@cjhyy/code-shell-server 0.8.0

package/dist/mobile-remote/mobile-upload-service.js

@@ -0,0 +1,370 @@
+import { createHash, randomBytes } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { mkdir, readdir, rename, rm, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { pipeline } from "node:stream/promises";
+import { Transform } from "node:stream";
+export const MAX_MOBILE_IMAGE_BYTES = 10 * 1024 * 1024;
+export const MOBILE_UPLOAD_TTL_MS = 5 * 60 * 1000;
+export const MAX_MOBILE_UPLOAD_TICKETS_PER_DEVICE = 16;
+export const MAX_MOBILE_UPLOAD_CLAIM_ATTEMPTS = 3;
+const IMAGE_MIMES = new Set([
+    "image/png",
+    "image/jpeg",
+    "image/webp",
+    "image/gif",
+]);
+function normalizedContentType(value) {
+    return String(value ?? "")
+        .split(";", 1)[0]
+        .trim()
+        .toLowerCase();
+}
+function reply(res, status, message) {
+    if (res.headersSent || res.writableEnded)
+        return;
+    res.writeHead(status, { "content-type": "text/plain; charset=utf-8" });
+    res.end(message);
+}
+/** One-time, device-bound HTTP upload tickets backed by a temporary spool. */
+export class MobileUploadService {
+    opts;
+    uploads = new Map();
+    activeTransfers = new Map();
+    now;
+    uploadTtlMs;
+    startupCleanup;
+    timer;
+    disposed = false;
+    disposePromise;
+    constructor(opts) {
+        this.opts = opts;
+        this.now = opts.now ?? (() => Date.now());
+        this.uploadTtlMs = opts.uploadTtlMs ?? MOBILE_UPLOAD_TTL_MS;
+        this.startupCleanup = this.cleanupOrphanSpools(this.now(), false);
+        const interval = opts.cleanupIntervalMs ?? 60_000;
+        if (interval > 0) {
+            this.timer = setInterval(() => void this.cleanupExpired().catch(() => undefined), interval);
+            this.timer.unref?.();
+        }
+    }
+    /** Wait until startup orphan recovery has completed. */
+    async ready() {
+        await this.startupCleanup;
+    }
+    begin(deviceId, metadata) {
+        if (this.disposed)
+            throw new Error("upload service is shutting down");
+        void this.cleanupExpired().catch(() => undefined);
+        const mime = normalizedContentType(metadata.mime);
+        if (!deviceId.trim())
+            throw new Error("authenticated device is required");
+        if (!metadata.clientId?.trim())
+            throw new Error("attachment clientId is required");
+        if (!metadata.name?.trim())
+            throw new Error("attachment name is required");
+        if (!IMAGE_MIMES.has(mime))
+            throw new Error("unsupported image MIME");
+        if (!Number.isSafeInteger(metadata.size) ||
+            metadata.size <= 0 ||
+            metadata.size > MAX_MOBILE_IMAGE_BYTES) {
+            throw new Error("attachment size is outside the allowed range");
+        }
+        let deviceTickets = 0;
+        for (const upload of this.uploads.values()) {
+            if (upload.deviceId === deviceId)
+                deviceTickets += 1;
+        }
+        if (deviceTickets >= MAX_MOBILE_UPLOAD_TICKETS_PER_DEVICE) {
+            throw new Error("too many pending attachment uploads for this device");
+        }
+        const uploadId = randomBytes(24).toString("base64url");
+        const expiresAt = this.now() + this.uploadTtlMs;
+        this.uploads.set(uploadId, {
+            ...metadata,
+            mime,
+            uploadId,
+            deviceId,
+            expiresAt,
+            status: "pending",
+            claimAttempts: 0,
+        });
+        return {
+            clientId: metadata.clientId,
+            uploadId,
+            putUrl: `/api/mobile/uploads/${uploadId}`,
+            expiresAt,
+        };
+    }
+    async acceptPut(uploadId, req, res) {
+        try {
+            await this.ready();
+        }
+        catch {
+            reply(res, 500, "upload storage is unavailable");
+            return;
+        }
+        if (this.disposed) {
+            reply(res, 503, "upload service is shutting down");
+            return;
+        }
+        const record = this.uploads.get(uploadId);
+        if (!record || record.expiresAt <= this.now()) {
+            if (record)
+                await this.expire(uploadId, record);
+            reply(res, 404, "upload ticket not found or expired");
+            return;
+        }
+        if (req.method !== "PUT") {
+            reply(res, 405, "method not allowed");
+            return;
+        }
+        if (record.status !== "pending") {
+            reply(res, 409, "upload ticket is already in use");
+            return;
+        }
+        if (normalizedContentType(req.headers["content-type"]) !== record.mime) {
+            reply(res, 415, "content type does not match ticket");
+            return;
+        }
+        const declaredLength = Number(req.headers["content-length"]);
+        if (Number.isFinite(declaredLength) && declaredLength > MAX_MOBILE_IMAGE_BYTES) {
+            reply(res, 413, "upload is too large");
+            return;
+        }
+        if (Number.isFinite(declaredLength) && declaredLength !== record.size) {
+            reply(res, 400, "content length does not match ticket");
+            return;
+        }
+        // Reserve the ticket synchronously before the first filesystem await. Two
+        // near-simultaneous PUTs used to both observe `pending`, then race on the
+        // same .part path and reset/delete each other's record. The duplicate now
+        // receives the existing 409 above while this first request runs normally.
+        record.status = "uploading";
+        try {
+            await mkdir(this.opts.rootDir, { recursive: true });
+        }
+        catch {
+            if (this.uploads.get(uploadId) === record && record.status === "uploading") {
+                record.status = "pending";
+            }
+            reply(res, 500, "upload storage is unavailable");
+            return;
+        }
+        const partPath = join(this.opts.rootDir, `${uploadId}.part`);
+        const finalPath = join(this.opts.rootDir, `${uploadId}.upload`);
+        const hash = createHash("sha256");
+        let received = 0;
+        let deadlineExpired = false;
+        const counter = new Transform({
+            transform(chunk, _encoding, callback) {
+                received += chunk.byteLength;
+                if (received > MAX_MOBILE_IMAGE_BYTES) {
+                    callback(new Error("upload exceeds size limit"));
+                    return;
+                }
+                hash.update(chunk);
+                callback(null, chunk);
+            },
+        });
+        const controller = new AbortController();
+        const deadline = setTimeout(() => {
+            deadlineExpired = true;
+            controller.abort(new Error("upload ticket expired during transfer"));
+        }, Math.max(0, record.expiresAt - this.now()));
+        deadline.unref?.();
+        const transfer = pipeline(req, counter, createWriteStream(partPath, { flags: "wx" }), {
+            signal: controller.signal,
+        });
+        this.activeTransfers.set(uploadId, { controller, done: transfer });
+        try {
+            await transfer;
+            if (received !== record.size) {
+                await rm(partPath, { force: true });
+                record.status = "pending";
+                reply(res, 400, "received size does not match ticket");
+                return;
+            }
+            if (this.uploads.get(uploadId) !== record ||
+                record.status !== "uploading" ||
+                record.expiresAt <= this.now()) {
+                await rm(partPath, { force: true });
+                if (this.uploads.get(uploadId) === record)
+                    this.uploads.delete(uploadId);
+                reply(res, 408, "upload ticket expired during transfer");
+                return;
+            }
+            await rename(partPath, finalPath);
+            if (this.uploads.get(uploadId) !== record ||
+                record.status !== "uploading" ||
+                record.expiresAt <= this.now()) {
+                await rm(finalPath, { force: true });
+                if (this.uploads.get(uploadId) === record)
+                    this.uploads.delete(uploadId);
+                reply(res, 408, "upload ticket expired during transfer");
+                return;
+            }
+            record.status = "ready";
+            record.path = finalPath;
+            record.sha256 = hash.digest("hex");
+            reply(res, 201, "uploaded");
+        }
+        catch (error) {
+            await rm(partPath, { force: true }).catch(() => undefined);
+            const expired = deadlineExpired || record.expiresAt <= this.now();
+            if (this.uploads.get(uploadId) === record) {
+                if (expired || this.disposed)
+                    this.uploads.delete(uploadId);
+                else
+                    record.status = "pending";
+            }
+            reply(res, expired ? 408 : String(error.message).includes("size limit") ? 413 : 400, "upload failed");
+        }
+        finally {
+            clearTimeout(deadline);
+            if (this.activeTransfers.get(uploadId)?.done === transfer) {
+                this.activeTransfers.delete(uploadId);
+            }
+        }
+    }
+    /** Atomically move a ready upload into a request-owned lease. */
+    claim(deviceId, uploadId) {
+        const record = this.uploads.get(uploadId);
+        if (!record || record.expiresAt <= this.now()) {
+            if (record)
+                void this.expire(uploadId, record);
+            throw new Error("upload is not ready or no longer exists");
+        }
+        if (record.deviceId !== deviceId)
+            throw new Error("upload belongs to another device");
+        if (record.status !== "ready")
+            throw new Error("upload is already claimed or not ready");
+        if (record.claimAttempts >= MAX_MOBILE_UPLOAD_CLAIM_ATTEMPTS) {
+            void this.expire(uploadId, record);
+            throw new Error("upload claim retry limit exceeded");
+        }
+        const claimId = randomBytes(18).toString("base64url");
+        record.status = "claimed";
+        record.claimId = claimId;
+        record.claimAttempts += 1;
+        return {
+            uploadId,
+            claimId,
+            clientId: record.clientId,
+            name: record.name,
+            mime: record.mime,
+            size: record.size,
+            path: record.path,
+            sha256: record.sha256,
+        };
+    }
+    /** Release a failed staging/dispatch attempt for a bounded retry. */
+    async release(deviceId, uploadId, claimId) {
+        const record = this.assertClaimOwner(deviceId, uploadId, claimId);
+        delete record.claimId;
+        if (record.claimAttempts >= MAX_MOBILE_UPLOAD_CLAIM_ATTEMPTS) {
+            this.uploads.delete(uploadId);
+            if (record.path)
+                await rm(record.path, { force: true }).catch(() => undefined);
+            return;
+        }
+        record.status = "ready";
+    }
+    /** Finalize a successful turn; only the active claim owner may consume it. */
+    async finalize(deviceId, uploadId, claimId) {
+        const record = this.assertClaimOwner(deviceId, uploadId, claimId);
+        this.uploads.delete(uploadId);
+        if (record.path)
+            await rm(record.path, { force: true }).catch(() => undefined);
+    }
+    async cleanupExpired() {
+        await this.ready();
+        const now = this.now();
+        const expired = [];
+        for (const [uploadId, record] of this.uploads) {
+            if (record.expiresAt <= now)
+                expired.push(this.expire(uploadId, record));
+        }
+        await Promise.allSettled(expired);
+        await this.cleanupOrphanSpools(now, false);
+    }
+    /** Abort all in-flight transfers and invalidate every outstanding ticket. */
+    async cancelActiveTransfers() {
+        await this.ready();
+        const records = [...this.uploads.entries()];
+        for (const [uploadId] of records)
+            this.uploads.delete(uploadId);
+        for (const transfer of this.activeTransfers.values()) {
+            transfer.controller.abort(new Error("upload service stopped"));
+        }
+        await Promise.allSettled([...this.activeTransfers.values()].map((item) => item.done));
+        await Promise.allSettled(records.map(([uploadId, record]) => this.cleanupRecordFiles(uploadId, record)));
+    }
+    /** Fully await timer shutdown, active aborts, and every spool unlink. */
+    async dispose() {
+        if (this.disposePromise)
+            return this.disposePromise;
+        this.disposed = true;
+        if (this.timer)
+            clearInterval(this.timer);
+        this.disposePromise = (async () => {
+            await this.cancelActiveTransfers();
+            await this.cleanupOrphanSpools(this.now(), true);
+        })();
+        return this.disposePromise;
+    }
+    async expire(uploadId, record) {
+        if (this.uploads.get(uploadId) === record)
+            this.uploads.delete(uploadId);
+        const active = this.activeTransfers.get(uploadId);
+        if (active) {
+            active.controller.abort(new Error("upload ticket expired"));
+            await active.done.catch(() => undefined);
+        }
+        await this.cleanupRecordFiles(uploadId, record);
+    }
+    async cleanupRecordFiles(uploadId, record) {
+        await Promise.allSettled([
+            rm(join(this.opts.rootDir, `${uploadId}.part`), { force: true }),
+            rm(join(this.opts.rootDir, `${uploadId}.upload`), { force: true }),
+            ...(record?.path ? [rm(record.path, { force: true })] : []),
+        ]);
+    }
+    async cleanupOrphanSpools(now, removeAll) {
+        try {
+            await mkdir(this.opts.rootDir, { recursive: true });
+        }
+        catch {
+            return;
+        }
+        const entries = await readdir(this.opts.rootDir, { withFileTypes: true }).catch(() => []);
+        const activeIds = new Set([...this.uploads.keys(), ...this.activeTransfers.keys()]);
+        await Promise.allSettled(entries.map(async (entry) => {
+            if (!entry.isFile())
+                return;
+            const match = /^([A-Za-z0-9_-]+)\.(part|upload)$/.exec(entry.name);
+            if (!match || activeIds.has(match[1]))
+                return;
+            const path = join(this.opts.rootDir, entry.name);
+            if (!removeAll) {
+                const info = await stat(path).catch(() => undefined);
+                if (!info)
+                    return;
+                if (info.mtimeMs + this.uploadTtlMs > now)
+                    return;
+            }
+            await rm(path, { force: true });
+        }));
+    }
+    assertClaimOwner(deviceId, uploadId, claimId) {
+        const record = this.uploads.get(uploadId);
+        if (!record)
+            throw new Error("upload claim no longer exists");
+        if (record.deviceId !== deviceId)
+            throw new Error("upload belongs to another device");
+        if (record.status !== "claimed" || record.claimId !== claimId) {
+            throw new Error("upload claim owner does not match");
+        }
+        return record;
+    }
+}

package/dist/mobile-remote/pairing.d.ts

@@ -0,0 +1,8 @@
+import type { PairingToken } from "./types.js";
+export declare class PairingTokenManager {
+    private readonly now;
+    private tokens;
+    constructor(now?: () => number);
+    createToken(ttlMs?: number): PairingToken;
+    consume(value: string): boolean;
+}

package/dist/mobile-remote/pairing.js

@@ -0,0 +1,23 @@
+import { randomBytes } from "node:crypto";
+export class PairingTokenManager {
+    now;
+    tokens = new Map();
+    constructor(now = () => Date.now()) {
+        this.now = now;
+    }
+    createToken(ttlMs = 10 * 60 * 1000) {
+        const token = {
+            value: randomBytes(32).toString("base64url"),
+            expiresAt: this.now() + ttlMs,
+        };
+        this.tokens.set(token.value, token);
+        return token;
+    }
+    consume(value) {
+        const token = this.tokens.get(value);
+        if (!token)
+            return false;
+        this.tokens.delete(value);
+        return token.expiresAt >= this.now();
+    }
+}

package/dist/mobile-remote/path-bins.d.ts

@@ -0,0 +1,7 @@
+/**
+ * macOS GUI-launched Electron has a minimal PATH (no Homebrew). Prepend common
+ * CLI dirs so `claude` / `codex` resolve. Mirrors the external-agent adapter's
+ * fix. Standalone (no heavy imports) so both resident-agent and codex-room-agent
+ * can use it without dragging in core.
+ */
+export declare function pathWithCommonBins(env?: NodeJS.ProcessEnv): string;

package/dist/mobile-remote/path-bins.js

@@ -0,0 +1,16 @@
+import { delimiter } from "node:path";
+/**
+ * macOS GUI-launched Electron has a minimal PATH (no Homebrew). Prepend common
+ * CLI dirs so `claude` / `codex` resolve. Mirrors the external-agent adapter's
+ * fix. Standalone (no heavy imports) so both resident-agent and codex-room-agent
+ * can use it without dragging in core.
+ */
+export function pathWithCommonBins(env = process.env) {
+    const extra = ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin"];
+    const current = (env.PATH ?? "").split(delimiter).filter(Boolean);
+    const merged = [];
+    for (const dir of [...extra, ...current])
+        if (!merged.includes(dir))
+            merged.push(dir);
+    return merged.join(delimiter);
+}

package/dist/mobile-remote/pending-approvals.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Tracks currently pending core approval requests for mobile clients.
+ *
+ * Session snapshots intentionally contain only stream events. Approval requests
+ * are stateful: keep the latest unresolved raw JSON-RPC request here and replay
+ * it to a phone when that phone binds to the matching session.
+ */
+export declare class PendingMobileApprovals {
+    private readonly bySession;
+    observeOutboundLine(line: string): void;
+    resolve(requestId: string): void;
+    replayLines(sessionId: string): string[];
+    forgetSession(sessionId: string): void;
+}

package/dist/mobile-remote/pending-approvals.js

@@ -0,0 +1,54 @@
+/**
+ * Tracks currently pending core approval requests for mobile clients.
+ *
+ * Session snapshots intentionally contain only stream events. Approval requests
+ * are stateful: keep the latest unresolved raw JSON-RPC request here and replay
+ * it to a phone when that phone binds to the matching session.
+ */
+export class PendingMobileApprovals {
+    bySession = new Map();
+    observeOutboundLine(line) {
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (msg.method === "agent/approvalRequest") {
+            const params = msg.params;
+            const sessionId = params?.sessionId;
+            const requestId = params?.requestId;
+            if (typeof sessionId !== "string" || !sessionId)
+                return;
+            if (typeof requestId !== "string" || !requestId)
+                return;
+            let pending = this.bySession.get(sessionId);
+            if (!pending) {
+                pending = new Map();
+                this.bySession.set(sessionId, pending);
+            }
+            pending.set(requestId, line);
+            return;
+        }
+        if (msg.method === "agent/approvalResolved") {
+            const params = msg.params;
+            const requestId = params?.requestId;
+            if (typeof requestId === "string" && requestId)
+                this.resolve(requestId);
+        }
+    }
+    resolve(requestId) {
+        for (const [sessionId, pending] of this.bySession) {
+            pending.delete(requestId);
+            if (pending.size === 0)
+                this.bySession.delete(sessionId);
+        }
+    }
+    replayLines(sessionId) {
+        return [...(this.bySession.get(sessionId)?.values() ?? [])];
+    }
+    forgetSession(sessionId) {
+        this.bySession.delete(sessionId);
+    }
+}

package/dist/mobile-remote/remote-host-manager.d.ts

@@ -0,0 +1,117 @@
+import { EventEmitter } from "node:events";
+import { type WebSocket } from "ws";
+import type { AccessPasscode } from "./access-passcode.js";
+import type { TrustedDeviceStore } from "./trusted-device-store.js";
+import type { MobileClientEvent, MobileServerEvent } from "./types.js";
+import type { MobileUploadService } from "./mobile-upload-service.js";
+/**
+ * Pick the Mac's real LAN IPv4 so a phone on the same Wi-Fi can reach the
+ * remote host. We bind to a concrete LAN address (NOT 0.0.0.0) per the design's
+ * §6.5 network-safety rule. Excludes loopback (127.x), link-local (169.254.x),
+ * and common VPN/tunnel ranges (198.18.x carrier-grade test net used by some
+ * VPN clients) so we don't advertise an address the phone can't route to.
+ * Returns undefined if no suitable interface is found.
+ */
+export declare function resolveLanHost(): string | undefined;
+export interface RemoteHostStartOptions {
+    host: string;
+    port: number;
+    /**
+     * "lan" (default) keeps the existing LAN behaviour unchanged. "tunnel" binds
+     * 127.0.0.1 (cloudflared connects to loopback) and inserts a passcode gate in
+     * front of every HTTP route and the WS upgrade.
+     */
+    mode?: "lan" | "tunnel";
+    /** Required in tunnel mode: the public access gate. Ignored in lan mode. */
+    passcode?: AccessPasscode;
+}
+export interface RemoteHostStarted {
+    host: string;
+    port: number;
+    url: string;
+    mode: "lan" | "tunnel";
+}
+export interface RemoteHostManagerOptions {
+    devices: TrustedDeviceStore;
+    onClientEvent: (event: unknown, ws: WebSocket) => void;
+    /**
+     * Absolute path to the built mobile app (out/mobile). Defaults to the
+     * sibling of the bundled main (out/main → ../mobile). Overridable for tests.
+     */
+    mobileRootDir?: string;
+    /**
+     * Dev only: when set (from scripts/dev.ts via MOBILE_DEV_URL), /mobile/* is
+     * proxied to the mobile vite dev server for HMR instead of read from disk.
+     */
+    mobileDevUrl?: string;
+    /** One-time upload tickets. The route remains behind the tunnel passcode gate. */
+    uploads?: Pick<MobileUploadService, "acceptPut" | "cancelActiveTransfers">;
+}
+export declare class RemoteHostManager extends EventEmitter {
+    private readonly opts;
+    private server?;
+    private wss?;
+    private started?;
+    private pairing;
+    /** ws → authenticated device id. A socket absent here is unauthenticated. */
+    private authed;
+    /** Stable identity for each individual tab/socket, independent of device id. */
+    private viewers;
+    private nextViewerId;
+    /** deviceId → number of live authenticated sockets (a phone may open more
+     *  than one). A device is "online" while its count is > 0. */
+    private onlineCounts;
+    /** Public base URL (tunnel domain) used by createPairingUrl when set. */
+    private publicBaseUrl?;
+    /** Passcode gate, present only in tunnel mode. */
+    private passcode?;
+    /** Where the built mobile app lives (out/mobile). */
+    private readonly mobileRootDir;
+    /** Dev proxy target for /mobile (HMR); undefined in prod. */
+    private readonly mobileDevUrl?;
+    constructor(opts: RemoteHostManagerOptions);
+    /** Device ids with at least one live socket right now. */
+    onlineDeviceIds(): string[];
+    /** Register a live socket for a device; emits `online-change` only when the
+     *  device transitions offline→online (first socket). */
+    markOnline(deviceId: string): void;
+    /** Drop a socket for a device; emits `online-change` only when its last
+     *  socket goes away (online→offline). */
+    markOffline(deviceId: string): void;
+    start(options: RemoteHostStartOptions): Promise<RemoteHostStarted>;
+    /**
+     * Override the base URL used to build pairing URLs (tunnel mode points this
+     * at the `https://*.trycloudflare.com` domain so the QR encodes the public
+     * address, not the loopback bind). Pass undefined to clear it.
+     */
+    setPublicBaseUrl(url?: string): void;
+    createPairingUrl(): {
+        token: string;
+        url: string;
+        expiresAt: number;
+    };
+    /**
+     * Handle pairing/auth client events. Returns a server event for those two
+     * cases (consumed inline by the WS layer) or `undefined` for events the
+     * caller should route elsewhere. Pairing tokens are one-use; auth checks the
+     * trusted-device store (which rejects revoked devices), so the remote host
+     * never executes tools itself — it only gates transport.
+     */
+    handleClientEvent(event: MobileClientEvent): MobileServerEvent | undefined;
+    /** Broadcast a server event to every connected, authenticated mobile socket. */
+    broadcast(event: MobileServerEvent): void;
+    /** Send a server event to ONLY the sockets belonging to one device. Used for
+     *  per-device replies (chat.accepted, session.list.ok, permission.mode, …) so
+     *  one phone's session/permission state never leaks onto another's screen.
+     *  A device with no live socket (raced a disconnect) is a silent no-op. */
+    sendToDevice(deviceId: string, event: MobileServerEvent): void;
+    /** Send a raw JSON-RPC worker line to ONLY one authenticated device. */
+    sendRawToDevice(deviceId: string, payload: string): void;
+    /** Broadcast a raw line (e.g. a mirrored worker→renderer JSON-RPC line) to
+     *  every authenticated mobile socket. Unauthenticated sockets are skipped so
+     *  a half-paired client never sees session output. */
+    broadcastRaw(payload: string): void;
+    private releaseSocket;
+    stop(): Promise<void>;
+    status(): RemoteHostStarted | undefined;
+}