@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/api/oauth.ts

@@ -0,0 +1,1796 @@
+/**
+ * The OAuth and OpenID protocol paths under `/oauth2` and `/.well-known`, and the device grant's
+ * `/device/code`, which discovery advertises. Only the listed paths reach
+ * Better Auth, since its handler also serves client and consent management that Tempo ID calls only in
+ * process. Bodies and responses pass through, except that an error response gains `request_id`.
+ * A browser's authorization receives Tempo ID's page of its next step in place of a redirect to it.
+ * The device grant carries Tempo ID's key authorization through `/device/code` and `/oauth2/token`.
+ * Tempo ID serves `/oauth2/end-session` itself, since Better Auth's logout fetches the signing keys
+ * over HTTP and renders its own page.
+ * @module
+ */
+import { decodeBasicCredentials } from '@better-auth/core/oauth2'
+import { isAPIError } from 'better-auth/api'
+import type { Context } from 'hono'
+import { Hono } from 'hono'
+import { Base64 } from 'ox'
+import { env } from 'void/env'
+import * as z from 'zod'
+import * as Apps from '../internal/Apps.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 Logout from '../internal/Logout.js'
+import * as OpenApi from '../internal/OpenApi.js'
+import * as RateLimit from '../internal/RateLimit.js'
+import * as SigningKey from '../internal/SigningKey.js'
+import * as Timing from '../internal/Timing.js'
+import * as Validation from '../internal/Validation.js'
+import * as AccountStep from './lib/AccountStep.js'
+import { db } from './lib/Database.js'
+import * as DeviceRequest from './lib/DeviceRequest.js'
+import * as Session from './lib/Session.js'
+import * as SignInConsent from './lib/SignInConsent.js'
+
+namespace schema {
+  export namespace openidConfiguration {
+    export const response = z
+      .looseObject({
+        authorization_endpoint: z.url().meta({
+          description: 'The authorization endpoint.',
+          examples: ['https://id.tempo.xyz/oauth2/authorize'],
+        }),
+        issuer: z.url().meta({
+          description: "The issuer's identifier, every token's `iss`.",
+          examples: ['https://id.tempo.xyz'],
+        }),
+        jwks_uri: z.url().meta({
+          description: "The issuer's signing keys.",
+          examples: ['https://id.tempo.xyz/oauth2/jwks'],
+        }),
+        token_endpoint: z.url().meta({
+          description: 'The token endpoint.',
+          examples: ['https://id.tempo.xyz/oauth2/token'],
+        }),
+      })
+      .meta({
+        description:
+          "The issuer's metadata (RFC 8414 §2, OpenID Connect Discovery §3), with the members that RFC 8414 defines.",
+        id: 'AuthorizationServerMetadata',
+      })
+  }
+
+  export namespace oauthAuthorizationServer {
+    export const response = openidConfiguration.response
+  }
+
+  export namespace authorize {
+    export const query = z.object({
+      challenge: z
+        .string()
+        .optional()
+        .meta({
+          description:
+            "A message, such as a sign-in challenge from the app's backend, whose EIP-191 hash becomes the key authorization's `witness` (TIP-1053). Requires `key_authorization`, and the app's `tempo-id:sign` scope.",
+          examples: ['Sign in to app.example.com\nNonce: 7f3a9c2e5b1d4f60'],
+        }),
+      client_id: z.string().meta({
+        description: "The app's client ID.",
+        examples: ['tempo-cli'],
+      }),
+      code_challenge: z.string().meta({
+        description:
+          'The PKCE challenge: the base64url SHA-256 hash of the code verifier (RFC 7636 §4.2).',
+        examples: ['E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM'],
+      }),
+      code_challenge_method: z.literal('S256').meta({
+        description: 'The PKCE challenge method.',
+      }),
+      key_authorization: z
+        .string()
+        .optional()
+        .meta({
+          description:
+            "A key authorization for the app's own key, as base64url JSON in the shape of `KeyAuthorizationRequest`. The approval page shows the key, and `/oauth2/token` returns it beside the tokens once approval signs it. A key that breaks a rule returns to the redirect URI with the refusal.",
+          examples: [
+            'eyJhZGRyZXNzIjoiMHg4MWMwZjIyYmQxNzNjMTE1ZDE4ZWVlYTBmNmEzOGU5MzVlY2Y1MmZiIn0',
+          ],
+        }),
+      prompt: z
+        .enum(['consent', 'login', 'none', 'select_account'])
+        .optional()
+        .meta({
+          description:
+            'Whether the user signs in or consents again (OIDC Core §3.1.2.1). Absent to reuse the session and stored consent.',
+          examples: ['consent'],
+        }),
+      redirect_uri: z.url().meta({
+        description: "One of the app's registered redirect URIs.",
+        examples: ['https://app.example/callback'],
+      }),
+      resource: z
+        .url()
+        .optional()
+        .meta({
+          description:
+            "The API the access token is for (RFC 8707). Absent for Tempo ID's own origin.",
+          examples: ['https://id.tempo.xyz'],
+        }),
+      response_type: z.literal('code').meta({
+        description: 'The authorization code flow.',
+      }),
+      scope: z.string().meta({
+        description: 'Space-separated OAuth scopes.',
+        examples: ['openid profile email'],
+      }),
+      state: z
+        .string()
+        .optional()
+        .meta({
+          description:
+            'An opaque value that the redirect returns to the app unchanged.',
+          examples: ['af0ifjsldkj'],
+        }),
+    })
+
+    export const response = z
+      .object({
+        redirect: z.boolean().meta({
+          description: 'Whether the app sends the browser to `url`.',
+          examples: [true],
+        }),
+        url: z.string().meta({
+          description:
+            'Where the browser goes next: the sign-in page, the consent page, or the redirect URI with a code.',
+          examples: [
+            'https://app.example/callback?code=SplxlOBeZQQYbYS6WxSbIA',
+          ],
+        }),
+      })
+      .meta({
+        description:
+          'The next step of the authorization, for a request that a script sends.',
+      })
+  }
+
+  export namespace token {
+    /** An OAuth error response from the issuer, passed through. It carries no `reason`. */
+    export const error = z
+      .object({
+        error: z.string().meta({
+          description:
+            'The RFC 6749 error code, such as `invalid_grant` or `invalid_client`.',
+          examples: ['invalid_grant'],
+        }),
+        error_description: z
+          .string()
+          .optional()
+          .meta({
+            description:
+              "The issuer's description of the error. Absent when the issuer sends none.",
+            examples: ['invalid code'],
+          }),
+        error_uri: z
+          .url()
+          .optional()
+          .meta({
+            description:
+              'A page about the error. Absent when the issuer sends none.',
+            examples: ['https://example.com/docs/errors#invalid_grant'],
+          }),
+        request_id: z
+          .string()
+          .optional()
+          .meta({
+            description:
+              'The request ID, which Tempo ID adds and `X-Request-Id` also carries.',
+            examples: ['5b3e1f2a-8c4d-4e6f-9a0b-7c2d1e3f4a5b'],
+          }),
+      })
+      .meta({
+        description:
+          "The issuer's OAuth error response (RFC 6749 §5.2), passed through.",
+        id: 'OAuthErrorResponse',
+      })
+
+    export const form = z.object({
+      client_id: z
+        .string()
+        .optional()
+        .meta({
+          description:
+            "The app's client ID. Absent when the app authenticates with HTTP Basic `Authorization`.",
+          examples: ['tempo-cli'],
+        }),
+      client_secret: z
+        .string()
+        .optional()
+        .meta({
+          description: "A confidential app's secret.",
+          examples: ['3bTm9qXc2Lr7WvN5kYp8Hs4Df6Ga1Je0'],
+        }),
+      code: z
+        .string()
+        .optional()
+        .meta({
+          description:
+            'The authorization code to redeem, for the `authorization_code` grant.',
+          examples: ['SplxlOBeZQQYbYS6WxSbIA'],
+        }),
+      code_verifier: z
+        .string()
+        .optional()
+        .meta({
+          description:
+            "The PKCE verifier whose S256 hash is the authorization request's `code_challenge` (RFC 7636 §4.5).",
+          examples: ['dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk'],
+        }),
+      device_code: z
+        .string()
+        .optional()
+        .meta({
+          description:
+            'The device code, for the device code grant (RFC 8628 §3.4).',
+          examples: ['GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS'],
+        }),
+      grant_type: z
+        .enum([
+          'authorization_code',
+          'client_credentials',
+          'refresh_token',
+          'urn:ietf:params:oauth:grant-type:device_code',
+        ])
+        .meta({
+          description: 'The OAuth grant that the request redeems.',
+          examples: ['authorization_code'],
+        }),
+      redirect_uri: z
+        .string()
+        .optional()
+        .meta({
+          description:
+            'The redirect URI of the authorization request, for the `authorization_code` grant.',
+          examples: ['https://app.example/callback'],
+        }),
+      refresh_token: z
+        .string()
+        .optional()
+        .meta({
+          description:
+            'The refresh token to redeem, for the `refresh_token` grant.',
+          examples: ['yAjhKk7QnRZ3vD9pLm2Xc8Ws5Tf1Ub4N'],
+        }),
+      resource: z
+        .url()
+        .optional()
+        .meta({
+          description:
+            "The API the access token is for (RFC 8707). Absent for Tempo ID's own origin.",
+          examples: ['https://id.tempo.xyz'],
+        }),
+      scope: z
+        .string()
+        .optional()
+        .meta({
+          description:
+            'Space-separated OAuth scopes to request. Absent to keep the scopes of the grant.',
+          examples: ['openid profile email'],
+        }),
+    })
+
+    export const response = z
+      .looseObject({
+        access_token: z.string().meta({
+          description:
+            'The access token, an RS256 JWT for the requested resource.',
+          examples: [
+            'eyJhbGciOiJSUzI1NiIsInR5cCI6ImF0K2p3dCJ9.e30.c2lnbmF0dXJl',
+          ],
+        }),
+        account: KeyAuthorization.schema.account.optional().meta({
+          description:
+            'The Tempo Account that the key acts for. Present beside `key_authorization`.',
+          examples: ['0x9a073914db0d149375ac2b7fbb72c68c0780fb5f'],
+        }),
+        expires_in: z.number().meta({
+          description: 'How long the access token lasts, in seconds.',
+          examples: [300],
+        }),
+        id_token: z
+          .string()
+          .optional()
+          .meta({
+            description:
+              'The ID token, an RS256 JWT. Absent without the `openid` scope.',
+            examples: ['eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.e30.c2lnbmF0dXJl'],
+          }),
+        key_authorization: KeyAuthorization.schema.rpc.optional().meta({
+          description:
+            'The key authorization that the approval page or the device page signed, for the first redemption of a code or device code whose request carried `key_authorization`. Absent for every other code, a refresh, and a key that expired.',
+        }),
+        refresh_token: z
+          .string()
+          .optional()
+          .meta({
+            description:
+              'The refresh token. Absent without the `offline_access` scope.',
+            examples: ['yAjhKk7QnRZ3vD9pLm2Xc8Ws5Tf1Ub4N'],
+          }),
+        scope: z
+          .string()
+          .optional()
+          .meta({
+            description: 'Space-separated OAuth scopes of the tokens.',
+            examples: ['openid profile email'],
+          }),
+        token_type: z.string().meta({
+          description: 'The type of the access token (RFC 6749 §7.1).',
+          examples: ['Bearer'],
+        }),
+      })
+      .meta({
+        description: "The issuer's token response (RFC 6749 §5.1).",
+        id: 'TokenResponse',
+      })
+  }
+
+  export namespace deviceCode {
+    export const form = z.object({
+      client_id: z
+        .string()
+        .optional()
+        .meta({
+          description:
+            'The client ID of an app that holds the device grant. Absent when the app authenticates with HTTP Basic `Authorization`.',
+          examples: ['tempo-cli'],
+        }),
+      client_secret: z
+        .string()
+        .optional()
+        .meta({
+          description: "A confidential app's secret.",
+          examples: ['3bTm9qXc2Lr7WvN5kYp8Hs4Df6Ga1Je0'],
+        }),
+      resource: z
+        .url()
+        .optional()
+        .meta({
+          description:
+            "The API the access token is for (RFC 8707). Absent for Tempo ID's own origin.",
+          examples: ['https://id.tempo.xyz'],
+        }),
+      scope: z
+        .string()
+        .optional()
+        .meta({
+          description:
+            'Space-separated OAuth scopes. Defaults to `openid email offline_access`.',
+          examples: ['openid email offline_access'],
+        }),
+    })
+
+    /** The parameters that Tempo ID adds to the device authorization request. */
+    export const extension = z.object({
+      // The device page shows the challenge as the message that the key signs, so control and format
+      // characters, such as bidi overrides, cannot reorder it. Newlines and tabs stay.
+      challenge: Authorize.schema.challenge.refine(
+        (value) =>
+          value === undefined || /^(?:[\t\n]|[^\p{Cc}\p{Cf}])*$/u.test(value),
+        {
+          message:
+            'Remove control and format characters, such as bidi overrides',
+        },
+      ),
+      device: z
+        .string()
+        .trim()
+        .min(1)
+        .max(64)
+        // The device page shows the name as the device reports it, so control and format characters,
+        // such as bidi overrides, cannot reorder the text around it.
+        .regex(/^[^\p{Cc}\p{Cf}]*$/u, {
+          message:
+            'Remove control and format characters, such as bidi overrides',
+        })
+        .optional()
+        .meta({
+          description:
+            "The name that the device page shows, such as the machine's hostname. It holds no control or format characters.",
+          examples: ['ada-macbook'],
+        }),
+      key_authorization: authorize.query.shape.key_authorization.meta({
+        description:
+          "A key authorization for the app's own key, as base64url JSON in the shape of `KeyAuthorizationRequest`, from a public first-party app only. The device page shows it, approval signs it, and `/oauth2/token` returns it beside the tokens.",
+        examples: [
+          'eyJhZGRyZXNzIjoiMHg4MWMwZjIyYmQxNzNjMTE1ZDE4ZWVlYTBmNmEzOGU5MzVlY2Y1MmZiIn0',
+        ],
+      }),
+    })
+
+    export const response = z
+      .object({
+        device_code: z.string().meta({
+          description:
+            'The secret code that the device polls `/oauth2/token` with (RFC 8628 §3.2). The device keeps it private.',
+          examples: ['GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS'],
+        }),
+        expires_in: z.number().meta({
+          description: 'Seconds until the device code and user code expire.',
+          examples: [600],
+        }),
+        interval: z.number().meta({
+          description: 'Seconds between polls.',
+          examples: [5],
+        }),
+        user_code: z.string().meta({
+          description:
+            'The code that the user enters on the verification page: eight consonants.',
+          examples: ['WDJBMJHT'],
+        }),
+        verification_uri: z.url().meta({
+          description: 'The page where the user enters the user code.',
+          examples: ['https://id.tempo.xyz/device'],
+        }),
+        verification_uri_complete: z.url().meta({
+          description:
+            'The verification page with the user code filled in, for a link or QR code.',
+          examples: ['https://id.tempo.xyz/device?user_code=WDJBMJHT'],
+        }),
+      })
+      .meta({
+        description:
+          "The issuer's device authorization response (RFC 8628 §3.2).",
+      })
+
+    /** Better Auth's response, with the members that the device page's record reads. */
+    export const issued = z.looseObject({
+      device_code: z.string(),
+      expires_in: z.number(),
+      user_code: z.string(),
+    })
+  }
+
+  export namespace introspect {
+    export const form = z.object({
+      client_id: token.form.shape.client_id,
+      client_secret: token.form.shape.client_secret,
+      token: z.string().meta({
+        description: 'The token to introspect.',
+        examples: ['yAjhKk7QnRZ3vD9pLm2Xc8Ws5Tf1Ub4N'],
+      }),
+      token_type_hint: z
+        .enum(['access_token', 'refresh_token'])
+        .optional()
+        .meta({
+          description:
+            'The type of `token`, which helps the issuer find it (RFC 7662 §2.1).',
+          examples: ['refresh_token'],
+        }),
+    })
+
+    export const response = z
+      .looseObject({
+        active: z.boolean().meta({
+          description:
+            'Whether the token is active. An inactive token has no other members.',
+          examples: [true],
+        }),
+        client_id: z
+          .string()
+          .optional()
+          .meta({
+            description: 'The client ID of the app that the token belongs to.',
+            examples: ['tempo-cli'],
+          }),
+        exp: z
+          .number()
+          .optional()
+          .meta({
+            description: 'When the token expires, in Unix seconds.',
+            examples: [1792076100],
+          }),
+        iat: z
+          .number()
+          .optional()
+          .meta({
+            description: 'When the issuer issued the token, in Unix seconds.',
+            examples: [1792075800],
+          }),
+        iss: z
+          .string()
+          .optional()
+          .meta({
+            description: "The issuer's identifier.",
+            examples: ['https://id.tempo.xyz'],
+          }),
+        scope: z
+          .string()
+          .optional()
+          .meta({
+            description: 'Space-separated OAuth scopes of the token.',
+            examples: ['openid profile email'],
+          }),
+        sub: z
+          .string()
+          .optional()
+          .meta({
+            description: "The user ID of the token's subject.",
+            examples: ['user_01JZ8Q6W3N1R5B4V7C2X9K0M3T'],
+          }),
+      })
+      .meta({
+        description: "The issuer's introspection response (RFC 7662 §2.2).",
+        id: 'IntrospectionResponse',
+      })
+  }
+
+  export namespace revoke {
+    export const form = z.object({
+      client_id: token.form.shape.client_id,
+      client_secret: token.form.shape.client_secret,
+      token: z.string().meta({
+        description: 'The access or refresh token to revoke.',
+        examples: ['yAjhKk7QnRZ3vD9pLm2Xc8Ws5Tf1Ub4N'],
+      }),
+      token_type_hint: introspect.form.shape.token_type_hint,
+    })
+  }
+
+  export namespace userinfo {
+    export const response = z
+      .looseObject({
+        email: z
+          .string()
+          .optional()
+          .meta({
+            description:
+              "The user's email address. Absent without the `email` scope.",
+            examples: ['ada@example.com'],
+          }),
+        email_verified: z
+          .boolean()
+          .optional()
+          .meta({
+            description:
+              'Whether the issuer verified the email address. Absent without the `email` scope.',
+            examples: [true],
+          }),
+        sub: z.string().meta({
+          description: 'The user ID.',
+          examples: ['user_01JZ8Q6W3N1R5B4V7C2X9K0M3T'],
+        }),
+      })
+      .meta({
+        description: "The issuer's UserInfo response (OIDC Core §5.3.2).",
+        id: 'UserInfoResponse',
+      })
+  }
+
+  export namespace endSession {
+    export const query = z.object({
+      client_id: z
+        .string()
+        .optional()
+        .meta({
+          description:
+            "The app's client ID. Absent when `id_token_hint` names the app.",
+          examples: ['tempo-cli'],
+        }),
+      continuation: z
+        .string()
+        .optional()
+        .meta({
+          description:
+            'The sealed parameters of a form POST that carried no session cookie, which its 303 sends here. Absent otherwise.',
+          examples: ['a3f1c2…'],
+        }),
+      id_token_hint: z
+        .string()
+        .optional()
+        .meta({
+          description:
+            'An ID token that Tempo ID issued to the app, even an expired one, which names the session to end. Required without `continuation`.',
+          examples: ['eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.e30.c2lnbmF0dXJl'],
+        }),
+      post_logout_redirect_uri: z
+        .url()
+        .optional()
+        .meta({
+          description:
+            "Where the browser goes after sign-out: one of the app's registered post-logout redirect URIs.",
+          examples: ['https://app.example/signed-out'],
+        }),
+      state: authorize.query.shape.state,
+    })
+
+    export const form = query.omit({ continuation: true }).extend({
+      id_token_hint: z.string().meta({
+        description:
+          'An ID token that Tempo ID issued to the app, which names the session to end. It may be expired.',
+        examples: ['eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.e30.c2lnbmF0dXJl'],
+      }),
+    })
+
+    export const response = z.object({
+      signed_out: z.literal(true).meta({
+        description:
+          'The browser holds no session that the hint names, since it ended or never held one.',
+      }),
+    })
+  }
+
+  export namespace jwks {
+    export const response = z
+      .object({
+        keys: z
+          .array(
+            z.looseObject({
+              alg: z
+                .string()
+                .optional()
+                .meta({
+                  description: 'The algorithm that the key signs with.',
+                  examples: ['RS256'],
+                }),
+              kid: z
+                .string()
+                .optional()
+                .meta({
+                  description:
+                    'The key ID, which matches the `kid` header of a token that the key signs.',
+                  examples: ['Qq0BN2lPx8VzTRsaGgMjc5HbEFKY4Wty'],
+                }),
+              kty: z.string().meta({
+                description: 'The key family (RFC 7518 §6.1).',
+                examples: ['RSA'],
+              }),
+            }),
+          )
+          .meta({
+            description:
+              "The issuer's public signing keys, with the members of each key that RFC 7517 defines.",
+          }),
+      })
+      .meta({
+        description: "The issuer's JSON Web Key Set (RFC 7517 §5).",
+        id: 'JsonWebKeySet',
+      })
+  }
+}
+
+/**
+ * The issuer's refusals, which pass through with their own status, and the `unexpected` error
+ * response that Tempo ID returns when the issuer fails.
+ */
+const passthrough = {
+  ...OpenApi.errors([]),
+  400: {
+    content: {
+      'application/json': { schema: OpenApi.resolver(schema.token.error) },
+    },
+    description: "The issuer's refusal, passed through.",
+  },
+  401: {
+    content: {
+      'application/json': { schema: OpenApi.resolver(schema.token.error) },
+    },
+    description: "The issuer's refusal of the client or token, passed through.",
+  },
+} as const
+
+/** The responses of `POST /oauth2/introspect` in the OpenAPI document. */
+const introspectRoute = {
+  responses: {
+    200: {
+      content: {
+        'application/json': {
+          schema: OpenApi.resolver(schema.introspect.response),
+        },
+      },
+      description: "The issuer's introspection response.",
+    },
+    ...passthrough,
+    ...OpenApi.errors([...BodyLimit.errors, ...RateLimit.check.errors]),
+  },
+  security: [{}, { clientBasic: [] }],
+  tags: ['OAuth'],
+}
+
+/** The description and responses of `GET` and `POST /oauth2/end-session` in the OpenAPI document. */
+const endSessionRoute = {
+  description:
+    "Signs the browser out of the session that the app's ID token names, if the browser holds it, and revokes the tokens that apps received through it (OpenID Connect RP-Initiated Logout). Any other session stays signed in, and Tempo ID redirects the browser to the app's post-logout redirect URI.",
+  responses: {
+    302: {
+      description:
+        "Redirects the browser to the app's post-logout redirect URI, with `state`.",
+    },
+    ...OpenApi.responses({
+      errors: [...OpenApi.validate.errors, ...Logout.check.errors],
+      success: {
+        description:
+          'The browser is signed out of the session that the hint names, for a request without `post_logout_redirect_uri`.',
+        schema: schema.endSession.response,
+      },
+    }),
+  },
+  tags: ['OAuth'],
+}
+
+/**
+ * Returns the refusal of the device authorization request `form`'s `key`, or `undefined`. Only a
+ * public first-party device app receives a key, since its poll sends no secret, and a third-party
+ * app authorizes keys through a redirect. The device page shows the key, so a key that approval
+ * would refuse is refused here, before the device shows a code.
+ */
+async function refuseDeviceKey(
+  c: Context<Env>,
+  options: refuseDeviceKey.Options,
+): Promise<ErrorResponse.Instance<typeof refuseDeviceKey.errors> | undefined> {
+  const { form, key } = options
+  const clientId = basicClientId(c.req.raw) ?? form.get('client_id')
+  const app = clientId
+    ? await Timing.measure(
+        c,
+        Apps.get(db, { clientId, enabled: true }).catch((error: unknown) => {
+          if (error instanceof Apps.NotFoundError) return undefined
+          throw error
+        }),
+        'Apps.get',
+      )
+    : undefined
+  if (!clientId || !app?.device || app.secret || !app.firstParty)
+    return new Authorize.RejectedError({
+      description: `Device grant refused: \`client_id\` ${clientId ?? '(none)'} names no enabled public first-party device app. Send the client ID of a registered device app, or leave out \`key_authorization\`.`,
+    })
+  return (
+    KeyAuthorization.check(key) ??
+    KeyAuthorization.checkChallenge({ app, clientId, key })
+  )
+}
+
+declare namespace refuseDeviceKey {
+  type Options = {
+    /** The device authorization request's form. */
+    form: URLSearchParams
+    /** The key that the form requests, with its challenge bound. */
+    key: KeyAuthorization.Key
+  }
+}
+
+namespace refuseDeviceKey {
+  /** The refusals `refuseDeviceKey` returns. Its return type admits no other. */
+  export const errors = [
+    ...KeyAuthorization.check.errors,
+    ...KeyAuthorization.checkChallenge.errors,
+    Authorize.RejectedError,
+  ] as const
+}
+
+/**
+ * Returns the refusal of a `form` that repeats one of `names`, or `undefined`. A request parameter
+ * appears at most once (RFC 6749 §3.1).
+ */
+function repeated(form: URLSearchParams, options: repeated.Options) {
+  const name = options.names.find((entry) => form.getAll(entry).length > 1)
+  if (!name) return undefined
+  return new Validation.InvalidFieldError({
+    issues: [{ message: 'Repeated parameter. Send it once', path: [name] }],
+  })
+}
+
+declare namespace repeated {
+  type Options = {
+    /** The parameters that may appear once. */
+    names: readonly string[]
+  }
+}
+
+/** The protocol paths that Better Auth serves over HTTP, with any method it accepts. */
+const paths = [
+  '/.well-known/oauth-authorization-server',
+  '/.well-known/openid-configuration',
+  '/oauth2/authorize',
+  '/oauth2/introspect',
+  '/oauth2/jwks',
+  '/oauth2/revoke',
+  '/oauth2/token',
+  '/oauth2/userinfo',
+] as const
+
+/** Tempo ID's pages that an authorization redirects to, which `GET /oauth2/authorize` renders. */
+const pages: ReadonlySet<string> = new Set([
+  '/authorize',
+  '/choose-account',
+  '/error',
+  '/login',
+])
+
+/** The paths whose handler resolves the client that the request names, which `limitDiscovery` counts. */
+const discoveryPaths: ReadonlySet<string> = new Set([
+  '/device/code',
+  '/oauth2/authorize',
+  '/oauth2/introspect',
+  '/oauth2/revoke',
+  '/oauth2/token',
+])
+
+/** The OAuth and OpenID protocol routes. */
+export const oauth = new Hono<Env>()
+  .get(
+    '/.well-known/openid-configuration',
+    OpenApi.describeRoute({
+      description: "Reads the issuer's OpenID Connect discovery document.",
+      responses: OpenApi.responses({
+        success: {
+          description: 'The discovery document.',
+          schema: schema.openidConfiguration.response,
+        },
+      }),
+      tags: ['OAuth'],
+    }),
+    (c) => discovery(c),
+  )
+  .get(
+    '/.well-known/oauth-authorization-server',
+    OpenApi.describeRoute({
+      description: "Reads the issuer's authorization server metadata.",
+      responses: OpenApi.responses({
+        success: {
+          description: 'The metadata.',
+          schema: schema.oauthAuthorizationServer.response,
+        },
+      }),
+      tags: ['OAuth'],
+    }),
+    (c) => discovery(c),
+  )
+  .get(
+    '/oauth2/authorize',
+    OpenApi.describeRoute({
+      description:
+        'Starts an authorization. A signed-out browser receives the sign-in page, and a signed-in one the consent page or a redirect to the redirect URI with a code.',
+      responses: {
+        200: {
+          content: {
+            'application/json': {
+              schema: OpenApi.resolver(schema.authorize.response),
+            },
+            'text/html': { schema: { type: 'string' } },
+          },
+          description:
+            "The next step as JSON, for a request from a script. A browser navigation receives Tempo ID's page of the next step, such as the sign-in page or the error page.",
+        },
+        302: {
+          description:
+            'Redirects the browser to the redirect URI with a code. A refused `key_authorization` returns to the redirect URI with `error` and `error_description`.',
+        },
+        ...passthrough,
+        // A third-party app's requests count per address, before the redirect.
+        ...OpenApi.errors(RateLimit.check.errors),
+      },
+      tags: ['OAuth'],
+    }),
+    OpenApi.input('query', schema.authorize.query),
+    async (c) => {
+      const response = await Timing.measure(c, forward(c), 'oauth2.forward')
+      // A redirect to one of Tempo ID's own pages renders that page in this response, so the
+      // browser loads the page without a second request. Its URL keeps the signed query.
+      const location = URL.parse(
+        response.headers.get('location') ?? '',
+        env.URL,
+      )
+      if (
+        response.status !== 302 ||
+        location?.origin !== new URL(env.URL).origin ||
+        !pages.has(location.pathname)
+      )
+        return response
+
+      const setCookie = response.headers.getSetCookie()
+      for (const cookie of setCookie)
+        c.header('set-cookie', cookie, { append: true })
+      const request = new Request(location, {
+        headers: SignInConsent.sessionHeaders(c, { setCookie }),
+      })
+      return Timing.measure(c, c.env.pages(c, { request }), 'page.render')
+    },
+  )
+  .post(
+    '/oauth2/token',
+    OpenApi.describeRoute({
+      description:
+        'Redeems an authorization code, a refresh token, a device code, or client credentials for tokens.',
+      responses: {
+        200: {
+          content: {
+            'application/json': {
+              schema: OpenApi.resolver(schema.token.response),
+            },
+          },
+          description: 'The tokens.',
+        },
+        ...passthrough,
+        ...OpenApi.errors([
+          ...BodyLimit.errors,
+          ...OpenApi.validate.errors,
+          ...RateLimit.check.errors,
+        ]),
+      },
+      // Body credentials or HTTP Basic, so either requirement satisfies it.
+      security: [{}, { clientBasic: [] }],
+      tags: ['OAuth'],
+    }),
+    OpenApi.input('form', schema.token.form),
+    async (c) => {
+      const limited = await Timing.measure(
+        c,
+        RateLimit.check(c, {
+          limits: [{ binding: 'TOKEN_LIMIT', key: RateLimit.ip(c) }],
+        }),
+        'RateLimit.check',
+      )
+      if (limited) return limited
+
+      // A client ID is the caller's to choose, so an app's limit counts only a request whose client
+      // secret matches. A public app has no secret, and only the IP address bounds its callers.
+      const form = new URLSearchParams(
+        await Timing.measure(c, c.req.text(), 'request.text'),
+      )
+      const credentials = clientCredentials({
+        authorization: c.req.header('authorization'),
+        form,
+      })
+      const authenticated = credentials
+        ? await Timing.measure(
+            c,
+            Apps.authenticate(db, credentials),
+            'Apps.authenticate',
+          )
+        : false
+      const limitedApp = await Timing.measure(
+        c,
+        RateLimit.check(c, {
+          limits: [
+            {
+              binding: 'TOKEN_APP_LIMIT',
+              key: authenticated ? credentials?.clientId : undefined,
+            },
+          ],
+        }),
+        'RateLimit.check',
+      )
+      if (limitedApp) return limitedApp
+
+      // Better Auth reads the last value of a parameter, so the row is read for the code it redeems.
+      const twice = repeated(form, { names: ['device_code', 'grant_type'] })
+      if (twice) return ErrorResponse.json(c, twice)
+      // The redemption deletes the device code's row, so the row that names its held key is read
+      // first.
+      const deviceCode =
+        form.get('grant_type') === Apps.deviceGrant
+          ? form.get('device_code')
+          : null
+      const row = deviceCode
+        ? await Timing.measure(
+            c,
+            Device.find(db, { deviceCode }),
+            'Device.find',
+          )
+        : undefined
+      const response = await Timing.measure(c, forward(c), 'oauth2.forward')
+      if (!row || !response.ok) return response
+      return Timing.measure(
+        c,
+        withDeviceKey(c, { id: row.id, response }),
+        'oauth2.withDeviceKey',
+      )
+    },
+  )
+  .post(
+    '/device/code',
+    OpenApi.describeRoute({
+      description:
+        'Starts the device grant (RFC 8628 §3.1). The user approves the user code on the device page, and the device then redeems the device code at `/oauth2/token`.',
+      responses: {
+        200: {
+          content: {
+            'application/json': {
+              schema: OpenApi.resolver(schema.deviceCode.response),
+            },
+          },
+          description: 'The device code.',
+        },
+        ...passthrough,
+        ...OpenApi.errors([
+          ...BodyLimit.errors,
+          ...OpenApi.validate.errors,
+          ...RateLimit.check.errors,
+          ...refuseDeviceKey.errors,
+        ]),
+      },
+      security: [{}, { clientBasic: [] }],
+      tags: ['OAuth'],
+    }),
+    OpenApi.input(
+      'form',
+      schema.deviceCode.form.extend(schema.deviceCode.extension.shape),
+    ),
+    async (c) => {
+      // A client ID in the body is the caller's to choose, so only the IP address bounds a caller. Any
+      // page can post this form from a visitor's browser, which sends `Origin` and a CLI does not, so
+      // a page's requests count apart and spend none of the quota of a CLI at the same address.
+      const ip = RateLimit.ip(c)
+      const limited = await Timing.measure(
+        c,
+        RateLimit.check(c, {
+          limits: [
+            {
+              binding: 'DEVICE_LIMIT',
+              key:
+                ip !== undefined && c.req.header('origin') !== undefined
+                  ? `${ip}:browser`
+                  : ip,
+            },
+          ],
+        }),
+        'RateLimit.check',
+      )
+      if (limited) return limited
+
+      const form = new URLSearchParams(
+        await Timing.measure(c, c.req.text(), 'request.text'),
+      )
+      // Better Auth reads the last value of a parameter, and Tempo ID's checks the first.
+      const twice = repeated(form, { names: ['client_id', 'device'] })
+      if (twice) return ErrorResponse.json(c, twice)
+      // The issuer prefers Basic credentials to the form's `client_id`, so the two must name one app.
+      const basic = basicClientId(c.req.raw)
+      if (basic && form.has('client_id') && form.get('client_id') !== basic)
+        return ErrorResponse.json(
+          c,
+          new Validation.InvalidFieldError({
+            issues: [
+              {
+                message:
+                  'Conflicting client ID. Send the one of the Basic credentials, or leave it out',
+                path: ['client_id'],
+              },
+            ],
+          }),
+        )
+      const extension = schema.deviceCode.extension.safeParse({
+        challenge: form.get('challenge') ?? undefined,
+        device: form.get('device') ?? undefined,
+        key_authorization: form.get('key_authorization') ?? undefined,
+      })
+      if (!extension.success)
+        return ErrorResponse.json(
+          c,
+          new Validation.InvalidFieldError({ issues: extension.error.issues }),
+        )
+      const { challenge, device } = extension.data
+      const key = Authorize.fromQuery(form)
+      if (key instanceof ErrorResponse.ResponseError)
+        return ErrorResponse.json(c, key)
+
+      if (key) {
+        const refused = await Timing.measure(
+          c,
+          refuseDeviceKey(c, { form, key }),
+          'oauth2.refuseDeviceKey',
+        )
+        if (refused) return ErrorResponse.json(c, refused)
+      }
+
+      const response = await Timing.measure(c, forward(c), 'oauth2.forward')
+      if (!response.ok) return response
+      // The device page shows where each code came from and the key it requests.
+      const code = schema.deviceCode.issued.parse(
+        await Timing.measure(c, response.json(), 'response.json'),
+      )
+      await Timing.measure(
+        c,
+        DeviceRequest.create(c, {
+          challenge,
+          device: device ?? null,
+          deviceCode: code.device_code,
+          expiresIn: code.expires_in,
+          key: key && unbound(form),
+        }),
+        'DeviceRequest.create',
+      )
+
+      // The user code reads in two groups of four, as the device page shows it.
+      const userCode = Device.format(code.user_code)
+      const verification = new URL(Device.page, env.URL)
+      const headers = new Headers(response.headers)
+      headers.delete('content-length')
+      return new Response(
+        JSON.stringify({
+          ...code,
+          user_code: userCode,
+          verification_uri: verification.href,
+          verification_uri_complete: `${verification.href}?${new URLSearchParams({ code: userCode })}`,
+        }),
+        { headers, status: response.status },
+      )
+    },
+  )
+  .post(
+    '/oauth2/introspect',
+    OpenApi.describeRoute({
+      description:
+        'Introspects a token (RFC 7662). The app authenticates with its client credentials, in the body or as HTTP Basic `Authorization`.',
+      ...introspectRoute,
+    }),
+    OpenApi.input('form', schema.introspect.form),
+    (c) => forward(c),
+  )
+  .post(
+    '/oauth2/revoke',
+    OpenApi.describeRoute({
+      description:
+        'Revokes an access or refresh token (RFC 7009). The app authenticates with its client credentials, in the body or as HTTP Basic `Authorization`.',
+      responses: {
+        200: {
+          content: {
+            'application/json': {
+              schema: {
+                description:
+                  'Empty: the token is revoked, or was already invalid (RFC 7009 §2.2).',
+              },
+            },
+          },
+          description: 'The token is revoked.',
+        },
+        ...passthrough,
+        ...OpenApi.errors([...BodyLimit.errors, ...RateLimit.check.errors]),
+      },
+      security: [{}, { clientBasic: [] }],
+      tags: ['OAuth'],
+    }),
+    OpenApi.input('form', schema.revoke.form),
+    (c) => forward(c),
+  )
+  .get(
+    '/oauth2/userinfo',
+    OpenApi.describeRoute({
+      description: "Reads the token subject's claims (OIDC Core §5.3).",
+      responses: {
+        200: {
+          content: {
+            'application/json': {
+              schema: OpenApi.resolver(schema.userinfo.response),
+            },
+          },
+          description: "The issuer's UserInfo response.",
+        },
+        ...passthrough,
+      },
+      security: [{ accessToken: [] }],
+      tags: ['OAuth'],
+    }),
+    (c) => forward(c),
+  )
+  .get(
+    '/oauth2/end-session',
+    OpenApi.describeRoute(endSessionRoute),
+    OpenApi.validate('query', schema.endSession.query),
+    async (c) => endSession(c, c.req.valid('query')),
+  )
+  .post(
+    '/oauth2/end-session',
+    OpenApi.describeRoute({
+      ...endSessionRoute,
+      responses: {
+        ...endSessionRoute.responses,
+        ...OpenApi.errors(BodyLimit.errors),
+        303: {
+          description:
+            'Continues a form POST without the session cookie as `GET /oauth2/end-session` with the sealed parameters in `continuation`, which the browser sends with the cookie.',
+        },
+      },
+    }),
+    OpenApi.validate('form', schema.endSession.form),
+    async (c) => endSession(c, c.req.valid('form')),
+  )
+  .get(
+    '/oauth2/jwks',
+    OpenApi.describeRoute({
+      description:
+        "Reads the issuer's signing keys. A verifier may cache the response for 60 seconds, since a new key signs 5 minutes after its rotation.",
+      responses: OpenApi.responses({
+        success: {
+          description: 'The JSON Web Key Set.',
+          schema: schema.jwks.response,
+        },
+      }),
+      tags: ['OAuth'],
+    }),
+    async (c) => {
+      const response = await Timing.measure(c, forward(c), 'oauth2.forward')
+      if (!response.ok) return response
+      // A verifier caches the key set a fifth of the publication delay, so it holds a rotation's new
+      // key well before the key signs. An empty set, before the first token creates the first key,
+      // stays uncached, so a verifier reads that key once it signs.
+      const keys = schema.jwks.response.safeParse(
+        await Timing.measure(c, response.clone().json(), 'response.json'),
+      )
+      if (keys.success && keys.data.keys.length > 0)
+        response.headers.set(
+          'cache-control',
+          `public, max-age=${SigningKey.publication / 5}`,
+        )
+      return response
+    },
+  )
+  // The other method of each path that Better Auth accepts, such as a `POST` to `/oauth2/userinfo`.
+  .on(['GET', 'POST'], [...paths], (c) => forward(c))
+
+/**
+ * Returns the client ID and secret of a token request: from HTTP Basic `Authorization`, whose parts
+ * RFC 6749 §2.3.1 form-encodes, or else from the form body, as Better Auth reads them. Returns
+ * `undefined` for a request without a client secret, with a repeated one, or with an
+ * `Authorization` header that does not decode.
+ */
+function clientCredentials(options: clientCredentials.Options) {
+  const { authorization, form } = options
+  // The issuer decodes with the same function, so both read the same credentials.
+  if (authorization && /^Basic +/i.test(authorization))
+    try {
+      return decodeBasicCredentials(authorization)
+    } catch {
+      return undefined
+    }
+
+  // Better Auth drops empty values and refuses a repeated one, so only a single value counts.
+  const [clientId, ...otherIds] = form
+    .getAll('client_id')
+    .filter((value) => value.length > 0)
+  const [clientSecret, ...otherSecrets] = form
+    .getAll('client_secret')
+    .filter((value) => value.length > 0)
+  if (!clientId || !clientSecret || otherIds.length || otherSecrets.length)
+    return undefined
+  return { clientId, clientSecret }
+}
+
+declare namespace clientCredentials {
+  type Options = {
+    /** The request's `Authorization` header. */
+    authorization: string | undefined
+    /** The request's form body. */
+    form: URLSearchParams
+  }
+}
+
+/**
+ * Serves RP-initiated logout for `GET` and `POST /oauth2/end-session`, with the request's parameters.
+ * It ends the browser's session only when the hint names that session, since RP-Initiated Logout §2
+ * asks the user to confirm any other logout. Every valid request redirects to the app.
+ */
+async function endSession(
+  c: Context<Env>,
+  input: z.output<typeof schema.endSession.query>,
+) {
+  const parameters =
+    input.continuation === undefined
+      ? input
+      : await Timing.measure(
+          c,
+          Logout.unseal(input.continuation, { secret: env.SECRET }),
+          'Logout.unseal',
+        )
+  if (!parameters)
+    return ErrorResponse.json(
+      c,
+      new Validation.InvalidFieldError({
+        issues: [
+          {
+            message:
+              'Expired or invalid continuation. Send the logout request again',
+            path: ['continuation'],
+          },
+        ],
+      }),
+    )
+  const hint = parameters.id_token_hint
+  if (!hint)
+    return ErrorResponse.json(
+      c,
+      new Validation.InvalidFieldError({
+        issues: [{ message: 'Required', path: ['id_token_hint'] }],
+      }),
+    )
+
+  const jwks = await Timing.measure(
+    c,
+    SigningKey.hintKeys(db, { hint }),
+    'SigningKey.hintKeys',
+  )
+  const logout = await Timing.measure(
+    c,
+    Logout.check(db, {
+      clientId: parameters.client_id,
+      hint,
+      issuer: env.URL,
+      jwks,
+      postLogoutRedirectUri: parameters.post_logout_redirect_uri,
+      state: parameters.state,
+    }),
+    'Logout.check',
+  )
+  if (logout instanceof ErrorResponse.ResponseError)
+    return ErrorResponse.json(c, logout)
+
+  const token = await Timing.measure(c, Session.token(c), 'Session.token')
+  // One statement ends the session that the hint names, when it is the browser's own session.
+  const ended = token
+    ? await Timing.measure(
+        c,
+        Logout.end(db, { sessionId: logout.sessionId, token }),
+        'Logout.end',
+      )
+    : undefined
+  const holds = ended !== undefined
+  // A browser sends the `SameSite=Lax` session cookie on a top-level GET, but not on a cross-site
+  // form POST, so a POST without the session continues as that GET. The GET never redirects again,
+  // and its URL holds the parameters sealed, so the ID token stays out of history and logs.
+  if (!holds && c.req.method === 'POST') {
+    const continuation = await Timing.measure(
+      c,
+      Logout.seal(
+        {
+          client_id: parameters.client_id,
+          id_token_hint: hint,
+          post_logout_redirect_uri: parameters.post_logout_redirect_uri,
+          state: parameters.state,
+        },
+        { secret: env.SECRET },
+      ),
+      'Logout.seal',
+    )
+    const url = new URL('/oauth2/end-session', env.URL)
+    url.searchParams.set('continuation', continuation)
+    c.header('cache-control', 'no-store')
+    return c.redirect(url.href, 303)
+  }
+
+  if (holds) {
+    await Timing.measure(c, Session.clear(c), 'Session.clear')
+    // The next sign-in chooses each app's account again, as after `POST /v1/auth/logout`.
+    c.header('set-cookie', AccountStep.clear(), { append: true })
+  }
+
+  c.header('cache-control', 'no-store')
+  if (logout.redirect) return c.redirect(logout.redirect, 302)
+  return c.json({ signed_out: true as const }, 200)
+}
+
+/** The discovery members of front-channel logout, which Tempo ID's end-session does not deliver. */
+const frontchannel = [
+  'frontchannel_logout_session_supported',
+  'frontchannel_logout_supported',
+] as const
+
+/**
+ * Forwards the discovery request `c` to Better Auth, and returns its document without the
+ * `frontchannel` members. The issuer advertises front-channel logout unconditionally, but
+ * `Logout.end` ends the session without the issuer's end-session page, which delivers it.
+ */
+async function discovery(c: Context<Env>) {
+  const response = await Timing.measure(c, forward(c), 'oauth2.forward')
+  // Hono serves HEAD through this GET route, and the issuer responds to HEAD without a body.
+  if (!response.ok || c.req.method === 'HEAD') return response
+
+  const document = z
+    .record(z.string(), z.unknown())
+    .parse(await Timing.measure(c, response.json(), 'response.json'))
+  for (const member of frontchannel) delete document[member]
+
+  const headers = new Headers(response.headers)
+  headers.delete('content-length')
+  return new Response(JSON.stringify(document), {
+    headers,
+    status: response.status,
+  })
+}
+
+/**
+ * Forwards the request `c` to Better Auth, and returns its response. An authorization request with
+ * a key that Tempo ID refuses returns to the app's redirect URI instead, as `refuseKey` describes.
+ * A request that names a third-party app past the address's `APP_DISCOVERY_LIMIT` responds with
+ * `rate_limited`.
+ */
+async function forward(c: Context<Env>) {
+  const request = await Timing.measure(
+    c,
+    withResource(c),
+    'oauth2.withResource',
+  )
+  const body =
+    request.method === 'POST'
+      ? await Timing.measure(c, request.clone().text(), 'request.text')
+      : undefined
+  // Better Auth reads a `POST` request's parameters from its form body, and only from there.
+  const form =
+    body !== undefined &&
+    request.headers
+      .get('content-type')
+      ?.toLowerCase()
+      .includes('application/x-www-form-urlencoded')
+  const query = form
+    ? new URLSearchParams(body)
+    : new URL(request.url).searchParams
+
+  const limited = await Timing.measure(
+    c,
+    limitDiscovery(c, { body, request }),
+    'oauth2.limitDiscovery',
+  )
+  if (limited) return limited
+
+  // Better Auth reads the last `client_id` of a form, and Tempo ID's checks the first, so a form
+  // that names two apps is refused before either reads it.
+  if (
+    c.req.path === '/oauth2/authorize' &&
+    query.getAll('client_id').length > 1
+  )
+    return ErrorResponse.json(
+      c,
+      new Validation.InvalidFieldError({
+        issues: [
+          { message: 'Repeated parameter. Send it once', path: ['client_id'] },
+        ],
+      }),
+    )
+
+  // The issuer approves a device code through `/oauth2/authorize` with its `user_code`, and responds
+  // whether the code is live without counting the request. The `/device` page approves device codes,
+  // and counts each user's lookups.
+  if (c.req.path === '/oauth2/authorize' && query.has('user_code'))
+    return ErrorResponse.json(
+      c,
+      new Validation.InvalidFieldError({
+        issues: [
+          {
+            message: 'Unsupported parameter. Approve a device code at /device',
+            path: ['user_code'],
+          },
+        ],
+      }),
+    )
+
+  // The token endpoint runs as Better Auth's endpoint, without the router that `auth.handler` builds
+  // from every endpoint for each request. The router's origin check and request hooks serve cookie
+  // sessions and discovery, and the token endpoint reads neither. The form reads as the router reads
+  // it, with the last value of a repeated parameter.
+  if (c.req.path === '/oauth2/token' && form) {
+    const params: Record<string, string> = {}
+    for (const [name, value] of query) params[name] = value
+    return Timing.measure(
+      c,
+      c.var.auth.api.oauth2Token({
+        asResponse: true,
+        // The endpoint validates the form against its schema, as for the router, so a form without
+        // `grant_type` is refused there.
+        body: params as typeof params & { grant_type: string },
+        headers: request.headers,
+        request,
+      }),
+      'auth.oauth2Token',
+    )
+  }
+
+  if (c.req.path !== '/oauth2/authorize')
+    return Timing.measure(c, c.var.auth.handler(request), 'auth.handler')
+
+  const refused = await Timing.measure(
+    c,
+    refuseKey(c, { query }),
+    'oauth2.refuseKey',
+  )
+  if (refused) return refused
+  return Timing.measure(c, c.var.auth.handler(request), 'auth.handler')
+}
+
+/**
+ * Returns the `rate_limited` refusal when `request` names a third-party app whose row is missing or
+ * stale and its address spent `APP_DISCOVERY_LIMIT`, or `undefined`. Resolving such an app fetches
+ * its metadata document and writes its row before any sign-in, so each address starts a bounded
+ * number of them. A request for an app with a fresh row, such as a refresh, counts only against the
+ * path's own limit. The issuer prefers Basic credentials to the parameters and checks no match, so the limit
+ * reads both.
+ */
+async function limitDiscovery(
+  c: Context<Env>,
+  options: { body: string | undefined; request: Request },
+) {
+  const { body, request } = options
+  const url = new URL(request.url)
+  if (!discoveryPaths.has(url.pathname)) return undefined
+  const clientIds = [
+    ...url.searchParams.getAll('client_id'),
+    ...bodyClientIds(body),
+    basicClientId(request),
+  ].filter((clientId) => clientId !== undefined)
+  if (!clientIds.some(Apps.thirdParty)) return undefined
+
+  const stale = await Timing.measure(
+    c,
+    Apps.stale(db, { clientIds }),
+    'Apps.stale',
+  )
+  if (stale.length === 0) return undefined
+  return Timing.measure(
+    c,
+    RateLimit.check(c, {
+      limits: [{ binding: 'APP_DISCOVERY_LIMIT', key: RateLimit.ip(c) }],
+    }),
+    'RateLimit.check',
+  )
+}
+
+/**
+ * Returns every client ID in `body`, read as a form and as JSON: each `client_id`, and the `sub` and
+ * `iss` of each `client_assertion`. The check counts each one, since the issuer drops an empty
+ * value, reads the client of an assertion from its claims before it verifies the signature, and
+ * `/device/code` also accepts JSON.
+ */
+function bodyClientIds(body: string | undefined): readonly string[] {
+  if (!body) return []
+  const form = new URLSearchParams(body)
+  const json = (() => {
+    try {
+      const value: unknown = JSON.parse(body)
+      if (typeof value !== 'object' || value === null) return []
+      const clientId = (value as Record<string, unknown>).client_id
+      return typeof clientId === 'string' ? [clientId] : []
+    } catch {
+      // A form body is no JSON.
+      return []
+    }
+  })()
+  const assertions = form.getAll('client_assertion').flatMap((assertion) => {
+    try {
+      const [, payload] = assertion.split('.')
+      const claims: unknown = JSON.parse(
+        new TextDecoder().decode(Base64.toBytes(payload ?? '')),
+      )
+      if (typeof claims !== 'object' || claims === null) return []
+      const { iss, sub } = claims as Record<string, unknown>
+      return [iss, sub].filter((claim) => typeof claim === 'string')
+    } catch {
+      // An assertion that does not decode names no client, and the issuer refuses it.
+      return []
+    }
+  })
+  return [...form.getAll('client_id'), ...json, ...assertions]
+}
+
+/** Returns the client ID of `request`'s Basic credentials, if any. */
+function basicClientId(request: Request) {
+  const authorization = request.headers.get('authorization')
+  if (!authorization || !/^Basic +/i.test(authorization)) return undefined
+  // The issuer decodes with the same function, so both read the same client ID.
+  try {
+    return decodeBasicCredentials(authorization).clientId
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Returns the redirect to the app's redirect URI with the refusal (RFC 6749 §4.1.2.1) when the
+ * authorization request's `query` carries a key or a challenge that Tempo ID refuses, before the
+ * browser signs in.
+ * Returns `undefined` for a request without a key, and for an unknown app or an unregistered
+ * redirect URI, which Better Auth refuses without the redirect.
+ */
+async function refuseKey(c: Context<Env>, options: { query: URLSearchParams }) {
+  const { query } = options
+  // A challenge without a key is refused too, since no witness would bind it.
+  if (!query.has('key_authorization') && !query.has('challenge'))
+    return undefined
+  const clientId = query.get('client_id')
+  const redirectUri = query.get('redirect_uri')
+  if (!clientId || !redirectUri) return undefined
+
+  // A third-party app has a row only once Better Auth resolves its metadata document. A document
+  // that fails to resolve leaves no app here, and Better Auth refuses the request itself.
+  if (Apps.thirdParty(clientId)) {
+    const resolved = await Timing.measure(
+      c,
+      c.var.auth.api
+        .resolveOAuthClient({ body: { client_id: clientId } })
+        .catch((error: unknown) => {
+          if (isAPIError(error)) return { resolved: false }
+          throw error
+        }),
+      'auth.resolveOAuthClient',
+    )
+    if (!resolved.resolved) return undefined
+  }
+
+  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 || !app.redirectUris.includes(redirectUri)) return undefined
+
+  const key = Authorize.fromQuery(query)
+  const refused =
+    key instanceof ErrorResponse.ResponseError
+      ? key
+      : key &&
+        Authorize.checkKey({
+          app,
+          clientId,
+          codeChallenge: query.get('code_challenge'),
+          key,
+          query,
+        })
+  if (!refused) return undefined
+
+  // Each parameter follows the registered URI's own, as Better Auth appends its refusals.
+  const url = new URL(redirectUri)
+  url.searchParams.append('error', refused.response.error)
+  url.searchParams.append(
+    'error_description',
+    refused.response.error_description,
+  )
+  const state = query.get('state')
+  if (state) url.searchParams.append('state', state)
+  url.searchParams.append('iss', env.URL)
+  c.header('cache-control', 'no-store')
+  return c.redirect(url.href, 302)
+}
+
+/**
+ * Returns the token `response` of the redeemed device code with row `id`, with the key that its
+ * approval signed as `account` and `key_authorization`. Only the one redemption that succeeds
+ * reaches here, so only it takes the key. The code is spent, so a failed take returns the tokens
+ * alone.
+ */
+async function withDeviceKey(c: Context<Env>, options: withDeviceKey.Options) {
+  const { id, response } = options
+  const key = await Timing.measure(
+    c,
+    Device.take(db, { id }),
+    'Device.take',
+  ).catch((error: unknown) => {
+    Log.error(c, {
+      error,
+      message: 'A device code redemption failed to take the held key.',
+    })
+    return undefined
+  })
+  if (!key) return response
+
+  const body = (await Timing.measure(
+    c,
+    response.json(),
+    'response.json',
+  )) as Record<string, unknown>
+  const headers = new Headers(response.headers)
+  headers.delete('content-length')
+  return new Response(
+    JSON.stringify({
+      ...body,
+      account: key.account,
+      key_authorization: key.keyAuthorization,
+    }),
+    { headers, status: response.status },
+  )
+}
+
+declare namespace withDeviceKey {
+  type Options = {
+    /** The `device_code` row ID of the redeemed code. */
+    id: string
+    /** The issuer's token response. */
+    response: Response
+  }
+}
+
+/**
+ * Returns the key of the device authorization request `form` without its challenge bound, as the
+ * device page stores it and binds the challenge when it reads it.
+ */
+function unbound(form: URLSearchParams) {
+  const query = new URLSearchParams(form)
+  query.delete('challenge')
+  const key = Authorize.fromQuery(query)
+  // The form's key already passed the same parse.
+  return key instanceof ErrorResponse.ResponseError ? undefined : key
+}
+
+/**
+ * Returns the request with Tempo ID's origin as its `resource` when an authorization, a device
+ * authorization, or a token request names none. Better Auth issues a JWT access token only for a `resource`, and every API
+ * verifies the one audience. An authorization request with a key also asks for consent, and names
+ * the key's expiry, as `Authorize.prepare` describes.
+ */
+async function withResource(c: Context<Env>) {
+  const request = c.req.raw
+
+  if (c.req.path === '/oauth2/authorize' && c.req.method === 'GET') {
+    const url = new URL(request.url)
+    if (!url.searchParams.has('resource'))
+      url.searchParams.set('resource', env.URL)
+    url.search = Authorize.prepare(url.searchParams).toString()
+    return new Request(url, request)
+  }
+
+  // The `POST` form of an authorization request carries its parameters in the body, which Better
+  // Auth accepts only as a form. A key in that body gains the same consent and expiry. Better Auth
+  // accepts any media type that contains the form's, in any case, so each one is read here as a
+  // form and forwarded as exactly one.
+  if (
+    c.req.path === '/oauth2/authorize' &&
+    c.req.method === 'POST' &&
+    c.req
+      .header('content-type')
+      ?.split(';')[0]
+      ?.toLowerCase()
+      .includes('application/x-www-form-urlencoded')
+  ) {
+    const form = new URLSearchParams(
+      await Timing.measure(c, c.req.text(), 'request.text'),
+    )
+    if (!form.has('resource')) form.set('resource', env.URL)
+    const headers = new Headers(request.headers)
+    headers.delete('content-length')
+    headers.set('content-type', 'application/x-www-form-urlencoded')
+    return new Request(request.url, {
+      body: Authorize.prepare(form),
+      headers,
+      method: 'POST',
+    })
+  }
+
+  if (c.req.path === '/oauth2/token' && c.req.method === 'POST') {
+    const form = new URLSearchParams(
+      await Timing.measure(c, c.req.text(), 'request.text'),
+    )
+    if (!form.has('resource')) form.set('resource', env.URL)
+    const headers = new Headers(request.headers)
+    headers.delete('content-length')
+    // The client authenticates, never a session. The issuer refuses a cookie without a trusted
+    // `Origin`, such as a device's poll from a browser that holds Tempo ID's session.
+    headers.delete('cookie')
+    return new Request(request.url, { body: form, headers, method: 'POST' })
+  }
+
+  // A device authorization request is a form (RFC 8628 §3.1), whose resource every redemption must
+  // match. A device code binds to the user who approves it, so the request cannot bind one with
+  // `user_id`.
+  if (c.req.path === '/device/code' && c.req.method === 'POST') {
+    const form = new URLSearchParams(
+      await Timing.measure(c, c.req.text(), 'request.text'),
+    )
+    if (!form.has('resource')) form.set('resource', env.URL)
+    if (!form.has('scope')) form.set('scope', Device.scope)
+    form.delete('user_id')
+    // Tempo ID reads its own parameters, which the issuer does not take.
+    for (const name of ['challenge', 'device', 'key_authorization'])
+      form.delete(name)
+    const headers = new Headers(request.headers)
+    headers.delete('content-length')
+    // As for `/oauth2/token`, the client authenticates, and a session's cookie plays no part.
+    headers.delete('cookie')
+    headers.set('content-type', 'application/x-www-form-urlencoded')
+    return new Request(request.url, { body: form, headers, method: 'POST' })
+  }
+
+  return request
+}