matchlock-sdk 0.1.22

package/dist/client.js

@@ -0,0 +1,966 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Client = void 0;
+exports.defaultConfig = defaultConfig;
+const node_events_1 = require("node:events");
+const node_child_process_1 = require("node:child_process");
+const node_net_1 = require("node:net");
+const node_util_1 = require("node:util");
+const minimatch_1 = require("minimatch");
+const builder_1 = require("./builder");
+const errors_1 = require("./errors");
+const types_1 = require("./types");
+const DEFAULT_CPUS = 1;
+const DEFAULT_MEMORY_MB = 512;
+const DEFAULT_DISK_SIZE_MB = 5120;
+const DEFAULT_TIMEOUT_SECONDS = 300;
+const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
+function defaultConfig(config = {}) {
+    return {
+        binaryPath: config.binaryPath ?? process.env.MATCHLOCK_BIN ?? "matchlock",
+        useSudo: config.useSudo ?? false,
+    };
+}
+function toError(value) {
+    if (value instanceof Error) {
+        return value;
+    }
+    return new Error(String(value));
+}
+function toBuffer(content) {
+    if (typeof content === "string") {
+        return Buffer.from(content, "utf8");
+    }
+    if (Buffer.isBuffer(content)) {
+        return content;
+    }
+    if (content instanceof Uint8Array) {
+        return Buffer.from(content);
+    }
+    if (content instanceof ArrayBuffer) {
+        return Buffer.from(content);
+    }
+    throw new errors_1.MatchlockError("unsupported content type");
+}
+function lowerSet(values) {
+    return new Set((values ?? []).map((value) => value.toLowerCase()));
+}
+function asObject(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return {};
+    }
+    return value;
+}
+function asNumber(value, fallback = 0) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    return fallback;
+}
+function asString(value, fallback = "") {
+    return typeof value === "string" ? value : fallback;
+}
+function getUID() {
+    return typeof process.geteuid === "function" ? process.geteuid() : 0;
+}
+function getGID() {
+    return typeof process.getegid === "function" ? process.getegid() : 0;
+}
+class Client {
+    config;
+    process;
+    requestID = 0;
+    pending = new Map();
+    writeLock = Promise.resolve();
+    readBuffer = "";
+    vmIDValue = "";
+    lastVMID = "";
+    closed = false;
+    closing = false;
+    vfsHooks = [];
+    vfsMutateHooks = [];
+    vfsActionHooks = [];
+    vfsHookActive = false;
+    constructor(config = {}) {
+        this.config = defaultConfig(config);
+    }
+    get vmId() {
+        return this.vmIDValue;
+    }
+    async start() {
+        if (this.closed) {
+            throw new errors_1.MatchlockError("client is closed");
+        }
+        if (this.process && this.process.exitCode === null && !this.process.killed) {
+            return;
+        }
+        const command = this.config.useSudo ? "sudo" : this.config.binaryPath;
+        const args = this.config.useSudo
+            ? [this.config.binaryPath, "rpc"]
+            : ["rpc"];
+        const child = (0, node_child_process_1.spawn)(command, args, {
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        child.stderr.on("data", () => {
+            // Drain stderr so the child cannot block on full pipes.
+        });
+        child.stdout.on("data", (chunk) => {
+            this.readBuffer += chunk.toString("utf8");
+            this.processReadBuffer();
+        });
+        child.on("close", () => {
+            this.handleProcessClosed();
+        });
+        child.on("error", (error) => {
+            this.handleProcessClosed(error);
+        });
+        this.process = child;
+    }
+    async close(timeoutSeconds = 0) {
+        if (this.closed || this.closing) {
+            return;
+        }
+        this.closing = true;
+        this.lastVMID = this.vmIDValue;
+        this.setLocalVFSHooks([], [], []);
+        try {
+            if (!this.isRunning()) {
+                return;
+            }
+            const effectiveTimeout = timeoutSeconds > 0 ? timeoutSeconds : 2;
+            try {
+                await this.sendRequest("close", { timeout_seconds: effectiveTimeout }, {
+                    timeoutMs: (effectiveTimeout + 5) * 1000,
+                });
+            }
+            catch {
+                // Best effort shutdown.
+            }
+            if (this.process?.stdin.writable) {
+                this.process.stdin.end();
+            }
+            await this.waitForProcessExit(effectiveTimeout * 1000);
+        }
+        finally {
+            this.closed = true;
+            this.closing = false;
+        }
+    }
+    async remove() {
+        const vmID = this.vmIDValue || this.lastVMID;
+        if (!vmID) {
+            return;
+        }
+        try {
+            await execFileAsync(this.config.binaryPath, ["rm", vmID]);
+        }
+        catch (error) {
+            const err = toError(error);
+            throw new errors_1.MatchlockError(`matchlock rm ${vmID}: ${err.message}`);
+        }
+    }
+    async launch(sandbox) {
+        return this.create(sandbox.options());
+    }
+    async create(opts = {}) {
+        const options = (0, builder_1.cloneCreateOptions)(opts);
+        if (!options.image) {
+            throw new errors_1.MatchlockError("image is required (e.g., alpine:latest)");
+        }
+        if ((options.networkMtu ?? 0) < 0) {
+            throw new errors_1.MatchlockError("network mtu must be > 0");
+        }
+        for (const mapping of options.addHosts ?? []) {
+            this.validateAddHost(mapping);
+        }
+        const [wireVFS, localHooks, localMutateHooks, localActionHooks] = this.compileVFSHooks(options.vfsInterception);
+        const resources = {
+            cpus: options.cpus || DEFAULT_CPUS,
+            memory_mb: options.memoryMb || DEFAULT_MEMORY_MB,
+            disk_size_mb: options.diskSizeMb || DEFAULT_DISK_SIZE_MB,
+            timeout_seconds: options.timeoutSeconds || DEFAULT_TIMEOUT_SECONDS,
+        };
+        const params = {
+            image: options.image,
+            resources,
+        };
+        if (options.privileged) {
+            params.privileged = true;
+        }
+        const network = this.buildCreateNetworkParams(options);
+        if (network) {
+            params.network = network;
+        }
+        if ((options.mounts && Object.keys(options.mounts).length > 0) ||
+            options.workspace ||
+            wireVFS) {
+            const vfs = {};
+            if (options.mounts && Object.keys(options.mounts).length > 0) {
+                const mounts = {};
+                for (const [guestPath, config] of Object.entries(options.mounts)) {
+                    const mount = {
+                        type: config.type ?? "memory",
+                    };
+                    if (config.hostPath) {
+                        mount.host_path = config.hostPath;
+                    }
+                    if (config.readonly) {
+                        mount.readonly = true;
+                    }
+                    mounts[guestPath] = mount;
+                }
+                vfs.mounts = mounts;
+            }
+            if (options.workspace) {
+                vfs.workspace = options.workspace;
+            }
+            if (wireVFS) {
+                vfs.interception = wireVFS;
+            }
+            params.vfs = vfs;
+        }
+        if (options.env && Object.keys(options.env).length > 0) {
+            params.env = options.env;
+        }
+        if (options.imageConfig) {
+            const imageConfig = {};
+            if (options.imageConfig.user) {
+                imageConfig.user = options.imageConfig.user;
+            }
+            if (options.imageConfig.workingDir) {
+                imageConfig.working_dir = options.imageConfig.workingDir;
+            }
+            if (options.imageConfig.entrypoint) {
+                imageConfig.entrypoint = [...options.imageConfig.entrypoint];
+            }
+            if (options.imageConfig.cmd) {
+                imageConfig.cmd = [...options.imageConfig.cmd];
+            }
+            if (options.imageConfig.env) {
+                imageConfig.env = { ...options.imageConfig.env };
+            }
+            params.image_config = imageConfig;
+        }
+        const result = asObject(await this.sendRequest("create", params));
+        const id = asString(result.id);
+        if (!id) {
+            throw new errors_1.MatchlockError("invalid create response: missing id");
+        }
+        this.vmIDValue = id;
+        this.setLocalVFSHooks(localHooks, localMutateHooks, localActionHooks);
+        if ((options.portForwards ?? []).length > 0) {
+            await this.portForwardMappings(options.portForwardAddresses, options.portForwards ?? []);
+        }
+        return this.vmIDValue;
+    }
+    resolveCreateBlockPrivateIPs(opts) {
+        if (opts.blockPrivateIPsSet) {
+            return { value: !!opts.blockPrivateIPs, hasOverride: true };
+        }
+        if (opts.blockPrivateIPs) {
+            return { value: true, hasOverride: true };
+        }
+        return { value: false, hasOverride: false };
+    }
+    buildCreateNetworkParams(opts) {
+        const hasAllowedHosts = (opts.allowedHosts?.length ?? 0) > 0;
+        const hasAddHosts = (opts.addHosts?.length ?? 0) > 0;
+        const hasSecrets = (opts.secrets?.length ?? 0) > 0;
+        const hasDNSServers = (opts.dnsServers?.length ?? 0) > 0;
+        const hasHostname = (opts.hostname?.length ?? 0) > 0;
+        const hasMTU = (opts.networkMtu ?? 0) > 0;
+        const blockPrivate = this.resolveCreateBlockPrivateIPs(opts);
+        const includeNetwork = hasAllowedHosts ||
+            hasAddHosts ||
+            hasSecrets ||
+            hasDNSServers ||
+            hasHostname ||
+            hasMTU ||
+            blockPrivate.hasOverride;
+        if (!includeNetwork) {
+            return undefined;
+        }
+        const network = {
+            allowed_hosts: opts.allowedHosts ?? [],
+            block_private_ips: blockPrivate.hasOverride ? blockPrivate.value : true,
+        };
+        if (hasAddHosts) {
+            network.add_hosts = (opts.addHosts ?? []).map((mapping) => ({
+                host: mapping.host,
+                ip: mapping.ip,
+            }));
+        }
+        if (hasSecrets) {
+            const secrets = {};
+            for (const secret of opts.secrets ?? []) {
+                secrets[secret.name] = {
+                    value: secret.value,
+                    hosts: secret.hosts ?? [],
+                };
+            }
+            network.secrets = secrets;
+        }
+        if (hasDNSServers) {
+            network.dns_servers = opts.dnsServers ?? [];
+        }
+        if (hasHostname) {
+            network.hostname = opts.hostname ?? "";
+        }
+        if (hasMTU) {
+            network.mtu = opts.networkMtu ?? 0;
+        }
+        return network;
+    }
+    async exec(command, options = {}) {
+        return this.execWithDir(command, options.workingDir ?? "", options);
+    }
+    async execWithDir(command, workingDir = "", options = {}) {
+        const params = { command };
+        if (workingDir) {
+            params.working_dir = workingDir;
+        }
+        const result = asObject(await this.sendRequest("exec", params, options));
+        return {
+            exitCode: asNumber(result.exit_code),
+            stdout: Buffer.from(asString(result.stdout), "base64").toString("utf8"),
+            stderr: Buffer.from(asString(result.stderr), "base64").toString("utf8"),
+            durationMs: asNumber(result.duration_ms),
+        };
+    }
+    async execStream(command, options = {}) {
+        return this.execStreamWithDir(command, options.workingDir ?? "", options.stdout, options.stderr, options);
+    }
+    async execStreamWithDir(command, workingDir = "", stdout, stderr, options = {}) {
+        const params = { command };
+        if (workingDir) {
+            params.working_dir = workingDir;
+        }
+        const onNotification = (method, payload) => {
+            const data = asString(payload.data);
+            if (!data) {
+                return;
+            }
+            let decoded;
+            try {
+                decoded = Buffer.from(data, "base64");
+            }
+            catch {
+                return;
+            }
+            if (method === "exec_stream.stdout") {
+                this.writeStreamChunk(stdout, decoded);
+            }
+            else if (method === "exec_stream.stderr") {
+                this.writeStreamChunk(stderr, decoded);
+            }
+        };
+        const result = asObject(await this.sendRequest("exec_stream", params, options, onNotification));
+        return {
+            exitCode: asNumber(result.exit_code),
+            durationMs: asNumber(result.duration_ms),
+        };
+    }
+    async writeFile(path, content, options = {}) {
+        await this.writeFileMode(path, content, 0o644, options);
+    }
+    async writeFileMode(path, content, mode, options = {}) {
+        const original = toBuffer(content);
+        await this.applyLocalActionHooks(types_1.VFS_HOOK_OP_WRITE, path, original.length, mode);
+        const mutated = await this.applyLocalWriteMutations(path, original, mode);
+        await this.sendRequest("write_file", {
+            path,
+            content: mutated.toString("base64"),
+            mode,
+        }, options);
+    }
+    async readFile(path, options = {}) {
+        await this.applyLocalActionHooks(types_1.VFS_HOOK_OP_READ, path, 0, 0);
+        const result = asObject(await this.sendRequest("read_file", { path }, options));
+        return Buffer.from(asString(result.content), "base64");
+    }
+    async listFiles(path, options = {}) {
+        await this.applyLocalActionHooks(types_1.VFS_HOOK_OP_READDIR, path, 0, 0);
+        const result = asObject(await this.sendRequest("list_files", { path }, options));
+        const files = Array.isArray(result.files) ? result.files : [];
+        return files.map((entry) => {
+            const file = asObject(entry);
+            return {
+                name: asString(file.name),
+                size: asNumber(file.size),
+                mode: asNumber(file.mode),
+                isDir: Boolean(file.is_dir),
+            };
+        });
+    }
+    async portForward(...specs) {
+        return this.portForwardWithAddresses(undefined, ...specs);
+    }
+    async portForwardWithAddresses(addresses, ...specs) {
+        const forwards = this.parsePortForwards(specs);
+        return this.portForwardMappings(addresses, forwards);
+    }
+    async portForwardMappings(addresses, forwards) {
+        if (forwards.length === 0) {
+            return [];
+        }
+        const wireForwards = forwards.map((forward) => ({
+            local_port: forward.localPort,
+            remote_port: forward.remotePort,
+        }));
+        const result = asObject(await this.sendRequest("port_forward", {
+            forwards: wireForwards,
+            addresses: addresses && addresses.length > 0 ? [...addresses] : ["127.0.0.1"],
+        }));
+        const bindings = Array.isArray(result.bindings) ? result.bindings : [];
+        return bindings.map((entry) => {
+            const binding = asObject(entry);
+            return {
+                address: asString(binding.address),
+                localPort: asNumber(binding.local_port),
+                remotePort: asNumber(binding.remote_port),
+            };
+        });
+    }
+    parsePortForwards(specs) {
+        return specs.map((spec) => this.parsePortForward(spec));
+    }
+    parsePortForward(spec) {
+        const trimmed = spec.trim();
+        if (!trimmed) {
+            throw new errors_1.MatchlockError('invalid port-forward spec: empty spec');
+        }
+        const parts = trimmed.split(":");
+        if (parts.length === 1) {
+            const remotePort = this.parsePort(parts[0], "remote");
+            return { localPort: remotePort, remotePort };
+        }
+        if (parts.length === 2) {
+            const localPort = this.parsePort(parts[0], "local");
+            const remotePort = this.parsePort(parts[1], "remote");
+            return { localPort, remotePort };
+        }
+        throw new errors_1.MatchlockError(`invalid port-forward spec: ${JSON.stringify(trimmed)} (expected [LOCAL_PORT:]REMOTE_PORT)`);
+    }
+    parsePort(raw, role) {
+        const value = raw.trim();
+        if (!value) {
+            throw new errors_1.MatchlockError(`invalid port-forward spec: empty ${role} port`);
+        }
+        const port = Number.parseInt(value, 10);
+        if (!Number.isFinite(port)) {
+            throw new errors_1.MatchlockError(`invalid port value ${JSON.stringify(value)}`);
+        }
+        if (port < 1 || port > 65535) {
+            throw new errors_1.MatchlockError(`invalid port value ${port}: must be in range 1-65535`);
+        }
+        return port;
+    }
+    async sendRequest(method, params, options = {}, onNotification) {
+        if (this.closed) {
+            throw new errors_1.MatchlockError("client is closed");
+        }
+        await this.start();
+        if (!this.isRunning()) {
+            throw new errors_1.MatchlockError("Matchlock process not running");
+        }
+        const id = ++this.requestID;
+        const request = {
+            jsonrpc: "2.0",
+            method,
+            id,
+        };
+        if (params && Object.keys(params).length > 0) {
+            request.params = params;
+        }
+        let resolvePending = () => { };
+        let rejectPending = () => { };
+        const resultPromise = new Promise((resolve, reject) => {
+            resolvePending = resolve;
+            rejectPending = reject;
+        });
+        this.pending.set(id, {
+            resolve: resolvePending,
+            reject: rejectPending,
+            onNotification,
+        });
+        let timeoutHandle;
+        const onAbort = () => {
+            this.sendCancelRequest(id);
+            const reason = options.signal?.reason;
+            if (reason instanceof Error) {
+                rejectPending(reason);
+            }
+            else {
+                rejectPending(new errors_1.MatchlockError(`request ${method} was aborted`));
+            }
+        };
+        try {
+            if (options.signal?.aborted) {
+                onAbort();
+            }
+            else if (options.signal) {
+                options.signal.addEventListener("abort", onAbort, { once: true });
+            }
+            if ((options.timeoutMs ?? 0) > 0) {
+                timeoutHandle = setTimeout(() => {
+                    this.sendCancelRequest(id);
+                    rejectPending(new errors_1.MatchlockError(`request ${method} (id=${id}) timed out after ${options.timeoutMs}ms`));
+                }, options.timeoutMs);
+            }
+            await this.enqueueWrite(`${JSON.stringify(request)}\n`);
+            return await resultPromise;
+        }
+        finally {
+            this.pending.delete(id);
+            if (timeoutHandle) {
+                clearTimeout(timeoutHandle);
+            }
+            if (options.signal) {
+                options.signal.removeEventListener("abort", onAbort);
+            }
+        }
+    }
+    sendCancelRequest(targetID) {
+        const request = {
+            jsonrpc: "2.0",
+            method: "cancel",
+            params: { id: targetID },
+            id: ++this.requestID,
+        };
+        void this.enqueueWrite(`${JSON.stringify(request)}\n`).catch(() => {
+            // Ignore cancellation write errors.
+        });
+    }
+    async enqueueWrite(line) {
+        this.writeLock = this.writeLock
+            .catch(() => {
+            // Keep queue alive.
+        })
+            .then(async () => {
+            if (!this.process || !this.process.stdin.writable) {
+                throw new errors_1.MatchlockError("Matchlock process not running");
+            }
+            await new Promise((resolve, reject) => {
+                this.process?.stdin.write(line, (error) => {
+                    if (error) {
+                        reject(error);
+                        return;
+                    }
+                    resolve();
+                });
+            });
+        });
+        return this.writeLock;
+    }
+    processReadBuffer() {
+        for (;;) {
+            const newlineIndex = this.readBuffer.indexOf("\n");
+            if (newlineIndex === -1) {
+                break;
+            }
+            const line = this.readBuffer.slice(0, newlineIndex).trim();
+            this.readBuffer = this.readBuffer.slice(newlineIndex + 1);
+            if (!line) {
+                continue;
+            }
+            this.handleMessage(line);
+        }
+    }
+    handleMessage(line) {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (typeof parsed.id !== "number") {
+            this.handleNotification(parsed);
+            return;
+        }
+        const pending = this.pending.get(parsed.id);
+        if (!pending) {
+            return;
+        }
+        if (parsed.error) {
+            pending.reject(new errors_1.RPCError(parsed.error.code, parsed.error.message));
+            return;
+        }
+        pending.resolve(parsed.result ?? null);
+    }
+    handleNotification(msg) {
+        const method = msg.method;
+        const params = msg.params ?? {};
+        if (method === "exec_stream.stdout" || method === "exec_stream.stderr") {
+            const reqID = asNumber(params.id, -1);
+            if (reqID < 0) {
+                return;
+            }
+            const pending = this.pending.get(reqID);
+            if (pending?.onNotification) {
+                pending.onNotification(method, params);
+            }
+            return;
+        }
+        if (method === "event") {
+            this.handleVFSFileEventNotification(params);
+        }
+    }
+    handleVFSFileEventNotification(params) {
+        const file = asObject(params.file);
+        if (Object.keys(file).length === 0) {
+            return;
+        }
+        const op = asString(file.op).toLowerCase();
+        if (!op) {
+            return;
+        }
+        const event = {
+            op,
+            path: asString(file.path),
+            size: asNumber(file.size),
+            mode: asNumber(file.mode),
+            uid: asNumber(file.uid),
+            gid: asNumber(file.gid),
+        };
+        this.handleVFSFileEvent(event);
+    }
+    handleVFSFileEvent(event) {
+        const hooks = [...this.vfsHooks];
+        if (hooks.length === 0) {
+            return;
+        }
+        const safeHooks = [];
+        for (const hook of hooks) {
+            if (!this.matchesVFSHook(hook.ops, hook.path, event.op, event.path)) {
+                continue;
+            }
+            if (hook.dangerous) {
+                void this.runSingleVFSHook(hook, event);
+                continue;
+            }
+            safeHooks.push(hook);
+        }
+        if (safeHooks.length === 0) {
+            return;
+        }
+        if (this.vfsHookActive) {
+            return;
+        }
+        void this.runVFSSafeHooksForEvent(safeHooks, event);
+    }
+    async runVFSSafeHooksForEvent(hooks, event) {
+        if (this.vfsHookActive) {
+            return;
+        }
+        this.vfsHookActive = true;
+        try {
+            for (const hook of hooks) {
+                await this.runSingleVFSHook(hook, event);
+            }
+        }
+        finally {
+            this.vfsHookActive = false;
+        }
+    }
+    async runSingleVFSHook(hook, event) {
+        try {
+            const run = hook.callback(this, event);
+            if (hook.timeoutMs > 0) {
+                await Promise.race([
+                    run,
+                    new Promise((resolve) => {
+                        setTimeout(resolve, hook.timeoutMs);
+                    }),
+                ]);
+            }
+            else {
+                await run;
+            }
+        }
+        catch {
+            // Hooks are intentionally best effort.
+        }
+    }
+    matchesVFSHook(ops, path, op, actualPath) {
+        if (ops.size > 0 && !ops.has(op.toLowerCase())) {
+            return false;
+        }
+        if (!path) {
+            return true;
+        }
+        try {
+            return (0, minimatch_1.minimatch)(actualPath, path, { dot: true });
+        }
+        catch {
+            return false;
+        }
+    }
+    async applyLocalWriteMutations(path, content, mode) {
+        const hooks = [...this.vfsMutateHooks];
+        if (hooks.length === 0) {
+            return content;
+        }
+        let current = content;
+        for (const hook of hooks) {
+            if (!this.matchesVFSHook(hook.ops, hook.path, types_1.VFS_HOOK_OP_WRITE, path)) {
+                continue;
+            }
+            const request = {
+                path,
+                size: current.length,
+                mode,
+                uid: getUID(),
+                gid: getGID(),
+            };
+            const mutated = await hook.callback(request);
+            if (mutated === null || mutated === undefined) {
+                continue;
+            }
+            if (typeof mutated === "string") {
+                current = Buffer.from(mutated, "utf8");
+                continue;
+            }
+            if (Buffer.isBuffer(mutated) ||
+                mutated instanceof Uint8Array ||
+                mutated instanceof ArrayBuffer) {
+                current = toBuffer(mutated);
+                continue;
+            }
+            throw new errors_1.MatchlockError(`invalid mutate_hook return type for ${JSON.stringify(hook.name)}: expected bytes|string|undefined`);
+        }
+        return current;
+    }
+    async applyLocalActionHooks(op, path, size, mode) {
+        const hooks = [...this.vfsActionHooks];
+        if (hooks.length === 0) {
+            return;
+        }
+        const request = {
+            op,
+            path,
+            size,
+            mode,
+            uid: getUID(),
+            gid: getGID(),
+        };
+        for (const hook of hooks) {
+            if (!this.matchesVFSHook(hook.ops, hook.path, op, path)) {
+                continue;
+            }
+            const decision = String(await hook.callback(request)).trim().toLowerCase();
+            if (decision === "" || decision === types_1.VFS_HOOK_ACTION_ALLOW) {
+                continue;
+            }
+            if (decision === types_1.VFS_HOOK_ACTION_BLOCK) {
+                throw new errors_1.MatchlockError(`vfs action hook blocked operation: op=${op} path=${path} hook=${JSON.stringify(hook.name)}`);
+            }
+            throw new errors_1.MatchlockError(`invalid action_hook return value for ${JSON.stringify(hook.name)}: expected ${JSON.stringify(types_1.VFS_HOOK_ACTION_ALLOW)}|${JSON.stringify(types_1.VFS_HOOK_ACTION_BLOCK)}, got ${JSON.stringify(decision)}`);
+        }
+    }
+    compileVFSHooks(cfg) {
+        if (!cfg) {
+            return [undefined, [], [], []];
+        }
+        const wire = {
+            emit_events: cfg.emitEvents,
+            rules: [],
+        };
+        const localHooks = [];
+        const localMutateHooks = [];
+        const localActionHooks = [];
+        for (const rule of cfg.rules ?? []) {
+            const callbackCount = Number(Boolean(rule.hook)) + Number(Boolean(rule.dangerousHook)) + Number(Boolean(rule.mutateHook)) + Number(Boolean(rule.actionHook));
+            if (callbackCount > 1) {
+                throw new errors_1.MatchlockError(`invalid vfs hook ${JSON.stringify(rule.name ?? "")}: cannot set more than one callback hook`);
+            }
+            if (!rule.hook &&
+                !rule.dangerousHook &&
+                !rule.mutateHook &&
+                !rule.actionHook) {
+                const action = String(rule.action ?? "allow").trim().toLowerCase();
+                if (action === "mutate_write") {
+                    throw new errors_1.MatchlockError(`invalid vfs hook ${JSON.stringify(rule.name ?? "")}: mutate_write requires mutate_hook callback`);
+                }
+                wire.rules?.push(this.ruleToWire(rule, action));
+                continue;
+            }
+            if (rule.hook) {
+                this.validateLocalAfterRule(rule, "callback hooks");
+                localHooks.push({
+                    name: rule.name ?? "",
+                    ops: lowerSet(rule.ops),
+                    path: rule.path ?? "",
+                    timeoutMs: rule.timeoutMs ?? 0,
+                    dangerous: false,
+                    callback: async (_client, event) => {
+                        await rule.hook?.(event);
+                    },
+                });
+                continue;
+            }
+            if (rule.dangerousHook) {
+                this.validateLocalAfterRule(rule, "dangerous_hook");
+                localHooks.push({
+                    name: rule.name ?? "",
+                    ops: lowerSet(rule.ops),
+                    path: rule.path ?? "",
+                    timeoutMs: rule.timeoutMs ?? 0,
+                    dangerous: true,
+                    callback: async (client, event) => {
+                        await rule.dangerousHook?.(client, event);
+                    },
+                });
+                continue;
+            }
+            if (rule.actionHook) {
+                const action = String(rule.action ?? "").trim().toLowerCase();
+                if (action && action !== types_1.VFS_HOOK_ACTION_ALLOW) {
+                    throw new errors_1.MatchlockError(`invalid vfs hook ${JSON.stringify(rule.name ?? "")}: action_hook cannot set action=${JSON.stringify(rule.action)}`);
+                }
+                if (rule.phase &&
+                    String(rule.phase).toLowerCase() !== types_1.VFS_HOOK_PHASE_BEFORE) {
+                    throw new errors_1.MatchlockError(`invalid vfs hook ${JSON.stringify(rule.name ?? "")}: action_hook must use phase=before`);
+                }
+                localActionHooks.push({
+                    name: rule.name ?? "",
+                    ops: lowerSet(rule.ops),
+                    path: rule.path ?? "",
+                    callback: async (request) => (await rule.actionHook?.(request)) ?? types_1.VFS_HOOK_ACTION_ALLOW,
+                });
+                continue;
+            }
+            const action = String(rule.action ?? "").trim().toLowerCase();
+            if (action && action !== types_1.VFS_HOOK_ACTION_ALLOW) {
+                throw new errors_1.MatchlockError(`invalid vfs hook ${JSON.stringify(rule.name ?? "")}: mutate_hook cannot set action=${JSON.stringify(rule.action)}`);
+            }
+            if (rule.phase && String(rule.phase).toLowerCase() !== types_1.VFS_HOOK_PHASE_BEFORE) {
+                throw new errors_1.MatchlockError(`invalid vfs hook ${JSON.stringify(rule.name ?? "")}: mutate_hook must use phase=before`);
+            }
+            localMutateHooks.push({
+                name: rule.name ?? "",
+                ops: lowerSet(rule.ops),
+                path: rule.path ?? "",
+                callback: async (request) => rule.mutateHook?.(request),
+            });
+        }
+        if (localHooks.length > 0) {
+            wire.emit_events = true;
+        }
+        if ((wire.rules?.length ?? 0) === 0) {
+            wire.rules = undefined;
+        }
+        if (!wire.emit_events && !wire.rules) {
+            return [undefined, localHooks, localMutateHooks, localActionHooks];
+        }
+        return [wire, localHooks, localMutateHooks, localActionHooks];
+    }
+    validateLocalAfterRule(rule, label) {
+        const action = String(rule.action ?? "").trim().toLowerCase();
+        if (action && action !== types_1.VFS_HOOK_ACTION_ALLOW) {
+            throw new errors_1.MatchlockError(`invalid vfs hook ${JSON.stringify(rule.name ?? "")}: ${label} cannot set action=${JSON.stringify(rule.action)}`);
+        }
+        if (String(rule.phase ?? "").toLowerCase() !== types_1.VFS_HOOK_PHASE_AFTER) {
+            throw new errors_1.MatchlockError(`invalid vfs hook ${JSON.stringify(rule.name ?? "")}: ${label} must use phase=after`);
+        }
+    }
+    ruleToWire(rule, normalizedAction) {
+        const wire = {
+            action: normalizedAction,
+        };
+        if (rule.name) {
+            wire.name = rule.name;
+        }
+        if (rule.phase) {
+            wire.phase = rule.phase;
+        }
+        if (rule.ops && rule.ops.length > 0) {
+            wire.ops = [...rule.ops];
+        }
+        if (rule.path) {
+            wire.path = rule.path;
+        }
+        if ((rule.timeoutMs ?? 0) > 0) {
+            wire.timeout_ms = rule.timeoutMs;
+        }
+        return wire;
+    }
+    setLocalVFSHooks(hooks, mutateHooks, actionHooks) {
+        this.vfsHooks = [...hooks];
+        this.vfsMutateHooks = [...mutateHooks];
+        this.vfsActionHooks = [...actionHooks];
+        this.vfsHookActive = false;
+    }
+    validateAddHost(mapping) {
+        if (!mapping.host || !mapping.host.trim()) {
+            throw new errors_1.MatchlockError("invalid add-host mapping: empty host");
+        }
+        if (/\s/.test(mapping.host)) {
+            throw new errors_1.MatchlockError(`invalid add-host mapping: host ${JSON.stringify(mapping.host)} contains whitespace`);
+        }
+        if (mapping.host.includes(":")) {
+            throw new errors_1.MatchlockError(`invalid add-host mapping: host ${JSON.stringify(mapping.host)} must not contain ':'`);
+        }
+        if (!mapping.ip || !mapping.ip.trim()) {
+            throw new errors_1.MatchlockError("invalid add-host mapping: empty ip");
+        }
+        if (!this.isValidIP(mapping.ip.trim())) {
+            throw new errors_1.MatchlockError(`invalid add-host mapping: invalid ip ${JSON.stringify(mapping.ip)}`);
+        }
+    }
+    isValidIP(ip) {
+        return (0, node_net_1.isIP)(ip) !== 0;
+    }
+    writeStreamChunk(writer, chunk) {
+        if (!writer) {
+            return;
+        }
+        if (typeof writer === "function") {
+            void writer(chunk);
+            return;
+        }
+        writer.write(chunk);
+    }
+    isRunning() {
+        return !!this.process && this.process.exitCode === null && !this.process.killed;
+    }
+    async waitForProcessExit(timeoutMs) {
+        const proc = this.process;
+        if (!proc) {
+            return;
+        }
+        if (proc.exitCode !== null) {
+            return;
+        }
+        let timer;
+        try {
+            await Promise.race([
+                (0, node_events_1.once)(proc, "exit").then(() => undefined),
+                new Promise((resolve) => {
+                    timer = setTimeout(resolve, timeoutMs);
+                }),
+            ]);
+        }
+        finally {
+            if (timer) {
+                clearTimeout(timer);
+            }
+        }
+        if (proc.exitCode === null && !proc.killed) {
+            proc.kill("SIGKILL");
+            await (0, node_events_1.once)(proc, "exit").catch(() => undefined);
+        }
+    }
+    handleProcessClosed(error) {
+        const pending = [...this.pending.values()];
+        this.pending.clear();
+        const message = error
+            ? `Matchlock process closed unexpectedly: ${error.message}`
+            : "Matchlock process closed unexpectedly";
+        for (const request of pending) {
+            request.reject(new errors_1.MatchlockError(message));
+        }
+        this.process = undefined;
+    }
+}
+exports.Client = Client;