@safegres/test 0.0.1 → 1.30.7

package/corpus/cases/48-definer-function-reach/schema.sql

@@ -0,0 +1,41 @@
+DROP SCHEMA IF EXISTS c_definer_fn CASCADE;
+CREATE SCHEMA c_definer_fn;
+
+-- The role the function executes as, and the owner of the table behind it.
+DO $$ BEGIN
+  CREATE ROLE c_definer_fn_owner NOLOGIN;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;
+
+GRANT USAGE ON SCHEMA c_definer_fn TO corpus_anon, corpus_user, c_definer_fn_owner;
+
+CREATE TABLE c_definer_fn.secrets (
+  id bigserial PRIMARY KEY,
+  subject text NOT NULL,
+  body text NOT NULL
+);
+ALTER TABLE c_definer_fn.secrets OWNER TO c_definer_fn_owner;
+ALTER TABLE c_definer_fn.secrets ENABLE ROW LEVEL SECURITY;
+
+-- Signed-in users see their own rows. corpus_anon holds no grant on the table
+-- at all, and no policy names it.
+CREATE POLICY secrets_own_rows ON c_definer_fn.secrets
+  FOR SELECT TO corpus_user
+  USING (subject = (SELECT current_setting('app.subject', true)));
+CREATE INDEX secrets_subject_idx ON c_definer_fn.secrets (subject);
+GRANT SELECT ON c_definer_fn.secrets TO corpus_user;
+
+-- The flaw: the function is SECURITY DEFINER, so its body runs as
+-- c_definer_fn_owner — who owns `secrets` and, because RLS is not FORCEd, is
+-- not filtered by its policy. EXECUTE is the only grant corpus_anon needs, and
+-- nothing in the ACL of `secrets` names it. Postgres grants EXECUTE to PUBLIC
+-- by default, so this reach exists even where nobody wrote a grant.
+CREATE FUNCTION c_definer_fn.recent_subjects()
+RETURNS TABLE (id bigint, subject text)
+LANGUAGE sql
+SECURITY DEFINER
+SET search_path TO c_definer_fn, pg_catalog
+AS $$
+  SELECT s.id, s.subject FROM c_definer_fn.secrets s ORDER BY s.id DESC LIMIT 20;
+$$;
+ALTER FUNCTION c_definer_fn.recent_subjects() OWNER TO c_definer_fn_owner;

package/corpus/cases/49-invoker-function-no-reach/case.json

@@ -0,0 +1,32 @@
+{
+  "title": "An invoker function over the same body is not a reach edge",
+  "dimension": "security",
+  "exposure": {
+    "schemas": [
+      "c_invoker_fn"
+    ],
+    "roles": [
+      "corpus_anon",
+      "corpus_user"
+    ],
+    "anonRoles": [
+      "corpus_anon"
+    ]
+  },
+  "expect": [
+    {
+      "code": "A3",
+      "relation": "c_invoker_fn.secrets",
+      "note": "the only real finding left: RLS is not FORCEd, so the table owner still reads every row"
+    }
+  ],
+  "forbid": [
+    "L8",
+    "L15",
+    "L19",
+    "L20"
+  ],
+  "worstSeverity": "low",
+  "fix": "ALTER TABLE c_invoker_fn.secrets FORCE ROW LEVEL SECURITY. The function needs no fix — running as the caller is what the definer-function reach (case 48) is fixed *into*.",
+  "id": "49-invoker-function-no-reach"
+}

package/corpus/cases/49-invoker-function-no-reach/schema.sql

@@ -0,0 +1,38 @@
+DROP SCHEMA IF EXISTS c_invoker_fn CASCADE;
+CREATE SCHEMA c_invoker_fn;
+
+DO $$ BEGIN
+  CREATE ROLE c_invoker_fn_owner NOLOGIN;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;
+
+GRANT USAGE ON SCHEMA c_invoker_fn TO corpus_anon, corpus_user, c_invoker_fn_owner;
+
+CREATE TABLE c_invoker_fn.secrets (
+  id bigserial PRIMARY KEY,
+  subject text NOT NULL,
+  body text NOT NULL
+);
+ALTER TABLE c_invoker_fn.secrets OWNER TO c_invoker_fn_owner;
+ALTER TABLE c_invoker_fn.secrets ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY secrets_own_rows ON c_invoker_fn.secrets
+  FOR SELECT TO corpus_user
+  USING (subject = (SELECT current_setting('app.subject', true)));
+CREATE INDEX secrets_subject_idx ON c_invoker_fn.secrets (subject);
+GRANT SELECT ON c_invoker_fn.secrets TO corpus_user;
+
+-- The same body over the same shape, with the one difference that matters:
+-- a function is SECURITY INVOKER unless it says otherwise, so the body runs
+-- with the caller's privileges and corpus_anon is denied on `secrets` exactly
+-- as a direct SELECT would be. There is no reach edge here, and a rule that
+-- reported one would be flagging a correct schema — which is why this case
+-- forbids L19 rather than merely omitting it.
+CREATE FUNCTION c_invoker_fn.recent_subjects()
+RETURNS TABLE (id bigint, subject text)
+LANGUAGE sql
+SET search_path TO c_invoker_fn, pg_catalog
+AS $$
+  SELECT s.id, s.subject FROM c_invoker_fn.secrets s ORDER BY s.id DESC LIMIT 20;
+$$;
+ALTER FUNCTION c_invoker_fn.recent_subjects() OWNER TO c_invoker_fn_owner;

package/corpus/cases/50-instead-of-trigger-write/case.json

@@ -0,0 +1,38 @@
+{
+  "title": "Anonymous role writes a locked table through an INSTEAD OF trigger's definer function",
+  "dimension": "security",
+  "exposure": {
+    "schemas": [
+      "c_trigger_write"
+    ],
+    "roles": [
+      "corpus_anon",
+      "corpus_user"
+    ],
+    "anonRoles": [
+      "corpus_anon"
+    ]
+  },
+  "expect": [
+    {
+      "code": "L20",
+      "relation": "c_trigger_write.submissions",
+      "role": "corpus_anon",
+      "note": "the write never reaches `submissions` directly — it becomes the trigger function's body, which is SECURITY DEFINER, so it lands as c_trigger_write_owner. This is the write L9 suppressed as unfollowable"
+    },
+    {
+      "code": "A3",
+      "relation": "c_trigger_write.submissions",
+      "note": "RLS is not FORCEd, which is why the owner's insert inside the trigger body is not checked against the table's own policy"
+    }
+  ],
+  "forbid": [
+    "L8",
+    "L9",
+    "L15",
+    "L19"
+  ],
+  "worstSeverity": "low",
+  "fix": "Make c_trigger_write.tg_submission_inbox() SECURITY INVOKER so the caller's own grants apply, authorize the caller inside the body, or give the function an owner whose reach matches what the view is meant to accept. Revoking corpus_anon's INSERT on the view is not the fix — that grant is what the API serves.",
+  "id": "50-instead-of-trigger-write"
+}

package/corpus/cases/50-instead-of-trigger-write/schema.sql

@@ -0,0 +1,58 @@
+DROP SCHEMA IF EXISTS c_trigger_write CASCADE;
+CREATE SCHEMA c_trigger_write;
+
+DO $$ BEGIN
+  CREATE ROLE c_trigger_write_owner NOLOGIN;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;
+
+GRANT USAGE ON SCHEMA c_trigger_write TO corpus_anon, corpus_user, c_trigger_write_owner;
+
+CREATE TABLE c_trigger_write.submissions (
+  id bigserial PRIMARY KEY,
+  author text NOT NULL,
+  body text NOT NULL
+);
+ALTER TABLE c_trigger_write.submissions OWNER TO c_trigger_write_owner;
+ALTER TABLE c_trigger_write.submissions ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY submissions_own_rows ON c_trigger_write.submissions
+  FOR ALL TO corpus_user
+  USING (author = (SELECT current_setting('app.author', true)))
+  WITH CHECK (author = (SELECT current_setting('app.author', true)));
+CREATE INDEX submissions_author_idx ON c_trigger_write.submissions (author);
+GRANT SELECT, INSERT ON c_trigger_write.submissions TO corpus_user;
+GRANT USAGE ON SEQUENCE c_trigger_write.submissions_id_seq TO corpus_user;
+
+-- The flaw, in the function rather than the view: an INSTEAD OF trigger
+-- replaces the write against the view with this body, and the body is
+-- permission-checked against whoever the *function* runs as. SECURITY DEFINER
+-- makes that c_trigger_write_owner, so corpus_anon's INSERT on the view lands
+-- in `submissions` under the table owner. The view's own owner and its
+-- security_invoker setting do not enter into it.
+CREATE FUNCTION c_trigger_write.tg_submission_inbox()
+RETURNS trigger
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path TO c_trigger_write, pg_catalog
+AS $$
+BEGIN
+  INSERT INTO c_trigger_write.submissions (author, body) VALUES (NEW.author, NEW.body);
+  RETURN NEW;
+END;
+$$;
+ALTER FUNCTION c_trigger_write.tg_submission_inbox() OWNER TO c_trigger_write_owner;
+
+-- security_invoker, precisely so the finding cannot be attributed to the view:
+-- the escalation is the trigger function's, and L9's auto-update path does not
+-- apply to a view carrying INSTEAD OF triggers at all.
+CREATE VIEW c_trigger_write.submission_inbox
+  WITH (security_invoker = true) AS
+  SELECT id, author, body FROM c_trigger_write.submissions;
+ALTER VIEW c_trigger_write.submission_inbox OWNER TO c_trigger_write_owner;
+
+CREATE TRIGGER submission_inbox_insert
+  INSTEAD OF INSERT ON c_trigger_write.submission_inbox
+  FOR EACH ROW EXECUTE FUNCTION c_trigger_write.tg_submission_inbox();
+
+GRANT INSERT ON c_trigger_write.submission_inbox TO corpus_anon;

package/corpus/cases/51-invoker-trigger-no-write/case.json

@@ -0,0 +1,33 @@
+{
+  "title": "An INSTEAD OF trigger whose function runs as the caller is not a write bypass",
+  "dimension": "security",
+  "exposure": {
+    "schemas": [
+      "c_invoker_trigger"
+    ],
+    "roles": [
+      "corpus_anon",
+      "corpus_user"
+    ],
+    "anonRoles": [
+      "corpus_anon"
+    ]
+  },
+  "expect": [
+    {
+      "code": "A3",
+      "relation": "c_invoker_trigger.submissions",
+      "note": "the only real finding left: RLS is not FORCEd, so the table owner still writes every row"
+    }
+  ],
+  "forbid": [
+    "L8",
+    "L9",
+    "L15",
+    "L19",
+    "L20"
+  ],
+  "worstSeverity": "low",
+  "fix": "ALTER TABLE c_invoker_trigger.submissions FORCE ROW LEVEL SECURITY. Neither the trigger nor the view needs a fix — an invoker trigger function is what case 50 is fixed *into*, and the view being a definer changes nothing, because it is the function's security attribute that decides who the write runs as.",
+  "id": "51-invoker-trigger-no-write"
+}

package/corpus/cases/51-invoker-trigger-no-write/schema.sql

@@ -0,0 +1,54 @@
+DROP SCHEMA IF EXISTS c_invoker_trigger CASCADE;
+CREATE SCHEMA c_invoker_trigger;
+
+DO $$ BEGIN
+  CREATE ROLE c_invoker_trigger_owner NOLOGIN;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;
+
+GRANT USAGE ON SCHEMA c_invoker_trigger
+  TO corpus_anon, corpus_user, c_invoker_trigger_owner;
+
+CREATE TABLE c_invoker_trigger.submissions (
+  id bigserial PRIMARY KEY,
+  author text NOT NULL,
+  body text NOT NULL
+);
+ALTER TABLE c_invoker_trigger.submissions OWNER TO c_invoker_trigger_owner;
+ALTER TABLE c_invoker_trigger.submissions ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY submissions_own_rows ON c_invoker_trigger.submissions
+  FOR ALL TO corpus_user
+  USING (author = (SELECT current_setting('app.author', true)))
+  WITH CHECK (author = (SELECT current_setting('app.author', true)));
+CREATE INDEX submissions_author_idx ON c_invoker_trigger.submissions (author);
+GRANT SELECT, INSERT ON c_invoker_trigger.submissions TO corpus_user;
+GRANT USAGE ON SEQUENCE c_invoker_trigger.submissions_id_seq TO corpus_user;
+
+-- The same trigger over the same shape, with the one difference that matters:
+-- the trigger function is SECURITY INVOKER, so its body runs as the caller and
+-- Postgres denies corpus_anon on `submissions` exactly as it would deny a
+-- direct insert. The view here is *not* security_invoker, which is the point:
+-- a view's owner does not decide who a trigger function's body runs as, and a
+-- rule that read the view's setting instead of the function's would fire here.
+CREATE FUNCTION c_invoker_trigger.tg_submission_inbox()
+RETURNS trigger
+LANGUAGE plpgsql
+SET search_path TO c_invoker_trigger, pg_catalog
+AS $$
+BEGIN
+  INSERT INTO c_invoker_trigger.submissions (author, body) VALUES (NEW.author, NEW.body);
+  RETURN NEW;
+END;
+$$;
+ALTER FUNCTION c_invoker_trigger.tg_submission_inbox() OWNER TO c_invoker_trigger_owner;
+
+CREATE VIEW c_invoker_trigger.submission_inbox AS
+  SELECT id, author, body FROM c_invoker_trigger.submissions;
+ALTER VIEW c_invoker_trigger.submission_inbox OWNER TO c_invoker_trigger_owner;
+
+CREATE TRIGGER submission_inbox_insert
+  INSTEAD OF INSERT ON c_invoker_trigger.submission_inbox
+  FOR EACH ROW EXECUTE FUNCTION c_invoker_trigger.tg_submission_inbox();
+
+GRANT INSERT ON c_invoker_trigger.submission_inbox TO corpus_anon;

package/corpus/cases/52-revocable-execute-grant/case.json

@@ -0,0 +1,30 @@
+{
+  "title": "A role holds EXECUTE on a trigger function it can neither call nor fire — revocable",
+  "dimension": "security",
+  "exposure": {
+    "schemas": [
+      "c_revocable"
+    ],
+    "roles": [
+      "corpus_anon",
+      "corpus_user"
+    ],
+    "anonRoles": [
+      "corpus_anon"
+    ]
+  },
+  "expect": [
+    {
+      "code": "L21",
+      "relation": "c_revocable.stamp_created_by",
+      "role": "corpus_anon",
+      "note": "corpus_anon's EXECUTE arrives from a blanket default-privileges grant, but the reachability closure never lands on the function: a trigger function is not directly callable, and corpus_anon holds no write grant on `events` to fire the trigger. Granted minus reachable is non-empty, so the grant is revocable."
+    }
+  ],
+  "forbid": [
+    "L19",
+    "L20"
+  ],
+  "fix": "REVOKE EXECUTE ON FUNCTION c_revocable.stamp_created_by() FROM corpus_anon. No path exercises the grant — corpus_anon cannot call a trigger function directly, and cannot fire the trigger without a write grant on c_revocable.events — so dropping it changes nothing corpus_anon can do.",
+  "id": "52-revocable-execute-grant"
+}

package/corpus/cases/52-revocable-execute-grant/schema.sql

@@ -0,0 +1,45 @@
+DROP SCHEMA IF EXISTS c_revocable CASCADE;
+CREATE SCHEMA c_revocable;
+
+DO $$ BEGIN
+  CREATE ROLE c_revocable_owner NOLOGIN;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;
+
+GRANT USAGE ON SCHEMA c_revocable TO corpus_anon, corpus_user, c_revocable_owner;
+
+CREATE TABLE c_revocable.events (
+  id bigserial PRIMARY KEY,
+  body text NOT NULL
+);
+ALTER TABLE c_revocable.events OWNER TO c_revocable_owner;
+ALTER TABLE c_revocable.events ENABLE ROW LEVEL SECURITY;
+ALTER TABLE c_revocable.events FORCE ROW LEVEL SECURITY;
+
+-- corpus_anon may read, nothing more.
+CREATE POLICY events_read ON c_revocable.events
+  FOR SELECT TO corpus_anon USING (id > 0);
+GRANT SELECT ON c_revocable.events TO corpus_anon;
+
+-- A SECURITY DEFINER trigger function. It fires only on write, and corpus_anon
+-- holds no write grant on `events`, so it can never make the trigger run. A
+-- trigger function is not directly callable either: Postgres refuses a direct
+-- call however wide its EXECUTE ACL is.
+CREATE FUNCTION c_revocable.stamp_created_by()
+RETURNS trigger
+LANGUAGE plpgsql
+AS $$
+BEGIN
+  RETURN NEW;
+END;
+$$;
+ALTER FUNCTION c_revocable.stamp_created_by() OWNER TO c_revocable_owner;
+
+CREATE TRIGGER stamp_created_by BEFORE INSERT ON c_revocable.events
+  FOR EACH ROW EXECUTE FUNCTION c_revocable.stamp_created_by();
+
+-- The blanket grant: corpus_anon gets EXECUTE the way a schema created with
+-- `ALTER DEFAULT PRIVILEGES ... GRANT ALL ON FUNCTIONS TO anonymous` hands it
+-- out. corpus_anon now holds EXECUTE on a trigger function it can neither call
+-- nor fire — a grant `granted − reachable` should prove revocable.
+GRANT EXECUTE ON FUNCTION c_revocable.stamp_created_by() TO corpus_anon;

package/corpus/cases/53-policy-predicate-retains-execute/case.json

@@ -0,0 +1,23 @@
+{
+  "title": "A grant that looks dead but is reached through an RLS policy predicate — retained, not revocable",
+  "dimension": "security",
+  "exposure": {
+    "schemas": [
+      "c_policy_reach",
+      "c_policy_priv"
+    ],
+    "roles": [
+      "corpus_anon",
+      "corpus_user"
+    ],
+    "anonRoles": [
+      "corpus_anon"
+    ]
+  },
+  "expect": [],
+  "forbid": [
+    "L21"
+  ],
+  "fix": "Do not revoke. corpus_anon's EXECUTE on c_policy_priv.can_read(bigint) is exercised by the docs_visible policy predicate on every read of c_policy_reach.docs, which evaluates as the querying role. Revoking it makes the policy raise `permission denied for function can_read` and fails authorization closed for every anonymous read — the load-bearing grant the rule is built to protect.",
+  "id": "53-policy-predicate-retains-execute"
+}

package/corpus/cases/53-policy-predicate-retains-execute/schema.sql

@@ -0,0 +1,49 @@
+DROP SCHEMA IF EXISTS c_policy_reach CASCADE;
+DROP SCHEMA IF EXISTS c_policy_priv CASCADE;
+CREATE SCHEMA c_policy_reach;
+CREATE SCHEMA c_policy_priv;
+
+DO $$ BEGIN
+  CREATE ROLE c_policy_owner NOLOGIN;
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$;
+
+-- corpus_anon can reach the API schema, but holds no USAGE on the private one —
+-- exactly the constructive-db shape, where the `*_private` schemas hold the
+-- check functions the policies call. The private schema is still audited (it is
+-- in scope), it is simply not part of the surface corpus_anon addresses.
+GRANT USAGE ON SCHEMA c_policy_reach TO corpus_anon, c_policy_owner;
+GRANT USAGE ON SCHEMA c_policy_priv TO c_policy_owner;
+
+CREATE TABLE c_policy_reach.docs (
+  id bigserial PRIMARY KEY,
+  owner_id bigint NOT NULL,
+  body text NOT NULL
+);
+ALTER TABLE c_policy_reach.docs OWNER TO c_policy_owner;
+ALTER TABLE c_policy_reach.docs ENABLE ROW LEVEL SECURITY;
+ALTER TABLE c_policy_reach.docs FORCE ROW LEVEL SECURITY;
+
+-- The load-bearing check. It looks dead: corpus_anon never calls it, holds no
+-- USAGE on its schema, and no ACL on `docs` names it. But it is the SELECT
+-- policy's predicate, which evaluates as corpus_anon on every read of `docs`.
+CREATE FUNCTION c_policy_priv.can_read(owner_id bigint)
+RETURNS boolean
+LANGUAGE sql
+STABLE
+AS $$
+  SELECT owner_id = NULLIF(current_setting('app.uid', true), '')::bigint;
+$$;
+ALTER FUNCTION c_policy_priv.can_read(bigint) OWNER TO c_policy_owner;
+
+CREATE POLICY docs_visible ON c_policy_reach.docs
+  FOR SELECT TO corpus_anon
+  USING (c_policy_priv.can_read(owner_id));
+
+GRANT SELECT ON c_policy_reach.docs TO corpus_anon;
+
+-- The blanket grant again: corpus_anon holds EXECUTE on the private check
+-- function. `granted − reachable` must NOT report it revocable — the policy
+-- predicate is a reachable path, and losing EXECUTE would break authorization
+-- silently, for every anonymous read. This is the case the rule exists for.
+GRANT EXECUTE ON FUNCTION c_policy_priv.can_read(bigint) TO corpus_anon;

package/corpus/index.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The evaluation corpus: small schemas with a deliberate flaw and a written-down
+ * answer.
+ *
+ * It exists because "the score went up" is not evidence of anything on its own.
+ * A corpus with known answers turns safegres into a measuring instrument you
+ * can calibrate: every case names the findings a correct audit must produce, so
+ * a run can be graded on recall (did it find the flaw?) rather than on a number
+ * whose provenance nobody can check. It is used three ways —
+ *
+ *   1. safegres's own regression suite (`__tests__/corpus.test.ts`);
+ *   2. an evaluation harness for an agent asked to *fix* the case: audit,
+ *      hand the findings over, re-audit, and require the expected findings to
+ *      be gone without new ones appearing;
+ *   3. worked examples — each case is short enough to read.
+ *
+ * Cases live in `corpus/cases/<id>/` as `schema.sql` plus `case.json`, i.e.
+ * data, not code: another tool can consume the corpus without running ours.
+ */
+import type { ExposureConfig } from '../config/types';
+import type { Report, Severity } from '../types';
+/** One expected finding: a rule code, optionally pinned to a relation. */
+export interface ExpectedFinding {
+    code: string;
+    /** `schema.table`, when the case has more than one relation in play. */
+    relation?: string;
+    /** Why this is the right answer — the part a reader learns from. */
+    note?: string;
+}
+export interface CorpusCase {
+    id: string;
+    title: string;
+    /** Which axis the flaw is on. A case may be graded on both. */
+    dimension: 'security' | 'perf';
+    /** The SQL that builds the case, as committed. */
+    sql: string;
+    /** The surface the case is graded against — its whole point, for most cases. */
+    exposure: ExposureConfig;
+    /** Findings a correct audit must produce. */
+    expect: ExpectedFinding[];
+    /** Rule codes that must NOT fire: the false positives this case guards. */
+    forbid?: string[];
+    /** Worst severity the case should produce, as a coarse sanity check. */
+    worstSeverity?: Severity;
+    /** How the flaw is fixed, in one sentence — the answer key. */
+    fix: string;
+}
+/**
+ * The corpus shipped with the package. Two candidates because the package
+ * publishes from `dist/`, where the corpus sits one directory closer.
+ */
+export declare function corpusDir(): string;
+/**
+ * The SQL creating the roles every case is graded against (`corpus_anon`,
+ * `corpus_user`). Idempotent, so a harness can run it before every case.
+ */
+export declare function corpusBootstrap(dir?: string): string;
+/** Load every case in `dir` (default: the shipped corpus), ordered by id. */
+export declare function loadCorpus(dir?: string): CorpusCase[];
+/** Load a single case directory (`case.json` + `schema.sql`). */
+export declare function loadCase(dir: string): CorpusCase;
+export interface CaseResult {
+    id: string;
+    /** Expected findings the audit produced. */
+    found: ExpectedFinding[];
+    /** Expected findings the audit missed — recall failures. */
+    missed: ExpectedFinding[];
+    /** Forbidden rule codes the audit produced — precision failures. */
+    falsePositives: string[];
+    /** True when nothing was missed and nothing forbidden fired. */
+    passed: boolean;
+}
+/**
+ * Grade a report against the case it was produced from. Deliberately not a
+ * strict equality check on the finding set: a case pins the findings that
+ * define it, and a later release adding an unrelated advisory should not
+ * invalidate the corpus. What a case *does* pin negatively goes in `forbid`.
+ */
+export declare function gradeCase(report: Report, testCase: CorpusCase): CaseResult;

package/corpus/index.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * The evaluation corpus: small schemas with a deliberate flaw and a written-down
+ * answer.
+ *
+ * It exists because "the score went up" is not evidence of anything on its own.
+ * A corpus with known answers turns safegres into a measuring instrument you
+ * can calibrate: every case names the findings a correct audit must produce, so
+ * a run can be graded on recall (did it find the flaw?) rather than on a number
+ * whose provenance nobody can check. It is used three ways —
+ *
+ *   1. safegres's own regression suite (`__tests__/corpus.test.ts`);
+ *   2. an evaluation harness for an agent asked to *fix* the case: audit,
+ *      hand the findings over, re-audit, and require the expected findings to
+ *      be gone without new ones appearing;
+ *   3. worked examples — each case is short enough to read.
+ *
+ * Cases live in `corpus/cases/<id>/` as `schema.sql` plus `case.json`, i.e.
+ * data, not code: another tool can consume the corpus without running ours.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.corpusDir = corpusDir;
+exports.corpusBootstrap = corpusBootstrap;
+exports.loadCorpus = loadCorpus;
+exports.loadCase = loadCase;
+exports.gradeCase = gradeCase;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * The corpus shipped with the package. Two candidates because the package
+ * publishes from `dist/`, where the corpus sits one directory closer.
+ */
+function corpusDir() {
+    const candidates = [
+        path.resolve(__dirname, '..', 'corpus', 'cases'),
+        path.resolve(__dirname, '..', '..', 'corpus', 'cases')
+    ];
+    const found = candidates.find((dir) => fs.existsSync(dir));
+    if (!found)
+        throw new Error(`Corpus not found. Looked in: ${candidates.join(', ')}`);
+    return found;
+}
+/**
+ * The SQL creating the roles every case is graded against (`corpus_anon`,
+ * `corpus_user`). Idempotent, so a harness can run it before every case.
+ */
+function corpusBootstrap(dir = corpusDir()) {
+    return fs.readFileSync(path.resolve(dir, '..', 'bootstrap.sql'), 'utf8');
+}
+/** Load every case in `dir` (default: the shipped corpus), ordered by id. */
+function loadCorpus(dir = corpusDir()) {
+    return fs
+        .readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => loadCase(path.join(dir, e.name)))
+        .sort((a, b) => a.id.localeCompare(b.id));
+}
+/** Load a single case directory (`case.json` + `schema.sql`). */
+function loadCase(dir) {
+    const meta = JSON.parse(fs.readFileSync(path.join(dir, 'case.json'), 'utf8'));
+    return {
+        ...meta,
+        id: meta.id ?? path.basename(dir),
+        sql: fs.readFileSync(path.join(dir, 'schema.sql'), 'utf8')
+    };
+}
+function matches(finding, expected) {
+    if (finding.code !== expected.code)
+        return false;
+    if (!expected.relation)
+        return true;
+    return `${finding.schema}.${finding.table}` === expected.relation;
+}
+/**
+ * Grade a report against the case it was produced from. Deliberately not a
+ * strict equality check on the finding set: a case pins the findings that
+ * define it, and a later release adding an unrelated advisory should not
+ * invalidate the corpus. What a case *does* pin negatively goes in `forbid`.
+ */
+function gradeCase(report, testCase) {
+    const findings = report.findings;
+    const found = testCase.expect.filter((e) => findings.some((f) => matches(f, e)));
+    const missed = testCase.expect.filter((e) => !findings.some((f) => matches(f, e)));
+    const falsePositives = [...new Set(findings.map((f) => f.code))].filter((code) => (testCase.forbid ?? []).includes(code));
+    return {
+        id: testCase.id,
+        found,
+        missed,
+        falsePositives,
+        passed: missed.length === 0 && falsePositives.length === 0
+    };
+}

package/esm/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/esm/adapters.js

@@ -0,0 +1,6 @@
+/**
+ * `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 { BUILTIN_ADAPTERS, constructiveAdapter, definePlanes, graphileAdapter, hasuraAdapter, postgraphileAdapter, postgrestAdapter, resolveAdapters, supabaseAdapter } from './exposure/adapters';