tapimo 0.14.0 → 0.15.0

package/dist/internal/Auth.js

@@ -1,31 +1,57 @@
 import * as Accounts from 'accounts/server';
+import { splitSetCookieHeader } from 'better-auth/cookies';
 import { Hono } from 'hono';
+import { deleteCookie, getCookie, setCookie } from 'hono/cookie';
 import { createMiddleware } from 'hono/factory';
 import { matchedRoutes } from 'hono/route';
 import { findTargetHandler } from 'hono/utils/handler';
+import * as jose from 'jose';
+import { sql } from 'kysely';
 import { Challenge, Credential } from 'mppx';
 import { Mppx, tempo } from 'mppx/hono';
+import { Address, Hex } from 'ox';
 import { Addresses } from 'viem/tempo';
 import { tempoMainnet } from 'viem/tempo/chains';
 import * as z from 'zod/mini';
 import * as ApiKey from '../ApiKey.js';
 import * as ApiKeys from '../ApiKeys.js';
+import * as ApiKeyAdmissions from '../db/tables/apiKeyAdmissions.js';
+import * as ApiKeyOwnerTombstones from '../db/tables/apiKeyOwnerTombstones.js';
+import * as AuthAccounts from '../db/tables/authAccounts.js';
+import * as BetterAuth from './BetterAuth.js';
 import * as Db from '../db/Db.js';
 import * as Memberships from '../db/tables/memberships.js';
 import * as IpAllowlist from './IpAllowlist.js';
 import * as Metadata from '../apps/metadata.js';
 import * as OpenApi from './OpenApi.js';
 import * as Organizations from '../db/tables/organizations.js';
+import * as Path from './Path.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 Timing from './Timing.js';
 import * as Users from '../db/tables/users.js';
 const policySymbol = Symbol('tempo-api.auth.policy');
 const mppManagementSymbol = Symbol('tempo-api.auth.mpp-management');
 const defaultApiKeyRateLimit = { limit: 10_000, period: 'minute' };
+const defaultIdentitySessionTtl = 24 * 60 * 60;
 const defaultMppRateLimit = { limit: 100, period: 'minute' };
+const defaultPublicRateLimit = { limit: 60, period: 'minute' };
+const identityCookieName = 'tempo_identity';
+const walletIdentityIssuer = 'https://wallet.tempo.xyz/api/oidc';
+function isIdentityTokenError(error) {
+    return (error instanceof jose.errors.JOSEAlgNotAllowed ||
+        error instanceof jose.errors.JOSENotSupported ||
+        error instanceof jose.errors.JWSInvalid ||
+        error instanceof jose.errors.JWKSNoMatchingKey ||
+        error instanceof jose.errors.JWSSignatureVerificationFailed ||
+        error instanceof jose.errors.JWTClaimValidationFailed ||
+        error instanceof jose.errors.JWTExpired ||
+        error instanceof jose.errors.JWTInvalid ||
+        (error instanceof Error && error.message === 'email not verified'));
+}
 /** Reads the authenticated principal from a Hono context. */
 export function getPrincipal(c) {
     return c.get('principal') ?? null;
@@ -265,6 +291,13 @@ export function paidAccessError(c) {
 }
 /** Creates auth middleware for protected OpenAPI routes. */
 export function middleware(options) {
+    const resolve = createApiKeyResolver({
+        apiKey: options.apiKey,
+        scopeCatalog: options.scopeCatalog,
+    });
+    return createAuthMiddleware(options, resolve);
+}
+function createAuthMiddleware(options, resolve) {
     const { rateLimit: mppRateLimit = defaultMppRateLimit, session: session_ = {}, sessionChainIds, ...mpp } = options.mpp === false ? {} : (options.mpp ?? {});
     const secretKey = resolveMppSecretKey(mpp.secretKey);
     const defaults = laneDefaults(options);
@@ -278,24 +311,13 @@ export function middleware(options) {
     // keyed by token sha256) so hot keys skip the backend read on the auth path
     // of every request. Pass `apiKey.cache: false` when immediate key updates
     // matter more than the per-request read.
-    const resolve = (() => {
-        const uncached = (c, token) => {
-            const kv = contextKv(c);
-            return kv
-                ? ApiKeys.resolve(kv.store, token, { scopeCatalog: options.scopeCatalog })
-                : Promise.resolve(null);
-        };
-        if (options.apiKey === false || options.apiKey?.cache === false)
-            return uncached;
-        return cachedResolve(uncached, options.apiKey?.cache ?? {});
-    })();
     const auth = {
         ...(options.apiKey === false
             ? {}
             : {
                 apiKey: {
                     ...(options.apiKey?.rateLimits ? { rateLimits: options.apiKey.rateLimits } : {}),
-                    resolve,
+                    resolve: resolve.resolve,
                 },
             }),
         // The throttle ceiling for sandbox keys without active billing, so
@@ -336,33 +358,90 @@ export function middleware(options) {
             : {}),
     };
     return createMiddleware((c, next) => {
-        const route = openApiRoute(c);
-        if (!route)
+        const resolved = resolveRequestPolicy(c, { base, defaults, options });
+        if (!resolved)
             return next();
-        const { key, description, management, scope } = route;
-        const overrides = options.overrides;
-        const routePolicies = policies(c);
-        const configuredOverride = (() => {
-            const configured = overrides?.[key];
-            if (configured !== undefined)
-                return configured;
-            const inheritedMethod = routePolicies.find((policy) => policy.inheritOverridesFrom)?.inheritOverridesFrom;
-            if (inheritedMethod === undefined)
-                return undefined;
-            const inheritedKey = `${inheritedMethod.toUpperCase()} ${key.slice(key.indexOf(' ') + 1)}`;
-            return overrides?.[inheritedKey];
-        })();
-        const routeOverride = management && configuredOverride ? { mpp: configuredOverride.mpp } : configuredOverride;
-        const endpointPolicy = bindMppScope(resolvePolicy(base, defaults, [...routePolicies, routeOverride], description), scope);
-        if (!endpointPolicy)
+        c.set('auth', auth);
+        if (!resolved.policy)
             return next();
-        if (management && (!auth.mpp || !endpointPolicy.mpp))
+        if (resolved.management && (!auth.mpp || !resolved.policy.mpp))
             return next();
-        c.set('auth', auth);
-        return require(endpointPolicy)(c, next);
+        return require(resolved.policy)(c, next);
     });
 }
-/** Zod schemas documenting the session sign-in surface (`/v1/auth/siwe`). */
+function resolveRequestPolicy(c, options) {
+    const route = openApiRoute(c);
+    if (!route)
+        return undefined;
+    const { key, description, management, scope } = route;
+    const overrides = options.options.overrides;
+    const routePolicies = policies(c);
+    const configuredOverride = (() => {
+        const configured = overrides?.[key];
+        if (configured !== undefined)
+            return configured;
+        const inheritedMethod = routePolicies.find((routePolicy) => routePolicy !== false && routePolicy.inheritOverridesFrom !== undefined)?.inheritOverridesFrom;
+        if (inheritedMethod === undefined)
+            return undefined;
+        const inheritedKey = `${inheritedMethod.toUpperCase()} ${key.slice(key.indexOf(' ') + 1)}`;
+        return overrides?.[inheritedKey];
+    })();
+    const routeOverride = management && configuredOverride ? { mpp: configuredOverride.mpp } : configuredOverride;
+    return {
+        management,
+        policy: bindMppScope(resolvePolicy(options.base, options.defaults, [...routePolicies, routeOverride], description), scope),
+    };
+}
+function createApiKeyResolver(options) {
+    const requests = new WeakMap();
+    const uncached = (c, token) => {
+        const kv = contextKv(c);
+        return kv
+            ? ApiKeys.resolve(kv.store, token, { scopeCatalog: options.scopeCatalog })
+            : Promise.resolve(null);
+    };
+    const cache = options.apiKey === false || options.apiKey?.cache === false
+        ? { invalidate: () => { }, peek: () => undefined, resolve: uncached }
+        : cachedResolve(uncached, options.apiKey?.cache ?? {});
+    return {
+        peek: (c, token) => {
+            const tokenHash = ApiKey.hash(token);
+            const existing = requests.get(c);
+            if (existing?.tokenHash === tokenHash)
+                return existing.apiKey;
+            return cache.peek(token);
+        },
+        resolve: async (c, token) => {
+            const tokenHash = ApiKey.hash(token);
+            const existing = requests.get(c);
+            if (existing?.tokenHash === tokenHash)
+                return existing.apiKey;
+            const cached = await cache.resolve(c, token);
+            const kv = contextKv(c);
+            const apiKey = cached &&
+                ((kv && (await ApiKeys.isOwnerDeleted(kv.store, cached))) ||
+                    !(await apiKeyOwnerExists(cached, options.db)))
+                ? null
+                : cached;
+            if (cached && !apiKey)
+                cache.invalidate(token);
+            requests.set(c, { apiKey, tokenHash });
+            return apiKey;
+        },
+    };
+}
+/** Rejects attributed keys fenced by a committed owner deletion. */
+async function apiKeyOwnerExists(apiKey, source) {
+    if (!source)
+        return true;
+    const db = Db.get(source);
+    if (!(await ApiKeyAdmissions.matches(db, apiKey)))
+        return false;
+    if (await ApiKeyOwnerTombstones.isDeleted(db, apiKey))
+        return false;
+    return true;
+}
+/** Zod schemas documenting the session sign-in surface. */
 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';
@@ -379,19 +458,19 @@ var schema;
     let challenge;
     (function (challenge) {
         /** Request body. Accepted fields beyond this document pass through to the SDK handler. */
-        challenge.Body = z.object({});
+        challenge.Body = OpenApi.component(z.object({}), 'SiweChallengeRequest');
         /** Response body. */
-        challenge.Response = z.object({
+        challenge.Response = OpenApi.component(z.object({
             message: z
                 .string()
                 .check(z.describe('Single-use EIP-4361 (SIWE) message to sign and submit for verification.'), z.meta({ examples: [siweMessage] })),
-        });
+        }), 'SiweChallengeResponse');
     })(challenge = schema.challenge || (schema.challenge = {}));
     /** Schemas for `POST /v1/auth/siwe` (verify). */
     let verify;
     (function (verify) {
         /** Request body. */
-        verify.Body = z.object({
+        verify.Body = OpenApi.component(z.object({
             address: z
                 .string()
                 .check(z.describe('Wallet address that signed the message; becomes the session subject.'), z.meta({ examples: ['0x0000000000000000000000000000000000000001'] })),
@@ -407,14 +486,26 @@ var schema;
             signature: z
                 .string()
                 .check(z.describe('Signature over the challenge message (or the key-authorization digest).'), z.meta({ examples: [`0x${'aa'.repeat(65)}`] })),
-        });
+        }), 'SiweVerifyRequest');
         /** Response body. */
-        verify.Response = z.object({
+        verify.Response = OpenApi.component(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)] })),
-        });
+        }), 'SiweVerifyResponse');
     })(verify = schema.verify || (schema.verify = {}));
+    /** Schemas for `POST /v1/auth/identity`. */
+    let identity;
+    (function (identity) {
+        /** Request body. */
+        identity.Body = OpenApi.component(z.object({
+            idToken: z
+                .string()
+                .check(z.describe('Wallet-issued OpenID Connect identity token.'), z.meta({ examples: ['eyJhbGciOiJFZERTQSJ9.eyJzdWIiOiIweDAwMDAifQ.c2lnbmF0dXJl'] })),
+        }), 'IdentitySignInRequest');
+        /** Response body. */
+        identity.Response = OpenApi.component(z.object({}), 'IdentitySignInResponse');
+    })(identity = schema.identity || (schema.identity = {}));
 })(schema || (schema = {}));
 /** `{ error }` response for a sign-in handler failure status. */
 function handlerError(description) {
@@ -431,17 +522,34 @@ function handlerError(description) {
  */
 export function install(options) {
     const { db, kv, scopeCatalog } = options;
-    const { session: options_session, ...options_middleware } = options.auth === false ? {} : (options.auth ?? {});
+    const { edgeRateLimit: options_edgeRateLimit, session: options_session, ...options_middleware } = options.auth === false ? {} : (options.auth ?? {});
+    const publicClientIp = typeof options_middleware.public === 'object' ? options_middleware.public.clientIp : undefined;
     if (options_session && !kv)
         throw new Error('`auth.session` requires the `kv` state store: sessions and sign-in challenges persist there.'); // prettier-ignore
+    const options_betterAuth = options_session
+        ? {
+            basePath: Path.join(options.basePath, 'v1/auth'),
+            clientIp: (request) => resolveTrustedClientIp(request, publicClientIp),
+            db,
+            get email() {
+                return options.email();
+            },
+            rateLimit: RateLimit.memory(options_middleware.rateLimit),
+            secret: options_session.secret,
+            ...(options_session.google ? { google: options_session.google } : {}),
+            ...(options_session.trustedOrigins
+                ? { trustedOrigins: options_session.trustedOrigins }
+                : {}),
+        }
+        : undefined;
     // 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)
+        if (!options_betterAuth || !options_session || !kv)
             return undefined;
-        const { issuer, origin, requireEmail, ttl } = (typeof options_session === 'object' ? options_session.wallet : undefined) ?? {};
+        const { issuer, origin, requireEmail, ttl } = options_session.wallet ?? {};
         const handler = Accounts.Handler.auth({
             getClient: options.getClient,
             ...(issuer || requireEmail
@@ -476,30 +584,108 @@ export function install(options) {
             },
             ...(ttl ? { ttl } : {}),
         });
+        const identity = options_session.identity;
+        const identitySessionTtl = identity?.ttl ?? defaultIdentitySessionTtl;
+        const identitySessionKey = (token) => `identity:session:${token}`;
+        async function resolveWallet(payload) {
+            const database = Db.get(db);
+            const verifiedEmail = payload.email?.trim().toLowerCase();
+            return database.kysely.transaction().execute(async (kysely) => {
+                const tx = { ...database, kysely };
+                // Organization creation locks the same address row before resolving
+                // the wallet owner, serializing resource writes with reconciliation.
+                const addressUser = await Users.getByAddressForUpdate(tx, payload.address);
+                if (!addressUser)
+                    return null;
+                if (verifiedEmail)
+                    await sql `SELECT pg_advisory_xact_lock(hashtextextended(${verifiedEmail}, 0))`.execute(kysely);
+                const linkedUserId = await AuthAccounts.getWalletUserId(tx, payload.address);
+                const linkedUser = linkedUserId ? await Users.get(tx, linkedUserId) : undefined;
+                const emailUser = verifiedEmail ? await Users.getByEmail(tx, verifiedEmail) : undefined;
+                const walletUser = linkedUser ?? addressUser;
+                const walletHasResources = emailUser && walletUser.id !== emailUser.id
+                    ? await Memberships.existsForUser(tx, walletUser.id)
+                    : false;
+                // A verified email reconciles a provisional email-less wallet link.
+                // Keep a provisional owner when changing it would orphan its access.
+                const user = walletHasResources ? walletUser : (emailUser ?? walletUser);
+                if (linkedUser?.id !== user.id)
+                    await AuthAccounts.setWalletUser(tx, { address: payload.address, userId: user.id });
+                if (verifiedEmail && (user.email !== verifiedEmail || !user.emailVerified))
+                    await Users.setEmail(tx, user.id, verifiedEmail);
+                return { email: verifiedEmail ?? user.email ?? undefined, user };
+            });
+        }
         const session = {
             resolve: async (c) => {
-                const payload = await handler.getSession(c.req.raw);
-                if (!payload)
+                const [betterAuth, identitySession, wallet] = await Promise.all([
+                    (async () => {
+                        const auth = BetterAuth.fromContext(c, options_betterAuth);
+                        const request = BetterAuth.request(c, options_betterAuth);
+                        const result = await auth.api.getSession({ headers: request.headers });
+                        if (!result)
+                            return null;
+                        const provider = 'provider' in result.session && typeof result.session.provider === 'string'
+                            ? result.session.provider
+                            : undefined;
+                        if (!provider ||
+                            !result.user.email ||
+                            (provider === 'email' && !options_betterAuth.email))
+                            return null;
+                        return {
+                            email: result.user.email,
+                            id: result.user.id,
+                            identity: { provider, subject: result.user.email },
+                            type: 'session',
+                        };
+                    })(),
+                    (async () => {
+                        if (!identity)
+                            return null;
+                        const token = getCookie(c, identityCookieName);
+                        if (!token)
+                            return null;
+                        const value = await kv.store.get(identitySessionKey(token));
+                        if (value === null)
+                            return null;
+                        const payload = JSON.parse(value);
+                        if (payload.expiresAt <= Math.floor(Date.now() / 1_000))
+                            return null;
+                        const user = await resolveWallet(payload);
+                        if (!user)
+                            return null;
+                        return {
+                            ...(user.email ? { email: user.email } : {}),
+                            id: user.user.id,
+                            identity: { provider: 'wallet', subject: payload.address },
+                            type: 'session',
+                        };
+                    })(),
+                    (async () => {
+                        const payload = await handler.getSession(c.req.raw);
+                        if (!payload)
+                            return null;
+                        const user = await resolveWallet(payload);
+                        if (!user)
+                            return null;
+                        return {
+                            ...(user.email ? { email: user.email } : {}),
+                            id: user.user.id,
+                            identity: { provider: 'wallet', subject: payload.address },
+                            type: 'session',
+                        };
+                    })(),
+                ]);
+                if (betterAuth && identitySession && betterAuth.id !== identitySession.id)
                     return null;
-                const database = Db.get(db);
-                const user = await Users.getByAddress(database, payload.address);
-                if (!user)
+                if (betterAuth && wallet && betterAuth.id !== wallet.id)
                     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',
-                };
+                if (identitySession && wallet && identitySession.id !== wallet.id)
+                    return null;
+                return betterAuth ?? identitySession ?? wallet;
             },
         };
         const policy_public = policy({ public: true });
-        const policy_session = policy({ public: true, session: true });
         const describe = OpenApi.describeRoute({ hide: true });
         const app = new Hono()
             .use('/v1/auth/siwe', policy_public, describe)
@@ -507,10 +693,7 @@ export function install(options) {
         // 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({
+        app.post('/v1/auth/siwe/challenge', policy_public, OpenApi.documentJsonRequest(schema.challenge.Body), validateJsonRequest(schema.challenge.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,
@@ -528,10 +711,7 @@ export function install(options) {
             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({
+        app.post('/v1/auth/siwe', policy_public, OpenApi.documentJsonRequest(schema.verify.Body), validateJsonRequest(schema.verify.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',
@@ -557,35 +737,257 @@ export function install(options) {
             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.',
+        if (identity)
+            app.post('/v1/auth/identity', policy_public, OpenApi.documentJsonRequest(schema.identity.Body), validateJsonRequest(schema.identity.Body), OpenApi.describeRoute({
+                description: 'Verifies a Wallet-issued OpenID Connect identity token and establishes a session.',
+                hide: false,
+                operationId: 'verifyIdentity',
+                responses: {
+                    200: {
+                        content: {
+                            'application/json': { schema: OpenApi.resolver(schema.identity.Response) },
+                        },
+                        description: 'Session established.',
+                        headers: {
+                            ...OpenApi.successHeaders,
+                            'Set-Cookie': {
+                                description: `Session cookie (${identityCookieName}).`,
+                                schema: { type: 'string' },
+                            },
+                        },
+                    },
+                    400: OpenApi.standardError(400, 'Malformed request body.', ['body_invalid']),
+                    401: OpenApi.standardError(401, 'Identity verification failed.', ['identity_invalid']),
+                    429: OpenApi.standardError(429, 'Rate limited.'),
+                    500: OpenApi.standardError(500, 'Internal server error.'),
+                },
+                summary: 'Authenticate identity',
+                tags: ['Authentication'],
+            }), async (c) => {
+                const { idToken } = schema.identity.Body.parse(await c.req.json());
+                const claims = await Accounts.Identity.verify(idToken, {
+                    audience: identity.audience,
+                    issuer: identity.issuer ?? walletIdentityIssuer,
+                }).catch((error) => {
+                    // Issuer and network failures must reach the request error signal.
+                    if (isIdentityTokenError(error))
+                        return undefined;
+                    throw error;
+                });
+                if (!claims || !Address.validate(claims.subject, { strict: false }))
+                    return Response.error(c, {
+                        code: 'identity_invalid',
+                        message: 'Invalid identity token',
+                        status: 401,
+                    });
+                const address = Address.checksum(claims.subject);
+                await Users.upsertByAddress(Db.get(db), { address });
+                const issuedAt = Math.floor(Date.now() / 1_000);
+                const token = Hex.fromBytes(crypto.getRandomValues(new Uint8Array(32))).slice(2);
+                await kv.store.put(identitySessionKey(token), JSON.stringify({
+                    address,
+                    ...(claims.email ? { email: claims.email } : {}),
+                    expiresAt: issuedAt + identitySessionTtl,
+                    issuedAt,
+                }), { ttl: identitySessionTtl * 1_000 });
+                setCookie(c, identityCookieName, token, {
+                    httpOnly: true,
+                    maxAge: identitySessionTtl,
+                    path: '/',
+                    sameSite: 'Lax',
+                    secure: new URL(c.req.url).protocol === 'https:',
+                });
+                return c.json({}, 200);
+            });
+        app.post('/v1/auth/logout', policy(false), createMiddleware(async (c, next) => {
+            const auth = c.get('auth');
+            const principal = principalFromPublic(c, auth);
+            const result = await consumeRateLimit(auth, {
+                key: `public:${principal.id}`,
+                limit: auth.publicRateLimit ?? defaultPublicRateLimit,
+            });
+            if (result) {
+                setRateLimitHeaders(c, result);
+                if (!result.allowed)
+                    return rateLimitExceeded(c, result);
+            }
+            c.set('principal', principal);
+            await next();
+            return undefined;
+        }), OpenApi.describeRoute({
+            description: 'Revokes auth sessions and clears their cookies.',
             hide: false,
-            operationId: 'siweLogout',
+            operationId: 'logout',
             responses: {
-                204: { description: 'Session revoked and cookie cleared.' },
+                204: { description: 'Sessions revoked and cookies cleared.' },
                 429: OpenApi.standardError(429, 'Rate limited.'),
-                500: OpenApi.standardError(500, 'Internal server error.'),
+                500: OpenApi.standardError(500, 'Session logout failed.', ['session_logout_failed']),
             },
             summary: 'Sign out',
             tags: ['Authentication'],
-        }));
+        }), async (c) => {
+            const walletHeaders = (() => {
+                const authorization = c.req.header('authorization');
+                const cookie = c.req.header('cookie');
+                if (!authorization?.match(/^Bearer\s+.+$/i) || !cookie?.match(/(?:^|;\s*)accounts_auth=/))
+                    return [c.req.raw.headers];
+                const bearer = new Headers(c.req.raw.headers);
+                bearer.delete('cookie');
+                const cookie_ = new Headers(c.req.raw.headers);
+                cookie_.delete('authorization');
+                return [bearer, cookie_];
+            })();
+            const [betterAuth, identityLogout, ...accounts] = await Promise.allSettled([
+                BetterAuth.fromContext(c, options_betterAuth).api.signOut({
+                    headers: c.req.raw.headers,
+                    returnHeaders: true,
+                }),
+                (async () => {
+                    const token = getCookie(c, identityCookieName);
+                    deleteCookie(c, identityCookieName, { path: '/' });
+                    if (token)
+                        await kv.store.delete(identitySessionKey(token));
+                })(),
+                ...walletHeaders.map((headers) => handler.request(new Request(new URL('/logout', c.req.url), {
+                    headers,
+                    method: 'POST',
+                }))),
+            ]);
+            if (betterAuth.status === 'fulfilled')
+                for (const cookie of splitSetCookieHeader(betterAuth.value.headers.get('Set-Cookie') ?? ''))
+                    c.header('Set-Cookie', cookie, { append: true });
+            for (const result of accounts)
+                if (result.status === 'fulfilled')
+                    for (const cookie of splitSetCookieHeader(result.value.headers.get('Set-Cookie') ?? ''))
+                        c.header('Set-Cookie', cookie, { append: true });
+            const error = (() => {
+                const rejected = [betterAuth, identityLogout, ...accounts].find((result) => result.status === 'rejected');
+                if (rejected?.status === 'rejected')
+                    return rejected.reason instanceof Error
+                        ? rejected.reason
+                        : new Error('Session logout failed', { cause: rejected.reason });
+                const failed = accounts.find((result) => result.status === 'fulfilled' && !result.value.ok);
+                if (failed?.status === 'fulfilled')
+                    return new Error(`Accounts session logout failed with status ${failed.value.status}`);
+                return undefined;
+            })();
+            if (error) {
+                c.error = error;
+                return Response.error(c, {
+                    code: 'session_logout_failed',
+                    message: 'Session logout failed',
+                    status: 500,
+                });
+            }
+            return c.body(null, 204);
+        });
+        app.route('/v1/auth/siwe', handler);
+        app.on(['GET', 'POST'], '/v1/auth/*', policy_public, describe, async (c, next) => {
+            if (c.req.method === 'POST' &&
+                stripBasePath(c.req.path, basePath(c)) === '/v1/auth/email-otp/send-verification-otp') {
+                const body = await c.req.raw
+                    .clone()
+                    .json()
+                    .catch(() => undefined);
+                if (body && typeof body === 'object' && 'type' in body && body.type !== 'sign-in')
+                    return Response.error(c, {
+                        code: 'body_invalid',
+                        message: 'Only sign-in OTPs are supported',
+                        status: 400,
+                    });
+            }
+            const response = await BetterAuth.fromContext(c, options_betterAuth).handler(BetterAuth.request(c, options_betterAuth));
+            // Leave unmatched paths available to auth providers mounted by the host app.
+            return response.status === 404 ? next() : response;
+        });
         return Object.assign(
         // The tag joins the `Management API` group at `management()`'s chosen slot;
         // group listings filter to defined tags, so it drops out when unmounted.
-        Metadata.attach(app.route('/v1/auth/siwe', handler), {
+        Metadata.attach(app, {
+            securitySchemes: {
+                session: {
+                    description: 'Session cookie established by email OTP, Wallet identity, or SIWE sign-in. Browsers send `tempo_auth.session_token`, `tempo_identity`, or `accounts_auth`; Accounts sessions may also use `Authorization: Bearer <token>`.', // prettier-ignore
+                    in: 'header',
+                    name: 'Cookie',
+                    type: 'apiKey',
+                },
+            },
             tags: [{ name: 'Authentication', description: 'Authenticate into the Tempo Platform.' }],
         }), { session });
     })();
+    const resolve = createApiKeyResolver({
+        apiKey: options_middleware.apiKey,
+        db: options.db,
+        scopeCatalog,
+    });
+    const defaults = laneDefaults(options_middleware);
+    const base = {};
+    const edgeRateLimit = (() => {
+        if (options.auth === false || !options_edgeRateLimit)
+            return undefined;
+        const superAdminTokenHash = options_middleware.superAdmin?.secret
+            ? ApiKey.hash(options_middleware.superAdmin.secret)
+            : undefined;
+        return createMiddleware(async (c, next) => {
+            const credential = getApiKeyCredential(c);
+            const resolved = resolveRequestPolicy(c, { base, defaults, options: options_middleware });
+            const isSuperAdmin = credential &&
+                superAdminTokenHash !== undefined &&
+                ApiKey.hash(credential.token) === superAdminTokenHash;
+            const canUseApiKeyQuota = credential &&
+                !isSuperAdmin &&
+                !hasPaymentCredential(c) &&
+                options_middleware.apiKey !== false &&
+                resolved?.policy?.apiKey &&
+                (!resolved.management || (options_middleware.mpp !== false && resolved.policy.mpp));
+            const cached = canUseApiKeyQuota ? resolve.peek(c, credential.token) : undefined;
+            if (cached)
+                return next();
+            const response = await Timing.time(c, 'edge_rate_limit', () => options_edgeRateLimit(c.req.raw));
+            if (response)
+                return response;
+            if (canUseApiKeyQuota && cached === undefined)
+                await resolve.resolve(c, credential.token);
+            return next();
+        });
+    })();
     const middleware_ = options.auth === false
         ? undefined
-        : middleware({
+        : createAuthMiddleware({
             ...options_middleware,
             ...(app ? { session: app.session } : {}),
             scopeCatalog,
-        });
-    return { app, middleware: middleware_ };
+        }, resolve);
+    return { app, edgeRateLimit, middleware: middleware_ };
 }
-/** Creates route middleware that contributes an auth policy override. */
+function validateJsonRequest(schema) {
+    return async (c, next) => {
+        if (!c.req.header('content-type')?.toLowerCase().startsWith('application/json'))
+            return Response.error(c, {
+                code: 'body_invalid',
+                message: 'Invalid request body',
+                status: 400,
+            });
+        const value = await (async () => {
+            try {
+                return await c.req.raw.clone().json();
+            }
+            catch {
+                return undefined;
+            }
+        })();
+        const result = schema.safeParse(value);
+        if (!result.success)
+            return Response.error(c, {
+                code: 'body_invalid',
+                details: Response.validationDetails(result.error.issues),
+                message: 'Invalid request body',
+                status: 400,
+            });
+        return next();
+    };
+}
+/** Creates route middleware that contributes an auth policy override, or bypasses auth when passed `false`. */
 export function policy(options) {
     const middleware = createMiddleware((_, next) => next());
     middleware[policySymbol] = options;
@@ -601,7 +1003,7 @@ export function installMppManagementRoutes(app, options = {}) {
             continue;
         const target = targets.get(route.path) ?? { path: route.path };
         const override = policyFromRoute(route);
-        if (override?.mpp !== undefined)
+        if (override && override.mpp !== undefined)
             target.mpp = resolveMppLane(target.mpp, override.mpp, { session: {} });
         const spec = openApiSpec(route);
         if (spec) {
@@ -646,7 +1048,7 @@ function laneDefaults(options) {
             scopes: apiKey?.scopes ?? [Scope.wildcard],
         },
         mpp: { session: {} },
-        public: { rateLimit: public_?.rateLimit ?? { limit: 60, period: 'minute' } },
+        public: { rateLimit: public_?.rateLimit ?? defaultPublicRateLimit },
         session: true,
     };
 }
@@ -796,7 +1198,7 @@ export function describeAccess(app) {
         if (typeof spec?.operationId === 'string')
             group.operationId = spec.operationId;
         const override = policyFromRoute(route);
-        if (override)
+        if (override !== undefined)
             group.overrides.push(override);
         groups.set(key, group);
     }
@@ -809,7 +1211,12 @@ export function describeAccess(app) {
         let public_ = false;
         let mpp = false;
         let session = false;
+        let bypass = false;
         for (const override of overrides) {
+            if (override === false) {
+                bypass = true;
+                break;
+            }
             if (override.apiKey !== undefined)
                 apiKey = override.apiKey !== false;
             if (override.apiKey && override.apiKey !== true && override.apiKey.scopes)
@@ -821,7 +1228,14 @@ export function describeAccess(app) {
             if (override.session !== undefined)
                 session = override.session !== false;
         }
-        access[operationId] = { apiKey, mpp, public: public_, scopes: apiKey ? scopes : [], session };
+        access[operationId] = {
+            apiKey,
+            ...(bypass ? { bypass: true } : {}),
+            mpp,
+            public: public_,
+            scopes: apiKey ? scopes : [],
+            session,
+        };
     }
     return access;
 }
@@ -862,14 +1276,17 @@ export function require(policy) {
         const hasQueryApiKey = new URL(c.req.url).searchParams.has('key');
         // Auth owns `key`; strict route schemas must not validate it.
         stripApiKeyQuery(c);
-        // Reject unknown chains before MPP builds a chain-bound challenge. Route
-        // groups publish their supported chains into the shared app context.
         const chainId = explicitChainId(c);
         const supportedChainIds = c.var['supportedChainIds'];
-        if (chainId !== undefined &&
-            supportedChainIds instanceof Set &&
-            !supportedChainIds.has(chainId))
-            return Response.unsupportedChainId(c, chainId, supportedChainIds);
+        const unsupportedChain = (() => {
+            if (chainId === undefined ||
+                !(supportedChainIds instanceof Set) ||
+                supportedChainIds.has(chainId))
+                return undefined;
+            return { chainId, supportedChainIds };
+        })();
+        if (unsupportedChain && !credential)
+            return Response.unsupportedChainId(c, unsupportedChain.chainId, unsupportedChain.supportedChainIds);
         const proceed = async () => {
             await next();
             // Query credential responses must not enter shared caches.
@@ -890,11 +1307,15 @@ export function require(policy) {
             // 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) {
+                if (unsupportedChain)
+                    return Response.unsupportedChainId(c, unsupportedChain.chainId, unsupportedChain.supportedChainIds);
                 c.set('principal', { actor: 'super_admin', id: 'super_admin', type: 'super_admin' });
                 return proceed();
             }
             const apiKey_resolved = await auth.apiKey?.resolve(c, credential.token);
             if (!apiKey_resolved) {
+                if (unsupportedChain)
+                    return Response.unsupportedChainId(c, unsupportedChain.chainId, unsupportedChain.supportedChainIds);
                 // 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.
@@ -931,6 +1352,28 @@ export function require(policy) {
                     message: 'API key not permitted for this route',
                     status: 403,
                 });
+            // Non-paid requests consume API-key quota before rejection. Paid
+            // requests use the MPP quota after access checks.
+            const scope = policy.apiKey.scopes[0] ?? Scope.wildcard;
+            const throttled = apiKey.environment === 'sandbox' && apiKey.billingActive !== true;
+            const limit = throttled
+                ? (policy.public?.rateLimit ?? auth.publicRateLimit ?? { limit: 60, period: 'minute' })
+                : resolveApiKeyLimit({ apiKey, auth, policy: policy.apiKey, scope });
+            const paid = hasPayment && !throttled;
+            const result = paid
+                ? null
+                : 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. MPP challenges own their headers and drop these by design.
+                c.header('RateLimit-Scope', scope);
+            }
+            if (unsupportedChain)
+                return Response.unsupportedChainId(c, unsupportedChain.chainId, unsupportedChain.supportedChainIds);
             if (apiKey.allowedIps.length &&
                 !(await IpAllowlist.allows(c, {
                     address: trustedClientIp(c, auth),
@@ -958,53 +1401,25 @@ export function require(policy) {
                     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)
+            if (paid)
                 return requirePayment(c, proceed, {
                     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 ?? { limit: 60, period: 'minute' })
-                    : resolveApiKeyLimit({ apiKey, auth, policy: policy.apiKey, scope });
-                const result = await consumeRateLimit(auth, {
-                    key: `api_key:${apiKey.id}:scope:${scope}`,
-                    limit,
+            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, proceed, {
+                    auth,
+                    payment: { reason: 'api_key_over_quota', type: 'mpp' },
+                    policy,
+                    principal,
+                    rateLimit: result,
                 });
-                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, proceed, {
-                        auth,
-                        payment: { reason: 'api_key_over_quota', type: 'mpp' },
-                        policy,
-                        principal,
-                        rateLimit: result,
-                    });
-                }
             }
             return proceed();
         }
@@ -1074,7 +1489,8 @@ export function require(policy) {
  * server-side — we just stop waiting for it.
  */
 const rateLimitConsumeTimeout = 300;
-function consumeRateLimit(auth, options) {
+/** Consumes one quota and returns null when its counter is unavailable, allowing callers to fail open. */
+export 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)
@@ -1160,12 +1576,15 @@ function clientIp(c, auth) {
     return auth.publicClientIp ? auth.publicClientIp(c.req.raw) : c.req.header('cf-connecting-ip');
 }
 function trustedClientIp(c, auth) {
-    if (auth.publicClientIp)
-        return auth.publicClientIp(c.req.raw);
+    return resolveTrustedClientIp(c.req.raw, auth.publicClientIp);
+}
+function resolveTrustedClientIp(request, resolve) {
+    if (resolve)
+        return resolve(request);
     // Cloudflare supplies both the request metadata and this header.
-    if (!('cf' in c.req.raw))
+    if (!('cf' in request))
         return undefined;
-    return c.req.header('cf-connecting-ip');
+    return request.headers.get('cf-connecting-ip') ?? undefined;
 }
 /** Removes the reserved auth query parameter before route validation. */
 function stripApiKeyQuery(c) {
@@ -1348,19 +1767,13 @@ 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.
+// Resolve the session lane from the auth context's capability. Dependency
+// failures propagate to the app error boundary instead of becoming a `401`.
 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;
-    }
+    return session.resolve(c);
 }
 /** Maximum resolve-cache entries held per isolate before eviction. */
 const cachedMaxEntries = 10_000;
@@ -1377,39 +1790,54 @@ 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)
+    return {
+        invalidate(token) {
+            cells.delete(`v1:${ApiKey.hash(token)}`);
+        },
+        peek(token) {
+            const key = `v1:${ApiKey.hash(token)}`;
+            const cell = cells.get(key);
+            if (!cell)
+                return undefined;
+            if (cell.expiresAt > now())
+                return cell.value;
             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);
+            return undefined;
+        },
+        async resolve(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;
             }
-            cells.set(key, { expiresAt: now() + (value ? ttl : negativeTtl), value });
-            return value;
-        })();
-        flights.set(key, flight);
-        try {
-            return await flight;
-        }
-        finally {
-            flights.delete(key);
-        }
+            finally {
+                flights.delete(key);
+            }
+        },
     };
 }
 /** Thrown when a rate-limit consume exceeds {@link rateLimitConsumeTimeout}. */