kadi-deploy 0.19.0

package/src/schemas/profiles.ts

@@ -0,0 +1,529 @@
+/**
+ * Zod Schemas for Profile Validation
+ *
+ * Validates agent.json deploy profiles at runtime to catch configuration errors early.
+ * Provides clear error messages when profiles are malformed or missing required fields.
+ *
+ * @module schemas/profiles
+ */
+
+import { z } from 'zod';
+import type {
+  AkashRegion,
+  AkashTier,
+} from '@kadi.build/deploy-ability';
+
+/**
+ * Port exposure configuration for services
+ *
+ * Supports both simple string format and Akash SDL object format for 'to' field
+ */
+const PortExposeSchema = z.object({
+  /** Port number to expose */
+  port: z.number().int().min(1).max(65535),
+
+  /** Port number to expose as (required - be explicit about external port) */
+  as: z.number().int().min(1).max(65535),
+
+  /** Where to expose the port - defaults to local only */
+  to: z.array(
+    z.union([
+      z.string(),
+      z.object({ global: z.boolean() }).passthrough(),
+      z.object({ service: z.string() }).passthrough()
+    ])
+  ).default([{ global: false }]),
+
+  /** Protocol (tcp or udp) */
+  proto: z.enum(['tcp', 'udp']).optional(),
+
+  /** Enable global exposure (alternative to using 'to' field) */
+  global: z.boolean().optional(),
+
+  /** Accept list for global exposure */
+  accept: z.array(z.string()).optional(),
+});
+
+/**
+ * Registry credentials for private images
+ */
+const RegistryCredentialsSchema = z.object({
+  /** Registry host (e.g., "ghcr.io") */
+  host: z.string(),
+
+  /** Registry username */
+  username: z.string(),
+
+  /** Registry password or token */
+  password: z.string(),
+});
+
+/**
+ * Persistent volume specification for Akash Network
+ */
+const PersistentVolumeSchema = z.object({
+  /** Volume name (must be unique within service) */
+  name: z.string(),
+
+  /** Volume size (e.g., "10Gi") */
+  size: z.string(),
+
+  /** Container mount path (e.g., "/data") */
+  mount: z.string(),
+
+  /** Storage class: beta1 (HDD), beta2 (SSD), beta3 (NVMe), ram */
+  class: z.enum(['beta1', 'beta2', 'beta3', 'ram']).optional(),
+});
+
+/**
+ * GPU configuration schema (shared between Akash and Local)
+ *
+ * If requesting GPU, you must specify vendor and model details.
+ * Example: { units: 1, attributes: { vendor: { nvidia: [{ model: "rtx4090" }] } } }
+ */
+const GpuConfigSchema = z.object({
+  /** Number of GPU units */
+  units: z.number().int().positive(),
+
+  /**
+   * GPU attributes - REQUIRED when requesting GPU
+   * Specifies vendor and model requirements
+   */
+  attributes: z.object({
+    vendor: z.record(
+      z.string(),
+      z.array(
+        z.object({
+          /** GPU model - required so you know what you're getting */
+          model: z.string(),
+          ram: z.string().optional(),
+          interface: z.enum(['pcie', 'sxm']).optional(),
+        })
+      )
+    ),
+  }),
+});
+
+/**
+ * Resource configuration for Akash deployments
+ *
+ * cpu and memory are REQUIRED for Akash since the network needs to
+ * know what resources to allocate.
+ */
+const AkashResourceConfigSchema = z.object({
+  /** CPU units (e.g., 0.5 for half a CPU) - REQUIRED */
+  cpu: z.number().positive(),
+
+  /** Memory (RAM) with units (e.g., "512Mi", "2Gi") - REQUIRED */
+  memory: z.string(),
+
+  /** Ephemeral storage for container root filesystem (e.g., "512Mi", "1Gi") */
+  ephemeralStorage: z.string().optional(),
+
+  /** Persistent volumes that survive container restarts */
+  persistentVolumes: z.array(PersistentVolumeSchema).optional(),
+
+  /** GPU configuration */
+  gpu: GpuConfigSchema.optional(),
+});
+
+/**
+ * Resource configuration for Local deployments
+ *
+ * All fields optional since Docker/Podman handle defaults.
+ */
+const LocalResourceConfigSchema = z.object({
+  /** CPU units (e.g., 0.5 for half a CPU) */
+  cpu: z.number().positive().optional(),
+
+  /** Memory (RAM) with units (e.g., "512Mi", "2Gi") */
+  memory: z.string().optional(),
+
+  /** Ephemeral storage for container root filesystem (e.g., "512Mi", "1Gi") */
+  ephemeralStorage: z.string().optional(),
+
+  /** Persistent volumes that survive container restarts */
+  persistentVolumes: z.array(PersistentVolumeSchema).optional(),
+
+  /** GPU configuration */
+  gpu: GpuConfigSchema.optional(),
+});
+
+/**
+ * Akash pricing configuration
+ */
+const AkashPricingSchema = z.object({
+  /** Denomination (e.g., "uakt") */
+  denom: z.string(),
+
+  /** Amount (number or string) */
+  amount: z.union([z.number(), z.string()]),
+});
+
+/**
+ * Valid Akash region values (typed for validation)
+ *
+ * These are the **actual values used by providers on Akash mainnet**,
+ * not the official schema values. Based on provider query results.
+ *
+ * Provider counts (as of query):
+ * - us-west: 5, us-central: 4, us-east: 3
+ * - eu-central: 2, ca-central: 2, ca-east: 2
+ * - Others: 1-2 each
+ */
+const VALID_REGIONS: readonly AkashRegion[] = [
+  // United States (most common)
+  'us-west', 'us-central', 'us-east', 'us-west-1', 'us',
+  // Canada
+  'ca-central', 'ca-east', 'ca',
+  // Europe
+  'eu-central', 'eu-west', 'eu-east', 'europe', 'eu',
+  // Asia
+  'asia-east', 'singapore',
+  // Other regions (less common)
+  'westmidlands', 'westeurope', 'westcoast',
+];
+
+/**
+ * Valid Akash tier values (typed for validation)
+ *
+ * Provider tiers are one of the most commonly used attributes (37+ providers).
+ * - community: 35 providers (standard pricing)
+ * - premium: 2 providers (higher SLA)
+ */
+const VALID_TIERS: readonly AkashTier[] = [
+  'community', 'premium',
+];
+
+/**
+ * Akash placement attributes for geographic targeting
+ *
+ * Based on **actual provider usage on mainnet**, not the official schema.
+ * Only includes attributes that providers actually use.
+ *
+ * **Available Attributes:**
+ * - region: 33 providers use this
+ * - tier: 37 providers use this
+ */
+const AkashPlacementAttributesSchema = z.object({
+  /** Geographic region */
+  region: z.string()
+    .refine((val): val is AkashRegion => VALID_REGIONS.includes(val as AkashRegion), {
+      message: `Invalid region. Valid regions: ${VALID_REGIONS.slice(0, 8).join(', ')}... (${VALID_REGIONS.length} total). Examples: 'us-west' (5 providers), 'us-central' (4 providers), 'eu-central' (2 providers)`,
+    })
+    .optional(),
+
+  /** Provider tier (community or premium) */
+  tier: z.string()
+    .refine((val): val is AkashTier => VALID_TIERS.includes(val as AkashTier), {
+      message: `Invalid tier. Valid tiers: ${VALID_TIERS.join(', ')}. Note: 'community' (35 providers), 'premium' (2 providers)`,
+    })
+    .optional(),
+});
+
+/**
+ * Auditor signature requirements for provider attributes
+ */
+const SignedBySchema = z.object({
+  /** All of these auditors must have signed */
+  allOf: z.array(z.string()).optional(),
+
+  /** Any of these auditors must have signed */
+  anyOf: z.array(z.string()).optional(),
+});
+
+/**
+ * Vault name validation (reused across schemas)
+ */
+const VaultNameSchema = z.string()
+  .min(1, 'Vault name cannot be empty')
+  .regex(/^[a-zA-Z0-9_-]+$/, 'Vault name must contain only alphanumeric characters, hyphens, and underscores');
+
+/**
+ * Individual vault source for multi-vault secrets configuration.
+ * Each entry specifies a vault and its associated secret keys.
+ */
+const VaultSourceSchema = z.object({
+  /** Vault name to read secrets from (must exist in kadi-secret) */
+  vault: VaultNameSchema,
+
+  /** Secret names that must exist before deployment (deploy fails if missing) */
+  required: z.array(z.string()).optional(),
+
+  /** Secret names that will be shared if available (no error if missing) */
+  optional: z.array(z.string()).optional(),
+});
+
+/**
+ * Secrets configuration for deployment
+ *
+ * Declares which secrets the deployed agent needs. These are validated
+ * before deployment to ensure they exist in the specified vault(s) (via kadi-secret).
+ *
+ * Supports two formats:
+ *
+ * **Legacy (single vault):**
+ * ```json
+ * { "vault": "my-app", "required": ["API_KEY"], "delivery": "broker" }
+ * ```
+ *
+ * **Multi-vault:**
+ * ```json
+ * {
+ *   "vaults": [
+ *     { "vault": "my-app", "required": ["API_KEY"] },
+ *     { "vault": "infra", "required": ["TUNNEL_TOKEN"] }
+ *   ],
+ *   "delivery": "broker"
+ * }
+ * ```
+ *
+ * Delivery modes:
+ * - "env" (default): Secrets injected as plain environment variables
+ * - "broker": E2E encrypted handshake via broker (requires KADI CLI/SDK in container)
+ */
+const SecretsSchema = z.union([
+  // Legacy single-vault format (backwards compatible)
+  z.object({
+    /** Vault name to read secrets from (must exist in kadi-secret) */
+    vault: VaultNameSchema,
+
+    /** Secret names that must exist before deployment (deploy fails if missing) */
+    required: z.array(z.string()).optional(),
+
+    /** Secret names that will be shared if available (no error if missing) */
+    optional: z.array(z.string()).optional(),
+
+    /**
+     * Secret delivery mode:
+     * - "env": Inject secrets as plain environment variables (works with any container)
+     * - "broker": E2E encrypted handshake via broker (requires KADI CLI or SDK)
+     * Default: "env"
+     */
+    delivery: z.enum(['env', 'broker']).optional(),
+  }),
+
+  // New multi-vault format
+  z.object({
+    /** Array of vault sources, each with their own required/optional keys */
+    vaults: z.array(VaultSourceSchema).min(1, 'At least one vault source is required'),
+
+    /**
+     * Secret delivery mode (applies to all vaults):
+     * - "env": Inject secrets as plain environment variables (works with any container)
+     * - "broker": E2E encrypted handshake via broker (requires KADI CLI or SDK)
+     * Default: "env"
+     */
+    delivery: z.enum(['env', 'broker']).optional(),
+  }),
+]);
+
+/**
+ * Akash service definition
+ */
+const AkashServiceSchema = z.object({
+  /** Container image (e.g., "nginx:latest") */
+  image: z.string(),
+
+  /** Optional command override */
+  command: z.array(z.string()).optional(),
+
+  /** Environment variables (array or object format) */
+  env: z.union([
+    z.array(z.string()),
+    z.record(z.string(), z.string())
+  ]).optional(),
+
+  /** Port exposures */
+  expose: z.array(PortExposeSchema).optional(),
+
+  /** Registry credentials for private images */
+  credentials: RegistryCredentialsSchema.optional(),
+
+  /** Resource requirements */
+  resources: AkashResourceConfigSchema.optional(),
+
+  /** Pricing configuration */
+  pricing: AkashPricingSchema.optional(),
+
+  /** Number of instances */
+  count: z.number().int().positive().optional(),
+});
+
+/**
+ * Local service definition (for Docker/Podman)
+ */
+const LocalServiceSchema = z.object({
+  /** Container image (e.g., "nginx:latest") */
+  image: z.string(),
+
+  /** Optional command override */
+  command: z.array(z.string()).optional(),
+
+  /** Environment variables (array format) */
+  env: z.array(z.string()).optional(),
+
+  /** Port exposures */
+  expose: z.array(PortExposeSchema).optional(),
+
+  /** Resource requirements */
+  resources: LocalResourceConfigSchema.optional(),
+
+  /** Docker/Podman volume mounts (e.g., "/host/path:/container/path:ro") */
+  volumes: z.array(z.string()).optional(),
+
+  /** Working directory inside the container */
+  workingDir: z.string().optional(),
+
+  /** Services this service depends on */
+  dependsOn: z.array(z.string()).optional(),
+
+  /** Restart policy (e.g., "unless-stopped", "always", "on-failure") */
+  restart: z.string().optional(),
+});
+
+/**
+ * Akash deployment profile schema
+ */
+export const AkashProfileSchema = z.object({
+  /** Deployment target (must be 'akash') */
+  target: z.literal('akash'),
+
+  /** Network to deploy to */
+  network: z.enum(['mainnet', 'testnet']),
+
+  /** Container engine for local operations */
+  engine: z.enum(['docker', 'podman']).optional(),
+
+  /** Service definitions */
+  services: z.record(z.string(), AkashServiceSchema),
+
+  /** Geographic and facility placement constraints for deployment targeting */
+  placement: AkashPlacementAttributesSchema.optional(),
+
+  /** Custom provider attributes (advanced - prefer using 'placement' for geographic targeting) */
+  attributes: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+
+  /** Auditor signature requirements for provider attributes */
+  signedBy: SignedBySchema.optional(),
+
+  /** WalletConnect project ID */
+  walletConnectProjectId: z.string().optional(),
+
+  /** Path to certificate file */
+  cert: z.string().optional(),
+
+  /** Provider blacklist */
+  blacklist: z.array(z.string()).optional(),
+
+  /** Deployment deposit in AKT (default: 5 AKT) */
+  deposit: z.coerce.number().positive().optional(),
+
+  /** CLI options */
+  verbose: z.boolean().optional(),
+  showCommands: z.boolean().optional(),
+  yes: z.boolean().optional(),
+  dryRun: z.boolean().optional(),
+
+  /** Secrets to validate and share with the deployed agent */
+  secrets: SecretsSchema.optional(),
+});
+
+/**
+ * Local deployment profile schema
+ */
+export const LocalProfileSchema = z.object({
+  /** Deployment target (must be 'local') */
+  target: z.literal('local'),
+
+  /** Container engine (required) */
+  engine: z.enum(['docker', 'podman']),
+
+  /** Docker network name */
+  network: z.string().optional(),
+
+  /** Service definitions */
+  services: z.record(z.string(), LocalServiceSchema),
+
+  /** CLI options */
+  verbose: z.boolean().optional(),
+  showCommands: z.boolean().optional(),
+  yes: z.boolean().optional(),
+  dryRun: z.boolean().optional(),
+
+  /** Secrets to validate and share with the deployed agent */
+  secrets: SecretsSchema.optional(),
+});
+
+/**
+ * Union of all profile types
+ */
+export const ProfileSchema = z.union([
+  AkashProfileSchema,
+  LocalProfileSchema,
+]);
+
+/**
+ * Inferred TypeScript types from Zod schemas
+ */
+export type AkashProfile = z.infer<typeof AkashProfileSchema>;
+export type LocalProfile = z.infer<typeof LocalProfileSchema>;
+export type Profile = z.infer<typeof ProfileSchema>;
+
+/**
+ * Validate and parse a profile from agent.json
+ *
+ * @param profileData - Raw profile data from agent.json
+ * @param profileName - Name of the profile (for error messages)
+ * @returns Validated profile
+ * @throws ZodError with detailed validation errors
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const profile = validateProfile(rawData, 'production');
+ *   // profile is now fully typed and validated
+ * } catch (error) {
+ *   if (error instanceof z.ZodError) {
+ *     console.error('Profile validation failed:', error.format());
+ *   }
+ * }
+ * ```
+ */
+export function validateProfile(profileData: unknown, profileName: string): Profile {
+  try {
+    return ProfileSchema.parse(profileData);
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      // Add context to error message with detailed issue information
+      const formattedErrors = error.issues.map((issue: z.ZodIssue) => {
+        const path = issue.path.length > 0 ? issue.path.join('.') : 'root';
+        const expected = 'expected' in issue ? ` (expected: ${JSON.stringify(issue.expected)})` : '';
+        const received = 'received' in issue ? ` (received: ${JSON.stringify(issue.received)})` : '';
+        return `  - ${path}: ${issue.message}${expected}${received}`;
+      }).join('\n');
+
+      // Also log the raw profile data for debugging
+      console.error('[DEBUG] Raw profile data:', JSON.stringify(profileData, null, 2));
+
+      throw new Error(
+        `Profile "${profileName}" validation failed:\n${formattedErrors}`
+      );
+    }
+    throw error;
+  }
+}
+
+/**
+ * Type guard to check if profile is an Akash profile
+ */
+export function isAkashProfile(profile: Profile): profile is AkashProfile {
+  return profile.target === 'akash';
+}
+
+/**
+ * Type guard to check if profile is a Local profile
+ */
+export function isLocalProfile(profile: Profile): profile is LocalProfile {
+  return profile.target === 'local';
+}

package/src/secrets/broker-urls.ts

@@ -0,0 +1,109 @@
+/**
+ * Broker URL Resolution for Secrets Injection
+ *
+ * Resolves broker URLs from environment or agent.json configuration.
+ * The deployed agent needs broker URLs to request secrets from the deployer.
+ *
+ * Resolution order:
+ * 1. KADI_BROKER_URLS environment variable (comma-separated)
+ * 2. agent.json brokers field (object mapping names to URLs)
+ * 3. Fail fast with helpful error if neither found
+ *
+ * @module secrets/broker-urls
+ */
+
+import type { AgentConfig } from '../types.js';
+
+/**
+ * Result of broker URL resolution
+ */
+export interface BrokerUrlsResult {
+  /** Whether broker URLs were found */
+  found: boolean;
+  /** Comma-separated broker URLs (for KADI_BROKER_URLS env var) */
+  urls: string;
+  /** Source of the URLs for logging */
+  source: 'env' | 'agent.json' | 'none';
+}
+
+/**
+ * Resolve broker URLs from environment or agent.json
+ *
+ * @param agentConfig - Loaded agent.json configuration
+ * @returns Resolution result with URLs and source
+ *
+ * @example
+ * ```typescript
+ * const result = resolveBrokerUrls(agentConfig);
+ *
+ * if (!result.found) {
+ *   throw new Error('No broker URLs configured');
+ * }
+ *
+ * // Inject into container env
+ * env.push(`KADI_BROKER_URLS=${result.urls}`);
+ * ```
+ */
+export function resolveBrokerUrls(agentConfig: AgentConfig): BrokerUrlsResult {
+  // 1. Check KADI_BROKER_URLS env var first (takes precedence)
+  const envUrls = process.env.KADI_BROKER_URLS;
+  if (envUrls) {
+    const urls = envUrls
+      .split(',')
+      .map(u => u.trim())
+      .filter(u => u.length > 0);
+
+    if (urls.length > 0) {
+      return {
+        found: true,
+        urls: urls.join(','),
+        source: 'env',
+      };
+    }
+  }
+
+  // 2. Fall back to agent.json brokers field
+  const brokers = agentConfig.brokers;
+  if (brokers && typeof brokers === 'object') {
+    const urls = Object.values(brokers).filter(
+      (url): url is string => typeof url === 'string' && url.length > 0
+    );
+
+    if (urls.length > 0) {
+      return {
+        found: true,
+        urls: urls.join(','),
+        source: 'agent.json',
+      };
+    }
+  }
+
+  // 3. Not found
+  return {
+    found: false,
+    urls: '',
+    source: 'none',
+  };
+}
+
+/**
+ * Format error message for missing broker URLs
+ *
+ * @returns Formatted error message with instructions
+ */
+export function formatMissingBrokerUrlsError(): string {
+  return `No broker URLs configured.
+
+The deployed agent needs broker URLs to request secrets.
+Configure them in one of these ways:
+
+  1. Set KADI_BROKER_URLS environment variable:
+     export KADI_BROKER_URLS=ws://broker.example.com:8080/kadi
+
+  2. Add brokers to agent.json:
+     {
+       "brokers": {
+         "default": "ws://broker.example.com:8080/kadi"
+       }
+     }`;
+}