@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/internal/Apps.ts

@@ -0,0 +1,1283 @@
+/**
+ * OAuth apps: the Better Auth plugins that serve them, and the `tempo-id admin apps` operations on
+ * `oauth_client`. Every registered app is first-party. A third-party app's client ID is its
+ * metadata document's URL or its origin.
+ * @module
+ */
+import {
+  createCimdClientDiscovery,
+  isCimdClientIdUrlCandidate,
+} from '@better-auth/cimd'
+import {
+  isLoopbackHost,
+  isPublicRoutableHost,
+} from '@better-auth/core/utils/host'
+import { isNativePrivateUseRedirectUri } from '@better-auth/core/utils/redirect-uri'
+import type {
+  ClientDiscovery,
+  ClientMetadataResourceFetch,
+} from '@better-auth/oauth-provider'
+import {
+  getOAuthProviderApi,
+  getOAuthProviderState,
+  oauthProvider,
+} from '@better-auth/oauth-provider'
+import { registerClientMetadataDocument } from '@better-auth/oauth-provider/internal'
+import type { BetterAuthPlugin } from 'better-auth'
+import {
+  APIError,
+  createAuthEndpoint,
+  createAuthMiddleware,
+  getSessionFromCtx,
+  setShouldSkipSessionRefresh,
+} from 'better-auth/api'
+import { generateRandomString } from 'better-auth/crypto'
+import { jwt } from 'better-auth/plugins/jwt'
+import { and, asc, eq, inArray, isNull, or } from 'drizzle-orm'
+import { Base64, Bytes } from 'ox'
+import { z } from 'zod'
+import * as Schema from '../app/db/schema.js'
+import type * as Cache from './Cache.js'
+import type * as PendingKey from './PendingKey.js'
+import type * as Realm from './Realm.js'
+import * as SigningKey from './SigningKey.js'
+
+/** Another app already has the client ID. */
+export class ExistsError extends Error {
+  override readonly name = 'Apps.ExistsError'
+
+  constructor(options: { clientId: string }) {
+    super(
+      `App ${options.clientId} already exists. Update it, or choose another client ID.`,
+    )
+  }
+}
+
+/** A name, a redirect URI, or another value of an app is not valid. */
+export class InvalidError extends Error {
+  override readonly name = 'Apps.InvalidError'
+}
+
+/** No OAuth app has the client ID. */
+export class NotFoundError extends Error {
+  override readonly name = 'Apps.NotFoundError'
+
+  constructor(options: { clientId: string }) {
+    super(`Unknown app ${options.clientId}. Name a registered OAuth app.`)
+  }
+}
+
+/** The app redeems codes with PKCE alone, so it has no client secret to rotate. */
+export class PublicError extends Error {
+  override readonly name = 'Apps.PublicError'
+
+  constructor(options: { clientId: string }) {
+    super(
+      `App ${options.clientId} has no client secret. Rotate the secret of an app with a backend.`,
+    )
+  }
+}
+
+/** An OAuth app, as `tempo-id admin apps` returns it. */
+export type App = {
+  /** Sent as `client_id`. */
+  clientId: string
+  /** When the app was created. */
+  createdAt: Date | null
+  /** Whether the app signs in through the device grant, as a CLI does. */
+  device: boolean
+  /** Whether `tempo-id admin apps` registered the app, which then skips consent for keyless requests. */
+  firstParty: boolean
+  /** The logo as a `data:` URL. Only an app with an origin client ID has one. */
+  logo: string | null
+  /** The display name on the approval page. */
+  name: string | null
+  /** The URIs that `GET /oauth2/end-session` may return to. */
+  postLogoutRedirectUris: readonly string[]
+  /** The URIs that the app returns to. */
+  redirectUris: readonly string[]
+  /** Whether the app holds a client secret for its backend. */
+  secret: boolean
+  /** Whether the app holds the `tempo-id:sign` scope. */
+  sign: boolean
+  /** `web` for a browser app or a backend, and `native` for a mobile app. */
+  type: 'native' | 'web'
+}
+
+/** The grant type of the device grant (RFC 8628 §3.4). */
+export const deviceGrant = 'urn:ietf:params:oauth:grant-type:device_code'
+
+/** Lets an app bind its own challenge, and request unknown key calls headlessly. */
+export const signScope = 'tempo-id:sign'
+
+/** The scopes that every app may request. */
+const scopes = ['openid', 'profile', 'email', 'offline_access'] as const
+
+/** Returns whether `clientSecret` matches the enabled app, which selects a rate limit's app. */
+export async function authenticate(
+  db: Realm.Database,
+  options: authenticate.Options,
+) {
+  const [row] = await db
+    .select({
+      clientSecret: Schema.oauthClient.clientSecret,
+      disabled: Schema.oauthClient.disabled,
+    })
+    .from(Schema.oauthClient)
+    .where(eq(Schema.oauthClient.clientId, options.clientId))
+    .limit(1)
+  if (!row?.clientSecret || row.disabled) return false
+  return equal(await hashSecret(options.clientSecret), row.clientSecret)
+}
+
+export declare namespace authenticate {
+  type Options = {
+    /** The client ID that the request names. */
+    clientId: string
+    /** The client secret that the request sends. */
+    clientSecret: string
+  }
+}
+
+/**
+ * Registers an app, and returns it with its client secret, which appears only here. Throws
+ * `InvalidError` for an invalid value, and `ExistsError` for a client ID in use.
+ */
+export async function create(db: Realm.Database, options: create.Options) {
+  const type = options.type ?? 'web'
+  const name = parseName(options.name)
+  const postLogoutRedirectUris = parsePostLogoutRedirectUris(
+    options.postLogoutRedirectUris ?? [],
+    { type },
+  )
+  const device = options.device ?? false
+  // A CLI cannot keep a secret, and the device grant's poll sends none, so a device app is public.
+  if (device && (options.secret || options.clientSecret !== undefined))
+    throw new InvalidError(
+      'Invalid app: a device app has no client secret, since a CLI cannot keep one. Leave out the secret.',
+    )
+  // A device app redirects nowhere, so it needs no redirect URI.
+  const redirectUris =
+    device && (options.redirectUris ?? []).length === 0
+      ? []
+      : parseRedirectUris(options.redirectUris ?? [], { type })
+  const clientId =
+    options.clientId === undefined
+      ? // Better Auth's format: 32 random letters.
+        generateRandomString(32, 'a-z', 'A-Z')
+      : parseClientId(options.clientId)
+  const clientSecret = (() => {
+    if (options.clientSecret !== undefined)
+      return parseClientSecret(options.clientSecret)
+    return options.secret ? secret() : undefined
+  })()
+
+  const now = new Date()
+  const [row] = await db
+    .insert(Schema.oauthClient)
+    .values({
+      applicationType: type,
+      clientId,
+      clientSecret: clientSecret ? await hashSecret(clientSecret) : null,
+      createdAt: now,
+      // Lets the app end the session at `GET /oauth2/end-session`, and puts `sid` in its ID tokens.
+      enableEndSession: true,
+      // A device app has no authorization code grant, so `/oauth2/authorize` refuses it.
+      grantTypes: device
+        ? [deviceGrant, 'refresh_token']
+        : ['authorization_code', 'refresh_token'],
+      id: crypto.randomUUID(),
+      name,
+      postLogoutRedirectUris: [...postLogoutRedirectUris],
+      redirectUris: [...redirectUris],
+      responseTypes: ['code'],
+      scopes: scopesOf({ sign: options.sign ?? false }),
+      // Every registered app is first-party.
+      skipConsent: true,
+      // The client package sends the secret in the form body.
+      tokenEndpointAuthMethod: clientSecret ? 'client_secret_post' : 'none',
+      updatedAt: now,
+    })
+    .onConflictDoNothing({ target: Schema.oauthClient.clientId })
+    .returning()
+  if (!row) throw new ExistsError({ clientId })
+
+  return { app: toApp(row), ...(clientSecret ? { clientSecret } : {}) }
+}
+
+export declare namespace create {
+  type Options = {
+    /** Another deployment's client ID to keep. Defaults to 32 random letters. */
+    clientId?: string | undefined
+    /** Another deployment's client secret to keep. Implies `secret`. */
+    clientSecret?: string | undefined
+    /** Whether the app signs in through the device grant. Defaults to `false`. */
+    device?: boolean | undefined
+    /** The display name on the approval page. */
+    name: string
+    /** The URIs that `GET /oauth2/end-session` may return to. Defaults to none. */
+    postLogoutRedirectUris?: readonly string[] | undefined
+    /** The URIs that the app returns to, in every environment. A device app may have none. */
+    redirectUris?: readonly string[] | undefined
+    /** Whether the app receives a new client secret. Defaults to `false`. */
+    secret?: boolean | undefined
+    /** Whether the app holds the `tempo-id:sign` scope. Defaults to `false`. */
+    sign?: boolean | undefined
+    /** The application type. Defaults to `web`. */
+    type?: App['type'] | undefined
+  }
+}
+
+/**
+ * Returns the fetch of third-party apps' metadata documents, through `fetcher`. It refuses
+ * redirects, since a document must sit at its client ID's URL.
+ */
+export function fetchMetadata(
+  fetcher: fetchMetadata.Fetcher = globalThis,
+): ClientMetadataResourceFetch {
+  return async (input, init) => {
+    // Workers support only `follow` and `manual`, so a redirect returns, and the transport refuses it.
+    const response = await fetcher.fetch(
+      new Request(input, { ...init, redirect: 'manual' }),
+    )
+    // A 304 answers the discovery's own conditional request, and moves nothing.
+    if (
+      response.status < 300 ||
+      response.status >= 400 ||
+      response.status === 304
+    )
+      return response
+    await response.body?.cancel()
+    throw new TypeError('The metadata document redirects.')
+  }
+}
+
+export declare namespace fetchMetadata {
+  /** The global scope or a service binding. */
+  type Fetcher = {
+    /** Fetches the request. */
+    fetch: (request: Request) => Promise<Response>
+  }
+}
+
+/** Returns the enabled first-party apps with a redirect URI at `origin`. */
+export async function firstPartyOrigin(
+  db: Realm.Database,
+  options: firstPartyOrigin.Options,
+): Promise<readonly App[]> {
+  const rows = await db
+    .select()
+    .from(Schema.oauthClient)
+    .where(
+      and(
+        isNull(Schema.oauthClient.clientDiscoveryId),
+        eq(Schema.oauthClient.skipConsent, true),
+        or(
+          isNull(Schema.oauthClient.disabled),
+          eq(Schema.oauthClient.disabled, false),
+        ),
+      ),
+    )
+  return rows
+    .filter((row) =>
+      row.redirectUris.some((uri) => {
+        const url = URL.parse(uri)
+        return (
+          (url?.protocol === 'https:' || url?.protocol === 'http:') &&
+          url.origin === options.origin
+        )
+      }),
+    )
+    .map(toApp)
+}
+
+export declare namespace firstPartyOrigin {
+  type Options = {
+    /** The request's `Origin`. */
+    origin: string
+  }
+}
+
+/**
+ * Returns the app with `clientId`. Throws `NotFoundError` if it is unknown, or disabled with
+ * `enabled`.
+ */
+export async function get(db: Realm.Database, options: get.Options) {
+  const row = await find(db, options)
+  if (options.enabled && row.disabled)
+    throw new NotFoundError({ clientId: options.clientId })
+  return toApp(row)
+}
+
+export declare namespace get {
+  type Options = {
+    /** The app's client ID. */
+    clientId: string
+    /** Whether a disabled app counts as no app. Defaults to `false`. */
+    enabled?: boolean | undefined
+  }
+}
+
+/** Returns the SHA-256 hash of a client secret as unpadded base64url, as the row holds it. */
+export async function hashSecret(secret: string) {
+  const digest = await crypto.subtle.digest(
+    'SHA-256',
+    new TextEncoder().encode(secret),
+  )
+  return Base64.fromBytes(new Uint8Array(digest), { pad: false, url: true })
+}
+
+/**
+ * Compares two `hashSecret` hashes in constant time. The CLI runs this module in Node, whose
+ * `crypto.subtle` has no `timingSafeEqual`.
+ */
+function equal(a: string, b: string) {
+  const left = Base64.toBytes(a)
+  const right = Base64.toBytes(b)
+  if (left.length !== right.length) return false
+  let difference = 0
+  for (let index = 0; index < left.length; index++)
+    difference |= left[index]! ^ right[index]!
+  return difference === 0
+}
+
+/** Returns every registered app, oldest first, without third-party apps. */
+export async function list(db: Realm.Database): Promise<readonly App[]> {
+  const rows = await db
+    .select()
+    .from(Schema.oauthClient)
+    .where(isNull(Schema.oauthClient.clientDiscoveryId))
+    .orderBy(
+      asc(Schema.oauthClient.createdAt),
+      asc(Schema.oauthClient.clientId),
+    )
+  return rows.map(toApp)
+}
+
+/** The origins whose resource row this isolate read, so later instances skip the seed's read. */
+const seeded = new Set<string>()
+
+/** Returns the Better Auth plugins that serve OAuth apps: the JWT plugin and the OAuth provider. */
+export function plugins(options: plugins.Options) {
+  const { accountStep, baseURL, cache, pendingKey } = options
+  const fetch = options.metadataFetch ?? fetchMetadata()
+  return [
+    // `iss` is the configured origin, never the request's host. No client reads the session's JWT
+    // header, and each session read would otherwise read the signing keys and sign one.
+    jwt({
+      adapter: SigningKey.adapter({ cache }),
+      disableSettingJwtHeader: true,
+      jwks: SigningKey.jwks,
+      jwt: { issuer: baseURL },
+    }),
+    oauthProvider({
+      allowDynamicClientRegistration: false,
+      // The resource's row holds only the values below, so the isolate reads it once.
+      cachedResources: new Set([baseURL]),
+      // The provider keeps each client row that it reads for the life of its options, which each
+      // request creates again, so a request reads each app once, and the next one reads it again.
+      // A cached client cannot change through the provider's client endpoints, which no route serves.
+      cachedTrustedClients: Object.assign(new Set<string>(), {
+        has: () => true,
+      }),
+      // A third-party app holds only the scopes that every app may request, never `tempo-id:sign`.
+      clientRegistrationDefaultScopes: [...scopes],
+      consentPage: '/authorize',
+      // Apps read the user's address from the ID token, so a grant of `email` puts it there as well
+      // as in userinfo, as OIDC Core §5.4 allows.
+      customIdTokenClaims: (info) =>
+        info.scopes.includes('email')
+          ? {
+              email: info.user.email,
+              email_verified: info.user.emailVerified,
+            }
+          : {},
+      // Every app may request the one resource.
+      enforcePerClientResources: false,
+      // A third-party app names its metadata document's URL or its origin as its client ID, and
+      // registers no row.
+      extensions: [
+        {
+          clientDiscovery: [discovery({ fetch }), originDiscovery({ fetch })],
+        },
+      ],
+      loginPage: '/login',
+      // The account step runs after sign-in and before consent, and `oauth2Continue` resumes the
+      // authorization with `postLogin`, which checks again.
+      ...(accountStep
+        ? {
+            postLogin: {
+              consentReferenceId: () => undefined,
+              page: '/choose-account',
+              shouldRedirect: async (context: {
+                headers: Headers
+                session: { id: string }
+                user: { id: string }
+              }) => {
+                // The authorization stores its query before it checks, so the hook reads the app.
+                const stored = (await getOAuthProviderState())?.query
+                const query = new URLSearchParams(stored ?? '')
+                const clientId = query.get('client_id')
+                if (!clientId) return false
+                return await accountStep({
+                  clientId,
+                  headers: context.headers,
+                  query,
+                  sessionId: context.session.id,
+                  userId: context.user.id,
+                })
+              },
+            },
+          }
+        : {}),
+      // A code's redemption returns the key that its approval signed, once. Better Auth calls this
+      // after it checks the verifier against the code's challenge.
+      ...(pendingKey
+        ? {
+            customTokenResponseFields: async (info: {
+              grantType: string
+              user?: { id: string } | null | undefined
+              verificationValue?: {
+                query: {
+                  client_id: string
+                  code_challenge?: string | undefined
+                  key_authorization?: unknown
+                }
+              }
+            }) => {
+              const query = info.verificationValue?.query
+              if (
+                info.grantType !== 'authorization_code' ||
+                !query?.code_challenge ||
+                // Only a code whose request carried the key takes it, so a keyless code for a reused
+                // challenge leaves it for the keyed one.
+                query.key_authorization === undefined ||
+                !info.user
+              )
+                return {}
+              const key = await pendingKey({
+                clientId: query.client_id,
+                codeChallenge: query.code_challenge,
+                userId: info.user.id,
+              })
+              if (!key) return {}
+              return {
+                account: key.account,
+                key_authorization: key.keyAuthorization,
+              }
+            },
+          }
+        : {}),
+      // Every access token names one audience, so each API verifies tokens for every app the same way.
+      resources: seeded.has(baseURL)
+        ? []
+        : [{ accessTokenTtl: 300, identifier: baseURL, name: 'Tempo ID' }],
+      // Better Auth checks a registered app's scopes against its own row, so `tempo-id:sign` stays out
+      // of this list. A row without scopes falls back to this list, and never receives the scope.
+      scopes: [...scopes],
+      // `create` and `rotateSecret` store each secret with the same hash.
+      storeClientSecret: { hash: hashSecret },
+    }),
+    // A session read inside the authorization extends no session, since the provider's after hook
+    // reads the session cookie of the extension as a sign-in, and authorizes again, with a second
+    // code. This hook runs after the provider's, so it extends a session that is due once the
+    // authorization returns. Better Auth's read extends it and sets the cookie.
+    {
+      hooks: {
+        after: [
+          {
+            handler: createAuthMiddleware(async (ctx) => {
+              await setShouldSkipSessionRefresh(false)
+              const session = ctx.context.session
+              if (!session) return
+              // Better Auth extends a session once `updateAge` of its lifetime passed.
+              const { expiresIn, updateAge } = ctx.context.sessionConfig
+              const due =
+                new Date(session.session.expiresAt).getTime() -
+                  (expiresIn - updateAge) * 1000 <=
+                Date.now()
+              if (!due) return
+              ctx.context.session = null
+              await getSessionFromCtx(ctx)
+            }),
+            matcher: (ctx) => ctx.path === '/oauth2/authorize',
+          },
+        ],
+        before: [
+          {
+            handler: createAuthMiddleware(async () => {
+              await setShouldSkipSessionRefresh(true)
+            }),
+            matcher: (ctx) => ctx.path === '/oauth2/authorize',
+          },
+        ],
+      },
+      id: 'tempo-id-authorize-session',
+    } satisfies BetterAuthPlugin,
+    // Tempo ID's own checks read the `oauth_client` row, which only a resolution writes for a
+    // third-party app. Better Auth resolves a client only inside its endpoints, so a route resolves
+    // it here before the checks.
+    {
+      endpoints: {
+        resolveOAuthClient: createAuthEndpoint.serverOnly(
+          { body: z.object({ client_id: z.string() }), method: 'POST' },
+          async (ctx) => {
+            const plugin = ctx.context.getPlugin('oauth-provider')
+            if (!plugin)
+              throw new Error('The OAuth provider plugin is missing.')
+            const client = await getOAuthProviderApi(
+              ctx,
+              plugin.options,
+            ).getClient(ctx.body.client_id)
+            return ctx.json({ resolved: Boolean(client && !client.disabled) })
+          },
+        ),
+      },
+      id: 'tempo-id-client-discovery',
+    } satisfies BetterAuthPlugin,
+    // Plugins run `init` in order, so this one runs after the provider's seed. A seed that failed
+    // logs and leaves no row, so the next instance seeds again.
+    {
+      id: 'tempo-id-resource-seed',
+      init: async (ctx) => {
+        if (seeded.has(baseURL)) return
+        const row = await ctx.adapter.findOne({
+          model: 'oauthResource',
+          where: [{ field: 'identifier', value: baseURL }],
+        })
+        if (row) seeded.add(baseURL)
+      },
+    } satisfies BetterAuthPlugin,
+  ]
+}
+
+export declare namespace plugins {
+  type Options = {
+    /** Returns whether the app's authorization needs `/choose-account`. Absent, none does. */
+    accountStep?:
+      | ((options: {
+          clientId: string
+          headers: Headers
+          query: URLSearchParams
+          sessionId: string
+          userId: string
+        }) => Promise<boolean>)
+      | undefined
+    /** Tempo ID's origin, which is `iss` and the one resource. */
+    baseURL: string
+    /** The isolate's cache for the signing keys. Absent, nothing is cached. */
+    cache?: Cache.Cache | undefined
+    /** Fetches third-party apps' metadata documents. Defaults to `fetchMetadata()`. */
+    metadataFetch?: ClientMetadataResourceFetch | undefined
+    /** Takes a code's held key authorization, as `PendingKey.take` does. Absent, codes carry none. */
+    pendingKey?:
+      | ((options: {
+          clientId: string
+          codeChallenge: string
+          userId: string
+        }) => Promise<PendingKey.PendingKey | undefined>)
+      | undefined
+  }
+}
+
+/**
+ * Removes the registered app with `clientId`, with its consents, tokens, and realms. Throws
+ * `NotFoundError` when no registered app has it.
+ */
+export async function remove(db: Realm.Database, options: remove.Options) {
+  const removed = await db
+    .delete(Schema.oauthClient)
+    .where(
+      and(
+        eq(Schema.oauthClient.clientId, options.clientId),
+        isNull(Schema.oauthClient.clientDiscoveryId),
+      ),
+    )
+    .returning()
+  const [row] = removed
+  if (!row) throw new NotFoundError({ clientId: options.clientId })
+  return toApp(row)
+}
+
+export declare namespace remove {
+  type Options = {
+    /** The app's client ID. */
+    clientId: string
+  }
+}
+
+/**
+ * Replaces the client secret of the app with `clientId`, and returns the app with the new secret.
+ * The earlier secret stops working at once. Throws `NotFoundError` for an unknown app,
+ * `PublicError` for an app without a secret, and `InvalidError` for an invalid or unchanged secret.
+ */
+export async function rotateSecret(
+  db: Realm.Database,
+  options: rotateSecret.Options,
+) {
+  const clientSecret =
+    options.clientSecret === undefined
+      ? secret()
+      : parseClientSecret(options.clientSecret)
+  const current = await find(db, options)
+  if (!current.clientSecret) throw new PublicError(options)
+  // A rotation to the same secret would leave a leaked secret working while it reports success.
+  if (equal(current.clientSecret, await hashSecret(clientSecret)))
+    throw new InvalidError(
+      'Invalid client secret: it matches the current secret. Use a new secret.',
+    )
+
+  const [row] = await db
+    .update(Schema.oauthClient)
+    .set({
+      clientSecret: await hashSecret(clientSecret),
+      updatedAt: new Date(),
+    })
+    .where(eq(Schema.oauthClient.clientId, options.clientId))
+    .returning()
+  // A concurrent `remove` deleted the app after the read.
+  if (!row) throw new NotFoundError(options)
+  // The row, not the earlier read, since a concurrent `update` can change the app between them.
+  return { app: toApp(row), clientSecret }
+}
+
+export declare namespace rotateSecret {
+  type Options = {
+    /** The app's client ID. */
+    clientId: string
+    /** Another deployment's client secret to keep. Defaults to a new secret. */
+    clientSecret?: string | undefined
+  }
+}
+
+/** Returns whether `clientId` is a canonical `https` origin, such as `https://app.example`. */
+export function originId(clientId: string) {
+  const url = URL.parse(clientId)
+  return url?.protocol === 'https:' && url.origin === clientId
+}
+
+/** Returns whether `clientId` names a third-party app: an `https` URL or origin. */
+export function thirdParty(clientId: string) {
+  return isCimdClientIdUrlCandidate(clientId)
+}
+
+/** Returns the third-party client IDs in `clientIds` without a row within `discoveryFreshness`. */
+export async function stale(
+  db: Realm.Database,
+  options: stale.Options,
+): Promise<readonly string[]> {
+  const candidates = [...new Set(options.clientIds.filter(thirdParty))]
+  if (candidates.length === 0) return []
+  const rows = await db
+    .select({
+      clientDiscoveryId: Schema.oauthClient.clientDiscoveryId,
+      clientId: Schema.oauthClient.clientId,
+      updatedAt: Schema.oauthClient.updatedAt,
+    })
+    .from(Schema.oauthClient)
+    .where(inArray(Schema.oauthClient.clientId, candidates))
+  const current = new Set(
+    rows.filter((row) => fresh(row)).map((row) => row.clientId),
+  )
+  return candidates.filter((clientId) => !current.has(clientId))
+}
+
+export declare namespace stale {
+  type Options = {
+    /** The client IDs in the request's parameters or Basic credentials. */
+    clientIds: readonly string[]
+  }
+}
+
+/**
+ * Updates the registered app with `clientId`, and returns it. A value left out stays. Throws
+ * `NotFoundError` when no registered app has it, and `InvalidError` for an invalid value.
+ */
+export async function update(db: Realm.Database, options: update.Options) {
+  const current = await find(db, options)
+  // The discovery rewrites a third-party app's row from its document, so no update would hold.
+  if (current.clientDiscoveryId)
+    throw new NotFoundError({ clientId: options.clientId })
+  const app = toApp(current)
+  const name = options.name === undefined ? undefined : parseName(options.name)
+  const postLogoutRedirectUris =
+    options.postLogoutRedirectUris === undefined
+      ? undefined
+      : parsePostLogoutRedirectUris(options.postLogoutRedirectUris, {
+          type: app.type,
+        })
+  const redirectUris =
+    options.redirectUris === undefined
+      ? undefined
+      : parseRedirectUris(options.redirectUris, { type: app.type })
+
+  const [row] = await db
+    .update(Schema.oauthClient)
+    .set({
+      ...(name === undefined ? {} : { name }),
+      ...(postLogoutRedirectUris === undefined
+        ? {}
+        : { postLogoutRedirectUris: [...postLogoutRedirectUris] }),
+      // An app registered before logout existed gains it with its post-logout redirect URIs.
+      ...(postLogoutRedirectUris?.length ? { enableEndSession: true } : {}),
+      ...(redirectUris === undefined
+        ? {}
+        : { redirectUris: [...redirectUris] }),
+      ...(options.sign === undefined
+        ? {}
+        : {
+            scopes: scopesOf({
+              scopes: current.scopes ?? undefined,
+              sign: options.sign,
+            }),
+          }),
+      updatedAt: new Date(),
+    })
+    .where(eq(Schema.oauthClient.clientId, options.clientId))
+    .returning()
+  // A concurrent `remove` deleted the app after the read.
+  if (!row) throw new NotFoundError(options)
+  return toApp(row)
+}
+
+export declare namespace update {
+  type Options = {
+    /** The app's client ID. */
+    clientId: string
+    /** The display name. */
+    name?: string | undefined
+    /** Replaces the URIs that `GET /oauth2/end-session` may return to. An empty list clears them. */
+    postLogoutRedirectUris?: readonly string[] | undefined
+    /** Replaces the URIs that the app returns to. */
+    redirectUris?: readonly string[] | undefined
+    /** Whether the app holds the `tempo-id:sign` scope. */
+    sign?: boolean | undefined
+  }
+}
+
+/** Milliseconds that a third-party app's row serves before the next fetch of its document. */
+const discoveryFreshness = 5 * 60 * 1000
+
+/** Returns whether `row` is a third-party app's row written within `discoveryFreshness`. */
+function fresh(
+  row:
+    | { clientDiscoveryId?: string | null; updatedAt?: Date | null }
+    | null
+    | undefined,
+): row is { clientDiscoveryId: string; updatedAt: Date } {
+  if (!row?.clientDiscoveryId || !row.updatedAt) return false
+  return Date.now() - row.updatedAt.getTime() < discoveryFreshness
+}
+
+/**
+ * Returns the client discovery of apps whose client ID is a metadata document's URL. It binds every
+ * URL in the document to that origin. It refuses `http` or loopback URIs, grants other than
+ * `authorization_code` and `refresh_token`, and client authentication.
+ */
+function discovery(options: { fetch: ClientMetadataResourceFetch }) {
+  const cimd = createCimdClientDiscovery({
+    fetchClientMetadataResource: options.fetch,
+    originBoundFields: [
+      'client_uri',
+      'logo_uri',
+      'policy_uri',
+      'post_logout_redirect_uris',
+      'redirect_uris',
+      'tos_uri',
+    ],
+  })
+  // An authorization with a key resolves the app before the issuer does. A failed fetch blocks the
+  // next fetch for the per-client interval, so the second resolve repeats the first one's result.
+  const resolutions = new Map<string, ReturnType<typeof cimd.resolve>>()
+  return {
+    ...cimd,
+    // An origin client ID has no metadata document, and `originDiscovery` resolves it.
+    matches: (clientId) => cimd.matches(clientId) && !originId(clientId),
+    resolve: async (ctx, clientId, existing) => {
+      // The discovery's own cache lives in one Better Auth instance, which serves one request, so a
+      // fresh row serves as the cache. A row that the checks below refused stays refused.
+      const client = await (() => {
+        if (fresh(existing)) return existing
+        const resolution =
+          resolutions.get(clientId) ?? cimd.resolve(ctx, clientId, existing)
+        resolutions.set(clientId, resolution)
+        return resolution
+      })()
+      if (!client) return client
+      // The discovery admits loopback redirects, such as `http://localhost` and `https://x.localhost`,
+      // outside the origin binding. Tempo ID bans them, as `create` does.
+      // A custom scheme is refused too: any app on the device can claim it, so the key would reach an
+      // app other than the host that the approval page names. A mobile app uses a claimed https link.
+      const refused = [
+        ...(client.redirectUris ?? []),
+        ...(client.postLogoutRedirectUris ?? []),
+      ].find((uri) => {
+        const url = URL.parse(uri)
+        if (!url || url.protocol !== 'https:') return true
+        return (
+          isLoopbackHost(url.hostname) || url.hostname.endsWith('.localhost')
+        )
+      })
+      if (refused)
+        throw new APIError('BAD_REQUEST', {
+          error: 'invalid_client',
+          error_description: `Invalid redirect URI in the metadata document: ${refused}. Use an https URI on the client ID's origin.`,
+        })
+      // A third-party app signs in through a redirect alone. The device grant would show its name on
+      // the device page, beside no host that proves it.
+      const grant = (client.grantTypes ?? []).find(
+        (type) => type !== 'authorization_code' && type !== 'refresh_token',
+      )
+      if (grant)
+        throw new APIError('BAD_REQUEST', {
+          error: 'invalid_client',
+          error_description: `Unsupported grant type in the metadata document: ${grant}. Use authorization_code and refresh_token.`,
+        })
+      // A third-party app is a public client that redeems codes with PKCE alone, so it holds no key
+      // that Tempo ID would fetch from a `jwks_uri`.
+      const method = client.tokenEndpointAuthMethod ?? 'none'
+      if (method !== 'none')
+        throw new APIError('BAD_REQUEST', {
+          error: 'invalid_client',
+          error_description: `Unsupported token_endpoint_auth_method in the metadata document: ${method}. Use none.`,
+        })
+      return client
+    },
+  } satisfies ClientDiscovery
+}
+
+/**
+ * Returns the client discovery of apps whose client ID is their `https` origin. A failed `describe`
+ * falls back to the origin's root and host, so it never blocks a sign-in.
+ */
+function originDiscovery(options: { fetch: ClientMetadataResourceFetch }) {
+  // An authorization with a key resolves the app before the issuer does, so both read it once.
+  const resolutions = new Map<
+    string,
+    ReturnType<typeof registerClientMetadataDocument>
+  >()
+  return {
+    id: 'origin',
+    matches: originId,
+    resolve: async (ctx, clientId, existing) => {
+      // Tempo ID fetches the origin, so a private or reserved address is refused, as a metadata
+      // document's URL is.
+      const { host, hostname } = new URL(clientId)
+      if (!isPublicRoutableHost(hostname))
+        throw new APIError('BAD_REQUEST', {
+          error: 'invalid_client',
+          error_description: `Invalid client ID: ${clientId} is not a public host. Use the app's public https origin.`,
+        })
+
+      return await (async () => {
+        if (fresh(existing)) return existing
+        const plugin = ctx.context.getPlugin('oauth-provider')
+        if (!plugin) throw new Error('The OAuth provider plugin is missing.')
+        const resolution =
+          resolutions.get(clientId) ??
+          describe({ fetch: options.fetch, origin: clientId }).then((app) =>
+            registerClientMetadataDocument(ctx, plugin.options, {
+              clientDiscoveryId: 'origin',
+              clientId,
+              ...(existing ? { existingClient: existing } : {}),
+              metadata: {
+                client_id: clientId,
+                client_name: app.name ?? host,
+                grant_types: ['authorization_code', 'refresh_token'],
+                ...(app.logo ? { logo_uri: app.logo } : {}),
+                // Better Auth matches each redirect URI exactly, so no other path on the origin, such as
+                // an open redirect, receives a code.
+                redirect_uris: app.redirectUris?.length
+                  ? [...app.redirectUris]
+                  : [`${clientId}/`],
+                response_types: ['code'],
+                token_endpoint_auth_method: 'none',
+              },
+            }),
+          )
+        resolutions.set(clientId, resolution)
+        return (await resolution).client
+      })()
+    },
+  } satisfies ClientDiscovery
+}
+
+/** The most that `describe` reads of the origin's page, and of its manifest, in bytes. */
+const pageLimit = 64 * 1024
+
+/** The largest logo that `describe` inlines, in bytes. */
+const logoLimit = 32 * 1024
+
+/** The image types that `describe` inlines as a logo. */
+const logoTypes = new Set([
+  'image/gif',
+  'image/jpeg',
+  'image/png',
+  'image/svg+xml',
+  'image/webp',
+])
+
+/**
+ * Returns the name, logo, and redirect URIs of the app at `origin`, from its manifest, else from its
+ * page. The logo is a `data:` URL, so the approval page loads nothing from the app. The reads share
+ * a 5-second limit, and a failed read returns what it found.
+ */
+async function describe(options: {
+  fetch: ClientMetadataResourceFetch
+  origin: string
+}): Promise<{
+  logo?: string | undefined
+  name?: string | undefined
+  redirectUris?: readonly string[] | undefined
+}> {
+  const { origin } = options
+  const signal = AbortSignal.timeout(5000)
+
+  const read = async (url: string, accept: string) => {
+    const response = await options.fetch(url, {
+      headers: { accept },
+      redirect: 'error',
+      signal,
+    })
+    if (response.status !== 200 || !response.body) {
+      await response.body?.cancel()
+      throw new Error(`The read of ${url} responded with ${response.status}.`)
+    }
+    // The page's head comes first, so the read keeps only the start of a longer body. A chunk can
+    // be of any size, so each one is cut to the bytes left.
+    const reader = response.body.getReader()
+    const decoder = new TextDecoder()
+    // Each read has its own budget, so a long page leaves the manifest whole.
+    let remaining = pageLimit
+    let text = ''
+    while (remaining > 0) {
+      const { done, value } = await reader.read()
+      if (done) break
+      const chunk = value.subarray(0, remaining)
+      remaining -= chunk.byteLength
+      text += decoder.decode(chunk, { stream: true })
+    }
+    await reader.cancel()
+    return text
+  }
+
+  // A URL on another origin, such as a CDN or a `data:` URL, is not the app's.
+  const own = (href: unknown, base: string) => {
+    if (typeof href !== 'string') return undefined
+    const url = URL.parse(href, base)
+    return url?.origin === origin ? url.href : undefined
+  }
+
+  const page = await read(`${origin}/`, 'text/html')
+    .then(parsePage)
+    .catch(() => undefined)
+  if (!page) return {}
+
+  // The page's links resolve against its `<base>`, as a browser resolves them.
+  const base = URL.parse(page.base ?? '', `${origin}/`)?.href ?? `${origin}/`
+  const manifestUrl = own(page.manifest, base)
+  const manifest = manifestUrl
+    ? await read(manifestUrl, 'application/manifest+json, application/json')
+        .then((text): unknown => JSON.parse(text))
+        .catch(() => undefined)
+    : undefined
+  const fields =
+    typeof manifest === 'object' && manifest !== null
+      ? (manifest as Record<string, unknown>)
+      : {}
+  const icons = Array.isArray(fields.icons)
+    ? fields.icons.flatMap((icon: unknown) => {
+        if (typeof icon !== 'object' || icon === null) return []
+        const { purpose, sizes, src } = icon as Record<string, unknown>
+        // A monochrome icon is a mask, not a logo.
+        if (typeof purpose === 'string' && !/\b(any|maskable)\b/.test(purpose))
+          return []
+        const href = manifestUrl ? own(src, manifestUrl) : undefined
+        return href ? [{ href, size: iconSize(sizes, 0) }] : []
+      })
+    : []
+  // The page's icons apply only when the manifest names none. The page shows the logo at 48 pixels,
+  // so the smallest icon of at least 96 pixels fills it on any screen, else the largest icon.
+  const candidates =
+    icons.length > 0
+      ? icons
+      : page.icons.flatMap((icon) => {
+          const href = own(icon.href, base)
+          return href ? [{ href, size: icon.size }] : []
+        })
+  const icon = candidates.reduce<{ href: string; size: number } | undefined>(
+    (best, icon) => {
+      if (!best) return icon
+      if (best.size >= 96 && icon.size >= 96)
+        return icon.size < best.size ? icon : best
+      return icon.size > best.size ? icon : best
+    },
+    undefined,
+  )
+  const logo = icon
+    ? await (async () => {
+        const response = await options.fetch(icon.href, {
+          headers: { accept: [...logoTypes].join(', ') },
+          redirect: 'error',
+          signal,
+        })
+        const type = response.headers
+          .get('content-type')
+          ?.split(';')[0]
+          ?.trim()
+          .toLowerCase()
+        if (response.status !== 200 || !type || !logoTypes.has(type)) {
+          await response.body?.cancel()
+          return undefined
+        }
+        const reader = response.body?.getReader()
+        if (!reader) return undefined
+        const chunks: Uint8Array[] = []
+        let size = 0
+        while (true) {
+          const { done, value } = await reader.read()
+          if (done) break
+          size += value.byteLength
+          // A larger logo is refused whole, since a cut image does not render.
+          if (size > logoLimit) {
+            await reader.cancel()
+            return undefined
+          }
+          chunks.push(value)
+        }
+        return `data:${type};base64,${Base64.fromBytes(Bytes.concat(...chunks))}`
+      })().catch(() => undefined)
+    : undefined
+
+  // Each redirect URI is an exact `https` URI on the origin, as a metadata document names one.
+  const redirectUris = Array.isArray(fields.redirect_uris)
+    ? fields.redirect_uris
+        .flatMap((uri: unknown) => {
+          if (typeof uri !== 'string' || uri.includes('#')) return []
+          const url = URL.parse(uri)
+          if (url?.origin !== origin || url.username || url.password) return []
+          return [url.href]
+        })
+        .slice(0, 10)
+    : undefined
+
+  const name = [fields.name, fields.short_name, page.title]
+    .map((value) =>
+      typeof value === 'string'
+        ? // Control characters and runs of spaces would break the line that the page shows, and
+          // format characters, such as bidi overrides, would reorder the host beside the name.
+          value
+            .replace(/[\p{Cc}\p{Cf}\s]+/gu, ' ')
+            .trim()
+            .slice(0, 64)
+        : '',
+    )
+    .find(Boolean)
+  return { logo, name, redirectUris }
+}
+
+/**
+ * Returns the largest dimension in an icon's `sizes`, such as 512 for `192x192 512x512`, and
+ * infinity for `any`. Without sizes, returns `fallback`.
+ */
+function iconSize(sizes: unknown, fallback: number) {
+  if (typeof sizes !== 'string' || !sizes.trim()) return fallback
+  return Math.max(
+    ...sizes
+      .toLowerCase()
+      .split(/\s+/)
+      .map((size) => {
+        if (size === 'any') return Number.POSITIVE_INFINITY
+        const [width, height] = size.split('x').map(Number)
+        return Math.max(width || 0, height || 0)
+      }),
+  )
+}
+
+/**
+ * Returns the `<base>` URL, `<title>`, manifest link, and icon links of an untrusted HTML page, with
+ * patterns that each scan in linear time.
+ */
+function parsePage(html: string) {
+  const source = html.replace(
+    /<!--[\s\S]*?(?:-->|$)|<(script|style)\b[\s\S]*?(?:<\/\1\s*>|$)/gi,
+    '',
+  )
+  const attributesOf = (tag: string) =>
+    new Map(
+      [
+        ...tag.matchAll(
+          /([^\s"'=<>/]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]*)))?/g,
+        ),
+      ].map((entry) => [
+        entry[1]!.toLowerCase(),
+        decode(entry[2] ?? entry[3] ?? entry[4] ?? ''),
+      ]),
+    )
+  const links = [...source.matchAll(/<link\b([^>]*)(?:>|$)/gi)].map((match) => {
+    const attributes = attributesOf(match[1] ?? '')
+    const rel = (attributes.get('rel') ?? '').toLowerCase().split(/\s+/)
+    return { attributes, rel }
+  })
+  const title = /<title\b[^>]*(?:>([^<]*)|$)/i.exec(source)?.[1]
+  // A browser reads the first `<base>` with an `href`.
+  const base = [...source.matchAll(/<base\b([^>]*)(?:>|$)/gi)]
+    .map((match) => attributesOf(match[1] ?? '').get('href'))
+    .find(Boolean)
+  return {
+    base,
+    icons: links.flatMap((link) => {
+      const href = link.attributes.get('href')
+      if (!href) return []
+      // An Apple touch icon without sizes is 180 pixels, larger than a favicon.
+      if (link.rel.includes('apple-touch-icon'))
+        return [{ href, size: iconSize(link.attributes.get('sizes'), 180) }]
+      if (link.rel.includes('icon'))
+        return [{ href, size: iconSize(link.attributes.get('sizes'), 0) }]
+      return []
+    }),
+    manifest: links
+      .find((link) => link.rel.includes('manifest'))
+      ?.attributes.get('href'),
+    title: title === undefined ? undefined : decode(title),
+  }
+}
+
+/** Returns `text` with its HTML character references for markup and numbers replaced. */
+function decode(text: string) {
+  const named: Record<string, string> = {
+    amp: '&',
+    apos: "'",
+    gt: '>',
+    lt: '<',
+    nbsp: ' ',
+    quot: '"',
+  }
+  return text.replace(
+    /&(#x[0-9a-f]+|#[0-9]+|[a-z]+);/gi,
+    (match, name: string) => {
+      if (!name.startsWith('#')) return named[name.toLowerCase()] ?? match
+      const code =
+        name[1]?.toLowerCase() === 'x'
+          ? Number.parseInt(name.slice(2), 16)
+          : Number.parseInt(name.slice(1), 10)
+      return code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : match
+    },
+  )
+}
+
+/** Returns the `oauth_client` row with `clientId`. Throws `NotFoundError` when no app has it. */
+async function find(db: Realm.Database, options: { clientId: string }) {
+  const [row] = await db
+    .select()
+    .from(Schema.oauthClient)
+    .where(eq(Schema.oauthClient.clientId, options.clientId))
+  if (!row) throw new NotFoundError({ clientId: options.clientId })
+  return row
+}
+
+/** Returns `clientId`. Throws `InvalidError` unless it is 8 to 64 letters, digits, `-`, or `_`. */
+function parseClientId(clientId: string) {
+  if (!/^[A-Za-z0-9_-]{8,64}$/.test(clientId))
+    throw new InvalidError(
+      `Invalid client ID: ${clientId}. Use 8 to 64 letters, digits, -, or _.`,
+    )
+  return clientId
+}
+
+/** Returns `clientSecret`. Throws `InvalidError` when it holds fewer than 32 characters. */
+function parseClientSecret(clientSecret: string) {
+  // The message leaves the secret out, since errors never hold one.
+  if (clientSecret.length < 32)
+    throw new InvalidError(
+      'Invalid client secret: fewer than 32 characters. Use a longer secret.',
+    )
+  return clientSecret
+}
+
+/** Returns `name` trimmed. Throws `InvalidError` when it is empty. */
+function parseName(name: string) {
+  const trimmed = name.trim()
+  if (!trimmed)
+    throw new InvalidError('Invalid app: the name is empty. Set a name.')
+  return trimmed
+}
+
+/** Returns `uris` as `parseRedirectUris` does, but accepts an empty list. */
+function parsePostLogoutRedirectUris(
+  uris: readonly string[],
+  options: { type: App['type'] },
+): readonly string[] {
+  if (uris.length === 0) return []
+  return parseRedirectUris(uris, options)
+}
+
+/**
+ * Returns `uris`, each named once. A web app takes `https` URIs, and a native app also a custom
+ * scheme. Loopback and `http` URIs are refused. Throws `InvalidError` for an invalid URI or none.
+ */
+function parseRedirectUris(
+  uris: readonly string[],
+  options: { type: App['type'] },
+): readonly string[] {
+  if (uris.length === 0)
+    throw new InvalidError(
+      'Invalid app: no redirect URI. Set at least one redirect URI.',
+    )
+
+  for (const uri of uris) {
+    const url = URL.parse(uri)
+    const reason = (() => {
+      if (!url) return 'is not an absolute URI'
+      // RFC 6749 §3.1.2 bars a fragment from a redirect URI.
+      if (url.hash || uri.includes('#')) return 'has a fragment'
+      if (url.username || url.password) return 'holds credentials'
+      if (url.protocol === 'https:')
+        return isLoopbackHost(url.hostname) ? 'has a loopback host' : undefined
+      if (url.protocol === 'http:') return 'uses http'
+      if (options.type === 'web') return 'is not https'
+      // Refuses reserved schemes, such as `javascript:` and `file:`, as Better Auth's registration does.
+      if (!isNativePrivateUseRedirectUri(url))
+        return 'is not a valid custom scheme'
+      return undefined
+    })()
+    if (reason)
+      throw new InvalidError(
+        `Invalid redirect URI: ${uri} ${reason}. Use an https URI${options.type === 'native' ? ', or a custom scheme such as com.example.app:/callback' : ''}.`,
+      )
+  }
+  return [...new Set(uris)]
+}
+
+/** Returns `scopes`, or the default scopes, with `tempo-id:sign` only when `sign` is set. */
+function scopesOf(options: {
+  scopes?: readonly string[] | undefined
+  sign: boolean
+}): string[] {
+  const kept = (options.scopes ?? scopes).filter((scope) => scope !== signScope)
+  return [...kept, ...(options.sign ? [signScope] : [])]
+}
+
+/** Returns a new client secret: 32 random letters, as Better Auth creates. */
+function secret() {
+  return generateRandomString(32, 'a-z', 'A-Z')
+}
+
+/** Returns the app of an `oauth_client` row. */
+function toApp(row: typeof Schema.oauthClient.$inferSelect): App {
+  return {
+    clientId: row.clientId,
+    createdAt: row.createdAt,
+    device: (row.grantTypes ?? []).includes(deviceGrant),
+    // A metadata document cannot skip consent, so a discovered client is never first-party.
+    firstParty: !row.clientDiscoveryId && row.skipConsent === true,
+    // Only an inlined logo shows, so the approval page loads nothing from a third-party origin.
+    logo: row.icon?.startsWith('data:image/') ? row.icon : null,
+    name: row.name,
+    postLogoutRedirectUris: row.postLogoutRedirectUris ?? [],
+    redirectUris: row.redirectUris,
+    secret: Boolean(row.clientSecret),
+    sign: (row.scopes ?? []).includes(signScope),
+    type: row.applicationType === 'native' ? 'native' : 'web',
+  }
+}