@nxgt/janus 0.13.0 → 0.15.0

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,7 +95,9 @@ 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) |
 | `events` | `UserEventListener` | none | Called with every user event — `user.created`, `user.deleted`, … — after the write, awaited. See [user events](events.md) |
 
@@ -178,7 +180,7 @@ In the one-type form these are on `auth` itself; with several types, on
 | `find(id)` | the user, or `null` — for a malformed id, an unknown one, or one of another type | |
 | `get(id)` | the user | `NOT_FOUND` |
 | `list({ after?, limit? })` | `CursorPage<User>`, in creation order | `INVALID_CURSOR` |
-| `update(user, patch, { ifVersion? })` | the user as written | `USER_INVALID`, `LOGIN_TAKEN`, `VERSION_CONFLICT`, `NOT_FOUND` |
+| `update(user, patch, { ifVersion? })` | the user as written; sends `user.emailChanged` when the e-mail changed | `USER_INVALID`, `LOGIN_TAKEN`, `VERSION_CONFLICT`, `NOT_FOUND` |
 | `setActive(user, active, { ifVersion? })` | the user as written | `VERSION_CONFLICT`, `NOT_FOUND` |
 | `delete(user)` | `true`, or `false` for an unknown id or one of another type | |
 
@@ -187,10 +189,10 @@ 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`, `USER_INACTIVE`, `HASH_UNSUPPORTED` |
+| `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` |
 | `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 | `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 | `CREDENTIALS_INVALID`, `PASSWORD_TOO_SHORT` |
+| `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` |
 
 With `secondFactor` configured, a type with a password also answers
 `secondFactor.enroll`, `activate`, `disable` and `confirm` — see
@@ -220,7 +222,11 @@ 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.
+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.
 
 ### `ifVersion`
 
@@ -293,6 +299,6 @@ fields against your schema, not that `password` is a string.
 ## See also
 
 - [Sessions](sessions.md) — `authenticate`, the cookie, signing out
-- [User events](events.md) — what `create`, `signUp` and `delete` send
+- [User events](events.md) — what `create`, `signUp`, `update`, `setPassword`, `changePassword` and `delete` send
 - [Errors](errors.md) — every code, and the status it deserves
 - [Writing an adapter](adapters.md) — the identity stores behind `store`

package/docs/guide/vocabulary.md

@@ -46,20 +46,21 @@ either finds this row.
 | **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 |
 | **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.secondFactorEnabled`, `user.secondFactorDisabled`, `user.recoveryCodesRegenerated`, `user.recoveryCodeUsed`, `user.deleted` — a `UserEvent`, naming the user by id alone, 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 |
+| **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 |
 | **listener** | The one function `janus({ events })` hands every user event to, after the write and awaited | "handler", "hook", "subscriber" |
 

package/docs/roadmap.md

@@ -13,6 +13,12 @@ Nothing yet.
 
 ## Later
 
+- **Collecting lapsed one-time tokens** — `collectExpired()` deletes lapsed
+  sessions only. On a store with no TTL (PostgreSQL), lapsed tokens stay
+  until you delete them, and the sign-in throttle adds one per login tried
+  per window. A port method to collect them, as sessions are, would let the
+  core do it.
+
 - **More official adapters** — the ports are cut where atomicity is not
   required, so users, sessions and permission tuples can each live in the
   database that suits them. MongoDB is the first adapter
@@ -46,6 +52,9 @@ Nothing yet.
   Valibot, ArkType); none is imposed as a peer.
 - **A silent hasher fallback** — a user type with a password and no `hasher`
   is refused at wiring, rather than hashed with something you did not choose.
+- **An account lockout** — a login past its attempts waits for the next
+  window, and no number of wrong passwords blocks an account for longer:
+  a lockout would let anyone lock anyone out.
 - **Answering `null` or `false` on an outage** — a store that cannot answer
   throws `STORE_FAILED`, and a permission walk past `maxDepth` throws
   `PERMISSION_DEPTH`. Neither will become a denial: that turns an outage into
@@ -61,6 +70,34 @@ Nothing yet.
 The last ten, newest first, each with the version it came in. Everything
 before is in the [CHANGELOG](../CHANGELOG.md).
 
+- **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
+  password included, until the window ends. Nothing locks; a login nobody
+  holds is counted alike; a password sign-in that opens a session —
+  after its second factor, when one is active — starts the count again.
+  On by default: `signIn: { throttle: { attempts, window } }` changes it,
+  `signIn: { throttle: false }` turns it off. A tokens store that cannot
+  count fails the sign-in with `STORE_FAILED`. No change for adapters: the
+  counts are `secondFactor` tokens, counted by `TokenStore.countAttempt`.
+- **A password or an e-mail changed, in the user events, v0.14.0** —
+  `user.passwordChanged`, sent by `changePassword` and `setPassword` once the
+  older reset links are spent (a reset stays `user.passwordReset` alone), and
+  `user.emailChanged`, sent by an `update` that changed the e-mail, carrying
+  `formerEmail` — the one event with more than the user's id — so a notice
+  can reach the inbox the account just left, as `@nxgt/janus-mail`'s
+  `passwordChanged` and `emailChanged` notices do. Breaking for a `switch`
+  that exhausts `UserEventType`.
 - **An old reset link stops working, v0.13.0** — `resetPassword.request`
   spends the links sent before, so only the last e-mail's works, and writing
   a password — a link's `confirm`, `changePassword`, `setPassword` — spends
@@ -122,26 +159,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.
-- **User events, v0.8.0** — `janus({ events })` takes one listener, called
-  with `user.created`, `user.emailVerified`, `user.passwordReset` and
-  `user.deleted` once the write landed, and awaited before the flow answers.
-  An event names the user by id alone, with a UUIDv7 of its own to deliver
-  it once; a listener that throws fails no flow and is a
-  `JANUS_EVENT_FAILED` warning.
-- **At most one sign-in code live per user, and challenges that end when
-  they should, v0.7.0** — `signInCode.request` spends the codes sent before,
-  even when requests race, so only the last e-mail's works; writing a
-  password spends the second-factor challenges left waiting, and a sign-in
-  still running when it lands is refused; another user type's `confirm` spends a challenge
-  at its fifth attempt; `verifyEmail.confirm` and `resetPassword.confirm`
-  check the e-mail again on the record they write. `SecondFactorRequired`
-  carries `userId`, for logs and rate limits. For adapters:
-  `TokenStore.spendUserTokens(userId, kind, at, except?)`, with four new conformance
-  cases, implemented in `@nxgt/janus-drizzle`, `@nxgt/janus-mongo` and
-  `@nxgt/janus-redis` — and the port now says a read sees every write that
-  completed before it: never a secondary or a read replica.

package/docs/troubleshooting.md

@@ -40,6 +40,7 @@ How the messages are shaped:
 - [`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: 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)
 
 **Users, sessions and tokens**
@@ -51,6 +52,8 @@ How the messages are shaped:
 - [`USER_INVALID` — `<call>: the fields do not match the <type> schema …`](#user_invalid--call-the-fields-do-not-match-the-type-schema-n-issues-at-paths)
 - [`PASSWORD_TOO_SHORT` — `<call>: the password is shorter than the policy's <n> characters`](#password_too_short--call-the-password-is-shorter-than-the-policys-n-characters)
 - [`CREDENTIALS_INVALID` — `<call>: the login and the password do not match`](#credentials_invalid--call-the-login-and-the-password-do-not-match)
+- [`CREDENTIALS_INVALID` — `<call>: too many passwords tried at this login …`](#credentials_invalid--call-too-many-passwords-tried-at-this-login--wait-for-the-next-window)
+- [`STORE_FAILED` — `<call>: the store dropped the attempts it had just stored`](#store_failed--call-the-store-dropped-the-attempts-it-had-just-stored)
 - [`HASH_UNSUPPORTED` — `<call>: no wired verifier claims the prefix "<prefix>"`](#hash_unsupported--call-no-wired-verifier-claims-the-prefix-prefix)
 - [`scryptHasher: the stored hash has the $scrypt$ prefix and not its format`](#scrypthasher-the-stored-hash-has-the-scrypt-prefix-and-not-its-format)
 - [`USER_INACTIVE` — `<call>: the user is inactive`](#user_inactive--call-the-user-is-inactive)
@@ -88,6 +91,14 @@ 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 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)
@@ -129,6 +140,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)
 
 ---
 
@@ -328,7 +340,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` and `secondFactor.challenge` — 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.
@@ -403,6 +415,15 @@ janus({
 });
 ```
 
+### `janus: signIn.throttle` wiring messages
+
+`TypeError`, at `janus()`: `janus: signIn must be an object — { throttle }`,
+`janus: signIn.throttle must be { attempts, window }, or false to count
+nothing`, `janus: signIn.throttle.attempts must be a whole number above
+zero`, and a `janus: signIn.throttle.window` that is not a duration.
+**Fix:** `signIn: { throttle: { attempts: 10, window: '15m' } }` — the
+defaults — or `signIn: { throttle: false }` to count nothing.
+
 ### Other `janus:` wiring messages
 
 | Message | Fix |
@@ -495,6 +516,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
@@ -532,7 +564,7 @@ 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 holding a NUL character or a lone surrogate is `unknownLogin`: no user can hold one.
+**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:
 
 ```ts
@@ -540,6 +572,47 @@ Also `changePassword: the current password does not match`.
 return new Response('Wrong e-mail or password', { status: 401 });
 ```
 
+### `CREDENTIALS_INVALID` — `<call>: too many passwords tried at this login — wait for the next window`
+
+`CredentialError`, with `reason: 'throttled'` and `retryAfter`.
+
+**When:** `signIn`, after ten passwords were tried at this login in the
+current 15-minute window — whatever this password is, **the right one
+included**, and whether or not anybody holds the login. Nothing is compared.
+**Why:** `signIn` throttles password guessing per login, on by default:
+counted by the store, in fixed windows of the clock, shared by every process
+over the same store. Nothing locks: the next window signs in, and a sign-in
+that succeeds starts the count again. In tests with `fixedClock`, the window
+never ends: advance the clock past `retryAfter`, or wire
+`signIn: { throttle: false }`.
+**Fix:** tell the visitor to wait `retryAfter` seconds — not that the
+password is wrong — and answer 401, as `@nxgt/janus-hono`'s `janusErrors()`
+does, with a `Retry-After` header. If nobody you know tried ten passwords,
+somebody is guessing: look for `janus.signIn.throttled` in your logs. To
+change the limit or turn it off:
+
+```ts
+if (error instanceof JanusError && error.retryAfter !== undefined) {
+	const headers = { 'retry-after': String(error.retryAfter) };
+	return Response.json({ code: error.code, retryAfter: error.retryAfter }, { status: 401, headers });
+}
+
+janus({ ..., signIn: { throttle: { attempts: 20, window: '15m' } } });
+```
+
+### `STORE_FAILED` — `<call>: the store dropped the attempts it had just stored`
+
+`StoreFailure`, with `slot: 'tokens'` and `operation: 'countAttempt'`.
+
+**When:** `signIn`, when the tokens store answers `countAttempt` with `null`
+for the count it stored an instant before.
+**Why:** the store lost it — a Redis evicting keys under memory pressure, a
+flush between the two calls, or an adapter whose `countAttempt` does not
+find what `insertToken` wrote. The throttle cannot count, so the sign-in
+fails rather than pass uncounted.
+**Fix:** answer 503. Run the conformance suite against the adapter, and give
+a Redis tokens store `maxmemory-policy noeviction`.
+
 ### `HASH_UNSUPPORTED` — `<call>: no wired verifier claims the prefix "<prefix>"`
 
 **When:** `signIn` or `changePassword`, for a user whose stored hash was written by another system — typically after an import.
@@ -558,8 +631,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`
@@ -633,11 +706,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)`
 
@@ -705,7 +798,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`:
 
@@ -1098,6 +1191,88 @@ 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 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
@@ -1547,5 +1722,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.13.0",
+	"version": "0.15.0",
 	"description": "Embeddable, type-safe identities and permissions: bring your own database",
 	"license": "MIT",
 	"type": "module",