@harrylabsj/kiwi 0.6.0

package/dist/handoff/candidate.js

@@ -0,0 +1,172 @@
+/**
+ * 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.
+ */
+/**
+ * HandoffCandidate —— KTH/0.1 §5 不可变候选（v0.7.0 WP-C1 / 完成定义 #9、#10）。
+ *
+ * 与 `HandoffPackage`（src/handoff/package.ts，v0.6.0 WP1 的 UCP checkout session
+ * 层工件）**不是一回事**：HandoffPackage 是 UCP Checkout 适配层输入；
+ * HandoffCandidate 是 KTH 候选——agreement → 策略/批准 → 重验 → 交付链的
+ * 第一环。二者并存（术语对齐决策：不重命名、双轨共存）。
+ *
+ * 不可变性（KTH rev0.3 §5.1）：内容全部 readonly + 防御拷贝；
+ * lifecycle 状态**不是**候选 JSON 内的字段——它是 Ledger 事件的
+ * event-sourced 投影（见 lifecycle.ts / ledger.ts）。
+ *
+ * digest：candidate_digest = RFC 8785 JCS(contentDigest) 去除自身字段后
+ * 的 SHA-256（复用 src/negotiation/jcs.ts，KTH rev0.3 §10.1）。
+ */
+import { requireBoolean, requireIsoTimestamp, requireNonEmptyString, requireObject, schemaError, } from "../negotiation/domain/common.js";
+import { generateId, validateIdentifier } from "../negotiation/domain/identifiers.js";
+import { contentDigest } from "../negotiation/jcs.js";
+import { validateDestination } from "./destination.js";
+/** 类型守卫。 */
+export function isHandoffCandidate(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value.handoff_candidate_id !== undefined &&
+        value.candidate_digest !== undefined);
+}
+/** 计算 candidate_digest：candidate 去除 candidate_digest 后 JCS+SHA-256。 */
+export function computeCandidateDigest(candidate) {
+    const { candidate_digest: _digest, ...rest } = candidate;
+    return contentDigest(rest);
+}
+/** 校验 candidate_digest 与内容自洽。 */
+export function verifyHandoffCandidateDigest(candidate) {
+    return candidate.candidate_digest === computeCandidateDigest(candidate);
+}
+function freezeSummary(summary, path) {
+    const obj = requireObject(summary, path);
+    return Object.freeze({
+        merchant: requireNonEmptyString(obj.merchant, `${path}/merchant`),
+        summary: requireNonEmptyString(obj.summary, `${path}/summary`),
+    });
+}
+/**
+ * 构造即校验（KTH §5）：agreement 绑定、terms_digest 一致性（提供
+ * agreed_terms 时重算比对）、destination 校验、三 false 不变量、标识符
+ * 与时间戳校验。返回不可变候选（防御拷贝）。
+ */
+export function createHandoffCandidate(input) {
+    const agreementId = validateIdentifier(input.agreement_id, "agreement_id");
+    const negotiationId = validateIdentifier(input.negotiation_id, "negotiation_id");
+    if (input.buyer_identity_ref !== undefined) {
+        validateIdentifier(input.buyer_identity_ref, "buyer_identity_ref");
+    }
+    if (input.merchant_identity_ref !== undefined) {
+        validateIdentifier(input.merchant_identity_ref, "merchant_identity_ref");
+    }
+    if (input.supersedes_candidate_id !== undefined) {
+        validateIdentifier(input.supersedes_candidate_id, "supersedes_candidate_id");
+    }
+    let termsDigest = input.terms_digest;
+    if (input.agreed_terms !== undefined) {
+        const recomputed = contentDigest(input.agreed_terms);
+        if (termsDigest !== undefined && termsDigest !== recomputed) {
+            throw schemaError("terms_digest", `terms_digest does not match recomputed digest of agreed_terms ` +
+                `(expected ${termsDigest}, got ${recomputed})`);
+        }
+        termsDigest = recomputed;
+    }
+    if (termsDigest === undefined) {
+        throw schemaError("terms_digest", "terms_digest is required (or provide agreed_terms)");
+    }
+    requireNonEmptyString(termsDigest, "terms_digest");
+    const destination = validateDestination(input.destination, "destination");
+    const displaySummary = freezeSummary(input.display_summary, "display_summary");
+    const policyVersion = requireNonEmptyString(input.policy_version, "policy_version");
+    requireIsoTimestamp(input.expires_at, "expires_at");
+    const createdAt = input.created_at ?? new Date().toISOString();
+    requireIsoTimestamp(createdAt, "created_at");
+    const candidate = Object.freeze({
+        handoff_candidate_id: generateId("handoff_candidate"),
+        ...(input.supersedes_candidate_id !== undefined
+            ? { supersedes_candidate_id: input.supersedes_candidate_id }
+            : {}),
+        agreement_id: agreementId,
+        negotiation_id: negotiationId,
+        terms_digest: termsDigest,
+        buyer_identity_ref: input.buyer_identity_ref ?? "principal:unknown",
+        merchant_identity_ref: input.merchant_identity_ref ?? "merchant:unknown",
+        destination_type: destination.type,
+        destination_ref: destination.ref,
+        ...(destination.payload !== undefined ? { destination_payload: destination.payload } : {}),
+        display_summary: displaySummary,
+        policy_version: policyVersion,
+        expires_at: input.expires_at,
+        requires_user_action: input.requires_user_action ?? true,
+        creates_order: false,
+        authorizes_payment: false,
+        reserves_inventory: false,
+        candidate_digest: "",
+        created_at: createdAt,
+    });
+    // digest 依赖内容 → 构造完成后再计算，并整体冻结。
+    return Object.freeze({ ...candidate, candidate_digest: computeCandidateDigest(candidate) });
+}
+/**
+ * 校验并重建一个候选对象（Ledger 事件重建，§18-13）。
+ *
+ * 保留输入的 handoff_candidate_id 与 candidate_digest（不重新生成）：
+ * 字段校验复用 createHandoffCandidate 的规则，然后以输入 id 覆盖，
+ * 再核对 digest（提供 digest 时）或按内容重算（缺省时）。
+ */
+export function validateHandoffCandidate(value, path = "handoff_candidate") {
+    const obj = requireObject(value, path);
+    if (obj.creates_order !== false || obj.authorizes_payment !== false || obj.reserves_inventory !== false) {
+        throw schemaError(path, "HandoffCandidate 三副作用不变量必须全为 false（KTH/1.0 不创建订单/不授权支付/不预留库存）");
+    }
+    requireBoolean(obj.requires_user_action, `${path}/requires_user_action`);
+    const candidateId = validateIdentifier(obj.handoff_candidate_id, `${path}/handoff_candidate_id`);
+    const generated = createHandoffCandidate({
+        agreement_id: requireNonEmptyString(obj.agreement_id, `${path}/agreement_id`),
+        negotiation_id: requireNonEmptyString(obj.negotiation_id, `${path}/negotiation_id`),
+        terms_digest: requireNonEmptyString(obj.terms_digest, `${path}/terms_digest`),
+        buyer_identity_ref: obj.buyer_identity_ref,
+        merchant_identity_ref: obj.merchant_identity_ref,
+        destination: {
+            type: obj.destination_type,
+            ref: requireNonEmptyString(obj.destination_ref, `${path}/destination_ref`),
+            ...(obj.destination_payload !== undefined
+                ? { payload: obj.destination_payload }
+                : {}),
+        },
+        display_summary: {
+            merchant: requireNonEmptyString(obj.display_summary?.merchant, `${path}/display_summary/merchant`),
+            summary: requireNonEmptyString(obj.display_summary?.summary, `${path}/display_summary/summary`),
+        },
+        policy_version: requireNonEmptyString(obj.policy_version, `${path}/policy_version`),
+        expires_at: requireIsoTimestamp(obj.expires_at, `${path}/expires_at`),
+        requires_user_action: obj.requires_user_action,
+        ...(obj.supersedes_candidate_id !== undefined
+            ? { supersedes_candidate_id: obj.supersedes_candidate_id }
+            : {}),
+        created_at: obj.created_at,
+    });
+    const withId = { ...generated, handoff_candidate_id: candidateId };
+    if (obj.candidate_digest !== undefined) {
+        const withDigest = {
+            ...withId,
+            candidate_digest: requireNonEmptyString(obj.candidate_digest, `${path}/candidate_digest`),
+        };
+        if (!verifyHandoffCandidateDigest(withDigest)) {
+            throw schemaError(`${path}/candidate_digest`, "candidate_digest mismatch on rebuild");
+        }
+        return Object.freeze(withDigest);
+    }
+    return Object.freeze({ ...withId, candidate_digest: computeCandidateDigest(withId) });
+}
+//# sourceMappingURL=candidate.js.map

package/dist/handoff/candidate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidate.js","sourceRoot":"","sources":["../../src/handoff/candidate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,qBAAqB,EACrB,aAAa,EACb,WAAW,GACZ,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AACtF,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAwB,MAAM,kBAAkB,CAAC;AA2D7E,YAAY;AACZ,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAAiC,CAAC,oBAAoB,KAAK,SAAS;QACpE,KAAiC,CAAC,gBAAgB,KAAK,SAAS,CAClE,CAAC;AACJ,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,sBAAsB,CAAC,SAAqC;IAC1E,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,SAAS,CAAC;IACzD,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED,iCAAiC;AACjC,MAAM,UAAU,4BAA4B,CAAC,SAA2B;IACtE,OAAO,SAAS,CAAC,gBAAgB,KAAK,sBAAsB,CAAC,SAAS,CAAC,CAAC;AAC1E,CAAC;AAED,SAAS,aAAa,CAAC,OAAgB,EAAE,IAAY;IACnD,MAAM,GAAG,GAAG,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACzC,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,QAAQ,EAAE,qBAAqB,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,IAAI,WAAW,CAAC;QACjE,OAAO,EAAE,qBAAqB,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,IAAI,UAAU,CAAC;KAC/D,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAA4B;IACjE,MAAM,WAAW,GAAG,kBAAkB,CAAC,KAAK,CAAC,YAAY,EAAE,cAAc,CAAC,CAAC;IAC3E,MAAM,aAAa,GAAG,kBAAkB,CAAC,KAAK,CAAC,cAAc,EAAE,gBAAgB,CAAC,CAAC;IACjF,IAAI,KAAK,CAAC,kBAAkB,KAAK,SAAS,EAAE,CAAC;QAC3C,kBAAkB,CAAC,KAAK,CAAC,kBAAkB,EAAE,oBAAoB,CAAC,CAAC;IACrE,CAAC;IACD,IAAI,KAAK,CAAC,qBAAqB,KAAK,SAAS,EAAE,CAAC;QAC9C,kBAAkB,CAAC,KAAK,CAAC,qBAAqB,EAAE,uBAAuB,CAAC,CAAC;IAC3E,CAAC;IACD,IAAI,KAAK,CAAC,uBAAuB,KAAK,SAAS,EAAE,CAAC;QAChD,kBAAkB,CAAC,KAAK,CAAC,uBAAuB,EAAE,yBAAyB,CAAC,CAAC;IAC/E,CAAC;IAED,IAAI,WAAW,GAAG,KAAK,CAAC,YAAY,CAAC;IACrC,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACrC,MAAM,UAAU,GAAG,aAAa,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;QACrD,IAAI,WAAW,KAAK,SAAS,IAAI,WAAW,KAAK,UAAU,EAAE,CAAC;YAC5D,MAAM,WAAW,CACf,cAAc,EACd,gEAAgE;gBAC9D,aAAa,WAAW,SAAS,UAAU,GAAG,CACjD,CAAC;QACJ,CAAC;QACD,WAAW,GAAG,UAAU,CAAC;IAC3B,CAAC;IACD,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,MAAM,WAAW,CAAC,cAAc,EAAE,oDAAoD,CAAC,CAAC;IAC1F,CAAC;IACD,qBAAqB,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC;IAEnD,MAAM,WAAW,GAAG,mBAAmB,CAAC,KAAK,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC;IAC1E,MAAM,cAAc,GAAG,aAAa,CAAC,KAAK,CAAC,eAAe,EAAE,iBAAiB,CAAC,CAAC;IAC/E,MAAM,aAAa,GAAG,qBAAqB,CAAC,KAAK,CAAC,cAAc,EAAE,gBAAgB,CAAC,CAAC;IACpF,mBAAmB,CAAC,KAAK,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;IACpD,MAAM,SAAS,GAAG,KAAK,CAAC,UAAU,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC/D,mBAAmB,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;IAE7C,MAAM,SAAS,GAAqB,MAAM,CAAC,MAAM,CAAC;QAChD,oBAAoB,EAAE,UAAU,CAAC,mBAAmB,CAAC;QACrD,GAAG,CAAC,KAAK,CAAC,uBAAuB,KAAK,SAAS;YAC7C,CAAC,CAAC,EAAE,uBAAuB,EAAE,KAAK,CAAC,uBAAuB,EAAE;YAC5D,CAAC,CAAC,EAAE,CAAC;QACP,YAAY,EAAE,WAAW;QACzB,cAAc,EAAE,aAAa;QAC7B,YAAY,EAAE,WAAW;QACzB,kBAAkB,EAAE,KAAK,CAAC,kBAAkB,IAAI,mBAAmB;QACnE,qBAAqB,EAAE,KAAK,CAAC,qBAAqB,IAAI,kBAAkB;QACxE,gBAAgB,EAAE,WAAW,CAAC,IAAI;QAClC,eAAe,EAAE,WAAW,CAAC,GAAG;QAChC,GAAG,CAAC,WAAW,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,mBAAmB,EAAE,WAAW,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1F,eAAe,EAAE,cAAc;QAC/B,cAAc,EAAE,aAAa;QAC7B,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,oBAAoB,EAAE,KAAK,CAAC,oBAAoB,IAAI,IAAI;QACxD,aAAa,EAAE,KAAK;QACpB,kBAAkB,EAAE,KAAK;QACzB,kBAAkB,EAAE,KAAK;QACzB,gBAAgB,EAAE,EAAE;QACpB,UAAU,EAAE,SAAS;KACtB,CAAqB,CAAC;IAEvB,gCAAgC;IAChC,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,SAAS,EAAE,gBAAgB,EAAE,sBAAsB,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;AAC9F,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAAc,EAAE,IAAI,GAAG,mBAAmB;IACjF,MAAM,GAAG,GAAG,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACvC,IAAI,GAAG,CAAC,aAAa,KAAK,KAAK,IAAI,GAAG,CAAC,kBAAkB,KAAK,KAAK,IAAI,GAAG,CAAC,kBAAkB,KAAK,KAAK,EAAE,CAAC;QACxG,MAAM,WAAW,CACf,IAAI,EACJ,+DAA+D,CAChE,CAAC;IACJ,CAAC;IACD,cAAc,CAAC,GAAG,CAAC,oBAAoB,EAAE,GAAG,IAAI,uBAAuB,CAAC,CAAC;IACzE,MAAM,WAAW,GAAG,kBAAkB,CAAC,GAAG,CAAC,oBAAoB,EAAE,GAAG,IAAI,uBAAuB,CAAC,CAAC;IACjG,MAAM,SAAS,GAAG,sBAAsB,CAAC;QACvC,YAAY,EAAE,qBAAqB,CAAC,GAAG,CAAC,YAAY,EAAE,GAAG,IAAI,eAAe,CAAC;QAC7E,cAAc,EAAE,qBAAqB,CAAC,GAAG,CAAC,cAAc,EAAE,GAAG,IAAI,iBAAiB,CAAC;QACnF,YAAY,EAAE,qBAAqB,CAAC,GAAG,CAAC,YAAY,EAAE,GAAG,IAAI,eAAe,CAAC;QAC7E,kBAAkB,EAAE,GAAG,CAAC,kBAAwC;QAChE,qBAAqB,EAAE,GAAG,CAAC,qBAA2C;QACtE,WAAW,EAAE;YACX,IAAI,EAAE,GAAG,CAAC,gBAAmC;YAC7C,GAAG,EAAE,qBAAqB,CAAC,GAAG,CAAC,eAAe,EAAE,GAAG,IAAI,kBAAkB,CAAC;YAC1E,GAAG,CAAC,GAAG,CAAC,mBAAmB,KAAK,SAAS;gBACvC,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,mBAA8C,EAAE;gBACjE,CAAC,CAAC,EAAE,CAAC;SACR;QACD,eAAe,EAAE;YACf,QAAQ,EAAE,qBAAqB,CAC5B,GAAG,CAAC,eAAuD,EAAE,QAAQ,EACtE,GAAG,IAAI,2BAA2B,CACnC;YACD,OAAO,EAAE,qBAAqB,CAC3B,GAAG,CAAC,eAAuD,EAAE,OAAO,EACrE,GAAG,IAAI,0BAA0B,CAClC;SACF;QACD,cAAc,EAAE,qBAAqB,CAAC,GAAG,CAAC,cAAc,EAAE,GAAG,IAAI,iBAAiB,CAAC;QACnF,UAAU,EAAE,mBAAmB,CAAC,GAAG,CAAC,UAAU,EAAE,GAAG,IAAI,aAAa,CAAC;QACrE,oBAAoB,EAAE,GAAG,CAAC,oBAA2C;QACrE,GAAG,CAAC,GAAG,CAAC,uBAAuB,KAAK,SAAS;YAC3C,CAAC,CAAC,EAAE,uBAAuB,EAAE,GAAG,CAAC,uBAAiC,EAAE;YACpE,CAAC,CAAC,EAAE,CAAC;QACP,UAAU,EAAE,GAAG,CAAC,UAAgC;KACjD,CAAC,CAAC;IACH,MAAM,MAAM,GAAqB,EAAE,GAAG,SAAS,EAAE,oBAAoB,EAAE,WAAW,EAAE,CAAC;IACrF,IAAI,GAAG,CAAC,gBAAgB,KAAK,SAAS,EAAE,CAAC;QACvC,MAAM,UAAU,GAAqB;YACnC,GAAG,MAAM;YACT,gBAAgB,EAAE,qBAAqB,CAAC,GAAG,CAAC,gBAAgB,EAAE,GAAG,IAAI,mBAAmB,CAAC;SAC1F,CAAC;QACF,IAAI,CAAC,4BAA4B,CAAC,UAAU,CAAC,EAAE,CAAC;YAC9C,MAAM,WAAW,CAAC,GAAG,IAAI,mBAAmB,EAAE,sCAAsC,CAAC,CAAC;QACxF,CAAC;QACD,OAAO,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,MAAM,EAAE,gBAAgB,EAAE,sBAAsB,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AACxF,CAAC"}

package/dist/handoff/channel.d.ts

@@ -0,0 +1,88 @@
+/**
+ * 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 { TermSet } from "../negotiation/domain/common.js";
+import type { PaymentAuthorization, AuthorizationProvider } from "./authorization.js";
+import type { HandoffPackage } from "./package.js";
+export declare const HANDOFF_SESSION_STATUSES: readonly ["created", "updated", "completed", "cancelled"];
+export type HandoffSessionStatus = (typeof HANDOFF_SESSION_STATUSES)[number];
+/**
+ * 交易系统上的一个 checkout session。current_terms 可被 updateSession 改变
+ * （建模「下单前改购物车」）；current_terms_digest 与 current_terms 始终一致。
+ * 授权与完成门禁只认 current_terms_digest —— 换 terms 后旧授权即失效。
+ */
+export interface HandoffSession {
+    session_ref: string;
+    /** 创建该 session 的交接工件（原始 agreed_terms 是商业共识来源）。 */
+    package: HandoffPackage;
+    current_terms: TermSet;
+    current_terms_digest: string;
+    status: HandoffSessionStatus;
+    created_at: string;
+    updated_at: string;
+}
+/** HandoffChannel 的结构化结果（公共 `status` 判别）。 */
+export type HandoffResult = {
+    status: "ok";
+    session_ref: string;
+    session: HandoffSession;
+    continue_url?: string;
+} | {
+    status: "fail_closed";
+    reason: string;
+} | {
+    status: "requires_user";
+    continue_url?: string;
+    reason: string;
+};
+/** 交易系统适配接缝（WP2 实现 = UCP Checkout adapter）。 */
+export interface HandoffChannel {
+    createSession(pkg: HandoffPackage): HandoffResult;
+    getSession(ref: string): HandoffResult;
+    updateSession(ref: string, terms: TermSet): HandoffResult;
+    requestCompletion(ref: string, authorization: PaymentAuthorization): HandoffResult;
+    cancelSession(ref: string): HandoffResult;
+}
+export interface ManualHandoffChannelOptions {
+    /** 可注入时钟（RFC 3339）；缺省 new Date().toISOString()。 */
+    now?: () => string;
+    /** AP2 授权提供方；缺省 FailClosedAuthorizationProvider（完成一律拒绝）。 */
+    authorizationProvider?: AuthorizationProvider;
+}
+/**
+ * 参考实现：内存 Map + JSON 导出 + manual:// continue_url，无任何网络写入。
+ * requestCompletion 先跑完成门禁，任何前置不满足 → fail_closed。
+ */
+export declare class ManualHandoffChannel implements HandoffChannel {
+    private readonly sessions;
+    private readonly now;
+    private readonly authorizationProvider;
+    constructor(options?: ManualHandoffChannelOptions);
+    createSession(pkg: HandoffPackage): HandoffResult;
+    getSession(ref: string): HandoffResult;
+    updateSession(ref: string, terms: TermSet): HandoffResult;
+    requestCompletion(ref: string, authorization: PaymentAuthorization): HandoffResult;
+    cancelSession(ref: string): HandoffResult;
+    /** 导出 session JSON 供展示（Manual 参考实现；不执行任何网络写入）。 */
+    exportSessionJson(ref: string): {
+        status: "ok";
+        json: string;
+    } | {
+        status: "fail_closed";
+        reason: string;
+    };
+    /** 当前 session 数量（诊断用）。 */
+    get sessionCount(): number;
+}

package/dist/handoff/channel.js

@@ -0,0 +1,189 @@
+/**
+ * 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.
+ */
+/**
+ * Kiwi v0.7.0 Transaction Handoff — HandoffChannel 接缝（WP1）。
+ *
+ * HandoffChannel 是「交易系统适配接口」：真实实现（WP2 的 UCP Checkout adapter）
+ * 会在外部交易系统上创建 session / 更新 terms / 请求完成 / 取消。WP1 只定义
+ * 接口与结构化结果，并提供一个 ManualHandoffChannel 参考实现：
+ *
+ * - 内存 Map 存 session，导出 JSON + manual:// continue_url 供展示；
+ * - 不执行任何网络写入；
+ * - requestCompletion 复用完成门禁（completion.ts）——未配置真实 AP2 时，
+ *   默认 FailClosedAuthorizationProvider 保证一律 fail-closed，绝不伪造完成。
+ *
+ * 结构化结果（用公共 `status` 判别，strict TS 可可靠窄化；对应工作包语义
+ * `{ok}` / `{fail_closed, reason}` / `{requires_user, continue_url, reason}`）：
+ *   ok            —— 操作成功，携带 session；
+ *   fail_closed   —— 明确拒绝（找不到 session / 状态不可操作 / 门禁不过）；
+ *   requires_user —— 需要用户介入外部 checkout（如需要人去 UCP checkout 页面
+ *                    确认时），带 continue_url。
+ */
+import { uuidv7 } from "../negotiation/domain/identifiers.js";
+import { validateTermSet } from "../negotiation/domain/common.js";
+import { contentDigest } from "../negotiation/jcs.js";
+import { FailClosedAuthorizationProvider } from "./authorization.js";
+import { verifyHandoffPackageDigest } from "./package.js";
+import { evaluateCompletionGate } from "./completion.js";
+// ---------------------------------------------------------------------------
+// Session 与结果类型
+// ---------------------------------------------------------------------------
+export const HANDOFF_SESSION_STATUSES = ["created", "updated", "completed", "cancelled"];
+function sessionNotActionable(session) {
+    return session.status === "completed" || session.status === "cancelled";
+}
+function notFound(ref) {
+    return { status: "fail_closed", reason: `session_not_found: ${ref}` };
+}
+function notActionable(session) {
+    return { status: "fail_closed", reason: `session_not_actionable: status ${session.status}` };
+}
+/**
+ * 参考实现：内存 Map + JSON 导出 + manual:// continue_url，无任何网络写入。
+ * requestCompletion 先跑完成门禁，任何前置不满足 → fail_closed。
+ */
+export class ManualHandoffChannel {
+    sessions = new Map();
+    now;
+    authorizationProvider;
+    constructor(options = {}) {
+        this.now = options.now ?? (() => new Date().toISOString());
+        this.authorizationProvider =
+            options.authorizationProvider ?? new FailClosedAuthorizationProvider();
+    }
+    createSession(pkg) {
+        if (!verifyHandoffPackageDigest(pkg)) {
+            return {
+                status: "fail_closed",
+                reason: "createSession rejected: package terms_digest verification failed",
+            };
+        }
+        // 结构加固：agreed_terms 必须是合法 TermSet，且归一化后 digest 仍与
+        // terms_digest 一致（防伪造一个 digest 自洽但结构非法的 package）。
+        let currentTerms;
+        try {
+            currentTerms = validateTermSet(pkg.agreed_terms, "agreed_terms");
+        }
+        catch {
+            return {
+                status: "fail_closed",
+                reason: "createSession rejected: package agreed_terms failed structural validation",
+            };
+        }
+        if (contentDigest(currentTerms) !== pkg.terms_digest) {
+            return {
+                status: "fail_closed",
+                reason: "createSession rejected: package terms_digest does not match validated agreed_terms",
+            };
+        }
+        const sessionRef = `hs_${uuidv7()}`;
+        const now = this.now();
+        const session = {
+            session_ref: sessionRef,
+            package: pkg,
+            current_terms: currentTerms,
+            current_terms_digest: pkg.terms_digest,
+            status: "created",
+            created_at: now,
+            updated_at: now,
+        };
+        this.sessions.set(sessionRef, session);
+        // manual:// scheme 仅用于展示，不触发任何网络写入。
+        // 返回拷贝（与 getSession 一致：外部持有者不得持有内部对象引用）。
+        return {
+            status: "ok",
+            session_ref: sessionRef,
+            session: { ...session },
+            continue_url: `manual://checkout/${sessionRef}`,
+        };
+    }
+    getSession(ref) {
+        const session = this.sessions.get(ref);
+        if (session === undefined)
+            return notFound(ref);
+        // 返回拷贝：外部持有者不得绕过 status 机原地改写内部对象
+        //（此前引用别名泄漏，篡改 current_terms 靠完成门禁兜底，status 无兜底）。
+        return { status: "ok", session_ref: ref, session: { ...session } };
+    }
+    updateSession(ref, terms) {
+        const session = this.sessions.get(ref);
+        if (session === undefined)
+            return notFound(ref);
+        if (sessionNotActionable(session))
+            return notActionable(session);
+        const nextTerms = validateTermSet(terms, "terms");
+        // 不可变更新（新对象替换，不原地突变 Map 内的对象）。
+        const next = {
+            ...session,
+            current_terms: nextTerms,
+            current_terms_digest: contentDigest(nextTerms),
+            status: "updated",
+            updated_at: this.now(),
+        };
+        this.sessions.set(ref, next);
+        return { status: "ok", session_ref: ref, session: next };
+    }
+    requestCompletion(ref, authorization) {
+        const session = this.sessions.get(ref);
+        if (session === undefined)
+            return notFound(ref);
+        if (sessionNotActionable(session))
+            return notActionable(session);
+        // 完成门禁：授权验证 + terms_digest 一致 + 未 stale，任一不满足 → fail_closed。
+        const gate = evaluateCompletionGate({
+            authorization,
+            session,
+            authorizationProvider: this.authorizationProvider,
+            now: this.now,
+        });
+        if (!gate.allowed) {
+            return { status: "fail_closed", reason: gate.reason };
+        }
+        const completed = {
+            ...session,
+            status: "completed",
+            updated_at: this.now(),
+        };
+        this.sessions.set(ref, completed);
+        return { status: "ok", session_ref: ref, session: completed };
+    }
+    cancelSession(ref) {
+        const session = this.sessions.get(ref);
+        if (session === undefined)
+            return notFound(ref);
+        if (sessionNotActionable(session))
+            return notActionable(session);
+        const cancelled = {
+            ...session,
+            status: "cancelled",
+            updated_at: this.now(),
+        };
+        this.sessions.set(ref, cancelled);
+        return { status: "ok", session_ref: ref, session: cancelled };
+    }
+    /** 导出 session JSON 供展示（Manual 参考实现；不执行任何网络写入）。 */
+    exportSessionJson(ref) {
+        const session = this.sessions.get(ref);
+        if (session === undefined)
+            return { status: "fail_closed", reason: `session_not_found: ${ref}` };
+        return { status: "ok", json: JSON.stringify(session, null, 2) };
+    }
+    /** 当前 session 数量（诊断用）。 */
+    get sessionCount() {
+        return this.sessions.size;
+    }
+}
+//# sourceMappingURL=channel.js.map

package/dist/handoff/channel.js.map

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

package/dist/handoff/completion.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 { AuthorizationProvider, PaymentAuthorization } from "./authorization.js";
+import type { HandoffSession } from "./channel.js";
+export declare const COMPLETION_GATE_FAILURE_CODES: readonly ["authorization_not_verified", "terms_digest_mismatch", "approval_stale"];
+export type CompletionGateFailureCode = (typeof COMPLETION_GATE_FAILURE_CODES)[number];
+export type CompletionGateDecision = {
+    allowed: true;
+} | {
+    allowed: false;
+    code: CompletionGateFailureCode;
+    reason: string;
+};
+export interface CompletionGateContext {
+    authorization: PaymentAuthorization;
+    /** 待完成的 session（其 current_terms / current_terms_digest 是门禁输入）。 */
+    session: HandoffSession;
+    authorizationProvider: AuthorizationProvider;
+    /** 可注入时钟（RFC 3339）；缺省 new Date().toISOString()。 */
+    now?: () => string;
+}
+/**
+ * authorization 结构守卫：门禁绝不能信任一个字段缺失/格式错误的授权对象。
+ * 结构合法 ≠ 授权有效 —— 有效性由第 1 步 provider 验证与第 2/3 步绑定复核决定。
+ */
+export declare function isStructurallyValidAuthorization(value: unknown): value is PaymentAuthorization;
+/**
+ * 完成门禁判定（纯函数）。判定顺序固定（验授权 → 验 terms 绑定 → 验 stale），
+ * 任一失败 fail-closed。
+ */
+export declare function evaluateCompletionGate(ctx: CompletionGateContext): CompletionGateDecision;

package/dist/handoff/completion.js

@@ -0,0 +1,136 @@
+/**
+ * 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.
+ */
+/**
+ * Kiwi v0.7.0 Transaction Handoff — 完成门禁（WP1 交付 4）。
+ *
+ * requestCompletion 的调用前置条件（基线 §19 Approval Pipeline 绑定语义的
+ * 交接域投影；§4.6 fail closed）。任一不满足即拒绝完成，绝不静默放行：
+ *
+ *   1. authorization 经 AuthorizationProvider 验证
+ *      （verifyIntentMandate 必须 verified=true；authorization 结构必须先合法）；
+ *   2. terms_digest 与 session 当前 terms 一致
+ *      （session.current_terms 重算 digest 必须等于 current_terms_digest ——
+ *      防会话被篡改；且 authorization.terms_digest 必须等于该 digest ——
+ *      防授权被挪用到别的 terms）；
+ *   3. approval 未 stale
+ *      （authorization.session_ref 必须等于当前 session —— 换 session 即失效；
+ *      且未超过 expires_at —— 过期即 stale）。
+ *
+ * 判定顺序固定，便于审计：先验授权，再验 terms 绑定，最后验 stale。每个失败
+ * 都返回结构化 {allowed:false, code, reason}，由调用方决定如何转成
+ * HandoffResult（ManualHandoffChannel 把它映射为 {fail_closed, reason}）。
+ */
+import { contentDigest } from "../negotiation/jcs.js";
+export const COMPLETION_GATE_FAILURE_CODES = [
+    "authorization_not_verified",
+    "terms_digest_mismatch",
+    "approval_stale",
+];
+const DIGEST_RE = /^sha256:[0-9a-f]{64}$/;
+const TIMESTAMP_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+/**
+ * authorization 结构守卫：门禁绝不能信任一个字段缺失/格式错误的授权对象。
+ * 结构合法 ≠ 授权有效 —— 有效性由第 1 步 provider 验证与第 2/3 步绑定复核决定。
+ */
+export function isStructurallyValidAuthorization(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const a = value;
+    const evidence = a.evidence;
+    return (isNonEmptyString(a.authorization_id) &&
+        isNonEmptyString(a.session_ref) &&
+        typeof a.terms_digest === "string" &&
+        DIGEST_RE.test(a.terms_digest) &&
+        isNonEmptyString(a.intent_mandate) &&
+        typeof a.approved_at === "string" &&
+        TIMESTAMP_RE.test(a.approved_at) &&
+        typeof a.expires_at === "string" &&
+        TIMESTAMP_RE.test(a.expires_at) &&
+        evidence !== undefined &&
+        typeof evidence === "object" &&
+        (evidence.kind === "manual" || evidence.kind === "ap2") &&
+        isNonEmptyString(evidence.reference) &&
+        typeof evidence.confirmed_at === "string" &&
+        TIMESTAMP_RE.test(evidence.confirmed_at));
+}
+/**
+ * 完成门禁判定（纯函数）。判定顺序固定（验授权 → 验 terms 绑定 → 验 stale），
+ * 任一失败 fail-closed。
+ */
+export function evaluateCompletionGate(ctx) {
+    const { authorization, session, authorizationProvider } = ctx;
+    const now = ctx.now ?? (() => new Date().toISOString());
+    // 第 1 步：authorization 结构 + provider 验证。
+    if (!isStructurallyValidAuthorization(authorization)) {
+        return {
+            allowed: false,
+            code: "authorization_not_verified",
+            reason: "authorization is malformed; refusing to trust it",
+        };
+    }
+    const verification = authorizationProvider.verifyIntentMandate(authorization.intent_mandate, {
+        session_ref: authorization.session_ref,
+        terms_digest: authorization.terms_digest,
+    });
+    if (!verification.verified) {
+        return {
+            allowed: false,
+            code: "authorization_not_verified",
+            reason: verification.reason ?? "intent mandate verification failed",
+        };
+    }
+    // 第 2 步：terms_digest 与 session 当前 terms 一致。
+    const sessionCurrentDigest = contentDigest(session.current_terms);
+    if (sessionCurrentDigest !== session.current_terms_digest) {
+        return {
+            allowed: false,
+            code: "terms_digest_mismatch",
+            reason: "session.current_terms tampered: recomputed digest does not match current_terms_digest",
+        };
+    }
+    if (authorization.terms_digest !== session.current_terms_digest) {
+        return {
+            allowed: false,
+            code: "terms_digest_mismatch",
+            reason: "authorization is bound to different terms than session current terms",
+        };
+    }
+    // 第 3 步：approval 未 stale（§19 绑定语义 + 有效期）。
+    if (authorization.session_ref !== session.session_ref) {
+        return {
+            allowed: false,
+            code: "approval_stale",
+            reason: "authorization is bound to a different session_ref",
+        };
+    }
+    const expiresMs = Date.parse(authorization.expires_at);
+    const nowMs = Date.parse(now());
+    if (!Number.isFinite(expiresMs) || !Number.isFinite(nowMs)) {
+        return {
+            allowed: false,
+            code: "approval_stale",
+            reason: "invalid timestamp on authorization expires_at / clock",
+        };
+    }
+    if (nowMs > expiresMs) {
+        return { allowed: false, code: "approval_stale", reason: "authorization has expired" };
+    }
+    return { allowed: true };
+}
+//# sourceMappingURL=completion.js.map

package/dist/handoff/completion.js.map

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