@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/api/authorize.ts

@@ -0,0 +1,1086 @@
+/**
+ * Authorizations under `/v1/authorize`: an app's headless authorization, with the key authorization
+ * that the account's owner signs, and the requests of the pages that an app's authorization passes
+ * through, the account step's selection and the approval page's decision. Better Auth issues every
+ * code and token, in process.
+ * @module
+ */
+import { verifyOAuthQueryParams } from '@better-auth/oauth-provider'
+import { isAPIError } from 'better-auth/api'
+import type { Context } from 'hono'
+import { Hono } from 'hono'
+import { env } from 'void/env'
+import * as z from 'zod'
+import * as Apps from '../internal/Apps.js'
+import * as core_Auth from '../internal/Auth.js'
+import * as Authorize from '../internal/Authorize.js'
+import * as Balance from '../internal/Balance.js'
+import * as BodyLimit from '../internal/BodyLimit.js'
+import * as Cache from '../internal/Cache.js'
+import * as Chain from '../internal/Chain.js'
+import type { Env } from '../internal/Env.js'
+import * as ErrorResponse from '../internal/ErrorResponse.js'
+import * as KeyAuthorization from '../internal/KeyAuthorization.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 TempoAccount from '../internal/TempoAccount.js'
+import * as Timing from '../internal/Timing.js'
+import * as Validation from '../internal/Validation.js'
+import * as AccountStep from './lib/AccountStep.js'
+import * as Consent from './lib/Consent.js'
+import * as Cors from './lib/Cors.js'
+import { db } from './lib/Database.js'
+import * as Headless from './lib/Headless.js'
+import * as KeySigner from './lib/KeySigner.js'
+import * as Session from './lib/Session.js'
+import * as SignInConsent from './lib/SignInConsent.js'
+
+namespace schema {
+  export namespace authorize {
+    export const json = Authorize.schema.request.and(
+      z.object({
+        passkey: z
+          .union([
+            z.literal(true).meta({
+              description:
+                "Requests the passkey step for an account that a passkey owns, in place of `webauthn_required`. The passkey's relying party must cover the page's origin.",
+            }),
+            z.object({ assertion: Passkey.schema.assertion }).meta({
+              description:
+                "The passkey's assertion over the options of the passkey step. The repeated request signs the key with it.",
+            }),
+          ])
+          .optional()
+          .meta({
+            description:
+              "Whether the app's page signs the key with the passkey that owns the account. Absent, a passkey-owned account refuses the key with `webauthn_required`.",
+          }),
+      }),
+    )
+
+    export const step = Passkey.schema.headlessStep
+
+    export const response = z.union([Authorize.schema.response, step])
+  }
+
+  export namespace account {
+    export const json = z.object({
+      account: TempoAccount.schema.tempoAccount.shape.address.meta({
+        description:
+          "The address of the account that the user selects, one of the user's accounts in the app's realms.",
+        examples: ['0x8C3b5d0e2A4f6B1c9D7e3F5a0B2c4D6e8F1a3B5c'],
+      }),
+      oauth_query: z
+        .string()
+        .min(1)
+        .max(8192)
+        .meta({
+          description:
+            "The account step's query string, which Better Auth signs when it sends the browser there. At most 8,192 characters.",
+          examples: [
+            'client_id=Qk3vT9xZbLmN2pRw8YcHjF6sDaE4uGtK&response_type=code&exp=1760000000&sig=Gx3kB0',
+          ],
+        }),
+      passkey: z
+        .object({ assertion: Passkey.schema.assertion })
+        .optional()
+        .meta({
+          description:
+            "The passkey's assertion over the options of the passkey step, which the selection of a passkey-owned account returns. The repeated selection signs the key with it.",
+        }),
+    })
+
+    export const response = z.union([
+      z
+        .object({
+          redirect: z.string().meta({
+            description:
+              "Where the browser continues: the approval page's path on Tempo ID, or the app's `redirect_uri` with an authorization code and `state`.",
+            examples: [
+              'https://app.example.com/callback?code=Vb7mQ2xLkP9sTzR4&state=af0ifjsldkj',
+            ],
+          }),
+        })
+        .meta({ description: 'A selection that continues the authorization.' }),
+      Passkey.schema.step,
+    ])
+
+    /** Better Auth's result, which names the redirect: a path on Tempo ID, or the app's URL. */
+    export const result = z.object({ url: z.string().min(1) })
+  }
+
+  export namespace consent {
+    export const json = z.object({
+      accept: z.boolean().meta({
+        description:
+          'Whether the user approves the request. `false` denies it, and the app receives `access_denied`.',
+        examples: [true],
+      }),
+      account: TempoAccount.schema.tempoAccount.shape.address.optional().meta({
+        description:
+          "The Tempo Account that the approval page showed for the request's key authorization, one of the user's accounts in the app's realms. Ignored when the key names its account, and absent for a request without a key.",
+        examples: ['0x8C3b5d0e2A4f6B1c9D7e3F5a0B2c4D6e8F1a3B5c'],
+      }),
+      oauth_query: z
+        .string()
+        .min(1)
+        .max(8192)
+        .meta({
+          description:
+            "The approval page's query string, which Better Auth signs when it sends the browser there. At most 8,192 characters.",
+          examples: [
+            'client_id=Qk3vT9xZbLmN2pRw8YcHjF6sDaE4uGtK&response_type=code&exp=1760000000&sig=Gx3kB0',
+          ],
+        }),
+      passkey: z
+        .object({ assertion: Passkey.schema.assertion })
+        .optional()
+        .meta({
+          description:
+            "The passkey's assertion over the options of the passkey step, which a passkey-owned account's approval returns. The repeated approval signs the key with it.",
+        }),
+      session_id: z
+        .string()
+        .min(1)
+        .max(256)
+        .meta({
+          description:
+            'The ID of the session that the approval page showed. The decision applies only while that session is the signed-in one.',
+          examples: ['8nVq3kZ0bT5wXy2mLp7sR4dA'],
+        }),
+      skip_upgrade: z
+        .boolean()
+        .optional()
+        .meta({
+          description:
+            "Whether the approval skips the pending upgrade of a wallet.tempo passkey's wallet on the key's chain, `false` by default. The passkey then signs the key as its own account, and the key stops working on that chain once the wallet upgrades, unless the chain registered it first.",
+          examples: [true],
+        }),
+    })
+
+    export const step = Passkey.schema.step
+
+    export const response = z.union([
+      z
+        .object({
+          redirect: z.url().meta({
+            description:
+              "The app's `redirect_uri`, with an authorization code and `state`, or with `error=access_denied` when the user denied the request.",
+            examples: [
+              'https://app.example.com/callback?code=Vb7mQ2xLkP9sTzR4&state=af0ifjsldkj',
+            ],
+          }),
+        })
+        .meta({ description: 'A decision that returns to the app.' }),
+      step,
+    ])
+  }
+
+  export namespace request {
+    export const query = z.object({
+      oauth_query: z
+        .string()
+        .min(1)
+        .max(8192)
+        .meta({
+          description:
+            "The approval page's query string, which Better Auth signs when it sends the browser there. At most 8,192 characters.",
+          examples: [
+            'client_id=Qk3vT9xZbLmN2pRw8YcHjF6sDaE4uGtK&response_type=code&exp=1760000000&sig=Gx3kB0',
+          ],
+        }),
+    })
+
+    export const response = z.union([
+      z
+        .object({
+          redirect: z.url().meta({
+            description:
+              "The app's `redirect_uri`, with the refusal of the request's key as `error` and `error_description`, `state`, and `iss`.",
+            examples: [
+              'https://app.example.com/callback?error=invalid_request&state=af0ifjsldkj',
+            ],
+          }),
+        })
+        .meta({
+          description:
+            'A key that Tempo ID refuses, which returns the browser to the app.',
+        }),
+      z
+        .object({
+          request: z
+            .object({
+              account: z
+                .object({
+                  address: TempoAccount.schema.tempoAccount.shape.address.meta({
+                    description: 'The account address.',
+                    examples: ['0x8C3b5d0e2A4f6B1c9D7e3F5a0B2c4D6e8F1a3B5c'],
+                  }),
+                  owner:
+                    TempoAccount.schema.tempoAccount.shape.config.shape.owners.unwrap()
+                      .element.shape.type,
+                })
+                .optional()
+                .meta({
+                  description:
+                    "The Tempo Account that the approval applies to: the account that the key names, else the app's selected account, else the user's oldest. Present only when the user holds more than one account in the app's realms.",
+                }),
+              app: z.string().meta({
+                description:
+                  "The app's display name, or the host of its redirect URI without one.",
+                examples: ['Tempo Cash'],
+              }),
+              destination: z.string().meta({
+                description:
+                  "The host of the app's redirect URI, or its scheme for a native app. For a third-party app, the host that serves its metadata document.",
+                examples: ['cash.tempo.xyz'],
+              }),
+              email: z.email().meta({
+                description: "The signed-in user's email address.",
+                examples: ['ada@example.com'],
+              }),
+              key: KeyAuthorization.schema.description
+                .extend({
+                  chain: z
+                    .object({
+                      id: z
+                        .number()
+                        .int()
+                        .meta({
+                          description:
+                            'The ID of the chain that the key acts on.',
+                          examples: [42431],
+                        }),
+                      name: Chain.schema.optional().meta({
+                        description:
+                          'The name that `GET /v1/chains` lists for the chain. Absent for a chain that no name lists.',
+                        examples: ['testnet'],
+                      }),
+                    })
+                    .meta({ description: 'The chain that the key acts on.' }),
+                  challenge: z
+                    .string()
+                    .optional()
+                    .meta({
+                      description:
+                        "The message that the key's witness binds, such as a sign-in challenge from the app. Absent when the request carries none.",
+                      examples: [
+                        'Sign in to app.example.com\nNonce: 7f3a9c2e5b1d4f60',
+                      ],
+                    }),
+                  refusal: KeySigner.schema.refusal.optional(),
+                })
+                .optional()
+                .meta({
+                  description:
+                    'What the key that the request carries may do, and the account that approval signs for. Absent for a request without a key.',
+                }),
+              logo: z
+                .string()
+                .startsWith('data:image/')
+                .optional()
+                .meta({
+                  description:
+                    "The app's logo as a `data:` URL, which Tempo ID fetched from the origin of its client ID. Present only for an app with an origin client ID whose manifest or page names a logo.",
+                  examples: ['data:image/png;base64,iVBORw0KGgo='],
+                }),
+              session: z.string().meta({
+                description:
+                  'The ID of the signed-in session, which `POST /v1/authorize/consent` names.',
+                examples: ['8nVq3kZ0bT5wXy2mLp7sR4dA'],
+              }),
+              verified: z.boolean().meta({
+                description:
+                  'Whether the app is a registered app, whose name the page marks as verified. A third-party app names itself in its metadata document.',
+                examples: [true],
+              }),
+            })
+            .nullable()
+            .meta({
+              description:
+                'The request that the approval page shows, or `null` for a forged or expired query, or a request without a known app.',
+            }),
+        })
+        .meta({ description: 'The request that the approval page shows.' }),
+    ])
+  }
+
+  export namespace pageRequest {
+    export const query = request.query
+
+    export const response = request.response
+  }
+
+  export namespace accounts {
+    export const query = request.query
+
+    export const response = z.object({
+      request: z
+        .object({
+          accounts: z
+            .array(
+              z.object({
+                address: TempoAccount.schema.tempoAccount.shape.address.meta({
+                  description: 'The account address.',
+                  examples: ['0x8C3b5d0e2A4f6B1c9D7e3F5a0B2c4D6e8F1a3B5c'],
+                }),
+                balance: Balance.schema.balance.nullable().meta({
+                  description:
+                    "The account's holdings of USD tokens on the chain of the request's key, or of Tempo mainnet without one. `null` when the read fails or takes longer than 3 seconds.",
+                }),
+                owner:
+                  TempoAccount.schema.tempoAccount.shape.config.shape.owners.unwrap()
+                    .element.shape.type,
+                realm: z
+                  .string()
+                  .nullable()
+                  .meta({
+                    description:
+                      "The name of the account's realm, or `null` for the `default` realm.",
+                    examples: ['Tempo Cash'],
+                  }),
+              }),
+            )
+            .readonly()
+            .meta({
+              description:
+                "The user's accounts in the app's realms, oldest first.",
+            }),
+          app: z.string().meta({
+            description: "The app's display name.",
+            examples: ['Tempo Cash'],
+          }),
+        })
+        .nullable()
+        .meta({
+          description:
+            'The account step, or `null` for a forged or expired query, or a request without a known app.',
+        }),
+    })
+  }
+}
+
+/**
+ * Reads the authorization request that `oauthQuery` carries, as the approval page shows it: the app,
+ * where the browser returns, and any key. With `preview`, it also reads the account that the approval
+ * applies to, the account that approval signs for, and why approval cannot sign the key. That read
+ * counts against the user's `ACCOUNT_LIMIT`, as `GET /v1/account` does. Returns `request: null` for a
+ * forged or expired query or an unknown app, and the app's redirect with the refusal for a key that
+ * Tempo ID refuses.
+ */
+async function readRequest(
+  c: Context<Env>,
+  options: readRequest.Options,
+): Promise<
+  readRequest.ReturnType | ErrorResponse.Instance<typeof readRequest.errors>
+> {
+  // The preview can spend the user's `ACCOUNT_LIMIT`, which a page on another site could otherwise
+  // spend by navigating a window here. No page on another site reads the request either.
+  if (c.req.header('sec-fetch-site') === 'cross-site')
+    return new ErrorResponse.CrossSiteRequestError()
+
+  const session = await Timing.measure(c, Session.get(c), 'Session.get')
+  if (!session) return new core_Auth.SessionRequiredError()
+  c.header('cache-control', 'private, no-store')
+
+  // Better Auth reads the query that the page posts with `URLSearchParams`, so the route reads it
+  // the same way, and a malformed escape cannot show one request and approve another.
+  const query = new URLSearchParams(options.oauthQuery)
+  const context = await Timing.measure(c, c.var.auth.$context, 'auth.context')
+  const verified = await Timing.measure(
+    c,
+    verifyOAuthQueryParams(options.oauthQuery, context.secret),
+    'auth.verifyOAuthQueryParams',
+  )
+  if (!verified) return { request: null }
+
+  const clientId = query.get('client_id')
+  const uri = query.get('redirect_uri')
+  const redirectUri = URL.parse(uri ?? '')
+  if (!clientId || !uri || !redirectUri) return { request: null }
+
+  // A refused key returns the browser to the redirect URI, so the app is read with no cache.
+  const app = await Timing.measure(
+    c,
+    Apps.get(db, { clientId }).catch((error: unknown) => {
+      if (error instanceof Apps.NotFoundError) return undefined
+      throw error
+    }),
+    'Apps.get',
+  )
+  // Better Auth redirects only to a registered URI, compared as a string.
+  if (!app || !app.redirectUris.includes(uri)) return { request: null }
+
+  // A refused key returns to the app with the refusal (RFC 6749 §4.1.2.1), as `/oauth2/authorize`
+  // returns one before sign-in, since a refusal page would leave the app without a callback. Each
+  // parameter follows the registered URI's own, as Better Auth appends its refusals.
+  const refuse = (error: ErrorResponse.ResponseError) => {
+    const url = new URL(uri)
+    url.searchParams.append('error', error.response.error)
+    url.searchParams.append(
+      'error_description',
+      error.response.error_description,
+    )
+    const state = query.get('state')
+    if (state) url.searchParams.append('state', state)
+    url.searchParams.append('iss', env.URL)
+    return { redirect: url.href }
+  }
+
+  // The page shows the key that approval signs, so the route refuses one that approval would
+  // refuse.
+  const key = Authorize.fromQuery(query)
+  if (key instanceof ErrorResponse.ResponseError) return refuse(key)
+  const refused =
+    key &&
+    Authorize.checkKey({
+      app,
+      clientId,
+      codeChallenge: query.get('code_challenge'),
+      key,
+      query,
+    })
+  if (refused) return refuse(refused)
+
+  // A custom scheme can carry an authority, as in `com.example.app://oauth/callback`, but the
+  // browser returns to whichever native app claims the scheme, so only a web URI names its host.
+  // A third-party app names its own name, so the page names the host that serves its metadata
+  // document, which every one of its redirect URIs shares.
+  const destination = (() => {
+    if (Apps.thirdParty(clientId)) return new URL(clientId).host
+    if (['http:', 'https:'].includes(redirectUri.protocol))
+      return redirectUri.host
+    return redirectUri.protocol.slice(0, -1)
+  })()
+
+  // A request without a key reads the accounts too, since the app uses the selected one. Without
+  // `preview`, the read shows no account.
+  const preview = options.preview
+    ? await Timing.measure(
+        c,
+        KeySigner.preview(c, {
+          account: key?.account,
+          chainId: key?.chainId,
+          clientId,
+          email: session.user.email,
+          sessionId: session.session.id,
+          userId: session.user.id,
+        }),
+        'KeySigner.preview',
+      )
+    : undefined
+
+  // A user with several accounts sees the one that the approval applies to. A foreign account is
+  // not in the list, so the page shows no account for it.
+  const account = (() => {
+    if (!preview || preview.accounts.length < 2) return undefined
+    const found = AccountStep.find(preview.accounts, preview.account)
+    const owner = found ? TempoAccount.signer(found) : undefined
+    if (!found || !owner) return undefined
+    return { address: found.address, owner: owner.type }
+  })()
+
+  // A foreign account holds the approval like any other refusal, and never returns to the app
+  // before the user decides, so the app cannot test which accounts the user holds.
+  const shown = (() => {
+    if (!key) return undefined
+    const challenge = query.get('challenge')
+    const chainId = Number(key.chainId)
+    const name = Chain.name({ chainId, rpcUrls: env.RPC_URLS })
+    return {
+      ...KeyAuthorization.describe(key),
+      ...(preview?.account ? { account: preview.account } : {}),
+      chain: { id: chainId, ...(name ? { name } : {}) },
+      ...(challenge ? { challenge } : {}),
+      ...(preview?.refusal ? { refusal: preview.refusal } : {}),
+    }
+  })()
+
+  return {
+    request: {
+      ...(account ? { account } : {}),
+      app: app.name ?? destination,
+      destination,
+      email: session.user.email,
+      ...(shown ? { key: shown } : {}),
+      ...(app.logo ? { logo: app.logo } : {}),
+      session: session.session.id,
+      verified: !Apps.thirdParty(clientId),
+    },
+  }
+}
+
+namespace readRequest {
+  export type Options = {
+    /** The approval page's query string, which Better Auth signed. */
+    oauthQuery: string
+    /** Whether the read holds the account that approval signs for, and why it cannot sign the key. */
+    preview: boolean
+  }
+
+  export type ReturnType = z.output<typeof schema.request.response>
+
+  /** The refusals `readRequest` returns. Its return type admits no other. */
+  export const errors = [
+    core_Auth.SessionRequiredError,
+    ErrorResponse.CrossSiteRequestError,
+  ] as const
+}
+
+/** The authorization routes. */
+export const authorize = new Hono<Env>()
+  .post(
+    '/v1/authorize',
+    OpenApi.describeRoute({
+      description:
+        "Authorizes the app for the signed-in user without a redirect, from a first-party app's page on the redirect URI's origin. It returns a code with `code_challenge`, or tokens to a public app without one, and signs any key within the headless ceiling. With `passkey: true`, a passkey-owned account returns the passkey step, and the repeated request with `passkey: { assertion }` and the step's `expiry` signs the key.",
+      responses: OpenApi.responses({
+        errors: [
+          ...Authorize.check.errors,
+          ...AccountStep.held.errors,
+          ...BodyLimit.errors,
+          ...OpenApi.validate.errors,
+          ...RateLimit.check.errors,
+          core_Auth.SessionRequiredError,
+          ErrorResponse.CrossSiteRequestError,
+          KeyAuthorization.WebAuthnRequiredError,
+          Passkey.WebAuthnRejectedError,
+          TempoAccount.ForeignAccountError,
+        ],
+        success: {
+          description: 'The authorization, or the passkey step.',
+          schema: schema.authorize.response,
+        },
+      }),
+      security: [{ sessionCookie: [] }],
+      tags: ['Authorization'],
+    }),
+    OpenApi.validate('json', schema.authorize.json),
+    async (c) => {
+      const { passkey, ...request } = c.req.valid('json')
+      const clientId = request.client_id
+
+      // A write from a first-party app's page reuses the app that `Cors.firstParty` read.
+      const app = await Timing.measure(
+        c,
+        Headless.app(c, { clientId }),
+        'Headless.app',
+      )
+      const refused = Authorize.check(request, {
+        app,
+        origin: c.req.header('origin'),
+      })
+      if (refused) return ErrorResponse.json(c, refused)
+
+      // Without a session the app shows its sign-in.
+      const session = await Timing.measure(c, Session.get(c), 'Session.get')
+      if (!session)
+        return ErrorResponse.json(c, new core_Auth.SessionRequiredError())
+
+      const authorized = await Timing.measure(
+        c,
+        Headless.authorize(c, {
+          // A user who holds no account receives a first one, as `POST /v1/account` creates it, so
+          // the app's page sends one request after any sign-in.
+          create: true,
+          headers: new Headers(c.req.raw.headers),
+          passkey: passkey === true ? {} : passkey,
+          request,
+          secret: Boolean(app!.secret),
+          session,
+        }),
+        'Headless.authorize',
+      )
+      if (authorized instanceof Response) return authorized
+      if (authorized instanceof ErrorResponse.ResponseError)
+        return ErrorResponse.json(c, authorized)
+      // A passkey signs only in the browser, so the page signs the digest and repeats the request.
+      if ('options' in authorized) {
+        c.header('cache-control', 'no-store')
+        return c.json(
+          schema.authorize.step.parse({
+            expiry: authorized.expiry,
+            step: { options: authorized.options, type: 'passkey' },
+          }),
+          200,
+        )
+      }
+      return c.json(authorized, 200)
+    },
+  )
+  .post(
+    '/v1/authorize/account',
+    OpenApi.describeRoute({
+      description:
+        "Selects the account that the app of `oauth_query` uses, and returns the next redirect of the authorization. The selection holds for the app's later authorizations in the session, and `GET /v1/account` lists it first.",
+      responses: OpenApi.responses({
+        errors: [
+          ...BodyLimit.errors,
+          ...Cors.ownPage.errors,
+          ...OpenApi.validate.errors,
+          ...AccountStep.accounts.errors,
+          ...RateLimit.check.errors,
+          core_Auth.AuthorizationExpiredError,
+          core_Auth.SessionRequiredError,
+          TempoAccount.ForeignAccountError,
+        ],
+        success: {
+          description: 'The next redirect, or the passkey step.',
+          schema: schema.account.response,
+        },
+      }),
+      security: [{ sessionCookie: [] }],
+      tags: ['Authorization'],
+    }),
+    OpenApi.validate('json', schema.account.json),
+    async (c) => {
+      const { account, oauth_query, passkey } = c.req.valid('json')
+      const crossSite = Cors.ownPage(c, { oauth_query })
+      if (crossSite) return ErrorResponse.json(c, crossSite)
+
+      const session = await Timing.measure(c, Session.get(c), 'Session.get')
+      if (!session)
+        return ErrorResponse.json(c, new core_Auth.SessionRequiredError())
+
+      // The account lookup can call every realm's Privy app, so it counts against the user's
+      // account reads, as `GET /v1/account` does.
+      const refused = await Timing.measure(
+        c,
+        RateLimit.check(c, {
+          limits: [{ binding: 'ACCOUNT_LIMIT', key: session.user.id }],
+        }),
+        'RateLimit.check',
+      )
+      if (refused) return refused
+
+      // The account lookup reads only a signed query, so a forged one learns nothing about the user.
+      const context = await Timing.measure(
+        c,
+        c.var.auth.$context,
+        'auth.context',
+      )
+      const verified = await Timing.measure(
+        c,
+        verifyOAuthQueryParams(oauth_query, context.secret),
+        'auth.verifyOAuthQueryParams',
+      )
+      const query = new URLSearchParams(oauth_query)
+      const clientId = query.get('client_id')
+      if (!verified || !clientId)
+        return ErrorResponse.json(c, new core_Auth.AuthorizationExpiredError())
+      // The continued authorization can store a code for the redirect URI, so it is checked first.
+      Consent.checkRedirect(query)
+
+      // The selection names the account at its address on the key's chain, as the step lists it.
+      const key = Authorize.fromQuery(query)
+      const accounts = await Timing.measure(
+        c,
+        AccountStep.accounts(c, {
+          chainId:
+            key && !(key instanceof ErrorResponse.ResponseError) && key.chainId
+              ? Number(key.chainId)
+              : KeyAuthorization.defaultChainId,
+          clientId,
+          userId: session.user.id,
+        }),
+        'AccountStep.accounts',
+      )
+      if (!AccountStep.find(accounts, account))
+        return ErrorResponse.json(
+          c,
+          new TempoAccount.ForeignAccountError({ account }),
+        )
+      // The route read the accounts and found the selection among them, so the continued
+      // authorization reads them no second time.
+      c.set('accountChosen', true)
+
+      // The approval that a sign-in with the request's key continues reads the new selection.
+      const selection = AccountStep.select({
+        account: account.toLowerCase(),
+        clientId,
+        cookie: c.req.header('cookie'),
+        sessionId: session.session.id,
+      })
+      const headers = new Headers(c.req.raw.headers)
+      headers.set('cookie', selection.header)
+      const result = await Timing.measure(
+        c,
+        c.var.auth.api.oauth2Continue({
+          // A call with a request returns a `Response` unless `asResponse` is false.
+          asResponse: false,
+          body: { oauth_query, postLogin: true },
+          headers,
+          request: new Request(c.req.url, { headers, method: 'POST' }),
+        }),
+        'auth.oauth2Continue',
+      ).catch((error: unknown) => {
+        // Better Auth refuses a forged or expired request before it continues the authorization.
+        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)
+
+      // A sign-in that showed the request's key held its grant for this step, which takes it.
+      const next = await Timing.measure(
+        c,
+        SignInConsent.afterAccountStep(c, {
+          account,
+          assertion: passkey?.assertion,
+          headers,
+          redirect: schema.account.result.parse(result).url,
+          session,
+        }),
+        'SignInConsent.afterAccountStep',
+      )
+
+      c.header('set-cookie', selection.setCookie, { append: true })
+      c.header('cache-control', 'private, no-store')
+      // A passkey signs only in this browser, so the page signs the digest and repeats the selection.
+      if ('options' in next)
+        return c.json(
+          Passkey.schema.step.parse({
+            step: { options: next.options, type: 'passkey' },
+          }),
+          200,
+        )
+      return c.json({ redirect: next.redirect }, 200)
+    },
+  )
+  .post(
+    '/v1/authorize/consent',
+    OpenApi.describeRoute({
+      description:
+        "Records the signed-in user's decision on the request in `oauth_query`, stores an approval's consent, and returns the app's redirect. An approval of a key authorization signs the key. If the key names no account and the user holds none, the approval first creates an account.",
+      responses: OpenApi.responses({
+        errors: [
+          ...Authorize.checkKey.errors,
+          ...BodyLimit.errors,
+          ...Cors.ownPage.errors,
+          ...KeySigner.resolve.errors,
+          ...KeySigner.sign.errors,
+          ...KeySigner.unlinked.errors,
+          ...OpenApi.validate.errors,
+          ...RateLimit.check.errors,
+          Authorize.RejectedError,
+          core_Auth.AuthorizationExpiredError,
+          core_Auth.SessionChangedError,
+          core_Auth.SessionRequiredError,
+          Validation.InvalidFieldError,
+        ],
+        success: {
+          description: "The app's redirect, or the passkey step.",
+          schema: schema.consent.response,
+        },
+      }),
+      security: [{ sessionCookie: [] }],
+      tags: ['Authorization'],
+    }),
+    OpenApi.validate('json', schema.consent.json),
+    async (c) => {
+      const {
+        accept,
+        account,
+        oauth_query,
+        passkey,
+        session_id,
+        skip_upgrade,
+      } = c.req.valid('json')
+      const crossSite = Cors.ownPage(c, { oauth_query })
+      if (crossSite) return ErrorResponse.json(c, crossSite)
+
+      const session = await Timing.measure(c, Session.get(c), 'Session.get')
+      if (!session)
+        return ErrorResponse.json(c, new core_Auth.SessionRequiredError())
+      // A sign-in in another tab replaces the session, and the page still names the earlier account.
+      if (session.session.id !== session_id)
+        return ErrorResponse.json(c, new core_Auth.SessionChangedError())
+
+      // Better Auth stores the consent before it returns the redirect, so the signed redirect URI is
+      // checked first, or an approval would let the app's next request reach it without this page.
+      const context = await Timing.measure(
+        c,
+        c.var.auth.$context,
+        'auth.context',
+      )
+      const verified = await Timing.measure(
+        c,
+        verifyOAuthQueryParams(oauth_query, context.secret),
+        'auth.verifyOAuthQueryParams',
+      )
+      if (!verified)
+        return ErrorResponse.json(c, new core_Auth.AuthorizationExpiredError())
+      const query = new URLSearchParams(oauth_query)
+      Consent.checkRedirect(query)
+
+      // Each approval of a key reads the user's accounts and calls Privy, as a headless
+      // authorization does. The repeated approval of the passkey step counts too, since it reads
+      // the same owners before its assertion is checked.
+      const keyed =
+        accept && (query.has('key_authorization') || query.has('challenge'))
+      const limited = keyed
+        ? await Timing.measure(
+            c,
+            RateLimit.check(c, {
+              limits: [{ binding: 'AUTHORIZE_LIMIT', key: session.user.id }],
+            }),
+            'RateLimit.check',
+          )
+        : undefined
+      if (limited) return limited
+
+      // An approval signs the key before Better Auth issues the code, so a refused key issues none.
+      if (accept) {
+        const approved = await Timing.measure(
+          c,
+          Consent.approve(c, {
+            account,
+            assertion: passkey?.assertion,
+            email: session.user.email,
+            headers: new Headers(c.req.raw.headers),
+            oauthQuery: oauth_query,
+            session,
+            skipUpgrade: skip_upgrade,
+          }),
+          'Consent.approve',
+        )
+        if (approved instanceof ErrorResponse.ResponseError)
+          return ErrorResponse.json(c, approved)
+        c.header('cache-control', 'private, no-store')
+        // A passkey signs only in this browser, so the page signs the digest and repeats the approval.
+        if ('options' in approved)
+          return c.json(
+            schema.consent.step.parse({
+              step: { options: approved.options, type: 'passkey' },
+            }),
+            200,
+          )
+        return c.json({ redirect: approved.redirect }, 200)
+      }
+
+      const result = await Timing.measure(
+        c,
+        c.var.auth.api.oauth2Consent({
+          // A call with a request returns a `Response` unless `asResponse` is false.
+          asResponse: false,
+          body: { accept, 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),
+          // An authorization that asks to sign in again continues through the request.
+          request: c.req.raw,
+        }),
+        'auth.oauth2Consent',
+      ).catch((error: unknown) => {
+        // Better Auth refuses a forged or expired request before it stores anything.
+        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)
+
+      c.header('cache-control', 'private, no-store')
+      return c.json({ redirect: schema.account.result.parse(result).url }, 200)
+    },
+  )
+  .get(
+    '/v1/authorize/request',
+    OpenApi.describeRoute({
+      description:
+        "Reads the authorization request in `oauth_query` as the approval page shows it: the app, the destination, the account, and any key. For a key that Tempo ID refuses, it returns the app's redirect with the refusal.",
+      responses: OpenApi.responses({
+        errors: [
+          ...OpenApi.validate.errors,
+          core_Auth.SessionRequiredError,
+          ErrorResponse.CrossSiteRequestError,
+        ],
+        success: {
+          description: "The request, or the app's redirect with a refusal.",
+          schema: schema.request.response,
+        },
+      }),
+      security: [{ sessionCookie: [] }],
+      tags: ['Authorization'],
+    }),
+    OpenApi.validate('query', schema.request.query),
+    async (c) => {
+      const result = await Timing.measure(
+        c,
+        readRequest(c, {
+          oauthQuery: c.req.valid('query').oauth_query,
+          preview: true,
+        }),
+        'authorize.readRequest',
+      )
+      if (result instanceof ErrorResponse.ResponseError)
+        return ErrorResponse.json(c, result)
+      return c.json(result, 200)
+    },
+  )
+  // The approval page renders from this read, and streams in the account from
+  // `GET /v1/authorize/request`, whose owners' lookup can call every realm's Privy app.
+  .get(
+    '/i/authorize/request',
+    OpenApi.describeRoute({
+      description:
+        "Reads the app's authorization request that `oauth_query` carries, as `GET /v1/authorize/request` does, without the account that the approval applies to, the account that approval signs for, or why approval cannot sign the key. The read holds no account, so it does not count against the user's `ACCOUNT_LIMIT`. Internal: only Tempo ID's approval page sends the request, so the public document leaves it out.",
+      // Internal routes stay out of `/openapi.json` and `/docs`.
+      hide: true,
+      responses: OpenApi.responses({
+        errors: [...OpenApi.validate.errors, ...readRequest.errors],
+        success: {
+          description: "The request, or the app's redirect with a refusal.",
+          schema: schema.pageRequest.response,
+        },
+      }),
+      security: [{ sessionCookie: [] }],
+      tags: ['Authorization'],
+    }),
+    OpenApi.validate('query', schema.pageRequest.query),
+    async (c) => {
+      const result = await Timing.measure(
+        c,
+        readRequest(c, {
+          oauthQuery: c.req.valid('query').oauth_query,
+          preview: false,
+        }),
+        'authorize.readRequest',
+      )
+      if (result instanceof ErrorResponse.ResponseError)
+        return ErrorResponse.json(c, result)
+      return c.json(result, 200)
+    },
+  )
+  .get(
+    '/v1/authorize/accounts',
+    OpenApi.describeRoute({
+      description:
+        "Reads the account step of the authorization request in `oauth_query`: the app, and the user's accounts in its realms, oldest first. Each account carries its balance on the chain of the request's key, or of Tempo mainnet without a key.",
+      responses: OpenApi.responses({
+        errors: [
+          ...AccountStep.accounts.errors,
+          ...OpenApi.validate.errors,
+          ...RateLimit.check.errors,
+          core_Auth.SessionRequiredError,
+          ErrorResponse.CrossSiteRequestError,
+        ],
+        success: {
+          description: 'The account step.',
+          schema: schema.accounts.response,
+        },
+      }),
+      security: [{ sessionCookie: [] }],
+      tags: ['Authorization'],
+    }),
+    OpenApi.validate('query', schema.accounts.query),
+    async (c) => {
+      // A page on another site could otherwise spend the user's `ACCOUNT_LIMIT` by navigating a
+      // window here.
+      if (c.req.header('sec-fetch-site') === 'cross-site')
+        return ErrorResponse.json(c, new ErrorResponse.CrossSiteRequestError())
+
+      const session = await Timing.measure(c, Session.get(c), 'Session.get')
+      if (!session)
+        return ErrorResponse.json(c, new core_Auth.SessionRequiredError())
+      c.header('cache-control', 'private, no-store')
+
+      const { oauth_query } = c.req.valid('query')
+      const query = new URLSearchParams(oauth_query)
+      const context = await Timing.measure(
+        c,
+        c.var.auth.$context,
+        'auth.context',
+      )
+      const verified = await Timing.measure(
+        c,
+        verifyOAuthQueryParams(oauth_query, context.secret),
+        'auth.verifyOAuthQueryParams',
+      )
+      const clientId = query.get('client_id')
+      if (!verified || !clientId) return c.json({ request: null }, 200)
+
+      // The selection continues through Better Auth, which reads the app again.
+      const app = await Timing.measure(
+        c,
+        Cache.read(
+          c,
+          () =>
+            Apps.get(db, { clientId }).catch((error: unknown) => {
+              if (error instanceof Apps.NotFoundError) return undefined
+              throw error
+            }),
+          ['apps.get', clientId],
+        ),
+        'Apps.get',
+      )
+      if (!app) return c.json({ request: null }, 200)
+
+      // The account lookup can call every realm's Privy app, so it counts against the user's account
+      // reads, as `GET /v1/account` does.
+      const refused = await Timing.measure(
+        c,
+        RateLimit.check(c, {
+          limits: [{ binding: 'ACCOUNT_LIMIT', key: session.user.id }],
+        }),
+        'RateLimit.check',
+      )
+      if (refused) return refused
+
+      // A key that names no chain acts on the default chain. A key that does not parse falls back to
+      // it too, and the approval page refuses it. The accounts are listed at their addresses there.
+      const key = Authorize.fromQuery(query)
+      const chainId =
+        key && !(key instanceof ErrorResponse.ResponseError) && key.chainId
+          ? Number(key.chainId)
+          : KeyAuthorization.defaultChainId
+      const accounts = await Timing.measure(
+        c,
+        AccountStep.accounts(c, {
+          chainId,
+          clientId,
+          userId: session.user.id,
+        }),
+        'AccountStep.accounts',
+      )
+
+      // Each Tempo Account has an owner, so the guard only narrows the read.
+      const owned = accounts.flatMap((account) => {
+        const owner = TempoAccount.signer(account)
+        if (!owner) return []
+        return [
+          {
+            address: account.address,
+            owner: owner.type,
+            // The `default` realm goes unnamed, so a row names only a realm such as Tempo Cash.
+            realm:
+              account.realm.id === Realm.defaultId ? null : account.realm.name,
+          },
+        ]
+      })
+      const balances = await Timing.measure(
+        c,
+        Balance.list(c, {
+          accounts: owned,
+          apiUrl: Chain.apiUrl({ apiUrls: env.TEMPO_API_URLS, chainId }),
+          chainId,
+        }),
+        'Balance.list',
+      )
+      return c.json(
+        {
+          request: {
+            accounts: owned.map((account, index) => ({
+              ...account,
+              balance: balances[index] ?? null,
+            })),
+            app: app.name ?? 'The app',
+          },
+        },
+        200,
+      )
+    },
+  )