@constructive-db/machine-runner 0.1.0

package/esm/run.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+import { createLogger } from '@pgpmjs/logger';
+import { defaultConfigPath, RUNNER_USAGE, runRunnerCli } from './cli';
+import { loadRunnerConfig } from './config';
+import { MachineRunner } from './runner';
+import { ensureSpawnHelperExecutable, nodePtyRoot } from './spawn-helper';
+const logger = createLogger('machine-runner');
+/**
+ * Boot the daemon. `start` is what this process did before it grew verbs, and
+ * `--config <path>` / `MACHINE_RUNNER_CONFIG` still address the same file
+ * `enroll` writes.
+ */
+export function bootMachineRunner(argv) {
+    const flagIndex = argv.indexOf('--config');
+    const configPath = flagIndex >= 0 ? argv[flagIndex + 1] : defaultConfigPath();
+    if (!configPath) {
+        throw new Error('machine-runner: pass --config <path> or set MACHINE_RUNNER_CONFIG to the config file');
+    }
+    const config = loadRunnerConfig(configPath);
+    // Before the first session, not on its failure: an unusable spawn-helper
+    // surfaces as EACCES from deep inside forkpty, and the fix is a mode bit npm
+    // dropped rather than anything the tenant asked for.
+    for (const helper of ensureSpawnHelperExecutable(nodePtyRoot())) {
+        logger.warn(`machine-runner: restored the executable bit on ${helper}`);
+    }
+    const runner = new MachineRunner({
+        enrollments: config.enrollments,
+        policy: config.policy,
+        logger
+    });
+    runner.start();
+    return runner;
+}
+function readStdin() {
+    return new Promise((resolve, reject) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', chunk => {
+            data += chunk;
+        });
+        process.stdin.on('end', () => resolve(data));
+        process.stdin.on('error', reject);
+    });
+}
+function daemonize(argv) {
+    const runner = bootMachineRunner(argv);
+    const shutdown = () => {
+        runner.stop();
+        process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+}
+async function main(argv) {
+    const io = {
+        out: line => process.stdout.write(`${line}\n`),
+        readStdin,
+        env: process.env
+    };
+    const [command, ...rest] = argv;
+    // `start` takes over the process, so it is not one of the CLI's verbs.
+    if (command === 'start') {
+        daemonize(rest);
+        return;
+    }
+    const handled = await runRunnerCli(argv, io);
+    if (handled)
+        return;
+    // No verb at all keeps the pre-verb entrypoint working — the deployed unit
+    // and the bundle both invoke `run.js --config <path>`.
+    if (!command || command.startsWith('--')) {
+        daemonize(argv);
+        return;
+    }
+    throw new Error(`machine-runner: unknown command '${command}'\n\n${RUNNER_USAGE}`);
+}
+if (require.main === module) {
+    main(process.argv.slice(2)).catch(err => {
+        logger.error(`machine-runner failed to start: ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
+    });
+}

package/esm/runner.js

@@ -0,0 +1,378 @@
+// One outbound connection per enrollment. The runner dials the relay, keeps
+// the socket alive with a reconnect loop, and serves sessions: an `open`
+// frame spawns a pty (after the local policy says yes), `input`/`resize`/
+// `signal` drive it, and its output and exit stream back as frames. Nothing
+// here ever listens on a port.
+//
+// A pty outlives the socket that asked for it. An interactive session is a
+// terminal on this machine, not a state of the connection, so `detach` (and a
+// dropped relay) stop the *streaming* and leave the process running; the bytes
+// it writes while nobody is watching go into a capped ring buffer, and a later
+// `reattach` — from whichever client the tenant then authorizes — replays that
+// ring so the program repaints. The runner is the only place those bytes are
+// held in memory, and it holds a bounded window of them, never a transcript.
+import { decodeFrame, encodeFrame, HEADER_MACHINE_DATABASE, HEADER_MACHINE_ID, RUNNER_CONNECT_PATH } from '@constructive-db/machine-protocol';
+import * as pty from 'node-pty';
+import { WebSocket } from 'ws';
+import { PolicyViolationError, resolveSpawn } from './policy';
+/** Stop presenting a credential this long before it expires. */
+const CREDENTIAL_SKEW_MS = 30_000;
+/**
+ * How much recent output an unwatched session keeps, in characters. Bounded on
+ * purpose: it is a repaint buffer, not a recording, and the oldest bytes are
+ * dropped rather than growing a detached session without limit.
+ */
+const SCROLLBACK_LIMIT = 64 * 1024;
+/**
+ * Signals delivered as the terminal's own control characters instead of to a
+ * pid. `kill(SIGINT)` would signal the session leader — the shell — which
+ * either ignores it or dies; writing the interrupt character lets the pty's
+ * line discipline deliver it to the *foreground* process group, which is how a
+ * keyboard `^C` stops the running command and leaves the shell prompt behind.
+ */
+const CONTROL_CHARACTERS = {
+    SIGINT: '\x03',
+    SIGQUIT: '\x1c'
+};
+/** The connection for one enrollment: dial, serve sessions, redial on drop. */
+export class EnrollmentRunner {
+    enrollment;
+    policy;
+    logger;
+    reconnectInitialMs;
+    reconnectMaxMs;
+    ws = null;
+    sessions = new Map();
+    /**
+     * The short-lived credential the relay minted for the last dial, held in
+     * memory only: it is never logged and never written beside the enrollment
+     * file, and it is dropped once it can no longer verify so the next dial falls
+     * back to the enrollment token and is issued a fresh one.
+     */
+    credential = null;
+    reconnectDelayMs;
+    reconnectTimer = null;
+    stopped = false;
+    constructor(options) {
+        this.enrollment = options.enrollment;
+        this.policy = options.policy;
+        this.logger = options.logger;
+        this.reconnectInitialMs = options.reconnectInitialMs ?? 250;
+        this.reconnectMaxMs = options.reconnectMaxMs ?? 10_000;
+        this.reconnectDelayMs = this.reconnectInitialMs;
+    }
+    start() {
+        this.stopped = false;
+        this.connect();
+    }
+    stop() {
+        this.stopped = true;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        // Stopping the daemon is the one case where a live terminal does not
+        // survive: the process tree it belongs to is going away with it.
+        for (const [sessionId, session] of this.sessions) {
+            session.proc.kill();
+            this.sessions.delete(sessionId);
+        }
+        this.ws?.terminate();
+        this.ws = null;
+    }
+    get connected() {
+        return this.ws !== null && this.ws.readyState === WebSocket.OPEN;
+    }
+    /** Sessions this runner still holds, for tests and a future status frame. */
+    get liveSessions() {
+        return [...this.sessions.keys()];
+    }
+    /**
+     * What to present on this dial: the credential from the last exchange while it
+     * still verifies, else the enrollment token. The enrollment token buys an
+     * exchange; it is not the standing credential.
+     */
+    secret() {
+        const held = this.credential;
+        if (held && held.expiresAt * 1000 > Date.now() + CREDENTIAL_SKEW_MS)
+            return held.value;
+        this.credential = null;
+        return this.enrollment.token;
+    }
+    /**
+     * Send on whichever socket is current. A session outlives the socket it was
+     * opened on, so its output must never be pinned to a closed one.
+     */
+    send(frame) {
+        const ws = this.ws;
+        if (ws && ws.readyState === WebSocket.OPEN)
+            ws.send(encodeFrame(frame));
+    }
+    connect() {
+        const { relayUrl, machineId, database } = this.enrollment;
+        const url = new URL(RUNNER_CONNECT_PATH, relayUrl);
+        const ws = new WebSocket(url, {
+            headers: {
+                authorization: `Bearer ${this.secret()}`,
+                [HEADER_MACHINE_ID]: machineId,
+                [HEADER_MACHINE_DATABASE]: database
+            }
+        });
+        this.ws = ws;
+        ws.on('open', () => {
+            this.reconnectDelayMs = this.reconnectInitialMs;
+            this.logger.info(`machine-runner: '${machineId}' connected to ${relayUrl}`);
+        });
+        ws.on('message', raw => {
+            let frame;
+            try {
+                frame = decodeFrame(raw.toString());
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                this.logger.error(`machine-runner: bad frame from relay: ${message}`);
+                ws.close(4002, 'protocol error');
+                return;
+            }
+            this.handleFrame(ws, frame);
+        });
+        // 'close' always follows an errored socket, so the reconnect is scheduled
+        // there; here the failure only needs to be visible.
+        ws.on('error', err => {
+            this.logger.warn(`machine-runner: '${machineId}' socket error: ${err.message}`);
+        });
+        ws.on('close', () => {
+            if (this.ws !== ws)
+                return;
+            this.ws = null;
+            // A dropped relay is a detach the tenant never asked for: an interactive
+            // terminal keeps running and buffers, so a reattach after the relay comes
+            // back finds it alive. A command-mode session has no one to stream to and
+            // nothing to come back for, so it ends with its connection.
+            for (const [sessionId, session] of this.sessions) {
+                session.streaming = false;
+                if (session.interactive)
+                    continue;
+                session.proc.kill();
+                this.sessions.delete(sessionId);
+            }
+            if (this.stopped)
+                return;
+            this.logger.warn(`machine-runner: '${machineId}' disconnected, reconnecting in ${this.reconnectDelayMs}ms`);
+            this.reconnectTimer = setTimeout(() => {
+                this.reconnectTimer = null;
+                this.connect();
+            }, this.reconnectDelayMs);
+            this.reconnectDelayMs = Math.min(this.reconnectDelayMs * 2, this.reconnectMaxMs);
+        });
+    }
+    handleFrame(ws, frame) {
+        switch (frame.type) {
+            case 'open':
+                this.openSession(ws, frame.sessionId, frame.command, frame.args ?? [], {
+                    interactive: frame.interactive === true,
+                    cols: frame.cols,
+                    rows: frame.rows
+                });
+                return;
+            case 'input': {
+                const session = this.require(ws, frame.sessionId);
+                if (!session)
+                    return;
+                session.proc.write(frame.data);
+                return;
+            }
+            case 'resize': {
+                const session = this.require(ws, frame.sessionId);
+                if (!session)
+                    return;
+                session.cols = frame.cols;
+                session.rows = frame.rows;
+                session.proc.resize(frame.cols, frame.rows);
+                return;
+            }
+            case 'signal': {
+                const session = this.require(ws, frame.sessionId);
+                if (!session)
+                    return;
+                this.deliverSignal(session, frame.sessionId, frame.signal);
+                return;
+            }
+            case 'detach': {
+                const session = this.require(ws, frame.sessionId);
+                if (!session)
+                    return;
+                // The terminal keeps running; what stops is the streaming. The window it
+                // buffered goes back once, for the ledger to record, and is then dropped
+                // from this side of the wire.
+                session.streaming = false;
+                ws.send(encodeFrame({
+                    type: 'scrollback',
+                    sessionId: frame.sessionId,
+                    data: session.scrollback,
+                    truncated: session.truncated
+                }));
+                return;
+            }
+            case 'reattach': {
+                const session = this.require(ws, frame.sessionId);
+                if (!session)
+                    return;
+                session.streaming = true;
+                if (frame.cols !== undefined && frame.rows !== undefined) {
+                    session.cols = frame.cols;
+                    session.rows = frame.rows;
+                    session.proc.resize(frame.cols, frame.rows);
+                }
+                // Repaint: what the terminal looked like to whoever left it. A full-screen
+                // program redraws on the resize above, so this is what makes a scrolling
+                // session (a shell's history) come back too.
+                if (session.scrollback.length > 0) {
+                    ws.send(encodeFrame({ type: 'output', sessionId: frame.sessionId, data: session.scrollback }));
+                }
+                return;
+            }
+            case 'close': {
+                const session = this.sessions.get(frame.sessionId);
+                if (session) {
+                    session.proc.kill();
+                    this.sessions.delete(frame.sessionId);
+                }
+                return;
+            }
+            case 'enrolled':
+                // The exchange's result: the tenant resolved this machine to a principal
+                // and minted a credential to dial with next time. Its value never reaches
+                // the log — only that it exists, and for how long.
+                this.credential = { value: frame.credential, expiresAt: frame.expiresAt };
+                this.logger.info(`machine-runner: '${frame.machineId}' enrolled as principal ${frame.principalId}; ` +
+                    `credential valid for ${Math.max(0, frame.expiresAt - Math.floor(Date.now() / 1000))}s`);
+                return;
+            default:
+                this.logger.error(`machine-runner: unexpected '${frame.type}' frame from relay`);
+                ws.close(4002, 'protocol error');
+        }
+    }
+    /** The session a frame addresses, or an `error` frame back and undefined. */
+    require(ws, sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            ws.send(encodeFrame({ type: 'error', sessionId, message: 'unknown session' }));
+            return undefined;
+        }
+        return session;
+    }
+    /**
+     * Deliver a signal the way a terminal would. The two signals a keyboard
+     * produces go through the line discipline so they reach the foreground
+     * process group; the rest go to the session leader and therefore end the
+     * session, which is what asking for them means.
+     */
+    deliverSignal(session, sessionId, signal) {
+        const character = CONTROL_CHARACTERS[signal];
+        if (character) {
+            session.proc.write(character);
+            return;
+        }
+        try {
+            session.proc.kill(signal);
+        }
+        catch (err) {
+            // node-pty throws when the process is already gone, which is a race the
+            // requester should see rather than a failure of the runner.
+            const message = err instanceof Error ? err.message : String(err);
+            this.logger.warn(`machine-runner: ${signal} to session '${sessionId}' failed: ${message}`);
+            this.send({ type: 'error', sessionId, message: `${signal} failed: ${message}` });
+        }
+    }
+    openSession(ws, sessionId, command, args, shape) {
+        if (this.sessions.has(sessionId)) {
+            ws.send(encodeFrame({ type: 'error', sessionId, message: 'session id already in use' }));
+            return;
+        }
+        const cols = shape.cols ?? 80;
+        const rows = shape.rows ?? 24;
+        let proc;
+        try {
+            const spec = resolveSpawn(this.policy, command, args);
+            proc = pty.spawn(spec.command, spec.args, {
+                name: 'xterm-256color',
+                cols,
+                rows,
+                cwd: spec.cwd,
+                env: spec.env
+            });
+        }
+        catch (err) {
+            // A rejected command is the policy answering "no": the requester learns
+            // why, the machine's log records it, and the connection stays up.
+            const message = err instanceof Error ? err.message : String(err);
+            if (!(err instanceof PolicyViolationError)) {
+                this.logger.error(`machine-runner: spawn '${command}' failed: ${message}`);
+            }
+            else {
+                this.logger.warn(`machine-runner: refused '${command}': ${message}`);
+            }
+            ws.send(encodeFrame({ type: 'error', sessionId, message }));
+            return;
+        }
+        const session = {
+            proc,
+            interactive: shape.interactive,
+            cols,
+            rows,
+            streaming: true,
+            scrollback: '',
+            truncated: false
+        };
+        this.sessions.set(sessionId, session);
+        proc.onData(data => {
+            // Buffered for an interactive session whether or not anyone is watching:
+            // that buffer is the repaint a reattach needs. Command mode streams and
+            // keeps nothing — its transcript is the ledger.
+            if (session.interactive)
+                this.remember(session, data);
+            if (session.streaming)
+                this.send({ type: 'output', sessionId, data });
+        });
+        proc.onExit(({ exitCode, signal }) => {
+            this.sessions.delete(sessionId);
+            if (session.streaming)
+                this.send({ type: 'exit', sessionId, exitCode, signal });
+        });
+    }
+    /** Append to the capped ring, dropping the oldest bytes past the limit. */
+    remember(session, data) {
+        const combined = session.scrollback + data;
+        if (combined.length <= SCROLLBACK_LIMIT) {
+            session.scrollback = combined;
+            return;
+        }
+        session.scrollback = combined.slice(combined.length - SCROLLBACK_LIMIT);
+        session.truncated = true;
+    }
+}
+/** The daemon: one EnrollmentRunner per enrollment in the config. */
+export class MachineRunner {
+    runners;
+    constructor(options) {
+        if (options.enrollments.length === 0) {
+            throw new Error('machine-runner: at least one enrollment is required');
+        }
+        this.runners = options.enrollments.map(enrollment => new EnrollmentRunner({
+            enrollment,
+            policy: options.policy,
+            logger: options.logger,
+            reconnectInitialMs: options.reconnectInitialMs,
+            reconnectMaxMs: options.reconnectMaxMs
+        }));
+    }
+    start() {
+        for (const runner of this.runners)
+            runner.start();
+    }
+    stop() {
+        for (const runner of this.runners)
+            runner.stop();
+    }
+}

package/esm/spawn-helper.js

@@ -0,0 +1,46 @@
+// node-pty ships its darwin builds as prebuilt binaries in the npm tarball, and
+// the tarball does not carry the executable bit for anything outside `bin`: the
+// extracted `prebuilds/darwin-<arch>/spawn-helper` lands 0644, and the first
+// `pty.spawn()` then dies with EACCES — on the user's own laptop, which is the
+// only machine this daemon ever runs on. Restoring the bit is idempotent and
+// costs two stat calls, so the runner does it itself at startup instead of in a
+// postinstall script: `npm i -g` runs no lifecycle script of ours, and a
+// prebuild replaced by a later reinstall would lose the fix again.
+import fs from 'fs';
+import path from 'path';
+/** The mode a helper binary needs: executable wherever it is readable. */
+const EXECUTABLE_MODE = 0o755;
+/**
+ * Helper binaries the installed node-pty carries: one per prebuild it shipped,
+ * plus the one a local node-gyp build produces. Only paths that exist.
+ */
+function spawnHelpers(packageRoot) {
+    const helpers = [path.join(packageRoot, 'build', 'Release', 'spawn-helper')];
+    const prebuilds = path.join(packageRoot, 'prebuilds');
+    if (fs.existsSync(prebuilds)) {
+        for (const entry of fs.readdirSync(prebuilds)) {
+            helpers.push(path.join(prebuilds, entry, 'spawn-helper'));
+        }
+    }
+    return helpers.filter(helper => fs.existsSync(helper));
+}
+/**
+ * Make every spawn-helper of the node-pty rooted at `packageRoot` executable,
+ * and return the ones that had to be changed (nothing to say on a tree that is
+ * already correct — which is every Linux install, where there is no such file).
+ */
+export function ensureSpawnHelperExecutable(packageRoot) {
+    const repaired = [];
+    for (const helper of spawnHelpers(packageRoot)) {
+        const mode = fs.statSync(helper).mode;
+        if ((mode & 0o111) !== 0)
+            continue;
+        fs.chmodSync(helper, EXECUTABLE_MODE);
+        repaired.push(helper);
+    }
+    return repaired;
+}
+/** Where the node-pty this runner will spawn through is installed. */
+export function nodePtyRoot() {
+    return path.dirname(require.resolve('node-pty/package.json'));
+}

package/index.d.ts

@@ -0,0 +1,8 @@
+export type { CliIo } from './cli';
+export { defaultConfigPath, parseFlags, resolveEnrollmentToken, RUNNER_USAGE, runRunnerCli, TOKEN_ENV, writeEnrollment } from './cli';
+export type { Enrollment, RunnerConfig } from './config';
+export { loadRunnerConfig, parseRunnerConfig } from './config';
+export type { RunnerPolicy, SpawnSpec } from './policy';
+export { DEFAULT_ENV_ALLOW, PolicyViolationError, resolveSpawn } from './policy';
+export type { EnrollmentRunnerOptions, MachineRunnerOptions } from './runner';
+export { EnrollmentRunner, MachineRunner } from './runner';

package/index.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MachineRunner = exports.EnrollmentRunner = exports.resolveSpawn = exports.PolicyViolationError = exports.DEFAULT_ENV_ALLOW = exports.parseRunnerConfig = exports.loadRunnerConfig = exports.writeEnrollment = exports.TOKEN_ENV = exports.runRunnerCli = exports.RUNNER_USAGE = exports.resolveEnrollmentToken = exports.parseFlags = exports.defaultConfigPath = void 0;
+var cli_1 = require("./cli");
+Object.defineProperty(exports, "defaultConfigPath", { enumerable: true, get: function () { return cli_1.defaultConfigPath; } });
+Object.defineProperty(exports, "parseFlags", { enumerable: true, get: function () { return cli_1.parseFlags; } });
+Object.defineProperty(exports, "resolveEnrollmentToken", { enumerable: true, get: function () { return cli_1.resolveEnrollmentToken; } });
+Object.defineProperty(exports, "RUNNER_USAGE", { enumerable: true, get: function () { return cli_1.RUNNER_USAGE; } });
+Object.defineProperty(exports, "runRunnerCli", { enumerable: true, get: function () { return cli_1.runRunnerCli; } });
+Object.defineProperty(exports, "TOKEN_ENV", { enumerable: true, get: function () { return cli_1.TOKEN_ENV; } });
+Object.defineProperty(exports, "writeEnrollment", { enumerable: true, get: function () { return cli_1.writeEnrollment; } });
+var config_1 = require("./config");
+Object.defineProperty(exports, "loadRunnerConfig", { enumerable: true, get: function () { return config_1.loadRunnerConfig; } });
+Object.defineProperty(exports, "parseRunnerConfig", { enumerable: true, get: function () { return config_1.parseRunnerConfig; } });
+var policy_1 = require("./policy");
+Object.defineProperty(exports, "DEFAULT_ENV_ALLOW", { enumerable: true, get: function () { return policy_1.DEFAULT_ENV_ALLOW; } });
+Object.defineProperty(exports, "PolicyViolationError", { enumerable: true, get: function () { return policy_1.PolicyViolationError; } });
+Object.defineProperty(exports, "resolveSpawn", { enumerable: true, get: function () { return policy_1.resolveSpawn; } });
+var runner_1 = require("./runner");
+Object.defineProperty(exports, "EnrollmentRunner", { enumerable: true, get: function () { return runner_1.EnrollmentRunner; } });
+Object.defineProperty(exports, "MachineRunner", { enumerable: true, get: function () { return runner_1.MachineRunner; } });

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@constructive-db/machine-runner",
+  "version": "0.1.0",
+  "description": "The machine runner: a Node daemon installed on a user's own machine that dials out to a machine relay over WebSocket, spawns policy-checked processes in a pty, and streams their bytes back. No inbound port, ever.",
+  "author": "Constructive <developers@constructive.io>",
+  "license": "MIT",
+  "keywords": [
+    "pty",
+    "remote-control",
+    "terminal",
+    "websocket"
+  ],
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "bin": {
+    "machine-runner": "run.js"
+  },
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "dependencies": {
+    "@pgpmjs/logger": "^2.25.0",
+    "node-pty": "1.1.0",
+    "ws": "^8.18.0",
+    "@constructive-db/machine-protocol": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.10.4",
+    "@types/ws": "^8.5.13",
+    "jest": "^29.7.0",
+    "makage": "^0.1.12",
+    "ts-jest": "^29.2.0",
+    "typescript": "^5.1.6",
+    "@constructive-db/machine-relay": "0.1.0"
+  },
+  "scripts": {
+    "build": "makage build && cp LICENSE dist/LICENSE",
+    "build:dev": "makage build --dev && cp LICENSE dist/LICENSE",
+    "clean": "makage clean",
+    "lint": "eslint . --fix",
+    "start": "node dist/run.js",
+    "test": "jest"
+  }
+}

package/policy.d.ts

@@ -0,0 +1,27 @@
+export interface RunnerPolicy {
+    /** Commands (argv[0], exact match) a session may start. */
+    allowedCommands: string[];
+    /** Working directory every session starts in. */
+    cwd: string;
+    /**
+     * Environment the spawned process sees: `allow` names process.env vars to
+     * pass through, `set` adds explicit values. Nothing else leaks — the
+     * runner's own environment (tokens included) never reaches a session.
+     */
+    env?: {
+        allow?: string[];
+        set?: Record<string, string>;
+    };
+}
+/** Pass-through vars a pty session cannot reasonably run without. */
+export declare const DEFAULT_ENV_ALLOW: string[];
+export declare class PolicyViolationError extends Error {
+    constructor(message: string);
+}
+export interface SpawnSpec {
+    command: string;
+    args: string[];
+    cwd: string;
+    env: Record<string, string>;
+}
+export declare function resolveSpawn(policy: RunnerPolicy, command: string, args?: string[]): SpawnSpec;

package/policy.js

@@ -0,0 +1,42 @@
+"use strict";
+// Local policy: the runner, not the relay, decides what may run on the
+// machine it guards. The policy is written by the machine's owner and never
+// travels over the wire — a compromised relay can ask, but the answer is
+// decided here.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PolicyViolationError = exports.DEFAULT_ENV_ALLOW = void 0;
+exports.resolveSpawn = resolveSpawn;
+const os_1 = __importDefault(require("os"));
+/** Pass-through vars a pty session cannot reasonably run without. */
+exports.DEFAULT_ENV_ALLOW = ['PATH', 'HOME', 'TERM', 'LANG', 'USER', 'SHELL'];
+class PolicyViolationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PolicyViolationError';
+    }
+}
+exports.PolicyViolationError = PolicyViolationError;
+function resolveSpawn(policy, command, args = []) {
+    if (!policy.allowedCommands.includes(command)) {
+        throw new PolicyViolationError(`command '${command}' is not in the allowed command list`);
+    }
+    const allow = policy.env?.allow ?? exports.DEFAULT_ENV_ALLOW;
+    const env = {};
+    for (const name of allow) {
+        const value = process.env[name];
+        if (value !== undefined)
+            env[name] = value;
+    }
+    for (const [name, value] of Object.entries(policy.env?.set ?? {})) {
+        env[name] = value;
+    }
+    return {
+        command,
+        args,
+        cwd: policy.cwd || os_1.default.homedir(),
+        env
+    };
+}

package/run.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { MachineRunner } from './runner';
+/**
+ * Boot the daemon. `start` is what this process did before it grew verbs, and
+ * `--config <path>` / `MACHINE_RUNNER_CONFIG` still address the same file
+ * `enroll` writes.
+ */
+export declare function bootMachineRunner(argv: string[]): MachineRunner;