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

package/dist/esm/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/esm/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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"}