@safegres/test 0.0.2 → 1.30.7

package/esm/config/validate.js

@@ -0,0 +1,122 @@
+import { ConfigValidationError } from './resolve';
+import { CONFIG_SHAPE } from './schema';
+/**
+ * Check a config against the described shape: unknown keys, and values of the
+ * wrong kind.
+ *
+ * A typo'd key used to be *silently ignored*, which for a file that decides
+ * whether CI fails is the worst possible outcome — `failon: { grade: 'B' }`
+ * reads as a passing build rather than as a mistake. So this rejects rather
+ * than warns, and names the key it thinks you meant.
+ *
+ * Value checks stay shallow on purpose: rule settings, severities and grades
+ * are validated by `resolveRules` and by the gate code, which know the rule
+ * registry. This is the shape, not the semantics.
+ */
+export function validateConfigShape(config) {
+    const problems = [];
+    checkObject(config, CONFIG_SHAPE, '', problems, ['$schema', 'extends']);
+    if (problems.length === 0)
+        return;
+    throw new ConfigValidationError(`Invalid safegres configuration:\n${problems.map((p) => `  - ${p}`).join('\n')}`);
+}
+function checkObject(value, properties, path, problems, extraKeys = []) {
+    if (!isPlainObject(value))
+        return;
+    for (const [key, entry] of Object.entries(value)) {
+        if (extraKeys.includes(key))
+            continue;
+        const node = properties[key];
+        if (!node) {
+            problems.push(`unknown key ${quote(path, key)}${suggestion(key, Object.keys(properties))}`);
+            continue;
+        }
+        checkNode(entry, node, path ? `${path}.${key}` : key, problems);
+    }
+}
+function checkNode(value, node, path, problems) {
+    if (value === undefined || value === null)
+        return;
+    switch (node.type) {
+        case 'any':
+            return;
+        case 'string':
+            if (typeof value !== 'string')
+                return void problems.push(wrongType(path, 'a string', value));
+            if (node.enum && !node.enum.includes(value)) {
+                problems.push(`"${path}" is "${value}"; expected one of ${node.enum.map((v) => `"${v}"`).join(', ')}`);
+            }
+            return;
+        case 'number':
+            if (typeof value !== 'number')
+                problems.push(wrongType(path, 'a number', value));
+            return;
+        case 'boolean':
+            if (typeof value !== 'boolean')
+                problems.push(wrongType(path, 'a boolean', value));
+            return;
+        case 'array':
+            if (!Array.isArray(value))
+                return void problems.push(wrongType(path, 'an array', value));
+            value.forEach((item, i) => checkNode(item, node.items, `${path}[${i}]`, problems));
+            return;
+        case 'object':
+            if (!isPlainObject(value))
+                return void problems.push(wrongType(path, 'an object', value));
+            checkObject(value, node.properties, path, problems);
+            return;
+        case 'record':
+            if (!isPlainObject(value))
+                return void problems.push(wrongType(path, 'an object', value));
+            for (const [key, entry] of Object.entries(value)) {
+                checkNode(entry, node.values, `${path}.${key}`, problems);
+            }
+            return;
+        case 'union': {
+            // A union is satisfied by any branch, so only report when every branch
+            // rejects — and then report the branch that complained least.
+            const attempts = node.of.map((branch) => {
+                const branchProblems = [];
+                checkNode(value, branch, path, branchProblems);
+                return branchProblems;
+            });
+            if (attempts.some((a) => a.length === 0))
+                return;
+            const best = attempts.reduce((a, b) => (b.length < a.length ? b : a));
+            problems.push(...best);
+        }
+    }
+}
+function wrongType(path, expected, value) {
+    return `"${path}" is ${describe(value)}; expected ${expected}`;
+}
+function describe(value) {
+    if (Array.isArray(value))
+        return 'an array';
+    if (value === null)
+        return 'null';
+    return `a ${typeof value}`;
+}
+function quote(path, key) {
+    return `"${path ? `${path}.${key}` : key}"`;
+}
+/** "did you mean" for one edit's worth of typo, which is the common case. */
+function suggestion(key, known) {
+    const lower = key.toLowerCase();
+    const near = known.find((k) => k.toLowerCase() === lower)
+        ?? known.find((k) => distance(k.toLowerCase(), lower) <= Math.max(1, Math.floor(key.length / 4)));
+    return near ? ` — did you mean "${near}"?` : '';
+}
+function distance(a, b) {
+    const rows = [Array.from({ length: b.length + 1 }, (_, j) => j)];
+    for (let i = 1; i <= a.length; i++) {
+        rows[i] = [i];
+        for (let j = 1; j <= b.length; j++) {
+            rows[i][j] = Math.min(rows[i - 1][j] + 1, rows[i][j - 1] + 1, rows[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+    }
+    return rows[a.length][b.length];
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

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

@@ -0,0 +1,85 @@
+/**
+ * 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 * as fs from 'fs';
+import * as path from 'path';
+/**
+ * The corpus shipped with the package. Two candidates because the package
+ * publishes from `dist/`, where the corpus sits one directory closer.
+ */
+export 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.
+ */
+export 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. */
+export 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`). */
+export 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`.
+ */
+export 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/exposure/adapters.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Exposure adapters: how safegres learns what a stack exposes.
+ *
+ * An adapter is a value, not a module name. Built-ins are named exports of
+ * this module, a custom one is an object you construct in your own repo, and
+ * both are passed the same way — nothing is resolved by package name, and
+ * there is no plugin loader to reason about:
+ *
+ * ```ts
+ * import { constructiveAdapter, definePlanes } from 'safegres/adapters';
+ *
+ * export default defineConfig({
+ *   exposure: { adapters: [constructiveAdapter, myAdapter], schemas: ['app_public'] }
+ * });
+ * ```
+ *
+ * `detect()` answers "is this stack present in this database?" and `resolve()`
+ * returns the planes it exposes — one per API where the stack has more than
+ * one, because "the admin API grades A and the public API grades C" is
+ * strictly more useful than their union.
+ */
+import type { PlaneKind } from '../config/types';
+import type { QueryExecutor } from '../pg/introspect';
+import type { ApiReach } from './reach';
+/** A plane as an adapter reports it, before roles are resolved against the catalog. */
+export interface PlaneInput {
+    name: string;
+    kind?: PlaneKind;
+    primary?: boolean;
+    schemas?: string[];
+    /** Every role that reaches this plane, anonymous ones included. */
+    roles?: string[];
+    /**
+     * The subset of `roles` an *unauthenticated* caller arrives as. Every stack
+     * knows which one this is — Constructive's `apis.anon_role`, PostgREST's
+     * `pgrst.db_anon_role`, Supabase's `anon`, graphile's visitor — and the
+     * distinction is the difference between "a signed-in user can write this"
+     * (usually the point) and "anyone on the internet can" (usually the bug).
+     */
+    anonRoles?: string[];
+}
+/** What an adapter is asked to compute reach for. */
+export interface ReachContext {
+    /** Schemas on the plane. Empty means "the whole database". */
+    schemas: string[];
+    excludeSchemas?: string[];
+}
+export interface ExposureAdapter {
+    /** Stable identifier, reported as the exposure `source`. */
+    name: string;
+    /** True when this stack is present in the connected database. */
+    detect(exec: QueryExecutor): Promise<boolean>;
+    /** The planes this stack exposes. An empty array means "present, exposes nothing". */
+    resolve(exec: QueryExecutor): Promise<PlaneInput[]>;
+    /**
+     * Optional relation-level precision *within* a plane's schemas: which
+     * relations the stack's generated API cannot address at all.
+     *
+     * Separate from `resolve` because it answers a different question and most
+     * adapters cannot answer it. An adapter that knows the schemas but not the
+     * fields simply omits this, and the plane stays schema-granular.
+     */
+    reach?(exec: QueryExecutor, context: ReachContext): Promise<ApiReach>;
+}
+/**
+ * Constructive routing-plane introspection: an API exposes a set of schemas
+ * via `routing_public.apis` → `routing_public.api_schemas` →
+ * `metaschema_public.schema` (and the platform plane via `platform_apis` →
+ * `platform_api_schemas`). API-edge roles come from `apis.role_name` /
+ * `apis.anon_role`.
+ *
+ * Emits one `api` plane per API, plus a primary plane unioning them: the union
+ * is what the headline score has always been computed against, and the
+ * per-API planes are what let a reader see which API carries the debt.
+ */
+export declare const constructiveAdapter: ExposureAdapter;
+/**
+ * PostGraphile behaviors as relation-level reach.
+ *
+ * Deliberately *not* folded into {@link constructiveAdapter}, even though
+ * Constructive is a PostGraphile stack: behaviors are a Graphile convention
+ * that any Graphile database follows, and each adapter should say one true
+ * thing. This one contributes no planes — it has no idea which schemas an API
+ * serves — and only narrows the planes another adapter, or the config, already
+ * established.
+ */
+export declare const postgraphileAdapter: ExposureAdapter;
+/**
+ * PostgREST exposure, read from the catalog rather than inferred from a
+ * schema name: PostgREST serves exactly `pgrst.db_schemas`, which is set as a
+ * role or database GUC (`ALTER ROLE authenticator SET pgrst.db_schemas = …`)
+ * and therefore lands in `pg_db_role_setting`. `pgrst.db_anon_role` names the
+ * role an unauthenticated request runs as, and the connecting role
+ * (`authenticator` by convention) is the one that can `SET ROLE` to it.
+ *
+ * Supabase is PostgREST underneath, so this covers it too; the difference is
+ * the role vocabulary, which the `supabase` preset supplies.
+ */
+export declare const postgrestAdapter: ExposureAdapter;
+/**
+ * Supabase runs PostgREST, but configures it *outside* the database — the
+ * schema list is a platform setting, so `pgrst.db_schemas` is usually absent
+ * and `postgrestAdapter` correctly resolves nothing. Hence a separate
+ * adapter: it prefers the GUCs when a self-hosted stack sets them, and only
+ * falls back to the platform's fixed surface once it has *proved* it is
+ * looking at Supabase — `auth.users` plus the three roles every project has.
+ *
+ * The fallback is deliberately confined here. `postgrestAdapter` never
+ * guesses: an unconfigured PostgREST resolves no planes, which surfaces as
+ * unknown exposure (a capped score and a W1) rather than a wrong surface
+ * presented as fact.
+ */
+export declare const supabaseAdapter: ExposureAdapter;
+/**
+ * Hasura reads its exposed surface out of its own metadata: v2+ keeps one
+ * JSON document in `hdb_catalog.hdb_metadata`, older versions a row per
+ * tracked table in `hdb_catalog.hdb_table`. Only *tracked* tables are served,
+ * so the schemas that contain them are the surface.
+ */
+export declare const hasuraAdapter: ExposureAdapter;
+/**
+ * PostGraphile publishes whatever schemas it was started with — a CLI/library
+ * argument, invisible from inside the database. So this adapter resolves the
+ * `graphile-starter` layout (`app_public` served, `app_hidden`/`app_private`
+ * not) and nothing else.
+ *
+ * That is naming-as-intent, which safegres otherwise refuses. The difference
+ * is consent: listing this adapter *is* the declaration that the convention
+ * holds here. When it doesn't, list `exposure.schemas` instead — explicit
+ * always wins.
+ *
+ * Reach is a separate question — *which schemas are served* versus *which
+ * relations the served schemas expose* — and is delegated to
+ * {@link postgraphileAdapter}, which answers it for any Graphile stack
+ * regardless of schema layout.
+ */
+export declare const graphileAdapter: ExposureAdapter;
+/** Every adapter a config may name with a string. */
+export declare const BUILTIN_ADAPTERS: Record<string, ExposureAdapter>;
+/**
+ * Wrap a fixed set of planes as an adapter — the escape hatch for a surface
+ * you know but cannot introspect (a schema list your deployment tooling
+ * knows, an API gateway's config read at build time).
+ */
+export declare function definePlanes(name: string, planes: PlaneInput[]): ExposureAdapter;
+/**
+ * Coerce whatever a config carried in `exposure.adapters` into adapters.
+ * Strings resolve against the built-in table only — an unknown name is an
+ * error rather than a silent no-op, because a typo'd adapter name would
+ * otherwise present as an unexposed database.
+ */
+export declare function resolveAdapters(entries: Array<string | ExposureAdapter> | undefined): ExposureAdapter[];