@stage-labs/metro 0.1.0-beta.2 → 0.1.0-beta.200

package/runtime/node_modules/@metro-labs/daemon/src/metro-user/helper-script.ts

@@ -0,0 +1,126 @@
+export const HELPER_PATH = '/usr/local/lib/metro/root-helper';
+export const HELPER_VERSION = 1;
+export const SUDOERS_PATH = '/etc/sudoers.d/metro';
+export const METRO_USER = 'metro';
+export const METRO_HOME = '/var/lib/metro';
+
+export const sudoersText = (agent: string): string =>
+  [
+    `${METRO_USER} ALL=(${agent}) NOPASSWD: ALL`,
+    `${METRO_USER} ALL=(root) NOPASSWD: ${HELPER_PATH} *`,
+    `Defaults:${METRO_USER} !requiretty`,
+    '',
+  ].join('\n');
+
+const lines = (...parts: string[]): string => parts.join('\n');
+
+const CHECKS = lines(
+  'AGENT=agent',
+  'UNITS=/etc/systemd/system',
+  'die() { echo "root-helper: $*" >&2; exit 2; }',
+  'agent_uid() { id -u "$AGENT" 2>/dev/null || die "no agent user"; }',
+  'service_ok() {',
+  '  printf %s "$1" | grep -Eq "^[A-Za-z0-9@_.-]+\\.service$" || die "bad service name"',
+  '  case "$1" in metro*) die "not a metro unit";; esac',
+  '  frag=$(systemctl show "$1" -p FragmentPath --value)',
+  '  case "$frag" in "$UNITS"/*) ;; *) die "not a unit under $UNITS";; esac',
+  '  systemctl show "$1" -p TriggeredBy --value | grep -q "\\.timer" || die "not started by a timer"',
+  '}',
+  'dropin_ok() {',
+  '  case "$1" in 10-metro-agent.conf|11-metro-vault.conf) ;; *) die "bad drop-in name";; esac',
+  '  home=$(getent passwd "$AGENT" | cut -d: -f6)',
+  '  saw_user=0',
+  '  while IFS= read -r line; do',
+  '    case "$line" in',
+  '      "[Service]"|"") ;;',
+  '      "User=$AGENT") saw_user=1 ;;',
+  '      Group=*) printf %s "${line#Group=}" | grep -Eq "^[0-9]+$" || die "bad group" ;;',
+  '      "WorkingDirectory=$home"|"WorkingDirectory=$home"/*) ;;',
+  '      Environment=*) ;;',
+  '      "EnvironmentFile=-$home/.metro/vault.env") ;;',
+  '      "ExecStart=") ;;',
+  '      ExecStart=[+!@]*) die "privileged ExecStart refused" ;;',
+  '      ExecStart=*) ;;',
+  '      *) die "line not allowed: $line" ;;',
+  '    esac',
+  '  done < "$2"',
+  '  if [ "$1" = 10-metro-agent.conf ] && [ "$saw_user" != 1 ]; then die "the drop-in must set User=$AGENT"; fi',
+  '}',
+);
+
+const FIREWALL = lines(
+  'firewall_on() {',
+  '  uid=$(agent_uid)',
+  '  for t in iptables ip6tables; do',
+  '    $t -w -N METRO_AGENT 2>/dev/null || true',
+  '    $t -w -F METRO_AGENT',
+  '    $t -w -A METRO_AGENT -o lo -j ACCEPT',
+  '    $t -w -A METRO_AGENT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT',
+  '    $t -w -A METRO_AGENT -p udp --dport 53 -j ACCEPT',
+  '    $t -w -A METRO_AGENT -p tcp --dport 53 -j ACCEPT',
+  '    $t -w -A METRO_AGENT -p tcp -j REJECT --reject-with tcp-reset',
+  '    $t -w -A METRO_AGENT -j REJECT',
+  '    $t -w -C OUTPUT -m owner --uid-owner "$uid" -j METRO_AGENT 2>/dev/null || $t -w -I OUTPUT -m owner --uid-owner "$uid" -j METRO_AGENT',
+  '  done',
+  '}',
+  'firewall_off() {',
+  '  uid=$(agent_uid)',
+  '  for t in iptables ip6tables; do',
+  '    while $t -w -C OUTPUT -m owner --uid-owner "$uid" -j METRO_AGENT 2>/dev/null; do $t -w -D OUTPUT -m owner --uid-owner "$uid" -j METRO_AGENT; done',
+  '    $t -w -F METRO_AGENT 2>/dev/null || true',
+  '    $t -w -X METRO_AGENT 2>/dev/null || true',
+  '  done',
+  '}',
+);
+
+const ACTIONS = lines(
+  'action="${1:-}"; [ "$#" -gt 0 ] && shift',
+  'case "$action" in',
+  `  version) echo ${String(HELPER_VERSION)} ;;`,
+  '  ensure-agent)',
+  '    getent passwd "$AGENT" >/dev/null || useradd --create-home --shell /bin/bash "$AGENT"',
+  '    chmod 700 "$(getent passwd "$AGENT" | cut -d: -f6)" ;;',
+  '  as-agent-scope)',
+  '    [ "$#" -ge 3 ] || die "usage: as-agent-scope <max> <high> <command...>"',
+  '    printf %s "$1$2" | grep -Eq "^[0-9]+$" || die "bad memory limits"',
+  '    max="$1"; high="$2"; shift 2',
+  '    uid=$(agent_uid); gid=$(id -g "$AGENT")',
+  '    exec systemd-run --scope --quiet --collect --unit="metro-claude-$(date +%s%N)" -p MemoryMax="$max" -p MemoryHigh="$high" -p OOMPolicy=continue -- setpriv --reuid="$uid" --regid="$gid" --init-groups -- "$@" ;;',
+  '  dropin-write)',
+  '    service_ok "$1"; tmp=$(mktemp); trap \'rm -f "$tmp"\' EXIT; cat > "$tmp"; dropin_ok "$2" "$tmp"',
+  '    mkdir -p "$UNITS/$1.d"; install -m 644 "$tmp" "$UNITS/$1.d/$2" ;;',
+  '  dropin-remove)',
+  '    service_ok "$1"; case "$2" in 10-metro-agent.conf|11-metro-vault.conf) ;; *) die "bad drop-in name";; esac',
+  '    rm -f "$UNITS/$1.d/$2" ;;',
+  '  daemon-reload) systemctl daemon-reload ;;',
+  '  start-job)',
+  '    service_ok "$1"; [ "$(systemctl show "$1" -p User --value)" = "$AGENT" ] || die "that job does not run as $AGENT"',
+  '    systemctl start --no-block "$1" ;;',
+  '  root-crontab) crontab -l -u root 2>/dev/null || true ;;',
+  '  root-crontab-drop)',
+  '    printf %s "$1" | grep -Eq "^[0-9a-f]{16}$" || die "bad line id"',
+  `    backups="${METRO_HOME}/.metro/agents"`,
+  '    cur=$(mktemp); crontab -l -u root > "$cur" 2>/dev/null || true',
+  '    kept=$(mktemp); found=0',
+  '    while IFS= read -r line; do',
+  '      id=$(printf %s "$line" | sed "s/^[[:space:]]*//;s/[[:space:]]*$//" | tr -d "\\n" | sha256sum | cut -c1-16)',
+  '      if [ "$id" = "$1" ] && [ "$found" = 0 ]; then found=1; elif [ -n "$line" ]; then printf "%s\\n" "$line" >> "$kept"; fi',
+  '    done < "$cur"',
+  '    [ "$found" = 1 ] || die "that cron line is gone"',
+  '    install -m 600 "$cur" "$backups/crontab-root.$(date +%Y-%m-%dT%H-%M-%S).bak"',
+  '    crontab -u root "$kept"; rm -f "$cur" "$kept" ;;',
+  '  firewall-on) firewall_on ;;',
+  '  firewall-off) firewall_off ;;',
+  '  trust-ca)',
+  `    src="${METRO_HOME}/.metro/agents/vault/ca/ca.crt"`,
+  '    head -n1 "$src" | grep -q "BEGIN CERTIFICATE" || die "not a certificate"',
+  '    if grep -q "PRIVATE KEY" "$src"; then die "a key is not a certificate"; fi',
+  '    install -m 644 "$src" /usr/local/share/ca-certificates/metro-vault.crt && update-ca-certificates >/dev/null ;;',
+  '  untrust-ca) rm -f /usr/local/share/ca-certificates/metro-vault.crt; update-ca-certificates --fresh >/dev/null ;;',
+  '  install-nss-tools) DEBIAN_FRONTEND=noninteractive apt-get install -y -q libnss3-tools >/dev/null ;;',
+  '  *) die "unknown action: $action" ;;',
+  'esac',
+);
+
+export const helperScript = (): string =>
+  ['#!/bin/sh', 'set -eu', 'export PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin', CHECKS, FIREWALL, ACTIONS, ''].join('\n');

package/runtime/node_modules/@metro-labs/daemon/src/metro-user/move.ts

@@ -0,0 +1,165 @@
+import { spawnSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { ApiError } from '@metro-labs/http/api-error';
+import { METRO_VERSION } from '@metro-labs/core/version';
+import { AGENT_NAME } from '../agent-user/user.js';
+import { HELPER_PATH, helperScript, METRO_HOME, METRO_USER, SUDOERS_PATH, sudoersText } from './helper-script.js';
+import { runningAsRoot } from './privilege.js';
+
+export const UNIT_FILE = '/etc/systemd/system/metro.service';
+export const MOVE_DIR = '/var/lib/metro-move';
+export const MOVE_LOG = '/var/log/metro-move.log';
+const PREFIX = `${METRO_HOME}/.npm-global`;
+const CLI = `${PREFIX}/lib/node_modules/@stage-labs/metro/dist/cli.js`;
+
+const which = (bin: string): string | null => {
+  const run = spawnSync('sh', ['-c', `command -v ${bin}`], { encoding: 'utf8' });
+  const path = run.status === 0 ? run.stdout.trim() : '';
+  if (path === '') return null;
+  try {
+    return realpathSync(path);
+  } catch {
+    return null;
+  }
+};
+
+export interface UnitFacts {
+  serveArgs: string[];
+  env: string[];
+  port: string;
+}
+
+export function unitFacts(unit: string): UnitFacts {
+  const exec = /^ExecStart=(.*)$/m.exec(unit)?.[1] ?? '';
+  const words = [...exec.matchAll(/"((?:[^"\\]|\\.)*)"|(\S+)/g)].map((m) => (m[1] ?? m[2] ?? '').replace(/\\(.)/g, '$1'));
+  const at = words.indexOf('serve');
+  if (at < 0) throw new ApiError('the metro service does not run `metro serve`; move it by hand', 409);
+  const env = [...unit.matchAll(/^Environment=(.*)$/gm)].map((m) => m[1] ?? '').filter((e) => /^"?METRO_/.test(e) && !/^"?METRO_(AGENTS_DIR|RUNTIME_STORE)=/.test(e));
+  const portArg = words[words.indexOf('--port') + 1];
+  const envPort = /METRO_WEBHOOK_PORT=(\d+)/.exec(env.join(' '))?.[1];
+  return { serveArgs: words.slice(at + 1), env, port: (words.includes('--port') ? portArg : envPort) ?? '8420' };
+}
+
+const ESCAPED_QUOTE = '\'\\\'\'';
+const shellWord = (w: string): string => `'${w.replace(/'/g, ESCAPED_QUOTE)}'`;
+const unitWord = (w: string): string => (/^[A-Za-z0-9_/.:=+@,-]+$/.test(w) ? w : `"${w.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`);
+
+export function metroUnit(node: string, facts: UnitFacts): string {
+  return [
+    '[Unit]',
+    'Description=Metro daemon (metro serve)',
+    'After=network-online.target tailscaled.service',
+    'Wants=network-online.target',
+    '',
+    '[Service]',
+    `User=${METRO_USER}`,
+    `Group=${METRO_USER}`,
+    `ExecStart=${[node, CLI, 'serve', ...facts.serveArgs].map(unitWord).join(' ')}`,
+    'Restart=always',
+    'RestartSec=2',
+    'OOMPolicy=continue',
+    'WorkingDirectory=/',
+    `Environment=HOME=${METRO_HOME}`,
+    `Environment=PATH=${PREFIX}/bin:/usr/local/bin:/usr/bin:/bin`,
+    `Environment=NPM_CONFIG_PREFIX=${PREFIX}`,
+    ...facts.env.map((e) => `Environment=${e}`),
+    '',
+    '[Install]',
+    'WantedBy=multi-user.target',
+    '',
+  ].join('\n');
+}
+
+export function moveScript(port: string, spec: string, bun: string): string {
+  return [
+    '#!/bin/sh',
+    'set -u',
+    `exec >> ${MOVE_LOG} 2>&1`,
+    'echo "--- metro move $(date -Is)"',
+    `OLD=/root/.metro; NEW=${METRO_HOME}/.metro; DIR=${MOVE_DIR}`,
+    'fail() { echo "FAILED: $*"; echo failed > "$DIR/state"; exit 1; }',
+    'healthy() {',
+    '  i=0; while [ $i -lt 60 ]; do',
+    `    if curl -fsS -m 3 http://127.0.0.1:${port}/health >/dev/null 2>&1 && [ "$(ps -o user= -p "$(systemctl show metro -p MainPID --value)")" = "$1" ]; then return 0; fi`,
+    '    i=$((i+1)); sleep 2; done; return 1; }',
+    'echo moving > "$DIR/state"',
+    `id ${METRO_USER} >/dev/null 2>&1 || useradd --system --create-home --home-dir ${METRO_HOME} --shell /usr/sbin/nologin ${METRO_USER} || fail "useradd"`,
+    `usermod -aG systemd-journal ${METRO_USER} || true`,
+    `mkdir -p ${METRO_HOME} && chown ${METRO_USER}:${METRO_USER} ${METRO_HOME} && chmod 700 ${METRO_HOME}`,
+    `B=${shellWord(bun)}; case "$B" in /root/*) install -m 755 "$B" /usr/local/bin/bun || fail "bun";; esac`,
+    `su -s /bin/sh ${METRO_USER} -c ${shellWord(`cd / && npm install --global --prefix ${PREFIX} ${spec}`)} || fail "npm install for ${METRO_USER}"`,
+    `for bin in node bun tailscale npm; do su -s /bin/sh ${METRO_USER} -c ${shellWord(`PATH=${PREFIX}/bin:/usr/local/bin:/usr/bin:/bin command -v "$1" >/dev/null`)} sh "$bin" || fail "${METRO_USER} cannot find $bin"; done`,
+    `tailscale set --operator=${METRO_USER} || fail "tailscale operator"`,
+    `cp ${UNIT_FILE} "$DIR/metro.service.root" || fail "unit backup"`,
+    'systemctl stop metro',
+    'if [ -e "$NEW" ]; then mv "$NEW" "$NEW.old-$(date +%s)"; fi',
+    'mv "$OLD" "$NEW" || { systemctl start metro; fail "move"; }',
+    'rm -f "$NEW/runtime/runtime.json"',
+    `chown -R ${METRO_USER}:${METRO_USER} ${METRO_HOME}`,
+    `install -m 644 "$DIR/metro.service.new" ${UNIT_FILE}`,
+    'systemctl daemon-reload && systemctl start metro',
+    `if healthy ${METRO_USER}; then echo done > "$DIR/state"; echo "metro runs as ${METRO_USER}"; exit 0; fi`,
+    'echo "not healthy as metro, putting everything back"',
+    'systemctl stop metro',
+    'mv "$NEW" "$OLD" && chown -R root:root "$OLD"',
+    `install -m 644 "$DIR/metro.service.root" ${UNIT_FILE}`,
+    'systemctl daemon-reload && systemctl start metro',
+    'healthy root && fail "Metro did not start as metro; it runs as root again" || fail "Metro did not start as metro, and the way back did not answer either"',
+    '',
+  ].join('\n');
+}
+
+function whichOrFail(bin: string): string {
+  const found = which(bin);
+  if (found === null) throw new ApiError(`${bin} is missing on this box`, 409);
+  return found;
+}
+
+const requireTools = (): void => {
+  for (const bin of ['sudo', 'visudo', 'tailscale', 'curl', 'npm']) whichOrFail(bin);
+};
+
+function preflight(): { node: string; bun: string; unit: string } {
+  if (!runningAsRoot()) throw new ApiError('only a Metro running as root can move itself', 409);
+  if (!existsSync(UNIT_FILE)) throw new ApiError('this box does not run Metro as the systemd service `metro`', 409);
+  if (process.env.METRO_AGENTS_DIR !== undefined && process.env.METRO_AGENTS_DIR !== '') throw new ApiError('METRO_AGENTS_DIR is set; move this box by hand', 409);
+  if (homedir() !== '/root') throw new ApiError(`Metro keeps its files in ${homedir()}, not /root; move this box by hand`, 409);
+  const node = which('node');
+  if (node === null || node.startsWith('/root/')) throw new ApiError('Node must be installed for every user (not under /root) before the move', 409);
+  requireTools();
+  return { node, bun: whichOrFail('bun'), unit: readFileSync(UNIT_FILE, 'utf8') };
+}
+
+function installHelper(): void {
+  mkdirSync('/usr/local/lib/metro', { recursive: true, mode: 0o755 });
+  writeFileSync(HELPER_PATH, helperScript(), { mode: 0o755 });
+  chmodSync(HELPER_PATH, 0o755);
+  const draft = join(MOVE_DIR, 'sudoers');
+  writeFileSync(draft, sudoersText(AGENT_NAME), { mode: 0o440 });
+  const check = spawnSync('visudo', ['-cf', draft], { encoding: 'utf8' });
+  if (check.status !== 0) throw new ApiError(`the sudo rules did not validate: ${check.stdout}${check.stderr}`, 500);
+  spawnSync('install', ['-m', '440', draft, SUDOERS_PATH]);
+}
+
+export function startMove(spec = `@stage-labs/metro@${METRO_VERSION}`): { log: string } {
+  const { node, bun, unit } = preflight();
+  const facts = unitFacts(unit);
+  mkdirSync(MOVE_DIR, { recursive: true, mode: 0o700 });
+  installHelper();
+  writeFileSync(join(MOVE_DIR, 'metro.service.new'), metroUnit(node, facts), { mode: 0o600 });
+  writeFileSync(join(MOVE_DIR, 'move.sh'), moveScript(facts.port, spec, bun), { mode: 0o700 });
+  writeFileSync(join(MOVE_DIR, 'state'), 'starting\n');
+  const run = spawnSync('systemd-run', ['--unit=metro-move', '--collect', '--quiet', 'sh', join(MOVE_DIR, 'move.sh')], { encoding: 'utf8' });
+  if (run.status !== 0) throw new ApiError(`could not start the move: ${run.stderr.trim()}`, 500);
+  return { log: MOVE_LOG };
+}
+
+export function moveState(): string | null {
+  try {
+    return readFileSync(join(MOVE_DIR, 'state'), 'utf8').trim();
+  } catch {
+    return null;
+  }
+}

package/runtime/node_modules/@metro-labs/daemon/src/metro-user/privilege.ts

@@ -0,0 +1,48 @@
+import { spawnSync } from 'node:child_process';
+import { HELPER_PATH, METRO_USER } from './helper-script.js';
+
+export interface PrivilegeHost {
+  platform: string;
+  uid: number | undefined;
+  user: string;
+}
+
+let metroUid: number | null | undefined;
+
+function uidOfMetro(): number | null {
+  if (metroUid !== undefined) return metroUid;
+  const run = spawnSync('getent', ['passwd', METRO_USER], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  const uid = Number(run.status === 0 ? run.stdout.split(':')[2] : NaN);
+  metroUid = Number.isInteger(uid) && uid > 0 ? uid : null;
+  return metroUid;
+}
+
+const realHost = (): PrivilegeHost => {
+  const uid = process.getuid?.();
+  const linux = process.platform === 'linux';
+  return { platform: process.platform, uid, user: linux && uid !== 0 && uid !== undefined && uid === uidOfMetro() ? METRO_USER : '' };
+};
+
+export const runningAsRoot = (host: PrivilegeHost = realHost()): boolean => host.platform === 'linux' && host.uid === 0;
+
+export const runningAsMetro = (host: PrivilegeHost = realHost()): boolean =>
+  host.platform === 'linux' && host.uid !== 0 && host.user === METRO_USER;
+
+export interface HelperResult {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+export function rootHelper(args: string[], input?: string): HelperResult {
+  const run = spawnSync('sudo', ['-n', HELPER_PATH, ...args], { encoding: 'utf8', input, stdio: ['pipe', 'pipe', 'pipe'], timeout: 180_000 });
+  return { status: run.error === undefined ? run.status : null, stdout: run.stdout ?? '', stderr: run.stderr ?? run.error?.message ?? '' };
+}
+
+export function mustHelper(args: string[], input?: string): string {
+  const run = rootHelper(args, input);
+  if (run.status !== 0) throw new Error(run.stderr.trim() || `root-helper ${args[0] ?? ''} failed`);
+  return run.stdout;
+}
+
+export const helperArgv = (args: string[]): [string, string[]] => ['sudo', ['-n', HELPER_PATH, ...args]];

package/runtime/node_modules/@metro-labs/daemon/src/monitor/api.ts

@@ -0,0 +1,132 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { errMsg, log } from '@metro-labs/core/log';
+import { subscribeEvents, type MetroEvent } from '@metro-labs/core/events';
+import { eventInScope } from '../agents/scope.js';
+import { hasAnyKey } from '../agents/keys.js';
+import {
+  allowedAgents,
+  authenticate,
+} from '../mcp/request-identity.js';
+
+const KEEPALIVE_MS = 25_000;
+
+const monitorEnabled = (): boolean => hasAnyKey();
+
+function cors(req: IncomingMessage): Record<string, string> {
+  return {
+    'access-control-allow-origin': req.headers.origin ?? '*',
+    'access-control-allow-methods': 'GET, OPTIONS',
+    'access-control-allow-headers': 'Authorization, Content-Type',
+    'access-control-max-age': '86400',
+    vary: 'Origin',
+  };
+}
+
+function sendJson(
+  res: ServerResponse,
+  req: IncomingMessage,
+  status: number,
+  body: unknown,
+): void {
+  res.writeHead(status, { 'content-type': 'application/json', ...cors(req) });
+  res.end(JSON.stringify(body));
+}
+
+function startTailStream(
+  req: IncomingMessage,
+  res: ServerResponse,
+  allowed: Set<string>,
+): void {
+  res.writeHead(200, {
+    'content-type': 'text/event-stream',
+    'cache-control': 'no-cache, no-transform',
+    connection: 'keep-alive',
+    'x-accel-buffering': 'no',
+    ...cors(req),
+  });
+  const timers: { keepalive?: ReturnType<typeof setInterval> } = {};
+  const subs: { stop?: () => void } = {};
+  let done = false;
+  const cleanup = (): void => {
+    if (done) return;
+    done = true;
+    subs.stop?.();
+    if (timers.keepalive) clearInterval(timers.keepalive);
+    try {
+      res.end();
+    } catch {
+      log.debug('monitor: tail cleanup end failed');
+    }
+  };
+  const write = (chunk: string): void => {
+    if (done) return;
+    if (res.destroyed || res.writableEnded) {
+      cleanup();
+      return;
+    }
+    try {
+      res.write(chunk);
+    } catch (err) {
+      log.debug({ err: errMsg(err) }, 'monitor: tail write failed');
+      cleanup();
+    }
+  };
+  write(': metro monitor tail (live)\n\n');
+  let id = 0;
+  subs.stop = subscribeEvents((e: MetroEvent): void => {
+    if (!eventInScope(allowed, e.line)) return;
+    id += 1;
+    write(`id: ${id}\nevent: live\ndata: ${JSON.stringify(e)}\n\n`);
+  });
+  timers.keepalive = setInterval(() => {
+    write(': keepalive\n\n');
+  }, KEEPALIVE_MS);
+  timers.keepalive.unref?.();
+  req.on('close', cleanup);
+  req.on('error', cleanup);
+}
+
+function routeApi(
+  req: IncomingMessage,
+  res: ServerResponse,
+  path: string,
+  allowed: Set<string>,
+): void {
+  if (path === '/api/tail') {
+    if (req.method !== 'GET') {
+      sendJson(res, req, 405, { error: 'method not allowed' });
+      return;
+    }
+    startTailStream(req, res, allowed);
+    return;
+  }
+  sendJson(res, req, 404, { error: 'not found' });
+}
+
+function preflight(req: IncomingMessage, res: ServerResponse): boolean {
+  if (!monitorEnabled()) {
+    sendJson(res, req, 404, { error: 'not found' });
+    return true;
+  }
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204, cors(req)).end();
+    return true;
+  }
+  return false;
+}
+
+export function handleMonitorRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+): boolean {
+  const path = (req.url ?? '').split('?', 2)[0] ?? '';
+  if (!path.startsWith('/api/')) return false;
+  if (preflight(req, res)) return true;
+  const identity = authenticate(req);
+  if (!identity) {
+    sendJson(res, req, 401, { error: 'unauthorized' });
+    return true;
+  }
+  routeApi(req, res, path, allowedAgents(identity));
+  return true;
+}