@tenderprompt/accounts 0.2.0

package/templates/shopify-customer-account/apps/gateway/src/platform/customer-auth/session-store.ts

@@ -0,0 +1,864 @@
+const FLOW_MAX_TTL_SECONDS = 10 * 60;
+const HANDOFF_MAX_TTL_SECONDS = 5 * 60;
+const SESSION_MAX_TTL_SECONDS = 31 * 24 * 60 * 60;
+const EXPIRED_STATE_DELETE_LIMIT = 256;
+const DEFAULT_MAX_RECENT_AUTHORIZATION_ATTEMPTS_PER_PROJECT = 512;
+const DEFAULT_MAX_RECENT_AUTHORIZATION_ATTEMPTS_PER_CLIENT = 20;
+const MAX_CONFIGURED_AUTHORIZATION_ATTEMPTS = 100_000;
+const OPAQUE_VALUE_BYTES = 32;
+const SESSION_DATA_MAX_LENGTH = 65_536;
+const SESSION_SEAL_MAX_LENGTH = 100_000;
+
+type CustomerAuthD1Value = string | number | null;
+
+export interface CustomerAuthD1Result {
+  success?: boolean;
+  meta?: { changes?: number };
+}
+
+export interface CustomerAuthD1BoundStatement {
+  first<T = Record<string, unknown>>(): Promise<T | null>;
+  run(): Promise<CustomerAuthD1Result>;
+}
+
+export interface CustomerAuthD1PreparedStatement {
+  bind(...values: CustomerAuthD1Value[]): CustomerAuthD1BoundStatement;
+}
+
+export interface CustomerAuthD1Database {
+  prepare(sql: string): CustomerAuthD1PreparedStatement;
+  batch(statements: CustomerAuthD1BoundStatement[]): Promise<CustomerAuthD1Result[]>;
+}
+
+export type CustomerAuthHostnamePolicy = (input: {
+  projectId: string;
+  hostname: string;
+}) => boolean | Promise<boolean>;
+
+export class CustomerAuthFlowCapacityError extends Error {
+  constructor() {
+    super("The customer authentication flow capacity has been reached.");
+  }
+}
+
+export interface ConsumedAuthorizationFlow {
+  pkceVerifier: string;
+  returnHostname: string;
+  interactionMode: "interactive" | "silent";
+  expiresAt: number;
+}
+
+export interface ConsumedCustomerAuthHandoff {
+  sessionId: string;
+  returnHostname: string;
+  expiresAt: number;
+}
+
+export interface StoredShopperSession {
+  sessionData: string;
+  audienceHostname: string;
+  expiresAt: number;
+}
+
+export class PublicCustomerAuthSessionStore {
+  private readonly database: CustomerAuthD1Database;
+  private readonly hostnamePolicy: CustomerAuthHostnamePolicy;
+  private readonly maxRecentAuthorizationAttemptsPerProject: number;
+  private readonly maxRecentAuthorizationAttemptsPerClient: number;
+
+  constructor(
+    database: CustomerAuthD1Database,
+    hostnamePolicy: CustomerAuthHostnamePolicy,
+    options: {
+      maxRecentAuthorizationAttemptsPerProject?: number;
+      maxRecentAuthorizationAttemptsPerClient?: number;
+    } = {},
+  ) {
+    if (typeof hostnamePolicy !== "function") {
+      throw new Error("A customer authentication hostname policy is required.");
+    }
+    this.database = database;
+    this.hostnamePolicy = hostnamePolicy;
+    const maxRecentAuthorizationAttemptsPerProject = options.maxRecentAuthorizationAttemptsPerProject
+      ?? DEFAULT_MAX_RECENT_AUTHORIZATION_ATTEMPTS_PER_PROJECT;
+    const maxRecentAuthorizationAttemptsPerClient = options.maxRecentAuthorizationAttemptsPerClient
+      ?? DEFAULT_MAX_RECENT_AUTHORIZATION_ATTEMPTS_PER_CLIENT;
+    if (!validAuthorizationAttemptLimit(maxRecentAuthorizationAttemptsPerProject)
+        || !validAuthorizationAttemptLimit(maxRecentAuthorizationAttemptsPerClient)
+        || maxRecentAuthorizationAttemptsPerClient > maxRecentAuthorizationAttemptsPerProject) {
+      throw new Error("The customer authentication flow capacity is invalid.");
+    }
+    this.maxRecentAuthorizationAttemptsPerProject = maxRecentAuthorizationAttemptsPerProject;
+    this.maxRecentAuthorizationAttemptsPerClient = maxRecentAuthorizationAttemptsPerClient;
+  }
+
+  async createAuthorizationFlow(input: {
+    projectId: string;
+    pkceVerifier: string;
+    returnHostname: string;
+    clientKey: string;
+    interactionMode?: "interactive" | "silent";
+    ttlSeconds: number;
+    nowSeconds?: number;
+  }): Promise<{
+    state: string;
+    browserBinding: string;
+    returnHostname: string;
+    expiresAt: number;
+  }> {
+    const projectId = requiredProjectId(input.projectId);
+    const pkceVerifier = requiredPkceVerifier(input.pkceVerifier);
+    const returnHostname = normalizedHostname(input.returnHostname);
+    const clientKey = requiredClientKey(input.clientKey);
+    const interactionMode = requiredInteractionMode(input.interactionMode ?? "interactive");
+    const timing = expiration(input.nowSeconds, input.ttlSeconds, FLOW_MAX_TTL_SECONDS, "authorization flow");
+    await this.requireAllowedHostname(projectId, returnHostname);
+    await this.deleteExpiredState({ projectId, nowSeconds: timing.createdAt });
+    const state = randomOpaqueValue();
+    const browserBinding = randomOpaqueValue();
+    const stateDigest = await opaqueDigest(state);
+    const browserBindingDigest = await opaqueDigest(browserBinding);
+    const clientKeyDigest = await opaqueDigest(clientKey);
+    const result = await this.database.prepare(
+      `INSERT INTO public_customer_auth_flows (
+        project_id, state_digest, browser_binding_digest, client_key_digest, interaction_mode,
+        pkce_verifier, return_hostname, created_at, expires_at
+      )
+      SELECT ?, ?, ?, ?, ?, ?, ?, ?, ?
+      WHERE (
+        SELECT COUNT(*) FROM public_customer_auth_flows
+        WHERE project_id = ? AND expires_at > ?
+      ) < ?
+        AND (
+          SELECT COUNT(*) FROM public_customer_auth_flows
+          WHERE project_id = ? AND client_key_digest = ? AND expires_at > ?
+        ) < ?`,
+    ).bind(
+      projectId,
+      stateDigest,
+      browserBindingDigest,
+      clientKeyDigest,
+      interactionMode,
+      pkceVerifier,
+      returnHostname,
+      timing.createdAt,
+      timing.expiresAt,
+      projectId,
+      timing.createdAt,
+      this.maxRecentAuthorizationAttemptsPerProject,
+      projectId,
+      clientKeyDigest,
+      timing.createdAt,
+      this.maxRecentAuthorizationAttemptsPerClient,
+    ).run();
+    if (result.success === false) {
+      throw new Error("The customer authentication state was not stored.");
+    }
+    if (result.meta?.changes === 0) throw new CustomerAuthFlowCapacityError();
+    if (result.meta?.changes !== 1) {
+      throw new Error("The customer authentication state was not stored.");
+    }
+    return { state, browserBinding, returnHostname, expiresAt: timing.expiresAt };
+  }
+
+  async consumeAuthorizationFlow(input: {
+    projectId: string;
+    state: string;
+    browserBinding: string;
+    nowSeconds?: number;
+  }): Promise<ConsumedAuthorizationFlow | null> {
+    const projectId = requiredProjectId(input.projectId);
+    const stateDigest = await opaqueDigest(requiredOpaqueValue(input.state, "authorization state"));
+    const browserBindingDigest = await opaqueDigest(
+      requiredOpaqueValue(input.browserBinding, "authorization browser binding"),
+    );
+    const now = requiredNow(input.nowSeconds);
+    const row = await this.database.prepare(
+      `UPDATE public_customer_auth_flows
+       SET consumed_at = ?
+       WHERE project_id = ? AND state_digest = ? AND browser_binding_digest = ?
+         AND consumed_at IS NULL AND expires_at > ?
+       RETURNING pkce_verifier, return_hostname, interaction_mode, expires_at`,
+    ).bind(now, projectId, stateDigest, browserBindingDigest, now).first<AuthorizationFlowRow>();
+    if (!row) return null;
+    return {
+      pkceVerifier: requiredPkceVerifier(row.pkce_verifier),
+      returnHostname: normalizedHostname(row.return_hostname),
+      interactionMode: requiredInteractionMode(row.interaction_mode),
+      expiresAt: requiredExpiry(row.expires_at, now),
+    };
+  }
+
+  async createShopperSessionHandoff(input: {
+    projectId: string;
+    returnHostname: string;
+    sessionData: string;
+    sessionTtlSeconds: number;
+    handoffTtlSeconds: number;
+    nowSeconds?: number;
+  }): Promise<{ handoff: string; returnHostname: string; expiresAt: number }> {
+    const projectId = requiredProjectId(input.projectId);
+    const returnHostname = normalizedHostname(input.returnHostname);
+    const sessionData = requiredSessionData(input.sessionData);
+    const now = requiredNow(input.nowSeconds);
+    const timing = expiration(now, input.handoffTtlSeconds, HANDOFF_MAX_TTL_SECONDS, "handoff");
+    const sessionTiming = expiration(now, input.sessionTtlSeconds, SESSION_MAX_TTL_SECONDS, "shopper session");
+    if (input.handoffTtlSeconds > input.sessionTtlSeconds) {
+      throw new Error("The handoff cannot outlive its shopper session.");
+    }
+    await this.requireAllowedHostname(projectId, returnHostname);
+    await this.deleteExpiredState({ projectId, nowSeconds: now });
+    const sessionId = randomOpaqueValue();
+    const sessionDigest = await opaqueDigest(sessionId);
+    const handoff = randomOpaqueValue();
+    const handoffDigest = await opaqueDigest(handoff);
+    const sessionSeal = await sealPendingSessionPayload({
+      sessionId,
+      sessionExpiresAt: sessionTiming.expiresAt,
+      sessionData,
+      handoff,
+      projectId,
+      returnHostname,
+      handoffDigest,
+    });
+    await requireInsert(this.database.prepare(
+      `INSERT INTO public_customer_auth_handoffs (
+        project_id, handoff_digest, return_hostname, session_digest, session_seal, created_at, expires_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?)`,
+    ).bind(
+      projectId,
+      handoffDigest,
+      returnHostname,
+      sessionDigest,
+      sessionSeal,
+      timing.createdAt,
+      timing.expiresAt,
+    ));
+    return { handoff, returnHostname, expiresAt: timing.expiresAt };
+  }
+
+  async consumeHandoff(input: {
+    projectId: string;
+    handoff: string;
+    requestHostname: string;
+    nowSeconds?: number;
+  }): Promise<ConsumedCustomerAuthHandoff | null> {
+    const projectId = requiredProjectId(input.projectId);
+    const handoff = requiredOpaqueValue(input.handoff, "handoff");
+    const handoffDigest = await opaqueDigest(handoff);
+    const requestHostname = normalizedHostname(input.requestHostname);
+    const now = requiredNow(input.nowSeconds);
+    const readHandoff = () => this.database.prepare(
+      `SELECT session_seal, session_digest, return_hostname, expires_at, claimed_at
+       FROM public_customer_auth_handoffs
+       WHERE project_id = ? AND handoff_digest = ? AND return_hostname = ? AND expires_at > ?`,
+    ).bind(projectId, handoffDigest, requestHostname, now).first<HandoffRow>();
+    const row = await readHandoff();
+    if (!row) return null;
+    const returnHostname = normalizedHostname(row.return_hostname);
+    const handoffExpiresAt = requiredExpiry(row.expires_at, now);
+    const sessionDigest = requiredDigest(row.session_digest, "shopper session");
+    const sessionSeal = requiredSessionSeal(row.session_seal);
+    const claimedAt = optionalClaimedAt(row.claimed_at, now);
+    if (claimedAt !== null) {
+      return this.readClaimedHandoff({
+        projectId,
+        handoff,
+        handoffDigest,
+        requestHostname,
+        handoffExpiresAt,
+        sessionDigest,
+        sessionSeal,
+        now,
+      });
+    }
+    const payload = await unsealPendingSessionPayload({
+      sessionSeal,
+      handoff,
+      projectId,
+      returnHostname,
+      handoffDigest,
+    });
+    if (await opaqueDigest(payload.sessionId) !== sessionDigest) {
+      throw new Error("The customer authentication handoff is invalid.");
+    }
+    const sessionExpiresAt = requiredExpiry(payload.sessionExpiresAt, now);
+    const claimedSeal = await sealClaimedSessionId({
+      sessionId: payload.sessionId,
+      handoff,
+      projectId,
+      returnHostname,
+      handoffDigest,
+    });
+    const [claimResult, insertResult] = await this.database.batch([
+      this.database.prepare(
+        `UPDATE public_customer_auth_handoffs
+         SET claimed_at = ?, session_seal = ?
+         WHERE project_id = ? AND handoff_digest = ? AND return_hostname = ?
+           AND expires_at > ? AND claimed_at IS NULL AND session_digest = ? AND session_seal = ?`,
+      ).bind(
+        now,
+        claimedSeal,
+        projectId,
+        handoffDigest,
+        returnHostname,
+        now,
+        sessionDigest,
+        sessionSeal,
+      ),
+      this.database.prepare(
+        `INSERT INTO public_customer_auth_sessions (
+          project_id, session_digest, audience_hostname, session_data, created_at, expires_at
+        )
+        SELECT ?, ?, ?, ?, ?, ?
+        WHERE EXISTS (
+          SELECT 1 FROM public_customer_auth_handoffs
+          WHERE project_id = ? AND handoff_digest = ? AND return_hostname = ?
+            AND expires_at > ? AND claimed_at = ? AND session_digest = ? AND session_seal = ?
+        )`,
+      ).bind(
+        projectId,
+        sessionDigest,
+        returnHostname,
+        payload.sessionData,
+        now,
+        sessionExpiresAt,
+        projectId,
+        handoffDigest,
+        returnHostname,
+        now,
+        now,
+        sessionDigest,
+        claimedSeal,
+      ),
+    ]);
+    if (!claimResult || !insertResult || claimResult.success === false || insertResult.success === false) {
+      throw new Error("The customer authentication handoff could not be consumed.");
+    }
+    const claimed = claimResult.meta?.changes ?? 0;
+    const inserted = insertResult.meta?.changes ?? 0;
+    if (claimed === 0 && inserted === 0) {
+      const racedRow = await readHandoff();
+      if (!racedRow || optionalClaimedAt(racedRow.claimed_at, now) === null) {
+        throw new Error("The customer authentication handoff could not be consumed.");
+      }
+      return this.readClaimedHandoff({
+        projectId,
+        handoff,
+        handoffDigest,
+        requestHostname,
+        handoffExpiresAt: requiredExpiry(racedRow.expires_at, now),
+        sessionDigest: requiredDigest(racedRow.session_digest, "shopper session"),
+        sessionSeal: requiredSessionSeal(racedRow.session_seal),
+        now,
+      });
+    }
+    if (claimed !== 1 || inserted !== 1) {
+      throw new Error("The customer authentication handoff could not be consumed.");
+    }
+    return {
+      sessionId: payload.sessionId,
+      returnHostname,
+      expiresAt: handoffExpiresAt,
+    };
+  }
+
+  private async readClaimedHandoff(input: {
+    projectId: string;
+    handoff: string;
+    handoffDigest: string;
+    requestHostname: string;
+    handoffExpiresAt: number;
+    sessionDigest: string;
+    sessionSeal: string;
+    now: number;
+  }): Promise<ConsumedCustomerAuthHandoff> {
+    const sessionId = await unsealClaimedSessionId({
+      sessionSeal: input.sessionSeal,
+      handoff: input.handoff,
+      projectId: input.projectId,
+      returnHostname: input.requestHostname,
+      handoffDigest: input.handoffDigest,
+    });
+    if (await opaqueDigest(sessionId) !== input.sessionDigest) {
+      throw new Error("The customer authentication handoff is invalid.");
+    }
+    const session = await this.database.prepare(
+      `SELECT expires_at FROM public_customer_auth_sessions
+       WHERE project_id = ? AND session_digest = ? AND audience_hostname = ? AND expires_at > ?`,
+    ).bind(
+      input.projectId,
+      input.sessionDigest,
+      input.requestHostname,
+      input.now,
+    ).first<{ expires_at: unknown }>();
+    if (!session) throw new Error("The customer authentication handoff is invalid.");
+    requiredExpiry(session.expires_at, input.now);
+    return {
+      sessionId,
+      returnHostname: input.requestHostname,
+      expiresAt: input.handoffExpiresAt,
+    };
+  }
+
+  async createShopperSession(input: {
+    projectId: string;
+    audienceHostname: string;
+    sessionData: string;
+    ttlSeconds: number;
+    nowSeconds?: number;
+  }): Promise<{ sessionId: string; audienceHostname: string; expiresAt: number }> {
+    const projectId = requiredProjectId(input.projectId);
+    const audienceHostname = normalizedHostname(input.audienceHostname);
+    const sessionData = requiredSessionData(input.sessionData);
+    const timing = expiration(input.nowSeconds, input.ttlSeconds, SESSION_MAX_TTL_SECONDS, "shopper session");
+    await this.requireAllowedHostname(projectId, audienceHostname);
+    await this.deleteExpiredState({ projectId, nowSeconds: timing.createdAt });
+    return this.insertShopperSession({
+      projectId,
+      audienceHostname,
+      sessionData,
+      timing,
+    });
+  }
+
+  async deleteExpiredState(input: {
+    projectId: string;
+    nowSeconds?: number;
+  }): Promise<{ flows: number; handoffs: number; sessions: number }> {
+    const projectId = requiredProjectId(input.projectId);
+    const now = requiredNow(input.nowSeconds);
+    const deleted: Record<"flows" | "handoffs" | "sessions", number> = {
+      flows: 0,
+      handoffs: 0,
+      sessions: 0,
+    };
+    for (const [key, table] of [
+      ["flows", "public_customer_auth_flows"],
+      ["handoffs", "public_customer_auth_handoffs"],
+      ["sessions", "public_customer_auth_sessions"],
+    ] as const) {
+      const statement = this.database.prepare(
+        `DELETE FROM ${table}
+         WHERE rowid IN (
+           SELECT rowid FROM ${table}
+           WHERE project_id = ? AND expires_at <= ?
+           ORDER BY expires_at
+           LIMIT ?
+         )`,
+      ).bind(projectId, now, EXPIRED_STATE_DELETE_LIMIT);
+      const result = await statement.run();
+      if (result.success === false) {
+        throw new Error("Expired customer authentication state could not be deleted.");
+      }
+      deleted[key] = result.meta?.changes ?? 0;
+    }
+    return deleted;
+  }
+
+  /**
+   * Bounded maintenance entry point. Opportunistic request cleanup is enough
+   * for the first proof; a future trusted first-party scheduler can invoke a
+   * protected merchant route to drain inactive projects. A User Worker
+   * `scheduled` export is not itself a trigger in a dispatch namespace.
+   */
+  async runScheduledCleanup(input: {
+    projectId: string;
+    nowSeconds?: number;
+    maxBatches?: number;
+  }): Promise<{
+    flows: number;
+    handoffs: number;
+    sessions: number;
+    batches: number;
+    mayHaveMore: boolean;
+  }> {
+    const maxBatches = input.maxBatches ?? 4;
+    if (!Number.isSafeInteger(maxBatches) || maxBatches < 1 || maxBatches > 16) {
+      throw new Error("The scheduled customer authentication cleanup bound is invalid.");
+    }
+    const total = { flows: 0, handoffs: 0, sessions: 0 };
+    let batches = 0;
+    let mayHaveMore = false;
+    while (batches < maxBatches) {
+      const deleted = await this.deleteExpiredState({
+        projectId: input.projectId,
+        nowSeconds: input.nowSeconds,
+      });
+      batches += 1;
+      total.flows += deleted.flows;
+      total.handoffs += deleted.handoffs;
+      total.sessions += deleted.sessions;
+      mayHaveMore = Object.values(deleted).some((count) => count === EXPIRED_STATE_DELETE_LIMIT);
+      if (!mayHaveMore) break;
+    }
+    return { ...total, batches, mayHaveMore };
+  }
+
+  private async insertShopperSession(input: {
+    projectId: string;
+    audienceHostname: string;
+    sessionData: string;
+    timing: { createdAt: number; expiresAt: number };
+    sessionId?: string;
+  }): Promise<{ sessionId: string; audienceHostname: string; expiresAt: number }> {
+    const sessionId = input.sessionId === undefined
+      ? randomOpaqueValue()
+      : requiredOpaqueValue(input.sessionId, "shopper session");
+    const sessionDigest = await opaqueDigest(sessionId);
+    await requireInsert(this.database.prepare(
+      `INSERT INTO public_customer_auth_sessions (
+        project_id, session_digest, audience_hostname, session_data, created_at, expires_at
+      ) VALUES (?, ?, ?, ?, ?, ?)`,
+    ).bind(
+      input.projectId,
+      sessionDigest,
+      input.audienceHostname,
+      input.sessionData,
+      input.timing.createdAt,
+      input.timing.expiresAt,
+    ));
+    return {
+      sessionId,
+      audienceHostname: input.audienceHostname,
+      expiresAt: input.timing.expiresAt,
+    };
+  }
+
+  async readShopperSession(input: {
+    projectId: string;
+    sessionId: string;
+    requestHostname: string;
+    nowSeconds?: number;
+  }): Promise<StoredShopperSession | null> {
+    const projectId = requiredProjectId(input.projectId);
+    const sessionDigest = await opaqueDigest(requiredOpaqueValue(input.sessionId, "shopper session"));
+    const requestHostname = normalizedHostname(input.requestHostname);
+    const now = requiredNow(input.nowSeconds);
+    const row = await this.database.prepare(
+      `SELECT session_data, audience_hostname, expires_at
+       FROM public_customer_auth_sessions
+       WHERE project_id = ? AND session_digest = ? AND audience_hostname = ?
+         AND expires_at > ?`,
+    ).bind(projectId, sessionDigest, requestHostname, now).first<SessionRow>();
+    if (!row) return null;
+    return {
+      sessionData: requiredSessionData(row.session_data),
+      audienceHostname: normalizedHostname(row.audience_hostname),
+      expiresAt: requiredExpiry(row.expires_at, now),
+    };
+  }
+
+  async deleteShopperSession(input: {
+    projectId: string;
+    sessionId: string;
+    requestHostname: string;
+  }): Promise<boolean> {
+    const projectId = requiredProjectId(input.projectId);
+    const sessionDigest = await opaqueDigest(requiredOpaqueValue(input.sessionId, "shopper session"));
+    const requestHostname = normalizedHostname(input.requestHostname);
+    const result = await this.database.prepare(
+      `DELETE FROM public_customer_auth_sessions
+       WHERE project_id = ? AND session_digest = ? AND audience_hostname = ?`,
+    ).bind(projectId, sessionDigest, requestHostname).run();
+    if (result.success === false) throw new Error("The shopper session deletion failed.");
+    return result.meta?.changes === 1;
+  }
+
+  private async requireAllowedHostname(projectId: string, hostname: string): Promise<void> {
+    let allowed = false;
+    try {
+      allowed = await this.hostnamePolicy({ projectId, hostname });
+    } catch {
+      throw new Error("The customer authentication hostname is not allowed for this project.");
+    }
+    if (allowed !== true) {
+      throw new Error("The customer authentication hostname is not allowed for this project.");
+    }
+  }
+}
+
+interface AuthorizationFlowRow {
+  pkce_verifier: unknown;
+  return_hostname: unknown;
+  interaction_mode: unknown;
+  expires_at: unknown;
+}
+
+interface HandoffRow {
+  session_seal: unknown;
+  session_digest: unknown;
+  return_hostname: unknown;
+  expires_at: unknown;
+  claimed_at: unknown;
+}
+
+interface SessionRow {
+  session_data: unknown;
+  audience_hostname: unknown;
+  expires_at: unknown;
+}
+
+async function requireInsert(statement: CustomerAuthD1BoundStatement): Promise<void> {
+  const result = await statement.run();
+  if (result.success === false || (result.meta?.changes !== undefined && result.meta.changes !== 1)) {
+    throw new Error("The customer authentication state was not stored.");
+  }
+}
+
+function expiration(
+  nowSeconds: number | undefined,
+  ttlSeconds: number,
+  maximumTtlSeconds: number,
+  label: string,
+): { createdAt: number; expiresAt: number } {
+  const createdAt = requiredNow(nowSeconds);
+  if (!Number.isSafeInteger(ttlSeconds) || ttlSeconds < 1 || ttlSeconds > maximumTtlSeconds) {
+    throw new Error(`The ${label} lifetime is invalid.`);
+  }
+  return { createdAt, expiresAt: createdAt + ttlSeconds };
+}
+
+function requiredNow(value: number | undefined): number {
+  const now = value ?? Math.floor(Date.now() / 1000);
+  if (!Number.isSafeInteger(now) || now < 0) throw new Error("The current time is invalid.");
+  return now;
+}
+
+function requiredExpiry(value: unknown, now: number): number {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= now) {
+    throw new Error("The stored expiration is invalid.");
+  }
+  return value;
+}
+
+function optionalClaimedAt(value: unknown, now: number): number | null {
+  if (value === null) return null;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0 || value > now) {
+    throw new Error("The customer authentication handoff claim is invalid.");
+  }
+  return value;
+}
+
+function requiredProjectId(value: string): string {
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]{1,127}$/.test(value)) {
+    throw new Error("The customer authentication project is invalid.");
+  }
+  return value;
+}
+
+function requiredPkceVerifier(value: unknown): string {
+  if (typeof value !== "string" || !/^[A-Za-z0-9._~-]{43,128}$/.test(value)) {
+    throw new Error("The PKCE verifier is invalid.");
+  }
+  return value;
+}
+
+function requiredSessionData(value: unknown): string {
+  if (typeof value !== "string" || value.length < 1
+      || new TextEncoder().encode(value).byteLength > SESSION_DATA_MAX_LENGTH) {
+    throw new Error("The customer session data is invalid.");
+  }
+  return value;
+}
+
+function requiredClientKey(value: unknown): string {
+  if (typeof value !== "string" || value.length < 1 || value.length > 512
+      || /[\u0000-\u001f\u007f]/.test(value)) {
+    throw new Error("The customer authentication client key is invalid.");
+  }
+  return value;
+}
+
+function requiredInteractionMode(value: unknown): "interactive" | "silent" {
+  if (value !== "interactive" && value !== "silent") {
+    throw new Error("The customer authentication interaction mode is invalid.");
+  }
+  return value;
+}
+
+function validAuthorizationAttemptLimit(value: number): boolean {
+  return Number.isSafeInteger(value)
+    && value >= 1
+    && value <= MAX_CONFIGURED_AUTHORIZATION_ATTEMPTS;
+}
+
+function requiredDigest(value: unknown, label: string): string {
+  if (typeof value !== "string" || !/^[a-f0-9]{64}$/.test(value)) {
+    throw new Error(`The ${label} digest is invalid.`);
+  }
+  return value;
+}
+
+function requiredSessionSeal(value: unknown): string {
+  if (typeof value !== "string" || value.length > SESSION_SEAL_MAX_LENGTH
+      || !/^[A-Za-z0-9_-]{16}\.[A-Za-z0-9_-]{40,99980}$/.test(value)) {
+    throw new Error("The customer authentication session seal is invalid.");
+  }
+  return value;
+}
+
+function requiredOpaqueValue(value: unknown, label: string): string {
+  if (typeof value !== "string" || !/^[A-Za-z0-9_-]{43}$/.test(value)) {
+    throw new Error(`The ${label} is invalid.`);
+  }
+  return value;
+}
+
+function normalizedHostname(value: unknown): string {
+  if (typeof value !== "string") throw new Error("The customer authentication hostname is invalid.");
+  const hostname = value.toLowerCase().replace(/\.$/, "");
+  if (!/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/.test(hostname) ||
+      hostname.length > 253) {
+    throw new Error("The customer authentication hostname is invalid.");
+  }
+  return hostname;
+}
+
+function randomOpaqueValue(): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(OPAQUE_VALUE_BYTES));
+  return base64UrlEncode(bytes);
+}
+
+async function opaqueDigest(value: string): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
+  return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+async function sealPendingSessionPayload(input: {
+  sessionId: string;
+  sessionExpiresAt: number;
+  sessionData: string;
+  handoff: string;
+  projectId: string;
+  returnHostname: string;
+  handoffDigest: string;
+}): Promise<string> {
+  const key = await handoffKey(input.handoff, ["encrypt"]);
+  const nonce = crypto.getRandomValues(new Uint8Array(12));
+  const plaintext = new TextEncoder().encode(
+    `${requiredOpaqueValue(input.sessionId, "shopper session")}\n${requiredStoredExpiry(input.sessionExpiresAt)}\n${requiredSessionData(input.sessionData)}`,
+  );
+  const ciphertext = await crypto.subtle.encrypt({
+    name: "AES-GCM",
+    iv: nonce,
+    additionalData: handoffContext(input, "pending"),
+  }, key, plaintext);
+  return requiredSessionSeal(`${base64UrlEncode(nonce)}.${base64UrlEncode(new Uint8Array(ciphertext))}`);
+}
+
+async function unsealPendingSessionPayload(input: {
+  sessionSeal: string;
+  handoff: string;
+  projectId: string;
+  returnHostname: string;
+  handoffDigest: string;
+}): Promise<{ sessionId: string; sessionExpiresAt: number; sessionData: string }> {
+  const [encodedNonce, encodedCiphertext] = input.sessionSeal.split(".");
+  if (!encodedNonce || !encodedCiphertext) throw new Error("The customer authentication session seal is invalid.");
+  try {
+    const key = await handoffKey(input.handoff, ["decrypt"]);
+    const plaintext = await crypto.subtle.decrypt({
+      name: "AES-GCM",
+      iv: base64UrlDecode(encodedNonce),
+      additionalData: handoffContext(input, "pending"),
+    }, key, base64UrlDecode(encodedCiphertext));
+    const decoded = new TextDecoder("utf-8", { fatal: true }).decode(plaintext);
+    const firstSeparator = decoded.indexOf("\n");
+    const secondSeparator = decoded.indexOf("\n", firstSeparator + 1);
+    if (firstSeparator < 0 || secondSeparator < 0) {
+      throw new Error("The customer authentication session seal is invalid.");
+    }
+    return {
+      sessionId: requiredOpaqueValue(decoded.slice(0, firstSeparator), "shopper session"),
+      sessionExpiresAt: requiredStoredExpiry(decoded.slice(firstSeparator + 1, secondSeparator)),
+      sessionData: requiredSessionData(decoded.slice(secondSeparator + 1)),
+    };
+  } catch {
+    throw new Error("The customer authentication session seal is invalid.");
+  }
+}
+
+async function sealClaimedSessionId(input: {
+  sessionId: string;
+  handoff: string;
+  projectId: string;
+  returnHostname: string;
+  handoffDigest: string;
+}): Promise<string> {
+  const key = await handoffKey(input.handoff, ["encrypt"]);
+  const nonce = crypto.getRandomValues(new Uint8Array(12));
+  const ciphertext = await crypto.subtle.encrypt({
+    name: "AES-GCM",
+    iv: nonce,
+    additionalData: handoffContext(input, "claimed"),
+  }, key, new TextEncoder().encode(requiredOpaqueValue(input.sessionId, "shopper session")));
+  return requiredSessionSeal(`${base64UrlEncode(nonce)}.${base64UrlEncode(new Uint8Array(ciphertext))}`);
+}
+
+async function unsealClaimedSessionId(input: {
+  sessionSeal: string;
+  handoff: string;
+  projectId: string;
+  returnHostname: string;
+  handoffDigest: string;
+}): Promise<string> {
+  const [encodedNonce, encodedCiphertext] = input.sessionSeal.split(".");
+  if (!encodedNonce || !encodedCiphertext) throw new Error("The customer authentication session seal is invalid.");
+  try {
+    const key = await handoffKey(input.handoff, ["decrypt"]);
+    const plaintext = await crypto.subtle.decrypt({
+      name: "AES-GCM",
+      iv: base64UrlDecode(encodedNonce),
+      additionalData: handoffContext(input, "claimed"),
+    }, key, base64UrlDecode(encodedCiphertext));
+    return requiredOpaqueValue(
+      new TextDecoder("utf-8", { fatal: true }).decode(plaintext),
+      "shopper session",
+    );
+  } catch {
+    throw new Error("The customer authentication session seal is invalid.");
+  }
+}
+
+function requiredStoredExpiry(value: unknown): number {
+  const parsed = typeof value === "number"
+    ? value
+    : typeof value === "string" && /^(?:0|[1-9][0-9]{0,15})$/.test(value)
+      ? Number(value)
+      : Number.NaN;
+  if (!Number.isSafeInteger(parsed) || parsed < 1) {
+    throw new Error("The stored expiration is invalid.");
+  }
+  return parsed;
+}
+
+async function handoffKey(handoff: string, usages: KeyUsage[]): Promise<CryptoKey> {
+  const keyMaterial = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(`public-customer-auth-handoff:${handoff}`),
+  );
+  return crypto.subtle.importKey("raw", keyMaterial, "AES-GCM", false, usages);
+}
+
+function handoffContext(input: {
+  projectId: string;
+  returnHostname: string;
+  handoffDigest: string;
+}, state: "pending" | "claimed"): Uint8Array<ArrayBuffer> {
+  return new TextEncoder().encode(
+    `${input.projectId}\0${input.returnHostname}\0${input.handoffDigest}\0${state}`,
+  );
+}
+
+function base64UrlEncode(value: Uint8Array): string {
+  const binary = Array.from(value, (byte) => String.fromCharCode(byte)).join("");
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+}
+
+function base64UrlDecode(value: string): Uint8Array<ArrayBuffer> {
+  if (!/^[A-Za-z0-9_-]+$/.test(value)) throw new Error("The encoded customer authentication value is invalid.");
+  const padding = "=".repeat((4 - (value.length % 4)) % 4);
+  const binary = atob(value.replaceAll("-", "+").replaceAll("_", "/") + padding);
+  return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+}