From 8b4a8ccdbd2bc62bb0e8810620b4b22447a2e154 Mon Sep 17 00:00:00 2001 From: Sef Kloninger Date: Fri, 13 Nov 2026 14:47:12 -0800 Subject: [PATCH 01/34] docs(design): add the API keys design doc A working design for API keys on the platform proxy (#142): the key format and header, storage, per-key limits, the proxy check, and the three phases. Still being revised. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf --- docs/design/api-keys.md | 223 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 223 insertions(+) create mode 100644 docs/design/api-keys.md diff --git a/docs/design/api-keys.md b/docs/design/api-keys.md new file mode 100644 index 0000000..bcbb924 --- /dev/null +++ b/docs/design/api-keys.md @@ -0,0 +1,223 @@ +# API Keys for the Platform Proxy + +Initial draft by Claude Code. Revised by Sef Kloninger, + +[Issue #142][issue] + +Last Update: Nov 13, 2026 + +## Summary + +This feature is to add per-user access to the Development Finance Observatory backends. This will enable + +- Metered and ACL'ed access +- Cost and operational controls +- Enable potential to recoup costs from for-profits that wants programmatic access to our data. + +We intend to still have a free / open tier for ease of use and for crawlers. But more expensive and frequent access will need to come via an API key. + +The proxy fronts the public Search, Datasets and Graph APIs (`/api/v1/*`) and the MCP servers (`/mcp`). Today it knows callers only by address. + +Initial requirements: + +- Anonymous access will stays open up to a limit. Our goal is to manage usage and enable rate limits, not wholesale API gating. +- Each key carries its own rate limit. +- Some MCP features may later require sign-in. That is separate from keys and out of scope here. + +We'll take a phased approach. Initially we'll prove the concept with hand-provisioned keys and limited features. Once proven this works in production, follow-on work will enable more features, self-service provisioning, and admin interfaces to adjust access and limits. + +## How It Works Today + +Every public API and MCP call passes through one function in the website, `forward()` in `src/lib/proxy/forward.ts`. That is the single place a key needs to be checked. + +- **Rate limit.** `forward()` counts each call against the client's address in a fixed window: 120 calls a minute on `/api/*`, 300 on `/mcp`. The counters live in the website's Postgres (`limit_counter` table) and are shared by all instances. If the count fails or is slow, the call goes through uncounted. +- **No Redis.** The task description mentions turning a Redis limiter back on. There is no Redis code in the website now, so per-key limits need no Memorystore instance. +- **Edge limits.** Cloudflare WAF rules also rate-limit by address, in front of the site. +- **Caller identity.** The proxy names the caller to the backends as `x-dfo-caller: ip:`, a keyed hash of the address. dfo-apis counts its own allowances (shares, cards, pins) against that name. It trusts the header only beside a secret it shares with the website. +- **Backends are ahead of us in one place.** dfo-ai's caller module already documents `key:` and `user:` callers "from the website's edge". dfo-apis accepts only the `ip:` form. +- **MCP auth.** On `/mcp` the proxy attaches its own token for the harness when it holds one. Otherwise it passes the caller's `Authorization` header through. +- **Accounts.** The site has sign-in (Better Auth on its own Postgres) and an account menu, which is where self-service keys would attach. +- **Docs.** The API quickstart says the API accepts requests without a key. + +## Design + +A key is optional on every call. A call with a valid key is counted against the key at the key's limit, a call with no key is counted against the address as today, and a call with a bad key is refused. This is a proposal to react to, not a settled design. + +### The Key + +- Format: a recognisable prefix, an environment marker and random characters, for example `dfo_live_<32+ random chars>`. The prefix lets secret scanners and our own logs spot a leaked key. +- Sent as `Authorization: Bearer `, with `X-API-Key` accepted as an alias. See the next section. +- Shown once, when it is created. We store only a SHA-256 hash, so a database leak exposes no usable key. + +### Which Header Carries the Key + +The key is sent as `Authorization: Bearer dfo_…`. The proxy also accepts `X-API-Key` as an alias. A key is never accepted in the query string. + +- Bearer is what a programmatic partner reaches for first, and what MCP developer clients set most easily. +- The `dfo_` prefix lets the proxy tell our key from any other bearer token. +- The alias costs a few lines. It leaves `Authorization` free if `/mcp` later gains sign-in, where one call could carry a user's token and an application's key. +- A call that sends both headers with different keys is refused with a 400. +- The proxy strips the key before forwarding, so it never reaches a backend or its logs. + +**How other services do it** + +| Style | Who uses it | Notes | +| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `Authorization: Bearer ` | OpenAI, Stripe, GitHub, Cloudflare, SendGrid | The closest thing to a standard. Every HTTP client and SDK can set it, and proxies, loggers and secret scanners already treat it as sensitive | +| Custom header | Anthropic and AWS API Gateway (`x-api-key`), Google Cloud (`x-goog-api-key`), Azure (`Ocp-Apim-Subscription-Key`), Datadog (`DD-API-KEY`) | Common where `Authorization` is reserved for something else, usually a user's OAuth token or a signed request. The key names the application; `Authorization` names the user | +| Query parameter (`?api_key=`) | Google Maps, US Census, FRED, api.data.gov | Easy to try in a browser, which is why open-data APIs like it. It leaks into access logs, browser history and referrers, so newer APIs avoid it | + +Some services accept more than one: Stripe takes Bearer or HTTP Basic, and api.data.gov takes `X-Api-Key` or the query parameter. The split between the first two styles is mostly whether `Authorization` is already in use. A service with only keys uses Bearer. A service with keys and user tokens moves the key to a custom header. + +**Compatibility with MCP clients** + +The MCP specification defines authorization as OAuth, with the token sent as `Authorization: Bearer`. It has no API-key concept, so support for a key depends on the client. + +| Client type | Examples | Can it send our key? | +| ----------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Developer clients | Claude Code, Cursor, VS Code, SDK scripts | Yes. They let a user configure headers per server, so either header works | +| Hosted chat apps | Connector settings in Claude, ChatGPT and similar | Generally no. They are built around OAuth or no auth, and most give users no place to enter a header. This changes often and needs checking per client before we rely on it | + +So a key on `/mcp` serves programmatic and developer use. Chat-app users stay anonymous until `/mcp` has OAuth sign-in, which is the separate "MCP features that require logging in" work. + +**Compatibility with the proxy as built** + +| Path | What happens to `Authorization` today | Effect of a key there | +| -------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | +| `/api/v1/*` | Passed upstream, where dfo-apis does not use it to name callers | No conflict | +| `/mcp`, proxy holds the harness token (production) | Overwritten with the harness token | No conflict. The proxy reads the key first, then replaces the header as it does now | +| `/mcp`, proxy holds no token | The caller's value is passed through to the harness | The only conflict. The `dfo_` prefix resolves it: our key is consumed, any other token passes through | + +### Storage + +A new `api_key` table in the website's Postgres, beside the accounts and the limit counters. + +| Column | Purpose | +| ------------------------------------ | --------------------------------------------------------------------------- | +| id | Short public identifier, used in logs and as the caller name | +| key_hash | SHA-256 of the key, unique | +| prefix | First characters of the key, so its owner can recognise it in a list | +| label | What the key is for | +| user_id | Owning account. Empty for a manually provisioned key in Phase 1 | +| api_limit, mcp_limit | Calls per window on each surface. Empty means the default for keyed callers | +| created_at, revoked_at, last_used_at | Lifecycle | + +Postgres rather than Redis: the limiter already counts there, key volume is small, and it adds no new infrastructure. This can be changed later if we need something more scalable and performant at the cost of some additional dev and operational complexity. + +### Limits + +A key's limit is two plain numbers, one per surface. There are no named tiers. + +| Surface | Covers | Anonymous limit today | Column on the key | +| ------- | -------------------------------------- | ------------------------------ | ----------------- | +| API | `/api/v1/*`, `/openapi.json`, `/codes` | 120 calls a minute per address | `api_limit` | +| MCP | `/mcp` | 300 calls a minute per address | `mcp_limit` | + +- Each column is a nullable integer, in calls per window. +- Empty means the default for keyed callers, set per deployment in env (for example `RATE_LIMIT_API_KEYED` and `RATE_LIMIT_MCP_KEYED`). Most keys store nothing, and raising the default moves them all at once. +- A number overrides the default for that key. +- The window stays global at 60 seconds (`RATE_LIMIT_WINDOW_S`). There is no per-key window. + +This is all on the admin side. If we later want tiers, for single or bulk changes to keys, they can be added as a column or as a bulk update over these two numbers without changing what the numbers mean. + +Not covered by a key's limits: + +- The proxy's third allowance, `/api/download-pin` at 10 calls a minute, belongs to the site's download UI and is not part of the public API. +- The Studio's daily prompt allowance is for the site's own chat UI. +- dfo-apis keeps its own daily allowances per caller: 10 shares and 500 presentation cards, plus pins. A keyed caller gets these at the default values. Raising them for a partner would be a dfo-apis setting, not a column here. + +### The Proxy Check + +In `forward()`, before the rate limit: + +1. Read the key header. No header: carry on as an anonymous caller. +2. Hash the key and look it up, through a short in-process cache (about 60 seconds) so a keyed call adds no query in the common case. +3. Unknown or revoked key: answer 401 with a problem document. It does not fall back to anonymous, so a caller finds out their key is dead. +4. Valid key: count the call against `key:` at the key's limit, using the existing counter. + +A revoked key can keep working until the cache entry expires, so revocation takes up to a minute per instance. If the key lookup itself fails, the proposal is to treat the call as anonymous, in line with the limiter failing open. + +A keyed call is named to the backends as `x-dfo-caller: key:` instead of `ip:`. dfo-ai already expects that form. dfo-apis needs a small change to accept it, so its own allowances count per key and not per address. + +### Logs and Docs + +- The request log line carries the key caller, so usage per key can be counted in Cloud Logging. This is what Phase 3 needs to find high-volume callers. +- `/openapi.json` gains an optional security scheme, and the API and MCP docs explain keys. + +## Phases + +Three phases take keys from an optional test feature to the normal way heavy users reach the API. Anonymous access stays open throughout. + +### Phase 1: Validate + +**Goal:** Optional keys work end to end, for testing and the first partner + +**Who gets a key:** A few callers we choose + +**Provisioning:** Manual: an admin command creates and revokes keys + +**Limits:** Set per key by hand + +**Anonymous access:** Unchanged + +**Also needed:** Proxy check, `api_key` table, dfo-apis accepts `key:` callers, per-key usage in logs + +**Exit criteria:** The first partner runs on a key in production without incident, and per-key counts in the logs match what they report sending. + +### Phase 2: Provision + +**Goal:** Anyone can get a key; existing users have a path to move + +**Who gets a key:** Any signed-in account + +**Provisioning:** Self-service from the account menu: create, label, revoke, see last use + +**Limits:** Default tier for self-service keys; higher tiers granted by an operator + +**Anonymous access:** Unchanged; docs start recommending a key + +**Also needed:** Docs and quickstart, a transition notice for current users, usage shown to key owners + +**Exit criteria:** The transition notice has been out for an agreed period, and the callers who would be hit by lower anonymous limits have been identified and contacted where we can reach them. + +### Phase 3: Enforce + +**Goal:** High-volume users are on keys; anonymous limits can come down safely + +**Who gets a key:** Same, plus outreach to heavy anonymous callers + +**Provisioning:** Self-service, plus operator tools to raise or cut a key's limit + +**Limits:** Anonymous limits lowered in steps, key tiers settled + +**Anonymous access:** Open but lower + +**Also needed:** Usage reports by caller, a playbook for lowering a limit and rolling it back, edge rules that respect keys + +Phase 1 should avoid choices that Phase 2 has to undo. The table has an owner column from the start, and limits are stored per key in a form a tier can replace. + +## Work by Repository + +Most of the work is in the website. The Phase 1 pieces: + +| Where | Size | What | +| ---------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| website | Most of it | `api_key` table and migration; key check and per-key limit in `forward()`; admin command to create and revoke; key caller in the request log; OpenAPI security scheme; docs; tests beside the existing proxy tests | +| dfo-apis | Small | Accept `x-dfo-caller: key:` beside the website's shared secret, so allowances count per key. Today only `ip:` is accepted | +| dfo-ai | Little or none | Confirm a `key:` caller flows through `/mcp` to the MCP servers; add a test if none covers it | +| Cloudflare | Configuration | The WAF rate rules count by address. A keyed caller on a few addresses could hit them before reaching its key's limit | + +Order matters between the website and dfo-apis. dfo-apis refuses a caller form it does not recognize when it arrives with the shared secret, so the dfo-apis change has to be live before the website starts sending `key:` callers. + +## Open Questions + +The first three need an answer before Phase 1 code is written. + +- [ ] **Cloudflare.** Who owns the WAF rate rules, and can they exempt or raise the threshold for requests that carry a key header? An exemption on header presence alone could be abused with a fake key, so the rule may need a higher ceiling instead of none. +- [ ] **Does a key work on `/mcp` in Phase 1,** or only on `/api/v1/*`? The first partner's need is the API. +- [ ] **What is the default self-service limit in Phase 2,** relative to the anonymous limit? It has to be worth signing up for. +- [ ] **How do we reach current anonymous users** for the Phase 2 transition, given we know them only as hashed addresses? Candidates: docs, response headers, the SDK's `x-dfo-client` header. +- [ ] **Do keys expire,** and can an account hold more than one? +- [ ] **Does a key identify an account to the backends as well,** so a signed-in user's key and their site session share allowances? dfo-ai already names a `user:` caller form. + +[issue]: https://github.com/DevelopmentFinanceObservatory/website/issues/142 From 52b45117b48c8d6a28ea93ac4e8d2346a3856942 Mon Sep 17 00:00:00 2001 From: Sef Kloninger Date: Fri, 13 Nov 2026 15:01:33 -0800 Subject: [PATCH 02/34] docs(design): add Cloudflare integration to the API keys design Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf --- docs/design/api-keys.md | 59 +++++++++++++++++++++++++++++++++-------- 1 file changed, 48 insertions(+), 11 deletions(-) diff --git a/docs/design/api-keys.md b/docs/design/api-keys.md index bcbb924..4df8413 100644 --- a/docs/design/api-keys.md +++ b/docs/design/api-keys.md @@ -1,24 +1,22 @@ # API Keys for the Platform Proxy -Initial draft by Claude Code. Revised by Sef Kloninger, - -[Issue #142][issue] - +Sef Kloninger <> with Claude Code \ +[Issue #142][issue] \ Last Update: Nov 13, 2026 ## Summary -This feature is to add per-user access to the Development Finance Observatory backends. This will enable +This feature is to add per-user access to the Development Finance Observatory backend. Needs: - Metered and ACL'ed access -- Cost and operational controls -- Enable potential to recoup costs from for-profits that wants programmatic access to our data. +- Prevent cost overruns or operations problems that could come from +- Enable potential other business arrangements, e.g. charge to serve or syndicate high-volume, high-cost, or licensed data. -We intend to still have a free / open tier for ease of use and for crawlers. But more expensive and frequent access will need to come via an API key. +We intend to still have a free / open tier. We want minimal friction for the majority of users to use DFO, it's a valuable onramp; also search and AI crawlers are an important source of traffic for us, and will continue to be. But more expensive and frequent access will go through the API key. The proxy fronts the public Search, Datasets and Graph APIs (`/api/v1/*`) and the MCP servers (`/mcp`). Today it knows callers only by address. -Initial requirements: +Requirements: - Anonymous access will stays open up to a limit. Our goal is to manage usage and enable rate limits, not wholesale API gating. - Each key carries its own rate limit. @@ -59,7 +57,7 @@ The key is sent as `Authorization: Bearer dfo_…`. The proxy also accepts `X-AP - A call that sends both headers with different keys is refused with a 400. - The proxy strips the key before forwarding, so it never reaches a backend or its logs. -**How other services do it** +**Comparables: How Other Services Do It** | Style | Who uses it | Notes | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -139,6 +137,43 @@ A revoked key can keep working until the cache entry expires, so revocation take A keyed call is named to the backends as `x-dfo-caller: key:` instead of `ip:`. dfo-ai already expects that form. dfo-apis needs a small change to accept it, so its own allowances count per key and not per address. +### Cloudflare Integration + +Cloudflare sits in front of the site and rate-limits by address. The proxy stays the per-key limiter, and Cloudflare is a coarse backstop against floods, set above the highest limit any key will have. Cloudflare cannot tell a real key from a made-up one, since it sees only a header value, so it cannot enforce per-key limits itself. + +**What Cloudflare recommends** + +Its [rate limiting best practices][cf-best-practices] for REST APIs count requests per API key, not per address: + +- To protect an endpoint: match the path and method, count by the `x-api-key` header, and block above the rate. +- To protect resources: count by path plus `x-api-key`, so each key gets a rate per resource. +- For clients with no key: count by IP. +- For the rate itself: take it from API Discovery or from past traffic. The page gives no default number. + +It shows no paired "anonymous rule plus keyed rule" example, but that is what the pieces add up to. + +**What each plan allows** + +Counting by a header needs Advanced Rate Limiting, an Enterprise add-on ([availability by plan][cf-availability]). + +| Plan | Can count by | Rules | Longest window | +| ----------------------------------- | ------------------------------------------- | ----- | -------------- | +| Free | IP | 1 | 10 s | +| Pro | IP | 2 | 1 min | +| Business | IP, IP with NAT support | 5 | 10 min | +| Enterprise | IP, IP with NAT support | 100 | about 18 h | +| Enterprise + Advanced Rate Limiting | Headers, cookies, query, ASN, path and more | 100 | about 18 h | + +Below Enterprise, a rate limiting rule's own match expression cannot reference request headers, so "apply this rule only to requests without a key" cannot be written in the rule. + +**Options for keyed traffic** + +- With Advanced Rate Limiting: follow Cloudflare's pattern. One rule counts by IP for requests with no key header. Another counts by the key header at a high ceiling. A fake key then earns only a separate bucket that is still limited. +- Without it: raise the per-address threshold, or add a custom rule that skips rate limiting for requests that carry a key header. Whether custom rules can match headers and skip rate limiting rules on every plan is unconfirmed. The skip can be abused with a fake header, and the proxy's limit is then the only one left for that traffic. +- If today's thresholds are already well above 120 and 300 calls a minute, Phase 1 may need no edge change. + +Which option applies depends on the zone's plan and its current rules. See Open Questions. + ### Logs and Docs - The request log line carries the key caller, so usage per key can be counted in Cloud Logging. This is what Phase 3 needs to find high-volume callers. @@ -213,7 +248,7 @@ Order matters between the website and dfo-apis. dfo-apis refuses a caller form i The first three need an answer before Phase 1 code is written. -- [ ] **Cloudflare.** Who owns the WAF rate rules, and can they exempt or raise the threshold for requests that carry a key header? An exemption on header presence alone could be abused with a fake key, so the rule may need a higher ceiling instead of none. +- [ ] **Cloudflare.** Who owns the WAF rate rules, and can they exempt or raise the threshold for requests that carry a key header? An exemption on header presence alone could be abused with a fake key, so the rule may need a higher ceiling instead of none. Which plan is the zone on, and what are the current thresholds? See Cloudflare Integration. - [ ] **Does a key work on `/mcp` in Phase 1,** or only on `/api/v1/*`? The first partner's need is the API. - [ ] **What is the default self-service limit in Phase 2,** relative to the anonymous limit? It has to be worth signing up for. - [ ] **How do we reach current anonymous users** for the Phase 2 transition, given we know them only as hashed addresses? Candidates: docs, response headers, the SDK's `x-dfo-client` header. @@ -221,3 +256,5 @@ The first three need an answer before Phase 1 code is written. - [ ] **Does a key identify an account to the backends as well,** so a signed-in user's key and their site session share allowances? dfo-ai already names a `user:` caller form. [issue]: https://github.com/DevelopmentFinanceObservatory/website/issues/142 +[cf-best-practices]: https://developers.cloudflare.com/waf/rate-limiting-rules/best-practices/ +[cf-availability]: https://developers.cloudflare.com/waf/rate-limiting-rules/ From f5bf85c4d4421ec478b0d820f1260f115144f525 Mon Sep 17 00:00:00 2001 From: Sef Kloninger Date: Fri, 13 Nov 2026 15:02:21 -0800 Subject: [PATCH 03/34] docs(design): link the Cloudflare question to its section Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf --- docs/design/api-keys.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/design/api-keys.md b/docs/design/api-keys.md index 4df8413..1e1da12 100644 --- a/docs/design/api-keys.md +++ b/docs/design/api-keys.md @@ -248,7 +248,7 @@ Order matters between the website and dfo-apis. dfo-apis refuses a caller form i The first three need an answer before Phase 1 code is written. -- [ ] **Cloudflare.** Who owns the WAF rate rules, and can they exempt or raise the threshold for requests that carry a key header? An exemption on header presence alone could be abused with a fake key, so the rule may need a higher ceiling instead of none. Which plan is the zone on, and what are the current thresholds? See Cloudflare Integration. +- [ ] **Cloudflare.** Who owns the WAF rate rules, and can they exempt or raise the threshold for requests that carry a key header? An exemption on header presence alone could be abused with a fake key, so the rule may need a higher ceiling instead of none. Which plan is the zone on, and what are the current thresholds? See [Cloudflare Integration][cloudflare-integration]. - [ ] **Does a key work on `/mcp` in Phase 1,** or only on `/api/v1/*`? The first partner's need is the API. - [ ] **What is the default self-service limit in Phase 2,** relative to the anonymous limit? It has to be worth signing up for. - [ ] **How do we reach current anonymous users** for the Phase 2 transition, given we know them only as hashed addresses? Candidates: docs, response headers, the SDK's `x-dfo-client` header. @@ -258,3 +258,4 @@ The first three need an answer before Phase 1 code is written. [issue]: https://github.com/DevelopmentFinanceObservatory/website/issues/142 [cf-best-practices]: https://developers.cloudflare.com/waf/rate-limiting-rules/best-practices/ [cf-availability]: https://developers.cloudflare.com/waf/rate-limiting-rules/ +[cloudflare-integration]: #cloudflare-integration From 473878808c87f3a93c052e10c1b655e7d9b27639 Mon Sep 17 00:00:00 2001 From: Sef Kloninger Date: Fri, 13 Nov 2026 15:06:15 -0800 Subject: [PATCH 04/34] docs(design): settle API key scope questions and add future features Keys cover /mcp from Phase 1, default limits are tuned in Phase 2 from observed usage, and expiring keys and multiple keys per account move to a Future Features section. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf --- docs/design/api-keys.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/design/api-keys.md b/docs/design/api-keys.md index 1e1da12..ddb3ca8 100644 --- a/docs/design/api-keys.md +++ b/docs/design/api-keys.md @@ -187,6 +187,8 @@ Three phases take keys from an optional test feature to the normal way heavy use **Goal:** Optional keys work end to end, for testing and the first partner +**Scope:** Keys work on both `/api/v1/*` and `/mcp`. MCP is in scope from the start because it can be a significant cost driver. + **Who gets a key:** A few callers we choose **Provisioning:** Manual: an admin command creates and revokes keys @@ -207,7 +209,7 @@ Three phases take keys from an optional test feature to the normal way heavy use **Provisioning:** Self-service from the account menu: create, label, revoke, see last use -**Limits:** Default tier for self-service keys; higher tiers granted by an operator +**Limits:** A default for self-service keys, with higher limits granted by an operator. We will examine current usage and tune the default and the anonymous thresholds at that time, as part of the transition plan. **Anonymous access:** Unchanged; docs start recommending a key @@ -244,15 +246,19 @@ Most of the work is in the website. The Phase 1 pieces: Order matters between the website and dfo-apis. dfo-apis refuses a caller form it does not recognize when it arrives with the shared secret, so the dfo-apis change has to be live before the website starts sending `key:` callers. +## Future Features + +Not planned for any phase yet. The design should not rule them out. + +- **Expiring keys.** A key carries an expiry date and stops working after it. Until then a key lives until it is revoked. +- **Multiple keys per account.** An account holds several keys at once, for example one per application or to rotate a key without downtime. + ## Open Questions -The first three need an answer before Phase 1 code is written. +The Cloudflare question needs an answer before Phase 1 code is written. - [ ] **Cloudflare.** Who owns the WAF rate rules, and can they exempt or raise the threshold for requests that carry a key header? An exemption on header presence alone could be abused with a fake key, so the rule may need a higher ceiling instead of none. Which plan is the zone on, and what are the current thresholds? See [Cloudflare Integration][cloudflare-integration]. -- [ ] **Does a key work on `/mcp` in Phase 1,** or only on `/api/v1/*`? The first partner's need is the API. -- [ ] **What is the default self-service limit in Phase 2,** relative to the anonymous limit? It has to be worth signing up for. - [ ] **How do we reach current anonymous users** for the Phase 2 transition, given we know them only as hashed addresses? Candidates: docs, response headers, the SDK's `x-dfo-client` header. -- [ ] **Do keys expire,** and can an account hold more than one? - [ ] **Does a key identify an account to the backends as well,** so a signed-in user's key and their site session share allowances? dfo-ai already names a `user:` caller form. [issue]: https://github.com/DevelopmentFinanceObservatory/website/issues/142 From f202068e5c1896b610c236f878ed516ddace59e2 Mon Sep 17 00:00:00 2001 From: Sef Kloninger Date: Fri, 13 Nov 2026 15:10:15 -0800 Subject: [PATCH 05/34] docs(design): add a table of contents to the API keys design Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf --- docs/design/api-keys.md | 43 +++++++++++++++++++++++++++++++++++++++-- 1 file changed, 41 insertions(+), 2 deletions(-) diff --git a/docs/design/api-keys.md b/docs/design/api-keys.md index ddb3ca8..df22a34 100644 --- a/docs/design/api-keys.md +++ b/docs/design/api-keys.md @@ -4,6 +4,26 @@ Sef Kloninger <> with Claude Code \ [Issue #142][issue] \ Last Update: Nov 13, 2026 +## Contents + +- [Summary][] +- [How It Works Today][] +- [Design][] + - [The Key][] + - [Which Header Carries the Key][] + - [Storage][] + - [Limits][] + - [The Proxy Check][] + - [Cloudflare Integration][] + - [Logs and Docs][] +- [Phases][] + - [Phase 1: Validate][] + - [Phase 2: Provision][] + - [Phase 3: Enforce][] +- [Work by Repository][] +- [Future Features][] +- [Open Questions][] + ## Summary This feature is to add per-user access to the Development Finance Observatory backend. Needs: @@ -252,16 +272,35 @@ Not planned for any phase yet. The design should not rule them out. - **Expiring keys.** A key carries an expiry date and stops working after it. Until then a key lives until it is revoked. - **Multiple keys per account.** An account holds several keys at once, for example one per application or to rotate a key without downtime. +- **More graceful degradation besides limits.** Depending on how often limits are hit, and the user impact of that, we could have fancier throttles in the future + - Soft vs. hard limits (warnings) + - Hourly vs. weekly limits, like how modern chat interfaces work. This protects against spiky workloads while mitigating the impact of hitting a limit ("try again in a few hours"). ## Open Questions The Cloudflare question needs an answer before Phase 1 code is written. -- [ ] **Cloudflare.** Who owns the WAF rate rules, and can they exempt or raise the threshold for requests that carry a key header? An exemption on header presence alone could be abused with a fake key, so the rule may need a higher ceiling instead of none. Which plan is the zone on, and what are the current thresholds? See [Cloudflare Integration][cloudflare-integration]. +- [ ] **Cloudflare.** Who owns the WAF rate rules, and can they exempt or raise the threshold for requests that carry a key header? An exemption on header presence alone could be abused with a fake key, so the rule may need a higher ceiling instead of none. Which plan is the zone on, and what are the current thresholds? See [Cloudflare Integration][]. - [ ] **How do we reach current anonymous users** for the Phase 2 transition, given we know them only as hashed addresses? Candidates: docs, response headers, the SDK's `x-dfo-client` header. - [ ] **Does a key identify an account to the backends as well,** so a signed-in user's key and their site session share allowances? dfo-ai already names a `user:` caller form. [issue]: https://github.com/DevelopmentFinanceObservatory/website/issues/142 [cf-best-practices]: https://developers.cloudflare.com/waf/rate-limiting-rules/best-practices/ [cf-availability]: https://developers.cloudflare.com/waf/rate-limiting-rules/ -[cloudflare-integration]: #cloudflare-integration +[Summary]: #summary +[How It Works Today]: #how-it-works-today +[Design]: #design +[The Key]: #the-key +[Which Header Carries the Key]: #which-header-carries-the-key +[Storage]: #storage +[Limits]: #limits +[The Proxy Check]: #the-proxy-check +[Cloudflare Integration]: #cloudflare-integration +[Logs and Docs]: #logs-and-docs +[Phases]: #phases +[Phase 1: Validate]: #phase-1-validate +[Phase 2: Provision]: #phase-2-provision +[Phase 3: Enforce]: #phase-3-enforce +[Work by Repository]: #work-by-repository +[Future Features]: #future-features +[Open Questions]: #open-questions From f6ec3ca6da15e17d2ba2aee4fe2de322c0fe7114 Mon Sep 17 00:00:00 2001 From: Sef Kloninger Date: Fri, 13 Nov 2026 15:16:12 -0800 Subject: [PATCH 06/34] docs(design): fold the key header choice into The Key section Present the header as a proposal within The Key, and introduce the survey of how other services convey tokens. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf --- docs/design/api-keys.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/design/api-keys.md b/docs/design/api-keys.md index df22a34..0a63244 100644 --- a/docs/design/api-keys.md +++ b/docs/design/api-keys.md @@ -64,12 +64,9 @@ A key is optional on every call. A call with a valid key is counted against the ### The Key - Format: a recognisable prefix, an environment marker and random characters, for example `dfo_live_<32+ random chars>`. The prefix lets secret scanners and our own logs spot a leaked key. -- Sent as `Authorization: Bearer `, with `X-API-Key` accepted as an alias. See the next section. - Shown once, when it is created. We store only a SHA-256 hash, so a database leak exposes no usable key. -### Which Header Carries the Key - -The key is sent as `Authorization: Bearer dfo_…`. The proxy also accepts `X-API-Key` as an alias. A key is never accepted in the query string. +How the key is sent is a design choice. We propose send the key as a bearer token in a standard header, `Authorization: Bearer dfo_…`. The proxy also accepts `X-API-Key` as an alias. And we don't plan to accept the same bearer in a query string as that's an outmoded style, although some people like it for ease of use and debug-ability. - Bearer is what a programmatic partner reaches for first, and what MCP developer clients set most easily. - The `dfo_` prefix lets the proxy tell our key from any other bearer token. @@ -79,6 +76,8 @@ The key is sent as `Authorization: Bearer dfo_…`. The proxy also accepts `X-AP **Comparables: How Other Services Do It** +Since this is an interesting choice, I asked Claude to do a quick survey to see how other services convey tokens. + | Style | Who uses it | Notes | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Authorization: Bearer ` | OpenAI, Stripe, GitHub, Cloudflare, SendGrid | The closest thing to a standard. Every HTTP client and SDK can set it, and proxies, loggers and secret scanners already treat it as sensitive | @@ -291,7 +290,6 @@ The Cloudflare question needs an answer before Phase 1 code is written. [How It Works Today]: #how-it-works-today [Design]: #design [The Key]: #the-key -[Which Header Carries the Key]: #which-header-carries-the-key [Storage]: #storage [Limits]: #limits [The Proxy Check]: #the-proxy-check From 371cb5b65f406f1a0ce57dbb780aba81ba46a55e Mon Sep 17 00:00:00 2001 From: Sef Kloninger Date: Fri, 13 Nov 2026 15:17:46 -0800 Subject: [PATCH 07/34] docs(design): proofread the API keys design Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf --- docs/design/api-keys.md | 33 ++++++++++++++++----------------- 1 file changed, 16 insertions(+), 17 deletions(-) diff --git a/docs/design/api-keys.md b/docs/design/api-keys.md index 0a63244..11215ef 100644 --- a/docs/design/api-keys.md +++ b/docs/design/api-keys.md @@ -9,8 +9,7 @@ Last Update: Nov 13, 2026 - [Summary][] - [How It Works Today][] - [Design][] - - [The Key][] - - [Which Header Carries the Key][] + - [Key Format and Communication][] - [Storage][] - [Limits][] - [The Proxy Check][] @@ -32,17 +31,17 @@ This feature is to add per-user access to the Development Finance Observatory ba - Prevent cost overruns or operations problems that could come from - Enable potential other business arrangements, e.g. charge to serve or syndicate high-volume, high-cost, or licensed data. -We intend to still have a free / open tier. We want minimal friction for the majority of users to use DFO, it's a valuable onramp; also search and AI crawlers are an important source of traffic for us, and will continue to be. But more expensive and frequent access will go through the API key. +We intend to still have a free / open tier. We want minimal friction for the majority of users to use DFO, since it's a valuable onramp. Search and AI crawlers are also an important source of traffic for us, and will continue to be. But more expensive and frequent access will go through an API key. The proxy fronts the public Search, Datasets and Graph APIs (`/api/v1/*`) and the MCP servers (`/mcp`). Today it knows callers only by address. Requirements: -- Anonymous access will stays open up to a limit. Our goal is to manage usage and enable rate limits, not wholesale API gating. +- Anonymous access will stay open up to a limit. Our goal is to manage usage and enable rate limits, not wholesale API gating. - Each key carries its own rate limit. - Some MCP features may later require sign-in. That is separate from keys and out of scope here. -We'll take a phased approach. Initially we'll prove the concept with hand-provisioned keys and limited features. Once proven this works in production, follow-on work will enable more features, self-service provisioning, and admin interfaces to adjust access and limits. +We'll take a phased approach. Initially we'll prove the concept with hand-provisioned keys and limited features. Once this is proven in production, follow-on work will enable more features, self-service provisioning, and admin interfaces to adjust access and limits. ## How It Works Today @@ -61,12 +60,12 @@ Every public API and MCP call passes through one function in the website, `forwa A key is optional on every call. A call with a valid key is counted against the key at the key's limit, a call with no key is counted against the address as today, and a call with a bad key is refused. This is a proposal to react to, not a settled design. -### The Key +### Key Format and Communication -- Format: a recognisable prefix, an environment marker and random characters, for example `dfo_live_<32+ random chars>`. The prefix lets secret scanners and our own logs spot a leaked key. +- Format: a recognizable prefix, an environment marker and random characters, for example `dfo_live_<32+ random chars>`. The prefix lets secret scanners and our own logs spot a leaked key. - Shown once, when it is created. We store only a SHA-256 hash, so a database leak exposes no usable key. -How the key is sent is a design choice. We propose send the key as a bearer token in a standard header, `Authorization: Bearer dfo_…`. The proxy also accepts `X-API-Key` as an alias. And we don't plan to accept the same bearer in a query string as that's an outmoded style, although some people like it for ease of use and debug-ability. +How the key is sent is a design choice. We propose sending the key as a bearer token in a standard header, `Authorization: Bearer dfo_…`. The proxy also accepts `X-API-Key` as an alias. We don't plan to accept the key in a query string, as that's an outmoded style, although some people like it for ease of use and debuggability. - Bearer is what a programmatic partner reaches for first, and what MCP developer clients set most easily. - The `dfo_` prefix lets the proxy tell our key from any other bearer token. @@ -86,7 +85,7 @@ Since this is an interesting choice, I asked Claude to do a quick survey to see Some services accept more than one: Stripe takes Bearer or HTTP Basic, and api.data.gov takes `X-Api-Key` or the query parameter. The split between the first two styles is mostly whether `Authorization` is already in use. A service with only keys uses Bearer. A service with keys and user tokens moves the key to a custom header. -**Compatibility with MCP clients** +**Compatibility with MCP Clients** The MCP specification defines authorization as OAuth, with the token sent as `Authorization: Bearer`. It has no API-key concept, so support for a key depends on the client. @@ -97,7 +96,7 @@ The MCP specification defines authorization as OAuth, with the token sent as `Au So a key on `/mcp` serves programmatic and developer use. Chat-app users stay anonymous until `/mcp` has OAuth sign-in, which is the separate "MCP features that require logging in" work. -**Compatibility with the proxy as built** +**Compatibility with the Proxy as Built** | Path | What happens to `Authorization` today | Effect of a key there | | -------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | @@ -113,7 +112,7 @@ A new `api_key` table in the website's Postgres, beside the accounts and the lim | ------------------------------------ | --------------------------------------------------------------------------- | | id | Short public identifier, used in logs and as the caller name | | key_hash | SHA-256 of the key, unique | -| prefix | First characters of the key, so its owner can recognise it in a list | +| prefix | First characters of the key, so its owner can recognize it in a list | | label | What the key is for | | user_id | Owning account. Empty for a manually provisioned key in Phase 1 | | api_limit, mcp_limit | Calls per window on each surface. Empty means the default for keyed callers | @@ -160,7 +159,7 @@ A keyed call is named to the backends as `x-dfo-caller: key:` instead of `ip Cloudflare sits in front of the site and rate-limits by address. The proxy stays the per-key limiter, and Cloudflare is a coarse backstop against floods, set above the highest limit any key will have. Cloudflare cannot tell a real key from a made-up one, since it sees only a header value, so it cannot enforce per-key limits itself. -**What Cloudflare recommends** +**What Cloudflare Recommends** Its [rate limiting best practices][cf-best-practices] for REST APIs count requests per API key, not per address: @@ -171,7 +170,7 @@ Its [rate limiting best practices][cf-best-practices] for REST APIs count reques It shows no paired "anonymous rule plus keyed rule" example, but that is what the pieces add up to. -**What each plan allows** +**What Each Plan Allows** Counting by a header needs Advanced Rate Limiting, an Enterprise add-on ([availability by plan][cf-availability]). @@ -185,13 +184,13 @@ Counting by a header needs Advanced Rate Limiting, an Enterprise add-on ([availa Below Enterprise, a rate limiting rule's own match expression cannot reference request headers, so "apply this rule only to requests without a key" cannot be written in the rule. -**Options for keyed traffic** +**Options for Keyed Traffic** - With Advanced Rate Limiting: follow Cloudflare's pattern. One rule counts by IP for requests with no key header. Another counts by the key header at a high ceiling. A fake key then earns only a separate bucket that is still limited. - Without it: raise the per-address threshold, or add a custom rule that skips rate limiting for requests that carry a key header. Whether custom rules can match headers and skip rate limiting rules on every plan is unconfirmed. The skip can be abused with a fake header, and the proxy's limit is then the only one left for that traffic. - If today's thresholds are already well above 120 and 300 calls a minute, Phase 1 may need no edge change. -Which option applies depends on the zone's plan and its current rules. See Open Questions. +Which option applies depends on the zone's plan and its current rules. See [Open Questions][]. ### Logs and Docs @@ -271,7 +270,7 @@ Not planned for any phase yet. The design should not rule them out. - **Expiring keys.** A key carries an expiry date and stops working after it. Until then a key lives until it is revoked. - **Multiple keys per account.** An account holds several keys at once, for example one per application or to rotate a key without downtime. -- **More graceful degradation besides limits.** Depending on how often limits are hit, and the user impact of that, we could have fancier throttles in the future +- **More graceful degradation besides limits.** Depending on how often limits are hit, and the user impact of that, we could have fancier throttles in the future: - Soft vs. hard limits (warnings) - Hourly vs. weekly limits, like how modern chat interfaces work. This protects against spiky workloads while mitigating the impact of hitting a limit ("try again in a few hours"). @@ -289,7 +288,7 @@ The Cloudflare question needs an answer before Phase 1 code is written. [Summary]: #summary [How It Works Today]: #how-it-works-today [Design]: #design -[The Key]: #the-key +[Key Format and Communication]: #key-format-and-communication [Storage]: #storage [Limits]: #limits [The Proxy Check]: #the-proxy-check From 1c59354478cc0c120d21695daa683c3cf51e4ff6 Mon Sep 17 00:00:00 2001 From: Sef Kloninger Date: Fri, 13 Nov 2026 15:23:32 -0800 Subject: [PATCH 08/34] docs(design): proofread the revised API keys summary Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf --- docs/design/api-keys.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/design/api-keys.md b/docs/design/api-keys.md index 11215ef..103f29f 100644 --- a/docs/design/api-keys.md +++ b/docs/design/api-keys.md @@ -25,11 +25,11 @@ Last Update: Nov 13, 2026 ## Summary -This feature is to add per-user access to the Development Finance Observatory backend. Needs: +This feature is to add per-user access to the Development Finance Observatory backend. This will enable: - Metered and ACL'ed access -- Prevent cost overruns or operations problems that could come from -- Enable potential other business arrangements, e.g. charge to serve or syndicate high-volume, high-cost, or licensed data. +- Protection against cost overruns or operational problems stemming from heavy legitimate use or high-volume access by an adversary. Having the ability to grant API-specific access lets us lower default limits for safety, and make runtime maneuvers like turning off free access altogether if we are being abused or attacked. +- Potential future cost models, e.g. serving high-volume, high-cost, or licensed data We intend to still have a free / open tier. We want minimal friction for the majority of users to use DFO, since it's a valuable onramp. Search and AI crawlers are also an important source of traffic for us, and will continue to be. But more expensive and frequent access will go through an API key. @@ -48,7 +48,7 @@ We'll take a phased approach. Initially we'll prove the concept with hand-provis Every public API and MCP call passes through one function in the website, `forward()` in `src/lib/proxy/forward.ts`. That is the single place a key needs to be checked. - **Rate limit.** `forward()` counts each call against the client's address in a fixed window: 120 calls a minute on `/api/*`, 300 on `/mcp`. The counters live in the website's Postgres (`limit_counter` table) and are shared by all instances. If the count fails or is slow, the call goes through uncounted. -- **No Redis.** The task description mentions turning a Redis limiter back on. There is no Redis code in the website now, so per-key limits need no Memorystore instance. +- **No Redis.** The original task description mentions turning a Redis limiter back on. There is no Redis code in the website now, so per-key limits need no Memorystore instance. - **Edge limits.** Cloudflare WAF rules also rate-limit by address, in front of the site. - **Caller identity.** The proxy names the caller to the backends as `x-dfo-caller: ip:`, a keyed hash of the address. dfo-apis counts its own allowances (shares, cards, pins) against that name. It trusts the header only beside a secret it shares with the website. - **Backends are ahead of us in one place.** dfo-ai's caller module already documents `key:` and `user:` callers "from the website's edge". dfo-apis accepts only the `ip:` form. @@ -75,7 +75,7 @@ How the key is sent is a design choice. We propose sending the key as a bearer t **Comparables: How Other Services Do It** -Since this is an interesting choice, I asked Claude to do a quick survey to see how other services convey tokens. +Since this is an interesting choice, we did an informal survey of how other services convey tokens. | Style | Who uses it | Notes | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -243,7 +243,7 @@ Three phases take keys from an optional test feature to the normal way heavy use **Provisioning:** Self-service, plus operator tools to raise or cut a key's limit -**Limits:** Anonymous limits lowered in steps, key tiers settled +**Limits:** Anonymous limits lowered in steps **Anonymous access:** Open but lower From 84dca90167f3649bd26b535b9d0bbd416ed741e3 Mon Sep 17 00:00:00 2001 From: Sef Kloninger Date: Fri, 13 Nov 2026 15:24:13 -0800 Subject: [PATCH 09/34] docs(design): say key-specific access in the API keys summary Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf --- docs/design/api-keys.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design/api-keys.md b/docs/design/api-keys.md index 103f29f..2ab7b94 100644 --- a/docs/design/api-keys.md +++ b/docs/design/api-keys.md @@ -28,7 +28,7 @@ Last Update: Nov 13, 2026 This feature is to add per-user access to the Development Finance Observatory backend. This will enable: - Metered and ACL'ed access -- Protection against cost overruns or operational problems stemming from heavy legitimate use or high-volume access by an adversary. Having the ability to grant API-specific access lets us lower default limits for safety, and make runtime maneuvers like turning off free access altogether if we are being abused or attacked. +- Protection against cost overruns or operational problems stemming from heavy legitimate use or high-volume access by an adversary. Having the ability to grant key-specific access lets us lower default limits for safety, and make runtime maneuvers like turning off free access altogether if we are being abused or attacked. - Potential future cost models, e.g. serving high-volume, high-cost, or licensed data We intend to still have a free / open tier. We want minimal friction for the majority of users to use DFO, since it's a valuable onramp. Search and AI crawlers are also an important source of traffic for us, and will continue to be. But more expensive and frequent access will go through an API key. From 113390512dbdad98c14c4aa4b2594d2525c5256c Mon Sep 17 00:00:00 2001 From: Sef Kloninger Date: Fri, 13 Nov 2026 15:34:10 -0800 Subject: [PATCH 10/34] docs(design): add alternatives considered to the API keys design Compares building against Better Auth's API key plugin, a hosted key service, hosted and Google gateways, and Cloudflare. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf --- docs/design/api-keys.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/design/api-keys.md b/docs/design/api-keys.md index 2ab7b94..7dd7e1d 100644 --- a/docs/design/api-keys.md +++ b/docs/design/api-keys.md @@ -20,6 +20,7 @@ Last Update: Nov 13, 2026 - [Phase 2: Provision][] - [Phase 3: Enforce][] - [Work by Repository][] +- [Alternatives Considered][] - [Future Features][] - [Open Questions][] @@ -264,6 +265,20 @@ Most of the work is in the website. The Phase 1 pieces: Order matters between the website and dfo-apis. dfo-apis refuses a caller form it does not recognize when it arrives with the shared secret, so the dfo-apis change has to be live before the website starts sending `key:` callers. +## Alternatives Considered + +We looked at buying or reusing this instead of building it. The plan stays to build, because the hard parts are already in the proxy: one function every call passes through, a shared limiter in Postgres, and caller naming to the backends. What is left to build is a table, a lookup and an admin command. One option, Better Auth's plugin, is worth a closer look before Phase 2. + +| Option | What it is | What it would give us | Why not, or not yet | +| ------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Better Auth API key plugin][better-auth-api-key] | An add-on package (`@better-auth/api-key`) for the auth library the site already uses | Key creation and verification, per-key rate limits, expiry, usage quotas with refill, metadata, and client methods for create, list and revoke, in our own Postgres | The closest fit, and more a reuse than a buy. Open points: whether keys can exist without an owning account (Phase 1 keys have none), whether its rate limiter can share our `limit_counter` window and headers, and how it stores keys. Worth evaluating as the base for Phase 2 self-service | +| Hosted key service, for example [Unkey][unkey] | A service that issues and verifies keys; the proxy calls it on each request | Key management, per-key limits and usage analytics with no tables of our own. A free tier of 150,000 verifications a month | A network call to a third party on every keyed request, and a new vendor holding our callers' keys. Cost grows with traffic, which is the thing we are trying to control | +| Hosted API gateway, for example [Zuplo][zuplo] | A managed gateway in front of the APIs, with keys, rate limits and a developer portal | The whole feature, including self-service sign-up and docs | It replaces the proxy we already have. Streaming (SSE and MCP), caller naming and the harness token would all need to be rebuilt in its terms | +| Google Cloud API Gateway or Apigee | Google's gateways, in the cloud the backends already run in | API Gateway: keys and quotas. Apigee: a full product with developer portal and monetization | API Gateway keys are Google Cloud API keys, which suits internal consumers more than outside sign-ups. Apigee is priced and sized for a larger API program than ours | +| Cloudflare | Already in front of the site | Edge rate limiting per key header on the Enterprise Advanced Rate Limiting plan | It does not issue or validate keys, so it cannot replace the proxy check. See [Cloudflare Integration][] | + +If monetization becomes real, the calculation changes: metering, billing and a developer portal are where the gateway products earn their cost. Nothing in this design blocks moving to one later, since keys are checked in one place. + ## Future Features Not planned for any phase yet. The design should not rule them out. @@ -285,6 +300,9 @@ The Cloudflare question needs an answer before Phase 1 code is written. [issue]: https://github.com/DevelopmentFinanceObservatory/website/issues/142 [cf-best-practices]: https://developers.cloudflare.com/waf/rate-limiting-rules/best-practices/ [cf-availability]: https://developers.cloudflare.com/waf/rate-limiting-rules/ +[better-auth-api-key]: https://www.better-auth.com/docs/plugins/api-key +[unkey]: https://www.unkey.com/docs/platform/workspaces/billing +[zuplo]: https://zuplo.com/pricing [Summary]: #summary [How It Works Today]: #how-it-works-today [Design]: #design @@ -299,5 +317,6 @@ The Cloudflare question needs an answer before Phase 1 code is written. [Phase 2: Provision]: #phase-2-provision [Phase 3: Enforce]: #phase-3-enforce [Work by Repository]: #work-by-repository +[Alternatives Considered]: #alternatives-considered [Future Features]: #future-features [Open Questions]: #open-questions From 173fb2a018287ee0519181515021d8dc943b69d6 Mon Sep 17 00:00:00 2001 From: Sef Kloninger Date: Fri, 13 Nov 2026 16:26:48 -0800 Subject: [PATCH 11/34] docs(design): restructure API keys design into requirements, build and use Split Design into Requirements (true for either option), Build (our own key table) and Use (Better Auth's API key plugin, with what it provides, how it fits, its lack of an admin interface, and a spike checklist). Add a tentative recommendation to the summary and note that the work-by-repository split holds for both options. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf --- docs/design/api-keys.md | 214 +++++++++++++++++++++++++++++----------- 1 file changed, 155 insertions(+), 59 deletions(-) diff --git a/docs/design/api-keys.md b/docs/design/api-keys.md index 7dd7e1d..dfc99ec 100644 --- a/docs/design/api-keys.md +++ b/docs/design/api-keys.md @@ -8,13 +8,21 @@ Last Update: Nov 13, 2026 - [Summary][] - [How It Works Today][] -- [Design][] +- [Requirements][] - [Key Format and Communication][] - - [Storage][] - [Limits][] - - [The Proxy Check][] - [Cloudflare Integration][] - [Logs and Docs][] +- [Build][] + - [Storage][] + - [The Proxy Check][] + - [Future Work: Admin Interface][] +- [Use: Better Auth API Key Plugin][] + - [What the Plugin Provides][] + - [How It Would Fit][] + - [Admin System][] + - [What It Saves and What It Costs][] + - [Spike Before Deciding][] - [Phases][] - [Phase 1: Validate][] - [Phase 2: Provision][] @@ -42,6 +50,8 @@ Requirements: - Each key carries its own rate limit. - Some MCP features may later require sign-in. That is separate from keys and out of scope here. +**Recommendation (tentative).** There are two ways to get this: [build][Build] the key store ourselves, or [use][Use: Better Auth API Key Plugin] the API key plugin of Better Auth, the library that already handles sign-in on the site. We lean toward using the plugin for key storage and management, while keeping our own rate limiter and proxy check. It saves writing security-sensitive code and brings expiry, multiple keys per account and self-service endpoints that Phase 2 needs. We are not sure yet. A short spike should settle it before Phase 1 code starts, because moving existing keys between the two stores later may mean reissuing them. If the spike fails any of its checks, we build. + We'll take a phased approach. Initially we'll prove the concept with hand-provisioned keys and limited features. Once this is proven in production, follow-on work will enable more features, self-service provisioning, and admin interfaces to adjust access and limits. ## How It Works Today @@ -57,9 +67,9 @@ Every public API and MCP call passes through one function in the website, `forwa - **Accounts.** The site has sign-in (Better Auth on its own Postgres) and an account menu, which is where self-service keys would attach. - **Docs.** The API quickstart says the API accepts requests without a key. -## Design +## Requirements -A key is optional on every call. A call with a valid key is counted against the key at the key's limit, a call with no key is counted against the address as today, and a call with a bad key is refused. This is a proposal to react to, not a settled design. +A key is optional on every call. A call with a valid key is counted against the key at the key's limit, a call with no key is counted against the address as today, and a call with a bad key is refused. These requirements hold whether we build the key store or use Better Auth's plugin. ### Key Format and Communication @@ -105,32 +115,16 @@ So a key on `/mcp` serves programmatic and developer use. Chat-app users stay an | `/mcp`, proxy holds the harness token (production) | Overwritten with the harness token | No conflict. The proxy reads the key first, then replaces the header as it does now | | `/mcp`, proxy holds no token | The caller's value is passed through to the harness | The only conflict. The `dfo_` prefix resolves it: our key is consumed, any other token passes through | -### Storage - -A new `api_key` table in the website's Postgres, beside the accounts and the limit counters. - -| Column | Purpose | -| ------------------------------------ | --------------------------------------------------------------------------- | -| id | Short public identifier, used in logs and as the caller name | -| key_hash | SHA-256 of the key, unique | -| prefix | First characters of the key, so its owner can recognize it in a list | -| label | What the key is for | -| user_id | Owning account. Empty for a manually provisioned key in Phase 1 | -| api_limit, mcp_limit | Calls per window on each surface. Empty means the default for keyed callers | -| created_at, revoked_at, last_used_at | Lifecycle | - -Postgres rather than Redis: the limiter already counts there, key volume is small, and it adds no new infrastructure. This can be changed later if we need something more scalable and performant at the cost of some additional dev and operational complexity. - ### Limits A key's limit is two plain numbers, one per surface. There are no named tiers. -| Surface | Covers | Anonymous limit today | Column on the key | -| ------- | -------------------------------------- | ------------------------------ | ----------------- | -| API | `/api/v1/*`, `/openapi.json`, `/codes` | 120 calls a minute per address | `api_limit` | -| MCP | `/mcp` | 300 calls a minute per address | `mcp_limit` | +| Surface | Covers | Anonymous limit today | Setting on the key | +| ------- | -------------------------------------- | ------------------------------ | ------------------ | +| API | `/api/v1/*`, `/openapi.json`, `/codes` | 120 calls a minute per address | `api_limit` | +| MCP | `/mcp` | 300 calls a minute per address | `mcp_limit` | -- Each column is a nullable integer, in calls per window. +- Each setting is an optional integer, in calls per window. - Empty means the default for keyed callers, set per deployment in env (for example `RATE_LIMIT_API_KEYED` and `RATE_LIMIT_MCP_KEYED`). Most keys store nothing, and raising the default moves them all at once. - A number overrides the default for that key. - The window stays global at 60 seconds (`RATE_LIMIT_WINDOW_S`). There is no per-key window. @@ -141,20 +135,7 @@ Not covered by a key's limits: - The proxy's third allowance, `/api/download-pin` at 10 calls a minute, belongs to the site's download UI and is not part of the public API. - The Studio's daily prompt allowance is for the site's own chat UI. -- dfo-apis keeps its own daily allowances per caller: 10 shares and 500 presentation cards, plus pins. A keyed caller gets these at the default values. Raising them for a partner would be a dfo-apis setting, not a column here. - -### The Proxy Check - -In `forward()`, before the rate limit: - -1. Read the key header. No header: carry on as an anonymous caller. -2. Hash the key and look it up, through a short in-process cache (about 60 seconds) so a keyed call adds no query in the common case. -3. Unknown or revoked key: answer 401 with a problem document. It does not fall back to anonymous, so a caller finds out their key is dead. -4. Valid key: count the call against `key:` at the key's limit, using the existing counter. - -A revoked key can keep working until the cache entry expires, so revocation takes up to a minute per instance. If the key lookup itself fails, the proposal is to treat the call as anonymous, in line with the limiter failing open. - -A keyed call is named to the backends as `x-dfo-caller: key:` instead of `ip:`. dfo-ai already expects that form. dfo-apis needs a small change to accept it, so its own allowances count per key and not per address. +- dfo-apis keeps its own daily allowances per caller: 10 shares and 500 presentation cards, plus pins. A keyed caller gets these at the default values. Raising them for a partner would be a dfo-apis setting, not a setting on the key. ### Cloudflare Integration @@ -198,6 +179,112 @@ Which option applies depends on the zone's plan and its current rules. See [Open - The request log line carries the key caller, so usage per key can be counted in Cloud Logging. This is what Phase 3 needs to find high-volume callers. - `/openapi.json` gains an optional security scheme, and the API and MCP docs explain keys. +## Build + +In this option we own the key store: a table in the website's Postgres, a lookup in the proxy, and an admin command. Nothing new is installed. + +### Storage + +A new `api_key` table in the website's Postgres, beside the accounts and the limit counters. + +| Column | Purpose | +| ------------------------------------ | --------------------------------------------------------------------------- | +| id | Short public identifier, used in logs and as the caller name | +| key_hash | SHA-256 of the key, unique | +| prefix | First characters of the key, so its owner can recognize it in a list | +| label | What the key is for | +| user_id | Owning account. Empty for a manually provisioned key in Phase 1 | +| api_limit, mcp_limit | Calls per window on each surface. Empty means the default for keyed callers | +| created_at, revoked_at, last_used_at | Lifecycle | + +Postgres rather than Redis: the limiter already counts there, key volume is small, and it adds no new infrastructure. This can be changed later if we need something more scalable and performant at the cost of some additional dev and operational complexity. + +### The Proxy Check + +In `forward()`, before the rate limit: + +1. Read the key header. No header: carry on as an anonymous caller. +2. Hash the key and look it up, through a short in-process cache (about 60 seconds) so a keyed call adds no query in the common case. +3. Unknown or revoked key: answer 401 with a problem document. It does not fall back to anonymous, so a caller finds out their key is dead. +4. Valid key: count the call against `key:` at the key's limit, using the existing counter. + +A revoked key can keep working until the cache entry expires, so revocation takes up to a minute per instance. If the key lookup itself fails, the proposal is to treat the call as anonymous, in line with the limiter failing open. + +A keyed call is named to the backends as `x-dfo-caller: key:` instead of `ip:`. dfo-ai already expects that form. dfo-apis needs a small change to accept it, so its own allowances count per key and not per address. + +### Future Work: Admin Interface + +Phase 1 has only an admin command that creates and revokes keys and sets their limits. Later phases need more, and all of it would be ours to build: + +- Self-service pages in the account menu to create, label and revoke keys and see last use, with the endpoints and ownership checks behind them (Phase 2). +- An operator view to find a key, see its usage, and raise or cut its limits (Phase 3). +- Expiry and multiple keys per account, if we take them up from [Future Features][]. + +## Use: Better Auth API Key Plugin + +In this option the key store is the [API key plugin][better-auth-api-key] of Better Auth, the library that already handles sign-in on the site. It is a separate package, `@better-auth/api-key`, and is not installed today (the site has `better-auth` 1.7.7). Keys live in our own Postgres, in a table the plugin defines. No third-party service is involved. + +### What the Plugin Provides + +| Area | What it does | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------- | +| Storage | An `apikey` table. Keys are hashed by default, and the first characters are kept so an owner can recognize a key | +| Key format | A configurable prefix and length (64 characters by default), or our own generator | +| Create, list, update, delete | Server methods and matching client methods. A signed-in user can manage only their own keys | +| Verify | `auth.api.verifyApiKey({ key })` returns whether the key is valid, why not, and the key's record without the secret | +| Ownership | Every key belongs to a user, or to an organization if we adopt that plugin. A user can hold several keys | +| Expiry | Optional per key, with expired keys removed automatically | +| Rate limit | One limit per key: a window and a maximum, counted on the key's row at each verification | +| Quotas | An optional count of remaining requests per key, with periodic refill | +| Metadata | Free-form data per key, for example a plan name | +| Header | Reads `x-api-key` by default. Other headers, or a function that extracts the key, can be configured | + +### How It Would Fit + +- **Proxy check.** The steps in [The Proxy Check][] stay the same, with the lookup replaced by `verifyApiKey`. We would keep the short in-process cache, because the plugin writes to the key's row on each verification unless updates are deferred. +- **Header.** A small getter reads `Authorization: Bearer dfo_…` and `X-API-Key`, so [Key Format and Communication][] holds as written. +- **Limits.** Our design has two limits per key, one per surface, and the plugin has one. We would turn the plugin's limiter off, keep counting in `limit_counter`, and hold the two numbers in the key's metadata. The alternative is to move to one limit per key. +- **Ownership.** A hand-provisioned Phase 1 key needs an account to belong to. We would create one for the partner, or for ourselves on their behalf. +- **Caller name.** The plugin's key id becomes the `` in `x-dfo-caller: key:`. +- **Schema.** The plugin's table is added through our existing migrations, as the auth tables were. + +### Admin System + +There is no admin interface to leverage. This was checked in three places: + +| Candidate | What it is | Does it manage API keys? | +| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| The API key plugin itself | Server and client methods only | It has the operations, but no pages. Listing returns the signed-in user's own keys, so an operator view across all keys would query the table directly | +| [Better Auth admin plugin][better-auth-admin] | User administration: list and edit users, roles, bans, sessions, impersonation | No. It has no pages either, only methods, and it does not cover API keys | +| [Better Auth Infrastructure dashboard][better-auth-dash] | A hosted dashboard from the Better Auth company, fed by a plugin that sends user and session events to their service | Not documented. It would also send account activity to a third party | + +So an admin command, and later an operator view, are ours to write in either option. With the plugin, they are thin wrappers over its server methods instead of our own queries. A community library, better-auth-ui, has ready-made components for a user's own keys, which could shorten the Phase 2 self-service pages. It has not been evaluated. + +### What It Saves and What It Costs + +Saves: + +- Key generation, hashing and comparison, which are the security-sensitive parts. +- The create, list, update and delete endpoints with ownership checks, which Phase 2 needs. +- Expiry and multiple keys per account, both listed under [Future Features][]. + +Costs: + +- A dependency in the path of every keyed request, on a package that has changed recently: it moved to its own package, and its owner column was renamed. +- A second limiter we would switch off, and limits kept in metadata instead of typed columns. +- Every key must have an owning account. +- Less control over the table's shape, and upgrades that may bring migrations. + +### Spike Before Deciding + +A day or two should answer these. Any "no" sends us to [Build][]. + +- [ ] Does `@better-auth/api-key` work with the site's `better-auth` 1.7.7 and its Drizzle migrations? +- [ ] Can verification run without a database write per request, or is the write cheap enough behind our cache? +- [ ] Does a getter for `Authorization: Bearer` work alongside the plugin's own endpoints? +- [ ] Is the stored hash a plain SHA-256 of the key, so keys could be moved to or from our own table? +- [ ] Can an operator set a key's metadata and limits for another user's key from the server? + ## Phases Three phases take keys from an optional test feature to the normal way heavy users reach the API. Anonymous access stays open throughout. @@ -216,7 +303,7 @@ Three phases take keys from an optional test feature to the normal way heavy use **Anonymous access:** Unchanged -**Also needed:** Proxy check, `api_key` table, dfo-apis accepts `key:` callers, per-key usage in logs +**Also needed:** Proxy check, key table, dfo-apis accepts `key:` callers, per-key usage in logs **Exit criteria:** The first partner runs on a key in production without incident, and per-key counts in the logs match what they report sending. @@ -254,28 +341,27 @@ Phase 1 should avoid choices that Phase 2 has to undo. The table has an owner co ## Work by Repository -Most of the work is in the website. The Phase 1 pieces: +Most of the work is in the website. This split holds for both options: Build and Use differ only in the website row, in where keys are stored and how they are looked up. The dfo-apis, dfo-ai and Cloudflare rows are the same either way, since those systems see only the `key:` caller name and the key header. The Phase 1 pieces: -| Where | Size | What | -| ---------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| website | Most of it | `api_key` table and migration; key check and per-key limit in `forward()`; admin command to create and revoke; key caller in the request log; OpenAPI security scheme; docs; tests beside the existing proxy tests | -| dfo-apis | Small | Accept `x-dfo-caller: key:` beside the website's shared secret, so allowances count per key. Today only `ip:` is accepted | -| dfo-ai | Little or none | Confirm a `key:` caller flows through `/mcp` to the MCP servers; add a test if none covers it | -| Cloudflare | Configuration | The WAF rate rules count by address. A keyed caller on a few addresses could hit them before reaching its key's limit | +| Where | Size | What | +| ---------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| website | Most of it | Key table and migration (our own `api_key`, or the plugin's); key check and per-key limit in `forward()`; admin command to create and revoke; key caller in the request log; OpenAPI security scheme; docs; tests beside the existing proxy tests | +| dfo-apis | Small | Accept `x-dfo-caller: key:` beside the website's shared secret, so allowances count per key. Today only `ip:` is accepted | +| dfo-ai | Little or none | Confirm a `key:` caller flows through `/mcp` to the MCP servers; add a test if none covers it | +| Cloudflare | Configuration | The WAF rate rules count by address. A keyed caller on a few addresses could hit them before reaching its key's limit | Order matters between the website and dfo-apis. dfo-apis refuses a caller form it does not recognize when it arrives with the shared secret, so the dfo-apis change has to be live before the website starts sending `key:` callers. ## Alternatives Considered -We looked at buying or reusing this instead of building it. The plan stays to build, because the hard parts are already in the proxy: one function every call passes through, a shared limiter in Postgres, and caller naming to the backends. What is left to build is a table, a lookup and an admin command. One option, Better Auth's plugin, is worth a closer look before Phase 2. +Besides [Build][] and [Use][Use: Better Auth API Key Plugin] above, we looked at buying this outright. None of these fit as well, because the hard parts are already in the proxy: one function every call passes through, a shared limiter in Postgres, and caller naming to the backends. -| Option | What it is | What it would give us | Why not, or not yet | -| ------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Better Auth API key plugin][better-auth-api-key] | An add-on package (`@better-auth/api-key`) for the auth library the site already uses | Key creation and verification, per-key rate limits, expiry, usage quotas with refill, metadata, and client methods for create, list and revoke, in our own Postgres | The closest fit, and more a reuse than a buy. Open points: whether keys can exist without an owning account (Phase 1 keys have none), whether its rate limiter can share our `limit_counter` window and headers, and how it stores keys. Worth evaluating as the base for Phase 2 self-service | -| Hosted key service, for example [Unkey][unkey] | A service that issues and verifies keys; the proxy calls it on each request | Key management, per-key limits and usage analytics with no tables of our own. A free tier of 150,000 verifications a month | A network call to a third party on every keyed request, and a new vendor holding our callers' keys. Cost grows with traffic, which is the thing we are trying to control | -| Hosted API gateway, for example [Zuplo][zuplo] | A managed gateway in front of the APIs, with keys, rate limits and a developer portal | The whole feature, including self-service sign-up and docs | It replaces the proxy we already have. Streaming (SSE and MCP), caller naming and the harness token would all need to be rebuilt in its terms | -| Google Cloud API Gateway or Apigee | Google's gateways, in the cloud the backends already run in | API Gateway: keys and quotas. Apigee: a full product with developer portal and monetization | API Gateway keys are Google Cloud API keys, which suits internal consumers more than outside sign-ups. Apigee is priced and sized for a larger API program than ours | -| Cloudflare | Already in front of the site | Edge rate limiting per key header on the Enterprise Advanced Rate Limiting plan | It does not issue or validate keys, so it cannot replace the proxy check. See [Cloudflare Integration][] | +| Option | What it is | What it would give us | Why not, or not yet | +| ---------------------------------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Hosted key service, for example [Unkey][unkey] | A service that issues and verifies keys; the proxy calls it on each request | Key management, per-key limits and usage analytics with no tables of our own. A free tier of 150,000 verifications a month | A network call to a third party on every keyed request, and a new vendor holding our callers' keys. Cost grows with traffic, which is the thing we are trying to control | +| Hosted API gateway, for example [Zuplo][zuplo] | A managed gateway in front of the APIs, with keys, rate limits and a developer portal | The whole feature, including self-service sign-up and docs | It replaces the proxy we already have. Streaming (SSE and MCP), caller naming and the harness token would all need to be rebuilt in its terms | +| Google Cloud API Gateway or Apigee | Google's gateways, in the cloud the backends already run in | API Gateway: keys and quotas. Apigee: a full product with developer portal and monetization | API Gateway keys are Google Cloud API keys, which suits internal consumers more than outside sign-ups. Apigee is priced and sized for a larger API program than ours | +| Cloudflare | Already in front of the site | Edge rate limiting per key header on the Enterprise Advanced Rate Limiting plan | It does not issue or validate keys, so it cannot replace the proxy check. See [Cloudflare Integration][] | If monetization becomes real, the calculation changes: metering, billing and a developer portal are where the gateway products earn their cost. Nothing in this design blocks moving to one later, since keys are checked in one place. @@ -303,15 +389,25 @@ The Cloudflare question needs an answer before Phase 1 code is written. [better-auth-api-key]: https://www.better-auth.com/docs/plugins/api-key [unkey]: https://www.unkey.com/docs/platform/workspaces/billing [zuplo]: https://zuplo.com/pricing +[better-auth-admin]: https://www.better-auth.com/docs/plugins/admin +[better-auth-dash]: https://better-auth.com/docs/infrastructure/plugins/dash [Summary]: #summary [How It Works Today]: #how-it-works-today -[Design]: #design +[Requirements]: #requirements [Key Format and Communication]: #key-format-and-communication -[Storage]: #storage [Limits]: #limits -[The Proxy Check]: #the-proxy-check [Cloudflare Integration]: #cloudflare-integration [Logs and Docs]: #logs-and-docs +[Build]: #build +[Storage]: #storage +[The Proxy Check]: #the-proxy-check +[Future Work: Admin Interface]: #future-work-admin-interface +[Use: Better Auth API Key Plugin]: #use-better-auth-api-key-plugin +[What the Plugin Provides]: #what-the-plugin-provides +[How It Would Fit]: #how-it-would-fit +[Admin System]: #admin-system +[What It Saves and What It Costs]: #what-it-saves-and-what-it-costs +[Spike Before Deciding]: #spike-before-deciding [Phases]: #phases [Phase 1: Validate]: #phase-1-validate [Phase 2: Provision]: #phase-2-provision From 043341fe7a164b8063390688ab9a78b0c3041f28 Mon Sep 17 00:00:00 2001 From: Sef Kloninger Date: Fri, 13 Nov 2026 16:53:14 -0800 Subject: [PATCH 12/34] docs(design): give each API key one rate limit One number per key, applied to each surface separately, replaces the separate API and MCP limits. A separate MCP limit per key moves to Future Features. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf --- docs/design/api-keys.md | 53 +++++++++++++++++++++++------------------ 1 file changed, 30 insertions(+), 23 deletions(-) diff --git a/docs/design/api-keys.md b/docs/design/api-keys.md index dfc99ec..f6c1f2b 100644 --- a/docs/design/api-keys.md +++ b/docs/design/api-keys.md @@ -117,25 +117,31 @@ So a key on `/mcp` serves programmatic and developer use. Chat-app users stay an ### Limits -A key's limit is two plain numbers, one per surface. There are no named tiers. +A key's limit is one plain number, in calls per window. There are no named tiers. -| Surface | Covers | Anonymous limit today | Setting on the key | -| ------- | -------------------------------------- | ------------------------------ | ------------------ | -| API | `/api/v1/*`, `/openapi.json`, `/codes` | 120 calls a minute per address | `api_limit` | -| MCP | `/mcp` | 300 calls a minute per address | `mcp_limit` | +The number applies to each surface separately. A key with a limit of 200 can make 200 calls a minute on the API and 200 a minute on MCP, and heavy use of one does not use up the other. -- Each setting is an optional integer, in calls per window. -- Empty means the default for keyed callers, set per deployment in env (for example `RATE_LIMIT_API_KEYED` and `RATE_LIMIT_MCP_KEYED`). Most keys store nothing, and raising the default moves them all at once. +| Surface | Covers | Anonymous limit today | Keyed limit | +| ------- | -------------------------------------- | ------------------------------ | --------------- | +| API | `/api/v1/*`, `/openapi.json`, `/codes` | 120 calls a minute per address | The key's limit | +| MCP | `/mcp` | 300 calls a minute per address | The key's limit | + +- The limit is an optional integer on the key. +- Empty means the default for keyed callers, set per deployment in env (for example `RATE_LIMIT_KEYED`). Most keys store nothing, and raising the default moves them all at once. - A number overrides the default for that key. - The window stays global at 60 seconds (`RATE_LIMIT_WINDOW_S`). There is no per-key window. -This is all on the admin side. If we later want tiers, for single or bulk changes to keys, they can be added as a column or as a bulk update over these two numbers without changing what the numbers mean. +One number is simpler to explain to a key holder, simpler to administer, and fits Better Auth's plugin, which has one limit per key. The anonymous limits differ by surface because chat vendors send many users from one address. That does not apply to a key, which is one caller. + +What this gives up is setting a key's MCP limit apart from its API limit. MCP can be a significant cost driver, so a separate MCP limit is listed under [Future Features][]. It can be added later as a second optional number without disturbing existing keys. + +This is all on the admin side. If we later want tiers, for single or bulk changes to keys, they can be added as a column or as a bulk update over this number without changing what it means. Not covered by a key's limits: - The proxy's third allowance, `/api/download-pin` at 10 calls a minute, belongs to the site's download UI and is not part of the public API. - The Studio's daily prompt allowance is for the site's own chat UI. -- dfo-apis keeps its own daily allowances per caller: 10 shares and 500 presentation cards, plus pins. A keyed caller gets these at the default values. Raising them for a partner would be a dfo-apis setting, not a setting on the key. +- dfo-apis keeps its own daily allowances per caller: 10 shares and 500 presentation cards, plus pins. A keyed caller gets these at the default values. Raising them for a partner would be a dfo-apis setting, not part of the key's limit. ### Cloudflare Integration @@ -187,15 +193,15 @@ In this option we own the key store: a table in the website's Postgres, a lookup A new `api_key` table in the website's Postgres, beside the accounts and the limit counters. -| Column | Purpose | -| ------------------------------------ | --------------------------------------------------------------------------- | -| id | Short public identifier, used in logs and as the caller name | -| key_hash | SHA-256 of the key, unique | -| prefix | First characters of the key, so its owner can recognize it in a list | -| label | What the key is for | -| user_id | Owning account. Empty for a manually provisioned key in Phase 1 | -| api_limit, mcp_limit | Calls per window on each surface. Empty means the default for keyed callers | -| created_at, revoked_at, last_used_at | Lifecycle | +| Column | Purpose | +| ------------------------------------ | ------------------------------------------------------------------------------------ | +| id | Short public identifier, used in logs and as the caller name | +| key_hash | SHA-256 of the key, unique | +| prefix | First characters of the key, so its owner can recognize it in a list | +| label | What the key is for | +| user_id | Owning account. Empty for a manually provisioned key in Phase 1 | +| rate_limit | Calls per window, applied to each surface. Empty means the default for keyed callers | +| created_at, revoked_at, last_used_at | Lifecycle | Postgres rather than Redis: the limiter already counts there, key volume is small, and it adds no new infrastructure. This can be changed later if we need something more scalable and performant at the cost of some additional dev and operational complexity. @@ -206,7 +212,7 @@ In `forward()`, before the rate limit: 1. Read the key header. No header: carry on as an anonymous caller. 2. Hash the key and look it up, through a short in-process cache (about 60 seconds) so a keyed call adds no query in the common case. 3. Unknown or revoked key: answer 401 with a problem document. It does not fall back to anonymous, so a caller finds out their key is dead. -4. Valid key: count the call against `key:` at the key's limit, using the existing counter. +4. Valid key: count the call against `key:` at the key's limit, using the existing counter, which already counts each surface separately. A revoked key can keep working until the cache entry expires, so revocation takes up to a minute per instance. If the key lookup itself fails, the proposal is to treat the call as anonymous, in line with the limiter failing open. @@ -243,7 +249,7 @@ In this option the key store is the [API key plugin][better-auth-api-key] of Bet - **Proxy check.** The steps in [The Proxy Check][] stay the same, with the lookup replaced by `verifyApiKey`. We would keep the short in-process cache, because the plugin writes to the key's row on each verification unless updates are deferred. - **Header.** A small getter reads `Authorization: Bearer dfo_…` and `X-API-Key`, so [Key Format and Communication][] holds as written. -- **Limits.** Our design has two limits per key, one per surface, and the plugin has one. We would turn the plugin's limiter off, keep counting in `limit_counter`, and hold the two numbers in the key's metadata. The alternative is to move to one limit per key. +- **Limits.** The plugin has one limit per key, as our design does. Its per-key maximum field holds our number. We would still turn the plugin's own limiter off and keep counting in `limit_counter`: ours fails open on a slow database, lets verification sit behind the cache, emits the `X-RateLimit-*` headers, and is the limiter anonymous traffic uses anyway. - **Ownership.** A hand-provisioned Phase 1 key needs an account to belong to. We would create one for the partner, or for ourselves on their behalf. - **Caller name.** The plugin's key id becomes the `` in `x-dfo-caller: key:`. - **Schema.** The plugin's table is added through our existing migrations, as the auth tables were. @@ -271,7 +277,7 @@ Saves: Costs: - A dependency in the path of every keyed request, on a package that has changed recently: it moved to its own package, and its owner column was renamed. -- A second limiter we would switch off, and limits kept in metadata instead of typed columns. +- A second limiter that we would switch off. - Every key must have an owning account. - Less control over the table's shape, and upgrades that may bring migrations. @@ -283,7 +289,7 @@ A day or two should answer these. Any "no" sends us to [Build][]. - [ ] Can verification run without a database write per request, or is the write cheap enough behind our cache? - [ ] Does a getter for `Authorization: Bearer` work alongside the plugin's own endpoints? - [ ] Is the stored hash a plain SHA-256 of the key, so keys could be moved to or from our own table? -- [ ] Can an operator set a key's metadata and limits for another user's key from the server? +- [ ] Can an operator set the limit on another user's key from the server, and can the proxy read that number while the plugin's own limiter is off? ## Phases @@ -337,7 +343,7 @@ Three phases take keys from an optional test feature to the normal way heavy use **Also needed:** Usage reports by caller, a playbook for lowering a limit and rolling it back, edge rules that respect keys -Phase 1 should avoid choices that Phase 2 has to undo. The table has an owner column from the start, and limits are stored per key in a form a tier can replace. +Phase 1 should avoid choices that Phase 2 has to undo. The table has an owner column from the start, and the limit is stored per key in a form a tier can replace. ## Work by Repository @@ -371,6 +377,7 @@ Not planned for any phase yet. The design should not rule them out. - **Expiring keys.** A key carries an expiry date and stops working after it. Until then a key lives until it is revoked. - **Multiple keys per account.** An account holds several keys at once, for example one per application or to rotate a key without downtime. +- **A separate MCP limit per key.** A second optional number that sets a key's limit on `/mcp` apart from its limit on the API. MCP calls can cost much more than API calls, so this is the first refinement we expect to want. Keys without it keep using their one limit on both surfaces. - **More graceful degradation besides limits.** Depending on how often limits are hit, and the user impact of that, we could have fancier throttles in the future: - Soft vs. hard limits (warnings) - Hourly vs. weekly limits, like how modern chat interfaces work. This protects against spiky workloads while mitigating the impact of hitting a limit ("try again in a few hours"). From 12eb7f116acaf2f0f0753333461c3e136a4b02c6 Mon Sep 17 00:00:00 2001 From: Sef Kloninger Date: Fri, 13 Nov 2026 17:35:40 -0800 Subject: [PATCH 13/34] docs(design): revise API keys design after a review with Codex (#142) Recommend building Phase 1 on our own key table behind a verifier and deciding on Better Auth's plugin at Phase 2 planning. Add where keys apply, one resolved identity per request, limits on invalid-key attempts, revocation and emergency-switch rules, and the open choice between anonymous and 503 when the key store is unavailable. Correct the dfo-ai work (its MCP servers drop non-ip callers) and the rollout order, and record the static-list alternative. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf --- docs/design/api-keys.md | 117 +++++++++++++++++++++++++--------------- 1 file changed, 74 insertions(+), 43 deletions(-) diff --git a/docs/design/api-keys.md b/docs/design/api-keys.md index f6c1f2b..951c8b1 100644 --- a/docs/design/api-keys.md +++ b/docs/design/api-keys.md @@ -12,6 +12,8 @@ Last Update: Nov 13, 2026 - [Key Format and Communication][] - [Limits][] - [Cloudflare Integration][] + - [Where Keys Apply][] + - [Identity, Failure and Abuse][] - [Logs and Docs][] - [Build][] - [Storage][] @@ -50,7 +52,7 @@ Requirements: - Each key carries its own rate limit. - Some MCP features may later require sign-in. That is separate from keys and out of scope here. -**Recommendation (tentative).** There are two ways to get this: [build][Build] the key store ourselves, or [use][Use: Better Auth API Key Plugin] the API key plugin of Better Auth, the library that already handles sign-in on the site. We lean toward using the plugin for key storage and management, while keeping our own rate limiter and proxy check. It saves writing security-sensitive code and brings expiry, multiple keys per account and self-service endpoints that Phase 2 needs. We are not sure yet. A short spike should settle it before Phase 1 code starts, because moving existing keys between the two stores later may mean reissuing them. If the spike fails any of its checks, we build. +**Recommendation.** Build Phase 1 on a small key table of our own, behind a verifier that hides where keys are stored. Decide whether to move key management to Better Auth's API key plugin when Phase 2 is planned, with a spike at that point. The plugin's saving is the self-service endpoints Phase 2 needs. Everything on the request path (the proxy check, the limiter, caching and logging) is ours in either option, so Phase 1 gains little from it. This is where a design review with Codex ended up, after two rounds. The earlier lean was toward the plugin from the start. See [Build][], [Use: Better Auth API Key Plugin][] and [Alternatives Considered][]. We'll take a phased approach. Initially we'll prove the concept with hand-provisioned keys and limited features. Once this is proven in production, follow-on work will enable more features, self-service provisioning, and admin interfaces to adjust access and limits. @@ -180,14 +182,35 @@ Below Enterprise, a rate limiting rule's own match expression cannot reference r Which option applies depends on the zone's plan and its current rules. See [Open Questions][]. +### Where Keys Apply + +| Surface | Key honored? | Notes | +| -------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `/api/v1/search`, `datasets`, `graph`, `presentation`; `/openapi.json`; `/codes` | Yes | Counted on the API surface | +| `/mcp` | Yes | Counted on the MCP surface. Where the proxy holds no harness token, a `dfo_` bearer leaves no credential for the harness, so a keyed call there must send the key as `X-API-Key` and the harness token as the bearer | +| `/api/v1/studio/*` | No | The Studio is the site's own chat UI. A key never replaces or bypasses its daily prompt allowance. A key sent there is removed and otherwise ignored | +| `/api/download-pin`, MCP theme stylesheets | No | These do not pass through the key check today and stay as they are | + +On every surface, a `dfo_` bearer is consumed by the proxy and never copied upstream, including when verification fails. Other `Authorization` values are handled as they are today. + +### Identity, Failure and Abuse + +- **One identity per request.** The proxy resolves the caller once, as an address or a key, before the limiter runs. That one identity is used for counting, for `x-dfo-caller` to both dfo-apis and dfo-ai, and for logging. Today the MCP route, the dfo-apis path and the request log each work out the caller separately. +- **Invalid keys.** An unknown or revoked key gets a 401 and does not fall back to anonymous. Attempts are held to a budget per address that is checked before the key store is touched, so random keys cannot force unlimited lookups. Keys over a maximum length are refused unread, and unknown keys are cached briefly as unknown. +- **Revocation.** A revoked key stops being admitted within the cache lifetime, about a minute per instance. The lifetime is absolute and is not extended when the store is unreachable. Revoking stops new calls. It does not cut a stream that is already open. Lowering a key's limit takes effect on the same delay. +- **Emergency switch.** An operator can turn off one key, or all keyed access, without a deploy. How quickly that reaches every instance has to be stated when it is built. +- **Key store unavailable.** A key already in the cache keeps working until its entry expires. For a key not in the cache there are two positions, and this needs a decision (see [Open Questions][]). The original proposal was to treat the call as anonymous, in line with the limiter failing open. Codex argued for a 503: a revoked or made-up key would otherwise be served as an anonymous caller, and a partner would see rate-limit errors at the anonymous limit with no sign of why. A caller who wants anonymous access can leave the key out. The lookup gets its own bounded pool and timeout, as the counter has. + ### Logs and Docs -- The request log line carries the key caller, so usage per key can be counted in Cloud Logging. This is what Phase 3 needs to find high-volume callers. +- Usage per key is counted from a log line that carries the key's public id, the surface and the outcome, and never the key or its hash. The existing request log works the caller out from raw headers when the response closes, apart from `forward()`, so it has to be given the verified identity or be joined by a dedicated usage event. This is what the Phase 1 exit criterion and Phase 3's search for high-volume callers rely on. - `/openapi.json` gains an optional security scheme, and the API and MCP docs explain keys. ## Build -In this option we own the key store: a table in the website's Postgres, a lookup in the proxy, and an admin command. Nothing new is installed. +In this option we own the key store: a table in the website's Postgres, a lookup in the proxy, and an admin command. Nothing new is installed. This is the plan for Phase 1. + +The proxy reaches the store through a small verifier: it takes a key and answers with the key's public id, limit and owner, or says the key is invalid, or says the store is unavailable. Nothing else in the proxy knows where keys live, so the store can change later. Public ids stay the same if it does. ### Storage @@ -201,22 +224,22 @@ A new `api_key` table in the website's Postgres, beside the accounts and the lim | label | What the key is for | | user_id | Owning account. Empty for a manually provisioned key in Phase 1 | | rate_limit | Calls per window, applied to each surface. Empty means the default for keyed callers | -| created_at, revoked_at, last_used_at | Lifecycle | +| created_at, revoked_at, last_used_at | Lifecycle. `last_used_at` is updated occasionally, not on every call | Postgres rather than Redis: the limiter already counts there, key volume is small, and it adds no new infrastructure. This can be changed later if we need something more scalable and performant at the cost of some additional dev and operational complexity. ### The Proxy Check -In `forward()`, before the rate limit: +Before the rate limit, on the surfaces in [Where Keys Apply][]: 1. Read the key header. No header: carry on as an anonymous caller. -2. Hash the key and look it up, through a short in-process cache (about 60 seconds) so a keyed call adds no query in the common case. -3. Unknown or revoked key: answer 401 with a problem document. It does not fall back to anonymous, so a caller finds out their key is dead. -4. Valid key: count the call against `key:` at the key's limit, using the existing counter, which already counts each surface separately. +2. Check the address's budget for key attempts, then hash the key and look it up through a short in-process cache (about 60 seconds), so a keyed call adds no query in the common case. Lookup is by the hash, so no secret is compared by hand. +3. Unknown or revoked key: answer 401 with a problem document. +4. Valid key: count the call against `key:` at the key's limit, using the existing counter, which already counts each surface separately. The counter's entry point takes an address and a fixed limit today and needs to accept a caller and a limit. -A revoked key can keep working until the cache entry expires, so revocation takes up to a minute per instance. If the key lookup itself fails, the proposal is to treat the call as anonymous, in line with the limiter failing open. +[Identity, Failure and Abuse][] covers revocation delay and what happens when the store is unavailable. -A keyed call is named to the backends as `x-dfo-caller: key:` instead of `ip:`. dfo-ai already expects that form. dfo-apis needs a small change to accept it, so its own allowances count per key and not per address. +A keyed call is named to the backends as `x-dfo-caller: key:` instead of `ip:`. dfo-apis accepts only the `ip:` form today. dfo-ai accepts a `key:` caller on arrival, but its MCP servers drop any caller that is not `ip:` before they call dfo-apis. Both need a change, so allowances count per key and not per address. See [Work by Repository][]. ### Future Work: Admin Interface @@ -228,28 +251,28 @@ Phase 1 has only an admin command that creates and revokes keys and sets their l ## Use: Better Auth API Key Plugin -In this option the key store is the [API key plugin][better-auth-api-key] of Better Auth, the library that already handles sign-in on the site. It is a separate package, `@better-auth/api-key`, and is not installed today (the site has `better-auth` 1.7.7). Keys live in our own Postgres, in a table the plugin defines. No third-party service is involved. +In this option the key store is the [API key plugin][better-auth-api-key] of Better Auth, the library that already handles sign-in on the site. It is a separate package, `@better-auth/api-key`, and is not installed today (the site has `better-auth` 1.7.7). Keys live in our own Postgres, in a table the plugin defines. No third-party service is involved. This is a decision for Phase 2 planning, when self-service is scheduled. It would sit behind the same verifier as the Build store. ### What the Plugin Provides -| Area | What it does | -| ---------------------------- | ------------------------------------------------------------------------------------------------------------------- | -| Storage | An `apikey` table. Keys are hashed by default, and the first characters are kept so an owner can recognize a key | -| Key format | A configurable prefix and length (64 characters by default), or our own generator | -| Create, list, update, delete | Server methods and matching client methods. A signed-in user can manage only their own keys | -| Verify | `auth.api.verifyApiKey({ key })` returns whether the key is valid, why not, and the key's record without the secret | -| Ownership | Every key belongs to a user, or to an organization if we adopt that plugin. A user can hold several keys | -| Expiry | Optional per key, with expired keys removed automatically | -| Rate limit | One limit per key: a window and a maximum, counted on the key's row at each verification | -| Quotas | An optional count of remaining requests per key, with periodic refill | -| Metadata | Free-form data per key, for example a plan name | -| Header | Reads `x-api-key` by default. Other headers, or a function that extracts the key, can be configured | +| Area | What it does | +| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| Storage | An `apikey` table. Keys are hashed by default, and the first characters are kept so an owner can recognize a key | +| Key format | A configurable prefix and length (64 characters by default), or our own generator | +| Create, list, update, delete | Server methods and matching client methods. A signed-in user can manage only their own keys | +| Verify | `auth.api.verifyApiKey({ body: { key } })` returns whether the key is valid, why not, and the key's record without the secret | +| Ownership | Every key belongs to a user, or to an organization if we adopt that plugin. A user can hold several keys | +| Expiry | Optional per key, with expired keys removed automatically | +| Rate limit | One limit per key: a window and a maximum, counted on the key's row at each verification | +| Quotas | An optional count of remaining requests per key, with periodic refill | +| Metadata | Free-form data per key, for example a plan name | +| Header | Reads `x-api-key` by default. Other headers, or a function that extracts the key, can be configured | ### How It Would Fit - **Proxy check.** The steps in [The Proxy Check][] stay the same, with the lookup replaced by `verifyApiKey`. We would keep the short in-process cache, because the plugin writes to the key's row on each verification unless updates are deferred. - **Header.** A small getter reads `Authorization: Bearer dfo_…` and `X-API-Key`, so [Key Format and Communication][] holds as written. -- **Limits.** The plugin has one limit per key, as our design does. Its per-key maximum field holds our number. We would still turn the plugin's own limiter off and keep counting in `limit_counter`: ours fails open on a slow database, lets verification sit behind the cache, emits the `X-RateLimit-*` headers, and is the limiter anonymous traffic uses anyway. +- **Limits.** The plugin has one limit per key, as our design does. Its per-key maximum field can hold our number. A variant keeps limits and public ids in a small table of our own beside the plugin's, which avoids leaning on a field of a limiter we have switched off. Either way we would turn the plugin's own limiter off and keep counting in `limit_counter`: ours fails open on a slow database, lets verification sit behind the cache, emits the `X-RateLimit-*` headers, and is the limiter anonymous traffic uses anyway. - **Ownership.** A hand-provisioned Phase 1 key needs an account to belong to. We would create one for the partner, or for ourselves on their behalf. - **Caller name.** The plugin's key id becomes the `` in `x-dfo-caller: key:`. - **Schema.** The plugin's table is added through our existing migrations, as the auth tables were. @@ -283,12 +306,15 @@ Costs: ### Spike Before Deciding -A day or two should answer these. Any "no" sends us to [Build][]. +Run this when Phase 2 is planned. A day or two should answer these. Any "no" means Phase 2 extends the Build store instead. - [ ] Does `@better-auth/api-key` work with the site's `better-auth` 1.7.7 and its Drizzle migrations? - [ ] Can verification run without a database write per request, or is the write cheap enough behind our cache? - [ ] Does a getter for `Authorization: Bearer` work alongside the plugin's own endpoints? -- [ ] Is the stored hash a plain SHA-256 of the key, so keys could be moved to or from our own table? +- [ ] Can the Phase 1 keys be carried over, by converting our stored hashes to the plugin's form, or would the few Phase 1 holders be issued new keys? +- [ ] Can a signed-in user reach only their own keys, and are they unable to raise their own limit? +- [ ] What happens to an account's keys when the account is deleted, and when a key expires while it is in our cache? +- [ ] Do the plugin's errors let us tell an invalid key from an unavailable store? - [ ] Can an operator set the limit on another user's key from the server, and can the proxy read that number while the plugin's own limiter is off? ## Phases @@ -309,7 +335,7 @@ Three phases take keys from an optional test feature to the normal way heavy use **Anonymous access:** Unchanged -**Also needed:** Proxy check, key table, dfo-apis accepts `key:` callers, per-key usage in logs +**Also needed:** Proxy check behind a verifier, key table, admin command with an emergency off switch, dfo-apis and dfo-ai accept and pass on `key:` callers, per-key usage in logs, and the Cloudflare zone's real rules confirmed **Exit criteria:** The first partner runs on a key in production without incident, and per-key counts in the logs match what they report sending. @@ -325,7 +351,7 @@ Three phases take keys from an optional test feature to the normal way heavy use **Anonymous access:** Unchanged; docs start recommending a key -**Also needed:** Docs and quickstart, a transition notice for current users, usage shown to key owners +**Also needed:** The build-or-plugin decision and its spike, docs and quickstart, a transition notice for current users, usage shown to key owners, and a rule that stops an account multiplying its limit by creating keys: one key per account, or one allowance shared by all of an account's keys **Exit criteria:** The transition notice has been out for an agreed period, and the callers who would be hit by lower anonymous limits have been identified and contacted where we can reach them. @@ -347,27 +373,28 @@ Phase 1 should avoid choices that Phase 2 has to undo. The table has an owner co ## Work by Repository -Most of the work is in the website. This split holds for both options: Build and Use differ only in the website row, in where keys are stored and how they are looked up. The dfo-apis, dfo-ai and Cloudflare rows are the same either way, since those systems see only the `key:` caller name and the key header. The Phase 1 pieces: +Most of the work is in the website. This split holds for both options: Build and Use differ only in the website row, in where keys are stored and how they are looked up. The dfo-apis, dfo-ai and Cloudflare rows are the same either way, since those systems see only the `key:` caller name and the key header. Codex's review corrected the dfo-ai row, which first read "little or none". The Phase 1 pieces: -| Where | Size | What | -| ---------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| website | Most of it | Key table and migration (our own `api_key`, or the plugin's); key check and per-key limit in `forward()`; admin command to create and revoke; key caller in the request log; OpenAPI security scheme; docs; tests beside the existing proxy tests | -| dfo-apis | Small | Accept `x-dfo-caller: key:` beside the website's shared secret, so allowances count per key. Today only `ip:` is accepted | -| dfo-ai | Little or none | Confirm a `key:` caller flows through `/mcp` to the MCP servers; add a test if none covers it | -| Cloudflare | Configuration | The WAF rate rules count by address. A keyed caller on a few addresses could hit them before reaching its key's limit | +| Where | Size | What | +| ---------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| website | Most of it | Key table and migration (our own `api_key`, or the plugin's); key check and per-key limit in `forward()`; admin command to create and revoke; key caller in the request log; OpenAPI security scheme; docs; tests beside the existing proxy tests | +| dfo-apis | Small | Accept `x-dfo-caller: key:` beside the website's shared secret, so allowances count per key. Today only `ip:` is accepted | +| dfo-ai | Small | Pass a `key:` caller on to dfo-apis. Its data, presentation and analysis clients forward only `ip:` today and drop anything else, which would count a keyed caller's allowances against dfo-ai itself | +| Cloudflare | Configuration | The WAF rate rules count by address. A keyed caller on a few addresses could hit them before reaching its key's limit | -Order matters between the website and dfo-apis. dfo-apis refuses a caller form it does not recognize when it arrives with the shared secret, so the dfo-apis change has to be live before the website starts sending `key:` callers. +Order matters. dfo-apis refuses a caller form it does not recognize when it arrives with the shared secret. So dfo-apis ships first, then dfo-ai, and the website starts sending `key:` callers last. An end-to-end test should show a keyed call through `/mcp` spending the key's own allowance in dfo-apis. ## Alternatives Considered Besides [Build][] and [Use][Use: Better Auth API Key Plugin] above, we looked at buying this outright. None of these fit as well, because the hard parts are already in the proxy: one function every call passes through, a shared limiter in Postgres, and caller naming to the backends. -| Option | What it is | What it would give us | Why not, or not yet | -| ---------------------------------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Hosted key service, for example [Unkey][unkey] | A service that issues and verifies keys; the proxy calls it on each request | Key management, per-key limits and usage analytics with no tables of our own. A free tier of 150,000 verifications a month | A network call to a third party on every keyed request, and a new vendor holding our callers' keys. Cost grows with traffic, which is the thing we are trying to control | -| Hosted API gateway, for example [Zuplo][zuplo] | A managed gateway in front of the APIs, with keys, rate limits and a developer portal | The whole feature, including self-service sign-up and docs | It replaces the proxy we already have. Streaming (SSE and MCP), caller naming and the harness token would all need to be rebuilt in its terms | -| Google Cloud API Gateway or Apigee | Google's gateways, in the cloud the backends already run in | API Gateway: keys and quotas. Apigee: a full product with developer portal and monetization | API Gateway keys are Google Cloud API keys, which suits internal consumers more than outside sign-ups. Apigee is priced and sized for a larger API program than ours | -| Cloudflare | Already in front of the site | Edge rate limiting per key header on the Enterprise Advanced Rate Limiting plan | It does not issue or validate keys, so it cannot replace the proxy check. See [Cloudflare Integration][] | +| Option | What it is | What it would give us | Why not, or not yet | +| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Static list in a secret | No table in Phase 1: a list of hashed keys and limits in deploy configuration, changed by redeploying | The least to build for one partner. Suggested by Codex | Revoking a key or changing a limit would need a redeploy, and the emergency switch depends on not needing one. A small table costs one migration | +| Hosted key service, for example [Unkey][unkey] | A service that issues and verifies keys; the proxy calls it on each request | Key management, per-key limits and usage analytics with no tables of our own. A free tier of 150,000 verifications a month | A network call to a third party on every keyed request, and a new vendor holding our callers' keys. Cost grows with traffic, which is the thing we are trying to control | +| Hosted API gateway, for example [Zuplo][zuplo] | A managed gateway in front of the APIs, with keys, rate limits and a developer portal | The whole feature, including self-service sign-up and docs | It replaces the proxy we already have. Streaming (SSE and MCP), caller naming and the harness token would all need to be rebuilt in its terms | +| Google Cloud API Gateway or Apigee | Google's gateways, in the cloud the backends already run in | API Gateway: keys and quotas. Apigee: a full product with developer portal and monetization | API Gateway keys are Google Cloud API keys, which suits internal consumers more than outside sign-ups. Apigee is priced and sized for a larger API program than ours | +| Cloudflare | Already in front of the site | Edge rate limiting per key header on the Enterprise Advanced Rate Limiting plan | It does not issue or validate keys, so it cannot replace the proxy check. See [Cloudflare Integration][] | If monetization becomes real, the calculation changes: metering, billing and a developer portal are where the gateway products earn their cost. Nothing in this design blocks moving to one later, since keys are checked in one place. @@ -384,9 +411,11 @@ Not planned for any phase yet. The design should not rule them out. ## Open Questions -The Cloudflare question needs an answer before Phase 1 code is written. +The Cloudflare question and the store-unavailable question need answers before Phase 1 code is written. - [ ] **Cloudflare.** Who owns the WAF rate rules, and can they exempt or raise the threshold for requests that carry a key header? An exemption on header presence alone could be abused with a fake key, so the rule may need a higher ceiling instead of none. Which plan is the zone on, and what are the current thresholds? See [Cloudflare Integration][]. +- [ ] **Key store unavailable: anonymous or 503?** For a key that is not in the cache when the store cannot be reached. See [Identity, Failure and Abuse][] for both positions. +- [ ] **Per key or per account?** In Phase 2, is the allowance a property of each key or of the account that owns them? A cap on the number of keys only limits how far an allowance can be multiplied. - [ ] **How do we reach current anonymous users** for the Phase 2 transition, given we know them only as hashed addresses? Candidates: docs, response headers, the SDK's `x-dfo-client` header. - [ ] **Does a key identify an account to the backends as well,** so a signed-in user's key and their site session share allowances? dfo-ai already names a `user:` caller form. @@ -404,6 +433,8 @@ The Cloudflare question needs an answer before Phase 1 code is written. [Key Format and Communication]: #key-format-and-communication [Limits]: #limits [Cloudflare Integration]: #cloudflare-integration +[Where Keys Apply]: #where-keys-apply +[Identity, Failure and Abuse]: #identity-failure-and-abuse [Logs and Docs]: #logs-and-docs [Build]: #build [Storage]: #storage From f67517a666e190a295a891097535fb7c682afd66 Mon Sep 17 00:00:00 2001 From: Sef Kloninger Date: Fri, 13 Nov 2026 17:46:47 -0800 Subject: [PATCH 14/34] docs(design): fail open when the API key store is unavailable Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf --- docs/design/api-keys.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/design/api-keys.md b/docs/design/api-keys.md index 951c8b1..df7130e 100644 --- a/docs/design/api-keys.md +++ b/docs/design/api-keys.md @@ -1,6 +1,6 @@ # API Keys for the Platform Proxy -Sef Kloninger <> with Claude Code \ +Sef Kloninger <> with Claude Code and Codex \ [Issue #142][issue] \ Last Update: Nov 13, 2026 @@ -52,7 +52,8 @@ Requirements: - Each key carries its own rate limit. - Some MCP features may later require sign-in. That is separate from keys and out of scope here. -**Recommendation.** Build Phase 1 on a small key table of our own, behind a verifier that hides where keys are stored. Decide whether to move key management to Better Auth's API key plugin when Phase 2 is planned, with a spike at that point. The plugin's saving is the self-service endpoints Phase 2 needs. Everything on the request path (the proxy check, the limiter, caching and logging) is ours in either option, so Phase 1 gains little from it. This is where a design review with Codex ended up, after two rounds. The earlier lean was toward the plugin from the start. See [Build][], [Use: Better Auth API Key Plugin][] and [Alternatives Considered][]. +**Recommendation.** Build Phase 1 on a small key table of our own, behind a verifier that hides where keys are stored. Decide whether to move key management to Better Auth's API key plugin when Phase 2 is planned, with a spike at that point. The plugin's saving is the self-service endpoints Phase 2 needs. Everything on the request path (the proxy check, the limiter, caching and logging) is ours in either option, so Phase 1 gains little from it. +See [Build][], [Use: Better Auth API Key Plugin][] and [Alternatives Considered][]. We'll take a phased approach. Initially we'll prove the concept with hand-provisioned keys and limited features. Once this is proven in production, follow-on work will enable more features, self-service provisioning, and admin interfaces to adjust access and limits. @@ -199,7 +200,7 @@ On every surface, a `dfo_` bearer is consumed by the proxy and never copied upst - **Invalid keys.** An unknown or revoked key gets a 401 and does not fall back to anonymous. Attempts are held to a budget per address that is checked before the key store is touched, so random keys cannot force unlimited lookups. Keys over a maximum length are refused unread, and unknown keys are cached briefly as unknown. - **Revocation.** A revoked key stops being admitted within the cache lifetime, about a minute per instance. The lifetime is absolute and is not extended when the store is unreachable. Revoking stops new calls. It does not cut a stream that is already open. Lowering a key's limit takes effect on the same delay. - **Emergency switch.** An operator can turn off one key, or all keyed access, without a deploy. How quickly that reaches every instance has to be stated when it is built. -- **Key store unavailable.** A key already in the cache keeps working until its entry expires. For a key not in the cache there are two positions, and this needs a decision (see [Open Questions][]). The original proposal was to treat the call as anonymous, in line with the limiter failing open. Codex argued for a 503: a revoked or made-up key would otherwise be served as an anonymous caller, and a partner would see rate-limit errors at the anonymous limit with no sign of why. A caller who wants anonymous access can leave the key out. The lookup gets its own bounded pool and timeout, as the counter has. +- **Key store unavailable.** The check fails open. A key already in the cache keeps working until its entry expires. A key that is not in the cache is treated as anonymous while the store cannot be reached: the call goes through at the anonymous limit for its address. Rate limiting is not a mission-critical part of the system, so staying available matters more than enforcing a key's own limit during an outage. The lookup gets its own bounded pool and timeout, as the counter has, so a slow store does not slow the proxy. ### Logs and Docs @@ -237,7 +238,7 @@ Before the rate limit, on the surfaces in [Where Keys Apply][]: 3. Unknown or revoked key: answer 401 with a problem document. 4. Valid key: count the call against `key:` at the key's limit, using the existing counter, which already counts each surface separately. The counter's entry point takes an address and a fixed limit today and needs to accept a caller and a limit. -[Identity, Failure and Abuse][] covers revocation delay and what happens when the store is unavailable. +[Identity, Failure and Abuse][] covers revocation delay and failing open when the store is unavailable. A keyed call is named to the backends as `x-dfo-caller: key:` instead of `ip:`. dfo-apis accepts only the `ip:` form today. dfo-ai accepts a `key:` caller on arrival, but its MCP servers drop any caller that is not `ip:` before they call dfo-apis. Both need a change, so allowances count per key and not per address. See [Work by Repository][]. @@ -411,10 +412,9 @@ Not planned for any phase yet. The design should not rule them out. ## Open Questions -The Cloudflare question and the store-unavailable question need answers before Phase 1 code is written. +The Cloudflare question needs an answer before Phase 1 code is written. - [ ] **Cloudflare.** Who owns the WAF rate rules, and can they exempt or raise the threshold for requests that carry a key header? An exemption on header presence alone could be abused with a fake key, so the rule may need a higher ceiling instead of none. Which plan is the zone on, and what are the current thresholds? See [Cloudflare Integration][]. -- [ ] **Key store unavailable: anonymous or 503?** For a key that is not in the cache when the store cannot be reached. See [Identity, Failure and Abuse][] for both positions. - [ ] **Per key or per account?** In Phase 2, is the allowance a property of each key or of the account that owns them? A cap on the number of keys only limits how far an allowance can be multiplied. - [ ] **How do we reach current anonymous users** for the Phase 2 transition, given we know them only as hashed addresses? Candidates: docs, response headers, the SDK's `x-dfo-client` header. - [ ] **Does a key identify an account to the backends as well,** so a signed-in user's key and their site session share allowances? dfo-ai already names a `user:` caller form. From 314eed71cc9daaf4f549ae6adea2b3609a81c0e4 Mon Sep 17 00:00:00 2001 From: Sef Kloninger Date: Mon, 16 Nov 2026 08:31:56 -0800 Subject: [PATCH 15/34] docs(design): address review of the API keys design Recommend Better Auth's API key plugin from Phase 1, with our own limiter, cache and outage handling around it; building our own key table becomes the fallback if the spike fails. Limits count per account, revoking deletes the key, bad keys count against the address limit before lookup, a slow counter falls back to a per-instance count instead of letting bursts through, and key usage is logged in forward(). Record the current Cloudflare rules and the claude.ai and ChatGPT connector support, add infra and docs to the work, and move MCP caps to Future Features. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf --- docs/design/api-keys.md | 176 +++++++++++++++++++++------------------- 1 file changed, 93 insertions(+), 83 deletions(-) diff --git a/docs/design/api-keys.md b/docs/design/api-keys.md index df7130e..af76925 100644 --- a/docs/design/api-keys.md +++ b/docs/design/api-keys.md @@ -2,7 +2,7 @@ Sef Kloninger <> with Claude Code and Codex \ [Issue #142][issue] \ -Last Update: Nov 13, 2026 +Last Update: Nov 16, 2026 ## Contents @@ -49,11 +49,11 @@ The proxy fronts the public Search, Datasets and Graph APIs (`/api/v1/*`) and th Requirements: - Anonymous access will stay open up to a limit. Our goal is to manage usage and enable rate limits, not wholesale API gating. -- Each key carries its own rate limit. +- Each account that holds keys has its own rate limit, shared by all of its keys. - Some MCP features may later require sign-in. That is separate from keys and out of scope here. -**Recommendation.** Build Phase 1 on a small key table of our own, behind a verifier that hides where keys are stored. Decide whether to move key management to Better Auth's API key plugin when Phase 2 is planned, with a spike at that point. The plugin's saving is the self-service endpoints Phase 2 needs. Everything on the request path (the proxy check, the limiter, caching and logging) is ours in either option, so Phase 1 gains little from it. -See [Build][], [Use: Better Auth API Key Plugin][] and [Alternatives Considered][]. +**Recommendation.** Use Better Auth's API key plugin from Phase 1, with keys in our own Postgres. The site already uses Better Auth for sign-in and sessions, so the plugin gives us key generation, hashing, storage, ownership checks and the create, list and delete endpoints without writing them, and it makes self-service possible from the start. We keep our own limiter, which anonymous traffic needs anyway, and we own caching and outage handling around the plugin's verification. A short spike confirms the plugin fits before Phase 1 code is written. If it does not, we fall back to building a small key table of our own behind the same verifier. +See [Use: Better Auth API Key Plugin][], [Build][] and [Alternatives Considered][]. We'll take a phased approach. Initially we'll prove the concept with hand-provisioned keys and limited features. Once this is proven in production, follow-on work will enable more features, self-service provisioning, and admin interfaces to adjust access and limits. @@ -61,9 +61,10 @@ We'll take a phased approach. Initially we'll prove the concept with hand-provis Every public API and MCP call passes through one function in the website, `forward()` in `src/lib/proxy/forward.ts`. That is the single place a key needs to be checked. -- **Rate limit.** `forward()` counts each call against the client's address in a fixed window: 120 calls a minute on `/api/*`, 300 on `/mcp`. The counters live in the website's Postgres (`limit_counter` table) and are shared by all instances. If the count fails or is slow, the call goes through uncounted. +- **Rate limit.** `forward()` counts each call against the client's address in a fixed window: 120 calls a minute on `/api/*`, 300 on `/mcp`. The counters live in the website's Postgres (`limit_counter` table) and are shared by all instances. If the count fails or is slow, the call goes through uncounted, so a burst sent while the database is slow is not limited at all. - **No Redis.** The original task description mentions turning a Redis limiter back on. There is no Redis code in the website now, so per-key limits need no Memorystore instance. -- **Edge limits.** Cloudflare WAF rules also rate-limit by address, in front of the site. +- **Edge limits.** Cloudflare (Pro plan) also rate-limits by address, in front of the site: 600 calls a minute on the data API and 60 on the Studio, each blocking the address for 10 minutes. `/mcp` has no edge limit. +- **dfo-ai's own limit.** All outside MCP calls share one bucket in dfo-ai of about 2,400 calls a minute. Keyed MCP traffic draws on the same bucket. - **Caller identity.** The proxy names the caller to the backends as `x-dfo-caller: ip:`, a keyed hash of the address. dfo-apis counts its own allowances (shares, cards, pins) against that name. It trusts the header only beside a secret it shares with the website. - **Backends are ahead of us in one place.** dfo-ai's caller module already documents `key:` and `user:` callers "from the website's edge". dfo-apis accepts only the `ip:` form. - **MCP auth.** On `/mcp` the proxy attaches its own token for the harness when it holds one. Otherwise it passes the caller's `Authorization` header through. @@ -72,7 +73,7 @@ Every public API and MCP call passes through one function in the website, `forwa ## Requirements -A key is optional on every call. A call with a valid key is counted against the key at the key's limit, a call with no key is counted against the address as today, and a call with a bad key is refused. These requirements hold whether we build the key store or use Better Auth's plugin. +A key is optional on every call. A call with a valid key is counted against the key's account at the account's limit, a call with no key is counted against the address as today, and a call with a bad key is refused. These requirements hold whether we use Better Auth's plugin or build the key store. ### Key Format and Communication @@ -103,12 +104,13 @@ Some services accept more than one: Stripe takes Bearer or HTTP Basic, and api.d The MCP specification defines authorization as OAuth, with the token sent as `Authorization: Bearer`. It has no API-key concept, so support for a key depends on the client. -| Client type | Examples | Can it send our key? | -| ----------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Developer clients | Claude Code, Cursor, VS Code, SDK scripts | Yes. They let a user configure headers per server, so either header works | -| Hosted chat apps | Connector settings in Claude, ChatGPT and similar | Generally no. They are built around OAuth or no auth, and most give users no place to enter a header. This changes often and needs checking per client before we rely on it | +| Client type | Examples | Can it send our key? | +| ----------------- | ----------------------------------------- | ------------------------------------------------------------------------- | +| Developer clients | Claude Code, Cursor, VS Code, SDK scripts | Yes. They let a user configure headers per server, so either header works | +| Claude | Custom connectors | Yes. A custom connector accepts an API key as a request header | +| ChatGPT | Connectors | No. It accepts only OAuth or no sign-in | -So a key on `/mcp` serves programmatic and developer use. Chat-app users stay anonymous until `/mcp` has OAuth sign-in, which is the separate "MCP features that require logging in" work. +So a key on `/mcp` serves programmatic and developer use, and Claude connector users. ChatGPT users stay anonymous until `/mcp` has OAuth sign-in, which is the separate "MCP features that require logging in" work. Client support changes often and needs checking before we rely on it. **Compatibility with the Proxy as Built** @@ -120,35 +122,40 @@ So a key on `/mcp` serves programmatic and developer use. Chat-app users stay an ### Limits -A key's limit is one plain number, in calls per window. There are no named tiers. +The limit belongs to the account, not the key. All of an account's keys count against one allowance, so creating more keys does not multiply it. The limit is one plain number, in calls per window. There are no named tiers. -The number applies to each surface separately. A key with a limit of 200 can make 200 calls a minute on the API and 200 a minute on MCP, and heavy use of one does not use up the other. +The number applies to each surface separately. An account with a limit of 200 can make 200 calls a minute on the API and 200 a minute on MCP, and heavy use of one does not use up the other. -| Surface | Covers | Anonymous limit today | Keyed limit | -| ------- | -------------------------------------- | ------------------------------ | --------------- | -| API | `/api/v1/*`, `/openapi.json`, `/codes` | 120 calls a minute per address | The key's limit | -| MCP | `/mcp` | 300 calls a minute per address | The key's limit | +| Surface | Covers | Anonymous limit today | Keyed limit | +| ------- | -------------------------------------- | ------------------------------ | ------------------- | +| API | `/api/v1/*`, `/openapi.json`, `/codes` | 120 calls a minute per address | The account's limit | +| MCP | `/mcp` | 300 calls a minute per address | The account's limit | -- The limit is an optional integer on the key. -- Empty means the default for keyed callers, set per deployment in env (for example `RATE_LIMIT_KEYED`). Most keys store nothing, and raising the default moves them all at once. -- A number overrides the default for that key. -- The window stays global at 60 seconds (`RATE_LIMIT_WINDOW_S`). There is no per-key window. +- The limit is an optional integer on the account. +- Empty means the default for keyed callers, set per deployment in env (for example `RATE_LIMIT_KEYED`). Most accounts store nothing, and raising the default moves them all at once. +- A number overrides the default for that account. +- The window stays global at 60 seconds (`RATE_LIMIT_WINDOW_S`). There is no per-account window. +- A slow counter must not let a burst through. Today a slow or failed count lets the call through uncounted. Instead, each instance keeps a small in-memory count per caller and falls back to it when the shared count is slow, so the proxy stays available but one caller is still held near its limit on each instance. -One number is simpler to explain to a key holder, simpler to administer, and fits Better Auth's plugin, which has one limit per key. The anonymous limits differ by surface because chat vendors send many users from one address. That does not apply to a key, which is one caller. +One number is simpler to explain to a key holder and simpler to administer. The anonymous limits differ by surface because chat vendors send many users from one address. That does not apply to an account, which is one caller. -What this gives up is setting a key's MCP limit apart from its API limit. MCP can be a significant cost driver, so a separate MCP limit is listed under [Future Features][]. It can be added later as a second optional number without disturbing existing keys. +What this gives up is setting an account's MCP limit apart from its API limit. MCP can be a significant cost driver, and all outside MCP calls share dfo-ai's bucket, so caps for keyed MCP use are listed under [Future Features][]. They can be added later without disturbing existing accounts. This is all on the admin side. If we later want tiers, for single or bulk changes to keys, they can be added as a column or as a bulk update over this number without changing what it means. -Not covered by a key's limits: +Not covered by an account's limit: - The proxy's third allowance, `/api/download-pin` at 10 calls a minute, belongs to the site's download UI and is not part of the public API. - The Studio's daily prompt allowance is for the site's own chat UI. -- dfo-apis keeps its own daily allowances per caller: 10 shares and 500 presentation cards, plus pins. A keyed caller gets these at the default values. Raising them for a partner would be a dfo-apis setting, not part of the key's limit. +- dfo-apis keeps its own daily allowances per caller: 10 shares and 500 presentation cards, plus pins. A keyed caller gets these at the default values. Raising them for a partner would be a dfo-apis setting, not part of the account's limit. ### Cloudflare Integration -Cloudflare sits in front of the site and rate-limits by address. The proxy stays the per-key limiter, and Cloudflare is a coarse backstop against floods, set above the highest limit any key will have. Cloudflare cannot tell a real key from a made-up one, since it sees only a header value, so it cannot enforce per-key limits itself. +Cloudflare sits in front of the site and rate-limits by address. The proxy stays the per-account limiter, and Cloudflare is a coarse backstop against floods, set above the highest limit any account will have. + +**Current Configuration** + +The zone is on the Pro plan. It limits the data API to 600 calls a minute per address and the Studio to 60, each blocking the address for 10 minutes. `/mcp` has no edge limit. No change is proposed for Phase 1: 600 a minute is well above the proxy's anonymous limit, so it binds only if an account is granted more than 600 calls a minute from one address. If that happens, the threshold is raised or a rule skips requests carrying a key header, as below. Pro cannot count by a header. Cloudflare cannot tell a real key from a made-up one, since it sees only a header value, so it cannot enforce per-key limits itself. **What Cloudflare Recommends** @@ -179,9 +186,7 @@ Below Enterprise, a rate limiting rule's own match expression cannot reference r - With Advanced Rate Limiting: follow Cloudflare's pattern. One rule counts by IP for requests with no key header. Another counts by the key header at a high ceiling. A fake key then earns only a separate bucket that is still limited. - Without it: raise the per-address threshold, or add a custom rule that skips rate limiting for requests that carry a key header. Whether custom rules can match headers and skip rate limiting rules on every plan is unconfirmed. The skip can be abused with a fake header, and the proxy's limit is then the only one left for that traffic. -- If today's thresholds are already well above 120 and 300 calls a minute, Phase 1 may need no edge change. - -Which option applies depends on the zone's plan and its current rules. See [Open Questions][]. +- Today's thresholds are already well above the proxy's anonymous limits, so Phase 1 needs no edge change. ### Where Keys Apply @@ -197,19 +202,19 @@ On every surface, a `dfo_` bearer is consumed by the proxy and never copied upst ### Identity, Failure and Abuse - **One identity per request.** The proxy resolves the caller once, as an address or a key, before the limiter runs. That one identity is used for counting, for `x-dfo-caller` to both dfo-apis and dfo-ai, and for logging. Today the MCP route, the dfo-apis path and the request log each work out the caller separately. -- **Invalid keys.** An unknown or revoked key gets a 401 and does not fall back to anonymous. Attempts are held to a budget per address that is checked before the key store is touched, so random keys cannot force unlimited lookups. Keys over a maximum length are refused unread, and unknown keys are cached briefly as unknown. -- **Revocation.** A revoked key stops being admitted within the cache lifetime, about a minute per instance. The lifetime is absolute and is not extended when the store is unreachable. Revoking stops new calls. It does not cut a stream that is already open. Lowering a key's limit takes effect on the same delay. -- **Emergency switch.** An operator can turn off one key, or all keyed access, without a deploy. How quickly that reaches every instance has to be stated when it is built. -- **Key store unavailable.** The check fails open. A key already in the cache keeps working until its entry expires. A key that is not in the cache is treated as anonymous while the store cannot be reached: the call goes through at the anonymous limit for its address. Rate limiting is not a mission-critical part of the system, so staying available matters more than enforcing a key's own limit during an outage. The lookup gets its own bounded pool and timeout, as the counter has, so a slow store does not slow the proxy. +- **Invalid keys.** An unknown or revoked key gets a 401 and does not fall back to anonymous. There is no separate budget for bad keys. Any key that is not already in the cache is counted against its address's normal limit before the store is looked up, so made-up keys cannot force more lookups than the address could make calls anyway. Keys over a maximum length are refused unread, and unknown keys are cached briefly as unknown. +- **Revocation.** Revoking a key deletes it. The plugin lets a key's owner switch a disabled key back on, so disabling is not revocation. Logs keep the key's public id, so its history survives. A deleted key stops being admitted within the cache lifetime, about a minute per instance. The lifetime is absolute and is not extended when the store is unreachable. Revoking stops new calls. It does not cut a stream that is already open. Lowering an account's limit takes effect on the same delay. +- **Emergency switch.** An operator can delete one key, or turn off all keyed access, without a deploy. How quickly that reaches every instance has to be stated when it is built. +- **Key store unavailable.** The check fails open. A key already in the cache keeps working until its entry expires. A key that is not in the cache is treated as anonymous while the store cannot be reached: the call goes through at the anonymous limit for its address. Rate limiting is not a mission-critical part of the system, so staying available matters more than enforcing an account's own limit during an outage. The plugin reports a database outage as an invalid key, so the verifier has to tell the two apart itself rather than answer 401 to every uncached key during an outage. The lookup gets its own bounded pool and timeout, as the counter has, so a slow store does not slow the proxy. ### Logs and Docs -- Usage per key is counted from a log line that carries the key's public id, the surface and the outcome, and never the key or its hash. The existing request log works the caller out from raw headers when the response closes, apart from `forward()`, so it has to be given the verified identity or be joined by a dedicated usage event. This is what the Phase 1 exit criterion and Phase 3's search for high-volume callers rely on. -- `/openapi.json` gains an optional security scheme, and the API and MCP docs explain keys. +- Key usage is logged in `forward()`, where the key is checked. The line carries the key's public id, its account, the surface and the outcome, and never the key or its hash. The existing request log works the caller out from raw headers when the response closes, apart from `forward()`, so it cannot see which key was used. Per-key and per-account usage metrics come from this line, and the Phase 1 exit criterion and Phase 3's search for high-volume callers rely on it. +- `/openapi.json` gains an optional security scheme, and the API and MCP docs explain keys. The API quickstart in the docs repository, which says no key is needed, is updated. ## Build -In this option we own the key store: a table in the website's Postgres, a lookup in the proxy, and an admin command. Nothing new is installed. This is the plan for Phase 1. +In this option we own the key store: a table in the website's Postgres, a lookup in the proxy, and an admin command. Nothing new is installed. This is the fallback if the plugin spike fails. The proxy reaches the store through a small verifier: it takes a key and answers with the key's public id, limit and owner, or says the key is invalid, or says the store is unavailable. Nothing else in the proxy knows where keys live, so the store can change later. Public ids stay the same if it does. @@ -217,15 +222,16 @@ The proxy reaches the store through a small verifier: it takes a key and answers A new `api_key` table in the website's Postgres, beside the accounts and the limit counters. -| Column | Purpose | -| ------------------------------------ | ------------------------------------------------------------------------------------ | -| id | Short public identifier, used in logs and as the caller name | -| key_hash | SHA-256 of the key, unique | -| prefix | First characters of the key, so its owner can recognize it in a list | -| label | What the key is for | -| user_id | Owning account. Empty for a manually provisioned key in Phase 1 | -| rate_limit | Calls per window, applied to each surface. Empty means the default for keyed callers | -| created_at, revoked_at, last_used_at | Lifecycle. `last_used_at` is updated occasionally, not on every call | +| Column | Purpose | +| ------------------------ | -------------------------------------------------------------------- | +| id | Short public identifier, used in logs and as the caller name | +| key_hash | SHA-256 of the key, unique | +| prefix | First characters of the key, so its owner can recognize it in a list | +| label | What the key is for | +| user_id | Owning account | +| created_at, last_used_at | Lifecycle. `last_used_at` is updated occasionally, not on every call | + +The account's limit is an optional integer on the user record, empty meaning the default for keyed callers. Revoking deletes the row. Postgres rather than Redis: the limiter already counts there, key volume is small, and it adds no new infrastructure. This can be changed later if we need something more scalable and performant at the cost of some additional dev and operational complexity. @@ -234,17 +240,18 @@ Postgres rather than Redis: the limiter already counts there, key volume is smal Before the rate limit, on the surfaces in [Where Keys Apply][]: 1. Read the key header. No header: carry on as an anonymous caller. -2. Check the address's budget for key attempts, then hash the key and look it up through a short in-process cache (about 60 seconds), so a keyed call adds no query in the common case. Lookup is by the hash, so no secret is compared by hand. +2. Hash the key and look it up in a short in-process cache (about 60 seconds), so a keyed call adds no query in the common case. On a cache miss, count the call against the address's normal limit first, then look the key up in the store. Lookup is by the hash, so no secret is compared by hand. 3. Unknown or revoked key: answer 401 with a problem document. -4. Valid key: count the call against `key:` at the key's limit, using the existing counter, which already counts each surface separately. The counter's entry point takes an address and a fixed limit today and needs to accept a caller and a limit. +4. Valid key: count the call against the owning account at the account's limit, using the existing counter, which already counts each surface separately. The counter's entry point takes an address and a fixed limit today and needs to accept a caller and a limit. +5. Log the key's public id, its account, the surface and the outcome. [Identity, Failure and Abuse][] covers revocation delay and failing open when the store is unavailable. -A keyed call is named to the backends as `x-dfo-caller: key:` instead of `ip:`. dfo-apis accepts only the `ip:` form today. dfo-ai accepts a `key:` caller on arrival, but its MCP servers drop any caller that is not `ip:` before they call dfo-apis. Both need a change, so allowances count per key and not per address. See [Work by Repository][]. +A keyed call is named to the backends by its account instead of `ip:`, so their allowances are per account too. The exact form (`key:` or the `user:` form dfo-ai already documents) is settled with the dfo-apis change. dfo-apis refuses any form but `ip:` with a 400 today. dfo-ai accepts a keyed caller on arrival, but its MCP servers drop any caller that is not `ip:` before they call dfo-apis. Both need a change. See [Work by Repository][]. ### Future Work: Admin Interface -Phase 1 has only an admin command that creates and revokes keys and sets their limits. Later phases need more, and all of it would be ours to build: +Phase 1 has only an admin command that creates and revokes keys and sets account limits, run in production as a Cloud Run Job. Later phases need more, and all of it would be ours to build: - Self-service pages in the account menu to create, label and revoke keys and see last use, with the endpoints and ownership checks behind them (Phase 2). - An operator view to find a key, see its usage, and raise or cut its limits (Phase 3). @@ -252,7 +259,7 @@ Phase 1 has only an admin command that creates and revokes keys and sets their l ## Use: Better Auth API Key Plugin -In this option the key store is the [API key plugin][better-auth-api-key] of Better Auth, the library that already handles sign-in on the site. It is a separate package, `@better-auth/api-key`, and is not installed today (the site has `better-auth` 1.7.7). Keys live in our own Postgres, in a table the plugin defines. No third-party service is involved. This is a decision for Phase 2 planning, when self-service is scheduled. It would sit behind the same verifier as the Build store. +In this option the key store is the [API key plugin][better-auth-api-key] of Better Auth, the library that already handles sign-in on the site. It is a separate package, `@better-auth/api-key`, and is not installed today (the site has `better-auth` 1.7.7). Keys live in our own Postgres, in a table the plugin defines. No third-party service is involved. This is the recommended option from Phase 1, behind the same verifier the Build store would use. ### What the Plugin Provides @@ -271,11 +278,13 @@ In this option the key store is the [API key plugin][better-auth-api-key] of Bet ### How It Would Fit -- **Proxy check.** The steps in [The Proxy Check][] stay the same, with the lookup replaced by `verifyApiKey`. We would keep the short in-process cache, because the plugin writes to the key's row on each verification unless updates are deferred. +- **Proxy check.** The steps in [The Proxy Check][] stay the same, with the lookup replaced by `verifyApiKey`. We keep the short in-process cache, because the plugin writes to the key's row on each verification unless updates are deferred. +- **Outages.** The plugin reports a database outage as an invalid key. Our verifier owns outage handling: it treats an error or timeout as "store unavailable", and before answering 401 it confirms the store is reachable, so failing open works as in [Identity, Failure and Abuse][]. - **Header.** A small getter reads `Authorization: Bearer dfo_…` and `X-API-Key`, so [Key Format and Communication][] holds as written. -- **Limits.** The plugin has one limit per key, as our design does. Its per-key maximum field can hold our number. A variant keeps limits and public ids in a small table of our own beside the plugin's, which avoids leaning on a field of a limiter we have switched off. Either way we would turn the plugin's own limiter off and keep counting in `limit_counter`: ours fails open on a slow database, lets verification sit behind the cache, emits the `X-RateLimit-*` headers, and is the limiter anonymous traffic uses anyway. +- **Limits.** The plugin's limits are per key, and ours are per account, so we turn the plugin's own limiter off and keep counting in `limit_counter`: ours lets verification sit behind the cache, emits the `X-RateLimit-*` headers, and is the limiter anonymous traffic uses anyway. The account's limit is an extra field on the Better Auth user record. +- **Revocation.** Operators revoke by deleting the key, because the plugin lets an owner re-enable a disabled key. - **Ownership.** A hand-provisioned Phase 1 key needs an account to belong to. We would create one for the partner, or for ourselves on their behalf. -- **Caller name.** The plugin's key id becomes the `` in `x-dfo-caller: key:`. +- **Caller name.** The key's account names the caller to the backends. The plugin's key id is the public id in logs. - **Schema.** The plugin's table is added through our existing migrations, as the auth tables were. ### Admin System @@ -288,7 +297,7 @@ There is no admin interface to leverage. This was checked in three places: | [Better Auth admin plugin][better-auth-admin] | User administration: list and edit users, roles, bans, sessions, impersonation | No. It has no pages either, only methods, and it does not cover API keys | | [Better Auth Infrastructure dashboard][better-auth-dash] | A hosted dashboard from the Better Auth company, fed by a plugin that sends user and session events to their service | Not documented. It would also send account activity to a third party | -So an admin command, and later an operator view, are ours to write in either option. With the plugin, they are thin wrappers over its server methods instead of our own queries. A community library, better-auth-ui, has ready-made components for a user's own keys, which could shorten the Phase 2 self-service pages. It has not been evaluated. +So an admin command, run in production as a Cloud Run Job, and later an operator view, are ours to write in either option. With the plugin, they are thin wrappers over its server methods instead of our own queries. The plugin's own client methods already cover a signed-in user's keys, which is most of what self-service needs. A community library, better-auth-ui, has ready-made components for a user's own keys, which could shorten the Phase 2 self-service pages. It has not been evaluated. ### What It Saves and What It Costs @@ -300,23 +309,24 @@ Saves: Costs: -- A dependency in the path of every keyed request, on a package that has changed recently: it moved to its own package, and its owner column was renamed. -- A second limiter that we would switch off. -- Every key must have an owning account. +- A dependency in the path of every keyed request, on a package that has changed recently: it moved to its own package, and its owner column was renamed. Our cache keeps it off the path for most calls. +- A second limiter that we switch off. +- Outage handling the plugin does not do, which we wrap around it. - Less control over the table's shape, and upgrades that may bring migrations. +Every key needing an owning account is not a cost here: limits are per account anyway. + ### Spike Before Deciding -Run this when Phase 2 is planned. A day or two should answer these. Any "no" means Phase 2 extends the Build store instead. +Run this before Phase 1 code is written. A day or two should answer these. A "no" that cannot be worked around means Phase 1 uses the Build store instead. - [ ] Does `@better-auth/api-key` work with the site's `better-auth` 1.7.7 and its Drizzle migrations? - [ ] Can verification run without a database write per request, or is the write cheap enough behind our cache? - [ ] Does a getter for `Authorization: Bearer` work alongside the plugin's own endpoints? -- [ ] Can the Phase 1 keys be carried over, by converting our stored hashes to the plugin's form, or would the few Phase 1 holders be issued new keys? -- [ ] Can a signed-in user reach only their own keys, and are they unable to raise their own limit? +- [ ] Can a signed-in user reach only their own keys, and are they unable to raise their own account's limit? - [ ] What happens to an account's keys when the account is deleted, and when a key expires while it is in our cache? -- [ ] Do the plugin's errors let us tell an invalid key from an unavailable store? -- [ ] Can an operator set the limit on another user's key from the server, and can the proxy read that number while the plugin's own limiter is off? +- [ ] How does the verifier tell an invalid key from an unavailable store, given the plugin reports both as invalid? +- [ ] Can an admin command delete another user's key and set an account's limit from the server, and run as a Cloud Run Job? ## Phases @@ -330,13 +340,13 @@ Three phases take keys from an optional test feature to the normal way heavy use **Who gets a key:** A few callers we choose -**Provisioning:** Manual: an admin command creates and revokes keys +**Provisioning:** Manual: an admin command, run as a Cloud Run Job, creates and revokes keys -**Limits:** Set per key by hand +**Limits:** Set per account by hand **Anonymous access:** Unchanged -**Also needed:** Proxy check behind a verifier, key table, admin command with an emergency off switch, dfo-apis and dfo-ai accept and pass on `key:` callers, per-key usage in logs, and the Cloudflare zone's real rules confirmed +**Also needed:** The plugin spike, proxy check behind a verifier, the plugin's key table, admin command with an emergency off switch, a burst-safe fallback when the counter is slow, dfo-apis and dfo-ai accept and pass on keyed callers, key usage logged in `forward()`, and the API docs and quickstart **Exit criteria:** The first partner runs on a key in production without incident, and per-key counts in the logs match what they report sending. @@ -346,13 +356,13 @@ Three phases take keys from an optional test feature to the normal way heavy use **Who gets a key:** Any signed-in account -**Provisioning:** Self-service from the account menu: create, label, revoke, see last use +**Provisioning:** Self-service from the account menu: create, label, revoke, see last use. The plugin's endpoints make this mostly page work, so it could start earlier if a partner needs it. -**Limits:** A default for self-service keys, with higher limits granted by an operator. We will examine current usage and tune the default and the anonymous thresholds at that time, as part of the transition plan. +**Limits:** A default for self-service accounts, with higher limits granted by an operator. We will examine current usage and tune the default and the anonymous thresholds at that time, as part of the transition plan. **Anonymous access:** Unchanged; docs start recommending a key -**Also needed:** The build-or-plugin decision and its spike, docs and quickstart, a transition notice for current users, usage shown to key owners, and a rule that stops an account multiplying its limit by creating keys: one key per account, or one allowance shared by all of an account's keys +**Also needed:** A transition notice for current users, usage shown to key owners, and caps for keyed MCP use if MCP usage calls for them (see [Future Features][]) **Exit criteria:** The transition notice has been out for an agreed period, and the callers who would be hit by lower anonymous limits have been identified and contacted where we can reach them. @@ -362,7 +372,7 @@ Three phases take keys from an optional test feature to the normal way heavy use **Who gets a key:** Same, plus outreach to heavy anonymous callers -**Provisioning:** Self-service, plus operator tools to raise or cut a key's limit +**Provisioning:** Self-service, plus operator tools to raise or cut an account's limit **Limits:** Anonymous limits lowered in steps @@ -370,20 +380,22 @@ Three phases take keys from an optional test feature to the normal way heavy use **Also needed:** Usage reports by caller, a playbook for lowering a limit and rolling it back, edge rules that respect keys -Phase 1 should avoid choices that Phase 2 has to undo. The table has an owner column from the start, and the limit is stored per key in a form a tier can replace. +Phase 1 should avoid choices that Phase 2 has to undo. Every key has an owning account from the start, and the limit is stored per account in a form a tier can replace. ## Work by Repository -Most of the work is in the website. This split holds for both options: Build and Use differ only in the website row, in where keys are stored and how they are looked up. The dfo-apis, dfo-ai and Cloudflare rows are the same either way, since those systems see only the `key:` caller name and the key header. Codex's review corrected the dfo-ai row, which first read "little or none". The Phase 1 pieces: +Most of the work is in the website. This split holds for both options: Use and Build differ only in the website row, in where keys are stored and how they are looked up. The other rows are the same either way, since those systems see only the caller name and the key header. Codex's review corrected the dfo-ai row, which first read "little or none". The Phase 1 pieces: -| Where | Size | What | -| ---------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| website | Most of it | Key table and migration (our own `api_key`, or the plugin's); key check and per-key limit in `forward()`; admin command to create and revoke; key caller in the request log; OpenAPI security scheme; docs; tests beside the existing proxy tests | -| dfo-apis | Small | Accept `x-dfo-caller: key:` beside the website's shared secret, so allowances count per key. Today only `ip:` is accepted | -| dfo-ai | Small | Pass a `key:` caller on to dfo-apis. Its data, presentation and analysis clients forward only `ip:` today and drop anything else, which would count a keyed caller's allowances against dfo-ai itself | -| Cloudflare | Configuration | The WAF rate rules count by address. A keyed caller on a few addresses could hit them before reaching its key's limit | +| Where | Size | What | +| ---------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| website | Most of it | The plugin and its table migration (or our own `api_key`); key check, per-account limit, burst-safe counter fallback and key usage logging in `forward()`; admin command to create and revoke; OpenAPI security scheme; tests beside the existing proxy tests | +| dfo-apis | Small | Accept a keyed caller in `x-dfo-caller` beside the website's shared secret, so allowances count per account. Today only `ip:` is accepted, and anything else gets a 400 | +| dfo-ai | Small | Pass a keyed caller on to dfo-apis. Its data, presentation and analysis clients forward only `ip:` today and drop anything else, which would count a keyed caller's allowances against dfo-ai itself | +| infra | Small | A Cloud Run Job that runs the admin command in production, so keys can be deleted and limits changed there | +| docs | Small | The API quickstart, which says no key is needed, and a page on keys | +| Cloudflare | None today | The Pro plan's per-address rules (600 a minute on the data API) sit well above the proxy's limits. Revisit if an account is granted more than that from one address | -Order matters. dfo-apis refuses a caller form it does not recognize when it arrives with the shared secret. So dfo-apis ships first, then dfo-ai, and the website starts sending `key:` callers last. An end-to-end test should show a keyed call through `/mcp` spending the key's own allowance in dfo-apis. +Order matters. dfo-apis refuses a caller form it does not recognize with a 400 when it arrives with the shared secret. So dfo-apis ships first, then dfo-ai, and the website starts sending keyed callers last. An end-to-end test should show a keyed call through `/mcp` spending the account's own allowance in dfo-apis. ## Alternatives Considered @@ -405,17 +417,15 @@ Not planned for any phase yet. The design should not rule them out. - **Expiring keys.** A key carries an expiry date and stops working after it. Until then a key lives until it is revoked. - **Multiple keys per account.** An account holds several keys at once, for example one per application or to rotate a key without downtime. -- **A separate MCP limit per key.** A second optional number that sets a key's limit on `/mcp` apart from its limit on the API. MCP calls can cost much more than API calls, so this is the first refinement we expect to want. Keys without it keep using their one limit on both surfaces. +- **Caps for keyed MCP use.** MCP calls can cost much more than API calls, and all outside MCP calls share one dfo-ai bucket of about 2,400 calls a minute, so this is the first refinement we expect to want. Candidates are a separate per-minute MCP limit per account, or a daily cap per account. Keys are not required on `/mcp`, and there is no plan to require them yet. Accounts without a cap keep using their one limit on both surfaces. - **More graceful degradation besides limits.** Depending on how often limits are hit, and the user impact of that, we could have fancier throttles in the future: - Soft vs. hard limits (warnings) - Hourly vs. weekly limits, like how modern chat interfaces work. This protects against spiky workloads while mitigating the impact of hitting a limit ("try again in a few hours"). ## Open Questions -The Cloudflare question needs an answer before Phase 1 code is written. +None of these block Phase 1. -- [ ] **Cloudflare.** Who owns the WAF rate rules, and can they exempt or raise the threshold for requests that carry a key header? An exemption on header presence alone could be abused with a fake key, so the rule may need a higher ceiling instead of none. Which plan is the zone on, and what are the current thresholds? See [Cloudflare Integration][]. -- [ ] **Per key or per account?** In Phase 2, is the allowance a property of each key or of the account that owns them? A cap on the number of keys only limits how far an allowance can be multiplied. - [ ] **How do we reach current anonymous users** for the Phase 2 transition, given we know them only as hashed addresses? Candidates: docs, response headers, the SDK's `x-dfo-client` header. - [ ] **Does a key identify an account to the backends as well,** so a signed-in user's key and their site session share allowances? dfo-ai already names a `user:` caller form. From 5e6ae1fab924497ca7b15cb4084ead96831b22b4 Mon Sep 17 00:00:00 2001 From: Sef Kloninger Date: Mon, 16 Nov 2026 11:47:51 -0800 Subject: [PATCH 16/34] docs(design): record the API key plugin spike results The plugin fits with workarounds: the proxy reads the plugin's table itself (verifyApiKey writes on every call and reports an outage as an invalid key), the plugin's HTTP endpoints are disabled and wrapped, and the migration adds a unique key index and a cascading foreign key to the user. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf --- docs/design/api-keys.md | 38 ++++++++++++++++++++------------------ 1 file changed, 20 insertions(+), 18 deletions(-) diff --git a/docs/design/api-keys.md b/docs/design/api-keys.md index af76925..050b61f 100644 --- a/docs/design/api-keys.md +++ b/docs/design/api-keys.md @@ -52,7 +52,7 @@ Requirements: - Each account that holds keys has its own rate limit, shared by all of its keys. - Some MCP features may later require sign-in. That is separate from keys and out of scope here. -**Recommendation.** Use Better Auth's API key plugin from Phase 1, with keys in our own Postgres. The site already uses Better Auth for sign-in and sessions, so the plugin gives us key generation, hashing, storage, ownership checks and the create, list and delete endpoints without writing them, and it makes self-service possible from the start. We keep our own limiter, which anonymous traffic needs anyway, and we own caching and outage handling around the plugin's verification. A short spike confirms the plugin fits before Phase 1 code is written. If it does not, we fall back to building a small key table of our own behind the same verifier. +**Recommendation.** Use Better Auth's API key plugin from Phase 1, with keys in our own Postgres. The site already uses Better Auth for sign-in and sessions, so the plugin gives us key generation, hashing, storage, and the create, list and delete operations with ownership checks, without writing them, and it makes self-service possible from the start. We keep our own limiter, which anonymous traffic needs anyway, and we own the key lookup on the request path, with its caching and outage handling. A spike confirmed the plugin fits, with workarounds. If that changes, we fall back to building a small key table of our own behind the same verifier. See [Use: Better Auth API Key Plugin][], [Build][] and [Alternatives Considered][]. We'll take a phased approach. Initially we'll prove the concept with hand-provisioned keys and limited features. Once this is proven in production, follow-on work will enable more features, self-service provisioning, and admin interfaces to adjust access and limits. @@ -278,14 +278,16 @@ In this option the key store is the [API key plugin][better-auth-api-key] of Bet ### How It Would Fit -- **Proxy check.** The steps in [The Proxy Check][] stay the same, with the lookup replaced by `verifyApiKey`. We keep the short in-process cache, because the plugin writes to the key's row on each verification unless updates are deferred. -- **Outages.** The plugin reports a database outage as an invalid key. Our verifier owns outage handling: it treats an error or timeout as "store unavailable", and before answering 401 it confirms the store is reachable, so failing open works as in [Identity, Failure and Abuse][]. -- **Header.** A small getter reads `Authorization: Bearer dfo_…` and `X-API-Key`, so [Key Format and Communication][] holds as written. -- **Limits.** The plugin's limits are per key, and ours are per account, so we turn the plugin's own limiter off and keep counting in `limit_counter`: ours lets verification sit behind the cache, emits the `X-RateLimit-*` headers, and is the limiter anonymous traffic uses anyway. The account's limit is an extra field on the Better Auth user record. -- **Revocation.** Operators revoke by deleting the key, because the plugin lets an owner re-enable a disabled key. -- **Ownership.** A hand-provisioned Phase 1 key needs an account to belong to. We would create one for the partner, or for ourselves on their behalf. -- **Caller name.** The key's account names the caller to the backends. The plugin's key id is the public id in logs. -- **Schema.** The plugin's table is added through our existing migrations, as the auth tables were. +The spike (below) shaped these. The plugin generates, hashes, stores and manages keys. Our code owns the request path. + +- **Proxy check.** The proxy does not call `verifyApiKey`. That call writes to the key's row on every verification, with no way to turn the writes off, and it reports a database outage as an invalid key. Instead our verifier hashes the key with the plugin's own hasher (`base64url(SHA-256(key))`) and reads the plugin's `apikey` table with Drizzle, on its own bounded pool and timeout. It checks `enabled` and `expiresAt` itself. A throw or timeout means "store unavailable", so failing open works as in [Identity, Failure and Abuse][]. The read is behind the short in-process cache, and the cache stores `expiresAt` so an expired key is not admitted from the cache. +- **Header.** The proxy parses `Authorization: Bearer dfo_…` and `X-API-Key` itself. The plugin's option to turn a key into a session (`enableSessionForAPIKeys`) stays off: with it on, a key acts as its owner on every `/api/auth/*` endpoint, account deletion included. +- **Limits.** The plugin's limiter is off. We count in `limit_counter`: ours lets verification sit behind the cache, emits the `X-RateLimit-*` headers, and is the limiter anonymous traffic uses anyway. The account's limit is an extra field on the Better Auth user record (`apiRateLimit`, not settable by the user). +- **Endpoints.** The plugin's HTTP endpoints for keys are disabled. A user could otherwise create a key with any prefix, re-enable a key an operator disabled, or remove an expiry. Our own thin routes call the plugin's server methods, force the `dfo_live_` prefix, and always use the signed-in user as owner. +- **Revocation.** Revoking deletes the key. The plugin's server-side delete needs the owner's session, so operator deletes go through its adapter or Drizzle. +- **Ownership.** Every key belongs to an account. A hand-provisioned key belongs to an account we create for the partner, or to ourselves on their behalf. +- **Caller name.** The key's account names the caller to the backends as `user:<32 hex>`, a keyed digest of the account id. The plugin's key id, a 32-character random string, is the public id in logs. +- **Schema.** The plugin's table is added through our existing migrations, as the auth tables were, with two changes: a unique index on the key hash, and a foreign key to the user that deletes an account's keys with the account. The plugin has neither. ### Admin System @@ -318,15 +320,15 @@ Every key needing an owning account is not a cost here: limits are per account a ### Spike Before Deciding -Run this before Phase 1 code is written. A day or two should answer these. A "no" that cannot be worked around means Phase 1 uses the Build store instead. +Run on Nov 16, 2026 against `better-auth` 1.7.7 and `@better-auth/api-key` 1.7.7 on Postgres. Verdict: fits, with the workarounds in [How It Would Fit][]. -- [ ] Does `@better-auth/api-key` work with the site's `better-auth` 1.7.7 and its Drizzle migrations? -- [ ] Can verification run without a database write per request, or is the write cheap enough behind our cache? -- [ ] Does a getter for `Authorization: Bearer` work alongside the plugin's own endpoints? -- [ ] Can a signed-in user reach only their own keys, and are they unable to raise their own account's limit? -- [ ] What happens to an account's keys when the account is deleted, and when a key expires while it is in our cache? -- [ ] How does the verifier tell an invalid key from an unavailable store, given the plugin reports both as invalid? -- [ ] Can an admin command delete another user's key and set an account's limit from the server, and run as a Cloud Run Job? +- [x] Works with `better-auth` 1.7.7 and our Drizzle migrations. The plugin's version tracks `better-auth` exactly, so the two are upgraded together. +- [x] Verification writes on every call (a read and two updates), and the writes cannot be turned off. The proxy reads the table itself instead. +- [x] Headers: the proxy parses them itself. The plugin's getter only matters for key-as-session, which stays off. +- [x] A signed-in user reaches only their own keys and cannot set limits or permissions. They can set a key's prefix, re-enable a disabled key and remove an expiry, so the plugin's HTTP endpoints are disabled and wrapped. +- [x] Without a foreign key, deleting an account leaves keys that still verify. We add the foreign key. An expired key is deleted when it is next verified, so our cache checks expiry itself. +- [x] The plugin cannot tell an invalid key from an unavailable store. Our own read can. +- [x] An admin command can create a key for another user and set an account's limit from the server. Deleting another user's key goes through the adapter or Drizzle. Running it as a Cloud Run Job was not tested. ## Phases @@ -346,7 +348,7 @@ Three phases take keys from an optional test feature to the normal way heavy use **Anonymous access:** Unchanged -**Also needed:** The plugin spike, proxy check behind a verifier, the plugin's key table, admin command with an emergency off switch, a burst-safe fallback when the counter is slow, dfo-apis and dfo-ai accept and pass on keyed callers, key usage logged in `forward()`, and the API docs and quickstart +**Also needed:** Proxy check behind a verifier, the plugin's key table, admin command with an emergency off switch, a burst-safe fallback when the counter is slow, dfo-apis and dfo-ai accept and pass on keyed callers, key usage logged in `forward()`, and the API docs and quickstart **Exit criteria:** The first partner runs on a key in production without incident, and per-key counts in the logs match what they report sending. From 14efb736ba2a475647bc3f3367c306e6a997433e Mon Sep 17 00:00:00 2001 From: Sef Kloninger Date: Mon, 16 Nov 2026 11:52:01 -0800 Subject: [PATCH 17/34] feat(auth): add the API key plugin, table and account limit (#142) Installs @better-auth/api-key at the same version as better-auth and wires it into the auth config with the plugin's own limiter, metadata and key-as-session off, and its HTTP key endpoints on disabledPaths. Server-side auth.api calls still work. Migration 0025 adds the apikey table with a unique index on the key hash and a foreign key to user that deletes an account's keys with the account, and user.api_rate_limit, the account's own calls-per-window limit (user.additionalFields.apiRateLimit, never settable or returned to the account). Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf --- db/auth-schema.ts | 56 +- db/migrations/0025_api_keys.sql | 30 + db/migrations/meta/0025_snapshot.json | 1308 +++++++++++++++++++++++++ db/migrations/meta/_journal.json | 7 + db/test/api-key.test.ts | 195 ++++ package.json | 1 + pnpm-lock.yaml | 19 + src/lib/auth/apiKeyOptions.ts | 36 + src/lib/auth/auth.ts | 11 +- 9 files changed, 1660 insertions(+), 3 deletions(-) create mode 100644 db/migrations/0025_api_keys.sql create mode 100644 db/migrations/meta/0025_snapshot.json create mode 100644 db/test/api-key.test.ts create mode 100644 src/lib/auth/apiKeyOptions.ts diff --git a/db/auth-schema.ts b/db/auth-schema.ts index 9e70410..c8e9a75 100644 --- a/db/auth-schema.ts +++ b/db/auth-schema.ts @@ -1,5 +1,13 @@ import { relations } from 'drizzle-orm'; -import { pgTable, text, timestamp, boolean, index } from 'drizzle-orm/pg-core'; +import { + boolean, + index, + integer, + pgTable, + text, + timestamp, + uniqueIndex, +} from 'drizzle-orm/pg-core'; export const user = pgTable('user', { id: text('id').primaryKey(), @@ -15,6 +23,9 @@ export const user = pgTable('user', { // Set when the account's deletion begins (`user.additionalFields` in // src/lib/auth/auth.ts), so no share token is stored for it after. deletingAt: timestamp('deleting_at', { withTimezone: true }), + // The account's own calls-per-window limit for API keys (`user.additionalFields` + // in src/lib/auth/auth.ts). Null is the deployment default (RATE_LIMIT_KEYED). + apiRateLimit: integer('api_rate_limit'), }); export const session = pgTable( @@ -76,6 +87,49 @@ export const verification = pgTable( (table) => [index('verification_identifier_idx').on(table.identifier)], ); +/** + * The `@better-auth/api-key` plugin's table (its columns, as the plugin + * writes them). Differences from the plugin's own schema: `reference_id` has + * a foreign key to `user` that deletes an account's keys with the account + * (the plugin's owner may also be an organization, so it has none), and the + * index on `key`, the SHA-256 of the key, is unique. The proxy reads this + * table itself (src/lib/proxy/keyVerifier). + */ +export const apikey = pgTable( + 'apikey', + { + id: text('id').primaryKey(), + configId: text('config_id').default('default').notNull(), + name: text('name'), + start: text('start'), + referenceId: text('reference_id') + .notNull() + .references(() => user.id, { onDelete: 'cascade' }), + prefix: text('prefix'), + key: text('key').notNull(), + refillInterval: integer('refill_interval'), + refillAmount: integer('refill_amount'), + lastRefillAt: timestamp('last_refill_at'), + enabled: boolean('enabled').default(true), + rateLimitEnabled: boolean('rate_limit_enabled').default(true), + rateLimitTimeWindow: integer('rate_limit_time_window'), + rateLimitMax: integer('rate_limit_max'), + requestCount: integer('request_count').default(0), + remaining: integer('remaining'), + lastRequest: timestamp('last_request'), + expiresAt: timestamp('expires_at'), + createdAt: timestamp('created_at').notNull(), + updatedAt: timestamp('updated_at').notNull(), + permissions: text('permissions'), + metadata: text('metadata'), + }, + (table) => [ + index('apikey_configId_idx').on(table.configId), + index('apikey_referenceId_idx').on(table.referenceId), + uniqueIndex('apikey_key_idx').on(table.key), + ], +); + export const userRelations = relations(user, ({ many }) => ({ sessions: many(session), accounts: many(account), diff --git a/db/migrations/0025_api_keys.sql b/db/migrations/0025_api_keys.sql new file mode 100644 index 0000000..a7c60ff --- /dev/null +++ b/db/migrations/0025_api_keys.sql @@ -0,0 +1,30 @@ +CREATE TABLE "apikey" ( + "id" text PRIMARY KEY NOT NULL, + "config_id" text DEFAULT 'default' NOT NULL, + "name" text, + "start" text, + "reference_id" text NOT NULL, + "prefix" text, + "key" text NOT NULL, + "refill_interval" integer, + "refill_amount" integer, + "last_refill_at" timestamp, + "enabled" boolean DEFAULT true, + "rate_limit_enabled" boolean DEFAULT true, + "rate_limit_time_window" integer, + "rate_limit_max" integer, + "request_count" integer DEFAULT 0, + "remaining" integer, + "last_request" timestamp, + "expires_at" timestamp, + "created_at" timestamp NOT NULL, + "updated_at" timestamp NOT NULL, + "permissions" text, + "metadata" text +); +--> statement-breakpoint +ALTER TABLE "user" ADD COLUMN "api_rate_limit" integer;--> statement-breakpoint +ALTER TABLE "apikey" ADD CONSTRAINT "apikey_reference_id_user_id_fk" FOREIGN KEY ("reference_id") REFERENCES "public"."user"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint +CREATE INDEX "apikey_configId_idx" ON "apikey" USING btree ("config_id");--> statement-breakpoint +CREATE INDEX "apikey_referenceId_idx" ON "apikey" USING btree ("reference_id");--> statement-breakpoint +CREATE UNIQUE INDEX "apikey_key_idx" ON "apikey" USING btree ("key"); \ No newline at end of file diff --git a/db/migrations/meta/0025_snapshot.json b/db/migrations/meta/0025_snapshot.json new file mode 100644 index 0000000..9f68f8e --- /dev/null +++ b/db/migrations/meta/0025_snapshot.json @@ -0,0 +1,1308 @@ +{ + "id": "16fdd89e-1676-4797-b47b-8b5af2973ab6", + "prevId": "ea4d3404-8df5-4f62-90bf-93d2f9b32694", + "version": "7", + "dialect": "postgresql", + "tables": { + "public.conversation": { + "name": "conversation", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "user_id": { + "name": "user_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "title": { + "name": "title", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "agent_session_id": { + "name": "agent_session_id", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "turn_count": { + "name": "turn_count", + "type": "integer", + "primaryKey": false, + "notNull": true, + "default": 0 + }, + "data": { + "name": "data", + "type": "jsonb", + "primaryKey": false, + "notNull": true + }, + "created_at": { + "name": "created_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": true, + "default": "now()" + }, + "updated_at": { + "name": "updated_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "conversation_user_updated_idx": { + "name": "conversation_user_updated_idx", + "columns": [ + { + "expression": "user_id", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "updated_at", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": { + "conversation_user_id_user_id_fk": { + "name": "conversation_user_id_user_id_fk", + "tableFrom": "conversation", + "tableTo": "user", + "columnsFrom": [ + "user_id" + ], + "columnsTo": [ + "id" + ], + "onDelete": "cascade", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.event": { + "name": "event", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "bigint", + "primaryKey": true, + "notNull": true, + "identity": { + "type": "always", + "name": "event_id_seq", + "schema": "public", + "increment": "1", + "startWith": "1", + "minValue": "1", + "maxValue": "9223372036854775807", + "cache": "1", + "cycle": false + } + }, + "created_at": { + "name": "created_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": true, + "default": "now()" + }, + "name": { + "name": "name", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "user_id": { + "name": "user_id", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "visitor_id": { + "name": "visitor_id", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "page": { + "name": "page", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "props": { + "name": "props", + "type": "jsonb", + "primaryKey": false, + "notNull": true, + "default": "'{}'::jsonb" + } + }, + "indexes": { + "event_created_at_idx": { + "name": "event_created_at_idx", + "columns": [ + { + "expression": "created_at", + "isExpression": false, + "asc": false, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + }, + "event_name_created_at_idx": { + "name": "event_name_created_at_idx", + "columns": [ + { + "expression": "name", + "isExpression": false, + "asc": true, + "nulls": "last" + }, + { + "expression": "created_at", + "isExpression": false, + "asc": false, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": {}, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.feedback": { + "name": "feedback", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "bigint", + "primaryKey": true, + "notNull": true, + "identity": { + "type": "always", + "name": "feedback_id_seq", + "schema": "public", + "increment": "1", + "startWith": "1", + "minValue": "1", + "maxValue": "9223372036854775807", + "cache": "1", + "cycle": false + } + }, + "created_at": { + "name": "created_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": true, + "default": "now()" + }, + "message": { + "name": "message", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "email": { + "name": "email", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "page": { + "name": "page", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "user_agent": { + "name": "user_agent", + "type": "text", + "primaryKey": false, + "notNull": false + } + }, + "indexes": { + "feedback_created_at_idx": { + "name": "feedback_created_at_idx", + "columns": [ + { + "expression": "created_at", + "isExpression": false, + "asc": false, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": {}, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": { + "feedback_message_length": { + "name": "feedback_message_length", + "value": "char_length(\"feedback\".\"message\") BETWEEN 1 AND 5000" + } + }, + "isRLSEnabled": false + }, + "public.limit_counter": { + "name": "limit_counter", + "schema": "", + "columns": { + "key": { + "name": "key", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "window_start": { + "name": "window_start", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": true + }, + "count": { + "name": "count", + "type": "integer", + "primaryKey": false, + "notNull": true + } + }, + "indexes": { + "limit_counter_window_start_idx": { + "name": "limit_counter_window_start_idx", + "columns": [ + { + "expression": "window_start", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": {}, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.roadmap_vote": { + "name": "roadmap_vote", + "schema": "", + "columns": { + "user_id": { + "name": "user_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "entry_id": { + "name": "entry_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "created_at": { + "name": "created_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "roadmap_vote_entry_idx": { + "name": "roadmap_vote_entry_idx", + "columns": [ + { + "expression": "entry_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": { + "roadmap_vote_user_id_user_id_fk": { + "name": "roadmap_vote_user_id_user_id_fk", + "tableFrom": "roadmap_vote", + "tableTo": "user", + "columnsFrom": [ + "user_id" + ], + "columnsTo": [ + "id" + ], + "onDelete": "cascade", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": { + "roadmap_vote_user_id_entry_id_pk": { + "name": "roadmap_vote_user_id_entry_id_pk", + "columns": [ + "user_id", + "entry_id" + ] + } + }, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.share": { + "name": "share", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "user_id": { + "name": "user_id", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "kind": { + "name": "kind", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "mode": { + "name": "mode", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "conversation_id": { + "name": "conversation_id", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "card_id": { + "name": "card_id", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "title": { + "name": "title", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "data": { + "name": "data", + "type": "jsonb", + "primaryKey": false, + "notNull": true + }, + "created_at": { + "name": "created_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "share_user_idx": { + "name": "share_user_idx", + "columns": [ + { + "expression": "user_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": { + "share_user_id_user_id_fk": { + "name": "share_user_id_user_id_fk", + "tableFrom": "share", + "tableTo": "user", + "columnsFrom": [ + "user_id" + ], + "columnsTo": [ + "id" + ], + "onDelete": "cascade", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.share_cleanup": { + "name": "share_cleanup", + "schema": "", + "columns": { + "share_id": { + "name": "share_id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "user_id": { + "name": "user_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "write_token": { + "name": "write_token", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "reason": { + "name": "reason", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "recorded_at": { + "name": "recorded_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": {}, + "foreignKeys": {}, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.share_ref": { + "name": "share_ref", + "schema": "", + "columns": { + "share_id": { + "name": "share_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "part_index": { + "name": "part_index", + "type": "integer", + "primaryKey": false, + "notNull": true + }, + "spec_id": { + "name": "spec_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "identity": { + "name": "identity", + "type": "jsonb", + "primaryKey": false, + "notNull": true + }, + "entity_groups": { + "name": "entity_groups", + "type": "jsonb", + "primaryKey": false, + "notNull": false + }, + "variable_text": { + "name": "variable_text", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "content_version": { + "name": "content_version", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "artifact_digest": { + "name": "artifact_digest", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "operations": { + "name": "operations", + "type": "jsonb", + "primaryKey": false, + "notNull": true, + "default": "'[]'::jsonb" + }, + "assumptions": { + "name": "assumptions", + "type": "jsonb", + "primaryKey": false, + "notNull": false + } + }, + "indexes": {}, + "foreignKeys": { + "share_ref_share_id_share_id_fk": { + "name": "share_ref_share_id_share_id_fk", + "tableFrom": "share_ref", + "tableTo": "share", + "columnsFrom": [ + "share_id" + ], + "columnsTo": [ + "id" + ], + "onDelete": "cascade", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": { + "share_ref_share_id_part_index_pk": { + "name": "share_ref_share_id_part_index_pk", + "columns": [ + "share_id", + "part_index" + ] + } + }, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.share_token": { + "name": "share_token", + "schema": "", + "columns": { + "share_id": { + "name": "share_id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "user_id": { + "name": "user_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "write_token": { + "name": "write_token", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "created_at": { + "name": "created_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": {}, + "foreignKeys": { + "share_token_user_id_user_id_fk": { + "name": "share_token_user_id_user_id_fk", + "tableFrom": "share_token", + "tableTo": "user", + "columnsFrom": [ + "user_id" + ], + "columnsTo": [ + "id" + ], + "onDelete": "cascade", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.webmail_domain": { + "name": "webmail_domain", + "schema": "", + "columns": { + "domain": { + "name": "domain", + "type": "text", + "primaryKey": true, + "notNull": true + } + }, + "indexes": {}, + "foreignKeys": {}, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.account": { + "name": "account", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "account_id": { + "name": "account_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "provider_id": { + "name": "provider_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "user_id": { + "name": "user_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "access_token": { + "name": "access_token", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "refresh_token": { + "name": "refresh_token", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "id_token": { + "name": "id_token", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "access_token_expires_at": { + "name": "access_token_expires_at", + "type": "timestamp", + "primaryKey": false, + "notNull": false + }, + "refresh_token_expires_at": { + "name": "refresh_token_expires_at", + "type": "timestamp", + "primaryKey": false, + "notNull": false + }, + "scope": { + "name": "scope", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "password": { + "name": "password", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "created_at": { + "name": "created_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + }, + "updated_at": { + "name": "updated_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true + } + }, + "indexes": { + "account_userId_idx": { + "name": "account_userId_idx", + "columns": [ + { + "expression": "user_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": { + "account_user_id_user_id_fk": { + "name": "account_user_id_user_id_fk", + "tableFrom": "account", + "tableTo": "user", + "columnsFrom": [ + "user_id" + ], + "columnsTo": [ + "id" + ], + "onDelete": "cascade", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.apikey": { + "name": "apikey", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "config_id": { + "name": "config_id", + "type": "text", + "primaryKey": false, + "notNull": true, + "default": "'default'" + }, + "name": { + "name": "name", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "start": { + "name": "start", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "reference_id": { + "name": "reference_id", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "prefix": { + "name": "prefix", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "key": { + "name": "key", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "refill_interval": { + "name": "refill_interval", + "type": "integer", + "primaryKey": false, + "notNull": false + }, + "refill_amount": { + "name": "refill_amount", + "type": "integer", + "primaryKey": false, + "notNull": false + }, + "last_refill_at": { + "name": "last_refill_at", + "type": "timestamp", + "primaryKey": false, + "notNull": false + }, + "enabled": { + "name": "enabled", + "type": "boolean", + "primaryKey": false, + "notNull": false, + "default": true + }, + "rate_limit_enabled": { + "name": "rate_limit_enabled", + "type": "boolean", + "primaryKey": false, + "notNull": false, + "default": true + }, + "rate_limit_time_window": { + "name": "rate_limit_time_window", + "type": "integer", + "primaryKey": false, + "notNull": false + }, + "rate_limit_max": { + "name": "rate_limit_max", + "type": "integer", + "primaryKey": false, + "notNull": false + }, + "request_count": { + "name": "request_count", + "type": "integer", + "primaryKey": false, + "notNull": false, + "default": 0 + }, + "remaining": { + "name": "remaining", + "type": "integer", + "primaryKey": false, + "notNull": false + }, + "last_request": { + "name": "last_request", + "type": "timestamp", + "primaryKey": false, + "notNull": false + }, + "expires_at": { + "name": "expires_at", + "type": "timestamp", + "primaryKey": false, + "notNull": false + }, + "created_at": { + "name": "created_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true + }, + "updated_at": { + "name": "updated_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true + }, + "permissions": { + "name": "permissions", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "metadata": { + "name": "metadata", + "type": "text", + "primaryKey": false, + "notNull": false + } + }, + "indexes": { + "apikey_configId_idx": { + "name": "apikey_configId_idx", + "columns": [ + { + "expression": "config_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + }, + "apikey_referenceId_idx": { + "name": "apikey_referenceId_idx", + "columns": [ + { + "expression": "reference_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + }, + "apikey_key_idx": { + "name": "apikey_key_idx", + "columns": [ + { + "expression": "key", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": true, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": { + "apikey_reference_id_user_id_fk": { + "name": "apikey_reference_id_user_id_fk", + "tableFrom": "apikey", + "tableTo": "user", + "columnsFrom": [ + "reference_id" + ], + "columnsTo": [ + "id" + ], + "onDelete": "cascade", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.session": { + "name": "session", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "expires_at": { + "name": "expires_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true + }, + "token": { + "name": "token", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "created_at": { + "name": "created_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + }, + "updated_at": { + "name": "updated_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true + }, + "ip_address": { + "name": "ip_address", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "user_agent": { + "name": "user_agent", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "user_id": { + "name": "user_id", + "type": "text", + "primaryKey": false, + "notNull": true + } + }, + "indexes": { + "session_userId_idx": { + "name": "session_userId_idx", + "columns": [ + { + "expression": "user_id", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": { + "session_user_id_user_id_fk": { + "name": "session_user_id_user_id_fk", + "tableFrom": "session", + "tableTo": "user", + "columnsFrom": [ + "user_id" + ], + "columnsTo": [ + "id" + ], + "onDelete": "cascade", + "onUpdate": "no action" + } + }, + "compositePrimaryKeys": {}, + "uniqueConstraints": { + "session_token_unique": { + "name": "session_token_unique", + "nullsNotDistinct": false, + "columns": [ + "token" + ] + } + }, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.user": { + "name": "user", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "name": { + "name": "name", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "email": { + "name": "email", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "email_verified": { + "name": "email_verified", + "type": "boolean", + "primaryKey": false, + "notNull": true, + "default": false + }, + "image": { + "name": "image", + "type": "text", + "primaryKey": false, + "notNull": false + }, + "created_at": { + "name": "created_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + }, + "updated_at": { + "name": "updated_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + }, + "deleting_at": { + "name": "deleting_at", + "type": "timestamp with time zone", + "primaryKey": false, + "notNull": false + }, + "api_rate_limit": { + "name": "api_rate_limit", + "type": "integer", + "primaryKey": false, + "notNull": false + } + }, + "indexes": {}, + "foreignKeys": {}, + "compositePrimaryKeys": {}, + "uniqueConstraints": { + "user_email_unique": { + "name": "user_email_unique", + "nullsNotDistinct": false, + "columns": [ + "email" + ] + } + }, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + }, + "public.verification": { + "name": "verification", + "schema": "", + "columns": { + "id": { + "name": "id", + "type": "text", + "primaryKey": true, + "notNull": true + }, + "identifier": { + "name": "identifier", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "value": { + "name": "value", + "type": "text", + "primaryKey": false, + "notNull": true + }, + "expires_at": { + "name": "expires_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true + }, + "created_at": { + "name": "created_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + }, + "updated_at": { + "name": "updated_at", + "type": "timestamp", + "primaryKey": false, + "notNull": true, + "default": "now()" + } + }, + "indexes": { + "verification_identifier_idx": { + "name": "verification_identifier_idx", + "columns": [ + { + "expression": "identifier", + "isExpression": false, + "asc": true, + "nulls": "last" + } + ], + "isUnique": false, + "concurrently": false, + "method": "btree", + "with": {} + } + }, + "foreignKeys": {}, + "compositePrimaryKeys": {}, + "uniqueConstraints": {}, + "policies": {}, + "checkConstraints": {}, + "isRLSEnabled": false + } + }, + "enums": {}, + "schemas": {}, + "sequences": {}, + "roles": {}, + "policies": {}, + "views": {}, + "_meta": { + "columns": {}, + "schemas": {}, + "tables": {} + } +} \ No newline at end of file diff --git a/db/migrations/meta/_journal.json b/db/migrations/meta/_journal.json index 1cd9871..64a9132 100644 --- a/db/migrations/meta/_journal.json +++ b/db/migrations/meta/_journal.json @@ -169,6 +169,13 @@ "when": 1793871780545, "tag": "0024_drop_share_card_result", "breakpoints": true + }, + { + "idx": 25, + "version": "7", + "when": 1794858598852, + "tag": "0025_api_keys", + "breakpoints": true } ] } \ No newline at end of file diff --git a/db/test/api-key.test.ts b/db/test/api-key.test.ts new file mode 100644 index 0000000..2314447 --- /dev/null +++ b/db/test/api-key.test.ts @@ -0,0 +1,195 @@ +import assert from 'node:assert/strict'; +import { createHash } from 'node:crypto'; +import path from 'node:path'; +import test from 'node:test'; +import { defaultKeyHasher } from '@better-auth/api-key'; +import { betterAuth } from 'better-auth'; +import { drizzleAdapter } from 'better-auth/adapters/drizzle'; +import { makeSignature } from 'better-auth/crypto'; +import { eq } from 'drizzle-orm'; +import { drizzle } from 'drizzle-orm/node-postgres'; +import { API_KEY_PATHS, API_KEY_PREFIX, apiKeyPlugin } from '../../src/lib/auth/apiKeyOptions.ts'; +import { applyMigrations } from '../apply-migrations.ts'; +import * as schema from '../schema.ts'; +import { createTestDatabase } from './harness.ts'; + +const MIGRATIONS_FOLDER = path.resolve(import.meta.dirname, '../migrations'); +const BASE = 'http://localhost:3000'; +const SECRET = 'a-test-secret-long-enough-for-better-auth'; + +/** + * The API key tables and the plugin's setup (src/lib/auth/apiKeyOptions), on + * a migrated database and as the runtime role: the unique key index, the + * cascade from user, the grants the proxy's key read needs, the plugin's + * hash, and the HTTP endpoints that stay closed. + */ +test('API key table and plugin setup', async (t) => { + const database = await createTestDatabase(); + t.after(() => database.teardown()); + + await applyMigrations(database.migratorPool(), { + migrationsFolder: MIGRATIONS_FOLDER, + runtimeDbUser: database.runtimeUser, + migratorDbUser: database.migratorUser, + }); + + const pool = database.runtimePool(); + const db = drizzle(pool, { schema }); + const auth = betterAuth({ + database: drizzleAdapter(db, { provider: 'pg', schema }), + baseURL: BASE, + secret: SECRET, + trustedOrigins: [BASE], + disabledPaths: [...API_KEY_PATHS], + user: { + additionalFields: { + apiRateLimit: { type: 'number', required: false, input: false, returned: false }, + }, + }, + plugins: [apiKeyPlugin()], + }); + const context = await auth.$context; + + const signedIn = async (email: string) => { + const user = await context.internalAdapter.createUser( + { email, name: email, emailVerified: true }, + { method: 'email-otp' }, + ); + const session = await context.internalAdapter.createSession(user.id); + const signature = await makeSignature(session.token, SECRET); + const cookie = `better-auth.session_token=${encodeURIComponent(`${session.token}.${signature}`)}`; + + return { user, cookie }; + }; + + const alice = await signedIn('alice@a.example'); + + await t.test('the runtime role reads apikey and user.api_rate_limit', async () => { + await pool.query('select id, key, enabled, expires_at, reference_id from apikey limit 1'); + await pool.query('select api_rate_limit from "user" limit 1'); + }); + + await t.test( + 'a key is stored as its SHA-256, base64url, with the dfo_live_ prefix', + async () => { + const created = await auth.api.createApiKey({ body: { userId: alice.user.id } }); + + assert.match(created.key, /^dfo_live_[A-Za-z0-9]{32}$/); + assert.equal(created.key.startsWith(API_KEY_PREFIX), true); + + const [row] = await db + .select() + .from(schema.apikey) + .where(eq(schema.apikey.id, created.id)); + + assert.equal(row?.key, createHash('sha256').update(created.key).digest('base64url')); + assert.equal(row?.key, await defaultKeyHasher(created.key)); + assert.equal(row?.referenceId, alice.user.id); + }, + ); + + await t.test('a second row with the same key is refused', async () => { + const [row] = await db.select().from(schema.apikey).limit(1); + const now = new Date(); + + await assert.rejects( + () => + db.insert(schema.apikey).values({ + id: 'duplicate', + referenceId: alice.user.id, + key: row!.key, + createdAt: now, + updatedAt: now, + }), + (error: unknown) => { + assert.match(String((error as Error).cause), /apikey_key_idx/); + return true; + }, + ); + }); + + await t.test('deleting an account deletes its keys', async () => { + const carol = await signedIn('carol@c.example'); + const created = await auth.api.createApiKey({ body: { userId: carol.user.id } }); + + await context.internalAdapter.deleteUser(carol.user.id); + + const left = await db.select().from(schema.apikey).where(eq(schema.apikey.id, created.id)); + + assert.equal(left.length, 0); + }); + + await t.test('the plugin metadata is off', async () => { + await assert.rejects(() => + auth.api.createApiKey({ + body: { userId: alice.user.id, metadata: { plan: 'x' } }, + }), + ); + }); + + await t.test('the HTTP key endpoints answer 404 and server-side calls still work', async () => { + for (const [method, route] of [ + ['POST', '/api-key/create'], + ['POST', '/api-key/update'], + ['POST', '/api-key/delete'], + ['GET', '/api-key/list'], + ['GET', '/api-key/get?id=x'], + ] as const) { + const res = await auth.handler( + new Request(`${BASE}/api/auth${route}`, { + method, + headers: { + 'content-type': 'application/json', + cookie: alice.cookie, + origin: BASE, + }, + body: method === 'POST' ? '{}' : undefined, + }), + ); + + assert.equal(res.status, 404, route); + } + + const listed = await auth.api.listApiKeys({ + headers: new Headers({ cookie: alice.cookie, origin: BASE }), + }); + + assert.ok(listed.apiKeys.length >= 1); + }); + + await t.test('a key does not act as a session', async () => { + const created = await auth.api.createApiKey({ body: { userId: alice.user.id } }); + + for (const headers of [ + new Headers({ authorization: `Bearer ${created.key}` }), + new Headers({ 'x-api-key': created.key }), + ]) { + assert.equal(await auth.api.getSession({ headers }), null); + } + }); + + await t.test('apiRateLimit is neither settable nor readable by the account', async () => { + const update = await auth.handler( + new Request(`${BASE}/api/auth/update-user`, { + method: 'POST', + headers: { + 'content-type': 'application/json', + cookie: alice.cookie, + origin: BASE, + }, + body: JSON.stringify({ name: 'Alice', apiRateLimit: 9999 }), + }), + ); + const session = await auth.api.getSession({ + headers: new Headers({ cookie: alice.cookie }), + }); + const [row] = await db + .select({ limit: schema.user.apiRateLimit }) + .from(schema.user) + .where(eq(schema.user.id, alice.user.id)); + + assert.ok(update.status < 500); + assert.equal(row?.limit, null); + assert.equal('apiRateLimit' in (session?.user ?? {}), false); + }); +}); diff --git a/package.json b/package.json index 4ebda4e..41820eb 100644 --- a/package.json +++ b/package.json @@ -28,6 +28,7 @@ "dependencies": { "@aws-sdk/client-sesv2": "3.1150.0", "@aws-sdk/credential-providers": "3.1150.0", + "@better-auth/api-key": "1.7.7", "@developmentfinance/client": "file:vendor/developmentfinance-client-0.1.0.tgz", "@fontsource/dm-mono": "^5.3.0", "@fontsource/outfit": "^5.3.0", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 5039a66..4474da5 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -14,6 +14,9 @@ importers: '@aws-sdk/credential-providers': specifier: 3.1150.0 version: 3.1150.0 + '@better-auth/api-key': + specifier: 1.7.7 + version: 1.7.7(@better-auth/core@1.7.7(@better-auth/utils@0.4.2)(@better-fetch/fetch@1.3.2)(@opentelemetry/api@1.9.1)(better-call@1.4.0(zod@4.6.7))(jose@6.2.15)(kysely@0.29.8)(nanostores@1.5.5))(@better-auth/utils@0.4.2)(better-auth@1.7.7(@opentelemetry/api@1.9.1)(drizzle-kit@0.31.10)(drizzle-orm@0.45.2(@opentelemetry/api@1.9.1)(@types/pg@8.15.5)(kysely@0.29.8)(pg@8.23.0))(next@16.4.5(@babel/core@7.29.7)(@opentelemetry/api@1.9.1)(@types/node@22.20.5)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(sass@1.103.0))(pg@8.23.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(better-call@1.4.0(zod@4.6.7)) '@developmentfinance/client': specifier: file:vendor/developmentfinance-client-0.1.0.tgz version: file:vendor/developmentfinance-client-0.1.0.tgz(apache-arrow@21.2.0) @@ -797,6 +800,14 @@ packages: resolution: {integrity: sha512-Vj1jF3cPfxg7OAfoI7QnVKLoILlm2JF9pnVHrX8qx7AHMiYWT+NDAA7jChlNgRS4WTLc/fD1lXLmPixluj+3Gg==} engines: {node: '>=6.9.0'} + '@better-auth/api-key@1.7.7': + resolution: {integrity: sha512-XWtZxF37A7BURHh/GvsYh2Vype1p+R1ZxvQHkRzB4tK3uniZpILe2WRIXfVj3m8NIBHdg8Ez8S8sZJY/ewTu7w==} + peerDependencies: + '@better-auth/core': ^1.7.7 + '@better-auth/utils': 0.4.2 + better-auth: ^1.7.7 + better-call: 1.4.0 + '@better-auth/core@1.7.7': resolution: {integrity: sha512-srgFzHEjB2WWlokFz1i4BfG41sNhsA105Pukgqu6RrEh5A+LSkzf1mCHydVipkjt9l5qswtBMi7IL6ouHbZL4Q==} peerDependencies: @@ -7156,6 +7167,14 @@ snapshots: '@babel/helper-string-parser': 7.29.7 '@babel/helper-validator-identifier': 7.29.7 + '@better-auth/api-key@1.7.7(@better-auth/core@1.7.7(@better-auth/utils@0.4.2)(@better-fetch/fetch@1.3.2)(@opentelemetry/api@1.9.1)(better-call@1.4.0(zod@4.6.7))(jose@6.2.15)(kysely@0.29.8)(nanostores@1.5.5))(@better-auth/utils@0.4.2)(better-auth@1.7.7(@opentelemetry/api@1.9.1)(drizzle-kit@0.31.10)(drizzle-orm@0.45.2(@opentelemetry/api@1.9.1)(@types/pg@8.15.5)(kysely@0.29.8)(pg@8.23.0))(next@16.4.5(@babel/core@7.29.7)(@opentelemetry/api@1.9.1)(@types/node@22.20.5)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(sass@1.103.0))(pg@8.23.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(better-call@1.4.0(zod@4.6.7))': + dependencies: + '@better-auth/core': 1.7.7(@better-auth/utils@0.4.2)(@better-fetch/fetch@1.3.2)(@opentelemetry/api@1.9.1)(better-call@1.4.0(zod@4.6.7))(jose@6.2.15)(kysely@0.29.8)(nanostores@1.5.5) + '@better-auth/utils': 0.4.2 + better-auth: 1.7.7(@opentelemetry/api@1.9.1)(drizzle-kit@0.31.10)(drizzle-orm@0.45.2(@opentelemetry/api@1.9.1)(@types/pg@8.15.5)(kysely@0.29.8)(pg@8.23.0))(next@16.4.5(@babel/core@7.29.7)(@opentelemetry/api@1.9.1)(@types/node@22.20.5)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(sass@1.103.0))(pg@8.23.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8) + better-call: 1.4.0(zod@4.6.7) + zod: 4.6.7 + '@better-auth/core@1.7.7(@better-auth/utils@0.4.2)(@better-fetch/fetch@1.3.2)(@opentelemetry/api@1.9.1)(better-call@1.4.0(zod@4.6.7))(jose@6.2.15)(kysely@0.29.8)(nanostores@1.5.5)': dependencies: '@better-auth/utils': 0.4.2 diff --git a/src/lib/auth/apiKeyOptions.ts b/src/lib/auth/apiKeyOptions.ts new file mode 100644 index 0000000..d3df47d --- /dev/null +++ b/src/lib/auth/apiKeyOptions.ts @@ -0,0 +1,36 @@ +import { apiKey } from '@better-auth/api-key'; + +/** The key prefix. A secret scanner and our own logs can spot it. */ +export const API_KEY_PREFIX = 'dfo_live_'; + +/** + * The plugin's HTTP endpoints for managing keys. They stay off the router: + * a signed-in user could otherwise mint a key with any prefix, switch a key + * an operator disabled back on, or remove an expiry. Better Auth checks + * `disabledPaths` only in its HTTP router, so server code still reaches + * `auth.api.createApiKey` and the rest (our own routes and the admin + * command wrap those, forcing the prefix and the owner). + */ +export const API_KEY_PATHS: readonly string[] = [ + '/api-key/create', + '/api-key/update', + '/api-key/delete', + '/api-key/list', + '/api-key/get', +]; + +/** + * The `@better-auth/api-key` plugin, set up so the proxy owns the request + * path (src/lib/proxy/keyVerifier): the plugin's own limiter, metadata and + * key-as-session are off. A key as a session would let it act as its owner + * on every /api/auth/* endpoint, account deletion included. + */ +export const apiKeyPlugin = (overrides: Parameters[0] = {}) => + apiKey({ + defaultPrefix: API_KEY_PREFIX, + defaultKeyLength: 32, + rateLimit: { enabled: false }, + enableSessionForAPIKeys: false, + enableMetadata: false, + ...overrides, + }); diff --git a/src/lib/auth/auth.ts b/src/lib/auth/auth.ts index 71065e5..1352c65 100644 --- a/src/lib/auth/auth.ts +++ b/src/lib/auth/auth.ts @@ -5,6 +5,7 @@ import { nextCookies } from 'better-auth/next-js'; import { counterDb, db } from '@/lib/db'; import * as schema from '../../../db/schema'; +import { API_KEY_PATHS, apiKeyPlugin } from '@/lib/auth/apiKeyOptions'; import { CLIENT_IP_HEADER } from '@/lib/auth/clientIp'; import { TOKEN_PATHS } from '@/lib/auth/closedPaths'; import { takeCodeAllowance } from '@/lib/auth/codeLimit'; @@ -102,6 +103,9 @@ export const auth = betterAuth({ // share token is stored for it meanwhile. Never sent or accepted. additionalFields: { deletingAt: { type: 'date', required: false, input: false, returned: false }, + // The account's API-key limit, calls per window, set by an + // operator. Null is the default (RATE_LIMIT_KEYED). + apiRateLimit: { type: 'number', required: false, input: false, returned: false }, }, // Delete account (account menu). With no password to confirm with, // Better Auth asks for a fresh session instead (session.freshAge). @@ -142,8 +146,9 @@ export const auth = betterAuth({ advanced: { ipAddress: { ipAddressHeaders: [CLIENT_IP_HEADER] }, }, - // The token endpoints answer 404 to the browser (closedPaths). - disabledPaths: [...TOKEN_PATHS, ...(emailOptions?.disabledPaths ?? [])], + // The token endpoints answer 404 to the browser (closedPaths), and so do + // the API key plugin's management endpoints (apiKeyOptions). + disabledPaths: [...TOKEN_PATHS, ...API_KEY_PATHS, ...(emailOptions?.disabledPaths ?? [])], hooks: { // A provider callback or an email code that ended in a session is a // sign-in. The usage event carries the provider only. @@ -165,6 +170,8 @@ export const auth = betterAuth({ }, plugins: [ ...(emailOptions?.plugins ?? []), + // API keys for the platform proxy. The proxy verifies them itself. + apiKeyPlugin(), // Lets server actions / route handlers set the session cookie. Last, // as Better Auth asks. nextCookies(), From 433f6711f7f870076d7c141dc8201c440787128b Mon Sep 17 00:00:00 2001 From: Sef Kloninger Date: Mon, 16 Nov 2026 12:01:38 -0800 Subject: [PATCH 18/34] feat(proxy): add the API key parser and the key verifier (#142) readApiKey reads a key from `Authorization: Bearer dfo_...` or `X-API-Key`: a bearer that is not a dfo_ key is no key, two different keys conflict, and a value over 128 characters is refused unread. createKeyVerifier answers valid, invalid or unavailable for a key without calling the plugin's verifyApiKey, which writes to the key row on every call and reports an outage as an invalid key. It hashes with the plugin's own hasher, reads apikey joined to user.api_rate_limit on its own small bounded pool (buildKeyPool), checks enabled and expires_at itself, and caches in process: valid for an absolute minute and never past the key's expiry, invalid for 30 s, unavailable not at all, with one read per key at a time and bounded memory. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf --- db/connection.ts | 16 ++ src/lib/db/index.ts | 12 +- src/lib/proxy/apiKey.ts | 58 +++++ src/lib/proxy/keyVerifier.ts | 225 ++++++++++++++++++ src/lib/proxy/test/apiKey.test.ts | 79 +++++++ src/lib/proxy/test/keyVerifier.test.ts | 308 +++++++++++++++++++++++++ 6 files changed, 696 insertions(+), 2 deletions(-) create mode 100644 src/lib/proxy/apiKey.ts create mode 100644 src/lib/proxy/keyVerifier.ts create mode 100644 src/lib/proxy/test/apiKey.test.ts create mode 100644 src/lib/proxy/test/keyVerifier.test.ts diff --git a/db/connection.ts b/db/connection.ts index 8aeb31b..b82d5d0 100644 --- a/db/connection.ts +++ b/db/connection.ts @@ -266,3 +266,19 @@ export function buildCounterPool(env: EnvLike = process.env): Pool { statement_timeout: 400, }); } + +/** + * A small, bounded pool for the proxy's API key lookups (src/lib/proxy/ + * keyVerifier), apart from the counters' so a slow key store does not slow + * the counts, and the other way round. A lookup gives up in 400 ms in + * Postgres, 500 ms in the client, or 1 s waiting for a connection, and the + * proxy then treats the key store as unavailable. + */ +export function buildKeyPool(env: EnvLike = process.env): Pool { + return buildRuntimePool(env, { + max: 2, + connectionTimeoutMillis: 1_000, + query_timeout: 500, + statement_timeout: 400, + }); +} diff --git a/src/lib/db/index.ts b/src/lib/db/index.ts index 7ed4a74..170f418 100644 --- a/src/lib/db/index.ts +++ b/src/lib/db/index.ts @@ -1,7 +1,7 @@ import { drizzle } from 'drizzle-orm/node-postgres'; import { Pool } from 'pg'; -import { buildCounterPool, buildRuntimePool } from '../../../db/connection'; +import { buildCounterPool, buildKeyPool, buildRuntimePool } from '../../../db/connection'; import * as schema from '../../../db/schema'; /** @@ -14,7 +14,7 @@ import * as schema from '../../../db/schema'; * is safe to call at import time: nothing in it throws with no DB env at * all, which is how `next build` runs. */ -const globalForDb = globalThis as unknown as { pool?: Pool; counterPool?: Pool }; +const globalForDb = globalThis as unknown as { pool?: Pool; counterPool?: Pool; keyPool?: Pool }; const pool = globalForDb.pool ?? buildRuntimePool(); @@ -26,8 +26,13 @@ const pool = globalForDb.pool ?? buildRuntimePool(); // quiet instance does again after 30 s idle. const counterPool = globalForDb.counterPool ?? buildCounterPool(); +// The proxy's API key lookups get a pool of their own for the same reason, +// with a tighter connect bound (buildKeyPool). +const keyPool = globalForDb.keyPool ?? buildKeyPool(); + globalForDb.pool = pool; globalForDb.counterPool = counterPool; +globalForDb.keyPool = keyPool; /** Accounts, conversation history, and shares. */ export const db = drizzle(pool, { schema }); @@ -35,4 +40,7 @@ export const db = drizzle(pool, { schema }); /** Per-address rate limits, Studio prompt allowances and sign-in code caps. */ export const counterDb = drizzle(counterPool, { schema }); +/** The proxy's API key lookups (src/lib/proxy/keyVerifier). */ +export const keyDb = drizzle(keyPool, { schema }); + export type Db = typeof db; diff --git a/src/lib/proxy/apiKey.ts b/src/lib/proxy/apiKey.ts new file mode 100644 index 0000000..2a60ad0 --- /dev/null +++ b/src/lib/proxy/apiKey.ts @@ -0,0 +1,58 @@ +/** + * Where an API key is read from on a call to the platform proxy, kept apart + * from the route so `node --test` can load it. + * + * A key is `Authorization: Bearer dfo_…` or `X-API-Key: …`. A bearer that + * does not start with `dfo_` is not a key, whatever else it is (the harness + * token on /mcp, say), so it is left alone and the call is handled as it was + * before keys. `X-API-Key` always names a key. A call that sends both with + * different values is refused, and a value over MAX_KEY_LENGTH is refused + * unread. The key is never put in a query string. + */ + +/** The prefix every key carries (API_KEY_PREFIX in src/lib/auth/apiKeyOptions). */ +const KEY_PREFIX = 'dfo_'; + +/** Keys are `dfo_live_` and 32 characters; this leaves room and no more. */ +export const MAX_KEY_LENGTH = 128; + +export const API_KEY_HEADER = 'x-api-key'; + +export type KeyRead = + // No key on the call. + | { kind: 'none' } + | { kind: 'key'; key: string } + // Both headers, with different values. + | { kind: 'conflict' } + // A value past MAX_KEY_LENGTH. + | { kind: 'too-long' }; + +const BEARER = /^bearer\s+(\S.*)$/i; + +/** The `dfo_…` token in an Authorization value, or undefined when it is anything else. */ +export const bearerKey = (authorization: string | null): string | undefined => { + const token = authorization?.trim().match(BEARER)?.[1]?.trim(); + + return token?.startsWith(KEY_PREFIX) ? token : undefined; +}; + +/** The key a call carries, if any. */ +export const readApiKey = (headers: Headers): KeyRead => { + const bearer = bearerKey(headers.get('authorization')); + const alias = headers.get(API_KEY_HEADER)?.trim() || undefined; + + if (bearer !== undefined && alias !== undefined && bearer !== alias) { + return { kind: 'conflict' }; + } + + const key = bearer ?? alias; + + if (key === undefined) { + return { kind: 'none' }; + } + + return key.length > MAX_KEY_LENGTH ? { kind: 'too-long' } : { kind: 'key', key }; +}; + +/** Whether `key` has the shape of one of ours, so a lookup could find it. */ +export const hasKeyPrefix = (key: string): boolean => key.startsWith(KEY_PREFIX); diff --git a/src/lib/proxy/keyVerifier.ts b/src/lib/proxy/keyVerifier.ts new file mode 100644 index 0000000..38424bd --- /dev/null +++ b/src/lib/proxy/keyVerifier.ts @@ -0,0 +1,225 @@ +import { defaultKeyHasher } from '@better-auth/api-key'; +import { eq } from 'drizzle-orm'; +import type { NodePgDatabase } from 'drizzle-orm/node-postgres'; + +import { apikey, user } from '../../../db/schema.ts'; +import { hasKeyPrefix } from './apiKey.ts'; + +/** + * Looks an API key up for the platform proxy (src/lib/proxy/forward). The + * key store is the `apikey` table of the `@better-auth/api-key` plugin, in + * the website's Postgres, and the plugin's own `verifyApiKey` is not used + * here: it writes to the key's row on every call and reports a database + * outage as an invalid key. This reads the row itself, keyed by the plugin's + * own hash of the key (`defaultKeyHasher`: base64url SHA-256), joined to the + * owning account's limit (`user.api_rate_limit`), and checks `enabled` and + * `expires_at` itself. + * + * The answer is one of three, so the proxy can tell a bad key from a store it + * cannot reach: + * valid the key's public id, its account, the account's own limit + * (null for the deployment default) and when the key expires + * invalid no such key, disabled, or expired + * unavailable the read threw or timed out; the proxy fails open + * + * A small in-process cache keeps the common call off the database. A valid + * entry lives CACHE_VALID_MS from the read, never extended, and never past + * the key's own expiry, so a key deleted or an account limit lowered takes + * effect on an instance within that time even while the store is down. An + * invalid entry lives CACHE_INVALID_MS. An unavailable answer is not cached. + * Neither the key nor its hash leaves this module except as the cache key + * (hash only, in memory). + */ +export type KeyVerdict = + | { + kind: 'valid'; + // The plugin's `apikey.id`, the public name of the key in logs. + keyId: string; + accountId: string; + // The account's own calls per window, or null for the default. + rateLimit: number | null; + expiresAt: Date | null; + } + | { kind: 'invalid' } + | { kind: 'unavailable' }; + +export type ValidKey = Extract; + +export const CACHE_VALID_MS = 60_000; +export const CACHE_INVALID_MS = 30_000; +const CACHE_MAX_ENTRIES = 5_000; + +/** Reads only; the pool behind it is src/lib/db's keyDb. */ +export type KeyDb = Pick; + +type Row = { + id: string; + referenceId: string; + enabled: boolean | null; + expiresAt: Date | null; + apiRateLimit: number | null; +}; + +type Entry = { verdict: KeyVerdict; until: number }; + +// A bounded map of verdicts by key hash. Insertion order is age, so a full +// map drops its oldest entry (after dropping whatever has expired). +const boundedCache = (max: number, now: () => number) => { + const entries = new Map(); + + return { + get(hash: string): KeyVerdict | undefined { + const entry = entries.get(hash); + + if (!entry) { + return undefined; + } + + if (entry.until <= now()) { + entries.delete(hash); + + return undefined; + } + + return entry.verdict; + }, + set(hash: string, verdict: KeyVerdict, until: number): void { + entries.delete(hash); + + if (entries.size >= max) { + for (const [key, entry] of entries) { + if (entry.until <= now()) { + entries.delete(key); + } + } + } + + if (entries.size >= max) { + entries.delete(entries.keys().next().value!); + } + + entries.set(hash, { verdict, until }); + }, + size: () => entries.size, + }; +}; + +/** A positive whole number is an account's own limit; anything else is the default. */ +const ownLimit = (value: number | null): number | null => + typeof value === 'number' && Number.isSafeInteger(value) && value >= 1 ? value : null; + +export type KeyVerifier = { + /** The verdict for `key`: from the cache, else one read of the key store. */ + verify(key: string): Promise; + /** + * The cached verdict for `key` when it is a valid one, which answers + * without a lookup, and undefined otherwise. + */ + cachedValid(key: string): Promise; + /** How many verdicts are cached, valid and invalid together. */ + cacheSize(): number; +}; + +export const createKeyVerifier = ( + db: KeyDb, + { + now = Date.now, + validMs = CACHE_VALID_MS, + invalidMs = CACHE_INVALID_MS, + maxEntries = CACHE_MAX_ENTRIES, + log = console.warn, + }: { + now?: () => number; + validMs?: number; + invalidMs?: number; + maxEntries?: number; + log?: (message: string, error: unknown) => void; + } = {}, +): KeyVerifier => { + // Apart, so a flood of made-up keys cannot push real ones out. + const valid = boundedCache(maxEntries, now); + const invalid = boundedCache(maxEntries, now); + // One read per hash at a time: callers arriving during it share it. + const reading = new Map>(); + + const read = async (hash: string): Promise => { + let rows: Row[]; + + try { + rows = await db + .select({ + id: apikey.id, + referenceId: apikey.referenceId, + enabled: apikey.enabled, + expiresAt: apikey.expiresAt, + apiRateLimit: user.apiRateLimit, + }) + .from(apikey) + .innerJoin(user, eq(user.id, apikey.referenceId)) + .where(eq(apikey.key, hash)) + .limit(1); + } catch (error) { + log('api key store unavailable, treating the call as anonymous', error); + + return { kind: 'unavailable' }; + } + + const row = rows[0]; + const at = now(); + + if (!row || row.enabled === false || (row.expiresAt && row.expiresAt.getTime() <= at)) { + invalid.set(hash, { kind: 'invalid' }, at + invalidMs); + + return { kind: 'invalid' }; + } + + const verdict: ValidKey = { + kind: 'valid', + keyId: row.id, + accountId: row.referenceId, + rateLimit: ownLimit(row.apiRateLimit), + expiresAt: row.expiresAt, + }; + + valid.set(hash, verdict, Math.min(at + validMs, row.expiresAt?.getTime() ?? Infinity)); + + return verdict; + }; + + const cached = (hash: string): KeyVerdict | undefined => valid.get(hash) ?? invalid.get(hash); + + return { + cacheSize: () => valid.size() + invalid.size(), + async cachedValid(key) { + if (!hasKeyPrefix(key)) { + return undefined; + } + + const verdict = valid.get(await defaultKeyHasher(key)); + + return verdict?.kind === 'valid' ? verdict : undefined; + }, + async verify(key) { + // Nothing of ours is shaped otherwise, so there is nothing to look up. + if (!hasKeyPrefix(key)) { + return { kind: 'invalid' }; + } + + const hash = await defaultKeyHasher(key); + const known = cached(hash); + + if (known) { + return known; + } + + let pending = reading.get(hash); + + if (!pending) { + pending = read(hash).finally(() => reading.delete(hash)); + reading.set(hash, pending); + } + + return pending; + }, + }; +}; diff --git a/src/lib/proxy/test/apiKey.test.ts b/src/lib/proxy/test/apiKey.test.ts new file mode 100644 index 0000000..f7762c6 --- /dev/null +++ b/src/lib/proxy/test/apiKey.test.ts @@ -0,0 +1,79 @@ +/** + * `apiKey.ts`: where a call's API key is read from. A `dfo_` bearer or + * `X-API-Key` is a key, any other bearer is not, two different keys are a + * conflict, and an over-long value is refused unread. + */ +import assert from 'node:assert/strict'; +import test from 'node:test'; + +import { bearerKey, MAX_KEY_LENGTH, readApiKey } from '../apiKey.ts'; + +const KEY = `dfo_live_${'a'.repeat(32)}`; +const read = (headers: Record) => readApiKey(new Headers(headers)); + +test('readApiKey: no headers is no key', () => { + assert.deepEqual(read({}), { kind: 'none' }); +}); + +test('readApiKey: a dfo_ bearer is a key, whatever the scheme case or spacing', () => { + for (const value of [`Bearer ${KEY}`, `bearer ${KEY}`, `BEARER ${KEY} `]) { + assert.deepEqual(read({ authorization: value }), { kind: 'key', key: KEY }, value); + } +}); + +test('readApiKey: X-API-Key is a key', () => { + assert.deepEqual(read({ 'x-api-key': KEY }), { kind: 'key', key: KEY }); + assert.deepEqual(read({ 'X-API-Key': ` ${KEY} ` }), { kind: 'key', key: KEY }); +}); + +test('readApiKey: a bearer that is not a dfo_ key is not a key', () => { + for (const value of ['Bearer sk-live-123', 'Bearer eyJhbGciOi.payload.sig', 'Bearer DFO_X']) { + assert.deepEqual(read({ authorization: value }), { kind: 'none' }, value); + } + + // Other schemes are not ours either, even with our prefix in them. + assert.deepEqual(read({ authorization: `Basic ${KEY}` }), { kind: 'none' }); + assert.deepEqual(read({ authorization: `Token ${KEY}` }), { kind: 'none' }); +}); + +test('readApiKey: a foreign bearer beside X-API-Key leaves the key to X-API-Key', () => { + assert.deepEqual(read({ authorization: 'Bearer harness-token', 'x-api-key': KEY }), { + kind: 'key', + key: KEY, + }); +}); + +test('readApiKey: both headers with one value are one key', () => { + assert.deepEqual(read({ authorization: `Bearer ${KEY}`, 'x-api-key': KEY }), { + kind: 'key', + key: KEY, + }); +}); + +test('readApiKey: both headers with different values conflict', () => { + assert.deepEqual(read({ authorization: `Bearer ${KEY}`, 'x-api-key': `${KEY}b` }), { + kind: 'conflict', + }); + assert.deepEqual(read({ authorization: `Bearer ${KEY}`, 'x-api-key': 'other' }), { + kind: 'conflict', + }); +}); + +test('readApiKey: a blank X-API-Key is no key', () => { + assert.deepEqual(read({ 'x-api-key': ' ' }), { kind: 'none' }); +}); + +test('readApiKey: a value over the maximum length is refused unread', () => { + const long = `dfo_${'x'.repeat(MAX_KEY_LENGTH)}`; + + assert.deepEqual(read({ authorization: `Bearer ${long}` }), { kind: 'too-long' }); + assert.deepEqual(read({ 'x-api-key': long }), { kind: 'too-long' }); + assert.deepEqual(read({ 'x-api-key': 'd'.repeat(MAX_KEY_LENGTH) }).kind, 'key'); + assert.deepEqual(read({ 'x-api-key': 'd'.repeat(MAX_KEY_LENGTH + 1) }).kind, 'too-long'); +}); + +test('bearerKey: names the key in an Authorization value, or nothing', () => { + assert.equal(bearerKey(`Bearer ${KEY}`), KEY); + assert.equal(bearerKey('Bearer abc'), undefined); + assert.equal(bearerKey(null), undefined); +}); diff --git a/src/lib/proxy/test/keyVerifier.test.ts b/src/lib/proxy/test/keyVerifier.test.ts new file mode 100644 index 0000000..56f6e21 --- /dev/null +++ b/src/lib/proxy/test/keyVerifier.test.ts @@ -0,0 +1,308 @@ +/** + * `keyVerifier.ts` on a migrated database, as the runtime role: a valid key, + * and what makes one invalid (unknown, disabled, expired, not ours), an + * unavailable key store (a closed port, a table lock that outlasts the + * statement timeout), and the cache's lifetimes, expiry bound, bound on size + * and single read. + */ +import '../../test/serverModules.ts'; + +import assert from 'node:assert/strict'; +import path from 'node:path'; +import test from 'node:test'; + +import { defaultKeyHasher } from '@better-auth/api-key'; +import { drizzle } from 'drizzle-orm/node-postgres'; +import { Pool } from 'pg'; + +import { applyMigrations } from '../../../../db/apply-migrations.ts'; +import { buildKeyPool } from '../../../../db/connection.ts'; +import * as schema from '../../../../db/schema.ts'; +import { createTestDatabase } from '../../../../db/test/harness.ts'; + +const { CACHE_INVALID_MS, CACHE_VALID_MS, createKeyVerifier } = await import('../keyVerifier.ts'); + +const MIGRATIONS_FOLDER = path.resolve(import.meta.dirname, '../../../../db/migrations'); + +const keyOf = (name: string) => `dfo_live_${name.padEnd(32, '0')}`; + +test('keyVerifier on the key store', async (t) => { + const database = await createTestDatabase(); + + await applyMigrations(database.migratorPool(), { + migrationsFolder: MIGRATIONS_FOLDER, + runtimeDbUser: database.runtimeUser, + migratorDbUser: database.migratorUser, + }); + + const admin = database.adminPool(); + const host = process.env.PGHOST ?? 'localhost'; + const port = process.env.PGPORT ?? '5433'; + const url = `postgres://${database.runtimeUser}:${database.runtimePassword}@${host}:${port}/${database.databaseName}`; + + const pool = buildKeyPool({ DATABASE_URL: url }); + + t.after(async () => { + await pool.end(); + await database.teardown(); + }); + + const db = drizzle(pool, { schema }); + + for (const [id, limit] of [ + ['acct-default', null], + ['acct-250', 250], + ['acct-zero', 0], + ] as const) { + await admin.query( + `insert into "user" (id, name, email, email_verified, created_at, updated_at, api_rate_limit) + values ($1, $1, $1 || '@a.example', true, now(), now(), $2)`, + [id, limit], + ); + } + + const addKey = async ( + name: string, + account: string, + { enabled = true, expiresAt = null }: { enabled?: boolean; expiresAt?: Date | null } = {}, + ) => { + const key = keyOf(name); + + await admin.query( + `insert into apikey (id, reference_id, key, enabled, expires_at, created_at, updated_at) + values ($1, $2, $3, $4, $5, now(), now())`, + // The column has no time zone, which Drizzle reads as UTC. + [ + `id-${name}`, + account, + await defaultKeyHasher(key), + enabled, + expiresAt?.toISOString().replace('Z', '') ?? null, + ], + ); + + return key; + }; + + const live = await addKey('live', 'acct-default'); + const own = await addKey('own', 'acct-250'); + const zero = await addKey('zero', 'acct-zero'); + const disabled = await addKey('disabled', 'acct-default', { enabled: false }); + const expired = await addKey('expired', 'acct-default', { + expiresAt: new Date(Date.now() - 1000), + }); + + await t.test('a valid key names its public id, account, limit and expiry', async () => { + const verifier = createKeyVerifier(db); + + assert.deepEqual(await verifier.verify(live), { + kind: 'valid', + keyId: 'id-live', + accountId: 'acct-default', + rateLimit: null, + expiresAt: null, + }); + assert.equal( + await verifier.verify(own).then((v) => v.kind === 'valid' && v.rateLimit), + 250, + ); + // A limit that is not a positive whole number is the default. + assert.equal( + await verifier.verify(zero).then((v) => v.kind === 'valid' && v.rateLimit), + null, + ); + }); + + await t.test('unknown, disabled, expired and foreign-shaped keys are invalid', async () => { + const verifier = createKeyVerifier(db); + + for (const key of [keyOf('nobody'), disabled, expired, 'not-our-key', '']) { + assert.deepEqual(await verifier.verify(key), { kind: 'invalid' }, key); + } + }); + + await t.test('a lookup writes nothing to the key store', async () => { + const before = await admin.query( + `select id, request_count, last_request, updated_at, remaining from apikey order by id`, + ); + + const verifier = createKeyVerifier(db); + + await verifier.verify(live); + await verifier.verify(expired); + + const after = await admin.query( + `select id, request_count, last_request, updated_at, remaining from apikey order by id`, + ); + + assert.deepEqual(after.rows, before.rows); + assert.equal( + (await admin.query('select 1 from apikey where id = $1', ['id-expired'])).rowCount, + 1, + ); + }); + + await t.test('a valid answer is cached for an absolute minute, never extended', async () => { + let clock = 1_000_000; + const reads: string[] = []; + const verifier = createKeyVerifier(db, { now: () => clock }); + const sql = pool.query.bind(pool) as (...args: unknown[]) => unknown; + + (pool as unknown as { query: unknown }).query = (...args: unknown[]) => { + reads.push(String((args[0] as { text?: string }).text ?? args[0])); + + return sql(...args); + }; + t.after(() => { + (pool as unknown as { query: unknown }).query = sql; + }); + + assert.equal((await verifier.verify(live)).kind, 'valid'); + assert.equal(reads.length, 1); + + clock += CACHE_VALID_MS - 1; + assert.equal((await verifier.cachedValid(live))?.kind, 'valid'); + assert.equal((await verifier.verify(live)).kind, 'valid'); + assert.equal(reads.length, 1); + + // A deleted key is gone once the minute is up, however often it was used. + await admin.query('delete from apikey where id = $1', ['id-live']); + clock += 1; + assert.equal(await verifier.cachedValid(live), undefined); + assert.deepEqual(await verifier.verify(live), { kind: 'invalid' }); + assert.equal(reads.length, 2); + + await admin.query( + `insert into apikey (id, reference_id, key, created_at, updated_at) + values ('id-live', 'acct-default', $1, now(), now())`, + [await defaultKeyHasher(live)], + ); + }); + + await t.test( + 'the cache never outlives the key: an expiry sooner than a minute wins', + async () => { + let clock = Date.now(); + const soon = await addKey('soon', 'acct-default', { + expiresAt: new Date(clock + 5_000), + }); + const verifier = createKeyVerifier(db, { now: () => clock }); + + assert.equal((await verifier.verify(soon)).kind, 'valid'); + + clock += 4_999; + assert.equal((await verifier.cachedValid(soon))?.kind, 'valid'); + + clock += 2; + assert.equal(await verifier.cachedValid(soon), undefined); + assert.deepEqual(await verifier.verify(soon), { kind: 'invalid' }); + }, + ); + + await t.test( + 'an invalid answer is cached briefly, and a key added later is found after it', + async () => { + let clock = 1_000_000; + const verifier = createKeyVerifier(db, { now: () => clock }); + const later = keyOf('later'); + + assert.deepEqual(await verifier.verify(later), { kind: 'invalid' }); + await addKey('later', 'acct-default'); + assert.deepEqual(await verifier.verify(later), { kind: 'invalid' }); + + clock += CACHE_INVALID_MS; + assert.equal((await verifier.verify(later)).kind, 'valid'); + }, + ); + + await t.test('concurrent lookups of one key share one read', async () => { + const verifier = createKeyVerifier(db); + const verdicts = await Promise.all(Array.from({ length: 20 }, () => verifier.verify(own))); + + assert.ok(verdicts.every((verdict) => verdict.kind === 'valid')); + }); + + await t.test('the cache is bounded, and made-up keys do not push valid ones out', async () => { + const verifier = createKeyVerifier(db, { maxEntries: 3 }); + + assert.equal((await verifier.verify(live)).kind, 'valid'); + + for (let i = 0; i < 20; i++) { + await verifier.verify(keyOf(`bogus${i}`)); + } + + assert.equal(verifier.cacheSize(), 1 + 3); + assert.equal((await verifier.cachedValid(live))?.kind, 'valid'); + }); + + await t.test('a store that cannot be reached is unavailable, and not cached', async () => { + const logged: string[] = []; + const deadPool = new Pool({ + host: '127.0.0.1', + port: 1, + user: 'x', + database: 'x', + connectionTimeoutMillis: 500, + max: 1, + }); + + deadPool.on('error', () => {}); + t.after(() => deadPool.end()); + + const verifier = createKeyVerifier(drizzle(deadPool, { schema }), { + log: (message) => logged.push(message), + }); + + assert.deepEqual(await verifier.verify(live), { kind: 'unavailable' }); + assert.equal(verifier.cacheSize(), 0); + assert.equal(logged.length, 1); + assert.doesNotMatch(logged.join(), /dfo_/); + }); + + await t.test('a read that outlasts the statement timeout is unavailable', async () => { + const verifier = createKeyVerifier(db, { log: () => {} }); + const blocker = database.adminPool(); + const client = await blocker.connect(); + + try { + await client.query('begin'); + await client.query('lock table apikey in access exclusive mode'); + + const started = Date.now(); + + assert.deepEqual(await verifier.verify(own), { kind: 'unavailable' }); + assert.ok(Date.now() - started < 2_000); + } finally { + await client.query('rollback'); + client.release(); + } + + assert.equal(verifier.cacheSize(), 0); + assert.equal((await verifier.verify(own)).kind, 'valid'); + }); + + await t.test( + 'a cached valid key keeps answering while the store is down, until its minute ends', + async () => { + let clock = 1_000_000; + const flaky = { + down: false, + select: (...args: Parameters) => + flaky.down ? (undefined as never) : db.select(...args), + }; + const verifier = createKeyVerifier(flaky as unknown as typeof db, { + now: () => clock, + log: () => {}, + }); + + assert.equal((await verifier.verify(own)).kind, 'valid'); + flaky.down = true; + + clock += CACHE_VALID_MS - 1; + assert.equal((await verifier.verify(own)).kind, 'valid'); + + clock += 1; + assert.deepEqual(await verifier.verify(own), { kind: 'unavailable' }); + }, + ); +}); From cb3c4c9ebbff91aef24d0507988ccc2a63ce7f80 Mon Sep 17 00:00:00 2001 From: Sef Kloninger Date: Mon, 16 Nov 2026 12:02:15 -0800 Subject: [PATCH 19/34] feat(proxy): count calls with an API key against their account (#142) forward() now decides each call once (access.ts) before the limiter, on the API and MCP surfaces. No key: anonymous, counted by address as before. A valid key in the cache: counted against the key's account. Any other key: counted against the address first, then looked up. Invalid is a 401 problem document and not anonymous, an unavailable key store goes on as anonymous, and two different keys are a 400. The account's limit is its own user.api_rate_limit or RATE_LIMIT_KEYED (default 600), applied to each surface apart; API_KEYS_ENABLED=false strips keys and treats every call as anonymous. A dfo_ bearer and X-API-Key never go upstream, whether or not the key verified; any other Authorization behaves as before. The Studio strips a key and ignores it. A keyed call is named user: to dfo-apis and to /mcp's upstream, resolved once in forward(). /openapi.json declares the optional key as a security scheme. The limiter takes a caller key and a limit, and a shared count that fails or times out is now counted in memory per instance instead of passing uncounted. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf --- .env.example | 10 +- deploy/README.md | 2 + src/app/api/v1/studio/[...path]/route.ts | 3 + src/app/mcp/[[...path]]/route.ts | 10 +- src/lib/proxy/access.ts | 150 ++++++++ src/lib/proxy/caller.ts | 29 +- src/lib/proxy/forward.ts | 86 ++++- src/lib/proxy/limitFallback.ts | 64 ++++ src/lib/proxy/openapi.ts | 30 +- src/lib/proxy/problem.ts | 30 +- src/lib/proxy/rateHeaders.ts | 5 +- src/lib/proxy/rateLimit.ts | 120 +++--- src/lib/proxy/test/access.test.ts | 246 +++++++++++++ src/lib/proxy/test/caller.test.ts | 21 ++ src/lib/proxy/test/forwardKeys.test.ts | 442 +++++++++++++++++++++++ src/lib/proxy/test/limitFallback.test.ts | 65 ++++ src/lib/proxy/test/openapi.test.ts | 31 ++ src/lib/proxy/test/rateLimit.test.ts | 120 ++++++ 18 files changed, 1390 insertions(+), 74 deletions(-) create mode 100644 src/lib/proxy/access.ts create mode 100644 src/lib/proxy/limitFallback.ts create mode 100644 src/lib/proxy/test/access.test.ts create mode 100644 src/lib/proxy/test/forwardKeys.test.ts create mode 100644 src/lib/proxy/test/limitFallback.test.ts create mode 100644 src/lib/proxy/test/rateLimit.test.ts diff --git a/.env.example b/.env.example index dc29e98..075e9c7 100644 --- a/.env.example +++ b/.env.example @@ -116,13 +116,21 @@ SENTRY_AUTH_TOKEN= # RATE_LIMIT_PIN=10 # /mcp is higher because a vendor's address can carry many users. # RATE_LIMIT_MCP=300 +# A call with a valid API key (`Authorization: Bearer dfo_...` or `X-API-Key`) +# is counted against the key's account instead of its address: this many calls +# per window on each of /api and /mcp, for an account with no limit of its own +# (user.api_rate_limit). Keys are the proxy's own; the Studio ignores them. +# RATE_LIMIT_KEYED=600 +# Emergency switch: false strips keys and counts every call by address. +# API_KEYS_ENABLED=true # The harness's own token for its MCP server (MCP_API_TOKEN on dfo-ai); # attached by the proxy so outside MCP clients don't need it. Unset: the # caller's own Authorization header is passed through. MCP_API_TOKEN= # /mcp names each caller to dfo-ai, and the dfo-apis proxy to dfo-apis, as # x-dfo-caller: ip:, an HMAC-SHA-256 of the client address (an IPv6 -# address as its /64) keyed by this secret (e.g. openssl rand -hex 32). It +# address as its /64) keyed by this secret, or user: of the account for +# a call with an API key (e.g. openssl rand -hex 32). It # must equal dfo-apis's DFO_CALLER_HMAC_KEY. If unset, no caller is sent and # the site logs one warning. CALLER_HMAC_KEY= diff --git a/deploy/README.md b/deploy/README.md index 408e320..7ee3940 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -251,6 +251,8 @@ The app defines the definitive contract once it exists. Known so far: | `RATE_LIMIT_API` | Calls per window per address on `/api`; default 120 | | `RATE_LIMIT_PIN` | Calls per window per address on `/api/download-pin`; default 10 | | `RATE_LIMIT_MCP` | Requests per window per address on `/mcp`; default 300, above `/api` because a vendor's address can carry many users | +| `RATE_LIMIT_KEYED` | Calls per window per account, on each of `/api` and `/mcp`, for a call with a valid API key whose account has no limit of its own (`user.api_rate_limit`); default 600 | +| `API_KEYS_ENABLED` | Emergency switch for API keys; default on. `false`, `0`, `off` or `no` strips keys and counts every call by address, without a code change | | `OPENAI_APPS_CHALLENGE` | OpenAI's domain-verification token; `/.well-known/openai-apps-challenge` serves it as plain text, 404 while unset | | `TRUSTED_PROXY_HOPS` | Which `X-Forwarded-For` entry is the client, counted from the right; keys the `/api` and `/mcp` limits, the guest Studio allowance and the caller digest; default 0 (Cloud Run's); +1 per load balancer | | `WEBSITE_DB_INSTANCE_CONNECTION_NAME` | Cloud SQL instance the connector dials over PSC; set by infra | diff --git a/src/app/api/v1/studio/[...path]/route.ts b/src/app/api/v1/studio/[...path]/route.ts index d1e2ad5..d35142a 100644 --- a/src/app/api/v1/studio/[...path]/route.ts +++ b/src/app/api/v1/studio/[...path]/route.ts @@ -35,6 +35,9 @@ const proxy = async (req: NextRequest, { params }: { params: Promise<{ path: str const options = { surface: 'api', + // The Studio is the site's own chat UI: an API key sent here is + // stripped and ignored, and never lifts the prompt allowance. + keys: false, target: `${STUDIO_API_BASE}/api/studio/${route}${req.nextUrl.search}`, bearer: STUDIO_TOKEN, unreachable: 'The studio agent is unreachable. Is it running? (just dev in dfo-ai)', diff --git a/src/app/mcp/[[...path]]/route.ts b/src/app/mcp/[[...path]]/route.ts index 36f9660..e52a7bc 100644 --- a/src/app/mcp/[[...path]]/route.ts +++ b/src/app/mcp/[[...path]]/route.ts @@ -1,6 +1,5 @@ import { NextRequest } from 'next/server'; -import { requestCaller } from '@/lib/proxy/caller'; import { forward, forwardAsset, STUDIO_API_BASE } from '@/lib/proxy/forward'; // dfo-ai's combined MCP server (`/mcp/` on the harness), mirrored at the @@ -15,7 +14,12 @@ import { forward, forwardAsset, STUDIO_API_BASE } from '@/lib/proxy/forward'; // holds it, it is attached on the caller's behalf (the site is the front // door). Otherwise the caller's own Authorization header goes through. // The caller is named in x-dfo-caller (src/lib/proxy/caller). Each address is -// rate-limited (surface 'mcp' in src/lib/proxy/rateLimit). +// rate-limited (surface 'mcp' in src/lib/proxy/rateLimit), and a call with an +// API key is counted against the key's account instead (src/lib/proxy/access). +// The key is the caller's `X-API-Key`, or its bearer when the proxy holds the +// harness token. A `dfo_` bearer is the proxy's own and never goes upstream, so +// where the proxy holds no harness token, a keyed call sends the key in +// `X-API-Key` and the harness token as its bearer. // // The exception is the theme stylesheet presentation-mcp's views load, // `/mcp/presentation/theme-.css`, which is fetched from the same path on @@ -43,7 +47,7 @@ const proxy = async (req: NextRequest, { params }: { params: Promise<{ path?: st surface: 'mcp', target: `${STUDIO_API_BASE}/mcp/${req.nextUrl.search}`, bearer: MCP_TOKEN, - caller: requestCaller(req.headers), + sendCaller: true, unreachable: 'The MCP servers are unreachable.', }); }; diff --git a/src/lib/proxy/access.ts b/src/lib/proxy/access.ts new file mode 100644 index 0000000..eb07dbd --- /dev/null +++ b/src/lib/proxy/access.ts @@ -0,0 +1,150 @@ +/** + * Who a call to the platform proxy is, and whether it is within its + * allowance (src/lib/proxy/forward): one decision per call, made before the + * call goes upstream. Kept apart from `forward` so `node --test` can drive it + * with a fake limiter and key verifier. + * + * A call is anonymous, counted against its address as before, or keyed, + * counted against the account that owns the key at the account's limit + * (docs/design/api-keys.md, "The Proxy Check"): + * + * no key anonymous + * valid key in the cache counted against the account + * any other key counted against the address first, so a + * made-up key cannot cost more lookups than the + * address could make calls, and refused with 429 + * when over; then looked up: + * invalid 401, not anonymous + * store unavailable anonymous, on the address count just made + * valid counted against the account as well + * + * A key sent on a surface that does not honor keys, or with keys switched + * off (API_KEYS_ENABLED), is ignored: the call is anonymous and the key is + * stripped before the call goes upstream by `forward`. + */ +import { conflictingKeysProblem, invalidKeyProblem, rateLimitedProblem } from './problem.ts'; +import { readApiKey } from './apiKey.ts'; +import type { KeyVerifier, ValidKey } from './keyVerifier.ts'; +import type { RateVerdict } from './rateHeaders.ts'; +import type { Surface } from './rateLimit.ts'; +import { rateHeaders } from './rateHeaders.ts'; + +export type Identity = + | { kind: 'anonymous' } + | { kind: 'keyed'; keyId: string; accountId: string }; + +/** What the usage line says happened to a keyed call. */ +export type KeyOutcome = 'allowed' | 'limited' | 'invalid' | 'unavailable'; + +/** + * The decision. `refusal` is the answer when the call is not forwarded. + * `verdict` is what the rate headers say, when a count ran. `outcome` is set + * when the call carried a key that was looked at, and is what the usage line + * (forward) reports. + */ +export type Access = { + refusal?: Response; + identity: Identity; + verdict?: RateVerdict; + outcome?: KeyOutcome; +}; + +export type AccessDeps = { + verifier: KeyVerifier; + // Count a call from an address against the surface's anonymous allowance. + hitAddress: (surface: Surface, ip: string) => Promise; + // Count a call from an account against `limit`. + hitAccount: (surface: Surface, accountId: string, limit: number) => Promise; + // The account's limit when it has none of its own. + defaultLimit: number; +}; + +const accountLimit = (key: ValidKey, defaultLimit: number): number => key.rateLimit ?? defaultLimit; + +/** + * Decide the call. `keys` is whether this call honors a key at all (the + * route's surface, and API_KEYS_ENABLED); `surface` unset means the call has + * no limit and no key check. + */ +export const decideAccess = async ( + deps: AccessDeps, + { + surface, + keys, + headers, + ip, + }: { surface: Surface | undefined; keys: boolean; headers: Headers; ip: string }, +): Promise => { + const anonymous: Identity = { kind: 'anonymous' }; + const countAddress = async (): Promise => { + const verdict = surface ? await deps.hitAddress(surface, ip) : undefined; + + return verdict && !verdict.allowed + ? { + refusal: rateLimitedProblem(verdict, rateHeaders(verdict)), + identity: anonymous, + verdict, + } + : { identity: anonymous, verdict }; + }; + + if (!surface || !keys) { + return countAddress(); + } + + const read = readApiKey(headers); + + if (read.kind === 'none') { + return countAddress(); + } + + if (read.kind === 'conflict') { + return { refusal: conflictingKeysProblem(), identity: anonymous }; + } + + if (read.kind === 'too-long') { + return { refusal: invalidKeyProblem(), identity: anonymous, outcome: 'invalid' }; + } + + const countAccount = async (key: ValidKey): Promise => { + const verdict = await deps.hitAccount( + surface, + key.accountId, + accountLimit(key, deps.defaultLimit), + ); + const identity: Identity = { kind: 'keyed', keyId: key.keyId, accountId: key.accountId }; + + return verdict.allowed + ? { identity, verdict, outcome: 'allowed' } + : { + refusal: rateLimitedProblem(verdict, rateHeaders(verdict), 'account'), + identity, + verdict, + outcome: 'limited', + }; + }; + + const cached = await deps.verifier.cachedValid(read.key); + + if (cached) { + return countAccount(cached); + } + + const address = await countAddress(); + + if (address.refusal) { + return { ...address, outcome: 'limited' }; + } + + const found = await deps.verifier.verify(read.key); + + if (found.kind === 'valid') { + return countAccount(found); + } + + if (found.kind === 'invalid') { + return { refusal: invalidKeyProblem(), identity: anonymous, outcome: 'invalid' }; + } + + return { ...address, outcome: 'unavailable' }; +}; diff --git a/src/lib/proxy/caller.ts b/src/lib/proxy/caller.ts index 878fdd8..a5dfe25 100644 --- a/src/lib/proxy/caller.ts +++ b/src/lib/proxy/caller.ts @@ -183,6 +183,16 @@ export const resolveCaller = ( return `ip:${digest}`; }; +/** + * The caller for an account (the owner of an API key): `user:` and the first + * 32 hex characters of HMAC-SHA-256 over `"user:" + accountId`, keyed by + * CALLER_HMAC_KEY as the `ip:` digest is. The account id never leaves the + * site. The `user:` prefix in the digest's input keeps it apart from an + * address's. + */ +export const resolveAccountCaller = (accountId: string, { key }: CallerConfig): string => + `user:${createHmac('sha256', key).update(`user:${accountId}`).digest('hex').slice(0, DIGEST_LENGTH)}`; + /** Set the resolved caller on upstream headers, dropping any other value. */ export const setCaller = (headers: Headers, caller: string | undefined): void => { headers.delete(CALLER_HEADER); @@ -209,7 +219,7 @@ export type ApisCaller = { principal?: string; caller?: string }; export const apisCallerFor = ( env: Record, log: (message: string) => void = console.warn, -): ((forwardedFor: string | null) => ApisCaller) => { +): ((forwardedFor: string | null, caller?: string) => ApisCaller) => { const principal = env.DFO_CALLER_PRINCIPAL?.trim(); const config = callerConfig(env); let logged = false; @@ -240,7 +250,12 @@ export const apisCallerFor = ( }; } - return (forwardedFor) => ({ principal, caller: resolveCaller(forwardedFor, config) }); + // A call that has already named its caller (an account's, see + // resolveAccountCaller) sends that name in place of the address's. + return (forwardedFor, caller) => ({ + principal, + caller: caller ?? resolveCaller(forwardedFor, config), + }); }; const apisCaller = apisCallerFor(process.env); @@ -248,9 +263,11 @@ const apisCaller = apisCallerFor(process.env); /** * Name the caller of `incoming` on upstream headers bound for dfo-apis, from * this process's env (see apisCallerFor), dropping any value already there. + * `named` is the caller the proxy already resolved for an account, which goes + * in place of the address's. */ -export const setApisCaller = (headers: Headers, incoming: Headers): void => { - const { principal, caller } = apisCaller(incoming.get('x-forwarded-for')); +export const setApisCaller = (headers: Headers, incoming: Headers, named?: string): void => { + const { principal, caller } = apisCaller(incoming.get('x-forwarded-for'), named); headers.delete(CALLER_PRINCIPAL_HEADER); @@ -264,6 +281,10 @@ export const setApisCaller = (headers: Headers, incoming: Headers): void => { const config = callerConfig(process.env); let warned = false; +/** The caller for an account, from this process's env, or undefined without CALLER_HMAC_KEY. */ +export const accountCaller = (accountId: string): string | undefined => + 'problem' in config ? undefined : resolveAccountCaller(accountId, config); + /** The caller for an incoming request, from this process's env. */ export const requestCaller = (incoming: Headers): string | undefined => { if ('problem' in config) { diff --git a/src/lib/proxy/forward.ts b/src/lib/proxy/forward.ts index c0a9497..bf8a48c 100644 --- a/src/lib/proxy/forward.ts +++ b/src/lib/proxy/forward.ts @@ -3,8 +3,18 @@ import 'server-only'; import type { NextRequest } from 'next/server'; import { apisFetch } from '@/lib/apisAuth'; +import { keyDb } from '@/lib/db'; -import { limiterKeyFor, setApisCaller, setCaller, trustedHops } from './caller'; +import { decideAccess, type AccessDeps } from './access'; +import { API_KEY_HEADER, bearerKey } from './apiKey'; +import { + accountCaller, + limiterKeyFor, + requestCaller, + setApisCaller, + setCaller, + trustedHops, +} from './caller'; import { clientResponseHeaders, dropEncodedLength, @@ -12,9 +22,10 @@ import { upstreamRequestHeaders, type HeaderPass, } from './headers'; -import { rateLimitedProblem, unreachableProblem } from './problem'; +import { createKeyVerifier } from './keyVerifier'; +import { unreachableProblem } from './problem'; import { rateHeaders } from './rateHeaders'; -import { hit, type Surface } from './rateLimit'; +import { hit, hitKey, KEYED_LIMIT, type Surface } from './rateLimit'; /** * The platform proxy: the DFO APIs and the MCP servers mirrored 1:1 under @@ -23,7 +34,11 @@ import { hit, type Surface } from './rateLimit'; * must not reach a client). An /api/*, /openapi.json or /mcp call, and a * /codes call the route forwards, is rate-limited per IP: /mcp on its own * allowance, the rest on 'api' (src/lib/proxy/rateLimit; the X-RateLimit-* - * headers go out only on a counted call). A call is forwarded with its + * headers go out only on a counted call). A call may carry an API key, + * `Authorization: Bearer dfo_…` or `X-API-Key` (src/lib/proxy/apiKey), and is + * then counted against the key's account at the account's limit, or refused + * with a 401 when the key is not valid (src/lib/proxy/access). The key is + * never forwarded, on any route, and the Studio ignores it. A call is forwarded with its * method, query, body, content headers, user-agent, x-dfo-client and every * mcp-* header (src/lib/proxy/headers), and the upstream's response streamed back: SSE * (search resolve, studio turns, MCP) and file downloads both depend on @@ -50,8 +65,9 @@ import { hit, type Surface } from './rateLimit'; * A call to SEARCH_API_BASE carries the site's ID token on Cloud Run * (src/lib/apisAuth matches on the target's origin), and names the caller in * x-dfo-caller beside the x-dfo-caller-principal secret (setApisCaller in - * src/lib/proxy/caller), matched on the same origin. The other upstreams get - * neither. + * src/lib/proxy/caller), matched on the same origin. The caller is `ip:` and + * a digest of the address, or `user:` and a digest of the account for a call + * with a valid key. The other upstreams get neither, bar /mcp's caller. * * The unversioned /api/search|datasets|graph|studio/* paths rewrite onto the * same handlers (next.config.ts), so both addresses answer alike. @@ -71,18 +87,37 @@ const limiterKey = limiterKeyFor(trustedHops(process.env)); export const clientIp = (req: NextRequest): string => limiterKey(req.headers.get('x-forwarded-for')); +// The accounts' counts and key lookups, as forward() reaches them. A test +// swaps a field for a fake. +export const accessDeps: AccessDeps = { + verifier: createKeyVerifier(keyDb), + hitAddress: hit, + hitAccount: (surface, accountId, limit) => hitKey(surface, `acct:${accountId}`, limit), + defaultLimit: KEYED_LIMIT, +}; + +// API_KEYS_ENABLED is the emergency switch: set to `false` (or `0`, `off`, +// `no`), keys are stripped and every call is treated as anonymous. Read per +// call, so a test can flip it. +const keysEnabled = (): boolean => + !['false', '0', 'off', 'no'].includes(process.env.API_KEYS_ENABLED?.trim().toLowerCase() ?? ''); + type ForwardOptions = { // Which allowance applies (see rateLimit's LIMITS); unset, no limit. surface?: Surface; + // Whether an API key on the call counts. False (the Studio): the key is + // stripped and otherwise ignored. Default true, on a limited surface. + keys?: boolean; // The upstream URL to hit (path + query already resolved). target: string; // A bearer the proxy attaches on the caller's behalf; when unset, the // caller's own Authorization header goes through instead. bearer?: string; - // The x-dfo-caller value to send to an upstream other than dfo-apis, - // which gets its own (src/lib/proxy/caller). Any value the client sent is - // dropped either way. - caller?: string; + // Whether to name the caller in x-dfo-caller to an upstream other than + // dfo-apis (/mcp), which is resolved as for dfo-apis, which always gets + // its own (src/lib/proxy/caller). Any value the client sent is dropped + // either way. + sendCaller?: boolean; // Headers carried beyond the defaults (src/lib/proxy/headers). pass?: HeaderPass; // What to answer when the upstream is unreachable. @@ -138,13 +173,20 @@ const peeked = async (body: ReadableStream): Promise => { - const verdict = options.surface ? await hit(options.surface, clientIp(req)) : undefined; - const limitHeaders = verdict ? rateHeaders(verdict) : {}; + // Who the caller is and whether it is within its allowance, decided once. + const access = await decideAccess(accessDeps, { + surface: options.surface, + keys: options.keys !== false && keysEnabled(), + headers: req.headers, + ip: clientIp(req), + }); - if (verdict && !verdict.allowed) { - return rateLimitedProblem(verdict, limitHeaders); + if (access.refusal) { + return access.refusal; } + const limitHeaders = access.verdict ? rateHeaders(access.verdict) : {}; + const refusal = await options.admit?.(); if (refusal) { @@ -157,14 +199,24 @@ export const forward = async (req: NextRequest, options: ForwardOptions): Promis if (options.bearer) { headers.set('authorization', `Bearer ${options.bearer}`); - } else if (callerAuth) { + } else if (callerAuth && bearerKey(callerAuth) === undefined) { + // Any bearer but one of our keys passes through as it always did. + // A key is the proxy's own and goes no further, verified or not. headers.set('authorization', callerAuth); } + headers.delete(API_KEY_HEADER); + + const accountName = + access.identity.kind === 'keyed' ? accountCaller(access.identity.accountId) : undefined; + if (isApisTarget(options.target)) { - setApisCaller(headers, req.headers); + setApisCaller(headers, req.headers, accountName); } else { - setCaller(headers, options.caller); + setCaller( + headers, + options.sendCaller ? (accountName ?? requestCaller(req.headers)) : undefined, + ); } const hasBody = req.method !== 'GET' && req.method !== 'HEAD'; diff --git a/src/lib/proxy/limitFallback.ts b/src/lib/proxy/limitFallback.ts new file mode 100644 index 0000000..9fefec0 --- /dev/null +++ b/src/lib/proxy/limitFallback.ts @@ -0,0 +1,64 @@ +/** + * An in-memory fixed-window count per caller key, for one server instance. + * The proxy falls back to it when the shared count in Postgres + * (./limitCounter) fails or is slow, so a burst sent while the database is + * struggling is still held to its limit on each instance, instead of passing + * uncounted. A caller served by several instances can reach the limit times + * the instance count at worst, which is far under no limit. + * + * Windows are aligned to the Unix epoch, as the shared counters' are. The + * memory is bounded: a full map first drops the windows that have ended and + * then its oldest keys. An evicted key starts over, which is the same + * leniency as a fresh instance. + */ +import type { Verdict } from './limitCounter.ts'; + +export const FALLBACK_MAX_KEYS = 10_000; + +export type FallbackCounter = { + hit(key: string, limit: number): Verdict; + size(): number; +}; + +export const createFallbackCounter = ( + windowS: number, + { now = Date.now, maxKeys = FALLBACK_MAX_KEYS }: { now?: () => number; maxKeys?: number } = {}, +): FallbackCounter => { + const windowMs = windowS * 1000; + // The window a key was last counted in, and how many calls it held. + const counts = new Map(); + + return { + hit(key, limit) { + const at = now(); + const window = Math.floor(at / windowMs); + const known = counts.get(key); + const count = known && known.window === window ? known.count + 1 : 1; + + // Re-inserted, so insertion order stays the order of last use. + counts.delete(key); + + if (counts.size >= maxKeys) { + for (const [other, entry] of counts) { + if (entry.window < window) { + counts.delete(other); + } + } + } + + while (counts.size >= maxKeys) { + counts.delete(counts.keys().next().value!); + } + + counts.set(key, { window, count }); + + return { + allowed: count <= limit, + limit, + remaining: Math.max(0, limit - count), + reset: Math.max(1, Math.ceil(((window + 1) * windowMs - at) / 1000)), + }; + }, + size: () => counts.size, + }; +}; diff --git a/src/lib/proxy/openapi.ts b/src/lib/proxy/openapi.ts index 399f33a..063e0c2 100644 --- a/src/lib/proxy/openapi.ts +++ b/src/lib/proxy/openapi.ts @@ -12,7 +12,9 @@ import { SEARCH_API_SURFACES } from './surfaces.ts'; * presentation API, which the site does not proxy. The component schemas * only those paths used go with them. * The document carries no `servers`, so a client generated from it calls the - * host that served it, whichever environment that is. + * host that served it, whichever environment that is. It declares the + * optional API key as a security scheme (bearer and X-API-Key), and as the + * document's `security` when dfo-apis's own sets none. */ // dfo-apis deploys on its own schedule, so a cached copy goes stale in @@ -105,6 +107,23 @@ const keptSchemas = (schemas: JsonObject, root: unknown): JsonObject => { return Object.fromEntries(Object.entries(schemas).filter(([name]) => found.has(name))); }; +// How a call names its API key (src/lib/proxy/apiKey). A key is optional, so +// the document's `security` leads with the empty requirement. +const KEY_SECURITY_SCHEMES = { + ApiKeyBearer: { + type: 'http', + scheme: 'bearer', + description: + 'An optional API key, `dfo_live_…`, as `Authorization: Bearer `. Calls without a key are counted by address; a call with a valid key is counted against its account, and one with an invalid key is refused with 401.', + }, + ApiKeyHeader: { + type: 'apiKey', + in: 'header', + name: 'X-API-Key', + description: 'The same optional API key, as `X-API-Key: `.', + }, +} as const; + /** dfo-apis's OpenAPI document as the site publishes it. */ export const publicOpenApi = (document: OpenApiDocument): OpenApiDocument => { const paths = Object.fromEntries( @@ -131,6 +150,15 @@ export const publicOpenApi = (document: OpenApiDocument): OpenApiDocument => { }; } + out.components = { + ...out.components, + securitySchemes: { + ...asRecord(out.components?.securitySchemes), + ...KEY_SECURITY_SCHEMES, + }, + }; + out.security ??= [{}, { ApiKeyBearer: [] }, { ApiKeyHeader: [] }]; + return out; }; diff --git a/src/lib/proxy/problem.ts b/src/lib/proxy/problem.ts index 999be0e..1d6f9f9 100644 --- a/src/lib/proxy/problem.ts +++ b/src/lib/proxy/problem.ts @@ -1,7 +1,7 @@ /** * The problem documents the proxy answers with when it refuses a call * itself: a route it does not have (404), a spent allowance (429), an - * upstream it cannot reach (502, 503). They are in the shape dfo-apis uses + * upstream it cannot reach (502, 503), a bad API key (401). They are in the shape dfo-apis uses * for its own refusals (the docs corpus's dfo-apis/conventions.md, "Problem * details"): `application/problem+json` with the registry `code`, a * `trace_id` repeated in the `x-dfo-trace-id` header, and `retryable`. A @@ -119,15 +119,39 @@ export const unauthorizedProblem = (): Response => retryable: false, }); -/** A 429 `rate_limited` problem document; `headers` carry the rate headers. */ +/** + * A 401 `invalid_api_key` problem document: the call's API key is unknown, + * disabled, expired or malformed. The call is not treated as anonymous. + * No `WWW-Authenticate`, which would send an MCP client looking for OAuth. + */ +export const invalidKeyProblem = (): Response => + problem({ + status: 401, + code: 'invalid_api_key', + detail: 'The API key is not valid. Check the key, or leave it off to call without one.', + retryable: false, + }); + +/** A 400 `request_invalid` problem document: two different keys on one call. */ +export const conflictingKeysProblem = (): Response => + requestInvalidProblem( + 'The Authorization bearer and X-API-Key carry different API keys. Send one key.', + ); + +/** + * A 429 `rate_limited` problem document; `headers` carry the rate headers. + * `scope` says whose allowance is spent: the caller's address or, for a + * call with an API key, its account. + */ export const rateLimitedProblem = ( { limit, reset }: { limit: number; reset: number }, headers: Record, + scope: 'address' | 'account' = 'address', ): Response => problem({ status: 429, code: 'rate_limited', - detail: `Too many requests: ${limit} per window per address. Try again in ${reset}s.`, + detail: `Too many requests: ${limit} per window per ${scope}. Try again in ${reset}s.`, retryable: true, headers: { ...headers, 'Retry-After': String(reset) }, }); diff --git a/src/lib/proxy/rateHeaders.ts b/src/lib/proxy/rateHeaders.ts index 986db11..b84e3aa 100644 --- a/src/lib/proxy/rateHeaders.ts +++ b/src/lib/proxy/rateHeaders.ts @@ -6,8 +6,9 @@ import type { Verdict } from './limitCounter'; /** A verdict, and whether a count ran to reach it. */ export type RateVerdict = Verdict & { - // False for the verdict of the fail-open path (a database error or - // timeout): the call passed without a count, so no limit applies. + // False for a call that passed without a count, so no limit applies. The + // limiter always counts now: a shared count that fails is counted in + // memory instead (src/lib/proxy/rateLimit). counted: boolean; }; diff --git a/src/lib/proxy/rateLimit.ts b/src/lib/proxy/rateLimit.ts index 7a72cb0..e7e02bd 100644 --- a/src/lib/proxy/rateLimit.ts +++ b/src/lib/proxy/rateLimit.ts @@ -3,22 +3,21 @@ import 'server-only'; import { counterDb } from '@/lib/db'; import { limiterBucket } from './caller'; -import { countHit, pruneCounters } from './limitCounter'; +import { countHit, pruneCounters, type CounterDb } from './limitCounter'; +import { createFallbackCounter, type FallbackCounter } from './limitFallback'; import type { RateVerdict } from './rateHeaders'; /** - * Per-IP rate limit for the platform proxy's /api/*, /openapi.json, /codes - * and /mcp calls (src/lib/proxy/forward): a fixed window counted in Postgres - * (./limitCounter), shared by every instance. An IPv6 client is counted by - * its /64 (see limiterBucket). A count runs on its own small pool - * (src/lib/db's counterDb), which gives up after 400 ms in Postgres, 500 ms - * in the client, or 2 s waiting for a connection. A database error or a - * timed-out count fails open: the - * platform's own doors are the backstop, and the limit is a courtesy. - * - * A fail-open call gets a verdict with `counted: false`, and the response - * carries no X-RateLimit-* headers (see rateHeaders), so the proxy advertises - * a limit only while one is counted. + * Rate limit for the platform proxy's /api/*, /openapi.json, /codes and /mcp + * calls (src/lib/proxy/forward): a fixed window counted in Postgres + * (./limitCounter), shared by every instance. A caller is an address or an + * account (a key's owner). An IPv6 address is counted by its /64 (see + * limiterBucket). A count runs on its own small pool (src/lib/db's + * counterDb), which gives up after 400 ms in Postgres, 500 ms in the client, + * or 2 s waiting for a connection. A database error or a timed-out count does + * not let the call through uncounted: this instance counts it in memory + * instead (./limitFallback), so a burst is held near its limit on each + * instance while the database is slow, and the proxy stays available. * * The window and the allowance per surface are env-tunable: * RATE_LIMIT_WINDOW_S (default 60) @@ -27,6 +26,9 @@ import type { RateVerdict } from './rateHeaders'; * RATE_LIMIT_PIN calls per window per IP on /api/download-pin * (default 10) * RATE_LIMIT_MCP requests per window per IP on /mcp (default 300) + * RATE_LIMIT_KEYED calls per window per account on each of the API + * and MCP surfaces, for an account with no limit of + * its own (default 600) */ const WINDOW_S = Number(process.env.RATE_LIMIT_WINDOW_S) || 60; @@ -44,37 +46,69 @@ export const LIMITS = { mcp: Number(process.env.RATE_LIMIT_MCP) || 300, } as const; +/** + * An account's calls per window on each surface when it sets none of its own + * (`user.api_rate_limit`). One number for every surface, since an account is + * one caller, not a vendor's address with many users behind it. + */ +export const KEYED_LIMIT = Number(process.env.RATE_LIMIT_KEYED) || 600; + export type Surface = keyof typeof LIMITS; -let lastPrune = 0; +export type Limiter = { + /** + * Count one call by `callerKey` on `surface` against `limit` and say + * whether it is within it. `callerKey` is the limiter bucket of an + * address (limiterBucket) or `acct:`. + */ + hitKey(surface: Surface, callerKey: string, limit: number): Promise; +}; -/** - * Count one call for `ip` on `surface` and say whether it is within the - * allowance. A database that fails or is slow lets the call through, uncounted. Each - * instance also deletes dead counters, at most once an hour, the Studio's - * included (every Studio call passes here too). The delete uses the same - * bounded counter pool as the counts. - */ -export const hit = async (surface: Surface, ip: string): Promise => { - const limit = LIMITS[surface]; - - if (Date.now() - lastPrune > PRUNE_EVERY_MS) { - lastPrune = Date.now(); - pruneCounters(counterDb).catch((error) => console.warn('limit counters not pruned', error)); - } - - try { - const verdict = await countHit( - counterDb, - `${surface}:${limiterBucket(ip)}`, - limit, - WINDOW_S, - ); - - return { ...verdict, counted: true }; - } catch (error) { - console.warn('rate limit unavailable, passing', error); - - return { allowed: true, counted: false, limit, remaining: limit, reset: WINDOW_S }; - } +export const createLimiter = ( + db: CounterDb, + { + windowS = WINDOW_S, + fallback = createFallbackCounter(windowS), + warn = console.warn, + prune = true, + }: { + windowS?: number; + fallback?: FallbackCounter; + warn?: (message: string, error: unknown) => void; + prune?: boolean; + } = {}, +): Limiter => { + let lastPrune = 0; + + return { + async hitKey(surface, callerKey, limit) { + // Each instance deletes dead counters, at most once an hour, the + // Studio's included (every Studio call passes here too). The + // delete uses the same bounded counter pool as the counts. + if (prune && Date.now() - lastPrune > PRUNE_EVERY_MS) { + lastPrune = Date.now(); + pruneCounters(db).catch((error) => warn('limit counters not pruned', error)); + } + + const key = `${surface}:${callerKey}`; + + try { + return { ...(await countHit(db, key, limit, windowS)), counted: true }; + } catch (error) { + warn('rate limit unavailable, counting in memory', error); + + return { ...fallback.hit(key, limit), counted: true }; + } + }, + }; }; + +const limiter = createLimiter(counterDb); + +/** Count one call by `callerKey` on `surface` against `limit` (see Limiter). */ +export const hitKey = (surface: Surface, callerKey: string, limit: number): Promise => + limiter.hitKey(surface, callerKey, limit); + +/** Count one call from the address `ip` against `surface`'s anonymous allowance. */ +export const hit = (surface: Surface, ip: string): Promise => + hitKey(surface, limiterBucket(ip), LIMITS[surface]); diff --git a/src/lib/proxy/test/access.test.ts b/src/lib/proxy/test/access.test.ts new file mode 100644 index 0000000..9ed9048 --- /dev/null +++ b/src/lib/proxy/test/access.test.ts @@ -0,0 +1,246 @@ +/** + * `access.ts`: the decision for a call to the platform proxy, with a fake + * limiter and key verifier so the order of counts and lookups can be seen. + * An anonymous call is counted by address as before; a call with a key is + * counted against its account, after the address when the key was not in + * the cache. + */ +import '../../test/serverModules.ts'; + +import assert from 'node:assert/strict'; +import test from 'node:test'; + +import type { AccessDeps } from '../access.ts'; +import type { KeyVerdict, KeyVerifier, ValidKey } from '../keyVerifier.ts'; +import type { RateVerdict } from '../rateHeaders.ts'; + +const { decideAccess } = await import('../access.ts'); + +const KEY = `dfo_live_${'a'.repeat(32)}`; +const VALID: ValidKey = { + kind: 'valid', + keyId: 'key-1', + accountId: 'acct-1', + rateLimit: null, + expiresAt: null, +}; + +const verdict = (limit: number, used: number): RateVerdict => ({ + allowed: used <= limit, + counted: true, + limit, + remaining: Math.max(0, limit - used), + reset: 30, +}); + +// A world of fakes: `answer` is what the key store says, `cached` whether the +// cache already holds it, `used` how many calls each counter already has. +const world = ({ + answer = VALID as KeyVerdict, + cached = false, + addressUsed = 0, + accountUsed = 0, + defaultLimit = 600, + addressLimit = 120, +}: { + answer?: KeyVerdict; + cached?: boolean; + addressUsed?: number; + accountUsed?: number; + defaultLimit?: number; + addressLimit?: number; +} = {}) => { + const calls: string[] = []; + const verifier: KeyVerifier = { + cacheSize: () => 0, + cachedValid: async () => { + calls.push('cache'); + + return cached && answer.kind === 'valid' ? answer : undefined; + }, + verify: async () => { + calls.push('lookup'); + + return answer; + }, + }; + const deps: AccessDeps = { + verifier, + defaultLimit, + hitAddress: async (surface, ip) => { + calls.push(`address:${surface}:${ip}`); + + return verdict(addressLimit, addressUsed + 1); + }, + hitAccount: async (surface, accountId, limit) => { + calls.push(`account:${surface}:${accountId}:${limit}`); + + return verdict(limit, accountUsed + 1); + }, + }; + + return { calls, deps }; +}; + +const decide = ( + deps: AccessDeps, + headers: Record = {}, + options: { surface?: 'api' | 'mcp'; keys?: boolean } = {}, +) => + decideAccess(deps, { + surface: 'surface' in options ? options.surface : 'api', + keys: options.keys ?? true, + headers: new Headers(headers), + ip: '203.0.113.7', + }); + +test('a call with no key is counted against its address, as before', async () => { + const { calls, deps } = world(); + const access = await decide(deps); + + assert.deepEqual(calls, ['address:api:203.0.113.7']); + assert.deepEqual(access.identity, { kind: 'anonymous' }); + assert.equal(access.refusal, undefined); + assert.equal(access.outcome, undefined); + assert.equal(access.verdict?.limit, 120); +}); + +test('an anonymous call over the address limit is a 429', async () => { + const { deps } = world({ addressUsed: 120 }); + const access = await decide(deps); + + assert.equal(access.refusal?.status, 429); + assert.equal(access.refusal?.headers.get('x-ratelimit-limit'), '120'); + assert.equal(access.refusal?.headers.get('retry-after'), '30'); +}); + +test('a call on a surface with no limit is neither counted nor looked up', async () => { + const { calls, deps } = world(); + const access = await decide(deps, { 'x-api-key': KEY }, { surface: undefined }); + + assert.deepEqual(calls, []); + assert.equal(access.refusal, undefined); + assert.equal(access.verdict, undefined); +}); + +test('a key on a call that ignores keys is ignored: anonymous, counted by address', async () => { + const { calls, deps } = world(); + const access = await decide(deps, { 'x-api-key': 'nonsense' }, { keys: false }); + + assert.deepEqual(calls, ['address:api:203.0.113.7']); + assert.deepEqual(access.identity, { kind: 'anonymous' }); + assert.equal(access.refusal, undefined); +}); + +test('a valid key in the cache is counted against its account alone, at the default limit', async () => { + const { calls, deps } = world({ cached: true }); + const access = await decide(deps, { authorization: `Bearer ${KEY}` }); + + assert.deepEqual(calls, ['cache', 'account:api:acct-1:600']); + assert.deepEqual(access.identity, { kind: 'keyed', keyId: 'key-1', accountId: 'acct-1' }); + assert.equal(access.outcome, 'allowed'); + assert.equal(access.verdict?.limit, 600); + assert.equal(access.verdict?.remaining, 599); +}); + +test('an account with a limit of its own is counted at that limit, on each surface apart', async () => { + const { calls, deps } = world({ cached: true, answer: { ...VALID, rateLimit: 200 } }); + + await decide(deps, { 'x-api-key': KEY }, { surface: 'api' }); + await decide(deps, { 'x-api-key': KEY }, { surface: 'mcp' }); + + assert.deepEqual( + calls.filter((call) => call.startsWith('account')), + ['account:api:acct-1:200', 'account:mcp:acct-1:200'], + ); +}); + +test('a key not in the cache is counted against the address first, then looked up, then the account', async () => { + const { calls, deps } = world(); + const access = await decide(deps, { 'x-api-key': KEY }); + + assert.deepEqual(calls, [ + 'cache', + 'address:api:203.0.113.7', + 'lookup', + 'account:api:acct-1:600', + ]); + assert.equal(access.outcome, 'allowed'); + // The headers describe the account's allowance, not the address's. + assert.equal(access.verdict?.limit, 600); +}); + +test('an account past its limit is a 429 that names the account', async () => { + const { deps } = world({ cached: true, accountUsed: 600 }); + const access = await decide(deps, { 'x-api-key': KEY }); + + assert.equal(access.refusal?.status, 429); + assert.equal(access.outcome, 'limited'); + assert.equal(access.refusal?.headers.get('x-ratelimit-limit'), '600'); + assert.match((await access.refusal!.json()).detail, /per account/); + assert.deepEqual(access.identity, { kind: 'keyed', keyId: 'key-1', accountId: 'acct-1' }); +}); + +test('an address past its limit is refused before any lookup', async () => { + const { calls, deps } = world({ addressUsed: 120 }); + const access = await decide(deps, { 'x-api-key': KEY }); + + assert.equal(access.refusal?.status, 429); + assert.equal(access.outcome, 'limited'); + assert.deepEqual(calls, ['cache', 'address:api:203.0.113.7']); + assert.match((await access.refusal!.json()).detail, /per address/); +}); + +test('an invalid key is a 401 problem document and does not fall back to anonymous', async () => { + const { calls, deps } = world({ answer: { kind: 'invalid' } }); + const access = await decide(deps, { authorization: `Bearer ${KEY}` }); + + assert.equal(access.refusal?.status, 401); + assert.equal(access.refusal?.headers.get('content-type'), 'application/problem+json'); + assert.equal((await access.refusal!.json()).code, 'invalid_api_key'); + assert.equal(access.outcome, 'invalid'); + assert.deepEqual(access.identity, { kind: 'anonymous' }); + // No account count, and the 401 carries no limit headers. + assert.deepEqual(calls, ['cache', 'address:api:203.0.113.7', 'lookup']); + assert.equal(access.refusal?.headers.get('x-ratelimit-limit'), null); +}); + +test('an unavailable key store lets the call through as anonymous on the address count already made', async () => { + const { calls, deps } = world({ answer: { kind: 'unavailable' } }); + const access = await decide(deps, { 'x-api-key': KEY }); + + assert.equal(access.refusal, undefined); + assert.equal(access.outcome, 'unavailable'); + assert.deepEqual(access.identity, { kind: 'anonymous' }); + assert.equal(access.verdict?.limit, 120); + assert.deepEqual(calls, ['cache', 'address:api:203.0.113.7', 'lookup']); +}); + +test('two different keys are a 400 before anything is counted', async () => { + const { calls, deps } = world(); + const access = await decide(deps, { + authorization: `Bearer ${KEY}`, + 'x-api-key': `${KEY}x`, + }); + + assert.equal(access.refusal?.status, 400); + assert.equal((await access.refusal!.json()).code, 'request_invalid'); + assert.deepEqual(calls, []); +}); + +test('an over-long key is a 401 with no lookup and no count', async () => { + const { calls, deps } = world(); + const access = await decide(deps, { 'x-api-key': `dfo_${'x'.repeat(200)}` }); + + assert.equal(access.refusal?.status, 401); + assert.equal(access.outcome, 'invalid'); + assert.deepEqual(calls, []); +}); + +test('a bearer that is not one of our keys is no key: anonymous, no lookup', async () => { + const { calls, deps } = world(); + const access = await decide(deps, { authorization: 'Bearer harness-token' }); + + assert.deepEqual(calls, ['address:api:203.0.113.7']); + assert.equal(access.outcome, undefined); +}); diff --git a/src/lib/proxy/test/caller.test.ts b/src/lib/proxy/test/caller.test.ts index 87654db..32ec9fb 100644 --- a/src/lib/proxy/test/caller.test.ts +++ b/src/lib/proxy/test/caller.test.ts @@ -15,6 +15,7 @@ import { clientAddress, limiterBucket, limiterKeyFor, + resolveAccountCaller, resolveCaller, setCaller, trustedHops, @@ -220,3 +221,23 @@ test('apisCallerFor: a principal without a usable key or hops goes alone and log assert.equal(logged.length, 1); } }); + +// The digest's input is the cross-service contract, as the address's is. +test('resolveAccountCaller: user: and 32 hex of HMAC-SHA-256 over "user:" and the account id', () => { + const caller = resolveAccountCaller('acct-1', { key: KEY, hops: 0 }); + + assert.equal( + caller, + `user:${createHmac('sha256', KEY).update('user:acct-1').digest('hex').slice(0, 32)}`, + ); + assert.match(caller, /^user:[0-9a-f]{32}$/); + assert.notEqual(caller, resolveAccountCaller('acct-2', { key: KEY, hops: 0 })); + assert.notEqual(caller, resolveAccountCaller('acct-1', { key: 'other', hops: 0 })); +}); + +test('apisCallerFor: an account named by the proxy goes in place of the address', () => { + const named = apisCallerFor({ DFO_CALLER_PRINCIPAL: 'p', CALLER_HMAC_KEY: KEY }); + + assert.deepEqual(named('2.2.2.2', 'user:abc'), { principal: 'p', caller: 'user:abc' }); + assert.deepEqual(named('2.2.2.2'), { principal: 'p', caller: digest('2.2.2.2') }); +}); diff --git a/src/lib/proxy/test/forwardKeys.test.ts b/src/lib/proxy/test/forwardKeys.test.ts new file mode 100644 index 0000000..ac404ef --- /dev/null +++ b/src/lib/proxy/test/forwardKeys.test.ts @@ -0,0 +1,442 @@ +/** + * `forward()` with API keys: what reaches the upstream (never the key, the + * caller named as `user:` for an account), what a bad, unavailable or + * ignored key does, the Studio and the kill switch, the usage line, and the + * whole flow on a real key store and counter. + */ +import '../../test/serverModules.ts'; + +import assert from 'node:assert/strict'; +import { createHmac } from 'node:crypto'; +import { once } from 'node:events'; +import { createServer, type IncomingHttpHeaders } from 'node:http'; +import type { AddressInfo } from 'node:net'; +import path from 'node:path'; +import test, { mock } from 'node:test'; + +import { defaultKeyHasher } from '@better-auth/api-key'; +import { drizzle } from 'drizzle-orm/node-postgres'; +import { Pool } from 'pg'; +import type { NextRequest } from 'next/server'; + +import { applyMigrations } from '../../../../db/apply-migrations.ts'; +import { buildCounterPool, buildKeyPool } from '../../../../db/connection.ts'; +import * as schema from '../../../../db/schema.ts'; +import { createTestDatabase } from '../../../../db/test/harness.ts'; +import type { KeyVerdict } from '../keyVerifier.ts'; +import type { RateVerdict } from '../rateHeaders.ts'; + +// caller.ts and rateLimit.ts read these at import. +process.env.CALLER_HMAC_KEY = 'test-hmac-key'; +process.env.DFO_CALLER_PRINCIPAL = 'test-principal'; +process.env.TRUSTED_PROXY_HOPS = '0'; + +const { forward, accessDeps } = await import('../forward.ts'); +const { createKeyVerifier } = await import('../keyVerifier.ts'); +const { createLimiter } = await import('../rateLimit.ts'); + +const KEY = `dfo_live_${'k'.repeat(32)}`; +const ACCOUNT = 'acct-1'; +const accountCaller = `user:${createHmac('sha256', 'test-hmac-key') + .update(`user:${ACCOUNT}`) + .digest('hex') + .slice(0, 32)}`; +const addressCaller = `ip:${createHmac('sha256', 'test-hmac-key') + .update('203.0.113.7') + .digest('hex') + .slice(0, 32)}`; + +// What the upstream saw of each call. +const seen: IncomingHttpHeaders[] = []; +const upstream = createServer((req, res) => { + seen.push(req.headers); + res.writeHead(200, { 'content-type': 'application/json' }).end('{}'); +}); + +upstream.listen(0, '127.0.0.1'); +await once(upstream, 'listening'); +test.after(() => { + upstream.closeAllConnections(); + upstream.close(); +}); + +const base = `http://127.0.0.1:${(upstream.address() as AddressInfo).port}`; + +// The target is dfo-apis's origin, so the call is named as dfo-apis is. +process.env.SEARCH_API_BASE = base; + +type Options = Partial[1]>; + +const call = (headers: Record = {}, options: Options = {}): Promise => + forward( + new Request('http://site.test/api/v1/search/x', { + headers: { 'x-forwarded-for': '203.0.113.7', ...headers }, + }) as NextRequest, + { surface: 'api', target: `${base}/x`, unreachable: 'unreachable', ...options }, + ); + +const original = { ...accessDeps }; +const fakes = (answer: KeyVerdict, cached = false) => { + const log: string[] = []; + + accessDeps.verifier = { + cacheSize: () => 0, + cachedValid: async () => { + log.push('cache'); + + return cached && answer.kind === 'valid' ? answer : undefined; + }, + verify: async () => { + log.push('lookup'); + + return answer; + }, + }; + accessDeps.hitAddress = async (surface) => { + log.push(`address:${surface}`); + + return verdictOf(120); + }; + accessDeps.hitAccount = async (surface, accountId, limit) => { + log.push(`account:${surface}:${accountId}`); + + return verdictOf(limit); + }; + + return log; +}; +const verdictOf = (limit: number): RateVerdict => ({ + allowed: true, + counted: true, + limit, + remaining: limit - 1, + reset: 60, +}); +const VALID: KeyVerdict = { + kind: 'valid', + keyId: 'key-public-1', + accountId: ACCOUNT, + rateLimit: null, + expiresAt: null, +}; + +// The usage lines forward() writes, kept off the test output. +const lines: string[] = []; + +const fresh = () => { + mock.restoreAll(); + lines.length = 0; + mock.method(console, 'log', (line: string) => lines.push(line)); + seen.length = 0; + Object.assign(accessDeps, original); + delete process.env.API_KEYS_ENABLED; +}; + +test.after(() => mock.restoreAll()); + +test('forward: a valid key goes to dfo-apis as the account, with no key in sight', async () => { + fresh(); + fakes(VALID); + + for (const headers of [ + { authorization: `Bearer ${KEY}` }, + { 'x-api-key': KEY }, + { authorization: `Bearer ${KEY}`, 'x-api-key': KEY }, + ] as Record[]) { + seen.length = 0; + + const res = await call(headers); + + assert.equal(res.status, 200); + assert.equal(res.headers.get('x-ratelimit-limit'), '600'); + assert.equal(seen[0]!['x-dfo-caller'], accountCaller); + assert.equal(seen[0]!['x-dfo-caller-principal'], 'test-principal'); + assert.equal(seen[0]!.authorization, undefined); + assert.equal(seen[0]!['x-api-key'], undefined); + } +}); + +test('forward: an unavailable key store goes on as anonymous with the key still stripped', async () => { + fresh(); + const log = fakes({ kind: 'unavailable' }); + const res = await call({ authorization: `Bearer ${KEY}`, 'x-api-key': KEY }); + + assert.equal(res.status, 200); + assert.deepEqual(log, ['cache', 'address:api', 'lookup']); + assert.equal(seen[0]!['x-dfo-caller'], addressCaller); + assert.equal(seen[0]!.authorization, undefined); + assert.equal(seen[0]!['x-api-key'], undefined); +}); + +test('forward: an invalid key is a 401 and nothing goes upstream', async () => { + fresh(); + fakes({ kind: 'invalid' }); + + const res = await call({ 'x-api-key': KEY }); + + assert.equal(res.status, 401); + assert.equal((await res.json()).code, 'invalid_api_key'); + assert.equal(seen.length, 0); +}); + +test('forward: two different keys are a 400, and an over-long key a 401, with no lookup', async () => { + fresh(); + const log = fakes(VALID); + + assert.equal( + (await call({ authorization: `Bearer ${KEY}`, 'x-api-key': `${KEY}2` })).status, + 400, + ); + assert.equal((await call({ 'x-api-key': `dfo_${'z'.repeat(300)}` })).status, 401); + assert.deepEqual(log, []); + assert.equal(seen.length, 0); +}); + +test('forward: another bearer passes through to dfo-apis as before, and is no key', async () => { + fresh(); + const log = fakes(VALID); + const res = await call({ authorization: 'Bearer some-other-token' }); + + assert.equal(res.status, 200); + assert.deepEqual(log, ['address:api']); + assert.equal(seen[0]!.authorization, 'Bearer some-other-token'); + assert.equal(seen[0]!['x-dfo-caller'], addressCaller); +}); + +test('forward: a call with no key is anonymous, and a client-sent caller is dropped', async () => { + fresh(); + const log = fakes(VALID); + + await call({ 'x-dfo-caller': accountCaller }); + + assert.deepEqual(log, ['address:api']); + assert.equal(seen[0]!['x-dfo-caller'], addressCaller); +}); + +test('forward: /mcp names the account to dfo-ai, and the harness token replaces any bearer', async () => { + fresh(); + fakes(VALID, true); + + const mcp = (headers: Record, options: Options = {}) => + call(headers, { + surface: 'mcp', + target: 'http://127.0.0.1:1/never', + sendCaller: true, + ...options, + }); + + // The target is not dfo-apis here: serve it from a second origin. + const other = createServer((req, res) => { + seen.push(req.headers); + res.writeHead(200).end(); + }); + + other.listen(0, '127.0.0.1'); + await once(other, 'listening'); + + const target = `http://127.0.0.1:${(other.address() as AddressInfo).port}/mcp/`; + + try { + // With the harness token held: read the key, then replace the header. + await mcp({ authorization: `Bearer ${KEY}` }, { target, bearer: 'harness' }); + assert.equal(seen[0]!.authorization, 'Bearer harness'); + assert.equal(seen[0]!['x-dfo-caller'], accountCaller); + assert.equal(seen[0]!['x-dfo-caller-principal'], undefined); + + // Without it: the key is the proxy's own, so no credential goes on. + seen.length = 0; + await mcp({ authorization: `Bearer ${KEY}` }, { target }); + assert.equal(seen[0]!.authorization, undefined); + assert.equal(seen[0]!['x-api-key'], undefined); + + // The key in X-API-Key, the harness token as the bearer: both work. + seen.length = 0; + await mcp({ authorization: 'Bearer harness-token', 'x-api-key': KEY }, { target }); + assert.equal(seen[0]!.authorization, 'Bearer harness-token'); + assert.equal(seen[0]!['x-api-key'], undefined); + assert.equal(seen[0]!['x-dfo-caller'], accountCaller); + + // Anonymous callers are named by address, as before. + seen.length = 0; + await mcp({}, { target }); + assert.equal(seen[0]!['x-dfo-caller'], addressCaller); + } finally { + other.closeAllConnections(); + other.close(); + } +}); + +test('forward: the Studio strips a key and otherwise ignores it', async () => { + fresh(); + const log = fakes({ kind: 'invalid' }); + + for (const headers of [ + { 'x-api-key': KEY }, + { authorization: `Bearer ${KEY}` }, + { authorization: `Bearer ${KEY}`, 'x-api-key': 'something else' }, + ] as Record[]) { + seen.length = 0; + + const res = await call(headers, { keys: false, bearer: 'studio-token' }); + + assert.equal(res.status, 200); + assert.equal(seen[0]!.authorization, 'Bearer studio-token'); + assert.equal(seen[0]!['x-api-key'], undefined); + } + + // Counted by address only, never looked up. + assert.ok(log.every((entry) => entry === 'address:api')); +}); + +test('forward: API_KEYS_ENABLED=false strips keys and treats every call as anonymous', async () => { + fresh(); + process.env.API_KEYS_ENABLED = 'false'; + + const log = fakes({ kind: 'invalid' }); + const res = await call({ authorization: `Bearer ${KEY}`, 'x-api-key': 'junk' }); + + assert.equal(res.status, 200); + assert.deepEqual(log, ['address:api']); + assert.equal(seen[0]!.authorization, undefined); + assert.equal(seen[0]!['x-api-key'], undefined); + assert.equal(seen[0]!['x-dfo-caller'], addressCaller); +}); + +test('forward on a real key store and counter', async (t) => { + fresh(); + const database = await createTestDatabase(); + + await applyMigrations(database.migratorPool(), { + migrationsFolder: path.resolve(import.meta.dirname, '../../../../db/migrations'), + runtimeDbUser: database.runtimeUser, + migratorDbUser: database.migratorUser, + }); + + const host = process.env.PGHOST ?? 'localhost'; + const port = process.env.PGPORT ?? '5433'; + const env = { + DATABASE_URL: `postgres://${database.runtimeUser}:${database.runtimePassword}@${host}:${port}/${database.databaseName}`, + }; + const keyPool = buildKeyPool(env); + const counterPool = buildCounterPool(env); + + t.after(async () => { + await Promise.all([keyPool.end(), counterPool.end()]); + await database.teardown(); + }); + + const limiter = createLimiter(drizzle(counterPool), { windowS: 3600, warn: () => {} }); + const admin = database.adminPool(); + const keys: Record = {}; + + for (const [id, limit] of [ + ['own', 3], + ['default', null], + ] as const) { + await admin.query( + `insert into "user" (id, name, email, email_verified, created_at, updated_at, api_rate_limit) + values ($1, $1, $1 || '@a.example', true, now(), now(), $2)`, + [id, limit], + ); + + keys[id] = `dfo_live_${id.padEnd(32, '0')}`; + await admin.query( + `insert into apikey (id, reference_id, key, created_at, updated_at) + values ($1, $3, $2, now(), now())`, + [`key-${id}`, await defaultKeyHasher(keys[id]), id], + ); + } + + const wire = (verifierPool: Pool) => { + Object.assign(accessDeps, { + verifier: createKeyVerifier(drizzle(verifierPool, { schema }), { log: () => {} }), + hitAddress: (surface: 'api' | 'mcp' | 'pin', ip: string) => + limiter.hitKey(surface, ip, { api: 3, mcp: 3, pin: 3 }[surface]), + hitAccount: (surface: 'api' | 'mcp' | 'pin', accountId: string, limit: number) => + limiter.hitKey(surface, `acct:${accountId}`, limit), + defaultLimit: 5, + }); + }; + + wire(keyPool); + + await t.test('an account is held to its own limit, apart per surface', async () => { + const statuses = []; + + for (let i = 0; i < 4; i++) { + statuses.push((await call({ 'x-api-key': keys.own! })).status); + } + + assert.deepEqual(statuses, [200, 200, 200, 429]); + assert.equal((await call({ 'x-api-key': keys.own! }, { surface: 'mcp' })).status, 200); + }); + + await t.test('an account with no limit of its own gets the default', async () => { + const statuses = []; + + for (let i = 0; i < 6; i++) { + const res = await call({ authorization: `Bearer ${keys.default}` }); + + statuses.push(res.status); + + if (i === 0) { + assert.equal(res.headers.get('x-ratelimit-limit'), '5'); + assert.equal(res.headers.get('x-ratelimit-remaining'), '4'); + } + } + + assert.deepEqual(statuses, [200, 200, 200, 200, 200, 429]); + }); + + await t.test( + 'an unknown key is a 401, and a key lookup costs the address a count first', + async () => { + const bogus = `dfo_live_${'q'.repeat(32)}`; + const fresh = { 'x-forwarded-for': '198.51.100.9' }; + const statuses = []; + + // The address's own allowance (3 here) bounds the lookups it can cause. + for (let i = 0; i < 4; i++) { + statuses.push((await call({ ...fresh, 'x-api-key': bogus })).status); + } + + assert.deepEqual(statuses, [401, 401, 401, 429]); + }, + ); + + await t.test('anonymous calls are counted by address, unchanged', async () => { + const fresh = { 'x-forwarded-for': '198.51.100.10' }; + const statuses = []; + + for (let i = 0; i < 4; i++) { + statuses.push((await call(fresh)).status); + } + + assert.deepEqual(statuses, [200, 200, 200, 429]); + }); + + await t.test( + 'an unreachable key store passes a keyed call as anonymous, at the address limit', + async () => { + const dead = new Pool({ + host: '127.0.0.1', + port: 1, + max: 1, + connectionTimeoutMillis: 300, + }); + + dead.on('error', () => {}); + t.after(() => dead.end()); + wire(dead); + + const fresh = { 'x-forwarded-for': '198.51.100.11', 'x-api-key': keys.default! }; + const statuses = []; + + for (let i = 0; i < 4; i++) { + statuses.push((await call(fresh)).status); + } + + assert.deepEqual(statuses, [200, 200, 200, 429]); + }, + ); +}); diff --git a/src/lib/proxy/test/limitFallback.test.ts b/src/lib/proxy/test/limitFallback.test.ts new file mode 100644 index 0000000..98f1c88 --- /dev/null +++ b/src/lib/proxy/test/limitFallback.test.ts @@ -0,0 +1,65 @@ +/** + * `limitFallback.ts`: the in-memory count a server instance falls back to + * when the shared count is unavailable. + */ +import assert from 'node:assert/strict'; +import test from 'node:test'; + +import { createFallbackCounter } from '../limitFallback.ts'; + +test('fallback: holds a key to its limit within a window and starts over in the next', () => { + let now = 1_000_000 * 60_000; + const counter = createFallbackCounter(60, { now: () => now }); + const verdicts = Array.from({ length: 4 }, () => counter.hit('api:1.2.3.4', 3)); + + assert.deepEqual( + verdicts.map(({ allowed, remaining }) => [allowed, remaining]), + [ + [true, 2], + [true, 1], + [true, 0], + [false, 0], + ], + ); + assert.equal(verdicts[0]!.limit, 3); + assert.equal(verdicts[0]!.reset, 60); + + now += 30_000; + assert.equal(counter.hit('api:1.2.3.4', 3).reset, 30); + + now += 30_000; + assert.deepEqual(counter.hit('api:1.2.3.4', 3), { + allowed: true, + limit: 3, + remaining: 2, + reset: 60, + }); +}); + +test('fallback: keys count apart, and the limit can differ per call', () => { + const counter = createFallbackCounter(60); + + assert.equal(counter.hit('api:a', 1).allowed, true); + assert.equal(counter.hit('api:a', 1).allowed, false); + assert.equal(counter.hit('api:b', 1).allowed, true); + assert.equal(counter.hit('mcp:a', 1).allowed, true); +}); + +test('fallback: memory is bounded, dropping ended windows first and then the oldest keys', () => { + let now = 0; + const counter = createFallbackCounter(60, { now: () => now, maxKeys: 3 }); + + for (const key of ['a', 'b', 'c', 'd', 'e']) { + counter.hit(key, 10); + } + + assert.equal(counter.size(), 3); + + // The oldest were dropped, so 'a' starts over; the newest kept its count. + assert.equal(counter.hit('e', 10).remaining, 8); + assert.equal(counter.hit('a', 10).remaining, 9); + + now += 61_000; + counter.hit('z', 10); + assert.equal(counter.size(), 1); +}); diff --git a/src/lib/proxy/test/openapi.test.ts b/src/lib/proxy/test/openapi.test.ts index 396d90e..3fa9e70 100644 --- a/src/lib/proxy/test/openapi.test.ts +++ b/src/lib/proxy/test/openapi.test.ts @@ -89,6 +89,37 @@ test('publicOpenApi: keeps the schemas the kept paths and webhooks reach, throug ]); }); +test('publicOpenApi: declares the optional API key as bearer and X-API-Key', () => { + const out = publicOpenApi(structuredClone(DOCUMENT)); + + const schemes = (document: typeof out) => + (document.components as { securitySchemes?: Record }).securitySchemes; + + assert.deepEqual(Object.keys(schemes(out) ?? {}), ['ApiKeyBearer', 'ApiKeyHeader']); + assert.deepEqual(schemes(out)?.ApiKeyHeader, { + type: 'apiKey', + in: 'header', + name: 'X-API-Key', + description: 'The same optional API key, as `X-API-Key: `.', + }); + // Optional: the empty requirement comes first. + assert.deepEqual(out.security, [{}, { ApiKeyBearer: [] }, { ApiKeyHeader: [] }]); + // The document's own schemes and security stay. + const own: Record & typeof DOCUMENT = structuredClone(DOCUMENT); + + Object.assign(own.components, { securitySchemes: { Mine: { type: 'http', scheme: 'basic' } } }); + own.security = [{ Mine: [] }]; + + const kept = publicOpenApi(own as typeof DOCUMENT); + + assert.deepEqual(Object.keys(schemes(kept as typeof out) ?? {}), [ + 'Mine', + 'ApiKeyBearer', + 'ApiKeyHeader', + ]); + assert.deepEqual(kept.security, [{ Mine: [] }]); +}); + test('publicOpenApi: keeps every schema when a $ref names one the document lacks', () => { const document = structuredClone(DOCUMENT); diff --git a/src/lib/proxy/test/rateLimit.test.ts b/src/lib/proxy/test/rateLimit.test.ts new file mode 100644 index 0000000..43ffb09 --- /dev/null +++ b/src/lib/proxy/test/rateLimit.test.ts @@ -0,0 +1,120 @@ +/** + * `rateLimit.ts`'s limiter on a migrated database: an address and an account + * count apart, each against its own limit, on each surface; and a count that + * fails or is slow does not let a burst through, since the instance counts it + * in memory. + */ +import '../../test/serverModules.ts'; + +import assert from 'node:assert/strict'; +import path from 'node:path'; +import test from 'node:test'; + +import { drizzle } from 'drizzle-orm/node-postgres'; + +import { applyMigrations } from '../../../../db/apply-migrations.ts'; +import { buildCounterPool } from '../../../../db/connection.ts'; +import { createTestDatabase } from '../../../../db/test/harness.ts'; +import { createFallbackCounter } from '../limitFallback.ts'; + +const { createLimiter } = await import('../rateLimit.ts'); + +const MIGRATIONS_FOLDER = path.resolve(import.meta.dirname, '../../../../db/migrations'); + +test('limiter: counts an address and an account apart, per surface, at the limit given', async (t) => { + const database = await createTestDatabase(); + + await applyMigrations(database.migratorPool(), { + migrationsFolder: MIGRATIONS_FOLDER, + runtimeDbUser: database.runtimeUser, + migratorDbUser: database.migratorUser, + }); + + const host = process.env.PGHOST ?? 'localhost'; + const port = process.env.PGPORT ?? '5433'; + const pool = buildCounterPool({ + DATABASE_URL: `postgres://${database.runtimeUser}:${database.runtimePassword}@${host}:${port}/${database.databaseName}`, + }); + + t.after(async () => { + await pool.end(); + await database.teardown(); + }); + + const limiter = createLimiter(drizzle(pool), { + windowS: 3600, + warn: () => assert.fail('warned'), + }); + + await t.test('an account is held to its limit, and an address to its own', async () => { + const account = []; + + for (let i = 0; i < 4; i++) { + account.push(await limiter.hitKey('api', 'acct:a', 3)); + } + + assert.deepEqual( + account.map(({ allowed, remaining, counted }) => [allowed, remaining, counted]), + [ + [true, 2, true], + [true, 1, true], + [true, 0, true], + [false, 0, true], + ], + ); + assert.equal(account[0]!.limit, 3); + assert.equal((await limiter.hitKey('api', '203.0.113.7', 120)).remaining, 119); + }); + + await t.test('the same account counts on each surface apart', async () => { + assert.equal((await limiter.hitKey('mcp', 'acct:a', 3)).remaining, 2); + assert.equal((await limiter.hitKey('api', 'acct:b', 3)).remaining, 2); + }); +}); + +test('limiter: a count that fails is counted in memory instead of passing, and warns', async () => { + const warned: string[] = []; + const broken = { + execute: async () => { + throw new Error('database is down'); + }, + }; + const limiter = createLimiter(broken as never, { + windowS: 60, + warn: (message) => warned.push(message), + prune: false, + fallback: createFallbackCounter(60), + }); + const verdicts = []; + + for (let i = 0; i < 4; i++) { + verdicts.push(await limiter.hitKey('api', '203.0.113.7', 3)); + } + + assert.deepEqual( + verdicts.map(({ allowed, remaining, counted }) => [allowed, remaining, counted]), + [ + [true, 2, true], + [true, 1, true], + [true, 0, true], + [false, 0, true], + ], + ); + assert.equal(warned.length, 4); + + // Keyed callers fall back the same way, each account apart. + assert.equal((await limiter.hitKey('api', 'acct:a', 1)).allowed, true); + assert.equal((await limiter.hitKey('api', 'acct:a', 1)).allowed, false); + assert.equal((await limiter.hitKey('api', 'acct:b', 1)).allowed, true); +}); + +test('limiter: a count that times out falls back too', async () => { + const slow = { + execute: () => + new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 10)), + }; + const limiter = createLimiter(slow as never, { windowS: 60, warn: () => {}, prune: false }); + + assert.equal((await limiter.hitKey('mcp', 'x', 1)).allowed, true); + assert.equal((await limiter.hitKey('mcp', 'x', 1)).allowed, false); +}); From 344b46afa29eb4c721b41304b28f59a82d698054 Mon Sep 17 00:00:00 2001 From: Sef Kloninger Date: Mon, 16 Nov 2026 12:02:24 -0800 Subject: [PATCH 20/34] feat(proxy): log API key usage from forward() (#142) One structured line per call that carried a key, written where the key is checked: the key's public id, its account, the surface and the outcome (allowed, limited, invalid or unavailable). Never the key or its hash. The request log still names a keyed call by its address, since it is written from raw headers when the response closes; docs/analytics.md says so and describes the new line. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf --- docs/analytics.md | 10 ++++++ src/lib/proxy/forward.ts | 23 ++++++++++++- src/lib/proxy/test/forwardKeys.test.ts | 45 ++++++++++++++++++++++++++ 3 files changed, 77 insertions(+), 1 deletion(-) diff --git a/docs/analytics.md b/docs/analytics.md index 404f805..a35cf75 100644 --- a/docs/analytics.md +++ b/docs/analytics.md @@ -104,6 +104,16 @@ The site writes one JSON line to stdout for each logged request, which Cloud Log The line reads the request's raw headers, which keep the `RSC` and `Next-Router-Prefetch` headers that Next.js removes from `request.headers`. Logging leaves request bodies unread, so API and MCP payloads stream to their handlers in full. A Next.js proxy would buffer those bodies and truncate them at its default 10 MB limit. +### API key usage line + +A call to the platform proxy (`/api/v1/*`, `/openapi.json`, `/codes`, `/mcp`) that carries an API key also writes one line from `forward()` (`src/lib/proxy/forward.ts`), when the call is decided and before it goes upstream: + +```json +{"severity":"INFO","message":"api key call","surface":"api","outcome":"allowed","keyId":"…","accountId":"…"} +``` + +`keyId` is the key's public id (the plugin's `apikey.id`) and `accountId` its owner. Neither is the key or its hash, which are never logged. `surface` is `api` or `mcp`. `outcome` is `allowed` (counted against the account), `limited` (the account's allowance, or the address's when the key was not yet looked up, was spent: a 429), `invalid` (unknown, disabled, expired or over-long: a 401, with null ids) or `unavailable` (the key store could not be read, so the call went on as anonymous, with null ids). The `request` line above still names a keyed call by its address: it is written from the raw headers when the response closes and does not see the key. Count keyed use from this line. + ## Studio prompt allowance A Studio prompt is one turn (`POST /api/studio/turn`). The proxy atomically reserves one from the caller's daily allowance before it forwards the turn (`src/lib/studio/spendPrompt.ts`). Refused requests consume no allowance. A guest gets 5 a day per network address, an IPv6 address counted by its /64, so guests behind one shared address share them. A signed-in user gets 75 a day, counted per inbox: the address lower-cased, without a `+tag` and, for Gmail, without dots (`inboxOf` in `src/lib/auth/inbox.ts`). An email code makes a separate account for each spelling of one address, and those accounts share the 75. Both reset at 00:00 UTC. The numbers live in `src/lib/studio/promptAllowance.ts` and the counts in the `limit_counter` table. A turn past its allowance gets a 429 `resource_exhausted`, whose detail the chat shows as the reply. Allowance and rate-limit queries use a separate two-connection pool with a 400 ms database statement limit, a 500 ms client query limit, and a 2 s connection limit, so they cannot occupy the pool used for sessions and history. An allowance that cannot be read gets a 503. A turn the harness answers with anything but success gives its reservation back in its original counter window, since no model ran. The proxy forwards only the four routes the browser calls (`turn`, `interrupt`, `cancel`, `composition`) and answers 404 to any other path, so no encoding of a path reaches the turn route without spending a prompt. diff --git a/src/lib/proxy/forward.ts b/src/lib/proxy/forward.ts index bf8a48c..1e4e68f 100644 --- a/src/lib/proxy/forward.ts +++ b/src/lib/proxy/forward.ts @@ -5,7 +5,7 @@ import type { NextRequest } from 'next/server'; import { apisFetch } from '@/lib/apisAuth'; import { keyDb } from '@/lib/db'; -import { decideAccess, type AccessDeps } from './access'; +import { decideAccess, type Access, type AccessDeps } from './access'; import { API_KEY_HEADER, bearerKey } from './apiKey'; import { accountCaller, @@ -102,6 +102,25 @@ export const accessDeps: AccessDeps = { const keysEnabled = (): boolean => !['false', '0', 'off', 'no'].includes(process.env.API_KEYS_ENABLED?.trim().toLowerCase() ?? ''); +// One structured line per call that carried a key. The key's public id and +// the account are named; the key and its hash never are. +const logKeyUse = (surface: Surface | undefined, { identity, outcome }: Access): void => { + if (!outcome) { + return; + } + + console.log( + JSON.stringify({ + severity: 'INFO', + message: 'api key call', + surface: surface ?? null, + outcome, + keyId: identity.kind === 'keyed' ? identity.keyId : null, + accountId: identity.kind === 'keyed' ? identity.accountId : null, + }), + ); +}; + type ForwardOptions = { // Which allowance applies (see rateLimit's LIMITS); unset, no limit. surface?: Surface; @@ -181,6 +200,8 @@ export const forward = async (req: NextRequest, options: ForwardOptions): Promis ip: clientIp(req), }); + logKeyUse(options.surface, access); + if (access.refusal) { return access.refusal; } diff --git a/src/lib/proxy/test/forwardKeys.test.ts b/src/lib/proxy/test/forwardKeys.test.ts index ac404ef..ecf92a8 100644 --- a/src/lib/proxy/test/forwardKeys.test.ts +++ b/src/lib/proxy/test/forwardKeys.test.ts @@ -302,6 +302,51 @@ test('forward: API_KEYS_ENABLED=false strips keys and treats every call as anony assert.equal(seen[0]!['x-dfo-caller'], addressCaller); }); +test('forward: logs one line per keyed call with the key id, account, surface and outcome, never the key', async () => { + fresh(); + fakes(VALID); + await call({ authorization: `Bearer ${KEY}` }); + + fakes({ kind: 'invalid' }); + await call({ 'x-api-key': KEY }, { surface: 'mcp' }); + + fakes({ kind: 'unavailable' }); + await call({ 'x-api-key': KEY }); + + await call({}); + + assert.deepEqual( + lines.map((line) => JSON.parse(line)), + [ + { + severity: 'INFO', + message: 'api key call', + surface: 'api', + outcome: 'allowed', + keyId: 'key-public-1', + accountId: ACCOUNT, + }, + { + severity: 'INFO', + message: 'api key call', + surface: 'mcp', + outcome: 'invalid', + keyId: null, + accountId: null, + }, + { + severity: 'INFO', + message: 'api key call', + surface: 'api', + outcome: 'unavailable', + keyId: null, + accountId: null, + }, + ], + ); + assert.doesNotMatch(lines.join('\n'), /dfo_live/); +}); + test('forward on a real key store and counter', async (t) => { fresh(); const database = await createTestDatabase(); From aeedf4618c2f608e286a8035c13b0168f271332e Mon Sep 17 00:00:00 2001 From: Sef Kloninger Date: Mon, 16 Nov 2026 12:28:16 -0800 Subject: [PATCH 21/34] feat(account): add an API keys page to the account menu (#142) /account/api-keys lists the signed-in user's keys, makes one from a label and deletes one after a confirmation. The full key is shown once, at creation, with a copy button; only its hash is stored. Server actions take the owner from the session, force the dfo_live_ prefix, pass no expiry, limit, metadata or permissions, and delete the row to revoke. An account holds at most API_KEYS_MAX_PER_ACCOUNT keys (default 5). The page shows the account's limit read-only and how to send a key. The key service (src/lib/apiKeys/service) also carries the operator functions the admin page uses next, and its tests cover them: ownership, the forced prefix, the cap, and a created key verifying through the proxy's key verifier. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf --- .env.example | 4 + deploy/README.md | 1 + package.json | 2 +- src/app/(site)/account/api-keys/actions.ts | 64 +++ src/app/(site)/account/api-keys/page.tsx | 38 ++ .../molecules/AccountMenu/AccountMenu.tsx | 5 + .../organisms/ApiKeys/AccountApiKeys.tsx | 125 ++++++ .../organisms/ApiKeys/ApiKeys.module.scss | 291 ++++++++++++++ .../organisms/ApiKeys/ApiKeysShell.tsx | 35 ++ .../organisms/ApiKeys/CreateKeyForm.tsx | 104 +++++ .../organisms/ApiKeys/DeleteKeyButton.tsx | 57 +++ src/components/organisms/ApiKeys/format.ts | 10 + src/components/organisms/ApiKeys/state.ts | 10 + src/lib/apiKeys/server.ts | 50 +++ src/lib/apiKeys/service.ts | 280 ++++++++++++++ src/lib/apiKeys/settings.ts | 119 ++++++ src/lib/apiKeys/test/service.test.ts | 364 ++++++++++++++++++ src/lib/apiKeys/test/settings.test.ts | 98 +++++ src/lib/proxy/forward.ts | 2 +- 19 files changed, 1657 insertions(+), 2 deletions(-) create mode 100644 src/app/(site)/account/api-keys/actions.ts create mode 100644 src/app/(site)/account/api-keys/page.tsx create mode 100644 src/components/organisms/ApiKeys/AccountApiKeys.tsx create mode 100644 src/components/organisms/ApiKeys/ApiKeys.module.scss create mode 100644 src/components/organisms/ApiKeys/ApiKeysShell.tsx create mode 100644 src/components/organisms/ApiKeys/CreateKeyForm.tsx create mode 100644 src/components/organisms/ApiKeys/DeleteKeyButton.tsx create mode 100644 src/components/organisms/ApiKeys/format.ts create mode 100644 src/components/organisms/ApiKeys/state.ts create mode 100644 src/lib/apiKeys/server.ts create mode 100644 src/lib/apiKeys/service.ts create mode 100644 src/lib/apiKeys/settings.ts create mode 100644 src/lib/apiKeys/test/service.test.ts create mode 100644 src/lib/apiKeys/test/settings.test.ts diff --git a/.env.example b/.env.example index 075e9c7..16e4c4d 100644 --- a/.env.example +++ b/.env.example @@ -123,6 +123,10 @@ SENTRY_AUTH_TOKEN= # RATE_LIMIT_KEYED=600 # Emergency switch: false strips keys and counts every call by address. # API_KEYS_ENABLED=true +# How many API keys one account may hold on /account/api-keys (default 5). +# Housekeeping, not security: the limit is per account, so a second key adds +# no calls. +# API_KEYS_MAX_PER_ACCOUNT=5 # The harness's own token for its MCP server (MCP_API_TOKEN on dfo-ai); # attached by the proxy so outside MCP clients don't need it. Unset: the # caller's own Authorization header is passed through. diff --git a/deploy/README.md b/deploy/README.md index 7ee3940..3e7aca0 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -253,6 +253,7 @@ The app defines the definitive contract once it exists. Known so far: | `RATE_LIMIT_MCP` | Requests per window per address on `/mcp`; default 300, above `/api` because a vendor's address can carry many users | | `RATE_LIMIT_KEYED` | Calls per window per account, on each of `/api` and `/mcp`, for a call with a valid API key whose account has no limit of its own (`user.api_rate_limit`); default 600 | | `API_KEYS_ENABLED` | Emergency switch for API keys; default on. `false`, `0`, `off` or `no` strips keys and counts every call by address, without a code change | +| `API_KEYS_MAX_PER_ACCOUNT` | How many API keys one account may hold on `/account/api-keys`; default 5. Housekeeping, not security, since limits are per account | | `OPENAI_APPS_CHALLENGE` | OpenAI's domain-verification token; `/.well-known/openai-apps-challenge` serves it as plain text, 404 while unset | | `TRUSTED_PROXY_HOPS` | Which `X-Forwarded-For` entry is the client, counted from the right; keys the `/api` and `/mcp` limits, the guest Studio allowance and the caller digest; default 0 (Cloud Run's); +1 per load balancer | | `WEBSITE_DB_INSTANCE_CONNECTION_NAME` | Cloud SQL instance the connector dials over PSC; set by infra | diff --git a/package.json b/package.json index 41820eb..fc50be1 100644 --- a/package.json +++ b/package.json @@ -16,7 +16,7 @@ "motion-kit": "node motion-kit/cli.ts", "typecheck": "tsc --noEmit && tsc --noEmit -p motion-kit", "check:client-provenance": "node scripts/check-client-provenance.mjs", - "test": "node --test db/test/*.test.ts src/lib/search/test/*.test.ts src/lib/studio/test/*.test.ts src/lib/chat/test/*.test.ts src/lib/proxy/test/*.test.ts src/lib/auth/test/*.test.ts src/lib/mail/test/*.test.ts src/lib/sources/test/*.test.ts src/lib/graphExplorer/test/*.test.ts src/lib/test/*.test.ts src/lib/docs/test/*.test.ts motion-kit/test/*.test.ts", + "test": "node --test db/test/*.test.ts src/lib/search/test/*.test.ts src/lib/studio/test/*.test.ts src/lib/chat/test/*.test.ts src/lib/proxy/test/*.test.ts src/lib/auth/test/*.test.ts src/lib/apiKeys/test/*.test.ts src/lib/mail/test/*.test.ts src/lib/sources/test/*.test.ts src/lib/graphExplorer/test/*.test.ts src/lib/test/*.test.ts src/lib/docs/test/*.test.ts motion-kit/test/*.test.ts", "format": "prettier --write \"src/**/*.{ts,tsx,js,json,scss}\"", "optimize:svg": "svgo -f src/assets -r", "db:generate": "drizzle-kit generate", diff --git a/src/app/(site)/account/api-keys/actions.ts b/src/app/(site)/account/api-keys/actions.ts new file mode 100644 index 0000000..07e155a --- /dev/null +++ b/src/app/(site)/account/api-keys/actions.ts @@ -0,0 +1,64 @@ +'use server'; + +import { revalidatePath } from 'next/cache'; + +import { keyService } from '@/lib/apiKeys/server'; +import { getUser } from '@/lib/auth/session'; + +import type { CreatedState, DeleteState } from '@/components/organisms/ApiKeys/state'; + +// Server actions are POSTs anyone can send, so each one reads the session +// itself. Next.js also refuses one whose Origin is not the page's host, which +// is the CSRF check. An account only ever acts on its own keys: the owner is +// the session's user and nothing from the form. + +const PATH = '/account/api-keys'; + +const REFUSALS = { + label_invalid: 'Give the key a label of 1 to 32 characters.', + cap_reached: 'This account has as many keys as it may hold. Delete one to make another.', + no_such_account: 'That account was not found.', +} as const; + +/** Creates a key for the signed-in user and answers with it, once. */ +export const createKey = async ( + _previous: CreatedState, + formData: FormData, +): Promise => { + const user = await getUser(); + + if (!user) { + return { error: 'Your session has ended. Sign in again.' }; + } + + const result = await keyService.createOwn(user.id, formData.get('label')); + + if (!result.ok) { + return { error: REFUSALS[result.reason] }; + } + + revalidatePath(PATH); + + return { created: { id: result.id, key: result.key } }; +}; + +/** Deletes one of the signed-in user's keys. Another account's is "not found". */ +export const deleteKey = async ( + _previous: DeleteState, + formData: FormData, +): Promise => { + const user = await getUser(); + const keyId = formData.get('keyId'); + + if (!user) { + return { error: 'Your session has ended. Sign in again.' }; + } + + if (typeof keyId !== 'string' || !(await keyService.deleteOwn(user.id, keyId))) { + return { error: 'That key was not found.' }; + } + + revalidatePath(PATH); + + return { error: null }; +}; diff --git a/src/app/(site)/account/api-keys/page.tsx b/src/app/(site)/account/api-keys/page.tsx new file mode 100644 index 0000000..cea212b --- /dev/null +++ b/src/app/(site)/account/api-keys/page.tsx @@ -0,0 +1,38 @@ +import type { Metadata } from 'next'; + +import { createKey, deleteKey } from './actions'; + +import AccountApiKeys from '@/components/organisms/ApiKeys/AccountApiKeys'; +import { keyService, requireUser } from '@/lib/apiKeys/server'; +import { maxKeysPerAccount, rateWindowSeconds } from '@/lib/apiKeys/settings'; +import { keysEnabled } from '@/lib/proxy/forward'; +import { KEYED_LIMIT } from '@/lib/proxy/rateLimit'; + +export const metadata: Metadata = { + title: 'API keys — DFO', + robots: { index: false, follow: false }, +}; + +// Account-only: a signed-out visitor is sent to sign in and back. +const AccountApiKeysPage = async () => { + const user = await requireUser('/account/api-keys'); + const [keys, ownLimit] = await Promise.all([ + keyService.listOwn(user.id), + keyService.accountLimit(user.id), + ]); + + return ( + + ); +}; + +export default AccountApiKeysPage; diff --git a/src/components/molecules/AccountMenu/AccountMenu.tsx b/src/components/molecules/AccountMenu/AccountMenu.tsx index fdda9d4..c3feef0 100644 --- a/src/components/molecules/AccountMenu/AccountMenu.tsx +++ b/src/components/molecules/AccountMenu/AccountMenu.tsx @@ -104,6 +104,11 @@ const AccountMenu = ({ className }: AccountMenuProps) => { My History + navigate('/account/api-keys')}> + + + + {blocked &&

{blocked}

} + {state?.error && ( +

+ {state.error} +

+ )} + {key && ( +
+

+ Copy this key now. You won't see it again. +

+
+ + {key} + + +
+

+ Only a fingerprint of the key is stored, so it cannot be shown again. If you + lose it, delete it and make a new one. +

+
+ )} + + ); +}; + +export default CreateKeyForm; diff --git a/src/components/organisms/ApiKeys/DeleteKeyButton.tsx b/src/components/organisms/ApiKeys/DeleteKeyButton.tsx new file mode 100644 index 0000000..5be2b41 --- /dev/null +++ b/src/components/organisms/ApiKeys/DeleteKeyButton.tsx @@ -0,0 +1,57 @@ +'use client'; + +import { useActionState, useState } from 'react'; + +import styles from './ApiKeys.module.scss'; +import type { DeleteState } from './state'; + +type DeleteKeyButtonProps = { + action: (previous: DeleteState, formData: FormData) => Promise; + keyId: string; + // What the confirmation names: the key's label. + label: string; +}; + +/** Delete in two steps: the button asks, then a second press deletes. */ +const DeleteKeyButton = ({ action, keyId, label }: DeleteKeyButtonProps) => { + const [state, submit, pending] = useActionState(action, null); + const [asking, setAsking] = useState(false); + + if (!asking) { + return ( + + ); + } + + return ( +
+ + Delete “{label}” for good? + + + {state?.error && ( + + {state.error} + + )} +
+ ); +}; + +export default DeleteKeyButton; diff --git a/src/components/organisms/ApiKeys/format.ts b/src/components/organisms/ApiKeys/format.ts new file mode 100644 index 0000000..8b5523d --- /dev/null +++ b/src/components/organisms/ApiKeys/format.ts @@ -0,0 +1,10 @@ +/** A date as the key tables show it, in UTC so a server and a reader agree. */ +export const formatDate = (date: Date | null): string => + date + ? date.toLocaleDateString('en-GB', { + day: 'numeric', + month: 'short', + year: 'numeric', + timeZone: 'UTC', + }) + : '—'; diff --git a/src/components/organisms/ApiKeys/state.ts b/src/components/organisms/ApiKeys/state.ts new file mode 100644 index 0000000..0d807fc --- /dev/null +++ b/src/components/organisms/ApiKeys/state.ts @@ -0,0 +1,10 @@ +/** What an API key form action answers with (src/app/(site)/account/api-keys/actions). */ + +/** A create form's state: the new key, once, or why there is none. Null before the first submit. */ +export type CreatedState = { + created?: { id: string; key: string }; + error?: string; +} | null; + +/** A delete form's state: why it did not delete, or null. */ +export type DeleteState = { error: string | null } | null; diff --git a/src/lib/apiKeys/server.ts b/src/lib/apiKeys/server.ts new file mode 100644 index 0000000..84883dc --- /dev/null +++ b/src/lib/apiKeys/server.ts @@ -0,0 +1,50 @@ +import 'server-only'; + +import { notFound, redirect } from 'next/navigation'; + +import { auth } from '@/lib/auth/auth'; +import { getUser } from '@/lib/auth/session'; +import { db } from '@/lib/db'; + +import { createKeyService } from './service'; +import { adminFrom, maxKeysPerAccount } from './settings'; + +/** The API key service on the site's own auth instance and database. */ +export const keyService = createKeyService({ + auth, + db, + maxPerAccount: () => maxKeysPerAccount(process.env.API_KEYS_MAX_PER_ACCOUNT), +}); + +/** + * The signed-in user for an account page or action. A page sends a signed-out + * visitor to sign in and back (`next`); an action has no page to send them + * from, and answers null. + */ +export const requireUser = async (next: string) => { + const user = await getUser(); + + if (!user) { + redirect(`/login?next=${encodeURIComponent(next)}`); + } + + return user; +}; + +/** + * The admin gate, checked on every admin page and every admin action, since + * an action is a POST anyone can send. The admins are the signed-in users + * whose verified email is in `ADMIN_EMAILS` (settings.isAdmin). Everyone + * else, signed out included, gets the 404 page, not a 403, so a visitor + * cannot tell the page exists. The list is read per call, so a change to it + * needs only a new revision. + */ +export const requireAdmin = async () => { + const admin = adminFrom(await getUser(), process.env.ADMIN_EMAILS); + + if (!admin) { + notFound(); + } + + return admin; +}; diff --git a/src/lib/apiKeys/service.ts b/src/lib/apiKeys/service.ts new file mode 100644 index 0000000..a211be8 --- /dev/null +++ b/src/lib/apiKeys/service.ts @@ -0,0 +1,280 @@ +/** + * What the API key pages do with keys: a signed-in user's own (src/app/(site)/account/api-keys) and + * an operator's over every account (src/app/(site)/admin/api-keys). The plugin's own HTTP + * endpoints for keys stay closed (src/lib/auth/apiKeyOptions), so this is the + * only way in. It decides nothing about who may call: the caller has already + * checked the session or the admin gate (adminGate) and passes the user id or + * the actor in. A user's functions take the user id and never a key's owner, + * so a key is found only under its owner. + * + * Rules, from docs/design/api-keys.md ("How It Would Fit"): + * - the prefix is ours (`dfo_live_`), never taken from a request + * - a key's owner is the id passed in; expiry, metadata, permissions and + * limits are never passed on, so every key has the plugin's defaults and + * the account's own limit (user.api_rate_limit) is the one limit + * - revoking deletes the row: a disabled key could be switched back on + * - the full key is returned by the create call and nowhere else. Only its + * hash is stored, and neither the key nor the hash is logged + * + * Kept apart from the Next.js code, with the auth instance and database + * passed in, so `node --test` can drive it on a test database. + */ +import { and, count, desc, eq, ilike, sql } from 'drizzle-orm'; +import type { NodePgDatabase } from 'drizzle-orm/node-postgres'; + +import { apikey, user } from '../../../db/schema.ts'; +import { API_KEY_PREFIX } from '../auth/apiKeyOptions.ts'; +import { parseLabel } from './settings.ts'; + +/** The parts of the Better Auth instance this module uses. */ +export type KeyAuth = { + api: { + createApiKey(args: { + body: { userId: string; name?: string; prefix?: string }; + }): Promise<{ id: string; key: string }>; + }; + $context: PromiseLike<{ + internalAdapter: { + updateUser(id: string, data: { apiRateLimit: number | null }): Promise; + }; + }>; +}; + +export type KeyDb = Pick; + +export type KeyServiceOptions = { + auth: KeyAuth; + db: KeyDb; + /** How many keys an account may hold; read per call so a change needs no restart. */ + maxPerAccount: () => number; + /** One structured line per mutation. Never receives a key or a hash. */ + log?: (line: Record) => void; +}; + +/** A key as its owner sees it: never the key or its hash. */ +export type OwnKey = { + id: string; + name: string | null; + start: string | null; + createdAt: Date; + // The plugin writes this when it verifies a key. The proxy verifies keys + // itself and does not, so it is empty until the usage log feeds it. + lastRequest: Date | null; +}; + +/** A key and its account, as an operator sees it. */ +export type AdminKey = OwnKey & { + ownerId: string; + ownerEmail: string; + // The account's own limit, null for the default. + accountLimit: number | null; +}; + +export type CreateResult = + | { ok: true; id: string; key: string } + | { ok: false; reason: 'label_invalid' | 'cap_reached' | 'no_such_account' }; + +export const defaultLog = (line: Record): void => { + console.log(JSON.stringify({ severity: 'INFO', ...line })); +}; + +const ownKeyColumns = { + id: apikey.id, + name: apikey.name, + start: apikey.start, + createdAt: apikey.createdAt, + lastRequest: apikey.lastRequest, +}; + +// The most keys one operator list returns. +const ADMIN_LIST_LIMIT = 500; + +/** `value` as a LIKE pattern's literal text. */ +const likeLiteral = (value: string): string => value.replace(/[\\%_]/g, (c) => `\\${c}`); + +export const createKeyService = ({ + auth, + db, + maxPerAccount, + log = defaultLog, +}: KeyServiceOptions) => { + const mint = (userId: string, label: string) => + // The prefix is passed even though the plugin's default is the same, + // so no later change to the plugin options can open it to a request. + auth.api.createApiKey({ body: { userId, name: label, prefix: API_KEY_PREFIX } }); + + const userIdByEmail = async (email: string): Promise => { + const [row] = await db + .select({ id: user.id }) + .from(user) + .where(sql`lower(${user.email}) = ${email.trim().toLowerCase()}`) + .limit(1); + + return row?.id ?? null; + }; + + return { + /** The user's keys, newest first. */ + async listOwn(userId: string): Promise { + return db + .select(ownKeyColumns) + .from(apikey) + .where(eq(apikey.referenceId, userId)) + .orderBy(desc(apikey.createdAt)); + }, + + /** + * A new key for the user, unless the label is not usable or the + * account holds its cap. The full key is in this result and nowhere + * after it. + */ + async createOwn(userId: string, label: unknown): Promise { + const name = parseLabel(label); + + if (!name) { + return { ok: false, reason: 'label_invalid' }; + } + + const [held] = await db + .select({ n: count() }) + .from(apikey) + .where(eq(apikey.referenceId, userId)); + + if ((held?.n ?? 0) >= maxPerAccount()) { + return { ok: false, reason: 'cap_reached' }; + } + + const created = await mint(userId, name); + + log({ message: 'api key created', by: 'owner', keyId: created.id, accountId: userId }); + + return { ok: true, id: created.id, key: created.key }; + }, + + /** Deletes the user's key. False when it is not theirs, or not there. */ + async deleteOwn(userId: string, keyId: string): Promise { + const gone = await db + .delete(apikey) + .where(and(eq(apikey.id, keyId), eq(apikey.referenceId, userId))) + .returning({ id: apikey.id }); + + if (gone.length === 0) { + return false; + } + + log({ message: 'api key deleted', by: 'owner', keyId, accountId: userId }); + + return true; + }, + + /** The account's own limit, or null for the default. */ + async accountLimit(userId: string): Promise { + const [row] = await db + .select({ limit: user.apiRateLimit }) + .from(user) + .where(eq(user.id, userId)) + .limit(1); + + return row?.limit ?? null; + }, + + // Operator functions. The caller has passed the admin gate. + + /** Every key with its owner, newest first, optionally of the accounts whose email contains `email`. */ + async adminList(email?: string): Promise { + const needle = email?.trim(); + const rows = await db + .select({ + ...ownKeyColumns, + ownerId: user.id, + ownerEmail: user.email, + accountLimit: user.apiRateLimit, + }) + .from(apikey) + .innerJoin(user, eq(user.id, apikey.referenceId)) + .where(needle ? ilike(user.email, `%${likeLiteral(needle)}%`) : undefined) + .orderBy(desc(apikey.createdAt)) + .limit(ADMIN_LIST_LIMIT); + + return rows; + }, + + /** A key for the account with this email. Not held to the account cap. */ + async adminCreate(actor: string, email: string, label: unknown): Promise { + const name = parseLabel(label); + + if (!name) { + return { ok: false, reason: 'label_invalid' }; + } + + const accountId = await userIdByEmail(email); + + if (!accountId) { + return { ok: false, reason: 'no_such_account' }; + } + + const created = await mint(accountId, name); + + log({ + message: 'api key admin', + action: 'create', + actor, + keyId: created.id, + accountId, + }); + + return { ok: true, id: created.id, key: created.key }; + }, + + /** Deletes any key. False when there is none by that id. */ + async adminDelete(actor: string, keyId: string): Promise { + const gone = await db + .delete(apikey) + .where(eq(apikey.id, keyId)) + .returning({ id: apikey.id, accountId: apikey.referenceId }); + + if (gone.length === 0) { + return false; + } + + log({ + message: 'api key admin', + action: 'delete', + actor, + keyId, + accountId: gone[0]!.accountId, + }); + + return true; + }, + + /** + * Sets the limit of the account with this email, or clears it with + * null so the deployment default applies. False when there is no + * such account. The proxy's key cache holds the old limit for up to a + * minute. + */ + async adminSetLimit(actor: string, email: string, limit: number | null): Promise { + const accountId = await userIdByEmail(email); + + if (!accountId) { + return false; + } + + const context = await auth.$context; + + await context.internalAdapter.updateUser(accountId, { apiRateLimit: limit }); + log({ + message: 'api key admin', + action: limit === null ? 'clear-limit' : 'set-limit', + actor, + accountId, + limit, + }); + + return true; + }, + }; +}; + +export type KeyService = ReturnType; diff --git a/src/lib/apiKeys/settings.ts b/src/lib/apiKeys/settings.ts new file mode 100644 index 0000000..d5824c0 --- /dev/null +++ b/src/lib/apiKeys/settings.ts @@ -0,0 +1,119 @@ +/** + * The settings and input rules of the API key pages (account and admin), + * apart from the code that stores keys so `node --test` loads them with no + * database. docs/design/api-keys.md, "Phases", is the background. + */ + +const DEFAULT_MAX_PER_ACCOUNT = 5; + +/** + * How many keys one account may hold, from `API_KEYS_MAX_PER_ACCOUNT`. + * Limits are per account, so this is housekeeping and not a security + * control: a second key buys no more calls. A value that is not a whole + * number of at least 1 gives the default. + */ +export const maxKeysPerAccount = (value: string | undefined): number => { + const parsed = Number(value?.trim()); + + return Number.isSafeInteger(parsed) && parsed >= 1 ? parsed : DEFAULT_MAX_PER_ACCOUNT; +}; + +/** + * The admins' addresses from `ADMIN_EMAILS` (comma-separated), trimmed and + * lowercased, empty entries dropped. Unset or empty names nobody. + */ +export const parseAdminEmails = (value: string | undefined): ReadonlySet => + new Set( + (value ?? '') + .split(',') + .map((email) => email.trim().toLowerCase()) + .filter(Boolean), + ); + +/** The fields of a session's user the admin gate reads. */ +export type AdminCandidate = { id: string; email: string; emailVerified: boolean }; + +/** + * Whether the signed-in user is an admin: their address is on the list, + * whatever the case, and the sign-in proved it. An unverified address could + * be anyone's, so it never admits. + */ +export const isAdmin = ( + user: AdminCandidate | null | undefined, + admins: ReadonlySet, +): boolean => !!user && user.emailVerified === true && admins.has(user.email.trim().toLowerCase()); + +/** + * The admin gate's decision from the session's user and `ADMIN_EMAILS` as + * set: who the admin is, or null for anyone else, which the page and action + * answer with a 404. Signed out, an empty list and an unlisted address all + * give null. + */ +export const adminFrom = ( + user: AdminCandidate | null | undefined, + adminEmails: string | undefined, +): { id: string; email: string } | null => + user && isAdmin(user, parseAdminEmails(adminEmails)) + ? { id: user.id, email: user.email } + : null; + +/** The longest key label: the plugin's own bound on a key's name. */ +export const MAX_LABEL_LENGTH = 32; + +/** A label as typed: trimmed, 1 to MAX_LABEL_LENGTH characters, no control characters; else null. */ +export const parseLabel = (value: unknown): string | null => { + if (typeof value !== 'string') { + return null; + } + + const label = value.trim(); + + return label.length >= 1 && + label.length <= MAX_LABEL_LENGTH && + !/[\u0000-\u001f\u007f]/.test(label) + ? label + : null; +}; + +/** The largest limit the `user.api_rate_limit` column (a 32-bit integer) holds. */ +export const MAX_LIMIT = 2_147_483_647; + +export type LimitInput = { ok: true; limit: number | null } | { ok: false }; + +/** + * An account limit as typed in the admin form: a positive whole number, or + * empty to clear it (the deployment default, RATE_LIMIT_KEYED, applies). + */ +export const parseLimitInput = (value: unknown): LimitInput => { + if (typeof value !== 'string') { + return { ok: false }; + } + + const text = value.trim(); + + if (text === '') { + return { ok: true, limit: null }; + } + + if (!/^\d{1,10}$/.test(text)) { + return { ok: false }; + } + + const limit = Number(text); + + return limit >= 1 && limit <= MAX_LIMIT ? { ok: true, limit } : { ok: false }; +}; + +/** An email as typed in an admin form: trimmed and lowercased, and shaped like an address; else null. */ +export const parseEmailInput = (value: unknown): string | null => { + if (typeof value !== 'string') { + return null; + } + + const email = value.trim().toLowerCase(); + + return email.length <= 320 && /^[^\s@]+@[^\s@]+$/.test(email) ? email : null; +}; + +/** The rate-limit window in seconds, from `RATE_LIMIT_WINDOW_S` as the limiter reads it. */ +export const rateWindowSeconds = (value: string | undefined): number => Number(value) || 60; diff --git a/src/lib/apiKeys/test/service.test.ts b/src/lib/apiKeys/test/service.test.ts new file mode 100644 index 0000000..e0097ab --- /dev/null +++ b/src/lib/apiKeys/test/service.test.ts @@ -0,0 +1,364 @@ +import assert from 'node:assert/strict'; +import path from 'node:path'; +import test from 'node:test'; + +import { betterAuth } from 'better-auth'; +import { drizzleAdapter } from 'better-auth/adapters/drizzle'; +import { eq } from 'drizzle-orm'; +import { drizzle } from 'drizzle-orm/node-postgres'; + +import { applyMigrations } from '../../../../db/apply-migrations.ts'; +import * as schema from '../../../../db/schema.ts'; +import { createTestDatabase } from '../../../../db/test/harness.ts'; +import { API_KEY_PATHS, API_KEY_PREFIX, apiKeyPlugin } from '../../auth/apiKeyOptions.ts'; +import { createKeyVerifier } from '../../proxy/keyVerifier.ts'; +import { createKeyService } from '../service.ts'; + +const MIGRATIONS_FOLDER = path.resolve(import.meta.dirname, '../../../../db/migrations'); +const BASE = 'http://localhost:3000'; +const SECRET = 'a-test-secret-long-enough-for-better-auth'; + +/** + * The API key service (src/lib/apiKeys/service) on a migrated database, as + * the runtime role and through a real Better Auth instance set up as the + * site's is: ownership, the forced prefix, the key shown once, the cap, and + * the operator functions, with a key made here verified by the proxy's own + * verifier. + */ +test('API key service', async (t) => { + const database = await createTestDatabase(); + t.after(() => database.teardown()); + + await applyMigrations(database.migratorPool(), { + migrationsFolder: MIGRATIONS_FOLDER, + runtimeDbUser: database.runtimeUser, + migratorDbUser: database.migratorUser, + }); + + const pool = database.runtimePool(); + const db = drizzle(pool, { schema }); + const auth = betterAuth({ + database: drizzleAdapter(db, { provider: 'pg', schema }), + baseURL: BASE, + secret: SECRET, + trustedOrigins: [BASE], + disabledPaths: [...API_KEY_PATHS], + user: { + additionalFields: { + apiRateLimit: { type: 'number', required: false, input: false, returned: false }, + }, + }, + plugins: [apiKeyPlugin()], + }); + const context = await auth.$context; + const lines: Record[] = []; + let cap = 3; + const service = createKeyService({ + auth, + db, + maxPerAccount: () => cap, + log: (line) => lines.push(line), + }); + + const account = async (email: string) => + ( + await context.internalAdapter.createUser( + { email, name: email, emailVerified: true }, + { method: 'email-otp' }, + ) + ).id; + + const alice = await account('alice@a.example'); + const bob = await account('bob@b.example'); + const rowOf = async (id: string) => + (await db.select().from(schema.apikey).where(eq(schema.apikey.id, id)))[0]; + + await t.test('a created key has the forced prefix and the signed-in owner', async () => { + const made = await service.createOwn(alice, 'notebook'); + + assert.ok(made.ok); + assert.match(made.key, /^dfo_live_[A-Za-z0-9]{32}$/); + assert.ok(made.key.startsWith(API_KEY_PREFIX)); + + const row = await rowOf(made.id); + + assert.equal(row?.referenceId, alice); + assert.equal(row?.name, 'notebook'); + assert.equal(row?.prefix, API_KEY_PREFIX); + }); + + await t.test('a key has no expiry, limit, permissions or metadata of its own', async () => { + const made = await service.createOwn(bob, 'plain'); + + assert.ok(made.ok); + + const row = await rowOf(made.id); + + await service.deleteOwn(bob, made.id); + assert.equal(row?.enabled, true); + assert.equal(row?.expiresAt, null); + // The plugin's own per-key limiter is off (apiKeyOptions), so its stored + // default is inert; the account's limit is the one that counts. + assert.equal(row?.remaining, null); + // Stored as JSON text, where null may be the text `null`. + assert.equal(JSON.parse(row?.permissions ?? 'null'), null); + assert.equal(JSON.parse(row?.metadata ?? 'null'), null); + }); + + await t.test('the key is returned once: lists carry neither it nor its hash', async () => { + const made = await service.createOwn(bob, 'once'); + + assert.ok(made.ok); + + const listed = await service.listOwn(bob); + const row = await rowOf(made.id); + + assert.deepEqual(Object.keys(listed[0]!).sort(), [ + 'createdAt', + 'id', + 'lastRequest', + 'name', + 'start', + ]); + assert.ok(row?.key && row.key !== made.key); + + const everything = JSON.stringify([listed, await service.adminList()]); + + assert.equal(everything.includes(made.key), false); + assert.equal(everything.includes(row.key), false); + // The start is the first characters only. + assert.ok(listed[0]!.start && listed[0]!.start.length < made.key.length); + + await service.deleteOwn(bob, made.id); + }); + + await t.test('a user lists only their own keys', async () => { + const mine = await service.createOwn(bob, 'bobs'); + + assert.ok(mine.ok); + + const aliceSees = await service.listOwn(alice); + const bobSees = await service.listOwn(bob); + + assert.ok(aliceSees.length >= 1); + assert.equal( + aliceSees.some((k) => k.id === mine.id), + false, + ); + assert.deepEqual( + bobSees.map((k) => k.id), + [mine.id], + ); + }); + + await t.test("a user cannot delete another's key, and it stays", async () => { + const bobs = (await service.listOwn(bob))[0]!; + + assert.equal(await service.deleteOwn(alice, bobs.id), false); + assert.ok(await rowOf(bobs.id)); + assert.equal(await service.deleteOwn(alice, 'no-such-key'), false); + }); + + await t.test('deleting removes the row, and the key stops verifying', async () => { + const made = await service.createOwn(alice, 'short lived'); + + assert.ok(made.ok); + + // A verifier with no cache memory to speak of: every call reads. + const verifier = createKeyVerifier(db, { validMs: 0, invalidMs: 0 }); + + assert.equal((await verifier.verify(made.key)).kind, 'valid'); + assert.equal(await service.deleteOwn(alice, made.id), true); + assert.equal(await rowOf(made.id), undefined); + assert.equal((await verifier.verify(made.key)).kind, 'invalid'); + }); + + await t.test('a bad label is refused and makes no key', async () => { + const before = (await service.listOwn(alice)).length; + + for (const label of ['', ' ', 'x'.repeat(33), 'a\u0000b', undefined, 7]) { + const result = await service.createOwn(alice, label); + + assert.deepEqual(result, { ok: false, reason: 'label_invalid' }); + } + + assert.equal((await service.listOwn(alice)).length, before); + }); + + await t.test('the per-account cap is enforced, and a deletion frees a place', async () => { + const carol = await account('carol@c.example'); + const made = []; + + for (let i = 0; i < 3; i += 1) { + const result = await service.createOwn(carol, `k${i}`); + + assert.ok(result.ok); + made.push(result); + } + + assert.deepEqual(await service.createOwn(carol, 'one too many'), { + ok: false, + reason: 'cap_reached', + }); + assert.equal((await service.listOwn(carol)).length, 3); + + // The cap is another account's business: Dave is not held by Carol's keys. + const dave = await account('dave@d.example'); + + assert.ok((await service.createOwn(dave, 'mine')).ok); + + assert.equal(await service.deleteOwn(carol, made[0]!.id), true); + assert.ok((await service.createOwn(carol, 'fits now')).ok); + + // Changing the setting applies to the next call. + cap = 4; + assert.ok((await service.createOwn(carol, 'fifth place')).ok); + cap = 3; + }); + + await t.test( + 'a key made here verifies through the proxy verifier, to its account', + async () => { + const erin = await account('erin@e.example'); + const made = await service.createOwn(erin, 'verify me'); + + assert.ok(made.ok); + + const verifier = createKeyVerifier(db); + const verdict = await verifier.verify(made.key); + + assert.equal(verdict.kind, 'valid'); + assert.ok(verdict.kind === 'valid'); + assert.equal(verdict.keyId, made.id); + assert.equal(verdict.accountId, erin); + assert.equal(verdict.rateLimit, null); + assert.equal((await verifier.verify(`${made.key}x`)).kind, 'invalid'); + }, + ); + + await t.test('an account limit reads back, and the verifier sees it', async () => { + const frank = await account('frank@f.example'); + const made = await service.createOwn(frank, 'limited'); + + assert.ok(made.ok); + assert.equal(await service.accountLimit(frank), null); + assert.equal(await service.adminSetLimit('ops@example.org', 'Frank@F.example', 250), true); + assert.equal(await service.accountLimit(frank), 250); + + const verdict = await createKeyVerifier(db).verify(made.key); + + assert.ok(verdict.kind === 'valid'); + assert.equal(verdict.rateLimit, 250); + + // Clearing returns the account to the default. + assert.equal(await service.adminSetLimit('ops@example.org', 'frank@f.example', null), true); + assert.equal(await service.accountLimit(frank), null); + + const after = await createKeyVerifier(db).verify(made.key); + + assert.ok(after.kind === 'valid'); + assert.equal(after.rateLimit, null); + assert.equal(await service.adminSetLimit('ops@example.org', 'nobody@x.example', 5), false); + }); + + await t.test('admin: create for an account by email, case-insensitively', async () => { + const gina = await account('gina@g.example'); + const made = await service.adminCreate('ops@example.org', 'GINA@g.example', 'for partner'); + + assert.ok(made.ok); + assert.match(made.key, /^dfo_live_[A-Za-z0-9]{32}$/); + assert.equal((await rowOf(made.id))?.referenceId, gina); + + const verdict = await createKeyVerifier(db).verify(made.key); + + assert.ok(verdict.kind === 'valid'); + assert.equal(verdict.accountId, gina); + + assert.deepEqual(await service.adminCreate('ops@example.org', 'nobody@x.example', 'x'), { + ok: false, + reason: 'no_such_account', + }); + assert.deepEqual(await service.adminCreate('ops@example.org', 'gina@g.example', ''), { + ok: false, + reason: 'label_invalid', + }); + }); + + await t.test('admin: the cap does not apply to an operator', async () => { + const hank = await account('hank@h.example'); + + for (let i = 0; i < cap + 1; i += 1) { + assert.ok((await service.adminCreate('ops@example.org', 'hank@h.example', `k${i}`)).ok); + } + + assert.equal((await service.listOwn(hank)).length, cap + 1); + assert.equal((await service.createOwn(hank, 'self')).ok, false); + }); + + await t.test('admin: list across accounts, with the owner and limit, and filter', async () => { + const all = await service.adminList(); + const owners = new Set(all.map((k) => k.ownerEmail)); + + assert.ok(owners.has('alice@a.example') && owners.has('bob@b.example')); + assert.equal(all.find((k) => k.ownerEmail === 'frank@f.example')?.accountLimit, null); + + const filtered = await service.adminList(' ALICE@A '); + + assert.ok(filtered.length >= 1); + assert.ok(filtered.every((k) => k.ownerEmail === 'alice@a.example')); + assert.deepEqual(await service.adminList('no-match-anywhere'), []); + + // LIKE wildcards in the filter are text, not patterns. + assert.deepEqual(await service.adminList('%'), []); + assert.deepEqual(await service.adminList('_'), []); + }); + + await t.test('admin: delete any key, and report one that is not there', async () => { + const victim = (await service.listOwn(bob))[0]!; + + assert.equal(await service.adminDelete('ops@example.org', victim.id), true); + assert.equal(await rowOf(victim.id), undefined); + assert.equal(await service.adminDelete('ops@example.org', victim.id), false); + }); + + await t.test('every mutation logs a line without any key or hash', async () => { + const messages = lines.map((l) => l.message); + + assert.ok(messages.includes('api key created')); + assert.ok(messages.includes('api key deleted')); + + const admin = lines.filter((l) => l.message === 'api key admin'); + const actions = new Set(admin.map((l) => l.action)); + + assert.deepEqual([...actions].sort(), ['clear-limit', 'create', 'delete', 'set-limit']); + + for (const line of admin) { + assert.equal(line.actor, 'ops@example.org'); + assert.ok(line.keyId || line.accountId); + } + + const stored = await db.select({ key: schema.apikey.key }).from(schema.apikey); + const logged = JSON.stringify(lines); + + assert.equal(logged.includes('dfo_live_'), false); + + for (const { key } of stored) { + assert.equal(logged.includes(key), false); + } + + // A refused admin attempt (no such key) logs nothing. + const count = lines.length; + + await service.adminDelete('ops@example.org', 'no-such-key'); + await service.adminSetLimit('ops@example.org', 'nobody@x.example', 9); + assert.equal(lines.length, count); + }); + + await t.test('deleting an account deletes its keys', async () => { + const ivy = await account('ivy@i.example'); + + assert.ok((await service.createOwn(ivy, 'gone soon')).ok); + await context.internalAdapter.deleteUser(ivy); + assert.deepEqual(await service.listOwn(ivy), []); + }); +}); diff --git a/src/lib/apiKeys/test/settings.test.ts b/src/lib/apiKeys/test/settings.test.ts new file mode 100644 index 0000000..e040c57 --- /dev/null +++ b/src/lib/apiKeys/test/settings.test.ts @@ -0,0 +1,98 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; + +import { + adminFrom, + isAdmin, + maxKeysPerAccount, + parseAdminEmails, + parseEmailInput, + parseLabel, + parseLimitInput, + rateWindowSeconds, +} from '../settings.ts'; + +const user = (email: string, emailVerified = true) => ({ id: 'u1', email, emailVerified }); + +test('maxKeysPerAccount: the env value, else 5', () => { + assert.equal(maxKeysPerAccount(undefined), 5); + assert.equal(maxKeysPerAccount(''), 5); + assert.equal(maxKeysPerAccount('3'), 3); + assert.equal(maxKeysPerAccount(' 12 '), 12); + + for (const bad of ['0', '-1', '2.5', 'many', 'NaN']) { + assert.equal(maxKeysPerAccount(bad), 5, bad); + } +}); + +test('parseAdminEmails: trimmed, lowercased, empties dropped; unset names nobody', () => { + assert.deepEqual([...parseAdminEmails(' A@x.org, ,b@Y.org,')], ['a@x.org', 'b@y.org']); + assert.equal(parseAdminEmails(undefined).size, 0); + assert.equal(parseAdminEmails('').size, 0); + assert.equal(parseAdminEmails(' , ').size, 0); +}); + +test('isAdmin: matches the email whatever the case, and needs it verified', () => { + const admins = parseAdminEmails('Ops@Example.org'); + + assert.equal(isAdmin(user('ops@example.org'), admins), true); + assert.equal(isAdmin(user('OPS@EXAMPLE.ORG'), admins), true); + assert.equal(isAdmin(user('other@example.org'), admins), false); + assert.equal(isAdmin(user('ops@example.org', false), admins), false); + assert.equal(isAdmin(null, admins), false); + assert.equal(isAdmin(undefined, admins), false); +}); + +test('adminFrom: an empty or unset ADMIN_EMAILS admits nobody; signed out is not an admin', () => { + assert.equal(adminFrom(user('ops@example.org'), undefined), null); + assert.equal(adminFrom(user('ops@example.org'), ''), null); + assert.equal(adminFrom(user('ops@example.org'), ' , '), null); + assert.equal(adminFrom(null, 'ops@example.org'), null); + assert.equal(adminFrom(user('x@example.org'), 'ops@example.org'), null); + assert.deepEqual(adminFrom(user('Ops@example.org'), 'ops@example.org, b@c.d'), { + id: 'u1', + email: 'Ops@example.org', + }); +}); + +test('an address that only contains an admin address is not one', () => { + assert.equal(adminFrom(user('ops@example.org.evil.test'), 'ops@example.org'), null); + assert.equal(adminFrom(user('xops@example.org'), 'ops@example.org'), null); +}); + +test('parseLabel: 1 to 32 characters, trimmed, no control characters', () => { + assert.equal(parseLabel(' my notebook '), 'my notebook'); + assert.equal(parseLabel('x'.repeat(32)), 'x'.repeat(32)); + assert.equal(parseLabel('x'.repeat(33)), null); + assert.equal(parseLabel(' '), null); + assert.equal(parseLabel(''), null); + assert.equal(parseLabel('a\nb'), null); + assert.equal(parseLabel(undefined), null); + assert.equal(parseLabel(42), null); +}); + +test('parseLimitInput: a positive integer, or empty to clear', () => { + assert.deepEqual(parseLimitInput('250'), { ok: true, limit: 250 }); + assert.deepEqual(parseLimitInput(' 7 '), { ok: true, limit: 7 }); + assert.deepEqual(parseLimitInput(''), { ok: true, limit: null }); + assert.deepEqual(parseLimitInput(' '), { ok: true, limit: null }); + + for (const bad of ['0', '-5', '1.5', '1e3', 'ten', '2147483648', '99999999999', null, 5]) { + assert.deepEqual(parseLimitInput(bad), { ok: false }, String(bad)); + } + + assert.deepEqual(parseLimitInput('2147483647'), { ok: true, limit: 2147483647 }); +}); + +test('parseEmailInput: trimmed, lowercased, address-shaped', () => { + assert.equal(parseEmailInput(' Ops@Example.org '), 'ops@example.org'); + assert.equal(parseEmailInput('no at sign'), null); + assert.equal(parseEmailInput('a b@c.d'), null); + assert.equal(parseEmailInput(null), null); +}); + +test('rateWindowSeconds: the env value, else 60', () => { + assert.equal(rateWindowSeconds(undefined), 60); + assert.equal(rateWindowSeconds('30'), 30); + assert.equal(rateWindowSeconds('x'), 60); +}); diff --git a/src/lib/proxy/forward.ts b/src/lib/proxy/forward.ts index 1e4e68f..0e3b8ea 100644 --- a/src/lib/proxy/forward.ts +++ b/src/lib/proxy/forward.ts @@ -99,7 +99,7 @@ export const accessDeps: AccessDeps = { // API_KEYS_ENABLED is the emergency switch: set to `false` (or `0`, `off`, // `no`), keys are stripped and every call is treated as anonymous. Read per // call, so a test can flip it. -const keysEnabled = (): boolean => +export const keysEnabled = (): boolean => !['false', '0', 'off', 'no'].includes(process.env.API_KEYS_ENABLED?.trim().toLowerCase() ?? ''); // One structured line per call that carried a key. The key's public id and From 34d1f304089a40c79ed6c6743470469f6d2a29b7 Mon Sep 17 00:00:00 2001 From: Sef Kloninger Date: Mon, 16 Nov 2026 12:28:17 -0800 Subject: [PATCH 22/34] feat(admin): add an API keys admin page, a proof of concept (#142) /admin/api-keys lists every key across accounts (id, label, start, owner email, created, last request, account limit) with an email filter, makes a key for an account by email (shown once), deletes any key, and sets or clears an account's limit. It shows whether API_KEYS_ENABLED is on. Admins are signed-in users whose verified email is in ADMIN_EMAILS (comma-separated, case-insensitive; unset or empty means no admins). The gate runs on the page and again in every action, and answers anyone else, signed out included, with the 404 page. Each mutation logs one structured line with the actor's email, the action and the key or account id, never a key. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf --- .env.example | 6 + deploy/README.md | 1 + src/app/(site)/admin/api-keys/actions.ts | 83 +++++++++ src/app/(site)/admin/api-keys/page.tsx | 54 ++++++ .../organisms/ApiKeys/AdminApiKeys.tsx | 161 ++++++++++++++++++ 5 files changed, 305 insertions(+) create mode 100644 src/app/(site)/admin/api-keys/actions.ts create mode 100644 src/app/(site)/admin/api-keys/page.tsx create mode 100644 src/components/organisms/ApiKeys/AdminApiKeys.tsx diff --git a/.env.example b/.env.example index 16e4c4d..2a211cd 100644 --- a/.env.example +++ b/.env.example @@ -127,6 +127,12 @@ SENTRY_AUTH_TOKEN= # Housekeeping, not security: the limit is per account, so a second key adds # no calls. # API_KEYS_MAX_PER_ACCOUNT=5 +# Who may open /admin/api-keys, which lists every account's keys, makes and +# deletes keys and sets an account's limit (a proof of concept). Comma- +# separated emails, matched without regard to case against a signed-in user +# whose email is verified. Everyone else gets a 404. Unset or empty: no +# admins, so the page is closed to all. +# ADMIN_EMAILS= # The harness's own token for its MCP server (MCP_API_TOKEN on dfo-ai); # attached by the proxy so outside MCP clients don't need it. Unset: the # caller's own Authorization header is passed through. diff --git a/deploy/README.md b/deploy/README.md index 3e7aca0..5d7d509 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -254,6 +254,7 @@ The app defines the definitive contract once it exists. Known so far: | `RATE_LIMIT_KEYED` | Calls per window per account, on each of `/api` and `/mcp`, for a call with a valid API key whose account has no limit of its own (`user.api_rate_limit`); default 600 | | `API_KEYS_ENABLED` | Emergency switch for API keys; default on. `false`, `0`, `off` or `no` strips keys and counts every call by address, without a code change | | `API_KEYS_MAX_PER_ACCOUNT` | How many API keys one account may hold on `/account/api-keys`; default 5. Housekeeping, not security, since limits are per account | +| `ADMIN_EMAILS` | Comma-separated emails, matched case-insensitively against a signed-in user with a verified email, who may open `/admin/api-keys` (every account's keys, create, delete, set a limit; a proof of concept). Everyone else gets a 404; unset or empty means no admins | | `OPENAI_APPS_CHALLENGE` | OpenAI's domain-verification token; `/.well-known/openai-apps-challenge` serves it as plain text, 404 while unset | | `TRUSTED_PROXY_HOPS` | Which `X-Forwarded-For` entry is the client, counted from the right; keys the `/api` and `/mcp` limits, the guest Studio allowance and the caller digest; default 0 (Cloud Run's); +1 per load balancer | | `WEBSITE_DB_INSTANCE_CONNECTION_NAME` | Cloud SQL instance the connector dials over PSC; set by infra | diff --git a/src/app/(site)/admin/api-keys/actions.ts b/src/app/(site)/admin/api-keys/actions.ts new file mode 100644 index 0000000..ebbd59f --- /dev/null +++ b/src/app/(site)/admin/api-keys/actions.ts @@ -0,0 +1,83 @@ +'use server'; + +import { revalidatePath } from 'next/cache'; +import { redirect } from 'next/navigation'; + +import { keyService, requireAdmin } from '@/lib/apiKeys/server'; +import { parseEmailInput, parseLimitInput } from '@/lib/apiKeys/settings'; + +import type { CreatedState, DeleteState } from '@/components/organisms/ApiKeys/state'; + +/* + * Admin actions (proof of concept). A server action is a POST anyone can + * send, so each one runs the admin gate first (requireAdmin: everyone not + * on ADMIN_EMAILS gets the 404 page) and the page's own check is no + * substitute. Next.js refuses one whose Origin is not the page's host, which + * is the CSRF check. Each mutation logs one structured line through the + * service: the actor's email, the action, the key id and the account id, + * never a key. + */ + +const PATH = '/admin/api-keys'; + +const REFUSALS = { + label_invalid: 'Give the key a label of 1 to 32 characters.', + cap_reached: 'That account holds as many keys as it may.', + no_such_account: 'No account has that email.', +} as const; + +/** Creates a key for the account with the given email and answers with it, once. */ +export const adminCreateKey = async ( + _previous: CreatedState, + formData: FormData, +): Promise => { + const admin = await requireAdmin(); + const email = parseEmailInput(formData.get('email')); + + if (!email) { + return { error: 'Enter the account’s email address.' }; + } + + const result = await keyService.adminCreate(admin.email, email, formData.get('label')); + + if (!result.ok) { + return { error: REFUSALS[result.reason] }; + } + + revalidatePath(PATH); + + return { created: { id: result.id, key: result.key } }; +}; + +/** Deletes any key. */ +export const adminDeleteKey = async ( + _previous: DeleteState, + formData: FormData, +): Promise => { + const admin = await requireAdmin(); + const keyId = formData.get('keyId'); + + if (typeof keyId !== 'string' || !(await keyService.adminDelete(admin.email, keyId))) { + return { error: 'That key was not found.' }; + } + + revalidatePath(PATH); + + return { error: null }; +}; + +/** Sets or clears an account's limit, then returns to the page with what happened in `?limit=`. */ +export const adminSetLimit = async (formData: FormData): Promise => { + const admin = await requireAdmin(); + const email = parseEmailInput(formData.get('email')); + const limit = parseLimitInput(formData.get('limit')); + + if (!email || !limit.ok) { + redirect(`${PATH}?limit=invalid`); + } + + const done = await keyService.adminSetLimit(admin.email, email, limit.limit); + + revalidatePath(PATH); + redirect(`${PATH}?limit=${done ? (limit.limit === null ? 'cleared' : 'saved') : 'no-account'}`); +}; diff --git a/src/app/(site)/admin/api-keys/page.tsx b/src/app/(site)/admin/api-keys/page.tsx new file mode 100644 index 0000000..8310f6b --- /dev/null +++ b/src/app/(site)/admin/api-keys/page.tsx @@ -0,0 +1,54 @@ +import type { Metadata } from 'next'; + +import { adminCreateKey, adminDeleteKey, adminSetLimit } from './actions'; + +import AdminApiKeys from '@/components/organisms/ApiKeys/AdminApiKeys'; +import { keyService, requireAdmin } from '@/lib/apiKeys/server'; +import { keysEnabled } from '@/lib/proxy/forward'; +import { KEYED_LIMIT } from '@/lib/proxy/rateLimit'; + +export const metadata: Metadata = { + title: 'API keys: admin — DFO', + robots: { index: false, follow: false }, +}; + +const NOTICES: Record = { + saved: 'The limit was saved.', + cleared: 'The limit was cleared. The account is on the default.', + 'no-account': 'No account has that email, so nothing changed.', + invalid: 'Enter an account email and a positive whole number, or leave the limit empty.', +}; + +const one = (value: string | string[] | undefined): string => + (Array.isArray(value) ? value[0] : value) ?? ''; + +/** + * Admin proof of concept: every API key across accounts. Admins are the + * signed-in users whose verified email is in ADMIN_EMAILS; anyone else gets + * the 404 page (requireAdmin). The actions check the gate again. + */ +const AdminApiKeysPage = async ({ + searchParams, +}: { + searchParams: Promise>; +}) => { + await requireAdmin(); + + const query = await searchParams; + const filter = one(query.email).trim().slice(0, 320); + + return ( + + ); +}; + +export default AdminApiKeysPage; diff --git a/src/components/organisms/ApiKeys/AdminApiKeys.tsx b/src/components/organisms/ApiKeys/AdminApiKeys.tsx new file mode 100644 index 0000000..c105ea2 --- /dev/null +++ b/src/components/organisms/ApiKeys/AdminApiKeys.tsx @@ -0,0 +1,161 @@ +import styles from './ApiKeys.module.scss'; +import ApiKeysShell from './ApiKeysShell'; +import CreateKeyForm from './CreateKeyForm'; +import DeleteKeyButton from './DeleteKeyButton'; +import { formatDate } from './format'; +import type { CreatedState, DeleteState } from './state'; + +import type { AdminKey } from '@/lib/apiKeys/service'; + +type AdminApiKeysProps = { + keys: AdminKey[]; + // The email filter as typed, to fill the box again. + filter: string; + defaultLimit: number; + keysEnabled: boolean; + // The notice a limit change left, from the page's query (?limit=...). + notice?: string; + createAction: (previous: CreatedState, formData: FormData) => Promise; + deleteAction: (previous: DeleteState, formData: FormData) => Promise; + limitAction: (formData: FormData) => Promise; +}; + +/** + * The operators' view of every key (/admin/api-keys). A proof of concept: + * plain on purpose, and the admin gate (lib/apiKeys/server `requireAdmin`) + * is what keeps it private. + */ +const AdminApiKeys = ({ + keys, + filter, + defaultLimit, + keysEnabled, + notice, + createAction, + deleteAction, + limitAction, +}: AdminApiKeysProps) => ( + +

+ API_KEYS_ENABLED is {keysEnabled ? 'on' : 'off'} + {keysEnabled + ? ': keys are honoured.' + : ': keys are stripped and every call is counted by address.'}{' '} + It is set in the deployment, not here. +

+ {notice && ( +

+ {notice} +

+ )} + +

Keys

+
+ + +
+ {keys.length === 0 ? ( +

{filter ? 'No keys match.' : 'No keys yet.'}

+ ) : ( +
+ + + + + + + + + + + + + + {keys.map((key) => ( + + + + + + + + + + + ))} + +
Key idLabelStartOwnerCreatedLast requestAccount limit +
+ {key.id} + {key.name || 'Unnamed'} + {key.start ? `${key.start}…` : '—'} + {key.ownerEmail}{formatDate(key.createdAt)} + {key.lastRequest ? formatDate(key.lastRequest) : 'Not recorded'} + + {key.accountLimit === null + ? `default (${defaultLimit.toLocaleString('en-GB')})` + : key.accountLimit.toLocaleString('en-GB')} + + +
+
+ )} + +

Create a key for an account

+ + +

Set an account's limit

+
+ + + +
+

+ A positive whole number, or empty to go back to the default. A change reaches the proxy + within about a minute. +

+
+); + +export default AdminApiKeys; From b0fa967ad73ac6cdd52a9c9676ddb03f4f0ecf46 Mon Sep 17 00:00:00 2001 From: Sef Kloninger Date: Mon, 16 Nov 2026 12:29:34 -0800 Subject: [PATCH 23/34] fix(auth): keep the prefix and three random characters as a key's start (#142) The plugin stores the first 6 characters of a key as its start, which is only 'dfo_li', so every key looked the same on the key pages. Keep 12: the prefix and three of the 32 random characters, such as dfo_live_RCd. Existing rows keep their old start. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf --- src/lib/apiKeys/test/service.test.ts | 13 ++++++++++--- src/lib/auth/apiKeyOptions.ts | 9 +++++++++ 2 files changed, 19 insertions(+), 3 deletions(-) diff --git a/src/lib/apiKeys/test/service.test.ts b/src/lib/apiKeys/test/service.test.ts index e0097ab..1b5e3e7 100644 --- a/src/lib/apiKeys/test/service.test.ts +++ b/src/lib/apiKeys/test/service.test.ts @@ -10,7 +10,12 @@ import { drizzle } from 'drizzle-orm/node-postgres'; import { applyMigrations } from '../../../../db/apply-migrations.ts'; import * as schema from '../../../../db/schema.ts'; import { createTestDatabase } from '../../../../db/test/harness.ts'; -import { API_KEY_PATHS, API_KEY_PREFIX, apiKeyPlugin } from '../../auth/apiKeyOptions.ts'; +import { + API_KEY_PATHS, + API_KEY_PREFIX, + API_KEY_START_LENGTH, + apiKeyPlugin, +} from '../../auth/apiKeyOptions.ts'; import { createKeyVerifier } from '../../proxy/keyVerifier.ts'; import { createKeyService } from '../service.ts'; @@ -126,8 +131,10 @@ test('API key service', async (t) => { assert.equal(everything.includes(made.key), false); assert.equal(everything.includes(row.key), false); - // The start is the first characters only. - assert.ok(listed[0]!.start && listed[0]!.start.length < made.key.length); + // The start is the prefix and three random characters, nothing more. + assert.equal(listed[0]!.start, made.key.slice(0, API_KEY_START_LENGTH)); + assert.equal(listed[0]!.start?.length, 12); + assert.match(listed[0]!.start ?? '', /^dfo_live_[A-Za-z0-9]{3}$/); await service.deleteOwn(bob, made.id); }); diff --git a/src/lib/auth/apiKeyOptions.ts b/src/lib/auth/apiKeyOptions.ts index d3df47d..e4856d4 100644 --- a/src/lib/auth/apiKeyOptions.ts +++ b/src/lib/auth/apiKeyOptions.ts @@ -19,6 +19,14 @@ export const API_KEY_PATHS: readonly string[] = [ '/api-key/get', ]; +/** + * How much of a key is stored in the clear as the row's `start`, which the + * key pages show so an owner can tell keys apart: the prefix and three + * random characters (`dfo_live_RCd`). Three of 32 random characters give + * nothing to guess with. + */ +export const API_KEY_START_LENGTH = API_KEY_PREFIX.length + 3; + /** * The `@better-auth/api-key` plugin, set up so the proxy owns the request * path (src/lib/proxy/keyVerifier): the plugin's own limiter, metadata and @@ -32,5 +40,6 @@ export const apiKeyPlugin = (overrides: Parameters[0] = {}) => rateLimit: { enabled: false }, enableSessionForAPIKeys: false, enableMetadata: false, + startingCharactersConfig: { shouldStore: true, charactersLength: API_KEY_START_LENGTH }, ...overrides, }); From 2fc9f891389175f0ff641fd30298d1bfb1186e30 Mon Sep 17 00:00:00 2001 From: Sef Kloninger Date: Mon, 16 Nov 2026 12:29:34 -0800 Subject: [PATCH 24/34] fix(account): use a keyed /api/v1 path in the API key curl example (#142) The example called /api/search/catalogue, the site's own endpoint, which does not honour keys. GET /api/v1/graph/capabilities is on a keyed surface and cheap, and the docs already use it. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf --- src/components/organisms/ApiKeys/AccountApiKeys.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/components/organisms/ApiKeys/AccountApiKeys.tsx b/src/components/organisms/ApiKeys/AccountApiKeys.tsx index 5b4f894..28ffe4a 100644 --- a/src/components/organisms/ApiKeys/AccountApiKeys.tsx +++ b/src/components/organisms/ApiKeys/AccountApiKeys.tsx @@ -113,7 +113,7 @@ const AccountApiKeys = ({

For example:

-            {`curl -H "Authorization: Bearer $DFO_API_KEY" \\\n  https://developmentfinance.org/api/search/catalogue`}
+            {`curl -fsS -H "Authorization: Bearer $DFO_API_KEY" \\\n  https://developmentfinance.org/api/v1/graph/capabilities`}
         

Keep a key secret, like a password. If one leaks, delete it here and make another. Never From c13d579fcb0f736dbc28feaaeb8338f30a9adf94 Mon Sep 17 00:00:00 2001 From: Sef Kloninger Date: Mon, 16 Nov 2026 12:31:48 -0800 Subject: [PATCH 25/34] feat(proxy): record a key's last use when a lookup finds it (#142) A lookup that finds a valid key sets apikey.last_request, in the background on the key pool. It runs on a cache miss only, so about once per cache lifetime per key per instance, never on a cache hit and never for an invalid or unavailable answer. The write is fire and forget: the verdict does not wait for it, and a failure is logged at most, with no key or hash in the line. The runtime role already holds UPDATE on the table through the default privileges, and a test now says so. The key pages show the value as an approximate 'last used', up to a minute or so behind the last call. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf --- db/test/api-key.test.ts | 11 ++ .../organisms/ApiKeys/AccountApiKeys.tsx | 7 +- .../organisms/ApiKeys/AdminApiKeys.tsx | 8 +- src/lib/apiKeys/service.ts | 5 +- src/lib/proxy/keyVerifier.ts | 27 +++- src/lib/proxy/test/keyVerifier.test.ts | 132 +++++++++++++++++- 6 files changed, 174 insertions(+), 16 deletions(-) diff --git a/db/test/api-key.test.ts b/db/test/api-key.test.ts index 2314447..fbe38fb 100644 --- a/db/test/api-key.test.ts +++ b/db/test/api-key.test.ts @@ -69,6 +69,17 @@ test('API key table and plugin setup', async (t) => { await pool.query('select api_rate_limit from "user" limit 1'); }); + await t.test("the runtime role can record a key's last use", async () => { + const created = await auth.api.createApiKey({ body: { userId: alice.user.id } }); + const updated = await pool.query( + 'update apikey set last_request = now() where id = $1 returning last_request', + [created.id], + ); + + assert.equal(updated.rowCount, 1); + assert.ok(updated.rows[0].last_request); + }); + await t.test( 'a key is stored as its SHA-256, base64url, with the dfo_live_ prefix', async () => { diff --git a/src/components/organisms/ApiKeys/AccountApiKeys.tsx b/src/components/organisms/ApiKeys/AccountApiKeys.tsx index 28ffe4a..abc8809 100644 --- a/src/components/organisms/ApiKeys/AccountApiKeys.tsx +++ b/src/components/organisms/ApiKeys/AccountApiKeys.tsx @@ -64,9 +64,7 @@ const AccountApiKeys = ({ {key.start ? `${key.start}…` : '—'} {formatDate(key.createdAt)} - - {key.lastRequest ? formatDate(key.lastRequest) : 'Not recorded'} - + {key.lastRequest ? formatDate(key.lastRequest) : 'Not yet'} )}

- A deleted key stops working within about a minute. You can hold {max} keys. + A deleted key stops working within about a minute. “Last used” is approximate, up to a + minute or so behind. You can hold {max} keys.

Create a key

diff --git a/src/components/organisms/ApiKeys/AdminApiKeys.tsx b/src/components/organisms/ApiKeys/AdminApiKeys.tsx index c105ea2..5155714 100644 --- a/src/components/organisms/ApiKeys/AdminApiKeys.tsx +++ b/src/components/organisms/ApiKeys/AdminApiKeys.tsx @@ -47,6 +47,10 @@ const AdminApiKeys = ({ : ': keys are stripped and every call is counted by address.'}{' '} It is set in the deployment, not here.

+

+ Last request is approximate: it is written when the proxy looks a key up, so it can be a + minute or so behind the last call. +

{notice && (

{notice} @@ -98,9 +102,7 @@ const AdminApiKeys = ({ {key.ownerEmail} {formatDate(key.createdAt)} - - {key.lastRequest ? formatDate(key.lastRequest) : 'Not recorded'} - + {key.lastRequest ? formatDate(key.lastRequest) : 'Not yet'} {key.accountLimit === null ? `default (${defaultLimit.toLocaleString('en-GB')})` diff --git a/src/lib/apiKeys/service.ts b/src/lib/apiKeys/service.ts index a211be8..abc1468 100644 --- a/src/lib/apiKeys/service.ts +++ b/src/lib/apiKeys/service.ts @@ -57,8 +57,9 @@ export type OwnKey = { name: string | null; start: string | null; createdAt: Date; - // The plugin writes this when it verifies a key. The proxy verifies keys - // itself and does not, so it is empty until the usage log feeds it. + // When the proxy last looked the key up (keyVerifier records it on a + // cache miss), so up to about a minute behind the last call. Null until + // the key is first used. lastRequest: Date | null; }; diff --git a/src/lib/proxy/keyVerifier.ts b/src/lib/proxy/keyVerifier.ts index 38424bd..d1d1296 100644 --- a/src/lib/proxy/keyVerifier.ts +++ b/src/lib/proxy/keyVerifier.ts @@ -29,6 +29,16 @@ import { hasKeyPrefix } from './apiKey.ts'; * invalid entry lives CACHE_INVALID_MS. An unavailable answer is not cached. * Neither the key nor its hash leaves this module except as the cache key * (hash only, in memory). + * + * A lookup that finds a valid key also records its use: `apikey.last_request` + * is set to the time of the lookup, which the key pages show as "last used". + * It is written only on a cache miss, so at most about once per cache + * lifetime per key per instance, and not on every call, which would put a + * write on the request path. The write is fire and forget on the same pool: + * the verdict does not wait for it, and a failed or slow write is logged at + * most (the key's public id is not in the line) and changes nothing. An + * invalid or unavailable answer writes nothing. The shown time is therefore + * approximate, up to a cache lifetime behind the last call. */ export type KeyVerdict = | { @@ -50,7 +60,7 @@ export const CACHE_INVALID_MS = 30_000; const CACHE_MAX_ENTRIES = 5_000; /** Reads only; the pool behind it is src/lib/db's keyDb. */ -export type KeyDb = Pick; +export type KeyDb = Pick; type Row = { id: string; @@ -142,6 +152,20 @@ export const createKeyVerifier = ( // One read per hash at a time: callers arriving during it share it. const reading = new Map>(); + // Records the key's use. Never throws, and nothing waits on it. + const touch = (keyId: string): void => { + void (async () => { + try { + await db + .update(apikey) + .set({ lastRequest: new Date(now()) }) + .where(eq(apikey.id, keyId)); + } catch (error) { + log('api key last use not recorded', error); + } + })(); + }; + const read = async (hash: string): Promise => { let rows: Row[]; @@ -182,6 +206,7 @@ export const createKeyVerifier = ( }; valid.set(hash, verdict, Math.min(at + validMs, row.expiresAt?.getTime() ?? Infinity)); + touch(row.id); return verdict; }; diff --git a/src/lib/proxy/test/keyVerifier.test.ts b/src/lib/proxy/test/keyVerifier.test.ts index 56f6e21..e080694 100644 --- a/src/lib/proxy/test/keyVerifier.test.ts +++ b/src/lib/proxy/test/keyVerifier.test.ts @@ -121,27 +121,141 @@ test('keyVerifier on the key store', async (t) => { } }); - await t.test('a lookup writes nothing to the key store', async () => { + const lastRequestOf = async (id: string) => + (await admin.query('select last_request from apikey where id = $1', [id])).rows[0] + ?.last_request as Date | null | undefined; + + // The write is fire and forget, so a test waits for it to land. + const eventually = async (read: () => Promise): Promise => { + for (let i = 0; i < 100; i++) { + const value = await read(); + + if (value) { + return value; + } + + await new Promise((resolve) => setTimeout(resolve, 20)); + } + + throw new Error('the write never landed'); + }; + + await t.test('a valid lookup records last_request and changes nothing else', async () => { const before = await admin.query( - `select id, request_count, last_request, updated_at, remaining from apikey order by id`, + `select id, request_count, updated_at, remaining, enabled, expires_at from apikey where id <> 'id-fresh' order by id`, ); - const verifier = createKeyVerifier(db); + const fresh = await addKey('fresh', 'acct-default'); + + assert.equal(await lastRequestOf('id-fresh'), null); + + const clock = Date.now(); + const verifier = createKeyVerifier(db, { now: () => clock }); - await verifier.verify(live); + assert.equal((await verifier.verify(fresh)).kind, 'valid'); await verifier.verify(expired); + await verifier.verify(disabled); + await verifier.verify(keyOf('nobody')); + + const written = await eventually(() => lastRequestOf('id-fresh')); + + // The column has no time zone, which Drizzle writes and the driver reads as UTC. + assert.ok(Math.abs(written.getTime() - clock) < 24 * 3_600_000); const after = await admin.query( - `select id, request_count, last_request, updated_at, remaining from apikey order by id`, + `select id, request_count, updated_at, remaining, enabled, expires_at from apikey where id <> 'id-fresh' order by id`, ); assert.deepEqual(after.rows, before.rows); + // Only the valid key was touched: not the expired, the disabled or the unknown. + assert.equal(await lastRequestOf('id-expired'), null); + assert.equal(await lastRequestOf('id-disabled'), null); assert.equal( (await admin.query('select 1 from apikey where id = $1', ['id-expired'])).rowCount, 1, ); }); + await t.test('a cache hit does not write, a later miss does', async () => { + let clock = 1_000_000; + let updates = 0; + const counting = { + select: db.select.bind(db), + update: (...args: Parameters) => { + updates += 1; + + return db.update(...args); + }, + } as unknown as typeof db; + const verifier = createKeyVerifier(counting, { now: () => clock }); + + assert.equal((await verifier.verify(own)).kind, 'valid'); + assert.equal(updates, 1); + + for (let i = 0; i < 5; i++) { + assert.equal((await verifier.verify(own)).kind, 'valid'); + assert.equal((await verifier.cachedValid(own))?.kind, 'valid'); + } + + assert.equal(updates, 1); + + clock += CACHE_VALID_MS; + assert.equal((await verifier.verify(own)).kind, 'valid'); + assert.equal(updates, 2); + + // Not for answers that are not valid. + await verifier.verify(keyOf('nobody')); + await verifier.verify(disabled); + assert.equal(updates, 2); + await eventually(() => lastRequestOf('id-own')); + }); + + await t.test('a failed write is logged without the key and changes no verdict', async () => { + const logged: string[] = []; + const rejecting = { + select: db.select.bind(db), + update: () => ({ + set: () => ({ + where: () => Promise.reject(new Error('write refused')), + }), + }), + } as unknown as typeof db; + const throwing = { + select: db.select.bind(db), + update: () => { + throw new Error('no update here'); + }, + } as unknown as typeof db; + + for (const store of [rejecting, throwing]) { + const verifier = createKeyVerifier(store, { log: (message) => logged.push(message) }); + + assert.equal((await verifier.verify(own)).kind, 'valid'); + // Cached, with no second read and no second write. + assert.equal((await verifier.cachedValid(own))?.kind, 'valid'); + } + + await eventually(async () => (logged.length === 2 ? true : null)); + assert.ok(logged.every((line) => line === 'api key last use not recorded')); + assert.doesNotMatch(logged.join(), /dfo_/); + }); + + await t.test('a write that is slow does not hold the verdict', async () => { + const slow = { + select: db.select.bind(db), + update: () => ({ + set: () => ({ + where: () => new Promise(() => {}), + }), + }), + } as unknown as typeof db; + const verifier = createKeyVerifier(slow); + const started = Date.now(); + + assert.equal((await verifier.verify(own)).kind, 'valid'); + assert.ok(Date.now() - started < 1_000); + }); + await t.test('a valid answer is cached for an absolute minute, never extended', async () => { let clock = 1_000_000; const reads: string[] = []; @@ -149,7 +263,12 @@ test('keyVerifier on the key store', async (t) => { const sql = pool.query.bind(pool) as (...args: unknown[]) => unknown; (pool as unknown as { query: unknown }).query = (...args: unknown[]) => { - reads.push(String((args[0] as { text?: string }).text ?? args[0])); + const text = String((args[0] as { text?: string }).text ?? args[0]); + + // The key's use is recorded in the background, which is not a read. + if (text.startsWith('select')) { + reads.push(text); + } return sql(...args); }; @@ -289,6 +408,7 @@ test('keyVerifier on the key store', async (t) => { down: false, select: (...args: Parameters) => flaky.down ? (undefined as never) : db.select(...args), + update: (...args: Parameters) => db.update(...args), }; const verifier = createKeyVerifier(flaky as unknown as typeof db, { now: () => clock, From 42a4a2f42313343d6b1f4d8601fd8ab9b97b780f Mon Sep 17 00:00:00 2001 From: Sef Kloninger Date: Mon, 16 Nov 2026 13:34:12 -0800 Subject: [PATCH 26/34] chore(just): run the apis proxy, harness and dev server together `just stack` starts the dev apis proxy and the Studio harness from an ai checkout beside this one (AI_DIR, default ../ai) and the dev server, with each output line prefixed by its service and Ctrl-C stopping all three. Plain bash in the recipe, so it needs no process manager. It warns up front when gcloud has no valid login, since the proxy cannot prompt for one there. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf --- docs/development.md | 21 ++++++++++++++++++++- justfile | 30 ++++++++++++++++++++++++++++++ 2 files changed, 50 insertions(+), 1 deletion(-) diff --git a/docs/development.md b/docs/development.md index 2e1d70a..80e0765 100644 --- a/docs/development.md +++ b/docs/development.md @@ -57,6 +57,25 @@ not document whether the proxy renews its token after an hour, so if calls start answering 401 or 403 later in a session, restart it. The scripts below reach the APIs the same way. +### Run the whole stack + +`just stack` runs the dev apis proxy (8083) and the Studio harness (8080) +from an `ai` checkout beside this one, plus the dev server, in one terminal. +Each output line starts with its service's name (`apis`, `ai`, `web`), and +Ctrl-C stops all three: + +```bash +gcloud auth login # the proxy cannot prompt for it under `stack` +just stack +``` + +It looks for the `ai` checkout at `../ai`; pass `AI_DIR=` for another +one. The harness needs `ai`'s own setup first (`just setup` and `just env` +there), and its environment synced after pulling (`uv sync --all-packages` +in `ai`). A service that exits on its own, such as the proxy after its login +expires, leaves the other two running. Postgres runs outside `stack` (see +[Database](#database)). + ## just The [justfile](../justfile) is the entry point for the commands below. It @@ -67,7 +86,7 @@ workflows. `just` with no arguments lists everything. Install it with | Section | Recipes | | --------------------- | ------------------------------------------------------- | | Setup & Configuration | `setup`, `env` | -| Development | `dev`, `start`, `optimize-svg` | +| Development | `dev`, `stack`, `start`, `optimize-svg` | | Database | `db-up`, `db-migrate`, `db-reset`, `db-generate` | | Quality | `lint`, `format`, `typecheck`, `test`, `build`, `check` | | Container | `docker-build`, `run-local`, `clean` | diff --git a/justfile b/justfile index 6976778..8df56ed 100644 --- a/justfile +++ b/justfile @@ -17,6 +17,7 @@ REGION := "northamerica-northeast1" AR_REPO := "dfo-website-staging" SERVICE := env_var_or_default("SERVICE", "dfo-dev-website-staging") LOG_LIMIT := "50" # log lines `logs` reads +AI_DIR := "../ai" # the ai checkout `stack` runs the harness and apis proxy from GCP_ADC := env_var("HOME") / ".config/gcloud/application_default_credentials.json" # Show available commands (default) @@ -67,6 +68,35 @@ dev: @echo "http://localhost:{{PORT}}" pnpm dev --port {{PORT}} +# The site's whole local stack in one terminal: the dev apis proxy (8083) +# and the Studio harness (8080) from an `ai` checkout beside this one, plus +# this dev server. Each line is prefixed with its service. Ctrl-C stops all +# three; one that exits on its own (an expired gcloud login stops the proxy) +# leaves the others running. Postgres runs outside this, as `db-up` or a +# Postgres you already run. AI_DIR points at another `ai` checkout. +# +# Run the apis proxy, the ai harness and the dev server together +stack: + #!/usr/bin/env bash + set -uo pipefail + if [ ! -f "{{AI_DIR}}/justfile" ]; then + echo "No ai checkout at {{AI_DIR}}. Clone it there or pass AI_DIR=." >&2 + exit 1 + fi + if ! gcloud auth print-access-token >/dev/null 2>&1; then + echo "warning: gcloud has no valid login, so the apis proxy will exit. Run 'gcloud auth login'." >&2 + fi + # Prefix each output line with the service name, flushed line by line. + run() { + local name="$1"; shift + "$@" 2>&1 | awk -v p="$(printf '%-5s| ' "$name")" '{ print p $0; fflush() }' & + } + trap 'trap - INT TERM EXIT; kill 0 2>/dev/null' INT TERM EXIT + run apis just --justfile "{{AI_DIR}}/justfile" --working-directory "{{AI_DIR}}" apis-proxy + run ai just --justfile "{{AI_DIR}}/justfile" --working-directory "{{AI_DIR}}" dev + run web just dev + wait + # Needs 'just build' first -- this serves the production build, it doesn't # create one. Next warns that `next start` does not work with # `output: 'standalone'` (which next.config.ts sets); it serves locally From 3d7acb65d79e0ab0361d13ac9b5f72156dbe87ef Mon Sep 17 00:00:00 2001 From: Sef Kloninger Date: Mon, 16 Nov 2026 13:38:15 -0800 Subject: [PATCH 27/34] chore(just): color stack output by service and highlight errors MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit On a terminal, each service's prefix in `just stack` gets its own color and lines that look like errors (ERROR, Traceback, *Error, *Exception, `error:`, Next's ⨯) are shown in red. NO_COLOR or a non-terminal output keeps the plain prefixes. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf --- docs/development.md | 5 +++-- justfile | 24 +++++++++++++++++++----- 2 files changed, 22 insertions(+), 7 deletions(-) diff --git a/docs/development.md b/docs/development.md index 80e0765..735bd30 100644 --- a/docs/development.md +++ b/docs/development.md @@ -61,8 +61,9 @@ The scripts below reach the APIs the same way. `just stack` runs the dev apis proxy (8083) and the Studio harness (8080) from an `ai` checkout beside this one, plus the dev server, in one terminal. -Each output line starts with its service's name (`apis`, `ai`, `web`), and -Ctrl-C stops all three: +Each output line starts with its service's name (`apis`, `ai`, `web`), in +its own color on a terminal, with lines that look like errors in red +(`NO_COLOR=1` turns color off). Ctrl-C stops all three: ```bash gcloud auth login # the proxy cannot prompt for it under `stack` diff --git a/justfile b/justfile index 8df56ed..1ec1ff5 100644 --- a/justfile +++ b/justfile @@ -87,14 +87,28 @@ stack: echo "warning: gcloud has no valid login, so the apis proxy will exit. Run 'gcloud auth login'." >&2 fi # Prefix each output line with the service name, flushed line by line. + # On a terminal (and without NO_COLOR) each service's prefix has its own + # color, and a line that looks like an error is shown in red. + color=0 + if [ -t 1 ] && [ -z "${NO_COLOR:-}" ]; then color=1; fi run() { - local name="$1"; shift - "$@" 2>&1 | awk -v p="$(printf '%-5s| ' "$name")" '{ print p $0; fflush() }' & + local name="$1" hue="$2"; shift 2 + "$@" 2>&1 | awk -v name="$(printf '%-5s' "$name")" -v hue="$hue" -v color="$color" ' + BEGIN { + esc = sprintf("%c", 27) + prefix = color ? esc "[" hue "m" name " |" esc "[0m " : name " | " + red = color ? esc "[31m" : "" + reset = color ? esc "[0m" : "" + } + /(^|[^[:alnum:]_])(ERROR|FATAL|CRITICAL|Traceback|[A-Za-z]*(Error|Exception))([^[:alnum:]_]|$)|^error[:[]|⨯/ { + print prefix red $0 reset; fflush(); next + } + { print prefix $0; fflush() }' & } trap 'trap - INT TERM EXIT; kill 0 2>/dev/null' INT TERM EXIT - run apis just --justfile "{{AI_DIR}}/justfile" --working-directory "{{AI_DIR}}" apis-proxy - run ai just --justfile "{{AI_DIR}}/justfile" --working-directory "{{AI_DIR}}" dev - run web just dev + run apis 36 just --justfile "{{AI_DIR}}/justfile" --working-directory "{{AI_DIR}}" apis-proxy + run ai 35 just --justfile "{{AI_DIR}}/justfile" --working-directory "{{AI_DIR}}" dev + run web 32 just dev wait # Needs 'just build' first -- this serves the production build, it doesn't From 48941ffd7c92330a2712563b0ad158361bc5f79a Mon Sep 17 00:00:00 2001 From: Sef Kloninger Date: Mon, 16 Nov 2026 15:13:46 -0800 Subject: [PATCH 28/34] docs(design): record local test results for API keys A Testing section with the local run against the implementation: question and answer through MCP with a key, usage counted against the account, the limit enforced on the API and MCP with the 429 it returns, and what remains to test on dev (backends seeing the account caller, Cloudflare, a live store outage). Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf --- docs/design/api-keys.md | 42 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/docs/design/api-keys.md b/docs/design/api-keys.md index 050b61f..48083ae 100644 --- a/docs/design/api-keys.md +++ b/docs/design/api-keys.md @@ -29,6 +29,8 @@ Last Update: Nov 16, 2026 - [Phase 1: Validate][] - [Phase 2: Provision][] - [Phase 3: Enforce][] +- [Testing][] + - [Local Test Results][] - [Work by Repository][] - [Alternatives Considered][] - [Future Features][] @@ -384,6 +386,44 @@ Three phases take keys from an optional test feature to the normal way heavy use Phase 1 should avoid choices that Phase 2 has to undo. Every key has an owning account from the start, and the limit is stored per account in a form a tier can replace. +## Testing + +### Local Test Results + +Run on Nov 16, 2026 against the local stack: the website on the implementation branch, the ai harness, and the dev apis proxy. Sign-in used an emailed code caught by a local mail catcher, and the key was created on the account's API keys page. The key went in as `Authorization: Bearer dfo_live_…`. + +| Test | How | Result | +| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Question and answer through MCP | The pi coding agent, with a small local model, connected to the site's `/mcp` with the key as its bearer and was asked how much money Kenya received in 2025 | Answered from OECD DAC2A, citing the dataset and the partial 2025 data. The figures came from the tools. The small model's totals were unreliable: it mixed official and private donors | +| MCP session with a key | A scripted session: `initialize`, then `tools/list` | 16 tools. `X-RateLimit-Limit: 600`, the keyed default, where an anonymous MCP caller gets 300 | +| Usage counted against the account | The limiter's rows after keyed calls | Counted as `mcp:acct:` and `api:acct:`, not by address. The key's last use advanced as calls were made | +| Anonymous traffic unaffected | An anonymous call during the keyed burst below | 200, counted against its address at the anonymous limit (120) | +| Limit enforced on the API | Account limit set to 5; seven keyed `GET /openapi.json` calls at the start of a window | Calls 1 to 5 answered 200, with remaining counting down from 4 to 0. Calls 6 and 7 answered 429 with `Retry-After: 58` | +| Limit enforced on MCP | Two MCP sessions under the limit of 5 | The first used 3 calls. The second was refused at `initialize` with 429, because the account's calls are shared across sessions | +| An MCP client under a low limit | Account limit set to 2; pi asked the same question | pi finished, in about 4 minutes against 2 at the default limit | +| Limit changes take effect | The limit set to 5, then 2, then cleared | Each change reached the proxy within 8 seconds, inside the cache lifetime of about a minute | + +A refused call is answered with a problem document, the `Retry-After` header and the `X-RateLimit-*` headers: + +``` +HTTP/1.1 429 Too Many Requests +content-type: application/problem+json +retry-after: 36 +x-ratelimit-limit: 5 +x-ratelimit-remaining: 0 +x-ratelimit-reset: 36 + +{"type":"/codes/rate_limited","title":"Too Many Requests","status":429, + "detail":"Too many requests: 5 per window per account. Try again in 36s.", + "code":"rate_limited","retryable":true,"trace_id":"…"} +``` + +Observations: + +- **Refused calls count.** A refused call still adds to the window's count, because the limiter counts every attempt. Usage read from the counters therefore includes refusals. Usage reports should come from the usage log line, which records the outcome of each call. +- **Backends not exercised.** The local stack sends no caller to the backends, because the caller key and the shared secret are unset there. dfo-apis and dfo-ai seeing the account as a `user:` caller has to be tested on dev, after their changes are deployed. +- **Not tested locally.** Cloudflare's edge rules, and a store outage on a live stack, are covered only by unit tests so far. + ## Work by Repository Most of the work is in the website. This split holds for both options: Use and Build differ only in the website row, in where keys are stored and how they are looked up. The other rows are the same either way, since those systems see only the caller name and the key header. Codex's review corrected the dfo-ai row, which first read "little or none". The Phase 1 pieces: @@ -462,6 +502,8 @@ None of these block Phase 1. [Phase 1: Validate]: #phase-1-validate [Phase 2: Provision]: #phase-2-provision [Phase 3: Enforce]: #phase-3-enforce +[Testing]: #testing +[Local Test Results]: #local-test-results [Work by Repository]: #work-by-repository [Alternatives Considered]: #alternatives-considered [Future Features]: #future-features From 6a4ea4b6f1d0eaf79076a4d11786833977fdb090 Mon Sep 17 00:00:00 2001 From: Sef Kloninger Date: Mon, 16 Nov 2026 15:19:46 -0800 Subject: [PATCH 29/34] docs(design): bring the API keys design up to date with the build Phase 1 operators use the /admin/api-keys page, not an admin command, and self-service at /account/api-keys was built alongside it. The backends see a keyed call as `user:`, which settles the caller form; the open question narrows to whether site sessions should be named by account too. The infra Cloud Run Job becomes optional. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf --- docs/design/api-keys.md | 36 ++++++++++++++++++++---------------- 1 file changed, 20 insertions(+), 16 deletions(-) diff --git a/docs/design/api-keys.md b/docs/design/api-keys.md index 48083ae..d94590a 100644 --- a/docs/design/api-keys.md +++ b/docs/design/api-keys.md @@ -216,7 +216,7 @@ On every surface, a `dfo_` bearer is consumed by the proxy and never copied upst ## Build -In this option we own the key store: a table in the website's Postgres, a lookup in the proxy, and an admin command. Nothing new is installed. This is the fallback if the plugin spike fails. +In this option we own the key store: a table in the website's Postgres, a lookup in the proxy, and admin pages. Nothing new is installed. This is the fallback if the plugin spike fails. The proxy reaches the store through a small verifier: it takes a key and answers with the key's public id, limit and owner, or says the key is invalid, or says the store is unavailable. Nothing else in the proxy knows where keys live, so the store can change later. Public ids stay the same if it does. @@ -249,11 +249,11 @@ Before the rate limit, on the surfaces in [Where Keys Apply][]: [Identity, Failure and Abuse][] covers revocation delay and failing open when the store is unavailable. -A keyed call is named to the backends by its account instead of `ip:`, so their allowances are per account too. The exact form (`key:` or the `user:` form dfo-ai already documents) is settled with the dfo-apis change. dfo-apis refuses any form but `ip:` with a 400 today. dfo-ai accepts a keyed caller on arrival, but its MCP servers drop any caller that is not `ip:` before they call dfo-apis. Both need a change. See [Work by Repository][]. +A keyed call is named to the backends by its account instead of `ip:`, so their allowances are per account too. The form is `user:` and the first 32 hex digits of an HMAC-SHA-256 over the account id, keyed like the `ip:` digest, so no account id leaves the website. dfo-apis refuses any form but `ip:` with a 400 today. dfo-ai accepts a keyed caller on arrival, but its MCP servers drop any caller that is not `ip:` before they call dfo-apis. Both need a change. See [Work by Repository][]. ### Future Work: Admin Interface -Phase 1 has only an admin command that creates and revokes keys and sets account limits, run in production as a Cloud Run Job. Later phases need more, and all of it would be ours to build: +Operators work from an admin page (see [Admin System][]). Later phases need more, and all of it would be ours to build: - Self-service pages in the account menu to create, label and revoke keys and see last use, with the endpoints and ownership checks behind them (Phase 2). - An operator view to find a key, see its usage, and raise or cut its limits (Phase 3). @@ -301,7 +301,11 @@ There is no admin interface to leverage. This was checked in three places: | [Better Auth admin plugin][better-auth-admin] | User administration: list and edit users, roles, bans, sessions, impersonation | No. It has no pages either, only methods, and it does not cover API keys | | [Better Auth Infrastructure dashboard][better-auth-dash] | A hosted dashboard from the Better Auth company, fed by a plugin that sends user and session events to their service | Not documented. It would also send account activity to a third party | -So an admin command, run in production as a Cloud Run Job, and later an operator view, are ours to write in either option. With the plugin, they are thin wrappers over its server methods instead of our own queries. The plugin's own client methods already cover a signed-in user's keys, which is most of what self-service needs. A community library, better-auth-ui, has ready-made components for a user's own keys, which could shorten the Phase 2 self-service pages. It has not been evaluated. +So the operator view is ours to write in either option. With the plugin, it is a thin wrapper over its server methods instead of our own queries. + +Phase 1 ships it as a proof of concept at `/admin/api-keys`. It is open to signed-in users whose verified email is in `ADMIN_EMAILS`, and answers 404 to everyone else, checked on the page and in every action. An operator can list every key with its owner and last use, filter by email, create a key for an account, delete any key, and set or clear an account's limit. Each change writes a log line naming the operator. A Cloud Run Job running an admin command is no longer needed for Phase 1, though one could still be added for scripted changes. + +The self-service page, `/account/api-keys`, is built the same way: our own server actions over the plugin's server methods, since the plugin's HTTP endpoints are disabled. ### What It Saves and What It Costs @@ -344,13 +348,13 @@ Three phases take keys from an optional test feature to the normal way heavy use **Who gets a key:** A few callers we choose -**Provisioning:** Manual: an admin command, run as a Cloud Run Job, creates and revokes keys +**Provisioning:** Manual: operators create and revoke keys on the admin page, `/admin/api-keys` **Limits:** Set per account by hand **Anonymous access:** Unchanged -**Also needed:** Proxy check behind a verifier, the plugin's key table, admin command with an emergency off switch, a burst-safe fallback when the counter is slow, dfo-apis and dfo-ai accept and pass on keyed callers, key usage logged in `forward()`, and the API docs and quickstart +**Also needed:** Proxy check behind a verifier, the plugin's key table, the admin page, the `API_KEYS_ENABLED` switch that turns all keyed access off, a burst-safe fallback when the counter is slow, dfo-apis and dfo-ai accept and pass on keyed callers, key usage logged in `forward()`, and the API docs and quickstart **Exit criteria:** The first partner runs on a key in production without incident, and per-key counts in the logs match what they report sending. @@ -360,7 +364,7 @@ Three phases take keys from an optional test feature to the normal way heavy use **Who gets a key:** Any signed-in account -**Provisioning:** Self-service from the account menu: create, label, revoke, see last use. The plugin's endpoints make this mostly page work, so it could start earlier if a partner needs it. +**Provisioning:** Self-service from the account menu, `/account/api-keys`: create, label, revoke, see last use, up to `API_KEYS_MAX_PER_ACCOUNT` keys (5 by default). The page was built alongside Phase 1, so Phase 2 is when it is announced rather than when it is written. **Limits:** A default for self-service accounts, with higher limits granted by an operator. We will examine current usage and tune the default and the anonymous thresholds at that time, as part of the transition plan. @@ -428,14 +432,14 @@ Observations: Most of the work is in the website. This split holds for both options: Use and Build differ only in the website row, in where keys are stored and how they are looked up. The other rows are the same either way, since those systems see only the caller name and the key header. Codex's review corrected the dfo-ai row, which first read "little or none". The Phase 1 pieces: -| Where | Size | What | -| ---------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| website | Most of it | The plugin and its table migration (or our own `api_key`); key check, per-account limit, burst-safe counter fallback and key usage logging in `forward()`; admin command to create and revoke; OpenAPI security scheme; tests beside the existing proxy tests | -| dfo-apis | Small | Accept a keyed caller in `x-dfo-caller` beside the website's shared secret, so allowances count per account. Today only `ip:` is accepted, and anything else gets a 400 | -| dfo-ai | Small | Pass a keyed caller on to dfo-apis. Its data, presentation and analysis clients forward only `ip:` today and drop anything else, which would count a keyed caller's allowances against dfo-ai itself | -| infra | Small | A Cloud Run Job that runs the admin command in production, so keys can be deleted and limits changed there | -| docs | Small | The API quickstart, which says no key is needed, and a page on keys | -| Cloudflare | None today | The Pro plan's per-address rules (600 a minute on the data API) sit well above the proxy's limits. Revisit if an account is granted more than that from one address | +| Where | Size | What | +| ---------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| website | Most of it | The plugin and its table migration (or our own `api_key`); key check, per-account limit, burst-safe counter fallback and key usage logging in `forward()`; the self-service and admin pages; OpenAPI security scheme; tests beside the existing proxy tests | +| dfo-apis | Small | Accept a keyed caller in `x-dfo-caller` beside the website's shared secret, so allowances count per account. Today only `ip:` is accepted, and anything else gets a 400 | +| dfo-ai | Small | Pass a keyed caller on to dfo-apis. Its data, presentation and analysis clients forward only `ip:` today and drop anything else, which would count a keyed caller's allowances against dfo-ai itself | +| infra | Optional | The admin page covers operator changes in production. A Cloud Run Job for a scripted admin command is optional | +| docs | Small | The API quickstart, which says no key is needed, and a page on keys | +| Cloudflare | None today | The Pro plan's per-address rules (600 a minute on the data API) sit well above the proxy's limits. Revisit if an account is granted more than that from one address | Order matters. dfo-apis refuses a caller form it does not recognize with a 400 when it arrives with the shared secret. So dfo-apis ships first, then dfo-ai, and the website starts sending keyed callers last. An end-to-end test should show a keyed call through `/mcp` spending the account's own allowance in dfo-apis. @@ -469,7 +473,7 @@ Not planned for any phase yet. The design should not rule them out. None of these block Phase 1. - [ ] **How do we reach current anonymous users** for the Phase 2 transition, given we know them only as hashed addresses? Candidates: docs, response headers, the SDK's `x-dfo-client` header. -- [ ] **Does a key identify an account to the backends as well,** so a signed-in user's key and their site session share allowances? dfo-ai already names a `user:` caller form. +- [ ] **Should a signed-in site session be named by its account too,** so a user's key and their Studio session share allowances in the backends? A key already names its account to the backends as `user:`, and the Studio still names its callers by address. [issue]: https://github.com/DevelopmentFinanceObservatory/website/issues/142 [cf-best-practices]: https://developers.cloudflare.com/waf/rate-limiting-rules/best-practices/ From 343dff8f9b2b360a361f575bffde19e8f832b3a1 Mon Sep 17 00:00:00 2001 From: Sef Kloninger Date: Mon, 16 Nov 2026 15:25:28 -0800 Subject: [PATCH 30/34] feat(account): link the API keys admin page from the account menu (#142) Admins (a verified email on ADMIN_EMAILS) see "Admin: API keys" in the account menu. Whether the viewer is an admin is a server setting, so the menu asks through a server action the first time it opens for a user; the admin page and its actions still enforce the gate themselves. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_015QQk2mKJZzXv2AYykDjvQf --- .../molecules/AccountMenu/AccountMenu.tsx | 33 +++++++++++++++++-- src/lib/apiKeys/viewer.ts | 15 +++++++++ 2 files changed, 46 insertions(+), 2 deletions(-) create mode 100644 src/lib/apiKeys/viewer.ts diff --git a/src/components/molecules/AccountMenu/AccountMenu.tsx b/src/components/molecules/AccountMenu/AccountMenu.tsx index c3feef0..91ad0da 100644 --- a/src/components/molecules/AccountMenu/AccountMenu.tsx +++ b/src/components/molecules/AccountMenu/AccountMenu.tsx @@ -10,13 +10,20 @@ import DeleteAccountModal from './DeleteAccountModal'; import Button from '@/components/atoms/Button/Button'; import { useSiteNavigate } from '@/hooks/useSiteNavigate'; +import { viewerIsAdmin } from '@/lib/apiKeys/viewer'; import { signOut, useSession } from '@/lib/auth/client'; import { IS_SITE } from '@/lib/site'; /** * The header's account button. Signed out it leads to /login (and back * here afterwards); signed in it opens the account menu — who you are, My - * History, delete account (confirmed in the house panel), sign out. + * History, API keys, Admin (admins only), delete account (confirmed in the + * house panel), sign out. + * + * Whether the viewer is an admin is a server setting (ADMIN_EMAILS), so the + * menu asks once, the first time it opens for a given user, and shows the + * Admin item when the answer comes back. The prototypes app has no admin + * page, so it never asks. */ type AccountMenuProps = { className?: string; @@ -31,6 +38,8 @@ const AccountMenu = ({ className }: AccountMenuProps) => { // Keys the modal per opening so its fields start clean; it stays // mounted through the close animation. const [deleteSeq, setDeleteSeq] = useState(0); + // The user id the admin answer belongs to, so another sign-in asks again. + const [admin, setAdmin] = useState<{ userId: string; admin: boolean } | null>(null); if (!session) { return ( @@ -50,6 +59,19 @@ const AccountMenu = ({ className }: AccountMenuProps) => { } const { user } = session; + const isAdmin = admin?.userId === user.id && admin.admin; + + const askAdmin = (open: boolean) => { + if (!open || !IS_SITE || admin?.userId === user.id) { + return; + } + const userId = user.id; + + viewerIsAdmin().then( + (answer) => setAdmin({ userId, admin: answer }), + () => setAdmin({ userId, admin: false }), + ); + }; const leave = async () => { await signOut(); @@ -66,7 +88,7 @@ const AccountMenu = ({ className }: AccountMenuProps) => { // Non-modal, like every other menu in the app: the modal variant locks // the page (body pointer-events off + scroll lock) and on touch the // menu never showed, leaving the lock behind. - + + {isAdmin && ( + navigate('/admin/api-keys')}> + + + )}