@agentunion/fastaun-browser 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -6,6 +6,62 @@
 
 ---
 
+## 0.5.1 — 2026-07-01
+
+### ⚠️ 重大变更（Breaking Changes）
+
+#### 群组标识符统一为 GROUP_AID
+- **GROUP_ID 废弃**：历史 `group.{domain}/{base}` 格式已废弃，统一为 `{base}.{issuer}` 格式（group_aid）
+- **兼容转换**：`normalizeGroupId()` 函数保留向后兼容，自动转换旧格式到新格式
+- **新增函数**：`convertToGroupAid()` 显式转换任意历史格式到标准 group_aid
+- **RPC 参数**：`group_id` 字段名保留但值为 group_aid；新增 `group_aid` 参数与 `group_id` 等价
+- **影响范围**：所有群组相关 API（`group.send` / `group.pull` / `group.fs.*` 等）
+
+#### 移除 V1 E2EE 实现
+- **完全移除**：删除所有 V1 端到端加密代码（epoch key、群组加密管理器、V1 群组加密）
+- **仅保留 V2**：E2EE 功能完全迁移到 V2 协议（消息级密钥 + 逐设备 wrap + 状态签名）
+- **简化接口**：V2 E2EE 协调器大幅重构，移除 V1 兼容层
+- **注意**：此版本不向后兼容 V1 加密消息
+
+### 新功能
+
+#### Storage & Group FS 能力扩展
+- **Storage VFS P4**：新增 `touch()` 方法，支持创建空文件或更新文件时间戳
+- **Storage VFS P4**：新增 `du()` 方法，支持查询目录或文件的磁盘使用统计
+- **Storage VFS P6**：扩展 `getAcl()` / `listAcl()` 方法，支持 ACL 权限查询
+- **Group FS**：新增 `getAcl()` / `listAcl()` / `removeAcl()` 方法，完善群文件 ACL 管理
+- **Storage LowLevel**：补齐底层 RPC 映射，覆盖 `storage.fs.*` / `storage.object.*` 完整能力
+
+### 修复
+
+#### Storage & Group FS
+- 修复 `group.send` / `group.pull` 缺失 `group_id` 必填校验问题
+- 修复 `group.fs` 权限角色 (`role`) 在 ACL 展示中的格式错误
+- 修复 `storage.fs.symlink` 符号链接操作的路径解析问题
+- 修复 `storage.fs.memberdata` 路由逻辑错误
+- 修复 `storage.fs.mount` 挂载点权限校验问题
+
+#### 服务端性能优化（影响 SDK 行为）
+- Gateway 连接池改为可配置，降低高并发下的连接瓶颈
+- Group 推送改为异步化，提升大群消息分发性能
+- Message seq 号段化分配，减少数据库争抢
+- Message 短暂消息 (`persist=false`) 改用内存缓冲 + 异步推送
+
+### 改进
+
+- 路径校验增强：`storage.fs` / `group.fs` 路径参数增加规范化校验，拒绝 `..` / 空路径 / 非法字符
+- 系统目录保护：`memberdata` / `group_data` 写操作增加保护，防止误删系统目录
+- Validators：新增跨语言 `validatePath()` / `validateAid()` 等校验函数，四语言行为对齐
+- 浏览器环境保持 Blob/Uint8Array/ArrayBuffer 数据源支持，无本地文件路径依赖
+
+### 测试
+
+- 新增 `storage.spec.ts` E2E 测试（浏览器环境 `touch` / `du`）
+- 新增 `group-fs.spec.ts` E2E 测试（浏览器环境 ACL 操作）
+- 扩展 `storage-vfs-p5.test.ts` 单元测试覆盖新增能力
+
+---
+
 ## 0.5.0 — 2026-06-17
 
 ### 新功能

package/_packed_docs/CHANGELOG-validators.md

@@ -0,0 +1,144 @@
+# AID 和 Group ID 格式校验实现 (2026-06-18)
+
+## 背景
+
+发现测试环境中 SDK 发送的目标对象（AID 和 Group ID）存在完全不合法的格式（如 `__system__`），这些非法格式应该在客户端早期拦截，避免发送到服务端。
+
+## 问题
+
+1. SDK 没有在关键发送接口进行格式校验
+2. 文档中的 Group ID 格式描述与实际代码不一致
+
+## 解决方案
+
+### 1. 修正文档
+
+**原文档错误**（`docs/protocol/10-Group-子协议.md`）：
+- 声称 Group ID slug 为 4-14 位小写字母数字
+- 声称总长度 6-16 字符
+
+**实际格式**（基于服务端代码 `extensions/services/group/service.py`）：
+- **Legacy 格式**: `g-[a-z0-9]{4,32}` — 4 到 32 位
+- **新格式**: `[a-z0-9]{5,}` — 5 位或更多，无上限
+- **Group name 格式**: `[a-z0-9][a-z0-9_-]{3,63}` — 4 到 64 个字符
+
+已更新文档以反映实际实现。
+
+### 2. Python SDK 实现
+
+#### 新增模块
+- `python/src/aun_core/validators.py`
+  - `validate_aid_format(aid, *, param_name="aid") -> str`
+  - `validate_group_id_format(group_id, *, param_name="group_id") -> str`
+
+#### 集成位置
+- `python/src/aun_core/_client/rpc_pipeline.py` (`validate_outbound_call` 方法)
+  - `message.send` → 校验 `to` (AID)
+  - `group.send` → 校验 `group_id`
+  - `message.thought.put` → 校验 `to` (AID)
+  - `message.thought.get` → 校验 `sender_aid` (AID)
+  - `group.thought.put` → 校验 `group_id`
+  - `group.thought.get` → 校验 `sender_aid` (AID) 和 `group_id`
+
+- `python/src/aun_core/client.py` (`notify` 方法)
+  - 校验 `to` (AID)
+  - 校验 `group_id`
+
+#### 测试
+- `python/tests/unit/test_validators.py` — 26 个测试用例
+- 所有单元测试通过（1058 个）
+
+### 3. Go/TypeScript/JavaScript SDK 实现
+
+四个 SDK 全部在 **pipeline 层**（`validateOutboundCall` / `validate_outbound_call`）集成校验，确保 `client.call(...)` 直接调用也无法绕过：
+
+| SDK | 校验器文件 | 集成点 | 测试结果 |
+|-----|-----------|--------|---------|
+| Python | `python/src/aun_core/validators.py` | `_client/rpc_pipeline.py` + `client.py` notify | 1058 单测通过 |
+| Go | `go/validators.go` | `client_rpc_pipeline.go` + `client.go` Notify | 全部通过 |
+| TypeScript | `ts/src/validators.ts` | `client/rpc-pipeline.ts` + `client.ts` notify | 582 单测通过 |
+| JavaScript | `js/src/validators.ts` | `client/rpc-pipeline.ts` + `client.ts` notify | 599 单测通过 |
+
+**注意**：TS SDK 最初由 workflow 放在 facade 层（`facades.ts`），存在被 `client.call()` 绕过的风险，已修正为 pipeline 层（与其他三个 SDK 对齐）。facade 层保留了冗余的早期校验。
+
+**测试夹具修正**：四个 SDK 的测试中存在不合法的占位标识符（如 `bob.*` name 仅 3 字符、`g1`/`g-1` group base 过短），已统一改为合法形式（`bob1.*`、`grp01`、`g-test1`），并同步更新对应的 seq-tracker namespace（`group:g1` → `group:grp01`）。
+
+## AID 格式规范
+
+```
+{name}.{issuer}
+```
+
+- **name**: 4-64 字节，仅 `[a-z0-9_-]`，首字符不能是 `-`，不能以 `guest` 开头
+- **issuer**: 合法的可注册域名
+
+**示例**:
+- ✅ `alice.aid.pub`
+- ✅ `test_user.example.com`
+- ✅ `user-123.aid.pub`
+- ❌ `bob.aid.pub` (name 只有 3 个字符)
+- ❌ `__system__` (无 issuer，包含非法字符)
+- ❌ `guest.aid.pub` (以 guest 开头)
+
+## Group ID 格式规范
+
+### Base 格式（不含域名部分）
+
+支持三种格式：
+
+1. **Legacy 格式**: `g-[a-z0-9]{4,32}`
+   - 以 `g-` 开头
+   - 后接 4 到 32 位小写字母或数字
+   - 示例: `g-abc123`, `g-test`
+
+2. **新格式**: `[a-z0-9]{5,}`
+   - 5 位或更多小写字母或数字
+   - 无上限
+   - 示例: `12345`, `abcdef`
+
+3. **Group name 格式**: `[a-z0-9][a-z0-9_-]{3,63}`
+   - 4 到 64 个字符
+   - 首字符为 `[a-z0-9]`
+   - 可包含下划线和短横线
+   - 示例: `team_alpha`, `my-group`
+
+### 完整格式
+
+- `group.{issuer}/{base}` — canonical 格式
+- `{base}.{issuer}` — 旧格式（会被规范化）
+- `{base}@{issuer}` — 兼容格式（会被规范化）
+- `{base}` — 本域简写（需要服务端补全）
+
+**示例**:
+- ✅ `g-abc123.aid.pub`
+- ✅ `group.aid.pub/g-test1`
+- ✅ `team_alpha`
+- ✅ `12345678`
+- ❌ `g-1` (只有 3 个字符)
+- ❌ `abc` (只有 3 个字符，不满足任何格式)
+
+## 服务端已有校验
+
+服务端在 `group.create` 中已经有以下校验：
+
+```python
+# extensions/services/group/service.py:1036-1037
+if requested_group_id and self._is_numeric_group_id(requested_group_id):
+    raise ValueError("custom group_id cannot be numeric; numeric group_id is reserved for generated group_no")
+```
+
+**规则**: 创建命名群时，群 ID 不能为纯数字。纯数字的 ID 只能由系统自动分配，以免冲突。
+
+## 验证效果
+
+客户端校验成功拦截以下非法格式：
+- `__system__` → `ValidationError: Invalid aid '__system__': must be in format '{name}.{issuer}'`
+- `bob.aid.pub` → `ValidationError: Invalid aid 'bob.aid.pub': name 'bob' must be 4-64 characters`
+- `g-1` → `ValidationError: Invalid group_id 'g-1': base 'g-1' must be one of: ...`
+
+## 参考
+
+- Python SDK 实现: `python/src/aun_core/validators.py`
+- 服务端格式定义: `extensions/services/group/service.py:53-58`
+- 协议文档: `docs/protocol/10-Group-子协议.md`
+- SDK 文档: `docs/sdk/03-核心概念.md`

package/_packed_docs/CHANGELOG.md

@@ -6,6 +6,62 @@
 
 ---
 
+## 0.5.1 — 2026-07-01
+
+### ⚠️ 重大变更（Breaking Changes）
+
+#### 群组标识符统一为 GROUP_AID
+- **GROUP_ID 废弃**：历史 `group.{domain}/{base}` 格式已废弃，统一为 `{base}.{issuer}` 格式（group_aid）
+- **兼容转换**：`normalizeGroupId()` 函数保留向后兼容，自动转换旧格式到新格式
+- **新增函数**：`convertToGroupAid()` 显式转换任意历史格式到标准 group_aid
+- **RPC 参数**：`group_id` 字段名保留但值为 group_aid；新增 `group_aid` 参数与 `group_id` 等价
+- **影响范围**：所有群组相关 API（`group.send` / `group.pull` / `group.fs.*` 等）
+
+#### 移除 V1 E2EE 实现
+- **完全移除**：删除所有 V1 端到端加密代码（epoch key、群组加密管理器、V1 群组加密）
+- **仅保留 V2**：E2EE 功能完全迁移到 V2 协议（消息级密钥 + 逐设备 wrap + 状态签名）
+- **简化接口**：V2 E2EE 协调器大幅重构，移除 V1 兼容层
+- **注意**：此版本不向后兼容 V1 加密消息
+
+### 新功能
+
+#### Storage & Group FS 能力扩展
+- **Storage VFS P4**：新增 `touch()` 方法，支持创建空文件或更新文件时间戳
+- **Storage VFS P4**：新增 `du()` 方法，支持查询目录或文件的磁盘使用统计
+- **Storage VFS P6**：扩展 `getAcl()` / `listAcl()` 方法，支持 ACL 权限查询
+- **Group FS**：新增 `getAcl()` / `listAcl()` / `removeAcl()` 方法，完善群文件 ACL 管理
+- **Storage LowLevel**：补齐底层 RPC 映射，覆盖 `storage.fs.*` / `storage.object.*` 完整能力
+
+### 修复
+
+#### Storage & Group FS
+- 修复 `group.send` / `group.pull` 缺失 `group_id` 必填校验问题
+- 修复 `group.fs` 权限角色 (`role`) 在 ACL 展示中的格式错误
+- 修复 `storage.fs.symlink` 符号链接操作的路径解析问题
+- 修复 `storage.fs.memberdata` 路由逻辑错误
+- 修复 `storage.fs.mount` 挂载点权限校验问题
+
+#### 服务端性能优化（影响 SDK 行为）
+- Gateway 连接池改为可配置，降低高并发下的连接瓶颈
+- Group 推送改为异步化，提升大群消息分发性能
+- Message seq 号段化分配，减少数据库争抢
+- Message 短暂消息 (`persist=false`) 改用内存缓冲 + 异步推送
+
+### 改进
+
+- 路径校验增强：`storage.fs` / `group.fs` 路径参数增加规范化校验，拒绝 `..` / 空路径 / 非法字符
+- 系统目录保护：`memberdata` / `group_data` 写操作增加保护，防止误删系统目录
+- Validators：新增跨语言 `validatePath()` / `validateAid()` 等校验函数，四语言行为对齐
+- 浏览器环境保持 Blob/Uint8Array/ArrayBuffer 数据源支持，无本地文件路径依赖
+
+### 测试
+
+- 新增 `storage.spec.ts` E2E 测试（浏览器环境 `touch` / `du`）
+- 新增 `group-fs.spec.ts` E2E 测试（浏览器环境 ACL 操作）
+- 扩展 `storage-vfs-p5.test.ts` 单元测试覆盖新增能力
+
+---
+
 ## 0.5.0 — 2026-06-17
 
 ### 新功能