@cjhyy/code-shell-server 0.9.8 → 0.9.9

package/dist/project-runtime/registry.d.ts

@@ -0,0 +1,54 @@
+import { renameSync } from "node:fs";
+import type { ProjectRuntimeRecord } from "./types.js";
+export type ProjectStatus = "stopped" | "starting" | "running" | "stopping" | "error";
+export interface StoredProject extends ProjectRuntimeRecord {
+    name: string;
+    status: ProjectStatus;
+    createdAt: number;
+    updatedAt: number;
+    error?: string;
+}
+export interface ProjectView {
+    id: string;
+    name: string;
+    status: ProjectStatus;
+    generation: number;
+    createdAt: number;
+    updatedAt: number;
+    error?: string;
+}
+export declare class ProjectRegistryError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/** The control plane owns identifiers and credentials; callers receive explicit public views. */
+export declare class ProjectRegistry {
+    private readonly now;
+    private readonly io;
+    private readonly directory;
+    private readonly file;
+    private readonly marker;
+    private data;
+    private readonly controllerLock;
+    private diskDigest;
+    private markerEstablished;
+    constructor(dataDir: string, now?: () => number, io?: {
+        rename?: typeof renameSync;
+    });
+    /** Release the single-controller lease on shutdown or startup failure. */
+    close(): void;
+    get installationId(): string;
+    private validate;
+    private assertStorage;
+    private write;
+    all(): StoredProject[];
+    list(username: string): ProjectView[];
+    get(username: string, id: string): StoredProject;
+    create(username: string, name: unknown): StoredProject;
+    update(id: string, patch: {
+        status: ProjectStatus;
+        generation?: number;
+        error?: string;
+    }): StoredProject;
+}
+export declare function projectView(project: StoredProject): ProjectView;

package/dist/project-runtime/registry.js

@@ -0,0 +1,286 @@
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { constants, chmodSync, closeSync, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { join, resolve } from "node:path";
+import { acquireProjectControllerLock } from "./lock.js";
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+const TOKEN = /^[A-Za-z0-9_-]{43}$/;
+const STATUSES = new Set(["stopped", "starting", "running", "stopping", "error"]);
+const MAX_STORE_BYTES = 512 * 1024;
+const digest = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function privateFileBytes(file, maximum = MAX_STORE_BYTES) {
+    const entry = lstatSync(file);
+    if (!entry.isFile() ||
+        entry.isSymbolicLink() ||
+        entry.nlink !== 1 ||
+        entry.size > maximum ||
+        entry.mode & 0o077)
+        throw new Error("Project registry file must be a bounded private regular file.");
+    const fd = openSync(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const opened = fstatSync(fd);
+        if (!opened.isFile() ||
+            opened.ino !== entry.ino ||
+            opened.dev !== entry.dev ||
+            opened.nlink !== 1 ||
+            opened.size > maximum)
+            throw new Error("Project registry file changed while opening it.");
+        const bytes = Buffer.alloc(maximum + 1);
+        let size = 0;
+        while (size < bytes.length) {
+            const count = readSync(fd, bytes, size, bytes.length - size, size);
+            if (!count)
+                break;
+            size += count;
+        }
+        if (size > maximum)
+            throw new Error("Project registry file is too large.");
+        return bytes.subarray(0, size);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export class ProjectRegistryError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+/** The control plane owns identifiers and credentials; callers receive explicit public views. */
+export class ProjectRegistry {
+    now;
+    io;
+    directory;
+    file;
+    marker;
+    data;
+    controllerLock;
+    diskDigest;
+    markerEstablished = false;
+    constructor(dataDir, now = Date.now, io = {}) {
+        this.now = now;
+        this.io = io;
+        this.directory = resolve(dataDir, "project-control");
+        const existed = existsSync(this.directory);
+        mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+        const directory = lstatSync(this.directory);
+        if (!directory.isDirectory() || directory.isSymbolicLink())
+            throw new Error("Project registry must be a private directory");
+        chmodSync(this.directory, 0o700);
+        this.file = join(this.directory, "registry.json");
+        this.marker = join(this.directory, "initialized");
+        this.controllerLock = acquireProjectControllerLock(this.directory);
+        try {
+            if (existsSync(this.marker)) {
+                if (privateFileBytes(this.marker, 16).toString() !== "1\n")
+                    throw new Error("Project initialization marker is corrupt.");
+                this.markerEstablished = true;
+            }
+            if (existsSync(this.file)) {
+                const bytes = privateFileBytes(this.file);
+                this.data = JSON.parse(bytes.toString("utf8"));
+                this.validate();
+                this.diskDigest = digest(bytes);
+            }
+            else {
+                if (existsSync(this.marker) || existed)
+                    throw new Error("Project registry is missing; restore the existing registry before starting");
+                this.data = { version: 1, installationId: randomUUID(), owners: [], projects: [] };
+                this.write();
+            }
+            if (!this.markerEstablished) {
+                writeFileSync(this.marker, "1\n", { mode: 0o600, flag: "wx" });
+                this.markerEstablished = true;
+            }
+        }
+        catch (error) {
+            this.controllerLock.release();
+            throw error;
+        }
+    }
+    /** Release the single-controller lease on shutdown or startup failure. */
+    close() {
+        this.controllerLock.release();
+    }
+    get installationId() {
+        this.assertStorage();
+        return this.data.installationId;
+    }
+    validate(data = this.data) {
+        if (!data ||
+            data.version !== 1 ||
+            !UUID.test(data.installationId) ||
+            !Array.isArray(data.owners) ||
+            !Array.isArray(data.projects) ||
+            data.owners.length > 128 ||
+            data.projects.length > 128)
+            throw new Error("Project registry is corrupt; restore its backup");
+        const owners = new Set();
+        const names = new Set();
+        for (const owner of data.owners) {
+            if (!owner ||
+                !UUID.test(owner.id) ||
+                typeof owner.username !== "string" ||
+                !owner.username.trim() ||
+                owner.username.length > 64 ||
+                owner.username.trim() !== owner.username ||
+                /[\x00-\x1f\x7f]/.test(owner.username) ||
+                owners.has(owner.id) ||
+                names.has(owner.username))
+                throw new Error("Project owner registry is corrupt");
+            owners.add(owner.id);
+            names.add(owner.username);
+        }
+        const ids = new Set();
+        for (const project of data.projects) {
+            if (!project ||
+                !UUID.test(project.id) ||
+                ids.has(project.id) ||
+                !owners.has(project.ownerId) ||
+                typeof project.name !== "string" ||
+                !project.name.trim() ||
+                project.name.length > 80 ||
+                project.name.trim() !== project.name ||
+                /[\x00-\x1f\x7f]/.test(project.name) ||
+                !STATUSES.has(project.status) ||
+                !Number.isSafeInteger(project.generation) ||
+                project.generation < 0 ||
+                project.runtimeUsername !== "project-runtime" ||
+                !TOKEN.test(project.runtimePassword) ||
+                !Number.isSafeInteger(project.createdAt) ||
+                project.createdAt < 0 ||
+                !Number.isSafeInteger(project.updatedAt) ||
+                project.updatedAt < project.createdAt ||
+                (project.error !== undefined &&
+                    (typeof project.error !== "string" || project.error.length > 1000)))
+                throw new Error("Project registry entry is corrupt");
+            ids.add(project.id);
+        }
+    }
+    assertStorage() {
+        this.controllerLock.assertHeld();
+        if (this.markerEstablished && privateFileBytes(this.marker, 16).toString() !== "1\n")
+            throw new Error("Project initialization marker changed.");
+        if (this.diskDigest !== undefined) {
+            if (digest(privateFileBytes(this.file)) !== this.diskDigest)
+                throw new Error("Project registry changed while the controller was running.");
+        }
+        else if (existsSync(this.file))
+            throw new Error("Unexpected existing project registry.");
+    }
+    write(next = this.data) {
+        this.validate(next);
+        this.assertStorage();
+        const bytes = Buffer.from(JSON.stringify(next, null, 2) + "\n");
+        if (bytes.length > MAX_STORE_BYTES)
+            throw new Error("Project registry is too large.");
+        const file = join(this.directory, `.registry-${randomUUID()}.tmp`);
+        let fd;
+        try {
+            fd = openSync(file, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), 0o600);
+            writeFileSync(fd, bytes);
+            fsyncSync(fd);
+            closeSync(fd);
+            fd = undefined;
+            this.assertStorage();
+            (this.io.rename ?? renameSync)(file, this.file);
+            this.diskDigest = digest(bytes);
+        }
+        finally {
+            if (fd !== undefined)
+                closeSync(fd);
+            rmSync(file, { force: true });
+        }
+    }
+    all() {
+        this.assertStorage();
+        return this.data.projects.map((item) => ({ ...item }));
+    }
+    list(username) {
+        this.assertStorage();
+        const owner = this.data.owners.find((item) => item.username === username);
+        return this.data.projects.filter((item) => item.ownerId === owner?.id).map(projectView);
+    }
+    get(username, id) {
+        this.assertStorage();
+        const owner = this.data.owners.find((item) => item.username === username);
+        const project = this.data.projects.find((item) => item.id === id && item.ownerId === owner?.id);
+        if (!project)
+            throw new ProjectRegistryError(404, "找不到这个项目。");
+        return { ...project };
+    }
+    create(username, name) {
+        this.assertStorage();
+        if (typeof name !== "string" ||
+            !name.trim() ||
+            name.trim().length > 80 ||
+            /[\x00-\x1f\x7f]/.test(name))
+            throw new ProjectRegistryError(400, "请输入 1 至 80 个字符的项目名称。");
+        if (typeof username !== "string" ||
+            !username ||
+            username.trim() !== username ||
+            username.length > 64 ||
+            /[\x00-\x1f\x7f]/.test(username))
+            throw new ProjectRegistryError(401, "请先登录。");
+        if (this.data.projects.length >= 32)
+            throw new ProjectRegistryError(429, "项目数量已达到上限（32 个）。");
+        const next = structuredClone(this.data);
+        let owner = next.owners.find((item) => item.username === username);
+        if (!owner) {
+            owner = { id: randomUUID(), username };
+            next.owners.push(owner);
+        }
+        const timestamp = this.now();
+        const project = {
+            id: randomUUID(),
+            ownerId: owner.id,
+            name: name.trim(),
+            status: "stopped",
+            generation: 0,
+            runtimeUsername: "project-runtime",
+            runtimePassword: randomBytes(32).toString("base64url"),
+            createdAt: timestamp,
+            updatedAt: timestamp,
+        };
+        next.projects.push(project);
+        this.write(next);
+        this.data = next;
+        return { ...project };
+    }
+    update(id, patch) {
+        this.assertStorage();
+        const index = this.data.projects.findIndex((item) => item.id === id);
+        if (index === -1)
+            throw new ProjectRegistryError(404, "找不到这个项目。");
+        const previous = this.data.projects[index];
+        const next = {
+            ...previous,
+            status: patch.status,
+            updatedAt: Math.max(previous.updatedAt, this.now()),
+            ...(patch.generation !== undefined ? { generation: patch.generation } : {}),
+            ...(patch.error !== undefined ? { error: patch.error } : {}),
+        };
+        if (patch.error === undefined)
+            delete next.error;
+        if (next.generation < previous.generation || !Number.isSafeInteger(next.generation))
+            throw new Error("Project generation cannot move backwards");
+        const candidate = structuredClone(this.data);
+        candidate.projects[index] = next;
+        this.write(candidate);
+        this.data = candidate;
+        return { ...next };
+    }
+}
+export function projectView(project) {
+    const error = project.error?.split(project.runtimePassword).join("[redacted]");
+    return {
+        id: project.id,
+        name: project.name,
+        status: project.status,
+        generation: project.generation,
+        createdAt: project.createdAt,
+        updatedAt: project.updatedAt,
+        ...(error ? { error } : {}),
+    };
+}

package/dist/project-runtime/types.d.ts

@@ -0,0 +1,43 @@
+/** Stored only by the trusted control plane; credentials must never reach browser DTOs. */
+export interface ProjectRuntimeRecord {
+    id: string;
+    ownerId: string;
+    generation: number;
+    runtimeUsername: string;
+    runtimePassword: string;
+}
+export interface ProjectRuntimeConnection {
+    /** Always an HTTP URL bound to the Docker host's loopback interface. */
+    url: string;
+    username: string;
+    password: string;
+    generation: number;
+}
+export interface ProjectRuntimeAvailability {
+    available: boolean;
+    error?: string;
+}
+export interface ProjectRuntimeStatus {
+    state: "running" | "stopped" | "missing";
+    url?: string;
+}
+export interface ProjectRuntimeProvider {
+    availability(): Promise<ProjectRuntimeAvailability>;
+    ensure(project: ProjectRuntimeRecord, options: {
+        publicOrigin: string;
+    }): Promise<ProjectRuntimeConnection>;
+    stop(project: ProjectRuntimeRecord): Promise<void>;
+    status(project: ProjectRuntimeRecord): Promise<ProjectRuntimeStatus>;
+    /** Cancels control commands; never removes containers or persistent project volumes. */
+    close(): Promise<void>;
+}
+export interface ManagedProjectSecret {
+    version: 1;
+    projectId: string;
+    ownerId: string;
+    generation: number;
+    username: string;
+    password: string;
+    publicOrigin: string;
+    publicPathPrefix: string;
+}

package/dist/project-runtime/types.js

@@ -0,0 +1 @@
+export {};

package/dist/serve/cli.d.ts

@@ -3,6 +3,11 @@ interface CliArgs {
     host: string;
     port: number;
     passcode?: string;
+    authMode: "hub" | "passcode";
+    runtime: "local" | "docker";
+    runtimeImage?: string;
+    debugLogs?: boolean;
+    publicOrigin?: string;
     dataDir: string;
     staticRootDir?: string;
 }

package/dist/serve/cli.js

@@ -1,18 +1,14 @@
 // packages/server/src/serve/cli.ts
 //
-// `code-shell-serve` — boot the headless no-account web host from a terminal:
-//
-//   code-shell-serve --cwd ~/work/repo [--port 8790] [--host 127.0.0.1]
-//                    [--passcode <code>] [--data-dir <dir>]
-//
-// Access control is passcode + remember-cookie only (决策见 TODO 约束边界
-// 「服务端部署不做账号体系」). Default bind is loopback; binding 0.0.0.0 is a
-// deliberate operator choice.
+// `code-shell-serve` boots a single-workspace Hub under Node.js.
+// New deployments use one administrator and revocable device sessions.
+// --auth passcode preserves the original passcode-only host.
 import { createRequire } from "node:module";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { existsSync } from "node:fs";
 import { startHeadlessServer } from "./headless-server.js";
+import { startProjectControlServer } from "../project-runtime/control-server.js";
 const SERVE_HELP = `Usage: code-shell-serve [options]
 
 Run the CodeShell headless Web host for a workspace.
@@ -21,15 +17,24 @@ Options:
   --cwd <path>         Workspace root (default: current directory)
   --host <host>        Bind host (default: 127.0.0.1)
   --port <port>        Bind port, 0 selects a free port (default: 8790)
-  --passcode <code>    Set or rotate the access passcode
-  --data-dir <path>    Access-control data directory
+  --auth <mode>        hub (default) or legacy passcode
+  --runtime <mode>     local (default) or Docker project sandboxes
+  --runtime-image <tag> Prebuilt project image (default: codeshell-project-runtime:local)
+  --public-url <url>   External HTTPS origin for reverse-proxy deployments
+  --passcode <code>    Set or rotate the legacy passcode (selects passcode mode)
+  --data-dir <path>    Persistent server data (auth, uploads and worker sessions)
   --static-root <path> Override the built Web app directory
+  --debug-logs        Include raw worker diagnostics (may contain task content)
   -h, --help           Show this help and exit`;
 const VALUE_FLAGS = new Set([
     "--cwd",
     "--host",
     "--port",
     "--passcode",
+    "--auth",
+    "--runtime",
+    "--runtime-image",
+    "--public-url",
     "--data-dir",
     "--static-root",
 ]);
@@ -37,6 +42,10 @@ export function parseServeArgs(argv, env = process.env) {
     const args = {};
     for (let i = 0; i < argv.length; i++) {
         const key = argv[i];
+        if (key === "--debug-logs") {
+            args["debug-logs"] = "true";
+            continue;
+        }
         if (!key || !VALUE_FLAGS.has(key)) {
             throw new Error(`unknown argument: ${key ?? ""}\n\n${SERVE_HELP}`);
         }
@@ -52,7 +61,39 @@ export function parseServeArgs(argv, env = process.env) {
     if (!Number.isInteger(port) || port < 0 || port > 65535) {
         throw new Error(`invalid --port: ${args.port}`);
     }
+    const authMode = args.auth ?? (args.passcode ? "passcode" : "hub");
+    if (authMode !== "hub" && authMode !== "passcode")
+        throw new Error("--auth must be hub or passcode");
+    if (authMode === "hub" && args.passcode)
+        throw new Error("--passcode cannot be combined with --auth hub");
+    const runtime = args.runtime ?? "local";
+    if (runtime !== "local" && runtime !== "docker")
+        throw new Error("--runtime must be local or docker");
+    if (runtime === "docker" && authMode !== "hub")
+        throw new Error("Docker projects require --auth hub");
+    if (args["runtime-image"] && runtime !== "docker")
+        throw new Error("--runtime-image requires --runtime docker");
+    let publicOrigin;
+    const publicUrl = args["public-url"] ?? env.CODE_SHELL_SERVE_PUBLIC_URL;
+    if (publicUrl) {
+        const url = new URL(publicUrl);
+        if (url.username ||
+            url.password ||
+            url.search ||
+            url.hash ||
+            url.pathname !== "/" ||
+            (url.protocol !== "https:" &&
+                !(url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)))) {
+            throw new Error("--public-url must be an HTTPS origin (HTTP allowed only on loopback)");
+        }
+        publicOrigin = url.origin;
+    }
     return {
+        authMode,
+        runtime,
+        ...(args["runtime-image"] ? { runtimeImage: args["runtime-image"] } : {}),
+        ...(args["debug-logs"] ? { debugLogs: true } : {}),
+        ...(publicOrigin ? { publicOrigin } : {}),
         cwd: resolve(args.cwd ?? process.cwd()),
         host: args.host ?? "127.0.0.1",
         port,
@@ -96,22 +137,40 @@ export async function runServeCli(argv = process.argv.slice(2)) {
     }
     const parsed = parseServeArgs(argv);
     const staticRootDir = parsed.staticRootDir ?? resolveWebAppRoot();
-    const server = await startHeadlessServer({
-        host: parsed.host,
-        port: parsed.port,
-        cwd: parsed.cwd,
-        dataDir: parsed.dataDir,
-        workerEntryPath: resolveWorkerEntry(),
-        workerCapabilityModules: resolveWorkerCapabilityModules(),
-        ...(staticRootDir ? { staticRootDir } : {}),
-        ...(parsed.passcode ? { passcode: parsed.passcode } : {}),
-        log: (event, data) => console.error(`[serve] ${event}${data ? ` ${JSON.stringify(data)}` : ""}`),
-    });
-    console.log(`CodeShell web host listening at ${server.url}`);
-    console.log(`Workspace: ${parsed.cwd}`);
+    const server = parsed.runtime === "docker"
+        ? await startProjectControlServer({
+            host: parsed.host,
+            port: parsed.port,
+            dataDir: parsed.dataDir,
+            publicOrigin: parsed.publicOrigin,
+            staticRootDir,
+            runtimeImage: parsed.runtimeImage,
+        })
+        : await startHeadlessServer({
+            host: parsed.host,
+            port: parsed.port,
+            cwd: parsed.cwd,
+            dataDir: parsed.dataDir,
+            authMode: parsed.authMode,
+            debugLogs: parsed.debugLogs,
+            ...(parsed.publicOrigin ? { publicOrigin: parsed.publicOrigin } : {}),
+            workerEntryPath: resolveWorkerEntry(),
+            workerCapabilityModules: resolveWorkerCapabilityModules(),
+            ...(staticRootDir ? { staticRootDir } : {}),
+            ...(parsed.passcode ? { passcode: parsed.passcode } : {}),
+            log: (event, data) => console.error(`[serve] ${event}${data ? ` ${JSON.stringify(data)}` : ""}`),
+        });
+    console.log(`CodeShell ${parsed.authMode === "hub" ? "Hub" : "web host"} listening at ${parsed.publicOrigin ?? server.url}`);
+    console.log(parsed.runtime === "docker"
+        ? "Project sandboxes: Docker (project files persist in separate volumes)"
+        : `Workspace: ${parsed.cwd}`);
     if (!staticRootDir) {
         console.log("No web app build found — WS endpoint only (/ws). Build packages/web first.");
     }
+    if (server.bootstrapToken) {
+        const origin = parsed.publicOrigin ?? server.url.replace(/\/\/(0\.0\.0\.0|\[?::\]?)(?=:)/, "//127.0.0.1");
+        console.log(`Administrator setup (one-time link, save it now): ${origin}/#setup=${server.bootstrapToken}`);
+    }
     if (server.generatedPasscode) {
         console.log(`Access passcode (generated, save it now): ${server.generatedPasscode}`);
     }

package/dist/serve/headless-server.d.ts

@@ -30,6 +30,16 @@ export interface HeadlessServeOptions {
      * `generatedPasscode` — the CLI prints it once.
      */
     passcode?: string;
+    /** CLI defaults to hub; omitted by existing API hosts keeps passcode compatibility. */
+    authMode?: "hub" | "passcode";
+    /** Explicit diagnostics opt-in; may include task content and worker stderr. */
+    debugLogs?: boolean;
+    /** Exact external origin; required for HTTPS reverse proxies. Never trust forwarded headers. */
+    publicOrigin?: string;
+    /** Trusted project gateway prefix; generated by the controller, never a request parameter. */
+    publicPathPrefix?: string;
+    /** Session revocation/expiry sweep interval; defaults to 5 seconds. */
+    authRecheckMs?: number;
     log?: WorkerBridgeLog;
     /** Test/host tuning; production defaults to 60 seconds. */
     pendingWorkerResponseTtlMs?: number;
@@ -42,6 +52,7 @@ export interface HeadlessServer {
     port: number;
     /** Present only when this boot had to generate a fresh passcode. */
     generatedPasscode?: string;
+    bootstrapToken?: string;
     passcode: AccessPasscode;
     bridge: WorkerBridgeCore;
     /** Live authenticated tab count (for tests/status). */