@nxgt/janus-mail 0.7.1 → 0.9.0

package/README.md

@@ -2,8 +2,8 @@
 
 The e-mails of [`@nxgt/janus`](https://www.npmjs.com/package/@nxgt/janus)'s
 flows, ready to send: **e-mail verification, password reset, sign-in code,
-sign-in link, password changed, e-mail changed, two-factor authentication turned on or
-off, a recovery code used, and a welcome to a new user**, in English and
+sign-in link, a step-up's confirmation code, password changed, e-mail changed, two-factor authentication turned on or
+off, a recovery code used, a sign-in from a new device, and a welcome to a new user**, in English and
 French, with your brand
 in them. `@nxgt/janus` sends no e-mail — its flows answer what to send — and
 this package turns that answer into an e-mail and hands it to any
@@ -48,7 +48,7 @@ bun add -d typescript
 
 Three peers, all required: `@nxgt/mail` (0.1 or later, below 2 — 1.0 and
 its transports included), which defines the `Mailer` port and the errors;
-`@nxgt/janus` (0.15), whose flows' answers the methods take — types only,
+`@nxgt/janus` (0.17), whose flows' answers the methods take — types only,
 nothing of it is loaded; and `typescript` (6). **No Maizzle, no Vue, no
 Tailwind**: they run at this package's build, not in yours.
 
@@ -65,12 +65,12 @@ needs Node `^22.22.3`, `^24.15.0` or `>=26`, for Maizzle — see
 
 | Export | What it is |
 | --- | --- |
-| `janusMail(options)` | The e-mails, over your mailer: `verifyEmail`, `resetPassword`, `signInCode`, `magicLink`, `passwordChanged`, `emailChanged`, `twoFactorEnabled`, `twoFactorDisabled`, `recoveryCodeUsed`, `welcome`, and `templates` and `locales`. Options: `mailer`, `from`, `replyTo?`, `brand`, `links` (`verifyEmail`, `resetPassword`, `secureAccount`, `getStarted`, and `recoveryCodes?` and `magicLink?`), `locales?`, `fallbackLocale?`, `templates?`, `clock?`. A wrong option is a bare `TypeError`, thrown here |
-| `janusTemplates()` | The ten default templates alone, each `(variables & { locale }) => Rendered` |
+| `janusMail(options)` | The e-mails, over your mailer: `verifyEmail`, `resetPassword`, `signInCode`, `magicLink`, `stepUp`, `passwordChanged`, `emailChanged`, `twoFactorEnabled`, `twoFactorDisabled`, `recoveryCodeUsed`, `newSignIn`, `welcome`, and `templates` and `locales`. Options: `mailer`, `from`, `replyTo?`, `brand`, `links` (`verifyEmail`, `resetPassword`, `secureAccount`, `getStarted`, and `recoveryCodes?` and `magicLink?`), `locales?`, `fallbackLocale?`, `templates?`, `clock?`. A wrong option is a bare `TypeError`, thrown here |
+| `janusTemplates()` | The twelve default templates alone, each `(variables & { locale }) => Rendered` |
 | `JanusMail<L>`, `JanusMailOptions<L>` | What `janusMail()` answers and takes, for the locales `L` |
-| `JanusMailTemplate<V, L>`, `JanusMailTemplates<L>`, `JanusMailTemplateName` | One template, the ten of them, and their names |
-| `JanusMailVariables` | What each template is given: `brand`, and `name`, `link`, `code`, `expiresIn`, `newEmail`, `when` or `recoveryCodesLeft` as its e-mail needs |
-| `JanusMailSendOptions` | The third argument of `verifyEmail`, `resetPassword`, `signInCode` and `magicLink`: `{ expiresIn? }`, the expiry as text, over the one derived |
+| `JanusMailTemplate<V, L>`, `JanusMailTemplates<L>`, `JanusMailTemplateName` | One template, the twelve of them, and their names |
+| `JanusMailVariables` | What each template is given: `brand`, and `name`, `link`, `code`, `expiresIn`, `newEmail`, `when`, `recoveryCodesLeft`, or `device`, `time` and `location`, as its e-mail needs |
+| `JanusMailSendOptions` | The third argument of `verifyEmail`, `resetPassword`, `signInCode`, `magicLink` and `stepUp`: `{ expiresIn? }`, the expiry as text, over the one derived |
 | `JanusMailLocale` | `'en' \| 'fr'`: the locales the defaults are built in |
 | `JanusMailLinks`, `Recipient` | The `links` option; who an e-mail is for — `{ name, locale? }` |
 
@@ -88,14 +88,16 @@ class. To retry a `MailFailure` or trace each send, wrap the mailer you pass:
 | `resetPassword(issued, to, options?)` | `issued` from `auth.resetPassword.request(email)`, checked for `null`; a link from `links.resetPassword(issued.token)`, and how long it lasts | `issued.email` |
 | `signInCode(issued, to?, options?)` | `issued.code` from `auth.signInCode.request(email)`, and how long it lasts — **never the challenge** | `issued.email` |
 | `magicLink(issued, to?, options?)` | `issued` from `auth.magicLink.request(email)`, checked for `null`; a link from `links.magicLink(issued.token)`, and how long it lasts. A `TypeError` without `links.magicLink` | `issued.email` |
+| `stepUp(issued, to, options?)` | `issued.code` from `auth.stepUp.request(user)`, narrowed to `via: 'email'`, and how long it lasts, greeting `to.name`, with `links.secureAccount()` — **never the challenge**. A `TypeError` for `via: 'secondFactor'` | `issued.email` |
 | `passwordChanged(to)` | A notice, with `links.secureAccount()` | `to.email` |
 | `emailChanged(to)` | A notice naming `to.newEmail`, with `links.secureAccount()` | `to.formerEmail` |
 | `twoFactorEnabled(to)` | A notice: two-factor authentication was turned on, with `links.secureAccount()` | `to.email` |
 | `twoFactorDisabled(to)` | A notice: two-factor authentication was turned off, with `links.secureAccount()` | `to.email` |
 | `recoveryCodeUsed(to, { when, recoveryCodesLeft })` | A notice: a recovery code was used, `when`, and how many are left — "You have 9 recovery codes left." — with `links.recoveryCodes()`, else `links.secureAccount()` | `to.email` |
+| `newSignIn(to, { device, time, location? })` | A notice: the account was signed in from a new device — which device, `time`, and `location`, `—` when left out — with `links.secureAccount()` | `to.email` |
 | `welcome(to)` | A welcome to a new user — "Welcome, Ada" — with `links.getStarted()` | `to.email` |
 
-The four e-mails of a link or a code say how long it lasts — "This link
+The five e-mails of a link or a code say how long it lasts — "This link
 expires in 1 hour.", "Ce lien expire dans 1 heure." — from the flow's
 `issued.expiresAt`: the time left at send time, rounded to the minute, then
 down to the largest whole unit (days, hours or minutes), formatted with
@@ -156,6 +158,23 @@ scanners open every link in an e-mail, and one that signs in on `GET` signs
 in for the scanner. [`@nxgt/janus`'s sign-in link guide](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/magic-link.md)
 has that page.
 
+### Confirming a sensitive action — the step-up
+
+```ts
+const issued = await auth.stepUp.request(current.user); // the user of the session
+if (issued.via === 'email') {
+	await mail.stepUp(issued, { name: current.user.name, locale: current.user.locale }); // "Your confirmation code"
+}
+return Response.json({ challenge: issued.challenge, via: issued.via }); // the challenge stays with the user
+```
+
+A user whose second factor is active confirms with their app
+(`via: 'secondFactor'`): there is nothing to send. The e-mail names no
+action, and its **Secure my account** button links to
+`links.secureAccount()`, for a user who asked for nothing.
+[`@nxgt/janus`'s step-up guide](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus/docs/guide/step-up.md)
+has the confirming route.
+
 ### Saying the expiry yourself
 
 ```ts
@@ -273,6 +292,45 @@ récupération." — or the sentence itself, as text. The button links to
 `links.recoveryCodes()`, where the user regenerates their codes, and to
 `links.secureAccount()` when you give no `recoveryCodes`.
 
+### Telling a user a new device signed in
+
+`@nxgt/janus` 0.17, given `janus({ devices })` and a sign-in's `{ device }`,
+answers `newDevice: true` for a device the user had not signed in from, and
+sends `user.newDeviceSignedIn`. Send the notice from the sign-in's answer,
+where the request is in hand to name the device:
+
+```ts
+const signedIn = await auth.signIn({ email, password }, { device: cookie ?? null });
+if (signedIn.newDevice) {
+	const { name, email, locale } = signedIn.user;
+	const time = new Intl.DateTimeFormat(locale, { dateStyle: 'long', timeStyle: 'short', timeZone: 'Europe/Paris' })
+		.format(signedIn.session.createdAt);
+	await mail.newSignIn({ name, email, locale }, { device: 'Firefox on macOS', time }); // "New sign-in to your account"
+}
+```
+
+or from the event, which names the user by id alone:
+
+```ts
+const auth = janus({
+	...config,
+	async events(event) {
+		if (event.type === 'user.newDeviceSignedIn') {
+			const user = await auth.get(event.userId);
+			const time = new Intl.DateTimeFormat(user.locale, { dateStyle: 'long', timeStyle: 'short', timeZone: 'Europe/Paris' })
+				.format(event.occurredAt);
+			await mail.newSignIn({ name: user.name, email: user.email, locale: user.locale }, { device: 'a new device', time });
+		}
+	},
+});
+```
+
+Every value is your text, in the recipient's locale: `device` described
+from the request's `User-Agent`, `time` formatted in their time zone.
+**`@nxgt/janus` sees no IP**, so `location` is yours to work out — from a
+geo-IP of your own — and an e-mail without one shows `—` in its place. The
+button links to `links.secureAccount()`.
+
 ### Replacing a template
 
 Any template can be your own function — React Email, a string, another
@@ -361,14 +419,27 @@ it.** An application that sends no sign-in link leaves it out; calling
 rendered or sent. Unlike `recoveryCodes`, it has no fallback: no other page
 can carry the token.
 
+**Leave `location` out when you do not know it.** A geo-IP lookup that found
+nothing answers `null`, which is a compile error here and, in JavaScript,
+`janusMail.newSignIn: location must be a string`: spread it in only when it
+is a string — `...(city === null ? {} : { location: city })` — and the
+e-mail shows `—`.
+
+**Check `via` before `stepUp`.** `auth.stepUp.request(user)` answers
+`via: 'secondFactor'` — no code, no address — for a user whose second
+factor is active. Passed un-narrowed it is a compile error; in JavaScript,
+`janusMail.stepUp: via must be 'email' — …`, a `TypeError` before anything
+is sent. Unlike `signInCode`, `stepUp` takes the recipient: it greets the
+user by name.
+
 **Templates are own properties.** A class's methods live on its prototype
 and are refused with a `TypeError`; its fields (`signInCode = (variables) =>
 …`) pass.
 
 **A locale beyond `en` and `fr` needs every template.** The defaults are
-built in those two only, so `locales: ['en', 'fr', 'de']` without all ten
-templates — `recoveryCodeUsed` included, since 0.5, and `magicLink`, since
-0.7 — is a compile error, and a `TypeError` in JavaScript.
+built in those two only, so `locales: ['en', 'fr', 'de']` without all twelve
+templates — `recoveryCodeUsed` included, since 0.5, `magicLink`, since
+0.7, `stepUp`, since 0.8, and `newSignIn`, since 0.9 — is a compile error, and a `TypeError` in JavaScript.
 
 **The brand is text only.** `brand: 'Acme'` is written in the header, the
 body and the footer, escaped: no logo, no link, no markup. For those, replace
@@ -425,8 +496,8 @@ The symptoms and fixes are in [troubleshooting](docs/troubleshooting.md).
 
 ## Type safety, counted
 
-**Forty plausible mistakes, forty refused at compile time.**
-Seven files hold one `@ts-expect-error` per mistake, beside the calls that
+**Fifty plausible mistakes, fifty refused at compile time.**
+Nine files hold one `@ts-expect-error` per mistake, beside the calls that
 must keep compiling:
 [`test/types/send-refusals.ts`](test/types/send-refusals.ts) the eight of a
 send, 1 to 8;
@@ -440,9 +511,14 @@ the two-factor notices and the welcome, 26 to 29;
 [`test/types/recovery-refusals.ts`](test/types/recovery-refusals.ts) the
 five of the recovery code notice, 30 to 34;
 [`test/types/change-refusals.ts`](test/types/change-refusals.ts) the two of
-the e-mail change notice sent on its event, 35 and 36; and
+the e-mail change notice sent on its event, 35 and 36;
 [`test/types/magic-link-refusals.ts`](test/types/magic-link-refusals.ts) the
-four of the sign-in link, 37 to 40:
+four of the sign-in link, 37 to 40;
+[`test/types/step-up-refusals.ts`](test/types/step-up-refusals.ts) the six
+of the step-up's code, 41 to 46, beside the names of the templates, held to
+the twelve; and
+[`test/types/new-sign-in-refusals.ts`](test/types/new-sign-in-refusals.ts)
+the four of the new sign-in notice, 47 to 50:
 
 1. A sign-in code given to `verifyEmail`: it has no token.
 2. A one-time token given to `signInCode`: it has no code.
@@ -484,8 +560,18 @@ four of the sign-in link, 37 to 40:
 38. `magicLink.request`'s answer, not checked for `null` first.
 39. The token alone given to `magicLink`, rather than what the flow answered.
 40. `links.magicLink` computed asynchronously.
-
-In JavaScript, 19 to 23, 26 to 28, 30 to 33 and 35 to 40 are a `TypeError` at send
+41. `stepUp.request`'s answer not narrowed to `via: 'email'`: an app's step-up has nothing to send.
+42. A step-up confirmed with the user's app, narrowed to it, given to `stepUp`.
+43. A sign-in code given to `stepUp`: it signs in, it confirms no action.
+44. A one-time token given to `stepUp`: it has no code.
+45. `stepUp` without the recipient: its e-mail greets the user by name.
+46. The step-up's `user` given as the recipient when the user type has no name.
+47. The `user.newDeviceSignedIn` event itself given to `newSignIn`: it has neither a name nor an address.
+48. `newSignIn` without the device and the time.
+49. `time` given as the session's `Date` rather than the text in the recipient's locale and time zone.
+50. A location lookup's `null` passed as `location`, rather than leaving it out.
+
+In JavaScript, 19 to 23, 26 to 28, 30 to 33 and 35 to 50 are a `TypeError` at send
 time instead, naming the call or the field, and 25, 29 and 34 one from
 `janusMail()`.
 

package/dist/generated/mail.d.ts

@@ -1,5 +1,12 @@
 /** The e-mails of the build, each with the variables it takes when it is sent. */
 export interface MailEmails {
+    "confirm-action": {
+        readonly brand: string | number;
+        readonly code: string | number;
+        readonly expiresIn: string | number;
+        readonly link: string;
+        readonly name: string | number;
+    };
     "email-changed": {
         readonly brand: string | number;
         readonly link: string;
@@ -11,6 +18,14 @@ export interface MailEmails {
         readonly expiresIn: string | number;
         readonly link: string;
     };
+    "new-sign-in": {
+        readonly brand: string | number;
+        readonly device: string | number;
+        readonly link: string;
+        readonly location: string | number;
+        readonly name: string | number;
+        readonly time: string | number;
+    };
     "password-changed": {
         readonly brand: string | number;
         readonly link: string;

package/dist/generated/mail.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mail.d.ts","sourceRoot":"","sources":["../../src/generated/mail.ts"],"names":[],"mappings":"AAGA,kFAAkF;AAClF,MAAM,WAAW,UAAU;IAC1B,eAAe,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAChJ,YAAY,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9G,kBAAkB,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAC/G,oBAAoB,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAC9L,gBAAgB,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAClJ,cAAc,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACzH,qBAAqB,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAClH,oBAAoB,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACjH,cAAc,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAChJ,SAAS,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;CACtG"}
+{"version":3,"file":"mail.d.ts","sourceRoot":"","sources":["../../src/generated/mail.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -2,8 +2,9 @@
  * `@nxgt/janus-mail` — the e-mails of `@nxgt/janus`'s flows.
  *
  * `@nxgt/janus` sends no e-mail: its flows answer what to send — a one-time
- * token, a sign-in code, a sign-in link's token, the address — and this package turns that answer
- * into an e-mail and hands it to an `@nxgt/mail` transport. Ten e-mails, in
+ * token, a sign-in code, a sign-in link's token, a step-up's code, the
+ * address — and this package turns that answer into an e-mail and hands it
+ * to an `@nxgt/mail` transport. Twelve e-mails, in
  * English and French, prebuilt with Maizzle when this package is built, and
  * filled at send time with your brand, the recipient's name and your links.
  * Any of them can be replaced by a function of your own.

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,YAAY,EACX,SAAS,EACT,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,SAAS,GACT,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,YAAY,EACX,SAAS,EACT,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,SAAS,GACT,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -117,6 +117,32 @@ function expiringMails(options) {
   };
 }
 
+// src/new-sign-in-mail.ts
+var METHOD = "newSignIn";
+var NO_LOCATION = "—";
+function locationOf(signIn) {
+  const given = typeof signIn === "object" && signIn !== null ? signIn.location : undefined;
+  if (given === undefined)
+    return NO_LOCATION;
+  return field(METHOD, signIn, "location");
+}
+function newSignInMail(options) {
+  const { brand, links } = options;
+  return {
+    async newSignIn(to, signIn) {
+      return send(options, METHOD, field(METHOD, to, "email"), {
+        brand,
+        name: field(METHOD, to, "name"),
+        device: field(METHOD, signIn, "device"),
+        location: locationOf(signIn),
+        time: field(METHOD, signIn, "time"),
+        link: link(METHOD, links.secureAccount(), "secureAccount()"),
+        locale: localeFor(options, to)
+      });
+    }
+  };
+}
+
 // src/notice-mails.ts
 function noticeMails(options) {
   const { brand, links } = options;
@@ -198,24 +224,36 @@ function defaultRenderer() {
 }
 
 // src/templates.ts
+var recoveryCodeUsed = ({
+  brand,
+  name,
+  when,
+  recoveryCodesLeft,
+  link,
+  locale
+}) => defaultRenderer().render("recovery-code-used", { brand, name, when, recoveryCodesLeft, link }, { locale });
+var newSignIn = ({
+  brand,
+  name,
+  device,
+  location,
+  time,
+  link,
+  locale
+}) => defaultRenderer().render("new-sign-in", { brand, name, device, location, time, link }, { locale });
 function janusTemplates() {
   return Object.freeze({
     verifyEmail: ({ brand, name, link, expiresIn, locale }) => defaultRenderer().render("verify-email", { brand, name, link, expiresIn }, { locale }),
     resetPassword: ({ brand, name, link, expiresIn, locale }) => defaultRenderer().render("reset-password", { brand, name, link, expiresIn }, { locale }),
     signInCode: ({ brand, code, expiresIn, locale }) => defaultRenderer().render("sign-in-code", { brand, code, expiresIn }, { locale }),
     magicLink: ({ brand, link, expiresIn, locale }) => defaultRenderer().render("magic-link", { brand, link, expiresIn }, { locale }),
+    stepUp: ({ brand, name, code, expiresIn, link, locale }) => defaultRenderer().render("confirm-action", { brand, name, code, expiresIn, link }, { locale }),
     passwordChanged: ({ brand, name, link, locale }) => defaultRenderer().render("password-changed", { brand, name, link }, { locale }),
     emailChanged: ({ brand, name, link, newEmail, locale }) => defaultRenderer().render("email-changed", { brand, name, link, newEmail }, { locale }),
     twoFactorEnabled: ({ brand, name, link, locale }) => defaultRenderer().render("two-factor-enabled", { brand, name, link }, { locale }),
     twoFactorDisabled: ({ brand, name, link, locale }) => defaultRenderer().render("two-factor-disabled", { brand, name, link }, { locale }),
-    recoveryCodeUsed: ({
-      brand,
-      name,
-      when,
-      recoveryCodesLeft,
-      link,
-      locale
-    }) => defaultRenderer().render("recovery-code-used", { brand, name, when, recoveryCodesLeft, link }, { locale }),
+    recoveryCodeUsed,
+    newSignIn,
     welcome: ({ brand, name, link, locale }) => defaultRenderer().render("welcome", { brand, name, link }, { locale })
   });
 }
@@ -226,11 +264,13 @@ var TEMPLATE_NAMES = [
   "resetPassword",
   "signInCode",
   "magicLink",
+  "stepUp",
   "passwordChanged",
   "emailChanged",
   "twoFactorEnabled",
   "twoFactorDisabled",
   "recoveryCodeUsed",
+  "newSignIn",
   "welcome"
 ];
 var SYSTEM_CLOCK = Object.freeze({ now: () => new Date });
@@ -386,18 +426,18 @@ function codesLeftText(locale, count) {
 }
 
 // src/recovery-mail.ts
-var METHOD = "recoveryCodeUsed";
+var METHOD2 = "recoveryCodeUsed";
 var isCount = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
 function codesLeft(used, locale) {
   const given = typeof used === "object" && used !== null ? used.recoveryCodesLeft : undefined;
   if (typeof given === "string")
     return given;
   if (!isCount(given)) {
-    throw new TypeError(`janusMail.${METHOD}: recoveryCodesLeft must be a count — a whole number, 0 or more — or the sentence to show`);
+    throw new TypeError(`janusMail.${METHOD2}: recoveryCodesLeft must be a count — a whole number, 0 or more — or the sentence to show`);
   }
   const text = codesLeftText(locale, given);
   if (text === undefined) {
-    throw new TypeError(`janusMail.${METHOD}: recoveryCodesLeft must be the sentence to show in a locale the default e-mails are not built in`);
+    throw new TypeError(`janusMail.${METHOD2}: recoveryCodesLeft must be the sentence to show in a locale the default e-mails are not built in`);
   }
   return text;
 }
@@ -406,12 +446,38 @@ function recoveryMail(options) {
   return {
     async recoveryCodeUsed(to, used) {
       const locale = localeFor(options, to);
-      return send(options, METHOD, field(METHOD, to, "email"), {
+      return send(options, METHOD2, field(METHOD2, to, "email"), {
         brand,
-        name: field(METHOD, to, "name"),
-        when: field(METHOD, used, "when"),
+        name: field(METHOD2, to, "name"),
+        when: field(METHOD2, used, "when"),
         recoveryCodesLeft: codesLeft(used, locale),
-        link: links.recoveryCodes === undefined ? link(METHOD, links.secureAccount(), "secureAccount()") : link(METHOD, links.recoveryCodes(), "recoveryCodes()"),
+        link: links.recoveryCodes === undefined ? link(METHOD2, links.secureAccount(), "secureAccount()") : link(METHOD2, links.recoveryCodes(), "recoveryCodes()"),
+        locale
+      });
+    }
+  };
+}
+
+// src/step-up-mail.ts
+var METHOD3 = "stepUp";
+function checkVia(issued) {
+  const via = typeof issued === "object" && issued !== null ? issued.via : undefined;
+  if (via !== "email") {
+    throw new TypeError(`janusMail.${METHOD3}: via must be 'email' — a step-up confirmed with the user's app sends no e-mail`);
+  }
+}
+function stepUpMail(options) {
+  const { brand, links } = options;
+  return {
+    async stepUp(issued, to, sendOptions) {
+      checkVia(issued);
+      const locale = localeFor(options, to);
+      return send(options, METHOD3, field(METHOD3, issued, "email"), {
+        brand,
+        name: field(METHOD3, to, "name"),
+        code: field(METHOD3, issued, "code"),
+        expiresIn: expiresInFor(METHOD3, issued, locale, sendOptions, options.clock),
+        link: link(METHOD3, links.secureAccount(), "secureAccount()"),
         locale
       });
     }
@@ -425,6 +491,8 @@ function janusMail(options) {
     ...expiringMails(resolved),
     ...noticeMails(resolved),
     ...recoveryMail(resolved),
+    ...newSignInMail(resolved),
+    ...stepUpMail(resolved),
     templates: resolved.templates,
     locales: resolved.locales
   });
@@ -435,5 +503,5 @@ export {
   janusTemplates
 };
 
-//# debugId=45A006F2B09A6D7D64756E2164756E21
+//# debugId=F5414A38AA5F17CC64756E2164756E21
 //# sourceMappingURL=index.js.map