feat(permissions): implement fine-grained permission control

[Lanfei]

Description / 描述

This PR implements a fine-grained, per-user read/write permission system at the meta level, allowing administrators to restrict specific users from accessing or modifying
certain paths. It also refactors existing permission check functions for clarity and adds comprehensive test coverage.

本 PR 在 meta
层面实现了细粒度的用户读/写权限系统，允许管理员限制特定用户对某些路径的访问或修改权限。同时对现有权限检查函数进行了重命名重构以提升可读性，并添加了完整的测试覆盖。

Key changes / 主要变更：

• Add ReadUsers/WriteUsers fields to the Meta model with sub-directory inheritance flags
  在 Meta 模型中新增 ReadUsers/WriteUsers 字段，支持子目录继承标志
• Implement CanRead and CanWrite permission check functions in server/common
  在 server/common 中实现 CanRead 和 CanWrite 权限检查函数
• Filter file list results based on user read permissions
  根据用户读权限对文件列表结果进行过滤
• Add permission checks across all file operations (FTP, HTTP handlers, WebDAV)
  在所有文件操作（FTP、HTTP 处理器、WebDAV）中添加权限检查
• Rename functions for clarity: User.CanWrite() → User.CanCreateFilesOrFolders(), common.CanWrite() → common.CanWriteContentBypassUserPerms(), common.IsApply() →
  common.MetaCoversPath()
  重命名函数以提升可读性：User.CanWrite() → User.CanCreateFilesOrFolders()，common.CanWrite() → common.CanWriteContentBypassUserPerms()，common.IsApply() →
  common.MetaCoversPath()

Note / 注意： Batch and recursive operations (FsMove, FsCopy, FsRemove, FsRecursiveMove, FsBatchRename, FsRegexRename) currently check parent directory
permissions only. Individual item permission checks are not performed for performance reasons.
批量与递归操作（FsMove、FsCopy、FsRemove、FsRecursiveMove、FsBatchRename、FsRegexRename）当前仅检查父目录权限，出于性能考量，不对单个子项逐一检查权限。

Motivation and Context / 背景

The existing permission system only supports coarse-grained flags (e.g., global write permission). There was no way to restrict specific users from reading or writing to
particular paths without affecting all users. This PR addresses that gap by introducing a per-user allowlist at the meta level.

现有权限系统仅支持粗粒度的标志位（如全局写权限），无法在不影响其他用户的情况下限制特定用户对特定路径的读写访问。本 PR 通过在 meta 层面引入基于用户的白名单机制来填补这一空白。

Relates to #1328
Closes #1257
Closes #1267
Closes #346
Closes #1753

How Has This Been Tested? / 测试

• Added TestCanRead, TestCanWrite, TestCanAccessWithReadPermissions, and TestWritePermissionCombinations to validate the three-layer permission system
  新增 TestCanRead、TestCanWrite、TestCanAccessWithReadPermissions 及 TestWritePermissionCombinations，验证三层权限体系
• Test scenarios cover: nil user/meta, sub-path inheritance, user whitelists, and root-level restrictions
  测试场景覆盖：nil 用户/meta、子路径继承、用户白名单及根路径限制
• Added 43 test scenarios for MetaCoversPath, CanWriteContentBypassUserPerms, getReadme, getHeader, isEncrypt, and whetherHide
  为 MetaCoversPath、CanWriteContentBypassUserPerms、getReadme、getHeader、isEncrypt、whetherHide 新增 43 个测试场景
• Added list_test.go and fsread_test.go for coverage of list filtering and read handler logic
  新增 list_test.go 和 fsread_test.go，覆盖列表过滤与读取处理器逻辑

Checklist / 检查清单

• I have read the CONTRIBUTING document.
  我已阅读 CONTRIBUTING 文档。
• I have formatted my code with go fmt or prettier.
  我已使用 go fmt 或 prettier 格式化提交的代码。
• I have added appropriate labels to this PR (or mentioned needed labels in the description if lacking permissions).
  我已为此 PR 添加了适当的标签（如无权限或需要的标签不存在，请在描述中说明，管理员将后续处理）。
• I have requested review from relevant code authors using the "Request review" feature when applicable.
  我已在适当情况下使用"Request review"功能请求相关代码作者进行审查。
• I have updated the repository accordingly (If it's needed).
  我已相应更新了相关仓库（若适用）。
  • OpenList-Frontend - feat(permissions): implement fine-grained permission control OpenList-Frontend#386
  • OpenList-Docs - docs(meta): implement fine-grained permission control OpenList-Docs#310

[Lanfei]

Hi @xrgzs @PIKACHUIM, this PR has been open for about 3 weeks now. CI is all green and there are no merge conflicts. The companion frontend PR (OpenList-Frontend#386) and docs PR (OpenList-Docs#310) are also ready. Could you help schedule a review? Happy to make any adjustments based on your feedback. Thanks!

[Copilot]

Pull request overview

This PR introduces meta-level, per-user read/write allowlists and wires the new permission checks through core file operations (HTTP handlers, FTP, WebDAV), including filtering list results by read permission and expanding automated test coverage for the new permission logic.

Changes:

• Extend Meta with ReadUsers/WriteUsers (+ sub-path inheritance flags) and add common.CanRead / common.CanWrite checks.
• Apply permission checks across file operations (list/read/write/manage) including WebDAV/FTP and list filtering.
• Add/expand tests for meta path coverage and permission combinations.

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
internal/model/meta.go	Adds per-user read/write allowlists to Meta (JSON-serialized).
server/common/check.go	Introduces CanRead/CanWrite, refactors path coverage helper(s).
internal/fs/list.go	Filters directory listings based on per-user read permission.
server/handles/fsread.go	Adjusts list response fields and write/tool availability logic.
server/handles/fsmanage.go	Adds parent-meta permission checks to manage operations.
server/webdav.go	Updates WebDAV auth/middleware context values for permission checks.
server/webdav/webdav.go	Adds CanAccess/CanWrite enforcement for WebDAV operations.
server/webdav/file.go	Adds permission gates to WebDAV copy/move helpers.
server/middlewares/fsup.go	Refactors upload middleware permission checks.
server/ftp/fsup.go / server/ftp/fsmanage.go / server/ftp/fsread.go	Adds/adjusts FTP permission checks using new helpers.
server/handles/archive.go / server/handles/offline_download.go	Adds meta permission checks for archive/decompress and offline download creation.
server/common/check_test.go / internal/fs/list_test.go / server/handles/fsread_test.go	Adds/expands tests for the new permission model and helpers.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[Lanfei]

@xrgzs @PIKACHUIM All Copilot review comments have been addressed. Could you please take a look when you have a chance? Thanks!

[xrgzs]

@Lanfei Can it smoothly migrate from the old version to the new version? If not, please refine the migration code.

[Lanfei]

@xrgzs Yes, migration from older versions is smooth — no manual migration patch is needed.

GORM's AutoMigrate (called at startup in internal/db/db.go) will automatically ADD COLUMN for the four new fields on the metas table: read_users, read_users_sub, write_users, write_users_sub.

For existing rows, read_users and write_users will be NULL, which GORM's JSON serializer deserializes as a nil slice. Since CanRead/CanWrite only restrict access when len(ReadUsers) > 0 / len(WriteUsers) > 0, existing metas with no value set will behave exactly as before — no access restrictions are added. The two new bool columns default to false, which is also the safe/permissive default.

In short: upgrading applies additive schema changes only, and the zero-value semantics preserve backward-compatible behavior for all existing data.

[liliang1112]

@Lanfei @xrgzs @PIKACHUIM Could you please take a look at the approval when you have time? This feature is very important to me. Thank you!

[Lanfei]

@Lanfei @xrgzs @PIKACHUIM Could you please take a look at the approval when you have time? This feature is very important to me. Thank you!

Yeah, I am waiting for the approval as well :P

[liliang1112]

@xrgzs @PIKACHUIM I see that the author has already solved the above issues. Could you please help arrange for a review. Thank you!

[PIKACHUIM]

@liliang1112 @Lanfei Thank you for your contributions.

We are deeply moved that you are implementing the features we have planned.
However, the team members are currently quite busy, so we may need some time to test these features.

At first glance, this feature appears to be a major update / breaking change.
If possible, we would like to merge this PR into the 5.0 version branch (Next).

We previously designed a simple plan for reference:
Since this plan is still in its early stages, you are not required to follow the structure below.

OpenList File System Architecture

File Configuration

graph LR
A[Permission Config]
    A --> B(Permission Group A)
    A --> C(Permission Group B)
    A --> D(.......)
    B --> B1(Encrypt Content: bool)
    B --> B2(Encrypt Name: bool)
    B --> B3(Hide Directory: bool)
    B --> B4(Compress File: bool)
    B --> B5(Split Volume: bool)
    B --> B6(File Permission: 10bits)
    B --> B7(File Owner: number)
    B --> B8(Volume Size: number)
    B --> B9(Access Password: string)
    B --> BA(Encryption Password: string)

Loading

Encrypted paths must not overlap; traversal scan is required when adding new paths
If file content encryption is enabled, a password must be provided; filename-only encryption does not require a password
A default permission is needed: default is no encryption and public access, but it can be modified

File Configuration Page

graph LR
A[Path Config]
    A --> B(/path1/) --> B1(Permission Group A)
    A --> C(/path2/) --> C1(Permission Group A)
    A --> D(/path3/pic.jpg) --> D1(Permission Group B)
    A --> E(/path4/file.mp4) --> E1(Permission Group B)
    A --> F(...............)

Loading

Encryption Execution Flow

graph LR
A(Upload /path2/file.mp4)
    A --> B1(Match /path1/) --> C1(Miss)
    A --> B2(Match /path2/) --> C2(Hit) --> D1(Execute Encryption)
    F(file.mp4) --> G1(Encrypt File) --> J1(file.mp4.u8BMxMpD.enc)
    F(file.mp4) --> G2(Encrypt Name) --> J2(ZmlsZS5tcDQ=.b64)
    F(file.mp4) --> G3(Compress & Split) --> J3(file.mp4.f001.zip)
    X1[ZmlsZS5tcDQ=.b64] -->X4[.zip] -->X2[.f001] -->X3[.u8BMxMpD.enc] 
    Y1[Encrypted Filename] --> Y4[Compression] --> Y2[Split Volume] --> Y3[Encryption] 

Loading

Compression + Encryption suffix: ZEC, Encryption only: ENC, Compression only: ZIP
PS: If no rules match, the file is uploaded as-is without encryption or compression.

File Access Flow

graph LR
A1(/path2/file.mp4.enc)
    A1 --> B1(Suffix is ENC) --> C1(Display as file.mp4)
    B1 --> B11(Match /path1/) --> C11(Miss)
    B1 --> B12(Match /path2/) --> C12(Hit) --> D11(Decrypt)
    
A2(/path2/ZmlsZS5tcDQ=.b64.u8BMxMpD.enc)
    A2 --> B2(Suffix is ENC) --> C2(Decrypt Filename) -->D2(Display as file.mp4)
    B2 --> B21(Match /path1/) --> C21(Miss)
    B2 --> B22(Match /path2/) --> C22(Hit) --> D21(Decrypt)

Loading

PS: If no rules match and the file is encrypted, a password must be entered.

[PIKACHUIM]

Regarding the file system architecture design provided in our previous reply, we would like to add the following:
We aim to build a unified file system permission and configuration management system.
Therefore, we envision the overall structure as follows:

a. Different default read/write permissions can be set for individual users
b. Different default permissions can be configured for different directories
Thus, we hope you can review the design structure we submitted, but there is no need to strictly follow our design, as we have not yet reached a unified and definitive conclusion internally. If possible, we would like to discuss the feature planning with you.

[文件系统Opfs Layout]

graph LR
A[文件系统Opfs Layout]
    A --> B(网盘驱动Driver)
    B --> B1[驱动A]
    B --> B2[驱动B]

Loading

[网盘驱动File Driver]

graph LR
A[网盘驱动File Driver]
     A --> B(配置信息Config)
     A --> C(单个文件Module)
     C --> C1[文件A]
     C --> C2[文件B]

Loading

[单个文件File Module]

graph LR
A[单个文件File Module]
    A --> B(文件路径Path: string)
    A --> C(...........)
    A --> D(文件权限Mask（8进制）: number)
    A --> E(所有用户User: string)

Loading

[File Mask]

graph LR
A[文件权限FileMask 16B]
    A --> A0(0000类属性) -->B0(加密文件,加密名称,压缩文件,保留标识)
    A --> A1(0000所有者) -->B1(允许下载,允许写入,允许删除,保留标识)
    A --> A2(0000用户组) -->B2(允许下载,允许写入,允许删除,保留标识)
    A --> A3(0000其他人) -->B3(允许下载,允许写入,允许删除,保留标识)

Loading

[Lanfei]

@PIKACHUIM Thank you for the detailed response. I’m really excited to hear about the 5.0 direction.

Given the current situation, I’d like to suggest a conditional approach:

• If 5.0 introduces a fully new file/permission architecture and the release is still some time away, we could merge this PR first. It is a solid and practical solution built on the current system, and fine-grained permission control is already widely requested by users (while still respecting maintainers’ bandwidth).
• If the 5.0 architecture is close to the current model and the release plan is already relatively clear, then I’m happy to retarget this work to the 5.0 branch instead.

What do you think?

[jyxjjj]

Sounds good—merge now, redesign later on the 5.0 branch.

[PIKACHUIM]

The code is fine, but rigorous testing is necessary.

[liliang1112]

@PIKACHUIM @xrgzs Thank you for your detailed reply. Could you please arrange for a merger

[jyxjjj]

Pika may not be in a position to conduct a review right now.
And KirCute and I have been quite busy recently, so we unable to thoroughly review changes of this scale right now.
Given the scope of the changes, it would be helpful if the submitter could break them down more carefully into smaller, more reviewable pieces.
That would make it much easier for us to review them properly.
I took a quick look, but not very carefully, and didn’t really find any issues.

[xrgzs]

Guests can refresh the cache without authorization. Although the refresh icon existed on the frontend before, it previously required a password when clicked. But I consider this a bug rather than a feature.

[Lanfei]

Thanks for the review.

I’m not sure Write is the right boundary for refresh. Refresh is closer to list/read behavior, and there is a non-obvious case here: a user may not have write permission but may still be allowed to copy/move/rename/delete in some combinations. If refresh is blocked by write, the list can remain stale after those operations, which feels unexpected.

Do you have a suggested approach here? Happy to follow your preference.

[jyxjjj]

We either preserve the previous state or directly granularize the permissions. The latter would also help solve many of the issues that 5.0 will have to address.

[xrgzs]

@Lanfei

Regarding cache issues, different users hold differing opinions. Some users believe the cache should be refreshable by guests so they can view the latest file changes. Others argue that allowing regular users to refresh the cache is insecure, and only admin should have this permission.

I suppose we should revert it to the previous state. Only users with write permissions could refresh the cache.

[xrgzs]

We either preserve the previous state or directly granularize the permissions. The latter would also help solve many of the issues that 5.0 will have to address.

In OpenList v5.0, I think the situation will become more complex. Considering that features such as audio/video transcoding and media/doc library will be added, user file permissions will grow more complicated, making it necessary to implement atomic permission control.