@nxgt/janus 0.19.0 → 0.21.0

package/docs/README.md

@@ -11,8 +11,8 @@ below are defined once, in [Words](guide/vocabulary.md#words).
 
 | Page | Read it when |
 | --- | --- |
-| [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 |
+| [Users](guide/users.md) | You are wiring `janus()`, declaring one or several user types, or calling `create`, `update`, `list`, `delete` — or finding a user by e-mail on a type with no password (`findByEmail`) |
+| [Sessions](guide/sessions.md) | You need to know who a request belongs to, set or clear the cookie, renew, sign out, or test expiry — or sign in a user your application proved itself, such as on accepting an invitation (`signInProven`) |
 | [E-mail verification and password reset](guide/email-flows.md) | You are sending a verification or reset link, and handling what comes back — and how requests that send e-mail are throttled per address or user |
 | [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 |

package/docs/guide/devices.md

@@ -95,6 +95,7 @@ Every call that opens a session takes `{ device }` as its last argument, a
 | `secondFactor.recover(challenge, code, { device })` | the same, after `user.recoveryCodeUsed` |
 | `signInCode.confirm(challenge, code, { device })` | the same — or a challenge, with an active second factor |
 | `magicLink.confirm(token, { device })` | the same — or a challenge, with an active second factor |
+| `signInProven(user, { device })` | the same — or a challenge, with an active second factor |
 
 A step-up opens no session, and takes no device. With several user types,
 the calls are the type's: `clinic.staff.signIn(input, { device })`.
@@ -412,6 +413,9 @@ secondFactor.recover(challenge: string, code: string, options?: SignInOptions):
 signInCode.confirm(challenge: string, code: string, options?: SignInOptions): Promise<Answer>;
 magicLink.confirm(token: string, options?: SignInOptions): Promise<Answer>;
 
+// On every user type:
+signInProven(user: UserRef, options?: SignInOptions): Promise<Answer>;
+
 janus({ ..., devices?: DevicesConfig });
 ```
 

package/docs/guide/email-flows.md

@@ -135,6 +135,7 @@ factor, and signs out every session](magic-link.md#an-account-someone-else-regis
 ```ts
 readonly resetPassword: {
 	request(email: string): Promise<(IssuedToken & { user: User }) | null>;
+	prepare(email: string): Promise<PreparedRequest<IssuedToken & { user: User }>>; // { send() }, below
 	confirm(token: string, password: string): Promise<User>;
 };
 ```
@@ -179,6 +180,12 @@ inbox with at most five reset e-mails a window, but cannot shut the reset:
 the last one sent still works. Limit the route per client yourself too, and
 see [the mail throttle](#requests-that-send-e-mail-are-throttled).
 
+`request`'s time still tells an account from nobody — a lookup, then a link
+written and the earlier ones spent, against a lookup alone. To keep that off
+the visitor's request and still answer them `MAIL_THROTTLED`, call
+`resetPassword.prepare(email)` there and its `send()` in the background:
+[requests in two steps](#requests-in-two-steps).
+
 **Writing a password spends every reset link still live.** A `confirm`,
 `changePassword` and `setPassword` each do, so a link sent before the
 password changed cannot replace it again:
@@ -280,6 +287,11 @@ janus: tokens.signInCode is 5m, shorter than mail.throttle.window, 10m — past
 Shorten `mail.throttle.window`, or raise the lifetime. Nothing is refused, so
 a window you chose on purpose only costs the warning.
 
+**`prepare` counts as `request` does**, in the same window: see
+[requests in two steps](#requests-in-two-steps), for an application that
+sends the e-mail off the visitor's request and still wants to tell them
+they are throttled.
+
 **Each flow counts on its own**: a loop on `magicLink.request` never shuts
 `signInCode.request`. The address is normalised (trimmed, lowercased) and is
 the same count whatever the user type.
@@ -382,6 +394,99 @@ bounds sign-ins), not a request to mail an address:
 `@nxgt/janus-telemetry` writes a `janus.mail.throttled` warning with
 `janus.mail.flow` and `janus.mail.retryAfter`, never the address.
 
+## Requests in two steps
+
+`request(email)` counts the address, then looks it up and issues. Its time
+tells what its answer does not: an address with an account costs a lookup,
+a token written and the earlier ones spent; one nobody holds stops at the
+lookup. So an application that must not tell the two apart runs `request`
+**off the visitor's request** — and there, a `MAIL_THROTTLED` reaches
+nobody: the visitor is never told to use the last e-mail they received.
+
+`prepare(email)` cuts `request` in two at the count, on the three flows
+counted per address:
+
+| Call | Does | Answers |
+| --- | --- | --- |
+| `magicLink.prepare(email)` | validates, counts the address, looks nobody up | `PreparedRequest<IssuedToken & { user }>`: `{ send() }` |
+| `signInCode.prepare(email)` | the same, and mints the challenge | `PreparedCode<User>`: `{ challenge, send() }` |
+| `resetPassword.prepare(email)` | the same, refusing a type with no password as `request` does | `PreparedRequest<IssuedToken & { user }>`: `{ send() }` |
+| `send()`, on any of them | the rest of `request` — the lookup, the token issued, the earlier ones spent — **once**, and counts nothing | what `request` answers: the token or code, or `null` for nobody |
+
+Call `prepare` in the visitor's request, where its `MailThrottledError` can be
+answered; call `send()` off it:
+
+```ts
+import { Hono } from 'hono';
+import { janusErrors } from '@nxgt/janus-hono';
+
+const app = new Hono();
+app.onError(janusErrors()); // MAIL_THROTTLED → 429, Retry-After and retryAfter in the body
+
+app.post('/reset-password', async (c) => {
+	const { email } = await c.req.json();
+	const pending = await auth.resetPassword.prepare(email); // counted: throws MAIL_THROTTLED past the limit
+	void mailOff(async () => {
+		const issued = await pending.send(); // looked up and issued, off the visitor's request
+		if (issued !== null) {
+			await mailer.send(issued.email, `https://app.example/reset?token=${issued.token}`);
+		}
+	});
+	return c.body(null, 202); // the same answer either way
+});
+
+/** Runs `work` off the request, and reports what it throws: nobody else will see it. */
+function mailOff(work: () => Promise<void>): Promise<void> {
+	return work().catch((error: unknown) => console.error(error));
+}
+```
+
+The visitor sees `429` with `retryAfter` past the limit — "use the last
+e-mail you received, or wait" — and `202` otherwise, in the same time whether
+the address has an account or not. In production, `send()` belongs in the
+queue that sends the e-mail, so a failure is retried by preparing again.
+
+**What `prepare` does is the same for every address.** It looks nobody up:
+the store calls are the count's, the same calls whoever holds the address,
+and none at all with `mail: { throttle: false }`, where `prepare` still
+validates and answers a pending request. `prepare` and `request` share one
+count: three `prepare` and two `request` of one flow for one address fill
+the window.
+
+**`send()` runs once.** The count `prepare` made pays for one issue, and
+nothing a caller passes can skip it — there is no option to say "already
+counted". A second `send()` is a `TypeError`:
+
+```
+magicLink.prepare(…).send: already called — a prepared request sends once; call magicLink.prepare again for another
+```
+
+A `send()` that failed — `STORE_FAILED` — is spent too: prepare again, which
+counts again. Two `send()` at once issue one token; the other is the
+`TypeError`.
+
+**A sign-in code's challenge comes with `prepare`.** The visitor keeps the
+challenge, and the code goes to the inbox, so a code requested in the
+background still needs its challenge in the foreground answer.
+`signInCode.prepare` mints it before the lookup, so it is in the visitor's
+cookie whoever holds the address — the decoy an unknown address needed is
+no longer yours to make. For an address nobody holds, `send()` answers
+`null` and the challenge is `TOKEN_UNKNOWN`; otherwise the code `send()`
+issues is checked against it. See
+[the sign-in code guide](sign-in-code.md#requesting-a-code-in-two-steps).
+
+**`verifyEmail.send` and `stepUp.request` have no `prepare`.** They are
+counted per user, and called for a user the application already holds — the
+session's, or one it just created — so their time tells nothing about who
+has an account, and their `MAIL_THROTTLED` already reaches the visitor in
+the request that asked.
+
+**`@nxgt/janus-telemetry`** traces `prepare` as
+`janus.magicLink.prepare` and its `send()` as `janus.magicLink.prepare.send`;
+`janus.mail.throttled` names `janus.mail.flow: magicLink.prepare`, and
+`janus.magicLink.sent` and `janus.signInCode.sent` are written by `send()`,
+as by `request`.
+
 ## What a token refusal means
 
 | Code | When |

package/docs/guide/errors.md

@@ -49,7 +49,7 @@ that wired the library, so no handler needs to tell it apart.
 | Code | Class | Status | When | Carries |
 | --- | --- | --- | --- | --- |
 | `STORE_FAILED` | `StoreFailure` | 503 | A store could not answer. **Never a negative answer** | `slot`, `operation`, `cause` |
-| `NOT_FOUND` | `NotFoundError` | 404 | `get`, `getUser`, or a write to a user who is gone. `find*` answers `null` instead | `userId` |
+| `NOT_FOUND` | `NotFoundError` | 404 | `get`, `getUser`, `signInProven`, or a write to a user who is gone. `find*` answers `null` instead | `userId` |
 | `LOGIN_TAKEN` | `StoreConflict` (`on: 'login'`) | 409 | Another user of the same type holds the login | `login`, `userType` |
 | `VERSION_CONFLICT` | `StoreConflict` (`on: 'version'`) | 409 | `ifVersion` no longer matches; nothing was written. From `secondFactor.confirm` or `recover`, the same code used by two sign-ins at once: the other opened the session | `expectedVersion`, `actualVersion` |
 | `USER_INVALID` | `UserInvalidError` | 400 | The fields failed the schema | `issues`, field by field |
@@ -57,7 +57,7 @@ that wired the library, so no handler needs to tell it apart.
 | `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 |
 | `MAIL_THROTTLED` | `MailThrottledError` | 429 | A request that sends e-mail was made too often for one address or one user in the window — see [the mail throttle](email-flows.md#requests-that-send-e-mail-are-throttled). **Nothing was issued, spent or rotated**: the last link or code sent still works | `retryAfter`, the whole seconds to the end of the window, at least 1; `userType`; `userId` only for the per-user flows. No `reason` |
-| `USER_INACTIVE` | `UserInactiveError` | 403 | Deactivated; told only to someone who gave the right password, the right code, or a live sign-in link | `userId` |
+| `USER_INACTIVE` | `UserInactiveError` | 403 | Deactivated; told only to someone who gave the right password, the right code, or a live sign-in link — or to the application, by `signInProven` | `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); 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` |

package/docs/guide/events.md

@@ -52,7 +52,7 @@ The words — **user event**, **listener** — are defined in
 | `user.secondFactorDisabled` | `secondFactor.disable`, when it removed an **active** factor; `signInCode.confirm` and `magicLink.confirm` when their first proof of the e-mail removed one, after `user.emailVerified` and any `user.passwordChanged` — even if an outage interrupts the sign-outs | for a user who had no factor, a factor still waiting for its first code — it was never asked for — or a second `disable` |
 | `user.recoveryCodesRegenerated` | `secondFactor.regenerateRecoveryCodes`: the codes the user held stopped working | for `activate`, whose first codes come with `user.secondFactorEnabled`; for a code refused |
 | `user.recoveryCodeUsed` | `secondFactor.recover`, once the recovery code is spent — even if opening the session then fails | for a recovery code refused. How many are left is not in the event: `secondFactor.recoveryCodesLeft(event.userId)` reads it |
-| `user.newDeviceSignedIn` | `signIn`, `secondFactor.confirm`, `secondFactor.recover`, `signInCode.confirm` and `magicLink.confirm`, given a `device` whose token did not prove this user signed in there — once the sign-in is complete. It carries `sessionId`, the new session's. See [devices](devices.md) | for `signUp`, which mints the first token; for a call given no `device`; for a known device; for a challenge, which opens no session; for a sign-in refused — a wrong password, or a `signIn` refused after its session opened because a password was written meanwhile |
+| `user.newDeviceSignedIn` | `signIn`, `secondFactor.confirm`, `secondFactor.recover`, `signInCode.confirm`, `magicLink.confirm` and `signInProven`, given a `device` whose token did not prove this user signed in there — once the sign-in is complete. It carries `sessionId`, the new session's. See [devices](devices.md) | for `signUp`, which mints the first token; for a call given no `device`; for a known device; for a challenge, which opens no session; for a sign-in refused — a wrong password, or a `signIn` refused after its session opened because a password was written meanwhile |
 | `user.deleted` | `delete`, when it deleted the user | for a replay that finds nobody, or an id of another user type |
 
 A reset whose link verifies the e-mail sends both, `user.passwordReset`
@@ -248,7 +248,7 @@ Where the listener runs within a flow, and what an outage does to it:
 | `signInCode.confirm`, `magicLink.confirm` | on an e-mail never verified: **after** every session is revoked and the reset links and second-factor challenges left open are spent — before the write and again after it — and **before** the new session or second-factor challenge is opened. `user.passwordChanged` follows `user.emailVerified` when a password was dropped, then `user.secondFactorDisabled` when an active second factor was removed. An e-mail already verified sends nothing | fails the call; the events are sent all the same, from a `finally`. An outage in the sign-outs before the write fails the call with nothing written and nothing sent: the next code or link proves the e-mail again |
 | `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` |
-| `signIn`, `secondFactor.confirm`, `secondFactor.recover`, `signInCode.confirm`, `magicLink.confirm` — `user.newDeviceSignedIn` | **last**, once the session is open and the sign-in complete: after `user.recoveryCodeUsed`, and after the events of a first proof of the e-mail | fails the call, and `user.newDeviceSignedIn` is not sent: it comes only once the sign-in is complete |
+| `signIn`, `secondFactor.confirm`, `secondFactor.recover`, `signInCode.confirm`, `magicLink.confirm`, `signInProven` — `user.newDeviceSignedIn` | **last**, once the session is open and the sign-in complete: after `user.recoveryCodeUsed`, and after the events of a first proof of the e-mail | fails the call, and `user.newDeviceSignedIn` is not sent: it comes only once the sign-in is complete |
 | `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` |
 | `delete` | **after** the user's sessions and one-time tokens are removed, and the relation tuples naming them when `relations` is wired | fails the call; the event is sent all the same, from a `finally` |
 

package/docs/guide/magic-link.md

@@ -53,6 +53,15 @@ clinic.member.magicLink.request;  // exists: a passwordless type signs in by lin
 clinic.staff.magicLink;
 ```
 
+**Accepting an invitation? Use `signInProven` instead of `request` +
+`confirm`.** When your server already verified the person — the invitation
+token it issued and they followed — call
+[`auth.signInProven(userId)`](sessions.md#signing-in-on-your-own-proof--signinproven):
+the same sign-in, second factor included, with no e-mail sent, no mail
+throttle counted and no earlier link spent. A `request` made only to be
+confirmed at once is counted per address, so five anonymous requests for the
+invitee's address would make the acceptance answer `MAIL_THROTTLED`.
+
 ## Requesting a link
 
 ```ts
@@ -130,6 +139,38 @@ addresses is not counted. Add a per-IP ceiling with `@nxgt/redis` rate limits
 [the mail throttle](email-flows.md#requests-that-send-e-mail-are-throttled)
 for the options.
 
+## Requesting a link in two steps
+
+`request` takes longer for an address with an account — a lookup, a token
+written, the earlier ones spent — than for one nobody holds. Run it off the
+visitor's request to hide that, and its `MAIL_THROTTLED` reaches nobody.
+`prepare` keeps the count in the visitor's request and moves the rest off
+it:
+
+```ts
+// in the visitor's request: validated and counted, nobody looked up
+const pending = await auth.magicLink.prepare(email); // MAIL_THROTTLED past the limit: answer 429
+
+// off it — a queue, or a promise you do not await
+void pending
+	.send() // what request answers: IssuedToken & { user } | null — and it counts nothing
+	.then((issued) => {
+		// ORIGIN as in As routes, below
+		if (issued !== null) return sendMail(issued.email, 'Your sign-in link', `${ORIGIN}/sign-in/link?token=${issued.token}`);
+	})
+	.catch(reportError);
+
+return new Response(null, { status: 202 }); // the same answer either way
+```
+
+`prepare` makes the same store calls whoever holds the address — the
+count's, none with the throttle off — so its time tells nothing. `send()`
+runs **once**: a second call, or one after a `send()` that failed, is a
+`TypeError` (`magicLink.prepare(…).send: already called — …`); prepare
+again, which counts again. The details, shared with sign-in codes and
+password resets, are in
+[the e-mail flows guide](email-flows.md#requests-in-two-steps).
+
 ## Building the link
 
 The token is base64url — safe in a URL without escaping — and goes in a
@@ -469,15 +510,21 @@ it('signs in with the e-mailed link, once, and not after fifteen minutes', async
 interface MagicLinkApi<U, Answer = SignedIn<U>> {
 	readonly magicLink: {
 		request(email: string): Promise<(IssuedToken & { readonly user: U }) | null>;
+		prepare(email: string): Promise<PreparedRequest<IssuedToken & { readonly user: U }>>;
 		confirm(token: string, options?: SignInOptions): Promise<Answer>;
 	};
 }
+
+interface PreparedRequest<Issued> {
+	send(): Promise<Issued | null>; // once: a second call is a TypeError
+	};
+}
 ```
 
 `Answer` is `SignInResult<U>` on a type with a password in an instance given
 a `secondFactor`, and `SignedIn<U>` everywhere else. `MagicLinkApi`,
-`IssuedToken` and `SignInOptions` are exported from `@nxgt/janus`, as
-types; `SignInOptions` is `{ device?: string | null }` — see
+`IssuedToken`, `PreparedRequest` and `SignInOptions` are exported from
+`@nxgt/janus`, as types; `SignInOptions` is `{ device?: string | null }` — see
 [devices](devices.md#giving-a-sign-in-the-device).
 
 ## For an adapter

package/docs/guide/passwords.md

@@ -234,7 +234,7 @@ The throttle counts per login. It does not see:
 - `changePassword`, which compares the current password too: limit it per
   user.
 - `resetPassword.request`, `signInCode.request` and `magicLink.request`,
-  which send e-mail: [the mail throttle](email-flows.md#requests-that-send-e-mail-are-throttled)
+  which send e-mail — and their `prepare`: [the mail throttle](email-flows.md#requests-that-send-e-mail-are-throttled)
   counts them per address, but not per client. Limit them per client.
 
 ```ts
@@ -250,7 +250,10 @@ const signedIn = await auth.signIn({ email, password });
 - The hash never reaches a `User` — `hasPassword` says whether there is one.
 - `signIn` compares against a dummy hash when nobody holds the login, so the
   time taken does not reveal which users exist. The store's own latency
-  still can, and that limit is stated rather than denied.
+  still can, and that limit is stated rather than denied. For a reset, a
+  sign-in code or a link, `prepare` takes that latency off the visitor's
+  request: it counts and looks nobody up, and `send()` does the rest in the
+  background ([requests in two steps](email-flows.md#requests-in-two-steps)).
 
 ## See also
 

package/docs/guide/second-factor.md

@@ -406,7 +406,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, or `magicLink.confirm`'s — with a recovery code instead of the app's code, and
+`signInCode.confirm`'s, `magicLink.confirm`'s or `signInProven`'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.
 

package/docs/guide/sessions.md

@@ -2,7 +2,9 @@
 
 This page is for everything after a user has signed in: finding who a request
 belongs to, the session cookie, renewal, signing out, and testing expiry.
-Signing up and signing in are on the [users](users.md) page.
+Signing up and signing in are on the [users](users.md) page; signing in a
+user your application proved itself — accepting an invitation — is
+[below](#signing-in-on-your-own-proof--signinproven).
 
 ```ts
 import { z } from 'zod';
@@ -194,6 +196,107 @@ do `signInCode.confirm` and `magicLink.confirm` when they prove an e-mail
 never verified, before opening their own session
 ([why](magic-link.md#an-account-someone-else-registered)).
 
+## Signing in on your own proof — `signInProven`
+
+Some sign-ins are proved by the application, not by janus: a person accepts
+an invitation your server issued, and the token they followed is the proof.
+`auth.<type>.signInProven(user, options?)` signs that user in and answers
+what every other sign-in answers — a `SignedIn`, or a challenge when their
+second factor is active.
+
+```ts
+signInProven(user: UserRef, options?: SignInOptions): Promise<SignInResult<User>>
+// SignedIn<User> on a type that cannot have a second factor
+```
+
+**It checks no credential: your server carries the proof.** It is a
+privileged call, like `setPassword`. Call it only right after verifying a
+proof your server issued, and take the id from that proof's own record —
+never from the request body, a query string, or a cookie the client wrote.
+An id a visitor can choose signs that visitor in as anybody.
+
+### Accepting an invitation
+
+The recipe the call is made for. The invitation is yours: a random token,
+stored hashed, used once, with an expiry — the same rules janus applies to
+its own links.
+
+```ts
+import { createHash, randomBytes } from 'node:crypto';
+
+const hash = (token: string) => createHash('sha256').update(token).digest('base64url');
+
+// Inviting: mail a link of yours to the address — nothing of janus's is sent.
+export async function invite(email: string) {
+	const token = randomBytes(32).toString('base64url');
+	await invitations.insert({ hash: hash(token), email, expiresAt: inSevenDays() });
+	await sendMail(email, `Join us: https://app.example/invitation?token=${token}`);
+}
+
+// Accepting — from the page's POST, never from the link's GET, which a mail scanner follows.
+export async function accept(request: Request): Promise<Response> {
+	const { token } = (await request.json()) as { token: string };
+	// One conditional write: spent once, and only while it has not expired.
+	const invitation = await invitations.spend(hash(String(token)), new Date());
+	if (invitation === null) return Response.json({ code: 'INVITATION_INVALID' }, { status: 404 });
+
+	// The address is the invitation's, never the request's. The person may already have an
+	// account — findByEmail counts nothing, sends nothing — or gets one, with no password.
+	const user =
+		(await auth.findByEmail(invitation.email)) ??
+		(await auth.create({ email: invitation.email, name: '' }));
+	const result = await auth.signInProven(user, { device: deviceOf(request) });
+	if (result.status === 'secondFactor') {
+		// keep result.challenge for the next request — never in a URL — and ask for a code
+		return Response.json({ next: 'code' });
+	}
+	return Response.json(
+		{ id: result.user.id },
+		{ headers: { 'Set-Cookie': auth.cookie.serialize(result.token, result.session) } },
+	);
+}
+```
+
+**`findByEmail` works on every type with an e-mail, password or not** —
+since 0.21. A type with no password has no `findByLogin`, and must not
+declare one just to be looked up: that would open the password and reset
+flows on it. It answers whether an account exists, so call it only here,
+after the invitation was verified, on the address the invitation holds
+([users](users.md#finding-a-user-by-e-mail--findbyemail)).
+
+**Before 0.20 this was `magicLink.request(email)` then `magicLink.confirm`,
+at once — use `signInProven` instead.** `request` is counted against the
+mail throttle per address, five per 10 minutes by default: anybody asking
+five links for the invitee's address made the real acceptance answer
+`MAIL_THROTTLED`, with a message about "the last one sent" when nothing had
+been sent. `signInProven` counts nothing, sends nothing, and spends nothing:
+a link or a code already in the person's inbox still works afterwards.
+
+### What it does, and what it does not
+
+- **The same ending as every sign-in.** A user whose second factor is active
+  gets `{ status: 'secondFactor', challenge }` — the application's proof is
+  a first factor — and `secondFactor.confirm` opens the session. Given a
+  `device`, it answers `newDevice` and `deviceToken`, and sends
+  `user.newDeviceSignedIn` for a device new to the user
+  ([devices](devices.md)). `@nxgt/janus-telemetry` traces it as
+  `janus.<type>.signInProven` and writes `janus.signIn` with
+  `janus.signIn.proven: true`.
+- **Refused as every sign-in refuses.** An inactive user is `USER_INACTIVE`;
+  a malformed id, an unknown one, a deleted user or a user of another type
+  is `NOT_FOUND`, as for `get` — never `null`, since a sign-in that found
+  nobody must not be read past. Options that are not `{ device }` are a
+  `TypeError`, as on every sign-in.
+- **No e-mail proved.** `emailVerified` stays as it was: the call does not
+  know your proof reached the inbox. Nothing is dropped either — unlike a
+  first proof by link or code, the password and second factor stay.
+- **No throttle.** Neither the mail throttle nor the sign-in throttle counts
+  it, and it restarts neither: a login past its password attempts is still
+  throttled for `signIn`. Limit your own acceptance route per client, as
+  any route that redeems a token.
+- **No route.** `@nxgt/janus-hono` and `@nxgt/janus-graphql` expose nothing
+  for it: the proof is yours, so the route is yours.
+
 ## `collectExpired`
 
 ```ts
@@ -242,6 +345,7 @@ cannot be replayed. `Session` is the stored record without that hash: `id`,
 ## See also
 
 - [Users](users.md) — `signUp`, `signIn`, the configuration
+- [Signing in with an e-mailed link](magic-link.md) — when janus, not your application, proves the person
 - [The second factor](second-factor.md) — the challenge `signIn` answers instead of a session
 - [Step-up](step-up.md) — proving again who you are, and `assertFresh`
 - [Devices](devices.md) — the device cookie beside the session cookie, and a sign-in from a new device

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

@@ -134,6 +134,52 @@ earlier ones: only the last code sent works — see
 throttle](email-flows.md#requests-that-send-e-mail-are-throttled); limit the
 route per client yourself too.
 
+## Requesting a code in two steps
+
+Sending the e-mail after answering hides the mailer's time, not the store's:
+`request` looks the address up and writes a code for an account, and stops
+at the lookup for nobody. Running all of `request` off the visitor's request
+hides that too — but then its `MAIL_THROTTLED` reaches nobody, and the
+challenge, which the visitor must keep, is not there to set in a cookie.
+`prepare` answers both:
+
+```ts
+// in the visitor's request: validated and counted, nobody looked up, a challenge minted
+const pending = await auth.signInCode.prepare(email); // MAIL_THROTTLED past the limit: answer 429
+
+// off it — a queue, or a promise you do not await
+void pending
+	.send() // what request answers: IssuedCode | null, its challenge pending.challenge — and it counts nothing
+	.then((issued) => {
+		if (issued !== null) return sendMail(issued.email, 'Your sign-in code', `Your code is ${issued.code}.`);
+	})
+	.catch(reportError);
+
+// the same answer either way, the challenge with it: no decoy to make
+// (CHALLENGE and scope as in [As routes](#as-routes), below)
+return Response.json(
+	{ next: 'code' },
+	{ status: 202, headers: { 'Set-Cookie': `${CHALLENGE}=${pending.challenge}; Max-Age=600; ${scope}` } },
+);
+```
+
+**The challenge is minted before the lookup**, so every visitor gets one,
+whoever holds the address. For an address nobody holds, `send()` answers
+`null` and the challenge confirms as `TOKEN_UNKNOWN`, exactly as the decoy
+did; for an account, the code `send()` issues is checked against it. Until
+`send()` has run, the challenge is `TOKEN_UNKNOWN` for an account too — a
+visitor who types a code first reads the e-mail first.
+
+`prepare` makes the same store calls whoever holds the address — the
+count's, none with the throttle off. `send()` runs **once**: a second call,
+or one after a `send()` that failed, is a `TypeError`
+(`signInCode.prepare(…).send: already called — …`); prepare again, which
+counts again and mints another challenge. The confirmation still tells a
+real challenge from a decoy by `attemptsLeft`: answer every refusal alike
+where that matters, as [above](#requesting-a-code). The details, shared
+with links and password resets, are in
+[the e-mail flows guide](email-flows.md#requests-in-two-steps).
+
 ## Sending the code by e-mail
 
 Put **the code, and only the code**, in the e-mail — with its lifetime, so
@@ -554,15 +600,21 @@ it('signs in with the e-mailed code, and not after ten minutes', async () => {
 interface SignInCodeApi<U, Answer = SignedIn<U>> {
 	readonly signInCode: {
 		request(email: string): Promise<IssuedCode<U> | null>;
+		prepare(email: string): Promise<PreparedCode<U>>;
 		confirm(challenge: string, code: string, options?: SignInOptions): Promise<Answer>;
 	};
 }
+
+interface PreparedCode<U> {
+	readonly challenge: string;                // for the visitor, now: the one send() issues the code under
+	send(): Promise<IssuedCode<U> | null>;     // once: a second call is a TypeError
+}
 ```
 
 `Answer` is `SignInResult<U>` on a type with a password in an instance given
 a `secondFactor`, and `SignedIn<U>` everywhere else. `IssuedCode`,
-`SignInCodeApi` and `SignInOptions` are exported from `@nxgt/janus`, as
-types; `SignInOptions` is `{ device?: string | null }` — see
+`PreparedCode`, `SignInCodeApi` and `SignInOptions` are exported from
+`@nxgt/janus`, as types; `SignInOptions` is `{ device?: string | null }` — see
 [devices](devices.md#giving-a-sign-in-the-device).
 
 ## See also

package/docs/guide/users.md

@@ -186,6 +186,7 @@ In the one-type form these are on `auth` itself; with several types, on
 | `update(user, patch, { ifVersion? })` | the user as written; sends `user.emailChanged` when the e-mail changed | `USER_INVALID`, `LOGIN_TAKEN`, `VERSION_CONFLICT`, `NOT_FOUND` |
 | `setActive(user, active, { ifVersion? })` | the user as written | `VERSION_CONFLICT`, `NOT_FOUND` |
 | `delete(user)` | `true`, or `false` for an unknown id or one of another type | |
+| `signInProven(user, { device? })` | **privileged** — after a proof your server verified, such as an invitation token: what `signIn` answers, a session or a second-factor challenge; no credential checked, nothing sent, counted or spent — see [sessions](sessions.md#signing-in-on-your-own-proof--signinproven) | `NOT_FOUND`, `USER_INACTIVE` |
 
 With a `password`, besides:
 
@@ -197,6 +198,12 @@ With a `password`, besides:
 | `setPassword(user, password, { ifVersion? })` | the user — an admin's call; spends the user's reset links and second-factor challenges still waiting, and signs nobody out; sends `user.passwordChanged` | `PASSWORD_TOO_SHORT` |
 | `changePassword(user, { current, next }, { ifVersion? })` | the user — the user's own call; spends the user's reset links and second-factor challenges still waiting; sends `user.passwordChanged` | `CREDENTIALS_INVALID`, `PASSWORD_TOO_SHORT` |
 
+With an e-mail — the field `email` names, password or not — besides:
+
+| Method | Answers | Rejects with |
+| --- | --- | --- |
+| `findByEmail(email)` | the user, or `null`; the address trimmed and lowercased as the e-mail flows do, whatever the login; a value that is no address is nobody's — **server-side only**, see [below](#finding-a-user-by-e-mail--findbyemail) | `STORE_FAILED` only |
+
 With `secondFactor` configured, a type with a password also answers
 `secondFactor.enroll`, `activate`, `disable` and `confirm` — see
 [the second factor](second-factor.md).
@@ -215,6 +222,7 @@ await auth.get(grace.id);                          // User, or NOT_FOUND
 const renamed = await auth.update(grace, { name: 'Grace Hopper' }, { ifVersion: grace.version });
 await auth.setActive(renamed, true);
 await auth.findByLogin('  GRACE@example.com ');    // found: normalised as sign-up normalised it
+await auth.findByEmail('  GRACE@example.com ');    // found: normalised as the e-mail flows normalise it
 await auth.setPassword(renamed, 'a new password');
 await auth.changePassword(renamed, { current: 'a new password', next: 'another password' });
 await auth.delete(renamed);                        // true
@@ -297,6 +305,68 @@ const staffById = new DataLoader(async (ids: readonly string[]) => {
 });
 ```
 
+### Finding a user by e-mail — `findByEmail`
+
+```ts
+findByEmail(email: string): Promise<User | null>
+// typed by FindByEmailApi<User>, exported from @nxgt/janus
+```
+
+Every type with an e-mail has it, **with or without a password** — and a
+type with no password has no `findByLogin`. It is the lookup an invitation
+needs: the person was invited at an address, may already hold an account of
+a passwordless type, and is signed in with `signInProven` once your server
+verified the invitation
+([sessions](sessions.md#accepting-an-invitation)):
+
+```ts
+const clinic = janus({
+	users: {
+		patient: { schema: Patient, password: { login: 'email' } },
+		member: { schema: z.object({ email: z.email(), name: z.string() }) }, // no password, by design
+	},
+	store,
+	hasher,
+});
+
+const invitation = await invitations.spend(hash(token), new Date()); // your proof, verified first
+if (invitation === null) return notFound();
+const member =
+	(await clinic.member.findByEmail(invitation.email)) ??
+	(await clinic.member.create({ email: invitation.email, name: '' }));
+await clinic.member.signInProven(member);
+```
+
+Do not declare a `password` on such a type to get `findByLogin`: it would
+open `signIn`, `resetPassword` and the password changes on a type that has
+none by design.
+
+- **The holder the e-mail flows find.** The address is trimmed and
+  lowercased — the rule every e-mail follows, whatever the type's
+  `password.normalize` — and compared with the stored e-mail. On a type that
+  signs in with a username, the user is found by their e-mail, and a
+  username that only looks like an address is nobody's:
+  `magicLink.request`, `signInCode.request` and `resetPassword.request`
+  would find the same user, or nobody.
+- **Per type.** The same address may hold a patient and a member; each
+  type answers its own, and `null` for the other's.
+- **Inactive users are answered**, as by `find`. `signInProven` then
+  refuses them with `USER_INACTIVE`.
+- **Nothing counted, issued or written.** Neither the mail throttle nor the
+  sign-in throttle counts it, so it answers past both, and leaves both as
+  they were. The store is read once, by `findUserByLogin`.
+- **A value that is no address is nobody's.** Not a string, empty once
+  trimmed, or holding a NUL or a lone surrogate: `null` without asking the
+  store — as `find` answers a malformed id, never a throw, since the value
+  may come from a request.
+- **An outage is `STORE_FAILED`**, never `null`: a lookup that could not
+  ask is not an absence.
+- **Server-side only.** It answers whether an account exists, at once and
+  with no throttle. Never call it on an address a visitor typed into an
+  anonymous route; call it on the address your own proof holds.
+  `@nxgt/janus-telemetry` traces it as `janus.<type>.findByEmail`, with the
+  `user.id` it found and never the address.
+
 ### Paging every user
 
 ```ts