@harrylabsj/kiwi-merchant-cloud 0.12.0 → 0.12.2

package/app/cloud/connect-service.d.ts

@@ -0,0 +1,153 @@
+/**
+ * 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 { AgentCard } from "../discovery/agent-card/types.js";
+import { type AuthorizedEnrollment } from "./binding/enrollment-challenge.js";
+export declare class MerchantConnectError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * 配对诊断固定安全码（A15）：reconcile 各阶段失败只允许透出本集合内的自有
+ * 稳定码——绝不反射远端错误原文/grant/device_code/JWS/头/私钥。工作台 API
+ * 白名单（CATALOG_CONNECTION_SAFE_CODES）以此单源扩展。
+ */
+export declare const CONNECTION_PAIRING_SAFE_CODES: Set<string>;
+/**
+ * 公网入口 host 白名单口径（CLI parsePublicOrigin 与服务构造器共用，
+ * 两边边界一致，谁也不放宽）：拒绝 localhost/私网 IP/链路本地域名/无点主机。
+ * 只判 host；协议与路径形态由各自调用点另行校验。
+ */
+export declare function isPublicHostAllowed(hostname: string): boolean;
+/** 连接会话（merchant-enrollments.json 中单条 session 的完整形状）。 */
+export interface ConnectionSession extends AuthorizedEnrollment {
+    catalog_origin: string;
+    preview_digest: string;
+    frozen_card: AgentCard;
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    interval: number;
+    generation?: number;
+    catalog_agent_id?: string;
+    expected_catalog_agent_id?: string;
+    /** 仅由验真 binding claim 写入；authorized 轮询结果不写入本字段。 */
+    merchant_id?: string;
+    grant?: string;
+    authorization_epoch?: number;
+    /**
+     * authorized 轮询里的 merchant_id 断言（**未验真**）：仅供 bind 请求的
+     * 入参一致性校验，CatalogClient 会核对签名 claim 与它一致；商品盖戳等
+     * 任何权威用途都只认 claim 写入的 merchant_id。
+     */
+    offered_merchant_id?: string;
+    binding_id?: string;
+    binding_version?: number;
+    /** claim 里的 expires_at（已验证）：**首签声明的短期 TTL**（Catalog 每次
+     * 公开读会重签新声明）；bound 未发布时作有效期门槛，published 的续验以
+     * Catalog 当次重签的公开声明为准，不用它判死。 */
+    binding_expires_at?: string;
+    active_card_revision?: number;
+    expected_card_revision?: number;
+    card_revision?: number;
+}
+/**
+ * 纯 resume 选择：只有同 origin + 同公钥指纹 + 可续状态 + 未过期才复用。
+ * （自 merchant-connect.ts 原样搬移，行为被 tests/merchant-connect-migration.test.ts 钉住。）
+ *
+ * 过期口径按状态区分：preparing/authorized 看授权窗口 expires_at；
+ * **bound/published 看已验真绑定的 binding_expires_at**——绑定已建立后
+ * 授权 grant 过期不影响续办（用户无需重新授权），反过来绑定过期必须拒绝。
+ */
+export declare function selectReusableEnrollment(sessions: readonly AuthorizedEnrollment[], input: {
+    runtimeOrigin: string;
+    keyThumbprint: string;
+    nowMs: number;
+}): AuthorizedEnrollment | undefined;
+/** Keep the Catalog account's single-agent identity through key loss and address migration. */
+export declare function priorPublishedCatalogAgentId(sessions: readonly AuthorizedEnrollment[]): string | undefined;
+/** 助手/工作台安全摘要：永不含 user_code/device_code/grant/授权链接。 */
+export type ConnectionSummaryStatus = "idle" | "awaiting_confirmation" | "authorized" | "bound" | "published" | "replaced" | "revoked" | "paused" | "expired" | "canceled" | "unknown" | "error";
+export type ConnectionStage = "prepare" | "authorize" | "publish";
+export interface ConnectionSummary {
+    status: ConnectionSummaryStatus;
+    /** 自有固定阶段词（A15）：preparing→prepare，authorized→authorize，bound/published→publish。 */
+    stage: ConnectionStage;
+    published: boolean;
+    agentId: string | null;
+    bindingId: string | null;
+    bindingExpiresAt: string | null;
+    cardRevision: number | null;
+    /** 可用性/安全错误码（如 PUBLICATION_NOT_ACTIVE）；健康为 null。 */
+    code: string | null;
+    detail: string | null;
+}
+/** 仅商家本人可见的配对信息；只在 preparing/awaiting 阶段存在。 */
+export interface ConnectionPairing {
+    userCode: string;
+    verificationUri: string;
+    expiresAt: string;
+}
+/**
+ * 已验证绑定投影：merchantId 只来自 CatalogClient 验真的 binding claim
+ * （或 published 会话经公开绑定复核一致的结果）。
+ */
+export interface VerifiedBinding {
+    agentId: string;
+    bindingId: string;
+    bindingVersion: number;
+    merchantId: string;
+    keyThumbprint: string;
+    runtimeOrigin: string;
+    a2aEndpoint: string;
+    expiresAt: string;
+    cardRevision: number | null;
+}
+export interface MerchantConnectionServiceOptions {
+    /** 权威状态目录（merchant-enrollments.json 所在）。 */
+    dataDir: string;
+    /** Catalog 控制面根 URL（https；loopback 仅测试）。 */
+    catalogUrl: string;
+    /** 运行时公开 origin（只取自 KIWI_CLOUD_PUBLIC_ORIGIN 或 CLI 已校验值）。 */
+    publicOrigin: string;
+    /** 部署代次（当前 1）；会话按此选择，拒绝悄悄迁移。 */
+    generation?: number;
+    serviceEpoch?: number;
+    fetchImpl?: typeof fetch;
+    now?: () => Date;
+    /**
+     * 公开名片提供者（缺省：匿名读自身 origin 的 well-known 卡并核对签名声明，
+     * 与 CLI 的 verifyPublicRuntimeReady 同口径）。云端可注入本地构建的同名卡。
+     */
+    loadPublicCard?: () => Promise<AgentCard>;
+    /** 绑定验真后、发名片前调用；失败保留 bound、不发布。 */
+    beforePublish?: (binding: VerifiedBinding) => Promise<void>;
+    /** 仅测试/本地回环：放宽公网 host 白名单（默认绝不放宽 CLI 的私网边界）。 */
+    allowPrivateOrigin?: boolean;
+}
+export interface MerchantConnectionService {
+    /** 唯一允许创建 enrollment 的入口；同 origin/key/catalog/冻结卡幂等复用。 */
+    begin(): Promise<ConnectionSummary>;
+    /** 单趟短执行：至多一次 poll + 已就绪格级联；后台调用绝不创建新会话。 */
+    reconcile(): Promise<ConnectionSummary>;
+    /** 本地状态摘要（便宜、不触发 Catalog 写）；可用性码来自最近一次 reconcile。 */
+    getSummary(): Promise<ConnectionSummary>;
+    /** 本人配对信息（preparing 阶段）；无会话或已过该阶段返回 null。 */
+    getPairing(): ConnectionPairing | null;
+    /** 已验证绑定（bound/published 且未过期；published 另经 Catalog 复核）；无则 null。 */
+    getVerifiedBinding(): Promise<VerifiedBinding | null>;
+}
+/** 构造连接服务（幂等工厂；同一 dataDir 可由 CLI 与服务实例先后使用）。 */
+export declare function createMerchantConnectionService(options: MerchantConnectionServiceOptions): MerchantConnectionService;