@kadi.build/core 0.13.0 → 0.15.0

package/src/client.ts

@@ -61,6 +61,7 @@ import { loadStdioTransport } from './transports/stdio.js';
 import { loadBrokerTransport } from './transports/broker.js';
 import { AgentJsonManager } from './agent-json.js';
 import { ProcessManager } from './process-manager.js';
+import { CryptoService } from './crypto-service.js';
 
 // ═══════════════════════════════════════════════════════════════
 // CONSTANTS
@@ -206,12 +207,18 @@ export class KadiClient {
   /** Registered disconnect hooks */
   private readonly disconnectHooks: Array<() => Promise<void>> = [];
 
+  /** Registered reconnect hooks */
+  private readonly reconnectHooks: Array<(brokerName: string) => void | Promise<void>> = [];
+
   /** Lazy-initialized AgentJsonManager */
   private _agentJson: AgentJsonManager | null = null;
 
   /** Lazy-initialized ProcessManager */
   private _processes: ProcessManager | null = null;
 
+  /** Lazy-initialized CryptoService */
+  private _crypto: CryptoService | null = null;
+
   // ─────────────────────────────────────────────────────────────
   // IDENTITY (single keypair shared across all broker connections)
   // ─────────────────────────────────────────────────────────────
@@ -1698,9 +1705,36 @@ export class KadiClient {
       // Finalize connection (heartbeat + status)
       this.finalizeConnection(state);
 
+      // Re-subscribe event patterns that were active before disconnect.
+      // cleanupBroker() cleared subscribedPatterns but preserved eventHandlers,
+      // so we replay broker-side subscriptions for every pattern that still has handlers.
+      if (state.eventHandlers.size > 0) {
+        const patterns = [...state.eventHandlers.keys()];
+        console.error(`[KADI] Re-subscribing ${patterns.length} event pattern(s) on broker "${state.name}"`);
+        for (const pattern of patterns) {
+          try {
+            await this.sendRequest(state, protocol.eventSubscribe(this.nextRequestId++, pattern));
+            state.subscribedPatterns.add(pattern);
+          } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`[KADI] Failed to re-subscribe "${pattern}" on broker "${state.name}": ${msg}`);
+          }
+        }
+      }
+
       // Success!
       console.error(`[KADI] Reconnected to broker "${state.name}" after ${state.reconnectAttempts} attempts`);
       state.reconnectAttempts = 0;
+
+      // Fire reconnect hooks (best-effort, don't let a failing hook break reconnect)
+      for (const hook of this.reconnectHooks) {
+        try {
+          await hook(state.name);
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          console.error(`[KADI] Reconnect hook error for broker "${state.name}": ${msg}`);
+        }
+      }
     } catch (error) {
       // Log the error and try again
       const message = error instanceof Error ? error.message : String(error);
@@ -1722,6 +1756,26 @@ export class KadiClient {
     this.disconnectHooks.push(hook);
   }
 
+  /**
+   * Register a hook to run after a successful broker reconnection.
+   *
+   * Event subscriptions are automatically re-established on reconnect,
+   * so most agents won't need this. Use it for additional recovery logic:
+   * re-fetching state, logging, sending a "I'm back" message, etc.
+   *
+   * @param hook - Called with the broker name after each successful reconnect.
+   *
+   * @example
+   * ```typescript
+   * client.onReconnect(async (brokerName) => {
+   *   console.log(`Reconnected to ${brokerName} — re-initializing state`);
+   * });
+   * ```
+   */
+  onReconnect(hook: (brokerName: string) => void | Promise<void>): void {
+    this.reconnectHooks.push(hook);
+  }
+
   /**
    * Disconnect from broker(s) and run registered cleanup hooks.
    *
@@ -2481,6 +2535,35 @@ export class KadiClient {
     return this._processes;
   }
 
+  // ─────────────────────────────────────────────────────────────
+  // CRYPTO SERVICE
+  // ─────────────────────────────────────────────────────────────
+
+  /**
+   * Access the CryptoService for encrypting/decrypting messages.
+   *
+   * Lazily created on first access. Uses NaCl sealed boxes (X25519 +
+   * XSalsa20-Poly1305) derived from this agent's Ed25519 identity keys.
+   *
+   * @example
+   * ```typescript
+   * // Encrypt a message for another agent
+   * const encrypted = client.crypto.encryptFor('secret', otherAgent.publicKey);
+   *
+   * // Decrypt a message sent to this agent
+   * const plaintext = client.crypto.decrypt(encrypted);
+   *
+   * // Get this agent's encryption public key (to share with others)
+   * const pubKey = client.crypto.publicKey;
+   * ```
+   */
+  get crypto(): CryptoService {
+    if (!this._crypto) {
+      this._crypto = new CryptoService(this._privateKey, this._publicKeyBase64);
+    }
+    return this._crypto;
+  }
+
   // ─────────────────────────────────────────────────────────────
   // UTILITY
   // ─────────────────────────────────────────────────────────────

package/src/crypto-service.ts

@@ -0,0 +1,169 @@
+/**
+ * CryptoService — High-level encryption/decryption for KADI agents.
+ *
+ * Provides NaCl sealed-box encryption using the agent's Ed25519 identity
+ * keys (converted to X25519). Sealed boxes allow anyone with the recipient's
+ * public key to encrypt a message that only the recipient can decrypt.
+ *
+ * This is a stateless wrapper around tweetnacl-sealedbox-js, using the
+ * key conversion utilities already in crypto.ts.
+ *
+ * @example
+ * ```typescript
+ * // Agent A encrypts a message for Agent B
+ * const encrypted = agentA.crypto.encryptFor('secret data', agentB.publicKey);
+ *
+ * // Agent B decrypts
+ * const plaintext = agentB.crypto.decrypt(encrypted);
+ * ```
+ *
+ * @module crypto-service
+ */
+
+// @ts-expect-error - tweetnacl-sealedbox-js has no type declarations
+import sealedbox from 'tweetnacl-sealedbox-js';
+
+import {
+  convertToEncryptionKey,
+  convertToEncryptionKeyPair,
+  type EncryptionKeyPair,
+} from './crypto.js';
+
+/**
+ * High-level encryption/decryption service for inter-agent communication.
+ *
+ * Uses NaCl sealed boxes (X25519 + XSalsa20-Poly1305 authenticated encryption).
+ * Only the intended recipient can decrypt messages.
+ */
+export class CryptoService {
+  private readonly _privateKey: Buffer;
+  private readonly _publicKeyBase64: string;
+
+  /** Cached key pairs to avoid repeated conversions */
+  private _encryptionKeyPair: EncryptionKeyPair | null = null;
+  private _publicKeyX25519Base64: string | null = null;
+
+  /**
+   * @param privateKey - Ed25519 private key in PKCS8 DER format
+   * @param publicKeyBase64 - Base64-encoded Ed25519 public key (SPKI DER format)
+   */
+  constructor(privateKey: Buffer, publicKeyBase64: string) {
+    this._privateKey = privateKey;
+    this._publicKeyBase64 = publicKeyBase64;
+  }
+
+  /**
+   * This agent's X25519 encryption public key (base64).
+   *
+   * Share this with anyone who needs to encrypt messages for this agent.
+   * The key is derived from the agent's Ed25519 identity key.
+   */
+  get publicKey(): string {
+    if (!this._publicKeyX25519Base64) {
+      const raw = convertToEncryptionKey(this._publicKeyBase64);
+      this._publicKeyX25519Base64 = Buffer.from(raw).toString('base64');
+    }
+    return this._publicKeyX25519Base64;
+  }
+
+  /**
+   * This agent's Ed25519 identity public key (SPKI DER, base64).
+   *
+   * This is the same key used for broker authentication and agent ID derivation.
+   */
+  get identityPublicKey(): string {
+    return this._publicKeyBase64;
+  }
+
+  /**
+   * Encrypt a message so only the specified recipient can decrypt it.
+   *
+   * Uses NaCl sealed box: the sender generates an ephemeral keypair internally.
+   * The recipient cannot determine who sent the message (anonymous encryption).
+   * For authentication, use a separate mechanism (e.g., API tokens, signatures).
+   *
+   * @param plaintext - The string to encrypt
+   * @param recipientPublicKey - Recipient's public key. Accepts either:
+   *   - Ed25519 SPKI DER base64 (the standard `client.publicKey` format) — auto-converted to X25519
+   *   - Raw X25519 base64 (32 bytes when decoded) — used directly
+   * @returns Base64-encoded ciphertext (NaCl sealed box)
+   *
+   * @example
+   * ```typescript
+   * // Encrypt for another agent using their Ed25519 identity key
+   * const encrypted = client.crypto.encryptFor(
+   *   JSON.stringify({ API_KEY: 'sk-123', DB_PASS: 'hunter2' }),
+   *   otherAgent.publicKey
+   * );
+   * ```
+   */
+  encryptFor(plaintext: string, recipientPublicKey: string): string {
+    const x25519Key = this.resolveToX25519(recipientPublicKey);
+    const message = new TextEncoder().encode(plaintext);
+    const sealed = sealedbox.seal(message, x25519Key);
+    return Buffer.from(sealed).toString('base64');
+  }
+
+  /**
+   * Decrypt a message that was encrypted for this agent.
+   *
+   * The message must have been encrypted using this agent's public key
+   * (either via `encryptFor()` or directly with NaCl sealed box).
+   *
+   * @param ciphertext - Base64-encoded NaCl sealed box ciphertext
+   * @returns The decrypted plaintext string
+   * @throws Error if decryption fails (wrong key, corrupted data, or tampered message)
+   *
+   * @example
+   * ```typescript
+   * const plaintext = client.crypto.decrypt(encryptedBase64);
+   * const secrets = JSON.parse(plaintext);
+   * ```
+   */
+  decrypt(ciphertext: string): string {
+    const keyPair = this.getEncryptionKeyPair();
+    const sealed = new Uint8Array(Buffer.from(ciphertext, 'base64'));
+
+    const decrypted = sealedbox.open(sealed, keyPair.publicKey, keyPair.secretKey);
+
+    if (!decrypted) {
+      throw new Error(
+        'Decryption failed: invalid ciphertext, wrong key, or tampered message'
+      );
+    }
+
+    return new TextDecoder().decode(decrypted);
+  }
+
+  // ─────────────────────────────────────────────────────────────
+  // INTERNAL
+  // ─────────────────────────────────────────────────────────────
+
+  /**
+   * Resolve a public key to X25519 format.
+   * Handles both Ed25519 SPKI DER base64 and raw X25519 base64.
+   */
+  private resolveToX25519(publicKey: string): Uint8Array {
+    const raw = Buffer.from(publicKey, 'base64');
+
+    // Raw X25519 key is exactly 32 bytes
+    // SPKI DER Ed25519 key is 44 bytes (12-byte header + 32-byte key)
+    if (raw.length === 32) {
+      return new Uint8Array(raw);
+    }
+
+    // Assume SPKI DER format — convert Ed25519 → X25519
+    return convertToEncryptionKey(publicKey);
+  }
+
+  /** Get or create cached encryption key pair */
+  private getEncryptionKeyPair(): EncryptionKeyPair {
+    if (!this._encryptionKeyPair) {
+      this._encryptionKeyPair = convertToEncryptionKeyPair(
+        this._privateKey,
+        this._publicKeyBase64
+      );
+    }
+    return this._encryptionKeyPair;
+  }
+}

package/src/index.ts

@@ -119,6 +119,9 @@ export { AgentJsonManager } from './agent-json.js';
 // Process manager
 export { ProcessManager, ManagedProcess } from './process-manager.js';
 
+// Crypto service (sealed-box encryption for inter-agent communication)
+export { CryptoService } from './crypto-service.js';
+
 // Dot-path utilities
 export { getByPath, setByPath, deleteByPath, deepMerge } from './utils.js';