@harrylabsj/kiwi 0.6.0

package/dist/trust/identity/jws.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.
+ */
+/**
+ * Compact JWS 验签（EdDSA / ES256）与 Agent Card JWS 绑定验证（基线 §27 / §31）。
+ *
+ * - `verifyCompactJws`：RFC 7515 compact 形态 `header.payload.signature`
+ *   （各段 base64url）。EdDSA → Ed25519；ES256 → P-256 + SHA-256（原始 r||s）。
+ * - `verifyAgentCardJws`：JWS 负载必须是该 Agent Card 的规范化 JSON；比较用
+ *   JCS（RFC 8785），因此 key 顺序 / 可选字段缺省不影响比对。
+ *
+ * 是否强制 JWS 由 TrustPolicy.requireCardJws(level) 决定（§31），本模块只提供
+ * 「验签 + 卡片绑定」能力，不做强制决策。
+ */
+import { KeyObject, type JsonWebKey } from "node:crypto";
+import type { AgentCard } from "../../discovery/agent-card/index.js";
+import { type KeyResolver, type SigningKey } from "./keys.js";
+export type JwsErrorCode = "malformed" | "unsupported_algorithm" | "missing_key" | "invalid_signature";
+export declare class JwsError extends Error {
+    readonly code: JwsErrorCode;
+    constructor(code: JwsErrorCode, message: string);
+}
+export interface VerifiedJws {
+    /** 解码后的 JWS header。 */
+    header: Record<string, unknown>;
+    /** 解码后的负载字节。 */
+    payload: Buffer;
+    /** alg 值（EdDSA | ES256）。 */
+    alg: string;
+    /** header.kid（如有）。 */
+    keyid?: string;
+}
+/**
+ * 验签一个 compact JWS。publicKey 可以是 SigningKey（推荐，算法自动取）、
+ * JsonWebKey 或 KeyObject。
+ */
+export declare function verifyCompactJws(jws: string, publicKey: SigningKey | JsonWebKey | KeyObject): VerifiedJws;
+/** 读取 compact JWS 的 kid（不验签）；畸形返回 undefined。 */
+export declare function jwsKid(jws: string): string | undefined;
+export type AgentCardJwsResult = {
+    ok: true;
+    keyid?: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * 验证「Agent Card + 其 JWS」绑定：JWS 验签通过，且 JWS 负载规范化后与该
+ * card 一致。card 必须先过 parseAgentCard（结构校验 + secret 扫描）；负载经
+ * parseAgentCard 归一后再比对，双方都过 JCS。
+ */
+export declare function verifyAgentCardJws(card: AgentCard, jws: string, resolver: KeyResolver): AgentCardJwsResult;

package/dist/trust/identity/jws.js

@@ -0,0 +1,178 @@
+/**
+ * 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.
+ */
+/**
+ * Compact JWS 验签（EdDSA / ES256）与 Agent Card JWS 绑定验证（基线 §27 / §31）。
+ *
+ * - `verifyCompactJws`：RFC 7515 compact 形态 `header.payload.signature`
+ *   （各段 base64url）。EdDSA → Ed25519；ES256 → P-256 + SHA-256（原始 r||s）。
+ * - `verifyAgentCardJws`：JWS 负载必须是该 Agent Card 的规范化 JSON；比较用
+ *   JCS（RFC 8785），因此 key 顺序 / 可选字段缺省不影响比对。
+ *
+ * 是否强制 JWS 由 TrustPolicy.requireCardJws(level) 决定（§31），本模块只提供
+ * 「验签 + 卡片绑定」能力，不做强制决策。
+ */
+import { createPublicKey, KeyObject, verify as nodeVerify } from "node:crypto";
+import { parseAgentCard } from "../../discovery/agent-card/index.js";
+import { canonicalize } from "../../negotiation/jcs.js";
+import { publicKeyObject } from "./keys.js";
+export class JwsError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "JwsError";
+        this.code = code;
+    }
+}
+function malformed(detail) {
+    return new JwsError("malformed", `malformed compact JWS: ${detail}`);
+}
+function base64urlToBuffer(value, what) {
+    if (!/^[A-Za-z0-9_-]*$/.test(value))
+        throw malformed(`${what} is not base64url`);
+    return Buffer.from(value, "base64url");
+}
+/**
+ * 验签一个 compact JWS。publicKey 可以是 SigningKey（推荐，算法自动取）、
+ * JsonWebKey 或 KeyObject。
+ */
+export function verifyCompactJws(jws, publicKey) {
+    const parts = jws.split(".");
+    if (parts.length !== 3)
+        throw malformed("must have exactly 3 segments");
+    const headerSegment = parts[0] ?? "";
+    const payloadSegment = parts[1] ?? "";
+    const signatureSegment = parts[2] ?? "";
+    const headerBytes = base64urlToBuffer(headerSegment, "header");
+    let header;
+    try {
+        header = JSON.parse(headerBytes.toString("utf8"));
+    }
+    catch {
+        throw malformed("header is not valid JSON");
+    }
+    if (header === null || typeof header !== "object" || Array.isArray(header)) {
+        throw malformed("header must be a JSON object");
+    }
+    const headerRecord = header;
+    if (typeof headerRecord.alg !== "string" || headerRecord.alg.length === 0) {
+        throw malformed("header has no alg");
+    }
+    const alg = headerRecord.alg;
+    const keyid = typeof headerRecord.kid === "string" ? headerRecord.kid : undefined;
+    const payload = base64urlToBuffer(payloadSegment, "payload");
+    const signature = base64urlToBuffer(signatureSegment, "signature");
+    const signingInput = Buffer.from(`${headerSegment}.${payloadSegment}`, "utf8");
+    const key = resolveJwsKey(publicKey, alg);
+    if (!verifyJwsSignature(alg, signingInput, signature, key)) {
+        throw new JwsError("invalid_signature", "JWS signature verification failed");
+    }
+    return { header: headerRecord, payload, alg, keyid };
+}
+function resolveJwsKey(publicKey, alg) {
+    if (publicKey instanceof KeyObject)
+        return publicKey;
+    if (typeof publicKey === "object" && "keyid" in publicKey && "algorithm" in publicKey) {
+        const key = publicKey;
+        if (key.algorithm !== jwsAlgToSignatureAlgorithm(alg)) {
+            throw new JwsError("unsupported_algorithm", `JWS alg ${alg} does not match key algorithm ${key.algorithm}`);
+        }
+        return publicKeyObject(key);
+    }
+    const jwk = publicKey;
+    if (jwk.kty === "OKP" && jwk.crv === "Ed25519" && alg !== "EdDSA") {
+        throw new JwsError("unsupported_algorithm", `key is Ed25519 but JWS alg is ${alg}`);
+    }
+    if (jwk.kty === "EC" && jwk.crv === "P-256" && alg !== "ES256") {
+        throw new JwsError("unsupported_algorithm", `key is P-256 but JWS alg is ${alg}`);
+    }
+    return createPublicKey({ key: jwk, format: "jwk" });
+}
+function jwsAlgToSignatureAlgorithm(alg) {
+    if (alg === "EdDSA")
+        return "ed25519";
+    if (alg === "ES256")
+        return "es256";
+    return undefined;
+}
+function verifyJwsSignature(alg, signingInput, signature, key) {
+    switch (alg) {
+        case "EdDSA":
+            return nodeVerify(null, signingInput, key, signature);
+        case "ES256":
+            return nodeVerify("sha256", signingInput, { key, dsaEncoding: "ieee-p1363" }, signature);
+        default:
+            throw new JwsError("unsupported_algorithm", `unsupported JWS alg ${alg}`);
+    }
+}
+/** 读取 compact JWS 的 kid（不验签）；畸形返回 undefined。 */
+export function jwsKid(jws) {
+    const firstDot = jws.indexOf(".");
+    if (firstDot <= 0)
+        return undefined;
+    const headerSegment = jws.slice(0, firstDot);
+    let header;
+    try {
+        header = JSON.parse(base64urlToBuffer(headerSegment, "header").toString("utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (header === null || typeof header !== "object")
+        return undefined;
+    const kid = header.kid;
+    return typeof kid === "string" ? kid : undefined;
+}
+/**
+ * 验证「Agent Card + 其 JWS」绑定：JWS 验签通过，且 JWS 负载规范化后与该
+ * card 一致。card 必须先过 parseAgentCard（结构校验 + secret 扫描）；负载经
+ * parseAgentCard 归一后再比对，双方都过 JCS。
+ */
+export function verifyAgentCardJws(card, jws, resolver) {
+    const kid = jwsKid(jws);
+    const key = kid === undefined ? undefined : resolver(kid);
+    if (key === undefined) {
+        return { ok: false, reason: `no signing key for JWS kid "${kid ?? "(missing)"}"` };
+    }
+    let verified;
+    try {
+        verified = verifyCompactJws(jws, key);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            reason: err instanceof JwsError ? err.message : String(err),
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(verified.payload.toString("utf8"));
+    }
+    catch {
+        return { ok: false, reason: "JWS payload is not valid JSON" };
+    }
+    let normalized;
+    try {
+        normalized = parseAgentCard(parsed);
+    }
+    catch (err) {
+        return { ok: false, reason: `JWS payload is not a valid Agent Card: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    if (canonicalize(normalized) !== canonicalize(card)) {
+        return { ok: false, reason: "JWS payload does not match the presented Agent Card" };
+    }
+    return { ok: true, keyid: verified.keyid };
+}
+//# sourceMappingURL=jws.js.map

package/dist/trust/identity/jws.js.map

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

package/dist/trust/identity/keys.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 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.
+ */
+/**
+ * 签名密钥模型与 keyid → 公钥解析接缝。
+ *
+ * 两个来源（基线 §27 Identity Trust：HTTP Message Signatures / UCP signing keys）：
+ *   - `signing_keys` 本地配置信任锚：{ keyid, algorithm, publicKey, profile }；
+ *   - JWKS 接缝：{ keys: JsonWebKey[] }，kid → OKP(Ed25519) / EC(P-256)。
+ *
+ * 公钥材料三种等价形态：SPKI PEM、JWK、raw 字节（Ed25519=32B，P-256=64B
+ * 未压缩点 x||y）。`publicKeyObject` 归一为 node:crypto KeyObject 供验签。
+ * 私钥仅存在于出站签名器（signer.ts）；本模块不保存、不解析私钥除外的任何 secret。
+ */
+import { type JsonWebKey, type KeyObject } from "node:crypto";
+import type { TrustLevel } from "./trust-policy.js";
+/** 本实现支持的签名算法（RFC 9421 alg 名见 RFC9421_ALG_NAMES）。 */
+export type SignatureAlgorithm = "ed25519" | "es256";
+/** 与密钥绑定的身份档案（身份绑定冲突 → identity_rejected 的比对输入）。 */
+export interface KeyProfile {
+    /** 该 key 绑定的规范身份（幂等主键 sender 侧）。 */
+    identity?: string;
+    /** 组织名。 */
+    organization?: string;
+    /** KNP 角色（buyer|merchant）。 */
+    role?: "buyer" | "merchant";
+    /** 该密钥对应对端的信任等级。 */
+    trustLevel?: TrustLevel;
+}
+/** 一个签名密钥的验证方视图（只含公钥材料 + 绑定档案）。 */
+export interface SigningKey {
+    keyid: string;
+    algorithm: SignatureAlgorithm;
+    /** SPKI PEM 公钥。 */
+    publicKeyPem?: string;
+    /** raw 公钥：Ed25519=32B；P-256=64B（x||y 未压缩点）。 */
+    publicKeyRaw?: Buffer;
+    /** JWK 公钥。 */
+    jwk?: JsonWebKey;
+    /** 本地配置的信任档案。 */
+    profile?: KeyProfile;
+}
+/** keyid → 公钥。返回 undefined 表示未知 keyid（验证方不认识该签名者）。 */
+export type KeyResolver = (keyid: string) => SigningKey | undefined;
+/** 校验 raw 长度并按算法归一为 JWK。 */
+export declare function publicKeyJwkFromRaw(algorithm: SignatureAlgorithm, raw: Buffer): JsonWebKey;
+/** 把 SigningKey 归一为 node:crypto 公钥 KeyObject。 */
+export declare function publicKeyObject(key: SigningKey): KeyObject;
+/**
+ * 由 32 字节 Ed25519 seed 构造私钥 KeyObject（PKCS8 DER，固定前缀）。
+ * 确定性：同一 seed 恒得同一密钥，供测试与确定性签名器使用。
+ */
+export declare function ed25519PrivateKeyFromSeed(seed: Buffer): KeyObject;
+/** 由 PEM PKCS8 或 JWK 构造私钥 KeyObject（出站签名用）。 */
+export declare function privateKeyObject(input: string | JsonWebKey): KeyObject;
+/** 从本地 signing_keys 配置构建 resolver（精确 keyid 匹配）。 */
+export declare function resolveFromSigningKeys(keys: SigningKey[]): KeyResolver;
+/** 从 JWKS 构造 resolver：kid 匹配，kty/crv 推断算法，未知算法跳过。 */
+export declare function resolveFromJwks(keys: JsonWebKey[]): KeyResolver;

package/dist/trust/identity/keys.js

@@ -0,0 +1,118 @@
+/**
+ * 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.
+ */
+/**
+ * 签名密钥模型与 keyid → 公钥解析接缝。
+ *
+ * 两个来源（基线 §27 Identity Trust：HTTP Message Signatures / UCP signing keys）：
+ *   - `signing_keys` 本地配置信任锚：{ keyid, algorithm, publicKey, profile }；
+ *   - JWKS 接缝：{ keys: JsonWebKey[] }，kid → OKP(Ed25519) / EC(P-256)。
+ *
+ * 公钥材料三种等价形态：SPKI PEM、JWK、raw 字节（Ed25519=32B，P-256=64B
+ * 未压缩点 x||y）。`publicKeyObject` 归一为 node:crypto KeyObject 供验签。
+ * 私钥仅存在于出站签名器（signer.ts）；本模块不保存、不解析私钥除外的任何 secret。
+ */
+import { createPrivateKey, createPublicKey } from "node:crypto";
+/** 校验 raw 长度并按算法归一为 JWK。 */
+export function publicKeyJwkFromRaw(algorithm, raw) {
+    if (algorithm === "ed25519") {
+        if (raw.length !== 32) {
+            throw new Error(`Ed25519 raw public key must be 32 bytes (got ${raw.length})`);
+        }
+        return { kty: "OKP", crv: "Ed25519", x: raw.toString("base64url") };
+    }
+    if (raw.length !== 64) {
+        throw new Error(`P-256 raw public key must be 64 bytes (got ${raw.length})`);
+    }
+    return {
+        kty: "EC",
+        crv: "P-256",
+        x: raw.subarray(0, 32).toString("base64url"),
+        y: raw.subarray(32, 64).toString("base64url"),
+    };
+}
+/** 把 SigningKey 归一为 node:crypto 公钥 KeyObject。 */
+export function publicKeyObject(key) {
+    if (key.publicKeyPem !== undefined) {
+        return createPublicKey(key.publicKeyPem);
+    }
+    if (key.jwk !== undefined) {
+        return createPublicKey({ key: key.jwk, format: "jwk" });
+    }
+    if (key.publicKeyRaw !== undefined) {
+        return createPublicKey({
+            key: publicKeyJwkFromRaw(key.algorithm, key.publicKeyRaw),
+            format: "jwk",
+        });
+    }
+    throw new Error(`SigningKey ${key.keyid} has no public key material`);
+}
+/**
+ * 由 32 字节 Ed25519 seed 构造私钥 KeyObject（PKCS8 DER，固定前缀）。
+ * 确定性：同一 seed 恒得同一密钥，供测试与确定性签名器使用。
+ */
+export function ed25519PrivateKeyFromSeed(seed) {
+    if (seed.length !== 32) {
+        throw new Error(`Ed25519 private seed must be 32 bytes (got ${seed.length})`);
+    }
+    const DER_PREFIX = Buffer.from("302e020100300506032b657004220420", "hex");
+    return createPrivateKey({
+        key: Buffer.concat([DER_PREFIX, seed]),
+        format: "der",
+        type: "pkcs8",
+    });
+}
+/** 由 PEM PKCS8 或 JWK 构造私钥 KeyObject（出站签名用）。 */
+export function privateKeyObject(input) {
+    if (typeof input === "string")
+        return createPrivateKey(input);
+    return createPrivateKey({ key: input, format: "jwk" });
+}
+/** 从本地 signing_keys 配置构建 resolver（精确 keyid 匹配）。 */
+export function resolveFromSigningKeys(keys) {
+    const byId = new Map();
+    for (const key of keys) {
+        if (key.keyid.length === 0) {
+            throw new Error("resolveFromSigningKeys: keyid must be a non-empty string");
+        }
+        if (byId.has(key.keyid)) {
+            throw new Error(`resolveFromSigningKeys: duplicate keyid "${key.keyid}"`);
+        }
+        byId.set(key.keyid, key);
+    }
+    return (keyid) => byId.get(keyid);
+}
+/** 从 JWKS 构造 resolver：kid 匹配，kty/crv 推断算法，未知算法跳过。 */
+export function resolveFromJwks(keys) {
+    const byKid = new Map();
+    for (const jwk of keys) {
+        if (typeof jwk.kid !== "string" || jwk.kid.length === 0)
+            continue;
+        const algorithm = algorithmFromJwk(jwk);
+        if (algorithm === undefined)
+            continue;
+        byKid.set(jwk.kid, { keyid: jwk.kid, algorithm, jwk });
+    }
+    return (keyid) => byKid.get(keyid);
+}
+/** 由 JWK 推断算法：OKP+Ed25519 → ed25519；EC+P-256 → es256；其余不支持。 */
+function algorithmFromJwk(jwk) {
+    if (jwk.kty === "OKP" && jwk.crv === "Ed25519")
+        return "ed25519";
+    if (jwk.kty === "EC" && jwk.crv === "P-256")
+        return "es256";
+    return undefined;
+}
+//# sourceMappingURL=keys.js.map

package/dist/trust/identity/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../../../src/trust/identity/keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAmC,MAAM,aAAa,CAAC;AAmCjG,4BAA4B;AAC5B,MAAM,UAAU,mBAAmB,CACjC,SAA6B,EAC7B,GAAW;IAEX,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,IAAI,GAAG,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,gDAAgD,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;QACjF,CAAC;QACD,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC,EAAE,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;IACtE,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,8CAA8C,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;IAC/E,CAAC;IACD,OAAO;QACL,GAAG,EAAE,IAAI;QACT,GAAG,EAAE,OAAO;QACZ,CAAC,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC;QAC5C,CAAC,EAAE,GAAG,CAAC,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC;KAC9C,CAAC;AACJ,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,eAAe,CAAC,GAAe;IAC7C,IAAI,GAAG,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACnC,OAAO,eAAe,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAC3C,CAAC;IACD,IAAI,GAAG,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO,eAAe,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;IAC1D,CAAC;IACD,IAAI,GAAG,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACnC,OAAO,eAAe,CAAC;YACrB,GAAG,EAAE,mBAAmB,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,YAAY,CAAC;YACzD,MAAM,EAAE,KAAK;SACd,CAAC,CAAC;IACL,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,cAAc,GAAG,CAAC,KAAK,6BAA6B,CAAC,CAAC;AACxE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CAAC,IAAY;IACpD,IAAI,IAAI,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,8CAA8C,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;IAChF,CAAC;IACD,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,kCAAkC,EAAE,KAAK,CAAC,CAAC;IAC1E,OAAO,gBAAgB,CAAC;QACtB,GAAG,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QACtC,MAAM,EAAE,KAAK;QACb,IAAI,EAAE,OAAO;KACd,CAAC,CAAC;AACL,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,gBAAgB,CAAC,KAA0B;IACzD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAC9D,OAAO,gBAAgB,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;AACzD,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,sBAAsB,CAAC,IAAkB;IACvD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAsB,CAAC;IAC3C,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;QAC9E,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,4CAA4C,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC;QAC5E,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,CAAC,KAAa,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AAC5C,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,eAAe,CAAC,IAAkB;IAChD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;IAC5C,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,OAAO,GAAG,CAAC,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAClE,MAAM,SAAS,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;QACxC,IAAI,SAAS,KAAK,SAAS;YAAE,SAAS;QACtC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,CAAC,KAAa,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AAC7C,CAAC;AAED,+DAA+D;AAC/D,SAAS,gBAAgB,CAAC,GAAe;IACvC,IAAI,GAAG,CAAC,GAAG,KAAK,KAAK,IAAI,GAAG,CAAC,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACjE,IAAI,GAAG,CAAC,GAAG,KAAK,IAAI,IAAI,GAAG,CAAC,GAAG,KAAK,OAAO;QAAE,OAAO,OAAO,CAAC;IAC5D,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/trust/identity/message-signature.d.ts

@@ -0,0 +1,105 @@
+/**
+ * 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.
+ */
+/**
+ * HTTP Message Signatures（RFC 9421）—— 出站签名器 + 入站验签核心。
+ *
+ * 覆盖组件默认集：@method @target-uri @authority content-digest。
+ *   - @method / @target-uri / @authority 是派生组件（请求语义）；
+ *   - content-digest（RFC 9530）把请求体绑定进签名 —— 篡改任一 covered
+ *     component 都会导致验签失败，这是 §31「digest ≠ authentication」的落点：
+ *     envelope digest 只证完整性，HTTP Message Signature 证明「由持有该 key 的
+ *     身份发出」。
+ *
+ * 支持算法：Ed25519（RFC 9421 alg="ed25519"）与 ES256（P-256 + SHA-256，
+ * alg="ecdsa-p256-sha256"，原始 r||s 编码 = node:dns ieee-p1363）。零新增依赖。
+ */
+import { type JsonWebKey } from "node:crypto";
+import type { A2AOutboundRequest } from "../../a2a/client/types.js";
+import { type SignatureParams } from "./signature-base.js";
+import { type KeyProfile, type KeyResolver, type SignatureAlgorithm } from "./keys.js";
+import type { NonceStore } from "./nonce.js";
+/** RFC 9421 alg 名（Signature-Input 的 alg 参数）。 */
+export declare const RFC9421_ALG_NAMES: Record<SignatureAlgorithm, string>;
+/** 默认覆盖组件：把方法、目标、authority、请求体全部绑定进签名。 */
+export declare const DEFAULT_COVERED_COMPONENTS: readonly string[];
+/** 计算请求体的 content-digest 头值：`sha-256=:<base64>:`。 */
+export declare function contentDigestHeader(body: Buffer): string;
+/** 重算请求体 digest 并与头声明比较（内容完整性，§31）。 */
+export declare function verifyContentDigest(body: Buffer, header: string): boolean;
+export interface HttpMessageSignerOptions {
+    keyid: string;
+    algorithm: SignatureAlgorithm;
+    /** 私钥：PEM PKCS8，或 JWK，或（Ed25519 专用）32 字节 raw seed。 */
+    privateKey: string | JsonWebKey | Buffer;
+    /** 覆盖组件；默认 DEFAULT_COVERED_COMPONENTS。 */
+    coveredComponents?: readonly string[];
+    /** created 覆盖（unix 秒）；默认 now()。 */
+    created?: number;
+    /** expires（unix 秒，可选）。 */
+    expires?: number;
+    /** nonce 值（可选；T3 强制由策略决定，签名器侧可自行注入）。 */
+    nonce?: string;
+    /** 时钟（unix 秒）；默认 Date.now()/1000。 */
+    now?: () => number;
+}
+/** 出站 HTTP Message Signature 签名器。 */
+export declare class HttpMessageSigner {
+    readonly keyid: string;
+    readonly algorithm: SignatureAlgorithm;
+    private readonly privateKey;
+    private readonly coveredComponents;
+    private readonly created;
+    private readonly expires;
+    private readonly nonce;
+    private readonly now;
+    constructor(options: HttpMessageSignerOptions);
+    /** 为一次出站请求计算签名头（content-digest / signature-input / signature）。 */
+    sign(input: A2AOutboundRequest): Record<string, string>;
+}
+export interface VerifyHttpSignatureInput {
+    method: string;
+    /** 绝对 target URI（或 origin-form 请求目标）。 */
+    targetUri: string;
+    /** @authority 值（Host 头）。 */
+    authority: string;
+    /** 请求头（小写名）。 */
+    headers: Record<string, string | string[] | undefined>;
+    /** 请求体字节（用于 content-digest 重算）。 */
+    body: Buffer;
+    resolver: KeyResolver;
+    nonceStore?: NonceStore;
+    /** 时钟（unix 秒）；默认 Date.now()/1000。 */
+    now?: () => number;
+    maxClockSkewSeconds?: number;
+    maxSignatureAgeSeconds?: number;
+}
+export type HttpSignatureVerifyResult = {
+    ok: true;
+    keyid: string;
+    algorithm: SignatureAlgorithm;
+    params: SignatureParams;
+    profile?: KeyProfile;
+} | {
+    ok: false;
+    code: "authentication_required" | "authorization_failed" | "replay_detected";
+    reason: string;
+};
+/**
+ * 验签：解析 Signature-Input / Signature，逐项验证（keyid → 公钥、时间窗口、
+ * nonce、signature base、content-digest 完整性）。任一 signature 验证通过即成功；
+ * 全部失败返回第一个错误（fail-closed，§4.6）。
+ */
+export declare function verifyHttpMessageSignature(input: VerifyHttpSignatureInput): HttpSignatureVerifyResult;