@safegres/test 0.0.2 → 1.30.7

package/exposure/reach.d.ts

@@ -0,0 +1,78 @@
+/**
+ * API reach: which relations a generated API can actually address.
+ *
+ * A plane made of schemas answers "is this relation in the API's schemas?",
+ * which is as much precision as a schema list can carry. It over-counts in a
+ * way that matters: a generated API exposes types and fields, not schemas, and
+ * a schema routinely contains relations the API deliberately does not surface
+ * — join tables, denormalised shadows, machine-only back-pointers.
+ *
+ * Where the author has *declared* that, the declaration is better evidence
+ * than anything else safegres can collect. `reltuples` and `idx_scan` are
+ * measurements, and safegres grades ephemeral CI databases that have never
+ * held data, so both read zero at exactly the moment they would have to mean
+ * something. A behavior tag reads the same in CI as in production.
+ *
+ * Two properties keep this honest:
+ *
+ * - **Only an explicit denial counts.** Presets grant most behaviors by
+ *   default, so the absence of `+list` says nothing whatsoever. Silence is
+ *   never read as denial.
+ * - **Unreachable means unreachable by *every* route.** A relation the API
+ *   cannot address at the root can still be addressed by traversing a relation
+ *   field from one that can, so this is a graph reachability problem and not a
+ *   per-table test. Subtracting a relation that is in fact addressable would
+ *   silently drop real findings out of the score, which is the one failure
+ *   mode worth designing against.
+ */
+import type { BehaviorSnapshot } from '../pg/behaviors';
+/**
+ * Abilities that between them cover every root entry point to a relation.
+ * All four must be denied before the relation is absent from the API root: a
+ * table that cannot be read but can still be inserted into is present.
+ */
+export declare const ROOT_ABILITIES: string[];
+/** The reverse (child-listing) field exists under any one of these. */
+export declare const BACKWARD_ABILITIES: string[];
+/** The forward (parent) field is a single record. */
+export declare const FORWARD_ABILITIES: string[];
+/** One foreign key, as reach cares about it. */
+export interface ReachEdge {
+    /** Referencing relation, `schema.table`. */
+    from: string;
+    /** Referenced relation, `schema.table`. */
+    to: string;
+    constraint: string;
+}
+export interface ReachInputs {
+    /** Every relation in scope, `schema.table`. */
+    relations: string[];
+    edges: ReachEdge[];
+    behaviors: BehaviorSnapshot;
+}
+export interface UnreachableRelation {
+    schema: string;
+    table: string;
+    /** Why it is unreachable, in one human-readable clause. */
+    reason: string;
+}
+export interface ApiReach {
+    /** Relations no field of the generated API can address. */
+    unreachable: UnreachableRelation[];
+    /**
+     * `schema.table.constraint` for every foreign key whose reverse relation is
+     * declared absent. A hidden reverse relation is not the same claim as an
+     * unreachable table — it is one path, not all of them — so it is reported
+     * separately and consumed by the X1 access-path signals.
+     */
+    hiddenBackwardRelations: string[];
+}
+/**
+ * Compute what the generated API can address.
+ *
+ * The traversal starts from every relation the API roots — anything not
+ * explicitly denied all of {@link ROOT_ABILITIES} — and walks relation fields
+ * in both directions. What it never visits is a relation that is denied at the
+ * root *and* has no surviving field pointing at it from anywhere reachable.
+ */
+export declare function computeApiReach(inputs: ReachInputs): ApiReach;

package/exposure/reach.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * API reach: which relations a generated API can actually address.
+ *
+ * A plane made of schemas answers "is this relation in the API's schemas?",
+ * which is as much precision as a schema list can carry. It over-counts in a
+ * way that matters: a generated API exposes types and fields, not schemas, and
+ * a schema routinely contains relations the API deliberately does not surface
+ * — join tables, denormalised shadows, machine-only back-pointers.
+ *
+ * Where the author has *declared* that, the declaration is better evidence
+ * than anything else safegres can collect. `reltuples` and `idx_scan` are
+ * measurements, and safegres grades ephemeral CI databases that have never
+ * held data, so both read zero at exactly the moment they would have to mean
+ * something. A behavior tag reads the same in CI as in production.
+ *
+ * Two properties keep this honest:
+ *
+ * - **Only an explicit denial counts.** Presets grant most behaviors by
+ *   default, so the absence of `+list` says nothing whatsoever. Silence is
+ *   never read as denial.
+ * - **Unreachable means unreachable by *every* route.** A relation the API
+ *   cannot address at the root can still be addressed by traversing a relation
+ *   field from one that can, so this is a graph reachability problem and not a
+ *   per-table test. Subtracting a relation that is in fact addressable would
+ *   silently drop real findings out of the score, which is the one failure
+ *   mode worth designing against.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FORWARD_ABILITIES = exports.BACKWARD_ABILITIES = exports.ROOT_ABILITIES = void 0;
+exports.computeApiReach = computeApiReach;
+const behaviors_1 = require("../pg/behaviors");
+/**
+ * Abilities that between them cover every root entry point to a relation.
+ * All four must be denied before the relation is absent from the API root: a
+ * table that cannot be read but can still be inserted into is present.
+ */
+exports.ROOT_ABILITIES = ['select', 'insert', 'update', 'delete'];
+/** The reverse (child-listing) field exists under any one of these. */
+exports.BACKWARD_ABILITIES = ['list', 'connection', 'single'];
+/** The forward (parent) field is a single record. */
+exports.FORWARD_ABILITIES = ['single'];
+function splitRelation(relation) {
+    const dot = relation.indexOf('.');
+    return { schema: relation.slice(0, dot), table: relation.slice(dot + 1) };
+}
+/**
+ * Compute what the generated API can address.
+ *
+ * The traversal starts from every relation the API roots — anything not
+ * explicitly denied all of {@link ROOT_ABILITIES} — and walks relation fields
+ * in both directions. What it never visits is a relation that is denied at the
+ * root *and* has no surviving field pointing at it from anywhere reachable.
+ */
+function computeApiReach(inputs) {
+    const { relations, edges, behaviors } = inputs;
+    const inScope = new Set(relations);
+    const rooted = relations.filter((relation) => !(0, behaviors_1.deniesAll)(behaviors.tables.get(relation), exports.ROOT_ABILITIES));
+    const hiddenBackwardRelations = [];
+    const adjacency = new Map();
+    const addEdge = (from, to) => {
+        const list = adjacency.get(from);
+        if (list)
+            list.push(to);
+        else
+            adjacency.set(from, [to]);
+    };
+    for (const edge of edges) {
+        const key = `${edge.from}.${edge.constraint}`;
+        const directions = behaviors.constraintDirections.get(key);
+        const backwardHidden = (0, behaviors_1.deniesAll)((0, behaviors_1.directionalBehavior)(directions, 'backward'), exports.BACKWARD_ABILITIES);
+        if (backwardHidden)
+            hiddenBackwardRelations.push(key);
+        // The reverse field lives on the referenced table and reaches the
+        // referencing one.
+        if (!backwardHidden && inScope.has(edge.to))
+            addEdge(edge.to, edge.from);
+        const forwardHidden = (0, behaviors_1.deniesAll)((0, behaviors_1.directionalBehavior)(directions, 'forward'), exports.FORWARD_ABILITIES);
+        if (!forwardHidden && inScope.has(edge.from))
+            addEdge(edge.from, edge.to);
+    }
+    const reached = new Set();
+    const queue = [...rooted];
+    for (const relation of rooted)
+        reached.add(relation);
+    while (queue.length > 0) {
+        const current = queue.pop();
+        for (const next of adjacency.get(current) ?? []) {
+            if (!inScope.has(next) || reached.has(next))
+                continue;
+            reached.add(next);
+            queue.push(next);
+        }
+    }
+    const unreachable = [];
+    for (const relation of relations) {
+        if (reached.has(relation))
+            continue;
+        const inbound = edges.filter((e) => e.to === relation || e.from === relation).length;
+        unreachable.push({
+            ...splitRelation(relation),
+            reason: `a behavior denies ${exports.ROOT_ABILITIES.join(', ')} on the relation`
+                + (inbound > 0
+                    ? ', and every relation field that could reach it is denied too'
+                    : ', and no relation field points at it')
+        });
+    }
+    return { unreachable, hiddenBackwardRelations: hiddenBackwardRelations.sort() };
+}

package/exposure/routines.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Routine exposure: which functions an untrusted role can actually call.
+ *
+ * The exposure surface answers "which relations can the API address?", and
+ * every finding was graded by that question — including the ones that are not
+ * about a relation at all. A definer function lives in a private schema, so by
+ * relation reach it is unexposed; but `anonymous` holds `EXECUTE` on it, so it
+ * is one call away from whatever its owner can touch. Grading it by its schema
+ * is not conservative, it is wrong in the dangerous direction.
+ *
+ * The question a routine finding is graded by is therefore the callability
+ * one: can an untrusted role reach the function itself — `USAGE` on its
+ * schema, and `EXECUTE` on the function, directly, by inheritance, or through
+ * Postgres's default `EXECUTE TO PUBLIC`.
+ */
+import type { RoleGraph } from '../checks/lattice';
+import { type SchemaAclInfo } from '../pg/acl';
+import type { FunctionSnapshot } from '../pg/functions';
+export interface RoutineReachOptions {
+    /** Roles a request can arrive as — the API edge, plus its anonymous roles. */
+    roles: string[];
+    graph: RoleGraph;
+    schemaAcls: Map<string, SchemaAclInfo>;
+    /**
+     * Schemas on the API surface. A trigger function is not directly callable
+     * whatever its ACL says, so it is judged the way its firing is: reachable
+     * when a write that fires it is.
+     */
+    exposedSchemas: Set<string>;
+}
+/**
+ * Every `schema.name` an untrusted role can execute. Overloads collapse: the
+ * finding names a function, not a signature, and a role that can call one
+ * overload can reach the body the rule is talking about.
+ */
+export declare function resolveRoutineReach(functions: FunctionSnapshot[], options: RoutineReachOptions): Set<string>;

package/exposure/routines.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * Routine exposure: which functions an untrusted role can actually call.
+ *
+ * The exposure surface answers "which relations can the API address?", and
+ * every finding was graded by that question — including the ones that are not
+ * about a relation at all. A definer function lives in a private schema, so by
+ * relation reach it is unexposed; but `anonymous` holds `EXECUTE` on it, so it
+ * is one call away from whatever its owner can touch. Grading it by its schema
+ * is not conservative, it is wrong in the dangerous direction.
+ *
+ * The question a routine finding is graded by is therefore the callability
+ * one: can an untrusted role reach the function itself — `USAGE` on its
+ * schema, and `EXECUTE` on the function, directly, by inheritance, or through
+ * Postgres's default `EXECUTE TO PUBLIC`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRoutineReach = resolveRoutineReach;
+const acl_1 = require("../pg/acl");
+/**
+ * Every `schema.name` an untrusted role can execute. Overloads collapse: the
+ * finding names a function, not a signature, and a role that can call one
+ * overload can reach the body the rule is talking about.
+ */
+function resolveRoutineReach(functions, options) {
+    const reachable = new Set();
+    if (options.roles.length === 0)
+        return reachable;
+    for (const fn of functions) {
+        const key = `${fn.schema}.${fn.name}`;
+        if (reachable.has(key))
+            continue;
+        if (fn.returnsTrigger) {
+            // Postgres refuses a direct call however wide the ACL is. What reaches
+            // the body is a write to the table the trigger is attached to, so the
+            // API surface is the right question after all.
+            if (options.exposedSchemas.has(fn.schema))
+                reachable.add(key);
+            continue;
+        }
+        if (options.roles.some((role) => canExecute(fn, role, options)))
+            reachable.add(key);
+    }
+    return reachable;
+}
+function canExecute(fn, role, { graph, schemaAcls }) {
+    if (!(0, acl_1.canEnterSchema)(fn.schema, role, graph, schemaAcls))
+        return false;
+    const attrs = graph.get(role);
+    if (attrs?.isSuper)
+        return true;
+    if (role === fn.owner)
+        return true;
+    return fn.grants.some((g) => g.role === 'PUBLIC'
+        || g.role === role
+        || (attrs?.inheritsFrom ?? []).includes(g.role));
+}

package/index.d.ts

@@ -1,6 +1,96 @@
-export * from './admin';
-export * from './connect';
-export * from './manager';
-export * from './roles';
-export * from './seed';
-export * from './test-client';
+/**
+ * Public surface of `safegres` — a pure-PostgreSQL Row-Level-Security auditor.
+ *
+ * The auditor introspects pg_class / pg_policy / role grants and emits
+ * structured findings (A1–A7, P1, P5). It has no knowledge of any specific
+ * application schema or policy DSL.
+ */
+export { parsePolicyExpression, type PgAstNode, type PolicyExpression, PolicyParseError } from './ast/parse';
+export type { BaselineBoundary, CallGraphBaseline, CallGraphDiff } from './callgraph/baseline';
+export { boundaryKey, diffCallGraph, parseBaseline, serializeBaseline, toBaseline } from './callgraph/baseline';
+export type { CallGraphEdge, CallGraphNode, CallGraphOptions, CallGraphReport, ChecklistCode, ChecklistItem } from './callgraph/graph';
+export { buildCallGraph } from './callgraph/graph';
+export { checkUntrustedColumnGrants } from './checks/column-grants';
+export type { FunctionBodyAnalysis } from './checks/definer-function';
+export { analyzeFunctionBodies, checkDefinerFunctionReach, checkInsteadOfTriggerWrite, checkUnreadableFunctionReach } from './checks/definer-function';
+export type { SuppressedView, ViewBodyAnalysis } from './checks/definer-view';
+export { analyzeViewBodies, checkDefinerViewBypass, checkUnauditedViewReach, checkUnreadableViewReach } from './checks/definer-view';
+export { checkMissingPrimaryKey, checkRedundantIndexes, checkUnindexedForeignKeys, checkUnindexedSearchColumns, checkUnindexedSortColumns } from './checks/indexes';
+export type { EffectiveColumnGrant, EffectiveGrant, GrantVia, LatticeRoleOptions, RoleAccessEntry, RoleAccessRelation, RoleGraph } from './checks/lattice';
+export { checkDeadPolicies, checkDeadSchemaUsage, checkIndirectCoverageGaps, checkUnreachableGrants, checkUntrustedIndirectAccess, computeRoleAccess, effectiveColumnGrants, effectiveGrants } from './checks/lattice';
+export { checkUntrustedForeignTableGrants, checkUntrustedSequenceGrants } from './checks/object-acls';
+export type { PolicyClause, PredicateColumn } from './checks/policy-index';
+export { checkNonLeakproofPolicyFunctions, checkPolicyColumnCasts, checkUnhoistedPolicyFunctions, checkUnindexedPolicyColumns, collectPredicateColumns } from './checks/policy-index';
+export type { RoleTrustOptions } from './checks/role-trust';
+export { checkPublicGrants, checkUntrustedRolePolicies, checkUntrustedRoleWrites } from './checks/role-trust';
+export type { StatsThresholds } from './checks/stats';
+export { checkDeadTuples, checkSeqScanDominant, checkStats, checkTopStatements, checkUnusedIndexes, DEFAULT_STATS_THRESHOLDS } from './checks/stats';
+export type { ViewExposureAnalysis } from './checks/view-exposure';
+export { analyzeViewExposure, checkLeakyFilterView, checkMatviewSnapshot } from './checks/view-exposure';
+export type { ViewWriteAnalysis } from './checks/view-writes';
+export { analyzeViewWrites, checkDefinerViewWrite, checkUncheckedViewWrite, checkViewRuleBypass } from './checks/view-writes';
+export type { BaselineCandidate, BaselineSelection, ChosenBaseline, RejectedCandidate, SelectBaselineOptions } from './ci/baseline';
+export { CANDIDATE_LIMIT, MAX_BASELINE_AGE_MS, selectBaseline } from './ci/baseline';
+export type { GithubBaselineOptions, GithubBaselineResult } from './ci/github';
+export { selectGithubBaseline } from './ci/github';
+export type { AuditOptions } from './commands/audit';
+export { audit } from './commands/audit';
+export type { DoctorCheck, DoctorOptions, DoctorReport, DoctorStatus } from './commands/doctor';
+export { doctor } from './commands/doctor';
+export type { EvalCaseResult, EvalOptions, EvalReport } from './commands/eval';
+export { runEval } from './commands/eval';
+export type { Provenance } from './config/fingerprint';
+export { configFingerprint } from './config/fingerprint';
+export type { LoadConfigParams } from './config/loader';
+export { loadConfig, safegresConfigLoader } from './config/loader';
+export { constructive, graphile, hasura, minimal, multiTenant, oltp, postgrest, PRESETS, recommended, strict, supabase } from './config/presets';
+export type { ResolvedRule, ResolvedRules } from './config/resolve';
+export { allAstRulesDisabled, applyRulesToFindings, ConfigValidationError, defaultRuleMap, matchTablePattern, resolveRules, ruleCodesForDimension, rulesForTable } from './config/resolve';
+export { CONFIG_SHAPE, SCHEMA_ID, toJsonSchema } from './config/schema';
+export type { CallGraphConfig, EvalConfig, ExposureConfig, FailOnConfig, GithubCommentConfig, GithubReportConfig, Grade, OutputsConfig, OverrideEntry, PerfConfig, PlaneConfig, PlaneFailOnConfig, PlaneKind, ReportConfig, RulesConfig, RuleSetting, SafegresConfig, ScoringConfig, SourceConfig } from './config/types';
+export { validateConfigShape } from './config/validate';
+export type { CaseResult, CorpusCase, ExpectedFinding } from './corpus';
+export { corpusBootstrap, corpusDir, gradeCase, loadCase, loadCorpus } from './corpus';
+export type { ExposureAdapter, PlaneInput, ReachContext } from './exposure/adapters';
+export { BUILTIN_ADAPTERS, constructiveAdapter, definePlanes, graphileAdapter, hasuraAdapter, postgraphileAdapter, postgrestAdapter, resolveAdapters, supabaseAdapter } from './exposure/adapters';
+export type { PlaneReach } from './exposure/planes';
+export { onPlane, relationKey, resolvePlaneReach, scorePlane, stampPlanes } from './exposure/planes';
+export type { ApiReach, ReachEdge, ReachInputs, UnreachableRelation } from './exposure/reach';
+export { BACKWARD_ABILITIES, computeApiReach, FORWARD_ABILITIES, ROOT_ABILITIES } from './exposure/reach';
+export type { BaselineFinding, PerfBaseline, PerfDiff } from './perf/baseline';
+export { diffPerf, findingKey, parsePerfBaseline, serializePerfBaseline, subjectOf, toBaselineFinding, toPerfBaseline } from './perf/baseline';
+export type { ExplainOptions, ExplainReport } from './perf/explain';
+export { proveFindings } from './perf/explain';
+export type { RoleAttributes, SchemaAclGrant, SchemaAclInfo, SchemaAclOptions } from './pg/acl';
+export { introspectRoleGraph, introspectSchemaAcls } from './pg/acl';
+export type { ResolvedExposure, ResolvedPlane } from './pg/exposure';
+export { resolveConstructiveExposure, resolveExposure, resolvePlanes, resolveReach, UNKNOWN_EXPOSURE } from './pg/exposure';
+export type { FunctionGrant, FunctionSnapshot, IntrospectFunctionOptions } from './pg/functions';
+export { introspectFunctions } from './pg/functions';
+export type { ColumnInfo, ForeignKeyInfo, IndexInfo, TableIndexSnapshot, ViewSnapshot } from './pg/indexes';
+export { introspectIndexes, introspectViews } from './pg/indexes';
+export { type ColumnGrantInfo, type GrantInfo, type IntrospectOptions, introspectTables, type PgPrivilege, type PolicyCmd, type PolicyInfo, type QueryExecutor, type TableSnapshot } from './pg/introspect';
+export type { ObjectAclSnapshot, PgObjectKind } from './pg/objects';
+export { introspectObjectAcls } from './pg/objects';
+export { listAuditableRoles, resolveRoles } from './pg/roles';
+export type { IndexUsage, StatementUsage, StatsSnapshot, TableUsage } from './pg/stats';
+export { introspectStats } from './pg/stats';
+export { renderCallGraph, renderCallGraphDiff } from './report/callgraph';
+export type { BaselineProvenance, DimensionSnapshot, ReportComparison, ReportSnapshot, RuleDelta, ScoreDelta } from './report/compare';
+export { baselineLabel, compareReports, describeBaseline, formatAge, formatDelta, parseSnapshot, serializeSnapshot, toSnapshot } from './report/compare';
+export type { GithubRenderOptions } from './report/github';
+export { COMMENT_MARKER, emitGithub, gradeBadge, postStickyComment, renderAnnotations, renderGithubComment, renderGithubSummary, scoreBadge } from './report/github';
+export { renderJson } from './report/json';
+export type { RenderMarkdownOptions } from './report/markdown';
+export { renderMarkdown } from './report/markdown';
+export type { RenderPrettyOptions } from './report/pretty';
+export { renderPretty } from './report/pretty';
+export type { BuildSourceIndexOptions, RenderSarifOptions, SourceIndex, SourceLocation } from './report/sarif';
+export { buildSourceIndex, renderSarif } from './report/sarif';
+export type { ReportView, ViewConfig, ViewDimension, ViewFindings, ViewScore, ViewSection } from './report/view';
+export { ALL_SECTIONS, matchPlane, selectView, viewConfigFromReportConfig } from './report/view';
+export type { RuleMeta } from './rules/registry';
+export { dimensionOf, expandRuleSelector, isKnownRule, RULES, RULES_BY_CODE } from './rules/registry';
+export type { Score, ScoreContext, ScoreDeduction } from './score/score';
+export { computeScore, DEFAULT_GRADE_BANDS, DEFAULT_WEIGHTS, meetsGrade } from './score/score';
+export * from './types';