FoldDB Permissions System

What is the Permissions System?

The FoldDB Permissions System provides field-level access control through a hybrid approach that combines trust-based relationships and explicit permission grants. This system integrates with the schema system to enforce granular access control at the field level.

Key Components

The Permissions System consists of three primary components that work together to provide secure, granular access control:

Component Description Primary Responsibilities
PermissionWrapper Interface layer between FoldDB and PermissionManager • Coordinates permission validation requests
• Handles schema validation and lookup
• Verifies field existence
• Enforces permission policies
• Reports detailed errors
PermissionManager Core permission validation engine • Validates permissions against policies
• Checks trust distance requirements
• Verifies explicit permissions
• Implements the permission check logic
PermissionsPolicy Defines access rules at field level • Specifies trust distance requirements
• Stores explicit permission grants
• Defines separate read/write policies
• Integrates with schema definitions

How the Permission System Works

Permission Check Flow

When FoldDB receives a request, it follows this validation sequence:

  1. FoldDB sends the request to PermissionWrapper
  2. PermissionWrapper verifies the schema exists
  3. PermissionWrapper checks the field exists in the schema
  4. PermissionWrapper forwards the request to PermissionManager
  5. PermissionManager checks trust distance requirements
  6. If trust check fails, PermissionManager checks explicit permissions
  7. Access is granted if either check passes
  8. PermissionWrapper returns the result with detailed error information if access is denied
flowchart LR
    FoldDB[FoldDB] --> |request| PW[PermissionWrapper]
    PW --> |verify schema| SC[SchemaCore]
    SC --> |schema| PW
    PW --> |validate| PM[PermissionManager]
    PM --> |check| PP[PermissionsPolicy]
    PP --> |result| PM
    PM --> |decision| PW
    PW --> |response| FoldDB

Component Architecture

The components interact in a hierarchical structure:

classDiagram
    class FoldDB {
        +checkPermission()
        +validateAccess()
    }
    class PermissionWrapper {
        -permissionManager: PermissionManager
        +check_query_field_permission()
        +check_mutation_field_permission()
    }
    class PermissionManager {
        +has_read_permission()
        +has_write_permission()
    }
    class PermissionsPolicy {
        +read_policy: TrustDistance
        +write_policy: TrustDistance
        +explicit_read_policy: Option<ExplicitCounts>
        +explicit_write_policy: Option<ExplicitCounts>
    }
    class TrustDistance {
        <<enumeration>>
        Distance(u32)
        NoRequirement
    }
    class ExplicitCounts {
        +counts_by_pub_key: HashMap<String, u8>
    }
    FoldDB --> PermissionWrapper
    PermissionWrapper --> PermissionManager
    PermissionManager --> PermissionsPolicy
    PermissionsPolicy --> TrustDistance
    PermissionsPolicy --> ExplicitCounts

Trust Distance Model

The Trust Distance Model determines access rights based on the relationship between users:

  • Trust Distance: A numerical value representing the relationship between users
    • Lower values indicate higher trust (0 is highest trust)
    • Higher values indicate lower trust
    • Special value NoRequirement indicates no trust distance restriction

Trust Distance Benefits

Lower trust distance provides two key benefits:

  1. Higher trust level - Indicates stronger trust relationship
  2. Broader access rights - Grants more permissions to data

Access Control Features

1. Hybrid Access Control

The system provides two complementary access control mechanisms:

  • Trust-based access - Uses trust distance to determine access rights
  • Explicit permissions - Grants access to specific public keys
  • Fallback mechanism - Checks explicit permissions if trust check fails

2. Field-level Permissions

The system provides granular control at the field level:

  • Each field in a schema has its own permission policy
  • Different read/write permissions can be set per field
  • Permission checks are performed at the field level

3. Schema Integration

The permission system integrates with the schema system:

  • Permissions are defined as part of the schema
  • Each field has its own permission policy
  • Schema operations include trust distance and public key

4. Authentication

The system uses secure authentication:

  • Public key based authentication
  • Trust distance validation
  • Permission verification

Implementation Details

Permission Validation Process

The system follows this sequence for each access request:

  1. Verify the schema exists
  2. Check the field exists in the schema
  3. Check trust distance requirements
  4. If trust check fails, check explicit permissions
  5. Grant access if either check passes
  6. Return detailed error information if access is denied

Read Permission Check

The read permission check follows this logic:

function has_read_permission(pub_key, permissions_policy, trust_distance):
    # Check trust distance first
    if permissions_policy.read_policy is NoRequirement:
        return true
    
    if permissions_policy.read_policy is Distance(required_distance):
        if trust_distance <= required_distance:
            return true
    
    # If trust distance check fails, check explicit permissions
    if permissions_policy.explicit_read_policy exists:
        if pub_key exists in permissions_policy.explicit_read_policy:
            return true
    
    # If both checks fail, deny access
    return false

Write Permission Check

The write permission check follows similar logic but typically has stricter requirements:

function has_write_permission(pub_key, permissions_policy, trust_distance):
    # Check trust distance first
    if permissions_policy.write_policy is NoRequirement:
        return true
    
    if permissions_policy.write_policy is Distance(required_distance):
        if trust_distance <= required_distance:
            return true
    
    # If trust distance check fails, check explicit permissions
    if permissions_policy.explicit_write_policy exists:
        if pub_key exists in permissions_policy.explicit_write_policy:
            return true
    
    # If both checks fail, deny access
    return false

Best Practices

Follow these best practices when working with the permission system:

  1. Set appropriate trust distance requirements for different fields
  2. Use explicit permissions for specific users who need access
  3. Set stricter requirements for write operations than read operations
  4. Use NoRequirement only for truly public fields
  5. Document permission requirements for each field
  6. Test permission configurations with different trust distances and public keys
← Schema Marketplace Atom & AtomRef System →