@safegres/test 0.0.2 → 1.30.7

package/esm/checks/definer-view.js

@@ -0,0 +1,382 @@
+/**
+ * L8: a view that is not `security_invoker` hands its readers the owner's
+ * privileges on every relation its body touches.
+ *
+ * A view executes as its owner unless it was created `WITH (security_invoker
+ * = true)`. So a role holding nothing but SELECT on the view reads the base
+ * relations under the *owner's* rights — including tables it has no grant on,
+ * and, when the owner owns the base table or bypasses RLS, without the row
+ * filter the base table's policies would have applied.
+ *
+ * Nothing in the catalog-only effective-access layer can see this:
+ * `effectiveGrants` never names the calling role on the base relation, and
+ * the base relation's ACL never names it either. The edge only exists in the
+ * view's *body*, which makes this the first rule that reads SQL rather than
+ * pure catalog — the `proof: 'ast'` edge of the reach model in `role-reach.ts`.
+ *
+ * Two conservatism rules the rest of the analysis depends on:
+ *
+ *   - **A body we cannot read is unknown, not empty.** Dynamic SQL or an
+ *     unparseable body suppresses the view entirely rather than producing a
+ *     partial (and therefore misleading) base-relation set.
+ *   - **The fix is never a revoke.** The grant on the view is what the API
+ *     serves; the defect is the view executing as its owner. L8 recommends
+ *     `security_invoker = true` or a different owner, and nothing else.
+ */
+import { extractQuery } from '../callgraph/extract';
+import { effectiveColumnGrants, effectiveGrants } from './lattice';
+import { computeViewReach } from './role-reach';
+/** How deep a chain of views on views is followed before giving up. */
+const MAX_VIEW_DEPTH = 8;
+/**
+ * Read every definer view's body and resolve the base relations it reaches.
+ *
+ * Nested views are followed: a definer view over an invoker view still
+ * executes the inner body as the *outer* owner, while an inner definer view
+ * switches the executing role again. Each resolved relation therefore carries
+ * the hops it passed through and the owner of the last one.
+ */
+export async function analyzeViewBodies(views, tables, auditedSchemas) {
+    // A materialized view stores its rows: reading it touches no base relation,
+    // so it is a leaf here, never an edge.
+    const queryable = views.filter((v) => !v.materialized);
+    const index = buildRelationIndex(queryable, tables, auditedSchemas);
+    const bodies = await readBodies(queryable);
+    const out = [];
+    const suppressed = [];
+    for (const view of queryable) {
+        if (view.securityInvoker)
+            continue;
+        const { bases, opaque, tainted } = resolveViewBases(view, index, bodies);
+        // An unreadable body is unknown, not empty: its fragmentary relation list
+        // is discarded, but the view stays in the model so the gap is reportable
+        // rather than a silent clean bill (L15).
+        if (opaque)
+            suppressed.push({ view: `${view.schema}.${view.name}`, reason: opaque });
+        const unreadable = opaque ?? tainted;
+        if (!unreadable && bases.length === 0)
+            continue;
+        out.push({
+            schema: view.schema,
+            name: view.name,
+            owner: view.owner,
+            grants: view.grants,
+            baseRelations: opaque ? [] : bases,
+            ...(unreadable ? { unreadable } : {})
+        });
+    }
+    return { views: out, suppressed };
+}
+export async function readBodies(views) {
+    const bodies = new Map();
+    for (const v of views)
+        bodies.set(`${v.schema}.${v.name}`, await extractQuery(v.definition));
+    return bodies;
+}
+/**
+ * The base relations `root` reads, following nested views, with the owner in
+ * force at each hop.
+ *
+ * `opaque` is set to the first reason the walk had to stop, and when it is set
+ * the relation list is a fragment: the caller must discard it, because a body
+ * we could only partly read under-reports what the view reaches.
+ *
+ * `root` itself need not be in `index` — a materialized view is not a
+ * queryable relation for the purposes of resolving *other* bodies, but its own
+ * body reads the same way.
+ */
+export function resolveViewBases(root, index, bodies) {
+    const bases = [];
+    const seen = new Set();
+    let opaque;
+    let tainted;
+    const walk = (current, hops) => {
+        const key = `${current.schema}.${current.name}`;
+        if (hops.length > MAX_VIEW_DEPTH) {
+            opaque ??= `view chain deeper than ${MAX_VIEW_DEPTH} hops`;
+            return;
+        }
+        const body = bodies.get(key);
+        if (!body)
+            return;
+        if (body.opaque) {
+            opaque ??= body.opaqueReason ?? 'body could not be read';
+            return;
+        }
+        // Readable, but it runs SQL of its own: the relations below are real and
+        // the list of them is a lower bound.
+        if (body.tainted)
+            tainted ??= `${key}: ${body.tainted}`;
+        for (const ref of body.tables) {
+            const relation = resolveRelation(ref, current.schema, index);
+            if (!relation)
+                continue; // a CTE, an alias, or a name we cannot pin down
+            if (relation.kind === 'view') {
+                const nested = relation.view;
+                if (`${nested.schema}.${nested.name}` === key)
+                    continue;
+                // An inner definer view re-owns the read; an inner invoker view runs
+                // under whichever owner is already in force.
+                const owner = nested.securityInvoker ? hops[hops.length - 1].owner : nested.owner;
+                walk(nested, [...hops, { view: `${nested.schema}.${nested.name}`, owner }]);
+                continue;
+            }
+            const relKey = `${relation.schema}.${relation.name}`;
+            const dedupe = `${relKey}::${hops[hops.length - 1].owner}`;
+            if (seen.has(dedupe))
+                continue;
+            seen.add(dedupe);
+            // Which columns escape is the catalog's answer, not the body's: the
+            // rewriter recorded one dependency row per column the view reads.
+            const columns = current.columnDeps?.find((d) => d.schema === relation.schema && d.table === relation.name)?.columns;
+            bases.push({
+                schema: relation.schema,
+                table: relation.name,
+                hops: [...hops],
+                ...(relation.kind === 'external' ? { external: true } : {}),
+                ...(columns ? { columns } : {})
+            });
+        }
+    };
+    walk(root, [{ view: `${root.schema}.${root.name}`, owner: root.owner }]);
+    return { bases, ...(opaque ? { opaque } : {}), ...(tainted ? { tainted } : {}) };
+}
+export function buildRelationIndex(views, tables, auditedSchemas) {
+    const viewsByName = new Map();
+    for (const v of views)
+        viewsByName.set(v.name, [...(viewsByName.get(v.name) ?? []), v]);
+    return {
+        tableKeys: new Set(tables.map((t) => `${t.schema}.${t.name}`)),
+        viewKeys: new Map(views.map((v) => [`${v.schema}.${v.name}`, v])),
+        viewsByName,
+        auditedSchemas: new Set(auditedSchemas ?? [...tables.map((t) => t.schema), ...views.map((v) => v.schema)])
+    };
+}
+/**
+ * Pin a body reference to a relation in the snapshot.
+ *
+ * `pg_get_viewdef` qualifies anything outside the creating `search_path` but
+ * leaves the rest bare, so an unqualified name is resolved against the view's
+ * own schema first and then against the snapshot as a whole — and only when
+ * exactly one relation answers to it. An ambiguous or unknown name (a CTE, a
+ * table alias, a relation outside the audited schemas) resolves to nothing:
+ * over-approximating here would attribute a read to a relation nobody named.
+ */
+export function resolveRelation(ref, viewSchema, { tableKeys, viewKeys, viewsByName, auditedSchemas }) {
+    const candidates = ref.schema ? [ref.schema] : [viewSchema];
+    for (const schema of candidates) {
+        const key = `${schema}.${ref.name}`;
+        const view = viewKeys.get(key);
+        if (view)
+            return { kind: 'view', view };
+        if (tableKeys.has(key))
+            return { kind: 'table', schema, name: ref.name };
+    }
+    // Qualified and unknown: either a relation the audit skipped (external, and
+    // the reach is still real) or a genuine miss inside a schema it did read.
+    if (ref.schema) {
+        return auditedSchemas.has(ref.schema)
+            ? null
+            : { kind: 'external', schema: ref.schema, name: ref.name };
+    }
+    const matches = [
+        ...[...tableKeys]
+            .filter((k) => k.endsWith(`.${ref.name}`))
+            .map((k) => ({ kind: 'table', schema: k.slice(0, -(ref.name.length + 1)), name: ref.name })),
+        ...(viewsByName.get(ref.name) ?? []).map((v) => ({ kind: 'view', view: v }))
+    ];
+    return matches.length === 1 ? matches[0] : null;
+}
+/**
+ * L8: an untrusted role reads a base relation through a definer view.
+ *
+ * Fires once per (role, view, base relation) where the role can SELECT the
+ * view, the view executes as someone else, and the role holds no SELECT of
+ * its own on the relation the view reads. A `security_invoker` view over the
+ * same shape produces nothing — it executes as the caller, so the base
+ * relation's own ACL and policies apply and there is no edge to report.
+ */
+export function checkDefinerViewBypass(views, tables, graph, options = {}) {
+    const untrusted = options.roles ?? [];
+    if (untrusted.length === 0 || views.length === 0)
+        return [];
+    const byKey = new Map(tables.map((t) => [`${t.schema}.${t.name}`, t]));
+    const out = [];
+    for (const { role, cells } of computeViewReach(views, graph, untrusted)) {
+        for (const cell of cells) {
+            if (cell.effectiveRole === role)
+                continue;
+            // A tainted cell names the view, not a base relation: there is nothing
+            // here to grade, and L15 reports it instead.
+            if (cell.proof === 'opaque-tainted')
+                continue;
+            const base = byKey.get(`${cell.schema}.${cell.table}`);
+            if (!base)
+                continue;
+            // Already reachable in its own right: the view launders nothing.
+            if (effectiveGrants(base, role, graph).some((g) => g.privilege === 'SELECT'))
+                continue;
+            // Nor does it when the columns that escape are ones the role could
+            // already read column-by-column (L13's closure) and the base has no RLS
+            // for the owner's read to skip. With RLS on, the projection matching is
+            // beside the point: the owner sees rows the caller's policies hide.
+            const granted = effectiveColumnGrants(base, role, graph)
+                .find((g) => g.privilege === 'SELECT');
+            if (cell.columns && granted && !base.rlsEnabled
+                && cell.columns.every((c) => granted.columns.includes(c)))
+                continue;
+            const hops = cell.path.filter((e) => e.kind === 'view');
+            const outermost = hops[0];
+            const owner = cell.effectiveRole;
+            const ownerAttrs = graph.get(owner);
+            // The owner is exempt from the base table's policies — either because
+            // it owns the table and FORCE is off, or because it bypasses RLS
+            // outright — so the rows the policies would have filtered come back.
+            const rlsBypassed = base.rlsEnabled
+                && (!!ownerAttrs?.bypassRls || (base.owner === owner && !base.rlsForced));
+            out.push({
+                code: 'L8',
+                severity: 'info',
+                category: 'anti-pattern',
+                schema: base.schema,
+                table: base.name,
+                role,
+                privilege: 'SELECT',
+                message: `Untrusted role ${role} reads ${base.schema}.${base.name}`
+                    + (cell.columns ? ` (${cell.columns.join(', ')})` : '')
+                    + ` through view ${outermost.view}, `
+                    + `which executes as its owner ${owner} — ${role} holds no SELECT on the base relation`
+                    + (rlsBypassed ? `, and ${owner} is not subject to its RLS policies` : ''),
+                hint: `The view is not \`security_invoker\`, so Postgres checks ${owner}'s privileges on the base `
+                    + `relation, not ${role}'s. Recreate it \`WITH (security_invoker = true)\` so the caller's `
+                    + `own grants and policies apply, or give it an owner whose reach matches what the view is `
+                    + `meant to expose. Do not revoke the SELECT on the view — that grant is what the API serves.`,
+                context: {
+                    view: outermost.view,
+                    effectiveRole: owner,
+                    viaViews: hops.map((h) => h.view),
+                    baseRlsEnabled: base.rlsEnabled,
+                    rlsBypassed,
+                    ...(cell.columns ? { columns: cell.columns } : {}),
+                    ...(granted ? { grantedColumns: granted.columns } : {}),
+                    proof: cell.proof
+                }
+            });
+        }
+    }
+    return out;
+}
+/**
+ * L14: a definer view hands an untrusted role a relation the audit never
+ * looked at.
+ *
+ * Excluding a schema is a statement about what is *graded*, not about what is
+ * *reachable*. A view in an audited schema can read `information_schema`,
+ * `pg_catalog`, an extension's tables, or any schema left out of
+ * `exposure.schemas` — and because that relation is not in the snapshot,
+ * every rule that grades a base relation silently drops the edge. The view
+ * looked clean because the audit could not see the far end.
+ *
+ * This is the one L-rule that reports an *absence of knowledge*. It says the
+ * read happens and that nothing was graded on the other side; it does not
+ * claim the relation is sensitive, and it recommends no revoke — the remedy
+ * is to bring the schema into scope, or to satisfy yourself that the
+ * projection is safe and leave it.
+ */
+export function checkUnauditedViewReach(views, graph, options = {}) {
+    const untrusted = options.roles ?? [];
+    if (untrusted.length === 0 || views.length === 0)
+        return [];
+    const out = [];
+    for (const { role, cells } of computeViewReach(views, graph, untrusted)) {
+        for (const cell of cells) {
+            if (!cell.external || cell.proof === 'opaque-tainted')
+                continue;
+            const hops = cell.path.filter((e) => e.kind === 'view');
+            const outermost = hops[0];
+            if (!outermost)
+                continue;
+            const owner = cell.effectiveRole;
+            out.push({
+                code: 'L14',
+                severity: 'info',
+                category: 'coverage',
+                schema: cell.schema,
+                table: cell.table,
+                role,
+                privilege: 'SELECT',
+                message: `Untrusted role ${role} reads ${cell.schema}.${cell.table} through view ${outermost.view} `
+                    + `as its owner ${owner}, and ${cell.schema} is outside the audited schemas — nothing `
+                    + 'graded what that relation exposes',
+                hint: `The read is proven from the view body; its consequences are not, because ${cell.schema} `
+                    + 'was never introspected. Add the schema to the audit (`schemas`, or remove it from '
+                    + '`excludeSchemas`) to grade the far end, or confirm the projection is safe to serve. '
+                    + 'This is a gap in coverage, not a proven leak: do not revoke anything on its strength.',
+                context: {
+                    view: outermost.view,
+                    effectiveRole: owner,
+                    viaViews: hops.map((h) => h.view),
+                    unauditedSchema: cell.schema,
+                    proof: cell.proof
+                }
+            });
+        }
+    }
+    return out;
+}
+/**
+ * **L15 — an untrusted role reads a view whose body this analysis cannot
+ * read.** The coverage sibling of L14: there, the far end was out of scope;
+ * here, the body itself is.
+ *
+ * Two shapes reach this rule, and the distinction is the point of the
+ * `tainted` bit in {@link ExtractedBody}. A body that could not be read at all
+ * — an unparseable definition, a chain deeper than the hop limit — yields no
+ * relations, and every rule that grades a base relation had nothing to grade.
+ * A body that *was* read but calls something executing SQL of its own
+ * (`dblink`, `query_to_xml`) yields relations that are all real and not all of
+ * them: the graded ones still grade, and the gap is what is reported here.
+ *
+ * Either way the view executes as its owner and an untrusted role can read it,
+ * so the reach is proven and only its far end is unknown — which is exactly
+ * `proof: 'opaque-tainted'`, the state the reach model has carried since it
+ * was written and nothing could produce until now.
+ *
+ * Like L14 it is `info`/`neutral` and recommends no revoke: an unknown is not
+ * a leak, and scoring one would let an unreadable body move the number.
+ */
+export function checkUnreadableViewReach(views, graph, options = {}) {
+    const untrusted = options.roles ?? [];
+    if (untrusted.length === 0 || views.length === 0)
+        return [];
+    const out = [];
+    for (const { role, cells } of computeViewReach(views, graph, untrusted)) {
+        for (const cell of cells) {
+            if (cell.proof !== 'opaque-tainted')
+                continue;
+            out.push({
+                code: 'L15',
+                severity: 'info',
+                category: 'coverage',
+                schema: cell.schema,
+                table: cell.table,
+                role,
+                privilege: 'SELECT',
+                message: `Untrusted role ${role} reads view ${cell.schema}.${cell.table}, which executes as its `
+                    + `owner ${cell.effectiveRole} and whose body this analysis could not fully read `
+                    + `(${cell.taint}) — what it reaches under that owner was never graded`,
+                hint: 'The read is proven; what it reaches is not, so no view rule graded this path. Rewrite '
+                    + 'the body so the relations it reads are visible statically, or satisfy yourself that '
+                    + 'what it returns is safe to serve this role. Reporting stayed silent rather than '
+                    + 'guessing, and nothing here justifies a revoke.',
+                context: {
+                    view: `${cell.schema}.${cell.table}`,
+                    effectiveRole: cell.effectiveRole,
+                    taint: cell.taint,
+                    proof: cell.proof
+                }
+            });
+        }
+    }
+    return out;
+}

package/esm/checks/indexes.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Structural index-hygiene checks (perf dimension, `X*`).
+ *
+ * Everything here is pure catalog analysis — deterministic, workload-free,
+ * and safe to run in CI against an empty database.
+ */
+import type { TableIndexSnapshot } from '../pg/indexes';
+import { type AccessPath } from '../pg/paths';
+import type { Finding } from '../types';
+/**
+ * What X1 does with a foreign key whose only evidence is shape — it looks like
+ * a write-once provisioning pointer, but nothing has proven the path is
+ * unreachable.
+ *
+ * `report` is the default and the only honest one until a signal exists that
+ * can observe the generated API surface: the finding stands, and the shape is
+ * attached to it as context so a reviewer can act on it. The other two exist
+ * so the decision is a line of config rather than a fork of the scanner.
+ *
+ * `demote` is applied in `audit()` rather than here, because severities are
+ * restamped from the rule registry after the checks run.
+ */
+export type WriteOncePointerPolicy = 'report' | 'demote' | 'suppress';
+/**
+ * X1: a foreign key with no index that can serve it.
+ *
+ * An index covers a FK when its *leading* columns are exactly the FK's
+ * columns (order among them is irrelevant for equality lookups) and it
+ * covers every row. Without one, `ON DELETE`/`ON UPDATE` checks on the
+ * referenced side and joins on the referencing side degrade to sequential
+ * scans.
+ *
+ * Partial and expression indexes do not count: the planner cannot rely on
+ * them for the referential-integrity lookup.
+ *
+ * `paths` supplies the access-path signals. They never remove a finding on
+ * their own — see {@link WriteOncePointerPolicy} and `classifyPaths`.
+ */
+export declare function checkUnindexedForeignKeys(table: TableIndexSnapshot, paths?: Map<string, AccessPath>, onWriteOncePointer?: WriteOncePointerPolicy): Finding[];
+/**
+ * X5: an index that another index already serves.
+ *
+ * Two shapes: an exact duplicate, or a non-unique index whose columns are a
+ * leading-column prefix of a wider index. Both cost write throughput and
+ * disk for nothing. Constraint-backed indexes (PK/UNIQUE/EXCLUDE) are never
+ * reported — dropping them would drop the constraint.
+ *
+ * An index attached to a parent's partitioned index is never reported either:
+ * it can only be dropped with the parent's index, and the parent carries that
+ * finding once instead of every partition repeating it. An index created on
+ * the partition alone is the partition's own, and is reported there.
+ */
+export declare function checkRedundantIndexes(table: TableIndexSnapshot): Finding[];
+/**
+ * X6: no primary key and no usable replica identity.
+ *
+ * Rows cannot be addressed individually: updates and deletes have no cheap
+ * lookup path, logical replication and CDC cannot identify old rows, and
+ * realtime/change-feed features break.
+ */
+export declare function checkMissingPrimaryKey(table: TableIndexSnapshot): Finding | null;
+/**
+ * X7: a search column with no index the search can use.
+ *
+ * A `tsvector` or `vector` column is exposed as a search field by
+ * `graphile-search` purely from its type — the schema promises a fast path.
+ * Without a GIN/GiST (full-text) or HNSW/IVFFlat (vector) index the promise
+ * is served by a sequential scan plus a per-row distance or match computation,
+ * which is the single worst plan the API can produce.
+ */
+export declare function checkUnindexedSearchColumns(table: TableIndexSnapshot): Finding[];
+/**
+ * X8: a sort-shaped column that leads no index.
+ *
+ * Every PostGraphile connection can be ordered by any column and paginated
+ * with a cursor over that order. Sorting on an unindexed column forces a full
+ * sort of the (RLS-filtered) result on every page, and keyset pagination
+ * degenerates into a scan-and-discard. Timestamp columns are singled out
+ * because they are what feeds are actually ordered by — a heuristic, hence
+ * `info` by default; turn it off with `perf.rules: { "X8": "off" }`.
+ */
+export declare function checkUnindexedSortColumns(table: TableIndexSnapshot): Finding[];