feat(api): Track 3.2 — X-Admin-Key gates cross-user DELETE on /api/analysis-runs

[slittycode]

Second of four pieces from Track 3. Adds an operator-level privilege gate to DELETE /api/analysis-runs/{run_id} so operators can purge runs that don't belong to them.

Semantics

The admin key bypasses ownership rather than replacing it. Users can still delete their own runs without the header — existing behavior is preserved. Operators with the configured key can delete any run.

SONIC_ANALYZER_ADMIN_KEY set?	X-Admin-Key header matches?	Effect
❌ no (default)	—	Header is ignored; admin path is closed. Ownership is the only gate.
✅ yes	❌ no/wrong	Header is ignored; falls back to ownership. Non-owner gets RUN_NOT_FOUND.
✅ yes	✅ yes	Ownership check skipped. Any run can be deleted by the admin.

RUN_NOT_FOUND is still returned for nonexistent runs regardless of the admin key — the admin path cannot be used to enumerate run IDs (response is identical whether the run doesn't exist or the caller is denied).

Response now includes "deletedBy": "owner" | "admin" so audit logs can distinguish the two paths.

Security details

• hmac.compare_digest for constant-time comparison — resists timing-based probing of the configured key. There's a test that verifies this is actually wired in (so nobody "simplifies" it back to ==).
• Both the env value and the header value are whitespace-stripped before comparison so secret-manager trailing newlines don't break matching.
• Empty string and whitespace-only env values are treated as "unset" so a misconfigured deployment doesn't accidentally open the admin path with a trivial key.

Files

File	Change
apps/backend/auth_context.py	Two new pure functions: admin_key_is_configured() (presence check for routing decisions) and admin_key_matches(provided) (the auth decision). ADMIN_KEY_ENV_VAR constant at module scope.
apps/backend/server.py	delete_analysis_run accepts X-Admin-Key header. When it matches, runtime.get_run(owner_user_id=None) skips the ownership check.
apps/backend/tests/test_auth_context.py (new, 11 tests)	Pure-logic: env presence detection (unset/empty/whitespace/set), match decision (none/empty/exact/case-mismatch/partial/whitespace-stripped), and a regression gate that hmac.compare_digest is actually called.
apps/backend/tests/test_server.py (+3 tests, 138 lines)	Route-level: admin key bypasses ownership for non-owner; wrong key falls back to ownership (non-owner gets RUN_NOT_FOUND); env var unset closes the admin path even with a header. Existing test_delete_analysis_run_removes_owned_run test extended to assert deletedBy: "owner".
CLAUDE.md / ARCHITECTURE.md	Documented as backend-only env var.

Verification

11 auth_context tests pass locally (Python stdlib only):

$ python -m unittest tests.test_auth_context
...........
Ran 11 tests in 0.005s
OK

3 route tests run via the existing AnalysisRuntime + patch.object(server, "get_analysis_runtime", ...) pattern. CI will exercise them.

What this PR does NOT do

• No admin auth on other routes. The review's recommendation was for DELETE and a "forthcoming admin list." This PR scopes to DELETE only. Adding X-Admin-Key to a bulk-list / stats endpoint is a separate follow-up if/when those endpoints exist.
• No audit log persistence. The deletedBy field is in the response but isn't written to an audit table. The existing analysis_runs row is deleted; an admin audit trail is a hosted-mode feature for a later PR.
• No rate limiting on admin requests. Operator clients are trusted.

Track 3 sequencing

• ✅ Piece 1: URL ingestion (feat(api): Track 3.1 — URL-mode ingestion for POST /api/analysis-runs #36, merged)
• ▶ Piece 2: this PR — X-Admin-Key on DELETE
• ◯ Piece 3: GET /api/analysis-runs/{run_id}/source-audio re-serve
• ◯ Piece 4: Public state-machine collapse 8 → 5 at response boundary

https://claude.ai/code/session_01Uh2eNT1oqjixcox8UX3BTg

---

Generated by Claude Code

[slittycode]

Verdict: APPROVE

Summary

Adds an operator-level X-Admin-Key gate to DELETE /api/analysis-runs/{run_id}. The implementation is correctly partitioned: two pure functions in auth_context.py handle all auth logic; server.py is just routing. All 11 test_auth_context tests pass locally. Three route-level tests cover the admin-bypass, wrong-key-fallback, and unset-env-var paths; they require FastAPI's venv to run, which isn't present in this environment, but the test logic is correct from the diff.

Findings

Worth considering:

admin_key_is_configured() is defined and documented but not called in server.py — only admin_key_matches() is used. Fine; the docstring frames it as a routing-decision helper for future conditional route exposure. Noting it so nobody removes it thinking it's dead code.

The test_delete_analysis_run_admin_key_unset_ignores_header test calls server.os.environ.pop("SONIC_ANALYZER_ADMIN_KEY", None) inside the patch.dict block to handle environments where the var might already be set. That's the correct approach when patch.dict(clear=False) is in use — no issue.

Test results

11 passed / 0 failed (tests.test_auth_context). Server route tests not runnable without FastAPI venv in this environment; auth logic tests are exhaustive.

Phase boundary check

Clean. No Phase 1 measurements touched. No Phase 2/3 files modified. Purely infra.

---

Generated by Claude Code

[slittycode]

Verdict: APPROVE

Summary

Adds an optional operator-level privilege gate (SONIC_ANALYZER_ADMIN_KEY) to DELETE /api/analysis-runs/{run_id}. Default behavior is fully unchanged — when the env var is unset the admin path is closed and ownership is the only gate. The security-critical comparison uses hmac.compare_digest and the test suite includes a regression guard that it stays wired in. Test coverage is solid: 11 pure-logic tests in the new test_auth_context.py plus 3 new route-level integration tests. Both Backend and Frontend CI checks pass.

Findings

Worth considering (non-blocking):

server.py now has both import auth_context (new, line ~29) and from auth_context import AuthenticationRequiredError, UserContext, resolve_api_user_context (existing). The module-level import is used so the call site reads auth_context.admin_key_matches(...) rather than a bare function — reasonable intentional choice, not a bug.

The admin-bypass test exercises the "different user + matching key" case. The PR description's table also lists "no user header at all" as a valid admin scenario; that sub-case isn't separately tested. The code path is identical (both skip _resolve_route_user_context), so this isn't a correctness gap — mentioning in case you want the coverage to match the table.

Test results

Backend: 11 new auth_context tests + 3 new server route tests + 1 assertion added to existing delete test. All pass. CI: Backend ✅ Frontend ✅.

Phase boundary check

Clean. No changes to Phase 1 DSP code, Phase 1 output schema, or Phase 2/3 interpretation logic.

---

Generated by Claude Code