@ninelives/agent-governance-sdk 5.0.1

package/dist/encryption/mesh-client.js

@@ -0,0 +1,1110 @@
+"use strict";
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MeshClient = exports.WS_CLOSE_SESSION_REPLACED = void 0;
+/**
+ * AgentMesh transport client — WebSocket connection to relay with
+ * plaintext-peer support, KNOCK pending queue, and wsFactory hook.
+ *
+ * Spec: docs/specs/AGENTMESH-WIRE-1.0.md Sections 9, 10, 12
+ *
+ * Features added for AzureClaw compatibility:
+ * - plaintextPeers: bypass E2E encryption for legacy peers (e.g., Rust controller)
+ * - wsFactory: custom WebSocket constructor for HTTPS_PROXY CONNECT tunneling
+ * - KNOCK pending queue: handle race between KNOCK and first message
+ */
+const channel_1 = require("./channel");
+const registry_client_1 = require("./registry-client");
+/**
+ * Derive the canonical AGT-main agent DID from an Ed25519 public key.
+ *
+ * Format: `did:mesh:<sha256(public_key)[:32]>` (32 hex chars = 16 bytes
+ * of digest). Matches the server's derivation in
+ * `agent-governance-python/agent-mesh/src/agentmesh/registry/app.py`
+ * (`key_hash = hashlib.sha256(public_key).hexdigest()[:32]`).
+ *
+ * If `fallback` looks like a `did:mesh:` already (callers that compute
+ * it themselves), prefer that; otherwise compute fresh from the public
+ * key. Sync function — relies on Node's `node:crypto` or the browser's
+ * SubtleCrypto can't be used synchronously so we hand-roll SHA-256 if
+ * neither is available. In practice the SDK only runs in Node so this
+ * just falls through to `require("node:crypto")`.
+ */
+function computeCanonicalDid(ed25519Public, fallback) {
+    if (fallback && fallback.startsWith("did:mesh:"))
+        return fallback;
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const nodeCrypto = require("node:crypto");
+    const hex = nodeCrypto.createHash("sha256").update(ed25519Public).digest("hex");
+    return `did:mesh:${hex.slice(0, 32)}`;
+}
+/**
+ * WebSocket close code sent by the relay when another connection
+ * authenticates for the same DID and displaces this socket.
+ *
+ * Deliberately not 1000 (Normal Closure): 1000 is indistinguishable from the
+ * client closing its own socket, which made a mailbox takeover silent and
+ * unattributable. Clients receive this as a server-initiated close but must
+ * NOT auto-reconnect on it — reconnecting would displace the replacing socket
+ * and the two would evict each other in a loop.
+ *
+ * Must stay in sync with `WS_CLOSE_SESSION_REPLACED` in the relay
+ * (`agentmesh/relay/app.py`).
+ */
+exports.WS_CLOSE_SESSION_REPLACED = 4006;
+/**
+ * High-level mesh client for agent-to-agent communication.
+ *
+ * Manages WebSocket connection to the relay, session establishment
+ * (KNOCK + X3DH), and message encryption/decryption. Supports
+ * plaintext peers for legacy interop.
+ */
+class MeshClient {
+    options;
+    sessions = new Map();
+    plaintextPeers;
+    knockPending = new Map();
+    knockAccepted = new Set();
+    messageHandlers = [];
+    knockHandlers = [];
+    errorHandlers = [];
+    disconnectHandlers = [];
+    e2eVerifiedHandlers = [];
+    /** Tracks peers whose first encrypted message we've seen — feeds onE2EVerified. */
+    e2eVerifiedSet = new Set();
+    ws = null;
+    connected = false;
+    knockTimeout;
+    autoReconnect;
+    maxReconnectAttempts;
+    reconnectBaseDelayMs;
+    reconnectMaxDelayMs;
+    reconnectAttempts = 0;
+    reconnectTimer = null;
+    clientInitiatedClose = false;
+    preKnockBufferSize;
+    preKnockBufferTtlMs;
+    maxBufferedPeers;
+    /**
+     * Per-peer buffer for encrypted message frames that arrived before the
+     * peer's KNOCK was processed. Drained when the KNOCK is later accepted.
+     * Mirrors vendored agentmesh-sdk patch #16.
+     */
+    preKnockBuffer = new Map();
+    registry;
+    autoRegister;
+    oneTimePrekeyCount;
+    registered = false;
+    /**
+     * The agent DID used on every wire-level send (`connect.from`,
+     * `mesh_send.from`, `knock.from`, …). Starts at `options.agentDid` so
+     * back-compat is preserved when no registry is configured or when
+     * registering against a pre-2533 registry. When `registerSelf()` runs
+     * against a POP-aware registry (AGT main since 2026-05-23), the server
+     * returns the canonical `did:mesh:<sha256(public_key)[:32]>` and we
+     * adopt it here — every subsequent frame uses the canonical form so
+     * relay and registry lookups agree.
+     */
+    activeDid;
+    /**
+     * Public read-only view of the active DID. Caller code that previously
+     * read `options.agentDid` and stored it should read this instead so
+     * post-registration DID swaps are visible.
+     */
+    get currentDid() {
+        return this.activeDid;
+    }
+    constructor(options) {
+        this.options = options;
+        // Compute the canonical AGT main DID locally so the connect frame
+        // can include the matching `from` field even on the very first
+        // connect (registerSelf runs AFTER connect resolves; the relay's
+        // POP gate validates `from == "did:mesh:" + sha256(public_key)[:32]`
+        // on the connect frame, NOT on the eventual server-derived DID).
+        // We replace whatever caller-supplied DID was passed because the
+        // POP-aware relay/registry will reject any other format. Pre-POP
+        // deployments don't care, so this is back-compat-safe.
+        this.activeDid = computeCanonicalDid(options.keyManager.identityKeyEd, options.agentDid);
+        this.plaintextPeers = new Set(options.plaintextPeers ?? []);
+        this.knockTimeout = options.knockTimeout ?? 10_000;
+        this.autoReconnect = options.autoReconnect ?? true;
+        this.maxReconnectAttempts = options.maxReconnectAttempts ?? Number.POSITIVE_INFINITY;
+        this.reconnectBaseDelayMs = options.reconnectBaseDelayMs ?? 1000;
+        this.reconnectMaxDelayMs = options.reconnectMaxDelayMs ?? 60_000;
+        this.preKnockBufferSize = options.preKnockBufferSize ?? 5;
+        this.preKnockBufferTtlMs = options.preKnockBufferTtlMs ?? 3_000;
+        this.maxBufferedPeers = options.maxBufferedPeers ?? 100;
+        this.autoRegister = options.autoRegister ?? true;
+        this.oneTimePrekeyCount = options.oneTimePrekeyCount ?? 20;
+        if (options.registryClient) {
+            this.registry = options.registryClient;
+        }
+        else if (options.registryUrl) {
+            // Wire an Ed25519-Timestamp signer to every registry call so
+            // `PUT /v1/agents/{did}/prekeys` and the other authed endpoints
+            // (heartbeat, reputation) pass `verify_ed25519_timestamp_auth`.
+            // The signer uses the same identity key the relay POP / connect-frame
+            // signature uses, so the registry can map `authed_did == activeDid`.
+            // The caller can override by passing their own `authSigner` via
+            // `registryClientOptions`.
+            const callerOpts = options.registryClientOptions ?? {};
+            // eslint-disable-next-line @typescript-eslint/no-this-alias
+            const self = this;
+            const authSigner = callerOpts.authSigner ?? {
+                get did() { return self.activeDid; }, // late-bind: DID can change after register
+                sign: (m) => options.keyManager.signMessage(m),
+            };
+            this.registry = new registry_client_1.RegistryClient({
+                baseUrl: options.registryUrl,
+                ...callerOpts,
+                authSigner,
+            });
+        }
+        else {
+            this.registry = null;
+        }
+    }
+    /**
+     * Access the RegistryClient (built from registryUrl or injected via
+     * registryClient). Returns null only if MeshClient was constructed
+     * without a registry URL or client — which means discover/peer lookup
+     * features are disabled.
+     */
+    getRegistry() {
+        return this.registry;
+    }
+    // ── Plaintext peers ─────────────────────────────────────────────
+    addPlaintextPeer(peerId) {
+        this.plaintextPeers.add(peerId);
+    }
+    removePlaintextPeer(peerId) {
+        this.plaintextPeers.delete(peerId);
+    }
+    isPlaintextPeer(peerId) {
+        return this.plaintextPeers.has(peerId);
+    }
+    // ── Connection ──────────────────────────────────────────────────
+    async connect() {
+        if (this.connected)
+            return;
+        const wsUrl = this.options.relayUrl.replace(/^http/, "ws") + "/ws";
+        const wsFactory = this.options.wsFactory ?? ((url) => new WebSocket(url));
+        this.ws = wsFactory(wsUrl);
+        await new Promise((resolve, reject) => {
+            this.ws.onopen = () => {
+                this.connected = true;
+                // POP-enabled connect frame (AGT main since 2026-05-23 PR #2632).
+                // Pre-POP relays ignore the extra fields — back-compat preserved.
+                // The relay verifies:
+                //  - DID equals `did:mesh:` + sha256(public_key)[:32]
+                //  - Ed25519 signature over the timestamp string (NOT pub||ts)
+                //    -- distinct from registry POP which signs pub||ts
+                //
+                // Encoding gotcha: the relay decodes with stdlib `base64.b64decode`
+                // (standard base64 with +/=), while the registry decodes with
+                // `urlsafe_b64decode` (base64url with -_). Mismatch in upstream
+                // server code; we have to match each endpoint's expectation
+                // separately. Emitting standard base64 here so the relay's
+                // `base64.b64decode(pub_b64)` and signature decode succeed.
+                const pubB64 = Buffer.from(this.options.keyManager.identityKeyEd).toString("base64");
+                const tsStr = new Date().toISOString();
+                const sig = this.options.keyManager.signMessage(new TextEncoder().encode(tsStr));
+                const sigB64 = Buffer.from(sig).toString("base64");
+                this.sendFrame({
+                    v: 1,
+                    type: "connect",
+                    from: this.activeDid,
+                    public_key: pubB64,
+                    timestamp: tsStr,
+                    signature: sigB64,
+                });
+                // Request any messages queued while offline (inbox replay)
+                this.sendFrame({
+                    v: 1,
+                    type: "fetch_pending",
+                    from: this.activeDid,
+                });
+                resolve();
+            };
+            this.ws.onerror = (e) => {
+                // Surface to AzureClaw-style observers BEFORE rejecting connect.
+                // Once connect resolves, subsequent ws errors flow through this same path.
+                const errEvent = e;
+                const detail = errEvent?.message ?? errEvent?.type ?? "ws-error";
+                for (const h of this.errorHandlers) {
+                    try {
+                        h("ws", this.activeDid, detail);
+                    }
+                    catch { /* swallow handler errors */ }
+                }
+                if (!this.connected)
+                    reject(new Error(`WebSocket error: ${e}`));
+            };
+            this.ws.onmessage = (event) => {
+                // Guard against malformed frames (upstream #1998) — combines with
+                // our additive event-hook handler.
+                let frame;
+                try {
+                    frame = JSON.parse(String(event.data));
+                }
+                catch (err) {
+                    console.warn(`MeshClient: dropping malformed frame (JSON parse): ${err}`);
+                    return;
+                }
+                this.handleFrame(frame).catch((err) => {
+                    console.warn(`MeshClient: handler error for frame type=${String(frame.type)}: ${err}`);
+                });
+            };
+            this.ws.onclose = (event) => {
+                const wasConnected = this.connected;
+                this.connected = false;
+                if (wasConnected) {
+                    // Distinguish client-initiated disconnect (1000 Normal Closure) from server / network drops.
+                    const code = event?.code;
+                    const isClientInitiated = code === 1000 || this.clientInitiatedClose;
+                    // The relay sends WS_CLOSE_SESSION_REPLACED when another connection
+                    // authenticated for this same DID and displaced this socket. It is
+                    // genuinely server-initiated (so it is NOT reported as "client"),
+                    // but it must not trigger auto-reconnect: reconnecting would displace
+                    // the socket that just replaced us and the two would evict each other
+                    // in a loop. Surface it through the error channel instead so the host
+                    // can act — if this agent did not initiate a reconnect, then another
+                    // party successfully authenticated as this DID.
+                    const isSessionReplaced = code === exports.WS_CLOSE_SESSION_REPLACED;
+                    const reason = isClientInitiated ? "client" : "server";
+                    for (const h of this.disconnectHandlers) {
+                        try {
+                            h(reason, code);
+                        }
+                        catch { /* swallow handler errors */ }
+                    }
+                    if (isSessionReplaced) {
+                        for (const h of this.errorHandlers) {
+                            try {
+                                h("ws", this.activeDid, "session replaced: another connection authenticated for this DID; " +
+                                    "not reconnecting to avoid an eviction loop");
+                            }
+                            catch { /* swallow handler errors */ }
+                        }
+                    }
+                    // Auto-reconnect on non-client closures (network drops, relay restart).
+                    // Mirrors vendored agentmesh-sdk patch #9: never give up by default,
+                    // exponential backoff capped at 60s. Caller can opt out via
+                    // autoReconnect: false in MeshClientOptions.
+                    if (!isClientInitiated && !isSessionReplaced && this.autoReconnect) {
+                        this.scheduleReconnect();
+                    }
+                }
+                this.clientInitiatedClose = false;
+            };
+        });
+        // Successful connect — reset reconnect counter.
+        this.reconnectAttempts = 0;
+        // Auto-register the agent in the registry on first successful connect.
+        // Idempotent: a re-connect after a relay restart skips this. The
+        // registry POST is idempotent on its end too (409 = already present).
+        if (this.autoRegister && this.registry && !this.registered) {
+            await this.registerSelf();
+        }
+    }
+    /**
+     * Publish this agent in the registry and upload an X3DH pre-key bundle.
+     *
+     * - Generates a signed pre-key and `oneTimePrekeyCount` one-time
+     *   pre-keys via `keyManager.generateSignedPreKey()` /
+     *   `generateOneTimePreKeys()`.
+     * - Capabilities are `[displayName?, ...options.capabilities]` so peers
+     *   can find this agent via `registry.discover(displayName)`.
+     * - Throws RegistryError on transport / 4xx (other than 409) / 5xx
+     *   failure. Callers that want best-effort registration should catch.
+     *
+     * Safe to call directly when `autoRegister: false` was used.
+     */
+    async registerSelf() {
+        if (!this.registry) {
+            throw new Error("MeshClient.registerSelf: no registry configured");
+        }
+        const km = this.options.keyManager;
+        // identityKey is the long-term X25519 public key derived from the
+        // Ed25519 signing key in the X3DHKeyManager constructor.
+        // identityKeyEd is the Ed25519 public key — peers MUST receive it
+        // to verify the signed pre-key signature (see x3dh.ts verifyBundle).
+        const identityKey = km.identityKey.publicKey;
+        const identityKeyEd = km.identityKeyEd;
+        const signedPreKey = km.generateSignedPreKey();
+        const oneTimePreKeys = km.generateOneTimePreKeys(this.oneTimePrekeyCount);
+        // Capabilities: include displayName so name-based discover() works.
+        const caps = [];
+        const dn = this.options.displayName;
+        if (dn)
+            caps.push(dn);
+        for (const c of this.options.capabilities ?? []) {
+            if (c && !caps.includes(c))
+                caps.push(c);
+        }
+        const metadata = { ...(this.options.registrationMetadata ?? {}) };
+        if (dn && metadata.display_name === undefined)
+            metadata.display_name = dn;
+        // POP-aware registration (AGT registry built from main since 2026-05-23,
+        // PR #2533). The registry verifies Ed25519(public_key_b64 || timestamp)
+        // against the supplied `public_key` (which MUST be the Ed25519 key,
+        // not the X25519 key — the server uses pynacl `VerifyKey` on it).
+        // Server then derives the canonical DID as
+        // `did:mesh:<sha256(public_key)[:32]>` and returns it. We adopt that
+        // DID as the active DID so subsequent registry lookups + relay
+        // `connect.from` agree with the server's view.
+        const popSigner = { sign: (m) => km.signMessage(m) };
+        const registerResult = await this.registry.register(this.activeDid, // ignored by POP-aware registries; kept for legacy back-compat
+        identityKeyEd, // POP path uses the Ed25519 public; legacy path tolerates
+        // either key since it only forwards to peers verbatim.
+        caps, metadata, popSigner);
+        // Adopt the canonical server DID. Legacy registries return the
+        // caller-supplied DID, so this is a no-op when registering against an
+        // older deployment.
+        if (registerResult.did && registerResult.did !== this.activeDid) {
+            this.activeDid = registerResult.did;
+        }
+        // Prekey upload must use the canonical DID (the registry indexes
+        // prekeys by the DID it derived, not the one the SDK started with).
+        await this.registry.uploadPrekeys(this.activeDid, identityKey, identityKeyEd, signedPreKey, oneTimePreKeys);
+        this.registered = true;
+    }
+    /**
+     * Discover peers advertising a given capability. Returns [] if no
+     * registry is configured.
+     */
+    async discover(capability, limit = 50) {
+        if (!this.registry)
+            return [];
+        return this.registry.discover(capability, limit);
+    }
+    /**
+     * Convenience: fetch a peer's pre-key bundle from the registry, then
+     * call `establishSession`. Throws if no registry is configured or no
+     * bundle is published for `peerId`.
+     */
+    async establishSessionWithPeer(peerId) {
+        const existing = this.sessions.get(peerId);
+        if (existing)
+            return existing;
+        if (this.isPlaintextPeer(peerId)) {
+            return this.establishSession(peerId, {});
+        }
+        if (!this.registry) {
+            throw new Error("MeshClient.establishSessionWithPeer: no registry configured");
+        }
+        const bundle = await this.registry.fetchPrekeys(peerId);
+        if (!bundle) {
+            throw new Error(`MeshClient.establishSessionWithPeer: no prekey bundle for ${peerId}`);
+        }
+        return this.establishSession(peerId, bundle);
+    }
+    scheduleReconnect() {
+        if (this.reconnectTimer)
+            return; // already scheduled
+        if (this.reconnectAttempts >= this.maxReconnectAttempts) {
+            for (const h of this.errorHandlers) {
+                try {
+                    h("ws", this.activeDid, `auto-reconnect gave up after ${this.reconnectAttempts} attempts`);
+                }
+                catch { /* swallow */ }
+            }
+            return;
+        }
+        const exp = Math.min(this.reconnectBaseDelayMs * 2 ** this.reconnectAttempts, this.reconnectMaxDelayMs);
+        // Light jitter (±20%) to avoid thundering-herd reconnects across many sandboxes.
+        const jitter = exp * (0.8 + Math.random() * 0.4);
+        this.reconnectAttempts++;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            void this.reconnect().catch((err) => {
+                for (const h of this.errorHandlers) {
+                    try {
+                        h("ws", this.activeDid, `reconnect failed: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                    catch { /* swallow */ }
+                }
+                // Schedule next attempt — onclose may not fire if connect() rejected before ws.onopen.
+                this.scheduleReconnect();
+            });
+        }, Math.round(jitter));
+    }
+    async disconnect() {
+        // Cancel any pending reconnect — caller asked to stay disconnected.
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        this.reconnectAttempts = 0;
+        // Drop any buffered pre-KNOCK frames + their eviction timers.
+        for (const peer of [...this.preKnockBuffer.keys()]) {
+            this.dropPreKnockBuffer(peer);
+        }
+        if (!this.connected || !this.ws)
+            return;
+        this.clientInitiatedClose = true;
+        this.sendFrame({ v: 1, type: "disconnect", from: this.activeDid });
+        this.ws.close(1000, "client disconnect");
+        this.connected = false;
+        this.ws = null;
+    }
+    /**
+     * Disconnect and reconnect to the relay.
+     *
+     * Resets the WebSocket connection and sends a fresh connect +
+     * fetch_pending sequence, triggering inbox replay for any messages
+     * queued while offline.
+     */
+    async reconnect() {
+        this.connected = false;
+        if (this.ws) {
+            try {
+                this.ws.close();
+            }
+            catch {
+                /* ignore close errors */
+            }
+            this.ws = null;
+        }
+        await this.connect();
+    }
+    get isConnected() {
+        return this.connected && this.ws !== null;
+    }
+    // ── Sending ─────────────────────────────────────────────────────
+    async send(peerId, payload) {
+        if (!this.isConnected)
+            throw new Error("Not connected to relay");
+        const messageId = crypto.randomUUID();
+        if (this.isPlaintextPeer(peerId)) {
+            // Legacy plaintext path — no encryption
+            this.sendFrame({
+                v: 1,
+                type: "message",
+                from: this.activeDid,
+                to: peerId,
+                id: messageId,
+                ts: new Date().toISOString(),
+                ciphertext: btoa(JSON.stringify(payload)),
+                plaintext: true,
+            });
+            this.incrementSessionCount(peerId, true);
+            return;
+        }
+        // Encrypted path
+        let session = this.sessions.get(peerId);
+        if (!session || !session.channel) {
+            throw new Error(`No encrypted session with ${peerId}. Call establishSession() first.`);
+        }
+        const encrypted = session.channel.send(new TextEncoder().encode(JSON.stringify(payload)));
+        this.sendFrame({
+            v: 1,
+            type: "message",
+            from: this.activeDid,
+            to: peerId,
+            id: messageId,
+            ts: new Date().toISOString(),
+            header: {
+                dh: this.uint8ToBase64(encrypted.header.dhPublicKey),
+                pn: encrypted.header.previousChainLength,
+                n: encrypted.header.messageNumber,
+            },
+            ciphertext: this.uint8ToBase64(encrypted.ciphertext),
+        });
+        session.messageCount++;
+    }
+    // ── Session establishment ───────────────────────────────────────
+    async establishSession(peerId, peerBundle) {
+        // Check for existing session
+        const existing = this.sessions.get(peerId);
+        if (existing)
+            return existing;
+        if (this.isPlaintextPeer(peerId)) {
+            const session = {
+                peerId,
+                channel: null,
+                isPlaintext: true,
+                createdAt: new Date(),
+                messageCount: 0,
+            };
+            this.sessions.set(peerId, session);
+            return session;
+        }
+        // Send KNOCK
+        const knockId = crypto.randomUUID();
+        // X3DH + SecureChannel — compute establishment FIRST so we can embed it
+        // in the KNOCK frame. This lets the receiver auto-bootstrap the responder
+        // session before any ciphertext arrives, eliminating the
+        // "No encrypted session" race that vendored agentmesh-sdk patch #4b
+        // worked around. Backwards-compatible: receivers that don't understand
+        // the `establishment` field fall back to manual acceptSession() calls.
+        const [channel, establishment] = channel_1.SecureChannel.createSender(this.options.keyManager, peerBundle, new TextEncoder().encode(`${this.activeDid}|${peerId}`));
+        this.sendFrame({
+            v: 1,
+            type: "knock",
+            from: this.activeDid,
+            to: peerId,
+            id: knockId,
+            ts: new Date().toISOString(),
+            intent: { action: "establish_session" },
+            establishment: this.serializeEstablishment(establishment),
+        });
+        const session = {
+            peerId,
+            channel,
+            isPlaintext: false,
+            createdAt: new Date(),
+            messageCount: 0,
+        };
+        this.sessions.set(peerId, session);
+        return session;
+    }
+    acceptSession(peerId, establishment) {
+        const channel = channel_1.SecureChannel.createReceiver(this.options.keyManager, establishment, new TextEncoder().encode(`${peerId}|${this.activeDid}`));
+        const session = {
+            peerId,
+            channel,
+            isPlaintext: false,
+            createdAt: new Date(),
+            messageCount: 0,
+        };
+        this.sessions.set(peerId, session);
+        this.knockAccepted.add(peerId);
+        return session;
+    }
+    getSession(peerId) {
+        return this.sessions.get(peerId);
+    }
+    closeSession(peerId) {
+        const session = this.sessions.get(peerId);
+        if (!session)
+            return false;
+        if (session.channel)
+            session.channel.close();
+        this.sessions.delete(peerId);
+        this.knockAccepted.delete(peerId);
+        return true;
+    }
+    // ── Handlers ────────────────────────────────────────────────────
+    onMessage(handler) {
+        this.messageHandlers.push(handler);
+    }
+    onKnock(handler) {
+        this.knockHandlers.push(handler);
+    }
+    /**
+     * Register a callback for transport-level errors.
+     *
+     * Fires for: WebSocket errors (handshake, mid-stream), decrypt failures,
+     * KNOCK protocol errors, frame validation, and `session_desync` events
+     * (recoverable ratchet drift — caller should re-establishSession to that
+     * peer; differs from "decrypt" which means no session existed at all).
+     * Multiple handlers may be registered; each is invoked in registration
+     * order. Handler exceptions are swallowed so one buggy observer cannot
+     * break the others.
+     */
+    onError(handler) {
+        this.errorHandlers.push(handler);
+    }
+    /**
+     * Register a callback for transport disconnect events.
+     *
+     * `reason` is `"client"` for caller-initiated `disconnect()`, `"server"`
+     * for relay-side closes (network drop, relay restart), and `"ws-error"`
+     * when an error event fires on an already-connected socket.
+     */
+    onDisconnect(handler) {
+        this.disconnectHandlers.push(handler);
+    }
+    /**
+     * Register a callback that fires the first time we successfully decrypt
+     * a message from a given peer (i.e. the X3DH+Double-Ratchet session
+     * with that peer is fully end-to-end verified).
+     *
+     * `isFirstPeer` is `true` only for the very first verified peer in the
+     * client's lifetime; subsequent peers fire with `false`. This lets
+     * orchestrators print "mesh online" once and "+ peer X verified" for
+     * the rest.
+     */
+    onE2EVerified(handler) {
+        this.e2eVerifiedHandlers.push(handler);
+    }
+    // ── Heartbeat ───────────────────────────────────────────────────
+    sendHeartbeat() {
+        if (!this.isConnected)
+            return;
+        this.sendFrame({
+            v: 1,
+            type: "heartbeat",
+            from: this.activeDid,
+            ts: new Date().toISOString(),
+        });
+    }
+    // ── Frame handling ──────────────────────────────────────────────
+    async handleFrame(frame) {
+        const type = frame.type;
+        const from = frame.from;
+        if (type === "message") {
+            await this.handleMessage(frame);
+        }
+        else if (type === "knock") {
+            await this.handleKnock(frame);
+        }
+        else if (type === "knock_accept") {
+            this.handleKnockAccept(frame);
+        }
+        else if (type === "knock_reject") {
+            this.handleKnockReject(frame);
+        }
+        else if (type === "ack") {
+            // ACK processed — nothing to do
+        }
+        else if (type === "pending_messages") {
+            await this.handlePendingMessages(frame);
+        }
+    }
+    async handleMessage(frame) {
+        const from = frame.from;
+        // Check KNOCK pending queue — wait for resolution if KNOCK is in-flight
+        if (!this.knockAccepted.has(from) && !this.isPlaintextPeer(from)) {
+            const pending = this.knockPending.get(from);
+            if (pending) {
+                // Wait for KNOCK resolution
+                const accepted = await new Promise((resolve) => {
+                    const originalResolve = pending.resolve;
+                    pending.resolve = (val) => {
+                        originalResolve(val);
+                        resolve(val);
+                    };
+                });
+                if (!accepted)
+                    return; // KNOCK rejected — drop message
+            }
+        }
+        let payload;
+        let isPlaintext = false;
+        // Security hardening: whether an inbound message is treated as legacy
+        // plaintext is decided solely from the receiver's own operator
+        // configuration (`plaintextPeers`, via isPlaintextPeer(from)). The wire
+        // frame also carries a `plaintext` boolean, but it is sender-controlled and
+        // must not select this branch — trusting it would let the sender skip
+        // X3DH / Double Ratchet / AEAD verification and be attributed an arbitrary
+        // `from` DID. Gate on isPlaintextPeer only; a peer that is not explicitly
+        // allow-listed for plaintext always takes the encrypted path below and is
+        // dropped if it cannot be cryptographically authenticated.
+        if (this.isPlaintextPeer(from) &&
+            !this.sessions.get(from)?.channel &&
+            !this.e2eVerifiedSet.has(from)) {
+            // Legacy plaintext — taken ONLY for an operator-allow-listed peer that has
+            // no negotiated encrypted session AND has never been E2E-verified.
+            //
+            // The `e2eVerifiedSet` term is a one-way latch and is load-bearing. A live
+            // `session.channel` is NOT sufficient on its own, because several paths
+            // delete the session and would otherwise re-open this gate for a peer that
+            // had already been cryptographically verified:
+            //   * the Gap-G3 ratchet-desync handler below calls closeSession() after a
+            //     single decrypt failure — a malicious relay can force that with one
+            //     garbage-ciphertext frame and then downgrade with the next frame;
+            //   * handleKnockReject() calls closeSession() on an unauthenticated
+            //     `knock_reject` frame — a one-frame variant of the same attack;
+            //   * any future teardown path would silently inherit the same weakness.
+            // Latching on e2eVerifiedSet (which is only ever added to, never cleared)
+            // makes the guarantee teardown-path-agnostic: once a peer has produced a
+            // successfully decrypted frame, it can never again be handled as plaintext
+            // for the lifetime of this client.
+            //
+            // Once a live channel exists for the peer we deliberately fall through to
+            // the encrypted path instead of handling the frame as plaintext: a genuine
+            // encrypted frame is decrypted via the ratchet, while a plaintext /
+            // headerless downgrade frame fails closed on the missing-ratchet-header
+            // check below. This keeps downgrade protection while no longer
+            // black-holing legitimate encrypted traffic from a peer that is also
+            // allow-listed for plaintext.
+            payload = JSON.parse(atob(frame.ciphertext));
+            isPlaintext = true;
+        }
+        else {
+            // Encrypted
+            const header = frame.header;
+            if (!header || typeof header.dh !== "string") {
+                // Security hardening: an encrypted `message` frame must carry a ratchet
+                // header. Validate this BEFORE the pre-KNOCK buffering path below so a
+                // malformed / headerless frame — which can never be decrypted — is
+                // dropped immediately, instead of occupying pre-KNOCK buffer capacity
+                // until TTL eviction and only failing closed when the buffer is drained.
+                for (const h of this.errorHandlers) {
+                    try {
+                        h("decrypt", from, "encrypted message missing ratchet header — dropping");
+                    }
+                    catch { /* swallow */ }
+                }
+                return;
+            }
+            const session = this.sessions.get(from);
+            if (!session?.channel) {
+                // Gap-G4 (vendored agentmesh-sdk patch #16): pre-KNOCK message buffer.
+                // The relay does not guarantee inter-frame ordering — an encrypted
+                // message can land before its KNOCK is processed. Drop-on-floor was
+                // the upstream behaviour; instead, buffer the raw frame here and
+                // drain it from handleKnock() once the KNOCK is accepted. Capped at
+                // preKnockBufferSize entries per peer with preKnockBufferTtlMs TTL.
+                if (this.preKnockBufferSize > 0 && !this.isPlaintextPeer(from)) {
+                    this.bufferPreKnockFrame(from, frame);
+                }
+                else {
+                    for (const h of this.errorHandlers) {
+                        try {
+                            h("decrypt", from, "no session for encrypted message — dropping");
+                        }
+                        catch { /* swallow */ }
+                    }
+                }
+                return;
+            }
+            const encrypted = {
+                header: {
+                    dhPublicKey: this.base64ToUint8(header.dh),
+                    previousChainLength: header.pn,
+                    messageNumber: header.n,
+                },
+                ciphertext: this.base64ToUint8(frame.ciphertext),
+            };
+            let plaintext;
+            try {
+                plaintext = session.channel.receive(encrypted);
+            }
+            catch (err) {
+                // Gap-G3 (vendored agentmesh-sdk patch #13): on decrypt failure inside
+                // an existing session, the ratchet is desynchronised — every
+                // subsequent inbound frame will fail the same way. Tear down the
+                // broken session so the next establishSession() to this peer runs a
+                // fresh X3DH + KNOCK round, and surface a dedicated "session_desync"
+                // error kind so callers can distinguish recoverable ratchet drift
+                // (re-establish & retry) from genuine tampering (drop & alert).
+                const detail = err instanceof Error ? err.message : String(err);
+                this.closeSession(from);
+                this.knockAccepted.delete(from);
+                for (const h of this.errorHandlers) {
+                    try {
+                        h("session_desync", from, detail);
+                    }
+                    catch { /* swallow */ }
+                }
+                return;
+            }
+            payload = JSON.parse(new TextDecoder().decode(plaintext));
+            session.messageCount++;
+            // First successfully-decrypted message from this peer means E2E
+            // is end-to-end verified (KNOCK + X3DH + Double Ratchet all worked).
+            // Surface to observers exactly once per peer per process lifetime.
+            if (!this.e2eVerifiedSet.has(from)) {
+                this.e2eVerifiedSet.add(from);
+                const isFirstPeer = this.e2eVerifiedSet.size === 1;
+                for (const h of this.e2eVerifiedHandlers) {
+                    try {
+                        h(from, isFirstPeer);
+                    }
+                    catch { /* swallow handler errors */ }
+                }
+            }
+        }
+        // Send ACK
+        this.sendFrame({ v: 1, type: "ack", id: frame.id });
+        // Notify handlers
+        for (const handler of this.messageHandlers) {
+            try {
+                handler(from, payload, isPlaintext);
+            }
+            catch { /* swallow handler errors */ }
+        }
+    }
+    /**
+     * Handle a batch of pending messages replayed by the relay on reconnect.
+     *
+     * The relay may respond to a fetch_pending frame with a
+     * pending_messages frame containing an array of queued messages.
+     * Each message is dispatched through the standard handleMessage path.
+     */
+    async handlePendingMessages(frame) {
+        // Typed as unknown[] rather than Record<string, unknown>[] because this is
+        // relay-supplied JSON: entries can legally be null or primitives, and the
+        // stricter type would be a lie that hides the validation below.
+        const messages = frame.messages;
+        if (!Array.isArray(messages))
+            return;
+        for (const msg of messages) {
+            const isFrameShaped = typeof msg === "object" && msg !== null && !Array.isArray(msg);
+            // Extract the peer *before* the try and without dereferencing a
+            // possibly-null entry. Doing it inside the catch would throw on a null
+            // entry, and that throw would be absorbed by the handler guard below,
+            // losing the drop report entirely.
+            const rawFrom = isFrameShaped ? msg.from : undefined;
+            const peer = typeof rawFrom === "string" ? rawFrom : "";
+            // Isolate each queued message: the batch is relay-supplied, so a single
+            // malformed entry (e.g. ciphertext that fails JSON.parse) must not abort
+            // the loop and silently discard the remaining pending mail. Surface the
+            // failure and continue draining.
+            try {
+                if (!isFrameShaped) {
+                    throw new Error(`expected a frame object, got ${msg === null ? "null" : typeof msg}`);
+                }
+                await this.handleMessage(msg);
+            }
+            catch (err) {
+                const detail = err instanceof Error ? err.message : String(err);
+                for (const h of this.errorHandlers) {
+                    try {
+                        h("frame", peer, `pending message dropped: ${detail}`);
+                    }
+                    catch { /* swallow */ }
+                }
+            }
+        }
+    }
+    async handleKnock(frame) {
+        const from = frame.from;
+        const intent = frame.intent;
+        // Register pending entry so concurrent handleMessage calls wait for
+        // the verdict. handleMessage may wrap `resolve` to add its own waiter;
+        // we look up the (possibly-wrapped) function when we resolve below.
+        //
+        // The timer is the abort path: if no verdict arrives within
+        // knockTimeout, resolve waiters to false and clear the entry. A
+        // `timedOut` flag prevents a slow handler from sending knock_accept
+        // after the timer has already told waiters the KNOCK was rejected.
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            const entry = this.knockPending.get(from);
+            if (entry) {
+                this.knockPending.delete(from);
+                entry.resolve(false);
+            }
+        }, this.knockTimeout);
+        this.knockPending.set(from, { resolve: () => { }, timer });
+        // Evaluate via registered handlers. Use try/finally so the timer is
+        // cleared and the pending entry resolved even if a handler throws —
+        // otherwise the entry would leak and a re-KNOCK from the same peer
+        // would race against stale state.
+        let accepted = true;
+        try {
+            for (const handler of this.knockHandlers) {
+                if (!(await handler(from, intent))) {
+                    accepted = false;
+                    break;
+                }
+            }
+        }
+        finally {
+            clearTimeout(timer);
+            if (!timedOut) {
+                const entry = this.knockPending.get(from);
+                if (entry) {
+                    this.knockPending.delete(from);
+                    entry.resolve(accepted);
+                }
+            }
+        }
+        // If the timer beat the handler eval, waiters were already told
+        // "rejected"; honor that decision when responding to the relay.
+        if (timedOut)
+            accepted = false;
+        if (accepted) {
+            // Auto-bootstrap responder session if establishment data was embedded
+            // in the knock. Mirrors vendored agentmesh-sdk patch #4b — receiver no
+            // longer needs to call acceptSession() manually before the first
+            // encrypted message arrives.
+            const est = frame.establishment;
+            if (est && !this.sessions.has(from)) {
+                try {
+                    const establishment = this.deserializeEstablishment(est);
+                    this.acceptSession(from, establishment);
+                }
+                catch (err) {
+                    for (const h of this.errorHandlers) {
+                        try {
+                            h("knock", from, `failed to bootstrap responder from KNOCK: ${err instanceof Error ? err.message : String(err)}`);
+                        }
+                        catch { /* swallow */ }
+                    }
+                    accepted = false;
+                }
+            }
+            // Always record acceptance so the encrypted-message gate stops
+            // waiting/buffering. (`acceptSession` also sets this, but keep the
+            // legacy-peer path covered too.)
+            if (accepted)
+                this.knockAccepted.add(from);
+        }
+        if (accepted) {
+            this.sendFrame({
+                v: 1,
+                type: "knock_accept",
+                from: this.activeDid,
+                to: from,
+                id: crypto.randomUUID(),
+                knock_id: frame.id,
+                ts: new Date().toISOString(),
+            });
+            // Gap-G4: drain any encrypted frames that arrived for this peer
+            // before its KNOCK was processed. The session is now established
+            // (via auto-bootstrap above or a prior acceptSession call), so the
+            // buffered frames can be replayed through the normal handleMessage
+            // path and decrypted against the fresh session.
+            await this.drainPreKnockBuffer(from);
+        }
+        else {
+            this.sendFrame({
+                v: 1,
+                type: "knock_reject",
+                from: this.activeDid,
+                to: from,
+                id: crypto.randomUUID(),
+                knock_id: frame.id,
+                reason: "policy_denied",
+                ts: new Date().toISOString(),
+            });
+            // Drop any buffered frames — KNOCK was rejected so we cannot decrypt
+            // them anyway. Avoids unbounded buffer growth for hostile peers.
+            this.dropPreKnockBuffer(from);
+        }
+    }
+    handleKnockAccept(frame) {
+        const from = frame.from;
+        this.knockAccepted.add(from);
+    }
+    handleKnockReject(frame) {
+        const from = frame.from;
+        this.closeSession(from);
+    }
+    // ── Pre-KNOCK buffer (Gap-G4 / vendored patch #16) ──────────────
+    bufferPreKnockFrame(from, frame) {
+        let entries = this.preKnockBuffer.get(from);
+        if (!entries) {
+            // Enforce global peer cap before adding a new peer's buffer.
+            if (this.preKnockBuffer.size >= this.maxBufferedPeers) {
+                const oldestPeer = this.preKnockBuffer.keys().next().value;
+                this.dropPreKnockBuffer(oldestPeer);
+                for (const h of this.errorHandlers) {
+                    try {
+                        h("frame", oldestPeer, `pre-knock buffer evicted: global peer cap (${this.maxBufferedPeers}) reached`);
+                    }
+                    catch { /* swallow */ }
+                }
+            }
+            entries = [];
+            this.preKnockBuffer.set(from, entries);
+        }
+        // Cap: drop oldest when full to keep newest message (sender most likely
+        // to retransmit nothing — newer frames carry the most recent ratchet
+        // state and have the best chance of being decryptable).
+        if (entries.length >= this.preKnockBufferSize) {
+            const evicted = entries.shift();
+            if (evicted)
+                clearTimeout(evicted.timer);
+        }
+        const timer = setTimeout(() => {
+            const list = this.preKnockBuffer.get(from);
+            if (!list)
+                return;
+            const idx = list.findIndex((e) => e.frame === frame);
+            if (idx >= 0)
+                list.splice(idx, 1);
+            if (list.length === 0)
+                this.preKnockBuffer.delete(from);
+        }, this.preKnockBufferTtlMs);
+        entries.push({ frame, timer });
+    }
+    async drainPreKnockBuffer(from) {
+        const entries = this.preKnockBuffer.get(from);
+        if (!entries || entries.length === 0)
+            return;
+        this.preKnockBuffer.delete(from);
+        for (const entry of entries) {
+            clearTimeout(entry.timer);
+            try {
+                await this.handleMessage(entry.frame);
+            }
+            catch (err) {
+                for (const h of this.errorHandlers) {
+                    try {
+                        h("decrypt", from, `pre-knock drain failed: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                    catch { /* swallow */ }
+                }
+            }
+        }
+    }
+    dropPreKnockBuffer(from) {
+        const entries = this.preKnockBuffer.get(from);
+        if (!entries)
+            return;
+        for (const entry of entries)
+            clearTimeout(entry.timer);
+        this.preKnockBuffer.delete(from);
+    }
+    // ── Establishment (de)serialization ─────────────────────────────
+    serializeEstablishment(est) {
+        const out = {
+            ik: this.uint8ToBase64(est.initiatorIdentityKey),
+            ek: this.uint8ToBase64(est.ephemeralPublicKey),
+        };
+        if (typeof est.usedOneTimeKeyId === "number")
+            out.otk = est.usedOneTimeKeyId;
+        return out;
+    }
+    deserializeEstablishment(obj) {
+        const ik = obj.ik;
+        const ek = obj.ek;
+        if (typeof ik !== "string" || typeof ek !== "string") {
+            throw new Error("malformed establishment: missing ik/ek");
+        }
+        const result = {
+            initiatorIdentityKey: this.base64ToUint8(ik),
+            ephemeralPublicKey: this.base64ToUint8(ek),
+        };
+        if (typeof obj.otk === "number")
+            result.usedOneTimeKeyId = obj.otk;
+        return result;
+    }
+    // ── Utilities ───────────────────────────────────────────────────
+    sendFrame(frame) {
+        if (this.ws && this.connected) {
+            this.ws.send(JSON.stringify(frame));
+        }
+    }
+    incrementSessionCount(peerId, isPlaintext) {
+        let session = this.sessions.get(peerId);
+        if (!session) {
+            session = { peerId, channel: null, isPlaintext, createdAt: new Date(), messageCount: 0 };
+            this.sessions.set(peerId, session);
+        }
+        session.messageCount++;
+    }
+    uint8ToBase64(data) {
+        // Use Buffer in Node.js to avoid stack overflow on large payloads
+        if (typeof Buffer !== "undefined") {
+            return Buffer.from(data).toString("base64");
+        }
+        // Browser fallback — loop-based
+        let binary = "";
+        for (let i = 0; i < data.length; i++) {
+            binary += String.fromCharCode(data[i]);
+        }
+        return btoa(binary);
+    }
+    base64ToUint8(b64) {
+        if (typeof Buffer !== "undefined") {
+            return new Uint8Array(Buffer.from(b64, "base64"));
+        }
+        const binary = atob(b64);
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i++) {
+            bytes[i] = binary.charCodeAt(i);
+        }
+        return bytes;
+    }
+}
+exports.MeshClient = MeshClient;
+//# sourceMappingURL=mesh-client.js.map