@nxgt/janus 0.12.0 → 0.14.0

package/dist/permissions/index.js

@@ -4,15 +4,15 @@ import {
   UNSTORABLE,
   MAX_PAGE_SIZE2,
   pageLimit2
-} from "../chunks/index-jp2kka6d.js";
+} from "../chunks/index-kj3st57z.js";
 import {
   PermissionDepthError2,
   isSetOf2,
   formatEntity2
-} from "../chunks/index-j2gd8fry.js";
+} from "../chunks/index-hnwggyxs.js";
 import {
   createMemoryRelations2
-} from "../chunks/index-km7ffctx.js";
+} from "../chunks/index-6c9fbtv2.js";
 
 // src/permissions/resolve/resolved.ts
 function admits(holders, subject) {

package/docs/README.md

@@ -17,8 +17,8 @@ below are defined once, in [Words](guide/vocabulary.md#words).
 | [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 |
 | [Step-up](guide/step-up.md) | A sensitive action — changing the e-mail, disabling the second factor, deleting the account — should ask a signed-in user to prove again who they are: `assertFresh`, `stepUp.request` and `confirm`, by e-mailed code or by their app |
-| [User events](guide/events.md) | You want to hear when a user is created, verifies their e-mail, resets their password, turns the second factor on or off, uses a recovery code or is deleted — to queue it, sync it, or send it as a webhook |
-| [Password hashing](guide/passwords.md) | You are choosing a hasher, raising its cost, moving to argon2id, or importing hashes from another system |
+| [User events](guide/events.md) | You want to hear when a user is created, verifies their e-mail, resets or changes their password, changes their e-mail, turns the second factor on or off, uses a recovery code or is deleted — to queue it, sync it, or send it as a webhook |
+| [Password hashing](guide/passwords.md) | You are choosing a hasher, raising its cost, moving to argon2id, or importing hashes from another system — or how `signIn` throttles password guessing per login, and what you still limit per client |
 
 ### Permissions — `@nxgt/janus/permissions`
 

package/docs/guide/adapters.md

@@ -282,8 +282,9 @@ driver's error in `StoreFailure` as in [the six rules](#the-six-rules):
 Spends every **unspent** token of one user and one `kind` at `at` — but the
 one whose hash is `except`, when given — and answers how many it spent. The
 core calls it right after issuing a sign-in code, with that code's hash as
-`except`, so only the last code sent works; and after writing a password,
-for the user's `secondFactor` challenges:
+`except`, so only the last code sent works — and so after issuing a step-up
+or a reset link; and after writing a password, for the user's
+`resetPassword` links and `secondFactor` challenges:
 
 | The stored token | Written | Counted |
 | --- | --- | --- |

package/docs/guide/email-flows.md

@@ -144,6 +144,45 @@ export async function forgotPassword(request: Request): Promise<Response> {
 }
 ```
 
+**At most one reset link is live per user.** A `request` issues its link,
+then spends every other reset link of the user, so the link in an earlier
+e-mail answers `TOKEN_SPENT` — only the last one works, as for [sign-in
+codes](sign-in-code.md):
+
+```ts
+const first = await auth.resetPassword.request(email);
+const second = await auth.resetPassword.request(email); // the visitor asked again
+if (first !== null && second !== null) {
+	await auth.resetPassword.confirm(first.token, newPassword);  // TOKEN_SPENT
+	await auth.resetPassword.confirm(second.token, newPassword); // reset
+}
+```
+
+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.
+
+**Writing a password spends every reset link still live.** A `confirm`,
+`changePassword` and `setPassword` each do, so a link sent before the
+password changed cannot replace it again:
+
+```ts
+const issued = await auth.resetPassword.request(email);
+await auth.changePassword(user, { current, next });
+if (issued !== null) {
+	await auth.resetPassword.confirm(issued.token, other); // TOKEN_SPENT
+}
+```
+
+The links are spent **after** the password is written, so a link issued
+during the write is spent too. If the store fails at that step, the call
+rejects with `STORE_FAILED` although the password is written — answer 503 as
+usual — and the older links may still be live until the next `request`,
+which spends them. Sign-in codes and step-ups are not spent: the password
+proves neither.
+
 `confirm` sets the password, marks the e-mail verified — the link proved it —
 and **signs the user out everywhere**: their sessions are revoked, and every
 second-factor challenge still open is spent, so a sign-in started with the
@@ -183,7 +222,7 @@ export async function resetPassword(request: Request): Promise<Response> {
 | Code | When |
 | --- | --- |
 | `TOKEN_UNKNOWN` | No token holds that secret — or it was issued for the other flow: a verification token is not a reset token |
-| `TOKEN_SPENT` | Already redeemed. Every token is single use |
+| `TOKEN_SPENT` | Already redeemed — every token is single use. A reset link is also spent by a newer `request` for the same user, and by any password written since it was sent |
 | `TOKEN_EXPIRED` | Its lifespan passed. It is spent all the same, so it cannot be retried |
 | `TOKEN_STALE` | Sent to an e-mail the user no longer has |
 

package/docs/guide/errors.md

@@ -54,7 +54,7 @@ that wired the library, so no handler needs to tell it apart.
 | `VERSION_CONFLICT` | `StoreConflict` (`on: 'version'`) | 409 | `ifVersion` no longer matches; nothing was written. From `secondFactor.confirm` or `recover`, the same code used by two sign-ins at once: the other opened the session | `expectedVersion`, `actualVersion` |
 | `USER_INVALID` | `UserInvalidError` | 400 | The fields failed the schema | `issues`, field by field |
 | `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** | `reason`, for your logs only |
+| `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 |
 | `USER_INACTIVE` | `UserInactiveError` | 403 | Deactivated; told only to someone who gave the right password, or the right code | `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` |
@@ -81,7 +81,11 @@ async function signIn(email: string, password: string): Promise<Response> {
 		return Response.json({ token });
 	} catch (error) {
 		if (error instanceof CredentialError && error.code === 'CREDENTIALS_INVALID') {
-			console.warn('sign-in refused', error.reason); // 'unknownLogin' | 'noPassword' | 'wrongPassword'
+			console.warn('sign-in refused', error.reason); // 'unknownLogin' | 'noPassword' | 'wrongPassword' | 'throttled'
+			if (error.retryAfter !== undefined) {
+				const headers = { 'retry-after': String(error.retryAfter) };
+				return Response.json({ error: 'invalid', retryAfter: error.retryAfter }, { status: 401, headers });
+			}
 			return Response.json({ error: 'invalid' }, { status: 401 });
 		}
 		if (error instanceof StoreFailure) return new Response(null, { status: 503 });
@@ -96,6 +100,10 @@ async function signIn(email: string, password: string): Promise<Response> {
   would read as "no".
 - **`VERSION_CONFLICT` is a retry**: read the user again, reapply, write with
   the new `version`.
+- **`CREDENTIALS_INVALID`'s `retryAfter`** belongs in the body and a
+  `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.
 - **`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/events.md

@@ -1,8 +1,8 @@
 # User events
 
 This page is for hearing what happens to a user once it is written: created,
-e-mail verified, password reset, second factor turned on or off, recovery
-codes regenerated or one used, deleted. Another service can then follow
+e-mail verified, password reset or changed, e-mail changed, second factor
+turned on or off, recovery codes regenerated or one used, deleted. Another service can then follow
 without polling. `janus` hands each event to one function you give it;
 **delivering it is yours** — or
 [`@nxgt/janus-webhooks`](https://www.npmjs.com/package/@nxgt/janus-webhooks)'s:
@@ -38,13 +38,15 @@ received[0];
 The words — **user event**, **listener** — are defined in
 [the vocabulary](vocabulary.md#identities).
 
-## The eight types
+## The ten types
 
 | `type` | Sent by | Not sent |
 | --- | --- | --- |
 | `user.created` | `create`, `signUp` — once the user is inserted, even if `signUp`'s session then fails to open | for a sign-up refused (`LOGIN_TAKEN`, `USER_INVALID`, `PASSWORD_TOO_SHORT`) |
 | `user.emailVerified` | `verifyEmail.confirm`; `resetPassword.confirm`, whose link proves the e-mail; `signInCode.confirm`, whose code does | for an e-mail already verified, or a refused confirm |
 | `user.passwordReset` | `resetPassword.confirm` | for `setPassword` or `changePassword` — they are not resets |
+| `user.passwordChanged` | `changePassword` and `setPassword` — a first password set on a user created without one included — once the password is written — even if spending the reset links and second-factor challenges it ends then fails | for a reset, which is `user.passwordReset` alone; for a `changePassword` refused (`CREDENTIALS_INVALID`) |
+| `user.emailChanged` | `update`, when it changed the e-mail — added, replaced or removed. It carries `formerEmail`, the address before | for an update that leaves the e-mail alone, or changes only its case (`Ada@…` for `ada@…`): compared normalised, the same test that makes the new address unverified; for a type with no e-mail; for an update refused |
 | `user.secondFactorEnabled` | `secondFactor.activate`, once the first code made the factor active | for `enroll`, which leaves the factor waiting and asked for nowhere; for a code refused |
 | `user.secondFactorDisabled` | `secondFactor.disable`, when it removed an **active** factor | for a user who had no factor, a factor still waiting for its first code — it was never asked for — or a second `disable` |
 | `user.recoveryCodesRegenerated` | `secondFactor.regenerateRecoveryCodes`: the codes the user held stopped working | for `activate`, whose first codes come with `user.secondFactorEnabled`; for a code refused |
@@ -52,9 +54,13 @@ The words — **user event**, **listener** — are defined in
 | `user.deleted` | `delete`, when it deleted the user | for a replay that finds nobody, or an id of another user type |
 
 A reset whose link verifies the e-mail sends both, `user.passwordReset`
-first. Switch on `type`: the eight are a closed set, and TypeScript refuses a
-ninth. A new type is a compile error in a `switch` that exhausts them — the two
-recovery-code types, added in 0.10, broke such a `switch` until it handled them.
+first. **A reset does not also send `user.passwordChanged`**: a listener that
+cares about every new password handles both types, as the `switch` below
+does — one event per write, rather than two a listener would have to tell
+apart. Switch on `type`: the ten are a closed set, and TypeScript refuses an
+eleventh. A new type is a compile error in a `switch` that exhausts them — the
+two recovery-code types, added in 0.10, and the two change types, added in
+0.14, each broke such a `switch` until it handled them.
 
 ```ts
 function onUserEvent(event: UserEvent): void {
@@ -64,7 +70,10 @@ function onUserEvent(event: UserEvent): void {
 		case 'user.emailVerified':
 			return unlockFeatures(event.userId);
 		case 'user.passwordReset':
-			return alertSecurityTeam(event.userId);
+		case 'user.passwordChanged':
+			return noticeTheUser(event); // @nxgt/janus-mail's passwordChanged — see below
+		case 'user.emailChanged':
+			return noticeTheFormerAddress(event); // to event.formerEmail — see below
 		case 'user.secondFactorEnabled':
 		case 'user.secondFactorDisabled':
 			return noticeTheUser(event); // @nxgt/janus-mail's twoFactorEnabled or twoFactorDisabled
@@ -114,14 +123,59 @@ With several user types, the count is the type's:
 `auth.patient.secondFactor.recoveryCodesLeft(event.userId)`, on
 `event.userType`.
 
+### Telling the user their password or e-mail changed
+
+A password changed by someone else, or an e-mail moved to their inbox, is how
+an account is taken over — so tell the user each time. For a password, read
+the user and write to their address. For an e-mail, write to the **former**
+address: the new one belongs to whoever changed it. The event carries it,
+since nothing else keeps it once the write landed:
+
+```ts
+// `mail` is janusMail({ … }), and the user schema holds a name and a locale.
+const auth = janus({
+	...config,
+	async events(event) {
+		if (event.type === 'user.passwordChanged') {
+			const user = await auth.get(event.userId);
+			await mail.passwordChanged({ name: user.name, locale: user.locale, email: user.email });
+		}
+		if (event.type === 'user.emailChanged' && event.formerEmail != null) {
+			const user = await auth.get(event.userId);
+			await mail.emailChanged({
+				name: user.name,
+				locale: user.locale,
+				formerEmail: event.formerEmail, // to the inbox the account just left
+				newEmail: user.email,
+			});
+		}
+	},
+});
+```
+
+`formerEmail` is `null` for a user who had no e-mail before the update:
+there is no former inbox to tell. The example assumes a required e-mail; with
+an optional one, an update that removes it sends the event too, and the user
+read back has no `newEmail` to name — check `user.email` before the notice. Pass the same notices on `user.passwordReset`
+too, if a reset should be told as well.
+
 ## What an event carries
 
-**The user named by id, and nothing else.** No login, no e-mail, no field of
-the schema, no password or hash, no session or one-time token. An event can
+**The user named by id, and nothing else** — with one exception, below. No
+login, no field of the schema, no password or hash, no session or one-time
+token. An event can
 land in a queue, a log or another company's endpoint; whoever receives it
 reads the rest from where it is kept — `auth.get(event.userId)` — if they
 may. A user deleted since is `NOT_FOUND` there, which is the answer.
 
+**The exception is `formerEmail`, on `user.emailChanged` only**: the address
+the user had before the update, as it was stored, or `null` when they had
+none. Once the write landed it is kept nowhere else, and a notice to the
+inbox the account just left needs it. It is absent from every other type.
+`@nxgt/janus-webhooks` does not carry it: it strips it before the queue, so
+it reaches no endpoint, no queue and no `onGivingUp` report — send the
+notice from the listener, in the process that wrote.
+
 `id` is minted for the event, a UUIDv7 that sorts by time. Deliver on it:
 a queue job id, a primary key, a webhook's `webhook-id` header. Two events
 never share one.
@@ -148,15 +202,18 @@ Where the listener runs within a flow, and what an outage does to it:
 | `create` | after the insert — its last step | — |
 | `signUp` | after the insert, **before** the session is opened | fails the call; the event is already sent |
 | `verifyEmail.confirm` | after the write — the flow's last step | — |
+| `update` | after the write — the flow's last step | — |
+| `changePassword`, `setPassword` | **after** the reset links and the second-factor challenges left open are spent | fails the call; the event is sent all the same, from a `finally` |
 | `signInCode.confirm` | after the write, **before** the session or the second-factor challenge is opened | fails the call; the event is already sent |
 | `secondFactor.activate`, `secondFactor.regenerateRecoveryCodes`, `secondFactor.disable` | after the write — the flow's last step | — |
 | `secondFactor.recover` | after the recovery code is spent and the session opened — or failed to open | fails the call; the recovery code is spent and the event sent all the same, from a `finally` |
-| `resetPassword.confirm` | **after** the sessions opened with the old password are revoked and the second-factor challenges left open are spent | fails the call; the events are sent all the same, from a `finally` |
+| `resetPassword.confirm` | **after** the sessions opened with the old password are revoked, and the other reset links and the second-factor challenges left open are spent | fails the call; the events are sent all the same, from a `finally` |
 | `delete` | **after** the user's sessions and one-time tokens are removed, and the relation tuples naming them when `relations` is wired | fails the call; the event is sent all the same, from a `finally` |
 
 So a listener that takes its time never leaves an old session alive after a
-reset, and one that checks permissions on `user.deleted` finds the tuples
-gone. A retry could not send a lost event either way: `delete` then finds
+reset, one that hears of a password changed finds the older reset links
+already spent, and one that checks permissions on `user.deleted` finds the
+tuples gone. A retry could not send a lost event either way: `delete` then finds
 nobody, and the reset link is spent.
 
 `occurredAt` is the write's own time: the `createdAt` or `updatedAt` it
@@ -231,6 +288,8 @@ type UserEventType =
 	| 'user.created'
 	| 'user.emailVerified'
 	| 'user.passwordReset'
+	| 'user.passwordChanged'
+	| 'user.emailChanged'
 	| 'user.secondFactorEnabled'
 	| 'user.secondFactorDisabled'
 	| 'user.recoveryCodesRegenerated'
@@ -243,6 +302,7 @@ interface UserEvent {
 	readonly occurredAt: Date; // when the write landed: the createdAt or updatedAt written, or the time read just before a deletion
 	readonly userId: Id;
 	readonly userType: string;
+	readonly formerEmail?: string | null; // on user.emailChanged only: the address before, null for none
 }
 
 type UserEventListener = (event: UserEvent) => void | Promise<void>;
@@ -257,5 +317,6 @@ see [troubleshooting](../troubleshooting.md#janus-events-must-be-a-function-that
 
 - [E-mail verification and password reset](email-flows.md) — the flows that send `user.emailVerified` and `user.passwordReset`
 - [The second factor](second-factor.md) — `activate` and `disable`, which send `user.secondFactorEnabled` and `user.secondFactorDisabled`; [recovery codes](second-factor.md#recovery-codes), which send `user.recoveryCodesRegenerated` and `user.recoveryCodeUsed`
-- [Users](users.md) — `create`, `signUp`, `delete`
+- [Users](users.md) — `create`, `signUp`, `update`, `delete`
+- [Passwords](passwords.md) — `changePassword` and `setPassword`, which send `user.passwordChanged`
 - [Troubleshooting](../troubleshooting.md) — `JANUS_EVENT_FAILED`

package/docs/guide/passwords.md

@@ -1,7 +1,8 @@
 # Password hashing
 
-This page is for choosing a password hasher, moving from one to another, and
-importing hashes written by another system. The login and the length policy
+This page is for choosing a password hasher, moving from one to another,
+importing hashes written by another system, and how `signIn` throttles
+password guessing. The login and the length policy
 are on the [users](users.md#options) page.
 
 ```ts
@@ -122,6 +123,125 @@ Write each imported user's hash as their `PasswordRecord` with your store's
 scrypt the first time they sign in. Wire one verifier
 per prefix the old system wrote (`$2a$`, `$2b$`, `$2y$` for bcrypt).
 
+## Password guessing is throttled
+
+**`signIn` counts the passwords tried at each login, and past ten in a
+15-minute window it refuses every one — the right password included — until
+the window ends.** On by default. The refusal is the same `CREDENTIALS_INVALID`
+as a wrong password, with `reason: 'throttled'` for your logs and
+`retryAfter`, the seconds until the next window, for the client:
+
+```ts
+import { JanusError } from '@nxgt/janus';
+
+try {
+	return await auth.signIn({ email, password });
+} catch (error) {
+	if (error instanceof JanusError && error.code === 'CREDENTIALS_INVALID') {
+		const headers = error.retryAfter === undefined
+			? undefined
+			: { 'retry-after': String(error.retryAfter) };
+		return Response.json({ code: error.code, retryAfter: error.retryAfter }, { status: 401, headers });
+	}
+	throw error;
+}
+```
+
+[`janusErrors()`](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus-hono/docs/guide/routes.md#sign-up-and-sign-in) in
+`@nxgt/janus-hono` and `janusGraphQLError()` in `@nxgt/janus-graphql` do this
+for you, `Retry-After` header included.
+
+What it does, precisely:
+
+- **Nothing locks.** The next window signs in: no number of wrong
+  passwords blocks an account beyond its window. **But the right password is
+  refused while the login is throttled**, so somebody who knows only a login
+  can keep its password sign-in shut by trying ten passwords every window.
+  That is the price of counting per login; limit per client address (below),
+  and a [sign-in code](sign-in-code.md), when you wire them, still opens
+  the account.
+- **Per login, known or not.** A login nobody holds is counted as a
+  registered one is — `unknownLogin` ten times, then `throttled` — so the
+  throttle does not say which logins exist; an unknown login is still
+  compared against a dummy hash, as before. The login is counted as
+  [`password.normalize`](users.md#passwordnormalize) writes it, within its
+  user type: `ADA@example.test` and `ada@example.test` share one count.
+- **Counted before anything is compared**, by the store, in one write per
+  attempt: of twenty passwords tried at once, exactly ten are compared. A
+  throttled attempt compares nothing, so it costs no hashing either.
+- **A sign-in that opens a session starts the count again** for that
+  login: the right password of an active user — and, with a second factor
+  active, only once its code or a recovery code opens the session. A
+  password that only opens a challenge restarts nothing, so knowing the
+  password buys no more than ten challenges per window.
+- **The windows are fixed slices of the clock**, not sliding: ten attempts
+  at the end of one window and ten at the start of the next are allowed.
+
+Change the limit or the window, or turn it off — `SignInConfig` and
+`SignInThrottleConfig` are the option's types, for a wrapper of your own:
+
+```ts
+janus({ ..., signIn: { throttle: { attempts: 5, window: '1h' } } });
+janus({ ..., signIn: { throttle: false } }); // counts nothing: limit signIn yourself
+```
+
+### Where the counts live
+
+In the tokens store, as `secondFactor` tokens that belong to no user: the
+store needs no new method, and an adapter that passes the conformance suite
+counts correctly. Each is named by a keyed hash of the login, never the login
+— keyed by your `secondFactor` keys when you wire them, and by a fixed key
+otherwise, which only keeps the login out of plain sight: a dump of the
+tokens then tells which logins were tried, for a guessed list. Each expires
+two windows after its window starts — half an hour by default — **Redis and MongoDB drop it then;
+PostgreSQL keeps it** until something deletes it, and every login tried,
+registered or not, adds a row per window. Schedule a delete with
+`@nxgt/janus-drizzle`:
+
+```sql
+delete from tokens where expires_at < now() - interval '1 hour'; -- janus.tokens when your tables have a schema of their own
+```
+
+`tokens` has no index on `expires_at`, so the delete scans the table: add
+`create index on tokens (expires_at)` in a migration of yours if it grows.
+
+The key is your first `secondFactor` key: wiring
+`secondFactor` for the first time, or putting a new key first, starts every
+login's count again. **A Redis tokens store that is flushed, or evicts keys under
+memory pressure, forgets them** and every count starts again: give Redis
+`maxmemory-policy noeviction` (see `@nxgt/janus-redis`).
+
+### When the store cannot count
+
+`signIn` throws `STORE_FAILED` — answer 503. It never answers a refusal the
+visitor could not have caused, and never lets a password through uncounted:
+**the throttle fails closed**, so a tokens-store outage stops password
+sign-ins as a users-store outage would. A sign-in whose password was right and
+whose count could not start again also throws `STORE_FAILED`, before any
+session is opened.
+
+The store's round-trips are observable, as its latency is: a login that
+signed in this window costs a few more probes than one nobody holds.
+
+### What you still limit yourself
+
+The throttle counts per login. It does not see:
+
+- **One password tried against many logins** (password spraying), nor many
+  logins from one client: limit `signIn` **per client address** in front of
+  the call, with the limiter you already run.
+- `changePassword`, which compares the current password too: limit it per
+  user.
+- `resetPassword.request` and `signInCode.request`, which send e-mail: limit
+  them per address.
+
+```ts
+if (!(await limiter.consume(`sign-in:${clientAddress}`))) {
+	return new Response(null, { status: 429, headers: { 'retry-after': '900' } });
+}
+const signedIn = await auth.signIn({ email, password });
+```
+
 ## What never happens
 
 - The plain password is never stored, and never appears in an error message.
@@ -133,4 +253,4 @@ per prefix the old system wrote (`$2a$`, `$2b$`, `$2y$` for bcrypt).
 ## See also
 
 - [Users](users.md) — `signIn`, `setPassword`, `changePassword`
-- [Errors](errors.md) — `CREDENTIALS_INVALID` and its `reason`
+- [Errors](errors.md) — `CREDENTIALS_INVALID`, its `reason` and `retryAfter`

package/docs/guide/second-factor.md

@@ -306,8 +306,10 @@ try {
 ```
 
 Five attempts at a million values is a one-in-200,000 chance per password
-guessed right. A new challenge takes a new sign-in, with the password, so the
-attempts are bounded by your sign-in rate limit too.
+guessed right. A new challenge takes a new sign-in, with the password, and
+`signIn`'s throttle allows ten per login per 15-minute window — so the
+password alone buys at most ten challenges a window; a limit per client is
+yours to add.
 
 A call made through **another user type's** API — `auth.staff.secondFactor.confirm`
 for a patient's challenge — answers `TOKEN_UNKNOWN` and compares nothing, but

package/docs/guide/users.md

@@ -96,6 +96,7 @@ that cuts an emoji in half, say.
 | `tokens.resetPassword` | `Duration` | `'1h'` | How long a reset token lives |
 | `tokens.signInCode` | `Duration` | `'10m'` | How long an e-mailed sign-in code and its challenge live. See [sign-in codes](sign-in-code.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) |
 | `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) |
 | `events` | `UserEventListener` | none | Called with every user event — `user.created`, `user.deleted`, … — after the write, awaited. See [user events](events.md) |
 
@@ -178,7 +179,7 @@ In the one-type form these are on `auth` itself; with several types, on
 | `find(id)` | the user, or `null` — for a malformed id, an unknown one, or one of another type | |
 | `get(id)` | the user | `NOT_FOUND` |
 | `list({ after?, limit? })` | `CursorPage<User>`, in creation order | `INVALID_CURSOR` |
-| `update(user, patch, { ifVersion? })` | the user as written | `USER_INVALID`, `LOGIN_TAKEN`, `VERSION_CONFLICT`, `NOT_FOUND` |
+| `update(user, patch, { ifVersion? })` | the user as written; sends `user.emailChanged` when the e-mail changed | `USER_INVALID`, `LOGIN_TAKEN`, `VERSION_CONFLICT`, `NOT_FOUND` |
 | `setActive(user, active, { ifVersion? })` | the user as written | `VERSION_CONFLICT`, `NOT_FOUND` |
 | `delete(user)` | `true`, or `false` for an unknown id or one of another type | |
 
@@ -187,16 +188,20 @@ With a `password`, besides:
 | Method | Answers | Rejects with |
 | --- | --- | --- |
 | `signUp(fields & { password })` | `{ status: 'signedIn', user, session, token }` | `USER_INVALID`, `PASSWORD_TOO_SHORT`, `LOGIN_TAKEN` |
-| `signIn({ [login]: string, password })` | `{ status: 'signedIn', user, session, token }` — or, with `secondFactor` configured and the user's factor active, `{ status: 'secondFactor', challenge, expiresAt, userId }`: switch on `status` | `CREDENTIALS_INVALID`, `USER_INACTIVE`, `HASH_UNSUPPORTED` |
+| `signIn({ [login]: string, password })` | `{ status: 'signedIn', user, session, token }` — or, with `secondFactor` configured and the user's factor active, `{ status: 'secondFactor', challenge, expiresAt, userId }`: switch on `status` | `CREDENTIALS_INVALID` — with `retryAfter` once the login is throttled — `USER_INACTIVE`, `HASH_UNSUPPORTED` |
 | `findByLogin(login)` | the user, or `null`; the login is normalised first, and one holding a NUL or a lone surrogate is nobody's | |
-| `setPassword(user, password, { ifVersion? })` | the user — an admin's call; spends the user's second-factor challenges still waiting, and signs nobody out | `PASSWORD_TOO_SHORT` |
-| `changePassword(user, { current, next }, { ifVersion? })` | the user — the user's own call; spends the user's second-factor challenges still waiting | `CREDENTIALS_INVALID`, `PASSWORD_TOO_SHORT` |
+| `setPassword(user, password, { ifVersion? })` | the user — an admin's call; spends the user's reset links and second-factor challenges still waiting, and signs nobody out; sends `user.passwordChanged` | `PASSWORD_TOO_SHORT` |
+| `changePassword(user, { current, next }, { ifVersion? })` | the user — the user's own call; spends the user's reset links and second-factor challenges still waiting; sends `user.passwordChanged` | `CREDENTIALS_INVALID`, `PASSWORD_TOO_SHORT` |
 
 With `secondFactor` configured, a type with a password also answers
 `secondFactor.enroll`, `activate`, `disable` and `confirm` — see
 [the second factor](second-factor.md).
 
-Every method may also reject with `STORE_FAILED`. A `user` argument is a user
+Every method may also reject with `STORE_FAILED`. `setPassword` and
+`changePassword` spend the user's reset links and second-factor challenges
+after the write, so a `STORE_FAILED` there may come with the password
+already written: a retried `changePassword` with the old `current` then
+answers `CREDENTIALS_INVALID`. A `user` argument is a user
 or its id (`UserRef = string | { id: string }`).
 
 ```ts
@@ -216,7 +221,11 @@ await auth.delete(renamed);                        // true
 The patch is spread over the stored fields and the result is checked against
 the schema, so a patch can never leave a user the schema would refuse.
 Changing the e-mail sets `emailVerified` back to `false`, and moves the login
-with it when the e-mail is the login.
+with it when the e-mail is the login. It also sends a
+[`user.emailChanged` event](events.md#telling-the-user-their-password-or-e-mail-changed)
+carrying `formerEmail`, the address before — so the notice goes to the inbox
+the account just left. A change of case only (`Ada@…` for `ada@…`) is no
+change, and sends nothing.
 
 ### `ifVersion`
 
@@ -289,6 +298,6 @@ fields against your schema, not that `password` is a string.
 ## See also
 
 - [Sessions](sessions.md) — `authenticate`, the cookie, signing out
-- [User events](events.md) — what `create`, `signUp` and `delete` send
+- [User events](events.md) — what `create`, `signUp`, `update`, `setPassword`, `changePassword` and `delete` send
 - [Errors](errors.md) — every code, and the status it deserves
 - [Writing an adapter](adapters.md) — the identity stores behind `store`

package/docs/guide/vocabulary.md

@@ -52,14 +52,14 @@ either finds this row.
 | **recovery code** | One of ten single-use codes `secondFactor.activate` and `secondFactor.regenerateRecoveryCodes` answer **once** — ten characters, shown `xxxxx-xxxxx` — that `secondFactor.recover` takes instead of a TOTP code, for a user whose authenticator app is gone. Stored only as keyed hashes. Always written in full: *code* alone is a one-time code, and a recovery code is never one | "backup code", "scratch code", "recovery key" |
 | **attempt** | One code tried against a challenge, counted by `countAttempt` in the token's `attempts` before the code is checked. A challenge takes five, a second factor's or a sign-in code's | "try"; "retry" is a repeated write, never a guess |
 | **challenge** | A secret the visitor keeps, redeemed once with a code — which is what *confirm* means for it. `signIn` answers one instead of a session when the user's second factor is active, for `secondFactor.confirm` — or `secondFactor.recover`, with a recovery code; `signInCode.request` answers one beside the sign-in code, for `signInCode.confirm`; `stepUp.request` answers one for `stepUp.confirm`. Stored as its hash, as a one-time token of kind `secondFactor`, `signInCode` or `stepUp`: five minutes or ten by default, and five attempts | "MFA token", "pending session", "ticket" |
-| **spent** | A one-time token or a challenge that can no longer be redeemed — `spentAt` set, `TOKEN_SPENT`, and never unset. Spent by its redemption, by its fifth attempt (a wrong code, or a call through another user type's API), by a redemption after it expired, by a refusal that ends it (`USER_INACTIVE`, `TOKEN_STALE`, `SECOND_FACTOR_NOT_ENROLLED`), or by what ends it early: the next `signInCode.request` or `stepUp.request` for the same user (at most one of each is live at a time), or a password written by `resetPassword.confirm`, `setPassword` or `changePassword` (every second-factor challenge left waiting) | "used up", "invalidated"; "consumed" only in `consumeToken`'s name; "revoked" is a session's |
+| **spent** | A one-time token or a challenge that can no longer be redeemed — `spentAt` set, `TOKEN_SPENT`, and never unset. Spent by its redemption, by its fifth attempt (a wrong code, or a call through another user type's API), by a redemption after it expired, by a refusal that ends it (`USER_INACTIVE`, `TOKEN_STALE`, `SECOND_FACTOR_NOT_ENROLLED`), or by what ends it early: the next `signInCode.request`, `stepUp.request` or `resetPassword.request` for the same user (at most one of each is live at a time), or a password written by `resetPassword.confirm`, `setPassword` or `changePassword` (every reset link and every second-factor challenge left waiting) | "used up", "invalidated"; "consumed" only in `consumeToken`'s name; "revoked" is a session's |
 | **step** | The thirty-second period a TOTP code belongs to. `lastStep` is the step of the last code accepted, and only a later step counts: that is why a code is accepted once | "window", "period", "counter", in prose |
 | **seal**, **sealing key** | To seal is to encrypt a TOTP secret — AES-256-GCM, bound to the user's id — before a store sees it. A sealing key is one `{ id, key }` of `secondFactor.keys`: the first seals, every one opens | "encrypt", "encryption key", "master key", "pepper" |
 | **token** | Never alone in prose: a *session token* or a *one-time token*. The `tokens` store and the `TOKEN_*` codes are one-time tokens only | |
 | **e-mail flow** | `verifyEmail` or `resetPassword`: send a one-time token, then confirm it. `signInCode` sends a one-time code instead | |
 | **issued** | What a flow answers for the application to send: an `IssuedToken` from `verifyEmail.send` or `resetPassword.request`, an `IssuedCode` from `signInCode.request` — the address with it. `@nxgt/janus-mail` takes it as it is | "result", "payload" |
 | **notice** | An e-mail that tells a user of a change and asks for nothing: *password changed*, *e-mail changed* — the latter sent to the former address — and *two-factor enabled*, *two-factor disabled*. `@nxgt/janus-mail` sends all four | "alert", "notification" |
-| **user event** | What happened to a user, once it is written: `user.created`, `user.emailVerified`, `user.passwordReset`, `user.secondFactorEnabled`, `user.secondFactorDisabled`, `user.recoveryCodesRegenerated`, `user.recoveryCodeUsed`, `user.deleted` — a `UserEvent`, naming the user by id alone, with an `id` of its own. See [user events](events.md) | "webhook" — a webhook is one way to deliver it; "event" alone where it could be read as `@nxgt/janus-telemetry`'s audit log record — on a page about user events, "the event" is fine |
+| **user event** | What happened to a user, once it is written: `user.created`, `user.emailVerified`, `user.passwordReset`, `user.passwordChanged`, `user.emailChanged`, `user.secondFactorEnabled`, `user.secondFactorDisabled`, `user.recoveryCodesRegenerated`, `user.recoveryCodeUsed`, `user.deleted` — a `UserEvent`, naming the user by id alone — `user.emailChanged` adds `formerEmail` — with an `id` of its own. See [user events](events.md) | "webhook" — a webhook is one way to deliver it; "event" alone where it could be read as `@nxgt/janus-telemetry`'s audit log record — on a page about user events, "the event" is fine |
 | **step-up**, **fresh** | A step-up is a signed-in user proving again who they are before a sensitive action — `stepUp.request`, then `stepUp.confirm`, with an e-mailed code or, when their second factor is active, their app's — which moves the session's `authenticatedAt` to now and opens no session. A session is **fresh** for `maxAge` after it proved who it is, at the sign-in or by a step-up; `assertFresh` refuses an older one with `STEP_UP_REQUIRED`. See [step-up](step-up.md) | "re-authentication", "sudo mode", "elevated session"; "recent sign-in" once a step-up counts too |
 | **listener** | The one function `janus({ events })` hands every user event to, after the write and awaited | "handler", "hook", "subscriber" |
 

package/docs/roadmap.md

@@ -13,6 +13,12 @@ Nothing yet.
 
 ## Later
 
+- **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
+  core do it.
+
 - **More official adapters** — the ports are cut where atomicity is not
   required, so users, sessions and permission tuples can each live in the
   database that suits them. MongoDB is the first adapter
@@ -46,6 +52,9 @@ Nothing yet.
   Valibot, ArkType); none is imposed as a peer.
 - **A silent hasher fallback** — a user type with a password and no `hasher`
   is refused at wiring, rather than hashed with something you did not choose.
+- **An account lockout** — a login past its attempts waits for the next
+  window, and no number of wrong passwords blocks an account for longer:
+  a lockout would let anyone lock anyone out.
 - **Answering `null` or `false` on an outage** — a store that cannot answer
   throws `STORE_FAILED`, and a permission walk past `maxDepth` throws
   `PERMISSION_DEPTH`. Neither will become a denial: that turns an outage into
@@ -61,6 +70,31 @@ Nothing yet.
 The last ten, newest first, each with the version it came in. Everything
 before is in the [CHANGELOG](../CHANGELOG.md).
 
+- **Password guessing throttled per login, v0.14.0** — past ten passwords
+  tried at one login in a 15-minute window, `signIn` answers
+  `CREDENTIALS_INVALID` with `reason: 'throttled'` and `retryAfter`, the right
+  password included, until the window ends. Nothing locks; a login nobody
+  holds is counted alike; a password sign-in that opens a session —
+  after its second factor, when one is active — starts the count again.
+  On by default: `signIn: { throttle: { attempts, window } }` changes it,
+  `signIn: { throttle: false }` turns it off. A tokens store that cannot
+  count fails the sign-in with `STORE_FAILED`. No change for adapters: the
+  counts are `secondFactor` tokens, counted by `TokenStore.countAttempt`.
+- **A password or an e-mail changed, in the user events, v0.14.0** —
+  `user.passwordChanged`, sent by `changePassword` and `setPassword` once the
+  older reset links are spent (a reset stays `user.passwordReset` alone), and
+  `user.emailChanged`, sent by an `update` that changed the e-mail, carrying
+  `formerEmail` — the one event with more than the user's id — so a notice
+  can reach the inbox the account just left, as `@nxgt/janus-mail`'s
+  `passwordChanged` and `emailChanged` notices do. Breaking for a `switch`
+  that exhausts `UserEventType`.
+- **An old reset link stops working, v0.13.0** — `resetPassword.request`
+  spends the links sent before, so only the last e-mail's works, and writing
+  a password — a link's `confirm`, `changePassword`, `setPassword` — spends
+  every reset link still live, so a link sent before the change cannot
+  replace the new password. Both answer `TOKEN_SPENT`; an outage spending
+  them fails the call with `STORE_FAILED`. No change for adapters: the
+  existing `TokenStore.spendUserTokens` does it.
 - **Confirm an action with a code (step-up), v0.12.0** —
   `auth.stepUp.request(user)` and `stepUp.confirm(request, challenge, code)`:
   a signed-in user proves again who they are before a sensitive action, with
@@ -120,29 +154,3 @@ before is in the [CHANGELOG](../CHANGELOG.md).
   Webhooks specification (HMAC-SHA256, secrets that rotate) and posted to
   your endpoints, retried with backoff, and reported to `onGivingUp` when
   given up — never dropped in silence. `verifyWebhook` is the receiving side.
-- **User events, v0.8.0** — `janus({ events })` takes one listener, called
-  with `user.created`, `user.emailVerified`, `user.passwordReset` and
-  `user.deleted` once the write landed, and awaited before the flow answers.
-  An event names the user by id alone, with a UUIDv7 of its own to deliver
-  it once; a listener that throws fails no flow and is a
-  `JANUS_EVENT_FAILED` warning.
-- **At most one sign-in code live per user, and challenges that end when
-  they should, v0.7.0** — `signInCode.request` spends the codes sent before,
-  even when requests race, so only the last e-mail's works; writing a
-  password spends the second-factor challenges left waiting, and a sign-in
-  still running when it lands is refused; another user type's `confirm` spends a challenge
-  at its fifth attempt; `verifyEmail.confirm` and `resetPassword.confirm`
-  check the e-mail again on the record they write. `SecondFactorRequired`
-  carries `userId`, for logs and rate limits. For adapters:
-  `TokenStore.spendUserTokens(userId, kind, at, except?)`, with four new conformance
-  cases, implemented in `@nxgt/janus-drizzle`, `@nxgt/janus-mongo` and
-  `@nxgt/janus-redis` — and the port now says a read sees every write that
-  completed before it: never a secondary or a read replica.
-- **Sign in with a code sent by e-mail, v0.6.0** —
-  `auth.<type>.signInCode.request(email)` answers a six-digit code to send
-  and a challenge to keep with the visitor, or `null` for nobody — never
-  saying which; `signInCode.confirm(challenge, code)` marks the e-mail
-  verified and opens the session. On every user type with an e-mail, one
-  without a password included; an active second factor is still asked for.
-  A challenge lives ten minutes (`tokens.signInCode`) and takes five
-  attempts, and only the code's hash is stored, keyed by the challenge.