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

package/dist/types/audit/verify-cache.d.ts

@@ -0,0 +1,127 @@
+import { type ChainVerifyResult } from './chain';
+import type { AuditHead } from './types';
+/**
+ * Stat identity of one log file.
+ *
+ * The timestamps are decimal nanoseconds (`bigint` stat) rather than millisecond
+ * floats: a float cannot hold `1.7e18` ns without rounding, and the rounding
+ * window is exactly where a "same second, same size" tamper would hide.
+ */
+export interface AuditFileIdentity {
+    size: number;
+    mtime_ns: string;
+    ctime_ns: string;
+    ino: string;
+    dev: string;
+}
+/** Reads a file's identity, or null when it cannot be stat'ed. */
+export declare function statAuditFileIdentity(file: string): Promise<AuditFileIdentity | null>;
+/** What a completed verification of one file leaves behind. */
+export interface CachedAuditFile {
+    /** The file's stat identity at verification time. */
+    identity: AuditFileIdentity;
+    /** Records in the file, and how many of them were not parseable. */
+    records: number;
+    malformed_lines: number;
+    /** Sequence number the file's *first* record must carry. */
+    first_seq: number;
+    /** Hash the file's *first* record must chain from (genesis when it starts at 1). */
+    first_prev_hash: string;
+    /** Chain head after the last record of the file. */
+    seq: number;
+    last_hash: string;
+    chain_id: string;
+    /** Fingerprint of the signing key the entry was verified with. */
+    key_fingerprint: string;
+    verified_at: string;
+}
+/**
+ * The chain state an entry may be reused for. An entry is only ever equivalent
+ * to having read the file when it was verified from exactly this state.
+ */
+export interface CacheResumption {
+    /** Chain the caller requires, or null when it is not constrained yet. */
+    chainId: string | null;
+    /** Sequence number the file's first record must carry. */
+    seq: number;
+    /** Hash the file's first record must chain from. */
+    prevHash: string;
+    /** Fingerprint of the signing key in use now. */
+    keyFingerprint: string;
+}
+export declare class AuditVerifyCache {
+    private readonly entries;
+    /**
+     * A usable entry for this exact file revision and this exact resumption point,
+     * or null. Every field is load-bearing: see the trust model at the top of this
+     * module.
+     */
+    get(file: string, identity: AuditFileIdentity, expect: CacheResumption): CachedAuditFile | null;
+    set(file: string, entry: CachedAuditFile): void;
+    /**
+     * Copy of the stored entries. Read-only: nothing can be invalidated through
+     * it, so a caller reporting on the cache cannot weaken it by accident.
+     */
+    snapshot(): ReadonlyMap<string, CachedAuditFile>;
+    /** Drops entries for files that no longer exist (rotated out of retention). */
+    prune(liveFiles: Iterable<string>): void;
+    clear(): void;
+    get size(): number;
+}
+/**
+ * The process-wide cache. Exposed so a caller that verifies the same directory
+ * repeatedly (an interactive shell running `doctor` over and over) shares one
+ * set of entries, and so a test can observe that production code used it.
+ */
+export declare function getSharedAuditVerifyCache(): AuditVerifyCache;
+export interface CachedVerifyOptions {
+    /** Signing key. Defaults to `SW_AGENT_AUDIT_KEY` / `audit.key`. */
+    key?: Buffer | string;
+    /** Directory holding `audit.key`. Defaults to `dir`, then the agent home. */
+    keyDir?: string;
+    /** Expected head. Defaults to `head.json` in `dir`; pass `null` to skip. */
+    head?: AuditHead | null;
+    /** Stop after this many records read in this run. */
+    maxRecords?: number;
+    /** First sequence number the log must carry. Defaults to the anchored floor. */
+    expectedSeq?: number;
+    /** Cache to use. Defaults to the process-wide cache. */
+    cache?: AuditVerifyCache;
+    /** Set false to ignore and not populate the cache. Default true. */
+    useCache?: boolean;
+}
+export interface CachedVerifyResult extends ChainVerifyResult {
+    files: string[];
+    malformed_lines: number;
+    unreadable_files: string[];
+    head_present: boolean;
+    chain_id: string | null;
+    coverage?: {
+        from_seq: number;
+        to_seq: number;
+        records: number;
+    };
+    /** Every anchor that was consulted, in the order given. */
+    anchor_sources?: string[];
+    /** Which of them decided the verdict. */
+    anchor_source?: string | null;
+    /** Files skipped because they match a previous successful verification. */
+    cached_files: string[];
+    /** Files actually read in this run. */
+    verified_files: string[];
+    skipped_bytes: number;
+    verified_bytes: number;
+    /** True when nothing had to be read at all. */
+    cache_hit: boolean;
+    /** Newest verified-at stamp among the entries this run reused. */
+    cached_since?: string;
+}
+/**
+ * Verifies the log chronologically across rotated files, reusing verified files
+ * that have not changed. Fails closed: no key, no verdict.
+ *
+ * The verdict is identical to {@link verifyAuditLog}'s for any input the cache
+ * did not serve; `verify-streaming.test.ts` pins both against the same logs.
+ */
+export declare function verifyAuditDirCached(dir: string, opts?: CachedVerifyOptions): Promise<CachedVerifyResult>;
+//# sourceMappingURL=verify-cache.d.ts.map

package/dist/types/audit/verify-cache.d.ts.map

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

package/dist/types/channels/agent-session.d.ts

@@ -0,0 +1,228 @@
+import { WakeChannelOptions } from './wake-channel';
+import { AgentMessage, Role } from '../protocol/envelope';
+import { InboundEnvelopeGuard } from '../protocol/validate';
+import type { AuditSink } from '../audit/sink';
+import { AgentSessionState, DataChannelCloseReason, EnvelopeAuthPolicy, MessageHandler, WakeEvent, StateChangeHandler } from './types';
+import { MachineConfig } from '../config/machine-config';
+export interface AgentSessionOptions {
+    /** Machine config (loaded by caller). */
+    machineConfig: MachineConfig;
+    /** Optional: returns configured database list from databases.config.json. */
+    getDatabases?: () => Array<{
+        db_alias: string;
+        database: string;
+    }>;
+    /** Message handler. Called for every incoming message on the data channel. */
+    onMessage: MessageHandler;
+    /** State change handler. Called whenever AgentSessionState changes. */
+    onStateChange?: StateChangeHandler;
+    /** Optional: custom wake channel options (for tests). */
+    wakeChannelOverrides?: Partial<WakeChannelOptions>;
+    /** Optional: abort signal. */
+    abortSignal?: AbortSignal;
+    /**
+     * Per-session envelope authentication policy. Omit to take every default from
+     * src/protocol/constants.ts (a MAC is required; the relay may negotiate up to
+     * `admin`).
+     */
+    envelopeAuth?: EnvelopeAuthPolicy;
+    /** Audit sink for session lifecycle events. */
+    auditSink?: AuditSink;
+    /**
+     * Explicit authorisation to tear down a HEALTHY data channel because a wake
+     * event named a different `browser_session_id` (audit M-15).
+     *
+     * Omit it and the session is never replaced while healthy. When present, the
+     * caller decides — that is the point: session replacement must be a
+     * deliberate, policy-bearing decision, not an accident of message ordering. It
+     * must itself verify that the incoming session is authorised (for example by
+     * checking a token the cloud scoped to the new session); the agent cannot
+     * establish that on its own.
+     */
+    authoriseSessionReplacement?: (event: WakeEvent, current: WakeEvent | undefined) => boolean;
+    /**
+     * Called when requests are being failed because the channel is being torn
+     * down, so the execution layer can cancel the backends. Receive the request
+     * ids and the close reason.
+     */
+    onInFlightDrained?: (requestIds: string[], reason: DataChannelCloseReason) => void | Promise<void>;
+    /** Clock injection point for the churn budget. Defaults to `Date.now`. */
+    now?: () => number;
+    /** Session churn budget override. Every field defaults to DEFAULTS. */
+    sessionChangeBudget?: {
+        /** Minimum spacing between admitted replacements. */
+        cooldownMs?: number;
+        /** Window the count applies over. */
+        windowMs?: number;
+        /** Max admitted replacements per window. */
+        maxPerWindow?: number;
+    };
+}
+/** What a wake event was permitted to do to the active data channel. */
+export type SessionAdmission = {
+    action: 'adopt';
+    reason: string;
+    churn?: never;
+} | {
+    action: 'noop';
+    reason: string;
+    churn?: never;
+} | {
+    action: 'replace';
+    reason: string;
+    churn: ChurnVerdict;
+} | {
+    action: 'reject';
+    reason: string;
+    churn: ChurnVerdict;
+};
+export interface ChurnVerdict {
+    allowed: boolean;
+    reason: string;
+    replacements: number;
+}
+export declare class AgentSession {
+    private wakeChannel?;
+    private dataChannel?;
+    private state;
+    private readonly opts;
+    private inFlightRequests;
+    private currentWakeEvent?;
+    private inboundGuard?;
+    private activeMessageHandler;
+    private activeStateChangeHandler?;
+    /** Explicit authoriser for tearing down a healthy session. Absent = deny. */
+    private readonly authoriseReplacement?;
+    private readonly now;
+    private readonly sessionPolicy;
+    /**
+     * Timestamps of session-change attempts inside the current window, oldest
+     * first. Bounded: entries are trimmed by age and the array is hard-capped at
+     * `maxPerWindow * 4`, so a churn flood cannot grow it without limit.
+     */
+    private readonly sessionChanges;
+    constructor(opts: AgentSessionOptions);
+    /** Start the agent. Boots wake channel. Returns when fully started. */
+    start(): Promise<void>;
+    /** Graceful shutdown. Closes data channel, then wake channel. */
+    stop(): Promise<void>;
+    /**
+     * Send a message out via the data channel.
+     * If data channel is closed, opens it first (using current wake event's token).
+     * Throws if no wake event has been received yet (i.e., no token to open data channel).
+     */
+    send(msg: AgentMessage): Promise<void>;
+    /** Register a message handler (overrides the one from opts). */
+    setMessageHandler(handler: MessageHandler): void;
+    /**
+     * Resolve once this session's data channel has caught up: the send buffer is at
+     * or below its high-water mark and nothing earlier is still in flight.
+     *
+     * This is the transport signal a cursor fetch loop waits on (audit H-10), so
+     * the producer stops asking PostgreSQL for rows while the relay is behind.
+     * Hand it to the dispatcher as its `waitForDrain` option.
+     *
+     * Resolves immediately when there is no data channel — before the first wake
+     * event, or after the channel was torn down. A socket that will never drain
+     * again must not strand a producer, and the caller still observes the missing
+     * channel on its next {@link send}.
+     */
+    waitForDrain(): Promise<void>;
+    /** Register a state change handler (overrides the one from opts). */
+    onStateChange(handler: StateChangeHandler): void;
+    /** Current state. */
+    getState(): AgentSessionState;
+    /**
+     * The envelope authenticator for the open data channel, or undefined before
+     * the first wake event. Exposed so diagnostics and tests can inspect the
+     * negotiated role set and replay-cache occupancy.
+     */
+    getInboundGuard(): InboundEnvelopeGuard | undefined;
+    /**
+     * Roles permitted for the current session. Empty until a wake event arrives,
+     * and empty — meaning nothing is permitted — if the relay negotiated none.
+     */
+    getNegotiatedRoles(): Role[];
+    /**
+     * Build the per-session inbound authenticator: derive the MAC key from the
+     * data-channel token, intersect the roles the relay asked for with the local
+     * ceiling, and start with an empty replay cache.
+     */
+    private buildInboundGuard;
+    /**
+     * Authenticate one inbound envelope, then hand it on. A rejected envelope
+     * never reaches `onMessage` — and therefore never reaches the dispatcher — and
+     * the data channel is torn down rather than left open to a peer that is
+     * forging authorization claims.
+     */
+    private handleInboundMessage;
+    /** Tear down the current authenticator so no envelope can be admitted. */
+    private clearInboundGuard;
+    /**
+     * Track an in-flight request (for reconnect/resume).
+     * Called by execution engine before sending a request.
+     * Cleared when response is received.
+     */
+    trackInFlight(requestId: string, msg: AgentMessage): void;
+    untrackInFlight(requestId: string): void;
+    getInFlight(): Map<string, AgentMessage>;
+    private handleWakeEvent;
+    /**
+     * Decide what a wake event is allowed to do to the active data channel.
+     *
+     * Audit M-15. The previous implementation closed the live channel and opened a
+     * new one for ANY wake event carrying a different `browser_session_id`, which
+     * made session takeover and forced disconnection a single message, and
+     * orphaned every in-flight query on the old channel. The policy is now:
+     *
+     *   1. Same session while healthy → no-op (a duplicate wake for work already
+     *      being served).
+     *   2. A different `browser_session_id` while the current channel is HEALTHY
+     *      (open or connecting) → REPLACED only when the caller supplied an explicit
+     *      authoriser, otherwise REJECTED. Deny by default.
+     *   3. A different session while the current channel is DEAD (closed or error)
+     *      → replaced, because there is nothing to take over and refusing would
+     *      strand the agent.
+     *   4. No channel at all (first wake) → adopted.
+     *
+     * Session churn is additionally rate limited, so the 3 case cannot be turned
+     * into a cheaper denial of service than tearing the channel down once.
+     */
+    private evaluateWakeEvent;
+    /**
+     * Bounded session-churn budget (audit M-15): at most
+     * DEFAULTS.SESSION_CHANGE_MAX_PER_WINDOW session changes inside any
+     * DEFAULTS.SESSION_CHANGE_WINDOW_MS window, and never two closer together than
+     * DEFAULTS.SESSION_CHANGE_COOLDOWN_MS. Deny by default when the budget is out.
+     */
+    private checkChurnBudget;
+    /**
+     * Every session replacement is a security event: the active channel is being
+     * torn down by a party that merely asserted a different session id. Recorded
+     * as a `system` actor (no principal is authenticated for this) through the
+     * same sink the dispatcher uses.
+     */
+    private auditSessionAdmission;
+    /**
+     * Fail in-flight work explicitly when the channel is being torn down.
+     *
+     * The old behaviour silently dropped the tracking map, so those queries ran to
+     * completion against a channel that could no longer carry their responses. They
+     * are now cancelled at the backend (best effort) and removed from tracking, and
+     * `onInFlightDrained` lets the caller observe exactly what was lost.
+     */
+    private drainInFlight;
+    private processWakeEvent;
+    private updateState;
+}
+/**
+ * Roles the connector will accept for this session: the roles the relay
+ * negotiated, minus anything above the local ceiling, minus anything that is not
+ * a legal role. Returned in the canonical `ROLES` order.
+ *
+ * An absent, empty, or wholly invalid `allowed_roles` yields an empty set, which
+ * the guard treats as "no role is permitted" — there is no fallback to "all
+ * roles", because that fallback is the C-04 vulnerability.
+ */
+export declare function intersectNegotiatedRoles(negotiated: readonly unknown[] | undefined, ceiling?: Role): Role[];
+//# sourceMappingURL=agent-session.d.ts.map

package/dist/types/channels/agent-session.d.ts.map

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

package/dist/types/channels/data-channel.d.ts

@@ -0,0 +1,181 @@
+import { AgentMessage } from '../protocol/envelope';
+import { DataChannelState, DataChannelCloseReason, MessageHandler } from './types';
+/**
+ * Inbound frame ceiling enforced by the transport, in bytes.
+ *
+ * `ws` checks this against the *decompressed* message length as well as the
+ * frame length, so a compressed payload cannot inflate past it.
+ */
+export declare const MAX_INBOUND_FRAME_BYTES: 16777216;
+/** RFC 6455 close code for a message that exceeded the negotiated limit. */
+export declare const CLOSE_MESSAGE_TOO_BIG = 1009;
+/**
+ * Safety margin applied to `data_channel_token_expires_at` before connecting.
+ *
+ * The token is spent on a TLS handshake plus a round trip; refusing slightly
+ * early is cheaper than a data channel that 401s mid-session.
+ */
+export declare const TOKEN_EXPIRY_SAFETY_MARGIN_MS = 5000;
+/**
+ * Watermark above which the socket is considered back-pressured, in bytes.
+ *
+ * At or below this the relay is keeping up and the producer may keep sending.
+ * Above it the producer waits instead of pushing more bytes into a buffer that
+ * is already draining slower than it is fed.
+ */
+export declare const SEND_BUFFER_HIGH_WATER_MARK_BYTES: number;
+/**
+ * Hard ceiling on unsent bytes, in bytes.
+ *
+ * Above the watermark a send is deferred, never rejected — but a producer that
+ * never gets a drain signal (a relay that has stopped reading) must not be able
+ * to grow the daemon's heap without limit. Past this the send fails closed with
+ * a `payload_invalid` ProtocolError, which the caller's error path reports
+ * terminally instead of silently truncating a stream.
+ */
+export declare const SEND_BUFFER_HARD_CAP_BYTES: 16777216;
+/** Current send-buffer occupancy. Diagnostics only. */
+export interface DataChannelSendStats {
+    /** Bytes the socket has accepted but not yet written. */
+    buffered: number;
+    /** Bytes handed to `ws.send` whose callback has not fired yet. */
+    pending: number;
+    /** Watermark at or below which the producer is unblocked. */
+    high_water_mark: number;
+    /** Ceiling past which a send is refused. */
+    hard_cap: number;
+}
+export interface DataChannelOptions {
+    /** Cloud URL, e.g. "wss://api.schemaweaver.dev". Plaintext schemes are refused. */
+    cloudUrl: string;
+    /** Short-lived data channel token from wake event. */
+    dataChannelToken: string;
+    /**
+     * Epoch ms at which `dataChannelToken` expires (from the wake event).
+     *
+     * Required: the client is the only party that can check it before the
+     * handshake, so an absent value is treated as a malformed credential.
+     */
+    dataChannelTokenExpiresAt: number;
+    /** Agent ID for routing. */
+    agentId: string;
+    /** Browser session ID this channel serves. */
+    browserSessionId: string;
+    /** Incoming message handler. */
+    onMessage: MessageHandler;
+    /** Called when channel state changes. */
+    onStateChange?: (state: DataChannelState, reason?: DataChannelCloseReason, error?: string) => void;
+    /** Idle timeout in ms. Default 60_000. Set to 0 to disable. */
+    idleTimeoutMs?: number;
+    /** Optional: abort signal. */
+    abortSignal?: AbortSignal;
+    /**
+     * Allow a cleartext `ws:`/`http:` target. Only wire this to an explicit,
+     * non-persisted operator flag (`--insecure-transport`).
+     */
+    allowInsecureTransport?: boolean;
+}
+export declare class DataChannel {
+    private state;
+    private ws?;
+    private idleTimer?;
+    private closeReason?;
+    private transportError?;
+    private readonly opts;
+    /** Bytes handed to `ws.send` whose completion callback has not fired yet. */
+    private pendingSendBytes;
+    /** Producers blocked in {@link DataChannel.waitForDrain}. */
+    private readonly drainWaiters;
+    private drainPollTimer?;
+    /**
+     * Safety net for a close that the peer never answers. Held so it can be
+     * cancelled the moment the close settles: a timer left armed here outlives
+     * the close it belongs to and would tear down the *next* connection opened on
+     * this instance (token rotation reconnects on the same object), and it also
+     * holds the process open for its whole backoff window.
+     */
+    private closeSafetyTimer?;
+    constructor(opts: DataChannelOptions);
+    /** Open the WSS connection. Resolves when handshake completes. */
+    connect(): Promise<void>;
+    /**
+     * Refuse to authenticate with an unusable data channel token (audit H-12).
+     *
+     * Runs before the handshake so an expired token is never presented, and
+     * reports through onStateChange so the operator sees why the channel refused.
+     */
+    private assertTokenUsable;
+    /**
+     * Send a message, applying backpressure instead of rejecting a busy socket.
+     *
+     * Above {@link SEND_BUFFER_HIGH_WATER_MARK_BYTES} the send waits for the
+     * socket to drain. It used to throw `payload_invalid` here, which aborted the
+     * producer mid-stream and left the browser waiting for a `stream_end` that
+     * never came (audit H-10). A slow relay is a condition to wait out, not an
+     * error. Past {@link SEND_BUFFER_HARD_CAP_BYTES} the wait has demonstrably not
+     * been satisfied and the send fails closed so unbounded growth stays impossible.
+     *
+     * Concurrent callers are serialised through the gate: the drain condition is
+     * re-tested after every wait, and the check and the hand-off to `ws.send` sit
+     * in one synchronous step. Without that, N producers resuming from the same
+     * microtask batch would all observe an empty buffer and push N messages into
+     * the socket anyway — the gate would throttle nothing.
+     *
+     * Throws `channel_closed` if the channel is not open, or if it closes while
+     * this call is waiting to drain.
+     */
+    send(msg: AgentMessage): Promise<void>;
+    /**
+     * Resolve once the socket has caught up: `bufferedAmount` is at or below
+     * {@link SEND_BUFFER_HIGH_WATER_MARK_BYTES} and no earlier send is still in
+     * flight. Returns immediately when that is already true, and also when the
+     * channel is not open — a socket that will never drain again must not strand a
+     * producer, and the caller still observes the closed channel on its next send.
+     *
+     * This is the hook to hand to a cursor fetch loop so the producer stops asking
+     * PostgreSQL for more rows while the relay is behind:
+     *
+     * ```ts
+     * await queryRunner.runStreaming(payload, { waitForDrain: () => channel.waitForDrain(), ... });
+     * ```
+     *
+     * Every waiter is released when the channel leaves `open`, so a stalled relay
+     * is bounded by the idle timeout rather than by this promise.
+     */
+    waitForDrain(): Promise<void>;
+    /** Current send-buffer occupancy against the watermark and hard cap. */
+    getSendBufferStats(): DataChannelSendStats;
+    private bufferedBytes;
+    /**
+     * True while the socket is behind. `pendingSendBytes` is included because a
+     * `ws.send` callback has not yet fired for it, so the bytes are still in
+     * flight and the producer should not run ahead of them.
+     */
+    private drainPending;
+    /** True when queueing `incomingBytes` more would reach the cap `send` refuses at. */
+    private sendBufferExceeded;
+    /**
+     * Release every blocked producer, then stop polling. A single shared interval
+     * serves all waiters so N blocked producers cost one timer, not N.
+     */
+    private notifyDrainWaiters;
+    private startDrainPoll;
+    private stopDrainPoll;
+    /**
+     * Release every blocked producer unconditionally: the channel is leaving
+     * `open`, so no amount of draining can satisfy them.
+     */
+    private releaseDrainWaiters;
+    /** Graceful close. */
+    close(reason?: DataChannelCloseReason): Promise<void>;
+    /** Cancel the pending close safety net, if any. */
+    private cancelCloseSafety;
+    /** Force close (e.g. on fatal error). */
+    forceClose(reason: DataChannelCloseReason, error?: string): void;
+    /** Current state. */
+    getState(): DataChannelState;
+    /** Reset idle timer (called when activity occurs). */
+    private pingActivity;
+    private setState;
+}
+//# sourceMappingURL=data-channel.d.ts.map

package/dist/types/channels/data-channel.d.ts.map

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