@nodii/db-rls 0.13.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/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"}

package/dist/claims-context.js

@@ -0,0 +1,262 @@
+// Request-scoped VERIFIED-claims context — the tenant binding for the
+// authenticated pool.
+//
+// WHY THIS EXISTS
+// ---------------
+// Until this module, `withUserContext({ userId, tenantId }, fn)` took the
+// tenant as a PARAMETER. RLS then trusted `app.tenant_id` completely: the
+// authenticated-pool predicate resolves the session tenant and never proves
+// the principal actually holds it (membership was proven exactly once, in
+// nodii-auth at login, and nowhere near the database). So any handler that
+// passed a REQUEST-DERIVED tenant — `req.body.tenantId`, a path param, a
+// header — instead of the verified JWT claim silently defeated row-level
+// security, and nothing in the stack caught it. 271 call sites across 11
+// services were one line away from serving another tenant's rows.
+//
+// The fix is structural, not advisory: the tenant is no longer expressible
+// as an argument. It is read from a request-scoped store that carries the
+// VERIFIED claim set, established ONCE per request by auth middleware. A
+// handler cannot pass a tenant, cannot rebind the store to a different
+// tenant, and cannot mutate a bound claim set. There is no override option
+// and no default — an unbound context throws.
+//
+// SCOPE — the AUTHENTICATED path, plus ONE fence on the system path.
+// `withSystemContext({ tenantId }, fn)` (workers, cron, S2S, webhooks: a
+// legitimately resolved tenant and no user claim) keeps its explicit
+// parameter — with claims UNBOUND it is completely unchanged. But when it
+// is called INSIDE a claims-bound request it now refuses unless the caller
+// passes an explicit `{ reason }` (see
+// {@link assertSystemContextEscapeAllowed}): the services-pool predicate is
+// the bare `tenant_id = auth.get_tenant_id()` with no membership proof, so
+// an authenticated request that falls through to it can aim the session at
+// ANY tenant — the seam where the ₹250,000 cross-tenant refund reproduced.
+// `withPlatformOpsContext` (Nodii staff, RBAC-gated by a different
+// predicate against `platform_ops_grants_replica`) is not touched.
+//
+// SUBPATH-SPLIT SAFETY (@nodii/grpc-auth `user-context-als.ts` class).
+// @nodii/db-rls ships five entry points (`.`, `/drizzle`,
+// `/drizzle/platform-ops-grants`, `/postgres-js`, `/node-postgres`). Under
+// plain `tsc` they share one `dist/claims-context.js`, but a bundler that
+// splits per entry point (esbuild for Lambda) would DUPLICATE a
+// module-level `new AsyncLocalStorage()`: middleware would bind on one
+// copy while the secure-client factory read another. The single instance is
+// therefore held on a non-configurable `globalThis` slot so every bundle
+// copy in a realm shares it. Note the failure mode here is loud rather than
+// silent — an unbound read throws `NoVerifiedTenantClaims` — but "loud in
+// production" is not the bar; we want it to be impossible.
+import { AsyncLocalStorage } from "node:async_hooks";
+import { InvalidVerifiedTenantClaims, NoVerifiedTenantClaims, SystemContextUnderClaimsRefused, TenantArgumentRefused, VerifiedTenantClaimsAlreadyBound, } from "./types.js";
+const SLOT = "__nodii_db_rls_verified_tenant_claims_als__";
+function resolveStore() {
+    const realm = globalThis;
+    const existing = realm[SLOT];
+    if (existing) {
+        return existing;
+    }
+    const als = new AsyncLocalStorage();
+    // Non-writable + non-configurable: the store cannot be swapped out from
+    // under the fence at runtime (a swapped store is a tenant override with
+    // extra steps).
+    Object.defineProperty(realm, SLOT, {
+        value: als,
+        enumerable: false,
+        writable: false,
+        configurable: false,
+    });
+    return als;
+}
+const store = resolveStore();
+function describe(value) {
+    if (value === null)
+        return "null";
+    if (typeof value === "string")
+        return `a string (${JSON.stringify(value)})`;
+    if (typeof value === "object") {
+        const keys = Object.keys(value);
+        return `an object with keys [${keys.join(", ")}]`;
+    }
+    return `a ${typeof value}`;
+}
+/**
+ * Every claim field is validated EXPLICITLY against `typeof` + blankness.
+ * There is deliberately no `value || fallback` / `value ?? fallback` here:
+ * a configured-but-falsy value quietly becoming a default is a failure mode
+ * this fleet has shipped more than once, and on this path the "default"
+ * would be a tenant.
+ */
+function requireNonBlankString(field, value) {
+    if (typeof value !== "string") {
+        throw new InvalidVerifiedTenantClaims(field, `expected a non-blank string, received ${describe(value)}`);
+    }
+    if (value.trim() === "") {
+        throw new InvalidVerifiedTenantClaims(field, "received a blank string — an empty tenant binds an empty GUC and the RLS predicate then resolves nothing, which reads as 'no rows' rather than 'refused'");
+    }
+    return value;
+}
+/**
+ * Copy the caller's claim fields into a fresh FROZEN object.
+ *
+ * The copy is load-bearing, not hygiene. Without it a handler could hold a
+ * reference to the object the middleware bound and mutate `tenantId` after
+ * the fact — the store would hand the mutated tenant to the next
+ * `withUserContext`, which is precisely the forgery this module exists to
+ * make unrepresentable. Extra properties are dropped for the same reason.
+ */
+function sealClaims(claims) {
+    if (claims === null || typeof claims !== "object") {
+        throw new InvalidVerifiedTenantClaims("claims", `expected an object with { userId, tenantId }, received ${describe(claims)}`);
+    }
+    const userId = requireNonBlankString("userId", claims.userId);
+    const tenantId = requireNonBlankString("tenantId", claims.tenantId);
+    const sealed = {
+        userId,
+        tenantId,
+    };
+    // `sourceIp` is forensic-only, so it stays optional — but if it is
+    // supplied it must be usable. Binding an empty `app.source_ip` GUC would
+    // put a blank string in the audit trail and read as "we recorded it".
+    if (claims.sourceIp !== undefined) {
+        sealed.sourceIp = requireNonBlankString("sourceIp", claims.sourceIp);
+    }
+    return Object.freeze(sealed);
+}
+/** Read a tenant off an UNVALIDATED object, for an error message only. */
+function peekTenant(claims) {
+    if (claims !== null && typeof claims === "object") {
+        const candidate = claims.tenantId;
+        if (typeof candidate === "string" && candidate.trim() !== "") {
+            return candidate;
+        }
+    }
+    return "<unreadable>";
+}
+/**
+ * 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 function runWithVerifiedTenantClaims(claims, fn) {
+    const alreadyBound = store.getStore();
+    if (alreadyBound) {
+        throw new VerifiedTenantClaimsAlreadyBound(alreadyBound.tenantId, peekTenant(claims));
+    }
+    if (typeof fn !== "function") {
+        throw new TypeError("runWithVerifiedTenantClaims: the second argument must be the callback to run inside the bound context.");
+    }
+    return store.run(sealClaims(claims), fn);
+}
+/**
+ * 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 function getVerifiedTenantClaimsOrNull() {
+    return store.getStore() ?? null;
+}
+/** Whether verified claims are bound in the current async context. */
+export function hasVerifiedTenantClaims() {
+    return store.getStore() !== undefined;
+}
+/**
+ * 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 function requireVerifiedTenantClaims(helper) {
+    const claims = store.getStore();
+    if (!claims) {
+        throw new NoVerifiedTenantClaims(helper);
+    }
+    return claims;
+}
+/**
+ * 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 function assertNoTenantArgument(helper, fn) {
+    if (typeof fn !== "function") {
+        throw new TenantArgumentRefused(helper, describe(fn));
+    }
+}
+/**
+ * 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 function assertSystemContextEscapeAllowed(helper, opts) {
+    const claims = store.getStore();
+    if (!claims)
+        return null;
+    const reason = opts?.reason;
+    // Explicit typeof + blankness — a blank reason is not a reason, and there
+    // is deliberately no `reason || default` on this path.
+    if (typeof reason !== "string" || reason.trim() === "") {
+        throw new SystemContextUnderClaimsRefused(helper, claims.tenantId, typeof opts?.tenantId === "string" ? opts.tenantId : "<unreadable>");
+    }
+    return { boundTenantId: claims.tenantId, reason };
+}
+//# sourceMappingURL=claims-context.js.map

package/dist/claims-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claims-context.js","sourceRoot":"","sources":["../src/claims-context.ts"],"names":[],"mappings":"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"}

package/dist/context.d.ts

@@ -1,5 +1,5 @@
 import { type OwnerContextOpts } from "./migrate-guard.js";
-import { type AutoDispatchOpts, type PgTx, type PlatformOpsContextOpts, type SystemContextOpts, type UserContextOpts, type UserMembershipContextOpts } from "./types.js";
+import { type AutoDispatchOpts, type PgTx, type PlatformOpsContextOpts, type SystemContextOpts, type UserMembershipContextOpts } from "./types.js";
 /** Test-only. Not exported through the public barrel. */
 export declare function _resetFenceGateForTests(): void;
 /**
@@ -8,13 +8,24 @@ export declare function _resetFenceGateForTests(): void;
  * `set_config(..., true)` tx-scoped GUCs, yields the tx, commits/rolls
  * back per the PgPool contract.
  *
+ * BREAKING (unforgeable tenant binding): the tenant is NO LONGER an
+ * argument. It is read from the request's verified claims, bound once by
+ * auth middleware via `runWithVerifiedTenantClaims`. The previous shape,
+ * `withUserContext({ userId, tenantId }, fn)`, let a handler pass a
+ * request-derived tenant instead of the verified claim and silently defeat
+ * RLS — the database layer accepted `app.tenant_id` without ever proving
+ * the principal held it. The callback is now the only argument, so every
+ * call site is a compile error until it has been examined.
+ *
  * On the FIRST call in a process it also runs the tenant-fence gate (see
  * {@link assertFenceOnce}) and refuses to yield the tx if the fence is broken.
  *
+ * Throws `NoVerifiedTenantClaims` if no claims are bound — never falls back
+ * to a default or to a passed value.
  * Throws `DbRlsNotInitialized` if `initDbRls` hasn't run.
  * Wraps any error thrown by `fn` in `TransactionRolledBack`.
  */
-export declare function withUserContext<T>(opts: UserContextOpts, fn: (tx: PgTx) => Promise<T>): Promise<T>;
+export declare function withUserContext<T>(fn: (tx: PgTx) => Promise<T>): Promise<T>;
 /**
  * @deprecated REMOVED — always throws {@link CrossTenantSessionRefused}.
  *
@@ -30,8 +41,11 @@ export declare function withUserContext<T>(opts: UserContextOpts, fn: (tx: PgTx)
  * task, got HTTP 200, and released a 250,000 INR refund. Rewriting predicates
  * while leaving this callable would have changed nothing for any caller of it.
  *
- * Migrate to `withUserContext({ userId, tenantId }, fn)` — the same pool, with
- * the tenant the request actually resolved to. If a caller genuinely needs to
+ * Migrate to `withUserContext(fn)` — the same pool, with the tenant the
+ * request's VERIFIED claims resolved to. That tenant is bound once by auth
+ * middleware (`runWithVerifiedTenantClaims`) and is no longer an argument at
+ * all, so the "pass the tenant the request resolved to" step this docblock
+ * used to ask for cannot be got wrong. If a caller genuinely needs to
  * know which tenants a user belongs to (a tenant switcher, a login
  * tenant-picker), query `auth.user_tenant_ids` directly from a services-pool
  * context; that function is deliberately left intact and still answers exactly
@@ -47,6 +61,22 @@ export declare function withUserMembershipContext<T>(_opts: UserMembershipContex
  * withSystemContext — opens a tx on the `services` (nodii_services) pool,
  * sets `app.tenant_id` via tx-scoped `set_config`, yields the tx, commits
  * / rolls back per the PgPool contract.
+ *
+ * THE STEP-1 FENCE (panel finding). The services-pool predicate is the bare
+ * `tenant_id = auth.get_tenant_id()` — no membership proof — so an
+ * authenticated request that falls through to this helper can aim the
+ * session at ANY tenant. That fall-through is the un-fenced seam where the
+ * ₹250,000 cross-tenant refund reproduced. Therefore:
+ *
+ *   - **Claims UNBOUND** (boot, cron, workers, S2S, webhooks): unchanged.
+ *     This is the compat property that keeps the fence from breaking every
+ *     worker in the fleet.
+ *   - **Claims BOUND** (`hasVerifiedTenantClaims()` is true): REFUSED with
+ *     {@link SystemContextUnderClaimsRefused} — a throw, before any pool is
+ *     acquired — unless the caller passes an explicit non-blank
+ *     `{ reason }`. A sanctioned escape is emitted to telemetry as
+ *     `db_rls.cross_pool_nesting_total{outer=authenticated,inner=services,reason}`
+ *     so every crossing is named, counted, and audit-greppable.
  */
 export declare function withSystemContext<T>(opts: SystemContextOpts, fn: (tx: PgTx) => Promise<T>): Promise<T>;
 /**
@@ -108,17 +138,28 @@ export declare function _resetWithPlatformOpsDeprecationWarnedForTests(): void;
  */
 export declare function withPlatformOps<T>(opts: PlatformOpsContextOpts, fn: (tx: PgTx) => Promise<T>): Promise<T>;
 /**
- * autoDispatch — chooses the right pool based on what's bound.
- *
- *   - `authContext` present → dispatch through withUserContext
- *     (uses authContext.userId + authContext.tenantId).
- *   - only `tenantId` present → dispatch through withSystemContext.
- *   - neither → throw `MissingTenantContext`.
- *
- * This mirrors `withRequestContext` from the spec § 5.4 with one
- * simplification: the auth context is passed explicitly rather than
- * being read from ALS. Real auth-sdk integration lands in v0.1.x —
- * `// TODO db-rls-v0.1.x: ALS-bound auto-dispatch`.
+ * autoDispatch — chooses the pool from HOW IT IS CALLED, not from a bag of
+ * optional fields.
+ *
+ *   - `autoDispatch(fn)` → authenticated pool, tenant from the request's
+ *     verified claims. Throws `NoVerifiedTenantClaims` if none are bound.
+ *   - `autoDispatch({ systemTenantId }, fn)` → services pool, explicit
+ *     tenant. The system leg (workers, cron, S2S, webhooks) legitimately
+ *     resolves its own tenant and keeps its parameter.
+ *
+ * This is the ALS-bound dispatch the original docblock deferred
+ * (`// TODO db-rls-v0.1.x: ALS-bound auto-dispatch`). The retired shape
+ * was `autoDispatch({ authContext?, tenantId? }, fn)` — `authContext` was
+ * assembled by the handler, so autoDispatch was a second way to hand the
+ * database a request-derived tenant. It is gone.
+ *
+ * The system leg dispatches through {@link withSystemContext}, so it
+ * inherits the step-1 fence: INSIDE a claims-bound request an explicit
+ * `systemTenantId` needs a non-blank `reason` too, or it throws
+ * `SystemContextUnderClaimsRefused`. There is deliberately no silent
+ * precedence rule — the caller either names the system leg (and, under
+ * claims, the reason for it) or takes the authenticated leg.
  */
+export declare function autoDispatch<T>(fn: (tx: PgTx) => Promise<T>): Promise<T>;
 export declare function autoDispatch<T>(opts: AutoDispatchOpts, fn: (tx: PgTx) => Promise<T>): Promise<T>;
 //# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AASA,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,KAAK,gBAAgB,EAGrB,KAAK,IAAI,EACT,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EAEtB,KAAK,eAAe,EACpB,KAAK,yBAAyB,EAC/B,MAAM,YAAY,CAAC;AAepB,yDAAyD;AACzD,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAyCD;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CAAC,CAAC,EACrC,IAAI,EAAE,eAAe,EACrB,EAAE,EAAE,CAAC,EAAE,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GAC3B,OAAO,CAAC,CAAC,CAAC,CAmCZ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,yBAAyB,CAAC,CAAC,EAC/C,KAAK,EAAE,yBAAyB,EAChC,GAAG,EAAE,CAAC,EAAE,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC,CAEZ;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,IAAI,EAAE,iBAAiB,EACvB,EAAE,EAAE,CAAC,EAAE,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GAC3B,OAAO,CAAC,CAAC,CAAC,CAUZ;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,QAAQ,EAAE,gBAAgB,GAAG,CAAC,CAAC,EAAE,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,EACvD,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GACjC,OAAO,CAAC,CAAC,CAAC,CAiBZ;AAiBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,IAAI,EAAE,sBAAsB,EAC5B,EAAE,EAAE,CAAC,EAAE,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GAC3B,OAAO,CAAC,CAAC,CAAC,CAYZ;AAMD,4DAA4D;AAC5D,wBAAgB,8CAA8C,IAAI,IAAI,CAErE;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,CAAC,EACrC,IAAI,EAAE,sBAAsB,EAC5B,EAAE,EAAE,CAAC,EAAE,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GAC3B,OAAO,CAAC,CAAC,CAAC,CAWZ;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,IAAI,EAAE,gBAAgB,EACtB,EAAE,EAAE,CAAC,EAAE,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GAC3B,OAAO,CAAC,CAAC,CAAC,CAeZ"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAiBA,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,KAAK,gBAAgB,EAGrB,KAAK,IAAI,EACT,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EAEtB,KAAK,yBAAyB,EAC/B,MAAM,YAAY,CAAC;AAepB,yDAAyD;AACzD,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAyCD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,eAAe,CAAC,CAAC,EACrC,EAAE,EAAE,CAAC,EAAE,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GAC3B,OAAO,CAAC,CAAC,CAAC,CAmCZ;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,yBAAyB,CAAC,CAAC,EAC/C,KAAK,EAAE,yBAAyB,EAChC,GAAG,EAAE,CAAC,EAAE,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC,CAEZ;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,IAAI,EAAE,iBAAiB,EACvB,EAAE,EAAE,CAAC,EAAE,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GAC3B,OAAO,CAAC,CAAC,CAAC,CAiBZ;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,QAAQ,EAAE,gBAAgB,GAAG,CAAC,CAAC,EAAE,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,EACvD,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GACjC,OAAO,CAAC,CAAC,CAAC,CAiBZ;AAiBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,IAAI,EAAE,sBAAsB,EAC5B,EAAE,EAAE,CAAC,EAAE,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GAC3B,OAAO,CAAC,CAAC,CAAC,CAYZ;AAMD,4DAA4D;AAC5D,wBAAgB,8CAA8C,IAAI,IAAI,CAErE;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,CAAC,EACrC,IAAI,EAAE,sBAAsB,EAC5B,EAAE,EAAE,CAAC,EAAE,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GAC3B,OAAO,CAAC,CAAC,CAAC,CAWZ;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAChF,wBAAsB,YAAY,CAAC,CAAC,EAClC,IAAI,EAAE,gBAAgB,EACtB,EAAE,EAAE,CAAC,EAAE,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GAC3B,OAAO,CAAC,CAAC,CAAC,CAAC"}