@harrylabsj/kiwi-merchant-cloud 0.12.0 → 0.12.1

package/app/cloud/connect-service.js

@@ -0,0 +1,776 @@
+/**
+ * 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.
+ */
+/**
+ * Catalog 连接服务内核（A2 直连 device enrollment）。
+ *
+ * 把 `merchant-connect.ts` 里既有的签名 device enrollment 协议
+ * （create → poll → bind → publish → activate，CatalogClient 承载）抽成
+ * 可供工作台/云端 bootstrap 调用的服务，CLI 变为本服务之上的薄适配。
+ * **协议步骤只有这一套**——本文件是从 CLI 实现原样搬移的状态机，不是重写。
+ *
+ * 与 CLI 的差异只在"驱动方式"：
+ *
+ * - `begin()` 是**唯一**允许创建 enrollment 的入口（幂等：同 origin/公钥/
+ *   Catalog/冻结卡直接复用），且永远不会被 GET 触发；
+ * - `reconcile()` 是单趟短执行（至多一次 poll，随后级联 authorized→bound→
+ *   published 中已就绪的格），尊重 interval/slow_down 节流，不创建新会话、
+ *   不轮询已过期授权、**不输出配对码/授权链接/grant**；
+ * - 状态经 `getSummary()`（助手安全层：状态枚举/published/agentId/bindingId/
+ *   bindingExpiresAt/可用性错误码，永无 user_code/device_code/grant）与
+ *   `getPairing()`（仅商家本人层：user_code/verification_uri/expires_at）分层外露；
+ * - `options.beforePublish(binding)` 钩子在**绑定回执经 Catalog 验签之后、
+ *   发名片之前**调用（cloud bootstrap 用它拿已验证 merchantId 盖戳商品表并跑
+ *   真实 readiness）；钩子失败保留 bound，不发布。
+ *
+ * 身份纪律（全部沿用 CLI 既有校验，不新增信任根）：
+ *
+ * - 首次 Catalog 服务端回执里的 `catalog_agent_id` 是权威身份；只与"历史已
+ *   发布身份"（expected_catalog_agent_id）做迁移约束，**不与本地 cagt_* 假定比较**；
+ * - `merchantId` 只能来自 CatalogClient 验真的 binding claim（bind 时写入并
+ *   持久化 binding_expires_at 等已验证声明以便重启），authorized 轮询结果
+ *   **绝不**足以盖戳商品；
+ * - 代次固定为配置值（当前 1），会话按 generation 选择，拒绝悄悄迁移；
+ *   绝不把 applicationId 字符串当权威证据（本服务根本不经过开通向导）。
+ *
+ * 持久化仍是 0600 `merchant-enrollments.json` 原子写；任何失败路径只改
+ * 目标会话的格，不删除其他会话。
+ */
+import { createHash } from "node:crypto";
+import { isIP } from "node:net";
+import { loadOrCreateA2aSigningIdentity, toJwsSigningIdentity } from "../a2a/signing-key.js";
+import { writeFileAtomic } from "../fs/atomic-write.js";
+import { canonicalize } from "../negotiation/jcs.js";
+import { validateAgentCard } from "../discovery/agent-card/validate.js";
+import { isRedirectResponse, readJsonBody } from "../net/safe-http.js";
+import { CatalogClient, normalizeOrigin, runtimePublicKey, } from "./catalog-client.js";
+import { enrollmentStorePath, readEnrollmentStore, } from "./binding/enrollment-challenge.js";
+export class MerchantConnectError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "MerchantConnectError";
+    }
+}
+/**
+ * 公网入口 host 白名单口径（CLI parsePublicOrigin 与服务构造器共用，
+ * 两边边界一致，谁也不放宽）：拒绝 localhost/私网 IP/链路本地域名/无点主机。
+ * 只判 host；协议与路径形态由各自调用点另行校验。
+ */
+export function isPublicHostAllowed(hostname) {
+    const host = hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    const ip = isIP(host);
+    const octets = ip === 4 ? host.split(".").map(Number) : [];
+    const privateIpv4 = ip === 4 && (octets[0] === 0 || octets[0] === 10 || octets[0] === 127 || octets[0] === 169 && octets[1] === 254 ||
+        octets[0] === 192 && octets[1] === 168 || octets[0] === 172 && (octets[1] ?? 0) >= 16 && (octets[1] ?? 0) <= 31 ||
+        octets[0] === 100 && (octets[1] ?? 0) >= 64 && (octets[1] ?? 0) <= 127 || (octets[0] ?? 0) >= 224);
+    const privateIpv6 = ip === 6 && (host === "::" || host === "::1" || host.startsWith("fc") ||
+        host.startsWith("fd") || host.startsWith("fe80:") || host.startsWith("::ffff:"));
+    return host !== "localhost" && !host.endsWith(".localhost") &&
+        !host.endsWith(".local") && !host.endsWith(".internal") && !host.endsWith(".lan") && !host.endsWith(".home") &&
+        host.includes(".") && !privateIpv4 && !privateIpv6;
+}
+/**
+ * 纯 resume 选择：只有同 origin + 同公钥指纹 + 可续状态 + 未过期才复用。
+ * （自 merchant-connect.ts 原样搬移，行为被 tests/merchant-connect-migration.test.ts 钉住。）
+ *
+ * 过期口径按状态区分：preparing/authorized 看授权窗口 expires_at；
+ * **bound/published 看已验真绑定的 binding_expires_at**——绑定已建立后
+ * 授权 grant 过期不影响续办（用户无需重新授权），反过来绑定过期必须拒绝。
+ */
+export function selectReusableEnrollment(sessions, input) {
+    return sessions.find((session) => {
+        const state = session;
+        if (state.runtime_origin !== input.runtimeOrigin || state.key_thumbprint !== input.keyThumbprint)
+            return false;
+        if (!["preparing", "authorized", "bound", "published"].includes(state.status))
+            return false;
+        if (state.status === "published")
+            return true;
+        const expiry = state.status === "bound" ? state.binding_expires_at : state.expires_at;
+        return Number.isFinite(Date.parse(expiry ?? "")) && Date.parse(expiry ?? "") > input.nowMs;
+    });
+}
+/** Keep the Catalog account's single-agent identity through key loss and address migration. */
+export function priorPublishedCatalogAgentId(sessions) {
+    const ids = new Set(sessions
+        .map((session) => session)
+        .filter((session) => session.status === "published" && typeof session.catalog_agent_id === "string")
+        .map((session) => session.catalog_agent_id));
+    if (ids.size > 1)
+        throw new MerchantConnectError("AMBIGUOUS_MIGRATION", "本Runtime已有多个Catalog Agent历史绑定；请在Catalog先确认要迁移的商家身份。");
+    return ids.values().next().value;
+}
+function cardDigest(card) {
+    return `sha256:${createHash("sha256").update(canonicalize(card), "utf8").digest("hex")}`;
+}
+/** 缺省公开卡加载：与 CLI verifyPublicRuntimeReady 同口径（匿名读 + 签名声明核对）。 */
+async function fetchPublicCard(origin, expectedEndpoint, identity, fetchImpl) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 8_000);
+    const url = `${origin}/.well-known/agent-card.json`;
+    try {
+        const response = await fetchImpl(url, { method: "GET", redirect: "manual", signal: controller.signal, headers: { accept: "application/json" } });
+        if (isRedirectResponse(response) || !response.ok) {
+            throw new MerchantConnectError("RUNTIME_UNREACHABLE", `暂时无法从外部读取商家服务的 Agent Card（HTTP ${response.status}）。请确认服务已启动且公网入口可访问，然后重新运行 kiwi merchant connect。`);
+        }
+        const card = validateAgentCard(await readJsonBody(response, { signal: controller.signal }));
+        const urls = card.supportedInterfaces.map((entry) => entry.url);
+        if (typeof card.url !== "string" || new URL(card.url).origin !== origin || !urls.includes(expectedEndpoint)) {
+            throw new MerchantConnectError("RUNTIME_NOT_READY", "公网入口返回的 Agent Card 与当前 Runtime 地址不一致；未发布名片。请检查反向代理与服务配置后重试。");
+        }
+        const signatureScheme = card.securitySchemes?.["kiwi-signature"];
+        if (signatureScheme !== undefined && (signatureScheme.type !== "kiwi-http-message-signature" ||
+            signatureScheme.keyid !== identity.keyid ||
+            signatureScheme.publicKeyPem !== identity.publicKeyPem ||
+            signatureScheme.algorithm !== "ed25519")) {
+            throw new MerchantConnectError("RUNTIME_IDENTITY_MISMATCH", "公网服务的 A2A 签名声明与当前 Runtime 持久密钥不一致；未发布名片。请在实际承接请求的 Runtime 主机上运行连接命令。");
+        }
+        return card;
+    }
+    catch (err) {
+        if (err instanceof MerchantConnectError)
+            throw err;
+        throw new MerchantConnectError("RUNTIME_UNREACHABLE", `暂时无法从外部连接你的商家服务（${err instanceof Error ? err.message : String(err)}）。请确认服务已启动、TLS 证书有效且允许公网访问，然后重试。`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+class ConnectionServiceImpl {
+    dataDir;
+    origin;
+    a2aEndpoint;
+    generation;
+    serviceEpoch;
+    client;
+    identityRaw;
+    identity;
+    keyThumbprint;
+    now;
+    loadPublicCard;
+    beforePublish;
+    /** begin/reconcile 串行（排队不交错）。 */
+    mutex = Promise.resolve();
+    /** poll 节流（内存态；重启后首趟允许立即 poll）。 */
+    nextPollAtMs = 0;
+    /**
+     * published 会话的"本次已验证"结论（fail-closed，getSummary 只读它）：
+     * publicationVerified=false 表示本实例还没从 Catalog 核对过当前绑定/名片，
+     * 此时绝不允许把本地历史 published 记录当当前发布回执；
+     * availability 非 null 表示核对给出否定/出错结论（撤回、网络不可达等）。
+     */
+    publicationVerified = false;
+    availability = null;
+    constructor(options) {
+        this.dataDir = options.dataDir;
+        this.generation = options.generation ?? 1;
+        this.serviceEpoch = options.serviceEpoch ?? 1;
+        const trimmed = String(options.publicOrigin ?? "").trim().replace(/\/+$/, "");
+        let parsed;
+        try {
+            parsed = new URL(trimmed);
+        }
+        catch {
+            throw new MerchantConnectError("PUBLIC_ORIGIN_INVALID", "公网入口不是合法 URL；请设置 KIWI_A2A_PUBLIC_URL=https://你的域名");
+        }
+        if (parsed.protocol !== "https:" || parsed.username !== "" || parsed.password !== "" ||
+            parsed.search !== "" || parsed.hash !== "" || (parsed.pathname !== "/" && parsed.pathname !== "")) {
+            throw new MerchantConnectError("PUBLIC_ORIGIN_INVALID", "公网入口不是合法 URL；请设置 KIWI_A2A_PUBLIC_URL=https://你的域名");
+        }
+        // 与 CLI parsePublicOrigin 同一白名单口径：生产构造必须提供公网可达 host；
+        // 只有显式 allowPrivateOrigin（测试/本地回环）才放宽。
+        if (options.allowPrivateOrigin !== true && !isPublicHostAllowed(parsed.hostname)) {
+            throw new MerchantConnectError("PUBLIC_ORIGIN_INVALID", "商家服务尚未配置可用的公网 HTTPS origin。请运行 `kiwi merchant setup-public` 查看入口配置指引；资料已保留，配置后重新运行连接命令。");
+        }
+        this.origin = normalizeOrigin(trimmed);
+        this.a2aEndpoint = `${this.origin}/a2a`;
+        this.client = new CatalogClient({ baseUrl: options.catalogUrl, ...(options.fetchImpl !== undefined ? { fetchImpl: options.fetchImpl } : {}) });
+        this.identityRaw = loadOrCreateA2aSigningIdentity(this.dataDir, this.origin);
+        this.identity = { signingIdentity: toJwsSigningIdentity(this.identityRaw), keyId: this.identityRaw.keyid };
+        this.keyThumbprint = runtimePublicKey(this.identity).keyThumbprint;
+        this.now = options.now ?? (() => new Date());
+        const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+        this.loadPublicCard = options.loadPublicCard ??
+            (async () => await fetchPublicCard(this.origin, this.a2aEndpoint, {
+                keyid: this.identityRaw.keyid,
+                publicKeyPem: this.identityRaw.publicKeyPem,
+            }, fetchImpl));
+        this.beforePublish = options.beforePublish;
+    }
+    // ── 公开接口 ─────────────────────────────────────────────────────────
+    async begin() {
+        return await this.withLock(async () => {
+            const card = await this.loadPublicCard();
+            const currentDigest = cardDigest(card);
+            const store = readEnrollmentStore(this.dataDir);
+            const session = this.selectSession(store);
+            const catalogOrigin = this.client.catalogOrigin;
+            if (session !== undefined) {
+                if (session.catalog_origin !== catalogOrigin) {
+                    throw new MerchantConnectError("CATALOG_MISMATCH", "待续办的接入任务属于另一个 Catalog；为防止许可串用，已停止。");
+                }
+                const frozenDigest = cardDigest(session.frozen_card);
+                if (typeof session.preview_digest !== "string" || frozenDigest !== session.preview_digest) {
+                    throw new MerchantConnectError("STATE_INVALID", "持久接入任务缺少冻结的公开名片，已停止。");
+                }
+                if (currentDigest !== session.preview_digest) {
+                    throw new MerchantConnectError(session.status === "published" ? "RUNTIME_CARD_CHANGED" : "PREVIEW_CHANGED", "公网服务当前的 Agent Card 与已批准预览不同；请核对变更并重新授权，Runtime不会静默更改已公开信息。");
+                }
+                if (session.status === "published") {
+                    try {
+                        await this.assertPublicationActive(session);
+                    }
+                    catch (err) {
+                        // 撤回/暂停如实留痕（summary fail-closed 为未发布）并继续向上抛；
+                        // begin 是显式动作，保持与旧 CLI 一致的抛错语义。
+                        this.publicationVerified = false;
+                        this.availability = err instanceof MerchantConnectError
+                            ? { code: err.code, detail: err.message }
+                            : { code: "PUBLICATION_CHECK_FAILED", detail: String(err) };
+                        throw err;
+                    }
+                    this.publicationVerified = true;
+                    this.availability = null;
+                    const fresh = this.selectSession(readEnrollmentStore(this.dataDir));
+                    return this.toSummary(fresh ?? session);
+                }
+                return this.toSummary(session);
+            }
+            // 无可用会话：只有这里允许创建 enrollment。但若同 origin+key 还存在
+            // **其他 Catalog** 的活会话，说明配置指向变了——明确拒绝而不是 silently
+            // 在新 Catalog 重建（防止许可串用/悄悄迁移）。
+            const foreign = this.findForeignCatalogSession(store);
+            if (foreign !== undefined) {
+                throw new MerchantConnectError("CATALOG_MISMATCH", "待续办的接入任务属于另一个 Catalog；为防止许可串用，已停止。");
+            }
+            const expectedCatalogAgentId = priorPublishedCatalogAgentId(store.sessions);
+            const enrollment = await this.client.createDeviceEnrollment({
+                runtimeOrigin: this.origin,
+                a2aEndpoint: this.a2aEndpoint,
+                generation: this.generation,
+                serviceEpoch: this.serviceEpoch,
+                publicPreview: card,
+                publicProfileRevision: 1,
+            }, this.identity);
+            const next = {
+                enrollment_id: enrollment.enrollmentId,
+                runtime_origin: this.origin,
+                key_thumbprint: this.keyThumbprint,
+                catalog_origin: catalogOrigin,
+                preview_digest: currentDigest,
+                frozen_card: card,
+                generation: this.generation,
+                ...(expectedCatalogAgentId !== undefined ? { expected_catalog_agent_id: expectedCatalogAgentId } : {}),
+                expires_at: enrollment.expiresAt,
+                status: "preparing",
+                device_code: enrollment.deviceCode,
+                user_code: enrollment.userCode,
+                verification_uri: enrollment.verificationUri,
+                interval: enrollment.intervalSeconds,
+            };
+            // 同 origin+key 的旧 preparing 会话被本任务取代（标 canceled 留痕），
+            // 其余会话（含其他 origin/key、bound/published 历史）一律保留。
+            this.persist((fresh) => [
+                ...fresh.sessions.map((item) => {
+                    const old = item;
+                    return old.enrollment_id !== next.enrollment_id &&
+                        old.runtime_origin === this.origin && old.key_thumbprint === this.keyThumbprint &&
+                        old.status === "preparing"
+                        ? { ...old, status: "canceled" }
+                        : item;
+                }),
+                next,
+            ]);
+            this.nextPollAtMs = 0;
+            this.publicationVerified = false;
+            this.availability = null;
+            return this.toSummary(next);
+        });
+    }
+    async reconcile() {
+        return await this.withLock(async () => {
+            const store = readEnrollmentStore(this.dataDir);
+            const session = this.selectSession(store);
+            if (session === undefined) {
+                // 过期授权显式标记：不再轮询，下一次 begin() 为同 origin+key 新建。
+                const stale = this.findStaleSession(store);
+                if (stale !== undefined) {
+                    const expired = { ...stale, status: "expired" };
+                    this.persist((fresh) => fresh.sessions.map((item) => item.enrollment_id === stale.enrollment_id ? expired : item));
+                    return this.toSummary(expired);
+                }
+                return this.toSummary(null);
+            }
+            // 单趟级联：preparing →（poll）authorized →（bind）bound →（钩子+publish）
+            // published，每格已就绪就顺势走完；poll 节流保证至多一次出站 poll。
+            let current = session;
+            if (current.status === "preparing")
+                current = await this.stepPreparing(current);
+            if (current.status === "authorized")
+                current = await this.stepAuthorized(current);
+            if (current.status === "bound")
+                current = await this.stepBound(current);
+            if (current.status === "published") {
+                try {
+                    await this.assertPublicationActive(current);
+                }
+                catch (err) {
+                    // 撤回/暂停/网络不可达一律 fail-closed：summary 报未发布（paused/error），
+                    // 绝不自动恢复营业、不发任何写请求；下趟 reconcile 会重新核对。
+                    this.publicationVerified = false;
+                    this.availability = err instanceof MerchantConnectError
+                        ? { code: err.code, detail: err.message }
+                        : { code: "PUBLICATION_CHECK_FAILED", detail: String(err) };
+                    return this.toSummary(current);
+                }
+                this.publicationVerified = true;
+                this.availability = null;
+            }
+            return this.toSummary(current);
+        });
+    }
+    async getSummary() {
+        const store = readEnrollmentStore(this.dataDir);
+        const session = this.selectSession(store);
+        if (session !== undefined)
+            return this.toSummary(session);
+        const stale = this.findStaleSession(store);
+        return this.toSummary(stale === undefined ? null : { ...stale, status: "expired" });
+    }
+    getPairing() {
+        const store = readEnrollmentStore(this.dataDir);
+        const session = this.selectSession(store);
+        if (session === undefined || session.status !== "preparing")
+            return null;
+        return {
+            userCode: session.user_code,
+            verificationUri: session.verification_uri,
+            expiresAt: session.expires_at,
+        };
+    }
+    /**
+     * 已验证绑定投影（bound 与 published 两条口径）：
+     *
+     * - **bound（尚未公开发布）**：只认 bind 时验真并持久化的签名 claim，
+     *   且该 claim 未过期——绝不无条件延长旧凭据；
+     * - **published**：先从 Catalog 公开端点读取**当次重签**的绑定声明
+     *   （Catalog 每次公开读都会重新签发 expires_at=now+ttl≤900s 的短期声明，
+     *   本地 binding_expires_at 只是首签 TTL、不是长期绑定的终点），逐字段核对
+     *   merchant/origin/key/binding id/version/card revision 后，用新鲜声明的
+     *   期限刷新投影。历史 claim 过期绝不阻断只读续验，也不触发重建 enrollment。
+     */
+    async getVerifiedBinding() {
+        const store = readEnrollmentStore(this.dataDir);
+        const session = this.selectSession(store);
+        if (session === undefined)
+            return null;
+        if (session.status === "bound") {
+            // 未发布：必须用本地已验证且未过期的签名 claim。
+            return this.verifiedFromSession(session);
+        }
+        if (session.status !== "published")
+            return null;
+        try {
+            const active = await this.assertPublicationActive(session);
+            this.markPublishedVerified();
+            return this.verifiedFromPublication(session, active);
+        }
+        catch (err) {
+            this.publicationVerified = false;
+            this.availability = err instanceof MerchantConnectError
+                ? { code: err.code, detail: err.message }
+                : { code: "PUBLICATION_CHECK_FAILED", detail: "Catalog publication could not be verified" };
+            return null;
+        }
+    }
+    // ── 协议单步（自 CLI 状态机原样搬移，顺序与校验一致）──────────────────
+    /** begin/reconcile 后本趟已确认 published 健康（发布成功即视为已验证）。 */
+    markPublishedVerified() {
+        this.publicationVerified = true;
+        this.availability = null;
+    }
+    async stepPreparing(session) {
+        const nowMs = this.now().getTime();
+        if (!Number.isFinite(Date.parse(session.expires_at)) || Date.parse(session.expires_at) <= nowMs) {
+            // 授权已过期：不再轮询，显式标记；下一次 begin() 会为同 origin+key 新建。
+            const expired = { ...session, status: "expired" };
+            this.persist((fresh) => fresh.sessions.map((item) => item.enrollment_id === session.enrollment_id ? expired : item));
+            return expired;
+        }
+        if (nowMs < this.nextPollAtMs)
+            return session;
+        const poll = await this.client.pollDeviceEnrollment(session.device_code, this.identity);
+        if (poll.status !== "authorized") {
+            const intervalMs = poll.status === "slow_down"
+                ? Math.max(session.interval * 1000 + 5_000, poll.intervalSeconds * 1000)
+                : Math.max(session.interval, poll.intervalSeconds) * 1000;
+            this.nextPollAtMs = nowMs + intervalMs;
+            const updated = { ...session, interval: Math.round(intervalMs / 1000) };
+            this.persist((fresh) => fresh.sessions.map((item) => item.enrollment_id === session.enrollment_id ? updated : item));
+            return updated;
+        }
+        this.verifyAuthorizedPoll(session, poll);
+        const authorized = {
+            ...session,
+            status: "authorized",
+            catalog_agent_id: poll.catalogAgentId,
+            grant: poll.grant,
+            authorization_epoch: poll.authorizationEpoch,
+            expires_at: poll.expiresAt,
+            // poll.merchantId 是未验真断言，只存 offered_merchant_id 供 bind 入参
+            // 一致性校验（CatalogClient 会核对签名 claim 与它一致）；
+            // 权威的 merchant_id 只在 bind 阶段由 Catalog 签名 claim 写入。
+            offered_merchant_id: poll.merchantId,
+        };
+        this.persist((fresh) => fresh.sessions.map((item) => item.enrollment_id === session.enrollment_id ? authorized : item));
+        return authorized;
+    }
+    verifyAuthorizedPoll(session, poll) {
+        if (poll.enrollmentId !== session.enrollment_id || poll.runtimeOrigin !== this.origin || poll.a2aEndpoint !== this.a2aEndpoint ||
+            poll.merchantId.trim() === "" ||
+            session.expected_catalog_agent_id !== undefined && poll.catalogAgentId !== session.expected_catalog_agent_id) {
+            throw new MerchantConnectError("AUTHORIZED_MATERIAL_MISMATCH", "Catalog 授权材料与当前 Runtime 不一致，已停止连接。");
+        }
+        if (poll.authorizationEpoch < 1 || poll.approvedCardDigest !== session.preview_digest ||
+            !poll.scopes.includes("runtime:bind") || !poll.scopes.includes("card:publish") ||
+            !poll.scopes.includes("heartbeat")) {
+            throw new MerchantConnectError("GRANT_SCOPE_INVALID", "Catalog 接入许可缺少有效授权代次或必要范围，已停止。");
+        }
+    }
+    async stepAuthorized(session) {
+        // 兼容旧 CLI 写入的会话（当时 merchant_id 存的是 poll 断言）：优先
+        // offered_merchant_id，缺失时回落旧字段，语义相同（都只是 bind 入参）。
+        const offeredMerchantId = session.offered_merchant_id ?? session.merchant_id;
+        if (session.catalog_agent_id === undefined || session.grant === undefined ||
+            session.authorization_epoch === undefined || offeredMerchantId === undefined) {
+            throw new MerchantConnectError("STATE_INVALID", "本地授权状态缺少许可、授权代次、merchant_id或 catalog_agent_id");
+        }
+        const binding = await this.client.bindEnrollment({
+            enrollmentId: session.enrollment_id,
+            grant: session.grant,
+            catalogAgentId: session.catalog_agent_id,
+            merchantId: offeredMerchantId,
+            runtimeOrigin: this.origin,
+            a2aEndpoint: this.a2aEndpoint,
+            generation: session.generation ?? this.generation,
+            serviceEpoch: this.serviceEpoch,
+            authorizationEpoch: session.authorization_epoch,
+        }, this.identity);
+        if (binding.keyThumbprint !== this.keyThumbprint) {
+            throw new MerchantConnectError("BINDING_KEY_MISMATCH", "Catalog 绑定回执的密钥与本 Runtime 不一致");
+        }
+        const rawClaims = binding.bindingClaim["claims"];
+        const claimMerchantId = rawClaims !== null && typeof rawClaims === "object" && !Array.isArray(rawClaims)
+            ? rawClaims["merchant_id"]
+            : undefined;
+        const claimExpiry = rawClaims !== null && typeof rawClaims === "object" && !Array.isArray(rawClaims)
+            ? rawClaims["expires_at"]
+            : undefined;
+        if (typeof claimMerchantId !== "string" || claimMerchantId.trim() === "") {
+            throw new MerchantConnectError("BINDING_CLAIM_INVALID", "Catalog已签名绑定声明缺少merchant_id；名片保持未发布。");
+        }
+        if (typeof claimExpiry !== "string" || !Number.isFinite(Date.parse(claimExpiry))) {
+            throw new MerchantConnectError("BINDING_CLAIM_INVALID", "Catalog已签名绑定声明缺少有效expires_at；名片保持未发布。");
+        }
+        const bound = {
+            ...session,
+            status: "bound",
+            binding_id: binding.bindingId,
+            binding_version: binding.bindingVersion,
+            merchant_id: claimMerchantId,
+            binding_expires_at: claimExpiry,
+            expected_card_revision: binding.activeCardRevision ?? 0,
+        };
+        this.persist((fresh) => fresh.sessions.map((item) => item.enrollment_id === session.enrollment_id ? bound : item));
+        // 级联：同一趟继续走 bound 格（发名片前仍要复核公开卡 + beforePublish 钩子）。
+        return await this.stepBound(bound);
+    }
+    async stepBound(session) {
+        if (session.catalog_agent_id === undefined || session.binding_id === undefined ||
+            session.binding_version === undefined || session.merchant_id === undefined ||
+            session.binding_expires_at === undefined) {
+            throw new MerchantConnectError("STATE_INVALID", "绑定状态缺少回执字段");
+        }
+        // 重启续办/长等待后重新验证：绑定授权已过期的绝不允许带过期绑定调
+        // beforePublish 钩子或发布名片；显式标记 expired，下一次 begin() 重开。
+        if (!Number.isFinite(Date.parse(session.binding_expires_at)) || Date.parse(session.binding_expires_at) <= this.now().getTime()) {
+            const expired = { ...session, status: "expired" };
+            this.persist((fresh) => fresh.sessions.map((item) => item.enrollment_id === session.enrollment_id ? expired : item));
+            return expired;
+        }
+        // 重启续办/长等待后重新验证：公开卡必须与冻结预览一致才允许发布。
+        const currentCard = await this.loadPublicCard();
+        if (canonicalize(currentCard) !== canonicalize(session.frozen_card)) {
+            throw new MerchantConnectError("PREVIEW_CHANGED", "公网服务的公开 Agent Card 已不同于商家批准的预览；未发布名片。请重新检查并授权新的公开信息。");
+        }
+        const catalogAgentId = session.catalog_agent_id;
+        const bindingId = session.binding_id;
+        const verified = {
+            agentId: catalogAgentId,
+            bindingId,
+            bindingVersion: session.binding_version,
+            merchantId: session.merchant_id,
+            keyThumbprint: this.keyThumbprint,
+            runtimeOrigin: this.origin,
+            a2aEndpoint: this.a2aEndpoint,
+            expiresAt: session.binding_expires_at,
+            cardRevision: session.card_revision ?? null,
+        };
+        if (this.beforePublish !== undefined)
+            await this.beforePublish(verified);
+        const expectedRevision = session.expected_card_revision ?? 0;
+        let cardRevision = session.card_revision;
+        if (cardRevision === undefined) {
+            const publication = await this.client.publishCard({
+                agentId: catalogAgentId,
+                bindingId,
+                generation: session.generation ?? this.generation,
+                expectedRevision,
+                agentCard: session.frozen_card,
+                a2aEndpoint: this.a2aEndpoint,
+                runtimeOrigin: this.origin,
+            }, this.identity);
+            if (publication.revision === null) {
+                throw new MerchantConnectError("PUBLICATION_RECEIPT_INVALID", "Catalog 未返回名片 revision；绑定已保留，重试可续办");
+            }
+            cardRevision = publication.revision;
+            const publishedCard = { ...session, card_revision: cardRevision };
+            this.persist((fresh) => fresh.sessions.map((item) => item.enrollment_id === session.enrollment_id ? publishedCard : item));
+            session = publishedCard;
+        }
+        const activated = await this.client.activateCard({
+            agentId: catalogAgentId,
+            bindingId,
+            cardRevision,
+            expectedRevision,
+        }, this.identity);
+        if (activated.revision === null) {
+            throw new MerchantConnectError("ACTIVATION_RECEIPT_INVALID", "Catalog 未确认名片激活；绑定已保留，重试可续办");
+        }
+        const published = { ...session, status: "published", card_revision: activated.revision };
+        // 同 catalog agent 的旧 published 会话由新绑定取代（标 replaced）；其余一律保留。
+        this.persist((fresh) => fresh.sessions.map((item) => {
+            if (item.enrollment_id === session.enrollment_id)
+                return published;
+            const old = item;
+            return old.status === "published" && old.catalog_agent_id === published.catalog_agent_id &&
+                old.binding_id !== published.binding_id
+                ? { ...old, status: "replaced" }
+                : item;
+        }));
+        this.markPublishedVerified();
+        return published;
+    }
+    // ── 内部 ─────────────────────────────────────────────────────────────
+    /**
+     * 选择当前（origin, key, catalog_origin, generation）可续的会话。
+     * published 永不过期；其余状态按各自过期口径（bound 看 binding_expires_at）。
+     * 逐条扫描而非取首条：第一条 catalog/generation 不匹配不得遮挡后面正确的会话；
+     * 任何路径都不得把别的 Catalog 的 device_code/grant 发给当前 Catalog。
+     */
+    selectSession(store) {
+        const nowMs = this.now().getTime();
+        for (const item of store.sessions) {
+            const session = item;
+            if (session.runtime_origin !== this.origin || session.key_thumbprint !== this.keyThumbprint)
+                continue;
+            if (!["preparing", "authorized", "bound", "published"].includes(session.status))
+                continue;
+            if (session.status !== "published") {
+                // published 永不在本地按首签 claim 的 TTL 判死（Catalog 每次公开读都会
+                // 重签短期声明；长期绑定是否有效由 Catalog 复核把关），其余状态按各自
+                // 过期口径：bound 看验真绑定 binding_expires_at，preparing/authorized
+                // 看授权窗口 expires_at。
+                const expiry = session.status === "bound" ? session.binding_expires_at : session.expires_at;
+                if (!(Number.isFinite(Date.parse(expiry ?? "")) && Date.parse(expiry ?? "") > nowMs))
+                    continue;
+            }
+            if (session.catalog_origin !== this.client.catalogOrigin)
+                continue;
+            if (session.generation !== undefined && session.generation !== this.generation)
+                continue;
+            return session;
+        }
+        return undefined;
+    }
+    /** 同 origin/key/catalog/generation、但授权窗口已过的 preparing/authorized 会话。 */
+    findStaleSession(store) {
+        const candidate = store.sessions.find((item) => {
+            const session = item;
+            return session.runtime_origin === this.origin && session.key_thumbprint === this.keyThumbprint &&
+                (session.generation ?? 1) === this.generation &&
+                session.catalog_origin === this.client.catalogOrigin &&
+                ["preparing", "authorized"].includes(session.status) &&
+                (!Number.isFinite(Date.parse(session.expires_at)) || Date.parse(session.expires_at) <= this.now().getTime());
+        });
+        return candidate;
+    }
+    /**
+     * 同 origin+key 可续、但属于**其他 Catalog** 的会话（begin 创建新 enrollment
+     * 前的显式守卫；selection 本身已按 catalog 过滤，这里只是给出明确拒绝）。
+     */
+    findForeignCatalogSession(store) {
+        const nowMs = this.now().getTime();
+        for (const item of store.sessions) {
+            const session = item;
+            if (session.runtime_origin !== this.origin || session.key_thumbprint !== this.keyThumbprint)
+                continue;
+            if (!["preparing", "authorized", "bound", "published"].includes(session.status))
+                continue;
+            if (session.status !== "published") {
+                const expiry = session.status === "bound" ? session.binding_expires_at : session.expires_at;
+                if (!(Number.isFinite(Date.parse(expiry ?? "")) && Date.parse(expiry ?? "") > nowMs))
+                    continue;
+            }
+            if (session.catalog_origin === this.client.catalogOrigin)
+                continue;
+            if (session.generation !== undefined && session.generation !== this.generation)
+                continue;
+            return session;
+        }
+        return undefined;
+    }
+    /**
+     * published 会话核对 Catalog **当次重签**的公开绑定声明；不符即
+     * PUBLICATION_NOT_ACTIVE（不自动恢复）。返回核对通过的公开文档，
+     * 其 expiresAt 是新鲜短期声明的期限（Catalog 每次公开读重签，
+     * expires_at=now+ttl≤900s），不是长期绑定的终止时间——长期绑定过期由
+     * Catalog 拒签（403）体现。
+     */
+    async assertPublicationActive(session) {
+        if (session.catalog_agent_id === undefined || session.binding_id === undefined) {
+            throw new MerchantConnectError("STATE_INVALID", "已发布接入缺少 Catalog/绑定信息。");
+        }
+        const active = await this.client.fetchPublicBinding(session.catalog_agent_id);
+        if (active === null || active.bindingId !== session.binding_id ||
+            (session.binding_version !== undefined && active.bindingVersion !== session.binding_version) ||
+            active.keyThumbprint !== this.keyThumbprint ||
+            active.runtimeOrigin.replace(/\/+$/, "") !== this.origin || active.a2aEndpoint !== this.a2aEndpoint ||
+            active.cardRevision !== session.card_revision ||
+            !Number.isFinite(Date.parse(active.expiresAt)) || Date.parse(active.expiresAt) <= this.now().getTime() ||
+            !["ACTIVE", "active"].includes(active.publicationState)) {
+            throw new MerchantConnectError("PUBLICATION_NOT_ACTIVE", "Catalog 当前没有返回这条绑定和已激活名片；服务可能已暂停或撤回。请到Catalog恢复服务后再检查，Runtime不会自动恢复营业。");
+        }
+        if (session.merchant_id === undefined) {
+            const backfilled = { ...session, merchant_id: active.merchantId };
+            this.persist((fresh) => fresh.sessions.map((item) => item.enrollment_id === session.enrollment_id ? backfilled : item));
+            return active;
+        }
+        if (session.merchant_id !== active.merchantId) {
+            throw new MerchantConnectError("BINDING_MERCHANT_MISMATCH", "Catalog binding的merchant_id与本地Enrollment不一致，已停止。");
+        }
+        return active;
+    }
+    /** 用当次重签的公开声明构造已验证绑定投影（期限取新鲜声明）。 */
+    verifiedFromPublication(session, active) {
+        return {
+            agentId: session.catalog_agent_id,
+            bindingId: active.bindingId,
+            bindingVersion: active.bindingVersion,
+            merchantId: active.merchantId,
+            keyThumbprint: active.keyThumbprint,
+            runtimeOrigin: active.runtimeOrigin,
+            a2aEndpoint: active.a2aEndpoint,
+            expiresAt: active.expiresAt,
+            cardRevision: active.cardRevision,
+        };
+    }
+    verifiedFromSession(session) {
+        if (session.catalog_agent_id === undefined || session.binding_id === undefined ||
+            session.binding_version === undefined || session.merchant_id === undefined ||
+            session.binding_expires_at === undefined)
+            return null;
+        if (!Number.isFinite(Date.parse(session.binding_expires_at)) || Date.parse(session.binding_expires_at) <= this.now().getTime()) {
+            return null;
+        }
+        return {
+            agentId: session.catalog_agent_id,
+            bindingId: session.binding_id,
+            bindingVersion: session.binding_version,
+            merchantId: session.merchant_id,
+            keyThumbprint: session.key_thumbprint,
+            runtimeOrigin: session.runtime_origin,
+            a2aEndpoint: this.a2aEndpoint,
+            expiresAt: session.binding_expires_at,
+            cardRevision: session.card_revision ?? null,
+        };
+    }
+    /**
+     * published 的 summary 视图是 fail-closed 的，仅限"本次已验证"的当前绑定/名片：
+     * 本实例尚未核对 → unknown/published=false；撤回暂停 → paused/published=false；
+     * 核对出错（含网络不可达、长期绑定过期被 Catalog 拒签）→ error/published=false。
+     * 绝不把读取本地历史记录当作当前发布回执，也绝不用首签声明的短期 TTL 在本地判死。
+     */
+    toSummary(session) {
+        if (session === null) {
+            return { status: "idle", published: false, agentId: null, bindingId: null, bindingExpiresAt: null, cardRevision: null, code: null, detail: null };
+        }
+        if (session.status !== "published") {
+            return {
+                status: session.status === "preparing" ? "awaiting_confirmation" : session.status,
+                published: false,
+                agentId: session.catalog_agent_id ?? null,
+                bindingId: session.binding_id ?? null,
+                bindingExpiresAt: session.binding_expires_at ?? null,
+                cardRevision: session.card_revision ?? null,
+                code: null,
+                detail: null,
+            };
+        }
+        // published 绝不在本地按首签 claim 的 TTL 判死：binding_expires_at 只是
+        // 首次绑定声明的短期期限（Catalog 每次公开读重签 expires_at=now+ttl≤900s
+        // 的新声明），长期绑定是否有效只由 Catalog 复核结论决定。
+        if (!this.publicationVerified || this.availability !== null) {
+            const paused = this.availability?.code === "PUBLICATION_NOT_ACTIVE";
+            return {
+                status: this.availability === null ? "unknown" : paused ? "paused" : "error",
+                published: false,
+                agentId: session.catalog_agent_id ?? null,
+                bindingId: session.binding_id ?? null,
+                bindingExpiresAt: session.binding_expires_at ?? null,
+                cardRevision: session.card_revision ?? null,
+                code: this.availability?.code ?? null,
+                detail: this.availability?.detail ?? "本实例尚未完成 Catalog 发布核对；published 暂报未确认。",
+            };
+        }
+        return {
+            status: "published", published: true,
+            agentId: session.catalog_agent_id ?? null,
+            bindingId: session.binding_id ?? null,
+            bindingExpiresAt: session.binding_expires_at ?? null,
+            cardRevision: session.card_revision ?? null,
+            code: null,
+            detail: null,
+        };
+    }
+    /** 0600 原子写；mutator 在**新鲜重读**的 store 上操作，保留 consumed 与其他会话。 */
+    persist(mutate) {
+        const fresh = readEnrollmentStore(this.dataDir);
+        const sessions = mutate(fresh);
+        writeFileAtomic(enrollmentStorePath(this.dataDir), `${JSON.stringify({ ...fresh, sessions })}\n`, { mode: 0o600 });
+    }
+    async withLock(fn) {
+        const result = this.mutex.then(fn);
+        this.mutex = result.then(() => undefined, () => undefined);
+        return result;
+    }
+}
+/** 构造连接服务（幂等工厂；同一 dataDir 可由 CLI 与服务实例先后使用）。 */
+export function createMerchantConnectionService(options) {
+    return new ConnectionServiceImpl(options);
+}
+//# sourceMappingURL=connect-service.js.map