@nxgt/janus 0.23.0 → 0.23.1

package/README.md

@@ -761,11 +761,12 @@ password and the second factor go with it, so whoever holds the new inbox
 and follows the link signs in with them. The mail to the new address should
 say so, and say "ignore it if it was not you".
 
-**For now, send the link to the new address with your own mailer**:
-`@nxgt/janus-mail` has no template for it yet (it sends the notice to the
-former address, `emailChanged`). `mail.verifyEmail(issued)` is not the
-change-of-e-mail mail: it would tell the new address to verify, not that the
-account moves there.
+**Send the link to the new address with `@nxgt/janus-mail` 0.10.0 or later**:
+`mail.changeEmail(issued, { name })` (its `links.changeEmail` is the page
+above), and it sends the notice to the former address, `emailChanged`, once
+the link is redeemed. `mail.verifyEmail(issued)` is not the change-of-e-mail
+mail: it would tell the new address to verify, not that the account moves
+there. Without janus-mail, send it with your own mailer.
 
 - **On every user type with an e-mail**, with a password or without one. The
   address is validated by the type's schema as `update` would: a malformed

package/docs/guide/email-flows.md

@@ -37,15 +37,17 @@ writes it: it takes what `send` and `request` answer, as they answer it, and
 sends the verification, reset, sign-in code and sign-in link e-mails — with the notices
 of a password, an e-mail or a second factor changed, and a welcome on
 `user.created` — in English and French, over any `@nxgt/mail` transport.
-Every link is required but two: `getStarted`, since janus-mail 0.4.0, is
-where the welcome's **Get started** button leads; `recoveryCodes` and
+Every link is required but three: `getStarted`, since janus-mail 0.4.0, is
+where the welcome's **Get started** button leads; `recoveryCodes`,
 `magicLink` — the page a [sign-in link](magic-link.md) opens, since
-janus-mail 0.7.0 — are optional. **`changeEmail.send` is not among them
-yet**: janus-mail has no template for the link to a new address. Send that
-link with your own mailer; janus-mail sends the notice to the former address
-(`emailChanged`). `mail.verifyEmail(issued)` is not the change-of-e-mail
-mail: it would ask the new address to verify, not say the account moves
-there.
+janus-mail 0.7.0 — and `changeEmail`, the page that confirms a new address,
+since janus-mail 0.10.0, are optional. **`changeEmail.send`'s link has its
+own e-mail**: `mail.changeEmail(issued, { name })` sends it to
+`issued.email`, the new address, and janus-mail sends the notice to the
+former address (`emailChanged`) once the link is redeemed. It needs
+`@nxgt/janus-mail` 0.10.0 or later; `mail.verifyEmail(issued)` is not the
+change-of-e-mail mail: it would ask the new address to verify, not say the
+account moves there.
 
 ```ts
 import { janusMail } from '@nxgt/janus-mail';
@@ -59,11 +61,15 @@ const mail = janusMail({
 		resetPassword: (token) => `https://app.example/reset?token=${token}`,
 		secureAccount: () => 'https://app.example/account/security',
 		getStarted: () => 'https://app.example/',
+		changeEmail: (token) => `https://app.example/email/confirm?token=${token}`, // optional
 	},
 });
 
 await mail.verifyEmail(await auth.verifyEmail.send(user), { name: user.name });
 
+// to the NEW address; the account moves when changeEmail.confirm(token) redeems the link
+await mail.changeEmail(await auth.changeEmail.send(user, newEmail), { name: user.name });
+
 const issued = await auth.resetPassword.request(email);
 if (issued !== null) await mail.resetPassword(issued, { name: issued.user.name });
 ```

package/docs/guide/vocabulary.md

@@ -59,7 +59,7 @@ either finds this row.
 | **device**, **device token** | A device is a browser or an app a user signs in from, as the client's long-lived cookie — or a bearer client's storage — tells it. A **device token** is what janus signs for it with `devices.keys`, answers as `deviceToken`, and takes back as `device`: `d1.<key id>.<device id>.<mac>`, bound to one user, stored nowhere. A sign-in from a **new device** — one whose token did not prove this user signed in there — answers `newDevice: true` and sends `user.newDeviceSignedIn`. See [devices](devices.md) | "fingerprint", "trusted device", "remembered browser"; "token" alone |
 | **token** | Never alone in prose: a *session token*, a *one-time token* or a *device token*. The `tokens` store and the `TOKEN_*` codes are one-time tokens only | |
 | **e-mail flow** | `verifyEmail`, `resetPassword` or `changeEmail`: send a one-time token, then confirm it. `magicLink` sends one too, to sign in; `signInCode` sends a one-time code instead | |
-| **issued** | What a flow answers for the application to send: an `IssuedToken` from `verifyEmail.send`, `changeEmail.send`, `resetPassword.request` or `magicLink.request`, an `IssuedCode` from `signInCode.request` — the address with it. `@nxgt/janus-mail` takes it as it is, except `changeEmail.send`'s: it has no template for that link yet, so send it with your own mailer | "result", "payload" |
+| **issued** | What a flow answers for the application to send: an `IssuedToken` from `verifyEmail.send`, `changeEmail.send`, `resetPassword.request` or `magicLink.request`, an `IssuedCode` from `signInCode.request` — the address with it. `@nxgt/janus-mail` takes it as it is — `mail.changeEmail(issued, to)` for `changeEmail.send`'s, sent to the new address (janus-mail 0.10.0 or later) | "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 — *two-factor enabled*, *two-factor disabled*, *recovery code used* and *new sign-in*. `@nxgt/janus-mail` sends all six | "alert", "notification" |
 | **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.newDeviceSignedIn`, `user.deleted` — a `UserEvent`, naming the user by id alone — `user.emailChanged` adds `formerEmail`, `user.newDeviceSignedIn` adds `sessionId` — 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 |

package/package.json

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