@nxgt/janus 0.6.0 → 0.7.0

package/docs/README.md

@@ -30,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

@@ -74,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`
@@ -100,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.
 

package/docs/guide/second-factor.md

@@ -203,6 +203,7 @@ 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
 }
 ```
 
@@ -261,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 |
@@ -292,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

package/docs/guide/sign-in-code.md

@@ -181,10 +181,10 @@ hash, like a session token, so the store cannot give it back either.
 
 A challenge belongs to the user type that issued it: confirm a patient's
 challenge with `clinic.patient.signInCode.confirm`. Another type's `confirm`
-answers `TOKEN_UNKNOWN`, compares no code and spends nothing — but it has
-already cost one of the challenge's five attempts, because the attempt is
-counted before the type is known. The challenge is left for its own type,
-with one attempt fewer.
+answers `TOKEN_UNKNOWN` and compares no code — but it has already cost one of
+the challenge's five attempts, because the attempt is counted before the type
+is known. The challenge is left for its own type, with one attempt fewer, and
+the fifth such call spends it, as a fifth wrong code would.
 
 ## Confirming the code
 
@@ -221,8 +221,26 @@ try {
 Five attempts at a million values is a one-in-200,000 chance per challenge.
 Codes sent at once past the fifth attempt are all refused, the right one
 included: the store counts, and nothing reads the count before writing it.
-A new challenge takes a new `request` and a new e-mail — which is why that
-route is the one to rate-limit.
+
+**At most one code is live per user.** A `request` issues its code, then
+spends every other challenge of the user, so the code in an earlier e-mail
+answers `TOKEN_SPENT` — only the last one works:
+
+```ts
+const first = await auth.signInCode.request(email);
+const second = await auth.signInCode.request(email); // the visitor asked again
+await auth.signInCode.confirm(first.challenge, first.code);   // TOKEN_SPENT
+await auth.signInCode.confirm(second.challenge, second.code); // signed in
+```
+
+Requests that arrive at once cannot each keep a code: each spends the others'
+once it issued its own, so at most one survives — sometimes none, and the
+visitor asks again. Guesses therefore never run against two live challenges.
+
+**Rate-limit `request` per address.** A new challenge takes only a new
+`request`, and each one sends an e-mail and cancels the code before it:
+without a limit, anyone who knows an address can fill its inbox, or keep
+its owner from ever typing a code in time.
 
 ### Lifetime
 
@@ -270,8 +288,8 @@ answers `SignedIn`.
 | Rejects with | When | What to do |
 | --- | --- | --- |
 | `CODE_INVALID`, with `attemptsLeft` | the code does not match, or is not six digits. Message: `signInCode.confirm: the code does not match, or was already used` | ask again while `attemptsLeft > 0`; at `0` the challenge is spent: request a new code |
-| `TOKEN_UNKNOWN` | no such challenge — a typo, another user type's, one whose user was deleted, or one a store's TTL already dropped. Another type's challenge still loses one of its attempts | request a new code |
-| `TOKEN_SPENT` | the challenge already signed someone in, or its attempts ran out | request a new code |
+| `TOKEN_UNKNOWN` | no such challenge — a typo, another user type's, one whose user was deleted, or one a store's TTL already dropped. Another type's challenge still loses one of its attempts, and its fifth spends it | request a new code |
+| `TOKEN_SPENT` | the challenge already signed someone in, its attempts ran out, or a newer `request` for the same user spent it — only the last code sent works | request a new code, and use the latest e-mail |
 | `TOKEN_EXPIRED` | `expiresAt` has passed | request a new code |
 | `TOKEN_STALE` | the user changed their e-mail since the code was sent. Message: `signInCode.confirm: the code was sent to an e-mail the user no longer has`. The challenge is spent | request a new code, to the current address |
 | `USER_INACTIVE` | the user was deactivated since the code was sent. The challenge is spent | answer 403 |

package/docs/guide/users.md

@@ -185,10 +185,10 @@ With a `password`, besides:
 | Method | Answers | Rejects with |
 | --- | --- | --- |
 | `signUp(fields & { password })` | `{ status: 'signedIn', user, session, token }` | `USER_INVALID`, `PASSWORD_TOO_SHORT`, `LOGIN_TAKEN` |
-| `signIn({ [login]: string, password })` | `{ status: 'signedIn', user, session, token }` — or, with `secondFactor` configured and the user's factor active, `{ status: 'secondFactor', challenge, expiresAt }`: switch on `status` | `CREDENTIALS_INVALID`, `USER_INACTIVE`, `HASH_UNSUPPORTED` |
+| `signIn({ [login]: string, password })` | `{ status: 'signedIn', user, session, token }` — or, with `secondFactor` configured and the user's factor active, `{ status: 'secondFactor', challenge, expiresAt, userId }`: switch on `status` | `CREDENTIALS_INVALID`, `USER_INACTIVE`, `HASH_UNSUPPORTED` |
 | `findByLogin(login)` | the user, or `null`; the login is normalised first, and one holding a NUL or a lone surrogate is nobody's | |
-| `setPassword(user, password, { ifVersion? })` | the user — an admin's call | `PASSWORD_TOO_SHORT` |
-| `changePassword(user, { current, next }, { ifVersion? })` | the user — the user's own call | `CREDENTIALS_INVALID`, `PASSWORD_TOO_SHORT` |
+| `setPassword(user, password, { ifVersion? })` | the user — an admin's call; spends the user's second-factor challenges still waiting, and signs nobody out | `PASSWORD_TOO_SHORT` |
+| `changePassword(user, { current, next }, { ifVersion? })` | the user — the user's own call; spends the user's second-factor challenges still waiting | `CREDENTIALS_INVALID`, `PASSWORD_TOO_SHORT` |
 
 With `secondFactor` configured, a type with a password also answers
 `secondFactor.enroll`, `activate`, `disable` and `confirm` — see

package/docs/guide/vocabulary.md

@@ -51,6 +51,7 @@ either finds this row.
 | **second factor** | What a user proves at sign-in beyond their password: a TOTP secret their authenticator app holds, `UserRecord.secondFactor`. **Enrolled** once `enroll` stored it, waiting for a first code (`confirmedAt: null`); **active** once `activate` accepted one — `hasSecondFactor`, and only then does `signIn` ask for a code | "2FA", "MFA", "OTP device"; "confirmed" for the state — to *confirm* is to redeem a challenge |
 | **attempt** | One code tried against a challenge, counted by `countAttempt` in the token's `attempts` before the code is checked. A challenge takes five, a second factor's or a sign-in code's | "try"; "retry" is a repeated write, never a guess |
 | **challenge** | A secret the visitor keeps, redeemed once with a code — which is what *confirm* means for it. `signIn` answers one instead of a session when the user's second factor is active, for `secondFactor.confirm`; `signInCode.request` answers one beside the sign-in code, for `signInCode.confirm`. Stored as its hash, as a one-time token of kind `secondFactor` or `signInCode`: five minutes or ten by default, and five attempts | "MFA token", "pending session", "ticket" |
+| **spent** | A one-time token or a challenge that can no longer be redeemed — `spentAt` set, `TOKEN_SPENT`, and never unset. Spent by its redemption, by its fifth attempt (a wrong code, or a call through another user type's API), by a redemption after it expired, by a refusal that ends it (`USER_INACTIVE`, `TOKEN_STALE`, `SECOND_FACTOR_NOT_ENROLLED`), or by what ends it early: the next `signInCode.request` for the same user (at most one sign-in code is live at a time), or a password written by `resetPassword.confirm`, `setPassword` or `changePassword` (every second-factor challenge left waiting) | "used up", "invalidated"; "consumed" only in `consumeToken`'s name; "revoked" is a session's |
 | **step** | The thirty-second period a TOTP code belongs to. `lastStep` is the step of the last code accepted, and only a later step counts: that is why a code is accepted once | "window", "period", "counter", in prose |
 | **seal**, **sealing key** | To seal is to encrypt a TOTP secret — AES-256-GCM, bound to the user's id — before a store sees it. A sealing key is one `{ id, key }` of `secondFactor.keys`: the first seals, every one opens | "encrypt", "encryption key", "master key", "pepper" |
 | **token** | Never alone in prose: a *session token* or a *one-time token*. The `tokens` store and the `TOKEN_*` codes are one-time tokens only | |

package/docs/roadmap.md

@@ -93,6 +93,18 @@ Nothing between releases.
 The last ten, newest first, each with the version it came in. Everything
 before is in the [CHANGELOG](../CHANGELOG.md).
 
+- **At most one sign-in code live per user, and challenges that end when
+  they should, v0.7.0** — `signInCode.request` spends the codes sent before,
+  even when requests race, so only the last e-mail's works; writing a
+  password spends the second-factor challenges left waiting, and a sign-in
+  still running when it lands is refused; another user type's `confirm` spends a challenge
+  at its fifth attempt; `verifyEmail.confirm` and `resetPassword.confirm`
+  check the e-mail again on the record they write. `SecondFactorRequired`
+  carries `userId`, for logs and rate limits. For adapters:
+  `TokenStore.spendUserTokens(userId, kind, at, except?)`, with four new conformance
+  cases, implemented in `@nxgt/janus-drizzle`, `@nxgt/janus-mongo` and
+  `@nxgt/janus-redis` — and the port now says a read sees every write that
+  completed before it: never a secondary or a read replica.
 - **Sign in with a code sent by e-mail, v0.6.0** —
   `auth.<type>.signInCode.request(email)` answers a six-digit code to send
   and a challenge to keep with the visitor, or `null` for nobody — never
@@ -149,7 +161,3 @@ before is in the [CHANGELOG](../CHANGELOG.md).
 - **The conformance suite accepts a store with its own expiry** — a store
   that drops a lapsed session at once, as a Redis TTL does, passes
   `sessions.deleteUser`; one that still holds it must count it. — v0.2.0
-- **A Hono integration** — [`@nxgt/janus-hono`](https://www.npmjs.com/package/@nxgt/janus-hono):
-  the session middleware, the cookie, a route guarded by a permission,
-  `bindJanus()` to bind the instances once, and every error as its status.
-  Its own 0.1.0, beside `@nxgt/janus` 0.1.3.

package/docs/troubleshooting.md

@@ -232,9 +232,11 @@ Also: `janus: store.<slot> is missing`, `janus: store must be an object with use
 
 **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.
-An adapter written against `@nxgt/janus` 0.3 reports
-`store.tokens has no method countAttempt` until it implements the method 0.4
-added.
+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
+`store.tokens has no method spendUserTokens` for one written against 0.6 (the
+method came in 0.7).
 
 **Fix:** pass the three stores, whole:
 
@@ -244,17 +246,17 @@ import { createMemoryStores, janus } from '@nxgt/janus';
 janus({ ..., store: createMemoryStores() });
 ```
 
-For `countAttempt`, upgrade the published adapter to the release that
-implements it — `@nxgt/janus-drizzle` 0.2, `@nxgt/janus-mongo` 0.3,
-`@nxgt/janus-redis` 0.2:
+Upgrade the published adapter to the release that implements both —
+`@nxgt/janus-drizzle` 0.3, `@nxgt/janus-mongo` 0.4, `@nxgt/janus-redis` 0.3:
 
 ```bash
-bun add @nxgt/janus@^0.4 @nxgt/janus-drizzle@^0.2 # or @nxgt/janus-mongo@^0.3, @nxgt/janus-redis@^0.2
+bun add @nxgt/janus@^0.7 @nxgt/janus-drizzle@^0.3 # or @nxgt/janus-mongo@^0.4, @nxgt/janus-redis@^0.3
 ```
 
-Your own adapter implements it as
-[`TokenStore.countAttempt`](guide/adapters.md#tokenstorecountattempt) sets
-out, then runs the conformance suite.
+Your own adapter implements them as
+[`TokenStore.countAttempt`](guide/adapters.md#tokenstorecountattempt) and
+[`TokenStore.spendUserTokens`](guide/adapters.md#tokenstorespendusertokens)
+set out, then runs the conformance suite.
 
 ### `janus: relations must be a relation store — relations.deleteEntity is missing`
 
@@ -473,7 +475,7 @@ if (error instanceof UserInvalidError) {
 Also `changePassword: the current password does not match`.
 
 **When:** `signIn`, `changePassword`.
-**Why:** no user holds the login, the user has no password, or the password is wrong — **one code for the three**. `error.reason` (`unknownLogin`, `noPassword`, `wrongPassword`) tells them apart for your logs and your rate limiter. A login holding a NUL character or a lone surrogate is `unknownLogin`: no user can hold one.
+**Why:** no user holds the login, the user has no password, or the password is wrong — **one code for the three**. Also a sign-in that verified a password written over while it ran (`reason: 'wrongPassword'`): its session is revoked, or its challenge spent, before the refusal. `error.reason` (`unknownLogin`, `noPassword`, `wrongPassword`) tells them apart for your logs and your rate limiter. A login holding a NUL character or a lone surrogate is `unknownLogin`: no user can hold one.
 **Fix:** answer 401 with the same body whatever the reason:
 
 ```ts
@@ -522,10 +524,14 @@ answered: `secondFactor.confirm: no such challenge`,
 
 **When:** `secondFactor.confirm(challenge, code)`.
 **Why:** a challenge lives five minutes and takes five codes. It is spent by
-the code that opens the session, by the fifth wrong code, and by a refusal
-that ends it (`USER_INACTIVE`, `SECOND_FACTOR_NOT_ENROLLED`). `TOKEN_UNKNOWN`
-also covers a challenge whose user was deleted, and a challenge passed where a
-code was expected — the two arguments swapped.
+the code that opens the session, by the fifth wrong code, by a refusal
+that ends it (`USER_INACTIVE`, `SECOND_FACTOR_NOT_ENROLLED`), and by a
+password written — `resetPassword.confirm`, `setPassword`, `changePassword` —
+which ends every sign-in left waiting on its code.
+`TOKEN_UNKNOWN` also covers a challenge whose user was deleted, one
+confirmed through another user type's `secondFactor`, and a challenge passed
+where a code was expected — the two arguments swapped. Another type's
+`confirm` still costs an attempt, and the fifth spends the challenge.
 **Fix:** answer 400 and send the visitor back to sign in, which asks for a new
 code. To give slower visitors more time:
 
@@ -540,15 +546,20 @@ janus({ ..., secondFactor: { issuer: 'Acme', keys, challenge: '10m' } });
 
 **When:** `signInCode.confirm(challenge, code)`.
 **Why:** a challenge lives ten minutes and takes five codes. It is spent by
-the code that signs the user in, by the fifth wrong code, and by a refusal
-that ends it (`TOKEN_STALE`, `USER_INACTIVE`). `TOKEN_UNKNOWN` also covers a
+the code that signs the user in, by the fifth wrong code, by a refusal
+that ends it (`TOKEN_STALE`, `USER_INACTIVE`), and by the next `request` for
+the same user: only the last code sent works, so a visitor who asked twice
+and typed the first code gets `TOKEN_SPENT` — and when two requests race,
+even the last code can be spent: at most one survives, sometimes none. `TOKEN_UNKNOWN` also covers a
 challenge whose user was deleted, one confirmed through another user type's
 `signInCode`, the decoy challenge of a `request` that answered `null`, and
-the two arguments swapped. Another type's `confirm` compares no code and
-spends nothing, but it has already cost one of the challenge's five
+the two arguments swapped. Another type's `confirm` compares no code, but it
+has already cost one of the challenge's five
 attempts: the attempt is counted before the type is known. The challenge is
-left for its own type, with one attempt fewer.
-**Fix:** answer 400 and offer to send a new code. To give slower inboxes
+left for its own type, with one attempt fewer — and the fifth such call
+spends it, as a fifth wrong code would.
+**Fix:** answer 400 and offer to send a new code — and tell the visitor to
+use the latest e-mail. To give slower inboxes
 more time:
 
 ```ts
@@ -557,8 +568,8 @@ janus({ ..., tokens: { signInCode: '15m' } });
 
 ### `TOKEN_STALE` — `<call>: the token was sent to an e-mail the user no longer has`
 
-**When:** `verifyEmail.confirm` or `resetPassword.confirm`, after the user changed their e-mail.
-**Why:** confirming it would verify an address nobody holds any more. The token is spent.
+**When:** `verifyEmail.confirm` or `resetPassword.confirm`, after the user changed their e-mail — even while the link was being redeemed: the address is checked again on the very record the write replaces.
+**Why:** confirming it would verify an address nobody holds any more, or reset a password through one. The token is spent, and nothing is written.
 **Fix:** send a new token to the current address: `await auth.verifyEmail.send(user)`.
 
 ### `INVALID_CURSOR` — `<call>: this cursor was not minted by this store, or was minted for another ordering (<n> characters)`
@@ -626,7 +637,7 @@ each of those entries has a paragraph for it.
 The same for `session` and `user`.
 
 **When:** `tsc`, wherever `signIn`'s answer is read, once `janus()` is given a `secondFactor` — and `signInCode.confirm`'s, on a user type with a password.
-**Why:** `signIn` then answers one of two shapes: `{ status: 'signedIn', user, session, token }`, or `{ status: 'secondFactor', challenge, expiresAt }` for a user whose second factor is active — the password alone opens no session for them. Without `secondFactor`, `signIn` still answers a session.
+**Why:** `signIn` then answers one of two shapes: `{ status: 'signedIn', user, session, token }`, or `{ status: 'secondFactor', challenge, expiresAt, userId }` for a user whose second factor is active — the password alone opens no session for them. Without `secondFactor`, `signIn` still answers a session.
 **Fix:** switch on `status`:
 
 ```ts
@@ -849,8 +860,8 @@ form field now holds the second challenge, so the first code does not
 match it — and costs an attempt.
 **Fix:** tell the visitor that only the last code sent works, and put the
 time it was sent in the e-mail's subject or text so they can tell the
-e-mails apart. The earlier challenge is not revoked: it still expires on its
-own.
+e-mails apart. The earlier challenge is spent by the new `request`: the
+first code, even with its own challenge, answers `TOKEN_SPENT`.
 
 ### `signInCode.request` answers `null` for a user who exists
 

package/package.json

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