[kafka pr-1 · 06/6] Slice 06 — Auth scopes (HITL)

[zsculac]

Stack position

LAST sub-PR for the kafka foundation (PR #390). Stacked on slice 05's PR #395.

main
 └── feat/kafka-walking-skeleton    (foundation rollup, PR #390 — draft)
      └── feat/kafka-list-revoke-verify    (slice 05, PR #395)
           └── feat/kafka-auth-scopes      ← THIS PR (HITL)

Base is slice 05's branch — diff is just slice 06's 6 commits / 19 files. Once slice 05 merges into the foundation, retarget this PR's base to feat/kafka-walking-skeleton.

⚠️ HITL — human inspection required before merge

This slice modifies packages/cli/src/auth.ts, the single source of truth for daemon auth across HTTP / MCP / SSE. SDD review passed all four stages (implementer → spec → code quality → polish), with one critical fix loop on the code-quality stage. The human MUST inspect the diff themselves before merging. Specifically verify:

• The exact backward-compat code path: legacy lines (no TAB) → * scope set → grants all routes
• The atomic-write implementation: race window between rename and crash
• The mint response surface: full token returned ONCE; never in list responses
• Per-route scope strings match the PRD table exactly: kafka:endpoint:write for write routes, kafka:endpoint:read for read routes

What slice 06 adds

Per-token scopes via extended bearer-token file format. Implements ADR-0003.

• New token-store deep module extracted from auth.ts — pure parser/serializer for the token file format
• File format extended: <token><TAB><scopes-comma-separated>[<TAB><name>[<TAB><createdAt>]]. Legacy lines (no TAB) continue to grant full access (* scope) — non-negotiable
• New verifyTokenScope(token, requiredScope, store) helper with explicit fail-closed guard for empty/undefined required scope
• All 5 kafka endpoint routes gated by their scope per PRD table; 403 (not 401) on scope mismatch; no WWW-Authenticate header on 403
• Token mint flows: POST /api/auth/tokens (root-only), GET /api/auth/tokens (root-only, prefixes only), DELETE /api/auth/tokens/<prefix> (root-only)
• CLI: dkg auth mint-token / list-tokens / revoke-token (under existing dkg auth group)
• Concurrency-safe write to ~/.dkg/auth.token via shared writeFileAtomic helper (extended to accept { mode: 0o600 } so the temp file is created secure from the start, closing the umask window)
• Disk-first write order in mint/revoke: persist before mutating in-memory state, with try/catch rollback and 5xx on write failure

Test plan

• Backward compat: legacy token file (no TABs anywhere) grants full access on every kafka route — uses real on-disk legacy file, no mocks
• Unit: token-store parse/serialize/round-trip across legacy/scoped/mixed/malformed (30 cases)
• Unit: verifyTokenScope semantics including * grants all + fail-closed on empty/undefined required scope (6 cases)
• Integration: token scoped kafka:endpoint:read rejected (403) on POST /api/kafka/endpoint, accepted on GET — asserts no WWW-Authenticate on 403
• Integration: scoped token cannot mint another token via API (403); root token can; mint of * scope rejected; auth:tokens:* scope rejected
• Integration: mint returns full token ONCE; subsequent list calls strip via toPublicRecord; assertion: full token string never appears in list response body
• Persistence-failure injection: chmod 0o500 on dkg-home mid-test → 5xx returned, in-memory store unchanged, on-disk file byte-identical
• Concurrency: parallel writes (10 Promise.all mints) produce well-formed file, no truncation, all 10 records survive
• CLI smoke: full token printed exactly once on stdout (match(/.../g)?.length === 1 strict count); negative-control: secret never appears on stderr
• e2e: mint scoped token via CLI, register endpoint with it, attempt list → 403; cleanup via revoke
• Coverage ratchets unchanged: kafka package coverage unaffected (no kafka/ source touched); CLI uses package-level ratchet (not per-module), so the 1300+ LOC of new well-tested cli/ code can only raise it

SDD pipeline outcome

Stage	Verdict
Implementer	DONE
Spec compliance review	✅ SPEC COMPLIANT
Code quality review	❌ → ✅ APPROVED (after 1 critical + 4 important fixes in e5bd1512)
Polish review	📝 SUGGESTIONS (3 mechanical wins applied in 294b6182)

Critical fix in the loop: writeFileAtomic originally created the temp file with default umask (0o644 typically), opening a brief permissions window on ~/.dkg/auth.token between rename and the explicit chmod. Fixed at the helper level so slice 07 inherits the secure default by construction.

Pre-existing footguns surfaced (not fixed in this slice)

• dkg auth show (pre-slice-06) prints all token strings including new scoped tokens. Description unchanged.
• dkg auth rotate (pre-slice-06) silently overwrites scoped tokens. Description prose updated to warn operators (this slice); behavior unchanged. Full fix is slice 07 cleanup territory.
• Multi-process write races: slice 06 routes all admin via the daemon's in-process mutex (CLI commands hit the API). Cross-daemon-process races aren't covered but aren't a normal config.

Risk notes

Highest-risk slice in the foundation:

• auth.ts is daemon-wide; mistakes silently lock or unlock entire deployments
• Concurrency-safe write must be correct under realistic contention
• Token leakage paths (logs, list responses, error responses) are the worst possible bug

Related

• ADR-0003 (auth scopes via extended bearer-token file)
• Issue: .scratch/kafka-registry/issues/06-auth-scopes.md

[zsculac]

Codex round 2 — known limitations (deferred for v1)

Codex flagged two prefix-collision edge cases that are deliberately deferred to a future slice:

• packages/cli/src/auth.ts — config-token dedupe uses full-token equality but the store is prefix-keyed. A config token sharing an 8-char prefix with a file token would silently overwrite it in memory.
• packages/cli/src/daemon/routes/auth.ts — mint does not check prefix uniqueness before setTokenRecord(). A prefix collision would silently revoke the older token.

Why deferred: prefix is 8 chars of base64url (64⁸ ≈ 281 trillion combinations). The birthday-problem collision threshold is ~75M tokens for >1% probability. Real deployments are nowhere near this, and triggering the collision deliberately requires operator-root control of token generation (i.e. the attacker already has the keys).

Future fix (one-liner): bump prefix length to 16 chars in tokenPrefix() — drops collision probability to ~1 in 10²⁸. The full collision-detect-and-retry path is unnecessary.

Tracking for slice 07 cleanup.