safegres 1.7.0 → 1.8.0

package/README.md

@@ -28,25 +28,69 @@ Per-field overrides (`--host`, `--port`, `--user`, `--password`, `--database`) a
 
 ## 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.
+
 ## 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 +130,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 +171,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/checks/anti-patterns.d.ts

@@ -21,16 +21,22 @@ export declare function checkVolatileFunctions(table: TableSnapshot, expr: PgAst
  */
 export declare function checkSessionUserGating(table: TableSnapshot, expr: PgAstNode, policyName: string): Finding[];
 /**
- * Anti-pattern A7: trivially-permissive policy body.
+ * Anti-patterns A7 / A8: trivially-permissive policy body.
  *
- * A permissive policy whose body is the literal `true` (and has no tightening
- * `WITH CHECK` clause) adds zero security — it's equivalent to not having RLS
- * at all for the covered command. This is different from an intentional
- * *restrictive* `true` (which would require all rows to satisfy it). We only
- * flag `permissive = true` here because Postgres defaults to PERMISSIVE and
- * `USING (true)` is the most common accidental "fail-open" shape.
+ * A permissive policy whose body is the literal `true` adds zero security —
+ * it's equivalent to not having RLS at all for the covered command. This is
+ * different from an intentional *restrictive* `true` (which would require
+ * all rows to satisfy it). We only flag `permissive = true` here because
+ * Postgres defaults to PERMISSIVE and `USING (true)` is the most common
+ * accidental "fail-open" shape.
  *
- * Severity: HIGH — any auditor should see this as RLS-not-actually-enforced.
+ * The verb matters enormously:
+ *   - A7 (critical): a WRITE verb (INSERT/UPDATE/DELETE/ALL) with literal
+ *     `true` lets every applicable role mutate every row — and, because
+ *     permissive policies OR together, it silently defeats any carefully
+ *     scoped policies on the same table.
+ *   - A8 (low): a SELECT-only `USING (true)` is the standard public-read
+ *     reference-table pattern; flag it for confirmation, not alarm.
  *
  * Input: the parsed USING and WITH CHECK ASTs (may be null if empty).
  */

package/checks/anti-patterns.js

@@ -139,16 +139,22 @@ function checkSessionUserGating(table, expr, policyName) {
     return out;
 }
 /**
- * Anti-pattern A7: trivially-permissive policy body.
+ * Anti-patterns A7 / A8: trivially-permissive policy body.
  *
- * A permissive policy whose body is the literal `true` (and has no tightening
- * `WITH CHECK` clause) adds zero security — it's equivalent to not having RLS
- * at all for the covered command. This is different from an intentional
- * *restrictive* `true` (which would require all rows to satisfy it). We only
- * flag `permissive = true` here because Postgres defaults to PERMISSIVE and
- * `USING (true)` is the most common accidental "fail-open" shape.
+ * A permissive policy whose body is the literal `true` adds zero security —
+ * it's equivalent to not having RLS at all for the covered command. This is
+ * different from an intentional *restrictive* `true` (which would require
+ * all rows to satisfy it). We only flag `permissive = true` here because
+ * Postgres defaults to PERMISSIVE and `USING (true)` is the most common
+ * accidental "fail-open" shape.
  *
- * Severity: HIGH — any auditor should see this as RLS-not-actually-enforced.
+ * The verb matters enormously:
+ *   - A7 (critical): a WRITE verb (INSERT/UPDATE/DELETE/ALL) with literal
+ *     `true` lets every applicable role mutate every row — and, because
+ *     permissive policies OR together, it silently defeats any carefully
+ *     scoped policies on the same table.
+ *   - A8 (low): a SELECT-only `USING (true)` is the standard public-read
+ *     reference-table pattern; flag it for confirmation, not alarm.
  *
  * Input: the parsed USING and WITH CHECK ASTs (may be null if empty).
  */
@@ -181,17 +187,30 @@ function checkTriviallyPermissive(table, policy, usingAst, withCheckAst) {
     if (trivialClauses.length !== presentClauses.length)
         return null;
     const clauseList = trivialClauses.join(' and ');
-    return {
-        code: 'A7',
-        severity: 'high',
-        category: 'anti-pattern',
-        schema: table.schema,
-        table: table.name,
-        policy: policy.name,
-        message: `Policy "${policy.name}" on ${table.schema}.${table.name} is trivially permissive (${clauseList} = true)`,
-        hint: 'A permissive policy whose body is the literal `true` imposes no constraint. Either tighten the predicate (reference the authenticated user / membership) or drop the policy and use a GRANT REVOKE model.',
-        context: { cmd: policy.cmd, clauses: trivialClauses }
-    };
+    const isWrite = policy.cmd !== 'SELECT';
+    return isWrite
+        ? {
+            code: 'A7',
+            severity: 'critical',
+            category: 'anti-pattern',
+            schema: table.schema,
+            table: table.name,
+            policy: policy.name,
+            message: `Policy "${policy.name}" (FOR ${policy.cmd}) on ${table.schema}.${table.name} is trivially permissive (${clauseList} = true) — every applicable role can write every row`,
+            hint: 'Permissive policies OR together, so a literal-true write policy defeats every scoped policy on the table. Tighten the predicate or drop the policy.',
+            context: { cmd: policy.cmd, clauses: trivialClauses }
+        }
+        : {
+            code: 'A8',
+            severity: 'low',
+            category: 'anti-pattern',
+            schema: table.schema,
+            table: table.name,
+            policy: policy.name,
+            message: `Policy "${policy.name}" (FOR SELECT) on ${table.schema}.${table.name} is trivially permissive (${clauseList} = true) — all rows readable by applicable roles`,
+            hint: 'This is the standard public-read reference-table pattern. Confirm the table holds no per-tenant data; otherwise tighten the predicate.',
+            context: { cmd: policy.cmd, clauses: trivialClauses }
+        };
 }
 /**
  * Walk a policy expression, collecting unique function `(schema, name)` tuples

package/cli/audit.js

@@ -9,12 +9,32 @@ const score_1 = require("../score/score");
 const types_1 = require("../types");
 const shared_1 = require("./shared");
 const log = new logger_1.Logger('safegres');
+/**
+ * `--pgpm` mode needs the optional peer dependency `pgsql-test`, so the
+ * helper module is loaded lazily with a friendly error when it's missing.
+ */
+function importPgpmTest() {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        return require('../pgpm-test');
+    }
+    catch (err) {
+        if (err.code === 'MODULE_NOT_FOUND') {
+            log.error('--pgpm requires the optional peer dependency "pgsql-test" — install it (e.g. `npm i -D pgsql-test`) and retry');
+            process.exit(2);
+        }
+        throw err;
+    }
+}
 const usage = `
 safegres audit — pure-PostgreSQL RLS auditor
 
   safegres audit [OPTIONS]
 
 Connection (priority order, top wins):
+  --pgpm [dir]             No connection needed: deploy the pgpm workspace at
+                           [dir] (default: nearest from cwd) into an ephemeral
+                           test database and audit it (requires pgsql-test)
   --connection <url>       Full PostgreSQL connection string
   --host <host>            PostgreSQL host        (else PGHOST,    default localhost)
   --port <port>            PostgreSQL port        (else PGPORT,    default 5432)
@@ -28,6 +48,11 @@ Configuration:
   --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
 
+Exposure (what the score is computed against):
+  --exposure-schemas <csv> Declare the API-exposed schemas; findings outside
+                           them become unscored internal advisories
+  --exposed-only           Hide internal (non-exposed) findings from output
+
 Audit options:
   --schemas <csv>          Limit to these schemas (default: all non-system)
   --exclude-schemas <csv>  Skip these schemas
@@ -49,58 +74,75 @@ exports.default = async (argv, _prompter, _options) => {
     }
     // minimist parses `--no-color` as `color: false`.
     const colorEnabled = argv.color !== false;
-    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: (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;
-        switch (fmt) {
-            case 'json':
-                output = (0, json_1.renderJson)(report);
-                break;
-            case 'json-pretty':
-                output = (0, json_1.renderJson)(report, { pretty: true });
-                break;
-            case 'pretty':
-                output = (0, pretty_1.renderPretty)(report, { color: colorEnabled });
-                break;
-            default:
-                log.error(`Unknown --format: ${fmt}`);
-                process.exit(2);
+    const pgpmCwd = typeof argv.pgpm === 'string' ? argv.pgpm : undefined;
+    const { config } = (0, loader_1.loadConfig)({ cwd: pgpmCwd, ...(0, shared_1.configParamsFromArgv)(argv) });
+    const exposureSchemas = (0, shared_1.csvList)(argv['exposure-schemas']);
+    const auditOptions = {
+        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,
+        exposure: exposureSchemas
+            ? { ...config.exposure, schemas: exposureSchemas }
+            : undefined,
+        config
+    };
+    let report;
+    if (argv.pgpm) {
+        const { auditPgpmWorkspace } = importPgpmTest();
+        report = await auditPgpmWorkspace({ ...auditOptions, cwd: pgpmCwd });
+    }
+    else {
+        const client = (0, shared_1.buildClient)(argv);
+        await client.connect();
+        try {
+            report = await (0, audit_1.audit)(client, auditOptions);
         }
-        process.stdout.write(output);
-        process.stdout.write('\n');
-        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, failOnSeverity))) {
-                process.exit(1);
-            }
+        finally {
+            await client.end();
         }
-        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);
+    }
+    if (argv['exposed-only'] === true) {
+        report.findings = report.findings.filter((f) => f.exposed !== false);
+        report.summary = (0, types_1.summarize)(report.findings);
+    }
+    const fmt = typeof argv.format === 'string' ? argv.format : 'pretty';
+    let output;
+    switch (fmt) {
+        case 'json':
+            output = (0, json_1.renderJson)(report);
+            break;
+        case 'json-pretty':
+            output = (0, json_1.renderJson)(report, { pretty: true });
+            break;
+        case 'pretty':
+            output = (0, pretty_1.renderPretty)(report, { color: colorEnabled });
+            break;
+        default:
+            log.error(`Unknown --format: ${fmt}`);
+            process.exit(2);
+    }
+    process.stdout.write(output);
+    process.stdout.write('\n');
+    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);
         }
-        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}`);
+        if (report.findings.some((f) => (0, types_1.meetsThreshold)(f.severity, failOnSeverity))) {
             process.exit(1);
         }
     }
-    finally {
-        await client.end();
+    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);
     }
 };

package/commands/audit.d.ts

@@ -3,7 +3,7 @@
  *
  * Ingests a catalog snapshot, runs every check, and returns a structured report.
  */
-import type { SafegresConfig } from '../config/types';
+import type { ExposureConfig, SafegresConfig } from '../config/types';
 import { type IntrospectOptions, type QueryExecutor } from '../pg/introspect';
 import type { Report } from '../types';
 export interface AuditOptions extends IntrospectOptions {
@@ -16,6 +16,11 @@ export interface AuditOptions extends IntrospectOptions {
      * that only want grants + RLS-flag + coverage findings.
      */
     skipAstChecks?: boolean;
+    /**
+     * The exposed API surface. Overrides `config.exposure` when provided.
+     * Findings on non-exposed schemas contribute nothing to the score.
+     */
+    exposure?: ExposureConfig;
     /**
      * Merged safegres configuration (rules, overrides, scoring). Rule settings
      * filter and retune findings; scoring settings drive the report score.

package/commands/audit.js

@@ -11,9 +11,11 @@ const coverage_1 = require("../checks/coverage");
 const rls_flags_1 = require("../checks/rls-flags");
 const role_trust_1 = require("../checks/role-trust");
 const resolve_1 = require("../config/resolve");
+const exposure_1 = require("../pg/exposure");
 const introspect_1 = require("../pg/introspect");
 const proc_1 = require("../pg/proc");
 const roles_1 = require("../pg/roles");
+const registry_1 = require("../rules/registry");
 const score_1 = require("../score/score");
 const types_1 = require("../types");
 const version_1 = require("../version");
@@ -25,11 +27,16 @@ async function audit(client, options = {}) {
     // Resolve role set.
     const allRoles = await (0, roles_1.listAuditableRoles)(exec);
     const resolution = (0, roles_1.resolveRoles)(allRoles, options.includeRoles ?? config.roles, options.excludeRoles ?? config.excludeRoles);
+    const exposure = await (0, exposure_1.resolveExposure)(exec, options.exposure ?? config.exposure);
+    const exposedSchemas = new Set(exposure.schemas);
     const snapshot = await (0, introspect_1.introspectTables)(exec, {
         schemas: options.schemas ?? config.schemas,
         excludeSchemas: options.excludeSchemas ?? config.excludeSchemas,
         roles: resolution.roles
     });
+    const exposedTables = exposure.known
+        ? snapshot.filter((t) => exposedSchemas.has(t.schema)).length
+        : snapshot.length;
     let findings = [];
     for (const table of snapshot) {
         // --- RLS flags (structural) ---
@@ -56,13 +63,55 @@ async function audit(client, options = {}) {
         }
     }
     findings = (0, resolve_1.applyRulesToFindings)(resolved, findings);
+    // Stamp direction (from the registry) and exposure on every finding.
+    const publicRead = config.public?.read ?? [];
+    for (const f of findings) {
+        const meta = registry_1.RULES_BY_CODE.get(f.code);
+        if (meta && f.direction === undefined)
+            f.direction = meta.direction;
+        if (exposure.known && f.schema)
+            f.exposed = exposedSchemas.has(f.schema);
+        // Declared-public reads: an open SELECT on a table listed in
+        // `public.read` is intent, not a finding — acknowledge it (info,
+        // excluded from the score). Undeclared open reads stay scored.
+        if (f.code === 'A8' && f.schema && f.table
+            && publicRead.some((p) => (0, resolve_1.matchTablePattern)(p, `${f.schema}.${f.table}`))) {
+            f.acknowledged = true;
+            f.severity = 'info';
+            f.message += ' — declared public read (public.read)';
+            f.hint = 'This table is declared in `public.read`, so the open read is treated as intentional and does not affect the score.';
+        }
+    }
+    // W1: no exposure surface — the whole database is assumed reachable.
+    if (!exposure.known && resolved.rules.get('W1')?.enabled !== false) {
+        findings.push({
+            code: 'W1',
+            severity: resolved.rules.get('W1')?.severity ?? 'medium',
+            category: 'meta',
+            direction: 'neutral',
+            message: 'No exposure surface configured — the audit assumes the entire database is reachable and the score is capped',
+            hint: 'Declare `exposure.schemas` (or use `exposure.resolver: "constructive"` on a Constructive database) so the score reflects what the exposed APIs can actually reach.'
+        });
+    }
     findings.sort(compareFindings);
+    const exposureReport = {
+        known: exposure.known,
+        source: exposure.source,
+        schemas: exposure.schemas,
+        ...(exposure.roles ? { roles: exposure.roles } : {}),
+        exposedTables,
+        totalTables: snapshot.length
+    };
     return {
         version: version_1.version,
         generatedAt: new Date().toISOString(),
         summary: (0, types_1.summarize)(findings),
         findings,
-        score: (0, score_1.computeScore)(findings, config.scoring)
+        score: (0, score_1.computeScore)(findings, config.scoring, {
+            exposedTables,
+            exposureKnown: exposure.known
+        }),
+        exposure: exposureReport
     };
 }
 async function auditTableAst(exec, table) {

package/commands/doctor.js

@@ -9,12 +9,17 @@ exports.doctor = doctor;
 const parse_1 = require("../ast/parse");
 const loader_1 = require("../config/loader");
 const resolve_1 = require("../config/resolve");
+const exposure_1 = require("../pg/exposure");
 const introspect_1 = require("../pg/introspect");
 async function doctor(client, options = {}) {
     const checks = [];
+    let exposureConfig;
+    let publicRead = [];
     // --- configuration ---
     try {
         const loaded = (0, loader_1.loadConfig)(options);
+        exposureConfig = loaded.config.exposure;
+        publicRead = loaded.config.public?.read ?? [];
         if (loaded.isEmpty) {
             checks.push({
                 name: 'config',
@@ -126,6 +131,49 @@ async function doctor(client, options = {}) {
     catch (err) {
         checks.push({ name: 'rls', status: 'warn', detail: err.message });
     }
+    // --- exposure surface ---
+    try {
+        const exposure = await (0, exposure_1.resolveExposure)(exec, exposureConfig);
+        if (exposure.known) {
+            checks.push({
+                name: 'exposure',
+                status: 'ok',
+                detail: `${exposure.schemas.length} exposed schema(s) via ${exposure.source}${exposure.roles && exposure.roles.length > 0 ? ` (api roles: ${exposure.roles.join(', ')})` : ''}`
+            });
+        }
+        else {
+            checks.push({
+                name: 'exposure',
+                status: 'warn',
+                detail: 'no exposure surface configured — the audit assumes the whole database is reachable and caps the score. Declare `exposure.schemas` or use `exposure.resolver: "constructive"`.'
+            });
+        }
+    }
+    catch (err) {
+        checks.push({ name: 'exposure', status: 'warn', detail: err.message });
+    }
+    // --- declared public surface ---
+    if (publicRead.length > 0) {
+        try {
+            const { rows } = await exec.query(`SELECT n.nspname || '.' || c.relname AS qualified
+         FROM pg_class c
+         JOIN pg_namespace n ON n.oid = c.relnamespace
+         WHERE c.relkind IN ('r','p')
+           AND n.nspname NOT IN ('pg_catalog','information_schema')`);
+            const qualified = rows.map((r) => r.qualified);
+            const stale = publicRead.filter((p) => !qualified.some((q) => (0, resolve_1.matchTablePattern)(p, q)));
+            checks.push({
+                name: 'public',
+                status: stale.length > 0 ? 'warn' : 'ok',
+                detail: stale.length > 0
+                    ? `stale \`public.read\` pattern(s) match no table: ${stale.join(', ')}`
+                    : `${publicRead.length} \`public.read\` pattern(s), all match at least one table`
+            });
+        }
+        catch (err) {
+            checks.push({ name: 'public', status: 'warn', detail: err.message });
+        }
+    }
     return finish(checks);
 }
 function finish(checks) {

package/config/presets.d.ts

@@ -6,12 +6,21 @@ import type { SafegresConfig } from './types';
  */
 /** Today's default behavior: every rule at its registry default severity. */
 export declare const recommended: SafegresConfig;
-/** Everything on and escalated; coverage gaps are treated as critical. */
+/**
+ * Everything on and escalated. Fail-closed hygiene findings (dead grants,
+ * locked tables) are re-tuned upward and even contribute a fraction of
+ * their weight to the score.
+ */
 export declare const strict: SafegresConfig;
 /**
- * Tuned for Constructive's role model (RLS-first, anonymous/authenticated/
- * administrator): untrusted-role rules watch `anonymous`, and anything that
- * can leak rows across the role boundary is critical.
+ * Tuned for Constructive's architecture:
+ * - the exposure surface auto-resolves from the routing plane
+ *   (`routing_public.apis` → `api_schemas` → `metaschema_public.schema`),
+ *   so only what the exposed APIs can reach drives the score;
+ * - untrusted-role rules watch `anonymous`; anything that can leak rows
+ *   across the role boundary is critical;
+ * - A3 is off — API roles never own tables in the Constructive model, so
+ *   non-FORCEd RLS is not an exposure.
  */
 export declare const constructive: SafegresConfig;
 /** Structural flags only — a fast CI smoke check. */