@voidly/agent-sdk 2.1.0 → 3.0.0

package/dist/index.d.mts

@@ -8,7 +8,7 @@ export { decodeBase64, decodeUTF8, encodeBase64, encodeUTF8 } from 'tweetnacl-ut
  * All encryption and decryption happens CLIENT-SIDE.
  * The Voidly relay server NEVER sees private keys or plaintext.
  *
- * Crypto: X25519 key exchange + XSalsa20-Poly1305 + Ed25519 signatures
+ * Crypto: X25519 + ML-KEM-768 hybrid key exchange, XSalsa20-Poly1305, Ed25519 signatures
  * Identity: did:voidly:{base58-encoded-ed25519-pubkey}
  */
 
@@ -17,12 +17,23 @@ interface AgentIdentity {
     apiKey: string;
     signingKeyPair: nacl.SignKeyPair;
     encryptionKeyPair: nacl.BoxKeyPair;
+    /** ML-KEM-768 post-quantum keypair (optional — enables hybrid PQ encryption) */
+    mlkemPublicKey?: Uint8Array;
+    mlkemSecretKey?: Uint8Array;
 }
 interface AgentProfile {
     did: string;
     name: string | null;
     signing_public_key: string;
     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;
 }
@@ -64,6 +75,16 @@ interface VoidlyAgentConfig {
     requireSignatures?: boolean;
     /** Request timeout in milliseconds (default: 30000) */
     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) */
@@ -143,6 +164,15 @@ declare class VoidlyAgent {
     private sealedSender;
     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;
@@ -169,6 +199,22 @@ declare class VoidlyAgent {
         apiKey: string;
         signingSecretKey: string;
         encryptionSecretKey: string;
+        ratchetStates?: Record<string, {
+            sendChainKey: string;
+            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.
@@ -181,6 +227,22 @@ declare class VoidlyAgent {
         encryptionSecretKey: string;
         signingPublicKey: string;
         encryptionPublicKey: string;
+        ratchetStates?: Record<string, {
+            sendChainKey: string;
+            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.
@@ -810,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.
@@ -878,6 +1016,8 @@ declare class VoidlyAgent {
      * ```
      */
     conversation(peerDid: string, threadId?: string): Conversation;
+    /** @internal Fetch with timeout via AbortController */
+    private _timedFetch;
     /** @internal Auto-pin keys on first contact (TOFU) */
     private _autoPinKeys;
     /** @internal Fetch with exponential backoff retry */

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export { decodeBase64, decodeUTF8, encodeBase64, encodeUTF8 } from 'tweetnacl-ut
  * All encryption and decryption happens CLIENT-SIDE.
  * The Voidly relay server NEVER sees private keys or plaintext.
  *
- * Crypto: X25519 key exchange + XSalsa20-Poly1305 + Ed25519 signatures
+ * Crypto: X25519 + ML-KEM-768 hybrid key exchange, XSalsa20-Poly1305, Ed25519 signatures
  * Identity: did:voidly:{base58-encoded-ed25519-pubkey}
  */
 
@@ -17,12 +17,23 @@ interface AgentIdentity {
     apiKey: string;
     signingKeyPair: nacl.SignKeyPair;
     encryptionKeyPair: nacl.BoxKeyPair;
+    /** ML-KEM-768 post-quantum keypair (optional — enables hybrid PQ encryption) */
+    mlkemPublicKey?: Uint8Array;
+    mlkemSecretKey?: Uint8Array;
 }
 interface AgentProfile {
     did: string;
     name: string | null;
     signing_public_key: string;
     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;
 }
@@ -64,6 +75,16 @@ interface VoidlyAgentConfig {
     requireSignatures?: boolean;
     /** Request timeout in milliseconds (default: 30000) */
     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) */
@@ -143,6 +164,15 @@ declare class VoidlyAgent {
     private sealedSender;
     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;
@@ -169,6 +199,22 @@ declare class VoidlyAgent {
         apiKey: string;
         signingSecretKey: string;
         encryptionSecretKey: string;
+        ratchetStates?: Record<string, {
+            sendChainKey: string;
+            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.
@@ -181,6 +227,22 @@ declare class VoidlyAgent {
         encryptionSecretKey: string;
         signingPublicKey: string;
         encryptionPublicKey: string;
+        ratchetStates?: Record<string, {
+            sendChainKey: string;
+            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.
@@ -810,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.
@@ -878,6 +1016,8 @@ declare class VoidlyAgent {
      * ```
      */
     conversation(peerDid: string, threadId?: string): Conversation;
+    /** @internal Fetch with timeout via AbortController */
+    private _timedFetch;
     /** @internal Auto-pin keys on first contact (TOFU) */
     private _autoPinKeys;
     /** @internal Fetch with exponential backoff retry */