@nxgt/janus 0.17.2 → 0.18.0

package/dist/permissions/index.js

@@ -4,15 +4,15 @@ import {
   UNSTORABLE,
   MAX_PAGE_SIZE2,
   pageLimit2
-} from "../chunks/index-6fxq0kzf.js";
+} from "../chunks/index-4khsm7mw.js";
 import {
   PermissionDepthError2,
   isSetOf2,
   formatEntity2
-} from "../chunks/index-ztng6018.js";
+} from "../chunks/index-kppkcbn5.js";
 import {
   createMemoryRelations2
-} from "../chunks/index-k136102s.js";
+} from "../chunks/index-cntabs9d.js";
 
 // src/permissions/resolve/resolved.ts
 function admits(holders, subject) {

package/docs/README.md

@@ -13,7 +13,7 @@ below are defined once, in [Words](guide/vocabulary.md#words).
 | --- | --- |
 | [Users](guide/users.md) | You are wiring `janus()`, declaring one or several user types, or calling `create`, `update`, `list`, `delete` |
 | [Sessions](guide/sessions.md) | You need to know who a request belongs to, set or clear the cookie, renew, sign out, or test expiry |
-| [E-mail verification and password reset](guide/email-flows.md) | You are sending a verification or reset link, and handling what comes back |
+| [E-mail verification and password reset](guide/email-flows.md) | You are sending a verification or reset link, and handling what comes back — and how requests that send e-mail are throttled per address or user |
 | [Signing in with an e-mailed link](guide/magic-link.md) | You are signing users in with a link sent by e-mail — a magic link: the page that confirms it from a `POST` so mail scanners spend nothing, the lifetime, the errors, and what ends a link |
 | [Signing in with an e-mailed code](guide/sign-in-code.md) | You are signing users in with a six-digit code sent by e-mail — with no password, or beside one: requesting it without telling who exists, keeping the challenge, the attempts and the errors |
 | [The second factor](guide/second-factor.md) | You are turning on TOTP codes: making and rotating the sealing keys, the QR code, `signIn`'s `status`, confirming a challenge, recovery codes for a lost phone, disabling |

package/docs/guide/email-flows.md

@@ -114,7 +114,11 @@ readonly verifyEmail: {
 };
 ```
 
-`send` issues a token for the user's **current** e-mail. `confirm` redeems it
+`send` issues a token for the user's **current** e-mail. It is throttled
+**per user**, five per 10-minute window: past it, `MailThrottledError`
+(`MAIL_THROTTLED`, with `userId`) and no token. The application calls it for a
+user it knows, so an unauthenticated loop on the address cannot spend the
+count, and a user who changes e-mail buys no extra sends. `confirm` redeems it
 and sets `emailVerified`. A token sent to an e-mail the user has since changed
 is `TOKEN_STALE`: confirming it would verify an address nobody holds any more.
 The address is checked again on the very record the write replaces, so an
@@ -165,9 +169,15 @@ if (first !== null && second !== null) {
 
 Requests that arrive at once cannot each keep a link: each spends the
 others' once it issued its own, so at most one survives — sometimes none, and
-the visitor asks again. **Rate-limit `request` per address**, as for sign-in
-codes: each one sends an e-mail and cancels the link before it, so without a
-limit anyone who knows an address can keep its owner from ever using a link.
+the visitor asks again. **`request` is throttled per address**, as for
+sign-in codes: each one sends an e-mail and cancels the link before it, so
+past five requests for one address in a 10-minute window it throws
+`MailThrottledError` (`MAIL_THROTTLED`) and issues nothing; the link last sent
+still works. An address nobody holds is counted and refused alike, and under
+the limit still answers `null`. Somebody who knows an address can fill its
+inbox with at most five reset e-mails a window, but cannot shut the reset:
+the last one sent still works. Limit the route per client yourself too, and
+see [the mail throttle](#requests-that-send-e-mail-are-throttled).
 
 **Writing a password spends every reset link still live.** A `confirm`,
 `changePassword` and `setPassword` each do, so a link sent before the
@@ -222,6 +232,156 @@ export async function resetPassword(request: Request): Promise<Response> {
 }
 ```
 
+## Requests that send e-mail are throttled
+
+**Every request that hands out something to e-mail is counted**, on by default:
+five per 10 minutes, per flow. Past the limit the request throws
+`MailThrottledError` (`MAIL_THROTTLED`, 429) with `retryAfter` — the whole
+seconds to the end of the window, at least 1 — and **a refused request spends,
+invalidates and rotates nothing**: no token, code or challenge is minted, and
+nothing earlier is spent, so **the last link or code sent still confirms until
+it expires**, whoever asked for it. The count comes before anything is issued,
+and the earlier tokens are spent only after a new one is issued.
+
+```ts
+import { MailThrottledError } from '@nxgt/janus';
+
+try {
+	await auth.resetPassword.request(email);
+} catch (error) {
+	if (error instanceof MailThrottledError) {
+		// 429 and Retry-After: error.retryAfter — safe to show, it reveals nothing about accounts.
+		// Tell the visitor: "Check your inbox: the last e-mail we sent still works.
+		// You can ask for a new one in N minutes."
+	}
+	throw error;
+}
+```
+
+| Flow | Counted per | Why |
+| --- | --- | --- |
+| `magicLink.request(email)` | address | Anybody can call it with any address. Counted before the address is looked up, so an address nobody holds is refused like a registered one |
+| `signInCode.request(email)` | address | The same |
+| `resetPassword.request(email)` | address | The same |
+| `verifyEmail.send(user)` | user | The application calls it for a user it knows: an unauthenticated loop on the address cannot spend this count, so it never blocks the user's own verification, and a user changing e-mail buys no extra sends |
+| `stepUp.request(user)`, when it e-mails a code (`via: 'email'`) | user | The same. A step-up confirmed with the app (`via: 'secondFactor'`) sends nothing and is not counted |
+
+**Keep the window no longer than the shortest token lifetime you set.** A
+refused request spends nothing, but the last link or code sent still has to be
+alive. With `tokens.signInCode: '5m'` and the 10-minute window, a code can lapse
+while the visitor is still refused. `janus()` warns for it, once per call, with
+`process.emitWarning` and the code `JANUS_THROTTLE_WINDOW`, naming each flow
+whose lifetime is shorter than the window:
+
+```
+janus: tokens.signInCode is 5m, shorter than mail.throttle.window, 10m — past the limit the last token sent can expire before the refusal ends. Set mail.throttle.window to 5m or less, or raise tokens.signInCode to 10m or more.
+```
+
+Shorten `mail.throttle.window`, or raise the lifetime. Nothing is refused, so
+a window you chose on purpose only costs the warning.
+
+**Each flow counts on its own**: a loop on `magicLink.request` never shuts
+`signInCode.request`. The address is normalised (trimmed, lowercased) and is
+the same count whatever the user type.
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `mail.throttle.attempts` | whole number above zero | `5` | Requests per flow, per address or user, per window |
+| `mail.throttle.window` | `Duration` | `'10m'` | How long a window lasts |
+| `mail.throttle` | `false` | | Counts nothing: limit those requests yourself |
+
+```ts
+janus({ user, store, mail: { throttle: { attempts: 3, window: '1h' } } });
+janus({ user, store, mail: { throttle: false } });
+```
+
+```ts
+export interface MailConfig {
+	readonly throttle?: MailThrottleConfig | false;
+}
+export interface MailThrottleConfig {
+	readonly attempts?: number;
+	readonly window?: Duration;
+}
+```
+
+Five per ten minutes is no longer than the shortest default token lifetime
+(`signInCode` and `stepUp` `'10m'`; `magicLink` `'15m'`, `resetPassword` `'1h'`,
+`verifyEmail` `'24h'`), so under the defaults the last link or code sent —
+issued inside the window — is still live for the whole refusal. It leaves room
+for a visitor who asks again, and holds a loop to thirty e-mails an hour per
+flow and address. A wrong value is refused when `janus()` is called, with
+a `TypeError`: `janus: mail must be an object — { throttle }`, `janus:
+mail.throttle must be { attempts, window }, or false to count nothing`,
+`janus: mail.throttle.attempts must be a whole number above zero`, or a
+`janus: mail.throttle.window` duration message.
+
+**Fixed windows, and nothing locks.** The window is a fixed slice of the
+clock, as the sign-in throttle's. Requests at once are counted in one store
+write each: of twenty at once, exactly five are issued. The next window
+answers again. A refused request is counted too but cannot extend the wait.
+
+**Where the counts live.** In the tokens store, as `secondFactor` tokens named
+by a keyed hash of the flow and the address or user id: no port change, no new
+infrastructure, and never the address. That is one row per flow per address or
+user per window. On PostgreSQL, `collectExpired()` does not collect lapsed
+ones: schedule the delete, as for the sign-in throttle. A flushed or evicting
+Redis forgets the counts, and a tokens store that cannot count throws
+`STORE_FAILED` with nothing issued: it fails closed.
+
+**What it does not do.**
+
+- **It cannot lock somebody out.** Somebody who asks for an address in a loop
+  can fill its inbox with at most five e-mails per window per flow, but the
+  last e-mail they caused to be sent was a real e-mail to the real owner and
+  still works until it expires. The password sign-in is untouched.
+- **A lifetime shorter than the window breaks that.** With
+  `tokens.signInCode: '5m'` and the default window, the last code can expire
+  before the window ends and the visitor has no live code until it does. Keep
+  `mail.throttle.window` no longer than the shortest of the `tokens.*`
+  lifetimes you use.
+- **It is not per client.** `janus` never sees IP addresses, so one client
+  asking for many addresses is not counted. Add a per-IP ceiling in front of
+  the routes: `@nxgt/redis` (0.5.0 and later) has rate limits for it.
+
+```ts
+import { bindRateLimit, defineRateLimit, GuardError } from '@nxgt/redis';
+
+export const mailRequests = defineRateLimit({
+	name: 'mail-requests',
+	key: (p: { ip: string }) => p.ip,
+	limit: 20,
+	per: 3_600_000,
+});
+const perIp = bindRateLimit(client, mailRequests); // or redis.limits.<name> when wired
+
+try {
+	await perIp.enforce({ ip }); // before auth.magicLink.request(email)
+} catch (error) {
+	if (error instanceof GuardError && error.code === 'RATE_LIMITED') {
+		// error.retryAfter is in MILLISECONDS: Math.ceil(error.retryAfter / 1000) for Retry-After
+	}
+	throw error;
+}
+```
+- **A test suite** that requests more than five of one flow for one address or
+  user over a `fixedClock` is throttled: advance the clock past `retryAfter`,
+  or wire `mail: { throttle: false }`.
+
+**Not throttled**, because they follow a write or a sign-in, which are bounded
+elsewhere (the [sign-in throttle](passwords.md#password-guessing-is-throttled)
+bounds sign-ins), not a request to mail an address:
+
+- `update` changing the e-mail: an application write. Its notice to the former
+  address is sent from the `user.emailChanged` event.
+- The notices sent from [events](events.md): a new device, a password changed,
+  a recovery code used, and the like.
+
+`@nxgt/janus-hono` and `@nxgt/janus-graphql` answer `MAIL_THROTTLED` with 429,
+`retryAfter` in the body (or the extensions) and a `Retry-After` header;
+`@nxgt/janus-telemetry` writes a `janus.mail.throttled` warning with
+`janus.mail.flow` and `janus.mail.retryAfter`, never the address.
+
 ## What a token refusal means
 
 | Code | When |

package/docs/guide/errors.md

@@ -17,11 +17,11 @@ export function toResponse(error: unknown): Response {
 
 `statusOf(code)` is the table under [The codes](#the-codes), exported so every
 integration answers a code the same way — `@nxgt/janus-hono`'s `statusOf` is
-this one. It answers `JanusErrorStatus`, a union of the eight statuses it can
-give (`400 | 401 | 403 | 404 | 409 | 500 | 501 | 503`), so a framework whose
+this one. It answers `JanusErrorStatus`, a union of the nine statuses it can
+give (`400 | 401 | 403 | 404 | 409 | 429 | 500 | 501 | 503`), so a framework whose
 response takes a narrower type than `number` accepts it as it is.
 
-`JanusErrorCode` is a union of nineteen string literals, and `statusOf` is a
+`JanusErrorCode` is a union of twenty-one string literals, and `statusOf` is a
 `switch` over it that is exhaustive: when a code is added, it stops compiling
 instead of answering `undefined` — and so does a `switch` of your own.
 
@@ -56,6 +56,7 @@ that wired the library, so no handler needs to tell it apart.
 | `PASSWORD_TOO_SHORT` | `CredentialError` | 400 | Below `password.minLength` | `minLength` — never the password |
 | `CREDENTIALS_INVALID` | `CredentialError` | 401 | Unknown login, no password, or the wrong one — **one code for the three** — and any password, the right one included, at a login past its attempts in the window — see [throttling](passwords.md#password-guessing-is-throttled) | `reason`, for your logs only; `retryAfter`, the seconds until the next window, when throttled |
 | `HASH_UNSUPPORTED` | `CredentialError` | 400 | A stored hash no wired hasher reads | `hashPrefix` — never the hash |
+| `MAIL_THROTTLED` | `MailThrottledError` | 429 | A request that sends e-mail was made too often for one address or one user in the window — see [the mail throttle](email-flows.md#requests-that-send-e-mail-are-throttled). **Nothing was issued, spent or rotated**: the last link or code sent still works | `retryAfter`, the whole seconds to the end of the window, at least 1; `userType`; `userId` only for the per-user flows. No `reason` |
 | `USER_INACTIVE` | `UserInactiveError` | 403 | Deactivated; told only to someone who gave the right password, the right code, or a live sign-in link | `userId` |
 | `STEP_UP_REQUIRED` | `StepUpRequiredError` | 403 | `assertFresh`: the session proved who it is `maxAge` ago or more. Not a denial of the action — ask for a [step-up](step-up.md), then send the request again | `userId` |
 | `TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED`, `TOKEN_STALE` | `TokenError` | 400 | See [e-mail flows](email-flows.md#what-a-token-refusal-means). For a second factor's challenge: sign in again; for a sign-in code's: request a new code — see [sign-in codes](sign-in-code.md#what-confirm-refuses); for a sign-in link: ask for a new link — see [sign-in links](magic-link.md#what-confirm-refuses) | `userId` on `TOKEN_STALE` |
@@ -104,6 +105,14 @@ async function signIn(email: string, password: string): Promise<Response> {
   `Retry-After` header: the login is throttled, and the right password is
   refused too until then. It says nothing of whether the login exists — an
   unknown one is throttled alike.
+- **`MAIL_THROTTLED`'s `retryAfter`** belongs in the body and a `Retry-After`
+  header with a 429. Unlike `reason`, it is **safe to show the visitor**: an
+  address nobody holds is counted and refused alike, so it reveals nothing
+  about accounts. Its message names the call and whether the address or the
+  user was counted: `magicLink.request: too many e-mails asked for this
+  address — the last one sent still works; use it, or wait for the next window`,
+  or `… for this user …`. Tell the visitor to use the last e-mail they received,
+  or to wait `retryAfter` seconds.
 - **`CODE_INVALID`'s `attemptsLeft`** belongs in the body — the form can say
   how many attempts are left. `0` means the challenge is spent: send the visitor
   back to the password.

package/docs/guide/magic-link.md

@@ -90,9 +90,45 @@ once cannot each keep a link: at most one survives, sometimes none, and the
 visitor asks again. A link and a [sign-in code](sign-in-code.md) are
 separate kinds: asking for one leaves the other live.
 
-**Rate-limit the request route**, per address and per client, as you would a
-password reset: every call sends an e-mail, and cancels the link before it.
-Without a limit, anyone who knows an address can fill its inbox.
+**`request` is throttled per address**: every call sends an e-mail and
+cancels the link before it, so past five requests for one address in a
+10-minute window, `request` throws `MailThrottledError` (`MAIL_THROTTLED`)
+and issues nothing: **a refused request spends and rotates nothing, so the
+link last sent still works** until it expires, even when somebody else's
+request caused it. The address is counted
+before anything is looked up, so an address nobody holds is counted and
+refused alike, and under the limit it still answers `null`. Sign-in codes and
+password resets count on their own: a loop on this route never shuts them.
+Answer it with a 429 and `Retry-After`:
+
+```ts
+import { MailThrottledError } from '@nxgt/janus';
+
+try {
+	const issued = await auth.magicLink.request(email);
+	// …send the e-mail from `issued`, whether or not there is one to send
+} catch (error) {
+	if (error instanceof MailThrottledError) {
+		return Response.json(
+			{
+				error: 'too many e-mails — the last one we sent still works; use it, or wait',
+				retryAfter: error.retryAfter,
+			},
+			{ status: 429, headers: { 'retry-after': String(error.retryAfter) } },
+		);
+	}
+	throw error;
+}
+```
+
+Tell the visitor to use the last e-mail they received, or to wait
+`retryAfter` seconds: "Check your inbox: the last e-mail we sent still works.
+You can ask for a new one in N minutes." The throttle is per address, not per
+client: `janus` never sees IP addresses, so one client asking for many
+addresses is not counted. Add a per-IP ceiling with `@nxgt/redis` rate limits
+([example](email-flows.md#requests-that-send-e-mail-are-throttled)). See
+[the mail throttle](email-flows.md#requests-that-send-e-mail-are-throttled)
+for the options.
 
 ## Building the link
 
@@ -332,8 +368,8 @@ has each message with its cause.
   for sign-in codes.
 - **Signing out everywhere.** It revokes sessions; a link opens a new one.
 - **The sign-in throttle.** `signIn.throttle` counts passwords tried at one
-  login; a link is not a password, and its token cannot be guessed. Limit
-  `magicLink.request` yourself, as above.
+  login; a link is not a password, and its token cannot be guessed. The
+  [mail throttle](#requesting-a-link) counts its requests instead.
 
 What does: its own redemption, a newer `request`, its fifteen minutes, an
 e-mail changed since (`TOKEN_STALE`), the user deactivated

package/docs/guide/passwords.md

@@ -234,7 +234,8 @@ The throttle counts per login. It does not see:
 - `changePassword`, which compares the current password too: limit it per
   user.
 - `resetPassword.request`, `signInCode.request` and `magicLink.request`,
-  which send e-mail: limit them per address.
+  which send e-mail: [the mail throttle](email-flows.md#requests-that-send-e-mail-are-throttled)
+  counts them per address, but not per client. Limit them per client.
 
 ```ts
 if (!(await limiter.consume(`sign-in:${clientAddress}`))) {

package/docs/guide/sign-in-code.md

@@ -130,9 +130,9 @@ patient observer; that limit is stated rather than denied.
 
 Every `request` issues a **new** code with its own challenge, and spends the
 earlier ones: only the last code sent works — see
-[attempts](#attempts). `janus` does not limit how often a code is asked for: **rate-limit the request route** per address
-and per client, as you would a password reset, or anyone can fill a user's
-inbox.
+[attempts](#attempts). How often a code is asked for is limited per address by [the mail
+throttle](email-flows.md#requests-that-send-e-mail-are-throttled); limit the
+route per client yourself too.
 
 ## Sending the code by e-mail
 
@@ -252,10 +252,46 @@ Requests that arrive at once cannot each keep a code: each spends the others'
 once it issued its own, so at most one survives — sometimes none, and the
 visitor asks again. Guesses therefore never run against two live challenges.
 
-**Rate-limit `request` per address.** A new challenge takes only a new
-`request`, and each one sends an e-mail and cancels the code before it:
-without a limit, anyone who knows an address can fill its inbox, or keep
-its owner from ever typing a code in time.
+**`request` is throttled per address.** A new challenge takes only a new
+`request`, and each one sends an e-mail and cancels the code before it, so
+past five requests for one address in a 10-minute window `request` throws
+`MailThrottledError` (`MAIL_THROTTLED`) and issues nothing — no challenge is
+minted, a refused request spends and rotates nothing, and the code last sent
+still works until it expires, even when somebody else's request caused it. The address is counted before
+anything is looked up, so an address nobody holds is counted and refused
+alike; under the limit it still answers `null`. This flow counts on its own:
+a loop on `magicLink.request` never shuts it. Answer it with a 429 and
+`Retry-After`:
+
+```ts
+import { MailThrottledError } from '@nxgt/janus';
+
+try {
+	const issued = await auth.signInCode.request(email);
+	// …send the e-mail from `issued`, whether or not there is one to send
+} catch (error) {
+	if (error instanceof MailThrottledError) {
+		return Response.json(
+			{
+				error: 'too many e-mails — the last one we sent still works; use it, or wait',
+				retryAfter: error.retryAfter,
+			},
+			{ status: 429, headers: { 'retry-after': String(error.retryAfter) } },
+		);
+	}
+	throw error;
+}
+```
+
+With several user types the message is prefixed with the type, as in
+`patient.signInCode.request: too many e-mails asked for this address — the last
+one sent still works; use it, or wait for the next window`. Somebody who knows
+an address cannot shut its e-mailed sign-in: the last code they caused to be
+sent still works, and they can only fill the inbox, five per window. Tell the
+visitor to use the last e-mail they received, or to wait `retryAfter` seconds.
+`janus` never sees IP addresses, so one client asking for many addresses is
+not counted: add a per-IP ceiling with `@nxgt/redis` rate limits
+([example](email-flows.md#requests-that-send-e-mail-are-throttled)).
 
 ### Lifetime
 
@@ -267,6 +303,9 @@ arrive and be read; a longer window is a longer life for a stolen challenge.
 janus({ ..., tokens: { signInCode: '15m' } });
 ```
 
+Keep the mail window (`mail.throttle.window`, `'10m'` by default) no longer
+than the lifetime: with `tokens.signInCode: '5m'` the last code can expire
+before the window ends, and the visitor has none live until it does.
 ### The e-mail is verified
 
 A user whose `emailVerified` was `false` has it `true` once `confirm`

package/docs/guide/step-up.md

@@ -181,13 +181,44 @@ counted **per user**, five per 15-minute window, in the same count as
 challenge still gets five guesses per window, not five per challenge. The
 app's code accepted is spent, as at a sign-in: it confirms nothing else.
 
-**Rate-limit `request` per user.** An e-mailed code has no such window:
-five guesses per challenge, and a new challenge takes only a new `request`.
-A stolen session could ask again and again — each request also sends an
-e-mail and cancels the code before it. Limit `stepUp.request` per user —
-a few an hour is plenty for a person — as you limit `signInCode.request`
-per address; the `janus.stepUp.asked` event of `@nxgt/janus-telemetry` is
-the signal to alert on.
+**`request` is throttled per user, when it e-mails.** An e-mailed code has no
+such window: five guesses per challenge, and a new challenge takes only a new
+`request`. A stolen session could ask again and again — each request also
+sends an e-mail and cancels the code before it. So `stepUp.request` counts
+the user, five per 10-minute window (`mail: { throttle }`), and past it throws
+`MailThrottledError` (`MAIL_THROTTLED`, with `userId`) and issues nothing: a
+refused request spends nothing, so the code last sent still works until it
+expires. Tell the user to use the last e-mail they received, or to wait
+`retryAfter` seconds.
+It counts **only** `via: 'email'`: a step-up confirmed with the app
+(`via: 'secondFactor'`) sends nothing and is not counted.
+
+It is per user rather than per address because the application calls it for a
+user it knows: nobody without their session can spend the count, so an
+unauthenticated loop on their address never blocks their own step-up, and a
+user who changes e-mail buys no extra sends. Answer it with a 429 and
+`Retry-After`:
+
+```ts
+import { MailThrottledError } from '@nxgt/janus';
+
+try {
+	const issued = await auth.stepUp.request(current.user);
+	// …send the e-mail from `issued`, whether or not there is one to send
+} catch (error) {
+	if (error instanceof MailThrottledError) {
+		return Response.json(
+			{ error: 'too many e-mails', retryAfter: error.retryAfter },
+			{ status: 429, headers: { 'retry-after': String(error.retryAfter) } },
+		);
+	}
+	throw error;
+}
+```
+
+The `janus.stepUp.asked` event of `@nxgt/janus-telemetry` is the signal to
+alert on; it also writes a `janus.mail.throttled` warning when the throttle
+refuses. See [the mail throttle](email-flows.md#requests-that-send-e-mail-are-throttled).
 
 A step-up and a sign-in code are **two kinds of token**: a sign-in code's
 challenge confirms no action, and a step-up's code signs nobody in.

package/docs/guide/users.md

@@ -98,6 +98,7 @@ that cuts an emoji in half, say.
 | `tokens.magicLink` | `Duration` | `'15m'` | How long an e-mailed sign-in link lives. See [sign-in links](magic-link.md) |
 | `tokens.stepUp` | `Duration` | `'10m'` | How long a step-up's challenge — and its e-mailed code — lives. See [step-up](step-up.md) |
 | `signIn.throttle` | `{ attempts?, window? }` or `false` | `{ attempts: 10, window: '15m' }` | Passwords one login may try per window, the right one included, before `signIn` answers `CREDENTIALS_INVALID` with `retryAfter` until the window ends. `false` counts nothing. See [passwords](passwords.md#password-guessing-is-throttled) |
+| `mail.throttle` | `{ attempts?, window? }` or `false` | `{ attempts: 5, window: '10m' }` | E-mails one address (`magicLink`, `signInCode`, `resetPassword` requests) or one user (`verifyEmail.send`, an e-mailed `stepUp.request`) may ask for per flow and window, before the request throws `MAIL_THROTTLED` with `retryAfter` and issues nothing (the last link or code sent still works). Keep `window` no longer than the shortest `tokens.*` lifetime you use. `false` counts nothing. See [e-mail flows](email-flows.md#requests-that-send-e-mail-are-throttled) |
 | `secondFactor` | `{ issuer, keys, challenge? }` | none | A TOTP second factor for every type with a password. Changes what `signIn` answers — see [the second factor](second-factor.md#configuration) |
 | `devices` | `{ keys }` | none | The keys device tokens are signed with, to tell a sign-in from a new device. Without it, no sign-in may be given a `device` — see [devices](devices.md#wiring) |
 | `events` | `UserEventListener` | none | Called with every user event — `user.created`, `user.deleted`, … — after the write, awaited. See [user events](events.md) |

package/docs/roadmap.md

@@ -16,7 +16,8 @@ Nothing yet.
 - **Collecting lapsed one-time tokens** — `collectExpired()` deletes lapsed
   sessions only. On a store with no TTL (PostgreSQL), lapsed tokens stay
   until you delete them, and the sign-in throttle adds one per login tried
-  per window. A port method to collect them, as sessions are, would let the
+  per window, and the mail throttle one per flow per address or user per
+  window. A port method to collect them, as sessions are, would let the
   core do it.
 
 - **More official adapters** — the ports are cut where atomicity is not
@@ -70,6 +71,18 @@ Nothing yet.
 The last ten, newest first, each with the version it came in. Everything
 before is in the [CHANGELOG](../CHANGELOG.md).
 
+- **Requests that send e-mail are throttled, v0.18.0** —
+  `janus({ mail: { throttle: { attempts, window } } })`, five per ten
+  minutes by default and `false` to turn it off. `magicLink.request`,
+  `signInCode.request` and `resetPassword.request` count per address;
+  `verifyEmail.send` and an e-mailed `stepUp.request` count per user; each
+  flow on its own. Past the limit a request throws `MailThrottledError`
+  (`MAIL_THROTTLED`, 429) with `retryAfter` and issues, spends and rotates
+  nothing: the last link or code sent still works, so a loop on an address
+  cannot lock its owner out.
+  The window is no longer than the shortest default token lifetime. The counts
+  live in the tokens store, with no port change. `MailConfig` and
+  `MailThrottleConfig` are exported.
 - **A sign-in from a new device, v0.17.0** — `janus({ devices: { keys } })`,
   and `{ device }` as the last argument of `signUp`, `signIn`,
   `secondFactor.confirm`, `secondFactor.recover`, `signInCode.confirm` and

package/docs/troubleshooting.md

@@ -42,6 +42,8 @@ How the messages are shaped:
 - [`janus: devices.keys: …`](#janus-deviceskeys-expected-at-least-one-key---id-key--the-first-seals)
 - [`janus: events must be a function that takes a user event …`](#janus-events-must-be-a-function-that-takes-a-user-event--webhooks---from-nxgtjanus-webhooks-or-your-own)
 - [`janus: signIn.throttle …` wiring messages](#janus-signinthrottle-wiring-messages)
+- [`janus: mail.throttle …` wiring messages](#janus-mailthrottle-wiring-messages)
+- [`janus: tokens.<flow> is 5m, shorter than mail.throttle.window, 10m …`](#janus-tokensflow-is-5m-shorter-than-mailthrottlewindow-10m-)
 - [Other `janus:` wiring messages](#other-janus-wiring-messages)
 
 **Users, sessions and tokens**
@@ -54,6 +56,7 @@ How the messages are shaped:
 - [`PASSWORD_TOO_SHORT` — `<call>: the password is shorter than the policy's <n> characters`](#password_too_short--call-the-password-is-shorter-than-the-policys-n-characters)
 - [`CREDENTIALS_INVALID` — `<call>: the login and the password do not match`](#credentials_invalid--call-the-login-and-the-password-do-not-match)
 - [`CREDENTIALS_INVALID` — `<call>: too many passwords tried at this login …`](#credentials_invalid--call-too-many-passwords-tried-at-this-login--wait-for-the-next-window)
+- [`MAIL_THROTTLED` — `<call>: too many e-mails asked for this address …`, or `… for this user …`](#mail_throttled--call-too-many-e-mails-asked-for-this-address--the-last-one-sent-still-works-use-it-or-wait-for-the-next-window)
 - [`STORE_FAILED` — `<call>: the store dropped the attempts it had just stored`](#store_failed--call-the-store-dropped-the-attempts-it-had-just-stored)
 - [`HASH_UNSUPPORTED` — `<call>: no wired verifier claims the prefix "<prefix>"`](#hash_unsupported--call-no-wired-verifier-claims-the-prefix-prefix)
 - [`scryptHasher: the stored hash has the $scrypt$ prefix and not its format`](#scrypthasher-the-stored-hash-has-the-scrypt-prefix-and-not-its-format)
@@ -465,6 +468,39 @@ zero`, and a `janus: signIn.throttle.window` that is not a duration.
 **Fix:** `signIn: { throttle: { attempts: 10, window: '15m' } }` — the
 defaults — or `signIn: { throttle: false }` to count nothing.
 
+### `janus: mail.throttle` wiring messages
+
+`TypeError`, at `janus()`: `janus: mail must be an object — { throttle }`,
+`janus: mail.throttle must be { attempts, window }, or false to count
+nothing`, `janus: mail.throttle.attempts must be a whole number above zero`,
+and a `janus: mail.throttle.window` that is not a duration.
+**Fix:** `mail: { throttle: { attempts: 5, window: '10m' } }` — the defaults —
+or `mail: { throttle: false }` to count nothing.
+
+### `janus: tokens.<flow> is 5m, shorter than mail.throttle.window, 10m …`
+
+A warning, not an error: `janus()` returns, and emits through
+`process.emitWarning` with the code `JANUS_THROTTLE_WINDOW`, once per call. The
+text, here for `tokens.signInCode: '5m'` with the default window:
+
+```
+janus: tokens.signInCode is 5m, shorter than mail.throttle.window, 10m — past the limit the last token sent can expire before the refusal ends. Set mail.throttle.window to 5m or less, or raise tokens.signInCode to 10m or more.
+```
+
+With several flows shorter than the window, one warning lists each
+(`tokens.magicLink is 2m, … ; tokens.stepUp is 30s, …`). **Why:** a request the
+mail throttle refuses spends nothing, so the last link or code sent still works,
+but only until it expires; with a lifetime shorter than the window it can lapse
+while the visitor is still refused. **Fix:** make the window no longer than the
+shortest lifetime, or raise the lifetime:
+
+```ts
+janus({ user, store, tokens: { signInCode: '5m' }, mail: { throttle: { window: '5m' } } });
+```
+
+A runtime without `process.emitWarning` stays silent. Silence it with
+`node --disable-warning=JANUS_THROTTLE_WINDOW`.
+
 ### Other `janus:` wiring messages
 
 | Message | Fix |
@@ -641,6 +677,52 @@ if (error instanceof JanusError && error.retryAfter !== undefined) {
 janus({ ..., signIn: { throttle: { attempts: 20, window: '15m' } } });
 ```
 
+### `MAIL_THROTTLED` — `<call>: too many e-mails asked for this address — the last one sent still works; use it, or wait for the next window`
+
+`MailThrottledError`, with `retryAfter` and `userType`. The per-user flows say
+`… too many e-mails asked for this user — the last one sent still works; use
+it, or wait for the next window` and carry `userId`.
+
+**When:** `magicLink.request`, `signInCode.request` or
+`resetPassword.request` (per address), or `verifyEmail.send` and an e-mailed
+`stepUp.request` (per user), past five requests of that flow in the current
+10-minute window — whether or not anybody holds the address. `<call>` is the
+call, such as `magicLink.request` or `patient.signInCode.request`.
+**Why:** requests that send e-mail are throttled, on by default, so a loop
+cannot fill an inbox or cancel its owner's link or code. Each flow counts on
+its own, in fixed windows of the clock, by the store. **A refused request
+spends, invalidates and rotates nothing**: no token, code or challenge is
+issued, and the last link or code sent — by anyone's request, an attacker's
+included — still confirms until it expires, so a loop on a victim's address
+cannot lock them out. Nothing locks: the next window answers again. In tests with `fixedClock`, the window never
+ends.
+**Fix:** answer 429 with a `Retry-After` header, and tell the visitor to use
+the last e-mail they received (it still works), or to wait `retryAfter`
+seconds: "Check your inbox: the last e-mail we sent still works. You can ask for
+a new one in N minutes." It reveals nothing about accounts, so it is safe to
+show.
+In tests, advance the clock past `retryAfter`, or wire `mail: { throttle:
+false }`. If nobody you know asked five times, somebody is looping on the
+route: `janus` never sees IP addresses, so limit it per client, which the
+throttle does not — with `@nxgt/redis` rate limits (`defineRateLimit`,
+`bindRateLimit`; `enforce()` throws `GuardError` `RATE_LIMITED` whose
+`retryAfter` is in milliseconds), as in the
+[e-mail flows guide](guide/email-flows.md#requests-that-send-e-mail-are-throttled).
+If you set a token lifetime shorter than the window (`tokens.signInCode: '5m'`
+with the default), the last code can expire before the window ends: keep
+`mail.throttle.window` no longer than the shortest `tokens.*` you use.
+
+```ts
+import { MailThrottledError } from '@nxgt/janus';
+
+if (error instanceof MailThrottledError) {
+	const headers = { 'retry-after': String(error.retryAfter) };
+	return Response.json({ code: error.code, retryAfter: error.retryAfter }, { status: 429, headers });
+}
+
+janus({ ..., mail: { throttle: { attempts: 10, window: '10m' } } });
+```
+
 ### `STORE_FAILED` — `<call>: the store dropped the attempts it had just stored`
 
 `StoreFailure`, with `slot: 'tokens'` and `operation: 'countAttempt'`.
@@ -1153,7 +1235,9 @@ A `TypeError`.
 
 The messages start with `signInCode.confirm` — prefixed by the type with
 several user types: `patient.signInCode.confirm: …`. `signInCode.request`
-throws nothing but `STORE_FAILED`: an e-mail it cannot sign in is `null`.
+throws nothing but `STORE_FAILED` and
+[`MAIL_THROTTLED`](#mail_throttled--call-too-many-e-mails-asked-for-this-address--the-last-one-sent-still-works-use-it-or-wait-for-the-next-window):
+an e-mail it cannot sign in is `null`.
 `signInCode.confirm` also rejects with
 [`CODE_INVALID`](#code_invalid--call-the-code-does-not-match-or-was-already-used),
 [`TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED`](#token_unknown-token_spent-token_expired),
@@ -1236,8 +1320,9 @@ janus({
 
 `magicLink.confirm`'s messages start with `magicLink.confirm` — prefixed by
 the type with several user types: `patient.magicLink.confirm: …`.
-`magicLink.request` throws nothing but `STORE_FAILED`: an e-mail it cannot
-sign in is `null`. `magicLink.confirm` rejects with
+`magicLink.request` throws nothing but `STORE_FAILED` and
+[`MAIL_THROTTLED`](#mail_throttled--call-too-many-e-mails-asked-for-this-address--the-last-one-sent-still-works-use-it-or-wait-for-the-next-window):
+an e-mail it cannot sign in is `null`. `magicLink.confirm` rejects with
 [`TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED`](#token_unknown-token_spent-token_expired),
 [`TOKEN_STALE`](#token_stale--call-the-token-was-sent-to-an-e-mail-the-user-no-longer-has),
 [`USER_INACTIVE`](#user_inactive--call-the-user-is-inactive) and

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/janus",
-	"version": "0.17.2",
+	"version": "0.18.0",
 	"description": "Embeddable, type-safe identities and permissions: bring your own database",
 	"license": "MIT",
 	"type": "module",

package/dist/auth/config/resolve-sign-in.d.ts

@@ -1,5 +0,0 @@
-/** Resolves `signIn.throttle`: on unless `false`, ten passwords per login per fifteen minutes. */
-import type { SignInConfig } from './janus-config';
-import type { ResolvedConfig } from './resolved-config';
-export declare function resolveSignInThrottle(config: SignInConfig | undefined, where: string): ResolvedConfig['signInThrottle'];
-//# sourceMappingURL=resolve-sign-in.d.ts.map