@nxgt/janus 0.23.1 → 0.24.0

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.

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 |

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

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

@@ -76,6 +76,31 @@ Nothing yet.
 The last ten, newest first, each with the version it came in. Everything
 before is in the [CHANGELOG](../CHANGELOG.md).
 
+- **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

@@ -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**
@@ -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
@@ -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.24.0",
 	"description": "Embeddable, type-safe identities and permissions: bring your own database",
 	"license": "MIT",
 	"type": "module",