feat(accounts): opaque API keys resolved by hash, and a working key UI

[alukach]

Into #570's branch, as the in-place rework that PR's description will need once this merges; #570 then no longer depends on the proxy and can land before it. Implements ADR-013 as revised in source-cooperative/data.source.coop#234. Part of #491 and #548.

What

The key is opaque. sck_ + 32 random bytes in base64url, a fixed 47 characters matching ^sck_[A-Za-z0-9_-]{43}$, from randomBytes (not the modulo-biased legacy generator). Its SHA-256 is the record's partition key; a random public key_id is what the UI, revoke and expiry actions handle. The table's account_id index stands. Nothing signs the key and nothing calls the proxy at issue: proxy-keys.ts, the Ory ID-token round-trip and the compensating delete are gone, and getOryIdToken is private again.

The proxy asks by hash, as itself. POST /api/v1/service-account-keys/exchanges takes {key_hash} and answers {account_id, key_id, active: true} for a live key, or {active: false} for an unknown, revoked, expired or disabled one, with the reason only in the log under the forwarded x-request-id. Because the proxy does not yet know which account is calling, the route authenticates the proxy itself: verifyProxyAssertion, extracted from authenticateWithOidcToken and logging under its own operation name, verifies the assertion, and the route accepts only the sentinel subject urn:source:data-proxy. authenticateWithOidcToken refuses that subject outright, so it can never become a session, and the route never touches getApiSession, so no cookie reaches it. Last use is recorded best-effort: a throttled write must not refuse a live key.

The hash stays on the server. ServiceAccountKeyRecord is the stored row; publicKey strips key_hash before either page hands records to the client component. The Storybook mock returns a key of the real shape.

The key UI works end to end. Opening the issue dialog threw on #570's branch: its "Never" expiry option had an empty value, which Radix Select refuses. The select is now ApiKeyExpiryField, where "never" stands for the empty expires_in_days the actions read as no expiry. The smoke test renders its stories, and it skips the dialogs that contain it, which is how the crash went unnoticed. The show-once view prints the five variables a stock AWS SDK or the AWS CLI needs to use the key from a file, filled in for this environment's proxy, with the same role/FullAccess ARN form and region as the GitHub workflow snippet. setApiKeyExpiry had no caller: each live key now has a "Change expiry" dialog on the same field. The key list says to disable the account to stop every key at once, and the danger zone says what disabling does to credentials already issued and warns that enabling lets unrevoked keys sign in again.

Decisions to flag.

• revokeApiKey and setApiKeyExpiry find the key via listByAccount(...).find(key_id) rather than a third index: one query, and the ownership check comes free.
• The route answers active: false rather than 404 for an unknown hash, so the proxy's existing cache code applies and the client learns nothing it did not already hold.
• after() is not used for the last-use write; it is awaited in a try/catch because after() throws outside a request scope and would need mocking in every route test.
• The printed AWS_ROLE_ARN names FullAccess, like the GitHub snippet already on main; both work once Add the ReadOnly Role alongside FullAccess data.source.coop#221 serves the named roles. Until then, role/_default is the name the proxy accepts.

Stories

• IssueApiKeyDialog › Default: https://source-coop-ui-git-feat-opaque-api-keys-radiantearth.vercel.app/?path=/story/features-service-accounts-issueapikeydialog--default. Open it, pick "Never", and submit to reach the show-once view with the variables.
• ApiKeyExpiryField › Default, Never: https://source-coop-ui-git-feat-opaque-api-keys-radiantearth.vercel.app/?path=/story/features-service-accounts-apikeyexpiryfield--default
• ServiceAccountDetail › Default, with "Change expiry" on each live key: https://source-coop-ui-git-feat-opaque-api-keys-radiantearth.vercel.app/?path=/story/features-service-accounts-serviceaccountdetail--default
• ServiceAccountDetail › Disabled, with the re-enable warning: https://source-coop-ui-git-feat-opaque-api-keys-radiantearth.vercel.app/?path=/story/features-service-accounts-serviceaccountdetail--disabled
• ServiceAccountList › Default: https://source-coop-ui-git-feat-opaque-api-keys-radiantearth.vercel.app/?path=/story/features-service-accounts-serviceaccountlist--default

Captured from a static Storybook build with headless Chromium, with no page errors:

Testing

• npx jest on the touched suites, 5 suites and 204 tests, all passing:
  • service-account-keys.test.ts: stores only the hash and returns the key once; a different key each time; no-expiry; disabled account, non-manager, bad label and bad expiry refused before any write; revoke and expiry by key_id.
  • oidc.test.ts: the existing 16, plus: the sentinel never becomes a session even if an account had that id; verifyProxyAssertion returns claims without resolving anyone, and null for wrong issuer, wrong audience, expired, or no token.
  • The exchanges route: active with account and last-use written; still active when the write fails; revoked, expired, disabled and unknown all answer inactive without a write; 401 for any other subject or none; 400 for a non-hex body.
  • ApiKeyExpiryField.test.tsx: 90 days by default; an empty value for "never".
  • The stories smoke test, which now renders both ApiKeyExpiryField stories.
• npm run type-check, npm run lint (one require() warning in the new route test, the same pattern as the trusts route test), npm run build-storybook: clean.
• The screenshots above drive both dialogs in a real browser, including choosing "Never", which crashed before.

Docs and ADRs

data.source.coop: ADR-013 as revised in source-cooperative/data.source.coop#234 is what this implements. The route contract here ({key_hash} in, always-200 standing out, proxy-as-itself auth) is the seam that source-cooperative/data.source.coop#235 calls; source-cooperative/data.source.coop#235 is the proxy PR replacing source-cooperative/data.source.coop#233. The ADR-005 amendment in source-cooperative/data.source.coop#234 records the sentinel subject.

docs.source.coop: the unattended-workflow guide (source-cooperative/docs.source.coop#34) carries the setup the show-once view prints, and uses the same variables. Nothing existing describes keys.

🤖 Generated with Claude Code

https://claude.ai/code/session_01R1eiTse4416N6uTgAy4Ddd

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
source-coop-ui	Ready	Preview	Sep 29, 2026 9:37pm UTC
source-cooperative	Ready	Preview	Sep 29, 2026 9:37pm UTC

[claude]

Claude finished @alukach's task in 16s —— View job

---

✅ No blocking issues — safe to merge.

I read the exchanges route, the keys table client, the server actions, the oidc.ts changes and the key types. I did not run the tests or the type-check.

• Sentinel subject: it is checked in the route, and authenticateWithOidcToken refuses it, so a proxy assertion can't become a session.
• Hash handling: key_hash is validated as 64 hex characters, and publicKey strips it before it reaches client components.
• Race safety: set() is a conditional single-field update, so a concurrent revoke isn't overwritten by the last-use write.
• Caching: fetchByHash goes through cachedSend, which memoizes per request, so it can't serve a stale revocation across requests.

Simplify (ponytail)

• src/app/api/v1/service-account-keys/exchanges/route.ts, the reason ternary chain: it is only used for the log line. It's readable, so cutting it is optional. If you want less code, drop reason and log active: false alone. You lose the diagnostic detail the PR description promises, so I'd keep it.
• src/types/service-account-key.ts, API_KEY_PATTERN: only the test uses it. Fine as the documented scanner pattern; otherwise move it into the test.

Docs

• The description names ADR-013 and its revision in data.source.coop#234, the ADR-005 amendment for the sentinel subject, and the proxy PR [Bug] Unable to save account website with path #235. It also links docs.source.coop#34 and says nothing existing describes keys. That covers the requirement.

---

💰 Estimated review cost: $0.18 · 0m15s · 6 turns

[alukach]

Rebased onto #570's current branch and force-pushed. #570 had been rebased onto a newer main (picking up #574), so its two commits have new hashes and this branch still carried the old ones. This PR is now its own three commits on top of #570; its diff against #570 is identical to before, type-check is clean, and all 78 test suites pass.