@smartcrab/browser 0.1.0

package/src/client.ts

@@ -0,0 +1,1117 @@
+import type {
+  AuthorizationCodeGrantRequest,
+  ClientId,
+  EmailChallengeResponse,
+  EmailResendRequest,
+  EmailStartRequest,
+  EmailVerifyRequest,
+  EmailVerifyResponse,
+  MeDeleteResponse,
+  MeEmailChangeStartRequest,
+  MeEmailChangeStartResponse,
+  MeEmailChangeVerifyNewRequest,
+  MeEmailChangeVerifyNewResponse,
+  MeEmailChangeVerifyOldRequest,
+  MeEmailChangeVerifyOldResponse,
+  MeIdentitiesListResponse,
+  MeIdentityLinkRequest,
+  MeIdentityLinkResponse,
+  MeIdentityUnlinkResponse,
+  MePasskeyRegistrationOptionsResponse,
+  MePasskeyRegistrationVerifyRequest,
+  MePasskeyRegistrationVerifyResponse,
+  MePasskeyDeleteResponse,
+  MePasskeysListResponse,
+  MeSessionRevokeResponse,
+  MeSessionsListResponse,
+  MeSessionsRevokeAllResponse,
+  MeUpdateRequest,
+  MeUpdateResponse,
+  MeUser,
+  PasskeyAuthenticationOptionsRequest,
+  PasskeyAuthenticationOptionsResponse,
+  PasskeyAuthenticationVerifyRequest,
+  PasskeyAuthenticationVerifyResponse,
+  PasskeyRegistrationOptionsResponse,
+  PasskeyRegistrationVerifyRequest,
+  PublicConfigResponse,
+  RefreshTokenGrantRequest,
+  RevocationRequest,
+  SocialProvider,
+  SocialStartResponse,
+  TokenResponse,
+  TransactionCancelResponse,
+  TransactionCompleteResponse,
+  TransactionCreateRequest,
+  TransactionCreateResponse,
+  TransactionGetResponse,
+  TransactionPasskeyRegistrationVerifyResponse,
+} from "@smartcrab/contracts-public";
+import {
+  clientIdSchema,
+  emailChallengeResponseSchema,
+  emailVerifyResponseSchema,
+  meDeleteResponseSchema,
+  meEmailChangeStartResponseSchema,
+  meEmailChangeVerifyNewResponseSchema,
+  meEmailChangeVerifyOldResponseSchema,
+  meIdentitiesListResponseSchema,
+  meIdentityLinkResponseSchema,
+  meIdentityUnlinkResponseSchema,
+  mePasskeyDeleteResponseSchema,
+  mePasskeyRegistrationOptionsResponseSchema,
+  mePasskeyRegistrationVerifyResponseSchema,
+  mePasskeysListResponseSchema,
+  meSessionRevokeResponseSchema,
+  meSessionsListResponseSchema,
+  meSessionsRevokeAllResponseSchema,
+  meUpdateResponseSchema,
+  meUserSchema,
+  passkeyAuthenticationOptionsResponseSchema,
+  passkeyAuthenticationVerifyResponseSchema,
+  passkeyRegistrationOptionsResponseSchema,
+  publicConfigResponseSchema,
+  scopeStringSchema,
+  socialStartResponseSchema,
+  tokenResponseSchema,
+  transactionCancelResponseSchema,
+  transactionCompleteResponseSchema,
+  transactionCreateResponseSchema,
+  transactionGetResponseSchema,
+  transactionPasskeyRegistrationVerifyResponseSchema,
+} from "@smartcrab/contracts-public";
+import { err, ok } from "@smartcrab/contracts-public";
+import type { Outcome } from "@smartcrab/contracts-public";
+import type { BrowserAuthError } from "./errors.js";
+import type { FetchPort } from "./http.js";
+import { buildUrl, isOAuthErrorCode, requestJson } from "./http.js";
+import type { WireSchema } from "./http.js";
+import { generateNonce, generatePkcePair, generateState } from "./pkce.js";
+import { navigatorWebAuthnPort } from "./webauthn.js";
+import type { WebAuthnBrowserPort } from "./webauthn.js";
+
+/**
+ * `BrowserAuthClient` — the SPA-facing client for the public authentication
+ * API (design.md §16, §22.3).
+ *
+ * Security posture (design.md §22.3, §32.1/§32.2):
+ * - Authorization Code + PKCE S256; `state` and `nonce` are generated when not supplied.
+ * - Access and refresh tokens stay in memory by default; access tokens never enter Web Storage.
+ * - Short-lived PKCE callback metadata is stored in `sessionStorage` (never `localStorage`) so a
+ *   top-level redirect can resume after the SPA reloads. It is consumed once and expires after
+ *   10 minutes; when storage is unavailable, the current client falls back to its memory copy.
+ * - Refresh-token persistence is a separate explicit opt-in via `refreshTokenStorage`.
+ * - No silent-iframe / third-party-cookie renewal. After reload, reauthorize top-level via
+ *   `beginHostedAuthorization()` against the existing Hosted Session, or call `restoreSession()`
+ *   when opt-in refresh-token persistence is configured.
+ *
+ * Result channel: `@praha/byethrow` does not resolve from this package (not a
+ * declared dependency), so every fallible method returns the local
+ * `Outcome<T, BrowserAuthError>` discriminated union re-exported from
+ * `@smartcrab/contracts-public` instead of `Result`.
+ */
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/** Top-level navigation port (design.md §20.6/§22.3: external, top-level redirects only). */
+export interface RedirectPort {
+  assign(url: string): void;
+}
+
+/**
+ * OPT-IN refresh token persistence (design.md §22.3: "refresh tokenの永続保存
+ * は既定で無効").
+ *
+ * WARNING — think before enabling: anything written here survives page
+ * reloads and is readable by every script running on your origin, including
+ * any XSS payload. Prefer the default (memory-only) and re-authorize through
+ * the Hosted Session after reload. If you enable this, use the most
+ * constrained storage available to you (e.g. an encrypted, origin-isolated
+ * store), never plain `localStorage` on a hostile-script surface, and combine
+ * it with a strict CSP (design.md §32.2). The platform rotates refresh tokens
+ * on every use and detects replay (design.md §32.1), which limits — but does
+ * not eliminate — the blast radius of a stolen token.
+ */
+export interface RefreshTokenStoragePort {
+  load(): Promise<string | null> | string | null;
+  save(refreshToken: string): Promise<void> | void;
+  clear(): Promise<void> | void;
+}
+/**
+ * Short-lived PKCE metadata needed to resume a top-level authorization
+ * redirect. This is not a token set; the browser client stores it in
+ * sessionStorage under a key derived from `state`.
+ */
+interface PendingAuthorization {
+  readonly state: string;
+  readonly nonce: string;
+  readonly codeVerifier: string;
+  readonly redirectUri: string;
+  readonly createdAt: number;
+}
+
+export interface BrowserAuthClientConfig {
+  /** Public API origin, e.g. `https://id.example.com` (trailing slash tolerated). */
+  readonly baseUrl: string;
+  readonly clientId: ClientId;
+  /** Must be byte-for-byte registered on the client (design.md §15.9). */
+  readonly redirectUri: string;
+  /** Space-delimited OIDC scopes; defaults to `openid profile email`. */
+  readonly scope?: string;
+  /** RFC 8707 resource indicators to bind to the grant (design.md §15.7). */
+  readonly resource?: readonly string[];
+  /**
+   * Issuer (`https://host/e/env_xxx`). Optional: discovered and cached from
+   * `GET /v1/config` on first token/authorize call when omitted.
+   */
+  readonly issuer?: string;
+  /** fetch override (tests, custom instrumentation). Defaults to global `fetch`. */
+  readonly fetch?: FetchPort;
+  /** WebAuthn ceremony port. Defaults to `navigator.credentials`. */
+  readonly webAuthn?: WebAuthnBrowserPort;
+  /** Top-level navigation port. Defaults to `window.location.assign`. */
+  readonly redirect?: RedirectPort;
+  /** OPT-IN refresh token persistence — read the security warning on the type. */
+  readonly refreshTokenStorage?: RefreshTokenStoragePort;
+  /** Clock override for tests (epoch ms). */
+  readonly now?: () => number;
+}
+
+/** A live auth transaction plus the client-generated `state` that correlates its completion. */
+export interface BrowserTransaction {
+  readonly transactionId: string;
+  readonly state: string;
+  readonly expiresAt: string;
+  readonly availableMethods: TransactionCreateResponse["available_methods"];
+}
+
+export interface CreateTransactionInput {
+  readonly scope?: string;
+  readonly resource?: readonly string[];
+  /** App-supplied correlation value; the SDK generates one when omitted. */
+  readonly state?: string;
+  readonly nonce?: string;
+}
+
+/** Session metadata. Note: the access token itself is only ever handed out by `getAccessToken()`. */
+export interface AuthenticatedSession {
+  /** Epoch ms when the in-memory access token expires. */
+  readonly accessTokenExpiresAt: number;
+  readonly scope: string;
+  readonly hasRefreshToken: boolean;
+}
+
+/** Auth state snapshot for `subscribe`/`getSnapshot` (React bindings consume this). */
+export interface BrowserAuthSnapshot {
+  readonly status: "signed_out" | "signed_in";
+  readonly accessTokenExpiresAt?: number;
+  readonly scope?: string;
+  readonly hasRefreshToken: boolean;
+}
+
+export type BrowserAuthListener = (snapshot: BrowserAuthSnapshot) => void;
+
+export interface HostedAuthorization {
+  readonly url: string;
+  readonly state: string;
+}
+
+export interface BrowserAuthClient {
+  /** `GET /v1/config` (design.md §16.2), schema-validated. */
+  getPublicConfig(): Promise<Outcome<PublicConfigResponse, BrowserAuthError>>;
+
+  // -- Transactions (design.md §16.1-§16.3) ---------------------------------
+  createTransaction(
+    input?: CreateTransactionInput,
+  ): Promise<Outcome<BrowserTransaction, BrowserAuthError>>;
+  getTransaction(transactionId: string): Promise<Outcome<TransactionGetResponse, BrowserAuthError>>;
+  cancelTransaction(
+    transactionId: string,
+  ): Promise<Outcome<TransactionCancelResponse, BrowserAuthError>>;
+
+  // -- Email OTP (design.md §18) ---------------------------------------------
+  startEmailOtp(
+    transactionId: string,
+    input: EmailStartRequest,
+  ): Promise<Outcome<EmailChallengeResponse, BrowserAuthError>>;
+  resendEmailOtp(
+    transactionId: string,
+    input: EmailResendRequest,
+  ): Promise<Outcome<EmailChallengeResponse, BrowserAuthError>>;
+  verifyEmailOtp(
+    transactionId: string,
+    input: EmailVerifyRequest,
+  ): Promise<Outcome<EmailVerifyResponse, BrowserAuthError>>;
+
+  // -- Passkeys (design.md §17) ----------------------------------------------
+  getPasskeyRegistrationOptions(
+    transactionId: string,
+  ): Promise<Outcome<PasskeyRegistrationOptionsResponse, BrowserAuthError>>;
+  verifyPasskeyRegistration(
+    transactionId: string,
+    input: PasskeyRegistrationVerifyRequest,
+  ): Promise<Outcome<TransactionPasskeyRegistrationVerifyResponse, BrowserAuthError>>;
+  /** Full registration ceremony: options → authenticator → verify. */
+  startPasskeyRegistration(
+    transactionId: string,
+    input?: { readonly name?: string },
+  ): Promise<Outcome<TransactionPasskeyRegistrationVerifyResponse, BrowserAuthError>>;
+  getPasskeyAuthenticationOptions(
+    transactionId: string,
+    input?: PasskeyAuthenticationOptionsRequest,
+  ): Promise<Outcome<PasskeyAuthenticationOptionsResponse, BrowserAuthError>>;
+  verifyPasskeyAuthentication(
+    transactionId: string,
+    input: PasskeyAuthenticationVerifyRequest,
+  ): Promise<Outcome<PasskeyAuthenticationVerifyResponse, BrowserAuthError>>;
+  /** Full authentication ceremony (discoverable-credential default, design.md §17.2). */
+  startPasskeyAuthentication(
+    transactionId: string,
+    input?: PasskeyAuthenticationOptionsRequest,
+  ): Promise<Outcome<PasskeyAuthenticationVerifyResponse, BrowserAuthError>>;
+
+  // -- Social (design.md §20) --------------------------------------------------
+  /**
+   * Starts social sign-in and performs a TOP-LEVEL redirect to the returned
+   * `authorization_url` (embedded iframes/WebViews are never used). The
+   * provider callback eventually lands on `redirectUri`; resume with
+   * `handleHostedAuthorizationCallback`.
+   */
+  startSocialSignIn(
+    transactionId: string,
+    provider: SocialProvider,
+  ): Promise<Outcome<SocialStartResponse, BrowserAuthError>>;
+
+  // -- Completion / code exchange (design.md §16.3, §15.2) ---------------------
+  completeTransaction(
+    transactionId: string,
+  ): Promise<Outcome<TransactionCompleteResponse, BrowserAuthError>>;
+  /**
+   * Exchanges a one-time authorization code at the token endpoint using the
+   * PKCE verifier registered under `state`. Fails with `state_mismatch` when
+   * the state is unknown or expired.
+   */
+  exchangeAuthorizationCode(input: {
+    readonly code: string;
+    readonly state: string;
+  }): Promise<Outcome<AuthenticatedSession, BrowserAuthError>>;
+
+  // -- Hosted (redirect) authorization ------------------------------------------
+  /** Builds `{issuer}/oauth2/authorize` with fresh PKCE/state/nonce (design.md §15.1). */
+  createHostedAuthorizationUrl(): Promise<Outcome<HostedAuthorization, BrowserAuthError>>;
+  /** Same as `createHostedAuthorizationUrl` plus a top-level navigation. */
+  beginHostedAuthorization(): Promise<Outcome<{ readonly state: string }, BrowserAuthError>>;
+  /** Parses the authorize/social callback URL and exchanges the code it carries. */
+  handleHostedAuthorizationCallback(
+    callbackUrl: string,
+  ): Promise<Outcome<AuthenticatedSession, BrowserAuthError>>;
+
+  // -- Token/session management ---------------------------------------------------
+  getSnapshot(): BrowserAuthSnapshot;
+  subscribe(listener: BrowserAuthListener): () => void;
+  /** Runtime WebAuthn capability (design.md §21.2: UI must hide passkeys when false). */
+  isPasskeySupported(): boolean;
+  /** Current access token; silently refreshes first when expired and a refresh token exists. */
+  getAccessToken(): Promise<Outcome<string, BrowserAuthError>>;
+  /** Explicit refresh. Concurrent calls share one in-flight request (design.md §21.7). */
+  refreshSession(): Promise<Outcome<AuthenticatedSession, BrowserAuthError>>;
+  /**
+   * Reload recovery for the OPT-IN persistence path: loads the persisted
+   * refresh token and immediately rotates it into a fresh in-memory session.
+   * Without `refreshTokenStorage` (or an empty store) this resolves to
+   * `not_authenticated` and the app should start a fresh authorization.
+   */
+  restoreSession(): Promise<Outcome<AuthenticatedSession, BrowserAuthError>>;
+  /** Best-effort refresh-token revocation, then full local cleanup. */
+  signOut(): Promise<Outcome<{ readonly signedOut: true }, BrowserAuthError>>;
+
+  // -- /v1/me (design.md §16.2; all Bearer-authenticated) --------------------------
+  getMe(): Promise<Outcome<MeUser, BrowserAuthError>>;
+  updateMe(input: MeUpdateRequest): Promise<Outcome<MeUpdateResponse, BrowserAuthError>>;
+  listMyPasskeys(): Promise<Outcome<MePasskeysListResponse, BrowserAuthError>>;
+  getMyPasskeyRegistrationOptions(): Promise<
+    Outcome<MePasskeyRegistrationOptionsResponse, BrowserAuthError>
+  >;
+  verifyMyPasskeyRegistration(
+    input: MePasskeyRegistrationVerifyRequest,
+  ): Promise<Outcome<MePasskeyRegistrationVerifyResponse, BrowserAuthError>>;
+  /** Full me-scoped registration ceremony: options → authenticator → verify. */
+  registerMyPasskey(input?: {
+    readonly name?: string;
+  }): Promise<Outcome<MePasskeyRegistrationVerifyResponse, BrowserAuthError>>;
+  deleteMyPasskey(passkeyId: string): Promise<Outcome<MePasskeyDeleteResponse, BrowserAuthError>>;
+  listMyIdentities(): Promise<Outcome<MeIdentitiesListResponse, BrowserAuthError>>;
+  linkMyIdentity(
+    provider: SocialProvider,
+    input: MeIdentityLinkRequest,
+  ): Promise<Outcome<MeIdentityLinkResponse, BrowserAuthError>>;
+  unlinkMyIdentity(
+    identityId: string,
+  ): Promise<Outcome<MeIdentityUnlinkResponse, BrowserAuthError>>;
+  listMySessions(): Promise<Outcome<MeSessionsListResponse, BrowserAuthError>>;
+  revokeMySession(sessionId: string): Promise<Outcome<MeSessionRevokeResponse, BrowserAuthError>>;
+  revokeAllMySessions(): Promise<Outcome<MeSessionsRevokeAllResponse, BrowserAuthError>>;
+  startMyEmailChange(
+    input: MeEmailChangeStartRequest,
+  ): Promise<Outcome<MeEmailChangeStartResponse, BrowserAuthError>>;
+  verifyMyEmailChangeOld(
+    input: MeEmailChangeVerifyOldRequest,
+  ): Promise<Outcome<MeEmailChangeVerifyOldResponse, BrowserAuthError>>;
+  verifyMyEmailChangeNew(
+    input: MeEmailChangeVerifyNewRequest,
+  ): Promise<Outcome<MeEmailChangeVerifyNewResponse, BrowserAuthError>>;
+  deleteMyAccount(): Promise<Outcome<MeDeleteResponse, BrowserAuthError>>;
+}
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+const EXPIRY_SKEW_MS = 30_000;
+/** Matches the transaction lifetime implied by design.md §16.1's example (10 minutes). */
+const PENDING_AUTHORIZATION_TTL_MS = 10 * 60 * 1000;
+
+interface TokenSet {
+  accessToken: string;
+  /** Epoch ms of expiry (before skew). */
+  accessTokenExpiresAt: number;
+  scope: string;
+  refreshToken: string | null;
+}
+
+const defaultFetchPort: FetchPort = (url, init) => fetch(url, init);
+
+const defaultRedirectPort: RedirectPort = {
+  assign: (url) => {
+    if (typeof window !== "undefined") {
+      window.location.assign(url);
+    }
+  },
+};
+const PENDING_AUTHORIZATION_STORAGE_PREFIX = "@smartcrab/browser:pending:";
+
+const isPendingAuthorization = (value: unknown): value is PendingAuthorization => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  return (
+    typeof record["state"] === "string" &&
+    typeof record["nonce"] === "string" &&
+    typeof record["codeVerifier"] === "string" &&
+    typeof record["redirectUri"] === "string" &&
+    typeof record["createdAt"] === "number" &&
+    Number.isFinite(record["createdAt"])
+  );
+};
+
+const encodeSegment = encodeURIComponent;
+
+export const createBrowserAuthClient = (config: BrowserAuthClientConfig): BrowserAuthClient => {
+  // Programmer-error validation: fail fast at factory time (not a runtime
+  // failure channel, hence a TypeError rather than an Outcome).
+  if (!URL.canParse(config.baseUrl)) {
+    throw new TypeError(`baseUrl is not a valid URL: ${config.baseUrl}`);
+  }
+  if (!clientIdSchema.safeParse(config.clientId).success) {
+    throw new TypeError("clientId is not a valid cli_ identifier");
+  }
+  const scope = config.scope ?? "openid profile email";
+  if (!scopeStringSchema.safeParse(scope).success) {
+    throw new TypeError(`scope contains unknown tokens: ${scope}`);
+  }
+  if (config.redirectUri.length === 0) {
+    throw new TypeError("redirectUri must not be empty");
+  }
+
+  const baseUrl = config.baseUrl.replace(/\/+$/, "");
+  const fetchPort = config.fetch ?? defaultFetchPort;
+  const webAuthn = config.webAuthn ?? navigatorWebAuthnPort;
+  const redirectPort = config.redirect ?? defaultRedirectPort;
+  const now = config.now ?? (() => Date.now());
+  const storage = config.refreshTokenStorage;
+
+  // Tokens stay in this closure; only short-lived PKCE callback state uses sessionStorage.
+  let tokenSet: TokenSet | null = null;
+  let cachedIssuer: string | null = config.issuer ?? null;
+  let inflightRefresh: Promise<Outcome<AuthenticatedSession, BrowserAuthError>> | null = null;
+  const pendingByState = new Map<string, PendingAuthorization>();
+  const listeners = new Set<BrowserAuthListener>();
+  let snapshot: BrowserAuthSnapshot = { status: "signed_out", hasRefreshToken: false };
+
+  const notify = (): void => {
+    snapshot =
+      tokenSet === null
+        ? { status: "signed_out", hasRefreshToken: false }
+        : {
+            status: "signed_in",
+            accessTokenExpiresAt: tokenSet.accessTokenExpiresAt,
+            scope: tokenSet.scope,
+            hasRefreshToken: tokenSet.refreshToken !== null,
+          };
+    for (const listener of listeners) {
+      listener(snapshot);
+    }
+  };
+
+  const prunePending = (): void => {
+    const cutoff = now() - PENDING_AUTHORIZATION_TTL_MS;
+    for (const [state, pending] of pendingByState) {
+      if (pending.createdAt < cutoff) pendingByState.delete(state);
+    }
+  };
+
+  // Storage is a navigation-recovery aid: unavailable storage (Node/SSR, blocked storage,
+  // quota) or malformed entries fall back to the in-memory copy. Exception boundaries are
+  // promise rejection handlers, never try/catch (scripts/check-backend-error-style.ts).
+  const registerPending = async (pending: PendingAuthorization): Promise<void> => {
+    prunePending();
+    pendingByState.set(pending.state, pending);
+    await Promise.resolve()
+      .then(() =>
+        sessionStorage.setItem(
+          `${PENDING_AUTHORIZATION_STORAGE_PREFIX}${pending.state}`,
+          JSON.stringify(pending),
+        ),
+      )
+      .then(undefined, () => undefined);
+  };
+
+  const consumePending = async (state: string): Promise<PendingAuthorization | null> => {
+    const inMemory = pendingByState.get(state) ?? null;
+    pendingByState.delete(state);
+    const stored = await Promise.resolve()
+      .then((): PendingAuthorization | null => {
+        const key = `${PENDING_AUTHORIZATION_STORAGE_PREFIX}${state}`;
+        const serialized = sessionStorage.getItem(key);
+        if (serialized === null) return null;
+        sessionStorage.removeItem(key);
+        const parsed: unknown = JSON.parse(serialized);
+        return isPendingAuthorization(parsed) && parsed.state === state ? parsed : null;
+      })
+      .then(undefined, () => null);
+    const pending = inMemory ?? stored;
+    if (pending === null || now() - pending.createdAt > PENDING_AUTHORIZATION_TTL_MS) {
+      return null;
+    }
+    return pending;
+  };
+
+  const applyTokenResponse = async (
+    tokenResponse: TokenResponse,
+  ): Promise<AuthenticatedSession> => {
+    const refreshToken = tokenResponse.refresh_token ?? tokenSet?.refreshToken ?? null;
+    tokenSet = {
+      accessToken: tokenResponse.access_token,
+      accessTokenExpiresAt: now() + tokenResponse.expires_in * 1000,
+      scope: tokenResponse.scope,
+      refreshToken,
+    };
+    const persistToken = tokenResponse.refresh_token;
+    if (persistToken !== undefined && storage !== undefined) {
+      // Best-effort: a failing storage port must not break authentication.
+      await Promise.resolve()
+        .then(() => storage.save(persistToken))
+        .then(undefined, () => undefined);
+    }
+    notify();
+    return {
+      accessTokenExpiresAt: tokenSet.accessTokenExpiresAt,
+      scope: tokenSet.scope,
+      hasRefreshToken: refreshToken !== null,
+    };
+  };
+
+  const clearSession = (): void => {
+    tokenSet = null;
+    if (storage !== undefined) {
+      void Promise.resolve()
+        .then(() => storage.clear())
+        .then(undefined, () => undefined);
+    }
+    notify();
+  };
+
+  const request = <T>(
+    method: "GET" | "POST" | "PATCH" | "DELETE",
+    path: string,
+    schema: WireSchema<T>,
+    options?: {
+      readonly body?: unknown;
+      readonly accessToken?: string;
+      readonly query?: Record<string, string>;
+    },
+  ): Promise<Outcome<T, BrowserAuthError>> =>
+    requestJson(
+      fetchPort,
+      {
+        method,
+        url: buildUrl(baseUrl, path, options?.query),
+        ...(options?.body !== undefined ? { body: options.body } : {}),
+        ...(options?.accessToken !== undefined ? { accessToken: options.accessToken } : {}),
+      },
+      schema,
+    );
+
+  const getPublicConfig = (): Promise<Outcome<PublicConfigResponse, BrowserAuthError>> =>
+    request("GET", "/v1/config", publicConfigResponseSchema, {
+      query: { client_id: config.clientId },
+    });
+
+  const resolveIssuer = async (): Promise<Outcome<string, BrowserAuthError>> => {
+    if (cachedIssuer !== null) return ok(cachedIssuer);
+    const configOutcome = await getPublicConfig();
+    if (!configOutcome.ok) return configOutcome;
+    cachedIssuer = configOutcome.value.issuer;
+    return ok(cachedIssuer);
+  };
+
+  // --- transactions -----------------------------------------------------------
+
+  const createTransaction = async (
+    input?: CreateTransactionInput,
+  ): Promise<Outcome<BrowserTransaction, BrowserAuthError>> => {
+    const pkce = await generatePkcePair();
+    const state = input?.state ?? generateState();
+    const nonce = input?.nonce ?? generateNonce();
+    const resource = input?.resource ?? config.resource;
+    const body: TransactionCreateRequest = {
+      client_id: config.clientId,
+      redirect_uri: config.redirectUri,
+      code_challenge: pkce.challenge,
+      code_challenge_method: "S256",
+      state,
+      nonce,
+      scope: input?.scope ?? scope,
+      ...(resource !== undefined ? { resource: [...resource] } : {}),
+      // The SPA drives the ceremony itself and calls `/complete` over XHR
+      // (design.md §16.3), which is the `native_return` mode.
+      response_mode: "native_return",
+    };
+    const outcome = await request(
+      "POST",
+      "/v1/auth/transactions",
+      transactionCreateResponseSchema,
+      { body },
+    );
+    if (!outcome.ok) return outcome;
+    await registerPending({
+      state,
+      nonce,
+      codeVerifier: pkce.verifier,
+      redirectUri: config.redirectUri,
+      createdAt: now(),
+    });
+    return ok({
+      transactionId: outcome.value.transaction_id,
+      state,
+      expiresAt: outcome.value.expires_at,
+      availableMethods: outcome.value.available_methods,
+    });
+  };
+
+  const transactionPath = (transactionId: string): string =>
+    `/v1/auth/transactions/${encodeSegment(transactionId)}`;
+
+  const getTransaction = (transactionId: string) =>
+    request("GET", transactionPath(transactionId), transactionGetResponseSchema);
+
+  const cancelTransaction = (transactionId: string) =>
+    request("POST", `${transactionPath(transactionId)}/cancel`, transactionCancelResponseSchema, {
+      body: {},
+    });
+
+  // --- email OTP -----------------------------------------------------------------
+
+  const startEmailOtp = (transactionId: string, input: EmailStartRequest) =>
+    request("POST", `${transactionPath(transactionId)}/email/start`, emailChallengeResponseSchema, {
+      body: input,
+    });
+
+  const resendEmailOtp = (transactionId: string, input: EmailResendRequest) =>
+    request(
+      "POST",
+      `${transactionPath(transactionId)}/email/resend`,
+      emailChallengeResponseSchema,
+      { body: input },
+    );
+
+  const verifyEmailOtp = (transactionId: string, input: EmailVerifyRequest) =>
+    request("POST", `${transactionPath(transactionId)}/email/verify`, emailVerifyResponseSchema, {
+      body: input,
+    });
+
+  // --- passkeys --------------------------------------------------------------------
+
+  const getPasskeyRegistrationOptions = (transactionId: string) =>
+    request(
+      "POST",
+      `${transactionPath(transactionId)}/passkeys/registration/options`,
+      passkeyRegistrationOptionsResponseSchema,
+      {
+        body: {},
+      },
+    );
+
+  const verifyPasskeyRegistration = (
+    transactionId: string,
+    input: PasskeyRegistrationVerifyRequest,
+  ) =>
+    request(
+      "POST",
+      `${transactionPath(transactionId)}/passkeys/registration/verify`,
+      transactionPasskeyRegistrationVerifyResponseSchema,
+      { body: input },
+    );
+
+  const startPasskeyRegistration = async (
+    transactionId: string,
+    input?: { readonly name?: string },
+  ): Promise<Outcome<TransactionPasskeyRegistrationVerifyResponse, BrowserAuthError>> => {
+    if (!webAuthn.isAvailable()) {
+      return err({
+        type: "webauthn_error",
+        reason: "not_supported",
+        message: "WebAuthn is not available",
+      });
+    }
+    const options = await getPasskeyRegistrationOptions(transactionId);
+    if (!options.ok) return options;
+    const credential = await webAuthn.create(options.value);
+    if (!credential.ok) return credential;
+    return verifyPasskeyRegistration(transactionId, {
+      credential: credential.value,
+      ...(input?.name !== undefined ? { name: input.name } : {}),
+    });
+  };
+
+  const getPasskeyAuthenticationOptions = (
+    transactionId: string,
+    input?: PasskeyAuthenticationOptionsRequest,
+  ) =>
+    request(
+      "POST",
+      `${transactionPath(transactionId)}/passkeys/authentication/options`,
+      passkeyAuthenticationOptionsResponseSchema,
+      { body: input ?? {} },
+    );
+
+  const verifyPasskeyAuthentication = (
+    transactionId: string,
+    input: PasskeyAuthenticationVerifyRequest,
+  ) =>
+    request(
+      "POST",
+      `${transactionPath(transactionId)}/passkeys/authentication/verify`,
+      passkeyAuthenticationVerifyResponseSchema,
+      { body: input },
+    );
+
+  const startPasskeyAuthentication = async (
+    transactionId: string,
+    input?: PasskeyAuthenticationOptionsRequest,
+  ): Promise<Outcome<PasskeyAuthenticationVerifyResponse, BrowserAuthError>> => {
+    if (!webAuthn.isAvailable()) {
+      return err({
+        type: "webauthn_error",
+        reason: "not_supported",
+        message: "WebAuthn is not available",
+      });
+    }
+    const options = await getPasskeyAuthenticationOptions(transactionId, input);
+    if (!options.ok) return options;
+    const credential = await webAuthn.get(options.value);
+    if (!credential.ok) return credential;
+    return verifyPasskeyAuthentication(transactionId, { credential: credential.value });
+  };
+
+  // --- social -----------------------------------------------------------------------
+
+  const startSocialSignIn = async (
+    transactionId: string,
+    provider: SocialProvider,
+  ): Promise<Outcome<SocialStartResponse, BrowserAuthError>> => {
+    const outcome = await request(
+      "POST",
+      `${transactionPath(transactionId)}/social/${encodeSegment(provider)}/start`,
+      socialStartResponseSchema,
+      { body: {} },
+    );
+    if (!outcome.ok) return outcome;
+    // design.md §22.3/§20.6: top-level navigation only; the SPA resumes via
+    // the redirect back to `redirectUri`.
+    redirectPort.assign(outcome.value.authorization_url);
+    return outcome;
+  };
+
+  // --- completion + token exchange ------------------------------------------------------
+
+  const completeTransaction = async (
+    transactionId: string,
+  ): Promise<Outcome<TransactionCompleteResponse, BrowserAuthError>> => {
+    const outcome = await request(
+      "POST",
+      `${transactionPath(transactionId)}/complete`,
+      transactionCompleteResponseSchema,
+      {
+        body: {},
+      },
+    );
+    if (!outcome.ok) return outcome;
+    if (outcome.value.redirect_uri !== config.redirectUri) {
+      // design.md §15.9: exact redirect matching. A mismatch here is a server
+      // contract violation (or an attack), never a usable code.
+      return err({
+        type: "invalid_response",
+        message: "complete response redirect_uri does not match the configured redirectUri",
+      });
+    }
+    return outcome;
+  };
+
+  const exchangeAuthorizationCode = async (input: {
+    readonly code: string;
+    readonly state: string;
+  }): Promise<Outcome<AuthenticatedSession, BrowserAuthError>> => {
+    const pending = await consumePending(input.state);
+    if (pending === null) {
+      // Unknown, expired, or already-consumed state: possible CSRF/replay.
+      return err({ type: "state_mismatch" });
+    }
+    const issuerOutcome = await resolveIssuer();
+    if (!issuerOutcome.ok) return issuerOutcome;
+    const body: AuthorizationCodeGrantRequest = {
+      grant_type: "authorization_code",
+      code: input.code,
+      redirect_uri: pending.redirectUri,
+      code_verifier: pending.codeVerifier,
+      client_id: config.clientId,
+      ...(config.resource !== undefined ? { resource: [...config.resource] } : {}),
+    };
+    const outcome = await requestJson(
+      fetchPort,
+      { method: "POST", url: `${issuerOutcome.value}/oauth2/token`, body },
+      tokenResponseSchema,
+    );
+    if (!outcome.ok) return outcome;
+    return ok(await applyTokenResponse(outcome.value));
+  };
+
+  // --- hosted (redirect) authorization ------------------------------------------------------
+
+  const createHostedAuthorizationUrl = async (): Promise<
+    Outcome<HostedAuthorization, BrowserAuthError>
+  > => {
+    const issuerOutcome = await resolveIssuer();
+    if (!issuerOutcome.ok) return issuerOutcome;
+    const pkce = await generatePkcePair();
+    const state = generateState();
+    const nonce = generateNonce();
+    const params = new URLSearchParams();
+    params.set("response_type", "code");
+    params.set("client_id", config.clientId);
+    params.set("redirect_uri", config.redirectUri);
+    params.set("scope", scope);
+    params.set("state", state);
+    params.set("nonce", nonce);
+    params.set("code_challenge", pkce.challenge);
+    params.set("code_challenge_method", "S256");
+    for (const resource of config.resource ?? []) {
+      params.append("resource", resource);
+    }
+    await registerPending({
+      state,
+      nonce,
+      codeVerifier: pkce.verifier,
+      redirectUri: config.redirectUri,
+      createdAt: now(),
+    });
+    return ok({ url: `${issuerOutcome.value}/oauth2/authorize?${params.toString()}`, state });
+  };
+
+  const beginHostedAuthorization = async (): Promise<
+    Outcome<{ readonly state: string }, BrowserAuthError>
+  > => {
+    const outcome = await createHostedAuthorizationUrl();
+    if (!outcome.ok) return outcome;
+    redirectPort.assign(outcome.value.url);
+    return ok({ state: outcome.value.state });
+  };
+
+  const handleHostedAuthorizationCallback = async (
+    callbackUrl: string,
+  ): Promise<Outcome<AuthenticatedSession, BrowserAuthError>> => {
+    if (!URL.canParse(callbackUrl)) {
+      return err({ type: "invalid_response", message: "callback URL is not parseable" });
+    }
+    const url = new URL(callbackUrl);
+    const state = url.searchParams.get("state");
+    const errorParam = url.searchParams.get("error");
+    if (errorParam !== null) {
+      if (state !== null) await consumePending(state);
+      // RFC 6749 §4.1.2.1 error redirect. The code list is closed; an unknown
+      // value means the callback is not contract-shaped.
+      if (!isOAuthErrorCode(errorParam)) {
+        return err({
+          type: "invalid_response",
+          message: `callback carried an unknown OAuth error: ${errorParam}`,
+        });
+      }
+      const description = url.searchParams.get("error_description");
+      return err({
+        type: "oauth_error",
+        code: errorParam,
+        ...(description !== null ? { description } : {}),
+      });
+    }
+    const code = url.searchParams.get("code");
+    if (code === null || state === null) {
+      if (state !== null) await consumePending(state);
+      return err({ type: "invalid_response", message: "callback URL is missing code or state" });
+    }
+    return exchangeAuthorizationCode({ code, state });
+  };
+
+  // --- token / session management -------------------------------------------------------------
+
+  const refreshSession = (): Promise<Outcome<AuthenticatedSession, BrowserAuthError>> => {
+    if (inflightRefresh !== null) return inflightRefresh;
+    const pending = (async (): Promise<Outcome<AuthenticatedSession, BrowserAuthError>> => {
+      const refreshToken = tokenSet?.refreshToken ?? null;
+      if (refreshToken === null) {
+        return err({ type: "not_authenticated" });
+      }
+      const issuerOutcome = await resolveIssuer();
+      if (!issuerOutcome.ok) return issuerOutcome;
+      const body: RefreshTokenGrantRequest = {
+        grant_type: "refresh_token",
+        refresh_token: refreshToken,
+        client_id: config.clientId,
+        ...(config.resource !== undefined ? { resource: [...config.resource] } : {}),
+      };
+      const outcome = await requestJson(
+        fetchPort,
+        { method: "POST", url: `${issuerOutcome.value}/oauth2/token`, body },
+        tokenResponseSchema,
+      );
+      if (!outcome.ok) {
+        // design.md §21.7: invalid_grant kills the local session entirely;
+        // transient failures (network/5xx/429) must not.
+        if (outcome.error.type === "oauth_error" && outcome.error.code === "invalid_grant") {
+          clearSession();
+        }
+        return outcome;
+      }
+      return ok(await applyTokenResponse(outcome.value));
+    })();
+    inflightRefresh = pending;
+    const clearInflight = (): void => {
+      if (inflightRefresh === pending) inflightRefresh = null;
+    };
+    void pending.then(clearInflight, clearInflight);
+    return pending;
+  };
+
+  const getAccessToken = async (): Promise<Outcome<string, BrowserAuthError>> => {
+    if (tokenSet !== null && now() < tokenSet.accessTokenExpiresAt - EXPIRY_SKEW_MS) {
+      return ok(tokenSet.accessToken);
+    }
+    if (tokenSet !== null && tokenSet.refreshToken !== null) {
+      const refreshed = await refreshSession();
+      if (!refreshed.ok) return refreshed;
+      const current = tokenSet;
+      if (current === null) return err({ type: "not_authenticated" });
+      return ok(current.accessToken);
+    }
+    return err({ type: "not_authenticated" });
+  };
+
+  const restoreSession = async (): Promise<Outcome<AuthenticatedSession, BrowserAuthError>> => {
+    if (storage === undefined) return err({ type: "not_authenticated" });
+    // A rejecting storage port is treated as "nothing persisted".
+    const persisted: string | null = await Promise.resolve()
+      .then(() => storage.load())
+      .then(
+        (value) => value,
+        () => null,
+      );
+    if (persisted === null) return err({ type: "not_authenticated" });
+    tokenSet = {
+      accessToken: "",
+      accessTokenExpiresAt: 0,
+      scope: "",
+      refreshToken: persisted,
+    };
+    return refreshSession();
+  };
+
+  const signOut = async (): Promise<Outcome<{ readonly signedOut: true }, BrowserAuthError>> => {
+    const refreshToken = tokenSet?.refreshToken ?? null;
+    if (refreshToken !== null && cachedIssuer !== null) {
+      // Best-effort revocation (RFC 7009; design.md §15.8): the endpoint
+      // succeeds even for unknown tokens, and local cleanup proceeds
+      // regardless of the outcome.
+      const body: RevocationRequest = {
+        token: refreshToken,
+        token_type_hint: "refresh_token",
+        client_id: config.clientId,
+      };
+      await requestJson(
+        fetchPort,
+        { method: "POST", url: `${cachedIssuer}/oauth2/revoke`, body },
+        {
+          safeParse: () => ({ success: true as const, data: {} }),
+        },
+      );
+    }
+    clearSession();
+    return ok({ signedOut: true });
+  };
+
+  // --- /v1/me -------------------------------------------------------------------------
+
+  const authed = async <T>(
+    method: "GET" | "POST" | "PATCH" | "DELETE",
+    path: string,
+    schema: WireSchema<T>,
+    body?: unknown,
+  ): Promise<Outcome<T, BrowserAuthError>> => {
+    const token = await getAccessToken();
+    if (!token.ok) return token;
+    return request(method, path, schema, {
+      accessToken: token.value,
+      ...(body !== undefined ? { body } : {}),
+    });
+  };
+
+  const getMe = () => authed("GET", "/v1/me", meUserSchema);
+
+  const updateMe = (input: MeUpdateRequest) =>
+    authed("PATCH", "/v1/me", meUpdateResponseSchema, input);
+
+  const listMyPasskeys = () => authed("GET", "/v1/me/passkeys", mePasskeysListResponseSchema);
+
+  const getMyPasskeyRegistrationOptions = () =>
+    authed(
+      "POST",
+      "/v1/me/passkeys/registration/options",
+      mePasskeyRegistrationOptionsResponseSchema,
+      {},
+    );
+
+  const verifyMyPasskeyRegistration = (input: MePasskeyRegistrationVerifyRequest) =>
+    authed(
+      "POST",
+      "/v1/me/passkeys/registration/verify",
+      mePasskeyRegistrationVerifyResponseSchema,
+      input,
+    );
+
+  const registerMyPasskey = async (input?: {
+    readonly name?: string;
+  }): Promise<Outcome<MePasskeyRegistrationVerifyResponse, BrowserAuthError>> => {
+    if (!webAuthn.isAvailable()) {
+      return err({
+        type: "webauthn_error",
+        reason: "not_supported",
+        message: "WebAuthn is not available",
+      });
+    }
+    const options = await getMyPasskeyRegistrationOptions();
+    if (!options.ok) return options;
+    const credential = await webAuthn.create(options.value);
+    if (!credential.ok) return credential;
+    return verifyMyPasskeyRegistration({
+      credential: credential.value,
+      ...(input?.name !== undefined ? { name: input.name } : {}),
+    });
+  };
+
+  const deleteMyPasskey = (passkeyId: string) =>
+    authed("DELETE", `/v1/me/passkeys/${encodeSegment(passkeyId)}`, mePasskeyDeleteResponseSchema);
+
+  const listMyIdentities = () => authed("GET", "/v1/me/identities", meIdentitiesListResponseSchema);
+
+  const linkMyIdentity = (provider: SocialProvider, input: MeIdentityLinkRequest) =>
+    authed(
+      "POST",
+      `/v1/me/identities/${encodeSegment(provider)}/link`,
+      meIdentityLinkResponseSchema,
+      input,
+    );
+
+  const unlinkMyIdentity = (identityId: string) =>
+    authed(
+      "DELETE",
+      `/v1/me/identities/${encodeSegment(identityId)}`,
+      meIdentityUnlinkResponseSchema,
+    );
+
+  const listMySessions = () => authed("GET", "/v1/me/sessions", meSessionsListResponseSchema);
+
+  const revokeMySession = (sessionId: string) =>
+    authed("DELETE", `/v1/me/sessions/${encodeSegment(sessionId)}`, meSessionRevokeResponseSchema);
+
+  const revokeAllMySessions = () =>
+    authed("DELETE", "/v1/me/sessions", meSessionsRevokeAllResponseSchema);
+
+  const startMyEmailChange = (input: MeEmailChangeStartRequest) =>
+    authed("POST", "/v1/me/email/change/start", meEmailChangeStartResponseSchema, input);
+
+  const verifyMyEmailChangeOld = (input: MeEmailChangeVerifyOldRequest) =>
+    authed("POST", "/v1/me/email/change/verify-old", meEmailChangeVerifyOldResponseSchema, input);
+
+  const verifyMyEmailChangeNew = (input: MeEmailChangeVerifyNewRequest) =>
+    authed("POST", "/v1/me/email/change/verify-new", meEmailChangeVerifyNewResponseSchema, input);
+
+  const deleteMyAccount = () => authed("DELETE", "/v1/me", meDeleteResponseSchema);
+
+  return {
+    getPublicConfig,
+    createTransaction,
+    getTransaction,
+    cancelTransaction,
+    startEmailOtp,
+    resendEmailOtp,
+    verifyEmailOtp,
+    getPasskeyRegistrationOptions,
+    verifyPasskeyRegistration,
+    startPasskeyRegistration,
+    getPasskeyAuthenticationOptions,
+    verifyPasskeyAuthentication,
+    startPasskeyAuthentication,
+    startSocialSignIn,
+    completeTransaction,
+    exchangeAuthorizationCode,
+    createHostedAuthorizationUrl,
+    beginHostedAuthorization,
+    handleHostedAuthorizationCallback,
+    getSnapshot: () => snapshot,
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    isPasskeySupported: () => webAuthn.isAvailable(),
+    getAccessToken,
+    refreshSession,
+    restoreSession,
+    signOut,
+    getMe,
+    updateMe,
+    listMyPasskeys,
+    getMyPasskeyRegistrationOptions,
+    verifyMyPasskeyRegistration,
+    registerMyPasskey,
+    deleteMyPasskey,
+    listMyIdentities,
+    linkMyIdentity,
+    unlinkMyIdentity,
+    listMySessions,
+    revokeMySession,
+    revokeAllMySessions,
+    startMyEmailChange,
+    verifyMyEmailChangeOld,
+    verifyMyEmailChangeNew,
+    deleteMyAccount,
+  };
+};