@proteinjs/user-server 1.22.1 → 1.22.2

package/src/routes/initiatePasswordReset.ts

@@ -8,6 +8,15 @@ import {
   getDefaultPasswordResetEmailConfigFactory as getDefaultConfigFactory,
 } from '@proteinjs/email-server';
 import { PasswordResetToken } from '../authentication/PasswordResetToken';
+import { ClientAddress } from '../throttle/ClientAddress';
+import { RequestDigests } from '../throttle/RequestDigests';
+import { passwordResetThrottle } from '../throttle/PasswordResetThrottle';
+
+/**
+ * The door's one answer: the same words for an address with an account or without, inside or
+ * past a window, mailed or not — the page shows exactly this sentence.
+ */
+const ONE_ANSWER = { message: 'If that address has an account, a reset link is on its way.' };
 
 /**
  * Route for initiating a password reset process.
@@ -16,6 +25,13 @@ import { PasswordResetToken } from '../authentication/PasswordResetToken';
  * its expiry on the user row — and mails the token to the account as a reset link. The token is
  * withdrawn again when the mail fails to send.
  *
+ * ONE ANSWER: every request with an address is answered `ONE_ANSWER` — BEFORE the address is
+ * looked up — whether it has an account, is throttled (`PasswordResetThrottle`: per client and
+ * per address), is inside the account's five-minute gap, or its mail fails; so neither the
+ * words, the status nor the timing say whether an address has an account. The work runs after
+ * the answer. Every request is one outcome line carrying the account digest and the coarse IP
+ * hash (`RequestDigests`) — never the address.
+ *
  * Requires an implementation of `DefaultPasswordResetEmailConfigFactory` to build the password reset email with.
  *
  * @bodyParam {string} email - The email address of the user requesting a password reset.
@@ -34,16 +50,20 @@ export const initiatePasswordReset: Route = {
       return;
     }
 
+    const digests = new RequestDigests();
+    const fields = { account: digests.account(requestedEmail), ip: digests.coarseIp(new ClientAddress().of(request)) };
+    const window = passwordResetThrottle.admit(fields.ip, fields.account);
+    response.send(ONE_ANSWER);
+    if (window) {
+      logger.warn({ message: `Password reset throttled`, obj: { ...fields, window } });
+      return;
+    }
+
     const email = requestedEmail.toLowerCase();
     const db = getDbAsSystem();
-
-    const genericResponse = { message: 'If an account with that email exists, we have sent a password reset link.' };
-
     const user = await db.get(tables.User, { email });
     if (!user) {
-      logger.info({ message: `Password reset requested for non-existent user`, obj: { email } });
-      // Don't reveal that the user doesn't exist
-      response.send(genericResponse);
+      logger.info({ message: `Password reset requested for non-existent user`, obj: fields });
       return;
     }
 
@@ -51,8 +71,7 @@ export const initiatePasswordReset: Route = {
     const resetToken = new PasswordResetToken();
     const mintedAt = resetToken.mintedAt(user);
     if (mintedAt && moment().diff(mintedAt, 'minutes') < 5) {
-      logger.info({ message: `Password reset requested too soon for user`, obj: { email } });
-      response.send(genericResponse);
+      logger.info({ message: `Password reset requested too soon for user`, obj: fields });
       return;
     }
 
@@ -81,12 +100,11 @@ export const initiatePasswordReset: Route = {
         ...config.options,
       });
 
-      response.send(genericResponse);
+      logger.info({ message: `Password reset link mailed`, obj: fields });
     } catch (error: any) {
-      logger.error({ message: `Failed to send password reset email`, obj: { email }, error });
+      logger.error({ message: `Failed to send password reset email`, obj: fields, error });
       // The link never reached the account: withdraw the token so asking again is not throttled
       await resetToken.revoke(user, passwordResetToken);
-      response.status(500).send({ error: 'Failed to send password reset email. Please try again later.' });
     }
   },
 };

package/src/routes/login.ts

@@ -1,34 +1,65 @@
 import { Route } from '@proteinjs/server-api';
 import { routes } from '@proteinjs/user';
-import { authenticate } from '../authentication/authenticate';
+import { Logger } from '@proteinjs/logger';
+import { authenticate, checkPassword } from '../authentication/authenticate';
 import { establishSession } from '../authentication/establishSession';
 import { AccountDeletion } from '../services/AccountDeletion';
+import { ClientAddress } from '../throttle/ClientAddress';
+import { RequestDigests } from '../throttle/RequestDigests';
+import { SignInThrottle, signInThrottle } from '../throttle/SignInThrottle';
 
+/**
+ * `POST /user/login`. Throttled per client and per account (`SignInThrottle`): a throttled try
+ * is told "Too many attempts. Try again in a few minutes." whether or not the address has an
+ * account, after the same password check a refusal runs (verdict discarded), so neither the
+ * words nor the timing tell. Every refusal is a "Sign-in refused" line and every throttled try
+ * its own "Sign-in throttled" line, carrying the account digest and the coarse IP hash
+ * (`RequestDigests`) — never the address.
+ */
 export const login: Route = {
   path: routes.login.path,
   method: routes.login.method,
   onRequest: async (request: any, response): Promise<void> => {
-    const credentials: { email: string; password: string } = request.body;
-    if (!credentials.email || !credentials.password) {
+    const logger = new Logger({ name: 'login' });
+    const credentials = request.body ?? {};
+    // A field that is not text is a blank one — never something to call methods on.
+    const email: string = typeof credentials.email === 'string' ? credentials.email : '';
+    const password: string = typeof credentials.password === 'string' ? credentials.password : '';
+    const digests = new RequestDigests();
+    const ip = digests.coarseIp(new ClientAddress().of(request));
+    const account = email ? digests.account(email) : undefined;
+    const fields = account ? { account, ip } : { ip };
+
+    // The account is counted only when a password came with the try: a blank one judges nothing.
+    const window = signInThrottle.admit(ip, password ? account : undefined);
+    if (window) {
+      await checkPassword(email, password);
+      logger.warn({ message: 'Sign-in throttled', obj: { ...fields, window } });
+      response.send({ error: SignInThrottle.ANSWER });
+      return;
+    }
+
+    if (!email || !password || !account) {
       const error = `Email and password cannot be blank`;
-      console.error(error);
+      logger.info({ message: 'Sign-in refused', obj: { ...fields, reason: error } });
       response.send({ error });
       return;
     }
 
-    const result = await authenticate(credentials.email, credentials.password);
+    const result = await authenticate(email, password);
     if (result !== true) {
-      console.error(result);
+      logger.info({ message: 'Sign-in refused', obj: { ...fields, reason: result } });
       response.send({ error: result });
       return;
     }
+    signInThrottle.recordSuccess(account, ip);
 
     // Cancel-by-login: a pending-deletion account's successful authentication IS the cancel
     // signal. The restore runs synchronously here, BEFORE request.login, so the first
     // authenticated paint sees the fully restored account (no transient).
     let outcome: Awaited<ReturnType<AccountDeletion['cancelPendingDeletion']>>;
     try {
-      outcome = await new AccountDeletion().cancelPendingDeletion(credentials.email);
+      outcome = await new AccountDeletion().cancelPendingDeletion(email);
     } catch (error) {
       // Security boundary: the login response never carries internal error detail — an
       // attacker probing emails must learn nothing from failure shapes (founder ruling
@@ -45,7 +76,7 @@ export const login: Route = {
       return;
     }
 
-    await establishSession(request, credentials.email);
+    await establishSession(request, email);
     response.send({});
   },
 };

package/src/throttle/ClientAddress.ts

@@ -0,0 +1,47 @@
+/** The request fields the read needs — an express request has all of them. */
+type ClientRequest = {
+  app?: { get?: (setting: string) => unknown };
+  headers?: Record<string, string | string[] | undefined>;
+  socket?: { remoteAddress?: string };
+};
+
+/**
+ * The client's address, as a throttle should key on it.
+ *
+ * Behind Google's external Application Load Balancer the `X-Forwarded-For` header ENDS with the
+ * two entries the balancer appends — `<client-ip>,<load-balancer-ip>` — and everything before
+ * them is whatever the client itself sent. So the client is the second entry from the right:
+ * - never the LAST entry: that is the balancer's own forwarding-rule address, the same for every
+ *   visitor. It is what express's `request.ip` resolves to under the server's `trust proxy 1`
+ *   (one trusted hop: the Google front end that opened the connection), so a throttle keyed on
+ *   `request.ip` there is one bucket for the whole world;
+ * - never the FIRST entry: a client can send its own header, and the balancer keeps it.
+ *
+ * Only when the server trusts a proxy (the deployed shape; `trust proxy` is unset in
+ * development) is the header read at all. A request that did not come through the balancer —
+ * no appended pair: an in-cluster call, a probe — and every request in development key on the
+ * connection's own address.
+ */
+export class ClientAddress {
+  /** How many entries the load balancer appends to the header: the client, then itself. */
+  private static readonly BALANCER_APPENDED_ENTRIES = 2;
+
+  of(request: ClientRequest): string {
+    if (request.app?.get?.('trust proxy')) {
+      const entries = this.forwardedFor(request);
+      if (entries.length >= ClientAddress.BALANCER_APPENDED_ENTRIES) {
+        return entries[entries.length - ClientAddress.BALANCER_APPENDED_ENTRIES];
+      }
+    }
+    return request.socket?.remoteAddress ?? '';
+  }
+
+  private forwardedFor(request: ClientRequest): string[] {
+    const header = request.headers?.['x-forwarded-for'];
+    const value = Array.isArray(header) ? header.join(',') : header ?? '';
+    return value
+      .split(',')
+      .map((entry) => entry.trim())
+      .filter((entry) => entry.length > 0);
+  }
+}

package/src/throttle/PasswordResetThrottle.ts

@@ -0,0 +1,62 @@
+import { SlidingWindow } from './SlidingWindow';
+import { ThrottleWindow } from './SignInThrottle';
+
+/**
+ * The password-reset door's two windows (`POST /user/initiate-password-reset`), keyed by digests
+ * (`RequestDigests`), never by an address. Both count every request, whether or not the address
+ * has an account — a window that only counted real accounts would itself say which addresses
+ * have one. Past either window nothing is looked up, minted or mailed; the door's answer is the
+ * same sentence as always (see the route).
+ *
+ * These sit on top of the account row's own five-minute gap between links, which spans replicas
+ * (it is stored); 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×) — for one address
+ * still at most one mail per five minutes. Friction, not the wall — a shared store is a
+ * separate step.
+ */
+export class PasswordResetThrottle {
+  /**
+   * Per client: 10 requests an hour. Someone asking for their own address again, or a household
+   * asking for a few addresses, passes; a script sweeping addresses stops at ten.
+   */
+  private static readonly CLIENT_LIMIT = 10;
+  private static readonly CLIENT_WINDOW_MS = 60 * 60 * 1000;
+
+  /**
+   * Per address: 3 requests an hour. A person whose mail is slow asks once or twice more; beyond
+   * that it is mail aimed at somebody's inbox.
+   */
+  private static readonly ACCOUNT_LIMIT = 3;
+  private static readonly ACCOUNT_WINDOW_MS = 60 * 60 * 1000;
+
+  private readonly clients: SlidingWindow;
+  private readonly accounts: SlidingWindow;
+
+  constructor(options?: { now?: () => number }) {
+    this.clients = new SlidingWindow({
+      windowMs: PasswordResetThrottle.CLIENT_WINDOW_MS,
+      limit: PasswordResetThrottle.CLIENT_LIMIT,
+      now: options?.now,
+    });
+    this.accounts = new SlidingWindow({
+      windowMs: PasswordResetThrottle.ACCOUNT_WINDOW_MS,
+      limit: PasswordResetThrottle.ACCOUNT_LIMIT,
+      now: options?.now,
+    });
+  }
+
+  /** Count this request and answer which window refuses it, if any. */
+  admit(client: string, account: string): ThrottleWindow | undefined {
+    if (this.clients.hit(client)) {
+      return 'client';
+    }
+    if (this.accounts.hit(account)) {
+      return 'account';
+    }
+    return undefined;
+  }
+}
+
+/** The process-wide windows the reset door shares — they must span requests. */
+export const passwordResetThrottle = new PasswordResetThrottle();

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