cursedbelt-server 4.24.0 → 4.25.0

package/src/server/auth/loginThrottle.spec.ts

@@ -211,3 +211,85 @@ describe('createLoginThrottle', () => {
     expect(t.size).toBe(1);
   });
 });
+
+describe('attempt — check and charge in one step', () => {
+  it('🔴 a burst of concurrent attempts is admitted only up to the threshold', async () => {
+    const c = clock();
+    const t = createLoginThrottle({ now: c.now, threshold: 3, globalThreshold: 1000 });
+    // Every attempt is admitted BEFORE any verify finishes — the shape of K concurrent guesses
+    // each waiting on argon2id. With check-then-recordFailure all ten would pass one stale count.
+    const verdicts = Array.from({ length: 10 }, () => t.attempt('ip'));
+    // Threshold 3 → charges 1–3 free, the 4th arms the delay but is itself admitted (the same
+    // "one extra" the threshold option documents), the 5th onward are refused.
+    expect(verdicts.filter((v) => v.allowed).length).toBe(4);
+    expect(verdicts[4]).toEqual({ allowed: false, scope: 'ip', retryAfterSeconds: 1 });
+  });
+
+  it('a success after an attempt clears the charge', () => {
+    const c = clock();
+    const t = createLoginThrottle({ now: c.now, threshold: 1, globalThreshold: 1 });
+    expect(t.attempt('ip').allowed).toBe(true);
+    t.recordSuccess('ip');
+    expect(t.attempt('ip').allowed).toBe(true);
+    t.recordSuccess('ip');
+    expect(t.check('ip')).toEqual({ allowed: true });
+    expect(t.size).toBe(0);
+  });
+
+  it('a refused attempt is not itself charged', () => {
+    const c = clock();
+    const t = createLoginThrottle({ now: c.now, threshold: 0, baseDelayMs: 1_000, globalThreshold: 1000 });
+    expect(t.attempt('ip').allowed).toBe(true); // charged: failure 1 → 1 s delay
+    for (let i = 0; i < 5; i++) expect(t.attempt('ip').allowed).toBe(false);
+    c.advance(1_000);
+    // Still failure 1's delay that just elapsed — not 2^5 s from five refused attempts.
+    expect(t.attempt('ip').allowed).toBe(true);
+  });
+});
+
+describe('snapshot / restore', () => {
+  it('a throttle restored from a snapshot enforces what the original had seen', () => {
+    const c = clock();
+    const first = createLoginThrottle({ now: c.now, threshold: 2, globalThreshold: 1000 });
+    for (let i = 0; i < 3; i++) first.recordFailure('Attacker');
+    expect(first.check('attacker').allowed).toBe(false);
+    const snap = JSON.parse(JSON.stringify(first.snapshot()));
+    const second = createLoginThrottle({ now: c.now, threshold: 2, globalThreshold: 1000, restore: snap });
+    expect(second.check('attacker').allowed).toBe(false);
+    expect(second.check('someone-else').allowed).toBe(true);
+    // The count carries on rather than restarting.
+    c.advance(10_000);
+    const next = second.recordFailure('attacker');
+    expect(next.allowed).toBe(false);
+    if (!next.allowed) expect(next.retryAfterSeconds).toBe(2);
+  });
+
+  it('keeps the global counter, and only the most recent keys under a limit', () => {
+    const c = clock();
+    const t = createLoginThrottle({ now: c.now, globalThreshold: 3 });
+    for (let i = 0; i < 5; i++) {
+      c.advance(1);
+      t.recordFailure(`ip-${i}`);
+    }
+    const snap = t.snapshot(2);
+    expect(snap.entries.map(([k]) => k)).toEqual(['ip-4', 'ip-3']);
+    expect(snap.global.failures).toBe(5);
+    const restored = createLoginThrottle({ now: c.now, globalThreshold: 3, restore: snap });
+    const v = restored.check('a-new-ip');
+    expect(v.allowed).toBe(false);
+    if (!v.allowed) expect(v.scope).toBe('global');
+  });
+
+  it('an unreadable snapshot starts empty rather than throwing', () => {
+    const bad = [
+      { v: 2, global: { failures: 99, lockedUntil: 9e15, lastSeen: 0 }, entries: [] },
+      { v: 1, global: { failures: 'x' }, entries: [['k', { failures: null }], 'junk'] },
+      { v: 1, global: null, entries: null },
+    ];
+    for (const restore of bad) {
+      const t = createLoginThrottle({ restore: restore as never });
+      expect(t.check('k')).toEqual({ allowed: true });
+      expect(t.size).toBe(0);
+    }
+  });
+});

package/src/server/auth/loginThrottle.ts

@@ -45,6 +45,25 @@
  * global counter keeps working after eviction, which is precisely the case where it
  * matters most.
  *
+ * 🔴 **"Per-process" is one ISOLATE on a Cloudflare Worker, and that is not a process.**
+ * Cloudflare runs an isolate per colo (often several), discards them without warning and
+ * builds a fresh one on every deploy, so a module-scope throttle there is global to one
+ * isolate only: a guesser reaching N isolates gets N × `globalThreshold` free failures,
+ * and one built per REQUEST has no memory at all (patterns' Worker until 2026-09-23). A
+ * Worker keeps its ledger in a Durable Object instead — `./loginThrottleDurable.ts`
+ * (`cursedbelt-server/login-throttle/durable`), which serves THIS algorithm from one
+ * named object and persists it, so every isolate and every colo meets the same counts.
+ *
+ * ── `attempt`, not `check` then `recordFailure` ─────────────────────────────
+ * `check` → verify → `recordFailure` has a gap exactly as long as the verify: argon2id,
+ * hundreds of ms. Every request that arrives inside it reads the same count, so K
+ * concurrent guesses are all admitted and the counter learns of them afterwards — the
+ * throttle limits guesses per BURST, and the burst is as wide as the attacker's
+ * concurrency. `attempt` closes the gap: it checks and, when admitted, charges a
+ * failure in the same synchronous step, so the (threshold+1)th concurrent request is
+ * refused. A success then clears the charge (`recordSuccess`), and a failure needs no
+ * second call. The Durable Object serves `attempt` as one operation for the same reason.
+ *
  * Pair with the coarse per-IP `createRateLimiter` (`../middleware/rateLimit`); this is
  * the strict per-identity layer.
  */
@@ -74,6 +93,28 @@ export interface LoginThrottleOptions {
   windowMs?: number;
   /** Hard cap on tracked keys, so the table cannot be a memory vector. Default 4096. */
   maxKeys?: number;
+  /**
+   * Start from a persisted {@link LoginThrottle.snapshot} rather than empty — how a Durable
+   * Object (`./loginThrottleDurable.ts`) survives its own eviction. An unreadable snapshot
+   * (wrong version, wrong shape) starts EMPTY for the keys and is ignored, never thrown on.
+   */
+  restore?: LoginThrottleSnapshot | null;
+}
+
+/** One key's (or the global counter's) ledger line — the unit {@link LoginThrottleSnapshot} holds. */
+export interface LoginThrottleEntry {
+  failures: number;
+  /** When the current lockout ends; 0 when not locked. */
+  lockedUntil: number;
+  lastSeen: number;
+}
+
+/** A throttle's whole state as plain data, for a store that outlives the throttle. */
+export interface LoginThrottleSnapshot {
+  v: 1;
+  global: LoginThrottleEntry;
+  /** Most recently seen first, `[normalizedKey, entry]`. */
+  entries: Array<[string, LoginThrottleEntry]>;
 }
 
 export type ThrottleVerdict =
@@ -83,6 +124,13 @@ export type ThrottleVerdict =
 export interface LoginThrottle {
   /** May this key attempt a login right now? */
   check(key: string): ThrottleVerdict;
+  /**
+   * `check`, and when allowed, charge a failure in the SAME step — so concurrent attempts
+   * cannot all be admitted against one count. Follow an allowed attempt with
+   * `recordSuccess` when the credential was right; a wrong one needs no further call.
+   * See the header's `attempt` section.
+   */
+  attempt(key: string): ThrottleVerdict;
   /** Record a failed attempt. Returns the verdict the NEXT attempt would get. */
   recordFailure(key: string): ThrottleVerdict;
   /** Record a success — clears this key and the global counter. */
@@ -91,8 +139,26 @@ export interface LoginThrottle {
   reset(key: string): void;
   /** Tracked-key count, for the bounded-growth test. */
   readonly size: number;
+  /** The state as plain data — the `limit` most recently seen keys (default all) and the global counter. */
+  snapshot(limit?: number): LoginThrottleSnapshot;
 }
 
+/**
+ * The same ledger across a round trip — `createRemoteLoginThrottle` in
+ * `./loginThrottleDurable.ts`. A door that awaits every call takes either shape:
+ * {@link LoginThrottleLike}.
+ */
+export interface AsyncLoginThrottle {
+  check(key: string): Promise<ThrottleVerdict>;
+  attempt(key: string): Promise<ThrottleVerdict>;
+  recordFailure(key: string): Promise<ThrottleVerdict>;
+  recordSuccess(key: string): Promise<void>;
+  reset(key: string): Promise<void>;
+}
+
+/** What a sign-in handler should accept: the in-process throttle or the Durable Object's. */
+export type LoginThrottleLike = LoginThrottle | AsyncLoginThrottle;
+
 /**
  * The client address to key on — the LAST `X-Forwarded-For` entry (what our proxy
  * saw), falling back to `X-Real-IP`, the socket peer, and finally a shared constant.
@@ -142,12 +208,16 @@ export function clientKeyOfContext(req: Request, env: unknown): string {
   return clientKeyOf(req, address);
 }
 
-interface Attempt {
-  failures: number;
-  /** When the current lockout ends; 0 when not locked. */
-  lockedUntil: number;
-  lastSeen: number;
-}
+type Attempt = LoginThrottleEntry;
+
+/** A persisted entry is trusted only as far as its three numbers are finite. */
+const readEntry = (raw: unknown): Attempt | null => {
+  const e = raw as Partial<Attempt> | null | undefined;
+  if (!e || typeof e !== 'object') return null;
+  const { failures, lockedUntil, lastSeen } = e;
+  if (![failures, lockedUntil, lastSeen].every((n) => typeof n === 'number' && Number.isFinite(n))) return null;
+  return { failures: failures as number, lockedUntil: lockedUntil as number, lastSeen: lastSeen as number };
+};
 
 /**
  * Keys are compared case- and whitespace-insensitively.
@@ -172,6 +242,18 @@ export function createLoginThrottle(options: LoginThrottleOptions = {}): LoginTh
 
   const attempts = new Map<string, Attempt>();
   const global: Attempt = { failures: 0, lockedUntil: 0, lastSeen: 0 };
+  const restored = options.restore;
+  if (restored && restored.v === 1) {
+    const g = readEntry(restored.global);
+    if (g) Object.assign(global, g);
+    // Oldest first, so the Map's insertion order matches what it would have been live.
+    const entries = Array.isArray(restored.entries) ? [...restored.entries].reverse() : [];
+    for (const pair of entries) {
+      if (!Array.isArray(pair) || typeof pair[0] !== 'string') continue;
+      const entry = readEntry(pair[1]);
+      if (entry) attempts.set(normalizeKey(pair[0]), entry);
+    }
+  }
 
   /** Delay for the nth failure past a threshold: base·2^(n-1), capped. */
   const delayFor = (failures: number, limit: number, cap: number): number => {
@@ -215,11 +297,19 @@ export function createLoginThrottle(options: LoginThrottleOptions = {}): LoginTh
     return { allowed: true };
   };
 
-  return {
+  const api: LoginThrottle = {
     check(key) {
       return verdict(key, now());
     },
 
+    attempt(key) {
+      const gate = verdict(key, now());
+      if (!gate.allowed) return gate;
+      // Charged BEFORE the caller verifies anything — see the header's `attempt` section.
+      api.recordFailure(key);
+      return gate;
+    },
+
     recordFailure(rawKey) {
       const key = normalizeKey(rawKey);
       const nowMs = now();
@@ -257,5 +347,16 @@ export function createLoginThrottle(options: LoginThrottleOptions = {}): LoginTh
     get size() {
       return attempts.size;
     },
+
+    snapshot(limit) {
+      const byRecency = [...attempts.entries()].sort((a, b) => b[1].lastSeen - a[1].lastSeen);
+      const kept = limit === undefined ? byRecency : byRecency.slice(0, Math.max(0, limit));
+      return {
+        v: 1,
+        global: { ...global },
+        entries: kept.map(([key, entry]) => [key, { ...entry }]),
+      };
+    },
   };
+  return api;
 }

package/src/server/auth/loginThrottleDurable.spec.ts

@@ -0,0 +1,165 @@
+import { describe, expect, it } from 'bun:test';
+import { createLoginThrottle } from './loginThrottle.js';
+import {
+  createRemoteLoginThrottle,
+  type DurableNamespaceLike,
+  type DurableStorageLike,
+  LOGIN_THROTTLE_OPERATIONS,
+  LoginThrottleObject,
+} from './loginThrottleDurable.js';
+
+/** A Durable Object's storage, as a Map that survives the object — which is what storage is for. */
+const memoryStorage = (): DurableStorageLike & { data: Map<string, unknown> } => {
+  const data = new Map<string, unknown>();
+  return {
+    data,
+    // Structured clone, as the runtime does — an object that kept a live reference would pass
+    // a persistence test without persisting anything.
+    get: async <T>(key: string) => (data.has(key) ? (structuredClone(data.get(key)) as T) : undefined),
+    put: async (key, value) => {
+      data.set(key, structuredClone(value));
+    },
+  };
+};
+
+const clock = (start = 5_000_000) => {
+  let t = start;
+  return { now: () => t, advance: (ms: number) => (t += ms) };
+};
+
+/** A namespace whose ONE object can be swapped — `evict()` is the platform recycling it. */
+const namespaceOver = (storage: DurableStorageLike, now: () => number) => {
+  let object = new LoginThrottleObject({ storage }, {}, { now, threshold: 2, globalThreshold: 4 });
+  const ns: DurableNamespaceLike & { evict(): void; calls: number } = {
+    calls: 0,
+    idFromName: (name) => name,
+    get: () => ({
+      fetch: (request: Request) => {
+        ns.calls += 1;
+        return object.fetch(request);
+      },
+    }),
+    evict() {
+      object = new LoginThrottleObject({ storage }, {}, { now, threshold: 2, globalThreshold: 4 });
+    },
+  };
+  return ns;
+};
+
+describe('LoginThrottleObject + createRemoteLoginThrottle', () => {
+  it('🔴 two isolates share ONE ledger — failures in one lock the other', async () => {
+    const c = clock();
+    const ns = namespaceOver(memoryStorage(), c.now);
+    // Two isolates: each builds its own client (per request, as a Worker does) over one binding.
+    const isolateA = createRemoteLoginThrottle(ns, { ledger: 'owner' });
+    const isolateB = createRemoteLoginThrottle(ns, { ledger: 'owner' });
+    for (let i = 0; i < 3; i++) await isolateA.recordFailure('203.0.113.9');
+    const seenByB = await isolateB.check('203.0.113.9');
+    expect(seenByB.allowed).toBe(false);
+    // …and the per-isolate version of the same thing does not, which is the bug this replaces.
+    const perIsolateA = createLoginThrottle({ now: c.now, threshold: 2 });
+    const perIsolateB = createLoginThrottle({ now: c.now, threshold: 2 });
+    for (let i = 0; i < 3; i++) perIsolateA.recordFailure('203.0.113.9');
+    expect(perIsolateB.check('203.0.113.9').allowed).toBe(true);
+  });
+
+  it('🔴 the ledger survives the object being evicted and rebuilt over the same storage', async () => {
+    const c = clock();
+    const storage = memoryStorage();
+    const ns = namespaceOver(storage, c.now);
+    const t = createRemoteLoginThrottle(ns, { ledger: 'owner' });
+    for (let i = 0; i < 3; i++) await t.recordFailure('192.0.2.44');
+    ns.evict();
+    expect((await t.check('192.0.2.44')).allowed).toBe(false);
+    // The global counter too: a fifth failure from anywhere arms the global delay (threshold 4).
+    await t.recordFailure('198.51.100.1');
+    ns.evict();
+    await t.recordFailure('198.51.100.2');
+    ns.evict();
+    const v = await t.check('a-fresh-address');
+    expect(v.allowed).toBe(false);
+    if (!v.allowed) expect(v.scope).toBe('global');
+  });
+
+  it('lockout after N failures, and a success clears it everywhere', async () => {
+    const c = clock();
+    const ns = namespaceOver(memoryStorage(), c.now);
+    const t = createRemoteLoginThrottle(ns, { ledger: 'owner' });
+    // threshold 2: attempts 1–3 admitted (the third arms), the fourth refused.
+    const verdicts = [];
+    for (let i = 0; i < 4; i++) verdicts.push(await t.attempt('ip'));
+    expect(verdicts.map((v) => v.allowed)).toEqual([true, true, true, false]);
+    c.advance(60_000);
+    expect((await t.attempt('ip')).allowed).toBe(true);
+    await t.recordSuccess('ip');
+    expect(await createRemoteLoginThrottle(ns, { ledger: 'owner' }).check('ip')).toEqual({ allowed: true });
+  });
+
+  it('🔴 a concurrent burst is admitted only up to the threshold, not all at once', async () => {
+    const c = clock();
+    const ns = namespaceOver(memoryStorage(), c.now);
+    const verdicts = await Promise.all(
+      Array.from({ length: 12 }, () => createRemoteLoginThrottle(ns, { ledger: 'owner' }).attempt('burst')),
+    );
+    expect(verdicts.filter((v) => v.allowed).length).toBe(3);
+  });
+
+  it('ledgers are independent — the probe never spends the owner', async () => {
+    const c = clock();
+    const ns = namespaceOver(memoryStorage(), c.now);
+    const probe = createRemoteLoginThrottle(ns, { ledger: 'probe' });
+    const owner = createRemoteLoginThrottle(ns, { ledger: 'owner' });
+    for (let i = 0; i < 20; i++) await probe.recordFailure('home');
+    expect((await probe.check('home')).allowed).toBe(false);
+    expect(await owner.attempt('home')).toEqual({ allowed: true });
+  });
+
+  it('an unreachable object degrades to the fallback, which was mirrored all along', async () => {
+    const c = clock();
+    const storage = memoryStorage();
+    const ns = namespaceOver(storage, c.now);
+    const fallback = createLoginThrottle({ now: c.now, threshold: 2, globalThreshold: 4 });
+    const lines: string[] = [];
+    const t = createRemoteLoginThrottle(ns, { ledger: 'owner', fallback, onError: (l) => lines.push(l) });
+    for (let i = 0; i < 3; i++) await t.attempt('ip');
+    // The object goes away. The fallback has seen all three charges, so it refuses the fourth
+    // instead of starting from zero.
+    const broken: DurableNamespaceLike = {
+      idFromName: (n) => n,
+      get: () => ({ fetch: async () => new Response('overloaded', { status: 503 }) }),
+    };
+    const degraded = createRemoteLoginThrottle(broken, { ledger: 'owner', fallback, onError: (l) => lines.push(l) });
+    expect((await degraded.attempt('ip')).allowed).toBe(false);
+    expect(lines.length).toBe(1);
+    expect(lines[0]).toContain('503');
+    // Without a fallback the error is the caller's, never a silent allow.
+    await expect(createRemoteLoginThrottle(broken).check('ip')).rejects.toThrow('503');
+  });
+
+  it('answers exactly LOGIN_THROTTLE_OPERATIONS, and refuses malformed input', async () => {
+    const object = new LoginThrottleObject({ storage: memoryStorage() });
+    const post = (path: string, body: unknown) =>
+      object.fetch(new Request(`https://x.invalid${path}`, { method: 'POST', body: JSON.stringify(body) }));
+    for (const [, path] of LOGIN_THROTTLE_OPERATIONS) {
+      expect([path, (await post(path, { ledger: 'owner', key: 'k' })).status]).toEqual([path, 200]);
+    }
+    expect((await post('/throttle/nope', { ledger: 'owner', key: 'k' })).status).toBe(404);
+    expect((await post('/throttle/check', { ledger: 'Not A Slug', key: 'k' })).status).toBe(400);
+    expect((await post('/throttle/check', { ledger: 'owner', key: 'x'.repeat(321) })).status).toBe(400);
+    expect((await post('/throttle/check', { ledger: 'owner' })).status).toBe(400);
+    expect((await object.fetch(new Request('https://x.invalid/throttle/check'))).status).toBe(405);
+  });
+
+  it('persists a bounded ledger, however many keys it has seen', async () => {
+    const storage = memoryStorage();
+    const object = new LoginThrottleObject({ storage }, {}, { globalThreshold: 1e9, maxKeys: 5000 });
+    const t = createRemoteLoginThrottle(
+      { idFromName: (n) => n, get: () => ({ fetch: (r) => object.fetch(r) }) },
+      { ledger: 'owner' },
+    );
+    for (let i = 0; i < 1100; i++) await t.recordFailure(`10.0.${Math.floor(i / 250)}.${i % 250}`);
+    const saved = storage.data.get('ledger:owner') as { entries: unknown[] };
+    expect(saved.entries.length).toBe(1024);
+    expect(JSON.stringify(saved).length).toBeLessThan(128 * 1024);
+  });
+});