@proteinjs/user-server 1.22.0 → 1.22.2

package/test/LoginThrottle.integration.test.ts

@@ -0,0 +1,339 @@
+import { createHash } from 'crypto';
+import { getDbAsSystem } from '@proteinjs/db';
+import { tables } from '@proteinjs/user';
+import { login } from '../src/routes/login';
+import { PasswordHasher } from '../src/authentication/PasswordHasher';
+import { createPassportRequest } from './passportSessionHarness';
+import { UserServerTestEnvironment } from './UserServerTestEnvironment';
+import { LogCapture } from './LogCapture';
+
+const testEnv = new UserServerTestEnvironment();
+
+/**
+ * `POST /user/login`, end to end against the Spanner emulator, outcomes only (what the door
+ * answers, whether a session was bound, what the log holds):
+ * - per account: ten refused passwords in the window, then every try — the right password too —
+ *   answers "Too many attempts. Try again in a few minutes." and binds no session; an address
+ *   with no account walks the same steps with the same answers; a success clears the count;
+ * - per client address: fifty tries that are not successes, then the same answer for any account;
+ *   successes never count, however many;
+ * - a blank submission counts toward the address window, never an account's;
+ * - the throttled answer takes as long as a refused password, and a refusal for an address with
+ *   no account takes as long as one for an account (no timing tell either way);
+ * - every refusal is a "Sign-in refused" line and every throttled answer its own "Sign-in
+ *   throttled" line, each carrying the account digest and the coarse IP hash — one digest for
+ *   one address however it was typed — and never the address;
+ * - tries in flight at the same moment cannot all pass the account's window together;
+ * - a refusal for an account still in the legacy password format takes as long as any other;
+ * - a field that is not text is a blank one: the door answers, it never throws.
+ */
+
+const WRONG = 'User name or password incorrect';
+const THROTTLED = 'Too many attempts. Try again in a few minutes.';
+const BLANK = 'Email and password cannot be blank';
+const RIGHT_PASSWORD = 'the right horse battery';
+
+type Attempt = { sent: any; signedInAs?: string };
+
+/** One sign-in attempt from `ip` as the server sees it with no proxy in front (the dev shape). */
+const attempt = async (ip: string, email: string, password: string): Promise<Attempt> => {
+  let sent: any;
+  const response: any = {
+    send: (body: any) => {
+      sent = body;
+    },
+    status: () => response,
+  };
+  const { request } = await createPassportRequest({
+    body: { email, password },
+    headers: {},
+    socket: { remoteAddress: ip },
+    app: { get: () => false },
+  });
+  await login.onRequest(request, response);
+  return { sent, signedInAs: request.session.passport?.user };
+};
+
+const errors = async (count: number, ip: (i: number) => string, email: (i: number) => string, password: string) => {
+  const answers: string[] = [];
+  for (let i = 0; i < count; i++) {
+    answers.push((await attempt(ip(i), email(i), password)).sent?.error);
+  }
+  return answers;
+};
+
+const createAccount = async (email: string) => {
+  const user = await testEnv.createUser({ name: 'Throttle User', email });
+  await getDbAsSystem().update(tables.User, { id: user.id, password: await new PasswordHasher().hash(RIGHT_PASSWORD) });
+  return user;
+};
+
+const elapsedMs = async (run: () => Promise<unknown>): Promise<number> => {
+  const start = process.hrtime.bigint();
+  await run();
+  return Number(process.hrtime.bigint() - start) / 1e6;
+};
+
+const median = (values: number[]) => [...values].sort((a, b) => a - b)[Math.floor(values.length / 2)];
+
+/** Log text without terminal colour codes. */
+const plain = (text: string) => text.replace(new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, 'g'), '');
+
+/** The `field: '<16 hex>'` values on the lines that contain `marker`. */
+const fieldsOn = (log: LogCapture, marker: string, field: string): string[] =>
+  log.lines
+    .map(plain)
+    .filter((line) => line.includes(marker))
+    .map((line) => new RegExp(`${field}: '([0-9a-f]{16})'`).exec(line)?.[1] ?? 'missing');
+
+describe('login route throttle', () => {
+  const originalSecret = process.env.SESSION_SECRET;
+
+  beforeAll(async () => {
+    process.env.SESSION_SECRET = 'login-throttle-test-secret';
+    await testEnv.beforeAll();
+  }, 120000);
+
+  afterAll(async () => {
+    if (originalSecret === undefined) {
+      delete process.env.SESSION_SECRET;
+    } else {
+      process.env.SESSION_SECRET = originalSecret;
+    }
+    await testEnv.afterAll();
+  });
+
+  it('ten wrong passwords are refused as today; the eleventh try — even with the right password — is "Too many attempts…" and no session', async () => {
+    await createAccount('throttle-known@test.local');
+    // Spread over many client addresses, and typed in varying case: the ACCOUNT window catches it.
+    const ip = (i: number) => `198.51.100.${i + 1}`;
+    const email = (i: number) => (i % 2 ? 'Throttle-Known@Test.local' : 'throttle-known@test.local');
+
+    expect(await errors(10, ip, email, 'wrong guess')).toEqual(Array(10).fill(WRONG));
+
+    expect((await attempt('198.51.100.50', 'throttle-known@test.local', 'wrong guess')).sent).toEqual({
+      error: THROTTLED,
+    });
+    const right = await attempt('198.51.100.51', 'throttle-known@test.local', RIGHT_PASSWORD);
+    expect(right.sent).toEqual({ error: THROTTLED });
+    expect(right.signedInAs).toBeUndefined();
+  });
+
+  it('an address with no account walks the same steps with the same answers', async () => {
+    const ip = (i: number) => `198.51.101.${i + 1}`;
+    const email = () => 'throttle-nobody@test.local';
+
+    expect(await errors(10, ip, email, 'wrong guess')).toEqual(Array(10).fill(WRONG));
+    expect((await attempt('198.51.101.50', 'throttle-nobody@test.local', 'wrong guess')).sent).toEqual({
+      error: THROTTLED,
+    });
+  });
+
+  it("a success clears the account's count: after it, ten more wrong tries are refused as usual before the throttle", async () => {
+    await createAccount('throttle-cleared@test.local');
+    const ip = (i: number) => `198.51.102.${i + 1}`;
+    const email = () => 'throttle-cleared@test.local';
+    expect(await errors(9, ip, email, 'wrong guess')).toEqual(Array(9).fill(WRONG));
+
+    const success = await attempt('198.51.102.100', 'throttle-cleared@test.local', RIGHT_PASSWORD);
+    expect(success.sent).toEqual({});
+    expect(success.signedInAs).toBe('throttle-cleared@test.local');
+
+    const again = (i: number) => `198.51.102.${i + 120}`;
+    expect(await errors(10, again, email, 'wrong guess')).toEqual(Array(10).fill(WRONG));
+    expect((await attempt('198.51.102.200', 'throttle-cleared@test.local', 'wrong guess')).sent).toEqual({
+      error: THROTTLED,
+    });
+  });
+
+  it('fifty wrong tries from one client address across fifty accounts, then the same answer for any account; another address is unaffected', async () => {
+    await createAccount('throttle-ip-target@test.local');
+    const ip = () => '203.0.113.20';
+    const email = (i: number) => `throttle-ip-${i}@test.local`;
+    expect(await errors(50, ip, email, 'wrong guess')).toEqual(Array(50).fill(WRONG));
+
+    const right = await attempt('203.0.113.20', 'throttle-ip-target@test.local', RIGHT_PASSWORD);
+    expect(right.sent).toEqual({ error: THROTTLED });
+    expect(right.signedInAs).toBeUndefined();
+
+    const elsewhere = await attempt('203.0.113.21', 'throttle-ip-target@test.local', RIGHT_PASSWORD);
+    expect(elsewhere.sent).toEqual({});
+    expect(elsewhere.signedInAs).toBe('throttle-ip-target@test.local');
+  });
+
+  it('successes never count against the address: thirty sign-ins from one address, then fifty wrong tries are still judged before the window shuts', async () => {
+    await createAccount('throttle-office@test.local');
+    const ip = () => '203.0.113.30';
+    for (let i = 0; i < 30; i++) {
+      const signedIn = await attempt(ip(), 'throttle-office@test.local', RIGHT_PASSWORD);
+      expect(signedIn.sent).toEqual({});
+      expect(signedIn.signedInAs).toBe('throttle-office@test.local');
+    }
+
+    const email = (i: number) => `throttle-office-guess-${i}@test.local`;
+    expect(await errors(50, ip, email, 'wrong guess')).toEqual(Array(50).fill(WRONG));
+    expect((await attempt(ip(), 'throttle-office@test.local', RIGHT_PASSWORD)).sent).toEqual({ error: THROTTLED });
+  });
+
+  it("blank submissions count toward the client address's window, never an account's", async () => {
+    await createAccount('throttle-blank@test.local');
+    // Fifteen blank passwords for one account, from fifteen addresses: the account is not throttled.
+    const ip = (i: number) => `192.0.2.${i + 1}`;
+    expect(await errors(15, ip, () => 'throttle-blank@test.local', '')).toEqual(Array(15).fill(BLANK));
+    expect((await attempt('192.0.2.100', 'throttle-blank@test.local', 'wrong guess')).sent).toEqual({ error: WRONG });
+
+    // Fifty blank submissions from one address: its fifty-first try is throttled.
+    expect(
+      await errors(
+        50,
+        () => '192.0.2.200',
+        () => '',
+        ''
+      )
+    ).toEqual(Array(50).fill(BLANK));
+    expect((await attempt('192.0.2.200', 'throttle-blank@test.local', RIGHT_PASSWORD)).sent).toEqual({
+      error: THROTTLED,
+    });
+  });
+
+  it('no timing tell: the throttled answer takes as long as a refused password, and an address with no account is refused as slowly as one with', async () => {
+    await createAccount('throttle-timing-open@test.local');
+    await createAccount('throttle-timing-shut@test.local');
+    // Push one account over its window (from addresses the samples never use).
+    await errors(
+      10,
+      (i) => `100.64.0.${i + 1}`,
+      () => 'throttle-timing-shut@test.local',
+      'wrong guess'
+    );
+
+    const refused: number[] = [];
+    const unknown: number[] = [];
+    const throttled: number[] = [];
+    // Interleaved, so machine load drifts over all three series alike; seven samples each keeps
+    // the open account under its own window.
+    for (let i = 0; i < 7; i++) {
+      refused.push(
+        await elapsedMs(() => attempt(`100.64.1.${i + 1}`, 'throttle-timing-open@test.local', 'wrong guess'))
+      );
+      unknown.push(
+        await elapsedMs(() => attempt(`100.64.2.${i + 1}`, 'throttle-timing-none@test.local', 'wrong guess'))
+      );
+      throttled.push(
+        await elapsedMs(() => attempt(`100.64.3.${i + 1}`, 'throttle-timing-shut@test.local', 'wrong guess'))
+      );
+    }
+
+    const [r, u, t] = [median(refused), median(unknown), median(throttled)];
+    // A refusal costs one database read and one password verification (argon2, tens of ms).
+    // The tolerance is wide on purpose — a throttled answer or an unknown address that SKIPPED
+    // the verification lands near zero or at the read alone, far outside it.
+    expect(t / r).toBeGreaterThan(0.6);
+    expect(t / r).toBeLessThan(1.6);
+    expect(u / r).toBeGreaterThan(0.6);
+    expect(u / r).toBeLessThan(1.6);
+  });
+
+  it('every refusal and every throttled answer is its own line with the account digest and the coarse IP hash — one digest per address however typed, never the address', async () => {
+    await createAccount('throttle.privacy.person@test.local');
+    const spellings = [
+      'throttle.privacy.person@test.local',
+      'Throttle.Privacy.Person@TEST.local',
+      ' THROTTLE.PRIVACY.PERSON@test.local',
+    ];
+
+    const log = await LogCapture.during(async () => {
+      for (let i = 0; i < 11; i++) {
+        await attempt('198.51.103.7', spellings[i % 3], 'wrong guess');
+      }
+      await attempt('198.51.103.8', 'throttle.privacy.other@test.local', 'wrong guess');
+      await attempt('198.51.103.8', '', '');
+    });
+
+    const refusedAccounts = fieldsOn(log, 'Sign-in refused', 'account');
+    const throttledAccounts = fieldsOn(log, 'Sign-in throttled', 'account');
+    // Ten for the person, one for the other address, one for the blank submission (no account).
+    expect(refusedAccounts).toHaveLength(12);
+    expect(throttledAccounts).toHaveLength(1);
+    const person = refusedAccounts[0];
+    expect(person).toMatch(/^[0-9a-f]{16}$/);
+    expect(refusedAccounts.slice(0, 10)).toEqual(Array(10).fill(person));
+    expect(throttledAccounts).toEqual([person]);
+    expect(refusedAccounts[10]).toMatch(/^[0-9a-f]{16}$/);
+    expect(refusedAccounts[10]).not.toBe(person);
+    expect(refusedAccounts[11]).toBe('missing');
+
+    const ips = [...fieldsOn(log, 'Sign-in refused', 'ip'), ...fieldsOn(log, 'Sign-in throttled', 'ip')];
+    expect(ips).toHaveLength(13);
+    expect(new Set(ips.slice(0, 10)).size).toBe(1);
+    expect(ips[10]).not.toBe(ips[0]);
+    expect(ips[12]).toBe(ips[0]);
+
+    const text = plain(log.text).toLowerCase();
+    for (const fragment of ['throttle.privacy.person', 'throttle.privacy.other', 'throttle.privacy', '198.51.103.']) {
+      expect(text).not.toContain(fragment);
+    }
+  });
+
+  it('thirty wrong passwords for one account fired at once from thirty addresses: at most ten are judged, the rest are throttled', async () => {
+    await createAccount('throttle-burst@test.local');
+
+    const answers = await Promise.all(
+      Array.from({ length: 30 }, (_, i) => attempt(`198.51.104.${i + 1}`, 'throttle-burst@test.local', 'wrong guess'))
+    );
+
+    const judged = answers.filter((answer) => answer.sent?.error === WRONG).length;
+    const throttled = answers.filter((answer) => answer.sent?.error === THROTTLED).length;
+    expect(judged).toBeLessThanOrEqual(10);
+    expect(judged + throttled).toBe(30);
+    expect((await attempt('198.51.104.50', 'throttle-burst@test.local', RIGHT_PASSWORD)).sent).toEqual({
+      error: THROTTLED,
+    });
+  });
+
+  it('a refusal for an account still in the legacy sha256 format takes as long as one in the current format', async () => {
+    await createAccount('throttle-timing-current@test.local');
+    const legacy = await testEnv.createUser({ name: 'Throttle User', email: 'throttle-timing-legacy@test.local' });
+    await getDbAsSystem().update(tables.User, {
+      id: legacy.id,
+      password: createHash('sha256').update(RIGHT_PASSWORD).digest('hex'),
+    });
+
+    const current: number[] = [];
+    const legacyRow: number[] = [];
+    for (let i = 0; i < 7; i++) {
+      current.push(
+        await elapsedMs(() => attempt(`100.64.4.${i + 1}`, 'throttle-timing-current@test.local', 'wrong guess'))
+      );
+      legacyRow.push(
+        await elapsedMs(() => attempt(`100.64.5.${i + 1}`, 'throttle-timing-legacy@test.local', 'wrong guess'))
+      );
+    }
+
+    // A legacy row verifies in microseconds; without the stand-in its refusal lands far under 0.6.
+    const ratio = median(legacyRow) / median(current);
+    expect(ratio).toBeGreaterThan(0.6);
+    expect(ratio).toBeLessThan(1.6);
+  });
+
+  it('a field that is not text is a blank one: the door answers and never throws', async () => {
+    let sent: any;
+    const response: any = {
+      send: (body: any) => {
+        sent = body;
+      },
+      status: () => response,
+    };
+    const { request } = await createPassportRequest({
+      body: { email: 123, password: { not: 'text' } },
+      headers: {},
+      socket: { remoteAddress: '198.51.105.1' },
+      app: { get: () => false },
+    });
+
+    await login.onRequest(request, response);
+
+    expect(sent).toEqual({ error: BLANK });
+    expect(request.session.passport?.user).toBeUndefined();
+  });
+});

package/test/MalformedResetTokens.ts

@@ -0,0 +1,27 @@
+/**
+ * The `token` field of a request that does not carry a well-formed reset token: every type a
+ * parsed body or query string can deliver, and every near-miss of the token's shape. The
+ * near-misses are cut from a LIVE token, so a shape check that loosens (a lost anchor, a wider
+ * length, a case-insensitive class, a missing type check) would be looking up something derived
+ * from a real credential — and the suites that use this table assert that no lookup is built.
+ */
+export class MalformedResetTokens {
+  static readonly CASES: [label: string, tokenField: (liveToken: string) => Record<string, unknown>][] = [
+    ['absent', () => ({})],
+    ['undefined', () => ({ token: undefined })],
+    ['null', () => ({ token: null })],
+    ['empty', () => ({ token: '' })],
+    ['a string of another shape', () => ({ token: 'tok-valid-1' })],
+    ['a number', () => ({ token: 123 })],
+    ['true', () => ({ token: true })],
+    ['an array', () => ({ token: ['a', 'b'] })],
+    ['an array holding the live token', (liveToken) => ({ token: [liveToken] })],
+    ['an object', () => ({ token: { passwordResetToken: null } })],
+    ['63 hex characters of the live token', (liveToken) => ({ token: liveToken.slice(0, 63) })],
+    ['the live token and one more hex character', (liveToken) => ({ token: `${liveToken}a` })],
+    ['the live token in uppercase hex', (liveToken) => ({ token: liveToken.toUpperCase() })],
+    ['the live token and a trailing newline', (liveToken) => ({ token: `${liveToken}\n` })],
+    ['the live token after a leading space', (liveToken) => ({ token: ` ${liveToken}` })],
+    ['64 characters that are not hex', () => ({ token: 'g'.repeat(64) })],
+  ];
+}

package/test/RequestDigests.test.ts

@@ -0,0 +1,81 @@
+import { createHash } from 'crypto';
+import { RequestDigests } from '../src/throttle/RequestDigests';
+
+/**
+ * The two keyed digests the throttled doors key their windows on and write on their log lines:
+ * the account digest (a keyed hash of the lowercased address) and the coarse IP hash. Both are
+ * stable for one key (so an operator can say "one account, one device" across lines, pods and
+ * restarts) and useless without it (never the address, never a plain hash a list of addresses
+ * could reverse).
+ */
+describe('RequestDigests', () => {
+  const digests = new RequestDigests({ secret: 'test-session-secret' });
+
+  it('the account digest is stable for one address whatever its case or surrounding spaces', () => {
+    const digest = digests.account('Ada.Lovelace@Example.com');
+
+    expect(digest).toMatch(/^[0-9a-f]{16}$/);
+    expect(digests.account('ada.lovelace@example.com')).toBe(digest);
+    expect(digests.account('  ADA.LOVELACE@EXAMPLE.COM ')).toBe(digest);
+    expect(digests.account('ada.lovelace@example.org')).not.toBe(digest);
+  });
+
+  it('the account digest is keyed: another key gives another digest, and it is no plain hash of the address', () => {
+    const address = 'ada.lovelace@example.com';
+    const digest = digests.account(address);
+
+    expect(new RequestDigests({ secret: 'another-secret' }).account(address)).not.toBe(digest);
+    expect(createHash('sha256').update(address).digest('hex')).not.toContain(digest);
+    expect(digest).not.toContain('ada');
+  });
+
+  it('the account digest and the coarse IP hash are separate: one value never reads as the other', () => {
+    expect(digests.account('203.0.113.7')).not.toBe(digests.coarseIp('203.0.113.7'));
+  });
+
+  it('the coarse IP hash is stable for one IPv4 address and differs for the next', () => {
+    const hash = digests.coarseIp('203.0.113.7');
+
+    expect(hash).toMatch(/^[0-9a-f]{16}$/);
+    expect(digests.coarseIp('203.0.113.7')).toBe(hash);
+    expect(digests.coarseIp('::ffff:203.0.113.7')).toBe(hash);
+    expect(digests.coarseIp('203.0.113.8')).not.toBe(hash);
+  });
+
+  it('IPv6 is coarsened to its /64 — one device rotates freely inside its own /64', () => {
+    const hash = digests.coarseIp('2001:db8:1:2:aaaa:bbbb:cccc:dddd');
+
+    expect(digests.coarseIp('2001:db8:1:2::1')).toBe(hash);
+    expect(digests.coarseIp('2001:0db8:0001:0002:ffff:0:0:1')).toBe(hash);
+    expect(digests.coarseIp('2001:db8:1:3::1')).not.toBe(hash);
+  });
+
+  it('with no key configured the digests refuse to run — never a plain hash, never a key of their own', () => {
+    const original = process.env.SESSION_SECRET;
+    delete process.env.SESSION_SECRET;
+    try {
+      expect(() => new RequestDigests().account('ada.lovelace@example.com')).toThrow(/SESSION_SECRET/);
+      expect(() => new RequestDigests({ secret: '' }).coarseIp('203.0.113.7')).toThrow(/SESSION_SECRET/);
+    } finally {
+      if (original !== undefined) {
+        process.env.SESSION_SECRET = original;
+      }
+    }
+  });
+
+  it('reads the key the deployment configures (SESSION_SECRET) when none is passed', () => {
+    const original = process.env.SESSION_SECRET;
+    process.env.SESSION_SECRET = 'test-session-secret';
+    try {
+      expect(new RequestDigests().account('ada.lovelace@example.com')).toBe(
+        digests.account('ada.lovelace@example.com')
+      );
+    } finally {
+      if (original === undefined) {
+        delete process.env.SESSION_SECRET;
+      } else {
+        process.env.SESSION_SECRET = original;
+      }
+    }
+  });
+});

package/test/SlidingWindow.test.ts

@@ -0,0 +1,85 @@
+import { SlidingWindow } from '../src/throttle/SlidingWindow';
+
+/**
+ * The per-key sliding window every throttled door shares (the sign-in and reset doors here, the
+ * invite-request door in the consuming app): `hit` records and answers whether the key is over,
+ * `isOver` only reads, `record` only counts, `clear` forgets. Attempts refused as over the window
+ * are not counted, so a key drains exactly one window after its last counted attempt.
+ */
+describe('SlidingWindow', () => {
+  const MINUTE = 60 * 1000;
+  let now = 1_700_000_000_000;
+  const clock = () => now;
+
+  it('admits up to the limit inside the window and refuses the next', () => {
+    const window = new SlidingWindow({ windowMs: 10 * MINUTE, limit: 3, now: clock });
+
+    expect([window.hit('a'), window.hit('a'), window.hit('a')]).toEqual([false, false, false]);
+    expect(window.hit('a')).toBe(true);
+    expect(window.isOver('a')).toBe(true);
+  });
+
+  it('keeps each key in its own window', () => {
+    const window = new SlidingWindow({ windowMs: 10 * MINUTE, limit: 2, now: clock });
+    window.hit('a');
+    window.hit('a');
+
+    expect(window.hit('a')).toBe(true);
+    expect(window.hit('b')).toBe(false);
+  });
+
+  it('drains: an attempt older than the window no longer counts, and refused attempts never counted', () => {
+    const window = new SlidingWindow({ windowMs: 10 * MINUTE, limit: 2, now: clock });
+    window.hit('a');
+    now += 4 * MINUTE;
+    window.hit('a');
+    now += 5 * MINUTE;
+    expect(window.hit('a')).toBe(true); // both counted attempts are still inside the window
+
+    now += 1 * MINUTE + 1; // the first counted attempt left the window; the refused one never counted
+    expect(window.hit('a')).toBe(false);
+    expect(window.hit('a')).toBe(true);
+  });
+
+  it('isOver reads without counting; record counts without answering; clear forgets the key', () => {
+    const window = new SlidingWindow({ windowMs: 10 * MINUTE, limit: 2, now: clock });
+
+    expect(window.isOver('a')).toBe(false);
+    expect(window.isOver('a')).toBe(false);
+    window.record('a');
+    expect(window.isOver('a')).toBe(false);
+    window.record('a');
+    expect(window.isOver('a')).toBe(true);
+
+    window.clear('a');
+    expect(window.isOver('a')).toBe(false);
+  });
+
+  it('forgive uncounts the latest attempt only', () => {
+    const window = new SlidingWindow({ windowMs: 10 * MINUTE, limit: 2, now: clock });
+    window.hit('a');
+    window.hit('a');
+    expect(window.isOver('a')).toBe(true);
+
+    window.forgive('a');
+
+    expect(window.isOver('a')).toBe(false);
+    expect(window.hit('a')).toBe(false);
+    expect(window.hit('a')).toBe(true);
+    window.forgive('b'); // a key never seen: nothing to uncount, nothing thrown
+    expect(window.isOver('b')).toBe(false);
+  });
+
+  it('bounds the keys it tracks: at the bound the oldest-touched key is forgotten first', () => {
+    const window = new SlidingWindow({ windowMs: 10 * MINUTE, limit: 1, maxKeys: 2, now: clock });
+    window.hit('a');
+    window.hit('b');
+    window.hit('a'); // refused, but 'a' is now the most recently touched
+
+    window.hit('c'); // at the bound: 'b' (oldest-touched) is forgotten
+
+    expect(window.isOver('a')).toBe(true);
+    expect(window.isOver('b')).toBe(false);
+    expect(window.isOver('c')).toBe(true);
+  });
+});