@secure-exec/core 0.2.1 → 0.3.0-rc.1

package/dist/protocol-frames.js

@@ -0,0 +1,139 @@
+import { toExactUint8Array } from "./bytes.js";
+import { decodeJsonFramePayload, encodeJsonFramePayload, } from "./frame-payload-codec.js";
+import { errorSidecarResponsePayload, fromGeneratedSidecarRequestPayload, isMatchingSidecarResponsePayload, toGeneratedSidecarResponsePayload, } from "./callbacks.js";
+import { fromGeneratedEventPayload, } from "./event-buffer.js";
+import * as protocol from "./generated-protocol.js";
+import { bigIntToSafeNumber } from "./numbers.js";
+import { fromGeneratedOwnershipScope, toGeneratedOwnershipScope, } from "./ownership.js";
+import { SIDECAR_PROTOCOL_SCHEMA, validateSidecarProtocolSchema, } from "./protocol-schema.js";
+import { toGeneratedRequestPayload, } from "./request-payloads.js";
+import { fromGeneratedResponsePayload, } from "./response-payloads.js";
+export class HostProtocolFrameFactory {
+    nextRequestId = 1;
+    createRequestFrame(input) {
+        return {
+            frame_type: "request",
+            schema: SIDECAR_PROTOCOL_SCHEMA,
+            request_id: this.nextRequestId++,
+            ownership: input.ownership,
+            payload: input.payload,
+        };
+    }
+    createSidecarResponseFrame(input) {
+        return {
+            frame_type: "sidecar_response",
+            schema: SIDECAR_PROTOCOL_SCHEMA,
+            request_id: input.request.request_id,
+            ownership: input.request.ownership,
+            payload: input.payload,
+        };
+    }
+}
+export async function resolveSidecarRequestFramePayload(request, handler) {
+    try {
+        if (!handler) {
+            throw new Error(`no sidecar request handler registered for ${request.payload.type}`);
+        }
+        const payload = await handler(request);
+        if (!isMatchingSidecarResponsePayload(request.payload, payload)) {
+            throw new Error(`sidecar handler returned ${payload.type} for ${request.payload.type}`);
+        }
+        return payload;
+    }
+    catch (error) {
+        return errorSidecarResponsePayload(request.payload, error);
+    }
+}
+export function toGeneratedProtocolFrame(frame) {
+    switch (frame.frame_type) {
+        case "request":
+            return {
+                tag: "RequestFrame",
+                val: {
+                    schema: frame.schema,
+                    requestId: BigInt(frame.request_id),
+                    ownership: toGeneratedOwnershipScope(frame.ownership),
+                    payload: toGeneratedRequestPayload(frame.payload),
+                },
+            };
+        case "sidecar_response":
+            return {
+                tag: "SidecarResponseFrame",
+                val: {
+                    schema: frame.schema,
+                    requestId: BigInt(frame.request_id),
+                    ownership: toGeneratedOwnershipScope(frame.ownership),
+                    payload: toGeneratedSidecarResponsePayload(frame.payload),
+                },
+            };
+        case "response":
+        case "event":
+        case "sidecar_request":
+            throw new Error(`BARE encoding is only implemented for host-written frames, received ${frame.frame_type}`);
+    }
+}
+export function encodeBareProtocolFrame(frame) {
+    return Buffer.from(protocol.encodeProtocolFrame(toGeneratedProtocolFrame(frame)));
+}
+export function decodeBareProtocolFrame(payload) {
+    return fromGeneratedSidecarWrittenProtocolFrame(protocol.decodeProtocolFrame(toExactUint8Array(payload)));
+}
+export function encodeProtocolFramePayload(frame, codec) {
+    if (codec === "json") {
+        return encodeJsonFramePayload(frame);
+    }
+    return encodeBareProtocolFrame(frame);
+}
+export function decodeProtocolFramePayload(payload, codec) {
+    if (codec === "json") {
+        return decodeJsonFramePayload(payload);
+    }
+    return decodeBareProtocolFrame(payload);
+}
+export function classifySidecarWrittenProtocolFrame(frame) {
+    switch (frame.frame_type) {
+        case "response":
+            return {
+                kind: "response",
+                requestId: frame.request_id,
+                frame,
+            };
+        case "event":
+            return { kind: "event", frame };
+        case "sidecar_request":
+            return { kind: "sidecarRequest", frame };
+    }
+}
+export function fromGeneratedSidecarWrittenProtocolFrame(frame) {
+    switch (frame.tag) {
+        case "ResponseFrame":
+            return {
+                frame_type: "response",
+                schema: toLiveProtocolSchema(frame.val.schema),
+                request_id: bigIntToSafeNumber(frame.val.requestId, "response request id"),
+                ownership: fromGeneratedOwnershipScope(frame.val.ownership),
+                payload: fromGeneratedResponsePayload(frame.val.payload),
+            };
+        case "EventFrame":
+            return {
+                frame_type: "event",
+                schema: toLiveProtocolSchema(frame.val.schema),
+                ownership: fromGeneratedOwnershipScope(frame.val.ownership),
+                payload: fromGeneratedEventPayload(frame.val.payload),
+            };
+        case "SidecarRequestFrame":
+            return {
+                frame_type: "sidecar_request",
+                schema: toLiveProtocolSchema(frame.val.schema),
+                request_id: bigIntToSafeNumber(frame.val.requestId, "sidecar request id"),
+                ownership: fromGeneratedOwnershipScope(frame.val.ownership),
+                payload: fromGeneratedSidecarRequestPayload(frame.val.payload),
+            };
+        case "RequestFrame":
+        case "SidecarResponseFrame":
+            throw new Error(`unsupported BARE protocol frame tag: ${frame.tag}`);
+    }
+}
+export function toLiveProtocolSchema(schema) {
+    return validateSidecarProtocolSchema(schema);
+}

package/dist/protocol-maps.d.ts

@@ -0,0 +1,28 @@
+import * as protocol from "./generated-protocol.js";
+export type LiveGuestRuntimeKind = "java_script" | "python" | "web_assembly";
+export type LiveDisposeReason = "requested" | "connection_closed" | "host_shutdown";
+export type LiveRootFilesystemMode = "ephemeral" | "read_only";
+export type LiveRootFilesystemEntryKind = "file" | "directory" | "symlink";
+export type LiveRootFilesystemEntryEncoding = "utf8" | "base64";
+export type LiveWasmPermissionTier = "full" | "read-write" | "read-only" | "isolated";
+export type LivePermissionMode = "allow" | "ask" | "deny";
+export type LiveGuestFilesystemOperation = "read_file" | "write_file" | "create_dir" | "mkdir" | "exists" | "stat" | "lstat" | "read_dir" | "remove_file" | "remove_dir" | "rename" | "realpath" | "symlink" | "read_link" | "link" | "chmod" | "chown" | "utimes" | "truncate" | "pread";
+export type LiveVmLifecycleState = "creating" | "ready" | "disposing" | "disposed" | "failed";
+export type LiveStreamChannel = "stdout" | "stderr";
+export type LiveProcessSnapshotStatus = "running" | "exited" | "stopped";
+export type LiveSignalDispositionAction = "default" | "ignore" | "user";
+export declare function toGeneratedPermissionMode(mode: LivePermissionMode): protocol.PermissionMode;
+export declare function toGeneratedGuestRuntimeKind(runtime: LiveGuestRuntimeKind): protocol.GuestRuntimeKind;
+export declare function toGeneratedDisposeReason(reason: LiveDisposeReason): protocol.DisposeReason;
+export declare function toGeneratedRootFilesystemMode(mode: LiveRootFilesystemMode): protocol.RootFilesystemMode;
+export declare function toGeneratedRootFilesystemEntryKind(kind: LiveRootFilesystemEntryKind): protocol.RootFilesystemEntryKind;
+export declare function toGeneratedRootFilesystemEntryEncoding(encoding: LiveRootFilesystemEntryEncoding): protocol.RootFilesystemEntryEncoding;
+export declare function toGeneratedWasmPermissionTier(tier: LiveWasmPermissionTier): protocol.WasmPermissionTier;
+export declare function toGeneratedGuestFilesystemOperation(operation: LiveGuestFilesystemOperation): protocol.GuestFilesystemOperation;
+export declare function fromGeneratedVmLifecycleState(state: protocol.VmLifecycleState): LiveVmLifecycleState;
+export declare function fromGeneratedStreamChannel(channel: protocol.StreamChannel): LiveStreamChannel;
+export declare function fromGeneratedProcessSnapshotStatus(status: protocol.ProcessSnapshotStatus): LiveProcessSnapshotStatus;
+export declare function fromGeneratedSignalDispositionAction(action: protocol.SignalDispositionAction): LiveSignalDispositionAction;
+export declare function fromGeneratedRootFilesystemEntryKind(kind: protocol.RootFilesystemEntryKind): LiveRootFilesystemEntryKind;
+export declare function fromGeneratedRootFilesystemEntryEncoding(encoding: protocol.RootFilesystemEntryEncoding): LiveRootFilesystemEntryEncoding;
+export declare function fromGeneratedGuestFilesystemOperation(operation: protocol.GuestFilesystemOperation): LiveGuestFilesystemOperation;

package/dist/protocol-maps.js

@@ -0,0 +1,217 @@
+import * as protocol from "./generated-protocol.js";
+export function toGeneratedPermissionMode(mode) {
+    switch (mode) {
+        case "allow":
+            return protocol.PermissionMode.Allow;
+        case "ask":
+            return protocol.PermissionMode.Ask;
+        case "deny":
+            return protocol.PermissionMode.Deny;
+    }
+}
+export function toGeneratedGuestRuntimeKind(runtime) {
+    switch (runtime) {
+        case "java_script":
+            return protocol.GuestRuntimeKind.JavaScript;
+        case "python":
+            return protocol.GuestRuntimeKind.Python;
+        case "web_assembly":
+            return protocol.GuestRuntimeKind.WebAssembly;
+    }
+}
+export function toGeneratedDisposeReason(reason) {
+    switch (reason) {
+        case "requested":
+            return protocol.DisposeReason.Requested;
+        case "connection_closed":
+            return protocol.DisposeReason.ConnectionClosed;
+        case "host_shutdown":
+            return protocol.DisposeReason.HostShutdown;
+    }
+}
+export function toGeneratedRootFilesystemMode(mode) {
+    switch (mode) {
+        case "ephemeral":
+            return protocol.RootFilesystemMode.Ephemeral;
+        case "read_only":
+            return protocol.RootFilesystemMode.ReadOnly;
+    }
+}
+export function toGeneratedRootFilesystemEntryKind(kind) {
+    switch (kind) {
+        case "file":
+            return protocol.RootFilesystemEntryKind.File;
+        case "directory":
+            return protocol.RootFilesystemEntryKind.Directory;
+        case "symlink":
+            return protocol.RootFilesystemEntryKind.Symlink;
+    }
+}
+export function toGeneratedRootFilesystemEntryEncoding(encoding) {
+    switch (encoding) {
+        case "utf8":
+            return protocol.RootFilesystemEntryEncoding.UtF8;
+        case "base64":
+            return protocol.RootFilesystemEntryEncoding.BasE64;
+    }
+}
+export function toGeneratedWasmPermissionTier(tier) {
+    switch (tier) {
+        case "full":
+            return protocol.WasmPermissionTier.Full;
+        case "read-write":
+            return protocol.WasmPermissionTier.ReadWrite;
+        case "read-only":
+            return protocol.WasmPermissionTier.ReadOnly;
+        case "isolated":
+            return protocol.WasmPermissionTier.Isolated;
+    }
+}
+export function toGeneratedGuestFilesystemOperation(operation) {
+    switch (operation) {
+        case "read_file":
+            return protocol.GuestFilesystemOperation.ReadFile;
+        case "write_file":
+            return protocol.GuestFilesystemOperation.WriteFile;
+        case "create_dir":
+            return protocol.GuestFilesystemOperation.CreateDir;
+        case "mkdir":
+            return protocol.GuestFilesystemOperation.Mkdir;
+        case "exists":
+            return protocol.GuestFilesystemOperation.Exists;
+        case "stat":
+            return protocol.GuestFilesystemOperation.Stat;
+        case "lstat":
+            return protocol.GuestFilesystemOperation.Lstat;
+        case "read_dir":
+            return protocol.GuestFilesystemOperation.ReadDir;
+        case "remove_file":
+            return protocol.GuestFilesystemOperation.RemoveFile;
+        case "remove_dir":
+            return protocol.GuestFilesystemOperation.RemoveDir;
+        case "rename":
+            return protocol.GuestFilesystemOperation.Rename;
+        case "realpath":
+            return protocol.GuestFilesystemOperation.Realpath;
+        case "symlink":
+            return protocol.GuestFilesystemOperation.Symlink;
+        case "read_link":
+            return protocol.GuestFilesystemOperation.ReadLink;
+        case "link":
+            return protocol.GuestFilesystemOperation.Link;
+        case "chmod":
+            return protocol.GuestFilesystemOperation.Chmod;
+        case "chown":
+            return protocol.GuestFilesystemOperation.Chown;
+        case "utimes":
+            return protocol.GuestFilesystemOperation.Utimes;
+        case "truncate":
+            return protocol.GuestFilesystemOperation.Truncate;
+        case "pread":
+            return protocol.GuestFilesystemOperation.Pread;
+    }
+}
+export function fromGeneratedVmLifecycleState(state) {
+    switch (state) {
+        case protocol.VmLifecycleState.Creating:
+            return "creating";
+        case protocol.VmLifecycleState.Ready:
+            return "ready";
+        case protocol.VmLifecycleState.Disposing:
+            return "disposing";
+        case protocol.VmLifecycleState.Disposed:
+            return "disposed";
+        case protocol.VmLifecycleState.Failed:
+            return "failed";
+    }
+}
+export function fromGeneratedStreamChannel(channel) {
+    switch (channel) {
+        case protocol.StreamChannel.Stdout:
+            return "stdout";
+        case protocol.StreamChannel.Stderr:
+            return "stderr";
+    }
+}
+export function fromGeneratedProcessSnapshotStatus(status) {
+    switch (status) {
+        case protocol.ProcessSnapshotStatus.Running:
+            return "running";
+        case protocol.ProcessSnapshotStatus.Exited:
+            return "exited";
+        case protocol.ProcessSnapshotStatus.Stopped:
+            return "stopped";
+    }
+}
+export function fromGeneratedSignalDispositionAction(action) {
+    switch (action) {
+        case protocol.SignalDispositionAction.Default:
+            return "default";
+        case protocol.SignalDispositionAction.Ignore:
+            return "ignore";
+        case protocol.SignalDispositionAction.User:
+            return "user";
+    }
+}
+export function fromGeneratedRootFilesystemEntryKind(kind) {
+    switch (kind) {
+        case protocol.RootFilesystemEntryKind.File:
+            return "file";
+        case protocol.RootFilesystemEntryKind.Directory:
+            return "directory";
+        case protocol.RootFilesystemEntryKind.Symlink:
+            return "symlink";
+    }
+}
+export function fromGeneratedRootFilesystemEntryEncoding(encoding) {
+    switch (encoding) {
+        case protocol.RootFilesystemEntryEncoding.UtF8:
+            return "utf8";
+        case protocol.RootFilesystemEntryEncoding.BasE64:
+            return "base64";
+    }
+}
+export function fromGeneratedGuestFilesystemOperation(operation) {
+    switch (operation) {
+        case protocol.GuestFilesystemOperation.ReadFile:
+            return "read_file";
+        case protocol.GuestFilesystemOperation.WriteFile:
+            return "write_file";
+        case protocol.GuestFilesystemOperation.CreateDir:
+            return "create_dir";
+        case protocol.GuestFilesystemOperation.Mkdir:
+            return "mkdir";
+        case protocol.GuestFilesystemOperation.Exists:
+            return "exists";
+        case protocol.GuestFilesystemOperation.Stat:
+            return "stat";
+        case protocol.GuestFilesystemOperation.Lstat:
+            return "lstat";
+        case protocol.GuestFilesystemOperation.ReadDir:
+            return "read_dir";
+        case protocol.GuestFilesystemOperation.RemoveFile:
+            return "remove_file";
+        case protocol.GuestFilesystemOperation.RemoveDir:
+            return "remove_dir";
+        case protocol.GuestFilesystemOperation.Rename:
+            return "rename";
+        case protocol.GuestFilesystemOperation.Realpath:
+            return "realpath";
+        case protocol.GuestFilesystemOperation.Symlink:
+            return "symlink";
+        case protocol.GuestFilesystemOperation.ReadLink:
+            return "read_link";
+        case protocol.GuestFilesystemOperation.Link:
+            return "link";
+        case protocol.GuestFilesystemOperation.Chmod:
+            return "chmod";
+        case protocol.GuestFilesystemOperation.Chown:
+            return "chown";
+        case protocol.GuestFilesystemOperation.Utimes:
+            return "utimes";
+        case protocol.GuestFilesystemOperation.Truncate:
+            return "truncate";
+        case protocol.GuestFilesystemOperation.Pread:
+            return "pread";
+    }
+}

package/dist/protocol-schema.d.ts

@@ -0,0 +1,10 @@
+export declare const SIDECAR_PROTOCOL_SCHEMA: {
+    readonly name: "secure-exec-sidecar";
+    readonly version: 7;
+};
+export type LiveProtocolSchema = typeof SIDECAR_PROTOCOL_SCHEMA;
+export type ProtocolSchemaLike = {
+    name: string;
+    version: number;
+};
+export declare function validateSidecarProtocolSchema(schema: ProtocolSchemaLike): LiveProtocolSchema;

package/dist/protocol-schema.js

@@ -0,0 +1,11 @@
+export const SIDECAR_PROTOCOL_SCHEMA = {
+    name: "secure-exec-sidecar",
+    version: 7,
+};
+export function validateSidecarProtocolSchema(schema) {
+    if (schema.name !== SIDECAR_PROTOCOL_SCHEMA.name ||
+        schema.version !== SIDECAR_PROTOCOL_SCHEMA.version) {
+        throw new Error(`unsupported sidecar protocol schema ${schema.name}@${schema.version}`);
+    }
+    return SIDECAR_PROTOCOL_SCHEMA;
+}

package/dist/request-payloads.d.ts

@@ -0,0 +1,137 @@
+import { type LiveMountDescriptor, type LiveProjectedModuleDescriptor, type LiveSidecarPlacement, type LiveSoftwareDescriptor } from "./descriptors.js";
+import { type LiveExtEnvelope } from "./ext.js";
+import { type LiveRootFilesystemEntry, type LiveRootFilesystemEntryEncoding } from "./filesystem.js";
+import type * as protocol from "./generated-protocol.js";
+import type { CreateVmConfig } from "./generated/CreateVmConfig.js";
+import { type LivePermissionsPolicy } from "./permissions.js";
+import { type LiveDisposeReason, type LiveGuestFilesystemOperation, type LiveGuestRuntimeKind, type LiveRootFilesystemMode, type LiveWasmPermissionTier } from "./protocol-maps.js";
+export interface LiveRegisteredHostCallbackExample {
+    description: string;
+    input: unknown;
+}
+export interface LiveRegisteredHostCallbackDefinition {
+    description: string;
+    input_schema: unknown;
+    timeout_ms?: number;
+    examples?: LiveRegisteredHostCallbackExample[];
+}
+export type LiveRequestPayload = {
+    type: "authenticate";
+    client_name: string;
+    auth_token: string;
+    protocol_version: number;
+    bridge_version: number;
+} | {
+    type: "open_session";
+    placement: LiveSidecarPlacement;
+    metadata: Record<string, string>;
+} | {
+    type: "create_vm";
+    runtime: LiveGuestRuntimeKind;
+    config: CreateVmConfig;
+} | {
+    type: "configure_vm";
+    mounts: LiveMountDescriptor[];
+    software: LiveSoftwareDescriptor[];
+    permissions?: LivePermissionsPolicy;
+    module_access_cwd?: string;
+    instructions: string[];
+    projected_modules: LiveProjectedModuleDescriptor[];
+    command_permissions: Record<string, LiveWasmPermissionTier>;
+    loopback_exempt_ports?: number[];
+} | {
+    type: "register_host_callbacks";
+    name: string;
+    description: string;
+    command_aliases?: string[];
+    registry_command_aliases?: string[];
+    callbacks: Record<string, LiveRegisteredHostCallbackDefinition>;
+} | {
+    type: "dispose_vm";
+    reason: LiveDisposeReason;
+} | {
+    type: "bootstrap_root_filesystem";
+    entries: LiveRootFilesystemEntry[];
+} | {
+    type: "create_layer";
+} | {
+    type: "seal_layer";
+    layer_id: string;
+} | {
+    type: "import_snapshot";
+    entries: LiveRootFilesystemEntry[];
+} | {
+    type: "export_snapshot";
+    layer_id: string;
+} | {
+    type: "create_overlay";
+    mode?: LiveRootFilesystemMode;
+    upper_layer_id?: string;
+    lower_layer_ids: string[];
+} | {
+    type: "snapshot_root_filesystem";
+} | {
+    type: "guest_filesystem_call";
+    operation: LiveGuestFilesystemOperation;
+    path: string;
+    destination_path?: string;
+    target?: string;
+    content?: string;
+    encoding?: LiveRootFilesystemEntryEncoding;
+    recursive?: boolean;
+    mode?: number;
+    uid?: number;
+    gid?: number;
+    atime_ms?: number;
+    mtime_ms?: number;
+    len?: number;
+    offset?: number;
+} | {
+    type: "execute";
+    process_id: string;
+    command?: string;
+    runtime?: LiveGuestRuntimeKind;
+    entrypoint?: string;
+    args: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    wasm_permission_tier?: LiveWasmPermissionTier;
+} | {
+    type: "write_stdin";
+    process_id: string;
+    chunk: Uint8Array;
+} | {
+    type: "close_stdin";
+    process_id: string;
+} | {
+    type: "kill_process";
+    process_id: string;
+    signal: string;
+} | {
+    type: "get_process_snapshot";
+} | {
+    type: "find_listener";
+    host?: string;
+    port?: number;
+    path?: string;
+} | {
+    type: "find_bound_udp";
+    host?: string;
+    port?: number;
+} | {
+    type: "vm_fetch";
+    port: number;
+    method: string;
+    path: string;
+    headers_json: string;
+    body?: string;
+} | {
+    type: "get_signal_state";
+    process_id: string;
+} | {
+    type: "get_zombie_timer_count";
+} | {
+    type: "ext";
+    envelope: LiveExtEnvelope;
+};
+export declare function toGeneratedRequestPayload(payload: LiveRequestPayload): protocol.RequestPayload;