@invictus-z/attp 0.1.0-alpha.0

package/dist/index.d.cts

@@ -0,0 +1,296 @@
+/**
+ * 消息格式规范化 — RecordedHop / NodeMessage / BackMessage。
+ *
+ * 从 python/attp/core/message/event.py 翻译而来。
+ * 序列化格式 (to_dict/from_dict) 与 Python 端完全一致，
+ * 确保跨语言通信时的数据兼容性。
+ */
+/**
+ * 单跳记录内容，嵌入在 NodeMessage 和 BackMessage 中。
+ *
+ * sigContent 是对其余字段哈希后的签名，
+ * 由发送方私钥签署，用于内容完整性验证。
+ */
+declare class RecordedHop {
+    sessionId: string;
+    senderDid: string;
+    targetDid: string;
+    content: string;
+    timestamp: number;
+    hopCount: number;
+    sigContent: string;
+    constructor(data: {
+        sessionId: string;
+        senderDid: string;
+        targetDid: string;
+        content: string;
+        timestamp: number;
+        hopCount: number;
+        sigContent?: string;
+    });
+    /** 计算除 sigContent 外所有字段的 SHA-256 哈希。 */
+    contentHash(): Promise<string>;
+    toDict(): Record<string, unknown>;
+    static fromDict(data: Record<string, unknown>): RecordedHop;
+}
+/**
+ * 转发消息：A 向 B 发送。
+ *
+ * protocolUrl: 协议节点地址
+ * nonce:       唯一标识，用于匹配回传消息
+ * recordedHop: 单跳记录内容
+ */
+declare class NodeMessage {
+    protocolUrl: string;
+    nonce: string;
+    recordedHop: RecordedHop;
+    constructor(data: {
+        protocolUrl: string;
+        nonce: string;
+        recordedHop: RecordedHop;
+    });
+    /** 发送方私钥对 recordedHop 内容签名，写入 sigContent。 */
+    signContent(privateKey: CryptoKey): Promise<void>;
+    /** 验证 recordedHop.sigContent 是否由对应公钥签署。 */
+    verifyContent(publicKey: CryptoKey): Promise<boolean>;
+    toDict(): Record<string, unknown>;
+    static fromDict(data: Record<string, unknown>): NodeMessage;
+}
+/**
+ * 节点回传消息：节点（A 或 B）向协议节点回传。
+ *
+ * protocolUrl:  协议节点地址
+ * nodeDid:      回传节点的 DID 身份
+ * nonce:        唯一标识，用于匹配回传消息
+ * sigIdentity:  nodeDid + nonce 的私钥签名，用于身份确认
+ * recordedHop:  单跳记录内容
+ */
+declare class BackMessage {
+    protocolUrl: string;
+    nodeDid: string;
+    nonce: string;
+    sigIdentity: string;
+    recordedHop: RecordedHop;
+    constructor(data: {
+        protocolUrl: string;
+        nodeDid: string;
+        nonce: string;
+        sigIdentity?: string;
+        recordedHop: RecordedHop;
+    });
+    /** 使用回传节点私钥对 nodeDid+nonce 签名，写入 sigIdentity。 */
+    signIdentity(privateKey: CryptoKey): Promise<void>;
+    /** 验证 sigIdentity 是否合法。 */
+    verifyIdentity(publicKey: CryptoKey): Promise<boolean>;
+    /** 使用发送方私钥对 recordedHop 内容签名。 */
+    signContent(privateKey: CryptoKey): Promise<void>;
+    /** 验证 recordedHop 内容签名（发送方签名）。 */
+    verifyContent(publicKey: CryptoKey): Promise<boolean>;
+    toDict(): Record<string, unknown>;
+    static fromDict(data: Record<string, unknown>): BackMessage;
+}
+
+/**
+ * 密钥管理 — KeyStore 用于缓存公钥/私钥。
+ *
+ * 从 python/attp/core/authentication/keys.py 翻译而来。
+ * 浏览器端使用 CryptoKey 对象替代 Python cryptography 库的密钥对象。
+ */
+/**
+ * 密钥存储：管理公钥缓存 (nodeDid → publicKey) 和私钥缓存 (path → privateKey)。
+ *
+ * 在浏览器环境中，私钥通过 CryptoKey 对象表示，
+ * 公钥同样为 CryptoKey 对象。
+ */
+declare class KeyStore {
+    private _cache;
+    private _privateKeyCache;
+    /**
+     * 注入公钥到缓存。
+     */
+    cachePublicKey(nodeDid: string, publicKey: CryptoKey): void;
+    /**
+     * 获取缓存的公钥，不存在返回 undefined。
+     */
+    get(nodeDid: string): CryptoKey | undefined;
+    /**
+     * 暴露内部缓存 Map 引用，维持兼容性。
+     */
+    get cacheDict(): Map<string, CryptoKey>;
+    /**
+     * 缓存私钥，后续调用相同标识直接返回缓存。
+     */
+    cachePrivateKey(keyId: string, privateKey: CryptoKey): void;
+    /**
+     * 获取缓存的私钥。
+     */
+    getPrivateKey(keyId: string): CryptoKey | undefined;
+    /**
+     * 检查是否已有缓存的私钥。
+     */
+    hasPrivateKey(keyId: string): boolean;
+}
+
+/**
+ * 签名与验签引擎。
+ *
+ * 从 python/attp/core/authentication/signatures.py 翻译而来。
+ * 使用 Web Crypto API 实现，支持：
+ *   - RSA-PSS (对应 Python rsa.RSAPrivateKey/RSAPublicKey)
+ *   - ECDSA P-256/384/521 (对应 Python ec.EllipticCurvePrivateKey)
+ *
+ * 注意：Python 端对 entry_hash 字符串直接签名（UTF-8 编码后），
+ * Web Crypto API 签名时也对 UTF-8 编码的字符串签名，保持一致。
+ */
+/**
+ * 使用私钥对 entryHash 签名，返回 Base64 编码的签名字符串。
+ *
+ * @param entryHash SHA-256 hex 字符串
+ * @param privateKey CryptoKey 私钥对象 (RSA 或 EC)
+ * @returns Base64 编码的签名字符串，失败返回空字符串
+ */
+declare function signHash(entryHash: string, privateKey: CryptoKey): Promise<string>;
+/**
+ * 用公钥验证 entryHash 的签名。
+ *
+ * @param entryHash SHA-256 hex 字符串
+ * @param signatureB64 Base64 编码的签名
+ * @param publicKey CryptoKey 公钥对象
+ * @returns true 签名合法，false 验证失败
+ */
+declare function verifySignature(entryHash: string, signatureB64: string, publicKey: CryptoKey): Promise<boolean>;
+
+/**
+ * 哈希计算：genesis 标识哈希和每跳签名哈希。
+ *
+ * 从 python/attp/core/provenance/hashing.py 翻译而来。
+ * 使用 Web Crypto API (crypto.subtle.digest) 实现 SHA-256，
+ * 保证输出与 Python 端 hashlib.sha256 完全一致。
+ */
+/**
+ * 计算创世标识的 SHA-256 哈希，用于防篡改验证。
+ */
+declare function calculateGenesisHash(sessionId: string, protocolNodeAddress: string): Promise<string>;
+/**
+ * 计算单跳消息字段的 SHA-256 哈希，用于身份验证签名。
+ */
+declare function calculateHopHash(content: string, nodeDid: string, targetDid: string, hopCount: number, timestamp: number, sessionId: string, protocolNodeAddress: string): Promise<string>;
+
+/**
+ * BehaviorEntry — 单条行为记录。
+ *
+ * 从 python/attp/core/sessions/node_message.py 翻译而来。
+ *
+ * fieldType 取值：
+ *   A2T — Agent → Tool   （Agent 调用工具）
+ *   A2U — Agent → User   （Agent 发给用户）
+ *   U2A — User  → Agent  （用户发给 Agent）
+ *   A2A — Agent → Agent  （Agent 间通信）
+ *   T2A — Tool  → Agent  （工具返回结果，预留）
+ */
+/** 行为类型枚举 */
+type FieldType = 'A2T' | 'A2U' | 'U2A' | 'A2A' | 'T2A';
+declare class BehaviorEntry {
+    fieldType: FieldType;
+    content: string;
+    timestamp: number;
+    target: string;
+    extra: Record<string, unknown>;
+    constructor(data: {
+        fieldType: FieldType;
+        content: string;
+        timestamp?: number;
+        target?: string;
+        extra?: Record<string, unknown>;
+    });
+    toDict(): Record<string, unknown>;
+    static fromDict(data: Record<string, unknown>): BehaviorEntry;
+}
+
+/**
+ * UserSession / UserSessionManager — 用户端会话管理。
+ *
+ * 面向 User 客户端，管理 ATTP 协议层的会话元数据：
+ *   - session_id / protocol_node_address / hop 元数据
+ *   - 用户身份 (userDid) 和密钥标识
+ *
+ * 参考 Python 端 AppSession 的结构，但针对用户端场景简化。
+ */
+/** Hop 记录的元数据结构 */
+interface HopMetadata {
+    Hop_Count: number;
+    Timestamp: number;
+    Signature: string;
+    Content: string;
+    node_did: string;
+    target_did: string;
+    session_id?: string;
+    protocol_node_address?: string;
+}
+/**
+ * UserSession — 用户端单个会话的协议层状态容器。
+ */
+declare class UserSession {
+    /** 会话标识（通常是 chatId） */
+    key: string;
+    /** ATTP 协议层元数据 */
+    metadata: Record<string, unknown>;
+    /** 最后更新时间（Unix 时间戳，秒） */
+    updatedAt: number;
+    constructor(data: {
+        key: string;
+        metadata?: Record<string, unknown>;
+        updatedAt?: number;
+    });
+    /** 提取追踪相关的元数据。 */
+    getTraceMetadata(): Record<string, unknown>;
+    /** 合并追踪元数据。 */
+    setTraceMetadata(traceData: Record<string, unknown>): void;
+    get sessionId(): string | undefined;
+    set sessionId(value: string | undefined);
+    get protocolNodeAddress(): string | undefined;
+    set protocolNodeAddress(value: string | undefined);
+    get hop(): HopMetadata | undefined;
+    get hopCount(): number;
+    /** 用户 DID 标识 */
+    get userDid(): string | undefined;
+    set userDid(value: string | undefined);
+    /** 密钥标识（用于从 KeyStore 查找私钥） */
+    get keyId(): string | undefined;
+    set keyId(value: string | undefined);
+    setMetadata(key: string, value: unknown): void;
+    getMetadata(key: string, defaultValue?: unknown): unknown;
+    updateMetadata(data: Record<string, unknown>): void;
+    toDict(): Record<string, unknown>;
+    static fromDict(data: Record<string, unknown>): UserSession;
+}
+/**
+ * UserSessionManager — 用户端会话存储，按 chatId 索引。
+ *
+ * 内存中维护所有活跃会话，可选持久化到 localStorage。
+ */
+declare class UserSessionManager {
+    private _sessions;
+    /** 获取或创建会话。 */
+    getOrCreate(chatId: string): UserSession;
+    /** 获取已有会话，不存在返回 undefined。 */
+    get(chatId: string): UserSession | undefined;
+    /** 保存/更新会话。 */
+    save(session: UserSession): void;
+    /** 删除会话。 */
+    delete(chatId: string): void;
+    /** 所有会话条目。 */
+    entries(): IterableIterator<[string, UserSession]>;
+    /** 会话数量。 */
+    get size(): number;
+    /** 序列化所有会话为 JSON 字符串。 */
+    serialize(): string;
+    /** 从 JSON 字符串反序列化恢复所有会话。 */
+    deserialize(json: string): void;
+    /** 保存到 localStorage。 */
+    saveToStorage(storageKey?: string): void;
+    /** 从 localStorage 加载。 */
+    loadFromStorage(storageKey?: string): void;
+}
+
+export { BackMessage, BehaviorEntry, type FieldType, type HopMetadata, KeyStore, NodeMessage, RecordedHop, UserSession, UserSessionManager, calculateGenesisHash, calculateHopHash, signHash, verifySignature };

package/dist/index.d.ts

@@ -0,0 +1,296 @@
+/**
+ * 消息格式规范化 — RecordedHop / NodeMessage / BackMessage。
+ *
+ * 从 python/attp/core/message/event.py 翻译而来。
+ * 序列化格式 (to_dict/from_dict) 与 Python 端完全一致，
+ * 确保跨语言通信时的数据兼容性。
+ */
+/**
+ * 单跳记录内容，嵌入在 NodeMessage 和 BackMessage 中。
+ *
+ * sigContent 是对其余字段哈希后的签名，
+ * 由发送方私钥签署，用于内容完整性验证。
+ */
+declare class RecordedHop {
+    sessionId: string;
+    senderDid: string;
+    targetDid: string;
+    content: string;
+    timestamp: number;
+    hopCount: number;
+    sigContent: string;
+    constructor(data: {
+        sessionId: string;
+        senderDid: string;
+        targetDid: string;
+        content: string;
+        timestamp: number;
+        hopCount: number;
+        sigContent?: string;
+    });
+    /** 计算除 sigContent 外所有字段的 SHA-256 哈希。 */
+    contentHash(): Promise<string>;
+    toDict(): Record<string, unknown>;
+    static fromDict(data: Record<string, unknown>): RecordedHop;
+}
+/**
+ * 转发消息：A 向 B 发送。
+ *
+ * protocolUrl: 协议节点地址
+ * nonce:       唯一标识，用于匹配回传消息
+ * recordedHop: 单跳记录内容
+ */
+declare class NodeMessage {
+    protocolUrl: string;
+    nonce: string;
+    recordedHop: RecordedHop;
+    constructor(data: {
+        protocolUrl: string;
+        nonce: string;
+        recordedHop: RecordedHop;
+    });
+    /** 发送方私钥对 recordedHop 内容签名，写入 sigContent。 */
+    signContent(privateKey: CryptoKey): Promise<void>;
+    /** 验证 recordedHop.sigContent 是否由对应公钥签署。 */
+    verifyContent(publicKey: CryptoKey): Promise<boolean>;
+    toDict(): Record<string, unknown>;
+    static fromDict(data: Record<string, unknown>): NodeMessage;
+}
+/**
+ * 节点回传消息：节点（A 或 B）向协议节点回传。
+ *
+ * protocolUrl:  协议节点地址
+ * nodeDid:      回传节点的 DID 身份
+ * nonce:        唯一标识，用于匹配回传消息
+ * sigIdentity:  nodeDid + nonce 的私钥签名，用于身份确认
+ * recordedHop:  单跳记录内容
+ */
+declare class BackMessage {
+    protocolUrl: string;
+    nodeDid: string;
+    nonce: string;
+    sigIdentity: string;
+    recordedHop: RecordedHop;
+    constructor(data: {
+        protocolUrl: string;
+        nodeDid: string;
+        nonce: string;
+        sigIdentity?: string;
+        recordedHop: RecordedHop;
+    });
+    /** 使用回传节点私钥对 nodeDid+nonce 签名，写入 sigIdentity。 */
+    signIdentity(privateKey: CryptoKey): Promise<void>;
+    /** 验证 sigIdentity 是否合法。 */
+    verifyIdentity(publicKey: CryptoKey): Promise<boolean>;
+    /** 使用发送方私钥对 recordedHop 内容签名。 */
+    signContent(privateKey: CryptoKey): Promise<void>;
+    /** 验证 recordedHop 内容签名（发送方签名）。 */
+    verifyContent(publicKey: CryptoKey): Promise<boolean>;
+    toDict(): Record<string, unknown>;
+    static fromDict(data: Record<string, unknown>): BackMessage;
+}
+
+/**
+ * 密钥管理 — KeyStore 用于缓存公钥/私钥。
+ *
+ * 从 python/attp/core/authentication/keys.py 翻译而来。
+ * 浏览器端使用 CryptoKey 对象替代 Python cryptography 库的密钥对象。
+ */
+/**
+ * 密钥存储：管理公钥缓存 (nodeDid → publicKey) 和私钥缓存 (path → privateKey)。
+ *
+ * 在浏览器环境中，私钥通过 CryptoKey 对象表示，
+ * 公钥同样为 CryptoKey 对象。
+ */
+declare class KeyStore {
+    private _cache;
+    private _privateKeyCache;
+    /**
+     * 注入公钥到缓存。
+     */
+    cachePublicKey(nodeDid: string, publicKey: CryptoKey): void;
+    /**
+     * 获取缓存的公钥，不存在返回 undefined。
+     */
+    get(nodeDid: string): CryptoKey | undefined;
+    /**
+     * 暴露内部缓存 Map 引用，维持兼容性。
+     */
+    get cacheDict(): Map<string, CryptoKey>;
+    /**
+     * 缓存私钥，后续调用相同标识直接返回缓存。
+     */
+    cachePrivateKey(keyId: string, privateKey: CryptoKey): void;
+    /**
+     * 获取缓存的私钥。
+     */
+    getPrivateKey(keyId: string): CryptoKey | undefined;
+    /**
+     * 检查是否已有缓存的私钥。
+     */
+    hasPrivateKey(keyId: string): boolean;
+}
+
+/**
+ * 签名与验签引擎。
+ *
+ * 从 python/attp/core/authentication/signatures.py 翻译而来。
+ * 使用 Web Crypto API 实现，支持：
+ *   - RSA-PSS (对应 Python rsa.RSAPrivateKey/RSAPublicKey)
+ *   - ECDSA P-256/384/521 (对应 Python ec.EllipticCurvePrivateKey)
+ *
+ * 注意：Python 端对 entry_hash 字符串直接签名（UTF-8 编码后），
+ * Web Crypto API 签名时也对 UTF-8 编码的字符串签名，保持一致。
+ */
+/**
+ * 使用私钥对 entryHash 签名，返回 Base64 编码的签名字符串。
+ *
+ * @param entryHash SHA-256 hex 字符串
+ * @param privateKey CryptoKey 私钥对象 (RSA 或 EC)
+ * @returns Base64 编码的签名字符串，失败返回空字符串
+ */
+declare function signHash(entryHash: string, privateKey: CryptoKey): Promise<string>;
+/**
+ * 用公钥验证 entryHash 的签名。
+ *
+ * @param entryHash SHA-256 hex 字符串
+ * @param signatureB64 Base64 编码的签名
+ * @param publicKey CryptoKey 公钥对象
+ * @returns true 签名合法，false 验证失败
+ */
+declare function verifySignature(entryHash: string, signatureB64: string, publicKey: CryptoKey): Promise<boolean>;
+
+/**
+ * 哈希计算：genesis 标识哈希和每跳签名哈希。
+ *
+ * 从 python/attp/core/provenance/hashing.py 翻译而来。
+ * 使用 Web Crypto API (crypto.subtle.digest) 实现 SHA-256，
+ * 保证输出与 Python 端 hashlib.sha256 完全一致。
+ */
+/**
+ * 计算创世标识的 SHA-256 哈希，用于防篡改验证。
+ */
+declare function calculateGenesisHash(sessionId: string, protocolNodeAddress: string): Promise<string>;
+/**
+ * 计算单跳消息字段的 SHA-256 哈希，用于身份验证签名。
+ */
+declare function calculateHopHash(content: string, nodeDid: string, targetDid: string, hopCount: number, timestamp: number, sessionId: string, protocolNodeAddress: string): Promise<string>;
+
+/**
+ * BehaviorEntry — 单条行为记录。
+ *
+ * 从 python/attp/core/sessions/node_message.py 翻译而来。
+ *
+ * fieldType 取值：
+ *   A2T — Agent → Tool   （Agent 调用工具）
+ *   A2U — Agent → User   （Agent 发给用户）
+ *   U2A — User  → Agent  （用户发给 Agent）
+ *   A2A — Agent → Agent  （Agent 间通信）
+ *   T2A — Tool  → Agent  （工具返回结果，预留）
+ */
+/** 行为类型枚举 */
+type FieldType = 'A2T' | 'A2U' | 'U2A' | 'A2A' | 'T2A';
+declare class BehaviorEntry {
+    fieldType: FieldType;
+    content: string;
+    timestamp: number;
+    target: string;
+    extra: Record<string, unknown>;
+    constructor(data: {
+        fieldType: FieldType;
+        content: string;
+        timestamp?: number;
+        target?: string;
+        extra?: Record<string, unknown>;
+    });
+    toDict(): Record<string, unknown>;
+    static fromDict(data: Record<string, unknown>): BehaviorEntry;
+}
+
+/**
+ * UserSession / UserSessionManager — 用户端会话管理。
+ *
+ * 面向 User 客户端，管理 ATTP 协议层的会话元数据：
+ *   - session_id / protocol_node_address / hop 元数据
+ *   - 用户身份 (userDid) 和密钥标识
+ *
+ * 参考 Python 端 AppSession 的结构，但针对用户端场景简化。
+ */
+/** Hop 记录的元数据结构 */
+interface HopMetadata {
+    Hop_Count: number;
+    Timestamp: number;
+    Signature: string;
+    Content: string;
+    node_did: string;
+    target_did: string;
+    session_id?: string;
+    protocol_node_address?: string;
+}
+/**
+ * UserSession — 用户端单个会话的协议层状态容器。
+ */
+declare class UserSession {
+    /** 会话标识（通常是 chatId） */
+    key: string;
+    /** ATTP 协议层元数据 */
+    metadata: Record<string, unknown>;
+    /** 最后更新时间（Unix 时间戳，秒） */
+    updatedAt: number;
+    constructor(data: {
+        key: string;
+        metadata?: Record<string, unknown>;
+        updatedAt?: number;
+    });
+    /** 提取追踪相关的元数据。 */
+    getTraceMetadata(): Record<string, unknown>;
+    /** 合并追踪元数据。 */
+    setTraceMetadata(traceData: Record<string, unknown>): void;
+    get sessionId(): string | undefined;
+    set sessionId(value: string | undefined);
+    get protocolNodeAddress(): string | undefined;
+    set protocolNodeAddress(value: string | undefined);
+    get hop(): HopMetadata | undefined;
+    get hopCount(): number;
+    /** 用户 DID 标识 */
+    get userDid(): string | undefined;
+    set userDid(value: string | undefined);
+    /** 密钥标识（用于从 KeyStore 查找私钥） */
+    get keyId(): string | undefined;
+    set keyId(value: string | undefined);
+    setMetadata(key: string, value: unknown): void;
+    getMetadata(key: string, defaultValue?: unknown): unknown;
+    updateMetadata(data: Record<string, unknown>): void;
+    toDict(): Record<string, unknown>;
+    static fromDict(data: Record<string, unknown>): UserSession;
+}
+/**
+ * UserSessionManager — 用户端会话存储，按 chatId 索引。
+ *
+ * 内存中维护所有活跃会话，可选持久化到 localStorage。
+ */
+declare class UserSessionManager {
+    private _sessions;
+    /** 获取或创建会话。 */
+    getOrCreate(chatId: string): UserSession;
+    /** 获取已有会话，不存在返回 undefined。 */
+    get(chatId: string): UserSession | undefined;
+    /** 保存/更新会话。 */
+    save(session: UserSession): void;
+    /** 删除会话。 */
+    delete(chatId: string): void;
+    /** 所有会话条目。 */
+    entries(): IterableIterator<[string, UserSession]>;
+    /** 会话数量。 */
+    get size(): number;
+    /** 序列化所有会话为 JSON 字符串。 */
+    serialize(): string;
+    /** 从 JSON 字符串反序列化恢复所有会话。 */
+    deserialize(json: string): void;
+    /** 保存到 localStorage。 */
+    saveToStorage(storageKey?: string): void;
+    /** 从 localStorage 加载。 */
+    loadFromStorage(storageKey?: string): void;
+}
+
+export { BackMessage, BehaviorEntry, type FieldType, type HopMetadata, KeyStore, NodeMessage, RecordedHop, UserSession, UserSessionManager, calculateGenesisHash, calculateHopHash, signHash, verifySignature };