@voidly/agent-sdk 2.0.0 → 2.2.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,17 @@ 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;
     capabilities: string[];
     message_count: number;
 }
@@ -60,6 +65,12 @@ interface VoidlyAgentConfig {
     padding?: boolean;
     /** Enable sealed sender — hide sender DID from relay metadata (default: false) */
     sealedSender?: boolean;
+    /** Reject messages with invalid signatures (default: false — returns signatureValid: false) */
+    requireSignatures?: boolean;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Enable post-quantum hybrid encryption — ML-KEM-768 + X25519 (default: true) */
+    postQuantum?: boolean;
 }
 interface ListenOptions {
     /** Milliseconds between polls (default: 2000, min: 500) */
@@ -137,11 +148,19 @@ declare class VoidlyAgent {
     private fallbackRelays;
     private paddingEnabled;
     private sealedSender;
+    private requireSignatures;
+    private timeout;
+    private postQuantum;
+    private mlkemPublicKey;
+    private mlkemSecretKey;
     private _pinnedDids;
     private _listeners;
     private _conversations;
     private _offlineQueue;
     private _ratchetStates;
+    private _identityCache;
+    private _seenMessageIds;
+    private _decryptFailCount;
     private constructor();
     /**
      * Register a new agent on the Voidly relay.
@@ -160,6 +179,14 @@ declare class VoidlyAgent {
         apiKey: string;
         signingSecretKey: string;
         encryptionSecretKey: string;
+        ratchetStates?: Record<string, {
+            sendChainKey: string;
+            sendStep: number;
+            recvChainKey: string;
+            recvStep: number;
+        }>;
+        mlkemPublicKey?: string;
+        mlkemSecretKey?: string;
     }, config?: VoidlyAgentConfig): VoidlyAgent;
     /**
      * Export credentials for persistence.
@@ -172,7 +199,26 @@ declare class VoidlyAgent {
         encryptionSecretKey: string;
         signingPublicKey: string;
         encryptionPublicKey: string;
+        ratchetStates?: Record<string, {
+            sendChainKey: string;
+            sendStep: number;
+            recvChainKey: string;
+            recvStep: number;
+        }>;
+        mlkemPublicKey?: string;
+        mlkemSecretKey?: string;
     };
+    /**
+     * Get the number of messages that failed to decrypt.
+     * Useful for detecting key mismatches, attacks, or corruption.
+     */
+    get decryptFailCount(): number;
+    /**
+     * Generate a did:key identifier from this agent's Ed25519 signing key.
+     * did:key is a W3C standard — interoperable across systems.
+     * Format: did:key:z6Mk{base58-multicodec-ed25519-pubkey}
+     */
+    get didKey(): string;
     /**
      * Send an E2E encrypted message with hardened security.
      * Encryption happens locally — the relay NEVER sees plaintext or private keys.
@@ -644,7 +690,8 @@ declare class VoidlyAgent {
     }, signingPublicKey: string): boolean;
     /**
      * Store an encrypted key-value pair in persistent memory.
-     * Values are encrypted with a key derived from your API key — only you can read them.
+     * Values are encrypted CLIENT-SIDE with nacl.secretbox before sending to relay.
+     * The relay never sees plaintext values — true E2E encrypted storage.
      */
     memorySet(namespace: string, key: string, value: unknown, options?: {
         valueType?: string;
@@ -657,7 +704,7 @@ declare class VoidlyAgent {
     }>;
     /**
      * Retrieve a value from persistent memory.
-     * Decrypted server-side using your API key derivation.
+     * Decrypted CLIENT-SIDE — relay never sees plaintext.
      */
     memoryGet(namespace: string, key: string): Promise<{
         namespace: string;
@@ -857,6 +904,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,17 @@ 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;
     capabilities: string[];
     message_count: number;
 }
@@ -60,6 +65,12 @@ interface VoidlyAgentConfig {
     padding?: boolean;
     /** Enable sealed sender — hide sender DID from relay metadata (default: false) */
     sealedSender?: boolean;
+    /** Reject messages with invalid signatures (default: false — returns signatureValid: false) */
+    requireSignatures?: boolean;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Enable post-quantum hybrid encryption — ML-KEM-768 + X25519 (default: true) */
+    postQuantum?: boolean;
 }
 interface ListenOptions {
     /** Milliseconds between polls (default: 2000, min: 500) */
@@ -137,11 +148,19 @@ declare class VoidlyAgent {
     private fallbackRelays;
     private paddingEnabled;
     private sealedSender;
+    private requireSignatures;
+    private timeout;
+    private postQuantum;
+    private mlkemPublicKey;
+    private mlkemSecretKey;
     private _pinnedDids;
     private _listeners;
     private _conversations;
     private _offlineQueue;
     private _ratchetStates;
+    private _identityCache;
+    private _seenMessageIds;
+    private _decryptFailCount;
     private constructor();
     /**
      * Register a new agent on the Voidly relay.
@@ -160,6 +179,14 @@ declare class VoidlyAgent {
         apiKey: string;
         signingSecretKey: string;
         encryptionSecretKey: string;
+        ratchetStates?: Record<string, {
+            sendChainKey: string;
+            sendStep: number;
+            recvChainKey: string;
+            recvStep: number;
+        }>;
+        mlkemPublicKey?: string;
+        mlkemSecretKey?: string;
     }, config?: VoidlyAgentConfig): VoidlyAgent;
     /**
      * Export credentials for persistence.
@@ -172,7 +199,26 @@ declare class VoidlyAgent {
         encryptionSecretKey: string;
         signingPublicKey: string;
         encryptionPublicKey: string;
+        ratchetStates?: Record<string, {
+            sendChainKey: string;
+            sendStep: number;
+            recvChainKey: string;
+            recvStep: number;
+        }>;
+        mlkemPublicKey?: string;
+        mlkemSecretKey?: string;
     };
+    /**
+     * Get the number of messages that failed to decrypt.
+     * Useful for detecting key mismatches, attacks, or corruption.
+     */
+    get decryptFailCount(): number;
+    /**
+     * Generate a did:key identifier from this agent's Ed25519 signing key.
+     * did:key is a W3C standard — interoperable across systems.
+     * Format: did:key:z6Mk{base58-multicodec-ed25519-pubkey}
+     */
+    get didKey(): string;
     /**
      * Send an E2E encrypted message with hardened security.
      * Encryption happens locally — the relay NEVER sees plaintext or private keys.
@@ -644,7 +690,8 @@ declare class VoidlyAgent {
     }, signingPublicKey: string): boolean;
     /**
      * Store an encrypted key-value pair in persistent memory.
-     * Values are encrypted with a key derived from your API key — only you can read them.
+     * Values are encrypted CLIENT-SIDE with nacl.secretbox before sending to relay.
+     * The relay never sees plaintext values — true E2E encrypted storage.
      */
     memorySet(namespace: string, key: string, value: unknown, options?: {
         valueType?: string;
@@ -657,7 +704,7 @@ declare class VoidlyAgent {
     }>;
     /**
      * Retrieve a value from persistent memory.
-     * Decrypted server-side using your API key derivation.
+     * Decrypted CLIENT-SIDE — relay never sees plaintext.
      */
     memoryGet(namespace: string, key: string): Promise<{
         namespace: string;
@@ -857,6 +904,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 */