Skip to main content
syft-permissions is the core permission engine for SyftBox, providing an ACL (Access Control List) tree-based system for managing file and folder permissions on datasites.

​
Installation

pip install syft-permissions
For most use cases, you should use syft-perm instead, which provides a user-friendly API on top of this package.

​
When to Use

Use syft-permissions when you need to:
  • Build custom permission systems on top of the ACL engine
  • Implement low-level permission checks
  • Create permission rules and rulesets programmatically
  • Extend the SyftBox permission system
For day-to-day permission management, use syft-perm instead.

​
Core Concepts

​
ACL Service

The ACLService is the core engine that processes permission requests against rulesets.

​
Access Levels

  • READ: View file contents
  • CREATE: Read + create new files in folders
  • WRITE: Read + Create + modify existing files
  • ADMIN: Read + Create + Write + manage permissions

​
RuleSet

A RuleSet is a collection of rules stored in syftperm.yaml files that define who can access what.

​
API Reference

​
Main Exports

from syft_permissions import (
    ACLService,            # Core permission engine
    ACLRequest,            # Permission request object
    AccessLevel,           # Enum: READ, CREATE, WRITE, ADMIN
    User,                  # User representation
    RuleSet,               # Collection of permission rules
    Rule,                  # Individual permission rule
    Access,                # Access specification
    PERMISSION_FILE_NAME,  # "syftperm.yaml"
)

​
Basic Usage

​
Creating a Permission Service

from syft_permissions import ACLService, RuleSet
from pathlib import Path

# Initialize the ACL service
service = ACLService(root_path=Path("/path/to/datasite"))

​
Making Permission Requests

from syft_permissions import ACLRequest, AccessLevel, User

# Create a permission request
request = ACLRequest(
    user=User(email="[email protected]"),
    path=Path("/path/to/file.csv"),
    access_level=AccessLevel.READ
)

# Check if access is granted
result = service.check_access(request)
if result.granted:
    print("Access granted!")
else:
    print(f"Access denied: {result.reason}")

​
Creating RuleSets

from syft_permissions import RuleSet, Rule, Access, AccessLevel

# Create a ruleset
ruleset = RuleSet(
    rules=[
        Rule(
            pattern="**/*.csv",
            access=Access(
                read=["[email protected]"],
                write=["[email protected]"],
                admin=["[email protected]"]
            )
        ),
        Rule(
            pattern="public/**",
            access=Access(
                read=["*"],  # Everyone can read
                write=["[email protected]"]
            )
        )
    ]
)

# Save to syftperm.yaml
ruleset_path = Path("/path/to/folder") / PERMISSION_FILE_NAME
ruleset.save(ruleset_path)

​
Working with Access Levels

from syft_permissions import AccessLevel

# Access levels in hierarchy (each includes all lower levels)
print(AccessLevel.READ)    # Lowest level
print(AccessLevel.CREATE)  # Includes READ
print(AccessLevel.WRITE)   # Includes READ + CREATE
print(AccessLevel.ADMIN)   # Highest level, includes all

# Check access level hierarchy
if AccessLevel.WRITE >= AccessLevel.READ:
    print("Write access includes read permissions")

​
Permission File Format

The permission system uses syftperm.yaml files: 
rules:
  - pattern: "**/*.csv"
    access:
      read:
        - [email protected]
        - [email protected]
      write:
        - [email protected]
  
  - pattern: "public/**"
    access:
      read:
        - "*"  # Everyone
      create:
        - [email protected]
      write:
        - [email protected]

​
Pattern Matching

The system uses glob patterns for matching paths:
  • **/*.csv - All CSV files in any subdirectory
  • public/** - Everything in the public folder
  • *.json - All JSON files in current directory
  • data/*/results.csv - results.csv in any subdirectory of data

​
Advanced Usage

​
Custom Permission Logic

from syft_permissions import ACLService, RuleSet

class CustomACLService(ACLService):
    def check_access(self, request: ACLRequest) -> ACLResult:
        # Add custom logic before checking
        if request.user.email.endswith("@trusted-domain.com"):
            # Grant automatic access to trusted domain
            return ACLResult(granted=True)
        
        # Fall back to standard ACL checking
        return super().check_access(request)

​
Dependencies

  • pydantic>=2.11.7 - Data validation and models
  • pyyaml>=6.0 - YAML file parsing
  • wcmatch>=10.0 - Advanced glob pattern matching
  • syft-perm - User-friendly permission API (recommended for most users)

​
Documentation

For detailed documentation, see the permission user docs.

Build docs developers (and LLMs) love

Get started for freeTalk to us