fix(authz): enforce current role, token revocation, S3 permissions

[PIKACHUIM]

fix(authz): 强化授权校验、令牌吊销、S3 权限与用户根目录隔离

分支：fix/security-authz-path-isolation
提交：e3a95c2
基线：2da4256（已包含 #89 / #90）
规模：4 个文件，+185 / −43

---

一、背景与动机

一次针对本仓库的安全评审（代码走查 + 隔离环境 PoC 实测）确认了若干授权与
隔离类缺陷。它们的共同特征是：「签发时刻合法」被当成了「当前仍然合法」，
以及**「路径字符串相等」被当成了「权限边界成立」**。

这些缺陷不会导致数据泄露到公网，但会在多用户部署下破坏权限模型：
已注销/已降权的管理员仍持有后台权限、禁用用户的令牌继续可用、只读用户可写入、
受限用户可越出 base_path 读写他人目录。

本 PR 只修复不改变正常接口结构的部分（无需迁移、无需前端改动），
把需要兼容性设计的问题留作后续（见 §七）。

---

二、修复内容

1. checkAdminAuth —— 管理后台授权改以数据库为权威

文件：src/backend/pkg/utils.ts

缺陷：只读取 JWT 里的 payload.role，且完全不检查 jti。
后果是「退出登录」和「把管理员降权为普通用户」都不会立即生效——旧令牌在
7 天有效期内继续拥有完整后台权限。

实测：注销后 /api/admin/* 仍返回 200；把 role 改为 0 后仍返回 200。

修复：管理员授权必须同时满足四条不变量：

1. 令牌签名有效且未过期（HS256，alg 已 pin）；
2. 令牌未被注销（jti 不在吊销名单）；
3. 用户在库中存在且未被禁用；
4. 用户的当前 role 仍是管理员。

注意不能反过来只信 JWT——那样降权/禁用同样无效。数据库是权威来源。

静态 API Token（settings.token）分支保持不变，仍在函数开头提前返回。

2. authUserFromReq —— 身份解析复检禁用状态

文件：src/backend/server/auth.ts

缺陷：只验证 JWT 签名并查找用户，缺少 disabled 判断。核心 API 走
getUserFromContext（有该检查），但 S3 网关直接复用本函数，因此绕过了限制。

修复：if (!user || user.disabled) return null。

JWT 只证明「签发时刻身份合法」，不证明「现在仍然合法」。每个身份解析入口
都必须复检当前状态。

3. S3 网关 —— 补权限位与用户根目录隔离

文件：src/backend/server/s3.ts

缺陷：路由只判断「是否登录」，随后直接操作全局虚拟路径
/${bucket}/${key}。两条后果：

• 任何已登录用户（含 permission=0 的只读用户、已禁用用户）都能上传/删除；
• 受限 base_path 的用户可以读写其他用户的目录。

修复：

能力	修复前	修复后
PutObject	仅需登录	需 WRITE_CONTENT（canWrite），管理员放行
DeleteObject	仅需登录	需 DELETE（canRemove），管理员放行
对象路径	全局 /bucket/key	<base_path>/bucket/key，并二次 isWithinUserRoot 校验
bucket/key	无校验	isValidS3Bucket 拒绝 .、..、含 / \ \0

新增 s3VirtualPath() 统一做路径映射，新增 outOfScope() 统一返回 403
（不暴露目标是否存在）。getCtx 现在透传 env，保证多环境下驱动解析正确。

兼容性：base_path 为 / 的（默认）用户路径映射完全不变，
bucket 仍即存储挂载点首段。

4. getActualPath —— 折叠点段，用户根不可越过

文件：src/backend/pkg/permission.ts

缺陷：只做字符串拼接，.. 段留给下游 resolvePath() 折叠。于是
/photos/alice + /../bob/x 会解析成 /photos/bob/x——用户根被越过。

关键区分：下游只保证「不逃出存储物理根」，不保证「不逃出用户根」。
两者不是同一个约束。

实测：受限用户通过 /fs/get 的路径参数取得其他用户目录下文件的元信息，
明文与百分号编码两种写法均成立。

修复：新增 normalizeSegments()（栈折叠 ..，空栈时钳制在根），
getActualPath 先折叠再拼接，从源头保证返回值只可能等于 base_path
或位于其下。同时新增导出 isWithinUserRoot() 供网关类入口做二次确认。

刻意不做的事：不增加 decodeURIComponent 次数。多次解码会改变合法
%2f/百分号字面量文件名的含义，与 Go 的 EncodePath 契约冲突。

5. OTP 失败计入防爆破计数

文件：src/backend/server/auth.ts

缺陷：/login 与 /login/hash 的 OTP 分支直接 return，不调用
recordLoginFailure。攻击者只要先拿到正确密码，就能以无限次尝试爆破
6 位 TOTP，而账号永远不会被锁定。

实测：连续 7 次错误 OTP 后仍可继续提交。

修复：OTP 失败调用 recordLoginFailure(c, username, c.env)，与密码失败
共用同一套 IP+用户名 / 全局限定计数与指数退避。

---

三、验证

自动化测试

cd OpenList-TSWorker
npx tsx --test "src/backend/server/*.test.ts" \
               "src/backend/pkg/*.test.ts" \
               "src/backend/internal/model/*.test.ts"

结果：225 项全部通过，0 失败（基线 2da4256）。

静态检查

• 改动文件 lint 无错误。
• ⚠️ 类型检查未执行：本仓库 node_modules 未安装 typescript，
  tsx 仅转译不做类型检查。合入前请先跑 pnpm run lint（= tsc --noEmit）。

PoC 实测口径（复现条件说明）

评审阶段在隔离环境中验证上述行为，全部使用：合成密钥、注入式内存后端、
工作区临时文件、被禁止联网的 fetch。未触碰真实账号、真实网盘、生产数据库
或私网资源。 相关临时测试文件已删除，未进入本提交。

---

四、兼容性与影响面

需要关注的行为变化

场景	变化	说明
管理员注销后访问后台	由 200 → 401	预期收紧，注销应当立即生效
管理员被降权后访问后台	由 200 → 401	预期收紧
禁用用户持有旧令牌	由可用 → 401	预期收紧
只读用户经 S3 写入	由成功 → 403	预期收紧；需授予 WRITE_CONTENT
无 DELETE 位用户经 S3 删除	由成功 → 403	预期收紧；需授予 DELETE
非根 base_path 用户的 S3 路径	bucket 现为其顶层目录	需按新映射调整客户端路径
base_path="/" 用户的 S3 路径	不变	默认部署无影响
getActualPath 含 .. 的请求	被钳制在用户根内	无合法用法受影响
OTP 连续失败	会触发锁定	正常用户不受影响

明确未改动的契约（避免误伤）

• 未给 /d、/p、/sd 增加登录要求——签名直链要保持可被
  <video src>、播放器、下载器匿名消费；
• 未给下载验签侧再拼一次 base_path（官方前端已在 URL 中携带）；
• 未全局强制 CSRF 头（现有客户端不发送）；
• 未清洗管理员主动配置的 customize_head / customize_body（这是功能）；
• 未改动 Go 兼容的密码哈希或第三方加密协议。

文档

已核对 OpenList-Docs 的 pages/guide/advanced/s3.md：该文档仅描述
「存储桶 ↔ 目录映射」的配置方式，未描述 S3 网关的认证与权限语义，
因此本次权限收紧不存在需要同步的文档描述。若后续补充 S3 网关权限说明，
需明确：需要 WRITE_CONTENT / DELETE 位、对象路径相对 base_path、
且不识别静态 API Token。

---

五、已知遗留问题（本 PR 未包含）

以下来自同一轮评审，因需要兼容性设计或更大改动面，未在本 PR 修复：

1. 归档接口：/fs/archive/list、/fs/archive/decompress 不做源路径的
   元信息密码校验、不检查 READ_ARCHIVES / DECOMPRESS 位；解压目标未做
   base_path 映射；ZIP 条目中的 ../ 可逃出目标目录（仍受存储物理根限制）。
2. 配置损坏被误当空库：map 格式把 JSON 解析失败转成 null，随后
   /api/public/init/setup 会重新开放初始化并覆盖配置。应区分
   「不存在 / 空库 / 损坏 / 读取失败」。
3. 上传体积限制：仅依据 Content-Length，缺失该头时不做拦截。
4. isSafeUrl：规范化后的 IPv4-mapped IPv6 私网地址（如
   http://[::ffff:127.0.0.1]/）未被识别。
5. 文件操作权限位：rename / remove / move / copy 仍统一使用
   canWrite，未使用已定义的 RENAME / DELETE / MOVE / COPY 位；
   导致「只有写权限也能删除」而「只有删除权限反被拒」。
6. 目录 write_users ACL：仅影响 /fs/list 返回的 write 字段提示，
   写接口未在执行时重新校验。
7. 分片上传会话：仅按原始 path+size 复用，无 owner 绑定，跨用户可能
   复用同一会话；/fs/multipart/status 无需认证。
8. 跨实例会话吊销：吊销黑名单按实例加载，且仍走旧 KV 通道，
   D1-only 环境下不保证可靠持久化与即时一致性。
9. 存储一致性：map 全量快照的 last-writer-wins、key 格式
   「先删后写」失败后旧记录丢失、D1 多批提交无整体原子性、持久化失败后
   内存缓存仍被更新。

---

六、建议的验收要点

1. base_path 非根用户的签名下载继续正常（不得 401）；
2. 管理员注销 / 降权后立即失去后台权限；
3. S3：只读用户 PUT → 403；无 DELETE 位用户 DELETE → 403；
   默认 base_path="/" 用户路径映射与修复前一致；
4. 连续错误 OTP 达到阈值后账号被锁定；
5. 含 ..（含百分号编码形式）的请求被钳制在用户根内，且合法文件名、
   中文路径、既有编码链接不受影响；
6. 公开直链 / 播放器 Range 请求 / 分享链接行为不变。

---

七、提交信息

fix(authz): enforce current role, token revocation, S3 permissions and user-root isolation

checkAdminAuth: no longer trusts the JWT role claim. Logout and demotion previously
had no effect on admin routes because only payload.role was read and jti was never
checked; it now re-checks the revocation list, the disabled flag and the current
database role.

authUserFromReq: reject disabled users. JWT only proves the identity was valid when
issued; every resolver must re-check current status. Core APIs went through
getUserFromContext (which checks), but the S3 gateway reused this function and did not.

S3 gateway: PutObject now requires WRITE_CONTENT and DeleteObject requires DELETE;
object paths are scoped to the caller's base_path and bucket/key are validated.
Previously any authenticated user, including read-only and disabled accounts,
could write anywhere.

getActualPath: fold dot segments before joining base_path so a user cannot escape
their root via plain or percent-encoded traversal.

verify: 225 tests pass.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	openlist-work	22dd197	Sep 29 2026, 07:30 AM

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	openlist-tsworkers	22dd197	Sep 29 2026, 07:31 AM

[pikachuren]

🙏 感谢 @PIKACHUIM 提交！
🤖 AI 自动审核声明：本评审报告由 AI 自动生成，当前使用 GLM 模型进行分析。
⚠️ AI 分析结果仅供参考，可能存在误判或遗漏。如您发现任何问题或有不同意见，欢迎随时提出讨论和纠正。
⚠️ 重要提醒：即使 AI 评审认为代码质量良好且建议合并，最终是否合并仍需由项目维护者进行人工判定。

🎯 结论

🔄 Request Changes — 权限修复整体扎实，但上传大小限制的修复不完整，S3 网关完全缺失大小限制

📖 概要

一批授权加固：JWT 解析复核 disabled、OTP 失败纳入防爆破计数、目录级写 ACL 真正执行、归档读取走 meta ACL、ZIP 条目路径清理、上传大小按实际字节数复核、S3 网关补权限位与用户根目录隔离、WebAuthn challenge/origin/UV 校验。

🧭 整体方案

每个修复点都标注了「历史缺陷 + 实测复现」，用 isWithinUserRoot 统一收口路径越界，方案方向正确。问题在于大小限制这条线只修了一半。

📊 变更统计

8+ 个文件 | 功能 ⭐⭐⭐⭐ | 最小改动 ⭐⭐⭐⭐ | 前向兼容 ⭐⭐⭐⭐ | 方案设计 ⭐⭐⭐

🚨 关键问题

P1（建议修复后再合并）：

• ⚠️ server/fs.ts:1655-1673（/fs/multipart/part）仍只做 Content-Length 预检，无该头时直接 Buffer.from(await c.req.arrayBuffer())——readBodyWithinLimit 想封死的「省略头绕过上限」路径在这里依然可用。该函数只接入了 /fs/put（L974）和 /fs/upload/part（L1104）。建议本路由同样改用 readBodyWithinLimit(c, true)，并把 L1655 的预检删掉换成统一入口。
• ⚠️ server/s3.ts:206（PutObject）Buffer.from(await c.req.arrayBuffer()) 之前没有任何大小限制——MAX_UPLOAD/MAX_UPPART 都不生效，超大请求体可整包读入内存。与 /fs/put 的防护形成明显不对称。建议复用 getUploadSizeLimit（或新增 MAX_S3_PUT）+ 实际字节数复核。

P2（可选）：

• 💡 s3.ts:206 PutObject 的 ETag 用 Date.now().toString(16) 生成，不是内容的真实哈希；对做分片续传/幂等判断的 S3 客户端可能产生误导，是否考虑至少返回空 ETag 或内容 md5？
• 💡 safeArchiveEntryPath 拒绝了 ../盘符/NUL，覆盖到位；/fs/other 签发直传 URL 后的写入路径不经过本 PR 的大小限制（预失效 #75 已单独处理失效），边界行为建议在 PR 描述中注明。

📂 逐文件分析

src/backend/server/fs.ts

改动意图：写 ACL 执行点 + 归档 ACL + 条目清理 + 上传限流。
问题分析：deniedByMetaWriteAcl / deniedByMetaReadAcl 管理员放行、meta 缺失时放行的语义与 pkg/meta 约定一致；readBodyWithinLimit 的实际字节数复核思路正确——只是接入点不全（见 P1）。

src/backend/server/s3.ts

改动意图：S3 权限位 + base_path 隔离。
问题分析：canWrite/canRemove 权限位、isWithinUserRoot 收口、authUserFromReq 复检 disabled 都已到位；s3VirtualPath 对受限用户把 bucket 解释为自己根下的一层目录，与 /api/fs 视图一致。缺的只有大小限制（见 P1）。

src/backend/pkg/permission.ts

改动意图：normalizeSegments + isWithinUserRoot。
问题分析：.. 越根钳制、重复 / 合并正确；建议补一条「normalizeSegments('/a/../../b') === '/b'」的显式测试。

其余文件（auth.ts / webauthn.ts 等）无重大问题。

✅ 待处理清单

• [P1] /fs/multipart/part 改用 readBodyWithinLimit，封死无 Content-Length 绕过
• [P1] S3 PutObject 增加大小限制 + 实际字节数复核
• [P2] S3 ETag 语义（可选）
• [P2] normalizeSegments 补越根钳制测试（可选）

🎯 结论：🔄 Request Changes — 权限加固值得合并，但上传限流修复不完整，两条 P1 补齐后即可通过。