@proteinjs/user-server 1.22.0 → 1.22.2

package/src/authentication/PasswordResetToken.ts

@@ -13,22 +13,42 @@ export type PasswordResetResolution =
  * The password-reset token's one owner: its shape, its mint, the lookup that maps a presented
  * value back to the user it was issued to, and its single-use redemption.
  *
- * A token is 32 bytes from the platform CSPRNG, hex-encoded (64 lowercase hex characters),
- * stored on the user row beside its expiry until it is redeemed or expires.
+ * A token is 32 bytes from the platform CSPRNG, hex-encoded (64 lowercase hex characters). The
+ * token itself exists only in the link mailed to the account: the user row stores its SHA-256
+ * digest (hex) beside the expiry, never the token, so a read of the table yields nothing that
+ * can be presented. A digest is not a token — presenting one is hashed again and matches no row.
+ * A fast unsalted hash is enough here because the input is 256 bits of CSPRNG output, not a
+ * human-chosen secret.
  *
- * Resolution refuses anything that is not a value of that shape BEFORE any lookup. A query
- * filter built from a request value that is not a token does not compare the way a token does:
- * `null` renders as `IS NULL` and would match every account with no pending reset, an empty
- * string matches an emptied column, and other types reach the driver. The row the lookup
- * returns is then re-checked in code — its stored token must be a string equal to the presented
- * one (compared in constant time) and its expiry a real timestamp still in the future — so the
+ * Resolution refuses anything that is not a value of the token's shape BEFORE any lookup. A
+ * query filter built from a request value that is not a token does not compare the way a token
+ * does: `null` renders as `IS NULL` and would match every account with no pending reset, an
+ * empty string matches an emptied column, and other types reach the driver. The presented token
+ * is then hashed, the row is looked up by that digest, and the row the lookup returns is
+ * re-checked in code — its stored digest must be a string equal to the presented token's digest
+ * (compared in constant time) and its expiry a real timestamp still in the future — so the
  * outcome never rests on how the storage compares.
+ *
+ * No migration accompanies the move from a stored token to a stored digest: a row that still
+ * holds a token minted before it never equals the digest of anything presented, so that token
+ * fails validation for what remains of its hour and the person asks for a new link.
  */
 export class PasswordResetToken {
   private static readonly SHAPE = /^[0-9a-f]{64}$/;
+  private static readonly LIFETIME_MINUTES = 60;
 
-  mint(): string {
-    return randomBytes(32).toString('hex');
+  /**
+   * Issue a token to `user`: store its digest and its expiry on the row, replacing any token
+   * outstanding, and return the token — the only time it exists outside the mailed link.
+   */
+  async mint(user: User): Promise<string> {
+    const token = randomBytes(32).toString('hex');
+    await getDbAsSystem().update(tables.User, {
+      id: user.id,
+      passwordResetToken: this.digest(token),
+      passwordResetTokenExpiration: moment().add(PasswordResetToken.LIFETIME_MINUTES, 'minutes'),
+    });
+    return token;
   }
 
   async resolve(presented: unknown): Promise<PasswordResetResolution> {
@@ -37,8 +57,9 @@ export class PasswordResetToken {
       return { status: 'malformed' };
     }
 
-    const user = await getDbAsSystem().get(tables.User, { passwordResetToken: token });
-    if (!user || !this.matches(user.passwordResetToken, token)) {
+    const digest = this.digest(token);
+    const user = await getDbAsSystem().get(tables.User, { passwordResetToken: digest });
+    if (!user || !this.matches(user.passwordResetToken, digest)) {
       return { status: 'unknown' };
     }
 
@@ -51,38 +72,71 @@ export class PasswordResetToken {
 
   /**
    * Write the new credential and clear the token in one conditional update: the row must still
-   * carry this token at write time, so two presentations of the same token cannot both succeed.
-   * Resolves false when the token was already redeemed.
+   * carry this token's digest at write time, so two presentations of the same token cannot both
+   * succeed. Resolves false when the token was already redeemed.
    */
   async redeem(user: User, token: string, hashedPassword: string): Promise<boolean> {
     const updated = await getDbAsSystem().update(
       tables.User,
       { password: hashedPassword, passwordResetToken: null, passwordResetTokenExpiration: null },
-      { id: user.id, passwordResetToken: token }
+      { id: user.id, passwordResetToken: this.digest(token) }
     );
     return updated === 1;
   }
 
-  /** A log-safe reference to a presented token: a short digest of a well-formed one, never the value itself. */
+  /**
+   * Withdraw a token that never reached its owner (the mail carrying it failed to send): the row
+   * is cleared only while it still carries this token's digest, so a newer token is left alone.
+   */
+  async revoke(user: User, token: string): Promise<void> {
+    await getDbAsSystem().update(
+      tables.User,
+      { passwordResetToken: null, passwordResetTokenExpiration: null },
+      { id: user.id, passwordResetToken: this.digest(token) }
+    );
+  }
+
+  /** When the token outstanding on `user` was minted, or undefined when the row carries none. */
+  mintedAt(user: User): Moment | undefined {
+    if (!user.passwordResetToken || !user.passwordResetTokenExpiration) {
+      return undefined;
+    }
+
+    return moment(user.passwordResetTokenExpiration).subtract(PasswordResetToken.LIFETIME_MINUTES, 'minutes');
+  }
+
+  /**
+   * A log-safe reference to a presented token: a short prefix of a well-formed one's digest,
+   * never the value itself and never a part of it. The routes log it only for a token that
+   * resolved `unknown` — one no row carries — so it never lines up with a digest a row holds.
+   * What it is for is telling refusals apart in the log: one stale link presented again reads
+   * the same each time, a run of different values reads differently. 48 bits of the SHA-256 of
+   * 256 random bits identify nothing and can be presented nowhere.
+   */
   fingerprint(presented: unknown): string | undefined {
     const token = this.parse(presented);
     if (token === undefined) {
       return undefined;
     }
 
-    return createHash('sha256').update(token).digest('hex').slice(0, 12);
+    return this.digest(token).slice(0, 12);
   }
 
   private parse(presented: unknown): string | undefined {
     return typeof presented === 'string' && PasswordResetToken.SHAPE.test(presented) ? presented : undefined;
   }
 
-  private matches(stored: string | null | undefined, presented: string): boolean {
-    if (typeof stored !== 'string' || stored.length !== presented.length) {
+  /** What the row stores in place of a token: its SHA-256, hex-encoded. */
+  private digest(token: string): string {
+    return createHash('sha256').update(token).digest('hex');
+  }
+
+  private matches(storedDigest: string | null | undefined, presentedDigest: string): boolean {
+    if (typeof storedDigest !== 'string' || storedDigest.length !== presentedDigest.length) {
       return false;
     }
 
-    return timingSafeEqual(Buffer.from(stored), Buffer.from(presented));
+    return timingSafeEqual(Buffer.from(storedDigest), Buffer.from(presentedDigest));
   }
 
   private isLive(expiration: Moment | null | undefined): boolean {

package/src/authentication/authenticate.ts

@@ -1,6 +1,7 @@
 import { getDbAsSystem } from '@proteinjs/db';
-import { tables } from '@proteinjs/user';
+import { User, tables } from '@proteinjs/user';
 import { Logger } from '@proteinjs/logger';
+import { RequestDigests } from '../throttle/RequestDigests';
 import { DefaultAdminCredentials } from './DefaultAdminCredentials';
 import { PasswordHasher } from './PasswordHasher';
 
@@ -24,15 +25,12 @@ export async function authenticate(email: string, password: string): Promise<tru
     return true;
   }
 
-  // Fetch by EMAIL ONLY and compare in code — never query by password hash. Query-by-hash
-  // forced every stored credential into one deterministic queryable value (unsalted sha256);
-  // in-code comparison is what lets the stored format be salted and per-user.
-  const db = getDbAsSystem();
-  const user = await db.get(tables.User, { email: email.toLowerCase() });
-  const hasher = new PasswordHasher();
-  if (!user || !(await hasher.verify(user.password, password))) {
+  const { user, matches } = await checkPassword(email, password);
+  if (!user || !matches) {
     return 'User name or password incorrect';
   }
+  const db = getDbAsSystem();
+  const hasher = new PasswordHasher();
 
   // Verify-then-rehash: the just-proven password re-hashes a legacy sha256 row into the
   // current format in place — the only moment the plaintext is available to migrate with.
@@ -53,9 +51,38 @@ export async function authenticate(email: string, password: string): Promise<tru
       return true;
     }
 
-    logger.warn({ message: 'Refused login for deactivated account', obj: { email: email.toLowerCase() } });
+    logger.warn({
+      message: 'Refused login for deactivated account',
+      obj: { account: new RequestDigests().account(email) },
+    });
     return 'This account has been deactivated';
   }
 
   return true;
 }
+
+/**
+ * Looks the account up and verifies the password — the cost every refusal pays, whether or not
+ * the address has an account: with none, the password is verified against a stand-in of the
+ * same cost (`PasswordHasher.verifyAgainstNothing`), so a refusal's timing says nothing about
+ * the address; a human row still in the legacy sha256 format (verified in microseconds) pays the
+ * stand-in too, so a refusal's timing says nothing about whether the account has signed in since
+ * the format changed either. The login door also runs it on a throttled try and discards the
+ * verdict, so a throttled answer takes as long as a refused password. No side effects (no
+ * rehash, no log).
+ */
+export async function checkPassword(email: string, password: string): Promise<{ user?: User; matches: boolean }> {
+  // Fetch by EMAIL ONLY and compare in code — never query by password hash. Query-by-hash
+  // forced every stored credential into one deterministic queryable value (unsalted sha256);
+  // in-code comparison is what lets the stored format be salted and per-user.
+  const user = await getDbAsSystem().get(tables.User, { email: email.toLowerCase() });
+  const hasher = new PasswordHasher();
+  if (!user) {
+    return { matches: await hasher.verifyAgainstNothing(password) };
+  }
+  const matches = await hasher.verify(user.password, password);
+  if (hasher.needsRehash(user.password, user.isLoadedFromSource === true ? 'machine' : 'human')) {
+    await hasher.verifyAgainstNothing(password);
+  }
+  return { user, matches };
+}

package/src/routes/devLogin.ts

@@ -45,7 +45,7 @@ const emailDomain = (address: string) => address.slice(address.lastIndexOf('@')
  * call is unchanged; the variable absent = nothing changes; the gates closed = 404 regardless.
  * Test and prod never set it — the omission is the safety, the same idiom as the gates. The
  * outcome is logged as ONE marker line, `Dev bootstrap admin door: <granted|admin-exists>`,
- * which the n3xa compose-estate boot proof reads from the server log to PROVE the grant landed.
+ * which a consumer's boot proof can read from the server log to PROVE the grant landed.
  *
  * Role-bootstrap door (`DEV_BOOTSTRAP_ROLES='email:role[,role];email:role…'`, the grammar in
  * DevBootstrapRoles.ts): the first-admin door leaves every OTHER account role-less, and a

package/src/routes/executePasswordReset.ts

@@ -3,6 +3,8 @@ import { routes } from '@proteinjs/user';
 import { Logger } from '@proteinjs/logger';
 import { PasswordHasher } from '../authentication/PasswordHasher';
 import { PasswordResetToken } from '../authentication/PasswordResetToken';
+import { RequestDigests } from '../throttle/RequestDigests';
+import { signInThrottle } from '../throttle/SignInThrottle';
 
 /**
  * Route handler for executing a password reset.
@@ -10,7 +12,12 @@ import { PasswordResetToken } from '../authentication/PasswordResetToken';
  * Resolves the presented token through `PasswordResetToken` — which refuses anything but a
  * well-formed token before any lookup — checks its expiry, and redeems it: the new password is
  * written and the token cleared in one conditional update, so a token resets a password once.
- * The token itself never reaches the log.
+ * The token itself never reaches the log. A request that carries no body at all is refused like
+ * one that carries a blank password.
+ *
+ * A redeemed link also opens the account's sign-in window again (`SignInThrottle`): the person
+ * just proved the mailbox, so a reset made while wrong guesses held the door shut lets the new
+ * password in at once instead of waiting the window out.
  *
  * @bodyParam {string} token - The password reset token.
  * @bodyParam {string} newPassword - The new password for the user.
@@ -20,7 +27,7 @@ export const executePasswordReset: Route = {
   method: routes.executePasswordReset.method,
   onRequest: async (request, response): Promise<void> => {
     const logger = new Logger({ name: 'executePasswordReset' });
-    const { token, newPassword } = request.body;
+    const { token, newPassword } = request.body ?? {};
     if (typeof newPassword !== 'string' || newPassword.length === 0) {
       response.status(400).send({ error: 'New password cannot be blank' });
       return;
@@ -51,6 +58,7 @@ export const executePasswordReset: Route = {
       return;
     }
 
+    signInThrottle.recordSuccess(new RequestDigests().account(user.email));
     logger.info({ message: `Password successfully reset`, obj: { email: user.email } });
     response.send({ message: 'Password has been successfully reset' });
   },

package/src/routes/initiatePasswordReset.ts

@@ -8,12 +8,29 @@ 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.
  *
- * This route handles the process of generating a password reset token,
- * sending a reset email to the user, and storing the token and expiration of the token in the database.
+ * Mints a reset token through `PasswordResetToken` — which stores only the token's digest and
+ * 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.
  *
@@ -27,29 +44,35 @@ export const initiatePasswordReset: Route = {
   method: routes.initiatePasswordReset.method,
   onRequest: async (request, response): Promise<void> => {
     const logger = new Logger({ name: 'initiatePasswordReset' });
-    const email = request.body.email?.toLowerCase();
-    const db = getDbAsSystem();
+    const { email: requestedEmail } = request.body ?? {};
+    if (typeof requestedEmail !== 'string' || requestedEmail.length === 0) {
+      response.status(400).send({ error: 'Email cannot be blank' });
+      return;
+    }
 
-    const genericResponse = { message: 'If an account with that email exists, we have sent a password reset link.' };
+    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 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;
     }
 
     // Check if there's an existing token and it's less than 5 minutes old
-    if (user.passwordResetToken && user.passwordResetTokenExpiration) {
-      const currentTime = moment();
-      const tokenCreationTime = moment(user.passwordResetTokenExpiration).subtract(1, 'hour');
-      const timeDifference = currentTime.diff(tokenCreationTime, 'minutes');
-      if (timeDifference < 5) {
-        logger.info({ message: `Password reset requested too soon for user`, obj: { email } });
-        response.send(genericResponse);
-        return;
-      }
+    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: fields });
+      return;
     }
 
     const emailSender = new EmailSender();
@@ -61,9 +84,8 @@ export const initiatePasswordReset: Route = {
       );
     }
 
-    // Generate reset token
-    const passwordResetToken = new PasswordResetToken().mint();
-    const passwordResetTokenExpiration = moment().add(1, 'hour');
+    // The row now holds the token's digest; the token itself goes only into the mailed link
+    const passwordResetToken = await resetToken.mint(user);
 
     try {
       const config = defaultConfigFactory.getConfig();
@@ -78,12 +100,11 @@ export const initiatePasswordReset: Route = {
         ...config.options,
       });
 
-      // If email is sent successfully, save reset token to user record
-      await db.update(tables.User, { id: user.id, passwordResetToken, passwordResetTokenExpiration });
-      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 });
-      response.status(500).send({ error: 'Failed to send password reset email. Please try again later.' });
+      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);
     }
   },
 };

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