cursedbelt-server 1.0.0

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

@@ -0,0 +1,106 @@
+import { describe, expect, test } from 'bun:test';
+import { SignJWT } from 'jose';
+import { signToken, verifyPurposeToken, verifyToken } from './jwt';
+import type { AppJwtPayload } from './types';
+
+const SECRET = 'a-test-secret-at-least-32-chars-long!!';
+
+describe('signToken / verifyToken', () => {
+  test('roundtrips the claims, defaulting getOnly handling to the caller', async () => {
+    const token = await signToken(
+      { userId: 'u1', sessionId: 's1', roles: ['owner'], getOnly: false },
+      SECRET,
+      '15m',
+    );
+    const p = await verifyToken(token, SECRET);
+    expect(p.userId).toBe('u1');
+    expect(p.sessionId).toBe('s1');
+    expect(p.roles).toEqual(['owner']);
+    expect(p.getOnly).toBe(false);
+    // iat/exp are stamped automatically
+    expect(typeof p.iat).toBe('number');
+    expect(typeof p.exp).toBe('number');
+  });
+
+  test('carries getOnly=true', async () => {
+    const token = await signToken(
+      { userId: 'u1', sessionId: 's1', roles: [], getOnly: true },
+      SECRET,
+      '15m',
+    );
+    const p = await verifyToken(token, SECRET);
+    expect(p.getOnly).toBe(true);
+  });
+
+  test('rejects a wrong secret', async () => {
+    const token = await signToken(
+      { userId: 'u1', sessionId: 's1', roles: [], getOnly: false },
+      SECRET,
+      '15m',
+    );
+    await expect(verifyToken(token, `${SECRET}-different`)).rejects.toThrow();
+  });
+
+  test('rejects an expired token', async () => {
+    const token = await signToken(
+      { userId: 'u1', sessionId: 's1', roles: [], getOnly: false },
+      SECRET,
+      '0s',
+    );
+    // exp == iat == now → already expired (jose treats exp as "must be in the future")
+    await new Promise((r) => setTimeout(r, 1100));
+    await expect(verifyToken(token, SECRET)).rejects.toThrow();
+  });
+
+  test('a numeric expiresIn is RELATIVE seconds-from-now (not an absolute epoch)', async () => {
+    const token = await signToken(
+      { userId: 'u1', sessionId: 's1', roles: [], getOnly: false },
+      SECRET,
+      3600,
+    );
+    const p = await verifyToken(token, SECRET);
+    const now = Math.floor(Date.now() / 1000);
+    // exp should be ~1h ahead, NOT 3600 (1970) — the jose bare-number footgun.
+    expect(p.exp).toBeGreaterThan(now + 3000);
+    expect(p.exp).toBeLessThan(now + 4200);
+  });
+
+  test('verifies a standard HS256 token NOT minted via signToken (jsonwebtoken-compat)', async () => {
+    // jose verifies any RFC-7519 HS256 JWT regardless of signer — the whole cutover
+    // guarantee. Mint one without the signToken sugar (no getOnly claim, like an old
+    // pre-getOnly jsonwebtoken token) and confirm verify accepts it + getOnly is absent.
+    const legacy = await new SignJWT({ userId: 'u1', sessionId: 's1', roles: [] })
+      .setProtectedHeader({ alg: 'HS256' })
+      .setIssuedAt()
+      .setExpirationTime('15m')
+      .sign(new TextEncoder().encode(SECRET));
+    const p = await verifyToken<AppJwtPayload>(legacy, SECRET);
+    expect(p.userId).toBe('u1');
+    expect(p.getOnly).toBeUndefined();
+    expect(p.getOnly ?? false).toBe(false);
+  });
+});
+
+describe('verifyPurposeToken', () => {
+  test('accepts a matching purpose, rejects a mismatch', async () => {
+    const token = await signToken(
+      { userId: 'u1', sessionId: 's1', roles: [], getOnly: false, purpose: 'vault-unlock' },
+      SECRET,
+      '15m',
+    );
+    const p = await verifyPurposeToken(token, SECRET, 'vault-unlock');
+    expect(p.userId).toBe('u1');
+    await expect(verifyPurposeToken(token, SECRET, 'pm-unlock')).rejects.toThrow(
+      /purpose mismatch/,
+    );
+  });
+
+  test('rejects a plain access token replayed as a purpose token', async () => {
+    const access = await signToken(
+      { userId: 'u1', sessionId: 's1', roles: [], getOnly: false },
+      SECRET,
+      '15m',
+    );
+    await expect(verifyPurposeToken(access, SECRET, 'vault-unlock')).rejects.toThrow();
+  });
+});

package/src/server/auth/jwt.ts

@@ -0,0 +1,75 @@
+import { type JWTPayload, jwtVerify, SignJWT } from 'jose';
+import type { AppJwtPayload } from './types';
+
+/**
+ * JWT sign/verify on `jose` (Web Crypto HMAC — native on Bun + Node, no native
+ * deps; replaces `jsonwebtoken`). Every token system in the apps — the access
+ * token plus the short-lived vault/private-media/files/yt-oauth unlock tokens —
+ * goes through these, so there is exactly ONE jose integration to reason about.
+ *
+ * jose verifies any standard HS256 JWT regardless of which library signed it, so a
+ * token previously minted by `jsonwebtoken` validates here unchanged — that is the
+ * whole cutover guarantee (no dual-verify shim or `jsonwebtoken` dependency is
+ * carried into this from-scratch toolkit). A pre-`getOnly` token simply has no
+ * `getOnly` claim; the auth middleware reads it as `false`.
+ *
+ * NOTE: Web Crypto HMAC is async, so these are async (jsonwebtoken was sync — every
+ * caller becomes async/await).
+ */
+
+const keyOf = (secret: string): Uint8Array => new TextEncoder().encode(secret);
+
+/**
+ * Normalize jose's expiration input. jose treats a bare **number** as an absolute
+ * UNIX timestamp (seconds) — so `3600` would mean "1970" and expire instantly. We
+ * treat a number as RELATIVE seconds-from-now (the obviously-intended meaning) by
+ * handing jose a `"<n>s"` duration; a string (`'15m'`, `'24h'`) passes through as a
+ * jose duration unchanged.
+ */
+const asDuration = (expiresIn: string | number): string =>
+  typeof expiresIn === 'number' ? `${expiresIn}s` : expiresIn;
+
+/**
+ * Sign an HS256 token. `expiresIn` is a jose duration string (`'15m'`, `'24h'`) or a
+ * number of seconds-from-now. `iat`/`exp` are set automatically — pass everything
+ * else (`userId`, `sessionId`, `roles`, `getOnly`, optional `purpose`).
+ */
+export async function signToken(
+  payload: Omit<AppJwtPayload, 'iat' | 'exp'>,
+  secret: string,
+  expiresIn: string | number,
+): Promise<string> {
+  return new SignJWT(payload as JWTPayload)
+    .setProtectedHeader({ alg: 'HS256' })
+    .setIssuedAt()
+    .setExpirationTime(asDuration(expiresIn))
+    .sign(keyOf(secret));
+}
+
+/** Verify signature + claims and return the decoded payload (throws on bad
+ * signature / expiry / malformed). */
+export async function verifyToken<T extends JWTPayload = AppJwtPayload>(
+  token: string,
+  secret: string,
+): Promise<T> {
+  const { payload } = await jwtVerify(token, keyOf(secret));
+  return payload as T;
+}
+
+/**
+ * Verify a single-purpose token (vault/private-media/files/yt-oauth) AND assert its
+ * `purpose` claim matches — so an access token (or a token for a *different*
+ * feature) can never be replayed as, say, a vault-unlock token. Throws on a bad
+ * signature, expiry, or a purpose mismatch.
+ */
+export async function verifyPurposeToken<T extends AppJwtPayload = AppJwtPayload>(
+  token: string,
+  secret: string,
+  purpose: string,
+): Promise<T> {
+  const payload = await verifyToken<T>(token, secret);
+  if (payload.purpose !== purpose) {
+    throw new Error(`token purpose mismatch: expected '${purpose}', got '${payload.purpose}'`);
+  }
+  return payload;
+}

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

@@ -0,0 +1,213 @@
+import { describe, expect, it } from 'bun:test';
+import { clientKeyOf, createLoginThrottle } from './loginThrottle';
+
+const clock = (start = 1_000_000) => {
+  let t = start;
+  return { now: () => t, advance: (ms: number) => (t += ms) };
+};
+
+describe('clientKeyOf', () => {
+  // The security-relevant case. `$proxy_add_x_forwarded_for` APPENDS the socket
+  // peer, so the LAST entry is what our own nginx observed; the first is whatever
+  // the client typed. Reading the first is the classic version of this bug, and it
+  // would let an attacker mint a fresh per-IP budget on every request.
+  it('reads the LAST forwarded hop, not the client-supplied first one', () => {
+    const req = new Request('https://x.example/api/auth/login', {
+      headers: { 'x-forwarded-for': '1.2.3.4, 203.0.113.9' },
+    });
+    expect(clientKeyOf(req)).toBe('203.0.113.9');
+  });
+
+  it("ignores a spoofed chain's padding entirely", () => {
+    const req = new Request('https://x.example/', {
+      headers: { 'x-forwarded-for': '9.9.9.9, 8.8.8.8, 7.7.7.7, 203.0.113.9' },
+    });
+    expect(clientKeyOf(req)).toBe('203.0.113.9');
+  });
+
+  it('falls back to x-real-ip, then the socket, then ONE shared key', () => {
+    expect(
+      clientKeyOf(new Request('https://x.example/', { headers: { 'x-real-ip': '198.51.100.7' } })),
+    ).toBe('198.51.100.7');
+    expect(clientKeyOf(new Request('https://x.example/'), '192.0.2.5')).toBe('192.0.2.5');
+    // Deliberately NOT a unique key per request — that would silently disable the
+    // per-IP layer for exactly the clients we can least identify.
+    expect(clientKeyOf(new Request('https://x.example/'))).toBe('unknown');
+    expect(clientKeyOf(new Request('https://x.example/'), '  ')).toBe('unknown');
+  });
+});
+
+describe('createLoginThrottle', () => {
+  it('allows the first attempts, then delays with exponential backoff', () => {
+    const c = clock();
+    const t = createLoginThrottle({ now: c.now, threshold: 3, baseDelayMs: 1_000 });
+    expect(t.check('ip')).toEqual({ allowed: true });
+
+    // Three free failures — a real person mistyping a password.
+    for (let i = 0; i < 3; i++) t.recordFailure('ip');
+    expect(t.check('ip')).toEqual({ allowed: true });
+
+    const fourth = t.recordFailure('ip');
+    expect(fourth).toEqual({ allowed: false, scope: 'ip', retryAfterSeconds: 1 });
+
+    c.advance(1_000);
+    expect(t.check('ip')).toEqual({ allowed: true });
+
+    const fifth = t.recordFailure('ip');
+    expect(fifth.allowed).toBe(false);
+    if (!fifth.allowed) expect(fifth.retryAfterSeconds).toBe(2); // doubled
+  });
+
+  it('caps the per-IP delay instead of growing without bound', () => {
+    const c = clock();
+    // globalThreshold high, so this test observes the per-IP cap in isolation —
+    // the global lock would otherwise decide (and rightly so, in production).
+    const t = createLoginThrottle({
+      now: c.now,
+      threshold: 1,
+      baseDelayMs: 1_000,
+      maxDelayMs: 10_000,
+      globalThreshold: 10_000,
+    });
+    for (let i = 0; i < 40; i++) {
+      t.recordFailure('ip');
+      c.advance(60_000); // wait out each lockout so failures keep compounding
+    }
+    const v = t.recordFailure('ip');
+    expect(v.allowed).toBe(false);
+    // Capped, and specifically NOT Infinity/NaN from an overflowing 2**n.
+    if (!v.allowed) expect(v.retryAfterSeconds).toBe(10);
+  });
+
+  it('a quiet window forgives, so an old mistype does not compound', () => {
+    const c = clock();
+    const t = createLoginThrottle({
+      now: c.now,
+      threshold: 2,
+      baseDelayMs: 1_000,
+      windowMs: 60_000,
+    });
+    t.recordFailure('ip');
+    t.recordFailure('ip');
+    c.advance(120_000); // longer than the window
+    // Counter reset: this is failure #1 again, still inside the free allowance.
+    expect(t.recordFailure('ip')).toEqual({ allowed: true });
+  });
+
+  it("one client's failures do not lock a different client out", () => {
+    const c = clock();
+    const t = createLoginThrottle({ now: c.now, threshold: 1, globalThreshold: 100 });
+    for (let i = 0; i < 5; i++) t.recordFailure('noisy');
+    expect(t.check('noisy').allowed).toBe(false);
+    expect(t.check('quiet')).toEqual({ allowed: true });
+  });
+
+  // The layer that actually defends the door: rotating X-Forwarded-For gives an
+  // attacker a fresh per-IP budget every time, and the global counter is what
+  // makes that pointless.
+  it('the global counter catches an attacker rotating their apparent IP', () => {
+    const c = clock();
+    const t = createLoginThrottle({
+      now: c.now,
+      threshold: 5,
+      globalThreshold: 10,
+      baseDelayMs: 1_000,
+    });
+    // Every attempt from a brand-new 'IP', so no per-IP counter ever trips.
+    for (let i = 0; i < 10; i++) t.recordFailure(`ip-${i}`);
+    const next = t.recordFailure('ip-fresh');
+    expect(next.allowed).toBe(false);
+    if (!next.allowed) expect(next.scope).toBe('global');
+  });
+
+  it('the global ceiling stays low, so the owner is never locked out for long', () => {
+    const c = clock();
+    const t = createLoginThrottle({
+      now: c.now,
+      globalThreshold: 1,
+      baseDelayMs: 1_000,
+      globalMaxDelayMs: 60_000,
+    });
+    for (let i = 0; i < 30; i++) {
+      t.recordFailure(`ip-${i}`);
+      c.advance(120_000);
+    }
+    const v = t.recordFailure('ip-final');
+    expect(v.allowed).toBe(false);
+    // A minute, not the 15 the per-IP layer allows — see the module's DoS note.
+    if (!v.allowed) expect(v.retryAfterSeconds).toBeLessThanOrEqual(60);
+  });
+
+  it('a success clears both the key and the global counter', () => {
+    const c = clock();
+    const t = createLoginThrottle({
+      now: c.now,
+      threshold: 1,
+      globalThreshold: 1,
+      baseDelayMs: 5_000,
+    });
+    t.recordFailure('ip');
+    t.recordFailure('ip');
+    expect(t.check('ip').allowed).toBe(false);
+
+    t.recordSuccess('ip');
+    expect(t.check('ip')).toEqual({ allowed: true });
+    // And a different client is not left serving the attacker's sentence.
+    expect(t.check('other')).toEqual({ allowed: true });
+  });
+
+  // An unbounded map keyed by attacker-controlled input is a memory-exhaustion
+  // vector, so the cap has to be a real limit and not a comment.
+  it('bounds the table, and keeps defending after eviction', () => {
+    const c = clock();
+    const t = createLoginThrottle({ now: c.now, maxKeys: 50, globalThreshold: 10, threshold: 1 });
+    for (let i = 0; i < 5_000; i++) t.recordFailure(`ip-${i}`);
+    expect(t.size).toBeLessThanOrEqual(50);
+    // The global counter survived the eviction that dropped 4,950 keys.
+    expect(t.check('ip-brand-new').allowed).toBe(false);
+  });
+
+  // The hole the satellites' copy had, found when the two implementations were
+  // consolidated (2026-08-02). The recommended key is `<email>:<ip>`, and email is
+  // case-insensitive, so an unnormalized key lets an attacker mint a fresh per-account
+  // budget by flipping one letter's case.
+  it('normalizes keys, so varying case cannot evade the per-account budget', () => {
+    const c = clock();
+    const t = createLoginThrottle({ now: c.now, threshold: 1, baseDelayMs: 1_000, globalThreshold: 10_000 });
+    t.recordFailure('Victim@example.com:1.2.3.4');
+    t.recordFailure('victim@EXAMPLE.com:1.2.3.4 ');
+    expect(t.check('VICTIM@example.com:1.2.3.4').allowed).toBe(false);
+    expect(t.size).toBe(1);
+    // A genuinely different account is untouched.
+    expect(t.check('other@example.com:1.2.3.4')).toEqual({ allowed: true });
+  });
+
+  it('reset() clears one key without pardoning the global counter', () => {
+    const c = clock();
+    const t = createLoginThrottle({ now: c.now, threshold: 1, baseDelayMs: 5_000, globalThreshold: 2 });
+    t.recordFailure('ip');
+    t.recordFailure('ip');
+    t.recordFailure('ip');
+    expect(t.check('ip').allowed).toBe(false);
+    t.reset('ip');
+    // Still refused — by the GLOBAL layer, which an admin unlock must not clear.
+    const after = t.check('ip');
+    expect(after.allowed).toBe(false);
+    if (!after.allowed) expect(after.scope).toBe('global');
+  });
+
+  it('forgets stale keys once their window passes', () => {
+    const c = clock();
+    const t = createLoginThrottle({
+      now: c.now,
+      windowMs: 60_000,
+      threshold: 10,
+      globalThreshold: 1000,
+    });
+    for (let i = 0; i < 20; i++) t.recordFailure(`ip-${i}`);
+    expect(t.size).toBe(20);
+    c.advance(120_000);
+    t.recordFailure('someone-new'); // any activity triggers the prune
+    expect(t.size).toBe(1);
+  });
+});

package/src/server/auth/loginThrottle.ts

@@ -0,0 +1,261 @@
+/**
+ * Failed-login backoff for every password door in the fleet — cc's `guard` mixin and
+ * the satellites' own auth stacks alike.
+ *
+ * ── Why this shape (consolidated 2026-08-02) ────────────────────────────────
+ * There were two of these. This file used to hold a fixed-window lockout (N failures
+ * in a window → locked for M minutes); `cursed-satellites` grew a second, better one
+ * in `satellite-kit` because at the time `cursed-core` was treated as read-only from
+ * there. That precedent is repealed, so the EVOLVED implementation lands here and the
+ * satellites import it back. Everything below that reads like over-engineering is a
+ * lesson the fixed-window version had already lost.
+ *
+ * ── The trust model, which is the whole design ───────────────────────────────
+ * A client-supplied `X-Forwarded-For` is forgeable, so per-IP limiting alone is
+ * defeated by rotating the header. Two things follow, and both are deliberate:
+ *
+ * 1. **The IP is read from the LAST hop, not the first.** Behind nginx,
+ *    `proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for` APPENDS the socket
+ *    peer to whatever the client sent. The final entry is therefore the address our
+ *    own proxy observed; the first is whatever the client typed. Reading the first is
+ *    the classic version of this bug.
+ * 2. **The GLOBAL counter is the actual defense.** For a single-principal door
+ *    ("somebody is failing a lot" is enough to slow everybody down) it cannot be
+ *    evaded by rotating a header at all. Per-IP limiting is the courtesy layer that
+ *    keeps one noisy client from being the reason the legitimate user waits.
+ *
+ * ── The lockout-vs-DoS trade, stated plainly ─────────────────────────────────
+ * A global lock means an attacker can make a legitimate user wait. That is why the
+ * global ceiling is 60s while the per-IP ceiling is 15 minutes: a minute of delay per
+ * attempt reduces a distributed brute force to a rounding error against argon2id, and
+ * never locks someone out of their own dashboard for a quarter of an hour. A
+ * successful sign-in clears both counters.
+ *
+ * ── Exponential, not fixed-window ───────────────────────────────────────────
+ * Delay is `base·2^(n-1)` past the threshold rather than a flat lockout, so an honest
+ * typo costs a second and a scripted run costs progressively everything. A quiet
+ * window forgives: someone who mistyped twice last week starts fresh.
+ *
+ * ── Why in-memory, and why bounded ──────────────────────────────────────────
+ * The state is per-process and does not survive a restart. That is acceptable: an
+ * attacker cannot cause a restart, and the only thing that does — a deploy — is
+ * operator-initiated and rare. What is NOT acceptable is an unbounded map keyed by
+ * attacker-controlled input, so the table has a hard key cap and evicts the
+ * least-recently-seen entry when full. The cap is a real limit, not a comment: the
+ * global counter keeps working after eviction, which is precisely the case where it
+ * matters most.
+ *
+ * Pair with the coarse per-IP `createRateLimiter` (`../middleware/rateLimit`); this is
+ * the strict per-identity layer.
+ */
+
+export interface LoginThrottleOptions {
+  /** Injected clock, so backoff is testable without waiting. */
+  now?: () => number;
+  /**
+   * Failures that incur NO delay. Default 5.
+   *
+   * Read it precisely: with `threshold: 5`, failures 1–5 are answered 401 with no
+   * lock, failure 6 is ALSO answered 401 and is the one that arms the first delay, so
+   * attempt 7 is the first refusal. The extra attempt is deliberate — the alternative
+   * (lock on the Nth failure itself) means a 429 whose cause the user cannot
+   * distinguish from a wrong password.
+   */
+  threshold?: number;
+  /** First delay after the threshold, doubling per further failure. Default 1s. */
+  baseDelayMs?: number;
+  /** Ceiling on the per-key delay. Default 15 minutes. */
+  maxDelayMs?: number;
+  /** Free failures, across ALL clients, before everyone is delayed. Default 20. */
+  globalThreshold?: number;
+  /** Ceiling on the global delay — deliberately lower; see the header. Default 60s. */
+  globalMaxDelayMs?: number;
+  /** A key with no failures for this long is forgotten. Default 1 hour. */
+  windowMs?: number;
+  /** Hard cap on tracked keys, so the table cannot be a memory vector. Default 4096. */
+  maxKeys?: number;
+}
+
+export type ThrottleVerdict =
+  | { allowed: true }
+  | { allowed: false; retryAfterSeconds: number; scope: 'ip' | 'global' };
+
+export interface LoginThrottle {
+  /** May this key attempt a login right now? */
+  check(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. */
+  recordSuccess(key: string): void;
+  /** Clear one key without touching the global counter (admin unlock, verified reset). */
+  reset(key: string): void;
+  /** Tracked-key count, for the bounded-growth test. */
+  readonly size: number;
+}
+
+/**
+ * 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.
+ *
+ * The fallback deliberately collapses to ONE key rather than inventing a unique one
+ * per request. A per-request key would make every attempt look like a first attempt
+ * from a new client, i.e. it would silently disable the per-IP layer. Collapsing means
+ * an unidentifiable client shares a budget with every other unidentifiable client,
+ * which is the conservative direction.
+ */
+export function clientKeyOf(req: Request, socketAddress?: string | null): string {
+  const forwarded = req.headers.get('x-forwarded-for');
+  if (forwarded) {
+    const hops = forwarded
+      .split(',')
+      .map((h) => h.trim())
+      .filter((h) => h.length > 0);
+    // LAST, not first — see the header.
+    const observed = hops[hops.length - 1];
+    if (observed) return observed;
+  }
+  const real = req.headers.get('x-real-ip')?.trim();
+  if (real) return real;
+  return socketAddress?.trim() || 'unknown';
+}
+
+/**
+ * The same, from inside a Hono handler.
+ *
+ * Under Bun, Hono's `env` IS the `Server` (the second argument to `app.fetch`), and
+ * `Server.requestIP(req)` is the only source of the real socket peer. Every step is
+ * defensive because that plumbing is the least stable thing here: `env` is `undefined`
+ * under `app.request()` in tests, and a future adapter could pass something else
+ * entirely. A missing address is not an error — `clientKeyOf` falls back to the
+ * headers, which is what production actually uses behind nginx.
+ */
+export function clientKeyOfContext(req: Request, env: unknown): string {
+  let address: string | null = null;
+  const requestIP = (env as { requestIP?: unknown } | null | undefined)?.requestIP;
+  if (typeof requestIP === 'function') {
+    try {
+      address = (requestIP.call(env, req) as { address?: string } | null)?.address ?? null;
+    } catch {
+      address = null;
+    }
+  }
+  return clientKeyOf(req, address);
+}
+
+interface Attempt {
+  failures: number;
+  /** When the current lockout ends; 0 when not locked. */
+  lockedUntil: number;
+  lastSeen: number;
+}
+
+/**
+ * Keys are compared case- and whitespace-insensitively.
+ *
+ * This is NOT cosmetic, and it is the one behavior the satellites' version had lost:
+ * the recommended key is `"<email>:<ip>"`, and an email address is case-insensitive,
+ * so without this `Victim@example.com` and `victim@example.com` are separate budgets
+ * and an attacker evades the per-account layer by varying the case of a letter. The
+ * global counter still caught that, but only after 20 free guesses per attacker.
+ */
+const normalizeKey = (key: string): string => key.trim().toLowerCase();
+
+export function createLoginThrottle(options: LoginThrottleOptions = {}): LoginThrottle {
+  const now = options.now ?? Date.now;
+  const threshold = options.threshold ?? 5;
+  const baseDelayMs = options.baseDelayMs ?? 1_000;
+  const maxDelayMs = options.maxDelayMs ?? 15 * 60_000;
+  const globalThreshold = options.globalThreshold ?? 20;
+  const globalMaxDelayMs = options.globalMaxDelayMs ?? 60_000;
+  const windowMs = options.windowMs ?? 60 * 60_000;
+  const maxKeys = options.maxKeys ?? 4096;
+
+  const attempts = new Map<string, Attempt>();
+  const global: Attempt = { failures: 0, lockedUntil: 0, lastSeen: 0 };
+
+  /** Delay for the nth failure past a threshold: base·2^(n-1), capped. */
+  const delayFor = (failures: number, limit: number, cap: number): number => {
+    const past = failures - limit;
+    if (past <= 0) return 0;
+    // `Math.min` before the shift would still overflow for large `past`; clamp the
+    // exponent instead so a client that keeps hammering cannot reach Infinity.
+    const exponent = Math.min(past - 1, 32);
+    return Math.min(baseDelayMs * 2 ** exponent, cap);
+  };
+
+  /** Drop stale entries; then, if still over the cap, evict least-recently-seen. */
+  const prune = (nowMs: number): void => {
+    for (const [key, entry] of attempts) {
+      if (nowMs - entry.lastSeen > windowMs && entry.lockedUntil <= nowMs) attempts.delete(key);
+    }
+    if (attempts.size <= maxKeys) return;
+    const byAge = [...attempts.entries()].sort((a, b) => a[1].lastSeen - b[1].lastSeen);
+    for (const [key] of byAge.slice(0, attempts.size - maxKeys)) attempts.delete(key);
+  };
+
+  const verdict = (rawKey: string, nowMs: number): ThrottleVerdict => {
+    const key = normalizeKey(rawKey);
+    // Global first: it is the layer that cannot be evaded by rotating a header, so it
+    // should also be the one that decides.
+    if (global.lockedUntil > nowMs) {
+      return {
+        allowed: false,
+        scope: 'global',
+        retryAfterSeconds: Math.ceil((global.lockedUntil - nowMs) / 1000),
+      };
+    }
+    const entry = attempts.get(key);
+    if (entry && entry.lockedUntil > nowMs) {
+      return {
+        allowed: false,
+        scope: 'ip',
+        retryAfterSeconds: Math.ceil((entry.lockedUntil - nowMs) / 1000),
+      };
+    }
+    return { allowed: true };
+  };
+
+  return {
+    check(key) {
+      return verdict(key, now());
+    },
+
+    recordFailure(rawKey) {
+      const key = normalizeKey(rawKey);
+      const nowMs = now();
+      const entry = attempts.get(key) ?? { failures: 0, lockedUntil: 0, lastSeen: nowMs };
+      // A quiet window forgives: someone who mistyped twice last week starts fresh,
+      // while a run of failures keeps compounding.
+      if (nowMs - entry.lastSeen > windowMs) entry.failures = 0;
+      entry.failures += 1;
+      entry.lastSeen = nowMs;
+      entry.lockedUntil = nowMs + delayFor(entry.failures, threshold, maxDelayMs);
+      attempts.set(key, entry);
+
+      if (nowMs - global.lastSeen > windowMs) global.failures = 0;
+      global.failures += 1;
+      global.lastSeen = nowMs;
+      global.lockedUntil = nowMs + delayFor(global.failures, globalThreshold, globalMaxDelayMs);
+
+      prune(nowMs);
+      return verdict(key, nowMs);
+    },
+
+    recordSuccess(rawKey) {
+      attempts.delete(normalizeKey(rawKey));
+      // The user got in, so whatever the global counter was reacting to is over.
+      // Leaving it armed would punish the legitimate user for the attack.
+      global.failures = 0;
+      global.lockedUntil = 0;
+      global.lastSeen = now();
+    },
+
+    reset(rawKey) {
+      attempts.delete(normalizeKey(rawKey));
+    },
+
+    get size() {
+      return attempts.size;
+    },
+  };
+}