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/ENVIRONMENT_VARIABLES.md

@@ -181,6 +181,21 @@
   - 作用：`tool_log` 中 args/result 截断上限
   - 生效：`oclaw/platform/persistence/sqlite_store.py`
 
+- `AIA_MAX_ATTACHMENT_BYTES`
+  - 默认：`26214400`（25MB）
+  - 作用：工具结果/MCP payload 中嵌入式 base64 内容落盘为 `attachment_id` 时的单附件最大字节数（超限则不落盘，降级为 `*_ref` 元信息并标记 `attachment_too_large`）
+  - 取值：`0` 表示不限制（不推荐）
+  - 生效：`oclaw/runtime/chat/media_redact.py`
+
+- `AIA_ATTACHMENT_ACL_STRICT`
+  - 默认：`0`
+  - 作用：附件下载鉴权是否严格依赖 `attachment_acl`
+  - 说明：
+    - `0`：优先走 `attachment_acl`，缺失时仍允许回退扫描历史 `chat_message.attachments`（兼容旧数据）
+    - `1`：**严格模式**，只允许 `attachment_acl`（以及用户头像 `avatar_attachment_id`）命中的附件被下载
+  - 上线建议：先执行 Admin “ACL 回填”，再开启 strict
+  - 生效：`oclaw/interfaces/admin/chat_api.py`
+
 - `AIA_IMAGE_TOOL_RESULT_REPLAY_CAP_CHARS`
   - 默认：`4000`
   - 作用：限制历史轮次中 `query_image_attachment`（OCR/描述）结果回放到模型上下文时的 `text` 长度上限

docs/RUNBOOK.md

@@ -356,6 +356,26 @@ npm install images-mcp
 powershell -ExecutionPolicy Bypass -File .\scripts\weixin_install.ps1
 ```
 
+注意：
+
+- 脚本支持两种模式：
+  - 官方插件模式：`-UseOpenclawCli`（不校验 `runner.ts/login.ts`）
+  - 本地 sidecar 模式：`-LocalSourcePath`（会强校验 `runner.ts/login.ts`）
+
+- 默认按本地 sidecar 模式处理：必须传 `-LocalSourcePath`（指向你们自研 weixin sidecar 源码目录）。
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\weixin_install.ps1 -LocalSourcePath "D:\path\to\your-weixin-module"
+```
+
+- 若你要临时切回官方链路，可显式指定：
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\weixin_install.ps1 -UseOpenclawCli
+```
+
+- 仅本地 sidecar 模式会强校验 `runner.ts` / `login.ts` 是否存在；官方插件模式不做该校验。
+
 安装目录：
 
 - `data/channel_sidecar/oclaw-weixin/`

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
+