feat(security): hook-event auth secret + tunnel password guard

docs/security-architecture.md

@@ -124,7 +124,11 @@ loopback bind matters. The auth pipeline (`src/web/middleware/auth.ts`,
 `onRequest` hook) runs in this order:
 
 1. **Localhost‑only exemptions** (always first): `POST /api/hook-event` and the QR
- `/q/` short‑code path are exempt when `req.ip` is loopback (see §3).
+ `/q/` short‑code path are exempt when `req.ip` is loopback (see §3). While the
+ **managed tunnel is running**, the hook‑event exemption additionally requires
+ the per‑instance `X-Codeman-Hook-Secret` header (COD‑54); failed presentations
+ are rate‑limited in a **dedicated bucket** (separate from Basic‑Auth failures)
+ so misfiring hooks can never lock out the login path.
 2. **Session cookie** check — a valid `codeman_session` cookie short‑circuits to
  allow.
 3. **HTTP Basic** check — correct credentials short‑circuit to allow and clear
@@ -165,17 +169,29 @@ protection is unchanged.
 with `req.ip = 127.0.0.1`**. The localhost‑only exemptions then treat those
 requests as local:
 
-- `POST /api/hook-event` — auth‑exempt for loopback. Bounded impact: it is
+- `POST /api/hook-event` — auth‑exempt for loopback **only while no managed tunnel
+ is running**. When Codeman's own tunnel is up, the exemption requires the
+ per‑instance shared secret (`X-Codeman-Hook-Secret`, 256‑bit hex in
+ `~/.codeman/hook-secret`, mode 0600, COD‑54). Local hook commands read the
+ secret file at execution time (`$CODEMAN_HOOK_SECRET_FILE`, exported into every
+ managed session), so they keep working — tunneled internet traffic can't know
+ it. Even without the secret the impact is bounded: the route is
  `HookEventSchema`‑validated and requires a valid in‑memory `sessionId`; it can
  drive respawn signals, SSE broadcasts, push notifications, and transcript
- watching — **not** arbitrary terminal input or file reads. It is a
- session‑disruption / notification‑spoofing surface, not RCE.
+ watching — **not** arbitrary terminal input or file reads. ⚠️ The gate keys off
+ the **managed** tunnel — an externally run loopback proxy (your own
+ `cloudflared`, `tailscale serve`) is invisible to it, so the plain loopback
+ exemption still applies there (prefer `tailscale serve`, which authenticates at
+ the tailnet layer). Hook configs regenerated since COD‑54 always present the
+ header, so a future release can require the secret unconditionally.
 - QR `/q/` — still protected by its own short‑code brute‑force limiter
  (10 failures / 60s against a 62⁶ space).
 
 **Mitigation:** set `CODEMAN_PASSWORD` whenever a loopback‑connecting tunnel is
-up (it does not gate the hook‑event exemption, but it gates everything else and
-is the documented practice). Prefer `tailscale serve` (below), which authenticates
+up — it gates everything except the (secret‑gated) hook exemption and is the
+documented practice; since COD‑55 enabling the managed tunnel **refuses** to start
+without it unless `CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK=1` explicitly
+acknowledges the exposure. Prefer `tailscale serve` (below), which authenticates
 at the tailnet layer so untrusted clients never reach the loopback port at all.
 
 ### Host‑header & Origin allowlist (DNS‑rebinding & CSRF defense)

src/config/hook-secret.ts

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview Per-instance shared hook secret (COD-54).
+ *
+ * Claude Code hooks POST to `/api/hook-event` with no Basic-Auth credentials,
+ * relying on a localhost bypass in `web/middleware/auth.ts`. That bypass is safe
+ * for loopback-only deploys, but a `cloudflared --url http://127.0.0.1:port`
+ * tunnel proxies internet traffic INTO the loopback origin, so tunneled requests
+ * arrive with `req.ip === 127.0.0.1` and would otherwise pass the bypass and
+ * drive respawn/Ralph signals unauthenticated.
+ *
+ * To close that hole WITHOUT breaking the loop's own (credential-less) hook
+ * channel, every locally-generated hook command now presents a per-instance
+ * shared secret in the `X-Codeman-Hook-Secret` header. The middleware requires
+ * a matching secret for the bypass WHEN A TUNNEL IS RUNNING. Tunneled internet
+ * traffic can't know the secret; local hooks (which we generate) do.
+ *
+ * Storage mirrors the VAPID-key pattern in `push-store.ts`: a small file under
+ * the instance data dir (`dataPath('hook-secret')`), read-if-present /
+ * generate-if-missing, stable across restarts. 256 bits of hex.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { getDataDir, dataPath } from './instance.js';
+
+/** HTTP header local hooks use to present the shared secret. */
+export const HOOK_SECRET_HEADER = 'X-Codeman-Hook-Secret';
+
+/** Number of random bytes in the secret (256 bits → 64 hex chars). */
+const SECRET_BYTES = 32;
+
+let cachedSecret: string | null = null;
+
+/**
+ * Return this instance's hook secret, generating and persisting it on first use.
+ * Stable across restarts. Cached in-process after the first read.
+ */
+export function getHookSecret(): string {
+ if (cachedSecret) return cachedSecret;
+
+ const secretFile = dataPath('hook-secret');
+
+ if (existsSync(secretFile)) {
+ try {
+ const raw = readFileSync(secretFile, 'utf-8').trim();
+ if (raw) {
+ cachedSecret = raw;
+ return cachedSecret;
+ }
+ // Empty/whitespace file — fall through and regenerate.
+ } catch {
+ // Unreadable — fall through and regenerate.
+ }
+ }
+
+ const secret = randomBytes(SECRET_BYTES).toString('hex');
+ try {
+ mkdirSync(getDataDir(), { recursive: true });
+ // Owner-only perms — the secret gates the hook bypass.
+ writeFileSync(secretFile, secret, { mode: 0o600 });
+ } catch {
+ // Best-effort persistence: even if the write fails we still return a usable
+ // secret for this process so hooks/middleware agree within this run.
+ }
+ cachedSecret = secret;
+ return cachedSecret;
+}

src/hooks-config.ts

@@ -3,8 +3,9 @@
  *
  * Generates `.claude/settings.local.json` with hook definitions that POST
  * to Codeman's `/api/hook-event` endpoint when Claude Code fires hooks.
- * Uses `$CODEMAN_API_URL` and `$CODEMAN_SESSION_ID` env vars (set on every
- * managed session) so the config is static per case directory.
+ * Uses `$CODEMAN_API_URL`, `$CODEMAN_SESSION_ID`, and `$CODEMAN_HOOK_SECRET_FILE`
+ * env vars (set on every managed session) so the config is static per case
+ * directory and free of secret values.
  *
  * Key exports:
  * - `generateHooksConfig()` — returns hooks object for settings.local.json
@@ -41,11 +42,18 @@ import { HOOK_TIMEOUT_MS } from './config/auth-config.js';
 export function generateHooksConfig(): { hooks: Record<string, unknown[]> } {
  // Read Claude Code's stdin JSON and forward it as the data field.
  // Falls back to empty object if stdin is unavailable or malformed.
+ // COD-54: present the per-instance hook secret so the bypass keeps working while
+ // a tunnel is running. The value is read from the secret file AT EXECUTION TIME
+ // (path via $CODEMAN_HOOK_SECRET_FILE, set in every managed session's env), so it
+ // never lands in this config and rotation needs no respawn. If the var/file is
+ // missing the header is empty — the middleware then allows the request only on
+ // the plain loopback bypass (tunnel down), same as pre-secret behavior.
  const curlCmd = (event: HookEventType) =>
  `HOOK_DATA=$(cat 2>/dev/null || echo '{}'); ` +
  `printf '{"event":"${event}","sessionId":"%s","data":%s}' "$CODEMAN_SESSION_ID" "$HOOK_DATA" | ` +
  `curl -s -X POST "$CODEMAN_API_URL/api/hook-event" ` +
  `-H 'Content-Type: application/json' ` +
+ `-H "X-Codeman-Hook-Secret: $(cat "$CODEMAN_HOOK_SECRET_FILE" 2>/dev/null)" ` +
  `--data @- ` +
  `2>/dev/null || true`;
 

src/session-cli-builder.ts

@@ -11,6 +11,7 @@
 import type { ClaudeMode, EffortLevel } from './types.js';
 import { isEffortLevel } from './types.js';
 import { getAugmentedPath } from './utils/index.js';
+import { dataPath } from './config/instance.js';
 
 /**
  * Build Claude CLI permission flags based on the configured mode.
@@ -113,6 +114,8 @@ export function buildClaudeEnv(sessionId: string): Record<string, string | undef
  CODEMAN_MUX: '1',
  CODEMAN_SESSION_ID: sessionId,
  CODEMAN_API_URL: process.env.CODEMAN_API_URL || 'http://localhost:3000',
+ // Path only (not the secret value) — hook curls cat it at execution time (COD-54)
+ CODEMAN_HOOK_SECRET_FILE: dataPath('hook-secret'),
  };
 }
 
@@ -149,5 +152,7 @@ export function buildShellEnv(sessionId: string): Record<string, string | undefi
  CODEMAN_MUX: '1',
  CODEMAN_SESSION_ID: sessionId,
  CODEMAN_API_URL: process.env.CODEMAN_API_URL || 'http://localhost:3000',
+ // Path only (not the secret value) — hook curls cat it at execution time (COD-54)
+ CODEMAN_HOOK_SECRET_FILE: dataPath('hook-secret'),
  };
 }

src/tmux-manager.ts

@@ -857,6 +857,9 @@ export class TmuxManager extends EventEmitter implements TerminalMultiplexer {
  `export CODEMAN_SESSION_ID=${sessionId}`,
  `export CODEMAN_MUX_NAME=${muxName}`,
  `export CODEMAN_API_URL=${process.env.CODEMAN_API_URL || 'http://localhost:3000'}`,
+ // Path only (not the secret value): hook curl commands cat the file at
+ // execution time, so the COD-54 hook secret stays off the command line.
+ `export CODEMAN_HOOK_SECRET_FILE="${dataPath('hook-secret')}"`,
  ];
  // Only unset CLAUDECODE for Claude sessions
  if (mode === 'claude') exports.splice(2, 0, 'unset CLAUDECODE');

src/web/middleware/auth.ts

@@ -19,6 +19,7 @@ import {
  AUTH_FAILURE_MAX,
  AUTH_FAILURE_WINDOW_MS,
 } from '../../config/auth-config.js';
+import { getHookSecret, HOOK_SECRET_HEADER } from '../../config/hook-secret.js';
 
 // Auth session cookie name
 export const AUTH_COOKIE_NAME = 'codeman_session';
@@ -28,19 +29,32 @@ interface AuthState {
  authSessions: StaleExpirationMap<string, AuthSessionRecord> | null;
  authFailures: StaleExpirationMap<string, number> | null;
  qrAuthFailures: StaleExpirationMap<string, number> | null;
+ hookSecretFailures: StaleExpirationMap<string, number> | null;
 }
 
 /**
  * Register HTTP Basic Auth middleware with session cookies and rate limiting.
  * Only active when CODEMAN_PASSWORD is set.
  *
+ * @param getTunnelRunning - returns true while a managed tunnel is active. Used
+ * to gate the `/api/hook-event` localhost bypass: when a tunnel is up, tunneled
+ * internet traffic reaches the loopback origin with `req.ip === 127.0.0.1`, so
+ * the bypass additionally requires the shared hook secret (COD-54). When no
+ * tunnel is running (loopback-only, the normal case) the plain localhost bypass
+ * is kept so already-deployed (pre-secret) hooks + the loop channel keep working.
+ * Optional; defaults to "no tunnel" (unchanged behavior) when omitted.
  * @returns AuthState for lifecycle management (dispose on server stop)
  */
-export function registerAuthMiddleware(app: FastifyInstance, https: boolean): AuthState {
+export function registerAuthMiddleware(
+ app: FastifyInstance,
+ https: boolean,
+ getTunnelRunning: () => boolean = () => false
+): AuthState {
  const state: AuthState = {
  authSessions: null,
  authFailures: null,
  qrAuthFailures: null,
+ hookSecretFailures: null,
  };
 
  const authPassword = process.env.CODEMAN_PASSWORD;
@@ -67,24 +81,70 @@ export function registerAuthMiddleware(app: FastifyInstance, https: boolean): Au
  refreshOnGet: false,
  });
 
+ // Separate hook-secret failure counter (COD-54). MUST NOT share authFailures:
+ // legacy (pre-secret) hook configs fire constantly from 127.0.0.1, and counting
+ // their 401s against the shared bucket would 429 every cookie-less request from
+ // loopback — locking out the Basic-Auth login path (and, through a tunnel, every
+ // client, since tunneled traffic also arrives as 127.0.0.1).
+ state.hookSecretFailures = new StaleExpirationMap<string, number>({
+ ttlMs: AUTH_FAILURE_WINDOW_MS,
+ refreshOnGet: false,
+ });
+
  const authSessions = state.authSessions;
  const authFailures = state.authFailures;
+ const hookSecretFailures = state.hookSecretFailures;
 
- function sendAuthRateLimit(reply: FastifyReply, clientIp: string): void {
- const remainingMs = authFailures.getRemainingTtl(clientIp) ?? AUTH_FAILURE_WINDOW_MS;
+ function sendAuthRateLimit(
+ reply: FastifyReply,
+ clientIp: string,
+ failures: StaleExpirationMap<string, number> = authFailures
+ ): void {
+ const remainingMs = failures.getRemainingTtl(clientIp) ?? AUTH_FAILURE_WINDOW_MS;
  const retryAfterSeconds = Math.max(1, Math.ceil(remainingMs / 1000));
  reply.header('Retry-After', String(retryAfterSeconds));
  reply.code(429).send('Too Many Requests — try again later');
  }
 
  app.addHook('onRequest', (req, reply, done) => {
- // Hook events come from local Claude Code hooks (curl from localhost) — no auth headers available.
- // Safe: validated by HookEventSchema, only triggers broadcasts.
- // Security: restrict bypass to localhost only — prevents forged hook events via tunnel/LAN.
+ // Hook events come from local Claude Code hooks (curl from localhost) — no
+ // Basic-Auth credentials available. Validated downstream by HookEventSchema.
+ //
+ // COD-54: the bare localhost bypass is unsafe while a tunnel is running, because
+ // `cloudflared --url http://127.0.0.1:port` proxies internet traffic INTO the
+ // loopback origin, so a tunneled request arrives with req.ip === 127.0.0.1 and
+ // would pass. So:
+ // - tunnel running → bypass requires the shared hook secret (local hooks present
+ // it via the X-Codeman-Hook-Secret header; internet traffic can't know it),
+ // - tunnel not running (loopback-only, the normal case) → keep the plain
+ // localhost bypass so already-deployed (pre-secret) hooks + the loop's own
+ // credential-less hook channel keep working.
  if (req.url === '/api/hook-event' && req.method === 'POST') {
  const ip = req.ip;
- if (ip === '127.0.0.1' || ip === '::1' || ip === '::ffff:127.0.0.1') {
- done();
+ const isLoopback = ip === '127.0.0.1' || ip === '::1' || ip === '::ffff:127.0.0.1';
+ if (isLoopback) {
+ if (!getTunnelRunning()) {
+ // Loopback-only: unchanged behavior.
+ done();
+ return;
+ }
+ // Tunnel up: require the shared secret (constant-time compare).
+ const presented = Buffer.from(req.headers[HOOK_SECRET_HEADER.toLowerCase()]?.toString() ?? '');
+ const expected = Buffer.from(getHookSecret());
+ if (presented.length === expected.length && timingSafeEqual(presented, expected)) {
+ done();
+ return;
+ }
+ // Wrong/absent secret while tunneled — rate-limit per IP in the DEDICATED
+ // hook bucket (never authFailures, which would lock out the login path).
+ const hookIp = req.ip;
+ const hookFailures = hookSecretFailures.get(hookIp) ?? 0;
+ if (hookFailures >= AUTH_FAILURE_MAX) {
+ sendAuthRateLimit(reply, hookIp, hookSecretFailures);
+ return;
+ }
+ hookSecretFailures.set(hookIp, hookFailures + 1);
+ reply.code(401).send('Unauthorized: hook secret required');
  return;
  }
  // Non-localhost hook requests fall through to normal auth

src/web/network-auth-policy.ts

@@ -6,6 +6,16 @@ export function isExplicitlyEnabled(value: string | undefined): boolean {
  return value !== undefined && EXPLICIT_TRUE_VALUES.has(value.trim().toLowerCase());
 }
 
+/**
+ * True when unauthenticated network exposure is acceptable: either a password is
+ * set (auth active) or the operator explicitly acknowledged it. Used by the
+ * tunnel-enable guard (COD-55) to refuse publishing an unauthenticated public URL.
+ */
+export function isUnauthenticatedNetworkAcknowledged(allowFlag = false): boolean {
+ if (process.env.CODEMAN_PASSWORD) return true;
+ return allowFlag || isExplicitlyEnabled(process.env.CODEMAN_ALLOW_UNAUTHENTICATED_NETWORK);
+}
+
 export function isLoopbackBindHost(host: string): boolean {
  const normalized = host
  .trim()