@uln/auth 0.4.2 → 0.6.0

package/src/rate-limit.ts

@@ -5,6 +5,39 @@ export interface RateLimitResult {
   remainingSeconds?: number;
 }
 
+/**
+ * Count an attempt against `key` and report whether the caller is now over the limit. The attempt is recorded
+ * *before* the decision, so concurrent requests can't all pass a check that ran before any of them was counted.
+ * Clear the key on success. Race-free only when the store implements `increment`.
+ */
+export async function consumeRateLimit(
+  store: RateLimitStore,
+  key: string,
+  config: RateLimitConfig,
+): Promise<RateLimitResult> {
+  const entry = store.increment
+    ? await store.increment(key, config.windowSeconds)
+    : await incrementViaGetSet(store, key, config);
+  if (entry.attempts <= config.maxAttempts) return { blocked: false };
+  const remaining = config.windowSeconds - Math.floor((Date.now() - entry.firstAttempt) / 1000);
+  return { blocked: true, remainingSeconds: Math.max(remaining, 1) };
+}
+
+async function incrementViaGetSet(store: RateLimitStore, key: string, config: RateLimitConfig) {
+  const existing = await store.get(key);
+  const windowOver = existing !== null && Date.now() - existing.firstAttempt >= config.windowSeconds * 1000;
+  const entry =
+    existing && !windowOver
+      ? { attempts: existing.attempts + 1, firstAttempt: existing.firstAttempt }
+      : { attempts: 1, firstAttempt: Date.now() };
+  await store.set(key, entry, config.windowSeconds);
+  return entry;
+}
+
+/**
+ * @deprecated Check-then-record is racy: concurrent requests all pass the check before any is recorded. Use
+ * `consumeRateLimit`.
+ */
 export async function checkRateLimit(
   store: RateLimitStore,
   key: string,
@@ -24,7 +57,12 @@ export async function checkRateLimit(
   return { blocked: false };
 }
 
+/** @deprecated Pair of `checkRateLimit`; use `consumeRateLimit`. */
 export async function recordFailedAttempt(store: RateLimitStore, key: string, config: RateLimitConfig): Promise<void> {
+  if (store.increment) {
+    await store.increment(key, config.windowSeconds);
+    return;
+  }
   const entry = await store.get(key);
   if (entry) {
     await store.set(key, { attempts: entry.attempts + 1, firstAttempt: entry.firstAttempt }, config.windowSeconds);

package/src/remote.ts

@@ -0,0 +1,158 @@
+import { importPublicKey, isTokenPayload } from "./token.ts";
+import type { PublicKeyEntry, TokenPayload } from "./types.ts";
+
+/** Anything with a Fetch-compatible `fetch` — the global `fetch` wrapped, or a Cloudflare service binding. */
+export interface FetchLike {
+  fetch(input: string, init?: RequestInit): Promise<Response>;
+}
+
+/** Calls the auth service over the public internet. */
+export function publicFetcher(authUrl: string): FetchLike {
+  return { fetch: (path, init) => fetch(new URL(path, authUrl), init) };
+}
+
+/** Calls the auth service through a Cloudflare service binding. The hostname is ignored by bindings. */
+export function bindingFetcher(binding: { fetch(input: string, init?: RequestInit): Promise<Response> }): FetchLike {
+  return { fetch: (path, init) => binding.fetch(new URL(path, "https://auth").toString(), init) };
+}
+
+function isLoopbackHostname(hostname: string): boolean {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
+}
+
+function toOrigin(value: string): string | null {
+  try {
+    return new URL(value).origin;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Whether a validated token grants access to `origin`. The token's `aud` must be this origin — a token issued to
+ * another site (or to the auth service itself) is never accepted, even for admins. Then admins can access every
+ * site; everyone else needs the origin in their `scopes` (loopback origins are exempt so local development works).
+ *
+ * A valid signature alone only proves the user has *an* account — every consuming site must also run this check.
+ */
+export function hasSiteAccess(payload: TokenPayload, origin: string): boolean {
+  return hasSiteAccessFor(payload, { audiences: [origin], scopeOrigin: origin });
+}
+
+/**
+ * `hasSiteAccess` for a site that answers on more than one origin — e.g. a Worker whose request URL origin (where the
+ * login callback landed, and so the token's audience) differs from the origin registered for scopes.
+ */
+export function hasSiteAccessFor(payload: TokenPayload, site: { audiences: string[]; scopeOrigin: string }): boolean {
+  const scopeOrigin = toOrigin(site.scopeOrigin);
+  if (!scopeOrigin || payload.aud === undefined) return false;
+  if (!site.audiences.some((audience) => toOrigin(audience) === payload.aud)) return false;
+  if (payload.admin) return true;
+  if (isLoopbackHostname(new URL(scopeOrigin).hostname)) return true;
+  return payload.scopes.includes(scopeOrigin);
+}
+
+async function readJsonObject(res: Response): Promise<object | null> {
+  try {
+    const body: unknown = await res.json();
+    return typeof body === "object" && body !== null ? body : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * POST /api/exchange-code — trade a one-time `?code=` for a signed token bound to `redirectOrigin`. `codeVerifier` is
+ * the PKCE verifier whose challenge went out with the login (required for codes issued with one).
+ */
+export async function exchangeAuthCode(
+  auth: FetchLike,
+  code: string,
+  redirectOrigin: string,
+  codeVerifier?: string,
+): Promise<string | null> {
+  const res = await auth.fetch("/api/exchange-code", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(
+      codeVerifier === undefined ? { code, redirectOrigin } : { code, redirectOrigin, codeVerifier },
+    ),
+  });
+  if (!res.ok) return null;
+  const body = await readJsonObject(res);
+  if (!body || !("token" in body) || typeof body.token !== "string") return null;
+  return body.token;
+}
+
+export type RemoteCheck =
+  | { status: "valid"; payload: TokenPayload }
+  | { status: "invalid" }
+  /** Network error or 5xx — the auth service didn't give an answer. */
+  | { status: "unavailable" };
+
+/**
+ * POST /api/verify-token — validate a token with the auth service itself. Unlike local JWKS validation this also
+ * rejects tokens for deleted users or revoked sessions, and returns the user's *current* admin/scopes/flags. With an
+ * `audience`, the auth service also rejects tokens issued to any other origin.
+ */
+export async function checkTokenRemote(auth: FetchLike, token: string, audience?: string): Promise<RemoteCheck> {
+  let res: Response;
+  try {
+    res = await auth.fetch("/api/verify-token", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(audience === undefined ? { token } : { token, audience }),
+    });
+  } catch {
+    return { status: "unavailable" };
+  }
+  if (res.status >= 500) return { status: "unavailable" };
+  if (!res.ok) return { status: "invalid" };
+  const body = await readJsonObject(res);
+  if (!body || !("user" in body) || typeof body.user !== "object" || body.user === null) return { status: "invalid" };
+  const user = body.user;
+  if (!("id" in user)) return { status: "invalid" };
+  const candidate = { ...user, sub: user.id, iat: "iat" in user ? user.iat : 0, exp: "exp" in user ? user.exp : 0 };
+  if (!isTokenPayload(candidate)) return { status: "invalid" };
+  return {
+    status: "valid",
+    payload: {
+      sub: candidate.sub,
+      email: candidate.email,
+      name: candidate.name,
+      admin: candidate.admin,
+      scopes: candidate.scopes,
+      flags: candidate.flags,
+      kid: candidate.kid,
+      iat: candidate.iat,
+      exp: candidate.exp,
+      ...(candidate.aud === undefined ? {} : { aud: candidate.aud }),
+    },
+  };
+}
+
+/** `checkTokenRemote`, collapsed to the payload or null (an unreachable auth service counts as invalid). */
+export async function verifyTokenRemote(
+  auth: FetchLike,
+  token: string,
+  audience?: string,
+): Promise<TokenPayload | null> {
+  const result = await checkTokenRemote(auth, token, audience);
+  return result.status === "valid" ? result.payload : null;
+}
+
+/** Fetch and import the auth service's JWKS (`/.well-known/jwk.json`). Keys without a string `kid` are skipped. */
+export async function fetchJwks(auth: FetchLike): Promise<PublicKeyEntry[]> {
+  const res = await auth.fetch("/.well-known/jwk.json");
+  if (!res.ok) throw new Error(`Failed to fetch JWKS: ${res.status}`);
+  const body = await readJsonObject(res);
+  if (!body || !("keys" in body) || !Array.isArray(body.keys)) throw new Error("Malformed JWKS response");
+  const entries: PublicKeyEntry[] = [];
+  for (const jwk of body.keys) {
+    if (typeof jwk !== "object" || jwk === null || !("kid" in jwk) || typeof jwk.kid !== "string") continue;
+    if (!("kty" in jwk) || typeof jwk.kty !== "string") continue;
+    const { kid, ...keyData } = jwk;
+    entries.push({ kid, key: await importPublicKey({ ...keyData, kty: jwk.kty }) });
+  }
+  return entries;
+}

package/src/service.ts

@@ -1,51 +1,38 @@
-import { extractCookie, makeSessionCookie } from "./cookie.ts";
+import { extractCookie } from "./cookie.ts";
+import { DEFAULT_AUTH_URL, handleLoginCallback } from "./flow.ts";
+import { bindingFetcher, hasSiteAccessFor, verifyTokenRemote } from "./remote.ts";
+import { peekTokenPayload } from "./token.ts";
 import type { CookieConfig, TokenPayload } from "./types.ts";
-export { makeSessionCookie, makeClearCookie } from "./cookie.ts";
-export type { TokenPayload, CookieConfig } from "./types.ts";
+
+export { makeClearCookie, makeSessionCookie } from "./cookie.ts";
+export { redirectToLogin } from "./flow.ts";
+export { hasSiteAccess } from "./remote.ts";
+export type { CookieConfig, TokenPayload } from "./types.ts";
 
 /**
  * Validate a raw token string via the auth service binding.
- * Returns the token payload or null if invalid.
+ * Returns the token payload (with the user's current admin/scopes/flags) or null if invalid or revoked. Pass the
+ * site's origin as `audience` so tokens issued to other origins are rejected too.
+ * This does not check site access — use `getAuthUser` or `hasSiteAccess` for that.
  */
-export async function verifyToken(authService: Fetcher, token: string): Promise<TokenPayload | null> {
-  const res = await authService.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,
-  };
+export async function verifyToken(
+  authService: Fetcher,
+  token: string,
+  audience?: string,
+): Promise<TokenPayload | null> {
+  return verifyTokenRemote(bindingFetcher(authService), token, audience);
 }
 
 /**
  * Get the authenticated user from the session cookie via the auth service binding.
- * Returns the token payload or null if not authenticated.
+ * 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,
   authService: Fetcher,
   cookieConfig: CookieConfig,
+  siteOrigin?: string,
 ): Promise<TokenPayload | null> {
   const cookieHeader = request.headers.get("Cookie");
   if (!cookieHeader) return null;
@@ -53,60 +40,33 @@ export async function getAuthUser(
   const token = extractCookie(cookieHeader, cookieConfig.name);
   if (!token) return null;
 
-  return verifyToken(authService, token);
-}
-
-/**
- * Redirect to the centralized login page at auth.uln.industries.
- * Requests one-time auth-code callbacks so signed tokens are not sent through URLs.
- */
-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);
-}
-
-async function exchangeCode(authService: Fetcher, code: string, redirectOrigin: string): Promise<string | null> {
-  const res = await authService.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;
+  // With a separate `siteOrigin`, either origin may be the token's audience. The unverified `aud` only picks which one
+  // to ask the auth service about (which checks it), so this is one call, and none for a token issued elsewhere.
+  const requestOrigin = new URL(request.url).origin;
+  const scopeOrigin = siteOrigin ?? requestOrigin;
+  const audiences = [requestOrigin, scopeOrigin];
+  const audience = peekTokenPayload(token)?.aud;
+  if (audience === undefined || !audiences.includes(audience)) return null;
+  const payload = await verifyToken(authService, token, audience);
+  if (!payload || !hasSiteAccessFor(payload, { audiences, scopeOrigin })) return null;
+  return payload;
 }
 
 /**
  * Handle an auth callback on a consuming Worker using the auth service binding.
- * Preferred `?code=` callbacks are exchanged for signed tokens before setting the local cookie.
- * Returns null if the request has no auth callback parameters.
+ * `?code=` callbacks started by this browser are exchanged for signed tokens before setting the local cookie.
+ * Returns 403 if the user doesn't have access to this site, or null if the request has no callback parameters.
  */
 export async function handleCallback(
   request: Request,
   authService: Fetcher,
   cookieConfig: CookieConfig,
 ): Promise<Response | null> {
-  const url = new URL(request.url);
-
-  const code = url.searchParams.get("code");
-  if (code) {
-    const token = await exchangeCode(authService, code, url.origin);
-    if (!token) return redirectToLogin(url.origin);
-
-    const payload = await verifyToken(authService, 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 audience = new URL(request.url).origin;
+  return handleLoginCallback(request, {
+    auth: bindingFetcher(authService),
+    authUrl: DEFAULT_AUTH_URL,
+    cookieConfig,
+    validate: (token) => verifyToken(authService, token, audience),
+  });
 }

package/src/token.ts

@@ -10,7 +10,8 @@ function base64urlEncode(data: Uint8Array): string {
   return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
 
-function base64urlDecode(str: string): Uint8Array {
+function base64urlDecode(str: string): Uint8Array<ArrayBuffer> {
+  if (!/^[A-Za-z0-9_-]*$/.test(str)) throw new Error("Invalid base64url");
   const padded = str.replace(/-/g, "+").replace(/_/g, "/");
   const binary = atob(padded);
   const bytes = new Uint8Array(binary.length);
@@ -52,11 +53,22 @@ export interface CreateTokenInput {
   isAdmin: boolean;
   scopes: string[];
   flags: Record<string, string[]>;
+  /** The origin the token is for (see `TokenPayload.aud`). */
+  audience?: string;
+}
+
+export interface CreateTokenOptions {
+  /** Unix seconds to use as `iat` instead of now (e.g. to land just after a session revocation cut-off). */
+  issuedAt?: number;
 }
 
 /** Create a signed token: `base64url(JSON payload).base64url(ECDSA-SHA256 signature)`. */
-export async function createToken(config: SigningConfig, user: CreateTokenInput): Promise<string> {
-  const now = Math.floor(Date.now() / 1000);
+export async function createToken(
+  config: SigningConfig,
+  user: CreateTokenInput,
+  options: CreateTokenOptions = {},
+): Promise<string> {
+  const now = options.issuedAt ?? Math.floor(Date.now() / 1000);
   const payload: TokenPayload = {
     sub: user.id,
     email: user.email,
@@ -67,6 +79,7 @@ export async function createToken(config: SigningConfig, user: CreateTokenInput)
     kid: config.kid,
     iat: now,
     exp: now + config.maxAgeSeconds,
+    ...(user.audience === undefined ? {} : { aud: user.audience }),
   };
   const payloadB64 = base64urlEncode(encoder.encode(JSON.stringify(payload)));
   const payloadBytes = encoder.encode(payloadB64);
@@ -75,28 +88,72 @@ export async function createToken(config: SigningConfig, user: CreateTokenInput)
   return `${payloadB64}.${sigB64}`;
 }
 
-/** Validate a signed token. Returns the payload if valid and not expired, or null. Matches `kid` to find the correct public key. */
-export async function validateToken(config: VerifyConfig, token: string): Promise<TokenPayload | null> {
-  const dotIndex = token.indexOf(".");
-  if (dotIndex === -1) return null;
+/** Allowed clock skew between the issuer and a verifier, in seconds. */
+const CLOCK_SKEW_SECONDS = 60;
 
-  const payloadB64 = token.substring(0, dotIndex);
-  const sigB64 = token.substring(dotIndex + 1);
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((v) => typeof v === "string");
+}
 
-  let payload: TokenPayload;
-  try {
-    const decoded = new TextDecoder().decode(base64urlDecode(payloadB64));
-    payload = JSON.parse(decoded) as TokenPayload;
-  } catch {
-    return null;
+function isFlags(value: unknown): value is Record<string, string[]> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  return Object.values(value).every(isStringArray);
+}
+
+/** Structural check for a decoded token payload. Rejects anything whose fields don't match `TokenPayload`. */
+export function isTokenPayload(value: unknown): value is TokenPayload {
+  if (typeof value !== "object" || value === null) return false;
+  if (
+    !("sub" in value) ||
+    !("email" in value) ||
+    !("name" in value) ||
+    !("admin" in value) ||
+    !("scopes" in value) ||
+    !("flags" in value) ||
+    !("kid" in value) ||
+    !("iat" in value) ||
+    !("exp" in value)
+  ) {
+    return false;
   }
+  return (
+    typeof value.sub === "string" &&
+    typeof value.email === "string" &&
+    typeof value.name === "string" &&
+    typeof value.admin === "boolean" &&
+    isStringArray(value.scopes) &&
+    isFlags(value.flags) &&
+    typeof value.kid === "string" &&
+    Number.isSafeInteger(value.iat) &&
+    Number.isSafeInteger(value.exp) &&
+    (!("aud" in value) || value.aud === undefined || typeof value.aud === "string")
+  );
+}
 
-  if (typeof payload.sub !== "string" || typeof payload.exp !== "number" || typeof payload.kid !== "string") {
+/**
+ * Validate a signed token. Returns the payload if the signature is valid and the token is within its lifetime,
+ * or null. Matches `kid` to find the correct public key. Tokens issued in the future (beyond a small clock skew)
+ * or older than `config.maxAgeSeconds` are rejected even if `exp` says otherwise.
+ */
+export async function validateToken(config: VerifyConfig, token: string): Promise<TokenPayload | null> {
+  const parts = token.split(".");
+  if (parts.length !== 2) return null;
+  const [payloadB64 = "", sigB64 = ""] = parts;
+  if (!payloadB64 || !sigB64) return null;
+
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(new TextDecoder().decode(base64urlDecode(payloadB64)));
+  } catch {
     return null;
   }
+  if (!isTokenPayload(decoded)) return null;
+  const payload = decoded;
 
   const now = Math.floor(Date.now() / 1000);
   if (now > payload.exp) return null;
+  if (payload.iat > now + CLOCK_SKEW_SECONDS) return null;
+  if (now - payload.iat > config.maxAgeSeconds) return null;
 
   const entry = config.publicKeys.find((k) => k.kid === payload.kid);
   if (!entry) return null;
@@ -112,3 +169,31 @@ export async function validateToken(config: VerifyConfig, token: string): Promis
 
   return payload;
 }
+
+/**
+ * Decode a token's payload **without verifying it** — only to decide which key or account to look up, or which
+ * audience to ask about, before the real check. Null unless it is structurally a `TokenPayload`.
+ */
+export function peekTokenPayload(token: string): TokenPayload | null {
+  const payloadB64 = token.split(".")[0];
+  if (!payloadB64) return null;
+  try {
+    const decoded: unknown = JSON.parse(new TextDecoder().decode(base64urlDecode(payloadB64)));
+    return isTokenPayload(decoded) ? decoded : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Read the `kid` claim from a token without verifying it. Used to decide whether a JWKS refresh is worthwhile. */
+export function peekTokenKid(token: string): string | null {
+  const payloadB64 = token.split(".")[0];
+  if (!payloadB64) return null;
+  try {
+    const decoded: unknown = JSON.parse(new TextDecoder().decode(base64urlDecode(payloadB64)));
+    if (typeof decoded !== "object" || decoded === null || !("kid" in decoded)) return null;
+    return typeof decoded.kid === "string" ? decoded.kid : null;
+  } catch {
+    return null;
+  }
+}

package/src/totp.ts

@@ -111,19 +111,29 @@ export async function currentTotpCode(secret: string, nowMs = Date.now()): Promi
   return generateCode(secret, step);
 }
 
-/** Verify a TOTP code against the secret. Allows ±1 time step for clock drift. */
-export async function verifyTotpCode(secret: string, code: string): Promise<boolean> {
-  if (code.length !== TOTP_DIGITS) return false;
+/**
+ * Verify a TOTP code against the secret, allowing ±1 time step for clock drift.
+ * Returns the matched time step, or null. Callers should persist the step and reject any code whose step is not
+ * strictly greater than the last accepted one — otherwise a code can be replayed for up to 90 seconds.
+ */
+export async function verifyTotpStep(secret: string, code: string, nowMs = Date.now()): Promise<number | null> {
+  if (!/^\d{6}$/.test(code)) return null;
 
-  const now = Math.floor(Date.now() / 1000);
-  const currentStep = Math.floor(now / TOTP_PERIOD);
+  const currentStep = Math.floor(nowMs / 1000 / TOTP_PERIOD);
 
+  // Check every step (no early exit) so timing doesn't reveal which window matched.
+  let matched: number | null = null;
   for (let offset = -TOTP_WINDOW; offset <= TOTP_WINDOW; offset++) {
-    const expected = await generateCode(secret, currentStep + offset);
-    if (timingSafeEqual(code, expected)) return true;
+    const step = currentStep + offset;
+    const expected = await generateCode(secret, step);
+    if (timingSafeEqual(code, expected)) matched = step;
   }
+  return matched;
+}
 
-  return false;
+/** Verify a TOTP code against the secret. Allows ±1 time step for clock drift. Does not prevent replay. */
+export async function verifyTotpCode(secret: string, code: string): Promise<boolean> {
+  return (await verifyTotpStep(secret, code)) !== null;
 }
 
 const BACKUP_CODE_COUNT = 10;
@@ -134,11 +144,14 @@ const BACKUP_CODE_CHARS = "abcdefghijklmnopqrstuvwxyz0123456789";
 export function generateBackupCodes(): string[] {
   const codes: string[] = [];
   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) {
+        // Rejection sampling: 252 is the largest multiple of 36 below 256, so every character is equally likely.
+        if (byte < 252 && code.length < BACKUP_CODE_LENGTH) code += BACKUP_CODE_CHARS[byte % BACKUP_CODE_CHARS.length];
+      }
     }
     codes.push(code);
   }

package/src/types.ts

@@ -28,6 +28,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 {
@@ -45,6 +50,12 @@ 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;
 }
 
 export interface PublicKeyEntry {
@@ -61,6 +72,12 @@ 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 {

package/src/users.ts

@@ -1,4 +1,4 @@
-import { hashPassword, verifyPassword } from "./password.ts";
+import { hashPassword, MAX_PASSWORD_LENGTH, needsRehash, verifyPassword } from "./password.ts";
 import type { User, UserStore } from "./types.ts";
 
 const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
@@ -13,6 +13,8 @@ export async function createUser(
   input: { email: string; name: string; password?: string; isAdmin?: boolean },
 ): Promise<User> {
   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`);
 
@@ -35,12 +37,27 @@ export async function createUser(
   return user;
 }
 
+let dummyHash: Promise<string> | null = null;
+
+/**
+ * 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 async function verifyUserCredentials(store: UserStore, email: string, password: string): Promise<User | null> {
   const user = await store.getUserByEmail(email.toLowerCase());
-  if (!user) return null;
+  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 = { ...user, passwordHash: await hashPassword(password), updatedAt: new Date().toISOString() };
+  await store.saveUser(upgraded);
+  return upgraded;
 }
 
 export async function updateName(store: UserStore, userId: string, name: string): Promise<void> {
@@ -56,6 +73,7 @@ export async function updateName(store: UserStore, userId: string, name: string)
 }
 
 export async function changePassword(store: UserStore, userId: string, newPassword: string): Promise<void> {
+  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`);