@nxgt/janus 0.13.0 → 0.15.0

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

@@ -1,7 +1,8 @@
 # Password hashing
 
-This page is for choosing a password hasher, moving from one to another, and
-importing hashes written by another system. The login and the length policy
+This page is for choosing a password hasher, moving from one to another,
+importing hashes written by another system, and how `signIn` throttles
+password guessing. The login and the length policy
 are on the [users](users.md#options) page.
 
 ```ts
@@ -122,28 +123,126 @@ Write each imported user's hash as their `PasswordRecord` with your store's
 scrypt the first time they sign in. Wire one verifier
 per prefix the old system wrote (`$2a$`, `$2b$`, `$2y$` for bcrypt).
 
-## Rate-limit password guessing
+## Password guessing is throttled
 
-**Rate-limit `signIn` per login and per client: `janus` counts no failed
-password**, so without a limit anyone can guess one user's password — or try
-one password against every login — as fast as your server hashes. A sign-in
-code, a second factor and a step-up each count their guesses; a password
-does not. Put the limit in front of the call, with the limiter you already
-run:
+**`signIn` counts the passwords tried at each login, and past ten in a
+15-minute window it refuses every one — the right password included — until
+the window ends.** On by default. The refusal is the same `CREDENTIALS_INVALID`
+as a wrong password, with `reason: 'throttled'` for your logs and
+`retryAfter`, the seconds until the next window, for the client:
 
 ```ts
-const key = `sign-in:${email.trim().toLowerCase()}`;
-if (!(await limiter.consume(key))) {
+import { JanusError } from '@nxgt/janus';
+
+try {
+	return await auth.signIn({ email, password });
+} catch (error) {
+	if (error instanceof JanusError && error.code === 'CREDENTIALS_INVALID') {
+		const headers = error.retryAfter === undefined
+			? undefined
+			: { 'retry-after': String(error.retryAfter) };
+		return Response.json({ code: error.code, retryAfter: error.retryAfter }, { status: 401, headers });
+	}
+	throw error;
+}
+```
+
+[`janusErrors()`](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus-hono/docs/guide/routes.md#sign-up-and-sign-in) in
+`@nxgt/janus-hono` and `janusGraphQLError()` in `@nxgt/janus-graphql` do this
+for you, `Retry-After` header included.
+
+What it does, precisely:
+
+- **Nothing locks.** The next window signs in: no number of wrong
+  passwords blocks an account beyond its window. **But the right password is
+  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) 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
+  compared against a dummy hash, as before. The login is counted as
+  [`password.normalize`](users.md#passwordnormalize) writes it, within its
+  user type: `ADA@example.test` and `ada@example.test` share one count.
+- **Counted before anything is compared**, by the store, in one write per
+  attempt: of twenty passwords tried at once, exactly ten are compared. A
+  throttled attempt compares nothing, so it costs no hashing either.
+- **A sign-in that opens a session starts the count again** for that
+  login: the right password of an active user — and, with a second factor
+  active, only once its code or a recovery code opens the session. A
+  password that only opens a challenge restarts nothing, so knowing the
+  password buys no more than ten challenges per window.
+- **The windows are fixed slices of the clock**, not sliding: ten attempts
+  at the end of one window and ten at the start of the next are allowed.
+
+Change the limit or the window, or turn it off — `SignInConfig` and
+`SignInThrottleConfig` are the option's types, for a wrapper of your own:
+
+```ts
+janus({ ..., signIn: { throttle: { attempts: 5, window: '1h' } } });
+janus({ ..., signIn: { throttle: false } }); // counts nothing: limit signIn yourself
+```
+
+### Where the counts live
+
+In the tokens store, as `secondFactor` tokens that belong to no user: the
+store needs no new method, and an adapter that passes the conformance suite
+counts correctly. Each is named by a keyed hash of the login, never the login
+— keyed by your `secondFactor` keys when you wire them, and by a fixed key
+otherwise, which only keeps the login out of plain sight: a dump of the
+tokens then tells which logins were tried, for a guessed list. Each expires
+two windows after its window starts — half an hour by default — **Redis and MongoDB drop it then;
+PostgreSQL keeps it** until something deletes it, and every login tried,
+registered or not, adds a row per window. Schedule a delete with
+`@nxgt/janus-drizzle`:
+
+```sql
+delete from tokens where expires_at < now() - interval '1 hour'; -- janus.tokens when your tables have a schema of their own
+```
+
+`tokens` has no index on `expires_at`, so the delete scans the table: add
+`create index on tokens (expires_at)` in a migration of yours if it grows.
+
+The key is your first `secondFactor` key: wiring
+`secondFactor` for the first time, or putting a new key first, starts every
+login's count again. **A Redis tokens store that is flushed, or evicts keys under
+memory pressure, forgets them** and every count starts again: give Redis
+`maxmemory-policy noeviction` (see `@nxgt/janus-redis`).
+
+### When the store cannot count
+
+`signIn` throws `STORE_FAILED` — answer 503. It never answers a refusal the
+visitor could not have caused, and never lets a password through uncounted:
+**the throttle fails closed**, so a tokens-store outage stops password
+sign-ins as a users-store outage would. A sign-in whose password was right and
+whose count could not start again also throws `STORE_FAILED`, before any
+session is opened.
+
+The store's round-trips are observable, as its latency is: a login that
+signed in this window costs a few more probes than one nobody holds.
+
+### What you still limit yourself
+
+The throttle counts per login. It does not see:
+
+- **One password tried against many logins** (password spraying), nor many
+  logins from one client: limit `signIn` **per client address** in front of
+  the call, with the limiter you already run.
+- `changePassword`, which compares the current password too: limit it per
+  user.
+- `resetPassword.request`, `signInCode.request` and `magicLink.request`,
+  which send e-mail: limit them per address.
+
+```ts
+if (!(await limiter.consume(`sign-in:${clientAddress}`))) {
 	return new Response(null, { status: 429, headers: { 'retry-after': '900' } });
 }
 const signedIn = await auth.signIn({ email, password });
 ```
 
-Key it on the login normalised as
-[`password.normalize`](users.md#passwordnormalize) does — `lowercaseTrim` by
-default, as above — and add a second limit per client address; a few
-attempts per quarter hour per login is plenty for a person. `changePassword` compares the current password too: limit it per user.
-
 ## What never happens
 
 - The plain password is never stored, and never appears in an error message.
@@ -155,4 +254,4 @@ attempts per quarter hour per login is plenty for a person. `changePassword` com
 ## See also
 
 - [Users](users.md) — `signIn`, `setPassword`, `changePassword`
-- [Errors](errors.md) — `CREDENTIALS_INVALID` and its `reason`
+- [Errors](errors.md) — `CREDENTIALS_INVALID`, its `reason` and `retryAfter`

package/docs/guide/second-factor.md

@@ -306,8 +306,10 @@ try {
 ```
 
 Five attempts at a million values is a one-in-200,000 chance per password
-guessed right. A new challenge takes a new sign-in, with the password, so the
-attempts are bounded by your sign-in rate limit too.
+guessed right. A new challenge takes a new sign-in, with the password, and
+`signIn`'s throttle allows ten per login per 15-minute window — so the
+password alone buys at most ten challenges a window; a limit per client is
+yours to add.
 
 A call made through **another user type's** API — `auth.staff.secondFactor.confirm`
 for a patient's challenge — answers `TOKEN_UNKNOWN` and compares nothing, but
@@ -382,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.
 
@@ -872,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