@safegres/test 0.0.1 → 1.30.7

package/esm/types.d.ts

@@ -0,0 +1,292 @@
+/**
+ * Report types for the safegres audit.
+ *
+ * Kept intentionally minimal and dependency-free so they can be imported
+ * by downstream packages (e.g. `@constructive-db/rls-audit-constructive`)
+ * without pulling in `pg` or `pgsql-parser`.
+ */
+export type Severity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+/**
+ * Which way a finding fails:
+ * - `fail-open`   — the untrusted side can read/write more than intended (a leak).
+ * - `fail-closed` — the operation is denied at runtime; an availability/hygiene
+ *                   concern, not an exposure. Excluded from the score by default.
+ * - `neutral`     — directionless (performance, meta).
+ */
+export type Direction = 'fail-open' | 'fail-closed' | 'neutral';
+/**
+ * Which axis a finding is scored on. `security` findings drive `report.score`;
+ * `perf` findings drive `report.perf.score`. The two are never mixed — a
+ * database can be an A+ on security and a D on index hygiene, and both
+ * numbers stay meaningful.
+ */
+export type Dimension = 'security' | 'perf';
+export declare const SEVERITY_ORDER: Record<Severity, number>;
+export interface Finding {
+    /** Finding code, e.g. `A1`, `P7`. Stable across versions. */
+    code: string;
+    severity: Severity;
+    /** High-level bucket — helps renderers group findings. */
+    category: 'flags' | 'coverage' | 'anti-pattern' | 'index' | 'sync' | 'match' | 'meta' | 'convention';
+    /** Leak vs deny vs directionless. Stamped from the rule registry. */
+    direction?: Direction;
+    /** Scoring axis. Stamped from the rule registry; defaults to `security`. */
+    dimension?: Dimension;
+    /**
+     * Whether the finding's table is on the resolved exposure surface — i.e.
+     * reachable on the *primary* plane. `undefined` when no exposure surface is
+     * known (everything is assumed reachable).
+     */
+    exposed?: boolean;
+    /**
+     * Every access plane the finding is reachable on, by name. A relation that
+     * is internal to the API can still be reachable by a role holding a direct
+     * connection, and this is where that shows up. Not part of a finding's
+     * identity: baselines and comparisons key on the finding, not on who can
+     * reach it.
+     */
+    planes?: string[];
+    /**
+     * The finding is acknowledged by config as intentional (e.g. an open read
+     * on a table declared in `public.read`) — reported, but excluded from the
+     * score.
+     */
+    acknowledged?: boolean;
+    /** Schema-qualified location, where applicable. */
+    schema?: string;
+    table?: string;
+    policy?: string;
+    role?: string;
+    privilege?: string;
+    /** Human-readable summary. */
+    message: string;
+    /** Optional remediation hint / pointer to docs. */
+    hint?: string;
+    /** Optional machine-readable extras (AST nodes, offending function name, …). */
+    context?: Record<string, unknown>;
+    /**
+     * Proof attached by `--explain`: the plan the database produced for the
+     * query shape this finding is a claim about.
+     */
+    evidence?: FindingEvidence;
+}
+/**
+ * Planner evidence for a finding. `refuted` means the planner disagreed with
+ * the catalog inference — the finding is reported but no longer scored.
+ */
+export interface FindingEvidence {
+    source: 'explain';
+    status: 'confirmed' | 'refuted' | 'inconclusive';
+    /** The probe query, with parameters left unbound. */
+    probe: string;
+    /** Plan node types, outermost first. */
+    plan: string;
+    /** Why an inconclusive probe was inconclusive. */
+    note?: string;
+}
+export interface Summary {
+    critical: number;
+    high: number;
+    medium: number;
+    low: number;
+    info: number;
+}
+/**
+ * One graded access plane: a way into the database, with its own score.
+ *
+ * The primary plane is the declared API surface, and its score *is*
+ * `report.score` — secondary planes never move it. They answer the question
+ * the headline cannot: what does this database grade for somebody who does
+ * not come through the API?
+ */
+export interface PlaneReport {
+    name: string;
+    kind: 'api' | 'role' | 'schema';
+    /** The headline plane. Exactly one plane is primary. */
+    primary: boolean;
+    /** Adapter name, `config`, or `none`. */
+    source: string;
+    schemas: string[];
+    roles?: string[];
+    /** Relations the plane reaches (the density denominator). */
+    exposedTables: number;
+    /**
+     * Relations in the plane's schemas its API cannot address, and which are
+     * therefore excluded from `exposedTables`.
+     */
+    unaddressableTables?: number;
+    /** Role planes: the most direct way the reach arrives. */
+    reachedVia?: 'grant' | 'PUBLIC' | 'inheritance';
+    /** Security score for this plane, same model as the headline. */
+    score: import('./score/score').Score;
+    /** Severity counts for the findings reachable on this plane. */
+    summary: Summary;
+    /** Present when the plane was reported but deliberately not graded. */
+    skipped?: string;
+}
+/** The resolved exposure surface an audit was scored against. */
+export interface ExposureReport {
+    /** True when a surface was configured or auto-resolved. */
+    known: boolean;
+    /** Where the surface came from: an adapter name, `config`, or `none`. */
+    source: string;
+    /** Name of the primary plane. */
+    plane?: string;
+    /** Schemas reachable from the exposed APIs. Empty when unknown. */
+    schemas: string[];
+    /** API-edge roles, when the resolver can discover them. */
+    roles?: string[];
+    /**
+     * The subset of `roles` an unauthenticated caller arrives as — the answer to
+     * "what can someone with no credentials reach?". Omitted when none resolve.
+     */
+    anonRoles?: string[];
+    /** Tables on the exposed surface (the score denominator). */
+    exposedTables: number;
+    /** All tables the audit introspected. */
+    totalTables: number;
+    /**
+     * Relations in the exposed schemas the generated API cannot address, and
+     * which are therefore excluded from `exposedTables`. Present only when an
+     * adapter could prove it; listed rather than counted, because a subtraction
+     * from the score denominator should be readable.
+     */
+    unaddressable?: import('./exposure/reach').UnreachableRelation[];
+}
+/**
+ * The optional performance dimension (`--perf`): index-hygiene and
+ * policy-cost findings, scored on their own 0-100 axis against the same
+ * exposure surface.
+ */
+export interface PerfReport {
+    /** Perf-dimension findings (also present in `report.findings`). */
+    findings: Finding[];
+    summary: Summary;
+    /** Perf score — computed only over perf-dimension findings. */
+    score: import('./score/score').Score;
+    /**
+     * Diff against a committed perf baseline (`--perf-baseline`): which findings
+     * are new debt, which were fixed, which are accepted.
+     */
+    diff?: import('./perf/baseline').PerfDiff;
+    /** Runtime-statistics provenance, present when the audit ran with `--stats`. */
+    stats?: PerfStatsReport;
+    /**
+     * Access-path classification: how many foreign keys X1 was not applied to,
+     * because nothing reads them. Reported so a suppression this broad is never
+     * silent.
+     */
+    paths?: PerfPathsReport;
+    /** Planner-proof summary, present when the audit ran with `--explain`. */
+    explain?: import('./perf/explain').ExplainReport;
+}
+/**
+ * What the access-path signals found, and what X1 did about it. Reported so
+ * the evidence is visible even when — as by default — it changes nothing.
+ */
+export interface PerfPathsReport {
+    /** Foreign keys examined. */
+    total: number;
+    /** Keys with a `read` signal: an RLS policy or a view names the column. */
+    read: number;
+    /** Keys whose only signals are shape: they look like provisioning pointers. */
+    writeOnceShaped: number;
+    /** Tables carrying enough write-once pointers to look like config records. */
+    tables: number;
+    /** What X1 did with the write-once-shaped keys. */
+    onWriteOncePointer: 'report' | 'demote' | 'suppress';
+    /**
+     * Keys whose reverse relation an API behavior declares absent. Reported
+     * only: one missing path is not proof that nothing traverses the key.
+     */
+    declaredHidden?: number;
+}
+/** Where the `S*` findings' numbers came from, and how much to trust them. */
+export interface PerfStatsReport {
+    source: 'live';
+    /** Tables whose cumulative statistics were read. */
+    tables: number;
+    /** When the counters were last reset — the window the numbers describe. */
+    statsReset: string | null;
+    /** Whether `S*` findings counted toward the perf score. */
+    scored: boolean;
+    /** Non-fatal gaps, e.g. `pg_stat_statements` not installed. */
+    notes?: string[];
+}
+/**
+ * The per-role exposure report: the direct answer to "what can role X
+ * access?", computed over effective grants (direct, TO PUBLIC, inherited)
+ * for the configured untrusted roles. Present whenever such roles are
+ * configured (e.g. L5/R1 options), independent of any findings.
+ */
+export interface RoleAccessReport {
+    roles: import('./checks/lattice').RoleAccessEntry[];
+}
+export interface Report {
+    version: string;
+    generatedAt: string;
+    /**
+     * What ruler this score was measured with: a fingerprint of the resolved
+     * configuration, and whether the run refused local config entirely. Two
+     * reports are comparable when their fingerprints match.
+     */
+    provenance?: import('./config/fingerprint').Provenance;
+    summary: Summary;
+    findings: Finding[];
+    /** Config-driven audit score (weighted deductions, 0-100 + grade). */
+    score?: import('./score/score').Score;
+    /** Performance dimension, present when the audit ran with `perf` enabled. */
+    perf?: PerfReport;
+    /** The exposure surface the score was computed against. */
+    exposure?: ExposureReport;
+    /**
+     * Every graded access plane, primary first. `planes[0].score` is
+     * `report.score`; the rest are advisory unless `failOn.planes` opts them
+     * into gating.
+     */
+    planes?: PlaneReport[];
+    /**
+     * Named scores over slices of the same findings (`scorecards` config), the
+     * reserved `default` and `raw` cards first. Different teams gate on
+     * different questions; this is where each one's answer lives, computed
+     * from the one set of findings so they can never disagree about the facts.
+     */
+    scorecards?: import('./score/scorecards').ScorecardReport[];
+    /** Effective per-role access, for the configured untrusted roles. */
+    roleAccess?: RoleAccessReport;
+    /**
+     * L21's `granted − reachable` result: per role, the EXECUTE grants that are
+     * revocable, the ones retained (each with the reachability path that proves
+     * it load-bearing), and the ones suppressed because the closure could not be
+     * fully read. The retained-and-suppressed lists are the point of the rule —
+     * they are what a human reviews before dropping anything.
+     */
+    revocableGrants?: import('./checks/revocable-grants').RevocableGrantsReport;
+    /**
+     * Unscored call-graph audit (`--call-graph`): trust boundaries reachable
+     * from the exposed entry points, for human review.
+     */
+    callGraph?: import('./callgraph/graph').CallGraphReport;
+    /**
+     * Diff against a committed call-graph baseline (`--baseline`): trust
+     * boundaries added since the snapshot (require sign-off) and boundaries
+     * that were resolved.
+     */
+    callGraphDiff?: import('./callgraph/baseline').CallGraphDiff;
+    /**
+     * Movement against a previous run (`--compare`): score deltas, severity
+     * deltas and the rules that changed. A report describes a database; this is
+     * the only part that describes a change to one.
+     */
+    comparison?: import('./report/compare').ReportComparison;
+    /**
+     * Why there is no `comparison` (`--compare-skipped`): a baseline was looked
+     * for and none qualified. Silence would read as "nothing moved", which is
+     * how a delta nobody could see went wrong unnoticed; the absolute score and
+     * the perf ratchet still gate the run, and this line says so.
+     */
+    comparisonSkipped?: string;
+}
+export declare function newSummary(): Summary;
+export declare function summarize(findings: Finding[]): Summary;
+export declare function meetsThreshold(sev: Severity, threshold: Severity): boolean;

package/esm/types.js

@@ -0,0 +1,26 @@
+/**
+ * Report types for the safegres audit.
+ *
+ * Kept intentionally minimal and dependency-free so they can be imported
+ * by downstream packages (e.g. `@constructive-db/rls-audit-constructive`)
+ * without pulling in `pg` or `pgsql-parser`.
+ */
+export const SEVERITY_ORDER = {
+    critical: 4,
+    high: 3,
+    medium: 2,
+    low: 1,
+    info: 0
+};
+export function newSummary() {
+    return { critical: 0, high: 0, medium: 0, low: 0, info: 0 };
+}
+export function summarize(findings) {
+    const s = newSummary();
+    for (const f of findings)
+        s[f.severity] += 1;
+    return s;
+}
+export function meetsThreshold(sev, threshold) {
+    return SEVERITY_ORDER[sev] >= SEVERITY_ORDER[threshold];
+}

package/esm/version.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The analyzer version stamped into every report and into the SARIF tool
+ * record. Read from package.json the same way the CLI reads it, rather than
+ * held in a generated constant: a constant only stays true if a sync step runs
+ * on the same commit lerna bumps the manifest, and it drifted (1.16.1 against a
+ * 1.18.0 manifest) precisely because it doesn't.
+ */
+export declare const version: string;

package/esm/version.js

@@ -0,0 +1,9 @@
+import { getPackageVersion } from '@inquirerer/utils';
+/**
+ * The analyzer version stamped into every report and into the SARIF tool
+ * record. Read from package.json the same way the CLI reads it, rather than
+ * held in a generated constant: a constant only stays true if a sync step runs
+ * on the same commit lerna bumps the manifest, and it drifted (1.16.1 against a
+ * 1.18.0 manifest) precisely because it doesn't.
+ */
+export const version = getPackageVersion(__dirname);

package/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[];