Skip to main content

Syft Permissions

Overview​

Syft Permissions allows you to control access to files and folders in your SyftBox. With these permissions, you can specify which users can read, create, update, or delete specific paths. You can also delegate permission management by inviting other users to set permissions for specific paths.

Permission Types​

Permissions are defined through syftperm.yaml files placed throughout your datasite's file structure. Each syftperm.yaml file defines access rules that apply to its directory and all subdirectories (unless overridden by another syftperm.yaml file further down the tree).

Syft uses four permission "bits" that can be combined:

  • read: Allows reading file contents
  • create: Allows creating new files at the specified path
  • write: Allows modifying existing files
  • admin: Allows changing permissions (editing syftperm.yaml files)

Creating a syftperm.yaml File​

Basic Format​

A syftperm.yaml file contains one or more permission rules:

- path: '**'
  permissions:
  - read
  - write
  - admin
  user: alice@example.org

- path: 'public/**'
  permissions:
  - read
  user: '*'

Rule Components​

Each rule consists of:

  • path: A glob pattern specifying which files/folders the rule applies to
  • permissions: One or more permission types to grant or deny
  • user: The email address of a specific user, or '*' for all users
  • type: Either allow (default) or disallow

Path Patterns​

The path parameter supports Unix-style glob patterns:

  • *: Matches all files in the current directory
  • *.txt: Matches all .txt files in the current directory
  • **: Matches all files in the current directory and all subdirectories
  • {useremail}/*.txt: Matches all .txt files in a user-specific folder

Note: Path patterns can only reference the current directory or subdirectories, not parent directories. The pattern syntax doesn't support [] or {} expressions, except for the special {useremail} placeholder.

Common Permission Scenarios​

Private Folder (Owner Access Only)​

- path: '**'
  permissions:
  - admin
  - read
  - write
  user: irina@openmined.org

Public Read-Only Folder​

- path: '**'
  permissions:
  - admin
  - read
  - write
  user: irina@openmined.org

- path: '**'
  permissions:
  - read
  user: '*'

Collaborator Folder (Shared Write Access)​

- path: '**'
  permissions:
  - admin
  - read
  - write
  user: irina@openmined.org

- path: '**'
  permissions:
  - read
  - write
  user: collaborator@example.org

How Permissions Are Resolved​

Permission rules are combined based on the following principles:

  1. Rule Precedence: Rules are sorted by file path depth and rule sequence
  2. Overriding: Later rules override earlier rules for the same paths and users
  3. Default State:
    • Datasite owners automatically have all permissions (cannot be overridden)
    • All other users have no permissions by default

Permission Dependencies​

Permissions are independent, so each needs to be granted independently. However, currently some permissions have dependencies to take note of:

  1. admin permission automatically grants all other permissions
  2. write and create permissions are only effective if read permission is also granted
  3. Datasite owners always have full permissions to all content