@harrylabsj/kiwi-merchant-cloud 0.12.0

package/app/mcp/merchant-server.js

@@ -0,0 +1,852 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Merchant Workbench 标准远程 MCP Server（WorkBuddy Buddy 应用开发计划 阶段二）。
+ *
+ * 官方 @modelcontextprotocol/sdk 的 StreamableHTTPServerTransport（无状态模式，
+ * sessionIdGenerator: undefined——每个请求独立的 Server+Transport，天然适配
+ * 远程连接器，不维护进程内会话状态），承载在 Node http 上。
+ *
+ * 边界：
+ *   - 独立端口/路径（缺省 9100 / /mcp），不复用 A2A `/` 端点；
+ *   - 单商家一服务（MVP）：一个实例绑定一个 MerchantWorkbenchService（其
+ *     expectedMerchantId = profile.owner_id），租户校验在 Facade 内；
+ *   - Bearer 认证由调用方注入校验器（merchant-auth.ts）；本层只负责在配置
+ *     了校验器时强制执行（401，不回显原因细节之外的信息）；
+ *   - 不持有任何商业状态——状态唯一权威在 MerchantWorkbenchService 背后的
+ *     Ledger/Store。
+ */
+import { createServer, } from "node:http";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { formatAppOAuthCallbackLog, handleAppOAuthCallback, } from "../auth/app-oauth-callback.js";
+import { buildMerchantMcpTools, } from "./merchant-tools.js";
+import { OnboardingStore } from "../cloud/onboarding/store.js";
+import { readEnrollmentStore } from "../cloud/binding/enrollment-challenge.js";
+import { deriveLocalFallback, degradedRecoveryAsk } from "../cloud/onboarding/local-fallback.js";
+import { planWizard } from "../cloud/onboarding/steps.js";
+import { renderPendingPage } from "../merchant-admin/pending-page.js";
+import { renderRfqCasePage, renderRfqDashboard, renderRfqReleasePage, } from "../merchant-admin/rfq-page.js";
+import { ADMIN_SESSION_COOKIE, readAdminCredentials, renderAdminLoginPage, verifyAdminPassword, } from "../auth/merchant-sessions.js";
+import { contentHash } from "../agent/merchant/action-candidate.js";
+import { issuePairedCredential, redeemPairingCode } from "../auth/merchant-pairing.js";
+/** 从 Cookie 头取值（管理会话）。 */
+function cookieValue(req, name) {
+    const header = req.headers.cookie;
+    if (header === undefined)
+        return undefined;
+    for (const part of header.split(";")) {
+        const eq = part.indexOf("=");
+        if (eq === -1)
+            continue;
+        if (part.slice(0, eq).trim() === name)
+            return part.slice(eq + 1).trim();
+    }
+    return undefined;
+}
+/** 只允许管理面内部相对路径，避免 XSS 和开放重定向。 */
+function safeAdminNext(value) {
+    if (value === undefined ||
+        value === "" ||
+        !value.startsWith("/") ||
+        value.startsWith("//") ||
+        value.includes("\\")) {
+        return "/admin/pending";
+    }
+    return value;
+}
+/** 缺省监听地址（远程连接器形态；fail-closed 由 merchant-auth 守卫）。 */
+export const DEFAULT_MERCHANT_MCP_HOST = "0.0.0.0";
+/** 缺省端口（与 A2A 9000 分离）。 */
+export const DEFAULT_MERCHANT_MCP_PORT = 9100;
+/** 缺省 MCP endpoint 路径。 */
+export const DEFAULT_MERCHANT_MCP_PATH = "/mcp";
+/** POST body 上限（防御性；MCP 工具入参都很小）。 */
+const MAX_BODY_BYTES = 1_048_576;
+function writeJson(res, status, body, headers = {}) {
+    const text = JSON.stringify(body);
+    res.writeHead(status, { "content-type": "application/json", ...headers });
+    res.end(text);
+}
+/** RFC 6749 §5.1：token/授权/管理面响应必须 no-store（审查 P2：token 与
+ *  一次性确认凭证不得落入共享缓存）。 */
+const NO_STORE_HEADERS = {
+    "cache-control": "no-store",
+    pragma: "no-cache",
+};
+/** 读 POST body（超上限直接拒绝，绝不流入解析）。 */
+async function readBody(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_BODY_BYTES) {
+            throw new Error(`request body exceeds ${MAX_BODY_BYTES} bytes`);
+        }
+        chunks.push(chunk);
+    }
+    if (chunks.length === 0)
+        return undefined;
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+/** 每个请求独立的协议 Server（无状态模式），handlers 引用共享的工具分发器。
+ *  scopes 来自本次请求的授权上下文（OAuth access_token）；undefined = 静态
+ *  token 过渡模式（全量 scope）。tools/list 按 scope 过滤，tools/call 逐次强制。 */
+export function createProtocolServer(serverInfo, toolsBundle, scopes, presentations, rfqResources) {
+    const hasResources = presentations !== undefined || rfqResources !== undefined;
+    const server = new Server({ name: serverInfo.name, version: serverInfo.version }, { capabilities: { tools: {}, ...(hasResources ? { resources: {} } : {}) } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: await toolsBundle.listTools(scopes),
+    }));
+    if (hasResources) {
+        server.setRequestHandler(ListResourcesRequestSchema, () => {
+            if (scopes !== undefined && !scopes.includes("merchant:read"))
+                return { resources: [] };
+            return {
+                resources: [
+                    ...(presentations?.list() ?? []),
+                    ...(rfqResources?.list() ?? []),
+                ],
+            };
+        });
+        server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+            if (scopes !== undefined && !scopes.includes("merchant:read")) {
+                throw new Error("scope 不足：resources/read 需要 merchant:read");
+            }
+            // 按前缀路由：ui://kiwi-rfq/* 走 RFQ 展示资源，其余走 merchant presentations。
+            if (rfqResources !== undefined && request.params.uri.startsWith("ui://kiwi-rfq/")) {
+                return await rfqResources.read(request.params.uri);
+            }
+            if (presentations !== undefined) {
+                return await presentations.read(request.params.uri);
+            }
+            throw new Error(`未知资源 ${request.params.uri}`);
+        });
+    }
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const result = await toolsBundle.call(request.params.name, (request.params.arguments ?? {}), scopes);
+        // SDK 1.30 的 CallToolResult 含 task 增强变体；本 server 只用经典
+        // content/structuredContent/isError 形状。
+        return result;
+    });
+    return server;
+}
+/**
+ * 组装商家 HTTP 处理器（/mcp + /oauth/* + /pairing/* + /admin/*），**不绑定端口**。
+ *
+ * 云端单端口部署需要把这些路由与 A2A 路由挂到同一监听上（设计 §8.2），因此把
+ * 路由闭包从 `startMerchantMcpServer` 抽出共享；CLI 路径行为不变。
+ */
+export function createMerchantHttpHandler(options) {
+    const mcpPath = options.path ?? DEFAULT_MERCHANT_MCP_PATH;
+    const serverInfo = options.serverInfo ?? { name: "kiwi-merchant-workbench", version: "0.0.0" };
+    const merchantTools = buildMerchantMcpTools(options.service, {
+        ...(options.maxChars !== undefined ? { maxChars: options.maxChars } : {}),
+        ...(options.requestTimeoutMs !== undefined
+            ? { requestTimeoutMs: options.requestTimeoutMs }
+            : {}),
+    });
+    // RFQ 工具束合并（v0.1.1 §11.2）：同一 scope 体系逐次强制；名字分发按
+    // 前缀路由——rfq_* 走 RFQ 束，其余走 merchant 束。
+    const rfqOptions = options.rfq;
+    const toolsBundle = rfqOptions === undefined
+        ? merchantTools
+        : {
+            listTools: (scopes) => [...merchantTools.listTools(scopes), ...rfqOptions.tools.listTools(scopes)],
+            call: async (name, args, scopes) => name.startsWith("kiwi_merchant_rfq_")
+                ? rfqOptions.tools.call(name, args, scopes)
+                : merchantTools.call(name, args, scopes),
+        };
+    // 活跃连接跟踪：close() 时连同 transport 一起关闭，优雅退出。
+    const transports = new Set();
+    let closing = false;
+    // 审查 P2：无认证端点限速（进程内计数，重启归零可接受——目标是抬高脚本
+    // 刷注册/在线爆破口令的成本，不做分布式级配额）。
+    const registerHits = new Map();
+    const loginFailures = new Map();
+    const REGISTER_LIMIT_PER_HOUR = 20;
+    const LOGIN_MAX_FAILURES = 10;
+    const LOGIN_BLOCK_MS = 5 * 60 * 1000;
+    const clientKey = (req) => req.socket.remoteAddress ?? "unknown";
+    const pruneRateLimits = (nowMs) => {
+        if (registerHits.size > 4096) {
+            for (const [k, v] of registerHits) {
+                if (nowMs - v.windowStart > 60 * 60 * 1000)
+                    registerHits.delete(k);
+            }
+        }
+        if (loginFailures.size > 4096) {
+            for (const [k, v] of loginFailures) {
+                if (nowMs >= v.blockedUntil && v.count === 0)
+                    loginFailures.delete(k);
+            }
+        }
+    };
+    /** OAuth 端点结果写出（JSON / HTML 授权页 / 302 回跳）。统一附加 no-store。 */
+    const writeOAuthResult = (res, result) => {
+        const headers = { ...NO_STORE_HEADERS, ...(result.headers ?? {}) };
+        if (result.html !== undefined) {
+            res.writeHead(result.status, {
+                "content-type": "text/html; charset=utf-8",
+                ...headers,
+            });
+            res.end(result.html);
+            return;
+        }
+        if (headers.location !== undefined) {
+            res.writeHead(result.status, headers);
+            res.end();
+            return;
+        }
+        writeJson(res, result.status, result.body ?? {}, headers);
+    };
+    /** 读表单/JSON body（/oauth/token 等用 application/x-www-form-urlencoded）。 */
+    const readForm = async (req) => {
+        const chunks = [];
+        let size = 0;
+        for await (const chunk of req) {
+            size += chunk.length;
+            if (size > MAX_BODY_BYTES)
+                throw new Error(`request body exceeds ${MAX_BODY_BYTES} bytes`);
+            chunks.push(chunk);
+        }
+        const text = Buffer.concat(chunks).toString("utf8");
+        if (text.trim() === "")
+            return {};
+        if ((req.headers["content-type"] ?? "").includes("application/json")) {
+            return JSON.parse(text);
+        }
+        return Object.fromEntries(new URLSearchParams(text).entries());
+    };
+    /** OAuth 端点路由（授权流程本身不需要 Bearer；/mcp 才校验）。 */
+    const routeOAuth = async (req, res, url) => {
+        // 应用级 OAuth 回调（开放平台 → Buddy 应用的 Open API 授权链）：与连接器级
+        // OAuth（下方各端点，需 options.oauth）是两条互不相通的链路，不依赖连接器
+        // 授权服务器配置。只接收与留痕，code 永不兑换（模块注释详见 app-oauth-callback）。
+        if (req.method === "GET" && url.pathname === "/oauth/callback") {
+            const callback = handleAppOAuthCallback(url.searchParams);
+            process.stderr.write(`${formatAppOAuthCallbackLog(callback.log)}\n`);
+            res.writeHead(callback.status, {
+                "content-type": "text/html; charset=utf-8",
+                ...NO_STORE_HEADERS,
+                "x-content-type-options": "nosniff",
+            });
+            res.end(callback.html);
+            return true;
+        }
+        const oauth = options.oauth;
+        if (oauth === undefined)
+            return false;
+        const p = url.pathname;
+        if (req.method === "GET" && p === "/.well-known/oauth-protected-resource") {
+            writeOAuthResult(res, oauth.protectedResourceMetadata());
+            return true;
+        }
+        if (req.method === "GET" && p === "/.well-known/oauth-authorization-server") {
+            writeOAuthResult(res, oauth.authorizationServerMetadata());
+            return true;
+        }
+        if (req.method === "POST" && p === "/oauth/register") {
+            // 限速（审查 P2）：注册无认证，按来源 IP 限每小时次数。
+            const nowMs = Date.now();
+            pruneRateLimits(nowMs);
+            const ip = clientKey(req);
+            const reg = registerHits.get(ip);
+            if (reg === undefined || nowMs - reg.windowStart > 60 * 60 * 1000) {
+                registerHits.set(ip, { count: 1, windowStart: nowMs });
+            }
+            else {
+                reg.count += 1;
+                if (reg.count > REGISTER_LIMIT_PER_HOUR) {
+                    writeJson(res, 429, {
+                        error: "slow_down",
+                        error_description: "too many client registrations from this source",
+                    });
+                    return true;
+                }
+            }
+            // RFC 7591：畸形 body 属客户端错误 → 400 invalid_client_metadata，
+            // 不冒泡成 500（审查 P2：此前 500 且顶层 catch 静默无日志）。
+            let body;
+            try {
+                body = await readBody(req);
+            }
+            catch (err) {
+                process.stderr.write(`[merchant oauth] /oauth/register body 解析失败：${err instanceof Error ? err.message : String(err)}\n`);
+                writeJson(res, 400, {
+                    error: "invalid_client_metadata",
+                    error_description: "request body must be valid JSON",
+                });
+                return true;
+            }
+            writeOAuthResult(res, oauth.register(body));
+            return true;
+        }
+        if (req.method === "GET" && p === "/oauth/authorize") {
+            // BUG-01：授权页需要管理登录会话（cookie）；无会话 → 303 登录页。
+            const sessionId = cookieValue(req, ADMIN_SESSION_COOKIE);
+            const session = sessionId !== undefined && options.admin !== undefined
+                ? options.admin.sessions.getSession(sessionId)
+                : undefined;
+            writeOAuthResult(res, oauth.authorize(Object.fromEntries(url.searchParams.entries()), session));
+            return true;
+        }
+        if (req.method === "POST" &&
+            (p === "/oauth/authorize" || p === "/oauth/token" || p === "/oauth/revoke")) {
+            let form;
+            try {
+                form = await readForm(req);
+            }
+            catch (err) {
+                process.stderr.write(`[merchant oauth] ${p} body 解析失败：${err instanceof Error ? err.message : String(err)}\n`);
+                writeJson(res, 400, {
+                    error: "invalid_request",
+                    error_description: "malformed request body",
+                });
+                return true;
+            }
+            let result;
+            if (p === "/oauth/authorize") {
+                const sessionId = cookieValue(req, ADMIN_SESSION_COOKIE);
+                const session = sessionId !== undefined && options.admin !== undefined
+                    ? options.admin.sessions.getSession(sessionId)
+                    : undefined;
+                if (session === undefined) {
+                    writeOAuthResult(res, {
+                        status: 401,
+                        body: {
+                            error: "login_required",
+                            error_description: "授权提交需要有效的商家管理会话",
+                        },
+                    });
+                    return true;
+                }
+                result = oauth.authorizeSubmit(form, session);
+            }
+            else if (p === "/oauth/token") {
+                result = oauth.token(form);
+            }
+            else {
+                result = oauth.revoke(form);
+            }
+            writeOAuthResult(res, result);
+            return true;
+        }
+        if (p.startsWith("/oauth/") || p.startsWith("/.well-known/oauth-")) {
+            writeJson(res, 404, { error: "not_found", message: `unknown OAuth endpoint ${p}` });
+            return true;
+        }
+        return false;
+    };
+    const handler = (req, res) => {
+        void (async () => {
+            const url = new URL(req.url ?? "/", "http://localhost");
+            if (await routeOAuth(req, res, url))
+                return;
+            // 一次性配对码兑换（设计 §8.4 第二期）：只能兑换一次，过期即失效；
+            // 成功才返回内部凭据（供商家连接器网关按 merchant_id 路由使用）。
+            if (options.pairing !== undefined &&
+                req.method === "POST" &&
+                url.pathname === "/pairing/redeem") {
+                const nowMs = Date.now();
+                pruneRateLimits(nowMs);
+                const ip = clientKey(req);
+                const hits = registerHits.get(`pair:${ip}`);
+                if (hits === undefined || nowMs - hits.windowStart > 60 * 60 * 1000) {
+                    registerHits.set(`pair:${ip}`, { count: 1, windowStart: nowMs });
+                }
+                else {
+                    hits.count += 1;
+                    if (hits.count > 30) {
+                        writeJson(res, 429, { error: "slow_down", message: "配对码尝试过于频繁" });
+                        return;
+                    }
+                }
+                let form;
+                try {
+                    form = await readForm(req);
+                }
+                catch {
+                    writeJson(res, 400, { error: "invalid_request", message: "请求体解析失败" });
+                    return;
+                }
+                const code = String(form.code ?? "");
+                if (!redeemPairingCode(options.pairing.dir, code)) {
+                    writeJson(res, 403, {
+                        error: "invalid_pairing_code",
+                        message: "配对码无效或已过期（请在实例上重新生成）",
+                    });
+                    return;
+                }
+                const identity = options.pairing.instance();
+                // 兑换即签发：新凭据覆盖旧的（单槽轮换），明文只在此响应里出现一次。
+                const issued = issuePairedCredential(options.pairing.dir);
+                process.stderr.write(`[merchant pairing] issued paired credential for owner=${identity.ownerId}` +
+                    `（旧配对凭据已失效）\n`);
+                writeJson(res, 200, {
+                    ok: true,
+                    instance: { owner_id: identity.ownerId, principal_id: identity.principalId },
+                    // 能力探测：实例自报名称/版本，供网关在绑定页展示与兼容性判断。
+                    server_info: { name: serverInfo.name, version: serverInfo.version },
+                    credential: issued.credential,
+                });
+                return;
+            }
+            // 配套商家管理面（BUG-01/03 修复后）：登录用 cookie 会话（HttpOnly/
+            // SameSite=Lax/生产 Secure）；/admin/pending 需会话；/admin/decision
+            // 需会话 + 一次性确认凭证（绑定候选摘要/主体/商家/动作，单次用途）。
+            if (options.admin !== undefined && url.pathname.startsWith("/admin/")) {
+                const admin = options.admin;
+                // 登录端点（公开；口令校验后签发会话）。失败退避（审查 P2：scrypt
+                // 单次成本不足以挡在线爆破，按来源连续失败 10 次锁 5 分钟）。
+                if (url.pathname === "/admin/login") {
+                    if (req.method === "GET") {
+                        res.writeHead(200, {
+                            "content-type": "text/html; charset=utf-8",
+                            ...NO_STORE_HEADERS,
+                        });
+                        res.end(renderAdminLoginPage({
+                            next: safeAdminNext(url.searchParams.get("next") ?? undefined),
+                        }));
+                        return;
+                    }
+                    if (req.method === "POST") {
+                        const nowMs = Date.now();
+                        pruneRateLimits(nowMs);
+                        const ip = clientKey(req);
+                        const failure = loginFailures.get(ip);
+                        if (failure !== undefined && nowMs < failure.blockedUntil) {
+                            res.writeHead(429, {
+                                "content-type": "text/html; charset=utf-8",
+                                ...NO_STORE_HEADERS,
+                            });
+                            res.end(renderAdminLoginPage({ error: "失败次数过多，请 5 分钟后再试" }));
+                            return;
+                        }
+                        const form = await readForm(req);
+                        const creds = readAdminCredentials(admin.adminDir);
+                        const password = form.password ?? "";
+                        if (creds === undefined || !verifyAdminPassword(password, creds.password_hash)) {
+                            const count = (failure?.count ?? 0) + 1;
+                            loginFailures.set(ip, {
+                                count,
+                                blockedUntil: count >= LOGIN_MAX_FAILURES ? nowMs + LOGIN_BLOCK_MS : failure?.blockedUntil ?? 0,
+                            });
+                            res.writeHead(200, {
+                                "content-type": "text/html; charset=utf-8",
+                                ...NO_STORE_HEADERS,
+                            });
+                            res.end(renderAdminLoginPage({ error: "口令错误或管理员未初始化" }));
+                            return;
+                        }
+                        loginFailures.delete(ip);
+                        const session = admin.sessions.createSession({
+                            principalId: creds.principal_id,
+                            merchantId: creds.merchant_id,
+                        });
+                        const secure = admin.secureCookies === true ? "; Secure" : "";
+                        res.writeHead(303, {
+                            location: safeAdminNext(form.next),
+                            "set-cookie": `${ADMIN_SESSION_COOKIE}=${session.sessionId}; HttpOnly; SameSite=Lax; Path=/${secure}`,
+                        });
+                        res.end();
+                        return;
+                    }
+                }
+                // 其余 /admin/* 需要有效会话
+                const sessionId = cookieValue(req, ADMIN_SESSION_COOKIE);
+                const session = sessionId !== undefined ? admin.sessions.getSession(sessionId) : undefined;
+                if (session === undefined) {
+                    res.writeHead(303, { location: "/admin/login" });
+                    res.end();
+                    return;
+                }
+                if (req.method === "GET" && url.pathname === "/admin/pending") {
+                    const commands = admin.surface.listPending();
+                    // 按候选签发一次性确认凭证（表单 CSRF + 确认绑定，单次用途）
+                    const tokenFor = (candidateId, action) => {
+                        const candidate = commands.find((c) => c.candidate_id === candidateId);
+                        if (candidate === undefined)
+                            return "";
+                        return admin.store.createConfirmation({
+                            candidateId,
+                            candidateDigest: contentHash({
+                                arguments: candidate.arguments,
+                                preconditions: candidate.preconditions,
+                            }),
+                            principalId: session.principal_id,
+                            merchantId: session.merchant_id,
+                            action,
+                        });
+                    };
+                    res.writeHead(200, {
+                        "content-type": "text/html; charset=utf-8",
+                        // 页面内嵌一次性确认凭证（审查 P2）：绝不进缓存。
+                        ...NO_STORE_HEADERS,
+                    });
+                    res.end(renderPendingPage(admin.merchantName, commands, tokenFor));
+                    return;
+                }
+                if (req.method === "GET" && url.pathname === "/admin/onboarding") {
+                    const onboarding = options.admin?.onboarding;
+                    if (onboarding === undefined) {
+                        res.writeHead(404, { "content-type": "application/json" });
+                        res.end(JSON.stringify({ ok: false, error: "onboarding is not configured" }));
+                        return;
+                    }
+                    const record = onboarding.store.activeRecord(onboarding.merchantId) ?? null;
+                    const plan = record === null ? null : planWizard(record);
+                    const enrollment = record === null || onboarding.enrollmentStateDir === undefined
+                        ? undefined
+                        : readEnrollmentStore(onboarding.enrollmentStateDir).sessions
+                            .map((session) => session)
+                            .find((session) => session.owner_ref === record.recordId);
+                    const readiness = await onboarding.readiness();
+                    const fallback = deriveLocalFallback({
+                        publicationState: record === null
+                            ? "NONE"
+                            : record.status === "PUBLISHED"
+                                ? "ACTIVE"
+                                : "NONE",
+                        readiness,
+                        controlPlaneReachable: onboarding.controlPlaneReachable,
+                    });
+                    res.writeHead(200, { "content-type": "application/json", ...NO_STORE_HEADERS });
+                    res.end(JSON.stringify({
+                        ok: true,
+                        record,
+                        plan,
+                        ...(enrollment !== undefined ? {
+                            connect: {
+                                enrollment_id: enrollment.enrollment_id,
+                                status: enrollment.status,
+                                user_code: enrollment.user_code,
+                                verification_uri: enrollment.verification_uri,
+                                expires_at: enrollment.expires_at,
+                            },
+                        } : {}),
+                        fallback,
+                        recovery_ask: degradedRecoveryAsk({
+                            publicationState: record?.status === "PUBLISHED" ? "ACTIVE" : "NONE",
+                            readiness,
+                            controlPlaneReachable: onboarding.controlPlaneReachable,
+                        }),
+                    }));
+                    return;
+                }
+                if (req.method === "POST" && url.pathname === "/admin/decision") {
+                    const form = await readForm(req);
+                    const commandId = form.command_id ?? "";
+                    const action = form.decision === "approve"
+                        ? "approve"
+                        : form.decision === "reject"
+                            ? "reject"
+                            : undefined;
+                    if (action === undefined) {
+                        writeJson(res, 400, {
+                            error: "invalid_request",
+                            message: "decision 必须是 approve/reject",
+                        });
+                        return;
+                    }
+                    const candidate = admin.surface.listPending().find((c) => c.candidate_id === commandId);
+                    if (candidate === undefined) {
+                        writeJson(res, 400, {
+                            error: "not_found",
+                            message: `未知或非 pending 命令 ${commandId}`,
+                        });
+                        return;
+                    }
+                    // 一次性确认凭证由执行层（命令日志）逐项核对并核销（候选内容摘要/
+                    // 主体/商家/动作/有效期/单次用途）——路由不再预消费，防双重核销。
+                    try {
+                        if (action === "approve") {
+                            await admin.surface.executeApproved(commandId, session.principal_id, form.confirmation);
+                        }
+                        else {
+                            await admin.surface.rejectCandidate(commandId, session.principal_id, form.confirmation);
+                        }
+                    }
+                    catch (err) {
+                        // 不回显异常消息（可能含内部细节）：只按「确认凭证失效」与「其余失败」
+                        // 两类给稳定结论，原文进 stderr。
+                        const expired = err instanceof Error && err.message.includes("确认凭证");
+                        process.stderr.write(`[merchant mcp] /admin/decision 失败：${err instanceof Error ? err.message : String(err)}\n`);
+                        writeJson(res, expired ? 403 : 400, {
+                            error: expired ? "invalid_confirmation" : "command_failed",
+                            message: expired ? "确认凭证无效或已过期，请刷新待批准页重试" : "审批未执行（详见服务日志）",
+                        });
+                        return;
+                    }
+                    // 回跳待批准页（PRG 模式）
+                    res.writeHead(303, { location: "/admin/pending" });
+                    res.end();
+                    return;
+                }
+                // ---- RFQ 管理页（v0.1.1 §11.4；批准/下载只在此通道） ------------------
+                const rfqAdmin = options.rfq;
+                if (rfqAdmin !== undefined && url.pathname === "/admin/rfq" && req.method === "GET") {
+                    res.writeHead(200, { "content-type": "text/html; charset=utf-8", ...NO_STORE_HEADERS });
+                    res.end(renderRfqDashboard(admin.merchantName, rfqAdmin.admin.listCases(session.principal_id, 50)));
+                    return;
+                }
+                if (rfqAdmin !== undefined && url.pathname.startsWith("/admin/rfq/cases/")) {
+                    const parts = url.pathname.split("/").filter((p) => p !== "");
+                    // /admin/rfq/cases/{id}[/confirm|/close]
+                    const caseId = parts[3] ?? "";
+                    if (req.method === "GET" && parts.length === 4) {
+                        res.writeHead(200, { "content-type": "text/html; charset=utf-8", ...NO_STORE_HEADERS });
+                        res.end(renderRfqCasePage(admin.merchantName, rfqAdmin.admin.getCase(caseId, session.principal_id)));
+                        return;
+                    }
+                    if (req.method === "POST" && parts[4] === "confirm") {
+                        const form = await readForm(req);
+                        const sku = (form.sku ?? "").trim();
+                        if (sku === "") {
+                            writeJson(res, 400, { error: "invalid_request", message: "确认需要 SKU（先在需求行选择商品）" });
+                            return;
+                        }
+                        const result = rfqAdmin.admin.confirmLines({
+                            caseId: caseId,
+                            expectedRevision: Number(form.expected_revision ?? "0"),
+                            selections: [{ line_id: form.line_id ?? "", sku }],
+                            principalId: session.principal_id,
+                        });
+                        writeJson(res, 200, { ok: true, result });
+                        return;
+                    }
+                    if (req.method === "POST" && parts[4] === "close") {
+                        const form = await readForm(req);
+                        const outcome = form.outcome === "CLOSED" ? "CLOSED" : "CANCELLED";
+                        const result = rfqAdmin.admin.closeCase({
+                            caseId: caseId,
+                            expectedRevision: Number(form.expected_revision ?? "0"),
+                            outcome,
+                            principalId: session.principal_id,
+                        });
+                        res.writeHead(303, { location: "/admin/rfq" });
+                        res.end();
+                        void result;
+                        return;
+                    }
+                }
+                if (rfqAdmin !== undefined && url.pathname.startsWith("/admin/rfq/releases/")) {
+                    const parts = url.pathname.split("/").filter((p) => p !== "");
+                    const releaseId = parts[3] ?? "";
+                    if (req.method === "GET" && parts.length === 4) {
+                        const detail = rfqAdmin.admin.releaseDetail(releaseId, session.principal_id);
+                        // 一次性确认凭证（绑定候选内容摘要 + 主体 + 商家 + 动作；单次用途）
+                        const tokenFor = (candidateId, action) => {
+                            const candidate = rfqAdmin.admin.candidateFor(candidateId);
+                            if (candidate === undefined)
+                                return "";
+                            return admin.store.createConfirmation({
+                                candidateId,
+                                candidateDigest: contentHash({
+                                    arguments: candidate.arguments,
+                                    preconditions: candidate.preconditions,
+                                }),
+                                principalId: session.principal_id,
+                                merchantId: session.merchant_id,
+                                action,
+                            });
+                        };
+                        res.writeHead(200, { "content-type": "text/html; charset=utf-8", ...NO_STORE_HEADERS });
+                        res.end(renderRfqReleasePage(admin.merchantName, detail, tokenFor));
+                        return;
+                    }
+                    if (req.method === "POST" && (parts[4] === "approve" || parts[4] === "reject")) {
+                        const form = await readForm(req);
+                        // release_id → 候选 id 解析：批准/拒绝作用于命令日志候选。
+                        const detail = rfqAdmin.admin.releaseDetail(releaseId, session.principal_id);
+                        const commandId = detail.candidate_id;
+                        if (commandId === "") {
+                            writeJson(res, 400, { error: "not_found", message: "该发布没有可操作的审批候选" });
+                            return;
+                        }
+                        try {
+                            if (parts[4] === "approve") {
+                                await rfqAdmin.admin.approveRelease(commandId, session.principal_id, form.confirmation);
+                            }
+                            else {
+                                await rfqAdmin.admin.rejectRelease(commandId, session.principal_id, form.confirmation);
+                            }
+                        }
+                        catch (err) {
+                            const expired = err instanceof Error && err.message.includes("确认凭证");
+                            process.stderr.write(`[merchant mcp] /admin/rfq/releases 决策失败：${err instanceof Error ? err.message : String(err)}\n`);
+                            writeJson(res, expired ? 403 : 400, {
+                                error: expired ? "invalid_confirmation" : "command_failed",
+                                message: expired ? "确认凭证无效或已过期，请刷新页面重试" : "审批未执行（详见服务日志）",
+                            });
+                            return;
+                        }
+                        res.writeHead(303, { location: `/admin/rfq/releases/${encodeURIComponent(releaseId)}` });
+                        res.end();
+                        return;
+                    }
+                }
+                if (rfqAdmin !== undefined && req.method === "GET" && url.pathname.startsWith("/admin/rfq/artifacts/")) {
+                    const artifactId = url.pathname.split("/").filter((p) => p !== "")[3] ?? "";
+                    try {
+                        const file = rfqAdmin.admin.downloadArtifact(artifactId, session.principal_id);
+                        res.writeHead(200, {
+                            "content-type": file.content_type,
+                            // 下载响应不落缓存（产物字节绑定批准摘要）。
+                            ...NO_STORE_HEADERS,
+                            "content-disposition": `attachment; filename="${file.filename.replaceAll('"', "")}"`,
+                        });
+                        res.end(file.content);
+                    }
+                    catch (err) {
+                        process.stderr.write(`[merchant mcp] 产物下载失败：${err instanceof Error ? err.message : String(err)}\n`);
+                        writeJson(res, 403, { error: "download_forbidden", message: "产物不可下载（未激活/摘要不一致/归属不符）" });
+                    }
+                    return;
+                }
+                if (rfqAdmin !== undefined && req.method === "POST" && /^\/admin\/rfq\/handoffs\/[^/]+\/owner-recorded$/.test(url.pathname)) {
+                    const handoffId = url.pathname.split("/").filter((p) => p !== "")[3] ?? "";
+                    const result = rfqAdmin.admin.markHandoffOwnerRecorded(handoffId, session.principal_id);
+                    writeJson(res, 200, { ok: true, result });
+                    return;
+                }
+                writeJson(res, 404, { error: "not_found" });
+                return;
+            }
+            if (url.pathname !== mcpPath) {
+                writeJson(res, 404, { error: "not_found", message: `unknown path ${url.pathname}` });
+                return;
+            }
+            let scopes;
+            if (options.auth !== undefined) {
+                const verdict = options.auth.verify({
+                    ...(typeof req.headers.authorization === "string"
+                        ? { authorizationHeader: req.headers.authorization }
+                        : {}),
+                });
+                if (!verdict.ok) {
+                    // RFC 9728：401 携带 resource_metadata 指引客户端发现授权服务器。
+                    writeJson(res, 401, { error: "unauthorized", message: "认证失败：需要有效的 Bearer token" }, {
+                        "www-authenticate": options.oauth !== undefined
+                            ? `Bearer resource_metadata="${options.oauth.resourceMetadataUrl}"`
+                            : "Bearer",
+                    });
+                    return;
+                }
+                // OAuth 模式按 token scope 过滤；静态 token 过渡模式全量（undefined）。
+                scopes = verdict.authorization?.scopes;
+            }
+            if (req.method !== "POST" && req.method !== "GET" && req.method !== "DELETE") {
+                writeJson(res, 405, { error: "method_not_allowed" }, { allow: "POST, GET, DELETE" });
+                return;
+            }
+            let body;
+            try {
+                body = req.method === "POST" ? await readBody(req) : undefined;
+            }
+            catch (err) {
+                // 超限 413；其余（JSON 解析失败等）属客户端错误 → 400（审查 P2）。
+                const tooLarge = err instanceof Error && err.message.includes("exceeds");
+                if (!tooLarge) {
+                    process.stderr.write(`[merchant mcp] /mcp body 解析失败：${err instanceof Error ? err.message : String(err)}\n`);
+                }
+                // 不回显异常消息：响应只给稳定结论，细节已在上面进 stderr。
+                writeJson(res, tooLarge ? 413 : 400, {
+                    error: "invalid_request",
+                    message: tooLarge ? "请求体超过大小上限" : "请求体无法解析",
+                });
+                return;
+            }
+            const protocolServer = createProtocolServer(serverInfo, toolsBundle, scopes, options.presentations, options.rfq?.resources);
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined,
+                enableJsonResponse: true,
+            });
+            transports.add(transport);
+            res.on("close", () => {
+                transports.delete(transport);
+                void transport.close().catch(() => undefined);
+                void protocolServer.close().catch(() => undefined);
+            });
+            try {
+                await protocolServer.connect(transport);
+                await transport.handleRequest(req, res, body);
+            }
+            catch (err) {
+                // 内部异常消息（可能含栈/上游响应内容）只进 stderr，不回显给调用方。
+                process.stderr.write(`[merchant mcp] /mcp transport error：${err instanceof Error ? err.message : String(err)}\n`);
+                if (!res.headersSent) {
+                    writeJson(res, 500, { error: "internal_error", message: "服务内部错误" });
+                }
+                else {
+                    res.end();
+                }
+            }
+        })().catch((err) => {
+            // 审查 P2：顶层静默吞错让排障无迹——记错误摘要（不含 body 与凭据）。
+            process.stderr.write(`[merchant mcp] ${req.method} ${req.url ?? "/"} 处理异常：` +
+                `${err instanceof Error ? err.message : String(err)}\n`);
+            if (!res.headersSent)
+                writeJson(res, 500, { error: "internal_error" });
+            else
+                res.end();
+        });
+    };
+    return {
+        handler,
+        close: async () => {
+            if (closing)
+                return;
+            closing = true;
+            for (const transport of transports) {
+                await transport.close().catch(() => undefined);
+            }
+            transports.clear();
+        },
+    };
+}
+/**
+ * 启动 Merchant MCP Server（streamable HTTP，无状态）。
+ * 返回 handle 含实际 host/port（port 传 0 时取 ephemeral 端口）与优雅关闭。
+ */
+export async function startMerchantMcpServer(options) {
+    const host = options.host ?? DEFAULT_MERCHANT_MCP_HOST;
+    const port = options.port ?? DEFAULT_MERCHANT_MCP_PORT;
+    const mcpPath = options.path ?? DEFAULT_MERCHANT_MCP_PATH;
+    const { handler, close: closeHandler } = createMerchantHttpHandler(options);
+    const httpServer = createServer(handler);
+    await new Promise((resolve, reject) => {
+        httpServer.once("error", reject);
+        httpServer.listen(port, host, () => resolve());
+    });
+    const address = httpServer.address();
+    const boundPort = typeof address === "object" && address !== null ? address.port : port;
+    return {
+        host,
+        port: boundPort,
+        path: mcpPath,
+        url: `http://${host === "0.0.0.0" ? "127.0.0.1" : host}:${boundPort}${mcpPath}`,
+        close: async () => {
+            await closeHandler();
+            await new Promise((resolve) => {
+                httpServer.close(() => resolve());
+                httpServer.closeAllConnections();
+            });
+        },
+    };
+}
+//# sourceMappingURL=merchant-server.js.map