@cjhyy/code-shell-server 0.9.52 → 0.10.1

package/dist/mobile-remote/remote-host-manager.js

@@ -1,3 +1,4 @@
+import { stampApprovalClock } from "./approval-clock.js";
 import { createServer } from "node:http";
 import { networkInterfaces } from "node:os";
 import { EventEmitter } from "node:events";
@@ -8,6 +9,7 @@ import { serveMobile } from "./mobile-static.js";
 import { PairingTokenManager } from "./pairing.js";
 import { parseMobileClientEvent } from "./mobile-client-event-validator.js";
 import { isRelayOrigin } from "../remote-relay/protocol.js";
+import { AccountRelayAccessGate, readRelayHandoff, } from "./account-relay-access.js";
 /** Outbound bytes one paired socket may leave unread before it is retired. */
 const MAX_SOCKET_BACKLOG_BYTES = 4 * 1024 * 1024;
 /** The query suffix ("" or "?…") when the raw request target is exactly the
@@ -69,18 +71,62 @@ export class RemoteHostManager extends EventEmitter {
     passcode;
     socketAccessValidity = new WeakMap();
     accessSweep;
+    accountAccess;
+    accountSocketDevices = new WeakMap();
     /** Where the built mobile app lives (out/mobile). */
     mobileRootDir;
     /** Dev proxy target for /mobile (HMR); undefined in prod. */
     mobileDevUrl;
+    turnQueueEnabled = false;
     constructor(opts) {
         super();
         this.opts = opts;
+        this.accountAccess = new AccountRelayAccessGate(opts.devices, (id) => this.revokeDevice(id));
         // Bundled main is out/main/index.mjs → mobile app is the sibling out/mobile.
         const here = dirname(fileURLToPath(import.meta.url));
         this.mobileRootDir = opts.mobileRootDir ?? resolve(here, "../mobile");
         this.mobileDevUrl = opts.mobileDevUrl ?? process.env.MOBILE_DEV_URL;
     }
+    /** Install main-owned directory redemption; replacing it synchronously revokes old sessions. */
+    setAccountRelayAccess(provider) {
+        this.accountAccess.setProvider(provider);
+    }
+    /** The attached command Host installed a pending-turn FIFO; advertise it on (re)auth. */
+    advertiseTurnQueue() {
+        this.turnQueueEnabled = true;
+    }
+    /** A paired (or live account) device that has not been revoked or removed. */
+    isTrustedDevice(deviceId) {
+        try {
+            return this.opts.devices
+                .listDevices()
+                .some((device) => device.id === deviceId && !device.revokedAt);
+        }
+        catch {
+            // An unreadable store proves nothing; fail closed.
+            return false;
+        }
+    }
+    get turnQueueAdvertised() {
+        return this.turnQueueEnabled || this.opts.turnQueue === true;
+    }
+    relayRequestOrigin(request, requireOrigin = false) {
+        return !!(this.publicBaseUrl &&
+            request.headers.host === new URL(this.publicBaseUrl).host &&
+            (request.headers.origin === this.publicBaseUrl ||
+                (!requireOrigin && request.headers.origin === undefined)) &&
+            request.headers["sec-fetch-site"] !== "cross-site");
+    }
+    relayJson(response, status, body) {
+        if (response.writableEnded || response.destroyed)
+            return;
+        response.writeHead(status, {
+            "content-type": "application/json; charset=utf-8",
+            "cache-control": "no-store",
+            "x-content-type-options": "nosniff",
+        });
+        response.end(JSON.stringify(body));
+    }
     /** Device ids with at least one live socket right now. */
     onlineDeviceIds() {
         return [...this.onlineCounts.keys()];
@@ -129,11 +175,13 @@ export class RemoteHostManager extends EventEmitter {
     async startOnce(options) {
         const relay = options.mode === "relay";
         const publicAccess = relay || options.mode === "tunnel";
-        if (publicAccess && !options.passcode?.isSet()) {
+        if (publicAccess && !options.passcode?.isSet() && !(relay && this.accountAccess.available)) {
             throw new Error(`${relay ? "Relay" : "Tunnel"} mode requires an initialized access passcode`);
         }
         if (relay)
             this.publicBaseUrl = undefined;
+        // Keep the gate object even when account auto-start precedes passcode setup.
+        // Its current configuration is consulted for each HTTP/WS admission.
         this.passcode = publicAccess ? options.passcode : undefined;
         const gate = this.passcode;
         this.opts.webApi?.start();
@@ -148,11 +196,47 @@ export class RemoteHostManager extends EventEmitter {
                 req.resume();
                 return;
             }
+            if (relay && pathname === "/api/v1/relay/session") {
+                if (req.method !== "POST" ||
+                    !this.accountAccess.available ||
+                    !this.relayRequestOrigin(req, true)) {
+                    this.relayJson(res, 403, { error: "Account relay session is unavailable" });
+                    req.resume();
+                    return;
+                }
+                const lifetime = this.relayLifetime;
+                void readRelayHandoff(req)
+                    .then((handoff) => {
+                    if (!lifetime || lifetime.signal.aborted || lifetime !== this.relayLifetime)
+                        throw new Error("Relay Host stopped");
+                    return this.accountAccess.exchange(handoff);
+                })
+                    .then((session) => this.relayJson(res, 200, session))
+                    .catch(() => this.relayJson(res, 401, { error: "Account relay handoff expired or invalid" }));
+                return;
+            }
             const serve = () => {
                 // All ordinary routes retain the tunnel passcode gate. Only a Host-verified
                 // short-lived Panel asset capability may use independent authorization.
-                if (gate && !gate.gate(req, res))
+                const account = relay && this.relayRequestOrigin(req) ? this.accountAccess.capture(req) : undefined;
+                if (!account) {
+                    if (relay && (req.headers["x-codeshell-host-access"] !== undefined || !gate?.isSet())) {
+                        this.relayJson(res, 401, { error: "Account relay authorization is required" });
+                        req.resume();
+                        return;
+                    }
+                    if (gate && !gate.gate(req, res))
+                        return;
+                }
+                if (relay && pathname === "/api/v1/relay/projects") {
+                    if (req.method !== "GET" || !account) {
+                        this.relayJson(res, 401, { error: "Account relay authorization is required" });
+                        req.resume();
+                        return;
+                    }
+                    void this.accountAccess.projects(account).then((projects) => this.relayJson(res, 200, projects), () => this.relayJson(res, 401, { error: "Account relay authorization expired" }));
                     return;
+                }
                 if (req.url === "/health") {
                     res.writeHead(200, { "content-type": "application/json" });
                     res.end(JSON.stringify({ ok: true }));
@@ -166,7 +250,11 @@ export class RemoteHostManager extends EventEmitter {
                         return;
                     }
                     void this.opts.webApi
-                        .handle(req, res, { baseUrl, isAccessAuthorized: gate?.captureValidity() })
+                        .handle(req, res, {
+                        baseUrl,
+                        isAccessAuthorized: account?.isAuthorized ?? gate?.captureValidity(),
+                        ...(account ? { accessDeviceId: account.deviceId } : {}),
+                    })
                         .then((handled) => {
                         if (!handled && !res.writableEnded) {
                             res.writeHead(404);
@@ -234,13 +322,13 @@ export class RemoteHostManager extends EventEmitter {
         // In tunnel mode we must gate the WS handshake too. `noServer` lets us run
         // the passcode check during the HTTP `upgrade` event before completing the
         // handshake; in lan mode behaviour is unchanged (the same path/server bind).
-        this.wss = gate
+        this.wss = publicAccess
             ? new WebSocketServer({ noServer: true, maxPayload: 1024 * 1024 })
             : new WebSocketServer({ server, path: "/ws", maxPayload: 1024 * 1024 });
         // ws re-emits its HTTP server's bind errors. Without an error listener a
         // handled EADDRINUSE rejection still becomes an uncaught EventEmitter error.
         this.wss.on("error", (error) => this.emit("host-error", error));
-        if (gate) {
+        if (publicAccess) {
             server.on("upgrade", (req, socket, head) => {
                 let isWebSocketPath = false;
                 try {
@@ -253,21 +341,23 @@ export class RemoteHostManager extends EventEmitter {
                     socket.destroy();
                     return;
                 }
-                if (relay &&
-                    (!this.publicBaseUrl ||
-                        req.headers.origin !== this.publicBaseUrl ||
-                        req.headers.host !== new URL(this.publicBaseUrl).host)) {
+                if (relay && !this.relayRequestOrigin(req, true)) {
                     socket.end("HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n");
                     return;
                 }
-                if (!gate.allows(req)) {
+                const account = relay ? this.accountAccess.capture(req) : undefined;
+                if (!account &&
+                    ((relay && req.headers["x-codeshell-host-access"] !== undefined) ||
+                        !gate?.allows(req))) {
                     socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
                     socket.destroy();
                     return;
                 }
-                const isAccessAuthorized = gate.captureValidity();
+                const isAccessAuthorized = account?.isAuthorized ?? gate.captureValidity();
                 this.wss.handleUpgrade(req, socket, head, (ws) => {
                     this.socketAccessValidity.set(ws, isAccessAuthorized);
+                    if (account)
+                        this.accountSocketDevices.set(ws, account.deviceId);
                     this.wss.emit("connection", ws, req);
                 });
             });
@@ -298,12 +388,19 @@ export class RemoteHostManager extends EventEmitter {
                     this.sendBounded(ws, JSON.stringify({ type: "error", message: "Invalid client event" }));
                     return;
                 }
+                const accountDevice = this.accountSocketDevices.get(ws);
+                if (accountDevice &&
+                    (event.type === "pair.complete" ||
+                        (event.type === "auth.device" && event.deviceId !== accountDevice))) {
+                    this.sendBounded(ws, JSON.stringify({ type: "auth.failed", message: "Account device mismatch" }));
+                    return;
+                }
                 // Pairing/auth are handled inline and bind device identity to this
                 // socket. Everything else is gated: an unauthenticated socket cannot
                 // send chat/approval/run/job events (design §6.1).
                 let reply;
                 try {
-                    reply = this.handleClientEvent(event);
+                    reply = this.handleClientEvent(event, accountDevice);
                 }
                 catch {
                     this.sendBounded(ws, JSON.stringify({ type: "error", message: "Client event failed" }));
@@ -390,7 +487,7 @@ export class RemoteHostManager extends EventEmitter {
             url: `http://${bindHost}:${port}`,
             mode: options.mode ?? "lan",
         };
-        if (gate) {
+        if (publicAccess) {
             const sockets = this.wss;
             // Idle public tabs must also relinquish viewer-owned state after rotation.
             // Traffic is checked synchronously in both directions, without rehashing
@@ -453,7 +550,7 @@ export class RemoteHostManager extends EventEmitter {
      * trusted-device store (which rejects revoked devices), so the remote host
      * never executes tools itself — it only gates transport.
      */
-    handleClientEvent(input) {
+    handleClientEvent(input, accountDeviceId) {
         const event = parseMobileClientEvent(input);
         if (!event)
             return { type: "error", message: "Invalid client event" };
@@ -474,11 +571,12 @@ export class RemoteHostManager extends EventEmitter {
             return {
                 type: "pair.ok",
                 device,
-                ...(this.opts.outputJournal || this.opts.nativeModelSelection
+                ...(this.opts.outputJournal || this.opts.nativeModelSelection || this.turnQueueAdvertised
                     ? {
                         capabilities: {
                             ...(this.opts.outputJournal ? { outputJournal: 1 } : {}),
                             ...(this.opts.nativeModelSelection ? { nativeModelSelection: 1 } : {}),
+                            ...(this.turnQueueAdvertised ? { turnQueue: 1 } : {}),
                             ...(this.opts.outputJournal && this.opts.historyView
                                 ? { historyView: 1 }
                                 : {}),
@@ -494,6 +592,8 @@ export class RemoteHostManager extends EventEmitter {
             };
         }
         if (event.type === "auth.device") {
+            if (this.opts.devices.isEphemeralDevice(event.deviceId) && event.deviceId !== accountDeviceId)
+                return { type: "auth.failed", message: "Account device requires its Host access grant" };
             let device;
             try {
                 device = this.opts.devices.authenticate(event.deviceId, event.secretHash);
@@ -506,11 +606,12 @@ export class RemoteHostManager extends EventEmitter {
             return {
                 type: "auth.ok",
                 device,
-                ...(this.opts.outputJournal || this.opts.nativeModelSelection
+                ...(this.opts.outputJournal || this.opts.nativeModelSelection || this.turnQueueAdvertised
                     ? {
                         capabilities: {
                             ...(this.opts.outputJournal ? { outputJournal: 1 } : {}),
                             ...(this.opts.nativeModelSelection ? { nativeModelSelection: 1 } : {}),
+                            ...(this.turnQueueAdvertised ? { turnQueue: 1 } : {}),
                             ...(this.opts.outputJournal && this.opts.historyView
                                 ? { historyView: 1 }
                                 : {}),
@@ -558,6 +659,7 @@ export class RemoteHostManager extends EventEmitter {
     }
     /** Preserve the full worker envelope while retaining exact authenticated-tab routing. */
     sendRawToViewer(viewerId, payload) {
+        payload = stampApprovalClock(payload);
         for (const client of this.wss?.clients ?? []) {
             if (client.readyState === client.OPEN &&
                 this.authed.has(client) &&
@@ -571,6 +673,7 @@ export class RemoteHostManager extends EventEmitter {
     }
     /** Send a raw JSON-RPC worker line to ONLY one authenticated device. */
     sendRawToDevice(deviceId, payload) {
+        payload = stampApprovalClock(payload);
         for (const client of this.wss?.clients ?? []) {
             if (client.readyState === client.OPEN && this.authed.get(client) === deviceId) {
                 this.sendBounded(client, payload);
@@ -581,6 +684,7 @@ export class RemoteHostManager extends EventEmitter {
      *  every authenticated mobile socket. Unauthenticated sockets are skipped so
      *  a half-paired client never sees session output. */
     broadcastRaw(payload) {
+        payload = stampApprovalClock(payload);
         for (const client of this.wss?.clients ?? []) {
             if (client.readyState === client.OPEN && this.authed.has(client)) {
                 this.sendBounded(client, payload);
@@ -614,7 +718,7 @@ export class RemoteHostManager extends EventEmitter {
         this.releaseSocket(client);
         // Distinct from paired-device rejection (4401/4403): the browser keeps its
         // identity and offers a fresh HTTP challenge instead of silently retrying.
-        client.close(4407, "Access passcode changed");
+        client.close(4407, "Host access expired");
         const deadline = setTimeout(() => client.terminate(), 1000);
         deadline.unref();
         client.once("close", () => clearTimeout(deadline));
@@ -647,6 +751,8 @@ export class RemoteHostManager extends EventEmitter {
     }
     /** Call after revoking/removing a trusted device to release both transports immediately. */
     revokeDevice(deviceId) {
+        if (this.accountAccess.revokeDevice(deviceId))
+            return;
         void this.opts.uploads?.revokeDevice(deviceId).catch((error) => {
             this.emit("host-error", error instanceof Error ? error.message : String(error));
         });
@@ -662,6 +768,7 @@ export class RemoteHostManager extends EventEmitter {
         // Listeners synchronously fence and destroy outbound sockets before the
         // loopback listener can close or its port can be reused by another Host.
         this.relayLifetime?.abort();
+        this.accountAccess.clear();
         if (this.stopping)
             return this.stopping;
         const attempt = Promise.resolve()

package/dist/mobile-remote/resident-agent.d.ts

@@ -87,7 +87,13 @@ export interface ResidentAgentOptions {
 export declare class ResidentAgentProcess {
     private readonly opts;
     private child?;
+    /** The most recently spawned process, kept after stop() so a caller can
+     * wait for it to actually exit before starting a replacement. */
+    private lastChild?;
+    private spawned?;
     constructor(opts: ResidentAgentOptions);
+    /** Exact argv for one resident process. Pure → unit-testable. */
+    static argsFor(opts: Pick<ResidentAgentOptions, "permissionMode" | "resumeSessionId" | "appendSystemPrompt">): string[];
     start(): void;
     /** Feed one user turn. Returns false if the process isn't running. */
     send(text: string): boolean;
@@ -95,4 +101,12 @@ export declare class ResidentAgentProcess {
     respondControl(requestId: string, decision: ControlDecision): void;
     isRunning(): boolean;
     stop(): void;
+    /** Resolves once the spawned process exists; rejects when the spawn failed. */
+    whenStarted(): Promise<void>;
+    /**
+     * Stop, then resolve true only after the last spawned process has exited.
+     * A process already retired by a pipe error is still waited for: it may be
+     * alive for up to the SIGKILL grace period.
+     */
+    stopAndWait(timeoutMs: number): Promise<boolean>;
 }

package/dist/mobile-remote/resident-agent.js

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { releaseStdioAfterExit, stopRoomProcess } from "./room-process-stop.js";
+import { releaseStdioAfterExit, stopRoomProcess, stopRoomProcessAndWait, waitForRoomProcessSpawn, } from "./room-process-stop.js";
 import { createInterface } from "node:readline";
 import { pathWithCommonBins } from "./path-bins.js";
 /**
@@ -119,12 +119,15 @@ export function parseStreamJsonLine(line) {
 export class ResidentAgentProcess {
     opts;
     child;
+    /** The most recently spawned process, kept after stop() so a caller can
+     * wait for it to actually exit before starting a replacement. */
+    lastChild;
+    spawned;
     constructor(opts) {
         this.opts = opts;
     }
-    start() {
-        if (this.child)
-            return;
+    /** Exact argv for one resident process. Pure → unit-testable. */
+    static argsFor(opts) {
         const args = [
             "--print",
             "--verbose",
@@ -135,13 +138,17 @@ export class ResidentAgentProcess {
             "--permission-prompt-tool",
             "stdio",
         ];
-        if (this.opts.appendSystemPrompt) {
-            args.push("--append-system-prompt", this.opts.appendSystemPrompt);
-        }
-        if (this.opts.resumeSessionId) {
-            args.push("--resume", this.opts.resumeSessionId);
-        }
-        args.push("--permission-mode", this.opts.permissionMode);
+        if (opts.appendSystemPrompt)
+            args.push("--append-system-prompt", opts.appendSystemPrompt);
+        if (opts.resumeSessionId)
+            args.push("--resume", opts.resumeSessionId);
+        args.push("--permission-mode", opts.permissionMode);
+        return args;
+    }
+    start() {
+        if (this.child)
+            return;
+        const args = ResidentAgentProcess.argsFor(this.opts);
         const child = spawn(this.opts.command, args, {
             cwd: this.opts.cwd,
             env: { ...process.env, PATH: pathWithCommonBins() },
@@ -149,6 +156,10 @@ export class ResidentAgentProcess {
             stdio: ["pipe", "pipe", "pipe"],
         });
         this.child = child;
+        this.lastChild = child;
+        this.spawned = waitForRoomProcessSpawn(child);
+        // Observed by whenStarted(); an unobserved failed spawn is reported via onEvent.
+        this.spawned.catch(() => undefined);
         // Settle on `close` so trailing output is read, without waiting on grandchildren.
         releaseStdioAfterExit(child);
         if (child.stdout) {
@@ -231,4 +242,20 @@ export class ResidentAgentProcess {
         if (child)
             stopRoomProcess(child);
     }
+    /** Resolves once the spawned process exists; rejects when the spawn failed. */
+    whenStarted() {
+        return this.spawned ?? Promise.resolve();
+    }
+    /**
+     * Stop, then resolve true only after the last spawned process has exited.
+     * A process already retired by a pipe error is still waited for: it may be
+     * alive for up to the SIGKILL grace period.
+     */
+    stopAndWait(timeoutMs) {
+        const child = this.child ?? this.lastChild;
+        this.child = undefined;
+        if (!child)
+            return Promise.resolve(true);
+        return stopRoomProcessAndWait(child, timeoutMs);
+    }
 }

package/dist/mobile-remote/room-history.d.ts

@@ -14,6 +14,13 @@ export interface RoomHistoryRequest {
 export declare function scanRoomHistory<T extends {
     seq: number;
 }>(file: string, parse: (value: unknown) => T | undefined, visit?: (message: T) => void): number;
+/** Same strict snapshot proof as scanRoomHistory, yielding between bounded reads. */
+export declare function scanRoomHistoryAsync<T extends {
+    seq: number;
+}>(file: string, parse: (value: unknown) => T | undefined, visit?: (message: T) => void): Promise<{
+    sequence: number;
+    stamp: string;
+}>;
 /** Durable immutable copies keep a frozen page boundary valid across Host restarts. */
 export declare function readRoomHistoryPage<T extends {
     seq: number;

package/dist/mobile-remote/room-history.js

@@ -1,12 +1,15 @@
 import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import { closeSync, constants, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmSync, writeFileSync, writeSync, } from "node:fs";
 import { join } from "node:path";
+import { lstat, open } from "node:fs/promises";
 const MAX_BYTES = 256 * 1024 * 1024;
 const MAX_LINE = 4 * 1024 * 1024;
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 const decoder = new TextDecoder("utf-8", { fatal: true });
 function regular(path) {
-    const stat = lstatSync(path);
+    return assertRegular(lstatSync(path));
+}
+function assertRegular(stat) {
     if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) {
         throw new Error("room history must be a private regular file");
     }
@@ -99,6 +102,58 @@ export function scanRoomHistory(file, parse, visit) {
         closeSync(fd);
     }
 }
+/** Same strict snapshot proof as scanRoomHistory, yielding between bounded reads. */
+export async function scanRoomHistoryAsync(file, parse, visit) {
+    const initial = assertRegular(await lstat(file));
+    const handle = await open(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const before = assertRegular(await handle.stat());
+        if (stamp(initial) !== stamp(before))
+            throw new Error("room history changed while opening");
+        if (before.size > MAX_BYTES)
+            throw new Error("room history exceeds 256 MiB; archive it before continuing");
+        let offset = 0, seq = 0, partialBytes = 0;
+        let parts = [];
+        while (offset < before.size) {
+            const chunk = Buffer.allocUnsafe(Math.min(64 * 1024, before.size - offset));
+            const { bytesRead } = await handle.read(chunk, 0, chunk.length, offset);
+            if (!bytesRead)
+                throw new Error("room history was truncated while reading");
+            offset += bytesRead;
+            let from = 0;
+            while (from < bytesRead) {
+                const next = chunk.indexOf(0x0a, from);
+                const newline = next >= 0 && next < bytesRead ? next : -1;
+                const end = newline < 0 ? bytesRead : newline;
+                const piece = chunk.subarray(from, end);
+                partialBytes += piece.length;
+                if (partialBytes > MAX_LINE)
+                    throw new Error("room history record exceeds size limit");
+                parts.push(piece);
+                if (newline < 0)
+                    break;
+                const bytes = parts.length === 1 ? parts[0] : Buffer.concat(parts, partialBytes);
+                const message = parse(JSON.parse(decoder.decode(bytes)));
+                if (!message || message.seq !== seq + 1)
+                    throw new Error(`room history is corrupt at sequence ${seq + 1}`);
+                seq = message.seq;
+                visit?.(message);
+                parts = [];
+                partialBytes = 0;
+                from = newline + 1;
+            }
+        }
+        if (partialBytes)
+            throw new Error("room history has an incomplete final record");
+        if (stamp(before) !== stamp(await handle.stat()) ||
+            stamp(before) !== stamp(assertRegular(await lstat(file))))
+            throw new Error("room history changed while scanning");
+        return { sequence: seq, stamp: stamp(before) };
+    }
+    finally {
+        await handle.close();
+    }
+}
 function validateManifest(value, roomId, snapshotId) {
     if (!value ||
         value.version !== 1 ||