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

package/dist/esm/protocol/messages.d.ts

@@ -0,0 +1,327 @@
+import { MigrationStatementStatus, EventKind } from './envelope';
+import { ErrorCode } from './errors';
+export interface PingPayload {
+    /** Sender's epoch ms when ping was sent. */
+    sent_at: number;
+    /** Optional: sender reports its agent_id or browser_session_id. */
+    sender_id?: string;
+}
+export interface IntrospectPayload {
+    /** Include views in snapshot. Default true. */
+    include_views: boolean;
+    /** Include indexes. Default true. */
+    include_indexes: boolean;
+    /** Include triggers. Default false (expensive). */
+    include_triggers: boolean;
+    /** Include partitions. Default true. */
+    include_partitions: boolean;
+    /** Include extensions. Default true. */
+    include_extensions: boolean;
+    /**
+     * Declared server version the caller expects, e.g. "16.2", or null for "no
+     * expectation".
+     *
+     * Honoured, not ignored (audit L-08): the agent compares the major version
+     * against the server it is actually connected to and refuses the request on a
+     * mismatch, so a snapshot taken against a different server than the caller
+     * believes is never presented as this one.
+     */
+    pg_version_hint: string | null;
+}
+export interface IntrospectResultPayload {
+    /** PG version string, e.g. "16.2". */
+    pg_version: string;
+    /** When snapshot was taken (epoch ms). */
+    snapshot_at: number;
+    /** Schema snapshot. Structure mirrors pg-ddl-parser output (ParsedSchema). */
+    schema: unknown;
+    /** List of installed extensions. */
+    extensions: Array<{
+        name: string;
+        version: string;
+        enabled: boolean;
+    }>;
+    /** List of schemas (namespaces). */
+    schemas: string[];
+    /**
+     * On-disk size of the database, from `pg_database_size`, or `null` when the
+     * server does not permit it to be read.
+     *
+     * Audit M-30: this field previously carried the JSON byte length of the
+     * snapshot itself, so a viewer of the API could reasonably read it as the
+     * database size and be wrong by orders of magnitude. The response's own size
+     * is now reported separately and honestly as `snapshot_json_bytes`.
+     */
+    size_bytes: number | null;
+    /** Serialised size of this snapshot, in bytes. Use this for budgeting. */
+    snapshot_json_bytes: number;
+    /**
+     * Detail level actually applied, after the requester's role was taken into
+     * account. `structure` means definitions, defaults, trigger metadata, owners,
+     * comments and partition bounds were omitted.
+     */
+    detail: 'full' | 'structure';
+}
+export interface QueryPayload {
+    /** SQL statement. Single statement only. Multi-statement = rejected. */
+    sql: string;
+    /** Parameter values for prepared statement. */
+    params?: unknown[];
+    /** Override default timeout. 0 = no timeout (dangerous). */
+    timeout_ms?: number;
+    /** Intent tag (advisory only — agent re-parses to verify). */
+    intent: 'read' | 'write' | 'ddl' | 'migration';
+    /** If intent='migration', the pre-registered plan_id (anti-spoofing). */
+    plan_id?: string;
+}
+export interface QueryResultPayload {
+    /** Column metadata. */
+    columns: Array<{
+        name: string;
+        type_oid: number;
+        type_name: string;
+    }>;
+    /** Row data. Each row is an array of cell values (in column order). */
+    rows: unknown[][];
+    /** Rows affected (for INSERT/UPDATE/DELETE). -1 if not applicable. */
+    rows_affected: number;
+    /** Execution time in ms. */
+    ms: number;
+    /** Whether result was truncated due to MAX_QUERY_ROWS. */
+    truncated: boolean;
+}
+/**
+ * Keyset pagination cursor. `column` is applied as an ordered, exclusive bound
+ * on the result (`>` forward, `<` backward), so a page never re-reads or skips
+ * the rows already seen the way an offset does.
+ */
+export interface StreamCursor {
+    column: string;
+    last_value: unknown;
+    direction: 'forward' | 'backward';
+}
+export interface StreamQueryPayload {
+    sql: string;
+    params?: unknown[];
+    timeout_ms?: number;
+    intent: 'read' | 'write' | 'ddl' | 'migration';
+    plan_id?: string;
+    /** Optional: cursor for pagination. If provided, agent uses cursor-based fetch. */
+    cursor?: StreamCursor;
+    /** Page size for cursor pagination. Default 50 (Data Explorer mode). */
+    page_size?: number;
+}
+export interface StreamChunkPayload {
+    /** Matches the stream_query request id. */
+    request_id: string;
+    /** Column metadata (sent on first chunk only, null on subsequent). */
+    columns: Array<{
+        name: string;
+        type_oid: number;
+        type_name: string;
+    }> | null;
+    /** Row data in this chunk. */
+    rows: unknown[][];
+    /** Chunk sequence number (0, 1, 2, ...). */
+    chunk_index: number;
+    /** Whether any cell in this chunk was truncated due to MAX_CELL_BYTES. */
+    has_truncated_cells: boolean;
+}
+export interface StreamEndPayload {
+    request_id: string;
+    /** Total rows across all chunks. */
+    total_rows: number;
+    /** Whether stream was truncated due to MAX_STREAM_ROWS. */
+    truncated: boolean;
+    /** Total execution time in ms. */
+    ms: number;
+    /** Chunk count sent. */
+    chunk_count: number;
+    /**
+     * True when the request carried a cursor and the page ended with rows still
+     * available on the server. Absent means the whole result was delivered.
+     */
+    has_more?: boolean;
+    /** Cursor for the next page. Present only when `has_more` is true. */
+    next_cursor?: StreamCursor;
+}
+export interface MigrationRunPayload {
+    /** Pre-registered plan ID (anti-spoofing). */
+    plan_id: string;
+    /** SQL statements in order. */
+    statements: string[];
+    /** Execution strategy. */
+    strategy: 'single_tx' | 'per_statement';
+    /** Optional timeout override. */
+    timeout_ms?: number;
+    /** Whether to dry-run (parse only, no execution). */
+    dry_run: boolean;
+}
+export interface MigrationResultPayload {
+    plan_id: string;
+    /** Final status. */
+    status: 'committed' | 'rolled_back' | 'partial' | 'dry_run_ok' | 'dry_run_failed';
+    /** Per-statement outcome. */
+    statements: Array<{
+        index: number;
+        status: MigrationStatementStatus;
+        ms: number;
+        rows_affected: number;
+        error?: string;
+        pg_error_code?: string;
+    }>;
+    /** Total execution time in ms. */
+    total_ms: number;
+    /** If rolled_back: which statement indices were rolled back. */
+    rolled_back_indices: number[];
+    /** If strategy was auto-switched (e.g. CONCURRENTLY detected), original strategy is here. */
+    strategy_changed_from?: 'single_tx' | 'per_statement';
+}
+export interface CancelPayload {
+    /** The request_id to cancel. */
+    target_id: string;
+    /** Reason for cancellation (for audit). */
+    reason: 'user_cancelled' | 'timeout' | 'session_closed' | 'orphaned';
+}
+export interface CancelResultPayload {
+    target_id: string;
+    /** Whether the cancel signal was sent. */
+    cancelled: boolean;
+    /** Whether the original request actually terminated. */
+    terminated: boolean;
+    /**
+     * Whether the agent's in-process cooperative abort fired. True here with
+     * `terminated: false` means the request stopped locally while the
+     * PostgreSQL backend could not be signalled.
+     */
+    local_abort?: boolean;
+    /** If false, why not. */
+    reason?: string;
+}
+export interface ResponsePayload<T = unknown> {
+    /** Matches the request_id. */
+    request_id: string;
+    /** Whether the request succeeded. */
+    ok: boolean;
+    /** Type-specific result. Shape depends on the original request type. */
+    data: T;
+    /** Execution time in ms (for queries/migrations). */
+    ms?: number;
+}
+/** PG-specific error fields that may appear on the wire. */
+export interface PgErrorSummary {
+    /** SQLSTATE, e.g. "23505". Stable, so the browser can branch on failure kind. */
+    code: string;
+    /** ERROR, FATAL, PANIC, WARNING, NOTICE, DEBUG or INFO. */
+    severity: string;
+    /**
+     * Operator-facing hint, always one of the agent's own curated strings for the
+     * SQLSTATE. It is never PostgreSQL's `hint` field, which can quote schema
+     * and column names and suggest DDL the caller did not ask for.
+     */
+    hint?: string;
+}
+/**
+ * 3.10 Error
+ *
+ * `pg_error` is an allow-list of two fields. PostgreSQL `DETAIL` and `HINT`
+ * lines routinely contain row data (`DETAIL:  Key (email)=(alice@corp.com)
+ * already exists.`) and error messages embed the offending SQL and absolute
+ * filesystem paths, so neither is carried on this frame; the agent substitutes
+ * a curated message per SQLSTATE instead.
+ */
+export interface ErrorPayload {
+    request_id: string;
+    /** Stable error code (see errors.ts catalog). */
+    code: ErrorCode;
+    /** Human-readable message. Safe to show in browser UI. */
+    message: string;
+    /** Optional: reduced, data-free PostgreSQL error summary. */
+    pg_error?: PgErrorSummary;
+    /** Whether the error is fatal (connection should be torn down). */
+    fatal: boolean;
+    /** Whether the error is retryable (browser may auto-retry). */
+    retryable: boolean;
+}
+export interface EventPayload {
+    kind: EventKind;
+    /** Type-specific event data. */
+    data: EventData;
+}
+export type EventData = StatusChangeEvent | MigrationProgressEvent | ApprovalRequiredEvent | ApprovalResponseEvent | WarningEvent | ResumeRequestEvent;
+export interface StatusChangeEvent {
+    new_status: 'online' | 'offline' | 'degraded' | 'maintenance';
+    reason?: string;
+}
+export interface MigrationProgressEvent {
+    plan_id: string;
+    statement_index: number;
+    /**
+     * Preview of the statement. MUST be redacted (`redactSqlLiterals`) before it
+     * is transmitted: it is shipped to the cloud by default, and a raw
+     * `substring(0, 100)` carries every literal in the first 100 characters.
+     */
+    statement_sql_preview: string;
+    status: MigrationStatementStatus;
+    ms?: number;
+    error?: string;
+    /** True if this event is a replay after reconnect (not fresh). */
+    replayed?: boolean;
+}
+export interface ApprovalRequiredEvent {
+    request_id: string;
+    sql: string;
+    /** Redacted + truncated preview. Safe to log and to transmit. */
+    sql_preview: string;
+    intent: 'write' | 'ddl';
+    db_alias: string;
+    /**
+     * Unguessable value minted by the agent. The approver must echo it back in
+     * ApprovalResponseEvent; without it any sender could approve any pending
+     * write by guessing the request id.
+     */
+    approval_nonce: string;
+    /** When approval expires (epoch ms). */
+    expires_at: number;
+}
+export interface ApprovalResponseEvent {
+    request_id: string;
+    approved: boolean;
+    /**
+     * Must equal the `approval_nonce` from the corresponding ApprovalRequiredEvent.
+     * Verified by the agent.
+     */
+    approval_nonce: string;
+    /**
+     * Display-only. The agent IGNORES this value and records the approver from
+     * the authenticated envelope instead, so a spoofed string cannot be used to
+     * fabricate an approval in the audit log.
+     */
+    approved_by?: string;
+}
+export interface WarningEvent {
+    code: string;
+    message: string;
+    /** Optional context object. */
+    context?: Record<string, unknown>;
+}
+export interface ResumeRequestEvent {
+    /** The request_id to resume (after reconnect). */
+    request_id: string;
+}
+export type AnyPayload = PingPayload | IntrospectPayload | QueryPayload | StreamQueryPayload | StreamChunkPayload | StreamEndPayload | MigrationRunPayload | MigrationResultPayload | CancelPayload | CancelResultPayload | ResponsePayload | ErrorPayload | EventPayload;
+/** Maps message type → expected payload type. */
+export interface PayloadByType {
+    ping: PingPayload;
+    introspect: IntrospectPayload | ResponsePayload<IntrospectResultPayload>;
+    query: QueryPayload | ResponsePayload<QueryResultPayload>;
+    stream_query: StreamQueryPayload;
+    stream_chunk: StreamChunkPayload;
+    stream_end: StreamEndPayload;
+    migration_run: MigrationRunPayload | ResponsePayload<MigrationResultPayload>;
+    cancel: CancelPayload | ResponsePayload<CancelResultPayload>;
+    response: ResponsePayload;
+    error: ErrorPayload;
+    event: EventPayload;
+}
+//# sourceMappingURL=messages.d.ts.map

package/dist/esm/protocol/messages.d.ts.map

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

package/dist/esm/protocol/messages.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=messages.js.map

package/dist/esm/protocol/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../../../src/protocol/messages.ts"],"names":[],"mappings":""}

package/dist/esm/protocol/serialize.d.ts

@@ -0,0 +1,26 @@
+import { AgentMessage } from './envelope';
+import { ErrorCode } from './errors';
+export declare class ProtocolError extends Error {
+    code: ErrorCode;
+    fatal: boolean;
+    constructor(code: ErrorCode, message: string, fatal?: boolean);
+}
+/**
+ * Serialize an AgentMessage to a UTF-8 JSON string.
+ * Throws ProtocolError if message exceeds MAX_PAYLOAD_BYTES.
+ */
+export declare function serialize<T>(msg: AgentMessage<T>): string;
+/**
+ * Deserialize a JSON string into a typed AgentMessage.
+ * Throws ProtocolError on JSON parse error, size limit, or protocol version mismatch.
+ */
+export declare function deserialize<T = unknown>(raw: string): AgentMessage<T>;
+/**
+ * Serialize to Uint8Array (for WebSocket binary frames).
+ */
+export declare function serializeToBytes<T>(msg: AgentMessage<T>): Uint8Array;
+/**
+ * Deserialize from Uint8Array.
+ */
+export declare function deserializeFromBytes<T = unknown>(bytes: Uint8Array): AgentMessage<T>;
+//# sourceMappingURL=serialize.d.ts.map

package/dist/esm/protocol/serialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../../../src/protocol/serialize.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1C,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAErC,qBAAa,aAAc,SAAQ,KAAK;IAE7B,IAAI,EAAE,SAAS;IAEf,KAAK,EAAE,OAAO;gBAFd,IAAI,EAAE,SAAS,EACtB,OAAO,EAAE,MAAM,EACR,KAAK,GAAE,OAAe;CAKhC;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,MAAM,CAMzD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC,CA0BrE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,GAAG,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,UAAU,CAGpE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,UAAU,GAAG,YAAY,CAAC,CAAC,CAAC,CAGpF"}

package/dist/esm/protocol/serialize.js

@@ -0,0 +1,63 @@
+import { LIMITS, PROTOCOL_VERSION } from './constants';
+export class ProtocolError extends Error {
+    code;
+    fatal;
+    constructor(code, message, fatal = false) {
+        super(message);
+        this.code = code;
+        this.fatal = fatal;
+        this.name = 'ProtocolError';
+    }
+}
+/**
+ * Serialize an AgentMessage to a UTF-8 JSON string.
+ * Throws ProtocolError if message exceeds MAX_PAYLOAD_BYTES.
+ */
+export function serialize(msg) {
+    const json = JSON.stringify(msg);
+    if (Buffer.byteLength(json, 'utf8') > LIMITS.MAX_PAYLOAD_BYTES) {
+        throw new ProtocolError('invalid_message', 'Message exceeds maximum payload size');
+    }
+    return json;
+}
+/**
+ * Deserialize a JSON string into a typed AgentMessage.
+ * Throws ProtocolError on JSON parse error, size limit, or protocol version mismatch.
+ */
+export function deserialize(raw) {
+    if (Buffer.byteLength(raw, 'utf8') > LIMITS.MAX_PAYLOAD_BYTES) {
+        throw new ProtocolError('invalid_message', 'Message exceeds maximum payload size');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        // Deliberately no `err.message`: V8 quotes the offending input in its parse
+        // errors, so the frame that carried a statement or a secret would be
+        // echoed back verbatim.
+        throw new ProtocolError('invalid_message', 'Malformed JSON');
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        throw new ProtocolError('invalid_message', 'Message must be a JSON object');
+    }
+    if (parsed.v !== PROTOCOL_VERSION) {
+        throw new ProtocolError('protocol_version_mismatch', 'Protocol version mismatch. Expected version 1.');
+    }
+    return parsed;
+}
+/**
+ * Serialize to Uint8Array (for WebSocket binary frames).
+ */
+export function serializeToBytes(msg) {
+    const json = serialize(msg);
+    return Buffer.from(json, 'utf8');
+}
+/**
+ * Deserialize from Uint8Array.
+ */
+export function deserializeFromBytes(bytes) {
+    const json = Buffer.from(bytes).toString('utf8');
+    return deserialize(json);
+}
+//# sourceMappingURL=serialize.js.map

package/dist/esm/protocol/serialize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.js","sourceRoot":"","sources":["../../../src/protocol/serialize.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGvD,MAAM,OAAO,aAAc,SAAQ,KAAK;IAE7B;IAEA;IAHT,YACS,IAAe,EACtB,OAAe,EACR,QAAiB,KAAK;QAE7B,KAAK,CAAC,OAAO,CAAC,CAAC;QAJR,SAAI,GAAJ,IAAI,CAAW;QAEf,UAAK,GAAL,KAAK,CAAiB;QAG7B,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAI,GAAoB;IAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,iBAAiB,EAAE,CAAC;QAC/D,MAAM,IAAI,aAAa,CAAC,iBAAiB,EAAE,sCAAsC,CAAC,CAAC;IACrF,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAc,GAAW;IAClD,IAAI,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,iBAAiB,EAAE,CAAC;QAC9D,MAAM,IAAI,aAAa,CAAC,iBAAiB,EAAE,sCAAsC,CAAC,CAAC;IACrF,CAAC;IACD,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,4EAA4E;QAC5E,qEAAqE;QACrE,wBAAwB;QACxB,MAAM,IAAI,aAAa,CAAC,iBAAiB,EAAE,gBAAgB,CAAC,CAAC;IAC/D,CAAC;IAED,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC1C,MAAM,IAAI,aAAa,CAAC,iBAAiB,EAAE,+BAA+B,CAAC,CAAC;IAC9E,CAAC;IAED,IAAI,MAAM,CAAC,CAAC,KAAK,gBAAgB,EAAE,CAAC;QAClC,MAAM,IAAI,aAAa,CACrB,2BAA2B,EAC3B,gDAAgD,CACjD,CAAC;IACJ,CAAC;IAED,OAAO,MAAyB,CAAC;AACnC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAI,GAAoB;IACtD,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IAC5B,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AACnC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAc,KAAiB;IACjE,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACjD,OAAO,WAAW,CAAI,IAAI,CAAC,CAAC;AAC9B,CAAC"}

package/dist/esm/protocol/validate.d.ts

@@ -0,0 +1,135 @@
+import { AgentMessage, MessageType, Role } from './envelope';
+/**
+ * Validate the envelope structure (not the payload).
+ * Checks: required fields present, types correct, v=1, type is valid enum,
+ *         project/user/db_alias/id non-empty, ts is a number.
+ * Throws ProtocolError on any failure.
+ *
+ * Shape only. This proves the envelope is well-formed, never that its contents
+ * are authentic — use `InboundEnvelopeGuard` for that.
+ */
+export declare function validateEnvelope(msg: unknown): asserts msg is AgentMessage;
+export interface InboundEnvelopeGuardOptions {
+    /**
+     * Per-session MAC key, from `deriveSessionMacKey({ dataChannelToken, agentId,
+     * browserSessionId })`.
+     */
+    macKey: Buffer;
+    /**
+     * Roles the cloud negotiated when this session was created. An envelope whose
+     * `user.role` is not in this set is rejected even when its MAC is valid: the
+     * relay must not be able to escalate a session to a role it did not ask for.
+     */
+    allowedRoles: readonly Role[];
+    /**
+     * Reject envelopes that carry no MAC. Defaults to
+     * ENVELOPE_MAC_REQUIRED_DEFAULT (true). Only a deliberate machine-config
+     * override turns this off; an envelope that does carry a MAC must always
+     * verify.
+     */
+    requireMac?: boolean;
+    /** Maximum absolute skew tolerated on `ts`. Defaults to DEFAULTS.ENVELOPE_MAX_CLOCK_SKEW_MS. */
+    maxClockSkewMs?: number;
+    /**
+     * Hard local ceiling on the role a frame may assert, applied in `verify()`
+     * AFTER the negotiated-set check. Defaults to
+     * ENVELOPE_MAX_NEGOTIABLE_ROLE_DEFAULT (`developer`).
+     *
+     * This is deliberately independent of `allowedRoles`. A caller that computed
+     * the negotiated set wrongly — or that was never told about the operator's
+     * ceiling at all — cannot widen this ceiling by widening the set.
+     */
+    maxNegotiableRole?: Role;
+    /** Replay cache capacity. Defaults to LIMITS.REPLAY_CACHE_MAX_ENTRIES. */
+    replayCacheEntries?: number;
+    /** Clock injection point for tests. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * Fails an envelope closed on: a bad or missing MAC, a stale `ts`, a replayed
+ * `nonce`, a `user.role` that was not negotiated for this session, or a
+ * `user.role` above this installation's local ceiling.
+ *
+ * Every rejection throws a fatal ProtocolError; there is no "log and proceed"
+ * path. Call `verify` on the *inbound* path only, before the message reaches the
+ * dispatcher — after this point `msg.user.role` may be treated as an
+ * authenticated fact rather than a claim.
+ */
+export declare class InboundEnvelopeGuard {
+    private readonly opts;
+    /** nonce -> `ts` at first sight. Insertion-ordered so eviction is FIFO. */
+    private readonly seenNonces;
+    constructor(options: InboundEnvelopeGuardOptions);
+    /** Roles this guard will accept. */
+    getAllowedRoles(): Role[];
+    /**
+     * The local role ceiling this guard enforces, whatever it was handed as
+     * `allowedRoles`. Reported so an operator surface (`sw-agent status`,
+     * `doctor`) can state the effective bound rather than the negotiated set.
+     */
+    getMaxNegotiableRole(): Role;
+    /** Number of nonces currently held in the replay cache. */
+    replayCacheSize(): number;
+    /** Forget every seen nonce. Call when the session ends or rolls over. */
+    reset(): void;
+    /**
+     * Authenticate and admit one inbound envelope, or throw. Checks run cheapest
+     * and most decisive first: nonce shape, freshness, MAC, replay, negotiated role.
+     */
+    verify(msg: AgentMessage): void;
+}
+/**
+ * Validate the payload for a given message type.
+ * Each type has its own validator.
+ * Throws ProtocolError with code 'payload_invalid' on failure.
+ */
+export declare function validatePayload(type: MessageType, payload: unknown): void;
+/**
+ * Convenience: validate envelope + payload together.
+ */
+export declare function validateMessage(msg: unknown): asserts msg is AgentMessage;
+export declare function validatePingPayload(p: unknown): void;
+export declare function validateIntrospectPayload(p: unknown): void;
+/**
+ * Count the top-level statements in a SQL string.
+ *
+ * This is a lexical scan, not a parser, and it is written to be sound over the
+ * constructs an attacker would use to hide a `;` from it:
+ *
+ *   - `'...'` string constants, where `''` is an escaped quote;
+ *   - `E'...'` / `B'...'` / `X'...'` / `N'...'` prefixed constants;
+ *   - `U&'...'` unicode constants, whose escapes are backslash sequences, plus
+ *     the optional trailing `UESCAPE '<char>'` clause;
+ *   - dollar quoting, both `$$...$$` and `$tag$...$tag$`;
+ *   - `"..."` quoted identifiers, where `""` is an escaped double quote;
+ *   - `-- ...` line comments and nestable slash-star block comments;
+ *
+ * `\` is treated as an escape inside `E'...'` / `U&'...'` only, matching
+ * PostgreSQL's default `standard_conforming_strings = on`. If that GUC is ever
+ * turned off on a pooled connection the plain-string rule below would differ
+ * from the server's; pinning it at acquire time (Group 1 owns `pool.ts`) closes
+ * that, and `src/execution/sql-parser.ts` (Group 2) is the authoritative check.
+ *
+ * Unterminated literals, dollar quotes, identifiers and block comments throw
+ * rather than guessing: a construct this scan cannot account for is one it
+ * cannot rule a hidden `;` out of.
+ */
+export declare function countSqlStatements(sql: string, field?: string): number;
+/**
+ * Reject anything that is not exactly one statement. A single trailing `;`
+ * terminator is allowed (`SELECT 1;` is one statement); a second statement is
+ * not, whatever separates them.
+ */
+export declare function assertSingleStatement(sql: string, field?: string): void;
+export declare function validateQueryPayload(p: unknown): void;
+export declare function validateStreamQueryPayload(p: unknown): void;
+export declare function validateStreamChunkPayload(p: unknown): void;
+export declare function validateStreamEndPayload(p: unknown): void;
+export declare function validateMigrationRunPayload(p: unknown): void;
+export declare function validateMigrationResultPayload(p: unknown): void;
+export declare function validateCancelPayload(p: unknown): void;
+export declare function validateCancelResultPayload(p: unknown): void;
+export declare function validateResponsePayload(p: unknown): void;
+export declare function validateErrorPayload(p: unknown): void;
+export declare function validateEventPayload(p: unknown): void;
+//# sourceMappingURL=validate.d.ts.map

package/dist/esm/protocol/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/protocol/validate.ts"],"names":[],"mappings":"AACA,OAAO,EACL,YAAY,EAIZ,WAAW,EAEX,IAAI,EAIL,MAAM,YAAY,CAAC;AAWpB;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,IAAI,YAAY,CAyD1E;AAMD,MAAM,WAAW,2BAA2B;IAC1C;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,YAAY,EAAE,SAAS,IAAI,EAAE,CAAC;IAC9B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,gGAAgG;IAChG,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;;OAQG;IACH,iBAAiB,CAAC,EAAE,IAAI,CAAC;IACzB,0EAA0E;IAC1E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAWnB;IACF,2EAA2E;IAC3E,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;gBAE5C,OAAO,EAAE,2BAA2B;IAgBhD,oCAAoC;IACpC,eAAe,IAAI,IAAI,EAAE;IAIzB;;;;OAIG;IACH,oBAAoB,IAAI,IAAI;IAI5B,2DAA2D;IAC3D,eAAe,IAAI,MAAM;IAIzB,yEAAyE;IACzE,KAAK,IAAI,IAAI;IAIb;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI;CA+DhC;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CA0CzE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,IAAI,YAAY,CAGzE;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAQpD;AAED,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAW1D;AASD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,SAAQ,GAAG,MAAM,CAyGrE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,SAAQ,GAAG,IAAI,CAQtE;AAoED,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAyBrD;AAED,wBAAgB,0BAA0B,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CA0B3D;AAED,wBAAgB,0BAA0B,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAsC3D;AAED,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAczD;AAED,wBAAgB,2BAA2B,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAyB5D;AAED,wBAAgB,8BAA8B,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAmD/D;AAED,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAStD;AAED,wBAAgB,2BAA2B,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAc5D;AAED,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAcxD;AAED,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAsCrD;AAiBD,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CA8HrD"}