@nxgt/janus 0.14.0 → 0.16.0

package/docs/guide/second-factor.md

@@ -127,7 +127,7 @@ Without `secondFactor`, `signIn` answers a session as before, typed
 
 | State | `hasSecondFactor` | `signIn` answers | Recovery codes | Reached by |
 | --- | --- | --- | --- | --- |
-| none | `false` | a session | none | a new user; `disable`, which removes the codes with the factor |
+| none | `false` | a session | none | a new user; `disable`, which removes the codes with the factor; the [first proof of the e-mail](#a-first-sign-in-by-e-mail-removes-it-too) by a sign-in code or link |
 | **enrolled** — waiting for a first code | `false` | a session | none | `enroll` |
 | **active** | `true` | a challenge | ten from `activate`; one fewer per `recover`; ten new from `regenerateRecoveryCodes` | `activate`, with a code that matches |
 
@@ -384,7 +384,7 @@ is as good as the user's phone.
 ### Signing in with one
 
 `recover(challenge, code)` redeems the challenge `signIn` answered — or
-`signInCode.confirm`'s — with a recovery code instead of the app's code, and
+`signInCode.confirm`'s, or `magicLink.confirm`'s — with a recovery code instead of the app's code, and
 opens the session. The recovery code is **spent**: its hash leaves the store,
 and `recoveryCodesLeft` says how many remain.
 
@@ -559,6 +559,31 @@ const auth = janus({
 });
 ```
 
+### A first sign-in by e-mail removes it too
+
+When [`signInCode.confirm`](sign-in-code.md) or
+[`magicLink.confirm`](magic-link.md#an-account-someone-else-registered)
+proves an e-mail **never verified**, the write that proves it also removes
+the factor, active or enrolled, with its recovery codes — and drops the
+password, and signs out every session. Whoever registered the address never
+proved they held its inbox, so a factor they enrolled is not theirs to keep:
+the inbox's owner signs in with no challenge.
+
+```ts
+const signedIn = await auth.magicLink.confirm(token); // an e-mail never verified
+if (signedIn.status === 'signedIn' && !signedIn.user.hasSecondFactor) {
+	// offer setPassword, then enroll again
+}
+```
+
+`user.secondFactorDisabled` is sent when the factor removed was active, after
+`user.emailVerified` and any `user.passwordChanged`, so the listener above
+tells the inbox's owner. An e-mail already verified keeps the factor, and
+`confirm` answers a challenge as `signIn` does. **Send `verifyEmail` before
+offering `enroll`**: a user who enrolls before proving their own e-mail loses
+the factor on their first sign-in by code or link, since the library cannot
+tell them from someone who registered their address.
+
 ### Asking before `enroll` and `disable` is your policy
 
 `janus` checks nothing before `enroll` or `disable`: it does not know who is
@@ -874,6 +899,7 @@ with `STORE_FAILED`.
 ## See also
 
 - [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`
 - [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

package/docs/guide/sessions.md

@@ -182,7 +182,10 @@ if (current !== null) {
 ```
 
 `changePassword` leaves other sessions open; call this after it when that is
-your policy. `resetPassword.confirm` signs out everywhere on its own.
+your policy. `resetPassword.confirm` signs out everywhere on its own, and so
+do `signInCode.confirm` and `magicLink.confirm` when they prove an e-mail
+never verified, before opening their own session
+([why](magic-link.md#an-account-someone-else-registered)).
 
 ## `collectExpired`
 

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

@@ -128,9 +128,9 @@ and the time the answer takes would tell what its body does not. The store's
 own latency — one write for a code issued, none for `null` — still tells a
 patient observer; that limit is stated rather than denied.
 
-Every `request` issues a **new** code with its own challenge; the earlier
-ones stay valid until they are confirmed or expire. `janus` does not limit
-how often a code is asked for: **rate-limit the request route** per address
+Every `request` issues a **new** code with its own challenge, and spends the
+earlier ones: only the last code sent works — see
+[attempts](#attempts). `janus` does not limit how often a code is asked for: **rate-limit the request route** per address
 and per client, as you would a password reset, or anyone can fill a user's
 inbox.
 
@@ -153,9 +153,10 @@ if (issued !== null) {
 
 **No link, and no challenge.** A link carrying the challenge would put it in
 the mailbox beside the code — whoever reads the e-mail would hold both
-halves — and in every server log and proxy the link crosses. A sign-in link
-is not this flow: the code is typed into the page that asked for it, so the
-sign-in completes in the browser that started it.
+halves — and in every server log and proxy the link crosses. A [sign-in link](magic-link.md)
+is another flow, with a token of its own: here the code is typed into the
+page that asked for it, so the sign-in completes in the browser that started
+it.
 
 Send it to `issued.email`, not to what the visitor typed: it is the address
 the user's field holds, as they registered it.
@@ -273,10 +274,21 @@ succeeds, and their `version` moves: the code proves the address as a
 verification link would, and a [`user.emailVerified` event](events.md) is
 sent. A user already verified is not written, and nothing is sent.
 
+**An e-mail proved for the first time drops the password and the second
+factor, and signs out every session** before the new one opens: the proof
+can land on an account someone else registered, with a password — and maybe
+a second factor — of theirs. `user.passwordChanged` follows
+`user.emailVerified` when a password was dropped, then
+`user.secondFactorDisabled` when an active factor was; an e-mail already
+verified changes nothing. The details are in
+[the sign-in link guide](magic-link.md#an-account-someone-else-registered):
+the same holds for a code.
+
 ### A second factor is still asked for
 
 The code proves the e-mail, not the second factor. With `janus({ secondFactor })`,
-a user whose factor is active gets **no session from the code**: `confirm`
+a user whose e-mail was already verified and whose factor is active gets
+**no session from the code**: `confirm`
 answers a challenge, exactly as `signIn` does with a password, and
 [`secondFactor.confirm`](second-factor.md#confirming-the-code-at-sign-in)
 redeems it with the code of their authenticator app — or
@@ -499,6 +511,7 @@ a `secondFactor`, and `SignedIn<U>` everywhere else. `IssuedCode` and
 ## See also
 
 - [The second factor](second-factor.md) — the challenge `confirm` answers for a user whose factor is active
+- [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
 - [Errors](errors.md) — every code and its status

package/docs/guide/users.md

@@ -82,7 +82,7 @@ that cuts an emoji in half, say.
 | `password.login` | a field name | — | The field users sign in with: a **top-level, required string** field. A typo is a compile error |
 | `password.normalize` | `'none' \| 'lowercase' \| 'lowercaseTrim' \| 'nfkcLowercaseTrim' \| (value) => string` | `'lowercaseTrim'` | Applied to the login before any store sees it, at sign-up and at sign-in alike |
 | `password.minLength` | integer ≥ 1 | `8` | Below it: `PASSWORD_TOO_SHORT` |
-| `email` | a field name | `'email'` | The field `verifyEmail`, `resetPassword` and `signInCode` send to. Without one, those flows are absent from the type |
+| `email` | a field name | `'email'` | The field `verifyEmail`, `resetPassword`, `signInCode` and `magicLink` send to. Without one, those flows are absent from the type |
 | `session.lifespan` | `Duration` | `'7d'` | How long a session lives |
 | `session.renewAfter` | `Duration \| false` | `'1d'` | When `authenticate` slides the session. `false` for a fixed lifespan |
 | `schemaVersion` | string | `'1'` | Recorded on every user written. Bump it when the schema tightens |
@@ -95,6 +95,7 @@ that cuts an emoji in half, say.
 | `tokens.verifyEmail` | `Duration` | `'24h'` | How long a verification token lives |
 | `tokens.resetPassword` | `Duration` | `'1h'` | How long a reset token lives |
 | `tokens.signInCode` | `Duration` | `'10m'` | How long an e-mailed sign-in code and its challenge live. See [sign-in codes](sign-in-code.md) |
+| `tokens.magicLink` | `Duration` | `'15m'` | How long an e-mailed sign-in link lives. See [sign-in links](magic-link.md) |
 | `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) |
@@ -221,11 +222,14 @@ await auth.delete(renamed);                        // true
 The patch is spread over the stored fields and the result is checked against
 the schema, so a patch can never leave a user the schema would refuse.
 Changing the e-mail sets `emailVerified` back to `false`, and moves the login
-with it when the e-mail is the login. It also sends a
-[`user.emailChanged` event](events.md#telling-the-user-their-password-or-e-mail-changed)
-carrying `formerEmail`, the address before — so the notice goes to the inbox
-the account just left. A change of case only (`Ada@…` for `ada@…`) is no
-change, and sends nothing.
+with it when the e-mail is the login — so the next sign-in by code or link
+proves it anew, and [drops the password and the second factor, and signs out
+every session](magic-link.md#an-account-someone-else-registered). It also
+sends a [`user.emailChanged`
+event](events.md#telling-the-user-their-password-or-e-mail-changed) carrying
+`formerEmail`, the address before — so the notice goes to the inbox the
+account just left. A change of case only (`Ada@…` for `ada@…`) is no change,
+and sends nothing.
 
 ### `ifVersion`
 

package/docs/guide/vocabulary.md

@@ -43,21 +43,22 @@ either finds this row.
 | **credential** | What a caller presents to prove who they are: a login and a password at sign-in (`CredentialError`, `CREDENTIALS_INVALID`), or a token on a request — always written *session credential* | |
 | **password policy** | The rules a new password must meet: `minLength`, `normalize` | the model |
 | **session** | A signed-in period, carried by a **session token** | |
-| **lapsed**, **revoked**, **renewed** | A session past its `expiresAt`; one ended by a sign-out or a password reset; one whose `expiresAt` moved in passing (`renewAfter`) | "expired" — kept for `TOKEN_EXPIRED`, a one-time token |
+| **lapsed**, **revoked**, **renewed** | A session past its `expiresAt`; one ended by a sign-out, a password reset, or the first proof of an e-mail by a code or a link; one whose `expiresAt` moved in passing (`renewAfter`) | "expired" — kept for `TOKEN_EXPIRED`, a one-time token |
 | **anonymous** | A request that presents no session credential, or one that authenticates nobody: `authenticate` answers `null` | "unauthenticated", "guest", "logged out" |
 | **bearer client** | A client that sends its session token as `Authorization: Bearer` rather than in a cookie | |
-| **one-time token** | A single-use token sent by e-mail in a link, for verification or a password reset | "code": a code is typed, a token is followed in a link |
+| **one-time token** | A single-use token sent by e-mail in a link, for verification, a password reset or a sign-in | "code": a code is typed, a token is followed in a link |
+| **sign-in link** | A one-time token sent by e-mail in a link that signs the user in, with no password — what `magicLink.request` issues and `magicLink.confirm` takes, see [sign-in links](magic-link.md). *Magic link* is its common name, and its API's; in prose, *sign-in link*, or *link* where the sentence says which | "magic code", "login link", "passwordless link" |
 | **one-time code** | Six digits a user types, checked against a challenge. Two kinds: a **TOTP code**, computed by an authenticator app from the user's secret and never sent — what `secondFactor.activate`, `secondFactor.regenerateRecoveryCodes` and `secondFactor.confirm` take, see [the second factor](second-factor.md); and a **sign-in code**, sent by e-mail — what `signInCode.request` issues and `signInCode.confirm` takes, see [sign-in codes](sign-in-code.md). **"Code" alone always means a one-time code**, the kind named by the sentence around it. An error's is written `error.code`, or by its value (`CODE_INVALID`), and said *error code*; the program is *your code* | "OTP", "PIN", "passcode", "magic code"; "code" for an error's `code`, unless written *error code* |
 | **second factor** | What a user proves at sign-in beyond their password: a TOTP secret their authenticator app holds, `UserRecord.secondFactor`. **Enrolled** once `enroll` stored it, waiting for a first code (`confirmedAt: null`); **active** once `activate` accepted one — `hasSecondFactor`, and only then does `signIn` ask for a code | "2FA", "MFA", "OTP device"; "confirmed" for the state — to *confirm* is to redeem a challenge |
 | **recovery code** | One of ten single-use codes `secondFactor.activate` and `secondFactor.regenerateRecoveryCodes` answer **once** — ten characters, shown `xxxxx-xxxxx` — that `secondFactor.recover` takes instead of a TOTP code, for a user whose authenticator app is gone. Stored only as keyed hashes. Always written in full: *code* alone is a one-time code, and a recovery code is never one | "backup code", "scratch code", "recovery key" |
 | **attempt** | One code tried against a challenge, counted by `countAttempt` in the token's `attempts` before the code is checked. A challenge takes five, a second factor's or a sign-in code's | "try"; "retry" is a repeated write, never a guess |
 | **challenge** | A secret the visitor keeps, redeemed once with a code — which is what *confirm* means for it. `signIn` answers one instead of a session when the user's second factor is active, for `secondFactor.confirm` — or `secondFactor.recover`, with a recovery code; `signInCode.request` answers one beside the sign-in code, for `signInCode.confirm`; `stepUp.request` answers one for `stepUp.confirm`. Stored as its hash, as a one-time token of kind `secondFactor`, `signInCode` or `stepUp`: five minutes or ten by default, and five attempts | "MFA token", "pending session", "ticket" |
-| **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`, `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 |
+| **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 | |
-| **e-mail flow** | `verifyEmail` or `resetPassword`: send a one-time token, then confirm it. `signInCode` sends a one-time code instead | |
-| **issued** | What a flow answers for the application to send: an `IssuedToken` from `verifyEmail.send` or `resetPassword.request`, an `IssuedCode` from `signInCode.request` — the address with it. `@nxgt/janus-mail` takes it as it is | "result", "payload" |
+| **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 |
 | **step-up**, **fresh** | A step-up is a signed-in user proving again who they are before a sensitive action — `stepUp.request`, then `stepUp.confirm`, with an e-mailed code or, when their second factor is active, their app's — which moves the session's `authenticatedAt` to now and opens no session. A session is **fresh** for `maxAge` after it proved who it is, at the sign-in or by a step-up; `assertFresh` refuses an older one with `STEP_UP_REQUIRED`. See [step-up](step-up.md) | "re-authentication", "sudo mode", "elevated session"; "recent sign-in" once a step-up counts too |

package/docs/roadmap.md

@@ -70,6 +70,24 @@ Nothing yet.
 The last ten, newest first, each with the version it came in. Everything
 before is in the [CHANGELOG](../CHANGELOG.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
+  its recovery codes are dropped and every session signed out before the
+  new one opens: whoever registered the address without its inbox keeps
+  nothing, and the owner is asked for no factor they never set.
+  `user.passwordChanged` and `user.secondFactorDisabled` report what was
+  dropped. An e-mail already verified changes nothing.
+- **Sign in with an e-mailed link (magic link), v0.15.0** —
+  `auth.magicLink.request(email)` and `magicLink.confirm(token)` on every
+  user type with an e-mail, with or without a password: the sign-in code
+  with nothing to type. `request` answers `null` for nobody and for an
+  inactive user alike; only the last link sent works; a link lives fifteen
+  minutes (`tokens.magicLink`) and is spent by its first `confirm`, which
+  proves the e-mail and still asks for an active second factor. Confirmed
+  from a `POST`, so a mail scanner that opens the link spends nothing.
+  **Breaking for an adapter: `TokenKind` gains `'magicLink'`**, which a
+  `CHECK` or a validator's enum must list.
 - **Password guessing throttled per login, v0.14.0** — past ten passwords
   tried at one login in a 15-minute window, `signIn` answers
   `CREDENTIALS_INVALID` with `reason: 'throttled'` and `retryAfter`, the right
@@ -124,13 +142,6 @@ before is in the [CHANGELOG](../CHANGELOG.md).
   `SecondFactorRecord.recoveryCodes`,
   stored by the users stores of `@nxgt/janus-drizzle` and
   `@nxgt/janus-mongo`, with conformance cases.
-- **The second factor in the user events, v0.9.0** —
-  `user.secondFactorEnabled`, once `secondFactor.activate` made a factor
-  active, and `user.secondFactorDisabled`, once `secondFactor.disable`
-  removed an active one: a listener can tell the user, as
-  `@nxgt/janus-mail`'s `twoFactorEnabled` and `twoFactorDisabled` notices
-  do, whoever made the change. `enroll`, a factor still waiting, and a
-  `disable` that found none send nothing.
 - **Sending the e-mails, `@nxgt/janus-mail` v0.1.0** — a package of its
   own, built on the `@nxgt/mail` toolkit: `janusMail({ mailer, from, brand,
   links })` takes what each flow answers —
@@ -149,8 +160,3 @@ before is in the [CHANGELOG](../CHANGELOG.md).
   `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
-- **Webhooks, `@nxgt/janus-webhooks` v0.1.0** — a package of its own: the
-  user events `janus({ events })` hands over, signed by the Standard
-  Webhooks specification (HMAC-SHA256, secrets that rotate) and posted to
-  your endpoints, retried with backoff, and reported to `onGivingUp` when
-  given up — never dropped in silence. `verifyWebhook` is the receiving side.

package/docs/troubleshooting.md

@@ -91,6 +91,15 @@ How the messages are shaped:
 - [`TS2339: Property 'signInCode' does not exist on type 'TypeApi<…>'.`](#ts2339-property-signincode-does-not-exist-on-type-typeapi)
 - `CODE_INVALID`, `TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED`, `USER_INACTIVE` and `VERSION_CONFLICT` from `signInCode.confirm`, and `TS2339` on its `token`: in their entries above.
 
+**Sign-in links**
+- [A sign-in link answers `TOKEN_SPENT` on the user's first click](#a-sign-in-link-answers-token_spent-on-the-users-first-click)
+- [The link's own button answers `403`](#the-links-own-button-answers-403)
+- [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)
+- `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**
 - [`STEP_UP_REQUIRED` — `assertFresh: the session proved who it is longer ago than maxAge …`](#step_up_required--assertfresh-the-session-proved-who-it-is-longer-ago-than-maxage--confirm-with-a-step-up)
 - [`TOKEN_UNKNOWN` — `stepUp.confirm: no such challenge`, with a challenge just issued](#token_unknown--stepupconfirm-no-such-challenge-with-a-challenge-just-issued)
@@ -132,6 +141,7 @@ How the messages are shaped:
 - [`findUser should answer recoveryCodes [] as [] — never null, never undefined`](#finduser-should-answer-recoverycodes--as---never-null-never-undefined)
 - [`reauthenticateSession racing revokeSession: the session should stay revoked — one conditional write, never a read then a write`](#reauthenticatesession-racing-revokesession-the-session-should-stay-revoked--one-conditional-write-never-a-read-then-a-write)
 - [`tokens.insertToken: the store could not answer`, in `tokens.everyKind`](#tokensinserttoken-the-store-could-not-answer-in-tokenseverykind)
+- [`consumeToken for a signInCode token redeemed as magicLink`, in `tokens.magicLinkKind`](#consumetoken-for-a-signincode-token-redeemed-as-magiclink-in-tokensmagiclinkkind)
 
 ---
 
@@ -331,7 +341,7 @@ Also `janus: "<name>" cannot name a user type — janus() answers a method of th
 
 ### `janus: session.lifespan: "<value>" is not a duration; write a number followed by ms, s, m, h or d — for example "15m" or "720h"`
 
-The same for `session.renewAfter`, `tokens.verifyEmail`, `tokens.resetPassword`, `tokens.signInCode`, `tokens.stepUp`, `secondFactor.challenge` and `signIn.throttle.window` — and, at call time rather than in `janus()`, `assertFresh: maxAge: "<value>" is not a duration; …`, from a `maxAge` written wrong. Also `<option>: a duration must be above zero` and `<option>: a duration in milliseconds must be a finite number above zero`.
+The same for `session.renewAfter`, `tokens.verifyEmail`, `tokens.resetPassword`, `tokens.signInCode`, `tokens.magicLink`, `tokens.stepUp`, `secondFactor.challenge` and `signIn.throttle.window` — and, at call time rather than in `janus()`, `assertFresh: maxAge: "<value>" is not a duration; …`, from a `maxAge` written wrong. Also `<option>: a duration must be above zero` and `<option>: a duration in milliseconds must be a finite number above zero`.
 
 **When:** `janus({...})`.
 **Why:** a duration is a number of milliseconds, or a number followed by one unit. `'30 m'` compiles — TypeScript's `${number}` accepts the space — and is refused here.
@@ -507,6 +517,17 @@ challenge — the same code will not, it was used.
 form.addEventListener('submit', () => form.querySelector('button')?.setAttribute('disabled', ''));
 ```
 
+**From `signInCode.confirm` and `magicLink.confirm`**, the message names the
+call: `magicLink.confirm: expected version <n>, found <m>`.
+
+**When:** the user was written — an `update`, a sign-in that rehashed the
+password — between `confirm` reading them and writing the e-mail as
+verified. Rare: the window is one read.
+**Why:** the proof is written under the version read, so an address changed
+meanwhile is never the one marked verified. Nothing was written and no
+session opened, but the code's challenge or the link is already spent.
+**Fix:** answer it as a spent link or code: ask for a new one.
+
 **From `secondFactor.recover`**, the same store message.
 
 **When:** one recovery code used by two sign-ins at once — the same
@@ -544,8 +565,8 @@ if (error instanceof UserInvalidError) {
 Also `changePassword: the current password does not match`.
 
 **When:** `signIn`, `changePassword`.
-**Why:** no user holds the login, the user has no password, or the password is wrong — **one code for the three**. Also a sign-in that verified a password written over while it ran (`reason: 'wrongPassword'`): its session is revoked, or its challenge spent, before the refusal. `error.reason` (`unknownLogin`, `noPassword`, `wrongPassword`) tells them apart for your logs and your rate limiter; a login past its attempts has its own message, below. A login holding a NUL character or a lone surrogate is `unknownLogin`: no user can hold one.
-**Fix:** answer 401 with the same body whatever the reason:
+**Why:** no user holds the login, the user has no password, or the password is wrong — **one code for the three**. Also a sign-in that verified a password written over while it ran (`reason: 'wrongPassword'`): its session is revoked, or its challenge spent, before the refusal. `error.reason` (`unknownLogin`, `noPassword`, `wrongPassword`) tells them apart for your logs and your rate limiter; a login past its attempts has its own message, below. A login holding a NUL character or a lone surrogate is `unknownLogin`: no user can hold one. A user who signed up with a password and then signed in by `signInCode` or `magicLink` before verifying the e-mail has no password any more (`noPassword`): that first proof drops it, and the second factor, and signs out every session, so an address registered by someone else keeps nothing of theirs — [the sign-in link guide](guide/magic-link.md#an-account-someone-else-registered) has why.
+**Fix:** answer 401 with the same body whatever the reason — and, for a user who signed in by code or link before verifying, offer `setPassword` after that sign-in, or send `verifyEmail` at sign-up:
 
 ```ts
 // Never: { reason: error.reason } — `unknownLogin` tells an attacker which users exist.
@@ -611,8 +632,8 @@ janus({ ..., hasher: scryptHasher(), verifiers: [bcryptVerifier] }); // a Passwo
 
 ### `USER_INACTIVE` — `<call>: the user is inactive`
 
-**When:** `signIn`, with the **right** password, for a user set inactive. Also `secondFactor.confirm` and `secondFactor.recover`, for a user set inactive after `signIn` asked for a code, and `signInCode.confirm`, for a user set inactive after the code was sent.
-**Why:** an inactive user keeps their record and password, and every sign-in is refused. It is checked after the password, so only somebody who knows the password learns the user is inactive — and after the code, so only somebody who read the e-mail does: `signInCode.request` answers `null` for an inactive user, as for nobody. On either `confirm`, the challenge is spent: reactivating the user does not revive it.
+**When:** `signIn`, with the **right** password, for a user set inactive. Also `secondFactor.confirm` and `secondFactor.recover`, for a user set inactive after `signIn` asked for a code, `signInCode.confirm`, for a user set inactive after the code was sent, and `magicLink.confirm`, for one set inactive after the link was sent.
+**Why:** an inactive user keeps their record and password, and every sign-in is refused. It is checked after the password, so only somebody who knows the password learns the user is inactive — and after the code, so only somebody who read the e-mail does: `signInCode.request` answers `null` for an inactive user, as for nobody. On either `confirm`, the challenge is spent: reactivating the user does not revive it. `magicLink.confirm` checks after spending the link, which is spent too, and `magicLink.request` answers `null` for an inactive user.
 **Fix:** answer 403, or reactivate, then sign in again: `await auth.setActive(user, true)`.
 
 ### `TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED`
@@ -686,11 +707,31 @@ more time:
 janus({ ..., tokens: { signInCode: '15m' } });
 ```
 
+**On `magicLink.confirm`**, the messages name the token, as for the other
+links: `magicLink.confirm: no such token`, `magicLink.confirm: the token was
+already used`, `magicLink.confirm: the token has expired`.
+
+**When:** `magicLink.confirm(token)`.
+**Why:** a sign-in link lives fifteen minutes and is spent by its first
+`confirm`, whether that call signs in or is refused — so a second click, a
+refresh that posts again, or a link [a mail scanner opened](#a-sign-in-link-answers-token_spent-on-the-users-first-click)
+first answers `TOKEN_SPENT`. The next `request` for the same user spends it
+too: only the last link sent works. `TOKEN_UNKNOWN` also covers a link
+whose user was deleted, one confirmed through another user type's
+`magicLink` — which spends it — a sign-in code's challenge, and a token cut
+short by the mail client wrapping the URL.
+**Fix:** send the visitor back to ask for a new link — every `TOKEN_*`
+means that to them — and tell them to use the latest e-mail.
+
+```ts
+janus({ ..., tokens: { magicLink: '30m' } });
+```
+
 ### `TOKEN_STALE` — `<call>: the token was sent to an e-mail the user no longer has`
 
-**When:** `verifyEmail.confirm` or `resetPassword.confirm`, after the user changed their e-mail — even while the link was being redeemed: the address is checked again on the very record the write replaces.
+**When:** `verifyEmail.confirm`, `resetPassword.confirm` or `magicLink.confirm`, after the user changed their e-mail — even while the link was being redeemed: the address is checked again on the very record the write replaces.
 **Why:** confirming it would verify an address nobody holds any more, or reset a password through one. The token is spent, and nothing is written.
-**Fix:** send a new token to the current address: `await auth.verifyEmail.send(user)`.
+**Fix:** send a new token to the current address: `await auth.verifyEmail.send(user)` — or, for a sign-in link, ask for a new one: `magicLink.request` sends it to the current address.
 
 ### `INVALID_CURSOR` — `<call>: this cursor was not minted by this store, or was minted for another ordering (<n> characters)`
 
@@ -758,7 +799,7 @@ each of those entries has a paragraph for it.
 
 The same for `session` and `user`.
 
-**When:** `tsc`, wherever `signIn`'s answer is read, once `janus()` is given a `secondFactor` — and `signInCode.confirm`'s, on a user type with a password.
+**When:** `tsc`, wherever `signIn`'s answer is read, once `janus()` is given a `secondFactor` — and `signInCode.confirm`'s and `magicLink.confirm`'s, on a user type with a password.
 **Why:** `signIn` then answers one of two shapes: `{ status: 'signedIn', user, session, token }`, or `{ status: 'secondFactor', challenge, expiresAt, userId }` for a user whose second factor is active — the password alone opens no session for them. Without `secondFactor`, `signIn` still answers a session.
 **Fix:** switch on `status`:
 
@@ -946,7 +987,7 @@ const { recoveryCodes } = await auth.secondFactor.regenerateRecoveryCodes(curren
 
 `SecondFactorError`. Also `secondFactor.confirm: the user no longer has a second factor — sign in again`, and the same from `secondFactor.recover`.
 
-**When:** `activate` before `enroll`, or after `disable`. On `confirm` or `recover`: the factor was disabled after `signIn` asked for a code.
+**When:** `activate` before `enroll`, or after `disable` — or after a sign-in by `signInCode` or `magicLink` that proved the e-mail for the first time, which removes a factor enrolled before it. On `confirm` or `recover`: the factor was disabled after `signIn` asked for a code, or removed by such a first proof when an outage kept its challenges from being spent — the proof spends them otherwise, and `confirm` answers `TOKEN_SPENT`.
 **Why:** `activate` checks a code against the secret `enroll` wrote, and there is none. On `confirm`, the factor the challenge asked for is gone, so the challenge is spent.
 **Fix:** `enroll`, show the `uri` as a QR code, then `activate` with a code from the app. After `confirm`'s refusal, sign in again: `signIn` answers a session directly for a user without a factor.
 
@@ -1151,6 +1192,112 @@ janus({
 
 ---
 
+## Sign-in links
+
+`magicLink.confirm`'s messages start with `magicLink.confirm` — prefixed by
+the type with several user types: `patient.magicLink.confirm: …`.
+`magicLink.request` throws nothing but `STORE_FAILED`: an e-mail it cannot
+sign in is `null`. `magicLink.confirm` rejects with
+[`TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED`](#token_unknown-token_spent-token_expired),
+[`TOKEN_STALE`](#token_stale--call-the-token-was-sent-to-an-e-mail-the-user-no-longer-has),
+[`USER_INACTIVE`](#user_inactive--call-the-user-is-inactive) and
+[`VERSION_CONFLICT`](#version_conflict--call-expected-version-n-found-m);
+each of those entries has a paragraph for it. On a type with a password in
+an instance given a `secondFactor`, reading its `token` before narrowing on
+`status` is the `TS2339` of `signIn`'s. [The sign-in link guide](guide/magic-link.md)
+has the whole flow.
+
+### A sign-in link answers `TOKEN_SPENT` on the user's first click
+
+`magicLink.confirm: the token was already used`, when the user swears they
+clicked once.
+
+**When:** a route calls `magicLink.confirm` on the `GET` of the link — and
+most often for users behind a corporate mail gateway, or of a webmail that
+checks links.
+**Why:** a mail scanner opened the link before the user did. Gateways,
+safe-browsing checks and antivirus fetch every URL in an e-mail, and some
+run the page's scripts; a `GET` that confirms spent the token for them.
+**Fix:** make the link's `GET` a page that spends nothing, and confirm from
+its button's `POST` — not from a script that submits by itself, which a
+scanner that runs scripts submits too:
+
+```ts
+// GET /sign-in/link?token=…  → a page whose <form method="post"> holds the token, and a button
+// POST /sign-in/link         → the one place that calls confirm
+const token = String((await request.formData()).get('token') ?? '');
+const signedIn = await auth.magicLink.confirm(token);
+```
+
+The [guide](guide/magic-link.md#confirming-from-a-post-never-from-the-links-get)
+has the page, with the headers it needs.
+
+### The link's own button answers `403`
+
+**When:** the page the e-mailed link opens posts its token, and the route
+that checks the `Origin` before `magicLink.confirm` refuses it — for every
+user, or only on plain HTTP off `localhost` and in older browsers.
+**Why:** the page is sent with `Referrer-Policy: no-referrer`, and under it
+the browser posts the form with `Origin: null`. A check on `Origin` alone
+refuses every such `POST`; one that tries `Sec-Fetch-Site: same-origin`
+first refuses it wherever the browser sends no `Sec-Fetch-Site`. A
+mismatched `ORIGIN` — `http` for `https`, a port, a trailing `/` — does the
+same.
+**Fix:** send the page with `Referrer-Policy: strict-origin`, and set
+`ORIGIN` to the scheme, host and port the address bar shows. A `Referer`
+then holds the origin only, never the path and its token, and the form
+carries its real `Origin`:
+
+```ts
+new Response(html, { headers: { 'Referrer-Policy': 'strict-origin', 'Cache-Control': 'no-store' } }); // the GET page
+if (request.headers.get('Origin') !== ORIGIN) return new Response(null, { status: 403 }); // on the POST
+```
+
+The [guide](guide/magic-link.md#confirming-from-a-post-never-from-the-links-get)
+has the page and the route.
+
+### The link signed in another device than the one that asked
+
+**When:** a user asks for a link on a laptop and opens the e-mail on their
+phone: the phone is signed in, the laptop still waits.
+**Why:** the session opens in the browser that posts the token — whoever
+opens the link signs in, wherever they open it. That is what a link is.
+**Fix:** say on the page that asked "open the link on this device", or send
+a [sign-in code](guide/sign-in-code.md) instead: it is typed into the page
+that asked for it, so the sign-in completes there.
+
+### `magicLink.request` answers `null` for a user who exists
+
+**When:** `magicLink.request(email)`, for an address you can see in the
+database.
+**Why:** the same three causes as a
+[sign-in code's `null`](#signincoderequest-answers-null-for-a-user-who-exists):
+the user is inactive, is of another user type, or the address is not the
+type's e-mail field.
+**Fix:** as there. Do not tell the visitor which — the route answers the
+same page either way.
+
+### `TS2339: Property 'magicLink' does not exist on type 'TypeApi<…>'.`
+
+Also `Property 'magicLink' does not exist on type 'Janus<…>'.`, with the
+single-type form.
+
+**When:** `tsc`, on `auth.magicLink` or `clinic.<type>.magicLink`.
+**Why:** the user type has no e-mail, so a link has nowhere to be sent — as
+for [`signInCode`](#ts2339-property-signincode-does-not-exist-on-type-typeapi).
+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`
+
+**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.
+
+---
+
 ## Step-up
 
 The messages start with `stepUp.request` or `stepUp.confirm` — prefixed by
@@ -1313,7 +1460,7 @@ process.on('warning', (warning) => {
 
 **Fix:** for the last two, reconcile against the users themselves and treat events as the fast path, not the record: page through `auth.list()` and compare with the receiver's copy — a user it lacks is a missed `user.created`, a user the receiver has that `auth.find` answers `null` for is a missed `user.deleted`, a user whose `emailVerified` differs is a missed `user.emailVerified`, and a user whose `hasSecondFactor` differs is a missed `user.secondFactorEnabled` or `user.secondFactorDisabled`.
 
-A store outage **after** the write does not lose the event. `create`, `signUp` and `signInCode.confirm` send it before the steps that follow; `delete` and `resetPassword.confirm` run theirs — removing the sessions, tokens and tuples; revoking the sessions — in a `try`, and send it from its `finally`, whether they succeeded or not.
+A store outage **after** the write does not lose the event. `create` and `signUp` send it before the steps that follow; `delete`, `resetPassword.confirm`, and `signInCode.confirm` and `magicLink.confirm` on an e-mail never verified run theirs — removing the sessions, tokens and tuples; revoking the sessions — in a `try`, and send it from its `finally`, whether they succeeded or not. `signInCode.confirm` and `magicLink.confirm` also revoke the sessions **before** the write: an outage there leaves nothing written and nothing sent, and the next code or link proves the e-mail again.
 
 ---
 
@@ -1600,5 +1747,24 @@ In SQL, `update … set authenticated_at = $2 where id = $1 and revoked_at is nu
 ### `tokens.insertToken: the store could not answer`, in `tokens.everyKind`
 
 **When:** the case `tokens.everyKind`, on an adapter whose database lists the token kinds — a `CHECK`, a validator's enum.
-**Why:** the list does not hold `stepUp`, which came in `@nxgt/janus` 0.12, so the database refuses the insert, and the adapter reports it as the outage it cannot tell apart.
-**Fix:** add `stepUp` to the list, and ship the migration or the validator with it: `'verifyEmail', 'resetPassword', 'secondFactor', 'signInCode', 'stepUp'`.
+**Why:** the list does not hold `stepUp`, which came in `@nxgt/janus` 0.12, or `magicLink`, which came in 0.15, so the database refuses the insert, and the adapter reports it as the outage it cannot tell apart.
+**Fix:** add the missing kind to the list, and ship the migration or the validator with it: `'verifyEmail', 'resetPassword', 'secondFactor', 'signInCode', 'magicLink', 'stepUp'`.
+
+### `consumeToken for a signInCode token redeemed as magicLink`, in `tokens.magicLinkKind`
+
+Also `countAttempt for a magicLink token counted as signInCode`, `spendUserTokens of magicLink: the link only`, and `spendUserTokens of magicLink should not touch a sign-in code, nor anything else have counted it`.
+
+**When:** the case `tokens.magicLinkKind`, on an adapter that matches a token by its hash alone, or spends a user's tokens of every kind at once.
+**Why:** a sign-in code's challenge is handed to whoever asked for the code. Redeemed as a link, it would sign them in with no code at all — the kind is what keeps the two apart, so every token method must match it.
+**Fix:** put `kind` in the condition of `consumeToken`, `countAttempt` and `spendUserTokens`, beside the hash or the user:
+
+```ts
+// MongoDB: consumeToken — the hash and the kind, never the hash alone
+await tokens.findOneAndUpdate(
+	{ _id: tokenHash, kind },
+	[{ $set: { spentAt: { $ifNull: ['$spentAt', at] } } }],
+	{ returnDocument: 'before' },
+);
+```
+
+In SQL, `… where token_hash = $1 and kind = $2`; `spendUserTokens` holds `user_id = $1 and kind = $2`. See [`TokenStore`](guide/adapters.md#sessionstore-and-tokenstore).

package/package.json

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