@nxgt/janus 0.23.1 → 0.25.0

package/docs/guide/adapters.md

@@ -31,7 +31,7 @@ describeJanusStores({
 
 | Port | Taken by | Methods |
 | --- | --- | --- |
-| `JanusStores` — `{ users: UserStore, sessions: SessionStore, tokens: TokenStore }` | `janus({ store })` | 6 (+ 1 optional) + 7 (+ 1 optional) + 5 |
+| `JanusStores` — `{ users: UserStore, sessions: SessionStore, tokens: TokenStore }` | `janus({ store })` | 6 (+ 1 optional) + 7 (+ 1 optional) + 5 (+ 1 optional) |
 | `RelationStore` | `permissions({ store })`, `janus({ relations })` | 6 |
 
 They are separate on purpose: an application that only authenticates
@@ -184,6 +184,7 @@ interface TokenStore {
 	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>;
+	deleteExpiredTokens?(before: Date): Promise<number>; // optional: omit it if the database expires on its own
 }
 ```
 
@@ -368,6 +369,41 @@ of the right `kind` whose `spentAt` is empty, skipping the one named by
 `except`. `spendUserTokens` has its own
 outage case.
 
+### `TokenStore.deleteExpiredTokens` (optional)
+
+What `collectExpired()` asks for, beside `SessionStore.deleteExpiredSessions`:
+**delete every token whose `expiresAt` is at or before `before`**, and answer
+how many. Leave it out when your database expires records on its own (a TTL
+index, a key TTL) — nothing breaks, the core compares `expiresAt` on every
+redemption — and implement it when it does not, or the rows pile up.
+
+| The stored token | Written |
+| --- | --- |
+| `expiresAt` at or before `before`, spent or not, of any kind and any user | deleted, and counted |
+| `expiresAt` later than `before`, spent or not | **kept** |
+| none at all | `0`, an absence — never a failure |
+
+**Never delete a token whose `expiresAt` is later, spent or not**: a spent
+token is kept, answered as spent, until it lapses, or a count would start
+over. That includes the throttles' counts — ordinary `secondFactor` tokens
+under a keyed-hash user id, which `deleteUserTokens` never reaches and this
+method is the only thing to collect. The core calls it with `clock.now()`, no
+margin: a link collected answers `TOKEN_UNKNOWN`.
+
+```ts
+import type { TokenStore } from '@nxgt/janus';
+
+// PostgreSQL through Drizzle — one statement, over an index on expires_at
+deleteExpiredTokens: async (before) =>
+	(await db.delete(tokens).where(lte(tokens.expiresAt, before)).returning({ tokenHash: tokens.tokenHash })).length,
+```
+
+`janus()` reads its presence once (`StoreCapabilities.collectExpiredTokens`),
+and refuses a `deleteExpiredTokens` that is there but not a function with a
+`TypeError`. The suite's `tokens.deleteExpired` and `outage.deleteExpiredTokens`
+cases check it, and are skipped with their reason for a store that leaves it
+out. A failure throws, as everywhere on the port.
+
 ### `RelationStore`
 
 ```ts
@@ -449,7 +485,7 @@ compile error naming the missing method.
 
 | Suite | Cases | Harness opens |
 | --- | --- | --- |
-| `describeJanusStores({ name, harness, runner?, faults?, skip? })` | 59: users, sessions, tokens, and one outage per method whose honest answer can be "nothing" — fifteen of them | `{ stores, faults?, close? }` |
+| `describeJanusStores({ name, harness, runner?, faults?, skip? })` | 61: users, sessions, tokens, and one outage per method whose honest answer can be "nothing" — sixteen of them | `{ stores, faults?, close? }` |
 | `describeRelationStores({ name, harness, runner?, faults?, skip? })` | 16: the relation store, ids of edge characters, and one outage per method | `{ store, faults?, close? }` |
 
 `harness.open()` is called **once per case** and must answer fresh, empty
@@ -546,7 +582,8 @@ describeJanusStores({
 
 A skipped case still appears in the run, with its reason in its name. A case
 that cannot run on the stores it was given — an outage case with no `faults`,
-`collectExpired` on a store without `deleteExpiredSessions`, a `findUsers`
+`sessions.deleteExpired` on a store without `deleteExpiredSessions`,
+`tokens.deleteExpired` on one without `deleteExpiredTokens`, a `findUsers`
 case on a store without `findUsers` — passes, and emits a
 `JANUS_CONFORMANCE_SKIPPED` warning with the reason. A case's `needs` says what
 it cannot run without — one `CaseNeed` or a list: `outage.findUsers` needs

package/docs/guide/email-flows.md

@@ -182,7 +182,8 @@ confirms read it: `emailVerified`.
 **Call it before `setPassword` and before `signInProven`.** It drops the
 password and revokes every session, so in the other order it erases the
 password the invitee just chose, and signs out the session just opened.
-Accepting an invitation is `findByEmail` (or `create`), `proveFirst`,
+Accepting an invitation is `findByEmail` (or `create`; `findOrCreate` does both
+in one call), `proveFirst`,
 `setPassword` for a type with a password, then `signInProven` —
 [sessions](sessions.md#accepting-an-invitation) has the route in full.
 
@@ -195,8 +196,37 @@ whoever chooses it can drop anybody's password and second factor.
 It sends no e-mail, issues no token, and counts in neither the mail
 throttle nor the sign-in throttle. An inactive user is `USER_INACTIVE`; a
 malformed id, an unknown one or one of another type is `NOT_FOUND`, as for
-`signInProven`; a user written between the read and the write is
-`VERSION_CONFLICT`, and nothing is proved; an outage is `STORE_FAILED`.
+`signInProven`; an outage is `STORE_FAILED`.
+
+**A write landing between the read and the proof is retried once.** The
+proof is written under the version read, so a write in between (the user
+renaming themselves, a second acceptance of the same invitation) makes it
+`VERSION_CONFLICT`. `proveFirst` then runs the whole flow again on a fresh
+read, and what that read finds decides:
+
+- the user is gone or of another type: `NOT_FOUND`; inactive:
+  `USER_INACTIVE`;
+- **the e-mail is no longer the address first read, or the one your `User`
+  carries** (compared as e-mails
+  are, so a change of case or spacing is the same address): the original
+  `VERSION_CONFLICT`, with nothing proved: the address changed since the first
+  read, or is not the one the `User` you passed carries. The proof you hold
+  reached the inbox of the address you read;
+- the e-mail was proved meanwhile: `{ user, proved: false }`;
+- otherwise the proof runs under the new version, and one
+  `user.emailVerified` is sent.
+
+**The address you hold is checked.** Pass the `User` you read (any object
+carrying the type's e-mail field) and `proveFirst` compares that address,
+normalised as e-mails are, with the one it reads, on the first read and on
+the retry read: a stale `User` whose address changed is `VERSION_CONFLICT`
+and nothing is proved. Pass a bare id string, or an object without the e-mail
+field, and it proves the current address, whatever it is.
+
+A second `VERSION_CONFLICT` propagates: nothing is proved, and calling
+again is safe. Running the proof twice is harmless: a failed attempt wrote
+nothing and sent no event, and the sessions it revoked and the tokens it
+spent before the write are revoked and spent again to the same end.
 `@nxgt/janus-telemetry` traces it as `janus.<type>.verifyEmail.proveFirst`
 and writes `janus.email.verified` with `janus.email.proveFirst: true` when
 it proved — the user's id, never the address.
@@ -481,8 +511,8 @@ answers again. A refused request is counted too but cannot extend the wait.
 **Where the counts live.** In the tokens store, as `secondFactor` tokens named
 by a keyed hash of the flow and the address or user id: no port change, no new
 infrastructure, and never the address. That is one row per flow per address or
-user per window. On PostgreSQL, `collectExpired()` does not collect lapsed
-ones: schedule the delete, as for the sign-in throttle. A flushed or evicting
+user per window. `collectExpired()` collects the lapsed ones on a tokens store that implements
+`deleteExpiredTokens`; a store with a TTL expires them on its own. A flushed or evicting
 Redis forgets the counts, and a tokens store that cannot count throws
 `STORE_FAILED` with nothing issued: it fails closed.
 

package/docs/guide/errors.md

@@ -51,7 +51,7 @@ that wired the library, so no handler needs to tell it apart.
 | `STORE_FAILED` | `StoreFailure` | 503 | A store could not answer. **Never a negative answer** | `slot`, `operation`, `cause` |
 | `NOT_FOUND` | `NotFoundError` | 404 | `get`, `getUser`, `signInProven`, `verifyEmail.proveFirst`, or a write to a user who is gone. `find*` answers `null` instead | `userId` |
 | `LOGIN_TAKEN` | `StoreConflict` (`on: 'login'`) | 409 | Another user of the same type holds the login — on `changeEmail.confirm`, the new address | `login`, `userType` |
-| `VERSION_CONFLICT` | `StoreConflict` (`on: 'version'`) | 409 | `ifVersion` no longer matches; nothing was written. From `secondFactor.confirm` or `recover`, the same code used by two sign-ins at once: the other opened the session. From `verifyEmail.proveFirst`, the user was written between its read and its write: nothing was proved — call it again | `expectedVersion`, `actualVersion` |
+| `VERSION_CONFLICT` | `StoreConflict` (`on: 'version'`) | 409 | `ifVersion` no longer matches; nothing was written. From `secondFactor.confirm` or `recover`, the same code used by two sign-ins at once: the other opened the session. From `verifyEmail.proveFirst`, which already retried once: the user was written again during the retry, or the write changed the e-mail address; nothing was proved | `expectedVersion`, `actualVersion` |
 | `USER_INVALID` | `UserInvalidError` | 400 | The fields failed the schema | `issues`, field by field |
 | `PASSWORD_TOO_SHORT` | `CredentialError` | 400 | Below `password.minLength` | `minLength` — never the password |
 | `CREDENTIALS_INVALID` | `CredentialError` | 401 | Unknown login, no password, or the wrong one — **one code for the three** — and any password, the right one included, at a login past its attempts in the window — see [throttling](passwords.md#password-guessing-is-throttled) | `reason`, for your logs only; `retryAfter`, the seconds until the next window, when throttled |
@@ -64,7 +64,7 @@ that wired the library, so no handler needs to tell it apart.
 | `SECOND_FACTOR_NOT_ENROLLED` | `SecondFactorError` | 409 | `activate` before `enroll`; `regenerateRecoveryCodes` without an active factor; `confirm` or `recover` after the factor was disabled | `userId` |
 | `SECOND_FACTOR_ACTIVE` | `SecondFactorError` | 409 | `enroll` or `activate` on a factor already active: `disable` it first | `userId` |
 | `INVALID_CURSOR` | `InvalidCursorError` | 400 | A cursor this store did not mint. Never a silent first page | |
-| `UNSUPPORTED` | `UnsupportedError` | 501 | The wired store lacks an optional capability — `collectExpired` without `deleteExpiredSessions` | `slot`, `operation` |
+| `UNSUPPORTED` | `UnsupportedError` | 501 | The wired store lacks an optional capability — `collectExpired` with neither `deleteExpiredSessions` nor `deleteExpiredTokens` | `slot`, `operation` |
 | `PERMISSION_DEPTH` | `PermissionDepthError` | 500 | A check or list walked past `maxDepth`. **Not a denial** | `permission`, `maxDepth` |
 
 Every class extends `JanusError`, which extends `Error`, so no `catch` block

package/docs/guide/passwords.md

@@ -195,16 +195,13 @@ counts correctly. Each is named by a keyed hash of the login, never the login
 otherwise, which only keeps the login out of plain sight: a dump of the
 tokens then tells which logins were tried, for a guessed list. Each expires
 two windows after its window starts — half an hour by default — **Redis and MongoDB drop it then;
-PostgreSQL keeps it** until something deletes it, and every login tried,
-registered or not, adds a row per window. Schedule a delete with
-`@nxgt/janus-drizzle`:
-
-```sql
-delete from tokens where expires_at < now() - interval '1 hour'; -- janus.tokens when your tables have a schema of their own
-```
-
-`tokens` has no index on `expires_at`, so the delete scans the table: add
-`create index on tokens (expires_at)` in a migration of yours if it grows.
+a store with no TTL keeps it** until `collectExpired()` deletes it (the
+tokens store's optional `deleteExpiredTokens`), and every login tried,
+registered or not, adds a row per window. Schedule `collectExpired()` on such
+a store: `@nxgt/janus-drizzle` implements `deleteExpiredTokens` (since 0.9),
+with an index on `expires_at` that its
+[migration](https://github.com/softistx/nxgt-janus/blob/develop/packages/janus-drizzle/docs/guide/migrations.md#to-09-an-index-on-tokensexpires_at)
+adds. A store of your own implements the method, or its rows stay.
 
 The key is your first `secondFactor` key: wiring
 `secondFactor` for the first time, or putting a new key first, starts every

package/docs/guide/permissions.md

@@ -1,7 +1,7 @@
 # Permissions — `@nxgt/janus/permissions`
 
 This page is for modelling who may do what, and asking: `defineModel`,
-`fromField`, `when`, then `can`, `list`, `grant` and `revoke`. It is
+`fromField`, `when`, then `can`, `list`, `grant`, `revoke` and `replace`. It is
 Zanzibar's model — relations between objects and subjects, permissions
 computed from them — **without its infrastructure**: the tuples live in your
 database, so a read follows a write and there is nothing to cache.
@@ -544,6 +544,47 @@ await relations.write({
 Narrowing a model therefore hides the tuples it no longer admits; it does not
 delete them, and widening it again brings them back.
 
+### `replace`
+
+```ts
+replace(object, relation, subjects): Promise<{ added: RelationTuple[]; removed: RelationTuple[] }>;
+```
+
+Makes `subjects` the only holders of `relation` on `object`: the use is
+keeping a group's members equal to a list the application already holds.
+`subjects` is typed as `grant`'s `subject`, as an array. It answers the
+tuples it added and the tuples it removed, `{ object, relation, subject }`
+each, in the order written, so the application can audit or mirror them.
+
+```ts
+const wanted = await db.staff.membersOf('cardiology');
+const { added, removed } = await access.replace(cardiology, 'members', wanted);
+// added[0] is { object: cardiology, relation: 'members', subject: … }
+
+await access.replace(cardiology, 'members', []);   // removes every holder
+```
+
+- Every subject is checked first, as `grant()` checks it, and one refusal
+  anywhere in the list is a `TypeError` that writes nothing. An empty list
+  still names an object and a stored relation, and those are checked.
+- The current holders are read (`findEntities` and `findSubjectSets`), and the
+  difference is one `write`: removals and additions together, all or nothing
+  as the port requires, and no write when both are empty.
+- A holder is told apart by its type, id and, for a subject set, its relation:
+  `team:t2#members` is not the entity `team:t2`. A subject listed twice counts
+  once.
+- Tuples of other relations, and of other objects, are never touched. A tuple
+  stored past the model (an older model, or by hand) that the list does not
+  name is removed like any other holder.
+- A failure is `STORE_FAILED`, as for `grant()`.
+- It reads every holder of the relation, so a relation store must answer them
+  all through `findEntities` and `findSubjectSets` and never cap.
+
+**Two concurrent calls on the same object and relation are not serialised.**
+Each reads, then writes its own diff, so the result can hold the union of both
+adds. A caller that needs one winner serialises them itself, with a lock or a
+queue of its own.
+
 ### Deleting
 
 Wire the relation store into `janus({ relations })`, as the clinic does, and

package/docs/guide/sessions.md

@@ -264,6 +264,12 @@ export async function accept(request: Request): Promise<Response> {
 }
 ```
 
+**`findOrCreate` is step 1 in one call.** `auth.findOrCreate(invitation.email, () => ({ … }))`
+finds the holder or creates the user, losing no race to a second acceptance
+of the same invitation, and its `input` may throw to refuse — "a password is
+required" — before anything is written
+([users](users.md#finding-a-user-or-creating-them--findorcreate)).
+
 **The order is the recipe.** `verifyEmail.proveFirst` (since 0.22) applies
 the first proof of the e-mail that a sign-in link would: on an address
 never proved, somebody may have signed up with it first, with a password
@@ -323,10 +329,21 @@ a link or a code already in the person's inbox still works afterwards.
 const removed: number = await auth.collectExpired();
 ```
 
-Deletes lapsed sessions, for a store that keeps them. It rejects with
-`UNSUPPORTED` when the sessions store does not implement the optional
-`deleteExpiredSessions` — a store with its own TTL, such as
-`@nxgt/janus-mongo`'s, does not. The reference store implements it.
+Deletes lapsed sessions and lapsed one-time tokens, from the stores that keep
+them, and answers how many in all. The tokens include the sign-in and mail
+throttles' counts, which are ordinary tokens. It runs whichever of the
+optional `sessions.deleteExpiredSessions` and `tokens.deleteExpiredTokens` the
+stores implement, sessions first, and rejects with `UNSUPPORTED` only when
+neither does — a store with its own TTL, such as `@nxgt/janus-mongo`'s, does
+not implement them. The reference store implements both.
+
+A token is deleted once its `expiresAt` is at or before now, spent or not;
+one that has not lapsed is never deleted, so a throttle keeps counting and a
+link still redeems until its time is up. After a token is collected, its link
+answers `TOKEN_UNKNOWN` rather than `TOKEN_EXPIRED` or `TOKEN_SPENT`, as it
+already does on a store with a TTL. A failure in the tokens store, after the
+sessions went, is `STORE_FAILED`; both deletions are idempotent, so call it
+again.
 
 ## Testing expiry
 

package/docs/guide/users.md

@@ -203,6 +203,7 @@ With an e-mail — the field `email` names, password or not — besides:
 | Method | Answers | Rejects with |
 | --- | --- | --- |
 | `findByEmail(email)` | the user, or `null`; the address trimmed and lowercased as the e-mail flows do, whatever the login; a value that is no address is nobody's — **server-side only**, see [below](#finding-a-user-by-e-mail--findbyemail) | `STORE_FAILED` only |
+| `findOrCreate(key, input)` | `{ user, created }`: the holder of `key`, or the user `input()` describes, created; every type with a login or an e-mail — **server-side only**, see [below](#finding-a-user-or-creating-them--findorcreate) | `USER_INVALID`, `PASSWORD_TOO_SHORT`, `LOGIN_TAKEN`, `STORE_FAILED`, and what `input` throws |
 
 With `secondFactor` configured, a type with a password also answers
 `secondFactor.enroll`, `activate`, `disable` and `confirm` — see
@@ -370,6 +371,49 @@ none by design.
   `@nxgt/janus-telemetry` traces it as `janus.<type>.findByEmail`, with the
   `user.id` it found and never the address.
 
+### Finding a user, or creating them — `findOrCreate`
+
+```ts
+findOrCreate(
+	key: string,
+	input: () => Fields | Promise<Fields>, // what create takes
+): Promise<{ user: User; created: boolean }>
+// typed by FindOrCreateApi<User, Fields>, exported from @nxgt/janus
+```
+
+The accept step of an invitation, without the race between `findByEmail`
+and `create`. The `key` is looked up as the type's own lookup would: the
+login on a type with a password, the e-mail on a type without one — so a
+type with neither has no `findOrCreate`. A user found, inactive or not, is
+answered `{ user, created: false }` and `input` is never called:
+
+```ts
+const invitation = await invitations.spend(hash(token), new Date()); // your proof, verified first
+if (invitation === null) return notFound();
+const { user, created } = await clinic.patient.findOrCreate(invitation.email, () => {
+	if (body.password === undefined) throw new Error('a password is required'); // refused before any write
+	return { email: invitation.email, birthDate: body.birthDate }; // no password: proveFirst would drop it
+});
+await clinic.patient.verifyEmail.proveFirst(user);          // drops what a squatter left
+if (typeof body.password === 'string') await clinic.patient.setPassword(user, body.password); // set once, here
+```
+
+- **`input` runs only on an absence, and may refuse.** What it throws
+  propagates, and nothing is written.
+- **The key is a string.** Any other value is `USER_INVALID` before `input`
+  is called.
+- **The input names the key.** After validation its login (its e-mail, on a
+  type with no password), normalised, must equal the normalised `key`; if it
+  does not, the call rejects with `USER_INVALID` before the write.
+- **Created exactly as `create` creates**: validation, hashing, the password
+  policy, `user.created`. The event is sent only when this call created.
+- **A lost race answers the winner.** If the write meets `LOGIN_TAKEN`, the
+  key is read once more: found, it is `{ user, created: false }`; still
+  absent, the `LOGIN_TAKEN` is rethrown.
+- **A key that is no storable string** is nobody's, as for `findByLogin`, and
+  goes through `input` and the creation, which refuses it with `USER_INVALID`.
+- **Server-side only**, an account-existence oracle like `findByEmail`.
+
 ### Paging every user
 
 ```ts

package/docs/guide/vocabulary.md

@@ -30,7 +30,7 @@ either finds this row.
 | --- | --- | --- |
 | **side** | One of the two things Janus does, each usable alone: identities or permissions | "half", "module" |
 | **identities** | The side that answers *who is this?* — users, logins, passwords, sessions, one-time tokens. `janus()`, from `@nxgt/janus` | "auth", "authentication", in prose; `auth` is only the variable name in examples |
-| **permissions** | The side that answers *may they?* — a model, the tuples stored against it, `can`, `list`, `grant`, `revoke`. `@nxgt/janus/permissions` | "authorization", "access control", "ACL" |
+| **permissions** | The side that answers *may they?* — a model, the tuples stored against it, `can`, `list`, `grant`, `revoke`, `replace`. `@nxgt/janus/permissions` | "authorization", "access control", "ACL" |
 
 ### Identities
 

package/docs/roadmap.md

@@ -5,7 +5,7 @@ dates here, and the version something shipped in is the only number.
 
 ## Now
 
-Nothing between releases.
+Nothing yet.
 
 ## Next
 
@@ -13,13 +13,6 @@ Nothing yet.
 
 ## Later
 
-- **Collecting lapsed one-time tokens** — `collectExpired()` deletes lapsed
-  sessions only. On a store with no TTL (PostgreSQL), lapsed tokens stay
-  until you delete them, and the sign-in throttle adds one per login tried
-  per window, and the mail throttle one per flow per address or user per
-  window. A port method to collect them, as sessions are, would let the
-  core do it.
-
 - **A batch read across types** — `findMany` reads one user type, as `find`
   does. The shared `findUser(id)` has no batch counterpart yet; one on the
   instance, answering a union narrowed by `user.type`, would serve a list that
@@ -76,6 +69,38 @@ Nothing yet.
 The last ten, newest first, each with the version it came in. Everything
 before is in the [CHANGELOG](../CHANGELOG.md).
 
+- **Collecting lapsed one-time tokens, v0.25.0** — `collectExpired()` deletes
+  lapsed sessions and, through a new optional `TokenStore.deleteExpiredTokens`,
+  lapsed one-time tokens too: the sign-in and mail throttles' counts
+  included, which a store with no TTL (PostgreSQL) kept for ever, one per
+  login tried per window and one per flow per address or user per window.
+  The reference store and `@nxgt/janus-drizzle` 0.9 implement it; MongoDB and
+  Redis expire tokens themselves and do not.
+- **Finding a user, or creating them, v0.24.0** —
+  `auth.<type>.findOrCreate(key, input)` answers `{ user, created }`: the
+  holder of the key — the login on a type with a password, the e-mail on one
+  without — or the user `input()` describes, created as `create` creates
+  one. `input` runs only on an absence and may refuse before any write; it
+  must name the key, or the call is `USER_INVALID`; a lost race is
+  answered with the winner, `created: false`. It is the accept step of an
+  invitation in one call. Server-side only.
+- **`replace()` on permissions, v0.24.0** — `access.replace(object, relation,
+  subjects)` makes a list of subjects the only holders of a relation, in one
+  write, and answers `{ added, removed }`, the tuples added and the tuples
+  removed: the call that keeps a group's members equal to a list the
+  application holds, and what `@nxgt/janus-telemetry` traces as a `janus.replace`
+  span with one audit event per tuple. Concurrent calls on the same
+  object and relation are not serialised.
+- **Retrying `verifyEmail.proveFirst` once on a version conflict, v0.24.0** — a write
+  landing between the read and the proof no longer fails the call: it reads
+  the user again and proves under the new version, answers `proved: false`
+  when that write proved the e-mail, and keeps `VERSION_CONFLICT` when the
+  address changed since the first read, or is not the one the passed `User`
+  carries (the proof the caller holds is for the address it read), or when
+  the retry conflicts too. Given a `User`, it also compares the address
+  that `User` carries with the one it reads, on the first read and on the
+  retry: a stale `User` whose address changed is `VERSION_CONFLICT`, with
+  nothing proved. Given a bare id, it proves the current address.
 - **Changing a user's e-mail, v0.23.0** —
   `auth.<type>.changeEmail.send(user, email)` issues a link for the new
   address, and `changeEmail.confirm(token)` moves the user there, verified,
@@ -140,33 +165,3 @@ before is in the [CHANGELOG](../CHANGELOG.md).
   The window is no longer than the shortest default token lifetime. The counts
   live in the tokens store, with no port change. `MailConfig` and
   `MailThrottleConfig` are exported.
-- **A sign-in from a new device, v0.17.0** — `janus({ devices: { keys } })`,
-  and `{ device }` as the last argument of `signUp`, `signIn`,
-  `secondFactor.confirm`, `secondFactor.recover`, `signInCode.confirm` and
-  `magicLink.confirm`: the device token the client holds, or `null`. Every
-  answer that opens a session says `newDevice` and hands back a
-  `deviceToken` for a long-lived cookie, and a new device sends
-  `user.newDeviceSignedIn`, with the new session's `sessionId`, once the
-  sign-in is complete. Nothing is stored: the token is a device id signed
-  for the user, so the store ports are unchanged. A sign-up is never new, a
-  call given no device is not tracked, and removing a key forgets every
-  device it signed. Breaking for a `switch` that exhausts `UserEventType`,
-  and for a `SignedIn` built by hand. See [devices](guide/devices.md).
-- **The first sign-in by link or code ends a squatter's password and second
-  factor, v0.16.0** — when `signInCode.confirm` or `magicLink.confirm`
-  proves an e-mail never verified, the password and the second factor with
-  its recovery codes are dropped and every session signed out before the
-  new one opens: whoever registered the address without its inbox keeps
-  nothing, and the owner is asked for no factor they never set.
-  `user.passwordChanged` and `user.secondFactorDisabled` report what was
-  dropped. An e-mail already verified changes nothing.
-- **Sign in with an e-mailed link (magic link), v0.15.0** —
-  `auth.magicLink.request(email)` and `magicLink.confirm(token)` on every
-  user type with an e-mail, with or without a password: the sign-in code
-  with nothing to type. `request` answers `null` for nobody and for an
-  inactive user alike; only the last link sent works; a link lives fifteen
-  minutes (`tokens.magicLink`) and is spent by its first `confirm`, which
-  proves the e-mail and still asks for an active second factor. Confirmed
-  from a `POST`, so a mail scanner that opens the link spends nothing.
-  **Breaking for an adapter: `TokenKind` gains `'magicLink'`**, which a
-  `CHECK` or a validator's enum must list.

package/docs/troubleshooting.md

@@ -75,7 +75,7 @@ How the messages are shaped:
 - [`TOKEN_STALE` — `<call>: the token was sent to an e-mail the user no longer has`](#token_stale--call-the-token-was-sent-to-an-e-mail-the-user-no-longer-has)
 - [`INVALID_CURSOR` — `<call>: this cursor was not minted by this store …`](#invalid_cursor--call-this-cursor-was-not-minted-by-this-store-or-was-minted-for-another-ordering-n-characters)
 - [`<call>: limit must be an integer of at least 1, or absent`](#call-limit-must-be-an-integer-of-at-least-1-or-absent)
-- [`UNSUPPORTED` — `collectExpired: store.sessions does not implement deleteExpiredSessions …`](#unsupported--collectexpired-storesessions-does-not-implement-deleteexpiredsessions--its-store-expires-sessions-on-its-own-or-implement-the-method)
+- [`UNSUPPORTED` — `collectExpired: store.sessions does not implement deleteExpiredSessions, nor store.tokens deleteExpiredTokens …`](#unsupported--collectexpired-storesessions-does-not-implement-deleteexpiredsessions-nor-storetokens-deleteexpiredtokens--their-stores-expire-records-on-their-own-or-implement-the-methods)
 - [`<call>: the <type> type does not sign in with a password …`](#call-the-type-type-does-not-sign-in-with-a-password--add-password--login--to-it)
 - [`authenticate()` answers `null` although a valid cookie was sent](#authenticate-answers-null-although-a-valid-cookie-was-sent)
 
@@ -151,7 +151,10 @@ How the messages are shaped:
 - [`list: the lookup of <type>.<relation> must answer an array of ids`](#list-the-lookup-of-typerelation-must-answer-an-array-of-ids)
 - [`grant: <type>.<relation> is read from <field>; there is nothing to store …`](#grant-typerelation-is-read-from-field-there-is-nothing-to-store--change-the-type-instead)
 - [`grant: <type>.<relation> is not held by <holder>`](#grant-typerelation-is-not-held-by-holder)
-- [Other `can:`, `list:`, `grant:` and `revoke:` messages](#other-can-list-grant-and-revoke-messages)
+- [`replace: the subjects must be an array`](#replace-the-subjects-must-be-an-array)
+- [Two `replace` calls at once leave the union of their adds](#two-replace-calls-at-once-leave-the-union-of-their-adds)
+- [`replace` leaves extra holders on a capped relation store](#replace-leaves-extra-holders-on-a-capped-relation-store)
+- [Other `can:`, `list:`, `grant:`, `revoke:` and `replace:` messages](#other-can-list-grant-revoke-and-replace-messages)
 - [`defineModel: …`](#definemodel-)
 
 **Subjects**
@@ -294,10 +297,10 @@ janus({ ..., hasher: scryptHasher(), verifiers: [legacyBcrypt] }); // not [scryp
 
 ### `janus: store.<slot> has no method <method>, which the port requires`
 
-Also: `janus: store.<slot> is missing`, `janus: store must be an object with users, sessions and tokens`, `janus: store.sessions.deleteExpiredSessions must be a function or absent`, `janus: store.users.findUsers must be a function or absent`.
+Also: `janus: store.<slot> is missing`, `janus: store must be an object with users, sessions and tokens`, `janus: store.sessions.deleteExpiredSessions must be a function or absent`, `janus: store.tokens.deleteExpiredTokens must be a function or absent`, `janus: store.users.findUsers must be a function or absent`.
 
 **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. Two methods are optional — `sessions.deleteExpiredSessions` and `users.findUsers` — and each is absent, or a function: a value in its place (`findUsers: true`, a property copied from a config) is a wiring mistake, not an absent capability.
+**Why:** `store` is `{ users, sessions, tokens }`, and each slot must answer every method of the port. Three methods are optional — `sessions.deleteExpiredSessions`, `tokens.deleteExpiredTokens` and `users.findUsers` — and each is absent, or a function: a value in its place (`findUsers: true`, a property copied from a config) is a wiring mistake, not an absent capability.
 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
@@ -625,7 +628,7 @@ const user = await auth.find(id); // null when there is nobody
 
 `StoreConflict` with `on: 'login'`, carrying `login` and `userType`. The login is not in the message, which never carries a value: an e-mail in a log line is personal data. Read it from `error.login`.
 
-**When:** `signUp`, `create`, or an `update` that changes the login, when another user of **the same type** holds it after normalisation (`Ada@Example.com` and `ada@example.com` collide by default).
+**When:** `signUp`, `create`, or an `update` that changes the login, when another user of **the same type** holds it after normalisation (`Ada@Example.com` and `ada@example.com` collide by default). `findOrCreate` rethrows it only when its re-read of the key still finds nobody — another login of the new user (its e-mail, beside a username) is taken; a race lost on the key itself answers `{ user, created: false }` instead.
 **Why:** the store's unique constraint refused the write. A login is unique per user type: one e-mail may hold a patient user and a staff user.
 **On `changeEmail.confirm`** the address was free when `changeEmail.send` asked — `send` never checks — and somebody took it before the link was used. The link is already spent and nothing was written: the user keeps their e-mail.
 **Fix:** answer 409. On `changeEmail.confirm`, tell the user the address is taken and ask for another with a new `changeEmail.send`. If two concurrent sign-ups with one login both succeed, the unique index is missing — with `@nxgt/janus-mongo`, run `syncMongoStores(db)`.
@@ -643,12 +646,19 @@ const user = await auth.get(id);
 await auth.update(user, { name }, { ifVersion: user.version });
 ```
 
-**From `verifyEmail.proveFirst`**, with no `ifVersion` of yours: the user
-was written between the read that found the e-mail never proved and the
+**From `verifyEmail.proveFirst`**, with no `ifVersion` of yours: either the
+`User` you passed carries an address that is no longer the user's (nothing is
+proved, on the first read already; a bare id skips this check and proves the
+current address), or the user was written between the read that found the e-mail never proved and the
 write that proves it — by the user, or by a second acceptance of the same
-invitation. Nothing was proved, though the sessions may already be revoked.
-Call it again: it reads the user anew, and answers `proved: false` when the
-other write proved the e-mail.
+invitation. `proveFirst` already retried once on a fresh read, so you see
+this error only when the user was written **again** during the retry, or when
+the write **changed the e-mail address** since the first read (or it is not
+the one the `User` you passed carries): the proof you hold is for the
+address you read. Nothing was proved, though
+the sessions may already be revoked. Read the user and check that their
+e-mail is still the invitation's address; if it is, call it again — it
+answers `proved: false` when another write proved the e-mail.
 
 **From `secondFactor.confirm`**, the message is the store's:
 `updateUser: expected version <n>, found <m>`.
@@ -694,8 +704,9 @@ does the first.
 
 `UserInvalidError`, carrying `issues` — each a `path` and a `message`.
 
-**When:** `signUp`, `create`, `update`, and `changeEmail.send`.
+**When:** `signUp`, `create`, `update`, `changeEmail.send`, and `findOrCreate`.
 **Why:** your schema refused the fields. `changeEmail.send` also answers it, with one issue at the e-mail field (`is the current e-mail of the user`), for an address equal to the user's current one once normalised: nothing is counted or issued; answer 400, or offer `verifyEmail.send` to prove the current one. `update` merges the patch over the stored fields and validates the whole, so the refusal can name a field the patch did not touch. An issue whose message is `set by janus, not by a request` means the input carried a field janus sets (`id`, `active`, `version`, …) and your schema let it through. An issue whose message is `holds a NUL character or a lone surrogate, which no store can keep` means a string — or, with `a key holds …`, an object key — carried `\u0000` or half of a surrogate pair: PostgreSQL refuses both, so janus refuses them on every adapter rather than answer `STORE_FAILED` on one. A key is reported by the path of the object holding it, never by the key itself — in janus's issues and in your schema's alike. An issue at your login field whose message is `normalises to a login that holds …` means your own `password.normalize` function produced such a login from a valid field: fix the function. On MongoDB or the memory store, a user written before janus refused these characters may already hold one: every `update` of that user is refused, whatever it patches, until the field is cleaned — patch it with a clean value in the same `update`.
+**`findOrCreate`** also answers it, with one issue at the login field (the e-mail field on a type with no password) and the message `is not the key findOrCreate was given`, when the validated input names another key than the one asked for; nothing is written. A username type given an e-mail nobody holds always meets it, since the input's username cannot be that e-mail. Fix: build the input from the same value as the key. A key that is not a string is answered before `input()` runs, with one issue at the empty path and the message `is not a string`: pass the login or the e-mail as a string.
 **Fix:** answer 400, field by field:
 
 ```ts
@@ -1058,11 +1069,11 @@ const page = await access.list(user, 'view', 'record', {
 });
 ```
 
-### `UNSUPPORTED` — `collectExpired: store.sessions does not implement deleteExpiredSessions — its store expires sessions on its own, or implement the method`
+### `UNSUPPORTED` — `collectExpired: store.sessions does not implement deleteExpiredSessions, nor store.tokens deleteExpiredTokens — their stores expire records on their own, or implement the methods`
 
 **When:** `auth.collectExpired()`.
-**Why:** the sessions store does not implement the optional `deleteExpiredSessions` — usually because it expires sessions itself (a MongoDB TTL index, a Redis `EXPIRE`).
-**Fix:** do not schedule `collectExpired` for that store. Expiry does not depend on it: the core compares `expiresAt` on every `authenticate`.
+**Why:** neither the sessions store implements the optional `deleteExpiredSessions` nor the tokens store the optional `deleteExpiredTokens` — usually because they expire records themselves (a MongoDB TTL index, a Redis `EXPIRE`). With one of the two, `collectExpired` collects that one and does not throw.
+**Fix:** do not schedule `collectExpired` for those stores. Expiry does not depend on it: the core compares `expiresAt` on every `authenticate` and on every redemption. If your database has no TTL, implement the methods ([adapters](guide/adapters.md#tokenstoredeleteexpiredtokens-optional)).
 
 ### `<call>: the <type> type does not sign in with a password — add password: { login } to it`
 
@@ -2009,22 +2020,40 @@ A `lookup` is your code and is not guarded: if it throws, `list()` rejects with
 
 ### `grant: <type>.<relation> is read from <field>; there is nothing to store — change the <type> instead`
 
-Also with `revoke:`.
+Also with `revoke:` and `replace:`.
 
-**When:** `access.grant(...)` or `access.revoke(...)` on a `fromField` relation.
+**When:** `access.grant(...)`, `access.revoke(...)` or `access.replace(...)` on a `fromField` relation.
 **Why:** that relation lives in the object's own data, not in a tuple.
 **Fix:** update the object — for example set `record.doctorId` — in your own database.
 
 ### `grant: <type>.<relation> is not held by <holder>`
 
-Also with `revoke:`.
+Also with `revoke:` and `replace:`.
 
-**When:** `access.grant(object, relation, subject)`.
+**When:** `access.grant(object, relation, subject)`, or any subject in the list of `access.replace(object, relation, subjects)`; nothing is written.
 **Why:** the model's relation does not admit that kind of subject: `members: ['staff']` refuses a `patient`, and refuses the subject set `team#members` unless it is listed.
 **Fix:** grant a subject the relation admits, or add the holder to the model: `members: ['staff', 'team#members']`.
 With `revoke:` on a tuple stored before the model stopped admitting it, the tuple already grants nothing; remove it through the store: `relations.write({ remove: [tuple] })`.
 
-### Other `can:`, `list:`, `grant:` and `revoke:` messages
+### `replace: the subjects must be an array`
+
+**When:** `access.replace(object, relation, subject)` with one subject instead of a list.
+**Why:** `replace` makes the list the only holders of the relation, so it takes the whole list.
+**Fix:** wrap the subject, `access.replace(team, 'members', [ada])`; `[]` empties the relation. See [`replace`](guide/permissions.md#replace).
+
+### Two `replace` calls at once leave the union of their adds
+
+**When:** two `replace` calls on the same object and relation run concurrently.
+**Why:** each reads the holders, then writes its own difference; they are not serialised, so both lists' additions can remain.
+**Fix:** serialise them yourself (a lock or a queue) when one list must win. See [`replace`](guide/permissions.md#replace).
+
+### `replace` leaves extra holders on a capped relation store
+
+**When:** you wrote a `RelationStore` adapter, and `access.replace(object, relation, subjects)` leaves holders you meant to remove, silently.
+**Why:** `replace` reads every holder of the relation through `findEntities` and `findSubjectSets` and removes those the list does not name. An adapter that caps either answer (a `LIMIT`, a first page) hides the rest from it, so they are never removed.
+**Fix:** answer every holder from both methods, unpaged, and never cap. The relation-store conformance suite is the place to check an adapter.
+
+### Other `can:`, `list:`, `grant:`, `revoke:` and `replace:` messages
 
 Each is a `TypeError` naming the call. TypeScript refuses most of them on the argument first.
 
@@ -2035,10 +2064,10 @@ Each is a `TypeError` naming the call. TypeScript refuses most of them on the ar
 | `<call>: the object must be { type, id, …its fields }` | `{ type: 'record', ...record }`. |
 | `<call>: the subject must be a user, or { type, id }` | Pass the user from `janus()`, or `{ type, id }`. `null` is anonymous and answers `false`. |
 | `<call>: the object id must be a non-empty string without @, # or parentheses` | Also for `the subject id`. Those characters belong to the tuple notation. |
-| `grant: the object id holds a NUL character or a lone surrogate, which no store can keep` | Also with `revoke:`, and for `the subject id`. PostgreSQL refuses `\u0000` and half a surrogate pair, so janus refuses them on every adapter: clean the id where it was read. `can()` answers `false` and `list()` an empty page for such an id instead — no tuple can name it. |
+| `grant: the object id holds a NUL character or a lone surrogate, which no store can keep` | Also with `revoke:` and `replace:`, and for `the subject id`. PostgreSQL refuses `\u0000` and half a surrogate pair, so janus refuses them on every adapter: clean the id where it was read. `can()` answers `false` and `list()` an empty page for such an id instead — no tuple can name it. |
 | `<call>: "<relation>" is not a relation of <type>, so <type>#<relation> is no subject set` | A subject set names a relation of its type: `{ type: 'team', id, relation: 'members' }`. |
 | `<call>: <type> is a user type the model does not declare as an object type, so <type>#<relation> is no subject set` | `setOf(user, relation)` names a relation on that user: declare the user type under `types` too, with that relation — see [permissions on a user](guide/permissions.md#permissions-on-a-user). The compiler refuses it first. |
-| `grant: "<relation>" is not a relation of <type>` | Grant a relation, never a permission. |
+| `grant: "<relation>" is not a relation of <type>` | Grant a relation, never a permission. Also with `revoke:` and `replace:` — `replace: "<relation>" is not a relation of <type>`, even for an empty list. |
 | `list: the type must be an object type of the model` | The third argument is a type name: `'record'`. |
 | `list: after must be the nextCursor of a page, or null` | Pass `nextCursor` back as it came. |
 

package/package.json

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