Permissions

LoonFS supports granular permissions on individual files and folders.

Namespaces are unrestricted by default. To use file and folder permissions, enable ACLs when creating the namespace. (Note that the access mode cannot be changed later in either direction.)

Understanding permissions

A permission grant connects a principal to a set of privileges. A principal is an application layer ID, such as a user ID or a group ID. LoonFS does not manage group membership; an implementating backend sends the applicable principal IDs with each request.

Privilege	On a folder	On a file
read	List entries and read attributes.	Read contents and attributes.
history	Read previous folder contents through a snapshot. (Requires read too.)	Read previous revisions and revision history. (Requires read too.)
write	Update attributes.	Update contents or attributes. Restoring an earlier revision also requires history.
create	Add files and folders, including moving an item into the folder.	Not applicable. (Permission for creating a file is granted using create on the parent folder.)
remove	Delete entries or move them out of the folder.	Not applicable. (Permission for deleting a file is granted using remove on the parent folder.)
share	Add or remove grants for permissions already granted to the actor.	Same as folders.
manage	Change grants and whether the folder inherits permissions. Cannot grant or remove admin.	Change grants, except admin.
admin	Full access to the namespace. (Can only be granted on the root folder.)	Not applicable.

For example, editing a file requires write on the file, while deleting it requires remove on its parent folder.

Building roles in the application layer

LoonFS stores permissions, not role names. Applications may wish to combine permissions into familiar roles:

Example role	Permissions
Upload-only	create
Viewer	read
Viewer with history	read, history
Editor	read, history, write, create, remove
Manager	read, history, write, create, remove, share, manage
Administrator	admin on the root folder

These are examples, not built-in roles. For instance, applications may wish to add the share permission to the Editor role if editors should be able to invite other users.

Inheriting permissions

A grant on a folder applies to its files and subfolders. If a user has access through several principals, those permissions are combined.

Set boundary: true on a folder to stop it from inheriting grants from its parents. The folder’s own grants still apply to its contents. For example, a restricted /finance folder can stop inheriting the access granted to everyone at /.

There are no explicit deny rules. Namespace administrators can access every file and folder, including folders with an inheritance boundary.

Creating a namespace with ACLs

To create a namespace with ACLs, include an access object when calling Create namespace:

{
  "namespace_id": "team-files",
  "access": {
    "kind": "acl",
    "principal_scope": "acme",
    "root_grants": {
      "user_123": ["admin"]
    }
  }
}

This creates a namespace with user_123 as an administrator. principal_scope identifies the application layer identity system that issued the IDs.

Remember to include the required Loonfs-Actor header when creating the namespace.

Making requests for a user

Applications must add these headers alongside the bearer token when making file requests for a user:

Loonfs-Actor: user_123
Loonfs-Principal-Scope: acme
Loonfs-Principals: user_123,team_design

How to interpret this example: “The request is from user_123, who also belongs to team_design. Use the grants for both IDs when checking access.”

Loonfs-Actor records who made a change. Loonfs-Principals determines the permissions used for the request. The subject ID defaults to the actor ID; use Loonfs-Subject when the request acts for a different user. Principal IDs must be separated with commas (no spaces).

Changing a folder’s permissions

For example, to let the design team edit an existing /design folder, POST a commit with this operation:

{
  "kind": "update_access",
  "path": "/design",
  "boundary": false,
  "grants": {
    "team_design": ["read", "history", "write", "create", "remove"]
  }
}

update_access replaces the item’s direct grants, so include any existing grants you want to keep. Setting boundary: false ensures grants from parent folders still apply.

To avoid overwriting another permission change, include expected_inode_id and expected_access_revision_no from the item’s current entry.

A few useful details

• Reading a folder’s children can reveal the names of children that the user cannot open. Reading those files still requires permission on each file.
• Moving a file can change its inherited permissions. Moves that grant new access require permission to share that access.
• Snapshot and revision reads use the user’s current permissions. An old snapshot does not restore permissions that were removed.
• Deleting a folder checks remove on its parent, even if the folder contains restricted subfolders.