@secure-exec/core 0.0.0-split-runtime-preview.7b0dded

package/dist/native-client.d.ts

@@ -0,0 +1,41 @@
+import { StdioSidecarProcess } from "./process.js";
+import type { LiveEventFrame, LiveResponseFrame, LiveSidecarRequestHandler, ProtocolFramePayloadCodec } from "./protocol-frames.js";
+import type { LiveOwnershipScope } from "./ownership.js";
+import type { LiveRequestPayload } from "./request-payloads.js";
+import type { LiveSidecarEventSelector } from "./event-buffer.js";
+export declare const DEFAULT_SIDECAR_FRAME_TIMEOUT_MS = 120000;
+export declare const DEFAULT_SIDECAR_EVENT_BUFFER_CAPACITY = 4096;
+export declare const DEFAULT_SIDECAR_GRACEFUL_EXIT_MS = 5000;
+export declare const DEFAULT_SIDECAR_FORCE_EXIT_MS = 2000;
+export interface StdioSidecarProtocolClientSpawnOptions {
+    cwd?: string;
+    command?: string;
+    args?: string[];
+    frameTimeoutMs?: number;
+    eventBufferCapacity?: number;
+    gracefulExitMs?: number;
+    forceExitMs?: number;
+    disposedErrorMessage?: string;
+    payloadCodec?: ProtocolFramePayloadCodec;
+}
+export declare class StdioSidecarProtocolClient {
+    readonly child: StdioSidecarProcess["child"];
+    private readonly sidecarProcess;
+    private readonly protocolClient;
+    private readonly gracefulExitMs;
+    private readonly forceExitMs;
+    private readonly disposedErrorMessage;
+    private constructor();
+    static spawn(options?: StdioSidecarProtocolClientSpawnOptions): StdioSidecarProtocolClient;
+    setSidecarRequestHandler(handler: LiveSidecarRequestHandler | null): void;
+    onEvent(handler: (event: LiveEventFrame) => void): () => void;
+    sendRequest(input: {
+        ownership: LiveOwnershipScope;
+        payload: LiveRequestPayload;
+    }): Promise<LiveResponseFrame>;
+    waitForEvent(matcher: LiveSidecarEventSelector | ((event: LiveEventFrame) => boolean), timeoutMs?: number, options?: {
+        signal?: AbortSignal;
+    }): Promise<LiveEventFrame>;
+    dispose(): Promise<void>;
+    failPermanently(error: Error): void;
+}

package/dist/native-client.js

@@ -0,0 +1,124 @@
+import { resolvePublishedSidecarBinary } from "./binary.js";
+import { SidecarProcessExited, StdioSidecarProcess, } from "./process.js";
+import { SidecarProtocolClient } from "./protocol-client.js";
+export const DEFAULT_SIDECAR_FRAME_TIMEOUT_MS = 120_000;
+export const DEFAULT_SIDECAR_EVENT_BUFFER_CAPACITY = 4_096;
+export const DEFAULT_SIDECAR_GRACEFUL_EXIT_MS = 5_000;
+export const DEFAULT_SIDECAR_FORCE_EXIT_MS = 2_000;
+export class StdioSidecarProtocolClient {
+    child;
+    sidecarProcess;
+    protocolClient;
+    gracefulExitMs;
+    forceExitMs;
+    disposedErrorMessage;
+    constructor(sidecarProcess, options) {
+        this.sidecarProcess = sidecarProcess;
+        this.child = sidecarProcess.child;
+        this.gracefulExitMs = options.gracefulExitMs;
+        this.forceExitMs = options.forceExitMs;
+        this.disposedErrorMessage = options.disposedErrorMessage;
+        this.protocolClient = new SidecarProtocolClient({
+            stdin: this.child.stdin,
+            stdout: this.child.stdout,
+            frameTimeoutMs: options.frameTimeoutMs,
+            eventBufferCapacity: options.eventBufferCapacity,
+            payloadCodec: options.payloadCodec,
+            stderrText: () => this.sidecarProcess.stderrText(),
+            streamEndedError: () => this.sidecarProcess.currentExitError() ??
+                new SidecarProcessExited({
+                    exitCode: this.child.exitCode,
+                    signal: this.child.signalCode,
+                    stderr: this.sidecarProcess.stderrText(),
+                }),
+            frameError: (error) => this.sidecarProcess.currentExitError() ?? error,
+        });
+        this.sidecarProcess.onExit((error) => {
+            this.failPermanently(error);
+        });
+        this.sidecarProcess.onError((error) => {
+            this.failPermanently(error);
+        });
+    }
+    static spawn(options = {}) {
+        return new StdioSidecarProtocolClient(StdioSidecarProcess.spawn({
+            command: options.command ?? resolvePublishedSidecarBinary(),
+            args: options.args ?? [],
+            cwd: options.cwd,
+        }), {
+            frameTimeoutMs: options.frameTimeoutMs ?? DEFAULT_SIDECAR_FRAME_TIMEOUT_MS,
+            eventBufferCapacity: options.eventBufferCapacity ??
+                DEFAULT_SIDECAR_EVENT_BUFFER_CAPACITY,
+            gracefulExitMs: options.gracefulExitMs ?? DEFAULT_SIDECAR_GRACEFUL_EXIT_MS,
+            forceExitMs: options.forceExitMs ?? DEFAULT_SIDECAR_FORCE_EXIT_MS,
+            disposedErrorMessage: options.disposedErrorMessage ?? "sidecar client disposed",
+            payloadCodec: options.payloadCodec ?? "bare",
+        });
+    }
+    setSidecarRequestHandler(handler) {
+        this.protocolClient.setSidecarRequestHandler(handler);
+    }
+    onEvent(handler) {
+        return this.protocolClient.onEvent(handler);
+    }
+    async sendRequest(input) {
+        return await this.protocolClient.sendRequest(input);
+    }
+    async waitForEvent(matcher, timeoutMs, options) {
+        return await this.protocolClient.waitForEvent(matcher, timeoutMs, options);
+    }
+    async dispose() {
+        this.protocolClient.failPermanently(new Error(this.disposedErrorMessage));
+        if (!this.child.stdin.destroyed) {
+            try {
+                this.child.stdin.end();
+            }
+            catch {
+                // Stdin may already be closing. The child exit watcher will catch up.
+            }
+        }
+        const exitCode = await this.sidecarProcess.waitForExit(this.gracefulExitMs);
+        if (exitCode === null) {
+            try {
+                this.child.kill("SIGKILL");
+            }
+            catch {
+                // The child may have exited between the timeout and the kill attempt.
+            }
+            await this.sidecarProcess.waitForExit(this.forceExitMs);
+        }
+        this.protocolClient.dispose();
+        try {
+            this.child.stdin.destroy();
+        }
+        catch {
+            // Best effort. The child is gone so the descriptor will close on its own.
+        }
+        try {
+            this.child.stdout.destroy();
+        }
+        catch {
+            // Best effort. The child is gone so the descriptor will close on its own.
+        }
+        try {
+            this.child.stderr.destroy();
+        }
+        catch {
+            // Best effort. The child is gone so the descriptor will close on its own.
+        }
+        if (exitCode !== null &&
+            exitCode !== 0 &&
+            this.child.signalCode === null) {
+            throw new Error(`sidecar exited with code ${exitCode}\nstderr:\n${this.sidecarProcess.stderrText()}`);
+        }
+    }
+    failPermanently(error) {
+        this.protocolClient.failPermanently(error, {
+            replaceExisting: (current, next) => current instanceof SidecarProcessExited &&
+                current.exitCode === null &&
+                current.signal === null &&
+                next instanceof SidecarProcessExited &&
+                (next.exitCode !== null || next.signal !== null),
+        });
+    }
+}

package/dist/numbers.d.ts

@@ -0,0 +1 @@
+export declare function bigIntToSafeNumber(value: bigint, context: string): number;

package/dist/numbers.js

@@ -0,0 +1,8 @@
+export function bigIntToSafeNumber(value, context) {
+    const max = BigInt(Number.MAX_SAFE_INTEGER);
+    const min = BigInt(Number.MIN_SAFE_INTEGER);
+    if (value > max || value < min) {
+        throw new Error(`${context} exceeds JavaScript safe integer range`);
+    }
+    return Number(value);
+}

package/dist/ownership.d.ts

@@ -0,0 +1,18 @@
+import * as protocol from "./generated-protocol.js";
+export type LiveOwnershipScope = {
+    scope: "connection";
+    connection_id: string;
+} | {
+    scope: "session";
+    connection_id: string;
+    session_id: string;
+} | {
+    scope: "vm";
+    connection_id: string;
+    session_id: string;
+    vm_id: string;
+};
+export declare function ownershipSelectorKey(ownership: LiveOwnershipScope): string;
+export declare function ownershipMatchesSelector(selector: LiveOwnershipScope | undefined, ownership: LiveOwnershipScope): boolean;
+export declare function toGeneratedOwnershipScope(ownership: LiveOwnershipScope): protocol.OwnershipScope;
+export declare function fromGeneratedOwnershipScope(ownership: protocol.OwnershipScope): LiveOwnershipScope;

package/dist/ownership.js

@@ -0,0 +1,77 @@
+export function ownershipSelectorKey(ownership) {
+    switch (ownership.scope) {
+        case "connection":
+            return `connection:${ownership.connection_id}`;
+        case "session":
+            return `session:${ownership.connection_id}:${ownership.session_id}`;
+        case "vm":
+            return `vm:${ownership.connection_id}:${ownership.session_id}:${ownership.vm_id}`;
+    }
+}
+export function ownershipMatchesSelector(selector, ownership) {
+    if (!selector) {
+        return true;
+    }
+    switch (selector.scope) {
+        case "connection":
+            return (ownership.scope === "connection" &&
+                selector.connection_id === ownership.connection_id);
+        case "session":
+            return (ownership.scope === "session" &&
+                selector.connection_id === ownership.connection_id &&
+                selector.session_id === ownership.session_id);
+        case "vm":
+            return (ownership.scope === "vm" &&
+                selector.connection_id === ownership.connection_id &&
+                selector.session_id === ownership.session_id &&
+                selector.vm_id === ownership.vm_id);
+    }
+}
+export function toGeneratedOwnershipScope(ownership) {
+    switch (ownership.scope) {
+        case "connection":
+            return {
+                tag: "ConnectionOwnership",
+                val: { connectionId: ownership.connection_id },
+            };
+        case "session":
+            return {
+                tag: "SessionOwnership",
+                val: {
+                    connectionId: ownership.connection_id,
+                    sessionId: ownership.session_id,
+                },
+            };
+        case "vm":
+            return {
+                tag: "VmOwnership",
+                val: {
+                    connectionId: ownership.connection_id,
+                    sessionId: ownership.session_id,
+                    vmId: ownership.vm_id,
+                },
+            };
+    }
+}
+export function fromGeneratedOwnershipScope(ownership) {
+    switch (ownership.tag) {
+        case "ConnectionOwnership":
+            return {
+                scope: "connection",
+                connection_id: ownership.val.connectionId,
+            };
+        case "SessionOwnership":
+            return {
+                scope: "session",
+                connection_id: ownership.val.connectionId,
+                session_id: ownership.val.sessionId,
+            };
+        case "VmOwnership":
+            return {
+                scope: "vm",
+                connection_id: ownership.val.connectionId,
+                session_id: ownership.val.sessionId,
+                vm_id: ownership.val.vmId,
+            };
+    }
+}

package/dist/permissions.d.ts

@@ -0,0 +1,29 @@
+import * as protocol from "./generated-protocol.js";
+import { type LivePermissionMode } from "./protocol-maps.js";
+export type { LivePermissionMode } from "./protocol-maps.js";
+export interface LiveFsPermissionRule {
+    mode: LivePermissionMode;
+    operations?: string[];
+    paths?: string[];
+}
+export interface LivePatternPermissionRule {
+    mode: LivePermissionMode;
+    operations?: string[];
+    patterns?: string[];
+}
+export interface LiveRulePermissions<TRule> {
+    default?: LivePermissionMode;
+    rules: TRule[];
+}
+export type LivePermissionScope<TRule> = LivePermissionMode | LiveRulePermissions<TRule>;
+export interface LivePermissionsPolicy {
+    fs?: LivePermissionScope<LiveFsPermissionRule>;
+    network?: LivePermissionScope<LivePatternPermissionRule>;
+    child_process?: LivePermissionScope<LivePatternPermissionRule>;
+    process?: LivePermissionScope<LivePatternPermissionRule>;
+    env?: LivePermissionScope<LivePatternPermissionRule>;
+    tool?: LivePermissionScope<LivePatternPermissionRule>;
+}
+export declare function toGeneratedPermissionsPolicy(policy: LivePermissionsPolicy | undefined): protocol.PermissionsPolicy | null;
+export declare function toGeneratedFilesystemPermissionScope(scope: LivePermissionScope<LiveFsPermissionRule>): protocol.FsPermissionScope;
+export declare function toGeneratedPatternPermissionScope(scope: LivePermissionScope<LivePatternPermissionRule>): protocol.PatternPermissionScope;

package/dist/permissions.js

@@ -0,0 +1,68 @@
+import { toGeneratedPermissionMode, } from "./protocol-maps.js";
+export function toGeneratedPermissionsPolicy(policy) {
+    if (policy === undefined) {
+        return null;
+    }
+    return {
+        fs: policy.fs === undefined
+            ? null
+            : toGeneratedFilesystemPermissionScope(policy.fs),
+        network: policy.network === undefined
+            ? null
+            : toGeneratedPatternPermissionScope(policy.network),
+        childProcess: policy.child_process === undefined
+            ? null
+            : toGeneratedPatternPermissionScope(policy.child_process),
+        process: policy.process === undefined
+            ? null
+            : toGeneratedPatternPermissionScope(policy.process),
+        env: policy.env === undefined
+            ? null
+            : toGeneratedPatternPermissionScope(policy.env),
+        tool: policy.tool === undefined
+            ? null
+            : toGeneratedPatternPermissionScope(policy.tool),
+    };
+}
+export function toGeneratedFilesystemPermissionScope(scope) {
+    if (typeof scope === "string") {
+        return {
+            tag: "PermissionMode",
+            val: toGeneratedPermissionMode(scope),
+        };
+    }
+    return {
+        tag: "FsPermissionRuleSet",
+        val: {
+            default: scope.default === undefined
+                ? null
+                : toGeneratedPermissionMode(scope.default),
+            rules: scope.rules.map((rule) => ({
+                mode: toGeneratedPermissionMode(rule.mode),
+                operations: rule.operations ?? [],
+                paths: rule.paths ?? [],
+            })),
+        },
+    };
+}
+export function toGeneratedPatternPermissionScope(scope) {
+    if (typeof scope === "string") {
+        return {
+            tag: "PermissionMode",
+            val: toGeneratedPermissionMode(scope),
+        };
+    }
+    return {
+        tag: "PatternPermissionRuleSet",
+        val: {
+            default: scope.default === undefined
+                ? null
+                : toGeneratedPermissionMode(scope.default),
+            rules: scope.rules.map((rule) => ({
+                mode: toGeneratedPermissionMode(rule.mode),
+                operations: rule.operations ?? [],
+                patterns: rule.patterns ?? [],
+            })),
+        },
+    };
+}

package/dist/process.d.ts

@@ -0,0 +1,35 @@
+import { type ChildProcessWithoutNullStreams } from "node:child_process";
+export interface StdioSidecarProcessSpawnOptions {
+    command: string;
+    args?: string[];
+    cwd?: string;
+}
+export declare class SidecarProcessExited extends Error {
+    readonly exitCode: number | null;
+    readonly signal: NodeJS.Signals | null;
+    readonly stderr: string;
+    constructor(options: {
+        exitCode: number | null;
+        signal: NodeJS.Signals | null;
+        stderr: string;
+    });
+}
+export declare class SidecarProcessError extends Error {
+    readonly childError: Error;
+    readonly stderr: string;
+    constructor(error: Error, stderr: string);
+}
+export declare class StdioSidecarProcess {
+    readonly child: ChildProcessWithoutNullStreams;
+    private readonly stderrChunks;
+    private readonly exitListeners;
+    private readonly errorListeners;
+    private constructor();
+    static spawn(options: StdioSidecarProcessSpawnOptions): StdioSidecarProcess;
+    static fromChild(child: ChildProcessWithoutNullStreams): StdioSidecarProcess;
+    onExit(handler: (error: SidecarProcessExited) => void): () => void;
+    onError(handler: (error: SidecarProcessError) => void): () => void;
+    stderrText(): string;
+    currentExitError(): SidecarProcessExited | null;
+    waitForExit(timeoutMs: number): Promise<number | null>;
+}

package/dist/process.js

@@ -0,0 +1,125 @@
+import { spawn, } from "node:child_process";
+function formatSidecarStderrSuffix(stderr) {
+    return stderr ? `\nstderr:\n${stderr}` : "";
+}
+export class SidecarProcessExited extends Error {
+    exitCode;
+    signal;
+    stderr;
+    constructor(options) {
+        const reason = options.signal !== null
+            ? `signal ${options.signal}`
+            : options.exitCode !== null
+                ? `code ${options.exitCode}`
+                : "disconnect";
+        super(`sidecar process exited with ${reason}${formatSidecarStderrSuffix(options.stderr)}`);
+        this.name = "SidecarProcessExited";
+        this.exitCode = options.exitCode;
+        this.signal = options.signal;
+        this.stderr = options.stderr;
+    }
+}
+export class SidecarProcessError extends Error {
+    childError;
+    stderr;
+    constructor(error, stderr) {
+        super(`sidecar process error: ${error.message}${formatSidecarStderrSuffix(stderr)}`);
+        this.name = "SidecarProcessError";
+        this.childError = error;
+        this.stderr = stderr;
+    }
+}
+export class StdioSidecarProcess {
+    child;
+    stderrChunks = [];
+    exitListeners = new Set();
+    errorListeners = new Set();
+    constructor(child) {
+        this.child = child;
+        this.child.stderr.on("data", (chunk) => {
+            this.stderrChunks.push(typeof chunk === "string" ? Buffer.from(chunk) : Buffer.from(chunk));
+        });
+        this.child.on("exit", (code, signal) => {
+            const error = new SidecarProcessExited({
+                exitCode: code,
+                signal,
+                stderr: this.stderrText(),
+            });
+            for (const listener of this.exitListeners) {
+                listener(error);
+            }
+        });
+        this.child.on("error", (error) => {
+            const normalized = error instanceof Error ? error : new Error(String(error));
+            const sidecarError = new SidecarProcessError(normalized, this.stderrText());
+            for (const listener of this.errorListeners) {
+                listener(sidecarError);
+            }
+        });
+    }
+    static spawn(options) {
+        return new StdioSidecarProcess(spawn(options.command, options.args ?? [], {
+            cwd: options.cwd,
+            stdio: ["pipe", "pipe", "pipe"],
+        }));
+    }
+    static fromChild(child) {
+        return new StdioSidecarProcess(child);
+    }
+    onExit(handler) {
+        this.exitListeners.add(handler);
+        return () => {
+            this.exitListeners.delete(handler);
+        };
+    }
+    onError(handler) {
+        this.errorListeners.add(handler);
+        return () => {
+            this.errorListeners.delete(handler);
+        };
+    }
+    stderrText() {
+        return Buffer.concat(this.stderrChunks).toString("utf8").trim();
+    }
+    currentExitError() {
+        if (this.child.exitCode === null && this.child.signalCode === null) {
+            return null;
+        }
+        return new SidecarProcessExited({
+            exitCode: this.child.exitCode,
+            signal: this.child.signalCode,
+            stderr: this.stderrText(),
+        });
+    }
+    waitForExit(timeoutMs) {
+        return new Promise((resolve) => {
+            let timer = null;
+            const cleanup = () => {
+                this.child.off("exit", onExit);
+                this.child.off("close", onClose);
+                if (timer !== null) {
+                    clearTimeout(timer);
+                    timer = null;
+                }
+            };
+            const onExit = (code) => {
+                cleanup();
+                resolve(code);
+            };
+            const onClose = (code) => {
+                cleanup();
+                resolve(code);
+            };
+            if (this.child.exitCode !== null || this.child.signalCode !== null) {
+                resolve(this.child.exitCode);
+                return;
+            }
+            this.child.on("exit", onExit);
+            this.child.on("close", onClose);
+            timer = setTimeout(() => {
+                cleanup();
+                resolve(null);
+            }, timeoutMs);
+        });
+    }
+}

package/dist/protocol-client.d.ts

@@ -0,0 +1,46 @@
+import type { Readable, Writable } from "node:stream";
+import { type LiveSidecarEventSelector } from "./event-buffer.js";
+import { type LiveEventFrame, type LiveResponseFrame, type LiveSidecarRequestHandler, type ProtocolFramePayloadCodec } from "./protocol-frames.js";
+import type { LiveOwnershipScope } from "./ownership.js";
+import type { LiveRequestPayload } from "./request-payloads.js";
+export interface SidecarProtocolClientOptions {
+    stdin: Writable;
+    stdout: Readable;
+    frameTimeoutMs: number;
+    eventBufferCapacity: number;
+    payloadCodec?: ProtocolFramePayloadCodec;
+    stderrText?: () => string;
+    frameError?: (error: Error) => Error;
+    streamEndedError?: () => Error;
+}
+export declare class SidecarProtocolClient {
+    private readonly eventBuffer;
+    private readonly eventListeners;
+    private readonly frameTimeoutMs;
+    private readonly payloadCodec;
+    private readonly stderrText;
+    private readonly hostFrameFactory;
+    private readonly frameTransport;
+    private closedError;
+    private readonly eventWaiters;
+    private sidecarRequestHandler;
+    constructor(options: SidecarProtocolClientOptions);
+    setSidecarRequestHandler(handler: LiveSidecarRequestHandler | null): void;
+    onEvent(handler: (event: LiveEventFrame) => void): () => void;
+    sendRequest(input: {
+        ownership: LiveOwnershipScope;
+        payload: LiveRequestPayload;
+    }): Promise<LiveResponseFrame>;
+    waitForEvent(matcher: LiveSidecarEventSelector | ((event: LiveEventFrame) => boolean), timeoutMs?: number, options?: {
+        signal?: AbortSignal;
+    }): Promise<LiveEventFrame>;
+    failPermanently(error: Error, options?: {
+        replaceExisting?: (current: Error, next: Error) => boolean;
+    }): void;
+    dispose(): void;
+    private writeFrame;
+    private dispatchSidecarRequest;
+    private dispatchEvent;
+    private bufferEvent;
+    private rejectPending;
+}