@pleri/olam-cli 0.1.7

package/host-cp/src/container-secret-fetcher.mjs

@@ -0,0 +1,163 @@
+// Phase F-2-B (B3): fetch a per-world container's X-Olam-Secret via the
+// docker-socket-proxy sidecar (container mode) OR via `docker exec` (bare-
+// node mode — host-cp running as a plain Node process on the host).
+//
+// The secret lives at `/tmp/olam-container-secret` inside the world's
+// devbox container. Phase E init wrote it (`chmod 400` owned by root —
+// world-app user has no write permission, T9 mitigation) and the
+// per-world CP's `requireAuth` middleware compares against it. Host CP
+// reads the secret server-side and injects `X-Olam-Secret` on proxied
+// requests, so the browser never sees the secret directly.
+//
+// Container mode (`dockerHost = 'tcp://docker-socket-proxy:2375'`):
+//   1. POST /containers/<name>/exec
+//      body: { Cmd: ['cat', '/tmp/olam-container-secret'], AttachStdout: true, AttachStderr: true }
+//      → { Id: '<exec-id>' }
+//   2. POST /exec/<exec-id>/start
+//      body: { Detach: false, Tty: false }
+//      → response stream containing the file bytes (raw multiplexed
+//        stdout/stderr per Docker exec protocol)
+//
+//   The exec endpoint is whitelisted in the socket-proxy (EXEC=1).
+//
+// Bare-node mode (`dockerHost = 'docker-cli'`):
+//   Spawn `docker exec <containerName> cat /tmp/olam-container-secret` via
+//   child_process. No socket-proxy on the host; the docker CLI on the
+//   operator's $PATH is the canonical access path. Same `olam-<id>-devbox`
+//   naming convention applies. ~10 ms of process-spawn overhead per miss
+//   is fine because the secret is cached for OLAM_SECRET_CACHE_TTL_SEC
+//   (default 300 s).
+
+import { spawnSync } from 'node:child_process';
+
+/**
+ * Read /tmp/olam-container-secret from a world's devbox container.
+ * Throws on any non-2xx response from the socket-proxy or on the
+ * file being empty (the world's CP is misconfigured if it is).
+ *
+ * @param {object} args
+ * @param {string} args.worldId
+ * @param {string} args.dockerHost  Either `tcp://...` for socket-proxy
+ *   mode or the sentinel `'docker-cli'` for bare-node mode.
+ * @param {(host: string, init: RequestInit) => Promise<Response>} [args.fetchImpl]
+ *   injectable for tests; defaults to global fetch (Node 22+)
+ * @returns {Promise<string>}  the secret (trimmed of trailing whitespace)
+ */
+export async function fetchContainerSecret({ worldId, dockerHost, fetchImpl = globalThis.fetch }) {
+  // Container naming convention: docker provider creates containers as
+  // `olam-${worldId}-devbox` (see packages/adapters/src/docker/container.ts).
+  // Phase F-2-D dogfood revealed the original `${worldId}-devbox` was
+  // missing the `olam-` prefix.
+  const containerName = `olam-${worldId}-devbox`;
+
+  // Bare-node mode: shell out to docker exec directly. Operator's docker
+  // CLI on $PATH is the canonical access path; no socket-proxy needed.
+  if (dockerHost === 'docker-cli') {
+    const result = spawnSync(
+      'docker',
+      ['exec', containerName, 'cat', '/tmp/olam-container-secret'],
+      { encoding: 'utf-8' },
+    );
+    if (result.error) {
+      throw new Error(`docker exec ${containerName} cat ... failed: ${result.error.message}`);
+    }
+    if (result.status !== 0) {
+      throw new Error(
+        `docker exec ${containerName} cat ... exit ${result.status}: ${(result.stderr || '').trim()}`,
+      );
+    }
+    const secret = (result.stdout || '').trim();
+    if (!secret) {
+      throw new Error(`/tmp/olam-container-secret empty in container ${containerName}`);
+    }
+    return secret;
+  }
+
+  // Container mode: HTTP via the docker-socket-proxy sidecar.
+  // Docker API: tcp://host:port → http://host:port
+  const apiBase = dockerHost.replace(/^tcp:\/\//, 'http://');
+
+  // Step 1: create exec instance
+  const createUrl = `${apiBase}/containers/${encodeURIComponent(containerName)}/exec`;
+  const createRes = await fetchImpl(createUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      Cmd: ['cat', '/tmp/olam-container-secret'],
+      AttachStdout: true,
+      AttachStderr: true,
+      Tty: false,
+    }),
+  });
+  if (!createRes.ok) {
+    throw new Error(
+      `socket-proxy POST /containers/${containerName}/exec failed: ${createRes.status} ${createRes.statusText}`,
+    );
+  }
+  const createBody = await createRes.json();
+  const execId = createBody.Id;
+  if (!execId) {
+    throw new Error(`socket-proxy /exec did not return Id: ${JSON.stringify(createBody)}`);
+  }
+
+  // Step 2: start exec, read stdout. The response is Docker's
+  // multiplexed exec stream: 8-byte header per frame + payload bytes.
+  // Header byte 0 = stream id (1=stdout, 2=stderr), bytes 4-7 = payload
+  // length (big-endian uint32). For `cat <smallfile>` we expect a single
+  // frame on stream 1.
+  const startUrl = `${apiBase}/exec/${execId}/start`;
+  const startRes = await fetchImpl(startUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ Detach: false, Tty: false }),
+  });
+  if (!startRes.ok) {
+    throw new Error(
+      `socket-proxy POST /exec/${execId}/start failed: ${startRes.status} ${startRes.statusText}`,
+    );
+  }
+  const buf = new Uint8Array(await startRes.arrayBuffer());
+
+  // Decode the multiplexed stream. Skip stderr frames; concatenate
+  // stdout payloads. Empty file → throw (per-world CP is broken).
+  const stdoutBytes = decodeDockerExecStream(buf);
+  const secret = new TextDecoder('utf-8').decode(stdoutBytes).trim();
+  if (!secret) {
+    throw new Error(`/tmp/olam-container-secret empty in container ${containerName}`);
+  }
+  return secret;
+}
+
+/**
+ * Decode Docker's multiplexed exec stream — keep only stdout (stream id 1).
+ * Stream format: each frame is 8-byte header + payload. Header byte 0
+ * is the stream id (0=stdin, 1=stdout, 2=stderr); bytes 4-7 are the
+ * payload length as big-endian uint32. Bytes 1-3 are reserved (zero).
+ *
+ * @param {Uint8Array} buf
+ * @returns {Uint8Array}
+ */
+export function decodeDockerExecStream(buf) {
+  const out = [];
+  let i = 0;
+  while (i + 8 <= buf.byteLength) {
+    const streamId = buf[i];
+    // Big-endian uint32 at offset i+4..i+8
+    const len = (buf[i + 4] << 24) | (buf[i + 5] << 16) | (buf[i + 6] << 8) | buf[i + 7];
+    const payload = buf.subarray(i + 8, i + 8 + len);
+    if (streamId === 1) {
+      out.push(payload);
+    }
+    i += 8 + len;
+  }
+  // Concatenate.
+  let total = 0;
+  for (const p of out) total += p.byteLength;
+  const merged = new Uint8Array(total);
+  let off = 0;
+  for (const p of out) {
+    merged.set(p, off);
+    off += p.byteLength;
+  }
+  return merged;
+}

package/host-cp/src/docker-events.mjs

@@ -0,0 +1,184 @@
+// Phase F-2-B (B3): subscribe to docker events stream and invalidate
+// the secret cache on `restart` / `stop` events for known worlds.
+//
+// M2 ship gate: `docker restart <world>; within 10s, proxy call returns
+// 200 not 401`. The 10s budget is dominated by docker-events latency
+// (events fire ~1s after the docker daemon emits them) + JSON parse +
+// cache invalidate (<100ms). 10s is conservative.
+//
+// Stream format: Docker sends NDJSON — newline-delimited JSON events.
+// Each event has shape:
+//   {"Type":"container","Action":"restart","Actor":{"Attributes":{"name":"<container-name>"}},...}
+// We filter `Type === 'container'` && `Action ∈ {restart, stop, die}` and
+// extract the container name to compute worldId.
+
+import http from 'node:http';
+import { spawn } from 'node:child_process';
+
+/**
+ * Subscribe to docker events. Returns a stop function. Auto-reconnects
+ * on transient errors (the events stream is long-lived; a daemon
+ * restart breaks the connection but the function recovers).
+ *
+ * @param {object} args
+ * @param {string} args.dockerHost      Either `tcp://...` for socket-proxy
+ *   mode or the sentinel `'docker-cli'` for bare-node mode (spawns
+ *   `docker events --format json` via child_process).
+ * @param {(worldId: string) => void} args.onWorldRestart
+ *   called when a known world restarts/stops/dies
+ * @param {(message: string) => void} [args.log]
+ * @returns {() => void}                stop function
+ */
+export function subscribeDockerEvents({ dockerHost, onWorldRestart, log = console.log }) {
+  let stopped = false;
+  let activeReq = null;
+  let activeProc = null;
+  let reconnectTimer = null;
+
+  // Bare-node mode: shell out to `docker events --format json` and parse
+  // its stdout as NDJSON. Same semantic as the HTTP path; different
+  // transport. Eliminates the `tcp://docker-cli` URL-construction crash.
+  function connectViaCli() {
+    if (stopped) return;
+    const filters = ['--filter', 'type=container'];
+    log('docker-events: spawning `docker events --format json`');
+    const child = spawn(
+      'docker',
+      ['events', '--format', '{{json .}}', ...filters],
+      { stdio: ['ignore', 'pipe', 'pipe'] },
+    );
+    activeProc = child;
+    let buf = '';
+    child.stdout.setEncoding('utf-8');
+    child.stdout.on('data', (chunk) => {
+      buf += chunk;
+      let nl;
+      while ((nl = buf.indexOf('\n')) !== -1) {
+        const line = buf.slice(0, nl);
+        buf = buf.slice(nl + 1);
+        if (!line.trim()) continue;
+        try {
+          const event = JSON.parse(line);
+          // CLI shape uses `status` instead of HTTP API's `Action`; normalize.
+          if (event.status && !event.Action) event.Action = event.status;
+          if (event.Type === undefined && event.Type !== 'container') event.Type = 'container';
+          handleEvent(event, { onWorldRestart, log });
+        } catch (err) {
+          log(`docker-events: parse error on line: ${line.slice(0, 120)} (${err.message})`);
+        }
+      }
+    });
+    child.stderr.on('data', (chunk) => {
+      const text = String(chunk).trim();
+      if (text) log(`docker-events: stderr: ${text}`);
+    });
+    child.on('exit', (code, signal) => {
+      activeProc = null;
+      log(`docker-events: child exited code=${code} signal=${signal}; reconnecting`);
+      scheduleReconnect();
+    });
+    child.on('error', (err) => {
+      log(`docker-events: spawn error: ${err.message}; reconnecting`);
+      scheduleReconnect();
+    });
+  }
+
+  function connect() {
+    if (stopped) return;
+    if (dockerHost === 'docker-cli') {
+      return connectViaCli();
+    }
+    // Docker Engine API: GET /events?filters=...
+    // Filter: type=container AND event=restart|stop|die
+    // (Note: `event` filter takes a JSON-stringified array.)
+    const filters = JSON.stringify({
+      type: ['container'],
+      event: ['restart', 'stop', 'die'],
+    });
+    const url = new URL('/events', dockerHost.replace(/^tcp:\/\//, 'http://'));
+    url.searchParams.set('filters', filters);
+
+    log(`docker-events: connecting to ${url.origin}/events`);
+    activeReq = http.get(url, (res) => {
+      if (res.statusCode !== 200) {
+        log(`docker-events: unexpected status ${res.statusCode}; will retry`);
+        scheduleReconnect();
+        return;
+      }
+      let buf = '';
+      res.setEncoding('utf-8');
+      res.on('data', (chunk) => {
+        buf += chunk;
+        // NDJSON: split on newlines; last fragment may be partial.
+        let nl;
+        while ((nl = buf.indexOf('\n')) !== -1) {
+          const line = buf.slice(0, nl);
+          buf = buf.slice(nl + 1);
+          if (!line.trim()) continue;
+          try {
+            handleEvent(JSON.parse(line), { onWorldRestart, log });
+          } catch (err) {
+            log(`docker-events: parse error on line: ${line.slice(0, 120)} (${err.message})`);
+          }
+        }
+      });
+      res.on('end', () => {
+        log('docker-events: stream closed; reconnecting');
+        scheduleReconnect();
+      });
+      res.on('error', (err) => {
+        log(`docker-events: stream error: ${err.message}; reconnecting`);
+        scheduleReconnect();
+      });
+    });
+    activeReq.on('error', (err) => {
+      log(`docker-events: connect error: ${err.message}; reconnecting`);
+      scheduleReconnect();
+    });
+  }
+
+  function scheduleReconnect() {
+    if (stopped) return;
+    if (reconnectTimer) return;
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = null;
+      connect();
+    }, 2000); // 2s backoff
+  }
+
+  connect();
+
+  return function stop() {
+    stopped = true;
+    if (reconnectTimer) clearTimeout(reconnectTimer);
+    if (activeReq) activeReq.destroy();
+    if (activeProc) {
+      try { activeProc.kill('SIGTERM'); } catch { /* ignore */ }
+      activeProc = null;
+    }
+  };
+}
+
+/**
+ * Inspect a docker event and call onWorldRestart if it matches a
+ * world container. Container naming convention: `<worldId>-devbox`
+ * (per packages/adapters/src/docker/container.ts).
+ *
+ * Exported for unit testing.
+ *
+ * @param {{ Type?: string, Action?: string, Actor?: { Attributes?: { name?: string } } }} event
+ * @param {{ onWorldRestart: (worldId: string) => void, log: (m: string) => void }} ctx
+ */
+export function handleEvent(event, { onWorldRestart, log }) {
+  if (event?.Type !== 'container') return;
+  if (!['restart', 'stop', 'die'].includes(event.Action ?? '')) return;
+  const name = event.Actor?.Attributes?.name;
+  if (!name) return;
+  // Strip leading slash that Docker sometimes prepends to container names.
+  const cleanName = name.startsWith('/') ? name.slice(1) : name;
+  const m = /^(.+)-devbox$/.exec(cleanName);
+  if (!m) return;
+  const worldId = m[1];
+  log(`docker-events: ${event.Action} on ${cleanName} → invalidating ${worldId}`);
+  onWorldRestart(worldId);
+}

package/host-cp/src/local-worlds-source.mjs

@@ -0,0 +1,83 @@
+/**
+ * Phase E2 (olam-dogfood-vision): LocalWorldsSource implementation.
+ *
+ * Wraps host-cp's existing dockerode-driven world enumeration in a
+ * WorldsSource-shaped object so E4's composition layer can fan out
+ * across multiple sources (local + future Pylon cloud) and merge.
+ *
+ * The class deliberately takes its dependencies via factory function
+ * injection rather than reaching into server.mjs's module-level state
+ * directly. Two reasons:
+ *   1. Testability — vitest can pass mocked getWorldsRegistry +
+ *      fetchWorldServices without spinning up the full host-cp
+ *      server.mjs.
+ *   2. Module-cycle avoidance — server.mjs imports this module, so
+ *      this module CANNOT import server.mjs back without a cycle.
+ *
+ * Returns the same shape as the pre-E2 GET /api/worlds response with
+ * a single addition: `source: 'local'` on every entry.
+ *
+ * @typedef {import('./worlds-source.mjs').WorldsSource} WorldsSource
+ * @typedef {import('./worlds-source.mjs').WorldSummary} WorldSummary
+ * @typedef {import('./worlds-source.mjs').ServiceInfo} ServiceInfo
+ */
+
+/**
+ * @typedef {object} LocalWorldsSourceDeps
+ * @property {() => Record<string, number>} getWorldsRegistry
+ *   Returns current WORLDS map (worldId → host_port). Called fresh
+ *   per list() so post-list registry mutations are visible immediately.
+ * @property {(worldId: string) => string | null} getWorldName
+ *   Returns the operator-set friendly name OR null if absent.
+ * @property {(worldId: string) => Promise<ServiceInfo[]>} fetchWorldServices
+ *   Probes per-world services (atlas-core, diner-app, ttyd, per-world CP).
+ *   Same function the pre-E2 handler called inline.
+ */
+
+/**
+ * @param {LocalWorldsSourceDeps} deps
+ * @returns {WorldsSource}
+ */
+export function createLocalWorldsSource(deps) {
+  return {
+    name: 'local',
+    async list() {
+      const registry = deps.getWorldsRegistry();
+      const entries = Object.entries(registry);
+      const worlds = await Promise.all(
+        entries.map(async ([id, host_port]) => {
+          const services = await deps.fetchWorldServices(id);
+          // World status mirrors pre-E2 behavior:
+          //   - running:  >=1 service responds to a probe
+          //   - starting: container has port bindings but nothing answers
+          //   - unknown:  no port bindings at all (container down/missing)
+          const liveCount = services.filter((s) => s.live).length;
+          /** @type {'running' | 'starting' | 'unknown'} */
+          const status =
+            services.length === 0
+              ? 'unknown'
+              : liveCount > 0
+                ? 'running'
+                : 'starting';
+          /** @type {WorldSummary} */
+          const summary = {
+            id,
+            name: deps.getWorldName(id),
+            status,
+            services,
+            source: 'local',
+          };
+          // Preserve the pre-E2 host_port field so SPA + CLI consumers
+          // that depend on it don't break. WorldSummary type doesn't
+          // declare host_port (it's local-source-specific metadata),
+          // but extra fields on the object are tolerated by the type.
+          return /** @type {WorldSummary & {host_port: number}} */ ({
+            ...summary,
+            host_port,
+          });
+        }),
+      );
+      return worlds;
+    },
+  };
+}