@nxgt/janus 0.19.0 → 0.21.0

package/docs/roadmap.md

@@ -76,7 +76,30 @@ 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)`
+- **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
+  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
@@ -143,35 +166,3 @@ before is in the [CHANGELOG](../CHANGELOG.md).
   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.
-- **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.

package/docs/troubleshooting.md

@@ -9,8 +9,9 @@ How the messages are shaped:
   `resetPassword.confirm: …`, `can: …`. With several user types, that call is
   prefixed by the type: `staff.signIn: …`. Below, `<call>` stands for it.
 - **A `TypeError` is a wiring mistake**: it comes from how the application was
-  put together — a configuration, a store, a model — and never from a request.
-  Fix the code; no handler should answer one.
+  put together — a configuration, a store, a model, a prepared request sent
+  twice — and never from a request. Fix the code; no handler should answer
+  one.
 - **A `JanusError` is a refusal at call time**, on a value that could have come
   from a request. It carries a `code` you can `switch` on; the heading of each
   entry below names it.
@@ -52,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)
@@ -60,6 +62,9 @@ How the messages are shaped:
 - [`CREDENTIALS_INVALID` — `<call>: the login and the password do not match`](#credentials_invalid--call-the-login-and-the-password-do-not-match)
 - [`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)
+- [`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)
 - [`HASH_UNSUPPORTED` — `<call>: no wired verifier claims the prefix "<prefix>"`](#hash_unsupported--call-no-wired-verifier-claims-the-prefix-prefix)
 - [`scryptHasher: the stored hash has the $scrypt$ prefix and not its format`](#scrypthasher-the-stored-hash-has-the-scrypt-prefix-and-not-its-format)
@@ -580,12 +585,25 @@ 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`, `verifyEmail.send`, `secondFactor.recoveryCodesLeft`. Also `<call>: the user has no e-mail`.
+`NotFoundError`, from `get`, `getUser`, `update`, `setActive`, `setPassword`, `signInProven`, `verifyEmail.send`, `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.
+**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.
 **Fix:** answer 404, or use `find` when absence is an ordinary outcome:
 
 ```ts
@@ -760,6 +778,82 @@ if (error instanceof MailThrottledError) {
 janus({ ..., mail: { throttle: { attempts: 10, window: '10m' } } });
 ```
 
+### Accepting an invitation answers `MAIL_THROTTLED`
+
+**When:** the application signs an invitee in by calling
+`magicLink.request(email)` and confirming the token at once, and somebody
+asked for links to that address five times in the window — the default mail
+throttle. The acceptance answers 429, and the message says the last link
+sent still works, though the invitee was sent none.
+**Why:** `request` is counted per address, whoever asks: that is what stops a
+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 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. 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 user = await auth.findByEmail(invitation.email); // or invitation.userId, when you stored the id
+if (user === null) return new Response(null, { status: 404 });
+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).
+
+### `MAIL_THROTTLED` never reaches the visitor: `request` runs in the background
+
+**When:** the application runs `magicLink.request`, `signInCode.request` or
+`resetPassword.request` off the visitor's request — a queue, a promise it
+does not await — so that the time of the answer does not tell whether the
+address has an account. Past the limit, the refusal is thrown there, and
+nobody tells the visitor to use the last e-mail they received.
+**Why:** `request` counts, then looks the address up and issues: its
+`MAIL_THROTTLED` comes from the same call whose time must be hidden.
+**Fix:** call `prepare(email)` in the visitor's request — validated and
+counted, nobody looked up, the same store calls for any address — and
+answer its `MAIL_THROTTLED` with 429; call `send()` on what it answered in the
+background. `send()` counts nothing and answers what `request` would have.
+
+```ts
+const pending = await auth.magicLink.prepare(email); // MAIL_THROTTLED here, in the visitor's request
+void pending.send().then(mailIt).catch(reportError); // looked up and issued off it
+return new Response(null, { status: 202 });
+```
+
+See [requests in two steps](guide/email-flows.md#requests-in-two-steps).
+
+### `<flow>.prepare(…).send: already called — a prepared request sends once; call <flow>.prepare again for another`
+
+A `TypeError`, such as `magicLink.prepare(…).send: already called — a
+prepared request sends once; call magicLink.prepare again for another`, or
+`patient.signInCode.prepare(…)…` with several user types.
+**When:** `send()` was called a second time on what one `prepare` answered —
+after it issued, after it answered `null`, after it threw (`STORE_FAILED`),
+or while the first call was still running.
+**Why:** `prepare` counted one request against the mail throttle, and that
+count pays for one issue. A `send()` that could run again would issue
+uncounted, so a loop could mail an address past the limit; nothing a caller
+passes skips the count. It is a bug in the calling code, never a value from
+a request, so it is a `TypeError` with no `code`.
+**Fix:** call `send()` once per `prepare`. To retry — after a failure, in a
+queue that retries — `prepare` again, which counts again (and, for a sign-in
+code, mints another challenge: give the visitor the new one):
+
+```ts
+async function sendLink(email: string): Promise<void> {
+	const pending = await auth.magicLink.prepare(email); // one count…
+	const issued = await pending.send();                 // …one issue
+	if (issued !== null) await mailer.send(issued.email, linkTo(issued.token));
+}
+// a retry calls sendLink again: never pending.send() twice
+```
+
 ### `STORE_FAILED` — `<call>: the store dropped the attempts it had just stored`
 
 `StoreFailure`, with `slot: 'tokens'` and `operation: 'countAttempt'`.
@@ -791,7 +885,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.
+**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.
 **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)`.
 
@@ -930,7 +1024,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.19.0",
+	"version": "0.21.0",
 	"description": "Embeddable, type-safe identities and permissions: bring your own database",
 	"license": "MIT",
 	"type": "module",