@safegres/test 0.0.1 → 1.30.7

package/checks/indexes.js

@@ -0,0 +1,263 @@
+"use strict";
+/**
+ * Structural index-hygiene checks (perf dimension, `X*`).
+ *
+ * Everything here is pure catalog analysis — deterministic, workload-free,
+ * and safe to run in CI against an empty database.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkUnindexedForeignKeys = checkUnindexedForeignKeys;
+exports.checkRedundantIndexes = checkRedundantIndexes;
+exports.checkMissingPrimaryKey = checkMissingPrimaryKey;
+exports.checkUnindexedSearchColumns = checkUnindexedSearchColumns;
+exports.checkUnindexedSortColumns = checkUnindexedSortColumns;
+const paths_1 = require("../pg/paths");
+/**
+ * X1: a foreign key with no index that can serve it.
+ *
+ * An index covers a FK when its *leading* columns are exactly the FK's
+ * columns (order among them is irrelevant for equality lookups) and it
+ * covers every row. Without one, `ON DELETE`/`ON UPDATE` checks on the
+ * referenced side and joins on the referencing side degrade to sequential
+ * scans.
+ *
+ * Partial and expression indexes do not count: the planner cannot rely on
+ * them for the referential-integrity lookup.
+ *
+ * `paths` supplies the access-path signals. They never remove a finding on
+ * their own — see {@link WriteOncePointerPolicy} and `classifyPaths`.
+ */
+function checkUnindexedForeignKeys(table, paths, onWriteOncePointer = 'report') {
+    // Partitions inherit their parent's indexes; the parent carries the finding.
+    if (table.isPartition)
+        return [];
+    const findings = [];
+    for (const fk of table.foreignKeys) {
+        if (fk.columns.length === 0)
+            continue;
+        if (table.indexes.some((idx) => indexCoversColumns(idx, fk.columns)))
+            continue;
+        const path = paths?.get((0, paths_1.pathKey)(table.schema, table.name, fk.name));
+        const writeOnceShaped = path?.assessment === 'write-once-shaped';
+        if (writeOnceShaped && onWriteOncePointer === 'suppress')
+            continue;
+        const cols = fk.columnNames.join(', ');
+        findings.push({
+            code: 'X1',
+            severity: 'medium',
+            category: 'index',
+            schema: table.schema,
+            table: table.name,
+            message: `Foreign key ${fk.name} on ${table.schema}.${table.name} (${cols}) has no covering index`,
+            hint: writeOnceShaped
+                ? `CREATE INDEX ON ${table.schema}.${table.name} (${cols}) — or, if nothing queries this relation, stop exposing it. ${path.signals.map((s) => s.detail).join('; ')}.`
+                : `CREATE INDEX ON ${table.schema}.${table.name} (${cols}); without it, deletes/updates on ${fk.references} and joins across this key scan the whole table.`,
+            context: {
+                constraint: fk.name,
+                columns: fk.columnNames,
+                references: fk.references,
+                ...(path ? { pathSignals: path.signals.map((s) => s.name), pathAssessment: path.assessment } : {})
+            }
+        });
+    }
+    return findings;
+}
+/**
+ * X5: an index that another index already serves.
+ *
+ * Two shapes: an exact duplicate, or a non-unique index whose columns are a
+ * leading-column prefix of a wider index. Both cost write throughput and
+ * disk for nothing. Constraint-backed indexes (PK/UNIQUE/EXCLUDE) are never
+ * reported — dropping them would drop the constraint.
+ *
+ * An index attached to a parent's partitioned index is never reported either:
+ * it can only be dropped with the parent's index, and the parent carries that
+ * finding once instead of every partition repeating it. An index created on
+ * the partition alone is the partition's own, and is reported there.
+ */
+function checkRedundantIndexes(table) {
+    const findings = [];
+    const candidates = new Set(table.indexes.filter((i) => !i.primary && !i.constraint && !i.partial && !i.expression && !i.unique && !i.attached));
+    for (const idx of candidates) {
+        const covering = table.indexes.find((other) => {
+            if (other.name === idx.name)
+                return false;
+            if (other.partial || other.expression)
+                return false;
+            if (other.method !== idx.method)
+                return false;
+            if (!isPrefix(idx.columns, other.columns))
+                return false;
+            // Exact duplicates: when both are droppable, report only one of the
+            // pair, deterministically.
+            if (idx.columns.length === other.columns.length
+                && candidates.has(other)
+                && idx.name < other.name)
+                return false;
+            return true;
+        });
+        if (!covering)
+            continue;
+        const duplicate = idx.columns.length === covering.columns.length;
+        findings.push({
+            code: 'X5',
+            severity: 'low',
+            category: 'index',
+            schema: table.schema,
+            table: table.name,
+            message: `Index ${idx.name} (${idx.columnNames.join(', ')}) is ${duplicate ? 'a duplicate of' : 'a leading-column prefix of'} `
+                + `${covering.name} (${covering.columnNames.join(', ')})`,
+            hint: `DROP INDEX ${table.schema}.${idx.name}; every query it serves is served by ${covering.name}.`,
+            context: { index: idx.name, coveredBy: covering.name, duplicate }
+        });
+    }
+    return findings;
+}
+/**
+ * X6: no primary key and no usable replica identity.
+ *
+ * Rows cannot be addressed individually: updates and deletes have no cheap
+ * lookup path, logical replication and CDC cannot identify old rows, and
+ * realtime/change-feed features break.
+ */
+function checkMissingPrimaryKey(table) {
+    if (table.isPartition)
+        return null;
+    if (table.hasPrimaryKey)
+        return null;
+    // `f` (FULL) and `i` (index) still give logical decoding an identity.
+    if (table.replicaIdentity === 'f' || table.replicaIdentity === 'i')
+        return null;
+    return {
+        code: 'X6',
+        severity: 'low',
+        category: 'index',
+        schema: table.schema,
+        table: table.name,
+        message: `${table.schema}.${table.name} has no primary key`,
+        hint: 'Add a primary key, or set REPLICA IDENTITY FULL / USING INDEX, so rows can be addressed by updates, deletes, and logical replication.',
+        context: { replicaIdentity: table.replicaIdentity }
+    };
+}
+/**
+ * Search column types that only perform with a specialised index, mapped to
+ * the access methods that can serve them.
+ *
+ * The column type *is* the declaration: `graphile-search` detects searchable
+ * columns by codec (tsvector → full-text filter, vector → similarity search),
+ * so a bare `tsvector` column is already an API promise. BM25 and pg_trgm are
+ * absent on purpose — they are discovered *from* their indexes, so a missing
+ * index means the feature was never exposed rather than exposed and slow.
+ */
+const SEARCH_TYPES = {
+    tsvector: {
+        methods: ['gin', 'gist'],
+        feature: 'full-text search',
+        example: 'USING gin (%s)'
+    },
+    vector: {
+        methods: ['hnsw', 'ivfflat'],
+        feature: 'vector similarity search',
+        example: 'USING hnsw (%s vector_cosine_ops)'
+    },
+    halfvec: {
+        methods: ['hnsw', 'ivfflat'],
+        feature: 'vector similarity search',
+        example: 'USING hnsw (%s halfvec_cosine_ops)'
+    },
+    sparsevec: {
+        methods: ['hnsw'],
+        feature: 'vector similarity search',
+        example: 'USING hnsw (%s sparsevec_cosine_ops)'
+    }
+};
+/**
+ * X7: a search column with no index the search can use.
+ *
+ * A `tsvector` or `vector` column is exposed as a search field by
+ * `graphile-search` purely from its type — the schema promises a fast path.
+ * Without a GIN/GiST (full-text) or HNSW/IVFFlat (vector) index the promise
+ * is served by a sequential scan plus a per-row distance or match computation,
+ * which is the single worst plan the API can produce.
+ */
+function checkUnindexedSearchColumns(table) {
+    if (table.isPartition)
+        return [];
+    const findings = [];
+    for (const column of table.columns) {
+        const spec = SEARCH_TYPES[column.baseType];
+        if (!spec)
+            continue;
+        const served = table.indexes.some((idx) => spec.methods.includes(idx.method) && idx.columns.includes(column.attnum));
+        if (served)
+            continue;
+        findings.push({
+            code: 'X7',
+            severity: 'medium',
+            category: 'index',
+            schema: table.schema,
+            table: table.name,
+            message: `${table.schema}.${table.name}.${column.name} is a ${column.type} column with no ${spec.methods.join('/')} index — ${spec.feature} scans the whole table`,
+            hint: `CREATE INDEX ON ${table.schema}.${table.name} ${spec.example.replace('%s', column.name)};`,
+            context: { column: column.name, type: column.type, methods: spec.methods }
+        });
+    }
+    return findings;
+}
+/** Types whose columns are, in practice, what a connection is sorted by. */
+const SORT_TYPES = new Set(['timestamptz', 'timestamp', 'date']);
+/**
+ * X8: a sort-shaped column that leads no index.
+ *
+ * Every PostGraphile connection can be ordered by any column and paginated
+ * with a cursor over that order. Sorting on an unindexed column forces a full
+ * sort of the (RLS-filtered) result on every page, and keyset pagination
+ * degenerates into a scan-and-discard. Timestamp columns are singled out
+ * because they are what feeds are actually ordered by — a heuristic, hence
+ * `info` by default; turn it off with `perf.rules: { "X8": "off" }`.
+ */
+function checkUnindexedSortColumns(table) {
+    if (table.isPartition)
+        return [];
+    // A leading column can serve both ASC and DESC ordering; a trailing one
+    // cannot serve the sort on its own.
+    const leading = new Set(table.indexes.filter((i) => !i.partial).map((i) => i.columns[0]).filter((c) => c !== undefined));
+    const findings = [];
+    for (const column of table.columns) {
+        if (!SORT_TYPES.has(column.baseType))
+            continue;
+        if (leading.has(column.attnum))
+            continue;
+        findings.push({
+            code: 'X8',
+            severity: 'info',
+            category: 'index',
+            schema: table.schema,
+            table: table.name,
+            message: `${table.schema}.${table.name}.${column.name} (${column.type}) leads no index — ordering or paginating a connection by it sorts the whole table`,
+            hint: `If the API orders by this column, CREATE INDEX ON ${table.schema}.${table.name} (${column.name} DESC); otherwise disable X8 or add the table to perf.ignore.`,
+            context: { column: column.name, type: column.type }
+        });
+    }
+    return findings;
+}
+/**
+ * True when `index` can serve an equality lookup on exactly `columns`:
+ * its leading columns are that same set, and it covers every row.
+ */
+function indexCoversColumns(index, columns) {
+    if (index.partial || index.expression)
+        return false;
+    if (index.method !== 'btree')
+        return false;
+    if (index.columns.length < columns.length)
+        return false;
+    const leading = new Set(index.columns.slice(0, columns.length));
+    return columns.every((c) => leading.has(c));
+}
+/** True when `a` is a leading-column prefix of `b` (`a` may equal `b`). */
+function isPrefix(a, b) {
+    if (a.length > b.length)
+        return false;
+    return a.every((col, i) => b[i] === col);
+}

package/checks/lattice.d.ts

@@ -0,0 +1,179 @@
+/**
+ * The grant/RLS/policy lattice (L-series).
+ *
+ * The A/R rules reason from grants exactly as the catalog stores them, which
+ * misses two ways access actually arrives: `GRANT TO PUBLIC` (one ACL row
+ * that applies to every role) and role inheritance (zero ACL rows on the
+ * member). The lattice rules evaluate the *effective* cell each
+ * (relation, role, privilege) lands in:
+ *
+ *   | grant | RLS | policy | verdict                                   |
+ *   |-------|-----|--------|-------------------------------------------|
+ *   | yes   | on  | yes    | normal — policy-mediated access           |
+ *   | yes   | on  | no     | dead grant (L1, indirect; A4/A5, direct)  |
+ *   | yes   | off | —      | unmediated (L5 for untrusted, indirect)   |
+ *   | no    | —   | yes    | dead policy (L2)                          |
+ *
+ * plus schema-USAGE composition: an object grant the grantee cannot reach
+ * because USAGE is missing (L3), and USAGE that reaches no object (L4).
+ *
+ * Every L rule ships signal-only: L1–L3 are fail-closed (zero score weight by
+ * default), L4/L5 default to `info`. Escalate via config once the findings
+ * prove themselves.
+ */
+import type { RoleAttributes, SchemaAclInfo } from '../pg/acl';
+import type { GrantInfo, PgPrivilege, TableSnapshot } from '../pg/introspect';
+import type { Finding } from '../types';
+export type RoleGraph = Map<string, RoleAttributes>;
+/** How an effective privilege arrived at a role. */
+export type GrantVia = 'direct' | 'PUBLIC' | `member of ${string}`;
+export interface EffectiveGrant {
+    privilege: PgPrivilege;
+    via: GrantVia;
+}
+/**
+ * Every privilege `role` effectively holds on `table`: direct grants, grants
+ * TO PUBLIC, and grants to roles it inherits from. Deduplicated per privilege
+ * with the most direct provenance winning (direct > PUBLIC > inherited).
+ *
+ * Takes anything carrying an ACL, not just a table: a view's own grants
+ * compose the same way, and the view-ownership reach edge asks this same
+ * question of them.
+ */
+export declare function effectiveGrants(table: Pick<TableSnapshot, 'grants'>, role: string, graph: RoleGraph): EffectiveGrant[];
+/**
+ * How `role` comes to hold EXECUTE on a function, or `null` when it does not.
+ *
+ * A function ACL carries one privilege, so the closure {@link effectiveGrants}
+ * performs per privilege collapses to a single provenance — but it is the same
+ * closure: a grant to PUBLIC and a grant to a role the caller INHERITs from
+ * both confer EXECUTE without naming the caller anywhere.
+ */
+export declare function effectiveExecute(fn: {
+    grants: Array<{
+        role: string;
+    }>;
+}, role: string, graph: RoleGraph): GrantVia | null;
+/** A privilege `role` holds on some, but not all, of a relation's columns. */
+export interface EffectiveColumnGrant extends EffectiveGrant {
+    /** The columns it covers, sorted. */
+    columns: string[];
+}
+/**
+ * Every privilege `role` effectively holds on individual *columns* of `table`,
+ * composed exactly like {@link effectiveGrants} — direct, PUBLIC, inherited.
+ *
+ * A column grant lives in `pg_attribute.attacl` and never appears in the
+ * relation's ACL, so a role can hold nothing at all by `effectiveGrants` and
+ * still read the columns that matter. Privileges the role already holds on the
+ * whole relation are dropped: the column grant then adds no reach, and
+ * reporting it would double-count the same access.
+ */
+export declare function effectiveColumnGrants(table: Pick<TableSnapshot, 'grants' | 'columnGrants'>, role: string, graph: RoleGraph): EffectiveColumnGrant[];
+/**
+ * L1: an *indirect* grant (TO PUBLIC, or inherited from a granted role) on an
+ * RLS-enabled table with no applicable permissive policy — a dead grant that
+ * A4/A5 cannot see because no direct ACL row names the role. Default-deny
+ * admits nothing today; the risk is the grant silently activating the day a
+ * broad policy is added.
+ */
+export declare function checkIndirectCoverageGaps(table: TableSnapshot, graph: RoleGraph): Finding[];
+/**
+ * L2: a permissive policy names a role that holds no grant the policy could
+ * mediate — authorization written for a role that cannot reach the table.
+ * Either the grant was forgotten (a broken feature) or the policy is stale.
+ */
+export declare function checkDeadPolicies(table: TableSnapshot, graph: RoleGraph): Finding[];
+/**
+ * L3: an object grant the grantee cannot use because it lacks USAGE on the
+ * schema — direct, via PUBLIC, or inherited. The grant is unreachable today
+ * and activates silently the day USAGE is granted.
+ */
+export declare function checkUnreachableGrants(table: TableSnapshot, schemaAcls: Map<string, SchemaAclInfo>, graph: RoleGraph): Finding[];
+/**
+ * L4: schema USAGE that opens the door to nothing — the role reaches no
+ * relation (directly, via PUBLIC, or by inheritance) and can EXECUTE no
+ * function in the schema. Advisory only: sequences, types and future objects
+ * are not modeled, so this is a review candidate, not a proof.
+ *
+ * `views` matters more than its optionality suggests: a role whose only
+ * reachable object in the schema is a view holds USAGE that is load-bearing,
+ * and L8 exists precisely because that view can be the role's entire read
+ * path. Called without them, L4 sees a table-only schema and reports a grant
+ * the API depends on as revokable — so pass them wherever they are available.
+ */
+export declare function checkDeadSchemaUsage(schemaAcls: SchemaAclInfo[], tables: TableSnapshot[], graph: RoleGraph, views?: Array<{
+    schema: string;
+    grants: GrantInfo[];
+}>): Finding[];
+export interface LatticeRoleOptions {
+    /** Role names considered untrusted (exact match). */
+    roles?: string[];
+    /** Take the untrusted roles from the resolved exposure surface. See `RoleTrustOptions`. */
+    rolesFrom?: 'exposure' | 'anon';
+}
+export interface UnaddressableGrantOptions {
+    /** API-edge roles: the roles requests actually arrive as. */
+    roles: string[];
+    /**
+     * Relations named by some RLS policy predicate anywhere in the database.
+     *
+     * The reason this parameter exists: a grant on a relation the API cannot
+     * address is *not* automatically dead, because a policy on a different
+     * relation may subquery it under the querying role. Revoking that grant
+     * breaks authorization at runtime, silently, everywhere. A relation any
+     * predicate mentions is therefore never reported, whatever the API says.
+     */
+    policyReferenced: Set<string>;
+}
+/**
+ * L6: an API-edge role holds privileges on a relation its own API cannot
+ * address.
+ *
+ * The composition the two halves of safegres were built for: the lattice knows
+ * what a role effectively holds, exposure reach knows what the generated API
+ * can name, and the difference is grant surface that exists for nothing. It is
+ * not a leak — the role would have to connect directly to use it — which is
+ * exactly why it is the kind of finding that survives for years.
+ */
+export declare function checkUnaddressableGrant(table: TableSnapshot, graph: RoleGraph, unaddressable: Set<string>, options: UnaddressableGrantOptions): Finding[];
+/**
+ * L5: an untrusted role reaches an RLS-disabled table *indirectly* — through
+ * a grant TO PUBLIC or by inheriting from a granted role. Direct grants are
+ * A2/R1 territory; the indirect paths are exactly the ones that slip past
+ * exact-name matching (e.g. a world-readable table reached by `anonymous`
+ * through PUBLIC).
+ */
+export declare function checkUntrustedIndirectAccess(table: TableSnapshot, graph: RoleGraph, options?: LatticeRoleOptions): Finding[];
+/** One role's effective reach into one relation. */
+export interface RoleAccessRelation {
+    schema: string;
+    table: string;
+    privileges: PgPrivilege[];
+    /** Most direct provenance across the privileges. */
+    via: GrantVia;
+    /**
+     * Present when the reach is column-scoped: the columns reachable, and the
+     * privileges above are the column-level ones. Absent for whole-relation
+     * access.
+     */
+    columns?: string[];
+    /** `unmediated` = RLS off or bypassed; `mediated` = at least one applicable policy; `dead` = RLS default-deny. */
+    access: 'unmediated' | 'mediated' | 'dead';
+}
+export interface RoleAccessEntry {
+    role: string;
+    /** Relations where at least one privilege is usable (mediated or unmediated). */
+    accessibleTables: number;
+    /** Relations readable/writable with no RLS mediation at all. */
+    unmediated: RoleAccessRelation[];
+    /** Relations reachable only through policies. */
+    mediated: number;
+    /** Relations where every effective privilege is dead (RLS default-deny). */
+    dead: number;
+}
+/**
+ * The direct answer to "what can role X see?": every relation the role
+ * effectively reaches, classified by whether RLS mediates the access.
+ */
+export declare function computeRoleAccess(tables: TableSnapshot[], graph: RoleGraph, roles: string[]): RoleAccessEntry[];