@harrylabsj/kiwi 0.8.0 → 0.10.0

package/dist/merchant-gateway/pinned-fetch.js

@@ -0,0 +1,231 @@
+/**
+ * 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.
+ */
+/**
+ * 面向商家自有实例的**钉住式**出站请求（SSRF / DNS 重绑定加固）。
+ *
+ * 背景：商家实例地址由商家自己提供（自助绑定 / 配对码），属于不可信输入。
+ * 只做静态校验（https + 非私网字面 IP）挡不住两类攻击：
+ *
+ *   1. **解析后落到内网**：域名静态看没问题，但解析出 10.x / 169.254 / ::1；
+ *   2. **DNS 重绑定（TOCTOU）**：校验时解析到公网 IP，随后 fetch 再解析一次
+ *      却拿到内网 IP。
+ *
+ * 本模块的做法：**一次解析、校验、然后直接用该 IP 建连**（`host: <ip>` +
+ * `servername`/`Host: <主机名>`），不再给运行时第二次解析的机会——这就是钉住。
+ * 校验规则复用 A2A 出站守卫（`assertResolvableTargetUrl`）：任一解析结果落在
+ * 保留/私网段、或"公网域名解析到 loopback"，一律 fail-closed 拒绝。
+ *
+ * loopback 与字面 IP 不走钉住：前者是本地/同机形态（静态策略已允许且已在
+ * 白名单内），后者没有解析步骤可被劫持。
+ *
+ * 只覆盖网关需要的调用形态（JSON/文本体的 GET/POST，不跟随重定向、读完整
+ * 响应体），不是 fetch 的完整实现。
+ */
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+import { assertResolvableTargetUrl, isLoopbackHost } from "../a2a/client/url-policy.js";
+export class PinnedFetchError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PinnedFetchError";
+    }
+}
+async function defaultResolve(hostname) {
+    const addresses = await lookup(hostname, { all: true, verbatim: true });
+    return addresses.map((entry) => entry.address);
+}
+/**
+ * 请求头归一化：接受 Headers / 键值对数组 / 普通对象（调用方可能传 fetch 的
+ * RequestInit.headers 或我们自己的字面量）。用 unknown 收口，避免依赖
+ * 各类型定义里对 HeadersInit 的差异。
+ */
+function headersToObject(init) {
+    if (init === undefined || init === null)
+        return {};
+    if (init instanceof Headers)
+        return Object.fromEntries(init.entries());
+    if (Array.isArray(init)) {
+        return Object.fromEntries(init);
+    }
+    if (typeof init === "object")
+        return { ...init };
+    return {};
+}
+/** 过滤掉 undefined 值（Node 的请求头不接受 undefined）。 */
+function definedHeaders(headers) {
+    const result = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (typeof value === "string")
+            result[key] = value;
+    }
+    return result;
+}
+/** 字面 IP（v4/v6）判定：这些地址没有可被劫持的解析步骤。 */
+function isIpLiteral(hostname) {
+    return isIP(hostname.replace(/^\[|\]$/g, "")) !== 0;
+}
+function nodeHeadersToPairs(headers) {
+    const pairs = [];
+    for (const [key, value] of Object.entries(headers)) {
+        if (value === undefined)
+            continue;
+        pairs.push([key, Array.isArray(value) ? value.join(", ") : value]);
+    }
+    return pairs;
+}
+/**
+ * 解析 + 校验 + 选定一个可直连的 IP。
+ *
+ * 与 `assertResolvableTargetUrl` 同一套规则，但把「校验用的解析结果」原样
+ * 返回给调用方去建连，消除两次解析之间的窗口。
+ */
+export async function resolvePinnedAddress(hostname, resolve) {
+    let addresses;
+    try {
+        addresses = await resolve(hostname);
+    }
+    catch {
+        throw new PinnedFetchError(`无法解析实例主机名：${hostname}`);
+    }
+    if (addresses.length === 0) {
+        throw new PinnedFetchError(`实例主机名未解析出任何地址：${hostname}`);
+    }
+    // 复用 A2A 守卫的判定（含"公网域名解析到 loopback 一律拒绝"），
+    // 并固定用同一批解析结果做校验与建连。拒绝原因统一包装成 PinnedFetchError。
+    try {
+        await assertResolvableTargetUrl(new URL(`https://${hostname}/`), {
+            resolveIp: async () => addresses,
+        });
+    }
+    catch (err) {
+        throw new PinnedFetchError(`实例主机名被出站策略拒绝：${err instanceof Error ? err.message : String(err)}`);
+    }
+    const [first] = addresses;
+    if (first === undefined) {
+        throw new PinnedFetchError(`实例主机名未解析出任何地址：${hostname}`);
+    }
+    return first;
+}
+/**
+ * 按**给定地址**建连（钉住的落点），HTTP 适配层：
+ * `host: <address>` + `Host: <主机名>`（https 另加 servername 供 SNI/证书校验）。
+ * 单独导出便于对本地服务做往返测试（不经过 DNS 策略）。
+ */
+export async function requestViaAddress(url, address, init = {}, maxResponseBytes = 1_048_576) {
+    const method = init.method ?? "GET";
+    const headers = headersToObject(init.headers);
+    const body = init.body;
+    const secure = url.protocol === "https:";
+    const request = secure ? httpsRequest : httpRequest;
+    const port = url.port === "" ? (secure ? 443 : 80) : Number(url.port);
+    const defaultPort = secure ? "443" : "80";
+    const hostHeader = url.port === "" || url.port === defaultPort ? url.hostname : `${url.hostname}:${url.port}`;
+    return await new Promise((resolvePromise, rejectPromise) => {
+        const req = request({
+            host: address,
+            port,
+            path: `${url.pathname}${url.search}`,
+            method,
+            headers: {
+                ...definedHeaders(headers),
+                host: hostHeader,
+            },
+            ...(secure ? { servername: url.hostname } : {}),
+            ...(init.signal !== undefined && init.signal !== null
+                ? { signal: init.signal }
+                : {}),
+        }, (res) => {
+            const chunks = [];
+            let size = 0;
+            let settled = false;
+            const rejectOnce = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                rejectPromise(error);
+            };
+            res.on("data", (chunk) => {
+                size += chunk.length;
+                if (size > maxResponseBytes) {
+                    res.destroy();
+                    rejectOnce(new PinnedFetchError(`实例响应体超过 ${maxResponseBytes} 字节上限`));
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            res.on("end", () => {
+                if (settled)
+                    return;
+                settled = true;
+                resolvePromise(new Response(Buffer.concat(chunks), {
+                    status: res.statusCode ?? 0,
+                    statusText: res.statusMessage ?? "",
+                    headers: nodeHeadersToPairs(res.headers),
+                }));
+            });
+            res.on("error", rejectOnce);
+        });
+        req.on("error", (err) => {
+            rejectPromise(err instanceof Error && err.name === "AbortError"
+                ? err
+                : new PinnedFetchError(`实例请求失败（${url.hostname}）：${err.message}`));
+        });
+        if (typeof body === "string")
+            req.write(body);
+        req.end();
+    });
+}
+/**
+ * 构造一个把目标主机**钉在已校验 IP** 上的 fetch 实现。
+ *
+ * 语义与 fetch 的差异（故意为之）：不跟随重定向；响应体一次性读完（JSON-RPC
+ * 体量小）；不处理 cookie / 流式上传。
+ */
+export function createPinnedFetch(options = {}) {
+    const resolve = options.resolveIp ?? defaultResolve;
+    const pinnedFetch = async (input, init) => {
+        const requestInit = init ?? {};
+        const url = new URL(typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url);
+        const method = requestInit.method ?? (input instanceof Request ? input.method : "GET");
+        const headers = {
+            ...headersToObject(input instanceof Request ? input.headers : undefined),
+            ...headersToObject(requestInit.headers),
+        };
+        const body = requestInit.body;
+        // loopback / 字面 IP：无解析步骤可被劫持，直接按该主机建连（仍走同一适配层）
+        // ——统一路径的另一个好处：不经过全局 fetch 的连接池，实例重启后不会因为
+        // 复用到失效的 keep-alive 连接而出现一次 ECONNRESET（表现为 backend_unavailable）。
+        if (isLoopbackHost(url.hostname) || isIpLiteral(url.hostname)) {
+            return await requestViaAddress(url, url.hostname.replace(/^\[|\]$/g, ""), {
+                method,
+                headers,
+                ...(body !== undefined && body !== null ? { body } : {}),
+                ...(requestInit.signal !== undefined ? { signal: requestInit.signal } : {}),
+            }, options.maxResponseBytes);
+        }
+        const pinnedIp = await resolvePinnedAddress(url.hostname, resolve);
+        return await requestViaAddress(url, pinnedIp, {
+            method,
+            headers,
+            ...(body !== undefined && body !== null ? { body } : {}),
+            ...(requestInit.signal !== undefined ? { signal: requestInit.signal } : {}),
+        }, options.maxResponseBytes);
+    };
+    return pinnedFetch;
+}
+//# sourceMappingURL=pinned-fetch.js.map

package/dist/merchant-gateway/pinned-fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pinned-fetch.js","sourceRoot":"","sources":["../../src/merchant-gateway/pinned-fetch.ts"],"names":[],"mappings":"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"}

package/dist/merchant-gateway/tenant-registry.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 商家连接器入口的受信任后端注册表（第 1 版实例路由）。
+ *
+ * 入口只知道自己的公网 URL；它从**已验证 OAuth token 的 merchant_id** 选择
+ * 服务端注册的商家实例，绝不使用模型工具参数或客户端可填写的 URL 路由。
+ *
+ * URL 策略（fail-closed，对齐商家连接器发布计划 §3.3）：
+ *   - 非 loopback 必须是 https（明文 http 仅限 loopback 开发实例）；
+ *   - 复用 A2A 出站守卫 `assertSafeTargetUrl`：拒绝 userinfo、保留主机名、
+ *     字面保留 IP；路径必须恰为 `/mcp`，不得带查询串或片段；
+ *   - loopback 实例必须显式指定端口（避免误连本机其它服务）。
+ *
+ * **仍未覆盖**（不得宣称已支持异地自托管）：请求时的 DNS/IP 钉住与 mTLS
+ * 尚未实现——`assertResolvableTargetUrl` 只做解析后私网复查，不能替代钉住；
+ * 服务认领（配对码）与凭证轮换属后续增量。
+ */
+import type { MerchantAuthorization } from "../auth/merchant-authorization.js";
+import type { MerchantCredentialStore } from "./credential-vault.js";
+/** 实例内部凭据的保管库键前缀（与目录凭据 cmt_ 分开放）。 */
+export declare const INSTANCE_CREDENTIAL_KIND = "instance";
+export interface TenantBackendConfig {
+    merchantId: string;
+    /** 商家自有实例的 MCP 地址：https，或 loopback http；路径恰为 /mcp。 */
+    mcpUrl: string;
+    /** 内部凭据来源：进程环境变量名（运维侧注入）。 */
+    tokenEnv?: string;
+    /** 内部凭据来源：入口凭据保管库（加密存储；键 `<merchant_id>`，kind=instance）。 */
+    credentialKind?: "env" | "vault";
+}
+export interface ResolvedTenantBackend {
+    merchantId: string;
+    mcpUrl: string;
+    bearerToken: string;
+}
+export declare class TenantBackendError extends Error {
+    readonly code: "invalid_config" | "service_not_connected" | "backend_credentials_missing";
+    constructor(message: string, code: "invalid_config" | "service_not_connected" | "backend_credentials_missing");
+}
+/** 实例 MCP 地址规范化 + 出站策略校验（绑定页与注册表共用同一口径）。 */
+export declare function canonicalInstanceUrl(value: string): string;
+export interface TenantBackendRegistryOptions {
+    /** 凭据保管库（`credentialKind: "vault"` 的实例从这里取内部凭据）。 */
+    credentials?: MerchantCredentialStore;
+    /**
+     * 动态注册（商家自助绑定，§8.4 第一期）：静态配置未命中时按 merchant_id
+     * 查询商家自行绑定的实例地址；凭据同样从保管库取（键 `instance:<id>`）。
+     */
+    dynamic?: {
+        lookup(merchantId: string): {
+            mcpUrl: string;
+        } | undefined;
+    };
+}
+/**
+ * 解析运维提供的租户配置（JSON 文本）→ 注册表配置。
+ *
+ * 形状：
+ * ```json
+ * { "tenants": [
+ *   { "merchant_id": "mkt_acme_1", "mcp_url": "https://merchant.acme.example/mcp",
+ *     "token_env": "ACME_MCP_TOKEN" },
+ *   { "merchant_id": "mkt_dev_1", "mcp_url": "http://127.0.0.1:9100/mcp",
+ *     "credential_kind": "vault" }
+ * ] }
+ * ```
+ * 字段缺失/类型不符一律抛 TenantBackendError（invalid_config），不做默认填充。
+ */
+export declare function loadTenantBackendConfigs(raw: string): TenantBackendConfig[];
+/** 只由运维配置构造；尚未配对的商家不进入注册表（第 0 版能力不受影响）。 */
+export declare class TenantBackendRegistry {
+    private readonly backends;
+    private readonly env;
+    private readonly credentials;
+    private readonly dynamic;
+    constructor(configs: TenantBackendConfig[], env?: Record<string, string | undefined>, options?: TenantBackendRegistryOptions);
+    /** 该商家是否已注册实例（静态配置或商家自助绑定）。 */
+    has(merchantId: string): boolean;
+    /** 已注册实例数量（启动摘要用）。 */
+    get size(): number;
+    /** OAuth 校验之后调用；不接受 tool arguments 中的 merchant_id 作为路由依据。 */
+    resolve(authorization: MerchantAuthorization): ResolvedTenantBackend;
+}

package/dist/merchant-gateway/tenant-registry.js

@@ -0,0 +1,190 @@
+/**
+ * 商家连接器入口的受信任后端注册表（第 1 版实例路由）。
+ *
+ * 入口只知道自己的公网 URL；它从**已验证 OAuth token 的 merchant_id** 选择
+ * 服务端注册的商家实例，绝不使用模型工具参数或客户端可填写的 URL 路由。
+ *
+ * URL 策略（fail-closed，对齐商家连接器发布计划 §3.3）：
+ *   - 非 loopback 必须是 https（明文 http 仅限 loopback 开发实例）；
+ *   - 复用 A2A 出站守卫 `assertSafeTargetUrl`：拒绝 userinfo、保留主机名、
+ *     字面保留 IP；路径必须恰为 `/mcp`，不得带查询串或片段；
+ *   - loopback 实例必须显式指定端口（避免误连本机其它服务）。
+ *
+ * **仍未覆盖**（不得宣称已支持异地自托管）：请求时的 DNS/IP 钉住与 mTLS
+ * 尚未实现——`assertResolvableTargetUrl` 只做解析后私网复查，不能替代钉住；
+ * 服务认领（配对码）与凭证轮换属后续增量。
+ */
+import { assertSafeTargetUrl, isLoopbackHost } from "../a2a/client/url-policy.js";
+/** 实例内部凭据的保管库键前缀（与目录凭据 cmt_ 分开放）。 */
+export const INSTANCE_CREDENTIAL_KIND = "instance";
+export class TenantBackendError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "TenantBackendError";
+    }
+}
+/** 实例 MCP 地址规范化 + 出站策略校验（绑定页与注册表共用同一口径）。 */
+export function canonicalInstanceUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new TenantBackendError("商家 MCP 后端 URL 非法", "invalid_config");
+    }
+    // 明文 http 仅限 loopback；非 loopback 必须 https。保留主机名/字面保留 IP 拒绝。
+    try {
+        assertSafeTargetUrl(value, { allowLoopback: true });
+    }
+    catch (err) {
+        throw new TenantBackendError(`商家 MCP 后端地址被出站策略拒绝：${err instanceof Error ? err.message : String(err)}`, "invalid_config");
+    }
+    if (url.pathname !== "/mcp" || url.search !== "" || url.hash !== "") {
+        throw new TenantBackendError("商家 MCP 后端路径必须恰为 /mcp，且不含查询串或片段", "invalid_config");
+    }
+    if (isLoopbackHost(url.hostname)) {
+        if (url.port === "" || Number(url.port) <= 0 || Number(url.port) > 65535) {
+            throw new TenantBackendError("loopback 商家后端必须显式指定有效端口", "invalid_config");
+        }
+    }
+    else if (url.port !== "" && (Number(url.port) <= 0 || Number(url.port) > 65535)) {
+        throw new TenantBackendError("商家 MCP 后端端口非法", "invalid_config");
+    }
+    return url.toString();
+}
+/**
+ * 解析运维提供的租户配置（JSON 文本）→ 注册表配置。
+ *
+ * 形状：
+ * ```json
+ * { "tenants": [
+ *   { "merchant_id": "mkt_acme_1", "mcp_url": "https://merchant.acme.example/mcp",
+ *     "token_env": "ACME_MCP_TOKEN" },
+ *   { "merchant_id": "mkt_dev_1", "mcp_url": "http://127.0.0.1:9100/mcp",
+ *     "credential_kind": "vault" }
+ * ] }
+ * ```
+ * 字段缺失/类型不符一律抛 TenantBackendError（invalid_config），不做默认填充。
+ */
+export function loadTenantBackendConfigs(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new TenantBackendError(`租户配置不是合法 JSON：${err instanceof Error ? err.message : String(err)}`, "invalid_config");
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new TenantBackendError("租户配置必须是对象", "invalid_config");
+    }
+    const tenants = parsed.tenants;
+    if (!Array.isArray(tenants)) {
+        throw new TenantBackendError('租户配置缺 "tenants" 数组', "invalid_config");
+    }
+    const configs = [];
+    for (const element of tenants) {
+        if (element === null || typeof element !== "object" || Array.isArray(element)) {
+            throw new TenantBackendError("tenants[] 必须是对象", "invalid_config");
+        }
+        const record = element;
+        const merchantId = typeof record.merchant_id === "string" ? record.merchant_id.trim() : "";
+        const mcpUrl = typeof record.mcp_url === "string" ? record.mcp_url.trim() : "";
+        if (merchantId === "" || mcpUrl === "") {
+            throw new TenantBackendError("tenants[] 必须含 merchant_id 与 mcp_url", "invalid_config");
+        }
+        const tokenEnv = typeof record.token_env === "string" ? record.token_env.trim() : undefined;
+        const kindRaw = record.credential_kind;
+        const credentialKind = kindRaw === undefined ? undefined : kindRaw === "vault" ? "vault" : undefined;
+        if (kindRaw !== undefined && credentialKind === undefined) {
+            throw new TenantBackendError(`tenants[] credential_kind 只支持 "vault"（实际 ${String(kindRaw)}）`, "invalid_config");
+        }
+        configs.push({
+            merchantId,
+            mcpUrl,
+            ...(tokenEnv !== undefined ? { tokenEnv } : {}),
+            ...(credentialKind !== undefined ? { credentialKind } : {}),
+        });
+    }
+    return configs;
+}
+/** 只由运维配置构造；尚未配对的商家不进入注册表（第 0 版能力不受影响）。 */
+export class TenantBackendRegistry {
+    backends = new Map();
+    env;
+    credentials;
+    dynamic;
+    constructor(configs, env = process.env, options = {}) {
+        this.env = env;
+        this.credentials = options.credentials;
+        this.dynamic = options.dynamic;
+        for (const config of configs) {
+            const merchantId = config.merchantId.trim();
+            if (!merchantId || !/^[a-zA-Z0-9:_-]+$/.test(merchantId)) {
+                throw new TenantBackendError("商家后端配置缺合法 merchantId", "invalid_config");
+            }
+            if (this.backends.has(merchantId)) {
+                throw new TenantBackendError(`重复商家后端配置：${merchantId}`, "invalid_config");
+            }
+            const kind = config.credentialKind ?? "env";
+            if (kind === "env") {
+                if (config.tokenEnv === undefined || !/^[A-Z][A-Z0-9_]*$/.test(config.tokenEnv)) {
+                    throw new TenantBackendError("商家后端 tokenEnv 必须是环境变量名", "invalid_config");
+                }
+            }
+            else if (config.tokenEnv !== undefined) {
+                throw new TenantBackendError(`商家后端 ${merchantId} 的凭据来源只能二选一（tokenEnv 或 credentialKind）`, "invalid_config");
+            }
+            this.backends.set(merchantId, {
+                merchantId,
+                mcpUrl: canonicalInstanceUrl(config.mcpUrl),
+                ...(config.tokenEnv !== undefined ? { tokenEnv: config.tokenEnv } : {}),
+                credentialKind: kind,
+            });
+        }
+    }
+    /** 该商家是否已注册实例（静态配置或商家自助绑定）。 */
+    has(merchantId) {
+        if (this.backends.has(merchantId))
+            return true;
+        return this.dynamic?.lookup(merchantId) !== undefined;
+    }
+    /** 已注册实例数量（启动摘要用）。 */
+    get size() {
+        return this.backends.size;
+    }
+    /** OAuth 校验之后调用；不接受 tool arguments 中的 merchant_id 作为路由依据。 */
+    resolve(authorization) {
+        if (!authorization.principal_id || !authorization.merchant_id) {
+            throw new TenantBackendError("未认证的商家主体", "service_not_connected");
+        }
+        const backend = this.backends.get(authorization.merchant_id);
+        if (backend === undefined) {
+            // 商家自助绑定（§8.4）：地址来自注册表、凭据来自加密保管库；地址在这里
+            // 再校验一次（防配置被改动后绕过出站策略）。
+            const registered = this.dynamic?.lookup(authorization.merchant_id);
+            if (registered === undefined) {
+                throw new TenantBackendError("当前商家尚未连接 Kiwi Merchant 实例", "service_not_connected");
+            }
+            const bearerToken = this.credentials?.get(`${INSTANCE_CREDENTIAL_KIND}:${authorization.merchant_id}`)?.token ??
+                "";
+            if (!bearerToken) {
+                throw new TenantBackendError("商家后端内部凭据未配置", "backend_credentials_missing");
+            }
+            return {
+                merchantId: authorization.merchant_id,
+                mcpUrl: canonicalInstanceUrl(registered.mcpUrl),
+                bearerToken,
+            };
+        }
+        const bearerToken = backend.credentialKind === "vault"
+            ? (this.credentials?.get(`${INSTANCE_CREDENTIAL_KIND}:${backend.merchantId}`)?.token ?? "")
+            : (this.env[String(backend.tokenEnv)] ?? "");
+        if (!bearerToken) {
+            throw new TenantBackendError("商家后端内部凭据未配置", "backend_credentials_missing");
+        }
+        return { merchantId: backend.merchantId, mcpUrl: backend.mcpUrl, bearerToken };
+    }
+}
+//# sourceMappingURL=tenant-registry.js.map

package/dist/merchant-gateway/tenant-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-registry.js","sourceRoot":"","sources":["../../src/merchant-gateway/tenant-registry.ts"],"names":[],"mappings":"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"}

package/dist/merchant-gateway/tool-bundle.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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.
+ */
+/**
+ * 把多个带 scope 的工具束合成一个（入口同时提供第 0 版目录工具与第 1 版
+ * 实例工具）。
+ *
+ * 语义：
+ *   - `listTools`：按名去重后拼接（同名工具以先出现的束为准）；
+ *   - `call`：按工具名路由到提供它的束；都没有则返回可解释错误；
+ *   - 空数组返回 `undefined`（调用方据此对调用方隐藏全部工具）。
+ */
+import type { ScopedMcpTools } from "../mcp/merchant-server.js";
+export declare function combineScopedTools(bundles: Array<ScopedMcpTools | undefined>): ScopedMcpTools | undefined;

package/dist/merchant-gateway/tool-bundle.js

@@ -0,0 +1,56 @@
+/**
+ * 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.
+ */
+export function combineScopedTools(bundles) {
+    const active = bundles.filter((bundle) => bundle !== undefined);
+    if (active.length === 0)
+        return undefined;
+    if (active.length === 1)
+        return active[0];
+    const callTool = async (name, args, scopes) => {
+        for (const bundle of active) {
+            const tools = await bundle.listTools(scopes);
+            if (tools.some((tool) => tool.name === name)) {
+                return await bundle.call(name, args, scopes);
+            }
+        }
+        return undefined;
+    };
+    return {
+        listTools: async (scopes) => {
+            const merged = [];
+            const seen = new Set();
+            for (const bundle of active) {
+                for (const tool of await bundle.listTools(scopes)) {
+                    if (seen.has(tool.name))
+                        continue;
+                    seen.add(tool.name);
+                    merged.push(tool);
+                }
+            }
+            return merged;
+        },
+        call: async (name, args, scopes) => {
+            const result = await callTool(name, args, scopes);
+            if (result !== undefined)
+                return result;
+            return {
+                content: [{ type: "text", text: `未提供工具 ${name}（可能未授权、或该商家尚未连接实例）` }],
+                isError: true,
+            };
+        },
+    };
+}
+//# sourceMappingURL=tool-bundle.js.map

package/dist/merchant-gateway/tool-bundle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-bundle.js","sourceRoot":"","sources":["../../src/merchant-gateway/tool-bundle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAeH,MAAM,UAAU,kBAAkB,CAChC,OAA0C;IAE1C,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAA4B,EAAE,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC;IAC1F,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC1C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;IAE1C,MAAM,QAAQ,GAAG,KAAK,EACpB,IAAY,EACZ,IAA6B,EAC7B,MAA4B,EACgB,EAAE;QAC9C,KAAK,MAAM,MAAM,IAAI,MAAM,EAAE,CAAC;YAC5B,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;YAC7C,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;gBAC7C,OAAO,MAAM,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;YAC/C,CAAC;QACH,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC,CAAC;IAEF,OAAO;QACL,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE;YAC1B,MAAM,MAAM,GAAgC,EAAE,CAAC;YAC/C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;YAC/B,KAAK,MAAM,MAAM,IAAI,MAAM,EAAE,CAAC;gBAC5B,KAAK,MAAM,IAAI,IAAI,MAAM,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;oBAClD,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;wBAAE,SAAS;oBAClC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;oBACpB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACpB,CAAC;YACH,CAAC;YACD,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;YACjC,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;YAClD,IAAI,MAAM,KAAK,SAAS;gBAAE,OAAO,MAAM,CAAC;YACxC,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,IAAI,oBAAoB,EAAE,CAAC;gBACpE,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}