@schema-weaver/pg-connector 0.0.0-stage → 2.0.0

package/dist/types/execution/function-effects.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Function-effect analysis, answered by PostgreSQL's own catalogue.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * `isProvableRead()` used to be "one statement, parsed, `type === 'read'`, no
+ * read violations", and `read_violations` was populated from a NAME deny-list.
+ * That made the class of attack trivially reachable: an operator-written
+ * `SECURITY DEFINER` wrapper around `pg_read_file`, or any `VOLATILE` function
+ * that INSERTs, is called from a `SELECT`, is on no deny-list, and was therefore
+ * a *provable read* for every role at every permission level. `viewer` read
+ * `/etc/passwd` from the database host even with
+ * `default_transaction_read_only = on`, because that setting constrains WRITES,
+ * not reads.
+ *
+ * A deny-list cannot close that class: the names are not enumerable. The
+ * `pg_proc` row, however, states what PostgreSQL itself believes about every
+ * function in the database — `provolatile` and `prosecdef` — and the rule we
+ * need is a property of the function, not of its spelling. Only
+ * `provolatile = 'i' AND prosecdef = false` is a call with no effect at all.
+ *
+ * THE RULE
+ * --------
+ * `immutable`      provolatile = 'i' AND prosecdef = false -> no side effect
+ * `volatile`       provolatile = 'v' -> may do anything the role may do
+ * `stable`         provolatile = 's' -> snapshot/time dependent, not a provable read
+ * `security_definer` prosecdef = true -> runs as the owner, whatever its volatility
+ * `unknown`        not in pg_proc, or the catalogue could not be read -> NOT a read
+ *
+ * Everything that is not `immutable` — including `unknown`, including "the
+ * catalogue was not reachable" — is refused by `isProvableRead()`. That is the
+ * fail-closed direction and it is the whole point: an unresolved function must
+ * not be treated as safe.
+ *
+ * OVERLOADS AND SCHEMAS
+ * ---------------------
+ * A bare name can resolve to many overloads in many schemas. PostgreSQL picks
+ * one through `search_path`, and `pg_function_is_visible()` reports exactly that
+ * choice, so an unqualified reference is judged on the visible overloads. A
+ * `schema.name` reference is judged on that schema only. When a bare name
+ * matches nothing visible, the reference cannot be pinned down at all, so every
+ * same-named function in the cluster is treated as a candidate and the MOST
+ * CONSERVATIVE verdict wins: one unsafe overload is enough.
+ *
+ * COST
+ * ----
+ * One batched `pg_proc` read per classification, cached per (database, name)
+ * with a short TTL, and never issued at all when the statement references no
+ * function. The cache is a latency optimisation only: expiring it early can
+ * only make the analysis stricter (a re-read finds the same or a worse
+ * verdict), never laxer.
+ */
+import type { QueryConfig, QueryResult } from 'pg';
+/** What PostgreSQL's catalogue says a function call can do. */
+export type FunctionEffect = 
+/** provolatile = 'i' AND prosecdef = false. No effect at all. */
+'immutable'
+/** provolatile = 'v'. May do anything the calling role may do. */
+ | 'volatile'
+/** provolatile = 's'. Snapshot/time dependent; not a provable read. */
+ | 'stable'
+/** prosecdef = true. Runs with the owner's rights, whatever its volatility. */
+ | 'security_definer'
+/** Absent from pg_proc, or the catalogue could not be read. */
+ | 'unknown';
+/**
+ * A recorded effect that escapes the transaction.
+ *
+ * `NOTIFY`, advisory locks, sequence advances and XID allocation all commit or
+ * take effect OUTSIDE the transaction that issued them, so a rollback — and
+ * therefore `default_transaction_read_only` on the writes it does cover — is
+ * not a control over any of them. They are recorded explicitly so the audit
+ * trail shows a mutation attempt rather than a read.
+ */
+export type SideEffectKind = 'notified' | 'advisory_lock' | 'xid_allocated' | 'sequence' | 'session_mutation' | 'remote_io' | 'unknown_effect';
+/** One referenced function and the catalogue's verdict on it. */
+export interface FunctionEffectRecord {
+    /** The name exactly as {@link collectFunctionNames} produced it. */
+    name: string;
+    /** `schema.name`, when the statement qualified the reference. */
+    qualified_name?: string;
+    /** Schema the verdict came from, when it could be pinned to one. */
+    schema?: string;
+    /** Verdict for the whole reference (worst overload, when ambiguous). */
+    effect: FunctionEffect;
+    /** Side effects recorded for this reference. Empty only for `immutable`. */
+    side_effects: SideEffectKind[];
+    /** False when pg_proc did not answer, or answered "no such function". */
+    resolved: boolean;
+}
+/**
+ * The analysis of one statement's function references.
+ *
+ * `analysed: false` means "no catalogue verdict was obtained". Callers must
+ * treat that as unsafe: the statement is not a provable read.
+ */
+export interface FunctionEffectAnalysis {
+    records: FunctionEffectRecord[];
+    analysed: boolean;
+}
+/**
+ * Resolver injected by the caller that owns the connection.
+ *
+ * It is deliberately an *argument* rather than something the classifier reaches
+ * for: classification happens in several places (permission check, local CLI
+ * surface, migrations) and only some of them have a live client. A caller
+ * without one must get `analysed: false`, not a silent pass.
+ */
+export type FunctionEffectResolver = (names: readonly string[]) => Promise<FunctionEffectAnalysis>;
+/** The minimum a `pg` client has to provide to answer the catalogue query. */
+export interface FunctionEffectQueryable {
+    query(config: QueryConfig): Promise<Pick<QueryResult<any>, 'rows'>>;
+}
+/**
+ * A source that lends a connection per lookup, so the caller is not asked to
+ * hold a pool slot across the whole permission decision (which can include a
+ * human approval that takes minutes).
+ */
+export interface FunctionEffectConnectionSource {
+    acquire(): Promise<{
+        client: FunctionEffectQueryable;
+        release: () => void;
+    }>;
+}
+/** Either an already-held client or something that can lend one. */
+export type FunctionEffectSource = FunctionEffectQueryable | FunctionEffectConnectionSource;
+/**
+ * Safe PostgreSQL catalog read functions that have zero mutation side effects.
+ * Even if PostgreSQL marks them as STABLE or VOLATILE in pg_proc (e.g. pg_table_size
+ * reads disk state so pg_proc has provolatile = 'v'), they are purely read-only
+ * catalog inspection / sizing helpers and must not demote a SELECT to a mutation.
+ */
+export declare const SAFE_READ_CATALOG_FUNCTIONS: ReadonlySet<string>;
+/** A reference with no catalogue answer: check if it is a non-dangerous catalog built-in, else unknown. */
+export declare function unresolvedRecord(name: string): FunctionEffectRecord;
+/**
+ * Drop cached verdicts so the next classification re-reads `pg_proc`.
+ *
+ * Call it when the catalogue may have changed underneath the cache: a pool
+ * closing, a db entry being re-pointed, or a statement that was not a read
+ * having just executed. Dropping an entry can only make the next verdict equal
+ * to the catalogue or stricter, so it is always safe to call.
+ *
+ * @param dbKey Only this database's verdicts when supplied; all of them
+ *   otherwise.
+ */
+export declare function invalidateFunctionEffectCache(dbKey?: string): void;
+/** Number of cached verdicts. Diagnostics and tests only. */
+export declare function functionEffectCacheSize(): number;
+/**
+ * Resolve every function a statement references against `pg_proc`.
+ *
+ * Contract:
+ *   - No names in, `analysed: true` and no records: there is nothing to prove,
+ *     so `SELECT 1` is unaffected.
+ *   - No connection, or a failed catalogue read: `analysed: false` and every
+ *     unresolved name reported as `unknown`. The caller must then refuse the
+ *     statement. This is the required fail-closed direction.
+ *   - One batched query per call, whatever the number of names.
+ */
+export declare function analyseFunctionEffects(names: Iterable<string>, source?: FunctionEffectSource | null, options?: {
+    dbKey?: string;
+    now?: () => number;
+}): Promise<FunctionEffectAnalysis>;
+/**
+ * Build a resolver bound to one connection source.
+ *
+ * Pass this into `PermissionChecker.check` (and therefore into
+ * `classifyStatement`). Omit it and every statement that references a function
+ * is refused, which is the intended behaviour for a caller with no database to
+ * consult — see {@link analyseFunctionEffects}.
+ */
+export declare function createFunctionEffectResolver(source?: FunctionEffectSource | null, options?: {
+    dbKey?: string;
+}): FunctionEffectResolver;
+/**
+ * A resolver over a `PoolManager`-shaped object.
+ *
+ * Exists so a caller that owns a pool but not a connection can wire the
+ * analysis in one line, and so the pool slot is held for the duration of the
+ * catalogue query only — the permission decision itself can block on a human
+ * approval, and holding a connection across that would exhaust the pool.
+ *
+ * Typed structurally rather than against `PoolManager` so this module does not
+ * depend on the connection layer.
+ */
+export declare function functionEffectResolverForPool(pool: {
+    acquire(dbEntry: any): Promise<{
+        client: FunctionEffectQueryable;
+        release: () => void;
+    }>;
+}, dbEntry: unknown, options?: {
+    dbKey?: string;
+}): FunctionEffectResolver;
+/**
+ * A resolver that answers from a fixed verdict table, for callers and tests
+ * that have no database to consult. Same contract as the real thing: anything
+ * not in the table is `unknown`, and therefore refused.
+ *
+ * NOT for a production execution path. It can only be as strict as the table it
+ * is handed, so wiring it in place of the catalogue read would reintroduce
+ * exactly the gap this module closes. It is here so the unit suite can drive
+ * the composed classifier without a server, and so a caller that genuinely has
+ * no database gets the fail-closed verdict explicitly instead of by omission.
+ */
+export declare function createStaticFunctionEffectResolver(verdicts: Readonly<Record<string, FunctionEffect | 'unresolved'>>, options?: {
+    analysed?: boolean;
+}): FunctionEffectResolver;
+//# sourceMappingURL=function-effects.d.ts.map

package/dist/types/execution/function-effects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"function-effects.d.ts","sourceRoot":"","sources":["../../../src/execution/function-effects.ts"],"names":[],"mappings":"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"}

package/dist/types/execution/introspection.d.ts

@@ -0,0 +1,76 @@
+import { PoolManager } from './pool';
+import { DbEntry } from '../config/db-config';
+import { IntrospectPayload, IntrospectResultPayload } from '../protocol/messages';
+import type { Role } from '../protocol/envelope';
+/**
+ * How much of the schema a snapshot may carry.
+ *
+ * - `full` — everything, including `indexdef`, `check_clause`,
+ *   `column_default`, trigger function source, owners, comments and partition
+ *   bounds.
+ * - `structure` — relation names, column names/types/nullable, and the
+ *   primary-key/unique/foreign-key shape. Everything that is a *fact about the
+ *   data model* is kept; every field that is *database implementation detail or
+ *   business-rule expression* is dropped.
+ *
+ * Audit M-30: `ROLE_CAPABILITIES` granted `introspect` to all four roles while
+ * the snapshot returned the entire schema, so a `viewer` could exfiltrate the
+ * whole thing — index bodies, check-clause expressions (which encode validation
+ * rules), column defaults (which name sequences and generated columns) and
+ * trigger function source. Dropping `introspect` outright for the least
+ * privileged roles was the other option; it was rejected because a read-only
+ * user could then not populate a schema browser or write a valid join, which is
+ * the product's whole purpose for them. The reduced level keeps the product and
+ * removes the channel.
+ */
+export type IntrospectionDetail = 'full' | 'structure';
+/**
+ * Fields dropped at `structure` detail. Listed explicitly (rather than
+ * "delete whatever looks internal") so the reduction is auditable: adding a
+ * column to a snapshot query does not silently become a leak, it has to be added
+ * here deliberately.
+ */
+export declare const STRUCTURE_ONLY_DROPPED_FIELDS: readonly string[];
+export interface IntrospectorOptions {
+    poolManager: PoolManager;
+}
+export declare class Introspector {
+    private readonly poolManager;
+    constructor(opts: IntrospectorOptions);
+    /**
+     * Take a schema snapshot.
+     *
+     * `role` is the authenticated envelope's role; it selects the detail level via
+     * `introspectionDetailFor` in permissions/role-policy.ts. It defaults to
+     * `structure` rather than `full`, so a caller that forgets to pass it cannot
+     * leak the full schema — the reverse of the usual default would be fail-open.
+     *
+     * Every catalogue query below goes out through `extendedQuery`, so it travels
+     * over the extended query protocol: node-postgres takes the simple protocol
+     * whenever `values` is falsy, and that protocol executes every
+     * semicolon-separated statement in one round trip. The SQL here is
+     * agent-authored and carries no caller-supplied text, but pinning it means a
+     * future edit cannot quietly turn one catalogue query into a multi-command
+     * string.
+     */
+    introspect(payload: IntrospectPayload, dbEntry: DbEntry, role?: Role): Promise<IntrospectResultPayload>;
+}
+/**
+ * Major version from a PostgreSQL version string.
+ *
+ * `SELECT version()` returns e.g. `PostgreSQL 16.2 (Debian 16.2-1.pgdg120+1) on
+ * x86_64-pc-linux-gnu`, and a caller-supplied hint may be `16`, `16.2` or the
+ * same string. Only the leading `major.minor` is meaningful for compatibility,
+ * so the major is what is compared.
+ */
+export declare function parseMajorVersion(raw: string): number | null;
+/**
+ * Fail closed when the caller's declared server version is not the server we are
+ * connected to. An absent hint (`null`/blank) imposes no expectation.
+ *
+ * Throws a plain `Error`; the dispatcher converts it into an error frame, so the
+ * caller learns that no snapshot was taken rather than receiving one that
+ * answers a question it did not ask.
+ */
+export declare function assertVersionHintMatches(serverVersion: string, hint: string | null | undefined): void;
+//# sourceMappingURL=introspection.d.ts.map

package/dist/types/execution/introspection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"introspection.d.ts","sourceRoot":"","sources":["../../../src/execution/introspection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAElF,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAGjD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,WAAW,CAAC;AAEvD;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,mBAQxC,CAAC;AAEH,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;gBAE9B,IAAI,EAAE,mBAAmB;IAIrC;;;;;;;;;;;;;;;OAeG;IACG,UAAU,CACd,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,OAAO,EAChB,IAAI,GAAE,IAAe,GACpB,OAAO,CAAC,uBAAuB,CAAC;CAoapC;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAO5D;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC9B,IAAI,CAwBN"}

package/dist/types/execution/migration-runner.d.ts

@@ -0,0 +1,128 @@
+import { PoolManager } from './pool';
+import { DbEntry } from '../config/db-config';
+import { MigrationRunPayload, MigrationResultPayload } from '../protocol/messages';
+import { InFlightRequest } from './types';
+import { AgentMessage, Role } from '../protocol/envelope';
+export declare class MigrationInProgressError extends Error {
+    /** Error catalog code. Not a SQLSTATE: `safePgCode` requires exactly 5. */
+    readonly code = "migration_in_progress";
+    constructor(message: string);
+}
+export declare class MigrationStrategyConflictError extends Error {
+    readonly code = "migration_strategy_conflict";
+    constructor(message: string);
+}
+/**
+ * The plan could not be verified: something in it does not parse, contains
+ * more than one statement, or is a statement form the agent cannot prove runs
+ * inside a transaction block. The run is refused rather than guessed at.
+ */
+export declare class MigrationPlanUnsafeError extends Error {
+    readonly code = "migration_plan_unsafe";
+    constructor(message: string);
+}
+/**
+ * The migration stopped partway with statements already committed.
+ *
+ * `MigrationRunner.run` never *resolves* with `status: 'partial'`: a caller
+ * that only inspects a returned value can therefore never mistake a
+ * half-applied schema for a success. The per-statement detail is on
+ * {@link MigrationPartiallyAppliedError.result} for a caller that wants to
+ * report it.
+ */
+export declare class MigrationPartiallyAppliedError extends Error {
+    readonly code = "migration_partial";
+    readonly result: MigrationResultPayload;
+    readonly pg_error_code?: string;
+    constructor(message: string, result: MigrationResultPayload);
+}
+/** The run exceeded its overall deadline and was abandoned. */
+export declare class MigrationTimeoutError extends Error {
+    readonly code = "migration_timeout";
+    constructor(message: string);
+}
+/**
+ * Absolute ceiling on one migration statement, in milliseconds. A caller
+ * cannot raise it, and it can never exceed the agent-wide statement ceiling in
+ * `pool.ts` — nothing is allowed to turn `statement_timeout` off.
+ */
+export declare const MAX_MIGRATION_STATEMENT_TIMEOUT_MS: number;
+/** Absolute ceiling on the whole migration run, in milliseconds. */
+export declare const MAX_MIGRATION_DEADLINE_MS: 1800000;
+/** How long a migration statement may wait for a lock before it is cancelled. */
+export declare const MIGRATION_LOCK_TIMEOUT_MS = 10000;
+export interface MigrationBudget {
+    /** `statement_timeout` applied to every statement of the run. */
+    statementTimeoutMs: number;
+    /** Wall-clock budget for the whole run, enforced by the runner. */
+    deadlineMs: number;
+    /** `lock_timeout` applied to every statement of the run. */
+    lockTimeoutMs: number;
+}
+/**
+ * Turn a caller-supplied `timeout_ms` into the three server-side budgets.
+ *
+ * The number is never trusted: it is floored to an integer, and clamped to
+ * {@link MAX_MIGRATION_STATEMENT_TIMEOUT_MS} / {@link MAX_MIGRATION_DEADLINE_MS}.
+ * `0`, a negative number, `NaN` and `Infinity` all mean "use the server
+ * default" — never "no timeout", which is how a remote caller would otherwise
+ * be able to remove the ceiling by asking for zero.
+ */
+export declare function resolveMigrationBudget(requestedTimeoutMs?: number): MigrationBudget;
+export interface MigrationRunnerOptions {
+    poolManager: PoolManager;
+    /**
+     * Per-installation secret the advisory lock key is derived from. Defaults to
+     * the agent token in the machine config, which is generated once per install
+     * and never leaves the host.
+     */
+    lockSecret?: string;
+}
+export interface MigrationContext {
+    dbEntry: DbEntry;
+    request_id: string;
+    project: string;
+    user: {
+        id: string;
+        role: Role;
+    };
+    db_alias: string;
+    /** Called for each statement status change. */
+    onProgress?: (event: AgentMessage) => void | Promise<void>;
+    abortSignal?: AbortSignal;
+    registerInFlight?: (req: InFlightRequest) => void;
+    unregisterInFlight?: (request_id: string) => void;
+}
+/**
+ * Advisory lock key for SW migrations.
+ *
+ * Keyed with HMAC-SHA256 over a per-installation secret. The previous version
+ * hashed the project name with a bare MD5, so anybody who could guess (or was
+ * told) a project name could compute the lock key, take the lock from another
+ * session, and deny migrations for that project indefinitely. A keyed MAC is
+ * not derivable by a third party with database access, because the secret never
+ * reaches the database.
+ */
+export declare function advisoryLockKey(projectName: string, secret: string): {
+    key1: number;
+    key2: number;
+};
+export declare class MigrationRunner {
+    private readonly poolManager;
+    private readonly injectedLockSecret?;
+    private resolvedLockSecret;
+    constructor(opts: MigrationRunnerOptions);
+    /**
+     * The installation secret the lock key is keyed with.
+     *
+     * An explicit option wins (tests, embedders). Otherwise the agent token from
+     * the machine config is used: it is per-installation, secret, and stable
+     * across processes, which is exactly what mutual exclusion between two agents
+     * needs. If the machine config cannot be read the fallback is a random
+     * per-process secret — still unguessable from outside, so the lock key cannot
+     * be pre-taken by anyone with database access.
+     */
+    private lockSecret;
+    run(payload: MigrationRunPayload, ctx: MigrationContext): Promise<MigrationResultPayload>;
+}
+//# sourceMappingURL=migration-runner.d.ts.map

package/dist/types/execution/migration-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-runner.d.ts","sourceRoot":"","sources":["../../../src/execution/migration-runner.ts"],"names":[],"mappings":"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"}

package/dist/types/execution/non-tx-detector.d.ts

@@ -0,0 +1,23 @@
+export interface NonTxCheckResult {
+    has_non_transactional: boolean;
+    /** Indices of statements that can't run in a transaction. */
+    non_tx_indices: number[];
+    /** Human-readable summary. */
+    summary: string;
+    /** Indices of statements that could not be parsed at all. */
+    unparseable_indices: number[];
+    /** Indices of statements whose transactionality could not be proven. */
+    ambiguous_indices: number[];
+}
+/**
+ * Detects whether a migration plan contains statements that cannot run inside a
+ * transaction block, or that cannot be parsed.
+ *
+ * Transactionality is a table lookup on the PostgreSQL parse tree, never an
+ * inference from token overlap. Unknown statement forms fail SAFE: they are
+ * reported as non-transactional so the caller is forced to choose
+ * `per_statement` rather than having a statement the agent cannot reason about
+ * silently wrapped in `BEGIN`/`COMMIT`.
+ */
+export declare function detectNonTransactional(statements: string[]): Promise<NonTxCheckResult>;
+//# sourceMappingURL=non-tx-detector.d.ts.map

package/dist/types/execution/non-tx-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"non-tx-detector.d.ts","sourceRoot":"","sources":["../../../src/execution/non-tx-detector.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,gBAAgB;IAC/B,qBAAqB,EAAE,OAAO,CAAC;IAC/B,6DAA6D;IAC7D,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,wEAAwE;IACxE,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B;AAyKD;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA2D5F"}