@stage-labs/metro 0.1.0-beta.31 → 0.1.0-beta.310

package/runtime/node_modules/@metro-labs/daemon/src/mcp-server/link.ts

@@ -0,0 +1,197 @@
+import { errMsg, log } from '@metro-labs/core/log';
+import { MCP_APPROVAL_WAIT_MS, MCP_PATHS, mcpApprovalsOf, type McpApproval, type McpDecision } from '@metro-labs/http/mcp-server-protocol';
+import { agentsDir } from '../agents/files.js';
+import { readAgentKey, type AgentKey } from '../connectors/agent-key.js';
+import { agentCall, MetroApiRefusal, type AgentFetch, type MetroApi } from '../connectors/metro-api.js';
+import { mcpServerUrl } from './config.js';
+import { ensureMcpToken } from './token.js';
+
+export type AnswerOutcome = 'acknowledged' | 'gone' | 'stopped';
+
+export type HoldApproval = (approval: McpApproval, answer: (decision: McpDecision) => Promise<AnswerOutcome>) => void;
+
+export interface McpTiming {
+  retryMs: number;
+  retryMaxMs: number;
+  idleMs: number;
+  minPollMs: number;
+  pollTimeoutMs: number;
+}
+
+export interface McpLinkDeps {
+  url: string;
+  owner: () => string | null;
+  key: () => AgentKey | null;
+  dir: () => string;
+  hold: HoldApproval;
+  registered?: () => void;
+  fetch?: AgentFetch;
+  timing?: Partial<McpTiming>;
+}
+
+const TIMING: McpTiming = { retryMs: 2_000, retryMaxMs: 60_000, idleMs: 30_000, minPollMs: 1_000, pollTimeoutMs: MCP_APPROVAL_WAIT_MS + 15_000 };
+const APPROVALS_MAX = 256 * 1024;
+
+const refusedWith = (err: unknown, status: number): boolean => err instanceof MetroApiRefusal && err.upstreamStatus === status;
+
+export class McpServerLink {
+  private readonly api: MetroApi;
+  private readonly timing: McpTiming;
+  private readonly abort = new AbortController();
+  private registered: string | null = null;
+  private failures = 0;
+  private running: Promise<void> | null = null;
+
+  constructor(private readonly deps: McpLinkDeps) {
+    this.api = { base: deps.url, fetch: deps.fetch ?? ((url, init) => fetch(url, init)), now: () => Date.now() };
+    this.timing = { ...TIMING, ...deps.timing };
+  }
+
+  private get stopped(): boolean {
+    return this.abort.signal.aborted;
+  }
+
+  start(): void {
+    this.running ??= this.run().catch((err: unknown) => {
+      log.error({ err: errMsg(err) }, 'mcp-server: the token and approval loop stopped');
+    });
+  }
+
+  async stop(): Promise<void> {
+    this.abort.abort();
+    await this.running;
+  }
+
+  reregister(): void {
+    this.registered = null;
+  }
+
+  async answer(id: string, decision: McpDecision): Promise<AnswerOutcome> {
+    for (let attempt = 0; !this.stopped; attempt += 1) {
+      if (attempt > 0) await this.pause(this.delay(attempt));
+      const key = this.enrolledKey();
+      if (key === null || this.stopped) continue;
+      try {
+        await agentCall(this.api, key, MCP_PATHS.answer, { id, decision }, { signal: this.abort.signal });
+        log.info({ id, decision }, 'mcp-server: the owner answer reached the server');
+        return 'acknowledged';
+      } catch (err) {
+        if (refusedWith(err, 404)) return 'gone';
+        if (refusedWith(err, 401)) this.registered = null;
+        if (!this.stopped) log.warn({ id, attempt: attempt + 1, err: errMsg(err) }, 'mcp-server: the owner answer did not reach the server; trying again');
+      }
+    }
+    return 'stopped';
+  }
+
+  private enrolledKey(): AgentKey | null {
+    try {
+      const key = this.deps.key();
+      const owner = this.deps.owner();
+      return key !== null && owner !== null && key.enrollment?.organization === owner ? key : null;
+    } catch (err) {
+      log.warn({ err: errMsg(err) }, 'mcp-server: the agent key could not be read');
+      return null;
+    }
+  }
+
+  private async run(): Promise<void> {
+    while (!this.stopped) {
+      const key = this.enrolledKey();
+      if (key === null) {
+        this.registered = null;
+        await this.pause(this.timing.idleMs);
+      } else if (await this.step(key)) this.failures = 0;
+      else await this.pause(this.delay(++this.failures));
+    }
+  }
+
+  private async step(key: AgentKey): Promise<boolean> {
+    let doing = 'register the MCP token';
+    try {
+      await this.register(key);
+      doing = 'ask for approvals';
+      await this.poll(key);
+      return true;
+    } catch (err) {
+      if (this.stopped) return true;
+      if (refusedWith(err, 401)) this.registered = null;
+      log.warn({ server: this.deps.url, failures: this.failures + 1, err: errMsg(err) }, `mcp-server: could not ${doing}; trying again`);
+      return false;
+    }
+  }
+
+  private async register(key: AgentKey): Promise<void> {
+    const token = ensureMcpToken(key.keyId, this.deps.dir());
+    if (token.fresh) log.info({ keyId: key.keyId }, 'mcp-server: made a new MCP token for this agent');
+    const binding = `${key.keyId} ${token.hash}`;
+    if (this.registered === binding) return;
+    await agentCall(this.api, key, MCP_PATHS.token, { tokenHash: token.hash }, { signal: this.abort.signal });
+    this.registered = binding;
+    log.info({ server: this.deps.url, keyId: key.keyId }, 'mcp-server: the MCP token is registered');
+    this.deps.registered?.();
+  }
+
+  private async poll(key: AgentKey): Promise<void> {
+    const started = Date.now();
+    const answer = await agentCall(this.api, key, MCP_PATHS.approvals, {}, { signal: this.abort.signal, timeoutMs: this.timing.pollTimeoutMs, answerMax: APPROVALS_MAX });
+    const approvals = mcpApprovalsOf(answer);
+    for (const approval of approvals) this.receive(approval);
+    const rest = this.timing.minPollMs - (Date.now() - started);
+    if (approvals.length === 0 && rest > 0) await this.pause(rest);
+  }
+
+  private receive(approval: McpApproval): void {
+    try {
+      this.deps.hold(approval, (decision) => this.answer(approval.id, decision));
+    } catch (err) {
+      log.warn({ id: approval.id, err: errMsg(err) }, 'mcp-server: an approval could not be held');
+    }
+  }
+
+  private delay(attempt: number): number {
+    return Math.min(this.timing.retryMs * 2 ** Math.min(attempt - 1, 20), this.timing.retryMaxMs);
+  }
+
+  private pause(ms: number): Promise<void> {
+    if (this.stopped) return Promise.resolve();
+    const signal = this.abort.signal;
+    return new Promise((resolve) => {
+      const done = (): void => {
+        clearTimeout(timer);
+        signal.removeEventListener('abort', done);
+        resolve();
+      };
+      const timer = setTimeout(done, ms);
+      timer.unref();
+      signal.addEventListener('abort', done, { once: true });
+    });
+  }
+}
+
+let active: McpServerLink | null = null;
+
+export interface McpServerWatch {
+  owner: () => string | null;
+  hold: HoldApproval;
+  registered?: () => void;
+}
+
+export function watchMcpServer(watch: McpServerWatch, env: NodeJS.ProcessEnv = process.env): boolean {
+  const url = mcpServerUrl(env);
+  if (url === null || active !== null) return false;
+  active = new McpServerLink({ url, owner: watch.owner, key: () => readAgentKey(), dir: agentsDir, hold: watch.hold, ...(watch.registered === undefined ? {} : { registered: watch.registered }) });
+  active.start();
+  log.info({ server: url }, 'mcp-server: connector approvals relay from this server once the agent is enrolled');
+  return true;
+}
+
+export function reregisterMcpToken(): void {
+  active?.reregister();
+}
+
+export async function stopMcpServer(): Promise<void> {
+  const link = active;
+  active = null;
+  await link?.stop();
+}

package/runtime/node_modules/@metro-labs/daemon/src/mcp-server/rpc.ts

@@ -0,0 +1,67 @@
+import { isRecord } from '@metro-labs/core/is-record';
+import { errMsg } from '@metro-labs/core/log';
+import { agentsDir } from '../agents/files.js';
+import { mcpServerUrl } from './config.js';
+import { reregisterMcpToken } from './link.js';
+import { readMcpToken } from './token.js';
+
+export interface ServerDeps {
+  url?: string | null;
+  token?: string | null;
+  fetch?: (url: string, init: RequestInit) => Promise<Response>;
+  reregister?: () => void;
+}
+
+export type ServerAnswer =
+  | { ok: true; result: unknown }
+  | { ok: false; reason: 'unset' }
+  | { ok: false; reason: 'unavailable'; detail: string }
+  | { ok: false; reason: 'refused'; message: string };
+
+let nextId = 1;
+
+const unavailable = (detail: string): ServerAnswer => ({ ok: false, reason: 'unavailable', detail });
+
+async function bodyOf(res: Response): Promise<ServerAnswer> {
+  let body: unknown;
+  try {
+    body = JSON.parse(await res.text());
+  } catch (err) {
+    return unavailable(`unreadable answer: ${errMsg(err)}`);
+  }
+  if (isRecord(body) && isRecord(body.error))
+    return { ok: false, reason: 'refused', message: typeof body.error.message === 'string' ? body.error.message.slice(0, 500) : 'refused' };
+  return isRecord(body) && Object.hasOwn(body, 'result') ? { ok: true, result: body.result } : unavailable('no JSON-RPC result');
+}
+
+interface Target {
+  url: string;
+  token: string;
+}
+
+function targetOf(deps: ServerDeps): Target | null {
+  const url = deps.url === undefined ? mcpServerUrl() : deps.url;
+  const token = deps.token === undefined ? readMcpToken(agentsDir()) : deps.token;
+  return url === null || token === null ? null : { url, token };
+}
+
+export async function askServer(method: string, params: Record<string, unknown>, timeoutMs: number, deps: ServerDeps = {}): Promise<ServerAnswer> {
+  const target = targetOf(deps);
+  if (target === null) return { ok: false, reason: 'unset' };
+  const { url, token } = target;
+  let res: Response;
+  try {
+    res = await (deps.fetch ?? fetch)(`${url}/`, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json', accept: 'application/json, text/event-stream' },
+      body: JSON.stringify({ jsonrpc: '2.0', id: nextId++, method, params }),
+      redirect: 'manual',
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (err) {
+    return unavailable(errMsg(err));
+  }
+  if (res.status === 401) (deps.reregister ?? reregisterMcpToken)();
+  if (!res.ok) return unavailable(`HTTP ${String(res.status)}`);
+  return bodyOf(res);
+}

package/runtime/node_modules/@metro-labs/daemon/src/mcp-server/token.ts

@@ -0,0 +1,50 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isRecord } from '@metro-labs/core/is-record';
+import { writeSecure } from '@metro-labs/core/secure-fs';
+import { MCP_TOKEN_RE } from '@metro-labs/http/mcp-server-protocol';
+
+export const MCP_TOKEN_FILE = 'mcp-token';
+const BINDING_FILE = 'mcp-token.json';
+
+export interface McpToken {
+  token: string;
+  hash: string;
+  fresh: boolean;
+}
+
+export const mcpTokenHash = (token: string): string => createHash('sha256').update(token).digest('base64url');
+
+const readText = (path: string): string | null => {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch {
+    return null;
+  }
+};
+
+export function readMcpToken(dir: string): string | null {
+  const text = readText(join(dir, MCP_TOKEN_FILE))?.trim() ?? '';
+  return MCP_TOKEN_RE.test(text) ? text : null;
+}
+
+function boundKeyId(dir: string): string | null {
+  const text = readText(join(dir, BINDING_FILE));
+  if (text === null) return null;
+  try {
+    const parsed: unknown = JSON.parse(text);
+    return isRecord(parsed) && parsed.version === 1 && typeof parsed.keyId === 'string' ? parsed.keyId : null;
+  } catch {
+    return null;
+  }
+}
+
+export function ensureMcpToken(keyId: string, dir: string): McpToken {
+  const kept = readMcpToken(dir);
+  if (kept !== null && boundKeyId(dir) === keyId) return { token: kept, hash: mcpTokenHash(kept), fresh: false };
+  const token = `mcp_${randomBytes(32).toString('base64url')}`;
+  writeSecure(join(dir, MCP_TOKEN_FILE), `${token}\n`);
+  writeSecure(join(dir, BINDING_FILE), `${JSON.stringify({ version: 1, keyId })}\n`);
+  return { token, hash: mcpTokenHash(token), fresh: true };
+}

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

@@ -0,0 +1,183 @@
+const ROOT_DIR = '/usr/local/lib/metro';
+export const HELPER_PATH = `${ROOT_DIR}/root-helper`;
+const HELPER_VERSION = 3;
+export const SUDOERS_PATH = '/etc/sudoers.d/metro';
+export const IMDS_UNIT = 'metro-imds.service';
+export const IMDS_UNIT_PATH = `/etc/systemd/system/${IMDS_UNIT}`;
+export const UPGRADE_UNIT = 'metro-root-upgrade@.service';
+export const UPGRADE_UNIT_PATH = `/etc/systemd/system/${UPGRADE_UNIT}`;
+const RELEASE_DIR = `${ROOT_DIR}/release`;
+export const METRO_USER = 'metro';
+const METRO_HOME = '/var/lib/metro';
+const VAULT_DROP_IN = '11-metro-vault.conf';
+const PRIVILEGED_EXEC = ['ExecConditionEx', 'ExecStartPreEx', 'ExecStartEx', 'ExecStartPostEx', 'ExecReloadEx', 'ExecStopEx', 'ExecStopPostEx'];
+
+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() {',
+  '  case "$1" in [!A-Za-z0-9]*|*[!A-Za-z0-9@_.-]*|"") die "bad service name";; esac',
+  '  case "$1" in *.service) ;; *) die "bad service name";; esac',
+  '  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"',
+  '}',
+  'agent_only() {',
+  '  [ "$(systemctl show "$1" -p User --value)" = "$AGENT" ] || die "that job does not run as $AGENT"',
+  '  [ "$(systemctl show "$1" -p PermissionsStartOnly --value)" != yes ] || die "that job runs commands as root"',
+  '  [ -n "$(systemctl show "$1" -p ExecStartEx --value)" ] || die "cannot read the commands of that job"',
+  `  if systemctl show "$1" ${PRIVILEGED_EXEC.map((p) => `-p ${p}`).join(' ')} --value | grep -Eq "flags=[^;]*(privileged|no-setuid|ambient)"; then die "that job runs commands as root"; fi`,
+  '}',
+  'dropin_ok() {',
+  `  [ "$1" = ${VAULT_DROP_IN} ] || die "bad drop-in name"`,
+  '  home=$(getent passwd "$AGENT" | cut -d: -f6)',
+  '  printf \'[Service]\\nEnvironmentFile=-%s/.metro/vault.env\\n\' "$home" | cmp -s - "$2" || die "only the vault environment file may be added"',
+  '}',
+);
+
+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 IMDS = lines(
+  'imds_block() {',
+  `  metro_uid=$(id -u ${METRO_USER} 2>/dev/null) || die "no ${METRO_USER} user"`,
+  '  for t in iptables ip6tables; do',
+  '    if [ "$t" = iptables ]; then dst=169.254.169.254; else dst=fd00:ec2::254; fi',
+  '    if ! $t -w -L OUTPUT -n >/dev/null 2>&1; then [ "$t" = ip6tables ] && continue; die "$t is not usable"; fi',
+  '    $t -w -N METRO_IMDS 2>/dev/null || true',
+  '    $t -w -F METRO_IMDS',
+  '    $t -w -A METRO_IMDS -m owner --uid-owner 0 -j RETURN',
+  '    $t -w -A METRO_IMDS -m owner --uid-owner "$metro_uid" -j RETURN',
+  '    $t -w -A METRO_IMDS -p tcp -j REJECT --reject-with tcp-reset',
+  '    $t -w -A METRO_IMDS -j REJECT',
+  '    $t -w -C OUTPUT -d "$dst" -j METRO_IMDS 2>/dev/null || $t -w -I OUTPUT -d "$dst" -j METRO_IMDS',
+  '  done',
+  '}',
+);
+
+export const imdsUnitText = (): string =>
+  lines(
+    '[Unit]',
+    `Description=Metro: only root and ${METRO_USER} reach the instance metadata service`,
+    'DefaultDependencies=no',
+    'After=local-fs.target',
+    'Before=network-pre.target shutdown.target',
+    'Wants=network-pre.target',
+    'Conflicts=shutdown.target',
+    '',
+    '[Service]',
+    'Type=oneshot',
+    'RemainAfterExit=yes',
+    `ExecStart=${HELPER_PATH} imds-block`,
+    '',
+    '[Install]',
+    'WantedBy=multi-user.target',
+    '',
+  );
+
+export const upgradeUnitText = (node: string): string =>
+  lines(
+    '[Unit]',
+    'Description=Metro: bring the root side to Metro %i, checked against npm and its GitHub provenance',
+    'After=network-online.target',
+    'Wants=network-online.target',
+    '',
+    '[Service]',
+    'Type=oneshot',
+    `ExecStart=/usr/bin/flock ${ROOT_DIR} ${node} ${RELEASE_DIR}/dist/cli.js service root-upgrade %i`,
+    'TimeoutStartSec=900',
+    '',
+  );
+
+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"; agent_only "$1"; tmp=$(mktemp); trap \'rm -f "$tmp"\' EXIT; head -c 4096 > "$tmp"; dropin_ok "$2" "$tmp"',
+  '    mkdir -p "$UNITS/$1.d"; install -m 644 "$tmp" "$UNITS/$1.d/$2" ;;',
+  '  dropin-remove)',
+  `    service_ok "$1"; [ "$2" = ${VAULT_DROP_IN} ] || die "bad drop-in name"`,
+  '    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" ;;',
+  '  imds-block) imds_block ;;',
+  '  upgrade)',
+  '    [ "$#" -eq 1 ] || die "usage: upgrade <version>"',
+  '    case "$1" in *[!0-9A-Za-z.-]*|"") die "bad version";; esac',
+  '    printf %s "$1" | grep -Eqx "[0-9]{1,9}\\.[0-9]{1,9}\\.[0-9]{1,9}(-[0-9A-Za-z]{1,20}(\\.[0-9A-Za-z]{1,20}){0,4})?" || die "bad version"',
+  `    systemctl start --no-block "${UPGRADE_UNIT.replace('@.', '@$1.')}" ;;`,
+  '  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, IMDS, ACTIONS, ''].join('\n');

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

@@ -0,0 +1,16 @@
+import { log } from '@metro-labs/core/log';
+import { METRO_VERSION } from '@metro-labs/core/version';
+import { rootHelper, rootStepHint, type HelperResult } from './privilege.js';
+
+export function blockImds(run: (args: string[]) => HelperResult = rootHelper): boolean {
+  const result = run(['imds-block']);
+  if (result.status === 0) {
+    log.info('imds: only root and metro reach the instance metadata service');
+    return true;
+  }
+  log.warn(
+    { err: result.stderr.trim(), fix: rootStepHint(METRO_VERSION) },
+    'imds: the agent can still read the instance metadata (setup data, instance role), since the root helper on this box predates the guard',
+  );
+  return false;
+}

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

@@ -0,0 +1,78 @@
+import { spawnSync } from 'node:child_process';
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import {
+  HELPER_PATH,
+  helperScript,
+  IMDS_UNIT,
+  IMDS_UNIT_PATH,
+  imdsUnitText,
+  SUDOERS_PATH,
+  sudoersText,
+  UPGRADE_UNIT_PATH,
+  upgradeUnitText,
+} from './helper-script.js';
+import { AGENT_NAME } from '../agent-user/user.js';
+
+interface InstallPaths {
+  helper: string;
+  sudoers: string;
+}
+
+type Run = (file: string, args: string[]) => void;
+
+function checked(file: string, args: string[]): void {
+  const run = spawnSync(file, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  if (run.error !== undefined) throw run.error;
+  if (run.status !== 0) throw new Error(`${file} ${args.join(' ')}: ${`${run.stdout}${run.stderr}`.trim() || `exit ${String(run.status)}`}`);
+}
+
+export function installRootHelper(paths: InstallPaths = { helper: HELPER_PATH, sudoers: SUDOERS_PATH }): void {
+  mkdirSync(dirname(paths.helper), { recursive: true, mode: 0o755 });
+  writeFileSync(paths.helper, helperScript(), { mode: 0o755 });
+  chmodSync(paths.helper, 0o755);
+  const work = mkdtempSync(join(tmpdir(), 'metro-sudoers-'));
+  try {
+    const draft = join(work, 'metro');
+    writeFileSync(draft, sudoersText(AGENT_NAME), { mode: 0o440 });
+    checked('visudo', ['-cf', draft]);
+    checked('install', ['-m', '440', draft, paths.sudoers]);
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
+}
+
+export function installImdsGuard(unit: string = IMDS_UNIT_PATH, run: Run = checked): void {
+  writeFileSync(unit, imdsUnitText(), { mode: 0o644 });
+  chmodSync(unit, 0o644);
+  run('systemctl', ['daemon-reload']);
+  run('systemctl', ['enable', IMDS_UNIT]);
+  run('systemctl', ['restart', IMDS_UNIT]);
+}
+
+const PLAIN_PATH = /^\/[A-Za-z0-9_./+-]+$/;
+
+export function installUpgradeUnit(node: string, unit: string = UPGRADE_UNIT_PATH, run: Run = checked): void {
+  if (!PLAIN_PATH.test(node)) throw new Error(`the root upgrade needs node by a plain absolute path, not '${node}'`);
+  writeFileSync(unit, upgradeUnitText(node), { mode: 0o644 });
+  chmodSync(unit, 0o644);
+  run('systemctl', ['daemon-reload']);
+}
+
+export function nodeArg(argv: string[]): string {
+  const at = argv.indexOf('--node');
+  const node = at < 0 ? undefined : argv[at + 1];
+  if (node === undefined) throw new Error('usage: install.ts --node <absolute path of the node that runs the root upgrade>');
+  return node;
+}
+
+if (import.meta.main) {
+  const node = nodeArg(process.argv.slice(2));
+  installRootHelper();
+  installImdsGuard();
+  installUpgradeUnit(node);
+  process.stdout.write(
+    `metro: wrote ${HELPER_PATH}, ${SUDOERS_PATH}, ${IMDS_UNIT_PATH} and ${UPGRADE_UNIT_PATH}; only root and metro reach the instance metadata service, and the root side follows every update\n`,
+  );
+}

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

@@ -0,0 +1,50 @@
+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]];
+
+export const rootStepHint = (version: string): string => `as root, once: npx -y @stage-labs/metro@${version} service install --user metro`;

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

@@ -0,0 +1,16 @@
+import { log } from '@metro-labs/core/log';
+import { METRO_VERSION } from '@metro-labs/core/version';
+import { rootHelper, rootStepHint, type HelperResult } from './privilege.js';
+
+export function followRelease(run: (args: string[]) => HelperResult = rootHelper, version: string = METRO_VERSION): boolean {
+  const result = run(['upgrade', version]);
+  if (result.status === 0) {
+    log.info({ version, journal: `journalctl -u metro-root-upgrade@${version}` }, 'root: asked the root side to follow this version');
+    return true;
+  }
+  log.warn(
+    { err: result.stderr.trim(), fix: rootStepHint(version) },
+    'root: the root side cannot follow updates by itself yet, since the root helper on this box predates it',
+  );
+  return false;
+}