@nxgt/janus-mail 0.7.1 → 0.9.0

package/docs/guide/locales.md

@@ -82,12 +82,15 @@ const templates: JanusMailTemplates<Locale> = {
 	resetPassword: ({ name, link, expiresIn, locale }) => render('reset-password', locale, { name, link, expiresIn }),
 	signInCode: ({ code, expiresIn, locale }) => render('sign-in-code', locale, { code, expiresIn }),
 	magicLink: ({ link, expiresIn, locale }) => render('magic-link', locale, { link, expiresIn }),
+	stepUp: ({ name, code, expiresIn, link, locale }) => render('confirm-action', locale, { name, code, expiresIn, link }),
 	passwordChanged: ({ name, link, locale }) => render('password-changed', locale, { name, link }),
 	emailChanged: ({ name, link, newEmail, locale }) => render('email-changed', locale, { name, link, newEmail }),
 	twoFactorEnabled: ({ name, link, locale }) => render('two-factor-enabled', locale, { name, link }),
 	twoFactorDisabled: ({ name, link, locale }) => render('two-factor-disabled', locale, { name, link }),
 	recoveryCodeUsed: ({ name, when, recoveryCodesLeft, link, locale }) =>
 		render('recovery-code-used', locale, { name, when, recoveryCodesLeft, link }),
+	newSignIn: ({ name, device, location, time, link, locale }) =>
+		render('new-sign-in', locale, { name, device, location, time, link }),
 	welcome: ({ name, link, locale }) => render('welcome', locale, { name, link }),
 };
 
@@ -101,8 +104,10 @@ mail.locales; // readonly ('en' | 'fr' | 'de')[]
 plural of the codes left in `en` and `fr` only, so a German recipient's
 `mail.recoveryCodeUsed` takes the sentence as text — "Sie haben noch 3
 Wiederherstellungscodes." — and a count is a `TypeError` there.
-`recoveryCodeUsed` is the ninth template, since 0.5.0, and `magicLink` the
-tenth, since 0.7.0: a `templates` written for an earlier version no longer
+`recoveryCodeUsed` is the ninth template, since 0.5.0, `magicLink` the
+tenth, since 0.7.0, `stepUp` the eleventh, since 0.8.0, and `newSignIn` the
+twelfth, since 0.9.0: a `templates`
+written for an earlier version no longer
 compiles with a locale beyond `en` and `fr` — add the one it lacks. A
 renderer over a Maizzle build of your own, with
 `@nxgt/mail-presets` and a `locales/de.json`, is the closest to the defaults.
@@ -110,13 +115,13 @@ With only some templates, the call does not compile — the error lands on
 `templates`:
 
 ```text
-TS2740: Type '{ verifyEmail: () => Rendered; }' is missing the following properties from type 'JanusMailTemplates<"en" | "fr" | "de">': welcome, resetPassword, signInCode, magicLink, and 5 more.
+TS2740: Type '{ verifyEmail: () => Rendered; }' is missing the following properties from type 'JanusMailTemplates<"en" | "fr" | "de">': welcome, resetPassword, signInCode, magicLink, and 7 more.
 ```
 
 and in JavaScript it throws when `janusMail()` is called:
 
 ```text
-TypeError: janusMail: the default templates are built in en and fr only — with another locale in locales, pass every template in templates; resetPassword, signInCode, magicLink, passwordChanged, emailChanged, twoFactorEnabled, twoFactorDisabled, recoveryCodeUsed, welcome missing
+TypeError: janusMail: the default templates are built in en and fr only — with another locale in locales, pass every template in templates; resetPassword, signInCode, magicLink, stepUp, passwordChanged, emailChanged, twoFactorEnabled, twoFactorDisabled, recoveryCodeUsed, newSignIn, welcome missing
 ```
 
 A default template is typed for `'en' | 'fr'`, so reusing one in a wider set
@@ -129,4 +134,4 @@ Built-in locales for more languages are on the [roadmap](../roadmap.md).
 
 - `@nxgt/mail`'s [locales guide](https://github.com/softistx/nxgt-mail/blob/develop/packages/mail/docs/guide/locales.md)
   — `pickLocale` and `parseAcceptLanguage` in full.
-- [Templates](templates.md) — writing the ten for a new locale.
+- [Templates](templates.md) — writing the twelve for a new locale.

package/docs/guide/sending.md

@@ -46,7 +46,7 @@ time one is sent, and kept.
 | `brand` | `string` | required | The name the e-mails show, in the header, the body and the footer. Text: escaped in the HTML |
 | `links.verifyEmail` | `(token) => string` | required | The page that confirms an address, given the one-time token |
 | `links.resetPassword` | `(token) => string` | required | The page that sets a new password, given the one-time token |
-| `links.secureAccount` | `() => string` | required | Where a user who made no change secures their account: the notices link to it |
+| `links.secureAccount` | `() => string` | required | Where a user who made no change secures their account: the notices link to it — the new sign-in's included — and so does the step-up's code, for a user who asked for none |
 | `links.getStarted` | `() => string` | required | Where a new user starts — your home page, or your sign-in page for an account someone else created: the welcome's **Get started** button links to it |
 | `links.magicLink` | `(token) => string` | none: `magicLink` is a `TypeError` without it | The page a sign-in link opens, given the one-time token. That page spends nothing: its button posts the token to the route that calls `auth.magicLink.confirm` |
 | `links.recoveryCodes` | `() => string` | `links.secureAccount` | Where a user regenerates their recovery codes: the recovery code notice links to it, from its **Secure my account** button |
@@ -145,6 +145,44 @@ nobody by name — and only its `locale` is read.
   visitor's secret, and no `token`: the compiler refuses it here, and
   JavaScript gets `janusMail.magicLink: token must be a string`.
 
+### `stepUp(issued, to, options?)`
+
+```ts
+const current = await auth.authenticate(request); // the signed-in user, their session
+if (current === null) return new Response(null, { status: 401 });
+const issued = await auth.stepUp.request(current.user); // StepUpByEmail, or StepUpByApp with a second factor
+if (issued.via === 'email') {
+	await mail.stepUp(issued, { name: current.user.name, locale: current.user.locale });
+}
+return Response.json({ challenge: issued.challenge, via: issued.via }); // the challenge stays with the user
+```
+
+The code of a step-up — a signed-in user proving again who they are before
+a sensitive action, `@nxgt/janus`'s
+[step-up guide](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/step-up.md) —
+sent to `issued.email`, greeting `to.name`: "Your confirmation code",
+"Votre code de confirmation", the code, how long it lasts — "This code
+expires in 10 minutes." — and a **Secure my account** button to
+`links.secureAccount()`, for a user who asked for nothing. The e-mail names
+no action: it says "something sensitive", whatever the route guards.
+
+- **Narrow `via` first.** A user whose second factor is active confirms with
+  their app: `request` answers `via: 'secondFactor'`, with no code and no
+  address, and there is nothing to send. The compiler refuses the answer
+  un-narrowed; JavaScript gets
+  `janusMail.stepUp: via must be 'email' — a step-up confirmed with the user's app sends no e-mail`,
+  before anything is rendered. A type without `secondFactor` in `janus()`
+  answers `via: 'email'` alone, and needs no check.
+- **`to` is required**, unlike `signInCode`'s: the e-mail greets the user by
+  name, and it is the user of the session, whose name you hold.
+- It reads `issued.via`, `issued.code`, `issued.email` and
+  `issued.expiresAt`, **and nothing else**: the challenge never reaches a
+  template.
+- **The link has no fallback, and needs none.** `links.secureAccount` is
+  required by `janusMail()`: the notices link to it too.
+- **Rate-limit `stepUp.request` per user**, as the step-up guide says: each
+  request sends this e-mail.
+
 ### `passwordChanged(to)`
 
 ```ts
@@ -311,10 +349,56 @@ when opening the session then fails.
   codes; without it, `links.secureAccount()`. `recoveryCodes` is optional,
   so a `links` written for 0.4 still compiles.
 
+### `newSignIn(to, { device, time, location? })`
+
+```ts
+// From the sign-in's answer, with @nxgt/janus given devices: { keys } and the device cookie:
+const signedIn = await auth.signIn({ email, password }, { device: cookie ?? null });
+if (signedIn.newDevice) {
+	const { name, email, locale } = signedIn.user;
+	await mail.newSignIn(
+		{ name, email, locale },
+		{
+			device: describeDevice(request.headers.get('user-agent')), // yours: 'Firefox on macOS'
+			time: new Intl.DateTimeFormat(locale ?? 'en', {
+				dateStyle: 'long',
+				timeStyle: 'short',
+				timeZone: 'Europe/Paris', // the user's, when you keep it
+			}).format(signedIn.session.createdAt),
+			location: 'Lyon, France', // optional: from a geo-IP of yours
+		},
+	);
+}
+```
+
+A notice for the account at `to.email`: it was signed in from a device the
+user had not signed in from — which device, where and when — with a
+**Secure my account** button to `links.secureAccount()`. Send it when a
+`@nxgt/janus` 0.17 sign-in answers `newDevice: true`, or on the
+`user.newDeviceSignedIn` event it sends then — the event names the user by
+id alone, so read the name, the locale and the address from the user, and
+it carries no request to describe the device from.
+
+- **Every value is your text**, already in the recipient's locale: `device`
+  as you describe the request — "Firefox on macOS", "Firefox sur macOS" —
+  and `time` formatted in their time zone: "29 septembre 2026 à 09:12".
+  The session's `createdAt`, or the event's `occurredAt`, is when it
+  happened.
+- **`location` is optional, and yours.** `@nxgt/janus` sees no IP: a
+  location comes from a geo-IP of your own, if you have one. Left out, the
+  e-mail shows `—` — an em dash, which reads the same in English and
+  French — since every line of the summary is always there. `null` is a
+  compile error, and in JavaScript `janusMail.newSignIn: location must be a
+  string`: spread it in only when you have one,
+  `...(city === null ? {} : { location: city })`.
+- **The text part** gives each line of the summary as its label, then its
+  value on the next line — `Device`, then `Firefox on macOS` — where every
+  other paragraph is one line.
+
 ## The expiry
 
-`verifyEmail`, `resetPassword`, `signInCode` and `magicLink` say how long
-the link or the code lasts — "This link expires in 1 hour.", "Ce code expire dans
+`verifyEmail`, `resetPassword`, `signInCode`, `magicLink` and `stepUp` say
+how long the link or the code lasts — "This link expires in 1 hour.", "Ce code expire dans
 10 minutes." The text is `expiresIn`, one of the template's variables,
 derived at send time from the flow's `issued.expiresAt`:
 
@@ -328,7 +412,7 @@ derived at send time from the flow's `issued.expiresAt`:
    `unitDisplay: 'long'`, in the recipient's locale: "3 hours", "3 heures".
 
 With `@nxgt/janus`'s defaults, a verification link says "1 day", a reset
-link "1 hour" and a sign-in code "10 minutes".
+link "1 hour", and a sign-in code and a step-up's code "10 minutes".
 
 The time is `janusMail({ clock })`'s — pass the clock `janus({ clock })` was
 given, a `fixedClock` in tests — else the system clock:
@@ -363,10 +447,12 @@ a `TypeError`, and nothing reaches the mailer: revive the date with
 | `resetPassword` | `issued.email` | the `email` passed to `request` |
 | `signInCode` | `issued.email` | the `email` passed to `request` |
 | `magicLink` | `issued.email` | the `email` passed to `request` |
+| `stepUp` | `issued.email` | an address the client sent |
 | `passwordChanged` | `to.email` | — |
 | `emailChanged` | `to.formerEmail` | `to.newEmail` |
 | `twoFactorEnabled`, `twoFactorDisabled` | `to.email` | — |
 | `recoveryCodeUsed` | `to.email` | — |
+| `newSignIn` | `to.email` | — |
 | `welcome` | `to.email` | — |
 
 `issued.email` is the address the user's record holds, as they registered
@@ -386,7 +472,7 @@ defines no error class and wraps nothing:
 | --- | --- | --- | --- |
 | `MailFailure` (`MAIL_FAILED`) | the mailer | The transport could not hand the e-mail over. Nothing is known to have been sent | A `503`, or a retry from a queue |
 | `MailRefused` (`MAIL_REFUSED`) | the renderer, or the mailer | The e-mail itself is wrong: a link that is not `http:`, `https:` or `mailto:`, an address that is not one | A bug to fix; sending it again fails again |
-| `TypeError` | this package, or the renderer | A call without the value a flow answered — `janusMail.resetPassword: token must be a string` — or, in JavaScript, a link that is not a string (a compile error in TypeScript) — `janusMail.verifyEmail: links.verifyEmail(token) must answer a string`. For [the expiry](#the-expiry): `janusMail.<method>: expiresAt must be a Date`, `janusMail.<method>: expiresAt is past — the link or code would not work`, `janusMail.<method>: expiresIn must be a string`, `janusMail.<method>: clock.now() must answer a Date` | A bug to fix — for a past `expiresAt`, issue a new token or code and send that |
+| `TypeError` | this package, or the renderer | A call without the value a flow answered — `janusMail.resetPassword: token must be a string` — or, in JavaScript, a link that is not a string (a compile error in TypeScript) — `janusMail.verifyEmail: links.verifyEmail(token) must answer a string`. For [the expiry](#the-expiry): `janusMail.<method>: expiresAt must be a Date`, `janusMail.<method>: expiresAt is past — the link or code would not work`, `janusMail.<method>: expiresIn must be a string`, `janusMail.<method>: clock.now() must answer a Date`. For `stepUp`: `janusMail.stepUp: via must be 'email' — …` | A bug to fix — for a past `expiresAt`, issue a new token or code and send that |
 | `Error` from `createMailRenderer` | the renderer | `mails/` is missing where the package runs: a bundler inlined `@nxgt/janus-mail`, or a deploy kept `dist/` only | Keep `@nxgt/janus-mail` external to your bundle and deploy its `mails/` with it; see [troubleshooting](../troubleshooting.md#createmailrenderer-mailsmail-manifestjson-cannot-be-read--run-maizzle-build-and-deploy-its-output-folder) |
 
 `instanceof` holds against the classes of your own `@nxgt/mail`, since it is

package/docs/guide/templates.md

@@ -1,7 +1,7 @@
 # Templates
 
 This page is for changing what an e-mail says or looks like: what a template
-is given and answers, replacing some of the ten, using the defaults on their
+is given and answers, replacing some of the twelve, using the defaults on their
 own, and what the defaults say.
 
 ```ts
@@ -22,7 +22,7 @@ const mail = janusMail({
 });
 ```
 
-The sign-in code e-mail is now yours; the eight others stay the defaults.
+The sign-in code e-mail is now yours; the eleven others stay the defaults.
 
 ## What a template is
 
@@ -63,19 +63,22 @@ e-mail.
 | `resetPassword` | `brand`, `name`, `link`, `expiresIn` | `mail.resetPassword(issued, to, options?)` |
 | `signInCode` | `brand`, `code`, `expiresIn` | `mail.signInCode(issued, to?, options?)` |
 | `magicLink` | `brand`, `link`, `expiresIn` | `mail.magicLink(issued, to?, options?)` |
+| `stepUp` | `brand`, `name`, `code`, `expiresIn`, `link` | `mail.stepUp(issued, to, options?)` |
 | `passwordChanged` | `brand`, `name`, `link` | `mail.passwordChanged(to)` |
 | `emailChanged` | `brand`, `name`, `link`, `newEmail` | `mail.emailChanged(to)` |
 | `twoFactorEnabled` | `brand`, `name`, `link` | `mail.twoFactorEnabled(to)` |
 | `twoFactorDisabled` | `brand`, `name`, `link` | `mail.twoFactorDisabled(to)` |
 | `recoveryCodeUsed` | `brand`, `name`, `when`, `recoveryCodesLeft`, `link` | `mail.recoveryCodeUsed(to, { when, recoveryCodesLeft })` |
+| `newSignIn` | `brand`, `name`, `device`, `location`, `time`, `link` | `mail.newSignIn(to, { device, time, location? })` |
 | `welcome` | `brand`, `name`, `link` | `mail.welcome(to)` |
 
 Every one also gets `locale`, one of `locales`. Every value is a string:
 `brand` from the options, `name` from the recipient, `link` from `links` —
-`links.secureAccount()` for the four notices, `links.recoveryCodes()` (else
+`links.secureAccount()` for the notices other than `recoveryCodeUsed` and
+for `stepUp`, `links.recoveryCodes()` (else
 `links.secureAccount()`) for `recoveryCodeUsed`, `links.getStarted()` for
-`welcome` — `code`, `newEmail` and `when` from the
-call, and `expiresIn` derived from the flow's `expiresAt` in the locale, or
+`welcome` — `code`, `newEmail`, `when`, `device` and `time` from the
+call, `location` from the call or `—` without one, and `expiresIn` derived from the flow's `expiresAt` in the locale, or
 the send's own `expiresIn` ([Sending](sending.md#the-expiry)).
 
 `recoveryCodesLeft` is a **sentence**, not the count: "You have 9 recovery
@@ -95,8 +98,8 @@ templates: {
 // await mail.recoveryCodeUsed(to, { when, recoveryCodesLeft: `Sie haben noch ${left} Wiederherstellungscodes.` });
 ```
 
-`signInCode` is **never given the challenge**: it is not in its variables,
-and the method never reads it. An override states the expiry from
+`signInCode` and `stepUp` are **never given the challenge**: it is not in
+their variables, and the methods never read it. An override states the expiry from
 `expiresIn`, already formatted:
 
 ```ts
@@ -125,11 +128,12 @@ methods live on its prototype and are refused — see
 [troubleshooting](../troubleshooting.md#janusmail-templatesname-is-not-an-own-enumerable-property--pass-a-plain-object-as--name-variables--rendered-).
 
 `templates` is `Partial` while `locales` stays within `en` and `fr`: give
-any of the ten, and the defaults render the rest. Once `locales` holds
-another locale, it takes **all ten** — see
+any of the twelve, and the defaults render the rest. Once `locales` holds
+another locale, it takes **all twelve** — `stepUp` included, since 0.8, and
+`newSignIn`, since 0.9 — see
 [Adding a locale](locales.md#adding-a-locale).
 
-`mail.templates` answers the ten in use — yours, and the defaults for the
+`mail.templates` answers the twelve in use — yours, and the defaults for the
 rest — frozen:
 
 ```ts
@@ -151,7 +155,7 @@ const { subject, html, text } = await defaults.resetPassword({
 });
 ```
 
-It answers the ten defaults, typed for `'en' | 'fr'`, without a mailer:
+It answers the twelve defaults, typed for `'en' | 'fr'`, without a mailer:
 to preview an e-mail, to wrap one — add a line to the default text, say — or
 to send one through something other than `janusMail()`. A default reused for
 a wider set of locales is a compile error: it could not render the one it
@@ -177,7 +181,7 @@ them renders: that is when the package's `mails/` folder is read, once.
 ## What the defaults say
 
 The defaults are [`@nxgt/mail-presets`](https://www.npmjs.com/package/@nxgt/mail-presets)
-1.0.1, built with a neutral grey theme and no logo:
+1.1.0, built with a neutral grey theme and no logo:
 
 | Template | Built from | Subject (`en`) | Subject (`fr`) |
 | --- | --- | --- | --- |
@@ -185,25 +189,35 @@ The defaults are [`@nxgt/mail-presets`](https://www.npmjs.com/package/@nxgt/mail
 | `resetPassword` | `reset-password` | Reset your password | Réinitialisez votre mot de passe |
 | `signInCode` | `sign-in-code` | Your sign-in code: `042817` | Votre code de connexion : `042817` |
 | `magicLink` | `magic-link` | Your sign-in link | Votre lien de connexion |
+| `stepUp` | `confirm-action` | Your confirmation code | Votre code de confirmation |
 | `passwordChanged` | `password-changed` | Your password was changed | Votre mot de passe a été modifié |
 | `emailChanged` | `email-changed` | Your e-mail address was changed | Votre adresse e-mail a été modifiée |
 | `twoFactorEnabled` | `two-factor-enabled` | Two-factor authentication was turned on | L'authentification à deux facteurs a été activée |
 | `twoFactorDisabled` | `two-factor-disabled` | Two-factor authentication was turned off | L'authentification à deux facteurs a été désactivée |
 | `recoveryCodeUsed` | `recovery-code-used` | A recovery code was used on your account | Un code de récupération a été utilisé sur votre compte |
+| `newSignIn` | `new-sign-in` | New sign-in to your account | Nouvelle connexion à votre compte |
 | `welcome` | `welcome` | Welcome, `Ada` | Bienvenue, `Ada` |
 
 Each has a header and a footer with the brand, a heading, a greeting by name
 (but `signInCode` and `magicLink`), a button with its link and the link again in text for a
-client that shows no button, and a text part. The other four notices add a warning:
-*if this was not you, secure your account now*. `recoveryCodeUsed` says it
+client that shows no button, and a text part. The notices other than `recoveryCodeUsed` add a warning:
+*if this was not you, secure your account now*. `stepUp` shows its code as
+the sign-in code does, names no action — *someone, we hope you, asked to do
+something sensitive on your account* — and warns not to share the code if
+it was not the user, its button saying **Secure my account**. `recoveryCodeUsed` says it
 too, after a warning banner — *a recovery code was used on your account at
 `when`* — the codes left, and a line on generating new ones; its button says
-**Secure my account**. `welcome` has the brand in
+**Secure my account**. `newSignIn` says the account *was signed in from a
+device we had not seen*, then a summary of three lines — **Device**,
+**Location** and **Time**, *Appareil*, *Lieu* and *Heure* in French — then
+*if this was you, there is nothing to do; if this was not you, secure your
+account now*, its button saying **Secure my account**; in the text part each
+line of the summary is its label, then its value on the next line. `welcome` has the brand in
 its heading — "Welcome to Acme" — and the recipient's name in its subject,
 filled at send time like the body; its button says **Get started**.
 
-`verifyEmail`, `resetPassword`, `signInCode` and `magicLink` also say how
-long the link or the code lasts: "This link expires in 1 hour.", "Ce code expire dans
+`verifyEmail`, `resetPassword`, `signInCode`, `magicLink` and `stepUp` also
+say how long the link or the code lasts: "This link expires in 1 hour.", "Ce code expire dans
 10 minutes." The text part keeps each paragraph on one line.
 
 **The HTML follows dark mode.** Each HTML part declares
@@ -215,7 +229,7 @@ is near-black (`#27272a`) with light text in light mode, and near-white
 (`#fafafa`) with near-black text (`#18181b`) in dark mode — 17:1 against the
 dark card, where the light primary would be 1.2:1. The page behind the card
 is 5% of the light primary over the dark background, a shade darker than the
-card, which its border outlines. The sign-in code's box is a light grey
+card, which its border outlines. The code's box — the sign-in code's and the step-up's — is a light grey
 (`#f1f5f9`) with near-black code (`#020918`) in light mode, and a slate a
 step above the dark card (`#1e293b`) with light code (`#cbd5e1`) in dark
 mode, 9.85:1. The muted text — the footer, and the closing *if you did not

package/docs/roadmap.md

@@ -9,9 +9,8 @@ Nothing between releases.
 
 ## Next
 
-- **The other presets** — `new-sign-in` and `invitation` from
-  `@nxgt/mail-presets`, each once `@nxgt/janus` has a flow that sends it: a
-  sign-in from a new device, an invitation to a user type.
+- **The invitation** — `invitation` from `@nxgt/mail-presets`, once
+  `@nxgt/janus` has a flow that sends it: an invitation to a user type.
 - **The other presets of `@nxgt/mail-presets` 0.4.0** — `account-deleted`,
   after a user is deleted, once `@nxgt/janus` has a deletion a link can
   undo; and `invitation-accepted`, once it has invitations.
@@ -40,13 +39,33 @@ Nothing between releases.
   its flows answer what to send, and this package is called with that answer.
   An application that sends its own way needs neither this package nor a
   hook to turn off.
-- **The challenge in an e-mail** — a sign-in code e-mail carries the code and
-  never the challenge, not even through an override.
+- **The challenge in an e-mail** — a sign-in code's or a step-up's e-mail
+  carries the code and never the challenge, not even through an override.
 
 ## Shipped
 
 Newest first; from the first release on, the package's CHANGELOG holds every one.
 
+- **The new sign-in notice, v0.9.0.** `newSignIn(to, { device, time,
+  location? })`, built from `@nxgt/mail-presets` 1.1.0's `new-sign-in` in
+  English and French — "New sign-in to your account", which device, where
+  and when, and a **Secure my account** button to `links.secureAccount()`:
+  send it when an `@nxgt/janus` 0.17 sign-in answers `newDevice: true`, or
+  on `user.newDeviceSignedIn`. Every value is your text in the recipient's
+  locale; `@nxgt/janus` sees no IP, so `location` is yours, and `—` without
+  one. Twelve e-mails now, and twelve templates to pass for a locale beyond
+  `en` and `fr`.
+
+- **The step-up's code, v0.8.0.** `stepUp(issued, to, options?)`, built
+  from `@nxgt/mail-presets` 1.1.0's `confirm-action` in English and French:
+  send what `@nxgt/janus`'s `auth.stepUp.request(user)` answered, once
+  narrowed to `via: 'email'`, to `issued.email` — "Your confirmation code",
+  the code, how long it lasts, and a **Secure my account** button to
+  `links.secureAccount()` for a user who asked for nothing. A step-up
+  confirmed with the user's app sends nothing, and is refused. Eleven
+  e-mails now, and eleven templates to pass for a locale beyond `en` and
+  `fr`.
+
 - **The sign-in link, v0.7.0.** `magicLink(issued, to?, options?)`, built
   from `@nxgt/mail-presets` 1.0.1's `magic-link` in English and French:
   send what `@nxgt/janus` 0.15's `auth.magicLink.request(email)` answered,
@@ -111,23 +130,3 @@ Newest first; from the first release on, the package's CHANGELOG holds every one
   linking to `links.secureAccount()`: send them on `@nxgt/janus` 0.9's
   `user.secondFactorEnabled` and `user.secondFactorDisabled` events. Seven
   e-mails now, and seven templates to pass for a locale beyond `en` and `fr`.
-- **Dark mode, v0.3.0.** The e-mails follow the reader's dark mode in
-  every client that supports it, Gmail excepted: a dark page, a dark card and
-  light text. Built from `@nxgt/mail-ui` 0.4.0, `@nxgt/mail-presets` 0.4.0
-  and `@nxgt/mail-i18n` 0.5.0; the text parts, subjects and variables are
-  unchanged, the manifest is still format 1, and the `@nxgt/mail` peer stays
-  `>=0.1.0 <1`.
-
-- **The expiry in the e-mail, v0.2.0.** The verification, reset and sign-in
-  code e-mails say how long the link or code lasts — "1 hour", "1 heure" —
-  derived from the flow's `expiresAt` in the recipient's locale, measured
-  against `janusMail({ clock })` (the clock given to `janus()`), or given per
-  send as `{ expiresIn }`. Two breaks: a template called directly takes
-  `expiresIn`, and `signInCode` reads `issued.expiresAt`. Built from
-  `@nxgt/mail-presets` 0.2.0, whose text parts keep each paragraph on one
-  line.
-
-- **The first release, v0.1.0.** The five e-mails of `@nxgt/janus`'s flows,
-  in English and French, over any `@nxgt/mail` transport: `janusMail()` and
-  `janusTemplates()`. Built with Maizzle when the package is built, shipped
-  in `mails/`, and only filled in at send time, every value escaped.

package/docs/troubleshooting.md

@@ -34,7 +34,7 @@ How the messages are shaped:
 - [`janusMail: locales holds the same locale twice`](#janusmail-locales-holds-the-same-locale-twice)
 - [`janusMail: fallbackLocale must be one of locales`](#janusmail-fallbacklocale-must-be-one-of-locales)
 - [`janusMail: templates must be an object of functions, as { verifyEmail: (variables) => rendered }`](#janusmail-templates-must-be-an-object-of-functions-as--verifyemail-variables--rendered-)
-- [`janusMail: templates has no template <name> — name one of verifyEmail, resetPassword, signInCode, magicLink, passwordChanged, emailChanged, twoFactorEnabled, twoFactorDisabled, recoveryCodeUsed, welcome`](#janusmail-templates-has-no-template-name--name-one-of-verifyemail-resetpassword-signincode-magiclink-passwordchanged-emailchanged-twofactorenabled-twofactordisabled-recoverycodeused-welcome)
+- [`janusMail: templates has no template <name> — name one of verifyEmail, resetPassword, signInCode, magicLink, stepUp, passwordChanged, emailChanged, twoFactorEnabled, twoFactorDisabled, recoveryCodeUsed, newSignIn, welcome`](#janusmail-templates-has-no-template-name--name-one-of-verifyemail-resetpassword-signincode-magiclink-stepup-passwordchanged-emailchanged-twofactorenabled-twofactordisabled-recoverycodeused-newsignin-welcome)
 - [`janusMail: templates.<name> must be a function`](#janusmail-templatesname-must-be-a-function)
 - [`janusMail: templates.<name> is not an own enumerable property — pass a plain object, as { <name>: (variables) => rendered }`](#janusmail-templatesname-is-not-an-own-enumerable-property--pass-a-plain-object-as--name-variables--rendered-)
 - [`janusMail: clock must be a Clock — an object with a now function`](#janusmail-clock-must-be-a-clock--an-object-with-a-now-function)
@@ -42,6 +42,7 @@ How the messages are shaped:
 
 **Sending**
 - [`janusMail.magicLink: links.magicLink is missing — pass it to janusMail({ links }) to send sign-in links`](#janusmailmagiclink-linksmagiclink-is-missing--pass-it-to-janusmail-links--to-send-sign-in-links)
+- [`janusMail.stepUp: via must be 'email' — a step-up confirmed with the user's app sends no e-mail`](#janusmailstepup-via-must-be-email--a-step-up-confirmed-with-the-users-app-sends-no-e-mail)
 - [`janusMail.<method>: <field> must be a string`](#janusmailmethod-field-must-be-a-string)
 - [`janusMail.<method>: expiresAt must be a Date`](#janusmailmethod-expiresat-must-be-a-date)
 - [`janusMail.recoveryCodeUsed: recoveryCodesLeft must be a count — a whole number, 0 or more — or the sentence to show`](#janusmailrecoverycodeused-recoverycodesleft-must-be-a-count--a-whole-number-0-or-more--or-the-sentence-to-show)
@@ -68,10 +69,14 @@ How the messages are shaped:
 - [`TS2739: Type '{ … }' is missing the following properties from type 'JanusMailTemplates<…>'`](#ts2739-type----is-missing-the-following-properties-from-type-janusmailtemplates)
 - [`TS2741: Property 'recoveryCodeUsed' is missing in type '{ … }' but required in type 'JanusMailTemplates<…>'.`](#ts2741-property-recoverycodeused-is-missing-in-type----but-required-in-type-janusmailtemplates)
 - [`TS2741: Property 'magicLink' is missing in type '{ … }' but required in type 'JanusMailTemplates<…>'.`](#ts2741-property-magiclink-is-missing-in-type----but-required-in-type-janusmailtemplates)
+- [`TS2741: Property 'stepUp' is missing in type '{ … }' but required in type 'JanusMailTemplates<…>'.`](#ts2741-property-stepup-is-missing-in-type----but-required-in-type-janusmailtemplates)
+- [`TS2741: Property 'newSignIn' is missing in type '{ … }' but required in type 'JanusMailTemplates<…>'.`](#ts2741-property-newsignin-is-missing-in-type----but-required-in-type-janusmailtemplates)
+- [`TS2345: Argument of type 'StepUpByEmail<…> | StepUpByApp<…>' is not assignable to parameter of type 'Pick<StepUpByEmail<unknown>, …>'.`](#ts2345-argument-of-type-stepupbyemail--stepupbyapp-is-not-assignable-to-parameter-of-type-pickstepupbyemailunknown-)
 - [`TS2322: Type '"de"' is not assignable to type '"en" | "fr"'.`](#ts2322-type-de-is-not-assignable-to-type-en--fr)
 - [`TS2741: Property 'getStarted' is missing in type '{ … }' but required in type 'JanusMailLinks'.`](#ts2741-property-getstarted-is-missing-in-type----but-required-in-type-janusmaillinks)
 - [`TS2322: Type 'number | null' is not assignable to type 'string | number'.`](#ts2322-type-number--null-is-not-assignable-to-type-string--number)
 - [`TS2322: Type 'Date' is not assignable to type 'string'.`](#ts2322-type-date-is-not-assignable-to-type-string)
+- [`TS2322: Type 'string | null' is not assignable to type 'string'.`, on `location`](#ts2322-type-string--null-is-not-assignable-to-type-string-on-location) — or `… to type 'string | undefined'.`
 
 ---
 
@@ -196,9 +201,9 @@ A `fallbackLocale` the list does not hold — `'de'` with the default
 
 `templates` given as a list or a function. Key each template by its name.
 
-### `janusMail: templates has no template <name> — name one of verifyEmail, resetPassword, signInCode, magicLink, passwordChanged, emailChanged, twoFactorEnabled, twoFactorDisabled, recoveryCodeUsed, welcome`
+### `janusMail: templates has no template <name> — name one of verifyEmail, resetPassword, signInCode, magicLink, stepUp, passwordChanged, emailChanged, twoFactorEnabled, twoFactorDisabled, recoveryCodeUsed, newSignIn, welcome`
 
-A key that is not one of the ten — `newSignIn`, or the e-mail's file name
+A key that is not one of the twelve — `invitation`, or the e-mail's file name
 `'verify-email'` rather than the template's, `verifyEmail`. Other e-mails are
 on the [roadmap](roadmap.md); send them with `@nxgt/mail` directly meanwhile.
 
@@ -232,7 +237,7 @@ as it is: fields are own properties.
 ### `janusMail: the default templates are built in en and fr only — with another locale in locales, pass every template in templates; <names> missing`
 
 `locales` holds a locale beyond `en` and `fr`, and `templates` leaves some
-out: the defaults could not render them in that locale. Pass all ten — see
+out: the defaults could not render them in that locale. Pass all twelve — see
 [Adding a locale](guide/locales.md#adding-a-locale) — or drop the locale.
 The message lists the templates missing.
 
@@ -267,6 +272,26 @@ const mail = janusMail({
 
 Sending again fails again: it is a bug, not an outage.
 
+### `janusMail.stepUp: via must be 'email' — a step-up confirmed with the user's app sends no e-mail`
+
+A `TypeError` from `mail.stepUp`, before anything is rendered or sent: it
+was given what `auth.stepUp.request(user)` answered for a user whose second
+factor is active — `via: 'secondFactor'`, with no code and no address — or
+something with no `via` at all, such as a sign-in code's answer. A step-up
+confirmed with the user's app sends nothing: ask for the code their app
+shows. Check `via` first:
+
+```ts
+const issued = await auth.stepUp.request(current.user);
+if (issued.via === 'email') {
+	await mail.stepUp(issued, { name: current.user.name, locale: current.user.locale });
+}
+return Response.json({ challenge: issued.challenge, via: issued.via });
+```
+
+In TypeScript the unchecked call does not compile — see
+[`TS2345: Argument of type 'StepUpByEmail<…> | StepUpByApp<…>' …`](#ts2345-argument-of-type-stepupbyemail--stepupbyapp-is-not-assignable-to-parameter-of-type-pickstepupbyemailunknown-).
+
 ### `janusMail.<method>: <field> must be a string`
 
 A `TypeError` from a call, naming the method and the field it could not read
@@ -286,7 +311,9 @@ send it with `signInCode`, or ask `auth.magicLink.request` for a link.
 
 `issued` needs `token` and `email` (`code` and `email` for `signInCode`), and
 the recipient its `name` — a user whose schema has no name passes one
-anyway: `{ name: user.email }`. `janusMail.verifyEmail: expiresIn must be a
+anyway: `{ name: user.email }`. `janusMail.stepUp: name must be a string`
+is `stepUp` called without the recipient: unlike `signInCode`, its e-mail
+greets the user by name. `janusMail.verifyEmail: expiresIn must be a
 string` is the third argument's `expiresIn` given as something else — a
 number of seconds: pass the text to show, `{ expiresIn: '1 hour' }`, or
 leave it out.
@@ -315,6 +342,14 @@ if (event.type === 'user.emailChanged' && event.formerEmail != null) {
 }
 ```
 
+`janusMail.newSignIn: device must be a string` and `janusMail.newSignIn:
+time must be a string` are the second argument missing, or its `time` given
+as the session's `Date`: pass the device as you describe it and the time as
+text. `janusMail.newSignIn: location must be a string` is a location lookup's
+`null`: leave `location` out, and the e-mail shows `—`. `janusMail.newSignIn:
+email must be a string` is the `user.newDeviceSignedIn` event itself given
+as the recipient — read the user first.
+
 `janusMail.recoveryCodeUsed: when must be a string` is the second argument
 missing, or its `when` given as the event's `Date`: pass the text to show,
 formatted in the recipient's locale and time zone —
@@ -322,8 +357,8 @@ formatted in the recipient's locale and time zone —
 
 ### `janusMail.<method>: expiresAt must be a Date`
 
-A `TypeError` from `verifyEmail`, `resetPassword`, `signInCode` or
-`magicLink`: the e-mail says how long its link or code lasts, from `issued.expiresAt`, and that is
+A `TypeError` from `verifyEmail`, `resetPassword`, `signInCode`,
+`magicLink` or `stepUp`: the e-mail says how long its link or code lasts, from `issued.expiresAt`, and that is
 not a valid `Date`. The usual cause is a flow's answer that went through
 JSON — a job queue, a cache — where a `Date` becomes a string. Nothing is
 sent. Revive it when the job runs, or say the expiry yourself:
@@ -363,8 +398,8 @@ await mail.recoveryCodeUsed(to, { when, recoveryCodesLeft: `Sie haben noch ${lef
 
 ### `janusMail.<method>: clock.now() must answer a Date`
 
-A `TypeError` from `verifyEmail`, `resetPassword`, `signInCode` or
-`magicLink`: the `clock` given to `janusMail()` has a `now` that answered something else — a
+A `TypeError` from `verifyEmail`, `resetPassword`, `signInCode`,
+`magicLink` or `stepUp`: the `clock` given to `janusMail()` has a `now` that answered something else — a
 number from `Date.now()`, a string, an invalid `Date`. Nothing is sent.
 `clock` is `@nxgt/janus`'s `Clock`: pass the one `janus({ clock })` was
 given, or `{ now: () => new Date() }`.
@@ -497,7 +532,7 @@ avoids the read altogether. (In this repository: run `bun run build`.)
 
 The default templates read `mails/` with `node:fs`, through
 `@nxgt/mail/renderer`: Node, Bun or Deno only. On an edge runtime, pass all
-ten templates yourself; an inlined build is on the [roadmap](roadmap.md).
+twelve templates yourself; an inlined build is on the [roadmap](roadmap.md).
 
 ### An e-mail stays light in dark mode
 
@@ -630,8 +665,9 @@ whole.
 ### `TS2739: Type '{ … }' is missing the following properties from type 'JanusMailTemplates<…>'`
 
 `locales` holds a locale beyond `en` and `fr`, and `templates` does not give
-all ten. With five or more missing, the code is `TS2740` and the list ends
-`…, and 5 more.` See [Adding a locale](guide/locales.md#adding-a-locale).
+all twelve. With five or more missing, the code is `TS2740` and the list ends
+`…, and <n> more.` — `…, and 7 more.` for a `templates` holding one
+template. See [Adding a locale](guide/locales.md#adding-a-locale).
 
 ### `TS2741: Property 'recoveryCodeUsed' is missing in type '{ … }' but required in type 'JanusMailTemplates<…>'.`
 
@@ -651,6 +687,42 @@ Add `magicLink` — it is given `brand`, `link` and `expiresIn` — even if you
 never send it; in JavaScript the same `templates` is
 [`janusMail: the default templates are built in en and fr only — …; magicLink missing`](#janusmail-the-default-templates-are-built-in-en-and-fr-only--with-another-locale-in-locales-pass-every-template-in-templates-names-missing).
 
+### `TS2741: Property 'stepUp' is missing in type '{ … }' but required in type 'JanusMailTemplates<…>'.`
+
+`templates` written before 0.8, with a locale beyond `en` and `fr`: since
+0.8.0 there are eleven templates, and with such a locale every one is
+yours. Add `stepUp` — it is given `brand`, `name`, `code`, `expiresIn` and
+`link` — even if you never send it; in JavaScript the same `templates` is
+[`janusMail: the default templates are built in en and fr only — …; stepUp missing`](#janusmail-the-default-templates-are-built-in-en-and-fr-only--with-another-locale-in-locales-pass-every-template-in-templates-names-missing).
+See [Templates](guide/templates.md#what-each-template-is-given).
+
+### `TS2741: Property 'newSignIn' is missing in type '{ … }' but required in type 'JanusMailTemplates<…>'.`
+
+`templates` written before 0.9, with a locale beyond `en` and `fr`: since
+0.9.0 there are twelve templates, and with such a locale every one is
+yours. Add `newSignIn` — it is given `brand`, `name`, `device`, `location`,
+`time` and `link` — even if you never send it; in JavaScript the same
+`templates` is
+[`janusMail: the default templates are built in en and fr only — …; newSignIn missing`](#janusmail-the-default-templates-are-built-in-en-and-fr-only--with-another-locale-in-locales-pass-every-template-in-templates-names-missing).
+See [Templates](guide/templates.md#what-each-template-is-given).
+
+### `TS2345: Argument of type 'StepUpByEmail<…> | StepUpByApp<…>' is not assignable to parameter of type 'Pick<StepUpByEmail<unknown>, …>'.`
+
+What `auth.stepUp.request(user)` answered, passed to `mail.stepUp` without
+checking `via`, on a user type that may have a second factor. The error
+goes on: `Type 'StepUpByApp<…>' is missing the following properties …`,
+naming `code` and `email` — a user whose factor is active confirms with their app, and
+there is nothing to send. Narrow it first:
+
+```ts
+const issued = await auth.stepUp.request(current.user);
+if (issued.via === 'email') await mail.stepUp(issued, { name: current.user.name });
+```
+
+A sign-in code's answer given to `stepUp` reads `Property 'via' is missing
+in type 'IssuedCode<…>'`: a sign-in code signs in, it confirms no action —
+send it with `signInCode`.
+
 ### `TS2322: Type '"de"' is not assignable to type '"en" | "fr"'.`
 
 A `fallbackLocale` outside `locales`. Add it to `locales` — with every
@@ -681,10 +753,24 @@ has no codes to count; check it first, as in
 
 ### `TS2322: Type 'Date' is not assignable to type 'string'.`
 
-On `when`: the event's `occurredAt` passed as it is. `when` is the text the
-e-mail shows — format it in the recipient's locale and time zone first:
+On `when`: the event's `occurredAt` passed as it is — or, on `newSignIn`'s
+`time`, the session's `createdAt`. Both are the text the e-mail shows —
+format the date in the recipient's locale and time zone first:
 
 ```ts
 const when = new Intl.DateTimeFormat(user.locale, { dateStyle: 'long', timeStyle: 'short', timeZone: 'Europe/Paris' })
 	.format(event.occurredAt);
 ```
+
+### `TS2322: Type 'string | null' is not assignable to type 'string'.`, on `location`
+
+Also, without `exactOptionalPropertyTypes` in your tsconfig:
+`Type 'string | null' is not assignable to type 'string | undefined'.`
+
+On `newSignIn`'s `location`: a geo-IP lookup's answer, `null` when it found
+nothing, passed as it is. `location` is optional: leave it out, and the
+e-mail shows `—`:
+
+```ts
+await mail.newSignIn(to, { device, time, ...(city === null ? {} : { location: city }) });
+```