@smartcrab/browser 0.1.0

package/src/client-me.test.ts

@@ -0,0 +1,321 @@
+import { describe, expect, test } from "vitest";
+import { createBrowserAuthClient } from "./client.js";
+import type { FetchPort } from "./http.js";
+
+/**
+ * The `/v1/me` self-service surface (design.md §16.2): every route is
+ * Bearer-authenticated with the in-memory token, requests match the contract
+ * shapes, and responses are schema-validated.
+ */
+
+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 USER_ID = `usr_${"c".repeat(32)}`;
+const SESSION_ID = `ses_${"d".repeat(32)}`;
+const PASSKEY_ID = `psk_${"e".repeat(32)}`;
+const IDENTITY_ID = `idn_${"f".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 jsonResponse = (status: number, body: unknown): Response =>
+  new Response(JSON.stringify(body), { status });
+
+const ME_USER = {
+  user_id: USER_ID,
+  email: "user@example.com",
+  email_verified: true,
+  name: "Ada Lovelace",
+  avatar_url: null,
+  locale: "en-US",
+  timezone: "UTC",
+  status: "active",
+  created_at: "2026-08-02T08:10:00Z",
+  last_login_at: null,
+};
+
+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 SESSION_SUMMARY = {
+  session_id: SESSION_ID,
+  client_id: CLIENT_ID,
+  device_name: "Chrome on macOS",
+  created_at: "2026-08-01T08:00:00Z",
+  last_active_at: "2026-08-05T07:00:00Z",
+  current: true,
+};
+
+const IDENTITY_SUMMARY = {
+  identity_id: IDENTITY_ID,
+  provider: "google",
+  linked_at: "2026-08-01T08:00:00Z",
+  last_used_at: null,
+};
+
+/**
+ * Fetch stub that serves the sign-in path (create/complete/token) and then
+ * routes every `/v1/me*` call to `onMe`.
+ */
+const createStub = (onMe: (req: CapturedRequest) => 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);
+    if (url.endsWith("/v1/auth/transactions")) {
+      return Promise.resolve(
+        jsonResponse(200, {
+          transaction_id: TXN_ID,
+          expires_at: "2026-08-05T08:10:00Z",
+          available_methods: ["email_otp"],
+        }),
+      );
+    }
+    if (url.endsWith("/complete")) {
+      const state = (
+        calls.find((c) => c.url.endsWith("/v1/auth/transactions"))?.body as Record<string, unknown>
+      )["state"];
+      return Promise.resolve(
+        jsonResponse(200, { authorization_code: AUTH_CODE, state, redirect_uri: REDIRECT_URI }),
+      );
+    }
+    if (url.endsWith("/oauth2/token")) {
+      return Promise.resolve(
+        jsonResponse(200, {
+          access_token: "at_me",
+          token_type: "Bearer",
+          expires_in: 300,
+          scope: "openid profile email",
+        }),
+      );
+    }
+    return Promise.resolve(onMe(captured));
+  };
+  return { calls, fetchPort };
+};
+
+const createSignedInClient = async (fetchPort: FetchPort) => {
+  const client = createBrowserAuthClient({
+    baseUrl: BASE_URL,
+    clientId: CLIENT_ID,
+    redirectUri: REDIRECT_URI,
+    issuer: ISSUER,
+    fetch: fetchPort,
+  });
+  const created = await client.createTransaction();
+  if (!created.ok) throw new Error("setup failed");
+  const completed = await client.completeTransaction(created.value.transactionId);
+  if (!completed.ok) throw new Error("setup failed");
+  const exchanged = await client.exchangeAuthorizationCode({
+    code: completed.value.authorization_code,
+    state: completed.value.state,
+  });
+  if (!exchanged.ok) throw new Error("setup failed");
+  return client;
+};
+
+describe("/v1/me surface (design.md §16.2)", () => {
+  test("getMe sends the Bearer token and parses the profile", async () => {
+    const { calls, fetchPort } = createStub(() => jsonResponse(200, ME_USER));
+    const client = await createSignedInClient(fetchPort);
+    const outcome = await client.getMe();
+    expect(outcome.ok).toBe(true);
+    if (outcome.ok) expect(outcome.value.user_id).toBe(USER_ID);
+    const meCall = calls.find((c) => c.url === `${BASE_URL}/v1/me`);
+    expect(meCall?.method).toBe("GET");
+    expect(meCall?.headers["authorization"]).toBe("Bearer at_me");
+  });
+
+  test("updateMe PATCHes the editable fields only (design.md §12.1: email excluded)", async () => {
+    const { calls, fetchPort } = createStub(() => jsonResponse(200, ME_USER));
+    const client = await createSignedInClient(fetchPort);
+    const outcome = await client.updateMe({ name: "Grace Hopper", locale: "ja-JP" });
+    expect(outcome.ok).toBe(true);
+    const patch = calls.find((c) => c.url === `${BASE_URL}/v1/me` && c.method === "PATCH");
+    expect(patch?.body).toEqual({ name: "Grace Hopper", locale: "ja-JP" });
+  });
+
+  test("a malformed profile is invalid_response", async () => {
+    const { fetchPort } = createStub(() => jsonResponse(200, { user_id: "nope" }));
+    const client = await createSignedInClient(fetchPort);
+    const outcome = await client.getMe();
+    expect(outcome.ok).toBe(false);
+    if (!outcome.ok) expect(outcome.error.type).toBe("invalid_response");
+  });
+
+  test("passkey list / register-verify / delete hit the contract routes", async () => {
+    const { calls, fetchPort } = createStub((req) => {
+      if (req.url.endsWith("/v1/me/passkeys"))
+        return jsonResponse(200, { passkeys: [PASSKEY_SUMMARY] });
+      if (req.url.endsWith("/registration/verify"))
+        return jsonResponse(200, { passkey: PASSKEY_SUMMARY });
+      if (req.url.endsWith(`/v1/me/passkeys/${PASSKEY_ID}`)) {
+        return jsonResponse(200, { passkey_id: PASSKEY_ID, deleted: true });
+      }
+      return jsonResponse(500, {});
+    });
+    const client = await createSignedInClient(fetchPort);
+
+    const list = await client.listMyPasskeys();
+    expect(list.ok).toBe(true);
+    if (list.ok) expect(list.value.passkeys).toHaveLength(1);
+
+    const verified = await client.verifyMyPasskeyRegistration({
+      credential: {
+        id: "Y3JlZA",
+        rawId: "Y3JlZA",
+        type: "public-key",
+        response: { clientDataJSON: "Y2xpZW50", attestationObject: "YXR0ZXN0" },
+      },
+      name: "MacBook",
+    });
+    expect(verified.ok).toBe(true);
+    const verifyCall = calls.find((c) => c.url.endsWith("/v1/me/passkeys/registration/verify"));
+    expect(verifyCall?.method).toBe("POST");
+    expect((verifyCall?.body as Record<string, unknown>)["name"]).toBe("MacBook");
+
+    const deleted = await client.deleteMyPasskey(PASSKEY_ID);
+    expect(deleted.ok).toBe(true);
+    const deleteCall = calls.find((c) => c.url.endsWith(`/v1/me/passkeys/${PASSKEY_ID}`));
+    expect(deleteCall?.method).toBe("DELETE");
+  });
+
+  test("identities list / link / unlink", async () => {
+    const { calls, fetchPort } = createStub((req) => {
+      if (req.url.endsWith("/v1/me/identities"))
+        return jsonResponse(200, { identities: [IDENTITY_SUMMARY] });
+      if (req.url.endsWith("/link")) {
+        return jsonResponse(200, {
+          authorization_url: "https://accounts.google.com/o/oauth2/v2/auth?x=1",
+        });
+      }
+      return jsonResponse(200, { identity_id: IDENTITY_ID, unlinked: true });
+    });
+    const client = await createSignedInClient(fetchPort);
+
+    const list = await client.listMyIdentities();
+    expect(list.ok).toBe(true);
+    if (list.ok) expect(list.value.identities[0]?.provider).toBe("google");
+
+    const linked = await client.linkMyIdentity("google", {
+      redirect_uri: "https://app.example.com/settings",
+    });
+    expect(linked.ok).toBe(true);
+    const linkCall = calls.find((c) => c.url.endsWith("/v1/me/identities/google/link"));
+    expect(linkCall?.method).toBe("POST");
+    expect(linkCall?.body).toEqual({ redirect_uri: "https://app.example.com/settings" });
+
+    const unlinked = await client.unlinkMyIdentity(IDENTITY_ID);
+    expect(unlinked.ok).toBe(true);
+    const unlinkCall = calls.find((c) => c.url.endsWith(`/v1/me/identities/${IDENTITY_ID}`));
+    expect(unlinkCall?.method).toBe("DELETE");
+  });
+
+  test("sessions list / revoke / revoke-all", async () => {
+    const { calls, fetchPort } = createStub((req) => {
+      if (req.url.endsWith("/v1/me/sessions") && req.method === "GET") {
+        return jsonResponse(200, { sessions: [SESSION_SUMMARY] });
+      }
+      if (req.url.endsWith("/v1/me/sessions") && req.method === "DELETE") {
+        return jsonResponse(200, { revoked: true });
+      }
+      return jsonResponse(200, { session_id: SESSION_ID, revoked: true });
+    });
+    const client = await createSignedInClient(fetchPort);
+
+    const list = await client.listMySessions();
+    expect(list.ok).toBe(true);
+    if (list.ok) expect(list.value.sessions[0]?.current).toBe(true);
+
+    const revoked = await client.revokeMySession(SESSION_ID);
+    expect(revoked.ok).toBe(true);
+    const revokeCall = calls.find((c) => c.url.endsWith(`/v1/me/sessions/${SESSION_ID}`));
+    expect(revokeCall?.method).toBe("DELETE");
+
+    const revokedAll = await client.revokeAllMySessions();
+    expect(revokedAll.ok).toBe(true);
+  });
+
+  test("email change: start → verify-old → verify-new (design.md §25)", async () => {
+    const { calls, fetchPort } = createStub((req) => {
+      if (req.url.endsWith("/email/change/start")) {
+        return jsonResponse(200, { challenge_id: "chal_old", expires_at: "2026-08-05T08:05:00Z" });
+      }
+      if (req.url.endsWith("/email/change/verify-old")) {
+        return jsonResponse(200, { challenge_id: "chal_new", expires_at: "2026-08-05T08:06:00Z" });
+      }
+      return jsonResponse(200, { email: "new@example.com", email_verified: true });
+    });
+    const client = await createSignedInClient(fetchPort);
+
+    const started = await client.startMyEmailChange({ new_email: "new@example.com" });
+    expect(started.ok).toBe(true);
+    if (started.ok) expect(started.value.challenge_id).toBe("chal_old");
+    const startCall = calls.find((c) => c.url.endsWith("/email/change/start"));
+    expect(startCall?.body).toEqual({ new_email: "new@example.com" });
+
+    const verifiedOld = await client.verifyMyEmailChangeOld({
+      challenge_id: "chal_old",
+      code: "123456",
+    });
+    expect(verifiedOld.ok).toBe(true);
+    if (verifiedOld.ok) expect(verifiedOld.value.challenge_id).toBe("chal_new");
+
+    const verifiedNew = await client.verifyMyEmailChangeNew({
+      challenge_id: "chal_new",
+      code: "654321",
+    });
+    expect(verifiedNew.ok).toBe(true);
+    if (verifiedNew.ok) {
+      expect(verifiedNew.value.email).toBe("new@example.com");
+      expect(verifiedNew.value.email_verified).toBe(true);
+    }
+  });
+
+  test("deleteMyAccount issues DELETE /v1/me and parses pending_deletion", async () => {
+    const { calls, fetchPort } = createStub(() =>
+      jsonResponse(200, { user_id: USER_ID, status: "pending_deletion" }),
+    );
+    const client = await createSignedInClient(fetchPort);
+    const outcome = await client.deleteMyAccount();
+    expect(outcome.ok).toBe(true);
+    if (outcome.ok) expect(outcome.value.status).toBe("pending_deletion");
+    const deleteCall = calls.find((c) => c.url === `${BASE_URL}/v1/me` && c.method === "DELETE");
+    expect(deleteCall).toBeDefined();
+  });
+
+  test("me calls without a session resolve not_authenticated without any HTTP call", async () => {
+    const { calls, fetchPort } = createStub(() => jsonResponse(200, ME_USER));
+    const client = createBrowserAuthClient({
+      baseUrl: BASE_URL,
+      clientId: CLIENT_ID,
+      redirectUri: REDIRECT_URI,
+      issuer: ISSUER,
+      fetch: fetchPort,
+    });
+    const outcome = await client.getMe();
+    expect(outcome).toEqual({ ok: false, error: { type: "not_authenticated" } });
+    expect(calls).toHaveLength(0);
+  });
+});

package/src/client-tokens.test.ts

@@ -0,0 +1,378 @@
+import { afterEach, describe, expect, test, vi } from "vitest";
+import { createBrowserAuthClient } from "./client.js";
+import type { BrowserAuthClient, RefreshTokenStoragePort } from "./client.js";
+import type { FetchPort } from "./http.js";
+
+/**
+ * Token lifecycle (design.md §22.3, §21.7):
+ * - access and refresh tokens stay in memory by default; only transient PKCE callback state uses sessionStorage
+ * - refresh persistence is opt-in; rotation replaces the stored value
+ * - concurrent refresh is deduped to one network call
+ * - invalid_grant wipes the local session; transient failures do not
+ */
+
+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 AUTH_CODE = `ac_${"g".repeat(32)}`;
+const REDIRECT_URI = "https://app.example.com/oauth/callback";
+
+interface CapturedRequest {
+  url: string;
+  method: string;
+  body: unknown;
+}
+
+const parseJson = (text: string): unknown => JSON.parse(text);
+
+const jsonResponse = (status: number, body: unknown, headers?: Record<string, string>): Response =>
+  new Response(JSON.stringify(body), { status, ...(headers !== undefined ? { headers } : {}) });
+
+const tokenBody = (overrides?: Record<string, unknown>) => ({
+  access_token: "at_1",
+  token_type: "Bearer",
+  expires_in: 300,
+  scope: "openid profile email offline_access",
+  ...overrides,
+});
+
+interface Stub {
+  calls: CapturedRequest[];
+  fetchPort: FetchPort;
+}
+
+/**
+ * A fetch stub covering transaction create/complete; everything else (token,
+ * revocation) is delegated to `onApi`. Self-referential so the `/complete`
+ * handler can echo back the `state` issued at create time.
+ */
+const createStub = (onApi: (req: CapturedRequest) => Response | Promise<Response>): Stub => {
+  const stub: Stub = {
+    calls: [],
+    fetchPort: (url, init) => {
+      const captured: CapturedRequest = {
+        url,
+        method: init.method ?? "GET",
+        body: typeof init.body === "string" ? parseJson(init.body) : undefined,
+      };
+      stub.calls.push(captured);
+      if (url.endsWith("/v1/auth/transactions")) {
+        return Promise.resolve(
+          jsonResponse(200, {
+            transaction_id: TXN_ID,
+            expires_at: "2026-08-05T08:10:00Z",
+            available_methods: ["email_otp"],
+          }),
+        );
+      }
+      if (url.endsWith("/complete")) {
+        const createCall = stub.calls.find((c) => c.url.endsWith("/v1/auth/transactions"));
+        const state = (createCall?.body as Record<string, unknown>)["state"];
+        return Promise.resolve(
+          jsonResponse(200, { authorization_code: AUTH_CODE, state, redirect_uri: REDIRECT_URI }),
+        );
+      }
+      return Promise.resolve(onApi(captured));
+    },
+  };
+  return stub;
+};
+
+const createClient = (
+  fetchPort: FetchPort,
+  options?: { storage?: RefreshTokenStoragePort; now?: () => number },
+): BrowserAuthClient =>
+  createBrowserAuthClient({
+    baseUrl: BASE_URL,
+    clientId: CLIENT_ID,
+    redirectUri: REDIRECT_URI,
+    issuer: ISSUER,
+    scope: "openid profile email offline_access",
+    fetch: fetchPort,
+    ...(options?.storage !== undefined ? { refreshTokenStorage: options.storage } : {}),
+    ...(options?.now !== undefined ? { now: options.now } : {}),
+  });
+
+/** Drives create → complete → exchange so the client holds a token set. */
+const signIn = async (client: BrowserAuthClient) => {
+  const created = await client.createTransaction();
+  if (!created.ok) throw new Error("setup failed at createTransaction");
+  const completed = await client.completeTransaction(created.value.transactionId);
+  if (!completed.ok) throw new Error("setup failed at completeTransaction");
+  const exchanged = await client.exchangeAuthorizationCode({
+    code: completed.value.authorization_code,
+    state: completed.value.state,
+  });
+  if (!exchanged.ok) throw new Error("setup failed at exchange");
+  return exchanged.value;
+};
+
+interface MemoryStorage extends RefreshTokenStoragePort {
+  saved: string[];
+  cleared: number;
+  stored: string | null;
+}
+
+const createMemoryStorage = (): MemoryStorage => {
+  const storage: MemoryStorage = {
+    saved: [],
+    cleared: 0,
+    stored: null,
+    load() {
+      return storage.stored;
+    },
+    save(refreshToken: string) {
+      storage.saved.push(refreshToken);
+      storage.stored = refreshToken;
+    },
+    clear() {
+      storage.cleared += 1;
+      storage.stored = null;
+    },
+  };
+  return storage;
+};
+
+describe("access token memory rules (design.md §22.3)", () => {
+  afterEach(() => {
+    Reflect.deleteProperty(globalThis, "localStorage");
+    Reflect.deleteProperty(globalThis, "sessionStorage");
+  });
+
+  test("only transient PKCE metadata, never tokens, reaches Web Storage", async () => {
+    const localSetItem = vi.fn((_key: string, _value: string): void => undefined);
+    const sessionValues: string[] = [];
+    const sessionSetItem = vi.fn((_key: string, value: string): void => {
+      sessionValues.push(value);
+    });
+    const shim = (setItem: (key: string, value: string) => void): Storage => ({
+      length: 0,
+      clear: () => undefined,
+      getItem: () => null,
+      key: () => null,
+      removeItem: () => undefined,
+      setItem,
+    });
+    Object.defineProperty(globalThis, "localStorage", {
+      value: shim(localSetItem),
+      configurable: true,
+    });
+    Object.defineProperty(globalThis, "sessionStorage", {
+      value: shim(sessionSetItem),
+      configurable: true,
+    });
+
+    const stub = createStub(() => jsonResponse(200, tokenBody({ refresh_token: "rt_1" })));
+    const client = createClient(stub.fetchPort);
+    await signIn(client);
+    const token = await client.getAccessToken();
+    expect(token).toEqual({ ok: true, value: "at_1" });
+
+    expect(localSetItem).not.toHaveBeenCalled();
+    expect(sessionSetItem).toHaveBeenCalledTimes(1);
+    const pending = JSON.parse(sessionValues[0] ?? "{}") as Record<string, unknown>;
+    expect(Object.keys(pending).sort()).toEqual([
+      "codeVerifier",
+      "createdAt",
+      "nonce",
+      "redirectUri",
+      "state",
+    ]);
+    expect(sessionValues.join("")).not.toContain("at_1");
+    expect(sessionValues.join("")).not.toContain("rt_1");
+  });
+
+  test("the auth snapshot exposes metadata but never raw tokens", async () => {
+    const stub = createStub(() => jsonResponse(200, tokenBody({ refresh_token: "rt_1" })));
+    const client = createClient(stub.fetchPort);
+    await signIn(client);
+    const snapshot = client.getSnapshot();
+    expect(snapshot.status).toBe("signed_in");
+    expect(snapshot.hasRefreshToken).toBe(true);
+    expect(JSON.stringify(snapshot)).not.toContain("at_1");
+    expect(JSON.stringify(snapshot)).not.toContain("rt_1");
+  });
+
+  test("subscribers observe sign-in and sign-out transitions, and unsubscribe works", async () => {
+    const stub = createStub(() => jsonResponse(200, tokenBody({ refresh_token: "rt_1" })));
+    const client = createClient(stub.fetchPort);
+    const events: string[] = [];
+    const unsubscribe = client.subscribe((snapshot) => events.push(snapshot.status));
+
+    await signIn(client);
+    await client.signOut();
+    expect(events).toEqual(["signed_in", "signed_out"]);
+
+    unsubscribe();
+    await client.signOut();
+    expect(events).toHaveLength(2);
+  });
+});
+
+describe("refresh token persistence opt-in (design.md §22.3)", () => {
+  test("default: in-memory only, flow succeeds with no storage anywhere", async () => {
+    const stub = createStub(() => jsonResponse(200, tokenBody({ refresh_token: "rt_1" })));
+    const client = createClient(stub.fetchPort);
+    const session = await signIn(client);
+    expect(session.hasRefreshToken).toBe(true);
+    expect(client.getSnapshot().hasRefreshToken).toBe(true);
+  });
+
+  test("opt-in storage receives the refresh token on exchange and on rotation", async () => {
+    const storage = createMemoryStorage();
+    const stub = createStub((req) => {
+      const body = req.body as Record<string, unknown>;
+      if (body["grant_type"] === "refresh_token") {
+        return jsonResponse(200, tokenBody({ access_token: "at_2", refresh_token: "rt_2" }));
+      }
+      return jsonResponse(200, tokenBody({ refresh_token: "rt_1" }));
+    });
+    const client = createClient(stub.fetchPort, { storage });
+    await signIn(client);
+    expect(storage.saved).toEqual(["rt_1"]);
+
+    const refreshed = await client.refreshSession();
+    expect(refreshed.ok).toBe(true);
+    expect(storage.saved).toEqual(["rt_1", "rt_2"]);
+
+    // The refresh grant used the previous (now-rotated-out) token.
+    const refreshCall = stub.calls.find(
+      (c) => (c.body as Record<string, unknown> | undefined)?.["grant_type"] === "refresh_token",
+    );
+    expect((refreshCall?.body as Record<string, unknown>)["refresh_token"]).toBe("rt_1");
+  });
+
+  test("restoreSession loads the persisted token and rotates it into memory", async () => {
+    const storage = createMemoryStorage();
+    storage.stored = "rt_persisted";
+    const stub = createStub((req) => {
+      const body = req.body as Record<string, unknown>;
+      expect(body["grant_type"]).toBe("refresh_token");
+      expect(body["refresh_token"]).toBe("rt_persisted");
+      return jsonResponse(
+        200,
+        tokenBody({ access_token: "at_restored", refresh_token: "rt_fresh" }),
+      );
+    });
+    const client = createClient(stub.fetchPort, { storage });
+    const restored = await client.restoreSession();
+    expect(restored.ok).toBe(true);
+    const token = await client.getAccessToken();
+    expect(token).toEqual({ ok: true, value: "at_restored" });
+    expect(storage.stored).toBe("rt_fresh");
+  });
+
+  test("restoreSession without opt-in storage resolves not_authenticated", async () => {
+    const client = createClient(createStub(() => jsonResponse(200, {})).fetchPort);
+    const outcome = await client.restoreSession();
+    expect(outcome).toEqual({ ok: false, error: { type: "not_authenticated" } });
+  });
+
+  test("restoreSession with an empty store resolves not_authenticated", async () => {
+    const storage = createMemoryStorage();
+    const client = createClient(createStub(() => jsonResponse(200, {})).fetchPort, { storage });
+    const outcome = await client.restoreSession();
+    expect(outcome).toEqual({ ok: false, error: { type: "not_authenticated" } });
+  });
+});
+
+describe("refresh semantics (design.md §21.7, §32.1)", () => {
+  test("concurrent getAccessToken on an expired token dedupes to one refresh request", async () => {
+    let nowMs = 1_000_000;
+    let refreshCalls = 0;
+    const stub = createStub((req) => {
+      const body = req.body as Record<string, unknown>;
+      if (body["grant_type"] === "refresh_token") {
+        refreshCalls += 1;
+        return jsonResponse(
+          200,
+          tokenBody({ access_token: "at_refreshed", refresh_token: "rt_2" }),
+        );
+      }
+      return jsonResponse(200, tokenBody({ refresh_token: "rt_1" }));
+    });
+    const client = createClient(stub.fetchPort, { now: () => nowMs });
+    await signIn(client);
+
+    nowMs += 400_000; // access token (300s TTL) is now expired
+    const [a, b, c] = await Promise.all([
+      client.getAccessToken(),
+      client.getAccessToken(),
+      client.getAccessToken(),
+    ]);
+    expect(a).toEqual({ ok: true, value: "at_refreshed" });
+    expect(b).toEqual({ ok: true, value: "at_refreshed" });
+    expect(c).toEqual({ ok: true, value: "at_refreshed" });
+    expect(refreshCalls).toBe(1);
+  });
+
+  test("invalid_grant on refresh wipes the local session and the opt-in store", async () => {
+    const storage = createMemoryStorage();
+    const stub = createStub((req) => {
+      const body = req.body as Record<string, unknown>;
+      if (body["grant_type"] === "refresh_token") {
+        return jsonResponse(400, {
+          error: "invalid_grant",
+          error_description: "refresh token replayed",
+        });
+      }
+      return jsonResponse(200, tokenBody({ refresh_token: "rt_1" }));
+    });
+    const client = createClient(stub.fetchPort, { storage });
+    await signIn(client);
+    expect(storage.stored).toBe("rt_1");
+
+    const refreshed = await client.refreshSession();
+    expect(refreshed.ok).toBe(false);
+    if (!refreshed.ok) {
+      expect(refreshed.error).toMatchObject({ type: "oauth_error", code: "invalid_grant" });
+    }
+    expect(client.getSnapshot().status).toBe("signed_out");
+    expect(storage.cleared).toBe(1);
+    expect(storage.stored).toBeNull();
+    const token = await client.getAccessToken();
+    expect(token).toEqual({ ok: false, error: { type: "not_authenticated" } });
+  });
+
+  test("a transient network failure on refresh keeps the session", async () => {
+    const stub = createStub((req) => {
+      const body = req.body as Record<string, unknown>;
+      if (body["grant_type"] === "refresh_token") {
+        return Promise.reject(new TypeError("Failed to fetch"));
+      }
+      return jsonResponse(200, tokenBody({ refresh_token: "rt_1" }));
+    });
+    const client = createClient(stub.fetchPort);
+    await signIn(client);
+    const refreshed = await client.refreshSession();
+    expect(refreshed.ok).toBe(false);
+    if (!refreshed.ok) expect(refreshed.error.type).toBe("network_error");
+    // Session survives transient failures (design.md §21.7).
+    expect(client.getSnapshot().status).toBe("signed_in");
+  });
+
+  test("signOut revokes the refresh token best-effort and clears memory", async () => {
+    const stub = createStub((req) => {
+      const url = req.url;
+      if (url.endsWith("/oauth2/revoke")) return new Response("", { status: 200 });
+      return jsonResponse(200, tokenBody({ refresh_token: "rt_1" }));
+    });
+    const client = createClient(stub.fetchPort);
+    await signIn(client);
+    const signedOut = await client.signOut();
+    expect(signedOut).toEqual({ ok: true, value: { signedOut: true } });
+    expect(client.getSnapshot().status).toBe("signed_out");
+
+    const revokeCall = stub.calls.find((c) => c.url.endsWith("/oauth2/revoke"));
+    expect(revokeCall).toBeDefined();
+    expect(revokeCall?.body).toMatchObject({
+      token: "rt_1",
+      token_type_hint: "refresh_token",
+      client_id: CLIENT_ID,
+    });
+
+    const token = await client.getAccessToken();
+    expect(token).toEqual({ ok: false, error: { type: "not_authenticated" } });
+  });
+});