@world-engines/project-host 0.1.0-alpha.0

package/dist/preview-runtime.js

@@ -0,0 +1,460 @@
+import { spawn } from "node:child_process";
+import { mkdir, readFile, realpath, rm, writeFile } from "node:fs/promises";
+import { createServer } from "node:net";
+import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { removeLocalPreviewViteConfig, writeLocalPreviewViteConfig } from "./local-preview-vite-config.js";
+import { LOCAL_GUI_HOST, LOCAL_GUI_ORIGIN } from "./local-gui-contract.js";
+/** 浏览器使用独立 hostname，避免 127.0.0.1 的 host-only GUI cookie 随 Preview 请求发送。 */
+export const LOCAL_PREVIEW_HOST = "localhost";
+/** Socket 始终绑定 IPv4 loopback，避免 localhost 的 IPv6 DNS 解析歧义。 */
+export const LOCAL_PREVIEW_BIND_HOST = "127.0.0.1";
+export const MAX_PREVIEW_OUTPUT_BYTES = 32 * 1024;
+export class PreviewRuntimeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "PreviewRuntimeError";
+        this.code = code;
+    }
+}
+const CAPABILITY_PREFIX = "/_worldengine_preview/";
+const outputTails = new WeakMap();
+function redactOutputChunk(previous, next) {
+    const combined = previous + next;
+    const complete = combined.replace(/\/_worldengine_preview\/[a-f0-9]{32}\//giu, "/_worldengine_preview/[redacted]/");
+    const marker = complete.lastIndexOf(CAPABILITY_PREFIX);
+    if (marker >= 0 && !complete.slice(marker).startsWith("/_worldengine_preview/[redacted]/")) {
+        return { visible: complete.slice(0, marker), tail: complete.slice(marker) };
+    }
+    for (let length = Math.min(CAPABILITY_PREFIX.length - 1, complete.length); length > 0; length -= 1) {
+        if (complete.endsWith(CAPABILITY_PREFIX.slice(0, length))) {
+            return { visible: complete.slice(0, -length), tail: complete.slice(-length) };
+        }
+    }
+    return { visible: complete, tail: "" };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isInside(root, candidate) {
+    const path = relative(root, candidate);
+    return path === "" || (!path.startsWith(`..${sep}`) && path !== ".." && !isAbsolute(path));
+}
+function copySession(session) {
+    return Object.freeze({ ...session });
+}
+function appendOutput(session, field, truncated, chunk) {
+    if (session[truncated])
+        return;
+    const tails = outputTails.get(session) ?? { stdout: "", stderr: "" };
+    outputTails.set(session, tails);
+    const next = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+    const sanitized = redactOutputChunk(tails[field], next);
+    const text = sanitized.visible;
+    tails[field] = sanitized.tail;
+    const remaining = MAX_PREVIEW_OUTPUT_BYTES - Buffer.byteLength(session[field], "utf8");
+    if (remaining <= 0) {
+        session[truncated] = true;
+        return;
+    }
+    const bytes = Buffer.from(text, "utf8");
+    if (bytes.byteLength <= remaining) {
+        session[field] += text;
+        return;
+    }
+    session[field] += bytes.subarray(0, remaining).toString("utf8");
+    session[truncated] = true;
+}
+export function previewChildEnvironment(base = process.env, nodeExecutable = process.execPath) {
+    const currentPath = base.PATH ?? base.Path ?? base.path ?? "";
+    const nodeDirectory = dirname(nodeExecutable);
+    return {
+        ...base,
+        PATH: currentPath.length === 0 ? nodeDirectory : `${nodeDirectory}${delimiter}${currentPath}`,
+    };
+}
+function spawnForPreview(command, args, cwd) {
+    return spawn(command, args, {
+        cwd,
+        env: previewChildEnvironment(),
+        detached: true,
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+    });
+}
+function previewNpmInvocation() {
+    if (process.platform !== "win32")
+        return { command: "npm", argsPrefix: [] };
+    // npm.cmd 不能与 detached process group 可靠组合；直接运行同一 Node 安装内的 npm CLI。
+    return {
+        command: process.execPath,
+        argsPrefix: [join(dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js")],
+    };
+}
+async function collectProcessOutput(command, args) {
+    return new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn(command, args, { windowsHide: true, stdio: ["ignore", "pipe", "ignore"] });
+        let output = "";
+        child.stdout.on("data", (chunk) => { output += chunk.toString(); });
+        child.once("error", rejectPromise);
+        child.once("exit", (code) => {
+            if (code === 0 || code === 1)
+                resolvePromise(output);
+            else
+                rejectPromise(new Error(`${command} 退出码 ${code ?? 1}`));
+        });
+    });
+}
+async function findListeningPids(port) {
+    if (process.platform !== "win32")
+        return [];
+    const output = await collectProcessOutput("netstat.exe", ["-ano", "-p", "tcp"]);
+    const matcher = new RegExp(`^\\s*TCP\\s+127\\.0\\.0\\.1:${port}\\s+\\S+\\s+LISTENING\\s+(\\d+)\\s*$`, "gim");
+    const pids = new Set();
+    for (const match of output.matchAll(matcher)) {
+        const pid = Number(match[1]);
+        if (Number.isSafeInteger(pid) && pid > 0)
+            pids.add(pid);
+    }
+    return [...pids];
+}
+/**
+ * 先绑定独立 Preview loopback host 的动态端口；调用方在 spawn 前的最后一刻释放它。
+ * Vite 仍以 strictPort 启动，随后必须把监听 PID 回读到本 process tree，不能把抢占的端口当作 Preview。
+ */
+async function reserveLoopbackPort() {
+    const server = createServer();
+    await new Promise((resolvePromise, rejectPromise) => {
+        server.once("error", rejectPromise);
+        server.listen({ host: LOCAL_PREVIEW_BIND_HOST, port: 0 }, () => {
+            server.off("error", rejectPromise);
+            resolvePromise();
+        });
+    });
+    const address = server.address();
+    if (address === null || typeof address === "string" || address.address !== LOCAL_PREVIEW_BIND_HOST || address.port <= 0) {
+        await new Promise((resolvePromise, rejectPromise) => server.close((error) => error === undefined ? resolvePromise() : rejectPromise(error)));
+        throw new PreviewRuntimeError("E_PREVIEW_START_FAILED", "无法保留 loopback Preview 端口");
+    }
+    let released = false;
+    return {
+        port: address.port,
+        async release() {
+            if (released)
+                return;
+            released = true;
+            await new Promise((resolvePromise, rejectPromise) => server.close((error) => error === undefined ? resolvePromise() : rejectPromise(error)));
+        },
+    };
+}
+async function terminateProcessTree(pid) {
+    if (process.platform === "win32") {
+        await collectProcessOutput("taskkill.exe", ["/PID", String(pid), "/T", "/F"]);
+        return;
+    }
+    try {
+        process.kill(-pid, "SIGTERM");
+    }
+    catch (error) {
+        if (error.code !== "ESRCH")
+            throw error;
+    }
+}
+async function getProcessCommandLine(pid) {
+    try {
+        if (process.platform === "win32") {
+            const output = await collectProcessOutput("powershell.exe", [
+                "-NoProfile",
+                "-NonInteractive",
+                "-Command",
+                `Get-CimInstance Win32_Process -Filter 'ProcessId = ${pid}' | Select-Object -ExpandProperty CommandLine`,
+            ]);
+            return output.trim() || null;
+        }
+        if (process.platform === "linux") {
+            return (await readFile(`/proc/${pid}/cmdline`, "utf8")).replaceAll("\0", " ").trim() || null;
+        }
+    }
+    catch {
+        // 无法读到进程身份时必须保持端口占用，不得猜测并终止。
+    }
+    return null;
+}
+async function isProcessInTree(rootPid, pid) {
+    if (rootPid === pid)
+        return true;
+    try {
+        if (process.platform === "win32") {
+            const output = await collectProcessOutput("powershell.exe", [
+                "-NoProfile",
+                "-NonInteractive",
+                "-Command",
+                `$current = ${pid}; while ($current -gt 0) { $process = Get-CimInstance Win32_Process -Filter \"ProcessId = $current\"; if ($null -eq $process) { break }; if ($process.ParentProcessId -eq ${rootPid}) { Write-Output true; exit 0 }; $current = $process.ParentProcessId }; Write-Output false; exit 0`,
+            ]);
+            return output.trim().toLowerCase() === "true";
+        }
+        if (process.platform === "linux") {
+            let current = pid;
+            while (current > 0) {
+                const fields = (await readFile(`/proc/${current}/stat`, "utf8")).split(" ");
+                const parent = Number(fields[3]);
+                if (parent === rootPid)
+                    return true;
+                if (!Number.isSafeInteger(parent) || parent <= 0 || parent === current)
+                    return false;
+                current = parent;
+            }
+        }
+    }
+    catch {
+        // 身份不可验证时必须 fail closed，不能把同端口的其他服务认作 Preview。
+    }
+    return false;
+}
+function ledgerPath(projectRoot) {
+    return join(projectRoot, ".worldengine", "preview-session.json");
+}
+function isPreviewSessionLedger(value) {
+    return isRecord(value)
+        && value.schema_version === 1
+        && typeof value.session_id === "string"
+        && typeof value.project_root === "string"
+        && typeof value.cwd === "string"
+        && typeof value.port === "number"
+        && Number.isSafeInteger(value.port)
+        && value.port > 0
+        && value.port <= 65535
+        && typeof value.pid === "number"
+        && Number.isSafeInteger(value.pid)
+        && value.pid > 0
+        && (value.url === undefined || typeof value.url === "string");
+}
+async function readPreviewSessionLedger(projectRoot) {
+    try {
+        const value = JSON.parse(await readFile(ledgerPath(projectRoot), "utf8"));
+        return isPreviewSessionLedger(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 跨进程只读 owner 探针；只返回 PID、listener 与 cwd 三者都能验证的 live ledger。 */
+export async function readLivePreviewSessionOwner(projectRoot) {
+    const root = await realpath(resolve(projectRoot));
+    const ledger = await readPreviewSessionLedger(root);
+    if (ledger === null || ledger.project_root !== root || ledger.cwd !== await realpath(join(root, "view")))
+        return null;
+    if (!(await findListeningPids(ledger.port)).includes(ledger.pid))
+        return null;
+    const commandLine = await getProcessCommandLine(ledger.pid);
+    if (commandLine === null || !commandReferencesPath(commandLine, ledger.cwd))
+        return null;
+    if (typeof ledger.url !== "string")
+        return null;
+    let url;
+    try {
+        url = new URL(ledger.url);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== "http:" || url.hostname !== LOCAL_PREVIEW_HOST || Number(url.port) !== ledger.port
+        || !/^\/_worldengine_preview\/[a-f0-9]{32}\/$/u.test(url.pathname) || url.search || url.hash)
+        return null;
+    return Object.freeze({ session_id: ledger.session_id, pid: ledger.pid, port: ledger.port, project_root: root, cwd: ledger.cwd, url: url.href });
+}
+async function writePreviewSessionLedger(session) {
+    if (session.pid === null)
+        throw new PreviewRuntimeError("E_PREVIEW_START_FAILED", "Preview 进程未返回 PID");
+    const path = ledgerPath(session.project_root);
+    await mkdir(join(session.project_root, ".worldengine"), { recursive: true });
+    await writeFile(path, `${JSON.stringify({
+        schema_version: 1,
+        session_id: session.session_id,
+        project_root: session.project_root,
+        cwd: session.cwd,
+        port: session.port,
+        pid: session.pid,
+        url: session.url,
+    })}\n`, "utf8");
+}
+async function clearPreviewSessionLedger(session) {
+    const ledger = await readPreviewSessionLedger(session.project_root);
+    if (ledger?.session_id === session.session_id && ledger.pid === session.pid) {
+        await rm(ledgerPath(session.project_root), { force: true });
+    }
+}
+function commandReferencesPath(commandLine, path) {
+    return commandLine.replaceAll("/", "\\").toLowerCase().includes(path.replaceAll("/", "\\").toLowerCase());
+}
+/** ProjectHost 的本地 Vite Preview 生命周期；每个 session 独占一个内核分配的 loopback 端口。 */
+export class LocalPreviewRuntime {
+    #now;
+    #newSessionId;
+    #spawn;
+    #findListeningPids;
+    #getProcessCommandLine;
+    #isProcessInTree;
+    #terminateProcessTree;
+    #reserveLoopbackPort;
+    #session = null;
+    #configPath = null;
+    #basePath = "/";
+    #parentOrigin = LOCAL_GUI_ORIGIN;
+    #childClosed = null;
+    constructor(dependencies = {}) {
+        this.#now = dependencies.now ?? Date.now;
+        this.#newSessionId = dependencies.newSessionId ?? (() => crypto.randomUUID());
+        this.#spawn = dependencies.spawn ?? spawnForPreview;
+        this.#findListeningPids = dependencies.findListeningPids ?? findListeningPids;
+        this.#getProcessCommandLine = dependencies.getProcessCommandLine ?? getProcessCommandLine;
+        this.#isProcessInTree = dependencies.isProcessInTree ?? isProcessInTree;
+        this.#terminateProcessTree = dependencies.terminateProcessTree ?? terminateProcessTree;
+        this.#reserveLoopbackPort = dependencies.reserveLoopbackPort ?? reserveLoopbackPort;
+    }
+    async start(projectRoot, parentOrigin = LOCAL_GUI_ORIGIN) {
+        let parent;
+        try {
+            parent = new URL(parentOrigin);
+        }
+        catch {
+            throw new PreviewRuntimeError("E_PREVIEW_START_FAILED", "Preview parent origin 无效");
+        }
+        if (parent.protocol !== "http:" || parent.hostname !== LOCAL_GUI_HOST || parent.port === "" || parent.pathname !== "/" || parent.search !== "" || parent.hash !== "" || parent.username !== "" || parent.password !== "") {
+            throw new PreviewRuntimeError("E_PREVIEW_START_FAILED", "Preview parent origin 无效");
+        }
+        const trustedParentOrigin = parent.origin;
+        const root = await realpath(resolve(projectRoot));
+        const view = await realpath(join(root, "view"));
+        if (!isInside(root, view) || view === root) {
+            throw new PreviewRuntimeError("E_PATH_OUTSIDE_PROJECT", "Preview cwd 必须是项目内 view/");
+        }
+        if (this.#session?.state === "starting" || this.#session?.state === "running") {
+            if (this.#session.project_root === root && this.#parentOrigin === trustedParentOrigin)
+                return copySession(this.#session);
+            await this.stop();
+        }
+        const ledger = await readPreviewSessionLedger(root);
+        const listeningPids = ledger === null ? [] : await this.#findListeningPids(ledger.port);
+        if (ledger?.project_root === root && ledger.cwd === view && listeningPids.includes(ledger.pid)) {
+            const commandLine = await this.#getProcessCommandLine(ledger.pid);
+            if (commandLine !== null && commandReferencesPath(commandLine, view)) {
+                await this.#terminateProcessTree(ledger.pid);
+                await clearPreviewSessionLedger({ ...ledger, url: `http://${LOCAL_PREVIEW_HOST}:${ledger.port}/`, state: "stopped", started_at_ms: 0, stopped_at_ms: 0, exit_code: null, stdout: "", stderr: "", stdout_truncated: false, stderr_truncated: false });
+            }
+        }
+        const reservation = await this.#reserveLoopbackPort();
+        const npm = previewNpmInvocation();
+        let child;
+        try {
+            const config = await writeLocalPreviewViteConfig(root, view, reservation.port, trustedParentOrigin);
+            this.#configPath = config.path;
+            this.#basePath = config.basePath;
+            this.#parentOrigin = trustedParentOrigin;
+            await reservation.release();
+            child = this.#spawn(npm.command, [...npm.argsPrefix, "--prefix", view, "run", "dev", "--", "--config", config.path, "--host", LOCAL_PREVIEW_BIND_HOST, "--port", String(reservation.port), "--strictPort"], view);
+        }
+        catch (error) {
+            await reservation.release();
+            if (this.#configPath !== null)
+                await removeLocalPreviewViteConfig(root, this.#configPath);
+            this.#configPath = null;
+            throw error;
+        }
+        const session = {
+            session_id: this.#newSessionId(),
+            project_root: root,
+            cwd: view,
+            url: `http://${LOCAL_PREVIEW_HOST}:${reservation.port}${this.#basePath}`,
+            port: reservation.port,
+            state: "starting",
+            pid: child.pid ?? null,
+            started_at_ms: this.#now(),
+            stopped_at_ms: null,
+            exit_code: null,
+            stdout: "",
+            stderr: "",
+            stdout_truncated: false,
+            stderr_truncated: false,
+        };
+        this.#session = session;
+        this.#childClosed = new Promise((resolvePromise) => {
+            child.once("close", () => resolvePromise());
+        });
+        try {
+            await writePreviewSessionLedger(session);
+        }
+        catch (error) {
+            this.#session = null;
+            if (session.pid !== null)
+                await this.#terminateProcessTree(session.pid);
+            if (error instanceof PreviewRuntimeError)
+                throw error;
+            throw new PreviewRuntimeError("E_PREVIEW_START_FAILED", "无法持久化 Preview session ledger");
+        }
+        child.stdout.on("data", (chunk) => {
+            appendOutput(session, "stdout", "stdout_truncated", chunk);
+            void this.#verifyReadyListener(session);
+        });
+        child.stderr.on("data", (chunk) => appendOutput(session, "stderr", "stderr_truncated", chunk));
+        child.once("error", (error) => {
+            appendOutput(session, "stderr", "stderr_truncated", error.stack ?? error.message);
+            session.state = "failed";
+            session.stopped_at_ms = this.#now();
+            void clearPreviewSessionLedger(session);
+        });
+        child.once("exit", (code) => {
+            session.exit_code = code;
+            session.stopped_at_ms = this.#now();
+            if (session.state !== "stopped")
+                session.state = code === 0 ? "stopped" : "failed";
+            void clearPreviewSessionLedger(session);
+        });
+        child.once("close", () => {
+            const configPath = this.#configPath;
+            this.#configPath = null;
+            this.#childClosed = null;
+            if (configPath !== null)
+                void removeLocalPreviewViteConfig(session.project_root, configPath);
+        });
+        return copySession(session);
+    }
+    async #verifyReadyListener(session) {
+        if (session !== this.#session || session.state !== "starting" || session.pid === null)
+            return;
+        if (!session.stdout.includes(`http://${LOCAL_PREVIEW_BIND_HOST}:${session.port}`))
+            return;
+        const pids = await this.#findListeningPids(session.port);
+        for (const pid of pids) {
+            if (await this.#isProcessInTree(session.pid, pid)) {
+                session.state = "running";
+                return;
+            }
+        }
+        appendOutput(session, "stderr", "stderr_truncated", "Preview ready 后未在 child process tree 中验证 loopback listener PID");
+        session.state = "failed";
+        session.stopped_at_ms = this.#now();
+        await this.#terminateProcessTree(session.pid);
+        await clearPreviewSessionLedger(session);
+    }
+    inspect() {
+        return this.#session === null ? null : copySession(this.#session);
+    }
+    async stop() {
+        const session = this.#session;
+        if (session === null)
+            return null;
+        if (session.pid !== null && (session.state === "starting" || session.state === "running")) {
+            await this.#terminateProcessTree(session.pid);
+            if (this.#childClosed !== null)
+                await this.#childClosed;
+        }
+        if (session.state === "starting" || session.state === "running") {
+            session.state = "stopped";
+            session.stopped_at_ms = this.#now();
+        }
+        await clearPreviewSessionLedger(session);
+        // 配置只在 child stdio/handle 真正 close 后清理，避免 Windows 下 Vite 仍持有 view/。
+        return copySession(session);
+    }
+}

package/dist/project-auth-transport.d.ts

@@ -0,0 +1,27 @@
+import type { ProjectTransferTransport } from "./transfer/transport.js";
+/** 与 native broker 一致；覆盖 96 MiB author-source wire 加 JSON response 外壳。 */
+export declare const PROJECT_AUTH_MAX_RESPONSE_BYTES: number;
+/** 与 Edge frozen-artifacts JSON body gate 一致。 */
+export declare const PROJECT_AUTH_MAX_HTTP_REQUEST_BYTES: number;
+/** body_json 作为 pipe 外层 JSON 字符串传输时的统一 envelope gate。 */
+export declare const PROJECT_AUTH_MAX_PIPE_REQUEST_BYTES: number;
+export interface ProjectBoundBrokerCapability {
+    readonly pipe_name: string;
+    readonly challenge_id: string;
+    readonly challenge: string;
+    readonly expires_at_ms: number;
+}
+export interface ProjectAuthTransportEnvironment {
+    readonly WORLDENGINE_PROJECT_TRANSFER_PIPE?: string;
+    readonly WORLDENGINE_PROJECT_TRANSFER_CHALLENGE_ID?: string;
+    readonly WORLDENGINE_PROJECT_TRANSFER_CHALLENGE?: string;
+    readonly WORLDENGINE_PROJECT_TRANSFER_EXPIRES_AT_MS?: string;
+}
+/** 只供同模块测试验证有界累计；错误不包含 payload、capability 或 secret。 */
+export declare function appendProjectAuthResponseChunk(chunks: Buffer[], total: number, chunk: Buffer): number;
+export declare function assertProjectAuthRequestBudget(bodyByteLength: number, envelopeByteLength: number): void;
+/**
+ * CLI production composition：只消费 desktop 注入的短期 named-pipe capability。
+ * 环境中没有 URL、cookie 或 header authority；SID/project/challenge 仍由 native broker 复验。
+ */
+export declare function createProjectAuthTransport(projectId: string, environment?: ProjectAuthTransportEnvironment): Promise<ProjectTransferTransport | undefined>;

package/dist/project-auth-transport.js

@@ -0,0 +1,121 @@
+import { execFile } from "node:child_process";
+import { createConnection } from "node:net";
+import { promisify } from "node:util";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+const execFileAsync = promisify(execFile);
+const PIPE_PATTERN = /^\\\\\.\\pipe\\worldengine-project-transfer-auth-[a-f0-9]{64}$/i;
+/** 与 native broker 一致；覆盖 96 MiB author-source wire 加 JSON response 外壳。 */
+export const PROJECT_AUTH_MAX_RESPONSE_BYTES = 128 * 1024 * 1024;
+/** 与 Edge frozen-artifacts JSON body gate 一致。 */
+export const PROJECT_AUTH_MAX_HTTP_REQUEST_BYTES = 96 * 1024 * 1024;
+/** body_json 作为 pipe 外层 JSON 字符串传输时的统一 envelope gate。 */
+export const PROJECT_AUTH_MAX_PIPE_REQUEST_BYTES = 128 * 1024 * 1024;
+function capabilityFromEnvironment(environment) {
+    const values = [environment.WORLDENGINE_PROJECT_TRANSFER_PIPE, environment.WORLDENGINE_PROJECT_TRANSFER_CHALLENGE_ID, environment.WORLDENGINE_PROJECT_TRANSFER_CHALLENGE, environment.WORLDENGINE_PROJECT_TRANSFER_EXPIRES_AT_MS];
+    if (values.every((value) => value === undefined))
+        return undefined;
+    const [pipe_name, challenge_id, challenge, expires] = values;
+    const expires_at_ms = Number(expires);
+    if (pipe_name === undefined || !PIPE_PATTERN.test(pipe_name) || challenge_id === undefined || !/^[0-9a-f-]{36}$/i.test(challenge_id) || challenge === undefined || challenge.length < 32 || challenge.length > 256 || !Number.isSafeInteger(expires_at_ms) || expires_at_ms <= Date.now()) {
+        throw new AuthoringBridgeError("E_AUTH_REQUIRED", "ProjectAuthBroker capability 无效或已过期");
+    }
+    return { pipe_name, challenge_id, challenge, expires_at_ms };
+}
+async function currentWindowsSid() {
+    const { stdout } = await execFileAsync("whoami", ["/user", "/fo", "csv", "/nh"], { windowsHide: true });
+    const sid = stdout.split(",").map((value) => value.trim().replace(/^"|"$/g, "")).find((value) => /^S-1-[0-9-]+$/i.test(value));
+    if (sid === undefined)
+        throw new AuthoringBridgeError("E_AUTH_REQUIRED", "Windows SID 无法验证");
+    return sid;
+}
+function base64(bytes) { return Buffer.from(bytes).toString("base64"); }
+/** 只供同模块测试验证有界累计；错误不包含 payload、capability 或 secret。 */
+export function appendProjectAuthResponseChunk(chunks, total, chunk) {
+    const next = total + chunk.length;
+    if (!Number.isSafeInteger(next) || next > PROJECT_AUTH_MAX_RESPONSE_BYTES) {
+        throw new AuthoringBridgeError("E_VALIDATION_FAILED", "ProjectAuthBroker 响应过大");
+    }
+    chunks.push(chunk);
+    return next;
+}
+export function assertProjectAuthRequestBudget(bodyByteLength, envelopeByteLength) {
+    if (!Number.isSafeInteger(bodyByteLength)
+        || bodyByteLength < 0
+        || bodyByteLength > PROJECT_AUTH_MAX_HTTP_REQUEST_BYTES
+        || !Number.isSafeInteger(envelopeByteLength)
+        || envelopeByteLength < 0
+        || envelopeByteLength > PROJECT_AUTH_MAX_PIPE_REQUEST_BYTES) {
+        throw new AuthoringBridgeError("E_VALIDATION_FAILED", "ProjectAuthBroker 请求过大");
+    }
+}
+async function pipeRequest(pipe, payload) {
+    return new Promise((resolvePromise, rejectPromise) => {
+        const socket = createConnection(pipe);
+        const chunks = [];
+        let total = 0;
+        const fail = (error) => { socket.destroy(); rejectPromise(error); };
+        socket.setTimeout(10_000, () => fail(new AuthoringBridgeError("E_AUTH_REQUIRED", "ProjectAuthBroker 响应超时")));
+        socket.once("connect", () => socket.write(`${payload}\n`));
+        socket.on("data", (chunk) => {
+            try {
+                total = appendProjectAuthResponseChunk(chunks, total, chunk);
+            }
+            catch (error) {
+                fail(error);
+            }
+        });
+        socket.once("error", () => fail(new AuthoringBridgeError("E_AUTH_REQUIRED", "ProjectAuthBroker 不可用")));
+        socket.once("end", () => {
+            try {
+                resolvePromise(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+            }
+            catch {
+                rejectPromise(new AuthoringBridgeError("E_VALIDATION_FAILED", "ProjectAuthBroker 响应无效"));
+            }
+        });
+    });
+}
+/**
+ * CLI production composition：只消费 desktop 注入的短期 named-pipe capability。
+ * 环境中没有 URL、cookie 或 header authority；SID/project/challenge 仍由 native broker 复验。
+ */
+export async function createProjectAuthTransport(projectId, environment = process.env) {
+    if (!projectId || projectId.length > 256)
+        throw new AuthoringBridgeError("E_SCHEMA_INVALID", "project_id 无效");
+    const capability = capabilityFromEnvironment(environment);
+    if (capability === undefined)
+        return undefined;
+    await currentWindowsSid();
+    return Object.freeze({
+        async request(request) {
+            if (request.project_id !== projectId || capability.expires_at_ms <= Date.now())
+                throw new AuthoringBridgeError("E_AUTH_REQUIRED", "ProjectAuthBroker project/capability 已失效");
+            const bytes = request.body instanceof Uint8Array ? request.body : undefined;
+            const bodyJson = bytes === undefined && request.body !== undefined ? JSON.stringify(request.body) : undefined;
+            const payload = JSON.stringify({
+                project_id: projectId,
+                challenge_id: capability.challenge_id,
+                challenge: capability.challenge,
+                method: request.method,
+                path: request.path,
+                ...(request.content_type === undefined ? {} : { content_type: request.content_type }),
+                ...(request.operation_id === undefined ? {} : { operation_id: request.operation_id }),
+                ...(bodyJson === undefined ? {} : { body_json: bodyJson }),
+                ...(bytes === undefined ? {} : { body_base64: base64(bytes) }),
+                ...(request.body_digest === undefined ? {} : { body_digest: request.body_digest }),
+                ...(request.body_size === undefined ? {} : { body_size: request.body_size }),
+                ...(request.raw_body_digest === undefined ? {} : { raw_body_digest: request.raw_body_digest }),
+                ...(request.raw_body_size === undefined ? {} : { raw_body_size: request.raw_body_size }),
+                ...(request.body_codec === undefined ? {} : { body_codec: request.body_codec }),
+            });
+            assertProjectAuthRequestBudget(bytes?.byteLength ?? (bodyJson === undefined ? 0 : Buffer.byteLength(bodyJson, "utf8")), Buffer.byteLength(payload, "utf8") + 1);
+            const response = await pipeRequest(capability.pipe_name, payload);
+            if (typeof response !== "object" || response === null || Array.isArray(response) || "error" in response)
+                throw new AuthoringBridgeError("E_AUTH_REQUIRED", "ProjectAuthBroker 请求被拒绝");
+            const value = response;
+            if (typeof value.status !== "number" || !Number.isInteger(value.status))
+                throw new AuthoringBridgeError("E_VALIDATION_FAILED", "ProjectAuthBroker 响应 status 无效");
+            return { status: value.status, body: value.body, ...(value.readback === undefined ? {} : { readback: value.readback }) };
+        },
+    });
+}

package/dist/project-auth.d.ts

@@ -0,0 +1,51 @@
+/** 登录状态只描述 broker 是否有可用的外部会话；cookie 永远不离开 WebView。 */
+export type ProjectAuthState = "signed_out" | "challenge_pending" | "signed_in";
+export interface ProjectAuthPaths {
+    readonly project_root: string;
+    readonly auth_directory: string;
+    readonly webview_data_directory: string;
+}
+/** Pipe 身份必须同时绑定当前 Windows identity、项目和一次性 challenge。 */
+export interface ProjectAuthBrokerIdentity {
+    readonly windows_user_id: string;
+    readonly project_id: string;
+}
+export interface ProjectAuthChallenge {
+    readonly challenge_id: string;
+    readonly challenge: string;
+    readonly expires_at_ms: number;
+}
+/**
+ * 外部 adapter 是唯一可以与认证服务或 WebView cookie jar 交互的边界。
+ * 这些接口特意不包含 token/cookie 字段，避免 CLI 或项目日志取得密钥材料。
+ */
+export interface ProjectAuthAdapter {
+    beginChallenge(identity: ProjectAuthBrokerIdentity, webviewDataDirectory: string): Promise<ProjectAuthChallenge>;
+    completeChallenge(identity: ProjectAuthBrokerIdentity, challenge: ProjectAuthChallenge, webviewDataDirectory: string): Promise<void>;
+    logout(identity: ProjectAuthBrokerIdentity, webviewDataDirectory: string): Promise<void>;
+}
+/** 将任意项目相对位置安全地解析到给定项目根内。 */
+export declare function resolveProjectAuthPath(projectRoot: string, projectRelativePath: string): string;
+/** auth 与 WebView profile 固定在项目根，绝不退回到用户目录或共享 app data。 */
+export declare function resolveProjectAuthPaths(projectRoot: string): ProjectAuthPaths;
+/**
+ * 项目级 broker。它不保存会话凭据：没有可用的外部 adapter 时只能保持 signed_out。
+ */
+export declare class ProjectAuthBroker {
+    #private;
+    readonly identity: ProjectAuthBrokerIdentity;
+    readonly paths: ProjectAuthPaths;
+    private constructor();
+    static open(projectRoot: string, identity: ProjectAuthBrokerIdentity, adapter?: ProjectAuthAdapter): Promise<ProjectAuthBroker>;
+    get state(): ProjectAuthState;
+    beginLogin(): Promise<ProjectAuthChallenge>;
+    completeLogin(challengeId: string): Promise<void>;
+    logout(): Promise<void>;
+    /** 可安全记录的诊断；故意不包含 challenge、cookie、token 或 WebView 内容。 */
+    diagnostic(): Readonly<{
+        project_id: string;
+        auth_state: ProjectAuthState;
+        auth_directory: string;
+        webview_data_directory: string;
+    }>;
+}