@agentunion/fastaun-browser 0.5.2 → 0.5.4

package/CHANGELOG.md

@@ -6,6 +6,80 @@
 
 ---
 
+## 0.5.4 — 2026-07-09
+
+### 新功能
+
+#### 通用 indexed document settings
+- 浏览器 `GroupFacade` 新增 `getSettingWithIndex()` / `updateSettingWithIndex()`，支持按 `keyName` 管理 `{keyName}.content` 与 `{keyName}.attachments` 两类文档型 indexed settings。
+- `keyName` 增加统一校验：必须匹配 `^[A-Za-z][A-Za-z0-9_-]{0,63}$`，并拒绝 `join`、`group`、`index`、`visibility` 等保留基名。
+- `getAnnouncement()` / `updateAnnouncement()` 与 `getRules()` / `updateRules()` 复用通用 indexed document setting 路径，继续通过 signed `group.index` + `expected_index_etag` CAS 写入。
+
+#### 入群要求附件
+- `getJoinRequirements()` / `updateJoinRequirements()` 支持 `attachments`，对应服务端 `join.attachments` indexed setting。
+- `join.attachments` 与公告/群规附件保持同一类 `group.fs` 引用结构，可通过 group.index 签名索引同步。
+
+#### Group FS 角色 ACL
+- 服务端 group.fs 命名空间新增受保护 `.group` 控制目录，并为 owner/admin 同步基线角色 ACL。
+- owner/admin 默认可写群自有区；admin 可管理群自有区角色 ACL。
+- `role:member` 支持按具体业务目录授予 `rw`，允许成员创建/上传，但不允许删除、重命名或移动群自有区内容。
+
+### 修复
+
+- 修复 Storage 直接入口对群自有区删除/移动/重命名权限检查不足的问题，删除类操作统一走 `delete` 权限判定。
+- 修复旧 group AID 证书类型仍为 normal 时，Storage 无法通过 group resolver 判定群空间的问题。
+- 兼容 CA 续期时 PEM 公钥与 SPKI base64 的等价比较，并兼容托管续期返回 `cert_pem` / `new_cert` 字段。
+
+### 改进
+
+- message/group WAL writer 的 `micro_wait` 支持 auto 预算模型，并扩展性能统计输出，便于观察批量写入队列深度与 pending 状态。
+- group.fs 命名空间在读取 group 记录时支持懒修复，缺失 baseline ACL 时可重试同步。
+- SDK 包版本、运行时 `VERSION` 和 conformance 期望版本更新为 `0.5.4`。
+
+### 测试
+
+- 扩展浏览器 GroupFacade group index 单元测试，覆盖通用 indexed document setting、`join.attachments` 缓存读取和 group.index 写入路径。
+- 更新 conformance 版本期望到 `0.5.4`。
+- 服务端测试扩展 group settings、group.fs namespace / role ACL、Storage 群自有区权限和 CA 续期兼容性。
+
+---
+
+## 0.5.3 — 2026-07-07
+
+### 新功能
+
+#### group.index 索引化群设置
+- 新增浏览器 `group.index` JSONL 工具：支持 canonical entries、body hash、etag、ECDSA P-256 签名/验签，以及将 settings 更新合并为带 `group.index` 的原子写入。
+- `GroupFacade` 新增 `checkGroupIndex` / `getGroupIndex` / `updateGroupIndex`，写入时携带 `expected_index_etag` 做 CAS，并在冲突后重拉索引重试。
+- 浏览器 IndexedDB TokenStore 新增 `group_index_cache`，按 local AID + group AID 持久化 index JSONL、remote meta、本地 etag、settings cache 和 entry etags。
+- 入口导出 `GROUP_INDEX_KEY`、`GROUP_INDEX_SCHEMA`、`GroupIndexMetaCache`、`buildSignedGroupIndex`、`verifyGroupIndex`、`prepareGroupSettingsWithIndex` 等 group.index API。
+
+### 修复
+
+#### 撤回去重与有序投递
+- `message.recalled` 改为专用处理路径，支持 P2P 撤回 tombstone 的有序投递、自动 ack、gap fill 和按原消息标识去重，避免 push / pull 对同一次撤回重复回调。
+- 群撤回去重键改为规范化 group id + 原消息 id/seq，忽略 `recalled_at`，并补齐顶层 recall 字段归一化。
+- 群消息 pull / legacy fallback 识别 `group.message_recalled` tombstone，避免把撤回通知作为普通群消息投递。
+- P2P 与群 push 按 namespace 串行化处理，降低异步解密和投递导致的乱序风险。
+- V2 P2P / Group pull 页内消息按 `seq` 排序后处理，避免服务端返回无序时影响本地 seq 推进。
+
+### 改进
+
+- `RPCTransport` 的 `_meta` observer 支持异步回调；RPC 成功响应会等待 observer 完成，事件/通知路径统一走安全的 meta observer 分发。
+- `getAnnouncement` / `getRules` / `getJoinRequirements` 优先使用 group.index settings cache；`updateAnnouncement` / `updateRules` / `updateJoinRequirements` 改走 `updateGroupIndex`，保持索引与设置同步。
+- cross-sdk JS agent 支持 `sdk.update_group_index` 调用，便于跨 SDK 测试索引化群设置。
+- SDK 包版本、运行时 `VERSION` 和 conformance 期望版本更新为 `0.5.3`。
+
+### 测试
+
+- 新增 group.index 单元测试，覆盖 hash/etag、签名/验签、settings merge、RPC meta stale/fresh、async meta observer 和 IndexedDB 持久化恢复。
+- 新增 GroupFacade group.index 单元测试，覆盖 CAS 写入、冲突重试、远端索引验签、tamper 拒绝、settings cache 和便利方法索引化写入。
+- 新增浏览器 E2E：验证签名 `group.index` 写入、裸 settings 写入拒绝、CAS 冲突重试和最终 settings 一致性。
+- 扩展撤回投递测试，覆盖 P2P/group recall 顶层字段归一化、push/pull tombstone 去重和有序投递。
+- 更新 group settings 与签名审计 E2E，使公告/群规等索引化 settings 通过 `updateGroupIndex` 写入。
+
+---
+
 ## 0.5.2 — 2026-07-05
 
 ### 新功能

package/_packed_docs/CHANGELOG.md

@@ -6,6 +6,80 @@
 
 ---
 
+## 0.5.4 — 2026-07-09
+
+### 新功能
+
+#### 通用 indexed document settings
+- 浏览器 `GroupFacade` 新增 `getSettingWithIndex()` / `updateSettingWithIndex()`，支持按 `keyName` 管理 `{keyName}.content` 与 `{keyName}.attachments` 两类文档型 indexed settings。
+- `keyName` 增加统一校验：必须匹配 `^[A-Za-z][A-Za-z0-9_-]{0,63}$`，并拒绝 `join`、`group`、`index`、`visibility` 等保留基名。
+- `getAnnouncement()` / `updateAnnouncement()` 与 `getRules()` / `updateRules()` 复用通用 indexed document setting 路径，继续通过 signed `group.index` + `expected_index_etag` CAS 写入。
+
+#### 入群要求附件
+- `getJoinRequirements()` / `updateJoinRequirements()` 支持 `attachments`，对应服务端 `join.attachments` indexed setting。
+- `join.attachments` 与公告/群规附件保持同一类 `group.fs` 引用结构，可通过 group.index 签名索引同步。
+
+#### Group FS 角色 ACL
+- 服务端 group.fs 命名空间新增受保护 `.group` 控制目录，并为 owner/admin 同步基线角色 ACL。
+- owner/admin 默认可写群自有区；admin 可管理群自有区角色 ACL。
+- `role:member` 支持按具体业务目录授予 `rw`，允许成员创建/上传，但不允许删除、重命名或移动群自有区内容。
+
+### 修复
+
+- 修复 Storage 直接入口对群自有区删除/移动/重命名权限检查不足的问题，删除类操作统一走 `delete` 权限判定。
+- 修复旧 group AID 证书类型仍为 normal 时，Storage 无法通过 group resolver 判定群空间的问题。
+- 兼容 CA 续期时 PEM 公钥与 SPKI base64 的等价比较，并兼容托管续期返回 `cert_pem` / `new_cert` 字段。
+
+### 改进
+
+- message/group WAL writer 的 `micro_wait` 支持 auto 预算模型，并扩展性能统计输出，便于观察批量写入队列深度与 pending 状态。
+- group.fs 命名空间在读取 group 记录时支持懒修复，缺失 baseline ACL 时可重试同步。
+- SDK 包版本、运行时 `VERSION` 和 conformance 期望版本更新为 `0.5.4`。
+
+### 测试
+
+- 扩展浏览器 GroupFacade group index 单元测试，覆盖通用 indexed document setting、`join.attachments` 缓存读取和 group.index 写入路径。
+- 更新 conformance 版本期望到 `0.5.4`。
+- 服务端测试扩展 group settings、group.fs namespace / role ACL、Storage 群自有区权限和 CA 续期兼容性。
+
+---
+
+## 0.5.3 — 2026-07-07
+
+### 新功能
+
+#### group.index 索引化群设置
+- 新增浏览器 `group.index` JSONL 工具：支持 canonical entries、body hash、etag、ECDSA P-256 签名/验签，以及将 settings 更新合并为带 `group.index` 的原子写入。
+- `GroupFacade` 新增 `checkGroupIndex` / `getGroupIndex` / `updateGroupIndex`，写入时携带 `expected_index_etag` 做 CAS，并在冲突后重拉索引重试。
+- 浏览器 IndexedDB TokenStore 新增 `group_index_cache`，按 local AID + group AID 持久化 index JSONL、remote meta、本地 etag、settings cache 和 entry etags。
+- 入口导出 `GROUP_INDEX_KEY`、`GROUP_INDEX_SCHEMA`、`GroupIndexMetaCache`、`buildSignedGroupIndex`、`verifyGroupIndex`、`prepareGroupSettingsWithIndex` 等 group.index API。
+
+### 修复
+
+#### 撤回去重与有序投递
+- `message.recalled` 改为专用处理路径，支持 P2P 撤回 tombstone 的有序投递、自动 ack、gap fill 和按原消息标识去重，避免 push / pull 对同一次撤回重复回调。
+- 群撤回去重键改为规范化 group id + 原消息 id/seq，忽略 `recalled_at`，并补齐顶层 recall 字段归一化。
+- 群消息 pull / legacy fallback 识别 `group.message_recalled` tombstone，避免把撤回通知作为普通群消息投递。
+- P2P 与群 push 按 namespace 串行化处理，降低异步解密和投递导致的乱序风险。
+- V2 P2P / Group pull 页内消息按 `seq` 排序后处理，避免服务端返回无序时影响本地 seq 推进。
+
+### 改进
+
+- `RPCTransport` 的 `_meta` observer 支持异步回调；RPC 成功响应会等待 observer 完成，事件/通知路径统一走安全的 meta observer 分发。
+- `getAnnouncement` / `getRules` / `getJoinRequirements` 优先使用 group.index settings cache；`updateAnnouncement` / `updateRules` / `updateJoinRequirements` 改走 `updateGroupIndex`，保持索引与设置同步。
+- cross-sdk JS agent 支持 `sdk.update_group_index` 调用，便于跨 SDK 测试索引化群设置。
+- SDK 包版本、运行时 `VERSION` 和 conformance 期望版本更新为 `0.5.3`。
+
+### 测试
+
+- 新增 group.index 单元测试，覆盖 hash/etag、签名/验签、settings merge、RPC meta stale/fresh、async meta observer 和 IndexedDB 持久化恢复。
+- 新增 GroupFacade group.index 单元测试，覆盖 CAS 写入、冲突重试、远端索引验签、tamper 拒绝、settings cache 和便利方法索引化写入。
+- 新增浏览器 E2E：验证签名 `group.index` 写入、裸 settings 写入拒绝、CAS 冲突重试和最终 settings 一致性。
+- 扩展撤回投递测试，覆盖 P2P/group recall 顶层字段归一化、push/pull tombstone 去重和有序投递。
+- 更新 group settings 与签名审计 E2E，使公告/群规等索引化 settings 通过 `updateGroupIndex` 写入。
+
+---
+
 ## 0.5.2 — 2026-07-05
 
 ### 新功能

package/_packed_docs/INDEX.md

@@ -21,7 +21,8 @@
 | [消息收件箱统一迁移方案](design/消息收件箱统一迁移方案.md) | P2P `message_inbox` 与群消息 `group_inbox` 的统一读模型、后台回填和旧表清理方案 |
 | [AUN 反向代理服务方案与 TDD 实施计划](design/AUN反向代理服务方案与TDD实施计划.md) | AUN Service Proxy、service_proxy 服务模块、SDK service-proxy-client、URL 路由、隧道协议、Web 边界和分阶段 TDD 落地计划 |
 | [远程 agent.md 缓存与 ETag 透传方案](agent.md/远程agent.md缓存与etag透传方案.md) | 远程 agent.md per-AID 本地文件/IndexedDB 缓存、Gateway `_meta.agent_md_etags` 角色、消息信封 ETag 和注入节流方案 |
-| [SDK 文档索引](sdk/INDEX.md) | SDK 使用手册、RPC 手册、E2EE、Storage VFS、Group FS 和 Collab 的子索引 |
+| [群索引版本提示与附件引用方案](design/群索引版本提示与附件引用方案.md) | `group.index` 签名索引、`_meta.group_indexes` 版本提示、CAS 更新、服务端缓存注入和附件稳定引用 |
+| [SDK 文档索引](sdk/INDEX.md) | SDK 使用手册、RPC 手册、E2EE、Storage VFS、Group FS 和 Collab 的子索引 |
 | [SDK 查阅指南](sdk/AUN_DOCS_GUIDE.md) | SDK 文档按行区间渐进式查阅方法 |
 | [AUN CLI 手册](cli/CLI手册.md) | Python CLI 源码位置、安装运行入口、全局选项、profile 配置和主要命令集 |
 | [AUN CLI 设计文档](cli/AUN-CLI设计文档.md) | `python/src/aun_cli` 当前实现架构、命令注册面、配置解析、SDK 桥接和实现边界 |
@@ -76,6 +77,7 @@
 - `client.notify()` 在线轻量通知、AID/群路由、跨域 federation 和不离线存储边界 → [Notify 通知方案](sdk/Notify通知方案.md)
 - 协议细节、子协议和消息格式 → [协议文档目录](protocol/)
 - agent.md 远程缓存、`remote_etag` / `local_etag`、`requester` / `peer` / `group` 角色、消息信封与 Gateway `_meta` ETag 透传 → [远程 agent.md 缓存与 ETag 透传方案](agent.md/远程agent.md缓存与etag透传方案.md)
+- `group.index` owner/admin SDK 生成签名索引、`_meta.group_indexes` 观察、`expected_index_etag` CAS、服务端正/负缓存与注入频率控制 → [群索引版本提示与附件引用方案](design/群索引版本提示与附件引用方案.md)、[SDK 文档索引](sdk/INDEX.md)
 
 ### Service Proxy 与服务暴露
 
@@ -103,9 +105,9 @@
 
 ## Layer 3：重点文档摘要
 
-### aun测试运行指南
-
-记录当前 AUN 服务与 SDK 在 Docker 单域、双域环境中的实际测试入口。包含 Python、TypeScript、Go、JavaScript 四语言测试矩阵，Python / TypeScript / Go / JavaScript 跨语言容器 E2E 的 83 用例矩阵，覆盖 P2P 明文/E2EE、群聊 pairwise 明文/E2EE、三/四成员同群矩阵、storage ticket/ACL、group.fs 与 group.fs POSIX、collab 与 collab ACL、连续消息、ack、预期失败和混合明文/E2EE 场景，另包含固定身份目录、bench-pairs16 性能身份池、uvloop bench 环境变量、Gateway 客户端 mock 网络延迟、`--perf-trace` 开关、容器名、典型命令、浏览器 E2E、双域 federation 测试、Service Proxy 单域/双域 E2E 入口、message/group WAL 回归检查和数据保护规则。
+### aun测试运行指南
+
+记录当前 AUN 服务与 SDK 在 Docker 单域、双域环境中的实际测试入口。包含 Python、TypeScript、Go、JavaScript 四语言测试矩阵和跨语言容器 E2E，覆盖 group.index 签名/CAS/meta 观察、P2P 明文/E2EE、群聊 pairwise 明文/E2EE、三/四成员同群矩阵、storage ticket/ACL、group.fs 与 group.fs POSIX、collab 与 collab ACL、连续消息、ack、预期失败和混合明文/E2EE 场景，另包含固定身份目录、bench-pairs16 性能身份池、uvloop bench 环境变量、Gateway 客户端 mock 网络延迟、`--perf-trace` 开关、容器名、典型命令、浏览器 E2E、双域 federation 测试、Service Proxy 单域/双域 E2E 入口、message/group WAL 回归检查和数据保护规则。
 
 ### AUN SDK 重构修改清单
 
@@ -147,13 +149,17 @@
 
 定义 AUN Service Proxy / AUN 服务代理的整体方案：服务侧新增 `service_proxy` 模块，`service-proxy-server` 负责公网 HTTP/HTTPS 入口、WSS 隧道、在线连接索引和协议桥接；SDK 侧 `service-proxy-client` 负责 provider 侧 embedded registry、本地 endpoint 调用和服务摘要上报。方案明确去掉 ACP GlobalRegistry/RSA 同步，URL 以 `https://proxy.{issuer}/{user_name}/{svc_name}/...` 为 canonical，`https://{user_name}.{issuer}/proxy/{svc_name}/...` 由 NameService 跳转；Web 服务推荐 host-root 模式，目录式 path-prefix 只做受限转发。文档还按 Phase 0 到 Phase 11 给出 TDD 实施步骤，记录 Phase 10 已新增宿主机进程内 7 类 HTTP/SSE/WS/NameService/Web/ACL/双域边界 E2E，以及单域和双域 Docker E2E 脚本入口；真实 Docker 执行仍需先满足模块启用、镜像包含新模块和 `/ws/client` AUN 身份 resolver 前置条件。
 
-### 远程 agent.md 缓存与 ETag 透传方案
-
+### 远程 agent.md 缓存与 ETag 透传方案
+
 定义每个远程 AID 在 SDK 内存和本地持久化记录中维护一条 agent.md 状态：Python / TypeScript / Go 使用 `{aun_path}/AIDs/{aid}/agent.md` 与 `agentmd.json`，浏览器 JavaScript 使用 IndexedDB logical key。方案规定 Gateway 在 RPC response / event push 的 `_meta.agent_md_etags` 中按 `requester`、`peer`、`group` 注入元数据，保留旧别名兼容，并通过 300 秒正缓存、60 秒负缓存和默认 60 秒发送节流控制热路径开销；Message Service V2 P2P 信封携带 `agent_md.sender`。四端 SDK 自动观察 `_meta` 和信封 `agent_md.sender/group`，写入 `remote_etag` / `last_modified`，并遵守按需下载、无条件 GET、304 兼容、竞态和跨 SDK 一致性规则。
-
-### SDK 文档索引
-
-`docs/sdk/INDEX.md` 是 SDK 手册的三层子索引，覆盖快速开始、WebSocket 协议、核心概念、连接认证、E2EE V2、API 手册、错误处理、最佳实践、payload、Service Proxy、Storage VFS、Group FS、Collab GC/reflog/reset 和各类 RPC 手册。
+
+### 群索引版本提示与附件引用方案
+
+定义 `group.index` 的 owner/admin SDK 生成、canonical JSONL、签名、`etag` / `body_hash`、`expected_index_etag` CAS、`_meta.group_indexes` 版本提示、Gateway/Message 转发边界、服务端正/负缓存、singleflight、写后失效/刷新、注入频率控制，以及 DB 保存核心设置、group.fs 保存大附件、附件稳定引用和 SDK `check/get/updateGroupIndex` 语义。
+
+### SDK 文档索引
+
+`docs/sdk/INDEX.md` 是 SDK 手册的三层子索引，覆盖快速开始、WebSocket 协议、核心概念、连接认证、E2EE V2、API 手册、错误处理、最佳实践、payload、Service Proxy、Storage VFS、Group FS、Group Index、Collab GC/reflog/reset 和各类 RPC 手册。
 
 ### Service Proxy RPC 手册
 

package/_packed_docs/KITE_DOCS_GUIDE.md

@@ -47,6 +47,7 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 | 服务端消息通信诊断总体方案 | `docs/design/AUN服务端消息通信诊断面板方案.md` L3-47 |
 | 服务端消息通信 P0 诊断面板 | `docs/design/服务端消息通信诊断面板P0方案.md` L3-73 |
 | P2P / Group 消息 inbox 统一迁移与旧表清理 | `docs/design/消息收件箱统一迁移方案.md` |
+| group.index 签名索引、`_meta.group_indexes`、CAS 更新和服务端缓存注入 | `docs/design/群索引版本提示与附件引用方案.md` L1-348、`docs/INDEX.md` L24、L80、L156 |
 | AUN Service Proxy 总体架构、参考项目与边界 | `docs/design/AUN反向代理服务方案与TDD实施计划.md` L3-127 |
 | AUN Service Proxy URL、注册、隧道协议和 Web 边界 | `docs/design/AUN反向代理服务方案与TDD实施计划.md` L129-384 |
 | AUN Service Proxy 服务列表注册、双注册和 wakeup 路由 | `docs/sdk/09-proxy-rpc-manual.md` L1-226、`docs/protocol/06-服务协议.md` L43-204 |
@@ -58,7 +59,7 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 | test-control HTTP API | `docs/design/跨语言容器E2E测试方案.md` L160-305 |
 | 客户端容器要求和 Compose 建议 | `docs/design/跨语言容器E2E测试方案.md` L307-411 |
 | test-runner 标准用例流程 | `docs/design/跨语言容器E2E测试方案.md` L413-440 |
-| Python / TypeScript / Go / JavaScript 跨 SDK 测试矩阵 | `docs/aun测试运行指南.md` L202-228 |
+| Python / TypeScript / Go / JavaScript 跨 SDK 测试矩阵与 group.index 覆盖 | `docs/aun测试运行指南.md` L202-229、L321-346 |
 | 跨语言日志、trace、身份隔离、CLI 定位 | `docs/design/跨语言容器E2E测试方案.md` L514-576 |
 | 失败分类与落地阶段 | `docs/design/跨语言容器E2E测试方案.md` L579-625 |
 | 与现有测试环境的关系和验收标准 | `docs/design/跨语言容器E2E测试方案.md` L627-665 |
@@ -66,7 +67,8 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 | agent.md ETag 透传时序图 | `docs/agent.md/远程agent.md缓存与etag透传方案.md` L129-239 |
 | agent.md 服务端与 SDK 实现流程 | `docs/agent.md/远程agent.md缓存与etag透传方案.md` L241-319 |
 | agent.md 本地持久化、竞态和测试点 | `docs/agent.md/远程agent.md缓存与etag透传方案.md` L321-370 |
-| SDK API、RPC、E2EE、Storage VFS、Group FS、Collab GC/reflog/reset 使用细节 | `docs/sdk/AUN_DOCS_GUIDE.md` |
+| SDK API、RPC、E2EE、Storage VFS、Group FS、Collab GC/reflog/reset 使用细节 | `docs/sdk/AUN_DOCS_GUIDE.md` |
+| SDK group.index facade、`check/get/updateGroupIndex` 和 CAS 冲突处理 | `docs/sdk/06-API手册.md` L340-370、`docs/sdk/09-group-rpc-manual.md` L1015-1095、`docs/sdk/07-错误处理.md` |
 | AUN Python CLI 源码位置、安装入口、全局选项、profile 配置和主要命令集 | `docs/cli/CLI手册.md` L3-325 |
 | AUN Python CLI 当前实现架构、命令注册、SDK 桥接和实现边界 | `docs/cli/AUN-CLI设计文档.md` L3-265 |
 | AUN Storage 架构、SDK VFS、direct backend 数据面、类 Linux 权限和 mount/symlink | `docs/aun-fs/AUN Storage架构设计.md` L16-47、L74-120、L183-228、L289-315 |