@mmerterden/multi-agent-pipeline 20.33.0 → 20.35.0

package/pipeline/scripts/office-control.mjs

@@ -23,11 +23,11 @@
  *   status           running or not, the URL without the token, the idle
  *                    limit, remote access, the paired devices the phone
  *                    registry lists, and the last panel actions from
- *                    office-actions.jsonl. Remote access is "not available in
- *                    this installation" unless a remote layer is present: a
- *                    prefs.global.office.remote block, or a separately
- *                    installed module at ~/.claude/office-remote/. This
- *                    script only reports it; it carries no remote code.
+ *                    office-actions.jsonl. Remote access is "off" until
+ *                    office-pair pairs a phone, "configured" when
+ *                    prefs.global.office.remote is set but nothing is paired,
+ *                    and "paired" once a device is; while paired, office-on
+ *                    starts office-remote-client.mjs beside the server.
  *
  * State: one 0600 file, ~/.claude/logs/multi-agent/office/office.json, with
  * the pid, port and token file of the server this script started. The server
@@ -58,6 +58,7 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
 import { codeDigest } from "../lib/code-digest.mjs";
+import { phoneDir } from "./_phone-auth.mjs";
 import { fileURLToPath } from "node:url";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -72,6 +73,7 @@ const START_SKEW_MS = 120 * 1000;
 const home = (env) => env.HOME || homedir();
 const stateDir = (env) => join(home(env), ".claude", "logs", "multi-agent", "office");
 const stateFile = (env) => join(stateDir(env), "office.json");
+const clientFile = (env) => join(stateDir(env), "remote-client.json");
 const actionsLog = (env) =>
   join(home(env), ".claude", "logs", "multi-agent", "office-actions.jsonl");
 
@@ -86,16 +88,22 @@ const readJson = (p) => {
 /** The panel page: next to this scripts directory, in a checkout and in the install. */
 export const pagePath = () => join(HERE, "..", "office", "index.html");
 
-/** Whether a remote layer is present; none ships with the pipeline. */
+/** Whether a device is paired for remote use (office-pair wrote the remote config). */
+export const remotePaired = (env = process.env) => existsSync(join(phoneDir(env), "remote.json"));
+
+/** Whether the remote layer is configured: a paired device, or a prefs block. */
 export function remoteLayer(env = process.env) {
+  if (remotePaired(env)) return true;
   const prefs = readJson(join(home(env), ".claude", "multi-agent-preferences.json"));
   const block = prefs?.global?.office?.remote;
-  if (block && typeof block === "object" && !Array.isArray(block)) return true;
-  return existsSync(join(home(env), ".claude", "office-remote"));
+  return Boolean(block && typeof block === "object" && !Array.isArray(block));
 }
 
-const remoteText = (env) =>
-  remoteLayer(env) ? "provided by a separate remote layer" : "not available in this installation";
+const remoteText = (env) => {
+  if (remotePaired(env)) return "paired: the remote client runs while the office is on";
+  if (remoteLayer(env)) return "configured, no phone paired (office-pair start)";
+  return "off: no phone paired";
+};
 
 /** The contract server: beside this script, else the install. */
 export function serverScript(env = process.env) {
@@ -127,6 +135,55 @@ function psField(pid, field) {
   return r.status === 0 ? r.stdout.trim() : "";
 }
 
+/** The remote client this script started, if it is still running. */
+function remoteClient(env) {
+  const c = readJson(clientFile(env));
+  if (!c || !Number.isInteger(c.pid) || !alive(c.pid)) return null;
+  return psField(c.pid, "command").includes("office-remote-client.mjs") ? c : null;
+}
+
+/**
+ * Start office-remote-client.mjs beside the server when a device is paired,
+ * or keep the one already running. Without a pairing nothing starts, so
+ * remote stays off by default; the client also stops by itself once the
+ * server is gone.
+ */
+export function startRemoteClient(env = process.env) {
+  if (!remotePaired(env)) return false;
+  if (remoteClient(env)) return true;
+  const script = join(HERE, "office-remote-client.mjs");
+  if (!existsSync(script)) return false;
+  const child = spawn(process.execPath, [script, "loop"], {
+    env,
+    detached: true,
+    stdio: "ignore",
+  });
+  child.unref();
+  mkdirSync(stateDir(env), { recursive: true, mode: 0o700 });
+  writeFileSync(
+    clientFile(env),
+    JSON.stringify({ pid: child.pid, startedAt: new Date().toISOString() }) + "\n",
+    { mode: 0o600 },
+  );
+  return true;
+}
+
+/** Stop the remote client this script started. */
+export function stopRemoteClient(env = process.env) {
+  const c = remoteClient(env);
+  let stopped = false;
+  if (c) {
+    try {
+      process.kill(c.pid, "SIGTERM");
+      stopped = true;
+    } catch {
+      stopped = false;
+    }
+  }
+  rmSync(clientFile(env), { force: true });
+  return stopped;
+}
+
 /**
  * Whether `pid` is still the server a state record names: its token file
  * names the same pid, the process runs contract-server.mjs, and it started
@@ -313,6 +370,7 @@ export async function officeOn({ env = process.env, open = true } = {}) {
     if (!s) throw new Error("the server stopped right after it started");
   }
   const page = `${s.url}/office`;
+  const remote = startRemoteClient(env);
   const opened = open ? openBrowser(`${page}#code=${await panelCode(s)}`, env) : false;
   return {
     running: true,
@@ -321,12 +379,14 @@ export async function officeOn({ env = process.env, open = true } = {}) {
     url: page,
     pid: s.pid,
     idleMinutes: s.idleMinutes,
+    remote,
     opened,
   };
 }
 
 /** Stop the server this script started. */
 export function officeOff({ env = process.env } = {}) {
+  stopRemoteClient(env);
   const s = readJson(stateFile(env));
   let stopped = false;
   if (isOurServer(s, s ? readJson(s.tokenFile ?? "") : null)) {

package/pipeline/scripts/office-pair.mjs

@@ -0,0 +1,407 @@
+#!/usr/bin/env node
+/**
+ * @file office-pair.mjs  -  pair a phone with this machine for the office
+ * remote layer (features/office-remote-protocol.md, Pairing).
+ *
+ *   start [--relay <url>]  register a pairing with the relay and show its QR
+ *                          code on this machine's screen
+ *   wait                   wait for the phone's pairing message, open it and
+ *                          print the comparison code
+ *   confirm <code>         enrol the device once the code the phone shows is
+ *                          typed back here, and send the phone its device id
+ *                          in the first sealed machine-to-phone frame
+ *   cancel                 drop the pending pairing
+ *
+ * What stays on this machine: the machine private key and the relay token
+ * live in <phone dir>/remote.json (0600); the relay only gets the SHA-256 of
+ * the token. The one-time secret and the machine public key travel in the QR
+ * link's fragment, which a browser never sends to a server, so the relay can
+ * neither open the phone's pairing message nor swap the machine key. The QR
+ * page is a 0600 file in a 0700 directory opened in the local browser; the
+ * secret is never printed. Enrolment goes through `phone-devices.mjs add`
+ * with scopes read,answer, so `launch` stays a separate local switch.
+ *
+ * Every subcommand refuses an unattended run (unattended-policy.json).
+ * Exit: 0 done, 1 refused or failed, 2 usage, 3 unattended.
+ *
+ * @module pipeline/scripts/office-pair
+ */
+
+import { spawnSync } from "node:child_process";
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  comparisonCode,
+  createMachineKeys,
+  directionKeys,
+  openPairing,
+  sealFrame,
+} from "../lib/office-remote.mjs";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { encodeQr, qrSvg } from "../lib/qr-code.mjs";
+import { isUnattended } from "../lib/unattended.mjs";
+import { phoneDir } from "./_phone-auth.mjs";
+import { readConfig, writeConfig } from "./office-remote-client.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const PAIRING_TTL_MS = 10 * 60_000;
+const NAME = /^[\p{L}\p{N} ._'-]{1,64}$/u;
+const B64U = /^[A-Za-z0-9_-]+$/;
+
+const home = (env) => env.HOME || homedir();
+export const pendingPath = (env = process.env) => join(phoneDir(env), "pair-pending.json");
+const pageDir = (env) => join(home(env), ".claude", "logs", "multi-agent", "office");
+const pagePath = (env) => join(pageDir(env), "pair.html");
+const b64u = (b) => Buffer.from(b).toString("base64url");
+const sha256hex = (s) => createHash("sha256").update(s).digest("hex");
+
+/** First 16 hex digits of SHA-256 over a public key, in groups of four (the phone shows the same). */
+export const keyFingerprint = (publicKey) =>
+  createHash("sha256")
+    .update(Buffer.from(publicKey, "base64url"))
+    .digest("hex")
+    .slice(0, 16)
+    .replace(/(.{4})(?=.)/g, "$1 ");
+
+class Refusal extends Error {}
+
+function readJson(p) {
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function writePrivate(file, text) {
+  mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+  chmodSync(dirname(file), 0o700);
+  writeFileSync(file, text, { mode: 0o600 });
+  chmodSync(file, 0o600);
+}
+
+/** A relay URL: https, or http on the loopback; no credentials, query or fragment. */
+export function relayOrigin(raw) {
+  let u;
+  try {
+    u = new URL(String(raw));
+  } catch {
+    throw new Refusal("the relay URL is not a URL");
+  }
+  const loopback = ["127.0.0.1", "localhost", "[::1]"].includes(u.hostname);
+  if (u.protocol !== "https:" && !(u.protocol === "http:" && loopback)) {
+    throw new Refusal("the relay URL must be https");
+  }
+  if (u.username || u.password || u.search || u.hash || (u.pathname && u.pathname !== "/")) {
+    throw new Refusal("the relay URL is an origin only (scheme, host, port)");
+  }
+  return u.origin;
+}
+
+function relayFromPrefs(env) {
+  const prefs = readJson(join(home(env), ".claude", "multi-agent-preferences.json"));
+  return prefs?.global?.office?.remote?.relayUrl ?? null;
+}
+
+/** The link the QR code carries; everything after `#` stays on the phone. */
+export function pairingLink({ relayUrl, pairingId, secret, machinePublic }) {
+  return `${relayUrl}/office/pair#p=${pairingId}&s=${secret}&k=${machinePublic}`;
+}
+
+function pageHtml(svg) {
+  return (
+    "<!doctype html><html><head><meta charset=utf-8>" +
+    `<meta http-equiv="Content-Security-Policy" content="default-src 'none'">` +
+    "<title>Office pairing</title></head><body>" +
+    "<p>Scan with the phone, signed in to your site. The code expires in 10 minutes.</p>" +
+    `${svg}</body></html>`
+  );
+}
+
+function openPage(file, env) {
+  const bin = env.MA_OFFICE_OPENER || "open";
+  const r = spawnSync(bin, [`file://${file}`], { stdio: "ignore", timeout: 15000 });
+  return r.status === 0;
+}
+
+async function relayCall(fetchImpl, url, init) {
+  const res = await fetchImpl(url, { ...init, signal: AbortSignal.timeout(30_000) });
+  const text = await res.text();
+  let body;
+  try {
+    body = text ? JSON.parse(text) : null;
+  } catch {
+    body = null;
+  }
+  return { status: res.status, ok: res.ok, body };
+}
+
+/**
+ * Register a pairing with the relay and show its QR code.
+ *
+ * @returns {Promise<{pairingId: string, expiresAt: string, page: string, opened: boolean}>}
+ */
+export async function start({ relay, env = process.env, fetchImpl = fetch, now = Date.now() }) {
+  const relayUrl = relayOrigin(relay ?? relayFromPrefs(env) ?? "");
+  const existing = readConfig(env);
+  const machine =
+    existing?.machinePrivatePem && existing?.machinePublic
+      ? { privatePem: existing.machinePrivatePem, publicKey: existing.machinePublic }
+      : createMachineKeys();
+  const relayToken =
+    existing?.relayToken && existing.relayUrl === relayUrl
+      ? existing.relayToken
+      : b64u(randomBytes(32));
+  const pairingId = b64u(randomBytes(16));
+  const secret = b64u(randomBytes(16));
+  const expiresAt = new Date(now + PAIRING_TTL_MS).toISOString();
+  const r = await relayCall(fetchImpl, `${relayUrl}/api/office/relay/pairings`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      pairingId,
+      machinePublic: machine.publicKey,
+      tokenHash: sha256hex(relayToken),
+      expiresAt,
+    }),
+  });
+  if (!r.ok) throw new Refusal(`the relay refused the pairing (${r.status})`);
+  writeConfig(
+    {
+      ...(existing ?? {}),
+      relayUrl,
+      relayToken,
+      pairingId: existing?.pairingId ?? null,
+      machinePrivatePem: machine.privatePem,
+      machinePublic: machine.publicKey,
+      devices: existing?.devices ?? {},
+    },
+    env,
+  );
+  writePrivate(
+    pendingPath(env),
+    JSON.stringify({ relayUrl, pairingId, secret, expiresAt, relayToken }) + "\n",
+  );
+  const link = pairingLink({ relayUrl, pairingId, secret, machinePublic: machine.publicKey });
+  writePrivate(pagePath(env), pageHtml(qrSvg(encodeQr(link, { ecc: "M" }))));
+  return { pairingId, expiresAt, page: pagePath(env), opened: openPage(pagePath(env), env) };
+}
+
+function pending(env, now) {
+  const p = readJson(pendingPath(env));
+  if (!p?.pairingId) throw new Refusal("no pairing is pending; run office-pair start");
+  if (Date.parse(p.expiresAt) <= now) {
+    dropPending(env);
+    throw new Refusal("the pairing expired; run office-pair start again");
+  }
+  return p;
+}
+
+function dropPending(env) {
+  rmSync(pendingPath(env), { force: true });
+  rmSync(pagePath(env), { force: true });
+}
+
+/** Check what the phone sent before anything of it is kept. */
+export function checkPairingMessage(value, relayUrl) {
+  const v = value ?? {};
+  if (typeof v.deviceName !== "string" || !NAME.test(v.deviceName))
+    throw new Refusal("the device name is not 1 to 64 letters, digits, spaces or ._'-");
+  if (typeof v.devicePublicKey !== "string" || !/^[A-Za-z0-9_-]{43}$/.test(v.devicePublicKey))
+    throw new Refusal("the device key is not a base64url Ed25519 public key");
+  const pk = v.passkey ?? {};
+  if (typeof pk.credential !== "string" || !B64U.test(pk.credential) || pk.credential.length > 400)
+    throw new Refusal("the passkey public key is missing");
+  if (typeof pk.credentialId !== "string" || !B64U.test(pk.credentialId))
+    throw new Refusal("the passkey credential id is missing");
+  if (pk.origin !== relayUrl) throw new Refusal("the passkey origin is not the relay's");
+  if (pk.rpId !== new URL(relayUrl).hostname)
+    throw new Refusal("the passkey rp id is not the relay's host");
+  return {
+    deviceName: v.deviceName,
+    devicePublicKey: v.devicePublicKey,
+    passkey: {
+      credential: pk.credential,
+      credentialId: pk.credentialId,
+      rpId: pk.rpId,
+      origin: pk.origin,
+    },
+  };
+}
+
+/**
+ * Wait for the phone's pairing message, open it and keep it with the pending
+ * pairing. Prints the comparison code, never a key.
+ */
+export async function wait({
+  env = process.env,
+  fetchImpl = fetch,
+  now = Date.now,
+  pollMs = 2000,
+}) {
+  const p = pending(env, now());
+  const config = readConfig(env);
+  while (now() < Date.parse(p.expiresAt)) {
+    const r = await relayCall(
+      fetchImpl,
+      `${p.relayUrl}/api/office/relay/pairings/${encodeURIComponent(p.pairingId)}`,
+      { headers: { Authorization: `Bearer ${p.relayToken}` } },
+    );
+    if (r.ok && r.body?.envelope) {
+      const { sessionPublic, sealed } = r.body.envelope;
+      if (typeof sessionPublic !== "string" || !B64U.test(sessionPublic))
+        throw new Refusal("the phone sent no session key");
+      const opened = openPairing({
+        privatePem: config.machinePrivatePem,
+        peerPublic: sessionPublic,
+        secret: p.secret,
+        pairingId: p.pairingId,
+        sealed,
+      });
+      if (!opened.ok) throw new Refusal("the pairing message did not open with this pairing");
+      const message = checkPairingMessage(opened.value, p.relayUrl);
+      writePrivate(pendingPath(env), JSON.stringify({ ...p, sessionPublic, message }) + "\n");
+      return {
+        deviceName: message.deviceName,
+        code: comparisonCode(config.machinePublic, sessionPublic),
+        machineKey: keyFingerprint(config.machinePublic),
+      };
+    }
+    if (!r.ok && r.status !== 404) throw new Refusal(`the relay answered ${r.status}`);
+    await new Promise((res) => setTimeout(res, pollMs));
+  }
+  dropPending(env);
+  throw new Refusal("the pairing expired before the phone answered");
+}
+
+function enrol(message, env) {
+  const r = spawnSync(
+    process.execPath,
+    [
+      join(HERE, "phone-devices.mjs"),
+      "add",
+      "--name",
+      message.deviceName,
+      "--public-key",
+      message.devicePublicKey,
+      "--scopes",
+      "read,answer",
+    ],
+    { env, encoding: "utf8", timeout: 30_000 },
+  );
+  if (r.status !== 0) {
+    throw new Refusal(`phone-devices refused the device: ${(r.stderr || "").trim()}`);
+  }
+  return JSON.parse(r.stdout);
+}
+
+/**
+ * Enrol the device once the user typed the code the phone shows.
+ *
+ * @returns {Promise<{id: string, name: string, scopes: string[]}>}
+ */
+export async function confirm({ code, env = process.env, fetchImpl = fetch, now = Date.now() }) {
+  const p = pending(env, now);
+  if (!p.message || !p.sessionPublic) throw new Refusal("run office-pair wait first");
+  const config = readConfig(env);
+  const want = Buffer.from(comparisonCode(config.machinePublic, p.sessionPublic));
+  const got = Buffer.from(String(code ?? "").trim());
+  if (got.length !== want.length || !timingSafeEqual(got, want)) {
+    dropPending(env);
+    throw new Refusal("the code does not match; the pairing was dropped, start again");
+  }
+  const device = enrol(p.message, env);
+  const keys = directionKeys({
+    privatePem: config.machinePrivatePem,
+    peerPublic: p.sessionPublic,
+    pairingId: p.pairingId,
+    role: "machine",
+  });
+  const welcome = sealFrame(keys.send, 1, "machine-to-phone", {
+    deviceId: device.id,
+    scopes: device.scopes,
+  });
+  const r = await relayCall(
+    fetchImpl,
+    `${p.relayUrl}/api/office/relay/pairings/${encodeURIComponent(p.pairingId)}/confirm`,
+    {
+      method: "POST",
+      headers: { Authorization: `Bearer ${p.relayToken}`, "content-type": "application/json" },
+      body: JSON.stringify({ welcome }),
+    },
+  );
+  if (!r.ok) {
+    spawnSync(process.execPath, [join(HERE, "phone-devices.mjs"), "revoke", device.id], {
+      env,
+      stdio: "ignore",
+      timeout: 30_000,
+    });
+    dropPending(env);
+    throw new Refusal(
+      `the relay refused the confirmation (${r.status}); the device was revoked again, start over`,
+    );
+  }
+  writeConfig(
+    {
+      ...config,
+      pairingId: p.pairingId,
+      devices: {
+        [device.id]: {
+          id: device.id,
+          sessionPublic: p.sessionPublic,
+          passkey: { ...p.message.passkey, signCount: 0 },
+          recvCounter: 0,
+          sendCounter: 1,
+        },
+      },
+    },
+    env,
+  );
+  dropPending(env);
+  return { id: device.id, name: device.name, scopes: device.scopes };
+}
+
+/** Drop the pending pairing and its QR page. */
+export function cancel({ env = process.env } = {}) {
+  const had = existsSync(pendingPath(env));
+  dropPending(env);
+  return { cancelled: had };
+}
+
+async function main(argv) {
+  const [cmd, ...rest] = argv;
+  if (!["start", "wait", "confirm", "cancel"].includes(cmd)) {
+    process.stderr.write(
+      "usage: office-pair.mjs start [--relay <url>] | wait | confirm <code> | cancel\n",
+    );
+    return 2;
+  }
+  if (isUnattended()) {
+    process.stderr.write("office-pair: an unattended run may not pair a device\n");
+    return 3;
+  }
+  try {
+    let out;
+    if (cmd === "start") {
+      const i = rest.indexOf("--relay");
+      out = await start({ relay: i === -1 ? undefined : rest[i + 1] });
+    } else if (cmd === "wait") out = await wait({});
+    else if (cmd === "confirm") out = await confirm({ code: rest[0] });
+    else out = cancel();
+    process.stdout.write(JSON.stringify(out) + "\n");
+    return 0;
+  } catch (err) {
+    process.stderr.write(`office-pair: ${err.message}\n`);
+    return 1;
+  }
+}
+
+if (invokedDirectly(import.meta.url)) {
+  main(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+  });
+}