@cjhyy/code-shell-server 0.9.8 → 0.9.10

package/dist/panels/process-service.js

@@ -0,0 +1,501 @@
+import { spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { access, realpath, stat } from "node:fs/promises";
+import { basename, delimiter, extname, join } from "node:path";
+import { killProcessGroup } from "@cjhyy/code-shell-core/extension";
+const EXECUTABLE_NAME = /^[a-zA-Z0-9][a-zA-Z0-9._+-]{0,127}$/;
+const FILE_ARGUMENT_NAME = /^--[a-zA-Z][a-zA-Z0-9-]{0,63}$/;
+const MAX_ARGUMENTS = 256;
+const MAX_ARGUMENT_LENGTH = 8_192;
+const MAX_ARGUMENT_BYTES = 64 * 1024;
+const MAX_CONCURRENT_PROCESSES = 3;
+const MAX_FILE_ARGUMENTS = 8;
+const MAX_EVENT_CHARS = 16_384;
+const MAX_PROCESS_OUTPUT_BYTES = 4 * 1024 * 1024;
+const PROCESS_LIFETIME_MS = 24 * 60 * 60 * 1_000;
+export function panelProcessInfo(platform = process.platform, arch = process.arch, report = process.report?.getReport()) {
+    if (platform !== "linux")
+        return { platform, arch };
+    const header = report && typeof report === "object"
+        ? report.header
+        : undefined;
+    const libc = typeof header?.glibcVersionRuntime === "string" && header.glibcVersionRuntime
+        ? "glibc"
+        : "musl";
+    return { platform, arch, libc };
+}
+async function executableFingerprint(path) {
+    const info = await stat(path);
+    if (!info.isFile())
+        throw new Error("resolved executable is no longer a regular file");
+    return createHash("sha256")
+        .update(String(info.dev))
+        .update("\0")
+        .update(String(info.ino))
+        .update("\0")
+        .update(String(info.size))
+        .update("\0")
+        .update(String(info.mtimeMs))
+        .update("\0")
+        .update(String(info.mode))
+        .digest("hex");
+}
+export function panelExecutableDirectories(managedBin, options = {}) {
+    const platform = options.platform ?? process.platform;
+    const env = options.env ?? process.env;
+    const directories = [managedBin];
+    if (platform === "darwin") {
+        if (options.home)
+            directories.push(join(options.home, ".local", "bin"));
+        directories.push("/opt/homebrew/bin", "/usr/local/bin");
+    }
+    else if (platform === "linux") {
+        if (options.home)
+            directories.push(join(options.home, ".local", "bin"));
+        directories.push("/home/linuxbrew/.linuxbrew/bin", "/usr/local/bin");
+    }
+    else if (platform === "win32") {
+        const localAppData = env.LOCALAPPDATA || (options.home ? join(options.home, "AppData", "Local") : "");
+        if (localAppData) {
+            directories.push(join(localAppData, "Microsoft", "WinGet", "Links"), join(localAppData, "Microsoft", "WindowsApps"));
+        }
+    }
+    return [...new Set(directories.filter(Boolean))];
+}
+function safeProcessEnv(source, extraPathDirectories = []) {
+    const allowed = [
+        "PATH",
+        "HOME",
+        "USERPROFILE",
+        "TMPDIR",
+        "TMP",
+        "TEMP",
+        "LANG",
+        "LC_ALL",
+        "SystemRoot",
+        "WINDIR",
+        "SSL_CERT_FILE",
+        "SSL_CERT_DIR",
+    ];
+    const safe = Object.fromEntries(allowed.flatMap((key) => (source[key] === undefined ? [] : [[key, source[key]]])));
+    const currentPath = safe.PATH ?? "";
+    safe.PATH = [
+        ...new Set([
+            ...extraPathDirectories.filter(Boolean),
+            ...currentPath.split(delimiter).filter(Boolean),
+        ]),
+    ].join(delimiter);
+    return safe;
+}
+function executableCandidates(name, platform, env) {
+    if (platform !== "win32" || extname(name))
+        return [name];
+    const pathExt = env.PATHEXT || ".EXE;.CMD;.BAT;.COM";
+    return pathExt
+        .split(";")
+        .filter(Boolean)
+        .map((extension) => `${name}${extension.toLowerCase()}`);
+}
+export async function resolvePanelExecutable(name, options = {}) {
+    if (!EXECUTABLE_NAME.test(name))
+        throw new Error("invalid executable name");
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const pathValue = env.PATH || "";
+    const directories = [
+        ...(options.extraPathDirectories ?? []),
+        ...pathValue.split(delimiter).filter(Boolean),
+    ];
+    for (const directory of [...new Set(directories)]) {
+        for (const candidateName of executableCandidates(name, platform, env)) {
+            const candidate = join(directory, candidateName);
+            try {
+                await access(candidate, platform === "win32" ? constants.F_OK : constants.X_OK);
+                const info = await stat(candidate);
+                if (info.isFile())
+                    return await realpath(candidate);
+            }
+            catch {
+                // Keep searching the remaining PATH entries.
+            }
+        }
+    }
+    return null;
+}
+function validateArguments(raw) {
+    if (!Array.isArray(raw) || raw.length > MAX_ARGUMENTS) {
+        throw new Error(`process.spawn accepts at most ${MAX_ARGUMENTS} arguments`);
+    }
+    const args = raw.map((value) => {
+        if (typeof value !== "string" || value.length > MAX_ARGUMENT_LENGTH || value.includes("\0")) {
+            throw new Error("process.spawn arguments must be bounded strings without NUL bytes");
+        }
+        return value;
+    });
+    if (Buffer.byteLength(JSON.stringify(args), "utf8") > MAX_ARGUMENT_BYTES) {
+        throw new Error("process.spawn arguments are too large");
+    }
+    return args;
+}
+function validateFileArgumentHandles(raw) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw) || raw.length > MAX_FILE_ARGUMENTS) {
+        throw new Error(`process.spawn accepts at most ${MAX_FILE_ARGUMENTS} sealed file arguments`);
+    }
+    const handles = raw.map((value) => {
+        if (typeof value !== "string" || !value || value.length > 160) {
+            throw new Error("process.spawn sealed file argument handles must be bounded strings");
+        }
+        return value;
+    });
+    if (new Set(handles).size !== handles.length) {
+        throw new Error("process.spawn sealed file argument handles must be unique");
+    }
+    return handles;
+}
+export class PanelAppProcessService {
+    options;
+    executables = new Map();
+    directories = new Map();
+    fileArguments = new Map();
+    processes = new Map();
+    approvedExecutables = new Set();
+    guestEpochs = new Map();
+    reservations = new Map();
+    closed = false;
+    constructor(options) {
+        this.options = options;
+    }
+    epoch(owner) {
+        if (this.closed)
+            throw new Error("Panel process service is closed");
+        return this.guestEpochs.get(owner.guestId) ?? 0;
+    }
+    assertLive(owner, epoch) {
+        if (this.closed || (this.guestEpochs.get(owner.guestId) ?? 0) !== epoch) {
+            throw new Error("Panel App process owner is no longer authorized");
+        }
+    }
+    async authorize(owner, epoch) {
+        this.assertLive(owner, epoch);
+        if (this.options.isOwnerAuthorized && !(await this.options.isOwnerAuthorized(owner))) {
+            throw new Error("Panel App process owner is no longer authorized");
+        }
+        this.assertLive(owner, epoch);
+    }
+    async findExecutable(owner, params) {
+        owner = { ...owner };
+        const epoch = this.epoch(owner);
+        await this.authorize(owner, epoch);
+        const name = params?.name;
+        if (typeof name !== "string" || !EXECUTABLE_NAME.test(name)) {
+            throw new Error("process.find requires a simple executable name");
+        }
+        const path = await resolvePanelExecutable(name, {
+            ...this.options,
+            extraPathDirectories: this.options.extraPathDirectories?.(),
+        });
+        await this.authorize(owner, epoch);
+        this.assertLive(owner, epoch);
+        if (!path)
+            return { available: false, name };
+        const handle = randomUUID();
+        this.executables.set(handle, { guestId: owner.guestId, name, path });
+        return { available: true, name, handle };
+    }
+    async grantDirectory(owner, path) {
+        owner = { ...owner };
+        const epoch = this.epoch(owner);
+        await this.authorize(owner, epoch);
+        const resolved = await realpath(path);
+        await this.authorize(owner, epoch);
+        const info = await stat(resolved);
+        await this.authorize(owner, epoch);
+        this.assertLive(owner, epoch);
+        if (!info.isDirectory())
+            throw new Error("selected process directory is not a directory");
+        const handle = randomUUID();
+        this.directories.set(handle, { guestId: owner.guestId, path: resolved });
+        return { handle, path: resolved, name: basename(resolved) || resolved };
+    }
+    executableName(owner, handle) {
+        this.epoch(owner);
+        if (typeof handle !== "string")
+            throw new Error("executable handle is required");
+        const executable = this.executables.get(handle);
+        if (!executable || executable.guestId !== owner.guestId) {
+            throw new Error("executable handle is invalid or belongs to another Panel App");
+        }
+        return executable.name;
+    }
+    async grantFileArgument(owner, input) {
+        owner = { ...owner };
+        const epoch = this.epoch(owner);
+        await this.authorize(owner, epoch);
+        if (typeof input.executableHandle !== "string") {
+            throw new Error("sealed file arguments require an executable handle");
+        }
+        const executable = this.executables.get(input.executableHandle);
+        if (!executable || executable.guestId !== owner.guestId) {
+            throw new Error("executable handle is invalid or belongs to another Panel App");
+        }
+        if (typeof input.argumentName !== "string" || !FILE_ARGUMENT_NAME.test(input.argumentName)) {
+            throw new Error("sealed file arguments require a simple long-option name");
+        }
+        const resolved = await realpath(input.path);
+        await this.authorize(owner, epoch);
+        const info = await stat(resolved);
+        await this.authorize(owner, epoch);
+        this.assertLive(owner, epoch);
+        if (!info.isFile())
+            throw new Error("sealed process input is not a file");
+        const handle = randomUUID();
+        this.fileArguments.set(handle, {
+            guestId: owner.guestId,
+            executablePath: executable.path,
+            argumentName: input.argumentName,
+            path: resolved,
+            cleanup: input.cleanup ?? (() => undefined),
+        });
+        return { handle };
+    }
+    directoryPath(owner, handle) {
+        this.epoch(owner);
+        if (typeof handle !== "string")
+            throw new Error("directory handle is required");
+        const grant = this.directories.get(handle);
+        if (!grant || grant.guestId !== owner.guestId) {
+            throw new Error("directory handle is invalid or belongs to another Panel App");
+        }
+        return grant.path;
+    }
+    async start(owner, params) {
+        owner = { ...owner };
+        const epoch = this.epoch(owner);
+        const input = params;
+        if (!input || typeof input.executableHandle !== "string") {
+            throw new Error("process.spawn requires an executable handle from process.find");
+        }
+        const executable = this.executables.get(input.executableHandle);
+        if (!executable || executable.guestId !== owner.guestId) {
+            throw new Error("executable handle is invalid or belongs to another Panel App");
+        }
+        const cwd = this.directoryPath(owner, input.directoryHandle);
+        const rawArgs = validateArguments(input.args);
+        const fileArgumentHandles = validateFileArgumentHandles(input.fileArgumentHandles);
+        const sealedArgs = [];
+        for (const handle of fileArgumentHandles) {
+            const grant = this.fileArguments.get(handle);
+            if (!grant || grant.guestId !== owner.guestId) {
+                throw new Error("sealed file argument handle is invalid or belongs to another Panel App");
+            }
+            if (grant.executablePath !== executable.path) {
+                throw new Error("sealed file argument is bound to a different executable");
+            }
+            sealedArgs.push(grant.argumentName, grant.path);
+        }
+        const args = validateArguments([...sealedArgs, ...rawArgs]);
+        const active = [...this.processes.values()].filter((process) => process.guestId === owner.guestId).length;
+        const reserved = this.reservations.get(owner.guestId) ?? 0;
+        if (active + reserved >= MAX_CONCURRENT_PROCESSES) {
+            throw new Error(`Panel App may run at most ${MAX_CONCURRENT_PROCESSES} processes at once`);
+        }
+        // Admission is reserved before the first await, including a user's approval dialog.
+        this.reservations.set(owner.guestId, reserved + 1);
+        try {
+            await this.authorize(owner, epoch);
+            const scope = {
+                appId: owner.appId,
+                revision: owner.revision,
+                executablePath: executable.path,
+                executableFingerprint: await executableFingerprint(executable.path),
+            };
+            await this.authorize(owner, epoch);
+            const guestScoped = this.options.approvalScope === "guest";
+            const approvalKey = (guestScoped ? `${owner.guestId}\0${epoch}\0` : "") +
+                `${scope.appId}\0${scope.revision}\0${scope.executablePath}\0${scope.executableFingerprint}`;
+            let approved = this.approvedExecutables.has(approvalKey);
+            if (!approved && !guestScoped && this.options.isExecutionApproved) {
+                approved = await this.options.isExecutionApproved(scope).catch(() => false);
+                await this.authorize(owner, epoch);
+            }
+            if (!approved) {
+                const allowed = await this.options.confirmExecution({
+                    guestId: owner.guestId,
+                    appId: owner.appId,
+                    appTitle: owner.appTitle,
+                    executable: executable.name,
+                    executablePath: executable.path,
+                });
+                await this.authorize(owner, epoch);
+                if (!allowed)
+                    throw new Error(`User denied running ${executable.name}`);
+                if (!guestScoped) {
+                    await this.options.rememberExecutionApproval?.(scope).catch(() => undefined);
+                    await this.authorize(owner, epoch);
+                }
+            }
+            // A binary replaced while a dialog was open must earn a new approval.
+            if ((await executableFingerprint(executable.path)) !== scope.executableFingerprint) {
+                throw new Error("resolved executable changed; find it and approve it again");
+            }
+            await this.authorize(owner, epoch);
+            const env = safeProcessEnv(this.options.env ?? process.env, this.options.extraPathDirectories?.() ?? []);
+            this.assertLive(owner, epoch);
+            if (this.executables.get(input.executableHandle) !== executable ||
+                this.directoryPath(owner, input.directoryHandle) !== cwd) {
+                throw new Error("Panel App process handles were revoked");
+            }
+            this.approvedExecutables.add(approvalKey);
+            const processId = randomUUID();
+            const child = spawn(executable.path, args, {
+                cwd,
+                detached: process.platform !== "win32",
+                env,
+                shell: false,
+                stdio: ["ignore", "pipe", "pipe"],
+                windowsHide: true,
+            });
+            const sendOutput = (stream, chunk) => {
+                const running = this.processes.get(processId);
+                if (running?.child !== child || running.outputTruncated)
+                    return;
+                const text = String(chunk);
+                running.outputBytes += Buffer.byteLength(text, "utf8");
+                if (running.outputBytes > MAX_PROCESS_OUTPUT_BYTES) {
+                    running.outputTruncated = true;
+                    owner.send("process.output", {
+                        processId,
+                        stream: "stderr",
+                        text: `Process output exceeded ${MAX_PROCESS_OUTPUT_BYTES} bytes; CodeShell stopped it.\n`,
+                    });
+                    this.terminate(running);
+                    return;
+                }
+                for (let offset = 0; offset < text.length; offset += MAX_EVENT_CHARS) {
+                    owner.send("process.output", {
+                        processId,
+                        stream,
+                        text: text.slice(offset, offset + MAX_EVENT_CHARS),
+                    });
+                }
+            };
+            child.stdout?.on("data", (chunk) => sendOutput("stdout", chunk));
+            child.stderr?.on("data", (chunk) => sendOutput("stderr", chunk));
+            child.once("error", (error) => {
+                if (this.processes.get(processId)?.child !== child)
+                    return;
+                owner.send("process.output", {
+                    processId,
+                    stream: "stderr",
+                    text: `${error.message}\n`,
+                });
+            });
+            const lifetime = setTimeout(() => {
+                const running = this.processes.get(processId);
+                if (running)
+                    this.terminate(running);
+            }, PROCESS_LIFETIME_MS);
+            lifetime.unref();
+            this.processes.set(processId, {
+                guestId: owner.guestId,
+                child,
+                lifetime,
+                outputBytes: 0,
+                outputTruncated: false,
+            });
+            child.once("close", (code, signal) => {
+                clearTimeout(lifetime);
+                if (this.processes.get(processId)?.child !== child)
+                    return;
+                this.processes.delete(processId);
+                owner.send("process.exit", { processId, code, signal });
+            });
+            return { processId, executable: executable.name };
+        }
+        finally {
+            const remaining = (this.reservations.get(owner.guestId) ?? 1) - 1;
+            if (remaining)
+                this.reservations.set(owner.guestId, remaining);
+            else
+                this.reservations.delete(owner.guestId);
+        }
+    }
+    cancel(owner, params) {
+        const processId = params?.processId;
+        if (typeof processId !== "string")
+            throw new Error("process.cancel requires processId");
+        const running = this.processes.get(processId);
+        if (!running || running.guestId !== owner.guestId)
+            return { cancelled: false };
+        this.terminate(running);
+        return { cancelled: true };
+    }
+    revokeGuest(guestId) {
+        this.guestEpochs.set(guestId, (this.guestEpochs.get(guestId) ?? 0) + 1);
+        if (this.options.approvalScope === "guest") {
+            for (const key of this.approvedExecutables) {
+                if (key.startsWith(`${guestId}\0`))
+                    this.approvedExecutables.delete(key);
+            }
+        }
+        for (const [handle, grant] of this.executables) {
+            if (grant.guestId === guestId)
+                this.executables.delete(handle);
+        }
+        for (const [handle, grant] of this.directories) {
+            if (grant.guestId === guestId)
+                this.directories.delete(handle);
+        }
+        for (const [processId, running] of this.processes) {
+            if (running.guestId !== guestId)
+                continue;
+            clearTimeout(running.lifetime);
+            this.terminate(running);
+            this.processes.delete(processId);
+        }
+        for (const [handle, grant] of this.fileArguments) {
+            if (grant.guestId !== guestId)
+                continue;
+            this.fileArguments.delete(handle);
+            try {
+                grant.cleanup();
+            }
+            catch {
+                // Credential-backed temporary inputs are best-effort cleanup only.
+            }
+        }
+    }
+    /** Permanently shut down all guests, including operations awaiting approval. */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        const guests = new Set([
+            ...this.guestEpochs.keys(),
+            ...this.reservations.keys(),
+            ...[...this.executables.values()].map((grant) => grant.guestId),
+            ...[...this.directories.values()].map((grant) => grant.guestId),
+            ...[...this.fileArguments.values()].map((grant) => grant.guestId),
+            ...[...this.processes.values()].map((running) => running.guestId),
+        ]);
+        for (const guestId of guests)
+            this.revokeGuest(guestId);
+        this.approvedExecutables.clear();
+    }
+    terminate(running) {
+        const pid = running.child.pid;
+        if (typeof pid === "number" && pid > 1) {
+            void killProcessGroup(pid);
+            return;
+        }
+        try {
+            running.child.kill("SIGTERM");
+        }
+        catch {
+            // The process already exited.
+        }
+    }
+}

package/dist/panels/runtime-services.d.ts

@@ -0,0 +1,24 @@
+export interface PanelRuntimeScope {
+    appId: string;
+    cwd: string;
+    projectPath: string;
+    permissions: readonly string[];
+    /** Checks the live owner, its project binding, and the installed revision. */
+    isAuthorized: () => Promise<boolean>;
+}
+/** Node-only implementation of the existing Panel SDK's bounded disk operations. */
+export declare class PanelRuntimeServices {
+    private readonly roots;
+    private readonly dataDir;
+    constructor(options: {
+        dataDir: string;
+    });
+    call(input: PanelRuntimeScope, method: string, params?: unknown): Promise<unknown>;
+    private storage;
+    private root;
+    private openPath;
+    private read;
+    private workspace;
+    private ensureDirectory;
+    private write;
+}