@nodii/db-rls 0.10.0 → 0.12.0

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"}