@nxgt/janus 0.19.0 → 0.20.0

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.
@@ -60,6 +61,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)
@@ -582,10 +586,10 @@ const member = byId.get(row.staffId); // undefined: nobody of this type holds it
 
 ### `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 +764,78 @@ 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 id 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.
+
+```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) });
+```
+
+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 +867,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)`.
 

package/package.json

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