chore(sync): cascade SOCKET_API_TOKEN canonical + cross-repo-guard placeholder fixes from socket-repo-template

Author: jdalton

.claude/commands/setup-security-tools.md

@@ -8,11 +8,11 @@ Set up all Socket security tools for local development.
 
 ## Setup
 
-First, ask the user if they have a Socket API key for SFW enterprise features.
+First, ask the user if they have a Socket API token for SFW enterprise features.
 
 If they do:
 1. Ask them to provide it
-2. Write it to `.env.local` as `SOCKET_API_KEY=<their-key>` (create if needed)
+2. Write it to `.env.local` as `SOCKET_API_TOKEN=<their-token>` (create if needed). The deprecated `SOCKET_API_KEY` name is also accepted as an alias for one cycle, but new files should use `SOCKET_API_TOKEN`.
 3. Verify `.env.local` is in `.gitignore` — if not, add it and warn
 
 If they don't, proceed with SFW free mode.

.claude/hooks/cross-repo-guard/test/cross-repo-guard.test.mts

@@ -45,7 +45,7 @@ test('blocks ../socket-lib/ relative reference', async () => {
   assert.ok(stderr.includes('cross-repo-guard'))
 })
 
-test('blocks /Users/<name>/projects/<fleet-repo>/ absolute reference', async () => {
+test('blocks /Users/<user>/projects/<fleet-repo>/ absolute reference', async () => {
   const { code, stderr } = await runHook({
     tool_name: 'Write',
     tool_input: {

.claude/hooks/setup-security-tools/README.md

@@ -51,10 +51,13 @@ package manager — that transparently route commands through the
 firewall. You make sure that directory is at the front of your PATH;
 nothing else changes about how you use the tools.
 
-**Free vs. Enterprise**: if `SOCKET_API_KEY` is set in your env,
+**Free vs. Enterprise**: if `SOCKET_API_TOKEN` is set in your env,
 `.env`, or `.env.local`, the script installs the enterprise SFW
 build (which adds gem, bundler, nuget, and go support). Otherwise
 it installs the free build (npm, yarn, pnpm, pip, pip3, uv, cargo).
+The legacy name `SOCKET_API_KEY` is still recognized as an alias
+for one cycle so existing dev setups don't break in lockstep with
+the rename — pass either name and the bootstrap reads it.
 
 ## How to use
 
@@ -64,8 +67,9 @@ pnpm run setup
 
 (That's wired in `package.json` to `node .claude/hooks/setup-security-tools/index.mts`.)
 
-The script will detect whether you have a `SOCKET_API_KEY`, ask if
-unsure, then download whatever isn't already cached.
+The script will detect whether you have a `SOCKET_API_TOKEN` (or the
+deprecated `SOCKET_API_KEY` alias), ask if unsure, then download
+whatever isn't already cached.
 
 ## Where each tool lands
 

.git-hooks/_helpers.mts

@@ -52,8 +52,21 @@ export const FAKE_TOKEN_MARKER = 'socket-test-fake-token'
 // lib's rename PR lands.
 export const FAKE_TOKEN_LEGACY = 'socket-lib-test-fake-token'
 
-// Name of the env var used in shell examples; not a token value.
-export const SOCKET_SECURITY_ENV = 'SOCKET_SECURITY_API_KEY='
+// Env-var name prefixes used in shell examples / `.env.example` files.
+// Lines containing `<name>=` are documentation, not real tokens — drop
+// them from secret-scanner hits. SOCKET_API_TOKEN is the canonical
+// fleet name; the rest are legacy variants kept on the allowlist for
+// one cycle so existing `.env.example` files don't trip the gate
+// after the rebrand.
+export const SOCKET_TOKEN_ENV_NAMES: readonly string[] = [
+  'SOCKET_API_TOKEN=',
+  'SOCKET_API_KEY=',
+  'SOCKET_SECURITY_API_TOKEN=',
+  'SOCKET_SECURITY_API_KEY=',
+]
+// Back-compat alias — earlier callers imported this single-string
+// constant. New code should reach for SOCKET_TOKEN_ENV_NAMES.
+export const SOCKET_SECURITY_ENV = SOCKET_TOKEN_ENV_NAMES[0]!
 
 // ── Output ──────────────────────────────────────────────────────────
 //
@@ -79,7 +92,7 @@ const isAllowedApiKey = (line: string): boolean =>
   line.includes(ALLOWED_PUBLIC_KEY) ||
   line.includes(FAKE_TOKEN_MARKER) ||
   line.includes(FAKE_TOKEN_LEGACY) ||
-  line.includes(SOCKET_SECURITY_ENV) ||
+  SOCKET_TOKEN_ENV_NAMES.some(name => line.includes(name)) ||
   line.includes('.example')
 
 // Drops any line that matches an allowlist entry. Kept for callers
@@ -94,8 +107,20 @@ export const filterAllowedApiKeys = (lines: readonly string[]): string[] =>
 const PERSONAL_PATH_RE =
   /(\/Users\/[^/\s]+\/|\/home\/[^/\s]+\/|C:\\Users\\[^\\]+\\)/
 
-// Placeholders we ALLOW (documentation, not real leaks): any path
-// component wrapped in <...> or starting with $VAR / ${VAR}.
+// Placeholders we ALLOW (documentation, not real leaks). The scanner
+// accepts any path component wrapped in <...> or starting with $VAR /
+// ${VAR}, but for **canonical fleet style** use exactly these forms in
+// docs / tests / comments / error messages — pick the one matching the
+// path's platform:
+//
+//   POSIX  →  /Users/<user>/...     (macOS — `<user>` matches $USER)
+//   POSIX  →  /home/<user>/...      (Linux — same convention)
+//   Windows →  C:\Users\<USERNAME>\... (matches %USERNAME%)
+//
+// Don't drift to `<name>` / `<me>` / `<USER>` / `<u>` etc. The
+// `suggestPersonalPathReplacement` helper below auto-rewrites real
+// paths into these canonical shapes; mirror its output everywhere
+// else.
 const PERSONAL_PATH_PLACEHOLDER_RE =
   /(\/Users\/<[^>]*>\/|\/home\/<[^>]*>\/|C:\\Users\\<[^>]*>\\|\/Users\/\$\{?[A-Z_]+\}?\/|\/home\/\$\{?[A-Z_]+\}?\/)/
 

.git-hooks/pre-commit.mts

@@ -110,10 +110,11 @@ const main = (): number => {
         }
       }
       logger.info(
-        'Replace with `<user>` / `<USERNAME>` placeholders, an env var ' +
-          '(`$HOME`, `${USER}`), or — for documentation lines that need ' +
-          'the literal username form — append the marker ' +
-          '`# zizmor: documentation-placeholder`.',
+        'Replace with the canonical placeholder for the path platform: ' +
+          '`/Users/<user>/...` (macOS), `/home/<user>/...` (Linux), or ' +
+          '`C:\\Users\\<USERNAME>\\...` (Windows). Env vars also work ' +
+          '(`$HOME`, `${USER}`). For documentation lines that need the ' +
+          `literal form, append the marker \`${socketHookMarkerFor(file, 'personal-path')}\`.`,
       )
       errors++
     }
@@ -132,7 +133,9 @@ const main = (): number => {
     const hits = scanSocketApiKeys(text)
     if (hits.length > 0) {
       logger.warn(`Potential API key found in: ${file}`)
-      hits.slice(0, 3).forEach(h => logger.info(`${h.lineNumber}:${h.line.trim()}`))
+      hits
+        .slice(0, 3)
+        .forEach(h => logger.info(`${h.lineNumber}:${h.line.trim()}`))
       logger.info('If this is a real API key, DO NOT COMMIT IT.')
     }
   }
@@ -151,14 +154,18 @@ const main = (): number => {
     const aws = scanAwsKeys(text)
     if (aws.length > 0) {
       logger.fail(`Potential AWS credentials found in: ${file}`)
-      aws.slice(0, 3).forEach(h => logger.info(`${h.lineNumber}:${h.line.trim()}`))
+      aws
+        .slice(0, 3)
+        .forEach(h => logger.info(`${h.lineNumber}:${h.line.trim()}`))
       errors++
     }
 
     const gh = scanGitHubTokens(text)
     if (gh.length > 0) {
       logger.fail(`Potential GitHub token found in: ${file}`)
-      gh.slice(0, 3).forEach(h => logger.info(`${h.lineNumber}:${h.line.trim()}`))
+      gh.slice(0, 3).forEach(h =>
+        logger.info(`${h.lineNumber}:${h.line.trim()}`),
+      )
       errors++
     }
 

.git-hooks/pre-push.mts

@@ -174,7 +174,9 @@ const scanCommitMessages = (range: string): number => {
   }
   if (errors > 0) {
     logger.info('')
-    logger.info('These commits were likely created with --no-verify, bypassing the')
+    logger.info(
+      'These commits were likely created with --no-verify, bypassing the',
+    )
     logger.info('commit-msg hook that strips AI attribution.')
     logger.info('')
     const rangeBase = range.split('..')[0]
@@ -267,32 +269,39 @@ const scanFilesInRange = (range: string): number => {
         }
       }
       logger.info(
-        'Replace with `<user>` / `<USERNAME>` placeholders, an env var ' +
-          '(`$HOME`, `${USER}`), or — for documentation lines that need ' +
-          'the literal username form — append the marker ' +
-          '`# zizmor: documentation-placeholder`.',
+        'Replace with the canonical placeholder for the path platform: ' +
+          '`/Users/<user>/...` (macOS), `/home/<user>/...` (Linux), or ' +
+          '`C:\\Users\\<USERNAME>\\...` (Windows). Env vars also work ' +
+          '(`$HOME`, `${USER}`). For documentation lines that need the ' +
+          `literal form, append the marker \`${socketHookMarkerFor(file, 'personal-path')}\`.`,
       )
       errors++
     }
 
     const apiHits = scanSocketApiKeys(text)
     if (apiHits.length > 0) {
       logger.fail(`Real API key detected in: ${file}`)
-      apiHits.slice(0, 3).forEach(h => logger.info(`${h.lineNumber}:${h.line.trim()}`))
+      apiHits
+        .slice(0, 3)
+        .forEach(h => logger.info(`${h.lineNumber}:${h.line.trim()}`))
       errors++
     }
 
     const awsHits = scanAwsKeys(text)
     if (awsHits.length > 0) {
       logger.fail(`Potential AWS credentials found in: ${file}`)
-      awsHits.slice(0, 3).forEach(h => logger.info(`${h.lineNumber}:${h.line.trim()}`))
+      awsHits
+        .slice(0, 3)
+        .forEach(h => logger.info(`${h.lineNumber}:${h.line.trim()}`))
       errors++
     }
 
     const ghHits = scanGitHubTokens(text)
     if (ghHits.length > 0) {
       logger.fail(`Potential GitHub token found in: ${file}`)
-      ghHits.slice(0, 3).forEach(h => logger.info(`${h.lineNumber}:${h.line.trim()}`))
+      ghHits
+        .slice(0, 3)
+        .forEach(h => logger.info(`${h.lineNumber}:${h.line.trim()}`))
       errors++
     }
 

CLAUDE.md

@@ -160,6 +160,12 @@ Behavior the hook can't catch: redact `token` / `jwt` / `access_token` / `refres
 
 Full hook spec in [`.claude/hooks/token-guard/README.md`](.claude/hooks/token-guard/README.md).
 
+**Personal-path placeholders** — when a doc / test / comment needs to show an example user-home path, use the canonical platform-specific placeholder so the personal-paths scanner recognizes it as documentation: `/Users/<user>/...` (macOS), `/home/<user>/...` (Linux), `C:\Users\<USERNAME>\...` (Windows). Don't drift to `<name>` / `<me>` / `<USER>` / `<u>` etc. — the scanner accepts anything in `<...>` but a fleet-wide audit relies on the canonical strings being grep-able. Env vars (`$HOME`, `${USER}`, `%USERNAME%`) also satisfy the scanner.
+
+**Socket API token env var** — the canonical fleet name is `SOCKET_API_TOKEN`. The legacy names `SOCKET_API_KEY`, `SOCKET_SECURITY_API_TOKEN`, and `SOCKET_SECURITY_API_KEY` are accepted as aliases for one cycle (deprecation grace period) — bootstrap hooks read all four and normalize to `SOCKET_API_TOKEN` going forward. New `.env.example` files, docs, workflow inputs, and action env exports use `SOCKET_API_TOKEN`. Don't confuse with `SOCKET_CLI_API_TOKEN` (socket-cli's separate setting).
+
+**Cross-repo path references** — `../<fleet-repo>/...` (relative escape) and `/<abs-prefix>/projects/<fleet-repo>/...` (absolute sibling-clone) are both forbidden. Either form hardcodes a clone-layout assumption that breaks in CI / fresh clones / non-standard checkouts. Import via the published npm package (`@socketsecurity/lib/<subpath>`, `@socketsecurity/registry/<subpath>`) — every fleet repo is a real workspace dep. The `cross-repo-guard` PreToolUse hook blocks both forms at edit time; the git-side `scanCrossRepoPaths` gate catches commits/pushes too.
+
 ### Agents & skills
 
 - `/scanning-security` — AgentShield + zizmor audit