feat(auth): migrate API keys to a SQLite credential registry

[cursor]

What

Closes the request-time os.getenv("CODEC_CARVER_API_KEYS") deviation tracked in #329 and #373.

• New stdlib credential_registry.py stores SHA-256 verifiers in api_credentials (3NF, two-word table names) with credential_events and runtime_policies.
• saas_web bootstraps from env once at startup, then verifies X-API-Key against the registry. Later env changes are ignored.
• Public binds (0.0.0.0) fail closed without keys. Empty-registry local use requires explicit loopback development mode.
• Rotation keeps the previous key valid until revoke. 401 responses use Cache-Control: no-store and never echo secrets.
• Doctoring: docs/doctoring/api-credential-registry.md (APA 7: NIST SP 800-63B-4, OWASP API2:2023, RFC 2104, NIST SP 800-218).

Why

Org rule: env is transport into a KV, never the runtime source. Comparing raw env strings on every request also first-match short-circuited and could raise on hostile headers.

Validation

• python3 -m unittest tests.test_credential_registry tests.test_saas_web.TestApiKeyAuth tests.test_job_store -q — 51 passed
• python3 -m unittest tests.test_saas_web -q — 98 passed with credential_registry.py and saas_web.py at 100% coverage
• python3 -m interrogate credential_registry.py saas_web.py — 100%
• python3 -m py_compile ... credential_registry.py — OK

Notes

• Do not mix this with Cloud Agent environment work (Add Cloud Agent dev environment config #426 / fix(env): fail-closed Cloud Agent start and hash-locked install #427) or drop-zone UI (fix(ui): restore drop-zone click-to-open after landmark-only rewrite #425 / fix(ui): overlay landmarks and click-or-drag copy on drop zones #428).
• usage still stores plaintext keys; that rename/migration is a follow-up after this lands.
• Do not self-approve. Request a human review before merge.

  

[cursor]

Stale comment

This is the #373-complete credential landing on this head (5a80b18). It adds the fail-closed public-bind policy, credential_events audit rows, and public listings that omit key_digest.

Do this next:

1. Keep #430 as the named credential head for issues #329/#373. Do not also merge #429 onto main — the two registries will collide (lifecycle_status vs lifecycle_state, lifespan vs on_event, verify return type).
2. After required checks finish, port two #429 ideas onto this head if they are still missing: FastAPI lifespan instead of deprecated on_event, and verify returning credential_id so usage_metering can stop storing plaintext.
3. GET /health belongs to #427, not this PR. Do not copy environment scripts here.
4. Do not self-approve. seonghobae is requested.

Local evidence on this head: 51 focused tests, 98 test_saas_web, 100% coverage on credential_registry.py + saas_web.py, interrogate 100%.

View PR

  

_{Sent by Cursor Automation: Fix Issues}

[cursor]

fe1023c on this head ports the two #429 ideas without taking #429's registry: verify_api_key returns credential_id, and FastAPI lifespan runs the named bootstrap.

Keep #430 as the named credential landing for #329/#373. Do not merge #429 — lifecycle_status vs lifecycle_state, on_event vs lifespan, and the verify return type will collide.

GET /health still belongs to #427. Do not copy environment scripts here.

The buyer gap this head left open is billing: usage still stored plaintext keys. The stacked follow-up on cursor/bc-9615934f-b2f0-472b-83ac-65cd089b0a4e-b5a7 rebinds that to usage_periods(credential_id, billing_period) and 429s a spent monthly plan. Merge this PR first, then that follow-up.

Do not self-approve. seonghobae is requested.

Local evidence on fe1023c plus the follow-up commits: 133 tests across credential, usage, and saas_web; 100% coverage on those three modules; interrogate 100%.

  

_{Sent by Cursor Automation: Fix Issues}