@smartcrab/browser 0.1.0

package/src/errors.ts

@@ -0,0 +1,154 @@
+import type { OAuthErrorCode } from "@smartcrab/contracts-public";
+
+/**
+ * Error model for `@smartcrab/browser` (design.md §26.3, §32).
+ *
+ * Every client method resolves to `Outcome<T, BrowserAuthError>`; nothing
+ * throws for expected failure modes. The union mirrors what the public API
+ * can actually put on the wire:
+ *
+ * - `network_error` — fetch itself failed (DNS, TLS, abort, CORS). Retryable.
+ * - `invalid_response` — a 2xx body failed the contracts-public zod schema,
+ *   an error body was not Problem Details / OAuth error shaped, or the body
+ *   was not JSON at all. Never trust the wire (IMPL_NOTES §1).
+ * - `rate_limited` — HTTP 429; `retryAfterSeconds` reflects the `Retry-After`
+ *   header when present (design.md §22's rate limit surface).
+ * - `problem_details` — RFC 9457 body from the API (`code` is the snake_case
+ *   platform error code, e.g. `invalid_request`, `not_found`).
+ * - `oauth_error` — RFC 6749 §5.2 error from the token endpoint (the
+ *   `OAUTH_ERROR_CODES` set from contracts-public).
+ * - `state_mismatch` — an authorization/complete callback carried a `state`
+ *   the client never issued (CSRF/replay protection, design.md §32.1).
+ * - `not_authenticated` — a token was required but none is held and no
+ *   refresh path exists.
+ * - `webauthn_error` — the platform authenticator ceremony failed or is
+ *   unavailable (design.md §17, §21.2 normalization rule).
+ */
+
+export interface NetworkFailureError {
+  readonly type: "network_error";
+  readonly message: string;
+  readonly retryable: true;
+}
+
+export interface InvalidResponseError {
+  readonly type: "invalid_response";
+  readonly message: string;
+  /** HTTP status of the offending response, when a response was received at all. */
+  readonly status?: number;
+}
+
+export interface RateLimitedError {
+  readonly type: "rate_limited";
+  readonly retryable: true;
+  /** Whole-second delay from the `Retry-After` header; absent when the server sent none. */
+  readonly retryAfterSeconds?: number;
+  readonly requestId?: string;
+}
+
+export interface ProblemDetailsError {
+  readonly type: "problem_details";
+  /** `type` URI from the Problem Details body. */
+  readonly problemType: string;
+  /** Platform snake_case error code (`code` extension member). */
+  readonly code: string;
+  readonly title: string;
+  readonly status: number;
+  readonly detail?: string;
+  readonly requestId?: string;
+}
+
+export interface OAuthFailureError {
+  readonly type: "oauth_error";
+  readonly code: OAuthErrorCode;
+  readonly description?: string;
+  /** HTTP status for token-endpoint errors; absent for front-channel (redirect) errors. */
+  readonly status?: number;
+}
+
+export interface StateMismatchError {
+  readonly type: "state_mismatch";
+}
+
+export interface NotAuthenticatedError {
+  readonly type: "not_authenticated";
+}
+
+export type WebAuthnFailureReason = "not_supported" | "cancelled" | "failed";
+
+export interface WebAuthnFailureError {
+  readonly type: "webauthn_error";
+  readonly reason: WebAuthnFailureReason;
+  readonly message: string;
+}
+
+export type BrowserAuthError =
+  | NetworkFailureError
+  | InvalidResponseError
+  | RateLimitedError
+  | ProblemDetailsError
+  | OAuthFailureError
+  | StateMismatchError
+  | NotAuthenticatedError
+  | WebAuthnFailureError;
+
+// ---------------------------------------------------------------------------
+// Wire guards (this package has no zod dependency — see package.json — so the
+// two error body shapes are validated with hand-rolled narrowing instead of a
+// schema; the success path always goes through contracts-public schemas).
+// ---------------------------------------------------------------------------
+
+/** Validated RFC 9457 Problem Details body as sent by the platform (design.md §26.3). */
+export interface ProblemDetailsWire {
+  readonly type: string;
+  readonly title: string;
+  readonly status: number;
+  readonly detail?: string;
+  readonly code?: string;
+  readonly requestId?: string;
+}
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/**
+ * Narrows an already-JSON-parsed body to the Problem Details shape. Field
+ * types are checked one by one; extension members are ignored (carried by the
+ * server for its own diagnostics, not part of the client contract).
+ */
+export const parseProblemDetailsWire = (value: unknown): ProblemDetailsWire | null => {
+  if (!isPlainObject(value)) return null;
+  if (typeof value["type"] !== "string" || typeof value["title"] !== "string") return null;
+  if (typeof value["status"] !== "number" || !Number.isInteger(value["status"])) return null;
+  const detail = value["detail"];
+  const code = value["code"];
+  const requestId = value["request_id"];
+  if (detail !== undefined && typeof detail !== "string") return null;
+  if (code !== undefined && typeof code !== "string") return null;
+  if (requestId !== undefined && typeof requestId !== "string") return null;
+  return {
+    type: value["type"],
+    title: value["title"],
+    status: value["status"],
+    ...(detail !== undefined ? { detail } : {}),
+    ...(code !== undefined ? { code } : {}),
+    ...(requestId !== undefined ? { requestId } : {}),
+  };
+};
+
+/** Validated RFC 6749 §5.2 error body (token endpoint). */
+export interface OAuthErrorWire {
+  readonly error: string;
+  readonly description?: string;
+}
+
+export const parseOAuthErrorWire = (value: unknown): OAuthErrorWire | null => {
+  if (!isPlainObject(value)) return null;
+  if (typeof value["error"] !== "string" || value["error"].length === 0) return null;
+  const description = value["error_description"];
+  if (description !== undefined && typeof description !== "string") return null;
+  return {
+    error: value["error"],
+    ...(description !== undefined ? { description } : {}),
+  };
+};

package/src/http.test.ts

@@ -0,0 +1,225 @@
+import { describe, expect, test } from "vitest";
+import { buildUrl, requestJson } from "./http.js";
+import type { FetchPort, WireSchema } from "./http.js";
+
+/**
+ * Transport-level error normalization (design.md §26.3 Problem Details,
+ * RFC 6749 §5.2 OAuth errors, rate limiting with Retry-After).
+ */
+
+/** A trivial schema standing in for the contracts-public zod schemas. */
+const stringSchema: WireSchema<{ value: string }> = {
+  safeParse(input) {
+    if (
+      typeof input === "object" &&
+      input !== null &&
+      "value" in input &&
+      typeof input.value === "string"
+    ) {
+      return { success: true, data: { value: input.value } };
+    }
+    return { success: false, error: new Error("bad shape") };
+  },
+};
+
+const jsonResponse = (status: number, body: unknown, headers?: Record<string, string>): Response =>
+  new Response(JSON.stringify(body), { status, ...(headers !== undefined ? { headers } : {}) });
+
+const fetchReturning =
+  (response: Response): FetchPort =>
+  () =>
+    Promise.resolve(response);
+
+const fetchRejecting =
+  (cause: unknown): FetchPort =>
+  () =>
+    Promise.reject(cause);
+
+describe("requestJson — success path", () => {
+  test("serializes method, headers and JSON body exactly", async () => {
+    const seen: { url?: string; init?: RequestInit } = {};
+    const fetchPort: FetchPort = (url, init) => {
+      seen.url = url;
+      seen.init = init;
+      return Promise.resolve(jsonResponse(200, { value: "ok" }));
+    };
+    const outcome = await requestJson(
+      fetchPort,
+      { method: "POST", url: "https://id.example.com/v1/x", body: { a: 1 }, accessToken: "at_1" },
+      stringSchema,
+    );
+    expect(outcome).toEqual({ ok: true, value: { value: "ok" } });
+    expect(seen.init?.method).toBe("POST");
+    expect(new Headers(seen.init?.headers).get("content-type")).toBe("application/json");
+    expect(new Headers(seen.init?.headers).get("authorization")).toBe("Bearer at_1");
+    expect(new Headers(seen.init?.headers).get("accept")).toBe("application/json");
+    expect(seen.init?.body).toBe(JSON.stringify({ a: 1 }));
+  });
+
+  test("GET without body sends no content-type and no body", async () => {
+    const seen: { init?: RequestInit } = {};
+    const fetchPort: FetchPort = (_url, init) => {
+      seen.init = init;
+      return Promise.resolve(jsonResponse(200, { value: "ok" }));
+    };
+    await requestJson(
+      fetchPort,
+      { method: "GET", url: "https://id.example.com/v1/x" },
+      stringSchema,
+    );
+    expect(new Headers(seen.init?.headers).get("content-type")).toBeNull();
+    expect(seen.init?.body).toBeUndefined();
+  });
+
+  test("2xx body failing the schema is invalid_response", async () => {
+    const outcome = await requestJson(
+      fetchReturning(jsonResponse(200, { unexpected: true })),
+      { method: "GET", url: "https://id.example.com/v1/x" },
+      stringSchema,
+    );
+    expect(outcome.ok).toBe(false);
+    if (!outcome.ok) {
+      expect(outcome.error.type).toBe("invalid_response");
+      if (outcome.error.type === "invalid_response") {
+        expect(outcome.error.status).toBe(200);
+      }
+    }
+  });
+});
+
+describe("requestJson — error normalization", () => {
+  test("fetch rejection maps to retryable network_error", async () => {
+    const outcome = await requestJson(
+      fetchRejecting(new TypeError("Failed to fetch")),
+      { method: "GET", url: "https://id.example.com/v1/x" },
+      stringSchema,
+    );
+    expect(outcome).toEqual({
+      ok: false,
+      error: { type: "network_error", message: "Failed to fetch", retryable: true },
+    });
+  });
+
+  test("429 with Retry-After maps to rate_limited with retryAfterSeconds", async () => {
+    const outcome = await requestJson(
+      fetchReturning(jsonResponse(429, {}, { "retry-after": "17" })),
+      { method: "GET", url: "https://id.example.com/v1/x" },
+      stringSchema,
+    );
+    expect(outcome.ok).toBe(false);
+    if (!outcome.ok) {
+      expect(outcome.error).toMatchObject({
+        type: "rate_limited",
+        retryable: true,
+        retryAfterSeconds: 17,
+      });
+    }
+  });
+
+  test("429 without Retry-After omits retryAfterSeconds", async () => {
+    const outcome = await requestJson(
+      fetchReturning(jsonResponse(429, {})),
+      { method: "GET", url: "https://id.example.com/v1/x" },
+      stringSchema,
+    );
+    expect(outcome.ok).toBe(false);
+    if (!outcome.ok && outcome.error.type === "rate_limited") {
+      expect(outcome.error.retryAfterSeconds).toBeUndefined();
+    }
+  });
+
+  test("4xx Problem Details body maps to problem_details with code/title/status/requestId", async () => {
+    const problem = {
+      type: "https://docs.example-auth.com/errors/not-found",
+      title: "Not Found",
+      status: 404,
+      detail: "transaction does not exist",
+      code: "not_found",
+      request_id: "req_123",
+    };
+    const outcome = await requestJson(
+      fetchReturning(jsonResponse(404, problem)),
+      { method: "GET", url: "https://id.example.com/v1/x" },
+      stringSchema,
+    );
+    expect(outcome.ok).toBe(false);
+    if (!outcome.ok) {
+      expect(outcome.error).toEqual({
+        type: "problem_details",
+        problemType: problem.type,
+        code: "not_found",
+        title: "Not Found",
+        status: 404,
+        detail: "transaction does not exist",
+        requestId: "req_123",
+      });
+    }
+  });
+
+  test("OAuth error body maps to oauth_error with a known code", async () => {
+    const outcome = await requestJson(
+      fetchReturning(
+        jsonResponse(400, { error: "invalid_grant", error_description: "code expired" }),
+      ),
+      { method: "POST", url: "https://id.example.com/e/env/oauth2/token" },
+      stringSchema,
+    );
+    expect(outcome.ok).toBe(false);
+    if (!outcome.ok) {
+      expect(outcome.error).toEqual({
+        type: "oauth_error",
+        code: "invalid_grant",
+        description: "code expired",
+        status: 400,
+      });
+    }
+  });
+
+  test("an unknown OAuth error code is not trusted → invalid_response", async () => {
+    const outcome = await requestJson(
+      fetchReturning(jsonResponse(400, { error: "made_up_code" })),
+      { method: "POST", url: "https://id.example.com/e/env/oauth2/token" },
+      stringSchema,
+    );
+    expect(outcome.ok).toBe(false);
+    if (!outcome.ok) {
+      expect(outcome.error.type).toBe("invalid_response");
+    }
+  });
+
+  test("malformed JSON body maps to invalid_response", async () => {
+    const outcome = await requestJson(
+      fetchReturning(new Response("not json at all{", { status: 200 })),
+      { method: "GET", url: "https://id.example.com/v1/x" },
+      stringSchema,
+    );
+    expect(outcome.ok).toBe(false);
+    if (!outcome.ok) {
+      expect(outcome.error.type).toBe("invalid_response");
+    }
+  });
+
+  test("error status with a non-Problem, non-OAuth body maps to invalid_response", async () => {
+    const outcome = await requestJson(
+      fetchReturning(jsonResponse(500, { oops: true })),
+      { method: "GET", url: "https://id.example.com/v1/x" },
+      stringSchema,
+    );
+    expect(outcome.ok).toBe(false);
+    if (!outcome.ok) {
+      expect(outcome.error.type).toBe("invalid_response");
+      if (outcome.error.type === "invalid_response") {
+        expect(outcome.error.status).toBe(500);
+      }
+    }
+  });
+});
+
+describe("buildUrl", () => {
+  test("joins base and path, appending an encoded query string", () => {
+    expect(buildUrl("https://id.example.com", "/v1/config", { client_id: "cli_x y" })).toBe(
+      "https://id.example.com/v1/config?client_id=cli_x+y",
+    );
+    expect(buildUrl("https://id.example.com", "/v1/me")).toBe("https://id.example.com/v1/me");
+  });
+});

package/src/http.ts

@@ -0,0 +1,173 @@
+import type { Outcome } from "@smartcrab/contracts-public";
+import { err, ok } from "@smartcrab/contracts-public";
+import { OAUTH_ERROR_CODES } from "@smartcrab/contracts-public";
+import type { OAuthErrorCode } from "@smartcrab/contracts-public";
+import { parseOAuthErrorWire, parseProblemDetailsWire } from "./errors.js";
+import type { BrowserAuthError } from "./errors.js";
+
+/**
+ * HTTP transport for the public API (design.md §16.2) and the token endpoint
+ * (design.md §15.1).
+ *
+ * Responsibilities:
+ * - exact request serialization (JSON bodies, Bearer header, query strings)
+ * - response normalization into `BrowserAuthError` (network failure, 429 with
+ *   `Retry-After`, RFC 9457 Problem Details, RFC 6749 OAuth errors, and
+ *   `invalid_response` for anything that does not match the wire contract)
+ * - success-path validation through the contracts-public zod schemas — the
+ *   wire is never trusted (IMPL_NOTES §1)
+ *
+ * Exception boundaries are promise rejection handlers (`.then(onOk, onErr)`),
+ * never `try`/`catch` statements: `scripts/check-backend-error-style.ts`
+ * (design.md §5.2) scans this package and rejects direct try-catch.
+ */
+
+/** Minimal structural view of a zod schema's `safeParse` (this package has no zod dependency). */
+export interface WireSchema<T> {
+  safeParse(input: unknown): { success: true; data: T } | { success: false; error: unknown };
+}
+
+export type FetchPort = (url: string, init: RequestInit) => Promise<Response>;
+
+export type HttpMethod = "GET" | "POST" | "PATCH" | "DELETE";
+
+export interface JsonRequest {
+  readonly method: HttpMethod;
+  /** Fully-built URL, including query string. */
+  readonly url: string;
+  readonly body?: unknown;
+  readonly accessToken?: string;
+}
+
+const OAUTH_ERROR_CODE_SET: ReadonlySet<string> = new Set(OAUTH_ERROR_CODES);
+
+export const isOAuthErrorCode = (value: string): value is OAuthErrorCode =>
+  OAUTH_ERROR_CODE_SET.has(value);
+
+const parseRetryAfterSeconds = (response: Response): number | undefined => {
+  const raw = response.headers.get("retry-after");
+  if (raw === null) return undefined;
+  // Only the delta-seconds form is honored; HTTP-date form is intentionally
+  // unsupported (the platform always emits delta-seconds).
+  if (!/^[0-9]+$/.test(raw.trim())) return undefined;
+  return Number.parseInt(raw.trim(), 10);
+};
+
+const invalidResponse = (message: string, status?: number): Outcome<never, BrowserAuthError> =>
+  err({
+    type: "invalid_response",
+    message,
+    ...(status !== undefined ? { status } : {}),
+  });
+
+const toNetworkError = (cause: unknown): Outcome<never, BrowserAuthError> =>
+  err({
+    type: "network_error",
+    message: cause instanceof Error ? cause.message : "Network request failed",
+    retryable: true,
+  });
+
+/** `JSON.parse` without a try statement: the throw becomes a rejection inside the promise chain. */
+const parseJsonBody = (text: string, status: number): Promise<Outcome<unknown, BrowserAuthError>> =>
+  Promise.resolve()
+    .then((): unknown => JSON.parse(text))
+    .then(
+      (value) => ok(value),
+      () => invalidResponse("Response body was not valid JSON", status),
+    );
+
+/**
+ * Executes one JSON request and validates the response against `schema`.
+ *
+ * Error precedence on non-2xx: 429 → `rate_limited`; a valid Problem Details
+ * body → `problem_details`; a valid OAuth error body → `oauth_error`;
+ * anything else → `invalid_response`.
+ */
+export const requestJson = async <T>(
+  fetchPort: FetchPort,
+  request: JsonRequest,
+  schema: WireSchema<T>,
+): Promise<Outcome<T, BrowserAuthError>> => {
+  const headers: Record<string, string> = {
+    accept: "application/json",
+    ...(request.body !== undefined ? { "content-type": "application/json" } : {}),
+    ...(request.accessToken !== undefined
+      ? { authorization: `Bearer ${request.accessToken}` }
+      : {}),
+  };
+
+  const responseOutcome = await fetchPort(request.url, {
+    method: request.method,
+    headers,
+    ...(request.body !== undefined ? { body: JSON.stringify(request.body) } : {}),
+  }).then((response) => ok<Response, BrowserAuthError>(response), toNetworkError);
+  if (!responseOutcome.ok) return responseOutcome;
+  const response = responseOutcome.value;
+
+  // A rejection while streaming the body is still a transport failure.
+  const textOutcome = await response
+    .text()
+    .then((text) => ok<string, BrowserAuthError>(text), toNetworkError);
+  if (!textOutcome.ok) return textOutcome;
+  const text = textOutcome.value;
+
+  const jsonOutcome: Outcome<unknown, BrowserAuthError> =
+    text.length === 0 ? ok(undefined) : await parseJsonBody(text, response.status);
+  if (!jsonOutcome.ok) return jsonOutcome;
+  const json = jsonOutcome.value;
+
+  if (response.status === 429) {
+    const retryAfterSeconds = parseRetryAfterSeconds(response);
+    const problem = parseProblemDetailsWire(json);
+    return err({
+      type: "rate_limited",
+      retryable: true,
+      ...(retryAfterSeconds !== undefined ? { retryAfterSeconds } : {}),
+      ...(problem !== null && problem.requestId !== undefined
+        ? { requestId: problem.requestId }
+        : {}),
+    });
+  }
+
+  if (!response.ok) {
+    const problem = parseProblemDetailsWire(json);
+    if (problem !== null) {
+      return err({
+        type: "problem_details",
+        problemType: problem.type,
+        code: problem.code ?? "unknown_error",
+        title: problem.title,
+        status: problem.status,
+        ...(problem.detail !== undefined ? { detail: problem.detail } : {}),
+        ...(problem.requestId !== undefined ? { requestId: problem.requestId } : {}),
+      });
+    }
+    const oauthError = parseOAuthErrorWire(json);
+    if (oauthError !== null && isOAuthErrorCode(oauthError.error)) {
+      return err({
+        type: "oauth_error",
+        code: oauthError.error,
+        status: response.status,
+        ...(oauthError.description !== undefined ? { description: oauthError.description } : {}),
+      });
+    }
+    return invalidResponse(
+      `HTTP ${response.status} error body was neither Problem Details nor an OAuth error`,
+      response.status,
+    );
+  }
+
+  const parsed = schema.safeParse(json);
+  if (!parsed.success) {
+    return invalidResponse("Response body did not match the public API contract", response.status);
+  }
+  return ok(parsed.data);
+};
+
+/** Builds `base + path` plus an optional query string. */
+export const buildUrl = (baseUrl: string, path: string, query?: Record<string, string>): string => {
+  const url = `${baseUrl}${path}`;
+  if (query === undefined || Object.keys(query).length === 0) return url;
+  const params = new URLSearchParams(query);
+  return `${url}?${params.toString()}`;
+};

package/src/index.ts

@@ -0,0 +1,68 @@
+/**
+ * @smartcrab/browser — dependency-free SPA client for the passwordless
+ * auth platform's public API (design.md §16 transaction API, §15 token
+ * endpoint, §22.3 SPA rules).
+ *
+ * - Every request/response goes through the `@smartcrab/contracts-public`
+ *   zod schemas; malformed wire data surfaces as typed `invalid_response`
+ *   failures, never as trusted objects.
+ * - Access tokens live in memory only (design.md §22.3); refresh-token
+ *   persistence is an explicit, documented opt-in.
+ * - Fallible methods return `Outcome<T, BrowserAuthError>` — the local
+ *   discriminated-union channel from contracts-public, because
+ *   `@praha/byethrow` is not resolvable from this package (not a declared
+ *   dependency).
+ */
+export { createBrowserAuthClient } from "./client.js";
+export type {
+  AuthenticatedSession,
+  BrowserAuthClient,
+  BrowserAuthClientConfig,
+  BrowserAuthListener,
+  BrowserAuthSnapshot,
+  BrowserTransaction,
+  CreateTransactionInput,
+  HostedAuthorization,
+  RedirectPort,
+  RefreshTokenStoragePort,
+} from "./client.js";
+export { parseOAuthErrorWire, parseProblemDetailsWire } from "./errors.js";
+export type {
+  BrowserAuthError,
+  InvalidResponseError,
+  NetworkFailureError,
+  NotAuthenticatedError,
+  OAuthErrorWire,
+  OAuthFailureError,
+  ProblemDetailsError,
+  ProblemDetailsWire,
+  RateLimitedError,
+  StateMismatchError,
+  WebAuthnFailureError,
+  WebAuthnFailureReason,
+} from "./errors.js";
+export { buildUrl, requestJson } from "./http.js";
+export type { FetchPort, HttpMethod, JsonRequest, WireSchema } from "./http.js";
+export { generateNonce, generatePkcePair, generateState } from "./pkce.js";
+export type { PkcePair } from "./pkce.js";
+export { base64UrlDecodeToBytes, base64UrlEncodeBytes, bufferToBase64Url } from "./base64url.js";
+export { navigatorWebAuthnPort } from "./webauthn.js";
+export type { WebAuthnBrowserPort } from "./webauthn.js";
+
+// Selected contract types re-exported so downstream SDKs (e.g.
+// `@smartcrab/react`, which cannot depend on contracts-public directly)
+// can type their own surfaces against the exact wire shapes. `ok`/`err` are
+// re-exported as values so consumers can construct `Outcome`s themselves.
+export { err, ok } from "@smartcrab/contracts-public";
+export type {
+  EmailChallengeResponse,
+  MeIdentitySummary,
+  MeSessionSummary,
+  MeUpdateRequest,
+  MeUser,
+  Outcome,
+  PasskeySummary,
+  PublicConfigResponse,
+  SocialProvider,
+  TransactionStatus,
+} from "@smartcrab/contracts-public";

package/src/pkce.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from "vitest";
+import { base64UrlEncodeBytes } from "./base64url.js";
+import { generateNonce, generatePkcePair, generateState } from "./pkce.js";
+
+/**
+ * PKCE/state generation (design.md §32.1: S256 only, state/nonce 必須;
+ * RFC 7636 §4.1/§4.2 shape rules).
+ */
+
+const BASE64URL_PATTERN = /^[A-Za-z0-9_-]+$/;
+const RFC7636_VERIFIER_PATTERN = /^[A-Za-z0-9._~-]{43,128}$/;
+
+describe("generatePkcePair", () => {
+  test("verifier is 43 chars in the RFC 7636 unreserved charset", () => {
+    return generatePkcePair().then((pair) => {
+      expect(pair.verifier).toHaveLength(43);
+      expect(pair.verifier).toMatch(RFC7636_VERIFIER_PATTERN);
+      expect(pair.method).toBe("S256");
+    });
+  });
+
+  test("challenge is 43-char base64url and equals base64url(SHA-256(verifier))", async () => {
+    const pair = await generatePkcePair();
+    expect(pair.challenge).toHaveLength(43);
+    expect(pair.challenge).toMatch(BASE64URL_PATTERN);
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(pair.verifier));
+    expect(pair.challenge).toBe(base64UrlEncodeBytes(new Uint8Array(digest)));
+    // S256 must actually transform the verifier.
+    expect(pair.challenge).not.toBe(pair.verifier);
+  });
+
+  test("pairs are unique across generations", async () => {
+    const [a, b] = await Promise.all([generatePkcePair(), generatePkcePair()]);
+    expect(a.verifier).not.toBe(b.verifier);
+    expect(a.challenge).not.toBe(b.challenge);
+  });
+});
+
+describe("generateState / generateNonce", () => {
+  test("are 43-char base64url values (256 bits of entropy)", () => {
+    for (const value of [generateState(), generateNonce()]) {
+      expect(value).toHaveLength(43);
+      expect(value).toMatch(BASE64URL_PATTERN);
+    }
+  });
+
+  test("never repeat across a batch", () => {
+    const values = new Set(Array.from({ length: 100 }, () => generateState()));
+    expect(values.size).toBe(100);
+  });
+});