@uln/auth 0.4.2 → 0.6.1

package/src/hono.ts

@@ -1,14 +1,34 @@
 import type { Context, MiddlewareHandler } from "hono";
 import { extractCookie } from "./cookie.ts";
-import { makeSessionCookie } from "./cookie.ts";
-import { importPublicKey } from "./token.ts";
-import { validateToken } from "./token.ts";
+import {
+  DEFAULT_AUTH_URL,
+  DEFAULT_REVALIDATE_SECONDS,
+  handleLoginCallback,
+  redirectToLogin,
+  revalidateToken,
+} from "./flow.ts";
+import {
+  bindingFetcher,
+  type FetchLike,
+  fetchJwks,
+  hasSiteAccessFor,
+  publicFetcher,
+  verifyTokenRemote,
+} from "./remote.ts";
+import { peekTokenKid, peekTokenPayload, validateToken } from "./token.ts";
 import type { CookieConfig, PublicKeyEntry, TokenPayload } from "./types.ts";
 
+declare module "hono" {
+  interface ContextVariableMap {
+    user: TokenPayload;
+  }
+}
+
 interface AuthOptions {
   /**
    * Service binding name (e.g. "AUTH"). If provided, validates tokens
    * via the auth worker service binding instead of fetching public keys.
+   * Binding mode also rejects tokens for deleted users and revoked sessions.
    */
   binding?: string;
 
@@ -23,15 +43,30 @@ interface AuthOptions {
    */
   authUrl?: string;
 
-  /** Cookie name. Defaults to "uln_auth". */
+  /**
+   * Cookie name. Defaults to "__Host-uln_auth": the `__Host-` prefix means only this exact host can set it, so a page on
+   * a sibling subdomain can't plant a session cookie (session fixation / cookie tossing).
+   */
   cookie?: string;
 
   /** Cookie/token max age in seconds. Defaults to 86400 (24h). */
   maxAge?: number;
+
+  /**
+   * The registered origin of this site, used for the scope check. Defaults to the request URL's origin.
+   * Set this when the Worker is reached through a different hostname than the one registered in auth.
+   */
+  siteOrigin?: string;
+
+  /**
+   * Public-key mode only: confirm a locally valid token with the auth service at most this often (seconds, per
+   * token), so password resets, deleted users and removed scopes take effect within this window instead of when the
+   * token expires. If the auth service is unreachable the local result stands. Defaults to 300; 0 disables.
+   */
+  revalidateSeconds?: number;
 }
 
-const DEFAULT_AUTH_URL = "https://auth.uln.industries";
-const DEFAULT_COOKIE = "uln_auth";
+const DEFAULT_COOKIE = "__Host-uln_auth";
 const DEFAULT_MAX_AGE = 86400;
 
 function isPublicPath(pathname: string, patterns: string[]): boolean {
@@ -48,98 +83,55 @@ function isPublicPath(pathname: string, patterns: string[]): boolean {
 
 // --- Public key caching (client mode) ---
 
-let cachedKeys: PublicKeyEntry[] | null = null;
-let cachedAt = 0;
-const CACHE_TTL = 3600_000; // 1 hour
-
-async function getPublicKeys(authUrl: string): Promise<PublicKeyEntry[]> {
-  if (cachedKeys && Date.now() - cachedAt < CACHE_TTL) {
-    return cachedKeys;
-  }
-  const res = await fetch(`${authUrl}/.well-known/jwk.json`);
-  if (!res.ok) throw new Error(`Failed to fetch JWKS from ${authUrl}: ${res.status}`);
-  const jwks = (await res.json()) as { keys: (JsonWebKey & { kid: string })[] };
-  cachedKeys = await Promise.all(
-    jwks.keys.map(async (jwk) => ({
-      kid: jwk.kid,
-      key: await importPublicKey(jwk),
-    })),
-  );
-  cachedAt = Date.now();
-  return cachedKeys;
+interface KeyCache {
+  keys: PublicKeyEntry[];
+  fetchedAt: number;
 }
 
-// --- Token validation ---
-
-async function validateWithPublicKeys(token: string, authUrl: string, maxAge: number): Promise<TokenPayload | null> {
-  const publicKeys = await getPublicKeys(authUrl);
-  return validateToken({ publicKeys, maxAgeSeconds: maxAge }, token);
+const keyCaches = new Map<string, KeyCache>();
+const CACHE_TTL = 10 * 60_000;
+/** Minimum spacing between forced refreshes triggered by an unknown `kid`, so bad tokens can't hammer JWKS. */
+const MIN_REFRESH_INTERVAL = 10_000;
+
+async function getPublicKeys(authUrl: string, wantedKid: string | null): Promise<PublicKeyEntry[]> {
+  const cached = keyCaches.get(authUrl);
+  const age = cached ? Date.now() - cached.fetchedAt : Number.POSITIVE_INFINITY;
+  const hasKid = wantedKid === null || cached?.keys.some((k) => k.kid === wantedKid);
+  // After a key rotation, tokens carry a kid we haven't seen yet — refetch instead of waiting out the TTL.
+  if (cached && age < CACHE_TTL && (hasKid || age < MIN_REFRESH_INTERVAL)) {
+    return cached.keys;
+  }
+  const keys = await fetchJwks(publicFetcher(authUrl));
+  keyCaches.set(authUrl, { keys, fetchedAt: Date.now() });
+  return keys;
 }
 
-async function validateWithBinding(token: string, binding: Fetcher): Promise<TokenPayload | null> {
-  const res = await binding.fetch("https://auth/api/verify-token", {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ token }),
-  });
-  if (!res.ok) return null;
-  const data = (await res.json()) as {
-    user: {
-      id: string;
-      email: string;
-      name: string;
-      admin: boolean;
-      scopes: string[];
-      flags: Record<string, string[]>;
-      kid: string;
-    };
-  };
-  return {
-    sub: data.user.id,
-    email: data.user.email,
-    name: data.user.name,
-    admin: data.user.admin,
-    scopes: data.user.scopes,
-    flags: data.user.flags,
-    kid: data.user.kid,
-    iat: 0,
-    exp: 0,
-  };
+/** Test hook: forget cached JWKS. */
+export function clearPublicKeyCache(): void {
+  keyCaches.clear();
 }
 
-async function exchangeCodeWithPublicEndpoint(
-  code: string,
-  redirectOrigin: string,
-  authUrl: string,
-): Promise<string | null> {
-  const res = await fetch(`${authUrl}/api/exchange-code`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ code, redirectOrigin }),
-  });
-  if (!res.ok) return null;
-  const data = (await res.json()) as { token?: string };
-  return typeof data.token === "string" ? data.token : null;
+function isFetcher(value: unknown): value is { fetch(input: string, init?: RequestInit): Promise<Response> } {
+  return typeof value === "object" && value !== null && "fetch" in value && typeof value.fetch === "function";
 }
 
-async function exchangeCodeWithBinding(code: string, redirectOrigin: string, binding: Fetcher): Promise<string | null> {
-  const res = await binding.fetch("https://auth/api/exchange-code", {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ code, redirectOrigin }),
-  });
-  if (!res.ok) return null;
-  const data = (await res.json()) as { token?: string };
-  return typeof data.token === "string" ? data.token : null;
+function getBinding(env: unknown, name: string): FetchLike {
+  const binding: unknown = typeof env === "object" && env !== null ? Reflect.get(env, name) : undefined;
+  if (!isFetcher(binding)) throw new Error(`Service binding "${name}" not found in env`);
+  return bindingFetcher(binding);
 }
 
 /**
  * Hono middleware that handles the full auth flow:
  *
- * 1. If `?code=` in URL → exchange for token, set cookie, redirect to clean URL
- * 2. If session cookie present → validate, set `c.get("user")`
+ * 1. If `?code=` in URL → check it belongs to this browser's login, exchange for token, set cookie, redirect to
+ *    clean URL
+ * 2. If session cookie or `Authorization: Bearer` present → validate, check site access, set `c.get("user")`
  * 3. If unauthenticated → redirect to auth.uln.industries/login
  *
+ * Tokens issued to another origin are rejected. Users without access to this site (not admin, origin not in
+ * `scopes`) get a 403.
+ *
  * Usage:
  * ```ts
  * import { auth } from "@uln/auth/hono";
@@ -163,33 +155,38 @@ export function auth(options?: AuthOptions): MiddlewareHandler {
   const maxAge = options?.maxAge ?? DEFAULT_MAX_AGE;
   const publicPaths = options?.public ?? [];
   const bindingName = options?.binding;
+  const revalidateSeconds = options?.revalidateSeconds ?? DEFAULT_REVALIDATE_SECONDS;
 
   const cookieConf: CookieConfig = { name: cookieName, maxAgeSeconds: maxAge, secure: true };
 
-  async function validate(token: string, env: Record<string, unknown>): Promise<TokenPayload | null> {
-    if (bindingName) {
-      const binding = env[bindingName] as Fetcher | undefined;
-      if (!binding) throw new Error(`Service binding "${bindingName}" not found in env`);
-      return validateWithBinding(token, binding);
-    }
-    return validateWithPublicKeys(token, authUrl, maxAge);
+  function authService(env: unknown): FetchLike {
+    return bindingName ? getBinding(env, bindingName) : publicFetcher(authUrl);
   }
 
-  async function exchangeCode(
-    code: string,
-    redirectOrigin: string,
-    env: Record<string, unknown>,
-  ): Promise<string | null> {
+  /**
+   * Validate a token issued to one of `audiences` (this site's origins); a token for any other audience — including
+   * one from before audience binding — counts as no session, so the user is sent to sign in. Scopes are checked by
+   * the caller.
+   */
+  async function validate(token: string, env: unknown, audiences: string[]): Promise<TokenPayload | null> {
     if (bindingName) {
-      const binding = env[bindingName] as Fetcher | undefined;
-      if (!binding) throw new Error(`Service binding "${bindingName}" not found in env`);
-      return exchangeCodeWithBinding(code, redirectOrigin, binding);
+      // The unverified `aud` only picks which audience to ask about (one call instead of one per origin); the auth
+      // service still checks it. Tokens for any other audience are refused without a call.
+      const audience = peekTokenPayload(token)?.aud;
+      if (audience === undefined || !audiences.includes(audience)) return null;
+      return verifyTokenRemote(getBinding(env, bindingName), token, audience);
     }
-    return exchangeCodeWithPublicEndpoint(code, redirectOrigin, authUrl);
+    const publicKeys = await getPublicKeys(authUrl, peekTokenKid(token));
+    const local = await validateToken({ publicKeys, maxAgeSeconds: maxAge }, token);
+    if (!local || local.aud === undefined || !audiences.includes(local.aud)) return null;
+    if (revalidateSeconds <= 0) return local;
+    return revalidateToken(publicFetcher(authUrl), token, local, local.aud, revalidateSeconds);
   }
 
   return async (c, next) => {
     const url = new URL(c.req.url);
+    const scopeOrigin = options?.siteOrigin ?? url.origin;
+    const site = { audiences: [url.origin, scopeOrigin], scopeOrigin };
 
     // Public paths bypass auth
     if (isPublicPath(url.pathname, publicPaths)) {
@@ -197,63 +194,52 @@ export function auth(options?: AuthOptions): MiddlewareHandler {
     }
 
     // Step 1: Handle ?code= callback (login redirect landing)
-    const incomingCode = url.searchParams.get("code");
-    if (incomingCode) {
-      const token = await exchangeCode(incomingCode, url.origin, c.env as Record<string, unknown>);
-      if (!token) {
-        return c.text("Invalid code", 401);
-      }
-      const payload = await validate(token, c.env as Record<string, unknown>);
-      if (!payload) {
-        return c.text("Invalid token", 401);
-      }
-
-      url.searchParams.delete("code");
-      return new Response(null, {
-        status: 302,
-        headers: {
-          Location: url.toString(),
-          "Set-Cookie": makeSessionCookie(cookieConf, token),
-        },
-      });
-    }
+    const callback = await handleLoginCallback(c.req.raw, {
+      auth: authService(c.env),
+      authUrl,
+      cookieConfig: cookieConf,
+      validate: (token) => validate(token, c.env, site.audiences),
+      scopeOrigin: site.scopeOrigin,
+    });
+    if (callback) return callback;
 
     // Step 2: Check session cookie
     const cookieHeader = c.req.header("Cookie");
     if (cookieHeader) {
       const token = extractCookie(cookieHeader, cookieName);
       if (token) {
-        const payload = await validate(token, c.env as Record<string, unknown>);
+        const payload = await validate(token, c.env, site.audiences);
         if (payload) {
+          if (!hasSiteAccessFor(payload, site)) {
+            return c.text("You don't have access to this site", 403);
+          }
           c.set("user", payload);
           return next();
         }
       }
     }
 
-    // Step 4: Check Authorization header
+    // Step 3: Check Authorization header
     const authHeader = c.req.header("Authorization");
     if (authHeader?.startsWith("Bearer ")) {
       const token = authHeader.substring(7);
-      const payload = await validate(token, c.env as Record<string, unknown>);
-      if (payload) {
-        c.set("user", payload);
-        return next();
-      }
-      return c.json({ error: "Invalid token" }, 401);
+      const payload = await validate(token, c.env, site.audiences);
+      if (!payload) return c.json({ error: "Invalid token" }, 401);
+      if (!hasSiteAccessFor(payload, site)) return c.json({ error: "Forbidden" }, 403);
+      c.set("user", payload);
+      return next();
     }
 
-    // Step 5: Redirect to login
-    const loginUrl = new URL("/login", authUrl);
-    loginUrl.searchParams.set("redirect", c.req.url);
-    loginUrl.searchParams.set("response_type", "code");
-    return c.redirect(loginUrl.toString(), 302);
+    // Step 4: Redirect to login
+    return redirectToLogin(c.req.url, authUrl);
   };
 }
 
-/** Type-safe helper to get the authenticated user from context. */
+/** Get the authenticated user from context. Throws if called on a route that `auth()` doesn't cover. */
 export function getUser(c: Context): TokenPayload {
-  return c.get("user") as TokenPayload;
+  const user: TokenPayload | undefined = c.get("user");
+  if (!user) throw new Error("getUser() called on a route that is not behind the auth() middleware");
+  return user;
 }
 
 export type { TokenPayload } from "./types.ts";

package/src/index.ts

@@ -1,29 +1,37 @@
-export type {
-  User,
-  UserStore,
-  RateLimitEntry,
-  RateLimitStore,
-  RateLimitConfig,
-  TokenPayload,
-  SigningConfig,
-  VerifyConfig,
-  PublicKeyEntry,
-  CookieConfig,
-} from "./types.ts";
-
-export { hashPassword, verifyPassword } from "./password.ts";
-export { createToken, validateToken, generateKeyPair, importPrivateKey, importPublicKey } from "./token.ts";
-export type { CreateTokenInput } from "./token.ts";
-export { makeSessionCookie, makeClearCookie, extractCookie } from "./cookie.ts";
-export { checkRateLimit, recordFailedAttempt, clearRateLimit } from "./rate-limit.ts";
+export { extractCookie, makeClearCookie, makeSessionCookie } from "./cookie.ts";
+export { checkBearerToken, getAuthUser, getClientIP, redirectToLogin } from "./middleware.ts";
+export { hashPassword, MAX_PASSWORD_LENGTH, needsRehash, verifyPassword } from "./password.ts";
 export type { RateLimitResult } from "./rate-limit.ts";
-export { getClientIP, checkBearerToken, getAuthUser, redirectToLogin } from "./middleware.ts";
-export { createUser, verifyUserCredentials, changePassword, isValidEmail } from "./users.ts";
+export { checkRateLimit, clearRateLimit, consumeRateLimit, recordFailedAttempt } from "./rate-limit.ts";
+export { hasSiteAccess } from "./remote.ts";
+export type { CreateTokenInput } from "./token.ts";
+export {
+  createToken,
+  generateKeyPair,
+  importPrivateKey,
+  importPublicKey,
+  isTokenPayload,
+  validateToken,
+} from "./token.ts";
 export {
-  generateTotpSecret,
-  getTotpUri,
-  verifyTotpCode,
   base32Encode,
   generateBackupCodes,
+  generateTotpSecret,
+  getTotpUri,
   hashBackupCode,
+  verifyTotpCode,
+  verifyTotpStep,
 } from "./totp.ts";
+export type {
+  CookieConfig,
+  PublicKeyEntry,
+  RateLimitConfig,
+  RateLimitEntry,
+  RateLimitStore,
+  SigningConfig,
+  TokenPayload,
+  User,
+  UserStore,
+  VerifyConfig,
+} from "./types.ts";
+export { changePassword, createUser, isValidEmail, verifyUserCredentials } from "./users.ts";

package/src/middleware.ts

@@ -1,11 +1,19 @@
-import { extractCookie, makeSessionCookie } from "./cookie.ts";
+import { extractCookie } from "./cookie.ts";
+import { DEFAULT_AUTH_URL, handleLoginCallback, revalidateToken } from "./flow.ts";
+import { hasSiteAccessFor, publicFetcher } from "./remote.ts";
 import { validateToken } from "./token.ts";
 import type { CookieConfig, TokenPayload, VerifyConfig } from "./types.ts";
 
+export { redirectToLogin } from "./flow.ts";
+
 export interface AuthCodeExchangeConfig {
   authUrl: string;
 }
 
+/**
+ * Best-effort client IP. Prefers Cloudflare's `cf-connecting-ip`, which clients cannot spoof when the request
+ * arrives through Cloudflare. `x-forwarded-for` is only a fallback and is attacker-controlled off Cloudflare.
+ */
 export function getClientIP(request: Request): string {
   return (
     request.headers.get("cf-connecting-ip") ??
@@ -14,15 +22,29 @@ export function getClientIP(request: Request): string {
   );
 }
 
+/** Constant-time check that the request carries `Authorization: Bearer <expectedToken>`. */
 export function checkBearerToken(request: Request, expectedToken: string): boolean {
-  const header = request.headers.get("Authorization");
-  return header === `Bearer ${expectedToken}`;
+  const header = request.headers.get("Authorization") ?? "";
+  const expected = `Bearer ${expectedToken}`;
+  const a = new TextEncoder().encode(header);
+  const b = new TextEncoder().encode(expected);
+  let diff = a.length ^ b.length;
+  for (let i = 0; i < b.length; i++) {
+    diff |= (a[i] ?? 0) ^ (b[i] ?? 0);
+  }
+  return diff === 0;
 }
 
+/**
+ * Get the authenticated user from the session cookie, validated locally against `verifyConfig` (and confirmed with
+ * the auth service when `verifyConfig.revalidate` is set). Returns null if not authenticated, or if the token wasn't
+ * issued to — or the user doesn't have access to — `siteOrigin` (defaults to the request's origin).
+ */
 export async function getAuthUser(
   request: Request,
   verifyConfig: VerifyConfig,
   cookieConfig: CookieConfig,
+  siteOrigin?: string,
 ): Promise<TokenPayload | null> {
   const cookieHeader = request.headers.get("Cookie");
   if (!cookieHeader) return null;
@@ -30,36 +52,29 @@ export async function getAuthUser(
   const token = extractCookie(cookieHeader, cookieConfig.name);
   if (!token) return null;
 
-  return validateToken(verifyConfig, token);
-}
-
-export function redirectToLogin(currentUrl: string): Response {
-  const loginUrl = new URL("/login", "https://auth.uln.industries");
-  loginUrl.searchParams.set("redirect", currentUrl);
-  loginUrl.searchParams.set("response_type", "code");
-  return Response.redirect(loginUrl.toString(), 302);
-}
+  const audience = new URL(request.url).origin;
+  const scopeOrigin = siteOrigin ?? audience;
+  const site = { audiences: [audience, scopeOrigin], scopeOrigin };
+  const payload = await validateToken(verifyConfig, token);
+  if (!payload || !hasSiteAccessFor(payload, site)) return null;
 
-async function exchangeCode(
-  code: string,
-  redirectOrigin: string,
-  config: AuthCodeExchangeConfig,
-): Promise<string | null> {
-  const res = await fetch(`${config.authUrl}/api/exchange-code`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ code, redirectOrigin }),
-  });
-  if (!res.ok) return null;
-  const data = (await res.json()) as { token?: string };
-  return typeof data.token === "string" ? data.token : null;
+  const { revalidate } = verifyConfig;
+  if (!revalidate) return payload;
+  const current = await revalidateToken(
+    publicFetcher(revalidate.authUrl),
+    token,
+    payload,
+    payload.aud ?? audience,
+    revalidate.intervalSeconds,
+  );
+  return current && hasSiteAccessFor(current, site) ? current : null;
 }
 
 /**
  * Handle the auth callback on consuming sites.
- * If the request URL has a `?code=` param, exchanges it for a token,
- * sets a session cookie, and redirects to the same URL without the code param.
- * Returns null if there's no callback param.
+ * If the request URL has a `?code=` param (and the login was started by this browser), exchanges it for a token,
+ * sets a session cookie, and redirects to the same URL without the callback params.
+ * Returns 403 if the user doesn't have access to this site, or null if there's no callback param.
  */
 export async function handleCallback(
   request: Request,
@@ -67,26 +82,11 @@ export async function handleCallback(
   cookieConfig: CookieConfig,
   exchangeConfig?: AuthCodeExchangeConfig,
 ): Promise<Response | null> {
-  const url = new URL(request.url);
-  const code = url.searchParams.get("code");
-  if (code) {
-    if (!exchangeConfig) return redirectToLogin(url.origin);
-
-    const token = await exchangeCode(code, url.origin, exchangeConfig);
-    if (!token) return redirectToLogin(url.origin);
-
-    const payload = await validateToken(verifyConfig, token);
-    if (!payload) return redirectToLogin(url.origin);
-
-    url.searchParams.delete("code");
-    return new Response(null, {
-      status: 302,
-      headers: {
-        Location: url.toString(),
-        "Set-Cookie": makeSessionCookie(cookieConfig, token),
-      },
-    });
-  }
-
-  return null;
+  const authUrl = exchangeConfig?.authUrl ?? DEFAULT_AUTH_URL;
+  return handleLoginCallback(request, {
+    auth: publicFetcher(authUrl),
+    authUrl,
+    cookieConfig,
+    validate: (token) => validateToken(verifyConfig, token),
+  });
 }

package/src/password.ts

@@ -1,6 +1,15 @@
 const SALT_LENGTH = 32;
 const KEY_LENGTH = 64;
-const ITERATIONS = 100_000;
+// 100k is the maximum PBKDF2 iteration count the Cloudflare Workers runtime accepts in one call. Higher work factors
+// chain calls: each stage's output is the next stage's key material (same salt), so a guess still costs every stage.
+const STAGE_ITERATIONS = 100_000;
+/** OWASP's recommendation for PBKDF2-HMAC-SHA256. New hashes use this; older ones are upgraded on the next login. */
+const ITERATIONS = 600_000;
+const MAX_ITERATIONS = 10_000_000;
+/** Upper bound enforced wherever a password is *set*. Verification accepts any length so no stored password is locked out. */
+export const MAX_PASSWORD_LENGTH = 1024;
+const HEX_REGEX = /^(?:[0-9a-f]{2})+$/;
+const PREFIX = "pbkdf2-sha256";
 
 function toHex(buffer: ArrayBuffer): string {
   return Array.from(new Uint8Array(buffer))
@@ -16,44 +25,75 @@ function fromHex(hex: string): Uint8Array<ArrayBuffer> {
   return bytes;
 }
 
-async function deriveKey(password: string, salt: Uint8Array<ArrayBuffer>): Promise<ArrayBuffer> {
-  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: string, salt: Uint8Array<ArrayBuffer>, iterations: number): Promise<ArrayBuffer> {
+  let material: BufferSource = 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;
+}
+
+interface ParsedHash {
+  iterations: number;
+  salt: Uint8Array<ArrayBuffer>;
+  key: Uint8Array<ArrayBuffer>;
 }
 
-/** Hash a password with PBKDF2-SHA256 (100k iterations, 32-byte salt, 64-byte key). Returns `hex(salt):hex(key)`. */
+/** `pbkdf2-sha256$<iterations>$<salt>$<key>`, or the original `<salt>:<key>` (one 100k stage). */
+function parseHash(storedHash: string): ParsedHash | null {
+  let iterations = STAGE_ITERATIONS;
+  let saltHex: string;
+  let keyHex: string;
+  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) };
+}
+
+/**
+ * Hash a password with PBKDF2-SHA256 (600k iterations, 32-byte salt, 64-byte key). Returns
+ * `pbkdf2-sha256$600000$hex(salt)$hex(key)`.
+ */
 export async function hashPassword(password: string): Promise<string> {
   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)}`;
 }
 
-/** Verify a password against a stored `hex(salt):hex(key)` hash. Uses constant-time comparison. */
+/** Verify a password against any hash `hashPassword` produces now or produced before. Uses constant-time comparison. */
 export async function verifyPassword(password: string, storedHash: string): Promise<boolean> {
-  const separatorIndex = storedHash.indexOf(":");
-  if (separatorIndex === -1) 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));
+  const parsed = parseHash(storedHash);
+  if (!parsed) return false;
+  const derived = new Uint8Array(await deriveKey(password, parsed.salt, parsed.iterations));
 
-  if (derived.length !== expectedKey.length) return false;
+  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;
 }
+
+/** Whether a stored hash is weaker than what `hashPassword` produces now, so it should be replaced after a login. */
+export function needsRehash(storedHash: string): boolean {
+  return !storedHash.startsWith(`${PREFIX}$`) || (parseHash(storedHash)?.iterations ?? 0) < ITERATIONS;
+}