@nxgt/janus 0.17.2 → 0.19.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/adapters.md

@@ -31,7 +31,7 @@ describeJanusStores({
 
 | Port | Taken by | Methods |
 | --- | --- | --- |
-| `JanusStores` — `{ users: UserStore, sessions: SessionStore, tokens: TokenStore }` | `janus({ store })` | 6 + 6 (+ 1 optional) + 4 |
+| `JanusStores` — `{ users: UserStore, sessions: SessionStore, tokens: TokenStore }` | `janus({ store })` | 6 (+ 1 optional) + 7 (+ 1 optional) + 5 |
 | `RelationStore` | `permissions({ store })`, `janus({ relations })` | 6 |
 
 They are separate on purpose: an application that only authenticates
@@ -57,6 +57,7 @@ record, a session is derived state, a token is ephemeral.
 interface UserStore {
 	insertUser(record: UserRecord): Promise<UserRecord>;
 	findUser(id: Id): Promise<UserRecord | null>;
+	findUsers?(ids: readonly Id[]): Promise<readonly UserRecord[]>; // optional: one query for many ids
 	findUserByLogin(type: string, login: string): Promise<UserRecord | null>;
 	listUsers(page: UserPageRequest): Promise<CursorPage<UserRecord>>;
 	updateUser(id: Id, patch: UserPatch, ifVersion: number): Promise<UserRecord>;
@@ -77,6 +78,41 @@ interface UserStore {
 - `listUsers` pages in ascending id order; `after` is the last id of the
   previous page, already checked by the core.
 
+#### `UserStore.findUsers` (optional)
+
+What `findMany` asks for: the users holding these ids, **in one query**.
+Leave it out and nothing breaks — `findMany` reads with `findUser` instead,
+ten at a time — so implement it when your database can answer a list of ids
+in one round trip.
+
+- **Whatever their type**, as `findUser`: the core keeps the type's own users,
+  and puts them back in its caller's order. Answer them **in any order**.
+- **An id nobody holds is left out.** An absence is a shorter list — `[]` when
+  nobody holds any — never `null`, never a rejection.
+- **A failure throws**, as everywhere on the port (rule 2). Answering `[]` for
+  an outage tells the application those users do not exist.
+- The core calls it with **1 to 100 distinct, well-formed ids**, never an
+  empty list, and reads a longer list in several calls one after another — no
+  `IN` grows past 100.
+
+```ts
+import type { UserStore } from '@nxgt/janus';
+
+// PostgreSQL through Drizzle — @nxgt/janus-drizzle's, in one statement
+findUsers: async (ids) =>
+	(await db.select().from(users).where(inArray(users.id, [...ids]))).map(toUser),
+
+// MongoDB — @nxgt/janus-mongo's, in one query
+findUsers: async (ids) =>
+	(await collection.find({ _id: { $in: [...ids] } }).toArray()).map(toUser),
+```
+
+`janus()` reads its presence once (`StoreCapabilities.findUsers`), and refuses
+a `findUsers` that is there but not a function with a `TypeError`: a value in
+the wrong place is a wiring mistake, not an absent capability. The suite's
+`users.findUsers`, `users.findUsersNone` and `outage.findUsers` cases check it,
+and are skipped with their reason for a store that leaves it out.
+
 #### A user's password and second factor
 
 Both are one field of `UserRecord`, `null` when the user has none, and a
@@ -407,7 +443,7 @@ compile error naming the missing method.
 
 | Suite | Cases | Harness opens |
 | --- | --- | --- |
-| `describeJanusStores({ name, harness, runner?, faults?, skip? })` | 55: users, sessions, tokens, and one outage per method whose honest answer can be "nothing" — fourteen of them | `{ stores, faults?, close? }` |
+| `describeJanusStores({ name, harness, runner?, faults?, skip? })` | 58: users, sessions, tokens, and one outage per method whose honest answer can be "nothing" — fifteen of them | `{ stores, faults?, close? }` |
 | `describeRelationStores({ name, harness, runner?, faults?, skip? })` | 16: the relation store, ids of edge characters, and one outage per method | `{ store, faults?, close? }` |
 
 `harness.open()` is called **once per case** and must answer fresh, empty
@@ -504,8 +540,12 @@ describeJanusStores({
 
 A skipped case still appears in the run, with its reason in its name. A case
 that cannot run on the stores it was given — an outage case with no `faults`,
-`collectExpired` on a store without `deleteExpiredSessions` — passes, and
-emits a `JANUS_CONFORMANCE_SKIPPED` warning with the reason.
+`collectExpired` on a store without `deleteExpiredSessions`, a `findUsers`
+case on a store without `findUsers` — passes, and emits a
+`JANUS_CONFORMANCE_SKIPPED` warning with the reason. A case's `needs` says what
+it cannot run without — one `CaseNeed` or a list: `outage.findUsers` needs
+`['faults', 'findUsers']`, and is skipped for whichever is missing, `faults`
+named first.
 
 ### Without a test runner
 

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) |
@@ -179,6 +180,7 @@ In the one-type form these are on `auth` itself; with several types, on
 | --- | --- | --- |
 | `create(fields & { password?, active? })` | the user; no session | `USER_INVALID`, `PASSWORD_TOO_SHORT`, `LOGIN_TAKEN` |
 | `find(id)` | the user, or `null` — for a malformed id, an unknown one, or one of another type | |
+| `findMany(ids)` | the users, in the order of `ids`, each once; an id `find` answers `null` for is left out — see [below](#several-users-at-once--findmany) | |
 | `get(id)` | the user | `NOT_FOUND` |
 | `list({ after?, limit? })` | `CursorPage<User>`, in creation order | `INVALID_CURSOR` |
 | `update(user, patch, { ifVersion? })` | the user as written; sends `user.emailChanged` when the e-mail changed | `USER_INVALID`, `LOGIN_TAKEN`, `VERSION_CONFLICT`, `NOT_FOUND` |
@@ -248,6 +250,53 @@ idempotent: calling it again finishes the job. When it deleted the user, it
 sends a [`user.deleted` event](events.md) — once, after the sessions, tokens and relation tuples are gone, and even when an outage interrupts removing them;
 `create` and `signUp` send `user.created`.
 
+### Several users at once — `findMany`
+
+A list of rows that each name a user — a staff list showing every member's
+account state — reads them in one call, not one `find` per row:
+
+```ts
+const rows = await db.staffRows();                       // your own table, 100 rows
+const members = await clinic.staff.findMany(rows.map((row) => row.staffId));
+const byId = new Map(members.map((member) => [member.id, member]));
+
+const shown = rows.map((row) => {
+	const member = byId.get(row.staffId);                // undefined: nobody holds this id
+	return { ...row, active: member?.active ?? false, verified: member?.emailVerified ?? false };
+});
+```
+
+- **Order**: the order of `ids`. A repeated id is answered once, at its first
+  place.
+- **Absence**: an id `find` would answer `null` for — malformed, unknown, or
+  held by a user of another type — is **left out**, never an error. The answer
+  may be shorter than `ids`, so match by `user.id`, never by position.
+- **Empty**: `[]`, or a list with no well-formed id, answers `[]` without
+  reaching the store.
+- **Size**: any length. The store is asked 100 ids at a time, one batch after
+  another, so no query grows with your list.
+- **Failure**: `STORE_FAILED`, never a shorter list. Something other than an
+  array is a bare `TypeError`: only your code passes one.
+- **Cost**: one query per 100 ids when the users store implements the
+  optional `findUsers` — the reference store, `@nxgt/janus-drizzle` and
+  `@nxgt/janus-mongo` do. A store that does not is read with `findUser`,
+  **ten at a time**, so a third-party adapter keeps working and never opens
+  more than ten reads at once for one call; see
+  [writing an adapter](adapters.md#userstorefindusers-optional).
+
+**A GraphQL resolver per row** can batch through a DataLoader of your own —
+`@nxgt/janus-graphql` loads no users itself:
+
+```ts
+import DataLoader from 'dataloader';
+
+// One per request, so nothing is cached across users' requests.
+const staffById = new DataLoader(async (ids: readonly string[]) => {
+	const found = new Map((await clinic.staff.findMany(ids)).map((u) => [u.id, u]));
+	return ids.map((id) => found.get(id) ?? null);
+});
+```
+
 ### Paging every user
 
 ```ts