@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/api/authenticate.ts

@@ -0,0 +1,1662 @@
+/** The sign-in routes under `/v1/auth`: email codes, passkeys, sign-out, and the session. @module */
+import { verifyOAuthQueryParams } from '@better-auth/oauth-provider'
+import { isAPIError } from 'better-auth/api'
+import { eq } from 'drizzle-orm'
+import type { Context } from 'hono'
+import { Hono } from 'hono'
+import { Hex } from 'ox'
+import { Authentication } from 'webauthx/server'
+import { env } from 'void/env'
+import * as z from 'zod'
+import * as Schema from '../app/db/schema.js'
+import * as Apps from '../internal/Apps.js'
+import * as core_Auth from '../internal/Auth.js'
+import * as Authorize from '../internal/Authorize.js'
+import * as BodyLimit from '../internal/BodyLimit.js'
+import * as Cache from '../internal/Cache.js'
+import * as Device from '../internal/Device.js'
+import type { Env } from '../internal/Env.js'
+import * as ErrorResponse from '../internal/ErrorResponse.js'
+import * as KeyAuthorization from '../internal/KeyAuthorization.js'
+import * as Log from '../internal/Log.js'
+import * as Logout from '../internal/Logout.js'
+import * as OpenApi from '../internal/OpenApi.js'
+import * as Passkey from '../internal/Passkey.js'
+import * as RateLimit from '../internal/RateLimit.js'
+import * as Realm from '../internal/Realm.js'
+import * as SignInGrant from '../internal/SignInGrant.js'
+import * as TempoAccount from '../internal/TempoAccount.js'
+import * as Timing from '../internal/Timing.js'
+import * as Wallet from '../internal/Wallet.js'
+import * as AccountStep from './lib/AccountStep.js'
+import * as Auth from './lib/Auth.js'
+import * as Cors from './lib/Cors.js'
+import { db } from './lib/Database.js'
+import * as FirstAccount from './lib/FirstAccount.js'
+import * as Headless from './lib/Headless.js'
+import * as PasskeyLink from './lib/PasskeyLink.js'
+import * as Session from './lib/Session.js'
+import * as SignInConsent from './lib/SignInConsent.js'
+
+/** A hostname label: 1 to 63 letters, digits, and hyphens, with no hyphen at either end. */
+const hostnameLabel = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/
+
+namespace schema {
+  export namespace code {
+    export const json = z.object({
+      email: z
+        .string()
+        .trim()
+        .toLowerCase()
+        .pipe(
+          // A malformed or long address stops at its first failed check, so the refusal names it once.
+          z
+            .email({ abort: true })
+            .max(254, { abort: true, error: 'Invalid email address' })
+            // The email service refuses a local part over 64 characters, and a domain label that is
+            // not a hostname label: over 63 characters, or with a hyphen at either end.
+            .refine((value) => {
+              const [local = '', domain = ''] = value.split('@')
+              return (
+                local.length <= 64 &&
+                domain.split('.').every((label) => hostnameLabel.test(label))
+              )
+            }, 'Invalid email address'),
+        )
+        .meta({
+          description: "The user's email address.",
+          examples: ['ada@example.com'],
+        }),
+    })
+
+    export const response = z.object({
+      sent: z.literal(true).meta({
+        description:
+          'The request is accepted. The value is the same for every address.',
+      }),
+    })
+  }
+
+  export namespace verify {
+    export const json = z
+      .object({
+        assertion: Passkey.schema.assertion.optional().meta({
+          description:
+            "The assertion of the email step's passkey, over a challenge from `POST /v1/auth/passkey/options` with `link`. Required with `link`, since only the person who holds the passkey can link it.",
+        }),
+        authorize: Authorize.schema.request.optional().meta({
+          description:
+            "The app's headless authorization request, as `POST /v1/authorize` takes it, from a first-party app's page. The sign-in then authorizes the app in the same request, creates a first Tempo Account for a user who holds none, and returns the authorization. A refusal that depends only on the app and the request, such as a key over the headless ceiling, comes before the sign-in and leaves the code unspent. A refusal of the authorization server after the sign-in, such as for a scope that the app's registration lacks, spends the code. Not with `link` or `oauth_query`.",
+        }),
+        code: z
+          .string()
+          .trim()
+          .regex(/^\d{6}$/)
+          .meta({
+            description: 'The six-digit emailed code.',
+            examples: ['123456'],
+          }),
+        email: code.json.shape.email,
+        link: z
+          .string()
+          .max(64)
+          .optional()
+          .meta({
+            description:
+              "The email step's `link`, which links the wallet.tempo passkey that asked for it to this user, with that passkey's `assertion`. An expired link refuses the sign-in with `passkey_link_expired`, and the code stays valid.",
+            examples: ['dGhlIG5vbmNlIHRoYXQgdGhlIHN0ZXAgY2Fycmllcw'],
+          }),
+        passkey: z.literal(true).optional().meta({
+          description:
+            "With `authorize`, requests the passkey step for an account that a passkey owns, in place of `webauthn_required`. The response's `authorization` is then the step, which the page signs, and `POST /v1/authorize` with `passkey: { assertion }` signs the key.",
+        }),
+        // The bound covers an authorization request's query, and limits what an unsigned query can
+        // write, since the passkey challenge stores its client ID before the signature is checked.
+        oauth_query: z
+          .string()
+          .max(8192)
+          .optional()
+          .meta({
+            description:
+              "The sign-in page's query string, which Better Auth signs when an app's authorization request sends the browser there. At most 8,192 characters.",
+            examples: [
+              'client_id=client_01JZ8Q6W3N1R5B4V7C2X9K0M3T&response_type=code&exp=1760000000&sig=Gx3kB0',
+            ],
+          }),
+      })
+      .refine((value) => !value.link || value.assertion, {
+        message: 'Required with `link`.',
+        path: ['assertion'],
+      })
+      .refine(
+        (value) => !value.authorize || (!value.link && !value.oauth_query),
+        {
+          message: 'Not allowed with `link` or `oauth_query`.',
+          path: ['authorize'],
+        },
+      )
+
+    /** The user fields that the API returns. */
+    export const user = z
+      .object({
+        email: z.email().meta({
+          description: "The user's email address.",
+          examples: ['ada@example.com'],
+        }),
+        id: z.string().meta({
+          description:
+            "The user's ID, which is the `sub` of every token Tempo ID issues for the user.",
+          examples: ['user_01JZ8Q6W3N1R5B4V7C2X9K0M3T'],
+        }),
+      })
+      .meta({ description: 'The signed-in user.', id: 'User' })
+
+    export const response = z.object({
+      authorization: z
+        .union([Authorize.schema.response, Passkey.schema.headlessStep])
+        .optional()
+        .meta({
+          description:
+            "The app's headless authorization, for a sign-in that carried `authorize`, or a sign-in with key signature on the app's page whose options carried it. With `passkey`, the passkey step for a passkey-owned account. Absent for any other sign-in.",
+        }),
+      redirect: z
+        .url()
+        .nullable()
+        .meta({
+          description:
+            "Where the browser continues: the app's `redirect_uri` with an authorization code, or `null` for a sign-in that no app waits on.",
+          examples: [
+            'https://app.example.com/callback?code=SplxlOBeZQQYbYS6WxSbIA',
+          ],
+        }),
+      user,
+    })
+
+    /** What Better Auth returns: the user, or the authorization that the sign-in continued. */
+    export const signedIn = z.union([
+      z.object({ url: z.string() }),
+      z.object({ user: z.object({ email: z.string(), id: z.string() }) }),
+    ])
+  }
+
+  export namespace passkeyOptions {
+    export const json = z
+      .object({
+        authorize: Authorize.schema.request.optional().meta({
+          description:
+            "The app's headless authorization request, as `POST /v1/authorize` takes it, from a first-party app's page. The challenge is then the digest of its key, so the passkey's one assertion signs the user in and signs the key, and `POST /v1/auth/passkey/verify` returns the authorization. Requires `client_id`, the same as its own.",
+        }),
+        client_id: z
+          .string()
+          .min(1)
+          .max(64)
+          .optional()
+          .meta({
+            description:
+              "The client ID of the first-party app whose page runs the ceremony, which selects the app's realms. Required from an app's page, whose `Origin` must be one of the app's redirect URI origins.",
+            examples: ['client_01JZ8Q6W3N1R5B4V7C2X9K0M3T'],
+          }),
+        credentialId: z
+          .union([
+            Passkey.schema.credentialId,
+            z.array(Passkey.schema.credentialId).max(16),
+          ])
+          .optional()
+          .meta({
+            description:
+              'The credential ID, or up to 16 IDs, that the browser offers as `allowCredentials`, base64url. Defaults to every discoverable passkey of the relying party, as an empty list does.',
+            examples: ['KEbWNCc7NgaYnUyrNeFGX9_3Y-8'],
+          }),
+        link: verify.json.shape.link.meta({
+          description:
+            "The email step's `link`, which limits the options to that step's passkey, in place of `credentialId`. The emailed-code sign-in then sends the passkey's assertion with the `link`.",
+          examples: ['dGhlIG5vbmNlIHRoYXQgdGhlIHN0ZXAgY2Fycmllcw'],
+        }),
+        mediation: z
+          .enum(['conditional', 'optional', 'required', 'silent'])
+          .optional()
+          .meta({
+            description:
+              'Returned in the options for `navigator.credentials.get()`, such as `conditional` for passkey autofill.',
+            examples: ['conditional'],
+          }),
+        oauth_query: verify.json.shape.oauth_query,
+        user_code: z
+          .string()
+          .max(32)
+          .optional()
+          .meta({
+            description:
+              "The user code of the device grant that the sign-in returns to, ignored with `oauth_query` or `client_id`. A pending, unbound code selects its app's realms, and any other code selects the `default` realm.",
+            examples: ['WDJB-MJHT'],
+          }),
+      })
+      .refine(
+        (value) =>
+          !value.authorize || value.authorize.client_id === value.client_id,
+        { message: 'Requires the same `client_id`.', path: ['authorize'] },
+      )
+
+    /** The `authorize` field as the page sent it, which the challenge stores with its expiry filled. */
+    export const sent = z.object({
+      authorize: z.looseObject({
+        key_authorization: z.looseObject({}).optional(),
+      }),
+    })
+
+    export const response = z.object({
+      options: z
+        .object({
+          mediation: passkeyOptions.json.shape.mediation,
+          publicKey: z
+            .object({
+              allowCredentials: z
+                .array(
+                  z
+                    .object({
+                      id: z.string().meta({
+                        description: 'A credential ID, base64url.',
+                        examples: ['KEbWNCc7NgaYnUyrNeFGX9_3Y-8'],
+                      }),
+                      type: z.literal('public-key').meta({
+                        description: 'The credential type.',
+                      }),
+                    })
+                    .meta({ description: 'A passkey the browser offers.' }),
+                )
+                .optional()
+                .meta({
+                  description:
+                    'The passkeys the browser offers, from `credentialId`. Absent, it offers every discoverable passkey of the relying party.',
+                }),
+              challenge: z.templateLiteral(['0x', z.string()]).meta({
+                description:
+                  'The single-use challenge, as hex. It expires after 5 minutes.',
+                examples: [
+                  '0xf6310589abb21116acc6e123967ed0a125b5041c43f8e157237093e07eaa354c',
+                ],
+              }),
+              rpId: z.string().meta({
+                description: 'The relying party ID of the passkeys.',
+                examples: ['tempo.xyz'],
+              }),
+              userVerification: z.literal('required').meta({
+                description:
+                  'Every passkey sign-in requires user verification.',
+              }),
+            })
+            .meta({
+              description:
+                'The `PublicKeyCredentialRequestOptions`, serialized with the challenge as hex.',
+            }),
+        })
+        .meta({
+          description: 'The options for `navigator.credentials.get()`.',
+        }),
+    })
+  }
+
+  export namespace passkeyVerify {
+    export const json = z.object({
+      assertion: Passkey.schema.assertion,
+      oauth_query: verify.json.shape.oauth_query,
+    })
+
+    export const response = z.union([
+      verify.response.meta({ description: 'The signed-in user.' }),
+      z
+        .object({
+          step: z
+            .object({
+              link: z.string().meta({
+                description:
+                  'Send as `link` with the emailed-code sign-in, which links the passkey to that user.',
+                examples: ['dGhlIG5vbmNlIHRoYXQgdGhlIHN0ZXAgY2Fycmllcw'],
+              }),
+              signed: z.literal(false).meta({
+                description:
+                  'Whether the assertion already signed a key authorization. This route signs none.',
+              }),
+              type: z.literal('email').meta({
+                description:
+                  'Sign in with an emailed code, which links the passkey to that user.',
+              }),
+            })
+            .meta({
+              description:
+                'The email step, for a wallet.tempo passkey whose account has no email.',
+            }),
+        })
+        .meta({
+          description:
+            'A passkey sign-in that continues when the user verifies an email address.',
+        }),
+    ])
+  }
+
+  export namespace logout {
+    export const response = z.object({
+      signed_out: z.literal(true).meta({
+        description: 'The session is over, or there was none.',
+      }),
+    })
+  }
+
+  export namespace session {
+    export const response = z.object({
+      user: verify.user
+        .extend({
+          name: z
+            .string()
+            .nullable()
+            .meta({
+              description:
+                "The user's name, or `null` for a user who signed up without one.",
+              examples: ['Ada Lovelace'],
+            }),
+        })
+        .nullable()
+        .meta({
+          description: 'The signed-in user, or `null` without a session.',
+          id: 'SessionUser',
+        }),
+    })
+  }
+
+  export namespace assets {
+    export const response = z.object({
+      assets: z
+        .array(
+          z.string().meta({
+            description:
+              "The path of a script or style sheet on Tempo ID's origin.",
+            examples: ['/assets/index-QK4GWdO3.js'],
+          }),
+        )
+        .meta({
+          description:
+            "The sign-in page's scripts and style sheets, each once.",
+          examples: [
+            ['/assets/index-QK4GWdO3.js', '/assets/zyzz-DYC-X0_B.css'],
+          ],
+        }),
+    })
+  }
+
+  export namespace methods {
+    export const query = z.object({
+      oauth_query: verify.json.shape.oauth_query,
+      return_to: z
+        .string()
+        .max(2048)
+        .optional()
+        .meta({
+          description:
+            "The page that sign-in returns to, from the sign-in page's query. Only a path on the device page passes, and any other value reads as absent.",
+          examples: ['/device?code=WDJB-MJHT'],
+        }),
+    })
+
+    export const response = z.object({
+      passkeys: z.boolean().meta({
+        description:
+          "Whether one of the sign-in's realms holds passkeys that sign in at Tempo ID's origin, so the page offers passkey sign-in.",
+        examples: [true],
+      }),
+      app: z
+        .string()
+        .nullable()
+        .meta({
+          description:
+            'The display name of the app of the request in `oauth_query`, or its client ID without a name. `null` for a forged or expired query, or an unknown app.',
+          examples: ['Tempo Cash'],
+        }),
+      host: z
+        .string()
+        .nullable()
+        .meta({
+          description:
+            "The host of a third-party app's client ID, which the page shows beside its name, or `null` for a registered app or without an app.",
+          examples: ['app.example'],
+        }),
+      request: z
+        .object({
+          app: z.string().meta({
+            description:
+              "The app's display name, or its client ID without one.",
+            examples: ['Tempo Cash'],
+          }),
+          key: KeyAuthorization.schema.description,
+        })
+        .nullable()
+        .meta({
+          description:
+            'The app and the key of the signed authorization request in `oauth_query`, which the sign-in grants. `null` when the sign-in grants no key, such as for an invalid query or a third-party app.',
+        }),
+      return_to: z
+        .string()
+        .nullable()
+        .meta({
+          description:
+            'The page that sign-in returns to, a path on the device page, or `null` for the account.',
+          examples: ['/device?code=WDJB-MJHT'],
+        }),
+      user_code: z
+        .string()
+        .nullable()
+        .meta({
+          description:
+            'The user code of the device page that sign-in returns to, or `null` without one.',
+          examples: ['WDJBMJHT'],
+        }),
+      verified: z.boolean().meta({
+        description:
+          'Whether `app` is a registered app, whose name the page marks as verified. `false` for a third-party app, which names itself in its metadata document, and without an app.',
+        examples: [true],
+      }),
+    })
+  }
+}
+
+/**
+ * Returns the ID and stored address of the user with `email`, which wallet.tempo verified, and
+ * creates that user when none exists. A concurrent first sign-in can create the user first, so the
+ * read repeats.
+ */
+async function emailUser(c: Context<Env>, options: emailUser.Options) {
+  const email = options.email.trim().toLowerCase()
+  const context = await Timing.measure(c, c.var.auth.$context, 'auth.context')
+  const found = await Timing.measure(
+    c,
+    context.internalAdapter.findUserByEmail(email),
+    'db.user.findByEmail',
+  )
+  if (found) return { email: found.user.email, id: found.user.id }
+
+  try {
+    const created = await Timing.measure(
+      c,
+      context.internalAdapter.createUser(
+        { email, emailVerified: true, name: '' },
+        { method: 'passkey' },
+      ),
+      'db.user.create',
+    )
+    return { email: created.email, id: created.id }
+  } catch (error) {
+    // The user hook refuses a new user outside `SIGN_UP_DOMAINS`.
+    if (
+      isAPIError(error) &&
+      error.body?.code === core_Auth.SignUpNotPermittedError.reason
+    )
+      throw new core_Auth.SignUpNotPermittedError({
+        domains: Auth.signUpDomains() ?? [],
+      })
+    const again = await Timing.measure(
+      c,
+      context.internalAdapter.findUserByEmail(email),
+      'db.user.findByEmail',
+    )
+    if (again) return { email: again.user.email, id: again.user.id }
+    throw error
+  }
+}
+
+declare namespace emailUser {
+  type Options = {
+    /** The email address that wallet.tempo verified. */
+    email: string
+  }
+}
+
+namespace emailUser {
+  /** The refusals `emailUser` throws. */
+  export const errors = [core_Auth.SignUpNotPermittedError] as const
+}
+
+/** The sign-in routes under `/v1/auth`. */
+export const authenticate = new Hono<Env>()
+  .post(
+    '/v1/auth/code',
+    OpenApi.describeRoute({
+      description:
+        'Emails a sign-in code. The response is the same for every address, so it reveals no account.',
+      responses: OpenApi.responses({
+        errors: [
+          ...BodyLimit.errors,
+          ...Auth.sendCode.errors,
+          ...OpenApi.validate.errors,
+          ...RateLimit.check.errors,
+          ErrorResponse.CrossSiteRequestError,
+          ErrorResponse.UpstreamUnavailableError,
+        ],
+        success: {
+          description:
+            'The response for every address: the email service accepted the code, or does not deliver to the address.',
+          schema: schema.code.response,
+        },
+      }),
+      tags: ['Authenticate'],
+    }),
+    OpenApi.validate('json', schema.code.json),
+    async (c) => {
+      const { email } = c.req.valid('json')
+      // The IP address's limit counts first, so a refused flood spends no address's sends.
+      const refused = await Timing.measure(
+        c,
+        RateLimit.check(c, {
+          limits: [
+            { binding: 'SIGN_IN_IP_LIMIT', key: RateLimit.ip(c) },
+            { binding: 'SIGN_IN_CODE_LIMIT', key: RateLimit.email({ email }) },
+          ],
+        }),
+        'RateLimit.check',
+      )
+      if (refused) return refused
+
+      // The Workers limits count each location on its own, so the database counts the address's
+      // codes across every location.
+      const within = await Timing.measure(
+        c,
+        RateLimit.countCode(db, { email }),
+        'RateLimit.countCode',
+      )
+      if (!within) {
+        RateLimit.describe(c, { policy: RateLimit.codePolicy })
+        return RateLimit.refuse(c, {
+          policy: RateLimit.codePolicy,
+          retryAfter: RateLimit.codePolicy.window,
+        })
+      }
+
+      // Every address receives a code, so the response reveals no account. The route waits for the
+      // email service, so a failed send refuses the request instead of a sign-in that never arrives.
+      const code = await Timing.measure(
+        c,
+        c.var.auth.api.createVerificationOTP({
+          body: { email, type: 'sign-in' },
+        }),
+        'auth.createVerificationOTP',
+      )
+      const failure = await Timing.measure(
+        c,
+        Auth.sendCode(c, { code, email: email.toLowerCase() }),
+        'Auth.sendCode',
+      ).catch((error: unknown) => error)
+      if (failure) {
+        // The refusal is the email service's, as for any upstream service, so it is a warning.
+        Log.warn(c, {
+          error: failure,
+          message: 'The email service refused a sign-in code.',
+        })
+        // A refusal of the address itself responds as a sent code, so the response is the same for
+        // every address. The email service's rate limit is one the caller can wait out. Any other
+        // refusal is an outage.
+        if (!(failure instanceof Auth.UndeliverableError))
+          return ErrorResponse.json(
+            c,
+            failure instanceof ErrorResponse.RateLimitedError
+              ? failure
+              : new ErrorResponse.UpstreamUnavailableError(),
+          )
+      }
+
+      return c.json({ sent: true as const }, 200)
+    },
+  )
+  .post(
+    '/v1/auth/code/verify',
+    OpenApi.describeRoute({
+      description:
+        'Signs in with an emailed code, and sets the session cookie. For a user with no Tempo Account in the first realm of the app that `oauth_query` names, or in the `default` realm, it creates one when that realm creates accounts. A failed creation leaves the user signed in, and the next sign-in or `POST /v1/account` creates the account. With `authorize`, it also authorizes the app as `POST /v1/authorize` does, and a refusal after the sign-in carries `Tempo-Id-Signed-In: true`.',
+      responses: OpenApi.responses({
+        errors: [
+          ...BodyLimit.errors,
+          ...Cors.ownPage.errors,
+          ...OpenApi.validate.errors,
+          ...Headless.afterCode.errors,
+          ...Headless.check.errors,
+          ...Headless.keySignature.errors,
+          ...RateLimit.check.errors,
+          core_Auth.AuthorizationExpiredError,
+          core_Auth.InvalidCodeError,
+          core_Auth.SignUpNotPermittedError,
+          Passkey.LinkExpiredError,
+          Passkey.WebAuthnRejectedError,
+        ],
+        success: {
+          description: 'The signed-in user.',
+          schema: schema.verify.response,
+        },
+      }),
+      tags: ['Authenticate'],
+    }),
+    OpenApi.validate('json', schema.verify.json),
+    async (c) => {
+      const { assertion, authorize, code, email, link, oauth_query, passkey } =
+        c.req.valid('json')
+      const crossSite = Cors.ownPage(c, { oauth_query })
+      if (crossSite) return ErrorResponse.json(c, crossSite)
+      // Better Auth counts the guesses at each code. The IP address's limit bounds guesses across
+      // addresses.
+      const refused = await Timing.measure(
+        c,
+        RateLimit.check(c, {
+          limits: [{ binding: 'SIGN_IN_IP_LIMIT', key: RateLimit.ip(c) }],
+        }),
+        'RateLimit.check',
+      )
+      if (refused) return refused
+
+      // The app's request is checked as a headless one before the code, so a refused request leaves
+      // the code unspent.
+      const app = authorize
+        ? await Timing.measure(
+            c,
+            Headless.app(c, { clientId: authorize.client_id }),
+            'Headless.app',
+          )
+        : undefined
+      const refusesAuthorize =
+        authorize &&
+        Headless.check(authorize, { app, origin: c.req.header('origin') })
+      if (refusesAuthorize) return ErrorResponse.json(c, refusesAuthorize)
+
+      // The email step's link is checked before the code, so an expired one refuses the sign-in and
+      // leaves the code unspent. The sign-in then never ends without the passkey it was meant to link.
+      const deferred = link
+        ? await Timing.measure(
+            c,
+            PasskeyLink.claim(c, { nonce: link }),
+            'PasskeyLink.claim',
+          )
+        : undefined
+      if (link && !deferred)
+        return ErrorResponse.json(c, new Passkey.LinkExpiredError())
+
+      // The link's passkey signs again before the code is checked, so a page left at the email step
+      // links nothing for the next person, and a refusal leaves the code unspent. On an app's page,
+      // that assertion can sign the key of the request that the options carried, as a digest
+      // sign-in does.
+      const challenge =
+        deferred && assertion
+          ? await Timing.measure(
+              c,
+              Passkey.take(db, {
+                clientDataJSON: assertion.metadata.clientDataJSON,
+              }),
+              'Passkey.take',
+            )
+          : undefined
+      if (deferred) {
+        // Only a challenge that the options issued for this link confirms it.
+        const bound =
+          challenge && link
+            ? await Timing.measure(
+                c,
+                PasskeyLink.matches({ expected: challenge.link, nonce: link }),
+                'PasskeyLink.matches',
+              )
+            : false
+        if (
+          !assertion ||
+          !challenge ||
+          !bound ||
+          challenge.clientId !== client({ oauth_query }) ||
+          challenge.origin !== Cors.appOrigin(c) ||
+          challenge.rpId !== deferred.rpId ||
+          assertion.id !== deferred.id ||
+          !Passkey.verify(assertion, {
+            challenge: challenge.challenge,
+            origin: challenge.origin ?? new URL(env.URL).origin,
+            publicKey: deferred.publicKey,
+            rpId: deferred.rpId,
+          }) ||
+          !(await Timing.measure(
+            c,
+            Headless.spend(c, { assertion, challenge }),
+            'Headless.spend',
+          ))
+        )
+          return ErrorResponse.json(c, new Passkey.WebAuthnRejectedError())
+      }
+
+      const result = await Timing.measure(
+        c,
+        c.var.auth.api.signInEmailOTP({
+          // A call with a request returns a `Response` unless `asResponse` is false.
+          asResponse: false,
+          body: { email, otp: code, ...(oauth_query ? { oauth_query } : {}) },
+          // Better Auth sets `accept` to continue an authorization as JSON, and a request's own headers
+          // are immutable.
+          headers: new Headers(c.req.raw.headers),
+          // Better Auth continues an authorization only for a call that carries its request.
+          request: c.req.raw,
+          returnHeaders: true,
+        }),
+        'auth.signInEmailOTP',
+      ).catch((error: unknown) => {
+        // Better Auth checks the authorization request's signature before the code, so a forged or
+        // expired one leaves the code unspent.
+        if (isAPIError(error) && error.body?.error === 'invalid_signature')
+          return new core_Auth.AuthorizationExpiredError()
+        // The user hook refuses a new user outside `SIGN_UP_DOMAINS`, after the code verifies.
+        if (
+          isAPIError(error) &&
+          error.body?.code === core_Auth.SignUpNotPermittedError.reason
+        )
+          return new core_Auth.SignUpNotPermittedError({
+            domains: Auth.signUpDomains() ?? [],
+          })
+        // Better Auth refuses a wrong, expired, or spent code, and a code past its guesses. Any other
+        // failure fails the request.
+        if (isAPIError(error)) return new core_Auth.InvalidCodeError()
+        throw error
+      })
+      if (result instanceof ErrorResponse.ResponseError)
+        return ErrorResponse.json(c, result)
+
+      for (const cookie of result.headers.getSetCookie())
+        c.header('set-cookie', cookie, { append: true })
+      c.header('cache-control', 'private, no-store')
+
+      // With `oauth_query`, Better Auth continues the app's authorization once the session exists, and
+      // returns its redirect in place of the user.
+      const signedIn = schema.verify.signedIn.parse(result.response)
+      const user = (() => {
+        if ('user' in signedIn)
+          return { email: signedIn.user.email, id: signedIn.user.id }
+        // Better Auth signs in the user whose address is the lowercase `email`, and the session
+        // that it created names that user.
+        const id = c.var.newSession?.user.id
+        if (!id) throw new Error('The signed-in user is missing.')
+        return { email, id }
+      })()
+
+      // The email step's passkey links to the user that the code signed in.
+      if (deferred) {
+        const linked = await Timing.measure(
+          c,
+          Passkey.link(db, {
+            credential: deferred,
+            id: deferred.id,
+            rpId: deferred.rpId,
+            userId: user.id,
+          }),
+          'Passkey.link',
+        )
+        // The account step of the sign-in listed the user's keys before the link.
+        TempoAccount.forget(c)
+        // A concurrent sign-in can link the passkey to another user first. Its row decides, so this
+        // sign-in links nothing, and the cookie stays until it expires.
+        if (linked === user.id) PasskeyLink.release(c)
+      }
+
+      // A linked passkey owns its account, so the first account follows the link. The sign-in grant
+      // below can then sign the key with it.
+      await Timing.measure(
+        c,
+        FirstAccount.create(c, {
+          clientId: client({ oauth_query }),
+          // Better Auth signs in the user of the lowercase address.
+          email: user.email.toLowerCase(),
+          userId: user.id,
+        }),
+        'FirstAccount.create',
+      )
+
+      // The link's assertion signs the key of the request that its options carried.
+      if (challenge?.authorize !== undefined && assertion) {
+        // The session exists, so the page reads any refusal from here, thrown ones included, as
+        // one after the sign-in.
+        c.header(Headless.signedInHeader, 'true')
+        const authorization = await Timing.measure(
+          c,
+          Headless.keySignature(c, {
+            assertion,
+            challenge,
+            email: user.email,
+            setCookie: result.headers.getSetCookie(),
+          }),
+          'Headless.keySignature',
+        )
+        if (authorization instanceof Response) return authorization
+        if (authorization instanceof ErrorResponse.ResponseError)
+          return ErrorResponse.json(c, authorization)
+        return c.json({ authorization, redirect: null, user }, 200)
+      }
+
+      // The app's request authorizes in the same request, after the code signed the user in.
+      if (authorize && app) {
+        // The session exists, so the page reads any refusal from here, thrown ones included, as one
+        // after the sign-in.
+        c.header(Headless.signedInHeader, 'true')
+        const authorization = await Timing.measure(
+          c,
+          Headless.afterCode(c, {
+            app,
+            email: user.email,
+            passkey,
+            request: authorize,
+            setCookie: result.headers.getSetCookie(),
+          }),
+          'Headless.afterCode',
+        )
+        if (authorization instanceof Response) return authorization
+        if (authorization instanceof ErrorResponse.ResponseError)
+          return ErrorResponse.json(c, authorization)
+        // A passkey signs only in the browser, so the page signs the digest and repeats the request
+        // at `POST /v1/authorize`.
+        if ('options' in authorization)
+          return c.json(
+            {
+              authorization: Passkey.schema.headlessStep.parse({
+                expiry: authorization.expiry,
+                step: { options: authorization.options, type: 'passkey' },
+              }),
+              redirect: null,
+              user,
+            },
+            200,
+          )
+        return c.json({ authorization, redirect: null, user }, 200)
+      }
+
+      // The sign-in page showed the request's key, so the sign-in grants it.
+      const redirect =
+        'user' in signedIn
+          ? null
+          : await Timing.measure(
+              c,
+              SignInConsent.afterSignIn(c, {
+                redirect: signedIn.url,
+                setCookie: result.headers.getSetCookie(),
+              }),
+              'SignInConsent.afterSignIn',
+            )
+      return c.json({ redirect, user }, 200)
+    },
+  )
+  .post(
+    '/v1/auth/passkey/options',
+    OpenApi.describeRoute({
+      description:
+        "Issues a single-use challenge, and returns request options for the passkeys of the first realm whose relying party covers Tempo ID's origin, and also the page's origin from an app's page. The realms are those of the app that `oauth_query`, `client_id`, or `user_code` names, or the `default` realm. With `link`, that realm must be the `default` realm at the link's relying party.",
+      responses: OpenApi.responses({
+        errors: [
+          ...BodyLimit.errors,
+          ...Cors.ownPage.errors,
+          ...OpenApi.validate.errors,
+          ...Authorize.check.errors,
+          ...Passkey.checkPage.errors,
+          ...RateLimit.check.errors,
+          Passkey.LinkExpiredError,
+          Passkey.NotPermittedError,
+        ],
+        success: {
+          description: 'The request options.',
+          schema: schema.passkeyOptions.response,
+        },
+      }),
+      tags: ['Authenticate'],
+    }),
+    OpenApi.validate('json', schema.passkeyOptions.json),
+    async (c) => {
+      const {
+        authorize,
+        client_id,
+        credentialId,
+        link,
+        mediation,
+        oauth_query,
+        user_code,
+      } = c.req.valid('json')
+      const crossSite = Cors.ownPage(c, { oauth_query })
+      if (crossSite) return ErrorResponse.json(c, crossSite)
+      // Each view of the sign-in page requests options for its autofill, so the options requests
+      // count on their own key, and spend none of the address's quota for email sign-in.
+      const ip = RateLimit.ip(c)
+      const refused = await Timing.measure(
+        c,
+        RateLimit.check(c, {
+          limits: [
+            {
+              binding: 'SIGN_IN_IP_LIMIT',
+              key: ip ? `passkey-options:${ip}` : undefined,
+            },
+          ],
+        }),
+        'RateLimit.check',
+      )
+      if (refused) return refused
+
+      const deferred = link
+        ? await Timing.measure(
+            c,
+            PasskeyLink.claim(c, { nonce: link }),
+            'PasskeyLink.claim',
+          )
+        : undefined
+      if (link && !deferred)
+        return ErrorResponse.json(c, new Passkey.LinkExpiredError())
+
+      // A first-party app's page runs the ceremony at its own origin, which the challenge stores.
+      // Only an assertion for that origin, from a request that origin sends, spends it.
+      const page = Cors.appOrigin(c)
+      const app = client_id
+        ? await Timing.measure(
+            c,
+            // A disabled app can share its origin with an enabled one, which CORS admits.
+            Headless.app(c, { clientId: client_id }),
+            'Headless.app',
+          )
+        : undefined
+      if (page || client_id) {
+        const refusal = Passkey.checkPage({
+          app,
+          clientId: client_id,
+          origin: c.req.header('origin'),
+        })
+        if (refusal) return ErrorResponse.json(c, refusal)
+      }
+
+      // The signature of `oauth_query` is checked when the session is created. Until then, its app
+      // selects only the relying party. An app's page continues no authorization, so its challenge
+      // names no app.
+      const clientId = client({ oauth_query })
+      // A device app comes from the code's own row, never from the request, and selects only the
+      // relying party, so the challenge names no app.
+      const userCode = user_code ? Device.normalize(user_code) : undefined
+      const deviceApp =
+        !clientId && !client_id && userCode
+          ? await Timing.measure(
+              c,
+              Device.client(db, { userCode }),
+              'Device.client',
+            )
+          : undefined
+      const appId = clientId ?? client_id ?? deviceApp
+      const stored = appId
+        ? await Timing.measure(
+            c,
+            Cache.read(c, () => Realm.forApp(db, { clientId: appId }), [
+              'realm.forApp',
+              appId,
+            ]),
+            'Realm.forApp',
+          )
+        : [
+            await Timing.measure(
+              c,
+              Cache.read(c, () => Realm.get(db, { id: Realm.defaultId }), [
+                'realm.get',
+                Realm.defaultId,
+              ]),
+              'Realm.get',
+            ),
+          ]
+      const realms = await Timing.measure(
+        c,
+        Realm.withDefaults(c, { db, origin: env.URL, realms: stored }),
+        'Realm.withDefaults',
+      )
+      const relyingParty = Passkey.relyingParty(realms, {
+        origin: env.URL,
+        page,
+      })
+      // Only a challenge of the `default` realm reads wallet.tempo, so a link's passkey signs again
+      // only for a sign-in whose realms select that realm, at the link's relying party.
+      const refusesLink =
+        deferred &&
+        (relyingParty?.realmId !== Realm.defaultId ||
+          relyingParty.rpId !== deferred.rpId)
+      if (!relyingParty || refusesLink)
+        return ErrorResponse.json(
+          c,
+          new Passkey.NotPermittedError({
+            // A device app stays unnamed, so the refusal names no app that a code reveals.
+            clientId: (clientId ?? client_id) || undefined,
+            origin: page,
+          }),
+        )
+
+      // A challenge for a link stores the link's digest, so only that link's code sign-in takes it.
+      const linked = link
+        ? await Timing.measure(
+            c,
+            PasskeyLink.digest({ nonce: link }),
+            'PasskeyLink.digest',
+          )
+        : undefined
+      // On an app's page, the request is checked as a headless one before the ceremony, so a key
+      // over the headless ceiling signs nothing. Its key's expiry is filled now, so the request that
+      // the sign-in runs has the digest that the passkey signs.
+      const refusesAuthorize =
+        authorize &&
+        (page
+          ? Authorize.check(authorize, { app, origin: c.req.header('origin') })
+          : new Authorize.InvalidOriginError({
+              error_description:
+                "Invalid `Origin`: none. A sign-in with `authorize` runs only on the app's page.",
+              field: 'Origin',
+            }))
+      if (refusesAuthorize) return ErrorResponse.json(c, refusesAuthorize)
+      const pinned = await (async () => {
+        if (!authorize) return undefined
+        const sent = schema.passkeyOptions.sent.parse(await c.req.json())
+        const key = authorize.key_authorization
+        return key
+          ? {
+              ...sent.authorize,
+              key_authorization: {
+                ...sent.authorize.key_authorization,
+                expiry: key.expiry,
+              },
+            }
+          : sent.authorize
+      })()
+
+      // The challenge of a request with a key is the key's digest, so one passkey assertion signs in
+      // and signs the key: on the sign-in page for the request it continues, and on an app's page for
+      // `authorize`. A link's step on the sign-in page signs in only. The witness is the request's
+      // own, from its `challenge`, or a random one.
+      const keyChallenge = await (async () => {
+        if (page) {
+          const key = authorize?.key_authorization
+          if (!key) return undefined
+          const witness =
+            key.witness ??
+            Hex.fromBytes(crypto.getRandomValues(new Uint8Array(32)))
+          return {
+            digest: KeyAuthorization.digest({ key, witness }),
+            witness,
+          }
+        }
+        if (!oauth_query || link) return undefined
+        return await Timing.measure(
+          c,
+          SignInConsent.keyChallenge(c, { oauthQuery: oauth_query }),
+          'SignInConsent.keyChallenge',
+        )
+      })()
+      const challenge = await Timing.measure(
+        c,
+        Passkey.challenge(db, {
+          authorize: pinned,
+          clientId,
+          keyChallenge,
+          link: linked,
+          origin: page,
+          ...relyingParty,
+        }),
+        'Passkey.challenge',
+      )
+      // A pending challenge holds the same key challenge, which only an app's challenge repeats.
+      if (!challenge)
+        return ErrorResponse.json(c, new Passkey.WebAuthnRejectedError())
+      // Without a credential ID, the browser offers every discoverable passkey of the relying party,
+      // as WebAuthn defines for an empty list. The challenge stays Tempo ID's either way.
+      const allowed = (() => {
+        if (deferred) return [deferred.id]
+        return credentialId === undefined ? [] : [credentialId].flat()
+      })()
+      const options = schema.passkeyOptions.response.shape.options.parse({
+        ...Authentication.getOptions({
+          challenge,
+          ...(allowed.length > 0 ? { credentialId: allowed } : {}),
+          rpId: relyingParty.rpId,
+          userVerification: 'required',
+        }).options,
+        ...(mediation ? { mediation } : {}),
+      })
+      c.header('cache-control', 'private, no-store')
+      return c.json({ options }, 200)
+    },
+  )
+  .post(
+    '/v1/auth/passkey/verify',
+    OpenApi.describeRoute({
+      description:
+        'Signs in with a passkey assertion over a challenge from `POST /v1/auth/passkey/options`, and sets the session cookie. For a user with no Tempo Account in the first realm of the app that `oauth_query` names, or in the `default` realm, it creates one when that realm creates accounts. A failed creation leaves the user signed in, and the next sign-in or `POST /v1/account` creates the account.',
+      responses: OpenApi.responses({
+        errors: [
+          ...BodyLimit.errors,
+          ...Cors.ownPage.errors,
+          ...OpenApi.validate.errors,
+          ...ErrorResponse.fromUpstream.errors,
+          ...Headless.keySignature.errors,
+          ...RateLimit.check.errors,
+          ...emailUser.errors,
+          core_Auth.AuthorizationExpiredError,
+          Passkey.WebAuthnRejectedError,
+        ],
+        success: {
+          description:
+            'The signed-in user, with the authorization of a sign-in with key signature, or the email step for a wallet.tempo passkey without an email.',
+          schema: schema.passkeyVerify.response,
+        },
+      }),
+      tags: ['Authenticate'],
+    }),
+    OpenApi.validate('json', schema.passkeyVerify.json),
+    async (c) => {
+      const { assertion, oauth_query } = c.req.valid('json')
+      const crossSite = Cors.ownPage(c, { oauth_query })
+      if (crossSite) return ErrorResponse.json(c, crossSite)
+      const refused = await Timing.measure(
+        c,
+        RateLimit.check(c, {
+          limits: [{ binding: 'SIGN_IN_IP_LIMIT', key: RateLimit.ip(c) }],
+        }),
+        'RateLimit.check',
+      )
+      if (refused) return refused
+
+      // The challenge is spent before any other check, so a failed attempt cannot be retried. The
+      // same statement reads the passkey and its user.
+      const { id } = assertion
+      const taken = await Timing.measure(
+        c,
+        Passkey.takeWithKey(db, {
+          clientDataJSON: assertion.metadata.clientDataJSON,
+          id,
+        }),
+        'Passkey.takeWithKey',
+      )
+      const challenge = taken?.challenge
+      // A challenge serves only the sign-in it was issued for: the same app, or none, from the same
+      // page. A challenge for an email step's link serves only that link's code sign-in.
+      if (
+        !challenge ||
+        challenge.link !== undefined ||
+        challenge.clientId !== client({ oauth_query }) ||
+        challenge.origin !== Cors.appOrigin(c)
+      )
+        return ErrorResponse.json(c, new Passkey.WebAuthnRejectedError())
+
+      const key = taken.key
+      // A passkey that Tempo ID does not store yet may be wallet.tempo's, which shares the `default`
+      // realm's relying party, and links once it verifies.
+      const credential = await (async () => {
+        if (key || !c.env.WALLET || challenge.realmId !== Realm.defaultId)
+          return undefined
+        try {
+          return await Timing.measure(
+            c,
+            Wallet.credential(c.env.WALLET, { id }),
+            'Wallet.credential',
+          )
+        } catch (error) {
+          // Only the binding call throws, so the failure is wallet.tempo's.
+          Log.warn(c, {
+            error,
+            message: 'The wallet service failed a passkey lookup.',
+          })
+          return (
+            (error instanceof Error && ErrorResponse.fromUpstream(error)) ||
+            new ErrorResponse.UpstreamUnavailableError()
+          )
+        }
+      })()
+      if (credential instanceof ErrorResponse.ResponseError)
+        return ErrorResponse.json(c, credential)
+      const publicKey = key?.publicKey ?? credential?.publicKey
+      if (
+        !publicKey ||
+        !Passkey.verify(assertion, {
+          challenge: challenge.challenge,
+          origin: challenge.origin ?? new URL(env.URL).origin,
+          publicKey: publicKey as `0x${string}`,
+          rpId: challenge.rpId,
+        })
+      )
+        return ErrorResponse.json(c, new Passkey.WebAuthnRejectedError())
+      // An assertion of a sign-in with key signature on an app's page signs in once, whatever then
+      // signs the key.
+      const unspent = await Timing.measure(
+        c,
+        Headless.spend(c, { assertion, challenge }),
+        'Headless.spend',
+      )
+      if (!unspent)
+        return ErrorResponse.json(c, new Passkey.WebAuthnRejectedError())
+
+      // A wallet.tempo account without an email links once the user verifies one with a code.
+      if (credential && !credential.email) {
+        const link = await Timing.measure(
+          c,
+          PasskeyLink.defer(c, { credential, id, rpId: challenge.rpId }),
+          'PasskeyLink.defer',
+        )
+        c.header('cache-control', 'private, no-store')
+        return c.json(
+          { step: { link, signed: false, type: 'email' as const } },
+          200,
+        )
+      }
+
+      // The user whom the passkey signs in, with the address that the response returns, when the
+      // route already read it.
+      const signer = await (async () => {
+        if (key) return { user: key.user, userId: key.userId }
+        // wallet.tempo verified the email, so its user is found or created by that address.
+        const user = await Timing.measure(
+          c,
+          emailUser(c, { email: credential!.email! }),
+          'authenticate.emailUser',
+        )
+        const linked = await Timing.measure(
+          c,
+          Passkey.link(db, {
+            credential: credential!,
+            id,
+            rpId: challenge.rpId,
+            userId: user.id,
+          }),
+          'Passkey.link',
+        )
+        TempoAccount.forget(c)
+        // A concurrent first sign-in can link the passkey to another user, whose row decides.
+        return linked
+          ? { user: linked === user.id ? user : undefined, userId: linked }
+          : undefined
+      })()
+      // Another passkey holds the address that wallet.tempo returned.
+      if (!signer)
+        return ErrorResponse.json(c, new Passkey.WebAuthnRejectedError())
+      const { userId } = signer
+
+      // A sign-in that continues an app's request reads the user's accounts in the app's realms, so
+      // their Privy users load beside the session's creation, and so does the user's first account.
+      // The assertion already verified, and its challenge is spent. Both start only for a query that
+      // Better Auth signed and that has not expired, which the sign-in checks too, so a forged query
+      // creates no account in its app's realm.
+      const signed = await (async () => {
+        if (!oauth_query) return true
+        const context = await Timing.measure(
+          c,
+          c.var.auth.$context,
+          'auth.context',
+        )
+        return await Timing.measure(
+          c,
+          verifyOAuthQueryParams(oauth_query, context.secret),
+          'auth.verifyOAuthQueryParams',
+        )
+      })()
+      const appId = signed
+        ? (client({ oauth_query }) ??
+          Authorize.schema.request.safeParse(challenge.authorize).data
+            ?.client_id)
+        : undefined
+      // Every branch settles before the response, so a refused sign-in leaves no first account
+      // running after it. The other branches catch their own failures.
+      const [settled] = await Promise.allSettled([
+        Timing.measure(
+          c,
+          c.var.auth.api.signInPasskey({
+            asResponse: false,
+            body: {
+              userId,
+              ...(key ? { user: key.user } : {}),
+              ...(oauth_query ? { oauth_query } : {}),
+            },
+            // Better Auth sets `accept` to continue an authorization as JSON, and a request's own
+            // headers are immutable.
+            headers: new Headers(c.req.raw.headers),
+            request: c.req.raw,
+            returnHeaders: true,
+          }),
+          'auth.signInPasskey',
+        ).catch((error: unknown) => {
+          if (isAPIError(error) && error.body?.error === 'invalid_signature')
+            return new core_Auth.AuthorizationExpiredError()
+          throw error
+        }),
+        appId
+          ? Timing.measure(
+              c,
+              AccountStep.prefetch(c, { clientId: appId, userId }),
+              'AccountStep.prefetch',
+            )
+          : undefined,
+        // A linked or registered passkey owns its account, so only a sign-in passkey's user can
+        // receive one. The verified assertion signs the user in, so the account needs no session.
+        // The account step inside the sign-in finds at most this one account either way.
+        signed
+          ? Timing.measure(
+              c,
+              FirstAccount.create(c, {
+                clientId: client({ oauth_query }),
+                email: signer.user?.email,
+                userId,
+              }),
+              'FirstAccount.create',
+            )
+          : undefined,
+      ])
+      if (settled.status === 'rejected') throw settled.reason
+      const result = settled.value
+      if (result instanceof ErrorResponse.ResponseError)
+        return ErrorResponse.json(c, result)
+
+      for (const cookie of result.headers.getSetCookie())
+        c.header('set-cookie', cookie, { append: true })
+      c.header('cache-control', 'private, no-store')
+
+      // With `oauth_query`, Better Auth continues the app's authorization once the session exists, and
+      // returns its redirect in place of the user.
+      const signedIn = schema.verify.signedIn.parse(result.response)
+      if ('user' in signedIn) {
+        const user = { email: signedIn.user.email, id: signedIn.user.id }
+        if (challenge.authorize === undefined)
+          return c.json({ redirect: null, user }, 200)
+        // The session exists, so the page reads any refusal from here, thrown ones included, as
+        // one after the sign-in.
+        c.header(Headless.signedInHeader, 'true')
+        const authorization = await Timing.measure(
+          c,
+          Headless.keySignature(c, {
+            assertion,
+            challenge,
+            email: user.email,
+            setCookie: result.headers.getSetCookie(),
+          }),
+          'Headless.keySignature',
+        )
+        if (authorization instanceof Response) return authorization
+        if (authorization instanceof ErrorResponse.ResponseError)
+          return ErrorResponse.json(c, authorization)
+        return c.json({ authorization, redirect: null, user }, 200)
+      }
+      // The passkey's row or wallet.tempo's address named the user, so only a passkey that a
+      // concurrent sign-in linked to another user reads it again.
+      const user = await (async () => {
+        if (signer.user) return { email: signer.user.email, id: signer.user.id }
+        const [row] = await Timing.measure(
+          c,
+          db
+            .select({ email: Schema.user.email, id: Schema.user.id })
+            .from(Schema.user)
+            .where(eq(Schema.user.id, userId)),
+          'db.user.get',
+        )
+        return row
+      })()
+      if (!user) throw new Error('The signed-in user is missing.')
+
+      // The sign-in page showed the request's key, so the sign-in grants it. A key challenge was
+      // the key's digest, so the same assertion signs it for an account that this passkey owns.
+      const redirect = await Timing.measure(
+        c,
+        SignInConsent.afterSignIn(c, {
+          keySignature: challenge.witness
+            ? { assertion, witness: challenge.witness }
+            : undefined,
+          redirect: signedIn.url,
+          setCookie: result.headers.getSetCookie(),
+        }),
+        'SignInConsent.afterSignIn',
+      )
+      return c.json({ redirect, user }, 200)
+    },
+  )
+  .post(
+    '/v1/auth/logout',
+    OpenApi.describeRoute({
+      description:
+        'Signs out: ends the session, revokes the access and refresh tokens that apps received through it, and clears its cookie.',
+      responses: OpenApi.responses({
+        errors: [...BodyLimit.errors, ErrorResponse.CrossSiteRequestError],
+        success: {
+          description: 'The session is over.',
+          schema: schema.logout.response,
+        },
+      }),
+      tags: ['Authenticate'],
+    }),
+    async (c) => {
+      // One statement ends the session and its apps' tokens. Better Auth's sign-out takes six round
+      // trips, and runs only to expire the cookies.
+      const token = await Timing.measure(c, Session.token(c), 'Session.token')
+      if (token)
+        await Timing.measure(c, Logout.end(db, { token }), 'Logout.end')
+      await Timing.measure(c, Session.clear(c), 'Session.clear')
+      // The next sign-in chooses each app's account again.
+      c.header('set-cookie', AccountStep.clear(), { append: true })
+      c.header('cache-control', 'private, no-store')
+      return c.json({ signed_out: true as const }, 200)
+    },
+  )
+  .get(
+    '/v1/auth/session',
+    OpenApi.describeRoute({
+      description: 'Reads the signed-in user, or `null` without a session.',
+      responses: OpenApi.responses({
+        success: {
+          description: 'The session.',
+          schema: schema.session.response,
+        },
+      }),
+      tags: ['Authenticate'],
+    }),
+    async (c) => {
+      const session = await Timing.measure(c, Session.get(c), 'Session.get')
+      c.header('cache-control', 'private, no-store')
+      if (!session) return c.json({ user: null }, 200)
+      return c.json(
+        {
+          user: {
+            email: session.user.email,
+            id: session.user.id,
+            // Better Auth stores an empty name for a user who signed up without one.
+            name: session.user.name || null,
+          },
+        },
+        200,
+      )
+    },
+  )
+  .get(
+    '/v1/auth/assets',
+    OpenApi.describeRoute({
+      description:
+        "Lists the sign-in page's scripts and style sheets, which a page on Tempo ID's site prefetches before it redirects. Browsers partition their caches by site, so a page on another site gains nothing.",
+      responses: OpenApi.responses({
+        success: {
+          description: 'The assets.',
+          schema: schema.assets.response,
+        },
+      }),
+      tags: ['Authenticate'],
+    }),
+    async (c) => {
+      const assets = await Timing.measure(
+        c,
+        c.env.signInAssets(),
+        'pages.assets',
+      )
+      // A deploy changes the list, so a browser keeps it for a short time only.
+      c.header('cache-control', 'public, max-age=300')
+      return c.json({ assets }, 200)
+    },
+  )
+  .get(
+    '/v1/auth/methods',
+    OpenApi.describeRoute({
+      description:
+        'Reads the sign-in methods that the sign-in page offers, the key that `oauth_query` grants, and the page that sign-in returns to. The app of `oauth_query`, or of a pending, unbound device code in `return_to`, selects the realms. The read binds nothing, and counts against the sign-in limit of the IP address.',
+      responses: OpenApi.responses({
+        errors: [...OpenApi.validate.errors],
+        success: {
+          description: 'The sign-in methods.',
+          schema: schema.methods.response,
+        },
+      }),
+      tags: ['Authenticate'],
+    }),
+    OpenApi.validate('query', schema.methods.query),
+    async (c) => {
+      const input = c.req.valid('query')
+      // Sign-in returns only to an allowlisted path, so `return_to` never redirects to another site.
+      const returnTo = Device.returnTo(input.return_to, { origin: env.URL })
+      const query = (() => {
+        if (!input.oauth_query) return undefined
+        const query = new URLSearchParams(input.oauth_query)
+        return query.has('sig') ? query : undefined
+      })()
+
+      // The user code comes from `return_to`, but the app comes from the code's own row, so the
+      // visitor selects no app by itself.
+      const userCode = returnTo
+        ? Device.normalize(
+            new URL(returnTo, env.URL).searchParams.get('code') ?? '',
+          )
+        : undefined
+      const clientId = await (async () => {
+        if (query) return query.get('client_id') ?? undefined
+        if (!userCode) return undefined
+        // A live code's realms change the page, so each IP address's lookups count, and keep a guess
+        // of a live code out of reach (RFC 8628 §5.1). Past the limit, the page shows the `default`
+        // realm.
+        const ip = RateLimit.ip(c)
+        if (!ip) return undefined
+        const outcome = await Timing.measure(
+          c,
+          c.env.SIGN_IN_IP_LIMIT.limit({ key: `device-lookup:${ip}` }),
+          'ratelimit.limit',
+        )
+        if (!outcome.success) return undefined
+        return await Timing.measure(
+          c,
+          Device.client(db, { userCode }),
+          'Device.client',
+        )
+      })()
+      const stored = clientId
+        ? await Timing.measure(
+            c,
+            Cache.read(c, () => Realm.forApp(db, { clientId }), [
+              'realm.forApp',
+              clientId,
+            ]),
+            'Realm.forApp',
+          )
+        : [
+            await Timing.measure(
+              c,
+              Cache.read(c, () => Realm.get(db, { id: Realm.defaultId }), [
+                'realm.get',
+                Realm.defaultId,
+              ]),
+              'Realm.get',
+            ),
+          ]
+      const realms = await Timing.measure(
+        c,
+        Realm.withDefaults(c, { db, origin: env.URL, realms: stored }),
+        'Realm.withDefaults',
+      )
+      const request = query
+        ? await Timing.measure(c, granted(c, { query }), 'authenticate.granted')
+        : null
+      return c.json(
+        {
+          app: request?.app ?? null,
+          host: request?.host ?? null,
+          passkeys: Boolean(Passkey.relyingParty(realms, { origin: env.URL })),
+          // `request` keeps its `/v1` shape: it is `null` without a key that the sign-in grants.
+          request: request?.key ? { app: request.app, key: request.key } : null,
+          return_to: returnTo ?? null,
+          user_code: userCode || null,
+          verified: request?.verified ?? false,
+        },
+        200,
+      )
+    },
+  )
+
+/** Returns the client ID of the app that `oauth_query` names, or `null` without one. */
+function client(options: client.Options) {
+  if (!options.oauth_query) return null
+  return new URLSearchParams(options.oauth_query).get('client_id')
+}
+
+declare namespace client {
+  type Options = {
+    /** The sign-in page's query string, as the request sends it. */
+    oauth_query?: string | undefined
+  }
+}
+
+/**
+ * Returns the app of the signed authorization request `query`, whether it is first-party, and the
+ * key that the sign-in grants, or `null` for a forged or expired query, or an unknown app. The key is
+ * `null` for a request without one, with a `challenge`, whose key the approval page shows beside its
+ * message, or from a third-party app, whose key the approval page shows beside the host that serves
+ * its metadata document.
+ */
+async function granted(c: Context<Env>, options: granted.Options) {
+  const { query } = options
+  const context = await Timing.measure(c, c.var.auth.$context, 'auth.context')
+  const verified = await Timing.measure(
+    c,
+    verifyOAuthQueryParams(query.toString(), context.secret),
+    'auth.verifyOAuthQueryParams',
+  )
+  const clientId = query.get('client_id')
+  if (!verified || !clientId) return null
+
+  // The sign-in page shows only the app's name, so the cache holds the name alone.
+  const app = await Timing.measure(
+    c,
+    Cache.read(
+      c,
+      async () => {
+        const found = await Apps.get(db, { clientId }).catch(
+          (error: unknown) => {
+            if (error instanceof Apps.NotFoundError) return undefined
+            throw error
+          },
+        )
+        return found ? { name: found.name } : undefined
+      },
+      ['apps.name', clientId],
+      { keep: (found) => found !== undefined },
+    ),
+    'Apps.get',
+  )
+  if (!app) return null
+
+  // A third-party app names itself in its metadata document, so only the approval page grants its key.
+  const thirdParty = Apps.thirdParty(clientId)
+  // A request that a sign-in already spent grants nothing at sign-in, so only the approval page
+  // shows its key.
+  const key =
+    query.has('challenge') ||
+    thirdParty ||
+    !query.has('key_authorization') ||
+    (await Timing.measure(
+      c,
+      SignInGrant.spent(db, { query }),
+      'SignInGrant.spent',
+    ))
+      ? undefined
+      : Authorize.fromQuery(query)
+  return {
+    app: app.name ?? clientId,
+    host: thirdParty ? new URL(clientId).host : null,
+    key:
+      key && !(key instanceof ErrorResponse.ResponseError)
+        ? KeyAuthorization.describe(key)
+        : null,
+    verified: !thirdParty,
+  }
+}
+
+declare namespace granted {
+  type Options = {
+    /** The sign-in page's query. */
+    query: URLSearchParams
+  }
+}