@safegres/test 0.0.1 → 1.30.7

package/config/resolve.js

@@ -0,0 +1,192 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigValidationError = void 0;
+exports.applyRulesConfig = applyRulesConfig;
+exports.defaultRuleMap = defaultRuleMap;
+exports.resolveRules = resolveRules;
+exports.ruleCodesForDimension = ruleCodesForDimension;
+exports.matchTablePattern = matchTablePattern;
+exports.rulesForTable = rulesForTable;
+exports.applyRulesToFindings = applyRulesToFindings;
+exports.allAstRulesDisabled = allAstRulesDisabled;
+const registry_1 = require("../rules/registry");
+const types_1 = require("../types");
+class ConfigValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConfigValidationError';
+    }
+}
+exports.ConfigValidationError = ConfigValidationError;
+function parseSetting(code, setting) {
+    if (setting === 'off') {
+        return { enabled: false, severity: registry_1.RULES_BY_CODE.get(code).defaultSeverity };
+    }
+    if (typeof setting === 'string') {
+        assertSeverity(code, setting);
+        return { enabled: true, severity: setting };
+    }
+    if (Array.isArray(setting) && setting.length >= 1) {
+        assertSeverity(code, setting[0]);
+        return { enabled: true, severity: setting[0], options: setting[1] };
+    }
+    throw new ConfigValidationError(`Invalid setting for rule "${code}": expected "off", a severity, or [severity, options].`);
+}
+function assertSeverity(code, sev) {
+    if (!(sev in types_1.SEVERITY_ORDER)) {
+        throw new ConfigValidationError(`Invalid severity "${sev}" for rule "${code}". Expected one of: ${Object.keys(types_1.SEVERITY_ORDER).join(', ')}, off.`);
+    }
+}
+/**
+ * Apply a RulesConfig on top of a base rule map. Wildcard selectors apply
+ * first, exact codes second — so `{ 'P*': 'off', P1: 'high' }` disables all
+ * P-rules except P1.
+ */
+function applyRulesConfig(base, rulesConfig, strictUnknown = true) {
+    const out = new Map(base);
+    const entries = Object.entries(rulesConfig);
+    const wildcards = entries.filter(([sel]) => sel.endsWith('*'));
+    const exacts = entries.filter(([sel]) => !sel.endsWith('*'));
+    for (const [selector, setting] of [...wildcards, ...exacts]) {
+        if (!selector.endsWith('*') && !(0, registry_1.isKnownRule)(selector)) {
+            if (strictUnknown) {
+                throw new ConfigValidationError(`Unknown rule code "${selector}". Known rules: ${registry_1.RULES.map((r) => r.code).join(', ')}.`);
+            }
+            continue;
+        }
+        for (const code of (0, registry_1.expandRuleSelector)(selector)) {
+            out.set(code, parseSetting(code, setting));
+        }
+    }
+    return out;
+}
+/** Base rule map: every registered rule enabled at its default severity. */
+function defaultRuleMap() {
+    return new Map(registry_1.RULES.map((r) => [r.code, { enabled: true, severity: r.defaultSeverity }]));
+}
+/** Resolve the rule + override portion of a merged SafegresConfig. */
+function resolveRules(config) {
+    let rules = defaultRuleMap();
+    if (config.rules) {
+        rules = applyRulesConfig(rules, config.rules);
+    }
+    if (config.perf?.rules) {
+        assertPerfSelectors(config.perf.rules);
+        rules = applyRulesConfig(rules, config.perf.rules);
+    }
+    const overrides = config.overrides ?? [];
+    for (const o of overrides) {
+        if (!Array.isArray(o.tables) || o.tables.length === 0) {
+            throw new ConfigValidationError('Every "overrides" entry needs a non-empty "tables" array.');
+        }
+        // Validate override rule settings eagerly.
+        applyRulesConfig(rules, o.rules ?? {});
+    }
+    const publicRead = config.public?.read;
+    if (publicRead !== undefined) {
+        if (!Array.isArray(publicRead) || publicRead.some((p) => typeof p !== 'string' || p.length === 0)) {
+            throw new ConfigValidationError('"public.read" must be an array of non-empty schema.table glob patterns.');
+        }
+    }
+    const perfIgnore = config.perf?.ignore;
+    if (perfIgnore !== undefined) {
+        if (!Array.isArray(perfIgnore) || perfIgnore.some((p) => typeof p !== 'string' || p.length === 0)) {
+            throw new ConfigValidationError('"perf.ignore" must be an array of non-empty schema.table glob patterns.');
+        }
+    }
+    const ignoredExtensions = config.extensions?.ignore;
+    if (ignoredExtensions !== undefined) {
+        if (!Array.isArray(ignoredExtensions)
+            || ignoredExtensions.some((e) => typeof e !== 'string' || e.length === 0)) {
+            throw new ConfigValidationError('"extensions.ignore" must be an array of non-empty extension names.');
+        }
+    }
+    return { rules, overrides };
+}
+/**
+ * `perf.rules` may only retune perf-dimension codes — otherwise a security
+ * rule would silently change behind the perf flag.
+ */
+function assertPerfSelectors(rules) {
+    for (const selector of Object.keys(rules)) {
+        const codes = (0, registry_1.expandRuleSelector)(selector);
+        if (codes.length === 0) {
+            throw new ConfigValidationError(`Unknown rule code "${selector}" in "perf.rules". Perf rules: ${perfRuleCodes().join(', ')}.`);
+        }
+        const security = codes.filter((code) => (0, registry_1.dimensionOf)(registry_1.RULES_BY_CODE.get(code)) !== 'perf');
+        if (security.length > 0) {
+            throw new ConfigValidationError(`"perf.rules" may only configure perf-dimension rules; "${selector}" matches security rule(s) `
+                + `${security.join(', ')}. Configure those under the top-level "rules".`);
+        }
+    }
+}
+/** Rule codes belonging to a scoring dimension. */
+function ruleCodesForDimension(dimension) {
+    return registry_1.RULES.filter((r) => (0, registry_1.dimensionOf)(r) === dimension).map((r) => r.code);
+}
+function perfRuleCodes() {
+    return ruleCodesForDimension('perf');
+}
+/** Simple `*` glob match against a qualified `schema.table` name. */
+function matchTablePattern(pattern, qualified) {
+    const re = new RegExp(`^${pattern.split('*').map(escapeRegExp).join('.*')}$`);
+    return re.test(qualified);
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * The effective rule settings for one table: base rules plus any matching
+ * override entries (later entries win).
+ */
+function rulesForTable(resolved, schema, table) {
+    const qualified = `${schema}.${table}`;
+    let rules = resolved.rules;
+    for (const o of resolved.overrides) {
+        if (o.tables.some((p) => matchTablePattern(p, qualified))) {
+            rules = applyRulesConfig(rules, o.rules ?? {});
+        }
+    }
+    return rules;
+}
+/**
+ * Apply resolved rules to raw findings: drop findings for disabled rules and
+ * restamp severities from config (respecting per-table overrides).
+ */
+function applyRulesToFindings(resolved, findings) {
+    const out = [];
+    for (const f of findings) {
+        const rules = f.schema && f.table ? rulesForTable(resolved, f.schema, f.table) : resolved.rules;
+        const rule = rules.get(f.code);
+        if (!rule) {
+            out.push(f); // unknown/unregistered code — pass through untouched
+            continue;
+        }
+        if (!rule.enabled)
+            continue;
+        out.push(f.severity === rule.severity ? f : { ...f, severity: rule.severity });
+    }
+    return out;
+}
+/**
+ * True when every AST-scoped rule is disabled (lets the audit skip parsing).
+ *
+ * The policy-aware index rules (X2–X4) are AST-scoped but only run when the
+ * perf dimension is on, so they hold parsing open only in that mode.
+ */
+function allAstRulesDisabled(resolved, options = {}) {
+    const astCodes = registry_1.RULES
+        .filter((r) => r.scope === 'policy-ast')
+        .filter((r) => options.perf || r.category !== 'index')
+        .map((r) => r.code);
+    const base = astCodes.every((code) => resolved.rules.get(code)?.enabled === false);
+    if (!base)
+        return false;
+    // An override could re-enable an AST rule for some table.
+    for (const o of resolved.overrides) {
+        const merged = applyRulesConfig(resolved.rules, o.rules ?? {});
+        if (astCodes.some((code) => merged.get(code)?.enabled))
+            return false;
+    }
+    return true;
+}

package/config/schema.d.ts

@@ -0,0 +1,54 @@
+import type { SafegresConfig } from './types';
+/**
+ * The shape of the config file, as data: what an editor completes against
+ * (JSON Schema, via `toJsonSchema`) and what a load validates against, from
+ * one declaration.
+ *
+ * Drift is a compile error, not a stale file. `Shape<T>` maps over
+ * `Required<T>`, so a key added to `SafegresConfig` that nobody described
+ * here fails to typecheck — which is the only reason a hand-written schema
+ * for a growing interface is defensible at all.
+ */
+export type Shape<T> = {
+    [K in keyof Required<T>]: Node;
+};
+/** One described value. `any` is the honest answer for a live JS object. */
+export type Node = {
+    type: 'any';
+    description: string;
+} | {
+    type: 'string';
+    description: string;
+    enum?: readonly string[];
+} | {
+    type: 'number';
+    description: string;
+} | {
+    type: 'boolean';
+    description: string;
+} | {
+    type: 'array';
+    description: string;
+    items: Node;
+} | {
+    type: 'object';
+    description: string;
+    properties: Record<string, Node>;
+}
+/** A map with arbitrary keys — `rules`, `failOn.planes`, … */
+ | {
+    type: 'record';
+    description: string;
+    values: Node;
+}
+/** A key whose value may be more than one of the above. */
+ | {
+    type: 'union';
+    description: string;
+    of: Node[];
+};
+/** The config file, described. */
+export declare const CONFIG_SHAPE: Shape<SafegresConfig>;
+export declare const SCHEMA_ID = "https://raw.githubusercontent.com/constructive-io/constructive/main/packages/safegres/schema/safegres.schema.json";
+/** The described shape as a draft-07 JSON Schema, for editors. */
+export declare function toJsonSchema(): Record<string, unknown>;

package/config/schema.js

@@ -0,0 +1,269 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCHEMA_ID = exports.CONFIG_SHAPE = void 0;
+exports.toJsonSchema = toJsonSchema;
+const str = (description, values) => values ? { type: 'string', description, enum: values } : { type: 'string', description };
+const num = (description) => ({ type: 'number', description });
+const bool = (description) => ({ type: 'boolean', description });
+const list = (description, items) => ({ type: 'array', description, items });
+const obj = (description, properties) => ({
+    type: 'object',
+    description,
+    properties: properties
+});
+const oneOf = (description, ...of) => ({ type: 'union', description, of });
+const GRADES = ['A+', 'A', 'B', 'C', 'D', 'F'];
+const SEVERITIES = ['critical', 'high', 'medium', 'low', 'info'];
+/** `'off' | Severity | [Severity, options]`. */
+const RULE_SETTING = oneOf('off, a severity, or [severity, options]', str('Rule setting', ['off', ...SEVERITIES]), list('Severity plus rule options', { type: 'any', description: 'Severity or options object' }));
+const RULES = {
+    type: 'record',
+    description: 'Rule settings by code or prefix wildcard (A*, P*, *). Exact codes win.',
+    values: RULE_SETTING
+};
+const PLANE = {
+    name: str('Plane identifier, e.g. api, direct:app, internal'),
+    kind: str('What kind of access path this plane describes', ['api', 'role', 'schema']),
+    primary: bool('Make this plane the headline score. At most one plane may claim it.'),
+    schemas: list('Schemas this plane reaches', str('Schema name')),
+    roles: list('Roles this plane grants access as', str('Role name')),
+    anonRoles: list('The subset of roles reachable without authenticating', str('Role name'))
+};
+const EXPOSURE = {
+    resolver: str('How to resolve the exposed surface', ['static', 'constructive', 'postgraphile']),
+    adapters: list('Exposure adapters: built-in names, or ExposureAdapter objects in a JS/TS config', { type: 'any', description: 'Built-in name or adapter object' }),
+    schemas: list('Schemas reachable from the exposed APIs', str('Schema name')),
+    roles: list('Roles reachable at the API edge', str('Role name')),
+    anonRoles: list('The subset of roles an unauthenticated caller arrives as', str('Role name')),
+    name: str('Name of the primary plane. Default api.'),
+    reach: bool('Let adapters narrow a plane to the relations the API can address. Default true.'),
+    planes: list('Additional access planes to grade', obj('One graded access plane', PLANE))
+};
+const SCORING = {
+    model: str('Scoring model. Default density.', ['density', 'weighted']),
+    weights: { type: 'record', description: 'Points deducted per finding severity', values: num('Points') },
+    perRuleWeights: { type: 'record', description: 'Per-rule weight, beating the severity weight', values: num('Points') },
+    maxDeductionPerRule: num('Cap on one rule\u2019s total deduction (weighted model)'),
+    maxRuleDensity: oneOf('Cap on one rule\u2019s contribution, as a fraction of the points that fail an audit alone. Default 0.5; false disables the cap.', num('Fraction'), bool('false to disable')),
+    failClosedWeight: num('Multiplier for fail-closed findings. Default 0.'),
+    densityK: num('Density falloff constant. Default 0.17.'),
+    unknownExposureCap: oneOf('Maximum score when no exposure surface resolves. Default 80; false disables the cap.', num('Cap'), bool('false to disable')),
+    floorOnCritical: oneOf('Grade any critical finding floors the score at. Default C; false disables.', str('Grade', GRADES), bool('false to disable')),
+    gradeBands: { type: 'record', description: 'Minimum score for each grade', values: num('Score') }
+};
+const PERF_SCORING = {
+    ...SCORING,
+    includeStats: bool('Whether S* runtime-statistics findings count toward the perf score. Default true.')
+};
+const PERF_STATS = {
+    enabled: bool('Collect runtime statistics without passing --stats'),
+    minRows: num('Ignore tables with fewer live rows than this. Default 1000.'),
+    seqScanRatio: num('S1 fires above this seq-scan/index-scan ratio. Default 10.'),
+    minIndexBytes: num('S2 ignores indexes smaller than this. Default 1048576.'),
+    deadTupleRatio: num('S3 fires above this dead/live tuple ratio. Default 0.2.'),
+    minTimeShare: num('S4 reports statements at or above this share of total time. Default 0.05.'),
+    topStatements: num('S4 reports at most this many statements. Default 5.')
+};
+const PERF_EXPLAIN = {
+    enabled: bool('Probe findings with EXPLAIN without passing --explain'),
+    minRows: num('Below this planner row estimate a seq scan is right. Default 1000.')
+};
+const PERF_PATHS = {
+    infer: bool('Collect access-path signals for every foreign key. Default true.'),
+    minPointers: num('Write-once pointers before the config-record signal fires. Default 2.'),
+    onWriteOncePointer: str('What X1 does with a shape-only write-once pointer', [
+        'report',
+        'demote',
+        'suppress'
+    ])
+};
+const PERF = {
+    enabled: bool('Collect and score perf findings without passing --perf'),
+    rules: RULES,
+    ignore: list('Table globs whose perf findings are intentional', str('schema.table glob')),
+    scoring: obj('Scoring for the perf axis', PERF_SCORING),
+    stats: obj('Runtime statistics (S*)', PERF_STATS),
+    explain: obj('Planner proof (--explain)', PERF_EXPLAIN),
+    baseline: str('Baseline of accepted perf debt; its presence enables the diff'),
+    failOnNew: bool('Exit non-zero on a perf finding absent from the baseline'),
+    paths: obj('Access-path classification, which decides whether X1 applies', PERF_PATHS)
+};
+const SCORECARD_SELECT = {
+    rules: list('Rule codes or C* prefix wildcards to grade', str('Rule code or wildcard')),
+    exclude: list('Rule codes or wildcards to drop after rules selected', str('Rule code or wildcard')),
+    dimension: str('Which axis: security (default), perf, or all', ['security', 'perf', 'all']),
+    roles: list('Only findings about these roles', str('Role name')),
+    planes: list('Only findings reachable on these access planes', str('Plane name')),
+    schemas: list('Only findings in these schemas', str('Schema name')),
+    direction: str('fail-open leaks, fail-closed denials, or any', ['fail-open', 'fail-closed', 'none', 'any']),
+    minSeverity: str('Drop findings below this severity before scoring', SEVERITIES),
+    exposure: str('exposed (default) grades the API surface; all ignores exposure', ['exposed', 'all']),
+    acknowledged: str('include grades acknowledged findings too. Default skip.', ['skip', 'include']),
+    severities: str('configured (default) uses this config\u2019s severities; declared uses each rule\u2019s registry default', ['configured', 'declared']),
+    denominator: str('Density denominator: exposed relations (default) or all', ['exposed', 'all'])
+};
+const SCORECARD = {
+    ...SCORING,
+    title: str('Heading for reports. Defaults to the config key.'),
+    description: str('What decision this score informs. Rendered with it.'),
+    select: obj('Which findings it grades', SCORECARD_SELECT)
+};
+const FAIL_ON_PLANE = {
+    score: num('Exit non-zero below this plane score'),
+    grade: str('Exit non-zero below this plane grade', GRADES)
+};
+const FAIL_ON = {
+    severity: str('Exit non-zero on any finding at or above this severity', SEVERITIES),
+    score: num('Exit non-zero below this security score'),
+    grade: str('Exit non-zero below this security grade', GRADES),
+    perfScore: num('Exit non-zero below this perf score'),
+    perfGrade: str('Exit non-zero below this perf grade', GRADES),
+    planes: {
+        type: 'record',
+        description: 'Per-plane gates, keyed by plane name. A floor is the useful shape.',
+        values: obj('One plane gate', FAIL_ON_PLANE)
+    },
+    scorecards: {
+        type: 'record',
+        description: 'Per-scorecard gates, keyed by scorecard name.',
+        values: obj('One scorecard gate', FAIL_ON_PLANE)
+    }
+};
+const GITHUB_COMMENT = {
+    sticky: bool('Reuse one comment per PR instead of appending. Default true.'),
+    sections: list('Sections to include. Default scores, delta, new-findings. `report` adds the '
+        + 'markdown report (`findings` is its old name).', str('Section', ['scores', 'delta', 'new-findings', 'report', 'findings', 'planes'])),
+    detail: str('How much of the report the report section carries. Default summary.', [
+        'summary',
+        'normal',
+        'verbose'
+    ])
+};
+const GITHUB = {
+    summary: list('Scores in the job summary, in order (security, perf, planes:<glob>)', str('Score')),
+    comment: obj('Sticky PR comment', GITHUB_COMMENT),
+    annotations: str('Which findings become annotations. Default gate-failures.', [
+        'all',
+        'gate-failures',
+        'none'
+    ]),
+    detail: str('How much of the report goes in the job summary. Default normal.', [
+        'summary',
+        'normal',
+        'verbose'
+    ]),
+    badges: bool('Render scores as colored shields.io badges. Default true.')
+};
+const REPORT = {
+    planes: list('Planes to render, by name or glob', str('Plane name or glob')),
+    dimensions: list('Dimensions to render. Default both.', str('Dimension', ['security', 'perf'])),
+    github: obj('GitHub Actions output', GITHUB)
+};
+const OVERRIDE = {
+    tables: list('schema.table globs this entry applies to', str('schema.table glob')),
+    rules: RULES
+};
+const OUTPUTS = {
+    dir: str('Write safegres.{json,md,sarif} into this directory'),
+    json: str('Path for the JSON report'),
+    markdown: str('Path for the Markdown report'),
+    sarif: str('Path for the SARIF report'),
+    sarifSources: str('Root scanned to resolve SARIF findings to SQL source lines'),
+    snapshot: str('Path for the aggregate-only snapshot, for a later compare'),
+    githubComment: str('Path for the rendered sticky PR comment')
+};
+const SOURCE = {
+    pgpm: str('Deploy the pgpm workspace at this path into an ephemeral database and audit it')
+};
+const CALL_GRAPH = {
+    enabled: bool('Build the call-graph audit without passing --call-graph'),
+    baseline: str('Baseline of accepted trust boundaries; enables the diff'),
+    failOnNew: bool('Exit non-zero on a boundary absent from the baseline')
+};
+const EVAL = {
+    corpus: str('Corpus directory of <id>/{case.json,schema.sql}'),
+    preset: str('Preset every case is graded under. Default recommended.'),
+    cases: list('Case ids (or id prefixes) to run', str('Case id'))
+};
+const PUBLIC = {
+    read: list('Table globs whose open SELECT policies are by design', str('schema.table glob'))
+};
+const EXTENSIONS = {
+    skipOwned: bool('Skip relations an extension owns. Default true.'),
+    ignore: list('Extension names whose schemas are skipped wholesale', str('Extension name'))
+};
+/** The config file, described. */
+exports.CONFIG_SHAPE = {
+    extends: oneOf('Presets (safegres:recommended, \u2026), relative file paths, or npm packages', str('Preset name, path, or package'), list('Several, lowest precedence first', str('Preset name, path, or package'))),
+    exposure: obj('The exposed API surface \u2014 what the score is computed against', EXPOSURE),
+    public: obj('Declared-public surface: open reads that are deliberate', PUBLIC),
+    extensions: obj('How to treat objects belonging to installed extensions', EXTENSIONS),
+    perf: obj('The optional performance dimension', PERF),
+    schemas: list('Only audit these schemas', str('Schema name')),
+    excludeSchemas: list('Never audit these schemas', str('Schema name')),
+    roles: list('Only audit these roles', str('Role name')),
+    excludeRoles: list('Never audit these roles', str('Role name')),
+    rules: RULES,
+    overrides: list('Per-scope retuning, ESLint overrides-style', obj('One override', OVERRIDE)),
+    scoring: obj('The security scoring model', SCORING),
+    scorecards: {
+        type: 'record',
+        description: 'Named scores over slices of the same findings, keyed by name',
+        values: obj('One scorecard', SCORECARD)
+    },
+    failOn: obj('Gates \u2014 what makes the run exit non-zero', FAIL_ON),
+    source: obj('Where the database to audit comes from', SOURCE),
+    outputs: obj('Files a single run writes', OUTPUTS),
+    callGraph: obj('The unscored call-graph audit and its baseline', CALL_GRAPH),
+    report: obj('What a rendered report shows \u2014 selection, not analysis', REPORT),
+    eval: obj('Defaults for safegres eval', EVAL)
+};
+exports.SCHEMA_ID = 'https://raw.githubusercontent.com/constructive-io/constructive/main/packages/safegres/schema/safegres.schema.json';
+/** The described shape as a draft-07 JSON Schema, for editors. */
+function toJsonSchema() {
+    return {
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        $id: exports.SCHEMA_ID,
+        title: 'safegres configuration',
+        description: 'Configuration for safegres, the PostgreSQL security and performance auditor. '
+            + 'Discovered as safegres.config.{ts,js,mjs,cjs}, .safegresrc{,.json,.yaml,.yml,.js}, '
+            + 'safegres.json, or the "safegres" key in package.json.',
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            $schema: { type: 'string', description: 'JSON Schema reference, for editor completion.' },
+            ...objectProperties(exports.CONFIG_SHAPE)
+        }
+    };
+}
+function objectProperties(shape) {
+    const out = {};
+    for (const [key, node] of Object.entries(shape))
+        out[key] = jsonNode(node);
+    return out;
+}
+function jsonNode(node) {
+    const description = node.description;
+    switch (node.type) {
+        case 'any':
+            return { description };
+        case 'string':
+            return node.enum ? { type: 'string', enum: [...node.enum], description } : { type: 'string', description };
+        case 'number':
+        case 'boolean':
+            return { type: node.type, description };
+        case 'array':
+            return { type: 'array', items: jsonNode(node.items), description };
+        case 'object':
+            return {
+                type: 'object',
+                additionalProperties: false,
+                properties: objectProperties(node.properties),
+                description
+            };
+        case 'record':
+            return { type: 'object', additionalProperties: jsonNode(node.values), description };
+        case 'union':
+            return { anyOf: node.of.map(jsonNode), description };
+    }
+}