@agentunion/fastaun-browser 0.3.3 → 0.3.4

package/dist/bundle.js

@@ -346,7 +346,7 @@ var init_indexeddb_store = __esm({
         return this._masterKeyPromise;
       }
       async _initMasterKey() {
-        if (this._encryptionSeed) {
+        if (this._encryptionSeed !== void 0) {
           return this._deriveKeyFromSeed(this._encryptionSeed);
         }
         const storedSeed = await secretGet(STORE_MASTER, "seed");
@@ -495,6 +495,12 @@ var AuthError = class extends AUNError {
     this.name = "AuthError";
   }
 };
+var IdentityConflictError = class extends AuthError {
+  constructor(message, opts) {
+    super(message, opts);
+    this.name = "IdentityConflictError";
+  }
+};
 var PermissionError = class extends AUNError {
   constructor(message, opts) {
     super(message, opts);
@@ -970,6 +976,8 @@ var GatewayDiscovery = class {
 
 // src/transport.ts
 var MAX_WS_PAYLOAD_SIZE = 1e6;
+var MAX_RPC_INFLIGHT = 16;
+var MAX_BACKGROUND_RPC_INFLIGHT = 8;
 var _noopLog3 = { error: () => {
 }, warn: () => {
 }, info: () => {
@@ -1226,6 +1234,10 @@ var RPCTransport = class {
     __publicField(this, "_closed", true);
     __publicField(this, "_challenge", null);
     __publicField(this, "_pending", /* @__PURE__ */ new Map());
+    __publicField(this, "_pendingBackground", /* @__PURE__ */ new Set());
+    __publicField(this, "_rpcQueue", []);
+    __publicField(this, "_backgroundRpcQueue", []);
+    __publicField(this, "_drainingRpcQueue", false);
     // Gateway 在 RPC envelope 注入 _meta 字段（与 result 同级），由 client 层 observer 接收。
     // 注入失败 / 字段缺失时 observer 不会被调用，不影响业务路径。
     __publicField(this, "_metaObserver", null);
@@ -1329,7 +1341,8 @@ var RPCTransport = class {
   async close() {
     const tStart = Date.now();
     const pendingCount = this._pending.size;
-    this._log.debug(`close enter: pending_rpc=${pendingCount}`);
+    const queuedCount = this._rpcQueue.length + this._backgroundRpcQueue.length;
+    this._log.debug(`close enter: pending_rpc=${pendingCount}, queued_rpc=${queuedCount}, background_pending=${this._pendingBackground.size}`);
     this._closed = true;
     if (this._ws) {
       try {
@@ -1343,16 +1356,28 @@ var RPCTransport = class {
       this._ws = null;
     }
     for (const [, pending] of this._pending) {
+      clearTimeout(pending.timer);
       pending.reject(new ConnectionError("transport closed"));
     }
     this._pending.clear();
-    this._log.debug(`close exit: elapsed=${Date.now() - tStart}ms`);
+    this._pendingBackground.clear();
+    for (const queued of this._rpcQueue) {
+      clearTimeout(queued.pending.timer);
+      queued.pending.reject(new ConnectionError("transport closed"));
+    }
+    this._rpcQueue = [];
+    for (const queued of this._backgroundRpcQueue) {
+      clearTimeout(queued.pending.timer);
+      queued.pending.reject(new ConnectionError("transport closed"));
+    }
+    this._backgroundRpcQueue = [];
+    this._log.debug(`close exit: elapsed=${Date.now() - tStart}ms, cancelled ${pendingCount} pending, ${queuedCount} queued`);
   }
   /**
    * 发起 JSON-RPC 2.0 调用。
    * 返回 result 字段的值；若有 error 字段则抛出映射后的错误。
    */
-  async call(method, params, timeout, trace) {
+  async call(method, params, timeout, trace, background = false) {
     if (this._closed || !this._ws) {
       throw new ConnectionError("transport not connected");
     }
@@ -1361,20 +1386,19 @@ var RPCTransport = class {
     const tStart = Date.now();
     const effectiveTraceMode = trace === "off" || trace === "log" || trace === "diag" ? trace : this._traceMode;
     let traceId = "";
-    let sendParams = params ?? {};
+    const sendParams = { ...params ?? {} };
+    const localParams = sendParams;
+    const backgroundRpc = background || localParams._rpc_background === true;
+    delete localParams._rpc_background;
     if (effectiveTraceMode !== "off") {
       traceId = typeof crypto !== "undefined" && crypto.randomUUID ? crypto.randomUUID().replace(/-/g, "") : Array.from({ length: 32 }, () => Math.floor(Math.random() * 16).toString(16)).join("");
-      sendParams = { ...params ?? {} };
       const tracePayload = { trace_id: traceId, mode: effectiveTraceMode };
       if (effectiveTraceMode === "diag") {
         tracePayload.spans = [{ node: "sdk", ts: tStart, action: "send" }];
       }
-      sendParams._trace = tracePayload;
+      localParams._trace = tracePayload;
       this._log.info(`[trace=${traceId}] rpc_send method=${method} rpc_id=${rpcId}`);
     }
-    const promise = new Promise((resolve, reject) => {
-      this._pending.set(rpcId, { resolve, reject });
-    });
     const payload = JSON.stringify({
       jsonrpc: "2.0",
       id: rpcId,
@@ -1383,65 +1407,136 @@ var RPCTransport = class {
     });
     const payloadSize = new TextEncoder().encode(payload).length;
     if (payloadSize > MAX_WS_PAYLOAD_SIZE) {
-      this._pending.delete(rpcId);
       throw new ValidationError("payload is too large");
     }
-    try {
-      this._ws.send(payload);
-      this._log.debug(`RPC request sent: method=${method}, id=${rpcId} ${summarizeDict(sendParams, DIAG_PARAM_FIELDS)}`);
-    } catch (exc) {
-      this._pending.delete(rpcId);
-      this._log.error(`RPC send failed: method=${method}, id=${rpcId}, error=${String(exc)}`, exc instanceof Error ? exc : void 0);
-      throw new ConnectionError(`failed to send rpc ${method}: ${exc}`);
-    }
-    let timeoutHandle = null;
-    const timeoutPromise = new Promise((_, reject) => {
-      timeoutHandle = globalThis.setTimeout(() => {
-        this._pending.delete(rpcId);
+    return new Promise((resolve, reject) => {
+      const timer = globalThis.setTimeout(() => {
+        this._removeRpc(rpcId, pending);
         this._log.warn(`RPC timeout: method=${method}, id=${rpcId}, elapsed=${Date.now() - tStart}ms, timeout=${effectiveTimeout}ms`);
         reject(new TimeoutError(`rpc timeout: ${method}`, { retryable: true }));
+        this._drainRpcQueue();
       }, effectiveTimeout);
+      const pending = {
+        resolve: (response) => {
+          clearTimeout(timer);
+          const elapsed = Date.now() - tStart;
+          if (response.error !== void 0) {
+            this._log.debug(`RPC error response: method=${method}, id=${rpcId}, elapsed=${elapsed}ms, error=${JSON.stringify(response.error)}`);
+            if (traceId) {
+              this._log.info(`[trace=${traceId}] rpc_recv method=${method} rpc_id=${rpcId} duration_ms=${elapsed} status=error`);
+            }
+            const respTrace = response._trace;
+            if (respTrace && typeof respTrace === "object" && !Array.isArray(respTrace)) {
+              this._handleResponseTrace(method, "error", elapsed, respTrace);
+            }
+            reject(mapRemoteError(response.error));
+          } else if (response.result !== void 0) {
+            this._log.debug(`RPC response ok: method=${method}, id=${rpcId}, elapsed=${elapsed}ms ${summarizeDict(response.result, DIAG_RESULT_FIELDS)}`);
+            if (traceId) {
+              this._log.info(`[trace=${traceId}] rpc_recv method=${method} rpc_id=${rpcId} duration_ms=${elapsed} status=ok`);
+            }
+            if (this._metaObserver !== null) {
+              const meta = response._meta;
+              if (isJsonObject(meta)) {
+                try {
+                  this._metaObserver(meta);
+                } catch (exc) {
+                  this._log.debug(`meta_observer raised: ${String(exc)}`);
+                }
+              }
+            }
+            const respTrace = response._trace;
+            if (respTrace && typeof respTrace === "object" && !Array.isArray(respTrace)) {
+              this._handleResponseTrace(method, "ok", elapsed, respTrace);
+            }
+            resolve(response.result);
+          } else {
+            this._log.warn(`RPC response missing result or error: method=${method}, id=${rpcId}, elapsed=${elapsed}ms`);
+            reject(new SerializationError(`rpc response missing result and error: ${method}`));
+          }
+        },
+        reject: (err) => {
+          clearTimeout(timer);
+          reject(err);
+        },
+        timer
+      };
+      if (backgroundRpc) {
+        this._backgroundRpcQueue.push({
+          rpcId,
+          method,
+          payload,
+          pending,
+          tStart,
+          timeoutMs: effectiveTimeout,
+          background: true
+        });
+      } else {
+        this._rpcQueue.push({
+          rpcId,
+          method,
+          payload,
+          pending,
+          tStart,
+          timeoutMs: effectiveTimeout,
+          background: false
+        });
+      }
+      this._drainRpcQueue();
     });
+  }
+  /** 从 pending / queue 中移除指定 RPC */
+  _removeRpc(rpcId, pending) {
+    const current = this._pending.get(rpcId);
+    if (current && (!pending || current === pending)) {
+      this._pending.delete(rpcId);
+      this._pendingBackground.delete(rpcId);
+    }
+    if (this._rpcQueue.length > 0) {
+      this._rpcQueue = this._rpcQueue.filter((entry) => entry.rpcId !== rpcId || pending !== void 0 && entry.pending !== pending);
+    }
+    if (this._backgroundRpcQueue.length > 0) {
+      this._backgroundRpcQueue = this._backgroundRpcQueue.filter((entry) => entry.rpcId !== rpcId || pending !== void 0 && entry.pending !== pending);
+    }
+  }
+  /** 从队列中取出 RPC 并发送，直到 inflight 达到上限 */
+  _drainRpcQueue() {
+    if (this._drainingRpcQueue) return;
+    this._drainingRpcQueue = true;
     try {
-      const response = await Promise.race([promise, timeoutPromise]);
-      const elapsed = Date.now() - tStart;
-      if (response.error !== void 0) {
-        this._log.debug(`RPC error response: method=${method}, id=${rpcId}, elapsed=${elapsed}ms, error=${JSON.stringify(response.error)}`);
-        if (traceId) {
-          this._log.info(`[trace=${traceId}] rpc_recv method=${method} rpc_id=${rpcId} duration_ms=${elapsed} status=error`);
+      while (!this._closed && this._ws && this._pending.size < MAX_RPC_INFLIGHT) {
+        let entry;
+        if (this._rpcQueue.length > 0) {
+          entry = this._rpcQueue.shift();
+        } else if (this._backgroundRpcQueue.length > 0 && this._pendingBackground.size < MAX_BACKGROUND_RPC_INFLIGHT) {
+          entry = this._backgroundRpcQueue.shift();
+        } else {
+          break;
         }
-        const respTrace2 = response._trace;
-        if (respTrace2 && typeof respTrace2 === "object" && !Array.isArray(respTrace2)) {
-          this._handleResponseTrace(method, "error", elapsed, respTrace2);
+        const elapsed = Date.now() - entry.tStart;
+        if (elapsed >= entry.timeoutMs) {
+          clearTimeout(entry.pending.timer);
+          this._log.warn(`RPC queue timeout: method=${entry.method}, id=${entry.rpcId}, elapsed=${elapsed}ms, timeout=${entry.timeoutMs}ms`);
+          entry.pending.reject(new TimeoutError(`rpc timeout before send: ${entry.method}`, { retryable: true }));
+          continue;
         }
-        throw mapRemoteError(response.error);
-      }
-      if (response.result === void 0) {
-        throw new SerializationError(`rpc response missing result and error: ${method}`);
-      }
-      this._log.debug(`RPC response ok: method=${method}, id=${rpcId}, elapsed=${elapsed}ms ${summarizeDict(response.result, DIAG_RESULT_FIELDS)}`);
-      if (traceId) {
-        this._log.info(`[trace=${traceId}] rpc_recv method=${method} rpc_id=${rpcId} duration_ms=${elapsed} status=ok`);
-      }
-      if (this._metaObserver !== null) {
-        const meta = response._meta;
-        if (isJsonObject(meta)) {
-          try {
-            this._metaObserver(meta);
-          } catch (exc) {
-            this._log.debug(`meta_observer raised: ${String(exc)}`);
-          }
+        this._pending.set(entry.rpcId, entry.pending);
+        if (entry.background) {
+          this._pendingBackground.add(entry.rpcId);
+        }
+        try {
+          this._ws.send(entry.payload);
+          this._log.debug(`RPC request sent: method=${entry.method}, id=${entry.rpcId}, background=${entry.background}`);
+        } catch (err) {
+          this._removeRpc(entry.rpcId, entry.pending);
+          this._log.error(`RPC send failed: method=${entry.method}, id=${entry.rpcId}, error=${String(err)}`, err instanceof Error ? err : void 0);
+          entry.pending.reject(
+            new ConnectionError(`failed to send rpc ${entry.method}: ${err instanceof Error ? err.message : String(err)}`)
+          );
         }
       }
-      const respTrace = response._trace;
-      if (respTrace && typeof respTrace === "object" && !Array.isArray(respTrace)) {
-        this._handleResponseTrace(method, "ok", elapsed, respTrace);
-      }
-      return response.result;
     } finally {
-      if (timeoutHandle !== null) {
-        globalThis.clearTimeout(timeoutHandle);
-      }
+      this._drainingRpcQueue = false;
     }
   }
   /** 处理 RPC 响应中的 _trace 字段：追加 sdk.recv span，格式化输出，通知 observer */
@@ -1476,10 +1571,23 @@ var RPCTransport = class {
   _handleClose(event) {
     const wasClosed = this._closed;
     this._closed = true;
+    const err = new ConnectionError(`websocket closed: code=${event.code}`);
     for (const [, pending] of this._pending) {
-      pending.reject(new ConnectionError(`websocket closed: code=${event.code}`));
+      clearTimeout(pending.timer);
+      pending.reject(err);
     }
     this._pending.clear();
+    this._pendingBackground.clear();
+    for (const queued of this._rpcQueue) {
+      clearTimeout(queued.pending.timer);
+      queued.pending.reject(err);
+    }
+    this._rpcQueue = [];
+    for (const queued of this._backgroundRpcQueue) {
+      clearTimeout(queued.pending.timer);
+      queued.pending.reject(err);
+    }
+    this._backgroundRpcQueue = [];
     if (!wasClosed) {
       const error = new ConnectionError(`websocket closed: code=${event.code} reason=${event.reason}`);
       this._dispatcher.publish("connection.error", { error });
@@ -1494,7 +1602,9 @@ var RPCTransport = class {
       const pending = this._pending.get(rpcId);
       if (pending) {
         this._pending.delete(rpcId);
+        this._pendingBackground.delete(rpcId);
         pending.resolve(message);
+        this._drainRpcQueue();
       } else {
         this._log.warn("[aun_core.transport] recv unknown rpc response (maybe arrived after timeout): id=" + rpcId);
       }
@@ -1591,6 +1701,8 @@ var _noopLog4 = { error: () => {
 }, info: () => {
 }, debug: () => {
 } };
+var AUN_SDK_LANG = "javascript";
+var AUN_SDK_VERSION = "0.3.4";
 function splitPemBundle(bundle) {
   const marker = "-----END CERTIFICATE-----";
   const certs = [];
@@ -1932,47 +2044,85 @@ var _AuthFlow = class _AuthFlow {
     this._slotId = String(opts.slotId ?? "").trim();
   }
   /**
-   * 注册新 AID。
+   * 严格注册新 AID（对齐 TS registerAid / Go RegisterAID）。
    *
-   * 流程：
-   *   1. 确保本地密钥对存在
-   *   2. 短连接 RPC 调用 auth.create_aid
-   *   3. 保存返回的证书
+   * 注册与认证彻底分离：此方法绝不被 SDK 内部自动调用，
+   * 必须由应用层显式调用。
    */
-  async createAid(gatewayUrl, aid) {
+  async registerAid(gatewayUrl, aid) {
     const tStart = Date.now();
-    this._log.debug(`createAid enter: aid=${aid} gateway=${gatewayUrl}`);
+    this._log.debug(`registerAid enter: aid=${aid} gateway=${gatewayUrl}`);
     _AuthFlow._validateAidName(aid);
     try {
-      const identity = await this._ensureLocalIdentity(aid);
-      if (identity.cert) {
-        this._log.debug(`createAid exit: elapsed=${Date.now() - tStart}ms aid=${aid} reason=already_has_cert`);
-        return { aid: identity.aid, cert: identity.cert };
-      }
-      try {
-        const created = await this._createAid(gatewayUrl, identity);
-        Object.assign(identity, created);
-      } catch (e) {
-        if (e instanceof Error && e.message.includes("already exists")) {
-          try {
-            const recovered = await this._recoverCertViaDownload(gatewayUrl, identity);
-            Object.assign(identity, recovered);
-          } catch {
-            this._log.debug(`createAid exit (error): elapsed=${Date.now() - tStart}ms aid=${aid} err=already_registered_recover_failed`);
-            throw new StateError(
-              `AID ${aid} already registered on server but local certificate is missing. Certificate download recovery failed. Options: (1) use a different AID name, or (2) restart server to clear registration.`
+      const existing = await this._keystore.loadIdentity(aid);
+      if (existing && existing.private_key_pem && existing.public_key_der_b64) {
+        this._log.debug(`registerAid: local keypair exists, checking server: aid=${aid}`);
+        const localPubB642 = String(existing.public_key_der_b64);
+        const serverCertPem2 = await this._downloadRegisteredCert(gatewayUrl, aid);
+        if (serverCertPem2) {
+          const serverCert = parseCertDer(serverCertPem2);
+          const serverPubB64 = uint8ToBase64(serverCert.spkiBytes);
+          if (serverPubB64 !== localPubB642) {
+            throw new IdentityConflictError(
+              `AID '${aid}' is registered by another party on server (public key mismatch). Choose a different name.`
             );
           }
+          this._log.info(`registerAid: idempotent return for already-registered AID: aid=${aid}`);
+          if (!existing.cert) {
+            existing.cert = serverCertPem2;
+            await this._persistIdentity(existing);
+          }
+          this._aid = aid;
+          return { aid, cert: serverCertPem2 };
         } else {
-          throw e;
+          this._log.debug(`registerAid: server has no record, registering with existing keypair: aid=${aid}`);
+          const created2 = await this._createAid(gatewayUrl, existing);
+          const certPem2 = String(created2.cert ?? "");
+          if (!certPem2) {
+            throw new AuthError(`registerAid: server response missing cert for ${aid}`);
+          }
+          existing.cert = certPem2;
+          const returnedCert2 = parseCertDer(certPem2);
+          const certPubB642 = uint8ToBase64(returnedCert2.spkiBytes);
+          if (certPubB642 !== localPubB642) {
+            throw new AuthError(
+              `registerAid: server returned certificate with mismatched public key for ${aid}`
+            );
+          }
+          await this._persistIdentity(existing);
+          this._aid = aid;
+          this._log.debug(`registerAid exit (recovered): elapsed=${Date.now() - tStart}ms aid=${aid}`);
+          return { aid, cert: certPem2 };
         }
       }
+      const serverCertPem = await this._downloadRegisteredCert(gatewayUrl, aid);
+      if (serverCertPem) {
+        throw new IdentityConflictError(
+          `AID '${aid}' is already registered on server. Choose a different name, or if you own the keypair use a recovery flow.`
+        );
+      }
+      const identity = await this._crypto.generateIdentity();
+      identity.aid = aid;
+      const created = await this._createAid(gatewayUrl, identity);
+      const certPem = String(created.cert ?? "");
+      if (!certPem) {
+        throw new AuthError(`registerAid: server response missing cert for ${aid}`);
+      }
+      identity.cert = certPem;
+      const returnedCert = parseCertDer(certPem);
+      const certPubB64 = uint8ToBase64(returnedCert.spkiBytes);
+      const localPubB64 = String(identity.public_key_der_b64);
+      if (certPubB64 !== localPubB64) {
+        throw new AuthError(
+          `registerAid: server returned certificate with mismatched public key for ${aid}`
+        );
+      }
       await this._persistIdentity(identity);
-      this._aid = identity.aid;
-      this._log.debug(`createAid exit: elapsed=${Date.now() - tStart}ms aid=${aid}`);
+      this._aid = aid;
+      this._log.debug(`registerAid exit: elapsed=${Date.now() - tStart}ms aid=${aid}`);
       return { aid: identity.aid, cert: identity.cert };
     } catch (err) {
-      this._log.debug(`createAid exit (error): elapsed=${Date.now() - tStart}ms aid=${aid} err=${err instanceof Error ? err.message : String(err)}`);
+      this._log.debug(`registerAid exit (error): elapsed=${Date.now() - tStart}ms aid=${aid} err=${err instanceof Error ? err.message : String(err)}`);
       throw err;
     }
   }
@@ -2009,23 +2159,16 @@ var _AuthFlow = class _AuthFlow {
           await this._persistIdentity(identity);
         } catch (e) {
           throw new StateError(
-            `local certificate missing and recovery failed: ${e}. Run auth.createAid() to register a new identity.`
+            `local certificate missing and recovery failed: ${e}. Run auth.registerAid() to register a new identity.`
           );
         }
       }
+      this._assertCertMatchesLocalKeypair(identity);
       let login;
       try {
         login = await this._login(gatewayUrl, identity);
       } catch (e) {
-        if (e instanceof AuthError && (String(e.message).includes("not registered") || String(e.message).includes("public key mismatch"))) {
-          this._log.warn(`[auth] cert not registered on server, auto re-register: aid=${identity.aid}`);
-          const created = await this._createAid(gatewayUrl, identity);
-          identity.cert = created.cert;
-          await this._persistIdentity(identity);
-          login = await this._login(gatewayUrl, identity);
-        } else {
-          throw e;
-        }
+        throw e;
       }
       this._rememberTokens(identity, login);
       await this._validateNewCert(identity, gatewayUrl);
@@ -2045,18 +2188,19 @@ var _AuthFlow = class _AuthFlow {
     }
   }
   /**
-   * 确保已认证（如无身份则先注册再登录）。
+   * 确保已认证。注册和登录彻底分离：无身份或无 cert 直接抛错。
    */
   async ensureAuthenticated(gatewayUrl) {
     const tStart = Date.now();
     this._log.debug(`ensureAuthenticated enter: gateway=${gatewayUrl}`);
     try {
-      const identity = await this._ensureIdentity();
+      const identity = await this._loadIdentityOrRaise();
       if (!identity.cert) {
-        const created = await this._createAid(gatewayUrl, identity);
-        Object.assign(identity, created);
-        await this._persistIdentity(identity);
+        throw new StateError(
+          `local identity for aid ${identity.aid} has no certificate; call auth.authenticate() to attempt cert recovery, or auth.registerAid() if this is a fresh registration.`
+        );
       }
+      this._assertCertMatchesLocalKeypair(identity);
       const login = await this._login(gatewayUrl, identity);
       this._rememberTokens(identity, login);
       await this._validateNewCert(identity, gatewayUrl);
@@ -2388,6 +2532,35 @@ var _AuthFlow = class _AuthFlow {
     });
     return { cert: response.cert };
   }
+  /** 下载服务端当前登记的证书；未注册返回 null */
+  async _downloadRegisteredCert(gatewayUrl, aid) {
+    const certUrl = gatewayHttpUrl(gatewayUrl, `/pki/cert/${aid}`);
+    try {
+      const certPem = await this._fetchText(certUrl);
+      if (!certPem || !certPem.includes("BEGIN CERTIFICATE")) return null;
+      return certPem;
+    } catch {
+      return null;
+    }
+  }
+  /** 防线 B：cert 公钥必须与本地 keypair 公钥一致，否则拒绝登录 */
+  _assertCertMatchesLocalKeypair(identity) {
+    const aid = identity.aid ?? "?";
+    const certPem = identity.cert;
+    const localPubB64 = identity.public_key_der_b64;
+    if (!certPem || !localPubB64) {
+      throw new AuthError(
+        `identity for aid ${aid} missing cert or public key; refusing to start two-phase login`
+      );
+    }
+    const cert = parseCertDer(certPem);
+    const certSpkiB64 = uint8ToBase64(cert.spkiBytes);
+    if (certSpkiB64 !== localPubB64) {
+      throw new AuthError(
+        `local certificate public key does not match local keypair for aid ${aid}; refusing to start two-phase login. Run auth.registerAid() to repair identity.`
+      );
+    }
+  }
   /** 下载已注册证书恢复本地状态 */
   async _recoverCertViaDownload(gatewayUrl, identity) {
     const certUrl = gatewayHttpUrl(gatewayUrl, `/pki/cert/${identity.aid}`);
@@ -2455,7 +2628,11 @@ var _AuthFlow = class _AuthFlow {
       auth: { method: "kite_token", token },
       protocol: { min: "1.0", max: "1.0" },
       device: { id: String(opts?.deviceId ?? this._deviceId ?? ""), type: "sdk" },
-      client: { slot_id: String(opts?.slotId ?? this._slotId ?? "") },
+      client: {
+        slot_id: String(opts?.slotId ?? this._slotId ?? ""),
+        sdk_lang: AUN_SDK_LANG,
+        sdk_version: AUN_SDK_VERSION
+      },
       delivery_mode: opts?.deliveryMode ?? { mode: "fanout" },
       capabilities
     };
@@ -2843,26 +3020,9 @@ var _AuthFlow = class _AuthFlow {
     }
   }
   /** 确保本地有密钥对（没有则生成） */
-  async _ensureLocalIdentity(aid) {
-    const existing = await this._keystore.loadIdentity(aid);
-    if (existing && existing.private_key_pem && existing.public_key_der_b64) {
-      this._aid = aid;
-      return existing;
-    }
-    const identity = await this._crypto.generateIdentity();
-    identity.aid = aid;
-    if (existing) {
-      for (const [k, v] of Object.entries(existing)) {
-        if (k !== "aid" && !(k in identity)) {
-          identity[k] = v;
-        }
-      }
-    }
-    await this._persistIdentity(identity);
-    this._aid = aid;
-    return identity;
-  }
-  /** 加载身份，不存在时抛出异常 */
+  // （_ensureLocalIdentity 已移除：注册和登录彻底分离，
+  // 登录路径绝不再隐式生成密钥；新身份必须由应用层显式调 registerAid）
+  /** 加载身份，不存在或半成品时抛出异常 */
   async _loadIdentityOrRaise(aid) {
     const requestedAid = aid ?? this._aid;
     if (requestedAid) {
@@ -2870,26 +3030,18 @@ var _AuthFlow = class _AuthFlow {
       if (!existing) {
         throw new StateError(`identity not found for aid: ${requestedAid}`);
       }
+      if (!existing.private_key_pem || !existing.public_key_der_b64) {
+        throw new StateError(
+          `local identity for aid ${requestedAid} is incomplete (missing keypair); call auth.registerAid() first`
+        );
+      }
       this._aid = requestedAid;
       if (!existing.aid) existing.aid = requestedAid;
       return existing;
     }
-    throw new StateError("no local identity found, call auth.createAid() first");
-  }
-  /** 确保有身份（无则尝试生成） */
-  async _ensureIdentity() {
-    try {
-      return await this._loadIdentityOrRaise();
-    } catch {
-      if (!this._aid) {
-        throw new StateError("no local identity found, call auth.createAid() first");
-      }
-      const identity = await this._crypto.generateIdentity();
-      identity.aid = this._aid;
-      await this._persistIdentity(identity);
-      return identity;
-    }
+    throw new StateError("no local identity found, call auth.registerAid() first");
   }
+  // （_ensureIdentity 已移除：注册和登录彻底分离）
   async _loadInstanceState(aid) {
     if (typeof this._keystore.loadInstanceState !== "function") {
       return null;
@@ -3533,29 +3685,29 @@ var AuthNamespace = class {
   }
   /** 内部访问 client 私有属性 */
   /**
-   * 注册新 AID。
-   * 通过 well-known 发现 gateway → 调用 AuthFlow.createAid 注册。
+   * 严格注册新 AID（对齐 TS registerAid）。
+   * 通过 well-known 发现 gateway → 调用 AuthFlow.registerAid 注册。
    */
-  async createAid(params) {
+  async registerAid(params) {
     const tStart = Date.now();
     const aid = String(params?.aid ?? "");
-    this._log.debug(`createAid enter: aid=${aid}`);
+    this._log.debug(`registerAid enter: aid=${aid}`);
     try {
-      if (!aid) throw new ValidationError("auth.createAid requires 'aid'");
+      if (!aid) throw new ValidationError("auth.registerAid requires 'aid'");
       const gatewayUrl = await this._resolveGateway(aid);
       this._client.gatewayUrl = gatewayUrl;
       const auth = this._internal._auth;
-      const result = await auth.createAid(gatewayUrl, aid);
+      const result = await auth.registerAid(gatewayUrl, aid);
       this._internal._aid = aid;
       this._internal._identity = await auth.loadIdentityOrNone(aid);
-      this._log.debug(`createAid exit: elapsed=${Date.now() - tStart}ms aid=${aid}`);
+      this._log.debug(`registerAid exit: elapsed=${Date.now() - tStart}ms aid=${aid}`);
       return {
         aid,
         cert_pem: result.cert,
         gateway: gatewayUrl
       };
     } catch (err) {
-      this._log.debug(`createAid exit (error): elapsed=${Date.now() - tStart}ms aid=${aid} err=${err instanceof Error ? err.message : String(err)}`);
+      this._log.debug(`registerAid exit (error): elapsed=${Date.now() - tStart}ms aid=${aid} err=${err instanceof Error ? err.message : String(err)}`);
       throw err;
     }
   }
@@ -3591,7 +3743,7 @@ var AuthNamespace = class {
       const targetAid = String(opts?.aid ?? client._aid ?? "").trim();
       const identity = await client._auth.loadIdentityOrNone(targetAid || void 0);
       if (!identity) {
-        throw new StateError("no local identity found, call auth.createAid() first");
+        throw new StateError("no local identity found, call auth.registerAid() first");
       }
       const privateKeyPem = String(identity.private_key_pem ?? "").trim();
       const certPem = normalizeIdentityCertPem(identity);
@@ -3713,7 +3865,7 @@ var AuthNamespace = class {
     const auth = this._internal._auth;
     let identity = await auth.loadIdentityOrNone(aid);
     if (!identity) {
-      throw new StateError("no local identity found, call auth.createAid() first");
+      throw new StateError("no local identity found, call auth.registerAid() first");
     }
     const cachedToken = String(identity.access_token ?? "");
     const expiresAt = auth.getAccessTokenExpiry(identity);
@@ -3745,11 +3897,11 @@ var AuthNamespace = class {
       const auth = this._internal._auth;
       const identity = await auth.loadIdentityOrNone(this._client.aid ?? void 0);
       if (!identity) {
-        throw new StateError("no local identity found, call auth.createAid() first");
+        throw new StateError("no local identity found, call auth.registerAid() first");
       }
       const aid = String(identity.aid ?? this._client.aid ?? "").trim();
       if (!aid) {
-        throw new StateError("no local identity found, call auth.createAid() first");
+        throw new StateError("no local identity found, call auth.registerAid() first");
       }
       const gatewayUrl = await this._resolveGateway(aid);
       this._client.gatewayUrl = gatewayUrl;
@@ -3829,15 +3981,35 @@ var AuthNamespace = class {
       }
       const cached = this._agentMdCache.get(targetAid);
       const requestHeaders = { Accept: "text/markdown" };
-      if (cached?.etag) requestHeaders["If-None-Match"] = cached.etag;
-      if (cached?.lastModified) requestHeaders["If-Modified-Since"] = cached.lastModified;
-      const response = await fetchWithTimeout(await this._resolveAgentMdUrl(targetAid), {
+      const agentMdUrl = await this._resolveAgentMdUrl(targetAid);
+      const response = await fetchWithTimeout(agentMdUrl, {
         method: "GET",
-        headers: requestHeaders
+        headers: requestHeaders,
+        redirect: "follow"
       });
-      if (response.status === 304 && cached) {
-        this._log.debug(`downloadAgentMd exit (not_modified): elapsed=${Date.now() - tStart}ms aid=${targetAid}`);
-        return cached.text;
+      if (response.status === 304) {
+        if (cached?.text) {
+          this._log.debug(`downloadAgentMd exit (not_modified): elapsed=${Date.now() - tStart}ms aid=${targetAid}`);
+          return cached.text;
+        }
+        this._log.warn(`downloadAgentMd got 304 but no local cache, retrying unconditional GET: aid=${targetAid}`);
+        const retryResp = await fetchWithTimeout(agentMdUrl, {
+          method: "GET",
+          headers: { Accept: "text/markdown" },
+          redirect: "follow"
+        });
+        if (retryResp.status === 404) {
+          throw new NotFoundError(`agent.md not found for aid: ${targetAid}`);
+        }
+        if (!retryResp.ok) {
+          const message = (await retryResp.text()).trim();
+          throw new AUNError(
+            `download agent.md failed (retry): HTTP ${retryResp.status}${message ? ` - ${message}` : ""}`
+          );
+        }
+        const retryText = await retryResp.text();
+        this._log.debug(`downloadAgentMd exit (retry): elapsed=${Date.now() - tStart}ms aid=${targetAid} bytes=${retryText.length}`);
+        return retryText;
       }
       if (response.status === 404) {
         throw new NotFoundError(`agent.md not found for aid: ${targetAid}`);
@@ -4962,6 +5134,12 @@ function sameJson(a, b) {
 }
 var _ENC_ALGO = "AES-GCM";
 var _PBKDF2_ITERATIONS = 1e5;
+var SeedMigrationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SeedMigrationError";
+  }
+};
 function _uint8ToBase64(bytes) {
   let b = "";
   for (let i = 0; i < bytes.length; i++) b += String.fromCharCode(bytes[i]);
@@ -5000,6 +5178,9 @@ async function _decryptPEM(enc, seed) {
   const pt = await crypto.subtle.decrypt({ name: _ENC_ALGO, iv: toBufferSource2(iv) }, key, toBufferSource2(ct));
   return new TextDecoder().decode(pt);
 }
+function hasEncryptionSeed(seed) {
+  return seed !== void 0;
+}
 var DB_NAME = "aun-keystore";
 var DB_VERSION = 6;
 var STORE_KEY_PAIRS = "key_pairs";
@@ -5322,6 +5503,52 @@ var _IndexedDBKeyStore = class _IndexedDBKeyStore {
   setLogger(log) {
     this._log = log;
   }
+  static async changeSeed(oldSeed, newSeed) {
+    if (oldSeed === ".seed") {
+      throw new SeedMigrationError("JS IndexedDB keystore does not support file .seed migration");
+    }
+    const rows = await idbGetAll(STORE_KEY_PAIRS);
+    const migrations = [];
+    for (const row of rows) {
+      if (!isRecord(row.value)) continue;
+      const envelope = row.value._encrypted_pk;
+      if (!isRecord(envelope)) continue;
+      try {
+        const privateKeyPem = await _decryptPEM(envelope, oldSeed);
+        migrations.push({ key: row.key, value: deepClone(row.value), privateKeyPem });
+      } catch {
+        throw new SeedMigrationError(`seed migration refused: private key is not encrypted by old seed: aid=${row.key}`);
+      }
+    }
+    if (migrations.length === 0) {
+      throw new SeedMigrationError("seed migration refused: no encrypted private key verified with old seed");
+    }
+    const result = {
+      migrated: 0,
+      skipped: 0,
+      errors: 0,
+      privateKeysVerified: migrations.length,
+      privateKeysMigrated: 0
+    };
+    for (const item of migrations) {
+      const next = deepClone(item.value);
+      next._encrypted_pk = await _encryptPEM(item.privateKeyPem, newSeed);
+      const verified = await _decryptPEM(next._encrypted_pk, newSeed);
+      if (verified !== item.privateKeyPem) {
+        throw new SeedMigrationError(`new seed verification failed for private key: aid=${item.key}`);
+      }
+      delete next.private_key_pem;
+      await idbPut(STORE_KEY_PAIRS, item.key, next);
+      result.migrated += 1;
+      result.privateKeysMigrated += 1;
+    }
+    return result;
+  }
+  async changeSeed(oldSeed, newSeed) {
+    const result = await _IndexedDBKeyStore.changeSeed(oldSeed, newSeed);
+    this._encryptionSeed = newSeed;
+    return result;
+  }
   async _withAidLock(aid, fn) {
     const key = safeAid(aid);
     const previous = _IndexedDBKeyStore._aidTails.get(key) ?? Promise.resolve();
@@ -5378,7 +5605,7 @@ var _IndexedDBKeyStore = class _IndexedDBKeyStore {
     if (!isRecord(data)) return null;
     const result = deepClone(data);
     const epk = result._encrypted_pk;
-    if (epk && typeof epk === "object" && !Array.isArray(epk) && this._encryptionSeed) {
+    if (epk && typeof epk === "object" && !Array.isArray(epk) && hasEncryptionSeed(this._encryptionSeed)) {
       try {
         const envelope = epk;
         result.private_key_pem = await _decryptPEM(envelope, this._encryptionSeed);
@@ -5388,7 +5615,7 @@ var _IndexedDBKeyStore = class _IndexedDBKeyStore {
       }
     } else if (
       // 透明迁移：旧版明文数据自动加密回写
-      !epk && typeof result.private_key_pem === "string" && this._encryptionSeed
+      !epk && typeof result.private_key_pem === "string" && hasEncryptionSeed(this._encryptionSeed)
     ) {
       try {
         await this.saveKeyPair(aid, result);
@@ -5399,7 +5626,7 @@ var _IndexedDBKeyStore = class _IndexedDBKeyStore {
   }
   async saveKeyPair(aid, keyPair) {
     const record = deepClone(keyPair);
-    if (this._encryptionSeed && typeof record.private_key_pem === "string") {
+    if (hasEncryptionSeed(this._encryptionSeed) && typeof record.private_key_pem === "string") {
       record._encrypted_pk = await _encryptPEM(record.private_key_pem, this._encryptionSeed);
       delete record.private_key_pem;
     }
@@ -5775,7 +6002,7 @@ var _IndexedDBKeyStore = class _IndexedDBKeyStore {
     const data = await idbGet(STORE_KEY_PAIRS, metadataStoreKey(aid));
     if (!isRecord(data)) return null;
     const result = deepClone(data);
-    if (isRecord(result._encrypted_pk) && this._encryptionSeed) {
+    if (isRecord(result._encrypted_pk) && hasEncryptionSeed(this._encryptionSeed)) {
       try {
         const envelope = result._encrypted_pk;
         result.private_key_pem = await _decryptPEM(envelope, this._encryptionSeed);
@@ -5785,7 +6012,7 @@ var _IndexedDBKeyStore = class _IndexedDBKeyStore {
       }
     } else if (
       // 透明迁移：旧版明文数据自动加密回写
-      !isRecord(result._encrypted_pk) && typeof result.private_key_pem === "string" && this._encryptionSeed
+      !isRecord(result._encrypted_pk) && typeof result.private_key_pem === "string" && hasEncryptionSeed(this._encryptionSeed)
     ) {
       try {
         await this._saveKeyPairUnlocked(aid, result);
@@ -5796,7 +6023,7 @@ var _IndexedDBKeyStore = class _IndexedDBKeyStore {
   }
   async _saveKeyPairUnlocked(aid, keyPair) {
     const record = deepClone(keyPair);
-    if (this._encryptionSeed && typeof record.private_key_pem === "string") {
+    if (hasEncryptionSeed(this._encryptionSeed) && typeof record.private_key_pem === "string") {
       record._encrypted_pk = await _encryptPEM(record.private_key_pem, this._encryptionSeed);
       delete record.private_key_pem;
     }
@@ -9654,6 +9881,7 @@ var V2Session = class {
     __publicField(this, "_peerIKCache", /* @__PURE__ */ new Map());
     __publicField(this, "_verifiedSPKs", /* @__PURE__ */ new Set());
     __publicField(this, "_oldSPKMaxSeq", /* @__PURE__ */ new Map());
+    __publicField(this, "_spkCache", /* @__PURE__ */ new Map());
     __publicField(this, "_nowFn", () => Date.now());
     if (!ikPriv || !ikPubDer) {
       throw new Error("V2Session requires AID priv/pub keys (IK = AID identity)");
@@ -9771,8 +9999,13 @@ var V2Session = class {
     await this.ensureKeys();
     if (!spkId) return { ikPriv: this._ikPriv };
     if (spkId === this._spkId) return { ikPriv: this._ikPriv, spkPriv: this._spkPriv };
+    const cached = this._spkCache.get(spkId);
+    if (cached) return { ikPriv: this._ikPriv, spkPriv: cached };
     const oldSPK = await this._loadSPK(spkId);
-    if (oldSPK) return { ikPriv: this._ikPriv, spkPriv: oldSPK };
+    if (oldSPK) {
+      this._spkCache.set(spkId, oldSPK);
+      return { ikPriv: this._ikPriv, spkPriv: oldSPK };
+    }
     const ikAlias = await this._loadIKSPK(spkId);
     if (ikAlias) return { ikPriv: ikAlias.priv, spkPriv: ikAlias.priv };
     if (spkId === await this._ikSPKId()) {
@@ -10079,7 +10312,7 @@ function isPlainObject(value) {
 var encoder3 = new TextEncoder();
 var decoder = new TextDecoder();
 var E2EE_SDK_LANG = "javascript";
-var E2EE_SDK_VERSION = "0.3.2";
+var E2EE_SDK_VERSION = "0.3.4";
 async function sha2563(data) {
   const buf = await crypto.subtle.digest("SHA-256", data.slice().buffer);
   return new Uint8Array(buf);
@@ -10249,7 +10482,8 @@ function normalizeProtectedHeaders(headers, payload) {
     normalized["payload_type"] = payloadType;
   }
   normalized.sdk_lang = E2EE_SDK_LANG;
-  normalized.sdk_vesion = E2EE_SDK_VERSION;
+  delete normalized.sdk_vesion;
+  normalized.sdk_version = E2EE_SDK_VERSION;
   return normalized;
 }
 function normalizeProtectedHeaderKey(key) {
@@ -10641,7 +10875,7 @@ async function verifySenderSignature(env, senderPubDer) {
 }
 function findMyRow(recipients, selfAid, selfDeviceId) {
   for (const row of recipients) {
-    if (row[0] === selfAid && row[1] === selfDeviceId) return row;
+    if (row[0] === selfAid && (row[1] === selfDeviceId || row[1] === "")) return row;
   }
   return null;
 }
@@ -11092,6 +11326,54 @@ function isGroupServiceAid(value) {
   const [name, ...issuerParts] = text.split(".");
   return name === "group" && issuerParts.join(".").length > 0;
 }
+function normalizeV2WrapPolicy(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return void 0;
+  const obj = raw;
+  let protocol = String(obj.protocol ?? "").trim().toUpperCase();
+  let scope = String(obj.scope ?? "").trim().toLowerCase();
+  if (scope !== "aid" && scope !== "device") {
+    if (obj.per_aid_wrap === true) scope = "aid";
+    else if (obj.per_device_wrap === true) scope = "device";
+    else scope = "";
+  }
+  if (protocol !== "1DH" && protocol !== "3DH") protocol = "";
+  if (scope === "aid") protocol = "1DH";
+  if (!protocol && !scope) return void 0;
+  return {
+    protocol: protocol ? protocol : void 0,
+    scope: scope ? scope : void 0
+  };
+}
+function v2WrapCapabilities() {
+  return {
+    version: "v2.1",
+    protocols: ["1DH", "3DH"],
+    scopes: ["aid", "device"],
+    per_aid_wrap: true,
+    per_device_wrap: true
+  };
+}
+function applyV2WrapPolicyToTargets(targets, policy) {
+  if (!policy) return targets;
+  const normalized = targets.map((target) => {
+    const row = { ...target };
+    if (policy.protocol === "1DH") {
+      row.keySource = "aid_master";
+      row.spkPkDer = void 0;
+      row.spkId = "";
+    }
+    return row;
+  });
+  if (policy.scope !== "aid") return normalized;
+  const collapsed = /* @__PURE__ */ new Map();
+  for (const target of normalized) {
+    const key = `${target.aid}\0${target.role}`;
+    if (!collapsed.has(key)) {
+      collapsed.set(key, { ...target, deviceId: "" });
+    }
+  }
+  return Array.from(collapsed.values());
+}
 function _v2LeftPad32(b) {
   if (b.length === 32) return b;
   if (b.length > 32) return b.subarray(b.length - 32);
@@ -11315,7 +11597,7 @@ var _AUNClient = class _AUNClient {
     __publicField(this, "_agentMdPath", "");
     __publicField(this, "_agentMdCache", /* @__PURE__ */ new Map());
     __publicField(this, "_agentMdFetchInflight", /* @__PURE__ */ new Set());
-    __publicField(this, "_agentMdListLock", Promise.resolve());
+    __publicField(this, "_agentMdLock", Promise.resolve());
     /** 消息序列号跟踪器（群消息 + P2P 空洞检测） */
     __publicField(this, "_seqTracker", new SeqTracker());
     __publicField(this, "_seqTrackerContext", null);
@@ -11329,6 +11611,8 @@ var _AUNClient = class _AUNClient {
     __publicField(this, "_groupSynced", /* @__PURE__ */ new Set());
     /** gap fill 来源标记：true 表示当前正在补洞（pull 触发），false 表示非补洞 */
     __publicField(this, "_gapFillActive", false);
+    // Pull Gate：序列化同一 key 的并发 pull 操作，防止重复拉取
+    __publicField(this, "_pullGates", /* @__PURE__ */ new Map());
     // 重连相关
     __publicField(this, "_reconnectActive", false);
     __publicField(this, "_reconnectAbort", null);
@@ -11372,7 +11656,7 @@ var _AUNClient = class _AUNClient {
     this._clientLog.info(`AUNClient initialized: debug=${_debug} aunPath=${this.configModel.aunPath} aid=${initAid ?? "-"}`);
     this._dispatcher = new EventDispatcher();
     this._discovery = new GatewayDiscovery();
-    this._keystore = new IndexedDBKeyStore();
+    this._keystore = new IndexedDBKeyStore({ encryptionSeed: this.configModel.seedPassword ?? void 0 });
     this._slotId = "";
     this._connectDeliveryMode = normalizeDeliveryModeConfig({ mode: "fanout" });
     this._defaultConnectDeliveryMode = { ...this._connectDeliveryMode };
@@ -11474,7 +11758,7 @@ var _AUNClient = class _AUNClient {
   }
   /**
    * 浏览器版本 publishAgentMd。默认从 {agentMdPath}/{self_aid}/agent.md 的等价 IndexedDB 正文读取，
-   * 然后签名、上传，并刷新 list.json 元数据。
+   * 然后签名、上传，并刷新 agentmd.json 元数据。
    *
    * 兼容旧浏览器调用：传入 content 时会先写入等价正文，再从该正文发布。
    */
@@ -11516,7 +11800,7 @@ var _AUNClient = class _AUNClient {
   }
   /**
    * 浏览器版本 fetchAgentMd。aid 缺省时取自身；下载后的正文固定写入
-   * {agentMdPath}/{aid}/agent.md 的等价 IndexedDB 正文，list.json 只保存元数据。
+   * {agentMdPath}/{aid}/agent.md 的等价 IndexedDB 正文，agentmd.json 只保存元数据。
    */
   async fetchAgentMd(aid) {
     const target = String(aid ?? this._aid ?? "").trim();
@@ -11588,8 +11872,8 @@ var _AUNClient = class _AUNClient {
     }
     return target;
   }
-  _agentMdListKey() {
-    return "list.json";
+  _agentMdMetaKey(aid) {
+    return `${this._agentMdSafeAid(aid)}/agentmd.json`;
   }
   _agentMdContentKey(aid) {
     return `${this._agentMdSafeAid(aid)}/agent.md`;
@@ -11621,20 +11905,13 @@ var _AUNClient = class _AUNClient {
       fetched_at: Date.now()
     });
   }
-  async _listAgentMdContentAids() {
-    const list = this._keystore.listAgentMdContentAids;
-    if (typeof list !== "function") {
-      throw new Error("IndexedDB agent.md storage unavailable");
-    }
-    return await list.call(this._keystore, this._agentMdRoot());
-  }
-  async _withAgentMdListLock(fn) {
-    const previous = this._agentMdListLock.catch(() => void 0);
+  async _withAgentMdLock(fn) {
+    const previous = this._agentMdLock.catch(() => void 0);
     let release;
     const current = new Promise((resolve) => {
       release = resolve;
     });
-    this._agentMdListLock = previous.then(() => current);
+    this._agentMdLock = previous.then(() => current);
     await previous;
     try {
       return await fn();
@@ -11642,70 +11919,35 @@ var _AUNClient = class _AUNClient {
       release();
     }
   }
-  _normalizeAgentMdList(data) {
-    const records = {};
-    let iterable = [];
-    if (isJsonObject(data)) {
-      const payload = data;
-      if (Array.isArray(payload.records)) iterable = payload.records;
-      else if (isJsonObject(payload.records)) iterable = Object.values(payload.records);
-    } else if (Array.isArray(data)) {
-      iterable = data;
-    }
-    for (const item of iterable) {
-      if (!isJsonObject(item)) continue;
-      const raw = item;
-      const aid = String(raw.aid ?? "").trim();
-      if (!aid) continue;
-      const record = {};
-      for (const [key, value] of Object.entries(raw)) {
-        if (key !== "content") record[key] = value;
-      }
-      record.aid = aid;
-      for (const key of ["fetched_at", "observed_at", "checked_at", "updated_at"]) {
-        record[key] = Number(record[key] ?? 0) || 0;
-      }
-      records[aid] = record;
-    }
-    return records;
-  }
-  async _writeAgentMdListUnlocked(records) {
-    const sorted = {};
-    for (const aid of Object.keys(records).sort()) sorted[aid] = records[aid];
-    await this._writeAgentMdStorage(this._agentMdListKey(), `${JSON.stringify({ version: 1, updated_at: Date.now(), records: sorted }, null, 2)}
-`);
-  }
-  async _rebuildAgentMdListUnlocked() {
-    const records = {};
-    const now = Date.now();
-    for (const aid of await this._listAgentMdContentAids()) {
-      try {
-        const content = await this._readAgentMdStorage(this._agentMdContentKey(aid));
-        if (content === null) continue;
-        records[aid] = {
-          aid,
-          local_etag: await this._agentMdContentEtag(content),
-          fetched_at: now,
-          updated_at: now
-        };
-      } catch (err) {
-        this._clientLog.warn(`agent.md rebuild skipped unreadable file aid=${aid} err=${err instanceof Error ? err.message : String(err)}`);
-      }
+  _normalizeAgentMdRecord(aid, data) {
+    if (!isJsonObject(data)) return {};
+    const record = {};
+    for (const [key, value] of Object.entries(data)) {
+      if (key !== "content") record[key] = value;
     }
-    await this._writeAgentMdListUnlocked(records);
-    this._agentMdCache.clear();
-    return records;
+    record.aid = this._agentMdSafeAid(String(record.aid ?? aid));
+    for (const key of ["fetched_at", "observed_at", "checked_at", "updated_at"]) {
+      record[key] = Number(record[key] ?? 0) || 0;
+    }
+    return record;
   }
-  async _readAgentMdListUnlocked() {
-    const raw = await this._readAgentMdStorage(this._agentMdListKey());
-    if (raw === null) {
-      return await this._rebuildAgentMdListUnlocked();
+  async _writeAgentMdRecordUnlocked(aid, record) {
+    const payload = {};
+    for (const [key, value] of Object.entries(record)) {
+      if (key !== "content" && value !== void 0 && value !== null) payload[key] = value;
     }
+    payload.aid = this._agentMdSafeAid(aid);
+    await this._writeAgentMdStorage(this._agentMdMetaKey(aid), `${JSON.stringify(payload, null, 2)}
+`);
+  }
+  async _readAgentMdRecordUnlocked(aid) {
+    const raw = await this._readAgentMdStorage(this._agentMdMetaKey(aid));
+    if (raw === null) return {};
     try {
-      return this._normalizeAgentMdList(JSON.parse(raw));
+      return this._normalizeAgentMdRecord(aid, JSON.parse(raw));
     } catch (err) {
-      this._clientLog.warn(`agent.md list.json damaged, rebuilding: ${err instanceof Error ? err.message : String(err)}`);
-      return await this._rebuildAgentMdListUnlocked();
+      this._clientLog.warn(`agent.md metadata damaged, ignoring: aid=${aid} err=${err instanceof Error ? err.message : String(err)}`);
+      return {};
     }
   }
   async _readAgentMdContent(aid) {
@@ -11727,20 +11969,28 @@ var _AUNClient = class _AUNClient {
     const target = String(aid ?? "").trim();
     if (!target) return null;
     try {
-      const records = await this._withAgentMdListLock(async () => await this._readAgentMdListUnlocked());
-      const record = records[target];
-      if (record && typeof record === "object") {
-        const loaded = { ...record, aid: target };
-        const content = await this._readAgentMdContent(target);
-        if (content !== null) {
-          loaded.content = content;
-          loaded.local_etag = await this._agentMdContentEtag(content);
-        } else {
-          this._clientLog.warn(`agent.md content read failed: aid=${target}`);
+      const loaded = await this._withAgentMdLock(async () => {
+        const record = await this._readAgentMdRecordUnlocked(target);
+        const next = Object.keys(record).length > 0 ? { ...record, aid: target } : { aid: target };
+        try {
+          const content = await this._readAgentMdContent(target);
+          if (content !== null) {
+            next.content = content;
+            next.local_etag = await this._agentMdContentEtag(content);
+          } else {
+            const metaRaw = await this._readAgentMdStorage(this._agentMdMetaKey(target));
+            if (metaRaw !== null) {
+              this._clientLog.warn(`agent.md content read failed: aid=${target}`);
+            }
+          }
+        } catch (err) {
+          this._clientLog.warn(`agent.md content read failed: aid=${target} err=${err instanceof Error ? err.message : String(err)}`);
         }
-        this._agentMdCache.set(target, { ...loaded });
-        return { ...loaded };
-      }
+        return next;
+      });
+      if (Object.keys(loaded).length <= 1) return null;
+      this._agentMdCache.set(target, { ...loaded });
+      return { ...loaded };
     } catch (err) {
       this._clientLog.debug(`agent.md cache load skipped: aid=${target} err=${err instanceof Error ? err.message : String(err)}`);
     }
@@ -11759,15 +12009,13 @@ var _AUNClient = class _AUNClient {
         if (!inputFields.fetched_at) inputFields.fetched_at = Date.now();
       }
       delete inputFields.content;
-      const record = await this._withAgentMdListLock(async () => {
-        const records = await this._readAgentMdListUnlocked();
-        const next = { ...records[target] ?? {}, aid: target };
+      const record = await this._withAgentMdLock(async () => {
+        const next = { ...await this._readAgentMdRecordUnlocked(target), aid: target };
         for (const [key, value] of Object.entries(inputFields)) {
           if (value !== void 0 && value !== null) next[key] = value;
         }
         next.updated_at = Date.now();
-        records[target] = { ...next };
-        await this._writeAgentMdListUnlocked(records);
+        await this._writeAgentMdRecordUnlocked(target, next);
         return next;
       });
       const loaded = { ...record };
@@ -12219,6 +12467,19 @@ var _AUNClient = class _AUNClient {
         return this._putMessageThoughtEncryptedV2(p);
       }
     }
+    const pullGateKey = this._pullGateKeyForCall(method, p);
+    if (pullGateKey) {
+      return await this._runPullSerialized(pullGateKey, async () => {
+        return await this._callImplInner(method, p);
+      });
+    }
+    return await this._callImplInner(method, p);
+  }
+  /**
+   * _callImpl 的内层：pull gate 之后的实际 RPC 分发逻辑。
+   * 拆分出来以便 pull gate 包裹整个操作。
+   */
+  async _callImplInner(method, p) {
     if (method === "message.pull" && this._v2Session) {
       this._clientLog.debug("call route: message.pull \u2192 V2 pull");
       const messages = await this.pullV2(Number(p.after_seq ?? 0) || 0, Number(p.limit ?? 50) || 50);
@@ -14786,7 +15047,10 @@ var _AUNClient = class _AUNClient {
       const session = this._v2Session;
       if (session && fromAid) {
         try {
-          const bs = await this.call("message.v2.bootstrap", { peer_aid: fromAid });
+          const bs = await this.call("message.v2.bootstrap", {
+            peer_aid: fromAid,
+            e2ee_wrap_capabilities: v2WrapCapabilities()
+          });
           const peers = Array.isArray(bs?.peer_devices) ? bs.peer_devices : [];
           for (const dev of peers) this._cacheV2PeerIKFromDevice(dev, fromAid);
         } catch (exc) {
@@ -14794,7 +15058,10 @@ var _AUNClient = class _AUNClient {
         }
         if (groupId) {
           try {
-            const gbs = await this.call("group.v2.bootstrap", { group_id: groupId });
+            const gbs = await this.call("group.v2.bootstrap", {
+              group_id: groupId,
+              e2ee_wrap_capabilities: v2WrapCapabilities()
+            });
             const devices = Array.isArray(gbs?.devices) ? gbs.devices : [];
             const audit = Array.isArray(gbs?.audit_recipients) ? gbs.audit_recipients : [];
             for (const dev of devices) this._cacheV2PeerIKFromDevice(dev);
@@ -15040,7 +15307,7 @@ var _AUNClient = class _AUNClient {
       spkId = String(msg.spk_id ?? "");
       if (!spkId) {
         for (const row of envelope.recipients) {
-          if (Array.isArray(row) && row.length >= 6 && row[0] === this._aid && row[1] === this._deviceId) {
+          if (Array.isArray(row) && row.length >= 6 && row[0] === this._aid && (row[1] === this._deviceId || row[1] === "")) {
             spkId = String(row[5] ?? "");
             recipientKeySource = row.length > 3 ? String(row[3] ?? "") : "";
             break;
@@ -15048,7 +15315,7 @@ var _AUNClient = class _AUNClient {
         }
       } else {
         for (const row of envelope.recipients) {
-          if (Array.isArray(row) && row.length >= 6 && row[0] === this._aid && row[1] === this._deviceId) {
+          if (Array.isArray(row) && row.length >= 6 && row[0] === this._aid && (row[1] === this._deviceId || row[1] === "")) {
             recipientKeySource = row.length > 3 ? String(row[3] ?? "") : "";
             break;
           }
@@ -15397,19 +15664,26 @@ var _AUNClient = class _AUNClient {
     const useCache = opts.useCache !== false;
     let peerDevices = [];
     let auditRaw = [];
+    let wrapPolicy;
     const cached = useCache ? this._v2BootstrapCache.get(to) : void 0;
     if (cached && Date.now() - cached.cachedAt < _AUNClient.V2_BOOTSTRAP_TTL_MS) {
       peerDevices = cached.devices;
       auditRaw = cached.auditRecipients;
+      wrapPolicy = cached.wrapPolicy;
     } else {
-      const bs = await this.call("message.v2.bootstrap", { peer_aid: to });
+      const bs = await this.call("message.v2.bootstrap", {
+        peer_aid: to,
+        e2ee_wrap_capabilities: v2WrapCapabilities()
+      });
       peerDevices = Array.isArray(bs?.peer_devices) ? bs.peer_devices : [];
       auditRaw = Array.isArray(bs?.audit_recipients) ? bs.audit_recipients : [];
+      wrapPolicy = normalizeV2WrapPolicy(bs?.e2ee_wrap_policy);
       if (peerDevices.length > 0) {
         this._v2BootstrapCache.set(to, {
           devices: peerDevices,
           auditRecipients: auditRaw,
-          cachedAt: Date.now()
+          cachedAt: Date.now(),
+          wrapPolicy
         });
       }
     }
@@ -15445,7 +15719,10 @@ var _AUNClient = class _AUNClient {
         if (selfCached && Date.now() - selfCached.cachedAt < _AUNClient.V2_BOOTSTRAP_TTL_MS) {
           selfDevices = selfCached.devices;
         } else {
-          const selfBs = await this.call("message.v2.bootstrap", { peer_aid: this._aid });
+          const selfBs = await this.call("message.v2.bootstrap", {
+            peer_aid: this._aid,
+            e2ee_wrap_capabilities: v2WrapCapabilities()
+          });
           selfDevices = Array.isArray(selfBs?.peer_devices) ? selfBs.peer_devices : [];
           if (selfDevices.length > 0) {
             this._v2BootstrapCache.set(this._aid, {
@@ -15472,9 +15749,10 @@ var _AUNClient = class _AUNClient {
       }
     }
     const sender = await session.getSenderIdentity();
+    const sendTargets = applyV2WrapPolicyToTargets(targets, wrapPolicy);
     const envelope = await encryptP2PMessage(
       sender,
-      { targets, auditRecipients: [] },
+      { targets: sendTargets, auditRecipients: [] },
       opts.payload,
       { messageId: opts.messageId, timestamp: opts.timestamp, protectedHeaders: opts.protectedHeaders, context: opts.context }
     );
@@ -15547,17 +15825,23 @@ var _AUNClient = class _AUNClient {
     let epoch = 0;
     let stateCommitment = { state_version: 0, state_hash: "", state_chain: "" };
     let auditRecipientsRaw = [];
+    let wrapPolicy;
     const cached = useCache ? this._v2BootstrapCache.get(cacheKey) : void 0;
     if (cached && Date.now() - cached.cachedAt < _AUNClient.V2_BOOTSTRAP_TTL_MS) {
       allDevices = cached.devices;
       epoch = cached.epoch ?? 0;
       stateCommitment = cached.stateCommitment ?? { state_version: 0, state_hash: "", state_chain: "" };
       auditRecipientsRaw = cached.auditRecipients;
+      wrapPolicy = cached.wrapPolicy;
     } else {
-      const bs = await this.call("group.v2.bootstrap", { group_id: groupId });
+      const bs = await this.call("group.v2.bootstrap", {
+        group_id: groupId,
+        e2ee_wrap_capabilities: v2WrapCapabilities()
+      });
       allDevices = Array.isArray(bs?.devices) ? bs.devices : [];
       epoch = Number(bs?.epoch ?? 0);
       auditRecipientsRaw = Array.isArray(bs?.audit_recipients) ? bs.audit_recipients : [];
+      wrapPolicy = normalizeV2WrapPolicy(bs?.e2ee_wrap_policy);
       await this._v2CheckFork(groupId, String(bs?.state_chain ?? ""));
       await this._v2VerifyStateSignature(groupId, bs);
       await this._publishV2GroupSecurityLevel(groupId, bs);
@@ -15572,7 +15856,8 @@ var _AUNClient = class _AUNClient {
           auditRecipients: auditRecipientsRaw,
           cachedAt: Date.now(),
           epoch,
-          stateCommitment
+          stateCommitment,
+          wrapPolicy
         });
       }
       const pendingAdds = Array.isArray(bs?.pending_adds) ? bs.pending_adds : [];
@@ -15612,11 +15897,12 @@ var _AUNClient = class _AUNClient {
       throw new E2EEError(`V2 group: no target devices for ${groupId}`);
     }
     const sender = await session.getSenderIdentity();
+    const sendTargets = applyV2WrapPolicyToTargets(targets, wrapPolicy);
     const envelope = await encryptGroupMessage(
       sender,
       groupId,
       epoch,
-      targets,
+      sendTargets,
       opts.payload,
       { messageId: opts.messageId, timestamp: opts.timestamp, protectedHeaders: opts.protectedHeaders, context: opts.context },
       stateCommitment
@@ -15697,7 +15983,7 @@ var _AUNClient = class _AUNClient {
     if (Array.isArray(recipients)) {
       for (const row of recipients) {
         if (Array.isArray(row) && row.length >= 6) {
-          if (row[0] === this._aid && row[1] === this._deviceId) {
+          if (row[0] === this._aid && (row[1] === this._deviceId || row[1] === "")) {
             spkId = String(row[5] ?? "");
             recipientKeySource = row.length > 3 ? String(row[3] ?? "") : "";
             break;
@@ -15976,7 +16262,10 @@ var _AUNClient = class _AUNClient {
         if (aid === myAid) myRole = role;
       }
       if (myRole !== "owner" && myRole !== "admin") return false;
-      const bootstrapResp = await this.call("group.v2.bootstrap", { group_id: groupId });
+      const bootstrapResp = await this.call("group.v2.bootstrap", {
+        group_id: groupId,
+        e2ee_wrap_capabilities: v2WrapCapabilities()
+      });
       const devices = Array.isArray(bootstrapResp?.devices) ? bootstrapResp.devices : [];
       const candidates = [];
       for (const dev of devices) {
@@ -16065,7 +16354,10 @@ var _AUNClient = class _AUNClient {
           }
         }
       }
-      const bootstrapResp = await this.call("group.v2.bootstrap", { group_id: groupId });
+      const bootstrapResp = await this.call("group.v2.bootstrap", {
+        group_id: groupId,
+        e2ee_wrap_capabilities: v2WrapCapabilities()
+      });
       const allDevices = Array.isArray(bootstrapResp?.devices) ? bootstrapResp.devices : [];
       const auditRecipients = Array.isArray(bootstrapResp?.audit_recipients) ? bootstrapResp.audit_recipients : [];
       const auditAidsList = [...new Set(
@@ -16374,6 +16666,62 @@ var _AUNClient = class _AUNClient {
       this._clientLog.warn(`background task exception:${String(exc)}`);
     });
   }
+  // ── Pull Gate（序列化同一 key 的并发 pull）──────────────────
+  _pullGateKeyForCall(method, params) {
+    if (method === "message.pull" || method === "message.v2.pull") {
+      return this._aid ? `p2p:${this._aid}` : "";
+    }
+    if (method === "group.pull" || method === "group.v2.pull") {
+      const gid = String(params.group_id ?? "").trim();
+      return gid ? `group:${gid}` : "";
+    }
+    if (method === "group.pull_events") {
+      const gid = String(params.group_id ?? "").trim();
+      return gid ? `group_event:${gid}` : "";
+    }
+    return "";
+  }
+  _tryAcquirePullGate(key) {
+    if (!key) return 0;
+    const now = Date.now();
+    const gate = this._pullGates.get(key) ?? { inflight: false, startedAt: 0, token: 0 };
+    if (gate.inflight && now - gate.startedAt <= _AUNClient._PULL_GATE_STALE_MS) {
+      return null;
+    }
+    if (gate.inflight) {
+      this._clientLog.warn(`pull in-flight stale reset: key=${key} age=${now - gate.startedAt}ms`);
+    }
+    gate.token += 1;
+    gate.inflight = true;
+    gate.startedAt = now;
+    this._pullGates.set(key, gate);
+    return gate.token;
+  }
+  _releasePullGate(key, token) {
+    if (!key || token == null) return;
+    const gate = this._pullGates.get(key);
+    if (!gate || gate.token !== token) return;
+    gate.inflight = false;
+    gate.startedAt = 0;
+  }
+  async _runPullSerialized(key, operation) {
+    let token = this._tryAcquirePullGate(key);
+    if (token === null) {
+      const deadline = Date.now() + _AUNClient._PULL_GATE_STALE_MS + 100;
+      while (token === null && Date.now() <= deadline) {
+        await this._sleep(25);
+        token = this._tryAcquirePullGate(key);
+      }
+      if (token === null) {
+        throw new StateError(`pull already in-flight for ${key}`);
+      }
+    }
+    try {
+      return await operation();
+    } finally {
+      this._releasePullGate(key, token);
+    }
+  }
   /** 可取消的 sleep */
   _sleep(ms) {
     return new Promise((resolve) => {
@@ -16385,6 +16733,7 @@ __publicField(_AUNClient, "V2_BOOTSTRAP_TTL_MS", 60 * 60 * 1e3);
 __publicField(_AUNClient, "V2_RETRYABLE_CODES", /* @__PURE__ */ new Set([-33011, -33012, -33050, -33052, -33054]));
 __publicField(_AUNClient, "_V2_SIG_CACHE_TTL", 60 * 60 * 1e3);
 __publicField(_AUNClient, "_V2_SIG_CACHE_MAX", 16384);
+__publicField(_AUNClient, "_PULL_GATE_STALE_MS", 3e4);
 // ── 内部：断线重连 ────────────────────────────────
 /** 不重连 close code 集合：认证失败/权限错误/被踢等，重连无意义 */
 __publicField(_AUNClient, "_NO_RECONNECT_CODES", /* @__PURE__ */ new Set([4001, 4003, 4008, 4009, 4010, 4011, 4012, 4013, 4014, 4015]));
@@ -16455,7 +16804,7 @@ var ProtectedHeaders = class _ProtectedHeaders {
 };
 
 // src/index.ts
-var __version__ = "0.3.2";
+var __version__ = "0.3.4";
 export {
   AUNClient,
   AUNError,
@@ -16480,6 +16829,7 @@ export {
   GroupError,
   GroupNotFoundError,
   GroupStateError,
+  IdentityConflictError,
   IndexedDBKeyStore,
   IndexedDBSecretStore,
   MetaNamespace,
@@ -16490,6 +16840,7 @@ export {
   RPCTransport,
   RateLimitError,
   STATE_PREFIX,
+  SeedMigrationError,
   SerializationError,
   SessionError,
   StateError,