@tempoxyz/id 0.0.0-stage → 0.0.0

package/src/internal/Passkey.ts

@@ -0,0 +1,1052 @@
+/**
+ * Passkeys: the WebAuthn credentials users sign in with, each a row of the `keys` table linked to a
+ * user. A linked wallet.tempo passkey also owns Tempo Accounts, as the kind in `owners/Passkey.ts`
+ * lists, and signs their key authorizations over a signature challenge. A realm's `realm_passkeys` row names the relying party whose passkeys belong to it. Every
+ * challenge comes from Tempo ID, lives in Better Auth's `verification` table, and is spent once. The
+ * plugin's server-only endpoint creates a native Better Auth session once a route verifies an
+ * assertion.
+ * @module
+ */
+import type { BetterAuthPlugin } from 'better-auth'
+import { createAuthEndpoint } from 'better-auth/api'
+import { setSessionCookie } from 'better-auth/cookies'
+import { symmetricDecrypt, symmetricEncrypt } from 'better-auth/crypto'
+import { and, eq, gt, sql } from 'drizzle-orm'
+import { Base64, Hash, Hex } from 'ox'
+import { Authentication } from 'webauthx/server'
+import { z } from 'zod'
+import * as Schema from '../app/db/schema.js'
+import type * as Apps from './Apps.js'
+import * as Authorize from './Authorize.js'
+import * as ErrorResponse from './ErrorResponse.js'
+import * as KeyAuthorization from './KeyAuthorization.js'
+import * as Owner from './Owner.js'
+import type * as Realm from './Realm.js'
+
+/**
+ * The email step's link to a wallet.tempo passkey expired, or the browser holds no link cookie for it.
+ * The refusal comes before the code is checked, so the code stays valid for a sign-in without the
+ * passkey.
+ */
+export class LinkExpiredError extends ErrorResponse.define(
+  'passkey_link_expired',
+) {
+  override readonly name = 'Passkey.LinkExpiredError'
+
+  constructor() {
+    super({
+      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',
+    })
+  }
+}
+
+/**
+ * A passkey sign-in names an app, or reaches a realm, that holds no passkeys for Tempo ID, or no
+ * passkeys whose relying party covers the app's page.
+ */
+export class NotPermittedError extends ErrorResponse.define(
+  'passkey_not_permitted',
+) {
+  override readonly name = 'Passkey.NotPermittedError'
+
+  constructor(options: NotPermittedError.Options = {}) {
+    const { clientId, origin } = options
+    super(
+      (() => {
+        if (clientId && origin)
+          return {
+            error_description: `Passkey not permitted: no realm of the app ${clientId} holds passkeys for ${origin}. Sign in with an emailed code.`,
+            meta: { client_id: clientId, origin },
+          }
+        if (clientId)
+          return {
+            error_description: `Passkey not permitted: the app ${clientId} holds no passkeys. Sign in with an emailed code.`,
+            meta: { client_id: clientId },
+          }
+        return {
+          error_description:
+            'Passkey not permitted: no realm holds passkeys for this sign-in. Sign in with an emailed code.',
+        }
+      })(),
+    )
+  }
+}
+
+export declare namespace NotPermittedError {
+  type Options = {
+    /** The client ID of the app the sign-in names, if any. */
+    clientId?: string | undefined
+    /** The origin of the app's page that runs the ceremony, or absent for Tempo ID's own page. */
+    origin?: string | undefined
+  }
+}
+
+/**
+ * A passkey ceremony failed: its challenge is unknown, spent, or expired, or the response does not
+ * verify. One refusal covers every case, so it reveals neither which check failed nor whether a
+ * credential exists.
+ */
+export class WebAuthnRejectedError extends ErrorResponse.define(
+  'webauthn_rejected',
+) {
+  override readonly name = 'Passkey.WebAuthnRejectedError'
+
+  constructor() {
+    super({
+      error_description:
+        'Passkey rejected. Request new options, then try again with the same passkey or another one.',
+    })
+  }
+}
+
+/** A passkey assertion, as `webauthx/client`'s `Authentication.sign` serializes it. */
+export type Assertion = z.output<typeof schema.assertion>
+
+/** A challenge that Tempo ID issued, as `take` returns it once spent. */
+export type Challenge = {
+  /** The challenge, as hex. */
+  challenge: Hex.Hex
+  /** The client ID of the app the sign-in named, or `null` for none. */
+  clientId: string | null
+  /**
+   * The SHA-256 digest of the email step's link that the challenge confirms, as hex, or `undefined`
+   * for a sign-in challenge.
+   */
+  link: string | undefined
+  /**
+   * The origin of the app's page that the ceremony runs at, or `undefined` for Tempo ID's own page.
+   */
+  origin: string | undefined
+  /**
+   * The realm whose relying party the challenge was issued for, or `undefined` when the stored
+   * challenge names none, which skips the wallet.tempo lookup.
+   */
+  realmId: string | undefined
+  /** The relying party the challenge was issued for. */
+  rpId: string
+  /**
+   * The witness that a one-tap challenge's key authorization digest binds, or `undefined` for a
+   * random challenge.
+   */
+  witness: Hex.Hex | undefined
+}
+
+/** A row of the `keys` table. */
+export type Key = typeof Schema.keys.$inferSelect
+
+/** A verified wallet.tempo passkey that waits for an emailed code to name its user. */
+export type Link = z.output<typeof schema.link>
+
+/**
+ * A challenge for a passkey's signature of a key authorization, as `takeSignature` returns it once
+ * spent. The challenge is the key authorization's digest.
+ */
+export type SignatureChallenge = {
+  /** The address of the Tempo Account that the key acts for, lowercase. */
+  account: string
+  /** The client ID of the app that requests the key. */
+  clientId: string
+  /** The passkey that must sign. */
+  credential: Owner.Credential
+  /** The digest of the key authorization, as hex. */
+  digest: Hex.Hex
+}
+
+/** Seconds a challenge lasts. */
+export const lifetime = 5 * 60
+
+/** Seconds a deferred link lasts. */
+export const linkLifetime = 5 * 60
+
+/** The prefix of a challenge's `verification` identifier, which its hex value follows. */
+const prefix = 'passkey-challenge:'
+
+/**
+ * The prefix of a signature challenge's `verification` identifier, which {@link signatureIdentifier}
+ * completes. It differs from {@link prefix}, so a sign-in never spends a signature challenge.
+ */
+const signaturePrefix = 'passkey-signature:'
+
+/**
+ * The longest a spent signature's record lasts, in seconds: a year, the longest a headless key
+ * lasts. A redirect's key can name a much later expiry, so the record does not follow it, and each
+ * user's approvals add rows that the cleanup cron removes within the year.
+ */
+const spentLifetime = KeyAuthorization.lifetime
+
+/**
+ * The prefix of a spent signature's `verification` identifier, which the SHA-256 digest of the
+ * assertion's authenticator data and signature follows.
+ */
+const spentPrefix = 'passkey-signature-spent:'
+
+/** Zod schemas for passkey ceremonies. */
+export namespace schema {
+  const base64url = z.string().regex(/^[A-Za-z0-9_-]+$/)
+  const hex = z.templateLiteral(['0x', z.string().regex(/^[0-9a-fA-F]*$/)])
+
+  /**
+   * A credential ID in canonical unpadded base64url, of at most 1,023 bytes, as WebAuthn bounds it:
+   * 1,364 characters.
+   */
+  export const credentialId = base64url.min(1).max(1364)
+
+  /** A passkey assertion, as `webauthx/client`'s `Authentication.sign` serializes it. */
+  export const assertion = z
+    .object({
+      id: credentialId.meta({
+        description: 'The credential ID of the passkey that signed, base64url.',
+        examples: ['KEbWNCc7NgaYnUyrNeFGX9_3Y-8'],
+      }),
+      metadata: z
+        .object({
+          authenticatorData: hex.meta({
+            description:
+              'The authenticator data the passkey signed, as hex: the relying party ID hash, flags, and signature counter.',
+            examples: [
+              '0x49960de5880e8c687434170f6476605b8fe4aeb9a28632c7995cf3ba831d97630500000000',
+            ],
+          }),
+          challengeIndex: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .meta({
+              description:
+                'The character offset of `"challenge"` in `clientDataJSON`. Absent, verification searches for it.',
+              examples: [23],
+            }),
+          clientDataJSON: z
+            .string()
+            .max(4096)
+            .meta({
+              description:
+                'The client data the browser collected, as a JSON string, which holds the type, challenge, and origin.',
+              examples: [
+                '{"type":"webauthn.get","challenge":"9jEFijuhEWrM4SOW-tChJbUEHEP44VcjcJ-Bqo1fTM8","origin":"https://id.tempo.xyz","crossOrigin":false}',
+              ],
+            }),
+          typeIndex: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .meta({
+              description:
+                'The character offset of `"type"` in `clientDataJSON`. Absent, verification searches for it.',
+              examples: [1],
+            }),
+          userVerificationRequired: z
+            .boolean()
+            .optional()
+            .meta({
+              description:
+                'Whether the client required user verification. Verification ignores it and always requires user verification.',
+              examples: [true],
+            }),
+        })
+        .meta({
+          description:
+            'The signed data that verification reads with `signature`, decoded from the browser response.',
+        }),
+      raw: z
+        .object({
+          authenticatorAttachment: z
+            .string()
+            .nullable()
+            .default(null)
+            .meta({
+              description:
+                'How the authenticator attaches to the client, such as `platform` or `cross-platform`. Defaults to `null` when the browser reports none.',
+              examples: ['platform'],
+            }),
+          id: base64url.meta({
+            description:
+              'The credential ID, base64url, as the browser returns it.',
+            examples: ['KEbWNCc7NgaYnUyrNeFGX9_3Y-8'],
+          }),
+          rawId: base64url.meta({
+            description: 'The bytes of the credential ID, base64url.',
+            examples: ['KEbWNCc7NgaYnUyrNeFGX9_3Y-8'],
+          }),
+          // Verification reads the top-level `metadata` and `signature`, so other fields are dropped.
+          response: z
+            .object({
+              clientDataJSON: base64url.meta({
+                description: 'The client data JSON, base64url.',
+                examples: [
+                  'eyJ0eXBlIjoid2ViYXV0aG4uZ2V0IiwiY2hhbGxlbmdlIjoiOWpFRmlqdWhFV3JNNFNPVy10Q2hKYlVFSEVQNDRWY2pjSi1CcW8xZlRNOCIsIm9yaWdpbiI6Imh0dHBzOi8vaWQudGVtcG8ueHl6IiwiY3Jvc3NPcmlnaW4iOmZhbHNlfQ',
+                ],
+              }),
+            })
+            .meta({
+              description:
+                "The authenticator's response. Verification keeps only `clientDataJSON` and drops other fields.",
+            }),
+          type: z.string().meta({
+            description: 'The credential type.',
+            examples: ['public-key'],
+          }),
+        })
+        .meta({
+          description:
+            'The `PublicKeyCredential` that `navigator.credentials.get()` returns, serialized as JSON.',
+        }),
+      signature: hex.meta({
+        description:
+          'The P-256 signature over the authenticator data and the client data hash, as 64-byte hex: `r` then `s`.',
+        examples: [
+          '0x6c3f1e0a9b7d24f58e1c3a6b9d0f2e4a7c5b8d1e3f6a9c2b4d7e0f1a3c5b8d9e1f2a7c4b6d8e0f3a5c7b9d1e4f6a8c0b2d5e7f9a1c3b6d8e0f2a4c7b9d1e3f5a',
+        ],
+      }),
+    })
+    .meta({
+      description: 'The assertion, serialized as `webauthx/client` returns it.',
+      id: 'PasskeyAssertion',
+    })
+
+  /** The client data fields that `take` and `verify` read. */
+  export const clientData = z.object({
+    challenge: base64url,
+    crossOrigin: z.boolean().optional(),
+  })
+
+  /** A deferred link, as `seal` encrypts it. */
+  export const link = z.object({
+    address: z.string(),
+    createdAt: z.number().nullable(),
+    /** When the link expires, in seconds. */
+    expiresAt: z.number(),
+    /** The host that sealed it. Another host that shares the secret does not accept it. */
+    host: z.string(),
+    id: z.string(),
+    /** The value that the email step carries, which the emailed-code sign-in sends back. */
+    nonce: z.string(),
+    publicKey: z.templateLiteral(['0x', z.string()]),
+    rpId: z.string(),
+  })
+
+  /** A signature challenge's `verification` value. */
+  export const signature = z.object({
+    account: z.string(),
+    clientId: z.string(),
+    credential: z.object({
+      id: z.string(),
+      publicKey: hex,
+      rpId: z.string(),
+    }),
+  })
+
+  /** The passkey step, which an approval of a key for a passkey-owned account returns. */
+  export const step = z
+    .object({
+      step: z
+        .object({
+          options: z
+            .object({
+              publicKey: z
+                .object({
+                  allowCredentials: z
+                    .array(
+                      z
+                        .object({
+                          id: credentialId.meta({
+                            description:
+                              "The credential ID of the account's passkey, base64url.",
+                            examples: ['KEbWNCc7NgaYnUyrNeFGX9_3Y-8'],
+                          }),
+                          type: z.literal('public-key').meta({
+                            description: 'The credential type.',
+                          }),
+                        })
+                        .meta({
+                          description: 'The passkey that must sign.',
+                        }),
+                    )
+                    .meta({
+                      description:
+                        "The account's passkey, the only one the browser offers.",
+                    }),
+                  challenge: z.templateLiteral(['0x', z.string()]).meta({
+                    description:
+                      "The key authorization's digest, as hex. It is single-use, and expires after 5 minutes.",
+                    examples: [
+                      '0xf6310589abb21116acc6e123967ed0a125b5041c43f8e157237093e07eaa354c',
+                    ],
+                  }),
+                  rpId: z.string().meta({
+                    description:
+                      "The relying party ID of the account's passkey.",
+                    examples: ['tempo.xyz'],
+                  }),
+                  userVerification: z.literal('required').meta({
+                    description:
+                      'Every passkey signature requires user verification.',
+                  }),
+                })
+                .meta({
+                  description:
+                    'The `PublicKeyCredentialRequestOptions`, serialized with the challenge as hex.',
+                }),
+            })
+            .meta({
+              description: 'The options for `navigator.credentials.get()`.',
+            }),
+          type: z.literal('passkey').meta({
+            description:
+              'Sign the options with the passkey, then repeat the approval with `passkey: { assertion }`.',
+          }),
+        })
+        .meta({
+          description:
+            "The next step: the passkey's signature over the key authorization's digest.",
+        }),
+    })
+    .meta({
+      description:
+        'An approval that continues when the passkey signs the key authorization.',
+      id: 'PasskeyStep',
+    })
+
+  /** A challenge's `verification` value. */
+  export const value = z.object({
+    clientId: z.string().nullable(),
+    link: z.string().optional(),
+    // A challenge without an origin runs at Tempo ID's own page.
+    origin: z.string().optional(),
+    // A stored challenge can name no realm. It verifies against stored passkeys only.
+    realmId: z.string().optional(),
+    rpId: z.string(),
+    // A one-tap challenge is the digest of a key authorization with this witness.
+    witness: z.templateLiteral(['0x', z.string()]).optional(),
+  })
+}
+
+/**
+ * Issues a challenge for a sign-in at `rpId`, stores it until it expires, and returns it as hex. The
+ * challenge is random, or the digest of a key authorization for a one-tap sign-in, which stores its
+ * witness beside it.
+ */
+export async function challenge(
+  db: Realm.Database,
+  options: challenge.Options,
+) {
+  const value = (
+    options.oneTap?.digest ??
+    Hex.fromBytes(crypto.getRandomValues(new Uint8Array(32)))
+  ).toLowerCase() as Hex.Hex
+  await db.insert(Schema.verification).values({
+    expiresAt: new Date(Date.now() + lifetime * 1000),
+    id: crypto.randomUUID(),
+    identifier: prefix + value,
+    value: JSON.stringify(
+      schema.value.parse({
+        clientId: options.clientId,
+        link: options.link,
+        origin: options.origin,
+        realmId: options.realmId,
+        rpId: options.rpId,
+        witness: options.oneTap?.witness,
+      }),
+    ),
+  })
+  return value
+}
+
+export declare namespace challenge {
+  type Options = {
+    /** The client ID of the app the sign-in names, or `null` for none. */
+    clientId: string | null
+    /**
+     * The SHA-256 digest of the email step's link that the challenge confirms, as hex. Absent for a
+     * sign-in challenge.
+     */
+    link?: string | undefined
+    /**
+     * The digest of the key authorization that a one-tap sign-in signs, and the witness that the
+     * digest binds. The digest takes the place of a random challenge. Absent for a plain sign-in.
+     */
+    oneTap?:
+      | {
+          /** The key authorization's digest, as hex. */
+          digest: Hex.Hex
+          /** The witness that the digest binds. */
+          witness: Hex.Hex
+        }
+      | undefined
+    /**
+     * The origin of the app's page that the ceremony runs at. Absent for Tempo ID's own page. Only
+     * an assertion that reports it, from a request that page sends, spends the challenge.
+     */
+    origin?: string | undefined
+    /** The realm whose relying party the sign-in uses. */
+    realmId: string
+    /** The relying party ID the passkey must belong to. */
+    rpId: string
+  }
+}
+
+/**
+ * Returns why Tempo ID refuses a passkey ceremony on an app's page, or `undefined` when the page may
+ * run one. Tempo ID verifies the assertion for the page's origin, so only a first-party web app's
+ * page, at the origin of one of its redirect URIs, runs a ceremony:
+ *
+ * - A page sends the app's `client_id`, and the app must exist, be enabled, and skip consent.
+ * - A native app's request proves no app, so it signs in through an authentication sheet.
+ * - The request's `Origin` must be the origin of one of the app's redirect URIs.
+ */
+export function checkPage(
+  options: checkPage.Options,
+): ErrorResponse.Instance<typeof checkPage.errors> | undefined {
+  const { app, clientId, origin } = options
+  if (!clientId)
+    return new Authorize.InvalidOriginError({
+      error_description: `Invalid \`Origin\`: ${origin ?? 'none'}. A passkey sign-in from an app's page sends the app's \`client_id\`.`,
+      field: 'Origin',
+      ...(origin ? { meta: { origin } } : {}),
+    })
+  if (!app || !app.skipConsent)
+    return new Authorize.RejectedError({
+      description: `Passkey sign-in refused: ${clientId} is not a first-party app. Send the user to \`/oauth2/authorize\`, which offers passkey sign-in.`,
+    })
+  if (app.type === 'native')
+    return new Authorize.RejectedError({
+      description:
+        "Passkey sign-in refused: a native app's request does not prove which app sends it. Open `/oauth2/authorize` in an authentication sheet.",
+    })
+
+  const origins = app.redirectUris.flatMap((uri) => {
+    const url = URL.parse(uri)
+    return url?.protocol === 'https:' || url?.protocol === 'http:'
+      ? [url.origin]
+      : []
+  })
+  if (!origin || !origins.includes(origin))
+    return new Authorize.InvalidOriginError({
+      error_description: `Invalid \`Origin\`: ${origin ?? 'none'}. Passkey sign-in for ${clientId} must come from the origin of one of its redirect URIs.`,
+      field: 'Origin',
+      ...(origin ? { meta: { origin } } : {}),
+    })
+  return undefined
+}
+
+export namespace checkPage {
+  export type Options = {
+    /** The app that `clientId` names, or `undefined` when no enabled app has it. */
+    app: Pick<Apps.App, 'redirectUris' | 'skipConsent' | 'type'> | undefined
+    /** The client ID that the request sends, if any. */
+    clientId: string | undefined
+    /** The request's `Origin`, if any. */
+    origin: string | undefined
+  }
+
+  /** The refusals `checkPage` returns. Its return type admits no other. */
+  export const errors = [
+    Authorize.InvalidOriginError,
+    Authorize.RejectedError,
+  ] as const
+}
+
+/**
+ * Returns the passkey with the credential `id` that belongs to `rpId`, or `undefined` when Tempo ID
+ * stores none.
+ */
+export async function get(db: Realm.Database, options: get.Options) {
+  const [key] = await db
+    .select()
+    .from(Schema.keys)
+    .where(
+      and(eq(Schema.keys.id, options.id), eq(Schema.keys.rpId, options.rpId)),
+    )
+  return key
+}
+
+export declare namespace get {
+  type Options = {
+    /** The credential ID, base64url. */
+    id: string
+    /** The relying party ID the passkey must belong to. */
+    rpId: string
+  }
+}
+
+/**
+ * Stores a verified wallet.tempo passkey for `userId`, and returns the user the passkey's row names.
+ * A concurrent first sign-in of the same passkey can store the row first, so the row decides.
+ * Returns `undefined` when another passkey holds the address.
+ */
+export async function link(db: Realm.Database, options: link.Options) {
+  const { credential, id, rpId, userId } = options
+  // `TempoAccount.create` takes the same lock to claim the realm of a first account, so a link
+  // either commits before the claim, and the claim gives way to it, or after it. A link after the
+  // claim adds the passkey's account beside the created one, as a link after its creation does.
+  return await db.transaction(async (tx) => {
+    await Owner.lock(tx, { userId })
+    // The `default` realm without a row signs in with a relying party that `Realm.withDefaults`
+    // derives. The first linked passkey stores it, so the unique `rp_id` keeps another realm from
+    // taking it, and a later change to `URL` keeps the passkeys that exist. A row already stored
+    // for `default`, or for this relying party, leaves the insert without effect.
+    await tx
+      .insert(Schema.realmPasskeys)
+      .values({ realmId: 'default', rpId })
+      .onConflictDoNothing()
+    const [inserted] = await tx
+      .insert(Schema.keys)
+      .values({
+        address: credential.address.toLowerCase(),
+        ...(credential.createdAt === null
+          ? {}
+          : { createdAt: new Date(credential.createdAt) }),
+        id,
+        publicKey: credential.publicKey,
+        rpId,
+        source: 'wallet',
+        type: 'passkey',
+        userId,
+      })
+      .onConflictDoNothing()
+      .returning({ userId: Schema.keys.userId })
+    if (inserted) return inserted.userId
+
+    const existing = await get(tx, { id, rpId })
+    return existing?.userId
+  })
+}
+
+export declare namespace link {
+  type Options = {
+    /** The passkey that wallet.tempo returned, which the assertion verified. */
+    credential: {
+      /** The address that the public key derives. */
+      address: string
+      /** When wallet.tempo created the passkey, in milliseconds, or `null` when it has no time. */
+      createdAt: number | null
+      /** The uncompressed P256 public key, hex. */
+      publicKey: Hex.Hex
+    }
+    /** The credential ID, base64url. */
+    id: string
+    /** The relying party of the passkey: the `default` realm's, which wallet.tempo shares. */
+    rpId: string
+    /** The user the passkey links to. */
+    userId: string
+  }
+}
+
+/**
+ * Derives the link cookie's own key from `secret` with HKDF-SHA256, as hex. The cookie thus shares
+ * no key with anything else that `SECRET` encrypts, such as the signing keys.
+ */
+async function linkKey(secret: string) {
+  const encoder = new TextEncoder()
+  const material = await crypto.subtle.importKey(
+    'raw',
+    encoder.encode(secret),
+    'HKDF',
+    false,
+    ['deriveBits'],
+  )
+  const bits = await crypto.subtle.deriveBits(
+    {
+      hash: 'SHA-256',
+      info: encoder.encode('tempo-id:passkey-link:v1'),
+      name: 'HKDF',
+      salt: new Uint8Array(),
+    },
+    material,
+    256,
+  )
+  return Hex.fromBytes(new Uint8Array(bits))
+}
+
+/**
+ * Instantiates a passkey sign-in plugin for Better Auth. Its server-only `signInPasskey` endpoint
+ * creates a session for a user whose assertion a route verified, and sets the session cookie. Like
+ * every sign-in, it continues an app's authorization that `oauth_query` names.
+ */
+export function plugin() {
+  return {
+    endpoints: {
+      signInPasskey: createAuthEndpoint.serverOnly(
+        {
+          body: z.object({
+            oauth_query: z.string().optional(),
+            userId: z.string(),
+          }),
+          method: 'POST',
+        },
+        async (ctx) => {
+          const user = await ctx.context.internalAdapter.findUserById(
+            ctx.body.userId,
+          )
+          if (!user) throw new Error('The passkey user is missing.')
+          const session = await ctx.context.internalAdapter.createSession(
+            user.id,
+          )
+          await setSessionCookie(ctx, { session, user })
+          return ctx.json({ user: { email: user.email, id: user.id } })
+        },
+      ),
+    },
+    id: 'tempo-id-passkey',
+  } satisfies BetterAuthPlugin
+}
+
+/**
+ * Returns the first of `realms` that holds passkeys which can sign in at `origin`, and at `page`
+ * when given, with its relying party ID, or `undefined` when none can. A WebAuthn ceremony runs
+ * only at an origin whose host is the relying party ID or one of its subdomains.
+ */
+export function relyingParty(
+  realms: readonly Realm.Realm[],
+  options: relyingParty.Options,
+) {
+  const hosts = [options.origin, options.page].flatMap((origin) =>
+    origin ? [new URL(origin).hostname] : [],
+  )
+  for (const realm of realms) {
+    const rpId = realm.passkeys?.rpId
+    if (
+      rpId !== undefined &&
+      hosts.every((host) => host === rpId || host.endsWith(`.${rpId}`))
+    )
+      return { realmId: realm.id, rpId }
+  }
+  return undefined
+}
+
+export declare namespace relyingParty {
+  type Options = {
+    /** Tempo ID's own origin. */
+    origin: string
+    /**
+     * The origin of the app's page that runs the ceremony, if any. The relying party must cover it
+     * and Tempo ID's origin both, so the page shares a site with Tempo ID, and the browser sends the
+     * session cookie on the page's requests after the sign-in.
+     */
+    page?: string | undefined
+  }
+}
+
+/**
+ * Stores the digest of a key authorization as the challenge of a signature by `credential`, until it
+ * expires. Only the user with `userId` spends it, for the same account, app, and passkey.
+ */
+export async function requestSignature(
+  db: Realm.Database,
+  options: requestSignature.Options,
+) {
+  const { account, clientId, credential, digest, userId } = options
+  await db.insert(Schema.verification).values({
+    expiresAt: new Date(Date.now() + lifetime * 1000),
+    id: crypto.randomUUID(),
+    identifier: signatureIdentifier({
+      account,
+      clientId,
+      credentialId: credential.id,
+      digest,
+      userId,
+    }),
+    value: JSON.stringify(
+      schema.signature.parse({
+        account: account.toLowerCase(),
+        clientId,
+        credential,
+      }),
+    ),
+  })
+}
+
+export declare namespace requestSignature {
+  type Options = {
+    /** The address of the Tempo Account that the key acts for. */
+    account: string
+    /** The client ID of the app that requests the key. */
+    clientId: string
+    /** The passkey that must sign: the account's owner. */
+    credential: Owner.Credential
+    /** The digest of the key authorization, as hex. */
+    digest: Hex.Hex
+    /** The signed-in user's ID. */
+    userId: string
+  }
+}
+
+/**
+ * Encrypts a deferred link with a key derived from `secret`, for the link cookie. The cookie cannot
+ * be read, changed, or forged without the secret.
+ */
+export async function seal(value: Link, options: seal.Options) {
+  return await symmetricEncrypt({
+    data: JSON.stringify(schema.link.parse(value)),
+    key: await linkKey(options.secret),
+  })
+}
+
+export declare namespace seal {
+  type Options = {
+    /** The `SECRET` variable. */
+    secret: string
+  }
+}
+
+/**
+ * Spends the challenge that `clientDataJSON` names, and returns it, or `undefined` when it is
+ * unknown, spent, or expired. One statement deletes and returns the row, so two concurrent
+ * assertions over one challenge cannot both spend it.
+ */
+export async function take(
+  db: Realm.Database,
+  options: take.Options,
+): Promise<Challenge | undefined> {
+  const challenge = (() => {
+    try {
+      const data = schema.clientData.parse(JSON.parse(options.clientDataJSON))
+      return Base64.toHex(data.challenge)
+    } catch {
+      return undefined
+    }
+  })()
+  if (!challenge) return undefined
+
+  const [row] = await db
+    .delete(Schema.verification)
+    .where(
+      and(
+        eq(Schema.verification.identifier, prefix + challenge.toLowerCase()),
+        gt(Schema.verification.expiresAt, new Date()),
+      ),
+    )
+    .returning({ value: Schema.verification.value })
+  if (!row) return undefined
+
+  const value = schema.value.parse(JSON.parse(row.value))
+  return {
+    challenge,
+    clientId: value.clientId,
+    link: value.link,
+    origin: value.origin,
+    realmId: value.realmId,
+    rpId: value.rpId,
+    witness: value.witness,
+  }
+}
+
+export declare namespace take {
+  type Options = {
+    /** The assertion's client data, as the JSON string the browser collected. */
+    clientDataJSON: string
+  }
+}
+
+/**
+ * Spends the signature challenge that `clientDataJSON` names, for the user, app, account, and
+ * passkey of `options`, and returns it, or `undefined` when it is unknown, spent, or expired. One
+ * statement deletes and returns the rows, so two concurrent assertions over one challenge cannot
+ * both spend it, and an approval for another app, account, or passkey spends none of its rows.
+ *
+ * Returns the challenge only when `verify` accepts it with the assertion. Every step for the same
+ * key issues the same digest, so the transaction then records the assertion as spent until
+ * `expiry`, for a year at most, and returns `undefined` for an assertion that it recorded before. A captured assertion
+ * thus signs no second approval, and an assertion that does not verify leaves no record.
+ */
+export async function takeSignature(
+  db: Realm.Database,
+  options: takeSignature.Options,
+): Promise<SignatureChallenge | undefined> {
+  const digest = (() => {
+    try {
+      const data = schema.clientData.parse(JSON.parse(options.clientDataJSON))
+      return Base64.toHex(data.challenge)
+    } catch {
+      return undefined
+    }
+  })()
+  if (!digest) return undefined
+
+  const spent =
+    spentPrefix +
+    Hash.sha256(Hex.concat(options.authenticatorData, options.signature))
+
+  return await db.transaction(async (tx) => {
+    // The lock serializes requests with one assertion, so only the first records it.
+    await tx.execute(
+      sql`select pg_advisory_xact_lock(hashtextextended(${spent}, 0))`,
+    )
+    const [used] = await tx
+      .select({ id: Schema.verification.id })
+      .from(Schema.verification)
+      .where(
+        and(
+          eq(Schema.verification.identifier, spent),
+          gt(Schema.verification.expiresAt, new Date()),
+        ),
+      )
+
+    // Each approval of one request issues the same digest, so every row that it names is spent.
+    // A replayed assertion spends the challenge too, so the step must run again.
+    const [row] = await tx
+      .delete(Schema.verification)
+      .where(
+        and(
+          eq(
+            Schema.verification.identifier,
+            signatureIdentifier({ ...options, digest }),
+          ),
+          gt(Schema.verification.expiresAt, new Date()),
+        ),
+      )
+      .returning({ value: Schema.verification.value })
+    if (!row || used) return undefined
+    const value = { ...schema.signature.parse(JSON.parse(row.value)), digest }
+    if (!options.verify(value)) return undefined
+
+    // A signed request with the same key can reach a new step until the key expires.
+    await tx.insert(Schema.verification).values({
+      expiresAt: new Date(
+        Math.min(
+          Math.max(options.expiry * 1000, Date.now() + lifetime * 1000),
+          Date.now() + spentLifetime * 1000,
+        ),
+      ),
+      id: crypto.randomUUID(),
+      identifier: spent,
+      value: '{}',
+    })
+    return value
+  })
+}
+
+export declare namespace takeSignature {
+  type Options = {
+    /** The address of the Tempo Account that the key acts for. */
+    account: string
+    /** The assertion's authenticator data, as hex. */
+    authenticatorData: Hex.Hex
+    /** The client ID of the app that requests the key. */
+    clientId: string
+    /** The assertion's client data, as the JSON string the browser collected. */
+    clientDataJSON: string
+    /** The credential ID of the passkey that signed, base64url. */
+    credentialId: string
+    /**
+     * When the key expires, in Unix seconds. The spent assertion stays recorded until then, for a
+     * year at most.
+     */
+    expiry: number
+    /** The assertion's signature, as hex. */
+    signature: Hex.Hex
+    /** The signed-in user's ID. */
+    userId: string
+    /**
+     * Returns whether the assertion verifies over the spent challenge, for the account, app, and
+     * passkey that it names. It runs in the transaction, so it performs no I/O.
+     */
+    verify: (challenge: SignatureChallenge) => boolean
+  }
+}
+
+/**
+ * Returns the `verification` identifier of a signature challenge, which names its user, app,
+ * account, passkey, and digest. JSON keeps each value apart, whatever characters it holds.
+ */
+function signatureIdentifier(options: signatureIdentifier.Options) {
+  return (
+    signaturePrefix +
+    JSON.stringify([
+      options.userId,
+      options.clientId,
+      options.account.toLowerCase(),
+      options.credentialId,
+      options.digest.toLowerCase(),
+    ])
+  )
+}
+
+declare namespace signatureIdentifier {
+  type Options = {
+    /** The address of the Tempo Account that the key acts for. */
+    account: string
+    /** The client ID of the app that requests the key. */
+    clientId: string
+    /** The credential ID of the passkey that signs, base64url. */
+    credentialId: string
+    /** The digest of the key authorization, as hex. */
+    digest: Hex.Hex
+    /** The signed-in user's ID. */
+    userId: string
+  }
+}
+
+/**
+ * Decrypts the link cookie's value, and returns the deferred link, or `undefined` when the value
+ * does not decrypt with `secret`, has another shape, came from another host, or expired.
+ */
+export async function unseal(sealed: string, options: unseal.Options) {
+  const value = await symmetricDecrypt({
+    data: sealed,
+    key: await linkKey(options.secret),
+  })
+    .then((data) => schema.link.safeParse(JSON.parse(data)))
+    .catch(() => undefined)
+  if (!value?.success) return undefined
+  if (value.data.host !== options.host) return undefined
+  if (value.data.expiresAt <= Date.now() / 1000) return undefined
+  return value.data
+}
+
+export declare namespace unseal {
+  type Options = {
+    /** The host that serves the request, which must be the one that sealed the link. */
+    host: string
+    /** The `SECRET` variable. */
+    secret: string
+  }
+}
+
+/**
+ * Returns whether `assertion` signs `challenge` with `publicKey`, at `origin`, for `rpId`, with the
+ * user present and verified, outside a cross-origin iframe. The client cannot waive user
+ * verification.
+ */
+export function verify(assertion: Assertion, options: verify.Options) {
+  try {
+    // WebAuthn verification leaves `crossOrigin` to the relying party. A frame on another site
+    // could otherwise run the ceremony for Tempo ID's origin.
+    const data = schema.clientData.parse(
+      JSON.parse(assertion.metadata.clientDataJSON),
+    )
+    if (data.crossOrigin) return false
+
+    return Authentication.verify(
+      {
+        ...assertion,
+        metadata: { ...assertion.metadata, userVerificationRequired: true },
+      },
+      {
+        challenge: options.challenge,
+        origin: options.origin,
+        publicKey: options.publicKey,
+        rpId: options.rpId,
+      },
+    )
+  } catch {
+    return false
+  }
+}
+
+export declare namespace verify {
+  type Options = {
+    /** The challenge that Tempo ID issued, as hex. */
+    challenge: Hex.Hex
+    /** The origin the ceremony must report: Tempo ID's own, or the app's page that the challenge names. */
+    origin: string
+    /** The passkey's uncompressed P256 public key, hex. */
+    publicKey: Hex.Hex
+    /** The relying party ID the challenge was issued for. */
+    rpId: string
+  }
+}