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

package/dist/esm/execution/search-path.js

@@ -0,0 +1,270 @@
+/**
+ * `search_path` a pooled session is pinned to when a database entry does not
+ * name one, and the component that is always kept last so unqualified names keep
+ * resolving. `pg_temp` is deliberately excluded: a temporary object of the same
+ * name would otherwise shadow a permanent table for the whole session.
+ */
+export const DEFAULT_SEARCH_PATH = 'public';
+/**
+ * The schema PostgreSQL implicitly searches first whenever it is not named
+ * explicitly in `search_path`. See {@link resolveSearchPath} for why it is
+ * hoisted rather than appended unconditionally.
+ */
+export const PG_CATALOG_SCHEMA = 'pg_catalog';
+/**
+ * The implicit schema for session-local temporary objects. Never pinned: a temp
+ * object of the same name would shadow a permanent table for the whole session,
+ * which is a session-poisoning primitive any principal with `CREATE TEMP
+ * TABLE` can reach.
+ */
+export const PG_TEMP_SCHEMA = 'pg_temp';
+/** PostgreSQL's NAMEDATALEN - 1. A longer name cannot exist on the server. */
+const MAX_IDENTIFIER_LENGTH = 63;
+/**
+ * A PostgreSQL identifier we are willing to interpolate into `SET search_path`.
+ * Deliberately narrow: letters, digits, underscore and `$`, never starting
+ * with a digit. Anything else is **discarded or refused**, never escaped —
+ * see {@link quoteSchemaIdentifier}.
+ */
+const SCHEMA_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_$]*$/;
+/**
+ * Whether a string may be used as one `search_path` component at all.
+ *
+ * Used both as the gate in {@link resolveSearchPathComponents} (discard a
+ * component the operator got wrong) and as the gate in
+ * {@link quoteSchemaIdentifier} (refuse to emit one we did not validate). The
+ * same predicate in both places is the point: there is no second, laxer path
+ * into the emitted statement.
+ */
+export function isBareSchemaIdentifier(name) {
+    return name.length > 0 && name.length <= MAX_IDENTIFIER_LENGTH && SCHEMA_IDENTIFIER.test(name);
+}
+/**
+ * The three component names the connector reasons about by identity rather than
+ * by text: the always-last fallback, the implicitly-first system catalog, and
+ * the session-local temp schema.
+ *
+ * They are matched case-insensitively because PostgreSQL folds unquoted
+ * identifiers, and — more importantly — because this module emits every
+ * component *quoted*. Without case-insensitive matching, a configured
+ * `search_path: 'app, PUBLIC'` would render `"PUBLIC"`, which is a *different*
+ * schema from `"public"`, and the always-last invariant would silently not hold.
+ * Matching folds that config back onto the canonical `public` the entry promised.
+ */
+function reservedRole(name) {
+    const folded = name.toLowerCase();
+    if (folded === PG_TEMP_SCHEMA)
+        return 'pg_temp';
+    if (folded === PG_CATALOG_SCHEMA)
+        return 'pg_catalog';
+    if (folded === DEFAULT_SEARCH_PATH)
+        return 'public';
+    return null;
+}
+/**
+ * Render one component as a double-quoted identifier.
+ *
+ * Refuses anything that is not a bare identifier instead of escaping it. The
+ * distinction matters: doubling an embedded quote (`a"b` -> `"a""b"`) is the
+ * *correct* PostgreSQL rendering, but it is also how a value that was never a
+ * schema name turns into a schema name. Rejecting keeps "what the operator
+ * wrote" and "what the session searches" the same set of names, which is the
+ * property  destroyed.
+ *
+ * @throws when the component is not a validated identifier.
+ */
+function quoteSchemaIdentifier(name) {
+    if (!isBareSchemaIdentifier(name)) {
+        throw new Error(`refusing to emit search_path component ${JSON.stringify(truncateForMessage(name))}: ` +
+            'not a bare schema identifier');
+    }
+    return `"${name}"`;
+}
+function truncateForMessage(value) {
+    const flat = value.replace(/\s+/g, ' ').trim();
+    return flat.length > 64 ? `${flat.slice(0, 64)}...` : flat;
+}
+/**
+ * The ordered, de-duplicated list of schemas a session for this entry searches.
+ *
+ * Rules, in order:
+ *
+ * 1. No configured value, or no component that survives validation, yields the
+ *    single component `['public']`.
+ * 2. A component is trimmed and then kept only if {@link isBareSchemaIdentifier}
+ *    accepts it, so `'a," public"'` contributes `['a']` and never a schema named
+ *    `" public"`. Nothing is escaped into existence, and whitespace *inside* a
+ *    component is a rejection rather than a rename — the two rules together are
+ *    what make it impossible to emit a component with a leading space.
+ * 3. `pg_temp` is dropped (temp objects must not shadow permanent ones), matched
+ *    case-insensitively.
+ * 4. `pg_catalog` is hoisted to the front if it appears anywhere.
+ *    PostgreSQL already searches `pg_catalog` first *unless* it is named
+ *    explicitly, in which case it is searched at the named position — so a
+ *    configured `'app, pg_catalog, public'` would let a customer schema shadow
+ *    built-ins such as `pg_class`. Hoisting restores the implicit-first behaviour
+ *    the operator was already relying on, without adding a component they did
+ *    not ask for.
+ * 5. `public` is always last, unconditionally — it is appended even when the
+ *    config never named it — so unqualified names keep resolving against the
+ *    schema the entry promises. That unconditional append is the property
+ *    destroyed and the reason a post-condition guard existed at all.
+ *    First-occurrence order is otherwise kept, and ordinary duplicates are
+ *    removed.
+ *
+ * The returned array is the single source of truth for both the emitted
+ * `SET search_path` and the post-condition comparison; it is never joined into
+ * a string and re-split.
+ */
+export function resolveSearchPathComponents(entry) {
+    const configured = entry.search_path;
+    if (typeof configured !== 'string')
+        return [DEFAULT_SEARCH_PATH];
+    const catalog = [];
+    const body = [];
+    const seen = new Set();
+    for (const raw of configured.split(',')) {
+        const component = raw.trim();
+        if (!isBareSchemaIdentifier(component))
+            continue;
+        const role = reservedRole(component);
+        if (role === 'pg_temp')
+            continue;
+        // Fold the three reserved names onto their canonical spelling. Everything
+        // else keeps the operator's exact text, so `Billing` is still `Billing` and
+        // is not conflated with a hypothetical `billing`.
+        const canonical = role === null ? component : role;
+        if (seen.has(canonical))
+            continue;
+        seen.add(canonical);
+        if (role === 'pg_catalog')
+            catalog.push(canonical);
+        else if (role !== 'public')
+            body.push(canonical);
+    }
+    // `public` is appended unconditionally, not merely kept if it was named. That
+    // is the property  destroyed and the reason the old substring guard was
+    // worth writing: an entry that names only `a` still needs `public` as the
+    // fallback, so its absence from the config must not remove it from the path.
+    return [...catalog, ...body, DEFAULT_SEARCH_PATH];
+}
+/**
+ * Render the `SET search_path` statement for a resolved component list.
+ *
+ * The output is the *statement*, not a fragment: the defect this function
+ * exists to make impossible was a caller composing a value from one string and
+ * a separator from another. Producing the whole statement means the tests can
+ * assert exactly what goes over the wire.
+ *
+ * @throws when a component is not a validated bare identifier, or the list is
+ * empty — both are unrecoverable and must fail closed.
+ */
+export function renderSearchPathSet(components) {
+    if (components.length === 0) {
+        throw new Error('refusing to render an empty search_path');
+    }
+    const rendered = components.map((component) => quoteSchemaIdentifier(component));
+    return `SET search_path = ${rendered.join(', ')}`;
+}
+/**
+ * Split the value PostgreSQL reports for `SHOW search_path` into components.
+ *
+ * Two things make a naive `value.split(',')` wrong here, and both were observed
+ * against a live PostgreSQL 16.2:
+ *
+ * - **Quoting.** `SET search_path = "Weird Schema", "public"` comes back as
+ *   `"Weird Schema", public`. Comparing that text to the expected list fails
+ *   even though the path is correct, so quoted components are unquoted
+ *   (including `""` -> `"`).
+ * - **Commas inside a quoted identifier.** `"a,b"` is one component, not two,
+ *   so the split is quote-aware.
+ *
+ * The load-bearing detail is that **whitespace inside a quoted identifier is
+ * significant and whitespace outside it is not**. `analytics, " public"`
+ * unquotes to a component named `" public"` — with the leading space — which is
+ * NOT `public`. Trimming after unquoting would turn the  payload back into
+ * a passing match, which is precisely the mistake the old substring guard made:
+ * the corruption was invisible because the comparison ignored the space. So
+ * each character is trimmed only while it is outside quotes.
+ *
+ * Components are lower-cased because unquoted identifiers are folded by
+ * PostgreSQL, so `PUBLIC` and `public` are the same schema and the comparison
+ * must not fail on case alone. Empty components are **kept** as `''` rather than
+ * filtered: a path with a hole in it is not the list we set.
+ */
+export function parseSearchPathSetting(value) {
+    const components = [];
+    let current = [];
+    let inQuotes = false;
+    const flush = () => {
+        let start = 0;
+        let end = current.length;
+        while (start < end && !current[start].quoted && /\s/.test(current[start].ch))
+            start += 1;
+        while (end > start && !current[end - 1].quoted && /\s/.test(current[end - 1].ch))
+            end -= 1;
+        components.push(current.slice(start, end).map((piece) => piece.ch).join('').toLowerCase());
+        current = [];
+    };
+    for (let i = 0; i < value.length; i += 1) {
+        const ch = value[i];
+        if (inQuotes) {
+            if (ch !== '"') {
+                current.push({ ch, quoted: true });
+                continue;
+            }
+            if (value[i + 1] === '"') {
+                // Escaped quote inside a quoted identifier.
+                current.push({ ch: '"', quoted: true });
+                i += 1;
+                continue;
+            }
+            inQuotes = false;
+            continue;
+        }
+        if (ch === '"') {
+            inQuotes = true;
+            continue;
+        }
+        if (ch === ',') {
+            flush();
+            continue;
+        }
+        // Outside quotes, so eligible for the trimming `flush` performs.
+        current.push({ ch, quoted: false });
+    }
+    flush();
+    return components;
+}
+/**
+ * The  post-condition: does `SHOW search_path` report exactly the list we
+ * pinned, component for component and in order?
+ *
+ * The previous check was `actual.toLowerCase().includes('public')`, which
+ * passes for `analytics, " public"` — the very corruption it was supposed to
+ * catch. Order matters too: `evil, public, analytics` is not the path we set,
+ * and a path that merely *contains* the expected components in a different
+ * order resolves unqualified names differently, so it is a failure.
+ *
+ * Length equality is part of the comparison, so a missing or an extra component
+ * fails. That also covers a server which chose to fold duplicates: the list we
+ * render is already de-duplicated, so any difference from it is a difference we
+ * did not ask for.
+ */
+export function searchPathMatches(actual, expected) {
+    if (expected.length === 0)
+        return false;
+    const got = parseSearchPathSetting(actual);
+    if (got.length !== expected.length)
+        return false;
+    return got.every((component, index) => component === expected[index].toLowerCase());
+}
+/**
+ * A human-readable, secret-free description of a `SHOW search_path` result for
+ * an error message. Schema names are operator-controlled, not credentials, but
+ * the value is still bounded because it reaches the browser.
+ */
+export function describeSearchPathSetting(value) {
+    return truncateForMessage(value);
+}
+//# sourceMappingURL=search-path.js.map

package/dist/esm/execution/search-path.js.map

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

package/dist/esm/execution/sql-parser.d.ts

@@ -0,0 +1,195 @@
+export declare class SqlParserUnavailableError extends Error {
+    constructor(cause?: unknown);
+}
+export declare class SqlParseError extends Error {
+    /** libpg_query error code, e.g. 'syntax_error'. */
+    readonly pgCode: string;
+    /** 1-based cursor position from PostgreSQL, 0 if unknown. */
+    readonly cursorPosition: number;
+    constructor(message: string, pgCode?: string, cursorPosition?: number);
+}
+/** Load the WASM parser. Idempotent and safe to call concurrently. */
+export declare function initSqlParser(): Promise<void>;
+/** True once the WASM module is loaded and parsing is possible. */
+export declare function isSqlParserReady(): boolean;
+/** Throws unless the parser is loaded. Use at the top of any SQL path. */
+export declare function assertParserReady(): void;
+/**
+ * Parse one or more SQL statements into libpg_query raw parse nodes.
+ *
+ * @throws {SqlParserUnavailableError} if the WASM module is not loaded
+ * @throws {SqlParseError} on a PostgreSQL syntax/semantic error
+ */
+export declare function parseSql(sql: string): RawParseResult;
+export interface RawParseResult {
+    version: number;
+    stmts: RawStmt[];
+}
+export interface RawStmt {
+    stmt: Record<string, any>;
+    stmt_location?: number;
+    stmt_len?: number;
+}
+/**
+ * Root node type of a statement (e.g. 'SelectStmt', 'DropStmt').
+ * Returns 'none' for an empty node.
+ */
+export declare function rootNodeType(stmt: RawStmt | undefined): string;
+/**
+ * The root node payload for a statement — i.e. the value of the single root
+ * key, not the `{ NodeName: {...} }` wrapper. Callers that want to walk the
+ * whole tree should use `walkAst(stmt.stmt, …)` instead.
+ */
+export declare function rootNode(stmt: RawStmt | undefined): any;
+/**
+ * Depth-first walk over every node in a parse tree, invoking `visit` on each
+ * node. libpg_query marks nodes two ways depending on level: raw parse trees
+ * wrap each node in a single-key object (e.g. `{ SelectStmt: {...} }`), while
+ * `nodeType`-tagged trees use `{ nodeType: 'SelectStmt' }`. We support both.
+ *
+ * The node name is read from the *key* that holds the child, never from the
+ * child's own keys. A wrapper can sit directly inside a list — e.g.
+ * `fromClause[0].RangeFunction.functions[0].List.items[0].FuncCall` — and a
+ * walk that only recognises a wrapper when it is the sole key of a *nested*
+ * object silently misses every node in that position. That omission is a
+ * security bug here: it made `SELECT * FROM pg_read_file('/etc/passwd') AS
+ * t(contents)` collect zero function names and classify as a read.
+ */
+export declare function walkAst(node: unknown, visit: (type: string, payload: any) => void): void;
+/**
+ * Extract every function name referenced anywhere in the statement, lower-cased
+ * and dot-joined so both `pg_read_file` and `pg_catalog.pg_read_file` are
+ * recognised. PostgreSQL folds unquoted identifiers to lower case; folding
+ * quoted ones too (`"PG_READ_FILE"`) only ever makes the match set larger,
+ * which is the safe direction.
+ */
+export declare function collectFunctionNames(stmt: RawStmt): string[];
+/**
+ * True when the SELECT contains a data-modifying CTE
+ * (`WITH x AS (INSERT …) SELECT …`). PostgreSQL executes those even though the
+ * outer statement is a SELECT.
+ */
+export declare function hasWritableCte(selectNode: any): boolean;
+/** SELECT … INTO <table> creates and populates a table. */
+export declare function getSelectInto(selectNode: any): any | null;
+/** Row-level locking clauses (FOR UPDATE / FOR SHARE / FOR NO KEY UPDATE …). */
+export declare function getLockingClauses(selectNode: any): any[];
+/** Side effects a `SELECT` envelope can carry, anywhere in the statement. */
+export interface ReadSideEffects {
+    /** `SELECT … INTO <table>` creates and populates a table. */
+    selectsInto: boolean;
+    /** Row-level locking clauses: FOR UPDATE / SHARE / NO KEY UPDATE / KEY SHARE. */
+    lockingClauses: any[];
+    /** A data-modifying CTE (`WITH x AS (DELETE …) SELECT …`). */
+    writableCte: boolean;
+}
+/**
+ * Find every read-shaped side effect in a statement.
+ *
+ * This walks *all* `SelectStmt` nodes rather than only the outermost one: a
+ * locking clause or a data-modifying CTE in a sub-select or CTE body takes the
+ * same locks and performs the same writes as one at the top level.
+ */
+export declare function findReadSideEffects(stmt: RawStmt): ReadSideEffects;
+/**
+ * True for `EXPLAIN ANALYZE`, which EXECUTES the statement it explains.
+ *
+ * libpg_query does not expose an `analyze` flag on `ExplainStmt`; the option is
+ * a `DefElem` with `defname: 'analyze'` in the `options` list, so reading a
+ * boolean field (as an earlier version did) always reported false.
+ */
+export declare function explainExecutesStatement(node: any): boolean;
+/**
+ * Root nodes that are session/transaction utilities rather than schema changes.
+ * They still require elevated capability (utility maps to `ddl` in the role
+ * policy) but they are not DDL for audit purposes. Note that PostgreSQL's
+ * ANALYZE also parses as `VacuumStmt`, so it is covered here.
+ */
+export declare const UTILITY_ROOTS: ReadonlySet<string>;
+/** Statements whose root node performs row modifications. */
+export declare const WRITE_ROOTS: ReadonlySet<string>;
+/**
+ * Root nodes that are acceptable as "read only".
+ *
+ * This is an ALLOWLIST, not a denylist. Anything not listed here is not a
+ * read. That is the entire point: adding a new PostgreSQL statement type
+ * cannot accidentally make it readable.
+ */
+export declare const READ_ROOTS: ReadonlySet<string>;
+/**
+ * Root nodes that modify schema, roles, or persistent database state.
+ * Anything not in READ_ROOTS or WRITE_ROOTS and not here is `utility`.
+ */
+export declare const DDL_ROOTS: ReadonlySet<string>;
+/**
+ * Root nodes that cannot run inside a transaction block.
+ * Used by the migration strategy detector, which previously mis-classified
+ * `DROP INDEX CONCURRENTLY` and `ALTER SYSTEM` as transactional.
+ */
+export declare const NON_TRANSACTIONAL_ROOTS: ReadonlySet<string>;
+/** Roots that can execute arbitrary code or reach outside the database. */
+export declare const EXECUTABLE_ROOTS: ReadonlySet<string>;
+/**
+ * Functions that must never be reachable from a statement classified as a
+ * read, because they mutate state, read server files, reach other systems, or
+ * produce a side effect that escapes the transaction.
+ * Matched case-insensitively against the fully-qualified name *and* against
+ * the bare name, so `pg_catalog.pg_read_file` and `pg_read_file` both match.
+ *
+ * This list is NOT a security boundary and must not be presented as one. It is
+ * defence in depth in front of the control that is: every function a statement
+ * references is resolved against `pg_proc` and only `IMMUTABLE`, non-`SECURITY
+ * DEFINER` calls count as a read
+ * (`statement-classifier.ts` → `classifySelect`, `function-effects.ts`). That
+ * control is name-independent, which is what closes the class this list cannot:
+ * an operator's own `SECURITY DEFINER` helper around `pg_read_file`, or any
+ * VOLATILE function that INSERTs, parses as a plain `SELECT` and appears on no
+ * list at all.
+ *
+ * The claim that used to sit here — that a miss "cannot reach the host" because
+ * the connection is read-only — was FALSE. `default_transaction_read_only`
+ * constrains writes to relations and nothing else, and it does not span a
+ * second connection opened inside a function body. A read of a server file, a
+ * `NOTIFY` delivered on commit, an XID allocation, or a `dblink` round trip all
+ * succeed at `read_only`; only the write arm of a VOLATILE function is blocked.
+ * `RECOMMENDED_PG_ROLE` in `src/permissions/role-policy.ts` (the EXECUTE
+ * revokes, plus the default-privileges row that stops them decaying) is what a
+ * miss cannot get past.
+ */
+export declare const DENIED_READ_FUNCTIONS: ReadonlySet<string>;
+/**
+ * Name prefixes denied for the same reason as {@link DENIED_READ_FUNCTIONS}.
+ *
+ * Families are matched on the bare function name so `dblink_fetch_result` and
+ * `postgres_fdw_validator` cannot be used to walk around the explicit list.
+ * Prefix rules are cheaper than enumerating every member of a function family
+ * and cannot be evaded by picking a sibling we forgot to write down.
+ *
+ * `txid_`, `pg_advisory_` and `pg_snapshot_` are here because the families
+ * grow: `pg_advisory_xact_lock_shared` and `txid_current_if_assigned` exist on
+ * some releases and not others.
+ */
+export declare const DENIED_READ_FUNCTION_PREFIXES: readonly string[];
+/**
+ * Name suffixes denied for the same reason as {@link DENIED_READ_FUNCTIONS}.
+ *
+ * A prefix cannot express "every function whose name ends this way", and the
+ * families that matter are named by their suffix: `dblink_exec`,
+ * `dblink_send_query`, `postgres_fdw_disconnect`, `mysql_fdw_connect_u`. They
+ * are matched on the bare function name, exactly as the prefixes are.
+ *
+ * This costs generality, not safety: a function called `x_disconnect` that does
+ * nothing is refused as a read, which is the correct direction for a control
+ * that has to be conservative about names it cannot resolve.
+ */
+export declare const DENIED_READ_FUNCTION_SUFFIXES: readonly string[];
+/** True when a (lower-cased, dot-joined) function name is denied in a read. */
+export declare function isDeniedReadFunction(name: string): boolean;
+/** Every denylisted function a statement references. */
+export declare function findDeniedReadFunction(fnNames: Iterable<string>): string[];
+/**
+ * Node-level transactionality that the root-node set cannot express.
+ * libpg_query uses a `concurrent` boolean on IndexStmt and DropStmt.
+ */
+export declare function isNonTransactionalNode(rootType: string, node: any): boolean;
+//# sourceMappingURL=sql-parser.d.ts.map

package/dist/esm/execution/sql-parser.d.ts.map

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