@antasphere/chassis-server 1.0.0

package/dist/middleware/json-depth.js

@@ -0,0 +1,80 @@
+import { apiError } from '../api/errors.js';
+/**
+ * Nesting cap for request JSON. Deliberately far above anything a contract in
+ * `@antasphere/contract` describes (the deepest is three or four levels) and far
+ * below the depth at which V8 recursion breaks.
+ *
+ * Why a cap at all: `JSON.parse` is iterative and swallows any depth, but
+ * `JSON.stringify` is RECURSIVE and blows the stack with a `RangeError` past a
+ * few thousand levels — and the exact depth depends on the V8 build, so it
+ * reproduces inside the shipped `node:22-alpine` image and not on a newer host
+ * Node. Every path that echoes, audits, logs, or persists a validated body
+ * stringifies it, so an anonymous client could turn one small request body
+ * into a 500 plus an error-level stack trace. Rejecting at the edge — before
+ * anything parses, let alone stringifies — is the only place the fix is
+ * complete.
+ */
+export const MAX_JSON_DEPTH = 100;
+/** Matches better-call's / Hono's JSON content-type test (same regex family). */
+const JSON_CONTENT_TYPE = /^application\/([a-z0-9.+-]*\+)?json/i;
+/**
+ * True when `text` nests `{`/`[` deeper than `max`. A single string-aware
+ * scan, no parsing and no allocation: brackets inside JSON string literals
+ * (and escaped quotes inside them) do not count. Returns as soon as the limit
+ * is passed, so a hostile body costs O(prefix), not O(body).
+ */
+export function exceedsJsonDepth(text, max) {
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (ch === '\\')
+                escaped = true;
+            else if (ch === '"')
+                inString = false;
+            continue;
+        }
+        if (ch === '"')
+            inString = true;
+        else if (ch === '{' || ch === '[') {
+            depth++;
+            if (depth > max)
+                return true;
+        }
+        else if (ch === '}' || ch === ']')
+            depth--;
+    }
+    return false;
+}
+/**
+ * Rejects over-deep JSON bodies with a 400 before any handler, parser or
+ * serializer sees them. Non-JSON and bodyless requests pass untouched, so
+ * streamed uploads and form-encoded token calls are unaffected. Mount it
+ * AFTER the body-size limit so the scan is bounded by that cap.
+ */
+export function jsonDepthLimit(maxDepth = MAX_JSON_DEPTH) {
+    return async (c, next) => {
+        const raw = c.req.raw;
+        if (!raw.body)
+            return next();
+        if (!JSON_CONTENT_TYPE.test(raw.headers.get('content-type') ?? ''))
+            return next();
+        let text;
+        try {
+            text = await raw.clone().text();
+        }
+        catch {
+            // Unreadable body — let the normal parser produce the normal error.
+            return next();
+        }
+        if (exceedsJsonDepth(text, maxDepth)) {
+            return apiError(c, 400, 'payload_too_deep', `Request JSON nests deeper than ${maxDepth} levels`);
+        }
+        return next();
+    };
+}
+//# sourceMappingURL=json-depth.js.map

package/dist/middleware/json-depth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-depth.js","sourceRoot":"","sources":["../../src/middleware/json-depth.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,CAAC;AAElC,iFAAiF;AACjF,MAAM,iBAAiB,GAAG,sCAAsC,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,GAAW;IACxD,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACnB,IAAI,QAAQ,EAAE,CAAC;YACb,IAAI,OAAO;gBAAE,OAAO,GAAG,KAAK,CAAC;iBACxB,IAAI,EAAE,KAAK,IAAI;gBAAE,OAAO,GAAG,IAAI,CAAC;iBAChC,IAAI,EAAE,KAAK,GAAG;gBAAE,QAAQ,GAAG,KAAK,CAAC;YACtC,SAAS;QACX,CAAC;QACD,IAAI,EAAE,KAAK,GAAG;YAAE,QAAQ,GAAG,IAAI,CAAC;aAC3B,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YAClC,KAAK,EAAE,CAAC;YACR,IAAI,KAAK,GAAG,GAAG;gBAAE,OAAO,IAAI,CAAC;QAC/B,CAAC;aAAM,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,KAAK,GAAG;YAAE,KAAK,EAAE,CAAC;IAC/C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,WAAmB,cAAc;IAC9D,OAAO,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE;QACvB,MAAM,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;QACtB,IAAI,CAAC,GAAG,CAAC,IAAI;YAAE,OAAO,IAAI,EAAE,CAAC;QAC7B,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;YAAE,OAAO,IAAI,EAAE,CAAC;QAClF,IAAI,IAAY,CAAC;QACjB,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,GAAG,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC;QAClC,CAAC;QAAC,MAAM,CAAC;YACP,oEAAoE;YACpE,OAAO,IAAI,EAAE,CAAC;QAChB,CAAC;QACD,IAAI,gBAAgB,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,CAAC;YACrC,OAAO,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,kBAAkB,EAAE,kCAAkC,QAAQ,SAAS,CAAC,CAAC;QACnG,CAAC;QACD,OAAO,IAAI,EAAE,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC"}

package/dist/middleware/no-store.d.ts

@@ -0,0 +1,21 @@
+import type { MiddlewareHandler } from 'hono';
+/**
+ * `Cache-Control: no-store` on authenticated JSON.
+ *
+ * `/me`, the member roster, the audit page, every product resource — all of
+ * them answer per-principal JSON with no cache directive at all, which leaves
+ * the decision to heuristic caching in whatever sits in front of the app (a
+ * shared corporate proxy, a CDN a self-hoster puts in the path, the browser's
+ * own bfcache/back-button restore). One user's roster served to the next is
+ * exactly the failure mode `no-store` exists to prevent.
+ *
+ * Scoped deliberately:
+ *
+ *  - only when a principal resolved — anonymous discovery (`/instance`) and
+ *    the OpenAPI document stay cacheable;
+ *  - only JSON — file downloads and exports are streamed, sometimes ranged,
+ *    and set their own headers (api/export.ts already sends `no-store`);
+ *  - never clobbering a Cache-Control a route set for itself.
+ */
+export declare function noStoreAuthenticated(): MiddlewareHandler;
+//# sourceMappingURL=no-store.d.ts.map

package/dist/middleware/no-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-store.d.ts","sourceRoot":"","sources":["../../src/middleware/no-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAE9C;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,IAAI,iBAAiB,CASxD"}

package/dist/middleware/no-store.js

@@ -0,0 +1,32 @@
+/**
+ * `Cache-Control: no-store` on authenticated JSON.
+ *
+ * `/me`, the member roster, the audit page, every product resource — all of
+ * them answer per-principal JSON with no cache directive at all, which leaves
+ * the decision to heuristic caching in whatever sits in front of the app (a
+ * shared corporate proxy, a CDN a self-hoster puts in the path, the browser's
+ * own bfcache/back-button restore). One user's roster served to the next is
+ * exactly the failure mode `no-store` exists to prevent.
+ *
+ * Scoped deliberately:
+ *
+ *  - only when a principal resolved — anonymous discovery (`/instance`) and
+ *    the OpenAPI document stay cacheable;
+ *  - only JSON — file downloads and exports are streamed, sometimes ranged,
+ *    and set their own headers (api/export.ts already sends `no-store`);
+ *  - never clobbering a Cache-Control a route set for itself.
+ */
+export function noStoreAuthenticated() {
+    return async (c, next) => {
+        await next();
+        if (!c.get('principal'))
+            return;
+        if (c.res.headers.has('cache-control'))
+            return;
+        const contentType = c.res.headers.get('content-type') ?? '';
+        if (!contentType.includes('json'))
+            return;
+        c.res.headers.set('Cache-Control', 'no-store');
+    };
+}
+//# sourceMappingURL=no-store.js.map

package/dist/middleware/no-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-store.js","sourceRoot":"","sources":["../../src/middleware/no-store.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE;QACvB,MAAM,IAAI,EAAE,CAAC;QACb,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC;YAAE,OAAO;QAChC,IAAI,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;YAAE,OAAO;QAC/C,MAAM,WAAW,GAAG,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;QAC5D,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC;YAAE,OAAO;QAC1C,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,UAAU,CAAC,CAAC;IACjD,CAAC,CAAC;AACJ,CAAC"}

package/dist/middleware/oauth-public.d.ts

@@ -0,0 +1,16 @@
+import type { MiddlewareHandler } from 'hono';
+export declare const OAUTH_CORS_HEADERS: {
+    readonly 'Access-Control-Allow-Origin': "*";
+    readonly 'Access-Control-Allow-Methods': "GET, POST, OPTIONS";
+    readonly 'Access-Control-Allow-Headers': "Content-Type, Authorization, mcp-protocol-version";
+    readonly 'Access-Control-Max-Age': "86400";
+};
+export declare function isPublicOauthPath(path: string): boolean;
+/**
+ * Wide-open CORS + preflight handling for the public OAuth endpoints, and
+ * RFC 6749 §5.1 cache suppression on the token endpoint (its responses carry
+ * credentials). Registered before the auth-surface rate limits so OPTIONS
+ * preflights never consume a bucket.
+ */
+export declare function oauthPublicEndpoints(): MiddlewareHandler;
+//# sourceMappingURL=oauth-public.d.ts.map

package/dist/middleware/oauth-public.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-public.d.ts","sourceRoot":"","sources":["../../src/middleware/oauth-public.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAmB9C,eAAO,MAAM,kBAAkB;;;;;CAKrB,CAAC;AAEX,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI,iBAAiB,CAiBxD"}

package/dist/middleware/oauth-public.js

@@ -0,0 +1,50 @@
+/**
+ * Public (cookie-less) OAuth endpoints that MCP clients call cross-origin.
+ * These authenticate via body credentials (code + PKCE, refresh token), never
+ * cookies, so a wildcard CORS origin is safe — and required for browser-based
+ * clients to read the responses. Cookie-bearing auth endpoints (sign-in,
+ * consent, authorize) are deliberately NOT in this list. Ported from the Neon
+ * template's hooks.server.ts PUBLIC_OAUTH_PATHS treatment, adapted to the
+ * /api/v1/auth base path.
+ */
+const PUBLIC_OAUTH_PATHS = new Set([
+    '/api/v1/auth/oauth2/token',
+    '/api/v1/auth/oauth2/register',
+    '/api/v1/auth/oauth2/introspect',
+    '/api/v1/auth/oauth2/revoke',
+    '/api/v1/auth/jwks'
+]);
+export const OAUTH_CORS_HEADERS = {
+    'Access-Control-Allow-Origin': '*',
+    'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+    'Access-Control-Allow-Headers': 'Content-Type, Authorization, mcp-protocol-version',
+    'Access-Control-Max-Age': '86400'
+};
+export function isPublicOauthPath(path) {
+    return PUBLIC_OAUTH_PATHS.has(path) || path.startsWith('/api/v1/auth/.well-known/');
+}
+/**
+ * Wide-open CORS + preflight handling for the public OAuth endpoints, and
+ * RFC 6749 §5.1 cache suppression on the token endpoint (its responses carry
+ * credentials). Registered before the auth-surface rate limits so OPTIONS
+ * preflights never consume a bucket.
+ */
+export function oauthPublicEndpoints() {
+    return async (c, next) => {
+        if (!isPublicOauthPath(c.req.path)) {
+            return next();
+        }
+        if (c.req.method === 'OPTIONS') {
+            return c.body(null, 204, { ...OAUTH_CORS_HEADERS });
+        }
+        await next();
+        for (const [key, value] of Object.entries(OAUTH_CORS_HEADERS)) {
+            c.res.headers.set(key, value);
+        }
+        if (c.req.path === '/api/v1/auth/oauth2/token') {
+            c.res.headers.set('Cache-Control', 'no-store');
+            c.res.headers.set('Pragma', 'no-cache');
+        }
+    };
+}
+//# sourceMappingURL=oauth-public.js.map

package/dist/middleware/oauth-public.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-public.js","sourceRoot":"","sources":["../../src/middleware/oauth-public.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC;IACjC,2BAA2B;IAC3B,8BAA8B;IAC9B,gCAAgC;IAChC,4BAA4B;IAC5B,mBAAmB;CACpB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,6BAA6B,EAAE,GAAG;IAClC,8BAA8B,EAAE,oBAAoB;IACpD,8BAA8B,EAAE,mDAAmD;IACnF,wBAAwB,EAAE,OAAO;CACzB,CAAC;AAEX,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,2BAA2B,CAAC,CAAC;AACtF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE;QACvB,IAAI,CAAC,iBAAiB,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACnC,OAAO,IAAI,EAAE,CAAC;QAChB,CAAC;QACD,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC/B,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,GAAG,kBAAkB,EAAE,CAAC,CAAC;QACtD,CAAC;QACD,MAAM,IAAI,EAAE,CAAC;QACb,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,kBAAkB,CAAC,EAAE,CAAC;YAC9D,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAChC,CAAC;QACD,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,KAAK,2BAA2B,EAAE,CAAC;YAC/C,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,UAAU,CAAC,CAAC;YAC/C,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/middleware/rate-limit.d.ts

@@ -0,0 +1,182 @@
+import { type RateLimiterAbstract } from 'rate-limiter-flexible';
+import type { Context, MiddlewareHandler } from 'hono';
+import type { EntitlementService, Principal } from '@antasphere/chassis-contract';
+import type { Env } from '../env.js';
+import type { Logger } from '../logger.js';
+/**
+ * Auth-surface rate limits (ours, not Better Auth's built-in): login, OTP
+ * sends, invitation acceptance, setup attempts, API-key verification
+ * failures. Memory backend per replica by default; Redis when REDIS_URL is
+ * set so limits hold across replicas (Profile B).
+ */
+/** Workspace-creation attempts one person gets per hour; an address gets ten times that. */
+export declare const WORKSPACE_CREATE_PER_PERSON = 60;
+export interface RateLimiters {
+    login: RateLimiterAbstract;
+    otp: RateLimiterAbstract;
+    invitationAccept: RateLimiterAbstract;
+    setup: RateLimiterAbstract;
+    apiKeyFailures: RateLimiterAbstract;
+    /**
+     * CLI connect (`POST /sso/cli-connect`, cloud): per client address, sized by
+     * CLI_CONNECT_IP_LIMIT_PER_15_MIN for a room behind one address (PRDCT-2958,
+     * the lane E verifier's F1: on the login wall, 10 per 15 minutes, the 11th
+     * `<tool> login` of a venue was refused). The exchange token it presents is
+     * one-time and minted by the hub for one person, behind the hub's own walls.
+     */
+    cliConnect: RateLimiterAbstract;
+    /** RFC 7591 dynamic client registration — unauthenticated by design, so tight. */
+    oauthRegister: RateLimiterAbstract;
+    /** OAuth token endpoint — a full connector dance is ~8 requests, so generous. */
+    oauthToken: RateLimiterAbstract;
+    /** The bundled /mcp endpoint — MCP clients are chatty, so generous per IP. */
+    mcp: RateLimiterAbstract;
+    /** Password reset requests — per IP AND per email, tight (abuse + enumeration). */
+    passwordReset: RateLimiterAbstract;
+    /** Full-workspace export — expensive streams, keyed per IP AND per user. */
+    workspaceExport: RateLimiterAbstract;
+    /** Break-glass superadmin recovery — a rare operator action, tight per IP. */
+    breakGlass: RateLimiterAbstract;
+    /**
+     * Workspace creation, the PER-PERSON bucket (key `u:<userId>`) — a rare
+     * human act; on cloud every attempt is a call to the hub, and the cloud
+     * zero-membership session resolves no principal, so the general quota
+     * never sees it. Spent by the handler (api/workspaces.ts) once the caller
+     * is IDENTIFIED — never by an unauthenticated request, never by a method
+     * that is not the POST.
+     */
+    workspaceCreate: RateLimiterAbstract;
+    /**
+     * Workspace creation, the PER-ADDRESS bucket — ten people's worth of the
+     * per-person one, spent only by identified callers the per-person bucket
+     * let through. One colleague can therefore take at most a tenth of it:
+     * an office behind one NAT address is never locked out by one person,
+     * while a farm of accounts behind one address is still bounded.
+     */
+    workspaceCreateAddress: RateLimiterAbstract;
+    /** The unauthenticated OpenAPI document — cheap now that it is a boot-time buffer, but still anonymous. */
+    openapiDoc: RateLimiterAbstract;
+    /**
+     * The demo pass redeem (demo sign-in, self-hosted only): an anonymous
+     * presentation of a sign-in-equivalent secret, so a guessing wall PER
+     * ADDRESS and nothing else — never keyed on the pass, whose legitimate
+     * audience it would cap. Mounted only while DEMO_SIGN_IN is on.
+     */
+    demoRedeem: RateLimiterAbstract;
+    /**
+     * Shared factory riding the same backend (Redis when REDIS_URL is set,
+     * memory otherwise) for buckets sized at runtime — the per-principal
+     * request quota creates one limiter per distinct quota tier through this.
+     */
+    make: (prefix: string, points: number, durationSec: number) => RateLimiterAbstract;
+}
+/**
+ * A tool's own bucket: the three arguments the shared `make` factory is
+ * called with. The store prefix is observable (`rl:<prefix>` in Redis), so a
+ * declaration is the bucket's identity, not only its size.
+ */
+export interface BucketDeclaration {
+    prefix: string;
+    points: number;
+    durationSec: number;
+}
+/**
+ * The chassis buckets plus the TOOL's own (`toolBuckets`, name → declaration),
+ * all built by the same `make`: one store (Redis when REDIS_URL is set, memory
+ * otherwise), one key-prefix scheme. A tool bucket can never take a chassis
+ * bucket's name — the type refuses it.
+ */
+export declare function createRateLimiters<TBucket extends string = never>(env: Pick<Env, 'REDIS_URL'> & Partial<Pick<Env, 'CLI_CONNECT_IP_LIMIT_PER_15_MIN'>>, logger: Logger, toolBuckets?: {
+    [K in TBucket]: K extends keyof RateLimiters ? never : BucketDeclaration;
+}): Promise<RateLimiters & Record<TBucket, RateLimiterAbstract>>;
+/** The client-identity function: what keys a per-IP bucket and the audit rows. */
+export type ClientIpFn = (c: Context) => string;
+/**
+ * Client identity for buckets and audit. x-forwarded-for is only believed
+ * when TRUST_PROXY says a proxy we control sets it; otherwise the socket
+ * address wins and spoofed headers are ignored. We read the RIGHTMOST hop —
+ * the one appended (or set) by the trusted proxy itself; the leftmost is
+ * client-claimed and spoofable whenever the proxy appends rather than
+ * overwrites. Note the compose caveat: without a proxy, Docker NAT can
+ * collapse external clients onto one address — per-IP limits are only as
+ * granular as what the socket sees.
+ */
+export declare function makeClientIp(trustProxy: boolean): ClientIpFn;
+/** 429 with the standard wire shape when the bucket is empty. */
+/**
+ * WHEN a request costs a point.
+ *
+ *  - `arrival` (default): consume before the handler runs. Correct for
+ *    everything whose cost IS the arrival — sending mail, accepting an
+ *    invitation, registering an OAuth client, running setup.
+ *  - `failure`: check the bucket before the handler (an exhausted bucket
+ *    still 429s immediately) but consume only when the handler answered a
+ *    client error. Correct for CREDENTIAL-VERIFICATION walls: on arrival, the
+ *    limiter cannot yet know whether the caller is the account owner, so an
+ *    email-keyed bucket consumed up front lets anyone who knows an address
+ *    spend that account's whole budget and lock its owner out — including on
+ *    the requests the owner themselves gets right. Consuming on failure keeps
+ *    the brute-force wall exactly as tight (a guess is a failure) while a
+ *    legitimate sign-in costs nothing.
+ */
+export interface RateLimitOptions {
+    consumeOn?: 'arrival' | 'failure';
+}
+export declare function rateLimit(limiter: RateLimiterAbstract, clientIp: ClientIpFn, extraKeys?: (c: Context) => Promise<string[]>, options?: RateLimitOptions): MiddlewareHandler;
+/**
+ * Per-email key for OTP sends and password login (per IP AND per email): the
+ * email key keeps per-account protection intact when NAT or a rotating
+ * attacker collapses/expands the IP dimension.
+ */
+export declare function emailKeyOf(c: Context): Promise<string[]>;
+/** Outcome of one quota consume — everything the HTTP layer needs for headers. */
+export interface QuotaDecision {
+    ok: boolean;
+    /** The sustained per-minute limit (what RateLimit-Limit reports). */
+    limit: number;
+    remaining: number;
+    /** Seconds until the sustained window resets. */
+    resetSeconds: number;
+    /** Present when ok=false: seconds the client should wait before retrying. */
+    retryAfterSeconds?: number;
+}
+export interface RequestQuotaService {
+    /** Consume one request for this principal; null = quota disabled (no headers). */
+    consume(principal: Principal): Promise<QuotaDecision | null>;
+}
+/** RateLimit draft headers + the X- legacy mirror; reset values are delta seconds. */
+export declare function quotaHeaderEntries(d: QuotaDecision): Array<[string, string]>;
+/**
+ * Bucket key for the general API quota, derived ONLY from the authenticated
+ * principal — never from a client-supplied header, so a caller can neither
+ * rotate its own bucket nor fill another principal's. Two API keys of the
+ * same user are separate buckets (a leaked key can be throttled/revoked
+ * without starving the owner's other integrations); the same user's session
+ * is a third.
+ */
+export declare function principalBucketKey(p: Principal): string;
+export interface RequestQuotaDeps {
+    entitlements: EntitlementService;
+    /** The shared limiter factory from createRateLimiters — Redis-backed when configured. */
+    make: RateLimiters['make'];
+    logger: Logger;
+}
+/**
+ * Per-principal request quota over the shared rate-limit backend. Two buckets
+ * per principal: a sustained per-minute window (the quota agents budget
+ * against — headers describe this one) and a 1-second spike cap that smooths
+ * thundering herds without burning sustained points on rejected spikes.
+ *
+ * Limits come from EntitlementService.getRequestQuota so a plan-aware edition
+ * varies them per principal; limiter instances are created lazily per
+ * distinct quota size (a product has a handful of plans, not thousands) and
+ * the size is part of the store prefix, so a plan change moves the principal
+ * to a fresh bucket instead of misreading the old counter.
+ *
+ * Failure posture matches the auth-surface limiters: Redis outages fall back
+ * to the per-replica insurance limiter inside `make`; any other backend or
+ * entitlement failure logs and FAILS OPEN (availability over throttling — the
+ * quota is a cost control, not an authz boundary; authz stays fail-closed).
+ */
+export declare function createRequestQuota({ entitlements, make, logger }: RequestQuotaDeps): RequestQuotaService;
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/middleware/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../src/middleware/rate-limit.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,mBAAmB,EACzB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAEvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAClF,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C;;;;;GAKG;AACH,4FAA4F;AAC5F,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAE9C,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,mBAAmB,CAAC;IAC3B,GAAG,EAAE,mBAAmB,CAAC;IACzB,gBAAgB,EAAE,mBAAmB,CAAC;IACtC,KAAK,EAAE,mBAAmB,CAAC;IAC3B,cAAc,EAAE,mBAAmB,CAAC;IACpC;;;;;;OAMG;IACH,UAAU,EAAE,mBAAmB,CAAC;IAChC,kFAAkF;IAClF,aAAa,EAAE,mBAAmB,CAAC;IACnC,iFAAiF;IACjF,UAAU,EAAE,mBAAmB,CAAC;IAChC,8EAA8E;IAC9E,GAAG,EAAE,mBAAmB,CAAC;IACzB,mFAAmF;IACnF,aAAa,EAAE,mBAAmB,CAAC;IACnC,4EAA4E;IAC5E,eAAe,EAAE,mBAAmB,CAAC;IACrC,8EAA8E;IAC9E,UAAU,EAAE,mBAAmB,CAAC;IAChC;;;;;;;OAOG;IACH,eAAe,EAAE,mBAAmB,CAAC;IACrC;;;;;;OAMG;IACH,sBAAsB,EAAE,mBAAmB,CAAC;IAC5C,2GAA2G;IAC3G,UAAU,EAAE,mBAAmB,CAAC;IAChC;;;;;OAKG;IACH,UAAU,EAAE,mBAAmB,CAAC;IAChC;;;;OAIG;IACH,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,mBAAmB,CAAC;CACpF;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,SAAS,MAAM,GAAG,KAAK,EACrE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,iCAAiC,CAAC,CAAC,EACnF,MAAM,EAAE,MAAM,EACd,WAAW,CAAC,EAAE;KAAG,CAAC,IAAI,OAAO,GAAG,CAAC,SAAS,MAAM,YAAY,GAAG,KAAK,GAAG,iBAAiB;CAAE,GACzF,OAAO,CAAC,YAAY,GAAG,MAAM,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAgD9D;AAED,kFAAkF;AAClF,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,EAAE,OAAO,KAAK,MAAM,CAAC;AAEhD;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,OAAO,GAAG,UAAU,CAc5D;AAED,iEAAiE;AACjE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;CACnC;AAMD,wBAAgB,SAAS,CACvB,OAAO,EAAE,mBAAmB,EAC5B,QAAQ,EAAE,UAAU,EACpB,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,EAC7C,OAAO,GAAE,gBAAqB,GAC7B,iBAAiB,CAwCnB;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAU9D;AAID,kFAAkF;AAClF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAClC,kFAAkF;IAClF,OAAO,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;CAC9D;AAED,sFAAsF;AACtF,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,aAAa,GAAG,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAY5E;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM,CAIvD;AAED,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,kBAAkB,CAAC;IACjC,yFAAyF;IACzF,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,gBAAgB,GAAG,mBAAmB,CAyFxG"}