@nxgt/janus 0.7.0 → 0.8.1

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`

package/docs/guide/email-flows.md

@@ -77,6 +77,8 @@ 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`
@@ -106,7 +108,8 @@ export async function forgotPassword(request: Request): Promise<Response> {
 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
+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.
 
@@ -153,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/sign-in-code.md

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

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.
@@ -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

@@ -56,6 +56,8 @@ either finds this row.
 | **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

@@ -5,7 +5,13 @@ dates here, and the version something shipped in is the only number.
 
 ## Now
 
-Nothing between releases.
+- **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 carries the event: the user
+  named by id, every key camelCase.
 
 ## Next
 
@@ -36,12 +42,6 @@ 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.
 
 ## Later
 
@@ -93,6 +93,12 @@ 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
@@ -158,6 +164,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

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)
@@ -360,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 |
@@ -906,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.7.0",
+	"version": "0.8.1",
 	"description": "Embeddable, type-safe identities and permissions: bring your own database",
 	"license": "MIT",
 	"type": "module",