@nxgt/janus 0.14.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,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) |

package/docs/guide/vocabulary.md

@@ -46,18 +46,19 @@ 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.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,16 @@ 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
@@ -149,8 +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.

package/docs/troubleshooting.md

@@ -91,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)
@@ -132,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)
 
 ---
 
@@ -331,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`, `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 +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
@@ -611,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`
@@ -686,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)`
 
@@ -758,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`:
 
@@ -1151,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
@@ -1600,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.14.0",
+	"version": "0.15.0",
 	"description": "Embeddable, type-safe identities and permissions: bring your own database",
 	"license": "MIT",
 	"type": "module",