@celilo/cli 0.3.30 → 0.4.0-alpha.1

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

@@ -0,0 +1,355 @@
+/**
+ * File-direct restore + system-file swap. Powers the `celilo restore`
+ * top-level convenience command (Phase 4 of v2/SYSTEM_BACKUP_TERRAFORM_STATE.md).
+ *
+ * The generic `restoreModuleBackup` reads from a configured storage
+ * destination — which on a fresh-bootstrap box doesn't exist yet.
+ * `restoreFromArtifactFile` takes a local file path directly: decrypts
+ * + extracts + validates the envelope, then invokes the module's
+ * on_restore hook through the same plumbing (cross_module_write_root
+ * apply, in-flight refusal, operation tracking).
+ *
+ * After the hook returns, `applyStagedSystemFiles` picks up the
+ * celilo.db + master.key that celilo-mgmt's on_restore staged under
+ * restore_dir/system/, closes the live DB, copies them into place,
+ * and runs Drizzle migrations on the restored DB. This is the chunk
+ * of the restore the hook itself cannot do (live DB is open).
+ */
+
+import { execSync } from 'node:child_process';
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { eq } from 'drizzle-orm';
+import { getDbPath, getMasterKeyPath } from '../config/paths';
+import { closeDb, getDb } from '../db/client';
+import { runMigrations } from '../db/migrate';
+import { modules } from '../db/schema';
+import { invokeHook } from '../hooks/executor';
+import { createConsoleLogger } from '../hooks/logger';
+import type { ModuleManifest } from '../manifest/schema';
+import { decryptSecret } from '../secrets/encryption';
+import { getOrCreateMasterKey } from '../secrets/master-key';
+import { shellEscape } from '../utils/shell';
+import { assertCompatibleSchema, parseManifest } from './backup-manifest';
+import { applyCrossModuleWriteRoot, moduleHasCrossModuleRead } from './cross-module-read';
+import { getModuleSystems } from './deployed-systems';
+import {
+  completeOperation,
+  failOperation,
+  refuseIfInFlight,
+  startOperation,
+} from './module-operations';
+
+export interface RestoreFromFileResult {
+  success: boolean;
+  error?: string;
+  /** Module IDs whose cross-module TF state was applied. */
+  crossModuleApplied?: string[];
+  /** Was celilo.db swapped into place? */
+  systemDbApplied?: boolean;
+  /** Was master.key swapped into place? */
+  masterKeyApplied?: boolean;
+  /** Was the fleet SSH keypair restored to <dataDir>/.ssh/? */
+  sshKeyApplied?: boolean;
+}
+
+export interface RestoreFromFileOptions {
+  /** Allow restoring onto a populated target. Default false (refuse). */
+  force?: boolean;
+}
+
+/**
+ * Decrypt + extract a backup artifact file, invoke the module's
+ * on_restore hook, apply cross-module write-back, and apply staged
+ * system files (celilo.db + master.key). Returns a result describing
+ * what landed.
+ *
+ * The module identified by the artifact's manifest.json MUST already
+ * exist in the DB. The `celilo restore` CLI handler (Phase 4) ensures
+ * this — on truly fresh bootstrap, bootstrap.sh imports celilo-mgmt
+ * from the registry before invoking restore.
+ */
+export async function restoreFromArtifactFile(
+  filePath: string,
+  _options: RestoreFromFileOptions = {},
+): Promise<RestoreFromFileResult> {
+  // refuseIfInFlight() before anything else — a restore alongside an
+  // active deploy would race with whichever process holds DB locks.
+  refuseIfInFlight();
+
+  if (!existsSync(filePath)) {
+    return { success: false, error: `Artifact not found: ${filePath}` };
+  }
+
+  // 1. Decrypt the encrypted envelope (JSON wrapper, identical to the
+  //    shape backup-create.ts writes).
+  let masterKey: Buffer;
+  try {
+    masterKey = await getOrCreateMasterKey();
+  } catch (err) {
+    return {
+      success: false,
+      error: `Cannot read master key: ${err instanceof Error ? err.message : String(err)}. The current master key must match the one the artifact was encrypted with.`,
+    };
+  }
+
+  let encryptedJson: unknown;
+  try {
+    encryptedJson = JSON.parse(readFileSync(filePath, 'utf-8'));
+  } catch (err) {
+    return {
+      success: false,
+      error: `Artifact is not valid JSON: ${err instanceof Error ? err.message : String(err)}. The file may be corrupted or not a celilo backup artifact.`,
+    };
+  }
+
+  const tempDir = join(tmpdir(), `celilo-restore-from-file-${Date.now()}`);
+  const envelopeDir = join(tempDir, 'envelope');
+
+  try {
+    mkdirSync(envelopeDir, { recursive: true });
+
+    // Decrypt the JSON wrapper into the inner tar bytes.
+    let tarData: Buffer;
+    try {
+      const base64 = decryptSecret(encryptedJson as Parameters<typeof decryptSecret>[0], masterKey);
+      tarData = Buffer.from(base64, 'base64');
+    } catch (err) {
+      return {
+        success: false,
+        error: `Decryption failed: ${err instanceof Error ? err.message : String(err)}. The master key may not match the one used at backup time.`,
+      };
+    }
+
+    // Extract the envelope tar.
+    const tarPath = join(tempDir, 'envelope.tar');
+    writeFileSync(tarPath, tarData);
+    execSync(`tar -xf ${shellEscape(tarPath)} -C ${shellEscape(envelopeDir)}`);
+
+    // 2. Read + validate the envelope manifest.
+    const manifestPath = join(envelopeDir, 'manifest.json');
+    if (!existsSync(manifestPath)) {
+      return {
+        success: false,
+        error:
+          'Artifact has no manifest.json. It may be from an older celilo (pre-envelope format) or corrupted.',
+      };
+    }
+    const envelopeManifest = parseManifest(readFileSync(manifestPath, 'utf-8'));
+    assertCompatibleSchema(envelopeManifest);
+    if (envelopeManifest.kind !== 'module') {
+      return {
+        success: false,
+        error: `Artifact kind is '${envelopeManifest.kind}', expected 'module'. (System artifacts shouldn't reach restore-from-file; use 'celilo backup restore' for those.)`,
+      };
+    }
+
+    const moduleId = envelopeManifest.moduleId;
+    if (!moduleId) {
+      return {
+        success: false,
+        error: "Artifact manifest doesn't name a moduleId. The artifact may be corrupted.",
+      };
+    }
+
+    const restoreDataDir = join(envelopeDir, 'data');
+    if (!existsSync(restoreDataDir)) {
+      return { success: false, error: 'Artifact has no data/ directory.' };
+    }
+
+    // 3. Look up the module's on_restore hook. The DB must already
+    //    have the module — bootstrap.sh's job is to import celilo-mgmt
+    //    before reaching restore.
+    const db = getDb();
+    const mod = db.select().from(modules).where(eq(modules.id, moduleId)).get();
+    if (!mod) {
+      return {
+        success: false,
+        error: `Module '${moduleId}' is not imported. Run 'celilo module import ${moduleId}' first (or use the bootstrap.sh script which handles this for you).`,
+      };
+    }
+    const manifest = mod.manifestData as unknown as ModuleManifest;
+    const hookDef = manifest.hooks?.on_restore;
+    if (!hookDef) {
+      return {
+        success: false,
+        error: `Module '${moduleId}' has no on_restore hook defined.`,
+      };
+    }
+
+    // 4. Set up cross-module write-back staging if the privilege is
+    //    granted. Same pattern as restoreModuleBackup.
+    const opId = startOperation(moduleId, 'restore');
+    const hookInputs: Record<string, unknown> = {
+      restore_dir: restoreDataDir,
+      schema_version: envelopeManifest.dataSchemaVersion ?? '',
+    };
+    let crossModuleWriteRoot: string | undefined;
+    if (moduleHasCrossModuleRead(manifest)) {
+      crossModuleWriteRoot = join(tempDir, 'cross-module-write');
+      mkdirSync(crossModuleWriteRoot, { recursive: true });
+      hookInputs.cross_module_write_root = crossModuleWriteRoot;
+    }
+
+    // 5. Invoke the hook.
+    const logger = createConsoleLogger(mod.id, 'on_restore');
+    const hookResult = await invokeHook(
+      mod.sourcePath,
+      'on_restore',
+      manifest.celilo_contract,
+      hookDef,
+      hookInputs,
+      {},
+      {},
+      logger,
+      { debug: false, systems: getModuleSystems(mod.id, db) },
+    );
+    if (!hookResult.success) {
+      const errMsg = hookResult.error ?? 'on_restore hook failed';
+      failOperation(opId, errMsg);
+      return { success: false, error: errMsg };
+    }
+
+    // 6. Apply cross-module write-back (atomic rotate-into-place).
+    let crossModuleApplied: string[] = [];
+    if (crossModuleWriteRoot) {
+      try {
+        const applyResult = applyCrossModuleWriteRoot(crossModuleWriteRoot);
+        crossModuleApplied = applyResult.applied;
+      } catch (err) {
+        const errMsg = `cross_module_write_root apply failed: ${err instanceof Error ? err.message : String(err)}`;
+        failOperation(opId, errMsg);
+        return { success: false, error: errMsg };
+      }
+    }
+
+    // 7. Apply staged system files (celilo.db + master.key).
+    //    These were staged by celilo-mgmt's on_restore at
+    //    restore_dir/system/. The live process has the DB open, so
+    //    this swap must happen AFTER the hook returns (which is now).
+    const systemStaging = join(restoreDataDir, 'system');
+    const apply = applyStagedSystemFiles(systemStaging);
+
+    completeOperation(opId);
+
+    return {
+      success: true,
+      crossModuleApplied,
+      systemDbApplied: apply.dbApplied,
+      masterKeyApplied: apply.keyApplied,
+      sshKeyApplied: apply.sshApplied,
+    };
+  } finally {
+    try {
+      rmSync(tempDir, { recursive: true, force: true });
+    } catch {
+      /* best-effort cleanup */
+    }
+  }
+}
+
+export interface StagedSystemApplyResult {
+  dbApplied: boolean;
+  keyApplied: boolean;
+  sshApplied: boolean;
+}
+
+/**
+ * Picks up the celilo.db + master.key that celilo-mgmt's on_restore
+ * staged under <restore_dir>/system/, closes the live DB, and copies
+ * each into its live path. Then runs Drizzle migrations on the
+ * restored DB so a snapshot from an older celilo can still be opened.
+ *
+ * Skips files that aren't present — restoring just a master.key (no
+ * DB) is a valid use case (e.g., recovering from a lost-key scenario
+ * without a full system restore).
+ *
+ * Exported for direct use by callers that don't go through
+ * restoreFromArtifactFile (tests, future system-only restore paths).
+ */
+export function applyStagedSystemFiles(systemStagingDir: string): StagedSystemApplyResult {
+  let dbApplied = false;
+  let keyApplied = false;
+  let sshApplied = false;
+
+  if (!existsSync(systemStagingDir)) {
+    return { dbApplied, keyApplied, sshApplied };
+  }
+
+  const stagedDb = join(systemStagingDir, 'celilo.db');
+  const stagedKey = join(systemStagingDir, 'master.key');
+  const stagedSsh = join(systemStagingDir, 'ssh');
+
+  // master.key first: it's not load-bearing for the running process
+  // (already in memory if the daemon's running). Safe to swap before
+  // closing the DB.
+  if (existsSync(stagedKey)) {
+    const livePath = getMasterKeyPath();
+    mkdirSync(join(livePath, '..'), { recursive: true });
+    copyFileSync(stagedKey, livePath);
+    keyApplied = true;
+  }
+
+  // Fleet SSH keypair → <dataDir>/.ssh/, restoring strict perms (the dir
+  // 0700, private key 0600, public 0644). celilo uses this key to reach
+  // managed machines; the DB only carries the public half, so without the
+  // private half on disk the restored box can't authenticate to the fleet.
+  if (existsSync(stagedSsh)) {
+    // The fleet key lives next to the DB (on_install writes it to
+    // dirname(db_path)/.ssh), so follow the DB's location — not getDataDir()
+    // — in case CELILO_DB_PATH points somewhere custom.
+    const liveSshDir = join(dirname(getDbPath()), '.ssh');
+    mkdirSync(liveSshDir, { recursive: true, mode: 0o700 });
+    chmodSync(liveSshDir, 0o700);
+    for (const entry of readdirSync(stagedSsh)) {
+      const dest = join(liveSshDir, entry);
+      copyFileSync(join(stagedSsh, entry), dest);
+      chmodSync(dest, entry.endsWith('.pub') ? 0o644 : 0o600);
+    }
+    sshApplied = true;
+  }
+
+  // celilo.db: must close the live DB connection before replacing
+  // the file or SQLite gets confused (macOS holds a vnode handle).
+  if (existsSync(stagedDb)) {
+    closeDb();
+    const livePath = getDbPath();
+    mkdirSync(join(livePath, '..'), { recursive: true });
+    copyFileSync(stagedDb, livePath);
+
+    // Stale WAL/SHM siblings would corrupt the restored DB.
+    for (const suffix of ['-wal', '-shm']) {
+      try {
+        rmSync(`${livePath}${suffix}`, { force: true });
+      } catch {
+        /* may not exist */
+      }
+    }
+    dbApplied = true;
+  }
+
+  return { dbApplied, keyApplied, sshApplied };
+}
+
+/**
+ * Migrate the restored DB to the current celilo build's schema. Called
+ * by the CLI handler after applyStagedSystemFiles so a backup from an
+ * older celilo still opens cleanly. Pure I/O wrapper around
+ * `runMigrations` exposed here so the same orchestration lives next
+ * to the swap logic.
+ */
+export async function migrateRestoredDb(): Promise<void> {
+  const dbPath = getDbPath();
+  if (!existsSync(dbPath)) return;
+  await runMigrations(dbPath);
+}

package/src/services/restore-preflight.test.ts

@@ -0,0 +1,127 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } 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 {
+  NonEmptyRestoreTargetError,
+  assertRestoreTargetEmpty,
+  surveyRestoreTarget,
+} from './restore-preflight';
+
+describe('restore pre-flight', () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'celilo-preflight-test-'));
+    process.env.CELILO_DB_PATH = join(dir, 'celilo.db');
+    process.env.CELILO_DATA_DIR = dir;
+    await runMigrations(process.env.CELILO_DB_PATH);
+  });
+
+  afterEach(() => {
+    closeDb();
+    process.env.CELILO_DB_PATH = undefined;
+    process.env.CELILO_DATA_DIR = undefined;
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  });
+
+  it('reports empty when DB has no modules and no TF state on disk', () => {
+    const report = surveyRestoreTarget();
+    expect(report.empty).toBe(true);
+    expect(report.modulesInDb).toEqual([]);
+    expect(report.modulesWithTerraformState).toEqual([]);
+  });
+
+  it('reports modulesInDb when modules exist in the DB', () => {
+    const db = getDb();
+    db.insert(modules)
+      .values({
+        id: 'homebridge',
+        name: 'homebridge',
+        version: '0.1.0',
+        sourcePath: '/tmp/fake',
+        manifestData: {} as Record<string, unknown>,
+      })
+      .run();
+
+    const report = surveyRestoreTarget();
+    expect(report.empty).toBe(false);
+    expect(report.modulesInDb).toEqual(['homebridge']);
+  });
+
+  it('reports modulesWithTerraformState when a tfstate file exists on disk', () => {
+    const tfDir = join(dir, 'modules', 'caddy', 'generated', 'terraform');
+    mkdirSync(tfDir, { recursive: true });
+    writeFileSync(join(tfDir, 'terraform.tfstate'), '{}');
+
+    const report = surveyRestoreTarget();
+    expect(report.empty).toBe(false);
+    expect(report.modulesWithTerraformState).toEqual(['caddy']);
+  });
+
+  it('treats an empty terraform/ dir as no state', () => {
+    const tfDir = join(dir, 'modules', 'half-installed', 'generated', 'terraform');
+    mkdirSync(tfDir, { recursive: true });
+
+    const report = surveyRestoreTarget();
+    expect(report.empty).toBe(true);
+    expect(report.modulesWithTerraformState).toEqual([]);
+  });
+
+  describe('assertRestoreTargetEmpty', () => {
+    it('does not throw on a fresh target', () => {
+      expect(() => assertRestoreTargetEmpty()).not.toThrow();
+    });
+
+    it('throws NonEmptyRestoreTargetError on a populated DB', () => {
+      const db = getDb();
+      db.insert(modules)
+        .values({
+          id: 'homebridge',
+          name: 'homebridge',
+          version: '0.1.0',
+          sourcePath: '/tmp/fake',
+          manifestData: {} as Record<string, unknown>,
+        })
+        .run();
+
+      expect(() => assertRestoreTargetEmpty()).toThrow(NonEmptyRestoreTargetError);
+    });
+
+    it('error message names the conflicting modules + suggests --force', () => {
+      const db = getDb();
+      db.insert(modules)
+        .values({
+          id: 'homebridge',
+          name: 'homebridge',
+          version: '0.1.0',
+          sourcePath: '/tmp/fake',
+          manifestData: {} as Record<string, unknown>,
+        })
+        .run();
+
+      const tfDir = join(dir, 'modules', 'caddy', 'generated', 'terraform');
+      mkdirSync(tfDir, { recursive: true });
+      writeFileSync(join(tfDir, 'terraform.tfstate'), '{}');
+
+      try {
+        assertRestoreTargetEmpty();
+      } catch (err) {
+        expect(err).toBeInstanceOf(NonEmptyRestoreTargetError);
+        const msg = (err as Error).message;
+        expect(msg).toContain('homebridge');
+        expect(msg).toContain('caddy');
+        expect(msg).toContain('--force');
+        return;
+      }
+      throw new Error('expected assertRestoreTargetEmpty to throw');
+    });
+  });
+});

package/src/services/restore-preflight.ts

@@ -0,0 +1,118 @@
+/**
+ * Pre-flight check for the celilo restore command. Refuses to run on a
+ * target that already holds celilo state -- restoring onto a working
+ * management server would clobber live state with no recovery path.
+ * Operator passes --force to override.
+ *
+ * Two signals count as "non-empty":
+ *   1. The celilo DB exists AND has rows in the modules table (i.e.
+ *      the operator has imported at least one module).
+ *   2. Any <getModuleStoragePath()>/<id>/generated/terraform/ directory
+ *      exists (i.e. at least one module has been deployed).
+ *
+ * Either signal is sufficient. Both are checked so a half-deployed
+ * target (DB cleared but disk artifacts left over) still gets caught.
+ *
+ * Phase 4 of v2/SYSTEM_BACKUP_TERRAFORM_STATE.md (Design Decision 9).
+ */
+
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { getModuleStoragePath } from '../config/paths';
+import { getDb } from '../db/client';
+import { modules } from '../db/schema';
+
+export interface PreflightReport {
+  /** True if the target looks empty enough to restore onto. */
+  empty: boolean;
+  /** Module IDs found in the DB (if any). Empty list if the DB doesn't exist. */
+  modulesInDb: string[];
+  /** Module IDs with a generated/terraform/ directory on disk. */
+  modulesWithTerraformState: string[];
+}
+
+/**
+ * Survey the target. Pure -- no mutations. Callers decide whether to
+ * proceed (raw `empty` check) or to surface the findings to the
+ * operator and require --force confirmation.
+ */
+export function surveyRestoreTarget(): PreflightReport {
+  let modulesInDb: string[] = [];
+  try {
+    const db = getDb();
+    modulesInDb = db
+      .select({ id: modules.id })
+      .from(modules)
+      .all()
+      .map((row) => row.id);
+  } catch {
+    // No DB / no migrations / file doesn't exist -- equivalent to "no
+    // modules in DB" for pre-flight purposes.
+  }
+
+  const storageRoot = getModuleStoragePath();
+  const modulesWithTerraformState: string[] = [];
+  if (existsSync(storageRoot)) {
+    for (const entry of readdirSync(storageRoot, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const tfDir = join(storageRoot, entry.name, 'generated', 'terraform');
+      if (existsSync(tfDir)) {
+        try {
+          // Treat empty terraform/ dirs as "no state" -- a leftover
+          // dir without files isn't load-bearing.
+          const tfStat = statSync(tfDir);
+          if (tfStat.isDirectory() && readdirSync(tfDir).length > 0) {
+            modulesWithTerraformState.push(entry.name);
+          }
+        } catch {
+          /* tfDir vanished mid-survey; skip */
+        }
+      }
+    }
+  }
+
+  return {
+    empty: modulesInDb.length === 0 && modulesWithTerraformState.length === 0,
+    modulesInDb,
+    modulesWithTerraformState,
+  };
+}
+
+/**
+ * Thrown by assertRestoreTargetEmpty() when the survey finds state.
+ * Carries the full report so the CLI handler can format an actionable
+ * message without re-surveying.
+ */
+export class NonEmptyRestoreTargetError extends Error {
+  constructor(public readonly report: PreflightReport) {
+    const lines: string[] = ['Refusing to restore: target is not empty.'];
+    if (report.modulesInDb.length > 0) {
+      lines.push(
+        `  ${report.modulesInDb.length} module(s) registered in DB: ${report.modulesInDb.join(', ')}`,
+      );
+    }
+    if (report.modulesWithTerraformState.length > 0) {
+      lines.push(
+        `  ${report.modulesWithTerraformState.length} module(s) with deployed terraform state: ${report.modulesWithTerraformState.join(', ')}`,
+      );
+    }
+    lines.push('');
+    lines.push(
+      'Restoring would clobber the existing state. Pass --force to proceed (irreversible).',
+    );
+    super(lines.join('\n'));
+    this.name = 'NonEmptyRestoreTargetError';
+  }
+}
+
+/**
+ * Throw NonEmptyRestoreTargetError when the target has state. Caller
+ * (the celilo restore CLI handler) catches and exits with the error
+ * message + non-zero status when --force isn't set.
+ */
+export function assertRestoreTargetEmpty(): void {
+  const report = surveyRestoreTarget();
+  if (!report.empty) {
+    throw new NonEmptyRestoreTargetError(report);
+  }
+}

package/src/services/storage-providers/s3.ts

@@ -3,7 +3,7 @@
  * Works with AWS S3, MinIO, Backblaze B2, Wasabi, and any S3-compatible service.
  */
 
-import { createReadStream, createWriteStream } from 'node:fs';
+import { createWriteStream, readFileSync } from 'node:fs';
 import { mkdir } from 'node:fs/promises';
 import { dirname } from 'node:path';
 import { Readable } from 'node:stream';
@@ -49,7 +49,15 @@ export function createS3StorageProvider(config: S3StorageConfig): StorageProvide
 
   return {
     async upload(localPath: string, remotePath: string): Promise<void> {
-      const body = createReadStream(localPath);
+      // Upload a Buffer, NOT a read stream (ISS-0016). A streamed Body fails
+      // with "The request body terminated unexpectedly": the SDK can't replay a
+      // one-shot Node stream across the retries/redirects S3 issues (e.g. a
+      // region 301), and with no ContentLength it falls back to aws-chunked
+      // encoding on top. A Buffer is replayable and self-describing — the same
+      // reason the string-bodied verify write succeeds where the stream upload
+      // did not. Backup envelopes are small (state + key, not provider
+      // binaries — ISS-0015), so buffering is fine.
+      const body = readFileSync(localPath);
       await client.send(
         new PutObjectCommand({
           Bucket: bucket,

package/src/services/system-identity.ts

@@ -0,0 +1,30 @@
+/**
+ * Resolve a deployed module's "system identity" — the hostname and IP of the
+ * machine / container-service instance it runs on. Used to populate
+ * system.created / system.destroyed event payloads (D5) and to enumerate hosts
+ * for a dns_internal provider's deploy-time DNS backfill.
+ */
+
+import type { DbClient } from '../db/client';
+import { getModuleSystems } from './deployed-systems';
+
+export interface SystemIdentity {
+  hostname: string;
+  /** IPv4 address, CIDR stripped. */
+  ip: string;
+}
+
+/**
+ * Get a module's hostname and IP from its recorded deployed systems
+ * (v2/MODULE_SYSTEMS_ADDRESSING.md). Returns null for a module with no host
+ * (config-only providers like namecheap). Single-system modules have one; this
+ * returns the first (Phase C iterates all systems for per-system events).
+ */
+export async function getModuleHostAndIp(
+  moduleId: string,
+  db: DbClient,
+): Promise<SystemIdentity | null> {
+  const systems = getModuleSystems(moduleId, db);
+  if (!systems[0]) return null;
+  return { hostname: systems[0].hostname, ip: systems[0].ipv4_address };
+}