tapimo 0.0.2 → 0.2.0

package/dist/internal/Auth.js

@@ -1,21 +1,154 @@
+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 { Credential } from 'mppx';
 import { Mppx, tempo } from 'mppx/hono';
-import * as ApiKeySource from '../ApiKeySource.js';
+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 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 +188,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,17 +226,24 @@ 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).
     // Resolution is cached per isolate by default (positive 60s / negative 10s,
-    // keyed by token sha256 — see `ApiKeySource.cached`) so hot keys skip the
-    // backend read on the auth path of every request. Pass `apiKey.cache: false`
-    // when instant revocation matters more than the per-request read.
-    const source = (() => {
-        if (options.apiKey === false || !options.apiKey?.source)
-            return ApiKeySource.noop;
-        if (options.apiKey.cache === false)
-            return options.apiKey.source;
-        return ApiKeySource.cached(options.apiKey.source, options.apiKey.cache);
+    // keyed by token sha256) so hot keys skip the backend read on the auth path
+    // of every request. Pass `apiKey.cache: false` when instant revocation
+    // matters more than the per-request read.
+    const resolve = (() => {
+        const uncached = (c, token) => {
+            const kv = contextKv(c);
+            return kv ? ApiKeys.resolve(kv.store, token) : Promise.resolve(null);
+        };
+        if (options.apiKey === false || options.apiKey?.cache === false)
+            return uncached;
+        return cachedResolve(uncached, options.apiKey?.cache ?? {});
     })();
     const auth = {
         ...(options.apiKey === false
@@ -86,7 +251,7 @@ export function middleware(options) {
             : {
                 apiKey: {
                     ...(options.apiKey?.rateLimits ? { rateLimits: options.apiKey.rateLimits } : {}),
-                    source,
+                    resolve,
                 },
             }),
         ...(options.mpp === false
@@ -99,6 +264,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);
@@ -113,6 +282,220 @@ 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, ttl } = (typeof options_session === 'object' ? options_session.wallet : undefined) ?? {};
+        const handler = Accounts.Handler.auth({
+            ...(issuer ? { identity: { issuer } } : {}),
+            // 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 describe = OpenApi.describeRoute({ hide: true });
+        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',
+        }), 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.'),
+                401: handlerError('Signature or identity verification failed.'),
+                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_public, 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());
@@ -137,21 +520,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;
@@ -160,18 +536,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_) {
@@ -207,6 +585,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)
@@ -243,8 +628,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();
@@ -263,10 +648,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;
@@ -276,8 +662,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;
 }
@@ -329,13 +717,30 @@ export function require(policy) {
             });
         const hasPayment = hasPaymentCredential(c) && isPaymentEnabled(auth, policy);
         if (credential) {
-            const apiKey = await auth.apiKey?.source.resolve(credential.token);
-            if (!apiKey)
+            // 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) {
+                // 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
@@ -354,6 +759,14 @@ export function require(policy) {
                     c.set('chainId', Viem.chainId.testnet);
                 const principal = principalFromApiKey(apiKey);
                 c.set('principal', principal);
+                // 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)) ?? []);
@@ -399,6 +812,16 @@ export function require(policy) {
                 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();
+            }
+        }
         const publicPrincipal = principalFromPublic(c);
         if (hasPayment) {
             c.set('principal', publicPrincipal);
@@ -446,16 +869,55 @@ 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 Cloudflare Durable Object overload is an expected
+        // degradation (a slow/hot counter backend), logged at warn so it stays out
+        // of error dashboards; an unexpected store throw is a genuine error.
+        if (error instanceof RateLimitTimeoutError || isDurableObjectOverload(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 isDurableObjectOverload(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'overloaded' in error &&
+        error.overloaded === true);
+}
+/**
+ * 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
@@ -566,6 +1028,7 @@ function principalFromApiKey(apiKey) {
         environment: apiKey.environment,
         id: apiKey.id,
         orgId: apiKey.orgId,
+        ...(apiKey.projectId === undefined ? {} : { projectId: apiKey.projectId }),
         type: 'api_key',
     };
 }
@@ -615,4 +1078,80 @@ function setRateLimitHeaders(c, result) {
     c.header('RateLimit-Remaining', String(result.remaining));
     c.header('RateLimit-Reset', String(result.reset));
 }
+// Reads the app's KV state store from request context (set by `App.create`
+// from its `kv` option); `undefined` leaves API-key auth closed.
+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;
+/**
+ * Wraps token resolution with a short-TTL per-isolate cache so hot keys skip
+ * the backend read on every request. Positive results cache for `ttl`
+ * (default 60s), negative for `negativeTtl` (default 10s) so a freshly minted
+ * key is usable quickly; concurrent misses for one token are single-flighted.
+ * Entries are keyed by the token's sha256 (`ApiKey.hash`) — never the
+ * plaintext. A revoked key may stay resolvable for up to `ttl` — the accepted
+ * trade-off for removing a backend read from the auth path.
+ */
+function cachedResolve(resolve, options) {
+    const { negativeTtl = 10_000, now = Date.now, ttl = 60_000 } = options;
+    const cells = new Map();
+    const flights = new Map();
+    return async (c, token) => {
+        // Versioned so a future record-shape change can't serve stale shapes.
+        const key = `v1:${ApiKey.hash(token)}`;
+        const cell = cells.get(key);
+        if (cell && cell.expiresAt > now())
+            return cell.value;
+        if (cell)
+            cells.delete(key);
+        const existing = flights.get(key);
+        if (existing)
+            return existing;
+        const flight = (async () => {
+            const value = await resolve(c, token);
+            // Bound the cache: random invalid tokens each add a (negative) entry,
+            // so sweep expired cells at the cap and then drop the oldest.
+            if (cells.size >= cachedMaxEntries) {
+                const time = now();
+                for (const [name, entry] of cells)
+                    if (entry.expiresAt <= time)
+                        cells.delete(name);
+                while (cells.size >= cachedMaxEntries)
+                    cells.delete(cells.keys().next().value);
+            }
+            cells.set(key, { expiresAt: now() + (value ? ttl : negativeTtl), value });
+            return value;
+        })();
+        flights.set(key, flight);
+        try {
+            return await flight;
+        }
+        finally {
+            flights.delete(key);
+        }
+    };
+}
+/** 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