@agentunion/fastaun 0.2.13

package/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Copyright 2024-2026 Agent Union Network
+
+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.

package/README.md

@@ -0,0 +1,78 @@
+# AUN Protocol — Node.js SDK
+
+## Overview
+
+AUN (Agent Union Network) defines a standard interface for secure communication between Agents — based on WebSocket + JSON-RPC 2.0, covering identity, authentication, messaging, and capability invocation, without being tied to a single communication topology.
+
+---
+
+## Core Concepts
+
+**Problem**: AI Agents are trapped in their respective platforms, unable to communicate across domains and invoke each other's capabilities.
+
+**AUN's Answer**:
+
+- **AID Identity**: Globally unique identifier in `{name}.{issuer}` format (e.g., `alice.agentid.pub`), based on X.509 certificate chain
+- **Three Connection Modes**: Gateway (standard access), Peer (point-to-point direct), Relay (relay forwarding), with consistent application-layer API
+- **Capability Invocation**: Native `tool_call` / `tool_result` message types, allowing cross-domain discovery and invocation of Agent capabilities
+
+```
+                  ┌─ Gateway ──→ Standard access (browser/mobile/server)
+Agent A ← WSS → ─┤─ Peer ─────→ Point-to-point direct (same network/low latency)
+                  └─ Relay ────→ Relay forwarding (NAT traversal/lightweight deployment)
+```
+
+**This SDK** is the Node.js/TypeScript client implementation of the AUN protocol. Install with `npm install @agentunion/fastaun`.
+
+---
+
+## Installation
+
+```bash
+npm install @agentunion/fastaun
+```
+
+## Quick Start
+
+```typescript
+import { AunClient } from '@agentunion/fastaun';
+
+// Create client
+const client = new AunClient({
+  aid: 'alice.agentid.pub',
+  gatewayUrl: 'wss://gateway.agentid.pub',
+  dataDir: './data'
+});
+
+// Connect
+await client.connect();
+
+// Send message
+await client.sendMessage({
+  to: 'bob.agentid.pub',
+  content: 'Hello from Alice!'
+});
+
+// Receive messages
+client.on('message', (msg) => {
+  console.log('Received:', msg);
+});
+```
+
+## Features
+
+- ✅ AID-based identity authentication
+- ✅ End-to-end encrypted messaging
+- ✅ Group chat with E2EE
+- ✅ Cross-domain communication
+- ✅ Tool call/result support
+- ✅ Storage service integration
+- ✅ TypeScript support with full type definitions
+
+## Documentation
+
+For detailed documentation, visit: https://github.com/agentunion/aun-sdk-core
+
+## License
+
+Apache-2.0

package/dist/auth.d.ts

@@ -0,0 +1,287 @@
+/**
+ * AuthFlow — 认证流程管理
+ *
+ * Node.js 完整实现，与 Python SDK 的 AuthFlow 接口对齐。
+ * 功能：
+ * - AID 创建（在 Gateway 注册身份）
+ * - 两阶段挑战-应答认证（login1 + login2）
+ * - 证书链验证（chain + CRL + OCSP）
+ * - Token 刷新
+ * - 会话初始化
+ * - 证书恢复与自动续期
+ */
+import WebSocket from 'ws';
+import type { CryptoProvider } from './crypto.js';
+import type { KeyStore } from './keystore/index.js';
+import type { RPCTransport } from './transport.js';
+import { type IdentityRecord, type JsonObject, type RpcMessage } from './types.js';
+/** 默认连接工厂：创建临时 WebSocket 连接 */
+type ConnectionFactory = (url: string) => Promise<WebSocket>;
+export declare class AuthFlow {
+    private static readonly _INSTANCE_STATE_FIELDS;
+    private _keystore;
+    private _crypto;
+    private _aid;
+    private _deviceId;
+    private _slotId;
+    private _verifySsl;
+    private _connectionFactory;
+    private _rootCaPath;
+    private _chainCacheTtl;
+    private _rootCerts;
+    private _gatewayChainCache;
+    private _gatewayCrlCache;
+    private _gatewayOcspCache;
+    private _chainVerifiedCache;
+    private _gatewayCaVerified;
+    constructor(opts: {
+        keystore: KeyStore;
+        crypto: CryptoProvider;
+        aid?: string | null;
+        deviceId?: string;
+        slotId?: string;
+        connectionFactory?: ConnectionFactory;
+        rootCaPath?: string | null;
+        chainCacheTtl?: number;
+        verifySsl?: boolean;
+    });
+    /** 加载身份信息（密钥对 + 证书 + 元数据） */
+    loadIdentity(aid?: string): IdentityRecord;
+    /** 加载身份信息，不存在时返回 null */
+    loadIdentityOrNone(aid?: string): IdentityRecord | null;
+    /** 与 Browser/JS SDK 对齐的别名：加载身份信息，不存在时返回 null */
+    loadIdentityOrNull(aid?: string): IdentityRecord | null;
+    /** 获取 access_token 的过期时间戳（秒） */
+    getAccessTokenExpiry(identity: IdentityRecord): number | null;
+    setInstanceContext(opts: {
+        deviceId: string;
+        slotId?: string;
+    }): void;
+    /**
+     * 创建 AID 并注册到 Gateway。
+     * 如果 AID 已在服务端注册但本地证书丢失，尝试从 PKI 端点下载恢复。
+     */
+    createAid(gatewayUrl: string, aid: string): Promise<JsonObject>;
+    /**
+     * 认证（登录）到 Gateway。
+     * 执行两阶段挑战-应答认证，返回 token 信息。
+     */
+    authenticate(gatewayUrl: string, opts?: {
+        aid?: string;
+    }): Promise<JsonObject>;
+    /**
+     * 确保已认证（自动创建 + 登录）。
+     * 如果没有本地身份则创建，然后执行登录流程。
+     */
+    ensureAuthenticated(gatewayUrl: string): Promise<AuthContext>;
+    /**
+     * 刷新缓存的 token。
+     * 使用 refresh_token 获取新的 access_token。
+     */
+    refreshCachedTokens(gatewayUrl: string, identity: IdentityRecord): Promise<IdentityRecord>;
+    /**
+     * 使用 token 初始化 WebSocket 会话。
+     * 发送 auth.connect RPC 完成会话握手。
+     */
+    initializeWithToken(transport: RPCTransport, challenge: RpcMessage | null, accessToken: string, opts?: {
+        deviceId?: string;
+        slotId?: string;
+        deliveryMode?: JsonObject | null;
+    }): Promise<void>;
+    /**
+     * 连接会话（自动选择认证策略）。
+     * 依次尝试：显式 token → 缓存 token → 刷新 token → 完整重认证。
+     */
+    connectSession(transport: RPCTransport, challenge: RpcMessage | null, gatewayUrl: string, opts?: {
+        accessToken?: string;
+        deviceId?: string;
+        slotId?: string;
+        deliveryMode?: JsonObject | null;
+    }): Promise<AuthContext>;
+    /**
+     * 验证对端证书：时间有效性 + 链验证 + CRL + OCSP + AID 绑定。
+     * 用于 E2EE 握手中验证通信对端的身份证书。
+     */
+    verifyPeerCertificate(gatewayUrl: string, certPem: string, expectedAid: string): Promise<void>;
+    /**
+     * 通过临时 WebSocket 发送单次 JSON-RPC 请求。
+     * 流程：连接 → 接收 challenge → 发送请求 → 接收响应 → 关闭。
+     */
+    private _shortRpc;
+    /** 从 WebSocket 接收一条消息（Promise 封装） */
+    private _wsRecv;
+    /** 注册 AID 到 Gateway */
+    private _createAid;
+    /** 两阶段登录 */
+    private _login;
+    /** 刷新 access_token */
+    private _refreshAccessToken;
+    /** 会话初始化：发送 auth.connect RPC */
+    private _initializeSession;
+    /**
+     * 验证 Phase 1 响应：
+     * 1. 解析 auth_cert
+     * 2. 验证证书链 + CRL + OCSP
+     * 3. 验证 client_nonce_signature
+     */
+    private _verifyPhase1Response;
+    /**
+     * 验证认证证书链。
+     * 1. 检查缓存
+     * 2. 时间有效性
+     * 3. 签名链验证
+     * 4. BasicConstraints 检查
+     * 5. 根证书自签 + 受信根锚定
+     */
+    private _verifyAuthCertChain;
+    /** 加载 Gateway CA 链（带缓存） */
+    private _loadGatewayCaChain;
+    /** 从 Gateway PKI 端点获取 CA 链 */
+    private _fetchGatewayCaChain;
+    /**
+     * CRL 吊销检查。
+     * 从 Gateway 的 /pki/crl.json 端点获取 CRL，
+     * 验证签发者签名，检查证书序列号是否在吊销列表中。
+     */
+    private _verifyAuthCertRevocation;
+    /** 加载 Gateway 吊销列表（带缓存） */
+    private _loadGatewayRevokedSerials;
+    /**
+     * 从 Gateway /pki/crl.json 获取 CRL 并解析。
+     *
+     * 响应格式: { crl_pem: "...", revoked_serials?: [...] }
+     *
+     * 注意：完整的 CRL PEM 签名验证需要 ASN.1/DER 解析，
+     * Node.js 标准库不直接支持 CRL 解析。
+     * 这里使用 JSON 响应中的 revoked_serials 字段作为可信数据源，
+     * 并验证 crl_pem 存在性。完整的 CRL 签名验证需要依赖
+     * @peculiar/x509 或手动 ASN.1 解析。
+     */
+    private _fetchGatewayCrl;
+    /**
+     * 从 CRL PEM 解析吊销序列号。
+     * 简化的 ASN.1 DER 解析：提取 TBSCertList 中的 revokedCertificates 序列号。
+     *
+     * CRL ASN.1 结构（简化）：
+     * CertificateList ::= SEQUENCE {
+     *   tbsCertList    TBSCertList,
+     *   signatureAlgorithm AlgorithmIdentifier,
+     *   signature      BIT STRING
+     * }
+     *
+     * TBSCertList ::= SEQUENCE {
+     *   version              INTEGER OPTIONAL,
+     *   signature            AlgorithmIdentifier,
+     *   issuer               Name,
+     *   thisUpdate           Time,
+     *   nextUpdate           Time OPTIONAL,
+     *   revokedCertificates  SEQUENCE OF SEQUENCE { ... } OPTIONAL,
+     *   ...
+     * }
+     */
+    private _parseCrlRevokedSerials;
+    /**
+     * OCSP 状态检查。
+     * 从 Gateway 的 /pki/ocsp/{serial_hex} 端点获取 OCSP 响应。
+     */
+    private _verifyAuthCertOcsp;
+    /** 加载 Gateway OCSP 状态（带缓存） */
+    private _loadGatewayOcspStatus;
+    /**
+     * 从 Gateway /pki/ocsp/{serial_hex} 获取 OCSP 状态。
+     *
+     * 响应格式: { status: "good"|"revoked"|"unknown", ocsp_response: "base64..." }
+     *
+     * 注意：完整的 OCSP DER 响应解析需要 ASN.1 解析。
+     * 这里从 JSON 响应中提取 status 字段，并验证 ocsp_response 存在性。
+     * 对于 ocsp_response 的签名验证，实现简化的 DER 解析以提取关键字段。
+     */
+    private _fetchGatewayOcspStatus;
+    /**
+     * 简化的 OCSP DER 响应解析。
+     *
+     * OCSPResponse ::= SEQUENCE {
+     *   responseStatus  ENUMERATED { successful(0), ... },
+     *   responseBytes   [0] EXPLICIT SEQUENCE {
+     *     responseType   OID,
+     *     response       OCTET STRING (BasicOCSPResponse DER)
+     *   } OPTIONAL
+     * }
+     *
+     * BasicOCSPResponse ::= SEQUENCE {
+     *   tbsResponseData  ResponseData,
+     *   signatureAlgorithm AlgorithmIdentifier,
+     *   signature        BIT STRING,
+     *   ...
+     * }
+     *
+     * ResponseData ::= SEQUENCE {
+     *   version          [0] EXPLICIT INTEGER DEFAULT v1,
+     *   responderID      ...,
+     *   producedAt       GeneralizedTime,
+     *   responses        SEQUENCE OF SingleResponse,
+     *   ...
+     * }
+     *
+     * SingleResponse ::= SEQUENCE {
+     *   certID           CertID,
+     *   certStatus       CHOICE { good [0], revoked [1], unknown [2] },
+     *   thisUpdate       GeneralizedTime,
+     *   nextUpdate       [0] EXPLICIT GeneralizedTime OPTIONAL,
+     * }
+     *
+     * 这里只做关键字段提取：responseStatus、certStatus。
+     * 完整签名验证依赖更全面的 ASN.1 库。
+     */
+    private _parseOcspResponse;
+    /** 读取 ASN.1 SEQUENCE 标签，返回内容偏移和长度 */
+    private _readAsn1Sequence;
+    /** 读取任意 ASN.1 标签的长度信息 */
+    private _readAsn1Tag;
+    /**
+     * 从 PKI HTTP 端点下载证书恢复。
+     * 本地有密钥但无证书、服务端已注册时使用。
+     */
+    private _recoverCertViaDownload;
+    /**
+     * 验证服务端返回的 new_cert，通过后才正式接受。
+     * 安全要点：CN/公钥/时间 + 完整链验证 + 受信根锚定 + CRL/OCSP。
+     */
+    private _validateNewCert;
+    /**
+     * 从认证结果中提取并保存 token 到 identity。
+     * 与 Python SDK 的 _remember_tokens 对齐。
+     */
+    private static _rememberTokens;
+    /**
+     * 获取缓存的 access_token（30 秒提前过期余量）。
+     * 返回空字符串表示 token 不可用。
+     */
+    private static _getCachedAccessToken;
+    private static readonly _AID_NAME_RE;
+    private static _validateAidName;
+    /** 确保本地有指定 AID 的身份（不存在则创建密钥对） */
+    private _ensureLocalIdentity;
+    /** 加载身份信息，不存在时抛出 StateError */
+    private _loadIdentityOrRaise;
+    /** 确保有身份（不存在时自动创建密钥对） */
+    private _ensureIdentity;
+    private _loadInstanceState;
+    private _persistIdentity;
+    /** 从 challenge 消息中提取 nonce */
+    private _extractChallengeNonce;
+    /** 加载受信根证书列表 */
+    private _loadTrustedRoots;
+    /**
+     * 加载根证书：内置 + 自定义路径。
+     * 在 SDK 的 certs/ 目录下查找 *.crt 文件。
+     */
+    private _loadRootCerts;
+    /** 清理过期的 gateway 缓存条目（供外部定时调用） */
+    cleanExpiredCaches(): void;
+}
+interface AuthContext extends JsonObject {
+    token?: string;
+    identity?: IdentityRecord;
+}
+export {};