update user docs

Author: MenxLi

docs/.vitepress/config.mts

@@ -25,6 +25,8 @@ export default defineConfig({
           { text: 'CLI Commands', link: '/commands' },
           { text: 'Environment Variables', link: '/environment-variables' },
           { text: 'Permission System', link: '/permission' },
+          { text: 'User Management', link: '/userman' },
+          { text: 'Virtual User', link: '/virtual-user' },
           { text: 'Configure Single Directory', link: '/lfssdir' },
           { text: 'WebDAV', link: '/webdav' },
           { text: 'Development', link: '/Development' },

docs/lfssdir.md

@@ -1,6 +1,8 @@
 
 # Configure Single Directory
 
+> Added in v0.14.0.
+
 You can configure the behavior of a single directory by placing a special file named `.lfssdir.json` in it.
 
 The file should contain a JSON object with the following optional fields:

docs/permission.md

@@ -9,12 +9,24 @@ There are different access levels for different users, which determine what oper
 - <span class="perm">read</span>: only `GET` permission and listing directories.
 - <span class="perm">none</span>: no permissions.
 
+:::info
+**directory** path ends with `/` and **file** does not end with `/`.
+:::
+
 ## User Roles
-There are two user roles in the system: Admin and Normal User ("users" are like "buckets" to some extent).  
-A user have <span class="perm">all</span> permissions of the files and directories under its path (starting with `/<user>/`). 
-Admins have <span class="perm">admin</span> permissions of all files and directories.
+There are three user roles in the system: Admin, Normal User, and Virtual User 
+- A normal user have <span class="perm">all</span> permissions of the files and directories under its path (starting with `/<user>/`). 
+- A virtual user doesn't have it's own path.
+- Admins have <span class="perm">admin</span> permissions of all files and directories.
+
+:::tip **Users are like "buckets" or "access keys" to some extent**  
+Normal users are like "buckets" that own files and directories.  
+Virtual users are like "access keys" that have expiry time and limited access to some users' paths.
+:::
+
+**Below sections only discuss normal users and admins. For virtual users, please refer to the [Virtual User](./virtual-user.md) document.**
+
 
-> **directory** path ends with `/` and **file** does not end with `/`.
 
 ### Ownership
 There are two types of ownership for files (terms used in permission checks):

docs/userman.md

@@ -0,0 +1,55 @@
+# User Management
+
+All user management operations can be performed via the `lfss-user` command. 
+Using `-h` or `--help` flag will show the help message with all available subcommands and options:
+```bash
+> lfss-user -h                                                     
+usage: lfss-user [-h] {add,add-virtual,delete,set,list,set-peer,set-expire} ...
+
+positional arguments:
+  {add,add-virtual,delete,set,list,set-peer,set-expire}
+    add                 Add a new user
+    add-virtual         Add a virtual (hidden) user, username will be prefixed with '.v-'
+    set                 Set user properties, refer to 'add' subcommand for details on each argument
+    list                List specified users, or detailed info with -l
+    set-peer            Set peer user relationship
+    set-expire          Set or clear user expire time
+```
+
+Most of the commands are self-explanatory, 
+and the details flags of each command can be found by using the `-h` flag after the subcommand. 
+
+**Below are some extra explanations for a few commands.**
+
+## Check user details
+Besides listing all users, 
+to check the details of the user(s), you can also use the `list` subcommand with the `-l/--long` flag, 
+followed by one or more usernames. For example:
+```bash
+> lfss-user list -l alice
+User alice (id=20, admin=0, created at 2025-11-13 03:15:09, last active at 2025-11-13 03:15:09, storage=1.00G, permission=UNSET)
+- Credential:  d9cf3312d1da59721fd28a5d3075c65b858a373d37e479c2defd6bfeee207677
+- Storage: 0B / 1.00G
+- Expire: never
+- Peers [READ]: bob, carol
+- Peers [WRITE]: dave
+```
+
+## Delete user
+To delete a user, you can use the `delete` subcommand.
+```bash
+> lfss-user delete alice
+```
+
+Note: there are a few clean up operations that need to be done when deleting a user, 
+so the deletion process may take some time depending on the number of files owned by the user, 
+and because this process is transactional, it may block the system for a short period.
+
+Specifically, user deletion involves:
+- Remove user record from the database.
+- Remove all files under the user's path.
+- Transfer ownership of all files owned by the user under other users' paths to the path owner.
+
+If any of the above steps fail 
+(for example, the path owner has insufficient storage space to take over the ownership), 
+the deletion process will be rolled back to ensure data consistency.

docs/virtual-user.md

@@ -0,0 +1,44 @@
+# Virtual User
+
+> Added in v0.16.0.
+
+Virtual user is a user without its own path. 
+It can only access files and directories under other users' paths according to the peer user settings, 
+and anybody want to access virtual user's path will get permission denied.
+
+In addition, virtual users is preferred to have an expiry time, after which they can no longer access the system. 
+This makes virtual users essentially "access keys" to some users' paths.
+
+The virtual user always have a name starting with `.v-`, 
+a typical virtual user name looks like `.v-{tag}-{id}`. 
+The tag is used to identify the purpose of the virtual user, and the id is a unique random string.
+
+To create a virtual user, you can use either the CLI command or the admin API. For example:
+
+```bash
+lfss-user add-virtual 
+    --tag tmpuser 
+    --expire 1d12h 
+    --max-storage 100M
+    --peers "read:alice,bob;write:carol"
+```
+
+```python
+Client().add_virtual_user(
+    tag="tmpuser",
+    expire="1d12h",
+    max_storage="100M",
+    peers={
+        AccessLevel.READ: ["alice", "bob"], 
+        AccessLevel.WRITE: ["carol"]
+    }
+)
+```
+
+To modify the expiry time of a virtual user, you can use the CLI command. For example:
+```bash
+lfss-user set-expire .v-tmpuser-VwFdjKpiqm4 2d1h10s
+```
+
+The management of virtual users is exactly the same as normal users. *e.g.*, via `lfss-user` command or admin API.
+

lfss/cli/user.py

@@ -11,7 +11,7 @@
 async def _main():
     parser = argparse.ArgumentParser()
     sp = parser.add_subparsers(dest='subparser_name', required=True)
-    sp_add = sp.add_parser('add')
+    sp_add = sp.add_parser('add', help="Add a new user")
     sp_add.add_argument('username', type=str)
     sp_add.add_argument('password', nargs='?', type=str, default=None)
     sp_add.add_argument('--admin', action='store_true', help='Set user as admin')
@@ -40,17 +40,17 @@ def parse_bool(s):
     sp_set.add_argument('--permission', type=parse_permission, default=None)
     sp_set.add_argument('--max-storage', type=parse_storage_size, default=None)
 
-    sp_list = sp.add_parser('list')
+    sp_list = sp.add_parser('list', help="List specified users, or detailed info with -l")
     sp_list.add_argument("username", nargs='*', type=str, default=None)
     sp_list.add_argument("-l", "--long", action="store_true", help="Show detailed information, including credential and peer users")
     sp_list.add_argument("--hidden", action="store_true", help="Include hidden users (virtual users) in the listing")
 
-    sp_peer = sp.add_parser('set-peer')
+    sp_peer = sp.add_parser('set-peer', help="Set peer user relationship")
     sp_peer.add_argument('src_username', type=str)
     sp_peer.add_argument('dst_username', type=str)
     sp_peer.add_argument('--level', type=parse_access_level, default=AccessLevel.READ, help="Access level")
 
-    sp_expire = sp.add_parser('set-expire')
+    sp_expire = sp.add_parser('set-expire', help="Set or clear user expire time")
     sp_expire.add_argument('username', type=str)
     sp_expire.add_argument('expire_time', type=str, nargs='?', default=None, help="Expire time in seconds or a string like '1d2h3m4s'. If not provided, the user will never expire.")