castle/docs/PERMISSIONS-SYSTEM.md

Castle Permissions System - Overview & Administration Guide

Date: November 10, 2025 Status: 📚 Documentation + 🔧 Improvement Recommendations

---

Executive Summary

Castle implements a granular, hierarchical permission system that controls who can access which accounts and perform what actions. The system supports permission inheritance, making it easy to grant access to entire account hierarchies with a single permission.

Key Features:

• ✅ Three permission levels: READ, SUBMIT_EXPENSE, MANAGE
• ✅ Hierarchical inheritance: Permission on parent → access to all children
• ✅ Expiration support: Time-limited permissions
• ✅ Caching: 1-minute TTL for performance
• ✅ Audit trail: Track who granted permissions and when

---

Permission Types

1. READ

Purpose: View account balances and transaction history

Capabilities:

• View account balance
• See transaction history for the account
• List sub-accounts (if hierarchical)

Use cases:

• Transparency for community members
• Auditors reviewing finances
• Users checking their own balances

Example:

# Grant read access to view food expenses
await create_account_permission(
    user_id="user123",
    account_id="expenses_food_account_id",
    permission_type=PermissionType.READ
)

2. SUBMIT_EXPENSE

Purpose: Submit expenses against an account

Capabilities:

• Submit new expense entries
• Create transactions that debit the account
• Automatically creates user receivable/payable entries

Use cases:

• Members submitting food expenses
• Workers logging accommodation costs
• Contributors recording service expenses

Example:

# Grant permission to submit food expenses
await create_account_permission(
    user_id="user123",
    account_id="expenses_food_account_id",
    permission_type=PermissionType.SUBMIT_EXPENSE
)

# User can now submit:
# Debit:  Expenses:Food:Groceries  100 EUR
# Credit: Liabilities:Payable:User-user123  100 EUR

3. MANAGE

Purpose: Administrative control over an account

Capabilities:

• Modify account settings
• Change account description/metadata
• Grant permissions to other users (delegated administration)
• Archive/close accounts

Use cases:

• Department heads managing their budgets
• Admins delegating permission management
• Account owners controlling access

Example:

# Grant full management rights to department head
await create_account_permission(
    user_id="dept_head",
    account_id="expenses_marketing_account_id",
    permission_type=PermissionType.MANAGE
)

---

Hierarchical Inheritance

How It Works

Permissions on parent accounts automatically apply to all child accounts.

Hierarchy Example:

Expenses:Food
├── Expenses:Food:Groceries
├── Expenses:Food:Restaurants
└── Expenses:Food:Cafeteria

Permission on Parent:

# Grant SUBMIT_EXPENSE on "Expenses:Food"
await create_account_permission(
    user_id="alice",
    account_id="expenses_food_id",
    permission_type=PermissionType.SUBMIT_EXPENSE
)

Result: Alice can now submit expenses to:

• ✅ Expenses:Food
• ✅ Expenses:Food:Groceries (inherited)
• ✅ Expenses:Food:Restaurants (inherited)
• ✅ Expenses:Food:Cafeteria (inherited)

Implementation

The get_user_permissions_with_inheritance() function checks for both direct and inherited permissions:

async def get_user_permissions_with_inheritance(
    user_id: str, account_name: str, permission_type: PermissionType
) -> list[tuple[AccountPermission, Optional[str]]]:
    """
    Returns: [(permission, parent_account_name or None)]

    Example:
        Checking permission on "Expenses:Food:Groceries"
        User has permission on "Expenses:Food"

        Returns: [(permission_obj, "Expenses:Food")]
    """
    user_permissions = await get_user_permissions(user_id, permission_type)

    applicable_permissions = []
    for perm in user_permissions:
        account = await get_account(perm.account_id)

        if account_name == account.name:
            # Direct permission
            applicable_permissions.append((perm, None))
        elif account_name.startswith(account.name + ":"):
            # Inherited from parent
            applicable_permissions.append((perm, account.name))

    return applicable_permissions

Benefits:

• Grant one permission → access to entire subtree
• Easier administration (fewer permissions to manage)
• Natural organizational structure
• Can still override with specific permissions on children

---

Permission Lifecycle

1. Granting Permission

Admin grants permission:

await create_account_permission(
    data=CreateAccountPermission(
        user_id="alice",
        account_id="expenses_food_id",
        permission_type=PermissionType.SUBMIT_EXPENSE,
        expires_at=None,  # No expiration
        notes="Food coordinator for Q1 2025"
    ),
    granted_by="admin_user_id"
)

Result:

• Permission stored in DB
• Cache invalidated for user
• Audit trail recorded (who, when)

2. Checking Permission

Before allowing expense submission:

# Check if user can submit expense to account
permissions = await get_user_permissions_with_inheritance(
    user_id="alice",
    account_name="Expenses:Food:Groceries",
    permission_type=PermissionType.SUBMIT_EXPENSE
)

if not permissions:
    raise HTTPException(403, "Permission denied")

# Permission found - allow operation

Performance: First check hits DB, subsequent checks hit cache (1min TTL)

3. Permission Expiration

Automatic expiration check:

# get_user_permissions() automatically filters expired permissions
SELECT * FROM account_permissions
WHERE user_id = :user_id
AND permission_type = :permission_type
AND (expires_at IS NULL OR expires_at > NOW())  ← Automatic filtering

Time-limited permission example:

await create_account_permission(
    data=CreateAccountPermission(
        user_id="contractor",
        account_id="expenses_temp_id",
        permission_type=PermissionType.SUBMIT_EXPENSE,
        expires_at=datetime(2025, 12, 31),  # Expires end of year
        notes="Temporary contractor access"
    ),
    granted_by="admin"
)

4. Revoking Permission

Manual revocation:

await delete_account_permission(permission_id="perm123")

Result:

• Permission deleted from DB
• Cache invalidated for user
• User immediately loses access (after cache TTL)

---

Caching Strategy

Cache Configuration

# Cache for permission lookups
permission_cache = Cache(default_ttl=60)  # 1 minute TTL

# Cache keys:
# - "permissions:user:{user_id}" → All permissions for user
# - "permissions:user:{user_id}:{permission_type}" → Filtered by type

Why 1 minute TTL?

• Permissions may change frequently (grant/revoke)
• Security-sensitive data needs to be fresh
• Balance between performance and accuracy

Cache Invalidation

On permission creation:

# Invalidate both general and type-specific caches
permission_cache._values.pop(f"permissions:user:{user_id}", None)
permission_cache._values.pop(f"permissions:user:{user_id}:{permission_type.value}", None)

On permission deletion:

# Get permission first to know which user's cache to clear
permission = await get_account_permission(permission_id)
await db.execute("DELETE FROM account_permissions WHERE id = :id", {"id": permission_id})

# Invalidate caches
permission_cache._values.pop(f"permissions:user:{permission.user_id}", None)
permission_cache._values.pop(f"permissions:user:{permission.user_id}:{permission.permission_type.value}", None)

Performance Impact:

• Cold cache: ~50ms (DB query)
• Warm cache: ~1ms (memory lookup)
• Reduction: 60-80% fewer DB queries

---

Administration Best Practices

1. Use Hierarchical Permissions

❌ Don't do this:

# Granting 10 separate permissions (hard to manage)
await create_account_permission(user, "Expenses:Food:Groceries", SUBMIT_EXPENSE)
await create_account_permission(user, "Expenses:Food:Restaurants", SUBMIT_EXPENSE)
await create_account_permission(user, "Expenses:Food:Cafeteria", SUBMIT_EXPENSE)
await create_account_permission(user, "Expenses:Food:Snacks", SUBMIT_EXPENSE)
# ... 6 more

✅ Do this instead:

# Single permission covers all children
await create_account_permission(user, "Expenses:Food", SUBMIT_EXPENSE)

Benefits:

• Fewer permissions to track
• Easier to revoke (one permission vs many)
• Automatically covers new sub-accounts
• Cleaner audit trail

2. Use Expiration for Temporary Access

❌ Don't do this:

# Grant permanent access to temp worker
await create_account_permission(user, account, SUBMIT_EXPENSE)
# ... then forget to revoke when they leave

✅ Do this instead:

# Auto-expiring permission
await create_account_permission(
    user,
    account,
    SUBMIT_EXPENSE,
    expires_at=contract_end_date,  # Automatic cleanup
    notes="Contractor until 2025-12-31"
)

Benefits:

• No manual cleanup needed
• Reduced security risk
• Self-documenting access period
• Admin can still revoke early if needed

3. Use Notes for Audit Trail

❌ Don't do this:

# No context
await create_account_permission(user, account, SUBMIT_EXPENSE)

✅ Do this instead:

# Clear documentation
await create_account_permission(
    user,
    account,
    SUBMIT_EXPENSE,
    notes="Food coordinator for Q1 2025 - approved in meeting 2025-01-05"
)

Benefits:

• Future admins understand why permission exists
• Audit trail for compliance
• Easier to review permissions
• Can reference approval process

4. Principle of Least Privilege

Start with READ, escalate only if needed:

# Initial access: READ only
await create_account_permission(user, account, PermissionType.READ)

# If user needs to submit expenses, upgrade:
await create_account_permission(user, account, PermissionType.SUBMIT_EXPENSE)

# Only grant MANAGE to trusted users:
await create_account_permission(dept_head, account, PermissionType.MANAGE)

Security principle: Grant minimum permissions needed for the task.

---

Current Implementation Strengths

✅ Well-designed features:

1. Hierarchical inheritance - Reduces admin burden
2. Type safety - Enum-based permission types prevent typos
3. Caching - Good performance without sacrificing security
4. Expiration support - Automatic cleanup of temporary access
5. Audit trail - Tracks who granted permissions and when
6. Foreign key constraints - Cannot grant permission on non-existent account

---

Improvement Opportunities

🔧 Opportunity 1: Permission Groups/Roles

Current limitation: Must grant permissions individually

Proposed enhancement:

# Define reusable permission groups
ROLE_FOOD_COORDINATOR = [
    (PermissionType.READ, "Expenses:Food"),
    (PermissionType.SUBMIT_EXPENSE, "Expenses:Food"),
    (PermissionType.MANAGE, "Expenses:Food:Groceries"),
]

# Grant entire role at once
await grant_role(user_id="alice", role=ROLE_FOOD_COORDINATOR)

Benefits:

• Standard permission sets
• Easier onboarding
• Consistent access patterns
• Bulk grant/revoke

Implementation effort: 1-2 days

---

🔧 Opportunity 2: Permission Templates

Current limitation: No way to clone permissions from one user to another

Proposed enhancement:

# Copy all permissions from one user to another
await copy_permissions(
    from_user="experienced_coordinator",
    to_user="new_coordinator",
    permission_types=[PermissionType.SUBMIT_EXPENSE],  # Optional filter
    notes="Copied from Alice - new food coordinator"
)

Benefits:

• Faster onboarding
• Consistency
• Reduces errors
• Preserves expiration patterns

Implementation effort: 1 day

---

🔧 Opportunity 3: Bulk Permission Management

Current limitation: One permission at a time

Proposed enhancement:

# Grant same permission to multiple users
await bulk_grant_permission(
    user_ids=["alice", "bob", "charlie"],
    account_id="expenses_food_id",
    permission_type=PermissionType.SUBMIT_EXPENSE,
    expires_at=datetime(2025, 12, 31),
    notes="Q4 food team"
)

# Revoke all permissions on an account
await revoke_all_permissions_on_account(account_id="old_project_id")

# Revoke all permissions for a user (offboarding)
await revoke_all_user_permissions(user_id="departed_user")

Benefits:

• Faster administration
• Consistent permission sets
• Easy offboarding
• Bulk operations for events/projects

Implementation effort: 2 days

---

🔧 Opportunity 4: Permission Analytics Dashboard

Current limitation: No visibility into permission usage

Proposed enhancement:

# Admin endpoint for permission analytics
@router.get("/api/v1/admin/permissions/analytics")
async def get_permission_analytics():
    return {
        "total_permissions": 150,
        "by_type": {
            "READ": 50,
            "SUBMIT_EXPENSE": 80,
            "MANAGE": 20
        },
        "expiring_soon": [
            {"user_id": "alice", "account": "Expenses:Food", "expires": "2025-11-15"},
            # ... more
        ],
        "most_permissioned_accounts": [
            {"account": "Expenses:Food", "permission_count": 25},
            # ... more
        ],
        "users_without_permissions": ["bob", "charlie"],  # Alert for review
        "orphaned_permissions": []  # Permissions on deleted accounts
    }

Benefits:

• Visibility into access patterns
• Proactive expiration management
• Security audit support
• Identify unused permissions

Implementation effort: 2-3 days

---

🔧 Opportunity 5: Permission Request Workflow

Current limitation: Users must ask admin manually to grant permissions

Proposed enhancement:

# User requests permission
await request_permission(
    user_id="alice",
    account_id="expenses_food_id",
    permission_type=PermissionType.SUBMIT_EXPENSE,
    justification="I'm the new food coordinator starting next week"
)

# Admin reviews and approves
pending = await get_pending_permission_requests()
await approve_permission_request(request_id="req123", admin_user_id="admin")

# Or deny with reason
await deny_permission_request(
    request_id="req456",
    admin_user_id="admin",
    reason="Please request via department head first"
)

Benefits:

• Self-service permission requests
• Audit trail for approvals
• Reduces admin manual work
• Transparent process

Implementation effort: 3-4 days

---

🔧 Opportunity 6: Permission Monitoring & Alerts

Current limitation: No alerts for security events

Proposed enhancement:

# Monitor and alert on permission changes
class PermissionMonitor:
    async def on_permission_granted(self, permission):
        # Alert if MANAGE permission granted
        if permission.permission_type == PermissionType.MANAGE:
            await send_admin_alert(
                f"MANAGE permission granted to {permission.user_id} on {account.name}"
            )

    async def on_permission_expired(self, permission):
        # Alert user their access is expiring
        await send_user_notification(
            user_id=permission.user_id,
            message=f"Your access to {account.name} expires in 7 days"
        )

    async def on_suspicious_activity(self, user_id, account_id):
        # Alert on unusual permission usage patterns
        if failed_permission_checks > 5:
            await send_admin_alert(
                f"User {user_id} attempted access to {account_id} 5 times (denied)"
            )

Benefits:

• Security monitoring
• Proactive expiration management
• Detect permission issues early
• Compliance support

Implementation effort: 2-3 days

---

Recommended Implementation Priority

Phase 1: Quick Wins (1 week)

1. Bulk Permission Management (2 days) - Immediate productivity boost
2. Permission Templates (1 day) - Easy onboarding
3. Permission Analytics (2 days) - Visibility and audit support

Total effort: 5 days Impact: High (reduces admin time by 50%)

Phase 2: Process Improvements (1 week)

4. Permission Request Workflow (3-4 days) - Self-service
5. Permission Groups/Roles (2 days) - Standardization

Total effort: 5-6 days Impact: Medium (better user experience)

Phase 3: Security & Compliance (1 week)

6. Permission Monitoring & Alerts (2-3 days) - Security
7. Audit log enhancements (2 days) - Compliance
8. Permission review workflow (2 days) - Periodic access review

Total effort: 6-7 days Impact: Medium (security & compliance)

---

API Reference

Grant Permission

POST /api/v1/permissions
{
    "user_id": "alice",
    "account_id": "acc123",
    "permission_type": "submit_expense",
    "expires_at": "2025-12-31T23:59:59",
    "notes": "Food coordinator Q4"
}

Get User Permissions

GET /api/v1/permissions/user/{user_id}
GET /api/v1/permissions/user/{user_id}?type=submit_expense

Get Account Permissions

GET /api/v1/permissions/account/{account_id}

Revoke Permission

DELETE /api/v1/permissions/{permission_id}

Check Permission (with inheritance)

GET /api/v1/permissions/check?user_id=alice&account=Expenses:Food:Groceries&type=submit_expense

---

Database Schema

CREATE TABLE account_permissions (
    id TEXT PRIMARY KEY,
    user_id TEXT NOT NULL,
    account_id TEXT NOT NULL,
    permission_type TEXT NOT NULL,
    granted_by TEXT NOT NULL,
    granted_at TIMESTAMP NOT NULL,
    expires_at TIMESTAMP,
    notes TEXT,

    FOREIGN KEY (account_id) REFERENCES castle_accounts (id)
);

CREATE INDEX idx_account_permissions_user_id ON account_permissions (user_id);
CREATE INDEX idx_account_permissions_account_id ON account_permissions (account_id);
CREATE INDEX idx_account_permissions_expires_at ON account_permissions (expires_at);

---

Security Considerations

1. Permission Escalation Prevention

Risk: User with MANAGE on child account tries to grant permissions on parent

Mitigation:

async def create_account_permission(data, granted_by):
    # Check granter has MANAGE permission on account (or parent)
    granter_permissions = await get_user_permissions_with_inheritance(
        granted_by, account.name, PermissionType.MANAGE
    )
    if not granter_permissions:
        raise HTTPException(403, "You don't have permission to grant access to this account")

2. Cache Timing Attacks

Risk: Stale cache shows old permissions after revocation

Mitigation:

• Conservative 1-minute TTL
• Explicit cache invalidation on writes
• Admin can force cache clear if needed

3. Expired Permission Cleanup

Current: Expired permissions filtered at query time but remain in DB

Improvement: Add background job to purge old permissions

async def cleanup_expired_permissions():
    """Run daily to remove expired permissions"""
    await db.execute(
        "DELETE FROM account_permissions WHERE expires_at < NOW() - INTERVAL '30 days'"
    )

---

Troubleshooting

Permission Denied Despite Valid Permission

Possible causes:

1. Cache not invalidated after grant
2. Permission expired
3. Checking wrong account name (case sensitive)
4. Account ID mismatch

Solution:

# Clear cache and re-check
permission_cache._values.clear()

# Verify permission exists
perms = await get_user_permissions(user_id)
logger.info(f"User {user_id} permissions: {perms}")

# Check with inheritance
inherited = await get_user_permissions_with_inheritance(user_id, account_name, perm_type)
logger.info(f"Inherited permissions: {inherited}")

Performance Issues

Symptom: Slow permission checks

Causes:

1. Cache not working
2. Too many permissions per user
3. Deep hierarchy causing many account lookups

Solution:

# Monitor cache hit rate
hits = len([v for v in permission_cache._values.values() if v is not None])
logger.info(f"Permission cache: {hits} entries")

# Optimize with account cache (implemented separately)
# Use account_cache to reduce DB queries for account lookups

---

Testing Permissions

Unit Tests

async def test_permission_inheritance():
    """Test that permission on parent grants access to child"""
    # Grant on parent
    await create_account_permission(
        user="alice",
        account="Expenses:Food",
        permission_type=PermissionType.SUBMIT_EXPENSE
    )

    # Check child access
    perms = await get_user_permissions_with_inheritance(
        "alice",
        "Expenses:Food:Groceries",
        PermissionType.SUBMIT_EXPENSE
    )

    assert len(perms) == 1
    assert perms[0][1] == "Expenses:Food"  # Inherited from parent

async def test_permission_expiration():
    """Test that expired permissions are filtered"""
    # Create expired permission
    await create_account_permission(
        user="bob",
        account="acc123",
        permission_type=PermissionType.READ,
        expires_at=datetime.now() - timedelta(days=1)  # Expired yesterday
    )

    # Should not be returned
    perms = await get_user_permissions("bob")
    assert len(perms) == 0

Integration Tests

async def test_expense_submission_with_permission():
    """Test full flow: grant permission → submit expense"""
    # 1. Grant permission
    await create_account_permission(user, account, PermissionType.SUBMIT_EXPENSE)

    # 2. Submit expense
    response = await api_create_expense_entry(ExpenseEntry(...))

    # 3. Verify success
    assert response.status_code == 200

async def test_expense_submission_without_permission():
    """Test that expense submission fails without permission"""
    # Try to submit without permission
    with pytest.raises(HTTPException) as exc:
        await api_create_expense_entry(ExpenseEntry(...))

    assert exc.value.status_code == 403

---

Summary

The Castle permissions system is well-designed with strong features:

• Hierarchical inheritance reduces admin burden
• Caching provides good performance
• Expiration and audit trail support compliance
• Type-safe enums prevent errors

Recommended next steps:

1. Implement bulk permission management (quick win)
2. Add permission analytics dashboard (visibility)
3. Consider permission request workflow (self-service)
4. Monitor cache performance and security events

The system is production-ready and scales well for small-to-medium deployments. For larger deployments (1000+ users), consider implementing the permission groups/roles feature for easier management.

---

Document Version: 1.0 Last Updated: November 10, 2025 Status: Complete + Improvement Recommendations