@sanity-labs/client-fake-for-test 0.10.0 → 0.12.0

package/README.md

@@ -80,7 +80,7 @@ More patterns — passing the fake to code typed against `SanityClient`, asserti
 | Config | `config()` | Returns `{ projectId, dataset, perspective, token?, useProjectHostname }` |
 | Config | `withConfig({ projectId?, dataset?, perspective?, accessControl?, token?, useProjectHostname? })` | Sibling handle into the same multi-dataset registry; `token` binds a registered identity (see the token→identity registry below), `accessControl` rebinds it inline — the two are mutually exclusive; `useProjectHostname: false` mints a global-hosted sibling |
 | Perspectives | `raw` / `published` / `drafts` / release stacks | Per-client default or per-`fetch` override; draft/version layering with `_originalId` projection |
-| HTTP | `request({ url? \| uri? })` | Present **only** when the handle has an acting identity (`accessControl`, or a bound `token`). Serves `/users/me` (host-aware: project-scoped record on the project host, `globalUser` on a global-hosted handle), the configured ACL path, `/projects/<projectId>` (the project's members: `{ id, isRobot? }` rows, one per distinct resolved project user), and `/projects/<projectId>/users/<ids>` (project-user records with `id` + `sanityUserId`). Calling it without one throws a guidance error. |
+| HTTP | `request({ url? \| uri? })` | Present **only** when the handle has an acting identity (`accessControl`, or a bound `token`). Serves `/users/me` (host-aware: project-scoped record on the project host, `globalUser` on a global-hosted handle), the configured ACL path, `/projects/<projectId>` (the project's members: `{ id, isRobot?, roles? }` rows, one per distinct resolved project user), and `/projects/<projectId>/users/<ids>` (project-user records with `id` + `sanityUserId`). Calling it without one throws a guidance error. |
 
 #### Mutation return shapes
 
@@ -98,9 +98,9 @@ More patterns — passing the fake to code typed against `SanityClient`, asserti
 
 ### Gating writes — `mutationGuard`
 
-`createTestClient({ mutationGuard })` installs a pluggable write interceptor. It runs on every write through the document mutation API — `create` / `createOrReplace` / `createIfNotExists` / `patch` / `delete` and the equivalent `transaction()` / `mutate()` operations — _before_ the store changes, and **throws to reject** the write (the throw propagates out of the client call, like a real lake rejection). The release/version action API (`action`, `releases.*`, `createVersion`) is **not** intercepted.
+`createTestClient({ mutationGuard })` installs a pluggable write interceptor. It runs once for each document's net change in a commit through the document mutation API — `create` / `createOrReplace` / `createIfNotExists` / `patch` / `delete` and the equivalent `transaction()` / `mutate()` operations. Document publish and unpublish actions are expanded into their published and draft mutations. Release and version actions (`releases.*`, `createVersion`, and `unpublishVersion`) are not intercepted.
 
-The client owns the _seam_; the caller owns the _policy_. This is the hook a workflow test bench uses to enforce Content Lake **mutation guards** at the write path without re-implementing guard evaluation. Each call receives the before/after image (`before` is `null` on create, `after` is `null` on delete), the `action`, and the acting `identity`.
+The client owns the _seam_; the caller owns the _policy_. This is the hook a workflow test bench uses to enforce Content Lake **mutation guards** at the write path without re-implementing guard evaluation. Each call receives the original/final image (`before` is `null` on create, `after` is `null` on delete), the `action`, and the acting `identity`. Return every denying guard as `{ guardID, name? }`; the fake evaluates every net document mutation, aggregates the returned denials, deduplicates them by `guardID` in first-observed order, rolls back the commit, and throws a 403-shaped `GuardDeniedError` with `type: "guardDeniedError"` and `denials`. Other thrown callback errors propagate unchanged.
 
 ```ts
 const client = createTestClient({
@@ -108,13 +108,16 @@ const client = createTestClient({
   mutationGuard: ({ action, before, after }) => {
     // Freeze `body` once an article is locked.
     if (action === "update" && before?.locked && before.body !== after?.body) {
-      throw new Error("body is locked");
+      return [{ guardID: "_.guards.article-body", name: "Locked article body" }];
     }
   },
 });
 
 await client.patch("article-1").set({ title: "ok" }).commit(); // allowed
-await expect(client.patch("article-1").set({ body: "no" }).commit()).rejects.toThrow();
+await expect(client.patch("article-1").set({ body: "no" }).commit()).rejects.toMatchObject({
+  statusCode: 403,
+  type: "guardDeniedError",
+});
 ```
 
 > [!NOTE]
@@ -140,6 +143,10 @@ const bob = alice.withConfig({ token: "t-bob" });
 
 Register more identities after creation with `client.addIdentity(token, { user, grants })` — an upsert into the family-shared registry; already-bound siblings resolve lazily and pick the change up immediately. For a one-off identity without a registry, `withConfig({ accessControl })` still works (mutually exclusive with `token` in the same call).
 
+#### System-document grants
+
+User-issued writes to system document IDs beginning with `_.` require the `manage` permission. Ordinary `create` and `update` grants do not authorize these writes; add `manage` to identities whose tests intentionally create, replace, patch, delete, transact, mutate, publish, or unpublish system documents. The fake's internal release/version bookkeeping remains outside access-control interception.
+
 #### Dual-namespace identities: global vs project user ids
 
 In production the same token resolves to a **different project-scoped user id in every project** (what lake `identity()` returns) and **one account-global id** (what the global API host's `/users/me` returns); robot tokens carry a single id on every host. An identity can model that split with `globalUser` (served by `/users/me` on a `useProjectHostname: false` handle) and `usersByProject` (per-project records; the handle's project falls back to `user`):
@@ -162,6 +169,8 @@ await client.withConfig({ useProjectHostname: false }).request({ uri: "/users/me
 await client.request({ uri: "/projects/alpha/users/pAlpha" }); // { id: "pAlpha", sanityUserId: "gSnorre", ... } (ProjectUserRecord)
 ```
 
+The project directory endpoint (`/projects/<projectId>`) returns each resolved project member's `id`, project-specific `roles`, and robot marker. Roles are served in canonical order, and duplicate-token agreement ignores role and property order. Registering two tokens with the same project user id is supported when their served member records agree; conflicting roles fail the request instead of making the result depend on registration order.
+
 Grant-filter and mutation-guard `identity()` stay bound to the **project-scoped** record, matching the lake. Identities without `globalUser` serve one record everywhere — the production robot-token shape.
 
 ### Test-only helpers (not on real `SanityClient`)

package/dist/index.cjs

@@ -64,6 +64,28 @@ function defaultAclPath(projectId, dataset) {
 function projectUserOf(identity, projectId) {
   return identity.usersByProject?.[projectId] ?? identity.user;
 }
+function consistentProjectRecords(args) {
+  const byId = /* @__PURE__ */ new Map();
+  for (const record of args.records) {
+    const existing = byId.get(record.id);
+    if (existing !== void 0 && JSON.stringify(existing) !== JSON.stringify(record))
+      throw fakeError(
+        `request(): two registered identities resolve to project user "${record.id}" in project "${args.projectId}" with different records. The project records cannot be served unambiguously \u2014 fix the identity registrations so duplicate ids carry identical records.`
+      );
+    byId.set(record.id, record);
+  }
+  return byId;
+}
+function canonicalProjectRoles(roles) {
+  return roles.map((role) => ({
+    name: role.name,
+    ...role.title !== void 0 ? { title: role.title } : {},
+    ...role.description !== void 0 ? { description: role.description } : {}
+  })).toSorted((left, right) => {
+    const leftKey = JSON.stringify(left), rightKey = JSON.stringify(right);
+    return leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0;
+  });
+}
 function serveProjectUsers(args) {
   const { requestedIds, pathProjectId, identities } = args, toRecord = (identity) => {
     const projectUser = projectUserOf(identity, pathProjectId);
@@ -73,43 +95,37 @@ function serveProjectUsers(args) {
       displayName: projectUser.name ?? projectUser.id,
       ...projectUser.email !== void 0 ? { email: projectUser.email } : {}
     };
-  }, byId = /* @__PURE__ */ new Map();
-  for (const identity of identities) {
-    const resolvedId = projectUserOf(identity, pathProjectId).id, existing = byId.get(resolvedId);
-    if (existing !== void 0 && JSON.stringify(toRecord(existing)) !== JSON.stringify(toRecord(identity)))
-      throw fakeError(
-        `request(): two registered identities resolve to project user "${resolvedId}" in project "${pathProjectId}" with different records. The directory cannot answer unambiguously \u2014 fix the identity registrations so duplicate ids carry identical records.`
-      );
-    byId.set(resolvedId, identity);
-  }
-  const ids = requestedIds.split(","), [firstId] = ids;
+  }, byId = consistentProjectRecords({
+    projectId: pathProjectId,
+    records: identities.map(toRecord)
+  }), ids = requestedIds.split(","), [firstId] = ids;
   if (ids.length === 1 && firstId !== void 0) {
-    const identity = byId.get(firstId);
-    if (identity === void 0)
+    const record = byId.get(firstId);
+    if (record === void 0)
       throw Object.assign(
         fakeError(
           `request(): no registered identity resolves to project user "${firstId}" in project "${pathProjectId}". Register it via createTestClient({ identities }) or addIdentity().`
         ),
         { statusCode: 404 }
       );
-    return toRecord(identity);
+    return record;
   }
   return ids.flatMap((id) => {
-    const identity = byId.get(id);
-    return identity === void 0 ? [] : [toRecord(identity)];
+    const record = byId.get(id);
+    return record === void 0 ? [] : [record];
   });
 }
 const PROJECT_USERS_PATH = /^\/projects\/([^/]+)\/users\/([^/]+)$/, PROJECT_PATH = /^\/projects\/([^/]+)$/;
 function serveProject(args) {
-  const ids = /* @__PURE__ */ new Set();
-  for (const identity of args.identities)
-    ids.add(projectUserOf(identity, args.pathProjectId).id);
-  return {
-    members: [...ids].map((id) => ({
-      id,
-      ...id.startsWith("p-") ? { isRobot: !0 } : {}
-    }))
-  };
+  const records = args.identities.map((identity) => {
+    const projectUser = projectUserOf(identity, args.pathProjectId);
+    return {
+      id: projectUser.id,
+      ...projectUser.id.startsWith("p-") ? { isRobot: !0 } : {},
+      ...projectUser.roles !== void 0 ? { roles: canonicalProjectRoles(projectUser.roles) } : {}
+    };
+  });
+  return { members: [...consistentProjectRecords({ projectId: args.pathProjectId, records }).values()] };
 }
 function makeRequestImpl(ctx) {
   const { getAccess, projectId, dataset, useProjectHostname, listIdentities } = ctx;
@@ -137,6 +153,48 @@ function makeRequestImpl(ctx) {
     );
   };
 }
+class GuardDeniedError extends Error {
+  statusCode = 403;
+  type = "guardDeniedError";
+  denials;
+  details;
+  response;
+  constructor(denials) {
+    const unique = uniqueDenials(denials);
+    super(`Mutation denied by guard(s) [${unique.map((denial) => denial.guardID).join(", ")}]`), this.name = "GuardDeniedError", this.denials = unique, this.details = { type: this.type, denials: unique }, this.response = {
+      body: { error: this.details },
+      url: "memory://client-fake-for-test/data/mutate",
+      method: "POST",
+      headers: {},
+      statusCode: this.statusCode,
+      statusMessage: "Forbidden"
+    };
+  }
+}
+function uniqueDenials(denials) {
+  const seen = /* @__PURE__ */ new Set();
+  return denials.filter((denial) => seen.has(denial.guardID) ? !1 : (seen.add(denial.guardID), !0));
+}
+function mutationContext(images) {
+  const { before, after } = images;
+  if (before !== after)
+    return before === void 0 ? { action: "create", before: null, after: after ?? null } : after === void 0 ? { action: "delete", before, after: null } : { action: "update", before, after };
+}
+function mutationContexts(images) {
+  return [...images].flatMap((image) => {
+    const context = mutationContext(image);
+    return context === void 0 ? [] : [context];
+  });
+}
+async function enforceMutationGuards(guard, contexts) {
+  if (guard === void 0) return;
+  const denials = [];
+  for (const context of contexts) {
+    const denied = await guard(context);
+    denied !== void 0 && denials.push(...denied);
+  }
+  if (denials.length > 0) throw new GuardDeniedError(denials);
+}
 function describeType(value) {
   return value === null ? "null" : Array.isArray(value) ? "an array" : `a ${typeof value}`;
 }
@@ -670,7 +728,7 @@ async function applyAction(store, action, hooks) {
       const published = store.get(action.publishedId);
       requireRevisionMatch(action.draftId, draft._rev, action.ifDraftRevisionId), requireRevisionMatch(action.publishedId, published?._rev, action.ifPublishedRevisionId);
       const promoted = promote({ ...draft, _id: action.publishedId });
-      return published !== void 0 && (promoted._createdAt = published._createdAt), await hooks?.gate?.(promoted, published === void 0 ? "create" : "update"), await hooks?.guard?.("publish", published ?? null, promoted), store.put(promoted), store.remove(action.draftId), { transactionId: cryptoRandomKey() };
+      return published !== void 0 && (promoted._createdAt = published._createdAt), await hooks?.gate?.(promoted, published === void 0 ? "create" : "update"), store.put(promoted), store.remove(action.draftId), { transactionId: cryptoRandomKey() };
     }
     case "sanity.action.document.unpublish": {
       requireDraftOf(action);
@@ -679,7 +737,7 @@ async function applyAction(store, action, hooks) {
         throw fakeError(
           `Cannot unpublish "${action.publishedId}": no published document with that _id exists. document.unpublish retracts a live published document into "${action.draftId}".`
         );
-      if (await hooks?.gate?.(published, "update"), await hooks?.guard?.("unpublish", published, null), store.get(action.draftId) === void 0) {
+      if (await hooks?.gate?.(published, "update"), store.get(action.draftId) === void 0) {
         const draft = promote({ ...published, _id: action.draftId });
         draft._createdAt = published._createdAt, store.put(draft);
       }
@@ -700,7 +758,7 @@ function requireRevisionMatch(documentId, actualRev, expectedRev) {
     );
 }
 async function applyActions(store, actions, hooks) {
-  const list = Array.isArray(actions) ? actions : [actions], snapshot = /* @__PURE__ */ new Map(), remember = (id) => {
+  const list = Array.isArray(actions) ? actions : [actions], snapshot = /* @__PURE__ */ new Map(), guardedIds = /* @__PURE__ */ new Set(), remember = (id) => {
     snapshot.has(id) || snapshot.set(id, store.get(id));
   };
   try {
@@ -736,13 +794,18 @@ async function applyActions(store, actions, hooks) {
           remember(a.versionId);
           break;
         case "sanity.action.document.publish":
+          remember(a.draftId), remember(a.publishedId), guardedIds.add(a.publishedId), guardedIds.add(a.draftId);
+          break;
         case "sanity.action.document.unpublish":
-          remember(a.draftId), remember(a.publishedId);
+          remember(a.draftId), remember(a.publishedId), guardedIds.add(a.draftId), guardedIds.add(a.publishedId);
           break;
       }
       last = await applyAction(store, a, hooks);
     }
-    return last;
+    const contexts = mutationContexts(
+      [...guardedIds].map((id) => ({ before: snapshot.get(id), after: store.get(id) }))
+    );
+    return await hooks?.guard?.(contexts), last;
   } catch (err) {
     for (const [id, doc] of snapshot)
       doc === void 0 ? store.remove(id) : store.put(doc);
@@ -1173,11 +1236,17 @@ function makeHandle(handleArgs) {
     access !== void 0 && await enforceWriteAccess({
       document,
       grants: access.grants,
-      permission,
+      permission: document._id !== void 0 && isSystemId(document._id) ? "manage" : permission,
       userId: access.currentUser.id
     });
-  }, guardGate = async (action, before, after) => {
-    mutationGuard !== void 0 && await mutationGuard({ action, before, after, identity: activeAccess()?.currentUser.id });
+  }, guardGate = async (contexts) => {
+    const identity = activeAccess()?.currentUser.id;
+    await enforceMutationGuards(
+      mutationGuard,
+      contexts.map((context) => ({ ...context, identity }))
+    );
+  }, guardOne = async (action, before, after) => {
+    await guardGate([{ action, before, after }]);
   }, canRead = async (document) => {
     const access = activeAccess();
     return access === void 0 ? !0 : canAccess({
@@ -1186,7 +1255,7 @@ function makeHandle(handleArgs) {
       permission: "read",
       userId: access.currentUser.id
     });
-  }, applyPatch = async (documentId, ops, ifRev) => {
+  }, applyPatch = async (documentId, ops, ifRev, options = {}) => {
     const existing = store.get(documentId);
     if (existing === void 0)
       throw fakeError(
@@ -1198,7 +1267,7 @@ function makeHandle(handleArgs) {
       _rev: cryptoRandomKey(),
       _updatedAt: now
     };
-    return await guardGate("update", existing, next), store.put(next), next;
+    return options.evaluateGuard !== !1 && await guardOne("update", existing, next), store.put(next), next;
   }, applyTransaction = async (mutations, txnOptions) => {
     const transactionId = txnOptions?.transactionId ?? cryptoRandomKey(), snapshot = /* @__PURE__ */ new Map(), touchedIds = [], operations = [], remember = (id) => {
       snapshot.has(id) || snapshot.set(id, store.get(id));
@@ -1213,17 +1282,13 @@ function makeHandle(handleArgs) {
               throw fakeError(
                 `create() failed: a document with _id "${promoted._id}" already exists in dataset "${projectId}:${dataset}". Use createOrReplace() to overwrite it, or createIfNotExists() to leave the existing one untouched.`
               );
-            await gate(promoted, "create"), await guardGate("create", null, promoted), store.put(promoted), touchedIds.push(promoted._id), operations.push({ id: promoted._id, operation: "create" });
+            await gate(promoted, "create"), store.put(promoted), touchedIds.push(promoted._id), operations.push({ id: promoted._id, operation: "create" });
             break;
           }
           case "createOrReplace": {
             remember(mut.doc._id);
             const promoted = promote2(mut.doc), existing = store.get(promoted._id);
-            await gate(existing ?? promoted, existing !== void 0 ? "update" : "create"), await guardGate(
-              existing !== void 0 ? "update" : "create",
-              existing ?? null,
-              promoted
-            );
+            await gate(existing ?? promoted, existing !== void 0 ? "update" : "create");
             const wasPresent = existing !== void 0;
             store.put(promoted), touchedIds.push(promoted._id), operations.push({ id: promoted._id, operation: wasPresent ? "update" : "create" });
             break;
@@ -1231,21 +1296,25 @@ function makeHandle(handleArgs) {
           case "createIfNotExists": {
             if (remember(mut.doc._id), store.get(mut.doc._id) === void 0) {
               const promoted = promote2(mut.doc);
-              await gate(promoted, "create"), await guardGate("create", null, promoted), store.put(promoted), touchedIds.push(promoted._id), operations.push({ id: promoted._id, operation: "create" });
+              await gate(promoted, "create"), store.put(promoted), touchedIds.push(promoted._id), operations.push({ id: promoted._id, operation: "create" });
             }
             break;
           }
           case "delete": {
             remember(mut.id);
             const existing = store.get(mut.id);
-            existing !== void 0 && await gate(existing, "update"), existing !== void 0 && await guardGate("delete", existing, null), store.remove(mut.id) && (touchedIds.push(mut.id), operations.push({ id: mut.id, operation: "delete" }));
+            existing !== void 0 && await gate(existing, "update"), store.remove(mut.id) && (touchedIds.push(mut.id), operations.push({ id: mut.id, operation: "delete" }));
             break;
           }
           case "patch": {
-            remember(mut.documentId), await applyPatch(mut.documentId, mut.ops, mut.ifRev), touchedIds.push(mut.documentId), operations.push({ id: mut.documentId, operation: "update" });
+            remember(mut.documentId), await applyPatch(mut.documentId, mut.ops, mut.ifRev, { evaluateGuard: !1 }), touchedIds.push(mut.documentId), operations.push({ id: mut.documentId, operation: "update" });
             break;
           }
         }
+      const contexts = mutationContexts(
+        [...snapshot].map(([id, before]) => ({ before, after: store.get(id) }))
+      );
+      await guardGate(contexts);
     } catch (error) {
       for (const [id, doc] of snapshot)
         doc === void 0 ? store.remove(id) : store.put(doc);
@@ -1310,7 +1379,7 @@ function makeHandle(handleArgs) {
           `create() failed: a document with _id "${doc._id}" already exists in dataset "${projectId}:${dataset}". Use createOrReplace() to overwrite it, or createIfNotExists() to leave the existing one untouched.`
         );
       const promoted = promote2(doc);
-      await gate(promoted, "create"), await guardGate("create", null, promoted);
+      await gate(promoted, "create"), await guardOne("create", null, promoted);
       const transactionId = opts?.transactionId ?? cryptoRandomKey();
       return opts?.dryRun !== !0 && (store.put(promoted), record(transactionId, [{ kind: "create", doc }], opts?.tag)), writeResult(
         [promoted],
@@ -1322,7 +1391,7 @@ function makeHandle(handleArgs) {
     createOrReplace: (doc, opts) => serializeWrite(backend, async () => {
       checkRevision(doc._id, opts?.ifRevisionId);
       const promoted = promote2(doc), existing = store.get(doc._id);
-      await gate(existing ?? promoted, existing !== void 0 ? "update" : "create"), await guardGate(existing !== void 0 ? "update" : "create", existing ?? null, promoted);
+      await gate(existing ?? promoted, existing !== void 0 ? "update" : "create"), await guardOne(existing !== void 0 ? "update" : "create", existing ?? null, promoted);
       const transactionId = opts?.transactionId ?? cryptoRandomKey();
       opts?.dryRun !== !0 && (store.put(promoted), record(transactionId, [{ kind: "createOrReplace", doc }], opts?.tag));
       const operation = existing !== void 0 ? "update" : "create";
@@ -1344,7 +1413,7 @@ function makeHandle(handleArgs) {
           opts
         );
       const promoted = promote2(doc);
-      return await gate(promoted, "create"), await guardGate("create", null, promoted), opts?.dryRun !== !0 && (store.put(promoted), record(transactionId, [{ kind: "createIfNotExists", doc }], opts?.tag)), writeResult(
+      return await gate(promoted, "create"), await guardOne("create", null, promoted), opts?.dryRun !== !0 && (store.put(promoted), record(transactionId, [{ kind: "createIfNotExists", doc }], opts?.tag)), writeResult(
         [promoted],
         [{ id: promoted._id, operation: "create" }],
         transactionId,
@@ -1354,7 +1423,7 @@ function makeHandle(handleArgs) {
     delete: (id, opts) => serializeWrite(backend, async () => {
       checkRevision(id, opts?.ifRevisionId);
       const existing = store.get(id);
-      existing !== void 0 && await gate(existing, "update"), existing !== void 0 && await guardGate("delete", existing, null);
+      existing !== void 0 && await gate(existing, "update"), existing !== void 0 && await guardOne("delete", existing, null);
       const transactionId = opts?.transactionId ?? cryptoRandomKey();
       let removed = existing;
       return opts?.dryRun !== !0 && (removed = store.remove(id), removed !== void 0 && record(transactionId, [{ kind: "delete", id }], opts?.tag)), opts?.returnDocuments === void 0 && opts?.returnFirst === void 0 ? removed !== void 0 ? { _id: id } : null : formatMutationResult(
@@ -1504,6 +1573,7 @@ function makeHandle(handleArgs) {
   });
 }
 exports.ERR_PREFIX = ERR_PREFIX;
+exports.GuardDeniedError = GuardDeniedError;
 exports.SUPPORTED_SURFACE = SUPPORTED_SURFACE;
 exports.UNSUPPORTED_MEMBERS = UNSUPPORTED_MEMBERS;
 exports.WriteAccessDeniedError = WriteAccessDeniedError;