@safegres/test 0.0.2 → 1.30.7

package/esm/pg/behaviors.js

@@ -0,0 +1,206 @@
+/**
+ * PostGraphile *behaviors*, read from the object comments they are declared in.
+ *
+ * A behavior string is the schema author stating which parts of the generated
+ * API an object participates in — `@behavior -list -connection` on a foreign
+ * key constraint says the reverse relation is not exposed. That is a different
+ * kind of evidence from anything else safegres collects: `pg_class.reltuples`
+ * and `pg_stat_user_indexes.idx_scan` are *measurements*, and safegres grades
+ * an ephemeral CI database that has never held data, so both read zero at
+ * exactly the moment they would have to mean something. A declaration reads the
+ * same in CI as in production.
+ *
+ * Read from the comment rather than from a running Graphile instance, or from
+ * whatever tables the author generated the comment out of:
+ *
+ * - `@behavior` in a comment is the PostGraphile v5 convention, so this works
+ *   on any Graphile database rather than one project's metadata schema.
+ * - The comment is the composed value — one tag per object — so it is already
+ *   the author's resolved intent.
+ * - A live instance would additionally resolve preset defaults, but requires an
+ *   API to be running. safegres grades a database.
+ *
+ * The consequence of that last point is the rule this module exists to enforce:
+ * **only an explicit negative fragment is evidence.** Presets grant most
+ * behaviors by default, so the *absence* of `+list` says nothing whatsoever. A
+ * scanner that reads silence as denial is a scanner that tells you to drop an
+ * index a live API is using.
+ */
+export function emptyBehaviorSnapshot() {
+    return {
+        tables: new Map(),
+        columns: new Map(),
+        constraints: new Map(),
+        constraintDirections: new Map()
+    };
+}
+/**
+ * The behavior governing one direction of a relation: the directional tag when
+ * present, else the undirected one. They do not merge — Graphile resolves the
+ * specific tag against the preset, and treating `@behavior -list` as an extra
+ * fragment on top of `@backwardBehavior +list` would invert the author's
+ * override.
+ */
+export function directionalBehavior(behaviors, direction) {
+    if (!behaviors)
+        return undefined;
+    return behaviors[direction] ?? behaviors.both;
+}
+/** Catalog schemas no API surface ever contains. */
+export const SYSTEM_SCHEMAS = ['pg_catalog', 'information_schema', 'pg_toast'];
+const DEFAULT_EXCLUDES = SYSTEM_SCHEMAS;
+/**
+ * Extract the `@behavior` smart tag from an object comment.
+ *
+ * Smart tags occupy the leading lines of the comment, `@tag [value]`, and stop
+ * at the first line that is not one; everything after is the description. Only
+ * `@behavior` is returned — `@omit` is deliberately not translated here, since
+ * its v4 semantics ("remove from the schema") are not the same question as a
+ * behavior fragment and conflating them would put a guess in the evidence.
+ */
+export function parseBehaviorTag(comment) {
+    return parseBehaviorTags(comment).both ?? null;
+}
+/** Every behavior tag on a comment, by direction. */
+export function parseBehaviorTags(comment) {
+    const out = {};
+    if (!comment)
+        return out;
+    for (const line of comment.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('@'))
+            break;
+        const match = /^@(behavior|forwardBehavior|backwardBehavior)\s+(.+)$/.exec(trimmed);
+        if (!match)
+            continue;
+        const value = match[2].trim();
+        if (match[1] === 'behavior')
+            out.both = value;
+        else if (match[1] === 'forwardBehavior')
+            out.forward = value;
+        else
+            out.backward = value;
+    }
+    return out;
+}
+/** Split a behavior string into fragments. A bare scope is a grant, as in PostGraphile. */
+export function parseFragments(behavior) {
+    if (!behavior)
+        return [];
+    const out = [];
+    for (const term of behavior.trim().split(/\s+/)) {
+        if (!term)
+            continue;
+        const modifier = term[0] === '-' ? '-' : '+';
+        const scope = term[0] === '+' || term[0] === '-' ? term.slice(1) : term;
+        if (scope)
+            out.push({ modifier, scope });
+    }
+    return out;
+}
+/**
+ * Does this fragment's scope speak to `ability`?
+ *
+ * Scope paths are `:`-separated and get more specific left to right
+ * (`resource:connection`), so the ability is the final segment. `*` matches
+ * anything, which is how `-*` denies wholesale.
+ */
+function scopeMatches(scope, ability) {
+    const segments = scope.split(':');
+    const last = segments[segments.length - 1];
+    return last === ability || last === '*';
+}
+/**
+ * Resolve one ability against a behavior string.
+ *
+ * `undefined` means *undeclared*, and is the answer that matters: it is not
+ * `false`. Later fragments win, matching PostGraphile — `-* +list` grants
+ * `list` and denies the rest.
+ */
+export function resolveAbility(behavior, ability) {
+    let verdict;
+    for (const fragment of parseFragments(behavior)) {
+        if (scopeMatches(fragment.scope, ability))
+            verdict = fragment.modifier === '+';
+    }
+    return verdict;
+}
+/**
+ * True when *every* one of `abilities` is explicitly denied.
+ *
+ * Every, not some: a relation reachable as a single record is still reachable,
+ * and one undeclared ability is enough to leave the question open.
+ */
+export function deniesAll(behavior, abilities) {
+    if (abilities.length === 0)
+        return false;
+    return abilities.every((ability) => resolveAbility(behavior, ability) === false);
+}
+/**
+ * Behavior tags on every table, column and constraint in scope.
+ *
+ * Extension-owned objects are not filtered here: the maps are only ever
+ * consulted for relations that survived the scan's own filtering, so an extra
+ * entry costs a map slot and changes nothing.
+ */
+export async function introspectBehaviors(exec, options = {}) {
+    const excludes = [...DEFAULT_EXCLUDES, ...(options.excludeSchemas ?? [])];
+    const schemaFilter = options.schemas && options.schemas.length > 0
+        ? `n.nspname = ANY($1::text[])`
+        : `NOT (n.nspname = ANY($2::text[]))`;
+    // Both parameters are referenced (even when only one filters) so Postgres can
+    // infer their types — an unused $N errors out at bind time.
+    const sql = `
+    WITH _params AS (
+      SELECT $1::text[] AS include_schemas, $2::text[] AS exclude_schemas
+    ),
+    rels AS (
+      SELECT c.oid, n.nspname AS schema_name, c.relname AS table_name
+      FROM pg_class c
+      JOIN pg_namespace n ON n.oid = c.relnamespace
+      WHERE c.relkind IN ('r', 'p', 'v', 'm')
+        AND ${schemaFilter}
+    )
+    SELECT 'table'::text AS kind, r.schema_name, r.table_name, NULL::text AS member, d.description
+      FROM rels r
+      JOIN pg_description d
+        ON d.objoid = r.oid AND d.classoid = 'pg_class'::regclass AND d.objsubid = 0
+    UNION ALL
+    SELECT 'column', r.schema_name, r.table_name, a.attname, d.description
+      FROM rels r
+      JOIN pg_attribute a ON a.attrelid = r.oid AND a.attnum > 0 AND NOT a.attisdropped
+      JOIN pg_description d
+        ON d.objoid = r.oid AND d.classoid = 'pg_class'::regclass AND d.objsubid = a.attnum
+    UNION ALL
+    SELECT 'constraint', r.schema_name, r.table_name, co.conname, d.description
+      FROM rels r
+      JOIN pg_constraint co ON co.conrelid = r.oid
+      JOIN pg_description d
+        ON d.objoid = co.oid AND d.classoid = 'pg_constraint'::regclass
+  `;
+    const { rows } = await exec.query(sql, [options.schemas ?? [], excludes]);
+    const snapshot = emptyBehaviorSnapshot();
+    for (const row of rows) {
+        const tags = parseBehaviorTags(row.description);
+        const relation = `${row.schema_name}.${row.table_name}`;
+        if (row.kind === 'table') {
+            if (tags.both)
+                snapshot.tables.set(relation, tags.both);
+            continue;
+        }
+        if (!row.member)
+            continue;
+        const key = `${relation}.${row.member}`;
+        if (row.kind === 'column') {
+            if (tags.both)
+                snapshot.columns.set(key, tags.both);
+            continue;
+        }
+        if (tags.both)
+            snapshot.constraints.set(key, tags.both);
+        if (tags.both || tags.forward || tags.backward) {
+            snapshot.constraintDirections.set(key, tags);
+        }
+    }
+    return snapshot;
+}

package/esm/pg/exposure.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Exposure-surface resolution: what is actually reachable, and by whom.
+ *
+ * A database has more than one way in. The declared API is the one the score
+ * is *about* — `resolveExposure` returns it, unchanged, and it stays the
+ * headline. `resolvePlanes` returns it alongside every other access path the
+ * config declares or an adapter discovers, so a direct connection as some
+ * role can be graded too, without moving the number that describes the API.
+ */
+import type { ExposureConfig, PlaneKind } from '../config/types';
+import type { ApiReach } from '../exposure/reach';
+import type { QueryExecutor } from './introspect';
+export interface ResolvedExposure {
+    /** True when a surface was configured or auto-resolved. */
+    known: boolean;
+    source: string;
+    schemas: string[];
+    roles?: string[];
+    /** The subset of `roles` reachable without authenticating. */
+    anonRoles?: string[];
+}
+/** A plane before its reach is computed against the table snapshot. */
+export interface ResolvedPlane {
+    name: string;
+    kind: PlaneKind;
+    /** The headline plane: its score is `report.score`. Exactly one is primary. */
+    primary: boolean;
+    /** Where the plane came from: an adapter name, `config`, or `none`. */
+    source: string;
+    schemas: string[];
+    roles: string[];
+    anonRoles: string[];
+}
+export declare const UNKNOWN_EXPOSURE: ResolvedExposure;
+/**
+ * Resolve the primary exposure surface: the declared API. Adapters run first
+ * (static `schemas`/`roles` extend, never replace, what they find), then the
+ * static surface, then `UNKNOWN_EXPOSURE`.
+ */
+export declare function resolveExposure(exec: QueryExecutor, config?: ExposureConfig): Promise<ResolvedExposure>;
+/**
+ * Every plane to grade, primary first.
+ *
+ * The primary plane is the resolved exposure surface — the same set of
+ * schemas the score has always been computed against — so adding planes
+ * cannot move the headline number. Secondary planes come from adapters (one
+ * per API, where a stack has several) and from `exposure.planes`.
+ */
+export declare function resolvePlanes(exec: QueryExecutor, config: ExposureConfig | undefined, primary: ResolvedExposure): Promise<ResolvedPlane[]>;
+/**
+ * Relation-level reach for the exposed schemas, from whichever adapters can
+ * compute it.
+ *
+ * Adapters *intersect*: a relation is subtracted from a plane only when every
+ * adapter that has an opinion agrees it is unaddressable. One adapter's
+ * silence is not agreement, so an adapter without `reach` is not consulted,
+ * but an adapter that ran and did not name a relation is a positive vote to
+ * keep it.
+ */
+export declare function resolveReach(exec: QueryExecutor, config: ExposureConfig | undefined, context: {
+    schemas: string[];
+    excludeSchemas?: string[];
+}): Promise<ApiReach | undefined>;
+/**
+ * Constructive routing-plane introspection.
+ *
+ * @deprecated Use `constructiveAdapter` from `safegres/adapters`; this wrapper
+ * preserves the pre-adapter shape (one union of every API) for callers that
+ * still import it.
+ */
+export declare function resolveConstructiveExposure(exec: QueryExecutor): Promise<{
+    schemas: string[];
+    roles: string[];
+} | null>;

package/esm/pg/exposure.js

@@ -0,0 +1,198 @@
+/**
+ * Exposure-surface resolution: what is actually reachable, and by whom.
+ *
+ * A database has more than one way in. The declared API is the one the score
+ * is *about* — `resolveExposure` returns it, unchanged, and it stays the
+ * headline. `resolvePlanes` returns it alongside every other access path the
+ * config declares or an adapter discovers, so a direct connection as some
+ * role can be graded too, without moving the number that describes the API.
+ */
+import { BUILTIN_ADAPTERS, resolveAdapters } from '../exposure/adapters';
+export const UNKNOWN_EXPOSURE = {
+    known: false,
+    source: 'none',
+    schemas: []
+};
+/**
+ * Resolve the primary exposure surface: the declared API. Adapters run first
+ * (static `schemas`/`roles` extend, never replace, what they find), then the
+ * static surface, then `UNKNOWN_EXPOSURE`.
+ */
+export async function resolveExposure(exec, config) {
+    if (!config)
+        return UNKNOWN_EXPOSURE;
+    for (const adapter of adaptersFor(config)) {
+        const planes = await runAdapter(exec, adapter);
+        if (planes.length === 0)
+            continue;
+        const primary = planes.find((p) => p.primary) ?? planes[0];
+        return {
+            known: true,
+            source: adapter.name,
+            schemas: union(primary.schemas ?? [], config.schemas),
+            roles: union(primary.roles ?? [], config.roles),
+            anonRoles: union(primary.anonRoles ?? [], config.anonRoles)
+        };
+    }
+    if (config.schemas && config.schemas.length > 0) {
+        return {
+            known: true,
+            source: 'config',
+            schemas: [...config.schemas].sort(),
+            roles: config.roles,
+            anonRoles: config.anonRoles
+        };
+    }
+    return UNKNOWN_EXPOSURE;
+}
+/**
+ * Every plane to grade, primary first.
+ *
+ * The primary plane is the resolved exposure surface — the same set of
+ * schemas the score has always been computed against — so adding planes
+ * cannot move the headline number. Secondary planes come from adapters (one
+ * per API, where a stack has several) and from `exposure.planes`.
+ */
+export async function resolvePlanes(exec, config, primary) {
+    const primaryName = config?.name ?? 'api';
+    const planes = [
+        {
+            name: primaryName,
+            kind: 'api',
+            primary: true,
+            source: primary.source,
+            schemas: primary.schemas,
+            roles: primary.roles ?? [],
+            anonRoles: primary.anonRoles ?? []
+        }
+    ];
+    const seen = new Set([primaryName]);
+    const push = (input, source) => {
+        if (input.primary || seen.has(input.name))
+            return;
+        seen.add(input.name);
+        planes.push({
+            name: input.name,
+            kind: input.kind ?? defaultKind(input),
+            primary: false,
+            source,
+            schemas: [...(input.schemas ?? [])].sort(),
+            roles: [...(input.roles ?? [])].sort(),
+            anonRoles: [...(input.anonRoles ?? [])].sort()
+        });
+    };
+    if (config && primary.known) {
+        for (const adapter of adaptersFor(config)) {
+            for (const plane of await runAdapter(exec, adapter))
+                push(plane, adapter.name);
+        }
+    }
+    const declared = config?.planes ?? [];
+    const claimingPrimary = declared.filter((p) => p.primary);
+    if (claimingPrimary.length > 1) {
+        throw new Error('more than one exposure plane declares `primary: true` '
+            + `(${claimingPrimary.map((p) => p.name).join(', ')}) — exactly one plane is the headline score`);
+    }
+    for (const plane of declared)
+        push(plane, 'config');
+    // A declared plane may take the headline over from the API surface: a
+    // database whose product *is* direct SQL access has no API to grade.
+    const override = claimingPrimary[0];
+    if (override) {
+        planes[0] = {
+            name: override.name,
+            kind: override.kind ?? defaultKind(override),
+            primary: true,
+            source: 'config',
+            schemas: [...(override.schemas ?? [])].sort(),
+            roles: [...(override.roles ?? [])].sort(),
+            anonRoles: [...(override.anonRoles ?? [])].sort()
+        };
+    }
+    return planes;
+}
+/**
+ * Relation-level reach for the exposed schemas, from whichever adapters can
+ * compute it.
+ *
+ * Adapters *intersect*: a relation is subtracted from a plane only when every
+ * adapter that has an opinion agrees it is unaddressable. One adapter's
+ * silence is not agreement, so an adapter without `reach` is not consulted,
+ * but an adapter that ran and did not name a relation is a positive vote to
+ * keep it.
+ */
+export async function resolveReach(exec, config, context) {
+    if (!config || config.reach === false)
+        return undefined;
+    let agreed;
+    const hidden = new Set();
+    let ran = false;
+    for (const adapter of adaptersFor(config)) {
+        if (!adapter.reach)
+            continue;
+        if (!(await adapter.detect(exec)))
+            continue;
+        const reach = await adapter.reach(exec, context);
+        ran = true;
+        for (const key of reach.hiddenBackwardRelations)
+            hidden.add(key);
+        const named = new Map(reach.unreachable.map((r) => [`${r.schema}.${r.table}`, r]));
+        if (agreed === undefined)
+            agreed = named;
+        else
+            for (const key of [...agreed.keys()])
+                if (!named.has(key))
+                    agreed.delete(key);
+    }
+    if (!ran)
+        return undefined;
+    return {
+        unreachable: [...(agreed?.values() ?? [])].sort((a, b) => `${a.schema}.${a.table}`.localeCompare(`${b.schema}.${b.table}`)),
+        hiddenBackwardRelations: [...hidden].sort()
+    };
+}
+function defaultKind(plane) {
+    if (plane.kind)
+        return plane.kind;
+    return plane.roles && plane.roles.length > 0 && !(plane.schemas && plane.schemas.length > 0)
+        ? 'role'
+        : 'schema';
+}
+/** Adapters named by the config, plus the `resolver` alias for the built-in. */
+function adaptersFor(config) {
+    const adapters = resolveAdapters(config.adapters);
+    if (config.resolver && config.resolver !== 'static') {
+        const builtin = BUILTIN_ADAPTERS[config.resolver];
+        if (builtin && !adapters.some((a) => a.name === builtin.name))
+            adapters.unshift(builtin);
+    }
+    return adapters;
+}
+/** An adapter that isn't present in this database contributes nothing. */
+async function runAdapter(exec, adapter) {
+    if (!(await adapter.detect(exec)))
+        return [];
+    return adapter.resolve(exec);
+}
+/**
+ * Constructive routing-plane introspection.
+ *
+ * @deprecated Use `constructiveAdapter` from `safegres/adapters`; this wrapper
+ * preserves the pre-adapter shape (one union of every API) for callers that
+ * still import it.
+ */
+export async function resolveConstructiveExposure(exec) {
+    const adapter = BUILTIN_ADAPTERS.constructive;
+    if (!(await adapter.detect(exec)))
+        return null;
+    const planes = await adapter.resolve(exec);
+    const primary = planes.find((p) => p.primary) ?? planes[0];
+    if (!primary || (primary.schemas ?? []).length === 0)
+        return null;
+    return { schemas: primary.schemas ?? [], roles: primary.roles ?? [] };
+}
+function union(base, extra) {
+    if (!extra || extra.length === 0)
+        return base;
+    return [...new Set([...base, ...extra])].sort();
+}

package/esm/pg/functions.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Function catalog introspection for the call-graph audit.
+ *
+ * One query over `pg_proc` returns every user-defined function with the
+ * attributes the trust-boundary analysis needs: SECURITY DEFINER vs INVOKER,
+ * the owner role (what a DEFINER actually runs as), whether `search_path`
+ * is pinned, the language, the body source, and EXECUTE grants per role.
+ */
+import type { ExtensionScopeOptions, QueryExecutor } from './introspect';
+export interface FunctionGrant {
+    role: string;
+    /** Was the grant delegated (`WITH GRANT OPTION`). */
+    grantable: boolean;
+}
+export interface FunctionSnapshot {
+    oid: number;
+    schema: string;
+    name: string;
+    /** Argument type signature, e.g. `text, uuid` — disambiguates overloads. */
+    args: string;
+    owner: string;
+    /** Owner is a superuser or has BYPASSRLS — RLS never applies to it. */
+    ownerBypassesRls: boolean;
+    isSecurityDefiner: boolean;
+    /** True when `proconfig` pins `search_path` (CWE-426 mitigation for DEFINERs). */
+    searchPathPinned: boolean;
+    language: string;
+    /** Raw body (`prosrc`); null for C/internal functions. */
+    source: string | null;
+    /** Full `CREATE FUNCTION` statement — what `parsePlPgSQL` consumes. */
+    definition: string | null;
+    /**
+     * EXECUTE grants. `PUBLIC` appears as the role name `PUBLIC`.
+     * When `proacl` is NULL Postgres applies the default function ACL, which
+     * includes EXECUTE to PUBLIC — represented here as a synthetic PUBLIC grant.
+     */
+    grants: FunctionGrant[];
+    /** True when the grants came from the default ACL (no explicit GRANT/REVOKE). */
+    defaultAcl: boolean;
+    /**
+     * The function returns `trigger`, so Postgres refuses to call it directly
+     * however wide its EXECUTE ACL is. EXECUTE on one confers nothing on its
+     * own: the body is only reachable by firing the trigger it is attached to.
+     */
+    returnsTrigger: boolean;
+}
+export interface IntrospectFunctionOptions {
+    schemas?: string[];
+    excludeSchemas?: string[];
+    extensions?: ExtensionScopeOptions;
+}
+export declare function introspectFunctions(exec: QueryExecutor, options?: IntrospectFunctionOptions): Promise<FunctionSnapshot[]>;

package/esm/pg/functions.js

@@ -0,0 +1,128 @@
+/**
+ * Function catalog introspection for the call-graph audit.
+ *
+ * One query over `pg_proc` returns every user-defined function with the
+ * attributes the trust-boundary analysis needs: SECURITY DEFINER vs INVOKER,
+ * the owner role (what a DEFINER actually runs as), whether `search_path`
+ * is pinned, the language, the body source, and EXECUTE grants per role.
+ */
+const DEFAULT_EXCLUDES = ['pg_catalog', 'information_schema', 'pg_toast'];
+/**
+ * Extension scoping for routines. The table-side filter reads ownership off
+ * `pg_class`; a function's is on `pg_proc`, and nothing about a routine is
+ * inherited the way a partition inherits its parent's dependency — so this is
+ * the same rule expressed against the other catalog, not a shared helper.
+ *
+ * Without it `extensions.ignore` narrowed the relation rules and left the
+ * routine rules reading the extension's own bodies: `pg_partman` alone
+ * accounted for every C1 finding and 60% of C4 on a real audit.
+ */
+function routineExtensionFilter(options, paramIndex) {
+    const clauses = [];
+    if (options?.skipOwned ?? true) {
+        clauses.push(`
+        AND NOT EXISTS (
+          SELECT 1 FROM pg_depend d
+          WHERE d.classid = 'pg_proc'::regclass
+            AND d.refclassid = 'pg_extension'::regclass
+            AND d.deptype = 'e'
+            AND d.objid = p.oid
+        )`);
+    }
+    clauses.push(`
+        AND NOT (n.oid = ANY (
+          SELECT e.extnamespace FROM pg_extension e WHERE e.extname = ANY($${paramIndex}::text[])
+        ))`);
+    return clauses.join('');
+}
+export async function introspectFunctions(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 extFilter = routineExtensionFilter(options.extensions, 3);
+    const sql = `
+    WITH _params AS (
+      SELECT $1::text[] AS include_schemas, $2::text[] AS exclude_schemas,
+             $3::text[] AS ignore_extensions
+    ),
+    procs AS (
+      SELECT
+        p.oid,
+        n.nspname                                    AS schema_name,
+        p.proname                                    AS name,
+        pg_get_function_identity_arguments(p.oid)    AS args,
+        pg_get_userbyid(p.proowner)                  AS owner,
+        COALESCE(o.rolsuper OR o.rolbypassrls, false) AS owner_bypasses_rls,
+        p.prosecdef                                  AS security_definer,
+        EXISTS (
+          SELECT 1 FROM unnest(COALESCE(p.proconfig, ARRAY[]::text[])) cfg
+          WHERE cfg LIKE 'search_path=%'
+        )                                            AS search_path_pinned,
+        l.lanname                                    AS language,
+        p.prorettype = 'pg_catalog.trigger'::regtype  AS returns_trigger,
+        p.prosrc                                     AS source,
+        CASE WHEN l.lanname IN ('sql', 'plpgsql')
+             THEN pg_get_functiondef(p.oid)
+             ELSE NULL END                           AS definition,
+        p.proacl                                     AS proacl
+      FROM pg_proc p
+      JOIN pg_namespace n ON n.oid = p.pronamespace
+      JOIN pg_language l  ON l.oid = p.prolang
+      LEFT JOIN pg_roles o ON o.oid = p.proowner
+      WHERE p.prokind IN ('f', 'p')
+        ${schemaFilter}${extFilter}
+    ),
+    grants AS (
+      SELECT
+        pr.oid,
+        CASE WHEN a.grantee = 0 THEN 'PUBLIC' ELSE rol.rolname END AS grantee,
+        a.is_grantable
+      FROM procs pr,
+           LATERAL aclexplode(pr.proacl) a
+      LEFT JOIN pg_roles rol ON rol.oid = a.grantee
+      WHERE pr.proacl IS NOT NULL
+        AND a.privilege_type = 'EXECUTE'
+    )
+    SELECT
+      p.oid::int            AS oid,
+      p.schema_name,
+      p.name,
+      p.args,
+      p.owner,
+      p.owner_bypasses_rls,
+      p.security_definer,
+      p.search_path_pinned,
+      p.returns_trigger,
+      p.language,
+      p.source,
+      p.definition,
+      COALESCE(
+        (SELECT jsonb_agg(jsonb_build_object('role', g.grantee, 'grantable', g.is_grantable))
+         FROM grants g WHERE g.oid = p.oid),
+        '[]'::jsonb
+      )                     AS grants,
+      (p.proacl IS NULL)    AS default_acl
+    FROM procs p
+    ORDER BY p.schema_name, p.name, p.args
+  `;
+    const { rows } = await exec.query(sql, [options.schemas ?? [], excludes, options.extensions?.ignore ?? []]);
+    return rows.map((r) => ({
+        oid: r.oid,
+        schema: r.schema_name,
+        name: r.name,
+        args: r.args,
+        owner: r.owner,
+        ownerBypassesRls: r.owner_bypasses_rls,
+        isSecurityDefiner: r.security_definer,
+        searchPathPinned: r.search_path_pinned,
+        returnsTrigger: r.returns_trigger,
+        language: r.language,
+        source: r.source,
+        definition: r.definition,
+        grants: r.default_acl
+            ? [{ role: 'PUBLIC', grantable: false }]
+            : r.grants.map((g) => ({ role: g.role, grantable: g.grantable })),
+        defaultAcl: r.default_acl
+    }));
+}