kadi-deploy 0.19.0

package/src/secrets/handshake.ts

@@ -0,0 +1,407 @@
+/**
+ * Secret Handshake for Broker Delivery Mode
+ *
+ * After deployment, the deployer stays connected to the broker and waits
+ * for the deployed agent to request secrets. This module handles:
+ *
+ * 1. Connecting to broker
+ * 2. Subscribing to secrets.request channel
+ * 3. Verifying the nonce matches what was injected
+ * 4. Prompting user for approval (or auto-approving)
+ * 5. Encrypting secrets with agent's public key (E2E encryption)
+ * 6. Sharing encrypted secrets via broker pub/sub
+ *
+ * ## Encryption
+ *
+ * Secrets are encrypted using sealed boxes (X25519 + XSalsa20-Poly1305).
+ * The agent's Ed25519 public key is converted to X25519 for encryption.
+ * Only the agent can decrypt using its private key.
+ *
+ * @module secrets/handshake
+ */
+
+import { KadiClient, convertToEncryptionKey, type BrokerEvent } from '@kadi.build/core';
+import nacl from 'tweetnacl';
+// @ts-expect-error - tweetnacl-sealedbox-js doesn't have type definitions
+import sealedbox from 'tweetnacl-sealedbox-js';
+
+/**
+ * Secret request from deployed agent
+ */
+export interface SecretRequest {
+  /** Nonce injected during deployment (for verification) */
+  nonce: string;
+  /** Agent's unique ID */
+  agentId: string;
+  /** Agent's public key (for future E2E encryption) */
+  publicKey?: string;
+  /** List of required secrets */
+  required: string[];
+  /** List of optional secrets */
+  optional?: string[];
+}
+
+/**
+ * Options for waiting for secret requests
+ */
+export interface WaitForSecretsOptions {
+  /** Broker URL to connect to */
+  brokerUrl: string;
+  /** Expected nonce (must match request) */
+  expectedNonce: string;
+  /** Timeout in milliseconds (default: 5 minutes) */
+  timeout?: number;
+  /** Logger for status updates */
+  logger?: {
+    log: (msg: string) => void;
+    error: (msg: string) => void;
+  };
+}
+
+/**
+ * Result of waiting for secrets
+ */
+export interface WaitForSecretsResult {
+  success: boolean;
+  /** The verified request (if successful) */
+  request?: SecretRequest;
+  /** Error message (if failed) */
+  error?: string;
+  /** Whether timeout occurred */
+  timedOut?: boolean;
+}
+
+/**
+ * Options for sharing secrets
+ */
+export interface ShareSecretsOptions {
+  /** Broker URL */
+  brokerUrl: string;
+  /** Agent ID to share with */
+  agentId: string;
+  /** Agent's Ed25519 public key (base64 SPKI DER format) for encryption */
+  agentPublicKey: string;
+  /** Secrets to share (key-value pairs) */
+  secrets: Record<string, string>;
+  /** Logger for status updates */
+  logger?: {
+    log: (msg: string) => void;
+    error: (msg: string) => void;
+  };
+}
+
+/**
+ * Wait for deployed agent to request secrets
+ *
+ * Connects to broker, subscribes to secrets.request, and waits for
+ * a request with matching nonce.
+ *
+ * @param options - Configuration options
+ * @returns Result with verified request or error
+ */
+export async function waitForSecretRequest(
+  options: WaitForSecretsOptions
+): Promise<WaitForSecretsResult> {
+  const {
+    brokerUrl,
+    expectedNonce,
+    timeout = 5 * 60 * 1000, // 5 minutes default
+    logger = { log: console.log, error: console.error },
+  } = options;
+
+  // Create a minimal KadiClient for broker connection
+  const client = new KadiClient({
+    name: 'kadi-deploy-handshake',
+    version: '1.0.0',
+    brokers: {
+      default: { url: brokerUrl },
+    },
+  });
+
+  return new Promise(async (resolve) => {
+    let resolved = false;
+    let timeoutHandle: NodeJS.Timeout | undefined;
+
+    // Cleanup function
+    const cleanup = async () => {
+      if (timeoutHandle) {
+        clearTimeout(timeoutHandle);
+      }
+      try {
+        await client.disconnect();
+      } catch {
+        // Ignore disconnect errors
+      }
+    };
+
+    // Set timeout
+    timeoutHandle = setTimeout(async () => {
+      if (!resolved) {
+        resolved = true;
+        await cleanup();
+        resolve({
+          success: false,
+          timedOut: true,
+          error: `Timeout waiting for agent to request secrets (${timeout / 1000}s)`,
+        });
+      }
+    }, timeout);
+
+    try {
+      // Connect to broker
+      logger.log('Connecting to broker...');
+      await client.connect();
+      logger.log('Connected. Waiting for agent to request secrets...');
+
+      // Subscribe to secret requests
+      await client.subscribe('secrets.request', async (event: BrokerEvent) => {
+        if (resolved) return;
+
+        // The actual request payload is in event.data
+        const request = event.data as SecretRequest;
+
+        // Verify nonce
+        if (request.nonce !== expectedNonce) {
+          logger.log(`Received request with invalid nonce (ignoring)`);
+          return;
+        }
+
+        // Valid request - capture and return it
+        // Caller will handle approval and sharing
+        resolved = true;
+        await cleanup();
+        resolve({
+          success: true,
+          request,
+        });
+      });
+    } catch (err) {
+      if (!resolved) {
+        resolved = true;
+        await cleanup();
+        resolve({
+          success: false,
+          error: `Failed to connect to broker: ${(err as Error).message}`,
+        });
+      }
+    }
+  });
+}
+
+/**
+ * Share secrets with deployed agent via broker
+ *
+ * Encrypts secrets using the agent's public key (sealed box) and publishes
+ * them to the agent's approval channel. Only the agent can decrypt.
+ *
+ * ## Encryption Flow
+ *
+ * 1. Convert agent's Ed25519 public key to X25519 (encryption key)
+ * 2. Serialize secrets as JSON
+ * 3. Encrypt with sealed box (X25519 + XSalsa20-Poly1305)
+ * 4. Send base64-encoded encrypted blob via broker
+ *
+ * @param options - Configuration options
+ */
+export async function shareSecrets(options: ShareSecretsOptions): Promise<void> {
+  const {
+    brokerUrl,
+    agentId,
+    agentPublicKey,
+    secrets,
+    logger = { log: console.log, error: console.error },
+  } = options;
+
+  // Step 1: Convert agent's Ed25519 public key to X25519 encryption key
+  // This uses kadi-core's convertToEncryptionKey which handles the
+  // Ed25519 -> X25519 conversion (both use Curve25519 underneath)
+  const encryptionKey = convertToEncryptionKey(agentPublicKey);
+
+  // Step 2: Serialize secrets as JSON
+  const secretsJson = JSON.stringify(secrets);
+  const secretsBytes = new TextEncoder().encode(secretsJson);
+
+  // Step 3: Encrypt with sealed box
+  // Sealed box = anonymous encryption where only recipient can decrypt
+  // Uses ephemeral keypair internally, so sender cannot decrypt their own message
+  const encrypted = sealedbox.seal(secretsBytes, encryptionKey);
+
+  // Step 4: Encode as base64 for transport
+  const encryptedBase64 = Buffer.from(encrypted).toString('base64');
+
+  // Create a minimal KadiClient for broker connection
+  const client = new KadiClient({
+    name: 'kadi-deploy-share',
+    version: '1.0.0',
+    brokers: {
+      default: { url: brokerUrl },
+    },
+  });
+
+  try {
+    // Connect to broker
+    await client.connect();
+
+    // Publish encrypted secrets to agent's response channel
+    // Channel format: secrets.response.{agentId}
+    const channel = `secrets.response.${agentId}`;
+
+    await client.publish(channel, {
+      status: 'approved',
+      encrypted: encryptedBase64,
+      sharedAt: new Date().toISOString(),
+    });
+
+    logger.log('Encrypted secrets shared successfully');
+  } finally {
+    try {
+      await client.disconnect();
+    } catch {
+      // Ignore disconnect errors
+    }
+  }
+}
+
+/**
+ * Options for sending rejection
+ */
+export interface SendRejectionOptions {
+  /** Broker URL */
+  brokerUrl: string;
+  /** Agent ID to notify */
+  agentId: string;
+  /** Reason for rejection */
+  reason: string;
+  /** Logger for status updates */
+  logger?: {
+    log: (msg: string) => void;
+    error: (msg: string) => void;
+  };
+}
+
+/**
+ * Send rejection to deployed agent via broker
+ *
+ * Notifies the agent that secrets will not be shared, allowing it to
+ * fail immediately instead of waiting for timeout.
+ *
+ * @param options - Configuration options
+ */
+export async function sendRejection(options: SendRejectionOptions): Promise<void> {
+  const {
+    brokerUrl,
+    agentId,
+    reason,
+    logger = { log: console.log, error: console.error },
+  } = options;
+
+  // Create a minimal KadiClient for broker connection
+  const client = new KadiClient({
+    name: 'kadi-deploy-reject',
+    version: '1.0.0',
+    brokers: {
+      default: { url: brokerUrl },
+    },
+  });
+
+  try {
+    // Connect to broker
+    await client.connect();
+
+    // Publish rejection to agent's response channel
+    const channel = `secrets.response.${agentId}`;
+
+    await client.publish(channel, {
+      status: 'rejected',
+      reason,
+      rejectedAt: new Date().toISOString(),
+    });
+
+    logger.log('Rejection sent to agent');
+  } finally {
+    try {
+      await client.disconnect();
+    } catch {
+      // Ignore disconnect errors
+    }
+  }
+}
+
+/**
+ * Complete secret handshake flow
+ *
+ * Convenience function that combines waiting and sharing.
+ *
+ * @param options - Configuration options
+ * @param getSecrets - Function to retrieve secret values by name
+ */
+export async function performSecretHandshake(
+  options: WaitForSecretsOptions & {
+    /** Function to get secret value by name */
+    getSecret: (name: string) => Promise<string | null>;
+  }
+): Promise<{ success: boolean; error?: string }> {
+  const { getSecret, ...waitOptions } = options;
+  const logger = options.logger || { log: console.log, error: console.error };
+
+  // Step 1: Wait for agent to request secrets
+  const waitResult = await waitForSecretRequest(waitOptions);
+
+  if (!waitResult.success || !waitResult.request) {
+    return {
+      success: false,
+      error: waitResult.error,
+    };
+  }
+
+  const request = waitResult.request;
+
+  // Step 2: Retrieve secrets from local vault
+  const secrets: Record<string, string> = {};
+  const missingSecrets: string[] = [];
+
+  // Get required secrets
+  for (const name of request.required) {
+    const value = await getSecret(name);
+    if (value !== null) {
+      secrets[name] = value;
+    } else {
+      missingSecrets.push(name);
+    }
+  }
+
+  // Get optional secrets (no error if missing)
+  for (const name of request.optional || []) {
+    const value = await getSecret(name);
+    if (value !== null) {
+      secrets[name] = value;
+    }
+  }
+
+  // Check for missing required secrets
+  if (missingSecrets.length > 0) {
+    return {
+      success: false,
+      error: `Missing required secrets: ${missingSecrets.join(', ')}`,
+    };
+  }
+
+  // Step 3: Verify agent provided public key for encryption
+  if (!request.publicKey) {
+    return {
+      success: false,
+      error: 'Agent did not provide public key for encryption',
+    };
+  }
+
+  // Step 4: Share encrypted secrets with agent
+  await shareSecrets({
+    brokerUrl: options.brokerUrl,
+    agentId: request.agentId,
+    agentPublicKey: request.publicKey,
+    secrets,
+    logger,
+  });
+
+  return { success: true };
+}

package/src/secrets/index.ts

@@ -0,0 +1,69 @@
+/**
+ * Secrets Module
+ *
+ * Handles secrets validation and injection for secure secret
+ * sharing with deployed agents.
+ *
+ * @module secrets
+ */
+
+// Validation (Phase 2.2)
+export {
+  validateSecrets,
+  validateSecretsOrFail,
+  formatMissingSecretsError,
+  formatMissingOptionalWarning,
+  type SecretsValidationResult,
+} from './validate.js';
+
+// Nonce generation (Phase 2.3)
+export { generateNonce } from './nonce.js';
+
+// Broker URL resolution (Phase 2.3)
+export {
+  resolveBrokerUrls,
+  formatMissingBrokerUrlsError,
+  type BrokerUrlsResult,
+} from './broker-urls.js';
+
+// Secrets injection
+export {
+  injectSecretsEnv,
+  type SecretsInjectionEnv,
+} from './inject-env.js';
+
+// Secret handshake (Phase 2.4)
+export {
+  waitForSecretRequest,
+  shareSecrets,
+  sendRejection,
+  performSecretHandshake,
+  type SecretRequest,
+  type WaitForSecretsOptions,
+  type WaitForSecretsResult,
+  type ShareSecretsOptions,
+  type SendRejectionOptions,
+} from './handshake.js';
+
+// Local vault helpers
+export { readSecretFromCli, readSecretsFromCli } from './vault.js';
+
+// Secrets preparation (shared logic for deploy commands)
+export {
+  prepareSecretsForDeployment,
+  type PrepareSecretsOptions,
+  type PrepareSecretsResult,
+} from './prepare.js';
+
+// Secrets normalization (multi-vault support)
+export {
+  normalizeSecrets,
+  hasAnySecrets,
+  allRequiredKeys,
+  allOptionalKeys,
+  allSecretKeys,
+  buildVaultSourcesEnv,
+  type NormalizedVaultSource,
+  type NormalizedSecrets,
+  type RawSecretsConfig,
+} from './normalize.js';

package/src/secrets/inject-env.ts

@@ -0,0 +1,171 @@
+/**
+ * Secrets Injection for Deployment
+ *
+ * Injects KADI environment variables into all services in a deploy profile.
+ * Supports two delivery modes:
+ *
+ * - "env" (default): Secrets injected as plain environment variables.
+ *   Works with any container. Secrets are visible in SDL/compose.
+ *
+ * - "broker": E2E encrypted handshake via broker. Requires KADI CLI or SDK
+ *   in the container. Secrets never appear in SDL/compose.
+ *
+ * Injected variables (both modes):
+ * - KADI_DEPLOY_NONCE: Cryptographic nonce to verify request authenticity
+ * - KADI_REQUIRED_SECRETS: Comma-separated list of secrets the agent needs
+ * - KADI_SECRET_DELIVERY: Delivery mode ("env" or "broker")
+ * - KADI_VAULT_SOURCES: JSON array mapping vaults to keys (only for multi-vault)
+ *
+ * Additional variables for "broker" mode:
+ * - KADI_BROKER_URLS: Comma-separated broker URLs
+ * - KADI_RENDEZVOUS_BROKER: The broker URL where secrets will be delivered
+ *
+ * Additional variables for "env" mode:
+ * - The actual secret values (e.g., API_KEY=xxx, DB_URL=xxx)
+ *
+ * @module secrets/inject-env
+ */
+
+import type { Profile } from '../schemas/profiles.js';
+import { buildVaultSourcesEnv, type NormalizedVaultSource } from './normalize.js';
+
+/**
+ * Secret delivery mode
+ */
+export type DeliveryMode = 'env' | 'broker';
+
+/**
+ * Environment variables to inject into deployed containers
+ */
+export interface SecretsInjectionEnv {
+  /** Comma-separated broker URLs (required for broker mode) */
+  brokerUrls?: string;
+  /** Cryptographic nonce for verification */
+  nonce: string;
+  /** Comma-separated required secret names */
+  requiredSecrets: string[];
+  /** Comma-separated optional secret names */
+  optionalSecrets: string[];
+  /** Delivery mode */
+  delivery: DeliveryMode;
+  /** Actual secret values (only for env mode) */
+  secrets?: Record<string, string>;
+  /** Vault sources for multi-vault routing (optional; omit for legacy single-vault) */
+  vaultSources?: NormalizedVaultSource[];
+}
+
+/**
+ * Normalize service env to array format
+ *
+ * The profile schema allows env as either:
+ * - Array of strings: ["KEY=value", "KEY2=value2"]
+ * - Object: { KEY: "value", KEY2: "value2" }
+ *
+ * This normalizes to array format for consistent handling.
+ *
+ * @param env - Service env in either format
+ * @returns Array of "KEY=value" strings
+ */
+function normalizeEnvToArray(env: string[] | Record<string, string> | undefined): string[] {
+  if (!env) {
+    return [];
+  }
+
+  if (Array.isArray(env)) {
+    return [...env];
+  }
+
+  // Convert object to array
+  return Object.entries(env).map(([key, value]) => `${key}=${value}`);
+}
+
+/**
+ * Inject environment variables for secret delivery into a deploy profile
+ *
+ * Mutates the profile in place, adding KADI_* env vars to all services.
+ * Works with both Akash and Local profiles.
+ *
+ * @param profile - Deployment profile (will be mutated)
+ * @param env - Environment variables to inject
+ *
+ * @example
+ * ```typescript
+ * // Broker mode (E2E encrypted)
+ * injectSecretsEnv(profile, {
+ *   brokerUrls: 'ws://broker:8080/kadi',
+ *   nonce: generateNonce(),
+ *   requiredSecrets: ['API_KEY', 'DB_URL'],
+ *   optionalSecrets: [],
+ *   delivery: 'broker',
+ * });
+ *
+ * // Env mode (plain env vars)
+ * injectSecretsEnv(profile, {
+ *   nonce: generateNonce(),
+ *   requiredSecrets: ['API_KEY', 'DB_URL'],
+ *   optionalSecrets: [],
+ *   delivery: 'env',
+ *   secrets: { API_KEY: 'xxx', DB_URL: 'postgres://...' },
+ * });
+ *
+ * // Multi-vault broker mode
+ * injectSecretsEnv(profile, {
+ *   brokerUrls: 'ws://broker:8080/kadi',
+ *   nonce: generateNonce(),
+ *   requiredSecrets: ['API_KEY', 'TUNNEL_TOKEN'],
+ *   optionalSecrets: [],
+ *   delivery: 'broker',
+ *   vaultSources: [
+ *     { vault: 'app', required: ['API_KEY'], optional: [] },
+ *     { vault: 'infra', required: ['TUNNEL_TOKEN'], optional: [] },
+ *   ],
+ * });
+ * ```
+ */
+export function injectSecretsEnv(
+  profile: Profile,
+  env: SecretsInjectionEnv
+): void {
+  const kadiEnvVars: string[] = [
+    `KADI_DEPLOY_NONCE=${env.nonce}`,
+    `KADI_SECRET_DELIVERY=${env.delivery}`,
+  ];
+
+  // Add secrets list
+  const allSecrets = [...env.requiredSecrets, ...env.optionalSecrets];
+  if (allSecrets.length > 0) {
+    kadiEnvVars.push(`KADI_REQUIRED_SECRETS=${allSecrets.join(',')}`);
+  }
+
+  // Multi-vault: inject KADI_VAULT_SOURCES so the receiver knows which vault each key belongs to
+  if (env.vaultSources) {
+    const vaultSourcesJson = buildVaultSourcesEnv(env.vaultSources);
+    if (vaultSourcesJson) {
+      kadiEnvVars.push(`KADI_VAULT_SOURCES=${vaultSourcesJson}`);
+    }
+  }
+
+  // Mode-specific env vars
+  if (env.delivery === 'broker') {
+    if (!env.brokerUrls) {
+      throw new Error('brokerUrls is required for broker delivery mode');
+    }
+    const rendezvousBroker = env.brokerUrls.split(',')[0]!;
+    kadiEnvVars.push(`KADI_BROKER_URLS=${env.brokerUrls}`);
+    kadiEnvVars.push(`KADI_RENDEZVOUS_BROKER=${rendezvousBroker}`);
+  } else if (env.delivery === 'env' && env.secrets) {
+    // Inject actual secret values
+    for (const [key, value] of Object.entries(env.secrets)) {
+      kadiEnvVars.push(`${key}=${value}`);
+    }
+  }
+
+  // Inject into all services
+  for (const serviceName of Object.keys(profile.services)) {
+    const service = profile.services[serviceName];
+
+    // Normalize existing env to array and add KADI vars
+    const existingEnv = normalizeEnvToArray(service.env);
+    service.env = [...existingEnv, ...kadiEnvVars];
+  }
+}

package/src/secrets/nonce.ts

@@ -0,0 +1,31 @@
+/**
+ * Nonce Generation for Secrets Injection
+ *
+ * Generates cryptographically secure nonces used to verify that
+ * secret requests come from the deployed agent (not an impersonator).
+ *
+ * @module secrets/nonce
+ */
+
+import { randomBytes } from 'node:crypto';
+
+/**
+ * Generate a cryptographically secure nonce
+ *
+ * The nonce is:
+ * 1. Injected into the container via KADI_DEPLOY_NONCE env var
+ * 2. Included in the agent's secret request message
+ * 3. Verified by the deployer before sharing secrets
+ *
+ * @param length - Number of random bytes (default: 32 = 256 bits)
+ * @returns Hex-encoded nonce string
+ *
+ * @example
+ * ```typescript
+ * const nonce = generateNonce();
+ * // nonce = "a1b2c3d4e5f6..." (64 hex characters)
+ * ```
+ */
+export function generateNonce(length: number = 32): string {
+  return randomBytes(length).toString('hex');
+}