tapimo 0.0.2 → 0.2.0

package/src/internal/Auth.ts

@@ -1,4 +1,6 @@
-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'
@@ -6,14 +8,23 @@ import type { MergePath, RouterRoute, Schema as core_Schema } from 'hono/types'
 import { findTargetHandler } from 'hono/utils/handler'
 import { Credential, type Method } from 'mppx'
 import { Mppx, tempo } from 'mppx/hono'
+import * as z from 'zod/mini'
 
-import * as ApiKeySource from '../ApiKeySource.js'
+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 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')
@@ -29,14 +40,18 @@ export type Context = {
          * per-key {@link ApiKey.ApiKey.rateLimits} shape.
          */
         rateLimits?: Record<string, RateLimit.Limit> | undefined
-        /** Backing API-key source. */
-        source: ApiKeySource.Source
+        /** Resolves a presented token against the app's KV store on `c`. */
+        resolve: (c: hono_Context, token: string) => Promise<ApiKey.ApiKey | null>
       }
     | undefined
   /** MPP payment configuration. */
   mpp?: Mpp | 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. */
@@ -86,9 +101,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. */
@@ -117,6 +134,8 @@ export type PolicyOverride = {
       }
     | boolean
     | undefined
+  /** Session lane: `true` allows signed-in wallet sessions, `false` disables. */
+  session?: boolean | undefined
 }
 
 /** Authenticated or anonymous caller. */
@@ -132,6 +151,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'
     }
@@ -143,13 +164,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. */
@@ -157,6 +211,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.
@@ -200,6 +395,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'))
@@ -216,15 +438,23 @@ 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).
   // Resolution is cached per isolate by default (positive 60s / negative 10s,
-  // keyed by token sha256 — see `ApiKeySource.cached`) so hot keys skip the
-  // backend read on the auth path of every request. Pass `apiKey.cache: false`
-  // when instant revocation matters more than the per-request read.
-  const source = (() => {
-    if (options.apiKey === false || !options.apiKey?.source) return ApiKeySource.noop
-    if (options.apiKey.cache === false) return options.apiKey.source
-    return ApiKeySource.cached(options.apiKey.source, options.apiKey.cache)
+  // keyed by token sha256) so hot keys skip the backend read on the auth path
+  // of every request. Pass `apiKey.cache: false` when instant revocation
+  // matters more than the per-request read.
+  const resolve = (() => {
+    const uncached = (c: hono_Context, token: string) => {
+      const kv = contextKv(c)
+      return kv ? ApiKeys.resolve(kv.store, token) : Promise.resolve(null)
+    }
+    if (options.apiKey === false || options.apiKey?.cache === false) return uncached
+    return cachedResolve(uncached, options.apiKey?.cache ?? {})
   })()
   const auth: Context = {
     ...(options.apiKey === false
@@ -232,7 +462,7 @@ export function middleware<
       : {
           apiKey: {
             ...(options.apiKey?.rateLimits ? { rateLimits: options.apiKey.rateLimits } : {}),
-            source,
+            resolve,
           },
         }),
     ...(options.mpp === false
@@ -245,6 +475,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) => {
@@ -280,16 +514,14 @@ export declare namespace middleware {
     apiKey?:
       | {
           /**
-           * Resolve-cache tuning for the source (per-isolate, positive 60s /
-           * negative 10s by default), or `false` to resolve uncached on every
-           * request — e.g. when instant revocation matters more than the
-           * per-request backend read.
+           * Resolve-cache tuning (per-isolate, positive 60s / negative 10s by
+           * default), or `false` to resolve uncached on every request — e.g.
+           * when instant revocation matters more than the per-request backend
+           * read.
            */
-          cache?: ApiKeySource.cached.Options | false | undefined
+          cache?: Cache | false | undefined
           /** API-key quotas keyed by quota scope (reserved `'*'` is the config default). */
           rateLimits?: Record<string, RateLimit.Limit> | undefined
-          /** Backing API-key source. Defaults to an empty source (rejects all). */
-          source?: ApiKeySource.Source | undefined
           /** Required API-key scopes. */
           scopes?: readonly Scope.Id[] | undefined
         }
@@ -309,6 +541,24 @@ 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. */
+  type Cache = {
+    /** Time-to-live for negative (`null`) results in milliseconds. */
+    negativeTtl?: number | undefined
+    /** Clock used for expiry. */
+    now?: (() => number) | undefined
+    /** Time-to-live for positive results in milliseconds. */
+    ttl?: number | undefined
   }
 
   /** MPP payment options used by auth middleware. */
@@ -318,6 +568,305 @@ 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, ttl } =
+      (typeof options_session === 'object' ? options_session.wallet : undefined) ?? {}
+
+    const handler = Accounts.Handler.auth({
+      ...(issuer ? { identity: { issuer } } : {}),
+      // Sign-in upserts the `users` row keyed by address.
+      onAuthenticate: async ({ address }) => {
+        await Users.upsertByAddress(Db.get(db), { address })
+      },
+      // No pinned origin: on Workers the edge proxy headers are trustworthy, so
+      // opt in explicitly (the SDK's guard ignores its own Workers default).
+      // Off-Workers the SDK keeps throwing until `wallet.origin` is set.
+      ...(origin
+        ? { origin }
+        : globalThis.navigator?.userAgent === 'Cloudflare-Workers'
+          ? { trustProxy: true }
+          : {}),
+      // The app's KV store under the SDK's Kv contract: JSON values,
+      // second-based TTLs, `auth:`-prefixed keys disjoint from API-key
+      // records. `take` is omitted; the SDK falls back to get+delete.
+      store: {
+        async delete(key) {
+          await kv.store.delete(`auth:${key}`)
+        },
+        async get(key) {
+          const value = await kv.store.get(`auth:${key}`)
+          return value === null ? undefined : (JSON.parse(value) 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 describe = OpenApi.describeRoute({ hide: true })
+    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',
+      }),
+      OpenApi.describeRoute({
+        description:
+          'Verifies the signed challenge and establishes a session. Sets a session cookie by default; pass `returnToken` to receive a bearer token instead.',
+        hide: false,
+        operationId: 'verifySiwe',
+        responses: {
+          200: {
+            content: { 'application/json': { schema: OpenApi.resolver(schema.verify.Response) } },
+            description: 'Session established. Cookie mode sets `Set-Cookie`; token mode returns `token`.', // prettier-ignore
+            headers: {
+              ...OpenApi.successHeaders,
+              'Set-Cookie': {
+                description: 'Session cookie (`accounts_auth`); omitted when `returnToken` is true.', // prettier-ignore
+                schema: { type: 'string' },
+              },
+            },
+          },
+          400: handlerError('Invalid, expired, or mismatched challenge message.'),
+          401: handlerError('Signature or identity verification failed.'),
+          409: handlerError('Challenge nonce already used or unknown.'),
+          429: OpenApi.standardError(429, 'Rate limited.'),
+          500: OpenApi.standardError(500, 'Internal server error.'),
+        },
+        summary: 'Authenticate (SIWE)',
+        tags: ['Authentication'],
+      }),
+    )
+    app.post(
+      '/v1/auth/siwe/logout',
+      policy_public,
+      OpenApi.describeRoute({
+        description: 'Revokes the current session and clears the session cookie.',
+        hide: false,
+        operationId: 'siweLogout',
+        responses: {
+          204: { description: 'Session revoked and cookie cleared.' },
+          429: OpenApi.standardError(429, 'Rate limited.'),
+          500: OpenApi.standardError(500, 'Internal server error.'),
+        },
+        summary: 'Sign out',
+        tags: ['Authentication'],
+      }),
+    )
+    return Object.assign(
+      // The tag joins the `Platform API` group at `platform()`'s chosen slot;
+      // group listings filter to defined tags, so it drops out when unmounted.
+      Metadata.attach(app.route('/v1/auth/siwe', handler), {
+        tags: [{ name: 'Authentication', description: 'Authenticate into the Tempo Platform.' }],
+      }),
+      { session },
+    )
+  })()
+
+  const middleware_ =
+    options.auth === false
+      ? undefined
+      : middleware({ ...options_middleware, ...(app ? { session: app.session } : {}) })
+
+  return { app, middleware: middleware_ }
+}
+
+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 wallet config. Requires `kv`. */
+          session?: boolean | { wallet?: Wallet | undefined } | 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
+  }
+
+  /** 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
+    /** 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
@@ -361,6 +910,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 = {
@@ -394,19 +944,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,
@@ -416,6 +957,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
@@ -423,6 +965,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
@@ -431,11 +974,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 } : {}),
   }
 }
 
@@ -478,6 +1023,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)
@@ -515,20 +1070,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[] }>()
@@ -545,18 +1104,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
 }
@@ -612,13 +1173,31 @@ export function require<environment extends Environment = Environment>(
 
     const hasPayment = hasPaymentCredential(c) && isPaymentEnabled(auth, policy)
     if (credential) {
-      const apiKey = await auth.apiKey?.source.resolve(credential.token)
-      if (!apiKey)
+      // The super admin secret precedes key lookup: it is not a stored key.
+      // It must never reach KV resolution or scope/quota checks.
+      if (auth.superAdmin && ApiKey.hash(credential.token) === auth.superAdmin.tokenHash) {
+        c.set('principal', { actor: 'super_admin', id: 'super_admin', type: 'super_admin' })
+        return next()
+      }
+
+      const apiKey = await auth.apiKey?.resolve(c, credential.token)
+      if (!apiKey) {
+        // A bearer session token is indistinguishable from an API key at the
+        // header, so a failed key lookup falls through to the session lane
+        // before rejecting.
+        if (policy.session) {
+          const session = await resolveSession(c, auth)
+          if (session) {
+            c.set('principal', session)
+            return next()
+          }
+        }
         return jsonError(c, {
           code: 'api_key_invalid',
           message: 'Invalid API key',
           status: 401,
         })
+      }
 
       // Sandbox keys are restricted to non-mainnet chains. An explicit
       // `chainId` of mainnet makes the key unusable for this request, so it is
@@ -643,6 +1222,14 @@ export function require<environment extends Environment = Environment>(
 
         const principal = principalFromApiKey(apiKey)
         c.set('principal', principal)
+        // Default-deny: routes with no API-key lane allow only the super admin.
+        // A valid key is authenticated but forbidden.
+        if (!policy.apiKey)
+          return jsonError(c, {
+            code: 'forbidden',
+            message: 'API key not permitted for this route',
+            status: 403,
+          })
         const missing = apiKey.scopes.includes(Scope.wildcard)
           ? []
           : (policy.apiKey?.scopes.filter((scope) => !apiKey.scopes.includes(scope)) ?? [])
@@ -692,6 +1279,17 @@ export function require<environment extends Environment = Environment>(
       }
     }
 
+    // Cookie sessions carry no Authorization credential; resolve the session
+    // lane before the public/paid lanes so signed-in browsers skip anonymous
+    // quotas.
+    if (policy.session) {
+      const session = await resolveSession(c, auth)
+      if (session) {
+        c.set('principal', session)
+        return next()
+      }
+    }
+
     const publicPrincipal = principalFromPublic(c)
     if (hasPayment) {
       c.set('principal', publicPrincipal)
@@ -773,6 +1371,8 @@ export declare namespace require {
           rateLimit: RateLimit.Limit
         }
       | undefined
+    /** Session access policy: `true` allows signed-in wallet sessions. */
+    session?: boolean | undefined
   }
 }
 
@@ -791,19 +1391,65 @@ 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 Cloudflare Durable Object overload is an expected
+    // degradation (a slow/hot counter backend), logged at warn so it stays out
+    // of error dashboards; an unexpected store throw is a genuine error.
+    if (error instanceof RateLimitTimeoutError || isDurableObjectOverload(error))
+      console.warn('[auth] rate-limit consume degraded; failing open', error)
+    else console.error('[auth] rate-limit consume failed; failing open', error)
     return null
   })
 }
 
+function isDurableObjectOverload(error: unknown): boolean {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'overloaded' in error &&
+    (error as { overloaded?: unknown }).overloaded === true
+  )
+}
+
+/**
+ * Rejects with a {@link RateLimitTimeoutError} if `promise` does not settle
+ * within `ms`, clearing the timer on either outcome so it never keeps the
+ * isolate alive.
+ */
+function withTimeout<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
@@ -944,6 +1590,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',
   }
 }
@@ -1010,3 +1657,95 @@ function setRateLimitHeaders(c: hono_Context, result: RateLimit.Result) {
   c.header('RateLimit-Remaining', String(result.remaining))
   c.header('RateLimit-Reset', String(result.reset))
 }
+
+// Reads the app's KV state store from request context (set by `App.create`
+// from its `kv` option); `undefined` leaves API-key auth closed.
+function contextKv(c: 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
+
+/**
+ * Wraps token resolution with a short-TTL per-isolate cache so hot keys skip
+ * the backend read on every request. Positive results cache for `ttl`
+ * (default 60s), negative for `negativeTtl` (default 10s) so a freshly minted
+ * key is usable quickly; concurrent misses for one token are single-flighted.
+ * Entries are keyed by the token's sha256 (`ApiKey.hash`) — never the
+ * plaintext. A revoked key may stay resolvable for up to `ttl` — the accepted
+ * trade-off for removing a backend read from the auth path.
+ */
+function cachedResolve(
+  resolve: (c: hono_Context, token: string) => Promise<ApiKey.ApiKey | null>,
+  options: middleware.Cache,
+): (c: hono_Context, token: string) => Promise<ApiKey.ApiKey | null> {
+  const { negativeTtl = 10_000, now = Date.now, ttl = 60_000 } = options
+  type Cell = { expiresAt: number; value: ApiKey.ApiKey | null }
+  const cells = new Map<string, Cell>()
+  const flights = new Map<string, Promise<ApiKey.ApiKey | null>>()
+
+  return async (c, token) => {
+    // Versioned so a future record-shape change can't serve stale shapes.
+    const key = `v1:${ApiKey.hash(token)}`
+    const cell = cells.get(key)
+    if (cell && cell.expiresAt > now()) return cell.value
+    if (cell) cells.delete(key)
+
+    const existing = flights.get(key)
+    if (existing) return existing
+
+    const flight = (async () => {
+      const value = await resolve(c, token)
+      // Bound the cache: random invalid tokens each add a (negative) entry,
+      // so sweep expired cells at the cap and then drop the oldest.
+      if (cells.size >= cachedMaxEntries) {
+        const time = now()
+        for (const [name, entry] of cells) if (entry.expiresAt <= time) cells.delete(name)
+        while (cells.size >= cachedMaxEntries) cells.delete(cells.keys().next().value as string)
+      }
+      cells.set(key, { expiresAt: now() + (value ? ttl : negativeTtl), value })
+      return value
+    })()
+    flights.set(key, flight)
+    try {
+      return await flight
+    } finally {
+      flights.delete(key)
+    }
+  }
+}
+
+/** Thrown when a rate-limit consume exceeds {@link rateLimitConsumeTimeout}. */
+export class RateLimitTimeoutError extends Error {
+  override name = 'Auth.RateLimitTimeoutError'
+  constructor(ms: number) {
+    super(`Rate-limit consume timed out after ${ms}ms; failing open.`)
+  }
+}