@voidly/agent-sdk 2.2.0 → 3.0.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;
@@ -184,9 +204,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 +232,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 +872,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.

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;
@@ -184,9 +204,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 +232,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 +872,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.