@safegres/test 0.0.1 → 1.30.7

package/esm/pg/introspect.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Single-query catalog introspection for the safegres audit.
+ *
+ * Pulls every relation + every policy + (parsed) role ACL per role in one shot,
+ * so Script A can process the whole database from one in-memory snapshot.
+ */
+import type { Client, Pool } from 'pg';
+/** Minimal query interface — accepts pg.Client, pg.Pool, or any `{ query }`. */
+export interface QueryExecutor {
+    query<T = unknown>(text: string, params?: unknown[]): Promise<{
+        rows: T[];
+    }>;
+}
+/**
+ * `USAGE` never appears on a table — it is the sequence privilege (`nextval`),
+ * and `EXECUTE` is the function one. Both are in this union because sequences
+ * and functions are graded through the same grant closure as everything else,
+ * and a reach path routinely starts on one and ends on a table.
+ */
+export type PgPrivilege = 'SELECT' | 'INSERT' | 'UPDATE' | 'DELETE' | 'TRUNCATE' | 'REFERENCES' | 'TRIGGER' | 'USAGE' | 'EXECUTE';
+/**
+ * Mapping of ACL single-letter codes (from `aclexplode`) to our privilege names.
+ * `r` = SELECT, `a` = INSERT, `w` = UPDATE, `d` = DELETE, etc.
+ */
+export declare const ACL_PRIVILEGE_MAP: Record<string, PgPrivilege>;
+export interface GrantInfo {
+    role: string;
+    privilege: PgPrivilege;
+    /** Was the grant delegated (i.e. `WITH GRANT OPTION`). */
+    grantable: boolean;
+    /**
+     * `true` if the grantee role is a superuser or has `BYPASSRLS`. RLS policies
+     * do not apply to this role, so coverage findings are suppressed for it.
+     * `false` for `PUBLIC` and all other grantees.
+     */
+    bypassRls: boolean;
+}
+/**
+ * A grant on one column (`pg_attribute.attacl`), which Postgres keeps entirely
+ * separate from the table's own ACL: `GRANT SELECT (secret) ON t TO anon`
+ * leaves `relacl` untouched, so any analysis that reads only `relacl`
+ * concludes the role reaches nothing.
+ *
+ * Only SELECT, INSERT, UPDATE and REFERENCES can be column-scoped.
+ */
+export interface ColumnGrantInfo extends GrantInfo {
+    column: string;
+}
+/** `pg_policy.polcmd` uses: `r` SELECT, `a` INSERT, `w` UPDATE, `d` DELETE, `*` ALL. */
+export type PolicyCmd = 'SELECT' | 'INSERT' | 'UPDATE' | 'DELETE' | 'ALL';
+export declare const POLICY_CMD_MAP: Record<string, PolicyCmd>;
+export interface PolicyInfo {
+    name: string;
+    cmd: PolicyCmd;
+    permissive: boolean;
+    /** Role names the policy applies to. `['PUBLIC']` if `polroles = {0}`. */
+    roles: string[];
+    using: string | null;
+    withCheck: string | null;
+}
+export interface TableSnapshot {
+    schema: string;
+    name: string;
+    oid: number;
+    rlsEnabled: boolean;
+    rlsForced: boolean;
+    /** `true` if the table is partitioned or is a view — used to skip irrelevant findings. */
+    isPartitioned: boolean;
+    owner: string;
+    grants: GrantInfo[];
+    /**
+     * Grants on individual columns. Disjoint from {@link TableSnapshot.grants}:
+     * a column grant never appears in `relacl`, and a table grant never appears
+     * in `attacl`, so a role can reach a relation through this list alone.
+     */
+    columnGrants: ColumnGrantInfo[];
+    policies: PolicyInfo[];
+}
+export interface IntrospectOptions {
+    /** Schemas to include. If omitted, all non-system schemas. */
+    schemas?: string[];
+    /**
+     * Schemas to exclude. Applied on top of `schemas`.
+     * Defaults to `['pg_catalog', 'information_schema', 'pg_toast']`.
+     */
+    excludeSchemas?: string[];
+    /**
+     * Roles to include when reporting grants. If omitted, all roles returned
+     * by {@link listAuditableRoles}.
+     */
+    roles?: string[];
+    /**
+     * How to treat relations that belong to an installed extension.
+     * Defaults to skipping them: they are the extension author's to secure and
+     * tune, not the application's, and they cannot be altered without breaking
+     * `pg_dump`/upgrade.
+     */
+    extensions?: ExtensionScopeOptions;
+}
+/**
+ * Extension relations are the `node_modules` of a database: physically present,
+ * scanned like anything else, and not yours to edit.
+ */
+export interface ExtensionScopeOptions {
+    /**
+     * Skip relations an extension owns (`pg_depend.deptype = 'e'`) and their
+     * partitions. Default `true`.
+     */
+    skipOwned?: boolean;
+    /**
+     * Extension names whose *schemas* are skipped wholesale, for objects the
+     * extension creates at runtime and never registers as dependencies —
+     * `pg_partman`'s child partitions and templates being the motivating case.
+     * Unknown/uninstalled names are ignored.
+     */
+    ignore?: string[];
+}
+/**
+ * SQL predicate excluding extension relations, for a query where `c` is the
+ * `pg_class` row and `n` its namespace. `paramIndex` is the bind position
+ * holding {@link ExtensionScopeOptions.ignore}.
+ */
+export declare function extensionFilter(options: ExtensionScopeOptions | undefined, paramIndex: number): string;
+/**
+ * One-query snapshot of every table + its policies + its grants expanded per role.
+ *
+ * We deliberately avoid views that hide permissive vs restrictive distinctions
+ * (like `pg_policies`) — `pg_policy` gives us `polpermissive` directly.
+ */
+export declare function introspectTables(exec: QueryExecutor, options?: IntrospectOptions): Promise<TableSnapshot[]>;
+/**
+ * Convenience: accept any of `pg.Client` / `pg.Pool` / a custom executor.
+ */
+export declare function asExecutor(client: Client | Pool | QueryExecutor): QueryExecutor;

package/esm/pg/introspect.js

@@ -0,0 +1,274 @@
+/**
+ * Single-query catalog introspection for the safegres audit.
+ *
+ * Pulls every relation + every policy + (parsed) role ACL per role in one shot,
+ * so Script A can process the whole database from one in-memory snapshot.
+ */
+/**
+ * Mapping of ACL single-letter codes (from `aclexplode`) to our privilege names.
+ * `r` = SELECT, `a` = INSERT, `w` = UPDATE, `d` = DELETE, etc.
+ */
+export const ACL_PRIVILEGE_MAP = {
+    r: 'SELECT',
+    a: 'INSERT',
+    w: 'UPDATE',
+    d: 'DELETE',
+    D: 'TRUNCATE',
+    x: 'REFERENCES',
+    t: 'TRIGGER'
+};
+export const POLICY_CMD_MAP = {
+    r: 'SELECT',
+    a: 'INSERT',
+    w: 'UPDATE',
+    d: 'DELETE',
+    '*': 'ALL'
+};
+/**
+ * SQL predicate excluding extension relations, for a query where `c` is the
+ * `pg_class` row and `n` its namespace. `paramIndex` is the bind position
+ * holding {@link ExtensionScopeOptions.ignore}.
+ */
+export function extensionFilter(options, paramIndex) {
+    const skipOwned = options?.skipOwned ?? true;
+    const clauses = [];
+    if (skipOwned) {
+        // A partition carries no extension dependency of its own, so ownership
+        // has to be read off the partition tree it belongs to — at any depth.
+        clauses.push(`
+      AND NOT EXISTS (
+        SELECT 1 FROM pg_depend d
+        WHERE d.classid = 'pg_class'::regclass
+          AND d.refclassid = 'pg_extension'::regclass
+          AND d.deptype = 'e'
+          AND (
+            d.objid = c.oid
+            OR d.objid IN (SELECT relid FROM pg_partition_ancestors(c.oid))
+          )
+      )`);
+    }
+    clauses.push(`
+      AND NOT (n.oid = ANY (
+        SELECT e.extnamespace FROM pg_extension e WHERE e.extname = ANY($${paramIndex}::text[])
+      ))`);
+    return clauses.join('');
+}
+const DEFAULT_EXCLUDES = ['pg_catalog', 'information_schema', 'pg_toast'];
+/**
+ * One-query snapshot of every table + its policies + its grants expanded per role.
+ *
+ * We deliberately avoid views that hide permissive vs restrictive distinctions
+ * (like `pg_policies`) — `pg_policy` gives us `polpermissive` directly.
+ */
+export async function introspectTables(exec, options = {}) {
+    const excludes = [...DEFAULT_EXCLUDES, ...(options.excludeSchemas ?? [])];
+    // PUBLIC (grantee oid 0) always survives the role filter: it is not a role
+    // that can be included or excluded — it is every role, including every one
+    // in the filter.
+    const roleFilter = options.roles && options.roles.length > 0
+        ? `AND (g.grantee_oid = 0 OR rol.rolname = ANY($3::text[]))`
+        : '';
+    const schemaFilter = options.schemas && options.schemas.length > 0
+        ? `AND n.nspname = ANY($1::text[])`
+        : `AND NOT (n.nspname = ANY($2::text[]))`;
+    const extFilter = extensionFilter(options.extensions, 4);
+    // We reference every param at least once (even if trivially) so Postgres
+    // can infer types for all of them. Unused parameters otherwise error with
+    // "could not determine data type of parameter $N".
+    const sql = `
+    WITH _params AS (
+      SELECT
+        $1::text[] AS include_schemas,
+        $2::text[] AS exclude_schemas,
+        $3::text[] AS role_filter,
+        $4::text[] AS ignore_extensions
+    ),
+    rels AS (
+      SELECT
+        n.nspname                                       AS schema_name,
+        c.relname                                       AS table_name,
+        c.oid                                           AS oid,
+        c.relrowsecurity                                AS rls_enabled,
+        c.relforcerowsecurity                           AS rls_forced,
+        (c.relkind = 'p')                               AS is_partitioned,
+        pg_catalog.pg_get_userbyid(c.relowner)          AS owner,
+        c.relacl                                        AS relacl
+      FROM pg_class c
+      JOIN pg_namespace n ON n.oid = c.relnamespace
+      WHERE c.relkind IN ('r', 'p')
+        ${schemaFilter}${extFilter}
+    ),
+    grants_exploded AS (
+      SELECT
+        r.oid,
+        (aclexplode(r.relacl)).grantee      AS grantee_oid,
+        (aclexplode(r.relacl)).privilege_type AS privilege_type,
+        (aclexplode(r.relacl)).is_grantable  AS is_grantable
+      FROM rels r
+      WHERE r.relacl IS NOT NULL
+    ),
+    grants AS (
+      SELECT
+        g.oid,
+        CASE WHEN g.grantee_oid = 0 THEN 'PUBLIC' ELSE rol.rolname END AS grantee,
+        g.privilege_type,
+        g.is_grantable,
+        CASE
+          WHEN g.grantee_oid = 0 THEN false
+          ELSE COALESCE(rol.rolsuper OR rol.rolbypassrls, false)
+        END AS bypass_rls
+      FROM grants_exploded g
+      LEFT JOIN pg_roles rol ON rol.oid = g.grantee_oid
+      WHERE true
+        ${roleFilter}
+    ),
+    -- Column ACLs live on pg_attribute, not pg_class: a column grant is
+    -- invisible to relacl, and this is the only place it surfaces.
+    col_grants_exploded AS (
+      SELECT
+        r.oid,
+        a.attname                             AS column_name,
+        (aclexplode(a.attacl)).grantee        AS grantee_oid,
+        (aclexplode(a.attacl)).privilege_type AS privilege_type,
+        (aclexplode(a.attacl)).is_grantable   AS is_grantable
+      FROM rels r
+      JOIN pg_attribute a ON a.attrelid = r.oid
+      WHERE a.attacl IS NOT NULL
+        AND a.attnum > 0
+        AND NOT a.attisdropped
+    ),
+    col_grants AS (
+      SELECT
+        g.oid,
+        g.column_name,
+        CASE WHEN g.grantee_oid = 0 THEN 'PUBLIC' ELSE rol.rolname END AS grantee,
+        g.privilege_type,
+        g.is_grantable,
+        CASE
+          WHEN g.grantee_oid = 0 THEN false
+          ELSE COALESCE(rol.rolsuper OR rol.rolbypassrls, false)
+        END AS bypass_rls
+      FROM col_grants_exploded g
+      LEFT JOIN pg_roles rol ON rol.oid = g.grantee_oid
+      WHERE true
+        ${roleFilter}
+    ),
+    policies AS (
+      SELECT
+        p.polrelid                                  AS oid,
+        p.polname                                   AS name,
+        p.polcmd                                    AS cmd,
+        p.polpermissive                             AS permissive,
+        CASE
+          WHEN p.polroles = ARRAY[0]::oid[] THEN ARRAY['PUBLIC']
+          ELSE COALESCE(
+            (SELECT array_agg(rolname) FROM pg_roles WHERE oid = ANY(p.polroles)),
+            ARRAY[]::text[]
+          )
+        END                                          AS roles,
+        pg_get_expr(p.polqual, p.polrelid)          AS using_expr,
+        pg_get_expr(p.polwithcheck, p.polrelid)     AS with_check_expr
+      FROM pg_policy p
+    )
+    SELECT
+      r.schema_name,
+      r.table_name,
+      r.oid::int                                          AS oid,
+      r.rls_enabled,
+      r.rls_forced,
+      r.is_partitioned,
+      r.owner,
+      COALESCE(
+        (SELECT jsonb_agg(jsonb_build_object(
+          'role', g.grantee,
+          'privilege', g.privilege_type,
+          'grantable', g.is_grantable,
+          'bypassRls', g.bypass_rls
+        )) FROM grants g WHERE g.oid = r.oid),
+        '[]'::jsonb
+      )                                                   AS grants,
+      COALESCE(
+        (SELECT jsonb_agg(jsonb_build_object(
+          'role', g.grantee,
+          'column', g.column_name,
+          'privilege', g.privilege_type,
+          'grantable', g.is_grantable,
+          'bypassRls', g.bypass_rls
+        ) ORDER BY g.grantee, g.column_name, g.privilege_type)
+         FROM col_grants g WHERE g.oid = r.oid),
+        '[]'::jsonb
+      )                                                   AS column_grants,
+      COALESCE(
+        (SELECT jsonb_agg(jsonb_build_object(
+          'name', p.name,
+          'cmd', p.cmd::text,
+          'permissive', p.permissive,
+          'roles', to_jsonb(p.roles),
+          'using', p.using_expr,
+          'withCheck', p.with_check_expr
+        )) FROM policies p WHERE p.oid = r.oid),
+        '[]'::jsonb
+      )                                                   AS policies
+    FROM rels r
+    ORDER BY r.schema_name, r.table_name
+  `;
+    const params = [
+        options.schemas ?? [],
+        excludes,
+        options.roles ?? [],
+        options.extensions?.ignore ?? []
+    ];
+    const { rows } = await exec.query(sql, params);
+    return rows.map((r) => ({
+        schema: r.schema_name,
+        name: r.table_name,
+        oid: r.oid,
+        rlsEnabled: r.rls_enabled,
+        rlsForced: r.rls_forced,
+        isPartitioned: r.is_partitioned,
+        owner: r.owner,
+        grants: r.grants.map((g) => ({
+            role: g.role,
+            privilege: normalizePrivilege(g.privilege),
+            grantable: g.grantable,
+            bypassRls: g.bypassRls === true
+        })),
+        columnGrants: r.column_grants.map((g) => ({
+            role: g.role,
+            column: g.column,
+            privilege: normalizePrivilege(g.privilege),
+            grantable: g.grantable,
+            bypassRls: g.bypassRls === true
+        })),
+        policies: r.policies.map((p) => ({
+            name: p.name,
+            cmd: POLICY_CMD_MAP[p.cmd] ?? 'ALL',
+            permissive: p.permissive,
+            roles: p.roles,
+            using: p.using,
+            withCheck: p.withCheck
+        }))
+    }));
+}
+function normalizePrivilege(raw) {
+    const upper = raw.toUpperCase();
+    switch (upper) {
+        case 'SELECT':
+        case 'INSERT':
+        case 'UPDATE':
+        case 'DELETE':
+        case 'TRUNCATE':
+        case 'REFERENCES':
+        case 'TRIGGER':
+            return upper;
+        default:
+            // `r`, `a`, `w`, `d` — ACL single-letter form
+            return ACL_PRIVILEGE_MAP[raw] ?? 'SELECT';
+    }
+}
+/**
+ * Convenience: accept any of `pg.Client` / `pg.Pool` / a custom executor.
+ */
+export function asExecutor(client) {
+    return client;
+}

package/esm/pg/objects.d.ts

@@ -0,0 +1,37 @@
+/**
+ * ACLs on the relations that are not tables.
+ *
+ * `introspectTables` reads `relkind IN ('r','p')` and `introspectViews` reads
+ * views and matviews, which leaves two kinds of relation carrying privileges
+ * that nothing in this package ever looked at:
+ *
+ *   - **sequences** (`relkind = 'S'`), where `USAGE`/`UPDATE` let a role call
+ *     `nextval`/`setval` and `SELECT` lets it read `last_value`; and
+ *   - **foreign tables** (`relkind = 'f'`), which cannot carry RLS at all —
+ *     `ALTER FOREIGN TABLE ... ENABLE ROW LEVEL SECURITY` is rejected by
+ *     Postgres (verified on 18), so a grant on one is never row-filtered.
+ *
+ * Both are read here rather than folded into the table snapshot: neither has
+ * RLS state, policies or column ACLs, and giving them a `TableSnapshot` with
+ * those fields stubbed out would invite every table rule to grade something it
+ * does not understand.
+ */
+import type { GrantInfo, IntrospectOptions, QueryExecutor } from './introspect';
+export type PgObjectKind = 'sequence' | 'foreign table';
+export interface ObjectAclSnapshot {
+    schema: string;
+    name: string;
+    kind: PgObjectKind;
+    owner: string;
+    grants: GrantInfo[];
+    /** The foreign server behind a foreign table; absent for a sequence. */
+    server?: string;
+    /**
+     * For a sequence, the `schema.table.column` it is attached to by an
+     * `OWNED BY` dependency (a `serial`/identity column records one). A role
+     * that inserts into that table legitimately needs `USAGE`, which is what
+     * keeps the sequence rule from recommending a revoke.
+     */
+    ownedBy?: string;
+}
+export declare function introspectObjectAcls(exec: QueryExecutor, options?: IntrospectOptions): Promise<ObjectAclSnapshot[]>;

package/esm/pg/objects.js

@@ -0,0 +1,108 @@
+/**
+ * ACLs on the relations that are not tables.
+ *
+ * `introspectTables` reads `relkind IN ('r','p')` and `introspectViews` reads
+ * views and matviews, which leaves two kinds of relation carrying privileges
+ * that nothing in this package ever looked at:
+ *
+ *   - **sequences** (`relkind = 'S'`), where `USAGE`/`UPDATE` let a role call
+ *     `nextval`/`setval` and `SELECT` lets it read `last_value`; and
+ *   - **foreign tables** (`relkind = 'f'`), which cannot carry RLS at all —
+ *     `ALTER FOREIGN TABLE ... ENABLE ROW LEVEL SECURITY` is rejected by
+ *     Postgres (verified on 18), so a grant on one is never row-filtered.
+ *
+ * Both are read here rather than folded into the table snapshot: neither has
+ * RLS state, policies or column ACLs, and giving them a `TableSnapshot` with
+ * those fields stubbed out would invite every table rule to grade something it
+ * does not understand.
+ */
+const DEFAULT_EXCLUDES = ['pg_catalog', 'information_schema', 'pg_toast'];
+export async function introspectObjectAcls(exec, options = {}) {
+    const excludes = [...DEFAULT_EXCLUDES, ...(options.excludeSchemas ?? [])];
+    const schemaFilter = options.schemas && options.schemas.length > 0
+        ? 'AND n.nspname = ANY($1::text[])'
+        : 'AND NOT (n.nspname = ANY($2::text[]))';
+    const sql = `
+    WITH _params AS (
+      SELECT $1::text[] AS include_schemas, $2::text[] AS exclude_schemas
+    ),
+    rels AS (
+      SELECT
+        n.nspname                              AS schema_name,
+        c.relname                              AS object_name,
+        c.oid                                  AS oid,
+        c.relkind                              AS relkind,
+        pg_catalog.pg_get_userbyid(c.relowner) AS owner,
+        c.relacl                               AS relacl
+      FROM pg_class c
+      JOIN pg_namespace n ON n.oid = c.relnamespace
+      WHERE c.relkind IN ('S', 'f')
+        ${schemaFilter}
+    ),
+    grants AS (
+      SELECT
+        r.oid,
+        CASE WHEN a.grantee = 0 THEN 'PUBLIC' ELSE rol.rolname END AS grantee,
+        a.privilege_type,
+        a.is_grantable,
+        CASE
+          WHEN a.grantee = 0 THEN false
+          ELSE COALESCE(rol.rolsuper OR rol.rolbypassrls, false)
+        END AS bypass_rls
+      FROM rels r, aclexplode(r.relacl) a
+      LEFT JOIN pg_roles rol ON rol.oid = a.grantee
+      WHERE r.relacl IS NOT NULL
+    ),
+    -- A serial/identity column records an OWNED BY dependency on its
+    -- sequence. The role inserting into that table needs USAGE on it, so the
+    -- link is what separates a load-bearing grant from a gratuitous one.
+    owners AS (
+      SELECT
+        d.objid AS seq_oid,
+        n.nspname || '.' || c.relname || '.' || a.attname AS owned_by
+      FROM pg_depend d
+      JOIN pg_class c ON c.oid = d.refobjid
+      JOIN pg_namespace n ON n.oid = c.relnamespace
+      JOIN pg_attribute a ON a.attrelid = d.refobjid AND a.attnum = d.refobjsubid
+      WHERE d.classid = 'pg_class'::regclass
+        AND d.refclassid = 'pg_class'::regclass
+        AND d.deptype IN ('a', 'i')
+        AND d.objid IN (SELECT oid FROM rels WHERE relkind = 'S')
+    )
+    SELECT
+      r.schema_name,
+      r.object_name,
+      r.relkind,
+      r.owner,
+      o.owned_by,
+      srv.srvname AS server_name,
+      COALESCE(
+        (
+          SELECT jsonb_agg(jsonb_build_object(
+            'role', g.grantee,
+            'privilege', g.privilege_type,
+            'grantable', g.is_grantable,
+            'bypassRls', g.bypass_rls
+          ) ORDER BY g.grantee, g.privilege_type)
+          FROM grants g
+          WHERE g.oid = r.oid
+        ),
+        '[]'::jsonb
+      ) AS grants
+    FROM rels r
+    LEFT JOIN owners o ON o.seq_oid = r.oid
+    LEFT JOIN pg_foreign_table ft ON ft.ftrelid = r.oid
+    LEFT JOIN pg_foreign_server srv ON srv.oid = ft.ftserver
+    ORDER BY r.schema_name, r.object_name
+  `;
+    const { rows } = await exec.query(sql, [options.schemas ?? null, excludes]);
+    return rows.map((r) => ({
+        schema: r.schema_name,
+        name: r.object_name,
+        kind: r.relkind === 'S' ? 'sequence' : 'foreign table',
+        owner: r.owner,
+        grants: r.grants,
+        ...(r.server_name ? { server: r.server_name } : {}),
+        ...(r.owned_by ? { ownedBy: r.owned_by } : {})
+    }));
+}

package/esm/pg/paths.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Access-path signals: independent, individually-auditable pieces of evidence
+ * about whether anything reads a foreign key.
+ *
+ * X1 ("foreign key with no covering index") is right about the mechanics — a
+ * `DELETE` on the parent really does scan the child — but it assumes the child
+ * is a relation somebody traverses. On a provisioning-config table that
+ * assumption is false, and acting on the finding buys a write penalty on every
+ * insert in exchange for speeding up a scan of one row.
+ *
+ * The tempting gate, `pg_class.reltuples`, is useless here: safegres grades an
+ * ephemeral CI database that has never held data, so every row estimate is 0
+ * at exactly the moment we grade. Worse, row count is the wrong question — a
+ * huge append-only log nobody joins on wants no FK index, and a tiny lookup
+ * table hammered by every request does. The property we need is *reachability*.
+ *
+ * Reachability is not one boolean, and this module deliberately does not
+ * compute one. It collects signals, each of which points in one direction and
+ * says why, and leaves the verdict to the caller:
+ *
+ * - `policy-read` and `view-read` are **reads**. They are decisive: the
+ *   database itself traverses the column, so no amount of contrary evidence
+ *   makes the path unreachable.
+ * - `write-once-pointer` and `config-record` are **shape**. They are not
+ *   evidence of unreachability, only of a schema idiom — a `NOT NULL` key
+ *   defaulting to the nil UUID is a slot a provisioner fills in, and a table
+ *   with several of them looks like a config record rather than a relation.
+ *
+ * Shape alone must never suppress a finding. A generated API can expose a
+ * reverse relation over any foreign key regardless of how its default is
+ * written, and if it does, the path is reachable and the index is wanted.
+ *
+ * - `behavior-hidden` is the third kind, **declared**: the schema author has
+ *   said the reverse relation is not in the generated API. It comes from the
+ *   same behavior tags exposure reach reads, so the two axes agree about what
+ *   the API contains rather than each guessing separately. It is reported and
+ *   not acted on — a hidden relation is one missing path, not proof that
+ *   nothing traverses the key, since the referential-integrity scan on a
+ *   parent `DELETE` runs whatever the API exposes.
+ */
+import type { TableIndexSnapshot } from './indexes';
+import type { TableSnapshot } from './introspect';
+/**
+ * Which way a signal points. `read` means something demonstrably traverses the
+ * key; `shape` means the schema resembles an idiom in which nothing does, which
+ * is a suspicion rather than a finding.
+ */
+export type SignalDirection = 'read' | 'shape' | 'declared';
+export type SignalName = 'policy-read' | 'view-read' | 'write-once-pointer' | 'config-record' | 'behavior-hidden';
+export interface PathSignal {
+    name: SignalName;
+    direction: SignalDirection;
+    /** Why this signal fired, in one human-readable clause. */
+    detail: string;
+}
+/**
+ * The caller-facing summary of a path's signals. Note there is no `unreachable`
+ * member: nothing safegres can currently observe proves a path is unreachable,
+ * and inventing the state is how a scanner ends up recommending that you drop
+ * an index a live API is using.
+ */
+export type PathAssessment = 
+/** At least one `read` signal. The key is traversed; X1 applies as written. */
+'read'
+/** Only `shape` signals. Looks like a provisioning pointer; unproven. */
+ | 'write-once-shaped'
+/** No signal fired either way. */
+ | 'unknown';
+export interface AccessPath {
+    schema: string;
+    table: string;
+    /** Referencing column names, in constraint order. */
+    columns: string[];
+    /** The foreign-key constraint this path belongs to. */
+    constraint: string;
+    /** Every signal that fired, so a reviewer can audit the assessment. */
+    signals: PathSignal[];
+    assessment: PathAssessment;
+}
+export interface ClassifyOptions {
+    /**
+     * Write-once pointers a table needs before the `config-record` signal fires.
+     * Default 2. Lifting the test from the column to the table is what catches
+     * the nullable, undefaulted pointer sitting alongside the defaulted ones.
+     */
+    minPointers?: number;
+    /**
+     * `schema.table.constraint` keys whose reverse relation an API declares
+     * absent, as computed by exposure reach.
+     */
+    hiddenBackwardRelations?: Set<string>;
+}
+export declare const DEFAULT_MIN_POINTERS = 2;
+export declare function isConstantDefault(defaultExpr: string | null): boolean;
+/** Key for {@link AccessPath} lookups: the relation plus the constraint name. */
+export declare function pathKey(schema: string, table: string, constraint: string): string;
+/**
+ * One real reader ends the discussion, so a `read` signal always wins. Absent
+ * one, the shape has to hold at the *table* level before it means anything: a
+ * lone defaulted column is a habit, whereas a table built entirely out of them
+ * is an idiom. `write-once-pointer` on its own is therefore reported and not
+ * acted on.
+ */
+export declare function assess(signals: PathSignal[]): PathAssessment;
+/**
+ * Collect the signals for every foreign key in the snapshot.
+ *
+ * `tables` supplies the RLS policy predicates (as SQL text) and `viewBodies`
+ * the view definitions. Both are matched as whole-word tokens across the
+ * *whole* database rather than per relation — deliberately over-eager, because
+ * a spurious `read` signal costs one retained finding while a missing one
+ * could cost a dropped index.
+ */
+export declare function classifyPaths(indexSnapshot: TableIndexSnapshot[], tables: TableSnapshot[], viewBodies: string[], options?: ClassifyOptions): Map<string, AccessPath>;