@multiplatform.one/keycloak 6.6.0 → 7.0.0

package/src/frappeToken.native.spec.ts

@@ -0,0 +1,104 @@
+/**
+ * Specs for the native Keycloak Bearer-token getter: caching, stampede
+ * dedup, signed-out cooldown, and the clear-on-auth-transition reset.
+ */
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { AppState } from "react-native";
+
+const getAccessToken = vi.fn();
+
+vi.mock("./betterAuth/expoAuthFlow.native", () => ({
+  getActiveExpoAuthFlow: () => ({ getAccessToken }),
+}));
+
+import {
+  clearKeycloakBearerToken,
+  getKeycloakBearerToken,
+  watchKeycloakBearerTokenRevalidate,
+} from "./frappeToken.native";
+
+describe("getKeycloakBearerToken (native)", () => {
+  beforeEach(() => {
+    getAccessToken.mockReset();
+    clearKeycloakBearerToken();
+  });
+
+  it("caches a token until near expiry", async () => {
+    getAccessToken.mockResolvedValue({
+      accessToken: "jwt-1",
+      accessTokenExpiresAt: new Date(Date.now() + 300_000).toISOString(),
+    });
+    expect(await getKeycloakBearerToken()).toBe("jwt-1");
+    expect(await getKeycloakBearerToken()).toBe("jwt-1");
+    expect(getAccessToken).toHaveBeenCalledTimes(1);
+  });
+
+  it("shares one in-flight fetch across parallel callers", async () => {
+    let release: (value: unknown) => void = () => {};
+    getAccessToken.mockImplementation(
+      () =>
+        new Promise((resolve) => {
+          release = resolve;
+        }),
+    );
+    const a = getKeycloakBearerToken();
+    const b = getKeycloakBearerToken();
+    release({
+      accessToken: "jwt-2",
+      accessTokenExpiresAt: new Date(Date.now() + 300_000).toISOString(),
+    });
+    expect(await a).toBe("jwt-2");
+    expect(await b).toBe("jwt-2");
+    expect(getAccessToken).toHaveBeenCalledTimes(1);
+  });
+
+  it("answers signed-out once per cooldown window instead of per request", async () => {
+    getAccessToken.mockResolvedValue(null);
+    expect(await getKeycloakBearerToken()).toBeUndefined();
+    expect(await getKeycloakBearerToken()).toBeUndefined();
+    expect(getAccessToken).toHaveBeenCalledTimes(1);
+  });
+
+  it("clearKeycloakBearerToken resets the cooldown (sign-in transition)", async () => {
+    getAccessToken.mockResolvedValueOnce(null);
+    expect(await getKeycloakBearerToken()).toBeUndefined();
+    clearKeycloakBearerToken();
+    getAccessToken.mockResolvedValueOnce({
+      accessToken: "jwt-3",
+      accessTokenExpiresAt: new Date(Date.now() + 300_000).toISOString(),
+    });
+    expect(await getKeycloakBearerToken()).toBe("jwt-3");
+    expect(getAccessToken).toHaveBeenCalledTimes(2);
+  });
+
+  it("treats a thrown fetch as signed out (guest requests)", async () => {
+    getAccessToken.mockRejectedValue(new Error("network down"));
+    expect(await getKeycloakBearerToken()).toBeUndefined();
+  });
+
+  it("watchKeycloakBearerTokenRevalidate busts the cache on foreground", async () => {
+    const listeners: Array<(status: string) => void> = [];
+    const spy = vi.spyOn(AppState, "addEventListener").mockImplementation((_event, cb) => {
+      listeners.push(cb as (status: string) => void);
+      return { remove: vi.fn() } as never;
+    });
+    getAccessToken.mockResolvedValue({
+      accessToken: "jwt-1",
+      accessTokenExpiresAt: new Date(Date.now() + 300_000).toISOString(),
+    });
+    expect(await getKeycloakBearerToken()).toBe("jwt-1");
+    expect(getAccessToken).toHaveBeenCalledTimes(1);
+
+    const unsub = watchKeycloakBearerTokenRevalidate();
+    getAccessToken.mockResolvedValue({
+      accessToken: "jwt-fresh",
+      accessTokenExpiresAt: new Date(Date.now() + 300_000).toISOString(),
+    });
+    for (const cb of listeners) cb("active");
+    expect(await getKeycloakBearerToken()).toBe("jwt-fresh");
+    expect(getAccessToken).toHaveBeenCalledTimes(2);
+    unsub();
+    spy.mockRestore();
+  });
+});

package/src/frappeToken.native.ts

@@ -9,20 +9,44 @@
  * when expired), authenticated with the SecureStore cookie jar.
  */
 
+import { AppState, type AppStateStatus } from "react-native";
 import { getActiveExpoAuthFlow } from "./betterAuth/expoAuthFlow.native";
 
 let cached: { token: string; expiresAt: number } | undefined;
+/** In-flight fetch, shared so parallel callers don't stampede the endpoint. */
+let pending: Promise<string | undefined> | undefined;
+/** After a signed-out answer, skip re-asking until this time (ms epoch). */
+let signedOutUntil = 0;
 
-/** Returns a valid Keycloak access token, or undefined when signed out. */
+const SIGNED_OUT_COOLDOWN_MS = 15_000;
+
+/**
+ * Returns a valid Keycloak access token, or undefined when signed out.
+ *
+ * Signed-out clients get a single 401 per cooldown window instead of one per
+ * concurrent collection sync: parallel callers share the in-flight fetch, and
+ * a signed-out answer short-circuits further attempts for a few seconds. The
+ * AuthProvider clears this module state on sign-in / sign-out.
+ */
 export async function getKeycloakBearerToken(): Promise<string | undefined> {
   // 60s slack so we never hand out a token that expires mid-request.
   if (cached && cached.expiresAt - 60_000 > Date.now()) return cached.token;
+  if (Date.now() < signedOutUntil) return undefined;
+  if (pending) return pending;
+  pending = fetchToken().finally(() => {
+    pending = undefined;
+  });
+  return pending;
+}
+
+async function fetchToken(): Promise<string | undefined> {
   const flow = getActiveExpoAuthFlow();
   if (!flow) return undefined;
   try {
     const res = await flow.getAccessToken("keycloak");
     if (!res?.accessToken) {
       cached = undefined;
+      signedOutUntil = Date.now() + SIGNED_OUT_COOLDOWN_MS;
       return undefined;
     }
     cached = {
@@ -35,11 +59,31 @@ export async function getKeycloakBearerToken(): Promise<string | undefined> {
   } catch {
     // Signed out / server unreachable -> guest requests.
     cached = undefined;
+    signedOutUntil = Date.now() + SIGNED_OUT_COOLDOWN_MS;
     return undefined;
   }
 }
 
-/** Drop the cached token (sign-out). */
+/** Drop the cached token (sign-out / fresh sign-in). */
 export function clearKeycloakBearerToken() {
   cached = undefined;
+  pending = undefined;
+  signedOutUntil = 0;
+}
+
+/**
+ * Bust the client cache and re-fetch when the app returns to the
+ * foreground, so a completed ASWebAuthenticationSession (or an SLO in
+ * Safari that the Linking listener missed) is noticed without a reload.
+ * Returns an unsubscribe. AfterAuth mounts this once.
+ */
+export function watchKeycloakBearerTokenRevalidate(): () => void {
+  const onChange = (next: AppStateStatus) => {
+    if (next !== "active") return;
+    cached = undefined;
+    signedOutUntil = 0;
+    void getKeycloakBearerToken();
+  };
+  const sub = AppState.addEventListener("change", onChange);
+  return () => sub.remove();
 }

package/src/frappeToken.spec.ts

@@ -0,0 +1,141 @@
+/**
+ * Specs for the web Keycloak Bearer-token getter: caching, stampede dedup,
+ * signed-out cooldown, and transient Keycloak-restart retries.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const notify = vi.fn();
+
+vi.mock("./betterAuth/client", () => ({
+  getAuthClient: () => ({ $store: { notify } }),
+}));
+
+import { clearKeycloakBearerToken, getKeycloakBearerToken } from "./frappeToken";
+
+function jsonResponse(status: number, body: unknown) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+describe("getKeycloakBearerToken (web)", () => {
+  beforeEach(() => {
+    notify.mockReset();
+    clearKeycloakBearerToken();
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue(
+        jsonResponse(200, {
+          accessToken: "jwt-1",
+          accessTokenExpiresAt: new Date(Date.now() + 300_000).toISOString(),
+        }),
+      ),
+    );
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+  });
+
+  it("caches a token until near expiry", async () => {
+    expect(await getKeycloakBearerToken()).toBe("jwt-1");
+    expect(await getKeycloakBearerToken()).toBe("jwt-1");
+    expect(fetch).toHaveBeenCalledTimes(1);
+  });
+
+  it("shares one in-flight fetch across parallel callers", async () => {
+    let release: (value: Response) => void = () => {};
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(
+        () =>
+          new Promise<Response>((resolve) => {
+            release = resolve;
+          }),
+      ),
+    );
+    const a = getKeycloakBearerToken();
+    const b = getKeycloakBearerToken();
+    release(
+      jsonResponse(200, {
+        accessToken: "jwt-2",
+        accessTokenExpiresAt: new Date(Date.now() + 300_000).toISOString(),
+      }),
+    );
+    expect(await a).toBe("jwt-2");
+    expect(await b).toBe("jwt-2");
+    expect(fetch).toHaveBeenCalledTimes(1);
+  });
+
+  it("answers signed-out once per cooldown window instead of per request", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue(jsonResponse(400, { code: "FAILED_TO_GET_ACCESS_TOKEN" })),
+    );
+    expect(await getKeycloakBearerToken()).toBeUndefined();
+    expect(await getKeycloakBearerToken()).toBeUndefined();
+    expect(fetch).toHaveBeenCalledTimes(1);
+    expect(notify).toHaveBeenCalledWith("$sessionSignal");
+  });
+
+  it("retries TOKEN_REFRESH_UNAVAILABLE and succeeds without signing out", async () => {
+    vi.useFakeTimers();
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce(jsonResponse(500, { code: "TOKEN_REFRESH_UNAVAILABLE" }))
+      .mockResolvedValueOnce(
+        jsonResponse(200, {
+          accessToken: "jwt-after-restart",
+          accessTokenExpiresAt: new Date(Date.now() + 300_000).toISOString(),
+        }),
+      );
+    vi.stubGlobal("fetch", fetchMock);
+
+    const pending = getKeycloakBearerToken();
+    await vi.runAllTimersAsync();
+    expect(await pending).toBe("jwt-after-restart");
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(notify).not.toHaveBeenCalled();
+  });
+
+  it("does not start the signed-out cooldown on a network blip", async () => {
+    vi.useFakeTimers();
+    const fetchMock = vi.fn().mockRejectedValue(new Error("ECONNREFUSED"));
+    vi.stubGlobal("fetch", fetchMock);
+
+    const pending = getKeycloakBearerToken();
+    await vi.runAllTimersAsync();
+    expect(await pending).toBeUndefined();
+    expect(notify).not.toHaveBeenCalled();
+
+    clearKeycloakBearerToken();
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse(200, {
+        accessToken: "jwt-recovered",
+        accessTokenExpiresAt: new Date(Date.now() + 300_000).toISOString(),
+      }),
+    );
+    expect(await getKeycloakBearerToken()).toBe("jwt-recovered");
+  });
+
+  it("clearKeycloakBearerToken resets the cooldown (sign-in transition)", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi
+        .fn()
+        .mockResolvedValueOnce(jsonResponse(401, {}))
+        .mockResolvedValueOnce(
+          jsonResponse(200, {
+            accessToken: "jwt-3",
+            accessTokenExpiresAt: new Date(Date.now() + 300_000).toISOString(),
+          }),
+        ),
+    );
+    expect(await getKeycloakBearerToken()).toBeUndefined();
+    clearKeycloakBearerToken();
+    expect(await getKeycloakBearerToken()).toBe("jwt-3");
+  });
+});

package/src/frappeToken.ts

@@ -11,15 +11,59 @@
  * cookie) and sends `Authorization: Bearer <token>` on every REST request
  * and socket handshake — the same transport native uses. The bench's
  * frappe_keycloak auth hook validates the JWT against the realm public key.
+ *
+ * Failures are classified, not collapsed:
+ * - 401/403, or 400 `FAILED_TO_GET_ACCESS_TOKEN` (server already decided
+ *   the refresh token is dead): signed-out cooldown + session notify.
+ * - 5xx `TOKEN_REFRESH_UNAVAILABLE`, other 5xx, network: retry with
+ *   backoff, keep the session. A Keycloak restart must not look like logout.
  */
 
+import { getAuthClient } from "./betterAuth/client";
+
 let cached: { token: string; expiresAt: number } | undefined;
 /** In-flight fetch, shared so parallel callers don't stampede the endpoint. */
 let pending: Promise<string | undefined> | undefined;
 /** After a signed-out answer, skip re-asking until this time (ms epoch). */
 let signedOutUntil = 0;
+/** After a transient Keycloak blip, skip re-asking briefly (not signed-out). */
+let unavailableUntil = 0;
 
 const SIGNED_OUT_COOLDOWN_MS = 15_000;
+const TRANSIENT_COOLDOWN_MS = 3_000;
+const RETRY_DELAYS_MS = [0, 400, 1000] as const;
+const FAILED_TO_GET_ACCESS_TOKEN = "FAILED_TO_GET_ACCESS_TOKEN";
+
+type FailureKind = "signed-out" | "transient";
+
+function classifyAccessTokenResponse(status: number, body?: { code?: string } | null): FailureKind {
+  if (status === 401 || status === 403) return "signed-out";
+  if (status === 400 && body?.code === FAILED_TO_GET_ACCESS_TOKEN) return "signed-out";
+  return "transient";
+}
+
+/**
+ * A definitive refresh failure (Keycloak declared the refresh token dead —
+ * e.g. its SSO session was wiped by a restart). The server revokes the stale
+ * Better Auth session on this answer and clears its cookies in the same
+ * response, so poke the session store to refetch: the UI flips to signed-out
+ * instead of silently degrading to Guest requests.
+ */
+function notifySessionInvalidated() {
+  try {
+    const client = getAuthClient() as {
+      $store?: { notify?: (signal: string) => void };
+    };
+    client.$store?.notify?.("$sessionSignal");
+  } catch {
+    // The session store is a UX nicety here; token callers already got their
+    // signed-out answer.
+  }
+}
+
+function sleep(ms: number) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 
 /**
  * Returns a valid Keycloak access token, or undefined when signed out.
@@ -28,13 +72,15 @@ const SIGNED_OUT_COOLDOWN_MS = 15_000;
  * concurrent data request: parallel callers share the in-flight fetch, and a
  * signed-out answer short-circuits further attempts for a few seconds. A real
  * sign-in arrives via the OAuth redirect (full navigation), which resets this
- * module state anyway.
+ * module state anyway. Transient Keycloak failures retry before giving up,
+ * and never start the signed-out cooldown.
  */
 export async function getKeycloakBearerToken(): Promise<string | undefined> {
   if (typeof window === "undefined") return undefined;
   // 60s slack so we never hand out a token that expires mid-request.
   if (cached && cached.expiresAt - 60_000 > Date.now()) return cached.token;
   if (Date.now() < signedOutUntil) return undefined;
+  if (Date.now() < unavailableUntil) return undefined;
   if (pending) return pending;
   pending = fetchToken().finally(() => {
     pending = undefined;
@@ -42,7 +88,9 @@ export async function getKeycloakBearerToken(): Promise<string | undefined> {
   return pending;
 }
 
-async function fetchToken(): Promise<string | undefined> {
+async function fetchTokenOnce(): Promise<
+  { ok: true; token: string; expiresAt: number } | { ok: false; kind: FailureKind }
+> {
   try {
     const res = await fetch(`${window.location.origin}/api/auth/get-access-token`, {
       method: "POST",
@@ -51,32 +99,51 @@ async function fetchToken(): Promise<string | undefined> {
       body: JSON.stringify({ providerId: "keycloak" }),
     });
     if (!res.ok) {
-      cached = undefined;
-      signedOutUntil = Date.now() + SIGNED_OUT_COOLDOWN_MS;
-      return undefined;
+      const body = (await res.json().catch(() => null)) as { code?: string } | null;
+      return { ok: false, kind: classifyAccessTokenResponse(res.status, body) };
     }
     const data = (await res.json().catch(() => null)) as {
       accessToken?: string;
       accessTokenExpiresAt?: string;
     } | null;
     if (!data?.accessToken) {
-      cached = undefined;
-      signedOutUntil = Date.now() + SIGNED_OUT_COOLDOWN_MS;
-      return undefined;
+      return { ok: false, kind: "signed-out" };
     }
-    cached = {
+    return {
+      ok: true,
       token: data.accessToken,
       expiresAt: data.accessTokenExpiresAt
         ? new Date(data.accessTokenExpiresAt).getTime()
         : Date.now() + 60_000,
     };
-    return cached.token;
   } catch {
-    // Signed out / server unreachable -> guest requests.
-    cached = undefined;
-    signedOutUntil = Date.now() + SIGNED_OUT_COOLDOWN_MS;
-    return undefined;
+    return { ok: false, kind: "transient" };
+  }
+}
+
+async function fetchToken(): Promise<string | undefined> {
+  let last: FailureKind = "transient";
+  for (let i = 0; i < RETRY_DELAYS_MS.length; i++) {
+    const wait = RETRY_DELAYS_MS[i];
+    if (wait) await sleep(wait);
+    const result = await fetchTokenOnce();
+    if (result.ok) {
+      cached = { token: result.token, expiresAt: result.expiresAt };
+      return result.token;
+    }
+    last = result.kind;
+    if (result.kind === "signed-out") {
+      cached = undefined;
+      signedOutUntil = Date.now() + SIGNED_OUT_COOLDOWN_MS;
+      notifySessionInvalidated();
+      return undefined;
+    }
   }
+  cached = undefined;
+  if (last === "transient") {
+    unavailableUntil = Date.now() + TRANSIENT_COOLDOWN_MS;
+  }
+  return undefined;
 }
 
 /** Drop the cached token (sign-out / fresh sign-in). */
@@ -84,4 +151,29 @@ export function clearKeycloakBearerToken() {
   cached = undefined;
   pending = undefined;
   signedOutUntil = 0;
+  unavailableUntil = 0;
+}
+
+/**
+ * Bust the client cache and re-fetch when the tab is focused again, so a
+ * front-channel logout (or Keycloak recovery) in another window is noticed
+ * without a full reload. Returns an unsubscribe. No-op on the server.
+ */
+export function watchKeycloakBearerTokenRevalidate(): () => void {
+  if (typeof document === "undefined" || typeof window === "undefined") {
+    return () => {};
+  }
+  const onVisible = () => {
+    if (document.visibilityState !== "visible") return;
+    cached = undefined;
+    signedOutUntil = 0;
+    unavailableUntil = 0;
+    void getKeycloakBearerToken();
+  };
+  document.addEventListener("visibilitychange", onVisible);
+  window.addEventListener("focus", onVisible);
+  return () => {
+    document.removeEventListener("visibilitychange", onVisible);
+    window.removeEventListener("focus", onVisible);
+  };
 }

package/src/index.ts

@@ -6,4 +6,4 @@ export * from "./provider/index";
 export * from "./session/index";
 export * from "./token";
 export * from "./types";
-export { getKeycloakBearerToken } from "./frappeToken";
+export { getKeycloakBearerToken, watchKeycloakBearerTokenRevalidate } from "./frappeToken";

package/src/keycloak/index.ts

@@ -10,6 +10,7 @@ import type KeycloakClient from "@multiplatform.one/keycloak-js";
 import { isBrowser, isServer, isStorybook, isWeb } from "@multiplatform.one/platform";
 import { useContext } from "react";
 import { getAuthClient } from "../betterAuth/client";
+import { clearKeycloakBearerToken } from "../frappeToken";
 import { useAuthConfig } from "../hooks/index";
 import type { Session } from "../session/index";
 import { useSession } from "../session/index";
@@ -52,21 +53,37 @@ export class Keycloak extends BaseKeycloak {
   async logout(options: KeycloakLogoutOptions = {}) {
     if (this._keycloakClient) {
       await this._keycloakClient.logout(options);
+    } else if (this._logout) {
+      await this._logout(options);
+    } else if (typeof window !== "undefined" && window.location?.href) {
+      // Front-channel single sign-out. Guard on `window.location` (not `isWeb`):
+      // vxrn polyfills `window` on native without a Location, and `isWeb` has
+      // been false in some One web bundles — falling through to fetch
+      // `signOut()` killed the Better Auth cookie but left the Keycloak SSO
+      // session alive, so the next Log in silently signed back in.
+      clearKeycloakBearerToken();
+      const origin = window.location.origin;
+      let callbackURL = options.redirectUri || "/";
+      try {
+        // Same-origin targets travel as app-relative paths (always trusted);
+        // cross-origin ones pass through for trustedOrigins to vet.
+        const url = new URL(callbackURL, origin);
+        callbackURL =
+          url.origin === origin ? `${url.pathname}${url.search}${url.hash}` || "/" : url.toString();
+      } catch {
+        callbackURL = "/";
+      }
+      window.location.href = `${origin}/api/auth/sign-out/sso?callbackURL=${encodeURIComponent(callbackURL)}`;
+      return;
     } else if (isBrowser && !isServer) {
       const client = getAuthClient();
       await client.signOut({
         fetchOptions: {
           onSuccess: () => {
-            if (options.redirectUri) {
-              if (isWeb) window.location.href = options.redirectUri;
-            } else {
-              if (isWeb) window.location.reload();
-            }
+            if (options.redirectUri && isWeb) window.location.href = options.redirectUri;
           },
         },
       });
-    } else {
-      await this._logout?.(options);
     }
     this._clear();
   }

package/src/keycloak/index.webext.ts

@@ -10,6 +10,7 @@ import type KeycloakClient from "@multiplatform.one/keycloak-js";
 import { isBrowser, isServer } from "@multiplatform.one/platform";
 import { useContext } from "react";
 import { getAuthClient } from "../betterAuth/client";
+import { clearKeycloakBearerToken } from "../frappeToken";
 import { useAuthConfig } from "../hooks";
 import type { KeycloakMock } from "../types";
 import { BaseKeycloak, type KeycloakLoginOptions, type KeycloakLogoutOptions } from "./base";
@@ -43,6 +44,21 @@ export class Keycloak extends BaseKeycloak {
   async logout(options: KeycloakLogoutOptions = {}) {
     if (this._keycloakClient) {
       await this._keycloakClient.logout(options);
+    } else if (isBrowser && !isServer && typeof window !== "undefined" && window.location) {
+      // Same front-channel ride as the web Keycloak class: ending only the
+      // Better Auth session leaves the Keycloak SSO cookie alive, so the
+      // next SSO-first hop silently signs the user back in.
+      clearKeycloakBearerToken();
+      const origin = window.location.origin;
+      let callbackURL = options.redirectUri || "/";
+      try {
+        const url = new URL(callbackURL, origin);
+        callbackURL =
+          url.origin === origin ? `${url.pathname}${url.search}${url.hash}` || "/" : url.toString();
+      } catch {
+        callbackURL = "/";
+      }
+      window.location.href = `${origin}/api/auth/sign-out/sso?callbackURL=${encodeURIComponent(callbackURL)}`;
     } else if (isBrowser && !isServer) {
       const client = getAuthClient();
       await client.signOut({

package/src/oauth/authorizationUrl.spec.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+import { buildAuthorizationUrl, buildLogoutUrl } from "./authorizationUrl";
+import { keycloakEndpoints } from "./endpoints";
+
+const endpoints = keycloakEndpoints({ url: "https://kc.example.com", realm: "myrealm" });
+
+const baseParams = {
+  endpoints,
+  clientId: "app-public",
+  redirectUri: "http://127.0.0.1:41234/callback",
+  state: "state-token",
+  codeChallenge: "challenge-value",
+  nonce: "nonce-token",
+};
+
+describe("buildAuthorizationUrl", () => {
+  it("requests an authorization code with an S256 challenge", () => {
+    const url = new URL(buildAuthorizationUrl(baseParams));
+    expect(`${url.origin}${url.pathname}`).toBe(endpoints.authorization);
+    expect(Object.fromEntries(url.searchParams)).toEqual({
+      client_id: "app-public",
+      redirect_uri: "http://127.0.0.1:41234/callback",
+      response_type: "code",
+      scope: "openid profile email",
+      state: "state-token",
+      nonce: "nonce-token",
+      code_challenge: "challenge-value",
+      code_challenge_method: "S256",
+    });
+  });
+
+  it("sends the nonce the id token will be checked against", () => {
+    const url = new URL(buildAuthorizationUrl(baseParams));
+    expect(url.searchParams.get("nonce")).toBe("nonce-token");
+  });
+
+  it("never puts a client secret or the verifier in the front-channel url", () => {
+    const url = buildAuthorizationUrl(baseParams);
+    expect(url).not.toContain("client_secret");
+    expect(url).not.toContain("code_verifier");
+  });
+
+  it("honours custom scopes, prompt and login_hint", () => {
+    const url = new URL(
+      buildAuthorizationUrl({
+        ...baseParams,
+        scopes: ["openid", "offline_access"],
+        prompt: "login",
+        loginHint: "testuser",
+      }),
+    );
+    expect(url.searchParams.get("scope")).toBe("openid offline_access");
+    expect(url.searchParams.get("prompt")).toBe("login");
+    expect(url.searchParams.get("login_hint")).toBe("testuser");
+  });
+
+  it("omits prompt and login_hint when not supplied", () => {
+    const url = new URL(buildAuthorizationUrl(baseParams));
+    expect(url.searchParams.has("prompt")).toBe(false);
+    expect(url.searchParams.has("login_hint")).toBe(false);
+  });
+});
+
+describe("buildLogoutUrl", () => {
+  it("passes the id token hint and post-logout redirect", () => {
+    const url = new URL(
+      buildLogoutUrl({
+        endpoints,
+        clientId: "app-public",
+        idToken: "id-token",
+        postLogoutRedirectUri: "http://127.0.0.1:41234/done",
+      }),
+    );
+    expect(`${url.origin}${url.pathname}`).toBe(endpoints.endSession);
+    expect(url.searchParams.get("id_token_hint")).toBe("id-token");
+    expect(url.searchParams.get("post_logout_redirect_uri")).toBe("http://127.0.0.1:41234/done");
+  });
+
+  it("omits the hint when there is no id token", () => {
+    const url = new URL(buildLogoutUrl({ endpoints, clientId: "app-public" }));
+    expect(url.searchParams.has("id_token_hint")).toBe(false);
+  });
+});