@ultimat3/auth 1.2.0 → 3.0.0

package/src/rate-limit.ts

@@ -4,68 +4,198 @@
 // bypassable. `loginFailed()` lives here so the throttle and the message can never drift apart.
 
 import type { Clock } from '@ultimat3/core';
-import { AuthError, accountLocked } from './errors';
+import { normaliseEmail } from './email';
+import {
+  AuthError,
+  accountLocked,
+  authLimiterNotShared,
+  authLimiterPolicyMismatch,
+} from './errors';
+
+/**
+ * Where a limiter's counters live. A limiter says which it provides; `AuthRateLimitPolicy` says
+ * which the deployment requires, and the two are checked against each other once, at `defineAuth`.
+ */
+export type AuthLimiterScope = 'process' | 'shared';
+
+/**
+ * Hard bound on tracked keys. A key is one identity — `account:<email>` or `ip:<addr>` — so the
+ * natural cardinality is lower than `@ultimat3/http`'s per-route buckets, and so is the cap.
+ */
+export const DEFAULT_MAX_AUTH_LIMIT_KEYS = 10_000;
 
 export interface AuthRateLimitPolicy {
   /** Failures inside `windowMs` before the key is locked. */
   readonly maxAttempts: number;
   readonly windowMs: number;
   readonly lockoutMs: number;
+  /**
+   * The third bucket: failures inside `windowMs` against one TENANT, across every member and
+   * every source address. Per-IP buckets each grant their own quota and per-account buckets
+   * protect one person, so a misconfigured integration spraying one org's logins from 400
+   * addresses is capped by neither — it saturates the shared limiter and every other tenant's
+   * logins slow down behind it.
+   *
+   * A separate number and not `maxAttempts`, because a whole tenant sharing five attempts is a
+   * denial of service against that tenant. Defaults to `maxAttempts * ORG_ATTEMPT_FACTOR`.
+   */
+  readonly orgMaxAttempts?: number | undefined;
+  /** Bound on the in-memory table. Defaults to `DEFAULT_MAX_AUTH_LIMIT_KEYS`. */
+  readonly maxKeys?: number | undefined;
+  /**
+   * What this deployment requires of the limiter. `'shared'` says `maxAttempts` is the whole
+   * fleet's allowance, and a per-process limiter then refuses to build — because N replicas each
+   * counting their own failures let an account survive `maxAttempts × N` guesses, and a lockout
+   * one replica established is invisible to the rest.
+   */
+  readonly scope: AuthLimiterScope;
 }
 
+/** One tenant is worth this many individuals' allowances before it is throttled as a tenant. */
+export const ORG_ATTEMPT_FACTOR = 20;
+
 export const DEFAULT_AUTH_RATE_LIMIT: AuthRateLimitPolicy = Object.freeze({
   maxAttempts: 5,
   windowMs: 15 * 60 * 1000,
   lockoutMs: 15 * 60 * 1000,
+  orgMaxAttempts: 5 * ORG_ATTEMPT_FACTOR,
+  maxKeys: DEFAULT_MAX_AUTH_LIMIT_KEYS,
+  // One process is the only thing this package can promise without being told.
+  scope: 'process',
 });
 
+/**
+ * Async on every member, so a shared implementation can exist at all: a lockout that holds across
+ * replicas is a network round trip, and a synchronous signature has no way to wait for one. The
+ * in-memory limiter below answers immediately — the cost is one already-settled promise per call,
+ * on a path that is about to run a KDF.
+ */
 export interface AuthLimiter {
-  /** Throws `X_ACCOUNT_LOCKED` if the key is inside a lockout. Call before any KDF work. */
-  assertAllowed(key: string): void;
-  recordFailure(key: string): void;
+  /**
+   * The limits this limiter actually enforces, including where it keeps its counters. Stated
+   * rather than assumed, because `defineAuth` compares it against the app's declaration: a
+   * limiter counting to 50 under a policy that says 5 makes `Auth.rateLimit` a number the
+   * operator reads and nothing enforces.
+   */
+  readonly policy: AuthRateLimitPolicy;
+  /** Rejects with `X_ACCOUNT_LOCKED` if the key is inside a lockout. Call before any KDF work. */
+  assertAllowed(key: string): Promise<void>;
+  recordFailure(key: string): Promise<void>;
   /** A success clears the window: a legitimate user is not punished for a typo yesterday. */
-  recordSuccess(key: string): void;
-  lockedUntil(key: string): Date | null;
-  reset(): void;
+  recordSuccess(key: string): Promise<void>;
+  lockedUntil(key: string): Promise<Date | null>;
+  reset(): Promise<void>;
 }
 
-export const accountKey = (email: string): string => `account:${email.trim().toLowerCase()}`;
+/** What `createAuthLimiter` returns: the interface, plus the bound it keeps, observable. */
+export interface MemoryAuthLimiter extends AuthLimiter {
+  readonly size: number;
+}
+
+/**
+ * The SAME normalisation the lookup uses, from the one declaration — a bucket keyed differently
+ * from the row it protects hands a sprayer a fresh attempt budget per spelling of one address.
+ */
+export const accountKey = (email: string): string => `account:${normaliseEmail(email)}`;
 
 export const ipKey = (ip: string): string => `ip:${ip}`;
 
+/**
+ * The tenant bucket's key shape, declared here even though the general noisy-neighbour case lives
+ * in `@ultimat3/http` and `@ultimat3/jobs`: three limiters that spell one tenant three ways cannot
+ * be read together during an incident.
+ */
+export const orgKey = (orgId: string): string => `org:${orgId}`;
+
+/**
+ * The policy the tenant limiter enforces — the same window and lockout, a wider allowance. One
+ * derivation, read by `defineAuth` when it builds the limiter and again when it checks an
+ * injected one, so the two cannot disagree about what was declared.
+ */
+export function orgRateLimit(policy: AuthRateLimitPolicy): AuthRateLimitPolicy {
+  return {
+    ...policy,
+    maxAttempts: policy.orgMaxAttempts ?? policy.maxAttempts * ORG_ATTEMPT_FACTOR,
+  };
+}
+
 interface Bucket {
   failures: number[];
   lockedUntilMs: number;
+  /**
+   * The instant this entry becomes indistinguishable from a missing one: the window has emptied
+   * and any lockout has expired, so it answers exactly as a first-ever attempt does.
+   */
+  forgetAtMs: number;
 }
 
+/** An idle limiter still sweeps this often, so one spray's state does not sit until the next. */
+const SWEEP_EVERY_MS = 60_000;
+
 /**
  * Sliding window over an injected `Clock` — never `Date.now()`, so a lockout test is
  * deterministic instead of a sleep. In-memory per process; a multi-process deployment passes
  * a shared implementation of the same interface.
+ *
+ * Bounded, because half the keys are attacker-chosen: `ipKey` mints one per source address, so
+ * a spray from an IPv6 /64 is a fresh key per attempt and an unbounded map is an OOM. Two rules
+ * keep it flat. An entry whose window has emptied and whose lockout has expired is *forgotten*,
+ * not evicted — it answers exactly as a missing one, so dropping it changes no decision. Only if
+ * that is not enough does the cap evict live state, and then the entries nearest to being
+ * forgotten anyway go first: a locked account is the last key to go, so filling the table is not
+ * a way to buy back attempts against one.
  */
 export function createAuthLimiter(
   clock: Clock,
   policy: AuthRateLimitPolicy = DEFAULT_AUTH_RATE_LIMIT,
-): AuthLimiter {
+): MemoryAuthLimiter {
   const buckets = new Map<string, Bucket>();
+  const maxKeys = Math.max(1, Math.floor(policy.maxKeys ?? DEFAULT_MAX_AUTH_LIMIT_KEYS));
+  const evictTo = Math.max(1, Math.floor(maxKeys * 0.9));
+  let lastSweepMs = Number.NEGATIVE_INFINITY;
 
   const bucketFor = (key: string): Bucket => {
     const existing = buckets.get(key);
     if (existing !== undefined) return existing;
-    const fresh: Bucket = { failures: [], lockedUntilMs: 0 };
+    const fresh: Bucket = { failures: [], lockedUntilMs: 0, forgetAtMs: 0 };
     buckets.set(key, fresh);
     return fresh;
   };
 
+  const sweep = (nowMs: number): void => {
+    lastSweepMs = nowMs;
+    for (const [key, bucket] of buckets) {
+      if (bucket.forgetAtMs <= nowMs) buckets.delete(key);
+    }
+    if (buckets.size <= maxKeys) return;
+    // Batched down to `evictTo` so this sort is paid once per 10% of the cap, not per failure.
+    // A live lockout outranks its deadline: two entries recorded a second apart are otherwise
+    // ordered by recency, which would let a spray evict the account it just locked.
+    const locked = (bucket: Bucket): number => (bucket.lockedUntilMs > nowMs ? 1 : 0);
+    const nearestForgotten = [...buckets.entries()].sort(
+      (a, b) => locked(a[1]) - locked(b[1]) || a[1].forgetAtMs - b[1].forgetAtMs,
+    );
+    for (const [key] of nearestForgotten) {
+      if (buckets.size <= evictTo) break;
+      buckets.delete(key);
+    }
+  };
+
   return {
-    assertAllowed(key) {
+    // The resolved policy, not the argument: `maxKeys` is normalized above, and a limiter that
+    // reported an unresolved bound would be reporting something it does not enforce.
+    policy: { ...policy, maxKeys, scope: 'process' },
+    get size() {
+      return buckets.size;
+    },
+    async assertAllowed(key) {
       const bucket = buckets.get(key);
       if (bucket === undefined) return;
       const nowMs = clock.now().getTime();
       if (bucket.lockedUntilMs <= nowMs) return;
       throw accountLocked(key, Math.ceil((bucket.lockedUntilMs - nowMs) / 1000));
     },
-    recordFailure(key) {
+    async recordFailure(key) {
       const nowMs = clock.now().getTime();
       const bucket = bucketFor(key);
       bucket.failures = bucket.failures.filter((at) => at > nowMs - policy.windowMs);
@@ -73,21 +203,54 @@ export function createAuthLimiter(
       if (bucket.failures.length >= policy.maxAttempts) {
         bucket.lockedUntilMs = nowMs + policy.lockoutMs;
       }
+      // The newest failure leaves the window last, so that is the earliest this entry is free —
+      // unless a lockout outlives it. Recorded here because this is the only growth path.
+      bucket.forgetAtMs = Math.max(bucket.lockedUntilMs, nowMs + policy.windowMs);
+      if (buckets.size > maxKeys || nowMs - lastSweepMs >= SWEEP_EVERY_MS) sweep(nowMs);
     },
-    recordSuccess(key) {
+    async recordSuccess(key) {
       buckets.delete(key);
     },
-    lockedUntil(key) {
+    async lockedUntil(key) {
       const bucket = buckets.get(key);
       if (bucket === undefined || bucket.lockedUntilMs <= clock.now().getTime()) return null;
       return new Date(bucket.lockedUntilMs);
     },
-    reset() {
+    async reset() {
       buckets.clear();
     },
   };
 }
 
+/**
+ * The numbers a limiter is compared on. `maxKeys` is absent deliberately: it bounds one process'
+ * table, so a shared limiter has no opinion on it and comparing it would refuse a correct pairing.
+ */
+const ENFORCED_LIMITS = ['maxAttempts', 'windowMs', 'lockoutMs'] as const;
+
+/**
+ * At `defineAuth`, never at the first login. Two ways the declared policy and the limiter in use
+ * can disagree, and both end the same way — an operator reading `Auth.rateLimit` and believing a
+ * number nothing enforces:
+ *
+ * - a per-node limiter under a `'shared'` declaration is a lockout worth `maxAttempts × replicas`;
+ * - a limiter counting to its own numbers makes every other field of the policy decorative.
+ *
+ * The declaration stays the app's — this package cannot see how many processes the image runs,
+ * and inferring it would be wrong the first time the app scaled — so the framework's job is to
+ * refuse the pairing, not to guess either half of it.
+ */
+export function assertAuthLimiterPolicy(declared: AuthRateLimitPolicy, limiter: AuthLimiter): void {
+  if (declared.scope === 'shared' && limiter.policy.scope !== 'shared') {
+    throw authLimiterNotShared(limiter.policy.scope);
+  }
+  for (const field of ENFORCED_LIMITS) {
+    if (declared[field] !== limiter.policy[field]) {
+      throw authLimiterPolicyMismatch(field, declared[field], limiter.policy[field]);
+    }
+  }
+}
+
 /**
  * The single generic failure. Every credential path — unknown email, wrong password, disabled
  * account, unverified address — throws exactly this object shape, so the rendered error is

package/src/revocation.ts

@@ -0,0 +1,100 @@
+// Single responsibility: taking a credential away, at the three blast radii an incident actually
+// has — one person, one tenant, everything issued before an instant. `deleteOtherSessions` was the
+// only one of the three the seam could express, so "kill every session in this org, now" was a
+// per-user loop over an enumeration the adapter could not do, or a `TRUNCATE` that killed every
+// other tenant with it. Doing nothing meant thirty days, which is the absolute TTL.
+
+import { logger } from '@ultimat3/core';
+import type { AuthUser } from './adapter';
+import type { Auth } from './auth';
+import { authNotImplemented, authWriteFailed } from './errors';
+
+/**
+ * Every revocation is logged before it runs, with the reason the caller gave. An incident review
+ * asks "who killed these sessions and why" and a `delete` with no line answers neither; the reason
+ * is a required argument for the same rule `crossTenant()` requires one.
+ */
+const record = (operation: string, scope: string, reason: string): void => {
+  logger.warn('auth.revocation', { operation, scope, reason });
+};
+
+const unsupported = (method: string, adapterName: string) =>
+  authNotImplemented(
+    `${adapterName}.${method}()`,
+    `implement ${method}() on your AuthAdapter — BuiltinAdapter (Postgres) and MemoryAdapter are the two reference implementations, in packages/auth/src`,
+  );
+
+/** Every session this user holds, their current one included. Returns how many died. */
+export async function revokeUserSessions(
+  auth: Auth,
+  userId: string,
+  reason: string,
+): Promise<number> {
+  const remove = auth.adapter.deleteSessionsForUser?.bind(auth.adapter);
+  if (remove === undefined) throw unsupported('deleteSessionsForUser', auth.adapter.name);
+  record('revokeUserSessions', userId, reason);
+  return await remove(userId);
+}
+
+/**
+ * Every session held by every member of one org. The 03:00 answer to a confirmed credential
+ * compromise in one tenant, and the one thing the seam could not express at all.
+ */
+export async function revokeOrgSessions(
+  auth: Auth,
+  orgId: string,
+  reason: string,
+): Promise<number> {
+  const remove = auth.adapter.deleteSessionsForOrg?.bind(auth.adapter);
+  if (remove === undefined) throw unsupported('deleteSessionsForOrg', auth.adapter.name);
+  record('revokeOrgSessions', orgId, reason);
+  return await remove(orgId);
+}
+
+/**
+ * Everything minted before an instant. The sweep that follows a rotated `SESSION_SECRET` or a
+ * suspected dump: it needs no enumeration of users, so it is the one that works when the list of
+ * affected accounts is exactly what is not known yet.
+ */
+export async function revokeSessionsCreatedBefore(
+  auth: Auth,
+  before: Date,
+  reason: string,
+): Promise<number> {
+  const remove = auth.adapter.deleteSessionsCreatedBefore?.bind(auth.adapter);
+  if (remove === undefined) throw unsupported('deleteSessionsCreatedBefore', auth.adapter.name);
+  record('revokeSessionsCreatedBefore', before.toISOString(), reason);
+  return await remove(before);
+}
+
+export interface DisabledUser {
+  readonly user: AuthUser;
+  readonly sessionsRevoked: number;
+}
+
+/**
+ * `disabledAt` is read by `login`, by `authenticate` and by the OAuth path — and until this
+ * function existed, no code path anywhere ever SET it. Offboarding was an UPDATE somebody typed.
+ *
+ * Stamping the column is not enough on its own: `authenticate` re-reads the user row on every
+ * request, so a disabled account stops working on its next request, but the live session row is
+ * still there and still slides. The sessions go in the same call, in that order — stamp first, so
+ * a request racing the revocation finds the row already disabled.
+ */
+export async function disableUser(
+  auth: Auth,
+  userId: string,
+  reason: string,
+): Promise<DisabledUser> {
+  const user = await auth.adapter.updateUser(userId, { disabledAt: auth.clock.now() });
+  // No row came back: either there is no such user, or the adapter did not return the update.
+  // Both mean the account is not known to be disabled, and reporting success would be a lie.
+  if (user === null) throw authWriteFailed('updateUser', 'x_users');
+  record('disableUser', userId, reason);
+  return { user, sessionsRevoked: await revokeUserSessions(auth, userId, reason) };
+}
+
+/** The inverse. No sessions are restored — a re-enabled account signs in again, deliberately. */
+export async function enableUser(auth: Auth, userId: string): Promise<AuthUser | null> {
+  return await auth.adapter.updateUser(userId, { disabledAt: null });
+}

package/src/session.ts

@@ -12,13 +12,34 @@ import { randomToken, sha256Hex, timingSafeEqual } from './tokens';
 export interface SessionPolicy {
   /** Hard ceiling from creation. Never extended. */
   readonly absoluteTtlMs: number;
-  /** Measured from `lastSeenAt`, refreshed on every verified request. */
+  /** Measured from `lastSeenAt`, refreshed at most once per `idleSlideMs`. */
   readonly idleTtlMs: number;
+  /**
+   * How stale `lastSeenAt` may get before a verified request writes it forward. Absent means
+   * `idleTtlMs / IDLE_SLIDE_DIVISOR`, derived rather than a constant so an app that shortens
+   * `idleTtlMs` does not silently get a slide longer than its own idle window — which would
+   * pin every session to its creation time and expire it on the dot.
+   *
+   * It exists because `verifySession` used to write on EVERY authenticated request: one request
+   * was a SELECT, an `UPDATE … RETURNING *` and a second SELECT, before the app's own first
+   * query. At 20k rps that is 20k writes a second on one hot table, autovacuum falls behind, and
+   * the incident reads as "the database is slow" rather than "authentication is a write path".
+   * The trade is bounded: idle expiry is now precise to within one `idleSlideMs`.
+   */
+  readonly idleSlideMs?: number | undefined;
   readonly cookieName: string;
   /** Mint a new session id whenever roles/scopes change — closes session fixation. */
   readonly rotateOnPrivilegeChange: boolean;
 }
 
+/** 20 → roughly 5% of the idle window, so the write rate falls ~20× and the drift stays small. */
+export const IDLE_SLIDE_DIVISOR = 20;
+
+/** The resolved slide, wherever it is read. One derivation, so the two readers cannot disagree. */
+export function idleSlideMs(policy: SessionPolicy): number {
+  return Math.max(0, policy.idleSlideMs ?? Math.floor(policy.idleTtlMs / IDLE_SLIDE_DIVISOR));
+}
+
 export const DEFAULT_SESSION_POLICY: SessionPolicy = Object.freeze({
   absoluteTtlMs: 30 * 24 * 60 * 60 * 1000,
   idleTtlMs: 7 * 24 * 60 * 60 * 1000,
@@ -134,10 +155,18 @@ export async function verifySession(
     throw sessionExpired(expiry.absoluteExpired ? 'absolute' : 'idle', session.id);
   }
 
+  const ip = observed?.ip ?? session.ip;
+  const userAgent = observed?.userAgent ?? session.userAgent;
+  // The window slides only when it has actually moved. A second request inside the slide issues
+  // no write at all — the read path stays a read — while a changed address or user agent is
+  // written immediately, because that is the row a device list and an incident review read.
+  const stale = now.getTime() - session.lastSeenAt.getTime() >= idleSlideMs(runtime.policy);
+  if (!stale && ip === session.ip && userAgent === session.userAgent) return session;
+
   const touched = await runtime.store.updateSession(session.id, {
-    lastSeenAt: now,
-    ip: observed?.ip ?? session.ip,
-    userAgent: observed?.userAgent ?? session.userAgent,
+    lastSeenAt: stale ? now : session.lastSeenAt,
+    ip,
+    userAgent,
   });
   return touched ?? session;
 }

package/src/tables.ts

@@ -10,11 +10,26 @@ export const X_USERS_TABLE = `create table if not exists x_users (
   org_id                uuid,
   roles                 text[] not null default '{}',
   permissions           text[] not null default '{}',
+  scopes                text[] not null default '{}',
+  external_id           text unique,
   mfa_secret            text,
   recovery_code_hashes  text[] not null default '{}',
   disabled_at           timestamptz,
   created_at            timestamptz not null default now()
-)`;
+);
+create index if not exists x_users_org_id_idx on x_users (org_id)`;
+
+/**
+ * The two columns `x_users` gained in 1.3.0, as the statements an app already running 1.2 runs
+ * once. Both are additive and both have a default, so the migration is not a rewrite and takes no
+ * exclusive lock beyond the catalog update.
+ */
+export const X_USERS_MIGRATION_1_3: readonly string[] = Object.freeze([
+  `alter table x_users add column if not exists scopes text[] not null default '{}'`,
+  'alter table x_users add column if not exists external_id text',
+  'create unique index if not exists x_users_external_id_key on x_users (external_id)',
+  'create index if not exists x_users_org_id_idx on x_users (org_id)',
+]);
 
 // `id` is the public half of the cookie; `token_hash` is sha256 of the secret half.
 export const X_SESSIONS_TABLE = `create table if not exists x_sessions (
@@ -29,7 +44,8 @@ export const X_SESSIONS_TABLE = `create table if not exists x_sessions (
   mfa_satisfied         boolean not null default false
 );
 create index if not exists x_sessions_user_id_idx on x_sessions (user_id);
-create index if not exists x_sessions_absolute_expires_at_idx on x_sessions (absolute_expires_at)`;
+create index if not exists x_sessions_absolute_expires_at_idx on x_sessions (absolute_expires_at);
+create index if not exists x_sessions_created_at_idx on x_sessions (created_at)`;
 
 export const X_ACCOUNTS_TABLE = `create table if not exists x_accounts (
   id                    uuid primary key,

package/src/tokens.ts

@@ -1,7 +1,13 @@
 // Single responsibility: the secret primitives every other file in this package shares —
-// CSPRNG tokens, SHA-256 hashing and a comparison whose duration does not depend on where
-// two strings first differ. Centralised so no call site can quietly reach for `===` on a
-// secret, which leaks the shared prefix length one request at a time.
+// CSPRNG tokens and SHA-256 hashing. Centralised so no call site can quietly reach for `===` on
+// a secret, which leaks the shared prefix length one request at a time. The constant-time
+// comparison itself lives in `@ultimat3/core` (`timingSafeEqual`) — `@ultimat3/storage` needs the
+// exact same one, and re-exporting it here keeps every existing `from '@ultimat3/auth'` import
+// working.
+
+import { timingSafeEqual } from '@ultimat3/core';
+
+export { timingSafeEqual };
 
 const BASE64URL_UNSAFE = /[+/=]/g;
 const BASE64URL_REPLACEMENTS: Readonly<Record<string, string>> = { '+': '-', '/': '_', '=': '' };
@@ -23,6 +29,23 @@ export function randomToken(byteLength = 32): string {
   return base64Url(randomBytes(byteLength));
 }
 
+/**
+ * The inverse of `base64Url`, for the segments of a JWT. Answers `null` rather than throwing
+ * because every caller is reading an attacker-supplied string — a `URIError` or an `InvalidCharacterError`
+ * escaping from here would turn a coded refusal into a 500, the same reason `readCookie` never throws.
+ */
+export function base64UrlBytes(segment: string): Uint8Array<ArrayBuffer> | null {
+  const padded = segment
+    .replaceAll('-', '+')
+    .replaceAll('_', '/')
+    .padEnd(Math.ceil(segment.length / 4) * 4, '=');
+  try {
+    return Uint8Array.from(atob(padded), (char) => char.charCodeAt(0));
+  } catch {
+    return null;
+  }
+}
+
 export function sha256Hex(value: string): string {
   return new Bun.CryptoHasher('sha256').update(value).digest('hex');
 }
@@ -31,20 +54,6 @@ export function sha256Bytes(value: string): Uint8Array {
   return Uint8Array.from(new Bun.CryptoHasher('sha256').update(value).digest());
 }
 
-/**
- * Length is compared first and non-constant-time on purpose: every secret this package
- * compares is a fixed-width hash or token, so the length carries no information, and the
- * XOR accumulator below is what has to be branch-free.
- */
-export function timingSafeEqual(a: string, b: string): boolean {
-  if (a.length !== b.length) return false;
-  let diff = 0;
-  for (let index = 0; index < a.length; index += 1) {
-    diff |= a.charCodeAt(index) ^ b.charCodeAt(index);
-  }
-  return diff === 0;
-}
-
 /** Hash-then-compare. The plaintext never has to be held next to the stored value. */
 export function matchesHash(plaintext: string, storedHash: string): boolean {
   return timingSafeEqual(sha256Hex(plaintext), storedHash);

package/src/verify.ts

@@ -108,19 +108,26 @@ export interface ConsumeVerificationInput {
 }
 
 /**
- * The store consumes the row atomically, so a second redemption finds nothing even if it
- * races the first. The hash comparison happens after, on the row we already own.
+ * The hash goes INTO the consume, it is not compared after one: the store consumes the row only
+ * when the hash is the live row's, atomically, so a second redemption finds nothing even if it
+ * races the first *and* a wrong guess leaves the row live. Comparing afterwards made an
+ * unauthenticated POST with any token at all destroy the victim's emailed link — one request per
+ * address for permanent password-reset denial.
  */
 export async function consumeVerification(
   runtime: VerificationRuntime,
   input: ConsumeVerificationInput,
 ): Promise<AuthVerification> {
-  const record = await runtime.store.takeVerification(input.purpose, input.identifier);
+  const tokenHash = sha256Hex(input.token);
+  const record = await runtime.store.takeVerification(input.purpose, input.identifier, tokenHash);
   if (record === null) throw verificationInvalid(input.purpose);
-  if (runtime.clock.now().getTime() >= record.expiresAt.getTime()) {
+  // Kept for the seam, not for the blessed adapters: `VerificationStore` is implementable by an
+  // app, and one that ignores the third argument would otherwise redeem any token. Constant-time
+  // because this package never compares a secret — or a digest of one — with `===`.
+  if (!timingSafeEqual(tokenHash, record.tokenHash)) {
     throw verificationInvalid(input.purpose);
   }
-  if (!timingSafeEqual(sha256Hex(input.token), record.tokenHash)) {
+  if (runtime.clock.now().getTime() >= record.expiresAt.getTime()) {
     throw verificationInvalid(input.purpose);
   }
   return record;