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

package/dist/local-gui-auth.js

@@ -0,0 +1,703 @@
+import { createHash, randomBytes } from "node:crypto";
+import { AuthoringBridgeError } from "@world-engines/authoring-bridge";
+import { MeResponse } from "@world-engines/protocol-ts/v1/rest/auth";
+import { WalletResponse } from "@world-engines/protocol-ts/v1/rest/billing";
+import { isKnownScenarioTag } from "@world-engines/authoring-ui/score-tags";
+import { readFrozenReviewTargetBinding } from "./frozen-review-local-pipeline.js";
+const API_ORIGIN = "https://api.late-frost.com";
+const CALLBACK_PATH = "/desktop-login/callback";
+const AUTHORIZATION_PATH = "/desktop-login";
+const MAX_AUTH_RESPONSE_BYTES = 64 * 1024;
+const MAX_TRANSFER_REQUEST_BYTES = 96 * 1024 * 1024;
+const MAX_TRANSFER_RESPONSE_BYTES = 128 * 1024 * 1024;
+const MAX_MODEL_RESPONSE_BYTES = 16 * 1024 * 1024;
+/** server 的 CSP form-action 必须复用此精确授权 origin 列表。 */
+export const LOCAL_GUI_AUTHORIZATION_ORIGINS = Object.freeze([
+    "https://late-frost.com",
+    "https://world-engines.org",
+]);
+const AUTHORIZATION_ORIGINS = new Set(LOCAL_GUI_AUTHORIZATION_ORIGINS);
+const PROJECT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/u;
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+const PKCE_PATTERN = /^[A-Za-z0-9_-]{43}$/u;
+const SHA256_PATTERN = /^[0-9a-f]{64}$/u;
+const ACCOUNT_MODEL_SESSION_PATH = "/v1/developer/account-models/session";
+const ACCOUNT_MODEL_CHAT_CATALOG_PATH = "/v1/developer/account-models/chat/catalog";
+const ACCOUNT_MODEL_EMBEDDING_DESCRIPTOR_PATH = "/v1/developer/account-models/embedding/descriptor";
+const ACCOUNT_MODEL_EMBEDDING_PATH = "/v1/developer/account-models/openai/v1/embeddings";
+const ACCOUNT_MODEL_CHAT_COMPLETIONS_PATH = "/v1/developer/account-models/openai/v1/chat/completions";
+const IDEMPOTENCY_KEY_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/u;
+const MODEL_SESSION_LEASES = new WeakMap();
+function fail(code, message) {
+    throw new AuthoringBridgeError(code, message);
+}
+function normalizeLoopbackOrigin(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        fail("E_SCHEMA_INVALID", "local GUI loopback origin 无效");
+    }
+    if (url.protocol !== "http:" || url.hostname !== "127.0.0.1" || url.port === ""
+        || url.username !== "" || url.password !== "" || url.pathname !== "/"
+        || url.search !== "" || url.hash !== "") {
+        fail("E_SCHEMA_INVALID", "local GUI loopback origin 必须是 127.0.0.1 的纯 HTTP origin");
+    }
+    return url;
+}
+function randomPkce() { return randomBytes(32).toString("base64url"); }
+function sha256(value) { return createHash("sha256").update(value).digest("hex"); }
+function object(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+async function boundedBytes(response, limit, errorMessage) {
+    const declared = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > limit)
+        fail("E_VALIDATION_FAILED", errorMessage);
+    if (response.body === null)
+        return new Uint8Array();
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        while (true) {
+            const item = await reader.read();
+            if (item.done)
+                break;
+            total += item.value.byteLength;
+            if (!Number.isSafeInteger(total) || total > limit) {
+                await reader.cancel().catch(() => undefined);
+                fail("E_VALIDATION_FAILED", errorMessage);
+            }
+            chunks.push(item.value);
+        }
+    }
+    catch (error) {
+        if (error instanceof AuthoringBridgeError)
+            throw error;
+        fail("E_VALIDATION_FAILED", errorMessage);
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}
+async function boundedJson(response, limit, errorMessage) {
+    const bytes = await boundedBytes(response, limit, errorMessage);
+    try {
+        const value = object(JSON.parse(new TextDecoder().decode(bytes)));
+        if (value !== undefined)
+            return value;
+    }
+    catch { /* 统一映射为不包含远端 body 的公开错误。 */ }
+    fail("E_VALIDATION_FAILED", errorMessage);
+}
+function assertAuthorizationUrl(value, pending) {
+    if (typeof value !== "string" || value.length > 4096)
+        fail("E_VALIDATION_FAILED", "远端认证服务返回无效授权 URL");
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        fail("E_VALIDATION_FAILED", "远端认证服务返回无效授权 URL");
+    }
+    const keys = [...url.searchParams.keys()];
+    if (!AUTHORIZATION_ORIGINS.has(url.origin) || url.pathname !== AUTHORIZATION_PATH
+        || url.username !== "" || url.password !== "" || url.hash !== ""
+        || keys.length !== 2 || new Set(keys).size !== 2
+        || url.searchParams.get("request_id") !== pending.requestId
+        || url.searchParams.get("state") !== pending.state) {
+        fail("E_VALIDATION_FAILED", "远端认证服务授权 URL 未通过 allowlist");
+    }
+    return url.toString();
+}
+function parseHttpOnlyCookie(header) {
+    if (header === null || !/(?:^|;)\s*HttpOnly(?:;|$)/iu.test(header)) {
+        fail("E_AUTH_REQUIRED", "远端认证服务未建立 HttpOnly session");
+    }
+    const first = header.split(";", 1)[0]?.trim() ?? "";
+    const separator = first.indexOf("=");
+    const name = separator < 0 ? "" : first.slice(0, separator);
+    const value = separator < 0 ? "" : first.slice(separator + 1);
+    if (!/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/u.test(name) || value.length === 0 || /[\x00-\x20\x7f;,]/u.test(value)) {
+        fail("E_AUTH_REQUIRED", "远端认证服务返回无效 HttpOnly session");
+    }
+    return Object.freeze({ pair: `${name}=${value}` });
+}
+function decodedStrictSegment(value) {
+    if (value.length === 0 || value.length > 768 || value.includes("/") || value.includes("\\"))
+        return undefined;
+    let decoded;
+    try {
+        decoded = decodeURIComponent(value);
+    }
+    catch {
+        return undefined;
+    }
+    return decoded.length <= 256 && /^[A-Za-z0-9_-]+$/u.test(decoded) ? decoded : undefined;
+}
+function operationSuffix(value, prefix) {
+    const parts = value.slice(prefix.length).split("/");
+    return decodedStrictSegment(parts[0] ?? "") !== undefined
+        && (parts.length === 1 || (parts.length === 2 && ["reconcile", "retry", "undo"].includes(parts[1] ?? "")));
+}
+/** 为 npm GUI adapter 镜像 native broker 的 project-transfer route allowlist。 */
+export function isLocalGuiTransferRouteAllowed(method, path) {
+    const prefix = "/v1/creator/project-transfer/";
+    if (!path.startsWith(prefix) || path.includes("?") || path.includes("//") || path.includes("\\"))
+        return false;
+    if ((method === "GET" && path === `${prefix}inventory`)
+        || (method === "POST" && ["upload-plans", "upload/confirm", "download/plan", "download/confirm"].some((suffix) => path === `${prefix}${suffix}`)))
+        return true;
+    for (const [candidateMethod, candidatePrefix] of [
+        ["PUT", `${prefix}upload-staging/`], ["PUT", `${prefix}staging/`],
+        ["HEAD", `${prefix}upload-staging/`], ["HEAD", `${prefix}staging/`],
+        ["GET", `${prefix}download/staging/`],
+    ]) {
+        if (method === candidateMethod && path.startsWith(candidatePrefix))
+            return decodedStrictSegment(path.slice(candidatePrefix.length)) !== undefined;
+    }
+    for (const candidatePrefix of [`${prefix}operations/`, `${prefix}download/operations/`]) {
+        if ((method === "GET" || method === "POST") && path.startsWith(candidatePrefix))
+            return operationSuffix(path, candidatePrefix);
+    }
+    return false;
+}
+function redact(value) {
+    if (Array.isArray(value))
+        return value.map(redact);
+    const source = object(value);
+    if (source === undefined)
+        return value;
+    return Object.fromEntries(Object.entries(source).map(([key, item]) => [
+        key,
+        /cookie|token|authorization|session|secret/iu.test(key) ? "[redacted]" : redact(item),
+    ]));
+}
+function projectModelResponse(kind, status, value) {
+    if (status < 200 || status >= 300) {
+        const error = object(value.error);
+        // embedding 和 chat 都可能在已扣费后丢失 provider 响应；必须保留同一
+        // 幂等键的持久终态，不能让本地代理把它降格为可换 key 的普通失败。
+        if ((kind === "chat_completions" || kind === "embedding") && error?.code === "E_OPERATION_UNCERTAIN") {
+            const projected = Object.fromEntries([
+                "operation_id", "status", "ledger_status", "provider_result_sha256", "retryable", "retry_policy",
+            ].filter((key) => value[key] !== undefined).map((key) => [key, value[key]]));
+            return Object.freeze({ ...projected, error: Object.freeze({ code: "E_OPERATION_UNCERTAIN" }) });
+        }
+        return Object.freeze({});
+    }
+    if (kind === "session") {
+        return Object.freeze(Object.fromEntries(["principal_id", "project_id"]
+            .filter((key) => typeof value[key] === "string")
+            .map((key) => [key, value[key]])));
+    }
+    if (kind === "chat_catalog") {
+        const projectedModels = Array.isArray(value.models) ? value.models.map((item) => {
+            const source = object(item);
+            return source === undefined ? null : Object.freeze({
+                model: source.model,
+                max_output_tokens: source.max_output_tokens,
+            });
+        }) : value.models;
+        return Object.freeze({ ...Object.fromEntries([
+                "principal_id", "project_id", "catalog_digest",
+            ].filter((key) => value[key] !== undefined).map((key) => [key, value[key]])), models: projectedModels });
+    }
+    if (kind === "embedding_descriptor") {
+        const inputKinds = object(value.input_kinds);
+        const projectedInputKinds = inputKinds === undefined ? value.input_kinds : Object.freeze(Object.fromEntries(["document", "query"].map((inputKind) => {
+            const source = object(inputKinds[inputKind]);
+            return [inputKind, source === undefined ? null : Object.freeze({
+                    prompt_version: source.prompt_version,
+                    descriptor_sha256: source.descriptor_sha256,
+                })];
+        })));
+        return Object.freeze({ ...Object.fromEntries([
+                "principal_id", "project_id", "provider", "model", "dimensions", "max_inputs", "max_input_chars", "descriptor_sha256",
+            ].filter((key) => value[key] !== undefined).map((key) => [key, value[key]])), input_kinds: projectedInputKinds });
+    }
+    if (kind === "chat_completions") {
+        return Object.freeze(Object.fromEntries([
+            "id", "object", "created", "model", "provider", "choices", "usage", "operation_id", "principal_id", "project_id", "cost_status",
+        ].filter((key) => value[key] !== undefined).map((key) => [key, value[key]])));
+    }
+    const projectedData = Array.isArray(value.data) ? value.data.map((item) => {
+        const source = object(item);
+        return source === undefined ? null : Object.freeze({ object: source.object, index: source.index, embedding: source.embedding });
+    }) : value.data;
+    const sourceUsage = object(value.usage);
+    const usage = sourceUsage === undefined ? value.usage : Object.freeze({
+        prompt_tokens: sourceUsage.prompt_tokens,
+        total_tokens: sourceUsage.total_tokens,
+        charged_units: sourceUsage.charged_units,
+        currency: sourceUsage.currency,
+        ledger_unit_scale: sourceUsage.ledger_unit_scale,
+        ledger_version: sourceUsage.ledger_version,
+    });
+    return Object.freeze({
+        object: value.object,
+        data: projectedData,
+        model: value.model,
+        provider: value.provider,
+        dimensions: value.dimensions,
+        input_kind: value.input_kind,
+        usage,
+        operation_id: value.operation_id,
+        principal_id: value.principal_id,
+        project_id: value.project_id,
+    });
+}
+function requestBytes(body) {
+    if (body === undefined)
+        return new Uint8Array();
+    if (body instanceof Uint8Array)
+        return body;
+    let encoded;
+    try {
+        encoded = JSON.stringify(body);
+    }
+    catch {
+        fail("E_VALIDATION_FAILED", "transfer body 无法编码");
+    }
+    if (encoded === undefined)
+        fail("E_VALIDATION_FAILED", "transfer body 无法编码");
+    return new TextEncoder().encode(encoded);
+}
+function assertTransferRequest(request, projectId, bytes) {
+    if (request.project_id !== projectId)
+        fail("E_AUTH_REQUIRED", "transfer project identity 不匹配");
+    if (!isLocalGuiTransferRouteAllowed(request.method, request.path))
+        fail("E_AUTH_REQUIRED", "transfer route 未获授权");
+    if ((request.method === "GET" || request.method === "HEAD") && (request.body !== undefined || request.body_digest !== undefined || request.body_size !== undefined)) {
+        fail("E_VALIDATION_FAILED", "GET/HEAD transfer 请求不得携带 body identity");
+    }
+    if (bytes.byteLength > MAX_TRANSFER_REQUEST_BYTES)
+        fail("E_VALIDATION_FAILED", "transfer 请求过大");
+    if (request.body_size !== undefined && request.body_size !== bytes.byteLength)
+        fail("E_VALIDATION_FAILED", "transfer body size 不匹配");
+    if (request.body !== undefined && request.body_digest !== sha256(bytes))
+        fail("E_VALIDATION_FAILED", "transfer body digest 不匹配");
+    if (request.operation_id !== undefined && (request.operation_id.length === 0 || request.operation_id.length > 256))
+        fail("E_VALIDATION_FAILED", "transfer operation_id 无效");
+    const rawCount = Number(request.raw_body_digest !== undefined) + Number(request.raw_body_size !== undefined) + Number(request.body_codec !== undefined);
+    const staging = request.method === "PUT" && (/^\/v1\/creator\/project-transfer\/(?:upload-)?staging\//u.test(request.path));
+    if (rawCount !== 0 && (rawCount !== 3 || !staging || !SHA256_PATTERN.test(request.raw_body_digest ?? "")
+        || request.raw_body_size === undefined || request.raw_body_size <= 0 || request.raw_body_size > 4 * 1024 * 1024
+        || !["identity-v1", "gzip-member-v1"].includes(request.body_codec ?? ""))) {
+        fail("E_VALIDATION_FAILED", "transfer raw body identity 无效");
+    }
+}
+export function createLocalGuiAuth(options) {
+    if (!PROJECT_ID_PATTERN.test(options.projectId))
+        fail("E_SCHEMA_INVALID", "local GUI project_id 无效");
+    const loopback = normalizeLoopbackOrigin(options.loopbackOrigin);
+    const request = options.fetch ?? globalThis.fetch;
+    if (typeof request !== "function")
+        fail("E_SCHEMA_INVALID", "Node fetch 不可用");
+    let pending;
+    let pendingRemoteCancel;
+    let cookie;
+    let sessionEpoch = 0;
+    const authFetch = async (path, body) => {
+        try {
+            return await request(`${API_ORIGIN}${path}`, {
+                method: "POST", redirect: "manual", headers: { "content-type": "application/json" }, body: JSON.stringify(body),
+            });
+        }
+        catch {
+            fail("E_AUTH_REQUIRED", "远端认证服务不可用");
+        }
+    };
+    /**
+     * logout 绝不能因为远端暂时不可达而回滚本地 signed_out。失败只留下不可见的
+     * cancel identity，供本 auth instance 的下一次 logout 原样重试。
+     */
+    const cancelRemoteChallenge = async (challenge) => {
+        let response;
+        try {
+            response = await request(`${API_ORIGIN}/v1/auth/desktop-handoff/cancel`, {
+                method: "POST", redirect: "manual", headers: { "content-type": "application/json" },
+                body: JSON.stringify({ requestId: challenge.requestId, projectId: options.projectId, state: challenge.state }),
+            });
+        }
+        catch {
+            return false;
+        }
+        await response.body?.cancel().catch(() => undefined);
+        return response.ok;
+    };
+    const status = () => {
+        if (pending !== undefined && pending.expiresAtMs <= Date.now())
+            pending = undefined;
+        return Object.freeze({
+            state: cookie !== undefined ? "signed_in" : pending !== undefined ? "challenge_pending" : "signed_out",
+            project_id: options.projectId,
+            ...(pending === undefined ? {} : { expires_at_ms: pending.expiresAtMs }),
+        });
+    };
+    const consumeRemoteResponse = async (response, dispatchedEpoch) => {
+        if (response.status === 401) {
+            await response.body?.cancel().catch(() => undefined);
+            if (sessionEpoch === dispatchedEpoch) {
+                cookie = undefined;
+                sessionEpoch += 1;
+            }
+            fail("E_AUTH_REQUIRED", "远端 session 已失效");
+        }
+        if (response.status < 200 || response.status >= 300)
+            await response.body?.cancel().catch(() => undefined);
+        if (response.status === 403)
+            fail("E_REMOTE_FORBIDDEN", "当前账户无权读取绑定剧本评分");
+        if (response.status === 404)
+            fail("E_REFERENCE_MISSING", "绑定的远端剧本不存在");
+        if (response.status === 409)
+            fail("E_OPERATION_UNCERTAIN", "远端评分基准正在更新");
+        if (response.status < 200 || response.status >= 300)
+            fail("E_OPERATION_UNCERTAIN", "远端评分服务暂时不可用");
+        const responseBytes = await boundedBytes(response, MAX_TRANSFER_RESPONSE_BYTES, "远端响应过大或读取失败");
+        try {
+            return redact(JSON.parse(new TextDecoder().decode(responseBytes)));
+        }
+        catch {
+            fail("E_VALIDATION_FAILED", "远端响应不是有效 JSON");
+        }
+    };
+    const transport = Object.freeze({
+        async request(transferRequest) {
+            if (cookie === undefined)
+                fail("E_AUTH_REQUIRED", "local GUI 尚未建立远端 session");
+            const bytes = requestBytes(transferRequest.body);
+            assertTransferRequest(transferRequest, options.projectId, bytes);
+            const headers = new Headers({
+                cookie: cookie.pair,
+                "x-worldengine-project-id": options.projectId,
+                "x-worldengine-operation-id": transferRequest.operation_id ?? "",
+            });
+            if (transferRequest.content_type !== undefined)
+                headers.set("content-type", transferRequest.content_type);
+            else if (transferRequest.body !== undefined)
+                headers.set("content-type", transferRequest.body instanceof Uint8Array ? "application/octet-stream" : "application/json");
+            if (transferRequest.raw_body_digest !== undefined) {
+                headers.set("x-worldengine-raw-sha256", transferRequest.raw_body_digest);
+                headers.set("x-worldengine-raw-byte-length", String(transferRequest.raw_body_size));
+                headers.set("x-worldengine-chunk-codec", transferRequest.body_codec ?? "");
+            }
+            let response;
+            try {
+                response = await request(`${API_ORIGIN}${transferRequest.path}`, {
+                    method: transferRequest.method, redirect: "manual", headers,
+                    ...(transferRequest.body === undefined ? {} : { body: bytes }),
+                });
+            }
+            catch {
+                fail("E_AUTH_REQUIRED", "远端 transfer 服务不可用");
+            }
+            if (response.status === 401)
+                cookie = undefined;
+            const responseBytes = await boundedBytes(response, MAX_TRANSFER_RESPONSE_BYTES, "transfer 响应过大或读取失败");
+            let body;
+            try {
+                body = redact(JSON.parse(new TextDecoder().decode(responseBytes)));
+            }
+            catch {
+                body = { contentBase64: Buffer.from(responseBytes).toString("base64") };
+            }
+            const headerDigest = response.headers.get("x-worldengine-sha256");
+            const headerSize = Number(response.headers.get("x-worldengine-byte-length") ?? response.headers.get("content-length"));
+            return {
+                status: response.status,
+                body,
+                readback: {
+                    sha256: headerDigest !== null && SHA256_PATTERN.test(headerDigest) ? headerDigest : sha256(responseBytes),
+                    byte_length: Number.isSafeInteger(headerSize) && headerSize >= 0 ? headerSize : responseBytes.byteLength,
+                },
+            };
+        },
+    });
+    return Object.freeze({
+        status,
+        async account() {
+            const dispatchedCookie = cookie;
+            const dispatchedEpoch = sessionEpoch;
+            if (dispatchedCookie === undefined)
+                return status();
+            const read = async (path, decoder) => {
+                const response = await request(`${API_ORIGIN}${path}`, {
+                    method: "GET", redirect: "manual", signal: AbortSignal.timeout(10_000),
+                    headers: { accept: "application/x-protobuf", cookie: dispatchedCookie.pair },
+                });
+                if (response.status === 401 && sessionEpoch === dispatchedEpoch && cookie === dispatchedCookie) {
+                    cookie = undefined;
+                    sessionEpoch += 1;
+                }
+                if (!response.ok || !/^application\/(?:x-)?protobuf(?:;|$)/iu.test(response.headers.get("content-type") ?? "")) {
+                    await response.body?.cancel().catch(() => undefined);
+                    fail("E_OPERATION_UNCERTAIN", "账户资料暂时不可用");
+                }
+                return decoder.decode(await boundedBytes(response, MAX_AUTH_RESPONSE_BYTES, "账户资料响应无效"));
+            };
+            const [profile, wallet] = await Promise.allSettled([
+                read("/v1/auth/me", MeResponse), read("/v1/wallet", WalletResponse),
+            ]);
+            // 注销或切换后，旧请求既不能显示旧身份，也不能使新账户退出。
+            if (sessionEpoch !== dispatchedEpoch || cookie !== dispatchedCookie)
+                return status();
+            const identity = profile.status === "fulfilled" && profile.value.error === undefined ? profile.value.current_identity : undefined;
+            const displayName = typeof identity?.user_id === "string" && identity.user_id.length > 0
+                && typeof identity.display_name === "string" && identity.display_name.trim().length > 0 ? identity.display_name : undefined;
+            const balance = wallet.status === "fulfilled" && wallet.value.error === undefined && wallet.value.currency === "CNY"
+                && /^(?:0|[1-9]\d*)$/u.test(wallet.value.top_up_balance_units)
+                && /^(?:0|[1-9]\d*)$/u.test(wallet.value.credit_balance_units)
+                ? (BigInt(wallet.value.top_up_balance_units) + BigInt(wallet.value.credit_balance_units)).toString() : undefined;
+            return Object.freeze({ ...status(), account: Object.freeze({
+                    profile_state: displayName === undefined ? "unavailable" : "ready",
+                    wallet_state: balance === undefined ? "unavailable" : "ready",
+                    ...(displayName === undefined ? {} : { display_name: displayName }),
+                    ...(balance === undefined ? {} : { balance_units: balance }),
+                }) });
+        },
+        async start() {
+            if (cookie !== undefined)
+                fail("E_AUTH_REQUIRED", "local GUI 已登录");
+            if (pendingRemoteCancel !== undefined)
+                fail("E_AUTH_REQUIRED", "local GUI 注销正在等待远端确认");
+            if (pending !== undefined && pending.expiresAtMs > Date.now())
+                fail("E_AUTH_REQUIRED", "local GUI 已有待完成的认证 challenge");
+            const state = randomPkce();
+            const verifier = randomPkce();
+            const draft = { requestId: "", state, verifier, expiresAtMs: 0 };
+            const response = await authFetch("/v1/auth/desktop-handoff/start", {
+                state,
+                pkceChallenge: createHash("sha256").update(verifier).digest("base64url"),
+                loopbackPort: Number(loopback.port),
+                deviceName: "WorldEngine Project",
+                projectId: options.projectId,
+            });
+            if (response.status !== 200 && response.status !== 201)
+                fail("E_AUTH_REQUIRED", "远端认证服务拒绝 handoff start");
+            const value = await boundedJson(response, MAX_AUTH_RESPONSE_BYTES, "远端认证服务 start 响应无效");
+            if (typeof value.requestId !== "string" || !UUID_PATTERN.test(value.requestId)
+                || value.projectId !== options.projectId || !Number.isSafeInteger(value.expiresAt)
+                || value.expiresAt <= Date.now() || value.expiresAt > Date.now() + 10 * 60_000) {
+                fail("E_VALIDATION_FAILED", "远端认证服务 start 响应未绑定当前项目");
+            }
+            draft.requestId = value.requestId;
+            draft.expiresAtMs = value.expiresAt;
+            if (!PKCE_PATTERN.test(state) || !PKCE_PATTERN.test(verifier))
+                fail("E_VALIDATION_FAILED", "本地 PKCE 生成失败");
+            const authorizationUrl = assertAuthorizationUrl(value.authorizationUrl, draft);
+            pending = Object.freeze(draft);
+            if (options.openBrowser !== undefined) {
+                try {
+                    await options.openBrowser(authorizationUrl);
+                }
+                catch {
+                    fail("E_AUTH_REQUIRED", "系统浏览器无法打开认证页面");
+                }
+            }
+            return Object.freeze({ state: "challenge_pending", project_id: options.projectId, expires_at_ms: draft.expiresAtMs, authorization_url: authorizationUrl });
+        },
+        async handleCallback(callbackUrl) {
+            const challenge = pending;
+            if (challenge === undefined || challenge.expiresAtMs <= Date.now()) {
+                pending = undefined;
+                fail("E_AUTH_REQUIRED", "local GUI 没有有效的认证 challenge");
+            }
+            let callback;
+            try {
+                callback = callbackUrl instanceof URL ? new URL(callbackUrl.toString()) : new URL(callbackUrl);
+            }
+            catch {
+                fail("E_AUTH_REQUIRED", "认证 callback 无效");
+            }
+            const keys = [...callback.searchParams.keys()];
+            if (callback.origin !== loopback.origin || callback.pathname !== CALLBACK_PATH || callback.hash !== ""
+                || keys.length !== 3 || new Set(keys).size !== 3
+                || callback.searchParams.get("request_id") !== challenge.requestId
+                || callback.searchParams.get("state") !== challenge.state
+                || !/^\d{6}$/u.test(callback.searchParams.get("otp") ?? "")) {
+                fail("E_AUTH_REQUIRED", "认证 callback 未通过 state/loopback 校验");
+            }
+            const exchangeEpoch = sessionEpoch;
+            pending = undefined;
+            const response = await authFetch("/v1/auth/desktop-handoff/exchange", {
+                requestId: challenge.requestId,
+                projectId: options.projectId,
+                state: challenge.state,
+                codeVerifier: challenge.verifier,
+                otp: callback.searchParams.get("otp"),
+            });
+            if (!response.ok)
+                fail("E_AUTH_REQUIRED", "远端认证服务拒绝 handoff exchange");
+            const nextCookie = parseHttpOnlyCookie(response.headers.get("set-cookie"));
+            const value = await boundedJson(response, MAX_AUTH_RESPONSE_BYTES, "远端认证服务 exchange 响应无效");
+            const device = object(value.device);
+            if (value.requestId !== challenge.requestId || value.projectId !== options.projectId || value.status !== "authenticated"
+                || typeof device?.id !== "string" || !UUID_PATTERN.test(device.id)) {
+                fail("E_VALIDATION_FAILED", "远端认证服务 exchange 响应未绑定当前项目");
+            }
+            if (sessionEpoch !== exchangeEpoch || pending !== undefined || cookie !== undefined) {
+                fail("E_AUTH_REQUIRED", "认证 exchange 返回时本地 session authority 已变化");
+            }
+            cookie = nextCookie;
+            sessionEpoch += 1;
+            return status();
+        },
+        async logout() {
+            const challenge = pendingRemoteCancel ?? pending;
+            pending = undefined;
+            cookie = undefined;
+            sessionEpoch += 1;
+            if (challenge === undefined || challenge.expiresAtMs <= Date.now()) {
+                pendingRemoteCancel = undefined;
+                return Object.freeze({ ...status(), remote_cancel: "not_required" });
+            }
+            if (await cancelRemoteChallenge(challenge)) {
+                pendingRemoteCancel = undefined;
+                return Object.freeze({ ...status(), remote_cancel: "confirmed" });
+            }
+            pendingRemoteCancel = challenge;
+            return Object.freeze({ ...status(), remote_cancel: "pending_retry" });
+        },
+        async requestModel(modelRequest) {
+            if (cookie === undefined)
+                fail("E_AUTH_REQUIRED", "local GUI 尚未建立远端 session");
+            if (typeof modelRequest !== "object" || modelRequest === null || Array.isArray(modelRequest)) {
+                fail("E_SCHEMA_INVALID", "账户模型请求无效");
+            }
+            const keys = Object.keys(modelRequest).sort().join("\0");
+            const sessionRequest = modelRequest.kind === "session" && keys === "kind";
+            const leaseReadRequest = (modelRequest.kind === "chat_catalog" || modelRequest.kind === "embedding_descriptor")
+                && keys === "kind\0session";
+            const executionRequest = (modelRequest.kind === "embedding" || modelRequest.kind === "chat_completions")
+                && keys === "body\0idempotency_key\0kind\0session"
+                && IDEMPOTENCY_KEY_PATTERN.test(modelRequest.idempotency_key)
+                && object(modelRequest.body) !== undefined;
+            if (!sessionRequest && !leaseReadRequest && !executionRequest)
+                fail("E_SCHEMA_INVALID", "账户模型请求字段无效");
+            let dispatchedCookie;
+            let dispatchedEpoch;
+            let issuedLease;
+            if (modelRequest.kind === "session") {
+                dispatchedCookie = cookie;
+                dispatchedEpoch = sessionEpoch;
+            }
+            else {
+                const binding = MODEL_SESSION_LEASES.get(modelRequest.session);
+                if (binding === undefined || binding.projectId !== options.projectId || binding.epoch !== sessionEpoch || binding.cookie !== cookie) {
+                    fail("E_AUTH_REQUIRED", "账户模型 session lease 已失效");
+                }
+                dispatchedCookie = binding.cookie;
+                dispatchedEpoch = binding.epoch;
+            }
+            const headers = new Headers({
+                accept: "application/json",
+                cookie: dispatchedCookie.pair,
+                "x-worldengine-project-id": options.projectId,
+            });
+            let path;
+            let init;
+            if (modelRequest.kind === "session" || modelRequest.kind === "chat_catalog" || modelRequest.kind === "embedding_descriptor") {
+                path = modelRequest.kind === "session"
+                    ? ACCOUNT_MODEL_SESSION_PATH
+                    : modelRequest.kind === "chat_catalog"
+                        ? ACCOUNT_MODEL_CHAT_CATALOG_PATH
+                        : ACCOUNT_MODEL_EMBEDDING_DESCRIPTOR_PATH;
+                init = { method: "GET", redirect: "manual", headers };
+            }
+            else {
+                headers.set("content-type", "application/json");
+                headers.set("idempotency-key", modelRequest.idempotency_key);
+                path = modelRequest.kind === "embedding" ? ACCOUNT_MODEL_EMBEDDING_PATH : ACCOUNT_MODEL_CHAT_COMPLETIONS_PATH;
+                init = { method: "POST", redirect: "manual", headers, body: JSON.stringify(modelRequest.body) };
+            }
+            let response;
+            try {
+                response = await request(`${API_ORIGIN}${path}`, init);
+            }
+            catch {
+                fail("E_OPERATION_UNCERTAIN", "远端账户模型服务暂时不可用");
+            }
+            if (response.status === 401 && sessionEpoch === dispatchedEpoch) {
+                cookie = undefined;
+                sessionEpoch += 1;
+            }
+            let body = await boundedJson(response, MAX_MODEL_RESPONSE_BYTES, "远端账户模型响应无效");
+            const operationId = response.headers.get("x-world-engines-operation-id");
+            if (operationId !== null) {
+                if (!/^[A-Za-z0-9._:-]{1,256}$/u.test(operationId)
+                    || (body.operation_id !== undefined && body.operation_id !== operationId)) {
+                    fail("E_VALIDATION_FAILED", "远端账户模型 operation identity 无效");
+                }
+                body = { ...body, operation_id: operationId };
+            }
+            if (sessionEpoch !== dispatchedEpoch || cookie !== dispatchedCookie)
+                fail("E_AUTH_REQUIRED", "账户模型 session 在请求期间已变化");
+            const projected = projectModelResponse(modelRequest.kind, response.status, body);
+            if (modelRequest.kind === "session" && response.status === 200) {
+                const principalId = projected.principal_id;
+                const projectId = projected.project_id;
+                if (typeof principalId !== "string" || typeof projectId !== "string" || projectId !== options.projectId)
+                    fail("E_VALIDATION_FAILED", "账户模型 session 响应无效");
+                issuedLease = Object.freeze({});
+                MODEL_SESSION_LEASES.set(issuedLease, Object.freeze({ epoch: dispatchedEpoch, cookie: dispatchedCookie, principalId, projectId }));
+            }
+            return Object.freeze({ kind: modelRequest.kind, status: response.status, body: projected, ...(issuedLease === undefined ? {} : { session: issuedLease }) });
+        },
+        async requestScore(scoreRequest) {
+            if (cookie === undefined)
+                fail("E_AUTH_REQUIRED", "local GUI 尚未建立远端 session");
+            if (options.projectRoot === undefined)
+                fail("E_REFERENCE_MISSING", "local GUI 未配置项目根，无法读取远端评分绑定");
+            if (typeof scoreRequest !== "object" || scoreRequest === null || Array.isArray(scoreRequest))
+                fail("E_SCHEMA_INVALID", "评分请求无效");
+            const keys = Object.keys(scoreRequest).sort().join("\0");
+            if ((scoreRequest.kind === "score" && keys !== "kind")
+                || (scoreRequest.kind === "tag-benchmark" && keys !== "kind\0tag")
+                || (scoreRequest.kind !== "score" && scoreRequest.kind !== "tag-benchmark"))
+                fail("E_SCHEMA_INVALID", "评分请求字段无效");
+            if (scoreRequest.kind === "tag-benchmark" && !isKnownScenarioTag(scoreRequest.tag))
+                fail("E_SCHEMA_INVALID", "评分 tag 不在 canonical 字典");
+            let binding;
+            try {
+                binding = await readFrozenReviewTargetBinding(options.projectRoot, options.projectId);
+            }
+            catch (error) {
+                if (error instanceof AuthoringBridgeError && (error.code === "E_OPERATION_ID_CONFLICT" || error.code === "E_PATH_OUTSIDE_PROJECT"))
+                    throw error;
+                fail("E_REFERENCE_MISSING", "当前项目尚未绑定远端评分剧本");
+            }
+            if (!/^[A-Za-z0-9_-]{1,256}$/u.test(binding.scenario_id))
+                fail("E_REFERENCE_MISSING", "远端评分剧本绑定无效");
+            const scenario = encodeURIComponent(binding.scenario_id);
+            const path = scoreRequest.kind === "score"
+                ? `/v1/scenarios/${scenario}/score`
+                : `/v1/scenarios/${scenario}/score/tag-benchmark?${new URLSearchParams({ tag: scoreRequest.tag }).toString()}`;
+            let response;
+            const dispatchedEpoch = sessionEpoch;
+            try {
+                response = await request(`${API_ORIGIN}${path}`, {
+                    method: "GET",
+                    redirect: "manual",
+                    headers: {
+                        cookie: cookie.pair,
+                        "x-worldengine-project-id": options.projectId,
+                    },
+                });
+            }
+            catch {
+                fail("E_OPERATION_UNCERTAIN", "远端评分服务暂时不可用");
+            }
+            return Object.freeze({ kind: scoreRequest.kind, body: await consumeRemoteResponse(response, dispatchedEpoch) });
+        },
+        transport,
+    });
+}