@nxgt/janus 0.25.0 → 0.26.0

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/users.md

@@ -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

package/docs/roadmap.md

@@ -69,6 +69,12 @@ Nothing yet.
 The last ten, newest first, each with the version it came in. Everything
 before is in the [CHANGELOG](../CHANGELOG.md).
 
+- **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
@@ -153,15 +159,3 @@ before is in the [CHANGELOG](../CHANGELOG.md).
   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"`
 
@@ -949,7 +949,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 +958,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.26.0",
 	"description": "Embeddable, type-safe identities and permissions: bring your own database",
 	"license": "MIT",
 	"type": "module",