@harrylabsj/kiwi 0.8.0 → 0.10.0

package/dist/merchant-gateway/credential-vault.js

@@ -0,0 +1,111 @@
+/**
+ * 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.
+ */
+/**
+ * 商家连接器入口的凭据保管（AES-256-GCM，密钥来自部署环境）。
+ *
+ * 入口在商家确认连接时兑换到**目录商家作用域凭据**（`cmt_…`），它需要长期
+ * 持有（入口重启后仍要代表该商家读写公开资料）。与既有做法一致，明文不落库：
+ * 这里用 `KIWI_GATEWAY_CREDENTIAL_KEY` 派生的 32 字节密钥做 AES-256-GCM
+ * 加密后存储，密钥缺失时 fail-closed（入口无法保管凭据 → 商家工具不可用，
+ * 而不是退回明文）。
+ *
+ * 存储位置：入口自己的 oauth.sqlite（0600），表 `gateway_merchant_credentials`。
+ * 每个商家一行（merchant_id 主键）；重新连接覆盖旧凭据。
+ */
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
+export const CREDENTIAL_KEY_ENV = "KIWI_GATEWAY_CREDENTIAL_KEY";
+const VAULT_SCHEMA = `
+CREATE TABLE IF NOT EXISTS gateway_merchant_credentials (
+  merchant_id TEXT PRIMARY KEY,
+  ciphertext TEXT NOT NULL,
+  expires_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+`;
+/** 从环境读取保管密钥；未配置返回 undefined（调用方据此 fail-closed）。 */
+export function credentialKeyFromEnv(env = process.env) {
+    const raw = (env[CREDENTIAL_KEY_ENV] ?? "").trim();
+    return raw === "" ? undefined : raw;
+}
+/** 任意长度的部署密钥 → 32 字节 AES 密钥（sha256 派生）。 */
+function deriveKey(secret) {
+    return createHash("sha256").update(secret).digest();
+}
+export class GatewayCredentialVault {
+    db;
+    key;
+    now;
+    constructor(options) {
+        if (typeof options.secret !== "string" || options.secret.trim() === "") {
+            throw new Error("GatewayCredentialVault requires a non-empty credential secret");
+        }
+        this.db = options.db;
+        this.key = deriveKey(options.secret);
+        this.now = options.now ?? (() => new Date().toISOString());
+        this.db.exec(VAULT_SCHEMA);
+    }
+    encrypt(plaintext) {
+        const iv = randomBytes(12);
+        const cipher = createCipheriv("aes-256-gcm", this.key, iv);
+        const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+        const tag = cipher.getAuthTag();
+        return Buffer.concat([iv, tag, ciphertext]).toString("base64");
+    }
+    decrypt(payload) {
+        const raw = Buffer.from(payload, "base64");
+        const iv = raw.subarray(0, 12);
+        const tag = raw.subarray(12, 28);
+        const ciphertext = raw.subarray(28);
+        const decipher = createDecipheriv("aes-256-gcm", this.key, iv);
+        decipher.setAuthTag(tag);
+        return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
+    }
+    put(merchantId, token, expiresAt) {
+        if (merchantId === "" || token === "") {
+            throw new Error("credential vault requires merchant_id and token");
+        }
+        this.db
+            .prepare(`INSERT INTO gateway_merchant_credentials(merchant_id, ciphertext, expires_at, updated_at)
+         VALUES (?, ?, ?, ?)
+         ON CONFLICT(merchant_id) DO UPDATE SET
+           ciphertext = excluded.ciphertext,
+           expires_at = excluded.expires_at,
+           updated_at = excluded.updated_at`)
+            .run(merchantId, this.encrypt(token), expiresAt, this.now());
+    }
+    get(merchantId) {
+        const row = this.db
+            .prepare("SELECT ciphertext, expires_at FROM gateway_merchant_credentials WHERE merchant_id = ?")
+            .get(merchantId);
+        if (row === undefined)
+            return undefined;
+        if (row.expires_at <= this.now())
+            return undefined;
+        try {
+            return { token: this.decrypt(row.ciphertext), expiresAt: row.expires_at };
+        }
+        catch {
+            // 密钥轮换/数据损坏：当作没有凭据（工具报「需要重新连接」），绝不返回噪音。
+            return undefined;
+        }
+    }
+    delete(merchantId) {
+        this.db
+            .prepare("DELETE FROM gateway_merchant_credentials WHERE merchant_id = ?")
+            .run(merchantId);
+    }
+}
+//# sourceMappingURL=credential-vault.js.map

package/dist/merchant-gateway/credential-vault.js.map

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

package/dist/merchant-gateway/entry-server.d.ts

@@ -0,0 +1,117 @@
+/**
+ * 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 type { MerchantAuthorization } from "../auth/merchant-authorization.js";
+import type { MerchantOAuthServer } from "../auth/merchant-oauth.js";
+import { type MerchantAdminSessions } from "../auth/merchant-sessions.js";
+import type { MerchantMcpAuthVerifier } from "../mcp/merchant-auth.js";
+import { type ScopedMcpTools } from "../mcp/merchant-server.js";
+import type { MerchantCredentialStore } from "./credential-vault.js";
+import { type InstanceRegistrationWriter, type ProbeResult } from "./instance-registration.js";
+export declare const DEFAULT_GATEWAY_ENTRY_PORT = 9200;
+export declare const DEFAULT_GATEWAY_ENTRY_PATH = "/mcp";
+/** catalog 连接能力（生产实现见 discovery/catalog-source/connector-identity.ts）。 */
+export interface GatewayIdentityProvider {
+    createRequest(input: {
+        returnUrl: string;
+        clientLabel?: string;
+    }): Promise<{
+        requestId: string;
+        loginUrl: string;
+        expiresAt: string;
+    }>;
+    exchange(input: {
+        requestId: string;
+        code: string;
+    }): Promise<{
+        merchantId: string;
+        merchantName: string;
+        credential: {
+            accessToken: string;
+            scope: string;
+            expiresAt: string;
+        };
+    }>;
+}
+export interface GatewayEntryServerOptions {
+    /** 入口对外地址（OAuth issuer；https，loopback 开发可为 http）。 */
+    publicBaseUrl: string;
+    oauth: MerchantOAuthServer;
+    sessions: MerchantAdminSessions;
+    identity: GatewayIdentityProvider;
+    /** 入口提供的工具束（V0 目录工具 / V1 商家工具）。 */
+    tools?: ScopedMcpTools;
+    /**
+     * 按已验证主体构造工具束（推荐）：商户隔离要求工具只能看到令牌绑定的
+     * merchant_id，而不是所有租户共用一份 bundler。
+     */
+    toolsFor?: (authorization: MerchantAuthorization | undefined) => ScopedMcpTools | undefined;
+    /** 商家目录凭据保管（连接成功时写入；工具按 merchant_id 取用）。 */
+    credentials?: MerchantCredentialStore;
+    /**
+     * 实例自助绑定（§8.4 第一期）：提供时挂载 `/instance` 页面（需商家会话）。
+     * 令牌只经该页面表单提交，**不进对话/模型上下文**；页面永不回显令牌。
+     */
+    instanceBinding?: {
+        registrations: InstanceRegistrationWriter;
+        credentials: MerchantCredentialStore;
+        /** 探活实现（缺省走真实网络）；测试可注入。 */
+        probe?: (mcpUrl: string, token: string) => Promise<ProbeResult>;
+        /** 配对码兑换替身（缺省走真实网络）；测试可注入。 */
+        redeem?: (mcpUrl: string, code: string) => Promise<{
+            credential: string;
+            ownerId: string;
+            principalId: string;
+            serverName: string;
+            serverVersion: string;
+        }>;
+    };
+    /** 入站 Bearer 校验器（OAuth access token → 主体 + scope）。 */
+    auth?: MerchantMcpAuthVerifier;
+    host?: string;
+    port?: number;
+    mcpPath?: string;
+    /** https 部署置 true（会话 cookie 加 Secure）。 */
+    secureCookies?: boolean;
+    /**
+     * 由本进程直接终止 TLS（生产可选形态之一）。缺省时进程不做 TLS：
+     * 只应监听 loopback，由受信反向代理终止 TLS（部署侧保证，见 CLI 校验）。
+     */
+    tls?: {
+        certPath: string;
+        keyPath: string;
+    };
+    serverInfo?: {
+        name: string;
+        version: string;
+    };
+    /** 商家连接器在目录确认页展示的来源名（缺省「Kiwi 商家运营」）。 */
+    clientLabel?: string;
+}
+export interface GatewayEntryServerHandle {
+    host: string;
+    port: number;
+    path: string;
+    url: string;
+    /** true = 本进程直接终止 TLS（否则应由受信反向代理终止）。 */
+    secure: boolean;
+    close: () => Promise<void>;
+}
+/** 只接受站内相对路径（拒绝协议相对 URL 与反斜杠变体，防开放重定向）。 */
+export declare function safeRelativePath(value: string | undefined): string | undefined;
+/**
+ * 启动商家连接器入口。返回 handle 含实际 host/port 与优雅关闭。
+ */
+export declare function startGatewayEntryServer(options: GatewayEntryServerOptions): Promise<GatewayEntryServerHandle>;