@nxgt/janus 0.16.1 → 0.17.0

package/docs/guide/second-factor.md

@@ -213,6 +213,8 @@ interface SignedIn<U> {
 	readonly user: U;
 	readonly session: Session;
 	readonly token: string;
+	readonly newDevice: boolean;         // with janus({ devices }): see devices.md
+	readonly deviceToken: string | null;
 }
 
 interface SecondFactorRequired {
@@ -284,6 +286,26 @@ const signedIn = await auth.secondFactor.confirm(challenge, code);
 | `USER_INACTIVE` | the user was deactivated since `signIn`. The challenge is spent | answer 403, as `signIn` would |
 | `SECOND_FACTOR_NOT_ENROLLED` | the factor was disabled since `signIn`. The challenge is spent | sign in again: the password alone now opens a session |
 
+### Giving the device again
+
+With [`janus({ devices })`](devices.md), the challenge carries **no
+device**: whatever `signIn` was given, `confirm` — and `recover` — decide
+whether the device is new only from what they are given themselves. Pass
+the same `{ device }` again, from the same cookie:
+
+```ts
+const result = await auth.signIn({ email, password }, { device: cookie ?? null });
+if (result.status === 'secondFactor') {
+	// the next request, with the code — and the device cookie again
+	const signedIn = await auth.secondFactor.confirm(challenge, code, { device: cookie ?? null });
+	// { status: 'signedIn', …, newDevice, deviceToken }: user.newDeviceSignedIn sent for a new one
+}
+```
+
+A confirmation given no device is untracked: `newDevice: false`,
+`deviceToken: null`, no event. The challenge answer itself has neither
+field, and sends nothing.
+
 ### Attempts
 
 A challenge takes **five attempts**. Every call to `confirm` counts one, in
@@ -392,7 +414,7 @@ and `recoveryCodesLeft` says how many remain.
 type RecoveredSignIn<U> = SignedIn<U> & { readonly recoveryCodesLeft: number };
 
 const signedIn = await auth.secondFactor.recover(challenge, ' 7K2MQ X9D4C ');
-// { status: 'signedIn', user, session, token, recoveryCodesLeft: 9 }
+// { status: 'signedIn', user, session, token, newDevice, deviceToken, recoveryCodesLeft: 9 }
 ```
 
 - **Read as the user may type it**: case, spaces and dashes are ignored, `o`
@@ -421,7 +443,8 @@ at the same moment, exactly one gets a session.
 `recover` sends a [`user.recoveryCodeUsed` event](events.md) once the code is
 spent — even if opening the session then fails. It is the one to tell the
 user about: a recovery code used by someone else is a sign-in without their
-phone.
+phone. Given a [`device`](devices.md) that is new, it sends
+`user.newDeviceSignedIn` after it.
 
 ### Counting what is left
 
@@ -875,8 +898,8 @@ interface SecondFactorApi<U> {
 		activate(user: UserRef, code: string, options?: WriteOptions): Promise<RecoveryCodesIssued<U>>;
 		regenerateRecoveryCodes(user: UserRef, code: string, options?: WriteOptions): Promise<RecoveryCodesIssued<U>>;
 		disable(user: UserRef, options?: WriteOptions): Promise<U>;
-		confirm(challenge: string, code: string): Promise<SignedIn<U>>;
-		recover(challenge: string, code: string): Promise<RecoveredSignIn<U>>; // code: a recovery code
+		confirm(challenge: string, code: string, options?: SignInOptions): Promise<SignedIn<U>>;
+		recover(challenge: string, code: string, options?: SignInOptions): Promise<RecoveredSignIn<U>>; // code: a recovery code
 		recoveryCodesLeft(user: UserRef): Promise<number | null>; // null: no active factor
 	};
 }
@@ -890,7 +913,8 @@ type RecoveredSignIn<U> = SignedIn<U> & { readonly recoveryCodesLeft: number };
 ```
 
 `RecoveryCodesIssued` and `RecoveredSignIn` are exported types of
-`@nxgt/janus`.
+`@nxgt/janus`. `SignInOptions` is `{ device?: string | null }` — see
+[devices](devices.md#giving-a-sign-in-the-device).
 
 `UserRef` is a user or its id; `WriteOptions` is `{ ifVersion? }`, as on
 every write — see [Users](users.md#ifversion). Every call may also reject
@@ -901,6 +925,7 @@ with `STORE_FAILED`.
 - [Sign-in codes](sign-in-code.md) — a sign-in by e-mailed code, which still asks for an active factor, with the same challenge
 - [Sign-in links](magic-link.md) — a sign-in by e-mailed link, which does the same
 - [Sessions](sessions.md) — the cookie `confirm`'s session is sent in, and `authenticatedAt`
+- [Devices](devices.md) — the `device` `confirm` and `recover` are given again, and the notice of a new one
 - [User events](events.md) — `user.secondFactorEnabled`, `user.secondFactorDisabled`, `user.recoveryCodesRegenerated` and `user.recoveryCodeUsed`
 - [Errors](errors.md) — `CODE_INVALID`, `SECOND_FACTOR_NOT_ENROLLED`, `SECOND_FACTOR_ACTIVE` and their statuses
 - [Writing an adapter](adapters.md#a-users-password-and-second-factor) — what a store keeps of a factor and its recovery codes

package/docs/guide/sessions.md

@@ -168,6 +168,13 @@ const { user, session, token } = result; // status 'signedIn': as above
 its session is sent the same way. See
 [the second factor](second-factor.md#signing-in-switch-on-status).
 
+**With `janus({ devices })`, a second cookie rides beside the session's.**
+A sign-in given `{ device }` answers a `deviceToken` for the client to keep
+in a long-lived cookie of its own, apart from the session cookie: it
+outlives every session, and a sign-out leaves it, so the device stays
+known. `auth.cookie` builds only the session cookie — see
+[devices](devices.md#keeping-the-token-the-cookie) for the device cookie.
+
 `signOutEverywhere(user, { except })` revokes every standing session of a
 user, but the one named, and answers how many it revoked — "sign out
 everywhere else". An `except` that names no session of theirs — an unknown
@@ -237,5 +244,6 @@ cannot be replayed. `Session` is the stored record without that hash: `id`,
 - [Users](users.md) — `signUp`, `signIn`, the configuration
 - [The second factor](second-factor.md) — the challenge `signIn` answers instead of a session
 - [Step-up](step-up.md) — proving again who you are, and `assertFresh`
+- [Devices](devices.md) — the device cookie beside the session cookie, and a sign-in from a new device
 - [E-mail flows](email-flows.md) — verification and password reset
 - [Errors](errors.md) — `STORE_FAILED`, `UNSUPPORTED` and the rest

package/docs/guide/sign-in-code.md

@@ -312,6 +312,22 @@ 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 third argument, and tells a sign-in from a new
+device as `signIn` does:
+
+```ts
+const signedIn = await auth.signInCode.confirm(challenge, code, { 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. 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 |
@@ -499,14 +515,16 @@ it('signs in with the e-mailed code, and not after ten minutes', async () => {
 interface SignInCodeApi<U, Answer = SignedIn<U>> {
 	readonly signInCode: {
 		request(email: string): Promise<IssuedCode<U> | null>;
-		confirm(challenge: string, code: string): Promise<Answer>;
+		confirm(challenge: string, code: 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. `IssuedCode` and
-`SignInCodeApi` are exported from `@nxgt/janus`, as types.
+a `secondFactor`, and `SignedIn<U>` everywhere else. `IssuedCode`,
+`SignInCodeApi` and `SignInOptions` are exported from `@nxgt/janus`, as
+types; `SignInOptions` is `{ device?: string | null }` — see
+[devices](devices.md#giving-a-sign-in-the-device).
 
 ## See also
 
@@ -514,6 +532,7 @@ a `secondFactor`, and `SignedIn<U>` everywhere else. `IssuedCode` and
 - [Sign-in links](magic-link.md) — the same sign-in with a link instead of a code: nothing to type, on whichever device opens it
 - [E-mail verification and password reset](email-flows.md) — the other flows that send an e-mail, 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
 - [`@nxgt/janus-telemetry`](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus-telemetry/docs/guide/tracing.md#a-code-sent-by-e-mail) — the events a sign-in by code writes
 - [Troubleshooting](../troubleshooting.md#sign-in-codes) — by the message you see

package/docs/guide/users.md

@@ -99,6 +99,7 @@ that cuts an emoji in half, say.
 | `tokens.stepUp` | `Duration` | `'10m'` | How long a step-up's challenge — and its e-mailed code — lives. See [step-up](step-up.md) |
 | `signIn.throttle` | `{ attempts?, window? }` or `false` | `{ attempts: 10, window: '15m' }` | Passwords one login may try per window, the right one included, before `signIn` answers `CREDENTIALS_INVALID` with `retryAfter` until the window ends. `false` counts nothing. See [passwords](passwords.md#password-guessing-is-throttled) |
 | `secondFactor` | `{ issuer, keys, challenge? }` | none | A TOTP second factor for every type with a password. Changes what `signIn` answers — see [the second factor](second-factor.md#configuration) |
+| `devices` | `{ keys }` | none | The keys device tokens are signed with, to tell a sign-in from a new device. Without it, no sign-in may be given a `device` — see [devices](devices.md#wiring) |
 | `events` | `UserEventListener` | none | Called with every user event — `user.created`, `user.deleted`, … — after the write, awaited. See [user events](events.md) |
 
 A `Duration` is `'500ms'`, `'30s'`, `'15m'`, `'8h'`, `'7d'`, or a number of
@@ -188,8 +189,8 @@ With a `password`, besides:
 
 | Method | Answers | Rejects with |
 | --- | --- | --- |
-| `signUp(fields & { password })` | `{ status: 'signedIn', user, session, token }` | `USER_INVALID`, `PASSWORD_TOO_SHORT`, `LOGIN_TAKEN` |
-| `signIn({ [login]: string, password })` | `{ status: 'signedIn', user, session, token }` — or, with `secondFactor` configured and the user's factor active, `{ status: 'secondFactor', challenge, expiresAt, userId }`: switch on `status` | `CREDENTIALS_INVALID` — with `retryAfter` once the login is throttled — `USER_INACTIVE`, `HASH_UNSUPPORTED` |
+| `signUp(fields & { password }, { device? })` | `{ status: 'signedIn', user, session, token, newDevice, deviceToken }` — `newDevice` always `false`; a first `deviceToken` when given a `device` ([devices](devices.md)) | `USER_INVALID`, `PASSWORD_TOO_SHORT`, `LOGIN_TAKEN` |
+| `signIn({ [login]: string, password }, { device? })` | `{ status: 'signedIn', user, session, token, newDevice, deviceToken }` — or, with `secondFactor` configured and the user's factor active, `{ status: 'secondFactor', challenge, expiresAt, userId }`: switch on `status` | `CREDENTIALS_INVALID` — with `retryAfter` once the login is throttled — `USER_INACTIVE`, `HASH_UNSUPPORTED` |
 | `findByLogin(login)` | the user, or `null`; the login is normalised first, and one holding a NUL or a lone surrogate is nobody's | |
 | `setPassword(user, password, { ifVersion? })` | the user — an admin's call; spends the user's reset links and second-factor challenges still waiting, and signs nobody out; sends `user.passwordChanged` | `PASSWORD_TOO_SHORT` |
 | `changePassword(user, { current, next }, { ifVersion? })` | the user — the user's own call; spends the user's reset links and second-factor challenges still waiting; sends `user.passwordChanged` | `CREDENTIALS_INVALID`, `PASSWORD_TOO_SHORT` |

package/docs/guide/vocabulary.md

@@ -56,11 +56,12 @@ either finds this row.
 | **spent** | A one-time token or a challenge that can no longer be redeemed — `spentAt` set, `TOKEN_SPENT`, and never unset. Spent by its redemption, by its fifth attempt (a wrong code, or a call through another user type's API), by a redemption after it expired, by a refusal that ends it (`USER_INACTIVE`, `TOKEN_STALE`, `SECOND_FACTOR_NOT_ENROLLED`), or by what ends it early: the next `signInCode.request`, `magicLink.request`, `stepUp.request` or `resetPassword.request` for the same user (at most one of each is live at a time), or a password written by `resetPassword.confirm`, `setPassword` or `changePassword` (every reset link and every second-factor challenge left waiting) | "used up", "invalidated"; "consumed" only in `consumeToken`'s name; "revoked" is a session's |
 | **step** | The thirty-second period a TOTP code belongs to. `lastStep` is the step of the last code accepted, and only a later step counts: that is why a code is accepted once | "window", "period", "counter", in prose |
 | **seal**, **sealing key** | To seal is to encrypt a TOTP secret — AES-256-GCM, bound to the user's id — before a store sees it. A sealing key is one `{ id, key }` of `secondFactor.keys`: the first seals, every one opens | "encrypt", "encryption key", "master key", "pepper" |
-| **token** | Never alone in prose: a *session token* or a *one-time token*. The `tokens` store and the `TOKEN_*` codes are one-time tokens only | |
+| **device**, **device token** | A device is a browser or an app a user signs in from, as the client's long-lived cookie — or a bearer client's storage — tells it. A **device token** is what janus signs for it with `devices.keys`, answers as `deviceToken`, and takes back as `device`: `d1.<key id>.<device id>.<mac>`, bound to one user, stored nowhere. A sign-in from a **new device** — one whose token did not prove this user signed in there — answers `newDevice: true` and sends `user.newDeviceSignedIn`. See [devices](devices.md) | "fingerprint", "trusted device", "remembered browser"; "token" alone |
+| **token** | Never alone in prose: a *session token*, a *one-time token* or a *device token*. The `tokens` store and the `TOKEN_*` codes are one-time tokens only | |
 | **e-mail flow** | `verifyEmail` or `resetPassword`: send a one-time token, then confirm it. `magicLink` sends one too, to sign in; `signInCode` sends a one-time code instead | |
 | **issued** | What a flow answers for the application to send: an `IssuedToken` from `verifyEmail.send`, `resetPassword.request` or `magicLink.request`, an `IssuedCode` from `signInCode.request` — the address with it. `@nxgt/janus-mail` takes it as it is | "result", "payload" |
-| **notice** | An e-mail that tells a user of a change and asks for nothing: *password changed*, *e-mail changed* — the latter sent to the former address — and *two-factor enabled*, *two-factor disabled*. `@nxgt/janus-mail` sends all four | "alert", "notification" |
-| **user event** | What happened to a user, once it is written: `user.created`, `user.emailVerified`, `user.passwordReset`, `user.passwordChanged`, `user.emailChanged`, `user.secondFactorEnabled`, `user.secondFactorDisabled`, `user.recoveryCodesRegenerated`, `user.recoveryCodeUsed`, `user.deleted` — a `UserEvent`, naming the user by id alone — `user.emailChanged` adds `formerEmail` — with an `id` of its own. See [user events](events.md) | "webhook" — a webhook is one way to deliver it; "event" alone where it could be read as `@nxgt/janus-telemetry`'s audit log record — on a page about user events, "the event" is fine |
+| **notice** | An e-mail that tells a user of a change and asks for nothing: *password changed*, *e-mail changed* — the latter sent to the former address — *two-factor enabled*, *two-factor disabled*, *recovery code used* and *new sign-in*. `@nxgt/janus-mail` sends all six | "alert", "notification" |
+| **user event** | What happened to a user, once it is written: `user.created`, `user.emailVerified`, `user.passwordReset`, `user.passwordChanged`, `user.emailChanged`, `user.secondFactorEnabled`, `user.secondFactorDisabled`, `user.recoveryCodesRegenerated`, `user.recoveryCodeUsed`, `user.newDeviceSignedIn`, `user.deleted` — a `UserEvent`, naming the user by id alone — `user.emailChanged` adds `formerEmail`, `user.newDeviceSignedIn` adds `sessionId` — with an `id` of its own. See [user events](events.md) | "webhook" — a webhook is one way to deliver it; "event" alone where it could be read as `@nxgt/janus-telemetry`'s audit log record — on a page about user events, "the event" is fine |
 | **step-up**, **fresh** | A step-up is a signed-in user proving again who they are before a sensitive action — `stepUp.request`, then `stepUp.confirm`, with an e-mailed code or, when their second factor is active, their app's — which moves the session's `authenticatedAt` to now and opens no session. A session is **fresh** for `maxAge` after it proved who it is, at the sign-in or by a step-up; `assertFresh` refuses an older one with `STEP_UP_REQUIRED`. See [step-up](step-up.md) | "re-authentication", "sudo mode", "elevated session"; "recent sign-in" once a step-up counts too |
 | **listener** | The one function `janus({ events })` hands every user event to, after the write and awaited | "handler", "hook", "subscriber" |
 

package/docs/roadmap.md

@@ -70,6 +70,18 @@ Nothing yet.
 The last ten, newest first, each with the version it came in. Everything
 before is in the [CHANGELOG](../CHANGELOG.md).
 
+- **A sign-in from a new device, v0.17.0** — `janus({ devices: { keys } })`,
+  and `{ device }` as the last argument of `signUp`, `signIn`,
+  `secondFactor.confirm`, `secondFactor.recover`, `signInCode.confirm` and
+  `magicLink.confirm`: the device token the client holds, or `null`. Every
+  answer that opens a session says `newDevice` and hands back a
+  `deviceToken` for a long-lived cookie, and a new device sends
+  `user.newDeviceSignedIn`, with the new session's `sessionId`, once the
+  sign-in is complete. Nothing is stored: the token is a device id signed
+  for the user, so the store ports are unchanged. A sign-up is never new, a
+  call given no device is not tracked, and removing a key forgets every
+  device it signed. Breaking for a `switch` that exhausts `UserEventType`,
+  and for a `SignedIn` built by hand. See [devices](guide/devices.md).
 - **The first sign-in by link or code ends a squatter's password and second
   factor, v0.16.0** — when `signInCode.confirm` or `magicLink.confirm`
   proves an e-mail never verified, the password and the second factor with
@@ -152,11 +164,3 @@ before is in the [CHANGELOG](../CHANGELOG.md).
   Maizzle when the package is built, and only filled in at send time, every
   value escaped: no template engine in your server. A transport that fails
   throws, like a store.
-- **A permission id no store can keep is held by nobody** — an object or
-  subject id holding a NUL character or a lone surrogate answers `false` from
-  `can()` and an empty page from `list()`, before any store call, and a
-  `fromField` holding one names nobody, nor does a `lookup` answering one;
-  `grant()` and `revoke()` refuse it with a `TypeError` rather than
-  `STORE_FAILED` on PostgreSQL alone. The relation store suite holds every
-  adapter to reading back every other character in an id exactly as written.
-  — v0.8.3

package/docs/troubleshooting.md

@@ -39,6 +39,7 @@ How the messages are shaped:
 - [`janus: secondFactor.issuer must name your application …`](#janus-secondfactorissuer-must-name-your-application--the-authenticator-app-shows-it-beside-the-account)
 - [`janus: secondFactor.keys: the key "<id>" is not 32 bytes in base64 …`](#janus-secondfactorkeys-the-key-id-is-not-32-bytes-in-base64--make-one-with-openssl-rand--base64-32)
 - [`"hasSecondFactor" is a field janus sets itself; rename it`](#hassecondfactor-is-a-field-janus-sets-itself-rename-it)
+- [`janus: devices.keys: …`](#janus-deviceskeys-expected-at-least-one-key---id-key--the-first-seals)
 - [`janus: events must be a function that takes a user event …`](#janus-events-must-be-a-function-that-takes-a-user-event--webhooks---from-nxgtjanus-webhooks-or-your-own)
 - [`janus: signIn.throttle …` wiring messages](#janus-signinthrottle-wiring-messages)
 - [Other `janus:` wiring messages](#other-janus-wiring-messages)
@@ -97,7 +98,7 @@ How the messages are shaped:
 - [The link signed in another device than the one that asked](#the-link-signed-in-another-device-than-the-one-that-asked)
 - [`magicLink.request` answers `null` for a user who exists](#magiclinkrequest-answers-null-for-a-user-who-exists)
 - [`TS2339: Property 'magicLink' does not exist on type 'TypeApi<…>'.`](#ts2339-property-magiclink-does-not-exist-on-type-typeapi)
-- [`TS2554: Expected 1 arguments, but got 2.`, on `magicLink.confirm`](#ts2554-expected-1-arguments-but-got-2-on-magiclinkconfirm)
+- [`TS2559: Type 'string' has no properties in common with type 'SignInOptions'.`, on `magicLink.confirm`](#ts2559-type-string-has-no-properties-in-common-with-type-signinoptions-on-magiclinkconfirm)
 - `TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED`, `TOKEN_STALE`, `USER_INACTIVE` and `VERSION_CONFLICT` from `magicLink.confirm`, and `TS2339` on its `token`: in their entries above.
 
 **Step-up**
@@ -111,6 +112,18 @@ How the messages are shaped:
 - [`TS2339: Property 'code' does not exist on type 'StepUpByEmail<…> | StepUpByApp<…>'.`](#ts2339-property-code-does-not-exist-on-type-stepupbyemail--stepupbyapp)
 - [`TS2339: Property 'stepUp' does not exist on type 'TypeApi<…>'.`](#ts2339-property-stepup-does-not-exist-on-type-typeapi)
 
+**Devices**
+- [`<call>: a device was given, but janus() has no devices — pass devices: { keys }`](#call-a-device-was-given-but-janus-has-no-devices--pass-devices--keys-)
+- [`<call>: options must be { device }, or left out — the token goes under device`](#call-options-must-be--device--or-left-out--the-token-goes-under-device)
+- [`<call>: options.device must be the device token the client holds, or null when it holds none`](#call-optionsdevice-must-be-the-device-token-the-client-holds-or-null-when-it-holds-none)
+- [Every sign-in reports a new device](#every-sign-in-reports-a-new-device)
+- [A new device is never reported: `newDevice` is always `false`](#a-new-device-is-never-reported-newdevice-is-always-false)
+- [`TS2379: Argument of type '{ device: string | undefined; }' is not assignable to parameter of type 'SignInOptions' …`](#ts2379-argument-of-type--device-string--undefined--is-not-assignable-to-parameter-of-type-signinoptions-with-exactoptionalpropertytypes-true)
+- [`TS2739: Type '{ … }' is missing the following properties from type 'SignedIn<…>': newDevice, deviceToken`](#ts2739-type----is-missing-the-following-properties-from-type-signedin-newdevice-devicetoken)
+- [`TS2559: Type 'string' has no properties in common with type 'SignInOptions'.`, on `secondFactor.confirm` or `signInCode.confirm`](#ts2559-type-string-has-no-properties-in-common-with-type-signinoptions-on-secondfactorconfirm-or-signincodeconfirm)
+- [`TS2322: Type 'string | null' is not assignable to type 'string'.`, on `deviceToken`](#ts2322-type-string--null-is-not-assignable-to-type-string-on-devicetoken)
+- `janus: devices.keys: …`: under [Configuring `janus()`](#configuring-janus).
+
 **User events**
 - [`[JANUS_EVENT_FAILED] Warning: janus: the events listener failed on <type> <event id> for user <user id>: <name>`](#janus_event_failed-warning-janus-the-events-listener-failed-on-type-event-id-for-user-user-id-name)
 - [An event you expected never arrived](#an-event-you-expected-never-arrived)
@@ -395,6 +408,33 @@ janus({
 });
 ```
 
+### `janus: devices.keys: expected at least one key — [{ id, key }], the first seals`
+
+Also:
+
+- `janus: devices.keys: every key needs an id of letters, digits, _ and -, at most 64 of them`
+- `janus: devices.keys: two keys have the id "<id>"`
+- `janus: devices.keys: the key "<id>" is not 32 bytes in base64 — make one with openssl rand -base64 32`
+
+**When:** `janus({ ..., devices })`.
+**Why:** device tokens are signed with these keys, in the format of
+`secondFactor.keys`: a list of at least one `{ id, key }`, the key 32 random
+bytes in base64. An empty list, a key from an environment variable that is
+not set, a hex key or a passphrase is refused.
+**Fix:** make a key of its own — not a sealing key of the second factor's —
+and keep it with your other secrets:
+
+```sh
+openssl rand -base64 32
+```
+
+```ts
+janus({
+  ...,
+  devices: { keys: [{ id: '2026-09', key: process.env.DEVICES_KEY_2026_09 ?? '' }] }, // the first signs
+});
+```
+
 ### `"hasSecondFactor" is a field janus sets itself; rename it`
 
 **When:** `tsc`, on the `janus({...})` call, when your schema declares a `hasSecondFactor` field. This version added it to the fields janus sets on every user.
@@ -1289,12 +1329,17 @@ Or `@nxgt/janus` is older than 0.15, which brought `magicLink`.
 **Fix:** name the field that holds the e-mail with the type's `email`
 option, or upgrade `@nxgt/janus`.
 
-### `TS2554: Expected 1 arguments, but got 2.`, on `magicLink.confirm`
+### `TS2559: Type 'string' has no properties in common with type 'SignInOptions'.`, on `magicLink.confirm`
+
+Before 0.17: `TS2554: Expected 1 arguments, but got 2.`
 
 **When:** `tsc`, on `magicLink.confirm(challenge, code)` — a sign-in code's
 route copied for a link.
-**Why:** a link carries no code: its token is the whole secret.
-**Fix:** `magicLink.confirm(token)`, with the token the link's page posted.
+**Why:** a link carries no code: its token is the whole secret. The second
+argument is `SignInOptions`, `{ device }`, which a string is not.
+**Fix:** `magicLink.confirm(token)`, with the token the link's page posted —
+and `magicLink.confirm(token, { device: cookie ?? null })` with
+[devices](guide/devices.md).
 
 ---
 
@@ -1432,6 +1477,164 @@ a code has nowhere to be sent.
 
 ---
 
+## Devices
+
+The three messages below are bare `TypeError`s, thrown by a sign-in before
+anything is written — a `signUp` creates no user. `<call>` is the call you
+wrote: `signIn`, `secondFactor.recover`, `patient.magicLink.confirm`. A
+device token itself is never refused: one that proves nothing is a new
+device. [The devices guide](guide/devices.md) has the whole flow.
+
+### `<call>: a device was given, but janus() has no devices — pass devices: { keys }`
+
+**When:** a sign-in given `{ device }` — `{ device: null }` included — on a
+`janus()` wired without `devices`. Most often one instance of several: the
+one that serves another route — the second factor's code, a sign-in link —
+was built from another configuration.
+**Why:** a device token is signed and checked with `devices.keys`; without
+keys there is nothing to sign it with, and answering `newDevice: false` would
+hide a notice you meant to send.
+**Fix:** give every `janus()` that signs users in the same `devices` — build
+the configuration once and import it:
+
+```ts
+export const devices = { keys: [{ id: '2026-09', key: process.env.DEVICES_KEY_2026_09 ?? '' }] } as const;
+janus({ ...config, devices });
+```
+
+Or stop passing `{ device }` where devices are not wanted.
+
+### `<call>: options must be { device }, or left out — the token goes under device`
+
+**When:** from JavaScript, or through a cast, options that are not an
+object — most often the token itself, `auth.signIn(credentials, deviceOf(c))`,
+where `{ device: deviceOf(c) }` belongs. Left unrefused, that sign-in would
+be silently untracked: no token, no notice.
+**Why:** the last argument is `SignInOptions`, `{ device }`, or nothing.
+**Fix:**
+
+```ts
+await auth.signIn(credentials, { device: token ?? null });
+```
+
+### `<call>: options.device must be the device token the client holds, or null when it holds none`
+
+**When:** from JavaScript, or through a cast, a `device` that is neither a
+string nor `null`: a number, an object — the cookie jar, a parsed cookie, the
+previous `SignedIn` instead of its `deviceToken`. `undefined` is not refused:
+it means "not tracked".
+**Why:** `device` is the token the client holds, as a string, or `null` when
+it holds none.
+**Fix:**
+
+```ts
+await auth.signIn(credentials, { device: previous.deviceToken }); // the string, or null
+```
+
+### Every sign-in reports a new device
+
+**When:** `newDevice` is `true` — and `user.newDeviceSignedIn` sent, and a
+notice e-mailed — at every sign-in of a user who always uses the same
+browser.
+**Why:** the token the sign-in is given does not prove this user signed in
+there. In order of likelihood:
+
+- **the device cookie is not kept.** It was never set from `deviceToken`;
+  it was set without `Max-Age` or `Expires`, so the browser drops it when it
+  closes; it is `Secure` on a plain `http://` origin other than
+  `localhost`; its `Path` or `Domain` leaves out a sign-in route; or it is
+  written under one name and read under another;
+- **a confirmation is given `null`** rather than the cookie — a
+  `{ device: null }` written in the second factor's route — so each
+  confirmation is a device holding no token;
+- **a device key was removed**, or two instances hold different keys: each
+  device is new once after a removal, and at every sign-in that reaches the
+  other instance;
+- **two people share the browser** and take turns: one cookie holds one
+  user's token, and the other's proves nothing.
+
+**Fix:** set the cookie from every answer's `deviceToken`, long-lived and
+sent to every sign-in route, and read it under the same name:
+
+```ts
+headers.append('Set-Cookie', `device=${signedIn.deviceToken}; Max-Age=34560000; Path=/; HttpOnly; Secure; SameSite=Lax`);
+```
+
+Give the confirmations the cookie too, and every `janus()` the same
+`devices`. The shared browser is not a bug: it is the price of storing
+nothing.
+
+### A new device is never reported: `newDevice` is always `false`
+
+**When:** a user signs in from a browser that never saw them, and nothing is
+reported: `newDevice: false`, `deviceToken: null`, no event.
+**Why:**
+
+- **no `device` was given** — absent, or `undefined`: a cookie read as
+  `string | undefined` passed as it is, which compiles unless your tsconfig
+  has `exactOptionalPropertyTypes`. Absent means *not tracked*, not *new*;
+- **the device was not given again** to `secondFactor.confirm` or `recover`:
+  for a user with an active second factor, the challenge `signIn` answered
+  carries none, and the confirmation decides alone;
+- `newDevice` read on `signUp`'s answer, which is never new.
+
+**Fix:** pass `null` for a client with no token, and the device to every
+call that opens a session:
+
+```ts
+const device = cookie ?? null;
+const result = await auth.signIn(credentials, { device });
+if (result.status === 'secondFactor') await auth.secondFactor.confirm(result.challenge, code, { device });
+```
+
+### `TS2379: Argument of type '{ device: string | undefined; }' is not assignable to parameter of type 'SignInOptions' with 'exactOptionalPropertyTypes: true'.`
+
+It goes on: `Type 'string | undefined' is not assignable to type 'string | null'.`
+
+**When:** `tsc`, with `exactOptionalPropertyTypes`, on a sign-in given a
+cookie read as `string | undefined`.
+**Why:** `undefined` would mean *not tracked*: a browser without a cookie
+would never be given a token, and never reported. `null` says the client
+holds none.
+**Fix:** `{ device: cookie ?? null }`. Without that compiler option, the same
+line compiles and tracks nothing — write `?? null` there too.
+
+### `TS2739: Type '{ … }' is missing the following properties from type 'SignedIn<…>': newDevice, deviceToken`
+
+**When:** `tsc`, on a `SignedIn` built by hand — a test double of `signIn`,
+a stub of `auth` — after upgrading to 0.17.
+**Why:** every answer that opens a session now carries `newDevice` and
+`deviceToken`.
+**Fix:**
+
+```ts
+const signedIn: SignedIn<User> = { status: 'signedIn', user, session, token, newDevice: false, deviceToken: null };
+```
+
+### `TS2559: Type 'string' has no properties in common with type 'SignInOptions'.`, on `secondFactor.confirm` or `signInCode.confirm`
+
+Also: `Type '"<value>"' has no properties in common with type 'SignInOptions'.`
+for a literal token, and `TS2345: Argument of type 'string | undefined' is
+not assignable to parameter of type 'SignInOptions | undefined'.` — or
+`'string | null'` — for a cookie or an earlier `deviceToken`, given as is.
+
+**When:** `tsc`, on `secondFactor.confirm(challenge, code, token)` or
+`signInCode.confirm(challenge, code, token)` — the device token given as a
+bare string, or as a nullable one.
+**Why:** the options come last, as an object: `{ device }`.
+**Fix:** `secondFactor.confirm(challenge, code, { device: token ?? null })`.
+
+### `TS2322: Type 'string | null' is not assignable to type 'string'.`, on `deviceToken`
+
+**When:** `tsc`, reading `signedIn.deviceToken` as a `string` — to set a
+cookie.
+**Why:** it is `null` when the sign-in was given no `device`: nothing was
+minted then.
+**Fix:** set the cookie only for a token — `if (signedIn.deviceToken !==
+null) …` — or give every sign-in a `device`.
+
+---
+
 ## User events
 
 ### `[JANUS_EVENT_FAILED] Warning: janus: the events listener failed on <type> <event id> for user <user id>: <name>`
@@ -1454,6 +1657,9 @@ process.on('warning', (warning) => {
 **Why:** one of these, in order of likelihood:
 - the e-mail was already verified: nothing changed, so nothing is sent;
 - `delete` deleted nobody — a replay, or an id of another user type;
+- a `user.newDeviceSignedIn` for a sign-in given no `device`, from a known
+  device, or confirmed without the device given again — see
+  [A new device is never reported](#a-new-device-is-never-reported-newdevice-is-always-false);
 - the flow was refused, or the store failed during the write itself — the call threw, and nothing was written or sent;
 - the process stopped between the write and the listener — events are sent at most once, from memory;
 - the listener threw: look for `JANUS_EVENT_FAILED` in the process's warnings.

package/package.json

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