@nxgt/janus 0.14.0 → 0.15.0

package/docs/README.md

@@ -14,6 +14,7 @@ below are defined once, in [Words](guide/vocabulary.md#words).
 | [Users](guide/users.md) | You are wiring `janus()`, declaring one or several user types, or calling `create`, `update`, `list`, `delete` |
 | [Sessions](guide/sessions.md) | You need to know who a request belongs to, set or clear the cookie, renew, sign out, or test expiry |
 | [E-mail verification and password reset](guide/email-flows.md) | You are sending a verification or reset link, and handling what comes back |
+| [Signing in with an e-mailed link](guide/magic-link.md) | You are signing users in with a link sent by e-mail — a magic link: the page that confirms it from a `POST` so mail scanners spend nothing, the lifetime, the errors, and what ends a link |
 | [Signing in with an e-mailed code](guide/sign-in-code.md) | You are signing users in with a six-digit code sent by e-mail — with no password, or beside one: requesting it without telling who exists, keeping the challenge, the attempts and the errors |
 | [The second factor](guide/second-factor.md) | You are turning on TOTP codes: making and rotating the sealing keys, the QR code, `signIn`'s `status`, confirming a challenge, recovery codes for a lost phone, disabling |
 | [Step-up](guide/step-up.md) | A sensitive action — changing the e-mail, disabling the second factor, deleting the account — should ask a signed-in user to prove again who they are: `assertFresh`, `stepUp.request` and `confirm`, by e-mailed code or by their app |
@@ -32,6 +33,6 @@ below are defined once, in [Words](guide/vocabulary.md#words).
 | --- | --- |
 | [The shared vocabulary](guide/vocabulary.md) | You want the words the documentation uses, or subjects and the tuple notation, ids, cursors, durations or `fixedClock` |
 | [Errors](guide/errors.md) | You are turning what the package throws into a status code, and want every code and what it carries |
-| [Writing an adapter](guide/adapters.md) | You are implementing the identity stores or the relation store for your database, upgrading one for `countAttempt`, `spendUserTokens` and the second factor, or running the conformance suites |
+| [Writing an adapter](guide/adapters.md) | You are implementing the identity stores or the relation store for your database, upgrading one for `countAttempt`, `spendUserTokens`, the second factor and a new token kind, or running the conformance suites |
 | [Troubleshooting](troubleshooting.md) | You have an error message and want its cause and its fix |
 | [Roadmap](roadmap.md) | You want to know what is coming, what shipped, and what is deliberately not planned |

package/docs/guide/adapters.md

@@ -160,7 +160,7 @@ update. A read followed by a write lets two requests redeem one reset token.
 A token is its hash, never its secret, and what it is for:
 
 ```ts
-type TokenKind = 'verifyEmail' | 'resetPassword' | 'secondFactor' | 'signInCode' | 'stepUp';
+type TokenKind = 'verifyEmail' | 'resetPassword' | 'secondFactor' | 'signInCode' | 'magicLink' | 'stepUp';
 
 interface TokenRecord {
 	readonly tokenHash: string;
@@ -178,9 +178,13 @@ interface TokenRecord {
 A token redeemed for another kind is unknown: every method that takes a
 `kind` matches on it. A `stepUp` token is a signed-in user's confirmation of
 a sensitive action; kept apart from `signInCode`, a sign-in code never
-confirms an action, nor an action's code signs anyone in. A store that lists
-the kinds — a `CHECK`, an enum in a validator — lists `stepUp` too, which
-`tokens.everyKind` proves. A `secondFactor` token is the challenge `signIn`
+confirms an action, nor an action's code signs anyone in. A `magicLink`
+token is a sign-in link's, new in 0.15, kept apart from `signInCode` the same
+way: a sign-in code's challenge is handed to whoever asked for it, and a
+store that redeemed it as a link would sign them in with no code —
+`tokens.magicLinkKind` holds that it does not. A store that lists the
+kinds — a `CHECK`, an enum in a validator — lists `stepUp` and `magicLink`
+too, which `tokens.everyKind` proves. A `secondFactor` token is the challenge `signIn`
 answers — or the count of a user's attempts at `regenerateRecoveryCodes`,
 a token of the same kind whose secret nobody is given, never redeemed and
 only counted — and its `address` is `''`: a column or a validator that refuses an
@@ -282,8 +286,8 @@ driver's error in `StoreFailure` as in [the six rules](#the-six-rules):
 Spends every **unspent** token of one user and one `kind` at `at` — but the
 one whose hash is `except`, when given — and answers how many it spent. The
 core calls it right after issuing a sign-in code, with that code's hash as
-`except`, so only the last code sent works — and so after issuing a step-up
-or a reset link; and after writing a password, for the user's
+`except`, so only the last code sent works — and so after issuing a sign-in
+link, a step-up or a reset link; and after writing a password, for the user's
 `resetPassword` links and `secondFactor` challenges:
 
 | The stored token | Written | Counted |
@@ -403,7 +407,7 @@ compile error naming the missing method.
 
 | Suite | Cases | Harness opens |
 | --- | --- | --- |
-| `describeJanusStores({ name, harness, runner?, faults?, skip? })` | 54: users, sessions, tokens, and one outage per method whose honest answer can be "nothing" — fourteen of them | `{ stores, faults?, close? }` |
+| `describeJanusStores({ name, harness, runner?, faults?, skip? })` | 55: users, sessions, tokens, and one outage per method whose honest answer can be "nothing" — fourteen of them | `{ stores, faults?, close? }` |
 | `describeRelationStores({ name, harness, runner?, faults?, skip? })` | 16: the relation store, ids of edge characters, and one outage per method | `{ store, faults?, close? }` |
 
 `harness.open()` is called **once per case** and must answer fresh, empty

package/docs/guide/email-flows.md

@@ -34,11 +34,13 @@ verified.emailVerified; // true
 `sendMail` above is yours to write, or
 [`@nxgt/janus-mail`](https://www.npmjs.com/package/@nxgt/janus-mail)
 writes it: it takes what `send` and `request` answer, as they answer it, and
-sends the verification, reset and sign-in code e-mails — with the notices
+sends the verification, reset, sign-in code and sign-in link e-mails — with the notices
 of a password, an e-mail or a second factor changed, and a welcome on
 `user.created` — in English and French, over any `@nxgt/mail` transport.
-Every link is required: `getStarted`, since janus-mail 0.4.0, is where the
-welcome's **Get started** button leads.
+Every link is required but two: `getStarted`, since janus-mail 0.4.0, is
+where the welcome's **Get started** button leads; `recoveryCodes` and
+`magicLink` — the page a [sign-in link](magic-link.md) opens, since
+janus-mail 0.7.0 — are optional.
 
 ```ts
 import { janusMail } from '@nxgt/janus-mail';
@@ -91,8 +93,9 @@ clinic.patient.verifyEmail.send; // exists: `email` names the field
 clinic.staff.verifyEmail;
 ```
 
-A type with an e-mail can also sign in with a code sent to it, with or
-without a password — see [sign-in codes](sign-in-code.md).
+A type with an e-mail can also sign in with a code or a link sent to it,
+with or without a password — see [sign-in codes](sign-in-code.md) and
+[sign-in links](magic-link.md).
 
 ## Options
 
@@ -180,8 +183,8 @@ The links are spent **after** the password is written, so a link issued
 during the write is spent too. If the store fails at that step, the call
 rejects with `STORE_FAILED` although the password is written — answer 503 as
 usual — and the older links may still be live until the next `request`,
-which spends them. Sign-in codes and step-ups are not spent: the password
-proves neither.
+which spends them. Sign-in codes, sign-in links and step-ups are not spent:
+the password proves none of them.
 
 `confirm` sets the password, marks the e-mail verified — the link proved it —
 and **signs the user out everywhere**: their sessions are revoked, and every
@@ -234,6 +237,7 @@ never the token, and no refusal's message contains it.
 
 - [Users](users.md) — `email`, `update`, and the other per-type methods
 - [Sign-in codes](sign-in-code.md) — the third flow that sends an e-mail: a code, not a link
+- [Sign-in links](magic-link.md) — the fourth: a link that signs in, confirmed from a `POST` so a mail scanner spends nothing
 - [Sessions](sessions.md) — `signOutEverywhere`, which `resetPassword.confirm` calls for you
 - [User events](events.md) — `user.emailVerified` and `user.passwordReset`, which the confirms send
 - [Errors](errors.md) — every code, and the status it deserves

package/docs/guide/errors.md

@@ -56,9 +56,9 @@ that wired the library, so no handler needs to tell it apart.
 | `PASSWORD_TOO_SHORT` | `CredentialError` | 400 | Below `password.minLength` | `minLength` — never the password |
 | `CREDENTIALS_INVALID` | `CredentialError` | 401 | Unknown login, no password, or the wrong one — **one code for the three** — and any password, the right one included, at a login past its attempts in the window — see [throttling](passwords.md#password-guessing-is-throttled) | `reason`, for your logs only; `retryAfter`, the seconds until the next window, when throttled |
 | `HASH_UNSUPPORTED` | `CredentialError` | 400 | A stored hash no wired hasher reads | `hashPrefix` — never the hash |
-| `USER_INACTIVE` | `UserInactiveError` | 403 | Deactivated; told only to someone who gave the right password, or the right code | `userId` |
+| `USER_INACTIVE` | `UserInactiveError` | 403 | Deactivated; told only to someone who gave the right password, the right code, or a live sign-in link | `userId` |
 | `STEP_UP_REQUIRED` | `StepUpRequiredError` | 403 | `assertFresh`: the session proved who it is `maxAge` ago or more. Not a denial of the action — ask for a [step-up](step-up.md), then send the request again | `userId` |
-| `TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED`, `TOKEN_STALE` | `TokenError` | 400 | See [e-mail flows](email-flows.md#what-a-token-refusal-means). For a second factor's challenge: sign in again; for a sign-in code's: request a new code — see [sign-in codes](sign-in-code.md#what-confirm-refuses) | `userId` on `TOKEN_STALE` |
+| `TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED`, `TOKEN_STALE` | `TokenError` | 400 | See [e-mail flows](email-flows.md#what-a-token-refusal-means). For a second factor's challenge: sign in again; for a sign-in code's: request a new code — see [sign-in codes](sign-in-code.md#what-confirm-refuses); for a sign-in link: ask for a new link — see [sign-in links](magic-link.md#what-confirm-refuses) | `userId` on `TOKEN_STALE` |
 | `CODE_INVALID` | `TokenError` | 401 | A one-time code that does not match: a second factor's, or one already accepted — see [the second factor](second-factor.md#confirming-the-code-at-sign-in) — a recovery code not the user's, or already used — see [recovery codes](second-factor.md#signing-in-with-one) — or a sign-in code sent by e-mail — see [sign-in codes](sign-in-code.md#attempts) | `attemptsLeft` from either `confirm` and from `recover`: what the challenge has left, `0` once it is spent; from `regenerateRecoveryCodes`, what the user's 15-minute window has left, `0` past the fifth — see [regenerating them](second-factor.md#regenerating-them). None from `activate`. `userId` |
 | `SECOND_FACTOR_NOT_ENROLLED` | `SecondFactorError` | 409 | `activate` before `enroll`; `regenerateRecoveryCodes` without an active factor; `confirm` or `recover` after the factor was disabled | `userId` |
 | `SECOND_FACTOR_ACTIVE` | `SecondFactorError` | 409 | `enroll` or `activate` on a factor already active: `disable` it first | `userId` |

package/docs/guide/events.md

@@ -43,7 +43,7 @@ The words — **user event**, **listener** — are defined in
 | `type` | Sent by | Not sent |
 | --- | --- | --- |
 | `user.created` | `create`, `signUp` — once the user is inserted, even if `signUp`'s session then fails to open | for a sign-up refused (`LOGIN_TAKEN`, `USER_INVALID`, `PASSWORD_TOO_SHORT`) |
-| `user.emailVerified` | `verifyEmail.confirm`; `resetPassword.confirm`, whose link proves the e-mail; `signInCode.confirm`, whose code does | for an e-mail already verified, or a refused confirm |
+| `user.emailVerified` | `verifyEmail.confirm`; `resetPassword.confirm` and `magicLink.confirm`, whose link proves the e-mail; `signInCode.confirm`, whose code does | for an e-mail already verified, or a refused confirm |
 | `user.passwordReset` | `resetPassword.confirm` | for `setPassword` or `changePassword` — they are not resets |
 | `user.passwordChanged` | `changePassword` and `setPassword` — a first password set on a user created without one included — once the password is written — even if spending the reset links and second-factor challenges it ends then fails | for a reset, which is `user.passwordReset` alone; for a `changePassword` refused (`CREDENTIALS_INVALID`) |
 | `user.emailChanged` | `update`, when it changed the e-mail — added, replaced or removed. It carries `formerEmail`, the address before | for an update that leaves the e-mail alone, or changes only its case (`Ada@…` for `ada@…`): compared normalised, the same test that makes the new address unverified; for a type with no e-mail; for an update refused |
@@ -204,7 +204,7 @@ Where the listener runs within a flow, and what an outage does to it:
 | `verifyEmail.confirm` | after the write — the flow's last step | — |
 | `update` | after the write — the flow's last step | — |
 | `changePassword`, `setPassword` | **after** the reset links and the second-factor challenges left open are spent | fails the call; the event is sent all the same, from a `finally` |
-| `signInCode.confirm` | after the write, **before** the session or the second-factor challenge is opened | fails the call; the event is already sent |
+| `signInCode.confirm`, `magicLink.confirm` | after the write, **before** the session or the second-factor challenge is opened | fails the call; the event is already sent |
 | `secondFactor.activate`, `secondFactor.regenerateRecoveryCodes`, `secondFactor.disable` | after the write — the flow's last step | — |
 | `secondFactor.recover` | after the recovery code is spent and the session opened — or failed to open | fails the call; the recovery code is spent and the event sent all the same, from a `finally` |
 | `resetPassword.confirm` | **after** the sessions opened with the old password are revoked, and the other reset links and the second-factor challenges left open are spent | fails the call; the events are sent all the same, from a `finally` |

package/docs/guide/magic-link.md

@@ -0,0 +1,411 @@
+# Signing in with an e-mailed link
+
+This page is for signing a user in with a link sent to their e-mail — a
+"magic link": no password, nothing to type, and the link proves the address.
+`janus` issues and redeems the link's token; **building the link, sending the
+e-mail and the page it opens are yours**.
+
+```ts
+import { z } from 'zod';
+import { createMemoryStores, janus, scryptHasher } from '@nxgt/janus';
+
+async function sendMail(to: string, subject: string, text: string): Promise<void> {
+	// your mailer
+}
+
+const auth = janus({
+	user: z.object({ email: z.email() }),
+	password: { login: 'email' },
+	store: createMemoryStores(),
+	hasher: scryptHasher(),
+});
+
+const issued = await auth.magicLink.request('ada@example.com'); // { token, email, expiresAt, user } | null
+if (issued !== null) {
+	const link = `https://app.example/sign-in/link?token=${issued.token}`;
+	await sendMail(issued.email, 'Your sign-in link', `${link}\nIt expires in 15 minutes.`);
+}
+
+// the link opens a page of yours, whose button POSTs the token back:
+const signedIn = await auth.magicLink.confirm(token);
+signedIn.token; // a session, as signIn opens one
+signedIn.user.emailVerified; // true: the link reached the inbox
+```
+
+It is the [sign-in code](sign-in-code.md) with the code folded into a link:
+the same users have it, the same refusals, the same second factor. What
+differs is what a link is — something anybody holding the e-mail can open,
+on any device, **and that a mail scanner opens too**. The words — **sign-in
+link**, **one-time token**, **spent**, **issued** — are defined in
+[the vocabulary](vocabulary.md#identities).
+
+## Which types have it
+
+`magicLink` exists on every user type with an e-mail — the field `email`
+names, or a required string field called `email` — **with or without a
+password**, exactly as `signInCode` does. A type with no e-mail has no
+`magicLink`: it is absent from its type, not failing at run time.
+
+```ts
+clinic.patient.magicLink.request; // exists
+clinic.member.magicLink.request;  // exists: a passwordless type signs in by link or code
+// @ts-expect-error — staff have no e-mail to send a link to
+clinic.staff.magicLink;
+```
+
+## Requesting a link
+
+```ts
+const issued = await auth.magicLink.request(email);
+```
+
+`request` looks up the user of this type holding that e-mail — trimmed and
+lowercased first — and issues a token for them:
+
+```ts
+interface IssuedToken {
+	readonly token: string;   // 32 random bytes, base64url: for the link, and nowhere else
+	readonly email: string;   // the address to send it to, as the user's field holds it
+	readonly expiresAt: Date; // fifteen minutes from now, by default
+}
+// request answers IssuedToken & { readonly user: U } — or null
+```
+
+It answers **`null`** when nobody of this type holds that e-mail, when the
+user is inactive, and when the value matches a login that only looks like an
+e-mail. Nothing is issued, nothing is written.
+
+**Never tell the visitor which.** Answer the same page, with the same
+headers — "if an account uses that address, we sent it a link". Unlike a
+sign-in code, there is **no decoy to forge**: nothing of a link reaches the
+visitor, so the same `202` with no body and no cookie is already the same
+answer. Send the e-mail **after** answering, from a queue, so the time the
+answer takes does not tell either; the store's one write for a link issued,
+and none for `null`, still tells a patient observer.
+
+**At most one link is live per user.** A `request` issues its token, then
+spends every other link of the user, so the link in an earlier e-mail
+answers `TOKEN_SPENT` — only the last one works. Requests that arrive at
+once cannot each keep a link: at most one survives, sometimes none, and the
+visitor asks again. A link and a [sign-in code](sign-in-code.md) are
+separate kinds: asking for one leaves the other live.
+
+**Rate-limit the request route**, per address and per client, as you would a
+password reset: every call sends an e-mail, and cancels the link before it.
+Without a limit, anyone who knows an address can fill its inbox.
+
+## Building the link
+
+The token is base64url — safe in a URL without escaping — and goes in a
+link to **a page of yours**, never to the route that signs in:
+
+```ts
+const link = `https://app.example/sign-in/link?token=${issued.token}`;
+```
+
+Put the token **in the e-mail and nowhere else**: not in a log, not in an
+analytics event. A query string reaches your server's access log, so leave
+the query out of the log line on that path. Only the token's hash is
+stored, like a session token's, so the store cannot give it back.
+
+Send it to `issued.email`, not to what the visitor typed: it is the address
+the user's field holds, as they registered it.
+
+[`@nxgt/janus-mail`](https://www.npmjs.com/package/@nxgt/janus-mail)
+sends this e-mail ready-made, in English and French, over any `@nxgt/mail`
+transport: its **Sign in** button is built by `links.magicLink(token)` —
+point it at the page below — and it says how long the link lasts, from
+`issued.expiresAt`.
+
+```ts
+const mail = janusMail({ …, links: { …, magicLink: (token) => `https://app.example/sign-in/link?token=${token}` } });
+if (issued !== null) await mail.magicLink(issued, { locale: 'fr-CA' }); // the recipient's locale: sent in fr
+```
+
+`links.magicLink` is optional there, and `mail.magicLink` throws a
+`TypeError` without it. Its send rejects with the mailer's `MailFailure` when
+the transport fails: hand it to a queue that awaits it and retries, rather
+than a promise nobody awaits.
+
+## Confirming from a `POST`, never from the link's `GET`
+
+**Mail scanners open links.** A corporate gateway, a webmail's safe-browsing
+check and an antivirus fetch every URL in an e-mail before the user sees
+it, and some run its scripts. A route that signs in on `GET` would spend the
+token for the scanner: the user clicks, and gets `TOKEN_SPENT`.
+
+So the link lands on a **page that spends nothing**, and the user's click
+on a button there sends the `POST` that calls `confirm`:
+
+```ts
+const TOKEN = /^[A-Za-z0-9_-]{43}$/;
+
+// GET /sign-in/link?token=… — a page, and nothing else
+export function linkPage(request: Request): Response {
+	const token = new URL(request.url).searchParams.get('token') ?? '';
+	if (!TOKEN.test(token)) return new Response('This link is not valid.', { status: 400 });
+	return new Response(
+		`<!doctype html><meta charset="utf-8"><title>Sign in</title>
+<form method="post" action="/sign-in/link">
+	<input type="hidden" name="token" value="${token}">
+	<button>Sign in</button>
+</form>`,
+		{
+			headers: {
+				'Content-Type': 'text/html; charset=utf-8',
+				'Referrer-Policy': 'no-referrer', // the URL holds the token: send it nowhere
+				'Cache-Control': 'no-store',
+			},
+		},
+	);
+}
+```
+
+- **Echo only a token of the token's shape** — 43 base64url characters.
+  Anything else written into the page is a cross-site scripting hole.
+- **A button, not a script that submits by itself.** A scanner that runs
+  scripts submits the form too; one that does not click buttons does not.
+  Auto-submitting saves the user a click, at the price of every link a
+  script-running scanner opens.
+- **`Referrer-Policy: no-referrer`** keeps the URL, and the token in it, out
+  of the `Referer` of anything the page loads.
+- **Refuse a `POST` from another site.** The token says nothing of the
+  browser that asked for it: a page anywhere that posts a token of the
+  attacker's own account to your route signs its visitor in as the attacker,
+  and what they type next lands there. Check `Origin` against your own, or
+  that `Sec-Fetch-Site` is `same-origin`, before calling `confirm` — as the
+  route [below](#as-routes) does.
+
+## Confirming the link
+
+```ts
+const signedIn = await auth.magicLink.confirm(token);
+// { status: 'signedIn', user, session, token }: the session is open
+```
+
+`confirm` spends the token, marks the user's e-mail verified — the link
+reached the inbox — and opens a session: the same `SignedIn` that `signIn`
+answers. **The session opens in the browser that opened the link**, which
+need not be the one that asked for it: a link asked for on a laptop and
+opened on a phone signs the phone in. Where the sign-in must complete in
+the browser that started it, send a [sign-in code](sign-in-code.md) instead.
+
+The token is spent **by the first call**, in one conditional write, whether
+that call signs in or is refused: of ten confirmations of one link at once,
+exactly one signs in and nine answer `TOKEN_SPENT`. There is nothing to
+guess — 256 random bits — so no attempts are counted.
+
+### Lifetime
+
+A link lives **fifteen minutes** unless `tokens.magicLink` says otherwise,
+and is `TOKEN_EXPIRED` after that. Fifteen rather than a code's ten: the
+e-mail must arrive and be opened, and a scanner may hold it a minute first.
+No longer: whoever reads the mailbox in that window signs in.
+
+```ts
+janus({ ..., tokens: { magicLink: '30m' } });
+```
+
+### The e-mail is verified
+
+A user whose `emailVerified` was `false` has it `true` once `confirm`
+succeeds, and their `version` moves; a
+[`user.emailVerified` event](events.md) is sent. A user already verified is
+not written, and nothing is sent. The proof is written under the version
+read: a user written meanwhile answers `VERSION_CONFLICT`, with the link
+spent.
+
+### An account someone else registered
+
+The proof can land on an account its owner did not create. `signUp` does
+not wait for the e-mail to be proved, and `signIn` does not ask whether it
+was, so anyone can register `ada@example.com` with a password of theirs. When
+Ada later signs in by link, `confirm` marks the e-mail verified and opens her
+session — **and the other password, and the session `signUp` opened, still
+work**. A [password reset](email-flows.md) would have replaced both; a link
+or a [code](sign-in-code.md) touches neither.
+
+Where a password signs in before the e-mail is verified, **require
+`verifyEmail` before `signIn`**, and the question does not arise. Otherwise
+treat the first proof as a takeover of the address: `confirm` sends
+[`user.emailVerified`](events.md) exactly when the e-mail was not verified
+before, and awaits your listener before the session opens. Sign every
+session out there — `signOutEverywhere(user)`; the one `confirm` opens comes
+after — and have the user set a password of their own.
+
+### A second factor is still asked for
+
+The link proves the e-mail, not the second factor. With
+`janus({ secondFactor })`, a user whose factor is active gets **no session
+from the link**: `confirm` answers a challenge, exactly as `signIn` does,
+and [`secondFactor.confirm`](second-factor.md#confirming-the-code-at-sign-in)
+redeems it with their app's code.
+
+```ts
+const result = await auth.magicLink.confirm(token);
+if (result.status === 'secondFactor') {
+	// result.challenge: for secondFactor.confirm — keep it as a sign-in keeps it
+} else {
+	// result.token, result.session: set the cookie
+}
+```
+
+`confirm` answers `SignInResult` on a type whose `signIn` does — a type with
+a password, in an instance given a `secondFactor` — and reading `token`
+before narrowing on `status` is a compile error there. Anywhere else it
+answers `SignedIn`.
+
+### What `confirm` refuses
+
+| Rejects with | When | What to do |
+| --- | --- | --- |
+| `TOKEN_UNKNOWN` | no such link — a mangled URL, another user type's, a sign-in code's challenge, one whose user was deleted, or one a store's TTL already dropped. Message: `magicLink.confirm: no such token`. Another type's link is spent by the call | ask for a new link |
+| `TOKEN_SPENT` | the link already signed someone in, a newer `request` for the same user spent it, or an earlier `confirm` of it was refused. Message: `magicLink.confirm: the token was already used` | ask for a new link, and use the latest e-mail |
+| `TOKEN_EXPIRED` | `expiresAt` has passed. The link is spent | ask for a new link |
+| `TOKEN_STALE` | the user changed their e-mail since the link was sent. Message: `magicLink.confirm: the token was sent to an e-mail the user no longer has`. The link is spent | ask for a new link, to the current address |
+| `USER_INACTIVE` | the user was deactivated since the link was sent. The link is spent | answer 403 |
+| `VERSION_CONFLICT` | rare: another write to the user landed while `confirm` marked the e-mail verified. The link is spent | ask for a new link |
+
+Every refusal is a `TokenError` but `USER_INACTIVE`, a `UserInactiveError`;
+with several user types the message starts with the type:
+`patient.magicLink.confirm: …`. Every call may also reject with
+`STORE_FAILED` — `request` as well as `confirm`: your 503, never "no such
+account" nor a 401. [Troubleshooting](../troubleshooting.md#sign-in-links)
+has each message with its cause.
+
+## What does not end a link
+
+- **Writing the password.** `resetPassword.confirm`, `changePassword` and
+  `setPassword` spend the user's reset links and second-factor challenges,
+  not their sign-in links: the password proves nothing a link does, and
+  whoever holds the inbox can ask for another link anyway. The same holds
+  for sign-in codes.
+- **Signing out everywhere.** It revokes sessions; a link opens a new one.
+- **The sign-in throttle.** `signIn.throttle` counts passwords tried at one
+  login; a link is not a password, and its token cannot be guessed. Limit
+  `magicLink.request` yourself, as above.
+
+What does: its own redemption, a newer `request`, its fifteen minutes, an
+e-mail changed since (`TOKEN_STALE`), the user deactivated
+(`USER_INACTIVE`), and deleting the user, which deletes every token of
+theirs.
+
+## Options
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `tokens.magicLink` | `Duration` | `'15m'` | How long a link can be confirmed |
+| `email` | a field name | `'email'` | The field the link is sent to, and looked up by, per type |
+
+A `tokens.magicLink` that is not a duration is refused when `janus()` is
+called, with a `TypeError`: `janus: tokens.magicLink: "<value>" is not a
+duration; …`.
+
+## As routes
+
+The page above, and a fetch-style pair beside it — the shape Bun and most
+frameworks hand you;
+[`@nxgt/janus-hono`](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus-hono/docs/guide/routes.md#a-link-sent-by-e-mail)
+has the same in Hono, behind its `csrf()`:
+
+```ts
+import { JanusError, TokenError, UserInactiveError } from '@nxgt/janus';
+
+const ORIGIN = 'https://app.example';
+
+// POST /sign-in/email/link — ask for a link
+export async function requestLink(request: Request): Promise<Response> {
+	const { email } = (await request.json()) as { email: string };
+	const issued = await auth.magicLink.request(email);
+	if (issued !== null) {
+		const link = `${ORIGIN}/sign-in/link?token=${issued.token}`;
+		void sendMail(issued.email, 'Your sign-in link', link); // not awaited, so the answer's time tells nothing; in production, a queue that awaits and retries
+	}
+	return new Response(null, { status: 202 }); // the same answer either way
+}
+
+// POST /sign-in/link — the page's button
+export async function confirmLink(request: Request): Promise<Response> {
+	// Only your own page posts here: another site's form would sign its visitor in.
+	if (request.headers.get('Origin') !== ORIGIN) return new Response(null, { status: 403 });
+	const token = String((await request.formData()).get('token') ?? '');
+	try {
+		const signedIn = await auth.magicLink.confirm(token);
+		return new Response(null, {
+			status: 303,
+			headers: { Location: '/', 'Set-Cookie': auth.cookie.serialize(signedIn.token, signedIn.session) },
+		});
+	} catch (error) {
+		if (error instanceof UserInactiveError) return new Response(null, { status: 403 });
+		if (error instanceof TokenError || (error instanceof JanusError && error.code === 'VERSION_CONFLICT')) {
+			return new Response(null, { status: 303, headers: { Location: '/sign-in?link=expired' } });
+		}
+		throw error; // STORE_FAILED: your 503
+	}
+}
+```
+
+A refused link sends the user back to ask for another: every `TOKEN_*`, and
+the rare `VERSION_CONFLICT`, means the same thing to them. With a
+`secondFactor` configured, narrow `confirm`'s answer on `status` before
+reading `token`, and hand the challenge on to
+[the second factor's route](second-factor.md#a-sign-in-with-a-code-as-routes).
+
+## In a test
+
+No mailbox needed: `request` answers the token it would have sent.
+
+```ts
+import { expect, it } from 'bun:test';
+import { z } from 'zod';
+import { createMemoryStores, fixedClock, janus } from '@nxgt/janus';
+
+it('signs in with the e-mailed link, once, and not after fifteen minutes', async () => {
+	const clock = fixedClock(Date.UTC(2026, 0, 1));
+	const auth = janus({ user: z.object({ email: z.email() }), store: createMemoryStores(), clock });
+	await auth.create({ email: 'ada@example.com' });
+
+	const issued = await auth.magicLink.request('ada@example.com');
+	if (issued === null) throw new Error('expected a link');
+	expect((await auth.magicLink.confirm(issued.token)).user.emailVerified).toBe(true);
+	await expect(auth.magicLink.confirm(issued.token)).rejects.toMatchObject({ code: 'TOKEN_SPENT' });
+
+	const late = await auth.magicLink.request('ada@example.com');
+	if (late === null) throw new Error('expected a link');
+	clock.advance(15 * 60_000);
+	await expect(auth.magicLink.confirm(late.token)).rejects.toMatchObject({ code: 'TOKEN_EXPIRED' });
+});
+```
+
+## Signatures
+
+```ts
+interface MagicLinkApi<U, Answer = SignedIn<U>> {
+	readonly magicLink: {
+		request(email: string): Promise<(IssuedToken & { readonly user: U }) | null>;
+		confirm(token: string): Promise<Answer>;
+	};
+}
+```
+
+`Answer` is `SignInResult<U>` on a type with a password in an instance given
+a `secondFactor`, and `SignedIn<U>` everywhere else. `MagicLinkApi` and
+`IssuedToken` are exported from `@nxgt/janus`, as types.
+
+## For an adapter
+
+A link is a token of kind **`magicLink`**, new in 0.15. A store that lists
+the kinds — a `CHECK`, a validator's enum — lists it too; the conformance
+suite's `tokens.everyKind` fails until it does, and `tokens.magicLinkKind`
+holds that a link and a sign-in code are never redeemed as each other. See
+[adapters](adapters.md#sessionstore-and-tokenstore).
+
+## See also
+
+- [Sign-in codes](sign-in-code.md) — the same sign-in with a code to type, which completes in the browser that asked
+- [The second factor](second-factor.md) — the challenge `confirm` answers for a user whose factor is active
+- [E-mail verification and password reset](email-flows.md) — the other flows that send a link, and `TOKEN_STALE`
+- [Sessions](sessions.md) — the cookie the session is sent in
+- [Errors](errors.md) — every code and its status
+- [Troubleshooting](../troubleshooting.md#sign-in-links) — by the message you see
+- [`@nxgt/janus-telemetry`](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus-telemetry/docs/guide/tracing.md#a-link-sent-by-e-mail) — the events a sign-in by link writes

package/docs/guide/passwords.md

@@ -158,8 +158,9 @@ What it does, precisely:
   refused while the login is throttled**, so somebody who knows only a login
   can keep its password sign-in shut by trying ten passwords every window.
   That is the price of counting per login; limit per client address (below),
-  and a [sign-in code](sign-in-code.md), when you wire them, still opens
-  the account.
+  and a [sign-in code](sign-in-code.md) or [link](magic-link.md), when you
+  wire them, still opens the account: the throttle counts passwords, never
+  e-mailed codes or links.
 - **Per login, known or not.** A login nobody holds is counted as a
   registered one is — `unknownLogin` ten times, then `throttled` — so the
   throttle does not say which logins exist; an unknown login is still
@@ -232,8 +233,8 @@ The throttle counts per login. It does not see:
   the call, with the limiter you already run.
 - `changePassword`, which compares the current password too: limit it per
   user.
-- `resetPassword.request` and `signInCode.request`, which send e-mail: limit
-  them per address.
+- `resetPassword.request`, `signInCode.request` and `magicLink.request`,
+  which send e-mail: limit them per address.
 
 ```ts
 if (!(await limiter.consume(`sign-in:${clientAddress}`))) {

package/docs/guide/second-factor.md

@@ -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.
 
@@ -874,6 +874,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/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,6 +274,12 @@ 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.
 
+**The proof can land on an account someone else registered** — with a
+password of theirs, which keeps working, as does the session `signUp`
+opened. Where a password signs in before the e-mail is verified, see
+[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 })`,
@@ -499,6 +506,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