@kadi.build/core 0.3.4 → 0.5.0

package/dist/client.d.ts

@@ -14,7 +14,8 @@
  * - Explicit over implicit (no proxy magic)
  * - Readable, traceable code flow
  */
-import type { ClientConfig, BrokerState, ToolDefinition, ZodToolDefinition, ToolHandler, LoadedAbility, ToolExecutionBridge, RegisterToolOptions, LoadNativeOptions, LoadStdioOptions, LoadBrokerOptions, InvokeRemoteOptions, BrokerEventHandler, PublishOptions, SubscribeOptions, EmitOptions } from './types.js';
+import { type EncryptionKeyPair } from './crypto.js';
+import type { ClientConfig, ClientIdentity, BrokerState, ToolDefinition, ZodToolDefinition, ToolHandler, LoadedAbility, ToolExecutionBridge, RegisterToolOptions, LoadNativeOptions, LoadStdioOptions, LoadBrokerOptions, InvokeRemoteOptions, BrokerEventHandler, PublishOptions, SubscribeOptions, EmitOptions } from './types.js';
 /**
  * The main client for building KADI agents.
  *
@@ -58,7 +59,92 @@ export declare class KadiClient {
     private eventHandler;
     /** Whether we're serving via stdio (set by serve('stdio')) */
     private isServingStdio;
+    /** Ed25519 private key (DER format) - used for signing */
+    private readonly _privateKey;
+    /** Base64-encoded Ed25519 public key (SPKI DER format) */
+    private readonly _publicKeyBase64;
+    /** Deterministic agent ID: SHA256(publicKey).hex().substring(0, 16) */
+    private readonly _agentId;
     constructor(config: ClientConfig);
+    /**
+     * Get the client's cryptographic identity.
+     *
+     * Available immediately after construction (before connect).
+     * The same identity is used for all broker connections.
+     *
+     * @example
+     * ```typescript
+     * const client = new KadiClient({ name: 'my-agent' });
+     * console.log(client.identity);
+     * // { publicKey: 'MIIBIjAN...', agentId: 'a1b2c3d4e5f67890' }
+     * ```
+     */
+    get identity(): ClientIdentity;
+    /**
+     * Get the client's public key (base64-encoded SPKI DER format).
+     *
+     * This is the key used for Ed25519 authentication with brokers.
+     */
+    get publicKey(): string;
+    /**
+     * Get the client's agent ID.
+     *
+     * Derived deterministically from publicKey: SHA256(publicKey).hex().substring(0, 16)
+     * This is the same ID that brokers will assign during authentication.
+     */
+    get agentId(): string;
+    /**
+     * Get the client's X25519 encryption public key.
+     *
+     * This key is derived from the client's Ed25519 signing key and can be
+     * shared with others so they can encrypt messages that only this client
+     * can decrypt.
+     *
+     * Use this when you want others to send encrypted data to your agent.
+     *
+     * @example
+     * ```typescript
+     * // Agent shares its encryption public key
+     * await client.publish('secrets.request', {
+     *   agentId: client.agentId,
+     *   publicKey: client.publicKey,  // Ed25519 for identity
+     *   // The sender will use convertToEncryptionKey(publicKey) to encrypt
+     * });
+     * ```
+     */
+    get encryptionPublicKey(): Uint8Array;
+    /**
+     * Get the client's X25519 encryption key pair.
+     *
+     * This key pair is derived from the client's Ed25519 signing keys and can
+     * be used to decrypt messages that were encrypted with the client's
+     * encryption public key.
+     *
+     * Use this when you need to decrypt sealed box messages sent to your agent.
+     *
+     * @example
+     * ```typescript
+     * import nacl from 'tweetnacl';
+     * nacl.sealedbox = require('tweetnacl-sealedbox-js');
+     *
+     * // Decrypt a sealed box message
+     * const keyPair = client.encryptionKeyPair;
+     * const decrypted = nacl.sealedbox.open(
+     *   encrypted,
+     *   keyPair.publicKey,
+     *   keyPair.secretKey
+     * );
+     * ```
+     */
+    get encryptionKeyPair(): EncryptionKeyPair;
+    /**
+     * Get the agent name (from config).
+     */
+    get name(): string;
+    /**
+     * Get the agent version (from config).
+     */
+    get version(): string;
     /**
      * Connect to all configured brokers.
      * Call this after registering tools.
@@ -74,14 +160,16 @@ export declare class KadiClient {
      * Connect to a specific broker by name.
      *
      * Protocol:
-     * 1. Generate Ed25519 keypair
-     * 2. Open WebSocket connection
-     * 3. Send kadi.session.hello
-     * 4. Receive nonce from broker
-     * 5. Send kadi.session.authenticate with signed nonce
-     * 6. Receive agentId from broker
-     * 7. Register tools with broker
-     * 8. Start heartbeat
+     * 1. Open WebSocket connection
+     * 2. Send kadi.session.hello
+     * 3. Receive nonce from broker
+     * 4. Send kadi.session.authenticate with signed nonce (using client's identity)
+     * 5. Receive agentId from broker (should match client.agentId)
+     * 6. Register tools with broker
+     * 7. Start heartbeat
+     *
+     * Note: The keypair is generated once at client construction and shared
+     * across all broker connections, ensuring consistent identity.
      */
     private connectToBroker;
     private buildHelloMessage;
@@ -230,6 +318,45 @@ export declare class KadiClient {
      * ```
      */
     publish(channel: string, data: unknown, options?: PublishOptions): Promise<void>;
+    /**
+     * Request secrets from the deployer during agent startup.
+     *
+     * This implements the agent side of the "Trusted Introducer" pattern:
+     * 1. Check for KADI_DEPLOY_NONCE env var (set by deployer)
+     * 2. Subscribe to secrets.response.{agentId} channel
+     * 3. Publish request to secrets.request with nonce and public key
+     * 4. Wait for response from deployer (approved with encrypted secrets, or rejected)
+     * 5. If approved, decrypt using agent's encryption key pair
+     * 6. Set secrets in process.env
+     *
+     * The deployer (kadi deploy) stays connected after deployment and waits
+     * for this request. It verifies the nonce, prompts for approval, and
+     * either shares encrypted secrets or sends a rejection.
+     *
+     * @param options - Configuration options
+     * @returns Decrypted secrets as key-value pairs, or null if no secrets needed
+     * @throws KadiError if timeout waiting for secrets or decryption fails
+     *
+     * @example
+     * ```typescript
+     * const client = new KadiClient({ name: 'my-agent', ... });
+     * await client.connect();
+     *
+     * // Request secrets from deployer (throws if timeout)
+     * const secrets = await client.requestSecrets();
+     *
+     * if (secrets) {
+     *   console.log('Received secrets:', Object.keys(secrets));
+     *   // Secrets are also set in process.env
+     * }
+     *
+     * // With custom timeout
+     * const secrets = await client.requestSecrets({ timeout: 120000 });
+     * ```
+     */
+    requestSecrets(options?: {
+        timeout?: number;
+    }): Promise<Record<string, string> | null>;
     /**
      * Handle incoming request from broker (tool invocation).
      */
@@ -299,8 +426,8 @@ export declare class KadiClient {
     /**
      * Attempt to reconnect to the broker.
      *
-     * This reuses the existing keypair (agentId stays the same) and
-     * re-registers tools with the broker.
+     * Uses the client's identity (same keypair/agentId for all connections)
+     * and re-registers tools with the broker.
      *
      * On failure, schedules another attempt with increased delay.
      */

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/client.js

@@ -16,6 +16,9 @@
  */
 import { WebSocket } from 'ws';
 import * as crypto from 'crypto';
+import { convertToEncryptionKey, convertToEncryptionKeyPair, } from './crypto.js';
+// @ts-expect-error - tweetnacl-sealedbox-js doesn't have type definitions
+import sealedbox from 'tweetnacl-sealedbox-js';
 import { KadiError } from './errors.js';
 import { zodToJsonSchema, isZodSchema } from './zod.js';
 import { resolveAbilityEntry, resolveAbilityScript } from './lockfile.js';
@@ -144,6 +147,15 @@ export class KadiClient {
     /** Whether we're serving via stdio (set by serve('stdio')) */
     isServingStdio = false;
     // ─────────────────────────────────────────────────────────────
+    // IDENTITY (single keypair shared across all broker connections)
+    // ─────────────────────────────────────────────────────────────
+    /** Ed25519 private key (DER format) - used for signing */
+    _privateKey;
+    /** Base64-encoded Ed25519 public key (SPKI DER format) */
+    _publicKeyBase64;
+    /** Deterministic agent ID: SHA256(publicKey).hex().substring(0, 16) */
+    _agentId;
+    // ─────────────────────────────────────────────────────────────
     // CONSTRUCTOR
     // ─────────────────────────────────────────────────────────────
     constructor(config) {
@@ -153,6 +165,12 @@ export class KadiClient {
                 hint: 'Provide a name for your agent: new KadiClient({ name: "my-agent" })',
             });
         }
+        // Generate Ed25519 keypair once for consistent identity across all brokers
+        const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
+        this._privateKey = privateKey.export({ type: 'pkcs8', format: 'der' });
+        this._publicKeyBase64 = publicKey.export({ type: 'spki', format: 'der' }).toString('base64');
+        // Derive agentId using same algorithm as broker: SHA256(publicKey).hex().substring(0, 16)
+        this._agentId = crypto.createHash('sha256').update(this._publicKeyBase64).digest('hex').substring(0, 16);
         // Resolve configuration with defaults
         // Auto-select first broker as default if not specified (matches Python behavior)
         const brokers = config.brokers ?? {};
@@ -179,6 +197,108 @@ export class KadiClient {
         }
     }
     // ─────────────────────────────────────────────────────────────
+    // IDENTITY GETTERS
+    // ─────────────────────────────────────────────────────────────
+    /**
+     * Get the client's cryptographic identity.
+     *
+     * Available immediately after construction (before connect).
+     * The same identity is used for all broker connections.
+     *
+     * @example
+     * ```typescript
+     * const client = new KadiClient({ name: 'my-agent' });
+     * console.log(client.identity);
+     * // { publicKey: 'MIIBIjAN...', agentId: 'a1b2c3d4e5f67890' }
+     * ```
+     */
+    get identity() {
+        return {
+            publicKey: this._publicKeyBase64,
+            agentId: this._agentId,
+        };
+    }
+    /**
+     * Get the client's public key (base64-encoded SPKI DER format).
+     *
+     * This is the key used for Ed25519 authentication with brokers.
+     */
+    get publicKey() {
+        return this._publicKeyBase64;
+    }
+    /**
+     * Get the client's agent ID.
+     *
+     * Derived deterministically from publicKey: SHA256(publicKey).hex().substring(0, 16)
+     * This is the same ID that brokers will assign during authentication.
+     */
+    get agentId() {
+        return this._agentId;
+    }
+    // ─────────────────────────────────────────────────────────────
+    // ENCRYPTION KEY GETTERS
+    // ─────────────────────────────────────────────────────────────
+    /**
+     * Get the client's X25519 encryption public key.
+     *
+     * This key is derived from the client's Ed25519 signing key and can be
+     * shared with others so they can encrypt messages that only this client
+     * can decrypt.
+     *
+     * Use this when you want others to send encrypted data to your agent.
+     *
+     * @example
+     * ```typescript
+     * // Agent shares its encryption public key
+     * await client.publish('secrets.request', {
+     *   agentId: client.agentId,
+     *   publicKey: client.publicKey,  // Ed25519 for identity
+     *   // The sender will use convertToEncryptionKey(publicKey) to encrypt
+     * });
+     * ```
+     */
+    get encryptionPublicKey() {
+        return convertToEncryptionKey(this._publicKeyBase64);
+    }
+    /**
+     * Get the client's X25519 encryption key pair.
+     *
+     * This key pair is derived from the client's Ed25519 signing keys and can
+     * be used to decrypt messages that were encrypted with the client's
+     * encryption public key.
+     *
+     * Use this when you need to decrypt sealed box messages sent to your agent.
+     *
+     * @example
+     * ```typescript
+     * import nacl from 'tweetnacl';
+     * nacl.sealedbox = require('tweetnacl-sealedbox-js');
+     *
+     * // Decrypt a sealed box message
+     * const keyPair = client.encryptionKeyPair;
+     * const decrypted = nacl.sealedbox.open(
+     *   encrypted,
+     *   keyPair.publicKey,
+     *   keyPair.secretKey
+     * );
+     * ```
+     */
+    get encryptionKeyPair() {
+        return convertToEncryptionKeyPair(this._privateKey, this._publicKeyBase64);
+    }
+    /**
+     * Get the agent name (from config).
+     */
+    get name() {
+        return this.config.name;
+    }
+    /**
+     * Get the agent version (from config).
+     */
+    get version() {
+        return this.config.version;
+    }
+    // ─────────────────────────────────────────────────────────────
     // CONNECTION MANAGEMENT
     // ─────────────────────────────────────────────────────────────
     /**
@@ -231,14 +351,16 @@ export class KadiClient {
      * Connect to a specific broker by name.
      *
      * Protocol:
-     * 1. Generate Ed25519 keypair
-     * 2. Open WebSocket connection
-     * 3. Send kadi.session.hello
-     * 4. Receive nonce from broker
-     * 5. Send kadi.session.authenticate with signed nonce
-     * 6. Receive agentId from broker
-     * 7. Register tools with broker
-     * 8. Start heartbeat
+     * 1. Open WebSocket connection
+     * 2. Send kadi.session.hello
+     * 3. Receive nonce from broker
+     * 4. Send kadi.session.authenticate with signed nonce (using client's identity)
+     * 5. Receive agentId from broker (should match client.agentId)
+     * 6. Register tools with broker
+     * 7. Start heartbeat
+     *
+     * Note: The keypair is generated once at client construction and shared
+     * across all broker connections, ensuring consistent identity.
      */
     async connectToBroker(brokerName) {
         const url = this.config.brokers[brokerName];
@@ -256,16 +378,11 @@ export class KadiClient {
                 return;
             }
         }
-        // Generate Ed25519 keypair for authentication
-        const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
-        // Create broker state
+        // Create broker state (identity is at client level, not per-broker)
         const state = {
             name: brokerName,
             url,
             ws: null,
-            agentId: '',
-            publicKey: publicKey.export({ type: 'spki', format: 'der' }),
-            privateKey: privateKey.export({ type: 'pkcs8', format: 'der' }),
             heartbeatTimer: null,
             pendingRequests: new Map(),
             pendingInvocations: new Map(),
@@ -302,9 +419,10 @@ export class KadiClient {
             params: { role: 'agent' },
         };
     }
-    buildAuthMessage(state, nonce) {
+    buildAuthMessage(nonce) {
+        // Sign the nonce using the client's private key
         const privateKey = crypto.createPrivateKey({
-            key: state.privateKey,
+            key: this._privateKey,
             format: 'der',
             type: 'pkcs8',
         });
@@ -314,7 +432,7 @@ export class KadiClient {
             id: this.nextRequestId++,
             method: 'kadi.session.authenticate',
             params: {
-                publicKey: state.publicKey.toString('base64'),
+                publicKey: this._publicKeyBase64,
                 signature: signature.toString('base64'),
                 nonce,
             },
@@ -399,13 +517,18 @@ export class KadiClient {
         }
         // Step 2: Sign the nonce and authenticate
         // This proves we own the private key without revealing it
-        const authResult = await this.sendRequest(state, this.buildAuthMessage(state, helloResult.nonce));
+        const authResult = await this.sendRequest(state, this.buildAuthMessage(helloResult.nonce));
         if (!authResult.agentId) {
             throw new KadiError('Auth response missing agentId', 'AUTHENTICATION_FAILED', {
                 broker: state.name,
             });
         }
-        state.agentId = authResult.agentId;
+        // Verify broker assigned the expected agentId (sanity check)
+        if (authResult.agentId !== this._agentId) {
+            console.warn(`[KADI] Broker "${state.name}" returned different agentId: ` +
+                `expected ${this._agentId}, got ${authResult.agentId}. ` +
+                `This may indicate the broker uses a different ID derivation algorithm.`);
+        }
     }
     /**
      * Register with broker after authentication.
@@ -790,6 +913,181 @@ export class KadiClient {
             },
         });
     }
+    // ─────────────────────────────────────────────────────────────
+    // DEPLOYMENT SECRETS (Trusted Introducer Pattern)
+    // ─────────────────────────────────────────────────────────────
+    /**
+     * Request secrets from the deployer during agent startup.
+     *
+     * This implements the agent side of the "Trusted Introducer" pattern:
+     * 1. Check for KADI_DEPLOY_NONCE env var (set by deployer)
+     * 2. Subscribe to secrets.response.{agentId} channel
+     * 3. Publish request to secrets.request with nonce and public key
+     * 4. Wait for response from deployer (approved with encrypted secrets, or rejected)
+     * 5. If approved, decrypt using agent's encryption key pair
+     * 6. Set secrets in process.env
+     *
+     * The deployer (kadi deploy) stays connected after deployment and waits
+     * for this request. It verifies the nonce, prompts for approval, and
+     * either shares encrypted secrets or sends a rejection.
+     *
+     * @param options - Configuration options
+     * @returns Decrypted secrets as key-value pairs, or null if no secrets needed
+     * @throws KadiError if timeout waiting for secrets or decryption fails
+     *
+     * @example
+     * ```typescript
+     * const client = new KadiClient({ name: 'my-agent', ... });
+     * await client.connect();
+     *
+     * // Request secrets from deployer (throws if timeout)
+     * const secrets = await client.requestSecrets();
+     *
+     * if (secrets) {
+     *   console.log('Received secrets:', Object.keys(secrets));
+     *   // Secrets are also set in process.env
+     * }
+     *
+     * // With custom timeout
+     * const secrets = await client.requestSecrets({ timeout: 120000 });
+     * ```
+     */
+    async requestSecrets(options = {}) {
+        const { timeout = 60000 } = options; // Default 60 seconds
+        // Check for deployment nonce - if not set, no secrets needed
+        const nonce = process.env.KADI_DEPLOY_NONCE;
+        if (!nonce) {
+            return null;
+        }
+        // Parse required/optional secrets from env
+        const requiredSecrets = process.env.KADI_REQUIRED_SECRETS?.split(',').filter(Boolean) || [];
+        const optionalSecrets = process.env.KADI_OPTIONAL_SECRETS?.split(',').filter(Boolean) || [];
+        if (requiredSecrets.length === 0 && optionalSecrets.length === 0) {
+            return null;
+        }
+        // Ensure we're connected to at least one broker
+        const connectedBrokers = [];
+        for (const [name, state] of this.brokers.entries()) {
+            if (state.status === 'connected') {
+                connectedBrokers.push([name, state]);
+            }
+        }
+        if (connectedBrokers.length === 0) {
+            throw new KadiError('Cannot request secrets: not connected to any broker', 'SECRETS_NOT_CONNECTED', { hint: 'Call client.connect() before requestSecrets()' });
+        }
+        // Determine which broker to use for the secret handshake
+        let brokerName;
+        const rendezvousBrokerUrl = process.env.KADI_RENDEZVOUS_BROKER;
+        if (rendezvousBrokerUrl) {
+            // Find the broker matching the rendezvous URL
+            const match = connectedBrokers.find(([_, state]) => state.url === rendezvousBrokerUrl);
+            if (!match) {
+                const connectedUrlsFormatted = connectedBrokers.map(([name, state]) => `  - ${name}: ${state.url}`).join('\n');
+                throw new KadiError(`This agent needs secrets, but it's not connected to the right broker.`, 'SECRETS_NOT_CONNECTED', {
+                    hint: `Secrets will be delivered on:\n  ${rendezvousBrokerUrl}\n\nYour client is connected to:\n${connectedUrlsFormatted}\n\nTo fix, add the delivery broker URL to your KadiClient config,\nor update agent.json brokers to include this URL.`,
+                });
+            }
+            brokerName = match[0];
+        }
+        else {
+            // No rendezvous broker specified - use first connected (for dev/testing)
+            brokerName = connectedBrokers[0][0];
+        }
+        return new Promise((resolve, reject) => {
+            let resolved = false;
+            let timeoutHandle;
+            // Cleanup function
+            const cleanup = () => {
+                if (timeoutHandle) {
+                    clearTimeout(timeoutHandle);
+                }
+                // Unsubscribe from the channel
+                this.unsubscribe(`secrets.response.${this._agentId}`, handleSecrets, { broker: brokerName })
+                    .catch(() => { }); // Ignore unsubscribe errors
+            };
+            // Handler for receiving secrets response
+            const handleSecrets = async (event) => {
+                if (resolved)
+                    return;
+                // Extract response data from event
+                const data = event.data;
+                if (!data?.status) {
+                    // Malformed response - ignore
+                    return;
+                }
+                // Validate status is expected value
+                if (data.status !== 'approved' && data.status !== 'rejected') {
+                    // Unknown status - ignore malformed response
+                    return;
+                }
+                resolved = true;
+                cleanup();
+                // Handle rejection
+                if (data.status === 'rejected') {
+                    reject(new KadiError(`Secrets request rejected: ${data.reason || 'No reason provided'}`, 'SECRETS_REJECTED', { reason: data.reason }));
+                    return;
+                }
+                // Handle approval - must have encrypted data
+                if (!data.encrypted) {
+                    reject(new KadiError('Secrets approved but no encrypted data received', 'SECRETS_DECRYPTION_FAILED', { hint: 'The deployer may have encountered an error' }));
+                    return;
+                }
+                try {
+                    // Decode base64 encrypted blob
+                    const encryptedBytes = Buffer.from(data.encrypted, 'base64');
+                    // Get our encryption key pair
+                    const keyPair = this.encryptionKeyPair;
+                    // Decrypt the sealed box
+                    const decrypted = sealedbox.open(new Uint8Array(encryptedBytes), keyPair.publicKey, keyPair.secretKey);
+                    if (!decrypted) {
+                        reject(new KadiError('Failed to decrypt secrets: invalid sealed box or wrong key', 'SECRETS_DECRYPTION_FAILED', { hint: 'The secrets may have been encrypted for a different agent' }));
+                        return;
+                    }
+                    // Parse JSON
+                    const secretsJson = new TextDecoder().decode(decrypted);
+                    const secrets = JSON.parse(secretsJson);
+                    // Set secrets in process.env
+                    for (const [key, value] of Object.entries(secrets)) {
+                        process.env[key] = value;
+                    }
+                    resolve(secrets);
+                }
+                catch (err) {
+                    reject(new KadiError(`Failed to decrypt secrets: ${err.message}`, 'SECRETS_DECRYPTION_FAILED', { cause: err, hint: 'The secrets may have been encrypted for a different agent' }));
+                }
+            };
+            // Set timeout
+            timeoutHandle = setTimeout(() => {
+                if (!resolved) {
+                    resolved = true;
+                    cleanup();
+                    reject(new KadiError(`Timeout waiting for secrets (${timeout / 1000}s). Deployer may have disconnected or denied the request.`, 'SECRETS_TIMEOUT', {
+                        timeout,
+                        hint: 'Ensure the deployer is still running and approves the secret request',
+                    }));
+                }
+            }, timeout);
+            // Subscribe to our response channel
+            this.subscribe(`secrets.response.${this._agentId}`, handleSecrets, { broker: brokerName })
+                .then(() => {
+                // Publish secret request
+                return this.publish('secrets.request', {
+                    nonce,
+                    agentId: this._agentId,
+                    publicKey: this._publicKeyBase64,
+                    required: requiredSecrets,
+                    optional: optionalSecrets,
+                }, { broker: brokerName });
+            })
+                .catch((err) => {
+                if (!resolved) {
+                    resolved = true;
+                    cleanup();
+                    reject(new KadiError(`Failed to request secrets: ${err.message}`, 'SECRETS_REQUEST_FAILED', { cause: err }));
+                }
+            });
+        });
+    }
     /**
      * Handle incoming request from broker (tool invocation).
      */
@@ -1028,8 +1326,8 @@ export class KadiClient {
     /**
      * Attempt to reconnect to the broker.
      *
-     * This reuses the existing keypair (agentId stays the same) and
-     * re-registers tools with the broker.
+     * Uses the client's identity (same keypair/agentId for all connections)
+     * and re-registers tools with the broker.
      *
      * On failure, schedules another attempt with increased delay.
      */