@nodii/db-rls

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:

// 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 }:

// 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.