@rebasepro/rls-check 0.22.0 → 0.24.0

package/dist/introspect.d.ts

@@ -1,5 +1,5 @@
 import type { ClientConfig } from "pg";
-import type { DbSnapshot } from "./types.js";
+import type { DbForeignKey, DbGrant, DbRelation, DbSnapshot, DbView } from "./types.js";
 export interface ConnectOptions {
     connectionString: string;
     /** Explicit schema allowlist. Default: every non-system schema. */
@@ -80,8 +80,24 @@ export declare class UnknownRoleError extends Error {
     readonly roles: string[];
     constructor(roles: string[]);
 }
+/**
+ * A `--schema` that is not in `pg_namespace`.
+ *
+ * The same failure as an unknown `--role`, and worse: a typo such as
+ * `--schema pubic`, or `--schema Public` for a schema named `public`, scanned
+ * nothing at all. Zero tables, "No findings", exit 0, for as long as the typo
+ * sat in a CI job. A name that matches nothing only ever narrows the scan, so
+ * it is an error.
+ */
+export declare class UnknownSchemaError extends Error {
+    readonly schemas: string[];
+    constructor(schemas: string[]);
+}
 export declare function introspect(opts: ConnectOptions): Promise<DbSnapshot>;
 export declare function introspectWithDiagnostics(opts: ConnectOptions): Promise<IntrospectResult>;
+type SslOption = false | {
+    rejectUnauthorized: boolean;
+};
 /**
  * The keywords in a libpq keyword string that this tool cannot honour, in the
  * order they were written. Empty for a URL, and empty for a keyword string it
@@ -95,6 +111,17 @@ export declare function unsupportedConnectionKeywords(connectionString: string):
  * failure would still be reported against the host the user typed.
  */
 export declare function clientConfigFromKeywords(keywords: Map<string, string>): ClientConfig;
+/**
+ * The TLS postures to try, in order, for an `sslmode`. Each entry says whether
+ * certificate verification had to be given up to get there.
+ */
+export declare function connectionAttempts(sslmode: string | undefined): {
+    ssl: SslOption;
+    downgraded: boolean;
+}[];
+export interface Reader {
+    query<R extends Record<string, unknown>>(what: string, text: string, values?: unknown[]): Promise<R[]>;
+}
 /**
  * Which of the database's schemas this scan covers.
  *
@@ -103,3 +130,76 @@ export declare function clientConfigFromKeywords(keywords: Map<string, string>):
  * {@link PLATFORM_SCHEMAS} silently stops being checked.
  */
 export declare function selectSchemas(all: string[], requested: string[] | undefined, diagnostics: IntrospectDiagnostics): string[];
+/**
+ * Relations a scanned view reads or a scanned foreign key points at that the
+ * scan did not read, each named once.
+ *
+ * View dependencies are read across schemas on purpose, and foreign keys
+ * always were — but a dependency on a relation that is not in the snapshot
+ * resolves to nothing. `CREATE VIEW public.files AS SELECT * FROM
+ * storage.objects`, granted to anon, produced no finding on a default scan
+ * (which leaves `storage` out), and a junction table pointing at `auth.users`
+ * was never considered.
+ */
+export declare function outOfScopeReferences(relations: DbRelation[], views: DbView[], foreignKeys: DbForeignKey[]): {
+    schema: string;
+    name: string;
+}[];
+/**
+ * Read the relations {@link outOfScopeReferences} names. Columns are not read:
+ * nothing judges a referenced relation by its columns, only by whether it has
+ * row-level security.
+ */
+export declare function readReferencedRelations(db: Reader, refs: {
+    schema: string;
+    name: string;
+}[]): Promise<DbRelation[]>;
+/**
+ * Privileges on each scanned relation, from the relation's ACL and from its
+ * columns' ACLs.
+ *
+ * A column privilege is a privilege on the relation for what these checks ask:
+ * `GRANT SELECT (id, email) ON users TO anon` on a table with RLS off hands
+ * anon those columns of every row, and a column-level UPDATE grant next to a
+ * `USING (true)` policy lets anon rewrite them. Reading `relacl` alone missed
+ * both, so `rls-disabled` and `anonymous-write-allowed` said nothing.
+ */
+export declare function readGrants(db: Reader, schemas: string[]): Promise<DbGrant[]>;
+/**
+ * Who holds USAGE on each schema. Every schema, not only the scanned ones: a
+ * view or a foreign key can point outside the scan.
+ *
+ * `undefined`, not `[]`, when the read failed — an empty list would say no role
+ * can use any schema and silence every check that gates on a grant, which is
+ * the wrong direction for a scanner to fail in.
+ */
+export declare function readSchemaUsage(db: Reader, diagnostics: IntrospectDiagnostics): Promise<{
+    schema: string;
+    grantee: string;
+}[] | undefined>;
+export declare function readViews(db: Reader, schemas: string[], serverVersionNum: number): Promise<DbView[]>;
+/**
+ * Postgres's `parse_bool`: `true`/`false`, `yes`/`no`, `on`/`off`, `1`/`0`,
+ * case-insensitively, and any unambiguous prefix of the words — `t`, `ye`,
+ * `of` — but not `o`, which could be either. `null` for anything else.
+ */
+export declare function parsePgBool(raw: string): boolean | null;
+export interface ViewDependencyRow extends Record<string, unknown> {
+    view_schema: string;
+    view_name: string;
+    ref_schema: string;
+    ref_name: string;
+}
+/**
+ * The transitive closure of direct view dependencies, keyed by
+ * `JSON.stringify([schema, name])`.
+ *
+ * Every view with a dependency of its own is expanded, wherever it lives, and
+ * names are kept as pairs: `schema.name` split at the first dot is wrong for a
+ * schema whose name has a dot in it.
+ */
+export declare function resolveViewDependencies(rows: ViewDependencyRow[]): Map<string, {
+    schema: string;
+    table: string;
+}[]>;
+export {};

package/dist/report.d.ts

@@ -24,6 +24,38 @@ export declare function maxSeverity(findings: readonly Finding[]): Severity | nu
  * would make the exit code disagree with the report.
  */
 export declare function exceedsThreshold(findings: readonly Finding[], failOn: Severity | "none"): boolean;
+/** 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;
+/**
+ * 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;
+/**
+ * The summary's last word: the code the process exits with, and why.
+ *
+ * Both reports print it, and both used to work it out for themselves from the
+ * findings alone, so a degraded scan printed "Exit code 0" or "Exit code 1"
+ * and then exited 2. It comes from {@link exitCodeFor} now, the same function
+ * the CLI exits with.
+ */
+export declare function exitVerdict(result: ScanResult, failOn: Severity | "none"): {
+    code: number;
+    reason: string;
+};
 export declare function clampWidth(columns: number | undefined): number;
 /**
  * Human-readable object path for a finding. Kept boring on purpose — people

package/dist/types.d.ts

@@ -175,6 +175,18 @@ export interface DbSnapshot {
     policies: DbPolicy[];
     roles: DbRole[];
     grants: DbGrant[];
+    /**
+     * Who holds USAGE on each schema, from `pg_namespace.nspacl` (`PUBLIC` for
+     * a grant to everyone). A role without it cannot name anything in the
+     * schema, whatever it holds on the tables there. Absent when it could not
+     * be read, and a schema with no entries here counts as unknown: either way
+     * every role is assumed to have USAGE, which widens a scan rather than
+     * narrowing it.
+     */
+    schemaUsage?: {
+        schema: string;
+        grantee: string;
+    }[];
     views: DbView[];
     foreignKeys: DbForeignKey[];
     routines: DbRoutine[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rebasepro/rls-check",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "Audit Row-Level Security on any PostgreSQL database — finds tables served without RLS, permissive tautologies, unqualified columns in policy subqueries, RLS-bypassing views and unprotected junction tables. Read-only.",
   "keywords": [
     "postgres",
@@ -59,7 +59,7 @@
     "@types/pg": "^8.11.10",
     "typescript": "^6.0.3",
     "vite": "^8.1.5",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.11"
   },
   "scripts": {
     "test": "vitest run",