@constructive-db/machine-runner 0.2.2 → 0.3.0

package/README.md

@@ -88,6 +88,24 @@ and optionally a directory. The runner:
 - keeps a detached interactive session alive with a bounded scrollback until
   a client reattaches or the session is closed.
 
+Separately from sessions, the runner answers two read-only path requests,
+`path_list` and `path_read`, each naming a relative `path` under an optional
+`root` (itself resolved under the policy's `cwd`, as an `open`'s `cwd` is). It:
+
+- refuses an absolute path, a `..` segment or a NUL byte (`PATH_INVALID`), and
+  a path — or a symlink anywhere along it — that resolves outside the root
+  (`PATH_OUTSIDE_ROOT`);
+- answers `path_listing` (name, kind, size; symlinks reported, not followed)
+  or `path_content` (base64 bytes);
+- refuses a directory of more than `MAX_LIST_ENTRIES` entries
+  (`DIRECTORY_TOO_LARGE`) and a file of more than `MAX_READ_BYTES` bytes
+  (`FILE_TOO_LARGE`) rather than truncating either;
+- answers every failure as an `error` frame carrying the request's
+  `requestId` and one of the `PATH_ERROR_CODES`.
+
+It writes nothing. Which root a request may name is the relay's decision, not
+the runner's: the runner only guarantees it stays under its policy.
+
 That is the whole contract. An agent session is one of these whose command
 happens to be an agent program — the relay composes that command and reads
 its output; the runner ran an allow-listed command:

package/esm/files.js

@@ -0,0 +1,179 @@
+// Read-only access to paths under the policy cwd. The relay names a root (the
+// same kind of value an `open` frame's `cwd` is: relative to, and confined to,
+// the policy cwd) and a path relative to that root; the runner answers with a
+// listing or a file's bytes. Nothing here knows what the root is for.
+import { MAX_LIST_ENTRIES, MAX_READ_BYTES, relativePathProblem } from '@constructive-db/machine-protocol';
+import { constants } from 'fs';
+import fs from 'fs/promises';
+import path from 'path';
+import { PolicyViolationError, resolveCwd } from './policy';
+/** A path request refused for a reason the requester can act on. */
+export class PathAccessError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'PathAccessError';
+    }
+}
+/** An errno failure as a refusal; anything else is a bug and propagates. */
+function fsFailure(err, requested) {
+    const errno = err?.code;
+    if (typeof errno !== 'string')
+        throw err;
+    if (errno === 'ENOENT' || errno === 'ENOTDIR') {
+        return new PathAccessError('PATH_NOT_FOUND', `'${requested}' does not exist`);
+    }
+    return new PathAccessError('PATH_UNREADABLE', `'${requested}' could not be read: ${err.message}`);
+}
+/**
+ * The real path `requested` names under `root`. Refuses an absolute or
+ * traversing path outright, a root outside the policy cwd, and — after
+ * resolving every symlink — a target that is not the root or inside it.
+ */
+export async function resolveUnder(policy, root, requested) {
+    const problem = relativePathProblem(requested);
+    if (problem)
+        throw new PathAccessError('PATH_INVALID', `path '${requested}' ${problem}`);
+    let base;
+    try {
+        base = resolveCwd(policy, root);
+    }
+    catch (err) {
+        if (!(err instanceof PolicyViolationError))
+            throw err;
+        throw new PathAccessError('PATH_OUTSIDE_ROOT', err.message);
+    }
+    let realBase;
+    try {
+        realBase = await fs.realpath(base);
+    }
+    catch (err) {
+        throw fsFailure(err, root ?? '.');
+    }
+    let real;
+    try {
+        real = await fs.realpath(path.join(base, requested));
+    }
+    catch (err) {
+        throw fsFailure(err, requested);
+    }
+    if (real !== realBase && !real.startsWith(realBase + path.sep)) {
+        throw new PathAccessError('PATH_OUTSIDE_ROOT', `'${requested}' resolves outside its root`);
+    }
+    return real;
+}
+/**
+ * Refuse unless `requested` still resolves under the root to the same file as
+ * `seen` (what was opened or listed). A path component swapped for a symlink
+ * after {@link resolveUnder} looked would otherwise be followed out of the root.
+ */
+async function assertStillUnder(policy, root, requested, seen) {
+    const now = await fs.stat(await resolveUnder(policy, root, requested)).catch(err => {
+        if (err instanceof PathAccessError)
+            throw err;
+        throw fsFailure(err, requested);
+    });
+    if (now.dev !== seen.dev || now.ino !== seen.ino) {
+        throw new PathAccessError('PATH_OUTSIDE_ROOT', `'${requested}' changed while being read`);
+    }
+}
+function entryKind(entry) {
+    if (entry.isSymbolicLink())
+        return 'symlink';
+    if (entry.isFile())
+        return 'file';
+    if (entry.isDirectory())
+        return 'directory';
+    return 'other';
+}
+/**
+ * The entries of a directory under `root`, sorted by name. A directory with
+ * more than {@link MAX_LIST_ENTRIES} entries is refused, not truncated, and is
+ * not read past the limit.
+ */
+export async function listPath(policy, root, requested) {
+    const target = await resolveUnder(policy, root, requested);
+    let dir;
+    let stat;
+    try {
+        stat = await fs.stat(target);
+        if (!stat.isDirectory()) {
+            throw new PathAccessError('NOT_A_DIRECTORY', `'${requested}' is not a directory`);
+        }
+        dir = await fs.opendir(target);
+    }
+    catch (err) {
+        if (err instanceof PathAccessError)
+            throw err;
+        throw fsFailure(err, requested);
+    }
+    const entries = [];
+    try {
+        for await (const dirent of dir) {
+            if (entries.length === MAX_LIST_ENTRIES) {
+                throw new PathAccessError('DIRECTORY_TOO_LARGE', `'${requested}' has more than ${MAX_LIST_ENTRIES} entries`);
+            }
+            const kind = entryKind(dirent);
+            const entry = { name: dirent.name, kind };
+            if (kind === 'file')
+                entry.size = (await fs.lstat(path.join(target, dirent.name))).size;
+            entries.push(entry);
+        }
+    }
+    catch (err) {
+        // Throwing out of `for await` closes the directory handle.
+        if (err instanceof PathAccessError)
+            throw err;
+        throw fsFailure(err, requested);
+    }
+    await assertStillUnder(policy, root, requested, stat);
+    return entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+/**
+ * A file's bytes, base64. A file over {@link MAX_READ_BYTES} is refused, not
+ * truncated — including one that grew past the limit after it was measured.
+ * The final component is opened `O_NOFOLLOW`, so a symlink swapped in after
+ * {@link resolveUnder} looked is refused rather than followed.
+ */
+export async function readPath(policy, root, requested) {
+    const target = await resolveUnder(policy, root, requested);
+    let handle;
+    try {
+        const stat = await fs.stat(target);
+        if (!stat.isFile())
+            throw new PathAccessError('NOT_A_FILE', `'${requested}' is not a file`);
+        if (stat.size > MAX_READ_BYTES) {
+            throw new PathAccessError('FILE_TOO_LARGE', `'${requested}' is ${stat.size} bytes; the limit is ${MAX_READ_BYTES}`);
+        }
+        handle = await fs.open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (err) {
+        if (err instanceof PathAccessError)
+            throw err;
+        throw fsFailure(err, requested);
+    }
+    try {
+        await assertStillUnder(policy, root, requested, await handle.stat());
+        const buffer = Buffer.alloc(MAX_READ_BYTES + 1);
+        let size = 0;
+        for (;;) {
+            const { bytesRead } = await handle.read(buffer, size, buffer.length - size, size);
+            if (bytesRead === 0)
+                break;
+            size += bytesRead;
+            if (size > MAX_READ_BYTES) {
+                throw new PathAccessError('FILE_TOO_LARGE', `'${requested}' grew past the ${MAX_READ_BYTES}-byte limit while being read`);
+            }
+        }
+        return { data: buffer.subarray(0, size).toString('base64'), size };
+    }
+    catch (err) {
+        if (err instanceof PathAccessError)
+            throw err;
+        throw fsFailure(err, requested);
+    }
+    finally {
+        await handle.close();
+    }
+}

package/esm/index.js

@@ -1,5 +1,6 @@
 export { defaultConfigPath, parseFlags, resolveEnrollmentToken, RUNNER_USAGE, runRunnerCli, TOKEN_ENV, writeEnrollment } from './cli';
 export { loadRunnerConfig, parseRunnerConfig } from './config';
+export { listPath, PathAccessError, readPath, resolveUnder } from './files';
 export { DEFAULT_ENV_ALLOW, PolicyViolationError, resolveCwd, resolveSpawn } from './policy';
 export { pipeProcess, ptyProcess } from './process';
 export { EnrollmentRunner, MachineRunner } from './runner';

package/esm/runner.js

@@ -19,8 +19,9 @@
 // `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 { decodeFrame, encodeFrame, HEADER_MACHINE_DATABASE, HEADER_MACHINE_ID, MAX_PATH_REQUESTS_IN_FLIGHT, RUNNER_CONNECT_PATH } from '@constructive-db/machine-protocol';
 import { WebSocket } from 'ws';
+import { listPath, PathAccessError, readPath } from './files';
 import { PolicyViolationError, resolveSpawn } from './policy';
 import { pipeProcess, ptyProcess } from './process';
 /** Stop presenting a credential this long before it expires. */
@@ -51,6 +52,7 @@ export class EnrollmentRunner {
     reconnectMaxMs;
     ws = null;
     sessions = new Map();
+    pathRequestsInFlight = 0;
     /**
      * 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
@@ -252,6 +254,22 @@ export class EnrollmentRunner {
                 }
                 return;
             }
+            case 'path_list':
+            case 'path_read':
+                if (this.pathRequestsInFlight >= MAX_PATH_REQUESTS_IN_FLIGHT) {
+                    ws.send(encodeFrame({
+                        type: 'error',
+                        requestId: frame.requestId,
+                        code: 'TOO_MANY_PATH_REQUESTS',
+                        message: `${MAX_PATH_REQUESTS_IN_FLIGHT} path requests are already being answered`
+                    }));
+                    return;
+                }
+                this.pathRequestsInFlight += 1;
+                void this.answerPath(ws, frame).finally(() => {
+                    this.pathRequestsInFlight -= 1;
+                });
+                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
@@ -265,6 +283,39 @@ export class EnrollmentRunner {
                 ws.close(4002, 'protocol error');
         }
     }
+    /**
+     * Answer a read-only path request on the socket it arrived on: a listing, a
+     * file's bytes, or an `error` carrying the request id and why. A refusal
+     * is the requester's to act on; any other failure is also logged here.
+     */
+    async answerPath(ws, frame) {
+        const { requestId } = frame;
+        let reply;
+        try {
+            reply =
+                frame.type === 'path_list'
+                    ? {
+                        type: 'path_listing',
+                        requestId,
+                        entries: await listPath(this.policy, frame.root, frame.path)
+                    }
+                    : { type: 'path_content', requestId, ...(await readPath(this.policy, frame.root, frame.path)) };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (!(err instanceof PathAccessError)) {
+                this.logger.error(`machine-runner: ${frame.type} '${frame.path}' failed: ${message}`);
+            }
+            reply = {
+                type: 'error',
+                requestId,
+                message,
+                code: err instanceof PathAccessError ? err.code : 'PATH_UNREADABLE'
+            };
+        }
+        if (ws.readyState === WebSocket.OPEN)
+            ws.send(encodeFrame(reply));
+    }
     /** The session a frame addresses, or an `error` frame back and undefined. */
     require(ws, sessionId) {
         const session = this.sessions.get(sessionId);

package/files.d.ts

@@ -0,0 +1,29 @@
+import { PathEntry, PathErrorCode } from '@constructive-db/machine-protocol';
+import { RunnerPolicy } from './policy';
+/** A path request refused for a reason the requester can act on. */
+export declare class PathAccessError extends Error {
+    readonly code: PathErrorCode;
+    constructor(code: PathErrorCode, message: string);
+}
+/**
+ * The real path `requested` names under `root`. Refuses an absolute or
+ * traversing path outright, a root outside the policy cwd, and — after
+ * resolving every symlink — a target that is not the root or inside it.
+ */
+export declare function resolveUnder(policy: RunnerPolicy, root: string | undefined, requested: string): Promise<string>;
+/**
+ * The entries of a directory under `root`, sorted by name. A directory with
+ * more than {@link MAX_LIST_ENTRIES} entries is refused, not truncated, and is
+ * not read past the limit.
+ */
+export declare function listPath(policy: RunnerPolicy, root: string | undefined, requested: string): Promise<PathEntry[]>;
+/**
+ * A file's bytes, base64. A file over {@link MAX_READ_BYTES} is refused, not
+ * truncated — including one that grew past the limit after it was measured.
+ * The final component is opened `O_NOFOLLOW`, so a symlink swapped in after
+ * {@link resolveUnder} looked is refused rather than followed.
+ */
+export declare function readPath(policy: RunnerPolicy, root: string | undefined, requested: string): Promise<{
+    data: string;
+    size: number;
+}>;

package/files.js

@@ -0,0 +1,189 @@
+"use strict";
+// Read-only access to paths under the policy cwd. The relay names a root (the
+// same kind of value an `open` frame's `cwd` is: relative to, and confined to,
+// the policy cwd) and a path relative to that root; the runner answers with a
+// listing or a file's bytes. Nothing here knows what the root is for.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PathAccessError = void 0;
+exports.resolveUnder = resolveUnder;
+exports.listPath = listPath;
+exports.readPath = readPath;
+const machine_protocol_1 = require("@constructive-db/machine-protocol");
+const fs_1 = require("fs");
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+const policy_1 = require("./policy");
+/** A path request refused for a reason the requester can act on. */
+class PathAccessError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'PathAccessError';
+    }
+}
+exports.PathAccessError = PathAccessError;
+/** An errno failure as a refusal; anything else is a bug and propagates. */
+function fsFailure(err, requested) {
+    const errno = err?.code;
+    if (typeof errno !== 'string')
+        throw err;
+    if (errno === 'ENOENT' || errno === 'ENOTDIR') {
+        return new PathAccessError('PATH_NOT_FOUND', `'${requested}' does not exist`);
+    }
+    return new PathAccessError('PATH_UNREADABLE', `'${requested}' could not be read: ${err.message}`);
+}
+/**
+ * The real path `requested` names under `root`. Refuses an absolute or
+ * traversing path outright, a root outside the policy cwd, and — after
+ * resolving every symlink — a target that is not the root or inside it.
+ */
+async function resolveUnder(policy, root, requested) {
+    const problem = (0, machine_protocol_1.relativePathProblem)(requested);
+    if (problem)
+        throw new PathAccessError('PATH_INVALID', `path '${requested}' ${problem}`);
+    let base;
+    try {
+        base = (0, policy_1.resolveCwd)(policy, root);
+    }
+    catch (err) {
+        if (!(err instanceof policy_1.PolicyViolationError))
+            throw err;
+        throw new PathAccessError('PATH_OUTSIDE_ROOT', err.message);
+    }
+    let realBase;
+    try {
+        realBase = await promises_1.default.realpath(base);
+    }
+    catch (err) {
+        throw fsFailure(err, root ?? '.');
+    }
+    let real;
+    try {
+        real = await promises_1.default.realpath(path_1.default.join(base, requested));
+    }
+    catch (err) {
+        throw fsFailure(err, requested);
+    }
+    if (real !== realBase && !real.startsWith(realBase + path_1.default.sep)) {
+        throw new PathAccessError('PATH_OUTSIDE_ROOT', `'${requested}' resolves outside its root`);
+    }
+    return real;
+}
+/**
+ * Refuse unless `requested` still resolves under the root to the same file as
+ * `seen` (what was opened or listed). A path component swapped for a symlink
+ * after {@link resolveUnder} looked would otherwise be followed out of the root.
+ */
+async function assertStillUnder(policy, root, requested, seen) {
+    const now = await promises_1.default.stat(await resolveUnder(policy, root, requested)).catch(err => {
+        if (err instanceof PathAccessError)
+            throw err;
+        throw fsFailure(err, requested);
+    });
+    if (now.dev !== seen.dev || now.ino !== seen.ino) {
+        throw new PathAccessError('PATH_OUTSIDE_ROOT', `'${requested}' changed while being read`);
+    }
+}
+function entryKind(entry) {
+    if (entry.isSymbolicLink())
+        return 'symlink';
+    if (entry.isFile())
+        return 'file';
+    if (entry.isDirectory())
+        return 'directory';
+    return 'other';
+}
+/**
+ * The entries of a directory under `root`, sorted by name. A directory with
+ * more than {@link MAX_LIST_ENTRIES} entries is refused, not truncated, and is
+ * not read past the limit.
+ */
+async function listPath(policy, root, requested) {
+    const target = await resolveUnder(policy, root, requested);
+    let dir;
+    let stat;
+    try {
+        stat = await promises_1.default.stat(target);
+        if (!stat.isDirectory()) {
+            throw new PathAccessError('NOT_A_DIRECTORY', `'${requested}' is not a directory`);
+        }
+        dir = await promises_1.default.opendir(target);
+    }
+    catch (err) {
+        if (err instanceof PathAccessError)
+            throw err;
+        throw fsFailure(err, requested);
+    }
+    const entries = [];
+    try {
+        for await (const dirent of dir) {
+            if (entries.length === machine_protocol_1.MAX_LIST_ENTRIES) {
+                throw new PathAccessError('DIRECTORY_TOO_LARGE', `'${requested}' has more than ${machine_protocol_1.MAX_LIST_ENTRIES} entries`);
+            }
+            const kind = entryKind(dirent);
+            const entry = { name: dirent.name, kind };
+            if (kind === 'file')
+                entry.size = (await promises_1.default.lstat(path_1.default.join(target, dirent.name))).size;
+            entries.push(entry);
+        }
+    }
+    catch (err) {
+        // Throwing out of `for await` closes the directory handle.
+        if (err instanceof PathAccessError)
+            throw err;
+        throw fsFailure(err, requested);
+    }
+    await assertStillUnder(policy, root, requested, stat);
+    return entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+/**
+ * A file's bytes, base64. A file over {@link MAX_READ_BYTES} is refused, not
+ * truncated — including one that grew past the limit after it was measured.
+ * The final component is opened `O_NOFOLLOW`, so a symlink swapped in after
+ * {@link resolveUnder} looked is refused rather than followed.
+ */
+async function readPath(policy, root, requested) {
+    const target = await resolveUnder(policy, root, requested);
+    let handle;
+    try {
+        const stat = await promises_1.default.stat(target);
+        if (!stat.isFile())
+            throw new PathAccessError('NOT_A_FILE', `'${requested}' is not a file`);
+        if (stat.size > machine_protocol_1.MAX_READ_BYTES) {
+            throw new PathAccessError('FILE_TOO_LARGE', `'${requested}' is ${stat.size} bytes; the limit is ${machine_protocol_1.MAX_READ_BYTES}`);
+        }
+        handle = await promises_1.default.open(target, fs_1.constants.O_RDONLY | fs_1.constants.O_NOFOLLOW);
+    }
+    catch (err) {
+        if (err instanceof PathAccessError)
+            throw err;
+        throw fsFailure(err, requested);
+    }
+    try {
+        await assertStillUnder(policy, root, requested, await handle.stat());
+        const buffer = Buffer.alloc(machine_protocol_1.MAX_READ_BYTES + 1);
+        let size = 0;
+        for (;;) {
+            const { bytesRead } = await handle.read(buffer, size, buffer.length - size, size);
+            if (bytesRead === 0)
+                break;
+            size += bytesRead;
+            if (size > machine_protocol_1.MAX_READ_BYTES) {
+                throw new PathAccessError('FILE_TOO_LARGE', `'${requested}' grew past the ${machine_protocol_1.MAX_READ_BYTES}-byte limit while being read`);
+            }
+        }
+        return { data: buffer.subarray(0, size).toString('base64'), size };
+    }
+    catch (err) {
+        if (err instanceof PathAccessError)
+            throw err;
+        throw fsFailure(err, requested);
+    }
+    finally {
+        await handle.close();
+    }
+}

package/index.d.ts

@@ -2,6 +2,7 @@ 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 { listPath, PathAccessError, readPath, resolveUnder } from './files';
 export type { RunnerPolicy, SpawnSpec } from './policy';
 export { DEFAULT_ENV_ALLOW, PolicyViolationError, resolveCwd, resolveSpawn } from './policy';
 export type { ProcessExit, SessionProcess } from './process';

package/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MachineRunner = exports.EnrollmentRunner = exports.ptyProcess = exports.pipeProcess = exports.resolveSpawn = exports.resolveCwd = 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;
+exports.MachineRunner = exports.EnrollmentRunner = exports.ptyProcess = exports.pipeProcess = exports.resolveSpawn = exports.resolveCwd = exports.PolicyViolationError = exports.DEFAULT_ENV_ALLOW = exports.resolveUnder = exports.readPath = exports.PathAccessError = exports.listPath = 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; } });
@@ -12,6 +12,11 @@ Object.defineProperty(exports, "writeEnrollment", { enumerable: true, get: funct
 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 files_1 = require("./files");
+Object.defineProperty(exports, "listPath", { enumerable: true, get: function () { return files_1.listPath; } });
+Object.defineProperty(exports, "PathAccessError", { enumerable: true, get: function () { return files_1.PathAccessError; } });
+Object.defineProperty(exports, "readPath", { enumerable: true, get: function () { return files_1.readPath; } });
+Object.defineProperty(exports, "resolveUnder", { enumerable: true, get: function () { return files_1.resolveUnder; } });
 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; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructive-db/machine-runner",
-  "version": "0.2.2",
+  "version": "0.3.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",
@@ -39,7 +39,7 @@
     "test": "jest"
   },
   "dependencies": {
-    "@constructive-db/machine-protocol": "0.2.2",
+    "@constructive-db/machine-protocol": "0.3.0",
     "@pgpmjs/logger": "^2.26.0",
     "node-pty": "1.1.0",
     "ws": "^8.21.3"
@@ -47,5 +47,5 @@
   "devDependencies": {
     "@types/ws": "^8.5.13"
   },
-  "gitHead": "81eed19332cc231de0fde02bc6e87002357f9536"
+  "gitHead": "bdcd72c542def42905ba3729304bf47e55085137"
 }

package/runner.d.ts

@@ -18,6 +18,7 @@ export declare class EnrollmentRunner {
     private readonly reconnectMaxMs;
     private ws;
     private readonly sessions;
+    private pathRequestsInFlight;
     /**
      * 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
@@ -47,6 +48,12 @@ export declare class EnrollmentRunner {
     private send;
     private connect;
     private handleFrame;
+    /**
+     * Answer a read-only path request on the socket it arrived on: a listing, a
+     * file's bytes, or an `error` carrying the request id and why. A refusal
+     * is the requester's to act on; any other failure is also logged here.
+     */
+    private answerPath;
     /** The session a frame addresses, or an `error` frame back and undefined. */
     private require;
     /**

package/runner.js

@@ -24,6 +24,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MachineRunner = exports.EnrollmentRunner = void 0;
 const machine_protocol_1 = require("@constructive-db/machine-protocol");
 const ws_1 = require("ws");
+const files_1 = require("./files");
 const policy_1 = require("./policy");
 const process_1 = require("./process");
 /** Stop presenting a credential this long before it expires. */
@@ -54,6 +55,7 @@ class EnrollmentRunner {
     reconnectMaxMs;
     ws = null;
     sessions = new Map();
+    pathRequestsInFlight = 0;
     /**
      * 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
@@ -255,6 +257,22 @@ class EnrollmentRunner {
                 }
                 return;
             }
+            case 'path_list':
+            case 'path_read':
+                if (this.pathRequestsInFlight >= machine_protocol_1.MAX_PATH_REQUESTS_IN_FLIGHT) {
+                    ws.send((0, machine_protocol_1.encodeFrame)({
+                        type: 'error',
+                        requestId: frame.requestId,
+                        code: 'TOO_MANY_PATH_REQUESTS',
+                        message: `${machine_protocol_1.MAX_PATH_REQUESTS_IN_FLIGHT} path requests are already being answered`
+                    }));
+                    return;
+                }
+                this.pathRequestsInFlight += 1;
+                void this.answerPath(ws, frame).finally(() => {
+                    this.pathRequestsInFlight -= 1;
+                });
+                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
@@ -268,6 +286,39 @@ class EnrollmentRunner {
                 ws.close(4002, 'protocol error');
         }
     }
+    /**
+     * Answer a read-only path request on the socket it arrived on: a listing, a
+     * file's bytes, or an `error` carrying the request id and why. A refusal
+     * is the requester's to act on; any other failure is also logged here.
+     */
+    async answerPath(ws, frame) {
+        const { requestId } = frame;
+        let reply;
+        try {
+            reply =
+                frame.type === 'path_list'
+                    ? {
+                        type: 'path_listing',
+                        requestId,
+                        entries: await (0, files_1.listPath)(this.policy, frame.root, frame.path)
+                    }
+                    : { type: 'path_content', requestId, ...(await (0, files_1.readPath)(this.policy, frame.root, frame.path)) };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (!(err instanceof files_1.PathAccessError)) {
+                this.logger.error(`machine-runner: ${frame.type} '${frame.path}' failed: ${message}`);
+            }
+            reply = {
+                type: 'error',
+                requestId,
+                message,
+                code: err instanceof files_1.PathAccessError ? err.code : 'PATH_UNREADABLE'
+            };
+        }
+        if (ws.readyState === ws_1.WebSocket.OPEN)
+            ws.send((0, machine_protocol_1.encodeFrame)(reply));
+    }
     /** The session a frame addresses, or an `error` frame back and undefined. */
     require(ws, sessionId) {
         const session = this.sessions.get(sessionId);