@proteinjs/user-server 1.22.0 → 1.22.2

package/src/throttle/RequestDigests.ts

@@ -0,0 +1,97 @@
+import { createHmac } from 'crypto';
+
+/**
+ * The two keyed digests the throttled doors key their windows on and write on their log lines,
+ * in place of what they stand for:
+ * - `account(email)` — the ACCOUNT DIGEST: a keyed hash of the trimmed, lowercased address.
+ *   One address gives one digest however it was typed, on every replica and across restarts, so
+ *   an operator can say "one account" across lines without the address.
+ * - `coarseIp(address)` — the COARSE IP HASH: a keyed hash of the client address at the grain
+ *   one device holds (an IPv4 address; an IPv6 /64, inside which a device rotates freely), so
+ *   an operator can say "one device" and a throttle cannot be dodged by rotating inside a /64.
+ *
+ * Keyed with HMAC-SHA256 under a key DERIVED from the session secret — the one secret every
+ * replica already shares, the same keying the invite-request door's IP hash uses; derived per
+ * purpose, never used raw, so neither digest weakens the session's own use of it, and the two
+ * digests never collide in meaning. Truncated to 64 bits: enough to tell accounts and devices
+ * apart, useless to anyone without the key — never the address, never a plain hash a list of
+ * addresses could reverse.
+ *
+ * The key is the deployment's `SESSION_SECRET` unless the constructor is given one (the tests).
+ * Without either the digests refuse to run: a server with no `SESSION_SECRET` has no sessions
+ * either (the session middleware refuses to start), so nothing ever runs unkeyed — never a plain
+ * hash a list of addresses could reverse, never a per-process key that quietly stops matching
+ * across replicas.
+ */
+export class RequestDigests {
+  /** Hex characters kept from the HMAC: 64 bits. */
+  private static readonly DIGEST_HEX_LENGTH = 16;
+
+  constructor(private readonly options?: { secret?: string }) {}
+
+  /** The account digest of an address, however it was typed. */
+  account(email: string): string {
+    return this.digest('account-digest', email.trim().toLowerCase());
+  }
+
+  /** The coarse IP hash of a client address (see `ClientAddress`). */
+  coarseIp(address: string): string {
+    return this.digest('coarse-ip', this.coarsen(address.trim().toLowerCase()));
+  }
+
+  private digest(purpose: string, value: string): string {
+    return createHmac('sha256', `${purpose}:${this.secret()}`)
+      .update(value)
+      .digest('hex')
+      .slice(0, RequestDigests.DIGEST_HEX_LENGTH);
+  }
+
+  private secret(): string {
+    const configured = this.options?.secret ?? process.env.SESSION_SECRET;
+    if (!configured) {
+      throw new Error(
+        'SESSION_SECRET is not set: the account digest and the coarse IP hash need the key every replica shares'
+      );
+    }
+    return configured;
+  }
+
+  /** An IPv4 address as itself (an IPv4-mapped IPv6 address as its IPv4); an IPv6 address as its /64. */
+  private coarsen(address: string): string {
+    const mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/.exec(address);
+    if (mapped) {
+      return mapped[1];
+    }
+    if (!address.includes(':')) {
+      return address;
+    }
+    const groups = this.ipv6Groups(address.split('%')[0]);
+    return groups ? `${groups.slice(0, 4).join(':')}::/64` : address;
+  }
+
+  /** The first four groups (the /64) of an IPv6 address, each without leading zeros; undefined when it does not parse. */
+  private ipv6Groups(address: string): string[] | undefined {
+    const halves = address.split('::');
+    if (halves.length > 2) {
+      return undefined;
+    }
+    const parts = (half: string | undefined) => (half ? half.split(':') : []);
+    const head = parts(halves[0]);
+    const tail = parts(halves[1]);
+    // A trailing dotted IPv4 part stands for two groups.
+    const groupsIn = (list: string[]) => list.reduce((count, part) => count + (part.includes('.') ? 2 : 1), 0);
+    const missing = 8 - groupsIn(head) - groupsIn(tail);
+    if (missing < 0 || (halves.length === 1 && missing !== 0)) {
+      return undefined;
+    }
+    const zeros: string[] = [];
+    for (let i = 0; i < missing; i++) {
+      zeros.push('0');
+    }
+    const groups = head.concat(zeros, tail).slice(0, 4);
+    if (groups.some((group) => !/^[0-9a-f]{1,4}$/.test(group))) {
+      return undefined;
+    }
+    return groups.map((group) => parseInt(group, 16).toString(16));
+  }
+}

package/src/throttle/SignInThrottle.ts

@@ -0,0 +1,98 @@
+import { SlidingWindow } from './SlidingWindow';
+
+/** Which window refused a try: the client's (its coarse IP hash) or the account's (its digest). */
+export type ThrottleWindow = 'client' | 'account';
+
+/**
+ * The sign-in door's two windows (`POST /user/login`), keyed by digests (`RequestDigests`),
+ * never by an address:
+ * - per CLIENT: every try that is not a success counts — wrong passwords, blank ones too, the
+ *   client made them — so one device cannot sweep many accounts; a successful sign-in never
+ *   counts (it is forgiven the moment it succeeds), so the people behind one shared address
+ *   signing in do not spend the window on each other;
+ * - per ACCOUNT: every try that carries a password counts (a blank submission judges no
+ *   password, so it never counts), so guesses spread over many devices still stop; a success
+ *   clears the account's count. A try is counted as it ARRIVES, before it is judged: tries in
+ *   flight at the same moment cannot all pass the window together.
+ *
+ * A throttled try is told `ANSWER` whichever window refused it and whether or not the address
+ * has an account, in the same time a refused password takes (the door runs the same password
+ * check and discards its verdict).
+ *
+ * The windows are in process memory (`SlidingWindow`): per replica. A deployment of three
+ * replicas behind a load balancer (up to ten under load) keeps three sets of windows, so its
+ * effective ceiling is ~3× the numbers below (up to ~10×). Friction, not the wall — a shared
+ * store is a separate step.
+ */
+export class SignInThrottle {
+  /** What a throttled try is told — in plain words, the same for every address, known or not. */
+  static readonly ANSWER = 'Too many attempts. Try again in a few minutes.';
+
+  /**
+   * Per client: 50 tries that are not successes in 10 minutes (the founder's number, 2026-09-23).
+   * Successes never count, so an office or a school behind one address signing in at nine o'clock
+   * never spends this window on itself — only its mistypes do, and fifty wrong or blank tries in
+   * ten minutes is beyond any human population behind one address; a guessing script from one
+   * device is held to ~300 tries an hour per replica.
+   */
+  private static readonly CLIENT_LIMIT = 50;
+  private static readonly CLIENT_WINDOW_MS = 10 * 60 * 1000;
+
+  /**
+   * Per account: 10 tries in 15 minutes (a success clears them, so only wrong ones ever add up).
+   * Someone who has forgotten a password tries a handful and asks for a reset link; ten wrong in
+   * a quarter of an hour is guessing, and counting per account holds however many devices the
+   * guesses come from. "A few minutes" in the answer is honest: the oldest try leaves the window
+   * within 15.
+   */
+  private static readonly ACCOUNT_LIMIT = 10;
+  private static readonly ACCOUNT_WINDOW_MS = 15 * 60 * 1000;
+
+  private readonly clients: SlidingWindow;
+  private readonly accounts: SlidingWindow;
+
+  constructor(options?: { now?: () => number }) {
+    this.clients = new SlidingWindow({
+      windowMs: SignInThrottle.CLIENT_WINDOW_MS,
+      limit: SignInThrottle.CLIENT_LIMIT,
+      now: options?.now,
+    });
+    this.accounts = new SlidingWindow({
+      windowMs: SignInThrottle.ACCOUNT_WINDOW_MS,
+      limit: SignInThrottle.ACCOUNT_LIMIT,
+      now: options?.now,
+    });
+  }
+
+  /**
+   * Count this try against the client and against the account, and answer which window refuses
+   * it, if any. `account` is the digest of the address tried, given only when a password came
+   * with it (a blank submission judges no password, so it never counts toward an account). The
+   * count is taken here, before the try is judged, so tries in flight at once cannot all pass
+   * the window; a success clears it (`recordSuccess`).
+   */
+  admit(client: string, account?: string): ThrottleWindow | undefined {
+    if (this.clients.hit(client)) {
+      return 'client';
+    }
+    if (account !== undefined && this.accounts.hit(account)) {
+      return 'account';
+    }
+    return undefined;
+  }
+
+  /**
+   * The account proved itself: its window opens again. When it was a sign-in try from `client`
+   * (rather than a reset link redeemed), that try is forgiven — a success never counts against
+   * the device.
+   */
+  recordSuccess(account: string, client?: string): void {
+    this.accounts.clear(account);
+    if (client !== undefined) {
+      this.clients.forgive(client);
+    }
+  }
+}
+
+/** The process-wide windows the sign-in door shares — they must span requests. */
+export const signInThrottle = new SignInThrottle();

package/src/throttle/SlidingWindow.ts

@@ -0,0 +1,90 @@
+/**
+ * A per-key sliding window: how many attempts a key made in the last `windowMs`, against a
+ * `limit`. The one window every throttled door shares — the sign-in and password-reset doors in
+ * this package, and any consumer door throttling per client (lifted from the invite-request
+ * door's per-IP throttle, which it replaces).
+ *
+ * Held in process memory only, which is what makes it cheap and what bounds it:
+ * - PER PROCESS. Each replica keeps its own windows, so behind a load balancer spreading a
+ *   client over N replicas the effective ceiling is ~N× the limit; a restart forgets them.
+ *   A throttle built on this is friction, not the wall. A shared store is a separate step.
+ * - BOUNDED. At most `maxKeys` keys are tracked; at the bound the oldest-touched key is
+ *   forgotten first, so a flood of fresh keys degrades the friction before it grows memory.
+ *
+ * Keys are whatever the caller passes — callers pass digests (see `RequestDigests`), never raw
+ * addresses, so nothing identifying is held here either.
+ */
+export class SlidingWindow {
+  private static readonly DEFAULT_MAX_KEYS = 10_000;
+
+  private readonly windowMs: number;
+  private readonly limit: number;
+  private readonly maxKeys: number;
+  private readonly now: () => number;
+  /** key → the counted attempt times inside the window (pruned on touch), in touch order. */
+  private readonly attempts = new Map<string, number[]>();
+
+  constructor(options: { windowMs: number; limit: number; maxKeys?: number; now?: () => number }) {
+    this.windowMs = options.windowMs;
+    this.limit = options.limit;
+    this.maxKeys = options.maxKeys ?? SlidingWindow.DEFAULT_MAX_KEYS;
+    this.now = options.now ?? Date.now;
+  }
+
+  /**
+   * Record an attempt for `key` and answer whether it was over the window — `true` means refuse.
+   * A refused attempt is not counted, so a key drains one window after its last counted attempt.
+   */
+  hit(key: string): boolean {
+    if (this.isOver(key)) {
+      this.touch(key, this.inWindow(key));
+      return true;
+    }
+    this.record(key);
+    return false;
+  }
+
+  /** Whether `key` has used up its window, without counting anything. */
+  isOver(key: string): boolean {
+    return this.inWindow(key).length >= this.limit;
+  }
+
+  /** Count an attempt for `key` without answering (for doors that judge the attempt first). */
+  record(key: string): void {
+    const attempts = this.inWindow(key);
+    attempts.push(this.now());
+    this.touch(key, attempts);
+  }
+
+  /** Forget `key`'s attempts. */
+  clear(key: string): void {
+    this.attempts.delete(key);
+  }
+
+  /**
+   * Uncount `key`'s latest attempt (for doors that count a try as it arrives and learn afterwards
+   * that it should never have counted — a sign-in that succeeded).
+   */
+  forgive(key: string): void {
+    const attempts = this.inWindow(key);
+    attempts.pop();
+    this.touch(key, attempts);
+  }
+
+  private inWindow(key: string): number[] {
+    const cutoff = this.now() - this.windowMs;
+    return (this.attempts.get(key) ?? []).filter((time) => time > cutoff);
+  }
+
+  /** Store `key`'s attempts as the most recently touched, evicting the oldest-touched key at the bound. */
+  private touch(key: string, attempts: number[]): void {
+    if (!this.attempts.has(key) && this.attempts.size >= this.maxKeys) {
+      const oldest = this.attempts.keys().next().value;
+      if (oldest !== undefined) {
+        this.attempts.delete(oldest);
+      }
+    }
+    this.attempts.delete(key);
+    this.attempts.set(key, attempts);
+  }
+}

package/test/ClientAddress.test.ts

@@ -0,0 +1,54 @@
+import { ClientAddress } from '../src/throttle/ClientAddress';
+
+/**
+ * Which address a throttle keys on. Behind Google's external Application Load Balancer the
+ * header ends `<client-ip>,<load-balancer-ip>` — the balancer appends both, and anything before
+ * them is whatever the client itself sent. So the client is the SECOND entry from the right:
+ * never the last (the balancer's own address, the same for every visitor — a throttle keyed on
+ * it is one bucket for the whole world) and never the first (client-supplied, rotatable at will).
+ */
+describe('ClientAddress', () => {
+  const behindTheBalancer = (forwardedFor: string | undefined, socketAddress = '35.191.0.10') => ({
+    app: { get: (setting: string) => (setting === 'trust proxy' ? 1 : undefined) },
+    headers: forwardedFor === undefined ? {} : { 'x-forwarded-for': forwardedFor },
+    socket: { remoteAddress: socketAddress },
+    // What express's own `request.ip` resolves to under `trust proxy 1`: the header's last entry.
+    ip: forwardedFor?.split(',').pop()?.trim() ?? socketAddress,
+  });
+
+  it("reads the client the balancer appended, not the balancer's own address", () => {
+    const request = behindTheBalancer('198.51.100.23, 34.120.1.1');
+
+    expect(new ClientAddress().of(request)).toBe('198.51.100.23');
+    expect(request.ip).toBe('34.120.1.1');
+  });
+
+  it('ignores whatever the client put in the header itself', () => {
+    const spoofed = behindTheBalancer('203.0.113.99, 10.0.0.1, 198.51.100.23, 34.120.1.1');
+
+    expect(new ClientAddress().of(spoofed)).toBe('198.51.100.23');
+  });
+
+  it('reads IPv6 clients the same way', () => {
+    expect(new ClientAddress().of(behindTheBalancer('2001:db8:1:2:3:4:5:6,34.120.1.1'))).toBe('2001:db8:1:2:3:4:5:6');
+  });
+
+  it('a request that did not come through the balancer (no appended pair) keys on its own connection', () => {
+    expect(new ClientAddress().of(behindTheBalancer(undefined, '10.8.0.7'))).toBe('10.8.0.7');
+    expect(new ClientAddress().of(behindTheBalancer('10.8.0.9', '10.8.0.7'))).toBe('10.8.0.7');
+  });
+
+  it('with no proxy trusted (development) the connection is the client, and a forwarded header is ignored', () => {
+    const direct = {
+      app: { get: () => false },
+      headers: { 'x-forwarded-for': '203.0.113.99, 198.51.100.23' },
+      socket: { remoteAddress: '::1' },
+    };
+
+    expect(new ClientAddress().of(direct)).toBe('::1');
+  });
+
+  it('a request with no connection details at all reads as the empty address', () => {
+    expect(new ClientAddress().of({})).toBe('');
+  });
+});

package/test/DbTraffic.ts

@@ -0,0 +1,43 @@
+import { Db, DbDriver } from '@proteinjs/db';
+
+/**
+ * What reached the database while a run executed — the outcome a "refused before any lookup"
+ * claim rests on. A response code cannot prove it: a value that is wrongly let through still
+ * matches no row and still answers 400, so the proof is that nothing was built and nothing ran.
+ * - `lookups`: the filter of every read built through the package's `Db` — every `query`, which
+ *   is also what a `get` is (the first row of one);
+ * - `writes`: how many writes were built through it (`insert`, `update`, `delete`);
+ * - `statements`: how many statements the driver ran, whoever built them.
+ */
+export class DbTraffic {
+  private constructor(
+    readonly lookups: unknown[],
+    readonly writes: number,
+    readonly statements: number
+  ) {}
+
+  /** The traffic of a run that never touched the database: `expect(traffic).toEqual(DbTraffic.NONE)`. */
+  static readonly NONE = { lookups: [], writes: 0, statements: 0 };
+
+  /** Runs `run` and answers what it resolved to beside the database traffic it caused. */
+  static async during<T>(driver: DbDriver, run: () => Promise<T>): Promise<{ result: T; traffic: DbTraffic }> {
+    const reads = jest.spyOn(Db.prototype, 'query');
+    const writes = [
+      jest.spyOn(Db.prototype, 'insert'),
+      jest.spyOn(Db.prototype, 'update'),
+      jest.spyOn(Db.prototype, 'delete'),
+    ];
+    const statements = [jest.spyOn(driver, 'runQuery'), jest.spyOn(driver, 'runDml')];
+    try {
+      const result = await run();
+      const lookups = reads.mock.calls.map(([_table, filter]) => filter);
+      return { result, traffic: new DbTraffic(lookups, DbTraffic.callCount(writes), DbTraffic.callCount(statements)) };
+    } finally {
+      [reads, ...writes, ...statements].forEach((spy) => spy.mockRestore());
+    }
+  }
+
+  private static callCount(spies: { mock: { calls: unknown[] } }[]): number {
+    return spies.reduce((count, spy) => count + spy.mock.calls.length, 0);
+  }
+}

package/test/DevLoginBootstrapAdmin.test.ts

@@ -6,10 +6,9 @@ import { UserServerTestEnvironment } from './UserServerTestEnvironment';
 const testEnv = new UserServerTestEnvironment();
 
 /**
- * `DEV_BOOTSTRAP_ADMIN_EMAIL` — the first-admin door INSIDE `/dev/login` (n3xa plans/DEV_ESTATES.md
- * D3, founder-ruled 2026-09-04). A dev estate on a fresh real database has no privileged account
- * to grant from, and the no-raw-DB rule forbids the emulator-era seed scripts there — so the ONE
- * sanctioned account door mints break-glass, once:
+ * `DEV_BOOTSTRAP_ADMIN_EMAIL` — the first-admin door INSIDE `/dev/login`. A development server on
+ * a fresh real database has no privileged account to grant from, and a no-raw-database-write rule
+ * forbids seed scripts there — so the ONE sanctioned account door mints break-glass, once:
  *  - behind the door's existing two gates (DEVELOPMENT AND DEV_AUTO_LOGIN_EMAIL): closed = 404 as
  *    before, and the variable changes nothing;
  *  - only while NO account carries 'admin' (the same membership test the app's admin checks make);

package/test/DevLoginStaleCookieFirstHit.test.ts

@@ -28,7 +28,7 @@ const testEnv = new UserServerTestEnvironment();
  * cookies the response set, and the follow-up MUST read as authenticated on the FIRST pass.
  */
 
-const SESSION_COOKIE_NAME = 'n3xa.sid.9876'; // dev cookie-name shape: n3xa.sid.${SERVER_PORT}
+const SESSION_COOKIE_NAME = 'app.sid.9876'; // a consumer's dev cookie-name shape: <app>.sid.${SERVER_PORT}
 const SESSION_SECRET = 'dev-first-hit-test-secret';
 const ENV_EMAIL = 'dev@test.local';
 /** Store commit latency. Generous so a pre-0.6 runtime (write racing the redirect) loses the