fix(pod): send the token-mint secret over the pod's unix socket, never TCP - #9051

Problem / Motivation

mint_token reads the pod's .local_secret and sends it in an X-Local-Secret header over loopback TCP to http://127.0.0.1:<port>/api/token/local. Ownership is attested (OWNER_POD positive proof) and then a separate TCP connection carries the secret — a pod exiting inside that window frees the port for any local user to bind, and loopback TCP has no peer-credential API, so nothing on the wire can tell the squatter from the pod's gateway. #8218 closed exactly this class for the token-bearing request; mint_token is the residual its review disposition called out, and it could not ride #8218 because the server refuses the better transport: api_token_local gates on is_loopback(request.remote), and an AF_UNIX request has an empty request.remote, so the endpoint answers 403 to the transport that is strictly harder to reach than loopback TCP.

Why it matters

The captured value is the pod's per-gateway-start .local_secret. The impact is bounded exactly as the issue bounds it (capture-now / replay-before-any-gateway-restart, and #8218's socket transport means a fabricated token is only ever handed to the pod's own socket) — but pods carry ~2h TTLs and are torn down routinely, so the port-release window is a normal lifecycle event, not an anomaly. A secret-bearing request should not depend on winning a race against ordinary pod churn.

What changed (motivation → approach → change)

The secret now rides a connection whose peer the kernel vouches for, end to end. Three pieces, client / transport / server:

• Client (src/kiro_crew/pod/runtime.py): mint_token sends the mint over the pod's private AF_UNIX socket via unix_socket_urlopen(req, timeout=5, socket_path=pod_socket_path(cfg, name, port), verify_peer=...). That opener has no TCP handler, so "no fallback" is structural rather than a flag: a missing, stale, or refusing socket raises instead of handing the header to whatever answered — the error says explicitly that the call is not retried on 127.0.0.1:<port> and why. An HTTP 403 over the socket gets its own message that separates the two causes an operator can hit: a pod worktree whose gateway predates unix-socket admission on /api/token/local (remedy named in the error: update the pod's worktree, then restart it) versus a genuine secret rejection. The URL keeps the loopback host so the gateway's Host validation sees exactly what it saw on TCP; the socket path is derived, never caller-supplied. The OWNER_POD pre-check stays: it costs one process lookup and buys refusal messages that name why the pod cannot answer. On Windows the mint keeps the OWNER_POD-attested loopback transport: CPython there has no AF_UNIX, so the pod binds no socket, and the IS_WINDOWS branch returns before any unix-socket machinery is built — the strongest transport the platform offers, unchanged in behavior.
• Transport (src/kiro_crew/loopback_http.py, src/kiro_crew/pod/runtime.py): unix_socket_urlopen accepts a verify_peer connect-time callback that runs on the connected socket before any HTTP bytes. _attested_gateway_verifier builds that check from the recorded gateway pid vs the kernel's peer credentials (SO_PEERCRED on Linux, LOCAL_PEERPID on macOS), and re-proves the freshness-checked record on the connected socket itself — so a pid recycled between the record read and the connect cannot attest: the socket path lives in an owner-writable directory, so a confined same-UID process can unlink it and bind its own listener there — a fresh pid record proves the gateway is alive, not that it is the process answering the file. Deny-by-default: a mismatched peer, an unreadable peer, an unprovable pid record, and a record that cannot be re-proven at connect time all refuse before the request line goes out. Both send sites are covered (token mint and pod api — a rebind between the two sends would otherwise capture a live credential), and the stub-gateway fixture attests itself, so every pod-api test drives the real kernel check end to end.
• Server (src/kiro_crew/dashboard/handlers/core.py): api_token_local admits kernel-verified unix peers via _unix_peer_is_self — the shared token_auth._unix_request_socket discriminator (one definition of "arrived on the dashboard's unix socket" for the CSRF and token-auth layers) plus check_peer_is_self(sock) is PeerCredResult.MATCH, both imported at module level. Because this endpoint is token_auth-bypassed, admission is deny-by-default: MISMATCH (another principal reached our socket — precisely when the 0700 directory gate has failed and refusing matters most) and UNVERIFIABLE (no platform mechanism, failed syscall) are both refused, so a platform without peer credentials never silently widens the gate. This admits a transport, never a caller: the X-Local-Secret check downstream is unchanged on both transports.
• Deliberately unchanged: health() / probe stay on TCP — they carry no credential, and port_owner() already reports who replied. The four sibling X-Local-Secret sends against the MAIN gateway in cli_server.py also stay on loopback TCP: the main gateway is out of this PR's scope (pod mint only), and migrating those sites onto the gateway's unix socket is tracked in Send X-Local-Secret over the main gateway's unix socket in cli_server.py (deferred from PR #9051) #11091. The docker guide (docs/guides/docker.md) local-bootstrap paragraph describes the two admitted transports.

flowchart LR
  subgraph Before
    m1[mint_token] -->|X-Local-Secret over loopback TCP| p1[whoever holds :port]
  end
  subgraph After
    m2[mint_token] -->|X-Local-Secret over AF_UNIX| v2{peer pid == attested gateway?}
    v2 -->|MATCH| g2[pod's gateway]
    v2 -->|MISMATCH / UNVERIFIABLE| r2[refused, zero bytes sent]
  end
  classDef added fill:#DCFCE7,stroke:#16A34A;
  classDef removed fill:#FEE2E2,stroke:#DC2626,stroke-dasharray:4 3;
  classDef ctx fill:#E0F2FE,stroke:#0284C7;
  class m2,v2,r2 added
  class p1 removed
  class m1,g2 ctx

🟩 added · 🟥 removed · 🟦 unchanged

The secret leaves the process only after the kernel names the listener, so a squatter on the port — or on the socket file — receives nothing.

Tests

Server half (test/test_dashboard_handlers_core_coverage.py, TestLocalToken):

• test_unix_peer_match_with_valid_secret_issues_a_token — kernel MATCH + valid secret mints (the benign path is admitted, not just attacks refused).
• test_unix_peer_still_needs_the_secret — admitted transport, wrong secret → 403 invalid secret (not loopback only), pinning that admission never weakens the secret check.
• test_unix_peer_uid_mismatch_is_refused_even_with_the_secret — kernel says another principal: refused with the audit log recording non-loopback.
• test_unix_peer_unverifiable_is_refused_even_with_the_secret — no peer-credential mechanism: refused (deny-by-default pin).

Client half (test/test_pod.py):

• test_mint_token_sends_the_secret_only_over_the_pod_socket — asserts the TCP opener list stays empty, the unix opener got pod_socket_path(...), and the X-Local-Secret header rode the socket.
• test_mint_token_uses_attested_loopback_on_windows — with IS_WINDOWS true, the mint rides the loopback opener with the secret header, and building the unix socket path, the unix opener, or the peer verifier each fails the test outright.
• TestMintPeerVerification — a live in-process listener answering the pod's derived socket path with a mismatched attested pid observes ZERO bytes (the refusal precedes the request line), and the same listener attested as this process completes the mint through the real peer-credential read — no monkeypatch on the kernel path. test_verifier_refuses_when_attestation_expires_before_connect pins the connect-time re-proof: a record valid when the verifier is built but gone at connect time refuses even when the numeric peer pid matches.
• test_mint_token_reads_secret_and_posts rides the socket transport; test_mint_token_refuses_a_foreign_port_holder passes unchanged on both sides (control: the pre-check's refusal behavior is untouched).

Fixture half (test/test_pod_api.py): the stub gateway records its own pid with a live start identity, so pod-api tests exercise the verification path rather than bypassing it.

Targeted files: 696 passed / 1 skipped. Scoped backend suite (721 related targets): green apart from 15 host-environment failures that reproduce byte-identically on pristine origin/main (doctor probes, a dev-fleet path assertion, member-context routing). mypy clean over 1539 files; flake8 / isort / black-baseline / comment-history / docs-lint all pass.

Manual verification

N/A — unit coverage sufficient: the two new seams are unit-pinned with the kernel verdict and transports faked, and both underlying primitives carry their own pre-existing real-socket suites (test_pod_api.py binds a live AF_UNIX server against unix_socket_urlopen; test_socketsec*.py covers check_peer_is_self including real-socket SO_PEERCRED). CI exercises the composed path.

Screenshots / video

N/A — backend transport and error-message change only; no user-visible dashboard or app state changes.

Related Issues

Fixes #8552

Pattern harvest

Rule candidate: review-prompt
Pattern: "attest-then-send across separate connections is a TOCTOU on the transport — a credential-bearing request must ride a connection whose peer is verified at send time (unix socket + peer creds), not a port whose owner was checked moments earlier". Flag any request that sends a secret over plain loopback TCP when a peer-verified unix transport exists for the same server.

Checklist

• At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)
• Existing tests pass and new tests added for new functionality
• Self-review completed; code follows project style guidelines
• Documentation updated (if applicable)
• No secrets, credentials, or internal references in the diff