@proteinjs/user-server 1.22.1 → 1.22.3

package/test/InitiatePasswordReset.test.ts

@@ -7,6 +7,9 @@ import { tables } from '@proteinjs/user';
 import { initiatePasswordReset } from '../src/routes/initiatePasswordReset';
 import { executePasswordReset } from '../src/routes/executePasswordReset';
 import { PasswordHasher } from '../src/authentication/PasswordHasher';
+import { PasswordResetToken } from '../src/authentication/PasswordResetToken';
+import { login } from '../src/routes/login';
+import { createPassportRequest } from './passportSessionHarness';
 import { UserServerTestEnvironment } from './UserServerTestEnvironment';
 import { LogCapture } from './LogCapture';
 
@@ -22,12 +25,30 @@ const testEnv = new UserServerTestEnvironment();
  * - an unknown address gets the same response and no mail;
  * - a request with no body, or no usable email: 400, no mail, nothing changes;
  * - no minted token, no leading characters of one and no full digest reach the log — on the
- *   mailed path, the throttled repeat, the unknown address, or the failed send's error line.
+ *   mailed path, the throttled repeat, the unknown address, or the failed send's error line;
+ * - ONE answer, whatever happens behind it: an account mailed, no account, too soon, over a
+ *   window, a failed send — the same 200 and the same sentence, sent before the account is
+ *   looked up (so its timing says nothing either);
+ * - per address three requests an hour and per client address ten: past either, nothing is mailed;
+ * - every request is one outcome line carrying the account digest and the coarse IP hash, never
+ *   the address.
  */
 
 type RouteOutcome = { status: number; body?: any };
 
-const invoke = async (route: typeof initiatePasswordReset, request: Record<string, unknown>): Promise<RouteOutcome> => {
+/** Each request arrives from its own client address unless the test names one (the dev shape: no proxy). */
+let nextAddress = 0;
+const fromAddress = (ip?: string) => ({
+  headers: {},
+  socket: { remoteAddress: ip ?? `10.20.${Math.floor(nextAddress / 250)}.${(nextAddress++ % 250) + 1}` },
+  app: { get: () => false },
+});
+
+const invoke = async (
+  route: typeof initiatePasswordReset,
+  request: Record<string, unknown>,
+  events?: string[]
+): Promise<RouteOutcome> => {
   const outcome: RouteOutcome = { status: 200 };
   const response = {
     status(code: number) {
@@ -35,14 +56,15 @@ const invoke = async (route: typeof initiatePasswordReset, request: Record<strin
       return this;
     },
     send(body?: unknown) {
+      events?.push('answered');
       outcome.body = body;
     },
   };
-  await route.onRequest(request as never, response as never);
+  await route.onRequest({ ...fromAddress(), ...request } as never, response as never);
   return outcome;
 };
 
-const GENERIC = { message: 'If an account with that email exists, we have sent a password reset link.' };
+const GENERIC = { message: 'If that address has an account, a reset link is on its way.' };
 
 const sha256Hex = (value: string) => createHash('sha256').update(value).digest('hex');
 
@@ -71,6 +93,25 @@ const mailedToken = (): string => tokenInLink(MailSink.get().list(1)[0]?.text);
 
 type SourceRepositoryInternals = { objectCache: Record<string, unknown[]> };
 
+/** Moves an account's last mint back past the five-minute gap, so only the windows can refuse. */
+const ageLastMint = async (email: string) => {
+  const armed = await userRow(email);
+  await getDbAsSystem().update(tables.User, {
+    id: armed.id,
+    passwordResetTokenExpiration: moment().add(54, 'minutes'),
+  });
+};
+
+/** 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>'` value on each line containing `marker` ('missing' where absent). */
+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('initiatePasswordReset route', () => {
   const originalTransport = process.env.EMAIL_TRANSPORT;
 
@@ -144,7 +185,7 @@ describe('initiatePasswordReset route', () => {
     try {
       const failed = await invoke(initiatePasswordReset, { body: { email: 'initiate-send-fails@test.local' } });
 
-      expect(failed.status).toBe(500);
+      expect(failed).toEqual({ status: 200, body: GENERIC });
       const withdrawn = await userRow('initiate-send-fails@test.local');
       expect(withdrawn.passwordResetToken).toBeNull();
       expect(withdrawn.passwordResetTokenExpiration).toBeNull();
@@ -209,7 +250,7 @@ describe('initiatePasswordReset route', () => {
       });
       try {
         const failed = await invoke(initiatePasswordReset, { body: { email: 'initiate-log-send-fails@test.local' } });
-        expect(failed.status).toBe(500);
+        expect(failed).toEqual({ status: 200, body: GENERIC });
       } finally {
         send.mockRestore();
       }
@@ -247,4 +288,169 @@ describe('initiatePasswordReset route', () => {
     expect(MailSink.get().list()).toHaveLength(0);
     expect(await tokensByEmail()).toEqual(tokensBefore);
   });
+
+  it('one answer whatever happens behind it: mailed, no account, too soon, over a window, a failed send', async () => {
+    await testEnv.createUser({ name: 'Reset User', email: 'one-answer@test.local' });
+    await testEnv.createUser({ name: 'Reset User', email: 'one-answer-fails@test.local' });
+    const answers: RouteOutcome[] = [];
+    const ask = async (email: string, ip?: string) =>
+      answers.push(await invoke(initiatePasswordReset, { ...fromAddress(ip), body: { email } }));
+
+    await ask('one-answer@test.local'); // mailed
+    await ask('one-answer-nobody@test.local'); // no account
+    await ask('one-answer@test.local'); // too soon
+    await ask('one-answer@test.local');
+    await ask('one-answer@test.local'); // over the address window
+    for (let i = 0; i < 11; i++) {
+      await ask(`one-answer-sweep-${i}@test.local`, '198.18.0.1'); // the eleventh is over the client window
+    }
+    const send = jest
+      .spyOn(EmailSender.prototype, 'sendEmail')
+      .mockRejectedValueOnce(new Error('Failed to send email'));
+    try {
+      await ask('one-answer-fails@test.local'); // a failed send
+    } finally {
+      send.mockRestore();
+    }
+
+    expect(answers).toHaveLength(17);
+    expect(new Set(answers.map((answer) => JSON.stringify(answer)))).toEqual(
+      new Set([JSON.stringify({ status: 200, body: GENERIC })])
+    );
+  });
+
+  it('the answer goes out before the account is looked up, a token minted or a mail sent — its timing says nothing', async () => {
+    await testEnv.createUser({ name: 'Reset User', email: 'answer-first@test.local' });
+    const events: string[] = [];
+    const realMint = PasswordResetToken.prototype.mint;
+    const mint = jest.spyOn(PasswordResetToken.prototype, 'mint').mockImplementation(async function (
+      this: PasswordResetToken,
+      ...args: Parameters<PasswordResetToken['mint']>
+    ) {
+      events.push('minted');
+      return await realMint.apply(this, args);
+    });
+    const send = jest.spyOn(EmailSender.prototype, 'sendEmail').mockImplementation(async () => {
+      events.push('mailed');
+    });
+    try {
+      await invoke(initiatePasswordReset, { body: { email: 'answer-first@test.local' } }, events);
+    } finally {
+      mint.mockRestore();
+      send.mockRestore();
+    }
+
+    expect(events).toEqual(['answered', 'minted', 'mailed']);
+  });
+
+  it('per address: the fourth request inside the hour mails nothing, even past the five-minute gap', async () => {
+    await testEnv.createUser({ name: 'Reset User', email: 'address-window@test.local' });
+    for (let i = 0; i < 3; i++) {
+      await invoke(initiatePasswordReset, { body: { email: 'Address-Window@test.local' } });
+      await ageLastMint('address-window@test.local');
+    }
+    expect(MailSink.get().list()).toHaveLength(3);
+    const armed = await userRow('address-window@test.local');
+
+    const fourth = await invoke(initiatePasswordReset, { body: { email: 'address-window@test.local' } });
+
+    expect(fourth).toEqual({ status: 200, body: GENERIC });
+    expect(MailSink.get().list()).toHaveLength(3);
+    expect((await userRow('address-window@test.local')).passwordResetToken).toBe(armed.passwordResetToken);
+  });
+
+  it('per client address: after ten requests the eleventh mails nothing, even for an account; another address still gets its link', async () => {
+    await testEnv.createUser({ name: 'Reset User', email: 'client-window@test.local' });
+    for (let i = 0; i < 10; i++) {
+      await invoke(initiatePasswordReset, {
+        ...fromAddress('198.18.1.1'),
+        body: { email: `client-window-${i}@test.local` },
+      });
+    }
+
+    const eleventh = await invoke(initiatePasswordReset, {
+      ...fromAddress('198.18.1.1'),
+      body: { email: 'client-window@test.local' },
+    });
+
+    expect(eleventh).toEqual({ status: 200, body: GENERIC });
+    expect(MailSink.get().list()).toHaveLength(0);
+
+    await invoke(initiatePasswordReset, { ...fromAddress('198.18.1.2'), body: { email: 'client-window@test.local' } });
+    expect(
+      MailSink.get()
+        .list()
+        .map((mail) => mail.to)
+    ).toEqual([['client-window@test.local']]);
+  });
+
+  it('every request is one outcome line with the account digest and the coarse IP hash — never the address', async () => {
+    await testEnv.createUser({ name: 'Reset User', email: 'reset.privacy.person@test.local' });
+
+    const log = await LogCapture.during(async () => {
+      const ask = (email: string) => invoke(initiatePasswordReset, { ...fromAddress('198.18.2.7'), body: { email } });
+      await ask('reset.privacy.person@test.local'); // mailed
+      await ask('Reset.Privacy.Person@TEST.local'); // too soon
+      await ask('RESET.PRIVACY.PERSON@test.local'); // too soon
+      await ask('reset.privacy.person@test.local'); // over the address window
+      await ask('reset.privacy.nobody@test.local'); // no account
+    });
+
+    const markers = [
+      'Password reset link mailed',
+      'Password reset requested too soon for user',
+      'Password reset throttled',
+      'Password reset requested for non-existent user',
+    ];
+    const accounts = markers.map((marker) => fieldsOn(log, marker, 'account'));
+    expect(accounts.map((values) => values.length)).toEqual([1, 2, 1, 1]);
+    const person = accounts[0][0];
+    expect(person).toMatch(/^[0-9a-f]{16}$/);
+    expect([...accounts[1], ...accounts[2]]).toEqual([person, person, person]);
+    expect(accounts[3][0]).toMatch(/^[0-9a-f]{16}$/);
+    expect(accounts[3][0]).not.toBe(person);
+
+    const ips = ([] as string[]).concat(...markers.map((marker) => fieldsOn(log, marker, 'ip')));
+    expect(ips).toHaveLength(5);
+    expect(ips[0]).toMatch(/^[0-9a-f]{16}$/);
+    expect(new Set(ips)).toEqual(new Set([ips[0]]));
+
+    const text = plain(log.text).toLowerCase();
+    for (const fragment of ['reset.privacy.person', 'reset.privacy.nobody', 'reset.privacy', '198.18.2.']) {
+      expect(text).not.toContain(fragment);
+    }
+  });
+
+  it("a reset link redeemed while wrong guesses hold the account's sign-in window shut lets the new password in at once", async () => {
+    await testEnv.createUser({ name: 'Reset User', email: 'reset-while-shut@test.local' });
+    const signIn = async (password: string) => {
+      let sent: any;
+      const response: any = {
+        send: (body: any) => {
+          sent = body;
+        },
+        status: () => response,
+      };
+      const { request } = await createPassportRequest({
+        body: { email: 'reset-while-shut@test.local', password },
+        ...fromAddress(),
+      });
+      await login.onRequest(request, response);
+      return { sent, signedInAs: request.session.passport?.user as string | undefined };
+    };
+    for (let i = 0; i < 10; i++) {
+      await signIn('wrong guess');
+    }
+    expect((await signIn('wrong guess')).sent).toEqual({ error: 'Too many attempts. Try again in a few minutes.' });
+
+    await invoke(initiatePasswordReset, { body: { email: 'reset-while-shut@test.local' } });
+    const redeemed = await invoke(executePasswordReset, {
+      body: { token: mailedToken(), newPassword: 'a brand new password' },
+    });
+
+    expect(redeemed.status).toBe(200);
+    const after = await signIn('a brand new password');
+    expect(after.sent).toEqual({});
+    expect(after.signedInAs).toBe('reset-while-shut@test.local');
+  });
 });

package/test/LogCapture.test.ts

@@ -0,0 +1,29 @@
+import { LogCapture } from './LogCapture';
+
+/**
+ * The log capture's address reader — what `expect(log.addresses).toEqual([])` stands on. It reads
+ * an address in every spelling a log line can carry: bare, inside a name-and-address form, and
+ * URL-encoded (`%40` for the `@`, `%2B` for a `+`) as a logged request path carries it. A digest
+ * or a bare domain is not an address.
+ */
+describe('LogCapture.addresses', () => {
+  it('reads an address bare, in a name-and-address form, and URL-encoded in a logged path', async () => {
+    const log = await LogCapture.during(async () => {
+      console.log('Email sent successfully to ada@example.com');
+      console.info('Invite from "Grace" <grace.hopper@example.org>');
+      console.info('Started /dev/login?email=ada%2Blane%40example.com');
+      console.warn('Sign-in refused', { account: '0123456789abcdef', domain: 'example.com' });
+    });
+
+    expect(log.addresses).toEqual(['ada@example.com', 'grace.hopper@example.org', 'ada%2Blane%40example.com']);
+  });
+
+  it('reads nothing from a log that names people by digest and domain only', async () => {
+    const log = await LogCapture.during(async () => {
+      console.info('Email sent — 1 recipient (example.com)', { recipients: ['0123456789abcdef'] });
+      console.info('Finished /user/login 200');
+    });
+
+    expect(log.addresses).toEqual([]);
+  });
+});

package/test/LogCapture.ts

@@ -9,6 +9,12 @@ import { createHash } from 'crypto';
 export class LogCapture {
   /** How many leading characters of a token count as the token showing up in a log. */
   private static readonly TOKEN_PREFIX_LENGTH = 12;
+  /**
+   * An e-mail address, as the house's log check reads one: bare, or URL-encoded (`%40` for the `@`)
+   * as a logged request path carries it — a check that read only the bare spelling missed the one
+   * place an address is known to reach a log, the request log's URL.
+   */
+  private static readonly ADDRESS_SHAPE = /[A-Za-z0-9._%+-]+(?:@|%40)[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
 
   private constructor(readonly lines: string[]) {}
 
@@ -38,6 +44,16 @@ export class LogCapture {
     return this.lines.join('\n');
   }
 
+  /** Every e-mail address the log holds, in order of appearance — a log names people by their digests, never by address. */
+  get addresses(): string[] {
+    return this.text.match(LogCapture.ADDRESS_SHAPE) ?? [];
+  }
+
+  /** The capture narrowed to the writes that contain `text` — one door's lines, read with the same readers. */
+  linesContaining(text: string): LogCapture {
+    return new LogCapture(this.lines.filter((line) => line.includes(text)));
+  }
+
   /**
    * Fails unless the log is free of `token` in every form that would let a log reader act on it
    * or tie a line to a row: the token, the SHA-256 digest a row stores for it, and the token's

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