@safegres/test 0.0.2 → 1.30.7

package/esm/perf/explain.js

@@ -0,0 +1,201 @@
+/**
+ * Proof by EXPLAIN (`--explain`).
+ *
+ * The `X*` rules infer from the catalog that a query *shape* has no index to
+ * serve it. This turns the inference into evidence: for each finding that has
+ * a probe shape, plan the query the finding is about and read the plan back.
+ *
+ * The planner is the authority, so the interesting outcome is disagreement —
+ * a finding whose probe plans as an index scan is **refuted** (some index the
+ * catalog rules didn't credit does serve it) and stops counting against the
+ * score. The reverse is not symmetrical: an empty or unanalyzed table always
+ * seq-scans, so a seq scan only *confirms* a finding above the row floor;
+ * below it the probe is inconclusive and the finding is left exactly as it
+ * was.
+ *
+ * Probes use `EXPLAIN (GENERIC_PLAN)` — parameters stay parameters, nothing
+ * is executed, and no value has to be invented for a column whose domain we
+ * know nothing about. That requires PostgreSQL 16+.
+ */
+/** The minimum server version supporting `EXPLAIN (GENERIC_PLAN)`. */
+const MIN_SERVER_VERSION = 160000;
+/**
+ * Plan a probe for every probeable perf finding and annotate it in place.
+ * Findings the planner refutes are acknowledged (reported, unscored).
+ */
+export async function proveFindings(exec, findings, tables, options = {}) {
+    const minRows = options.minRows ?? 1000;
+    const report = { probed: 0, confirmed: 0, refuted: 0, inconclusive: 0 };
+    const { rows: versionRows } = await exec.query(`SELECT setting FROM pg_settings WHERE name = 'server_version_num'`);
+    const version = versionRows[0];
+    if (Number(version?.setting ?? 0) < MIN_SERVER_VERSION) {
+        report.unavailable =
+            `EXPLAIN (GENERIC_PLAN) requires PostgreSQL 16 or later (server is ${version?.setting ?? 'unknown'}) — no findings were probed`;
+        return report;
+    }
+    for (const finding of findings) {
+        if (!finding.schema || !finding.table)
+            continue;
+        const table = tables.get(`${finding.schema}.${finding.table}`);
+        if (!table)
+            continue;
+        const probe = buildProbe(finding, table);
+        if (!probe)
+            continue;
+        const plan = await planProbe(exec, probe.sql);
+        if (!plan)
+            continue;
+        report.probed += 1;
+        const nodes = collectNodeTypes(plan);
+        const servedByIndex = nodes.some((n) => n.includes('Index'));
+        const predicted = probe.expect === 'sort'
+            ? nodes.includes('Sort') || nodes.includes('Incremental Sort')
+            : nodes.includes('Seq Scan');
+        const evidence = {
+            source: 'explain',
+            probe: probe.sql,
+            plan: nodes.join(' → '),
+            status: 'inconclusive'
+        };
+        if (servedByIndex && !predicted) {
+            evidence.status = 'refuted';
+            report.refuted += 1;
+            finding.acknowledged = true;
+            finding.severity = 'info';
+            finding.message += ' — refuted by EXPLAIN (the planner serves this shape with an index)';
+            finding.hint =
+                'The planner chose an index for the probe query, so this finding does not describe a real plan. Reported for review, excluded from the perf score.';
+        }
+        else if (predicted && estimatedRows(table) >= minRows) {
+            evidence.status = 'confirmed';
+            report.confirmed += 1;
+        }
+        else {
+            report.inconclusive += 1;
+            evidence.note = estimatedRows(table) < minRows
+                ? `table has ~${Math.max(estimatedRows(table), 0)} estimated rows (< ${minRows}); a sequential scan is the correct plan at this size, so the probe proves nothing`
+                : 'the probe plan matched neither an index scan nor the predicted scan';
+        }
+        finding.evidence = evidence;
+    }
+    return report;
+}
+/**
+ * The query a finding is a claim about. `null` for findings with no probeable
+ * shape (X5 redundant indexes, X6 missing PK, S*, P*) — nothing is planned
+ * speculatively, so `--explain` never invents work.
+ */
+function buildProbe(finding, table) {
+    const relation = `${quote(table.schema)}.${quote(table.name)}`;
+    const context = finding.context ?? {};
+    switch (finding.code) {
+        case 'X1': {
+            const columns = asStringArray(context.columns);
+            if (columns.length === 0)
+                return null;
+            const predicates = columns
+                .map((name, i) => equality(table, name, i + 1))
+                .filter((p) => p !== null);
+            if (predicates.length !== columns.length)
+                return null;
+            return { sql: `SELECT 1 FROM ${relation} WHERE ${predicates.join(' AND ')}`, expect: 'seq-scan' };
+        }
+        case 'X2': {
+            const predicate = typeof context.column === 'string'
+                ? equality(table, context.column, 1)
+                : null;
+            if (!predicate)
+                return null;
+            return { sql: `SELECT 1 FROM ${relation} WHERE ${predicate}`, expect: 'seq-scan' };
+        }
+        case 'X7': {
+            const column = typeof context.column === 'string' ? context.column : null;
+            if (!column)
+                return null;
+            const type = columnType(table, column);
+            if (!type)
+                return null;
+            if (type === 'tsvector') {
+                return {
+                    sql: `SELECT 1 FROM ${relation} WHERE ${quote(column)} @@ $1::tsquery`,
+                    expect: 'seq-scan'
+                };
+            }
+            // Vector search is an ordering, not a filter: the index either serves
+            // the distance order or the plan sorts every row.
+            return {
+                sql: `SELECT 1 FROM ${relation} ORDER BY ${quote(column)} <-> $1::${type} LIMIT 10`,
+                expect: 'sort'
+            };
+        }
+        case 'X8': {
+            const column = typeof context.column === 'string' ? context.column : null;
+            if (!column)
+                return null;
+            return {
+                sql: `SELECT 1 FROM ${relation} ORDER BY ${quote(column)} DESC LIMIT 100`,
+                expect: 'sort'
+            };
+        }
+        default:
+            return null;
+    }
+}
+async function planProbe(exec, sql) {
+    try {
+        const { rows } = await exec.query(`EXPLAIN (GENERIC_PLAN, FORMAT JSON) ${sql}`);
+        const first = rows[0];
+        if (!first)
+            return null;
+        // node-postgres returns the single JSON column under 'QUERY PLAN'.
+        const value = first['QUERY PLAN'] ?? Object.values(first)[0];
+        return typeof value === 'string' ? JSON.parse(value) : value;
+    }
+    catch {
+        // A probe that cannot be planned (missing operator class, permissions,
+        // an exotic type) is simply not evidence.
+        return null;
+    }
+}
+/** Plan node types, outermost first. */
+function collectNodeTypes(plan) {
+    const out = [];
+    const visit = (node) => {
+        if (Array.isArray(node)) {
+            for (const item of node)
+                visit(item);
+            return;
+        }
+        if (!node || typeof node !== 'object')
+            return;
+        const record = node;
+        if (typeof record['Node Type'] === 'string')
+            out.push(record['Node Type']);
+        for (const key of ['Plan', 'Plans']) {
+            if (key in record)
+                visit(record[key]);
+        }
+    };
+    visit(plan);
+    return out;
+}
+function equality(table, column, param) {
+    const type = columnType(table, column);
+    if (!type)
+        return null;
+    return `${quote(column)} = $${param}::${type}`;
+}
+function columnType(table, column) {
+    return table.columns.find((c) => c.name === column)?.type ?? null;
+}
+function estimatedRows(table) {
+    return table.estimatedRows;
+}
+function asStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((v) => typeof v === 'string');
+}
+function quote(identifier) {
+    return `"${identifier.replace(/"/g, '""')}"`;
+}

package/esm/pg/acl.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Role-graph and schema-ACL introspection for the grant/policy lattice.
+ *
+ * The table snapshot reports grants exactly as the catalog stores them —
+ * `GRANT TO PUBLIC` is one row, membership in a granted role is zero rows.
+ * The lattice rules reason about *effective* access, which needs:
+ *
+ *   - the role inheritance closure (`pg_auth_members`, INHERIT-respecting);
+ *   - which roles bypass RLS entirely (superuser / BYPASSRLS);
+ *   - schema USAGE ACLs (an object grant without USAGE on its schema is
+ *     unreachable);
+ *   - whether a schema holds any function the role can EXECUTE (so "dead
+ *     schema USAGE" doesn't false-positive on function-only schemas).
+ */
+import type { QueryExecutor } from './introspect';
+export interface RoleAttributes {
+    name: string;
+    /** Superuser or BYPASSRLS — policies never apply. */
+    bypassRls: boolean;
+    /** Superuser — ACL checks never apply either. */
+    isSuper: boolean;
+    /**
+     * Roles this role inherits privileges from, transitively. Only memberships
+     * that actually confer inheritance (INHERIT) are followed.
+     */
+    inheritsFrom: string[];
+    /**
+     * Roles this role can assume with `SET ROLE`, transitively. Distinct from
+     * `inheritsFrom`: on PG16+ a membership can confer the ability to `SET ROLE`
+     * (`pg_auth_members.set_option`) *without* passive inheritance, so a role
+     * that reaches nothing by inheritance can still execute with a target
+     * role's full privileges by assuming it. Excludes the role itself.
+     */
+    canSetRole: string[];
+}
+export interface SchemaAclGrant {
+    role: string;
+    privilege: 'USAGE' | 'CREATE';
+}
+export interface SchemaAclInfo {
+    schema: string;
+    owner: string;
+    grants: SchemaAclGrant[];
+    /** Roles (incl. 'PUBLIC') holding EXECUTE on at least one function in the schema. */
+    executeRoles: string[];
+}
+/**
+ * Every non-system role with its RLS-bypass flags, its transitive
+ * INHERIT-following membership closure, and its transitive `SET ROLE`
+ * (`set_option`) closure.
+ */
+export declare function introspectRoleGraph(exec: QueryExecutor): Promise<Map<string, RoleAttributes>>;
+export interface SchemaAclOptions {
+    schemas?: string[];
+    excludeSchemas?: string[];
+}
+/**
+ * Schema ACLs plus, per schema, the roles holding EXECUTE on at least one of
+ * its functions. A NULL `nspacl` means the default ACL (owner-only + nothing
+ * for PUBLIC on non-`public` schemas); a NULL `proacl` means EXECUTE for
+ * PUBLIC, which is why the EXECUTE aggregation has to account for it.
+ */
+export declare function introspectSchemaAcls(exec: QueryExecutor, options?: SchemaAclOptions): Promise<SchemaAclInfo[]>;
+/**
+ * The role can enter the schema, so a grant on something inside it is reach.
+ *
+ * The same gate L3 applies to a table grant, applied to a schema's contents:
+ * without `USAGE` the object cannot be named, and Postgres's default
+ * EXECUTE-to-PUBLIC would otherwise make every function in an internal schema
+ * look reachable by every role in the database.
+ */
+export declare function canEnterSchema(schema: string, role: string, graph: Map<string, RoleAttributes>, schemaAcls: Map<string, SchemaAclInfo>): boolean;

package/esm/pg/acl.js

@@ -0,0 +1,186 @@
+/**
+ * Role-graph and schema-ACL introspection for the grant/policy lattice.
+ *
+ * The table snapshot reports grants exactly as the catalog stores them —
+ * `GRANT TO PUBLIC` is one row, membership in a granted role is zero rows.
+ * The lattice rules reason about *effective* access, which needs:
+ *
+ *   - the role inheritance closure (`pg_auth_members`, INHERIT-respecting);
+ *   - which roles bypass RLS entirely (superuser / BYPASSRLS);
+ *   - schema USAGE ACLs (an object grant without USAGE on its schema is
+ *     unreachable);
+ *   - whether a schema holds any function the role can EXECUTE (so "dead
+ *     schema USAGE" doesn't false-positive on function-only schemas).
+ */
+/**
+ * Every non-system role with its RLS-bypass flags, its transitive
+ * INHERIT-following membership closure, and its transitive `SET ROLE`
+ * (`set_option`) closure.
+ */
+export async function introspectRoleGraph(exec) {
+    const { rows: roleRows } = await exec.query(`
+    SELECT rolname, rolsuper, rolbypassrls, rolinherit
+    FROM pg_roles
+    WHERE rolname NOT LIKE 'pg\\_%'
+    ORDER BY rolname
+  `);
+    let memberRows;
+    try {
+        const { rows } = await exec.query(`
+      SELECT m.rolname AS member, p.rolname AS parent,
+             am.inherit_option AS inherits, am.set_option AS "canSet"
+      FROM pg_auth_members am
+      JOIN pg_roles m ON m.oid = am.member
+      JOIN pg_roles p ON p.oid = am.roleid
+      WHERE m.rolname NOT LIKE 'pg\\_%' AND p.rolname NOT LIKE 'pg\\_%'
+    `);
+        memberRows = rows;
+    }
+    catch (e) {
+        if (!isUndefinedColumn(e))
+            throw e;
+        const { rows } = await exec.query(`
+      SELECT m.rolname AS member, p.rolname AS parent,
+             m.rolinherit AS inherits, true AS "canSet"
+      FROM pg_auth_members am
+      JOIN pg_roles m ON m.oid = am.member
+      JOIN pg_roles p ON p.oid = am.roleid
+      WHERE m.rolname NOT LIKE 'pg\\_%' AND p.rolname NOT LIKE 'pg\\_%'
+    `);
+        memberRows = rows;
+    }
+    const parents = new Map();
+    const setTargets = new Map();
+    for (const m of memberRows) {
+        if (m.inherits) {
+            const list = parents.get(m.member) ?? [];
+            list.push(m.parent);
+            parents.set(m.member, list);
+        }
+        if (m.canSet) {
+            const list = setTargets.get(m.member) ?? [];
+            list.push(m.parent);
+            setTargets.set(m.member, list);
+        }
+    }
+    const graph = new Map();
+    for (const r of roleRows) {
+        graph.set(r.rolname, {
+            name: r.rolname,
+            bypassRls: r.rolsuper || r.rolbypassrls,
+            isSuper: r.rolsuper,
+            inheritsFrom: closure(r.rolname, parents),
+            canSetRole: closure(r.rolname, setTargets)
+        });
+    }
+    return graph;
+}
+/** Transitive parents of `role`, excluding itself, cycle-safe. */
+function closure(role, parents) {
+    const seen = new Set();
+    const stack = [...(parents.get(role) ?? [])];
+    while (stack.length > 0) {
+        const next = stack.pop();
+        if (next === role || seen.has(next))
+            continue;
+        seen.add(next);
+        stack.push(...(parents.get(next) ?? []));
+    }
+    return [...seen].sort();
+}
+function isUndefinedColumn(e) {
+    return e.code === '42703';
+}
+const DEFAULT_EXCLUDES = ['pg_catalog', 'information_schema', 'pg_toast'];
+/**
+ * Schema ACLs plus, per schema, the roles holding EXECUTE on at least one of
+ * its functions. A NULL `nspacl` means the default ACL (owner-only + nothing
+ * for PUBLIC on non-`public` schemas); a NULL `proacl` means EXECUTE for
+ * PUBLIC, which is why the EXECUTE aggregation has to account for it.
+ */
+export async function introspectSchemaAcls(exec, options = {}) {
+    const excludes = [...DEFAULT_EXCLUDES, ...(options.excludeSchemas ?? [])];
+    const schemaFilter = options.schemas && options.schemas.length > 0
+        ? `AND n.nspname = ANY($1::text[])`
+        : `AND NOT (n.nspname = ANY($2::text[]))`;
+    const sql = `
+    WITH _params AS (
+      SELECT $1::text[] AS include_schemas, $2::text[] AS exclude_schemas
+    ),
+    ns AS (
+      SELECT n.oid, n.nspname, pg_get_userbyid(n.nspowner) AS owner, n.nspacl
+      FROM pg_namespace n
+      WHERE n.nspname NOT LIKE 'pg\\_%'
+        ${schemaFilter}
+    ),
+    schema_grants AS (
+      SELECT
+        ns.oid,
+        CASE WHEN a.grantee = 0 THEN 'PUBLIC' ELSE rol.rolname END AS grantee,
+        a.privilege_type
+      FROM ns, aclexplode(ns.nspacl) a
+      LEFT JOIN pg_roles rol ON rol.oid = a.grantee
+      WHERE ns.nspacl IS NOT NULL
+    ),
+    fn_execute AS (
+      SELECT
+        p.pronamespace AS oid,
+        CASE
+          WHEN p.proacl IS NULL THEN 'PUBLIC'
+          WHEN a.grantee = 0 THEN 'PUBLIC'
+          ELSE rol.rolname
+        END AS grantee
+      FROM pg_proc p
+      LEFT JOIN LATERAL aclexplode(p.proacl) a
+        ON p.proacl IS NOT NULL AND a.privilege_type = 'EXECUTE'
+      LEFT JOIN pg_roles rol ON rol.oid = a.grantee
+      WHERE p.pronamespace IN (SELECT oid FROM ns)
+    )
+    SELECT
+      ns.nspname AS schema_name,
+      ns.owner,
+      COALESCE(
+        (SELECT jsonb_agg(DISTINCT jsonb_build_object('role', g.grantee, 'privilege', g.privilege_type))
+         FROM schema_grants g WHERE g.oid = ns.oid),
+        '[]'::jsonb
+      ) AS grants,
+      COALESCE(
+        (SELECT array_agg(DISTINCT f.grantee) FROM fn_execute f
+         WHERE f.oid = ns.oid AND f.grantee IS NOT NULL),
+        ARRAY[]::text[]
+      ) AS execute_roles
+    FROM ns
+    ORDER BY ns.nspname
+  `;
+    const { rows } = await exec.query(sql, [options.schemas ?? [], excludes]);
+    return rows.map((r) => ({
+        schema: r.schema_name,
+        owner: r.owner,
+        grants: r.grants
+            .filter((g) => g.privilege === 'USAGE' || g.privilege === 'CREATE')
+            .map((g) => ({ role: g.role, privilege: g.privilege })),
+        executeRoles: r.execute_roles
+    }));
+}
+/**
+ * The role can enter the schema, so a grant on something inside it is reach.
+ *
+ * The same gate L3 applies to a table grant, applied to a schema's contents:
+ * without `USAGE` the object cannot be named, and Postgres's default
+ * EXECUTE-to-PUBLIC would otherwise make every function in an internal schema
+ * look reachable by every role in the database.
+ */
+export function canEnterSchema(schema, role, graph, schemaAcls) {
+    const acl = schemaAcls.get(schema);
+    if (!acl)
+        return true; // not introspected: assume reachable rather than silently drop
+    const attrs = graph.get(role);
+    if (attrs?.isSuper)
+        return true;
+    if (role === acl.owner)
+        return true;
+    const usage = new Set(acl.grants.filter((g) => g.privilege === 'USAGE').map((g) => g.role));
+    if (usage.has('PUBLIC') || usage.has(role))
+        return true;
+    return (attrs?.inheritsFrom ?? []).some((a) => usage.has(a) || a === acl.owner);
+}

package/esm/pg/behaviors.d.ts

@@ -0,0 +1,114 @@
+/**
+ * PostGraphile *behaviors*, read from the object comments they are declared in.
+ *
+ * A behavior string is the schema author stating which parts of the generated
+ * API an object participates in — `@behavior -list -connection` on a foreign
+ * key constraint says the reverse relation is not exposed. That is a different
+ * kind of evidence from anything else safegres collects: `pg_class.reltuples`
+ * and `pg_stat_user_indexes.idx_scan` are *measurements*, and safegres grades
+ * an ephemeral CI database that has never held data, so both read zero at
+ * exactly the moment they would have to mean something. A declaration reads the
+ * same in CI as in production.
+ *
+ * Read from the comment rather than from a running Graphile instance, or from
+ * whatever tables the author generated the comment out of:
+ *
+ * - `@behavior` in a comment is the PostGraphile v5 convention, so this works
+ *   on any Graphile database rather than one project's metadata schema.
+ * - The comment is the composed value — one tag per object — so it is already
+ *   the author's resolved intent.
+ * - A live instance would additionally resolve preset defaults, but requires an
+ *   API to be running. safegres grades a database.
+ *
+ * The consequence of that last point is the rule this module exists to enforce:
+ * **only an explicit negative fragment is evidence.** Presets grant most
+ * behaviors by default, so the *absence* of `+list` says nothing whatsoever. A
+ * scanner that reads silence as denial is a scanner that tells you to drop an
+ * index a live API is using.
+ */
+import type { IntrospectOptions, QueryExecutor } from './introspect';
+/** One `[+|-]scope` term of a behavior string. */
+export interface BehaviorFragment {
+    modifier: '+' | '-';
+    /**
+     * The scope as written, e.g. `list`, `resource:connection`, `*`. Scope paths
+     * are `:`-separated and increasingly specific left to right.
+     */
+    scope: string;
+}
+/**
+ * The three behavior tags a relation can carry.
+ *
+ * `@behavior` applies to *both* directions of a foreign key. Graphile also
+ * accepts `@forwardBehavior` and `@backwardBehavior`, which apply to only one
+ * — and the distinction is not cosmetic: denying `list` with a plain
+ * `@behavior` removes the forward `post.author` field as well as the reverse
+ * `author.posts` list, which is almost never what the author meant.
+ */
+export interface ConstraintBehaviors {
+    /** `@behavior` — applies to both directions. */
+    both?: string;
+    /** `@forwardBehavior` — the referencing table's field pointing at the parent. */
+    forward?: string;
+    /** `@backwardBehavior` — the referenced table's field listing the children. */
+    backward?: string;
+}
+/** Behaviors found on each kind of object, keyed as described on each map. */
+export interface BehaviorSnapshot {
+    /** `schema.table` → behavior string. */
+    tables: Map<string, string>;
+    /** `schema.table.column` → behavior string. */
+    columns: Map<string, string>;
+    /** `schema.table.constraint` → behavior string. */
+    constraints: Map<string, string>;
+    /** `schema.table.constraint` → the directional tags on that constraint. */
+    constraintDirections: Map<string, ConstraintBehaviors>;
+}
+export declare function emptyBehaviorSnapshot(): BehaviorSnapshot;
+/**
+ * The behavior governing one direction of a relation: the directional tag when
+ * present, else the undirected one. They do not merge — Graphile resolves the
+ * specific tag against the preset, and treating `@behavior -list` as an extra
+ * fragment on top of `@backwardBehavior +list` would invert the author's
+ * override.
+ */
+export declare function directionalBehavior(behaviors: ConstraintBehaviors | undefined, direction: 'forward' | 'backward'): string | undefined;
+/** Catalog schemas no API surface ever contains. */
+export declare const SYSTEM_SCHEMAS: string[];
+/**
+ * Extract the `@behavior` smart tag from an object comment.
+ *
+ * Smart tags occupy the leading lines of the comment, `@tag [value]`, and stop
+ * at the first line that is not one; everything after is the description. Only
+ * `@behavior` is returned — `@omit` is deliberately not translated here, since
+ * its v4 semantics ("remove from the schema") are not the same question as a
+ * behavior fragment and conflating them would put a guess in the evidence.
+ */
+export declare function parseBehaviorTag(comment: string | null | undefined): string | null;
+/** Every behavior tag on a comment, by direction. */
+export declare function parseBehaviorTags(comment: string | null | undefined): ConstraintBehaviors;
+/** Split a behavior string into fragments. A bare scope is a grant, as in PostGraphile. */
+export declare function parseFragments(behavior: string | null | undefined): BehaviorFragment[];
+/**
+ * Resolve one ability against a behavior string.
+ *
+ * `undefined` means *undeclared*, and is the answer that matters: it is not
+ * `false`. Later fragments win, matching PostGraphile — `-* +list` grants
+ * `list` and denies the rest.
+ */
+export declare function resolveAbility(behavior: string | null | undefined, ability: string): boolean | undefined;
+/**
+ * True when *every* one of `abilities` is explicitly denied.
+ *
+ * Every, not some: a relation reachable as a single record is still reachable,
+ * and one undeclared ability is enough to leave the question open.
+ */
+export declare function deniesAll(behavior: string | null | undefined, abilities: string[]): boolean;
+/**
+ * Behavior tags on every table, column and constraint in scope.
+ *
+ * Extension-owned objects are not filtered here: the maps are only ever
+ * consulted for relations that survived the scan's own filtering, so an extra
+ * entry costs a map slot and changes nothing.
+ */
+export declare function introspectBehaviors(exec: QueryExecutor, options?: Pick<IntrospectOptions, 'schemas' | 'excludeSchemas'>): Promise<BehaviorSnapshot>;