@secure-exec/core 0.0.0-nathan-docs-sdk-expansion.c9c2e4e

package/README.md

@@ -0,0 +1,7 @@
+# @secure-exec/core
+
+Raw Secure Exec protocol types and codecs.
+
+- `@secure-exec/core/protocol` exports the generated sidecar protocol.
+- `@secure-exec/core/binary` resolves the published `secure-exec-sidecar` binary and honors `SECURE_EXEC_SIDECAR_BIN`.
+- `@secure-exec/core/framing`, `@secure-exec/core/frame-stream`, `@secure-exec/core/frame-rpc`, `@secure-exec/core/frame-payload-codec`, `@secure-exec/core/correlation`, `@secure-exec/core/event-buffer`, `@secure-exec/core/ownership`, `@secure-exec/core/permissions`, `@secure-exec/core/state`, `@secure-exec/core/request-payloads`, `@secure-exec/core/response-payloads`, `@secure-exec/core/protocol-frames`, `@secure-exec/core/protocol-client`, `@secure-exec/core/native-client`, `@secure-exec/core/descriptors`, `@secure-exec/core/process`, `@secure-exec/core/protocol-schema`, `@secure-exec/core/protocol-maps`, `@secure-exec/core/callbacks`, `@secure-exec/core/filesystem`, `@secure-exec/core/json`, `@secure-exec/core/numbers`, `@secure-exec/core/bytes`, and `@secure-exec/core/ext` expose generic Node transport primitives.

package/dist/binary.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Resolves the published secure-exec sidecar binary for Node.js clients.
+ */
+export declare function resolvePublishedSidecarBinary(): string;

package/dist/binary.js

@@ -0,0 +1,25 @@
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+/**
+ * Resolves the published secure-exec sidecar binary for Node.js clients.
+ */
+export function resolvePublishedSidecarBinary() {
+    const override = process.env.SECURE_EXEC_SIDECAR_BIN;
+    if (override) {
+        if (!existsSync(override)) {
+            throw new Error(`SECURE_EXEC_SIDECAR_BIN is set to ${override} but the file does not exist`);
+        }
+        return override;
+    }
+    const require = createRequire(import.meta.url);
+    let mod;
+    try {
+        mod = require("@secure-exec/sidecar");
+    }
+    catch (error) {
+        throw new Error("failed to resolve the secure-exec sidecar binary: the @secure-exec/sidecar " +
+            "package is not installed. Install it, or set SECURE_EXEC_SIDECAR_BIN to a local " +
+            `secure-exec-sidecar binary. (${error.message})`);
+    }
+    return mod.getSidecarPath();
+}

package/dist/bytes.d.ts

@@ -0,0 +1,2 @@
+export declare function toExactArrayBuffer(value: Uint8Array): ArrayBuffer;
+export declare function toExactUint8Array(value: Uint8Array): Uint8Array;

package/dist/bytes.js

@@ -0,0 +1,6 @@
+export function toExactArrayBuffer(value) {
+    return value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength);
+}
+export function toExactUint8Array(value) {
+    return Uint8Array.from(value);
+}

package/dist/callbacks.d.ts

@@ -0,0 +1,41 @@
+import type * as protocol from "./generated-protocol.js";
+export interface CallbackExtEnvelope {
+    namespace: string;
+    payload: Uint8Array;
+}
+export type CallbackSidecarRequestPayload = {
+    type: "host_callback";
+    invocation_id: string;
+    callback_key: string;
+    input: unknown;
+    timeout_ms: number;
+} | {
+    type: "js_bridge_call";
+    call_id: string;
+    mount_id: string;
+    operation: string;
+    args: unknown;
+} | {
+    type: "ext";
+    envelope: CallbackExtEnvelope;
+};
+export type CallbackSidecarResponsePayload = {
+    type: "host_callback_result";
+    invocation_id: string;
+    result?: unknown;
+    error?: string;
+} | {
+    type: "js_bridge_result";
+    call_id: string;
+    result?: unknown;
+    error?: string;
+} | {
+    type: "ext_result";
+    envelope: CallbackExtEnvelope;
+};
+export type LiveSidecarRequestPayload = CallbackSidecarRequestPayload;
+export type LiveSidecarResponsePayload = CallbackSidecarResponsePayload;
+export declare function isMatchingSidecarResponsePayload(request: CallbackSidecarRequestPayload, response: CallbackSidecarResponsePayload): boolean;
+export declare function errorSidecarResponsePayload(request: CallbackSidecarRequestPayload, error: unknown): CallbackSidecarResponsePayload;
+export declare function fromGeneratedSidecarRequestPayload(payload: protocol.SidecarRequestPayload): LiveSidecarRequestPayload;
+export declare function toGeneratedSidecarResponsePayload(payload: LiveSidecarResponsePayload): protocol.SidecarResponsePayload;

package/dist/callbacks.js

@@ -0,0 +1,94 @@
+import { fromGeneratedExtEnvelope, toGeneratedExtEnvelope, } from "./ext.js";
+import { parseJsonUtf8, stringifyJsonUtf8 } from "./json.js";
+import { bigIntToSafeNumber } from "./numbers.js";
+export function isMatchingSidecarResponsePayload(request, response) {
+    switch (request.type) {
+        case "host_callback":
+            return response.type === "host_callback_result";
+        case "js_bridge_call":
+            return response.type === "js_bridge_result";
+        case "ext":
+            return response.type === "ext_result";
+    }
+}
+export function errorSidecarResponsePayload(request, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    switch (request.type) {
+        case "host_callback":
+            return {
+                type: "host_callback_result",
+                invocation_id: request.invocation_id,
+                error: message,
+            };
+        case "js_bridge_call":
+            return {
+                type: "js_bridge_result",
+                call_id: request.call_id,
+                error: message,
+            };
+        case "ext":
+            return {
+                type: "ext_result",
+                envelope: {
+                    namespace: request.envelope.namespace,
+                    payload: Buffer.from(message, "utf8"),
+                },
+            };
+    }
+}
+export function fromGeneratedSidecarRequestPayload(payload) {
+    switch (payload.tag) {
+        case "HostCallbackRequest":
+            return {
+                type: "host_callback",
+                invocation_id: payload.val.invocationId,
+                callback_key: payload.val.callbackKey,
+                input: parseJsonUtf8(payload.val.input, "host callback input"),
+                timeout_ms: bigIntToSafeNumber(payload.val.timeoutMs, "host callback timeout"),
+            };
+        case "JsBridgeCallRequest":
+            return {
+                type: "js_bridge_call",
+                call_id: payload.val.callId,
+                mount_id: payload.val.mountId,
+                operation: payload.val.operation,
+                args: parseJsonUtf8(payload.val.args, "js bridge call args"),
+            };
+        case "ExtEnvelope":
+            return {
+                type: "ext",
+                envelope: fromGeneratedExtEnvelope(payload.val),
+            };
+    }
+}
+export function toGeneratedSidecarResponsePayload(payload) {
+    switch (payload.type) {
+        case "host_callback_result":
+            return {
+                tag: "HostCallbackResultResponse",
+                val: {
+                    invocationId: payload.invocation_id,
+                    result: payload.result === undefined
+                        ? null
+                        : stringifyJsonUtf8(payload.result, "host_callback_result.result"),
+                    error: payload.error ?? null,
+                },
+            };
+        case "js_bridge_result":
+            return {
+                tag: "JsBridgeResultResponse",
+                val: {
+                    callId: payload.call_id,
+                    result: payload.result === undefined
+                        ? null
+                        : stringifyJsonUtf8(payload.result, "js_bridge_result.result"),
+                    error: payload.error ?? null,
+                },
+            };
+        case "ext_result":
+            return {
+                tag: "ExtEnvelope",
+                val: toGeneratedExtEnvelope(payload.envelope),
+            };
+    }
+}

package/dist/cargo.d.ts

@@ -0,0 +1,2 @@
+export declare function findCargoBinary(): string | null;
+export declare function resolveCargoBinary(): string;

package/dist/cargo.js

@@ -0,0 +1,142 @@
+import { accessSync, constants as fsConstants, existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+const CARGO_BINARY_NAME = process.platform === "win32" ? "cargo.exe" : "cargo";
+function hasPathSeparator(candidate) {
+    return candidate.includes("/") || candidate.includes("\\");
+}
+function isExecutableFile(candidate) {
+    try {
+        if (!statSync(candidate).isFile()) {
+            return false;
+        }
+        accessSync(candidate, fsConstants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function resolveExecutableOnPath(binaryName) {
+    const pathEntries = (process.env.PATH ?? "")
+        .split(path.delimiter)
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    for (const entry of pathEntries) {
+        const candidate = path.join(entry, binaryName);
+        if (isExecutableFile(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function resolveExecutableCandidate(candidate) {
+    if (hasPathSeparator(candidate)) {
+        return isExecutableFile(candidate) ? candidate : null;
+    }
+    return resolveExecutableOnPath(candidate);
+}
+function getToolchainCargoFromRustupHome(rustupHome) {
+    const toolchainsDir = path.join(rustupHome, "toolchains");
+    if (!existsSync(toolchainsDir)) {
+        return null;
+    }
+    const settingsPath = path.join(rustupHome, "settings.toml");
+    const orderedToolchains = [];
+    if (existsSync(settingsPath)) {
+        const defaultToolchain = readFileSync(settingsPath, "utf8")
+            .match(/^default_toolchain\s*=\s*"([^"]+)"/m)?.[1]
+            ?.trim();
+        if (defaultToolchain) {
+            orderedToolchains.push(defaultToolchain);
+        }
+    }
+    for (const entry of readdirSync(toolchainsDir)) {
+        if (!orderedToolchains.includes(entry)) {
+            orderedToolchains.push(entry);
+        }
+    }
+    for (const toolchain of orderedToolchains) {
+        const cargoPath = path.join(toolchainsDir, toolchain, "bin", CARGO_BINARY_NAME);
+        if (existsSync(cargoPath)) {
+            return { cargoPath, rustupHome };
+        }
+    }
+    return null;
+}
+function inferRustupHomesFromPath() {
+    const rustupHomes = new Set();
+    const pathEntries = (process.env.PATH ?? "")
+        .split(path.delimiter)
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    for (const entry of pathEntries) {
+        if (path.basename(entry) !== "bin") {
+            continue;
+        }
+        const parentDir = path.dirname(entry);
+        if (existsSync(path.join(parentDir, "toolchains"))) {
+            rustupHomes.add(parentDir);
+        }
+        const siblingRoot = path.dirname(parentDir);
+        try {
+            for (const sibling of readdirSync(siblingRoot, { withFileTypes: true })) {
+                if (!sibling.isDirectory()) {
+                    continue;
+                }
+                const siblingPath = path.join(siblingRoot, sibling.name);
+                if (existsSync(path.join(siblingPath, "toolchains"))) {
+                    rustupHomes.add(siblingPath);
+                }
+            }
+        }
+        catch { }
+    }
+    return [...rustupHomes];
+}
+function ensureToolchainEnvironment(toolchainCargo) {
+    const toolchainBin = path.dirname(toolchainCargo.cargoPath);
+    const currentPathEntries = (process.env.PATH ?? "")
+        .split(path.delimiter)
+        .filter(Boolean);
+    if (!currentPathEntries.includes(toolchainBin)) {
+        process.env.PATH = [toolchainBin, ...currentPathEntries].join(path.delimiter);
+    }
+    if (!process.env.RUSTUP_HOME) {
+        process.env.RUSTUP_HOME = toolchainCargo.rustupHome;
+    }
+    const toolchainName = path.basename(path.dirname(toolchainBin));
+    if (!process.env.RUSTUP_TOOLCHAIN) {
+        process.env.RUSTUP_TOOLCHAIN = toolchainName;
+    }
+}
+export function findCargoBinary() {
+    const explicitCargo = process.env.CARGO?.trim();
+    const rustupHomes = [
+        process.env.RUSTUP_HOME?.trim(),
+        path.join(homedir(), ".rustup"),
+        ...inferRustupHomesFromPath(),
+    ].filter((candidate) => Boolean(candidate));
+    const toolchainCargoCandidates = rustupHomes
+        .map((rustupHome) => getToolchainCargoFromRustupHome(rustupHome))
+        .filter((candidate) => Boolean(candidate));
+    if (toolchainCargoCandidates.length > 0) {
+        ensureToolchainEnvironment(toolchainCargoCandidates[0]);
+    }
+    const candidates = [
+        explicitCargo,
+        ...toolchainCargoCandidates.map((candidate) => candidate.cargoPath),
+        path.join(homedir(), ".cargo", "bin", CARGO_BINARY_NAME),
+        CARGO_BINARY_NAME,
+    ].filter((candidate) => Boolean(candidate));
+    for (const candidate of candidates) {
+        const resolved = resolveExecutableCandidate(candidate);
+        if (resolved) {
+            return resolved;
+        }
+    }
+    return null;
+}
+export function resolveCargoBinary() {
+    return findCargoBinary() ?? CARGO_BINARY_NAME;
+}

package/dist/correlation.d.ts

@@ -0,0 +1,10 @@
+export declare class PendingResponseRegistry<TResponse> {
+    private readonly pending;
+    waitForResponse(requestId: number, options: {
+        timeoutMs: number;
+        timeoutMessage: () => string;
+    }): Promise<TResponse>;
+    resolve(requestId: number, frame: TResponse): boolean;
+    reject(requestId: number, error: Error): boolean;
+    rejectAll(error: Error): void;
+}

package/dist/correlation.js

@@ -0,0 +1,49 @@
+export class PendingResponseRegistry {
+    pending = new Map();
+    waitForResponse(requestId, options) {
+        if (this.pending.has(requestId)) {
+            throw new Error(`response waiter already registered for request ${requestId}`);
+        }
+        return new Promise((resolve, reject) => {
+            const entry = {
+                resolve: (frame) => {
+                    clearTimeout(entry.timer);
+                    this.pending.delete(requestId);
+                    resolve(frame);
+                },
+                reject: (error) => {
+                    clearTimeout(entry.timer);
+                    this.pending.delete(requestId);
+                    reject(error);
+                },
+                timer: setTimeout(() => {
+                    this.pending.delete(requestId);
+                    reject(new Error(options.timeoutMessage()));
+                }, options.timeoutMs),
+            };
+            this.pending.set(requestId, entry);
+        });
+    }
+    resolve(requestId, frame) {
+        const pending = this.pending.get(requestId);
+        if (!pending) {
+            return false;
+        }
+        pending.resolve(frame);
+        return true;
+    }
+    reject(requestId, error) {
+        const pending = this.pending.get(requestId);
+        if (!pending) {
+            return false;
+        }
+        pending.reject(error);
+        return true;
+    }
+    rejectAll(error) {
+        for (const pending of this.pending.values()) {
+            pending.reject(error);
+        }
+        this.pending.clear();
+    }
+}

package/dist/descriptors.d.ts

@@ -0,0 +1,34 @@
+import type * as protocol from "./generated-protocol.js";
+export type LiveSidecarPlacement = {
+    kind: "shared";
+    pool?: string | null;
+} | {
+    kind: "explicit";
+    sidecar_id: string;
+};
+export type MountConfigJsonPrimitive = string | number | boolean | null;
+export type MountConfigJsonValue = MountConfigJsonPrimitive | MountConfigJsonObject | MountConfigJsonValue[];
+export interface MountConfigJsonObject {
+    [key: string]: MountConfigJsonValue;
+}
+export interface NativeMountPluginDescriptor<TConfig extends MountConfigJsonObject = MountConfigJsonObject> {
+    id: string;
+    config?: TConfig;
+}
+export interface LiveMountDescriptor {
+    guest_path: string;
+    read_only: boolean;
+    plugin: NativeMountPluginDescriptor;
+}
+export interface LiveSoftwareDescriptor {
+    package_name: string;
+    root: string;
+}
+export interface LiveProjectedModuleDescriptor {
+    package_name: string;
+    entrypoint: string;
+}
+export declare function toGeneratedSidecarPlacement(placement: LiveSidecarPlacement): protocol.SidecarPlacement;
+export declare function toGeneratedMountDescriptor(descriptor: LiveMountDescriptor): protocol.MountDescriptor;
+export declare function toGeneratedSoftwareDescriptor(descriptor: LiveSoftwareDescriptor): protocol.SoftwareDescriptor;
+export declare function toGeneratedProjectedModuleDescriptor(descriptor: LiveProjectedModuleDescriptor): protocol.ProjectedModuleDescriptor;

package/dist/descriptors.js

@@ -0,0 +1,37 @@
+import { stringifyJsonUtf8 } from "./json.js";
+export function toGeneratedSidecarPlacement(placement) {
+    switch (placement.kind) {
+        case "shared":
+            return {
+                tag: "SidecarPlacementShared",
+                val: { pool: placement.pool ?? null },
+            };
+        case "explicit":
+            return {
+                tag: "SidecarPlacementExplicit",
+                val: { sidecarId: placement.sidecar_id },
+            };
+    }
+}
+export function toGeneratedMountDescriptor(descriptor) {
+    return {
+        guestPath: descriptor.guest_path,
+        readOnly: descriptor.read_only,
+        plugin: {
+            id: descriptor.plugin.id,
+            config: stringifyJsonUtf8(descriptor.plugin.config ?? {}, "mount plugin config"),
+        },
+    };
+}
+export function toGeneratedSoftwareDescriptor(descriptor) {
+    return {
+        packageName: descriptor.package_name,
+        root: descriptor.root,
+    };
+}
+export function toGeneratedProjectedModuleDescriptor(descriptor) {
+    return {
+        packageName: descriptor.package_name,
+        entrypoint: descriptor.entrypoint,
+    };
+}

package/dist/event-buffer.d.ts

@@ -0,0 +1,90 @@
+import { type LiveExtEnvelope } from "./ext.js";
+import type * as protocol from "./generated-protocol.js";
+import { type LiveOwnershipScope } from "./ownership.js";
+export declare const ANY_BUFFERED_EVENT_KEY = "*";
+export type { LiveOwnershipScope } from "./ownership.js";
+export type LiveSidecarEventPayload = {
+    type: "vm_lifecycle";
+    state: "creating" | "ready" | "disposing" | "disposed" | "failed";
+} | {
+    type: "process_output";
+    process_id: string;
+    channel: "stdout" | "stderr";
+    chunk: Uint8Array;
+} | {
+    type: "process_exited";
+    process_id: string;
+    exit_code: number;
+} | {
+    type: "structured";
+    name: string;
+    detail: Record<string, string>;
+} | {
+    type: "ext";
+    envelope: LiveExtEnvelope;
+};
+export interface LiveSidecarEventFrame {
+    ownership: LiveOwnershipScope;
+    payload: LiveSidecarEventPayload;
+}
+export type LiveSidecarEventSelector = {
+    any: true;
+} | {
+    type: "vm_lifecycle";
+    ownership?: LiveOwnershipScope;
+    state?: Extract<LiveSidecarEventPayload, {
+        type: "vm_lifecycle";
+    }>["state"];
+} | {
+    type: "process_output";
+    ownership?: LiveOwnershipScope;
+    processId?: string;
+    channel?: Extract<LiveSidecarEventPayload, {
+        type: "process_output";
+    }>["channel"];
+} | {
+    type: "process_exited";
+    ownership?: LiveOwnershipScope;
+    processId?: string;
+} | {
+    type: "structured";
+    ownership?: LiveOwnershipScope;
+    name?: string;
+    detail?: Record<string, string>;
+};
+export type LiveSidecarBufferedEventRecord<TEvent extends LiveSidecarEventFrame> = {
+    event: TEvent;
+    keys: readonly string[];
+};
+export type LiveSidecarEventWaitMatcher<TEvent extends LiveSidecarEventFrame> = {
+    matches: (event: TEvent) => boolean;
+    bufferKey: string | null;
+};
+export declare class SidecarEventBufferOverflow extends Error {
+    readonly capacity: number;
+    readonly bufferedEvents: number;
+    readonly eventType: LiveSidecarEventPayload["type"];
+    constructor(options: {
+        capacity: number;
+        bufferedEvents: number;
+        eventType: LiveSidecarEventPayload["type"];
+    });
+}
+export declare class SidecarEventBuffer<TEvent extends LiveSidecarEventFrame> {
+    private readonly capacity;
+    private readonly bufferedEvents;
+    private readonly bufferedEventQueues;
+    private nextBufferedEventId;
+    constructor(capacity: number);
+    get size(): number;
+    buffer(event: TEvent): SidecarEventBufferOverflow | null;
+    take(matcher: LiveSidecarEventWaitMatcher<TEvent>): TEvent | null;
+    private takeFromKey;
+    private remove;
+}
+export declare function sidecarSelectorMatchesEvent<TEvent extends LiveSidecarEventFrame>(selector: LiveSidecarEventSelector, event: TEvent): boolean;
+export declare function sidecarSelectorBufferKey(selector: LiveSidecarEventSelector): string | null;
+export declare function normalizeSidecarEventMatcher<TEvent extends LiveSidecarEventFrame>(selector: LiveSidecarEventSelector | ((event: TEvent) => boolean)): LiveSidecarEventWaitMatcher<TEvent>;
+export declare function fromGeneratedEventPayload(payload: protocol.EventPayload): LiveSidecarEventPayload;
+export declare function sidecarEventWaitAbortError(reason: unknown): Error;
+export declare function sidecarEventBufferKeys<TEvent extends LiveSidecarEventFrame>(event: TEvent): string[];