@nxgt/janus 0.6.0 → 0.8.0

package/docs/README.md

@@ -16,6 +16,7 @@ below are defined once, in [Words](guide/vocabulary.md#words).
 | [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 |
+| [User events](guide/events.md) | You want to hear when a user is created, verifies their e-mail, resets their password or is deleted — to queue it, sync it, or send it as a webhook |
 | [Password hashing](guide/passwords.md) | You are choosing a hasher, raising its cost, moving to argon2id, or importing hashes from another system |
 
 ### Permissions — `@nxgt/janus/permissions`
@@ -30,6 +31,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,11 @@ 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.
+A confirm that verifies the e-mail sends a [`user.emailVerified`
+event](events.md); one for an e-mail already verified sends nothing.
 Changing the e-mail with `update` sets `emailVerified` back to `false`.
 
 ## `resetPassword`
@@ -100,7 +105,11 @@ 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 sends a [`user.passwordReset` event](events.md),
+then `user.emailVerified` when the link verified the e-mail. 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.
 
@@ -147,4 +156,5 @@ never the token, and no refusal's message contains it.
 - [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
+- [User events](events.md) — `user.emailVerified` and `user.passwordReset`, which the confirms send
 - [Errors](errors.md) — every code, and the status it deserves

package/docs/guide/events.md

@@ -0,0 +1,199 @@
+# User events
+
+This page is for hearing what happens to a user once it is written: created,
+e-mail verified, password reset, deleted. Another service can then follow
+without polling. `janus` hands each event to one function you give it;
+**delivering it is yours**, or `@nxgt/janus-webhooks`'s once it ships.
+
+```ts
+import { z } from 'zod';
+import { createMemoryStores, janus, scryptHasher, type UserEvent } from '@nxgt/janus';
+
+const received: UserEvent[] = [];
+
+const auth = janus({
+	user: z.object({ email: z.email() }),
+	password: { login: 'email' },
+	store: createMemoryStores(),
+	hasher: scryptHasher(),
+	events(event) {
+		received.push(event);
+	},
+});
+
+const { user } = await auth.signUp({ email: 'ada@example.com', password: 'correct horse' });
+received[0];
+// {
+//   id: '0199…',            a UUIDv7 minted for this event
+//   type: 'user.created',
+//   occurredAt: Date,       when the write landed — its createdAt here
+//   userId: user.id,
+//   userType: 'user',
+// }
+```
+
+The words — **user event**, **listener** — are defined in
+[the vocabulary](vocabulary.md#identities).
+
+## The four types
+
+| `type` | Sent by | Not sent |
+| --- | --- | --- |
+| `user.created` | `create`, `signUp` — once the user is inserted, even if `signUp`'s session then fails to open | for a sign-up refused (`LOGIN_TAKEN`, `USER_INVALID`, `PASSWORD_TOO_SHORT`) |
+| `user.emailVerified` | `verifyEmail.confirm`; `resetPassword.confirm`, whose link proves the e-mail; `signInCode.confirm`, whose code does | for an e-mail already verified, or a refused confirm |
+| `user.passwordReset` | `resetPassword.confirm` | for `setPassword` or `changePassword` — they are not resets |
+| `user.deleted` | `delete`, when it deleted the user | for a replay that finds nobody, or an id of another user type |
+
+A reset whose link verifies the e-mail sends both, `user.passwordReset`
+first. Switch on `type`: the four are a closed set, and TypeScript refuses a
+fifth.
+
+```ts
+function onUserEvent(event: UserEvent): void {
+	switch (event.type) {
+		case 'user.created':
+			return welcome(event.userId);
+		case 'user.emailVerified':
+			return unlockFeatures(event.userId);
+		case 'user.passwordReset':
+			return alertSecurityTeam(event.userId);
+		case 'user.deleted':
+			return forgetEverywhere(event.userId);
+	}
+}
+```
+
+## What an event carries
+
+**The user named by id, and nothing else.** No login, no e-mail, no field of
+the schema, no password or hash, no session or one-time token. An event can
+land in a queue, a log or another company's endpoint; whoever receives it
+reads the rest from where it is kept — `auth.get(event.userId)` — if they
+may. A user deleted since is `NOT_FOUND` there, which is the answer.
+
+`id` is minted for the event, a UUIDv7 that sorts by time. Deliver on it:
+a queue job id, a primary key, a webhook's `webhook-id` header. Two events
+never share one.
+
+## When the listener runs
+
+After the write, **awaited**, before the flow answers. So a listener
+that stores the event durably — a job queue, an outbox table — has done so
+when `signUp` answers:
+
+```ts
+const auth = janus({
+	...config,
+	async events(event) {
+		await jobs.add(event.type, event, { jobId: event.id });
+	},
+});
+```
+
+Where the listener runs within a flow, and what an outage does to it:
+
+| Flow | The listener runs | A store outage after the write |
+| --- | --- | --- |
+| `create` | after the insert — its last step | — |
+| `signUp` | after the insert, **before** the session is opened | fails the call; the event is already sent |
+| `verifyEmail.confirm` | after the write — the flow's last step | — |
+| `signInCode.confirm` | after the write, **before** the session or the second-factor challenge is opened | fails the call; the event is already sent |
+| `resetPassword.confirm` | **after** the sessions opened with the old password are revoked and the second-factor challenges left open are spent | fails the call; the events are sent all the same, from a `finally` |
+| `delete` | **after** the user's sessions and one-time tokens are removed, and the relation tuples naming them when `relations` is wired | fails the call; the event is sent all the same, from a `finally` |
+
+So a listener that takes its time never leaves an old session alive after a
+reset, and one that checks permissions on `user.deleted` finds the tuples
+gone. A retry could not send a lost event either way: `delete` then finds
+nobody, and the reset link is spent.
+
+`occurredAt` is the write's own time: the `createdAt` or `updatedAt` it
+wrote, the time read just before the deletion — not when the listener ran.
+
+It runs inline, so it costs every flow that sends an event: store the event
+and return. Sending an HTTP request from the listener makes every sign-up as
+slow as the slowest endpoint, and as fragile.
+
+## When the listener fails
+
+**It fails no flow.** The write happened: answering `signUp` with an error
+would tell the visitor their account does not exist when it does, and a retry
+would hit `LOGIN_TAKEN`. So a listener that throws, or rejects, is a warning:
+
+```
+(node:4242) [JANUS_EVENT_FAILED] Warning: janus: the events listener failed on user.created 0199… for user 0199…: Error
+```
+
+It names the event's type, its `id` and the user's id — what it takes to send
+it again — and the failure's name, never its message, which may hold anything.
+Listen for it where you watch your process's health:
+
+```ts
+process.on('warning', (warning) => {
+	if ((warning as { code?: string }).code === 'JANUS_EVENT_FAILED') {
+		metrics.increment('janus.events.failed');
+		logger.error(warning.message);
+	}
+});
+```
+
+## What is not promised
+
+**At most once, from the process that wrote.** The event is handed to the
+listener after the write, in memory: a crash between the two loses it, and
+nothing sends it later — there is no outbox in the store. What must never
+miss one — a billing sync, a search index — also reads the users now and
+then, and treats events as the fast path.
+
+**No order across processes.** Two instances each hand their own events to
+their own listener. `occurredAt` and the time-sorted `id` let a receiver put
+them back in order.
+
+## In a test
+
+```ts
+import { expect, it } from 'bun:test';
+import { z } from 'zod';
+import { createMemoryStores, janus, scryptHasher, type UserEvent } from '@nxgt/janus';
+
+it('tells the CRM about a sign-up', async () => {
+	const received: UserEvent[] = [];
+	const auth = janus({
+		user: z.object({ email: z.email() }),
+		password: { login: 'email' },
+		store: createMemoryStores(),
+		hasher: scryptHasher({ cost: 10 }),
+		events: (event) => void received.push(event),
+	});
+
+	const { user } = await auth.signUp({ email: 'ada@example.com', password: 'correct horse' });
+
+	expect(received).toEqual([expect.objectContaining({ type: 'user.created', userId: user.id })]);
+});
+```
+
+## Signatures
+
+```ts
+type UserEventType = 'user.created' | 'user.emailVerified' | 'user.passwordReset' | 'user.deleted';
+
+interface UserEvent {
+	readonly id: Id;           // a UUIDv7, the key to deliver it once
+	readonly type: UserEventType;
+	readonly occurredAt: Date; // when the write landed: the createdAt or updatedAt written, or the time read just before a deletion
+	readonly userId: Id;
+	readonly userType: string;
+}
+
+type UserEventListener = (event: UserEvent) => void | Promise<void>;
+
+janus({ ..., events?: UserEventListener });
+```
+
+`events` that is not a function is a `TypeError` when `janus()` is called —
+see [troubleshooting](../troubleshooting.md#janus-events-must-be-a-function-that-takes-a-user-event--webhooks---from-nxgtjanus-webhooks-or-your-own).
+
+## See also
+
+- [E-mail verification and password reset](email-flows.md) — the flows that send `user.emailVerified` and `user.passwordReset`
+- [Users](users.md) — `create`, `signUp`, `delete`
+- [Troubleshooting](../troubleshooting.md) — `JANUS_EVENT_FAILED`

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
 
@@ -238,7 +256,8 @@ janus({ ..., tokens: { signInCode: '15m' } });
 
 A user whose `emailVerified` was `false` has it `true` once `confirm`
 succeeds, and their `version` moves: the code proves the address as a
-verification link would. A user already verified is not written.
+verification link would, and a [`user.emailVerified` event](events.md) is
+sent. A user already verified is not written, and nothing is sent.
 
 ### A second factor is still asked for
 
@@ -270,8 +289,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

@@ -96,6 +96,7 @@ that cuts an emoji in half, say.
 | `tokens.resetPassword` | `Duration` | `'1h'` | How long a reset token lives |
 | `tokens.signInCode` | `Duration` | `'10m'` | How long an e-mailed sign-in code and its challenge live. See [sign-in codes](sign-in-code.md) |
 | `secondFactor` | `{ issuer, keys, challenge? }` | none | A TOTP second factor for every type with a password. Changes what `signIn` answers — see [the second factor](second-factor.md#configuration) |
+| `events` | `UserEventListener` | none | Called with every user event — `user.created`, `user.deleted`, … — after the write, awaited. See [user events](events.md) |
 
 A `Duration` is `'500ms'`, `'30s'`, `'15m'`, `'8h'`, `'7d'`, or a number of
 milliseconds.
@@ -185,10 +186,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
@@ -228,7 +229,9 @@ read before that sign-in conflicts — see [passwords](passwords.md#rehash-on-si
 Deletes the user **with every session and one-time token they had**, and
 every tuple naming them when `relations` is wired. The user goes first, so an
 outage half-way leaves only sessions and tokens that authenticate nobody. It is
-idempotent: calling it again finishes the job.
+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`.
 
 ### Paging every user
 
@@ -285,5 +288,6 @@ fields against your schema, not that `password` is a string.
 ## See also
 
 - [Sessions](sessions.md) — `authenticate`, the cookie, signing out
+- [User events](events.md) — what `create`, `signUp` and `delete` send
 - [Errors](errors.md) — every code, and the status it deserves
 - [Writing an adapter](adapters.md) — the identity stores behind `store`

package/docs/guide/vocabulary.md

@@ -51,10 +51,13 @@ 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 | |
 | **e-mail flow** | `verifyEmail` or `resetPassword`: send a one-time token, then confirm it. `signInCode` sends a one-time code instead | |
+| **user event** | What happened to a user, once it is written: `user.created`, `user.emailVerified`, `user.passwordReset`, `user.deleted` — a `UserEvent`, naming the user by id alone, with an `id` of its own. See [user events](events.md) | "webhook" — a webhook is one way to deliver it; "event" alone where it could be read as `@nxgt/janus-telemetry`'s audit log record — on a page about user events, "the event" is fine |
+| **listener** | The one function `janus({ events })` hands every user event to, after the write and awaited | "handler", "hook", "subscriber" |
 
 ### Permissions
 

package/docs/roadmap.md

@@ -36,12 +36,13 @@ Nothing between releases.
   catalogue, or replace any one template with your own function of the same
   shape — built with the same toolkit, React Email or a plain string — and
   keep the defaults for the rest.
-- **Webhooks** — signed HTTP events when something happens to a user
-  (created, e-mail verified, password reset, deleted), so another service can
-  follow without polling: a signature it can check, retries on failure, and
-  the same rule as the audit trail — the user named by id, never a login, a
-  password, a session token or a one-time token in a payload, and every key
-  camelCase. Retries that run out are reported, never dropped in silence.
+- **Webhooks** — in a package of its own, `@nxgt/janus-webhooks`: the user
+  events `janus({ events })` already hands over, signed and sent over HTTP,
+  so another service can follow without polling. A signature it can check —
+  the Standard Webhooks headers, HMAC-SHA256, secrets that rotate — retries
+  with backoff on failure, and retries that run out reported to a function
+  you give, never dropped in silence. The payload is the event: the user
+  named by id, every key camelCase.
 
 ## Later
 
@@ -93,6 +94,24 @@ Nothing between releases.
 The last ten, newest first, each with the version it came in. Everything
 before is in the [CHANGELOG](../CHANGELOG.md).
 
+- **User events, v0.8.0** — `janus({ events })` takes one listener, called
+  with `user.created`, `user.emailVerified`, `user.passwordReset` and
+  `user.deleted` once the write landed, and awaited before the flow answers.
+  An event names the user by id alone, with a UUIDv7 of its own to deliver
+  it once; a listener that throws fails no flow and is a
+  `JANUS_EVENT_FAILED` warning.
+- **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
@@ -146,10 +165,3 @@ before is in the [CHANGELOG](../CHANGELOG.md).
 - **`LOGIN_TAKEN` no longer quotes the login in its message**, in the memory
   store and in both adapters; `error.login` still names it, and the
   conformance suite checks it. — v0.2.0
-- **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.