tapimo 0.1.0 → 0.3.0

package/src/internal/Auth.ts

@@ -1,20 +1,32 @@
-import type { Context as hono_Context, Hono, MiddlewareHandler } from 'hono'
+import * as Accounts from 'accounts/server'
+import { Hono } from 'hono'
+import type { Context as hono_Context, MiddlewareHandler } from 'hono'
 import type { HonoBase } from 'hono/hono-base'
 import { createMiddleware } from 'hono/factory'
 import { matchedRoutes } from 'hono/route'
 import type { MergePath, RouterRoute, Schema as core_Schema } from 'hono/types'
 import { findTargetHandler } from 'hono/utils/handler'
+import { decodeJwt } from 'jose'
 import { Credential, type Method } from 'mppx'
 import { Mppx, tempo } from 'mppx/hono'
+import * as z from 'zod/mini'
 
+import type * as App from '../App.js'
 import * as ApiKey from '../ApiKey.js'
 import * as ApiKeys from '../ApiKeys.js'
+import * as Db from '../db/Db.js'
 import type * as Store from './Store.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')
@@ -36,8 +48,19 @@ export type Context = {
     | undefined
   /** MPP payment configuration. */
   mpp?: Mpp | undefined
+  /**
+   * Configured default anonymous public quota. Used as the throttle ceiling for
+   * sandbox keys without active billing on routes that expose no public lane
+   * (where the per-route `policy.public` is absent). Omit to fall back to the
+   * framework default.
+   */
+  publicRateLimit?: RateLimit.Limit | undefined
   /** Rate-limit store used by API handlers. */
   rateLimit?: RateLimit.Store | undefined
+  /** Session lane resolution (the session surface's capability), or undefined when sessions are unmounted. */
+  session?: Session | undefined
+  /** Super-admin machine credential (sha256 of the configured secret), or undefined when disabled. */
+  superAdmin?: { tokenHash: string } | undefined
 }
 
 /** Hono environment variables set by auth middleware. */
@@ -87,9 +110,11 @@ type Mpp = {
 /**
  * Route-level auth policy override. Each lane is independent: `true` enables it
  * with the middleware defaults, `false` disables it, an object enables it with
- * the given overrides, and omitting it inherits the resolved policy. Lanes are
- * default-closed except `apiKey` (see {@link middleware}), so a route that
- * declares nothing — or declares only `apiKey` — is API-key-only.
+ * the given overrides, and omitting it inherits the resolved policy. All lanes
+ * are default-closed (see {@link middleware}).
+ *
+ * Routes grant API-key, public, or paid access explicitly via {@link policy};
+ * otherwise only `super_admin` reaches them.
  */
 export type PolicyOverride = {
   /** API-key lane: pass quota/scopes overrides, or a boolean to enable/disable. */
@@ -118,6 +143,8 @@ export type PolicyOverride = {
       }
     | boolean
     | undefined
+  /** Session lane: `true` allows signed-in wallet sessions, `false` disables. */
+  session?: boolean | undefined
 }
 
 /** Authenticated or anonymous caller. */
@@ -133,6 +160,8 @@ export type Principal =
       orgId: string
       /** Payment metadata for paid overflow requests. */
       payment?: Payment | undefined
+      /** Owning project id, when the key carries project attribution. */
+      projectId?: string | undefined
       /** Principal kind. */
       type: 'api_key'
     }
@@ -144,13 +173,46 @@ export type Principal =
       /** Principal kind. */
       type: 'public'
     }
+  | {
+      /** Verified email bound to the session, when present. */
+      email?: string | undefined
+      /** Principal id: the user id (`usr_…`). */
+      id: string
+      /** Identity that established the session, as a provider/subject pair (OIDC `iss`/`sub` semantics). */
+      identity: {
+        /** Identity provider: `wallet` for SIWE sign-in, an OIDC issuer otherwise. */
+        provider: string
+        /** Provider-scoped subject — the wallet address for `wallet`. */
+        subject: string
+      }
+      /** Payment metadata for paid overflow requests. */
+      payment?: Payment | undefined
+      /** Principal kind. */
+      type: 'session'
+    }
+  | {
+      /** Attributed super admin identity (`'super_admin'` for the configured machine secret). */
+      actor: string
+      /** Principal id. */
+      id: string
+      /** Payment metadata for paid overflow requests. */
+      payment?: Payment | undefined
+      /** Principal kind. */
+      type: 'super_admin'
+    }
 
 /** Hono variables set by auth middleware. */
 export type Variables = {
   /** Auth context consumed by protected handlers. */
   auth: Context
+  /** Caller's membership resolved by {@link ensureOrg}; absent for `super_admin`. */
+  membership?: Memberships.Record | undefined
+  /** Organization resolved by {@link ensureOrg} for the current request. */
+  org?: Organizations.Record | undefined
   /** Authenticated or anonymous caller. */
   principal?: Principal | undefined
+  /** Project resolved by {@link ensureProject} for the current request. */
+  project?: Projects.Record | undefined
 }
 
 /** Reads the authenticated principal from a Hono context. */
@@ -158,6 +220,147 @@ export function getPrincipal<environment extends Environment>(c: hono_Context<en
   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: ensureOrg.Options = {}): MiddlewareHandler {
+  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<Environment>(async (c, next) => {
+    const notFound = () =>
+      Response.error(c, {
+        code: 'organization_not_found',
+        message: 'Organization not found',
+        status: 404,
+      })
+    const orgId = c.req.param('orgId' as never) as string | undefined
+    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
+  })
+}
+
+export declare namespace ensureOrg {
+  /** Options for the org guard. */
+  type Options = {
+    /** Minimum role required; defaults to `member` (any membership). */
+    role?: Memberships.Role | 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(): MiddlewareHandler {
+  // Typed loosely (like {@link policy}) so route chains keep their inferred
+  // schema; a concrete environment parameter collapses Hono's inference.
+  return createMiddleware<Environment>(async (c, next) => {
+    const notFound = () =>
+      Response.error(c, {
+        code: 'project_not_found',
+        message: 'Project not found',
+        status: 404,
+      })
+    const projectId = c.req.param('projectId' as never) as string | undefined
+    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 as boolean
+
+/** Typed org-scope error response for Hono client inference. Never reached at runtime. */
+export function ensureOrgError(c: hono_Context) {
+  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: hono_Context) {
+  // 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' as const)
+      : ('project_not_found' as const)
+  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<environment extends Environment>(
+  c: hono_Context<environment>,
+): Memberships.Record | undefined {
+  return c.get('membership')
+}
+
+/** Reads the organization resolved by {@link ensureOrg}; throws when the middleware did not run. */
+export function org<environment extends Environment>(
+  c: hono_Context<environment>,
+): Organizations.Record {
+  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<environment extends Environment>(
+  c: hono_Context<environment>,
+): Projects.Record {
+  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: hono_Context): Db.Source {
+  return (c.get as (key: string) => unknown)('db') as Db.Source
+}
+
 /**
  * Always false at runtime, but typed as `boolean` so handlers can include a
  * never-reached access-error branch in Hono's inferred response union.
@@ -201,6 +404,33 @@ export function accessError(c: hono_Context) {
   })
 }
 
+/** Typed lane-less policy error response for Hono client inference. Never reached at runtime. */
+export function superAdminAccessError(c: hono_Context) {
+  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: hono_Context) {
   const status = Number(c.req.header('tempo-narrow-access-status'))
@@ -217,7 +447,9 @@ export function middleware<
 >(options: middleware.Options<endpoint>): MiddlewareHandler<environment> {
   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: require.Policy = {}
   // 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).
@@ -242,6 +474,10 @@ export function middleware<
             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
       ? {}
       : {
@@ -252,6 +488,10 @@ export function middleware<
           }),
         }),
     rateLimit: RateLimit.memory(options.rateLimit),
+    ...(options.session ? { session: options.session } : {}),
+    ...(options.superAdmin?.secret
+      ? { superAdmin: { tokenHash: ApiKey.hash(options.superAdmin.secret) } }
+      : {}),
   }
 
   return createMiddleware<environment>((c, next) => {
@@ -314,6 +554,14 @@ export declare namespace middleware {
       | undefined
     /** Rate-limit store options. */
     rateLimit?: RateLimit.memory.Options | undefined
+    /** Session lane resolution — the session surface's capability; omit to leave the session lane closed. */
+    session?: Session | undefined
+    /**
+     * Super-admin machine credential. A presented API-key token matching this
+     * secret resolves to a `super_admin` principal — bypassing scope and quota
+     * checks — before the key lookup runs. Omit to disable the entry entirely.
+     */
+    superAdmin?: { secret: string } | undefined
   }
 
   /** Resolve-cache tuning for API-key resolution. */
@@ -333,6 +581,363 @@ export declare namespace middleware {
   }
 }
 
+/** Zod schemas documenting the session sign-in surface (`/v1/auth/siwe`). */
+namespace 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). */
+  export const 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`. */
+  export namespace challenge {
+    /** Request body. Accepted fields beyond this document pass through to the SDK handler. */
+    export const Body = z.object({})
+
+    /** Response body. */
+    export const 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] }),
+        ),
+    })
+  }
+
+  /** Schemas for `POST /v1/auth/siwe` (verify). */
+  export namespace verify {
+    /** Request body. */
+    export const 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. */
+    export const 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)] }),
+        ),
+    })
+  }
+}
+
+/** `{ error }` response for a sign-in handler failure status. */
+function handlerError(description: string) {
+  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: 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) as never)
+        },
+        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: 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<App.Environment>(async (c, next) => {
+      if (!emailAllowlist?.length) return next()
+      const { address, idToken } = (await c.req.json()) as z.output<typeof schema.verify.Body>
+      const database = Db.get(db)
+      const user = await Users.getByAddress(database, address)
+      if (!user) {
+        const email = (() => {
+          if (!idToken) return undefined
+          try {
+            const { email } = decodeJwt<{ email?: string }>(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<App.Environment>()
+      .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_ }
+}
+
+export declare namespace install {
+  /** Options for building the built-in auth pieces. */
+  type Options = {
+    auth:
+      | (Omit<middleware.Options, 'session'> & {
+          /** Session sign-in surface: mounts `/v1/auth/siwe` (challenge/verify/logout) and enables the session lane. Pass true for defaults or a config object. Requires `kv`. */
+          session?: Session | undefined
+        })
+      | false
+      | undefined
+    /** Authoritative database holding user rows. */
+    db: Db.Source
+    /** KV state store, or undefined when key auth is closed. */
+    kv: { store: Store.State } | undefined
+  }
+
+  /** Session sign-in surface configuration: `true` for defaults, or a config object. */
+  type Session =
+    | boolean
+    | {
+        /** Restrict new-user sign-ups to verified emails on these domains (case-insensitive exact match); invited emails and existing users sign in unaffected. */
+        emailAllowlist?: readonly string[] | undefined
+        /** SIWE wallet sign-in configuration. */
+        wallet?: Wallet | undefined
+      }
+
+  /** SIWE wallet sign-in configuration. */
+  type Wallet = {
+    /** Identity (verified email) issuer override; defaults to the Tempo wallet's production OIDC mount. */
+    issuer?: string | undefined
+    /** Pinned absolute origin for SIWE domain binding. Required off-Workers; on Workers the edge proxy headers are trusted by default. */
+    origin?: string | undefined
+    /** Reject sign-ins that carry no valid identity token, so every session holds a verified email. */
+    requireEmail?: boolean | undefined
+    /** Session and challenge TTL overrides, in seconds. */
+    ttl?: { challenge?: number | undefined; session?: number | undefined } | undefined
+  }
+}
+
 /** Creates route middleware that contributes an auth policy override. */
 export function policy(options: PolicyOverride): MiddlewareHandler {
   const middleware = createMiddleware((_, next) => next()) as MiddlewareHandler & PolicyHandler
@@ -376,6 +981,7 @@ type LaneDefaults = {
   apiKey: NonNullable<require.Policy['apiKey']>
   mpp: NonNullable<require.Policy['mpp']>
   public: NonNullable<require.Policy['public']>
+  session: NonNullable<require.Policy['session']>
 }
 
 type OpenApiHandler = {
@@ -409,19 +1015,10 @@ function laneDefaults(options: middleware.Options): LaneDefaults {
     },
     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: middleware.Options, defaults: LaneDefaults): require.Policy {
-  return options.apiKey === false ? {} : { apiKey: defaults.apiKey }
-}
-
 function resolvePolicy(
   base: require.Policy,
   defaults: LaneDefaults,
@@ -431,6 +1028,7 @@ function resolvePolicy(
   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
@@ -438,6 +1036,7 @@ function resolvePolicy(
     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
@@ -446,11 +1045,13 @@ function resolvePolicy(
   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 } : {}),
   }
 }
 
@@ -493,6 +1094,16 @@ function resolvePublicLane(
   return { rateLimit: override.rateLimit ?? base.rateLimit }
 }
 
+function resolveSessionLane(
+  current: require.Policy['session'],
+  override: PolicyOverride['session'],
+  default_: LaneDefaults['session'],
+): require.Policy['session'] {
+  if (override === undefined) return current
+  if (override === false) return undefined
+  return current ?? default_
+}
+
 function openApiRoute(c: hono_Context): OpenApiRoute | undefined {
   const route = matchedRoutes(c)
     .slice(c.req.routeIndex + 1)
@@ -530,20 +1141,24 @@ function policyFromRoute(route: RouterRoute) {
 
 /** Resolved access lanes for one documented operation. */
 export type OperationAccess = {
+  /** Whether API-key access is allowed. */
+  apiKey: boolean
   /** Whether MPP payment is accepted (enables the `402` payment-challenge response). */
   mpp: boolean
   /** Whether anonymous public-quota access is allowed (keeps the anonymous security option). */
   public: boolean
   /** Required API-key scopes (`[]` accepts any valid key); empty when the API-key lane is disabled. */
   scopes: readonly Scope.Id[]
+  /** Whether signed-in sessions are allowed. */
+  session: boolean
 }
 
 /**
  * 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: Hono<any, any>): Record<string, OperationAccess> {
   const groups = new Map<string, { operationId?: string; overrides: PolicyOverride[] }>()
@@ -560,18 +1175,20 @@ export function describeAccess(app: Hono<any, any>): Record<string, OperationAcc
   const access: Record<string, OperationAccess> = {}
   for (const { operationId, overrides } of groups.values()) {
     if (!operationId) continue
-    let apiKey = true
+    let apiKey = false
     let scopes: readonly Scope.Id[] = []
     let public_ = false
     let mpp = false
+    let session = false
     for (const override of overrides) {
       if (override.apiKey !== undefined) apiKey = override.apiKey !== false
       if (override.apiKey && override.apiKey !== true && override.apiKey.scopes)
         scopes = override.apiKey.scopes
       if (override.public !== undefined) 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
 }
@@ -627,82 +1244,133 @@ export function require<environment extends Environment = Environment>(
 
     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 =
+
+      const principal = principalFromApiKey(apiKey)
+      c.set('principal', principal)
+
+      if (
         apiKey.environment === 'sandbox' &&
         explicitChain !== undefined &&
         Viem.isMainnet(explicitChain)
+      )
+        return jsonError(c, {
+          code: 'api_key_forbidden',
+          message: 'Sandbox API keys only support testnet. Pass a testnet `chainId`.',
+          status: 403,
+        })
 
-      if (!sandboxOnMainnet) {
-        if (
-          apiKey.environment === 'sandbox' &&
-          explicitChain === undefined &&
-          Viem.isMainnet((c.get('chainId' as never) as number | undefined) ?? 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' as never, Viem.chainId.testnet as never)
-
-        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,
-          })
+      // 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 (hasPayment)
-          return requirePayment(c, next, {
+      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()
       }
     }
@@ -788,6 +1456,8 @@ export declare namespace require {
           rateLimit: RateLimit.Limit
         }
       | undefined
+    /** Session access policy: `true` allows signed-in wallet sessions. */
+    session?: boolean | undefined
   }
 }
 
@@ -806,19 +1476,68 @@ type RateLimitAccess = PaymentAccess & {
   rateLimit: RateLimit.Result
 }
 
+/**
+ * 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: Context,
   options: RateLimit.Store.ConsumeOptions,
 ): Promise<RateLimit.Result | null> {
   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: unknown): boolean {
+  const { message, overloaded, retryable } = (error ?? {}) as {
+    message?: string | undefined
+    overloaded?: boolean | undefined
+    retryable?: boolean | undefined
+  }
+  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<value>(promise: Promise<value>, ms: number): Promise<value> {
+  return new Promise<value>((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
@@ -959,6 +1678,7 @@ function principalFromApiKey(apiKey: ApiKey.ApiKey): Principal {
     environment: apiKey.environment,
     id: apiKey.id,
     orgId: apiKey.orgId,
+    ...(apiKey.projectId === undefined ? {} : { projectId: apiKey.projectId }),
     type: 'api_key',
   }
 }
@@ -1008,11 +1728,12 @@ function requirePaymentOrRateLimit<environment extends Environment>(
   options: RateLimitAccess,
 ) {
   if (isPaymentEnabled(options.auth, options.policy)) return requirePayment(c, next, options)
+  return rateLimitExceeded(c, options.rateLimit)
+}
 
-  c.header(
-    'Retry-After',
-    String(Math.max(options.rateLimit.reset - Math.ceil(Date.now() / 1_000), 1)),
-  )
+/** Emits a `429` with a `Retry-After` derived from the window reset. */
+function rateLimitExceeded(c: hono_Context, result: RateLimit.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',
@@ -1032,6 +1753,32 @@ function contextKv(c: hono_Context): { store: Store.State } | undefined {
   return (c.get as (key: string) => unknown)('kv') as { store: Store.State } | undefined
 }
 
+/** Session principal resolved by the session lane. */
+export type SessionPrincipal = Extract<Principal, { type: 'session' }>
+
+/**
+ * Session resolution capability installed on app context (`session`) by
+ * `App.create` when session auth is configured; `undefined` leaves the session
+ * lane closed.
+ */
+export type Session = {
+  /** Resolves the request's session (cookie or bearer token) to a principal. */
+  resolve: (c: hono_Context) => Promise<SessionPrincipal | null>
+}
+
+// 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: hono_Context, auth: Context): Promise<SessionPrincipal | null> {
+  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
 
@@ -1083,3 +1830,11 @@ function cachedResolve(
     }
   }
 }
+
+/** Thrown when a rate-limit consume exceeds {@link rateLimitConsumeTimeout}. */
+export class RateLimitTimeoutError extends Error {
+  override name = 'Auth.RateLimitTimeoutError'
+  constructor(ms: number) {
+    super(`Rate-limit consume timed out after ${ms}ms; failing open.`)
+  }
+}