@nodii/db-rls 0.11.0 → 0.13.0

package/dist/tenant-fence-gate.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Installs `auth.assert_tenant_fence()`.
+ *
+ * The function RAISES `P0001` naming every offender when the fence is broken,
+ * and returns silently when it is intact. It is the runtime post-condition:
+ * cheap enough to run once per process, specific enough that the error text
+ * tells an on-call engineer what to fix.
+ *
+ * The rule is the POSITIVE one, identical to `classifyAuthPolicy`: every
+ * permissive policy applying to `authenticated` MUST resolve through
+ * `auth.session_tenant_ids()`. Absence of the bad shape is not presence of the
+ * good one — a policy mangled by a sweep into something that mentions neither
+ * helper is an offender, not a pass.
+ *
+ * Role resolution uses `pg_has_role(..., 'USAGE')` plus OID 0 for PUBLIC, for
+ * the same reason the TypeScript verifier does: a `{public}` policy applies to
+ * `authenticated` without containing the word, and role membership is
+ * transitive. A substring test over `pg_policies.roles` misses both, and each
+ * was proven to yield a live cross-tenant read AND write while the check
+ * reported zero offenders.
+ */
+export declare const TENANT_FENCE_GATE_SQL = "CREATE SCHEMA IF NOT EXISTS auth;\nCREATE OR REPLACE FUNCTION auth._fence_reason(p_expr text) RETURNS text\nLANGUAGE sql IMMUTABLE\nSET search_path = pg_catalog, public, pg_temp\nAS $reason$\n  SELECT CASE\n    WHEN p_expr ~* '(auth\\s*\\.\\s*)?user_tenant_ids\\s*\\('\n      THEN 'consults auth.user_tenant_ids directly instead of auth.session_tenant_ids() \u2014 resolves across EVERY tenant the principal belongs to'\n    WHEN p_expr IS NULL OR btrim(p_expr) = '' OR p_expr ~* '^\\(?\\s*true\\s*\\)?$'\n      THEN 'is permissive with no tenant reference at all \u2014 every tenant, every row'\n    ELSE 'does not resolve through auth.session_tenant_ids() \u2014 it may be fenced some other way, but nothing here proves it, and an unrecognized shape is not a safe shape'\n  END\n$reason$;\nCREATE OR REPLACE FUNCTION auth.assert_tenant_fence(\n  p_schemas text[] DEFAULT ARRAY['public'],\n  p_exempt_policies text[] DEFAULT ARRAY[]::text[],\n  p_exempt_tables text[] DEFAULT ARRAY[]::text[],\n  p_tenant_columns text[] DEFAULT ARRAY['tenant_id','org_id','organization_id'],\n  p_allow_degraded boolean DEFAULT true\n) RETURNS void\nLANGUAGE plpgsql STABLE SECURITY DEFINER\nSET search_path = pg_catalog, public, pg_temp\nAS $fence_check$\nDECLARE\n  v_offenders text[] := ARRAY[]::text[];\n  v_row record;\n  v_resolver record;\n  v_membership record;\n  v_degraded boolean := false;\nBEGIN\n  -- ---------------------------------------------------------------------\n  -- 1. The resolver itself. If it is missing, every policy referencing it is\n  --    already broken, and nothing below can be interpreted.\n  -- ---------------------------------------------------------------------\n  SELECT p.prosrc, p.prosecdef INTO v_resolver\n    FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace\n   WHERE n.nspname = 'auth' AND p.proname = 'session_tenant_ids' LIMIT 1;\n\n  IF v_resolver IS NULL THEN\n    RAISE EXCEPTION 'tenant_fence: auth.session_tenant_ids() is not installed'\n      USING ERRCODE = 'P0001',\n            HINT = 'Apply INSTALL_SESSION_RESOLVER_SQL (applyAuthSchemaMigrations ships it, and @nodii/saga + @nodii/dsar + @nodii/audit-chain install it before their policies).';\n  END IF;\n\n  v_degraded := v_resolver.prosrc LIKE '%DB_RLS_DEGRADED_NO_MEMBERSHIP_MIRROR%';\n\n  IF v_resolver.prosrc !~* 'RAISE\\s+EXCEPTION' THEN\n    v_offenders := v_offenders || 'auth.session_tenant_ids() [session_tenant_ids] does not RAISE on an unbound session \u2014 it was replaced with a NULL-returning getter, which restores silent failure';\n  END IF;\n\n  IF NOT v_resolver.prosecdef THEN\n    v_offenders := v_offenders || 'auth.session_tenant_ids() [session_tenant_ids] is not SECURITY DEFINER \u2014 it cannot read the membership mirror (permission denied), or will recurse into the mirror''s own policy (54001)';\n  END IF;\n\n  IF v_degraded AND NOT p_allow_degraded THEN\n    v_offenders := v_offenders || 'auth.session_tenant_ids() [session_tenant_ids] is the DEGRADED fence-only resolver \u2014 the session tenant is trusted WITHOUT proving membership';\n  END IF;\n\n  -- The stub check applies ONLY to the strict resolver. Under the degraded body\n  -- auth.user_tenant_ids is never consulted, so a stub there is the expected,\n  -- D415-sanctioned terminal state \u2014 not a defect. Flagging it would make every\n  -- legitimately-degraded service permanently red, which is how a gate gets\n  -- switched off.\n  IF NOT v_degraded THEN\n    SELECT p.prosrc INTO v_membership\n      FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace\n     WHERE n.nspname = 'auth' AND p.proname = 'user_tenant_ids' LIMIT 1;\n    IF v_membership IS NOT NULL\n       AND v_membership.prosrc ~* 'where\\s+false'\n       AND v_membership.prosrc !~* 'from\\s+\\w' THEN\n      v_offenders := v_offenders || 'auth.user_tenant_ids(uuid) [user_tenant_ids] is still the bootstrap stub returning the empty set \u2014 the strict resolver intersects to nothing, so the authenticated pool is silently deny-all';\n    END IF;\n  END IF;\n\n  -- ---------------------------------------------------------------------\n  -- 2. The positive rule over every authenticated-applicable policy.\n  -- ---------------------------------------------------------------------\n  FOR v_row IN\n    SELECT n.nspname AS schemaname,\n           c.relname  AS tablename,\n           pol.polname AS policyname,\n           CASE pol.polcmd WHEN 'r' THEN 'SELECT' WHEN 'a' THEN 'INSERT'\n                           WHEN 'w' THEN 'UPDATE' WHEN 'd' THEN 'DELETE'\n                           ELSE 'ALL' END AS cmd,\n           pg_get_expr(pol.polqual, pol.polrelid)      AS qual,\n           pg_get_expr(pol.polwithcheck, pol.polrelid) AS with_check\n      FROM pg_policy pol\n      JOIN pg_class c ON c.oid = pol.polrelid\n      JOIN pg_namespace n ON n.oid = c.relnamespace\n     WHERE n.nspname = ANY(p_schemas)\n       -- RESTRICTIVE policies are ANDed; they can only narrow access, so they\n       -- cannot be the source of a cross-tenant grant.\n       AND pol.polpermissive\n       AND (\n         EXISTS (SELECT 1 FROM unnest(pol.polroles) r WHERE r = 0)\n         OR (\n           EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'authenticated')\n           AND EXISTS (\n             SELECT 1 FROM unnest(pol.polroles) r\n              WHERE pg_has_role('authenticated', r, 'USAGE')\n           )\n         )\n       )\n       AND NOT (pol.polname = ANY(p_exempt_policies))\n       AND NOT ((c.relname || '.' || pol.polname) = ANY(p_exempt_policies))\n       AND NOT (c.relname = ANY(p_exempt_tables))\n       AND NOT ((n.nspname || '.' || c.relname) = ANY(p_exempt_tables))\n     ORDER BY c.relname, pol.polname\n  LOOP\n    -- A policy with NEITHER clause is permissive-everything.\n    IF v_row.qual IS NULL AND v_row.with_check IS NULL THEN\n      v_offenders := v_offenders || format(\n        '%s.%s [%s %s] is permissive with no tenant reference at all \u2014 every tenant, every row',\n        v_row.schemaname, v_row.tablename, v_row.policyname, v_row.cmd);\n      CONTINUE;\n    END IF;\n\n    -- EVERY clause present must resolve. A fenced read with an unfenced\n    -- WITH CHECK is a cross-tenant WRITE, which is what the refund incident\n    -- actually exercised.\n    IF v_row.qual IS NOT NULL\n       AND v_row.qual !~* '(auth\\s*\\.\\s*)?session_tenant_ids\\s*\\(' THEN\n      v_offenders := v_offenders || format('%s.%s [%s %s USING] %s :: %s',\n        v_row.schemaname, v_row.tablename, v_row.policyname, v_row.cmd,\n        auth._fence_reason(v_row.qual), v_row.qual);\n    END IF;\n\n    IF v_row.with_check IS NOT NULL\n       AND v_row.with_check !~* '(auth\\s*\\.\\s*)?session_tenant_ids\\s*\\(' THEN\n      v_offenders := v_offenders || format('%s.%s [%s %s WITH CHECK] %s :: %s',\n        v_row.schemaname, v_row.tablename, v_row.policyname, v_row.cmd,\n        auth._fence_reason(v_row.with_check), v_row.with_check);\n    END IF;\n  END LOOP;\n\n  -- ---------------------------------------------------------------------\n  -- 3. Table coverage. THE HOLE A POLICY-LEVEL CHECK CANNOT SEE: a table with\n  --    a tenant column and RLS switched off has no rows in pg_policy to\n  --    inspect, and under the canonical blanket grants it is readable AND\n  --    writable across every tenant \u2014 strictly more open than the union\n  --    predicate this release removes.\n  --\n  --    Discovered FROM THE CATALOG, never from a caller-supplied list. The\n  --    author who forgets ENABLE ROW LEVEL SECURITY is the same author who\n  --    forgets the list entry, in the same migration.\n  -- ---------------------------------------------------------------------\n  FOR v_row IN\n    SELECT n.nspname AS schemaname, c.relname AS tablename,\n           c.relkind::text AS relkind, c.relrowsecurity,\n           COALESCE((SELECT true FROM unnest(COALESCE(c.reloptions,'{}')) o\n                      WHERE lower(replace(o,' ','')) = 'security_invoker=true'), false) AS security_invoker\n      FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace\n     WHERE c.relkind = ANY('{r,p,v,m,f}')\n       AND n.nspname = ANY(p_schemas)\n       AND NOT (c.relname = ANY(p_exempt_tables))\n       AND NOT ((n.nspname || '.' || c.relname) = ANY(p_exempt_tables))\n       AND EXISTS (SELECT 1 FROM pg_attribute a\n                    WHERE a.attrelid = c.oid AND a.attnum > 0\n                      AND NOT a.attisdropped AND a.attname = ANY(p_tenant_columns))\n     ORDER BY n.nspname, c.relname\n  LOOP\n    IF v_row.relkind IN ('v','m','f') THEN\n      -- A view with security_invoker=true executes as the CALLER, so the\n      -- underlying table's RLS applies and the view is genuinely safe.\n      IF v_row.relkind = 'v' AND v_row.security_invoker THEN CONTINUE; END IF;\n      v_offenders := v_offenders || format(\n        '%s.%s exposes a tenant column but cannot enforce RLS (relkind=%s) \u2014 a materialized/foreign relation has no row policies at all, and a view without security_invoker=true runs as its OWNER and bypasses the underlying table''s policies',\n        v_row.schemaname, v_row.tablename, v_row.relkind);\n    ELSIF NOT v_row.relrowsecurity THEN\n      v_offenders := v_offenders || format(\n        '%s.%s has a tenant column but ROW LEVEL SECURITY is NOT ENABLED \u2014 with the canonical blanket grants this table is readable and writable across EVERY tenant, and no policy is ever consulted',\n        v_row.schemaname, v_row.tablename);\n    END IF;\n  END LOOP;\n\n  IF array_length(v_offenders, 1) > 0 THEN\n    RAISE EXCEPTION 'tenant_fence: % authenticated-pool policy/helper defect(s). A user session must reach exactly ONE tenant \u2014 the one the edge resolved from the request \u2014 and nothing else, ever.%',\n      array_length(v_offenders, 1),\n      E'\\n  - ' || array_to_string(v_offenders, E'\\n  - ')\n      USING ERRCODE = 'P0001',\n            HINT = 'Regenerate policies with @nodii/db-rls withRls() / generateRlsPolicy(), which emit \"<col> IN (SELECT auth.session_tenant_ids())\". Nodii-staff cross-tenant access is a different path entirely: the platform_ops pool + withPlatformOpsContext.';\n  END IF;\nEND\n$fence_check$;\nGRANT EXECUTE ON FUNCTION auth._fence_reason(text) TO PUBLIC;\n";
+/** Grant for the gate. Split from the DDL for the same reason every other
+ *  grant in this package is: the roles must exist before the GRANT runs, and
+ *  on a fresh database they do not yet. */
+export declare const TENANT_FENCE_GATE_GRANTS_SQL = "GRANT EXECUTE ON FUNCTION auth.assert_tenant_fence(text[], text[], text[], text[], boolean) TO nodii_services, authenticated;\n";
+/** The statement `withUserContext` runs once per process on first authenticated
+ *  checkout. Kept as a named constant so the wiring is greppable from the call
+ *  site and the test-suite asserts the exact text. */
+export declare const TENANT_FENCE_GATE_CALL_SQL = "SELECT auth.assert_tenant_fence()";
+/**
+ * THE DELIVERY UNIT, whole: the resolver the policies reference, plus the gate
+ * that proves they reference it.
+ *
+ * These ship together because they fail together. A database with the resolver
+ * but no gate has a fence nobody checks; a database with the gate but no
+ * resolver cannot create the policies in the first place. Splitting them would
+ * create a state where a service is half-delivered and neither half complains,
+ * which is the condition this whole release exists to end.
+ *
+ * Every delivery path applies exactly this constant:
+ *   - `applyAuthSchemaMigrations` (@nodii/db-rls)
+ *   - `applySagaMigrations` (@nodii/saga)
+ *   - `applyDsarMigrations` (@nodii/dsar)
+ *   - `applyAuditChainMigrations` (@nodii/audit-chain)
+ *   - the `nodii-db-rls install-fence` CLI, for a service on none of the above
+ *
+ * The three mirrors inline a byte-equal copy rather than importing it, to
+ * preserve their deliberate zero-dependency posture on `@nodii/db-rls`. That
+ * duplication is guarded by a byte-equality test in each mirror's suite, not by
+ * a comment asking people to remember.
+ */
+export declare function sessionFenceBootstrapSql(installSql: string): string;
+//# sourceMappingURL=tenant-fence-gate.d.ts.map

package/dist/tenant-fence-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-fence-gate.d.ts","sourceRoot":"","sources":["../src/tenant-fence-gate.ts"],"names":[],"mappings":"AAkDA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,qBAAqB,0hUAyLjC,CAAC;AAEF;;2CAE2C;AAC3C,eAAO,MAAM,4BAA4B,oIACxC,CAAC;AAEF;;sDAEsD;AACtD,eAAO,MAAM,0BAA0B,sCAAsC,CAAC;AAE9E;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEnE"}

package/dist/tenant-fence-gate.js

@@ -0,0 +1,291 @@
+// The RUNTIME half of the fence gate: `auth.assert_tenant_fence()`.
+//
+// `verifyTenantFence` (tenant-fence.ts) is the deploy-time gate. It is
+// thorough, it reports every offender at once, and it is the right thing to run
+// in CI and in a `db:verify` step. It also cannot be the only gate, for a
+// reason that is structural rather than a matter of diligence:
+//
+//   SIX OF THE TEN SERVICES THIS RELEASE HAS TO REACH RUN NO DATABASE STEP ON
+//   DEPLOY AT ALL.
+//
+// That is measured, not assumed — `.github/workflows/deploy-dev.yml` in
+// billing, kyc, notification, task-tracking, tenant and geo contains no
+// `db:setup` and no `db:migrate`. Their `db:setup` exists, and it runs in
+// `ci.yml`, against a throwaway CI Postgres that is deleted minutes later. A
+// gate wired into `db:setup` would be green on every one of those services
+// forever while their real databases drifted, which is worse than no gate,
+// because it would be REPORTED as a pass.
+//
+// So the runtime gate has to live somewhere every service reaches without
+// anyone wiring it. There are only two such places: the library code a service
+// calls to get a connection, and the database itself. This module uses both —
+// a SECURITY DEFINER function in the database, invoked by `withUserContext` on
+// first use (context.ts).
+//
+// WHY A SQL FUNCTION RATHER THAN THE TYPESCRIPT VERIFIER.
+//
+// `PgTx.exec` returns `Promise<void>`. The pool abstraction in this library
+// deliberately yields no row-returning query surface, so a JavaScript catalog
+// scan cannot run on the pool a service already has — it needs a separate
+// `RlsQuerier` the caller supplies. "The caller supplies it" is precisely the
+// property that left `verifyRls` unwired in every repo for a year. A check
+// whose invocation depends on somebody passing something is a check that will
+// not run.
+//
+// A SECURITY DEFINER function has none of that dependency. It is installed by
+// the same delivery unit as the resolver, so a database that can evaluate the
+// fence predicate can always also evaluate the fence check. It is reachable
+// through `exec`. It works identically from the Go and Python ports, and from
+// psql during an incident. And because it is SECURITY DEFINER it can read
+// `pg_policy`, which `authenticated` cannot.
+//
+// TWO IMPLEMENTATIONS IS A REAL COST, AND IT IS PAID DELIBERATELY.
+//
+// This function and `verifyTenantFence` encode the same rule twice, which is
+// the duplication failure this codebase keeps being bitten by. The control is
+// not a comment asking people to keep them in step: `tests/fence-gate-agreement
+// .integration.test.ts` stands up each offending shape in a real database and
+// asserts BOTH implementations reach the same verdict on it. If one is fixed
+// and the other is not, that test goes red.
+/**
+ * Installs `auth.assert_tenant_fence()`.
+ *
+ * The function RAISES `P0001` naming every offender when the fence is broken,
+ * and returns silently when it is intact. It is the runtime post-condition:
+ * cheap enough to run once per process, specific enough that the error text
+ * tells an on-call engineer what to fix.
+ *
+ * The rule is the POSITIVE one, identical to `classifyAuthPolicy`: every
+ * permissive policy applying to `authenticated` MUST resolve through
+ * `auth.session_tenant_ids()`. Absence of the bad shape is not presence of the
+ * good one — a policy mangled by a sweep into something that mentions neither
+ * helper is an offender, not a pass.
+ *
+ * Role resolution uses `pg_has_role(..., 'USAGE')` plus OID 0 for PUBLIC, for
+ * the same reason the TypeScript verifier does: a `{public}` policy applies to
+ * `authenticated` without containing the word, and role membership is
+ * transitive. A substring test over `pg_policies.roles` misses both, and each
+ * was proven to yield a live cross-tenant read AND write while the check
+ * reported zero offenders.
+ */
+export const TENANT_FENCE_GATE_SQL = `CREATE SCHEMA IF NOT EXISTS auth;
+CREATE OR REPLACE FUNCTION auth._fence_reason(p_expr text) RETURNS text
+LANGUAGE sql IMMUTABLE
+SET search_path = pg_catalog, public, pg_temp
+AS $reason$
+  SELECT CASE
+    WHEN p_expr ~* '(auth\\s*\\.\\s*)?user_tenant_ids\\s*\\('
+      THEN 'consults auth.user_tenant_ids directly instead of auth.session_tenant_ids() — resolves across EVERY tenant the principal belongs to'
+    WHEN p_expr IS NULL OR btrim(p_expr) = '' OR p_expr ~* '^\\(?\\s*true\\s*\\)?$'
+      THEN 'is permissive with no tenant reference at all — every tenant, every row'
+    ELSE 'does not resolve through auth.session_tenant_ids() — it may be fenced some other way, but nothing here proves it, and an unrecognized shape is not a safe shape'
+  END
+$reason$;
+CREATE OR REPLACE FUNCTION auth.assert_tenant_fence(
+  p_schemas text[] DEFAULT ARRAY['public'],
+  p_exempt_policies text[] DEFAULT ARRAY[]::text[],
+  p_exempt_tables text[] DEFAULT ARRAY[]::text[],
+  p_tenant_columns text[] DEFAULT ARRAY['tenant_id','org_id','organization_id'],
+  p_allow_degraded boolean DEFAULT true
+) RETURNS void
+LANGUAGE plpgsql STABLE SECURITY DEFINER
+SET search_path = pg_catalog, public, pg_temp
+AS $fence_check$
+DECLARE
+  v_offenders text[] := ARRAY[]::text[];
+  v_row record;
+  v_resolver record;
+  v_membership record;
+  v_degraded boolean := false;
+BEGIN
+  -- ---------------------------------------------------------------------
+  -- 1. The resolver itself. If it is missing, every policy referencing it is
+  --    already broken, and nothing below can be interpreted.
+  -- ---------------------------------------------------------------------
+  SELECT p.prosrc, p.prosecdef INTO v_resolver
+    FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
+   WHERE n.nspname = 'auth' AND p.proname = 'session_tenant_ids' LIMIT 1;
+
+  IF v_resolver IS NULL THEN
+    RAISE EXCEPTION 'tenant_fence: auth.session_tenant_ids() is not installed'
+      USING ERRCODE = 'P0001',
+            HINT = 'Apply INSTALL_SESSION_RESOLVER_SQL (applyAuthSchemaMigrations ships it, and @nodii/saga + @nodii/dsar + @nodii/audit-chain install it before their policies).';
+  END IF;
+
+  v_degraded := v_resolver.prosrc LIKE '%DB_RLS_DEGRADED_NO_MEMBERSHIP_MIRROR%';
+
+  IF v_resolver.prosrc !~* 'RAISE\\s+EXCEPTION' THEN
+    v_offenders := v_offenders || 'auth.session_tenant_ids() [session_tenant_ids] does not RAISE on an unbound session — it was replaced with a NULL-returning getter, which restores silent failure';
+  END IF;
+
+  IF NOT v_resolver.prosecdef THEN
+    v_offenders := v_offenders || 'auth.session_tenant_ids() [session_tenant_ids] is not SECURITY DEFINER — it cannot read the membership mirror (permission denied), or will recurse into the mirror''s own policy (54001)';
+  END IF;
+
+  IF v_degraded AND NOT p_allow_degraded THEN
+    v_offenders := v_offenders || 'auth.session_tenant_ids() [session_tenant_ids] is the DEGRADED fence-only resolver — the session tenant is trusted WITHOUT proving membership';
+  END IF;
+
+  -- The stub check applies ONLY to the strict resolver. Under the degraded body
+  -- auth.user_tenant_ids is never consulted, so a stub there is the expected,
+  -- D415-sanctioned terminal state — not a defect. Flagging it would make every
+  -- legitimately-degraded service permanently red, which is how a gate gets
+  -- switched off.
+  IF NOT v_degraded THEN
+    SELECT p.prosrc INTO v_membership
+      FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
+     WHERE n.nspname = 'auth' AND p.proname = 'user_tenant_ids' LIMIT 1;
+    IF v_membership IS NOT NULL
+       AND v_membership.prosrc ~* 'where\\s+false'
+       AND v_membership.prosrc !~* 'from\\s+\\w' THEN
+      v_offenders := v_offenders || 'auth.user_tenant_ids(uuid) [user_tenant_ids] is still the bootstrap stub returning the empty set — the strict resolver intersects to nothing, so the authenticated pool is silently deny-all';
+    END IF;
+  END IF;
+
+  -- ---------------------------------------------------------------------
+  -- 2. The positive rule over every authenticated-applicable policy.
+  -- ---------------------------------------------------------------------
+  FOR v_row IN
+    SELECT n.nspname AS schemaname,
+           c.relname  AS tablename,
+           pol.polname AS policyname,
+           CASE pol.polcmd WHEN 'r' THEN 'SELECT' WHEN 'a' THEN 'INSERT'
+                           WHEN 'w' THEN 'UPDATE' WHEN 'd' THEN 'DELETE'
+                           ELSE 'ALL' END AS cmd,
+           pg_get_expr(pol.polqual, pol.polrelid)      AS qual,
+           pg_get_expr(pol.polwithcheck, pol.polrelid) AS with_check
+      FROM pg_policy pol
+      JOIN pg_class c ON c.oid = pol.polrelid
+      JOIN pg_namespace n ON n.oid = c.relnamespace
+     WHERE n.nspname = ANY(p_schemas)
+       -- RESTRICTIVE policies are ANDed; they can only narrow access, so they
+       -- cannot be the source of a cross-tenant grant.
+       AND pol.polpermissive
+       AND (
+         EXISTS (SELECT 1 FROM unnest(pol.polroles) r WHERE r = 0)
+         OR (
+           EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'authenticated')
+           AND EXISTS (
+             SELECT 1 FROM unnest(pol.polroles) r
+              WHERE pg_has_role('authenticated', r, 'USAGE')
+           )
+         )
+       )
+       AND NOT (pol.polname = ANY(p_exempt_policies))
+       AND NOT ((c.relname || '.' || pol.polname) = ANY(p_exempt_policies))
+       AND NOT (c.relname = ANY(p_exempt_tables))
+       AND NOT ((n.nspname || '.' || c.relname) = ANY(p_exempt_tables))
+     ORDER BY c.relname, pol.polname
+  LOOP
+    -- A policy with NEITHER clause is permissive-everything.
+    IF v_row.qual IS NULL AND v_row.with_check IS NULL THEN
+      v_offenders := v_offenders || format(
+        '%s.%s [%s %s] is permissive with no tenant reference at all — every tenant, every row',
+        v_row.schemaname, v_row.tablename, v_row.policyname, v_row.cmd);
+      CONTINUE;
+    END IF;
+
+    -- EVERY clause present must resolve. A fenced read with an unfenced
+    -- WITH CHECK is a cross-tenant WRITE, which is what the refund incident
+    -- actually exercised.
+    IF v_row.qual IS NOT NULL
+       AND v_row.qual !~* '(auth\\s*\\.\\s*)?session_tenant_ids\\s*\\(' THEN
+      v_offenders := v_offenders || format('%s.%s [%s %s USING] %s :: %s',
+        v_row.schemaname, v_row.tablename, v_row.policyname, v_row.cmd,
+        auth._fence_reason(v_row.qual), v_row.qual);
+    END IF;
+
+    IF v_row.with_check IS NOT NULL
+       AND v_row.with_check !~* '(auth\\s*\\.\\s*)?session_tenant_ids\\s*\\(' THEN
+      v_offenders := v_offenders || format('%s.%s [%s %s WITH CHECK] %s :: %s',
+        v_row.schemaname, v_row.tablename, v_row.policyname, v_row.cmd,
+        auth._fence_reason(v_row.with_check), v_row.with_check);
+    END IF;
+  END LOOP;
+
+  -- ---------------------------------------------------------------------
+  -- 3. Table coverage. THE HOLE A POLICY-LEVEL CHECK CANNOT SEE: a table with
+  --    a tenant column and RLS switched off has no rows in pg_policy to
+  --    inspect, and under the canonical blanket grants it is readable AND
+  --    writable across every tenant — strictly more open than the union
+  --    predicate this release removes.
+  --
+  --    Discovered FROM THE CATALOG, never from a caller-supplied list. The
+  --    author who forgets ENABLE ROW LEVEL SECURITY is the same author who
+  --    forgets the list entry, in the same migration.
+  -- ---------------------------------------------------------------------
+  FOR v_row IN
+    SELECT n.nspname AS schemaname, c.relname AS tablename,
+           c.relkind::text AS relkind, c.relrowsecurity,
+           COALESCE((SELECT true FROM unnest(COALESCE(c.reloptions,'{}')) o
+                      WHERE lower(replace(o,' ','')) = 'security_invoker=true'), false) AS security_invoker
+      FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+     WHERE c.relkind = ANY('{r,p,v,m,f}')
+       AND n.nspname = ANY(p_schemas)
+       AND NOT (c.relname = ANY(p_exempt_tables))
+       AND NOT ((n.nspname || '.' || c.relname) = ANY(p_exempt_tables))
+       AND EXISTS (SELECT 1 FROM pg_attribute a
+                    WHERE a.attrelid = c.oid AND a.attnum > 0
+                      AND NOT a.attisdropped AND a.attname = ANY(p_tenant_columns))
+     ORDER BY n.nspname, c.relname
+  LOOP
+    IF v_row.relkind IN ('v','m','f') THEN
+      -- A view with security_invoker=true executes as the CALLER, so the
+      -- underlying table's RLS applies and the view is genuinely safe.
+      IF v_row.relkind = 'v' AND v_row.security_invoker THEN CONTINUE; END IF;
+      v_offenders := v_offenders || format(
+        '%s.%s exposes a tenant column but cannot enforce RLS (relkind=%s) — a materialized/foreign relation has no row policies at all, and a view without security_invoker=true runs as its OWNER and bypasses the underlying table''s policies',
+        v_row.schemaname, v_row.tablename, v_row.relkind);
+    ELSIF NOT v_row.relrowsecurity THEN
+      v_offenders := v_offenders || format(
+        '%s.%s has a tenant column but ROW LEVEL SECURITY is NOT ENABLED — with the canonical blanket grants this table is readable and writable across EVERY tenant, and no policy is ever consulted',
+        v_row.schemaname, v_row.tablename);
+    END IF;
+  END LOOP;
+
+  IF array_length(v_offenders, 1) > 0 THEN
+    RAISE EXCEPTION 'tenant_fence: % authenticated-pool policy/helper defect(s). A user session must reach exactly ONE tenant — the one the edge resolved from the request — and nothing else, ever.%',
+      array_length(v_offenders, 1),
+      E'\\n  - ' || array_to_string(v_offenders, E'\\n  - ')
+      USING ERRCODE = 'P0001',
+            HINT = 'Regenerate policies with @nodii/db-rls withRls() / generateRlsPolicy(), which emit "<col> IN (SELECT auth.session_tenant_ids())". Nodii-staff cross-tenant access is a different path entirely: the platform_ops pool + withPlatformOpsContext.';
+  END IF;
+END
+$fence_check$;
+GRANT EXECUTE ON FUNCTION auth._fence_reason(text) TO PUBLIC;
+`;
+/** Grant for the gate. Split from the DDL for the same reason every other
+ *  grant in this package is: the roles must exist before the GRANT runs, and
+ *  on a fresh database they do not yet. */
+export const TENANT_FENCE_GATE_GRANTS_SQL = `GRANT EXECUTE ON FUNCTION auth.assert_tenant_fence(text[], text[], text[], text[], boolean) TO nodii_services, authenticated;
+`;
+/** The statement `withUserContext` runs once per process on first authenticated
+ *  checkout. Kept as a named constant so the wiring is greppable from the call
+ *  site and the test-suite asserts the exact text. */
+export const TENANT_FENCE_GATE_CALL_SQL = "SELECT auth.assert_tenant_fence()";
+/**
+ * THE DELIVERY UNIT, whole: the resolver the policies reference, plus the gate
+ * that proves they reference it.
+ *
+ * These ship together because they fail together. A database with the resolver
+ * but no gate has a fence nobody checks; a database with the gate but no
+ * resolver cannot create the policies in the first place. Splitting them would
+ * create a state where a service is half-delivered and neither half complains,
+ * which is the condition this whole release exists to end.
+ *
+ * Every delivery path applies exactly this constant:
+ *   - `applyAuthSchemaMigrations` (@nodii/db-rls)
+ *   - `applySagaMigrations` (@nodii/saga)
+ *   - `applyDsarMigrations` (@nodii/dsar)
+ *   - `applyAuditChainMigrations` (@nodii/audit-chain)
+ *   - the `nodii-db-rls install-fence` CLI, for a service on none of the above
+ *
+ * The three mirrors inline a byte-equal copy rather than importing it, to
+ * preserve their deliberate zero-dependency posture on `@nodii/db-rls`. That
+ * duplication is guarded by a byte-equality test in each mirror's suite, not by
+ * a comment asking people to remember.
+ */
+export function sessionFenceBootstrapSql(installSql) {
+    return `${installSql}${TENANT_FENCE_GATE_SQL}`;
+}
+//# sourceMappingURL=tenant-fence-gate.js.map

package/dist/tenant-fence-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-fence-gate.js","sourceRoot":"","sources":["../src/tenant-fence-gate.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,EAAE;AACF,uEAAuE;AACvE,gFAAgF;AAChF,0EAA0E;AAC1E,+DAA+D;AAC/D,EAAE;AACF,8EAA8E;AAC9E,mBAAmB;AACnB,EAAE;AACF,wEAAwE;AACxE,wEAAwE;AACxE,0EAA0E;AAC1E,6EAA6E;AAC7E,2EAA2E;AAC3E,2EAA2E;AAC3E,0CAA0C;AAC1C,EAAE;AACF,0EAA0E;AAC1E,+EAA+E;AAC/E,8EAA8E;AAC9E,+EAA+E;AAC/E,0BAA0B;AAC1B,EAAE;AACF,0DAA0D;AAC1D,EAAE;AACF,4EAA4E;AAC5E,8EAA8E;AAC9E,0EAA0E;AAC1E,8EAA8E;AAC9E,2EAA2E;AAC3E,8EAA8E;AAC9E,WAAW;AACX,EAAE;AACF,8EAA8E;AAC9E,8EAA8E;AAC9E,4EAA4E;AAC5E,8EAA8E;AAC9E,0EAA0E;AAC1E,6CAA6C;AAC7C,EAAE;AACF,mEAAmE;AACnE,EAAE;AACF,6EAA6E;AAC7E,8EAA8E;AAC9E,gFAAgF;AAChF,8EAA8E;AAC9E,6EAA6E;AAC7E,4CAA4C;AAE5C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyLpC,CAAC;AAEF;;2CAE2C;AAC3C,MAAM,CAAC,MAAM,4BAA4B,GAAG;CAC3C,CAAC;AAEF;;sDAEsD;AACtD,MAAM,CAAC,MAAM,0BAA0B,GAAG,mCAAmC,CAAC;AAE9E;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,wBAAwB,CAAC,UAAkB;IACzD,OAAO,GAAG,UAAU,GAAG,qBAAqB,EAAE,CAAC;AACjD,CAAC"}

package/dist/tenant-fence.d.ts

@@ -0,0 +1,165 @@
+import { DbRlsError } from "./types.js";
+import type { RlsQuerier } from "./verify-rls.js";
+/** Why one policy (or helper) failed the fence check. */
+export type TenantFenceReason = 
+/** THE HOLE. The policy consults `auth.user_tenant_ids` directly — the
+ *  membership union — instead of resolving through the session resolver, so
+ *  it spans every tenant the principal belongs to. This is the shape that
+ *  released a refund. */
+"cross_tenant_union"
+/** Permissive, granted to `authenticated`, with no tenant reference at all —
+ *  `USING (true)` or equivalent. Every tenant, every row. */
+ | "unfenced_permissive"
+/** The positive rule failing in the general case: there IS a predicate, but
+ *  nothing in it resolves through `auth.session_tenant_ids()`. Covers the
+ *  mangled-by-a-sweep case that an absence check would wave through. */
+ | "not_resolved_through_session"
+/** `auth.session_tenant_ids()` is not installed, so every policy referencing
+ *  it is broken. (In practice this surfaces at CREATE POLICY time, since
+ *  Postgres validates the reference then — but a function dropped AFTER the
+ *  policies were created lands here.) */
+ | "resolver_missing"
+/** The resolver exists but does not RAISE on an unbound session — someone
+ *  replaced it with a NULL-returning getter, restoring silent failure. */
+ | "resolver_not_loud"
+/** The resolver exists but is not SECURITY DEFINER, so it cannot read the
+ *  membership mirror and will fail with `permission denied` (or recurse into
+ *  the mirror's own policy and die at stack depth). */
+ | "resolver_not_security_definer"
+/** The DEGRADED, fence-only resolver is installed: the session tenant is
+ *  accepted WITHOUT proving the principal holds it. Legitimate for a service
+ *  with no membership mirror, but never something to be on by accident.
+ *  Reported unless `allowDegradedResolver` is set. */
+ | "resolver_degraded"
+/** `auth.user_tenant_ids` is still the bootstrap stub returning the empty
+ *  set, so the STRICT resolver intersects to nothing and the whole
+ *  authenticated pool is silently deny-all. (P0 drift 199feabc — crm's 430
+ *  dead policies — turned into a loud failure.) */
+ | "membership_helper_is_stub"
+/** THE HOLE A POLICY-LEVEL CHECK CANNOT SEE. The table has a `tenant_id`
+ *  column but `relrowsecurity = false`, so no policy is ever consulted. Since
+ *  the canonical grants are deliberately blanket —
+ *  `GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO
+ *  authenticated`, plus an `ALTER DEFAULT PRIVILEGES` that arms every FUTURE
+ *  table the same way — a table that simply never enables RLS is readable and
+ *  writable across every tenant. It is STRICTLY MORE OPEN than the union
+ *  predicate this release removes, and it passes any check that inspects
+ *  `pg_policies`, because it has no rows there to inspect. */
+ | "rls_disabled_on_tenant_table"
+/** A UNIQUE index on a tenant-scoped table that does NOT include the tenant
+ *  column. RLS filters which rows you can SEE; it does not partition the
+ *  uniqueness namespace. A caller-supplied key unique on its own lets one
+ *  tenant collide with another's row — `INSERT … ON CONFLICT` then either
+ *  raises 23505 (leaking existence) or takes an UPDATE path against a row the
+ *  session cannot see. An idempotent-mint `SELECT` with no tenant predicate
+ *  on such a key returns the other tenant's row outright. */
+ | "tenant_unscoped_unique_index"
+/** A VIEW, MATERIALIZED VIEW, or FOREIGN TABLE exposing a tenant column to
+ *  `authenticated`. A matview cannot have RLS AT ALL; a foreign table's
+ *  policies are not enforced remotely; and a plain view without
+ *  `security_invoker = true` executes with the VIEW OWNER's privileges, so
+ *  the underlying table's RLS is bypassed entirely. Each is a routine
+ *  migration artifact, and the justification for flagging an unprotected
+ *  table applies verbatim: it is strictly more open than the union this
+ *  release removes. */
+ | "unprotected_relation";
+/** One policy (or helper) that failed the fence check. */
+export interface TenantFenceOffender {
+    /** `schema.table`, or `auth.<fn>()` for a helper-level offender. */
+    object: string;
+    /** Policy name, or the helper function name. */
+    policy: string;
+    /** `SELECT` / `INSERT` / `UPDATE` / `DELETE` / `ALL`, or `-` for helpers. */
+    command: string;
+    reason: TenantFenceReason;
+    /** The deparsed expression that failed, straight from the catalog. */
+    expression: string | null;
+}
+/**
+ * Thrown by {@link verifyTenantFence}. Carries the structured offender list so
+ * a `db:setup` gate can render a precise failure — and so a caller can tell
+ * "this is a stale service that needs regenerating" apart from "someone
+ * hand-wrote a cross-tenant policy in prod".
+ */
+export declare class TenantFenceError extends DbRlsError {
+    readonly offenders: readonly TenantFenceOffender[];
+    constructor(offenders: readonly TenantFenceOffender[]);
+}
+export interface VerifyTenantFenceOpts {
+    /** Schema(s) to check. Defaults to `["public"]`. */
+    schema?: string | readonly string[];
+    /** Restrict to these table names (bare or `schema.table`). Omit to check
+     *  every table in `schema` that has an `authenticated` policy. */
+    tables?: readonly string[];
+    /**
+     * Policies exempt from the POSITIVE rule, as `table.policy_name` or just
+     * `policy_name`. Use sparingly, and argue it at the call site — the whole
+     * value of a positive assertion is that the exemptions are enumerated in one
+     * reviewable place instead of being implicit in a regex.
+     *
+     * The legitimate case is a policy that is genuinely not tenant-scoped: a
+     * public-listing row, a platform-global reference table exposed to
+     * `authenticated` (08-rls § 7.6), or a self-row policy keyed on
+     * `auth.get_user_id()` with no tenant dimension.
+     */
+    exemptPolicies?: readonly string[];
+    /** Accept the degraded fence-only resolver. Defaults to `false`. */
+    allowDegradedResolver?: boolean;
+    /** Also verify the `auth.*` helper shapes. Defaults to `true`. */
+    checkHelpers?: boolean;
+    /**
+     * Also assert that every table carrying a tenant column has RLS ENABLED.
+     * Defaults to `true`. This is the check that catches the table a migration
+     * simply never protected — see `rls_disabled_on_tenant_table`.
+     */
+    checkTableCoverage?: boolean;
+    /**
+     * Also flag UNIQUE indexes on tenant-scoped tables that omit the tenant
+     * column. Defaults to `true`.
+     */
+    checkUniqueIndexes?: boolean;
+    /** An ADDITIONAL tenant column name to recognise, on top of
+     *  {@link tenantColumns}. Kept for source compatibility. */
+    tenantColumn?: string;
+    /** Column names that mark a relation as tenant-scoped. Defaults to
+     *  `["tenant_id", "org_id", "organization_id"]`. Keying coverage on a SINGLE
+     *  configured name exempted every table using one of the others — including
+     *  `org_id`, which `withRls` explicitly supports and ships a test for. */
+    tenantColumns?: readonly string[];
+    /**
+     * Tables exempt from the table-level checks, bare or `schema.table`.
+     *
+     * The honest case is a tenant-scoped table deliberately left RLS-free
+     * because it is owner-only and no non-owner role is granted on it. Argue it
+     * at the call site — this list is the record of every place the fleet has
+     * decided a tenant column does not imply a tenant boundary.
+     */
+    exemptTables?: readonly string[];
+}
+/** Does this expression resolve through the session resolver? */
+export declare function resolvesThroughSession(expr: string | null): boolean;
+/** Does this expression consult the raw membership union? */
+export declare function consultsMembershipUnion(expr: string | null): boolean;
+/**
+ * Classify ONE authenticated policy. Exported so the test-suite can assert the
+ * classification directly without standing up every offending shape in the
+ * catalog, and so a caller can reuse the rule in a bespoke gate.
+ *
+ * The order matters: the two SPECIFIC diagnoses come first because they tell a
+ * reader what to do, and the general positive-rule failure is the fallback.
+ */
+export declare function classifyAuthPolicy(expr: string | null): TenantFenceReason | null;
+/**
+ * Asserts that EVERY policy granted to `authenticated` resolves through
+ * `auth.session_tenant_ids()`, and that the resolver itself is installed, loud,
+ * and SECURITY DEFINER.
+ *
+ * @throws {TenantFenceError} listing every offender, with the deparsed
+ * expression straight from the catalog.
+ */
+export declare function verifyTenantFence(querier: RlsQuerier, opts?: VerifyTenantFenceOpts): Promise<void>;
+/** The bootstrap stub is `SELECT NULL::uuid WHERE false` — any body that can
+ *  never return a row. Matched structurally rather than by exact string so a
+ *  reformatted copy is still caught. */
+export declare function isStubMembershipHelper(prosrc: string): boolean;
+//# sourceMappingURL=tenant-fence.d.ts.map

package/dist/tenant-fence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-fence.d.ts","sourceRoot":"","sources":["../src/tenant-fence.ts"],"names":[],"mappings":"AAsDA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,yDAAyD;AACzD,MAAM,MAAM,iBAAiB;AAC3B;;;yBAGyB;AACvB,oBAAoB;AACtB;6DAC6D;GAC3D,qBAAqB;AACvB;;wEAEwE;GACtE,8BAA8B;AAChC;;;yCAGyC;GACvC,kBAAkB;AACpB;0EAC0E;GACxE,mBAAmB;AACrB;;uDAEuD;GACrD,+BAA+B;AACjC;;;sDAGsD;GACpD,mBAAmB;AACrB;;;mDAGmD;GACjD,2BAA2B;AAC7B;;;;;;;;8DAQ8D;GAC5D,8BAA8B;AAChC;;;;;;6DAM6D;GAC3D,8BAA8B;AAChC;;;;;;;uBAOuB;GACrB,sBAAsB,CAAC;AAE3B,0DAA0D;AAC1D,MAAM,WAAW,mBAAmB;IAClC,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,sEAAsE;IACtE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,UAAU;IAC9C,QAAQ,CAAC,SAAS,EAAE,SAAS,mBAAmB,EAAE,CAAC;gBACvC,SAAS,EAAE,SAAS,mBAAmB,EAAE;CAKtD;AAqCD,MAAM,WAAW,qBAAqB;IACpC,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IACpC;sEACkE;IAClE,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B;;;;;;;;;;OAUG;IACH,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,oEAAoE;IACpE,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,kEAAkE;IAClE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;gEAC4D;IAC5D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;8EAG0E;IAC1E,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAmCD,iEAAiE;AACjE,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAEnE;AAED,6DAA6D;AAC7D,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAEpE;AAiBD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,GAAG,IAAI,GAClB,iBAAiB,GAAG,IAAI,CAO1B;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,UAAU,EACnB,IAAI,GAAE,qBAA0B,GAC/B,OAAO,CAAC,IAAI,CAAC,CAkHf;AAqVD;;wCAEwC;AACxC,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE9D"}