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

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

@@ -0,0 +1,229 @@
+import { PoolClient } from 'pg';
+import { DbEntry } from '../config/db-config';
+import { PoolManagerEvents } from './types';
+import { resolveSearchPathComponents } from './search-path';
+/**
+ * The search_path helpers live in `./search-path` so the pure composition and
+ * verification logic can be tested without a pool or a database. They are
+ * re-exported here because `./execution/pool` is the module the rest of the
+ * codebase (and the tests) have always imported them from, and moving that
+ * would be a change with no security value.
+ */
+export { DEFAULT_SEARCH_PATH, PG_CATALOG_SCHEMA, PG_TEMP_SCHEMA, isBareSchemaIdentifier, parseSearchPathSetting, renderSearchPathSet, searchPathMatches, } from './search-path';
+/** Stable machine-readable classification of a pool failure. */
+export type PoolErrorCode = 'env_var_missing' | 'connection_failed' | 'auth_failed' | 'db_not_found' | 'ssl_error' | 'pool_exhausted' | 'unsafe_session_setting';
+/**
+ * Absolute hard ceiling on `statement_timeout`, in milliseconds.
+ *
+ * Nothing can raise this: not a `timeout_ms` in a cloud request, not the
+ * `SW_MAX_STATEMENT_TIMEOUT_MS` environment variable, and not the
+ * `PoolManager` option. It exists so that "hard-capped" is a property of the
+ * build rather than of whatever number is configured next.
+ */
+export declare const MAX_STATEMENT_TIMEOUT_MS = 900000;
+/**
+ * How long a statement may wait for a lock before it is cancelled. Without
+ * this, `SELECT ... FOR UPDATE` or a migration waiting on a DDL lock pins a
+ * pooled backend (and its transaction snapshot) until the client's own
+ * statement_timeout, which is per-statement and can be very large.
+ */
+export declare const LOCK_TIMEOUT_MS = 10000;
+/**
+ * How long a connection may sit idle inside an open transaction. An idle
+ * transaction holds a snapshot, blocks vacuum cleanup and pins a pool slot;
+ * this terminates the backend instead of letting it linger.
+ */
+export declare const IDLE_IN_TRANSACTION_TIMEOUT_MS: 1800000;
+/** Bounds for the per-pool connection count. */
+export declare const MIN_POOL_SIZE = 1;
+export declare const MAX_POOL_SIZE = 100;
+export declare const DEFAULT_POOL_SIZE = 15;
+export declare class PoolError extends Error {
+    code: PoolErrorCode;
+    cause?: Error | undefined;
+    constructor(code: PoolErrorCode, message: string, cause?: Error | undefined);
+}
+/**
+ * Declare that a pooled connection has been used for a stateful sequence — an
+ * open transaction, a cursor, or any statement that may have changed session
+ * GUCs — and can no longer be proven to hold nothing but the posture
+ * {@link PoolManager.acquire} established.
+ *
+ * Call this as soon as such a sequence starts. The connection is destroyed on
+ * release, which costs one reconnect; forgetting to call it costs a session
+ * GUC leak into the next request.
+ */
+export declare function markSessionDirty(client: PoolClient): void;
+export interface PoolManagerOptions {
+    /** Called when a pool opens/closes. */
+    events?: PoolManagerEvents;
+    /** Idle timeout before closing a pool. Default 60_000. */
+    idleTimeoutMs?: number;
+    /** Max connections per pool. Default 15. */
+    maxPoolSize?: number;
+    /**
+     * Absolute ceiling on statement_timeout in ms, regardless of what a request
+     * asks for. A remote caller must never be able to raise this.
+     */
+    maxStatementTimeoutMs?: number;
+}
+export type PoolSslConfig = boolean | {
+    ca?: Buffer;
+    rejectUnauthorized: boolean;
+    checkServerIdentity?: () => undefined;
+};
+/** True when `host` is an IPv4/IPv6 literal rather than a DNS name. */
+export declare function isIpLiteral(host: string | null | undefined): boolean;
+/**
+ * Warning text for a `verify-full` entry whose host is an IP literal, or `null`
+ * when no warning applies.
+ *
+ * node-postgres only sets the TLS `servername` for DNS names
+ * (`pg/lib/connection.js`: `if (net.isIP(host) === 0) options.servername = host`),
+ * so an IP-literal host such as `10.0.1.20` gets no `servername` and Node
+ * performs no hostname check at all — `verify-full` silently becomes
+ * `verify-ca`. An on-path attacker with any certificate from the same CA can
+ * therefore impersonate the server unless the certificate also carries an IP
+ * SAN that Node checks, which is rare.
+ */
+export declare function hostnameVerificationWarning(mode: string, host: string | null | undefined): string | null;
+/**
+ * The two non-verifying ssl modes are silent today, which is how a
+ * cleartext-password or MITM-able posture goes unnoticed. `require` is the
+ * default in `db add`, so this is the warning most users actually need.
+ */
+export declare function unauthenticatedTlsWarning(mode: string): string | null;
+/**
+ * Build node-postgres SSL options from a DbEntry's ssl settings.
+ *
+ * `verify-ca` and `verify-full` are genuinely different here: `verify-ca`
+ * pins the CA and deliberately skips the hostname comparison, `verify-full`
+ * lets Node perform it. An unknown mode throws rather than falling back to
+ * plaintext.
+ *
+ * `host` is optional and only used to warn about the IP-literal case; it never
+ * changes the returned object.
+ */
+export declare function buildSslConfig(mode: string, rootCert?: string | null, host?: string | null): PoolSslConfig;
+/**
+ * Stable fingerprint of every parameter that affects the connection or the
+ * session posture. The password is hashed, never included verbatim.
+ *
+ * `password_env` is part of the fingerprint in addition to the resolved
+ * secret: switching the entry from `password_stored` to an env var that happens
+ * to hold the same string still changes where the credential comes from, and a
+ * pool opened for one must not serve the other.
+ *
+ * The `search_path` contribution is the resolved component list joined with `,`.
+ * Components are validated bare identifiers, so they cannot contain `,` or a
+ * quote and the join is unambiguous — unlike a joined-then-resplit round-trip,
+ * which is exactly the defect  was.
+ */
+export declare function connectionFingerprint(entry: DbEntry, password: string): string;
+/**
+ * Clamp a caller-supplied timeout to a server-controlled ceiling.
+ *
+ * `requested <= 0` means "no timeout" in the PostgreSQL world and is never
+ * honoured: a remote caller must not be able to remove the ceiling by asking
+ * for zero, so it falls back to the default instead.
+ */
+export declare function clampStatementTimeout(requested: number | undefined, ceilingMs: number): number;
+export declare class PoolManager {
+    private pools;
+    private activeClientsCount;
+    private readonly opts;
+    constructor(opts?: PoolManagerOptions);
+    /**
+     * Ceiling for `statement_timeout`, in milliseconds. Configurable by the
+     * operator, never by a request, and never above {@link MAX_STATEMENT_TIMEOUT_MS}.
+     */
+    get maxStatementTimeoutMs(): number;
+    /**
+     * Connections per pool. `SW_PG_POOL_MAX` is operator-controlled but must not
+     * be able to set an arbitrary number: an unbounded value exhausts the
+     * database's `max_connections`, and a NaN/negative value makes node-postgres
+     * behave unpredictably. Garbage falls back to the default of 15.
+     */
+    get maxPoolSize(): number;
+    /**
+     * Get a pool client for the given DB entry.
+     * Opens the pool if it does not exist, or if the entry's connection
+     * parameters changed since the pool was created (so a rotated password or a
+     * changed TLS mode takes effect immediately instead of after the idle timer).
+     */
+    acquire(dbEntry: DbEntry): Promise<{
+        client: PoolClient;
+        release: () => void;
+        pid: number;
+    }>;
+    /**
+     * Put a freshly-checked-out connection into the posture this database entry
+     * is configured for, and clear anything a previous request left behind.
+     *
+     * This is the enforcement point that makes `read_only` physical rather than
+     * advisory: a `read_only` entry gets `default_transaction_read_only = on`, so
+     * PostgreSQL itself raises `25006` for a write — including a write smuggled
+     * in after a `SELECT` that every lexical layer agreed was a read. The value
+     * is read back and verified, and any failure here aborts the request.
+     */
+    private hardenSession;
+    /**
+     * Translate a driver/pg connection failure into a PoolError with a stable
+     * machine code and a message that names the database only by its alias.
+     *
+     * These messages are forwarded to the cloud and the browser, so host, port,
+     * username and database name must never appear in them: an authentication
+     * failure used to disclose the username and the `pg_hba.conf` verdict, and a
+     * refused connection disclosed the host and port of a production database.
+     * `cause` is retained for the local error log only and is never sent.
+     */
+    private mapConnectError;
+    /**
+     * Release a client back to the pool. Resets idle timer.
+     *
+     * A connection marked dirty could not be proven to be back in the posture
+     * this entry requires, so it is destroyed instead of recycled: the next
+     * request must not inherit an open transaction or a session GUC that the
+     * previous request left behind.
+     */
+    release(dbAlias: string, client: PoolClient): void;
+    /** Close a specific pool. */
+    closePool(dbAlias: string, reason?: 'idle' | 'explicit' | 'error'): Promise<void>;
+    /**
+     * Close any pool whose connection parameters no longer match the config.
+     * Called after the databases config file is reloaded so that a rotated
+     * password or a changed TLS mode takes effect immediately.
+     */
+    reconcile(databases: DbEntry[]): Promise<string[]>;
+    /** Close all pools. Used during shutdown. */
+    closeAll(): Promise<void>;
+    /** Check if a pool is currently open for this DB. */
+    hasPool(dbAlias: string): boolean;
+    /** Get stats for monitoring. */
+    getStats(): Array<{
+        db_alias: string;
+        total_count: number;
+        idle_count: number;
+        waiting_count: number;
+    }>;
+    /** Max bytes an inbound protocol message may occupy. Re-exported for the channel layer. */
+    static get maxMessageBytes(): number;
+}
+/**
+ * The permission level that actually applies to a database entry. Mirrors the
+ * dispatcher's resolution so the session posture can never disagree with the
+ * permission decision.
+ */
+export declare function effectivePermission(dbEntry: DbEntry, machineDefault?: string): string;
+/**
+ * The `search_path` to pin for this entry, as an ordered list of schema names.
+ *
+ *  renamed this function's contract from `string` to `string[]` and moved
+ * it to `./search-path`, together with {@link renderSearchPathSet} (which turns
+ * the list into the full `SET search_path = ...` statement) and
+ * {@link searchPathMatches} (which verifies the server reported exactly that
+ * list back). The list is the only representation now: joining it into a string
+ * and re-splitting it on `,` is what turned `public` into `" public"`.
+ */
+export declare const resolveSearchPath: typeof resolveSearchPathComponents;
+//# sourceMappingURL=pool.d.ts.map

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

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

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

@@ -0,0 +1,88 @@
+import { PoolManager } from './pool';
+import { DbEntry } from '../config/db-config';
+import { QueryPayload, QueryResultPayload, StreamQueryPayload, StreamChunkPayload, StreamEndPayload } from '../protocol/messages';
+import type { InFlightRequest, StatementClassification } from './types';
+export declare class QueryTooLargeError extends Error {
+    constructor(message: string);
+}
+export declare class StreamTooLargeError extends Error {
+    constructor(message: string);
+}
+export declare class CellSizeLimitError extends Error {
+    constructor(message: string);
+}
+export declare class QueryCancelledError extends Error {
+    constructor(message?: string);
+}
+export interface QueryRunnerOptions {
+    poolManager: PoolManager;
+}
+export interface QueryRunContext {
+    dbEntry: DbEntry;
+    request_id: string;
+    /**
+     * Called for each stream chunk. The runner AWAITS the returned promise, which
+     * is what makes backpressure real: `DataChannel.send` settles on the
+     * WebSocket send callback, so the fetch loop stops while the socket drains.
+     *
+     * The contract returns a Promise because it used to return void while the
+     * only implementation returned one: the discarded promise turned a rejected
+     * send into an unhandled rejection, which either killed the daemon (Node's
+     * `--unhandled-rejections=throw` default) or was swallowed by the global
+     * handler, truncating the stream with no `stream_end`.
+     */
+    onChunk?: (chunk: StreamChunkPayload) => Promise<void>;
+    /** Called when stream ends. Awaited, and only ever called once, on success. */
+    onEnd?: (end: StreamEndPayload) => void | Promise<void>;
+    /**
+     * Optional transport drain signal. When supplied, it is awaited before every
+     * fetch: the producer pauses while the socket is above the transport's
+     * buffered-amount watermark and resumes once it drains. Without it the
+     * runner still stops on every awaited send, which throttles the producer to
+     * the socket but cannot observe the buffer directly.
+     */
+    waitForDrain?: () => Promise<void>;
+    /** Abort signal for cancellation. */
+    abortSignal?: AbortSignal;
+    /**
+     * Parsed classification of `payload.sql`. Decides whether the one-shot read
+     * may be fetched through a cursor. Omitting it is treated as "not provably a
+     * read", which is the fail-closed default.
+     */
+    classification?: StatementClassification;
+    registerInFlight?: (req: InFlightRequest) => void;
+    unregisterInFlight?: (request_id: string) => void;
+}
+export declare class QueryRunner {
+    private readonly poolManager;
+    constructor(opts: QueryRunnerOptions);
+    /**
+     * Run a one-shot query and return the whole result.
+     *
+     * Reads are fetched through the shared cursor so the row ceiling is enforced
+     * WHILE rows are produced. The previous implementation called `client.query`
+     * and only then compared `res.rows.length` against MAX_QUERY_ROWS, which meant
+     * a single `SELECT repeat('x', 1048576) FROM generate_series(1,5000000)` could
+     * exhaust memory before the check ever ran.
+     *
+     * Statements that are not provably reads are executed directly, because a
+     * cursor would force them into a transaction and change their semantics. They
+     * still travel over the extended query protocol, and they are still subject to
+     * the `read_only` connection posture.
+     */
+    runOneShot(payload: QueryPayload, ctx: QueryRunContext): Promise<QueryResultPayload>;
+    /**
+     * Run a streaming query, emitting chunks as rows are fetched.
+     *
+     * Chunks flush on 100 rows, 64 KB, or 100 ms, whichever comes first. The
+     * cursor is the same shared mechanism `runOneShot` uses, and `ctx.onChunk` is
+     * awaited, so a slow relay stops the fetch loop instead of buffering the
+     * entire result in the WebSocket send buffer.
+     *
+     * Exactly one terminal outcome is emitted: either `onEnd` on success, or a
+     * thrown error that the caller turns into a single `error` frame. A chunk
+     * send that rejects therefore ends the stream instead of leaving it open.
+     */
+    runStreaming(payload: StreamQueryPayload, ctx: QueryRunContext): Promise<void>;
+}
+//# sourceMappingURL=query-runner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"query-runner.d.ts","sourceRoot":"","sources":["../../../src/execution/query-runner.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAA2C,MAAM,QAAQ,CAAC;AAC9E,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,sBAAsB,CAAC;AAI9B,OAAO,KAAK,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAExE,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,GAAE,MAA8B;CAIpD;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,+EAA+E;IAC/E,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,qCAAqC;IACrC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;OAIG;IACH,cAAc,CAAC,EAAE,uBAAuB,CAAC;IACzC,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,IAAI,CAAC;IAClD,kBAAkB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;CACnD;AAyfD,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;gBAE9B,IAAI,EAAE,kBAAkB;IAIpC;;;;;;;;;;;;;OAaG;IACG,UAAU,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA4I1F;;;;;;;;;;;OAWG;IACG,YAAY,CAAC,OAAO,EAAE,kBAAkB,EAAE,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;CAoKrF"}

package/dist/types/execution/rate-limiter.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Operations that consume budget. Every inbound message type maps onto exactly
+ * one of these; `other` is the fail-safe bucket for a type this module does
+ * not recognise, so a new message type is rate limited by default rather than
+ * exempt by omission.
+ */
+export type RateLimitedAction = 'ping' | 'introspect' | 'query' | 'stream_query' | 'migration_run' | 'cancel' | 'event' | 'other';
+/** Token-bucket shape: a burst allowance plus a sustained refill rate. */
+export interface RateLimitPolicy {
+    /** Bucket capacity. One request per token. */
+    burst: number;
+    /** Tokens added per second while the bucket is below capacity. */
+    per_second: number;
+}
+/** Who is spending budget. All three components are attacker-controlled. */
+export interface RateLimitIdentity {
+    agent_id: string;
+    user_id: string;
+    db_alias: string;
+}
+/** Which limit refused the request. */
+export type RateLimitScope = 'global' | 'identity' | 'concurrency_global' | 'concurrency_db';
+/** Result of an admission check. */
+export interface RateLimitVerdict {
+    allowed: boolean;
+    scope?: RateLimitScope;
+    /** Curated, data-free text safe to forward to the browser. */
+    reason?: string;
+    retry_after_ms: number;
+}
+/** An admitted request. `release` must be called exactly once when it finishes. */
+export interface RateLimitPermit extends RateLimitVerdict {
+    release: () => void;
+}
+/**
+ * Default budget per action.
+ *
+ * `introspect` is deliberately the tightest: one call runs eleven catalogue
+ * queries and returns the entire schema, so it is the cheapest request to make
+ * and the most valuable one to an attacker exfiltrating a schema.
+ */
+export declare const DEFAULT_RATE_LIMIT_POLICIES: Record<RateLimitedAction, RateLimitPolicy>;
+/** Ceiling for everything the connector does, whatever the caller's identity. */
+export declare const DEFAULT_GLOBAL_POLICY: RateLimitPolicy;
+export declare const DEFAULT_MAX_INFLIGHT = 32;
+export declare const DEFAULT_MAX_INFLIGHT_PER_DB = 8;
+export interface RateLimiterOptions {
+    /** Per-action budget overrides, merged over {@link DEFAULT_RATE_LIMIT_POLICIES}. */
+    policies?: Partial<Record<RateLimitedAction, RateLimitPolicy>>;
+    /** Global budget override. */
+    global?: Partial<RateLimitPolicy>;
+    /** Concurrent admitted requests across every identity. */
+    max_inflight?: number;
+    /** Concurrent admitted requests for a single `db_alias`. */
+    max_inflight_per_db?: number;
+    /** Hard cap on tracked buckets, so the key space cannot grow without bound. */
+    max_tracked_keys?: number;
+    /** A bucket untouched for this long is evicted. */
+    idle_ttl_ms?: number;
+    /** Serialized introspection snapshot ceiling, in bytes. */
+    max_introspect_bytes?: number;
+    /** Clock injection point; tests supply a deterministic clock. */
+    now?: () => number;
+}
+export declare class RateLimiter {
+    private readonly policies;
+    private readonly globalPolicy;
+    private readonly maxInflight;
+    private readonly maxInflightPerDb;
+    private readonly maxTrackedKeys;
+    private readonly idleTtlMs;
+    private readonly sweepIntervalMs;
+    private readonly maxIntrospectBytes;
+    private readonly now;
+    /**
+     * Buckets keyed by `identity\u0000action`, plus the global bucket. Insertion
+     * order is maintained on touch, which makes the oldest entry the least
+     * recently used one and the entry evicted when the cap is reached.
+     */
+    private readonly buckets;
+    private readonly globalBucket;
+    private readonly inflightByDb;
+    private inflight;
+    private lastSweepAt;
+    constructor(opts?: RateLimiterOptions);
+    /** Number of tracked buckets. Exposed so boundedness is assertable. */
+    trackedKeys(): number;
+    /** Requests admitted and not yet released. */
+    inflightCount(): number;
+    limits(): {
+        global: RateLimitPolicy;
+        max_inflight: number;
+        max_inflight_per_db: number;
+        max_tracked_keys: number;
+    };
+    /**
+     * Admit one request, spending budget from the global bucket, the caller's
+     * per-identity bucket and the concurrency counters.
+     *
+     * The returned permit must be released exactly when the request finishes,
+     * including on every error path: an unreleased permit permanently consumes
+     * concurrency capacity.
+     */
+    tryAcquire(action: RateLimitedAction, identity: RateLimitIdentity): RateLimitPermit;
+    /**
+     * Size budget for one introspection response. A snapshot above the ceiling
+     * still cost eleven catalogue queries on the server, but it is not shipped,
+     * which is what bounds schema exfiltration.
+     */
+    checkIntrospectSize(bytes: number): RateLimitVerdict;
+    private deny;
+    /** Take one token, refilling for elapsed time first. */
+    private spend;
+    private bucketFor;
+    private releaseSlot;
+    /** Drop buckets that have been idle past the TTL, then enforce the cap. */
+    private sweep;
+    private evictOne;
+}
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/types/execution/rate-limiter.d.ts.map

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

package/dist/types/execution/search-path.d.ts

@@ -0,0 +1,161 @@
+/**
+ * `search_path` composition and verification.
+ *
+ * WHY THIS IS A SEPARATE MODULE
+ * -----------------------------
+ * This was a *seam* defect. `resolveSearchPath()` produced a correct
+ * intermediate string (`'analytics, public'`), `quoteSearchPath()` re-split that
+ * string on `,` **without trimming**, and the two halves disagreed about what a
+ * component was:
+ *
+ *     config   "analytics, public"
+ *       -> resolveSearchPath  ->  "analytics, public"      (looks right)
+ *       -> quoteSearchPath    ->  SET search_path = "analytics", " public"
+ *
+ * The second component is a schema literally named `" public"` — a name that
+ * does not exist — so the real `public` schema silently left the resolution
+ * path and every unqualified name resolved to whichever schema came first. The
+ * post-condition guard at `pool.ts` then passed, because it asked
+ * `actualPath.toLowerCase().includes('public')` and `" public"` contains
+ * `public`. The control written to catch this was defeated by the same defect
+ * it was checking for.
+ *
+ * The fix is structural rather than a patch: there is now **no string
+ * round-trip at all**. A list of schema names is resolved once, rendered once,
+ * and the post-condition compares that same list against what PostgreSQL reports
+ * — component by component, in order. A component can never acquire or lose a
+ * space, a quote or a comma between "what we intended" and "what the server
+ * was told", because it is a string element the whole way through and the only
+ * place a separator appears is where the renderer and the verifier each derive
+ * it independently from the same array.
+ *
+ * Everything here is pure: no database, no pool, no I/O. That is deliberate —
+ * the unit suite asserts the *composed statement* here rather than the
+ * intermediate value, which is precisely the seam the previous test missed.
+ */
+import type { DbEntry } from '../config/db-config';
+/**
+ * `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 declare 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 declare 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 declare const PG_TEMP_SCHEMA = "pg_temp";
+/**
+ * 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 declare function isBareSchemaIdentifier(name: string): boolean;
+/**
+ * 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 declare function resolveSearchPathComponents(entry: DbEntry): string[];
+/**
+ * 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 declare function renderSearchPathSet(components: readonly string[]): string;
+/**
+ * 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 declare function parseSearchPathSetting(value: string): string[];
+/**
+ * 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 declare function searchPathMatches(actual: string, expected: readonly string[]): boolean;
+/**
+ * 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 declare function describeSearchPathSetting(value: string): string;
+//# sourceMappingURL=search-path.d.ts.map

package/dist/types/execution/search-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-path.d.ts","sourceRoot":"","sources":["../../../src/execution/search-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,WAAW,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,eAAe,CAAC;AAE9C;;;;;GAKG;AACH,eAAO,MAAM,cAAc,YAAY,CAAC;AAaxC;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE5D;AAiDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CA8BpE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAMzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAiD9D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAKtF;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/D"}