@harrylabsj/kiwi 0.6.0

package/dist/fanout/policy.js

@@ -0,0 +1,130 @@
+/**
+ * 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 { trustLevelRank } from "../trust/identity/index.js";
+export const DISCLOSURE_TIERS = ["anonymous", "detailed"];
+/** §29 NetworkDisclosurePolicy 控制的属性清单。 */
+export const DISCLOSURE_ATTRIBUTES = [
+    "location_precision",
+    "organization_identity",
+    "buyer_urgency",
+    "contact_information",
+    "purchase_quantity",
+    "budget_hints",
+    "customer_segment",
+    "historical_preferences",
+];
+/** 默认披露档位：仅允许采购数量（round 2 精确数量）。预算/急迫度/身份等默认私有（§4.4）。 */
+export const DEFAULT_DISCLOSURE_PROFILE = {
+    allowed_attributes: ["purchase_quantity"],
+};
+/** 默认部署策略：推荐 progressive disclosure（§30），最多 5 家、最低 T1。 */
+export const DEFAULT_FANOUT_POLICY = {
+    max_recipients: 5,
+    minimum_trust: "T1",
+    disclosure_profile: DEFAULT_DISCLOSURE_PROFILE,
+    anonymous_first_round: true,
+};
+/** 取更严格（更高 rank）的信任要求：T3 比 T0 更严格。通用工具，供策略组合使用。 */
+export function stricterTrust(a, b) {
+    return trustLevelRank(a) >= trustLevelRank(b) ? a : b;
+}
+/** 命中敏感品类规则（大小写不敏感子串匹配；缺省 rule 匹配任意品类）。 */
+export function matchingCategorySensitivity(policy, category) {
+    if (policy.category_sensitivity === undefined)
+        return undefined;
+    const cat = category?.toLowerCase();
+    return policy.category_sensitivity.find((rule) => {
+        if (rule.category === undefined)
+            return true;
+        if (cat === undefined)
+            return false;
+        return cat.includes(rule.category.toLowerCase());
+    });
+}
+function tierFor(level, round, anonymousFirstRound, sensitive) {
+    if (round === 1) {
+        return anonymousFirstRound ? "anonymous" : "detailed";
+    }
+    // round 2：敏感品类且对端信任不足 → 披露门槛提升，只能拿匿名档。
+    if (sensitive?.minimum_trust !== undefined &&
+        trustLevelRank(level) < trustLevelRank(sensitive.minimum_trust)) {
+        return "anonymous";
+    }
+    return "detailed";
+}
+/**
+ * Fan-out 确定性判定（§30）。纯函数、无模型参与、无 I/O。
+ *
+ * 管线：解析信任 → 过滤（rejected / below_minimum_trust，按 base minimum_trust）
+ * → 确定性排序 → 截断（max_recipients）→ 按 round + 敏感性定每档 tier。
+ */
+export function judgeFanout(policy, input) {
+    const { profiles, trust = {}, category, round } = input;
+    const sensitive = matchingCategorySensitivity(policy, category);
+    // Eligibility 只按 base minimum_trust 过滤；category_sensitivity 只提升披露门槛
+    // （tier），不改变谁能收 RFQ。
+    const minTrust = policy.minimum_trust;
+    const eligible = [];
+    const excluded = [];
+    for (const profile of profiles) {
+        const signal = trust[profile.identity];
+        // §30：record 缺失按 T0；rejected 直接排除（fail-closed）。
+        const level = signal?.level ?? "T0";
+        const rejected = signal?.rejected === true;
+        if (rejected) {
+            excluded.push({ identity: profile.identity, reason: "rejected", trust_level: level });
+            continue;
+        }
+        if (trustLevelRank(level) < trustLevelRank(minTrust)) {
+            excluded.push({
+                identity: profile.identity,
+                reason: "below_minimum_trust",
+                trust_level: level,
+            });
+            continue;
+        }
+        eligible.push({ identity: profile.identity, profile, level });
+    }
+    // 确定性排序：trust 降序（高信任优先）→ identity 升序（稳定 tie-break）。
+    eligible.sort((a, b) => {
+        const rankDelta = trustLevelRank(b.level) - trustLevelRank(a.level);
+        if (rankDelta !== 0)
+            return rankDelta;
+        return a.identity < b.identity ? -1 : a.identity > b.identity ? 1 : 0;
+    });
+    const max = policy.max_recipients !== undefined && policy.max_recipients > 0
+        ? policy.max_recipients
+        : Number.POSITIVE_INFINITY;
+    const chosen = eligible.slice(0, max);
+    for (const t of eligible.slice(max)) {
+        excluded.push({ identity: t.identity, reason: "truncated", trust_level: t.level });
+    }
+    const anonymousFirstRound = policy.anonymous_first_round === true || sensitive?.anonymous_first_round === true;
+    const recipients = chosen.map((c) => ({
+        identity: c.identity,
+        profile: c.profile,
+        trust_level: c.level,
+        tier: tierFor(c.level, round, anonymousFirstRound, sensitive),
+    }));
+    return {
+        round,
+        recipients,
+        excluded,
+        eligible_count: eligible.length,
+        category_sensitive: sensitive !== undefined,
+    };
+}
+//# sourceMappingURL=policy.js.map

package/dist/fanout/policy.js.map

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

package/dist/handoff/acp-commerce.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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 — AcpCommerceAdapter 接缝（WP3）。
+ *
+ * 面向 Agentic Commerce Protocol（ACP-Commerce）checkout 生态的 HandoffChannel
+ * 适配占位。基线 §43：ACP-Commerce 属 v0.7.0+ Transaction Handoff，不绑定唯一实现；
+ * 本模块只钉住接缝形状，未来真实 ACP adapter 在同样位置替换内部实现。
+ *
+ * fail-closed 语义：
+ *   - 未配置真实 ACP-Commerce 服务时，所有操作一律返回 fail_closed；
+ *   - 绝不静默降级到 UCP 或其他通道（reason 明确标注 acp_commerce_not_configured）；
+ *   - 不创建订单、不处理支付凭据。
+ *
+ * 接口形状与 HandoffChannel 对齐（同一组操作、同一 HandoffResult 判别），未来
+ * 实现替换内部而不破坏调用方；若未来 ACP 需要异步投影，遵循 UcpCheckoutChannel
+ * 先例（AsyncHandoffChannel，status 判别不变）。
+ */
+import type { PaymentAuthorization } from "./authorization.js";
+import type { HandoffChannel, HandoffResult } from "./channel.js";
+import type { HandoffPackage } from "./package.js";
+import type { TermSet } from "../negotiation/domain/common.js";
+/** ACP-Commerce 接缝当前状态（占位阶段恒为 unconfigured）。 */
+export declare const ACP_COMMERCE_ADAPTER_STATUS: readonly ["unconfigured"];
+export type AcpCommerceAdapterStatus = (typeof ACP_COMMERCE_ADAPTER_STATUS)[number];
+/**
+ * 未来：ACP-Commerce checkout service endpoint / profile 配置。当前占位阶段无
+ * 配置字段（Record<string, never> 阻止任意值混入）。
+ */
+export type AcpCommerceAdapterOptions = Record<string, never>;
+/**
+ * ACP-Commerce 适配占位。实现 HandoffChannel 的全部操作，但未配置时一律
+ * fail-closed。`configured` 恒为 false —— 调用方可用它显式分支，而不是隐式降级。
+ */
+export declare class AcpCommerceAdapter implements HandoffChannel {
+    constructor(_options?: AcpCommerceAdapterOptions);
+    /** 当前是否已配置真实 ACP-Commerce 服务（占位阶段恒为 false）。 */
+    get configured(): boolean;
+    get status(): AcpCommerceAdapterStatus;
+    createSession(pkg: HandoffPackage): HandoffResult;
+    getSession(ref: string): HandoffResult;
+    updateSession(ref: string, _terms: TermSet): HandoffResult;
+    requestCompletion(ref: string, _authorization: PaymentAuthorization): HandoffResult;
+    cancelSession(ref: string): HandoffResult;
+}

package/dist/handoff/acp-commerce.js

@@ -0,0 +1,69 @@
+/**
+ * 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 { verifyHandoffPackageDigest } from "./package.js";
+/** ACP-Commerce 接缝当前状态（占位阶段恒为 unconfigured）。 */
+export const ACP_COMMERCE_ADAPTER_STATUS = ["unconfigured"];
+const NOT_CONFIGURED_REASON = "acp_commerce_not_configured: no Agentic Commerce Protocol checkout service is configured; " +
+    "refusing to route to UCP or any other channel (fail closed)";
+const SESSION_NOT_CONFIGURED = "acp_commerce_not_configured: no checkout session can exist";
+/**
+ * ACP-Commerce 适配占位。实现 HandoffChannel 的全部操作，但未配置时一律
+ * fail-closed。`configured` 恒为 false —— 调用方可用它显式分支，而不是隐式降级。
+ */
+export class AcpCommerceAdapter {
+    constructor(_options = {}) {
+        // 占位阶段无配置字段；未来真实 ACP adapter 在此接收 endpoint/profile。
+    }
+    /** 当前是否已配置真实 ACP-Commerce 服务（占位阶段恒为 false）。 */
+    get configured() {
+        return false;
+    }
+    get status() {
+        return "unconfigured";
+    }
+    createSession(pkg) {
+        // 即使未配置也先做工件形状校验，fail-closed 信息更精确；但绝不创建 session。
+        if (!verifyHandoffPackageDigest(pkg)) {
+            return { status: "fail_closed", reason: "createSession rejected: invalid handoff package" };
+        }
+        return { status: "fail_closed", reason: NOT_CONFIGURED_REASON };
+    }
+    getSession(ref) {
+        return {
+            status: "fail_closed",
+            reason: `${SESSION_NOT_CONFIGURED}: ${ref}`,
+        };
+    }
+    updateSession(ref, _terms) {
+        return {
+            status: "fail_closed",
+            reason: `${SESSION_NOT_CONFIGURED}: ${ref}`,
+        };
+    }
+    requestCompletion(ref, _authorization) {
+        return {
+            status: "fail_closed",
+            reason: `${NOT_CONFIGURED_REASON}; cannot complete checkout session ${ref}`,
+        };
+    }
+    cancelSession(ref) {
+        return {
+            status: "fail_closed",
+            reason: `${SESSION_NOT_CONFIGURED}: ${ref}`,
+        };
+    }
+}
+//# sourceMappingURL=acp-commerce.js.map

package/dist/handoff/acp-commerce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"acp-commerce.js","sourceRoot":"","sources":["../../src/handoff/acp-commerce.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAsBH,OAAO,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAG1D,gDAAgD;AAChD,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,cAAc,CAAU,CAAC;AASrE,MAAM,qBAAqB,GACzB,4FAA4F;IAC5F,6DAA6D,CAAC;AAEhE,MAAM,sBAAsB,GAAG,4DAA4D,CAAC;AAE5F;;;GAGG;AACH,MAAM,OAAO,kBAAkB;IAC7B,YAAY,WAAsC,EAAE;QAClD,oDAAoD;IACtD,CAAC;IAED,+CAA+C;IAC/C,IAAI,UAAU;QACZ,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,MAAM;QACR,OAAO,cAAc,CAAC;IACxB,CAAC;IAED,aAAa,CAAC,GAAmB;QAC/B,kDAAkD;QAClD,IAAI,CAAC,0BAA0B,CAAC,GAAG,CAAC,EAAE,CAAC;YACrC,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,iDAAiD,EAAE,CAAC;QAC9F,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,qBAAqB,EAAE,CAAC;IAClE,CAAC;IAED,UAAU,CAAC,GAAW;QACpB,OAAO;YACL,MAAM,EAAE,aAAa;YACrB,MAAM,EAAE,GAAG,sBAAsB,KAAK,GAAG,EAAE;SAC5C,CAAC;IACJ,CAAC;IAED,aAAa,CAAC,GAAW,EAAE,MAAe;QACxC,OAAO;YACL,MAAM,EAAE,aAAa;YACrB,MAAM,EAAE,GAAG,sBAAsB,KAAK,GAAG,EAAE;SAC5C,CAAC;IACJ,CAAC;IAED,iBAAiB,CAAC,GAAW,EAAE,cAAoC;QACjE,OAAO;YACL,MAAM,EAAE,aAAa;YACrB,MAAM,EAAE,GAAG,qBAAqB,sCAAsC,GAAG,EAAE;SAC5E,CAAC;IACJ,CAAC;IAED,aAAa,CAAC,GAAW;QACvB,OAAO;YACL,MAAM,EAAE,aAAa;YACrB,MAAM,EAAE,GAAG,sBAAsB,KAAK,GAAG,EAAE;SAC5C,CAAC;IACJ,CAAC;CACF"}

package/dist/handoff/authorization.d.ts

@@ -0,0 +1,127 @@
+/**
+ * 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";
+/** 用户显式授权确认的证据来源。 */
+export declare const CONFIRMATION_EVIDENCE_KINDS: readonly ["manual", "ap2"];
+export type ConfirmationEvidenceKind = (typeof CONFIRMATION_EVIDENCE_KINDS)[number];
+/** 用户显式授权确认的证据：authorization 必须绑定它。 */
+export interface UserConfirmationEvidence {
+    /** manual=操作者审批；ap2=真实 AP2 返回的确认回执。 */
+    kind: ConfirmationEvidenceKind;
+    /** 证据引用（如审批单号 / AP2 confirmation id），opaque。 */
+    reference: string;
+    /** 用户确认发生时间，RFC 3339。 */
+    confirmed_at: string;
+}
+export interface UserConfirmationEvidenceInput {
+    kind: ConfirmationEvidenceKind;
+    reference: string;
+    confirmed_at?: string;
+}
+/** 构造并校验用户确认证据（confirmed_at 缺省用 now）。 */
+export declare function createUserConfirmationEvidence(input: UserConfirmationEvidenceInput, now?: () => string): UserConfirmationEvidence;
+/**
+ * 完成门禁输入的唯一授权对象。三个绑定缺一不可：
+ *   session_ref   —— 授权只对这一个 session 有效（换 session 即失效）；
+ *   terms_digest  —— 授权只对这一个 terms 内容有效（换 terms 即失效）；
+ *   evidence      —— 用户显式确认证据（无人确认即不是授权）。
+ * intent_mandate 是 AP2 侧 mandate 引用；authorizeCheckout 前必须经 provider
+ * verifyIntentMandate 复核。
+ */
+export interface PaymentAuthorization {
+    authorization_id: string;
+    session_ref: string;
+    terms_digest: string;
+    intent_mandate: string;
+    evidence: UserConfirmationEvidence;
+    approved_at: string;
+    /** 授权有效期终点：过期即 stale（完成门禁第 3 步）。 */
+    expires_at: string;
+}
+export interface PaymentAuthorizationInput {
+    authorization_id: string;
+    session_ref: string;
+    terms_digest: string;
+    intent_mandate: string;
+    evidence: UserConfirmationEvidence;
+    approved_at?: string;
+    expires_at?: string;
+    /** 缺省有效期长度（毫秒）；缺省 30 分钟。 */
+    ttl_ms?: number;
+}
+/** 新授权 id：`authz_<uuidv7>`。 */
+export declare function newAuthorizationId(): string;
+/** 构造并校验 PaymentAuthorization。缺省 approved_at=now、expires_at=now+ttl_ms。 */
+export declare function createPaymentAuthorization(input: PaymentAuthorizationInput, now?: () => string): PaymentAuthorization;
+export interface CreateIntentMandateInput {
+    session_ref: string;
+    terms_digest: string;
+    terms: TermSet;
+}
+export type CreateIntentMandateResult = {
+    status: "ok";
+    intent_mandate: string;
+} | {
+    status: "fail_closed";
+    reason: string;
+} | {
+    status: "requires_user";
+    continue_url?: string;
+    reason: string;
+};
+export interface VerifyIntentMandateInput {
+    session_ref: string;
+    terms_digest: string;
+}
+export interface VerifyIntentMandateResult {
+    verified: boolean;
+    reason?: string;
+}
+export interface AuthorizeCheckoutInput {
+    session_ref: string;
+    terms_digest: string;
+    intent_mandate: string;
+    evidence: UserConfirmationEvidence;
+}
+export type AuthorizeCheckoutResult = {
+    status: "ok";
+    authorization: PaymentAuthorization;
+} | {
+    status: "fail_closed";
+    reason: string;
+};
+/**
+ * AP2 适配接缝（基线 §43 / docs §29）。实现方 = 外部支付/checkout 系统适配器；
+ * Kiwi 侧只消费结构化结果，绝不伪造授权。
+ */
+export interface AuthorizationProvider {
+    createIntentMandate(input: CreateIntentMandateInput): CreateIntentMandateResult;
+    verifyIntentMandate(intent_mandate: string, input: VerifyIntentMandateInput): VerifyIntentMandateResult;
+    authorizeCheckout(input: AuthorizeCheckoutInput): AuthorizeCheckoutResult;
+}
+/**
+ * fail-closed 默认实现。任何真实授权动作都拒绝：
+ *   createIntentMandate → requires_user（无 AP2 时只有人能继续，绝不伪造 mandate）；
+ *   verifyIntentMandate → verified:false；
+ *   authorizeCheckout   → fail_closed。
+ */
+export declare class FailClosedAuthorizationProvider implements AuthorizationProvider {
+    createIntentMandate(_input: CreateIntentMandateInput): CreateIntentMandateResult;
+    verifyIntentMandate(_intent_mandate: string, _input: VerifyIntentMandateInput): VerifyIntentMandateResult;
+    authorizeCheckout(_input: AuthorizeCheckoutInput): AuthorizeCheckoutResult;
+}
+/** terms 的 digest 便捷函数（构造 Authorization 时用）。 */
+export declare function digestTerms(terms: TermSet): string;

package/dist/handoff/authorization.js

@@ -0,0 +1,107 @@
+/**
+ * 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 — AuthorizationProvider（AP2 边界，WP1）。
+ *
+ * 基线 §43 / docs/kiwi_a2a_v1.md §29 预留给 AuthorizationProvider 的 AP2 接缝：
+ * Kiwi 不实现真实 AP2（外部系统），只定义适配边界，并提供一个 fail-closed 默认
+ * 实现（FailClosedAuthorizationProvider）——未配置真实 AP2 时：
+ *   - createIntentMandate  → requires_user（把人导向外部 checkout，绝不伪造 mandate）；
+ *   - verifyIntentMandate  → verified:false（绝不认可任何 mandate）；
+ *   - authorizeCheckout    → fail_closed（绝不伪造 checkout 授权）。
+ *
+ * PaymentAuthorization 必须绑定 terms_digest + session_ref + 用户确认证据，
+ * 防止「授权被挪用到别的 terms / 别的 session」。完成门禁（completion.ts）在
+ * complete 前复核这三个绑定。
+ */
+import { requireDigest, requireIsoTimestamp, requireNonEmptyString, } from "../negotiation/domain/common.js";
+import { uuidv7, validateIdentifier } from "../negotiation/domain/identifiers.js";
+import { contentDigest } from "../negotiation/jcs.js";
+import { HandoffError } from "./errors.js";
+// ---------------------------------------------------------------------------
+// 用户确认证据
+// ---------------------------------------------------------------------------
+/** 用户显式授权确认的证据来源。 */
+export const CONFIRMATION_EVIDENCE_KINDS = ["manual", "ap2"];
+/** 构造并校验用户确认证据（confirmed_at 缺省用 now）。 */
+export function createUserConfirmationEvidence(input, now = () => new Date().toISOString()) {
+    if (!CONFIRMATION_EVIDENCE_KINDS.includes(input.kind)) {
+        throw new HandoffError("invalid_authorization", `evidence.kind must be one of ${CONFIRMATION_EVIDENCE_KINDS.join("|")}`, "evidence.kind");
+    }
+    const evidence = {
+        kind: input.kind,
+        reference: requireNonEmptyString(input.reference, "evidence.reference"),
+        confirmed_at: input.confirmed_at ?? now(),
+    };
+    requireIsoTimestamp(evidence.confirmed_at, "evidence.confirmed_at");
+    return evidence;
+}
+/** 新授权 id：`authz_<uuidv7>`。 */
+export function newAuthorizationId() {
+    return `authz_${uuidv7()}`;
+}
+/** 构造并校验 PaymentAuthorization。缺省 approved_at=now、expires_at=now+ttl_ms。 */
+export function createPaymentAuthorization(input, now = () => new Date().toISOString()) {
+    const approvedAt = input.approved_at ?? now();
+    requireIsoTimestamp(approvedAt, "approved_at");
+    const ttlMs = input.ttl_ms ?? 30 * 60 * 1000;
+    if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
+        throw new HandoffError("invalid_authorization", "ttl_ms must be a positive number", "ttl_ms");
+    }
+    const expiresAt = input.expires_at ?? new Date(new Date(approvedAt).getTime() + ttlMs).toISOString();
+    requireIsoTimestamp(expiresAt, "expires_at");
+    const authorization = {
+        authorization_id: validateIdentifier(input.authorization_id, "authorization_id"),
+        session_ref: validateIdentifier(input.session_ref, "session_ref"),
+        terms_digest: requireDigest(input.terms_digest, "terms_digest"),
+        intent_mandate: requireNonEmptyString(input.intent_mandate, "intent_mandate"),
+        evidence: input.evidence,
+        approved_at: approvedAt,
+        expires_at: expiresAt,
+    };
+    requireIsoTimestamp(authorization.evidence.confirmed_at, "evidence.confirmed_at");
+    // 数值比较（非字符串）：RFC 3339 允许带时区偏移，字符串比较跨时区会
+    // fail-open（如 confirmed_at 带 -08:00 偏移时事后补签可通过）。NaN 视为非法。
+    const confirmedMs = Date.parse(authorization.evidence.confirmed_at);
+    const approvedMs = Date.parse(authorization.approved_at);
+    if (!Number.isFinite(confirmedMs) || !Number.isFinite(approvedMs) || confirmedMs > approvedMs) {
+        throw new HandoffError("invalid_authorization", "evidence.confirmed_at MUST NOT be after approved_at (evidence must precede approval)", "evidence.confirmed_at");
+    }
+    return authorization;
+}
+const NO_AP2_REASON = "no_ap2_configured: Kiwi is not configured with a real AP2/checkout provider; refusing to fabricate any authorization";
+/**
+ * fail-closed 默认实现。任何真实授权动作都拒绝：
+ *   createIntentMandate → requires_user（无 AP2 时只有人能继续，绝不伪造 mandate）；
+ *   verifyIntentMandate → verified:false；
+ *   authorizeCheckout   → fail_closed。
+ */
+export class FailClosedAuthorizationProvider {
+    createIntentMandate(_input) {
+        return { status: "requires_user", reason: NO_AP2_REASON };
+    }
+    verifyIntentMandate(_intent_mandate, _input) {
+        return { verified: false, reason: NO_AP2_REASON };
+    }
+    authorizeCheckout(_input) {
+        return { status: "fail_closed", reason: NO_AP2_REASON };
+    }
+}
+/** terms 的 digest 便捷函数（构造 Authorization 时用）。 */
+export function digestTerms(terms) {
+    return contentDigest(terms);
+}
+//# sourceMappingURL=authorization.js.map

package/dist/handoff/authorization.js.map

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

package/dist/handoff/candidate.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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 DestinationType } from "./destination.js";
+/** 展示摘要（KTH §6 display_summary；完成定义 #17 用户可见目标与摘要）。 */
+export interface HandoffDisplaySummary {
+    readonly merchant: string;
+    readonly summary: string;
+}
+/**
+ * HandoffCandidate（KTH rev0.3 §5）。全部字段 readonly —— 类型层面不可变。
+ */
+export interface HandoffCandidate {
+    readonly handoff_candidate_id: string;
+    /** 被本候选取代的旧候选（stale 后新建候选的审计链接，§5.1）。 */
+    readonly supersedes_candidate_id?: string;
+    readonly agreement_id: string;
+    readonly negotiation_id: string;
+    readonly terms_digest: string;
+    readonly buyer_identity_ref: string;
+    readonly merchant_identity_ref: string;
+    readonly destination_type: DestinationType;
+    readonly destination_ref: string;
+    /** 最小化、schema-validated、非秘密目的地载荷（KTH §11.3）。 */
+    readonly destination_payload?: Readonly<Record<string, unknown>>;
+    readonly display_summary: HandoffDisplaySummary;
+    readonly policy_version: string;
+    readonly expires_at: string;
+    readonly requires_user_action: boolean;
+    /** KTH/1.0 三副作用不变量：恒为 false（§16 Agreement 约束）。 */
+    readonly creates_order: false;
+    readonly authorizes_payment: false;
+    readonly reserves_inventory: false;
+    readonly candidate_digest: string;
+    readonly created_at: string;
+}
+/** 创建输入：agreement 溯源 + 目的地 + 策略元数据。 */
+export interface HandoffCandidateInput {
+    /** 产生本候选的 agreement 的 id。 */
+    agreement_id: string;
+    /** 产生本候选的 negotiation 的 id。 */
+    negotiation_id: string;
+    /** 已谈妥的条款对象（用于重算 terms_digest；缺省用 terms_digest 原值）。 */
+    agreed_terms?: unknown;
+    /** 期望的 terms_digest；与 agreed_terms 重算值不一致 → 校验失败。 */
+    terms_digest?: string;
+    buyer_identity_ref?: string;
+    merchant_identity_ref?: string;
+    destination: {
+        type: DestinationType;
+        ref: string;
+        payload?: Record<string, unknown>;
+    };
+    display_summary: HandoffDisplaySummary;
+    policy_version: string;
+    /** RFC 3339 过期时间（KTH §10 重验的一部分）。 */
+    expires_at: string;
+    requires_user_action?: boolean;
+    /** 取代的旧候选 id（stale 审计链接）。 */
+    supersedes_candidate_id?: string;
+    created_at?: string;
+}
+/** 类型守卫。 */
+export declare function isHandoffCandidate(value: unknown): value is HandoffCandidate;
+/** 计算 candidate_digest：candidate 去除 candidate_digest 后 JCS+SHA-256。 */
+export declare function computeCandidateDigest(candidate: Readonly<HandoffCandidate>): string;
+/** 校验 candidate_digest 与内容自洽。 */
+export declare function verifyHandoffCandidateDigest(candidate: HandoffCandidate): boolean;
+/**
+ * 构造即校验（KTH §5）：agreement 绑定、terms_digest 一致性（提供
+ * agreed_terms 时重算比对）、destination 校验、三 false 不变量、标识符
+ * 与时间戳校验。返回不可变候选（防御拷贝）。
+ */
+export declare function createHandoffCandidate(input: HandoffCandidateInput): HandoffCandidate;
+/**
+ * 校验并重建一个候选对象（Ledger 事件重建，§18-13）。
+ *
+ * 保留输入的 handoff_candidate_id 与 candidate_digest（不重新生成）：
+ * 字段校验复用 createHandoffCandidate 的规则，然后以输入 id 覆盖，
+ * 再核对 digest（提供 digest 时）或按内容重算（缺省时）。
+ */
+export declare function validateHandoffCandidate(value: unknown, path?: string): HandoffCandidate;