@nxgt/janus 0.18.0 → 0.20.0

package/docs/guide/users.md

@@ -180,11 +180,13 @@ In the one-type form these are on `auth` itself; with several types, on
 | --- | --- | --- |
 | `create(fields & { password?, active? })` | the user; no session | `USER_INVALID`, `PASSWORD_TOO_SHORT`, `LOGIN_TAKEN` |
 | `find(id)` | the user, or `null` — for a malformed id, an unknown one, or one of another type | |
+| `findMany(ids)` | the users, in the order of `ids`, each once; an id `find` answers `null` for is left out — see [below](#several-users-at-once--findmany) | |
 | `get(id)` | the user | `NOT_FOUND` |
 | `list({ after?, limit? })` | `CursorPage<User>`, in creation order | `INVALID_CURSOR` |
 | `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:
 
@@ -249,6 +251,53 @@ idempotent: calling it again finishes the job. When it deleted the user, it
 sends a [`user.deleted` event](events.md) — once, after the sessions, tokens and relation tuples are gone, and even when an outage interrupts removing them;
 `create` and `signUp` send `user.created`.
 
+### Several users at once — `findMany`
+
+A list of rows that each name a user — a staff list showing every member's
+account state — reads them in one call, not one `find` per row:
+
+```ts
+const rows = await db.staffRows();                       // your own table, 100 rows
+const members = await clinic.staff.findMany(rows.map((row) => row.staffId));
+const byId = new Map(members.map((member) => [member.id, member]));
+
+const shown = rows.map((row) => {
+	const member = byId.get(row.staffId);                // undefined: nobody holds this id
+	return { ...row, active: member?.active ?? false, verified: member?.emailVerified ?? false };
+});
+```
+
+- **Order**: the order of `ids`. A repeated id is answered once, at its first
+  place.
+- **Absence**: an id `find` would answer `null` for — malformed, unknown, or
+  held by a user of another type — is **left out**, never an error. The answer
+  may be shorter than `ids`, so match by `user.id`, never by position.
+- **Empty**: `[]`, or a list with no well-formed id, answers `[]` without
+  reaching the store.
+- **Size**: any length. The store is asked 100 ids at a time, one batch after
+  another, so no query grows with your list.
+- **Failure**: `STORE_FAILED`, never a shorter list. Something other than an
+  array is a bare `TypeError`: only your code passes one.
+- **Cost**: one query per 100 ids when the users store implements the
+  optional `findUsers` — the reference store, `@nxgt/janus-drizzle` and
+  `@nxgt/janus-mongo` do. A store that does not is read with `findUser`,
+  **ten at a time**, so a third-party adapter keeps working and never opens
+  more than ten reads at once for one call; see
+  [writing an adapter](adapters.md#userstorefindusers-optional).
+
+**A GraphQL resolver per row** can batch through a DataLoader of your own —
+`@nxgt/janus-graphql` loads no users itself:
+
+```ts
+import DataLoader from 'dataloader';
+
+// One per request, so nothing is cached across users' requests.
+const staffById = new DataLoader(async (ids: readonly string[]) => {
+	const found = new Map((await clinic.staff.findMany(ids)).map((u) => [u.id, u]));
+	return ids.map((id) => found.get(id) ?? null);
+});
+```
+
 ### Paging every user
 
 ```ts

package/docs/roadmap.md

@@ -20,6 +20,11 @@ Nothing yet.
   window. A port method to collect them, as sessions are, would let the
   core do it.
 
+- **A batch read across types** — `findMany` reads one user type, as `find`
+  does. The shared `findUser(id)` has no batch counterpart yet; one on the
+  instance, answering a union narrowed by `user.type`, would serve a list that
+  mixes types.
+
 - **More official adapters** — the ports are cut where atomicity is not
   required, so users, sessions and permission tuples can each live in the
   database that suits them. MongoDB is the first adapter
@@ -71,6 +76,29 @@ Nothing yet.
 The last ten, newest first, each with the version it came in. Everything
 before is in the [CHANGELOG](../CHANGELOG.md).
 
+- **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
+  optional `findUsers`, implemented by the reference store,
+  `@nxgt/janus-drizzle` 0.7.0 and `@nxgt/janus-mongo` 0.8.0; a store without it
+  is read with `findUser`, ten at a time, so third-party adapters keep working.
 - **Requests that send e-mail are throttled, v0.18.0** —
   `janus({ mail: { throttle: { attempts, window } } })`, five per ten
   minutes by default and `false` to turn it off. `magicLink.request`,
@@ -138,42 +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.
-- **Recovery codes, v0.10.0** — a user who loses their authenticator app
-  still signs in, with no operator resetting the account.
-  `secondFactor.activate` answers `{ user, recoveryCodes }`: ten single-use
-  codes, shown once and stored only as keyed hashes (breaking: read `.user`).
-  `secondFactor.recover(challenge, code)` redeems a sign-in's challenge with
-  one and answers the session with `recoveryCodesLeft`;
-  `secondFactor.regenerateRecoveryCodes(user, code)` replaces them all on a
-  fresh code from the app, and counts its attempts itself — five per user
-  per 15-minute window, in the store — so a stolen session cannot guess the
-  code, and the route needs no limiter of its own. Two user events,
-  `user.recoveryCodesRegenerated` and `user.recoveryCodeUsed`. For adapters:
-  `SecondFactorRecord.recoveryCodes`,
-  stored by the users stores of `@nxgt/janus-drizzle` and
-  `@nxgt/janus-mongo`, with conformance cases.
-- **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.
@@ -49,6 +50,9 @@ How the messages are shaped:
 **Users, sessions and tokens**
 - [`STORE_FAILED` — `<slot>.<method>: the store could not answer`](#store_failed--slotmethod-the-store-could-not-answer)
 - [`STORE_FAILED` — `<slot>.<method> answered undefined …`](#store_failed--slotmethod-answered-undefined-an-absence-is-null-so-this-store-forgot-to-answer)
+- [`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)
 - [`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)
@@ -57,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)
@@ -283,10 +290,10 @@ janus({ ..., hasher: scryptHasher(), verifiers: [legacyBcrypt] }); // not [scryp
 
 ### `janus: store.<slot> has no method <method>, which the port requires`
 
-Also: `janus: store.<slot> is missing`, `janus: store must be an object with users, sessions and tokens`, `janus: store.sessions.deleteExpiredSessions must be a function or absent`.
+Also: `janus: store.<slot> is missing`, `janus: store must be an object with users, sessions and tokens`, `janus: store.sessions.deleteExpiredSessions must be a function or absent`, `janus: store.users.findUsers must be a function or absent`.
 
 **When:** `janus({...})`, from JavaScript or with a store typed loosely. TypeScript refuses a partial store at compile time and names the method.
-**Why:** `store` is `{ users, sessions, tokens }`, and each slot must answer every method of the port. `deleteExpiredSessions` is the one optional method: absent, or a function.
+**Why:** `store` is `{ users, sessions, tokens }`, and each slot must answer every method of the port. Two methods are optional — `sessions.deleteExpiredSessions` and `users.findUsers` — and each is absent, or a function: a value in its place (`findUsers: true`, a property copied from a config) is a wiring mistake, not an absent capability.
 An adapter written for an earlier `@nxgt/janus` reports the method a later
 release added to the port: `store.tokens has no method countAttempt` for one
 written against 0.3 (the method came in 0.4), and
@@ -543,12 +550,46 @@ try {
 **Why:** a method that can find nothing must answer `null`. `undefined` is also what a missing `return` produces, so it is treated as a bug in the store, not as "not found".
 **Fix:** `return doc ?? null;` — and run `@nxgt/janus/conformance` against the store.
 
+### `STORE_FAILED` — `users.findUsers answered no list: an absence is a shorter list, so this store forgot to answer`
+
+**When:** `findMany`, over a users store you wrote that implements the optional `findUsers`.
+**Why:** `findUsers` answered `null`, `undefined` or something else than an array. An id nobody holds is left out of the list, and nobody at all is `[]`; anything else is a store that forgot to answer, so it fails rather than read as "nobody".
+**Fix:** answer the rows you found, mapped to records — or leave `findUsers` out, and `findMany` reads with `findUser`:
+
+```ts
+findUsers: async (ids) => (await db.users.where('id', 'in', ids)).map(toUser), // [] when none
+```
+
+### `<call>: ids must be an array of user ids`
+
+A bare `TypeError` — `findMany: …`, or `staff.findMany: …` with several user types.
+
+**When:** `findMany` was given something other than an array: one id, a `Set`, a comma-separated string.
+**Why:** `findMany` takes a list; one id is `find`. Only your code passes the wrong shape, and TypeScript refuses it.
+**Fix:** pass an array, or use `find` for one id:
+
+```ts
+await auth.staff.findMany([...selectedIds]); // from a Set
+await auth.staff.find(id);                   // one id
+```
+
+### `findMany` answers fewer users than ids
+
+**When:** always, when an id is malformed, unknown, held by a user of another type, or repeated.
+**Why:** `findMany` leaves out what `find` answers `null` for, and answers a repeated id once — it never puts `null` in a place. Reading `users[i]` as the user of `ids[i]` then shows one row's account on another.
+**Fix:** match by id:
+
+```ts
+const byId = new Map((await auth.staff.findMany(ids)).map((user) => [user.id, user]));
+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
@@ -723,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'`.
@@ -754,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.18.0",
+	"version": "0.20.0",
 	"description": "Embeddable, type-safe identities and permissions: bring your own database",
 	"license": "MIT",
 	"type": "module",