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

package/README.md

@@ -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`):

package/dist/index.cjs

@@ -153,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}`;
 }
@@ -686,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);
@@ -695,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);
       }
@@ -716,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 {
@@ -752,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);
@@ -1189,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({
@@ -1202,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(
@@ -1214,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));
@@ -1229,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;
@@ -1247,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);
@@ -1326,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],
@@ -1338,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";
@@ -1360,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,
@@ -1370,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(
@@ -1520,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;