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

package/src/api/device.ts

@@ -0,0 +1,874 @@
+/**
+ * The device grant (RFC 8628) for CLIs under `/v1/device`. A CLI requests a code, a signed-in user
+ * approves it on the device page from any browser, and the CLI polls until it receives tokens for
+ * its device app, `tempo-cli` unless it names another. Better Auth issues the codes and the tokens,
+ * in process. A CLI can also request a key authorization, which the device page shows, approval
+ * signs, and the first redemption returns beside the tokens. Approval and denial accept requests
+ * only from Tempo ID's own page, so no app's page decides a code for the user.
+ * @module
+ */
+import { isAPIError } from 'better-auth/api'
+import type { Context } from 'hono'
+import { Hono } from 'hono'
+import { env } from 'void/env'
+import * as z from 'zod'
+import * as Apps from '../internal/Apps.js'
+import * as core_Auth from '../internal/Auth.js'
+import * as Authorize from '../internal/Authorize.js'
+import * as BodyLimit from '../internal/BodyLimit.js'
+import * as Device from '../internal/Device.js'
+import type { Env } from '../internal/Env.js'
+import * as ErrorResponse from '../internal/ErrorResponse.js'
+import * as KeyAuthorization from '../internal/KeyAuthorization.js'
+import * as Log from '../internal/Log.js'
+import * as OpenApi from '../internal/OpenApi.js'
+import * as Passkey from '../internal/Passkey.js'
+import * as RateLimit from '../internal/RateLimit.js'
+import * as TempoAccount from '../internal/TempoAccount.js'
+import * as Timing from '../internal/Timing.js'
+import * as Cors from './lib/Cors.js'
+import { db } from './lib/Database.js'
+import * as DeviceRequest from './lib/DeviceRequest.js'
+import * as KeySigner from './lib/KeySigner.js'
+import * as Session from './lib/Session.js'
+
+namespace schema {
+  export namespace authorize {
+    export const json = z
+      .strictObject({
+        // 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',
+          },
+        ),
+        client_id: z
+          .string()
+          .min(1)
+          .max(255)
+          .optional()
+          .meta({
+            description:
+              'The client ID of the device app that the CLI signs in to, whose realms the sign-in and the device page use. Defaults to `tempo-cli`.',
+            examples: ['tempo-cli'],
+          }),
+        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',
+          })
+          .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: KeyAuthorization.schema.request,
+      })
+      .refine((request) => !request.challenge || request.key_authorization, {
+        message:
+          'A challenge requires `key_authorization`, whose witness binds it',
+        path: ['challenge'],
+      })
+
+    export const response = z.object({
+      device_code: z.string().meta({
+        description:
+          'The secret code that the CLI polls `/v1/device/token` with (RFC 8628 §3.2). The CLI 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 device page: eight consonants in two groups of four.',
+        examples: ['WDJB-MJHT'],
+      }),
+      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 device page with the user code filled in, for a link or QR code.',
+        examples: ['https://id.tempo.xyz/device?code=WDJB-MJHT'],
+      }),
+    })
+  }
+
+  export namespace token {
+    export const json = z.object({
+      client_id: authorize.json.shape.client_id.meta({
+        description:
+          'The client ID that `/v1/device/authorize` named. Defaults to `tempo-cli`.',
+        examples: ['tempo-cli'],
+      }),
+      device_code: z
+        .string()
+        .min(1)
+        .max(128)
+        .meta({
+          description: 'The device code that `/v1/device/authorize` returned.',
+          examples: ['GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS'],
+        }),
+    })
+
+    export const response = Authorize.schema.tokens
+      .extend({
+        account: KeyAuthorization.schema.account.optional(),
+        key_authorization: KeyAuthorization.schema.rpc.optional().meta({
+          description:
+            "The signed key authorization, in the node's RPC format, when the CLI requested a key. Only the first redemption returns it.",
+        }),
+      })
+      .meta({
+        description:
+          'The tokens, with the signed key authorization when the CLI requested a key.',
+        id: 'DeviceTokens',
+      })
+
+    /** Better Auth's token response for the device grant. */
+    export const issued = z.object({
+      access_token: z.string(),
+      expires_in: z.number(),
+      id_token: z.string().optional(),
+      refresh_token: z.string().optional(),
+      token_type: z.string(),
+    })
+  }
+
+  export namespace requests {
+    export const param = z.object({
+      code: z
+        .string()
+        .meta({ description: 'The user code.', examples: ['WDJB-MJHT'] }),
+    })
+
+    export const response = z.object({
+      request: z
+        .object({
+          app: z
+            .object({
+              name: z.string().meta({
+                description: "The app's display name.",
+                examples: ['Tempo CLI'],
+              }),
+            })
+            .optional()
+            .meta({
+              description:
+                'The app that requested the code. Absent when the app has no display name.',
+            }),
+          challenge: z
+            .string()
+            .optional()
+            .meta({
+              description:
+                "The message whose EIP-191 hash is the key's witness, which approval signs. Absent when the CLI sent none.",
+              examples: ['Sign in to app.example.com\nNonce: 7f3a9c2e5b1d4f60'],
+            }),
+          created_at: z.number().meta({
+            description: 'When the CLI requested the code, in Unix seconds.',
+            examples: [1792075800],
+          }),
+          device: z
+            .string()
+            .optional()
+            .meta({
+              description:
+                'The name that the CLI reported, such as its hostname. Absent for a code from `POST /device/code`.',
+              examples: ['ada-macbook'],
+            }),
+          ip: z
+            .string()
+            .optional()
+            .meta({
+              description: "The CLI's IP address. Absent when it is unknown.",
+              examples: ['203.0.113.7'],
+            }),
+          key_authorization: KeyAuthorization.schema.description
+            .extend({
+              account: KeyAuthorization.schema.description.shape.account.meta({
+                description:
+                  'The Tempo Account that approval signs for: the one the request names, else the one the user selected for the app, else the oldest. Absent when the request names none and the accounts cannot be read, or the user holds none.',
+                examples: ['0x9a073914db0d149375ac2b7fbb72c68c0780fb5f'],
+              }),
+              refusal: KeySigner.schema.refusal.optional(),
+            })
+            .optional()
+            .meta({
+              description:
+                'What the key that the CLI requested may do. Absent when the CLI requested no key.',
+            }),
+          location: z
+            .string()
+            .optional()
+            .meta({
+              description:
+                "The CLI's city and country, from its IP address. Absent when they are unknown.",
+              examples: ['Berlin, DE'],
+            }),
+          status: z.enum(['approved', 'denied', 'pending']).meta({
+            description:
+              'Whether the user approved or denied the code. `pending` until the user decides.',
+            examples: ['pending'],
+          }),
+          user_code: z
+            .string()
+            .meta({ description: 'The user code.', examples: ['WDJB-MJHT'] }),
+        })
+        .meta({ description: 'The request that the CLI made with the code.' }),
+    })
+  }
+
+  export namespace approve {
+    export const json = z.object({
+      account: TempoAccount.schema.tempoAccount.shape.address.optional().meta({
+        description:
+          "The Tempo Account that the device 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'],
+      }),
+      code: z
+        .string()
+        .max(32)
+        .meta({ description: 'The user code.', examples: ['WDJB-MJHT'] }),
+      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.",
+        }),
+    })
+
+    export const step = Passkey.schema.step
+
+    export const response = z.union([
+      z
+        .object({
+          status: z.literal('approved').meta({
+            description:
+              'The user approved the code. The CLI receives its tokens, and any signed key, on its next poll.',
+          }),
+        })
+        .meta({ description: 'A stored approval.' }),
+      step,
+    ])
+  }
+
+  export namespace deny {
+    export const json = z.object({ code: approve.json.shape.code })
+
+    export const response = z.object({
+      status: z.literal('denied').meta({
+        description:
+          'The user denied the code. The next poll returns `access_denied`.',
+      }),
+    })
+  }
+}
+
+/**
+ * Records the signed-in user's decision on the live user code `code`, from Tempo ID's own page.
+ * Better Auth first binds the code to the user, so no other user can sign its key or decide it
+ * after. An approval of a request with a key then signs the key and holds it for the code's
+ * redemption, so a refused key approves nothing, and a failed approval releases it. For a passkey-owned account, it returns the
+ * options of the passkey step, and the repeated approval with the assertion signs the key. Returns
+ * `undefined` once the decision is stored, the passkey step, the rate limit's response, or a
+ * refusal.
+ */
+async function decide(
+  c: Context<Env>,
+  options: decide.Options,
+): Promise<
+  | ErrorResponse.Instance<typeof decide.errors>
+  | NonNullable<Awaited<ReturnType<typeof RateLimit.check>>>
+  | { options: Awaited<ReturnType<typeof KeySigner.challenge>> }
+  | undefined
+> {
+  if (Cors.appOrigin(c)) return new ErrorResponse.CrossSiteRequestError()
+
+  const session = await Timing.measure(c, Session.get(c), 'Session.get')
+  if (!session) return new core_Auth.SessionRequiredError()
+
+  // Counted per user, as the approval page's decisions are, since each decision reads the database.
+  const limited = await Timing.measure(
+    c,
+    RateLimit.check(c, {
+      limits: [{ binding: 'AUTHORIZE_LIMIT', key: session.user.id }],
+    }),
+    'RateLimit.check',
+  )
+  if (limited) return limited
+
+  const userCode = Device.normalize(options.code)
+  const found = userCode
+    ? await Timing.measure(c, Device.get(db, { userCode }), 'Device.get')
+    : undefined
+  // A code that another user holds is unknown to this one, as `DeviceRequest.read` returns it.
+  if (!userCode || !found || (found.userId && found.userId !== session.user.id))
+    return new Device.UnknownCodeError()
+  // A decided code refuses before Better Auth binds it, and before any passkey step.
+  if (found.status !== 'pending') return new Device.AlreadyDecidedError()
+
+  // Better Auth binds the code to this user first, in one conditional update, so of concurrent
+  // decisions by several users only the bound user's signs a key or decides.
+  const headers = c.req.raw.headers
+  const bound = await (async () => {
+    if (found.userId) return found
+    try {
+      await Timing.measure(
+        c,
+        c.var.auth.api.deviceVerify({
+          headers,
+          query: { user_code: userCode },
+        }),
+        'auth.deviceVerify',
+      )
+    } catch (error) {
+      if (!isAPIError(error)) throw error
+    }
+    return await Timing.measure(c, Device.get(db, { userCode }), 'Device.get')
+  })()
+  // A code that another user bound in the meantime stays unknown to this one.
+  if (!bound || bound.userId !== session.user.id)
+    return new Device.UnknownCodeError()
+  if (bound.status !== 'pending') return new Device.AlreadyDecidedError()
+
+  // An approval of a request with a key signs the key and holds it first, so a refused key
+  // approves nothing.
+  const held = await (async () => {
+    if (options.decision !== 'approve' || !bound.key) return undefined
+    const signed = await Timing.measure(
+      c,
+      DeviceRequest.sign(c, {
+        account: options.account,
+        assertion: options.assertion,
+        request: bound,
+        session,
+      }),
+      'DeviceRequest.sign',
+    )
+    if (signed instanceof ErrorResponse.ResponseError) return signed
+    // A passkey signs only in this browser, so the page signs the digest and repeats the approval.
+    if (signed.options) return { options: signed.options }
+    const key = {
+      account: signed.account,
+      keyAuthorization: signed.keyAuthorization,
+    }
+    const stored = await Timing.measure(
+      c,
+      Device.hold(db, { id: bound.id, key, userId: session.user.id }),
+      'Device.hold',
+    )
+    // Another decision, the key of a concurrent approval, or the code's expiry came first.
+    if (!stored) return await refusal()
+    return { key }
+  })()
+  if (held instanceof ErrorResponse.ResponseError) return held
+  if (held && 'options' in held) return { options: held.options }
+
+  try {
+    await Timing.measure(
+      c,
+      options.decision === 'approve'
+        ? c.var.auth.api.deviceApprove({ body: { userCode }, headers })
+        : c.var.auth.api.deviceDeny({ body: { userCode }, headers }),
+      options.decision === 'approve' ? 'auth.deviceApprove' : 'auth.deviceDeny',
+    )
+    return undefined
+  } catch (error) {
+    // A failed approval releases its key while the code is pending, so the user can approve again.
+    if (held)
+      await Timing.measure(
+        c,
+        Device.release(db, { id: bound.id, key: held.key }),
+        'Device.release',
+      )
+    if (!isAPIError(error)) throw error
+    // Another decision, by this user, or the code's expiry, came between the read and Better
+    // Auth's own checks.
+    return await refusal()
+  }
+
+  /** Returns the refusal of a code that changed after the read: unknown when it expired. */
+  async function refusal() {
+    const current = await Timing.measure(
+      c,
+      Device.get(db, { userCode: userCode! }),
+      'Device.get',
+    )
+    if (!current) return new Device.UnknownCodeError()
+    return new Device.AlreadyDecidedError()
+  }
+}
+
+declare namespace decide {
+  type Options = {
+    /** The account that the device page showed for the request's key, if any. */
+    account?: `0x${string}` | undefined
+    /** The passkey's assertion over the options of the passkey step, if any. */
+    assertion?: Passkey.Assertion | undefined
+    /** The user code, as the user typed it. */
+    code: string
+    /** Whether the user approves or denies the code. */
+    decision: 'approve' | 'deny'
+  }
+}
+
+namespace decide {
+  /** The refusals `decide` returns. Its return type admits no other. */
+  export const errors = [
+    ...DeviceRequest.sign.errors,
+    core_Auth.SessionRequiredError,
+    Device.AlreadyDecidedError,
+    Device.UnknownCodeError,
+    ErrorResponse.CrossSiteRequestError,
+  ] as const
+}
+
+/**
+ * Redeems the device code `deviceCode` for tokens at Better Auth's token endpoint, in process, as
+ * the app with `clientId`. Returns the tokens, or the RFC 8628 refusal of a code that is pending,
+ * denied, polled too fast, expired, unknown, already redeemed, or for another app.
+ */
+async function poll(
+  c: Context<Env>,
+  options: poll.Options,
+): Promise<
+  | ErrorResponse.Instance<typeof poll.errors>
+  | z.output<typeof schema.token.issued>
+> {
+  const response = await Timing.measure(
+    c,
+    c.var.auth.handler(
+      new Request(new URL('/oauth2/token', env.URL), {
+        body: new URLSearchParams({
+          client_id: options.clientId,
+          device_code: options.deviceCode,
+          grant_type: Apps.deviceGrant,
+          resource: env.URL,
+        }),
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        method: 'POST',
+      }),
+    ),
+    'auth.handler',
+  )
+  const body: unknown = await Timing.measure(
+    c,
+    response.json(),
+    'response.json',
+  )
+  if (response.ok) return schema.token.issued.parse(body)
+
+  const error = z.object({ error: z.string() }).safeParse(body).data?.error
+  if (error === 'authorization_pending')
+    return new Device.ApprovalPendingError()
+  if (error === 'slow_down') return new Device.PollingTooFastError()
+  if (error === 'access_denied') return new Device.RequestDeniedError()
+  // Better Auth refuses an unknown or redeemed code with `invalid_grant`, and an expired one with
+  // `expired_token`.
+  if (error === 'expired_token' || error === 'invalid_grant')
+    return new Device.DeviceCodeExpiredError()
+  throw new Error(
+    `The token endpoint refused a device code with ${error ?? response.status}.`,
+  )
+}
+
+declare namespace poll {
+  type Options = {
+    /** The client ID of the device app that requested the code. */
+    clientId: string
+    /** The device code that the CLI holds. */
+    deviceCode: string
+  }
+}
+
+namespace poll {
+  /** The refusals `poll` returns, each an RFC 8628 error. */
+  export const errors = [
+    Device.ApprovalPendingError,
+    Device.DeviceCodeExpiredError,
+    Device.PollingTooFastError,
+    Device.RequestDeniedError,
+  ] as const
+}
+
+/** The device grant API for CLIs, and the decisions of the device page. */
+export const device = new Hono<Env>()
+  .post(
+    '/v1/device/authorize',
+    OpenApi.describeRoute({
+      description:
+        "Starts the device grant (RFC 8628) for a CLI, as the device app that `client_id` names, or `tempo-cli`. The user approves the user code on the device page, and the CLI polls `/v1/device/token`. A request with `key_authorization` asks for a key, which the device page shows and approval signs. The key follows the rules of the redirect's approval page, without the headless ceiling, and a `challenge` requires the app's `tempo-id:sign` scope.",
+      responses: OpenApi.responses({
+        errors: [
+          ...BodyLimit.errors,
+          ...KeyAuthorization.check.errors,
+          ...KeyAuthorization.checkChallenge.errors,
+          ...OpenApi.validate.errors,
+          ...RateLimit.check.errors,
+          Authorize.RejectedError,
+          ErrorResponse.CrossSiteRequestError,
+        ],
+        success: {
+          description: 'The device code.',
+          schema: schema.authorize.response,
+        },
+      }),
+      tags: ['Device grant'],
+    }),
+    OpenApi.validate('json', schema.authorize.json),
+    async (c) => {
+      // Any CLI can name any device app, so the IP address is the only useful key.
+      const limited = await Timing.measure(
+        c,
+        RateLimit.check(c, {
+          limits: [{ binding: 'DEVICE_LIMIT', key: RateLimit.ip(c) }],
+        }),
+        'RateLimit.check',
+      )
+      if (limited) return limited
+
+      const {
+        challenge,
+        client_id = Device.clientId,
+        device,
+        key_authorization,
+      } = c.req.valid('json')
+      const app = await Timing.measure(
+        c,
+        Apps.get(db, { clientId: client_id, enabled: true }).catch(
+          (error: unknown) => {
+            if (error instanceof Apps.NotFoundError) return undefined
+            throw error
+          },
+        ),
+        'Apps.get',
+      )
+      // A device app with a secret, which an import can hold, cannot redeem at the poll, which sends
+      // none, so it is refused as no device app.
+      if (!app?.device || app.secret)
+        return ErrorResponse.json(
+          c,
+          new Authorize.RejectedError({
+            description: `Device grant refused: \`client_id\` ${client_id} names no enabled public device app. Send the client ID of a device app, or leave out \`client_id\`.`,
+          }),
+        )
+
+      // The device page shows the key, so the request is refused here for a key that approval
+      // would refuse, before the CLI shows a code.
+      if (key_authorization) {
+        const key = KeyAuthorization.bind(key_authorization, { challenge })
+        const refused =
+          KeyAuthorization.check(key) ??
+          KeyAuthorization.checkChallenge({ app, clientId: client_id, key })
+        if (refused) return ErrorResponse.json(c, refused)
+      }
+
+      const code = await Timing.measure(
+        c,
+        c.var.auth.api.deviceCode({
+          body: {
+            client_id,
+            // Every redemption must match the code's resource, which `/oauth2/token` defaults to.
+            resource: env.URL,
+            scope: Device.scope,
+          },
+        }),
+        'auth.deviceCode',
+      )
+      await Timing.measure(
+        c,
+        DeviceRequest.create(c, {
+          challenge,
+          device,
+          deviceCode: code.device_code,
+          expiresIn: code.expires_in,
+          key: key_authorization,
+        }),
+        'DeviceRequest.create',
+      )
+
+      const userCode = Device.format(code.user_code)
+      const verification = new URL(Device.page, env.URL)
+      c.header('cache-control', 'no-store')
+      return c.json(
+        {
+          device_code: code.device_code,
+          expires_in: code.expires_in,
+          interval: code.interval,
+          user_code: userCode,
+          verification_uri: verification.href,
+          verification_uri_complete: `${verification.href}?${new URLSearchParams({ code: userCode })}`,
+        },
+        200,
+      )
+    },
+  )
+  .post(
+    '/v1/device/token',
+    OpenApi.describeRoute({
+      description:
+        "Polls for the device grant's tokens (RFC 8628 §3.4). The tokens of an approved code, and the key authorization that approval signed, are returned once.",
+      responses: OpenApi.responses({
+        errors: [
+          ...BodyLimit.errors,
+          ...OpenApi.validate.errors,
+          ...RateLimit.check.errors,
+          ...poll.errors,
+          ErrorResponse.CrossSiteRequestError,
+        ],
+        success: {
+          description: 'The tokens.',
+          schema: schema.token.response,
+        },
+      }),
+      tags: ['Device grant'],
+    }),
+    OpenApi.validate('json', schema.token.json),
+    async (c) => {
+      // The poll redeems at `/oauth2/token` in process, so it counts as that route counts its requests.
+      const limited = await Timing.measure(
+        c,
+        RateLimit.check(c, {
+          limits: [{ binding: 'TOKEN_LIMIT', key: RateLimit.ip(c) }],
+        }),
+        'RateLimit.check',
+      )
+      if (limited) return limited
+
+      const deviceCode = c.req.valid('json').device_code
+      // The redemption deletes the code's row, so its ID, which names the held key, is read first.
+      const id = await Timing.measure(
+        c,
+        Device.id(db, { deviceCode }),
+        'Device.id',
+      )
+      const result = await Timing.measure(
+        c,
+        poll(c, {
+          clientId: c.req.valid('json').client_id ?? Device.clientId,
+          deviceCode,
+        }),
+        'device.poll',
+      )
+      c.header('cache-control', 'no-store')
+      if (result instanceof ErrorResponse.ResponseError)
+        return ErrorResponse.json(c, result)
+
+      // Only the one poll that redeems the code reaches here, so only it takes the key. The code is
+      // spent, so a failed take still returns the tokens, without the key.
+      const key = id
+        ? await Timing.measure(c, Device.take(db, { id }), 'Device.take').catch(
+            (error: unknown) => {
+              Log.error(c, {
+                error,
+                message: 'The device token poll failed to take the held key.',
+              })
+              return undefined
+            },
+          )
+        : undefined
+      const { access_token, expires_in, id_token, refresh_token, token_type } =
+        result
+      return c.json(
+        {
+          access_token,
+          ...(key
+            ? { account: key.account, key_authorization: key.keyAuthorization }
+            : {}),
+          expires_in,
+          ...(id_token ? { id_token } : {}),
+          ...(refresh_token ? { refresh_token } : {}),
+          token_type,
+        },
+        200,
+      )
+    },
+  )
+  .get(
+    '/v1/device/requests/:code',
+    OpenApi.describeRoute({
+      description:
+        "Reads a device code's request for the device page, by its user code. The first signed-in user to read a pending code binds it, so no other user decides it. A pending request's key carries the account that approval signs for, and why approval cannot sign it, if it cannot. That lookup counts against the user's `ACCOUNT_LIMIT`, as `GET /v1/account` does. Creates no account.",
+      responses: OpenApi.responses({
+        errors: [
+          ...OpenApi.validate.errors,
+          ...DeviceRequest.read.errors,
+          ...RateLimit.check.errors,
+          core_Auth.SessionRequiredError,
+          ErrorResponse.CrossSiteRequestError,
+        ],
+        success: {
+          description: 'What the CLI requested.',
+          schema: schema.requests.response,
+        },
+      }),
+      security: [{ sessionCookie: [] }],
+      tags: ['Device grant'],
+    }),
+    OpenApi.validate('param', schema.requests.param),
+    async (c) => {
+      // The session cookie is `Lax`, so a top-level navigation from another site carries it. The read
+      // binds a pending code and spends the user's limits, so no other site's page starts one.
+      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())
+
+      // A user code holds about 34 bits, so each user's lookups count, which keeps a guess of a live
+      // code out of reach (RFC 8628 §5.1). They count apart from the user's authorizations, so a
+      // page that sends the user's lookups spends none of that quota.
+      const limited = await Timing.measure(
+        c,
+        RateLimit.check(c, {
+          limits: [
+            { binding: 'AUTHORIZE_LIMIT', key: `${session.user.id}:device` },
+          ],
+        }),
+        'RateLimit.check',
+      )
+      if (limited) return limited
+
+      const found = await Timing.measure(
+        c,
+        DeviceRequest.read(c, {
+          code: c.req.valid('param').code,
+          userId: session.user.id,
+        }),
+        'DeviceRequest.read',
+      )
+      c.header('cache-control', 'private, no-store')
+      if (found instanceof ErrorResponse.ResponseError)
+        return ErrorResponse.json(c, found)
+
+      // The key's account resolves in the realms of the app that requested the code.
+      const { clientId, request } = found
+      const { key_authorization, ...rest } = request
+      if (!key_authorization || request.status !== 'pending')
+        return c.json({ request }, 200)
+      const preview = await Timing.measure(
+        c,
+        KeySigner.preview(c, {
+          account: key_authorization.account,
+          clientId,
+          sessionId: session.session.id,
+          userId: session.user.id,
+        }),
+        'KeySigner.preview',
+      )
+      return c.json(
+        {
+          request: {
+            ...rest,
+            key_authorization: {
+              ...key_authorization,
+              ...(preview.account ? { account: preview.account } : {}),
+              ...(preview.refusal ? { refusal: preview.refusal } : {}),
+            },
+          },
+        },
+        200,
+      )
+    },
+  )
+  .post(
+    '/v1/device/approve',
+    OpenApi.describeRoute({
+      description:
+        "Approves a device code for the signed-in user. Only Tempo ID's device page may call it. The CLI receives its tokens on its next poll. An approval of a request with a key authorization signs the key as the account's owner, and the poll returns it beside the tokens. 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: [
+          ...BodyLimit.errors,
+          ...OpenApi.validate.errors,
+          ...RateLimit.check.errors,
+          ...decide.errors,
+        ],
+        success: {
+          description: 'The code is approved, or the passkey step.',
+          schema: schema.approve.response,
+        },
+      }),
+      security: [{ sessionCookie: [] }],
+      tags: ['Device grant'],
+    }),
+    OpenApi.validate('json', schema.approve.json),
+    async (c) => {
+      const { account, code, passkey } = c.req.valid('json')
+      const result = await Timing.measure(
+        c,
+        decide(c, {
+          account,
+          assertion: passkey?.assertion,
+          code,
+          decision: 'approve',
+        }),
+        'device.decide',
+      )
+      if (result instanceof Response) return result
+      if (result instanceof ErrorResponse.ResponseError)
+        return ErrorResponse.json(c, result)
+      if (result) {
+        c.header('cache-control', 'private, no-store')
+        return c.json(
+          schema.approve.step.parse({
+            step: { options: result.options, type: 'passkey' },
+          }),
+          200,
+        )
+      }
+      return c.json({ status: 'approved' as const }, 200)
+    },
+  )
+  .post(
+    '/v1/device/deny',
+    OpenApi.describeRoute({
+      description:
+        "Denies a device code for the signed-in user. Only Tempo ID's device page may call it. The CLI's next poll returns `access_denied`.",
+      responses: OpenApi.responses({
+        errors: [
+          ...BodyLimit.errors,
+          ...OpenApi.validate.errors,
+          ...RateLimit.check.errors,
+          ...decide.errors,
+        ],
+        success: {
+          description: 'The code is denied.',
+          schema: schema.deny.response,
+        },
+      }),
+      security: [{ sessionCookie: [] }],
+      tags: ['Device grant'],
+    }),
+    OpenApi.validate('json', schema.deny.json),
+    async (c) => {
+      const result = await Timing.measure(
+        c,
+        decide(c, { code: c.req.valid('json').code, decision: 'deny' }),
+        'device.decide',
+      )
+      if (result instanceof Response) return result
+      if (result instanceof ErrorResponse.ResponseError)
+        return ErrorResponse.json(c, result)
+      return c.json({ status: 'denied' as const }, 200)
+    },
+  )