proof-harness 0.1.0-next.11 → 0.1.0-next.13

package/COMPATIBILITY.md

@@ -27,9 +27,89 @@ versions rather than guessing how to interpret them.
 
 ## Prerelease migration notes
 
-### 0.1.0-next.11 (release candidate) — conservative service RPC assessment
+### 0.1.0-next.13 — column-restricted tenant isolation (release candidate)
 
-Prepared for release. After publication, pin exactly `proof-harness@0.1.0-next.11`.
+Prepared for release. After publication, pin exactly `proof-harness@0.1.0-next.13`
+and update the lockfile. Add `columns` only where column grants require it, then
+rerun the baseline, coverage, mutation and control checks against the real database.
+Existing consumers that omit this option need no API changes.
+
+`assert.tenantIsolation` accepts optional `columns: ["id", "account_id"]` for
+private tables that grant customers only selected columns. The SDK uses the
+same projection for service ground truth, owner controls, and outsider probes.
+Only distinct plain column names are allowed; empty lists, wildcards, aliases,
+aggregates, casts and joins are rejected before fixture setup. Omitting the
+option retains the existing all-column query.
+
+This proves row isolation for the selected columns. Consumers must separately
+prove that private columns remain unreadable; do not grant extra columns to
+make a fixture pass. Existing positive-control, bidirectional, non-vacuity and
+provenance requirements are unchanged. No trace, mission, or health protocol migration is
+required. Adopt only an exact reviewed published package version.
+
+### 0.1.0-next.12 — independent isolation fixtures and column ACL recovery
+
+Published release. Pin exactly `proof-harness@0.1.0-next.12` when adopting these changes.
+
+`assert.tenantIsolation` now accepts a caller-owned `isolationFixture` instead of
+workspace seeding. Supply a stable fixture `id`, the matching `table`, an explicit
+`scopeColumn`, `setup()` returning two distinct actors and scope values, and
+`cleanup()` that can handle partial setup. Scope values can be user IDs or
+independent account IDs. `scope: "account"` requires this fixture path. Existing
+workspace fixtures and their reverse-direction behavior remain unchanged.
+
+```ts
+await assert.tenantIsolation({
+  table: "notifications",
+  scope: "account",
+  scopeColumn: "account_id",
+  isolationFixture: {
+    id: "notifications-two-accounts-v1",
+    table: "notifications",
+    async setup() {
+      // Consumer creates real Auth customers, resolves account IDs, and seeds rows.
+      return {
+        a: { actor: { email: ownerA.email, password: ownerA.password }, scopeValue: accountA.id },
+        b: { actor: { email: ownerB.email, password: ownerB.password }, scopeValue: accountB.id },
+      };
+    },
+    async cleanup() { await cleanupOwnedResources(); },
+  },
+});
+```
+
+The SDK creates the service client and authenticated probe clients itself. Both
+sides must contain rows before probing; each owner must read all scoped rows,
+and each outsider must see none. Both directions are mandatory. Scope/criterion
+filters apply identically to ground truth and probes. Setup and cleanup run
+without helper provenance; callers cannot stamp SDK assertions. Cleanup errors
+fail the proof. Fixture IDs appear in probe detail; existing trace source hashes
+bind tracked and nonignored fixture source to evidence. Keep fixtures under the
+consumer's source identity, not an excluded artifact directory. This path is
+database-only: `page` is unsupported. It does not extend account-policy SQL
+classification; existing explicit classifier reviews remain separate.
+
+`tablePrivilege` mutations now snapshot the relevant table and column ACL entries
+(including grant options) and compare that complete state after restoration.
+Column UPDATE grants removed by PostgreSQL's table REVOKE are re-established.
+Owner-issued direct grants, including grant options, are supported; delegated
+grant graphs, inherited/PUBLIC effective privileges, and owner-target mutations
+remain blocked before planting. No CASCADE recovery is used. Recovery fails
+closed on an old Boolean snapshot: it cannot reconstruct already-lost column
+grants. Keep that journal and reconcile with the protected baseline rather than
+claiming automatic recovery succeeded.
+
+After upgrading: port fixtures to the public API, regenerate baseline evidence,
+restore formal table-isolation coverage, and rerun frozen install, static/unit/
+browser checks, the full proof/mutation/control gate, package parity, production
+build, and smoke. Verify actual profile editing and denied privileged-column
+writes after mutations. Package tests are not a substitute for that consumer run.
+Trace, mission, and health protocol versions remain unchanged; the internal
+ACL recovery snapshot has its own version 1.
+
+### 0.1.0-next.11 — conservative service RPC assessment
+
+Published release. Pin exactly `proof-harness@0.1.0-next.11`.
 Regenerate
 capabilities and rerun the complete baseline, coverage, inventory, and mutation
 validation after adoption. Trace, mission, and health versions are unchanged.

package/PROOF_SDK_CONTRACT.md

@@ -1290,3 +1290,13 @@ action-targeted primary denial and allowed control with operation `invoke`,
 including internal actions and actions without workspace inputs. Caller evidence
 is not transitively inherited. See COMPATIBILITY.md for supported syntax and
 remaining unassessable cases.
+
+## Independent scope fixtures (0.1.0-next.12 candidate)
+
+The Playwright entry point exports `IsolationFixture`, `IsolationParticipant`,
+and `TenantIsolationOptions`. `isolationFixture` is an alternative to the legacy
+workspace `setup`/`fixture` options. Its setup and cleanup are consumer-owned;
+clients, ground-truth checks, both owner controls, and both outsider probes stay
+SDK-owned. Missing either side, malformed actors/scopes, failed probes or cleanup
+prevent a passing proof. The SDK does not emit provenance on callback assertions.
+See COMPATIBILITY.md for the public call shape and source-identity requirements.

package/README.md

@@ -152,7 +152,15 @@ Release `0.1.0-next.10` restores explicit consumer primary assertions
 for mutation detection while retaining strict control provenance. See the
 [next.10 migration notes](COMPATIBILITY.md) before adopting it.
 
-Release candidate `0.1.0-next.11` discovers direct service RPC calls as potentially
+Release `0.1.0-next.11` discovers direct service RPC calls as potentially
 privileged writes and requires action-boundary evidence even without workspace
 inputs or for internal actions. See [required migration steps](COMPATIBILITY.md)
-before adopting the exact version after publication.
+before adopting the exact version.
+
+Release `0.1.0-next.12` adds caller-owned account/user isolation fixtures
+and restores column grants and grant options after table-privilege mutations.
+See [migration requirements](COMPATIBILITY.md).
+
+Release candidate `0.1.0-next.13` adds optional readable-column selection to
+`assert.tenantIsolation` for tables with column grants. Private-column denial
+remains a separate consumer proof; see [migration requirements](COMPATIBILITY.md).

package/cli/engines/proof_mutation_check.mjs

@@ -1,4 +1,9 @@
 #!/usr/bin/env node
+import {
+  tableAclSnapshotSql,
+  validateTableAcl,
+  restoreTableAclSql,
+} from "./proof_table_acl.mjs";
 import {
   validateControlBaseline,
   assertionSelectorsTurnedRed,
@@ -234,13 +239,13 @@ function assertDirectPrivilege(container, subject, functionSubject = false) {
     `SELECT NOT EXISTS (
     SELECT 1 FROM ${catalog} c, LATERAL aclexplode(coalesce(c.${acl},acldefault('${defaultKind}',c.${owner}))) a
     WHERE c.oid = ${object} AND a.privilege_type = ${quoteLiteral(subject.privilege.toUpperCase())}
-      AND ((a.grantee = ${quoteLiteral(subject.role)}::regrole AND (a.is_grantable OR a.grantor <> c.${owner}))
+      AND ((a.grantee = ${quoteLiteral(subject.role)}::regrole AND (${functionSubject ? "a.is_grantable OR " : ""}a.grantor <> c.${owner}))
         OR (a.grantee <> ${quoteLiteral(subject.role)}::regrole AND (a.grantee = 0 OR pg_has_role(${quoteLiteral(subject.role)},a.grantee,'USAGE'))))
   ) AND NOT EXISTS (SELECT 1 FROM ${catalog} WHERE oid = ${object} AND ${owner} = ${quoteLiteral(subject.role)}::regrole)`,
   );
   if (supported !== "t")
     throw new Error(
-      "[PROOF_FAIL] mutation_unassessed: privilege restoration supports owner-issued direct grants without grant options; inherited, PUBLIC, and owner privileges require a dedicated catalog mutation",
+      `[PROOF_FAIL] mutation_unassessed: privilege restoration requires owner-issued direct grants${functionSubject ? " without grant options" : ""}; inherited, PUBLIC, and owner privileges require a dedicated catalog mutation`,
     );
 }
 
@@ -314,17 +319,13 @@ const SUBJECTS = {
   },
 
   tablePrivilege: {
-    preflight: (container, s) => assertDirectPrivilege(container, s),
+    preflight: (container, s) => {
+      assertDirectPrivilege(container, s);
+      validateTableAcl(queryScalar(container, tableAclSnapshotSql(s)));
+    },
     describe: (s) => `${s.privilege} on ${s.table} for ${s.role}`,
-    snapshot: (container, s) =>
-      queryScalar(
-        container,
-        `SELECT has_table_privilege(${quoteLiteral(s.role)}, ${quoteLiteral(s.table)}, ${quoteLiteral(s.privilege)})`,
-      ),
-    restore: (s, snapshot) =>
-      snapshot === "t"
-        ? `GRANT ${s.privilege} ON ${s.table} TO ${s.role};`
-        : `REVOKE ${s.privilege} ON ${s.table} FROM ${s.role};`,
+    snapshot: (container, s) => queryScalar(container, tableAclSnapshotSql(s)),
+    restore: restoreTableAclSql,
   },
 
   functionPrivilege: {

package/cli/engines/proof_table_acl.mjs

@@ -0,0 +1,62 @@
+// Canonical relevant ACL state, not effective has_table_privilege booleans.
+const lit = (value) => "'" + String(value).replaceAll("'", "''") + "'";
+const ident = (value) => '"' + String(value).replaceAll('"', '""') + '"';
+export function tableAclSnapshotSql(subject) {
+  return `WITH target AS (SELECT oid, relowner, relacl FROM pg_class WHERE oid = ${lit(subject.table)}::regclass), entries AS (
+    SELECT NULL::text AS column_name, a.* FROM target t, LATERAL aclexplode(coalesce(t.relacl,acldefault('r',t.relowner))) a
+    UNION ALL
+    SELECT c.attname::text, a.* FROM target t JOIN pg_attribute c ON c.attrelid=t.oid AND c.attnum>0 AND NOT c.attisdropped,
+      LATERAL aclexplode(c.attacl) a
+  ) SELECT json_build_object('version',1,'owner',(SELECT pg_get_userbyid(relowner) FROM target),
+    'entries',coalesce((SELECT json_agg(json_build_object('column',column_name,'grantor',pg_get_userbyid(grantor),
+      'grantee',CASE WHEN grantee=0 THEN 'PUBLIC' ELSE pg_get_userbyid(grantee) END,'grantable',is_grantable)
+      ORDER BY column_name NULLS FIRST,grantor,grantee,is_grantable)
+      FROM entries WHERE privilege_type=${lit(subject.privilege.toUpperCase())}), '[]'::json))::text`;
+}
+export function validateTableAcl(snapshot) {
+  const value = JSON.parse(snapshot);
+  if (
+    value?.version !== 1 ||
+    typeof value.owner !== "string" ||
+    !Array.isArray(value.entries) ||
+    value.entries.some(
+      (e) =>
+        !(e.column === null || typeof e.column === "string") ||
+        typeof e.grantee !== "string" ||
+        typeof e.grantable !== "boolean" ||
+        e.grantor !== value.owner,
+    )
+  )
+    throw new Error(
+      "[PROOF_FAIL] mutation_unassessed: table ACL requires versioned owner-issued grants; delegated grant graphs need a dedicated mutation",
+    );
+  return value;
+}
+export function restoreTableAclSql(subject, snapshot) {
+  const value = validateTableAcl(snapshot);
+  const privilege = subject.privilege.toUpperCase();
+  if (
+    ![
+      "SELECT",
+      "INSERT",
+      "UPDATE",
+      "DELETE",
+      "TRUNCATE",
+      "REFERENCES",
+      "TRIGGER",
+      "MAINTAIN",
+    ].includes(privilege)
+  )
+    throw new Error("unsupported table privilege");
+  const role = subject.role === "PUBLIC" ? "PUBLIC" : ident(subject.role);
+  // Revoking a table privilege also removes this role's column grants. Restore
+  // those explicitly, preserving grant options. No CASCADE: unexpected dependent
+  // grants abort instead of destroying state not represented by the snapshot.
+  const sql = [`REVOKE ${privilege} ON ${subject.table} FROM ${role};`];
+  for (const entry of value.entries.filter((e) => e.grantee === subject.role)) {
+    sql.push(
+      `GRANT ${privilege}${entry.column === null ? "" : ` (${ident(entry.column)})`} ON ${subject.table} TO ${role}${entry.grantable ? " WITH GRANT OPTION" : ""};`,
+    );
+  }
+  return sql.join("\n");
+}

package/dist/playwright.d.ts

@@ -97,6 +97,10 @@ declare const actAsUser: {
 };
 
 interface TenantIsolationBaseOptions {
+    /** Plain readable column names for column-restricted tables. Defaults to all
+     * columns. The same projection is used for ground truth and both actors.
+     * This proves row isolation only; test secret-column denial separately. */
+    columns?: readonly string[];
     /**
      * Table to query as userB. RLS on the table is what is being tested.
      * Must be a table governed by a tenant-scoped RLS policy — either
@@ -116,7 +120,7 @@ interface TenantIsolationBaseOptions {
      *
      * Tables classified `user_scoped` in `.proof/schema.json` need `"user"`.
      */
-    scope?: "workspace" | "user";
+    scope?: "workspace" | "user" | "account";
     /**
      * Column carrying the scope value. Defaults to `workspace_id` for workspace
      * scope and `user_id` for user scope.
@@ -170,7 +174,31 @@ interface TenantIsolationBaseOptions {
  * until the builder knows the final constraints. Supplying both is rejected by
  * the type system so there is one source of fixture truth.
  */
+interface IsolationParticipant {
+    actor: {
+        email: string;
+        password: string;
+    };
+    scopeValue: string;
+}
+/** Caller owns all resources, including cleanup after partially failed setup. */
+interface IsolationFixture {
+    id: string;
+    table: string;
+    setup(): Promise<{
+        a: IsolationParticipant;
+        b: IsolationParticipant;
+    }>;
+    cleanup(): Promise<void>;
+}
 type TenantIsolationOptions = TenantIsolationBaseOptions & ({
+    isolationFixture: IsolationFixture;
+    scopeColumn: string;
+    page?: never;
+    setup?: never;
+    fixture?: never;
+} | {
+    isolationFixture?: never;
     /**
      * Inline setup for an already-known schema. It must create at least one
      * row for side A; side B is optional but required for a bidirectional
@@ -181,6 +209,7 @@ type TenantIsolationOptions = TenantIsolationBaseOptions & ({
 } | {
     /** Explicit table-owned factory from `e2e/fixtures/<table>.ts`. */
     fixture: ProofFixtureFactory;
+    isolationFixture?: never;
     setup?: never;
 });
 type AuthorizationOp = "select" | "insert" | "update" | "delete";
@@ -461,4 +490,4 @@ declare const trace: {
     proof(arg: string | ProofOptions, fn: (t: TraceRecorderImpl) => Promise<void>): Promise<void>;
 };
 
-export { actAsUser, assert, recordAssertion, trace };
+export { type IsolationFixture, type IsolationParticipant, type TenantIsolationOptions, actAsUser, assert, recordAssertion, trace };

package/dist/playwright.js

@@ -1765,9 +1765,22 @@ async function runRlsProbe(probe, actorCreds) {
     detail: `${actorCreds.label} UPDATE on ${probe.table} left ${columns.join(", ")} unchanged across ${before.length} targeted row(s)${error ? ` (${error.message})` : ""}; verified by service-role re-read (RLS honored)`
   });
 }
-async function countRowsAsService(sb, table, filter) {
+function tenantColumnSelection(columns) {
+  if (columns === void 0) return "*";
+  if (!Array.isArray(columns) || columns.length === 0 || columns.some(
+    (column) => typeof column !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(column)
+  ) || new Set(columns).size !== columns.length) {
+    throw proofFail(
+      "tenant_isolation_setup",
+      "a non-empty list of distinct plain column names",
+      "invalid tenant column projection"
+    );
+  }
+  return columns.join(",");
+}
+async function countRowsAsService(sb, table, filter, selection) {
   const { count, error } = await applyEq(
-    sb.from(table).select("*", { count: "exact", head: true }),
+    sb.from(table).select(selection, { count: "exact", head: true }),
     filter
   );
   if (error) {
@@ -1800,8 +1813,13 @@ async function probeTenantIsolation(args) {
     [scopeColumn]: scopeValue,
     ...criterion?.where ?? {}
   };
-  const criterionDetail = criterion ? ` matching planner criterion "${criterion.description}" (${JSON.stringify(criterion.where)})` : "";
-  const actualRowCount = await countRowsAsService(sb, table, filter);
+  const criterionDetail = (criterion ? ` matching planner criterion "${criterion.description}" (${JSON.stringify(criterion.where)})` : "") + (args.selection === "*" ? "" : ` selecting columns ${args.selection}`);
+  const actualRowCount = await countRowsAsService(
+    sb,
+    table,
+    filter,
+    args.selection
+  );
   if (actualRowCount === 0) {
     return "skipped_no_data";
   }
@@ -1813,7 +1831,7 @@ async function probeTenantIsolation(args) {
     data: ownRows,
     error: ownError,
     status: ownStatus
-  } = await applyEq(ownerClient.from(table).select("*"), filter);
+  } = await applyEq(ownerClient.from(table).select(args.selection), filter);
   failIfInfrastructure(
     ownError,
     ownStatus,
@@ -1826,7 +1844,7 @@ async function probeTenantIsolation(args) {
       "a valid owner control query",
       ownError.message
     );
-  if (ownError || (ownRows?.length ?? 0) === 0) {
+  if (ownError || (ownRows?.length ?? 0) === 0 || args.strictOwner && ownRows?.length !== actualRowCount) {
     recordAssertion({
       kind: "tenant_isolation",
       target: table,
@@ -1860,13 +1878,29 @@ async function probeTenantIsolation(args) {
     data: leakedRows,
     error: queryError,
     status: queryStatus
-  } = await applyEq(client.from(table).select("*"), filter);
+  } = await applyEq(client.from(table).select(args.selection), filter);
   failIfInfrastructure(
     queryError,
     queryStatus,
     "tenant_isolation_setup",
     `the outsider's SELECT on ${table}`
   );
+  if (queryError && args.strictOwner) {
+    recordAssertion({
+      kind: "tenant_isolation",
+      target: table,
+      operation: "select",
+      passed: false,
+      status: "incomplete",
+      role: "primary",
+      detail: `outsider query failed before isolation could be assessed: ${queryError.message}`
+    });
+    throw proofFail(
+      "tenant_isolation_setup",
+      "a successful outsider query returning no rows",
+      queryError.message
+    );
+  }
   if (queryError) {
     recordAssertion({
       kind: "tenant_isolation",
@@ -1886,7 +1920,9 @@ async function probeTenantIsolation(args) {
     );
   }
   if (leakedRows && leakedRows.length > 0) {
-    const sampleIds = leakedRows.slice(0, 3).map((r) => r.id ?? "?").join(", ");
+    const sampleIds = leakedRows.slice(0, 3).map(
+      (r) => r !== null && typeof r === "object" && "id" in r ? String(r.id) : "?"
+    ).join(", ");
     recordAssertion({
       kind: "tenant_isolation",
       target: table,
@@ -2021,6 +2057,131 @@ var assertMethods = {
    */
   async tenantIsolation(opts) {
     const { table, page } = opts;
+    const selection = tenantColumnSelection(opts.columns);
+    if (opts.isolationFixture) {
+      const fixture = await withoutAssertionProvenance(async () => {
+        const supplied = opts.isolationFixture;
+        return {
+          id: supplied.id,
+          table: supplied.table,
+          setup: typeof supplied.setup === "function" ? supplied.setup.bind(supplied) : supplied.setup,
+          cleanup: typeof supplied.cleanup === "function" ? supplied.cleanup.bind(supplied) : supplied.cleanup
+        };
+      });
+      if (page)
+        throw proofFail(
+          "tenant_isolation_setup",
+          "a database-only caller-owned fixture",
+          "page is unsupported for isolationFixture"
+        );
+      if (!fixture.id?.trim() || fixture.table !== table || !opts.scopeColumn?.trim() || typeof fixture.setup !== "function" || typeof fixture.cleanup !== "function")
+        throw proofFail(
+          "tenant_isolation_setup",
+          "a named, table-matched isolation fixture and scope column",
+          "malformed fixture"
+        );
+      validateTenantIsolationCriterion(table, opts.scopeColumn, opts.criterion);
+      const failures = [];
+      try {
+        const participants = await withoutAssertionProvenance(async () => {
+          const sides = await fixture.setup();
+          const valid = (side) => side && typeof side.scopeValue === "string" && side.scopeValue.trim() && typeof side.actor?.email === "string" && side.actor.email.trim() && typeof side.actor?.password === "string" && side.actor.password.length;
+          if (!sides || !valid(sides.a) || !valid(sides.b) || sides.a.scopeValue === sides.b.scopeValue || sides.a.actor.email.toLowerCase() === sides.b.actor.email.toLowerCase())
+            throw proofFail(
+              "tenant_isolation_setup",
+              "two distinct actors and scope values",
+              "malformed isolation participants"
+            );
+          return [sides.a, sides.b].map((side) => ({
+            scopeValue: side.scopeValue,
+            actor: { email: side.actor.email, password: side.actor.password }
+          }));
+        });
+        const sb = createProofServiceClient();
+        for (const side of participants) {
+          const count = await countRowsAsService(
+            sb,
+            table,
+            {
+              [opts.scopeColumn]: side.scopeValue,
+              ...opts.criterion?.where ?? {}
+            },
+            selection
+          );
+          if (!count)
+            throw proofFail(
+              "tenant_isolation_vacuous",
+              "existing rows for both isolation participants",
+              `empty side in fixture ${fixture.id}`
+            );
+        }
+        for (const [owner, viewer] of [
+          [participants[0], participants[1]],
+          [participants[1], participants[0]]
+        ]) {
+          const outcome = await probeTenantIsolation({
+            selection,
+            table,
+            owner: owner.actor,
+            viewer: viewer.actor,
+            ownerLabel: `fixture ${fixture.id} owner`,
+            viewerLabel: `fixture ${fixture.id} outsider`,
+            scopeColumn: opts.scopeColumn,
+            scopeValue: owner.scopeValue,
+            scopeLabel: owner.scopeValue,
+            criterion: opts.criterion,
+            scopePattern: "the consumer-owned owner/account policy",
+            sb,
+            strictOwner: true
+          });
+          if (outcome !== "proved")
+            throw proofFail(
+              "tenant_isolation_vacuous",
+              "existing target rows throughout both probes",
+              "rows disappeared"
+            );
+        }
+      } catch (error) {
+        recordAssertion({
+          kind: "tenant_isolation",
+          target: table,
+          operation: "select",
+          passed: false,
+          status: "incomplete",
+          role: "primary",
+          detail: `fixture ${fixture.id} did not complete both isolation directions`
+        });
+        failures.push(error);
+      } finally {
+        try {
+          await withoutAssertionProvenance(() => fixture.cleanup());
+        } catch (error) {
+          recordAssertion({
+            kind: "tenant_isolation",
+            target: table,
+            operation: "select",
+            passed: false,
+            status: "incomplete",
+            role: "primary",
+            detail: `fixture ${fixture.id} cleanup failed`
+          });
+          failures.push(error);
+        }
+      }
+      if (failures.length === 1) throw failures[0];
+      if (failures.length > 1)
+        throw new AggregateError(
+          failures,
+          "Isolation probe and cleanup failed"
+        );
+      return;
+    }
+    if (opts.scope === "account")
+      throw proofFail(
+        "tenant_isolation_setup",
+        "isolationFixture for account scope",
+        "workspace fixture selected"
+      );
     const tag = opts.tag ?? randomSuffix();
     const scope = opts.scope ?? "workspace";
     const scopeColumn = opts.scopeColumn ?? (scope === "user" ? "user_id" : "workspace_id");
@@ -2122,6 +2283,7 @@ var assertMethods = {
           );
         }
         const forward = await probeTenantIsolation({
+          selection,
           table,
           viewer: userB,
           viewerLabel: "user B",
@@ -2157,6 +2319,7 @@ var assertMethods = {
           );
         }
         const reverse = await probeTenantIsolation({
+          selection,
           table,
           viewer: userA,
           viewerLabel: "user A",