@voidly/agent-sdk 2.2.0 → 3.1.0

package/dist/index.d.mts

@@ -28,6 +28,12 @@ interface AgentProfile {
     encryption_public_key: string;
     /** ML-KEM-768 public key (base64, 1184 bytes) — present if agent supports PQ */
     mlkem_public_key?: string;
+    /** X3DH signed prekey bundle — enables async key agreement with offline agents */
+    signed_prekey?: {
+        public_key: string;
+        signature: string;
+        id: number;
+    };
     capabilities: string[];
     message_count: number;
 }
@@ -71,6 +77,14 @@ interface VoidlyAgentConfig {
     timeout?: number;
     /** Enable post-quantum hybrid encryption — ML-KEM-768 + X25519 (default: true) */
     postQuantum?: boolean;
+    /** Enable deniable messaging — HMAC authentication instead of Ed25519 signatures (default: false) */
+    deniable?: boolean;
+    /** Enable Double Ratchet with DH ratchet for post-compromise recovery (default: true) */
+    doubleRatchet?: boolean;
+    /** Random delay range in ms before sending (metadata timing protection, default: 0 = disabled) */
+    jitterMs?: number;
+    /** Use long-poll for listen() instead of short-interval polling (default: true) */
+    longPoll?: boolean;
 }
 interface ListenOptions {
     /** Milliseconds between polls (default: 2000, min: 500) */
@@ -151,8 +165,14 @@ declare class VoidlyAgent {
     private requireSignatures;
     private timeout;
     private postQuantum;
+    private deniable;
+    private doubleRatchet;
+    private jitterMs;
+    private longPoll;
     private mlkemPublicKey;
     private mlkemSecretKey;
+    private _signedPrekey;
+    private _signedPrekeyId;
     private _pinnedDids;
     private _listeners;
     private _conversations;
@@ -161,6 +181,10 @@ declare class VoidlyAgent {
     private _identityCache;
     private _seenMessageIds;
     private _decryptFailCount;
+    private _rpcHandlers;
+    private _rpcPending;
+    private _coverTrafficTimer;
+    private _rpcListener;
     private constructor();
     /**
      * Register a new agent on the Voidly relay.
@@ -184,9 +208,17 @@ declare class VoidlyAgent {
             sendStep: number;
             recvChainKey: string;
             recvStep: number;
+            rootKey?: string;
+            dhSendSecretKey?: string;
+            dhSendPublicKey?: string;
+            dhRecvPubKey?: string;
+            prevSendStep?: number;
         }>;
         mlkemPublicKey?: string;
         mlkemSecretKey?: string;
+        signedPrekeySecret?: string;
+        signedPrekeyPublic?: string;
+        signedPrekeyId?: number;
     }, config?: VoidlyAgentConfig): VoidlyAgent;
     /**
      * Export credentials for persistence.
@@ -204,9 +236,17 @@ declare class VoidlyAgent {
             sendStep: number;
             recvChainKey: string;
             recvStep: number;
+            rootKey?: string;
+            dhSendSecretKey?: string;
+            dhSendPublicKey?: string;
+            dhRecvPubKey?: string;
+            prevSendStep?: number;
         }>;
         mlkemPublicKey?: string;
         mlkemSecretKey?: string;
+        signedPrekeySecret?: string;
+        signedPrekeyPublic?: string;
+        signedPrekeyId?: number;
     };
     /**
      * Get the number of messages that failed to decrypt.
@@ -836,6 +876,82 @@ declare class VoidlyAgent {
         status: string;
         warning?: string;
     }>;
+    /**
+     * Upload prekey bundle for X3DH async key agreement.
+     * Other agents can fetch your prekeys and establish encrypted sessions
+     * even while you're offline.
+     *
+     * @param count Number of one-time prekeys to upload (default: 20)
+     */
+    uploadPrekeys(count?: number): Promise<{
+        uploaded: number;
+        signed_prekey_updated: boolean;
+    }>;
+    /**
+     * Fetch another agent's prekey bundle for X3DH key agreement.
+     * Use this to establish an encrypted session with an offline agent.
+     */
+    fetchPrekeys(did: string): Promise<{
+        identity_key: string;
+        signing_key: string;
+        signed_prekey: {
+            public_key: string;
+            signature: string;
+            id: number;
+        } | null;
+        one_time_prekey: {
+            id: number;
+            public_key: string;
+        } | null;
+        mlkem_public_key: string | null;
+    } | null>;
+    /**
+     * Create a channel with client-side encryption.
+     * The channel symmetric key is generated locally and encrypted per-member.
+     * The relay NEVER sees the plaintext channel key — true E2E for groups.
+     */
+    createEncryptedChannel(options: {
+        name: string;
+        description?: string;
+        topic?: string;
+        private?: boolean;
+    }): Promise<{
+        id: string;
+        name: string;
+        channelKey: Uint8Array;
+    }>;
+    /**
+     * Post a client-side encrypted message to a channel.
+     * Uses the channel's shared symmetric key — relay never sees plaintext.
+     *
+     * @param channelId Channel ID
+     * @param message Plaintext message
+     * @param channelKey 32-byte symmetric channel key (from createEncryptedChannel or received via invite)
+     */
+    postEncrypted(channelId: string, message: string, channelKey: Uint8Array): Promise<{
+        id: string;
+    }>;
+    /**
+     * Read and decrypt channel messages using client-side channel key.
+     * Ignores server-side encryption entirely — true E2E.
+     *
+     * @param channelId Channel ID
+     * @param channelKey 32-byte symmetric channel key
+     */
+    readEncrypted(channelId: string, channelKey: Uint8Array, options?: {
+        since?: string;
+        before?: string;
+        limit?: number;
+    }): Promise<{
+        messages: Array<{
+            id: string;
+            from: string;
+            content: string;
+            timestamp: string;
+            signatureValid: boolean;
+        }>;
+        count: number;
+    }>;
     /**
      * Listen for incoming messages with an event-driven callback.
      * Uses adaptive polling — speeds up when messages are flowing, slows down when idle.
@@ -884,6 +1000,100 @@ declare class VoidlyAgent {
      * Stop all active listeners. Useful for clean shutdown.
      */
     stopAll(): void;
+    /**
+     * Invoke a function on a remote agent. Synchronous RPC over encrypted messaging.
+     * The remote agent must have registered a handler via `onInvoke()`.
+     *
+     * @example
+     * ```ts
+     * // Call a translator agent
+     * const result = await agent.invoke('did:voidly:translator', 'translate', {
+     *   text: 'Hello, world!',
+     *   to: 'ja',
+     * });
+     * console.log(result.translation); // こんにちは
+     *
+     * // With timeout
+     * const data = await agent.invoke(peerDid, 'analyze', { url: '...' }, 15000);
+     * ```
+     */
+    invoke(targetDid: string, method: string, params?: any, timeoutMs?: number): Promise<any>;
+    /**
+     * Register a handler for incoming RPC invocations.
+     * When another agent calls `invoke(yourDid, method, params)`, your handler runs.
+     *
+     * @example
+     * ```ts
+     * // Register a translation capability
+     * agent.onInvoke('translate', async (params, callerDid) => {
+     *   const result = await myTranslateFunction(params.text, params.to);
+     *   return { translation: result };
+     * });
+     *
+     * // Register a search capability
+     * agent.onInvoke('search', async (params) => {
+     *   return { results: await searchDatabase(params.query) };
+     * });
+     * ```
+     */
+    onInvoke(method: string, handler: (params: any, callerDid: string) => Promise<any>): void;
+    /**
+     * Remove an RPC handler.
+     */
+    offInvoke(method: string): void;
+    /** @internal Start listening for RPC requests and responses */
+    private _ensureRpcListener;
+    /**
+     * Send a message directly to a peer's webhook endpoint, bypassing the relay entirely.
+     * The relay never sees the message — true peer-to-peer encrypted delivery.
+     *
+     * Falls back to relay-based send if direct delivery fails.
+     *
+     * @example
+     * ```ts
+     * // Try direct first, fall back to relay
+     * const result = await agent.sendDirect('did:voidly:peer', 'Hello P2P!');
+     * console.log(result.direct); // true if delivered directly, false if via relay
+     * ```
+     */
+    sendDirect(recipientDid: string, message: string, options?: {
+        contentType?: string;
+        messageType?: string;
+        threadId?: string;
+        ttl?: number;
+    }): Promise<SendResult & {
+        direct: boolean;
+    }>;
+    /**
+     * Enable cover traffic — sends encrypted noise at random intervals.
+     * Makes real messages indistinguishable from cover traffic for any observer
+     * monitoring message timing and frequency.
+     *
+     * Cover messages are encrypted and padded identically to real messages.
+     * The relay cannot distinguish them from real traffic.
+     *
+     * @example
+     * ```ts
+     * // Send noise every ~30s (randomized ±50%)
+     * agent.enableCoverTraffic({ intervalMs: 30000 });
+     *
+     * // Stop cover traffic
+     * agent.disableCoverTraffic();
+     * ```
+     */
+    enableCoverTraffic(options?: {
+        intervalMs?: number;
+    }): void;
+    /**
+     * Disable cover traffic.
+     */
+    disableCoverTraffic(): void;
+    /**
+     * Fetch from primary relay with fallback to alternate relays.
+     * Unlike _timedFetch which only hits one URL, this tries all known relays.
+     * @internal
+     */
+    private _resilientFetch;
     /**
      * Start or resume a conversation with another agent.
      * Automatically manages thread IDs, message history, and reply chains.

package/dist/index.d.ts

@@ -28,6 +28,12 @@ interface AgentProfile {
     encryption_public_key: string;
     /** ML-KEM-768 public key (base64, 1184 bytes) — present if agent supports PQ */
     mlkem_public_key?: string;
+    /** X3DH signed prekey bundle — enables async key agreement with offline agents */
+    signed_prekey?: {
+        public_key: string;
+        signature: string;
+        id: number;
+    };
     capabilities: string[];
     message_count: number;
 }
@@ -71,6 +77,14 @@ interface VoidlyAgentConfig {
     timeout?: number;
     /** Enable post-quantum hybrid encryption — ML-KEM-768 + X25519 (default: true) */
     postQuantum?: boolean;
+    /** Enable deniable messaging — HMAC authentication instead of Ed25519 signatures (default: false) */
+    deniable?: boolean;
+    /** Enable Double Ratchet with DH ratchet for post-compromise recovery (default: true) */
+    doubleRatchet?: boolean;
+    /** Random delay range in ms before sending (metadata timing protection, default: 0 = disabled) */
+    jitterMs?: number;
+    /** Use long-poll for listen() instead of short-interval polling (default: true) */
+    longPoll?: boolean;
 }
 interface ListenOptions {
     /** Milliseconds between polls (default: 2000, min: 500) */
@@ -151,8 +165,14 @@ declare class VoidlyAgent {
     private requireSignatures;
     private timeout;
     private postQuantum;
+    private deniable;
+    private doubleRatchet;
+    private jitterMs;
+    private longPoll;
     private mlkemPublicKey;
     private mlkemSecretKey;
+    private _signedPrekey;
+    private _signedPrekeyId;
     private _pinnedDids;
     private _listeners;
     private _conversations;
@@ -161,6 +181,10 @@ declare class VoidlyAgent {
     private _identityCache;
     private _seenMessageIds;
     private _decryptFailCount;
+    private _rpcHandlers;
+    private _rpcPending;
+    private _coverTrafficTimer;
+    private _rpcListener;
     private constructor();
     /**
      * Register a new agent on the Voidly relay.
@@ -184,9 +208,17 @@ declare class VoidlyAgent {
             sendStep: number;
             recvChainKey: string;
             recvStep: number;
+            rootKey?: string;
+            dhSendSecretKey?: string;
+            dhSendPublicKey?: string;
+            dhRecvPubKey?: string;
+            prevSendStep?: number;
         }>;
         mlkemPublicKey?: string;
         mlkemSecretKey?: string;
+        signedPrekeySecret?: string;
+        signedPrekeyPublic?: string;
+        signedPrekeyId?: number;
     }, config?: VoidlyAgentConfig): VoidlyAgent;
     /**
      * Export credentials for persistence.
@@ -204,9 +236,17 @@ declare class VoidlyAgent {
             sendStep: number;
             recvChainKey: string;
             recvStep: number;
+            rootKey?: string;
+            dhSendSecretKey?: string;
+            dhSendPublicKey?: string;
+            dhRecvPubKey?: string;
+            prevSendStep?: number;
         }>;
         mlkemPublicKey?: string;
         mlkemSecretKey?: string;
+        signedPrekeySecret?: string;
+        signedPrekeyPublic?: string;
+        signedPrekeyId?: number;
     };
     /**
      * Get the number of messages that failed to decrypt.
@@ -836,6 +876,82 @@ declare class VoidlyAgent {
         status: string;
         warning?: string;
     }>;
+    /**
+     * Upload prekey bundle for X3DH async key agreement.
+     * Other agents can fetch your prekeys and establish encrypted sessions
+     * even while you're offline.
+     *
+     * @param count Number of one-time prekeys to upload (default: 20)
+     */
+    uploadPrekeys(count?: number): Promise<{
+        uploaded: number;
+        signed_prekey_updated: boolean;
+    }>;
+    /**
+     * Fetch another agent's prekey bundle for X3DH key agreement.
+     * Use this to establish an encrypted session with an offline agent.
+     */
+    fetchPrekeys(did: string): Promise<{
+        identity_key: string;
+        signing_key: string;
+        signed_prekey: {
+            public_key: string;
+            signature: string;
+            id: number;
+        } | null;
+        one_time_prekey: {
+            id: number;
+            public_key: string;
+        } | null;
+        mlkem_public_key: string | null;
+    } | null>;
+    /**
+     * Create a channel with client-side encryption.
+     * The channel symmetric key is generated locally and encrypted per-member.
+     * The relay NEVER sees the plaintext channel key — true E2E for groups.
+     */
+    createEncryptedChannel(options: {
+        name: string;
+        description?: string;
+        topic?: string;
+        private?: boolean;
+    }): Promise<{
+        id: string;
+        name: string;
+        channelKey: Uint8Array;
+    }>;
+    /**
+     * Post a client-side encrypted message to a channel.
+     * Uses the channel's shared symmetric key — relay never sees plaintext.
+     *
+     * @param channelId Channel ID
+     * @param message Plaintext message
+     * @param channelKey 32-byte symmetric channel key (from createEncryptedChannel or received via invite)
+     */
+    postEncrypted(channelId: string, message: string, channelKey: Uint8Array): Promise<{
+        id: string;
+    }>;
+    /**
+     * Read and decrypt channel messages using client-side channel key.
+     * Ignores server-side encryption entirely — true E2E.
+     *
+     * @param channelId Channel ID
+     * @param channelKey 32-byte symmetric channel key
+     */
+    readEncrypted(channelId: string, channelKey: Uint8Array, options?: {
+        since?: string;
+        before?: string;
+        limit?: number;
+    }): Promise<{
+        messages: Array<{
+            id: string;
+            from: string;
+            content: string;
+            timestamp: string;
+            signatureValid: boolean;
+        }>;
+        count: number;
+    }>;
     /**
      * Listen for incoming messages with an event-driven callback.
      * Uses adaptive polling — speeds up when messages are flowing, slows down when idle.
@@ -884,6 +1000,100 @@ declare class VoidlyAgent {
      * Stop all active listeners. Useful for clean shutdown.
      */
     stopAll(): void;
+    /**
+     * Invoke a function on a remote agent. Synchronous RPC over encrypted messaging.
+     * The remote agent must have registered a handler via `onInvoke()`.
+     *
+     * @example
+     * ```ts
+     * // Call a translator agent
+     * const result = await agent.invoke('did:voidly:translator', 'translate', {
+     *   text: 'Hello, world!',
+     *   to: 'ja',
+     * });
+     * console.log(result.translation); // こんにちは
+     *
+     * // With timeout
+     * const data = await agent.invoke(peerDid, 'analyze', { url: '...' }, 15000);
+     * ```
+     */
+    invoke(targetDid: string, method: string, params?: any, timeoutMs?: number): Promise<any>;
+    /**
+     * Register a handler for incoming RPC invocations.
+     * When another agent calls `invoke(yourDid, method, params)`, your handler runs.
+     *
+     * @example
+     * ```ts
+     * // Register a translation capability
+     * agent.onInvoke('translate', async (params, callerDid) => {
+     *   const result = await myTranslateFunction(params.text, params.to);
+     *   return { translation: result };
+     * });
+     *
+     * // Register a search capability
+     * agent.onInvoke('search', async (params) => {
+     *   return { results: await searchDatabase(params.query) };
+     * });
+     * ```
+     */
+    onInvoke(method: string, handler: (params: any, callerDid: string) => Promise<any>): void;
+    /**
+     * Remove an RPC handler.
+     */
+    offInvoke(method: string): void;
+    /** @internal Start listening for RPC requests and responses */
+    private _ensureRpcListener;
+    /**
+     * Send a message directly to a peer's webhook endpoint, bypassing the relay entirely.
+     * The relay never sees the message — true peer-to-peer encrypted delivery.
+     *
+     * Falls back to relay-based send if direct delivery fails.
+     *
+     * @example
+     * ```ts
+     * // Try direct first, fall back to relay
+     * const result = await agent.sendDirect('did:voidly:peer', 'Hello P2P!');
+     * console.log(result.direct); // true if delivered directly, false if via relay
+     * ```
+     */
+    sendDirect(recipientDid: string, message: string, options?: {
+        contentType?: string;
+        messageType?: string;
+        threadId?: string;
+        ttl?: number;
+    }): Promise<SendResult & {
+        direct: boolean;
+    }>;
+    /**
+     * Enable cover traffic — sends encrypted noise at random intervals.
+     * Makes real messages indistinguishable from cover traffic for any observer
+     * monitoring message timing and frequency.
+     *
+     * Cover messages are encrypted and padded identically to real messages.
+     * The relay cannot distinguish them from real traffic.
+     *
+     * @example
+     * ```ts
+     * // Send noise every ~30s (randomized ±50%)
+     * agent.enableCoverTraffic({ intervalMs: 30000 });
+     *
+     * // Stop cover traffic
+     * agent.disableCoverTraffic();
+     * ```
+     */
+    enableCoverTraffic(options?: {
+        intervalMs?: number;
+    }): void;
+    /**
+     * Disable cover traffic.
+     */
+    disableCoverTraffic(): void;
+    /**
+     * Fetch from primary relay with fallback to alternate relays.
+     * Unlike _timedFetch which only hits one URL, this tries all known relays.
+     * @internal
+     */
+    private _resilientFetch;
     /**
      * Start or resume a conversation with another agent.
      * Automatically manages thread IDs, message history, and reply chains.