@nxgt/janus 0.25.0 → 0.27.0

package/docs/README.md

@@ -20,7 +20,7 @@ below are defined once, in [Words](guide/vocabulary.md#words).
 | [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 |
 | [Devices](guide/devices.md) | You want to tell a user their account was signed in from a new device: wiring `devices`, the `device` each sign-in takes, the device cookie, the second factor, the notice by e-mail, rotating the keys and forgetting devices |
 | [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, signs in from a new device 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 |
+| [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` and `changePassword` throttle password guessing per login, and what you still limit per client |
 
 ### Permissions — `@nxgt/janus/permissions`
 

package/docs/guide/email-flows.md

@@ -265,6 +265,20 @@ is no longer the one it was asked from although nothing spent it: a write
 outside janus, or a `send` racing an `update`. `confirm` sends `user.emailChanged` (with
 `formerEmail`) and `user.emailVerified`.
 
+**With several user types**, a type's own `confirm` answers `TOKEN_UNKNOWN`
+for a token issued to another type's user, and spends it — a later
+confirmation through the right type is then `TOKEN_SPENT`. A page that does
+not know the type calls the root's `confirm`, which reads the user the token
+was issued to and confirms as their type does: same move, same events, same
+errors, and `type` in the answer says which type it was. `send` stays on each
+type. The root's exists when one type has an e-mail, which is why no type may
+be named `changeEmail`.
+
+```ts
+// one anonymous page for every type
+const changed = await auth.changeEmail.confirm(token); // changed.type: 'admin' | 'member'
+```
+
 **Gate `send`, and tell the former address.** Whoever changes the e-mail
 takes over every reset: call `send` behind a fresh sign-in or a step-up.
 

package/docs/guide/passwords.md

@@ -175,6 +175,14 @@ What it does, precisely:
   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.
+- **`changePassword` counts in the same budget.** Each call is one more
+  password tried at the user's login, counted before `current` is compared
+  (a user with no password too, so the answer does not tell them apart), so
+  a caller holding a session cannot guess current passwords without limit.
+  Past the limit it answers `CREDENTIALS_INVALID` with `reason: 'throttled'`
+  and `retryAfter`, the right `current` included, and writes nothing. One
+  budget per account: wrong guesses at `signIn` and at `changePassword` add
+  up, and a change that is written starts the count again.
 - **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.
 
@@ -228,8 +236,6 @@ 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`, `signInCode.request` and `magicLink.request`,
   which send e-mail — and their `prepare`: [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.

package/docs/guide/users.md

@@ -97,7 +97,7 @@ that cuts an emoji in half, say.
 | `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.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) |
+| `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; `changePassword`'s wrong current passwords count in the same budget. `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`, and `changeEmail.send`, which counts the new address too) 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) |
@@ -168,7 +168,7 @@ and `schemaVersion`, with the defaults above. A login is unique **per type**:
 the same e-mail may hold a patient user and a staff user. A type name is
 camelCase, and may not be one of `janus()`'s own methods (`authenticate`,
 `signOut`, `signOutEverywhere`, `findUser`, `getUser`, `cookie`,
-`collectExpired`, `types`) — a compile error, and a `TypeError` for a
+`collectExpired`, `types`, `changeEmail`) — a compile error, and a `TypeError` for a
 JavaScript caller.
 
 ## What each user type answers
@@ -196,7 +196,7 @@ With a `password`, besides:
 | `signIn({ [login]: string, password }, { device? })` | `{ status: 'signedIn', user, session, token, newDevice, deviceToken }` — 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 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` |
+| `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` (`throttled` past the [sign-in throttle](passwords.md#password-guessing-is-throttled), which it counts in), `PASSWORD_TOO_SHORT` |
 
 With an e-mail — the field `email` names, password or not — besides:
 

package/docs/roadmap.md

@@ -69,6 +69,17 @@ Nothing yet.
 The last ten, newest first, each with the version it came in. Everything
 before is in the [CHANGELOG](../CHANGELOG.md).
 
+- **`changePassword` counts in the sign-in throttle, v0.27.0** — each call is
+  one more password tried at the user's login, in the budget `signIn` counts
+  in: past the limit it answers `CREDENTIALS_INVALID` with `reason:
+  'throttled'` and `retryAfter`, the right current password included, and a
+  change that is written restarts the count.
+- **Root `changeEmail.confirm` for instances with several user types, v0.26.0** —
+  `auth.changeEmail.confirm(token)` confirms a change of e-mail for a page that
+  does not know the user's type: it reads the user the link was issued to and
+  confirms as their type does. A type's own `confirm` still answers
+  `TOKEN_UNKNOWN`, and spends the token, for another type's link; no user type
+  may be named `changeEmail`.
 - **Collecting lapsed one-time tokens, v0.25.0** — `collectExpired()` deletes
   lapsed sessions and, through a new optional `TokenStore.deleteExpiredTokens`,
   lapsed one-time tokens too: the sign-in and mail throttles' counts
@@ -138,30 +149,3 @@ before is in the [CHANGELOG](../CHANGELOG.md).
   in no throttle and spends no link already sent, so accepting an
   invitation no longer goes through `magicLink.request` and its mail
   throttle. Privileged: never with an id a request supplied.
-- **E-mail requests in two steps, v0.20.0** — `magicLink.prepare(email)`,
-  `signInCode.prepare(email)` and `resetPassword.prepare(email)` count the
-  address and look nobody up — the same work for any address — so
-  `MAIL_THROTTLED` reaches the visitor while `send()`, the lookup and the
-  issue, runs off their request, where its time tells nothing. `send()`
-  answers what `request` does, once; a second call is a `TypeError`. A sign-in
-  code's prepared request carries its `challenge`, minted before the lookup,
-  so no decoy is needed for an address nobody holds.
-- **Several users by id in one query, v0.19.0** — `auth.<type>.findMany(ids)`
-  answers the type's users in the order of `ids`, each once, and leaves out an
-  id nobody of that type holds — for a list of rows that would otherwise make
-  one `find` per row and fill the connection pool. The users store gains an
-  optional `findUsers`, implemented by the reference store,
-  `@nxgt/janus-drizzle` 0.7.0 and `@nxgt/janus-mongo` 0.8.0; a store without it
-  is read with `findUser`, ten at a time, so third-party adapters keep working.
-- **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.

package/docs/troubleshooting.md

@@ -366,8 +366,8 @@ janus({ user: z.object({ username: z.string() }), password: { login: 'username'
 Also `janus: "<name>" cannot name a user type — janus() answers a method of that name` and `janus: users declares no user type`.
 
 **When:** `janus({ users: {...} })`.
-**Why:** each type becomes a property of what `janus()` answers — `auth.staff` — so it must be a name, and not one of the shared methods (`authenticate`, `signOut`, `signOutEverywhere`, `findUser`, `getUser`, `cookie`, `collectExpired`, `types`).
-**Fix:** `users: { staffMember: {...} }`, not `'staff-member'` or `cookie`.
+**Why:** each type becomes a property of what `janus()` answers — `auth.staff` — so it must be a name, and not one of the shared methods (`authenticate`, `signOut`, `signOutEverywhere`, `findUser`, `getUser`, `cookie`, `collectExpired`, `types`, `changeEmail`).
+**Fix:** `users: { staffMember: {...} }`, not `'staff-member'`, `cookie` or `changeEmail`.
 
 ### `janus: session.lifespan: "<value>" is not a duration; write a number followed by ms, s, m, h or d — for example "15m" or "720h"`
 
@@ -535,7 +535,7 @@ A runtime without `process.emitWarning` stays silent. Silence it with
 **Why:** a store that cannot answer throws; it never answers `null`. The driver's own error is on `error.cause` — not in the message, because a driver message can hold a connection string, and a connection string holds a password.
 **Fix:** answer **503**, and log `cause`. Never map it to 401, 404, `null` or `false`: that turns an outage into a silent lockout, where every user is told they do not exist.
 
-**After a password write** — `resetPassword.confirm`, `changePassword`, `setPassword` — the failure may come from spending the user's reset links and second-factor challenges, which runs after the password is written: the new password is then in place. A retried `changePassword` with the old `current` answers `CREDENTIALS_INVALID`; the next `resetPassword.request` spends any link left live.
+**After a password write** — `resetPassword.confirm`, `changePassword`, `setPassword` — the failure may come from spending the user's reset links and second-factor challenges, which runs after the password is written: the new password is then in place. A `STORE_FAILED` from `changePassword` may therefore follow a written change: check with `signIn` using `next` before retrying. A retried `changePassword` with the old `current` answers `CREDENTIALS_INVALID`; the next `resetPassword.request` spends any link left live.
 
 ```ts
 import { JanusError } from '@nxgt/janus';
@@ -738,19 +738,20 @@ return new Response('Wrong e-mail or password', { status: 401 });
 
 `CredentialError`, with `reason: 'throttled'` and `retryAfter`.
 
-**When:** `signIn`, after ten passwords were tried at this login in the
-current 15-minute window — whatever this password is, **the right one
-included**, and whether or not anybody holds the login. Nothing is compared.
+**When:** `signIn` or `changePassword`, after ten passwords were tried at
+this login in the current 15-minute window. The two share one count. Whatever
+the password is, **the right one included**, and whether or not anybody holds
+the login, it is refused. Nothing is compared.
 **Why:** `signIn` throttles password guessing per login, on by default:
 counted by the store, in fixed windows of the clock, shared by every process
 over the same store. Nothing locks: the next window signs in, and a sign-in
-that succeeds starts the count again. In tests with `fixedClock`, the window
-never ends: advance the clock past `retryAfter`, or wire
-`signIn: { throttle: false }`.
+that succeeds, or a `changePassword` that is written, starts the count
+again. In tests with `fixedClock`, the window never ends: advance the clock
+past `retryAfter`, or wire `signIn: { throttle: false }`.
 **Fix:** tell the visitor to wait `retryAfter` seconds — not that the
 password is wrong — and answer 401, as `@nxgt/janus-hono`'s `janusErrors()`
 does, with a `Retry-After` header. If nobody you know tried ten passwords,
-somebody is guessing: look for `janus.signIn.throttled` in your logs. To
+somebody is guessing: count the `CredentialError`s with `reason: 'throttled'` your handler sees. To
 change the limit or turn it off:
 
 ```ts
@@ -949,7 +950,7 @@ janus({ ..., hasher: scryptHasher(), verifiers: [bcryptVerifier] }); // a Passwo
 `TokenError`: `<call>: no such token`, `<call>: the token was already used`, `<call>: the token has expired`.
 
 **When:** `verifyEmail.confirm`, `resetPassword.confirm`, `changeEmail.confirm`.
-**Why:** a token is spent by its first use, and an expired one is spent too. `TOKEN_UNKNOWN` also covers a token whose user was deleted, and a change link confirmed through another user type's `changeEmail` or passed to another flow. The defaults are 24 h for `verifyEmail`, 1 h for `resetPassword` and for `changeEmail`. A change link is also spent by a newer `changeEmail.send` for the same user (only the last one works), and by an `update` that changes the user's e-mail.
+**Why:** a token is spent by its first use, and an expired one is spent too. `TOKEN_UNKNOWN` also covers a token whose user was deleted, and a change link confirmed through another user type's `changeEmail` (which spends it, so the right type then answers `TOKEN_SPENT`) or passed to another flow. The defaults are 24 h for `verifyEmail`, 1 h for `resetPassword` and for `changeEmail`. A change link is also spent by a newer `changeEmail.send` for the same user (only the last one works), and by an `update` that changes the user's e-mail.
 A reset link answers `resetPassword.confirm: the token was already used` in
 two more cases: a newer `resetPassword.request` for the same user spent it —
 only the last link sent works, so a visitor who asked twice and clicked the
@@ -958,7 +959,9 @@ sent, by another link's `confirm`, `changePassword` or `setPassword`. When two
 requests race, even the last link can be spent: at most one survives,
 sometimes none.
 **Fix:** answer 400 and offer to send a new link — and tell the visitor to use
-the latest e-mail. To change the lifetimes:
+the latest e-mail. With several user types, confirm a change link from a page
+that does not know the type with the root's `auth.changeEmail.confirm(token)`,
+never through a guessed type. To change the lifetimes:
 
 ```ts
 janus({ ..., tokens: { verifyEmail: '72h', resetPassword: '2h' } });

package/package.json

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