@tempoxyz/id 0.0.0-stage → 0.0.0

package/src/api/authorize.ts

@@ -0,0 +1,1030 @@
+/**
+ * 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 { Hono } from 'hono'
+import { Base64, Bytes, Hash } from 'ox'
+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 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 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 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
+
+    export const response = Authorize.schema.response
+
+    /** Better Auth's authorization result, which names the redirect with the code. */
+    export const redirect = z.object({ url: z.string().min(1) })
+  }
+
+  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',
+          ],
+        }),
+    })
+
+    export const response = 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',
+        ],
+      }),
+    })
+
+    /** 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'],
+        }),
+    })
+
+    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({
+              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.",
+                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({
+                  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',
+                      ],
+                    }),
+                  // A key that names a foreign account returns to the app instead.
+                  refusal: KeySigner.schema.refusal
+                    .exclude(['foreign_account'])
+                    .optional()
+                    .meta({
+                      description:
+                        'Why approval cannot sign the key: the user holds no account and none can be created (`no_account`), a passkey that this page cannot use owns the account (`passkey`), or the accounts could not be read (`unavailable`). Absent when approval can sign it.',
+                      examples: ['passkey'],
+                    }),
+                })
+                .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.',
+                }),
+              session: z.string().meta({
+                description:
+                  'The ID of the signed-in session, which `POST /v1/authorize/consent` names.',
+                examples: ['8nVq3kZ0bT5wXy2mLp7sR4dA'],
+              }),
+            })
+            .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 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.',
+        }),
+    })
+  }
+}
+
+/** 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. Only a first-party app's page on the redirect URI's origin calls it. A native app authorizes through `/oauth2/authorize` instead. With `code_challenge`, the app's backend receives a code. Without one, a public app receives tokens. A key authorization is signed by the account's owner, and must fit the headless ceiling. The account becomes the app's account for its later requests.",
+      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,
+          TempoAccount.ForeignAccountError,
+        ],
+        success: {
+          description: 'The authorization.',
+          schema: schema.authorize.response,
+        },
+      }),
+      security: [{ sessionCookie: [] }],
+      tags: ['Authorization'],
+    }),
+    OpenApi.validate('json', schema.authorize.json),
+    async (c) => {
+      const request = c.req.valid('json')
+      const clientId = request.client_id
+
+      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 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())
+
+      // A backend redeems its code with the app's secret, which a page never holds.
+      if (!request.code_challenge && app!.secret)
+        return ErrorResponse.json(
+          c,
+          new Authorize.RejectedError({
+            description:
+              'Tokens refused: the app holds a client secret, so its backend redeems a code. Send `code_challenge`, then redeem the code with the secret.',
+          }),
+        )
+
+      // Counted per user once the request can authorize, so no other caller spends the user's quota.
+      const limited = await Timing.measure(
+        c,
+        RateLimit.check(c, {
+          limits: [{ binding: 'AUTHORIZE_LIMIT', key: session.user.id }],
+        }),
+        'RateLimit.check',
+      )
+      if (limited) return limited
+
+      // A headless request creates no account, so it reads the accounts the user holds. Only
+      // `POST /v1/account` and an approval on the approval page create one. A key needs the owner
+      // of its account, to sign it.
+      const key = request.key_authorization
+      const signing = key
+        ? await Timing.measure(
+            c,
+            KeySigner.resolve(c, {
+              account: key.account,
+              clientId,
+              cookie: c.req.header('cookie'),
+              sessionId: session.session.id,
+              userId: session.user.id,
+            }),
+            'KeySigner.resolve',
+          )
+        : undefined
+      if (signing instanceof ErrorResponse.ResponseError)
+        return ErrorResponse.json(c, signing)
+
+      // Without a key, the accounts only pick the selection, so a Privy outage skips it, as the
+      // account step does.
+      const account = await (async () => {
+        if (signing) return signing.account
+        const listed = await Timing.measure(
+          c,
+          AccountStep.accounts(c, { clientId, userId: session.user.id }),
+          'AccountStep.accounts',
+        ).catch((error: unknown) => {
+          Log.warn(c, {
+            error,
+            fields: { clientId },
+            message:
+              'The headless authorization skipped an account selection whose accounts failed to load.',
+          })
+          return []
+        })
+        const selected = AccountStep.selected({
+          clientId,
+          cookie: c.req.header('cookie'),
+          sessionId: session.session.id,
+        })
+        return AccountStep.find(listed, selected)?.address ?? listed[0]?.address
+      })()
+
+      // The in-process authorization reads the account, so the account step passes. Only an account
+      // that the key names becomes the app's account for later requests.
+      const selection = account
+        ? AccountStep.select({
+            account: account.toLowerCase(),
+            clientId,
+            cookie: c.req.header('cookie'),
+            sessionId: session.session.id,
+          })
+        : undefined
+      const headers = new Headers(c.req.raw.headers)
+      if (selection) headers.set('cookie', selection.header)
+      // The route read the accounts and chose one, so the account step reads them no second time.
+      c.set('accountChosen', true)
+
+      // Without the app's challenge, Tempo ID holds the verifier and redeems the code itself.
+      const verifier = request.code_challenge
+        ? undefined
+        : Base64.fromBytes(Bytes.random(32), base64url)
+      const query = {
+        client_id: clientId,
+        code_challenge:
+          request.code_challenge ??
+          Base64.fromBytes(Hash.sha256(Bytes.fromString(verifier!)), base64url),
+        code_challenge_method: 'S256',
+        redirect_uri: request.redirect_uri,
+        // In-process calls skip `withResource`, so each names the one audience that APIs verify.
+        resource: env.URL,
+        response_type: 'code',
+        scope: request.scope ?? 'openid',
+        ...(request.state ? { state: request.state } : {}),
+      }
+      const url = new URL('/oauth2/authorize', env.URL)
+      url.search = new URLSearchParams(query).toString()
+      // Better Auth returns the redirect as JSON for a request that accepts it.
+      headers.set('accept', 'application/json')
+      const authorized = await Timing.measure(
+        c,
+        c.var.auth.api.oauth2Authorize({
+          asResponse: false,
+          // A `GET` request reads `query`. The endpoint types a body for its `POST` form.
+          body: {},
+          headers,
+          query,
+          request: new Request(url, { headers }),
+        }),
+        'auth.oauth2Authorize',
+      )
+      const location = schema.authorize.redirect.safeParse(authorized)
+      const redirect = location.success
+        ? URL.parse(location.data.url, env.URL)
+        : null
+      // A request that needs the approval page, or that Better Auth refuses, returns no code. Better
+      // Auth sets its `code` in place of a registered one, and appends its `error` to the registered
+      // URI's query, which may hold its own.
+      const registered = new URL(request.redirect_uri).searchParams
+      const code = redirect?.searchParams.get('code')
+      if (
+        !redirect ||
+        !code ||
+        redirect.searchParams.getAll('error').length >
+          registered.getAll('error').length ||
+        !`${redirect.origin}${redirect.pathname}`.startsWith(
+          new URL(request.redirect_uri).origin,
+        )
+      )
+        return ErrorResponse.json(
+          c,
+          new Authorize.RejectedError({
+            description:
+              "Authorization refused: the app's request needs the user's approval, which no page shows here. Authorize through a redirect, or register the app to skip consent.",
+          }),
+        )
+
+      // The owner signs only once the authorization returns a code, so a refused request signs nothing.
+      const signed =
+        key && signing
+          ? await Timing.measure(
+              c,
+              KeySigner.sign(c, {
+                account: signing.account,
+                clientId,
+                key,
+                owner: signing.owner,
+                userId: session.user.id,
+              }),
+              'KeySigner.sign',
+            )
+          : undefined
+      if (signed instanceof ErrorResponse.ResponseError)
+        return ErrorResponse.json(c, signed)
+
+      const result = {
+        ...(account && signed ? { account, key_authorization: signed } : {}),
+        ...(request.state ? { state: request.state } : {}),
+      }
+      if (selection && key?.account)
+        c.header('set-cookie', selection.setCookie, { append: true })
+      c.header('cache-control', 'no-store')
+      if (!verifier) return c.json({ ...result, code }, 200)
+
+      const tokens = await Timing.measure(
+        c,
+        c.var.auth.api.oauth2Token({
+          body: {
+            client_id: clientId,
+            code,
+            code_verifier: verifier,
+            grant_type: 'authorization_code',
+            redirect_uri: request.redirect_uri,
+            resource: env.URL,
+          },
+          headers: new Headers({
+            'content-type': 'application/x-www-form-urlencoded',
+          }),
+        }),
+        'auth.oauth2Token',
+      )
+      return c.json(
+        { ...result, tokens: Authorize.schema.tokens.parse(tokens) },
+        200,
+      )
+    },
+  )
+  .post(
+    '/v1/authorize/account',
+    OpenApi.describeRoute({
+      description:
+        "Selects the account that the app of `oauth_query` uses, then continues its authorization, and returns the next redirect. The selection holds for the app's later authorizations in the same 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.',
+          schema: schema.account.response,
+        },
+      }),
+      security: [{ sessionCookie: [] }],
+      tags: ['Authorization'],
+    }),
+    OpenApi.validate('json', schema.account.json),
+    async (c) => {
+      const { account, oauth_query } = 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)
+
+      const accounts = await Timing.measure(
+        c,
+        AccountStep.accounts(c, { clientId, userId: session.user.id }),
+        'AccountStep.accounts',
+      )
+      if (!AccountStep.find(accounts, account))
+        return ErrorResponse.json(
+          c,
+          new TempoAccount.ForeignAccountError({ account }),
+        )
+
+      // The continued authorization checks the account step again, so it 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 redirect = await Timing.measure(
+        c,
+        SignInConsent.afterAccountStep(c, {
+          account,
+          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')
+      return c.json({ redirect }, 200)
+    },
+  )
+  .post(
+    '/v1/authorize/consent',
+    OpenApi.describeRoute({
+      description:
+        "Records the signed-in user's decision on the app's authorization request that `oauth_query` carries, and returns the app's redirect. The decision applies only while `session_id` names the signed-in session. An approval stores the consent, so the app's next request with the same scopes skips the approval page. An approval of a request with a key authorization signs the key as the account's owner, and the first redemption of the code returns it from `/oauth2/token`. For a passkey-owned account, the approval first returns the passkey step, and the repeated approval with `passkey` signs the key. A user who holds no account in the app's realms, and whose key names none, first receives a Privy-owned account, as `POST /v1/account` creates it.",
+      responses: OpenApi.responses({
+        errors: [
+          ...Authorize.checkKey.errors,
+          ...BodyLimit.errors,
+          ...Cors.ownPage.errors,
+          ...KeySigner.resolve.errors,
+          ...KeySigner.sign.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 } =
+        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,
+            headers: new Headers(c.req.raw.headers),
+            oauthQuery: oauth_query,
+            session,
+          }),
+          '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 app's authorization request that `oauth_query` carries, as the approval page shows it: the app, where the browser returns, and any key, with the account that approval signs for and why approval cannot sign it, if it cannot. A user who holds no account shows no account, and approval creates the first one. Creates no account. Returns the app's redirect with the refusal for a key that Tempo ID refuses.",
+      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) => {
+      // The read can spend the user's `ACCOUNT_LIMIT`, which a page on another site could otherwise
+      // spend 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')
+
+      // 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 { 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',
+      )
+      if (!verified) return c.json({ request: null }, 200)
+
+      const clientId = query.get('client_id')
+      const uri = query.get('redirect_uri')
+      const redirectUri = URL.parse(uri ?? '')
+      if (!clientId || !uri || !redirectUri)
+        return c.json({ request: null }, 200)
+
+      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 c.json({ request: null }, 200)
+
+      // 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 c.json({ redirect: url.href }, 200)
+      }
+
+      // 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,
+        })
+      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.
+      const destination = ['http:', 'https:'].includes(redirectUri.protocol)
+        ? redirectUri.host
+        : redirectUri.protocol.slice(0, -1)
+
+      const preview = key
+        ? await Timing.measure(
+            c,
+            KeySigner.preview(c, {
+              account: key.account,
+              clientId,
+              sessionId: session.session.id,
+              userId: session.user.id,
+            }),
+            'KeySigner.preview',
+          )
+        : undefined
+      if (preview?.foreign) return refuse(preview.foreign)
+
+      const shown = (() => {
+        if (!key || !preview) return undefined
+        const challenge = query.get('challenge')
+        return {
+          ...KeyAuthorization.describe(key),
+          ...(preview.account ? { account: preview.account } : {}),
+          ...(challenge ? { challenge } : {}),
+          ...(preview.refusal && preview.refusal !== 'foreign_account'
+            ? { refusal: preview.refusal }
+            : {}),
+        }
+      })()
+
+      return c.json(
+        {
+          request: {
+            app: app.name ?? destination,
+            destination,
+            email: session.user.email,
+            ...(shown ? { key: shown } : {}),
+            session: session.session.id,
+          },
+        },
+        200,
+      )
+    },
+  )
+  .get(
+    '/v1/authorize/accounts',
+    OpenApi.describeRoute({
+      description:
+        "Reads the account step of the app's authorization request that `oauth_query` carries: the app, and the user's accounts in its realms, oldest first, each with its balance on the chain of the request's key, or of Tempo mainnet without one. The read counts against the user's `ACCOUNT_LIMIT`, as `GET /v1/account` does.",
+      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)
+
+      const app = await Timing.measure(
+        c,
+        Apps.get(db, { clientId }).catch((error: unknown) => {
+          if (error instanceof Apps.NotFoundError) return undefined
+          throw error
+        }),
+        '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
+
+      const accounts = await Timing.measure(
+        c,
+        AccountStep.accounts(c, { clientId, userId: session.user.id }),
+        'AccountStep.accounts',
+      )
+      // A key that does not parse falls back to the default chain, and the approval page refuses it.
+      const key = Authorize.fromQuery(query)
+      const chainId =
+        key && !(key instanceof ErrorResponse.ResponseError)
+          ? Number(key.chainId)
+          : KeyAuthorization.defaultChainId
+
+      // Each Tempo Account has one owner, so the guard only narrows the read.
+      const owned = accounts.flatMap((account) => {
+        const owner = account.config.owners[0]
+        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,
+          chainId,
+          rpcUrl: env.TEMPO_RPC_URL,
+        }),
+        'Balance.list',
+      )
+      return c.json(
+        {
+          request: {
+            accounts: owned.map((account, index) => ({
+              ...account,
+              balance: balances[index] ?? null,
+            })),
+            app: app.name ?? 'The app',
+          },
+        },
+        200,
+      )
+    },
+  )
+
+/** Unpadded URL-safe Base64, as PKCE encodes verifiers and challenges. */
+const base64url = { pad: false, url: true } as const