@constructive-db/machine-runner 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Interweb, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# @constructive-db/machine-runner
+
+The machine runner: the Node daemon a user installs on their own machine for
+Remote Control (constructive-planning#1690, phase 0). It dials **out** to a
+machine relay over WebSocket — it never listens on a port — spawns
+policy-checked processes in a pty (`node-pty`), and streams their bytes back
+as `@constructive-db/machine-protocol` frames. When the relay connection
+drops, it redials with exponential backoff and re-registers the machine.
+
+## Install
+
+```
+npm i -g @constructive-db/machine-runner
+```
+
+MIT-licensed and dependency-light on purpose (`node-pty`, `ws`,
+`@pgpmjs/logger`): it holds no database connection and no schema knowledge — every
+authorization answer comes from the relay it dials.
+
+## Usage
+
+```
+machine-runner --config ~/.constructive/machine-runner.json
+```
+
+The config carries a **list of enrollments** — one per relay/database this
+machine is enrolled in — plus the local policy:
+
+```json
+{
+  "enrollments": [
+    {
+      "machineId": "my-laptop",
+      "relayUrl": "wss://relay.example.com",
+      "token": "<machine token>",
+      "database": "db-uuid"
+    }
+  ],
+  "policy": {
+    "allowedCommands": ["echo", "ls", "git"],
+    "cwd": "/home/me/work",
+    "env": {
+      "allow": ["PATH", "HOME", "TERM", "LANG"],
+      "set": { "CONSTRUCTIVE_SESSION": "1" }
+    }
+  }
+}
+```
+
+The policy is decided here, on the machine, and never travels over the wire: a
+command not in `allowedCommands` is refused with an error frame, sessions
+start in the policy's `cwd`, and the spawned environment contains only the
+allow-listed pass-through variables plus the explicit `set` map — the runner's
+own environment (tokens included) never reaches a session.

package/cli.d.ts

@@ -0,0 +1,38 @@
+import { RunnerConfig } from './config';
+import { RunnerPolicy } from './policy';
+/** Env var carrying the enrollment token, for non-interactive installs. */
+export declare const TOKEN_ENV = "MACHINE_ENROLLMENT_TOKEN";
+/** Where the runner keeps its config when nothing says otherwise. */
+export declare function defaultConfigPath(): string;
+export interface CliIo {
+    /** Everything the CLI says. Never a secret. */
+    out: (line: string) => void;
+    /** Reads the enrollment token from stdin; only called when the env var is absent. */
+    readStdin: () => Promise<string>;
+    env: NodeJS.ProcessEnv;
+}
+export declare function parseFlags(argv: string[]): Record<string, string | true>;
+/**
+ * The token, from the environment or stdin. A token on the command line is a
+ * refusal, not a fallback — accepting it would put it in shell history, which
+ * is exactly the leak the paste-once flow exists to avoid.
+ */
+export declare function resolveEnrollmentToken(flags: Record<string, string | true>, io: CliIo): Promise<string>;
+/**
+ * Write (or extend) the runner config for one relay + machine. A machine can be
+ * enrolled in several databases, so an existing config is merged: the entry for
+ * the same machine at the same relay is replaced, everything else is kept.
+ */
+export declare function writeEnrollment(configPath: string, enrollment: {
+    machineId: string;
+    relayUrl: string;
+    token: string;
+    database: string;
+}, policy: RunnerPolicy): RunnerConfig;
+export declare const RUNNER_USAGE = "machine-runner <command>\n\n  enroll --relay <wss://host> --machine <uuid> --database <uuid> [--config <path>]\n         [--allow bash,sh] [--cwd <dir>]\n         reads the enrollment token from stdin or MACHINE_ENROLLMENT_TOKEN \u2014 never from argv\n\n  start  [--config <path>]   dial the relay and serve sessions\n  status [--config <path>]   what this runner is enrolled in (never secrets)";
+/**
+ * Run everything except `start`, which the entrypoint owns because it takes over
+ * the process. Returns false when the command was `start`, so the caller boots
+ * the daemon.
+ */
+export declare function runRunnerCli(argv: string[], io: CliIo): Promise<boolean>;

package/cli.js

@@ -0,0 +1,175 @@
+"use strict";
+// The runner's own command surface: `enroll`, `start`, `status`.
+//
+// It is deliberately its own binary rather than a subcommand of the
+// control-plane CLI: the runner is a daemon that needs a native `node-pty`
+// build on the box it serves, and the box is usually not the machine the
+// operator's credentials live on.
+//
+// The one rule that shapes `enroll`: the enrollment token is read from stdin or
+// an environment variable and NEVER from argv. Shell history is a log, and a
+// token in `~/.bash_history` outlives the exchange it was meant for. Passing
+// `--token` is refused rather than accepted quietly.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RUNNER_USAGE = exports.TOKEN_ENV = void 0;
+exports.defaultConfigPath = defaultConfigPath;
+exports.parseFlags = parseFlags;
+exports.resolveEnrollmentToken = resolveEnrollmentToken;
+exports.writeEnrollment = writeEnrollment;
+exports.runRunnerCli = runRunnerCli;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const config_1 = require("./config");
+/** Env var carrying the enrollment token, for non-interactive installs. */
+exports.TOKEN_ENV = 'MACHINE_ENROLLMENT_TOKEN';
+/** Where the runner keeps its config when nothing says otherwise. */
+function defaultConfigPath() {
+    return process.env.MACHINE_RUNNER_CONFIG || path_1.default.join(os_1.default.homedir(), '.machine-runner/config.json');
+}
+function parseFlags(argv) {
+    const flags = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (!arg.startsWith('--'))
+            continue;
+        const name = arg.slice(2);
+        const next = argv[i + 1];
+        if (next === undefined || next.startsWith('--')) {
+            flags[name] = true;
+        }
+        else {
+            flags[name] = next;
+            i += 1;
+        }
+    }
+    return flags;
+}
+function requireFlag(flags, name) {
+    const value = flags[name];
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`machine-runner: --${name} is required`);
+    }
+    return value;
+}
+function readTokenFromEnv(env) {
+    const value = env[exports.TOKEN_ENV];
+    return value && value.length > 0 ? value : null;
+}
+/**
+ * The token, from the environment or stdin. A token on the command line is a
+ * refusal, not a fallback — accepting it would put it in shell history, which
+ * is exactly the leak the paste-once flow exists to avoid.
+ */
+async function resolveEnrollmentToken(flags, io) {
+    if ('token' in flags) {
+        throw new Error(`machine-runner: refusing a token on the command line — shell history is a log. ` +
+            `Pipe it on stdin or set ${exports.TOKEN_ENV}.`);
+    }
+    const fromEnv = readTokenFromEnv(io.env);
+    if (fromEnv)
+        return fromEnv;
+    const fromStdin = (await io.readStdin()).trim();
+    if (!fromStdin) {
+        throw new Error(`machine-runner: no enrollment token — paste it on stdin or set ${exports.TOKEN_ENV}`);
+    }
+    return fromStdin;
+}
+function defaultPolicy(flags) {
+    const allowed = typeof flags.allow === 'string' ? flags.allow.split(',').map(c => c.trim()) : null;
+    const cwd = typeof flags.cwd === 'string' ? flags.cwd : os_1.default.homedir();
+    return {
+        allowedCommands: allowed && allowed.length > 0 ? allowed : ['bash', 'sh', 'zsh'],
+        cwd
+    };
+}
+function readExistingConfig(configPath) {
+    if (!fs_1.default.existsSync(configPath))
+        return null;
+    // A config that exists but does not parse is a fault to surface, not to
+    // overwrite: overwriting would silently drop the machine's other enrollments.
+    return (0, config_1.loadRunnerConfig)(configPath);
+}
+/**
+ * Write (or extend) the runner config for one relay + machine. A machine can be
+ * enrolled in several databases, so an existing config is merged: the entry for
+ * the same machine at the same relay is replaced, everything else is kept.
+ */
+function writeEnrollment(configPath, enrollment, policy) {
+    const existing = readExistingConfig(configPath);
+    const others = (existing?.enrollments ?? []).filter(e => !(e.machineId === enrollment.machineId && e.relayUrl === enrollment.relayUrl));
+    const next = (0, config_1.parseRunnerConfig)({
+        enrollments: [...others, enrollment],
+        policy: existing?.policy ?? policy
+    });
+    fs_1.default.mkdirSync(path_1.default.dirname(configPath), { recursive: true, mode: 0o700 });
+    // 0600 on the file: it holds the enrollment token until the first exchange
+    // replaces it with a short-lived credential.
+    fs_1.default.writeFileSync(configPath, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+    fs_1.default.chmodSync(configPath, 0o600);
+    return next;
+}
+async function enroll(flags, io) {
+    const relayUrl = requireFlag(flags, 'relay');
+    const machineId = requireFlag(flags, 'machine');
+    const database = requireFlag(flags, 'database');
+    const configPath = typeof flags.config === 'string' ? flags.config : defaultConfigPath();
+    const token = await resolveEnrollmentToken(flags, io);
+    const config = writeEnrollment(configPath, { machineId, relayUrl, token, database }, defaultPolicy(flags));
+    // Facts only. The token was written to a 0600 file and is never echoed.
+    io.out(`enrolled machine ${machineId} at ${relayUrl}`);
+    io.out(`config ${configPath} (${config.enrollments.length} enrollment(s), mode 0600)`);
+    io.out(`allowed commands: ${config.policy.allowedCommands.join(', ')}`);
+    io.out('next: machine-runner start');
+}
+function status(flags, io) {
+    const configPath = typeof flags.config === 'string' ? flags.config : defaultConfigPath();
+    if (!fs_1.default.existsSync(configPath)) {
+        io.out(`no config at ${configPath} — run: machine-runner enroll --relay <wss://…> --machine <id> --database <id>`);
+        return;
+    }
+    const config = (0, config_1.loadRunnerConfig)(configPath);
+    const mode = (fs_1.default.statSync(configPath).mode & 0o777).toString(8);
+    io.out(`config ${configPath} (mode ${mode})`);
+    io.out(`cwd ${config.policy.cwd}`);
+    io.out(`allowed commands: ${config.policy.allowedCommands.join(', ')}`);
+    for (const enrollment of config.enrollments) {
+        // `secret stored` is the only thing said about the secret, ever.
+        io.out(`machine ${enrollment.machineId} relay ${enrollment.relayUrl} database ${enrollment.database} secret stored`);
+    }
+}
+exports.RUNNER_USAGE = `machine-runner <command>
+
+  enroll --relay <wss://host> --machine <uuid> --database <uuid> [--config <path>]
+         [--allow bash,sh] [--cwd <dir>]
+         reads the enrollment token from stdin or ${exports.TOKEN_ENV} — never from argv
+
+  start  [--config <path>]   dial the relay and serve sessions
+  status [--config <path>]   what this runner is enrolled in (never secrets)`;
+/**
+ * Run everything except `start`, which the entrypoint owns because it takes over
+ * the process. Returns false when the command was `start`, so the caller boots
+ * the daemon.
+ */
+async function runRunnerCli(argv, io) {
+    const [command, ...rest] = argv;
+    const flags = parseFlags(rest);
+    switch (command) {
+        case 'enroll':
+            await enroll(flags, io);
+            return true;
+        case 'status':
+            status(flags, io);
+            return true;
+        case 'help':
+        case '--help':
+        case '-h':
+            io.out(exports.RUNNER_USAGE);
+            return true;
+        default:
+            return false;
+    }
+}

package/config.d.ts

@@ -0,0 +1,17 @@
+import { RunnerPolicy } from './policy';
+export interface Enrollment {
+    /** The machine's identity at this relay. */
+    machineId: string;
+    /** Where to dial out to, e.g. wss://relay.example.com. */
+    relayUrl: string;
+    /** The static machine token for this enrollment. Never logged. */
+    token: string;
+    /** The database this enrollment belongs to. */
+    database: string;
+}
+export interface RunnerConfig {
+    enrollments: Enrollment[];
+    policy: RunnerPolicy;
+}
+export declare function parseRunnerConfig(raw: unknown): RunnerConfig;
+export declare function loadRunnerConfig(path: string): RunnerConfig;

package/config.js

@@ -0,0 +1,73 @@
+"use strict";
+// Runner configuration: a list of enrollments (one per relay/database this
+// machine is enrolled in) plus the local policy. Loaded from a JSON file the
+// machine's owner writes; malformed config is a deployment fault and throws.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRunnerConfig = parseRunnerConfig;
+exports.loadRunnerConfig = loadRunnerConfig;
+const fs_1 = __importDefault(require("fs"));
+function requireString(obj, key, where) {
+    const value = obj[key];
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`machine-runner config: ${where} is missing '${key}'`);
+    }
+    return value;
+}
+function parseRunnerConfig(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new Error('machine-runner config: root must be an object');
+    }
+    const root = raw;
+    if (!Array.isArray(root.enrollments) || root.enrollments.length === 0) {
+        throw new Error("machine-runner config: 'enrollments' must be a non-empty array");
+    }
+    const enrollments = root.enrollments.map((entry, i) => {
+        if (typeof entry !== 'object' || entry === null) {
+            throw new Error(`machine-runner config: enrollments[${i}] must be an object`);
+        }
+        const obj = entry;
+        const where = `enrollments[${i}]`;
+        return {
+            machineId: requireString(obj, 'machineId', where),
+            relayUrl: requireString(obj, 'relayUrl', where),
+            token: requireString(obj, 'token', where),
+            database: requireString(obj, 'database', where)
+        };
+    });
+    const policy = root.policy;
+    if (typeof policy !== 'object' || policy === null) {
+        throw new Error("machine-runner config: 'policy' must be an object");
+    }
+    const policyObj = policy;
+    if (!Array.isArray(policyObj.allowedCommands) ||
+        policyObj.allowedCommands.some(c => typeof c !== 'string')) {
+        throw new Error("machine-runner config: 'policy.allowedCommands' must be a string array");
+    }
+    if (typeof policyObj.cwd !== 'string' || policyObj.cwd.length === 0) {
+        throw new Error("machine-runner config: 'policy.cwd' is required");
+    }
+    return {
+        enrollments,
+        policy: policyObj
+    };
+}
+function loadRunnerConfig(path) {
+    let raw;
+    try {
+        raw = fs_1.default.readFileSync(path, 'utf8');
+    }
+    catch (err) {
+        throw new Error(`machine-runner config: cannot read '${path}': ${err instanceof Error ? err.message : err}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`machine-runner config: '${path}' is not JSON: ${err instanceof Error ? err.message : err}`);
+    }
+    return parseRunnerConfig(parsed);
+}

package/esm/cli.js

@@ -0,0 +1,164 @@
+// The runner's own command surface: `enroll`, `start`, `status`.
+//
+// It is deliberately its own binary rather than a subcommand of the
+// control-plane CLI: the runner is a daemon that needs a native `node-pty`
+// build on the box it serves, and the box is usually not the machine the
+// operator's credentials live on.
+//
+// The one rule that shapes `enroll`: the enrollment token is read from stdin or
+// an environment variable and NEVER from argv. Shell history is a log, and a
+// token in `~/.bash_history` outlives the exchange it was meant for. Passing
+// `--token` is refused rather than accepted quietly.
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { loadRunnerConfig, parseRunnerConfig } from './config';
+/** Env var carrying the enrollment token, for non-interactive installs. */
+export const TOKEN_ENV = 'MACHINE_ENROLLMENT_TOKEN';
+/** Where the runner keeps its config when nothing says otherwise. */
+export function defaultConfigPath() {
+    return process.env.MACHINE_RUNNER_CONFIG || path.join(os.homedir(), '.machine-runner/config.json');
+}
+export function parseFlags(argv) {
+    const flags = {};
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (!arg.startsWith('--'))
+            continue;
+        const name = arg.slice(2);
+        const next = argv[i + 1];
+        if (next === undefined || next.startsWith('--')) {
+            flags[name] = true;
+        }
+        else {
+            flags[name] = next;
+            i += 1;
+        }
+    }
+    return flags;
+}
+function requireFlag(flags, name) {
+    const value = flags[name];
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`machine-runner: --${name} is required`);
+    }
+    return value;
+}
+function readTokenFromEnv(env) {
+    const value = env[TOKEN_ENV];
+    return value && value.length > 0 ? value : null;
+}
+/**
+ * The token, from the environment or stdin. A token on the command line is a
+ * refusal, not a fallback — accepting it would put it in shell history, which
+ * is exactly the leak the paste-once flow exists to avoid.
+ */
+export async function resolveEnrollmentToken(flags, io) {
+    if ('token' in flags) {
+        throw new Error(`machine-runner: refusing a token on the command line — shell history is a log. ` +
+            `Pipe it on stdin or set ${TOKEN_ENV}.`);
+    }
+    const fromEnv = readTokenFromEnv(io.env);
+    if (fromEnv)
+        return fromEnv;
+    const fromStdin = (await io.readStdin()).trim();
+    if (!fromStdin) {
+        throw new Error(`machine-runner: no enrollment token — paste it on stdin or set ${TOKEN_ENV}`);
+    }
+    return fromStdin;
+}
+function defaultPolicy(flags) {
+    const allowed = typeof flags.allow === 'string' ? flags.allow.split(',').map(c => c.trim()) : null;
+    const cwd = typeof flags.cwd === 'string' ? flags.cwd : os.homedir();
+    return {
+        allowedCommands: allowed && allowed.length > 0 ? allowed : ['bash', 'sh', 'zsh'],
+        cwd
+    };
+}
+function readExistingConfig(configPath) {
+    if (!fs.existsSync(configPath))
+        return null;
+    // A config that exists but does not parse is a fault to surface, not to
+    // overwrite: overwriting would silently drop the machine's other enrollments.
+    return loadRunnerConfig(configPath);
+}
+/**
+ * Write (or extend) the runner config for one relay + machine. A machine can be
+ * enrolled in several databases, so an existing config is merged: the entry for
+ * the same machine at the same relay is replaced, everything else is kept.
+ */
+export function writeEnrollment(configPath, enrollment, policy) {
+    const existing = readExistingConfig(configPath);
+    const others = (existing?.enrollments ?? []).filter(e => !(e.machineId === enrollment.machineId && e.relayUrl === enrollment.relayUrl));
+    const next = parseRunnerConfig({
+        enrollments: [...others, enrollment],
+        policy: existing?.policy ?? policy
+    });
+    fs.mkdirSync(path.dirname(configPath), { recursive: true, mode: 0o700 });
+    // 0600 on the file: it holds the enrollment token until the first exchange
+    // replaces it with a short-lived credential.
+    fs.writeFileSync(configPath, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+    fs.chmodSync(configPath, 0o600);
+    return next;
+}
+async function enroll(flags, io) {
+    const relayUrl = requireFlag(flags, 'relay');
+    const machineId = requireFlag(flags, 'machine');
+    const database = requireFlag(flags, 'database');
+    const configPath = typeof flags.config === 'string' ? flags.config : defaultConfigPath();
+    const token = await resolveEnrollmentToken(flags, io);
+    const config = writeEnrollment(configPath, { machineId, relayUrl, token, database }, defaultPolicy(flags));
+    // Facts only. The token was written to a 0600 file and is never echoed.
+    io.out(`enrolled machine ${machineId} at ${relayUrl}`);
+    io.out(`config ${configPath} (${config.enrollments.length} enrollment(s), mode 0600)`);
+    io.out(`allowed commands: ${config.policy.allowedCommands.join(', ')}`);
+    io.out('next: machine-runner start');
+}
+function status(flags, io) {
+    const configPath = typeof flags.config === 'string' ? flags.config : defaultConfigPath();
+    if (!fs.existsSync(configPath)) {
+        io.out(`no config at ${configPath} — run: machine-runner enroll --relay <wss://…> --machine <id> --database <id>`);
+        return;
+    }
+    const config = loadRunnerConfig(configPath);
+    const mode = (fs.statSync(configPath).mode & 0o777).toString(8);
+    io.out(`config ${configPath} (mode ${mode})`);
+    io.out(`cwd ${config.policy.cwd}`);
+    io.out(`allowed commands: ${config.policy.allowedCommands.join(', ')}`);
+    for (const enrollment of config.enrollments) {
+        // `secret stored` is the only thing said about the secret, ever.
+        io.out(`machine ${enrollment.machineId} relay ${enrollment.relayUrl} database ${enrollment.database} secret stored`);
+    }
+}
+export const RUNNER_USAGE = `machine-runner <command>
+
+  enroll --relay <wss://host> --machine <uuid> --database <uuid> [--config <path>]
+         [--allow bash,sh] [--cwd <dir>]
+         reads the enrollment token from stdin or ${TOKEN_ENV} — never from argv
+
+  start  [--config <path>]   dial the relay and serve sessions
+  status [--config <path>]   what this runner is enrolled in (never secrets)`;
+/**
+ * Run everything except `start`, which the entrypoint owns because it takes over
+ * the process. Returns false when the command was `start`, so the caller boots
+ * the daemon.
+ */
+export async function runRunnerCli(argv, io) {
+    const [command, ...rest] = argv;
+    const flags = parseFlags(rest);
+    switch (command) {
+        case 'enroll':
+            await enroll(flags, io);
+            return true;
+        case 'status':
+            status(flags, io);
+            return true;
+        case 'help':
+        case '--help':
+        case '-h':
+            io.out(RUNNER_USAGE);
+            return true;
+        default:
+            return false;
+    }
+}

package/esm/config.js

@@ -0,0 +1,66 @@
+// Runner configuration: a list of enrollments (one per relay/database this
+// machine is enrolled in) plus the local policy. Loaded from a JSON file the
+// machine's owner writes; malformed config is a deployment fault and throws.
+import fs from 'fs';
+function requireString(obj, key, where) {
+    const value = obj[key];
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`machine-runner config: ${where} is missing '${key}'`);
+    }
+    return value;
+}
+export function parseRunnerConfig(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new Error('machine-runner config: root must be an object');
+    }
+    const root = raw;
+    if (!Array.isArray(root.enrollments) || root.enrollments.length === 0) {
+        throw new Error("machine-runner config: 'enrollments' must be a non-empty array");
+    }
+    const enrollments = root.enrollments.map((entry, i) => {
+        if (typeof entry !== 'object' || entry === null) {
+            throw new Error(`machine-runner config: enrollments[${i}] must be an object`);
+        }
+        const obj = entry;
+        const where = `enrollments[${i}]`;
+        return {
+            machineId: requireString(obj, 'machineId', where),
+            relayUrl: requireString(obj, 'relayUrl', where),
+            token: requireString(obj, 'token', where),
+            database: requireString(obj, 'database', where)
+        };
+    });
+    const policy = root.policy;
+    if (typeof policy !== 'object' || policy === null) {
+        throw new Error("machine-runner config: 'policy' must be an object");
+    }
+    const policyObj = policy;
+    if (!Array.isArray(policyObj.allowedCommands) ||
+        policyObj.allowedCommands.some(c => typeof c !== 'string')) {
+        throw new Error("machine-runner config: 'policy.allowedCommands' must be a string array");
+    }
+    if (typeof policyObj.cwd !== 'string' || policyObj.cwd.length === 0) {
+        throw new Error("machine-runner config: 'policy.cwd' is required");
+    }
+    return {
+        enrollments,
+        policy: policyObj
+    };
+}
+export function loadRunnerConfig(path) {
+    let raw;
+    try {
+        raw = fs.readFileSync(path, 'utf8');
+    }
+    catch (err) {
+        throw new Error(`machine-runner config: cannot read '${path}': ${err instanceof Error ? err.message : err}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`machine-runner config: '${path}' is not JSON: ${err instanceof Error ? err.message : err}`);
+    }
+    return parseRunnerConfig(parsed);
+}

package/esm/index.js

@@ -0,0 +1,4 @@
+export { defaultConfigPath, parseFlags, resolveEnrollmentToken, RUNNER_USAGE, runRunnerCli, TOKEN_ENV, writeEnrollment } from './cli';
+export { loadRunnerConfig, parseRunnerConfig } from './config';
+export { DEFAULT_ENV_ALLOW, PolicyViolationError, resolveSpawn } from './policy';
+export { EnrollmentRunner, MachineRunner } from './runner';

package/esm/policy.js

@@ -0,0 +1,34 @@
+// 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.
+import os from 'os';
+/** Pass-through vars a pty session cannot reasonably run without. */
+export const DEFAULT_ENV_ALLOW = ['PATH', 'HOME', 'TERM', 'LANG', 'USER', 'SHELL'];
+export class PolicyViolationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PolicyViolationError';
+    }
+}
+export 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 ?? 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.homedir(),
+        env
+    };
+}