@ninelives/agent-governance-sdk 5.0.1

package/dist/encryption/mesh-client.d.ts

@@ -0,0 +1,281 @@
+/**
+ * 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
+ */
+import { SecureChannel, type ChannelEstablishment } from "./channel";
+import { X3DHKeyManager, type PreKeyBundle } from "./x3dh";
+import { RegistryClient, type RegistryClientOptions, type DiscoverResult } from "./registry-client";
+export type WebSocketFactory = (url: string) => WebSocket;
+export interface MeshClientOptions {
+    relayUrl: string;
+    registryUrl: string;
+    keyManager: X3DHKeyManager;
+    agentDid: string;
+    displayName?: string;
+    /** Custom WebSocket constructor (e.g., for HTTPS_PROXY CONNECT tunneling in Node 22) */
+    wsFactory?: WebSocketFactory;
+    /**
+     * Inject a pre-built RegistryClient (overrides registryUrl). Useful for
+     * tests, custom auth, or sharing a client across multiple MeshClients.
+     */
+    registryClient?: RegistryClient;
+    /**
+     * Extra options forwarded to the auto-built RegistryClient when
+     * `registryClient` is not provided. Ignored if registryClient is set.
+     */
+    registryClientOptions?: Partial<Omit<RegistryClientOptions, "baseUrl">>;
+    /**
+     * Capabilities to publish at registration time. The displayName is
+     * automatically appended (so peers can find this agent via
+     * `discover(displayName)`). Default: empty array.
+     */
+    capabilities?: string[];
+    /**
+     * Arbitrary metadata to publish at registration. The display_name is
+     * automatically merged in if displayName is set.
+     */
+    registrationMetadata?: Record<string, string>;
+    /**
+     * Number of one-time pre-keys to generate and upload at connect time.
+     * Each successful X3DH initiation by a peer consumes one. Default 20.
+     */
+    oneTimePrekeyCount?: number;
+    /**
+     * If false, skip auto-registration on connect even when registryUrl is
+     * set (caller will register manually via getRegistry().register()).
+     * Default true.
+     */
+    autoRegister?: boolean;
+    /** AMIDs/DIDs that bypass Signal E2E — use legacy base64(JSON) wire format */
+    plaintextPeers?: string[];
+    /** Max time (ms) to wait for KNOCK resolution before rejecting a message */
+    knockTimeout?: number;
+    /**
+     * Automatically reconnect on non-1000 close events.
+     * Defaults to true. Set to false to keep the legacy manual-only behavior.
+     */
+    autoReconnect?: boolean;
+    /** Max reconnect attempts (default: Number.POSITIVE_INFINITY). */
+    maxReconnectAttempts?: number;
+    /** Base reconnect delay in ms before exponential backoff (default: 1000). */
+    reconnectBaseDelayMs?: number;
+    /** Max reconnect delay cap in ms (default: 60000). */
+    reconnectMaxDelayMs?: number;
+    /**
+     * Max messages to buffer per peer when an encrypted message arrives before
+     * its KNOCK has been processed (out-of-order delivery on the relay).
+     * Mirrors vendored agentmesh-sdk patch #16. Default 5. Set to 0 to disable.
+     */
+    preKnockBufferSize?: number;
+    /**
+     * TTL in ms for buffered pre-KNOCK messages before they are evicted.
+     * Default 3000.
+     */
+    preKnockBufferTtlMs?: number;
+    /**
+     * Max number of distinct peers that can have pre-KNOCK message buffers
+     * simultaneously. Prevents memory exhaustion from an adversary sending
+     * messages from many distinct DIDs before any KNOCK arrives. When
+     * exceeded, the oldest peer's buffer is evicted entirely. Default 100.
+     */
+    maxBufferedPeers?: number;
+}
+export interface MeshSession {
+    peerId: string;
+    channel: SecureChannel | null;
+    isPlaintext: boolean;
+    createdAt: Date;
+    messageCount: number;
+}
+/**
+ * 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`).
+ */
+export declare const 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.
+ */
+export declare class MeshClient {
+    private options;
+    private sessions;
+    private plaintextPeers;
+    private knockPending;
+    private knockAccepted;
+    private messageHandlers;
+    private knockHandlers;
+    private errorHandlers;
+    private disconnectHandlers;
+    private e2eVerifiedHandlers;
+    /** Tracks peers whose first encrypted message we've seen — feeds onE2EVerified. */
+    private e2eVerifiedSet;
+    private ws;
+    private connected;
+    private knockTimeout;
+    private autoReconnect;
+    private maxReconnectAttempts;
+    private reconnectBaseDelayMs;
+    private reconnectMaxDelayMs;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private clientInitiatedClose;
+    private preKnockBufferSize;
+    private preKnockBufferTtlMs;
+    private 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.
+     */
+    private preKnockBuffer;
+    private readonly registry;
+    private readonly autoRegister;
+    private readonly oneTimePrekeyCount;
+    private registered;
+    /**
+     * 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.
+     */
+    private 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(): string;
+    constructor(options: MeshClientOptions);
+    /**
+     * 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(): RegistryClient | null;
+    addPlaintextPeer(peerId: string): void;
+    removePlaintextPeer(peerId: string): void;
+    isPlaintextPeer(peerId: string): boolean;
+    connect(): Promise<void>;
+    /**
+     * 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.
+     */
+    registerSelf(): Promise<void>;
+    /**
+     * Discover peers advertising a given capability. Returns [] if no
+     * registry is configured.
+     */
+    discover(capability: string, limit?: number): Promise<DiscoverResult[]>;
+    /**
+     * 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`.
+     */
+    establishSessionWithPeer(peerId: string): Promise<MeshSession>;
+    private scheduleReconnect;
+    disconnect(): Promise<void>;
+    /**
+     * 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.
+     */
+    reconnect(): Promise<void>;
+    get isConnected(): boolean;
+    send(peerId: string, payload: unknown): Promise<void>;
+    establishSession(peerId: string, peerBundle: PreKeyBundle): Promise<MeshSession>;
+    acceptSession(peerId: string, establishment: ChannelEstablishment): MeshSession;
+    getSession(peerId: string): MeshSession | undefined;
+    closeSession(peerId: string): boolean;
+    onMessage(handler: (from: string, payload: unknown, isPlaintext: boolean) => void): void;
+    onKnock(handler: (from: string, intent: unknown) => Promise<boolean>): void;
+    /**
+     * 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: (kind: "ws" | "decrypt" | "knock" | "frame" | "session_desync", from: string, detail: string) => void): void;
+    /**
+     * 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: (reason: "client" | "server" | "ws-error", code?: number) => void): void;
+    /**
+     * 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: (peerAmid: string, isFirstPeer: boolean) => void): void;
+    sendHeartbeat(): void;
+    private handleFrame;
+    private handleMessage;
+    /**
+     * 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.
+     */
+    private handlePendingMessages;
+    private handleKnock;
+    private handleKnockAccept;
+    private handleKnockReject;
+    private bufferPreKnockFrame;
+    private drainPreKnockBuffer;
+    private dropPreKnockBuffer;
+    private serializeEstablishment;
+    private deserializeEstablishment;
+    private sendFrame;
+    private incrementSessionCount;
+    private uint8ToBase64;
+    private base64ToUint8;
+}
+//# sourceMappingURL=mesh-client.d.ts.map

package/dist/encryption/mesh-client.d.ts.map

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