tapimo 0.1.0 → 0.3.0

package/dist/internal/Auth.js

@@ -1,21 +1,156 @@
+import * as Accounts from 'accounts/server';
+import { Hono } from 'hono';
 import { createMiddleware } from 'hono/factory';
 import { matchedRoutes } from 'hono/route';
 import { findTargetHandler } from 'hono/utils/handler';
+import { decodeJwt } from 'jose';
 import { Credential } from 'mppx';
 import { Mppx, tempo } from 'mppx/hono';
+import * as z from 'zod/mini';
 import * as ApiKey from '../ApiKey.js';
 import * as ApiKeys from '../ApiKeys.js';
+import * as Db from '../db/Db.js';
+import * as Invitations from '../db/tables/invitations.js';
+import * as Memberships from '../db/tables/memberships.js';
+import * as Metadata from '../apps/metadata.js';
 import * as OpenApi from './OpenApi.js';
+import * as Organizations from '../db/tables/organizations.js';
+import * as Projects from '../db/tables/projects.js';
 import * as RateLimit from './RateLimit.js';
 import * as Response from './Response.js';
 import * as Schema from './Schema.js';
 import * as Scope from '../Scope.js';
+import * as Users from '../db/tables/users.js';
 import * as Viem from './Viem.js';
 const policySymbol = Symbol('tempo-api.auth.policy');
 /** Reads the authenticated principal from a Hono context. */
 export function getPrincipal(c) {
     return c.get('principal') ?? null;
 }
+/**
+ * Guards org-scoped routes (`:orgId`). Sessions reach only organizations they
+ * are members of; the super admin reaches any. Missing or foreign
+ * organizations return `404`, so foreign org ids are indistinguishable from
+ * absent ones; a member below the required role gets `403` (the resource is
+ * visible to them, the action is not). The resolved organization and
+ * membership land on context — read them with {@link org} and
+ * {@link membership}.
+ */
+export function ensureOrg(options = {}) {
+    const { role: minimum = 'member' } = options;
+    // Typed loosely (like {@link policy}) so route chains keep their inferred
+    // schema; a concrete environment parameter collapses Hono's inference.
+    return createMiddleware(async (c, next) => {
+        const notFound = () => Response.error(c, {
+            code: 'organization_not_found',
+            message: 'Organization not found',
+            status: 404,
+        });
+        const orgId = c.req.param('orgId');
+        if (!orgId)
+            return notFound();
+        const principal = getPrincipal(c);
+        if (principal?.type !== 'session' && principal?.type !== 'super_admin')
+            return notFound();
+        const db = Db.get(contextDb(c));
+        const record = await Organizations.get(db, orgId);
+        if (!record)
+            return notFound();
+        if (principal.type !== 'super_admin') {
+            const member = await Memberships.get(db, orgId, principal.id);
+            if (!member)
+                return notFound();
+            if (Memberships.rank[member.role] < Memberships.rank[minimum])
+                return Response.error(c, {
+                    code: 'forbidden',
+                    message: `Requires the ${minimum} role`,
+                    status: 403,
+                });
+            c.set('membership', member);
+        }
+        c.set('org', record);
+        await next();
+        return undefined;
+    });
+}
+/**
+ * Guards project-scoped routes (`:projectId`) nested under {@link ensureOrg},
+ * which must run first. Projects resolve only within the scoped organization;
+ * missing or cross-org projects return `404`. The resolved project lands on
+ * context — read it with {@link project}.
+ */
+export function ensureProject() {
+    // Typed loosely (like {@link policy}) so route chains keep their inferred
+    // schema; a concrete environment parameter collapses Hono's inference.
+    return createMiddleware(async (c, next) => {
+        const notFound = () => Response.error(c, {
+            code: 'project_not_found',
+            message: 'Project not found',
+            status: 404,
+        });
+        const projectId = c.req.param('projectId');
+        if (!projectId)
+            return notFound();
+        const scoped = c.get('org');
+        if (!scoped)
+            return notFound();
+        const record = await Projects.get(Db.get(contextDb(c)), projectId);
+        if (!record || record.orgId !== scoped.id)
+            return notFound();
+        c.set('project', record);
+        await next();
+        return undefined;
+    });
+}
+/**
+ * Always false at runtime, but typed as `boolean` so handlers can include a
+ * never-reached scope-error branch in Hono's inferred response union (the
+ * ensure middlewares produce these `404`s before the handler runs).
+ */
+export const narrowScope = false;
+/** Typed org-scope error response for Hono client inference. Never reached at runtime. */
+export function ensureOrgError(c) {
+    return Response.error(c, {
+        code: 'organization_not_found',
+        message: 'Organization not found',
+        status: 404,
+    });
+}
+/** Typed project-scope error response for Hono client inference. Never reached at runtime. */
+export function ensureProjectError(c) {
+    // Project routes run the org scope first, so either not-found can surface.
+    const code = c.req.header('tempo-narrow-scope-code') === 'organization_not_found'
+        ? 'organization_not_found'
+        : 'project_not_found';
+    return Response.error(c, {
+        code,
+        message: 'Project not found',
+        status: 404,
+    });
+}
+/** Reads the caller's membership resolved by {@link ensureOrg}; `undefined` for `super_admin`. */
+export function membership(c) {
+    return c.get('membership');
+}
+/** Reads the organization resolved by {@link ensureOrg}; throws when the middleware did not run. */
+export function org(c) {
+    const record = c.get('org');
+    if (!record)
+        throw new Error('`orgScope` middleware must run before reading the organization');
+    return record;
+}
+/** Reads the project resolved by {@link ensureProject}; throws when the middleware did not run. */
+export function project(c) {
+    const record = c.get('project');
+    if (!record)
+        throw new Error('`projectScope` middleware must run before reading the project');
+    return record;
+}
+// Reads the app's database source from request context (set by `App.create`
+// from its `db` option).
+function contextDb(c) {
+    return c.get('db');
+}
 /**
  * Always false at runtime, but typed as `boolean` so handlers can include a
  * never-reached access-error branch in Hono's inferred response union.
@@ -55,6 +190,31 @@ export function accessError(c) {
         status: 429,
     });
 }
+/** Typed lane-less policy error response for Hono client inference. Never reached at runtime. */
+export function superAdminAccessError(c) {
+    const status = Number(c.req.header('tempo-narrow-access-status'));
+    if (status === 400)
+        return Response.error(c, {
+            code: 'api_key_malformed',
+            message: 'Malformed API key',
+            status: 400,
+        });
+    if (status === 401) {
+        const code = c.req.header('tempo-narrow-access-code') === 'api_key_missing'
+            ? 'api_key_missing'
+            : 'api_key_invalid';
+        return Response.error(c, {
+            code,
+            message: 'Missing or invalid API key',
+            status: 401,
+        });
+    }
+    return Response.error(c, {
+        code: 'forbidden',
+        message: 'API key not permitted for this route',
+        status: 403,
+    });
+}
 /** Typed auth/payment error response for Hono client inference. Never reached at runtime. */
 export function paidAccessError(c) {
     const status = Number(c.req.header('tempo-narrow-access-status'));
@@ -68,7 +228,9 @@ export function paidAccessError(c) {
 export function middleware(options) {
     const { charge = {}, ...mpp } = options.mpp === false ? {} : (options.mpp ?? {});
     const defaults = laneDefaults(options);
-    const base = basePolicy(options, defaults);
+    // Default-deny: no lanes open until a route grants them via `policy`.
+    // Otherwise the `super_admin` principal bypasses lane checks entirely.
+    const base = {};
     // Keys resolve against the app's KV state store on request context
     // (`App.create({ kv })`), so the middleware needs no storage wiring; when no
     // store is configured, every token resolves to `null` (closed).
@@ -94,6 +256,10 @@ export function middleware(options) {
                     resolve,
                 },
             }),
+        // The throttle ceiling for sandbox keys without active billing, so
+        // API-key-only routes (no per-route `policy.public`) still fall back to the
+        // deployment's configured public quota.
+        publicRateLimit: defaults.public.rateLimit,
         ...(options.mpp === false
             ? {}
             : {
@@ -104,6 +270,10 @@ export function middleware(options) {
                 }),
             }),
         rateLimit: RateLimit.memory(options.rateLimit),
+        ...(options.session ? { session: options.session } : {}),
+        ...(options.superAdmin?.secret
+            ? { superAdmin: { tokenHash: ApiKey.hash(options.superAdmin.secret) } }
+            : {}),
     };
     return createMiddleware((c, next) => {
         const route = openApiRoute(c);
@@ -118,6 +288,266 @@ export function middleware(options) {
         return require(endpointPolicy)(c, next);
     });
 }
+/** Zod schemas documenting the session sign-in surface (`/v1/auth/siwe`). */
+var schema;
+(function (schema) {
+    const siweMessage = 'api.tempo.xyz wants you to sign in with your Ethereum account:\n0x0000000000000000000000000000000000000000\n\nURI: https://api.tempo.xyz\nVersion: 1\nChain ID: 0\nNonce: 3D0sZfnHqTBmc9tKR\nIssued At: 2026-01-01T00:00:00.000Z\nExpiration Time: 2026-01-01T00:10:00.000Z';
+    /** Error body returned by the sign-in handler (SDK shape, not the API error envelope). */
+    schema.HandlerError = z.object({
+        error: z
+            .string()
+            .check(z.describe('Human-readable failure reason.'), z.meta({ examples: ['domain mismatch'] })),
+        issues: z
+            .optional(z.array(z.unknown()))
+            .check(z.describe('Field-level validation issues, present on request-schema failures.')),
+    });
+    /** Schemas for `POST /v1/auth/siwe/challenge`. */
+    let challenge;
+    (function (challenge) {
+        /** Request body. Accepted fields beyond this document pass through to the SDK handler. */
+        challenge.Body = z.object({});
+        /** Response body. */
+        challenge.Response = z.object({
+            message: z
+                .string()
+                .check(z.describe('Single-use EIP-4361 (SIWE) message to sign and submit for verification.'), z.meta({ examples: [siweMessage] })),
+        });
+    })(challenge = schema.challenge || (schema.challenge = {}));
+    /** Schemas for `POST /v1/auth/siwe` (verify). */
+    let verify;
+    (function (verify) {
+        /** Request body. */
+        verify.Body = z.object({
+            address: z
+                .string()
+                .check(z.describe('Wallet address that signed the message; becomes the session subject.'), z.meta({ examples: ['0x0000000000000000000000000000000000000001'] })),
+            idToken: z.optional(z.string()).check(z.describe('Wallet-minted OIDC identity token (JWT) asserting a verified email, folded onto the session.'), // prettier-ignore
+            z.meta({ examples: ['eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIweDAwMDAifQ.c2lnbmF0dXJl'] })),
+            keyAuthorization: z.optional(z.string()).check(z.describe('RLP-serialized signed key authorization (TIP-1053) whose witness binds this message; verification recovers over its digest.'), // prettier-ignore
+            z.meta({ examples: [`0x${'aa'.repeat(60)}`] })),
+            message: z
+                .string()
+                .check(z.describe('The exact challenge message issued by `POST /v1/auth/siwe/challenge`.'), z.meta({ examples: [siweMessage] })),
+            returnToken: z.optional(z.boolean()).check(z.describe('Return the session token in the body instead of setting the session cookie.'), // prettier-ignore
+            z.meta({ examples: [true] })),
+            signature: z
+                .string()
+                .check(z.describe('Signature over the challenge message (or the key-authorization digest).'), z.meta({ examples: [`0x${'aa'.repeat(65)}`] })),
+        });
+        /** Response body. */
+        verify.Response = z.object({
+            token: z
+                .optional(z.string())
+                .check(z.describe('Bearer session token; present only when `returnToken` is true.'), z.meta({ examples: ['aa'.repeat(32)] })),
+        });
+    })(verify = schema.verify || (schema.verify = {}));
+})(schema || (schema = {}));
+/** `{ error }` response for a sign-in handler failure status. */
+function handlerError(description) {
+    return {
+        content: { 'application/json': { schema: OpenApi.resolver(schema.HandlerError) } },
+        description,
+    };
+}
+/**
+ * Builds the built-in auth pieces from `App.create`'s `auth` option: the
+ * session-surface app to mount (when `session` is configured) and the
+ * enforcement middleware, wired with the surface's resolver. `auth: false`
+ * disables both.
+ */
+export function install(options) {
+    const { db, kv } = options;
+    const { session: options_session, ...options_middleware } = options.auth === false ? {} : (options.auth ?? {});
+    if (options_session && !kv)
+        throw new Error('`auth.session` requires the `kv` state store: sessions and sign-in challenges persist there.'); // prettier-ignore
+    // Session sign-in surface (challenge, verify, logout — SIWE wallet sign-in
+    // today) plus the capability the session lane resolves through. Public but
+    // policy-gated: the hidden describeRoute engages the middleware for the
+    // mounted sub-app, and the public lane rate-limits challenge-store writes.
+    const app = (() => {
+        if (!options_session || !kv)
+            return undefined;
+        const { issuer, origin, requireEmail, ttl } = (typeof options_session === 'object' ? options_session.wallet : undefined) ?? {};
+        // Case-insensitive exact-match email-domain allowlist for new-user sign-ups.
+        const emailAllowlist = (typeof options_session === 'object' ? options_session.emailAllowlist : undefined)
+            ?.map((domain) => domain.trim().toLowerCase())
+            .filter(Boolean);
+        const handler = Accounts.Handler.auth({
+            ...(issuer || requireEmail
+                ? { identity: { ...(issuer ? { issuer } : {}), ...(requireEmail ? { required: true } : {}) } } // prettier-ignore
+                : {}),
+            // Sign-in upserts the `users` row keyed by address.
+            onAuthenticate: async ({ address }) => {
+                await Users.upsertByAddress(Db.get(db), { address });
+            },
+            // No pinned origin: on Workers the edge proxy headers are trustworthy, so
+            // opt in explicitly (the SDK's guard ignores its own Workers default).
+            // Off-Workers the SDK keeps throwing until `wallet.origin` is set.
+            ...(origin
+                ? { origin }
+                : globalThis.navigator?.userAgent === 'Cloudflare-Workers'
+                    ? { trustProxy: true }
+                    : {}),
+            // The app's KV store under the SDK's Kv contract: JSON values,
+            // second-based TTLs, `auth:`-prefixed keys disjoint from API-key
+            // records. `take` is omitted; the SDK falls back to get+delete.
+            store: {
+                async delete(key) {
+                    await kv.store.delete(`auth:${key}`);
+                },
+                async get(key) {
+                    const value = await kv.store.get(`auth:${key}`);
+                    return value === null ? undefined : JSON.parse(value);
+                },
+                async set(key, value, options) {
+                    await kv.store.put(`auth:${key}`, JSON.stringify(value), options?.ttl ? { ttl: options.ttl * 1_000 } : {});
+                },
+            },
+            ...(ttl ? { ttl } : {}),
+        });
+        const session = {
+            resolve: async (c) => {
+                const payload = await handler.getSession(c.req.raw);
+                if (!payload)
+                    return null;
+                const database = Db.get(db);
+                const user = await Users.getByAddress(database, payload.address);
+                if (!user)
+                    return null;
+                // Fold a newly verified email onto the user row: identity tokens are
+                // optional per sign-in, so the column fills lazily.
+                if (payload.email && user.email !== payload.email)
+                    await Users.setEmail(database, user.id, payload.email);
+                const email = payload.email ?? user.email ?? undefined;
+                return {
+                    ...(email ? { email } : {}),
+                    id: user.id,
+                    identity: { provider: 'wallet', subject: payload.address },
+                    type: 'session',
+                };
+            },
+        };
+        const policy_public = policy({ public: true });
+        const policy_session = policy({ public: true, session: true });
+        const describe = OpenApi.describeRoute({ hide: true });
+        // Sign-up gate: new addresses need an allowlisted identity email domain
+        // or a pending invitation; existing users pass. The claim decodes
+        // unverified; the mounted handler verifies the token before any session
+        // or user is created, so a forged claim never authenticates.
+        const gate_signup = createMiddleware(async (c, next) => {
+            if (!emailAllowlist?.length)
+                return next();
+            const { address, idToken } = (await c.req.json());
+            const database = Db.get(db);
+            const user = await Users.getByAddress(database, address);
+            if (!user) {
+                const email = (() => {
+                    if (!idToken)
+                        return undefined;
+                    try {
+                        const { email } = decodeJwt(idToken);
+                        return typeof email === 'string' ? email.toLowerCase() : undefined;
+                    }
+                    catch {
+                        return undefined;
+                    }
+                })();
+                const allowed = await (async () => {
+                    if (!email)
+                        return false;
+                    const at = email.lastIndexOf('@');
+                    if (at > 0 && emailAllowlist.includes(email.slice(at + 1)))
+                        return true;
+                    // A pending invitation admits the email regardless of domain.
+                    return (await Invitations.listByEmail(database, email)).length > 0;
+                })();
+                if (!allowed)
+                    return c.json({ error: 'sign-ups are restricted to approved email domains or invited emails' }, 403); // prettier-ignore
+            }
+            return next();
+        });
+        const app = new Hono()
+            .use('/v1/auth/siwe', policy_public, describe)
+            .use('/v1/auth/siwe/*', policy_public, describe);
+        // Documented operations: pre-routes carrying the OpenAPI metadata and the
+        // envelope-shaped body validation; the mounted handler owns behavior.
+        // Statement form keeps them off the app type (`hc` surface).
+        app.post('/v1/auth/siwe/challenge', policy_public, OpenApi.validate('json', schema.challenge.Body, {
+            code: 'body_invalid',
+            message: 'Invalid request body',
+        }), OpenApi.describeRoute({
+            description: 'Issues a single-use SIWE challenge message to sign. The challenge expires after a short TTL.',
+            // Overrides the surface-wide hidden mount guard for this documented route.
+            hide: false,
+            operationId: 'createSiweChallenge',
+            responses: {
+                200: {
+                    content: { 'application/json': { schema: OpenApi.resolver(schema.challenge.Response) } }, // prettier-ignore
+                    description: 'The challenge message to sign.',
+                    headers: { ...OpenApi.successHeaders },
+                },
+                400: OpenApi.standardError(400, 'Malformed request body.', ['body_invalid']),
+                429: OpenApi.standardError(429, 'Rate limited.'),
+                500: OpenApi.standardError(500, 'Internal server error.'),
+            },
+            summary: 'Create challenge (SIWE)',
+            tags: ['Authentication'],
+        }));
+        app.post('/v1/auth/siwe', policy_public, OpenApi.validate('json', schema.verify.Body, {
+            code: 'body_invalid',
+            message: 'Invalid request body',
+        }), gate_signup, OpenApi.describeRoute({
+            description: 'Verifies the signed challenge and establishes a session. Sets a session cookie by default; pass `returnToken` to receive a bearer token instead.',
+            hide: false,
+            operationId: 'verifySiwe',
+            responses: {
+                200: {
+                    content: { 'application/json': { schema: OpenApi.resolver(schema.verify.Response) } },
+                    description: 'Session established. Cookie mode sets `Set-Cookie`; token mode returns `token`.', // prettier-ignore
+                    headers: {
+                        ...OpenApi.successHeaders,
+                        'Set-Cookie': {
+                            description: 'Session cookie (`accounts_auth`); omitted when `returnToken` is true.', // prettier-ignore
+                            schema: { type: 'string' },
+                        },
+                    },
+                },
+                400: handlerError('Invalid, expired, or mismatched challenge message; or a required identity token is missing.'), // prettier-ignore
+                401: handlerError('Signature or identity verification failed.'),
+                ...(emailAllowlist?.length
+                    ? { 403: handlerError('Sign-up rejected: the identity email is neither on an allowlisted domain nor pending an invitation.') } // prettier-ignore
+                    : {}),
+                409: handlerError('Challenge nonce already used or unknown.'),
+                429: OpenApi.standardError(429, 'Rate limited.'),
+                500: OpenApi.standardError(500, 'Internal server error.'),
+            },
+            summary: 'Authenticate (SIWE)',
+            tags: ['Authentication'],
+        }));
+        app.post('/v1/auth/siwe/logout', policy_session, OpenApi.describeRoute({
+            description: 'Revokes the current session and clears the session cookie.',
+            hide: false,
+            operationId: 'siweLogout',
+            responses: {
+                204: { description: 'Session revoked and cookie cleared.' },
+                429: OpenApi.standardError(429, 'Rate limited.'),
+                500: OpenApi.standardError(500, 'Internal server error.'),
+            },
+            summary: 'Sign out',
+            tags: ['Authentication'],
+        }));
+        return Object.assign(
+        // The tag joins the `Platform API` group at `platform()`'s chosen slot;
+        // group listings filter to defined tags, so it drops out when unmounted.
+        Metadata.attach(app.route('/v1/auth/siwe', handler), {
+            tags: [{ name: 'Authentication', description: 'Authenticate into the Tempo Platform.' }],
+        }), { session });
+    })();
+    const middleware_ = options.auth === false
+        ? undefined
+        : middleware({ ...options_middleware, ...(app ? { session: app.session } : {}) });
+    return { app, middleware: middleware_ };
+}
 /** Creates route middleware that contributes an auth policy override. */
 export function policy(options) {
     const middleware = createMiddleware((_, next) => next());
@@ -142,21 +572,14 @@ function laneDefaults(options) {
         },
         mpp: { charge: {} },
         public: { rateLimit: public_?.rateLimit ?? { perMinute: 60 } },
+        session: true,
     };
 }
-/**
- * Base policy before route overrides. Default-closed except the API-key lane:
- * a route that declares nothing is API-key-only, and must opt into the public
- * and paid lanes explicitly. This makes a partial override fail safe — omitting
- * a lane leaves it closed rather than silently inheriting open access.
- */
-function basePolicy(options, defaults) {
-    return options.apiKey === false ? {} : { apiKey: defaults.apiKey };
-}
 function resolvePolicy(base, defaults, overrides, description) {
     let apiKey = base.apiKey;
     let mpp = base.mpp;
     let public_ = base.public;
+    let session = base.session;
     for (const override of overrides) {
         if (override === false)
             return undefined;
@@ -165,18 +588,20 @@ function resolvePolicy(base, defaults, overrides, description) {
         apiKey = resolveApiKeyLane(apiKey, override.apiKey, defaults.apiKey);
         mpp = resolveMppLane(mpp, override.mpp, defaults.mpp);
         public_ = resolvePublicLane(public_, override.public, defaults.public);
+        session = resolveSessionLane(session, override.session, defaults.session);
     }
     // The OpenAPI summary/description rides along as the payment-challenge
     // description. It is metadata, not a policy override, so it only applies when
     // the paid lane is actually enabled and has no explicit description already.
     if (mpp && description !== undefined && mpp.charge.description === undefined)
         mpp = { charge: { ...mpp.charge, description } };
-    if (!apiKey && !mpp && !public_)
-        return undefined;
+    // A lane-less policy stays enforced for super admin; only an explicit
+    // `false` override opts a route out of auth entirely.
     return {
         ...(apiKey ? { apiKey } : {}),
         ...(mpp ? { mpp } : {}),
         ...(public_ ? { public: public_ } : {}),
+        ...(session ? { session } : {}),
     };
 }
 function resolveApiKeyLane(current, override, default_) {
@@ -212,6 +637,13 @@ function resolvePublicLane(current, override, default_) {
     const base = current ?? default_;
     return { rateLimit: override.rateLimit ?? base.rateLimit };
 }
+function resolveSessionLane(current, override, default_) {
+    if (override === undefined)
+        return current;
+    if (override === false)
+        return undefined;
+    return current ?? default_;
+}
 function openApiRoute(c) {
     const route = matchedRoutes(c)
         .slice(c.req.routeIndex + 1)
@@ -248,8 +680,8 @@ function policyFromRoute(route) {
  * Maps each documented operation id to its resolved access lanes by reading the
  * `policy` overrides co-located on the app's routes. This is the single source
  * of truth for per-operation `security` and the `402` response in the generated
- * OpenAPI document (see `App.create`): the API-key lane is default-on, and the
- * public/MPP lanes apply only where a route opts in via {@link policy}.
+ * OpenAPI document (see `App.create`): all lanes are default-closed, and an
+ * operation surfaces only the lanes its route opts into via {@link policy}.
  */
 export function describeAccess(app) {
     const groups = new Map();
@@ -268,10 +700,11 @@ export function describeAccess(app) {
     for (const { operationId, overrides } of groups.values()) {
         if (!operationId)
             continue;
-        let apiKey = true;
+        let apiKey = false;
         let scopes = [];
         let public_ = false;
         let mpp = false;
+        let session = false;
         for (const override of overrides) {
             if (override.apiKey !== undefined)
                 apiKey = override.apiKey !== false;
@@ -281,8 +714,10 @@ export function describeAccess(app) {
                 public_ = override.public !== false;
             if (override.mpp !== undefined)
                 mpp = override.mpp !== false;
+            if (override.session !== undefined)
+                session = override.session !== false;
         }
-        access[operationId] = { mpp, public: public_, scopes: apiKey ? scopes : [] };
+        access[operationId] = { apiKey, mpp, public: public_, scopes: apiKey ? scopes : [], session };
     }
     return access;
 }
@@ -334,73 +769,122 @@ export function require(policy) {
             });
         const hasPayment = hasPaymentCredential(c) && isPaymentEnabled(auth, policy);
         if (credential) {
+            // The super admin secret precedes key lookup: it is not a stored key.
+            // It must never reach KV resolution or scope/quota checks.
+            if (auth.superAdmin && ApiKey.hash(credential.token) === auth.superAdmin.tokenHash) {
+                c.set('principal', { actor: 'super_admin', id: 'super_admin', type: 'super_admin' });
+                return next();
+            }
             const apiKey = await auth.apiKey?.resolve(c, credential.token);
-            if (!apiKey)
+            if (!apiKey) {
+                // A bearer session token is indistinguishable from an API key at the
+                // header, so a failed key lookup falls through to the session lane
+                // before rejecting.
+                if (policy.session) {
+                    const session = await resolveSession(c, auth);
+                    if (session) {
+                        c.set('principal', session);
+                        return next();
+                    }
+                }
                 return jsonError(c, {
                     code: 'api_key_invalid',
                     message: 'Invalid API key',
                     status: 401,
                 });
-            // Sandbox keys are restricted to non-mainnet chains. An explicit
-            // `chainId` of mainnet makes the key unusable for this request, so it is
-            // ignored and the request falls through to the public policy below (as if
-            // no key were presented). A request that omits `chainId` is steered to
-            // testnet so a sandbox key still "just works" without passing `?chainId`.
+            }
+            // Sandbox keys are testnet-only. A sandbox key that explicitly targets
+            // mainnet (`?chainId`) is rejected with a clear message rather than
+            // steered or downgraded to anonymous, so the caller learns their key does
+            // not cover mainnet. The no-`chainId` default (mainnet) is enforced by
+            // the data group's chain guard, which knows the route is chain-scoped;
+            // the relay resolves its chain from the request body and enforces the
+            // same rule in its sponsor validation.
             const explicitChain = explicitChainId(c);
-            const sandboxOnMainnet = apiKey.environment === 'sandbox' &&
+            const principal = principalFromApiKey(apiKey);
+            c.set('principal', principal);
+            if (apiKey.environment === 'sandbox' &&
                 explicitChain !== undefined &&
-                Viem.isMainnet(explicitChain);
-            if (!sandboxOnMainnet) {
-                if (apiKey.environment === 'sandbox' &&
-                    explicitChain === undefined &&
-                    Viem.isMainnet(c.get('chainId') ?? Viem.defaultChainId))
-                    // `chainId` lives on the app's `Variables`, not the narrower auth
-                    // contract, so it is read/written through an untyped cast.
-                    c.set('chainId', Viem.chainId.testnet);
-                const principal = principalFromApiKey(apiKey);
-                c.set('principal', principal);
-                const missing = apiKey.scopes.includes(Scope.wildcard)
-                    ? []
-                    : (policy.apiKey?.scopes.filter((scope) => !apiKey.scopes.includes(scope)) ?? []);
-                if (missing.length > 0)
-                    return jsonError(c, {
-                        code: 'api_key_forbidden',
-                        message: 'API key missing required scope',
-                        status: 403,
-                    });
-                if (hasPayment)
-                    return requirePayment(c, next, {
+                Viem.isMainnet(explicitChain))
+                return jsonError(c, {
+                    code: 'api_key_forbidden',
+                    message: 'Sandbox API keys only support testnet. Pass a testnet `chainId`.',
+                    status: 403,
+                });
+            // Default-deny: routes with no API-key lane allow only the super admin.
+            // A valid key is authenticated but forbidden.
+            if (!policy.apiKey)
+                return jsonError(c, {
+                    code: 'forbidden',
+                    message: 'API key not permitted for this route',
+                    status: 403,
+                });
+            const missing = apiKey.scopes.includes(Scope.wildcard)
+                ? []
+                : (policy.apiKey?.scopes.filter((scope) => !apiKey.scopes.includes(scope)) ?? []);
+            if (missing.length > 0)
+                return jsonError(c, {
+                    code: 'api_key_forbidden',
+                    message: 'API key missing required scope',
+                    status: 403,
+                });
+            // Sandbox keys without active billing are throttled to the public quota.
+            // `billingActive` is snapshotted on the key record (stamped at mint,
+            // re-synced when billing changes), so this needs no billing read on the
+            // request path. Resolved before the paid lane so a payment credential
+            // can't buy past the throttle: sandbox is non-billable testnet.
+            const throttled = apiKey.environment === 'sandbox' && apiKey.billingActive !== true;
+            if (hasPayment && !throttled)
+                return requirePayment(c, next, {
+                    auth,
+                    payment: { reason: 'api_key_over_quota', type: 'mpp' },
+                    policy,
+                    principal,
+                });
+            if (policy.apiKey) {
+                // A route consumes exactly one quota bucket: its single required scope,
+                // else `'*'` (zero scopes). Routes today require at most one scope; a
+                // future multi-scope route buckets against its first scope.
+                const scope = policy.apiKey.scopes[0] ?? Scope.wildcard;
+                // A throttled sandbox key shares the key's bucket but at the public
+                // ceiling, so activating billing lifts the limit on the same counter.
+                const limit = throttled
+                    ? (policy.public?.rateLimit ?? auth.publicRateLimit ?? { perMinute: 60 })
+                    : resolveApiKeyLimit({ apiKey, auth, policy: policy.apiKey, scope });
+                const result = await consumeRateLimit(auth, {
+                    key: `api_key:${apiKey.id}:scope:${scope}`,
+                    limit,
+                });
+                if (result) {
+                    setRateLimitHeaders(c, result);
+                    // Surface the bucket so callers can correlate a 429 with the exhausted
+                    // quota. Set before the over-quota branch so it rides the 429 (an MPP
+                    // 402 challenge is owned by mppx and drops these headers — by design).
+                    c.header('RateLimit-Scope', scope);
+                }
+                if (result && !result.allowed) {
+                    // A throttled sandbox key gets a plain 429, never an MPP challenge —
+                    // it must activate billing to lift the ceiling, not pay per request.
+                    if (throttled)
+                        return rateLimitExceeded(c, result);
+                    return requirePaymentOrRateLimit(c, next, {
                         auth,
                         payment: { reason: 'api_key_over_quota', type: 'mpp' },
                         policy,
                         principal,
+                        rateLimit: result,
                     });
-                if (policy.apiKey) {
-                    // A route consumes exactly one quota bucket: its single required scope,
-                    // else `'*'` (zero scopes). Routes today require at most one scope; a
-                    // future multi-scope route buckets against its first scope.
-                    const scope = policy.apiKey.scopes[0] ?? Scope.wildcard;
-                    const limit = resolveApiKeyLimit({ apiKey, auth, policy: policy.apiKey, scope });
-                    const result = await consumeRateLimit(auth, {
-                        key: `api_key:${apiKey.id}:scope:${scope}`,
-                        limit,
-                    });
-                    if (result) {
-                        setRateLimitHeaders(c, result);
-                        // Surface the bucket so callers can correlate a 429 with the exhausted
-                        // quota. Set before the over-quota branch so it rides the 429 (an MPP
-                        // 402 challenge is owned by mppx and drops these headers — by design).
-                        c.header('RateLimit-Scope', scope);
-                    }
-                    if (result && !result.allowed)
-                        return requirePaymentOrRateLimit(c, next, {
-                            auth,
-                            payment: { reason: 'api_key_over_quota', type: 'mpp' },
-                            policy,
-                            principal,
-                            rateLimit: result,
-                        });
                 }
+            }
+            return next();
+        }
+        // Cookie sessions carry no Authorization credential; resolve the session
+        // lane before the public/paid lanes so signed-in browsers skip anonymous
+        // quotas.
+        if (policy.session) {
+            const session = await resolveSession(c, auth);
+            if (session) {
+                c.set('principal', session);
                 return next();
             }
         }
@@ -451,16 +935,57 @@ export function require(policy) {
         });
     });
 }
+/**
+ * How long to wait for the rate-limit counter before failing open. A hot
+ * counter backend (e.g. a single Durable Object serving one busy quota bucket)
+ * can stall for tens of seconds during a storage-latency blip; without this cap
+ * every request for that bucket blocks on it, turning a localized backend
+ * hiccup into an API-wide latency spike. The abandoned increment still applies
+ * server-side — we just stop waiting for it.
+ */
+const rateLimitConsumeTimeout = 300;
 function consumeRateLimit(auth, options) {
     if (!auth.rateLimit)
         return Promise.resolve(null);
-    // Fail open: a rate-limit store error (e.g. a lost Durable Object
-    // connection) degrades to unenforced quota instead of failing the request.
-    return auth.rateLimit.consume(options).catch((error) => {
-        console.error('[auth] rate-limit consume failed; failing open', error);
+    // Fail open: a rate-limit store error (e.g. a lost Durable Object connection)
+    // or a stall past `rateLimitConsumeTimeout` degrades to unenforced quota
+    // instead of failing — or blocking — the request.
+    return withTimeout(auth.rateLimit.consume(options), rateLimitConsumeTimeout).catch((error) => {
+        // A timeout or transient Durable Object fault is an expected degradation,
+        // logged at warn to stay out of error dashboards; an unexpected store
+        // throw is a genuine error.
+        if (error instanceof RateLimitTimeoutError || isDurableObjectFault(error))
+            console.warn('[auth] rate-limit consume degraded; failing open', error);
+        else
+            console.error('[auth] rate-limit consume failed; failing open', error);
         return null;
     });
 }
+function isDurableObjectFault(error) {
+    const { message, overloaded, retryable } = (error ?? {});
+    if (overloaded === true || retryable === true)
+        return true;
+    // Cloudflare redacts internal Durable Object faults to "internal error;
+    // reference = <token>", with no marker property to detect them by.
+    return typeof message === 'string' && message.startsWith('internal error');
+}
+/**
+ * Rejects with a {@link RateLimitTimeoutError} if `promise` does not settle
+ * within `ms`, clearing the timer on either outcome so it never keeps the
+ * isolate alive.
+ */
+function withTimeout(promise, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new RateLimitTimeoutError(ms)), ms);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
 /**
  * Resolves the rate limit for an API-key request against a quota bucket.
  * Most-specific wins: a per-key per-scope grant is the only thing that pierces a
@@ -571,6 +1096,7 @@ function principalFromApiKey(apiKey) {
         environment: apiKey.environment,
         id: apiKey.id,
         orgId: apiKey.orgId,
+        ...(apiKey.projectId === undefined ? {} : { projectId: apiKey.projectId }),
         type: 'api_key',
     };
 }
@@ -608,7 +1134,11 @@ async function requirePayment(c, next, options) {
 function requirePaymentOrRateLimit(c, next, options) {
     if (isPaymentEnabled(options.auth, options.policy))
         return requirePayment(c, next, options);
-    c.header('Retry-After', String(Math.max(options.rateLimit.reset - Math.ceil(Date.now() / 1_000), 1)));
+    return rateLimitExceeded(c, options.rateLimit);
+}
+/** Emits a `429` with a `Retry-After` derived from the window reset. */
+function rateLimitExceeded(c, result) {
+    c.header('Retry-After', String(Math.max(result.reset - Math.ceil(Date.now() / 1_000), 1)));
     return jsonError(c, {
         code: 'rate_limit_exceeded',
         message: 'Rate limit exceeded',
@@ -625,6 +1155,20 @@ function setRateLimitHeaders(c, result) {
 function contextKv(c) {
     return c.get('kv');
 }
+// Resolve the session lane from the auth context's capability. Failures
+// resolve to `null` so the remaining lanes and the final `401` still apply.
+async function resolveSession(c, auth) {
+    const session = auth.session;
+    if (!session)
+        return null;
+    try {
+        return await session.resolve(c);
+    }
+    catch (error) {
+        console.error('[auth] session resolve failed; treating as no session', error);
+        return null;
+    }
+}
 /** Maximum resolve-cache entries held per isolate before eviction. */
 const cachedMaxEntries = 10_000;
 /**
@@ -675,4 +1219,11 @@ function cachedResolve(resolve, options) {
         }
     };
 }
+/** Thrown when a rate-limit consume exceeds {@link rateLimitConsumeTimeout}. */
+export class RateLimitTimeoutError extends Error {
+    name = 'Auth.RateLimitTimeoutError';
+    constructor(ms) {
+        super(`Rate-limit consume timed out after ${ms}ms; failing open.`);
+    }
+}
 //# sourceMappingURL=Auth.js.map