@nxgt/janus 0.5.0 → 0.7.0

package/docs/README.md

@@ -14,6 +14,7 @@ below are defined once, in [Words](guide/vocabulary.md#words).
 | [Users](guide/users.md) | You are wiring `janus()`, declaring one or several user types, or calling `create`, `update`, `list`, `delete` |
 | [Sessions](guide/sessions.md) | You need to know who a request belongs to, set or clear the cookie, renew, sign out, or test expiry |
 | [E-mail verification and password reset](guide/email-flows.md) | You are sending a verification or reset link, and handling what comes back |
+| [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, disabling |
 | [Password hashing](guide/passwords.md) | You are choosing a hasher, raising its cost, moving to argon2id, or importing hashes from another system |
 
@@ -29,6 +30,6 @@ below are defined once, in [Words](guide/vocabulary.md#words).
 | --- | --- |
 | [The shared vocabulary](guide/vocabulary.md) | You want the words the documentation uses, or subjects and the tuple notation, ids, cursors, durations or `fixedClock` |
 | [Errors](guide/errors.md) | You are turning what the package throws into a status code, and want every code and what it carries |
-| [Writing an adapter](guide/adapters.md) | You are implementing the identity stores or the relation store for your database, upgrading one for `countAttempt` and the second factor, or running the conformance suites |
+| [Writing an adapter](guide/adapters.md) | You are implementing the identity stores or the relation store for your database, upgrading one for `countAttempt`, `spendUserTokens` and the second factor, or running the conformance suites |
 | [Troubleshooting](troubleshooting.md) | You have an error message and want its cause and its fix |
 | [Roadmap](roadmap.md) | You want to know what is coming, what shipped, and what is deliberately not planned |

package/docs/guide/adapters.md

@@ -133,6 +133,7 @@ interface TokenStore {
 	insertToken(record: TokenRecord): Promise<void>;
 	consumeToken(tokenHash: string, kind: TokenKind, at: Date): Promise<TokenRecord | null>;
 	countAttempt(tokenHash: string, kind: TokenKind): Promise<TokenRecord | null>;
+	spendUserTokens(userId: Id, kind: TokenKind, at: Date, except?: string): Promise<number>; // the unspent ones, but except
 	deleteUserTokens(userId: Id): Promise<number>;
 }
 ```
@@ -222,6 +223,50 @@ Lua script: `HINCRBY` only when `spentAt` is empty, then `HGETALL`. Wrap the
 driver's error in `StoreFailure` as in [the six rules](#the-six-rules):
 `countAttempt` has its own outage case.
 
+### `TokenStore.spendUserTokens`
+
+Spends every **unspent** token of one user and one `kind` at `at` — but the
+one whose hash is `except`, when given — and answers how many it spent. The
+core calls it right after issuing a sign-in code, with that code's hash as
+`except`, so only the last code sent works; and after writing a password,
+for the user's `secondFactor` challenges:
+
+| The stored token | Written | Counted |
+| --- | --- | --- |
+| unspent, of this user and this `kind` | `spentAt: at` | yes |
+| already spent | nothing — `spentAt` never changes once set | no |
+| another `kind`, another user, or the one named by `except` | nothing | no |
+| none at all | nothing | `0`, an absence — never a failure |
+
+Each token is spent by a **conditional write**, as `consumeToken` spends one:
+a token that a racing `consumeToken` spends at the same moment is counted by
+exactly one of the two calls, never both. An expired token is spent all the
+same, or not counted by a store that already dropped it.
+
+In MongoDB, one `updateMany` through the `userId` index `deleteUserTokens`
+already reads:
+
+```ts
+import type { TokenStore } from '@nxgt/janus';
+
+export const spendUserTokens: TokenStore['spendUserTokens'] = async (userId, kind, at, except) => {
+	const result = await tokens.updateMany(
+		{ userId, kind, spentAt: null, ...(except === undefined ? {} : { _id: { $ne: except } }) },
+		{ $set: { spentAt: at } },
+	);
+	return result.modifiedCount;
+};
+```
+
+In SQL, `update … set spent_at = $3 where user_id = $1 and kind = $2 and
+spent_at is null returning token_hash`, with `and token_hash <> $4` added
+only when `except` is given — bound to `NULL`, `<>` matches no row — answering the row count: PostgreSQL
+re-checks `spent_at is null` on a row a racing redemption just committed. In
+Redis, one Lua script over the user's set of tokens, `HSET spentAt` on each
+of the right `kind` whose `spentAt` is empty, skipping the one named by
+`except`. `spendUserTokens` has its own
+outage case.
+
 ### `RelationStore`
 
 ```ts
@@ -257,7 +302,11 @@ Written on the port's types, and checked by the suites:
    normalises logins before a store sees them, and never hands a store
    `\u0000` or a lone surrogate; every other character comes back as written.
 5. **Every method is atomic on its own.** The core opens no transaction; an
-   adapter may open one inside a method.
+   adapter may open one inside a method. And **a read sees every write that
+   completed before it** — never a secondary or a read replica: a sign-in
+   re-reads the user to see a password written while it ran, and a new
+   sign-in code spends the ones issued before it. No suite can check this
+   one; a `readPreference: 'secondaryPreferred'` breaks it silently.
 6. **Schema management is not on the port.** Expose your own `sync`; the core
    never calls it.
 
@@ -298,7 +347,7 @@ compile error naming the missing method.
 
 | Suite | Cases | Harness opens |
 | --- | --- | --- |
-| `describeJanusStores({ name, harness, runner?, faults?, skip? })` | 45: users, sessions, tokens, and one outage per method whose honest answer can be "nothing" — twelve of them | `{ stores, faults?, close? }` |
+| `describeJanusStores({ name, harness, runner?, faults?, skip? })` | 49: users, sessions, tokens, and one outage per method whose honest answer can be "nothing" — thirteen of them | `{ stores, faults?, close? }` |
 | `describeRelationStores({ name, harness, runner?, faults?, skip? })` | 15: the relation store, and one outage per method | `{ store, faults?, close? }` |
 
 `harness.open()` is called **once per case** and must answer fresh, empty
@@ -315,7 +364,7 @@ stores: a case that leaks into the next is the hardest failure to debug.
 
 The suites import no test framework and no assertion library.
 
-The second factor and attempts have their own cases — skip one by its id
+The second factor, attempts and a user's tokens spent have their own cases — skip one by its id
 while you work on it, never to ship:
 
 | Case | Checks |
@@ -327,6 +376,10 @@ while you work on it, never to ship:
 | `tokens.challenge` | a second-factor challenge, whose `address` is `''`, kept, counted and spent like any token |
 | `tokens.countAttemptSpent` | a spent token answered unchanged; another kind and an unknown hash answer `null` and count nothing |
 | `outage.countAttempt` | a store that cannot answer rejects, never `null` |
+| `tokens.spendUserTokens` | spends the unspent tokens of one user and kind at `at`, keeping their attempts, and counts them; a spent token keeps its `spentAt`; another kind and another user are untouched; `0` for none |
+| `tokens.spendUserTokensExcept` | spares the token named by `except`, and spends the user's others of that kind |
+| `tokens.spendUserTokensRace` | racing one `consumeToken`, ten times over: exactly one of the two spends the token |
+| `outage.spendUserTokens` | a store that cannot answer rejects, never `0` |
 
 ### `faults`: prove the outage invariant
 

package/docs/guide/email-flows.md

@@ -51,6 +51,9 @@ clinic.patient.verifyEmail.send; // exists: `email` names the field
 clinic.staff.verifyEmail;
 ```
 
+A type with an e-mail can also sign in with a code sent to it, with or
+without a password — see [sign-in codes](sign-in-code.md).
+
 ## Options
 
 | Option | Type | Default | Effect |
@@ -71,6 +74,9 @@ readonly verifyEmail: {
 `send` issues a token for the user's **current** e-mail. `confirm` redeems it
 and sets `emailVerified`. A token sent to an e-mail the user has since changed
 is `TOKEN_STALE`: confirming it would verify an address nobody holds any more.
+The address is checked again on the very record the write replaces, so an
+e-mail changed while the link is being redeemed is `TOKEN_STALE` too, and
+nothing is written.
 Changing the e-mail with `update` sets `emailVerified` back to `false`.
 
 ## `resetPassword`
@@ -97,7 +103,10 @@ export async function forgotPassword(request: Request): Promise<Response> {
 ```
 
 `confirm` sets the password, marks the e-mail verified — the link proved it —
-and **signs the user out everywhere**. It opens no session: call `signIn` next
+and **signs the user out everywhere**: their sessions are revoked, and every
+second-factor challenge still open is spent, so a sign-in started with the
+old password cannot be finished. The e-mail is checked again on the record
+written, as for `verifyEmail`. It opens no session: call `signIn` next
 if that is your policy. A password refused for its length does not spend the
 token, so the visitor can try again with the same link.
 
@@ -142,5 +151,6 @@ never the token, and no refusal's message contains it.
 ## See also
 
 - [Users](users.md) — `email`, `update`, and the other per-type methods
+- [Sign-in codes](sign-in-code.md) — the third flow that sends an e-mail: a code, not a link
 - [Sessions](sessions.md) — `signOutEverywhere`, which `resetPassword.confirm` calls for you
 - [Errors](errors.md) — every code, and the status it deserves

package/docs/guide/errors.md

@@ -83,9 +83,9 @@ that wired the library, so no handler needs to tell it apart.
 | `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** | `reason`, for your logs only |
 | `HASH_UNSUPPORTED` | `CredentialError` | 400 | A stored hash no wired hasher reads | `hashPrefix` — never the hash |
-| `USER_INACTIVE` | `UserInactiveError` | 403 | Deactivated; told only to someone who gave the right password | `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 | |
-| `CODE_INVALID` | `TokenError` | 401 | A second factor's code that does not match, or was already accepted — see [the second factor](second-factor.md#confirming-the-code-at-sign-in) | `attemptsLeft` from `confirm`: what the challenge has left, `0` once it is spent. None from `activate` |
+| `USER_INACTIVE` | `UserInactiveError` | 403 | Deactivated; told only to someone who gave the right password, or the right code | `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) | `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) — or a sign-in code sent by e-mail — see [sign-in codes](sign-in-code.md#attempts) | `attemptsLeft` from either `confirm`: what the challenge has left, `0` once it is spent. None from `activate`. `userId` |
 | `SECOND_FACTOR_NOT_ENROLLED` | `SecondFactorError` | 409 | `activate` before `enroll`, or `confirm` after the factor was disabled | `userId` |
 | `SECOND_FACTOR_ACTIVE` | `SecondFactorError` | 409 | `enroll` or `activate` on a factor already active: `disable` it first | `userId` |
 | `INVALID_CURSOR` | `InvalidCursorError` | 400 | A cursor this store did not mint. Never a silent first page | |

package/docs/guide/second-factor.md

@@ -203,11 +203,13 @@ interface SecondFactorRequired {
 	readonly status: 'secondFactor';
 	readonly challenge: string; // a secret, like a session token
 	readonly expiresAt: Date;   // five minutes from now, by default
+	readonly userId: Id;        // for your logs and rate limits — not for the visitor
 }
 ```
 
-A user whose factor is active gets **no session from their password**: they
-get a **challenge**, which `secondFactor.confirm` redeems with a code. Anyone
+A user whose factor is active gets **no session from their password** — nor
+from a [code sent by e-mail](sign-in-code.md#a-second-factor-is-still-asked-for),
+whose `confirm` answers the same union: they get a **challenge**, which `secondFactor.confirm` redeems with a code. Anyone
 else gets a session, as before. `signIn`'s refusals — `CREDENTIALS_INVALID`,
 `USER_INACTIVE` — are unchanged, and come before any challenge: a wrong
 password never tells anyone that a second factor exists.
@@ -260,8 +262,8 @@ const signedIn = await auth.secondFactor.confirm(challenge, code);
 | Rejects with | When | What to do |
 | --- | --- | --- |
 | `CODE_INVALID`, with `attemptsLeft` | the code does not match, is not six digits, or was already accepted | ask again while `attemptsLeft > 0`; at `0` the challenge is spent: sign in again |
-| `TOKEN_UNKNOWN` | no such challenge — a typo, another user type's, or one a store's TTL already dropped | sign in again |
-| `TOKEN_SPENT` | the challenge already opened a session, or its attempts ran out | sign in again |
+| `TOKEN_UNKNOWN` | no such challenge — a typo, another user type's, or one a store's TTL already dropped. Another type's challenge still loses one of its attempts, and its fifth spends it | sign in again |
+| `TOKEN_SPENT` | the challenge already opened a session, its attempts ran out, or a password reset spent it | sign in again |
 | `TOKEN_EXPIRED` | `expiresAt` has passed | sign in again |
 | `USER_INACTIVE` | the user was deactivated since `signIn`. The challenge is spent | answer 403, as `signIn` would |
 | `SECOND_FACTOR_NOT_ENROLLED` | the factor was disabled since `signIn`. The challenge is spent | sign in again: the password alone now opens a session |
@@ -291,6 +293,30 @@ Five attempts at a million values is a one-in-200,000 chance per password
 guessed right. A new challenge takes a new sign-in, with the password, so the
 attempts are bounded by your sign-in rate limit too.
 
+A call made through **another user type's** API — `auth.staff.secondFactor.confirm`
+for a patient's challenge — answers `TOKEN_UNKNOWN` and compares nothing, but
+its attempt counts all the same: the fifth spends the challenge, as a wrong
+code would.
+
+**Writing a password ends the sign-ins left waiting.** `resetPassword.confirm`,
+`setPassword` and `changePassword` spend every challenge of the user still
+open, so whoever had the old password cannot finish a sign-in they started
+with it:
+
+```ts
+const result = await auth.signIn({ email, password: oldPassword }); // a challenge
+await auth.resetPassword.confirm(resetToken, newPassword);
+await auth.secondFactor.confirm(result.challenge, code); // TOKEN_SPENT
+```
+
+A sign-in still running when the password is written is refused too.
+`signIn` reads the user again once it answered: if the password it verified
+is no longer theirs, it spends its own challenge — or revokes the session it
+opened — and throws `CREDENTIALS_INVALID`. The writer spends after writing,
+the sign-in reads after issuing, so however the two interleave one of them
+sees the other. A hash rewritten for the same password — another sign-in
+rehashing it — is not a change.
+
 ### Lifetime
 
 A challenge lives `'5m'` unless `secondFactor.challenge` says otherwise, and
@@ -562,6 +588,7 @@ with `STORE_FAILED`.
 
 ## See also
 
+- [Sign-in codes](sign-in-code.md) — a sign-in by e-mailed code, which still asks for an active factor, with the same challenge
 - [Sessions](sessions.md) — the cookie `confirm`'s session is sent in, and `authenticatedAt`
 - [Errors](errors.md) — `CODE_INVALID`, `SECOND_FACTOR_NOT_ENROLLED`, `SECOND_FACTOR_ACTIVE` and their statuses
 - [Writing an adapter](adapters.md#a-users-password-and-second-factor) — what a store keeps of a factor