@harrylabsj/kiwi 0.8.0 → 0.9.0

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>;