@nxgt/janus 0.17.2 → 0.19.0

package/docs/roadmap.md

@@ -16,9 +16,15 @@ Nothing yet.
 - **Collecting lapsed one-time tokens** — `collectExpired()` deletes lapsed
   sessions only. On a store with no TTL (PostgreSQL), lapsed tokens stay
   until you delete them, and the sign-in throttle adds one per login tried
-  per window. A port method to collect them, as sessions are, would let the
+  per window, and the mail throttle one per flow per address or user per
+  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
@@ -70,6 +76,25 @@ 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)`
+  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`,
+  `signInCode.request` and `resetPassword.request` count per address;
+  `verifyEmail.send` and an e-mailed `stepUp.request` count per user; each
+  flow on its own. Past the limit a request throws `MailThrottledError`
+  (`MAIL_THROTTLED`, 429) with `retryAfter` and issues, spends and rotates
+  nothing: the last link or code sent still works, so a loop on an address
+  cannot lock its owner out.
+  The window is no longer than the shortest default token lifetime. The counts
+  live in the tokens store, with no port change. `MailConfig` and
+  `MailThrottleConfig` are exported.
 - **A sign-in from a new device, v0.17.0** — `janus({ devices: { keys } })`,
   and `{ device }` as the last argument of `signUp`, `signIn`,
   `secondFactor.confirm`, `secondFactor.recover`, `signInCode.confirm` and
@@ -140,20 +165,6 @@ before is in the [CHANGELOG](../CHANGELOG.md).
   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 —

package/docs/troubleshooting.md

@@ -42,11 +42,16 @@ How the messages are shaped:
 - [`janus: devices.keys: …`](#janus-deviceskeys-expected-at-least-one-key---id-key--the-first-seals)
 - [`janus: events must be a function that takes a user event …`](#janus-events-must-be-a-function-that-takes-a-user-event--webhooks---from-nxgtjanus-webhooks-or-your-own)
 - [`janus: signIn.throttle …` wiring messages](#janus-signinthrottle-wiring-messages)
+- [`janus: mail.throttle …` wiring messages](#janus-mailthrottle-wiring-messages)
+- [`janus: tokens.<flow> is 5m, shorter than mail.throttle.window, 10m …`](#janus-tokensflow-is-5m-shorter-than-mailthrottlewindow-10m-)
 - [Other `janus:` wiring messages](#other-janus-wiring-messages)
 
 **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)
@@ -54,6 +59,7 @@ How the messages are shaped:
 - [`PASSWORD_TOO_SHORT` — `<call>: the password is shorter than the policy's <n> characters`](#password_too_short--call-the-password-is-shorter-than-the-policys-n-characters)
 - [`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)
 - [`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)
@@ -280,10 +286,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
@@ -465,6 +471,39 @@ zero`, and a `janus: signIn.throttle.window` that is not a duration.
 **Fix:** `signIn: { throttle: { attempts: 10, window: '15m' } }` — the
 defaults — or `signIn: { throttle: false }` to count nothing.
 
+### `janus: mail.throttle` wiring messages
+
+`TypeError`, at `janus()`: `janus: mail must be an object — { throttle }`,
+`janus: mail.throttle must be { attempts, window }, or false to count
+nothing`, `janus: mail.throttle.attempts must be a whole number above zero`,
+and a `janus: mail.throttle.window` that is not a duration.
+**Fix:** `mail: { throttle: { attempts: 5, window: '10m' } }` — the defaults —
+or `mail: { throttle: false }` to count nothing.
+
+### `janus: tokens.<flow> is 5m, shorter than mail.throttle.window, 10m …`
+
+A warning, not an error: `janus()` returns, and emits through
+`process.emitWarning` with the code `JANUS_THROTTLE_WINDOW`, once per call. The
+text, here for `tokens.signInCode: '5m'` with the default window:
+
+```
+janus: tokens.signInCode is 5m, shorter than mail.throttle.window, 10m — past the limit the last token sent can expire before the refusal ends. Set mail.throttle.window to 5m or less, or raise tokens.signInCode to 10m or more.
+```
+
+With several flows shorter than the window, one warning lists each
+(`tokens.magicLink is 2m, … ; tokens.stepUp is 30s, …`). **Why:** a request the
+mail throttle refuses spends nothing, so the last link or code sent still works,
+but only until it expires; with a lifetime shorter than the window it can lapse
+while the visitor is still refused. **Fix:** make the window no longer than the
+shortest lifetime, or raise the lifetime:
+
+```ts
+janus({ user, store, tokens: { signInCode: '5m' }, mail: { throttle: { window: '5m' } } });
+```
+
+A runtime without `process.emitWarning` stays silent. Silence it with
+`node --disable-warning=JANUS_THROTTLE_WINDOW`.
+
 ### Other `janus:` wiring messages
 
 | Message | Fix |
@@ -507,6 +546,40 @@ 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`.
@@ -641,6 +714,52 @@ if (error instanceof JanusError && error.retryAfter !== undefined) {
 janus({ ..., signIn: { throttle: { attempts: 20, window: '15m' } } });
 ```
 
+### `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`
+
+`MailThrottledError`, with `retryAfter` and `userType`. The per-user flows say
+`… too many e-mails asked for this user — the last one sent still works; use
+it, or wait for the next window` and carry `userId`.
+
+**When:** `magicLink.request`, `signInCode.request` or
+`resetPassword.request` (per address), or `verifyEmail.send` and an e-mailed
+`stepUp.request` (per user), past five requests of that flow in the current
+10-minute window — whether or not anybody holds the address. `<call>` is the
+call, such as `magicLink.request` or `patient.signInCode.request`.
+**Why:** requests that send e-mail are throttled, on by default, so a loop
+cannot fill an inbox or cancel its owner's link or code. Each flow counts on
+its own, in fixed windows of the clock, by the store. **A refused request
+spends, invalidates and rotates nothing**: no token, code or challenge is
+issued, and the last link or code sent — by anyone's request, an attacker's
+included — still confirms until it expires, so a loop on a victim's address
+cannot lock them out. Nothing locks: the next window answers again. In tests with `fixedClock`, the window never
+ends.
+**Fix:** answer 429 with a `Retry-After` header, and tell the visitor to use
+the last e-mail they received (it still works), or to wait `retryAfter`
+seconds: "Check your inbox: the last e-mail we sent still works. You can ask for
+a new one in N minutes." It reveals nothing about accounts, so it is safe to
+show.
+In tests, advance the clock past `retryAfter`, or wire `mail: { throttle:
+false }`. If nobody you know asked five times, somebody is looping on the
+route: `janus` never sees IP addresses, so limit it per client, which the
+throttle does not — with `@nxgt/redis` rate limits (`defineRateLimit`,
+`bindRateLimit`; `enforce()` throws `GuardError` `RATE_LIMITED` whose
+`retryAfter` is in milliseconds), as in the
+[e-mail flows guide](guide/email-flows.md#requests-that-send-e-mail-are-throttled).
+If you set a token lifetime shorter than the window (`tokens.signInCode: '5m'`
+with the default), the last code can expire before the window ends: keep
+`mail.throttle.window` no longer than the shortest `tokens.*` you use.
+
+```ts
+import { MailThrottledError } from '@nxgt/janus';
+
+if (error instanceof MailThrottledError) {
+	const headers = { 'retry-after': String(error.retryAfter) };
+	return Response.json({ code: error.code, retryAfter: error.retryAfter }, { status: 429, headers });
+}
+
+janus({ ..., mail: { throttle: { attempts: 10, window: '10m' } } });
+```
+
 ### `STORE_FAILED` — `<call>: the store dropped the attempts it had just stored`
 
 `StoreFailure`, with `slot: 'tokens'` and `operation: 'countAttempt'`.
@@ -1153,7 +1272,9 @@ A `TypeError`.
 
 The messages start with `signInCode.confirm` — prefixed by the type with
 several user types: `patient.signInCode.confirm: …`. `signInCode.request`
-throws nothing but `STORE_FAILED`: an e-mail it cannot sign in is `null`.
+throws nothing but `STORE_FAILED` and
+[`MAIL_THROTTLED`](#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):
+an e-mail it cannot sign in is `null`.
 `signInCode.confirm` also rejects with
 [`CODE_INVALID`](#code_invalid--call-the-code-does-not-match-or-was-already-used),
 [`TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED`](#token_unknown-token_spent-token_expired),
@@ -1236,8 +1357,9 @@ janus({
 
 `magicLink.confirm`'s messages start with `magicLink.confirm` — prefixed by
 the type with several user types: `patient.magicLink.confirm: …`.
-`magicLink.request` throws nothing but `STORE_FAILED`: an e-mail it cannot
-sign in is `null`. `magicLink.confirm` rejects with
+`magicLink.request` throws nothing but `STORE_FAILED` and
+[`MAIL_THROTTLED`](#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):
+an e-mail it cannot sign in is `null`. `magicLink.confirm` rejects with
 [`TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED`](#token_unknown-token_spent-token_expired),
 [`TOKEN_STALE`](#token_stale--call-the-token-was-sent-to-an-e-mail-the-user-no-longer-has),
 [`USER_INACTIVE`](#user_inactive--call-the-user-is-inactive) and

package/package.json

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

package/dist/auth/config/resolve-sign-in.d.ts

@@ -1,5 +0,0 @@
-/** Resolves `signIn.throttle`: on unless `false`, ten passwords per login per fifteen minutes. */
-import type { SignInConfig } from './janus-config';
-import type { ResolvedConfig } from './resolved-config';
-export declare function resolveSignInThrottle(config: SignInConfig | undefined, where: string): ResolvedConfig['signInThrottle'];
-//# sourceMappingURL=resolve-sign-in.d.ts.map

package/dist/auth/config/resolve-sign-in.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"resolve-sign-in.d.ts","sourceRoot":"","sources":["../../../src/auth/config/resolve-sign-in.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAGlG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,wBAAgB,qBAAqB,CACpC,MAAM,EAAE,YAAY,GAAG,SAAS,EAChC,KAAK,EAAE,MAAM,GACX,cAAc,CAAC,gBAAgB,CAAC,CAoBlC"}