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

package/dist/cjs/channels/reconnect.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Exponential backoff calculator.
+ * Sequence: 1s, 2s, 4s, 8s, 16s, 32s, 60s, 60s, 60s, ...
+ */
+export declare class Backoff {
+    /** Custom backoff schedule (defaults to DEFAULTS.RECONNECT_BACKOFF_MS). */
+    private readonly schedule;
+    private attempt;
+    private readonly max;
+    constructor(
+    /** Custom backoff schedule (defaults to DEFAULTS.RECONNECT_BACKOFF_MS). */
+    schedule?: readonly number[], 
+    /** Maximum delay cap (defaults to last value in schedule). */
+    maxMs?: number);
+    /** Returns the next delay in ms (does NOT sleep). */
+    next(): number;
+    /** Current attempt number (0 before first next() call). */
+    get attempts(): number;
+    /** Reset to attempt 0 (call after successful connect). */
+    reset(): void;
+    /** Sleep for the next backoff delay. Returns the ms slept. */
+    sleepNext(): Promise<number>;
+}
+/** Promise-based sleep. */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Compute jittered backoff (±20% of base delay) to prevent thundering herd.
+ * Optional — use only if you want to add jitter on top of Backoff.
+ */
+export declare function withJitter(delayMs: number, jitterPct?: number): number;
+/** URL schemes that mean "TLS-protected". Nothing else may carry the token. */
+export declare const SECURE_TRANSPORT_SCHEMES: readonly string[];
+/**
+ * Operator-facing remediation for a rejected or expired agent token.
+ *
+ * Wording is kept in step with `sw-agent agent rotate-token`: a running agent
+ * keeps the credential it was started with, so the restart is part of the fix,
+ * not an optional extra.
+ */
+export declare const TOKEN_ROTATION_HINT: string;
+/**
+ * Remediation for a cleartext transport target.
+ *
+ * Names the sanctioned lab escape hatch (`--insecure-transport`, audit H-03) with
+ * its costs attached. The config validators reject plaintext URLs outright, so
+ * the flag is the only route to a cleartext socket — withholding it would leave
+ * the operator with a refusal they cannot act on and a plaintext mode they cannot
+ * discover. The secure remedy still comes first and the flag is stated as a last
+ * resort that keeps the token in cleartext for the whole session.
+ */
+export declare const INSECURE_TRANSPORT_HINT: string;
+/** Marker so operators can grep logs for this condition. */
+export declare const INSECURE_TRANSPORT_MARKER = "[INSECURE TRANSPORT]";
+export type TransportSecurityErrorCode = 'insecure_transport' | 'invalid_url';
+/**
+ * Thrown when an outbound target is not a TLS-protected `wss:`/`https:` URL.
+ *
+ * Every outbound connection path throws this instead of downgrading the
+ * protocol, so the agent token can never be written to a cleartext socket.
+ */
+export declare class TransportSecurityError extends Error {
+    code: TransportSecurityErrorCode;
+    /** The offending target, as supplied by config. */
+    url: string;
+    /** The offending scheme, or '' when the URL could not be parsed. */
+    scheme: string;
+    /** Short description of the connection attempt, e.g. "wake channel". */
+    context: string;
+    constructor(code: TransportSecurityErrorCode, message: string, 
+    /** The offending target, as supplied by config. */
+    url: string, 
+    /** The offending scheme, or '' when the URL could not be parsed. */
+    scheme: string, 
+    /** Short description of the connection attempt, e.g. "wake channel". */
+    context?: string);
+}
+export interface TransportGuardOptions {
+    /**
+     * Opt-in plaintext allowance, for an explicit operator decision only. The CLI
+     * rejects plaintext URLs outright, so nothing in the shipped product sets
+     * this; it exists so a downstream embedder that has made its own decision
+     * cannot do so silently. When set, a loud warning is logged on every call.
+     */
+    allowInsecure?: boolean;
+    /** Short description of the connection attempt, used in error messages. */
+    context?: string;
+}
+/**
+ * True when the target is a TLS-protected `wss:`/`https:` URL. Unparseable
+ * input returns false — callers must fail closed.
+ */
+export declare function isSecureTransportUrl(url: string | URL): boolean;
+/**
+ * Assert that `url` is a `wss:`/`https:` target and return it parsed.
+ *
+ * This is the single enforcement point for audit H-03: every outbound
+ * connection path calls it (directly or via {@link toWebSocketUrl} /
+ * {@link toHttpUrl}) before an `Authorization: Bearer <agent token>` header is
+ * attached. Non-TLS schemes throw instead of being downgraded. Only an
+ * explicit, non-persisted `allowInsecure` opt-in permits plaintext, and it
+ * warns loudly on every call.
+ */
+export declare function assertSecureTransport(url: string | URL, opts?: TransportGuardOptions): URL;
+/**
+ * Build a `wss:` target from a configured cloud URL.
+ *
+ * `https:` maps to `wss:` (same TLS transport, different protocol) and `wss:`
+ * is used as-is. `ws:`/`http:` throw unless the caller passed `allowInsecure`.
+ */
+export declare function toWebSocketUrl(base: string | URL, opts?: TransportGuardOptions): URL;
+/**
+ * Build an `https:` target from a configured cloud URL.
+ *
+ * `wss:` maps to `https:` (same TLS transport, SSE/plain HTTP) and `https:` is
+ * used as-is. `ws:`/`http:` throw unless the caller passed `allowInsecure`.
+ */
+export declare function toHttpUrl(base: string | URL, opts?: TransportGuardOptions): URL;
+/**
+ * Backoff schedule for consecutive authentication failures. Kept separate from
+ * DEFAULTS.RECONNECT_BACKOFF_MS because a rejected credential is a different
+ * class of failure: it is slow to start and slow to give up on.
+ */
+export declare const AUTH_FAILURE_BACKOFF_MS: readonly number[];
+/**
+ * Consecutive 401/403 responses tolerated before the wake loop stops retrying.
+ *
+ * Policy: a credential the server evaluated and rejected cannot become valid by
+ * retrying, so retries are bounded rather than infinite. The bound exists only
+ * to absorb the two realistic transient cases — clock skew and a token the
+ * cloud rotated but has not yet replicated — after which the loop stops instead
+ * of hammering the auth endpoint from every connected agent.
+ */
+export declare const MAX_AUTH_FAILURE_ATTEMPTS = 5;
+/**
+ * Operator-facing message for a credential the cloud rejected.
+ */
+export declare function formatTokenRejectedMessage(status?: number, attempts?: number, maxAttempts?: number): string;
+/**
+ * Operator-facing message for a credential the client itself found expired.
+ */
+export declare function formatTokenExpiredMessage(expiresAt: number, marginMs: number, context: string): string;
+//# sourceMappingURL=reconnect.d.ts.map

package/dist/cjs/channels/reconnect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconnect.d.ts","sourceRoot":"","sources":["../../../src/channels/reconnect.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,qBAAa,OAAO;IAKhB,2EAA2E;IAC3E,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAL3B,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;;IAG3B,2EAA2E;IAC1D,QAAQ,GAAE,SAAS,MAAM,EAAkC;IAC5E,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM;IAKhB,qDAAqD;IACrD,IAAI,IAAI,MAAM;IAOd,2DAA2D;IAC3D,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,0DAA0D;IAC1D,KAAK,IAAI,IAAI;IAIb,8DAA8D;IACxD,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC;CAKnC;AAED,2BAA2B;AAC3B,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,GAAE,MAAY,GAAG,MAAM,CAG3E;AAMD,+EAA+E;AAC/E,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EAAsC,CAAC;AAE7F;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,QAEE,CAAC;AAEnC;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,QAKoC,CAAC;AAEzE,4DAA4D;AAC5D,eAAO,MAAM,yBAAyB,yBAAyB,CAAC;AAEhE,MAAM,MAAM,0BAA0B,GAAG,oBAAoB,GAAG,aAAa,CAAC;AAE9E;;;;;GAKG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAEtC,IAAI,EAAE,0BAA0B;IAEvC,mDAAmD;IAC5C,GAAG,EAAE,MAAM;IAClB,oEAAoE;IAC7D,MAAM,EAAE,MAAM;IACrB,wEAAwE;IACjE,OAAO,EAAE,MAAM;gBAPf,IAAI,EAAE,0BAA0B,EACvC,OAAO,EAAE,MAAM;IACf,mDAAmD;IAC5C,GAAG,EAAE,MAAM;IAClB,oEAAoE;IAC7D,MAAM,EAAE,MAAM;IACrB,wEAAwE;IACjE,OAAO,GAAE,MAA8B;CAKjD;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAqBD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,CAQ/D;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,IAAI,GAAE,qBAA0B,GAAG,GAAG,CAiB9F;AAaD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,EAAE,IAAI,GAAE,qBAA0B,GAAG,GAAG,CAQxF;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,EAAE,IAAI,GAAE,qBAA0B,GAAG,GAAG,CAUnF;AAMD;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,MAAM,EAEnD,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAE3C;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,CAAC,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,EACjB,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,CAWR;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,MAAM,CAMR"}

package/dist/cjs/channels/reconnect.js

@@ -0,0 +1,247 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_AUTH_FAILURE_ATTEMPTS = exports.AUTH_FAILURE_BACKOFF_MS = exports.TransportSecurityError = exports.INSECURE_TRANSPORT_MARKER = exports.INSECURE_TRANSPORT_HINT = exports.TOKEN_ROTATION_HINT = exports.SECURE_TRANSPORT_SCHEMES = exports.Backoff = void 0;
+exports.sleep = sleep;
+exports.withJitter = withJitter;
+exports.isSecureTransportUrl = isSecureTransportUrl;
+exports.assertSecureTransport = assertSecureTransport;
+exports.toWebSocketUrl = toWebSocketUrl;
+exports.toHttpUrl = toHttpUrl;
+exports.formatTokenRejectedMessage = formatTokenRejectedMessage;
+exports.formatTokenExpiredMessage = formatTokenExpiredMessage;
+const constants_1 = require("../protocol/constants");
+/**
+ * Exponential backoff calculator.
+ * Sequence: 1s, 2s, 4s, 8s, 16s, 32s, 60s, 60s, 60s, ...
+ */
+class Backoff {
+    schedule;
+    attempt = 0;
+    max;
+    constructor(
+    /** Custom backoff schedule (defaults to DEFAULTS.RECONNECT_BACKOFF_MS). */
+    schedule = constants_1.DEFAULTS.RECONNECT_BACKOFF_MS, 
+    /** Maximum delay cap (defaults to last value in schedule). */
+    maxMs) {
+        this.schedule = schedule;
+        this.max = maxMs ?? schedule[schedule.length - 1];
+    }
+    /** Returns the next delay in ms (does NOT sleep). */
+    next() {
+        const idx = Math.min(this.attempt, this.schedule.length - 1);
+        const delay = this.schedule[idx];
+        this.attempt++;
+        return Math.min(delay, this.max);
+    }
+    /** Current attempt number (0 before first next() call). */
+    get attempts() {
+        return this.attempt;
+    }
+    /** Reset to attempt 0 (call after successful connect). */
+    reset() {
+        this.attempt = 0;
+    }
+    /** Sleep for the next backoff delay. Returns the ms slept. */
+    async sleepNext() {
+        const delay = this.next();
+        await sleep(delay);
+        return delay;
+    }
+}
+exports.Backoff = Backoff;
+/** Promise-based sleep. */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Compute jittered backoff (±20% of base delay) to prevent thundering herd.
+ * Optional — use only if you want to add jitter on top of Backoff.
+ */
+function withJitter(delayMs, jitterPct = 0.2) {
+    const jitter = delayMs * jitterPct;
+    return Math.round(delayMs - jitter + Math.random() * 2 * jitter);
+}
+/* -------------------------------------------------------------------------- */
+/* Transport security guard (audit H-03)                                       */
+/* -------------------------------------------------------------------------- */
+/** URL schemes that mean "TLS-protected". Nothing else may carry the token. */
+exports.SECURE_TRANSPORT_SCHEMES = Object.freeze(['wss:', 'https:']);
+/**
+ * Operator-facing remediation for a rejected or expired agent token.
+ *
+ * Wording is kept in step with `sw-agent agent rotate-token`: a running agent
+ * keeps the credential it was started with, so the restart is part of the fix,
+ * not an optional extra.
+ */
+exports.TOKEN_ROTATION_HINT = 'Run `sw-agent agent rotate-token` to mint a new agent token, then `sw-agent agent restart` so ' +
+    'the running agent picks it up.';
+/**
+ * Remediation for a cleartext transport target.
+ *
+ * Names the sanctioned lab escape hatch (`--insecure-transport`, audit H-03) with
+ * its costs attached. The config validators reject plaintext URLs outright, so
+ * the flag is the only route to a cleartext socket — withholding it would leave
+ * the operator with a refusal they cannot act on and a plaintext mode they cannot
+ * discover. The secure remedy still comes first and the flag is stated as a last
+ * resort that keeps the token in cleartext for the whole session.
+ */
+exports.INSECURE_TRANSPORT_HINT = 'Set `cloud_url` (and `cloud_telemetry.ingest_url`, if set) to a wss:// or https:// URL: plaintext ' +
+    'targets are refused because the agent token would be readable in transit. For local lab use, put ' +
+    'a TLS terminator in front of the relay; if that is genuinely impossible, start the agent with ' +
+    '--insecure-transport, which is never written to config, logs a loud warning on every start, and ' +
+    'leaves the agent token in cleartext for the lifetime of the session.';
+/** Marker so operators can grep logs for this condition. */
+exports.INSECURE_TRANSPORT_MARKER = '[INSECURE TRANSPORT]';
+/**
+ * Thrown when an outbound target is not a TLS-protected `wss:`/`https:` URL.
+ *
+ * Every outbound connection path throws this instead of downgrading the
+ * protocol, so the agent token can never be written to a cleartext socket.
+ */
+class TransportSecurityError extends Error {
+    code;
+    url;
+    scheme;
+    context;
+    constructor(code, message, 
+    /** The offending target, as supplied by config. */
+    url, 
+    /** The offending scheme, or '' when the URL could not be parsed. */
+    scheme, 
+    /** Short description of the connection attempt, e.g. "wake channel". */
+    context = 'outbound connection') {
+        super(message);
+        this.code = code;
+        this.url = url;
+        this.scheme = scheme;
+        this.context = context;
+        this.name = 'TransportSecurityError';
+    }
+}
+exports.TransportSecurityError = TransportSecurityError;
+function describeContext(context) {
+    return context && context.length > 0 ? context : 'outbound connection';
+}
+/** Parse a target URL, throwing TransportSecurityError('invalid_url') on failure. */
+function parseTarget(url, context) {
+    try {
+        return url instanceof URL ? new URL(url.toString()) : new URL(url);
+    }
+    catch {
+        throw new TransportSecurityError('invalid_url', `Invalid URL for ${context}: ${String(url).slice(0, 200)}`, String(url).slice(0, 200), '', context);
+    }
+}
+/**
+ * True when the target is a TLS-protected `wss:`/`https:` URL. Unparseable
+ * input returns false — callers must fail closed.
+ */
+function isSecureTransportUrl(url) {
+    let parsed;
+    try {
+        parsed = url instanceof URL ? url : new URL(url);
+    }
+    catch {
+        return false;
+    }
+    return exports.SECURE_TRANSPORT_SCHEMES.includes(parsed.protocol);
+}
+/**
+ * Assert that `url` is a `wss:`/`https:` target and return it parsed.
+ *
+ * This is the single enforcement point for audit H-03: every outbound
+ * connection path calls it (directly or via {@link toWebSocketUrl} /
+ * {@link toHttpUrl}) before an `Authorization: Bearer <agent token>` header is
+ * attached. Non-TLS schemes throw instead of being downgraded. Only an
+ * explicit, non-persisted `allowInsecure` opt-in permits plaintext, and it
+ * warns loudly on every call.
+ */
+function assertSecureTransport(url, opts = {}) {
+    const context = describeContext(opts.context);
+    const parsed = parseTarget(url, context);
+    if (exports.SECURE_TRANSPORT_SCHEMES.includes(parsed.protocol)) {
+        return parsed;
+    }
+    if (opts.allowInsecure === true) {
+        console.warn(`${exports.INSECURE_TRANSPORT_MARKER} ${context} is using ${parsed.protocol}// — the agent token ` +
+            `is being sent in cleartext to ${parsed.host}. ${exports.INSECURE_TRANSPORT_HINT}`);
+        return parsed;
+    }
+    throw insecureTransportError(parsed, context);
+}
+function insecureTransportError(parsed, context) {
+    return new TransportSecurityError('insecure_transport', `Refusing to open ${context} to ${parsed.protocol}//${parsed.host}: the agent token is a ` +
+        `bearer credential and is only ever sent over TLS. ${exports.INSECURE_TRANSPORT_HINT}`, `${parsed.protocol}//${parsed.host}`, parsed.protocol, context);
+}
+/**
+ * Build a `wss:` target from a configured cloud URL.
+ *
+ * `https:` maps to `wss:` (same TLS transport, different protocol) and `wss:`
+ * is used as-is. `ws:`/`http:` throw unless the caller passed `allowInsecure`.
+ */
+function toWebSocketUrl(base, opts = {}) {
+    const context = describeContext(opts.context);
+    const parsed = assertSecureTransport(base, { ...opts, context });
+    if (parsed.protocol === 'https:') {
+        parsed.protocol = 'wss:';
+    }
+    return parsed;
+}
+/**
+ * Build an `https:` target from a configured cloud URL.
+ *
+ * `wss:` maps to `https:` (same TLS transport, SSE/plain HTTP) and `https:` is
+ * used as-is. `ws:`/`http:` throw unless the caller passed `allowInsecure`.
+ */
+function toHttpUrl(base, opts = {}) {
+    const context = describeContext(opts.context);
+    const parsed = assertSecureTransport(base, { ...opts, context });
+    if (parsed.protocol === 'wss:') {
+        parsed.protocol = 'https:';
+    }
+    else if (opts.allowInsecure === true && parsed.protocol === 'ws:') {
+        parsed.protocol = 'http:';
+    }
+    return parsed;
+}
+/* -------------------------------------------------------------------------- */
+/* Token lifecycle helpers (audit H-12)                                        */
+/* -------------------------------------------------------------------------- */
+/**
+ * Backoff schedule for consecutive authentication failures. Kept separate from
+ * DEFAULTS.RECONNECT_BACKOFF_MS because a rejected credential is a different
+ * class of failure: it is slow to start and slow to give up on.
+ */
+exports.AUTH_FAILURE_BACKOFF_MS = Object.freeze([
+    5_000, 15_000, 60_000, 300_000, 900_000,
+]);
+/**
+ * Consecutive 401/403 responses tolerated before the wake loop stops retrying.
+ *
+ * Policy: a credential the server evaluated and rejected cannot become valid by
+ * retrying, so retries are bounded rather than infinite. The bound exists only
+ * to absorb the two realistic transient cases — clock skew and a token the
+ * cloud rotated but has not yet replicated — after which the loop stops instead
+ * of hammering the auth endpoint from every connected agent.
+ */
+exports.MAX_AUTH_FAILURE_ATTEMPTS = 5;
+/**
+ * Operator-facing message for a credential the cloud rejected.
+ */
+function formatTokenRejectedMessage(status, attempts, maxAttempts) {
+    const statusText = status ? `HTTP ${status}` : 'auth failure';
+    const attemptText = typeof attempts === 'number' && typeof maxAttempts === 'number'
+        ? ` (attempt ${attempts} of ${maxAttempts})`
+        : '';
+    return (`auth_failed: agent token rejected by cloud (${statusText})${attemptText}. ` +
+        `The agent_token in sw-agent.config.json is invalid, revoked, or belongs to a different ` +
+        `agent_id. ${exports.TOKEN_ROTATION_HINT}`);
+}
+/**
+ * Operator-facing message for a credential the client itself found expired.
+ */
+function formatTokenExpiredMessage(expiresAt, marginMs, context) {
+    const at = Number.isFinite(expiresAt) ? new Date(expiresAt).toISOString() : 'an unknown time';
+    return (`${context} refused to use an expired token: it expires at ${at}, which is inside the ` +
+        `${marginMs}ms safety margin. ${exports.TOKEN_ROTATION_HINT}`);
+}
+//# sourceMappingURL=reconnect.js.map

package/dist/cjs/channels/reconnect.js.map

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

package/dist/cjs/channels/types.d.ts

@@ -0,0 +1,112 @@
+import { AgentMessage, Role } from '../protocol/envelope';
+/**
+ * State of the wake channel (SSE).
+ * - disconnected: not connected, possibly mid-backoff
+ * - connecting: HTTPS request in flight, awaiting response
+ * - connected: SSE stream open, receiving events
+ * - error: connection failed, will retry
+ */
+export type WakeChannelState = 'disconnected' | 'connecting' | 'connected' | 'error';
+/**
+ * Per-session envelope authentication policy.
+ *
+ * Supplied by the daemon from machine config; every field is optional and every
+ * default lives in `src/protocol/constants.ts` so the policy has exactly one
+ * definition. Nothing here can turn the negotiated-role check or the replay
+ * check off.
+ */
+export interface EnvelopeAuthPolicy {
+    /**
+     * Reject inbound envelopes that carry no per-session MAC. Defaults to
+     * ENVELOPE_MAC_REQUIRED_DEFAULT (true).
+     */
+    requireMac?: boolean;
+    /**
+     * Local ceiling: the highest role the relay may negotiate for this session,
+     * regardless of what it asks for. Defaults to
+     * ENVELOPE_MAX_NEGOTIABLE_ROLE_DEFAULT.
+     */
+    maxNegotiableRole?: Role;
+}
+/**
+ * State of the data channel (WSS).
+ * - closed: not open (either never opened, or closed after idle/disconnect)
+ * - connecting: WSS handshake in flight
+ * - open: ready to send/receive messages
+ * - closing: close handshake in flight
+ * - error: connection failed
+ */
+export type DataChannelState = 'closed' | 'connecting' | 'open' | 'closing' | 'error';
+/**
+ * Reason the data channel closed. Used for reconnect decisions and audit.
+ */
+export type DataChannelCloseReason = 'idle_timeout' | 'explicit_close' | 'remote_close' | 'protocol_error' | 'network_error' | 'auth_failed' | 'fatal_error' | 'shutdown';
+/**
+ * Wake event pushed by cloud via SSE.
+ * Tells the agent: "open the data channel, browser has work for you."
+ */
+export interface WakeEvent {
+    /** Unique ID for this wake (for dedup if SSE redelivers). */
+    wake_id: string;
+    /** Why cloud is waking the agent. */
+    reason: 'browser_request' | 'ping' | 'migration_queued' | 'config_sync';
+    /** Browser session ID that wants to talk (for routing). */
+    browser_session_id?: string;
+    /** Optional request_id that triggered the wake (for fast-track). */
+    request_id?: string;
+    /** When cloud queued this wake (epoch ms). */
+    queued_at: number;
+    /** Short-lived token to use when opening the data channel. */
+    data_channel_token: string;
+    /** When data_channel_token expires (epoch ms). */
+    data_channel_token_expires_at: number;
+    /**
+     * Roles the cloud agreed this session may act as. The connector intersects
+     * this with its own local ceiling and rejects every inbound envelope whose
+     * `user.role` is not in the result, so the relay cannot mint a role after the
+     * fact.
+     *
+     * Omitting this field is not a way to get "any role": an absent or empty list
+     * yields an empty permitted set and every envelope is rejected.
+     */
+    allowed_roles?: Role[];
+}
+/**
+ * Callback signature for incoming messages on the data channel.
+ * Part 5 will register a handler that dispatches to execution engine.
+ */
+export type MessageHandler = (msg: AgentMessage) => Promise<void> | void;
+/**
+ * Callback for state changes (used by agent-session to update browser UI).
+ */
+export type StateChangeHandler = (state: AgentSessionState) => void;
+export interface AgentSessionState {
+    wake: WakeChannelState;
+    data: DataChannelState;
+    /** True if at least one message is in-flight (waiting for response). */
+    has_in_flight: boolean;
+    /** Number of reconnect attempts since last successful connect. */
+    reconnect_attempts: number;
+    /** Last error message (if any). */
+    last_error?: string;
+    /** Epoch ms of last successful wake channel connect. */
+    wake_connected_at?: number;
+    /** Epoch ms of last successful data channel open. */
+    data_opened_at?: number;
+    /** Roles negotiated for the current data-channel session. Empty = none permitted. */
+    negotiated_roles: Role[];
+    /** True once a per-session envelope MAC key has been derived for the open channel. */
+    envelope_mac_active: boolean;
+    /** Inbound envelopes dropped by envelope authentication since start. */
+    envelope_authn_failures: number;
+    /** Epoch ms of the last inbound envelope dropped by envelope authentication. */
+    last_envelope_authn_failure_at?: number;
+    /**
+     * Wake events that were permitted to take over the data channel (audit M-15).
+     * Every increment is also written to the audit sink as a security event.
+     */
+    session_replacements: number;
+    /** Wake events refused because they named a different browser session. */
+    session_replacement_rejections: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cjs/channels/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/channels/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,cAAc,GAAG,YAAY,GAAG,WAAW,GAAG,OAAO,CAAC;AAErF;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,IAAI,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;AAEtF;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAC9B,cAAc,GACd,gBAAgB,GAChB,cAAc,GACd,gBAAgB,GAChB,eAAe,GACf,aAAa,GACb,aAAa,GACb,UAAU,CAAC;AAEf;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,MAAM,EAAE,iBAAiB,GAAG,MAAM,GAAG,kBAAkB,GAAG,aAAa,CAAC;IACxE,2DAA2D;IAC3D,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kDAAkD;IAClD,6BAA6B,EAAE,MAAM,CAAC;IACtC;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,IAAI,EAAE,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEzE;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;AAEpE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,EAAE,gBAAgB,CAAC;IACvB,wEAAwE;IACxE,aAAa,EAAE,OAAO,CAAC;IACvB,kEAAkE;IAClE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mCAAmC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,qDAAqD;IACrD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qFAAqF;IACrF,gBAAgB,EAAE,IAAI,EAAE,CAAC;IACzB,sFAAsF;IACtF,mBAAmB,EAAE,OAAO,CAAC;IAC7B,wEAAwE;IACxE,uBAAuB,EAAE,MAAM,CAAC;IAChC,gFAAgF;IAChF,8BAA8B,CAAC,EAAE,MAAM,CAAC;IACxC;;;OAGG;IACH,oBAAoB,EAAE,MAAM,CAAC;IAC7B,0EAA0E;IAC1E,8BAA8B,EAAE,MAAM,CAAC;CACxC"}

package/dist/cjs/channels/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/cjs/channels/types.js.map

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