@cplieger/access 0.0.0 → 1.0.0-dev.10

package/README.md

@@ -1,3 +1,66 @@
 # @cplieger/access
 
-This version is a placeholder that reserves the package name. The first real release is published by [cplieger/access](https://github.com/cplieger/access)'s release workflow.
+`@cplieger/access` is the browser half of [cplieger/access](https://github.com/cplieger/access): a typed client for the JSON routes the Go package `accesshttp` serves, with the passkey ceremonies, OIDC redirects and step-up flow those routes expect. Every response is validated against the server's wire types before your code sees it.
+
+## Install
+
+```sh
+npm install @cplieger/access @cplieger/reactive@dev
+```
+
+The package ships TypeScript source as ES modules. `@cplieger/reactive` 2.x, from 2.4, is a peer dependency: the client makes its requests through your `@cplieger/reactive/fetch` instance, so your base URL, credentials mode and error hook apply to every call, and the models that `createSessionsModel` and `shownOnce` return are `@cplieger/reactive/signal` signals, so read them from effects made with that same package.
+
+## Usage
+
+Create one client with the same prefixes you gave `accesshttp.Config`:
+
+```ts
+import { createFetch } from "@cplieger/reactive/fetch";
+import { createAuthClient, signInWithPasskey, withStepUp } from "@cplieger/access";
+
+const auth = createAuthClient({
+  fetch: createFetch({ credentials: "same-origin" }),
+  prefix: "/api/auth",
+  oidcPrefix: "/api/auth/oidc",
+});
+
+const res = await auth.loginPassword({ username, password });
+if (!res.ok) {
+  // authCode(res) and authReason(res) give the stable code and reason to branch on
+}
+
+const passkey = await signInWithPasskey(auth);
+if (passkey.kind === "signed-in") {
+  // passkey.result is the SignedInResponse
+}
+```
+
+Every call returns an `ApiResult`: `ok` with the decoded `data`, or the refusal. `authCode` and `authReason` read the refusal's code and reason as the `AuthCode` and `AuthReason` unions, which mirror the server's `Codes()` and `Reasons()`.
+
+`withStepUp` runs an action that needs a recent sign-in. On an `auth_recent_auth_required` refusal with no reason, it asks your `prompt` which method to use, re-authenticates with it and retries the action once. A refusal that carries a reason, such as `reenable_needs_other_method`, is returned as it is, because a step-up cannot cure it:
+
+```ts
+const out = await withStepUp(auth, () => auth.setPassword(change), {
+  prompt: async (methods) => askUser(methods), // "password", "passkey", "oidc" or "cancel"
+  password: async () => askForCurrentPassword(), // null when the user cancels
+});
+```
+
+The OIDC branch navigates to the identity provider and never returns to the action, so the app continues from its own redirect path.
+
+## What it exports
+
+- `createAuthClient` returns an `AuthClient` with one method per route, such as `me`, `loginPassword`, `sessions` and `createKey`. `adminSecurityLog` reads a page of the [security log](https://github.com/cplieger/access/blob/main/docs/security-log.md) with its per-class counts, newest first, or oldest first when `oldestFirst` is set; `after` and `before` are bounds only.
+- `signInWithPasskey`, `registerPasskey`, `setupWithPasskey`, `stepUpWithPasskey` and `recoverWithPasskey` run the WebAuthn ceremonies. `passkeySupport` reports what the browser offers, and `sendSignals` keeps the credential manager's passkey list in step with the server.
+- `oidcSignInURL`, `startOIDC`, `readOIDCReturn`, `pendingLink` and `completePendingLink` handle the OIDC sign-in, link and step-up redirects.
+- `withStepUp` retries an action after a step-up, and `createSessionsModel` keeps a reactive list of the user's sessions.
+- `shownOnce` holds a key or link shown once and clears it, `storePasswordCredential` offers the password to the browser's password manager, and `continuation` and `takeFragmentToken` carry state and a one-time token across a redirect.
+- A `parse*` validator and a type for every JSON body the routes accept or return (the query structs are built by the client methods), `authCode`, `authReason`, `AuthCode` and `AuthReason`.
+
+## Compatibility
+
+The client speaks the v1.0.0 wire. It needs a server built on `github.com/cplieger/access` at v1.0.0 or later, with `accesshttp` serving the routes. The Go module and this package version separately, and a later release states its own floor here.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

package/jsr.json

@@ -0,0 +1,22 @@
+{
+  "name": "@cplieger/access",
+  "version": "1.0.0-dev.10",
+  "license": "Apache-2.0",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publish": {
+    "include": [
+      "LICENSE",
+      "NOTICE",
+      "README.md",
+      "src/**/*.ts",
+      "jsr.json"
+    ],
+    "exclude": [
+      "src/**/*.test.ts",
+      "src/**/*-setup.ts",
+      "src/**/test-helpers/**"
+    ]
+  }
+}

package/package.json

@@ -1,22 +1,62 @@
 {
   "name": "@cplieger/access",
-  "version": "0.0.0",
-  "description": "Browser client for the cplieger/access Go library's accesshttp routes (placeholder release; the first real version is published from cplieger/access's release.yaml)",
+  "version": "1.0.0-dev.10",
+  "description": "Browser client for the cplieger/access accesshttp routes: typed calls, passkey ceremonies and step-up",
   "license": "Apache-2.0",
-  "author": "cplieger <917744+cplieger@users.noreply.github.com>",
-  "homepage": "https://github.com/cplieger/access",
-  "bugs": {
-    "url": "https://github.com/cplieger/access/issues"
-  },
+  "type": "module",
+  "sideEffects": false,
   "repository": {
     "type": "git",
     "url": "git+https://github.com/cplieger/access.git",
     "directory": "web"
   },
-  "type": "module",
+  "homepage": "https://github.com/cplieger/access",
+  "bugs": {
+    "url": "https://github.com/cplieger/access/issues"
+  },
+  "author": "cplieger <917744+cplieger@users.noreply.github.com>",
+  "exports": {
+    ".": "./src/index.ts"
+  },
   "files": [
-    "README.md",
+    "src/",
+    "!src/**/*.test.ts",
+    "!src/**/*-setup.ts",
+    "!src/**/test-helpers/**",
+    "jsr.json",
     "LICENSE",
     "NOTICE"
-  ]
+  ],
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.tests.json",
+    "typecheck:tests": "tsc -p tsconfig.tests.json",
+    "test": "vitest --run",
+    "test:browser": "vitest --run --project browser",
+    "lint:eslint": "eslint .",
+    "lint:prettier": "prettier --check .",
+    "lint:knip": "knip",
+    "lint:fix": "eslint . --fix && prettier --write ."
+  },
+  "devDependencies": {
+    "@cplieger/reactive": "2.4.0-dev.1",
+    "@eslint/js": "10.0.1",
+    "@types/node": "26.6.6",
+    "@typescript/native": "npm:typescript@7.0.2",
+    "@vitest/browser-playwright": "5.0.5",
+    "eslint": "10.13.0",
+    "fast-check": "4.10.2",
+    "knip": "6.44.0",
+    "playwright": "1.64.1",
+    "prettier": "3.9.10",
+    "typescript": "npm:@typescript/typescript6@6.0.2",
+    "typescript-eslint": "8.72.1",
+    "vite": "8.3.5",
+    "vitest": "5.0.5"
+  },
+  "overrides": {
+    "minimatch": "^11.0.1"
+  },
+  "peerDependencies": {
+    "@cplieger/reactive": "^2.4.0-dev.1"
+  }
 }

package/src/client.ts

@@ -0,0 +1,351 @@
+import type {
+  ApiResult,
+  FetchInstance,
+  HttpMethod,
+  RequestOptions,
+} from "@cplieger/reactive/fetch";
+import {
+  list,
+  parseCeremonyResponse,
+  parseKeyCreatedResponse,
+  parseKeyView,
+  parseMeResponse,
+  parseOIDCStartResponse,
+  parsePasskeyView,
+  parsePendingLinkResponse,
+  parseRecoveryResponse,
+  parseSecurityLogView,
+  parseSessionView,
+  parseSignedInResponse,
+  parseStateResponse,
+  parseTokenResponse,
+  parseTokenView,
+  parseUserView,
+  parseWebAuthnSignals,
+} from "./wire.js";
+import type {
+  CeremonyResponse,
+  InviteAcceptRequest,
+  InviteRequest,
+  KeyCreatedResponse,
+  KeyView,
+  LoginRequest,
+  MeResponse,
+  NameRequest,
+  NewKeyRequest,
+  NewUserRequest,
+  OIDCStartResponse,
+  PasskeyView,
+  PasswordChangeRequest,
+  PasswordRemoveRequest,
+  PasswordRequest,
+  PendingLinkResponse,
+  ProfileRequest,
+  RecoverPasswordRequest,
+  RecoveryResponse,
+  RedirectRequest,
+  SecurityLogView,
+  SessionView,
+  SetupPasskeyBeginRequest,
+  SetupPasswordRequest,
+  SignedInResponse,
+  StateResponse,
+  TTLRequest,
+  TokenRequest,
+  TokenResponse,
+  TokenView,
+  UserUpdateRequest,
+  UserView,
+  Validator,
+  WebAuthnSignals,
+} from "./wire.js";
+
+export interface AuthClientOptions {
+  /** The app's instance: its credentials mode, base URL and error hook apply to every call. */
+  readonly fetch: FetchInstance;
+  /** accesshttp.Config.Prefix. */
+  readonly prefix: string;
+  /** accesshttp.Config.OIDCPrefix. */
+  readonly oidcPrefix: string;
+}
+
+/**
+ * A finish route's body as the ceremonies build it: clientExtensionResults carries only an output
+ * the begin options requested (credProps on the create leg), because go-webauthn refuses any other.
+ */
+export type PublicKeyCredentialJSON =
+  | {
+      readonly id: string;
+      readonly rawId: string;
+      readonly type: string;
+      readonly authenticatorAttachment?: string;
+      readonly response: {
+        readonly attestationObject: string;
+        readonly clientDataJSON: string;
+        readonly transports?: readonly string[];
+      };
+      readonly clientExtensionResults: { readonly credProps?: { readonly rk?: boolean } };
+    }
+  | {
+      readonly id: string;
+      readonly rawId: string;
+      readonly type: string;
+      readonly authenticatorAttachment?: string;
+      readonly response: {
+        readonly authenticatorData: string;
+        readonly clientDataJSON: string;
+        readonly signature: string;
+        readonly userHandle?: string;
+      };
+      readonly clientExtensionResults: { readonly credProps?: { readonly rk?: boolean } };
+    };
+
+export interface RecoverFlags {
+  readonly keepSessions: boolean;
+  readonly keepKeys: boolean;
+}
+
+/**
+ * One method per JSON route of accesshttp, each decoded through wire.ts: a 2xx body that is not
+ * the route's type is the fetch instance's "decode" failure. The two redirect routes are
+ * navigations, built by oidcSignInURL.
+ */
+export interface AuthClient {
+  readonly prefix: string;
+  readonly oidcPrefix: string;
+  state(): Promise<ApiResult<StateResponse>>;
+  setupPassword(r: SetupPasswordRequest): Promise<ApiResult<SignedInResponse>>;
+  setupPasskeyBegin(r: SetupPasskeyBeginRequest): Promise<ApiResult<CeremonyResponse>>;
+  setupPasskeyFinish(
+    ceremony: string,
+    credential: PublicKeyCredentialJSON,
+  ): Promise<ApiResult<SignedInResponse>>;
+  loginPassword(r: LoginRequest): Promise<ApiResult<SignedInResponse>>;
+  loginPasskeyBegin(o?: {
+    readonly mediation?: "conditional";
+  }): Promise<ApiResult<CeremonyResponse>>;
+  loginPasskeyFinish(
+    ceremony: string,
+    credential: PublicKeyCredentialJSON,
+  ): Promise<ApiResult<SignedInResponse>>;
+  logout(): Promise<ApiResult<void>>;
+  oidcStartLink(r: RedirectRequest): Promise<ApiResult<OIDCStartResponse>>;
+  oidcStartStepUp(r: RedirectRequest): Promise<ApiResult<OIDCStartResponse>>;
+  oidcPending(): Promise<ApiResult<PendingLinkResponse>>;
+  oidcLinkPending(): Promise<ApiResult<MeResponse>>;
+  oidcUnlink(): Promise<ApiResult<void>>;
+  recoveryStart(r: TokenRequest): Promise<ApiResult<RecoveryResponse>>;
+  recoveryPassword(r: RecoverPasswordRequest): Promise<ApiResult<void>>;
+  recoveryPasskeyBegin(): Promise<ApiResult<CeremonyResponse>>;
+  recoveryPasskeyFinish(
+    ceremony: string,
+    credential: PublicKeyCredentialJSON,
+    o: RecoverFlags,
+  ): Promise<ApiResult<void>>;
+  inviteAcceptPassword(r: InviteAcceptRequest): Promise<ApiResult<SignedInResponse>>;
+  me(): Promise<ApiResult<MeResponse>>;
+  updateProfile(r: ProfileRequest): Promise<ApiResult<MeResponse>>;
+  reenableMethod(method: string): Promise<ApiResult<void>>;
+  stepUpPassword(r: PasswordRequest): Promise<ApiResult<void>>;
+  stepUpPasskeyBegin(): Promise<ApiResult<CeremonyResponse>>;
+  stepUpPasskeyFinish(
+    ceremony: string,
+    credential: PublicKeyCredentialJSON,
+  ): Promise<ApiResult<void>>;
+  setPassword(r: PasswordChangeRequest): Promise<ApiResult<void>>;
+  removePassword(r: PasswordRemoveRequest): Promise<ApiResult<void>>;
+  passkeys(): Promise<ApiResult<readonly PasskeyView[]>>;
+  passkeyRegisterBegin(): Promise<ApiResult<CeremonyResponse>>;
+  passkeyRegisterFinish(
+    ceremony: string,
+    credential: PublicKeyCredentialJSON,
+  ): Promise<ApiResult<PasskeyView>>;
+  renamePasskey(id: number, r: NameRequest): Promise<ApiResult<void>>;
+  removePasskey(id: number): Promise<ApiResult<void>>;
+  webauthnSignals(): Promise<ApiResult<WebAuthnSignals>>;
+  sessions(): Promise<ApiResult<readonly SessionView[]>>;
+  renameSession(id: string, r: NameRequest): Promise<ApiResult<void>>;
+  revokeSession(id: string): Promise<ApiResult<void>>;
+  revokeOtherSessions(): Promise<ApiResult<void>>;
+  keys(): Promise<ApiResult<readonly KeyView[]>>;
+  createKey(r: NewKeyRequest): Promise<ApiResult<KeyCreatedResponse>>;
+  revokeKey(id: number): Promise<ApiResult<void>>;
+  /** key lists the users any key in that key's lineage acted on (GET /users?key=). */
+  adminUsers(o?: { readonly key?: number }): Promise<ApiResult<readonly UserView[]>>;
+  adminCreateUser(r: NewUserRequest): Promise<ApiResult<UserView>>;
+  adminUpdateUser(id: number, r: UserUpdateRequest): Promise<ApiResult<UserView>>;
+  adminDeleteUser(id: number): Promise<ApiResult<void>>;
+  adminIssueRecovery(id: number, r: TTLRequest): Promise<ApiResult<TokenResponse>>;
+  adminInvite(r: InviteRequest): Promise<ApiResult<TokenResponse>>;
+  adminTokens(): Promise<ApiResult<readonly TokenView[]>>;
+  adminKeys(): Promise<ApiResult<readonly KeyView[]>>;
+  adminRevokeKey(id: number): Promise<ApiResult<void>>;
+  /**
+   * Newest first, or oldest first when oldestFirst is true; after and before are bounds only.
+   * kinds empty or absent is every kind.
+   */
+  adminSecurityLog(q?: {
+    readonly user?: number;
+    readonly actor?: number;
+    readonly actorKey?: number;
+    readonly after?: number;
+    readonly before?: number;
+    readonly kinds?: readonly string[];
+    readonly limit?: number;
+    readonly oldestFirst?: boolean;
+  }): Promise<ApiResult<SecurityLogView>>;
+}
+
+// The fetch instance's decoder contract is to throw on a mismatch, which it turns into a
+// "decode" failure; a wire.ts validator answers undefined instead.
+function decoder<T>(validate: Validator<T>): (v: unknown) => T {
+  return (v) => {
+    const out = validate(v);
+    if (out === undefined) {
+      throw new TypeError("response body is not the route's wire type");
+    }
+    return out;
+  };
+}
+
+function query(params: Readonly<Record<string, string | undefined>>): string {
+  const q = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) {
+    if (v !== undefined) {
+      q.set(k, v);
+    }
+  }
+  const s = q.toString();
+  return s === "" ? "" : `?${s}`;
+}
+
+const seg = encodeURIComponent;
+const num = (n: number | undefined): string | undefined =>
+  n === undefined ? undefined : String(n);
+
+export function createAuthClient(opts: AuthClientOptions): AuthClient {
+  const { fetch: f, prefix, oidcPrefix } = opts;
+
+  function json<T>(
+    method: HttpMethod,
+    path: string,
+    validate: Validator<T>,
+    o: RequestOptions<T> = {},
+  ): Promise<ApiResult<T>> {
+    return f.requestRaw<T>(method, path, { ...o, decoder: decoder(validate) });
+  }
+  function empty(method: HttpMethod, path: string, body?: unknown): Promise<ApiResult<void>> {
+    return f.requestRaw<undefined>(method, path, {
+      ignoreBody: true,
+      ...(body === undefined ? {} : { body }),
+    });
+  }
+  function finish(
+    ceremony: string,
+    credential: PublicKeyCredentialJSON,
+  ): { readonly body: unknown; readonly headers: Readonly<Record<string, string>> } {
+    return { body: credential, headers: { "X-Auth-Ceremony": ceremony } };
+  }
+  const p = (path: string): string => prefix + path;
+  const o = (path: string): string => oidcPrefix + path;
+  const passkeyList = list(parsePasskeyView);
+  const sessionList = list(parseSessionView);
+  const keyList = list(parseKeyView);
+  const userList = list(parseUserView);
+  const tokenList = list(parseTokenView);
+
+  return {
+    prefix,
+    oidcPrefix,
+    state: () => json("GET", p("/state"), parseStateResponse),
+    setupPassword: (r) => json("POST", p("/setup/password"), parseSignedInResponse, { body: r }),
+    setupPasskeyBegin: (r) =>
+      json("POST", p("/setup/passkey/begin"), parseCeremonyResponse, { body: r }),
+    setupPasskeyFinish: (c, cred) =>
+      json("POST", p("/setup/passkey/finish"), parseSignedInResponse, finish(c, cred)),
+    loginPassword: (r) => json("POST", p("/login/password"), parseSignedInResponse, { body: r }),
+    loginPasskeyBegin: (q) =>
+      json(
+        "POST",
+        p(`/login/passkey/begin${query({ mediation: q?.mediation })}`),
+        parseCeremonyResponse,
+      ),
+    loginPasskeyFinish: (c, cred) =>
+      json("POST", p("/login/passkey/finish"), parseSignedInResponse, finish(c, cred)),
+    logout: () => empty("POST", p("/logout")),
+    oidcStartLink: (r) => json("POST", o("/start/link"), parseOIDCStartResponse, { body: r }),
+    oidcStartStepUp: (r) => json("POST", o("/start/stepup"), parseOIDCStartResponse, { body: r }),
+    oidcPending: () => json("GET", p("/oidc/pending"), parsePendingLinkResponse),
+    oidcLinkPending: () => json("POST", p("/oidc/link"), parseMeResponse),
+    oidcUnlink: () => empty("DELETE", p("/oidc/link")),
+    recoveryStart: (r) => json("POST", p("/recovery"), parseRecoveryResponse, { body: r }),
+    recoveryPassword: (r) => empty("POST", p("/recovery/password"), r),
+    recoveryPasskeyBegin: () => json("POST", p("/recovery/passkey/begin"), parseCeremonyResponse),
+    recoveryPasskeyFinish: (c, cred, flags) =>
+      f.requestRaw<undefined>(
+        "POST",
+        p(
+          `/recovery/passkey/finish${query({
+            keep_sessions: flags.keepSessions ? "true" : undefined,
+            keep_keys: flags.keepKeys ? "true" : undefined,
+          })}`,
+        ),
+        { ...finish(c, cred), ignoreBody: true },
+      ),
+    inviteAcceptPassword: (r) =>
+      json("POST", p("/invite/password"), parseSignedInResponse, { body: r }),
+    me: () => json("GET", p("/me"), parseMeResponse),
+    updateProfile: (r) => json("PUT", p("/profile"), parseMeResponse, { body: r }),
+    reenableMethod: (m) => empty("POST", p(`/methods/${seg(m)}/reenable`)),
+    stepUpPassword: (r) => empty("POST", p("/stepup/password"), r),
+    stepUpPasskeyBegin: () => json("POST", p("/stepup/passkey/begin"), parseCeremonyResponse),
+    stepUpPasskeyFinish: (c, cred) =>
+      f.requestRaw<undefined>("POST", p("/stepup/passkey/finish"), {
+        ...finish(c, cred),
+        ignoreBody: true,
+      }),
+    setPassword: (r) => empty("PUT", p("/password"), r),
+    removePassword: (r) => empty("DELETE", p("/password"), r),
+    passkeys: () => json("GET", p("/passkeys"), passkeyList),
+    passkeyRegisterBegin: () => json("POST", p("/passkeys/begin"), parseCeremonyResponse),
+    passkeyRegisterFinish: (c, cred) =>
+      json("POST", p("/passkeys/finish"), parsePasskeyView, finish(c, cred)),
+    renamePasskey: (id, r) => empty("PUT", p(`/passkeys/${String(id)}`), r),
+    removePasskey: (id) => empty("DELETE", p(`/passkeys/${String(id)}`)),
+    webauthnSignals: () => json("GET", p("/webauthn/signals"), parseWebAuthnSignals),
+    sessions: () => json("GET", p("/sessions"), sessionList),
+    renameSession: (id, r) => empty("PUT", p(`/sessions/${seg(id)}`), r),
+    revokeSession: (id) => empty("DELETE", p(`/sessions/${seg(id)}`)),
+    revokeOtherSessions: () => empty("POST", p("/sessions/revoke-others")),
+    keys: () => json("GET", p("/apikeys"), keyList),
+    createKey: (r) => json("POST", p("/apikeys"), parseKeyCreatedResponse, { body: r }),
+    revokeKey: (id) => empty("DELETE", p(`/apikeys/${String(id)}`)),
+    adminUsers: (q) => json("GET", p(`/users${query({ key: num(q?.key) })}`), userList),
+    adminCreateUser: (r) => json("POST", p("/users"), parseUserView, { body: r }),
+    adminUpdateUser: (id, r) => json("PUT", p(`/users/${String(id)}`), parseUserView, { body: r }),
+    adminDeleteUser: (id) => empty("DELETE", p(`/users/${String(id)}`)),
+    adminIssueRecovery: (id, r) =>
+      json("POST", p(`/users/${String(id)}/recovery`), parseTokenResponse, { body: r }),
+    adminInvite: (r) => json("POST", p("/invites"), parseTokenResponse, { body: r }),
+    adminTokens: () => json("GET", p("/tokens"), tokenList),
+    adminKeys: () => json("GET", p("/admin/apikeys"), keyList),
+    adminRevokeKey: (id) => empty("DELETE", p(`/admin/apikeys/${String(id)}`)),
+    adminSecurityLog: (q) =>
+      json(
+        "GET",
+        p(
+          `/security-log${query({
+            user: num(q?.user),
+            actor: num(q?.actor),
+            actor_key: num(q?.actorKey),
+            after: num(q?.after),
+            before: num(q?.before),
+            kinds: q?.kinds === undefined || q.kinds.length === 0 ? undefined : q.kinds.join(","),
+            limit: num(q?.limit),
+            oldest_first: q?.oldestFirst === true ? "true" : undefined,
+          })}`,
+        ),
+        parseSecurityLogView,
+      ),
+  };
+}

package/src/continuation.ts

@@ -0,0 +1,174 @@
+import { readOIDCReturn } from "./oidc.js";
+
+const PREFIX = "@cplieger/access:continue:";
+const NONCE = /^[A-Za-z0-9_-]{22}$/;
+
+function storage(): Storage | undefined {
+  try {
+    return (globalThis as { readonly sessionStorage?: Storage }).sessionStorage;
+  } catch {
+    // The getter itself throws SecurityError where storage is blocked
+    // (https://html.spec.whatwg.org/multipage/webstorage.html#dom-sessionstorage).
+    return undefined;
+  }
+}
+
+function nonce(): string {
+  const b = crypto.getRandomValues(new Uint8Array(16));
+  return btoa(String.fromCharCode(...b))
+    .replaceAll("+", "-")
+    .replaceAll("/", "_")
+    .replace(/=+$/, "");
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+// Undefined for an entry this module did not write.
+function entry(raw: string | null): { readonly exp: number; readonly v: unknown } | undefined {
+  if (raw === null) {
+    return undefined;
+  }
+  let e: unknown;
+  try {
+    e = JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+  if (!isRecord(e) || typeof e["exp"] !== "number" || !Object.hasOwn(e, "v")) {
+    return undefined;
+  }
+  return { exp: e["exp"], v: e["v"] };
+}
+
+function dropExpired(s: Storage, now: number): void {
+  const keys: string[] = [];
+  for (let i = 0; i < s.length; i++) {
+    const k = s.key(i);
+    if (k?.startsWith(PREFIX) === true) {
+      keys.push(k);
+    }
+  }
+  for (const k of keys) {
+    const e = entry(s.getItem(k));
+    if (e === undefined || now > e.exp) {
+      s.removeItem(k);
+    }
+  }
+}
+
+/** The same-origin half of an OIDC step-up's continuation, kept per tab in sessionStorage. */
+export const continuation: {
+  /**
+   * Stores value (JSON-serialisable) under a fresh 128-bit base64url nonce for at most
+   * maxAgeMs, and returns the nonce, which the app puts in its startOIDC redirect as
+   * continue=<nonce>. Throws, storing nothing, unless maxAgeMs is a finite number greater than
+   * 0 and JSON.stringify can serialise value.
+   */
+  put(value: unknown, maxAgeMs: number): string;
+  /**
+   * Reads search (location.search). Returns the stored value once, only when the oidc marker
+   * is stepped_up and continue names a known, unspent, unexpired nonce; otherwise undefined.
+   * Every call that names a nonce spends it, whatever it returns, and drops every expired
+   * entry.
+   */
+  take(search: string): unknown;
+} = {
+  put(value, maxAgeMs) {
+    if (!(Number.isFinite(maxAgeMs) && maxAgeMs > 0)) {
+      throw new RangeError("continuation.put: maxAgeMs must be a finite number above 0");
+    }
+    if ((JSON.stringify(value) as string | undefined) === undefined) {
+      throw new TypeError("continuation.put: value has no JSON form");
+    }
+    const record = JSON.stringify({ v: value, exp: Date.now() + maxAgeMs });
+    const s = storage();
+    if (s === undefined) {
+      throw new Error("continuation.put: sessionStorage is unavailable");
+    }
+    const n = nonce();
+    s.setItem(PREFIX + n, record);
+    return n;
+  },
+
+  take(search) {
+    const s = storage();
+    if (s === undefined) {
+      return undefined;
+    }
+    const now = Date.now();
+    const named = new URLSearchParams(search).getAll("continue");
+    const found = named.map((n) => {
+      const k = PREFIX + n;
+      const e = entry(s.getItem(k));
+      s.removeItem(k);
+      return e;
+    });
+    dropExpired(s, now);
+    const [only] = named;
+    const [e] = found;
+    if (
+      named.length !== 1 ||
+      only === undefined ||
+      !NONCE.test(only) ||
+      e === undefined ||
+      now > e.exp ||
+      readOIDCReturn(search).kind !== "stepped_up"
+    ) {
+      return undefined;
+    }
+    return e.v;
+  },
+};
+
+function utf8Length(s: string): number {
+  return new TextEncoder().encode(s).length;
+}
+
+function decode(s: string): string | undefined {
+  try {
+    return decodeURIComponent(s);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Reads name from location.hash's key=value pairs, removes every pair named name with
+ * history.replaceState (and the "#" when none is left), and returns the value when name
+ * appears exactly once and its value is non-empty and at most maxBytes UTF-8 bytes; otherwise
+ * undefined. The pairs are removed in every case, so no token stays in the URL or in this
+ * history entry; an entry the browser recorded elsewhere before the call is out of its reach.
+ */
+export function takeFragmentToken(name: string, maxBytes = 512): string | undefined {
+  const hash = globalThis.location.hash;
+  if (hash.length <= 1) {
+    return undefined;
+  }
+  const pairs = hash.slice(1).split("&");
+  const values: (string | undefined)[] = [];
+  const kept: string[] = [];
+  for (const p of pairs) {
+    const eq = p.indexOf("=");
+    const key = eq === -1 ? p : p.slice(0, eq);
+    if (decode(key) === name) {
+      values.push(eq === -1 ? "" : decode(p.slice(eq + 1)));
+    } else {
+      kept.push(p);
+    }
+  }
+  if (values.length === 0) {
+    return undefined;
+  }
+  const { pathname, search } = globalThis.location;
+  history.replaceState(
+    history.state,
+    "",
+    pathname + search + (kept.length === 0 ? "" : `#${kept.join("&")}`),
+  );
+  const [v] = values;
+  return values.length === 1 && v !== undefined && v !== "" && utf8Length(v) <= maxBytes
+    ? v
+    : undefined;
+}