safegres 1.4.2 → 1.7.0

package/README.md

@@ -39,9 +39,70 @@ Per-field overrides (`--host`, `--port`, `--user`, `--password`, `--database`) a
 | 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) |
 
 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`.
+
+## 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)).
+
+```jsonc
+// .safegresrc.json
+{
+  "extends": "safegres:recommended",
+  "excludeSchemas": ["archive"],
+  "rules": {
+    "A3": "off",            // disable a rule
+    "A5": "high",           // retune a severity
+    "P*": "medium"          // prefix wildcards
+  },
+  "overrides": [
+    { "tables": ["public.audit_*"], "rules": { "A2": "off" } }
+  ],
+  "scoring": { "weights": { "medium": 2 } },
+  "failOn": { "severity": "high", "grade": "B" }
+}
+```
+
+Or typed:
+
+```ts
+// safegres.config.ts
+import { defineConfig } from 'confstash';
+
+export default defineConfig({
+  extends: 'safegres:constructive',
+  rules: { A6: 'low' }
+});
+```
+
+### Presets
+
+| 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: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.
+
+### Other commands
+
+```bash
+safegres doctor        # diagnose config, parser, connection, catalog access, blind spots
+safegres print-config  # show the resolved effective config (--explain for per-key provenance)
+```
+
 ## Library use
 
 ```ts
@@ -94,6 +155,7 @@ Common issues and solutions for pgpm, PostgreSQL, and testing.
 ### 🧪 Testing
 
 * [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [pglite-test](https://github.com/constructive-io/constructive/tree/main/postgres/pglite-test): **🪶 Drop-in pgsql-test replacement backed by PGlite** — in-process Postgres, no server required, instance-per-suite isolation.
 * [pgsql-seed](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-seed): **🌱 PostgreSQL seeding utilities** for CSV, JSON, SQL data loading, and pgpm deployment.
 * [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
 * [graphile-test](https://github.com/constructive-io/constructive/tree/main/graphile/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.

package/checks/anti-patterns.js

@@ -5,9 +5,9 @@ exports.checkSessionUserGating = checkSessionUserGating;
 exports.checkTriviallyPermissive = checkTriviallyPermissive;
 exports.collectFunctionNames = collectFunctionNames;
 exports.parseOrNull = parseOrNull;
+const helpers_1 = require("../ast/helpers");
 const parse_1 = require("../ast/parse");
 const walk_1 = require("../ast/walk");
-const helpers_1 = require("../ast/helpers");
 /**
  * Function names we consider "safe" (stable) for policy predicates, even when
  * pg_proc marks them volatile. These are the well-known Postgres session

package/checks/role-trust.d.ts

@@ -0,0 +1,31 @@
+import type { TableSnapshot } from '../pg/introspect';
+import type { Finding } from '../types';
+/**
+ * Role-trust rules (R-series): findings driven by *who* is granted access,
+ * not just whether coverage exists. R1/R2 take a configurable list of
+ * untrusted roles (e.g. `anonymous`) via rule options; with no roles
+ * configured they are no-ops, so they cost nothing on databases without
+ * such a role model.
+ */
+export interface RoleTrustOptions {
+    /** Role names considered untrusted (exact match). */
+    roles?: string[];
+}
+/**
+ * R1: an untrusted role holds a write privilege on a table. Even with
+ * airtight policies, write access for e.g. `anonymous` is almost always a
+ * grant mistake — unauthenticated actors can INSERT/UPDATE/DELETE.
+ */
+export declare function checkUntrustedRoleWrites(table: TableSnapshot, options?: RoleTrustOptions): Finding[];
+/**
+ * R2: a permissive policy makes write operations pass RLS for an untrusted
+ * role (directly or via PUBLIC). Pairs with R1: the grant is the door, the
+ * policy is the unlocked latch.
+ */
+export declare function checkUntrustedRolePolicies(table: TableSnapshot, options?: RoleTrustOptions): Finding[];
+/**
+ * R3: a table with RLS enabled has grants TO PUBLIC. PUBLIC includes every
+ * present and future role, which silently widens access as roles are added
+ * and defeats role-scoped policy reasoning.
+ */
+export declare function checkPublicGrants(table: TableSnapshot): Finding[];

package/checks/role-trust.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkUntrustedRoleWrites = checkUntrustedRoleWrites;
+exports.checkUntrustedRolePolicies = checkUntrustedRolePolicies;
+exports.checkPublicGrants = checkPublicGrants;
+const WRITE_PRIVILEGES = ['INSERT', 'UPDATE', 'DELETE', 'TRUNCATE'];
+/**
+ * R1: an untrusted role holds a write privilege on a table. Even with
+ * airtight policies, write access for e.g. `anonymous` is almost always a
+ * grant mistake — unauthenticated actors can INSERT/UPDATE/DELETE.
+ */
+function checkUntrustedRoleWrites(table, options = {}) {
+    const untrusted = new Set(options.roles ?? []);
+    if (untrusted.size === 0)
+        return [];
+    const out = [];
+    for (const grant of table.grants) {
+        if (!untrusted.has(grant.role))
+            continue;
+        if (!WRITE_PRIVILEGES.includes(grant.privilege))
+            continue;
+        out.push({
+            code: 'R1',
+            severity: 'critical',
+            category: 'anti-pattern',
+            schema: table.schema,
+            table: table.name,
+            role: grant.role,
+            privilege: grant.privilege,
+            message: `Untrusted role ${grant.role} has ${grant.privilege} grant on ${table.schema}.${table.name}`,
+            hint: `Revoke ${grant.privilege} from ${grant.role} unless unauthenticated writes to this table are intentional (e.g. a public signup or event-ingest table).`
+        });
+    }
+    return out;
+}
+/**
+ * R2: a permissive policy makes write operations pass RLS for an untrusted
+ * role (directly or via PUBLIC). Pairs with R1: the grant is the door, the
+ * policy is the unlocked latch.
+ */
+function checkUntrustedRolePolicies(table, options = {}) {
+    const untrusted = new Set(options.roles ?? []);
+    if (untrusted.size === 0 || !table.rlsEnabled)
+        return [];
+    const out = [];
+    for (const policy of table.policies) {
+        if (!policy.permissive)
+            continue;
+        if (policy.cmd === 'SELECT')
+            continue;
+        const applies = policy.roles.filter((r) => r === 'PUBLIC' || untrusted.has(r));
+        if (applies.length === 0)
+            continue;
+        const via = policy.roles.includes('PUBLIC') ? 'PUBLIC (all roles)' : applies.join(', ');
+        out.push({
+            code: 'R2',
+            severity: 'high',
+            category: 'anti-pattern',
+            schema: table.schema,
+            table: table.name,
+            policy: policy.name,
+            message: `Permissive ${policy.cmd} policy ${policy.name} on ${table.schema}.${table.name} applies to untrusted role via ${via}`,
+            hint: 'Scope the policy TO specific trusted roles instead of PUBLIC/untrusted roles, or verify unauthenticated writes are intended.'
+        });
+    }
+    return out;
+}
+/**
+ * R3: a table with RLS enabled has grants TO PUBLIC. PUBLIC includes every
+ * present and future role, which silently widens access as roles are added
+ * and defeats role-scoped policy reasoning.
+ */
+function checkPublicGrants(table) {
+    if (!table.rlsEnabled)
+        return [];
+    const publicPrivs = table.grants.filter((g) => g.role === 'PUBLIC').map((g) => g.privilege);
+    if (publicPrivs.length === 0)
+        return [];
+    return [
+        {
+            code: 'R3',
+            severity: 'medium',
+            category: 'anti-pattern',
+            schema: table.schema,
+            table: table.name,
+            role: 'PUBLIC',
+            message: `Table ${table.schema}.${table.name} has RLS enabled but grants ${publicPrivs.join(', ')} to PUBLIC`,
+            hint: 'Grant to specific roles instead of PUBLIC — PUBLIC includes every current and future role, including untrusted ones.'
+        }
+    ];
+}

package/cli/audit.js

@@ -1,12 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const logger_1 = require("@pgpmjs/logger");
-const pg_1 = require("pg");
-const pg_env_1 = require("pg-env");
 const audit_1 = require("../commands/audit");
+const loader_1 = require("../config/loader");
 const json_1 = require("../report/json");
 const pretty_1 = require("../report/pretty");
+const score_1 = require("../score/score");
 const types_1 = require("../types");
+const shared_1 = require("./shared");
 const log = new logger_1.Logger('safegres');
 const usage = `
 safegres audit — pure-PostgreSQL RLS auditor
@@ -21,6 +22,12 @@ Connection (priority order, top wins):
   --password <pw>          PostgreSQL password    (else PGPASSWORD,default password)
   --database <db>          PostgreSQL database    (else PGDATABASE,default postgres)
 
+Configuration:
+  --config <path>          Explicit config file (else discovered: safegres.config.{ts,js,mjs,cjs},
+                           .safegresrc{,.json,.yaml,.yml,.js}, safegres.json, package.json "safegres")
+  --preset <name>          Apply a built-in preset (recommended|strict|constructive|minimal)
+  --rule <CODE=SETTING>    Retune a rule (repeatable), e.g. --rule A3=off --rule A5=high
+
 Audit options:
   --schemas <csv>          Limit to these schemas (default: all non-system)
   --exclude-schemas <csv>  Skip these schemas
@@ -29,35 +36,12 @@ Audit options:
   --format <fmt>           "pretty" (default) | "json" | "json-pretty"
   --fail-on <severity>     Exit non-zero if any finding >= severity
                            (critical|high|medium|low|info; default: none)
+  --fail-on-score <n>      Exit non-zero if the score is below n (0-100)
+  --fail-on-grade <g>      Exit non-zero if the grade is below g (A+|A|B|C|D)
   --skip-ast               Skip AST-level anti-pattern checks (faster)
   --no-color               Disable ANSI colors in pretty output
   --help, -h               Show this help message
 `;
-function csvList(value) {
-    if (typeof value !== 'string' || value.length === 0)
-        return undefined;
-    return value
-        .split(',')
-        .map((p) => p.trim())
-        .filter(Boolean);
-}
-function buildClient(argv) {
-    if (typeof argv.connection === 'string' && argv.connection.length > 0) {
-        return new pg_1.Client({ connectionString: argv.connection });
-    }
-    const overrides = {};
-    if (typeof argv.host === 'string')
-        overrides.host = argv.host;
-    if (typeof argv.port === 'number')
-        overrides.port = argv.port;
-    if (typeof argv.user === 'string')
-        overrides.user = argv.user;
-    if (typeof argv.password === 'string')
-        overrides.password = argv.password;
-    if (typeof argv.database === 'string')
-        overrides.database = argv.database;
-    return new pg_1.Client((0, pg_env_1.getPgEnvOptions)(overrides));
-}
 exports.default = async (argv, _prompter, _options) => {
     if (argv.help || argv.h) {
         process.stdout.write(usage);
@@ -65,15 +49,17 @@ exports.default = async (argv, _prompter, _options) => {
     }
     // minimist parses `--no-color` as `color: false`.
     const colorEnabled = argv.color !== false;
-    const client = buildClient(argv);
+    const { config } = (0, loader_1.loadConfig)((0, shared_1.configParamsFromArgv)(argv));
+    const client = (0, shared_1.buildClient)(argv);
     await client.connect();
     try {
         const report = await (0, audit_1.audit)(client, {
-            schemas: csvList(argv.schemas),
-            excludeSchemas: csvList(argv['exclude-schemas']),
-            includeRoles: csvList(argv.roles),
-            excludeRoles: csvList(argv['exclude-roles']),
-            skipAstChecks: argv['skip-ast'] === true
+            schemas: (0, shared_1.csvList)(argv.schemas),
+            excludeSchemas: (0, shared_1.csvList)(argv['exclude-schemas']),
+            includeRoles: (0, shared_1.csvList)(argv.roles),
+            excludeRoles: (0, shared_1.csvList)(argv['exclude-roles']),
+            skipAstChecks: argv['skip-ast'] === true,
+            config
         });
         const fmt = typeof argv.format === 'string' ? argv.format : 'pretty';
         let output;
@@ -93,16 +79,26 @@ exports.default = async (argv, _prompter, _options) => {
         }
         process.stdout.write(output);
         process.stdout.write('\n');
-        const failOn = typeof argv['fail-on'] === 'string' ? argv['fail-on'] : undefined;
-        if (failOn) {
-            if (!(failOn in types_1.SEVERITY_ORDER)) {
-                log.error(`Unknown --fail-on severity: ${failOn}`);
+        const failOnSeverity = typeof argv['fail-on'] === 'string' ? argv['fail-on'] : config.failOn?.severity;
+        if (failOnSeverity) {
+            if (!(failOnSeverity in types_1.SEVERITY_ORDER)) {
+                log.error(`Unknown --fail-on severity: ${failOnSeverity}`);
                 process.exit(2);
             }
-            if (report.findings.some((f) => (0, types_1.meetsThreshold)(f.severity, failOn))) {
+            if (report.findings.some((f) => (0, types_1.meetsThreshold)(f.severity, failOnSeverity))) {
                 process.exit(1);
             }
         }
+        const failOnScore = typeof argv['fail-on-score'] === 'number' ? argv['fail-on-score'] : config.failOn?.score;
+        if (failOnScore != null && report.score && report.score.value < failOnScore) {
+            log.error(`score ${report.score.value} is below --fail-on-score ${failOnScore}`);
+            process.exit(1);
+        }
+        const failOnGrade = typeof argv['fail-on-grade'] === 'string' ? argv['fail-on-grade'] : config.failOn?.grade;
+        if (failOnGrade && report.score && !(0, score_1.meetsGrade)(report.score.grade, failOnGrade)) {
+            log.error(`grade ${report.score.grade} is below --fail-on-grade ${failOnGrade}`);
+            process.exit(1);
+        }
     }
     finally {
         await client.end();

package/cli/commands.js

@@ -7,6 +7,8 @@ exports.commands = void 0;
 const logger_1 = require("@pgpmjs/logger");
 const inquirerer_1 = require("inquirerer");
 const audit_1 = __importDefault(require("./audit"));
+const doctor_1 = __importDefault(require("./doctor"));
+const print_config_1 = __importDefault(require("./print-config"));
 const log = new logger_1.Logger('safegres');
 const usage = `
 safegres — pure-PostgreSQL RLS auditor
@@ -16,12 +18,16 @@ Usage:
 
 Commands:
   audit           Audit grants, RLS flags, policy coverage, and anti-patterns
+  doctor          Diagnose environment, connection, and configuration
+  print-config    Show the resolved effective configuration
   help            Show this help message
 
 Run \`safegres <command> --help\` for command-specific options.
 `;
 const commandMap = {
-    audit: audit_1.default
+    audit: audit_1.default,
+    doctor: doctor_1.default,
+    'print-config': print_config_1.default
 };
 const commands = async (argv, prompter, options) => {
     const { first: command, newArgv } = (0, inquirerer_1.extractFirst)(argv);

package/cli/doctor.d.ts

@@ -0,0 +1,3 @@
+import { CLIOptions, Inquirerer, ParsedArgs } from 'inquirerer';
+declare const _default: (argv: ParsedArgs, _prompter: Inquirerer, _options: CLIOptions) => Promise<void>;
+export default _default;

package/cli/doctor.js

@@ -0,0 +1,72 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const yanse_1 = __importDefault(require("yanse"));
+const doctor_1 = require("../commands/doctor");
+const shared_1 = require("./shared");
+const usage = `
+safegres doctor — diagnose the environment, connection, and configuration
+
+  safegres doctor [OPTIONS]
+
+Connection (same flags as \`safegres audit\`):
+  --connection <url>       Full PostgreSQL connection string
+  --host / --port / --user / --password / --database
+
+Configuration:
+  --config <path>          Explicit config file
+  --preset <name>          Apply a built-in preset
+  --rule <CODE=SETTING>    Retune a rule (repeatable)
+
+Options:
+  --no-color               Disable ANSI colors
+  --help, -h               Show this help message
+
+Checks: config discovery & rule validation, pgsql-parser availability,
+connection, catalog access (pg_policy), audit blind spots (BYPASSRLS),
+and whether any tables actually have RLS enabled.
+`;
+const STATUS_LABEL = {
+    ok: 'OK  ',
+    warn: 'WARN',
+    fail: 'FAIL'
+};
+exports.default = async (argv, _prompter, _options) => {
+    if (argv.help || argv.h) {
+        process.stdout.write(usage);
+        return;
+    }
+    const colorEnabled = argv.color !== false;
+    const paint = (status, s) => {
+        if (!colorEnabled)
+            return s;
+        if (status === 'ok')
+            return yanse_1.default.green(s);
+        if (status === 'warn')
+            return yanse_1.default.yellow(s);
+        return yanse_1.default.bold(yanse_1.default.red(s));
+    };
+    let client = (0, shared_1.buildClient)(argv);
+    try {
+        await client.connect();
+    }
+    catch {
+        client = null;
+    }
+    try {
+        const report = await (0, doctor_1.doctor)(client, (0, shared_1.configParamsFromArgv)(argv));
+        for (const check of report.checks) {
+            process.stdout.write(`[${paint(check.status, STATUS_LABEL[check.status])}] ${check.name.padEnd(12)} ${check.detail}\n`);
+        }
+        process.stdout.write('\n');
+        process.stdout.write(report.ok ? 'doctor: all checks passed\n' : 'doctor: some checks failed\n');
+        if (!report.ok)
+            process.exit(1);
+    }
+    finally {
+        if (client)
+            await client.end();
+    }
+};

package/cli/print-config.d.ts

@@ -0,0 +1,3 @@
+import { CLIOptions, Inquirerer, ParsedArgs } from 'inquirerer';
+declare const _default: (argv: ParsedArgs, _prompter: Inquirerer, _options: CLIOptions) => Promise<void>;
+export default _default;

package/cli/print-config.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const loader_1 = require("../config/loader");
+const resolve_1 = require("../config/resolve");
+const registry_1 = require("../rules/registry");
+const shared_1 = require("./shared");
+const usage = `
+safegres print-config — show the resolved effective configuration
+
+  safegres print-config [OPTIONS]
+
+Options:
+  --config <path>          Explicit config file
+  --preset <name>          Apply a built-in preset
+  --rule <CODE=SETTING>    Retune a rule (repeatable)
+  --explain                Show per-key provenance (which layer set each value)
+  --help, -h               Show this help message
+`;
+exports.default = async (argv, _prompter, _options) => {
+    if (argv.help || argv.h) {
+        process.stdout.write(usage);
+        return;
+    }
+    const params = (0, shared_1.configParamsFromArgv)(argv);
+    if (argv.explain === true) {
+        const loader = (0, loader_1.safegresConfigLoader)();
+        const explained = loader.explainSync({
+            configFile: params.configFile,
+            overrides: params.overrides
+        });
+        for (const e of explained) {
+            process.stdout.write(`${e.path} = ${JSON.stringify(e.value)}  (${e.source}: ${e.origin})\n`);
+        }
+        return;
+    }
+    const { config, filepath, isEmpty } = (0, loader_1.loadConfig)(params);
+    const resolved = (0, resolve_1.resolveRules)(config);
+    const effectiveRules = {};
+    for (const rule of registry_1.RULES) {
+        const r = resolved.rules.get(rule.code);
+        effectiveRules[rule.code] = r.enabled ? r.severity : 'off';
+    }
+    process.stdout.write(`${JSON.stringify({
+        source: filepath ?? (isEmpty ? '(no config file — defaults)' : undefined),
+        config,
+        effectiveRules
+    }, null, 2)}\n`);
+};

package/cli/shared.d.ts

@@ -0,0 +1,13 @@
+import type { ParsedArgs } from 'inquirerer';
+import { Client } from 'pg';
+import type { LoadConfigParams } from '../config/loader';
+import type { RulesConfig } from '../config/types';
+export declare function csvList(value: unknown): string[] | undefined;
+export declare function buildClient(argv: ParsedArgs): Client;
+/**
+ * Parse repeatable `--rule CODE=SETTING` flags into a RulesConfig, e.g.
+ * `--rule A3=off --rule A5=high --rule 'P*'=off`.
+ */
+export declare function parseRuleFlags(value: unknown): RulesConfig | undefined;
+/** Build config-loading params from shared CLI flags. */
+export declare function configParamsFromArgv(argv: ParsedArgs): LoadConfigParams;

package/cli/shared.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.csvList = csvList;
+exports.buildClient = buildClient;
+exports.parseRuleFlags = parseRuleFlags;
+exports.configParamsFromArgv = configParamsFromArgv;
+const pg_1 = require("pg");
+const pg_env_1 = require("pg-env");
+function csvList(value) {
+    if (typeof value !== 'string' || value.length === 0)
+        return undefined;
+    return value
+        .split(',')
+        .map((p) => p.trim())
+        .filter(Boolean);
+}
+function buildClient(argv) {
+    if (typeof argv.connection === 'string' && argv.connection.length > 0) {
+        return new pg_1.Client({ connectionString: argv.connection });
+    }
+    const overrides = {};
+    if (typeof argv.host === 'string')
+        overrides.host = argv.host;
+    if (typeof argv.port === 'number')
+        overrides.port = argv.port;
+    if (typeof argv.user === 'string')
+        overrides.user = argv.user;
+    if (typeof argv.password === 'string')
+        overrides.password = argv.password;
+    if (typeof argv.database === 'string')
+        overrides.database = argv.database;
+    return new pg_1.Client((0, pg_env_1.getPgEnvOptions)(overrides));
+}
+/**
+ * Parse repeatable `--rule CODE=SETTING` flags into a RulesConfig, e.g.
+ * `--rule A3=off --rule A5=high --rule 'P*'=off`.
+ */
+function parseRuleFlags(value) {
+    if (value == null)
+        return undefined;
+    const entries = Array.isArray(value) ? value : [value];
+    const rules = {};
+    for (const entry of entries) {
+        if (typeof entry !== 'string')
+            continue;
+        const eq = entry.indexOf('=');
+        if (eq <= 0) {
+            throw new Error(`Invalid --rule "${entry}": expected CODE=off|<severity>.`);
+        }
+        const code = entry.slice(0, eq).trim();
+        const setting = entry.slice(eq + 1).trim();
+        rules[code] = setting;
+    }
+    return Object.keys(rules).length > 0 ? rules : undefined;
+}
+/** Build config-loading params from shared CLI flags. */
+function configParamsFromArgv(argv) {
+    const cliRules = parseRuleFlags(argv.rule);
+    const overrides = {};
+    if (cliRules)
+        overrides.rules = cliRules;
+    return {
+        configFile: typeof argv.config === 'string' ? argv.config : undefined,
+        preset: typeof argv.preset === 'string' ? argv.preset : undefined,
+        overrides: Object.keys(overrides).length > 0 ? overrides : undefined
+    };
+}

package/commands/audit.d.ts

@@ -3,6 +3,7 @@
  *
  * Ingests a catalog snapshot, runs every check, and returns a structured report.
  */
+import type { SafegresConfig } from '../config/types';
 import { type IntrospectOptions, type QueryExecutor } from '../pg/introspect';
 import type { Report } from '../types';
 export interface AuditOptions extends IntrospectOptions {
@@ -15,5 +16,12 @@ export interface AuditOptions extends IntrospectOptions {
      * that only want grants + RLS-flag + coverage findings.
      */
     skipAstChecks?: boolean;
+    /**
+     * Merged safegres configuration (rules, overrides, scoring). Rule settings
+     * filter and retune findings; scoring settings drive the report score.
+     * Connection-independent option fields (`schemas`, `roles`, …) present on
+     * the config are used as fallbacks for the corresponding AuditOptions.
+     */
+    config?: SafegresConfig;
 }
 export declare function audit(client: QueryExecutor, options?: AuditOptions): Promise<Report>;

package/commands/audit.js

@@ -6,25 +6,31 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.audit = audit;
+const anti_patterns_1 = require("../checks/anti-patterns");
 const coverage_1 = require("../checks/coverage");
 const rls_flags_1 = require("../checks/rls-flags");
-const anti_patterns_1 = require("../checks/anti-patterns");
+const role_trust_1 = require("../checks/role-trust");
+const resolve_1 = require("../config/resolve");
 const introspect_1 = require("../pg/introspect");
 const proc_1 = require("../pg/proc");
 const roles_1 = require("../pg/roles");
+const score_1 = require("../score/score");
 const types_1 = require("../types");
 const version_1 = require("../version");
 async function audit(client, options = {}) {
     const exec = (0, introspect_1.asExecutor)(client);
+    const config = options.config ?? {};
+    const resolved = (0, resolve_1.resolveRules)(config);
+    const skipAst = options.skipAstChecks || (0, resolve_1.allAstRulesDisabled)(resolved);
     // Resolve role set.
     const allRoles = await (0, roles_1.listAuditableRoles)(exec);
-    const resolution = (0, roles_1.resolveRoles)(allRoles, options.includeRoles, options.excludeRoles);
+    const resolution = (0, roles_1.resolveRoles)(allRoles, options.includeRoles ?? config.roles, options.excludeRoles ?? config.excludeRoles);
     const snapshot = await (0, introspect_1.introspectTables)(exec, {
-        schemas: options.schemas,
-        excludeSchemas: options.excludeSchemas,
+        schemas: options.schemas ?? config.schemas,
+        excludeSchemas: options.excludeSchemas ?? config.excludeSchemas,
         roles: resolution.roles
     });
-    const findings = [];
+    let findings = [];
     for (const table of snapshot) {
         // --- RLS flags (structural) ---
         const a1 = (0, rls_flags_1.checkRlsEnabledNoPolicies)(table);
@@ -39,17 +45,24 @@ async function audit(client, options = {}) {
         // --- Grant-vs-policy coverage ---
         findings.push(...(0, coverage_1.checkCoverageGaps)(table));
         findings.push(...(0, coverage_1.checkUpdateWithCheckCoverage)(table));
+        // --- Role-trust (options-driven; per-table overrides can retune roles) ---
+        const tableRules = (0, resolve_1.rulesForTable)(resolved, table.schema, table.name);
+        findings.push(...(0, role_trust_1.checkUntrustedRoleWrites)(table, tableRules.get('R1')?.options));
+        findings.push(...(0, role_trust_1.checkUntrustedRolePolicies)(table, tableRules.get('R2')?.options));
+        findings.push(...(0, role_trust_1.checkPublicGrants)(table));
         // --- AST-level anti-patterns ---
-        if (!options.skipAstChecks) {
+        if (!skipAst) {
             findings.push(...(await auditTableAst(exec, table)));
         }
     }
+    findings = (0, resolve_1.applyRulesToFindings)(resolved, findings);
     findings.sort(compareFindings);
     return {
         version: version_1.version,
         generatedAt: new Date().toISOString(),
         summary: (0, types_1.summarize)(findings),
-        findings
+        findings,
+        score: (0, score_1.computeScore)(findings, config.scoring)
     };
 }
 async function auditTableAst(exec, table) {