@tempoxyz/id 0.0.0-pr-187.sha-eed04d3

package/src/api/authenticate.ts

@@ -0,0 +1,1290 @@
+/** 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 { and, eq, isNull } from 'drizzle-orm'
+import type { Context } from 'hono'
+import { Hono } from 'hono'
+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 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 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 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 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.",
+        }),
+        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'],
+          }),
+        // 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 when an app's authorization request sent the browser there, which the sign-in continues. Better Auth signs it. 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'],
+      })
+
+    /** 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({
+      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({
+      client_id: z
+        .string()
+        .min(1)
+        .max(64)
+        .optional()
+        .meta({
+          description:
+            "The client ID of the first-party app whose page runs the ceremony. It selects the app's realms, and the request's `Origin` must be the origin of one of the app's redirect URIs. Required from an app's page.",
+          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`. The options then name only that step's passkey, at its relying party, in place of `credentialId`. The emailed-code sign-in 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. While the code is pending and bound to no user, it selects the realms of the app that requested it. Any other code selects the `default` realm. Ignored with `oauth_query` or `client_id`.',
+          examples: ['WDJB-MJHT'],
+        }),
+    })
+
+    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 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({
+      google: z.boolean().meta({
+        description:
+          'Whether Tempo ID offers Google sign-in, which the deployment configures.',
+        examples: [true],
+      }),
+      passkeys: z.boolean().meta({
+        description:
+          "Whether Tempo ID offers passkey sign-in: one of the realms of the app that `oauth_query` or the device code of `return_to` names, or the `default` realm without one, holds passkeys that sign in at Tempo ID's origin.",
+        examples: [true],
+      }),
+      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, or `null` for a forged or expired query, an unknown app, a request without a key, or a key with a `challenge`, which the approval page shows instead.',
+        }),
+      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'],
+        }),
+    })
+  }
+}
+
+/** 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
+
+      // 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 realm of the sign-in, the first realm of the app that `oauth_query` names or the `default` realm, it creates one when the realm creates accounts. A failed creation leaves the sign-in 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,
+          ...RateLimit.check.errors,
+          core_Auth.AuthorizationExpiredError,
+          core_Auth.InvalidCodeError,
+          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, code, email, link, oauth_query } = 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 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.
+      if (deferred) {
+        const challenge = assertion
+          ? await Timing.measure(
+              c,
+              Passkey.take(db, {
+                clientDataJSON: assertion.metadata.clientDataJSON,
+              }),
+              'Passkey.take',
+            )
+          : undefined
+        // 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,
+          })
+        )
+          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()
+        // 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 = await (async () => {
+        if ('user' in signedIn)
+          return { email: signedIn.user.email, id: signedIn.user.id }
+        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) throw new Error('The signed-in user is missing.')
+        return { email: found.user.email, id: found.user.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',
+        )
+        // 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 }),
+          userId: user.id,
+        }),
+        'FirstAccount.create',
+      )
+
+      // 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 relying party that the sign-in reaches. Without `oauth_query` or `client_id`, that is the relying party of the `default` realm. With either, it is the first of the app's realms that holds passkeys. From a first-party app's page, with `client_id`, the relying party must cover the page's origin and Tempo ID's, and only that page's assertion spends the challenge. With `link`, the options name only the email step's passkey.",
+      responses: OpenApi.responses({
+        errors: [
+          ...BodyLimit.errors,
+          ...Cors.ownPage.errors,
+          ...OpenApi.validate.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 {
+        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)
+      if (page || client_id) {
+        const app = client_id
+          ? await Timing.measure(
+              c,
+              // A disabled app can share its origin with an enabled one, which CORS admits.
+              Apps.get(db, { clientId: client_id, enabled: true }).catch(
+                (error: unknown) => {
+                  if (error instanceof Apps.NotFoundError) return undefined
+                  throw error
+                },
+              ),
+              'Apps.get',
+            )
+          : undefined
+        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,
+            Realm.forApp(db, { clientId: appId }),
+            'Realm.forApp',
+          )
+        : [
+            await Timing.measure(
+              c,
+              Realm.get(db, { id: Realm.defaultId }),
+              'Realm.get',
+            ),
+          ]
+      const realms = await Timing.measure(
+        c,
+        Realm.withDefaults(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 the sign-in page, the challenge of a request with a key is the key's digest, so one
+      // passkey assertion signs in and signs the key. A link's step and an app's page sign in only.
+      const oneTap =
+        oauth_query && !link && !page
+          ? await Timing.measure(
+              c,
+              SignInConsent.oneTap(c, { oauthQuery: oauth_query }),
+              'SignInConsent.oneTap',
+            )
+          : undefined
+      const challenge = await Timing.measure(
+        c,
+        Passkey.challenge(db, {
+          clientId,
+          link: linked,
+          oneTap,
+          origin: page,
+          ...relyingParty,
+        }),
+        'Passkey.challenge',
+      )
+      // 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 the options, sent from the page that requested them, and sets the session cookie. For a user with no Tempo Account in the realm of the sign-in, the first realm of the app that `oauth_query` names or the `default` realm, it creates one when the realm creates accounts. A failed creation leaves the sign-in 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,
+          ...RateLimit.check.errors,
+          core_Auth.AuthorizationExpiredError,
+          Passkey.WebAuthnRejectedError,
+        ],
+        success: {
+          description:
+            'The signed-in user, 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.
+      const challenge = await Timing.measure(
+        c,
+        Passkey.take(db, {
+          clientDataJSON: assertion.metadata.clientDataJSON,
+        }),
+        'Passkey.take',
+      )
+      // 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 { id } = assertion
+      const key = await Timing.measure(
+        c,
+        Passkey.get(db, { id, rpId: challenge.rpId }),
+        'Passkey.get',
+      )
+      // 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())
+
+      // 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,
+        )
+      }
+
+      const userId = await (async () => {
+        if (key) return 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',
+        )
+        return Timing.measure(
+          c,
+          Passkey.link(db, {
+            credential: credential!,
+            id,
+            rpId: challenge.rpId,
+            userId: user,
+          }),
+          'Passkey.link',
+        )
+      })()
+      // Another passkey holds the address that wallet.tempo returned.
+      if (!userId)
+        return ErrorResponse.json(c, new Passkey.WebAuthnRejectedError())
+
+      const result = await Timing.measure(
+        c,
+        c.var.auth.api.signInPasskey({
+          asResponse: false,
+          body: {
+            userId,
+            ...(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
+      })
+      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)
+      // A wallet.tempo passkey owns its account, so only a Tempo ID passkey's user can receive one.
+      await Timing.measure(
+        c,
+        FirstAccount.create(c, { clientId: client({ oauth_query }), userId }),
+        'FirstAccount.create',
+      )
+      if ('user' in signedIn) {
+        const { user } = signedIn
+        return c.json(
+          { redirect: null, user: { email: user.email, id: user.id } },
+          200,
+        )
+      }
+      const [user] = 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',
+      )
+      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 one-tap 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, {
+          oneTap: 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 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) => {
+      const headers = c.req.raw.headers
+      const session = await Timing.measure(
+        c,
+        c.var.auth.api.getSession({ headers }),
+        'auth.getSession',
+      )
+      // Better Auth revokes a session's tokens when it deletes the session, except `offline_access`
+      // refresh tokens, which every app requests. Sign-out ends the apps' access too.
+      if (session)
+        await Timing.measure(
+          c,
+          db
+            .update(Schema.oauthRefreshToken)
+            .set({ revoked: new Date() })
+            .where(
+              and(
+                eq(Schema.oauthRefreshToken.sessionId, session.session.id),
+                isNull(Schema.oauthRefreshToken.revoked),
+              ),
+            ),
+          'db.oauthRefreshToken.revoke',
+        )
+
+      const result = await Timing.measure(
+        c,
+        c.var.auth.api.signOut({ headers, returnHeaders: true }),
+        'auth.signOut',
+      )
+      for (const cookie of result.headers.getSetCookie())
+        c.header('set-cookie', cookie, { append: true })
+      // 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/methods',
+    OpenApi.describeRoute({
+      description:
+        "Reads the sign-in methods that the sign-in page offers, the key that a signed authorization request in `oauth_query` grants, and the page that sign-in returns to. A device code in `return_to` names the app that requested it, while the code is pending and bound to no user. The read binds nothing, and counts against the IP address's sign-in limit. Without `oauth_query`, a client ID reads the `default` realm, as the other sign-in routes do.",
+      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 })
+      // A failed Google sign-in's `error` is not part of the signed request, so the route drops it.
+      const query = (() => {
+        if (!input.oauth_query) return undefined
+        const query = new URLSearchParams(input.oauth_query)
+        query.delete('error')
+        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,
+            Realm.forApp(db, { clientId }),
+            'Realm.forApp',
+          )
+        : [
+            await Timing.measure(
+              c,
+              Realm.get(db, { id: Realm.defaultId }),
+              'Realm.get',
+            ),
+          ]
+      const realms = await Timing.measure(
+        c,
+        Realm.withDefaults(db, { origin: env.URL, realms: stored }),
+        'Realm.withDefaults',
+      )
+      const request = query
+        ? await Timing.measure(c, granted(c, { query }), 'authenticate.granted')
+        : null
+      return c.json(
+        {
+          google: Boolean(Auth.google()),
+          passkeys: Boolean(Passkey.relyingParty(realms, { origin: env.URL })),
+          request,
+          return_to: returnTo ?? null,
+          user_code: userCode || null,
+        },
+        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 ID 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 found.user.id
+
+  try {
+    const created = await Timing.measure(
+      c,
+      context.internalAdapter.createUser(
+        { email, emailVerified: true, name: '' },
+        { method: 'passkey' },
+      ),
+      'db.user.create',
+    )
+    return created.id
+  } catch (error) {
+    const again = await Timing.measure(
+      c,
+      context.internalAdapter.findUserByEmail(email),
+      'db.user.findByEmail',
+    )
+    if (again) return again.user.id
+    throw error
+  }
+}
+
+declare namespace emailUser {
+  type Options = {
+    /** The email address that wallet.tempo verified. */
+    email: string
+  }
+}
+
+/**
+ * Returns the app and the key of the signed authorization request `query`, which the sign-in grants,
+ * or `null` for a forged or expired query, an unknown app, or a request without a key. A request
+ * with a `challenge` shows its key on the approval page instead, beside its message.
+ */
+async function granted(c: Context<Env>, options: granted.Options) {
+  const { query } = options
+  if (!query.has('key_authorization') || query.has('challenge')) return null
+
+  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
+
+  const app = await Timing.measure(
+    c,
+    Apps.get(db, { clientId }).catch((error: unknown) => {
+      if (error instanceof Apps.NotFoundError) return undefined
+      throw error
+    }),
+    'Apps.get',
+  )
+  const key = Authorize.fromQuery(query)
+  if (!app || !key || key instanceof ErrorResponse.ResponseError) return null
+  return { app: app.name ?? clientId, key: KeyAuthorization.describe(key) }
+}
+
+declare namespace granted {
+  type Options = {
+    /** The sign-in page's query, without a failed Google sign-in's `error`. */
+    query: URLSearchParams
+  }
+}