@tempoxyz/id 0.0.0-stage → 0.0.0

package/src/internal/ErrorResponse.ts

@@ -0,0 +1,854 @@
+/**
+ * OAuth error responses ([RFC 6749 §5.2](https://www.rfc-editor.org/rfc/rfc6749#section-5.2)):
+ * `error`, `error_description`, and `error_uri`, with extension members apps can branch on. OAuth
+ * clients ignore members they do not recognize. Every refusal names a `reason`, and each reason
+ * has exactly one `error` and one HTTP status, so a reason fully determines the response.
+ * @module
+ */
+import type { Context, TypedResponse } from 'hono'
+import { HTTPException } from 'hono/http-exception'
+import type { ContentfulStatusCode } from 'hono/utils/http-status'
+import type { JSONParsed } from 'hono/utils/types'
+import * as z from 'zod'
+import * as Log from './Log.js'
+
+/** The page that explains each `reason`, for `error_uri`. */
+const docs = 'https://github.com/tempoxyz/auth/blob/main/docs/errors.md'
+
+/**
+ * Every refusal Tempo ID returns, by `reason`: its OAuth `error` code, its HTTP status, and what it
+ * means. `docs/errors.md` explains each one.
+ */
+export const reasons = {
+  already_decided: {
+    description: 'The user code was already approved or denied.',
+    error: 'invalid_request',
+    status: 409,
+  },
+  approval_pending: {
+    description: 'The user has not decided the device code yet.',
+    error: 'authorization_pending',
+    status: 400,
+  },
+  authorization_expired: {
+    description:
+      "The app's authorization request that sign-in or the approval page continues is forged or expired.",
+    error: 'invalid_request',
+    status: 400,
+  },
+  body_too_large: {
+    description: 'The request body exceeds 64 KiB.',
+    error: 'invalid_request',
+    status: 413,
+  },
+  challenge_not_permitted: {
+    description:
+      'A request carries a challenge, and its app lacks the `tempo-id:sign` scope.',
+    error: 'unauthorized_client',
+    status: 403,
+  },
+  cross_site_request: {
+    description: 'A form or body-less write came from another site.',
+    error: 'access_denied',
+    status: 403,
+  },
+  device_code_expired: {
+    description: 'The device code is unknown, expired, or already redeemed.',
+    error: 'expired_token',
+    status: 400,
+  },
+  duplicate_limit: {
+    description: 'Two limits name the same token.',
+    error: 'invalid_authorization_details',
+    status: 400,
+  },
+  duplicate_scope: {
+    description: 'Two scopes name the same call on one token.',
+    error: 'invalid_authorization_details',
+    status: 400,
+  },
+  empty_limits: {
+    description: '`limits` is an empty list.',
+    error: 'invalid_authorization_details',
+    status: 400,
+  },
+  empty_scopes: {
+    description: '`scopes` is an empty list.',
+    error: 'invalid_authorization_details',
+    status: 400,
+  },
+  expiry_exceeds_maximum: {
+    description: 'A headless key lasts longer than a year.',
+    error: 'invalid_authorization_details',
+    status: 403,
+  },
+  expiry_passed: {
+    description: 'The key expiry has passed.',
+    error: 'invalid_authorization_details',
+    status: 400,
+  },
+  foreign_account: {
+    description:
+      "The request names a Tempo Account that is not the user's in the app's realms.",
+    error: 'access_denied',
+    status: 403,
+  },
+  invalid_chain: {
+    description: 'The key chain ID is 0.',
+    error: 'invalid_authorization_details',
+    status: 400,
+  },
+  invalid_code: {
+    description: 'The emailed code is wrong or expired.',
+    error: 'invalid_grant',
+    status: 401,
+  },
+  invalid_expiry: {
+    description: 'The key expiry is 0, which never expires.',
+    error: 'invalid_authorization_details',
+    status: 400,
+  },
+  invalid_field: {
+    description: 'A field is missing or malformed.',
+    error: 'invalid_request',
+    status: 400,
+  },
+  invalid_id_token_hint: {
+    description:
+      'The ID token hint is not an ID token that Tempo ID signed for the app.',
+    error: 'invalid_request',
+    status: 400,
+  },
+  invalid_origin: {
+    description:
+      'A headless request came from an origin its redirect URI does not allow.',
+    error: 'unauthorized_client',
+    status: 403,
+  },
+  invalid_period: {
+    description: "A limit's `period` is not a whole number of seconds.",
+    error: 'invalid_authorization_details',
+    status: 400,
+  },
+  invalid_public_key: {
+    description: 'The key public key is not a valid point.',
+    error: 'invalid_authorization_details',
+    status: 400,
+  },
+  invalid_recipients: {
+    description:
+      "A scope's `recipients` names the zero address, or one address twice.",
+    error: 'invalid_authorization_details',
+    status: 400,
+  },
+  limit_exceeds_maximum: {
+    description: 'A headless key limit exceeds the token’s ceiling.',
+    error: 'invalid_authorization_details',
+    status: 403,
+  },
+  logout_not_permitted: {
+    description:
+      'The app that the ID token hint names may not end the session at the end-session endpoint.',
+    error: 'unauthorized_client',
+    status: 403,
+  },
+  malformed_body: {
+    description: 'The request body is not valid JSON.',
+    error: 'invalid_request',
+    status: 400,
+  },
+  missing_key: {
+    description: 'The key authorization names no key.',
+    error: 'invalid_authorization_details',
+    status: 400,
+  },
+  missing_recipients: {
+    description: 'An `approve` scope names no spenders.',
+    error: 'invalid_authorization_details',
+    status: 400,
+  },
+  passkey_link_expired: {
+    description:
+      "The email step's link to a wallet.tempo passkey expired, or the browser holds no link for it.",
+    error: 'invalid_request',
+    status: 400,
+  },
+  passkey_not_permitted: {
+    description:
+      'A passkey sign-in names an app, or reaches a realm, that holds no passkeys for Tempo ID.',
+    error: 'unauthorized_client',
+    status: 403,
+  },
+  polling_too_fast: {
+    description: 'The device polled before its interval passed.',
+    error: 'slow_down',
+    status: 400,
+  },
+  post_logout_redirect_not_permitted: {
+    description:
+      'The post-logout redirect URI is not one of the post-logout redirect URIs the app registered.',
+    error: 'invalid_request',
+    status: 400,
+  },
+  rate_limited: {
+    description:
+      'Tempo ID, or a service it depends on, is rate limiting the request.',
+    error: 'temporarily_unavailable',
+    status: 429,
+  },
+  rejected: {
+    description: 'The issuer refused the authorization request.',
+    error: 'invalid_request',
+    status: 400,
+  },
+  request_denied: {
+    description: 'The user denied the device code.',
+    error: 'access_denied',
+    status: 400,
+  },
+  return_to_not_permitted: {
+    description:
+      "The page that a provider sign-in returns to is on neither Tempo ID's origin nor the app's.",
+    error: 'invalid_request',
+    status: 400,
+  },
+  scope_without_limit: {
+    description: 'A scope calls a token no limit names.',
+    error: 'invalid_authorization_details',
+    status: 400,
+  },
+  session_changed: {
+    description:
+      'The signed-in session differs from the one that the approval page showed.',
+    error: 'invalid_request',
+    status: 409,
+  },
+  session_required: {
+    description: 'The request needs a signed-in session.',
+    error: 'login_required',
+    status: 401,
+  },
+  unexpected: {
+    description: 'An unexpected failure.',
+    error: 'server_error',
+    status: 500,
+  },
+  unknown_code: {
+    description: 'The user code is wrong or expired.',
+    error: 'invalid_request',
+    status: 404,
+  },
+  unknown_endpoint: {
+    description: 'No API endpoint matches this method and path.',
+    error: 'invalid_request',
+    status: 404,
+  },
+  unknown_provider: {
+    description: 'The sign-in names a provider that Tempo ID does not offer.',
+    error: 'invalid_request',
+    status: 404,
+  },
+  unsupported_call: {
+    description: 'A scope calls a function a key may not call.',
+    error: 'invalid_authorization_details',
+    status: 400,
+  },
+  unsupported_token: {
+    description: 'A limit names a token that is not supported on the chain.',
+    error: 'invalid_authorization_details',
+    status: 400,
+  },
+  upstream_unavailable: {
+    description: 'A service Tempo ID depends on failed or did not respond.',
+    error: 'temporarily_unavailable',
+    status: 503,
+  },
+  webauthn_rejected: {
+    description:
+      'A passkey ceremony failed: its challenge is unknown, spent, or expired, or its response does not verify.',
+    error: 'access_denied',
+    status: 401,
+  },
+  webauthn_required: {
+    description:
+      'A request without a page names a Tempo Account whose passkey signs only on a Tempo ID page.',
+    error: 'interaction_required',
+    status: 403,
+  },
+} as const satisfies Record<
+  string,
+  { description: string; error: string; status: ContentfulStatusCode }
+>
+
+/** Each refusal's stable name. */
+export type Reason = keyof typeof reasons
+
+/** The OAuth error code of a refusal. */
+export type Code = (typeof reasons)[Reason]['error']
+
+/** The HTTP status of `reason`. */
+export type Status<reason extends Reason = Reason> =
+  (typeof reasons)[reason]['status']
+
+/** An OAuth error response for `reason`, as its schema reads it. */
+export type ErrorResponse<reason extends Reason = Reason> =
+  reason extends Reason
+    ? Omit<z.output<typeof schema.base>, 'error' | 'reason'> & {
+        /** The OAuth error code, which `reason` determines. */
+        error: (typeof reasons)[reason]['error']
+        /** A stable name for the refusal, for apps to branch on. */
+        reason: reason
+      }
+    : never
+
+/** The JSON response `json` returns for `reason`. One per reason, so each keeps its status. */
+export type Json<reason extends Reason> = reason extends Reason
+  ? Response &
+      TypedResponse<JSONParsed<ErrorResponse<reason>>, Status<reason>, 'json'>
+  : never
+
+/** A refusal's class, which `fn.errors` lists. Its static `reason` names the refusal. */
+export type Class = (abstract new (...args: never[]) => ResponseError) & {
+  /** The reason of every refusal the class constructs. */
+  readonly reason: Reason
+}
+
+/** An instance of one of the classes in `errors`: the return type of a function returning refusals. */
+export type Instance<errors extends readonly Class[]> = InstanceType<
+  errors[number]
+>
+
+/**
+ * A refusal, which a function returns or throws. `json` responds with a returned one, and `handle`
+ * with a thrown one. Each refusal is a subclass that {@link define} makes, so its reason is written
+ * once.
+ */
+export class ResponseError<
+  reason extends Reason = Reason,
+> extends HTTPException {
+  override readonly name: string = 'ErrorResponse.ResponseError'
+  /** The error response the refusal sends. */
+  readonly response: ErrorResponse<reason>
+
+  constructor(response: ErrorResponse<reason>) {
+    const status = reasons[response.reason].status
+    super(status, { res: Response.json(response, { status }) })
+    this.response = response
+  }
+}
+
+/**
+ * Returns the base class of `reason`'s refusals, whose static `reason` is `reason`. The module that
+ * returns or throws a refusal declares it as a subclass, such as
+ * `class InvalidCodeError extends ErrorResponse.define('invalid_code') {}`, and lists the class in
+ * its `fn.errors`.
+ */
+export function define<const reason extends Reason>(reason: reason) {
+  return class extends ResponseError<reason> {
+    static readonly reason = reason
+
+    constructor(options: define.Options) {
+      super(from({ ...options, reason }))
+    }
+  }
+}
+
+export declare namespace define {
+  type Options = Omit<from.Value<Reason>, 'reason'>
+}
+
+/**
+ * A form or body-less write came from another site, which `csrf()` refuses, or a cross-site read of
+ * `GET /v1/account`.
+ */
+export class CrossSiteRequestError extends define('cross_site_request') {
+  override readonly name = 'ErrorResponse.CrossSiteRequestError'
+
+  constructor() {
+    super({
+      error_description:
+        'Cross-site request refused. Send JSON from an allowed origin.',
+    })
+  }
+}
+
+/** The body is not valid JSON, which Hono's body validator refuses. */
+export class MalformedBodyError extends define('malformed_body') {
+  override readonly name = 'ErrorResponse.MalformedBodyError'
+
+  constructor() {
+    super({
+      error_description:
+        'Malformed request body. Send a JSON object with `Content-Type: application/json`.',
+    })
+  }
+}
+
+/** A service Tempo ID depends on, such as Privy, is rate limiting it. */
+export class RateLimitedError extends define('rate_limited') {
+  override readonly name = 'ErrorResponse.RateLimitedError'
+  /** The wait in seconds that the service requested, which `handle` sends as `Retry-After`. */
+  readonly retryAfter: number | undefined
+
+  constructor(options: RateLimitedError.Options = {}) {
+    const { retryAfter } = options
+    super({
+      error_description: `Rate limited by an upstream service. Retry ${retryAfter ? `after ${retryAfter} seconds` : 'later'}.`,
+      ...(retryAfter ? { meta: { retryAfter } } : {}),
+    })
+    this.retryAfter = retryAfter
+  }
+}
+
+export declare namespace RateLimitedError {
+  type Options = {
+    /** The wait in seconds that the service requested. */
+    retryAfter?: number | undefined
+  }
+}
+
+/** An unexpected failure, which `handle` logs. */
+export class UnexpectedError extends define('unexpected') {
+  override readonly name = 'ErrorResponse.UnexpectedError'
+
+  constructor() {
+    super({ error_description: 'Unexpected error. Try again.' })
+  }
+}
+
+/** No API route matches the method and path. */
+export class UnknownEndpointError extends define('unknown_endpoint') {
+  override readonly name = 'ErrorResponse.UnknownEndpointError'
+
+  constructor() {
+    // The path is the caller's, and may carry a misplaced credential, so it is not echoed.
+    super({
+      error_description:
+        'Unknown endpoint. Check the method and path against the API reference at /openapi.json.',
+    })
+  }
+}
+
+/** A service Tempo ID depends on, such as Privy, failed or did not respond. */
+export class UpstreamUnavailableError extends define('upstream_unavailable') {
+  override readonly name = 'ErrorResponse.UpstreamUnavailableError'
+
+  constructor() {
+    super({
+      error_description: 'An upstream service is unavailable. Retry later.',
+    })
+  }
+}
+
+/** Zod schemas for every error response, which the OpenAPI document reads. */
+export namespace schema {
+  /** The members every error response has. */
+  export const base = z.object({
+    error: z.string().meta({
+      description:
+        'The OAuth error code (RFC 6749, OIDC Core, RFC 8628, RFC 9396), which `reason` determines.',
+    }),
+    error_description: z.string().meta({
+      description:
+        'What went wrong and how to fix it, for people. Its wording may change.',
+    }),
+    error_uri: z.url().meta({
+      description: 'The errors page, at the refusal’s `reason`.',
+    }),
+    field: z.string().optional().meta({
+      description: 'Extension: the request field at fault, as a dotted path.',
+    }),
+    meta: z
+      .record(z.string(), z.union([z.number(), z.string()]))
+      .readonly()
+      .optional()
+      .meta({
+        description:
+          'Extension: the values the refusal compared. Base units are decimal strings.',
+      }),
+    reason: z.string().meta({
+      description: 'Extension: a stable name for the refusal, to branch on.',
+    }),
+    request_id: z.string().optional().meta({
+      description:
+        'Extension: the request ID, which `X-Request-Id` also carries. The Worker adds it to every error response.',
+    }),
+  })
+
+  /**
+   * Each reason's example `error_description`, and its `field` when the refusal names one. The
+   * OpenAPI document shows them, so they hold no real account, app, or origin.
+   */
+  const examples: Record<
+    Reason,
+    { error_description: string; field?: string | undefined }
+  > = {
+    already_decided: {
+      error_description: 'Code already approved or denied.',
+      field: 'code',
+    },
+    approval_pending: {
+      error_description:
+        'Approval pending. Poll again after `interval` seconds.',
+    },
+    authorization_expired: {
+      error_description:
+        'Expired authorization request: the request from the app is no longer valid. Return to the app, and start again.',
+      field: 'oauth_query',
+    },
+    body_too_large: {
+      error_description:
+        'Invalid request body: exceeds the 65536-byte maximum. Send a body of 65536 bytes or fewer.',
+    },
+    challenge_not_permitted: {
+      error_description:
+        'Challenge not permitted: the app lacks the `tempo-id:sign` scope. Remove `challenge`, or grant the app the scope.',
+      field: 'challenge',
+    },
+    cross_site_request: {
+      error_description:
+        'Cross-site request refused. Send JSON from an allowed origin.',
+    },
+    device_code_expired: {
+      error_description: 'Device code expired. Request a new code.',
+    },
+    duplicate_limit: {
+      error_description:
+        'Duplicate limit for 0x20c0000000000000000000000000000000000001. Limit each token once.',
+      field: 'key_authorization.limits.1.token',
+    },
+    duplicate_scope: {
+      error_description:
+        'Duplicate scope for 0xa9059cbb on OUSD. Name each call on a token once.',
+      field: 'key_authorization.scopes.1.selector',
+    },
+    empty_limits: {
+      error_description:
+        'Empty `limits`. Name at least one token, or omit `limits`.',
+      field: 'key_authorization.limits',
+    },
+    empty_scopes: {
+      error_description:
+        'Empty `scopes`. Name at least one call, or omit `scopes`.',
+      field: 'key_authorization.scopes',
+    },
+    expiry_exceeds_maximum: {
+      error_description:
+        'Invalid `expiry`: Sat, 01 Jan 2028 00:00:00 GMT exceeds the one-year maximum. Use an earlier expiry, or authorize through a redirect or device grant.',
+      field: 'key_authorization.expiry',
+    },
+    expiry_passed: {
+      error_description:
+        'Invalid `expiry`: Wed, 01 Jan 2025 00:00:00 GMT has passed. Use a future Unix time.',
+      field: 'key_authorization.expiry',
+    },
+    foreign_account: {
+      error_description:
+        "Access denied to Tempo Account 0x8C3b5d0e2A4f6B1c9D7e3F5a0B2c4D6e8F1a3B5c. Name one of the user's accounts in the app's realms.",
+      field: 'account',
+    },
+    invalid_chain: {
+      error_description:
+        'Invalid `chainId`: 0. Use a Tempo chain ID, such as 4217.',
+      field: 'key_authorization.chainId',
+    },
+    invalid_code: {
+      error_description: 'Invalid or expired code. Request a new one.',
+      field: 'code',
+    },
+    invalid_expiry: {
+      error_description:
+        'Invalid `expiry`: 0 never expires. Use a future Unix time.',
+      field: 'key_authorization.expiry',
+    },
+    invalid_field: {
+      error_description: 'Invalid request. `email`: Invalid email address.',
+      field: 'email',
+    },
+    invalid_id_token_hint: {
+      error_description:
+        'Invalid id_token_hint: it is not an ID token that this issuer signed for the app. Send the ID token that the app received at sign-in.',
+      field: 'id_token_hint',
+    },
+    invalid_origin: {
+      error_description:
+        'Invalid `Origin`: https://other.example.com. Requests for this redirect URI must come from https://app.example.com.',
+      field: 'Origin',
+    },
+    invalid_period: {
+      error_description:
+        'Invalid `period` on the OUSD limit: 1.5. Use a whole number of seconds, or 0 for a one-time limit.',
+      field: 'key_authorization.limits.0.period',
+    },
+    invalid_public_key: {
+      error_description:
+        'Invalid `publicKey`. Provide an uncompressed public key, or `address`.',
+      field: 'key_authorization.publicKey',
+    },
+    invalid_recipients: {
+      error_description:
+        'Invalid recipient 0x0000000000000000000000000000000000000000 for 0x095ea7b3 on OUSD. Name each recipient once, and never the zero address.',
+      field: 'key_authorization.scopes.0.recipients.0',
+    },
+    limit_exceeds_maximum: {
+      error_description:
+        'Invalid OUSD limit: 5000 exceeds the 1000 maximum. Lower the limit, or authorize through a redirect or device grant.',
+      field: 'key_authorization.limits.0.limit',
+    },
+    logout_not_permitted: {
+      error_description:
+        'Logout not permitted: the app client_01JZ8Q6W3N1R5B4V7C2X9K0M3T may not end the session. Register the app for logout, then retry.',
+    },
+    malformed_body: {
+      error_description:
+        'Malformed request body. Send a JSON object with `Content-Type: application/json`.',
+    },
+    missing_key: {
+      error_description:
+        'Missing `address` or `publicKey`. Provide the access key.',
+      field: 'key_authorization.address',
+    },
+    missing_recipients: {
+      error_description:
+        'Missing `recipients` for `approve` on OUSD. Name the allowed spenders.',
+      field: 'key_authorization.scopes.0.recipients',
+    },
+    passkey_link_expired: {
+      error_description:
+        'Expired passkey sign-in: the link from the passkey step is no longer valid. Enter the code again to sign in with email only, or sign in with the passkey again.',
+      field: 'link',
+    },
+    passkey_not_permitted: {
+      error_description:
+        'Passkey not permitted: the app client_01JZ8Q6W3N1R5B4V7C2X9K0M3T holds no passkeys. Sign in with an emailed code.',
+    },
+    polling_too_fast: {
+      error_description: 'Polling too fast. Add 5 seconds to `interval`.',
+    },
+    post_logout_redirect_not_permitted: {
+      error_description:
+        'Invalid post_logout_redirect_uri: https://app.example/elsewhere is not registered for the app. Use one of its post-logout redirect URIs, or leave it out.',
+      field: 'post_logout_redirect_uri',
+    },
+    rate_limited: {
+      error_description: 'Too many requests. Retry after 30 seconds.',
+    },
+    rejected: {
+      error_description:
+        "Authorization request rejected. Check `client_id`, `redirect_uri`, and `scope` against the app's registration.",
+    },
+    request_denied: { error_description: 'The user denied the request.' },
+    return_to_not_permitted: {
+      error_description:
+        "Invalid return_to: https://example.org is not an origin of the app's redirect URIs. Return to a page on one of them, and pass the app's client_id.",
+      field: 'return_to',
+    },
+    scope_without_limit: {
+      error_description:
+        'Scope on 0x20c0000000000000000000000000000000000002 has no limit. Add a limit for it, or remove the scope.',
+      field: 'key_authorization.scopes.0.address',
+    },
+    session_changed: {
+      error_description:
+        'Changed session: the signed-in account differs from the one that this page showed. Reload the page, and check the account before the decision.',
+      field: 'session_id',
+    },
+    session_required: { error_description: 'Sign in first.' },
+    unexpected: { error_description: 'Unexpected error. Try again.' },
+    unknown_code: {
+      error_description:
+        'Invalid or expired code. Check the code in the terminal.',
+      field: 'code',
+    },
+    unknown_endpoint: {
+      error_description:
+        'Unknown endpoint. Check the method and path against the API reference at /openapi.json.',
+    },
+    unknown_provider: {
+      error_description:
+        'Unknown provider: github is not offered. Request GET /v1/auth/providers for the providers offered.',
+      field: 'provider',
+    },
+    unsupported_call: {
+      error_description:
+        'Unsupported call on OUSD: any function. Use `transfer`, `transferWithMemo`, or `approve`.',
+      field: 'key_authorization.scopes.0.selector',
+    },
+    unsupported_token: {
+      error_description:
+        'Unsupported token on chain 4217: 0x20c00000000000000000000000000000000000ff. Use a supported token, such as OUSD.',
+      field: 'key_authorization.limits.0.token',
+    },
+    upstream_unavailable: {
+      error_description: 'An upstream service is unavailable. Retry later.',
+    },
+    webauthn_rejected: {
+      error_description:
+        'Passkey rejected. Request new options, then try again with the same passkey or another one.',
+    },
+    webauthn_required: {
+      error_description:
+        'Passkey required: Tempo Account 0x8C3b5d0e2A4f6B1c9D7e3F5a0B2c4D6e8F1a3B5c signs key authorizations only with its passkey, on a Tempo ID page. Authorize through a redirect, popup, or device grant, or name another account.',
+      field: 'key_authorization.account',
+    },
+  }
+
+  /** Each reason's schema, which the OpenAPI document lists as a component. */
+  const byReason = new Map<Reason, z.ZodType>(
+    Object.entries(reasons).map(([reason, definition]) => {
+      const example = examples[reason as Reason]
+      const extended = base.extend({
+        error: z.literal(definition.error).meta(base.shape.error.meta()!),
+        error_description: base.shape.error_description.meta({
+          ...base.shape.error_description.meta(),
+          examples: [example.error_description],
+        }),
+        error_uri: base.shape.error_uri.meta({
+          ...base.shape.error_uri.meta(),
+          examples: [`${docs}#${reason}`],
+        }),
+        reason: z.literal(reason).meta(base.shape.reason.meta()!),
+        request_id: base.shape.request_id.meta({
+          ...base.shape.request_id.meta(),
+          examples: ['8f1c2a3b4d5e6f70-SJC'],
+        }),
+      })
+      // A refusal that names no field never sends one, so its component leaves `field` out.
+      const documented = example.field
+        ? extended.extend({
+            field: base.shape.field.meta({
+              ...base.shape.field.meta(),
+              examples: [example.field],
+            }),
+          })
+        : extended.omit({ field: true })
+      return [
+        reason as Reason,
+        documented.meta({
+          description: `\`${definition.error}\` (${definition.status}): ${definition.description}`,
+          id: `ErrorResponse.${reason}`,
+        }),
+      ]
+    }),
+  )
+
+  /** The schema of `reason`'s error response. */
+  export function of<const reason extends Reason>(reason: reason) {
+    return byReason.get(reason)! as z.ZodType<ErrorResponse<reason>>
+  }
+}
+
+/**
+ * Instantiates an {@link ErrorResponse}, filling `error` from `reason`'s definition and
+ * `error_uri` with `reason`'s section of the errors page.
+ */
+export function from<const reason extends Reason>(
+  value: from.Value<reason>,
+): ErrorResponse<reason> {
+  const { error_description, field, meta, reason } = value
+  return {
+    error: reasons[reason].error,
+    error_description,
+    error_uri: `${docs}#${reason}`,
+    ...(field ? { field } : {}),
+    ...(meta ? { meta } : {}),
+    reason,
+  } as ErrorResponse<reason>
+}
+
+export declare namespace from {
+  type Value<reason extends Reason> = {
+    /** What went wrong and how to fix it, for people. */
+    error_description: string
+    /** The request field at fault, as a dotted path. */
+    field?: string | undefined
+    /** The values the refusal compared. Base units are decimal strings. */
+    meta?: Readonly<Record<string, number | string>> | undefined
+    /** The refusal, which determines `error` and the status. */
+    reason: reason
+  }
+}
+
+/**
+ * Returns the refusal for an upstream service's failure, from the error its SDK threw or the
+ * response it sent. The refusal is `rate_limited` for a 429, and `upstream_unavailable` for a 408,
+ * a 5xx, a timeout, or a request that received no response. Returns `undefined` for anything else,
+ * such as an error Tempo ID throws itself.
+ */
+export function fromUpstream(
+  failure: Error | Response,
+): Instance<typeof fromUpstream.errors> | undefined {
+  if (failure instanceof HTTPException) return undefined
+  // SDKs such as Privy's carry the service's HTTP status on the errors they throw.
+  const status = 'status' in failure ? failure.status : undefined
+  if (status === 429) {
+    const retryAfter = (() => {
+      if (failure instanceof Response) {
+        // Only the delay-seconds form of `Retry-After` is read. An HTTP date is left out.
+        const seconds = Number(failure.headers.get('retry-after'))
+        return Number.isInteger(seconds) && seconds > 0 ? seconds : undefined
+      }
+      return 'retryAfter' in failure && typeof failure.retryAfter === 'number'
+        ? failure.retryAfter
+        : undefined
+    })()
+    return new RateLimitedError({ retryAfter })
+  }
+  // An SDK error whose `status` is present but `undefined` received no response, such as Privy's
+  // `APIConnectionTimeoutError` for a timeout or `APIConnectionError` for a dropped connection.
+  const unanswered = 'status' in failure && status === undefined
+  if (
+    (typeof status === 'number' && (status === 408 || status >= 500)) ||
+    unanswered ||
+    (failure instanceof Error && failure.name === 'TimeoutError')
+  )
+    return new UpstreamUnavailableError()
+  return undefined
+}
+
+export namespace fromUpstream {
+  /** The refusals `fromUpstream` returns for an upstream service's failure. */
+  export const errors = [RateLimitedError, UpstreamUnavailableError] as const
+}
+
+/**
+ * Maps any error a handler or middleware throws to its documented response:
+ *
+ * - A {@link ResponseError} maps to its own response.
+ * - Hono's malformed body refusal maps to `malformed_body`.
+ * - The CSRF check's refusal maps to `cross_site_request`.
+ * - An upstream service's failure maps to `rate_limited` or `upstream_unavailable`, and logs a
+ *   warning.
+ * - Anything else maps to `unexpected`, and logs the error.
+ */
+export function handle(error: Error, c: Context) {
+  if (error instanceof ResponseError) return json(c, error)
+  // Hono's body validator refuses unreadable JSON with a bare 400, and `csrf()` with a bare 403.
+  if (error instanceof HTTPException && error.status === 400)
+    return json(c, new MalformedBodyError())
+  if (error instanceof HTTPException && error.status === 403)
+    return json(c, new CrossSiteRequestError())
+
+  const upstream = fromUpstream(error)
+  if (upstream) {
+    Log.warn(c, { error, message: 'An upstream service refused a request.' })
+    return json(c, upstream)
+  }
+
+  Log.error(c, { error, message: 'The API failed a request.' })
+  return json(c, new UnexpectedError())
+}
+
+/**
+ * Returns the response for `error`, at the status its `reason` determines. A `rate_limited` refusal
+ * that carries the service's wait also sends it as `Retry-After`.
+ */
+export function json<const reason extends Reason>(
+  c: Context,
+  error: ResponseError<reason>,
+): Json<reason> {
+  const { response } = error
+  if (error instanceof RateLimitedError && error.retryAfter)
+    c.header('retry-after', String(error.retryAfter))
+  return c.json(response, reasons[response.reason].status) as Json<reason>
+}