@celilo/cli 0.1.0

package/src/capabilities/validation.ts

@@ -0,0 +1,160 @@
+/**
+ * Capability Access Validation
+ * Validates that consumer modules have permission to access capability secrets
+ */
+
+import type { Database } from 'bun:sqlite';
+import type { ModuleManifest } from '../manifest/schema';
+
+export interface ValidationResult {
+  success: boolean;
+  error?: string;
+  details?: unknown;
+}
+
+/**
+ * Validate that consumer module can access required capability secrets
+ *
+ * Execution function (Rule 10.1) - performs database queries
+ *
+ * @param manifest - Consumer module manifest
+ * @param db - Database connection
+ * @returns Validation result
+ */
+export async function validateCapabilityAccess(
+  manifest: ModuleManifest,
+  db: Database,
+): Promise<ValidationResult> {
+  // If module doesn't require capabilities, validation passes
+  if (!manifest.requires?.capabilities || manifest.requires.capabilities.length === 0) {
+    return { success: true };
+  }
+
+  // Get list of capabilities this module provides
+  const consumerCapabilities = (manifest.provides?.capabilities || []).map((cap) => cap.name);
+
+  // Check each required capability
+  for (const requiredCapability of manifest.requires.capabilities) {
+    // Get the provider module's manifest
+    const providerManifest = getProviderManifest(requiredCapability.name, db);
+
+    if (!providerManifest) {
+      return {
+        success: false,
+        error: `Required capability '${requiredCapability.name}' not found. No module provides this capability.`,
+      };
+    }
+
+    // Check if any secrets in the capability require access permissions
+    const capabilityDef = providerManifest.provides?.capabilities?.find(
+      (cap) => cap.name === requiredCapability.name,
+    );
+
+    if (!capabilityDef?.secrets || capabilityDef.secrets.length === 0) {
+      // No secrets to validate
+      continue;
+    }
+
+    // Check allowlist for each secret
+    for (const secret of capabilityDef.secrets) {
+      if (secret.readable_by && secret.readable_by.length > 0) {
+        // Check if consumer provides any capability in the allowlist
+        const hasAccess = checkAllowlist(consumerCapabilities, secret.readable_by);
+
+        if (!hasAccess) {
+          return {
+            success: false,
+            error: formatAccessDeniedError(
+              manifest.id,
+              requiredCapability.name,
+              secret.name,
+              consumerCapabilities,
+              secret.readable_by,
+            ),
+          };
+        }
+      }
+      // If readable_by is empty or undefined, secret is accessible to all
+    }
+  }
+
+  return { success: true };
+}
+
+/**
+ * Check if consumer capabilities match provider allowlist
+ *
+ * Policy function (Rule 10.1) - pure logic, no I/O
+ *
+ * @param consumerCapabilities - Capabilities provided by consumer module
+ * @param allowlist - Allowlist from provider's secret definition
+ * @returns True if any consumer capability is in allowlist
+ */
+export function checkAllowlist(consumerCapabilities: string[], allowlist: string[]): boolean {
+  return consumerCapabilities.some((cap) => allowlist.includes(cap));
+}
+
+/**
+ * Get provider module manifest for a capability
+ *
+ * Execution function (Rule 10.1) - performs database query
+ *
+ * @param capabilityName - Name of the capability
+ * @param db - Database connection
+ * @returns Provider module manifest or null if not found
+ */
+export function getProviderManifest(capabilityName: string, db: Database): ModuleManifest | null {
+  const result = db
+    .prepare(
+      `SELECT p.manifest_data
+       FROM modules p
+       JOIN capabilities c ON p.id = c.module_id
+       WHERE c.capability_name = ?
+       LIMIT 1`,
+    )
+    .get(capabilityName) as { manifest_data: string } | undefined;
+
+  if (!result) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(result.manifest_data) as ModuleManifest;
+  } catch (error) {
+    throw new Error(
+      `Failed to parse manifest for module providing capability ${capabilityName}: ${error instanceof Error ? error.message : 'Invalid JSON'}`,
+    );
+  }
+}
+
+/**
+ * Format access denied error message
+ *
+ * Presentation function (Rule 10.1) - formats output for user
+ *
+ * @param consumerModuleId - Consumer module ID
+ * @param capabilityName - Capability name
+ * @param secretName - Secret name
+ * @param consumerCapabilities - Capabilities provided by consumer
+ * @param allowlist - Allowlist from provider
+ * @returns Formatted error message
+ */
+function formatAccessDeniedError(
+  consumerModuleId: string,
+  capabilityName: string,
+  secretName: string,
+  consumerCapabilities: string[],
+  allowlist: string[],
+): string {
+  const lines = [
+    `Module '${consumerModuleId}' cannot access secret '${secretName}' from capability '${capabilityName}'.`,
+    '',
+    `The ${capabilityName} capability only allows access to modules that provide: ${allowlist.join(', ')}`,
+    '',
+    `This module provides: ${consumerCapabilities.length > 0 ? consumerCapabilities.join(', ') : '(none)'}`,
+    '',
+    `To grant access, update the provider module's manifest to add one of the consumer's capabilities to the readable_by list.`,
+  ];
+
+  return lines.join('\n');
+}

package/src/capabilities/well-known.test.ts

@@ -0,0 +1,238 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  WELL_KNOWN_CAPABILITIES,
+  getCapabilityDataSchema,
+  getSupportedCapabilities,
+  getWellKnownCapability,
+  isWellKnown,
+  validateZoneRequirement,
+} from './well-known';
+
+describe('Well-Known Capabilities Registry', () => {
+  describe('WELL_KNOWN_CAPABILITIES', () => {
+    test('should have public_web capability', () => {
+      expect(WELL_KNOWN_CAPABILITIES.public_web).toBeDefined();
+      expect(WELL_KNOWN_CAPABILITIES.public_web.canonical_hostname).toBe('www');
+      expect(WELL_KNOWN_CAPABILITIES.public_web.required_zone).toBe('dmz');
+      expect(WELL_KNOWN_CAPABILITIES.public_web.zone_enforced).toBe(true);
+    });
+
+    test('should have dns_registrar capability', () => {
+      expect(WELL_KNOWN_CAPABILITIES.dns_registrar).toBeDefined();
+      expect(WELL_KNOWN_CAPABILITIES.dns_registrar.canonical_hostname).toBe('dns-reg');
+      expect(WELL_KNOWN_CAPABILITIES.dns_registrar.required_zone).toBe('dmz');
+      expect(WELL_KNOWN_CAPABILITIES.dns_registrar.zone_enforced).toBe(false);
+    });
+
+    test('should have dns_internal capability', () => {
+      expect(WELL_KNOWN_CAPABILITIES.dns_internal).toBeDefined();
+      expect(WELL_KNOWN_CAPABILITIES.dns_internal.canonical_hostname).toBe('dns-int');
+      expect(WELL_KNOWN_CAPABILITIES.dns_internal.required_zone).toBe('internal');
+      expect(WELL_KNOWN_CAPABILITIES.dns_internal.zone_enforced).toBe(true);
+    });
+
+    test('should have auth capability', () => {
+      expect(WELL_KNOWN_CAPABILITIES.auth).toBeDefined();
+      expect(WELL_KNOWN_CAPABILITIES.auth.canonical_hostname).toBe('auth');
+      expect(WELL_KNOWN_CAPABILITIES.auth.required_zone).toBe('secure');
+      expect(WELL_KNOWN_CAPABILITIES.auth.zone_enforced).toBe(true);
+    });
+
+    test('should have database capability', () => {
+      expect(WELL_KNOWN_CAPABILITIES.database).toBeDefined();
+      expect(WELL_KNOWN_CAPABILITIES.database.canonical_hostname).toBe('db');
+      expect(WELL_KNOWN_CAPABILITIES.database.required_zone).toBe('secure');
+      expect(WELL_KNOWN_CAPABILITIES.database.zone_enforced).toBe(true);
+    });
+
+    test('should have dhcp_server capability', () => {
+      expect(WELL_KNOWN_CAPABILITIES.dhcp_server).toBeDefined();
+      expect(WELL_KNOWN_CAPABILITIES.dhcp_server.canonical_hostname).toBe('dhcp');
+      expect(WELL_KNOWN_CAPABILITIES.dhcp_server.required_zone).toBe('internal');
+      expect(WELL_KNOWN_CAPABILITIES.dhcp_server.zone_enforced).toBe(false);
+    });
+
+    test('all capabilities should have required fields', () => {
+      for (const [name, capability] of Object.entries(WELL_KNOWN_CAPABILITIES)) {
+        expect(capability.canonical_hostname, `${name} missing canonical_hostname`).toBeDefined();
+        expect(capability.required_zone, `${name} missing required_zone`).toBeDefined();
+        expect(capability.zone_enforced, `${name} missing zone_enforced`).toBeDefined();
+        expect(capability.data_schema, `${name} missing data_schema`).toBeDefined();
+      }
+    });
+  });
+
+  describe('isWellKnown', () => {
+    test('should return true for well-known capabilities', () => {
+      expect(isWellKnown('public_web')).toBe(true);
+      expect(isWellKnown('dns_registrar')).toBe(true);
+      expect(isWellKnown('dns_internal')).toBe(true);
+      expect(isWellKnown('auth')).toBe(true);
+      expect(isWellKnown('database')).toBe(true);
+      expect(isWellKnown('dhcp_server')).toBe(true);
+    });
+
+    test('should return false for unknown capabilities', () => {
+      expect(isWellKnown('unknown_capability')).toBe(false);
+      expect(isWellKnown('custom_service')).toBe(false);
+      expect(isWellKnown('')).toBe(false);
+    });
+  });
+
+  describe('getWellKnownCapability', () => {
+    test('should return capability for well-known name', () => {
+      const capability = getWellKnownCapability('public_web');
+
+      expect(capability.canonical_hostname).toBe('www');
+      expect(capability.required_zone).toBe('dmz');
+    });
+
+    test('should throw error for unknown capability', () => {
+      expect(() => getWellKnownCapability('unknown')).toThrow('Unknown capability: unknown');
+      expect(() => getWellKnownCapability('unknown')).toThrow(
+        'Supported capabilities: public_web, dns_registrar, dns_internal, auth, database, dhcp_server',
+      );
+    });
+  });
+
+  describe('getSupportedCapabilities', () => {
+    test('should return all capability names', () => {
+      const capabilities = getSupportedCapabilities();
+
+      expect(capabilities).toContain('public_web');
+      expect(capabilities).toContain('dns_registrar');
+      expect(capabilities).toContain('dns_internal');
+      expect(capabilities).toContain('auth');
+      expect(capabilities).toContain('database');
+      expect(capabilities).toContain('dhcp_server');
+      expect(capabilities.length).toBe(6);
+    });
+  });
+
+  describe('validateZoneRequirement', () => {
+    test('should validate correct zone for public_web', () => {
+      const result = validateZoneRequirement('public_web', 'dmz');
+
+      expect(result.valid).toBe(true);
+      expect(result.error).toBeUndefined();
+    });
+
+    test('should reject wrong zone for public_web', () => {
+      const result = validateZoneRequirement('public_web', 'app');
+
+      expect(result.valid).toBe(false);
+      expect(result.required_zone).toBe('dmz');
+      expect(result.error).toContain("Capability 'public_web' requires zone='dmz'");
+      expect(result.error).toContain("Module specifies zone='app'");
+    });
+
+    test('should validate correct zone for auth', () => {
+      const result = validateZoneRequirement('auth', 'secure');
+
+      expect(result.valid).toBe(true);
+    });
+
+    test('should reject wrong zone for auth', () => {
+      const result = validateZoneRequirement('auth', 'dmz');
+
+      expect(result.valid).toBe(false);
+      expect(result.required_zone).toBe('secure');
+      expect(result.error).toContain("Capability 'auth' requires zone='secure'");
+    });
+
+    test('should validate correct zone for dns_internal', () => {
+      const result = validateZoneRequirement('dns_internal', 'internal');
+
+      expect(result.valid).toBe(true);
+    });
+
+    test('should allow dns_registrar in any zone (zone_enforced=false)', () => {
+      const result = validateZoneRequirement('dns_registrar', 'dmz');
+      expect(result.valid).toBe(true);
+
+      const result2 = validateZoneRequirement('dns_registrar', 'app');
+      expect(result2.valid).toBe(true);
+    });
+
+    test('should reject unknown capability', () => {
+      const result = validateZoneRequirement('unknown_capability', 'dmz');
+
+      expect(result.valid).toBe(false);
+      expect(result.error).toContain('Unknown capability: unknown_capability');
+      expect(result.error).toContain('Supported capabilities');
+    });
+  });
+
+  describe('getCapabilityDataSchema', () => {
+    test('should return data schema for public_web', () => {
+      const schema = getCapabilityDataSchema('public_web');
+
+      expect(schema).toEqual({
+        server: {
+          ip: {
+            primary: '$self:container_ip',
+          },
+          port: 443,
+        },
+      });
+    });
+
+    test('should return data schema for dns_registrar', () => {
+      const schema = getCapabilityDataSchema('dns_registrar');
+
+      expect(schema).toEqual({
+        provider: 'namecheap',
+        primary_domain: '$self:primary_domain',
+        supports: ['dynamic_dns_a_record'],
+      });
+    });
+
+    test('should return data schema for auth', () => {
+      const schema = getCapabilityDataSchema('auth');
+
+      // Note: oidc.issuer_url was removed in MANIFEST_V2 D9 — auth providers
+      // (e.g. authentik) now derive their issuer URL in their own manifest
+      // and expose it through provides.capabilities[].data.
+      expect(schema).toEqual({
+        server: {
+          ip: {
+            primary: '$self:container_ip',
+          },
+          port: 9000,
+        },
+      });
+    });
+
+    test('should return cloned schema (not reference)', () => {
+      const schema1 = getCapabilityDataSchema('public_web');
+      const schema2 = getCapabilityDataSchema('public_web');
+
+      // Modify one schema to test cloning
+      // biome-ignore lint/suspicious/noExplicitAny: intentionally mutating to verify independent copies
+      (schema1 as any).server.port = 8080;
+
+      // Other schema should be unchanged
+      // biome-ignore lint/suspicious/noExplicitAny: accessing mutated property for comparison
+      expect((schema2 as any).server.port).toBe(443);
+    });
+
+    test('should throw error for unknown capability', () => {
+      expect(() => getCapabilityDataSchema('unknown')).toThrow('Unknown capability: unknown');
+    });
+  });
+
+  describe('Security zone requirements', () => {
+    test('home lab public-facing services must be in DMZ', () => {
+      expect(WELL_KNOWN_CAPABILITIES.public_web.required_zone).toBe('dmz');
+    });
+
+    test('authentication services must be in secure zone', () => {
+      expect(WELL_KNOWN_CAPABILITIES.auth.required_zone).toBe('secure');
+      expect(WELL_KNOWN_CAPABILITIES.database.required_zone).toBe('secure');
+    });
+
+    test('internal services must be in internal zone', () => {
+      expect(WELL_KNOWN_CAPABILITIES.dns_internal.required_zone).toBe('internal');
+    });
+  });
+});

package/src/capabilities/well-known.ts

@@ -0,0 +1,222 @@
+/**
+ * Well-Known Capabilities Registry
+ * Defines standardized capabilities with predefined hostnames, zones, and schemas
+ * Hardcoded registry (extensibility deferred to future)
+ */
+
+/**
+ * Network zones define security boundaries and deployment locations
+ *
+ * Home Lab Zones (VLAN-based):
+ * - dmz: Public-facing services in home lab (VLAN 10, e.g., 10.0.10.0/24)
+ * - app: Internal services in home lab (VLAN 20, e.g., 10.0.20.0/24)
+ * - secure: Auth/DB in home lab (VLAN 30, e.g., 10.0.30.0/24)
+ *
+ * External Zone (Cloud/VPS):
+ * - external: Services hosted outside home network (no VLAN, e.g., VPS on internet)
+ */
+export type NetworkZone = 'internal' | 'dmz' | 'app' | 'secure' | 'external';
+
+export interface WellKnownCapability {
+  canonical_hostname: string;
+  required_zone: NetworkZone;
+  zone_enforced: boolean; // Always true
+  data_schema: Record<string, unknown>;
+}
+
+/**
+ * Registry of well-known capabilities
+ * These capabilities have standardized contracts enforced by Celilo
+ */
+export const WELL_KNOWN_CAPABILITIES: Record<string, WellKnownCapability> = {
+  /**
+   * public_web - Public-facing web server
+   * Example: Caddy reverse proxy
+   * Security: MUST be in DMZ zone (internet-facing)
+   */
+  public_web: {
+    canonical_hostname: 'www',
+    required_zone: 'dmz',
+    zone_enforced: true,
+    data_schema: {
+      server: {
+        ip: {
+          primary: '$self:container_ip',
+        },
+        port: 443,
+      },
+    },
+  },
+
+  /**
+   * dns_registrar - Domain registrar with Dynamic DNS support
+   * Example: Namecheap Dynamic DNS
+   * Security: Zone-agnostic (no infrastructure, just API calls)
+   */
+  dns_registrar: {
+    canonical_hostname: 'dns-reg',
+    required_zone: 'dmz',
+    zone_enforced: false,
+    data_schema: {
+      provider: 'namecheap',
+      primary_domain: '$self:primary_domain',
+      supports: ['dynamic_dns_a_record'],
+    },
+  },
+
+  /**
+   * dns_internal - Internal DNS resolver
+   * Example: Technitium DNS server for split-horizon LAN resolution
+   * Security: Internal zone (backbone service reachable from all zones)
+   */
+  dns_internal: {
+    canonical_hostname: 'dns-int',
+    required_zone: 'internal',
+    zone_enforced: true,
+    data_schema: {
+      server: {
+        ip: {
+          primary: '$self:container_ip',
+        },
+        port: 53,
+      },
+    },
+  },
+
+  /**
+   * auth - Authentication/Identity Provider
+   * Example: Authentik, Keycloak
+   * Security: MUST be in secure zone (handles authentication)
+   *
+   * Note: `oidc.issuer_url` is no longer derived here. Per the firm rule in
+   * design/TECHNICAL_DESIGN_MANIFEST_V2.md D9, well-known capability data
+   * templates must not cross-reference other capabilities. The IDP-providing
+   * module derives `auth_url` (or whatever it calls the issuer URL) in its
+   * own manifest from `$capability:dns_registrar.primary_domain` and exposes
+   * it through `provides.capabilities[].data`.
+   */
+  auth: {
+    canonical_hostname: 'auth',
+    required_zone: 'secure',
+    zone_enforced: true,
+    data_schema: {
+      server: {
+        ip: {
+          primary: '$self:container_ip',
+        },
+        port: 9000,
+      },
+    },
+  },
+
+  /**
+   * database - Database server
+   * Example: PostgreSQL, MySQL, MongoDB
+   * Security: Recommended secure zone (sensitive data)
+   */
+  database: {
+    canonical_hostname: 'db',
+    required_zone: 'secure',
+    zone_enforced: true,
+    data_schema: {
+      server: {
+        ip: {
+          primary: '$self:container_ip',
+        },
+        port: '$self:port', // Database-specific port
+      },
+      connection: {
+        host: '$self:container_ip',
+        port: '$self:port',
+        name: '$self:database_name',
+      },
+    },
+  },
+
+  /**
+   * dhcp_server - DHCP server with configurable DNS
+   * Example: ISP router (GreenWave C4000XG) DHCP service
+   * Security: Zone-agnostic (external service, no infrastructure)
+   */
+  dhcp_server: {
+    canonical_hostname: 'dhcp',
+    required_zone: 'internal',
+    zone_enforced: false,
+    data_schema: {
+      router_ip: '$self:router_ip',
+    },
+  },
+};
+
+/**
+ * Check if a capability name is well-known
+ */
+export function isWellKnown(capabilityName: string): boolean {
+  return capabilityName in WELL_KNOWN_CAPABILITIES;
+}
+
+/**
+ * Get well-known capability metadata
+ * Throws error if capability is not well-known
+ */
+export function getWellKnownCapability(capabilityName: string): WellKnownCapability {
+  if (!isWellKnown(capabilityName)) {
+    throw new Error(
+      `Unknown capability: ${capabilityName}. Supported capabilities: ${getSupportedCapabilities().join(', ')}`,
+    );
+  }
+  return WELL_KNOWN_CAPABILITIES[capabilityName];
+}
+
+/**
+ * Get list of all supported capability names
+ */
+export function getSupportedCapabilities(): string[] {
+  return Object.keys(WELL_KNOWN_CAPABILITIES);
+}
+
+/**
+ * Validation result for zone requirements
+ */
+export interface ZoneValidationResult {
+  valid: boolean;
+  error?: string;
+  required_zone?: NetworkZone;
+}
+
+/**
+ * Validate that module zone matches capability requirement
+ * Returns validation result with error message if mismatch
+ */
+export function validateZoneRequirement(
+  capabilityName: string,
+  moduleZone: NetworkZone,
+): ZoneValidationResult {
+  if (!isWellKnown(capabilityName)) {
+    return {
+      valid: false,
+      error: `Unknown capability: ${capabilityName}. Supported capabilities: ${getSupportedCapabilities().join(', ')}`,
+    };
+  }
+
+  const capability = WELL_KNOWN_CAPABILITIES[capabilityName];
+
+  if (capability.zone_enforced && moduleZone !== capability.required_zone) {
+    return {
+      valid: false,
+      required_zone: capability.required_zone,
+      error: `Capability '${capabilityName}' requires zone='${capability.required_zone}' (security requirement). Module specifies zone='${moduleZone}'.`,
+    };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Get capability data schema with variables resolved
+ * Note: This returns the template schema - actual variable resolution happens during generation
+ */
+export function getCapabilityDataSchema(capabilityName: string): Record<string, unknown> {
+  const capability = getWellKnownCapability(capabilityName);
+  return structuredClone(capability.data_schema);
+}