@voidly/agent-sdk 1.9.0 → 2.1.0

package/dist/index.d.mts

@@ -54,6 +54,16 @@ interface VoidlyAgentConfig {
     autoPin?: boolean;
     /** Default retry attempts for send() (default: 3) */
     retries?: number;
+    /** Fallback relays — if primary fails, try these in order */
+    fallbackRelays?: string[];
+    /** Enable message padding to resist traffic analysis (default: true) */
+    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;
 }
 interface ListenOptions {
     /** Milliseconds between polls (default: 2000, min: 500) */
@@ -128,9 +138,19 @@ declare class VoidlyAgent {
     private baseUrl;
     private autoPin;
     private defaultRetries;
+    private fallbackRelays;
+    private paddingEnabled;
+    private sealedSender;
+    private requireSignatures;
+    private timeout;
     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.
@@ -163,13 +183,28 @@ declare class VoidlyAgent {
         encryptionPublicKey: string;
     };
     /**
-     * Send an E2E encrypted message with automatic retry and transparent TOFU.
+     * 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.
      *
-     * Features:
+     * Security features:
+     * - **Message padding** — ciphertext padded to power-of-2 boundary (traffic analysis resistance)
+     * - **Hash ratchet** — per-conversation forward secrecy (compromise key[n] can't derive key[n-1])
+     * - **Sealed sender** — optionally hide sender DID from relay metadata
      * - **Auto-retry** with exponential backoff on transient failures
-     * - **Transparent TOFU** — automatically pins recipient keys on first contact
-     * - **Key verification** — warns if pinned keys have changed (potential MitM)
+     * - **Multi-relay fallback** — try backup relays if primary is down
+     * - **Offline queue** — queue messages if all relays fail
+     * - **Transparent TOFU** — auto-pin recipient keys on first contact
      */
     send(recipientDid: string, message: string, options?: {
         contentType?: string;
@@ -181,6 +216,10 @@ declare class VoidlyAgent {
         retries?: number;
         /** Skip auto key pinning for this message */
         skipPin?: boolean;
+        /** Force sealed sender for this message */
+        sealedSender?: boolean;
+        /** Disable padding for this message */
+        noPadding?: boolean;
     }): Promise<SendResult>;
     /**
      * Receive and decrypt messages. Decryption happens locally.
@@ -625,7 +664,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;
@@ -638,7 +678,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;
@@ -842,6 +882,28 @@ declare class VoidlyAgent {
     private _autoPinKeys;
     /** @internal Fetch with exponential backoff retry */
     private _fetchWithRetry;
+    /**
+     * Drain the offline message queue — retry sending queued messages.
+     * Call this when connectivity is restored.
+     * Returns: number of messages successfully sent.
+     */
+    drainQueue(): Promise<{
+        sent: number;
+        failed: number;
+        remaining: number;
+    }>;
+    /** Number of messages waiting in the offline queue */
+    get queueLength(): number;
+    /**
+     * Returns what the relay can and cannot see about this agent.
+     * Call this to understand your threat model. Total transparency.
+     */
+    threatModel(): {
+        relayCanSee: string[];
+        relayCannotSee: string[];
+        protections: string[];
+        gaps: string[];
+    };
 }
 /**
  * A conversation between two agents.

package/dist/index.d.ts

@@ -54,6 +54,16 @@ interface VoidlyAgentConfig {
     autoPin?: boolean;
     /** Default retry attempts for send() (default: 3) */
     retries?: number;
+    /** Fallback relays — if primary fails, try these in order */
+    fallbackRelays?: string[];
+    /** Enable message padding to resist traffic analysis (default: true) */
+    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;
 }
 interface ListenOptions {
     /** Milliseconds between polls (default: 2000, min: 500) */
@@ -128,9 +138,19 @@ declare class VoidlyAgent {
     private baseUrl;
     private autoPin;
     private defaultRetries;
+    private fallbackRelays;
+    private paddingEnabled;
+    private sealedSender;
+    private requireSignatures;
+    private timeout;
     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.
@@ -163,13 +183,28 @@ declare class VoidlyAgent {
         encryptionPublicKey: string;
     };
     /**
-     * Send an E2E encrypted message with automatic retry and transparent TOFU.
+     * 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.
      *
-     * Features:
+     * Security features:
+     * - **Message padding** — ciphertext padded to power-of-2 boundary (traffic analysis resistance)
+     * - **Hash ratchet** — per-conversation forward secrecy (compromise key[n] can't derive key[n-1])
+     * - **Sealed sender** — optionally hide sender DID from relay metadata
      * - **Auto-retry** with exponential backoff on transient failures
-     * - **Transparent TOFU** — automatically pins recipient keys on first contact
-     * - **Key verification** — warns if pinned keys have changed (potential MitM)
+     * - **Multi-relay fallback** — try backup relays if primary is down
+     * - **Offline queue** — queue messages if all relays fail
+     * - **Transparent TOFU** — auto-pin recipient keys on first contact
      */
     send(recipientDid: string, message: string, options?: {
         contentType?: string;
@@ -181,6 +216,10 @@ declare class VoidlyAgent {
         retries?: number;
         /** Skip auto key pinning for this message */
         skipPin?: boolean;
+        /** Force sealed sender for this message */
+        sealedSender?: boolean;
+        /** Disable padding for this message */
+        noPadding?: boolean;
     }): Promise<SendResult>;
     /**
      * Receive and decrypt messages. Decryption happens locally.
@@ -625,7 +664,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;
@@ -638,7 +678,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;
@@ -842,6 +882,28 @@ declare class VoidlyAgent {
     private _autoPinKeys;
     /** @internal Fetch with exponential backoff retry */
     private _fetchWithRetry;
+    /**
+     * Drain the offline message queue — retry sending queued messages.
+     * Call this when connectivity is restored.
+     * Returns: number of messages successfully sent.
+     */
+    drainQueue(): Promise<{
+        sent: number;
+        failed: number;
+        remaining: number;
+    }>;
+    /** Number of messages waiting in the offline queue */
+    get queueLength(): number;
+    /**
+     * Returns what the relay can and cannot see about this agent.
+     * Call this to understand your threat model. Total transparency.
+     */
+    threatModel(): {
+        relayCanSee: string[];
+        relayCannotSee: string[];
+        protections: string[];
+        gaps: string[];
+    };
 }
 /**
  * A conversation between two agents.