@celilo/cli 1.14.0 → 2.1.0

package/src/services/remote-access.ts

@@ -0,0 +1,149 @@
+/**
+ * D12's reachability policy: which remote targets a module may reach with the
+ * FLEET credential (openspec/changes/hook-process-boundary, stage 3).
+ *
+ * The rule: a module may reach the systems it provisioned — its own and its
+ * instances' (`ownedSystemModuleIds`, one indexed query because ownership is
+ * one level deep) — and reaches everything else through capabilities. The
+ * mount set is derived from the hook context; the reachable set is derived
+ * from the same identity.
+ *
+ * Two carve-outs, both following from "scoped by the CREDENTIAL":
+ *
+ *   - A request carrying the module's OWN credential (an identity key, or
+ *     `installAuthorizedKey`'s password) is not riding the fleet key at all.
+ *     The credential is the scope: it works exactly where its holder was
+ *     given access, which celilo neither grants nor needs to police.
+ *   - An explicit NON-ROOT user. The fleet key's authority is root on the
+ *     systems celilo provisions — that is the only place celilo installs it.
+ *     A non-root account trusts it only where an operator deliberately put it
+ *     there (the cPanel bootstrap installs it into an unprivileged hosting
+ *     account), and refusing those would break every off-fleet provider while
+ *     protecting nothing the key actually unlocks. The residual — an operator
+ *     who installed the fleet key as root on an OFF-fleet box — is refused
+ *     until that target carries its own identity, and design D12 records it.
+ *
+ * **Attribution (D12, task 5.1b).** A policy is built for the module that
+ * PERFORMS the operation, never the one that asked for it. For a hook that is
+ * the hook's module — the nine `invokeHook` call sites construct it with the
+ * id they are invoking. A capability provider's internal transport belongs to
+ * the provider's module; providers run in celilo's own process today (design
+ * D10), so their transport does not cross the remote-ops broker, and the one
+ * hand-built-ssh provider site (`public_web`'s upload) is being replaced by
+ * an Ansible converge under `openspec/changes/capability-owned-tables`
+ * (celilo#1014). If provider transport is ever brokered, it takes a policy
+ * built with the PROVIDER's id from this same function — neither "the calling
+ * module's systems" nor an exemption.
+ *
+ * Policy function (Rule 10.1) — decides; the remote-ops broker enforces.
+ */
+
+import { eq } from 'drizzle-orm';
+import type { DbClient } from '../db/client';
+import { capabilities, machines, moduleConfigs, moduleSystems } from '../db/schema';
+import type { RemoteAccessPolicy } from '../hooks/remote-broker';
+import { getModuleSystems } from './deployed-systems';
+import { ownedSystemModuleIds } from './module-instances';
+
+/** Build the policy one hook run's remote operations are checked against. */
+export function remoteAccessPolicy(moduleId: string, db: DbClient): RemoteAccessPolicy {
+  return {
+    moduleId,
+    checkTarget(target, hasOwnCredential) {
+      if (hasOwnCredential) return { allowed: true };
+      if (target.user !== undefined && target.user !== 'root') return { allowed: true };
+
+      // Queried per call rather than snapshotted at invoke time, so a system
+      // recorded mid-run (a provider arrival) is visible to the next check.
+      const owned = ownedSystemModuleIds(moduleId, db).flatMap((id) => getModuleSystems(id, db));
+      if (owned.some((system) => system.ipv4_address === target.ipv4_address)) {
+        return { allowed: true };
+      }
+
+      if (managesPoolMachine(moduleId, target.ipv4_address, db)) {
+        return { allowed: true };
+      }
+
+      return { allowed: false, message: refusalMessage(moduleId, target.ipv4_address, db) };
+    },
+  };
+}
+
+/**
+ * A machine in celilo's pool that this module's own config names.
+ *
+ * ## The case this exists for
+ *
+ * A module that MANAGES a pre-existing box rather than being deployed onto one
+ * — `iptables` configuring the firewall is the archetype — provisions no system
+ * and therefore never owns one. `module_systems` records nothing for a
+ * config-only module at any point in its lifecycle, so the owned-systems branch
+ * above cannot ever pass for it. Without this, such a module has no sanctioned
+ * path to the one box it exists to configure, and no amount of waiting fixes it
+ * (celilo#1225).
+ *
+ * ## Why this is not a module granting itself reach
+ *
+ * Both halves are the OPERATOR's acts, and a module can supply neither:
+ *
+ *   - The address is in the machine pool. `celilo machine add <ip> --ssh-key…`
+ *     is the operator saying celilo may use its credential on that box. The
+ *     fleet key's authority is exactly the set of boxes celilo was given, and
+ *     this is that set — the same reasoning as the non-root carve-out above.
+ *   - The module's own config names that address. `firewall_ip` is
+ *     `source: user, required: true`; an operator typed it.
+ *
+ * A module declares which config KEYS exist, never their values, so it cannot
+ * point itself at a box the operator did not both admit to the pool and assign
+ * to it. Two independent operator decisions have to agree.
+ *
+ * ## What it deliberately does not do
+ *
+ * It does not allow every pool machine. That would let any module reach any box
+ * celilo knows, which is far wider than the rule this file states. The
+ * intersection is the point: pool membership alone is not authorization, and
+ * config alone is not either.
+ */
+function managesPoolMachine(moduleId: string, ipv4Address: string, db: DbClient): boolean {
+  const inPool = db.select().from(machines).where(eq(machines.ipAddress, ipv4Address)).get();
+  if (!inPool) return false;
+
+  return db
+    .select({ value: moduleConfigs.value })
+    .from(moduleConfigs)
+    .where(eq(moduleConfigs.moduleId, moduleId))
+    .all()
+    .some((row) => row.value === ipv4Address);
+}
+
+/**
+ * Name the module, the target, and the capability route (task 5.2). The owner
+ * lookup is best-effort colour: the refusal stands whether or not celilo can
+ * say whose system it is.
+ */
+function refusalMessage(moduleId: string, ipv4Address: string, db: DbClient): string {
+  const preamble = `Module '${moduleId}' may not reach ${ipv4Address}: it is not a system this module (or one of its instances) provisioned.`;
+  const guidance =
+    'A hook reaches its own systems via ctx.systems and everything else through a capability (hook-process-boundary, design D12).';
+
+  const owner = db
+    .select()
+    .from(moduleSystems)
+    .where(eq(moduleSystems.ipv4Address, ipv4Address))
+    .get();
+  if (!owner) return `${preamble} ${guidance}`;
+
+  const provided = db
+    .select({ capabilityName: capabilities.capabilityName })
+    .from(capabilities)
+    .where(eq(capabilities.moduleId, owner.moduleId))
+    .all()
+    .map((row) => row.capabilityName);
+
+  const route =
+    provided.length > 0
+      ? `Reach it through a capability it provides ('${provided.join("', '")}').`
+      : "Reach it through a capability, never by SSH from another module's hook.";
+
+  return `${preamble} That system ('${owner.hostname}') belongs to module '${owner.moduleId}'. ${route}`;
+}

package/src/services/restore-from-file.ts

@@ -54,6 +54,7 @@ import {
   refuseIfInFlight,
   startOperation,
 } from './module-operations';
+import { remoteAccessPolicy } from './remote-access';
 
 export interface RestoreFromFileResult {
   success: boolean;
@@ -216,7 +217,11 @@ export async function restoreFromArtifactFile(
       {},
       {},
       logger,
-      { debug: false, systems: getModuleSystems(mod.id, db) },
+      {
+        debug: false,
+        systems: getModuleSystems(mod.id, db),
+        remoteAccess: remoteAccessPolicy(mod.id, db),
+      },
     );
     if (!hookResult.success) {
       const errMsg = hookResult.error ?? 'on_restore hook failed';

package/src/services/static-content-converge.test.ts

@@ -0,0 +1,338 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { eq } from 'drizzle-orm';
+import type { DbClient } from '../db/client';
+import { moduleConfigs, modules, webRoutes } from '../db/schema';
+import { setupTestDatabaseAt } from '../test-utils/database';
+import {
+  buildStaticContentPlan,
+  planStaticContent,
+  resolveStaticContentRetention,
+  staticContentVarsPath,
+  staticContentVarsYaml,
+  writeStaticContentVars,
+} from './static-content-converge';
+
+const HASH1 = 'a'.repeat(64);
+const HASH2 = 'b'.repeat(64);
+
+describe('planStaticContent — the declared release set (D10 task 4.1)', () => {
+  let dir: string;
+  let db: DbClient;
+
+  beforeEach(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'static-converge-'));
+    const dbPath = join(dir, 'celilo.db');
+    process.env.CELILO_DB_PATH = dbPath;
+    db = await setupTestDatabaseAt(dbPath);
+
+    // Two installed modules with real web roots on disk.
+    writeSite('lunacycle', '<html>luna</html>');
+    writeSite('hello-foo', '<html>foo</html>');
+    db.insert(modules)
+      .values({
+        id: 'lunacycle',
+        name: 'Lunacycle',
+        version: '1.0.0',
+        manifestData: {},
+        sourcePath: join(dir, 'modules', 'lunacycle'),
+      })
+      .onConflictDoNothing()
+      .run();
+    db.insert(modules)
+      .values({
+        id: 'hello-foo',
+        name: 'Hello Foo',
+        version: '0.1.2',
+        manifestData: {},
+        sourcePath: join(dir, 'modules', 'hello-foo'),
+      })
+      .onConflictDoNothing()
+      .run();
+  });
+
+  afterEach(() => {
+    db.$client.close();
+    process.env.CELILO_DB_PATH = undefined;
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  });
+
+  function writeSite(moduleId: string, html: string): string {
+    const webRoot = join(dir, 'modules', moduleId, 'site', 'dist');
+    mkdirSync(webRoot, { recursive: true });
+    writeFileSync(join(webRoot, 'index.html'), html, 'utf-8');
+    return webRoot;
+  }
+
+  function insertRoute(route: {
+    slug: string;
+    moduleId: string;
+    hostname: string;
+    path?: string;
+    type?: 'static' | 'reverse_proxy';
+    contentHash?: string | null;
+  }) {
+    db.insert(webRoutes)
+      .values({
+        slug: route.slug,
+        moduleId: route.moduleId,
+        type: route.type ?? 'static',
+        path: route.path ?? '/',
+        hostname: route.hostname,
+        websocket: false,
+        contentHash: route.contentHash ?? HASH1,
+      })
+      .run();
+  }
+
+  it('groups by slug across hostnames and derives the source dir', () => {
+    insertRoute({ slug: 'lunacycle', moduleId: 'lunacycle', hostname: 'lunacycle.net' });
+    insertRoute({
+      slug: 'lunacycle',
+      moduleId: 'lunacycle',
+      hostname: 'www.example.com',
+      path: '/x',
+    });
+    insertRoute({
+      slug: 'hello-foo',
+      moduleId: 'hello-foo',
+      hostname: 'www.example.com',
+      path: '/foo',
+    });
+
+    const releases = planStaticContent(db);
+
+    // Reverse-proxy rows and rows without a hash are not releases.
+    expect(releases).toHaveLength(2);
+    const luna = releases.find((r) => r.slug === 'lunacycle');
+    expect(luna?.hostnames).toEqual(['lunacycle.net', 'www.example.com']);
+    expect(luna?.sourceDir).toBe(join(dir, 'modules', 'lunacycle', 'site', 'dist'));
+    expect(luna?.contentHash).toBe(HASH1);
+  });
+
+  it('a slug claimed by two modules is a contradiction, not a merge', () => {
+    insertRoute({ slug: 'about', moduleId: 'lunacycle', hostname: 'a.example.com' });
+    insertRoute({ slug: 'about', moduleId: 'hello-foo', hostname: 'b.example.com' });
+
+    expect(() => planStaticContent(db)).toThrow(/claimed by 2 modules/);
+  });
+
+  it('rows sharing a slug must share a hash', () => {
+    insertRoute({ slug: 'lunacycle', moduleId: 'lunacycle', hostname: 'lunacycle.net' });
+    insertRoute({
+      slug: 'lunacycle',
+      moduleId: 'lunacycle',
+      hostname: 'www.example.com',
+      path: '/x',
+      contentHash: HASH2,
+    });
+
+    expect(() => planStaticContent(db)).toThrow(/content hashes/);
+  });
+
+  it('a missing web root fails loudly instead of converging an empty release', () => {
+    insertRoute({ slug: 'lunacycle', moduleId: 'lunacycle', hostname: 'lunacycle.net' });
+    rmSync(join(dir, 'modules', 'lunacycle', 'site', 'dist'), { recursive: true, force: true });
+
+    expect(() => planStaticContent(db)).toThrow(/no built site/);
+  });
+});
+
+describe('resolveStaticContentRetention — operator config with a default', () => {
+  let dir: string;
+  let db: DbClient;
+
+  beforeEach(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'static-retention-'));
+    process.env.CELILO_DB_PATH = join(dir, 'celilo.db');
+    db = await setupTestDatabaseAt(join(dir, 'celilo.db'));
+    db.insert(modules)
+      .values({
+        id: 'caddy',
+        name: 'Caddy',
+        version: '2.3.8',
+        manifestData: {
+          variables: { owns: [{ name: 'static_release_retention', default: 5 }] },
+        },
+        sourcePath: join(dir, 'modules', 'caddy'),
+      })
+      .onConflictDoNothing()
+      .run();
+  });
+
+  afterEach(() => {
+    db.$client.close();
+    process.env.CELILO_DB_PATH = undefined;
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  });
+
+  it('operator config wins over the manifest default', () => {
+    db.insert(moduleConfigs)
+      .values({ moduleId: 'caddy', key: 'static_release_retention', value: '2', valueJson: '2' })
+      .run();
+    expect(resolveStaticContentRetention(db, 'caddy')).toBe(2);
+  });
+
+  it('falls back to the manifest default, then the constant', () => {
+    expect(resolveStaticContentRetention(db, 'caddy')).toBe(5);
+
+    db.update(modules).set({ manifestData: {} }).where(eq(modules.id, 'caddy')).run();
+    expect(resolveStaticContentRetention(db, 'caddy')).toBe(5);
+  });
+
+  it('rejects a retention that cannot keep the current release', () => {
+    db.insert(moduleConfigs)
+      .values({ moduleId: 'caddy', key: 'static_release_retention', value: '0', valueJson: '0' })
+      .run();
+    expect(() => resolveStaticContentRetention(db, 'caddy')).toThrow(/positive integer/);
+  });
+});
+
+describe('staticContentVarsYaml — deterministic desired state', () => {
+  it('carries slug, content_hash, hostnames and the derived source dir, keyed by slug', () => {
+    const yaml = staticContentVarsYaml({
+      retention: 3,
+      releases: [
+        {
+          slug: 'hello-foo',
+          contentHash: HASH2,
+          hostnames: ['www.example.com'],
+          sourceDir: '/data/modules/hello-foo/site/dist',
+        },
+        {
+          slug: 'lunacycle',
+          contentHash: HASH1,
+          hostnames: ['lunacycle.net', 'www.example.com'],
+          sourceDir: '/data/modules/lunacycle/site/dist',
+        },
+      ],
+    });
+
+    expect(yaml).toContain('static_release_retention: 3');
+    expect(yaml).toContain('slug: lunacycle');
+    expect(yaml).toContain(`content_hash: ${HASH1}`);
+    expect(yaml).toContain('source_dir: /data/modules/lunacycle/site/dist');
+    // Deterministic: same input, same bytes — the idempotence of the WRITE
+    // depends on it.
+    expect(yaml).toBe(
+      staticContentVarsYaml({
+        retention: 3,
+        releases: [
+          {
+            slug: 'hello-foo',
+            contentHash: HASH2,
+            hostnames: ['www.example.com'],
+            sourceDir: '/data/modules/hello-foo/site/dist',
+          },
+          {
+            slug: 'lunacycle',
+            contentHash: HASH1,
+            hostnames: ['lunacycle.net', 'www.example.com'],
+            sourceDir: '/data/modules/lunacycle/site/dist',
+          },
+        ],
+      }),
+    );
+  });
+});
+
+describe('writeStaticContentVars — lands in the generated inventory', () => {
+  let dir: string;
+  let db: DbClient;
+
+  beforeEach(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'static-vars-'));
+    process.env.CELILO_DB_PATH = join(dir, 'celilo.db');
+    db = await setupTestDatabaseAt(join(dir, 'celilo.db'));
+    mkdirSync(join(dir, 'modules', 'caddy', 'site', 'dist'), { recursive: true });
+    writeFileSync(
+      join(dir, 'modules', 'caddy', 'site', 'dist', 'index.html'),
+      '<html>caddy</html>',
+      'utf-8',
+    );
+    db.insert(modules)
+      .values({
+        id: 'caddy',
+        name: 'Caddy',
+        version: '2.3.8',
+        manifestData: {},
+        sourcePath: join(dir, 'modules', 'caddy'),
+      })
+      .onConflictDoNothing()
+      .run();
+  });
+
+  afterEach(() => {
+    db.$client.close();
+    process.env.CELILO_DB_PATH = undefined;
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  });
+
+  it('writes the vars file and never writes into a module tree (task 4.7)', async () => {
+    db.insert(webRoutes)
+      .values({
+        slug: 'caddy',
+        moduleId: 'caddy',
+        type: 'static',
+        path: '/',
+        hostname: 'www.example.com',
+        websocket: false,
+        contentHash: HASH1,
+      })
+      .run();
+
+    const moduleTreeBefore = readFileSync(
+      join(dir, 'modules', 'caddy', 'site', 'dist', 'index.html'),
+      'utf-8',
+    );
+    const result = await writeStaticContentVars(
+      db,
+      'caddy',
+      join(dir, 'modules', 'caddy', 'generated'),
+    );
+
+    expect(result.success).toBe(true);
+    const varsPath = staticContentVarsPath(join(dir, 'modules', 'caddy', 'generated'));
+    expect(existsSync(varsPath)).toBe(true);
+    expect(readFileSync(varsPath, 'utf-8')).toContain('slug: caddy');
+
+    // Task 4.7: the converge path is read-only over the module tree. The
+    // clientConfig write into it is celilo#1018 and belongs to that thread —
+    // THIS path must not add a second writer.
+    expect(readFileSync(join(dir, 'modules', 'caddy', 'site', 'dist', 'index.html'), 'utf-8')).toBe(
+      moduleTreeBefore,
+    );
+  });
+
+  it('buildStaticContentPlan carries the resolved retention alongside the releases', async () => {
+    db.insert(webRoutes)
+      .values({
+        slug: 'caddy',
+        moduleId: 'caddy',
+        type: 'static',
+        path: '/',
+        hostname: 'www.example.com',
+        websocket: false,
+        contentHash: HASH1,
+      })
+      .run();
+
+    const plan = buildStaticContentPlan(db, 'caddy');
+    expect(plan.retention).toBe(5);
+    expect(plan.releases).toHaveLength(1);
+  });
+});