@rebasepro/rls-check 0.22.0 → 0.24.0

package/README.md

@@ -28,7 +28,7 @@ The failures that make a Postgres database leak in practice, rather than the one
 - policies that look like access control but evaluate to `true` for every row;
 - `auth.uid() IS NOT NULL`-shaped policies, which separate signed-in from signed-out callers and scope nothing;
 - views and materialized views that read past the RLS on their base tables because they run as their owner;
-- a bare column inside an `EXISTS` subquery that Postgres silently binds to the *inner* table, turning a tenant filter into a tautology;
+- a bare column inside an `EXISTS` subquery that Postgres silently binds to the *inner* table, turning a tenant filter into a tautology — which the catalog stores as the column compared with itself;
 - many-to-many join tables left unprotected between two protected endpoints — the whole edge list, readable;
 - `SECURITY DEFINER` routines with an unpinned `search_path`;
 - `GRANT`s to `PUBLIC`, and policies pointed at roles nothing can connect as.
@@ -144,7 +144,7 @@ rls-check is free and maintained by the team behind Rebase — https://rebase.pr
 
 That run found nothing heuristic. When it does, the heuristic findings go in a `WORTH CHECKING` section of their own, after the confident ones — mixing "this table is public" with "this might be a join table" is how a scanner teaches people to ignore it.
 
-The `Exposed` line is worth reading before the findings: every check reports a table only when one of those roles can reach it, so if the role your application connects as is not listed, name it with `--role` and run again.
+The `Exposed` line is worth reading before the findings: a check that calls a table exposed does so only when one of those roles can reach it — holds a privilege on it, and `USAGE` on its schema — so if the role your application connects as is not listed, name it with `--role` and run again.
 
 ## The checks
 
@@ -152,16 +152,16 @@ Run `npx @rebasepro/rls-check --list-checks` for the catalog on your installed v
 
 | id | typical severity | confidence | what it looks for |
 | --- | --- | --- | --- |
-| `rls-disabled` | critical | certain | A table with RLS off that grants SELECT/INSERT/UPDATE/DELETE to a role an untrusted caller can reach. |
-| `policy-always-true` | critical | certain | A permissive policy whose `USING` or `WITH CHECK` expression is always true. Downgraded to medium, and to heuristic, when the policy sits behind an authentication gate. |
+| `rls-disabled` | critical | certain | A table with RLS off that grants SELECT/INSERT/UPDATE/DELETE to a role an untrusted caller can reach, or a foreign table (which cannot have RLS) with such a grant. |
+| `policy-always-true` | critical | certain | A permissive policy whose `USING` or `WITH CHECK` expression is always true. High when only an UPDATE policy's `WITH CHECK` is constant: `USING` still scopes which rows it touches, and the check lets them become anything. Downgraded to medium, and to heuristic, when `RESTRICTIVE` policies on the same command apply to every role it reaches. |
 | `view-bypasses-rls` | critical | certain | A view granted to an untrusted role that selects from an RLS-protected table and runs with its owner's privileges. Heuristic on servers before PG15, where `security_invoker` does not exist. |
-| `policy-anonymous-tautology` | varies | heuristic | An `auth.uid() IS NOT NULL`-shaped policy: it separates signed-in from signed-out callers and scopes no rows. Critical on Supabase-shaped databases, lower elsewhere. |
+| `policy-anonymous-tautology` | varies | heuristic | An `auth.uid() IS NOT NULL`-shaped policy: it separates signed-in from signed-out callers and scopes no rows. Critical when a signed-out caller still has a value there — Rebase's and PostgREST's sentinel id, or `auth.role()` / `auth.jwt()` on Supabase, which the anon key fills; low for `auth.uid()` on Supabase, which is NULL for a signed-out caller; medium where the scan cannot tell. |
 | `policy-authenticated-tautology` | high | heuristic | The corrected form of the above — `auth.uid() IS NOT NULL AND auth.uid() <> 'anonymous'` — which excludes signed-out callers and still scopes no rows. Every account reads every row; with open registration that is everybody. |
 | `anonymous-write-allowed` | high | certain | A permissive INSERT/UPDATE/DELETE policy reachable without authentication whose check expression accepts any row, backed by a matching grant. |
 | `matview-bypasses-rls` | high | certain | A materialized view granted to an untrusted role whose defining query reads an RLS-protected table. Materialized views have no `security_invoker`. |
-| `unqualified-column-in-subquery` | high | heuristic | A bare column name in an `EXISTS`/`IN` subquery that exists on both the inner relation and the policy's own table, so Postgres binds it to the inner one. |
+| `unqualified-column-in-subquery` | high | heuristic | A bare column name in an `EXISTS`/`IN` subquery that exists on both the inner relation and the policy's own table, so Postgres binds it to the inner one. Postgres stores it with every column qualified, so on a live database it is found as the inner column compared with itself (`m.org_id = m.org_id`). |
 | `junction-table-unprotected` | high | heuristic | A table that is essentially two foreign keys pointing at RLS-protected tables, with no row-level security of its own. |
-| `grant-to-public` | medium | certain | A table privilege granted to `PUBLIC`, which includes roles that do not exist yet. |
+| `grant-to-public` | medium | certain | A table or foreign-table privilege granted to `PUBLIC`, which includes roles that do not exist yet. |
 | `rls-enabled-no-policies` | medium | certain | RLS enabled and not a single policy defined, so the table denies everything. |
 | `rls-enabled-not-forced` | medium | certain | RLS enabled without `FORCE`, so the owning role is exempt from its own policies. |
 | `policy-role-unreachable` | medium | certain | Every policy on a table names roles that do not exist, cannot log in, and that no login role inherits. |
@@ -329,7 +329,7 @@ A stock Rebase scaffold reports three `policy-always-true` criticals on its firs
 
 Findings are sorted worst-first and then by schema, object and id, so two scans of an unchanged database produce an identical file.
 
-`exposedRoles` and `diagnostics` are part of the contract, not decoration. Every check reports a table only when one of the exposed roles can reach it, and `diagnostics.degraded` is how a consumer tells "nothing was wrong" from "the scan could not look" — `findings: []` without both is half an answer.
+`exposedRoles` and `diagnostics` are part of the contract, not decoration. A check that calls a table exposed does so only when one of the exposed roles can reach it, and `diagnostics.degraded` is how a consumer tells "nothing was wrong" from "the scan could not look" — `findings: []` without both is half an answer.
 
 ## What this tool does not do
 
@@ -338,7 +338,7 @@ Being clear about this is the point of the tool. It is a **static audit of the c
 - **It does not execute queries as other roles.** It never connects as `anon`, never sets a JWT claim, and never tries to read a row it should not be able to read. Everything it reports is inferred from what the catalogs say, not observed.
 - **It cannot prove a policy is correct.** Deciding whether `owner_id = auth.uid()` is the right rule for your application requires knowing your application. `rls-check` can only tell you that certain *shapes* are wrong — a policy that is always true, a view that runs as its owner, a table with RLS switched off.
 - **A clean report is not a security certification.** It means these fifteen checks found nothing. It does not mean your authorization model is sound, your API layer enforces what it should, or your data is safe.
-- **It recognises app roles by name, and yours may not be one of them.** Every check reports a table as exposed only when a role an untrusted caller can arrive as holds privileges on it. Out of the box that means `PUBLIC`, Supabase's `anon` and `authenticated`, PostgREST's `web_anon`, and Rebase's `rebase_user`. If your application connects as `app_user`, `api` or anything else, name it — `--role app_user` — or the checks have nothing to gate on. A scan that finds a write-holding role it cannot account for says so in a `Note` rather than printing a clean report.
+- **It recognises app roles by name, and yours may not be one of them.** A check calls a table exposed only when a role an untrusted caller can arrive as holds privileges on it and `USAGE` on its schema. Out of the box that means `PUBLIC`, Supabase's `anon` and `authenticated`, PostgREST's `web_anon`, and Rebase's `rebase_user`. If your application connects as `app_user`, `api` or anything else, name it — `--role app_user` — or the checks have nothing to gate on. A scan that finds a write-holding role it cannot account for says so in a `Note` rather than printing a clean report.
 - **It does not model your API layer.** Whether a table is actually reachable depends on PostgREST, your server, or your gateway. Findings say "if this table is exposed over an API" when reachability depends on something outside the database — believe that qualifier.
 - **It does not see what your connection sees.** Almost every connection string handed to a tool like this belongs to a superuser or a table owner, which RLS cannot constrain. That is what lets it read the true catalog; it also means the findings describe what *other* roles get. The report says so, prominently, every time it applies.
 - **Heuristic checks produce false positives by design.** Junction-table inference and unqualified-column detection match a shape, not a proof. They are reported in a separate section for exactly that reason.

package/dist/checks/anonymous-write-allowed.d.ts

@@ -13,8 +13,9 @@ import type { Check } from "../types.js";
  *      correct one — satisfies condition 1 on almost every project out there.
  *      Flagging it would make this check fire on the whole ecosystem.
  *
- * So what is reported is the narrow, certain case: the check expression is
- * absent or constant-true, which in Postgres means "accept any row". Policies
+ * So what is reported is the narrow, certain case: the clause that decides the
+ * command is constant-true, which in Postgres means "accept any row". An
+ * *absent* clause is the opposite — see {@link writesAcceptingAnyRow}. Policies
  * whose expression is an anonymous *tautology* rather than a constant are the
  * business of `policy-anonymous-tautology`, which can weigh the platform.
  */

package/dist/checks/policy-always-true.d.ts

@@ -8,8 +8,8 @@ import type { Check } from "../types.js";
  * substring-matching version of this check would flag both.
  *
  * The one thing that legitimately rescues `USING (true)` is a RESTRICTIVE
- * policy on the same command, because RESTRICTIVE clauses are ANDed after the
- * PERMISSIVE ones are ORed. "Permissive default, restrictive gate" is a real
+ * policy on the same command that applies to the same callers, because
+ * RESTRICTIVE clauses are ANDed after the PERMISSIVE ones are ORed. "Permissive default, restrictive gate" is a real
  * pattern, so when one is present the finding degrades to a question instead of
  * an accusation rather than disappearing (the restrictive policy may well not
  * cover the same rows).

package/dist/checks/policy-anonymous-tautology.d.ts

@@ -9,7 +9,10 @@ import type { Check } from "../types.js";
  *   - Supabase: `auth.uid()` reads a JWT claim and returns NULL for an anonymous
  *     caller, so the expression is a legitimate "signed in" test. Its only real
  *     failing is that it does not scope rows to their owner — worth `low`, worded
- *     as a design observation rather than a vulnerability.
+ *     as a design observation rather than a vulnerability. That is a fact about
+ *     `auth.uid()`, not about Supabase: an anonymous caller there still carries
+ *     the anon key's JWT, so `auth.role()` and `auth.jwt()` are non-null for it,
+ *     and the same shape built on them is a bypass — see {@link CallerCall}.
  *   - Rebase / PostgREST-style stacks that coerce a missing id to a sentinel
  *     (`'anonymous'`, `''`): the expression is true for signed-out callers, so it
  *     is a straight authentication bypass. This exact policy shipped in this
@@ -22,9 +25,34 @@ import type { Check } from "../types.js";
  * {@link matchTautology}.
  */
 export declare const policyAnonymousTautology: Check;
+/**
+ * What a caller call hands a signed-out request, which is what decides whether
+ * `<call> IS NOT NULL` keeps that request out.
+ */
+export interface CallerCall {
+    /**
+     * On Supabase, a signed-out request carries the project's anon key — a real
+     * JWT with `role: "anon"` and no user in it. So:
+     *
+     *   - `null`: the call reads something that JWT does not carry (`auth.uid()`
+     *     reads `sub`), and a null test on it does exclude signed-out callers;
+     *   - `present`: the call reads something it does carry, and a null test on
+     *     it excludes nobody;
+     *   - `unknown`: Supabase does not set it, so whatever does decides.
+     */
+    onSupabase: "null" | "present" | "unknown";
+    /** What the call returns for that request, in prose, when it is `present`. */
+    signedOutValue?: string;
+    /** What the call names — "id", "role" — for the sentence about its sentinels. */
+    noun: string;
+    /** Values a signed-out caller arrives with, so a guard excluding one is real. */
+    sentinels: string[];
+}
 export interface TautologyMatch {
     /** How to name the caller-id expression in prose, e.g. `auth.uid()`. */
     shape: string;
+    /** What that call hands a signed-out request. */
+    call: CallerCall;
     /** Literals the policy excludes that exclude nobody. Empty for a bare null test. */
     decoyGuards: string[];
     /**

package/dist/checks/rls-disabled.d.ts

@@ -7,5 +7,9 @@ import type { Check } from "../types.js";
  * lookup tables reachable only by the service role. Flagging those is how a
  * scanner produces forty findings on a healthy database and gets ignored, so a
  * table nobody exposed produces no finding at all.
+ *
+ * Foreign tables are included, and are always "RLS off": Postgres refuses
+ * `ENABLE ROW LEVEL SECURITY` on one, so a grant to an exposed role hands over
+ * whatever the remote server returns, and the fix is the grant, not a policy.
  */
 export declare const rlsDisabled: Check;

package/dist/checks/rls-enabled-not-forced.d.ts

@@ -3,11 +3,18 @@ import type { Check } from "../types.js";
  * RLS on, FORCE off — the table owner is exempt from its own policies.
  *
  * How much that matters is entirely a question of *who the owner is*, and the
- * severity has to follow that or the check becomes noise:
+ * severity has to follow that or the check becomes noise. "The owner" means
+ * every role with the owner's privileges: Postgres decides the exemption with
+ * `has_privs_of_role`, so a member of the owning role is exempt exactly as the
+ * owner is.
  *
- *   - Owner cannot log in: a provisioning role nothing connects as. Informational.
- *   - Owner can log in and is otherwise ordinary: anything using that connection
- *     string reads the whole table. This is the case worth waking up for.
+ *   - A role an untrusted caller arrives as is, or is a member of, the owner:
+ *     every request made as it skips the policies. Critical.
+ *   - Owner can log in, or a login role is a member of it, and it is otherwise
+ *     ordinary: anything using that connection string reads the whole table.
+ *     This is the case worth waking up for.
+ *   - Owner cannot log in and nothing that can is a member of it: a
+ *     provisioning role nothing connects as. Informational.
  *   - Owner is a superuser or has BYPASSRLS: FORCE would not help either way,
  *     because those attributes skip RLS before ownership is even considered.
  *     Reporting `high` here would be misleading — the fix is "do not connect as

package/dist/checks/sql.d.ts

@@ -9,7 +9,8 @@
  * Everything it reads comes from `pg_policies.qual` / `with_check`, which is
  * Postgres's own re-rendering of the parse tree rather than the SQL anyone
  * typed: parenthesised more heavily, casts made explicit, and — importantly for
- * the unqualified-column check — references usually re-qualified. So a hit here
+ * the unqualified-column check — every column inside a subquery qualified, so a
+ * bare name written there never reaches this scanner from a live catalog. A hit
  * is strong evidence and a miss proves nothing, which is what the checks say.
  */
 export type TokenKind = "ident" | "string" | "number" | "op" | "punct";

package/dist/checks/unqualified-column-in-subquery.d.ts

@@ -24,10 +24,20 @@ import type { Check } from "../types.js";
  *     flagging it merely because the outer table also has a `user_id` would fire
  *     on a large fraction of correct policies.
  *
- * Confidence is always heuristic, and the detail says why an absence proves
- * nothing: `pg_policies.qual` is Postgres's re-rendering of the parse tree, and
- * it normally re-qualifies references. A finding here therefore means the
- * ambiguity survived that rewrite, which is strong evidence — but a clean scan
- * is not proof that the original SQL was unambiguous.
+ * What a live database hands this check is not what anyone typed.
+ * `pg_policies.qual` is Postgres's re-rendering of the parse tree, and inside a
+ * subquery it qualifies *every* column — so the bare name is never in the text.
+ * The bare-name scan below only ever fires on text that did not come out of the
+ * catalog. Against a real database the mistake shows up as its effect: the bare
+ * `organization_id` bound to the inner relation, so the stored comparison reads
+ * `m.organization_id = m.organization_id` — a column compared with itself. That
+ * shape is what {@link selfComparisons} looks for, and it is the half of this
+ * check that can fire on a scan. It was the half missing until it was noticed
+ * that the check could not fire at all; the e2e suite now holds it to that.
+ *
+ * Confidence is always heuristic, and an absence still proves nothing: a bare
+ * name compared with a *different* inner column (`organization_id = id`) comes
+ * back as `m.organization_id = m.id`, which is indistinguishable from a
+ * comparison somebody meant.
  */
 export declare const unqualifiedColumnInSubquery: Check;

package/dist/checks/util.d.ts

@@ -6,7 +6,7 @@
  * noise, and noise is what gets a tool like this uninstalled — so the helpers
  * below err towards "no" whenever the catalog is ambiguous.
  */
-import type { DbGrant, DbPolicy, DbRelation, DbSnapshot, Finding, Severity } from "../types.js";
+import type { DbForeignKey, DbGrant, DbPolicy, DbRelation, DbRole, DbSnapshot, Finding, Severity } from "../types.js";
 export declare const SEVERITY_ORDER: Severity[];
 export declare const docsFor: (id: string) => string;
 export type Privilege = DbGrant["privileges"][number];
@@ -17,6 +17,12 @@ export declare const WRITE_PRIVILEGES: Privilege[];
 export declare const ANONYMOUS_ROLES: string[];
 export declare const isPublicRole: (role: string) => boolean;
 export declare const sameRole: (a: string, b: string) => boolean;
+/** Every grant on one relation, in snapshot order. */
+export declare function grantsOn(snapshot: DbSnapshot, schema: string, table: string): readonly DbGrant[];
+/** The foreign keys declared on one table, in snapshot order. */
+export declare function foreignKeysOf(snapshot: DbSnapshot, schema: string, table: string): readonly DbForeignKey[];
+/** A role by name, compared the way {@link sameRole} compares. */
+export declare function roleNamed(snapshot: DbSnapshot, name: string): DbRole | undefined;
 /**
  * Every role whose grants `role` actually receives: itself, PUBLIC, and the
  * transitive closure of its memberships.
@@ -27,7 +33,19 @@ export declare const sameRole: (a: string, b: string) => boolean;
  * checker that only compares grantee names.
  */
 export declare function rolesUsableBy(snapshot: DbSnapshot, role: string): Set<string>;
-/** Privileges `role` effectively holds on a relation, memberships included. */
+/**
+ * Can `role` name objects in `schema` at all?
+ *
+ * Without USAGE on the schema a role gets "permission denied for schema" before
+ * any table privilege is looked at, so a grant on a table there reaches
+ * nothing. Unknown — the read failed, or the schema has no record — counts as
+ * yes: a scanner that cannot tell must report, not stay quiet.
+ */
+export declare function hasSchemaUsage(snapshot: DbSnapshot, schema: string, role: string): boolean;
+/**
+ * Privileges `role` effectively holds on a relation, memberships included —
+ * and none at all when it cannot use the relation's schema.
+ */
 export declare function effectivePrivileges(snapshot: DbSnapshot, schema: string, table: string, role: string): Set<Privilege>;
 /**
  * Which exposed roles hold at least one of `wanted` on this relation, and which.
@@ -40,18 +58,54 @@ export declare function exposedGrantees(snapshot: DbSnapshot, schema: string, ta
 }[];
 /** Does this policy's TO list name a role an untrusted caller arrives as? */
 export declare function policyTargetsExposedRole(snapshot: DbSnapshot, policy: DbPolicy): string[];
+/**
+ * The exposed callers a policy applies to *and* that can reach its table for
+ * its command: {@link policyTargetsExposedRole}, kept to the roles holding a
+ * privilege the command needs (and USAGE on the schema).
+ *
+ * A policy nobody can reach the table through is a latent problem, not an
+ * exposure, and every check claims an exposure: "a caller can read every row"
+ * is false for a role Postgres answers "permission denied". `PUBLIC` stays when
+ * the policy is TO PUBLIC and any exposed role reaches the table.
+ */
+export declare function policyReachedBy(snapshot: DbSnapshot, policy: DbPolicy): string[];
 export declare const TABLE_KINDS: DbRelation["kind"][];
 export declare const isTable: (r: DbRelation) => boolean;
 export declare function scannedTables(snapshot: DbSnapshot): DbRelation[];
+/**
+ * Foreign tables in the scanned schemas. Postgres cannot put row-level
+ * security on one, so a grant is all that stands between it and a caller.
+ */
+export declare function scannedForeignTables(snapshot: DbSnapshot): DbRelation[];
 export declare function relationAt(snapshot: DbSnapshot, schema: string, name: string): DbRelation | undefined;
 export declare function policiesFor(snapshot: DbSnapshot, schema: string, table: string): DbPolicy[];
 export declare const hasColumn: (r: DbRelation, name: string) => boolean;
 /** `≈ 12,000 rows` — only ever used to convey blast radius, never severity. */
 export declare function rowsPhrase(rel: DbRelation | undefined): string;
-export declare const qi: (ident: string) => string;
+/**
+ * A quoted identifier that is one printable token wherever a fix puts it.
+ *
+ * Every name here comes out of the catalog, which means out of whoever could
+ * create a table, a role or a policy, and every fix is printed to be pasted
+ * into psql. Doubling `"` keeps a name inside its quotes; a name with a line
+ * break in it is written as a Unicode-escape identifier (`U&"a\000Ab"`), which
+ * names the same object and has no line break to escape a comment with.
+ */
+export declare function qi(ident: string): string;
 export declare const qrel: (schema: string, name: string) => string;
 /** PUBLIC is a keyword, not an identifier — quoting it changes what it means. */
 export declare const qrole: (role: string) => string;
+/**
+ * The REVOKEs that take `privileges` on a relation away from the exposed roles:
+ * one per grant that reaches them, made to the role the grant names.
+ *
+ * Revoking from the exposed role by name is not the same thing. A grant to
+ * `app_reader` that `anon` inherits survives `REVOKE … FROM anon`, which is a
+ * no-op, and a relation granted to `anon` and `authenticated` keeps the second
+ * grant when the fix names only the first. Every fix that takes a grant away
+ * builds it here, so applying it and rescanning clears the finding.
+ */
+export declare function revokesReaching(snapshot: DbSnapshot, schema: string, table: string, exposed: string[], privileges: Privilege[]): string[];
 export declare function finding(f: Omit<Finding, "docs"> & {
     docs?: string;
 }): Finding;

package/dist/checks/view-bypasses-rls.d.ts

@@ -1,6 +1,6 @@
-import type { Check, DbSnapshot, DbView } from "../types.js";
+import type { Check, DbRelation, DbSnapshot, DbView } from "../types.js";
 /** Base relations of `view` that have RLS turned on. */
-export declare function protectedBaseTables(snapshot: DbSnapshot, view: DbView): string[];
+export declare function protectedBaseTables(snapshot: DbSnapshot, view: DbView): DbRelation[];
 /**
  * A view granted to an untrusted role that reads an RLS-protected table without
  * `security_invoker`.

package/dist/cli.d.ts

@@ -18,13 +18,8 @@
  *    could have come from `pg`, Node or the user goes through `redactSecrets`
  *    on its way out.
  */
-import type { ScanResult, Severity } from "./types.js";
-/** Clean, or nothing at or above `--fail-on`. */
-export declare const EXIT_OK = 0;
-/** Findings at or above `--fail-on`. */
-export declare const EXIT_FINDINGS = 1;
-/** The scan did not happen: bad arguments, bad connection, timeout. */
-export declare const EXIT_ERROR = 2;
+import type { DbSnapshot, Finding, ScanResult, Severity } from "./types.js";
+export { EXIT_OK, EXIT_FINDINGS, EXIT_ERROR, exitCodeFor } from "./report.js";
 export interface ScanOptions {
     connectionString: string;
     /** Restrict to these schemas. Empty or omitted means "every user schema". */
@@ -64,20 +59,12 @@ export declare function selectCheckIds(options: {
     only?: string[];
     skip?: string[];
 }): string[];
-/**
- * The verdict, as an exit code.
- *
- * Pulled out of `runCli` so it can be tested: `runCli` needs a database, and
- * the one line that decides whether CI goes red had no coverage at all —
- * deleting it broke no test.
- *
- * A degraded scan exits 2, the same code a crash uses, rather than 0. Checks
- * whose catalogue reads failed return no findings, which is indistinguishable
- * from finding none, so exiting 0 would have the scanner answer "no problems"
- * to a question it never managed to ask. Both codes mean the same thing here:
- * no verdict.
- */
-export declare function exitCodeFor(result: ScanResult, failOn: Severity | "none"): number;
+export declare function buildScanResult(snapshot: DbSnapshot, findings: Finding[], meta: {
+    connectionString: string;
+    checksRun: number;
+    scannedAt: string;
+    diagnostics: ScanResult["diagnostics"];
+}): ScanResult;
 export interface CliOptions {
     connectionString: string | null;
     json: boolean;