viber-channel 0.8.6 → 0.8.8

package/lib/runner_exec.ts

@@ -0,0 +1,436 @@
+/**
+ * runner_exec.ts — local execution of a claimed spawn command (#460 Phase 2,
+ * step-09/#474). Replaces the step-07 reconcile() stub.
+ *
+ * Flow (per claimed command): validate the SERVER-VALIDATED role snapshot
+ * against the machine's local DEFAULT-DENY policy (permissions = template ∩
+ * local, never widened — C3) → report `starting` → shell
+ * `vibe-master team spawn` via an argv ARRAY (execFile, never a shell string —
+ * no injection) → report `succeeded`/`failed` (fencing-guarded). A 409 report
+ * (re-claim/cancel) → cooperative abort (don't overwrite a newer outcome — C4).
+ *
+ * Dependency-injected: `runTeamSpawn` (the launcher) and `apiFetch` are
+ * injectable so the flow is unit-testable without shelling or a live server.
+ */
+
+import { execFile } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { cfAccessHeaders } from "./cfAccess.js";
+
+/** A validated role from the server snapshot (allowlisted shape). */
+export interface SnapshotRole {
+  role: string;
+  runtime: string;
+  permission: string;
+  rolePrompt?: string;
+  model?: string;
+  count?: number;
+}
+
+export interface ClaimedCommand {
+  id: string;
+  fencing_token: number;
+  template_name: string;
+  template_spec: { roles: SnapshotRole[] };
+  prefix: string;
+  team_name: string | null;
+  env: string | null;
+}
+
+export interface RunnerAuthLite {
+  base_url: string;
+  runner_id: string;
+  runner_token: string;
+}
+
+/**
+ * Local default-deny policy (`.viber/runner-policy.json`, optional). The machine
+ * can only RESTRICT what a template asks for, never widen it. Conservative
+ * defaults when the file is absent.
+ */
+export interface RunnerPolicy {
+  allowedRuntimes: string[];
+  /** Ceiling permission the machine will grant. */
+  maxPermission: "read-only" | "read-write";
+  maxRoles: number;
+  allowedEnvs: string[];
+}
+
+const DEFAULT_POLICY: RunnerPolicy = {
+  allowedRuntimes: ["claude-code", "codex", "gemma", "claude"],
+  maxPermission: "read-write",
+  maxRoles: 8,
+  allowedEnvs: ["staging", "dev"],
+};
+
+const PERMISSION_RANK: Record<string, number> = { "read-only": 1, "read-write": 2 };
+
+// prefix/team_name become CLI argv. execFile already blocks SHELL injection, but
+// an unconstrained value like "--env" would be an ARGV-FLAG injection into
+// vibe-master. The server validates this too; the runner re-checks (defense in
+// depth) and REFUSES rather than pass a suspicious argv.
+const ARGV_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9-]{0,31}$/;
+
+/** Thrown when a policy file is PRESENT but malformed — the caller must REFUSE
+ *  execution, never fall back to the permissive baseline (Codex review P1-4). */
+export class RunnerPolicyInvalidError extends Error {}
+
+function isStringArray(v: unknown): v is string[] {
+  return Array.isArray(v) && v.every((x) => typeof x === "string");
+}
+
+/**
+ * Load the local policy. ABSENT file → the baseline (an operator who wrote no
+ * policy accepts the default). PRESENT but malformed (bad JSON / bad shape) →
+ * THROW: it is NOT fail-closed to silently grant read-write when the operator
+ * clearly intended to constrain but fat-fingered the file (Codex review P1-4).
+ */
+export function loadRunnerPolicy(cwd: string = process.cwd()): RunnerPolicy {
+  const path = join(cwd, ".viber", "runner-policy.json");
+  if (!existsSync(path)) return DEFAULT_POLICY;
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    throw new RunnerPolicyInvalidError("runner-policy.json is not valid JSON");
+  }
+  if (typeof raw !== "object" || raw === null) {
+    throw new RunnerPolicyInvalidError("runner-policy.json must be an object");
+  }
+  const p = raw as Record<string, unknown>;
+  if (!isStringArray(p.allowedRuntimes)) throw new RunnerPolicyInvalidError("allowedRuntimes must be string[]");
+  if (p.maxPermission !== "read-only" && p.maxPermission !== "read-write") {
+    throw new RunnerPolicyInvalidError("maxPermission must be read-only|read-write");
+  }
+  if (typeof p.maxRoles !== "number" || !Number.isInteger(p.maxRoles) || p.maxRoles < 1) {
+    throw new RunnerPolicyInvalidError("maxRoles must be a positive integer");
+  }
+  if (!isStringArray(p.allowedEnvs)) throw new RunnerPolicyInvalidError("allowedEnvs must be string[]");
+  return {
+    allowedRuntimes: p.allowedRuntimes,
+    maxPermission: p.maxPermission,
+    maxRoles: p.maxRoles,
+    allowedEnvs: p.allowedEnvs,
+  };
+}
+
+/** Validate the server snapshot against the local policy. Returns null if OK, or
+ *  a human reason if the command must be REFUSED (default-deny). */
+export function validateAgainstPolicy(cmd: ClaimedCommand, policy: RunnerPolicy): string | null {
+  const roles = cmd.template_spec?.roles;
+  if (!Array.isArray(roles) || roles.length === 0) return "template has no roles";
+  // Cap on the TOTAL agent count, not just distinct roles (Codex): a role may
+  // carry a `count`, so sum(count ?? 1) is the real agent count. A bad count
+  // (non-positive-int) is itself a refusal.
+  let totalAgents = 0;
+  for (const r of roles) {
+    const n = r.count ?? 1;
+    if (typeof n !== "number" || !Number.isInteger(n) || n < 1) return `invalid role count for '${r.role}'`;
+    totalAgents += n;
+  }
+  if (totalAgents > policy.maxRoles) return `too many agents (${totalAgents} > ${policy.maxRoles})`;
+  if (cmd.env && !policy.allowedEnvs.includes(cmd.env)) return `env '${cmd.env}' not allowed locally`;
+  // Argv-injection guard (defense in depth): prefix/team_name must be plain names,
+  // never something that could be read as a flag by vibe-master.
+  if (!ARGV_NAME_RE.test(cmd.prefix)) return `invalid prefix '${cmd.prefix}'`;
+  if (cmd.team_name !== null && !ARGV_NAME_RE.test(cmd.team_name)) return `invalid team_name '${cmd.team_name}'`;
+  const cap = PERMISSION_RANK[policy.maxPermission] ?? 1;
+  for (const r of roles) {
+    if (!policy.allowedRuntimes.includes(r.runtime)) return `runtime '${r.runtime}' not allowed locally`;
+    const want = PERMISSION_RANK[r.permission];
+    if (want === undefined) return `unknown permission '${r.permission}'`;
+    if (want > cap) return `permission '${r.permission}' exceeds local ceiling '${policy.maxPermission}'`;
+  }
+  return null;
+}
+
+export type TeamSpawnRunner = (
+  args: string[],
+) => Promise<{ ok: boolean; recap: string }>;
+
+/**
+ * Build a CURATED child environment (Codex review, blocking): `execFile` would
+ * otherwise inherit ALL of process.env, exposing every local secret (GitHub,
+ * cloud, unrelated tokens) to the child. Pass only OS essentials + the Viber/CF
+ * vars vibe-master actually needs to spawn agents. Nothing else is inherited.
+ */
+// EXACT-NAME allowlist (Codex review — NOT a prefix sweep). Only OS essentials
+// plus the specific Viber/CF vars vibe-master needs to spawn agents. A generic
+// `VIBER_*`/`CF_ACCESS_*` sweep could pass an unrelated or overly-sensitive
+// secret through to child agents; naming each var keeps exactly what's exposed
+// visible and reviewable. (Extend this list — never a prefix — if step-11 live
+// QA shows vibe-master needs another var.)
+const CHILD_ENV_ALLOW = [
+  // OS essentials
+  "PATH", "Path", "HOME", "USERPROFILE", "SYSTEMROOT", "windir", "TEMP", "TMP", "TMPDIR", "LANG", "APPDATA", "LOCALAPPDATA", "ComSpec",
+  // Viber/CF vars vibe-master requires to reach the backend + CF-Access tunnel
+  "VIBER_BASE_URL", "VIBER_AUTH_FILE", "VIBER_CF_CLIENT_ID", "VIBER_CF_CLIENT_SECRET",
+  "CF_ACCESS_CLIENT_ID", "CF_ACCESS_CLIENT_SECRET",
+];
+
+export function buildChildEnv(source: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {};
+  for (const k of CHILD_ENV_ALLOW) {
+    const v = source[k];
+    if (v !== undefined) env[k] = v;
+  }
+  return env;
+}
+
+/** Redact long secret-like runs (hex/base64/token) from captured output before
+ *  it is reported to the server (Codex — the CLI/children may print secrets). */
+export function redactSecrets(text: string): string {
+  return text
+    .replace(/\b[0-9a-f]{32,}\b/gi, "[redacted-hex]")
+    .replace(/\b[A-Za-z0-9_-]{40,}\b/g, "[redacted-token]");
+}
+
+/** The base command that launches vibe-master. Defaults to the installed
+ *  `vibe-master` on PATH (production). `VIBE_MASTER_CMD` overrides it as a
+ *  space-separated token list so a DEV runner can point at the source
+ *  (`VIBE_MASTER_CMD="bun /path/vibe-master.ts"`) instead of a stale global
+ *  binary — the #460 dev-QA foot-gun ("dev must run from source"). Passed to
+ *  execFile as (bin, [...baseArgs, ...args]) — still an argv array, no shell. */
+export function vibeMasterBaseCmd(source: NodeJS.ProcessEnv = process.env): string[] {
+  const raw = source.VIBE_MASTER_CMD?.trim();
+  const parts = raw ? raw.split(/\s+/) : ["vibe-master"];
+  return parts.length > 0 ? parts : ["vibe-master"];
+}
+
+/** Default launcher: shell vibe-master via execFile with an ARGV ARRAY (never a
+ *  shell string), a CURATED env, bounded time + output, and process-tree kill on
+ *  timeout. The binary is resolved via VIBE_MASTER_CMD (default `vibe-master`). */
+export const execFileTeamSpawn: TeamSpawnRunner = (args) => {
+  const base = vibeMasterBaseCmd();
+  const bin = base[0] as string;
+  return new Promise((resolve) => {
+    execFile(
+      bin,
+      [...base.slice(1), ...args],
+      { timeout: 5 * 60 * 1000, killSignal: "SIGKILL", maxBuffer: 1024 * 1024, env: buildChildEnv() },
+      (err, stdout, stderr) => {
+        const recap = redactSecrets(`${stdout}\n${stderr}`.trim()).slice(0, 4000);
+        resolve({ ok: !err, recap });
+      },
+    );
+  });
+};
+
+/**
+ * Local idempotence by command_id (Codex review, blocking): fencing protects
+ * REPORTS, not the local SIDE EFFECT. If the runner crashes mid-spawn and a new
+ * daemon re-claims the same command, it must NOT relaunch (double team). A
+ * durable marker written BEFORE launch records "this command_id was started
+ * here"; a re-claim seeing the marker refuses to relaunch. (Full reconciliation
+ * — finding+adopting the already-spawned team — is a documented follow-up.)
+ */
+export interface InflightStore {
+  has(commandId: string): boolean;
+  mark(commandId: string): void;
+  clear(commandId: string): void;
+}
+
+function fsInflightStore(cwd: string = process.cwd()): InflightStore {
+  const dir = join(cwd, ".viber", "runner-inflight");
+  const path = (id: string) => join(dir, `${id}.json`);
+  return {
+    has: (id) => existsSync(path(id)),
+    mark: (id) => {
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(path(id), JSON.stringify({ started: true }), { mode: 0o600 });
+    },
+    clear: (id) => rmSync(path(id), { force: true }),
+  };
+}
+
+/** Materialize the server-validated snapshot to a temp file the CLI reads via
+ *  `--spec-file`, returning its path + a cleanup. Exclusive create (`wx`, 0600),
+ *  unpredictable name — so vibe-master runs EXACTLY the authorized roles, never a
+ *  name-resolved local template (P1-1). */
+export interface SpecFileWriter {
+  (spec: { name: string; roles: SnapshotRole[] }): { path: string; cleanup: () => void };
+}
+
+function fsWriteSpec(cwd: string = process.cwd()): SpecFileWriter {
+  return (spec) => {
+    const dir = join(cwd, ".viber", "runner-specs");
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, `${randomBytes(16).toString("hex")}.json`);
+    // `wx` = exclusive create (fail if it somehow exists) + owner-only perms.
+    writeFileSync(path, JSON.stringify(spec), { flag: "wx", mode: 0o600 });
+    return { path, cleanup: () => rmSync(path, { force: true }) };
+  };
+}
+
+export interface ExecDeps {
+  runTeamSpawn?: TeamSpawnRunner;
+  policy?: RunnerPolicy;
+  apiFetch?: typeof fetch;
+  inflight?: InflightStore;
+  /** Injectable spec-file writer (tests). */
+  writeSpec?: SpecFileWriter;
+  /** Injectable local-log writer (tests). Returns the log path. */
+  writeLog?: (commandId: string, recap: string) => string;
+}
+
+/** Write the full launch recap to a 0600 LOCAL log (never sent to the server —
+ *  it may hold secrets). Returns the path recorded in the generic remote report.
+ *  Best-effort: a write failure returns a placeholder, never blocks the report. */
+export function writeRunnerLog(commandId: string, recap: string, cwd: string = process.cwd()): string {
+  const dir = join(cwd, ".viber", "runner-logs");
+  const path = join(dir, `${commandId}.log`);
+  try {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path, recap, { mode: 0o600 });
+  } catch {
+    return "(local log unavailable)";
+  }
+  return path;
+}
+
+async function report(
+  auth: RunnerAuthLite,
+  cmdId: string,
+  body: Record<string, unknown>,
+  fetchImpl: typeof fetch,
+): Promise<number> {
+  const resp = await fetchImpl(`${auth.base_url}/api/runners/${auth.runner_id}/commands/${cmdId}/report`, {
+    method: "POST",
+    redirect: "error",
+    headers: {
+      Authorization: `Bearer ${auth.runner_token}`,
+      "Content-Type": "application/json",
+      ...cfAccessHeaders(),
+    },
+    body: JSON.stringify(body),
+  });
+  return resp.status;
+}
+
+/**
+ * Execute one already-claimed command. Validates against local policy, reports
+ * starting → runs the team spawn → reports the outcome (fencing-guarded). A 409
+ * on the `starting` report means the claim is no longer ours (re-claim/cancel)
+ * → cooperative abort BEFORE spawning (never launch on a lost claim). Returns
+ * the terminal status the runner recorded (or "aborted").
+ */
+export async function executeClaim(
+  auth: RunnerAuthLite,
+  cmd: ClaimedCommand,
+  deps: ExecDeps = {},
+): Promise<"succeeded" | "failed" | "aborted"> {
+  const runTeamSpawn = deps.runTeamSpawn ?? execFileTeamSpawn;
+  const fetchImpl = deps.apiFetch ?? fetch;
+  const inflight = deps.inflight ?? fsInflightStore();
+
+  // P1-4: a PRESENT-but-invalid local policy REFUSES execution (never the
+  // permissive baseline). An absent policy resolves to the baseline in loader.
+  let policy: RunnerPolicy;
+  try {
+    policy = deps.policy ?? loadRunnerPolicy();
+  } catch (err) {
+    const reason = err instanceof RunnerPolicyInvalidError ? err.message : "invalid local policy";
+    await report(auth, cmd.id, { fencing_token: cmd.fencing_token, status: "failed", error: `local policy invalid: ${reason}` }, fetchImpl);
+    return "failed";
+  }
+
+  const refusal = validateAgainstPolicy(cmd, policy);
+  if (refusal) {
+    await report(auth, cmd.id, { fencing_token: cmd.fencing_token, status: "failed", error: `local policy: ${refusal}` }, fetchImpl);
+    return "failed";
+  }
+
+  // Local idempotence (C4): a marker for this command_id means a PRIOR run
+  // already started it here (crashed mid-spawn, now re-claimed). Do NOT relaunch.
+  // Keep the marker unless the failed report is ACCEPTED (2xx) — else a later
+  // re-claim must still see it (P1-2).
+  if (inflight.has(cmd.id)) {
+    const s = await report(
+      auth,
+      cmd.id,
+      { fencing_token: cmd.fencing_token, status: "failed", error: "prior partial run detected on this runner — not relaunched" },
+      fetchImpl,
+    );
+    if (s >= 200 && s < 300) inflight.clear(cmd.id);
+    return "failed";
+  }
+
+  // template_name is the positional <name> in argv: positive allowlist (no
+  // leading '-', no control char) — argv-flag-injection defense.
+  if (!/^[A-Za-z0-9_.][A-Za-z0-9 _.-]{0,63}$/.test(cmd.template_name)) {
+    await report(auth, cmd.id, { fencing_token: cmd.fencing_token, status: "failed", error: "unsafe template_name" }, fetchImpl);
+    return "failed";
+  }
+
+  // Report starting FIRST. Launch ONLY on a 2xx accept (P1-3): 409 = claim lost
+  // (re-claim/cancel), ANY other status (401/403/500/network) = abort with NO
+  // side effect. Never spawn on a claim we don't provably hold.
+  const startingStatus = await report(auth, cmd.id, { fencing_token: cmd.fencing_token, status: "starting" }, fetchImpl);
+  if (startingStatus < 200 || startingStatus >= 300) return "aborted";
+
+  // P1-1: execute EXACTLY the server-validated snapshot. Serialize the already-
+  // validated roles to a temp spec file and invoke `team spawn --spec-file` — so
+  // vibe-master runs THOSE roles, never a name-resolved local template. Serialize
+  // the validated object verbatim (no role rebuild). Cleaned up in `finally`.
+  const spec = { name: cmd.template_name, roles: cmd.template_spec.roles };
+  const { path: specPath, cleanup } = (deps.writeSpec ?? fsWriteSpec())(spec);
+  try {
+    // Allowlisted argv (C3): fixed flags + validated values, no free string.
+    const args = ["team", "spawn", "--spec-file", specPath, "--prefix", cmd.prefix];
+    if (cmd.team_name) args.push("--team", cmd.team_name);
+    if (cmd.env) args.push("--env", cmd.env);
+
+    inflight.mark(cmd.id); // durable "started here" BEFORE launch (C4)
+    const { ok, recap } = await runTeamSpawn(args);
+
+    // Generic remote report; full recap to a 0600 LOCAL log only (no secret leak).
+    const logPath = deps.writeLog ? deps.writeLog(cmd.id, recap) : writeRunnerLog(cmd.id, recap);
+    const finalStatus = await report(
+      auth,
+      cmd.id,
+      ok
+        ? { fencing_token: cmd.fencing_token, status: "succeeded", result: { message: "team spawn completed", log: logPath } }
+        : { fencing_token: cmd.fencing_token, status: "failed", error: "team spawn failed — see local runner log" },
+      fetchImpl,
+    );
+    // Clear the inflight marker ONLY when the TERMINAL report is accepted (2xx)
+    // (P1-2): on 409 (newer holder took over) or a network/other failure, KEEP
+    // the marker so a re-claim doesn't relaunch a command that already ran here.
+    if (finalStatus >= 200 && finalStatus < 300) {
+      inflight.clear(cmd.id);
+      return ok ? "succeeded" : "failed";
+    }
+    return "aborted"; // report not accepted (409/other) — marker kept for reconcile
+  } finally {
+    cleanup(); // remove the temp spec (may hold sensitive rolePrompts)
+  }
+}
+
+/**
+ * One reconcile pass: list claimable commands, claim the first, execute it.
+ * Returns the number of commands handled (0 if none). One command per pass —
+ * the daemon's coalescing + the lease keep it serial.
+ */
+export async function reconcileOnce(auth: RunnerAuthLite, deps: ExecDeps = {}): Promise<number> {
+  const fetchImpl = deps.apiFetch ?? fetch;
+  const listResp = await fetchImpl(`${auth.base_url}/api/runners/${auth.runner_id}/commands`, {
+    method: "GET",
+    redirect: "error",
+    headers: { Authorization: `Bearer ${auth.runner_token}`, ...cfAccessHeaders() },
+  });
+  if (!listResp.ok) return 0;
+  const { commands } = (await listResp.json()) as { commands: { id: string }[] };
+  if (!commands.length) return 0;
+
+  const first = commands[0];
+  const claimResp = await fetchImpl(
+    `${auth.base_url}/api/runners/${auth.runner_id}/commands/${first.id}/claim`,
+    { method: "POST", redirect: "error", headers: { Authorization: `Bearer ${auth.runner_token}`, ...cfAccessHeaders() } },
+  );
+  if (claimResp.status !== 200) return 0; // lost the claim — another pass will retry
+  const claimed = (await claimResp.json()) as ClaimedCommand;
+  await executeClaim(auth, claimed, deps);
+  return 1;
+}