@agentunion/fastaun 0.2.14 → 0.2.15

package/dist/client.d.ts

@@ -15,6 +15,7 @@ import { GroupE2EEManager } from './e2ee-group.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';
 /**
  * 递归排序键的 JSON 序列化（Canonical JSON for AUN）
@@ -58,6 +59,8 @@ export declare class AUNClient {
     readonly auth: AuthNamespace;
     /** AID 托管命名空间 */
     readonly custody: CustodyNamespace;
+    /** Meta 命名空间（心跳、状态、信任根管理） */
+    readonly meta: MetaNamespace;
     /** 会话参数（重连用） */
     private _sessionParams;
     /** 会话选项 */
@@ -149,6 +152,7 @@ export declare class AUNClient {
     on(event: string, handler: EventHandler): Subscription;
     /** P2-13: 取消订阅事件（对齐 Python/JS off 方法） */
     off(event: string, handler: EventHandler): void;
+    private _protectedHeadersFromParams;
     /** 自动加密并发送 P2P 消息 */
     private _sendEncrypted;
     private _sendEncryptedSingle;

package/dist/client.js

@@ -27,6 +27,7 @@ import { AUNLogger } from './logger.js';
 import { SQLiteBackup } from './keystore/sqlite-backup.js';
 import { AuthNamespace } from './namespaces/auth.js';
 import { CustodyNamespace } from './namespaces/custody.js';
+import { MetaNamespace } from './namespaces/meta.js';
 import { RPCTransport } from './transport.js';
 import { AuthFlow } from './auth.js';
 import { SeqTracker } from './seq-tracker.js';
@@ -141,6 +142,7 @@ const SIGNED_METHODS = new Set([
 ]);
 /** peer 证书缓存 TTL（10 分钟） */
 const PEER_CERT_CACHE_TTL = 600;
+const PREKEY_FALLBACK_DEVICE_ID = 'aun_device_id';
 function isGroupServiceAid(value) {
     const text = String(value ?? '').trim();
     if (!text.includes('.'))
@@ -165,6 +167,52 @@ function isPeerPrekeyResponse(value) {
         return false;
     return candidate.prekey === undefined || isPeerPrekeyMaterial(candidate.prekey);
 }
+function normalizePeerPrekeys(prekeys) {
+    const normalized = [];
+    for (const item of prekeys) {
+        if (!isPeerPrekeyMaterial(item))
+            continue;
+        const prekeyId = item.prekey_id.trim();
+        const publicKey = item.public_key.trim();
+        const signature = item.signature.trim();
+        if (!prekeyId || !publicKey || !signature)
+            continue;
+        const deviceId = String(item.device_id ?? '').trim();
+        const certFingerprint = String(item.cert_fingerprint ?? '').trim().toLowerCase();
+        const candidate = {
+            ...item,
+            prekey_id: prekeyId,
+            public_key: publicKey,
+            signature,
+            device_id: deviceId,
+        };
+        if (certFingerprint) {
+            candidate.cert_fingerprint = certFingerprint;
+        }
+        else {
+            delete candidate.cert_fingerprint;
+        }
+        normalized.push(candidate);
+    }
+    if (normalized.length === 0)
+        return [];
+    if (normalized.length === 1) {
+        if (!String(normalized[0].device_id ?? '').trim()) {
+            normalized[0].device_id = PREKEY_FALLBACK_DEVICE_ID;
+        }
+        return normalized;
+    }
+    const seen = new Set();
+    const filtered = [];
+    for (const item of normalized) {
+        const deviceId = String(item.device_id ?? '').trim();
+        if (!deviceId || deviceId === PREKEY_FALLBACK_DEVICE_ID || seen.has(deviceId))
+            continue;
+        seen.add(deviceId);
+        filtered.push(item);
+    }
+    return filtered;
+}
 function formatCaughtError(error) {
     return error instanceof Error ? error : String(error);
 }
@@ -271,6 +319,8 @@ export class AUNClient {
     auth;
     /** AID 托管命名空间 */
     custody;
+    /** Meta 命名空间（心跳、状态、信任根管理） */
+    meta;
     /** 会话参数（重连用） */
     _sessionParams = null;
     /** 会话选项 */
@@ -368,6 +418,7 @@ export class AUNClient {
         });
         this.auth = new AuthNamespace(this);
         this.custody = new CustodyNamespace(this);
+        this.meta = new MetaNamespace(this);
         // 内部订阅：推送消息自动解密后 re-publish 给用户
         this._dispatcher.subscribe('_raw.message.received', (data) => this._onRawMessageReceived(data));
         // 群组消息推送：自动解密后 re-publish
@@ -518,6 +569,8 @@ export class AUNClient {
             if (encrypt) {
                 return await this._sendEncrypted(p);
             }
+            delete p.protected_headers;
+            delete p.headers;
         }
         // 自动加密：group.send 默认加密（encrypt 默认 True）
         if (method === 'group.send') {
@@ -526,6 +579,8 @@ export class AUNClient {
             if (encrypt) {
                 return await this._sendGroupEncrypted(p);
             }
+            delete p.protected_headers;
+            delete p.headers;
         }
         if (method === 'group.thought.put') {
             const encrypt = p.encrypt ?? true;
@@ -698,6 +753,17 @@ export class AUNClient {
         this._dispatcher.unsubscribe(event, handler);
     }
     // ── E2EE 加密发送 ────────────────────────────────────────
+    _protectedHeadersFromParams(params) {
+        const value = params.protected_headers ?? params.headers;
+        if (value == null)
+            return null;
+        if (isJsonObject(value))
+            return value;
+        if (typeof value === 'object' && typeof value.toObject === 'function') {
+            return value;
+        }
+        return null;
+    }
     /** 自动加密并发送 P2P 消息 */
     async _sendEncrypted(params) {
         const toAid = String(params.to ?? '');
@@ -709,6 +775,7 @@ export class AUNClient {
             throw new ValidationError('message.send payload must be an object when encrypt=true');
         }
         const persistRequired = Boolean(params.persist_required || params.durable);
+        const protectedHeaders = this._protectedHeadersFromParams(params);
         // 惰性同步：首次发送 P2P 消息时先 pull 一次
         if (!this._p2pSynced) {
             await this._lazySyncP2p();
@@ -719,6 +786,7 @@ export class AUNClient {
             payload,
             messageId,
             timestamp,
+            protectedHeaders,
         });
         if (recipientPrekeys.length <= 1 && selfSyncCopies.length === 0) {
             return await this._sendEncryptedSingle({
@@ -728,6 +796,7 @@ export class AUNClient {
                 timestamp,
                 prekey: recipientPrekeys[0],
                 persistRequired,
+                protectedHeaders,
             });
         }
         const recipientCopies = await this._buildRecipientDeviceCopies({
@@ -736,6 +805,7 @@ export class AUNClient {
             messageId,
             timestamp,
             prekeys: recipientPrekeys,
+            protectedHeaders,
         });
         const sendParams = {
             to: toAid,
@@ -769,6 +839,7 @@ export class AUNClient {
             prekey,
             messageId: opts.messageId,
             timestamp: opts.timestamp,
+            protectedHeaders: opts.protectedHeaders,
         });
         this._ensureEncryptResult(opts.toAid, encryptResult);
         const sendParams = {
@@ -787,7 +858,7 @@ export class AUNClient {
     async _buildRecipientDeviceCopies(opts) {
         const recipientCopies = [];
         const certCache = new Map();
-        for (const prekey of opts.prekeys) {
+        for (const prekey of normalizePeerPrekeys(opts.prekeys)) {
             const deviceId = String(prekey.device_id ?? '').trim();
             const peerCertFingerprint = String(prekey.cert_fingerprint ?? '').trim().toLowerCase();
             const cacheKey = peerCertFingerprint || '__default__';
@@ -803,6 +874,7 @@ export class AUNClient {
                 prekey,
                 messageId: opts.messageId,
                 timestamp: opts.timestamp,
+                protectedHeaders: opts.protectedHeaders,
             });
             this._ensureEncryptResult(opts.toAid, encryptResult);
             recipientCopies.push({
@@ -845,7 +917,7 @@ export class AUNClient {
         if (!myAid) {
             return [];
         }
-        const prekeys = await this._fetchPeerPrekeys(myAid);
+        const prekeys = normalizePeerPrekeys(await this._fetchPeerPrekeys(myAid));
         if (prekeys.length === 0) {
             return [];
         }
@@ -863,6 +935,7 @@ export class AUNClient {
                 prekey,
                 messageId: opts.messageId,
                 timestamp: opts.timestamp,
+                protectedHeaders: opts.protectedHeaders,
             });
             this._ensureEncryptResult(myAid, encryptResult);
             copies.push({
@@ -873,7 +946,7 @@ export class AUNClient {
         return copies;
     }
     _encryptCopyPayload(opts) {
-        const [envelope, encryptResult] = this._e2ee.encryptOutbound(opts.logicalToAid, opts.payload, opts.peerCertPem, opts.prekey ?? null, opts.messageId, opts.timestamp);
+        const [envelope, encryptResult] = this._e2ee.encryptOutbound(opts.logicalToAid, opts.payload, opts.peerCertPem, opts.prekey ?? null, opts.messageId, opts.timestamp, opts.protectedHeaders, opts.context ?? null);
         return [envelope, encryptResult];
     }
     _ensureEncryptResult(toAid, encryptResult) {
@@ -905,7 +978,7 @@ export class AUNClient {
         return await this._callGroupEncryptedRpc('group.thought.put', params, {
             idField: 'thought_id',
             idPrefix: 'gt',
-            extraFields: ['reply_to'],
+            extraFields: ['context'],
         });
     }
     async _putMessageThoughtEncrypted(params) {
@@ -930,6 +1003,8 @@ export class AUNClient {
             prekey,
             messageId: thoughtId,
             timestamp,
+            protectedHeaders: this._protectedHeadersFromParams(params),
+            context: isJsonObject(params.context) ? params.context : null,
         });
         this._ensureEncryptResult(toAid, encryptResult);
         const sendParams = {
@@ -939,8 +1014,9 @@ export class AUNClient {
             encrypted: true,
             thought_id: thoughtId,
             timestamp,
-            reply_to: params.reply_to,
         };
+        if ('context' in params)
+            sendParams.context = params.context;
         this._signClientOperation('message.thought.put', sendParams);
         return await this._transport.call('message.thought.put', sendParams);
     }
@@ -977,12 +1053,26 @@ export class AUNClient {
         await this._waitForGroupMembershipEpochFloor(groupId, 2000);
         const epochResult = await this._committedGroupEpochState(groupId);
         const committedEpoch = Number(epochResult.committed_epoch ?? epochResult.epoch ?? 0);
-        const envelope = committedEpoch > 0
-            ? this._groupE2ee.encryptWithEpoch(groupId, await this._ensureCommittedGroupSecretForSend(groupId, committedEpoch, epochResult), payload)
-            : await this._groupE2ee.encrypt(groupId, payload);
         const operationId = String(params[options.idField] ?? '').trim()
             || `${options.idPrefix}-${crypto.randomUUID()}`;
         const timestamp = Number(params.timestamp ?? Date.now());
+        const protectedHeaders = this._protectedHeadersFromParams(params);
+        const context = method === 'group.thought.put' && isJsonObject(params.context)
+            ? params.context
+            : null;
+        const envelope = committedEpoch > 0
+            ? this._groupE2ee.encryptWithEpoch(groupId, await this._ensureCommittedGroupSecretForSend(groupId, committedEpoch, epochResult), payload, {
+                messageId: operationId,
+                timestamp,
+                protectedHeaders,
+                context,
+            })
+            : await this._groupE2ee.encrypt(groupId, payload, {
+                messageId: operationId,
+                timestamp,
+                protectedHeaders,
+                context,
+            });
         const sendParams = {
             group_id: groupId,
             payload: envelope,
@@ -2416,11 +2506,17 @@ export class AUNClient {
     async _fetchPeerPrekeys(peerAid) {
         const cachedList = this._peerPrekeysCache.get(peerAid);
         if (cachedList && Date.now() / 1000 < cachedList.expireAt) {
-            return cachedList.items.map((item) => ({ ...item }));
+            const normalized = normalizePeerPrekeys(cachedList.items);
+            if (normalized.length > 0) {
+                return normalized.map((item) => ({ ...item }));
+            }
         }
         const cached = this._e2ee.getCachedPrekey(peerAid);
-        if (cached !== null)
-            return [{ ...cached }];
+        if (cached !== null) {
+            const normalized = normalizePeerPrekeys([cached]);
+            if (normalized.length > 0)
+                return normalized.map((item) => ({ ...item }));
+        }
         try {
             const result = await this._transport.call('message.e2ee.get_prekey', { aid: peerAid });
             if (!isJsonObject(result)) {
@@ -2431,13 +2527,7 @@ export class AUNClient {
             }
             const devicePrekeys = Array.isArray(result.device_prekeys) ? result.device_prekeys : null;
             if (devicePrekeys) {
-                const normalized = [];
-                for (const item of devicePrekeys) {
-                    if (!isPeerPrekeyMaterial(item)) {
-                        continue;
-                    }
-                    normalized.push({ ...item });
-                }
+                const normalized = normalizePeerPrekeys(devicePrekeys);
                 if (normalized.length > 0) {
                     this._peerPrekeysCache.set(peerAid, {
                         items: normalized.map((item) => ({ ...item })),
@@ -2452,12 +2542,15 @@ export class AUNClient {
             }
             const prekey = result.prekey;
             if (prekey) {
-                this._peerPrekeysCache.set(peerAid, {
-                    items: [{ ...prekey }],
-                    expireAt: Date.now() / 1000 + 300,
-                });
-                this._e2ee.cachePrekey(peerAid, prekey);
-                return [{ ...prekey }];
+                const normalized = normalizePeerPrekeys([prekey]);
+                if (normalized.length > 0) {
+                    this._peerPrekeysCache.set(peerAid, {
+                        items: normalized.map((item) => ({ ...item })),
+                        expireAt: Date.now() / 1000 + 300,
+                    });
+                    this._e2ee.cachePrekey(peerAid, normalized[0]);
+                    return normalized.map((item) => ({ ...item }));
+                }
             }
             if (result.found) {
                 throw new ValidationError(`invalid prekey response for ${peerAid}`);
@@ -2475,7 +2568,10 @@ export class AUNClient {
     async _fetchPeerPrekey(peerAid) {
         const cachedList = this._peerPrekeysCache.get(peerAid);
         if (cachedList && Date.now() / 1000 < cachedList.expireAt && cachedList.items.length > 0) {
-            return { ...cachedList.items[0] };
+            const normalized = normalizePeerPrekeys(cachedList.items);
+            if (normalized.length > 0) {
+                return { ...normalized[0] };
+            }
         }
         const prekeys = await this._fetchPeerPrekeys(peerAid);
         if (prekeys.length === 0) {
@@ -2852,14 +2948,16 @@ export class AUNClient {
                 this._enqueuePendingDecrypt(groupId, message);
                 continue;
             }
-            thoughts.push({
+            const thought = {
                 thought_id: thoughtId,
                 message_id: thoughtId,
-                reply_to: item.reply_to,
                 payload: decrypted.payload,
                 created_at: item.created_at,
                 e2ee: decrypted.e2ee,
-            });
+            };
+            if ('context' in item)
+                thought.context = item.context;
+            thoughts.push(thought);
         }
         return { ...result, thoughts };
     }
@@ -2902,16 +3000,18 @@ export class AUNClient {
                     continue;
                 }
             }
-            thoughts.push({
+            const thought = {
                 thought_id: thoughtId,
                 message_id: thoughtId,
-                reply_to: item.reply_to,
                 from: fromAid,
                 to: toAid,
                 payload: decrypted.payload,
                 created_at: item.created_at,
                 e2ee: decrypted.e2ee,
-            });
+            };
+            if ('context' in item)
+                thought.context = item.context;
+            thoughts.push(thought);
         }
         return { ...result, thoughts };
     }
@@ -3997,10 +4097,12 @@ export class AUNClient {
         }
         if (method === 'group.thought.put' || method === 'group.thought.get'
             || method === 'message.thought.put' || method === 'message.thought.get') {
-            const replyTo = isJsonObject(params.reply_to) ? params.reply_to : null;
-            const replyMsgId = String(replyTo?.message_id ?? '').trim();
-            if (!replyMsgId) {
-                throw new ValidationError(`${method} requires reply_to.message_id`);
+            const context = isJsonObject(params.context) ? params.context : null;
+            const contextType = String(context?.type ?? '').trim();
+            const contextId = String(context?.id ?? '').trim();
+            const hasContext = contextType.length > 0 && contextId.length > 0;
+            if (!hasContext) {
+                throw new ValidationError(`${method} requires context.type + context.id`);
             }
         }
         if (method === 'group.thought.get' && !String(params.sender_aid ?? '').trim()) {