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

Author: jdalton

.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: {

.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++
     }

.git-hooks/pre-push.mts

@@ -269,10 +269,11 @@ 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++
     }

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