@proteinjs/user-server 1.22.1 → 1.22.2

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);
+  });
+});

package/test/setup.js

@@ -1,2 +1,4 @@
 process.env.SPANNER_EMULATOR_HOST = process.env.SPANNER_EMULATOR_HOST || 'localhost:9010';
 process.env.DB_LOG_LEVEL = 'error';
+// The key the throttled doors' digests (RequestDigests) derive from; a process without one refuses to digest.
+process.env.SESSION_SECRET = process.env.SESSION_SECRET || 'user-server-test-secret';