@harrylabsj/kiwi 0.6.0

package/dist/a2a/server/pipeline.js

@@ -0,0 +1,329 @@
+/**
+ * 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.
+ */
+/**
+ * 入站 message/send 处理管线（WP2 核心，子规范 §24 / §20 / §28）。
+ *
+ * 顺序（全部 fail-closed）：
+ *   1. 严格解析入站 A2A Message（inbound-message.ts）——失败 → schema_invalid；
+ *   2. 提取 KNP envelope（Data Part 的 `knp_envelope`）——失败 → schema_invalid；
+ *   3. validateEnvelope（schema / version / action-payload 匹配）——失败 →
+ *      NegotiationValidationError.code 映射（未知版本 → protocol_version_unsupported）；
+ *   4. verifyEnvelopeDigest——不一致 → schema_invalid（完整性失败，§19.2）；
+ *   5. 协议幂等 check（(sender_identity, message_id)，§20）——同 key 同 digest →
+ *      返回原结果；同 key 异 digest → idempotency_conflict；
+ *   6. 串行锁（按幂等键）内重新 check（并发兜底），调用 NegotiationHandler；
+ *   7. 生成 A2A Task、落 Ledger（message_received 事件，含 handler 结果证据）、
+ *      幂等 commit（携带 ledger_event_id/digest 交叉引用，§22）。
+ *
+ * 入站内容永不触发本地工具、永不写入 Principal Memory（基线 §4.5 / §36-11/13）；
+ * handler 异常与 ledger 异常都收敛为通用内部错误，不泄漏内部细节。
+ */
+import { uuidv7 } from "../../negotiation/domain/identifiers.js";
+import { NegotiationValidationError } from "../../negotiation/domain/common.js";
+import { validateEnvelope, verifyEnvelopeDigest } from "../../negotiation/domain/envelope.js";
+import { IdempotencyConflictError, idempotencyKey } from "../../negotiation/idempotency/index.js";
+import { LedgerError, LedgerStore } from "../../negotiation/ledger/index.js";
+import { extractKnpEnvelope, parseInboundMessage } from "./inbound-message.js";
+import { fromNegotiationError, internalServerError, protocolCodeOf, protocolError, rateLimited, schemaInvalid, } from "./errors.js";
+import { A2AServerThrottle, domainFromUcpProfile } from "./throttle.js";
+import { isKnownTaskState, newArtifactId, newTaskId, TaskRegistry } from "./task-registry.js";
+// ---------------------------------------------------------------------------
+// 按幂等键串行化：防止并发同 key 请求双执行 handler
+// ---------------------------------------------------------------------------
+const locks = new Map();
+async function withKeyLock(key, fn) {
+    const tail = locks.get(key) ?? Promise.resolve();
+    let release;
+    const myTurn = new Promise((resolve) => {
+        release = resolve;
+    });
+    const chained = tail.then(() => myTurn);
+    locks.set(key, chained);
+    await tail;
+    try {
+        return await fn();
+    }
+    finally {
+        release();
+        if (locks.get(key) === chained)
+            locks.delete(key);
+    }
+}
+// ---------------------------------------------------------------------------
+// Task 构造 / 幂等结果还原
+// ---------------------------------------------------------------------------
+function validateTaskState(value) {
+    if (value === undefined)
+        return "completed";
+    if (!isKnownTaskState(value)) {
+        throw internalServerError();
+    }
+    return value;
+}
+/** 由 handler 结果构造 A2ATask。仅 accepted / declined 进入此路径（error 已提前抛）。 */
+function buildTask(result, ctx, now) {
+    if (result.kind === "error") {
+        // 防御性：pipeline 在 handlerResult.kind === "error" 时已抛协议错误，不应走到这里。
+        throw internalServerError();
+    }
+    const state = validateTaskState(result.taskState);
+    const task = { id: ctx.taskId, status: { state, timestamp: now() } };
+    if (ctx.contextId !== undefined)
+        task.contextId = ctx.contextId;
+    let message;
+    if (result.kind === "accepted") {
+        message = result.message;
+        if (result.artifactParts !== undefined) {
+            task.artifacts = [{ artifactId: newArtifactId(), parts: result.artifactParts }];
+        }
+    }
+    else {
+        message = {
+            role: "agent",
+            parts: [
+                {
+                    kind: "data",
+                    data: { decline: true, reason_code: result.reasonCode ?? "declined" },
+                },
+            ],
+            messageId: `msg_${uuidv7()}`,
+        };
+    }
+    if (message !== undefined)
+        task.status.message = message;
+    return task;
+}
+function isTaskLike(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const obj = value;
+    if (typeof obj.id !== "string" || obj.id.length === 0)
+        return false;
+    if (obj.status === null || typeof obj.status !== "object")
+        return false;
+    const status = obj.status;
+    return isKnownTaskState(status.state);
+}
+/** 幂等重放：从已落账 outcome 还原原结果 task。 */
+function outcomeToTask(outcome) {
+    if (outcome.kind !== "ok" || outcome.result === undefined) {
+        throw internalServerError();
+    }
+    const record = outcome.result;
+    const task = record["task"];
+    if (!isTaskLike(task))
+        throw internalServerError();
+    return task;
+}
+// ---------------------------------------------------------------------------
+// InboundPipeline
+// ---------------------------------------------------------------------------
+export class InboundPipeline {
+    handler;
+    idempotency;
+    ledger;
+    tasks;
+    now;
+    logError;
+    throttle;
+    constructor(options) {
+        this.handler = options.handler;
+        this.idempotency = options.idempotency;
+        this.ledger = options.ledger;
+        this.tasks = options.tasks;
+        this.now = options.now;
+        this.logError = options.logError;
+        this.throttle = options.throttle;
+    }
+    toThrottleRequest(caller) {
+        return {
+            identity: caller.senderIdentity,
+            remoteAddress: caller.remoteAddress,
+            domain: domainFromUcpProfile(caller.ucpAgentProfile),
+            identityVerified: caller.identityVerified,
+            trustLevel: caller.trustLevel,
+            fingerprintChanged: caller.fingerprintChanged,
+        };
+    }
+    /** message/send 入站处理（限流 → 校验 → 幂等 → handler → Ledger → 幂等 commit）。 */
+    async sendMessage(input, caller) {
+        // 惰性清理（评审项 L2）：negotiation 幂等文件的 sweep 此前无调用方，
+        // 过期行永久保留、磁盘无界增长。入站消息处理是低频操作，顺带清理。
+        try {
+            this.idempotency.sweep();
+        }
+        catch {
+            // 清理失败不影响消息处理（fail-safe 方向；下次再试）。
+        }
+        // 0. WP3 §31 反滥用：认证之后、schema 校验之前的限流判定（fail-closed）。
+        const th = this.throttle;
+        const tReq = th === undefined ? undefined : this.toThrottleRequest(caller);
+        if (th !== undefined && tReq !== undefined) {
+            const decision = th.check(tReq);
+            if (!decision.allowed) {
+                throw rateLimited(decision.retryAfterSeconds, decision.reason);
+            }
+            const slot = th.enterTask(tReq);
+            if (!slot.ok) {
+                throw rateLimited(slot.retryAfterSeconds, slot.reason);
+            }
+        }
+        try {
+            // 1-2. A2A Message schema + KNP envelope 提取（untrusted，fail-closed）。
+            const message = parseInboundMessage(input.message);
+            const contextId = input.contextId === undefined ? message.contextId : requireContextId(input.contextId);
+            const envelopeRaw = extractKnpEnvelope(message);
+            // 3. KNP envelope schema / version / action-payload 校验。
+            let envelope;
+            try {
+                envelope = validateEnvelope(envelopeRaw);
+            }
+            catch (err) {
+                if (err instanceof NegotiationValidationError)
+                    throw fromNegotiationError(err);
+                throw err;
+            }
+            // 4. wire digest 一致性（完整性，§19.2）。
+            if (!verifyEnvelopeDigest(envelope)) {
+                throw schemaInvalid("envelope digest mismatch (wire digest does not match content)");
+            }
+            const senderIdentity = caller.senderIdentity;
+            const key = idempotencyKey(senderIdentity, envelope.message_id);
+            return await withKeyLock(key, async () => {
+                // 5. 幂等三态判定（锁内重新判定，防 check/commit 并发窗口）。
+                const decision = this.idempotency.check({
+                    sender_identity: senderIdentity,
+                    message_id: envelope.message_id,
+                    digest: envelope.digest,
+                });
+                if (decision.status === "replayed") {
+                    return { task: outcomeToTask(decision.record.outcome) };
+                }
+                if (decision.status === "conflict") {
+                    throw protocolError("idempotency_conflict", `message_id ${envelope.message_id} already processed with a different digest (replay conflict, §20.3)`);
+                }
+                // 6. 路由给 NegotiationHandler。
+                const taskId = newTaskId();
+                const handlerCtx = {
+                    envelope,
+                    message,
+                    taskId,
+                    contextId,
+                    senderIdentity,
+                    remoteAddress: caller.remoteAddress,
+                    ucpAgentProfile: caller.ucpAgentProfile,
+                };
+                let handlerResult;
+                try {
+                    handlerResult = await this.handler.handle(handlerCtx);
+                }
+                catch (err) {
+                    this.logError(`negotiation handler "${this.handler.name}" failed`, err);
+                    throw internalServerError();
+                }
+                if (handlerResult.kind === "error") {
+                    throw protocolError(handlerResult.protocolCode, handlerResult.message);
+                }
+                // 7. 生成任务 → 落 Ledger → 幂等 commit（证据交叉引用）。
+                const task = buildTask(handlerResult, handlerCtx, this.now);
+                this.tasks.set(taskId, task);
+                let ledgerEvent;
+                try {
+                    ledgerEvent = this.ledger.append({
+                        event_kind: "message_received",
+                        negotiation_id: envelope.negotiation_id,
+                        exchange_id: envelope.exchange_id,
+                        message_id: envelope.message_id,
+                        in_reply_to: envelope.in_reply_to,
+                        remote_context_id: contextId,
+                        remote_task_id: taskId,
+                        identity: {
+                            sender_identity: senderIdentity,
+                            // 验签身份已给出时，counterparty 侧优先用验签身份（与 buyer 侧
+                            // 记录对称，基线 §22）；无验签身份（匿名/loopback/静态 bearer）才
+                            // 回退 socket 地址 —— 此时身份不足以标识对端，地址是仅有的区分面。
+                            counterparty_identity: caller.identityVerified === true
+                                ? senderIdentity
+                                : (caller.remoteAddress ?? senderIdentity),
+                            actor: envelope.actor,
+                        },
+                        capability: {
+                            capability: envelope.capability,
+                            protocol_version: envelope.protocol_version,
+                        },
+                        wire_digest: envelope.digest,
+                        wire_payload: envelope,
+                        outcome: { kind: "ok", result: { task_id: taskId, task_state: task.status.state } },
+                        occurred_at: envelope.created_at,
+                    });
+                }
+                catch (err) {
+                    if (err instanceof LedgerError && err.code === "ledger_forbidden_content") {
+                        // 内容策略违规：envelope 携带 ledger 不得记录的保留键（§28/§36-5）。
+                        throw schemaInvalid("envelope contains reserved content that must not be recorded");
+                    }
+                    this.logError("ledger append failed", err);
+                    throw internalServerError();
+                }
+                try {
+                    this.idempotency.commit({
+                        sender_identity: senderIdentity,
+                        message_id: envelope.message_id,
+                        digest: envelope.digest,
+                        negotiation_id: envelope.negotiation_id,
+                        outcome: { kind: "ok", result: { task } },
+                        ledger_event_id: ledgerEvent.event_id,
+                        ledger_event_digest: ledgerEvent.event_digest,
+                    });
+                }
+                catch (err) {
+                    // commit 的并发兜底（异 digest）——本锁内不应发生；仍 fail-closed。
+                    if (err instanceof IdempotencyConflictError) {
+                        throw protocolError("idempotency_conflict", `message_id ${envelope.message_id} already processed with a different digest`);
+                    }
+                    throw err;
+                }
+                return { task, ledgerEvent };
+            });
+        }
+        catch (err) {
+            // schema_invalid 计入 malformed budget（独立于正常限流；WP3 §31）。
+            if (th !== undefined && tReq !== undefined && protocolCodeOf(err) === "schema_invalid") {
+                th.recordMalformed(tReq);
+            }
+            throw err;
+        }
+        finally {
+            // 释放并发槽（幂等；与限流判定中的 enterTask 配对）。
+            if (th !== undefined && tReq !== undefined)
+                th.leaveTask(tReq);
+        }
+    }
+    /** tasks/get：内存优先，miss 时回退 Ledger 视图（§23 恢复第 4 步）。 */
+    async getTask(taskId) {
+        const inMemory = this.tasks.get(taskId);
+        if (inMemory !== null)
+            return inMemory;
+        return this.tasks.resolveFromLedger(this.ledger, taskId);
+    }
+}
+function requireContextId(value) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw schemaInvalid("params/contextId must be a non-empty string");
+    }
+    return value;
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/a2a/server/pipeline.js.map

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

package/dist/a2a/server/server.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 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.
+ */
+/**
+ * A2A Server（入站侧，WP2）node:http 实现。零新增依赖。
+ *
+ * 端点面：
+ *   GET  {wellKnownPath}   Agent Card（基线 §26 / 子规范 §24.1），默认
+ *                          `/.well-known/agent-card.json`；
+ *   POST {a2aPath}         JSON-RPC A2A endpoint（默认 "/"）：message/send、
+ *                          tasks/get；其他 method → -32601。
+ *
+ * 请求路径顺序（全部 fail-closed）：
+ *   1. 路由 → 2. 认证（AuthVerifier 接缝，缺省 loopback-only）→
+ *   3. body 大小上限（默认 1 MiB）→ 4. JSON 解析（失败 400）→
+ *   5. JSON-RPC 帧校验（失败 400）→ 6. method 分发 → 7. InboundPipeline。
+ *
+ * 内部异常一律收敛为通用 "internal error"（-32603），绝不把 handler / ledger 的
+ * 内部细节回显给远端（基线 §4.5 / §36-11）。
+ */
+import http from "node:http";
+import type { A2AServerOptions } from "./types.js";
+export declare class A2AServer {
+    private readonly cardConfig;
+    private readonly authVerifier;
+    private readonly maxPayloadBytes;
+    private readonly now;
+    private readonly wellKnownPath;
+    private readonly ucpOptions;
+    private readonly pipeline;
+    private readonly throttle;
+    constructor(options: A2AServerOptions);
+    private logError;
+    /** 返回 node:http request listener。 */
+    handler(): (req: http.IncomingMessage, res: http.ServerResponse) => void;
+    /** 创建并返回绑定本 handler 的 node:http server。 */
+    createServer(): http.Server;
+    private handleRequest;
+    private authenticate;
+    private handleWellKnown;
+    /**
+     * UCP Profile 端点（WP3）：GET /.well-known/ucp。
+     * 响应头 Cache-Control: public, max-age=N（N>=60，UCP 规范强制）；
+     * 内容由 buildUcpProfile 强制过 validate 自洽（fail-closed）。
+     */
+    private handleUcp;
+    private handleA2a;
+    private toJsonRpcErrorBody;
+    private dispatch;
+    private handleMessageSend;
+    private handleTasksGet;
+}