@agentunion/fastaun 0.3.6 → 0.4.1

package/dist/client.d.ts

@@ -10,18 +10,38 @@
  * - 客户端签名（关键操作）
  * - 群组 E2EE 全自动编排（建群/加人/踢人/退出）
  */
-import type { ProtectedHeadersInput } from './protected-headers.js';
 import { type Subscription, type EventHandler } from './events.js';
-import { AuthNamespace } from './namespaces/auth.js';
-import { CustodyNamespace } from './namespaces/custody.js';
-import { MetaNamespace } from './namespaces/meta.js';
-import { type JsonValue, type RpcParams, type RpcResult } from './types.js';
+import { type JsonValue, type RpcParams, type RpcResult, ConnectionState } from './types.js';
+import { AID } from './aid.js';
 /**
  * 递归排序键的 JSON 序列化（Canonical JSON for AUN）
  * 等价于 Python json.dumps(sort_keys=True, separators=(",",":"), ensure_ascii=False)
  * 非 ASCII 字符直接以 UTF-8 输出，与 AAD 序列化规则一致。
  */
 export declare function stableStringify(obj: JsonValue | object | undefined): string;
+export interface ConnectionOptions {
+    auto_reconnect?: boolean;
+    connect_timeout?: number;
+    retry_initial_delay?: number;
+    retry_max_delay?: number;
+    retry_max_attempts?: number;
+    heartbeat_interval?: number;
+    call_timeout?: number;
+}
+export interface AUNClientOptions extends Record<string, unknown> {
+    root_ca_path?: string;
+    rootCaPath?: string;
+    verify_ssl?: boolean;
+    verifySSL?: boolean;
+    verifySsl?: boolean;
+    require_forward_secrecy?: boolean;
+    requireForwardSecrecy?: boolean;
+    replay_window_seconds?: number;
+    replayWindowSeconds?: number;
+    debug?: boolean;
+    protected_headers?: Record<string, unknown> | null;
+    aid?: never;
+}
 export declare class AUNClient {
     /** 原始配置 */
     readonly config: RpcParams;
@@ -33,6 +53,16 @@ export declare class AUNClient {
     private _identity;
     /** 连接状态 */
     private _state;
+    /** 当前 AID 值对象（新 API） */
+    private _currentAid;
+    /** 实例级 protected_headers */
+    private _instanceProtectedHeaders;
+    /** 重连退避时间戳（ms） */
+    private _nextRetryAt;
+    private _retryAttempt;
+    private _retryMaxAttempts;
+    private _lastError;
+    private _lastErrorCode;
     /** Gateway URL */
     private _gatewayUrl;
     /** 是否正在关闭 */
@@ -47,12 +77,6 @@ export declare class AUNClient {
     private _auth;
     /** 密钥存储 */
     private _keystore;
-    /** Auth 命名空间 */
-    readonly auth: AuthNamespace;
-    /** AID 托管命名空间 */
-    readonly custody: CustodyNamespace;
-    /** Meta 命名空间（心跳、状态、信任根管理） */
-    readonly meta: MetaNamespace;
     /** 会话参数（重连用） */
     private _sessionParams;
     /** 会话选项 */
@@ -71,6 +95,9 @@ export declare class AUNClient {
     private _remoteAgentMdEtag;
     private _agentMdCache;
     private _agentMdFetchInflight;
+    private _agentMdDownloadInflight;
+    private _agentMdDownloadActive;
+    private _agentMdDownloadWaiters;
     /** 消息序列号跟踪器（群消息 + P2P 空洞检测） */
     private _seqTracker;
     private _seqTrackerContext;
@@ -115,8 +142,11 @@ export declare class AUNClient {
     private static readonly V2_BOOTSTRAP_TTL_MS;
     private static readonly V2_RETRYABLE_CODES;
     private static readonly PULL_GATE_STALE_MS;
+    /** 对端 AID 缓存（aid string → AID 对象） */
+    private _peerCache;
     private static readonly V2_SIG_CACHE_TTL_MS;
     private static readonly V2_SIG_CACHE_MAX;
+    private static readonly AGENT_MD_DOWNLOAD_CONCURRENCY;
     private _reconnectActive;
     private _reconnectAbort;
     private _serverKicked;
@@ -124,43 +154,51 @@ export declare class AUNClient {
     private _lastDisconnectInfo;
     private _logger;
     private _clientLog;
-    constructor(config?: RpcParams, debug?: boolean);
+    constructor(aid?: AID);
     /** 当前 AID */
     get aid(): string | null;
+    /** 当前 AID 值对象 */
+    get currentAid(): AID | null;
+    get hasIdentity(): boolean;
+    get canSign(): boolean;
+    get canConnect(): boolean;
+    get canSend(): boolean;
+    get isReady(): boolean;
+    get isOnline(): boolean;
+    get isClosed(): boolean;
+    get aunPath(): string | null;
+    get nextRetryAt(): Date | null;
+    get nextRetryInSeconds(): number | null;
+    get retryAttempt(): number;
+    get retryMaxAttempts(): number;
+    get lastError(): Error | null;
+    get lastErrorCode(): string | null;
+    loadIdentity(aid: AID): void;
+    setProtectedHeaders(headers: Record<string, unknown> | null): void;
+    getProtectedHeaders(): Record<string, string> | null;
+    cachePeer(aid: AID): AID;
+    getPeer(aid: string): AID | null;
+    lookupPeer(aid: string): Promise<AID>;
+    peers(): AID[];
+    private _resolveAgentMdUrl;
+    private _ensureAgentMdUploadToken;
+    private _uploadAgentMd;
+    private _acquireAgentMdDownloadSlot;
+    private _releaseAgentMdDownloadSlot;
+    private _downloadAgentMd;
+    private _downloadAgentMdOnce;
+    private _headAgentMd;
+    private _verifyAgentMd;
     /**
      * 读取 {agentMdPath}/{self_aid}/agent.md，签名后上传，并把签名结果原子写回本地。
      */
     publishAgentMd(): Promise<Record<string, unknown>>;
-    /**
-     * 下载 agent.md 并自动验签；内容固定保存到 {agentMdPath}/{aid}/agent.md。
-     */
-    fetchAgentMd(aid?: string | null): Promise<{
-        aid: string;
-        content: string;
-        signature: Record<string, unknown>;
-        in_sync: boolean | null;
-        saved_to: string | null;
-        save_error: string | null;
-    }>;
     private _startAgentMdFetchTask;
     private _fetchAgentMdOnce;
     /**
      * 设置 agent.md 本地存储根目录；为空时恢复默认 {aun_path}/AIDs。
      */
-    setAgentMdPath(root?: string | null): string;
-    SetAgentMDPath(root?: string | null): string;
-    /**
-     * 记录本地 agent.md 文件路径并一次性计算 etag（quoted sha256，与服务端一致）。
-     *
-     * - path 为空字符串：清除本地 path 与 etag。
-     * - 文件不存在 / 读取失败：清除 etag 并返回空串，不抛异常（应用可读 getLocalAgentMdEtag()
-     *   为空判断）。
-     * - 浏览器环境无文件系统：直接返回空串，记录 warn 日志。
-     * - 文件变更后需要重新调用 setLocalAgentMdPath() 触发重算（按设计：设置时一次性计算）。
-     *
-     * 返回当前 etag（quoted hex 或空串）。
-     */
-    setLocalAgentMdPath(path: string): string;
+    private _setAgentMdRoot;
     /** 返回 setLocalAgentMdPath 计算的 etag；未设置或读取失败时返回空串。 */
     getLocalAgentMdEtag(): string;
     /**
@@ -193,22 +231,18 @@ export declare class AUNClient {
     private _observeAgentMdMeta;
     private _observeAgentMdEtag;
     private _observeAgentMdFromEnvelope;
-    checkAgentMd(aid?: string | null, maxUnsyncedDays?: number): Promise<Record<string, unknown>>;
+    private _checkAgentMdCache;
     /** transport 的 meta observer：吸收 gateway 注入的 _meta 字段。失败不影响业务。 */
     private _observeRpcMeta;
     /** 连接状态 */
-    get state(): string;
+    get state(): ConnectionState;
+    private _publicState;
     /** 最近一次 gateway health check 结果，null 表示尚未检查 */
     get gatewayHealth(): boolean | null;
-    /** 向 gatewayUrl 的 /health 端点发送 GET 请求，检查网关可用性 */
-    checkGatewayHealth(gatewayUrl: string, timeout?: number): Promise<boolean>;
-    /**
-     * 连接到 Gateway。
-     *
-     * @param auth - 认证参数（必须包含 access_token 和 gateway）
-     * @param options - 会话选项（auto_reconnect、heartbeat_interval 等）
-     */
-    connect(auth: RpcParams, options?: RpcParams): Promise<void>;
+    /** 仅认证当前身份，获取/刷新 token，但不建立长连接。 */
+    authenticate(options?: RpcParams): Promise<Record<string, unknown>>;
+    /** 连接到 Gateway；身份来自构造函数或 loadIdentity(aid)，认证由 SDK 内部自动完成。 */
+    connect(opts?: ConnectionOptions): Promise<void>;
     /** 关闭连接 */
     close(): Promise<void>;
     /**
@@ -216,38 +250,11 @@ export declare class AUNClient {
      * disconnect 是可恢复的：停止心跳、关闭 WebSocket，但不清理 keystore 等状态。
      */
     disconnect(): Promise<void>;
-    /**
-     * 列出本地身份摘要。
-     *
-     * @param opts.all=false（默认）：仅返回严格校验通过的可用身份——
-     *   keypair 完整 + cert 公钥 == keypair 公钥 + cert 时间窗口有效
-     * @param opts.all=true：返回所有 AIDs/ 子目录（不含 _pending/）；
-     *   每项含 valid=bool 和 reason=string 字段
-     */
-    listIdentities(opts?: {
-        all?: boolean;
-    }): Array<{
-        aid: string;
-        valid: boolean;
-        reason?: string;
-        metadata?: Record<string, unknown>;
-    }>;
-    /**
-     * 严格校验本地身份的可用性。返回 {valid, reason}。
-     * 4 项校验：keypair 完整 + cert 存在 + cert 公钥 == keypair 公钥 + cert 时间窗口有效。
-     */
-    private _validateLocalIdentity;
     /**
      * 发送 JSON-RPC 调用。
      * 自动处理内部方法限制、E2EE 加解密、客户端签名等。
      */
     call(method: string, params?: RpcParams): Promise<RpcResult>;
-    /** 心跳检测 */
-    ping(params?: RpcParams): Promise<RpcResult>;
-    /** 获取服务端状态 */
-    status(params?: RpcParams): Promise<RpcResult>;
-    /** 获取信任根证书列表 */
-    trustRoots(params?: RpcParams): Promise<RpcResult>;
     /** 订阅事件 */
     on(event: string, handler: EventHandler): Subscription;
     private _callRawV2Rpc;
@@ -383,7 +390,7 @@ export declare class AUNClient {
      * 初始化 V2 session：IK 使用 AID 长期私钥，SPK 存储在 per-AID SQLite 的 v2_device_keys 表。
      * connect 成功后会自动调用；重复调用幂等。
      */
-    initV2Session(): Promise<void>;
+    private _initV2Session;
     private _v2TrustedIKPubDer;
     private _v2SPKTimestampText;
     private _v2VerifySPKDevice;
@@ -400,38 +407,20 @@ export declare class AUNClient {
      */
     private _buildV2P2PEnvelope;
     /** V2 P2P 加密发送，推测性缓存失败后刷新 bootstrap 重试一次。 */
-    sendV2(to: string, payload: Record<string, unknown>, opts?: {
-        messageId?: string;
-        timestamp?: number;
-        protectedHeaders?: ProtectedHeadersInput;
-        context?: Record<string, unknown>;
-    }): Promise<unknown>;
+    private _sendV2;
     /** V2 P2P 拉取并解密；直接方法返回消息数组，call("message.pull") 会包装为 {messages}. */
-    pullV2(afterSeq?: number, limit?: number, opts?: {
-        skipAutoAck?: boolean;
-        gateLocked?: boolean;
-        scheduleFollowup?: boolean;
-        force?: boolean;
-    }): Promise<Array<Record<string, unknown>>>;
+    private _pullV2;
     /** V2 P2P ack，并触发旧 SPK 销毁自检。 */
-    ackV2(upToSeq?: number): Promise<unknown>;
+    private _ackV2;
     /** V2 Group 加密发送，推测性缓存失败后刷新 bootstrap 重试一次。 */
-    sendGroupV2(groupId: string, payload: Record<string, unknown>, opts?: {
-        messageId?: string;
-        timestamp?: number;
-        protectedHeaders?: ProtectedHeadersInput;
-        context?: Record<string, unknown>;
-    }): Promise<unknown>;
+    private _sendGroupV2;
     /** 构造 V2 Group envelope；group.send 与 group.thought.put 共用。 */
     private _buildV2GroupEnvelope;
     private _pullGroupV2Internal;
     /** V2 Group 拉取并解密；直接方法返回消息数组，call("group.pull") 会包装为 {messages}. */
-    pullGroupV2(groupId: string, afterSeq?: number, limit?: number, opts?: {
-        gateLocked?: boolean;
-        scheduleFollowup?: boolean;
-    }): Promise<Array<Record<string, unknown>>>;
+    private _pullGroupV2;
     /** V2 Group ack。 */
-    ackGroupV2(groupId: string, upToSeq?: number): Promise<unknown>;
+    private _ackGroupV2;
     /** 解密单条 V2 pull 消息。缺 sender IK 时先入 pending，后台补齐后重试。 */
     private _decryptV2Message;
     private _v2E2eeMeta;
@@ -472,6 +461,8 @@ export declare class AUNClient {
     /** Push 通知带 payload 时的就地解密（复用 _decryptV2Message） */
     private _decryptV2PushMessage;
     private _onV2EpochRotated;
+    /** 按当前 AID 发现 Gateway；用于 authenticate()/connect() 的新入口。 */
+    private _resolveGatewayForAid;
     /** 从参数中解析 Gateway URL */
     private _resolveGateway;
     /** 从参数中解析所有 Gateway URL（支持 string 或 string[]） */
@@ -523,11 +514,11 @@ export declare class AUNClient {
      * 创建命名群：本地生成 P-256 keypair，调用 group.create 传入 public_key，
      * 服务端签发群 AID 证书，返回后将证书和私钥存入 keystore。
      */
-    createNamedGroup(groupName: string, opts?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    private createNamedGroup;
     /**
      * 为已有普通群绑定命名 AID（升级为命名群）。
      */
-    bindGroupAid(groupId: string, groupName: string): Promise<Record<string, unknown>>;
+    private bindGroupAid;
     /** 判断是否应重试重连 */
     private static _shouldRetryReconnect;
 }