@uln/auth 0.4.2 → 0.6.1

package/dist/totp.js

@@ -76,17 +76,21 @@ async function currentTotpCode(secret, nowMs = Date.now()) {
   const step = Math.floor(nowMs / 1000 / TOTP_PERIOD);
   return generateCode(secret, step);
 }
-async function verifyTotpCode(secret, code) {
-  if (code.length !== TOTP_DIGITS)
-    return false;
-  const now = Math.floor(Date.now() / 1000);
-  const currentStep = Math.floor(now / TOTP_PERIOD);
+async function verifyTotpStep(secret, code, nowMs = Date.now()) {
+  if (!/^\d{6}$/.test(code))
+    return null;
+  const currentStep = Math.floor(nowMs / 1000 / TOTP_PERIOD);
+  let matched = null;
   for (let offset = -TOTP_WINDOW;offset <= TOTP_WINDOW; offset++) {
-    const expected = await generateCode(secret, currentStep + offset);
+    const step = currentStep + offset;
+    const expected = await generateCode(secret, step);
     if (timingSafeEqual(code, expected))
-      return true;
+      matched = step;
   }
-  return false;
+  return matched;
+}
+async function verifyTotpCode(secret, code) {
+  return await verifyTotpStep(secret, code) !== null;
 }
 var BACKUP_CODE_COUNT = 10;
 var BACKUP_CODE_LENGTH = 8;
@@ -94,11 +98,14 @@ var BACKUP_CODE_CHARS = "abcdefghijklmnopqrstuvwxyz0123456789";
 function generateBackupCodes() {
   const codes = [];
   for (let i = 0;i < BACKUP_CODE_COUNT; i++) {
-    const bytes = new Uint8Array(BACKUP_CODE_LENGTH);
-    crypto.getRandomValues(bytes);
     let code = "";
-    for (const byte of bytes) {
-      code += BACKUP_CODE_CHARS[byte % BACKUP_CODE_CHARS.length];
+    while (code.length < BACKUP_CODE_LENGTH) {
+      const bytes = new Uint8Array(BACKUP_CODE_LENGTH);
+      crypto.getRandomValues(bytes);
+      for (const byte of bytes) {
+        if (byte < 252 && code.length < BACKUP_CODE_LENGTH)
+          code += BACKUP_CODE_CHARS[byte % BACKUP_CODE_CHARS.length];
+      }
     }
     codes.push(code);
   }
@@ -119,11 +126,12 @@ function timingSafeEqual(a, b) {
   return result === 0;
 }
 export {
-  verifyTotpCode,
-  hashBackupCode,
-  getTotpUri,
-  generateTotpSecret,
-  generateBackupCodes,
+  base32Encode,
   currentTotpCode,
-  base32Encode
+  generateBackupCodes,
+  generateTotpSecret,
+  getTotpUri,
+  hashBackupCode,
+  verifyTotpCode,
+  verifyTotpStep
 };

package/dist/types.d.ts

@@ -25,6 +25,11 @@ export interface RateLimitStore {
     get(key: string): Promise<RateLimitEntry | null>;
     set(key: string, entry: RateLimitEntry, ttlSeconds: number): Promise<void>;
     delete(key: string): Promise<void>;
+    /**
+     * Atomically add one attempt (creating the entry if needed) and return the result. Optional, but stores that
+     * implement it are race-free under concurrent requests; otherwise a read-modify-write via get/set is used.
+     */
+    increment?(key: string, ttlSeconds: number): Promise<RateLimitEntry>;
 }
 export interface RateLimitConfig {
     maxAttempts: number;
@@ -40,6 +45,19 @@ export interface TokenPayload {
     kid: string;
     iat: number;
     exp: number;
+    /**
+     * Audience: the origin this token was issued to (a site's origin, or the auth service's own origin for its session
+     * cookie). A token is only honoured where `aud` matches. Absent only on tokens minted before audience binding
+     * (library < 0.5); current verifiers reject those.
+     */
+    aud?: string;
+    /** Auth-service sessions only: the server-side session this token belongs to (worker `sessions` table). */
+    sid?: string;
+    /**
+     * Auth-service sessions only: a short-lived token for a Device Bound Session (DBSC), renewed by a proof from a key
+     * held by the user's device. Once a session is bound, only these tokens are honoured for it.
+     */
+    dbsc?: boolean;
 }
 export interface PublicKeyEntry {
     kid: string;
@@ -53,6 +71,15 @@ export interface SigningConfig {
 export interface VerifyConfig {
     publicKeys: PublicKeyEntry[];
     maxAgeSeconds: number;
+    /**
+     * Also confirm locally valid tokens with the auth service (at most once per token every `intervalSeconds`, default
+     * 300), so password resets, deleted users and removed scopes take effect without waiting for the token to expire.
+     * If the auth service can't be reached the local result stands.
+     */
+    revalidate?: {
+        authUrl: string;
+        intervalSeconds?: number;
+    };
 }
 export interface CookieConfig {
     name: string;

package/dist/users.d.ts

@@ -7,6 +7,11 @@ export declare function createUser(store: UserStore, input: {
     password?: string;
     isAdmin?: boolean;
 }): Promise<User>;
+/**
+ * Check an email/password pair. When the user doesn't exist a dummy hash is still verified, so response timing
+ * doesn't reveal which emails have accounts. A correct password stored under older hashing parameters is re-hashed
+ * with the current ones.
+ */
 export declare function verifyUserCredentials(store: UserStore, email: string, password: string): Promise<User | null>;
 export declare function updateName(store: UserStore, userId: string, name: string): Promise<void>;
 export declare function changePassword(store: UserStore, userId: string, newPassword: string): Promise<void>;

package/dist/users.js

@@ -2,7 +2,12 @@
 // src/password.ts
 var SALT_LENGTH = 32;
 var KEY_LENGTH = 64;
-var ITERATIONS = 1e5;
+var STAGE_ITERATIONS = 1e5;
+var ITERATIONS = 600000;
+var MAX_ITERATIONS = 1e7;
+var MAX_PASSWORD_LENGTH = 1024;
+var HEX_REGEX = /^(?:[0-9a-f]{2})+$/;
+var PREFIX = "pbkdf2-sha256";
 function toHex(buffer) {
   return Array.from(new Uint8Array(buffer)).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
@@ -13,38 +18,61 @@ function fromHex(hex) {
   }
   return bytes;
 }
-async function deriveKey(password, salt) {
-  const encoder = new TextEncoder;
-  const keyMaterial = await crypto.subtle.importKey("raw", encoder.encode(password), "PBKDF2", false, ["deriveBits"]);
-  return crypto.subtle.deriveBits({
-    name: "PBKDF2",
-    salt,
-    iterations: ITERATIONS,
-    hash: "SHA-256"
-  }, keyMaterial, KEY_LENGTH * 8);
+async function deriveKey(password, salt, iterations) {
+  let material = new TextEncoder().encode(password);
+  let derived = new ArrayBuffer(0);
+  for (let done = 0;done < iterations; done += STAGE_ITERATIONS) {
+    const keyMaterial = await crypto.subtle.importKey("raw", material, "PBKDF2", false, ["deriveBits"]);
+    derived = await crypto.subtle.deriveBits({ name: "PBKDF2", salt, iterations: STAGE_ITERATIONS, hash: "SHA-256" }, keyMaterial, KEY_LENGTH * 8);
+    material = new Uint8Array(derived);
+  }
+  return derived;
+}
+function parseHash(storedHash) {
+  let iterations = STAGE_ITERATIONS;
+  let saltHex;
+  let keyHex;
+  if (storedHash.startsWith(`${PREFIX}$`)) {
+    const [, rawIterations = "", salt = "", key = ""] = storedHash.split("$");
+    if (!/^[1-9]\d*$/.test(rawIterations))
+      return null;
+    iterations = Number(rawIterations);
+    if (iterations % STAGE_ITERATIONS !== 0 || iterations > MAX_ITERATIONS)
+      return null;
+    saltHex = salt;
+    keyHex = key;
+  } else {
+    const separatorIndex = storedHash.indexOf(":");
+    if (separatorIndex === -1)
+      return null;
+    saltHex = storedHash.substring(0, separatorIndex);
+    keyHex = storedHash.substring(separatorIndex + 1);
+  }
+  if (!HEX_REGEX.test(saltHex) || !HEX_REGEX.test(keyHex))
+    return null;
+  return { iterations, salt: fromHex(saltHex), key: fromHex(keyHex) };
 }
 async function hashPassword(password) {
   const salt = crypto.getRandomValues(new Uint8Array(SALT_LENGTH));
-  const derived = await deriveKey(password, salt);
-  return `${toHex(salt.buffer)}:${toHex(derived)}`;
+  const derived = await deriveKey(password, salt, ITERATIONS);
+  return `${PREFIX}$${ITERATIONS}$${toHex(salt.buffer)}$${toHex(derived)}`;
 }
 async function verifyPassword(password, storedHash) {
-  const separatorIndex = storedHash.indexOf(":");
-  if (separatorIndex === -1)
+  const parsed = parseHash(storedHash);
+  if (!parsed)
     return false;
-  const saltHex = storedHash.substring(0, separatorIndex);
-  const keyHex = storedHash.substring(separatorIndex + 1);
-  const salt = fromHex(saltHex);
-  const expectedKey = fromHex(keyHex);
-  const derived = new Uint8Array(await deriveKey(password, salt));
-  if (derived.length !== expectedKey.length)
+  const derived = new Uint8Array(await deriveKey(password, parsed.salt, parsed.iterations));
+  if (derived.length !== parsed.key.length)
     return false;
   let diff = 0;
   for (let i = 0;i < derived.length; i++) {
-    diff |= (derived[i] ?? 0) ^ (expectedKey[i] ?? 0);
+    diff |= (derived[i] ?? 0) ^ (parsed.key[i] ?? 0);
   }
   return diff === 0;
 }
+function needsRehash(storedHash) {
+  return !storedHash.startsWith(`${PREFIX}$`) || (parseHash(storedHash)?.iterations ?? 0) < ITERATIONS;
+}
 
 // src/users.ts
 var EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
@@ -54,6 +82,8 @@ function isValidEmail(email) {
 async function createUser(store, input) {
   if (!isValidEmail(input.email))
     throw new Error("Invalid email address");
+  if (input.password !== undefined && input.password.length > MAX_PASSWORD_LENGTH)
+    throw new Error("Password is too long");
   const existing = await store.getUserByEmail(input.email);
   if (existing)
     throw new Error(`User with email ${input.email} already exists`);
@@ -74,12 +104,22 @@ async function createUser(store, input) {
   await store.saveUser(user);
   return user;
 }
+var dummyHash = null;
 async function verifyUserCredentials(store, email, password) {
   const user = await store.getUserByEmail(email.toLowerCase());
-  if (!user)
+  if (!user) {
+    dummyHash ??= hashPassword(crypto.randomUUID());
+    await verifyPassword(password, await dummyHash);
     return null;
+  }
   const valid = await verifyPassword(password, user.passwordHash);
-  return valid ? user : null;
+  if (!valid)
+    return null;
+  if (!needsRehash(user.passwordHash))
+    return user;
+  const upgraded = { ...user, passwordHash: await hashPassword(password), updatedAt: new Date().toISOString() };
+  await store.saveUser(upgraded);
+  return upgraded;
 }
 async function updateName(store, userId, name) {
   const user = await store.getUser(userId);
@@ -93,6 +133,8 @@ async function updateName(store, userId, name) {
   await store.saveUser(updated);
 }
 async function changePassword(store, userId, newPassword) {
+  if (newPassword.length > MAX_PASSWORD_LENGTH)
+    throw new Error("Password is too long");
   const user = await store.getUser(userId);
   if (!user)
     throw new Error(`User ${userId} not found`);
@@ -104,9 +146,9 @@ async function changePassword(store, userId, newPassword) {
   await store.saveUser(updated);
 }
 export {
-  verifyUserCredentials,
-  updateName,
-  isValidEmail,
+  changePassword,
   createUser,
-  changePassword
+  isValidEmail,
+  updateName,
+  verifyUserCredentials
 };

package/dist/version.d.ts

@@ -0,0 +1,6 @@
+/**
+ * This library's version. Sent to the auth service on every login (`uln_v` on the return URL) so Admin → Sites can show
+ * which version each site runs and open upgrade PRs for the ones behind. `src/version.test.ts` keeps it equal to
+ * `package.json`.
+ */
+export declare const LIBRARY_VERSION = "0.6.1";

package/dist/version.js

@@ -0,0 +1,6 @@
+// @bun
+// src/version.ts
+var LIBRARY_VERSION = "0.6.1";
+export {
+  LIBRARY_VERSION
+};

package/package.json

@@ -1,6 +1,10 @@
 {
   "name": "@uln/auth",
-  "version": "0.4.2",
+  "version": "0.6.1",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ulnd/auth.git"
+  },
   "type": "module",
   "exports": {
     ".": {
@@ -24,45 +28,56 @@
       "types": "./dist/hono.d.ts"
     }
   },
-  "files": ["dist", "src", "!src/**/*.test.ts"],
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "dev": "bunx vite",
-    "dev:worker": "bunx wrangler dev",
+    "dev:worker": "wrangler dev",
     "build": "bun run scripts/build.ts",
     "check": "biome check --write .",
     "test": "bun test",
-    "ci": "biome check . && bun test --coverage",
+    "ci": "biome check . && bun run typecheck && bun test --coverage",
     "migrate:local": "bunx wrangler d1 migrations apply uln-auth --local",
     "migrate:remote": "bunx wrangler d1 migrations apply uln-auth --remote",
     "deploy": "bun run migrate:remote && bunx wrangler deploy",
-    "publish:check": "bun run scripts/publish.ts check",
-    "publish:release": "bun run scripts/publish.ts release"
+    "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p client/tsconfig.json"
   },
   "devDependencies": {
-    "@biomejs/biome": "^1.9.4",
-    "@uln/ui": "^0.2.0",
-    "@cloudflare/workers-types": "^4.20260317.1",
-    "@types/bun": "latest",
+    "@biomejs/biome": "^2.5.15",
+    "@cloudflare/workers-types": "^5.20261001.1",
+    "@types/bun": "^1.4.2",
     "@types/qrcode": "^1.5.6",
-    "@types/react": "^19.2.14",
-    "@types/react-dom": "^19.2.3",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
     "@uln/log": "^0.3.0",
-    "@vitejs/plugin-react": "^6.0.1",
-    "hono": "^4.12.8",
+    "@uln/ui": "^0.2.0",
+    "@vitejs/plugin-react": "^6.1.1",
+    "hono": "^4.13.12",
     "qrcode": "^1.5.4",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
-    "react-router": "^7.13.1",
-    "vite": "^8.0.1"
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "react-router": "^8.4.0",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.2",
+    "wrangler": "^4.145.0"
   },
   "peerDependencies": {
     "hono": "^4",
-    "typescript": "^5 || ^6"
+    "typescript": "^5 || ^6 || ^7"
   },
   "peerDependenciesMeta": {
     "hono": {
       "optional": true
     }
   },
-  "dependencies": {}
+  "dependencies": {},
+  "overrides": {
+    "hono": "^4.13.12"
+  }
 }

package/src/client.ts

@@ -1,20 +1,14 @@
-export type { TokenPayload, VerifyConfig, PublicKeyEntry, CookieConfig } from "./types.ts";
-export { validateToken, importPublicKey } from "./token.ts";
-export { makeSessionCookie, makeClearCookie, extractCookie } from "./cookie.ts";
-export type { AuthCodeExchangeConfig } from "./middleware.ts";
-export { getAuthUser, redirectToLogin, handleCallback, getClientIP, checkBearerToken } from "./middleware.ts";
-
-import { importPublicKey } from "./token.ts";
+import { fetchJwks, publicFetcher } from "./remote.ts";
 import type { PublicKeyEntry } from "./types.ts";
 
+export { extractCookie, makeClearCookie, makeSessionCookie } from "./cookie.ts";
+export type { AuthCodeExchangeConfig } from "./middleware.ts";
+export { checkBearerToken, getAuthUser, getClientIP, handleCallback, redirectToLogin } from "./middleware.ts";
+export { hasSiteAccess } from "./remote.ts";
+export { importPublicKey, validateToken } from "./token.ts";
+export type { CookieConfig, PublicKeyEntry, TokenPayload, VerifyConfig } from "./types.ts";
+
+/** Fetch and import the auth service's public signing keys. Cache the result; refetch when a token's kid is unknown. */
 export async function fetchPublicKeys(baseUrl: string): Promise<PublicKeyEntry[]> {
-  const res = await fetch(`${baseUrl}/.well-known/jwk.json`);
-  if (!res.ok) throw new Error(`Failed to fetch JWKS from ${baseUrl}: ${res.status}`);
-  const jwks = (await res.json()) as { keys: (JsonWebKey & { kid: string })[] };
-  return Promise.all(
-    jwks.keys.map(async (jwk) => ({
-      kid: jwk.kid,
-      key: await importPublicKey(jwk),
-    })),
-  );
+  return fetchJwks(publicFetcher(baseUrl));
 }

package/src/flow.ts

@@ -0,0 +1,178 @@
+import { extractCookie, makeSessionCookie } from "./cookie.ts";
+import { checkTokenRemote, exchangeAuthCode, type FetchLike, hasSiteAccessFor } from "./remote.ts";
+import type { CookieConfig, TokenPayload } from "./types.ts";
+import { LIBRARY_VERSION } from "./version.ts";
+
+// The one implementation of the site side of the login flow, shared by `@uln/auth/client`, `/service` and `/hono`.
+
+export const DEFAULT_AUTH_URL = "https://auth.uln.industries";
+
+/**
+ * Short-lived cookie tying a `?code=` callback to the browser that started the login. Its value is
+ * `<state>.<pkce verifier>`. The `__Host-` prefix makes browsers refuse it unless it was set by this exact host
+ * (Secure, `Path=/`, no `Domain`), so a page on a sibling subdomain can't plant a known state for the whole domain.
+ */
+export const STATE_COOKIE = "__Host-uln_auth_state";
+/** The state cookie's name on plain-http origins (local development), where browsers refuse `__Host-` cookies. */
+export const INSECURE_STATE_COOKIE = "uln_auth_state";
+/** Query parameter that carries the state through the auth service and back on the return URL. */
+export const STATE_PARAM = "uln_state";
+/**
+ * PKCE (RFC 7636, S256) challenge on the return URL. The auth service stores it with the one-time code and only
+ * exchanges the code for a client that presents the verifier, which never leaves this browser's state cookie, so a
+ * code that leaks (history, logs, a shared link) is useless on its own.
+ */
+export const CHALLENGE_PARAM = "uln_challenge";
+/**
+ * This library's version on the return URL (0.6.1+), so the auth service can track which version each site runs.
+ * The auth service strips it from the URL it sends the browser back to.
+ */
+export const VERSION_PARAM = "uln_v";
+const STATE_MAX_AGE_SECONDS = 600;
+
+function base64url(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function randomToken(): string {
+  return base64url(crypto.getRandomValues(new Uint8Array(32)));
+}
+
+/** S256 code challenge for a PKCE verifier: base64url(SHA-256(verifier)). */
+export async function pkceChallenge(verifier: string): Promise<string> {
+  return base64url(new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier))));
+}
+
+function stateCookie(value: string, secure: boolean, maxAgeSeconds: number): string {
+  const name = secure ? STATE_COOKIE : INSECURE_STATE_COOKIE;
+  const parts = [`${name}=${value}`, `Max-Age=${maxAgeSeconds}`, "Path=/", "HttpOnly", "SameSite=Lax"];
+  if (secure) parts.push("Secure");
+  return parts.join("; ");
+}
+
+function readStateCookie(request: Request, secure: boolean): { state: string; verifier: string } | null {
+  const name = secure ? STATE_COOKIE : INSECURE_STATE_COOKIE;
+  const [state = "", verifier = "", ...rest] = (extractCookie(request.headers.get("Cookie") ?? "", name) ?? "").split(
+    ".",
+  );
+  return state && verifier && rest.length === 0 ? { state, verifier } : null;
+}
+
+function stripCallbackParams(url: URL): void {
+  url.searchParams.delete("code");
+  url.searchParams.delete(STATE_PARAM);
+  url.searchParams.delete(CHALLENGE_PARAM);
+  url.searchParams.delete(VERSION_PARAM);
+}
+
+/**
+ * Redirect to the auth service's login page. Sets a one-time state cookie and puts the state on the return URL, which
+ * the auth service hands back untouched alongside `?code=`, together with a PKCE challenge for the verifier kept in
+ * the cookie. Requests a one-time code callback, so signed tokens never travel in URLs.
+ */
+export async function redirectToLogin(currentUrl: string, authUrl: string = DEFAULT_AUTH_URL): Promise<Response> {
+  const returnUrl = new URL(currentUrl);
+  stripCallbackParams(returnUrl);
+  const state = randomToken();
+  const verifier = randomToken();
+  returnUrl.searchParams.set(STATE_PARAM, state);
+  returnUrl.searchParams.set(CHALLENGE_PARAM, await pkceChallenge(verifier));
+  returnUrl.searchParams.set(VERSION_PARAM, LIBRARY_VERSION);
+
+  const loginUrl = new URL("/login", authUrl);
+  loginUrl.searchParams.set("redirect", returnUrl.toString());
+  loginUrl.searchParams.set("response_type", "code");
+
+  const headers = new Headers({ Location: loginUrl.toString() });
+  headers.append(
+    "Set-Cookie",
+    stateCookie(`${state}.${verifier}`, returnUrl.protocol === "https:", STATE_MAX_AGE_SECONDS),
+  );
+  return new Response(null, { status: 302, headers });
+}
+
+export interface LoginCallbackOptions {
+  auth: FetchLike;
+  authUrl: string;
+  cookieConfig: CookieConfig;
+  /** Validate the exchanged token (locally or with the auth service). Null rejects it. */
+  validate(token: string): Promise<TokenPayload | null>;
+  /** Origin registered for scopes, when it differs from the request URL's origin. */
+  scopeOrigin?: string;
+}
+
+/**
+ * Handle a `?code=` login callback; null when the request isn't one. The code is only exchanged when the request's
+ * `uln_state` matches this browser's state cookie, so a code planted in a link by someone else (login CSRF, which
+ * would sign the victim in to the attacker's account) is refused, and the exchange proves this browser holds the PKCE
+ * verifier. Any failure sends the user back to log in.
+ */
+export async function handleLoginCallback(request: Request, options: LoginCallbackOptions): Promise<Response | null> {
+  const url = new URL(request.url);
+  const code = url.searchParams.get("code");
+  if (!code) return null;
+
+  const state = url.searchParams.get(STATE_PARAM);
+  const secure = url.protocol === "https:";
+  const expected = readStateCookie(request, secure);
+  stripCallbackParams(url);
+  const startOver = () => redirectToLogin(url.toString(), options.authUrl);
+  if (!state || !expected || state !== expected.state) return startOver();
+
+  const token = await exchangeAuthCode(options.auth, code, url.origin, expected.verifier);
+  if (!token) return startOver();
+  const payload = await options.validate(token);
+  if (!payload) return startOver();
+  const scopeOrigin = options.scopeOrigin ?? url.origin;
+  if (!hasSiteAccessFor(payload, { audiences: [url.origin, scopeOrigin], scopeOrigin })) {
+    return new Response("You don't have access to this site", { status: 403 });
+  }
+
+  const headers = new Headers({ Location: url.toString() });
+  headers.append("Set-Cookie", makeSessionCookie(options.cookieConfig, token));
+  headers.append("Set-Cookie", stateCookie("", secure, 0));
+  return new Response(null, { status: 302, headers });
+}
+
+// --- Revocation checks for locally validated (JWKS) tokens ---
+
+/** Token → when the auth service last confirmed it (ms). Per isolate; insertion order doubles as LRU order. */
+const confirmedAt = new Map<string, number>();
+const MAX_CONFIRMED = 5000;
+export const DEFAULT_REVALIDATE_SECONDS = 300;
+
+/**
+ * Confirm a locally valid token with the auth service, at most once per `intervalSeconds` per token. Returns the
+ * payload to use: the auth service's (current admin/scopes/flags) after a fresh check, the local one while a previous
+ * confirmation is fresh or when the auth service can't be reached, and null when the auth service rejects the token
+ * (deleted user, revoked session, wrong audience).
+ */
+export async function revalidateToken(
+  auth: FetchLike,
+  token: string,
+  local: TokenPayload,
+  audience: string,
+  intervalSeconds: number = DEFAULT_REVALIDATE_SECONDS,
+): Promise<TokenPayload | null> {
+  const last = confirmedAt.get(token);
+  if (last !== undefined && Date.now() - last < intervalSeconds * 1000) return local;
+
+  const result = await checkTokenRemote(auth, token, audience);
+  if (result.status === "unavailable") return local;
+  confirmedAt.delete(token);
+  if (result.status === "invalid") return null;
+
+  if (confirmedAt.size >= MAX_CONFIRMED) {
+    const oldest = confirmedAt.keys().next();
+    if (!oldest.done) confirmedAt.delete(oldest.value);
+  }
+  confirmedAt.set(token, Date.now());
+  return result.payload;
+}
+
+/** Test hook: forget which tokens were recently confirmed. */
+export function clearRevalidationCache(): void {
+  confirmedAt.clear();
+}