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

package/dist/sidecar-client.d.ts

@@ -0,0 +1,242 @@
+import { type LiveSidecarRequestPayload, type LiveSidecarResponsePayload } from "./callbacks.js";
+import type { MountConfigJsonObject } from "./descriptors.js";
+import { type LiveSidecarEventSelector } from "./event-buffer.js";
+import { type LiveRootFilesystemEntry } from "./filesystem.js";
+import type { CreateVmConfig } from "./generated/CreateVmConfig.js";
+import { type LiveFsPermissionRule, type LivePatternPermissionRule, type LivePermissionMode, type LivePermissionScope, type LiveRulePermissions } from "./permissions.js";
+import type { LiveGuestRuntimeKind, LiveWasmPermissionTier } from "./protocol-maps.js";
+import { type LiveEventFrame, type LiveSidecarRequestHandler, type LiveSidecarRequestFrame, type LiveSidecarResponseFrame, type ProtocolFramePayloadCodec } from "./protocol-frames.js";
+import { type LiveGuestFilesystemStat } from "./state.js";
+export { SidecarProcessError, SidecarProcessExited, } from "./process.js";
+export { SidecarEventBufferOverflow } from "./event-buffer.js";
+export declare const NATIVE_SIDECAR_FRAME_TIMEOUT_MS = 120000;
+type GuestRuntimeKind = Extract<LiveGuestRuntimeKind, "java_script" | "web_assembly">;
+type WasmPermissionTier = LiveWasmPermissionTier;
+export interface RootFilesystemEntry extends LiveRootFilesystemEntry {
+}
+export interface RootFilesystemLowerDescriptor {
+    kind: "snapshot" | "bundled_base_filesystem";
+    entries?: RootFilesystemEntry[];
+}
+export interface GuestFilesystemStat extends LiveGuestFilesystemStat {
+}
+export interface SidecarSocketStateEntry {
+    processId: string;
+    host?: string;
+    port?: number;
+    path?: string;
+}
+export interface SidecarSignalHandlerRegistration {
+    action: "default" | "ignore" | "user";
+    mask: number[];
+    flags: number;
+}
+export interface SidecarSignalState {
+    processId: string;
+    handlers: Map<number, SidecarSignalHandlerRegistration>;
+}
+export interface SidecarProcessSnapshotEntry {
+    processId: string;
+    pid: number;
+    ppid: number;
+    pgid: number;
+    sid: number;
+    driver: string;
+    command: string;
+    args: string[];
+    cwd: string;
+    status: "running" | "exited" | "stopped";
+    exitCode: number | null;
+}
+export interface SidecarZombieTimerCount {
+    count: number;
+}
+export interface SidecarRegisteredHostCallbackExample {
+    description: string;
+    input: unknown;
+}
+export interface SidecarRegisteredHostCallbackDefinition {
+    description: string;
+    inputSchema: unknown;
+    timeoutMs?: number;
+    examples?: SidecarRegisteredHostCallbackExample[];
+}
+export interface ExtEnvelope {
+    namespace: string;
+    payload: Uint8Array;
+}
+export type SidecarRequestPayload = LiveSidecarRequestPayload;
+export type SidecarResponsePayload = LiveSidecarResponsePayload;
+type EventFrame = LiveEventFrame;
+export type SidecarEventSelector = LiveSidecarEventSelector;
+export type SidecarRequestFrame = LiveSidecarRequestFrame;
+export type SidecarResponseFrame = LiveSidecarResponseFrame;
+type NativeTransportPayloadCodec = ProtocolFramePayloadCodec;
+export type SidecarRequestHandler = LiveSidecarRequestHandler;
+export interface NativeSidecarSpawnOptions {
+    cwd: string;
+    command?: string;
+    args?: string[];
+    frameTimeoutMs?: number;
+    eventBufferCapacity?: number;
+    payloadCodec?: NativeTransportPayloadCodec;
+}
+export interface AuthenticatedSession {
+    connectionId: string;
+    sessionId: string;
+}
+export interface CreatedVm {
+    vmId: string;
+}
+export interface SidecarSessionState {
+    sessionId: string;
+    agentType: string;
+    processId: string;
+    pid?: number;
+    closed: boolean;
+    modes?: unknown;
+    configOptions: unknown[];
+    agentCapabilities?: unknown;
+    agentInfo?: unknown;
+}
+export interface SidecarMountPluginDescriptor {
+    id: string;
+    config?: MountConfigJsonObject;
+}
+export interface SidecarMountDescriptor {
+    guestPath: string;
+    readOnly: boolean;
+    plugin: SidecarMountPluginDescriptor;
+}
+export interface SidecarSoftwareDescriptor {
+    packageName: string;
+    root: string;
+}
+export type SidecarPermissionMode = LivePermissionMode;
+export interface SidecarFsPermissionRule extends LiveFsPermissionRule {
+}
+export interface SidecarPatternPermissionRule extends LivePatternPermissionRule {
+}
+export interface SidecarRulePermissions<TRule> extends LiveRulePermissions<TRule> {
+}
+export type SidecarPermissionScope<TRule> = LivePermissionScope<TRule>;
+export interface SidecarPermissionsPolicy {
+    fs?: SidecarPermissionScope<SidecarFsPermissionRule>;
+    network?: SidecarPermissionScope<SidecarPatternPermissionRule>;
+    childProcess?: SidecarPermissionScope<SidecarPatternPermissionRule>;
+    process?: SidecarPermissionScope<SidecarPatternPermissionRule>;
+    env?: SidecarPermissionScope<SidecarPatternPermissionRule>;
+    tool?: SidecarPermissionScope<SidecarPatternPermissionRule>;
+}
+export interface SidecarProjectedModuleDescriptor {
+    packageName: string;
+    entrypoint: string;
+}
+export declare class NativeSidecarProcessClient {
+    private readonly protocolClient;
+    private constructor();
+    static spawn(options: NativeSidecarSpawnOptions): NativeSidecarProcessClient;
+    setSidecarRequestHandler(handler: SidecarRequestHandler | null): void;
+    onEvent(handler: (event: EventFrame) => void): () => void;
+    authenticateAndOpenSession(sessionMetadata?: Record<string, string>): Promise<AuthenticatedSession>;
+    createVm(session: AuthenticatedSession, options: {
+        runtime: GuestRuntimeKind;
+        config: CreateVmConfig;
+    }): Promise<CreatedVm>;
+    extensionRequest(session: AuthenticatedSession, vm: CreatedVm, envelope: ExtEnvelope): Promise<ExtEnvelope>;
+    configureVm(session: AuthenticatedSession, vm: CreatedVm, options: {
+        mounts?: SidecarMountDescriptor[];
+        software?: SidecarSoftwareDescriptor[];
+        permissions?: SidecarPermissionsPolicy;
+        moduleAccessCwd?: string;
+        instructions?: string[];
+        projectedModules?: SidecarProjectedModuleDescriptor[];
+        commandPermissions?: Record<string, WasmPermissionTier>;
+        loopbackExemptPorts?: number[];
+    }): Promise<void>;
+    registerHostCallbacks(session: AuthenticatedSession, vm: CreatedVm, registration: {
+        name: string;
+        description: string;
+        commandAliases?: string[];
+        registryCommandAliases?: string[];
+        callbacks: Record<string, SidecarRegisteredHostCallbackDefinition>;
+    }): Promise<{
+        registration: string;
+        commandCount: number;
+    }>;
+    createLayer(session: AuthenticatedSession, vm: CreatedVm): Promise<string>;
+    sealLayer(session: AuthenticatedSession, vm: CreatedVm, layerId: string): Promise<string>;
+    importSnapshot(session: AuthenticatedSession, vm: CreatedVm, entries: RootFilesystemEntry[]): Promise<string>;
+    exportSnapshot(session: AuthenticatedSession, vm: CreatedVm, layerId: string): Promise<RootFilesystemEntry[]>;
+    createOverlay(session: AuthenticatedSession, vm: CreatedVm, options: {
+        mode?: "ephemeral" | "read_only";
+        upperLayerId?: string;
+        lowerLayerIds: string[];
+    }): Promise<string>;
+    bootstrapRootFilesystem(session: AuthenticatedSession, vm: CreatedVm, entries: RootFilesystemEntry[]): Promise<void>;
+    snapshotRootFilesystem(session: AuthenticatedSession, vm: CreatedVm): Promise<RootFilesystemEntry[]>;
+    readFile(session: AuthenticatedSession, vm: CreatedVm, path: string): Promise<Uint8Array>;
+    pread(session: AuthenticatedSession, vm: CreatedVm, path: string, offset: number, length: number): Promise<Uint8Array>;
+    writeFile(session: AuthenticatedSession, vm: CreatedVm, path: string, content: string | Uint8Array): Promise<void>;
+    mkdir(session: AuthenticatedSession, vm: CreatedVm, path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    readdir(session: AuthenticatedSession, vm: CreatedVm, path: string): Promise<string[]>;
+    exists(session: AuthenticatedSession, vm: CreatedVm, path: string): Promise<boolean>;
+    stat(session: AuthenticatedSession, vm: CreatedVm, path: string, options?: {
+        dereference?: boolean;
+    }): Promise<GuestFilesystemStat>;
+    lstat(session: AuthenticatedSession, vm: CreatedVm, path: string): Promise<GuestFilesystemStat>;
+    rename(session: AuthenticatedSession, vm: CreatedVm, fromPath: string, toPath: string): Promise<void>;
+    realpath(session: AuthenticatedSession, vm: CreatedVm, path: string): Promise<string>;
+    removeFile(session: AuthenticatedSession, vm: CreatedVm, path: string): Promise<void>;
+    removeDir(session: AuthenticatedSession, vm: CreatedVm, path: string): Promise<void>;
+    symlink(session: AuthenticatedSession, vm: CreatedVm, target: string, linkPath: string): Promise<void>;
+    readLink(session: AuthenticatedSession, vm: CreatedVm, path: string): Promise<string>;
+    link(session: AuthenticatedSession, vm: CreatedVm, fromPath: string, toPath: string): Promise<void>;
+    chmod(session: AuthenticatedSession, vm: CreatedVm, path: string, mode: number): Promise<void>;
+    chown(session: AuthenticatedSession, vm: CreatedVm, path: string, uid: number, gid: number): Promise<void>;
+    utimes(session: AuthenticatedSession, vm: CreatedVm, path: string, atimeMs: number, mtimeMs: number): Promise<void>;
+    truncate(session: AuthenticatedSession, vm: CreatedVm, path: string, length: number): Promise<void>;
+    disposeVm(session: AuthenticatedSession, vm: CreatedVm): Promise<void>;
+    execute(session: AuthenticatedSession, vm: CreatedVm, options: {
+        processId: string;
+        command?: string;
+        runtime?: GuestRuntimeKind;
+        entrypoint?: string;
+        args?: string[];
+        env?: Record<string, string>;
+        cwd?: string;
+        wasmPermissionTier?: WasmPermissionTier;
+    }): Promise<{
+        pid: number | null;
+    }>;
+    writeStdin(session: AuthenticatedSession, vm: CreatedVm, processId: string, chunk: string | Uint8Array): Promise<void>;
+    closeStdin(session: AuthenticatedSession, vm: CreatedVm, processId: string): Promise<void>;
+    killProcess(session: AuthenticatedSession, vm: CreatedVm, processId: string, signal?: string): Promise<void>;
+    findListener(session: AuthenticatedSession, vm: CreatedVm, request: {
+        host?: string;
+        port?: number;
+        path?: string;
+    }): Promise<SidecarSocketStateEntry | null>;
+    getProcessSnapshot(session: AuthenticatedSession, vm: CreatedVm): Promise<SidecarProcessSnapshotEntry[]>;
+    findBoundUdp(session: AuthenticatedSession, vm: CreatedVm, request: {
+        host?: string;
+        port?: number;
+    }): Promise<SidecarSocketStateEntry | null>;
+    vmFetch(session: AuthenticatedSession, vm: CreatedVm, request: {
+        port: number;
+        method: string;
+        path: string;
+        headersJson: string;
+        body?: string;
+    }): Promise<string>;
+    getSignalState(session: AuthenticatedSession, vm: CreatedVm, processId: string): Promise<SidecarSignalState>;
+    getZombieTimerCount(session: AuthenticatedSession, vm: CreatedVm): Promise<SidecarZombieTimerCount>;
+    waitForEvent(matcher: SidecarEventSelector | ((event: EventFrame) => boolean), timeoutMs?: number, options?: {
+        signal?: AbortSignal;
+    }): Promise<EventFrame>;
+    dispose(): Promise<void>;
+    private sendRequest;
+    private guestFilesystemCall;
+}