@nodii/db-rls 0.12.0 → 0.14.0

package/README.md

@@ -1,5 +1,83 @@
 # @nodii/db-rls
 
-Placeholder package at v0.0.1. Implementation lands at v0.1.0 per the locked feature_doc.
+Three-pool RLS dispatch + GUC binding + policy DDL generation for the Nodii
+microservice stack.
 
 **Spec**: `https://planning.dev.nucleus-cloud.in/api/v1/feature-docs?serviceId=nodii-libs&docKey=db-rls`
+
+## Unforgeable tenant binding
+
+On the **authenticated** path the tenant is not a parameter. It is read from a
+request-scoped verified-claims context that auth middleware binds once:
+
+```ts
+// ONCE, in auth middleware, immediately after JWT verification.
+app.use(async (c, next) => {
+  const claims = await verifyJwt(c.req.header("authorization"));
+  return runWithVerifiedTenantClaims(
+    { userId: claims.sub, tenantId: claims.tenant_id },
+    () => next(),
+  );
+});
+
+// Everywhere else — no tenant, and nowhere to put one.
+const rows = await withUserContextDbPostgresJs(async (db) =>
+  db.select().from(invoices),
+);
+```
+
+`withUserContext` / `withUserContextDb` / `withUserContextDbPostgresJs` take the
+callback as their **only** argument. `autoDispatch(fn)` is the same path;
+`autoDispatch({ systemTenantId }, fn)` is the system leg.
+
+Why: the previous shape, `withUserContext({ userId, tenantId }, fn)`, let a
+handler pass a request-derived tenant instead of the verified claim, and RLS
+accepted `app.tenant_id` without ever proving the principal held it. Membership
+was checked once at login in `nodii-auth`, and nowhere near the database.
+
+**Workers, cron, S2S and webhooks are unaffected** — they have a legitimately
+resolved tenant and no user claim, and keep their explicit parameter:
+`withSystemContext({ tenantId }, fn)`. Migrations use `withOwnerContext`
+(`NODII_ENV=migrate`-gated); Nodii staff cross-tenant access uses
+`withPlatformOpsContext` (RBAC-gated, a different predicate).
+
+There is **no escape hatch** — no option to override the tenant. Binding is
+refused if claims are already bound (a handler cannot rebind to a different
+tenant), bound claims are copied and frozen (they cannot be mutated after the
+fact), and a blank / missing / non-string `userId` or `tenantId` is refused at
+bind time rather than binding an empty GUC that reads as "no rows". With no
+claims bound the authenticated helpers throw `NoVerifiedTenantClaims` before
+acquiring a pool — never a default, never a fallback to a passed value.
+
+## The system pool is fenced against authenticated fall-through
+
+The services-pool predicate is the bare `tenant_id = auth.get_tenant_id()` —
+no membership proof. So an authenticated request that falls through to
+`withSystemContext({ tenantId: req.body.tenantId }, fn)` re-opens exactly the
+forgery the claims binding closes: the handler supplies the tenant, and
+nothing checks the principal holds it. That fall-through is the seam where the
+₹250,000 cross-tenant refund reproduced.
+
+Therefore, **inside a claims-bound request** (`hasVerifiedTenantClaims()` is
+true), `withSystemContext` / `withSystemContextDb` /
+`withSystemContextDbPostgresJs` (and `autoDispatch`'s system leg) **throw
+`SystemContextUnderClaimsRefused`** — before any pool is acquired — unless the
+caller passes an explicit, non-blank `{ reason }`:
+
+```ts
+// Deliberate system work inside a request — named, counted, greppable.
+await withSystemContext(
+  { tenantId, reason: "outbox-emit: invoice.settled fan-out" },
+  async (tx) => { ... },
+);
+```
+
+A sanctioned escape is emitted to telemetry as
+`db_rls.cross_pool_nesting_total{outer="authenticated", inner="services",
+reason}`, so every crossing is observable. **Outside any claims-bound context
+(boot, cron, workers, S2S, webhooks) nothing changes** — no reason is needed
+and the helpers behave exactly as before. That compat property is what keeps
+this fence from breaking every worker in the fleet.
+
+Full migration steps, including the `createSecureClient` before/after, are in
+`.changeset/db-rls-unforgeable-tenant-binding.md`.

package/bin/migrate-gen.mjs

@@ -7,12 +7,15 @@
 // Subcommands:
 //   migrate-gen <serviceName> [--out <dir>] [--stub]
 //   verify-rls  --tables <a,b,c> [--ref <x,y>] [--schema <name>] [--db <url>]
+//   install-fence [--db <url>] [--skip-grants]
+//   verify-fence  [--db <url>] [--schema <name>] [--strict-only]
 //
 // (Filename kept as migrate-gen.mjs for the package.json `bin` mapping;
 // it is the single `nodii-db-rls` entrypoint, not migrate-gen only.)
 
 import { runMigrateGenCli } from "../dist/migrate-gen.js";
 import { runVerifyRlsCli } from "../dist/verify-rls-cli.js";
+import { runInstallFenceCli, runVerifyFenceCli } from "../dist/fence-cli.js";
 
 const argv = process.argv.slice(2);
 const sub = argv[0];
@@ -22,6 +25,14 @@ if (sub === "verify-rls") {
   // Coverage failures (1) + usage (2) go to stderr; success (0) to stdout.
   (code === 0 ? console.log : console.error)(message);
   process.exit(code);
+} else if (sub === "install-fence") {
+  const { code, message } = await runInstallFenceCli(argv.slice(1));
+  (code === 0 ? console.log : console.error)(message);
+  process.exit(code);
+} else if (sub === "verify-fence") {
+  const { code, message } = await runVerifyFenceCli(argv.slice(1));
+  (code === 0 ? console.log : console.error)(message);
+  process.exit(code);
 } else {
   // migrate-gen (default + back-compat: runMigrateGenCli accepts the
   // leading "migrate-gen" token and prints usage on a missing serviceName).

package/dist/auth-schema.d.ts

@@ -4,7 +4,7 @@ import type { Pool, PoolClient } from "pg";
  * compliance requirement. Identical byte-equal payload across TS / Python
  * / Go ports (asserted by the parity-fence CI).
  */
-export declare const AUTH_SCHEMA_SQL = "CREATE SCHEMA IF NOT EXISTS auth;\n\nCREATE OR REPLACE FUNCTION auth.set_user_id(p_user_id uuid) RETURNS void\nLANGUAGE sql AS $$ SELECT set_config('app.user_id', p_user_id::text, true) $$;\n\nCREATE OR REPLACE FUNCTION auth.set_tenant_id(p_tenant_id uuid) RETURNS void\nLANGUAGE sql AS $$ SELECT set_config('app.tenant_id', p_tenant_id::text, true) $$;\n\nCREATE OR REPLACE FUNCTION auth.init(p_user_id uuid, p_tenant_id uuid) RETURNS void\nLANGUAGE sql AS $$\n  SELECT set_config('app.user_id', p_user_id::text, true);\n  SELECT set_config('app.tenant_id', p_tenant_id::text, true);\n$$;\n\nCREATE OR REPLACE FUNCTION auth.init_tenant(p_tenant_id uuid) RETURNS void\nLANGUAGE sql AS $$ SELECT set_config('app.tenant_id', p_tenant_id::text, true) $$;\n\nCREATE OR REPLACE FUNCTION auth.get_user_id() RETURNS uuid\nLANGUAGE sql STABLE AS $$ SELECT nullif(current_setting('app.user_id', true), '')::uuid $$;\n\nCREATE OR REPLACE FUNCTION auth.get_tenant_id() RETURNS uuid\nLANGUAGE sql STABLE AS $$ SELECT nullif(current_setting('app.tenant_id', true), '')::uuid $$;\n\n-- Stub variant. Replaced in-place by migrate-gen's 0001_user_tenant_ids.sql\n-- once the service has employees_mirror + customers_mirror tables.\nCREATE OR REPLACE FUNCTION auth.user_tenant_ids(p_user_id uuid) RETURNS SETOF uuid\nLANGUAGE sql STABLE AS $$ SELECT NULL::uuid WHERE false $$;\n";
+export declare const AUTH_SCHEMA_SQL = "CREATE SCHEMA IF NOT EXISTS auth;\n\nCREATE OR REPLACE FUNCTION auth.set_user_id(p_user_id uuid) RETURNS void\nLANGUAGE sql AS $$ SELECT set_config('app.user_id', p_user_id::text, true) $$;\n\nCREATE OR REPLACE FUNCTION auth.set_tenant_id(p_tenant_id uuid) RETURNS void\nLANGUAGE sql AS $$ SELECT set_config('app.tenant_id', p_tenant_id::text, true) $$;\n\nCREATE OR REPLACE FUNCTION auth.init(p_user_id uuid, p_tenant_id uuid) RETURNS void\nLANGUAGE sql AS $$\n  SELECT set_config('app.user_id', p_user_id::text, true);\n  SELECT set_config('app.tenant_id', p_tenant_id::text, true);\n$$;\n\nCREATE OR REPLACE FUNCTION auth.init_tenant(p_tenant_id uuid) RETURNS void\nLANGUAGE sql AS $$ SELECT set_config('app.tenant_id', p_tenant_id::text, true) $$;\n\nCREATE OR REPLACE FUNCTION auth.get_user_id() RETURNS uuid\nLANGUAGE sql STABLE AS $$ SELECT nullif(current_setting('app.user_id', true), '')::uuid $$;\n\nCREATE OR REPLACE FUNCTION auth.get_tenant_id() RETURNS uuid\nLANGUAGE sql STABLE AS $$ SELECT nullif(current_setting('app.tenant_id', true), '')::uuid $$;\n\n-- Stub variant, installed ONLY IF ABSENT. Replaced in-place by migrate-gen's\n-- 0001_user_tenant_ids.sql once the service has employees_mirror +\n-- customers_mirror tables.\n--\n-- IT IS A GUARDED CREATE, NOT A `CREATE OR REPLACE`, AND THAT IS LOAD-BEARING.\n-- As an unguarded REPLACE this statement silently overwrote a service's REAL\n-- membership helper with the dead stub every time the auth schema was\n-- re-applied \u2014 turning a correctly-fenced service into a deny-all one with no\n-- error, which is the same fail-silent shape this release exists to remove.\n-- It also made `INSTALL_SESSION_RESOLVER_SQL` unable to classify: running\n-- immediately after this block, it would read the stub this block had just\n-- stamped and conclude EVERY service needed the degraded body.\n--\n-- A bootstrap default must never win against the real thing it is standing in\n-- for.\nDO $ensure_user_tenant_ids$\nBEGIN\n  IF to_regprocedure('auth.user_tenant_ids(uuid)') IS NULL THEN\n    EXECUTE $utid$CREATE FUNCTION auth.user_tenant_ids(p_user_id uuid) RETURNS SETOF uuid\nLANGUAGE sql STABLE AS $utid_body$ SELECT NULL::uuid WHERE false $utid_body$;$utid$;\n  END IF;\nEND\n$ensure_user_tenant_ids$;\n";
 /**
  * `auth.session_tenant_ids()` — THE authenticated-pool resolver.
  *
@@ -124,6 +124,64 @@ export declare const SESSION_TENANT_IDS_DEGRADED_SQL = "CREATE OR REPLACE FUNCTI
 /** Grant for the resolver. Separate from {@link AUTH_SCHEMA_GRANTS_SQL} for the
  *  same reason: the roles must exist before the GRANT runs. */
 export declare const SESSION_TENANT_IDS_GRANTS_SQL = "GRANT EXECUTE ON FUNCTION auth.session_tenant_ids() TO nodii_services, authenticated;\n";
+/**
+ * THE DELIVERY UNIT. One idempotent, re-runnable, SELF-CLASSIFYING statement
+ * that installs whichever resolver body this database can actually support.
+ *
+ * WHY IT SELF-CLASSIFIES RATHER THAN TAKING A FLAG.
+ *
+ * The strict and degraded bodies are not interchangeable, and picking the wrong
+ * one is silent in BOTH directions:
+ *
+ *   - strict on a service whose `auth.user_tenant_ids` is the bootstrap stub
+ *     (`SELECT NULL::uuid WHERE false`) intersects to the EMPTY SET, so every
+ *     authenticated policy denies every row. No error. Measured live on
+ *     `nodii-dev-postgres`: crm carries 507 authenticated policies, and a strict
+ *     install there takes ALL 507 dark, not just the 85 already dead.
+ *   - degraded on a service that HAS a real membership mirror silently drops
+ *     the principal check, which is the defence-in-depth this release exists to
+ *     add.
+ *
+ * A caller-supplied boolean makes that choice a thing somebody has to know. The
+ * library shipped exactly such a list in prose — and it was WRONG BY SIX
+ * SERVICES on the first pass and had to be re-derived from the repos. A list
+ * that was wrong once, maintained by hand, across fifteen repos, on a
+ * fail-silent switch, is not a control. It is a countdown.
+ *
+ * So the choice is made from what the database ACTUALLY CONTAINS, at the moment
+ * of install, by the same structural test `isStubMembershipHelper` applies in
+ * TypeScript: a membership helper that is absent, or whose body can never
+ * return a row, cannot support the intersect. Nobody has to know anything, and
+ * there is no list to get wrong.
+ *
+ * D415 (LOCKED) is the governing decision: a single-tenant-session service
+ * whose `user_tenant_ids` is absent, stubbed or uncalled MAY fence on the
+ * session tenant — isolation-equivalent, forfeiting no cross-tenant protection.
+ * The predicate at every call site is IDENTICAL for both bodies, which is what
+ * makes this substitutable at all.
+ *
+ * IT IS ALSO D415's SUNSET, AUTOMATED. D415's exit path is "land a membership
+ * mirror → repoint the helper → swap in the strict body". Because this block
+ * re-reads the catalog on EVERY run and is `CREATE OR REPLACE`, the swap
+ * happens by itself on the next boot after the mirror lands. Nobody files a
+ * follow-up ticket, because there is nothing to follow up.
+ *
+ * THE ONE-WAY RATCHET. The condition is "absent OR stub", so a real helper
+ * ALWAYS yields strict. This block can upgrade degraded → strict; it can never
+ * downgrade strict → degraded. That direction is the one that matters: it means
+ * this delivery path cannot overwrite a correctly-strict service, and cannot
+ * overwrite crm's deliberately-degraded body with a strict one either, because
+ * crm's helper is still the stub and will keep classifying as such until it
+ * genuinely isn't.
+ *
+ * Byte-identical across the TS / Go / Python ports (asserted by the parity
+ * test). The nested dollar-quote tags are all distinct — `$fence_install$`
+ * outer, `$fence_strict$` / `$fence_degraded$` for the EXECUTE literals,
+ * `$session$` inside the bodies — so the statement survives every dollar-quote
+ * -aware splitter in the fleet, including the ones in @nodii/saga and
+ * @nodii/dsar that split the mirrors' DDL on `;\n`.
+ */
+export declare const INSTALL_SESSION_RESOLVER_SQL: string;
 /**
  * Grants for the 7 helper functions. Emitted separately because they
  * reference roles that must exist before the GRANT runs — applied last
@@ -154,6 +212,34 @@ export declare function applyAuthSchemaMigrations(client: AnyExecutor, opts?: {
     includeGrants?: boolean;
     degradedSessionResolver?: boolean;
 }): Promise<void>;
+/**
+ * THE WHOLE DELIVERY UNIT AS ONE STRING — resolver + gate, self-classifying,
+ * idempotent, re-runnable, and safe to apply on every boot.
+ *
+ * This is what the three mirrors inline byte-equal, what the CLI applies, and
+ * what a service with no other delivery path should call directly from its boot
+ * sequence, BEFORE any code that opens an authenticated transaction:
+ *
+ *     import { applySessionFenceBootstrap } from "@nodii/db-rls";
+ *     await applySessionFenceBootstrap(ownerSql);
+ *
+ * Grants are separate (as everywhere else in this package) because the runtime
+ * roles must exist before a GRANT naming them can run, and on a fresh database
+ * they do not yet.
+ */
+export declare const SESSION_FENCE_BOOTSTRAP_SQL: string;
+/**
+ * Apply {@link SESSION_FENCE_BOOTSTRAP_SQL} against an owner-privileged client.
+ *
+ * Idempotent and safe on every boot: the resolver and gate are
+ * `CREATE OR REPLACE`, the schema is `IF NOT EXISTS`, and the body selection
+ * re-derives from the catalog each run — so a service that lands a membership
+ * mirror upgrades itself from the degraded body to the strict one on its next
+ * restart, with no migration and no policy change (D415's exit path).
+ */
+export declare function applySessionFenceBootstrap(client: AnyExecutor, opts?: {
+    includeGrants?: boolean;
+}): Promise<void>;
 /**
  * Composite full DDL — the schema + helpers + grants, joined.
  * Provided for migrate-gen + parity-fence byte-equality.

package/dist/auth-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-schema.d.ts","sourceRoot":"","sources":["../src/auth-schema.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAE3C;;;;GAIG;AACH,eAAO,MAAM,eAAe,s1CA2B3B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,eAAO,MAAM,sBAAsB,iqCAuBlC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kCAAkC,yCACP,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,eAAO,MAAM,+BAA+B,isCAwB3C,CAAC;AAEF;+DAC+D;AAC/D,eAAO,MAAM,6BAA6B,4FACzC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,8oBAQlC,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtC;AAED,KAAK,WAAW,GAAG,IAAI,GAAG,UAAU,GAAG,WAAW,CAAC;AAEnD;;;;;;;;;;;GAWG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,WAAW,EACnB,IAAI,GAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAC;IAAC,uBAAuB,CAAC,EAAE,OAAO,CAAA;CAAO,GACxE,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,GAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAO,GACrC,MAAM,CAKR"}
+{"version":3,"file":"auth-schema.d.ts","sourceRoot":"","sources":["../src/auth-schema.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAO3C;;;;GAIG;AACH,eAAO,MAAM,eAAe,0uEA8C3B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,eAAO,MAAM,sBAAsB,iqCAuBlC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kCAAkC,yCACP,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,eAAO,MAAM,+BAA+B,isCAwB3C,CAAC;AAEF;+DAC+D;AAC/D,eAAO,MAAM,6BAA6B,4FACzC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,eAAO,MAAM,4BAA4B,QA4BxC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,8oBAQlC,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtC;AAED,KAAK,WAAW,GAAG,IAAI,GAAG,UAAU,GAAG,WAAW,CAAC;AAEnD;;;;;;;;;;;GAWG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,WAAW,EACnB,IAAI,GAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAC;IAAC,uBAAuB,CAAC,EAAE,OAAO,CAAA;CAAO,GACxE,OAAO,CAAC,IAAI,CAAC,CAgCf;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,2BAA2B,EAAE,MAEzC,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAsB,0BAA0B,CAC9C,MAAM,EAAE,WAAW,EACnB,IAAI,GAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAO,GACrC,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,GAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAO,GACrC,MAAM,CAKR"}

package/dist/auth-schema.js

@@ -19,6 +19,7 @@
 // fails closed if a service applies the helpers but hasn't yet emitted
 // the real per-service helper via `migrate-gen`. Once `migrate-gen` ships
 // the real helper, `CREATE OR REPLACE` replaces this stub in place.
+import { sessionFenceBootstrapSql, TENANT_FENCE_GATE_GRANTS_SQL, TENANT_FENCE_GATE_SQL, } from "./tenant-fence-gate.js";
 /**
  * Canonical SQL string exported as a module-level constant per the R1
  * compliance requirement. Identical byte-equal payload across TS / Python
@@ -47,10 +48,29 @@ LANGUAGE sql STABLE AS $$ SELECT nullif(current_setting('app.user_id', true), ''
 CREATE OR REPLACE FUNCTION auth.get_tenant_id() RETURNS uuid
 LANGUAGE sql STABLE AS $$ SELECT nullif(current_setting('app.tenant_id', true), '')::uuid $$;
 
--- Stub variant. Replaced in-place by migrate-gen's 0001_user_tenant_ids.sql
--- once the service has employees_mirror + customers_mirror tables.
-CREATE OR REPLACE FUNCTION auth.user_tenant_ids(p_user_id uuid) RETURNS SETOF uuid
-LANGUAGE sql STABLE AS $$ SELECT NULL::uuid WHERE false $$;
+-- Stub variant, installed ONLY IF ABSENT. Replaced in-place by migrate-gen's
+-- 0001_user_tenant_ids.sql once the service has employees_mirror +
+-- customers_mirror tables.
+--
+-- IT IS A GUARDED CREATE, NOT A \`CREATE OR REPLACE\`, AND THAT IS LOAD-BEARING.
+-- As an unguarded REPLACE this statement silently overwrote a service's REAL
+-- membership helper with the dead stub every time the auth schema was
+-- re-applied — turning a correctly-fenced service into a deny-all one with no
+-- error, which is the same fail-silent shape this release exists to remove.
+-- It also made \`INSTALL_SESSION_RESOLVER_SQL\` unable to classify: running
+-- immediately after this block, it would read the stub this block had just
+-- stamped and conclude EVERY service needed the degraded body.
+--
+-- A bootstrap default must never win against the real thing it is standing in
+-- for.
+DO $ensure_user_tenant_ids$
+BEGIN
+  IF to_regprocedure('auth.user_tenant_ids(uuid)') IS NULL THEN
+    EXECUTE $utid$CREATE FUNCTION auth.user_tenant_ids(p_user_id uuid) RETURNS SETOF uuid
+LANGUAGE sql STABLE AS $utid_body$ SELECT NULL::uuid WHERE false $utid_body$;$utid$;
+  END IF;
+END
+$ensure_user_tenant_ids$;
 `;
 /**
  * `auth.session_tenant_ids()` — THE authenticated-pool resolver.
@@ -219,6 +239,92 @@ $session$;
  *  same reason: the roles must exist before the GRANT runs. */
 export const SESSION_TENANT_IDS_GRANTS_SQL = `GRANT EXECUTE ON FUNCTION auth.session_tenant_ids() TO nodii_services, authenticated;
 `;
+/**
+ * THE DELIVERY UNIT. One idempotent, re-runnable, SELF-CLASSIFYING statement
+ * that installs whichever resolver body this database can actually support.
+ *
+ * WHY IT SELF-CLASSIFIES RATHER THAN TAKING A FLAG.
+ *
+ * The strict and degraded bodies are not interchangeable, and picking the wrong
+ * one is silent in BOTH directions:
+ *
+ *   - strict on a service whose `auth.user_tenant_ids` is the bootstrap stub
+ *     (`SELECT NULL::uuid WHERE false`) intersects to the EMPTY SET, so every
+ *     authenticated policy denies every row. No error. Measured live on
+ *     `nodii-dev-postgres`: crm carries 507 authenticated policies, and a strict
+ *     install there takes ALL 507 dark, not just the 85 already dead.
+ *   - degraded on a service that HAS a real membership mirror silently drops
+ *     the principal check, which is the defence-in-depth this release exists to
+ *     add.
+ *
+ * A caller-supplied boolean makes that choice a thing somebody has to know. The
+ * library shipped exactly such a list in prose — and it was WRONG BY SIX
+ * SERVICES on the first pass and had to be re-derived from the repos. A list
+ * that was wrong once, maintained by hand, across fifteen repos, on a
+ * fail-silent switch, is not a control. It is a countdown.
+ *
+ * So the choice is made from what the database ACTUALLY CONTAINS, at the moment
+ * of install, by the same structural test `isStubMembershipHelper` applies in
+ * TypeScript: a membership helper that is absent, or whose body can never
+ * return a row, cannot support the intersect. Nobody has to know anything, and
+ * there is no list to get wrong.
+ *
+ * D415 (LOCKED) is the governing decision: a single-tenant-session service
+ * whose `user_tenant_ids` is absent, stubbed or uncalled MAY fence on the
+ * session tenant — isolation-equivalent, forfeiting no cross-tenant protection.
+ * The predicate at every call site is IDENTICAL for both bodies, which is what
+ * makes this substitutable at all.
+ *
+ * IT IS ALSO D415's SUNSET, AUTOMATED. D415's exit path is "land a membership
+ * mirror → repoint the helper → swap in the strict body". Because this block
+ * re-reads the catalog on EVERY run and is `CREATE OR REPLACE`, the swap
+ * happens by itself on the next boot after the mirror lands. Nobody files a
+ * follow-up ticket, because there is nothing to follow up.
+ *
+ * THE ONE-WAY RATCHET. The condition is "absent OR stub", so a real helper
+ * ALWAYS yields strict. This block can upgrade degraded → strict; it can never
+ * downgrade strict → degraded. That direction is the one that matters: it means
+ * this delivery path cannot overwrite a correctly-strict service, and cannot
+ * overwrite crm's deliberately-degraded body with a strict one either, because
+ * crm's helper is still the stub and will keep classifying as such until it
+ * genuinely isn't.
+ *
+ * Byte-identical across the TS / Go / Python ports (asserted by the parity
+ * test). The nested dollar-quote tags are all distinct — `$fence_install$`
+ * outer, `$fence_strict$` / `$fence_degraded$` for the EXECUTE literals,
+ * `$session$` inside the bodies — so the statement survives every dollar-quote
+ * -aware splitter in the fleet, including the ones in @nodii/saga and
+ * @nodii/dsar that split the mirrors' DDL on `;\n`.
+ */
+export const INSTALL_SESSION_RESOLVER_SQL = `CREATE SCHEMA IF NOT EXISTS auth;
+DO $fence_install$
+DECLARE
+  v_src text;
+  v_is_stub boolean;
+BEGIN
+  SELECT p.prosrc INTO v_src
+    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;
+
+  -- Structural, not an exact-string compare: the bootstrap stub is
+  -- \`SELECT NULL::uuid WHERE false\` — an unsatisfiable WHERE and no FROM. A
+  -- reformatted or re-indented copy of the same dead body still classifies as a
+  -- stub. Mirrors isStubMembershipHelper() in tenant-fence.ts exactly; the two
+  -- are asserted equivalent in the test-suite so a fix to one cannot leave the
+  -- other behind.
+  v_is_stub := v_src IS NULL
+               OR (v_src ~* 'where\\s+false' AND v_src !~* 'from\\s+\\w');
+
+  IF v_is_stub THEN
+    EXECUTE $fence_degraded$${SESSION_TENANT_IDS_DEGRADED_SQL.trimEnd()}$fence_degraded$;
+  ELSE
+    EXECUTE $fence_strict$${SESSION_TENANT_IDS_SQL.trimEnd()}$fence_strict$;
+  END IF;
+END
+$fence_install$;
+`;
 /**
  * Grants for the 7 helper functions. Emitted separately because they
  * reference roles that must exist before the GRANT runs — applied last
@@ -257,12 +363,56 @@ export async function applyAuthSchemaMigrations(client, opts = {}) {
     // CREATE POLICY time, so the migration itself fails with `function
     // auth.session_tenant_ids() does not exist`. Installing both together makes
     // that unreachable.
+    //
+    // WHICH BODY IS NOT A DECISION THIS FUNCTION MAKES. It is derived from the
+    // membership helper actually present in THIS database — see
+    // INSTALL_SESSION_RESOLVER_SQL. `degradedSessionResolver` remains as an
+    // explicit override for the one case derivation cannot cover: a service that
+    // has a real-looking helper but knows it is not yet populated. Passing it is
+    // a deliberate, argued act; the default is derivation, so a caller who knows
+    // nothing gets the right body.
     await exec.query(opts.degradedSessionResolver
         ? SESSION_TENANT_IDS_DEGRADED_SQL
-        : SESSION_TENANT_IDS_SQL);
+        : INSTALL_SESSION_RESOLVER_SQL);
+    // The gate ships with the resolver, always. See sessionFenceBootstrapSql.
+    await exec.query(TENANT_FENCE_GATE_SQL);
     if (includeGrants) {
         await exec.query(AUTH_SCHEMA_GRANTS_SQL);
         await exec.query(SESSION_TENANT_IDS_GRANTS_SQL);
+        await exec.query(TENANT_FENCE_GATE_GRANTS_SQL);
+    }
+}
+/**
+ * THE WHOLE DELIVERY UNIT AS ONE STRING — resolver + gate, self-classifying,
+ * idempotent, re-runnable, and safe to apply on every boot.
+ *
+ * This is what the three mirrors inline byte-equal, what the CLI applies, and
+ * what a service with no other delivery path should call directly from its boot
+ * sequence, BEFORE any code that opens an authenticated transaction:
+ *
+ *     import { applySessionFenceBootstrap } from "@nodii/db-rls";
+ *     await applySessionFenceBootstrap(ownerSql);
+ *
+ * Grants are separate (as everywhere else in this package) because the runtime
+ * roles must exist before a GRANT naming them can run, and on a fresh database
+ * they do not yet.
+ */
+export const SESSION_FENCE_BOOTSTRAP_SQL = sessionFenceBootstrapSql(INSTALL_SESSION_RESOLVER_SQL);
+/**
+ * Apply {@link SESSION_FENCE_BOOTSTRAP_SQL} against an owner-privileged client.
+ *
+ * Idempotent and safe on every boot: the resolver and gate are
+ * `CREATE OR REPLACE`, the schema is `IF NOT EXISTS`, and the body selection
+ * re-derives from the catalog each run — so a service that lands a membership
+ * mirror upgrades itself from the degraded body to the strict one on its next
+ * restart, with no migration and no policy change (D415's exit path).
+ */
+export async function applySessionFenceBootstrap(client, opts = {}) {
+    const exec = client;
+    await exec.query(SESSION_FENCE_BOOTSTRAP_SQL);
+    if (opts.includeGrants ?? false) {
+        await exec.query(SESSION_TENANT_IDS_GRANTS_SQL);
+        await exec.query(TENANT_FENCE_GATE_GRANTS_SQL);
     }
 }
 /**

package/dist/auth-schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth-schema.js","sourceRoot":"","sources":["../src/auth-schema.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,EAAE;AACF,oEAAoE;AACpE,qEAAqE;AACrE,2BAA2B;AAC3B,EAAE;AACF,mEAAmE;AACnE,qBAAqB;AACrB,EAAE;AACF,4EAA4E;AAC5E,8EAA8E;AAC9E,qEAAqE;AACrE,4FAA4F;AAC5F,8DAA8D;AAC9D,8DAA8D;AAC9D,0EAA0E;AAC1E,EAAE;AACF,yEAAyE;AACzE,uEAAuE;AACvE,0EAA0E;AAC1E,oEAAoE;AAIpE;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2B9B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;CAuBrC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAC7C,sCAAsC,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG;;;;;;;OAOxC,kCAAkC;;;;;;;;;;;;;;;;;CAiBxC,CAAC;AAEF;+DAC+D;AAC/D,MAAM,CAAC,MAAM,6BAA6B,GAAG;CAC5C,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;;;;;;;;CAQrC,CAAC;AAYF;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,MAAmB,EACnB,OAAuE,EAAE;IAEzE,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC;IACjD,wEAAwE;IACxE,2CAA2C;IAC3C,MAAM,IAAI,GAAG,MAAqB,CAAC;IACnC,MAAM,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;IAClC,0EAA0E;IAC1E,+EAA+E;IAC/E,yEAAyE;IACzE,mEAAmE;IACnE,4EAA4E;IAC5E,oBAAoB;IACpB,MAAM,IAAI,CAAC,KAAK,CACd,IAAI,CAAC,uBAAuB;QAC1B,CAAC,CAAC,+BAA+B;QACjC,CAAC,CAAC,sBAAsB,CAC3B,CAAC;IACF,IAAI,aAAa,EAAE,CAAC;QAClB,MAAM,IAAI,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC;QACzC,MAAM,IAAI,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;IAClD,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAoC,EAAE;IAEtC,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC;IACjD,OAAO,aAAa;QAClB,CAAC,CAAC,GAAG,eAAe,KAAK,sBAAsB,EAAE;QACjD,CAAC,CAAC,eAAe,CAAC;AACtB,CAAC"}
+{"version":3,"file":"auth-schema.js","sourceRoot":"","sources":["../src/auth-schema.ts"],"names":[],"mappings":"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"}

package/dist/claims-context.d.ts

@@ -0,0 +1,100 @@
+import { type SystemContextOpts, type VerifiedTenantClaims } from "./types.js";
+/**
+ * Establish the request-scoped verified-claims context. Call this ONCE per
+ * request, from auth middleware, IMMEDIATELY after the JWT has been
+ * verified — and pass the values off the VERIFIED claim set, never off the
+ * request body / path / headers.
+ *
+ * Everything downstream (`withUserContext`, `withUserContextDb`,
+ * `withUserContextDbPostgresJs`, `autoDispatch`) reads the tenant from
+ * here. Nothing downstream can supply one.
+ *
+ * ```ts
+ * app.use(async (c, next) => {
+ *   const claims = await verifyJwt(c.req.header("authorization"));
+ *   return runWithVerifiedTenantClaims(
+ *     { userId: claims.sub, tenantId: claims.tenant_id },
+ *     () => next(),
+ *   );
+ * });
+ * ```
+ *
+ * Returns whatever `fn` returns (including a promise), so it composes with
+ * Hono / Express / gRPC interceptor shapes unchanged.
+ *
+ * Throws {@link VerifiedTenantClaimsAlreadyBound} if claims are already
+ * bound in the current async context. Re-binding is refused
+ * UNCONDITIONALLY — including to identical claims. A nested bind is the
+ * one shape that could re-open the hole (bind in middleware, re-bind to a
+ * request-derived tenant in the handler), so it is not a thing that
+ * happens quietly. If you have hit this legitimately, the answer is to
+ * move the single bind to the outermost auth boundary, not to relax it.
+ *
+ * Throws {@link InvalidVerifiedTenantClaims} if `userId` / `tenantId` is
+ * missing, not a string, or blank.
+ */
+export declare function runWithVerifiedTenantClaims<T>(claims: VerifiedTenantClaims, fn: () => T): T;
+/**
+ * The verified claims bound to the current request, or `null` outside any
+ * bound context.
+ *
+ * This is the DIAGNOSTIC read (health probes, "am I on the authenticated
+ * path?" branches). Anything that is about to touch the database must use
+ * {@link requireVerifiedTenantClaims} so an unbound context fails closed
+ * instead of degrading into a nullish branch.
+ */
+export declare function getVerifiedTenantClaimsOrNull(): VerifiedTenantClaims | null;
+/** Whether verified claims are bound in the current async context. */
+export declare function hasVerifiedTenantClaims(): boolean;
+/**
+ * The verified claims bound to the current request, or THROW.
+ *
+ * Fail closed and loud: there is no default tenant, no fallback to a
+ * passed value, and no empty result. A silently-empty result is how the
+ * crm 85-policy blackout stayed invisible for weeks.
+ */
+export declare function requireVerifiedTenantClaims(helper?: string): VerifiedTenantClaims;
+/**
+ * Refuse the retired `helper(opts, fn)` call shape.
+ *
+ * TypeScript already rejects it — the helpers take the callback as their
+ * only argument, so all 271 call sites are compile errors until each one is
+ * examined. This is the runtime backstop for consumers that do not
+ * typecheck against this package (plain JS, a stale `dist/`, a `any`-typed
+ * wrapper): without it, the opts object would be invoked as the callback
+ * and the caller would get `opts is not a function`, which reads like a bug
+ * in db-rls rather than a migration they have not done.
+ */
+export declare function assertNoTenantArgument(helper: string, fn: unknown): void;
+/**
+ * THE STEP-1 FENCE on the system leg. Called by `withSystemContext`,
+ * `withSystemContextDb` and `withSystemContextDbPostgresJs` before they
+ * open a services-pool transaction.
+ *
+ * Three outcomes:
+ *
+ *   - **No claims bound** (boot, cron, worker, S2S, webhook) → returns
+ *     `null`. The system helpers behave EXACTLY as before — this is the
+ *     compat property that keeps the fence from breaking every worker.
+ *   - **Claims bound + `opts.reason` is a non-blank string** → returns
+ *     `{ boundTenantId, reason }` so the caller can annotate telemetry
+ *     (`db_rls.cross_pool_nesting_total{outer=authenticated,inner=services,
+ *     reason}`). The escape is sanctioned, named, and observable.
+ *   - **Claims bound + no reason** → THROWS
+ *     {@link SystemContextUnderClaimsRefused}, BEFORE any pool is touched.
+ *
+ * WHY. The services-pool predicate is the bare
+ * `tenant_id = auth.get_tenant_id()` — it trusts the GUC completely and
+ * proves no membership. An authenticated request that falls through to
+ * `withSystemContext` therefore re-opens the exact hole the verified-claims
+ * binding closes on the authenticated pool: the handler supplies the
+ * tenant, and nothing checks the principal holds it. That fall-through is
+ * where the ₹250,000 cross-tenant refund reproduces. Requiring an explicit
+ * `{ reason }` turns a silent fall-through into a deliberate, reviewable,
+ * telemetry-visible act — and everything else into a throw.
+ */
+export declare function assertSystemContextEscapeAllowed(helper: string, opts: SystemContextOpts): {
+    boundTenantId: string;
+    reason: string;
+} | null;
+//# sourceMappingURL=claims-context.d.ts.map

package/dist/claims-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claims-context.d.ts","sourceRoot":"","sources":["../src/claims-context.ts"],"names":[],"mappings":"AAiDA,OAAO,EAIL,KAAK,iBAAiB,EAEtB,KAAK,oBAAoB,EAE1B,MAAM,YAAY,CAAC;AAuGpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,EAC3C,MAAM,EAAE,oBAAoB,EAC5B,EAAE,EAAE,MAAM,CAAC,GACV,CAAC,CAcH;AAED;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,IAAI,oBAAoB,GAAG,IAAI,CAE3E;AAED,sEAAsE;AACtE,wBAAgB,uBAAuB,IAAI,OAAO,CAEjD;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,CAAC,EAAE,MAAM,GACd,oBAAoB,CAMtB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,GAAG,IAAI,CAIxE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,gCAAgC,CAC9C,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,iBAAiB,GACtB;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAclD"}