galbe 0.15.6 → 0.16.0

package/src/middlewares/_auth.ts

@@ -0,0 +1,178 @@
+import type { OpenAPIV3 } from 'openapi-types'
+import type { PreParseContext, PreParseHook } from '../types'
+
+import { UnauthorizedError } from '../types'
+
+/**
+ * Internals shared by the credential-checking middlewares — `jwt`, `bearer`,
+ * `apiKey` and `basicAuth`. Only {@link AuthError} is public API; it is
+ * re-exported from each of those modules and from `galbe/middlewares`.
+ */
+
+export type MaybePromise<T> = T | Promise<T>
+
+/**
+ * Why a request was rejected: no credential at all, one that could not be read,
+ * or one that was read and refused. Available to an `errorHandler`, never sent
+ * to the client.
+ */
+export type AuthErrorCode = 'missing' | 'malformed' | 'invalid'
+
+/**
+ * Thrown by every auth middleware on rejection, and handed to its
+ * `errorHandler`. `jwt` throws the `JwtError` subclass, which carries a finer
+ * {@link AuthError.code}.
+ */
+export class AuthError<C extends string = AuthErrorCode> extends Error {
+  code: C
+  constructor(code: C, message: string) {
+    super(message)
+    this.name = 'AuthError'
+    this.code = code
+  }
+}
+
+/**
+ * Replaces the default rejection. Returning a `Response` answers the request,
+ * returning nothing falls back to the default `401` (or `429` for
+ * `rateLimit`), and throwing takes the usual error handler path.
+ *
+ * Optional authentication is deliberately **not** expressible here: it is the
+ * `optional` option of each middleware, so no error handler can turn a
+ * rejection into an authenticated request by forgetting to return something.
+ */
+export type AuthErrorHandler<E extends AuthError<any> = AuthError> = (
+  error: E,
+  ctx: PreParseContext
+) => MaybePromise<Response | void>
+
+/** Where a credential travels. `cookie` has no schema fragment: a middleware fragment covers headers, query and params. */
+export type CredentialIn = 'header' | 'query' | 'cookie'
+
+/**
+ * Reads a credential out of the pre-parse context, where the body, the params
+ * and the parsed query do not exist yet — hence the raw `URL` for query keys.
+ * An expected `prefix` (`'Bearer '`, `'Basic '`) is matched case-insensitively,
+ * as HTTP auth scheme names are, and stripped.
+ */
+export const readCredential = (ctx: PreParseContext, where: CredentialIn, name: string, prefix?: string) => {
+  if (where === 'query') return new URL(ctx.request.url).searchParams.get(name) || undefined
+  // cookie names are request-controlled keys: never reach through the prototype
+  if (where === 'cookie')
+    return Object.hasOwn(ctx.cookies, name) && ctx.cookies[name] ? String(ctx.cookies[name]) : undefined
+  const value = ctx.request.headers.get(name)
+  if (!value) return undefined
+  if (!prefix) return value
+  if (value.slice(0, prefix.length).toLowerCase() !== prefix.toLowerCase()) return undefined
+  return value.slice(prefix.length).trim() || undefined
+}
+
+/**
+ * Reads a credential the middleware requires, or reports it missing — unless
+ * the instance is `optional`, in which case a request carrying no credential
+ * simply carries on unauthenticated. Only *absence* is forgiven: a credential
+ * that is present and unreadable is still a malformed one.
+ */
+export const readRequired = (
+  ctx: PreParseContext,
+  where: CredentialIn,
+  name: string,
+  prefix?: string,
+  optional?: boolean
+) => {
+  const value = readCredential(ctx, where, name, prefix)
+  if (value) return value
+  if (optional) return undefined
+  throw new AuthError('missing', `no ${name} ${where} in the request`)
+}
+
+const encoder = new TextEncoder()
+const digest = async (value: string) => new Uint8Array(await crypto.subtle.digest('SHA-256', encoder.encode(value)))
+const equalBytes = (a: Uint8Array, b: Uint8Array) => {
+  let diff = a.length ^ b.length
+  for (let i = 0; i < a.length; i++) diff |= a[i]! ^ (b[i] ?? 0)
+  return diff === 0
+}
+
+/**
+ * Constant-time matcher against a fixed set of secrets. Both sides are reduced
+ * to a SHA-256 digest first, so the comparison always runs over 32 bytes:
+ * neither the length of the configured secret nor the position of the first
+ * differing byte is observable through timing. Every candidate is compared —
+ * the loop never short-circuits on a match.
+ */
+export const secretMatcher = (secrets: string[]) => {
+  let expected: Promise<Uint8Array[]> | undefined
+  return async (presented: string) => {
+    const candidates = await (expected ??= Promise.all(secrets.map(digest)))
+    const actual = await digest(presented)
+    let matched = false
+    for (const candidate of candidates) matched = equalBytes(actual, candidate) || matched
+    return matched
+  }
+}
+
+/** `WWW-Authenticate` value for the bearer scheme, per RFC 6750. */
+export const bearerChallenge = (realm: string | undefined, code: string) => {
+  const params = [realm && `realm="${realm}"`, code !== 'missing' && 'error="invalid_token"'].filter(Boolean)
+  return params.length ? `Bearer ${params.join(', ')}` : 'Bearer'
+}
+
+/** A realm ends up verbatim in a response header: keep quotes and control characters out of it. */
+export const checkRealm = (middleware: string, realm?: string) => {
+  if (realm !== undefined && /["\\\x00-\x1f\x7f]/.test(realm))
+    throw new SyntaxError(`${middleware}: realm must not contain quotes, backslashes or control characters`)
+  return realm
+}
+
+/**
+ * The rejection contract, in one place: an {@link AuthError} becomes the
+ * `errorHandler`'s business, or a bare `401` carrying the scheme's challenge.
+ * Anything else — a bad key, a throwing `verify` — is a real fault and is
+ * rethrown rather than flattened into a `401`.
+ */
+export const authHook = (
+  authenticate: (ctx: PreParseContext) => Promise<void>,
+  options: {
+    errorHandler?: AuthErrorHandler<any>
+    challenge?: (error: AuthError<any>) => string | undefined
+  }
+): PreParseHook => {
+  return async ctx => {
+    try {
+      await authenticate(ctx)
+    } catch (error) {
+      if (!(error instanceof AuthError)) throw error
+      // an errorHandler answers, or says nothing and leaves the default 401 in
+      // place: returning nothing is never a way to authenticate a request
+      const handled = await options.errorHandler?.(error, ctx)
+      if (handled) return handled
+      const challenge = options.challenge?.(error)
+      throw new UnauthorizedError(undefined, challenge ? { 'www-authenticate': challenge } : undefined)
+    }
+  }
+}
+
+/**
+ * Builds the two halves of the OpenAPI security metadata from the schemes a
+ * middleware enforces: the requirement (`security`) and the definitions
+ * (`securitySchemes`). `rename` overrides the default names so two instances
+ * can coexist in one app; `false` opts out of security metadata entirely.
+ * Colliding names get a numeric suffix rather than silently overwriting.
+ */
+export const securityMetadata = (
+  schemes: { name: string; scheme: OpenAPIV3.SecuritySchemeObject }[],
+  rename?: string | false
+) => {
+  const securitySchemes: Record<string, OpenAPIV3.SecuritySchemeObject> = Object.create(null)
+  const security: string[] = []
+  if (rename !== false)
+    for (const entry of schemes) {
+      const wanted = rename ?? entry.name
+      let name = wanted
+      for (let i = 2; Object.hasOwn(securitySchemes, name); i++) name = `${wanted}${i}`
+      securitySchemes[name] = entry.scheme
+      security.push(name)
+    }
+  return { security, securitySchemes }
+}

package/src/middlewares/apiKey.ts

@@ -0,0 +1,139 @@
+import type { MiddlewareDef, PreParseContext } from '../types'
+import type { STOptional, STString } from '../schema'
+import type { AuthErrorHandler, CredentialIn, MaybePromise } from './_auth'
+
+import { $T } from '../index'
+import { AuthError, authHook, readRequired, secretMatcher, securityMetadata } from './_auth'
+
+export { AuthError } from './_auth'
+
+export type ApiKeyConfig<N extends string = 'x-api-key', I extends CredentialIn = 'header'> = {
+  /**
+   * Accepted key(s), compared in constant time. Either this or `verify` is
+   * required; when both are given, `verify` decides.
+   */
+  key?: string | string[]
+  /**
+   * Looks the key up instead of comparing it to a constant. Return the
+   * identity to put on `ctx.state`, or `false`/`null`/`undefined` to reject.
+   * Returning `true` accepts the request with no identity to carry: the state
+   * key is then set to `true`, never to the key itself.
+   */
+  verify?: (key: string, ctx: PreParseContext) => MaybePromise<boolean | object | null | undefined>
+  /**
+   * Where the key travels. Default `header`. A `query` key is accepted because
+   * OpenAPI describes it, but it lands in access logs, proxy traces and
+   * `Referer` headers — prefer a header wherever you control the caller.
+   */
+  in?: I
+  /** Name of the header, query parameter or cookie carrying the key. Default `x-api-key`. */
+  name?: N
+  /** `ctx.state` key the identity is stored under. Default `apiKey`. */
+  stateHolder?: string
+  /**
+   * Lets a request carrying **no** key through unauthenticated instead of
+   * answering 401. A key that is present and refused is still rejected.
+   */
+  optional?: boolean
+  /**
+   * Replaces the default rejection. Return a `Response` to answer the request,
+   * or nothing to fall back to the default `401`; throwing takes the usual
+   * error handler path. Optional authentication is {@link ApiKeyConfig.optional},
+   * not something an error handler expresses.
+   */
+  errorHandler?: AuthErrorHandler
+  /**
+   * Name of the OpenAPI security scheme contributed. Default `apiKeyAuth` —
+   * rename it when two instances coexist in one app; `false` emits no security
+   * metadata at all.
+   */
+  securityScheme?: string | false
+}
+
+/**
+ * The contract an `apiKey` instance imposes on every route it matches — the
+ * declared parameter, in the part of the request it travels in. A cookie key
+ * contributes none: a middleware fragment covers headers, query and params.
+ */
+export type ApiKeyFragment<N extends string, I extends CredentialIn> = I extends 'header'
+  ? { headers: Record<N, STOptional<STString>> }
+  : I extends 'query'
+    ? { query: Record<N, STOptional<STString>> }
+    : {}
+
+/**
+ * #### apiKey
+ * Checks a named API key — a header by default, optionally a query parameter
+ * or a cookie — against a constant or against whatever `verify` looks it up in.
+ *
+ * It runs in the [`beforeParse`](https://galbe.dev/documentation/middleware#before-parsing)
+ * slot, so an unauthenticated request is answered **401 before its body is
+ * read**. Configured keys are compared in constant time, and the reason for a
+ * rejection stays server-side, in the {@link AuthError} handed to `errorHandler`.
+ *
+ * The def declares the parameter it reads and the `apiKey` security scheme that
+ * owns it, so the key documents as auth instead of as a plain header.
+ *
+ * ---
+ * @example
+ * ```typescript
+ * import { apiKey } from 'galbe/middlewares'
+ *
+ * // the default: an x-api-key header, checked against a constant
+ * galbe.middleware('/api/*', apiKey({ key: Bun.env.API_KEY! }))
+ *
+ * // a named header, looked up, with the tenant carried to the handlers
+ * galbe.middleware('/v1/*', apiKey({
+ *   name: 'x-tenant-key',
+ *   verify: async key => (await db.tenantByKey(key)) ?? false
+ * }))
+ *
+ * // public traffic carries no key at all: let it through unauthenticated
+ * galbe.middleware('/v1/public/*', apiKey({
+ *   verify: async key => await db.tenantByKey(key),
+ *   optional: true
+ * }))
+ *
+ * galbe.get('/v1/usage', ctx => ctx.state.apiKey.tenantId)
+ * ```
+ * @param config - see {@link ApiKeyConfig}
+ */
+export const apiKey = <N extends string = 'x-api-key', I extends CredentialIn = 'header'>(
+  config: ApiKeyConfig<N, I>
+): MiddlewareDef<ApiKeyFragment<N, I>> => {
+  if (!config.verify && config.key === undefined) throw new SyntaxError("apiKey: either 'key' or 'verify' is required")
+  const where: CredentialIn = config.in ?? 'header'
+  const name: string = config.name ?? 'x-api-key'
+  const stateHolder = config.stateHolder ?? 'apiKey'
+  const matches = config.key === undefined ? undefined : secretMatcher([config.key].flat())
+
+  const beforeParse = authHook(
+    async ctx => {
+      const key = readRequired(ctx, where, name, undefined, config.optional)
+      if (!key) return
+      const identity = config.verify ? await config.verify(key, ctx) : await matches!(key)
+      if (!identity) throw new AuthError('invalid', 'api key rejected')
+      // the key is set whenever the request authenticated — `true` for a
+      // configured constant, so the key itself never lands on `ctx.state`,
+      // where every log line and error report would find it
+      ctx.state[stateHolder] = identity
+    },
+    // no challenge: an api key scheme has no registered WWW-Authenticate form
+    { errorHandler: config.errorHandler }
+  )
+
+  const { security, securitySchemes } = securityMetadata(
+    [{ name: 'apiKeyAuth', scheme: { type: 'apiKey', in: where, name } }],
+    config.securityScheme
+  )
+  const parameter = { [name]: $T.optional($T.string()) }
+  return {
+    beforeParse,
+    ...(where === 'header'
+      ? { schema: { headers: parameter } }
+      : where === 'query'
+        ? { schema: { query: parameter } }
+        : {}),
+    ...(security.length ? { security, securitySchemes } : {}),
+  } as MiddlewareDef<ApiKeyFragment<N, I>>
+}

package/src/middlewares/basicAuth.ts

@@ -0,0 +1,151 @@
+import type { MiddlewareDef, PreParseContext } from '../types'
+import type { STOptional, STString } from '../schema'
+import type { AuthErrorHandler, MaybePromise } from './_auth'
+
+import { $T } from '../index'
+import { AuthError, authHook, checkRealm, readRequired, secretMatcher, securityMetadata } from './_auth'
+
+export { AuthError } from './_auth'
+
+export type BasicAuthConfig = {
+  /**
+   * Accepted credentials, as `{ user: password }`, compared in constant time.
+   * Either this or `verify` is required; when both are given, `verify` decides.
+   *
+   * > Passwords sit in memory in clear: this is the right shape for a handful
+   * > of machine accounts from the environment, not for real user accounts.
+   */
+  users?: Record<string, string>
+  /**
+   * Checks the credentials itself — against a database and a password hash,
+   * typically. Return the identity to put on `ctx.state`, or
+   * `false`/`null`/`undefined` to reject. Returning `true` accepts the request
+   * with no identity to carry: the state key is then set to `true`.
+   */
+  verify?: (user: string, password: string, ctx: PreParseContext) => MaybePromise<boolean | object | null | undefined>
+  /** Protection space named in the `WWW-Authenticate` challenge — what browsers show when prompting. Default `Restricted`. */
+  realm?: string
+  /** `ctx.state` key the identity is stored under — the username, unless `verify` returned one. Default `basicAuth`. */
+  stateHolder?: string
+  /**
+   * Lets a request carrying **no** credentials through unauthenticated instead
+   * of answering 401. Credentials that are present and refused are still
+   * rejected, as are ones that cannot be decoded.
+   */
+  optional?: boolean
+  /**
+   * Replaces the default rejection. Return a `Response` to answer the request,
+   * or nothing to fall back to the default `401`; throwing takes the usual
+   * error handler path. Optional authentication is {@link BasicAuthConfig.optional},
+   * not something an error handler expresses.
+   */
+  errorHandler?: AuthErrorHandler
+  /**
+   * Name of the OpenAPI security scheme contributed. Default `basicAuth` —
+   * rename it when two instances coexist in one app; `false` emits no security
+   * metadata at all.
+   */
+  securityScheme?: string | false
+}
+
+/** The header contract a `basicAuth` instance imposes on every route it matches. */
+export type BasicAuthFragment = { headers: { authorization: STOptional<STString> } }
+
+const decoder = new TextDecoder()
+
+/**
+ * #### basicAuth
+ * HTTP Basic authentication (RFC 7617): decodes `Authorization: Basic` and
+ * checks the credentials against a `{ user: password }` map or `verify`.
+ *
+ * It runs in the [`beforeParse`](https://galbe.dev/documentation/middleware#before-parsing)
+ * slot, so an unauthenticated request is answered **401 before its body is
+ * read**, with the `WWW-Authenticate: Basic` challenge browsers prompt on.
+ * Configured credentials are matched in constant time over the whole
+ * `user:password` pair, so an unknown username is indistinguishable from a
+ * wrong password — no user enumeration through timing.
+ *
+ * > Basic sends the password on every request, protected by nothing but TLS.
+ * > Fine for internal tooling and machine accounts; reach for `jwt` or `bearer`
+ * > for anything user-facing.
+ *
+ * ---
+ * @example
+ * ```typescript
+ * import { basicAuth } from 'galbe/middlewares'
+ *
+ * // a machine account from the environment
+ * galbe.middleware('/metrics/*', basicAuth({
+ *   users: { prometheus: Bun.env.METRICS_PASSWORD! },
+ *   realm: 'metrics'
+ * }))
+ *
+ * // checked against stored hashes, with the account carried to the handlers
+ * galbe.middleware('/admin/*', basicAuth({
+ *   verify: async (user, password) => {
+ *     const account = await db.user(user)
+ *     return account && (await Bun.password.verify(password, account.hash)) ? account : false
+ *   }
+ * }))
+ *
+ * // credentials are welcome but not required
+ * galbe.middleware('/status/*', basicAuth({
+ *   users: { prometheus: Bun.env.METRICS_PASSWORD! },
+ *   optional: true
+ * }))
+ *
+ * galbe.get('/admin/me', ctx => ctx.state.basicAuth.email)
+ * ```
+ * @param config - see {@link BasicAuthConfig}
+ */
+export const basicAuth = (config: BasicAuthConfig): MiddlewareDef<BasicAuthFragment> => {
+  if (!config.verify && config.users === undefined)
+    throw new SyntaxError("basicAuth: either 'users' or 'verify' is required")
+  // an empty map is almost always an environment variable that did not arrive:
+  // fail at registration rather than reject every caller as a wrong password
+  if (config.users !== undefined && !Object.keys(config.users).length)
+    throw new SyntaxError('basicAuth: `users` is empty, no credential would ever be accepted')
+  const stateHolder = config.stateHolder ?? 'basicAuth'
+  const realm = checkRealm('basicAuth', config.realm) ?? 'Restricted'
+  // one matcher over the whole `user:password` pair: checking the username
+  // first would answer faster for an unknown user than for a wrong password
+  const matches =
+    config.users === undefined ? undefined : secretMatcher(Object.entries(config.users).map(p => p.join(':')))
+
+  const beforeParse = authHook(
+    async ctx => {
+      const credentials = readRequired(ctx, 'header', 'authorization', 'Basic ', config.optional)
+      if (!credentials) return
+      let decoded: string
+      try {
+        // RFC 7617 allows UTF-8 credentials, so decode the bytes rather than
+        // reading atob's binary string as latin-1
+        decoded = decoder.decode(Uint8Array.from(atob(credentials), c => c.charCodeAt(0)))
+      } catch {
+        throw new AuthError('malformed', 'credentials are not valid base64')
+      }
+      const separator = decoded.indexOf(':')
+      if (separator < 0) throw new AuthError('malformed', "credentials are not 'user:password'")
+      const user = decoded.slice(0, separator)
+      const identity = config.verify
+        ? await config.verify(user, decoded.slice(separator + 1), ctx)
+        : (await matches!(decoded)) && user
+      if (!identity) throw new AuthError('invalid', 'credentials rejected')
+      // a `users` map authenticates a username, so that name is the identity;
+      // `true` from `verify` sets the key without carrying anything more
+      ctx.state[stateHolder] = identity
+    },
+    { errorHandler: config.errorHandler, challenge: () => `Basic realm="${realm}", charset="UTF-8"` }
+  )
+
+  const { security, securitySchemes } = securityMetadata(
+    [{ name: 'basicAuth', scheme: { type: 'http', scheme: 'basic' } }],
+    config.securityScheme
+  )
+  return {
+    beforeParse,
+    // case-insensitive: the scheme name is (RFC 9110 §11.1), and so is the hook
+    schema: { headers: { authorization: $T.optional($T.string({ pattern: /^Basic /i })) } },
+    ...(security.length ? { security, securitySchemes } : {}),
+  }
+}

package/src/middlewares/bearer.ts

@@ -0,0 +1,136 @@
+import type { MiddlewareDef, PreParseContext } from '../types'
+import type { STOptional, STString } from '../schema'
+import type { AuthErrorHandler, MaybePromise } from './_auth'
+
+import { $T } from '../index'
+import {
+  AuthError,
+  authHook,
+  bearerChallenge,
+  checkRealm,
+  readRequired,
+  secretMatcher,
+  securityMetadata,
+} from './_auth'
+
+export { AuthError } from './_auth'
+
+export type BearerConfig = {
+  /**
+   * Accepted token(s), compared in constant time. Either this or `verify` is
+   * required; when both are given, `verify` decides.
+   */
+  token?: string | string[]
+  /**
+   * Looks the token up instead of comparing it to a constant — a database, a
+   * cache, an introspection endpoint. Return the identity to put on
+   * `ctx.state`, or `false`/`null`/`undefined` to reject. Returning `true`
+   * accepts the request with no identity to carry: the state key is then set to
+   * `true`, never to the credential itself.
+   */
+  verify?: (token: string, ctx: PreParseContext) => MaybePromise<boolean | object | null | undefined>
+  /** `ctx.state` key the identity is stored under. Default `bearer`. */
+  stateHolder?: string
+  /**
+   * Lets a request carrying **no** token through unauthenticated instead of
+   * answering 401 — the public half of a route that personalizes a signed-in
+   * caller. A token that is present and refused is still rejected.
+   */
+  optional?: boolean
+  /** Protection space named in the `WWW-Authenticate` challenge. Omitted by default. */
+  realm?: string
+  /** Documentation only: the `bearerFormat` of the emitted scheme. */
+  format?: string
+  /**
+   * Replaces the default rejection. Return a `Response` to answer the request,
+   * or nothing to fall back to the default `401`; throwing takes the usual
+   * error handler path. Optional authentication is {@link BearerConfig.optional},
+   * not something an error handler expresses.
+   */
+  errorHandler?: AuthErrorHandler
+  /**
+   * Name of the OpenAPI security scheme contributed. Default `bearerAuth` —
+   * rename it when two instances coexist in one app; `false` emits no security
+   * metadata at all.
+   */
+  securityScheme?: string | false
+}
+
+/** The header contract a `bearer` instance imposes on every route it matches. */
+export type BearerFragment = { headers: { authorization: STOptional<STString> } }
+
+/**
+ * #### bearer
+ * Checks the `Authorization: Bearer` token against a constant, or against
+ * whatever `verify` looks it up in. This is the **opaque token** middleware —
+ * for tokens that carry their own signature, use `jwt`, which verifies rather
+ * than looks up.
+ *
+ * It runs in the [`beforeParse`](https://galbe.dev/documentation/middleware#before-parsing)
+ * slot, so an unauthenticated request is answered **401 before its body is
+ * read**. Configured tokens are compared in constant time, and the reason for a
+ * rejection stays server-side, in the {@link AuthError} handed to `errorHandler`.
+ *
+ * ---
+ * @example
+ * ```typescript
+ * import { bearer } from 'galbe/middlewares'
+ *
+ * // a shared secret, straight from the environment
+ * galbe.middleware('/hooks/*', bearer({ token: Bun.env.WEBHOOK_TOKEN! }))
+ *
+ * // looked up, with the identity carried to the handlers
+ * galbe.middleware('/api/*', bearer({
+ *   verify: async token => (await db.session(token)) ?? false
+ * }))
+ *
+ * // signed in or not: a missing token is not a rejection here
+ * galbe.middleware('/feed/*', bearer({
+ *   verify: async token => await db.session(token),
+ *   optional: true
+ * }))
+ *
+ * galbe.get('/api/me', ctx => ctx.state.bearer.userId)
+ * ```
+ * @param config - see {@link BearerConfig}
+ */
+export const bearer = (config: BearerConfig): MiddlewareDef<BearerFragment> => {
+  if (!config.verify && config.token === undefined)
+    throw new SyntaxError("bearer: either 'token' or 'verify' is required")
+  const stateHolder = config.stateHolder ?? 'bearer'
+  const realm = checkRealm('bearer', config.realm)
+  const matches = config.token === undefined ? undefined : secretMatcher([config.token].flat())
+
+  const beforeParse = authHook(
+    async ctx => {
+      const token = readRequired(ctx, 'header', 'authorization', 'Bearer ', config.optional)
+      if (!token) return
+      const identity = config.verify ? await config.verify(token, ctx) : await matches!(token)
+      if (!identity) throw new AuthError('invalid', 'bearer token rejected')
+      // the key is set whenever the request authenticated — `true` for a
+      // configured constant, so the token itself never lands on `ctx.state`,
+      // where every log line and error report would find it
+      ctx.state[stateHolder] = identity
+    },
+    { errorHandler: config.errorHandler, challenge: error => bearerChallenge(realm, error.code) }
+  )
+
+  const { security, securitySchemes } = securityMetadata(
+    [
+      {
+        name: 'bearerAuth',
+        scheme: { type: 'http', scheme: 'bearer', ...(config.format ? { bearerFormat: config.format } : {}) },
+      },
+    ],
+    config.securityScheme
+  )
+  // case-insensitive because the scheme name is (RFC 9110 §11.1) and the hook
+  // reads it that way: a fragment that rejected `bearer <token>` would 400 a
+  // request its own middleware just authenticated
+  const authorization = $T.optional($T.string({ pattern: /^Bearer /i }))
+  return {
+    beforeParse,
+    schema: { headers: { authorization } },
+    ...(security.length ? { security, securitySchemes } : {}),
+  }
+}