@safegres/test 0.0.2 → 1.30.7

package/checks/role-trust.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkUntrustedRoleWrites = checkUntrustedRoleWrites;
+exports.checkUntrustedRolePolicies = checkUntrustedRolePolicies;
+exports.checkPublicGrants = checkPublicGrants;
+const WRITE_PRIVILEGES = ['INSERT', 'UPDATE', 'DELETE', 'TRUNCATE'];
+/**
+ * R1: an untrusted role holds a write privilege on a table. Even with
+ * airtight policies, write access for e.g. `anonymous` is almost always a
+ * grant mistake — unauthenticated actors can INSERT/UPDATE/DELETE.
+ */
+function checkUntrustedRoleWrites(table, options = {}) {
+    const untrusted = new Set(options.roles ?? []);
+    if (untrusted.size === 0)
+        return [];
+    const out = [];
+    for (const grant of table.grants) {
+        if (!untrusted.has(grant.role))
+            continue;
+        if (!WRITE_PRIVILEGES.includes(grant.privilege))
+            continue;
+        out.push({
+            code: 'R1',
+            severity: 'critical',
+            category: 'anti-pattern',
+            schema: table.schema,
+            table: table.name,
+            role: grant.role,
+            privilege: grant.privilege,
+            message: `Untrusted role ${grant.role} has ${grant.privilege} grant on ${table.schema}.${table.name}`,
+            hint: `Revoke ${grant.privilege} from ${grant.role} unless unauthenticated writes to this table are intentional (e.g. a public signup or event-ingest table).`
+        });
+    }
+    return out;
+}
+/**
+ * R2: a permissive policy makes write operations pass RLS for an untrusted
+ * role (directly or via PUBLIC). Pairs with R1: the grant is the door, the
+ * policy is the unlocked latch.
+ */
+function checkUntrustedRolePolicies(table, options = {}) {
+    const untrusted = new Set(options.roles ?? []);
+    if (untrusted.size === 0 || !table.rlsEnabled)
+        return [];
+    const out = [];
+    for (const policy of table.policies) {
+        if (!policy.permissive)
+            continue;
+        if (policy.cmd === 'SELECT')
+            continue;
+        const applies = policy.roles.filter((r) => r === 'PUBLIC' || untrusted.has(r));
+        if (applies.length === 0)
+            continue;
+        const via = policy.roles.includes('PUBLIC') ? 'PUBLIC (all roles)' : applies.join(', ');
+        out.push({
+            code: 'R2',
+            severity: 'high',
+            category: 'anti-pattern',
+            schema: table.schema,
+            table: table.name,
+            policy: policy.name,
+            message: `Permissive ${policy.cmd} policy ${policy.name} on ${table.schema}.${table.name} applies to untrusted role via ${via}`,
+            hint: 'Scope the policy TO specific trusted roles instead of PUBLIC/untrusted roles, or verify unauthenticated writes are intended.'
+        });
+    }
+    return out;
+}
+/**
+ * R3: a table with RLS enabled has grants TO PUBLIC. PUBLIC includes every
+ * present and future role, which silently widens access as roles are added
+ * and defeats role-scoped policy reasoning.
+ */
+function checkPublicGrants(table) {
+    if (!table.rlsEnabled)
+        return [];
+    const publicPrivs = table.grants.filter((g) => g.role === 'PUBLIC').map((g) => g.privilege);
+    if (publicPrivs.length === 0)
+        return [];
+    return [
+        {
+            code: 'R3',
+            severity: 'medium',
+            category: 'anti-pattern',
+            schema: table.schema,
+            table: table.name,
+            role: 'PUBLIC',
+            message: `Table ${table.schema}.${table.name} has RLS enabled but grants ${publicPrivs.join(', ')} to PUBLIC`,
+            hint: 'Grant to specific roles instead of PUBLIC — PUBLIC includes every current and future role, including untrusted ones.'
+        }
+    ];
+}

package/checks/set-role.d.ts

@@ -0,0 +1,21 @@
+/**
+ * L7: an untrusted role can `SET ROLE` to a role with materially greater
+ * reach.
+ *
+ * The A/R/L rules all reason about privileges a role holds *passively* — a
+ * direct grant, a grant TO PUBLIC, or one it INHERITs. On PG16+ a membership
+ * can also confer the ability to `SET ROLE` to a role *without* inheriting its
+ * privileges (`pg_auth_members.set_option = true`, `inherit_option = false`),
+ * and that path is invisible to every passive-grant check: nothing the catalog
+ * shows for the untrusted role names the relation, yet an unauthenticated
+ * caller can assume the target role and execute with its full privileges.
+ *
+ * This flags, per relation, the privileges an untrusted role gains only by
+ * assuming another role. It is catalog-proven and, at its shipping severity
+ * (`info`), signal-only — see the registry entry for the intended severity
+ * once the rule has proven itself in the field.
+ */
+import type { TableSnapshot } from '../pg/introspect';
+import type { Finding } from '../types';
+import type { LatticeRoleOptions, RoleGraph } from './lattice';
+export declare function checkSetRoleEscalation(table: TableSnapshot, graph: RoleGraph, options?: LatticeRoleOptions): Finding[];

package/checks/set-role.js

@@ -0,0 +1,66 @@
+"use strict";
+/**
+ * L7: an untrusted role can `SET ROLE` to a role with materially greater
+ * reach.
+ *
+ * The A/R/L rules all reason about privileges a role holds *passively* — a
+ * direct grant, a grant TO PUBLIC, or one it INHERITs. On PG16+ a membership
+ * can also confer the ability to `SET ROLE` to a role *without* inheriting its
+ * privileges (`pg_auth_members.set_option = true`, `inherit_option = false`),
+ * and that path is invisible to every passive-grant check: nothing the catalog
+ * shows for the untrusted role names the relation, yet an unauthenticated
+ * caller can assume the target role and execute with its full privileges.
+ *
+ * This flags, per relation, the privileges an untrusted role gains only by
+ * assuming another role. It is catalog-proven and, at its shipping severity
+ * (`info`), signal-only — see the registry entry for the intended severity
+ * once the rule has proven itself in the field.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkSetRoleEscalation = checkSetRoleEscalation;
+const role_reach_1 = require("./role-reach");
+function checkSetRoleEscalation(table, graph, options = {}) {
+    const untrusted = options.roles ?? [];
+    if (untrusted.length === 0)
+        return [];
+    const out = [];
+    for (const { role, cells } of (0, role_reach_1.computeRoleReach)([table], graph, untrusted)) {
+        const passive = new Set(cells.filter((c) => c.effectiveRole === role).flatMap((c) => c.privileges));
+        // One finding per (untrusted role, assumed role) that adds reach: collapse
+        // the per-target cells so a role reachable by two SET ROLE hops is reported
+        // once, on the most privilege it grants.
+        for (const cell of cells) {
+            if (cell.effectiveRole === role)
+                continue;
+            const gained = cell.privileges.filter((p) => !passive.has(p));
+            if (gained.length === 0)
+                continue;
+            const target = cell.effectiveRole;
+            const attrs = graph.get(target);
+            const bypassesRls = !!attrs?.bypassRls && !graph.get(role)?.bypassRls;
+            const privileges = gained.join(', ');
+            out.push({
+                code: 'L7',
+                severity: 'info',
+                category: 'anti-pattern',
+                schema: table.schema,
+                table: table.name,
+                role,
+                privilege: privileges,
+                message: `Untrusted role ${role} can SET ROLE to ${target}, gaining ${privileges} on `
+                    + `${table.schema}.${table.name} that it holds no passive grant for`
+                    + (bypassesRls ? ` (and ${target} bypasses RLS)` : ''),
+                hint: `SET ROLE grants ${role} the full privileges of ${target} on demand — passive-grant `
+                    + `checks (A2/R1/L5) cannot see it. Revoke the membership, or set it \`WITH SET FALSE\` `
+                    + `so ${role} inherits only what is intended and cannot assume ${target}.`,
+                context: {
+                    effectiveRole: target,
+                    targetBypassesRls: bypassesRls,
+                    targetIsSuperuser: !!attrs?.isSuper,
+                    gained
+                }
+            });
+        }
+    }
+    return out;
+}

package/checks/stats.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Runtime-statistics checks (`--stats`, `S*`).
+ *
+ * These read the cumulative statistics views rather than the catalog, so
+ * unlike the `X*` rules they describe a workload rather than a schema: the
+ * same database can pass or fail depending on what traffic it has served.
+ * Every rule therefore takes a floor, so a cold or freshly-reset database
+ * produces silence instead of noise.
+ */
+import type { StatementUsage, StatsSnapshot, TableUsage } from '../pg/stats';
+import type { Finding } from '../types';
+export interface StatsThresholds {
+    /** Ignore tables with fewer live rows than this. Default 1000. */
+    minRows: number;
+    /** S1 fires when seqScans exceed indexScans by this factor. Default 10. */
+    seqScanRatio: number;
+    /** S2 ignores indexes smaller than this many bytes. Default 1 MiB. */
+    minIndexBytes: number;
+    /** S3 fires above this dead/live tuple ratio. Default 0.2. */
+    deadTupleRatio: number;
+    /** S4 fires for statements at or above this share of total time. Default 0.05. */
+    minTimeShare: number;
+    /** S4 reports at most this many statements. Default 5. */
+    topStatements: number;
+}
+export declare const DEFAULT_STATS_THRESHOLDS: StatsThresholds;
+/**
+ * S1: a table the planner reaches by sequential scan far more often than by
+ * index. On a table above the row floor that is a missing index, a policy
+ * predicate the planner can't use, or a query shape nothing covers.
+ */
+export declare function checkSeqScanDominant(table: TableUsage, thresholds: StatsThresholds): Finding | null;
+/**
+ * S2: an index the planner has never chosen. It still costs write throughput,
+ * disk, and vacuum time. Constraint-backed and unique indexes are exempt:
+ * they exist to enforce a constraint, not to be scanned.
+ */
+export declare function checkUnusedIndexes(table: TableUsage, thresholds: StatsThresholds): Finding[];
+/**
+ * S3: dead tuples the vacuum is not keeping up with. Bloat inflates every
+ * scan of the table and every index on it, and the planner's row estimates
+ * drift with it.
+ */
+export declare function checkDeadTuples(table: TableUsage, thresholds: StatsThresholds): Finding | null;
+/**
+ * S4: the statements the database actually spends its time in, restricted to
+ * ones touching a table in scope. This is not a defect — it is the ranked
+ * list to read the other findings against, so it is `info` by default.
+ */
+export declare function checkTopStatements(statements: StatementUsage[], tables: TableUsage[], thresholds: StatsThresholds): Finding[];
+/** Every stats finding for one snapshot. */
+export declare function checkStats(snapshot: StatsSnapshot, thresholds?: StatsThresholds): Finding[];

package/checks/stats.js

@@ -0,0 +1,192 @@
+"use strict";
+/**
+ * Runtime-statistics checks (`--stats`, `S*`).
+ *
+ * These read the cumulative statistics views rather than the catalog, so
+ * unlike the `X*` rules they describe a workload rather than a schema: the
+ * same database can pass or fail depending on what traffic it has served.
+ * Every rule therefore takes a floor, so a cold or freshly-reset database
+ * produces silence instead of noise.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_STATS_THRESHOLDS = void 0;
+exports.checkSeqScanDominant = checkSeqScanDominant;
+exports.checkUnusedIndexes = checkUnusedIndexes;
+exports.checkDeadTuples = checkDeadTuples;
+exports.checkTopStatements = checkTopStatements;
+exports.checkStats = checkStats;
+exports.DEFAULT_STATS_THRESHOLDS = {
+    minRows: 1000,
+    seqScanRatio: 10,
+    minIndexBytes: 1024 * 1024,
+    deadTupleRatio: 0.2,
+    minTimeShare: 0.05,
+    topStatements: 5
+};
+/**
+ * S1: a table the planner reaches by sequential scan far more often than by
+ * index. On a table above the row floor that is a missing index, a policy
+ * predicate the planner can't use, or a query shape nothing covers.
+ */
+function checkSeqScanDominant(table, thresholds) {
+    if (table.liveTuples < thresholds.minRows)
+        return null;
+    if (table.seqScans === 0)
+        return null;
+    if (table.seqScans < table.indexScans * thresholds.seqScanRatio)
+        return null;
+    // A table with no index at all is X6/X1 territory; the stats add nothing.
+    if (table.indexes.length === 0)
+        return null;
+    const perScan = Math.round(table.seqTuplesRead / Math.max(table.seqScans, 1));
+    return {
+        code: 'S1',
+        severity: 'medium',
+        category: 'index',
+        schema: table.schema,
+        table: table.name,
+        message: `${table.schema}.${table.name} is scanned sequentially ${table.seqScans} times vs ${table.indexScans} index scans (${table.liveTuples} live rows, ~${perScan} rows read per scan)`,
+        hint: 'Find the query shape behind the scans (pg_stat_statements, auto_explain) and index for it — at this row count every seq scan reads the whole table.',
+        context: {
+            seqScans: table.seqScans,
+            indexScans: table.indexScans,
+            liveTuples: table.liveTuples
+        }
+    };
+}
+/**
+ * S2: an index the planner has never chosen. It still costs write throughput,
+ * disk, and vacuum time. Constraint-backed and unique indexes are exempt:
+ * they exist to enforce a constraint, not to be scanned.
+ */
+function checkUnusedIndexes(table, thresholds) {
+    const findings = [];
+    for (const index of table.indexes) {
+        if (index.scans > 0)
+            continue;
+        if (index.unique || index.constraint)
+            continue;
+        if (index.sizeBytes < thresholds.minIndexBytes)
+            continue;
+        findings.push({
+            code: 'S2',
+            severity: 'low',
+            category: 'index',
+            schema: table.schema,
+            table: table.name,
+            message: `Index ${index.name} on ${table.schema}.${table.name} has never been scanned (${formatBytes(index.sizeBytes)})`,
+            hint: `DROP INDEX ${table.schema}.${index.name}; — confirm the counters cover a representative window first (see perf.stats.since).`,
+            context: { index: index.name, sizeBytes: index.sizeBytes }
+        });
+    }
+    return findings;
+}
+/**
+ * S3: dead tuples the vacuum is not keeping up with. Bloat inflates every
+ * scan of the table and every index on it, and the planner's row estimates
+ * drift with it.
+ */
+function checkDeadTuples(table, thresholds) {
+    if (table.liveTuples < thresholds.minRows)
+        return null;
+    const ratio = table.deadTuples / Math.max(table.liveTuples, 1);
+    if (ratio < thresholds.deadTupleRatio)
+        return null;
+    return {
+        code: 'S3',
+        severity: 'low',
+        category: 'index',
+        schema: table.schema,
+        table: table.name,
+        message: `${table.schema}.${table.name} is ${Math.round(ratio * 100)}% dead tuples (${table.deadTuples} dead / ${table.liveTuples} live${table.lastVacuum ? `, last vacuumed ${table.lastVacuum}` : ', never vacuumed'})`,
+        hint: 'VACUUM (ANALYZE) the table, then tune autovacuum for it (autovacuum_vacuum_scale_factor) — bloat is read by every scan and every index on the table.',
+        context: {
+            deadTuples: table.deadTuples,
+            liveTuples: table.liveTuples,
+            lastVacuum: table.lastVacuum
+        }
+    };
+}
+/**
+ * S4: the statements the database actually spends its time in, restricted to
+ * ones touching a table in scope. This is not a defect — it is the ranked
+ * list to read the other findings against, so it is `info` by default.
+ */
+function checkTopStatements(statements, tables, thresholds) {
+    const totalTime = statements.reduce((sum, s) => sum + s.totalTimeMs, 0);
+    if (totalTime <= 0)
+        return [];
+    const findings = [];
+    for (const statement of statements) {
+        if (findings.length >= thresholds.topStatements)
+            break;
+        const share = statement.totalTimeMs / totalTime;
+        if (share < thresholds.minTimeShare)
+            continue;
+        const matched = tables.filter((t) => statementTouches(statement.query, t));
+        if (matched.length === 0)
+            continue;
+        const relations = matched.map((t) => `${t.schema}.${t.name}`);
+        findings.push({
+            code: 'S4',
+            severity: 'info',
+            category: 'index',
+            schema: matched[0].schema,
+            table: matched[0].name,
+            message: `${Math.round(share * 100)}% of database execution time is spent in one statement over ${relations.join(', ')} (${statement.calls} calls, ${Math.round(statement.meanTimeMs)}ms mean)`,
+            hint: `EXPLAIN (ANALYZE, BUFFERS) this statement before acting on any other finding for these tables:\n    ${truncate(statement.query, 300)}`,
+            context: {
+                statement: truncate(statement.query, 300),
+                calls: statement.calls,
+                totalTimeMs: Math.round(statement.totalTimeMs),
+                meanTimeMs: Math.round(statement.meanTimeMs),
+                relations
+            }
+        });
+    }
+    return findings;
+}
+/** Every stats finding for one snapshot. */
+function checkStats(snapshot, thresholds = exports.DEFAULT_STATS_THRESHOLDS) {
+    const findings = [];
+    for (const table of snapshot.tables) {
+        const s1 = checkSeqScanDominant(table, thresholds);
+        if (s1)
+            findings.push(s1);
+        findings.push(...checkUnusedIndexes(table, thresholds));
+        const s3 = checkDeadTuples(table, thresholds);
+        if (s3)
+            findings.push(s3);
+    }
+    if (snapshot.statements) {
+        findings.push(...checkTopStatements(snapshot.statements, snapshot.tables, thresholds));
+    }
+    return findings;
+}
+/**
+ * Whether a normalised statement references a table. `pg_stat_statements`
+ * stores text, not parsed relations, so this matches the qualified name or
+ * the bare name on a word boundary — good enough to rank hotspots, and
+ * deliberately not used for anything that changes a severity.
+ */
+function statementTouches(query, table) {
+    const qualified = new RegExp(`\\b${escapeRegExp(table.schema)}\\.${escapeRegExp(table.name)}\\b`, 'i');
+    if (qualified.test(query))
+        return true;
+    const bare = new RegExp(`\\b(from|join|into|update)\\s+"?${escapeRegExp(table.name)}"?\\b`, 'i');
+    return bare.test(query);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function truncate(value, max) {
+    const collapsed = value.replace(/\s+/g, ' ').trim();
+    return collapsed.length <= max ? collapsed : `${collapsed.slice(0, max - 1)}…`;
+}
+function formatBytes(bytes) {
+    if (bytes >= 1024 * 1024 * 1024)
+        return `${(bytes / 1024 / 1024 / 1024).toFixed(1)} GiB`;
+    if (bytes >= 1024 * 1024)
+        return `${(bytes / 1024 / 1024).toFixed(1)} MiB`;
+    return `${Math.round(bytes / 1024)} KiB`;
+}

package/checks/view-exposure.d.ts

@@ -0,0 +1,68 @@
+/**
+ * L11 and L12: the two things a *readable* view does that its owner and its
+ * body, taken separately, do not explain.
+ *
+ * **L11 — a materialized view is a snapshot, not a query.** Its rows were
+ * computed once, by whoever ran `REFRESH`, and are then handed to every reader
+ * of the matview verbatim. The base relations are not consulted at read time,
+ * so their ACLs never apply and — the part that matters — their RLS policies
+ * never run. A matview cannot carry policies of its own either: RLS attaches
+ * to tables, and `security_invoker` is a view-only reloption. So a SELECT
+ * grant on a matview over an RLS-protected table is an unconditional grant on
+ * the rows that were visible at refresh time.
+ *
+ * **L12 — a view's `WHERE` is a filter, not a boundary.** Without
+ * `security_barrier` the planner may push the *caller's* qual below the view's
+ * own, so a leaky operator or a `COST 0.0001` function evaluates against rows
+ * the view was written to hide. The rows are not returned, but they are seen —
+ * and a function that raises them, writes them, or times differently on them
+ * exfiltrates them. This only matters where the view is the only path to the
+ * relation; if the caller can read the base table directly there is nothing
+ * for the view to hide.
+ *
+ * Both ship the same way as the rest of the L-series: `info`, score-neutral,
+ * and never recommending a revoke. The remedies are properties of the view.
+ */
+import type { ViewSnapshot } from '../pg/indexes';
+import type { TableSnapshot } from '../pg/introspect';
+import type { Finding } from '../types';
+import { type SuppressedView } from './definer-view';
+import { type LatticeRoleOptions, type RoleGraph } from './lattice';
+import { type ViewReachInput } from './role-reach';
+export interface ViewExposureAnalysis {
+    /** Materialized views whose bodies resolved — L11 inputs. */
+    matviews: ViewReachInput[];
+    /** Filtering definer views without `security_barrier` — L12 inputs. */
+    leaky: ViewReachInput[];
+    /** Views left out, with why. An unread body is not a clean bill. */
+    suppressed: SuppressedView[];
+}
+/**
+ * Resolve both populations in one pass over the view bodies.
+ *
+ * A materialized view is deliberately absent from the relation index: it is a
+ * terminal relation for anything reading *through* it (its rows are stored),
+ * so it must never be followed as a nested view. Its own body is still read,
+ * to learn which relations the refresh copied from.
+ */
+export declare function analyzeViewExposure(views: ViewSnapshot[], tables: TableSnapshot[]): Promise<ViewExposureAnalysis>;
+/**
+ * L11: an untrusted role reads a table's rows out of a materialized view.
+ *
+ * Fires where the role can SELECT the matview and either holds no SELECT on
+ * the relation the refresh read, or holds one but is subject to policies the
+ * stored rows never passed through. The second case is the one catalog-only
+ * analysis is worst at: the ACL says the role may read the table, RLS says it
+ * may read three rows of it, and the matview hands it all of them.
+ */
+export declare function checkMatviewSnapshot(matviews: ViewReachInput[], tables: TableSnapshot[], graph: RoleGraph, options?: LatticeRoleOptions): Finding[];
+/**
+ * L12: a definer view filters rows for an untrusted role but is not a barrier.
+ *
+ * Fires where the role reaches a relation *only* through a view whose body has
+ * a `WHERE`, and the view is not `security_barrier`. The finding is about the
+ * rows the view excludes: they are the ones the author meant to withhold, and
+ * without the barrier a cheap leaky qual supplied by the caller is evaluated
+ * against them.
+ */
+export declare function checkLeakyFilterView(views: ViewReachInput[], tables: TableSnapshot[], graph: RoleGraph, options?: LatticeRoleOptions): Finding[];