feat(sts): exchange API keys at /.sts and sign them at /.keys

[alukach]

⛔ Blocked by developmentseed/multistore#146 and developmentseed/multistore#147 — this branch builds against them through [patch.crates-io] pinned to their branch, which comes out when the release carrying them lands — and by source-cooperative/source.coop#570, which adds the exchanges route this calls. The proxy half of source-cooperative/source.coop#548; closes #231. Part of source-cooperative/source.coop#491.

What I'm changing

API keys per ADR-013, as amended by ADR-014 (#232): a long-lived JWT the proxy signs for a service account, handed out as sck_ + JWT, exchanged at /.sts for credentials like any ID token — with a revocation check.

• POST /.keys signs a key. source.coop calls it as whoever is issuing the key, with their Ory ID token as Authorization: Bearer and {"account_id", "jti", "expires_at"} (RFC 3339 or null), once it has written the record. The proxy verifies the token exactly as /.sts does — same issuer, same audiences — then asks the Source API whether that caller manages the account, and only then signs. A token alone mints nothing. Answers {"key": "sck_…"}. Like /.sts, it is 501 until AUTH_AUDIENCE is set.
• /.sts exchanges a key in process. A WebIdentityToken starting sck_ is verified against the proxy's own signing key — current and, during a rotation, previous — rather than by the STS route, because a Worker cannot fetch its own JWKS (Cloudflare refuses the self-request, error 1042). type must be api_key, so an outbound federation assertion signed under the same key is not a key. Then the step ADR-013 adds: POST /api/v1/service-account-keys/{jti}/exchanges, as the key's own account, cached 60s like the permissions lookup; active: false, 404, or an API failure all deny. Credentials are minted and sealed exactly as the STS route does, same duration floor and cap.
• One answer for every refusal. Bad signature, expired, revoked, unknown: the client sees InvalidIdentityToken "API key was not accepted" and an x-request-id; the reason is in the log under that id. A wrong RoleArn is still reported as such — it is about the request, not the key.
• The _default role now says subject_conditions: ["*"] outright, and allow_missing_exp_from: []: both fields multistore#146 requires. The API-key role is separate — trusts the proxy issuer, requires aud = the proxy issuer, exempts it from exp — and is only reachable through the sck_ path, so a bare proxy-signed JWT at /.sts is still an untrusted issuer.

Decisions to flag

• Keys carry aud = the proxy issuer. ADR-013's example had no aud; [Bug] Remove ability to create restricted product in AWS Opendata program bucket #146 makes an audience-less token unexchangeable, and the proxy is the only party meant to accept a key. ADR-013 is amended here to say so (one claim, one bullet; docs(adr): ADR-014 service accounts; amend ADR-010 and ADR-013 #232 touches other sections of the same file).
• No latency floor. Accept API-key JWTs at /.sts: jti revocation check, latency floor, and key minting #231 asks for one so a local rejection is not measurably faster than a lookup. Expiry is readable in the token by whoever holds it, so a fast "expired" reveals nothing the holder lacks; revoked and unknown both traverse the same cached lookup. Skipped; add one if a rejection path is ever added that short-circuits before the lookup on something not already in the token.
• The manager check reuses GET /api/v1/accounts/{id}/integrations as the oracle: it is gated on canManageServiceAccount and 401/403s otherwise; the list it returns is discarded. Not cached. A purpose-built route would read better; this needs no source.coop change.
• sck_ prefix — the same decision flagged in feat(accounts): issue, revoke and expire opaque API keys for service accounts source.coop#570; Register the API-key marker with secret scanners and expose self-revoke source.coop#561 registers the sck_eyJ[\w-]+\.[\w-]+\.[\w-]+ pattern.

How I did it

• src/keys.rs — new, wasm-free: api_key_role, api_key_claims/mint_api_key (sign_claims from multistore#147), strip_api_key, own_jwks (the signers as a JwksResponse, via the JWKS builder discovery already uses), verify_api_key/verify_with_any_key (tries each key in the set; a set holds one or two), credentials_for.
• src/lib.rs — /.keys joins the special paths and the fail-closed 501; mint_key/try_mint_key and api_key_exchange/exchange_api_key run after ApiAuth is built and before the router; finish adds CORS and the request id to a pre-gateway response.
• src/sts.rs — default_role factored out of new so /.keys verifies with the same trust; the two new RoleConfig fields.
• src/source_api/cache.rs — cached_fetch takes the method and stores nothing for a TTL of 0; get_or_fetch_key_standing (POST, 60s) and assert_caller_manages_account (GET, uncached).
• Cargo.toml — chrono (RFC 3339 and the clock), rsa/rand as dev-deps for the test key, the keys test target, and the [patch.crates-io] block with a comment saying when to drop it.
• adrs/013-api-keys.md — aud in the example claims and its bullet.
• README.md — the two endpoints in the operations table and an "API Keys" section under OIDC Provider.

How to test it

• cargo test — all suites; tests/keys.rs covers: claims shape (iss, aud, sub, jti, type, exp only when given); past expiry, unparsable expiry and blank fields refused at mint; only sck_-prefixed tokens are keys; a minted key verifies to its record; an expired key is refused; a key signed before a rotation verifies while the previous key is served and not once it is dropped; a federation assertion under the same key is not a key; another issuer's key is refused; credentials unseal to the account and are floored at 900s.
• cargo clippy --target wasm32-unknown-unknown -- -D warnings and cargo check --target wasm32-unknown-unknown — clean.
• End to end, once source.coop#570 is deployed against a preview of this: issue a key from a service account's card, save it to a file, then

  AWS_WEB_IDENTITY_TOKEN_FILE=./key AWS_ROLE_ARN=arn:aws:iam::000000000000:role/_default \
    aws --endpoint-url https://<preview> s3 ls s3://<owner>/<product>/

  revoke the key in source.coop and see the next exchange refused within 60s; a key issued with no expiry keeps working until revoked. Not run here: it needs #570 deployed.

PR Checklist

• This PR has no breaking changes. (_default behaves as before; the [patch] is a build-time pin.)
• I have updated or added new tests to cover the changes in this PR.
• This PR affects the Source Cooperative Frontend & API, and I have opened issue/PR feat(accounts): issue, revoke and expire opaque API keys for service accounts source.coop#570 to track the change.

Related Issues

#231, #232 (ADR-014), source-cooperative/source.coop#548, source-cooperative/source.coop#570, source-cooperative/source.coop#561, developmentseed/multistore#146, developmentseed/multistore#147.

🤖 Generated with Claude Code

https://claude.ai/code/session_01REZWKgQy2PDETn6j9YpM4z

[claude]

Claude finished @alukach's task in 3m 24s —— View job

---

Claude finished reviewing

• Gather context (diff, changed files, CLAUDE.md)
• Review correctness/security/best-practices
• Apply ponytail-review pass for over-engineering
• Post final review

---

✅ No blocking issues — safe to merge.

Reviewed src/keys.rs, the /.keys and /.sts wiring in src/lib.rs, the cache-layer changes in src/source_api/cache.rs, and the _default/API-key role split in src/sts.rs, against origin/main. Traced the full mint → exchange → credential-sealing path and the trust boundaries at each hop (issuer/audience checks, the manager oracle, the key-standing oracle, the generic-refusal mapping). Didn't find a correctness or security bug — the implementation matches the PR description closely and the tests in tests/keys.rs exercise the interesting edge cases (rotation, expiry, wrong issuer, federation-vs-key confusion, credential floor/cap).

A couple of non-blocking observations:

• src/source_api/cache.rs:220 — assert_caller_manages_account goes through the same cached_fetch used for product/permissions lookups, so a 404 (unknown account_id) surfaces to the /.keys caller as ProxyError::BucketNotFound("not found"). Harmless (it's an internal API only source.coop calls, and the status code is still right), but the error text is bucket-flavored for a request that has nothing to do with buckets — worth a glance if that message ever reaches a human.
• src/lib.rs:596 (exchange_api_key) — every error from the key-standing lookup, including a genuine Source API outage (5xx/network failure → ProxyError::Internal), collapses to the same InvalidIdentityToken "API key was not accepted" as a revoked/unknown key. That's the documented "one answer for every refusal" tradeoff, so presumably intentional, but it does mean an upstream outage looks identical to a bad key from the outside — flagging in case that wasn't the intent for the outage case specifically (vs. the key-validity cases it's clearly meant for).

Simplify (ponytail)

Nothing significant. src/keys.rs:88 (own_jwks) builds the JWKS by reusing the existing discovery-endpoint builder (jwks_json) and round-tripping through a JSON string to get a typed JwksResponse back — a little indirect, but it's correctly reusing existing logic rather than re-deriving JWK encoding, so not flagging it as a fix, just noting it as the one slightly-roundabout spot in an otherwise lean diff.

---

💰 Estimated review cost: $0.57 · 3m24s · 19 turns

[github-actions]

🚀 Latest commit deployed to https://source-data-proxy-pr-233.source-coop.workers.dev

• Date: 2026-09-23T04:17:29Z
• Commit: 0e72cfd

[alukach]

Superseded by #235. This PR signed API keys with the proxy's own signing key; the design review on 2026-09-25 replaced that with opaque sck_ keys that the proxy resolves by hash at source.coop (ADR-013 revised in #234), which removes the signing key, and with it the rotation problem: keys here verified against the current and one previous signer only, so the second rotation invalidated every key signed before the first.