@celilo/cli 0.3.30-alpha.0 → 0.4.0-alpha.0

package/src/manifest/validate.ts

@@ -173,6 +173,75 @@ export function validateCapabilityNames(manifest: ModuleManifest): ValidationErr
   return null;
 }
 
+/**
+ * Privileged capabilities — framework-granted privileges that only specific
+ * modules may declare in `requires.capabilities`. Allow-list is intentionally
+ * tiny: adding a module here is a deliberate trust decision, not an
+ * automatic side effect of how capabilities work elsewhere.
+ *
+ * Why this gate lives in `validate.ts` (not in the capability resolver):
+ * the privilege is gated at MANIFEST IMPORT time so the operator sees the
+ * rejection immediately when they try to `celilo module import` a module
+ * that's claiming a privilege it shouldn't have. Catching it later (at
+ * hook-invocation time) would let a bad module sit in IMPORTED state.
+ *
+ * Keys are capability names; values are arrays of module IDs allowed to
+ * require that capability. Empty value = no module may require it (acts as
+ * an internal-only privilege flag — currently unused, but the shape leaves
+ * room for that pattern).
+ */
+const PRIVILEGED_CAPABILITY_ALLOW_LIST: Record<string, readonly string[]> = {
+  cross_module_read: ['celilo-mgmt'],
+};
+
+/**
+ * Whether `name` is a framework-granted privilege rather than a normal
+ * provider-backed capability. Privileges are satisfied by the framework
+ * (gated by the allow-list above), so the capability-provider resolver
+ * must NOT expect a module to "provide" them.
+ */
+export function isPrivilegedCapability(name: string): boolean {
+  return name in PRIVILEGED_CAPABILITY_ALLOW_LIST;
+}
+
+/**
+ * Reject `requires.capabilities` declarations for privileged capabilities
+ * by modules not in the allow-list. Surfaces a clear actionable error
+ * identifying the privilege and the allowed modules.
+ *
+ * `optional.capabilities` is checked too — a module shouldn't be able to
+ * "soft-require" a privilege either (otherwise the privilege flag could be
+ * smuggled in via the optional path and granted at hook time).
+ */
+export function validatePrivilegedCapabilities(manifest: ModuleManifest): ValidationError | null {
+  const errors: Array<{ path: string; message: string }> = [];
+
+  for (const required of manifest.requires.capabilities) {
+    const allowed = PRIVILEGED_CAPABILITY_ALLOW_LIST[required.name];
+    if (allowed && !allowed.includes(manifest.id)) {
+      errors.push({
+        path: `requires.capabilities.${required.name}`,
+        message: `Capability '${required.name}' is a framework-granted privilege; only these modules may require it: ${allowed.join(', ')}. Module '${manifest.id}' is not on the allow-list.`,
+      });
+    }
+  }
+
+  for (const opt of manifest.optional?.capabilities ?? []) {
+    const allowed = PRIVILEGED_CAPABILITY_ALLOW_LIST[opt.name];
+    if (allowed && !allowed.includes(manifest.id)) {
+      errors.push({
+        path: `optional.capabilities.${opt.name}`,
+        message: `Capability '${opt.name}' is a framework-granted privilege; only these modules may declare it (including under optional): ${allowed.join(', ')}. Module '${manifest.id}' is not on the allow-list.`,
+      });
+    }
+  }
+
+  if (errors.length > 0) {
+    return { success: false, errors };
+  }
+  return null;
+}
+
 /**
  * Validate that variable sources are valid
  *

package/src/module/import.ts

@@ -16,6 +16,7 @@ import {
   validateDeriveFromSources,
   validateHookContract,
   validateManifest,
+  validatePrivilegedCapabilities,
   validateProvidesNoCrossCapabilityRefs,
   validateVariableSources,
   validateZoneRequirements,
@@ -184,6 +185,17 @@ export async function readModuleManifest(
     };
   }
 
+  const privilegedCapCheck = validatePrivilegedCapabilities(validationResult.data);
+  if (privilegedCapCheck) {
+    const errorMessages = privilegedCapCheck.errors
+      .map((e) => `${e.path}: ${e.message}`)
+      .join('\n');
+    return {
+      success: false,
+      error: `Privileged capability validation failed:\n${errorMessages}`,
+    };
+  }
+
   const variableSourceCheck = validateVariableSources(validationResult.data);
   if (variableSourceCheck) {
     const errorMessages = variableSourceCheck.errors

package/src/services/aspect-approvals.test.ts

@@ -0,0 +1,231 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { closeDb, getDb } from '../db/client';
+import { runMigrations } from '../db/migrate';
+import { modules } from '../db/schema';
+import type { BaseModuleAspect } from '../manifest/schema';
+import {
+  checkAspectApproval,
+  computeAspectScopeHash,
+  findAspectApproval,
+  recordAspectApproval,
+} from './aspect-approvals';
+
+const baseAspect: BaseModuleAspect = {
+  ansible_role: 'dns-client-config',
+  applicable_zones: ['dmz', 'app', 'secure'],
+  triggers: ['on_install'],
+};
+
+function insertModule(id: string, version: string) {
+  getDb()
+    .insert(modules)
+    .values({
+      id,
+      name: id,
+      version,
+      manifestData: { id, name: id, version, celilo_contract: '1.0' },
+      sourcePath: `/tmp/${id}`,
+    })
+    .run();
+}
+
+describe('aspect-approvals', () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'celilo-aspect-approvals-test-'));
+    process.env.CELILO_DB_PATH = join(dir, 'celilo.db');
+    await runMigrations(process.env.CELILO_DB_PATH);
+  });
+
+  afterEach(() => {
+    closeDb();
+    process.env.CELILO_DB_PATH = undefined;
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  });
+
+  describe('computeAspectScopeHash', () => {
+    it('is stable for the same scope', () => {
+      const h1 = computeAspectScopeHash(baseAspect);
+      const h2 = computeAspectScopeHash(baseAspect);
+      expect(h1).toBe(h2);
+    });
+
+    it('is the same regardless of zone or trigger order', () => {
+      const a: BaseModuleAspect = {
+        ansible_role: 'dns-client-config',
+        applicable_zones: ['app', 'dmz', 'secure'],
+        triggers: ['on_install', 'on_new_system_in_zone'],
+      };
+      const b: BaseModuleAspect = {
+        ansible_role: 'dns-client-config',
+        applicable_zones: ['secure', 'app', 'dmz'],
+        triggers: ['on_new_system_in_zone', 'on_install'],
+      };
+      expect(computeAspectScopeHash(a)).toBe(computeAspectScopeHash(b));
+    });
+
+    it('changes when applicable_zones changes', () => {
+      const a: BaseModuleAspect = { ...baseAspect, applicable_zones: ['dmz', 'app', 'secure'] };
+      const b: BaseModuleAspect = {
+        ...baseAspect,
+        applicable_zones: ['dmz', 'app', 'secure', 'internal'],
+      };
+      expect(computeAspectScopeHash(a)).not.toBe(computeAspectScopeHash(b));
+    });
+
+    it('changes when triggers change', () => {
+      const a: BaseModuleAspect = { ...baseAspect, triggers: ['on_install'] };
+      const b: BaseModuleAspect = {
+        ...baseAspect,
+        triggers: ['on_install', 'on_new_system_in_zone'],
+      };
+      expect(computeAspectScopeHash(a)).not.toBe(computeAspectScopeHash(b));
+    });
+
+    it('is unaffected by ansible_role changes', () => {
+      // ansible_role is intentionally NOT part of the scope hash —
+      // module authors evolve their role contents within an approved
+      // scope all the time.
+      const a: BaseModuleAspect = { ...baseAspect, ansible_role: 'old-role' };
+      const b: BaseModuleAspect = { ...baseAspect, ansible_role: 'new-role' };
+      expect(computeAspectScopeHash(a)).toBe(computeAspectScopeHash(b));
+    });
+  });
+
+  describe('recordAspectApproval + findAspectApproval', () => {
+    it('persists and reads back an approval', () => {
+      insertModule('knot-unbound-internal', '1.0.0');
+      const db = getDb();
+      const written = recordAspectApproval({
+        moduleId: 'knot-unbound-internal',
+        version: '1.0.0',
+        scopeHash: computeAspectScopeHash(baseAspect),
+        approver: 'testuser',
+        db,
+      });
+      expect(written.moduleId).toBe('knot-unbound-internal');
+      expect(written.version).toBe('1.0.0');
+      expect(written.approver).toBe('testuser');
+
+      const found = findAspectApproval('knot-unbound-internal', '1.0.0', db);
+      expect(found?.id).toBe(written.id);
+      expect(found?.scopeHash).toBe(written.scopeHash);
+    });
+
+    it('rejects duplicate (moduleId, version) via unique constraint', () => {
+      insertModule('knot-unbound-internal', '1.0.0');
+      const db = getDb();
+      recordAspectApproval({
+        moduleId: 'knot-unbound-internal',
+        version: '1.0.0',
+        scopeHash: 'abc',
+        approver: null,
+        db,
+      });
+      expect(() =>
+        recordAspectApproval({
+          moduleId: 'knot-unbound-internal',
+          version: '1.0.0',
+          scopeHash: 'def',
+          approver: null,
+          db,
+        }),
+      ).toThrow();
+    });
+
+    it('allows two approvals for the same module at different versions', () => {
+      insertModule('knot-unbound-internal', '1.0.0');
+      insertModule('knot-other', '1.0.0'); // unrelated; just keeping the test surface narrow
+      const db = getDb();
+      // Same module, but the test isolates versions by inserting a
+      // second row in `modules` first. We just want to verify the
+      // approvals table doesn't reject two rows with different
+      // versions.
+      db.insert(modules)
+        .values({
+          id: 'knot-unbound-internal-v2',
+          name: 'knot',
+          version: '2.0.0',
+          manifestData: { id: 'knot', name: 'knot', version: '2.0.0', celilo_contract: '1.0' },
+          sourcePath: '/tmp/knot',
+        })
+        .run();
+      recordAspectApproval({
+        moduleId: 'knot-unbound-internal',
+        version: '1.0.0',
+        scopeHash: 'abc',
+        approver: null,
+        db,
+      });
+      recordAspectApproval({
+        moduleId: 'knot-unbound-internal-v2',
+        version: '2.0.0',
+        scopeHash: 'def',
+        approver: null,
+        db,
+      });
+      expect(findAspectApproval('knot-unbound-internal', '1.0.0', db)?.scopeHash).toBe('abc');
+      expect(findAspectApproval('knot-unbound-internal-v2', '2.0.0', db)?.scopeHash).toBe('def');
+    });
+
+    it('returns undefined when there is no approval', () => {
+      const found = findAspectApproval('never-imported', '1.0.0', getDb());
+      expect(found).toBeUndefined();
+    });
+  });
+
+  describe('checkAspectApproval', () => {
+    it('returns "no_approval" when nothing is recorded', () => {
+      const status = checkAspectApproval('never-imported', '1.0.0', baseAspect, getDb());
+      expect(status).toBe('no_approval');
+    });
+
+    it('returns "approved" when an approval matches the current scope hash', () => {
+      insertModule('knot-unbound-internal', '1.0.0');
+      const db = getDb();
+      recordAspectApproval({
+        moduleId: 'knot-unbound-internal',
+        version: '1.0.0',
+        scopeHash: computeAspectScopeHash(baseAspect),
+        approver: null,
+        db,
+      });
+      const status = checkAspectApproval('knot-unbound-internal', '1.0.0', baseAspect, db);
+      expect(status).toBe('approved');
+    });
+
+    it('returns "scope_changed" when scope diverges from a prior approval', () => {
+      insertModule('knot-unbound-internal', '1.0.0');
+      const db = getDb();
+      const oldAspect: BaseModuleAspect = {
+        ansible_role: 'dns-client-config',
+        applicable_zones: ['app'],
+        triggers: ['on_install'],
+      };
+      recordAspectApproval({
+        moduleId: 'knot-unbound-internal',
+        version: '1.0.0',
+        scopeHash: computeAspectScopeHash(oldAspect),
+        approver: null,
+        db,
+      });
+      // Same version row, but the manifest's scope broadened — this is
+      // the D7 upgrade-changes-scope case.
+      const newAspect: BaseModuleAspect = {
+        ansible_role: 'dns-client-config',
+        applicable_zones: ['app', 'dmz', 'secure', 'internal'],
+        triggers: ['on_install'],
+      };
+      const status = checkAspectApproval('knot-unbound-internal', '1.0.0', newAspect, db);
+      expect(status).toBe('scope_changed');
+    });
+  });
+});

package/src/services/aspect-approvals.ts

@@ -0,0 +1,120 @@
+/**
+ * Aspect approvals — operator consent for a module's base-module aspect.
+ *
+ * Per v2/CELILO_BASE.md D2: when an operator imports a module that
+ * declares a `base_module_aspect`, they consent to that aspect's
+ * scope (applicable_zones + triggers) ONCE at import time. The
+ * consent is recorded in the `aspect_approvals` table and consulted
+ * before any aspect fan-out.
+ *
+ * D7 adds upgrade-scope detection: if a module version upgrade
+ * changes `applicable_zones` or `triggers`, the new version's
+ * scope_hash will differ from the prior approval's, signaling the
+ * framework that re-approval is required. Aspect-content-only
+ * changes (e.g., the Ansible role file got updated) DON'T change
+ * the scope_hash; they're allowed without re-prompting.
+ *
+ * The scope hash is a stable SHA-256 over the sorted JSON of the
+ * scope fields. Sorting matters: `[a, b]` and `[b, a]` should yield
+ * the same hash because zone order and trigger order don't carry
+ * semantic meaning.
+ */
+
+import { createHash, randomUUID } from 'node:crypto';
+import { and, eq } from 'drizzle-orm';
+import type { getDb } from '../db/client';
+import { aspectApprovals } from '../db/schema';
+import type { BaseModuleAspect } from '../manifest/schema';
+
+type DbClient = ReturnType<typeof getDb>;
+
+/**
+ * Compute a stable SHA-256 hash of the aspect's scope fields.
+ *
+ * The hash covers `applicable_zones` and `triggers` only — these
+ * are the fields the operator consents to. `ansible_role` is NOT
+ * part of the scope (a module author updating the role content
+ * within the approved zone set is normal evolution, captured by
+ * `on_aspect_change` rather than re-approval).
+ *
+ * Sorted so order doesn't affect the hash.
+ */
+export function computeAspectScopeHash(aspect: BaseModuleAspect): string {
+  const sortedZones = [...aspect.applicable_zones].sort();
+  const sortedTriggers = [...aspect.triggers].sort();
+  const canonical = JSON.stringify({
+    applicable_zones: sortedZones,
+    triggers: sortedTriggers,
+  });
+  return createHash('sha256').update(canonical).digest('hex');
+}
+
+/**
+ * Look up an existing approval for a (moduleId, version) pair.
+ * Returns the row if present, undefined otherwise.
+ */
+export function findAspectApproval(
+  moduleId: string,
+  version: string,
+  db: DbClient,
+): typeof aspectApprovals.$inferSelect | undefined {
+  return db
+    .select()
+    .from(aspectApprovals)
+    .where(and(eq(aspectApprovals.moduleId, moduleId), eq(aspectApprovals.version, version)))
+    .get();
+}
+
+/**
+ * Record operator approval for a module version's base-module
+ * aspect. Caller is responsible for verifying that an approval
+ * doesn't already exist (the unique constraint will reject
+ * duplicates, but callers should check first to provide a clear
+ * error path).
+ *
+ * @param approver - operator identifier (e.g., $USER). Null when
+ *   --accept-aspects is used in a context with no USER, or when
+ *   approval is automated.
+ */
+export function recordAspectApproval(args: {
+  moduleId: string;
+  version: string;
+  scopeHash: string;
+  approver: string | null;
+  db: DbClient;
+}): typeof aspectApprovals.$inferSelect {
+  const row = {
+    id: randomUUID(),
+    moduleId: args.moduleId,
+    version: args.version,
+    scopeHash: args.scopeHash,
+    approver: args.approver,
+  };
+  args.db.insert(aspectApprovals).values(row).run();
+  return args.db
+    .select()
+    .from(aspectApprovals)
+    .where(eq(aspectApprovals.id, row.id))
+    .get() as typeof aspectApprovals.$inferSelect;
+}
+
+/**
+ * Check whether the current (moduleId, version) has an approval
+ * whose scope matches the manifest's declared aspect. Returns:
+ *   - 'approved': there's an approval and its scope_hash matches
+ *   - 'scope_changed': there's an approval but the manifest's
+ *     scope is different (D7 — re-approval required before aspects
+ *     fan out under the new scope)
+ *   - 'no_approval': no approval row for this version
+ */
+export function checkAspectApproval(
+  moduleId: string,
+  version: string,
+  aspect: BaseModuleAspect,
+  db: DbClient,
+): 'approved' | 'scope_changed' | 'no_approval' {
+  const existing = findAspectApproval(moduleId, version, db);
+  if (!existing) return 'no_approval';
+  const currentHash = computeAspectScopeHash(aspect);
+  return existing.scopeHash === currentHash ? 'approved' : 'scope_changed';
+}