npm - @agentunion/fastaun-browser - Versions diffs - 0.3.4 → 0.3.5 - Mend

@agentunion/fastaun-browser 0.3.4 → 0.3.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (17) hide show

package/CHANGELOG.md +113 -111
package/_packed_docs/CHANGELOG.md +113 -111
package/_packed_docs/INDEX.md +16 -16
package/_packed_docs/KITE_DOCS_GUIDE.md +7 -7
package/_packed_docs/design/E2EE_V2/347/256/200/345/214/226/344/270/2721DH/345/212/240Per-AID_Wrap/346/226/271/346/241/210.md +124 -0
package/_packed_docs/sdk/04-/350/277/236/346/216/245/344/270/216/350/256/244/350/257/201.md +469 -454
package/_packed_docs/sdk/06-API/346/211/213/345/206/214.md +1475 -1410
package/dist/auth.js +1 -1
package/dist/bundle.js +27 -3
package/dist/index.d.ts +1 -1
package/dist/index.js +1 -1
package/dist/namespaces/auth.d.ts +6 -0
package/dist/namespaces/auth.d.ts.map +1 -1
package/dist/namespaces/auth.js +25 -0
package/dist/namespaces/auth.js.map +1 -1
package/dist/v2/e2ee/encrypt-p2p.js +1 -1
package/package.json +1 -1

package/CHANGELOG.md CHANGED Viewed

@@ -1,111 +1,113 @@
-# Changelog
-本文件记录 `@agentunion/fastaun-browser` SDK 的版本变更。最新版本在最前面。
-格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)；版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)。
----
-## 0.3.4 — 2026-05-28
-### Breaking Changes
-- **`createAid()` → `registerAid()`**：客户端 API 重命名，旧方法已移除
-- **注册与认证分离**：`authenticate()` 不再隐式注册；身份不完整时抛 `StateError`
-### Added
-- **`IdentityConflictError`**：新增错误类型（继承 `AuthError`），AID 注册冲突时抛出
-- **Pull Gate**：per-key 序列化 pull 操作，防止同一 namespace 并发 pull
-- **RPC Inflight 限制**：transport 层全局最大 16 个并发 RPC + 后台 RPC 独立限制 8 个，排队超时抛 `TimeoutError`
-- **`_assertCertMatchesLocalKeypair`**：authenticate 前显式校验 cert 公钥与本地 keypair 一致
-- **`_downloadRegisteredCert`**：注册前查服务端证书的辅助方法
-### Changed
-- **`registerAid` 半成品恢复**：本地有 keypair 无 cert 时，查服务端恢复；服务端无记录则用现有 keypair 注册
-- **agent.md 元数据存储**：从全局 `list.json` key 改为 per-AID `{aid}/agentmd.json` key（IndexedDB）
-- **agent.md 下载**：改为无条件 GET；302 显式跟随；304 时本地有缓存直接用，无缓存重试
-- **`_loadIdentityOrRaise`**：增加 keypair 完整性检查
-- **`ChangeSeed` API**：`IndexedDBKeyStore.changeSeed()` 支持更换 seed（重加密私钥）
-### Removed
-- **`_ensureLocalIdentity` / `_ensureIdentity`**：已移除，注册路径不再隐式生成密钥
-- **`createAid` 方法**：已移除
----
-## 0.3.3 — 2026-05-25
-### Added
-- **V2 Thought 加解密**：`group.thought.get` / `message.thought.get` 返回值自动解密；发送端自动加密；`attachV2EnvelopeMetadata` 附加 E2EE 元数据
-- **V2 Sender IK 延迟解密**：`_v2SenderIKPending` / `_v2SenderIKFetching` 机制，对端 IK 未缓存时挂起消息、异步拉取后重试解密
-- **agent.md 本地缓存体系（浏览器版本）**：`publishAgentMd(content?)` / `fetchAgentMd(aid?)`；基于 IndexedDB/localStorage 的 list + 按 AID 存储 + etag 比对 + 自动拉取缺失
-- **V2 辅助函数**：`getV2DeviceId` / `_v2B64ToBytesStrict` / `_v2BytesEqual` / `_v2ConcatBytes` / `_v2LengthPrefixedTextKey` / `_v2LengthPrefixedBytes`
-- **V2 envelope 元数据**：`attachV2EnvelopeMetadata` / `attachV2EnvelopeMetadataFromSource` / `extractV2EnvelopeFromSource` / `metadataWithoutAuth`
-### Changed
-- **V2 消息处理路径重构**：统一 P2P/Group 解密入口，支持 sender IK pending 延迟模式
-- **V2 SPK rotation**：thought 解密失败时触发 group SPK rotation / registration after peer fallback
-### Fixed
-- **service-plane envelope 解包**：修复 Kernel trace 字段传递丢失
-- **trace 树状展示**：enter/exit 配对 + 嵌套缩进
----
-## 0.3.1 — 2026-05-22
-### Added
-- **`auth.checkAid` handler**：本地证书自检 + 远端注册状态查询（与 Node 版对齐）
-- **RPC trace 增强（浏览器版本）**：`RPCTransport` 增加 `setTraceMode()` / `setTraceObserver()`；`sortTraceSpansForDisplay` / `formatTraceTree` / `traceDisplay` 树状展示
-- **V2 群组 SPK 生命周期**：`V2KeyStore.saveGroupSPK` / `loadGroupSPK` / `loadCurrentGroupSPK` 基于 IndexedDB 持久化；`V2Session.ensureGroupSPK` / `ensureGroupRegistered` / `rotateGroupSPK` / `getGroupDecryptKeys`；`DESTROY_DELAY_MS = 7d`
-- **V2 P2P push 解密**：`AUNClient` 增加 push payload 就地解密路径，失败回退到 pull
-### Changed
-- **`SeqTracker.forceContiguousSeq`**：原 `contiguousSeq = minSeq` 跳过空洞（会丢消息），改为 `contiguousSeq = minSeq - 1` 由连续前缀自然推进
-### Fixed
-- short RPC 请求增加 `debug` 完整报文日志，便于跨语言诊断
----
-## 0.3.0 — 2026-05-21 ⚠️ BREAKING CHANGE
-> **V2-only 版本**：移除全部 V1 E2EE（含群组加密），新增 V2 加密原语，API 不向后兼容。
-### BREAKING
-- **移除 V1 E2EE 全部实现**：`e2ee-group.ts`、V1 epoch key 逻辑全部删除
-- **移除 V1 群组加密测试**：`e2ee.spec.ts`、`epoch-key-server.spec.ts`、`group-e2ee.spec.ts`、`group-join-key-recovery.spec.ts` 等
-- **E2EE 接口简化**：`e2ee.ts` 仅保留 V2 路径，V1 加解密方法不再可用
-- **配置变更**：`config.ts` 移除 V1 相关配置项
-### Added
-- **agent.md 主 API（浏览器版本）**：`AUNClient.publishAgentMd(content)` / `AUNClient.fetchAgentMd(aid?)`
-- **V2 加密原语**（跨语言 golden vector 一致性）：ECDH P-256、HKDF-SHA256、AES-256-GCM、ECDSA-SHA256 RAW、1DH/3DH wrap_key、Recipients Sort + Merkle Digest、State Commitment
-- **V2 Session**：SPK 生命周期 + 对端 IK 缓存 + PFS 三重销毁
-- **V2 KeyStore**：IndexedDB 持久化 SPK/IK 异步实现
-### Removed
-- `AUNClient.setLocalAgentMdContent()` / `getLocalAgentMdEtag()` / `getRemoteAgentMdEtag()` — 由主 API 自动维护
-### Deprecated
-- `client.auth.signAgentMd` / `verifyAgentMd` / `uploadAgentMd` / `downloadAgentMd` — 建议迁移到 `client.publishAgentMd` / `client.fetchAgentMd`
----
-## 0.2.20 — 2026-05-18
-### Added
-- **agent.md 版本一致性 API（浏览器版本）**：
-  - `AUNClient.setLocalAgentMdContent(content: string): Promise<string>`：浏览器无法读本地文件，改为接收 markdown 文本字符串，用 `crypto.subtle.digest('SHA-256', ...)` 计算 etag。业务侧可用 `<input type=file>` 读出文本传入。
-  - `AUNClient.getLocalAgentMdEtag(): string` / `getRemoteAgentMdEtag(): string`。
-- SDK 自动从 RPC envelope `_meta.agent_md_etag` 提取服务端 etag，应用层订阅 `message.received` / `group.message_created` 等事件时 payload 多 `_agent_md.{local_etag, remote_etag}` 字段供版本比对。
-- **`downloadAgentMd` 条件请求缓存**：内部维护 ETag/Last-Modified，未变化时返回上次缓存内容；外部 API 形态不变。
-- **transport meta observer**：`RPCTransport.setMetaObserver(fn)` 透传 envelope `_meta`，observer 抛错被吞，不影响 RPC result。
-### Changed
-- **RPC call 默认超时 10s → 35s**：与服务端 30s handler timeout 对齐，留 5s buffer。
-- **multi-device 架构**：对端无 prekey 时 `_sendEncrypted` 直接抛错（`no registered device prekeys for ...`），不再降级到 `long_term_key`。
-### Docs
-- 仓库根 `docs/`（agent.md 规范、protocol、SDK 手册）随 npm tarball 打包到 `_packed_docs/`，安装后可读。`.gitignore` 排除项（如内部测试指南）不进包。
----
+# Changelog
+本文件记录 `@agentunion/fastaun-browser` SDK 的版本变更。最新版本在最前面。
+格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)；版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)。
+---
+## 0.3.5 — 2026-05-28
+### Breaking Changes
+- **`createAid()` → `registerAid()`**：客户端 API 重命名，旧方法已移除
+- **注册与认证分离**：`authenticate()` 不再隐式注册；身份不完整时抛 `StateError`
+### Added
+- **`IdentityConflictError`**：新增错误类型（继承 `AuthError`），AID 注册冲突时抛出
+- **`auth.loadIdentity()` / `auth.loadIdentityOrNull()`**：公开 API，只读加载本地已注册身份（密钥对 + 证书 + 实例状态），无副作用
+- **`auth.fetchPeerCert()`**：公开 API，获取对端 AID 证书 PEM（本地缓存优先，未命中走 PKI HTTP + 链验证）
+- **Pull Gate**：per-key 序列化 pull 操作，防止同一 namespace 并发 pull
+- **RPC Inflight 限制**：transport 层全局最大 16 个并发 RPC + 后台 RPC 独立限制 8 个，排队超时抛 `TimeoutError`
+- **`_assertCertMatchesLocalKeypair`**：authenticate 前显式校验 cert 公钥与本地 keypair 一致
+- **`_downloadRegisteredCert`**：注册前查服务端证书的辅助方法
+### Changed
+- **`registerAid` 半成品恢复**：本地有 keypair 无 cert 时，查服务端恢复；服务端无记录则用现有 keypair 注册
+- **agent.md 元数据存储**：从全局 `list.json` key 改为 per-AID `{aid}/agentmd.json` key（IndexedDB）
+- **agent.md 下载**：改为无条件 GET；302 显式跟随；304 时本地有缓存直接用，无缓存重试
+- **`_loadIdentityOrRaise`**：增加 keypair 完整性检查
+- **`ChangeSeed` API**：`IndexedDBKeyStore.changeSeed()` 支持更换 seed（重加密私钥）
+### Removed
+- **`_ensureLocalIdentity` / `_ensureIdentity`**：已移除，注册路径不再隐式生成密钥
+- **`createAid` 方法**：已移除
+---
+## 0.3.3 — 2026-05-25
+### Added
+- **V2 Thought 加解密**：`group.thought.get` / `message.thought.get` 返回值自动解密；发送端自动加密；`attachV2EnvelopeMetadata` 附加 E2EE 元数据
+- **V2 Sender IK 延迟解密**：`_v2SenderIKPending` / `_v2SenderIKFetching` 机制，对端 IK 未缓存时挂起消息、异步拉取后重试解密
+- **agent.md 本地缓存体系（浏览器版本）**：`publishAgentMd(content?)` / `fetchAgentMd(aid?)`；基于 IndexedDB/localStorage 的 list + 按 AID 存储 + etag 比对 + 自动拉取缺失
+- **V2 辅助函数**：`getV2DeviceId` / `_v2B64ToBytesStrict` / `_v2BytesEqual` / `_v2ConcatBytes` / `_v2LengthPrefixedTextKey` / `_v2LengthPrefixedBytes`
+- **V2 envelope 元数据**：`attachV2EnvelopeMetadata` / `attachV2EnvelopeMetadataFromSource` / `extractV2EnvelopeFromSource` / `metadataWithoutAuth`
+### Changed
+- **V2 消息处理路径重构**：统一 P2P/Group 解密入口，支持 sender IK pending 延迟模式
+- **V2 SPK rotation**：thought 解密失败时触发 group SPK rotation / registration after peer fallback
+### Fixed
+- **service-plane envelope 解包**：修复 Kernel trace 字段传递丢失
+- **trace 树状展示**：enter/exit 配对 + 嵌套缩进
+---
+## 0.3.1 — 2026-05-22
+### Added
+- **`auth.checkAid` handler**：本地证书自检 + 远端注册状态查询（与 Node 版对齐）
+- **RPC trace 增强（浏览器版本）**：`RPCTransport` 增加 `setTraceMode()` / `setTraceObserver()`；`sortTraceSpansForDisplay` / `formatTraceTree` / `traceDisplay` 树状展示
+- **V2 群组 SPK 生命周期**：`V2KeyStore.saveGroupSPK` / `loadGroupSPK` / `loadCurrentGroupSPK` 基于 IndexedDB 持久化；`V2Session.ensureGroupSPK` / `ensureGroupRegistered` / `rotateGroupSPK` / `getGroupDecryptKeys`；`DESTROY_DELAY_MS = 7d`
+- **V2 P2P push 解密**：`AUNClient` 增加 push payload 就地解密路径，失败回退到 pull
+### Changed
+- **`SeqTracker.forceContiguousSeq`**：原 `contiguousSeq = minSeq` 跳过空洞（会丢消息），改为 `contiguousSeq = minSeq - 1` 由连续前缀自然推进
+### Fixed
+- short RPC 请求增加 `debug` 完整报文日志，便于跨语言诊断
+---
+## 0.3.0 — 2026-05-21 ⚠️ BREAKING CHANGE
+> **V2-only 版本**：移除全部 V1 E2EE（含群组加密），新增 V2 加密原语，API 不向后兼容。
+### BREAKING
+- **移除 V1 E2EE 全部实现**：`e2ee-group.ts`、V1 epoch key 逻辑全部删除
+- **移除 V1 群组加密测试**：`e2ee.spec.ts`、`epoch-key-server.spec.ts`、`group-e2ee.spec.ts`、`group-join-key-recovery.spec.ts` 等
+- **E2EE 接口简化**：`e2ee.ts` 仅保留 V2 路径，V1 加解密方法不再可用
+- **配置变更**：`config.ts` 移除 V1 相关配置项
+### Added
+- **agent.md 主 API（浏览器版本）**：`AUNClient.publishAgentMd(content)` / `AUNClient.fetchAgentMd(aid?)`
+- **V2 加密原语**（跨语言 golden vector 一致性）：ECDH P-256、HKDF-SHA256、AES-256-GCM、ECDSA-SHA256 RAW、1DH/3DH wrap_key、Recipients Sort + Merkle Digest、State Commitment
+- **V2 Session**：SPK 生命周期 + 对端 IK 缓存 + PFS 三重销毁
+- **V2 KeyStore**：IndexedDB 持久化 SPK/IK 异步实现
+### Removed
+- `AUNClient.setLocalAgentMdContent()` / `getLocalAgentMdEtag()` / `getRemoteAgentMdEtag()` — 由主 API 自动维护
+### Deprecated
+- `client.auth.signAgentMd` / `verifyAgentMd` / `uploadAgentMd` / `downloadAgentMd` — 建议迁移到 `client.publishAgentMd` / `client.fetchAgentMd`
+---
+## 0.2.20 — 2026-05-18
+### Added
+- **agent.md 版本一致性 API（浏览器版本）**：
+  - `AUNClient.setLocalAgentMdContent(content: string): Promise<string>`：浏览器无法读本地文件，改为接收 markdown 文本字符串，用 `crypto.subtle.digest('SHA-256', ...)` 计算 etag。业务侧可用 `<input type=file>` 读出文本传入。
+  - `AUNClient.getLocalAgentMdEtag(): string` / `getRemoteAgentMdEtag(): string`。
+- SDK 自动从 RPC envelope `_meta.agent_md_etag` 提取服务端 etag，应用层订阅 `message.received` / `group.message_created` 等事件时 payload 多 `_agent_md.{local_etag, remote_etag}` 字段供版本比对。
+- **`downloadAgentMd` 条件请求缓存**：内部维护 ETag/Last-Modified，未变化时返回上次缓存内容；外部 API 形态不变。
+- **transport meta observer**：`RPCTransport.setMetaObserver(fn)` 透传 envelope `_meta`，observer 抛错被吞，不影响 RPC result。
+### Changed
+- **RPC call 默认超时 10s → 35s**：与服务端 30s handler timeout 对齐，留 5s buffer。
+- **multi-device 架构**：对端无 prekey 时 `_sendEncrypted` 直接抛错（`no registered device prekeys for ...`），不再降级到 `long_term_key`。
+### Docs
+- 仓库根 `docs/`（agent.md 规范、protocol、SDK 手册）随 npm tarball 打包到 `_packed_docs/`，安装后可读。`.gitignore` 排除项（如内部测试指南）不进包。
+---

package/_packed_docs/CHANGELOG.md CHANGED Viewed

@@ -1,111 +1,113 @@
-# Changelog
-本文件记录 `@agentunion/fastaun-browser` SDK 的版本变更。最新版本在最前面。
-格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)；版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)。
----
-## 0.3.4 — 2026-05-28
-### Breaking Changes
-- **`createAid()` → `registerAid()`**：客户端 API 重命名，旧方法已移除
-- **注册与认证分离**：`authenticate()` 不再隐式注册；身份不完整时抛 `StateError`
-### Added
-- **`IdentityConflictError`**：新增错误类型（继承 `AuthError`），AID 注册冲突时抛出
-- **Pull Gate**：per-key 序列化 pull 操作，防止同一 namespace 并发 pull
-- **RPC Inflight 限制**：transport 层全局最大 16 个并发 RPC + 后台 RPC 独立限制 8 个，排队超时抛 `TimeoutError`
-- **`_assertCertMatchesLocalKeypair`**：authenticate 前显式校验 cert 公钥与本地 keypair 一致
-- **`_downloadRegisteredCert`**：注册前查服务端证书的辅助方法
-### Changed
-- **`registerAid` 半成品恢复**：本地有 keypair 无 cert 时，查服务端恢复；服务端无记录则用现有 keypair 注册
-- **agent.md 元数据存储**：从全局 `list.json` key 改为 per-AID `{aid}/agentmd.json` key（IndexedDB）
-- **agent.md 下载**：改为无条件 GET；302 显式跟随；304 时本地有缓存直接用，无缓存重试
-- **`_loadIdentityOrRaise`**：增加 keypair 完整性检查
-- **`ChangeSeed` API**：`IndexedDBKeyStore.changeSeed()` 支持更换 seed（重加密私钥）
-### Removed
-- **`_ensureLocalIdentity` / `_ensureIdentity`**：已移除，注册路径不再隐式生成密钥
-- **`createAid` 方法**：已移除
----
-## 0.3.3 — 2026-05-25
-### Added
-- **V2 Thought 加解密**：`group.thought.get` / `message.thought.get` 返回值自动解密；发送端自动加密；`attachV2EnvelopeMetadata` 附加 E2EE 元数据
-- **V2 Sender IK 延迟解密**：`_v2SenderIKPending` / `_v2SenderIKFetching` 机制，对端 IK 未缓存时挂起消息、异步拉取后重试解密
-- **agent.md 本地缓存体系（浏览器版本）**：`publishAgentMd(content?)` / `fetchAgentMd(aid?)`；基于 IndexedDB/localStorage 的 list + 按 AID 存储 + etag 比对 + 自动拉取缺失
-- **V2 辅助函数**：`getV2DeviceId` / `_v2B64ToBytesStrict` / `_v2BytesEqual` / `_v2ConcatBytes` / `_v2LengthPrefixedTextKey` / `_v2LengthPrefixedBytes`
-- **V2 envelope 元数据**：`attachV2EnvelopeMetadata` / `attachV2EnvelopeMetadataFromSource` / `extractV2EnvelopeFromSource` / `metadataWithoutAuth`
-### Changed
-- **V2 消息处理路径重构**：统一 P2P/Group 解密入口，支持 sender IK pending 延迟模式
-- **V2 SPK rotation**：thought 解密失败时触发 group SPK rotation / registration after peer fallback
-### Fixed
-- **service-plane envelope 解包**：修复 Kernel trace 字段传递丢失
-- **trace 树状展示**：enter/exit 配对 + 嵌套缩进
----
-## 0.3.1 — 2026-05-22
-### Added
-- **`auth.checkAid` handler**：本地证书自检 + 远端注册状态查询（与 Node 版对齐）
-- **RPC trace 增强（浏览器版本）**：`RPCTransport` 增加 `setTraceMode()` / `setTraceObserver()`；`sortTraceSpansForDisplay` / `formatTraceTree` / `traceDisplay` 树状展示
-- **V2 群组 SPK 生命周期**：`V2KeyStore.saveGroupSPK` / `loadGroupSPK` / `loadCurrentGroupSPK` 基于 IndexedDB 持久化；`V2Session.ensureGroupSPK` / `ensureGroupRegistered` / `rotateGroupSPK` / `getGroupDecryptKeys`；`DESTROY_DELAY_MS = 7d`
-- **V2 P2P push 解密**：`AUNClient` 增加 push payload 就地解密路径，失败回退到 pull
-### Changed
-- **`SeqTracker.forceContiguousSeq`**：原 `contiguousSeq = minSeq` 跳过空洞（会丢消息），改为 `contiguousSeq = minSeq - 1` 由连续前缀自然推进
-### Fixed
-- short RPC 请求增加 `debug` 完整报文日志，便于跨语言诊断
----
-## 0.3.0 — 2026-05-21 ⚠️ BREAKING CHANGE
-> **V2-only 版本**：移除全部 V1 E2EE（含群组加密），新增 V2 加密原语，API 不向后兼容。
-### BREAKING
-- **移除 V1 E2EE 全部实现**：`e2ee-group.ts`、V1 epoch key 逻辑全部删除
-- **移除 V1 群组加密测试**：`e2ee.spec.ts`、`epoch-key-server.spec.ts`、`group-e2ee.spec.ts`、`group-join-key-recovery.spec.ts` 等
-- **E2EE 接口简化**：`e2ee.ts` 仅保留 V2 路径，V1 加解密方法不再可用
-- **配置变更**：`config.ts` 移除 V1 相关配置项
-### Added
-- **agent.md 主 API（浏览器版本）**：`AUNClient.publishAgentMd(content)` / `AUNClient.fetchAgentMd(aid?)`
-- **V2 加密原语**（跨语言 golden vector 一致性）：ECDH P-256、HKDF-SHA256、AES-256-GCM、ECDSA-SHA256 RAW、1DH/3DH wrap_key、Recipients Sort + Merkle Digest、State Commitment
-- **V2 Session**：SPK 生命周期 + 对端 IK 缓存 + PFS 三重销毁
-- **V2 KeyStore**：IndexedDB 持久化 SPK/IK 异步实现
-### Removed
-- `AUNClient.setLocalAgentMdContent()` / `getLocalAgentMdEtag()` / `getRemoteAgentMdEtag()` — 由主 API 自动维护
-### Deprecated
-- `client.auth.signAgentMd` / `verifyAgentMd` / `uploadAgentMd` / `downloadAgentMd` — 建议迁移到 `client.publishAgentMd` / `client.fetchAgentMd`
----
-## 0.2.20 — 2026-05-18
-### Added
-- **agent.md 版本一致性 API（浏览器版本）**：
-  - `AUNClient.setLocalAgentMdContent(content: string): Promise<string>`：浏览器无法读本地文件，改为接收 markdown 文本字符串，用 `crypto.subtle.digest('SHA-256', ...)` 计算 etag。业务侧可用 `<input type=file>` 读出文本传入。
-  - `AUNClient.getLocalAgentMdEtag(): string` / `getRemoteAgentMdEtag(): string`。
-- SDK 自动从 RPC envelope `_meta.agent_md_etag` 提取服务端 etag，应用层订阅 `message.received` / `group.message_created` 等事件时 payload 多 `_agent_md.{local_etag, remote_etag}` 字段供版本比对。
-- **`downloadAgentMd` 条件请求缓存**：内部维护 ETag/Last-Modified，未变化时返回上次缓存内容；外部 API 形态不变。
-- **transport meta observer**：`RPCTransport.setMetaObserver(fn)` 透传 envelope `_meta`，observer 抛错被吞，不影响 RPC result。
-### Changed
-- **RPC call 默认超时 10s → 35s**：与服务端 30s handler timeout 对齐，留 5s buffer。
-- **multi-device 架构**：对端无 prekey 时 `_sendEncrypted` 直接抛错（`no registered device prekeys for ...`），不再降级到 `long_term_key`。
-### Docs
-- 仓库根 `docs/`（agent.md 规范、protocol、SDK 手册）随 npm tarball 打包到 `_packed_docs/`，安装后可读。`.gitignore` 排除项（如内部测试指南）不进包。
----
+# Changelog
+本文件记录 `@agentunion/fastaun-browser` SDK 的版本变更。最新版本在最前面。
+格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)；版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)。
+---
+## 0.3.5 — 2026-05-28
+### Breaking Changes
+- **`createAid()` → `registerAid()`**：客户端 API 重命名，旧方法已移除
+- **注册与认证分离**：`authenticate()` 不再隐式注册；身份不完整时抛 `StateError`
+### Added
+- **`IdentityConflictError`**：新增错误类型（继承 `AuthError`），AID 注册冲突时抛出
+- **`auth.loadIdentity()` / `auth.loadIdentityOrNull()`**：公开 API，只读加载本地已注册身份（密钥对 + 证书 + 实例状态），无副作用
+- **`auth.fetchPeerCert()`**：公开 API，获取对端 AID 证书 PEM（本地缓存优先，未命中走 PKI HTTP + 链验证）
+- **Pull Gate**：per-key 序列化 pull 操作，防止同一 namespace 并发 pull
+- **RPC Inflight 限制**：transport 层全局最大 16 个并发 RPC + 后台 RPC 独立限制 8 个，排队超时抛 `TimeoutError`
+- **`_assertCertMatchesLocalKeypair`**：authenticate 前显式校验 cert 公钥与本地 keypair 一致
+- **`_downloadRegisteredCert`**：注册前查服务端证书的辅助方法
+### Changed
+- **`registerAid` 半成品恢复**：本地有 keypair 无 cert 时，查服务端恢复；服务端无记录则用现有 keypair 注册
+- **agent.md 元数据存储**：从全局 `list.json` key 改为 per-AID `{aid}/agentmd.json` key（IndexedDB）
+- **agent.md 下载**：改为无条件 GET；302 显式跟随；304 时本地有缓存直接用，无缓存重试
+- **`_loadIdentityOrRaise`**：增加 keypair 完整性检查
+- **`ChangeSeed` API**：`IndexedDBKeyStore.changeSeed()` 支持更换 seed（重加密私钥）
+### Removed
+- **`_ensureLocalIdentity` / `_ensureIdentity`**：已移除，注册路径不再隐式生成密钥
+- **`createAid` 方法**：已移除
+---
+## 0.3.3 — 2026-05-25
+### Added
+- **V2 Thought 加解密**：`group.thought.get` / `message.thought.get` 返回值自动解密；发送端自动加密；`attachV2EnvelopeMetadata` 附加 E2EE 元数据
+- **V2 Sender IK 延迟解密**：`_v2SenderIKPending` / `_v2SenderIKFetching` 机制，对端 IK 未缓存时挂起消息、异步拉取后重试解密
+- **agent.md 本地缓存体系（浏览器版本）**：`publishAgentMd(content?)` / `fetchAgentMd(aid?)`；基于 IndexedDB/localStorage 的 list + 按 AID 存储 + etag 比对 + 自动拉取缺失
+- **V2 辅助函数**：`getV2DeviceId` / `_v2B64ToBytesStrict` / `_v2BytesEqual` / `_v2ConcatBytes` / `_v2LengthPrefixedTextKey` / `_v2LengthPrefixedBytes`
+- **V2 envelope 元数据**：`attachV2EnvelopeMetadata` / `attachV2EnvelopeMetadataFromSource` / `extractV2EnvelopeFromSource` / `metadataWithoutAuth`
+### Changed
+- **V2 消息处理路径重构**：统一 P2P/Group 解密入口，支持 sender IK pending 延迟模式
+- **V2 SPK rotation**：thought 解密失败时触发 group SPK rotation / registration after peer fallback
+### Fixed
+- **service-plane envelope 解包**：修复 Kernel trace 字段传递丢失
+- **trace 树状展示**：enter/exit 配对 + 嵌套缩进
+---
+## 0.3.1 — 2026-05-22
+### Added
+- **`auth.checkAid` handler**：本地证书自检 + 远端注册状态查询（与 Node 版对齐）
+- **RPC trace 增强（浏览器版本）**：`RPCTransport` 增加 `setTraceMode()` / `setTraceObserver()`；`sortTraceSpansForDisplay` / `formatTraceTree` / `traceDisplay` 树状展示
+- **V2 群组 SPK 生命周期**：`V2KeyStore.saveGroupSPK` / `loadGroupSPK` / `loadCurrentGroupSPK` 基于 IndexedDB 持久化；`V2Session.ensureGroupSPK` / `ensureGroupRegistered` / `rotateGroupSPK` / `getGroupDecryptKeys`；`DESTROY_DELAY_MS = 7d`
+- **V2 P2P push 解密**：`AUNClient` 增加 push payload 就地解密路径，失败回退到 pull
+### Changed
+- **`SeqTracker.forceContiguousSeq`**：原 `contiguousSeq = minSeq` 跳过空洞（会丢消息），改为 `contiguousSeq = minSeq - 1` 由连续前缀自然推进
+### Fixed
+- short RPC 请求增加 `debug` 完整报文日志，便于跨语言诊断
+---
+## 0.3.0 — 2026-05-21 ⚠️ BREAKING CHANGE
+> **V2-only 版本**：移除全部 V1 E2EE（含群组加密），新增 V2 加密原语，API 不向后兼容。
+### BREAKING
+- **移除 V1 E2EE 全部实现**：`e2ee-group.ts`、V1 epoch key 逻辑全部删除
+- **移除 V1 群组加密测试**：`e2ee.spec.ts`、`epoch-key-server.spec.ts`、`group-e2ee.spec.ts`、`group-join-key-recovery.spec.ts` 等
+- **E2EE 接口简化**：`e2ee.ts` 仅保留 V2 路径，V1 加解密方法不再可用
+- **配置变更**：`config.ts` 移除 V1 相关配置项
+### Added
+- **agent.md 主 API（浏览器版本）**：`AUNClient.publishAgentMd(content)` / `AUNClient.fetchAgentMd(aid?)`
+- **V2 加密原语**（跨语言 golden vector 一致性）：ECDH P-256、HKDF-SHA256、AES-256-GCM、ECDSA-SHA256 RAW、1DH/3DH wrap_key、Recipients Sort + Merkle Digest、State Commitment
+- **V2 Session**：SPK 生命周期 + 对端 IK 缓存 + PFS 三重销毁
+- **V2 KeyStore**：IndexedDB 持久化 SPK/IK 异步实现
+### Removed
+- `AUNClient.setLocalAgentMdContent()` / `getLocalAgentMdEtag()` / `getRemoteAgentMdEtag()` — 由主 API 自动维护
+### Deprecated
+- `client.auth.signAgentMd` / `verifyAgentMd` / `uploadAgentMd` / `downloadAgentMd` — 建议迁移到 `client.publishAgentMd` / `client.fetchAgentMd`
+---
+## 0.2.20 — 2026-05-18
+### Added
+- **agent.md 版本一致性 API（浏览器版本）**：
+  - `AUNClient.setLocalAgentMdContent(content: string): Promise<string>`：浏览器无法读本地文件，改为接收 markdown 文本字符串，用 `crypto.subtle.digest('SHA-256', ...)` 计算 etag。业务侧可用 `<input type=file>` 读出文本传入。
+  - `AUNClient.getLocalAgentMdEtag(): string` / `getRemoteAgentMdEtag(): string`。
+- SDK 自动从 RPC envelope `_meta.agent_md_etag` 提取服务端 etag，应用层订阅 `message.received` / `group.message_created` 等事件时 payload 多 `_agent_md.{local_etag, remote_etag}` 字段供版本比对。
+- **`downloadAgentMd` 条件请求缓存**：内部维护 ETag/Last-Modified，未变化时返回上次缓存内容；外部 API 形态不变。
+- **transport meta observer**：`RPCTransport.setMetaObserver(fn)` 透传 envelope `_meta`，observer 抛错被吞，不影响 RPC result。
+### Changed
+- **RPC call 默认超时 10s → 35s**：与服务端 30s handler timeout 对齐，留 5s buffer。
+- **multi-device 架构**：对端无 prekey 时 `_sendEncrypted` 直接抛错（`no registered device prekeys for ...`），不再降级到 `long_term_key`。
+### Docs
+- 仓库根 `docs/`（agent.md 规范、protocol、SDK 手册）随 npm tarball 打包到 `_packed_docs/`，安装后可读。`.gitignore` 排除项（如内部测试指南）不进包。
+---

package/_packed_docs/INDEX.md CHANGED Viewed

@@ -9,9 +9,9 @@
 | 文档 | 定位 |
 | --- | --- |
 | [aun测试运行指南](aun测试运行指南.md) | 当前 Docker 单域、双域、多语言 SDK 测试运行命令 |
-| [跨语言容器E2E测试方案](design/跨语言容器E2E测试方案.md) | 多语言 SDK 同网同服、test-runner 控制面的跨语言 E2E 方案 |
-| [E2EE V2 简化为 1DH + Per-AID Wrap 方案](design/E2EE_V2简化为1DH加Per-AID_Wrap方案.md) | SDK bootstrap 能力声明 + 服务端 policy 控制 1DH/per-AID wrap 的兼容方案 |
-| [AUN RPC Trace 增强设计](design/2026-05-22-aun-rpc-trace-enhancement.md) | RPC trace 诊断字段与 enter/exit span 设计 |
+| [跨语言容器E2E测试方案](design/跨语言容器E2E测试方案.md) | 多语言 SDK 同网同服、test-runner 控制面的跨语言 E2E 方案 |
+| [E2EE V2 简化为 1DH + Per-AID Wrap 方案](design/E2EE_V2简化为1DH加Per-AID_Wrap方案.md) | SDK bootstrap 能力声明 + 服务端 policy 控制 1DH/per-AID wrap 的兼容方案 |
+| [AUN RPC Trace 增强设计](design/2026-05-22-aun-rpc-trace-enhancement.md) | RPC trace 诊断字段与 enter/exit span 设计 |
 | [远程 agent.md 缓存与 ETag 透传方案](agent.md/远程agent.md缓存与etag透传方案.md) | 远程 agent.md per-AID 缓存、SQLite 表、消息信封与 RPC 响应 ETag 透传方案 |
 | [SDK 文档索引](sdk/INDEX.md) | SDK 使用手册、RPC 手册、E2EE 手册的子索引 |
 | [SDK 查阅指南](sdk/AUN_DOCS_GUIDE.md) | SDK 文档按行区间渐进式查阅方法 |
@@ -44,9 +44,9 @@
 ### E2EE 与跨语言一致性
-- SDK E2EE API、会话管理、ProtectedHeaders → [SDK 文档索引](sdk/INDEX.md)
-- E2EE V2 1DH/per-AID wrap、bootstrap 能力声明、服务端 fanout → [E2EE V2 简化为 1DH + Per-AID Wrap 方案](design/E2EE_V2简化为1DH加Per-AID_Wrap方案.md)
-- 共享测试向量、transcript 回放、Python / TS / Go / C++ E2EE 互通 → [aun测试运行指南](aun测试运行指南.md)、[跨语言容器E2E测试方案](design/跨语言容器E2E测试方案.md)
+- SDK E2EE API、会话管理、ProtectedHeaders → [SDK 文档索引](sdk/INDEX.md)
+- E2EE V2 1DH/per-AID wrap、bootstrap 能力声明、服务端 fanout → [E2EE V2 简化为 1DH + Per-AID Wrap 方案](design/E2EE_V2简化为1DH加Per-AID_Wrap方案.md)
+- 共享测试向量、transcript 回放、Python / TS / Go / C++ E2EE 互通 → [aun测试运行指南](aun测试运行指南.md)、[跨语言容器E2E测试方案](design/跨语言容器E2E测试方案.md)
 ---
@@ -56,15 +56,15 @@
 记录当前 AUN 服务与 SDK 在 Docker 单域、双域环境中的实际测试入口。包含 Python、TypeScript、Go、JavaScript、C++ 五语言测试矩阵，Python / TypeScript / Go / C++ 跨语言容器 E2E 的 69 用例矩阵，覆盖 P2P 明文/E2EE、群聊 pairwise 明文/E2EE，以及四语言 agent 同群的明文/E2EE 矩阵，另包含固定身份目录、容器名、典型命令、浏览器 E2E、C++ Docker 测试、双域 federation 测试和数据保护规则。
-### 跨语言容器E2E测试方案
-定义多语言 SDK 同时作为真实客户端运行的目标测试体系。核心模型是每个语言一个客户端容器，全连接同一 AUN server / gateway；业务消息走 AUN，test-runner 通过每个客户端暴露的 test-control HTTP API 编排动作和断言结果。当前单域落地覆盖 Python / TypeScript / Go / C++，浏览器 JavaScript 仍按宿主机 Playwright 运行。
-### E2EE V2 简化为 1DH + Per-AID Wrap 方案
-定义新 SDK 通过 bootstrap 入参声明 `e2ee_wrap_capabilities`，服务端再返回实际 `e2ee_wrap_policy`；旧 SDK 未声明时保留 legacy `3DH/device`。policy 不进入 envelope 或 AAD。方案规定 per-AID row 使用现有 8 字段结构并以 `device_id=""` 标识，服务端按真实 device fanout 但保存 `recipient_row_json` 原始 row，pull 时用原始 row 重建 recipient，确保 Merkle proof 和历史消息兼容。
-### AUN RPC Trace 增强设计
+### 跨语言容器E2E测试方案
+定义多语言 SDK 同时作为真实客户端运行的目标测试体系。核心模型是每个语言一个客户端容器，全连接同一 AUN server / gateway；业务消息走 AUN，test-runner 通过每个客户端暴露的 test-control HTTP API 编排动作和断言结果。当前单域落地覆盖 Python / TypeScript / Go / C++，浏览器 JavaScript 仍按宿主机 Playwright 运行。
+### E2EE V2 简化为 1DH + Per-AID Wrap 方案
+定义新 SDK 通过 bootstrap 入参声明 `e2ee_wrap_capabilities`，服务端再返回实际 `e2ee_wrap_policy`；旧 SDK 未声明时保留 legacy `3DH/device`。policy 不进入 envelope 或 AAD。方案规定 per-AID row 使用现有 8 字段结构并以 `device_id=""` 标识，服务端按真实 device fanout 但保存 `recipient_row_json` 原始 row，pull 时用原始 row 重建 recipient，确保 Merkle proof 和历史消息兼容。
+### AUN RPC Trace 增强设计
 设计 RPC trace 的 enter/exit span 结构，补充方法、AID、route、错误码、业务结果等诊断字段，并定义安全字段白名单。目标是在跨模块 RPC 失败时能定位到具体业务原因，而不是只看到模块路径和耗时。
@@ -78,4 +78,4 @@
 ### SDK 查阅指南
-`docs/sdk/AUN_DOCS_GUIDE.md` 说明如何按行区间渐进式读取 SDK 文档，避免一次性加载过多文档内容。
+`docs/sdk/AUN_DOCS_GUIDE.md` 说明如何按行区间渐进式读取 SDK 文档，避免一次性加载过多文档内容。

package/_packed_docs/KITE_DOCS_GUIDE.md CHANGED Viewed

@@ -8,18 +8,18 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 ### Step 1：先读根级 Layer 1
-- `docs/INDEX.md` L7-20：根级文档地图。
+- `docs/INDEX.md` L7-20：根级文档地图。
 ### Step 2：按主题读根级 Layer 2
 - 测试与 E2E：`docs/INDEX.md` L25-29。
 - SDK 使用与协议：`docs/INDEX.md` L31-36。
 - 诊断与可观测性：`docs/INDEX.md` L38-42。
-- E2EE 与跨语言一致性：`docs/INDEX.md` L45-49。
+- E2EE 与跨语言一致性：`docs/INDEX.md` L45-49。
 ### Step 3：需要判断文档价值时读 Layer 3 摘要
-- `docs/INDEX.md` L53-81：重点文档摘要。
+- `docs/INDEX.md` L53-81：重点文档摘要。
 ### Step 4：再读目标文档章节
@@ -36,9 +36,9 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 | 双域 federation 测试容器和命令 | `docs/aun测试运行指南.md` L534-714 |
 | 何时 rebuild / restart | `docs/aun测试运行指南.md` L715-762 |
 | 测试故障排查 | `docs/aun测试运行指南.md` L763-782 |
-| 跨语言容器 E2E 背景与目标 | `docs/design/跨语言容器E2E测试方案.md` L5-35 |
-| E2EE V2 1DH/per-AID wrap 方案 | `docs/design/E2EE_V2简化为1DH加Per-AID_Wrap方案.md` |
-| 跨语言 Docker 拓扑 | `docs/design/跨语言容器E2E测试方案.md` L37-76 |
+| 跨语言容器 E2E 背景与目标 | `docs/design/跨语言容器E2E测试方案.md` L5-35 |
+| E2EE V2 1DH/per-AID wrap 方案 | `docs/design/E2EE_V2简化为1DH加Per-AID_Wrap方案.md` |
+| 跨语言 Docker 拓扑 | `docs/design/跨语言容器E2E测试方案.md` L37-76 |
 | 共享测试向量、CLI transcript、单域/双域分层 | `docs/design/跨语言容器E2E测试方案.md` L78-147 |
 | test-runner 如何控制不同语言 client | `docs/design/跨语言容器E2E测试方案.md` L149-158 |
 | test-control HTTP API | `docs/design/跨语言容器E2E测试方案.md` L160-305 |
@@ -52,4 +52,4 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 | agent.md ETag 透传时序图 | `docs/agent.md/远程agent.md缓存与etag透传方案.md` L88-185 |
 | agent.md 服务端与 SDK 实现流程 | `docs/agent.md/远程agent.md缓存与etag透传方案.md` L187-268 |
 | agent.md SQLite 表结构、竞态和测试点 | `docs/agent.md/远程agent.md缓存与etag透传方案.md` L270-328 |
-| SDK API、RPC、E2EE 使用细节 | `docs/sdk/AUN_DOCS_GUIDE.md` |
+| SDK API、RPC、E2EE 使用细节 | `docs/sdk/AUN_DOCS_GUIDE.md` |