@smartcrab/browser 0.1.0

package/src/client.test.ts

@@ -0,0 +1,714 @@
+import { afterEach, describe, expect, test, vi } from "vitest";
+import type {
+  PasskeyAuthenticationCredential,
+  PasskeyRegistrationCredential,
+} from "@smartcrab/contracts-public";
+import { ok } from "@smartcrab/contracts-public";
+import type { Outcome } from "@smartcrab/contracts-public";
+import { base64UrlEncodeBytes } from "./base64url.js";
+import { createBrowserAuthClient } from "./client.js";
+import type { RedirectPort } from "./client.js";
+import type { WebAuthnFailureError } from "./errors.js";
+import type { FetchPort } from "./http.js";
+import type { WebAuthnBrowserPort } from "./webauthn.js";
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+/**
+ * Client behavior against design.md §16's exact request/response shapes.
+ * Every test asserts both the outgoing request (method, path, body) and that
+ * the response is parsed through the contracts-public zod schemas (malformed
+ * payloads must surface as typed `invalid_response` failures).
+ */
+
+const BASE_URL = "https://id.example.com";
+const ISSUER = `${BASE_URL}/e/env_abcdefghij`;
+const CLIENT_ID = `cli_${"a".repeat(32)}`;
+const TXN_ID = `txn_${"b".repeat(32)}`;
+const PASSKEY_ID = `psk_${"e".repeat(32)}`;
+const AUTH_CODE = `ac_${"g".repeat(32)}`;
+const REDIRECT_URI = "https://app.example.com/oauth/callback";
+
+interface CapturedRequest {
+  url: string;
+  method: string;
+  headers: Record<string, string>;
+  body: unknown;
+}
+
+const parseJson = (text: string): unknown => JSON.parse(text);
+
+const createFetchStub = (handler: (req: CapturedRequest) => Response | Promise<Response>) => {
+  const calls: CapturedRequest[] = [];
+  const fetchPort: FetchPort = (url, init) => {
+    const captured: CapturedRequest = {
+      url,
+      method: init.method ?? "GET",
+      headers: Object.fromEntries(new Headers(init.headers).entries()),
+      body: typeof init.body === "string" ? parseJson(init.body) : undefined,
+    };
+    calls.push(captured);
+    return Promise.resolve(handler(captured));
+  };
+  return { calls, fetchPort };
+};
+
+const jsonResponse = (status: number, body: unknown, headers?: Record<string, string>): Response =>
+  new Response(JSON.stringify(body), { status, ...(headers !== undefined ? { headers } : {}) });
+
+const CREATE_RESPONSE = {
+  transaction_id: TXN_ID,
+  expires_at: "2026-08-05T08:10:00Z",
+  available_methods: ["passkey", "email_otp", "google"],
+};
+
+const PUBLIC_CONFIG = {
+  issuer: ISSUER,
+  rp_id: "example.com",
+  available_methods: ["passkey", "email_otp", "google"],
+  theme: null,
+  sdk_compatibility_version: 1,
+  legal: {},
+};
+
+const createTestSessionStorage = () => {
+  const entries = new Map<string, string>();
+  return {
+    entries,
+    storage: {
+      getItem: (key: string) => entries.get(key) ?? null,
+      removeItem: (key: string) => {
+        entries.delete(key);
+      },
+      setItem: (key: string, value: string) => {
+        entries.set(key, value);
+      },
+    },
+  };
+};
+
+const makeClient = (
+  fetchPort: FetchPort,
+  overrides?: { redirect?: RedirectPort; webAuthn?: WebAuthnBrowserPort; now?: () => number },
+) =>
+  createBrowserAuthClient({
+    baseUrl: BASE_URL,
+    clientId: CLIENT_ID,
+    redirectUri: REDIRECT_URI,
+    issuer: ISSUER,
+    fetch: fetchPort,
+    ...(overrides?.redirect !== undefined ? { redirect: overrides.redirect } : {}),
+    ...(overrides?.webAuthn !== undefined ? { webAuthn: overrides.webAuthn } : {}),
+    ...(overrides?.now !== undefined ? { now: overrides.now } : {}),
+  });
+
+describe("createTransaction (design.md §16.1)", () => {
+  test("sends the exact §16.1 request shape with generated PKCE/state/nonce", async () => {
+    const { calls, fetchPort } = createFetchStub(() => jsonResponse(200, CREATE_RESPONSE));
+    const client = makeClient(fetchPort);
+    const outcome = await client.createTransaction();
+
+    expect(outcome.ok).toBe(true);
+    if (outcome.ok) {
+      expect(outcome.value.transactionId).toBe(TXN_ID);
+      expect(outcome.value.availableMethods).toEqual(["passkey", "email_otp", "google"]);
+    }
+
+    const request = calls[0];
+    if (request === undefined) throw new Error("expected a request");
+    expect(request.method).toBe("POST");
+    expect(request.url).toBe(`${BASE_URL}/v1/auth/transactions`);
+    expect(request.body).toMatchObject({
+      client_id: CLIENT_ID,
+      redirect_uri: REDIRECT_URI,
+      code_challenge_method: "S256",
+      scope: "openid profile email",
+      response_mode: "native_return",
+    });
+    const body = request.body as Record<string, unknown>;
+    expect(body["code_challenge"]).toMatch(/^[A-Za-z0-9_-]{43}$/);
+    expect(body["state"]).toEqual(expect.any(String));
+    expect(body["nonce"]).toEqual(expect.any(String));
+  });
+
+  test("forwards explicit scope/resource/state", async () => {
+    const { calls, fetchPort } = createFetchStub(() => jsonResponse(200, CREATE_RESPONSE));
+    const client = makeClient(fetchPort);
+    await client.createTransaction({
+      scope: "openid profile email offline_access",
+      resource: ["https://api.customer.example"],
+      state: "app-state",
+    });
+    const body = calls[0]?.body as Record<string, unknown>;
+    expect(body["scope"]).toBe("openid profile email offline_access");
+    expect(body["resource"]).toEqual(["https://api.customer.example"]);
+    expect(body["state"]).toBe("app-state");
+  });
+
+  test("a malformed response fails as invalid_response, never trusted", async () => {
+    const { fetchPort } = createFetchStub(() => jsonResponse(200, { transaction_id: "not-a-txn" }));
+    const client = makeClient(fetchPort);
+    const outcome = await client.createTransaction();
+    expect(outcome.ok).toBe(false);
+    if (!outcome.ok) expect(outcome.error.type).toBe("invalid_response");
+  });
+});
+
+describe("getTransaction / cancelTransaction (design.md §16.2)", () => {
+  test("getTransaction issues GET on the transaction path", async () => {
+    const { calls, fetchPort } = createFetchStub(() =>
+      jsonResponse(200, {
+        transaction_id: TXN_ID,
+        status: "challenge_issued",
+        expires_at: "2026-08-05T08:10:00Z",
+        available_methods: ["email_otp"],
+        pending_link: null,
+      }),
+    );
+    const client = makeClient(fetchPort);
+    const outcome = await client.getTransaction(TXN_ID);
+    expect(outcome.ok).toBe(true);
+    if (outcome.ok) expect(outcome.value.status).toBe("challenge_issued");
+    expect(calls[0]?.method).toBe("GET");
+    expect(calls[0]?.url).toBe(`${BASE_URL}/v1/auth/transactions/${TXN_ID}`);
+    expect(calls[0]?.body).toBeUndefined();
+  });
+
+  test("cancelTransaction POSTs an empty body to /cancel", async () => {
+    const { calls, fetchPort } = createFetchStub(() =>
+      jsonResponse(200, { transaction_id: TXN_ID, status: "failed" }),
+    );
+    const client = makeClient(fetchPort);
+    const outcome = await client.cancelTransaction(TXN_ID);
+    expect(outcome.ok).toBe(true);
+    expect(calls[0]?.method).toBe("POST");
+    expect(calls[0]?.url).toBe(`${BASE_URL}/v1/auth/transactions/${TXN_ID}/cancel`);
+    expect(calls[0]?.body).toEqual({});
+  });
+});
+
+describe("email OTP (design.md §16.2, §18)", () => {
+  const CHALLENGE = { challenge_id: "chal_abc", expires_at: "2026-08-05T08:05:00Z" };
+
+  test("startEmailOtp posts {email} to /email/start", async () => {
+    const { calls, fetchPort } = createFetchStub(() => jsonResponse(200, CHALLENGE));
+    const client = makeClient(fetchPort);
+    const outcome = await client.startEmailOtp(TXN_ID, { email: "user@example.com" });
+    expect(outcome.ok).toBe(true);
+    if (outcome.ok) expect(outcome.value.challenge_id).toBe("chal_abc");
+    expect(calls[0]?.url).toBe(`${BASE_URL}/v1/auth/transactions/${TXN_ID}/email/start`);
+    expect(calls[0]?.body).toEqual({ email: "user@example.com" });
+  });
+
+  test("resendEmailOtp posts {challenge_id} to /email/resend", async () => {
+    const { calls, fetchPort } = createFetchStub(() => jsonResponse(200, CHALLENGE));
+    const client = makeClient(fetchPort);
+    await client.resendEmailOtp(TXN_ID, { challenge_id: "chal_abc" });
+    expect(calls[0]?.url).toBe(`${BASE_URL}/v1/auth/transactions/${TXN_ID}/email/resend`);
+    expect(calls[0]?.body).toEqual({ challenge_id: "chal_abc" });
+  });
+
+  test("verifyEmailOtp posts {challenge_id, code} and parses the transaction ack", async () => {
+    const { calls, fetchPort } = createFetchStub(() =>
+      jsonResponse(200, { transaction_id: TXN_ID, status: "authenticated" }),
+    );
+    const client = makeClient(fetchPort);
+    const outcome = await client.verifyEmailOtp(TXN_ID, {
+      challenge_id: "chal_abc",
+      code: "123456",
+    });
+    expect(outcome.ok).toBe(true);
+    if (outcome.ok) expect(outcome.value.status).toBe("authenticated");
+    expect(calls[0]?.url).toBe(`${BASE_URL}/v1/auth/transactions/${TXN_ID}/email/verify`);
+    expect(calls[0]?.body).toEqual({ challenge_id: "chal_abc", code: "123456" });
+  });
+
+  test("a verify response smuggling tokens is rejected (design.md §16.3)", async () => {
+    const { fetchPort } = createFetchStub(() =>
+      jsonResponse(200, { transaction_id: TXN_ID, status: "authenticated", access_token: "nope" }),
+    );
+    const client = makeClient(fetchPort);
+    const outcome = await client.verifyEmailOtp(TXN_ID, {
+      challenge_id: "chal_abc",
+      code: "123456",
+    });
+    expect(outcome.ok).toBe(false);
+    if (!outcome.ok) expect(outcome.error.type).toBe("invalid_response");
+  });
+});
+
+describe("passkeys (design.md §17)", () => {
+  const REG_OPTIONS = {
+    rp: { id: "example.com", name: "Example" },
+    user: { id: "dXNlci0x", name: "user@example.com", displayName: "User" },
+    challenge: "Y2hhbGxlbmdl",
+    pubKeyCredParams: [{ type: "public-key", alg: -7 }],
+    authenticatorSelection: { residentKey: "required", userVerification: "required" },
+    attestation: "none",
+  };
+  const REG_CREDENTIAL: PasskeyRegistrationCredential = {
+    id: "Y3JlZA",
+    rawId: "Y3JlZA",
+    type: "public-key",
+    response: { clientDataJSON: "Y2xpZW50", attestationObject: "YXR0ZXN0" },
+  };
+  const PASSKEY_SUMMARY = {
+    passkey_id: PASSKEY_ID,
+    name: "MacBook",
+    created_at: "2026-08-05T08:00:00Z",
+    last_used_at: null,
+    device_type: "multi_device",
+    backed_up: true,
+  };
+  const AUTHN_OPTIONS = {
+    challenge: "Y2hhbGxlbmdl",
+    rpId: "example.com",
+    userVerification: "required",
+  };
+  const ASSERTION: PasskeyAuthenticationCredential = {
+    id: "Y3JlZA",
+    rawId: "Y3JlZA",
+    type: "public-key",
+    response: { clientDataJSON: "Y2xpZW50", authenticatorData: "YXV0aA", signature: "c2ln" },
+  };
+
+  const okRegistration = (): Promise<
+    Outcome<PasskeyRegistrationCredential, WebAuthnFailureError>
+  > => Promise.resolve(ok(REG_CREDENTIAL));
+  const okAssertion = (): Promise<Outcome<PasskeyAuthenticationCredential, WebAuthnFailureError>> =>
+    Promise.resolve(ok(ASSERTION));
+
+  test("startPasskeyRegistration runs options → authenticator → verify", async () => {
+    const webAuthn: WebAuthnBrowserPort = {
+      isAvailable: () => true,
+      create: vi.fn(okRegistration),
+      get: vi.fn(okAssertion),
+    };
+    const { calls, fetchPort } = createFetchStub((req) => {
+      if (req.url.endsWith("/passkeys/registration/options")) return jsonResponse(200, REG_OPTIONS);
+      return jsonResponse(200, {
+        transaction_id: TXN_ID,
+        status: "authenticated",
+        passkey: PASSKEY_SUMMARY,
+      });
+    });
+    const client = makeClient(fetchPort, { webAuthn });
+    const outcome = await client.startPasskeyRegistration(TXN_ID, { name: "MacBook" });
+
+    expect(outcome.ok).toBe(true);
+    if (outcome.ok) expect(outcome.value.passkey.passkey_id).toBe(PASSKEY_ID);
+    expect(calls.map((c) => c.url)).toEqual([
+      `${BASE_URL}/v1/auth/transactions/${TXN_ID}/passkeys/registration/options`,
+      `${BASE_URL}/v1/auth/transactions/${TXN_ID}/passkeys/registration/verify`,
+    ]);
+    expect(webAuthn.create).toHaveBeenCalledWith(REG_OPTIONS);
+    expect(calls[1]?.body).toEqual({ credential: REG_CREDENTIAL, name: "MacBook" });
+  });
+
+  test("startPasskeyAuthentication runs the discoverable-credential ceremony", async () => {
+    const webAuthn: WebAuthnBrowserPort = {
+      isAvailable: () => true,
+      create: vi.fn(okRegistration),
+      get: vi.fn(okAssertion),
+    };
+    const { calls, fetchPort } = createFetchStub((req) => {
+      if (req.url.endsWith("/passkeys/authentication/options"))
+        return jsonResponse(200, AUTHN_OPTIONS);
+      return jsonResponse(200, { transaction_id: TXN_ID, status: "authenticated" });
+    });
+    const client = makeClient(fetchPort, { webAuthn });
+    const outcome = await client.startPasskeyAuthentication(TXN_ID);
+
+    expect(outcome.ok).toBe(true);
+    expect(calls.map((c) => c.url)).toEqual([
+      `${BASE_URL}/v1/auth/transactions/${TXN_ID}/passkeys/authentication/options`,
+      `${BASE_URL}/v1/auth/transactions/${TXN_ID}/passkeys/authentication/verify`,
+    ]);
+    expect(calls[0]?.body).toEqual({});
+    expect(calls[1]?.body).toEqual({ credential: ASSERTION });
+    expect(webAuthn.get).toHaveBeenCalledWith(AUTHN_OPTIONS);
+  });
+
+  test("authentication options accept an optional email narrowing hint", async () => {
+    const { calls, fetchPort } = createFetchStub(() => jsonResponse(200, AUTHN_OPTIONS));
+    const client = makeClient(fetchPort);
+    await client.getPasskeyAuthenticationOptions(TXN_ID, { email: "user@example.com" });
+    expect(calls[0]?.body).toEqual({ email: "user@example.com" });
+  });
+
+  test("unsupported WebAuthn surfaces webauthn_error without any HTTP call", async () => {
+    const webAuthn: WebAuthnBrowserPort = {
+      isAvailable: () => false,
+      create: vi.fn(okRegistration),
+      get: vi.fn(okAssertion),
+    };
+    const { calls, fetchPort } = createFetchStub(() => jsonResponse(200, REG_OPTIONS));
+    const client = makeClient(fetchPort, { webAuthn });
+    const outcome = await client.startPasskeyAuthentication(TXN_ID);
+    expect(outcome.ok).toBe(false);
+    if (!outcome.ok) {
+      expect(outcome.error).toMatchObject({ type: "webauthn_error", reason: "not_supported" });
+    }
+    expect(calls).toHaveLength(0);
+  });
+
+  test("an authenticator failure propagates without calling verify", async () => {
+    const webAuthn: WebAuthnBrowserPort = {
+      isAvailable: () => true,
+      create: vi.fn(() =>
+        Promise.resolve({
+          ok: false as const,
+          error: {
+            type: "webauthn_error" as const,
+            reason: "cancelled" as const,
+            message: "user cancelled",
+          },
+        }),
+      ),
+      get: vi.fn(okAssertion),
+    };
+    const { calls, fetchPort } = createFetchStub(() => jsonResponse(200, REG_OPTIONS));
+    const client = makeClient(fetchPort, { webAuthn });
+    const outcome = await client.startPasskeyRegistration(TXN_ID);
+    expect(outcome.ok).toBe(false);
+    if (!outcome.ok) {
+      expect(outcome.error).toMatchObject({ type: "webauthn_error", reason: "cancelled" });
+    }
+    expect(calls).toHaveLength(1); // options only, verify never reached
+  });
+});
+
+describe("social sign-in (design.md §20, §22.3)", () => {
+  test("startSocialSignIn posts to /social/:provider/start and top-level redirects", async () => {
+    const assigned: string[] = [];
+    const redirect: RedirectPort = { assign: (url) => assigned.push(url) };
+    const { calls, fetchPort } = createFetchStub(() =>
+      jsonResponse(200, {
+        authorization_url: "https://accounts.google.com/o/oauth2/v2/auth?client_id=x",
+      }),
+    );
+    const client = makeClient(fetchPort, { redirect });
+    const outcome = await client.startSocialSignIn(TXN_ID, "google");
+
+    expect(outcome.ok).toBe(true);
+    expect(calls[0]?.method).toBe("POST");
+    expect(calls[0]?.url).toBe(`${BASE_URL}/v1/auth/transactions/${TXN_ID}/social/google/start`);
+    expect(calls[0]?.body).toEqual({});
+    expect(assigned).toEqual(["https://accounts.google.com/o/oauth2/v2/auth?client_id=x"]);
+  });
+
+  test("no redirect happens when the start call fails", async () => {
+    const assigned: string[] = [];
+    const redirect: RedirectPort = { assign: (url) => assigned.push(url) };
+    const { fetchPort } = createFetchStub(() =>
+      jsonResponse(404, {
+        type: "https://docs.example-auth.com/errors/not-found",
+        title: "Not Found",
+        status: 404,
+        code: "not_found",
+      }),
+    );
+    const client = makeClient(fetchPort, { redirect });
+    const outcome = await client.startSocialSignIn(TXN_ID, "google");
+    expect(outcome.ok).toBe(false);
+    if (!outcome.ok) expect(outcome.error.type).toBe("problem_details");
+    expect(assigned).toHaveLength(0);
+  });
+});
+
+describe("complete + code exchange (design.md §16.3, §15.2)", () => {
+  const setupThroughComplete = async () => {
+    const { calls, fetchPort } = createFetchStub((req) => {
+      if (req.url.endsWith("/v1/auth/transactions")) return jsonResponse(200, CREATE_RESPONSE);
+      if (req.url.endsWith("/complete")) {
+        const state = (calls[0]?.body as Record<string, unknown>)["state"];
+        return jsonResponse(200, {
+          authorization_code: AUTH_CODE,
+          state,
+          redirect_uri: REDIRECT_URI,
+        });
+      }
+      return jsonResponse(200, {
+        access_token: "at_first",
+        token_type: "Bearer",
+        expires_in: 300,
+        scope: "openid profile email",
+      });
+    });
+    const client = makeClient(fetchPort);
+    const created = await client.createTransaction();
+    expect(created.ok).toBe(true);
+    if (!created.ok) throw new Error("setup failed");
+    const completed = await client.completeTransaction(created.value.transactionId);
+    expect(completed.ok).toBe(true);
+    if (!completed.ok) throw new Error("setup failed");
+    return { calls, client, created: created.value, completed: completed.value };
+  };
+
+  test("complete returns the one-time code; exchange sends verifier and stores tokens in memory", async () => {
+    const { calls, client, created, completed } = await setupThroughComplete();
+    expect(completed.authorization_code).toBe(AUTH_CODE);
+    expect(completed.state).toBe(created.state);
+
+    const exchanged = await client.exchangeAuthorizationCode({
+      code: completed.authorization_code,
+      state: completed.state,
+    });
+    expect(exchanged.ok).toBe(true);
+    if (exchanged.ok) {
+      expect(exchanged.value.scope).toBe("openid profile email");
+      expect(exchanged.value.hasRefreshToken).toBe(false);
+    }
+
+    const tokenRequest = calls[2];
+    expect(tokenRequest?.method).toBe("POST");
+    expect(tokenRequest?.url).toBe(`${ISSUER}/oauth2/token`);
+    const body = tokenRequest?.body as Record<string, unknown>;
+    expect(body).toMatchObject({
+      grant_type: "authorization_code",
+      code: AUTH_CODE,
+      redirect_uri: REDIRECT_URI,
+      client_id: CLIENT_ID,
+    });
+
+    // PKCE end-to-end: the verifier sent to the token endpoint must hash to
+    // the challenge sent at transaction create (RFC 7636 §4.6).
+    const createBody = calls[0]?.body as Record<string, unknown>;
+    const verifier = body["code_verifier"];
+    expect(typeof verifier).toBe("string");
+    if (typeof verifier === "string") {
+      expect(verifier).toMatch(/^[A-Za-z0-9._~-]{43,128}$/);
+      const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+      expect(base64UrlEncodeBytes(new Uint8Array(digest))).toBe(createBody["code_challenge"]);
+    }
+
+    const token = await client.getAccessToken();
+    expect(token).toEqual({ ok: true, value: "at_first" });
+  });
+
+  test("exchange with an unknown state fails closed with state_mismatch", async () => {
+    const { client } = await setupThroughComplete();
+    const outcome = await client.exchangeAuthorizationCode({
+      code: AUTH_CODE,
+      state: "forged-state",
+    });
+    expect(outcome).toEqual({ ok: false, error: { type: "state_mismatch" } });
+  });
+
+  test("a complete response with a foreign redirect_uri is rejected (design.md §15.9)", async () => {
+    const { calls, fetchPort } = createFetchStub((req) => {
+      if (req.url.endsWith("/v1/auth/transactions")) return jsonResponse(200, CREATE_RESPONSE);
+      const state = (calls[0]?.body as Record<string, unknown>)["state"];
+      return jsonResponse(200, {
+        authorization_code: AUTH_CODE,
+        state,
+        redirect_uri: "https://evil.example.com/callback",
+      });
+    });
+    const client = makeClient(fetchPort);
+    const created = await client.createTransaction();
+    expect(created.ok).toBe(true);
+    if (!created.ok) return;
+    const outcome = await client.completeTransaction(created.value.transactionId);
+    expect(outcome.ok).toBe(false);
+    if (!outcome.ok) expect(outcome.error.type).toBe("invalid_response");
+  });
+});
+
+describe("hosted authorization redirect flow (design.md §22.3 reload recovery)", () => {
+  test("builds the authorize URL with PKCE and handles the callback", async () => {
+    const assigned: string[] = [];
+    const redirect: RedirectPort = { assign: (url) => assigned.push(url) };
+    const { calls, fetchPort } = createFetchStub(() =>
+      jsonResponse(200, {
+        access_token: "at_hosted",
+        token_type: "Bearer",
+        expires_in: 300,
+        scope: "openid profile email",
+      }),
+    );
+    const client = makeClient(fetchPort, { redirect });
+
+    const begun = await client.beginHostedAuthorization();
+    expect(begun.ok).toBe(true);
+    expect(assigned).toHaveLength(1);
+    const authorizeUrl = new URL(assigned[0] ?? "");
+    expect(authorizeUrl.origin + authorizeUrl.pathname).toBe(`${ISSUER}/oauth2/authorize`);
+    expect(authorizeUrl.searchParams.get("response_type")).toBe("code");
+    expect(authorizeUrl.searchParams.get("client_id")).toBe(CLIENT_ID);
+    expect(authorizeUrl.searchParams.get("redirect_uri")).toBe(REDIRECT_URI);
+    expect(authorizeUrl.searchParams.get("code_challenge_method")).toBe("S256");
+    expect(authorizeUrl.searchParams.get("code_challenge")).toMatch(/^[A-Za-z0-9_-]{43}$/);
+    const state = authorizeUrl.searchParams.get("state");
+    expect(state).not.toBeNull();
+
+    const callback = await client.handleHostedAuthorizationCallback(
+      `${REDIRECT_URI}?code=${AUTH_CODE}&state=${state ?? ""}`,
+    );
+    expect(callback.ok).toBe(true);
+    const tokenRequest = calls[0];
+    expect(tokenRequest?.url).toBe(`${ISSUER}/oauth2/token`);
+    expect((tokenRequest?.body as Record<string, unknown>)["grant_type"]).toBe(
+      "authorization_code",
+    );
+    const token = await client.getAccessToken();
+    expect(token).toEqual({ ok: true, value: "at_hosted" });
+  });
+  test("a fresh client resumes authorization state from sessionStorage", async () => {
+    const { entries, storage } = createTestSessionStorage();
+    vi.stubGlobal("sessionStorage", storage);
+    const { calls, fetchPort } = createFetchStub(() =>
+      jsonResponse(200, {
+        access_token: "at_session_storage",
+        token_type: "Bearer",
+        expires_in: 300,
+        scope: "openid profile email",
+      }),
+    );
+    const beforeRedirect = makeClient(fetchPort);
+    const authorization = await beforeRedirect.createHostedAuthorizationUrl();
+    expect(authorization.ok).toBe(true);
+    if (!authorization.ok) return;
+
+    expect(entries.size).toBe(1);
+    const afterRedirect = makeClient(fetchPort);
+    const callbackUrl = `${REDIRECT_URI}?code=${AUTH_CODE}&state=${authorization.value.state}`;
+    expect((await afterRedirect.handleHostedAuthorizationCallback(callbackUrl)).ok).toBe(true);
+    expect(entries.size).toBe(0);
+    expect(await afterRedirect.getAccessToken()).toEqual({
+      ok: true,
+      value: "at_session_storage",
+    });
+    expect(await afterRedirect.handleHostedAuthorizationCallback(callbackUrl)).toEqual({
+      ok: false,
+      error: { type: "state_mismatch" },
+    });
+    expect(calls).toHaveLength(1);
+  });
+
+  test("expired persisted PKCE state is removed and rejected", async () => {
+    const { entries, storage } = createTestSessionStorage();
+    vi.stubGlobal("sessionStorage", storage);
+    let nowMs = 1_000;
+    const { fetchPort } = createFetchStub(() => jsonResponse(200, {}));
+    const beforeRedirect = makeClient(fetchPort, {
+      now: () => nowMs,
+    });
+    const authorization = await beforeRedirect.createHostedAuthorizationUrl();
+    expect(authorization.ok).toBe(true);
+    if (!authorization.ok) return;
+
+    expect(entries.size).toBe(1);
+    nowMs += 10 * 60 * 1000 + 1;
+    const afterRedirect = makeClient(fetchPort, {
+      now: () => nowMs,
+    });
+    const outcome = await afterRedirect.handleHostedAuthorizationCallback(
+      `${REDIRECT_URI}?code=${AUTH_CODE}&state=${authorization.value.state}`,
+    );
+    expect(outcome).toEqual({ ok: false, error: { type: "state_mismatch" } });
+    expect(entries.size).toBe(0);
+  });
+
+  test("callback with a foreign state fails closed", async () => {
+    const client = makeClient(createFetchStub(() => jsonResponse(200, {})).fetchPort);
+    const outcome = await client.handleHostedAuthorizationCallback(
+      `${REDIRECT_URI}?code=${AUTH_CODE}&state=forged`,
+    );
+    expect(outcome).toEqual({ ok: false, error: { type: "state_mismatch" } });
+  });
+
+  test("callback carrying an OAuth error surfaces the validated code", async () => {
+    const client = makeClient(createFetchStub(() => jsonResponse(200, {})).fetchPort);
+    const outcome = await client.handleHostedAuthorizationCallback(
+      `${REDIRECT_URI}?error=access_denied&error_description=user+refused`,
+    );
+    expect(outcome.ok).toBe(false);
+    if (!outcome.ok) {
+      expect(outcome.error).toMatchObject({
+        type: "oauth_error",
+        code: "access_denied",
+        description: "user refused",
+      });
+    }
+  });
+});
+
+describe("getPublicConfig (design.md §16.2)", () => {
+  test("GETs /v1/config with client_id and validates the payload", async () => {
+    const { calls, fetchPort } = createFetchStub(() => jsonResponse(200, PUBLIC_CONFIG));
+    const client = makeClient(fetchPort);
+    const outcome = await client.getPublicConfig();
+    expect(outcome.ok).toBe(true);
+    if (outcome.ok) {
+      expect(outcome.value.issuer).toBe(ISSUER);
+      expect(outcome.value.rp_id).toBe("example.com");
+    }
+    expect(calls[0]?.method).toBe("GET");
+    expect(calls[0]?.url).toBe(`${BASE_URL}/v1/config?client_id=${CLIENT_ID}`);
+  });
+
+  test("a config payload leaking an internal field is rejected (strictObject defense)", async () => {
+    const { fetchPort } = createFetchStub(() =>
+      jsonResponse(200, { ...PUBLIC_CONFIG, internal_shard: "shard-7" }),
+    );
+    const client = makeClient(fetchPort);
+    const outcome = await client.getPublicConfig();
+    expect(outcome.ok).toBe(false);
+    if (!outcome.ok) expect(outcome.error.type).toBe("invalid_response");
+  });
+
+  test("issuer discovery: token exchange works without a configured issuer", async () => {
+    const { calls, fetchPort } = createFetchStub((req) => {
+      if (req.url.startsWith(`${BASE_URL}/v1/config`)) return jsonResponse(200, PUBLIC_CONFIG);
+      if (req.url.endsWith("/v1/auth/transactions")) return jsonResponse(200, CREATE_RESPONSE);
+      if (req.url.endsWith("/complete")) {
+        const state = (
+          calls.find((c) => c.url.endsWith("/v1/auth/transactions"))?.body as Record<
+            string,
+            unknown
+          >
+        )["state"];
+        return jsonResponse(200, {
+          authorization_code: AUTH_CODE,
+          state,
+          redirect_uri: REDIRECT_URI,
+        });
+      }
+      return jsonResponse(200, {
+        access_token: "at_discovered",
+        token_type: "Bearer",
+        expires_in: 300,
+        scope: "openid profile email",
+      });
+    });
+    const client = createBrowserAuthClient({
+      baseUrl: BASE_URL,
+      clientId: CLIENT_ID,
+      redirectUri: REDIRECT_URI,
+      fetch: fetchPort,
+    });
+    const created = await client.createTransaction();
+    expect(created.ok).toBe(true);
+    if (!created.ok) return;
+    const completed = await client.completeTransaction(created.value.transactionId);
+    expect(completed.ok).toBe(true);
+    if (!completed.ok) return;
+    const exchanged = await client.exchangeAuthorizationCode({
+      code: completed.value.authorization_code,
+      state: completed.value.state,
+    });
+    expect(exchanged.ok).toBe(true);
+    // The issuer was discovered lazily via /v1/config, and that fetch must
+    // have happened before the token exchange that consumed it.
+    const configIndex = calls.findIndex(
+      (c) => c.url === `${BASE_URL}/v1/config?client_id=${CLIENT_ID}`,
+    );
+    const tokenIndex = calls.findIndex((c) => c.url.endsWith("/oauth2/token"));
+    expect(configIndex).toBeGreaterThanOrEqual(0);
+    expect(tokenIndex).toBeGreaterThan(configIndex);
+    expect(calls[tokenIndex]?.url).toBe(`${ISSUER}/oauth2/token`);
+  });
+});