@kadi.build/core 0.4.0 → 0.6.0

package/src/crypto.ts

@@ -0,0 +1,153 @@
+/**
+ * Cryptographic utilities for KADI
+ *
+ * This module provides utilities for converting between Ed25519 signing keys
+ * and X25519 encryption keys.
+ *
+ * ## Background
+ *
+ * KADI uses Ed25519 keys for identity and authentication (signing).
+ * However, Ed25519 is a signing algorithm - it cannot encrypt data.
+ *
+ * X25519 is an encryption algorithm that allows:
+ * - Encrypting data so only the recipient can read it
+ * - Sealed boxes: sender encrypts with recipient's public key,
+ *   only recipient's private key can decrypt
+ *
+ * Both algorithms use Curve25519 underneath, so an Ed25519 key
+ * can be mathematically converted to an X25519 key.
+ *
+ * @module crypto
+ */
+
+// @ts-expect-error - ed2curve doesn't have type definitions
+import ed2curve from 'ed2curve';
+
+/**
+ * X25519 encryption key pair.
+ *
+ * Used for public-key encryption (e.g., sealed boxes).
+ * Derived from Ed25519 signing keys.
+ */
+export interface EncryptionKeyPair {
+  /** X25519 public key (32 bytes) - share with others to receive encrypted messages */
+  publicKey: Uint8Array;
+  /** X25519 secret key (32 bytes) - keep private, used to decrypt messages */
+  secretKey: Uint8Array;
+}
+
+/**
+ * Convert an Ed25519 signing public key to an X25519 encryption public key.
+ *
+ * KADI uses Ed25519 keys for identity and authentication (signing).
+ * However, Ed25519 is a signing algorithm - it cannot encrypt data.
+ *
+ * X25519 is an encryption algorithm that allows:
+ * - Encrypting data so only the recipient can read it
+ * - Sealed boxes: sender encrypts with recipient's public key,
+ *   only recipient's private key can decrypt
+ *
+ * Both algorithms use Curve25519 underneath, so an Ed25519 key
+ * can be mathematically converted to an X25519 key. This function
+ * performs that conversion.
+ *
+ * @param publicKey - Base64-encoded Ed25519 public key (SPKI DER format)
+ * @returns X25519 public key as Uint8Array (32 bytes)
+ * @throws Error if the public key is invalid
+ *
+ * @example
+ * ```typescript
+ * import { convertToEncryptionKey } from '@kadi.build/core';
+ * import nacl from 'tweetnacl';
+ *
+ * // Convert agent's Ed25519 public key to X25519
+ * const encryptionKey = convertToEncryptionKey(agentPublicKey);
+ *
+ * // Now you can encrypt data for that agent using sealed box
+ * const encrypted = nacl.sealedbox.seal(message, encryptionKey);
+ * ```
+ */
+export function convertToEncryptionKey(publicKey: string): Uint8Array {
+  // Decode base64 SPKI DER format to raw bytes
+  const derBytes = Buffer.from(publicKey, 'base64');
+
+  // SPKI DER format for Ed25519 has a 12-byte header, raw key starts at offset 12
+  // Format: 30 2a 30 05 06 03 2b 65 70 03 21 00 [32-byte key]
+  const rawEd25519Key = derBytes.slice(12);
+
+  if (rawEd25519Key.length !== 32) {
+    throw new Error(
+      `Invalid Ed25519 public key: expected 32 bytes after SPKI header, got ${rawEd25519Key.length}`
+    );
+  }
+
+  // Convert Ed25519 public key to X25519 public key
+  const x25519Key = ed2curve.convertPublicKey(new Uint8Array(rawEd25519Key));
+
+  if (!x25519Key) {
+    throw new Error('Failed to convert Ed25519 public key to X25519');
+  }
+
+  return x25519Key;
+}
+
+/**
+ * Convert an Ed25519 signing key pair to an X25519 encryption key pair.
+ *
+ * This is used internally by KadiClient to derive encryption keys from
+ * its Ed25519 identity. The resulting key pair can be used with
+ * tweetnacl's box or sealedbox functions.
+ *
+ * @param privateKey - Ed25519 private key in PKCS8 DER format (Buffer)
+ * @param publicKey - Base64-encoded Ed25519 public key (SPKI DER format)
+ * @returns X25519 key pair for encryption/decryption
+ * @throws Error if the keys are invalid
+ *
+ * @example
+ * ```typescript
+ * // Inside KadiClient
+ * const keyPair = convertToEncryptionKeyPair(this._privateKey, this._publicKeyBase64);
+ *
+ * // Decrypt a sealed box message
+ * const decrypted = nacl.sealedbox.open(encrypted, keyPair.publicKey, keyPair.secretKey);
+ * ```
+ */
+export function convertToEncryptionKeyPair(
+  privateKey: Buffer,
+  publicKey: string
+): EncryptionKeyPair {
+  // Get X25519 public key
+  const x25519PublicKey = convertToEncryptionKey(publicKey);
+
+  // PKCS8 DER format for Ed25519 has a header, raw key is at offset 16
+  // Format: 30 2e 02 01 00 30 05 06 03 2b 65 70 04 22 04 20 [32-byte seed]
+  // The seed is the first 32 bytes of the 64-byte Ed25519 secret key
+  const rawSeed = privateKey.slice(16, 48);
+
+  if (rawSeed.length !== 32) {
+    throw new Error(
+      `Invalid Ed25519 private key: expected 32-byte seed after PKCS8 header, got ${rawSeed.length}`
+    );
+  }
+
+  // Convert Ed25519 secret key (seed) to X25519 secret key
+  // ed2curve.convertSecretKey expects the 64-byte secret key, but we only have the seed
+  // We need to expand the seed first by creating the full 64-byte key
+  // The full Ed25519 secret key is: seed (32 bytes) + public key (32 bytes)
+  const derBytes = Buffer.from(publicKey, 'base64');
+  const rawPublicKey = derBytes.slice(12);
+  const fullSecretKey = new Uint8Array(64);
+  fullSecretKey.set(rawSeed, 0);
+  fullSecretKey.set(rawPublicKey, 32);
+
+  const x25519SecretKey = ed2curve.convertSecretKey(fullSecretKey);
+
+  if (!x25519SecretKey) {
+    throw new Error('Failed to convert Ed25519 secret key to X25519');
+  }
+
+  return {
+    publicKey: x25519PublicKey,
+    secretKey: x25519SecretKey,
+  };
+}

package/src/errors.ts

@@ -0,0 +1,292 @@
+/**
+ * Error handling for kadi-core v0.1.0
+ *
+ * All errors in kadi-core use KadiError, which includes:
+ * - A human-readable message
+ * - An error code for programmatic handling
+ * - Context with additional details
+ * - Automatic formatting of hints and suggestions
+ *
+ * The goal is helpful errors that guide users to solutions.
+ */
+
+// ═══════════════════════════════════════════════════════════════════════
+// ERROR CODES
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * All possible error codes.
+ * Use these for programmatic error handling.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.connect();
+ * } catch (error) {
+ *   if (error instanceof KadiError && error.code === 'CONNECTION_FAILED') {
+ *     // Handle connection failure specifically
+ *   }
+ * }
+ * ```
+ */
+export type ErrorCode =
+  // Connection errors
+  | 'CONNECTION_FAILED'
+  | 'AUTHENTICATION_FAILED'
+  | 'REGISTRATION_FAILED'
+  | 'BROKER_NOT_CONNECTED'
+  | 'BROKER_CONNECTION_FAILED'
+  | 'CONNECTION_CLOSED'
+
+  // Broker errors
+  | 'BROKER_ERROR'
+  | 'BROKER_TIMEOUT'
+  | 'BROKER_RESPONSE_ERROR'
+  | 'UNKNOWN_BROKER'
+
+  // Tool errors
+  | 'TOOL_NOT_FOUND'
+  | 'TOOL_ALREADY_REGISTERED'
+  | 'TOOL_INVOCATION_FAILED'
+  | 'TOOL_TIMEOUT'
+  | 'VALIDATION_FAILED'
+
+  // Ability errors
+  | 'ABILITY_NOT_FOUND'
+  | 'ABILITY_LOAD_FAILED'
+  | 'ABILITY_NOT_CONNECTED'
+
+  // Lock file errors
+  | 'LOCKFILE_NOT_FOUND'
+  | 'LOCKFILE_PARSE_ERROR'
+
+  // Config errors
+  | 'INVALID_CONFIG'
+  | 'INVALID_INPUT'
+  | 'PROJECT_ROOT_NOT_FOUND'
+
+  // Transport errors
+  | 'STDIO_ERROR'
+  | 'STDIO_PROCESS_FAILED'
+  | 'NATIVE_IMPORT_ERROR'
+  | 'TRANSPORT_SEND_FAILED'
+
+  // Secrets errors (Trusted Introducer pattern)
+  | 'SECRETS_NOT_CONNECTED'
+  | 'SECRETS_DECRYPTION_FAILED'
+  | 'SECRETS_REQUEST_FAILED'
+  | 'SECRETS_REJECTED'
+  | 'SECRETS_TIMEOUT'
+
+  // Generic
+  | 'TIMEOUT'
+  | 'INTERNAL_ERROR'
+  | 'UNKNOWN_ERROR'
+  | 'NOT_IMPLEMENTED';
+
+// ═══════════════════════════════════════════════════════════════════════
+// ERROR CONTEXT
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Additional context that can be attached to errors.
+ * All fields are optional - include what's helpful.
+ */
+export interface ErrorContext {
+  /** Hint for how to fix the error */
+  hint?: string;
+
+  /** Alternative approaches */
+  alternative?: string;
+
+  /** Path that was searched */
+  searched?: string;
+
+  /** List of available options */
+  available?: string[];
+
+  /** List of connected brokers */
+  connectedBrokers?: string[];
+
+  /** The broker name involved */
+  broker?: string;
+
+  /** The broker URL involved */
+  url?: string;
+
+  /** The tool name involved */
+  toolName?: string;
+
+  /** The ability name involved */
+  abilityName?: string;
+
+  /** The path involved */
+  path?: string;
+
+  /** The reason for the error */
+  reason?: string;
+
+  /** Any other context */
+  [key: string]: unknown;
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// KADI ERROR CLASS
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Custom error class for kadi-core.
+ *
+ * Features:
+ * - Error code for programmatic handling
+ * - Context object with additional details
+ * - Automatic formatting of helpful messages
+ *
+ * @example
+ * ```typescript
+ * throw new KadiError(
+ *   'Ability "calculator" not found in agent-lock.json',
+ *   'ABILITY_NOT_FOUND',
+ *   {
+ *     searched: '/path/to/agent-lock.json',
+ *     hint: 'Run `kadi install calculator` to install it',
+ *     alternative: 'Or specify explicit path: { path: "./path" }',
+ *   }
+ * );
+ * ```
+ */
+export class KadiError extends Error {
+  /**
+   * Error code for programmatic handling.
+   */
+  public readonly code: ErrorCode;
+
+  /**
+   * Additional context about the error.
+   */
+  public readonly context: ErrorContext;
+
+  constructor(message: string, code: ErrorCode, context: ErrorContext = {}) {
+    // Format the message with context appended
+    super(formatErrorMessage(message, context));
+
+    this.name = 'KadiError';
+    this.code = code;
+    this.context = context;
+
+    // Maintain proper stack trace in V8 environments
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, KadiError);
+    }
+  }
+
+  /**
+   * Create a KadiError from an unknown error.
+   * Useful for wrapping errors from external sources.
+   *
+   * @param error - The error to wrap
+   * @param code - Error code to use (default: 'UNKNOWN_ERROR')
+   * @param context - Additional context to add
+   */
+  static from(
+    error: unknown,
+    code: ErrorCode = 'UNKNOWN_ERROR',
+    context: ErrorContext = {}
+  ): KadiError {
+    // If it's already a KadiError, return it (don't double-wrap)
+    if (error instanceof KadiError) {
+      return error;
+    }
+
+    // Extract message from various error types
+    let message: string;
+    if (error instanceof Error) {
+      message = error.message;
+    } else if (typeof error === 'string') {
+      message = error;
+    } else {
+      message = 'An unknown error occurred';
+    }
+
+    return new KadiError(message, code, context);
+  }
+
+  /**
+   * Check if an error is a KadiError.
+   */
+  static isKadiError(error: unknown): error is KadiError {
+    return error instanceof KadiError;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// MESSAGE FORMATTING
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Format an error message with context appended.
+ * Creates a multi-line message that's easy to read in console output.
+ *
+ * @example
+ * Input:
+ *   message: 'Ability "foo" not found'
+ *   context: { searched: '/path', hint: 'Run kadi install foo' }
+ *
+ * Output:
+ *   'Ability "foo" not found
+ *     Searched: /path
+ *     Hint: Run kadi install foo'
+ */
+function formatErrorMessage(message: string, context: ErrorContext): string {
+  const lines: string[] = [message];
+
+  // Add context fields in a consistent order
+  if (context.searched) {
+    lines.push(`  Searched: ${context.searched}`);
+  }
+
+  if (context.path) {
+    lines.push(`  Path: ${context.path}`);
+  }
+
+  if (context.broker) {
+    lines.push(`  Broker: ${context.broker}`);
+  }
+
+  if (context.url) {
+    lines.push(`  URL: ${context.url}`);
+  }
+
+  if (context.reason) {
+    lines.push(`  Reason: ${context.reason}`);
+  }
+
+  if (context.connectedBrokers && context.connectedBrokers.length > 0) {
+    lines.push(`  Connected brokers: ${context.connectedBrokers.join(', ')}`);
+  }
+
+  if (context.available && context.available.length > 0) {
+    lines.push(`  Available: ${context.available.join(', ')}`);
+  }
+
+  if (context.hint) {
+    lines.push(`  Hint: ${context.hint}`);
+  }
+
+  if (context.alternative) {
+    lines.push(`  Or: ${context.alternative}`);
+  }
+
+  return lines.join('\n');
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// TYPE GUARD
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * Check if a value is an Error object.
+ */
+export function isError(value: unknown): value is Error {
+  return value instanceof Error;
+}

package/src/index.ts

@@ -0,0 +1,114 @@
+/**
+ * kadi-core v0.1.0
+ *
+ * A lean, readable SDK for building KADI agents.
+ *
+ * @example
+ * ```typescript
+ * import { KadiClient, z } from 'kadi-core';
+ *
+ * const client = new KadiClient({
+ *   name: 'my-agent',
+ *   brokers: {
+ *     production: 'ws://broker:8080',
+ *   },
+ *   defaultBroker: 'production',
+ * });
+ *
+ * client.registerTool({
+ *   name: 'add',
+ *   description: 'Add two numbers',
+ *   input: z.object({ a: z.number(), b: z.number() }),
+ * }, async ({ a, b }) => ({ result: a + b }));
+ *
+ * await client.connect();
+ * ```
+ */
+
+// Re-export Zod for schema definitions
+export { z } from 'zod';
+
+// Main client
+export { KadiClient } from './client.js';
+
+// Errors
+export { KadiError } from './errors.js';
+export type { ErrorCode, ErrorContext } from './errors.js';
+
+// Types
+export type {
+  // Configuration
+  ClientConfig,
+  ResolvedConfig,
+
+  // Tools
+  ToolDefinition,
+  ZodToolDefinition,
+  ToolHandler,
+  RegisteredTool,
+  JSONSchema,
+  RequestContext,
+
+  // Abilities
+  LoadedAbility,
+  InvokeOptions,
+  TransportType,
+  EventHandler,
+
+  // Options
+  RegisterToolOptions,
+  LoadOptions,
+  LoadNativeOptions,
+  LoadStdioOptions,
+  LoadBrokerOptions,
+  InvokeRemoteOptions,
+
+  // Broker
+  BrokerState,
+  BrokerStatus,
+  PendingRequest,
+
+  // Broker Events (Pub/Sub)
+  BrokerEvent,
+  BrokerEventHandler,
+  PublishOptions,
+  SubscribeOptions,
+  EmitOptions,
+
+  // JSON-RPC
+  JsonRpcRequest,
+  JsonRpcResponse,
+  JsonRpcNotification,
+  JsonRpcError,
+  JsonRpcMessage,
+
+  // Lock file
+  AgentLockFile,
+  AbilityLockEntry,
+
+  // Script resolution
+  ResolvedScript,
+} from './types.js';
+
+// Zod utilities
+export { zodToJsonSchema, isZodSchema } from './zod.js';
+
+// Lock file utilities
+export {
+  findProjectRoot,
+  readLockFile,
+  findAbilityEntry,
+  resolveAbilityPath,
+  resolveAbilityEntry,
+  getInstalledAbilityNames,
+} from './lockfile.js';
+
+// Transports (for advanced use cases)
+export { loadNativeTransport } from './transports/native.js';
+export { loadStdioTransport } from './transports/stdio.js';
+export { loadBrokerTransport } from './transports/broker.js';
+export type { BrokerTransportOptions } from './transports/broker.js';
+
+// Crypto utilities (Ed25519 to X25519 conversion)
+export { convertToEncryptionKey, convertToEncryptionKeyPair } from './crypto.js';
+export type { EncryptionKeyPair } from './crypto.js';