Harden attachment access controls and stabilize the Weixin bridge.

This persists referenced media safely, adds explicit attachment ACL/backfill flows, and fixes the Weixin sidecar so official login state can bridge reliably into oclaw without duplicate replays or dropped replies.

Made-with: Cursor

docs/attachment-acl.md

@@ -0,0 +1,72 @@
+# Attachment ACL（附件访问控制）
+
+本文档说明 admin chat 附件下载鉴权的访问控制策略、回填流程与 strict 模式上线建议。
+
+## 背景
+
+系统把工具结果/上传文件等二进制内容落盘为 `attachment_id`（内容 hash），前端通过：
+
+- `GET /admin/api/chat/attachments/{attachment_id}`
+
+获取附件 bytes（下载/预览）。
+
+为避免仅凭 `attachment_id` 造成越权读取，需要对下载接口做归属校验。
+
+## 数据结构
+
+- **`attachment_acl`**
+  - 用途：记录附件归属关系（哪个租户/用户/会话以何种来源产生/引用了该附件）
+  - 主键：`(attachment_id, tenant_id, user_id, session_id, source)`
+
+## 鉴权策略
+
+下载接口会校验：
+
+- `attachment_id` 格式合法（64 位 hex）
+- 当前登录用户是否被 ACL 授权访问该附件
+- 头像附件通过 `avatar_attachment_id` 放行（不走 ACL）
+
+## strict 模式
+
+环境变量：
+
+- `AIA_ATTACHMENT_ACL_STRICT=1`
+
+行为：
+
+- 下载鉴权只信 `attachment_acl`（以及头像 `avatar_attachment_id`）
+- **不会**回退扫描历史 `chat_message.attachments`
+
+适用场景：
+
+- 生产环境附件访问收口
+- 已完成历史数据 ACL 回填
+
+## 回填流程（Admin）
+
+为了让历史消息中的附件也能被 strict 模式识别，需要先回填 ACL。
+
+入口（仅 `administrator` 可见/可调用）：
+
+- 管理台 Chat 页面右上角菜单：**回填 ACL**
+- 或接口：`POST /admin/api/chat/admin/attachments/acl/backfill?limit_messages=...`
+
+建议流程：
+
+1. 在低峰期执行回填（默认扫描最近 50k 条含 attachments 的消息）
+2. 观察返回结果（扫描/插入计数）
+3. 开启 `AIA_ATTACHMENT_ACL_STRICT=1`
+
+## 相关配置放一起（ENV）
+
+- `AIA_MAX_ATTACHMENT_BYTES`：控制工具结果 base64 落盘单附件大小上限
+- `AIA_ATTACHMENT_ACL_STRICT`：下载鉴权严格只信 `attachment_acl`
+
+## 回滚建议
+
+如 strict 模式误伤历史附件下载（403）：
+
+1. 临时关闭 strict：`AIA_ATTACHMENT_ACL_STRICT=0`
+2. 再次执行回填（提高 `limit_messages`）
+3. 重新开启 strict
+