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

package/runtime/node_modules/@metro-labs/{mcp/src/daemon → daemon/src/stations}/supervisor-io.ts

@@ -1,12 +1,12 @@
 import { watch, type FSWatcher } from 'node:fs';
 import { join, parse as parsePath } from 'node:path';
-import { errMsg, log } from './log.js';
-import type { Pending } from './protocol.js';
+import { errMsg, log } from '@metro-labs/core/log';
+import type { Pending } from '@metro-labs/core/trains/protocol';
 
 export const RESTART_BACKOFFS_MS = [1_000, 5_000, 30_000] as const;
 export const MAX_CONSECUTIVE_FAILS = 5;
 export const HOT_RELOAD_DEBOUNCE_MS = 300;
-export const TRAIN_EXT = /\.(ts|js|mjs)$/;
+const TRAIN_EXT = /\.(ts|js|mjs)$/;
 
 export interface TrainState {
   name: string;

package/runtime/node_modules/@metro-labs/{mcp/src/daemon → daemon/src/stations}/supervisor.ts

@@ -1,8 +1,7 @@
 import { mkdirSync, statSync, type FSWatcher } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
-import { errMsg, log } from './log.js';
-import { daemonSelf } from './events.js';
+import { errMsg, log } from '@metro-labs/core/log';
+import { userSelf } from '@metro-labs/core/events';
 import {
   drainLines,
   failAllPending,
@@ -12,7 +11,7 @@ import {
   sendCall,
   type TrainCallResponse,
   type TrainEvent,
-} from './protocol.js';
+} from '@metro-labs/core/trains/protocol';
 import {
   HOT_RELOAD_DEBOUNCE_MS,
   MAX_CONSECUTIVE_FAILS,
@@ -22,9 +21,7 @@ import {
   startWatcher,
   type TrainState,
 } from './supervisor-io.js';
-
-export const TRAINS_DIR =
-  process.env.METRO_TRAINS_DIR ?? join(homedir(), '.metro', 'trains');
+import { trainsDir } from '../boot/paths.js';
 
 const DYLD_FALLBACK_ENV: Record<string, string> =
   process.platform === 'darwin'
@@ -45,7 +42,7 @@ export class TrainSupervisor {
   private watcher: FSWatcher | null = null;
   private reloadTimers = new Map<string, ReturnType<typeof setTimeout>>();
 
-  constructor(private dir: string = TRAINS_DIR) {}
+  constructor(private dir: string = trainsDir()) {}
 
   running(): string[] {
     return [...this.trains.keys()];
@@ -212,7 +209,7 @@ export class TrainSupervisor {
           ...process.env,
           ...DYLD_FALLBACK_ENV,
           METRO_TRAIN_NAME: state.name,
-          METRO_SELF_URI: daemonSelf(),
+          METRO_SELF_URI: userSelf(),
         },
       });
       state.proc = proc;

package/runtime/node_modules/@metro-labs/daemon/src/stations/threema-callbacks.ts

@@ -0,0 +1,32 @@
+import { readJson } from '@metro-labs/core/secure-fs';
+import { accountFilePath } from './materialize.js';
+
+export interface ThreemaCallback {
+  id: string;
+  callbackId: string;
+  callbackToken: string;
+}
+
+const str = (v: unknown): string | undefined =>
+  typeof v === 'string' && v !== '' ? v : undefined;
+
+function toCallback(row: unknown): ThreemaCallback | null {
+  if (typeof row !== 'object' || row === null) return null;
+  const rec = row as Record<string, unknown>;
+  const id = str(rec.id);
+  const callbackId = str(rec.callbackId);
+  const callbackToken = str(rec.callbackToken);
+  if (id === undefined || callbackId === undefined || callbackToken === undefined) return null;
+  return { id, callbackId, callbackToken };
+}
+
+export function listThreemaCallbacks(): ThreemaCallback[] {
+  const raw = readJson<unknown[]>(accountFilePath('threema'), [], {
+    warn: 'threema-accounts.json: malformed, ignoring',
+  });
+  if (!Array.isArray(raw)) return [];
+  return raw.map(toCallback).filter((c): c is ThreemaCallback => c !== null);
+}
+
+export const findThreemaCallback = (callbackId: string): ThreemaCallback | undefined =>
+  listThreemaCallbacks().find((c) => c.callbackId === callbackId);

package/runtime/node_modules/@metro-labs/{mcp/src/daemon → daemon/src/stations}/train-call.ts

@@ -1,4 +1,4 @@
-import type { TrainCallResponse } from './protocol.js';
+import type { TrainCallResponse } from '@metro-labs/core/trains/protocol';
 
 export type TrainCallBackend = (
   train: string,

package/runtime/node_modules/@metro-labs/daemon/src/stations/webhook-endpoints.ts

@@ -0,0 +1,51 @@
+import type { Endpoint } from '@metro-labs/core/endpoints';
+import { timingSafeEqual } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { readJson } from '@metro-labs/core/secure-fs';
+
+interface AccountRecord {
+  id?: unknown;
+  webhookId?: unknown;
+  label?: unknown;
+  secret?: unknown;
+  createdAt?: unknown;
+}
+
+const accountsFile = (): string =>
+  process.env.WEBHOOK_ACCOUNTS_FILE ??
+  join(homedir(), '.metro', 'webhook-accounts.json');
+
+const str = (v: unknown): string | undefined =>
+  typeof v === 'string' && v !== '' ? v : undefined;
+
+function toEndpoint(raw: AccountRecord): Endpoint | null {
+  const id = str(raw.id);
+  if (id === undefined) return null;
+  return {
+    id,
+    webhookId: str(raw.webhookId),
+    label: str(raw.label) ?? id,
+    secret: str(raw.secret),
+    createdAt: str(raw.createdAt) ?? '',
+  };
+}
+
+export function listEndpoints(): Endpoint[] {
+  const raw = readJson<AccountRecord[]>(accountsFile(), [], {
+    warn: 'webhook-accounts.json: malformed, ignoring',
+  });
+  if (!Array.isArray(raw)) return [];
+  return raw.map(toEndpoint).filter((e): e is Endpoint => e !== null);
+}
+
+export const findEndpointByWebhookId = (
+  webhookId: string,
+): Endpoint | undefined =>
+  listEndpoints().find((e) => e.webhookId === webhookId);
+
+export function tokenMatches(secret: string, given: string): boolean {
+  const want = Buffer.from(secret);
+  const got = Buffer.from(given);
+  return want.length === got.length && timingSafeEqual(want, got);
+}

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

@@ -0,0 +1,84 @@
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { ApiError } from '@metro-labs/http/api-error';
+import { bodyField, readJsonBody, sessionRoute } from '@metro-labs/http/api-http';
+import { log } from '@metro-labs/core/log';
+import { mintTerminalTicket } from './tickets.js';
+import { agentCommand, asAgent, claudeHome } from '../agent-user/user.js';
+import { inSessionScope } from '../claude/memory.js';
+import { tmuxServerUp } from '../claude/session.js';
+
+const PREFIX = '/api/terminal';
+const TICKETS = `${PREFIX}/tickets`;
+const SESSION_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$/;
+
+const scoped = (command: string[]): string[] => {
+  if (tmuxServerUp()) return command;
+  const [file = '', ...args] = command;
+  const [bin, argv] = inSessionScope([file, args]);
+  return [bin, ...argv];
+};
+
+export const tmuxCommand = (session: string, home = claudeHome() ?? homedir()): string[] => scoped(agentCommand([
+  'tmux',
+  'new-session',
+  '-A',
+  '-D',
+  '-s',
+  session,
+  '-c',
+  home,
+  ';',
+  'set-option',
+  '-g',
+  'mouse',
+  'on',
+  ';',
+  'set-option',
+  '-s',
+  'set-clipboard',
+  'on',
+  ';',
+  'set-option',
+  '-as',
+  'terminal-features',
+  ',xterm-256color:clipboard',
+], { TERM: 'xterm-256color', COLORTERM: 'truecolor' }));
+
+export interface TerminalApiDeps {
+  command?: (session: string) => string[];
+}
+
+function tmuxAvailable(deps: TerminalApiDeps): boolean {
+  if (deps.command !== undefined) return true;
+  const run = spawnSync(...asAgent('tmux', ['-V']), { stdio: 'ignore' });
+  return run.error === undefined && run.status === 0;
+}
+
+function tmuxSessions(): string[] {
+  const run = spawnSync(...asAgent('tmux', ['list-sessions', '-F', '#{session_name}']), { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  if (run.error !== undefined || run.status !== 0) return [];
+  return run.stdout
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => SESSION_RE.test(l));
+}
+
+function sessionOf(raw: unknown): string {
+  if (raw === undefined || raw === null || raw === '')
+    throw new ApiError('name the tmux session to open; GET /api/terminal lists the ones that exist', 400);
+  if (typeof raw !== 'string' || !SESSION_RE.test(raw))
+    throw new ApiError('a session name is 1 to 32 letters, digits, dots, dashes or underscores', 400);
+  return raw;
+}
+
+export function handleTerminalRequest(req: IncomingMessage, res: ServerResponse, deps: TerminalApiDeps): boolean {
+  return sessionRoute(req, res, { methods: { [PREFIX]: ['GET'], [TICKETS]: ['POST'] }, admin: true, label: 'terminal-api' }, async (session, path) => {
+    if (path === PREFIX) return { available: tmuxAvailable(deps), sessions: tmuxSessions() };
+    const wanted = sessionOf(bodyField(await readJsonBody(req), 'session'));
+    const minted = mintTerminalTicket(session.subject, wanted);
+    log.info({ subject: session.subject, session: wanted }, 'terminal: ticket minted');
+    return { ...minted, session: wanted, path: `${PREFIX}/${minted.ticket}` };
+  });
+}

package/runtime/node_modules/@metro-labs/daemon/src/terminal/socket.ts

@@ -0,0 +1,124 @@
+import { spawn } from 'node:child_process';
+import type { IncomingMessage, Server } from 'node:http';
+import type { Duplex } from 'node:stream';
+import { WebSocketServer, type RawData, type WebSocket } from 'ws';
+import { errMsg, log } from '@metro-labs/core/log';
+import { isRecord } from '@metro-labs/core/is-record';
+import { takeTerminalTicket, type TerminalGrant } from './tickets.js';
+import { asAgent } from '../agent-user/user.js';
+
+const TICKET_PATH = /^\/api\/terminal\/([A-Za-z0-9_-]{43})$/;
+const MAX_MESSAGE = 1024 * 1024;
+const DEFAULT_COLS = 120;
+const DEFAULT_ROWS = 36;
+const MAX_DIMENSION = 500;
+
+export interface TerminalSocketDeps {
+  command: (session: string) => string[];
+  takeTicket?: (ticket: string) => TerminalGrant | null;
+}
+
+const rawBytes = (data: RawData): Buffer =>
+  Buffer.isBuffer(data) ? data : Array.isArray(data) ? Buffer.concat(data) : Buffer.from(data);
+
+export const resizeWindowArgs = (session: string, cols: number, rows: number): string[] => [
+  'resize-window',
+  '-t',
+  `${session}:`,
+  '-x',
+  String(cols),
+  '-y',
+  String(rows),
+];
+
+function sizeTmuxWindow(command: string[], session: string, cols: number, rows: number): void {
+  if (!command.includes('tmux')) return;
+  const child = spawn(...asAgent('tmux', resizeWindowArgs(session, cols, rows)), { stdio: 'ignore' });
+  child.on('error', (err) => {
+    log.warn({ err: errMsg(err) }, 'terminal: resize-window could not run');
+  });
+  child.on('exit', (code) => {
+    if (code !== 0) log.warn({ code, session, cols, rows }, 'terminal: tmux refused the window resize');
+  });
+}
+
+const dimension = (raw: unknown): number | null =>
+  typeof raw === 'number' && Number.isInteger(raw) && raw > 1 && raw <= MAX_DIMENSION ? raw : null;
+
+function sizeFrom(control: unknown): { cols: number; rows: number } | null {
+  if (!isRecord(control)) return null;
+  const cols = dimension(control.cols);
+  const rows = dimension(control.rows);
+  return cols === null || rows === null ? null : { cols, rows };
+}
+
+function runTerminal(ws: WebSocket, command: string[], subject: string, session: string): void {
+  const terminal = new Bun.Terminal({
+    cols: DEFAULT_COLS,
+    rows: DEFAULT_ROWS,
+    data: (_term, chunk) => {
+      if (ws.readyState === ws.OPEN) ws.send(chunk);
+    },
+  });
+  const proc = Bun.spawn(command, {
+    terminal,
+    env: { ...process.env, TERM: 'xterm-256color', COLORTERM: 'truecolor' },
+  });
+  log.info({ subject, pid: proc.pid, command: command[0] }, 'terminal: opened');
+  ws.on('message', (data, isBinary) => {
+    const bytes = rawBytes(data);
+    if (isBinary) {
+      terminal.write(bytes);
+      return;
+    }
+    try {
+      const size = sizeFrom(JSON.parse(bytes.toString('utf8')));
+      if (size !== null) {
+        terminal.resize(size.cols, size.rows);
+        proc.kill('SIGWINCH');
+        sizeTmuxWindow(command, session, size.cols, size.rows);
+      }
+    } catch (err) {
+      log.warn({ err: errMsg(err) }, 'terminal: bad control frame');
+    }
+  });
+  ws.on('close', () => {
+    proc.kill();
+    terminal.close();
+    log.info({ subject, pid: proc.pid }, 'terminal: closed by the page');
+  });
+  proc.exited
+    .then((code) => {
+      if (ws.readyState === ws.OPEN) ws.close(1000, `exit ${String(code)}`);
+      terminal.close();
+    })
+    .catch((err: unknown) => {
+      log.warn({ err: errMsg(err) }, 'terminal: exit watch failed');
+    });
+}
+
+function refuse(socket: Duplex, status: number, text: string): void {
+  socket.write(`HTTP/1.1 ${String(status)} ${text}\r\nConnection: close\r\n\r\n`);
+  socket.destroy();
+}
+
+export function attachTerminalSockets(server: Server, deps: TerminalSocketDeps): void {
+  const wss = new WebSocketServer({ noServer: true, maxPayload: MAX_MESSAGE });
+  const take = deps.takeTicket ?? takeTerminalTicket;
+  server.on('upgrade', (req: IncomingMessage, socket: Duplex, head: Buffer) => {
+    const path = (req.url ?? '').split('?')[0] ?? '';
+    const found = TICKET_PATH.exec(path);
+    if (!found) {
+      refuse(socket, 404, 'Not Found');
+      return;
+    }
+    const grant = take(found[1] ?? '');
+    if (grant === null) {
+      refuse(socket, 401, 'Unauthorized');
+      return;
+    }
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      runTerminal(ws, deps.command(grant.session), grant.subject, grant.session);
+    });
+  });
+}

package/runtime/node_modules/@metro-labs/daemon/src/terminal/tickets.ts

@@ -0,0 +1,15 @@
+import { ticketStore } from '@metro-labs/core/tickets';
+
+export interface TerminalGrant {
+  subject: string;
+  session: string;
+}
+
+const tickets = ticketStore<TerminalGrant>(30_000, 20);
+
+export const mintTerminalTicket = (subject: string, session: string, now = Date.now()): { ticket: string; expiresAt: number } =>
+  tickets.mint({ subject, session }, now);
+
+export const takeTerminalTicket = (ticket: string, now = Date.now()): TerminalGrant | null => tickets.take(ticket, now) ?? null;
+
+export const pendingTerminalTickets = (): number => tickets.size();

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

@@ -0,0 +1,45 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { ApiError } from '@metro-labs/http/api-error';
+import { bodyField, readJsonBody, sessionRoute } from '@metro-labs/http/api-http';
+import { isRecord } from '@metro-labs/core/is-record';
+import { log } from '@metro-labs/core/log';
+import { sessionRunning, stopSession } from '../claude/session.js';
+import { agentUser } from '../agent-user/user.js';
+import { applyVault, vaultStatus } from './index.js';
+import { recentRequests } from './proxy.js';
+import { addSecret, readVault, removeSecret, setVaultEnabled, updateSecret, type SecretInput } from './store.js';
+
+const PATH = '/api/vault';
+
+function view(): unknown {
+  return { ...vaultStatus(), secrets: readVault().secrets, recent: recentRequests().slice(0, 100) };
+}
+
+const inputOf = (body: unknown): SecretInput => (isRecord(body) ? { name: body.name, env: body.env, hosts: body.hosts, value: body.value } : {});
+
+function change(body: unknown): void {
+  const action = bodyField(body, 'action');
+  const id = bodyField(body, 'id');
+  if (action === 'enable' || action === 'disable') {
+    if (agentUser() === null) throw new ApiError('the vault needs Claude Code running as its own user (a Linux box)', 409);
+    setVaultEnabled(action === 'enable');
+  } else if (action === 'add') addSecret(inputOf(body));
+  else if (action === 'update' && typeof id === 'string') updateSecret(id, inputOf(body));
+  else if (action === 'remove' && typeof id === 'string') removeSecret(id);
+  else throw new ApiError('action must be enable, disable, add, update or remove', 400);
+}
+
+async function answer(req: IncomingMessage): Promise<unknown> {
+  if (req.method === 'GET') return view();
+  change(await readJsonBody(req));
+  const { envChanged } = await applyVault();
+  if (envChanged && sessionRunning()) {
+    stopSession();
+    log.info('vault: the Claude session restarts to pick up the new environment');
+  }
+  return view();
+}
+
+export function handleVaultRequest(req: IncomingMessage, res: ServerResponse): boolean {
+  return sessionRoute(req, res, { methods: { [PATH]: ['GET', 'POST'] }, admin: true, label: 'vault-api' }, () => answer(req));
+}

package/runtime/node_modules/@metro-labs/daemon/src/vault/config.ts

@@ -0,0 +1,51 @@
+import { caDir, ports, valueFile, vaultDir } from './paths.js';
+import type { VaultSecret } from './store.js';
+import { join } from 'node:path';
+
+export const MANAGEMENT_KEY_ENV = 'IRON_MANAGEMENT_API_KEY';
+
+function secretEntry(secret: VaultSecret, dir: string): Record<string, unknown> {
+  return {
+    source: { type: 'file', path: valueFile(secret.id, dir) },
+    replace: { proxy_value: secret.env, match_headers: [], match_query: true },
+    rules: secret.hosts.map((host) => ({ host })),
+  };
+}
+
+export function proxyConfig(secrets: VaultSecret[], dir = vaultDir()): Record<string, unknown> {
+  const p = ports();
+  const local = (port: number): string => `127.0.0.1:${String(port)}`;
+  return {
+    dns: { enabled: false },
+    proxy: {
+      tunnel_listen: local(p.tunnel),
+      http_listen: local(p.http),
+      https_listen: local(p.https),
+      upstream_response_header_timeout: '10m',
+    },
+    tls: { mode: 'mitm', ca_cert: join(caDir(dir), 'ca.crt'), ca_key: join(caDir(dir), 'ca.key') },
+    transforms: secrets.length === 0 ? [] : [{ name: 'secrets', config: { secrets: secrets.map((s) => secretEntry(s, dir)) } }],
+    metrics: { listen: local(p.metrics) },
+    management: { listen: local(p.management), api_key_env: MANAGEMENT_KEY_ENV },
+    log: { level: 'info' },
+  };
+}
+
+export function proxyEnvFor(caFile: string, bundle: string, secrets: VaultSecret[]): Record<string, string> {
+  const url = `http://127.0.0.1:${String(ports().tunnel)}`;
+  const skip = 'localhost,127.0.0.1,::1';
+  return {
+    HTTP_PROXY: url,
+    HTTPS_PROXY: url,
+    http_proxy: url,
+    https_proxy: url,
+    NO_PROXY: skip,
+    no_proxy: skip,
+    NODE_EXTRA_CA_CERTS: caFile,
+    SSL_CERT_FILE: bundle,
+    REQUESTS_CA_BUNDLE: bundle,
+    CURL_CA_BUNDLE: bundle,
+    GIT_SSL_CAINFO: bundle,
+    ...Object.fromEntries(secrets.map((s) => [s.env, s.env])),
+  };
+}

package/runtime/node_modules/@metro-labs/daemon/src/vault/firewall.ts

@@ -0,0 +1,9 @@
+import { mustHelper } from '../metro-user/privilege.js';
+
+export function applyFirewall(): void {
+  mustHelper(['firewall-on']);
+}
+
+export function removeFirewall(): void {
+  mustHelper(['firewall-off']);
+}

package/runtime/node_modules/@metro-labs/daemon/src/vault/index.ts

@@ -0,0 +1,96 @@
+import { writeFileSync } from 'node:fs';
+import { errMsg, log } from '@metro-labs/core/log';
+import { ensureSecureDir } from '@metro-labs/core/secure-fs';
+import { agentExtraEnv, agentUser, asAgent, setAgentExtraEnv, type AgentUser } from '../agent-user/user.js';
+import { spawnSync } from 'node:child_process';
+import { exportJobEnv } from '../agent-user/job-env.js';
+import { proxyConfig, proxyEnvFor } from './config.js';
+import { applyFirewall, removeFirewall } from './firewall.js';
+import { ensureAuthority, ensureProxyBinary } from './install.js';
+import { configFile, PROXY_VERSION, SYSTEM_BUNDLE, TRUSTED_CA, vaultDir } from './paths.js';
+import { proxyError, proxyRunning, runProxy, stopProxy } from './proxy.js';
+import { hasValue, readVault } from './store.js';
+import { trustBrowsers, trustSystem, untrustSystem } from './trust.js';
+
+export interface VaultStatus {
+  available: boolean;
+  enabled: boolean;
+  running: boolean;
+  version: string;
+  problem: string | null;
+  browsers: string | null;
+}
+
+const memory: { problem: string | null; browsers: string | null } = { problem: null, browsers: null };
+
+function pushTmuxEnv(before: Record<string, string>, after: Record<string, string>): void {
+  const has = spawnSync(...asAgent('tmux', ['list-sessions']), { stdio: 'ignore' }).status === 0;
+  if (!has) return;
+  for (const key of Object.keys(before)) if (!(key in after)) spawnSync(...asAgent('tmux', ['set-environment', '-gu', key]), { stdio: 'ignore' });
+  for (const [key, value] of Object.entries(after)) spawnSync(...asAgent('tmux', ['set-environment', '-g', key, value]), { stdio: 'ignore' });
+}
+
+const sameEnv = (a: Record<string, string>, b: Record<string, string>): boolean =>
+  JSON.stringify(Object.entries(a).sort()) === JSON.stringify(Object.entries(b).sort());
+
+function setEnv(next: Record<string, string>): boolean {
+  const before = agentExtraEnv();
+  if (sameEnv(before, next)) return false;
+  setAgentExtraEnv(next);
+  pushTmuxEnv(before, next);
+  return true;
+}
+
+function exportForJobs(user: AgentUser, env: Record<string, string>): void {
+  try {
+    exportJobEnv(user, env);
+  } catch (err) {
+    log.warn({ err: errMsg(err) }, 'vault: could not give the scheduled jobs the vault settings');
+  }
+}
+
+async function turnOn(user: AgentUser, dir: string): Promise<Record<string, string>> {
+  const bin = await ensureProxyBinary(dir);
+  const ca = ensureAuthority(bin, dir);
+  const secrets = readVault(dir).secrets.filter((s) => hasValue(s.id, dir));
+  ensureSecureDir(dir);
+  writeFileSync(configFile(dir), JSON.stringify(proxyConfig(secrets, dir), null, 2), { mode: 0o600 });
+  trustSystem(ca);
+  memory.browsers = trustBrowsers(user);
+  await runProxy(bin, configFile(dir));
+  applyFirewall();
+  return proxyEnvFor(TRUSTED_CA, SYSTEM_BUNDLE, secrets);
+}
+
+function turnOff(): void {
+  removeFirewall();
+  stopProxy();
+  untrustSystem();
+}
+
+export async function applyVault(user: AgentUser | null = agentUser(), dir = vaultDir()): Promise<{ status: VaultStatus; envChanged: boolean }> {
+  if (user === null) return { status: vaultStatus(null, dir), envChanged: false };
+  const enabled = readVault(dir).enabled;
+  try {
+    const env = enabled ? await turnOn(user, dir) : (turnOff(), {});
+    memory.problem = null;
+    const envChanged = setEnv(env);
+    if (envChanged || enabled) exportForJobs(user, env);
+    return { status: vaultStatus(user, dir), envChanged };
+  } catch (err) {
+    memory.problem = errMsg(err);
+    log.warn({ err: memory.problem }, 'vault: could not apply the vault');
+    return { status: vaultStatus(user, dir), envChanged: false };
+  }
+}
+
+export function vaultStatus(user: AgentUser | null = agentUser(), dir = vaultDir()): VaultStatus {
+  return {
+    available: user !== null,
+    enabled: user !== null && readVault(dir).enabled,
+    running: proxyRunning(),
+    version: PROXY_VERSION,
+    problem: memory.problem ?? (readVault(dir).enabled ? proxyError() : null),
+    browsers: memory.browsers,
+  };
+}

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

@@ -0,0 +1,56 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { chmodSync, copyFileSync, existsSync, mkdtempSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { ensureSecureDir } from '@metro-labs/core/secure-fs';
+import { binDir, caDir, PROXY_VERSION, proxyBin, vaultDir } from './paths.js';
+
+const RELEASES = `https://github.com/ironsh/iron-proxy/releases/download/v${PROXY_VERSION}`;
+
+export const archiveName = (arch = process.arch): string => `iron-proxy_${PROXY_VERSION}_linux_${arch === 'arm64' ? 'arm64' : 'amd64'}.tar.gz`;
+
+export function expectedSum(checksums: string, file: string): string | null {
+  const line = checksums.split('\n').find((l) => l.trim().endsWith(` ${file}`));
+  const sum = line?.trim().split(/\s+/)[0];
+  return sum !== undefined && /^[0-9a-f]{64}$/.test(sum) ? sum : null;
+}
+
+async function download(url: string): Promise<Buffer> {
+  const res = await fetch(url, { redirect: 'follow', signal: AbortSignal.timeout(120_000) });
+  if (!res.ok) throw new Error(`${url} answered ${String(res.status)}`);
+  return Buffer.from(await res.arrayBuffer());
+}
+
+export async function ensureProxyBinary(dir = vaultDir()): Promise<string> {
+  const bin = proxyBin(dir);
+  if (existsSync(bin)) return bin;
+  const file = archiveName();
+  const [archive, checksums] = await Promise.all([download(`${RELEASES}/${file}`), download(`${RELEASES}/checksums.txt`)]);
+  const want = expectedSum(checksums.toString('utf8'), file);
+  const got = createHash('sha256').update(archive).digest('hex');
+  if (want === null || want !== got) throw new Error(`the iron-proxy download does not match its checksum (${file})`);
+  const work = mkdtempSync(join(tmpdir(), 'metro-iron-'));
+  try {
+    writeFileSync(join(work, file), archive);
+    const untar = spawnSync('tar', ['-xzf', file, 'iron-proxy'], { cwd: work, encoding: 'utf8' });
+    if (untar.status !== 0) throw new Error(`could not unpack iron-proxy: ${untar.stderr.trim()}`);
+    ensureSecureDir(binDir(dir));
+    copyFileSync(join(work, 'iron-proxy'), `${bin}.part`);
+    chmodSync(`${bin}.part`, 0o755);
+    renameSync(`${bin}.part`, bin);
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
+  return bin;
+}
+
+export function ensureAuthority(bin: string, dir = vaultDir()): string {
+  const cert = join(caDir(dir), 'ca.crt');
+  if (existsSync(cert) && existsSync(join(caDir(dir), 'ca.key'))) return cert;
+  ensureSecureDir(caDir(dir));
+  const made = spawnSync(bin, ['generate-ca', '-outdir', caDir(dir), '-name', 'Metro vault', '-expiry-hours', '87600', '-alg', 'rsa4096'], { encoding: 'utf8' });
+  if (made.status !== 0) throw new Error(`could not create the vault certificate: ${made.stderr.trim()}`);
+  chmodSync(join(caDir(dir), 'ca.key'), 0o600);
+  return cert;
+}

package/runtime/node_modules/@metro-labs/daemon/src/vault/paths.ts

@@ -0,0 +1,26 @@
+import { join } from 'node:path';
+import { agentsDir } from '../agents/files.js';
+
+export const PROXY_VERSION = '0.50.0';
+
+const basePort = (): number => {
+  const raw = Number(process.env.METRO_VAULT_PORT);
+  return Number.isInteger(raw) && raw > 1024 && raw < 65000 ? raw : 8421;
+};
+
+export const ports = (): { tunnel: number; http: number; https: number; management: number; metrics: number } => {
+  const base = basePort();
+  return { tunnel: base, http: base + 1, https: base + 2, management: base + 3, metrics: base + 4 };
+};
+
+export const vaultDir = (dir = agentsDir()): string => join(dir, 'vault');
+export const stateFile = (dir = vaultDir()): string => join(dir, 'vault.json');
+export const valuesDir = (dir = vaultDir()): string => join(dir, 'values');
+export const valueFile = (id: string, dir = vaultDir()): string => join(valuesDir(dir), id);
+export const caDir = (dir = vaultDir()): string => join(dir, 'ca');
+export const binDir = (dir = vaultDir()): string => join(dir, 'bin');
+export const proxyBin = (dir = vaultDir()): string => join(binDir(dir), `iron-proxy-${PROXY_VERSION}`);
+export const configFile = (dir = vaultDir()): string => join(dir, 'iron-proxy.json');
+
+export const TRUSTED_CA = '/usr/local/share/ca-certificates/metro-vault.crt';
+export const SYSTEM_BUNDLE = '/etc/ssl/certs/ca-certificates.crt';