safegres 1.7.0 → 1.11.0

package/README.md

@@ -26,27 +26,128 @@ safegres audit
 
 Per-field overrides (`--host`, `--port`, `--user`, `--password`, `--database`) and a full `--connection <url>` flag are also supported. See `safegres audit --help`.
 
+### Output & verbosity
+
+Pretty output prints the exposure line, score, and the exposed findings. Internal (non-exposed) advisories are collapsed to a one-line count by default so a large database's report stays readable.
+
+- `--summary`, `-q` — print only the exposure line, score/grade, and severity counts (no per-finding lines). Ideal for CI job summaries.
+- `--verbose` — expand the internal advisories instead of collapsing them to a count.
+- `--exposed-only` — drop internal findings entirely.
+- `--format json` / `--format json-pretty` — machine-readable output (always carries every finding).
+
 ## What it checks
 
-| Code | Severity | Category | Check |
-| --- | --- | --- | --- |
-| A1 | critical | flags | RLS enabled but **0 policies** (effectively deny-all) |
-| A2 | high | flags | Grants exist on a table with **RLS disabled** |
-| A3 | medium | flags | RLS enabled but **`FORCE ROW LEVEL SECURITY` not set** (table owner bypass) |
-| A4 | high | coverage | INSERT / UPDATE / DELETE grant with **no covering policy** for that verb |
-| A5 | medium | coverage | SELECT grant with **no policy** (silent empty result) |
-| A6 | info | coverage | UPDATE has `USING` but **no `WITH CHECK`** (row-smuggling surface) |
-| A7 | high | anti-pattern | Trivially-permissive policy (`USING (true)` / `WITH CHECK (true)`) |
-| P1 | high | anti-pattern | Policy body calls a **VOLATILE function** (per-row evaluation) |
-| P5 | high | anti-pattern | Policy body references **`session_user`** / `current_user` / `pg_has_role(...)` |
-| R1 | critical | anti-pattern | An **untrusted role** (options: `{ roles: [...] }`) holds a write privilege |
-| R2 | high | anti-pattern | A permissive write policy applies to an untrusted role or PUBLIC |
-| R3 | medium | anti-pattern | An RLS table has grants **TO PUBLIC** (includes all current/future roles) |
+| Code | Severity | Direction | Category | Check |
+| --- | --- | --- | --- | --- |
+| A1 | low | fail-closed | flags | RLS enabled but **0 policies** (deny-all — confirm the lock is intended) |
+| A2 | high | fail-open | flags | Grants exist on a table with **RLS disabled** |
+| A3 | low | fail-open | flags | RLS enabled but **`FORCE ROW LEVEL SECURITY` not set** (table owner bypass) |
+| A4 | low | fail-closed | coverage | INSERT / UPDATE / DELETE grant with **no covering policy** — writes are denied at runtime |
+| A5 | low | fail-closed | coverage | SELECT grant with **no policy** — queries silently return 0 rows |
+| A6 | info | fail-closed | coverage | UPDATE has `USING` but **no `WITH CHECK`** (row-smuggling surface) |
+| A7 | critical | fail-open | anti-pattern | Trivially-permissive **WRITE** policy (INSERT/UPDATE/DELETE/ALL with literal `true`) |
+| A8 | low | fail-open | anti-pattern | Trivially-permissive **SELECT** policy (`USING (true)` — confirm public-read is intended) |
+| P1 | high | neutral | anti-pattern | Policy body calls a **VOLATILE function** (per-row evaluation) |
+| P5 | high | fail-open | anti-pattern | Policy body references **`session_user`** / `current_user` / `pg_has_role(...)` |
+| R1 | critical | fail-open | anti-pattern | An **untrusted role** (options: `{ roles: [...] }`) holds a write privilege |
+| R2 | high | fail-open | anti-pattern | A permissive write policy applies to an untrusted role or PUBLIC |
+| R3 | medium | fail-open | anti-pattern | An RLS table has grants **TO PUBLIC** (includes all current/future roles) |
+| W1 | medium | — | meta | No exposure surface configured — whole database assumed reachable, score capped |
+
+**Direction matters**: `fail-open` findings are actual exposure (the untrusted side can reach more than intended). `fail-closed` findings are denied at runtime — an availability/hygiene concern, not a leak — and contribute **nothing to the score** by default (tune with `scoring.failClosedWeight`).
 
 Coverage is aggregated `(table, role) → { hasUsing, hasWithCheck }` across every applicable permissive policy (FOR ALL + PUBLIC-role policies considered). Roles with `BYPASSRLS` are suppressed.
 
 R1/R2 are no-ops until a role list is configured — e.g. `"R1": ["critical", { "roles": ["anonymous"] }]` — so they cost nothing on databases without an untrusted-role model. The `safegres:constructive` preset configures them for `anonymous`.
 
+## Exposure surface
+
+A database-wide score is meaningless if most of the database isn't reachable through the app's APIs. Declare (or auto-resolve) the **exposure surface** and safegres partitions findings:
+
+- **Exposed** findings (on API-reachable schemas) drive the score.
+- **Internal** findings are reported as unscored *internal advisories* (hide entirely with `--exposed-only`).
+- **No exposure configured** → a `W1` warning is emitted and the score is capped at 80/B (`scoring.unknownExposureCap`).
+
+```jsonc
+{
+  "exposure": {
+    "schemas": ["app_public", "app_hidden"]      // static surface
+    // or, on a Constructive database:
+    // "resolver": "constructive"                 // introspects routing_public.apis → api_schemas
+  }
+}
+```
+
+CLI: `--exposure-schemas <csv>`, `--exposed-only`. The `safegres:constructive` preset sets `exposure.resolver: "constructive"` so the surface is discovered automatically from the routing plane (including API roles from `role_name`/`anon_role`).
+
+## Declared public surface
+
+Some open reads are deliberate — pricing tables, reference data, a public user directory. Declare them and safegres treats them as intent instead of findings:
+
+```jsonc
+{
+  "public": {
+    "read": [
+      "app_public.plans*",        // schema.table globs
+      "app_public.event_types",
+      "app_public.users"          // deliberate public directory
+    ]
+  }
+}
+```
+
+- An open SELECT policy (`USING (true)` — rule A8) on a declared table is **acknowledged**: reported as info, excluded from the score.
+- An open read on any *undeclared* table stays a scored finding — even in a `*_public`-named schema. Naming is never treated as intent; the config declaration is.
+- `safegres doctor` warns about stale `public.read` patterns that no longer match any table.
+
+## Call graph (`--call-graph`)
+
+RLS findings tell you what the *tables* allow. The call graph tells you what the *functions* reach: starting from the exposed entry points (functions the API roles can `EXECUTE`), safegres statically walks each body and lists every **trust boundary** on the way — unscored, because a public `SECURITY DEFINER` calling private functions is the intended pattern (that's how `sign_in` works). The output is a deterministic checklist for human review:
+
+| Code | Boundary |
+|------|----------|
+| CF1 | `SECURITY DEFINER` without a pinned `search_path` (CWE-426) — provable misconfiguration, fix these |
+| CF2 | `SECURITY DEFINER` executable by `anonymous`/PUBLIC — widest blast radius, confirm intent |
+| CG2 | RLS-bypass path — a DEFINER's owner owns (or bypasses RLS on) a table it touches, so RLS does not protect that table on this path |
+| CG3 | Auth-context mutation — a reachable function writes `jwt.claims.*` / `role` |
+| CG1 | Trust hop — execution crosses into a `SECURITY DEFINER` (you are trusting its author's authorization logic) |
+| CG4 | Internal reach — a non-exposed table is reached from a public entry via a DEFINER path |
+| CG5 | Opaque node — dynamic SQL (`EXECUTE`) or an unparseable body; static analysis ends here, audit manually |
+
+```bash
+safegres audit --database mydb --call-graph
+```
+
+```
+call graph — trust boundaries reachable from the exposed surface (unscored; human review)
+  2 entry point(s) → 4 reachable function(s)  |  3 trust hop(s)  1 RLS-bypass  1 auth-context  1 internal-reach  1 opaque
+
+CG2 — RLS-bypass paths (RLS does not protect the table on this path) (1)
+  • fx_cg_private.verify_password → fx_cg_private.users
+      RLS on fx_cg_private.users does not apply on this path — fx_cg_private.verify_password is SECURITY DEFINER running as postgres (BYPASSRLS/superuser)
+      via: fx_cg_public.sign_in → fx_cg_private.verify_password
+```
+
+Bodies are analyzed for `sql` and `plpgsql` functions (via the PL/pgSQL parser); overloads collapse into one node per `schema.name`; unqualified calls resolve to every user function with that name (a conservative over-approximation). JSON output (`--format json`) carries the full graph — nodes, edges, and checklist — sorted stably so it can be snapshotted and diffed in CI.
+
+### Baseline diffing (CI gate for new trust boundaries)
+
+Snapshot the checklist once, commit it, and let CI report anything **new**:
+
+```bash
+safegres audit --write-baseline .safegres-callgraph.json   # snapshot (implies --call-graph)
+safegres audit --baseline .safegres-callgraph.json         # diff: report new/resolved boundaries
+safegres audit --baseline .safegres-callgraph.json --fail-on-new-boundaries   # gate: exit 1 on new
+```
+
+```
+baseline: 1 NEW trust boundary — review and re-baseline to accept:
+  + [CF2] app_public.new_fn
+        SECURITY DEFINER executable by PUBLIC, anonymous — widest blast radius; confirm this is intended
+```
+
+The baseline stores only boundary *identity* (`code` + entry + function + table), so message rewording and path changes between safegres versions never invalidate it. A boundary that disappears is reported as resolved; re-run `--write-baseline` to accept either direction. The diff is also carried in JSON output (`callGraphDiff`).
+
 ## Configuration
 
 safegres is configurable like a linter. Config is discovered by walking up from the current directory: `safegres.config.{ts,js,mjs,cjs}`, `.safegresrc{,.json,.yaml,.yml,.js}`, `safegres.json`, or a `"safegres"` key in package.json (via [confstash](https://github.com/constructive-io/dev-utils/tree/main/packages/confstash)).
@@ -86,15 +187,21 @@ export default defineConfig({
 | Preset | Behavior |
 | --- | --- |
 | `safegres:recommended` | Every rule at its default severity (the no-config behavior) |
-| `safegres:strict` | Coverage gaps escalated (A4 critical, A5 high), `failOn: high` |
-| `safegres:constructive` | Constructive's role model: R1/R2 watch `anonymous`, leak surfaces (A2, A4, A7, P5) critical |
+| `safegres:strict` | Everything escalated; fail-closed findings count 25% toward the score, `failOn: high` |
+| `safegres:constructive` | Auto-resolves exposure from the routing plane; R1/R2 watch `anonymous`; leak surfaces (A2, P5) critical; A3 off (API roles never own tables) |
 | `safegres:minimal` | Structural flags only (A1–A3) — fast CI smoke check |
 
 CLI: `--config <path>`, `--preset <name>`, `--rule CODE=off|severity` (repeatable).
 
 ### Scoring
 
-Every report includes a config-driven score (0–100 + grade): weighted deductions per finding severity (critical 25, high 10, medium 4, low 1, info 0 by default), capped per rule, with any critical finding flooring the grade at C. Tune via `scoring.weights`, `scoring.perRuleWeights`, `scoring.maxDeductionPerRule`, `scoring.gradeBands`, `scoring.floorOnCritical`. Gate CI with `--fail-on-score <n>` / `--fail-on-grade <g>` or `failOn` in config.
+Every report includes a config-driven score (0–100 + grade). The default **density** model normalizes by the exposed surface so large schemas don't saturate to 0/F:
+
+```
+score = 100 · exp(−k · riskPoints / exposedTables)
+```
+
+where `riskPoints` is the severity-weighted sum (critical 25, high 10, medium 4, low 1, info 0) of *exposed, fail-open* findings, and `k` defaults to 0.17 (≈ one critical per 10 exposed tables lands at a C). Non-exposed findings score 0; fail-closed findings score 0 unless `scoring.failClosedWeight` is raised; unknown exposure caps the score (`scoring.unknownExposureCap`, default 80). Any exposed critical floors the grade at C (`scoring.floorOnCritical`). The legacy flat-deduction model is available via `scoring.model: "weighted"`. Tune via `scoring.weights`, `scoring.perRuleWeights`, `scoring.densityK`, `scoring.gradeBands`. Gate CI with `--fail-on-score <n>` / `--fail-on-grade <g>` or `failOn` in config.
 
 ### Other commands
 
@@ -121,6 +228,40 @@ console.log(renderPretty(report));
 console.log(`${report.findings.length} findings`);
 ```
 
+## pgpm projects
+
+For pgpm workspaces, safegres can deploy the workspace into an ephemeral test
+database and audit it — no running database or connection flags required
+(needs the optional peer dependency `pgsql-test`):
+
+```bash
+safegres audit --pgpm            # nearest pgpm module/workspace from cwd
+safegres audit --pgpm ./packages/my-db
+```
+
+Or as a jest test via the `safegres/pgpm-test` entrypoint:
+
+```ts
+import { auditPgpmWorkspace } from 'safegres/pgpm-test';
+
+it('passes the security audit', async () => {
+  const report = await auditPgpmWorkspace();
+  expect(report.score.grade).toBe('A+');
+});
+```
+
+Both discover the project's safegres config (`safegres.config.js`,
+`.safegresrc*`, …) by walking up from the workspace directory. pgpm projects
+usually don't have Constructive routing metadata, so declare the exposed
+surface statically:
+
+```json
+{
+  "extends": "safegres:recommended",
+  "exposure": { "schemas": ["app_public"] }
+}
+```
+
 ---
 
 ## Education and Tutorials

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,27 @@
+/**
+ * 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.
+ */
+import type { FunctionSnapshot } from '../pg/functions';
+export interface NameRef {
+    schema?: string;
+    name: string;
+}
+export interface TableRef extends NameRef {
+    write: boolean;
+}
+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;
+}
+export declare function extractBody(fn: FunctionSnapshot): Promise<ExtractedBody>;

package/callgraph/extract.js

@@ -0,0 +1,170 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractBody = extractBody;
+const libpg_query_1 = require("libpg-query");
+const pgsql_parser_1 = require("pgsql-parser");
+const walk_1 = require("../ast/walk");
+const EMPTY = { calls: [], tables: [], settings: [], opaque: false };
+/** Languages whose bodies we can statically analyze. */
+const ANALYZABLE = new Set(['sql', 'plpgsql']);
+async function extractBody(fn) {
+    if (!ANALYZABLE.has(fn.language)) {
+        if (fn.language === 'internal' || fn.language === 'c')
+            return EMPTY;
+        return { ...EMPTY, opaque: true, opaqueReason: `language "${fn.language}" is not statically analyzable` };
+    }
+    if (fn.language === 'sql') {
+        if (!fn.source || fn.source.trim() === '')
+            return EMPTY;
+        return extractFromSql(fn.source, 'statement');
+    }
+    // plpgsql: parse the full CREATE FUNCTION, then analyze every embedded
+    // SQL expression/statement the PL/pgSQL parser hands back.
+    if (!fn.definition)
+        return { ...EMPTY, opaque: true, opaqueReason: 'no function definition available' };
+    let parsed;
+    try {
+        parsed = await (0, libpg_query_1.parsePlPgSQL)(fn.definition);
+    }
+    catch {
+        return { ...EMPTY, opaque: true, opaqueReason: 'PL/pgSQL body failed to parse' };
+    }
+    const out = { calls: [], tables: [], settings: [], opaque: false };
+    const exprs = [];
+    collectPlpgsql(parsed, exprs, out);
+    for (const e of exprs) {
+        // parseMode 0 = full statement; 3 = assignment (`target := expr` or
+        // `target = expr`) — strip the anchored target so the RHS parses. The
+        // RHS may itself contain `:=` (named arguments), so only the leading
+        // target is removed. Anything else is a bare expression.
+        let q = e.query;
+        if (e.parseMode === 3) {
+            q = q.replace(/^\s*[a-zA-Z_"][\w$".]*(\[[^\]]*\])*\s*:?=\s*/, '');
+        }
+        const sql = e.parseMode === 0 ? q : `SELECT ${q}`;
+        const part = await extractFromSql(sql, 'statement');
+        mergeBody(out, part);
+    }
+    return finalize(out);
+}
+/** Walk the PL/pgSQL JSON tree: collect embedded SQL, flag dynamic EXECUTE. */
+function collectPlpgsql(node, exprs, out) {
+    if (Array.isArray(node)) {
+        for (const item of node)
+            collectPlpgsql(item, exprs, out);
+        return;
+    }
+    if (!node || typeof node !== 'object')
+        return;
+    const rec = node;
+    if (rec.PLpgSQL_stmt_dynexecute) {
+        out.opaque = true;
+        out.opaqueReason = 'dynamic SQL (EXECUTE) — cannot follow statically';
+        // Still walk it: the format() expression itself may call functions.
+    }
+    const expr = rec.PLpgSQL_expr;
+    if (expr && typeof expr.query === 'string') {
+        exprs.push({ query: expr.query, parseMode: typeof expr.parseMode === 'number' ? expr.parseMode : 2 });
+    }
+    for (const value of Object.values(rec))
+        collectPlpgsql(value, exprs, out);
+}
+async function extractFromSql(sql, _mode) {
+    let ast;
+    try {
+        ast = await (0, pgsql_parser_1.parse)(sql);
+    }
+    catch {
+        // Individual fragments can legitimately fail (PL/pgSQL variables in
+        // type positions, etc.) — treat as opaque rather than erroring out.
+        return { ...EMPTY, opaque: true, opaqueReason: 'SQL fragment failed to parse' };
+    }
+    const out = { calls: [], tables: [], settings: [], opaque: false };
+    for (const call of (0, walk_1.findAll)(ast, 'FuncCall')) {
+        const ref = (0, walk_1.funcNameParts)(call);
+        if (ref.name === '<unknown>')
+            continue;
+        out.calls.push(ref);
+        if (ref.name === 'set_config' && (!ref.schema || ref.schema === 'pg_catalog')) {
+            const setting = firstStringArg(call);
+            if (setting)
+                out.settings.push(setting);
+        }
+    }
+    // Write targets: the relation of INSERT/UPDATE/DELETE statements.
+    const writeOids = new Set();
+    for (const tag of ['InsertStmt', 'UpdateStmt', 'DeleteStmt']) {
+        for (const stmt of (0, walk_1.findAll)(ast, tag)) {
+            const rel = stmt.relation;
+            if (rel)
+                writeOids.add(rel);
+        }
+    }
+    for (const rv of (0, walk_1.findAll)(ast, 'RangeVar')) {
+        const name = typeof rv.relname === 'string' ? rv.relname : undefined;
+        if (!name)
+            continue;
+        const schema = typeof rv.schemaname === 'string' ? rv.schemaname : undefined;
+        out.tables.push({ schema, name, write: writeOids.has(rv) });
+    }
+    // SET role / SET session_authorization / SET request.jwt… inside SQL bodies.
+    for (const set of (0, walk_1.findAll)(ast, 'VariableSetStmt')) {
+        const name = typeof set.name === 'string' ? set.name : undefined;
+        if (name)
+            out.settings.push(name.toLowerCase());
+    }
+    return finalize(out);
+}
+function firstStringArg(call) {
+    const args = call.args;
+    if (!Array.isArray(args) || args.length === 0)
+        return null;
+    const first = args[0];
+    const aconst = first.A_Const;
+    const sval = aconst?.sval;
+    const v = sval?.sval;
+    return typeof v === 'string' ? v : null;
+}
+function mergeBody(into, from) {
+    into.calls.push(...from.calls);
+    into.tables.push(...from.tables);
+    into.settings.push(...from.settings);
+    if (from.opaque && !into.opaque) {
+        into.opaque = true;
+        into.opaqueReason = from.opaqueReason;
+    }
+}
+function finalize(body) {
+    const callKeys = new Set();
+    const calls = body.calls.filter((c) => {
+        const k = `${c.schema ?? ''}.${c.name}`;
+        if (callKeys.has(k))
+            return false;
+        callKeys.add(k);
+        return true;
+    });
+    const tableKeys = new Map();
+    for (const t of body.tables) {
+        const k = `${t.schema ?? ''}.${t.name}`;
+        const existing = tableKeys.get(k);
+        if (existing)
+            existing.write = existing.write || t.write;
+        else
+            tableKeys.set(k, { ...t });
+    }
+    return {
+        calls,
+        tables: [...tableKeys.values()],
+        settings: [...new Set(body.settings)],
+        opaque: body.opaque,
+        ...(body.opaqueReason ? { opaqueReason: body.opaqueReason } : {})
+    };
+}

package/callgraph/graph.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Call-graph construction and trust-boundary classification.
+ *
+ * Starting from the exposed entry points (functions the API roles can
+ * EXECUTE), walk what those functions transitively call and touch, and emit
+ * an unscored audit checklist of trust boundaries for human review:
+ *
+ *   CG1  trust hop           — execution crosses into a SECURITY DEFINER
+ *   CG2  RLS-bypass path     — a DEFINER touches a table whose RLS its owner bypasses
+ *   CG3  auth-context change — a reachable function mutates jwt claims / role
+ *   CG4  internal reach      — a non-exposed table is reached via a DEFINER hop
+ *   CG5  opaque node         — dynamic SQL / unparseable body; audit manually
+ *
+ * Plus two provable misconfigurations:
+ *
+ *   CF1  SECURITY DEFINER without a pinned search_path (CWE-426)
+ *   CF2  SECURITY DEFINER executable by anonymous / PUBLIC
+ */
+import type { FunctionSnapshot } from '../pg/functions';
+import type { TableSnapshot } from '../pg/introspect';
+export interface CallGraphOptions {
+    functions: FunctionSnapshot[];
+    tables: TableSnapshot[];
+    /** Exposed schemas; when undefined the exposure surface is unknown. */
+    exposedSchemas?: string[];
+    /** Roles the API connects as. EXECUTE for any of these (or PUBLIC) marks an entry point. */
+    apiRoles: string[];
+}
+export interface CallGraphNode {
+    id: string;
+    schema: string;
+    name: string;
+    securityDefiner: boolean;
+    owner: string;
+    ownerBypassesRls: boolean;
+    searchPathPinned: boolean;
+    language: string;
+    opaque: boolean;
+    opaqueReason?: string;
+    /** Auth-context settings this function writes (jwt claims, role, …). */
+    authSettings: string[];
+    /** Entry-point roles when this node is an entry (EXECUTE-granted API roles). */
+    entryRoles?: string[];
+}
+export interface CallGraphEdge {
+    from: string;
+    to: string;
+    kind: 'call' | 'read' | 'write';
+}
+export type ChecklistCode = 'CG1' | 'CG2' | 'CG3' | 'CG4' | 'CG5' | 'CF1' | 'CF2';
+export interface ChecklistItem {
+    code: ChecklistCode;
+    /** Entry point this boundary is reachable from. */
+    entry: string;
+    /** Call path from the entry to the flagged node, entry first. */
+    path: string[];
+    /** The flagged function. */
+    fn: string;
+    /** The touched table, for CG2/CG4. */
+    table?: string;
+    message: string;
+}
+export interface CallGraphReport {
+    entries: Array<{
+        fn: string;
+        roles: string[];
+        securityDefiner: boolean;
+    }>;
+    nodes: CallGraphNode[];
+    edges: CallGraphEdge[];
+    checklist: ChecklistItem[];
+    stats: {
+        entryPoints: number;
+        reachableFunctions: number;
+        trustHops: number;
+        rlsBypassPaths: number;
+        authContextMutations: number;
+        internalReach: number;
+        opaqueNodes: number;
+    };
+}
+export declare function buildCallGraph(options: CallGraphOptions): Promise<CallGraphReport>;