@fabricorg/platform-host 7.1.2 → 7.2.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @fabricorg/platform-host
 
+## 7.2.0
+
+### Minor Changes
+
+- 715e920: `tenantIsolationChecks()` and `runTenantIsolationChecks(subject)`: six checks proving that scope is a key on every read, write, claim, and completion. An invocation cannot be read, executed, or completed by callback under another tenant's scope; the same idempotency key in two tenants is two invocations; a tenant's event stream carries no other tenant's events; a tenant-scoped worker claims nothing of another's; and, when the subject lends a governed read, a viewer in the other tenant sees none of ours. Each check carries a positive control, so a store or host that does nothing fails it, and each has a teeth test against the flaw it names. The claim check uses a probe space of its own and retires its probe row, so a backlog cannot hide a tenant-ignoring claim and a live worker never runs the probe. Rows a lent read returns must carry their `tenantId`.
+
 ## 7.1.2
 
 ### Patch Changes

package/README.md

@@ -300,6 +300,15 @@ migration 3 adds the `pending_completion`, `external_completion`, and `completio
 a partial index on the due instant the overdue sweep uses; the due instant is a real column because a
 cast in an index expression is not immutable and PostgreSQL refuses it.
 
+## Tenant isolation
+
+`tenantIsolationChecks()` and `runTenantIsolationChecks(subject)` prove that scope is a key on every
+read, write, claim, and completion: an invocation is invisible, inert, and uncompletable under another
+tenant's scope; the same idempotency key in two tenants is two invocations; event streams carry only
+their own tenant's events; a tenant-scoped worker claims nothing of another's; and a governed read
+the subject lends shows the other tenant none of ours. The subject supplies a host, a recoverable
+store, a registered action, and two scopes in different tenants.
+
 ## Runtime observability and health
 
 Platform Host exposes vendor-neutral lifecycle telemetry through the optional `telemetry` sink on

package/dist/index.cjs

@@ -715,24 +715,24 @@ function createGovernedActionHost(options) {
     }
     const action = actionResolver(invocation.actionId);
     if (!action) {
-      return fail(invocation, "failed", `Unknown action: ${invocation.actionId}`);
+      return fail2(invocation, "failed", `Unknown action: ${invocation.actionId}`);
     }
     if (action.kind === "saga") {
-      return fail(
+      return fail2(
         invocation,
         "failed",
         `Saga action ${invocation.actionId} requires a durable PlatformActionDispatcher and cannot execute as an atomic Host action.`
       );
     }
     if (resumingRunningInvocation && invocation.attemptCount === 0 && !invocation.leaseOwner && !action.idempotent) {
-      return fail(
+      return fail2(
         invocation,
         "failed",
         `Interrupted inline action ${invocation.actionId} is not declared idempotent; manual reconciliation is required.`
       );
     }
     if (invocation.attemptCount > 1 && !action.idempotent) {
-      return fail(
+      return fail2(
         invocation,
         "failed",
         `Interrupted action ${invocation.actionId} is not declared idempotent; manual reconciliation is required.`
@@ -756,12 +756,12 @@ function createGovernedActionHost(options) {
       const parsed = action.schema.safeParse(invocation.parameters);
       if (!parsed.success) {
         const message = parsed.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ");
-        return fail(invocation, "validation_failed", message);
+        return fail2(invocation, "validation_failed", message);
       }
       if (options.resolveMutationGovernance && !invocation.mutationFootprint) {
         const governanceStore2 = asGovernanceStore(options.store);
         if (!governanceStore2) {
-          return fail(invocation, "failed", "The configured mutation-governance resolver requires a governance-capable store.");
+          return fail2(invocation, "failed", "The configured mutation-governance resolver requires a governance-capable store.");
         }
         const context = await options.resolveMutationGovernance({
           actionInvocationId,
@@ -779,7 +779,7 @@ function createGovernedActionHost(options) {
         const hitlParameters = isRecord(parsed.data) ? parsed.data : invocation.parameters;
         const approvalStore = asApprovalStore(options.store);
         if (!approvalStore) {
-          return fail(
+          return fail2(
             invocation,
             "failed",
             "The configured HITL evaluator requires a store with approval persistence support."
@@ -810,7 +810,7 @@ function createGovernedActionHost(options) {
           );
         }
         if (invocation.hitlRoute === "rejected") {
-          return fail(
+          return fail2(
             invocation,
             "failed",
             `HITL rejected: ${invocation.hitlReason ?? "no reason provided"}`
@@ -829,7 +829,7 @@ function createGovernedActionHost(options) {
       const authorizationInput = toAuthorizationInput(action, invocation);
       const executionReason = executionReasonOverride ?? (invocation.attemptCount > 1 || resumingRunningInvocation && invocation.attemptCount === 0 ? "recovery" : invocation.executionReason ?? "initial");
       if (!await options.authorization.checkEntitlement(authorizationInput)) {
-        return fail(
+        return fail2(
           invocation,
           "failed",
           `Module "${action.namespace}" is no longer enabled for tenant ${tenantId}`
@@ -869,7 +869,7 @@ function createGovernedActionHost(options) {
       }) : await options.authorization.authorize(authorizationInput);
       if (!executionAuthorized) {
         if (!action.execution) {
-          return fail(invocation, "failed", `Actor ${invocation.actorId} is not authorized to execute action ${action.actionId}`);
+          return fail2(invocation, "failed", `Actor ${invocation.actorId} is not authorized to execute action ${action.actionId}`);
         }
         const reconciliation = {
           kind: "authorization_denied",
@@ -919,12 +919,12 @@ function createGovernedActionHost(options) {
           subjectId: actionInvocationId,
           payload: { actionId: action.actionId, policyId: aggregate.policyId, reason }
         }, `compliance:${aggregate.policyId}`);
-        return fail(invocation, "blocked_by_policy", reason);
+        return fail2(invocation, "blocked_by_policy", reason);
       }
       if (options.resolvePolicyObligations) {
         const governanceStore2 = asGovernanceStore(options.store);
         if (!governanceStore2) {
-          return fail(invocation, "failed", "Policy obligations require a governance-capable store.");
+          return fail2(invocation, "failed", "Policy obligations require a governance-capable store.");
         }
         const existing = await governanceStore2.listPolicyObligations(actionInvocationId, tenantId, spaceId);
         if (existing.length === 0) {
@@ -1039,7 +1039,7 @@ function createGovernedActionHost(options) {
         data = executed.data;
         domainEvents = executed.domainEvents;
       } catch (error) {
-        return fail(invocation, "failed", errorMessage(error));
+        return fail2(invocation, "failed", errorMessage(error));
       }
       let pendingHandoff = invocation.pendingCompletion;
       for (const [stepIndex, step] of (action.adapterSteps ?? []).entries()) {
@@ -1219,7 +1219,7 @@ function createGovernedActionHost(options) {
               subjectId: adapterEventSubject.subjectId,
               payload: { adapterType: step.adapterType, operation: step.operation }
             }, `adapter:${stepIndex}:failed`);
-            return fail(invocation, "failed", result2.error ?? "Adapter failed");
+            return fail2(invocation, "failed", result2.error ?? "Adapter failed");
           }
           const resultRecord = result2;
           const output = isRecord(resultRecord.output) ? resultRecord.output : Object.fromEntries(
@@ -1323,7 +1323,7 @@ function createGovernedActionHost(options) {
             error: message,
             updatedAt: now()
           });
-          return fail(invocation, "failed", message);
+          return fail2(invocation, "failed", message);
         } finally {
           if (adapterDeadlineTimer) clearTimeout(adapterDeadlineTimer);
         }
@@ -1345,7 +1345,7 @@ function createGovernedActionHost(options) {
             }
             return withConsistency({ actionInvocationId, status: "reconciliation_required", error, pendingCompletion: pendingHandoff }, action.actionId);
           }
-          return fail(invocation, "failed", message);
+          return fail2(invocation, "failed", message);
         }
       }
       const result = withoutPrivateHostFields(data, eventResultFields);
@@ -1418,7 +1418,7 @@ function createGovernedActionHost(options) {
       };
     } catch (error) {
       if (error instanceof RecoverableFinalizationError) throw error;
-      return fail(invocation, "failed", errorMessage(error));
+      return fail2(invocation, "failed", errorMessage(error));
     }
   }
   async function resumeApprovedInvocation(actionInvocationId, tenantId, spaceId, decision) {
@@ -1437,7 +1437,7 @@ function createGovernedActionHost(options) {
       };
     }
     const action = actionResolver(invocation.actionId);
-    if (!action) return fail(invocation, "failed", `Unknown action: ${invocation.actionId}`);
+    if (!action) return fail2(invocation, "failed", `Unknown action: ${invocation.actionId}`);
     const approvalAuthorizationInput = toAuthorizationInput(action, {
       tenantId,
       spaceId,
@@ -1590,7 +1590,7 @@ function createGovernedActionHost(options) {
       await (transaction ?? options.store).appendEvent(envelope);
     }
   }
-  async function fail(invocation, status, error) {
+  async function fail2(invocation, status, error) {
     await persistInvocation(invocation, { status, error });
     return {
       actionInvocationId: invocation.id,
@@ -3564,6 +3564,181 @@ function createDurableSagaParentLifecycle(options) {
   };
 }
 
+// src/tenant-isolation.ts
+function fail(message) {
+  throw new Error(message);
+}
+function submitInput(subject, scope, idempotencyKey) {
+  return {
+    actionId: subject.actionId,
+    parameters: subject.parameters ?? {},
+    tenantId: scope.tenantId,
+    spaceId: scope.spaceId,
+    actorId: scope.actorId,
+    actorType: scope.actorType,
+    idempotencyKey
+  };
+}
+function tenantIsolationChecks() {
+  return [
+    {
+      id: "fabric.tenancy.invocation-scoped-read.v1",
+      async run(subject) {
+        await subject.reset?.();
+        if (subject.ours.tenantId === subject.theirs.tenantId) fail("the two scopes must be in different tenants");
+        const ours = await subject.host.submitAction(submitInput(subject, subject.ours, "iso:read"));
+        const crossRead = await subject.store.getActionInvocation(ours.actionInvocationId, subject.theirs.tenantId, subject.theirs.spaceId);
+        if (crossRead !== void 0) fail("an invocation was readable under another tenant's scope");
+        const shape = (record) => JSON.stringify({ status: record?.status, result: record?.result, error: record?.error, attemptCount: record?.attemptCount, updatedAt: record?.updatedAt });
+        const before = await subject.store.getActionInvocation(ours.actionInvocationId, subject.ours.tenantId, subject.ours.spaceId);
+        if (!before) fail("our own invocation was not readable under our scope, so the check proves nothing");
+        const untouched = shape(before);
+        let crossExecute;
+        try {
+          crossExecute = await subject.host.executeInvocation(ours.actionInvocationId, subject.theirs.tenantId, subject.theirs.spaceId);
+        } catch {
+          crossExecute = void 0;
+        }
+        if (crossExecute !== void 0) fail("an invocation was executable under another tenant's scope");
+        const after = await subject.store.getActionInvocation(ours.actionInvocationId, subject.ours.tenantId, subject.ours.spaceId);
+        if (untouched !== shape(after)) fail("an execution attempted under another tenant's scope changed our invocation");
+        return ["invocation readable under our scope, invisible and untouched under the other tenant's"];
+      }
+    },
+    {
+      id: "fabric.tenancy.idempotency-key-scoped.v1",
+      async run(subject) {
+        await subject.reset?.();
+        const ours = await subject.host.submitAction(submitInput(subject, subject.ours, "iso:shared-key"));
+        const again = await subject.host.submitAction(submitInput(subject, subject.ours, "iso:shared-key"));
+        if (ours.actionInvocationId !== again.actionInvocationId) fail("the same idempotency key in one tenant produced two invocations, so the key is not doing anything and the check proves nothing");
+        const theirs = await subject.host.submitAction(submitInput(subject, subject.theirs, "iso:shared-key"));
+        if (ours.actionInvocationId === theirs.actionInvocationId) fail("the same idempotency key in two tenants resolved to one invocation");
+        return ["one idempotency key: one invocation within a tenant, two across tenants"];
+      }
+    },
+    {
+      id: "fabric.tenancy.events-scoped.v1",
+      async run(subject) {
+        await subject.reset?.();
+        const ours = await subject.host.submitAction(submitInput(subject, subject.ours, "iso:events"));
+        const theirEvents = await subject.store.listEvents(subject.theirs.tenantId, subject.theirs.spaceId);
+        const leaked = theirEvents.filter((event) => event.tenantId === subject.ours.tenantId || event.actionInvocationId === ours.actionInvocationId);
+        if (leaked.length > 0) fail(`${leaked.length} of our events appeared in the other tenant's stream`);
+        const ourEvents = await subject.store.listEvents(subject.ours.tenantId, subject.ours.spaceId);
+        if (!ourEvents.some((event) => event.actionInvocationId === ours.actionInvocationId)) fail("our own stream does not carry the event we just caused, so the check proves nothing");
+        if (ourEvents.some((event) => event.tenantId !== subject.ours.tenantId)) fail("another tenant's event appeared in our stream");
+        return ["event streams carry their own tenant's events and only those"];
+      }
+    },
+    {
+      id: "fabric.tenancy.worker-claim-scoped.v1",
+      async run(subject) {
+        await subject.reset?.();
+        const probeSpace = `iso-probe-${Date.now()}`;
+        const created = await subject.store.createActionInvocation({
+          id: `iso_pending_${Date.now()}`,
+          tenantId: subject.ours.tenantId,
+          spaceId: probeSpace,
+          actionId: subject.actionId,
+          actionVersion: 1,
+          actorId: subject.ours.actorId,
+          actorType: subject.ours.actorType,
+          status: "pending",
+          parameters: subject.parameters ?? {},
+          result: {},
+          correlationId: `iso-corr-${Date.now()}`
+        });
+        try {
+          const theirs = await subject.store.claimActionInvocations({
+            workerId: "iso-worker",
+            leaseDurationMs: 1e3,
+            limit: 1e3,
+            tenantId: subject.theirs.tenantId,
+            spaceId: probeSpace
+          });
+          if (theirs.some((row) => row.id === created.id)) fail("a worker scoped to another tenant claimed our pending invocation");
+          const ours = await subject.store.claimActionInvocations({
+            workerId: "iso-worker",
+            leaseDurationMs: 1e3,
+            limit: 1e3,
+            tenantId: subject.ours.tenantId,
+            spaceId: probeSpace
+          });
+          if (!ours.some((row) => row.id === created.id)) fail("a worker scoped to our own tenant did not claim our pending invocation, so the check proves nothing");
+        } finally {
+          await subject.store.updateActionInvocation(created.id, subject.ours.tenantId, probeSpace, {
+            status: "failed",
+            error: "tenant isolation probe; never executed"
+          });
+        }
+        return ["tenant-scoped claim takes our work and leaves other tenants' alone"];
+      }
+    },
+    {
+      id: "fabric.tenancy.completion-scoped.v1",
+      async run(subject) {
+        await subject.reset?.();
+        const ours = await subject.host.submitAction(submitInput(subject, subject.ours, "iso:complete"));
+        let outcome;
+        try {
+          await subject.host.completeExternalInvocation(ours.actionInvocationId, subject.theirs.tenantId, subject.theirs.spaceId, {
+            externalReference: "iso-ref",
+            outcome: "completed",
+            observedAt: (/* @__PURE__ */ new Date()).toISOString()
+          });
+          outcome = "accepted";
+        } catch (error) {
+          const refusal = error.refusal;
+          outcome = refusal ?? "threw";
+        }
+        if (outcome !== "not_found") fail(`a completion under another tenant's scope was ${outcome}; it must be refused as not_found`);
+        let mine;
+        try {
+          await subject.host.completeExternalInvocation(ours.actionInvocationId, subject.ours.tenantId, subject.ours.spaceId, {
+            externalReference: "iso-ref",
+            outcome: "completed",
+            observedAt: (/* @__PURE__ */ new Date()).toISOString()
+          });
+          mine = "accepted";
+        } catch (error) {
+          mine = error.refusal ?? "threw";
+        }
+        if (mine === "not_found") fail("a completion under our own scope was refused as not_found, so the check proves nothing");
+        return ["completion under the other tenant's scope refused as not_found; found under ours"];
+      }
+    },
+    {
+      id: "fabric.tenancy.projection-scoped.v1",
+      async run(subject) {
+        if (!subject.read) return ["skipped: subject lends no read"];
+        await subject.reset?.();
+        await subject.host.submitAction(submitInput(subject, subject.ours, "iso:projection"));
+        const ours = await subject.read(subject.ours);
+        const theirs = await subject.read(subject.theirs);
+        if (!ours.allowed) fail("our own viewer was denied the read");
+        if (ours.rows.length === 0) fail("our own viewer saw nothing, so the check proves nothing");
+        if (ours.rows.some((row) => row?.tenantId !== subject.ours.tenantId)) fail("our own viewer saw rows that are not ours, or rows carrying no tenant");
+        const leaked = theirs.allowed ? theirs.rows.filter((row) => row?.tenantId === subject.ours.tenantId) : [];
+        if (leaked.length > 0) fail(`a viewer in the other tenant saw ${leaked.length} of our rows`);
+        return [theirs.allowed ? "other tenant's viewer sees none of our rows" : "other tenant's viewer is denied"];
+      }
+    }
+  ];
+}
+async function runTenantIsolationChecks(subject) {
+  const checks = [];
+  for (const check of tenantIsolationChecks()) {
+    try {
+      const evidence = await check.run(subject);
+      checks.push({ id: check.id, status: evidence[0]?.startsWith("skipped") ? "skipped" : "passed", evidence });
+    } catch (error) {
+      checks.push({ id: check.id, status: "failed", evidence: [], error: error instanceof Error ? error.message : String(error) });
+    }
+  }
+  return { passed: checks.every((check) => check.status !== "failed"), checks };
+}
+
 exports.ExternalCompletionError = ExternalCompletionError;
 exports.IdempotencyConflictError = IdempotencyConflictError;
 exports.MemoryPlatformHostStore = MemoryPlatformHostStore;
@@ -3584,6 +3759,8 @@ exports.getPlatformHostHealthSnapshot = getPlatformHostHealthSnapshot;
 exports.runOutboxRelayCycle = runOutboxRelayCycle;
 exports.runPlatformActionWorker = runPlatformActionWorker;
 exports.runPlatformActionWorkerCycle = runPlatformActionWorkerCycle;
+exports.runTenantIsolationChecks = runTenantIsolationChecks;
+exports.tenantIsolationChecks = tenantIsolationChecks;
 exports.toEnterpriseEventEnvelope = toEnterpriseEventEnvelope;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map