@safegres/test 0.0.1 → 1.30.7

package/esm/commands/audit.js

@@ -0,0 +1,776 @@
+/**
+ * Script A driver: pure-Postgres RLS audit.
+ *
+ * Ingests a catalog snapshot, runs every check, and returns a structured report.
+ */
+import { buildCallGraph } from '../callgraph/graph';
+import { checkSessionUserGating, checkTriviallyPermissive, checkVolatileFunctions, collectFunctionNames, parseOrNull } from '../checks/anti-patterns';
+import { checkUntrustedColumnGrants } from '../checks/column-grants';
+import { checkCoverageGaps, checkUpdateWithCheckCoverage } from '../checks/coverage';
+import { analyzeFunctionBodies, checkDefinerFunctionReach, checkInsteadOfTriggerWrite, checkUnreadableFunctionReach } from '../checks/definer-function';
+import { analyzeViewBodies, checkDefinerViewBypass, checkUnauditedViewReach, checkUnreadableViewReach } from '../checks/definer-view';
+import { checkMissingPrimaryKey, checkRedundantIndexes, checkUnindexedForeignKeys, checkUnindexedSearchColumns, checkUnindexedSortColumns } from '../checks/indexes';
+import { checkDeadPolicies, checkDeadSchemaUsage, checkIndirectCoverageGaps, checkUnaddressableGrant, checkUnreachableGrants, checkUntrustedIndirectAccess, computeRoleAccess } from '../checks/lattice';
+import { checkUntrustedForeignTableGrants, checkUntrustedSequenceGrants } from '../checks/object-acls';
+import { checkNonLeakproofPolicyFunctions, checkPolicyColumnCasts, checkUnhoistedPolicyFunctions, checkUnindexedPolicyColumns, collectPredicateColumns } from '../checks/policy-index';
+import { analyzeRevocableGrants, revocableGrantFindings } from '../checks/revocable-grants';
+import { checkGrantsWithoutRls, checkRlsEnabledNoPolicies, checkRlsNotForced } from '../checks/rls-flags';
+import { checkPublicGrants, checkUntrustedRolePolicies, checkUntrustedRoleWrites } from '../checks/role-trust';
+import { checkSetRoleEscalation } from '../checks/set-role';
+import { checkStats, DEFAULT_STATS_THRESHOLDS } from '../checks/stats';
+import { analyzeViewExposure, checkLeakyFilterView, checkMatviewSnapshot } from '../checks/view-exposure';
+import { analyzeViewWrites, checkDefinerViewWrite, checkUncheckedViewWrite, checkViewRuleBypass } from '../checks/view-writes';
+import { configFingerprint } from '../config/fingerprint';
+import { allAstRulesDisabled, applyRulesToFindings, matchTablePattern, resolveRules, rulesForTable } from '../config/resolve';
+import { resolvePlaneReach, scorePlane, stampPlanes } from '../exposure/planes';
+import { resolveRoutineReach } from '../exposure/routines';
+import { LINT_RULES, LINT_RULES_BY_ID, lintDefinition } from '../lint';
+import { proveFindings } from '../perf/explain';
+import { introspectRoleGraph, introspectSchemaAcls } from '../pg/acl';
+import { resolveExposure, resolvePlanes, resolveReach } from '../pg/exposure';
+import { introspectFunctions } from '../pg/functions';
+import { introspectIndexes, introspectViews } from '../pg/indexes';
+import { asExecutor, introspectTables } from '../pg/introspect';
+import { introspectObjectAcls } from '../pg/objects';
+import { classifyPaths } from '../pg/paths';
+import { lookupVolatility } from '../pg/proc';
+import { introspectReachInputs } from '../pg/reach-inputs';
+import { listAuditableRoles, resolveRoles } from '../pg/roles';
+import { introspectStats } from '../pg/stats';
+import { dimensionOf, RULES_BY_CODE, subjectOf } from '../rules/registry';
+import { computeScore } from '../score/score';
+import { computeScorecards, RESERVED_SCORECARDS } from '../score/scorecards';
+import { summarize } from '../types';
+import { version as PKG_VERSION } from '../version';
+export async function audit(client, options = {}) {
+    const exec = asExecutor(client);
+    const config = options.config ?? {};
+    const resolved = resolveRules(config);
+    const extensions = options.extensions ?? config.extensions;
+    // Function definitions are read by two independent features (the convention
+    // linter and the call graph); introspect them at most once.
+    let functionsCache;
+    const getFunctions = async () => {
+        if (!functionsCache) {
+            functionsCache = await introspectFunctions(exec, {
+                schemas: options.schemas ?? config.schemas,
+                excludeSchemas: options.excludeSchemas ?? config.excludeSchemas,
+                extensions
+            });
+        }
+        return functionsCache;
+    };
+    const statsEnabled = options.stats ?? config.perf?.stats?.enabled ?? false;
+    const explainEnabled = options.explain ?? config.perf?.explain?.enabled ?? false;
+    // Both tiers are refinements of the perf dimension: asking for either turns
+    // it on, but neither is reachable without opting into perf in the first place.
+    const perfEnabled = (options.perf ?? config.perf?.enabled ?? false) || statsEnabled || explainEnabled;
+    const skipAst = options.skipAstChecks || allAstRulesDisabled(resolved, { perf: perfEnabled });
+    // Resolve role set.
+    const allRoles = await listAuditableRoles(exec);
+    const resolution = resolveRoles(allRoles, options.includeRoles ?? config.roles, options.excludeRoles ?? config.excludeRoles);
+    const exposureConfig = options.exposure ?? config.exposure;
+    const exposure = await resolveExposure(exec, exposureConfig);
+    const exposedSchemas = new Set(exposure.schemas);
+    const planes = await resolvePlanes(exec, exposureConfig, exposure);
+    // Relation-level precision within those schemas: what the generated API can
+    // actually name. Schema membership is the coarse answer; this is the fine
+    // one, and only an adapter that can prove it contributes.
+    const apiReach = exposure.known
+        ? await resolveReach(exec, exposureConfig, {
+            schemas: exposure.schemas,
+            excludeSchemas: options.excludeSchemas ?? config.excludeSchemas
+        })
+        : undefined;
+    const unaddressable = new Set((apiReach?.unreachable ?? []).map((r) => `${r.schema}.${r.table}`));
+    const snapshot = await introspectTables(exec, {
+        schemas: options.schemas ?? config.schemas,
+        excludeSchemas: options.excludeSchemas ?? config.excludeSchemas,
+        roles: resolution.roles,
+        extensions
+    });
+    const isExposed = (schema, table) => {
+        if (!exposedSchemas.has(schema))
+            return false;
+        return table === undefined || !unaddressable.has(`${schema}.${table}`);
+    };
+    const exposedTables = exposure.known
+        ? snapshot.filter((t) => isExposed(t.schema, t.name)).length
+        : snapshot.length;
+    // Effective-access inputs for the lattice rules: the INHERIT-following
+    // role graph and the schema USAGE ACLs. Both are single cheap queries.
+    const roleGraph = await introspectRoleGraph(exec);
+    const schemaAcls = await introspectSchemaAcls(exec, {
+        schemas: options.schemas ?? config.schemas,
+        excludeSchemas: options.excludeSchemas ?? config.excludeSchemas
+    });
+    const schemaAclsByName = new Map(schemaAcls.map((a) => [a.schema, a]));
+    // Which schemas the audit actually looked at — the same include/exclude
+    // filters the table snapshot used. A view body naming anything outside this
+    // set reaches past the audit rather than reaching nothing (L14).
+    const auditedSchemas = new Set(schemaAcls.map((a) => a.schema));
+    // Roles requests arrive as, and the relations some policy predicate names.
+    // L6 needs both: the first is whose grants it is talking about, the second
+    // is the veto that stops it recommending a revoke of a load-bearing grant.
+    const apiRoles = exposure.roles ?? [];
+    const policyReferenced = policyReferencedRelations(snapshot);
+    let findings = [];
+    // --- Performance dimension (opt-in): index hygiene ---
+    const indexSnapshot = perfEnabled
+        ? await introspectIndexes(exec, {
+            schemas: options.schemas ?? config.schemas,
+            excludeSchemas: options.excludeSchemas ?? config.excludeSchemas,
+            extensions
+        })
+        : [];
+    const indexesByTable = new Map(indexSnapshot.map((t) => [`${t.schema}.${t.name}`, t]));
+    // Views are read for three independent reasons: their bodies refute "nothing
+    // queries this column" for the perf paths, their owners carry the L8 reach
+    // edge, and their ACLs keep L4 from calling schema USAGE dead when a view is
+    // the only thing in the schema the role can reach. One introspection serves
+    // all three.
+    const definerViewRoles = withExposedRoles(resolved.rules.get('L8')?.options, exposure)?.roles ?? [];
+    const viewWriteRoles = withExposedRoles(resolved.rules.get('L9')?.options, exposure)?.roles ?? [];
+    const ruleBypassRoles = withExposedRoles(resolved.rules.get('L10')?.options, exposure)?.roles ?? [];
+    const uncheckedWriteRoles = withExposedRoles(resolved.rules.get('L18')?.options, exposure)?.roles ?? [];
+    const matviewRoles = withExposedRoles(resolved.rules.get('L11')?.options, exposure)?.roles ?? [];
+    const leakyViewRoles = withExposedRoles(resolved.rules.get('L12')?.options, exposure)?.roles ?? [];
+    const unauditedReachRoles = withExposedRoles(resolved.rules.get('L14')?.options, exposure)?.roles ?? [];
+    const unreadableViewRoles = withExposedRoles(resolved.rules.get('L15')?.options, exposure)?.roles ?? [];
+    // Function bodies: L19 is the reach a definer function's body confers, L20
+    // the write an INSTEAD OF trigger's definer function performs, and L15
+    // reports the bodies neither could read.
+    const definerFunctionRoles = withExposedRoles(resolved.rules.get('L19')?.options, exposure)?.roles ?? [];
+    const triggerWriteRoles = withExposedRoles(resolved.rules.get('L20')?.options, exposure)?.roles ?? [];
+    // Sequences and foreign tables: one introspection, two rules, and no reason
+    // to run it when neither is configured with a role list.
+    const sequenceRoles = withExposedRoles(resolved.rules.get('L16')?.options, exposure)?.roles ?? [];
+    const foreignTableRoles = withExposedRoles(resolved.rules.get('L17')?.options, exposure)?.roles ?? [];
+    // L21 (`granted − reachable`) runs on the untrusted roles by default — its
+    // question is precisely "which of anonymous's grants are load-bearing?" — so
+    // it reads its role list from `exposure.anonRoles` unless the config overrides
+    // it. It reads function/view bodies, so it is gated on `skipAst` like the
+    // other body rules.
+    const revocableRoles = withExposedRoles({ rolesFrom: 'anon', ...resolved.rules.get('L21')?.options }, exposure)?.roles ?? [];
+    const revocableEnabled = !skipAst && revocableRoles.length > 0 && resolved.rules.get('L21')?.enabled !== false;
+    // L8 and L14 are two answers from one body pass: the base relations that
+    // were graded, and the ones that could not be because they are out of scope.
+    const viewBodiesEnabled = !skipAst
+        && ((definerViewRoles.length > 0 && resolved.rules.get('L8')?.enabled !== false)
+            || (unauditedReachRoles.length > 0 && resolved.rules.get('L14')?.enabled !== false)
+            || (unreadableViewRoles.length > 0 && resolved.rules.get('L15')?.enabled !== false));
+    const functionBodiesEnabled = !skipAst
+        && ((definerFunctionRoles.length > 0 && resolved.rules.get('L19')?.enabled !== false)
+            || (triggerWriteRoles.length > 0 && resolved.rules.get('L20')?.enabled !== false)
+            || (unreadableViewRoles.length > 0 && resolved.rules.get('L15')?.enabled !== false));
+    const viewExposureEnabled = !skipAst
+        && ((matviewRoles.length > 0 && resolved.rules.get('L11')?.enabled !== false)
+            || (leakyViewRoles.length > 0 && resolved.rules.get('L12')?.enabled !== false));
+    const viewWritesEnabled = !skipAst
+        && ((viewWriteRoles.length > 0 && resolved.rules.get('L9')?.enabled !== false)
+            || (ruleBypassRoles.length > 0 && resolved.rules.get('L10')?.enabled !== false)
+            || (uncheckedWriteRoles.length > 0 && resolved.rules.get('L18')?.enabled !== false));
+    const needsViews = (perfEnabled && config.perf?.paths?.infer !== false)
+        || resolved.rules.get('L4')?.enabled !== false
+        || viewBodiesEnabled
+        || viewWritesEnabled
+        || viewExposureEnabled
+        || functionBodiesEnabled
+        || revocableEnabled;
+    const viewSnapshot = needsViews
+        ? await introspectViews(exec, {
+            schemas: options.schemas ?? config.schemas,
+            excludeSchemas: options.excludeSchemas ?? config.excludeSchemas
+        })
+        : [];
+    // Evidence about which foreign keys anything reads. Reported alongside the
+    // findings; by default it changes neither, because no signal available on an
+    // empty database proves a path is unreachable.
+    const onWriteOncePointer = config.perf?.paths?.onWriteOncePointer ?? 'report';
+    const paths = perfEnabled && config.perf?.paths?.infer !== false
+        ? classifyPaths(indexSnapshot, snapshot, viewSnapshot.map((v) => v.definition), {
+            minPointers: config.perf?.paths?.minPointers,
+            hiddenBackwardRelations: new Set(apiReach?.hiddenBackwardRelations ?? [])
+        })
+        : new Map();
+    for (const table of snapshot) {
+        // --- RLS flags (structural) ---
+        const a1 = checkRlsEnabledNoPolicies(table);
+        if (a1)
+            findings.push(a1);
+        const a2 = checkGrantsWithoutRls(table);
+        if (a2)
+            findings.push(a2);
+        const a3 = checkRlsNotForced(table);
+        if (a3)
+            findings.push(a3);
+        // --- Grant-vs-policy coverage ---
+        findings.push(...checkCoverageGaps(table));
+        findings.push(...checkUpdateWithCheckCoverage(table));
+        // --- Role-trust (options-driven; per-table overrides can retune roles) ---
+        const tableRules = rulesForTable(resolved, table.schema, table.name);
+        findings.push(...checkUntrustedRoleWrites(table, withExposedRoles(tableRules.get('R1')?.options, exposure)));
+        findings.push(...checkUntrustedRolePolicies(table, withExposedRoles(tableRules.get('R2')?.options, exposure)));
+        findings.push(...checkPublicGrants(table));
+        // --- Grant/RLS/policy lattice (effective access: PUBLIC + inheritance) ---
+        findings.push(...checkIndirectCoverageGaps(table, roleGraph));
+        findings.push(...checkDeadPolicies(table, roleGraph));
+        findings.push(...checkUnreachableGrants(table, schemaAclsByName, roleGraph));
+        findings.push(...checkUntrustedIndirectAccess(table, roleGraph, withExposedRoles(tableRules.get('L5')?.options, exposure)));
+        if (unaddressable.size > 0 && apiRoles.length > 0) {
+            findings.push(...checkUnaddressableGrant(table, roleGraph, unaddressable, {
+                roles: apiRoles,
+                policyReferenced
+            }));
+        }
+        findings.push(...checkSetRoleEscalation(table, roleGraph, withExposedRoles(tableRules.get('L7')?.options, exposure)));
+        findings.push(...checkUntrustedColumnGrants(table, roleGraph, withExposedRoles(tableRules.get('L13')?.options, exposure)));
+        // --- AST-level anti-patterns (and, with perf on, policy-aware index rules) ---
+        if (!skipAst) {
+            findings.push(...(await auditTableAst(exec, table, perfEnabled ? indexesByTable.get(`${table.schema}.${table.name}`) : undefined)));
+        }
+    }
+    findings.push(...checkDeadSchemaUsage(schemaAcls, snapshot, roleGraph, viewSnapshot));
+    // L16/L17 grade relations that are not tables, so they sit outside the
+    // per-table loop entirely.
+    const objectAclsEnabled = (sequenceRoles.length > 0 && resolved.rules.get('L16')?.enabled !== false)
+        || (foreignTableRoles.length > 0 && resolved.rules.get('L17')?.enabled !== false);
+    if (objectAclsEnabled) {
+        const objects = await introspectObjectAcls(exec, {
+            schemas: options.schemas ?? config.schemas,
+            excludeSchemas: options.excludeSchemas ?? config.excludeSchemas
+        });
+        if (sequenceRoles.length > 0 && resolved.rules.get('L16')?.enabled !== false) {
+            findings.push(...checkUntrustedSequenceGrants(objects, roleGraph, { roles: sequenceRoles }));
+        }
+        if (foreignTableRoles.length > 0 && resolved.rules.get('L17')?.enabled !== false) {
+            findings.push(...checkUntrustedForeignTableGrants(objects, roleGraph, { roles: foreignTableRoles }));
+        }
+    }
+    // L8 is per-view, not per-table: a view body names its own base relations.
+    if (viewBodiesEnabled) {
+        const viewBodies = await analyzeViewBodies(viewSnapshot, snapshot, auditedSchemas);
+        if (definerViewRoles.length > 0 && resolved.rules.get('L8')?.enabled !== false) {
+            findings.push(...checkDefinerViewBypass(viewBodies.views, snapshot, roleGraph, { roles: definerViewRoles }));
+        }
+        if (unauditedReachRoles.length > 0 && resolved.rules.get('L14')?.enabled !== false) {
+            findings.push(...checkUnauditedViewReach(viewBodies.views, roleGraph, { roles: unauditedReachRoles }));
+        }
+        if (unreadableViewRoles.length > 0 && resolved.rules.get('L15')?.enabled !== false) {
+            findings.push(...checkUnreadableViewReach(viewBodies.views, roleGraph, { roles: unreadableViewRoles }));
+        }
+    }
+    // L9/L10/L18 are the write half of the same question, and share one analysis.
+    if (viewWritesEnabled) {
+        const writes = await analyzeViewWrites(viewSnapshot, snapshot);
+        if (viewWriteRoles.length > 0 && resolved.rules.get('L9')?.enabled !== false) {
+            findings.push(...checkDefinerViewWrite(writes.autoUpdatable, snapshot, roleGraph, { roles: viewWriteRoles }));
+        }
+        if (ruleBypassRoles.length > 0 && resolved.rules.get('L10')?.enabled !== false) {
+            findings.push(...checkViewRuleBypass(writes.ruleDriven, snapshot, roleGraph, { roles: ruleBypassRoles }));
+        }
+        if (uncheckedWriteRoles.length > 0 && resolved.rules.get('L18')?.enabled !== false) {
+            findings.push(...checkUncheckedViewWrite(writes.unchecked, snapshot, roleGraph, {
+                roles: uncheckedWriteRoles
+            }));
+        }
+    }
+    // L19/L20 are the function half of "SQL bodies confer privilege": what a
+    // definer function's body reaches, and where an INSTEAD OF trigger's write
+    // actually lands. One body pass serves both, plus L15's coverage report.
+    if (functionBodiesEnabled) {
+        const bodies = await analyzeFunctionBodies(await getFunctions(), viewSnapshot, snapshot, auditedSchemas);
+        if (definerFunctionRoles.length > 0 && resolved.rules.get('L19')?.enabled !== false) {
+            findings.push(...checkDefinerFunctionReach(bodies.functions, snapshot, roleGraph, schemaAclsByName, {
+                roles: definerFunctionRoles
+            }));
+        }
+        if (triggerWriteRoles.length > 0 && resolved.rules.get('L20')?.enabled !== false) {
+            findings.push(...checkInsteadOfTriggerWrite(bodies.triggers, snapshot, roleGraph, {
+                roles: triggerWriteRoles
+            }));
+        }
+        if (unreadableViewRoles.length > 0 && resolved.rules.get('L15')?.enabled !== false) {
+            findings.push(...checkUnreadableFunctionReach(bodies.functions, roleGraph, schemaAclsByName, {
+                roles: unreadableViewRoles
+            }));
+        }
+    }
+    // L11/L12 are the other two things a readable view does: store rows, and
+    // filter them without being a boundary. One body pass serves both.
+    if (viewExposureEnabled) {
+        const exposureViews = await analyzeViewExposure(viewSnapshot, snapshot);
+        if (matviewRoles.length > 0 && resolved.rules.get('L11')?.enabled !== false) {
+            findings.push(...checkMatviewSnapshot(exposureViews.matviews, snapshot, roleGraph, { roles: matviewRoles }));
+        }
+        if (leakyViewRoles.length > 0 && resolved.rules.get('L12')?.enabled !== false) {
+            findings.push(...checkLeakyFilterView(exposureViews.leaky, snapshot, roleGraph, { roles: leakyViewRoles }));
+        }
+    }
+    // L21: the EXECUTE grants each untrusted role holds that no reachable path
+    // exercises. Its own reachability closure — policy predicates, trigger
+    // bodies, write-time expressions and views — needs the trigger/expression
+    // inputs no other rule reads. The revocable recommendations enter the finding
+    // stream; the retained-and-suppressed proof lists ride on the report.
+    let revocableGrants;
+    if (revocableEnabled) {
+        const reachInputs = await introspectReachInputs(exec, {
+            schemas: options.schemas ?? config.schemas,
+            excludeSchemas: options.excludeSchemas ?? config.excludeSchemas
+        });
+        revocableGrants = await analyzeRevocableGrants({
+            roles: revocableRoles,
+            functions: await getFunctions(),
+            tables: snapshot,
+            views: viewSnapshot,
+            graph: roleGraph,
+            schemaAcls: schemaAclsByName,
+            reachInputs,
+            exposedSchemas,
+            exposureKnown: exposure.known,
+            unaddressable
+        });
+        findings.push(...revocableGrantFindings(revocableGrants));
+    }
+    const statsSnapshot = statsEnabled
+        ? await introspectStats(exec, {
+            schemas: options.schemas ?? config.schemas,
+            excludeSchemas: options.excludeSchemas ?? config.excludeSchemas,
+            extensions,
+            statementLimit: config.perf?.stats?.topStatements
+        })
+        : null;
+    if (perfEnabled) {
+        for (const table of indexSnapshot) {
+            findings.push(...checkUnindexedForeignKeys(table, paths, onWriteOncePointer));
+            findings.push(...checkRedundantIndexes(table));
+            findings.push(...checkUnindexedSearchColumns(table));
+            findings.push(...checkUnindexedSortColumns(table));
+            const x6 = checkMissingPrimaryKey(table);
+            if (x6)
+                findings.push(x6);
+        }
+    }
+    if (statsSnapshot) {
+        findings.push(...checkStats(statsSnapshot, statsThresholds(config)));
+    }
+    // --- Convention linter (C*): source-level rules over function definitions ---
+    const enabledLintRules = LINT_RULES.filter((r) => resolved.rules.get(r.code)?.enabled !== false);
+    if (enabledLintRules.length > 0) {
+        const lintRuleIds = enabledLintRules.map((r) => r.id);
+        for (const fn of await getFunctions()) {
+            if (!fn.definition)
+                continue;
+            const subject = `${fn.schema}.${fn.name}(${fn.args})`;
+            const { problems, suppressed } = await lintDefinition(fn.definition, fn.language, subject, { rules: lintRuleIds });
+            for (const p of problems)
+                findings.push(lintFinding(fn, subject, p));
+            for (const s of suppressed)
+                findings.push(lintFinding(fn, subject, s, true));
+        }
+    }
+    findings = applyRulesToFindings(resolved, findings);
+    // Routine findings are graded by whether an untrusted role can *call the
+    // function*, not by whether its schema is on the API surface — see
+    // `RuleMeta.subject`. Resolved only when such a finding exists, so an audit
+    // with the routine rules off still costs one query less.
+    const routineRoles = [...new Set([...apiRoles, ...(exposure.anonRoles ?? [])])];
+    let routineReach;
+    const isRoutineExposed = async (schema, name) => {
+        if (!routineReach) {
+            routineReach = resolveRoutineReach(await getFunctions(), {
+                roles: routineRoles,
+                graph: roleGraph,
+                schemaAcls: schemaAclsByName,
+                exposedSchemas
+            });
+        }
+        return routineReach.has(`${schema}.${name}`);
+    };
+    // Stamp direction (from the registry) and exposure on every finding.
+    const publicRead = config.public?.read ?? [];
+    const perfIgnore = config.perf?.ignore ?? [];
+    for (const f of findings) {
+        const meta = RULES_BY_CODE.get(f.code);
+        if (meta && f.direction === undefined)
+            f.direction = meta.direction;
+        if (meta && f.dimension === undefined)
+            f.dimension = dimensionOf(meta);
+        if (exposure.known && f.schema) {
+            // L14 names a relation outside the audited schemas by construction, so
+            // grading it by its own schema would file every finding as an internal
+            // advisory. What is exposed is the view an API role reads it through.
+            const viewRef = f.code === 'L14'
+                ? f.context?.view
+                : undefined;
+            // A routine finding names a function somewhere in the finding — in
+            // `context.function` for the reach rules, in `schema`/`table` for the
+            // convention linter, which files a function under the fields a relation
+            // finding uses.
+            const routineRef = meta && subjectOf(meta) === 'routine'
+                ? f.context?.function?.replace(/\(.*$/, '')
+                    ?? (f.table ? `${f.schema}.${f.table}` : undefined)
+                : undefined;
+            if (routineRef) {
+                const dot = routineRef.lastIndexOf('.');
+                f.exposed = await isRoutineExposed(routineRef.slice(0, dot), routineRef.slice(dot + 1));
+            }
+            else if (viewRef) {
+                f.exposed = isExposed(viewRef.slice(0, viewRef.lastIndexOf('.')), viewRef.slice(viewRef.lastIndexOf('.') + 1));
+            }
+            else {
+                f.exposed = isExposed(f.schema, f.table);
+            }
+        }
+        // A key that looks like a write-once provisioning pointer, where the
+        // reviewer has chosen to read the finding rather than gate on it. Applied
+        // here because severities are restamped from the rule registry above.
+        if (onWriteOncePointer === 'demote' && f.code === 'X1'
+            && f.context?.pathAssessment === 'write-once-shaped') {
+            f.acknowledged = true;
+            f.severity = 'info';
+            f.message += ' — write-once-shaped (perf.paths.onWriteOncePointer)';
+        }
+        // Declared-intentional perf debt: cold tables, tiny lookups, anything the
+        // planner will seq-scan regardless. Reported, but off the perf score.
+        if (f.dimension === 'perf' && f.schema && f.table
+            && perfIgnore.some((p) => matchTablePattern(p, `${f.schema}.${f.table}`))) {
+            f.acknowledged = true;
+            f.severity = 'info';
+            f.message += ' — acknowledged (perf.ignore)';
+            f.hint = 'This table is declared in `perf.ignore`, so the finding is treated as intentional and does not affect the perf score.';
+        }
+        // Declared-public reads: an open SELECT on a table listed in
+        // `public.read` is intent, not a finding — acknowledge it (info,
+        // excluded from the score). Undeclared open reads stay scored.
+        if (f.code === 'A8' && f.schema && f.table
+            && publicRead.some((p) => matchTablePattern(p, `${f.schema}.${f.table}`))) {
+            f.acknowledged = true;
+            f.severity = 'info';
+            f.message += ' — declared public read (public.read)';
+            f.hint = 'This table is declared in `public.read`, so the open read is treated as intentional and does not affect the score.';
+        }
+    }
+    // W1: no exposure surface — the whole database is assumed reachable.
+    if (!exposure.known && resolved.rules.get('W1')?.enabled !== false) {
+        findings.push({
+            code: 'W1',
+            severity: resolved.rules.get('W1')?.severity ?? 'medium',
+            category: 'meta',
+            direction: 'neutral',
+            message: 'No exposure surface configured — the audit assumes the entire database is reachable and the score is capped',
+            hint: 'Declare `exposure.schemas` (or use `exposure.resolver: "constructive"` on a Constructive database) so the score reflects what the exposed APIs can actually reach.'
+        });
+    }
+    // Planner proof runs last: it reads the findings the rules produced and
+    // acknowledges the ones the planner disagrees with, before scoring.
+    let explainReport;
+    if (explainEnabled) {
+        explainReport = await proveFindings(exec, findings.filter((f) => f.dimension === 'perf' && !f.acknowledged), indexesByTable, { minRows: config.perf?.explain?.minRows });
+    }
+    findings.sort(compareFindings);
+    const exposureReport = {
+        known: exposure.known,
+        source: exposure.source,
+        plane: planes[0].name,
+        schemas: exposure.schemas,
+        ...(exposure.roles ? { roles: exposure.roles } : {}),
+        ...(exposure.anonRoles && exposure.anonRoles.length > 0
+            ? { anonRoles: exposure.anonRoles }
+            : {}),
+        exposedTables,
+        totalTables: snapshot.length,
+        ...(apiReach && apiReach.unreachable.length > 0
+            ? { unaddressable: apiReach.unreachable.filter((r) => exposedSchemas.has(r.schema)) }
+            : {})
+    };
+    const securityFindings = findings.filter((f) => f.dimension !== 'perf');
+    const perfFindings = findings.filter((f) => f.dimension === 'perf');
+    const report = {
+        version: PKG_VERSION,
+        generatedAt: new Date().toISOString(),
+        provenance: {
+            version: PKG_VERSION,
+            fingerprint: configFingerprint(config, PKG_VERSION),
+            sealed: options.sealed === true,
+            ...(options.preset ? { preset: options.preset } : {})
+        },
+        summary: summarize(findings),
+        findings,
+        score: computeScore(securityFindings, config.scoring, {
+            exposedTables,
+            exposureKnown: exposure.known
+        }),
+        exposure: exposureReport
+    };
+    // Access planes. The primary plane's score is `report.score` — computed
+    // above, against the exposure surface — so declaring planes can never move
+    // the headline number; the secondaries answer what the headline cannot.
+    const reaches = resolvePlaneReach(planes, snapshot, roleGraph, apiReach);
+    stampPlanes(findings, reaches);
+    if (reaches.length > 1) {
+        report.planes = reaches.map((reach) => {
+            if (reach.skipped) {
+                return {
+                    ...scorePlane(reach, [], config.scoring, exposure.known),
+                    skipped: reach.skipped
+                };
+            }
+            if (reach.plane.primary) {
+                return {
+                    ...scorePlane(reach, securityFindings, config.scoring, exposure.known),
+                    exposedTables,
+                    score: report.score,
+                    summary: summarize(securityFindings.filter((f) => f.exposed !== false))
+                };
+            }
+            return scorePlane(reach, securityFindings, config.scoring, exposure.known);
+        });
+    }
+    // Per-role exposure: computed for the configured untrusted roles (L5/R1
+    // options), so the report answers "what can anonymous access?" directly
+    // even when no finding fires.
+    const untrustedRoles = [...new Set([
+            ...(withExposedRoles(resolved.rules.get('L5')?.options, exposure)?.roles ?? []),
+            ...(withExposedRoles(resolved.rules.get('R1')?.options, exposure)?.roles ?? [])
+        ])].sort();
+    if (untrustedRoles.length > 0) {
+        const roleAccess = {
+            roles: computeRoleAccess(snapshot, roleGraph, untrustedRoles)
+        };
+        report.roleAccess = roleAccess;
+    }
+    if (revocableGrants)
+        report.revocableGrants = revocableGrants;
+    if (perfEnabled) {
+        // `S*` findings are scored by default — opting into `--stats` is the
+        // opt-in — but can be demoted to advisories for a deterministic grade.
+        const includeStats = config.perf?.scoring?.includeStats ?? true;
+        const scorable = includeStats
+            ? perfFindings
+            : perfFindings.filter((f) => !f.code.startsWith('S'));
+        const perf = {
+            findings: perfFindings,
+            summary: summarize(perfFindings),
+            score: computeScore(scorable, config.perf?.scoring, {
+                exposedTables,
+                exposureKnown: exposure.known
+            })
+        };
+        if (paths.size > 0) {
+            const all = [...paths.values()];
+            const shaped = all.filter((p) => p.assessment === 'write-once-shaped');
+            const declaredHidden = all.filter((p) => p.signals.some((s) => s.name === 'behavior-hidden')).length;
+            perf.paths = {
+                total: paths.size,
+                read: all.filter((p) => p.assessment === 'read').length,
+                writeOnceShaped: shaped.length,
+                tables: new Set(shaped.map((p) => `${p.schema}.${p.table}`)).size,
+                onWriteOncePointer,
+                ...(declaredHidden > 0 ? { declaredHidden } : {})
+            };
+        }
+        if (statsSnapshot) {
+            const stats = {
+                source: 'live',
+                tables: statsSnapshot.tables.length,
+                statsReset: statsSnapshot.statsReset,
+                scored: includeStats
+            };
+            if (statsSnapshot.statementsUnavailable) {
+                stats.notes = [statsSnapshot.statementsUnavailable];
+            }
+            perf.stats = stats;
+        }
+        if (explainReport)
+            perf.explain = explainReport;
+        report.perf = perf;
+    }
+    // Scorecards last: they are named questions asked of the finished finding
+    // set, so every stamp a scorecard can select on (exposure, planes, perf
+    // dimension) is already on the findings by now.
+    report.scorecards = computeScorecards(findings, report.score, { ...RESERVED_SCORECARDS, ...(config.scorecards ?? {}) }, { exposedTables, totalTables: snapshot.length, exposureKnown: exposure.known });
+    if (options.callGraph) {
+        const functions = await getFunctions();
+        report.callGraph = await buildCallGraph({
+            functions,
+            tables: snapshot,
+            exposedSchemas: exposure.known ? exposure.schemas : undefined,
+            apiRoles: exposure.roles && exposure.roles.length > 0
+                ? exposure.roles
+                : ['anonymous', 'authenticated']
+        });
+    }
+    return report;
+}
+/**
+ * Materializes `rolesFrom: 'exposure'` into concrete role names. An adapter
+ * resolves the API-edge roles from the catalog (a Constructive API's
+ * `anon_role`, PostgREST's `pgrst.db_anon_role`, the role a graphile
+ * authenticator can `SET ROLE` to); those roles are exactly the untrusted
+ * ones, and their names are per-deployment, so a preset names the *source*
+ * instead of the roles. Explicit `roles` still apply — the two union.
+ */
+function withExposedRoles(options, exposure) {
+    if (!options?.rolesFrom)
+        return options;
+    const resolved = options.rolesFrom === 'anon' ? exposure.anonRoles : exposure.roles;
+    const roles = [...new Set([...(options.roles ?? []), ...(resolved ?? [])])].sort();
+    return { ...options, roles };
+}
+/** Stats floors, config over defaults. */
+function statsThresholds(config) {
+    const stats = config.perf?.stats ?? {};
+    return {
+        minRows: stats.minRows ?? DEFAULT_STATS_THRESHOLDS.minRows,
+        seqScanRatio: stats.seqScanRatio ?? DEFAULT_STATS_THRESHOLDS.seqScanRatio,
+        minIndexBytes: stats.minIndexBytes ?? DEFAULT_STATS_THRESHOLDS.minIndexBytes,
+        deadTupleRatio: stats.deadTupleRatio ?? DEFAULT_STATS_THRESHOLDS.deadTupleRatio,
+        minTimeShare: stats.minTimeShare ?? DEFAULT_STATS_THRESHOLDS.minTimeShare,
+        topStatements: stats.topStatements ?? DEFAULT_STATS_THRESHOLDS.topStatements
+    };
+}
+async function auditTableAst(exec, table, indexes) {
+    if (table.policies.length === 0)
+        return [];
+    // Collect all function names referenced across this table's policies so we
+    // can resolve volatility in one round-trip.
+    const funcNames = [];
+    const parsed = [];
+    for (const p of table.policies) {
+        const using = await parseOrNull(p.using, `${table.schema}.${table.name}.${p.name} USING`);
+        const withCheck = await parseOrNull(p.withCheck, `${table.schema}.${table.name}.${p.name} WITH CHECK`);
+        parsed.push({ policy: p, using, withCheck });
+        if (using)
+            funcNames.push(...collectFunctionNames(using));
+        if (withCheck)
+            funcNames.push(...collectFunctionNames(withCheck));
+    }
+    let volatility;
+    try {
+        volatility = await lookupVolatility(exec, funcNames);
+    }
+    catch {
+        volatility = new Map();
+    }
+    const findings = [];
+    const predicateColumns = new Map();
+    for (const { policy, using, withCheck } of parsed) {
+        const trivial = checkTriviallyPermissive(table, policy, using, withCheck);
+        if (trivial)
+            findings.push(trivial);
+        if (using) {
+            findings.push(...checkVolatileFunctions(table, using, volatility, policy.name));
+            findings.push(...checkSessionUserGating(table, using, policy.name));
+        }
+        if (withCheck) {
+            findings.push(...checkVolatileFunctions(table, withCheck, volatility, policy.name));
+            findings.push(...checkSessionUserGating(table, withCheck, policy.name));
+        }
+        if (!indexes)
+            continue;
+        // --- Policy-aware perf rules (X2/X3/X4/X9) ---
+        const cols = [];
+        if (using) {
+            cols.push(...collectPredicateColumns(using, 'USING', table.name));
+            findings.push(...checkNonLeakproofPolicyFunctions(table, using, volatility, policy.name));
+            findings.push(...checkUnhoistedPolicyFunctions(table, using, volatility, policy.name, 'USING'));
+        }
+        if (withCheck) {
+            cols.push(...collectPredicateColumns(withCheck, 'WITH CHECK', table.name));
+            findings.push(...checkNonLeakproofPolicyFunctions(table, withCheck, volatility, policy.name));
+            findings.push(...checkUnhoistedPolicyFunctions(table, withCheck, volatility, policy.name, 'WITH CHECK'));
+        }
+        if (cols.length > 0)
+            predicateColumns.set(policy.name, cols);
+    }
+    if (indexes && predicateColumns.size > 0) {
+        findings.push(...checkUnindexedPolicyColumns(table, indexes, predicateColumns));
+        findings.push(...checkPolicyColumnCasts(table, indexes, predicateColumns));
+    }
+    return dedupe(findings);
+}
+/**
+ * Relations named by any RLS policy predicate in the snapshot.
+ *
+ * Whole-word token matching over the predicate text, matching both the bare
+ * and the schema-qualified name. Deliberately over-eager: a spurious match
+ * costs one unreported L6, a missed one costs a recommendation to revoke a
+ * grant that authorization depends on.
+ */
+function policyReferencedRelations(tables) {
+    const tokens = new Set();
+    for (const table of tables) {
+        for (const policy of table.policies) {
+            for (const clause of [policy.using, policy.withCheck]) {
+                if (!clause)
+                    continue;
+                for (const match of clause.matchAll(/[A-Za-z_][A-Za-z0-9_$]*(?:\.[A-Za-z_][A-Za-z0-9_$]*)?/g)) {
+                    tokens.add(match[0].toLowerCase());
+                }
+            }
+        }
+    }
+    const referenced = new Set();
+    for (const table of tables) {
+        const key = `${table.schema}.${table.name}`;
+        if (tokens.has(key.toLowerCase()) || tokens.has(table.name.toLowerCase())) {
+            referenced.add(key);
+        }
+    }
+    return referenced;
+}
+/**
+ * Map a source-level lint problem onto a `Finding`. The function's name rides
+ * in the `table` slot so overrides, exposure and sorting key on it the same
+ * way they do for table findings. Suppressed problems are emitted as
+ * acknowledged findings — visible as accepted risk, off the score — carrying
+ * their waiver reason and scope in `context`.
+ */
+function lintFinding(fn, subject, problem, suppressed = false) {
+    const meta = LINT_RULES_BY_ID.get(problem.ruleId);
+    return {
+        code: meta.code,
+        severity: RULES_BY_CODE.get(meta.code).defaultSeverity,
+        category: 'convention',
+        schema: fn.schema,
+        table: fn.name,
+        message: `${problem.message} in ${subject}`,
+        ...(problem.hint ? { hint: problem.hint } : {}),
+        ...(suppressed ? { acknowledged: true } : {}),
+        context: {
+            ...problem.context,
+            function: subject,
+            line: problem.line,
+            ...(suppressed
+                ? {
+                    suppressed: true,
+                    reason: problem.reason,
+                    suppressionScope: problem.scope
+                }
+                : {})
+        }
+    };
+}
+function compareFindings(a, b) {
+    const order = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
+    if (order[a.severity] !== order[b.severity])
+        return order[a.severity] - order[b.severity];
+    if (a.schema !== b.schema)
+        return (a.schema ?? '').localeCompare(b.schema ?? '');
+    if (a.table !== b.table)
+        return (a.table ?? '').localeCompare(b.table ?? '');
+    return a.code.localeCompare(b.code);
+}
+function dedupe(findings) {
+    const seen = new Set();
+    const out = [];
+    for (const f of findings) {
+        const key = [f.code, f.schema, f.table, f.policy, f.message].join('::');
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(f);
+    }
+    return out;
+}