@nxgt/janus 0.6.0 → 0.8.0

package/docs/troubleshooting.md

@@ -39,6 +39,7 @@ How the messages are shaped:
 - [`janus: secondFactor.issuer must name your application …`](#janus-secondfactorissuer-must-name-your-application--the-authenticator-app-shows-it-beside-the-account)
 - [`janus: secondFactor.keys: the key "<id>" is not 32 bytes in base64 …`](#janus-secondfactorkeys-the-key-id-is-not-32-bytes-in-base64--make-one-with-openssl-rand--base64-32)
 - [`"hasSecondFactor" is a field janus sets itself; rename it`](#hassecondfactor-is-a-field-janus-sets-itself-rename-it)
+- [`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)
 - [Other `janus:` wiring messages](#other-janus-wiring-messages)
 
 **Users, sessions and tokens**
@@ -81,6 +82,10 @@ How the messages are shaped:
 - [`TS2339: Property 'signInCode' does not exist on type 'TypeApi<…>'.`](#ts2339-property-signincode-does-not-exist-on-type-typeapi)
 - `CODE_INVALID`, `TOKEN_UNKNOWN`, `TOKEN_SPENT`, `TOKEN_EXPIRED`, `USER_INACTIVE` and `VERSION_CONFLICT` from `signInCode.confirm`, and `TS2339` on its `token`: in their entries above.
 
+**User events**
+- [`[JANUS_EVENT_FAILED] Warning: janus: the events listener failed on <type> <event id> for user <user id>: <name>`](#janus_event_failed-warning-janus-the-events-listener-failed-on-type-event-id-for-user-user-id-name)
+- [An event you expected never arrived](#an-event-you-expected-never-arrived)
+
 **Permissions**
 - [`PERMISSION_DEPTH` — `can: checking <type>#<permission> crossed more than <n> relations without an answer`](#permission_depth--can-checking-typepermission-crossed-more-than-n-relations-without-an-answer)
 - [`permissions: this model was not made by defineModel() …`](#permissions-this-model-was-not-made-by-definemodel--pass-what-definemodel-answered)
@@ -232,9 +237,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 +251,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`
 
@@ -358,6 +365,21 @@ janus({
 **Why:** `user.hasSecondFactor` is janus's own answer: whether the user's second factor is active. A field of yours with that name would be shadowed. From JavaScript, a validated input holding it is refused with `USER_INVALID` and the issue `set by janus, not by a request`.
 **Fix:** rename the field in your schema, and read `user.hasSecondFactor` for janus's answer.
 
+### `janus: events must be a function that takes a user event — webhooks({ … }) from @nxgt/janus-webhooks, or your own`
+
+**When:** `janus({ events })` with something other than a function — most often an object of functions, one per event type.
+**Why:** `events` is one listener, called with every user event; the event's `type` says which.
+**Fix:** pass one function, and switch on `type`:
+
+```ts
+janus({
+  ...config,
+  events(event) {
+    if (event.type === 'user.created') return welcome(event.userId);
+  },
+});
+```
+
 ### Other `janus:` wiring messages
 
 | Message | Fix |
@@ -473,7 +495,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 +544,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 +566,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 +588,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 +657,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 +880,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
 
@@ -895,6 +926,38 @@ janus({
 
 ---
 
+## User events
+
+### `[JANUS_EVENT_FAILED] Warning: janus: the events listener failed on <type> <event id> for user <user id>: <name>`
+
+A process warning, not a thrown error: the flow that sent the event answered as if nothing happened.
+
+**When:** the function given to `janus({ events })` threw or rejected — a queue that was down, a bug in the listener.
+**Why:** the write the event reports has landed. Failing the flow would tell the visitor it did not happen, and their retry would hit `LOGIN_TAKEN`. So the failure is warned about, with the event's type, its id and the user's id, and the failure's name — never its message, which may hold anything.
+**Fix:** make the listener only store the event (a queue, an outbox table) and fix whatever refused it. To send the lost event again, rebuild it from the warning — its type, its `id`, the user's id; the warning has no `occurredAt`, so take the user's `updatedAt` (or the warning's own time) as an approximation:
+
+```ts
+process.on('warning', (warning) => {
+  if ((warning as { code?: string }).code === 'JANUS_EVENT_FAILED') logger.error(warning.message);
+});
+```
+
+### An event you expected never arrived
+
+**When:** a `user.emailVerified` after a confirm, a `user.deleted` after a delete, a `user.created` from a sign-up.
+**Why:** one of these, in order of likelihood:
+- the e-mail was already verified: nothing changed, so nothing is sent;
+- `delete` deleted nobody — a replay, or an id of another user type;
+- the flow was refused, or the store failed during the write itself — the call threw, and nothing was written or sent;
+- the process stopped between the write and the listener — events are sent at most once, from memory;
+- the listener threw: look for `JANUS_EVENT_FAILED` in the process's warnings.
+
+**Fix:** for the last two, reconcile against the users themselves and treat events as the fast path, not the record: page through `auth.list()` and compare with the receiver's copy — a user it lacks is a missed `user.created`, a user the receiver has that `auth.find` answers `null` for is a missed `user.deleted`, and a user whose `emailVerified` differs is a missed `user.emailVerified`.
+
+A store outage **after** the write does not lose the event. `create`, `signUp` and `signInCode.confirm` send it before the steps that follow; `delete` and `resetPassword.confirm` run theirs — removing the sessions, tokens and tuples; revoking the sessions — in a `try`, and send it from its `finally`, whether they succeeded or not.
+
+---
+
 ## Permissions
 
 ### `PERMISSION_DEPTH` — `can: checking <type>#<permission> crossed more than <n> relations without an answer`

package/package.json

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