diff --git a/.env.example b/.env.example index dc29e988..2a211cd4 100644 --- a/.env.example +++ b/.env.example @@ -116,13 +116,31 @@ 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 +# 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 +# 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. 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/db/auth-schema.ts b/db/auth-schema.ts index 9e70410e..c8e9a75d 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/connection.ts b/db/connection.ts index 8aeb31bd..b82d5d03 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/db/migrations/0025_api_keys.sql b/db/migrations/0025_api_keys.sql new file mode 100644 index 00000000..a7c60ff9 --- /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 00000000..9f68f8ea --- /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 1cd98719..64a91327 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 00000000..11495793 --- /dev/null +++ b/db/test/api-key.test.ts @@ -0,0 +1,210 @@ +import assert from 'node:assert/strict'; +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("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 () => { + 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, await defaultKeyHasher(created.key)); + // The stored form is base64url(SHA-256(key)), unpadded: the plugin's + // hasher on a fixed input matches that, computed independently. + assert.equal( + await defaultKeyHasher('dfo_live_known-answer'), + 'NJcfEBlh8jOAAbK52QabqvvVBcoa3ykj-SNDqq0F7Y0', + ); + 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/deploy/README.md b/deploy/README.md index 408e3201..5d7d5099 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -251,6 +251,10 @@ 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 | +| `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/docs/analytics.md b/docs/analytics.md index 404f8053..a35cf756 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/docs/design/api-keys.md b/docs/design/api-keys.md new file mode 100644 index 00000000..d94590ac --- /dev/null +++ b/docs/design/api-keys.md @@ -0,0 +1,514 @@ +# API Keys for the Platform Proxy + +Sef Kloninger <> with Claude Code and Codex \ +[Issue #142][issue] \ +Last Update: Nov 16, 2026 + +## Contents + +- [Summary][] +- [How It Works Today][] +- [Requirements][] + - [Key Format and Communication][] + - [Limits][] + - [Cloudflare Integration][] + - [Where Keys Apply][] + - [Identity, Failure and Abuse][] + - [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][] + - [Phase 3: Enforce][] +- [Testing][] + - [Local Test Results][] +- [Work by Repository][] +- [Alternatives Considered][] +- [Future Features][] +- [Open Questions][] + +## Summary + +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 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. + +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 stay open up to a limit. Our goal is to manage usage and enable rate limits, not wholesale API gating. +- 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, 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. + +## 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, 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 (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. +- **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. + +## Requirements + +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 + +- 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 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. +- 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. + +**Comparables: How Other Services Do It** + +Since this is an interesting choice, we did an informal survey of 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 | +| 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 | +| 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, 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** + +| 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 | + +### Limits + +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. 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 account's limit | +| MCP | `/mcp` | 300 calls a minute per address | The account's limit | + +- 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 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 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 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 account's limit. + +### Cloudflare Integration + +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** + +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. +- Today's thresholds are already well above the proxy's anonymous limits, so Phase 1 needs no edge change. + +### 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. 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 + +- 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 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. + +### 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 | +| 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. + +### The Proxy Check + +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 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 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 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 + +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). +- 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. This is the recommended option from Phase 1, behind the same verifier the Build store would use. + +### 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({ 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 + +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 + +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 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 + +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. 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 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][]. + +- [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 + +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 + +**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: 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, 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. + +### 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, `/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. + +**Anonymous access:** Unchanged; docs start recommending a key + +**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. + +### 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 an account's limit + +**Limits:** Anonymous limits lowered in steps + +**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. 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: + +| 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. + +## 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 | +| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 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. + +## 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. +- **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 + +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. +- [ ] **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/ +[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 +[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 +[Requirements]: #requirements +[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 +[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 +[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 +[Open Questions]: #open-questions diff --git a/docs/development.md b/docs/development.md index 2e1d70a6..735bd308 100644 --- a/docs/development.md +++ b/docs/development.md @@ -57,6 +57,26 @@ 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`), 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` +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 +87,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 69767787..1ec1ff5c 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,49 @@ 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. + # 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" 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 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 # create one. Next warns that `next start` does not work with # `output: 'standalone'` (which next.config.ts sets); it serves locally diff --git a/package.json b/package.json index 4ebda4e5..fc50be1f 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", @@ -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 5039a662..4474da53 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/app/(site)/account/api-keys/actions.ts b/src/app/(site)/account/api-keys/actions.ts new file mode 100644 index 00000000..07e155a5 --- /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 00000000..cea212ba --- /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/app/(site)/admin/api-keys/actions.ts b/src/app/(site)/admin/api-keys/actions.ts new file mode 100644 index 00000000..ebbd59f8 --- /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 00000000..8310f6b7 --- /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/app/api/account/admin/route.ts b/src/app/api/account/admin/route.ts new file mode 100644 index 00000000..a441a85e --- /dev/null +++ b/src/app/api/account/admin/route.ts @@ -0,0 +1,18 @@ +import { NextResponse } from 'next/server'; + +import { adminFrom } from '@/lib/apiKeys/settings'; +import { getUser } from '@/lib/auth/session'; + +// GET /api/account/admin → { admin: boolean }, whether the signed-in viewer is +// an admin (lib/apiKeys/settings.isAdmin: a verified email on ADMIN_EMAILS), +// so the account menu can show its link to /admin/api-keys. It answers only +// about the caller, and false when signed out. The link is a convenience: the +// admin page and every admin action check the gate themselves +// (lib/apiKeys/server.requireAdmin). A route rather than a server action, since +// the account menu is also built into the prototypes app's static export, +// which refuses server actions. +export const GET = async () => { + const admin = adminFrom(await getUser(), process.env.ADMIN_EMAILS) !== null; + + return NextResponse.json({ admin }, { headers: { 'cache-control': 'private, no-store' } }); +}; diff --git a/src/app/api/v1/studio/[...path]/route.ts b/src/app/api/v1/studio/[...path]/route.ts index d1e2ad56..d35142a1 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 36f96603..e52a7bcb 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/components/molecules/AccountMenu/AccountMenu.tsx b/src/components/molecules/AccountMenu/AccountMenu.tsx index fdda9d42..6f527080 100644 --- a/src/components/molecules/AccountMenu/AccountMenu.tsx +++ b/src/components/molecules/AccountMenu/AccountMenu.tsx @@ -16,7 +16,13 @@ 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 GET /api/account/admin 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 +37,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 +58,21 @@ 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; + + fetch('/api/account/admin', { cache: 'no-store' }) + .then((response) => (response.ok ? response.json() : { admin: false })) + .then( + (body: { admin?: unknown }) => setAdmin({ userId, admin: body.admin === true }), + () => setAdmin({ userId, admin: false }), + ); + }; const leave = async () => { await signOut(); @@ -66,7 +89,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. - + + navigate('/account/api-keys')}> + + + {isAdmin && ( + navigate('/admin/api-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 yet'} + {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; diff --git a/src/components/organisms/ApiKeys/ApiKeys.module.scss b/src/components/organisms/ApiKeys/ApiKeys.module.scss new file mode 100644 index 00000000..5f54f40d --- /dev/null +++ b/src/components/organisms/ApiKeys/ApiKeys.module.scss @@ -0,0 +1,291 @@ +@use "variables" as *; +@use "mixins" as *; +@use "breakpoints" as *; + +// The account and admin API key pages: one plain column under the light +// hero, as the policy pages have, with a wider one for the admin table. +.page { + position: relative; + background-color: var(--color-bg); +} + +.title { + @include font-size(64px, 0.95); + + font-family: var(--font-outfit); + font-weight: 800; + color: var(--color-charcoal); + letter-spacing: -0.04em; +} + +@include breakpoint(phone) { + .title { + @include font-size(44px, 0.95); + } +} + +.body, +.bodyWide { + padding: rem(60) rem(30) rem(120); + margin-inline: auto; + font-family: var(--font-outfit); + font-weight: 300; + color: var(--color-charcoal); + letter-spacing: -0.01em; +} + +.body { + max-width: rem(760); +} + +.bodyWide { + max-width: rem(1180); +} + +.lead { + @include font-size(17px, 1.45); + + margin-bottom: rem(32); +} + +.heading { + @include font-size(28px, 1); + + margin-top: rem(48); + margin-bottom: rem(16); + font-weight: 700; + letter-spacing: -0.03em; +} + +.copy { + @include font-size(17px, 1.45); + + margin-top: rem(12); + + strong { + font-weight: 600; + } +} + +.note { + @include font-size(14px, 1.4); + + margin-top: rem(10); + color: var(--color-text-muted); +} + +.notice, +.status { + @include font-size(14px, 1.4); + + padding: rem(10) rem(14); + margin-bottom: rem(16); + border-radius: rem(6); +} + +.notice { + background-color: var(--color-red-light); +} + +.status { + background-color: var(--color-net-light); +} + +.scroll { + overflow-x: auto; +} + +.table { + @include font-size(14px, 1.35); + + width: 100%; + border-collapse: collapse; + + th, + td { + padding: rem(10) rem(12) rem(10) 0; + text-align: left; + vertical-align: middle; + border-bottom: 1px solid var(--color-beige); + } + + th { + font-family: var(--font-dm-mono); + font-size: rem(12); + font-weight: 400; + color: var(--color-text-muted); + white-space: nowrap; + } + + code { + font-family: var(--font-dm-mono); + font-size: rem(12); + word-break: break-all; + } +} + +.actions { + text-align: right !important; + white-space: nowrap; +} + +.form { + @include flex(row, flex-start, flex-end); + + flex-wrap: wrap; + gap: rem(12); + margin-bottom: rem(12); +} + +.field { + display: flex; + flex-direction: column; + gap: rem(4); +} + +.label { + @include font-size(12px, 1.3); + + font-family: var(--font-dm-mono); + color: var(--color-text-muted); +} + +.input { + @include font-size(15px, 1.3); + + width: rem(240); + max-width: 100%; + height: rem(38); + padding: 0 rem(10); + font-family: var(--font-outfit); + color: var(--color-charcoal); + background-color: var(--color-white); + border: 1px solid var(--color-beige); + border-radius: rem(6); +} + +// The buttons share the house dark button's shape. +.primary, +.secondary, +.danger, +.dangerSolid { + @include flex(row, center, center); + @include font-size(12px, 1.34); + + height: rem(38); + padding: 0 rem(14); + font-family: var(--font-dm-mono); + letter-spacing: -0.01em; + cursor: pointer; + border-radius: rem(6); + transition: opacity 0.25s ease; + + &:hover:not(:disabled) { + opacity: 0.85; + } + + &:disabled { + cursor: default; + opacity: 0.4; + } +} + +.primary { + color: var(--color-white); + background-color: var(--color-charcoal); + border: 0; +} + +.secondary { + color: var(--color-charcoal); + background-color: transparent; + border: 1px solid var(--color-charcoal); +} + +.danger { + height: rem(30); + color: var(--color-red); + background-color: transparent; + border: 1px solid var(--color-red); +} + +.dangerSolid { + height: rem(30); + color: var(--color-white); + background-color: var(--color-red); + border: 0; +} + +.confirm { + @include flex(row, flex-end, center); + + flex-wrap: wrap; + gap: rem(8); + + .secondary { + height: rem(30); + } +} + +.confirmText { + @include font-size(13px, 1.3); +} + +.error, +.errorInline { + @include font-size(13px, 1.3); + + color: var(--color-red); +} + +.error { + padding: rem(8) rem(10); + margin-top: rem(10); + background-color: var(--color-net-light); + border-radius: rem(6); +} + +// The new key, shown once: loud enough that it is not missed. +.once { + padding: rem(16); + margin-top: rem(16); + background-color: var(--color-white); + border: 2px solid var(--color-charcoal); + border-radius: rem(8); +} + +.onceTitle { + @include font-size(17px, 1.3); + + font-weight: 600; +} + +.keyRow { + @include flex(row, flex-start, center); + + flex-wrap: wrap; + gap: rem(12); + margin-top: rem(12); +} + +.keyValue { + @include font-size(15px, 1.3); + + padding: rem(8) rem(10); + font-family: var(--font-dm-mono); + word-break: break-all; + user-select: all; + background-color: var(--color-net-light); + border-radius: rem(6); +} + +.code { + @include font-size(13px, 1.5); + + padding: rem(12) rem(14); + margin-top: rem(10); + overflow-x: auto; + font-family: var(--font-dm-mono); + background-color: var(--color-media-bg); + border-radius: rem(6); +} diff --git a/src/components/organisms/ApiKeys/ApiKeysShell.tsx b/src/components/organisms/ApiKeys/ApiKeysShell.tsx new file mode 100644 index 00000000..b1bfbe77 --- /dev/null +++ b/src/components/organisms/ApiKeys/ApiKeysShell.tsx @@ -0,0 +1,35 @@ +import type { ReactNode } from 'react'; + +import styles from './ApiKeys.module.scss'; + +import PageFade from '@/components/molecules/PageFade/PageFade'; +import PageHero from '@/components/molecules/PageHero/PageHero'; + +/** The frame of the two key pages: the light hero with the title, then the page's sections. */ +const ApiKeysShell = ({ + title, + lead, + wide, + children, +}: { + title: string; + lead: string; + // The admin table needs more room than the account page's one column. + wide?: boolean; + children: ReactNode; +}) => ( +
+
+ +

{title}

+
+
+

{lead}

+ {children} +
+ +
+
+); + +export default ApiKeysShell; diff --git a/src/components/organisms/ApiKeys/CreateKeyForm.tsx b/src/components/organisms/ApiKeys/CreateKeyForm.tsx new file mode 100644 index 00000000..64ee5f63 --- /dev/null +++ b/src/components/organisms/ApiKeys/CreateKeyForm.tsx @@ -0,0 +1,104 @@ +'use client'; + +import { useActionState, useState } from 'react'; + +import styles from './ApiKeys.module.scss'; +import type { CreatedState } from './state'; + +type CreateKeyFormProps = { + // A server action: the account's own, or the admin's. + action: (previous: CreatedState, formData: FormData) => Promise; + // The admin form names the account to make the key for. + withEmail?: boolean; + // Why a key cannot be made now, which disables the form. + blocked?: string; +}; + +/** + * The create form. The key the action answers with is held here, in this + * component's state, and nowhere else: reload or leave the page and it is + * gone, as the note beside it says. Only a hash is stored. + */ +const CreateKeyForm = ({ action, withEmail, blocked }: CreateKeyFormProps) => { + const [state, submit, pending] = useActionState(action, null); + const [copied, setCopied] = useState(false); + const key = state?.created?.key; + + const copy = async () => { + try { + await navigator.clipboard.writeText(key ?? ''); + setCopied(true); + } catch { + // Clipboard access can be refused; the key is selectable below. + setCopied(false); + } + }; + + return ( +
+
{ + setCopied(false); + submit(formData); + }} + > + {withEmail && ( + + )} + + +
+ {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 00000000..5be2b417 --- /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 00000000..8b5523d1 --- /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 00000000..0d807fcc --- /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 00000000..84883dc0 --- /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 00000000..abc14685 --- /dev/null +++ b/src/lib/apiKeys/service.ts @@ -0,0 +1,281 @@ +/** + * 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; + // 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; +}; + +/** 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 00000000..d5824c07 --- /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 00000000..1b5e3e7d --- /dev/null +++ b/src/lib/apiKeys/test/service.test.ts @@ -0,0 +1,371 @@ +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, + API_KEY_START_LENGTH, + 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 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); + }); + + 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 00000000..e040c572 --- /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/auth/apiKeyOptions.ts b/src/lib/auth/apiKeyOptions.ts new file mode 100644 index 00000000..e4856d45 --- /dev/null +++ b/src/lib/auth/apiKeyOptions.ts @@ -0,0 +1,45 @@ +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', +]; + +/** + * 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 + * 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, + startingCharactersConfig: { shouldStore: true, charactersLength: API_KEY_START_LENGTH }, + ...overrides, + }); diff --git a/src/lib/auth/auth.ts b/src/lib/auth/auth.ts index 71065e5d..1352c65e 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(), diff --git a/src/lib/db/index.ts b/src/lib/db/index.ts index 7ed4a74d..170f4180 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/access.ts b/src/lib/proxy/access.ts new file mode 100644 index 00000000..7fbaba7d --- /dev/null +++ b/src/lib/proxy/access.ts @@ -0,0 +1,148 @@ +/** + * 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/apiKey.ts b/src/lib/proxy/apiKey.ts new file mode 100644 index 00000000..2a60ad02 --- /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/caller.ts b/src/lib/proxy/caller.ts index 878fdd8b..a5dfe258 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 c0a9497e..0e3b8ea1 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 Access, 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,56 @@ 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. +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 +// 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; + // 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 +192,22 @@ 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); + logKeyUse(options.surface, access); + + if (access.refusal) { + return access.refusal; } + const limitHeaders = access.verdict ? rateHeaders(access.verdict) : {}; + const refusal = await options.admit?.(); if (refusal) { @@ -157,14 +220,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/keyVerifier.ts b/src/lib/proxy/keyVerifier.ts new file mode 100644 index 00000000..d1d12966 --- /dev/null +++ b/src/lib/proxy/keyVerifier.ts @@ -0,0 +1,250 @@ +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). + * + * 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 = + | { + 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>(); + + // 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[]; + + 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)); + touch(row.id); + + 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/limitFallback.ts b/src/lib/proxy/limitFallback.ts new file mode 100644 index 00000000..9fefec09 --- /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 399f33a5..063e0c2e 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 999be0e1..7c4047fd 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 @@ -30,6 +30,7 @@ export type ProblemStatus = keyof typeof TITLES; * code the site refuses with is its own, and its `type` is `about:blank`. */ export const REGISTRY_CODES = [ + 'invalid_api_key', 'request_invalid', 'not_found', 'rate_limited', @@ -119,15 +120,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/proxy-codes.json b/src/lib/proxy/proxy-codes.json index 31109001..3bec02f8 100644 --- a/src/lib/proxy/proxy-codes.json +++ b/src/lib/proxy/proxy-codes.json @@ -1,6 +1,11 @@ { "format_version": 1, "codes": [ + { + "code": "invalid_api_key", + "status": 401, + "condition": "The API key the caller sent in Authorization: Bearer dfo_... or X-API-Key is unknown, revoked or malformed; the call is not treated as anonymous, so it is refused rather than served without a key, and the document is not retryable." + }, { "code": "rate_limited", "status": 429, diff --git a/src/lib/proxy/proxyCodes.ts b/src/lib/proxy/proxyCodes.ts index 1a3c7c7e..c1d14a36 100644 --- a/src/lib/proxy/proxyCodes.ts +++ b/src/lib/proxy/proxyCodes.ts @@ -8,7 +8,7 @@ * `proxy-codes.json` is the client contract's file of the same name, * vendored from the spec-kit repository's * `python/client-contract/src/dfo_client_contract/proxy-codes.json` at - * 0d19172, formatted by Prettier. The vendored `@developmentfinance/client` + * 57ee5cd, formatted by Prettier. The vendored `@developmentfinance/client` * carries its statuses and not its descriptions, so the file is copied here. * Kept apart from the route so `node --test` can load it. */ diff --git a/src/lib/proxy/rateHeaders.ts b/src/lib/proxy/rateHeaders.ts index 986db11a..b84e3aa8 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 7a72cb0b..e7e02bd3 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 00000000..766dd228 --- /dev/null +++ b/src/lib/proxy/test/access.test.ts @@ -0,0 +1,248 @@ +/** + * `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'); + const body = await access.refusal!.json(); + assert.equal(body.code, 'invalid_api_key'); + assert.equal(body.type, '/codes/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/apiKey.test.ts b/src/lib/proxy/test/apiKey.test.ts new file mode 100644 index 00000000..f7762c6e --- /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/caller.test.ts b/src/lib/proxy/test/caller.test.ts index 87654dbb..32ec9fb0 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 00000000..ecf92a86 --- /dev/null +++ b/src/lib/proxy/test/forwardKeys.test.ts @@ -0,0 +1,487 @@ +/** + * `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: 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(); + + 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/keyVerifier.test.ts b/src/lib/proxy/test/keyVerifier.test.ts new file mode 100644 index 00000000..e0806943 --- /dev/null +++ b/src/lib/proxy/test/keyVerifier.test.ts @@ -0,0 +1,428 @@ +/** + * `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); + } + }); + + 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, updated_at, remaining, enabled, expires_at from apikey where id <> 'id-fresh' order by id`, + ); + + const fresh = await addKey('fresh', 'acct-default'); + + assert.equal(await lastRequestOf('id-fresh'), null); + + const clock = Date.now(); + const verifier = createKeyVerifier(db, { now: () => clock }); + + 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, 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[] = []; + 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[]) => { + 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); + }; + 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), + update: (...args: Parameters) => db.update(...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' }); + }, + ); +}); diff --git a/src/lib/proxy/test/limitFallback.test.ts b/src/lib/proxy/test/limitFallback.test.ts new file mode 100644 index 00000000..98f1c88a --- /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 396d90e4..3fa9e705 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/problem.test.ts b/src/lib/proxy/test/problem.test.ts index e7ce4045..5fc6ff4f 100644 --- a/src/lib/proxy/test/problem.test.ts +++ b/src/lib/proxy/test/problem.test.ts @@ -98,6 +98,7 @@ test('problem: titles the statuses the site refuses with and spreads the extra m test('problem: type links the registry codes and is about:blank for any other code', async () => { for (const [code, type] of [ + ['invalid_api_key', '/codes/invalid_api_key'], ['request_invalid', '/codes/request_invalid'], ['not_found', '/codes/not_found'], ['rate_limited', '/codes/rate_limited'], diff --git a/src/lib/proxy/test/proxyCodes.test.ts b/src/lib/proxy/test/proxyCodes.test.ts index 600b9a9d..b30ad845 100644 --- a/src/lib/proxy/test/proxyCodes.test.ts +++ b/src/lib/proxy/test/proxyCodes.test.ts @@ -5,7 +5,12 @@ import assert from 'node:assert/strict'; import { readFileSync } from 'node:fs'; import test from 'node:test'; -import { REGISTRY_CODES, rateLimitedProblem, unreachableProblem } from '../problem.ts'; +import { + REGISTRY_CODES, + invalidKeyProblem, + rateLimitedProblem, + unreachableProblem, +} from '../problem.ts'; import { proxyCodeEntry } from '../proxyCodes.ts'; // Read from the file, so the expected split does not come from the module under test. @@ -46,3 +51,12 @@ test('proxyCodeEntry: the body has the API registry entry shape, titled as the p (await unreachableProblem('x', {}).json()).title, ); }); + +test('proxyCodeEntry: invalid_api_key is the 401 the proxy answers a bad key with', async () => { + const problem = await invalidKeyProblem().json(); + const entry = proxyCodeEntry('invalid_api_key'); + + assert.equal(problem.type, '/codes/invalid_api_key'); + assert.equal(entry?.title, problem.title); + assert.equal(codes.find(({ code }) => code === 'invalid_api_key')?.status, 401); +}); diff --git a/src/lib/proxy/test/rateLimit.test.ts b/src/lib/proxy/test/rateLimit.test.ts new file mode 100644 index 00000000..43ffb098 --- /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); +});