@safegres/test 0.0.2 → 1.30.7

package/adapters.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `safegres/adapters` — the built-in exposure adapters and the interface a
+ * custom one implements. Kept as its own entry point so a config file can
+ * import an adapter without pulling in the whole auditor.
+ */
+export type { ExposureAdapter, PlaneInput, ReachContext } from './exposure/adapters';
+export { BUILTIN_ADAPTERS, constructiveAdapter, definePlanes, graphileAdapter, hasuraAdapter, postgraphileAdapter, postgrestAdapter, resolveAdapters, supabaseAdapter } from './exposure/adapters';
+export type { ApiReach, UnreachableRelation } from './exposure/reach';

package/adapters.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * `safegres/adapters` — the built-in exposure adapters and the interface a
+ * custom one implements. Kept as its own entry point so a config file can
+ * import an adapter without pulling in the whole auditor.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.supabaseAdapter = exports.resolveAdapters = exports.postgrestAdapter = exports.postgraphileAdapter = exports.hasuraAdapter = exports.graphileAdapter = exports.definePlanes = exports.constructiveAdapter = exports.BUILTIN_ADAPTERS = void 0;
+var adapters_1 = require("./exposure/adapters");
+Object.defineProperty(exports, "BUILTIN_ADAPTERS", { enumerable: true, get: function () { return adapters_1.BUILTIN_ADAPTERS; } });
+Object.defineProperty(exports, "constructiveAdapter", { enumerable: true, get: function () { return adapters_1.constructiveAdapter; } });
+Object.defineProperty(exports, "definePlanes", { enumerable: true, get: function () { return adapters_1.definePlanes; } });
+Object.defineProperty(exports, "graphileAdapter", { enumerable: true, get: function () { return adapters_1.graphileAdapter; } });
+Object.defineProperty(exports, "hasuraAdapter", { enumerable: true, get: function () { return adapters_1.hasuraAdapter; } });
+Object.defineProperty(exports, "postgraphileAdapter", { enumerable: true, get: function () { return adapters_1.postgraphileAdapter; } });
+Object.defineProperty(exports, "postgrestAdapter", { enumerable: true, get: function () { return adapters_1.postgrestAdapter; } });
+Object.defineProperty(exports, "resolveAdapters", { enumerable: true, get: function () { return adapters_1.resolveAdapters; } });
+Object.defineProperty(exports, "supabaseAdapter", { enumerable: true, get: function () { return adapters_1.supabaseAdapter; } });

package/ast/helpers.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Small typed helpers for inspecting `pgsql-parser` AST nodes.
+ *
+ * Operates on the raw shape returned by `parse()` rather than the typed
+ * `@pgsql/types` view, so the runtime cost is just object lookups.
+ */
+import type { PgAstNode } from './parse';
+type Obj = Record<string, unknown>;
+/** Extract the single wrapping key (e.g. `A_Expr`, `BoolExpr`) and its payload. */
+export declare function unwrap(node: PgAstNode): {
+    kind: string;
+    body: Obj;
+} | null;
+/** Returns the boolean literal value, or null if not an `A_Const(bool)`. */
+export declare function boolConst(node: PgAstNode): boolean | null;
+export {};

package/ast/helpers.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * Small typed helpers for inspecting `pgsql-parser` AST nodes.
+ *
+ * Operates on the raw shape returned by `parse()` rather than the typed
+ * `@pgsql/types` view, so the runtime cost is just object lookups.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unwrap = unwrap;
+exports.boolConst = boolConst;
+function isObj(x) {
+    return typeof x === 'object' && x !== null;
+}
+/** Extract the single wrapping key (e.g. `A_Expr`, `BoolExpr`) and its payload. */
+function unwrap(node) {
+    if (!isObj(node))
+        return null;
+    const keys = Object.keys(node);
+    if (keys.length !== 1)
+        return null;
+    const body = node[keys[0]];
+    if (!isObj(body))
+        return null;
+    return { kind: keys[0], body };
+}
+/** Returns the boolean literal value, or null if not an `A_Const(bool)`. */
+function boolConst(node) {
+    const u = unwrap(node);
+    if (!u || u.kind !== 'A_Const')
+        return null;
+    // `pgsql-parser` represents `true` as `{ boolval: { boolval: true } }` and
+    // `false` as `{ boolval: {} }` (the parser elides the default value). The
+    // *presence* of the `boolval` key is what identifies a boolean literal.
+    if (!('boolval' in u.body))
+        return null;
+    const boolval = u.body.boolval;
+    if (!boolval || typeof boolval !== 'object')
+        return null;
+    return boolval.boolval === true;
+}

package/ast/parse.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Wrapper around `pgsql-parser` that handles the reality that RLS predicates
+ * appearing in `pg_get_expr(polqual, polrelid)` are fragments, not statements.
+ *
+ * We wrap the fragment in a `SELECT … WHERE <expr>` so the parser accepts it,
+ * then pull the `whereClause` out of the resulting AST.
+ */
+/** Opaque AST node — intentionally `unknown` to keep us loose against pgsql-parser upgrades. */
+export type PgAstNode = unknown;
+export interface PolicyExpression {
+    /** Original text (exactly as returned by pg_get_expr). */
+    text: string;
+    /** Root AST node of the expression (not the wrapping SELECT). */
+    ast: PgAstNode;
+}
+export declare class PolicyParseError extends Error {
+    readonly expr: string;
+    readonly cause: unknown;
+    constructor(expr: string, cause: unknown);
+}
+/**
+ * Parse a policy expression fragment.
+ *
+ * `parse` from pgsql-parser v17 is async (it awaits a WASM load), so this
+ * wrapper is async too.
+ *
+ * @param expr   The text from `pg_get_expr(...)`.
+ * @returns      Parsed AST, or `null` if `expr` is null/empty.
+ * @throws       `PolicyParseError` on parse failure.
+ */
+export declare function parsePolicyExpression(expr: string | null): Promise<PolicyExpression | null>;

package/ast/parse.js

@@ -0,0 +1,87 @@
+"use strict";
+/**
+ * Wrapper around `pgsql-parser` that handles the reality that RLS predicates
+ * appearing in `pg_get_expr(polqual, polrelid)` are fragments, not statements.
+ *
+ * We wrap the fragment in a `SELECT … WHERE <expr>` so the parser accepts it,
+ * then pull the `whereClause` out of the resulting AST.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PolicyParseError = void 0;
+exports.parsePolicyExpression = parsePolicyExpression;
+const pgsql_parser_1 = require("pgsql-parser");
+class PolicyParseError extends Error {
+    expr;
+    cause;
+    constructor(expr, cause) {
+        super(`Failed to parse policy expression: ${expr}`);
+        this.expr = expr;
+        this.cause = cause;
+    }
+}
+exports.PolicyParseError = PolicyParseError;
+/**
+ * Parse a policy expression fragment.
+ *
+ * `parse` from pgsql-parser v17 is async (it awaits a WASM load), so this
+ * wrapper is async too.
+ *
+ * @param expr   The text from `pg_get_expr(...)`.
+ * @returns      Parsed AST, or `null` if `expr` is null/empty.
+ * @throws       `PolicyParseError` on parse failure.
+ */
+async function parsePolicyExpression(expr) {
+    if (expr === null || expr === undefined)
+        return null;
+    const trimmed = expr.trim();
+    if (trimmed === '')
+        return null;
+    // Strip outer parens that Postgres adds to pg_get_expr output, so the
+    // wrapping `WHERE` is cleaner. We only strip *one* pair and only when
+    // balanced — otherwise we leave the text alone and let the parser deal.
+    const inner = stripOuterParens(trimmed);
+    const wrapped = `SELECT 1 FROM __safegres_audit_dummy WHERE (${inner})`;
+    let parsed;
+    try {
+        parsed = await (0, pgsql_parser_1.parse)(wrapped);
+    }
+    catch (err) {
+        throw new PolicyParseError(expr, err);
+    }
+    const ast = extractWhereClause(parsed);
+    if (!ast) {
+        throw new PolicyParseError(expr, new Error('no whereClause in parsed SELECT'));
+    }
+    return { text: expr, ast };
+}
+function stripOuterParens(s) {
+    if (s.length < 2 || s[0] !== '(' || s[s.length - 1] !== ')')
+        return s;
+    let depth = 0;
+    for (let i = 0; i < s.length; i++) {
+        if (s[i] === '(')
+            depth++;
+        else if (s[i] === ')') {
+            depth--;
+            if (depth === 0 && i !== s.length - 1)
+                return s;
+        }
+    }
+    return s.slice(1, -1);
+}
+function extractWhereClause(parsed) {
+    // pgsql-parser v17 returns `{ stmts: [{ stmt: { SelectStmt: { whereClause: … } } }] }`
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const asRecord = parsed;
+    const stmts = asRecord.stmts;
+    if (!Array.isArray(stmts) || stmts.length === 0)
+        return null;
+    const first = stmts[0];
+    const stmt = (first.stmt ?? first);
+    const selectStmt = stmt.SelectStmt;
+    if (!selectStmt)
+        return null;
+    const where = selectStmt.whereClause;
+    return where ?? null;
+}

package/ast/walk.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Domain-specific AST helpers for the safegres auditor, layered on top of
+ * `@pgsql/traverse`'s `walk` / `NodePath`.
+ */
+import type { PgAstNode } from './parse';
+/** Find every node tagged with `tag` (e.g. `FuncCall`, `ColumnRef`). */
+export declare function findAll(root: PgAstNode, tag: string): Record<string, unknown>[];
+/** Visit every tagged node. `visit(node, tag, parent)` matches the old API. */
+export type Visitor = (node: Record<string, unknown>, tag: string, parent: Record<string, unknown> | null) => void;
+export declare function visitAll(root: PgAstNode, visit: Visitor): void;
+/**
+ * Extract the printable name of a `FuncCall.funcname` field.
+ *
+ * `funcname` is an array of `{ String: { sval: "..." } }` nodes — usually one
+ * element (bare name) or two (schema-qualified).
+ */
+export declare function funcNameParts(funcCall: Record<string, unknown>): {
+    schema?: string;
+    name: string;
+};
+/** Get the printable qualified name (`schema.name` or `name`). */
+export declare function funcNameQualified(funcCall: Record<string, unknown>): string;
+/**
+ * Get a ColumnRef's dotted name path. Example: `s.actor_id` → `['s', 'actor_id']`.
+ * Returns `['*']` for `SELECT *`.
+ */
+export declare function columnRefPath(columnRef: Record<string, unknown>): string[];

package/ast/walk.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Domain-specific AST helpers for the safegres auditor, layered on top of
+ * `@pgsql/traverse`'s `walk` / `NodePath`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findAll = findAll;
+exports.visitAll = visitAll;
+exports.funcNameParts = funcNameParts;
+exports.funcNameQualified = funcNameQualified;
+exports.columnRefPath = columnRefPath;
+const traverse_1 = require("@pgsql/traverse");
+/** Find every node tagged with `tag` (e.g. `FuncCall`, `ColumnRef`). */
+function findAll(root, tag) {
+    const out = [];
+    (0, traverse_1.walk)(root, (path) => {
+        if (path.tag === tag) {
+            out.push(path.node);
+        }
+    });
+    return out;
+}
+function visitAll(root, visit) {
+    (0, traverse_1.walk)(root, (path) => {
+        visit(path.node, path.tag, path.parent?.node ?? null);
+    });
+}
+/**
+ * Extract the printable name of a `FuncCall.funcname` field.
+ *
+ * `funcname` is an array of `{ String: { sval: "..." } }` nodes — usually one
+ * element (bare name) or two (schema-qualified).
+ */
+function funcNameParts(funcCall) {
+    const funcname = funcCall.funcname;
+    if (!Array.isArray(funcname))
+        return { name: '<unknown>' };
+    const parts = funcname
+        .map((n) => {
+        const rec = n;
+        const str = (rec.String ?? rec.string);
+        if (!str)
+            return '';
+        return String((str.sval ?? str.str) ?? '');
+    })
+        .filter((s) => s.length > 0);
+    if (parts.length >= 2)
+        return { schema: parts[0], name: parts[parts.length - 1] };
+    if (parts.length === 1)
+        return { name: parts[0] };
+    return { name: '<unknown>' };
+}
+/** Get the printable qualified name (`schema.name` or `name`). */
+function funcNameQualified(funcCall) {
+    const { schema, name } = funcNameParts(funcCall);
+    return schema ? `${schema}.${name}` : name;
+}
+/**
+ * Get a ColumnRef's dotted name path. Example: `s.actor_id` → `['s', 'actor_id']`.
+ * Returns `['*']` for `SELECT *`.
+ */
+function columnRefPath(columnRef) {
+    const fields = columnRef.fields;
+    if (!Array.isArray(fields))
+        return [];
+    const out = [];
+    for (const f of fields) {
+        const rec = f;
+        const str = (rec.String ?? rec.string);
+        if (str) {
+            out.push(String((str.sval ?? str.str) ?? ''));
+            continue;
+        }
+        if ('A_Star' in rec) {
+            out.push('*');
+        }
+    }
+    return out;
+}

package/callgraph/baseline.d.ts

@@ -0,0 +1,28 @@
+import type { CallGraphReport, ChecklistCode, ChecklistItem } from './graph';
+/**
+ * A committed snapshot of the call-graph checklist, used by CI to detect
+ * *new* trust boundaries introduced by a change. Only the identity of each
+ * boundary is stored (code + entry + fn + table) — messages and paths may
+ * be reworded between versions without invalidating the baseline.
+ */
+export interface CallGraphBaseline {
+    version: 1;
+    boundaries: BaselineBoundary[];
+}
+export interface BaselineBoundary {
+    code: ChecklistCode;
+    entry: string;
+    fn: string;
+    table?: string;
+}
+export interface CallGraphDiff {
+    /** Checklist items present now but not in the baseline — require sign-off. */
+    added: ChecklistItem[];
+    /** Baseline boundaries no longer present — resolved or removed. */
+    removed: BaselineBoundary[];
+}
+export declare function boundaryKey(b: BaselineBoundary): string;
+export declare function toBaseline(report: CallGraphReport): CallGraphBaseline;
+export declare function diffCallGraph(report: CallGraphReport, baseline: CallGraphBaseline): CallGraphDiff;
+export declare function parseBaseline(raw: string): CallGraphBaseline;
+export declare function serializeBaseline(baseline: CallGraphBaseline): string;

package/callgraph/baseline.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.boundaryKey = boundaryKey;
+exports.toBaseline = toBaseline;
+exports.diffCallGraph = diffCallGraph;
+exports.parseBaseline = parseBaseline;
+exports.serializeBaseline = serializeBaseline;
+function boundaryKey(b) {
+    return [b.code, b.entry, b.fn, b.table ?? ''].join('|');
+}
+function toBaseline(report) {
+    const seen = new Set();
+    const boundaries = [];
+    for (const item of report.checklist) {
+        const b = {
+            code: item.code,
+            entry: item.entry,
+            fn: item.fn,
+            ...(item.table ? { table: item.table } : {})
+        };
+        const key = boundaryKey(b);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        boundaries.push(b);
+    }
+    boundaries.sort((a, b) => boundaryKey(a).localeCompare(boundaryKey(b)));
+    return { version: 1, boundaries };
+}
+function diffCallGraph(report, baseline) {
+    const baseKeys = new Set(baseline.boundaries.map(boundaryKey));
+    const current = toBaseline(report);
+    const currentKeys = new Set(current.boundaries.map(boundaryKey));
+    const addedKeys = new Set();
+    const added = [];
+    for (const item of report.checklist) {
+        const key = boundaryKey({ code: item.code, entry: item.entry, fn: item.fn, table: item.table });
+        if (baseKeys.has(key) || addedKeys.has(key))
+            continue;
+        addedKeys.add(key);
+        added.push(item);
+    }
+    const removed = baseline.boundaries.filter((b) => !currentKeys.has(boundaryKey(b)));
+    return { added, removed };
+}
+function parseBaseline(raw) {
+    const data = JSON.parse(raw);
+    if (data.version !== 1 || !Array.isArray(data.boundaries)) {
+        throw new Error('invalid call-graph baseline: expected { version: 1, boundaries: [...] }');
+    }
+    return { version: 1, boundaries: data.boundaries };
+}
+function serializeBaseline(baseline) {
+    return JSON.stringify(baseline, null, 2) + '\n';
+}

package/callgraph/extract.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Static body extraction for the call graph.
+ *
+ * Given a function's source, extract the function calls, table references
+ * (read vs write), and auth-context mutations it contains. Dynamic SQL
+ * (`EXECUTE format(...)`) and unparseable bodies are surfaced as `opaque`
+ * rather than silently dropped — static analysis ends there.
+ *
+ * A view body is the same question asked of a different object, so
+ * {@link extractQuery} exposes the plain-SQL half directly.
+ */
+import type { FunctionSnapshot } from '../pg/functions';
+export interface NameRef {
+    schema?: string;
+    name: string;
+}
+export interface TableRef extends NameRef {
+    write: boolean;
+}
+/**
+ * A relation reference with the privilege the reference actually exercises,
+ * rather than the read/write bit {@link TableRef} carries. `INSERT INTO audit`
+ * and `UPDATE audit` are both writes, but they are not the same grant, and a
+ * rule action can mix them in one statement.
+ */
+export interface RelationAccess extends NameRef {
+    privilege: 'SELECT' | 'INSERT' | 'UPDATE' | 'DELETE';
+}
+export interface ExtractedAccess {
+    accesses: RelationAccess[];
+    opaque: boolean;
+    opaqueReason?: string;
+}
+export interface ExtractedBody {
+    calls: NameRef[];
+    tables: TableRef[];
+    /** GUC names written via `set_config(...)` / `SET`, plus `role` for SET ROLE. */
+    settings: string[];
+    /** True when the body contains dynamic SQL we cannot follow statically. */
+    opaque: boolean;
+    /** Why the body is (partially) opaque, when it is. */
+    opaqueReason?: string;
+    /**
+     * The body executes SQL this analysis cannot see, *alongside* references it
+     * could read: `calls`, `tables` and `settings` are correct but incomplete.
+     *
+     * This is the distinction {@link opaque} cannot make. `opaque` says the
+     * whole body is unknown and its references must be discarded; `tainted`
+     * says what was read is real and what was missed is unknowable, which is
+     * what a reach model needs in order to report the gap instead of the view
+     * disappearing from the analysis altogether.
+     */
+    tainted?: string;
+}
+export declare function extractBody(fn: FunctionSnapshot): Promise<ExtractedBody>;
+/**
+ * {@link extractAccess} asked of a whole function rather than one statement:
+ * every relation the body touches, with the privilege the touch exercises.
+ *
+ * This is what a SECURITY DEFINER function's reach is made of — the body runs
+ * as the owner, so each `INSERT INTO t` in it is an INSERT on `t` that the
+ * caller never needed a grant for. A body that cannot be read is `opaque`,
+ * and an opaque body's access list is a fragment its caller must discard.
+ */
+export declare function extractFunctionAccess(fn: FunctionSnapshot): Promise<ExtractedAccess>;
+/**
+ * The same extraction over a standalone SQL statement — a view body, a policy
+ * predicate, anything that is already plain SQL rather than a function.
+ */
+export declare function extractQuery(sql: string): Promise<ExtractedBody>;
+/**
+ * The same walk as {@link extractQuery}, but resolving each relation
+ * reference to the privilege it exercises instead of a read/write bit.
+ *
+ * Used for statements whose interesting content is *which grant* a reference
+ * needs — a rewrite rule's actions, where `INSERT INTO audit` means the rule
+ * needs INSERT on `audit` and nothing else tells you so.
+ */
+export declare function extractAccess(sql: string): Promise<ExtractedAccess>;
+/**
+ * Does this body restrict which rows come back?
+ *
+ * `null` when the SQL could not be parsed — "unknown", never "no". A view that
+ * filters is a view someone may be relying on as a row-level boundary, which
+ * is the precondition for the `security_barrier` question: without a `WHERE`
+ * there are no hidden rows for a leaky qual to reach.
+ *
+ * Only an explicit `WHERE`/`HAVING` counts. Row-limiting through a join,
+ * `DISTINCT` or `LIMIT` is real but is not the pattern that gets written as a
+ * security boundary, and treating it as one would fire on ordinary reporting
+ * views.
+ */
+export declare function bodyFiltersRows(sql: string): Promise<boolean | null>;