@harrylabsj/kiwi 0.7.22 → 0.9.0

package/dist/merchant-gateway/instance-tools.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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.
+ */
+/**
+ * 第 1 版实例工具：把已配对商家实例的 `kiwi_merchant_*` 工具暴露给该商家。
+ *
+ * 路由与隔离：
+ *   - 工具列表**从实例现取**（`tools/list` 经 mcp-proxy 转发并按 scope 过滤），
+ *     网关不硬编码工具清单，避免与实例版本漂移；
+ *   - 调用经 `proxyTenantMcp` 转发，租户仍由已验证 token 的 `merchant_id` 决定；
+ *   - 未配对实例、内部凭据缺失或实例不可用时，第 1 版工具**不出现/明确报错**，
+ *     第 0 版目录能力不受影响（发布计划 §4 第 1 条）。
+ *
+ * 缓存的只是工具清单（按商家 60 秒），不含任何业务数据；凭据从不进入缓存。
+ */
+import type { MerchantAuthorization } from "../auth/merchant-authorization.js";
+import type { ScopedMcpTools } from "../mcp/merchant-server.js";
+import type { MerchantMcpCallResult, MerchantMcpToolDefinition } from "../mcp/merchant-tools.js";
+import { TenantBackendRegistry } from "./tenant-registry.js";
+/** 工具清单缓存（每商家一条；TTL 内复用，避免每次 tools/list 都打实例）。 */
+export declare class InstanceToolListCache {
+    private readonly ttlMs;
+    private readonly entries;
+    constructor(ttlMs?: number);
+    get(merchantId: string, nowMs: number): MerchantMcpToolDefinition[] | undefined;
+    set(merchantId: string, tools: MerchantMcpToolDefinition[], nowMs: number): void;
+    clear(): void;
+}
+export interface InstanceToolDeps {
+    registry: TenantBackendRegistry;
+    authorization: MerchantAuthorization;
+    fetchImpl?: typeof fetch;
+    cache?: InstanceToolListCache;
+    now?: () => number;
+}
+/** 解析实例返回的 tools/list 结果（形状不符的条目直接丢弃，不编造工具）。 */
+export declare function parseToolList(payload: unknown): MerchantMcpToolDefinition[];
+/** 解析实例返回的 tools/call 结果 → 网关的调用结果形状。 */
+export declare function parseCallResult(payload: unknown): MerchantMcpCallResult;
+/**
+ * 构建绑定到该商家实例的工具束。
+ *
+ * 未配对实例（注册表无该 merchant_id）或内部凭据不可用时返回 `undefined`：
+ * 第 1 版工具对调用方**不可见**，第 0 版目录工具与目录发布继续可用。
+ */
+export declare function buildInstanceTools(deps: InstanceToolDeps): ScopedMcpTools | undefined;

package/dist/merchant-gateway/instance-tools.js

@@ -0,0 +1,184 @@
+/**
+ * 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.
+ */
+import { proxyTenantMcp } from "./mcp-proxy.js";
+import { createPinnedFetch } from "./pinned-fetch.js";
+import { TenantBackendError, TenantBackendRegistry } from "./tenant-registry.js";
+const DEFAULT_TOOL_CACHE_TTL_MS = 60_000;
+/** 工具清单缓存（每商家一条；TTL 内复用，避免每次 tools/list 都打实例）。 */
+export class InstanceToolListCache {
+    ttlMs;
+    entries = new Map();
+    constructor(ttlMs = DEFAULT_TOOL_CACHE_TTL_MS) {
+        this.ttlMs = ttlMs;
+    }
+    get(merchantId, nowMs) {
+        const entry = this.entries.get(merchantId);
+        if (entry === undefined)
+            return undefined;
+        if (entry.expiresAt <= nowMs) {
+            this.entries.delete(merchantId);
+            return undefined;
+        }
+        return entry.tools;
+    }
+    set(merchantId, tools, nowMs) {
+        this.entries.set(merchantId, { tools, expiresAt: nowMs + this.ttlMs });
+    }
+    clear() {
+        this.entries.clear();
+    }
+}
+function fail(message) {
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+/** 解析实例返回的 tools/list 结果（形状不符的条目直接丢弃，不编造工具）。 */
+export function parseToolList(payload) {
+    if (payload === null || typeof payload !== "object")
+        return [];
+    const result = payload.result;
+    if (result === null || typeof result !== "object")
+        return [];
+    const tools = result.tools;
+    if (!Array.isArray(tools))
+        return [];
+    const parsed = [];
+    for (const element of tools) {
+        if (element === null || typeof element !== "object")
+            continue;
+        const record = element;
+        const name = typeof record.name === "string" ? record.name : "";
+        if (name === "")
+            continue;
+        parsed.push({
+            name,
+            description: typeof record.description === "string" ? record.description : "",
+            inputSchema: record.inputSchema !== null && typeof record.inputSchema === "object"
+                ? record.inputSchema
+                : { type: "object", properties: {} },
+        });
+    }
+    return parsed;
+}
+/** 解析实例返回的 tools/call 结果 → 网关的调用结果形状。 */
+export function parseCallResult(payload) {
+    if (payload === null || typeof payload !== "object") {
+        return fail("商家实例返回了无法解析的结果");
+    }
+    const record = payload;
+    if (record.error !== undefined && record.error !== null) {
+        const message = typeof record.error === "object" && record.error !== null
+            ? String(record.error.message ?? "未知错误")
+            : String(record.error);
+        return fail(`商家实例返回错误：${message}`);
+    }
+    const result = record.result;
+    if (result === null || typeof result !== "object") {
+        return fail("商家实例未返回工具结果");
+    }
+    const content = result.content;
+    const textItems = [];
+    if (Array.isArray(content)) {
+        for (const item of content) {
+            if (item === null || typeof item !== "object")
+                continue;
+            const entry = item;
+            if (entry.type === "text" && typeof entry.text === "string") {
+                textItems.push({ type: "text", text: entry.text });
+            }
+            else {
+                textItems.push({ type: "text", text: JSON.stringify(entry) });
+            }
+        }
+    }
+    const isError = result.isError === true;
+    const outcome = {
+        content: textItems.length > 0 ? textItems : [{ type: "text", text: "{}" }],
+        ...(isError ? { isError: true } : {}),
+    };
+    return outcome;
+}
+/**
+ * 构建绑定到该商家实例的工具束。
+ *
+ * 未配对实例（注册表无该 merchant_id）或内部凭据不可用时返回 `undefined`：
+ * 第 1 版工具对调用方**不可见**，第 0 版目录工具与目录发布继续可用。
+ */
+export function buildInstanceTools(deps) {
+    try {
+        deps.registry.resolve(deps.authorization);
+    }
+    catch (err) {
+        if (err instanceof TenantBackendError)
+            return undefined;
+        throw err;
+    }
+    const merchantId = deps.authorization.merchant_id;
+    const cache = deps.cache ?? new InstanceToolListCache();
+    const now = deps.now ?? (() => Date.now());
+    const rpc = async (method, params) => {
+        const response = await proxyTenantMcp({
+            method: "POST",
+            authorization: deps.authorization,
+            body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+        }, deps.registry, 
+        // 商家实例是外部不可信端点：默认钉住已校验 IP（防 DNS 重绑定）。
+        deps.fetchImpl ?? createPinnedFetch());
+        let payload;
+        try {
+            payload = JSON.parse(response.body);
+        }
+        catch {
+            return { ok: false, message: "商家实例返回了无法解析的响应" };
+        }
+        if (response.status >= 400) {
+            const code = payload !== null &&
+                typeof payload === "object" &&
+                typeof payload.error === "string"
+                ? String(payload.error)
+                : `HTTP ${response.status}`;
+            return { ok: false, message: `商家实例暂不可用（${code}）` };
+        }
+        return { ok: true, payload };
+    };
+    return {
+        listTools: async (_scopes) => {
+            // 工具清单由实例现取，mcp-proxy 已按**令牌 scope** 过滤（与 tools/call
+            // 同一道门禁）并按工具名 allowlist 收敛；这里不再二次过滤，避免两处
+            // 规则漂移。缓存的是该令牌视角下的清单，TTL 60 秒。
+            const cached = cache.get(merchantId, now());
+            if (cached !== undefined)
+                return cached;
+            const result = await rpc("tools/list", {});
+            if (!result.ok)
+                return []; // 实例不可达：第 1 版工具不可见，第 0 版照常
+            const tools = parseToolList(result.payload);
+            if (tools.length > 0)
+                cache.set(merchantId, tools, now());
+            return tools;
+        },
+        call: async (name, args, _scopes) => {
+            const cached = cache.get(merchantId, now());
+            if (cached !== undefined && !cached.some((tool) => tool.name === name)) {
+                return fail(`商家实例未提供工具 ${name}（或当前授权不含所需 scope）`);
+            }
+            const result = await rpc("tools/call", { name, arguments: args });
+            if (!result.ok)
+                return fail(result.message);
+            return parseCallResult(result.payload);
+        },
+    };
+}
+//# sourceMappingURL=instance-tools.js.map

package/dist/merchant-gateway/instance-tools.js.map

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

package/dist/merchant-gateway/mcp-proxy.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 通用 Merchant MCP Gateway 的已认证请求分发层。
+ *
+ * 后端 URL 来自服务端 TenantBackendRegistry；模型参数无法更换租户。
+ * 这只是网关的一层，不负责 WorkBuddy OAuth 登录、服务托管或公网监听。
+ */
+import type { MerchantAuthorization } from "../auth/merchant-authorization.js";
+import { TenantBackendRegistry } from "./tenant-registry.js";
+export interface McpGatewayRequest {
+    method: "POST" | "GET";
+    body?: string;
+    accept?: string;
+    protocolVersion?: string;
+    authorization: MerchantAuthorization;
+}
+export interface McpGatewayResponse {
+    status: number;
+    contentType: string;
+    body: string;
+}
+/**
+ * 代理一个 MCP 请求。只支持 stateless JSON 响应；SSE/重定向 fail-closed。
+ * WorkBuddy 真实联调前须验证它与客户端的 Accept/transport 协商一致。
+ */
+export declare function proxyTenantMcp(request: McpGatewayRequest, registry: TenantBackendRegistry, fetchImpl?: typeof fetch): Promise<McpGatewayResponse>;

package/dist/merchant-gateway/mcp-proxy.js

@@ -0,0 +1,192 @@
+/**
+ * 通用 Merchant MCP Gateway 的已认证请求分发层。
+ *
+ * 后端 URL 来自服务端 TenantBackendRegistry；模型参数无法更换租户。
+ * 这只是网关的一层，不负责 WorkBuddy OAuth 登录、服务托管或公网监听。
+ */
+import { requiredScopeForTool } from "../mcp/merchant-tools.js";
+import { TenantBackendError, TenantBackendRegistry } from "./tenant-registry.js";
+const MAX_REQUEST_BYTES = 1_048_576;
+const MAX_RESPONSE_BYTES = 1_048_576;
+const ALLOWED_TOOLS = new Set([
+    "kiwi_merchant_list_products",
+    "kiwi_merchant_get_product",
+    "kiwi_merchant_get_inventory",
+    "kiwi_merchant_list_a2a_negotiations",
+    "kiwi_merchant_list_human_reviews",
+    "kiwi_merchant_get_analytics",
+    "kiwi_merchant_prepare_product_change",
+    "kiwi_merchant_prepare_product_create",
+    "kiwi_merchant_prepare_inventory_update",
+    "kiwi_merchant_prepare_listing_change",
+    "kiwi_merchant_prepare_review_resolve",
+    "kiwi_merchant_prepare_policy_change",
+    "kiwi_merchant_prepare_products_import",
+    "kiwi_merchant_prepare_products_withdraw",
+    "kiwi_merchant_get_operation",
+]);
+function json(status, body) {
+    return { status, contentType: "application/json", body: JSON.stringify(body) };
+}
+function scopeAllowed(authorization, scope) {
+    return authorization.scopes.includes(scope);
+}
+function gateRpc(body, authorization) {
+    let rpc;
+    try {
+        rpc = JSON.parse(body);
+    }
+    catch {
+        return json(400, { error: "invalid_json", message: "MCP JSON-RPC 请求无效" });
+    }
+    if (rpc === null || typeof rpc !== "object" || Array.isArray(rpc)) {
+        return json(400, { error: "invalid_request", message: "MCP JSON-RPC 请求无效" });
+    }
+    const request = rpc;
+    if (request.jsonrpc !== "2.0" || typeof request.method !== "string") {
+        return json(400, { error: "invalid_request", message: "MCP JSON-RPC 请求无效" });
+    }
+    const method = request.method;
+    if (["initialize", "notifications/initialized", "ping"].includes(method))
+        return undefined;
+    if (["tools/list", "resources/list", "resources/read"].includes(method)) {
+        if (!scopeAllowed(authorization, "merchant:read")) {
+            return json(403, { error: "insufficient_scope", required_scope: "merchant:read" });
+        }
+        if (method === "resources/read") {
+            const params = request.params;
+            if (typeof params?.uri !== "string" ||
+                !/^kiwi-merchant:\/\/presentation\/[a-z_]+$/.test(params.uri)) {
+                return json(403, { error: "resource_not_allowed" });
+            }
+        }
+        return undefined;
+    }
+    if (method === "tools/call") {
+        const params = request.params;
+        if (typeof params?.name !== "string" || !ALLOWED_TOOLS.has(params.name)) {
+            return json(403, { error: "tool_not_allowed" });
+        }
+        const required = requiredScopeForTool(params.name);
+        if (!scopeAllowed(authorization, required)) {
+            return json(403, { error: "insufficient_scope", required_scope: required });
+        }
+        return undefined;
+    }
+    return json(403, { error: "method_not_allowed" });
+}
+async function readBoundedResponse(response) {
+    if (response.body === null)
+        return "";
+    const reader = response.body.getReader();
+    const chunks = [];
+    let length = 0;
+    try {
+        while (true) {
+            const next = await reader.read();
+            if (next.done)
+                break;
+            length += next.value.byteLength;
+            if (length > MAX_RESPONSE_BYTES) {
+                await reader.cancel();
+                return undefined;
+            }
+            chunks.push(next.value);
+        }
+        return new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks));
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+/**
+ * 代理一个 MCP 请求。只支持 stateless JSON 响应；SSE/重定向 fail-closed。
+ * WorkBuddy 真实联调前须验证它与客户端的 Accept/transport 协商一致。
+ */
+export async function proxyTenantMcp(request, registry, fetchImpl = fetch) {
+    if (!request.authorization.merchant_id || !request.authorization.principal_id) {
+        return json(401, { error: "unauthorized" });
+    }
+    if (request.method !== "POST") {
+        return json(405, { error: "method_not_allowed" });
+    }
+    const body = request.body ?? "";
+    if (Buffer.byteLength(body, "utf8") > MAX_REQUEST_BYTES) {
+        return json(413, { error: "request_too_large" });
+    }
+    const gated = gateRpc(body, request.authorization);
+    if (gated !== undefined)
+        return gated;
+    // 只能在完成 OAuth 校验与 tool/scope gate 之后解析后端；不存在的商家没有
+    // 任何“缺省商家”回退。Backend secret 不进入返回结果或错误正文。
+    let backend;
+    try {
+        backend = registry.resolve(request.authorization);
+    }
+    catch (error) {
+        if (error instanceof TenantBackendError) {
+            return json(503, { error: error.code });
+        }
+        throw error;
+    }
+    let upstream;
+    try {
+        upstream = await fetchImpl(backend.mcpUrl, {
+            method: "POST",
+            redirect: "manual",
+            headers: {
+                authorization: `Bearer ${backend.bearerToken}`,
+                accept: "application/json, text/event-stream",
+                "content-type": "application/json",
+                ...(request.protocolVersion !== undefined
+                    ? { "mcp-protocol-version": request.protocolVersion }
+                    : {}),
+            },
+            body,
+            signal: AbortSignal.timeout(30_000),
+        });
+    }
+    catch (err) {
+        if (process.env.KIWI_GATEWAY_DEBUG_PROXY === "1") {
+            process.stderr.write(`[gateway proxy] backend fetch failed: ${err instanceof Error ? `${err.name}: ${err.message}` : String(err)}\n`);
+        }
+        return json(502, { error: "backend_unavailable" });
+    }
+    if (upstream.status >= 300 && upstream.status < 400) {
+        return json(502, { error: "backend_redirect_rejected" });
+    }
+    const contentType = upstream.headers.get("content-type") ?? "";
+    if (!/^application\/json(?:\s*;|\s*$)/i.test(contentType)) {
+        return json(502, { error: "backend_content_type_unsupported" });
+    }
+    const contentLength = Number(upstream.headers.get("content-length") ?? "0");
+    if (contentLength > MAX_RESPONSE_BYTES)
+        return json(502, { error: "backend_response_too_large" });
+    let responseBody;
+    try {
+        responseBody = await readBoundedResponse(upstream);
+    }
+    catch {
+        return json(502, { error: "backend_response_unreadable" });
+    }
+    if (responseBody === undefined) {
+        return json(502, { error: "backend_response_too_large" });
+    }
+    if (JSON.parse(body).method === "tools/list" && upstream.ok) {
+        let payload;
+        try {
+            payload = JSON.parse(responseBody);
+        }
+        catch {
+            return json(502, { error: "backend_invalid_json" });
+        }
+        if (Array.isArray(payload.result?.tools)) {
+            payload.result.tools = payload.result.tools.filter((tool) => typeof tool.name === "string" &&
+                ALLOWED_TOOLS.has(tool.name) &&
+                scopeAllowed(request.authorization, requiredScopeForTool(tool.name)));
+            return json(upstream.status, payload);
+        }
+    }
+    return { status: upstream.status, contentType: "application/json", body: responseBody };
+}
+//# sourceMappingURL=mcp-proxy.js.map

package/dist/merchant-gateway/mcp-proxy.js.map

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

package/dist/merchant-gateway/pinned-fetch.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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 declare class PinnedFetchError extends Error {
+    constructor(message: string);
+}
+/** 我们用到的那几个 fetch init 字段（避免依赖 DOM/undici 的类型名）。 */
+interface FetchInit {
+    method?: string;
+    headers?: unknown;
+    body?: unknown;
+    signal?: unknown;
+}
+export interface PinnedFetchOptions {
+    /** 自定义解析（测试用）；返回该主机名的全部 A/AAAA 记录。 */
+    resolveIp?: (hostname: string) => Promise<string[]>;
+    /** 请求超时（毫秒）；缺省由调用方通过 AbortSignal 控制。 */
+    timeoutMs?: number;
+}
+/**
+ * 解析 + 校验 + 选定一个可直连的 IP。
+ *
+ * 与 `assertResolvableTargetUrl` 同一套规则，但把「校验用的解析结果」原样
+ * 返回给调用方去建连，消除两次解析之间的窗口。
+ */
+export declare function resolvePinnedAddress(hostname: string, resolve: (hostname: string) => Promise<string[]>): Promise<string>;
+/**
+ * 按**给定地址**建连（钉住的落点），HTTP 适配层：
+ * `host: <address>` + `Host: <主机名>`（https 另加 servername 供 SNI/证书校验）。
+ * 单独导出便于对本地服务做往返测试（不经过 DNS 策略）。
+ */
+export declare function requestViaAddress(url: URL, address: string, init?: FetchInit): Promise<Response>;
+/**
+ * 构造一个把目标主机**钉在已校验 IP** 上的 fetch 实现。
+ *
+ * 语义与 fetch 的差异（故意为之）：不跟随重定向；响应体一次性读完（JSON-RPC
+ * 体量小）；不处理 cookie / 流式上传。
+ */
+export declare function createPinnedFetch(options?: PinnedFetchOptions): typeof fetch;
+export {};