@nxgt/janus 0.16.0 → 0.17.0

package/docs/README.md

@@ -18,7 +18,8 @@ below are defined once, in [Words](guide/vocabulary.md#words).
 | [Signing in with an e-mailed code](guide/sign-in-code.md) | You are signing users in with a six-digit code sent by e-mail — with no password, or beside one: requesting it without telling who exists, keeping the challenge, the attempts and the errors |
 | [The second factor](guide/second-factor.md) | You are turning on TOTP codes: making and rotating the sealing keys, the QR code, `signIn`'s `status`, confirming a challenge, recovery codes for a lost phone, disabling |
 | [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 |
-| [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 or is deleted — to queue it, sync it, or send it as a webhook |
+| [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 |
 
 ### Permissions — `@nxgt/janus/permissions`

package/docs/guide/devices.md

@@ -0,0 +1,428 @@
+# Devices — a sign-in from a new device
+
+This page is for telling a user when their account is signed in from a
+device they had not signed in from: wiring `devices`, giving each sign-in the
+**device token** the client holds, keeping it in a cookie, and sending the
+notice.
+
+```ts
+import { z } from 'zod';
+import { createMemoryStores, janus, scryptHasher } from '@nxgt/janus';
+
+const auth = janus({
+	user: z.object({ email: z.email() }),
+	password: { login: 'email' },
+	store: createMemoryStores(),
+	hasher: scryptHasher(),
+	devices: { keys: [{ id: '2026-09', key: process.env.DEVICES_KEY ?? '' }] }, // openssl rand -base64 32
+});
+
+const credentials = { email: 'ada@example.com', password: 'correct horse' };
+
+const signedUp = await auth.signUp(credentials, { device: null }); // no token yet
+signedUp.deviceToken; // 'd1.2026-09.…' — keep it in a long-lived cookie
+signedUp.newDevice; // false: a sign-up is never new
+
+const again = await auth.signIn(credentials, { device: signedUp.deviceToken });
+again.newDevice; // false: the device Ada signed up on
+
+const elsewhere = await auth.signIn(credentials, { device: null }); // a browser with no cookie
+elsewhere.newDevice; // true — and the event user.newDeviceSignedIn was sent
+elsewhere.deviceToken; // a fresh token, for that browser's cookie
+```
+
+**Nothing is stored.** A device token is a random device id and a keyed hash
+binding it to the user: the client keeps it, and it proves "this user signed
+in on this device before" on its own. The store ports are unchanged, and no
+adapter needs a migration. The words — **device**, **device token** — are
+defined in [the vocabulary](vocabulary.md#identities).
+
+## Wiring
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `devices.keys` | `[SealingKey, ...SealingKey[]]` | — required once `devices` is given | The keys device tokens are signed with. **The first signs, every one checks.** See [Rotating the keys](#rotating-the-keys-and-forgetting-devices) |
+
+Without `devices`, no sign-in may be given a `device`: every answer's
+`newDevice` is `false`, its `deviceToken` `null`, and no
+`user.newDeviceSignedIn` is sent.
+
+```ts
+interface DevicesConfig {
+	readonly keys: readonly [SealingKey, ...SealingKey[]];
+}
+
+interface SealingKey {
+	readonly id: string;  // letters, digits, _ and -, at most 64: written into every token it signs
+	readonly key: string; // 32 random bytes, in base64 or base64url
+}
+```
+
+The keys have the format of [`secondFactor.keys`](second-factor.md#making-a-key),
+and are made the same way:
+
+```sh
+openssl rand -base64 32
+```
+
+Use a key of its own rather than a sealing key of the second factor's: the
+two rotate for different reasons. Keep it where your other secrets are, and
+give **every `janus()` that signs users in the same `devices`** — a token
+signed by an instance whose keys another does not hold is a new device there.
+
+`janus()` refuses a configuration it cannot sign with, with a bare
+`TypeError`:
+
+| Message | Cause |
+| --- | --- |
+| `janus: devices.keys: expected at least one key — [{ id, key }], the first seals` | `keys` missing or empty |
+| `janus: devices.keys: every key needs an id of letters, digits, _ and -, at most 64 of them` | an `id` with a `.`, a space, or over 64 characters |
+| `janus: devices.keys: two keys have the id "<id>"` | a repeated `id` |
+| `janus: devices.keys: the key "<id>" is not 32 bytes in base64 — make one with openssl rand -base64 32` | a key of another length, or not base64 — an environment variable that is not set, say |
+
+`devices: { keys: [] }` is also a compile error.
+
+## Giving a sign-in the device
+
+Every call that opens a session takes `{ device }` as its last argument, a
+`SignInOptions`:
+
+| Call | Given a device |
+| --- | --- |
+| `signUp(input, { device })` | mints the user's first token: `newDevice` is always `false`, and no event is sent — the device they signed up on is known from the start |
+| `signIn(input, { device })` | answers `newDevice` and `deviceToken`; a new device sends `user.newDeviceSignedIn`. With an active second factor, the challenge — see [below](#with-a-second-factor) |
+| `secondFactor.confirm(challenge, code, { device })` | the same, once the code is right |
+| `secondFactor.recover(challenge, code, { device })` | the same, after `user.recoveryCodeUsed` |
+| `signInCode.confirm(challenge, code, { device })` | the same — or a challenge, with an active second factor |
+| `magicLink.confirm(token, { device })` | the same — or a challenge, with an active second factor |
+
+A step-up opens no session, and takes no device. With several user types,
+the calls are the type's: `clinic.staff.signIn(input, { device })`.
+
+What `device` says:
+
+| `device` | Means | The answer |
+| --- | --- | --- |
+| a string | the token the client holds — an earlier answer's `deviceToken` | `newDevice: false` and the same token when it proves this user signed in there; otherwise `newDevice: true` and a fresh token |
+| `null` | the client holds no token yet | `newDevice: true` and a fresh token — `false` on `signUp` |
+| absent | **devices are not tracked for this call** | `newDevice: false`, `deviceToken: null`, no event |
+
+**A token that proves nothing is a new device, never an error.** Malformed,
+forged, another user's, or signed with a key no longer held: the sign-in
+succeeds, answers `newDevice: true` and a fresh token. The value came from a
+request, so nothing about it is refused — only its type, from JavaScript.
+
+**`undefined` is not `null`.** A cookie read as `string | undefined` and
+handed over as it is makes every browser without a cookie untracked: it is
+never given a token, and never reported. With `exactOptionalPropertyTypes`
+in your tsconfig that is a compile error — `TS2379: … Type 'string |
+undefined' is not assignable to type 'string | null'` — and without it, it
+compiles and tracks nothing. Say what you mean:
+
+```ts
+const cookie: string | undefined = readCookie(request, 'device'); // yours
+await auth.signIn(credentials, { device: cookie ?? null });
+```
+
+## What the answer says
+
+`SignedIn` — and so `RecoveredSignIn` — carries two more fields:
+
+```ts
+interface SignedIn<U> {
+	readonly status: 'signedIn';
+	readonly user: U;
+	readonly session: Session;
+	readonly token: string;
+	readonly newDevice: boolean;          // false without a device, and on signUp
+	readonly deviceToken: string | null;  // null without a device: nothing minted
+}
+```
+
+- **`deviceToken`** is what the client keeps, and presents as `device` at its
+  next sign-in: the token it presented, a fresh one for a new device, or the
+  same device signed again with the first key after a
+  [rotation](#rotating-the-keys-and-forgetting-devices). Set the cookie again
+  on every sign-in: it keeps it alive.
+- **`newDevice`** is `true` when the session was opened from a device the
+  user had not signed in from — and `user.newDeviceSignedIn` was then sent.
+
+A test double that builds a `SignedIn` by hand needs both fields:
+`{ …, newDevice: false, deviceToken: null }`.
+
+## With a second factor
+
+A user whose second factor is active gets a challenge from `signIn`, and
+**the challenge carries no device**. Give the device again to
+`secondFactor.confirm` or `secondFactor.recover`, from the same cookie:
+
+```ts
+const result = await auth.signIn(credentials, { device: cookie ?? null });
+if (result.status === 'secondFactor') {
+	// …the next request, with the code:
+	const signedIn = await auth.secondFactor.confirm(result.challenge, code, { device: cookie ?? null });
+	signedIn.newDevice; // decided here, once the code is right
+}
+```
+
+The challenge answer has no `newDevice` and no `deviceToken`, and sends no
+event: nothing is known until the code is. A confirmation given no device is
+untracked, whatever `signIn` was given. The same holds for a
+`signInCode.confirm` or `magicLink.confirm` that answered a challenge.
+
+## Keeping the token: the cookie
+
+The token is made of cookie-value characters — `d1.<key id>.<device id>.<mac>`
+— so it goes into a cookie as it is. Keep it in **its own long-lived cookie**,
+`HttpOnly` and `Secure`, apart from the session cookie: it outlives every
+session, and signing out leaves it, so the device stays known.
+
+With Hono, [`@nxgt/janus-hono`](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus-hono/README.md)
+reads it with `deviceOf(c)` and sets it in `sendSession` whenever the answer
+carries a `deviceToken`:
+
+```ts
+import { deviceOf, sendSession } from '@nxgt/janus-hono';
+
+app.post('/sign-in', async (c) => {
+	const { email, password } = await c.req.json();
+	const signedIn = await auth.signIn({ email, password }, { device: deviceOf(c) });
+	const user = sendSession(c, auth, signedIn); // the session cookie, and the device cookie
+	return c.json({ id: user.id });
+});
+```
+
+Anywhere else, a fetch-style handler sets both cookies itself:
+
+```ts
+const DEVICE = 'device';
+const FOUR_HUNDRED_DAYS = 400 * 24 * 60 * 60; // the longest a browser keeps a cookie
+
+function cookieOf(request: Request, name: string): string | null {
+	const match = request.headers.get('cookie')?.match(new RegExp(`(?:^|;\\s*)${name}=([^;]*)`));
+	return match?.[1] || null; // no cookie, or an empty one: the client holds no token
+}
+
+export async function signIn(request: Request): Promise<Response> {
+	const { email, password } = (await request.json()) as { email: string; password: string };
+	const signedIn = await auth.signIn({ email, password }, { device: cookieOf(request, DEVICE) });
+	const headers = new Headers();
+	headers.append('Set-Cookie', auth.cookie.serialize(signedIn.token, signedIn.session));
+	if (signedIn.deviceToken !== null) {
+		headers.append(
+			'Set-Cookie',
+			`${DEVICE}=${signedIn.deviceToken}; Max-Age=${FOUR_HUNDRED_DAYS}; Path=/; HttpOnly; Secure; SameSite=Lax`,
+		);
+	}
+	return Response.json({ id: signedIn.user.id }, { headers });
+}
+```
+
+A bearer client — a mobile app — keeps `deviceToken` beside its session
+token, and sends it with its next sign-in.
+
+**One cookie holds one user's token.** Two people who share a browser and
+take turns signing in each present the other's token — which proves nothing
+for them — and each gets a new token and a notice at every turn. That is
+the price of storing nothing.
+
+## The event: `user.newDeviceSignedIn`
+
+A sign-in from a new device sends
+[`user.newDeviceSignedIn`](events.md#the-eleven-types) to `janus({ events })`:
+
+```ts
+{
+	id: '0199…',                    // a UUIDv7 minted for this event
+	type: 'user.newDeviceSignedIn',
+	occurredAt: Date,               // the new session's createdAt
+	userId: '0199…',
+	userType: 'user',
+	sessionId: '0199…',             // the session the new device holds
+}
+```
+
+It is the second exception to *the user by id only*, after `formerEmail`:
+`sessionId` names the session the new device holds, so a "this wasn't me"
+page can end that one — `store.sessions.revokeSession(sessionId, new Date())`
+on the store you wired — or every session with
+`auth.signOutEverywhere(user)`. `@nxgt/janus-webhooks` posts the event
+without it: a session id stays in the process.
+
+- **Sent once the sign-in is complete.** A wrong password sends nothing, nor
+  does a `signIn` refused after its session opened — a password written
+  meanwhile — nor a challenge.
+- **After the others.** `secondFactor.recover` sends it after
+  `user.recoveryCodeUsed`; a first proof of the e-mail by
+  [code](sign-in-code.md) or [link](magic-link.md) sends it last, after
+  `user.emailVerified` and what that proof removed.
+- **Never** from `signUp`, from a call given no device, or from a device the
+  token proved.
+
+## The e-mail: `@nxgt/janus-mail`'s `newSignIn`
+
+[`@nxgt/janus-mail`](https://www.npmjs.com/package/@nxgt/janus-mail) sends
+the notice, in English and French — "New sign-in to your account", the
+device, where, when, and a button to your security settings. Every value is
+your text, in the recipient's locale: **Janus sees no IP and no
+`User-Agent`**, so describing the device, formatting the time in the user's
+time zone and finding a location — from a geo-IP of your own, if you have one
+— are yours. Without a location, the e-mail shows `—`.
+
+From the sign-in's answer, where the request is in hand:
+
+```ts
+// `mail` is janusMail({ … }), and the user schema holds a name and a locale.
+const signedIn = await auth.signIn({ email, password }, { device: cookieOf(request, DEVICE) });
+if (signedIn.newDevice) {
+	const { user } = signedIn;
+	await mail.newSignIn(
+		{ name: user.name, email: user.email, locale: user.locale },
+		{
+			device: describeDevice(request.headers.get('user-agent')), // yours: 'Firefox on macOS'
+			time: new Intl.DateTimeFormat(user.locale, { dateStyle: 'long', timeStyle: 'short', timeZone }).format(
+				signedIn.session.createdAt,
+			),
+		},
+	);
+}
+```
+
+Or from the event, which names the user by id alone:
+
+```ts
+const auth = janus({
+	...config,
+	async events(event) {
+		if (event.type !== 'user.newDeviceSignedIn') return;
+		const user = await auth.get(event.userId);
+		const time = new Intl.DateTimeFormat(user.locale, { dateStyle: 'long', timeStyle: 'short', timeZone }).format(
+			event.occurredAt,
+		);
+		await mail.newSignIn({ name: user.name, email: user.email, locale: user.locale }, { device: 'a new device', time });
+	},
+});
+```
+
+The event has no request to describe the device from: send from the answer
+when you want the device named, or put the description in the job your
+route queues.
+
+## What a token proves, and what it does not
+
+A device token is `d1.<key id>.<device id>.<mac>`: 16 random bytes of device
+id, and an HMAC-SHA256 of the user's id and the device id, under a key
+derived (HKDF) from the device key. So:
+
+- **It is bound to the user.** A token copied onto another user's sign-in
+  proves nothing there, and is a new device.
+- **It cannot be forged** without the key, and a changed character proves
+  nothing.
+- **It proves only "this user signed in here before".** It is not a
+  session and not a credential: never authenticate a request with it, never
+  let it skip a password or a second factor. Whoever copies the cookie
+  copies a device, and the worst it buys is one notice fewer.
+
+## Rotating the keys, and forgetting devices
+
+The first key signs; every key checks. To rotate, put a new key first and
+keep the old one:
+
+```ts
+devices: {
+	keys: [
+		{ id: '2027-03', key: process.env.DEVICES_KEY_2027_03 ?? '' }, // signs
+		{ id: '2026-09', key: process.env.DEVICES_KEY_2026_09 ?? '' }, // still checks
+	],
+},
+```
+
+A token signed by the older key is known, and the answer's `deviceToken` is
+the same device signed again with the first: every device that signs in
+moves to the new key by itself.
+
+**Removing a key is the only way to forget devices, and it forgets every
+device that key signed.** Each one is reported new once, at its next
+sign-in, then known again. There is no way to forget one device alone —
+nothing is stored to delete. After a breach, drop every key and start with a
+new one: every user gets one notice per device.
+
+## Errors
+
+All three are bare `TypeError`s — wiring mistakes, thrown before anything is
+written. `<call>` is the call you wrote: `signIn`, `secondFactor.confirm`, or
+`patient.signIn` with several user types.
+
+| Message | Cause |
+| --- | --- |
+| `<call>: a device was given, but janus() has no devices — pass devices: { keys }` | `{ device }`, even `null`, given to a `janus()` wired without `devices` |
+| `<call>: options must be { device }, or left out — the token goes under device` | options that are not an object — the token itself where `{ device }` belongs — from JavaScript or through a cast |
+| `<call>: options.device must be the device token the client holds, or null when it holds none` | a `device` that is neither a string nor `null`, from JavaScript or through a cast |
+
+The configuration's are [above](#wiring). Every call may still reject as it
+did — `CREDENTIALS_INVALID`, `CODE_INVALID`, `STORE_FAILED` — and a device
+never adds a refusal of its own.
+
+## In a test
+
+```ts
+import { expect, it } from 'bun:test';
+import { z } from 'zod';
+import { createMemoryStores, janus, scryptHasher, type UserEvent } from '@nxgt/janus';
+
+it('tells a new device from a known one', async () => {
+	const received: UserEvent[] = [];
+	const auth = janus({
+		user: z.object({ email: z.email() }),
+		password: { login: 'email' },
+		store: createMemoryStores(),
+		hasher: scryptHasher({ cost: 10 }), // fast in tests; keep the default in production
+		devices: { keys: [{ id: 'test', key: Buffer.alloc(32, 7).toString('base64') }] },
+		events: (event) => void received.push(event),
+	});
+	const credentials = { email: 'ada@example.com', password: 'correct horse' };
+	const { deviceToken } = await auth.signUp(credentials, { device: null });
+
+	const known = await auth.signIn(credentials, { device: deviceToken });
+	const fresh = await auth.signIn(credentials, { device: null });
+
+	expect(known.newDevice).toBe(false);
+	expect(fresh.newDevice).toBe(true);
+	expect(received.filter((event) => event.type === 'user.newDeviceSignedIn')).toEqual([
+		expect.objectContaining({ userId: fresh.user.id, sessionId: fresh.session.id }),
+	]);
+});
+```
+
+## Signatures
+
+```ts
+interface SignInOptions {
+	readonly device?: string | null; // the token the client holds, or null for none; absent: untracked
+}
+
+// On every user type with a password:
+signUp(input: In & { readonly password: string }, options?: SignInOptions): Promise<SignedIn<U>>;
+signIn(input: { readonly [K in Login]: string } & { readonly password: string }, options?: SignInOptions): Promise<Answer>;
+secondFactor.confirm(challenge: string, code: string, options?: SignInOptions): Promise<SignedIn<U>>;
+secondFactor.recover(challenge: string, code: string, options?: SignInOptions): Promise<RecoveredSignIn<U>>;
+
+// On every user type with an e-mail:
+signInCode.confirm(challenge: string, code: string, options?: SignInOptions): Promise<Answer>;
+magicLink.confirm(token: string, options?: SignInOptions): Promise<Answer>;
+
+janus({ ..., devices?: DevicesConfig });
+```
+
+`Answer` is `SignInResult<U>` on a type with a password in an instance given
+a `secondFactor`, and `SignedIn<U>` everywhere else. `DevicesConfig`,
+`SignInOptions` and `SealingKey` are exported types of `@nxgt/janus`.
+
+## See also
+
+- [User events](events.md) — `user.newDeviceSignedIn` among the eleven types, and when the listener runs
+- [The second factor](second-factor.md#confirming-the-code-at-sign-in) — the challenge the device is given again after
+- [Sessions](sessions.md) — the session cookie, beside the device cookie
+- [`@nxgt/janus-hono`](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus-hono/docs/guide/routes.md#the-device-cookie) — `deviceOf` and `sendSession`'s device cookie
+- [`@nxgt/janus-mail`](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus-mail/docs/guide/sending.md#newsigninto--device-time-location-) — `newSignIn`
+- [Troubleshooting](../troubleshooting.md#devices) — every sign-in reports a new device, and the messages above

package/docs/guide/events.md

@@ -2,7 +2,8 @@
 
 This page is for hearing what happens to a user once it is written: created,
 e-mail verified, password reset or changed, e-mail changed, second factor
-turned on or off, recovery codes regenerated or one used, deleted. Another service can then follow
+turned on or off, recovery codes regenerated or one used, a sign-in from a
+new device, deleted. Another service can then follow
 without polling. `janus` hands each event to one function you give it;
 **delivering it is yours** — or
 [`@nxgt/janus-webhooks`](https://www.npmjs.com/package/@nxgt/janus-webhooks)'s:
@@ -38,7 +39,7 @@ received[0];
 The words — **user event**, **listener** — are defined in
 [the vocabulary](vocabulary.md#identities).
 
-## The ten types
+## The eleven types
 
 | `type` | Sent by | Not sent |
 | --- | --- | --- |
@@ -51,16 +52,18 @@ The words — **user event**, **listener** — are defined in
 | `user.secondFactorDisabled` | `secondFactor.disable`, when it removed an **active** factor; `signInCode.confirm` and `magicLink.confirm` when their first proof of the e-mail removed one, after `user.emailVerified` and any `user.passwordChanged` — even if an outage interrupts the sign-outs | for a user who had no factor, a factor still waiting for its first code — it was never asked for — or a second `disable` |
 | `user.recoveryCodesRegenerated` | `secondFactor.regenerateRecoveryCodes`: the codes the user held stopped working | for `activate`, whose first codes come with `user.secondFactorEnabled`; for a code refused |
 | `user.recoveryCodeUsed` | `secondFactor.recover`, once the recovery code is spent — even if opening the session then fails | for a recovery code refused. How many are left is not in the event: `secondFactor.recoveryCodesLeft(event.userId)` reads it |
+| `user.newDeviceSignedIn` | `signIn`, `secondFactor.confirm`, `secondFactor.recover`, `signInCode.confirm` and `magicLink.confirm`, given a `device` whose token did not prove this user signed in there — once the sign-in is complete. It carries `sessionId`, the new session's. See [devices](devices.md) | for `signUp`, which mints the first token; for a call given no `device`; for a known device; for a challenge, which opens no session; for a sign-in refused — a wrong password, or a `signIn` refused after its session opened because a password was written meanwhile |
 | `user.deleted` | `delete`, when it deleted the user | for a replay that finds nobody, or an id of another user type |
 
 A reset whose link verifies the e-mail sends both, `user.passwordReset`
 first. **A reset does not also send `user.passwordChanged`**: a listener that
 cares about every new password handles both types, as the `switch` below
 does — one event per write, rather than two a listener would have to tell
-apart. Switch on `type`: the ten are a closed set, and TypeScript refuses an
-eleventh. A new type is a compile error in a `switch` that exhausts them — the
-two recovery-code types, added in 0.10, and the two change types, added in
-0.14, each broke such a `switch` until it handled them.
+apart. Switch on `type`: the eleven are a closed set, and TypeScript refuses a
+twelfth. A new type is a compile error in a `switch` that exhausts them — the
+two recovery-code types, added in 0.10, the two change types, added in
+0.14, and `user.newDeviceSignedIn`, added in 0.17, each broke such a `switch`
+until it handled them.
 
 ```ts
 function onUserEvent(event: UserEvent): void {
@@ -81,6 +84,8 @@ function onUserEvent(event: UserEvent): void {
 			return;
 		case 'user.recoveryCodeUsed':
 			return warnTheUser(event.userId); // a sign-in without their phone — see below
+		case 'user.newDeviceSignedIn':
+			return warnTheUser(event.userId); // @nxgt/janus-mail's newSignIn — see below
 		case 'user.deleted':
 			return forgetEverywhere(event.userId);
 	}
@@ -123,6 +128,37 @@ With several user types, the count is the type's:
 `auth.patient.secondFactor.recoveryCodesLeft(event.userId)`, on
 `event.userType`.
 
+### Telling the user a new device signed in
+
+A sign-in from a device the user had not signed in from is how a stolen
+password shows, so tell the user.
+[`@nxgt/janus-mail`](https://www.npmjs.com/package/@nxgt/janus-mail)'s
+`newSignIn` is the e-mail — the device, the time and, when you know it, the
+place, each your text in the user's locale:
+
+```ts
+// `mail` is janusMail({ … }), and the user schema holds a name and a locale.
+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', // the user's, when you keep it
+			}).format(event.occurredAt); // the new session's createdAt
+			await mail.newSignIn({ name: user.name, locale: user.locale, email: user.email }, { device: 'a new device', time });
+		}
+	},
+});
+```
+
+The event has no request, so it cannot say which device: send from the
+sign-in's answer instead — `if (signedIn.newDevice) …` — to name it from
+the `User-Agent`. [Devices](devices.md#the-e-mail-nxgtjanus-mails-newsignin)
+has both.
+
 ### Telling the user their password or e-mail changed
 
 A password changed by someone else, or an e-mail moved to their inbox, is how
@@ -161,14 +197,14 @@ too, if a reset should be told as well.
 
 ## What an event carries
 
-**The user named by id, and nothing else** — with one exception, below. No
+**The user named by id, and nothing else** — with two exceptions, below. No
 login, no field of the schema, no password or hash, no session or one-time
 token. An event can
 land in a queue, a log or another company's endpoint; whoever receives it
 reads the rest from where it is kept — `auth.get(event.userId)` — if they
 may. A user deleted since is `NOT_FOUND` there, which is the answer.
 
-**The exception is `formerEmail`, on `user.emailChanged` only**: the address
+**The first exception is `formerEmail`, on `user.emailChanged` only**: the address
 the user had before the update, as it was stored, or `null` when they had
 none. Once the write landed it is kept nowhere else, and a notice to the
 inbox the account just left needs it. It is absent from every other type.
@@ -176,6 +212,11 @@ inbox the account just left needs it. It is absent from every other type.
 it reaches no endpoint, no queue and no `onGivingUp` report — send the
 notice from the listener, in the process that wrote.
 
+**The second is `sessionId`, on `user.newDeviceSignedIn` only**: the id of
+the session the new device opened, so a "this wasn't me" page can end that
+one. It is absent from every other type, and `@nxgt/janus-webhooks` strips
+it as it strips `formerEmail`.
+
 `id` is minted for the event, a UUIDv7 that sorts by time. Deliver on it:
 a queue job id, a primary key, a webhook's `webhook-id` header. Two events
 never share one.
@@ -207,6 +248,7 @@ Where the listener runs within a flow, and what an outage does to it:
 | `signInCode.confirm`, `magicLink.confirm` | on an e-mail never verified: **after** every session is revoked and the reset links and second-factor challenges left open are spent — before the write and again after it — and **before** the new session or second-factor challenge is opened. `user.passwordChanged` follows `user.emailVerified` when a password was dropped, then `user.secondFactorDisabled` when an active second factor was removed. An e-mail already verified sends nothing | fails the call; the events are sent all the same, from a `finally`. An outage in the sign-outs before the write fails the call with nothing written and nothing sent: the next code or link proves the e-mail again |
 | `secondFactor.activate`, `secondFactor.regenerateRecoveryCodes`, `secondFactor.disable` | after the write — the flow's last step | — |
 | `secondFactor.recover` | after the recovery code is spent and the session opened — or failed to open | fails the call; the recovery code is spent and the event sent all the same, from a `finally` |
+| `signIn`, `secondFactor.confirm`, `secondFactor.recover`, `signInCode.confirm`, `magicLink.confirm` — `user.newDeviceSignedIn` | **last**, once the session is open and the sign-in complete: after `user.recoveryCodeUsed`, and after the events of a first proof of the e-mail | fails the call, and `user.newDeviceSignedIn` is not sent: it comes only once the sign-in is complete |
 | `resetPassword.confirm` | **after** the sessions opened with the old password are revoked, and the other reset links and the second-factor challenges left open are spent | fails the call; the events are sent all the same, from a `finally` |
 | `delete` | **after** the user's sessions and one-time tokens are removed, and the relation tuples naming them when `relations` is wired | fails the call; the event is sent all the same, from a `finally` |
 
@@ -294,6 +336,7 @@ type UserEventType =
 	| 'user.secondFactorDisabled'
 	| 'user.recoveryCodesRegenerated'
 	| 'user.recoveryCodeUsed'
+	| 'user.newDeviceSignedIn'
 	| 'user.deleted';
 
 interface UserEvent {
@@ -303,6 +346,7 @@ interface UserEvent {
 	readonly userId: Id;
 	readonly userType: string;
 	readonly formerEmail?: string | null; // on user.emailChanged only: the address before, null for none
+	readonly sessionId?: string;          // on user.newDeviceSignedIn only: the session the new device opened
 }
 
 type UserEventListener = (event: UserEvent) => void | Promise<void>;
@@ -317,6 +361,7 @@ see [troubleshooting](../troubleshooting.md#janus-events-must-be-a-function-that
 
 - [E-mail verification and password reset](email-flows.md) — the flows that send `user.emailVerified` and `user.passwordReset`
 - [The second factor](second-factor.md) — `activate` and `disable`, which send `user.secondFactorEnabled` and `user.secondFactorDisabled` — sent too by the first proof of an e-mail by a [code](sign-in-code.md) or a [link](magic-link.md#an-account-someone-else-registered); [recovery codes](second-factor.md#recovery-codes), which send `user.recoveryCodesRegenerated` and `user.recoveryCodeUsed`
+- [Devices](devices.md) — the sign-ins that send `user.newDeviceSignedIn`, the device token and the cookie
 - [Users](users.md) — `create`, `signUp`, `update`, `delete`
 - [Passwords](passwords.md) — `changePassword` and `setPassword`, which send `user.passwordChanged`
 - [Troubleshooting](../troubleshooting.md) — `JANUS_EVENT_FAILED`

package/docs/guide/magic-link.md

@@ -286,6 +286,25 @@ a password, in an instance given a `secondFactor` — and reading `token`
 before narrowing on `status` is a compile error there. Anywhere else it
 answers `SignedIn`.
 
+### The device
+
+With [`janus({ devices })`](devices.md), `confirm` takes the device token
+the client holds as its second argument — read from the device cookie of
+the browser that posts the link's page, which is the one the session opens
+in:
+
+```ts
+const signedIn = await auth.magicLink.confirm(token, { device: cookie ?? null });
+// { status: 'signedIn', …, newDevice, deviceToken }: keep deviceToken in the device cookie
+```
+
+A new device sends `user.newDeviceSignedIn` — last, after the events a first
+proof of the e-mail sends. A link opened on a phone the user never signed in
+from is a new device, even when a laptop asked for it. When `confirm`
+answers a second factor's challenge, the challenge carries no device: give
+it again to `secondFactor.confirm`. Without `{ device }`, nothing is
+tracked.
+
 ### What `confirm` refuses
 
 | Rejects with | When | What to do |
@@ -414,14 +433,16 @@ it('signs in with the e-mailed link, once, and not after fifteen minutes', async
 interface MagicLinkApi<U, Answer = SignedIn<U>> {
 	readonly magicLink: {
 		request(email: string): Promise<(IssuedToken & { readonly user: U }) | null>;
-		confirm(token: string): Promise<Answer>;
+		confirm(token: string, options?: SignInOptions): Promise<Answer>;
 	};
 }
 ```
 
 `Answer` is `SignInResult<U>` on a type with a password in an instance given
-a `secondFactor`, and `SignedIn<U>` everywhere else. `MagicLinkApi` and
-`IssuedToken` are exported from `@nxgt/janus`, as types.
+a `secondFactor`, and `SignedIn<U>` everywhere else. `MagicLinkApi`,
+`IssuedToken` and `SignInOptions` are exported from `@nxgt/janus`, as
+types; `SignInOptions` is `{ device?: string | null }` — see
+[devices](devices.md#giving-a-sign-in-the-device).
 
 ## For an adapter
 
@@ -437,6 +458,7 @@ holds that a link and a sign-in code are never redeemed as each other. See
 - [The second factor](second-factor.md) — the challenge `confirm` answers for a user whose factor is active
 - [E-mail verification and password reset](email-flows.md) — the other flows that send a link, and `TOKEN_STALE`
 - [Sessions](sessions.md) — the cookie the session is sent in
+- [Devices](devices.md) — the `device` `confirm` takes, and the notice of a new one
 - [Errors](errors.md) — every code and its status
 - [Troubleshooting](../troubleshooting.md#sign-in-links) — by the message you see
 - [`@nxgt/janus-telemetry`](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus-telemetry/docs/guide/tracing.md#a-link-sent-by-e-mail) — the events a sign-in by link writes