@nxgt/janus 0.20.0 → 0.22.0

package/docs/README.md

@@ -11,9 +11,9 @@ 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` |
+| [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 |
+| [E-mail verification and password reset](guide/email-flows.md) | You are sending a verification or reset link, and handling what comes back — or proving an address on your own proof, such as an invitation (`verifyEmail.proveFirst`) — 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 |
 | [The second factor](guide/second-factor.md) | You are turning on TOTP codes: making and rotating the sealing keys, the QR code, `signIn`'s `status`, confirming a challenge, recovery codes for a lost phone, disabling |

package/docs/guide/email-flows.md

@@ -111,6 +111,7 @@ with or without a password — see [sign-in codes](sign-in-code.md) and
 readonly verifyEmail: {
 	send(user: UserRef): Promise<IssuedToken>; // { token, email, expiresAt }
 	confirm(token: string): Promise<User>;
+	proveFirst(user: UserRef): Promise<FirstProof<User>>; // { user, proved } — privileged, below
 };
 ```
 
@@ -130,6 +131,64 @@ Changing the e-mail with `update` sets `emailVerified` back to `false` — and
 the next sign-in by code or link then [drops the password and the second
 factor, and signs out every session](magic-link.md#an-account-someone-else-registered).
 
+## Proving an e-mail on your own proof — `proveFirst`
+
+`verifyEmail.confirm` proves an address and changes nothing else: the user
+asked for the link from inside their own account. A first sign-in by link
+or code goes further, since anybody may have signed up with the address
+before its holder ([why](magic-link.md#an-account-someone-else-registered)).
+`verifyEmail.proveFirst(user)` applies that same first proof when the proof
+is **yours** — an invitation token your server mailed to the address, and
+the person followed:
+
+```ts
+interface FirstProof<User> {
+	readonly user: User;      // after the call: emailVerified is true either way
+	readonly proved: boolean; // true: this call proved it; false: it was already proved
+}
+
+const { user, proved } = await auth.verifyEmail.proveFirst(invited);
+```
+
+On an e-mail **never proved**, it is exactly the ending of
+`magicLink.confirm` and `signInCode.confirm` — the same code runs:
+
+- one write, under the version it read, marks the e-mail verified and drops
+  the password and the second factor, active or waiting, with its recovery
+  codes;
+- every session is revoked, and the reset links and second-factor
+  challenges are spent — before the write, so an outage there leaves the
+  e-mail unproved and a retry runs it all again, and after it, so a sign-in
+  landing in between is ended too;
+- `user.emailVerified` is sent, then `user.passwordChanged` when a password
+  was dropped and `user.secondFactorDisabled` when an active factor was.
+
+On an e-mail **already proved**, nothing is written, revoked or sent, and
+`proved` is `false`. Whether it was proved is read off the user, as the
+confirms read it: `emailVerified`.
+
+**Call it before `setPassword` and before `signInProven`.** It drops the
+password and revokes every session, so in the other order it erases the
+password the invitee just chose, and signs out the session just opened.
+Accepting an invitation is `findByEmail` (or `create`), `proveFirst`,
+`setPassword` for a type with a password, then `signInProven` —
+[sessions](sessions.md#accepting-an-invitation) has the route in full.
+
+**It is privileged.** janus checks no credential: call it only right after
+your server verified a proof that reached the inbox — an invitation token
+it mailed to that address — on the user the proof names, whose current
+e-mail is the address it reached. Never with an id a request supplied:
+whoever chooses it can drop anybody's password and second factor.
+
+It sends no e-mail, issues no token, and counts in neither the mail
+throttle nor the sign-in throttle. An inactive user is `USER_INACTIVE`; a
+malformed id, an unknown one or one of another type is `NOT_FOUND`, as for
+`signInProven`; a user written between the read and the write is
+`VERSION_CONFLICT`, and nothing is proved; an outage is `STORE_FAILED`.
+`@nxgt/janus-telemetry` traces it as `janus.<type>.verifyEmail.proveFirst`
+and writes `janus.email.verified` with `janus.email.proveFirst: true` when
+it proved — the user's id, never the address.
+
 ## `resetPassword`
 
 ```ts
@@ -506,5 +565,5 @@ never the token, and no refusal's message contains it.
 - [Sign-in codes](sign-in-code.md) — the third flow that sends an e-mail: a code, not a link
 - [Sign-in links](magic-link.md) — the fourth: a link that signs in, confirmed from a `POST` so a mail scanner spends nothing
 - [Sessions](sessions.md) — `signOutEverywhere`, which `resetPassword.confirm` calls for you
-- [User events](events.md) — `user.emailVerified` and `user.passwordReset`, which the confirms send
+- [User events](events.md) — `user.emailVerified` and `user.passwordReset`, which the confirms and `proveFirst` send
 - [Errors](errors.md) — every code, and the status it deserves

package/docs/guide/errors.md

@@ -49,15 +49,15 @@ 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`, `signInProven`, or a write to a user who is gone. `find*` answers `null` instead | `userId` |
+| `NOT_FOUND` | `NotFoundError` | 404 | `get`, `getUser`, `signInProven`, `verifyEmail.proveFirst`, 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` |
+| `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. From `verifyEmail.proveFirst`, the user was written between its read and its write: nothing was proved — call it again | `expectedVersion`, `actualVersion` |
 | `USER_INVALID` | `UserInvalidError` | 400 | The fields failed the schema | `issues`, field by field |
 | `PASSWORD_TOO_SHORT` | `CredentialError` | 400 | Below `password.minLength` | `minLength` — never the password |
 | `CREDENTIALS_INVALID` | `CredentialError` | 401 | Unknown login, no password, or the wrong one — **one code for the three** — and any password, the right one included, at a login past its attempts in the window — see [throttling](passwords.md#password-guessing-is-throttled) | `reason`, for your logs only; `retryAfter`, the seconds until the next window, when throttled |
 | `HASH_UNSUPPORTED` | `CredentialError` | 400 | A stored hash no wired hasher reads | `hashPrefix` — never the hash |
 | `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 — or to the application, by `signInProven` | `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` and `verifyEmail.proveFirst` | `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

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

package/docs/guide/magic-link.md

@@ -58,7 +58,10 @@ clinic.staff.magicLink;
 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
+throttle counted and no earlier link spent. Call
+[`verifyEmail.proveFirst`](email-flows.md#proving-an-e-mail-on-your-own-proof--provefirst)
+before it: the invitation reached the inbox, and a first proof drops what
+somebody who signed up with the address left on it, as a link does. 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`.
 
@@ -307,7 +310,9 @@ their own phone. When Ada later signs in by link, `confirm` proves an e-mail
 never verified, and **drops the password and the second factor, and signs
 out every session** before it opens hers — as a
 [password reset](email-flows.md) does. The same holds for a
-[code](sign-in-code.md).
+[code](sign-in-code.md), and for
+[`verifyEmail.proveFirst`](email-flows.md#proving-an-e-mail-on-your-own-proof--provefirst),
+which applies this proof when the proof is your own — an invitation.
 
 - In the write that proves the e-mail, the password is removed
   (`hasPassword` turns `false`), and so is the second factor, active or

package/docs/guide/sessions.md

@@ -226,22 +226,33 @@ 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.
+// Inviting: mail a link of yours to the address — 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 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 };
+	const body = (await request.json()) as { token: string; password?: string };
+	const { token } = body;
 	// 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) });
+	// 1. 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: '' }));
+	// 2. The invitation reached the inbox: prove the e-mail. On an address never proved this
+	// drops whatever someone who signed up with it set — password, second factor, sessions.
+	await auth.verifyEmail.proveFirst(user);
+	// 3. Only now the invitee's own password, if your form asks for one: proveFirst would drop it.
+	if (typeof body.password === 'string') await auth.setPassword(user, body.password);
+	// 4. Last: proveFirst revokes every session, so the new one opens after it.
+	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' });
@@ -253,6 +264,25 @@ export async function accept(request: Request): Promise<Response> {
 }
 ```
 
+**The order is the recipe.** `verifyEmail.proveFirst` (since 0.22) applies
+the first proof of the e-mail that a sign-in link would: on an address
+never proved, somebody may have signed up with it first, with a password
+and a second factor of their own, and `signInProven` alone would leave them
+both — and that person's sessions — in place. It drops them and revokes
+every session, so it comes **before** `setPassword`, which would otherwise
+be erased, and **before** `signInProven`, whose session would otherwise be
+revoked. On an address already proved it does nothing. It is privileged as
+`signInProven` is: call it on the user your verified invitation names,
+never on an id from the request
+([e-mail flows](email-flows.md#proving-an-e-mail-on-your-own-proof--provefirst)).
+
+**`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
@@ -278,7 +308,8 @@ a link or a code already in the person's inbox still works afterwards.
   `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.
+  first proof by link or code, the password and second factor stay. When
+  your proof did reach the inbox, call `verifyEmail.proveFirst` first.
 - **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

package/docs/guide/users.md

@@ -198,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).
@@ -216,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
@@ -298,6 +305,69 @@ 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 and `verifyEmail.proveFirst` proved the address
+([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.verifyEmail.proveFirst(member); // before signInProven: it revokes every session
+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

package/docs/guide/vocabulary.md

@@ -43,7 +43,7 @@ either finds this row.
 | **credential** | What a caller presents to prove who they are: a login and a password at sign-in (`CredentialError`, `CREDENTIALS_INVALID`), or a token on a request — always written *session credential* | |
 | **password policy** | The rules a new password must meet: `minLength`, `normalize` | the model |
 | **session** | A signed-in period, carried by a **session token** | |
-| **lapsed**, **revoked**, **renewed** | A session past its `expiresAt`; one ended by a sign-out, a password reset, or the first proof of an e-mail by a code or a link; one whose `expiresAt` moved in passing (`renewAfter`) | "expired" — kept for `TOKEN_EXPIRED`, a one-time token |
+| **lapsed**, **revoked**, **renewed** | A session past its `expiresAt`; one ended by a sign-out, a password reset, or the first proof of an e-mail by a code, a link or `verifyEmail.proveFirst`; one whose `expiresAt` moved in passing (`renewAfter`) | "expired" — kept for `TOKEN_EXPIRED`, a one-time token |
 | **anonymous** | A request that presents no session credential, or one that authenticates nobody: `authenticate` answers `null` | "unauthenticated", "guest", "logged out" |
 | **bearer client** | A client that sends its session token as `Authorization: Bearer` rather than in a cookie | |
 | **one-time token** | A single-use token sent by e-mail in a link, for verification, a password reset or a sign-in | "code": a code is typed, a token is followed in a link |

package/docs/roadmap.md

@@ -76,6 +76,22 @@ Nothing yet.
 The last ten, newest first, each with the version it came in. Everything
 before is in the [CHANGELOG](../CHANGELOG.md).
 
+- **Proving an e-mail on the application's own proof, v0.22.0** —
+  `auth.<type>.verifyEmail.proveFirst(user)` applies the first proof of an
+  e-mail that a sign-in link or code applies — verified, the password and
+  the second factor dropped, every session revoked — when the proof is the
+  application's, such as an invitation token mailed to the address. An
+  e-mail already proved changes nothing; the answer says which,
+  `{ user, proved }`. Nothing is counted, sent or issued. An invitation is
+  accepted in this order: find or create, `proveFirst`, `setPassword`,
+  `signInProven`. Privileged: never with an id a request supplied.
+- **Finding a user by e-mail on every type, v0.21.0** —
+  `auth.<type>.findByEmail(email)` answers the user of the type holding the
+  address, or `null`, on every type with an e-mail — a type with no
+  password included, which has no `findByLogin`. The address is normalised
+  and compared as the e-mail flows do; nothing is counted, issued or
+  written. It is the lookup before `signInProven` when an invitation holds
+  an address. Server-side only: it tells whether an account exists.
 - **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
@@ -151,18 +167,3 @@ before is in the [CHANGELOG](../CHANGELOG.md).
   `signIn: { throttle: false }` turns it off. A tokens store that cannot
   count fails the sign-in with `STORE_FAILED`. No change for adapters: the
   counts are `secondFactor` tokens, counted by `TokenStore.countAttempt`.
-- **A password or an e-mail changed, in the user events, v0.14.0** —
-  `user.passwordChanged`, sent by `changePassword` and `setPassword` once the
-  older reset links are spent (a reset stays `user.passwordReset` alone), and
-  `user.emailChanged`, sent by an `update` that changed the e-mail, carrying
-  `formerEmail` — the one event with more than the user's id — so a notice
-  can reach the inbox the account just left, as `@nxgt/janus-mail`'s
-  `passwordChanged` and `emailChanged` notices do. Breaking for a `switch`
-  that exhausts `UserEventType`.
-- **An old reset link stops working, v0.13.0** — `resetPassword.request`
-  spends the links sent before, so only the last e-mail's works, and writing
-  a password — a link's `confirm`, `changePassword`, `setPassword` — spends
-  every reset link still live, so a link sent before the change cannot
-  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.

package/docs/troubleshooting.md

@@ -53,6 +53,7 @@ How the messages are shaped:
 - [`STORE_FAILED` — `users.findUsers answered no list …`](#store_failed--usersfindusers-answered-no-list-an-absence-is-a-shorter-list-so-this-store-forgot-to-answer)
 - [`<call>: ids must be an array of user ids`](#call-ids-must-be-an-array-of-user-ids)
 - [`findMany` answers fewer users than ids](#findmany-answers-fewer-users-than-ids)
+- [`findByEmail` answers `null` for an address somebody holds](#findbyemail-answers-null-for-an-address-somebody-holds)
 - [`NOT_FOUND` — `<call>: no <type> has this id`](#not_found--call-no-type-has-this-id)
 - [`LOGIN_TAKEN` — `<call>: the login is taken by another <type>`](#login_taken--call-the-login-is-taken-by-another-type)
 - [`VERSION_CONFLICT` — `<call>: expected version <n>, found <m>`](#version_conflict--call-expected-version-n-found-m)
@@ -62,6 +63,7 @@ How the messages are shaped:
 - [`CREDENTIALS_INVALID` — `<call>: too many passwords tried at this login …`](#credentials_invalid--call-too-many-passwords-tried-at-this-login--wait-for-the-next-window)
 - [`MAIL_THROTTLED` — `<call>: too many e-mails asked for this address …`, or `… for this user …`](#mail_throttled--call-too-many-e-mails-asked-for-this-address--the-last-one-sent-still-works-use-it-or-wait-for-the-next-window)
 - [Accepting an invitation answers `MAIL_THROTTLED`](#accepting-an-invitation-answers-mail_throttled)
+- [The password chosen when accepting an invitation answers `CREDENTIALS_INVALID` (`noPassword`)](#the-password-chosen-when-accepting-an-invitation-answers-credentials_invalid-nopassword)
 - [`MAIL_THROTTLED` never reaches the visitor: `request` runs in the background](#mail_throttled-never-reaches-the-visitor-request-runs-in-the-background)
 - [`<flow>.prepare(…).send: already called — …`](#flowpreparesend-already-called--a-prepared-request-sends-once-call-flowprepare-again-for-another)
 - [`STORE_FAILED` — `<call>: the store dropped the attempts it had just stored`](#store_failed--call-the-store-dropped-the-attempts-it-had-just-stored)
@@ -584,9 +586,22 @@ const byId = new Map((await auth.staff.findMany(ids)).map((user) => [user.id, us
 const member = byId.get(row.staffId); // undefined: nobody of this type holds it
 ```
 
+### `findByEmail` answers `null` for an address somebody holds
+
+**When:** `auth.<type>.findByEmail(email)` on an address you can see on a user.
+**Why:** one of three. The user is of **another type**: each type answers its own users, and the same address may hold one of each. The address is the type's **login, not its e-mail**: on a type that signs in with a username, only the field `email` names is looked up, and a username that looks like an address is nobody's. Or the value is **no address**: not a string — a `{ email }` object from JavaScript, an `undefined` read off a record — empty once trimmed, or holding a NUL or a lone surrogate; it answers `null` without asking the store, as `find` answers a malformed id.
+**Fix:** ask the type the user is of, pass the e-mail itself, and for a username use `findByLogin`:
+
+```ts
+const member = await clinic.member.findByEmail(invitation.email); // a string: the address the invitation holds
+const staff = await clinic.staff.findByLogin('grace');           // a username is a login, not an e-mail
+```
+
+An outage is never `null` here: it rejects with `STORE_FAILED`.
+
 ### `NOT_FOUND` — `<call>: no <type> has this id`
 
-`NotFoundError`, from `get`, `getUser`, `update`, `setActive`, `setPassword`, `signInProven`, `verifyEmail.send`, `secondFactor.recoveryCodesLeft`. Also `<call>: the user has no e-mail`.
+`NotFoundError`, from `get`, `getUser`, `update`, `setActive`, `setPassword`, `signInProven`, `verifyEmail.send`, `verifyEmail.proveFirst`, `secondFactor.recoveryCodesLeft`. Also `<call>: the user has no e-mail`.
 
 **When:** the id names nobody, names a user of another type (`auth.staff.get(patientId)`), or is not an id at all.
 **Why:** `get*` calls turn an absence into `NOT_FOUND`; `find*` calls answer `null` instead. `signInProven` is a `get`: a sign-in that found nobody throws, and on it `NOT_FOUND` means the proof you verified names a user deleted since, or you passed the id of another type's user — or a value that is not the proof's id at all.
@@ -617,6 +632,13 @@ const user = await auth.get(id);
 await auth.update(user, { name }, { ifVersion: user.version });
 ```
 
+**From `verifyEmail.proveFirst`**, with no `ifVersion` of yours: the user
+was written between the read that found the e-mail never proved and the
+write that proves it — by the user, or by a second acceptance of the same
+invitation. Nothing was proved, though the sessions may already be revoked.
+Call it again: it reads the user anew, and answers `proved: false` when the
+other write proved the e-mail.
+
 **From `secondFactor.confirm`**, the message is the store's:
 `updateUser: expected version <n>, found <m>`.
 
@@ -775,19 +797,47 @@ sent still works, though the invitee was sent none.
 loop from filling an inbox. A sign-in your server already proved — the
 invitation token it issued — does not need an e-mailed link, and should not
 share its count.
-**Fix:** call `signInProven` with the id from the invitation's record, after
+**Fix:** call `signInProven` with the user from the invitation's record, after
 verifying the token yourself. It counts nothing, sends nothing, spends no
-link already sent, and answers what `signIn` answers.
+link already sent, and answers what `signIn` answers. An invitation that
+holds an address rather than an id finds the account with `findByEmail`,
+which counts nothing either — on any type with an e-mail, password or not.
 
 ```ts
 const invitation = await invitations.spend(hash(token), new Date()); // yours: once, unexpired
 if (invitation === null) return new Response(null, { status: 404 });
-const result = await auth.signInProven(invitation.userId, { device: deviceOf(request) });
+const user = await auth.findByEmail(invitation.email); // or invitation.userId, when you stored the id
+if (user === null) return new Response(null, { status: 404 });
+await auth.verifyEmail.proveFirst(user); // the invitation reached the inbox — before signInProven
+const result = await auth.signInProven(user, { device: deviceOf(request) });
 ```
 
 Never pass it an id the request carries: it checks no credential. See
 [sessions](guide/sessions.md#signing-in-on-your-own-proof--signinproven).
 
+### The password chosen when accepting an invitation answers `CREDENTIALS_INVALID` (`noPassword`)
+
+**When:** the acceptance route calls `setPassword` with the password the
+invitee chose, then `verifyEmail.proveFirst`; the invitee is signed in, and
+their next `signIn` with that password answers `CREDENTIALS_INVALID` with
+`reason: 'noPassword'`. Or the route calls `signInProven` before
+`proveFirst`, and the session it just opened is anonymous on the next
+request.
+**Why:** on an e-mail never proved, `proveFirst` drops the password and the
+second factor and revokes every session — whatever was set before it is
+taken for what somebody who signed up with the address left there. It
+cannot tell the invitee's fresh password from a squatter's.
+**Fix:** prove first, then set the password, then sign in:
+
+```ts
+const user = (await auth.findByEmail(invitation.email)) ?? (await auth.create({ email: invitation.email, name }));
+await auth.verifyEmail.proveFirst(user); // 1. drops what was there before
+await auth.setPassword(user, body.password); // 2. the invitee's own
+const result = await auth.signInProven(user, { device: deviceOf(request) }); // 3. last
+```
+
+See [e-mail flows](guide/email-flows.md#proving-an-e-mail-on-your-own-proof--provefirst).
+
 ### `MAIL_THROTTLED` never reaches the visitor: `request` runs in the background
 
 **When:** the application runs `magicLink.request`, `signInCode.request` or
@@ -867,7 +917,7 @@ janus({ ..., hasher: scryptHasher(), verifiers: [bcryptVerifier] }); // a Passwo
 
 ### `USER_INACTIVE` — `<call>: the user is inactive`
 
-**When:** `signIn`, with the **right** password, for a user set inactive. Also `secondFactor.confirm` and `secondFactor.recover`, for a user set inactive after `signIn` asked for a code, `signInCode.confirm`, for a user set inactive after the code was sent, and `magicLink.confirm`, for one set inactive after the link was sent. And `signInProven`, for an inactive user: the application's proof does not reactivate anybody.
+**When:** `signIn`, with the **right** password, for a user set inactive. Also `secondFactor.confirm` and `secondFactor.recover`, for a user set inactive after `signIn` asked for a code, `signInCode.confirm`, for a user set inactive after the code was sent, and `magicLink.confirm`, for one set inactive after the link was sent. And `signInProven` and `verifyEmail.proveFirst`, for an inactive user: the application's proof does not reactivate anybody, and proves nothing on an inactive one.
 **Why:** an inactive user keeps their record and password, and every sign-in is refused. It is checked after the password, so only somebody who knows the password learns the user is inactive — and after the code, so only somebody who read the e-mail does: `signInCode.request` answers `null` for an inactive user, as for nobody. On either `confirm`, the challenge is spent: reactivating the user does not revive it. `magicLink.confirm` checks after spending the link, which is spent too, and `magicLink.request` answers `null` for an inactive user.
 **Fix:** answer 403, or reactivate, then sign in again: `await auth.setActive(user, true)`.
 
@@ -1006,7 +1056,7 @@ const page = await access.list(user, 'view', 'record', {
 
 **When:** `signIn`, `findByLogin`, `setPassword`, `changePassword`, `resetPassword.*`, from JavaScript. In TypeScript, these methods are absent from a type without `password`.
 **Why:** the user type has no `password` option.
-**Fix:** `users: { staff: { schema: Staff, password: { login: 'email' } } }`.
+**Fix:** `users: { staff: { schema: Staff, password: { login: 'email' } } }` — when the type should sign in with a password. To **find** a user of a type with no password, call `findByEmail(email)` instead of `findByLogin`: declaring a password only to look users up opens `signIn` and `resetPassword` on a type that has none by design.
 
 ### `authenticate()` answers `null` although a valid cookie was sent
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/janus",
-	"version": "0.20.0",
+	"version": "0.22.0",
 	"description": "Embeddable, type-safe identities and permissions: bring your own database",
 	"license": "MIT",
 	"type": "module",