@nxgt/janus 0.19.0 → 0.20.0

package/docs/README.md

@@ -12,7 +12,7 @@ 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 |
+| [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,96 @@ 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: create the user, then mail a link of yours — nothing of janus's is sent.
+export async function invite(email: string) {
+	const user = await auth.create({ email, name: '' }); // no password: they will never need one
+	const token = randomBytes(32).toString('base64url');
+	await invitations.insert({ hash: hash(token), userId: user.id, 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 });
+
+	const result = await auth.signInProven(invitation.userId, { 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) } },
+	);
+}
+```
+
+**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 +334,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:
 

package/docs/roadmap.md

@@ -76,7 +76,23 @@ Nothing yet.
 The last ten, newest first, each with the version it came in. Everything
 before is in the [CHANGELOG](../CHANGELOG.md).
 
-- **Several users by id in one query, v0.18.0** — `auth.<type>.findMany(ids)`
+- **Signing in on the application's own proof, v0.20.0** —
+  `auth.<type>.signInProven(user, { device })` signs in a user the
+  application proved itself — an invitation token it issued — and answers
+  what every sign-in answers: a session, or a second-factor challenge, with
+  the device and `USER_INACTIVE` handled alike. It sends no e-mail, counts
+  in no throttle and spends no link already sent, so accepting an
+  invitation no longer goes through `magicLink.request` and its mail
+  throttle. Privileged: never with an id a request supplied.
+- **E-mail requests in two steps, v0.20.0** — `magicLink.prepare(email)`,
+  `signInCode.prepare(email)` and `resetPassword.prepare(email)` count the
+  address and look nobody up — the same work for any address — so
+  `MAIL_THROTTLED` reaches the visitor while `send()`, the lookup and the
+  issue, runs off their request, where its time tells nothing. `send()`
+  answers what `request` does, once; a second call is a `TypeError`. A sign-in
+  code's prepared request carries its `challenge`, minted before the lookup,
+  so no decoy is needed for an address nobody holds.
+- **Several users by id in one query, v0.19.0** — `auth.<type>.findMany(ids)`
   answers the type's users in the order of `ids`, each once, and leaves out an
   id nobody of that type holds — for a list of rows that would otherwise make
   one `find` per row and fill the connection pool. The users store gains an
@@ -150,28 +166,3 @@ before is in the [CHANGELOG](../CHANGELOG.md).
   replace the new password. Both answer `TOKEN_SPENT`; an outage spending
   them fails the call with `STORE_FAILED`. No change for adapters: the
   existing `TokenStore.spendUserTokens` does it.
-- **Confirm an action with a code (step-up), v0.12.0** —
-  `auth.stepUp.request(user)` and `stepUp.confirm(request, challenge, code)`:
-  a signed-in user proves again who they are before a sensitive action, with
-  a six-digit code sent by e-mail — or, when their second factor is active,
-  the code from their app. The confirmation moves the session's
-  `authenticatedAt` and opens no session, and `assertFresh(session, maxAge)`
-  refuses an older one with `STEP_UP_REQUIRED` (403). A token kind of its
-  own, `stepUp`, and `SessionStore.reauthenticateSession`, in the three
-  adapters and the conformance suite.
-- **The recovery codes left, read again, v0.11.0** —
-  `secondFactor.recoveryCodesLeft(user)` answers the count `recover`
-  answered, for a `user.recoveryCodeUsed` listener — the event names the
-  user only — or a security settings page; `null` for a user with no active
-  factor. The listener can now tell the user how many codes remain, as
-  `@nxgt/janus-mail`'s `recoveryCodeUsed` e-mail does.
-- **Sending the e-mails, `@nxgt/janus-mail` v0.1.0** — a package of its
-  own, built on the `@nxgt/mail` toolkit: `janusMail({ mailer, from, brand,
-  links })` takes what each flow answers —
-  `await mail.verifyEmail(await auth.verifyEmail.send(user), { name, locale })`
-  — and sends five e-mails, in English and French, over any `@nxgt/mail`
-  transport: e-mail verification, password reset, sign-in code, and the
-  notices *password changed* and *e-mail changed*. They are built once with
-  Maizzle when the package is built, and only filled in at send time, every
-  value escaped: no template engine in your server. A transport that fails
-  throws, like a store.