Understanding Permission Reasons

👑

Owner of path

The user owns the datasite or is in the ownership path

~/SyftBox/ └── datasites/ └── alice@example.com/ OWNER ├── syft.pub.yaml ├── public/ │ └── research.csv All permissions └── private/ └── notes.txt All permissions

Example: Alice automatically has admin access to all files in her datasite alice@example.com/ because she is the owner.

This reason appears when:

The file is within the user's own datasite directory
The directory name matches the user's email address
No explicit permissions are needed - ownership grants full control

🎯

Explicitly granted [permission] in [path]

Direct permission grant in a YAML file

~/SyftBox/datasites/alice@example.com/ ├── syft.pub.yaml ← Contains rules ├── research/ │ ├── data.csv bob: read │ └── analysis.py carol: write └── public/ └── results.pdf

# In ~/SyftBox/datasites/alice@example.com/syft.pub.yaml
rules:
  - pattern: 'research/data.csv'
    access:
      read:
        - 'bob@example.com'
  - pattern: 'research/analysis.py'
    access:
      write:
        - 'carol@example.com'

Example: Bob sees "Explicitly granted read in /alice@example.com/syft.pub.yaml" when accessing data.csv

🔍

Pattern '[pattern]' matched

File matches a glob pattern in permission rules

~/SyftBox/datasites/alice@example.com/ ├── syft.pub.yaml ├── data/ │ ├── experiment1.csv ✓ Matches *.csv │ ├── experiment2.csv ✓ Matches *.csv │ └── notes.txt └── code/ ├── main.py ✓ Matches **/*.py └── utils/ └── helper.py ✓ Matches **/*.py

rules:
  - pattern: '*.csv'    # Matches CSV files in root
    access:
      read:
        - 'data-team@example.com'
  - pattern: '**/*.py'  # Matches Python files anywhere
    access:
      write:
        - 'dev-team@example.com'

Common patterns:

* - Matches any characters (except /)
** - Matches any characters (including /)
*.csv - All CSV files in current directory
**/*.csv - All CSV files in any subdirectory
data/* - Everything in the data folder
**/* - Everything recursively

🔗

Included via [higher permission] permission in [path]

Permission inherited from a higher access level

Bob has write permission on project/* Write automatically includes: read, create project/ ├── README.md ✓ write ✓ read (inherited) └── data.csv ✓ write ✓ read (inherited)

rules:
  - pattern: 'project/*'
    access:
      write:  # Write includes read automatically
        - 'bob@example.com'

Example: Bob has write permission on project files. He automatically gets read access with the reason "Included via write permission in /alice@example.com/syft.pub.yaml"

💡 Remember the hierarchy

Admin access includes Write, Create, and Read. Write access includes Create and Read. Create access includes Read.

📍

Nearest-node: Inherited from parent directory

No specific rule found, using closest parent's permissions

research/ ├── syft.pub.yaml ← Nearest permission file ├── 2024/ │ └── january/ │ └── results.csv ↑ Inherits from research/ └── 2023/ └── old-data.csv ↑ Inherits from research/

# In ~/SyftBox/datasites/alice@example.com/research/syft.pub.yaml
rules:
  - pattern: '**/*'  # Applies to all subdirectories
    access:
      read:
        - 'research-team@example.com'

Example: Files in 2024/january/ inherit permissions from research/syft.pub.yaml because there's no closer YAML file defining permissions.

🌍

Public access (*)

File is accessible to everyone

alice@example.com/ ├── public/ │ ├── dataset.csv 🌍 Everyone can read │ └── README.md 🌍 Everyone can read └── guestbook.txt 🌍 Everyone can write

rules:
  - pattern: 'public/*'
    access:
      read:
        - '*'  # Asterisk means everyone
  - pattern: 'guestbook.txt'
    access:
      write:
        - '*'  # Anyone can write

⚠️ Security Note

Use public access (*) carefully. It grants access to anyone with a SyftBox account.

✏️

Manually granted [permission] permission

Permission added through the UI or API

This reason appears when:

Using the share button in the syft-perm web interface
Calling file.grant_read_access("user@example.com") in Python
Using the permission API endpoints directly

Example: After clicking "Share" and adding bob@example.com with read access, Bob sees "Manually granted read permission"

🚫

Permission Denied Reasons

Why a user doesn't have access

When a permission check returns granted: false, you might see:

"No matching rules found" - No YAML rules grant this permission
"User not in access list" - Rules exist but don't include this user
"Pattern 'X' matched" - A pattern matched but didn't grant the requested permission level

# User bob@example.com has read but wants write access
rules:
  - pattern: 'data.csv'
    access:
      read:
        - 'bob@example.com'
      write:
        - 'alice@example.com'  # Bob not included

⚡

Special Cases

Other reasons you might encounter

YAML File Locations

syft-perm searches for syft.pub.yaml files in this order:

Same directory as the file
Parent directories (moving up)
Datasite root directory

For file: research/2024/data.csv syft-perm searches in this order: alice@example.com/ ├── syft.pub.yaml 3️⃣ Last resort └── research/ ├── syft.pub.yaml 2️⃣ Parent directory └── 2024/ ├── syft.pub.yaml 1️⃣ Same directory (used first) └── data.csv

Multiple Rules

When multiple rules match a file:

All matching rules are combined
Permissions are additive (never subtractive)
Most specific pattern takes precedence for conflicting rules

💡

Pro Tips

Best practices for understanding permissions

Use explain_permissions()

file = syft_perm.open("data.csv")
explanation = file.explain_permissions("bob@example.com")
print(explanation)

Check the permission table in Jupyter

file = syft_perm.open("research/")
file  # Shows interactive permission viewer

Look for the YAML file path in reasons
The reason often includes the exact YAML file location, helping you find where to make changes.
Remember inheritance
If you see "Included via write permission", the user has write access somewhere that automatically grants read.