Permissions and Roles

Access control and permission management in TheCompanyApp.

Permission Levels

TheCompanyApp uses two-layer permission model:

1. CloudKit Level: Owner vs Participant, Read vs Write

2. App Level: Fine-grained permissions via AccessControl entity

CloudKit-Level Permissions

Owner

Granted by: Creating the company

Permissions:

• Full read/write access to all company data

• Add/remove participants to CKShare

• Configure share permissions

• Delete company (stops sharing)

Cannot be revoked: Ownership is permanent (unless company deleted).

Participant

Granted by: Accepting CKShare

Permissions (configurable by owner):

• Read-Only: View all data, cannot edit

• Read-Write: View and edit all data

Set by Owner:

// Read-only participant
share.publicPermission = .readOnly

// Read-write participant
share.publicPermission = .readWrite

try await container.save(share)

Checking Participant Permission:

func canEditCloudKitShare(_ company: Companies) async -> Bool {
    let shares = try? await container.fetchShares(matching: [company.objectID])
    guard let share = shares?[company.objectID] else { return false }
    
    return share.publicPermission == .readWrite || share.currentUserParticipant?.permission == .readWrite
}

App-Level Permissions (AccessControl)

Purpose: Fine-grained control beyond CloudKit's read/write.

AccessControl Entity

Attributes:

companyID: UUID            // Company this applies to
userName: String           // Email/username of user
isAdmin: Bool              // Admin flag (owner-like permissions)

// Inventory permissions
canViewInventory: Bool
canEditInventory: Bool
canDeleteInventory: Bool

// Orders permissions
canViewOrders: Bool
canEditOrders: Bool
canDeleteOrders: Bool
canApproveOrders: Bool

// Dispatch permissions
canViewDispatch: Bool
canEditDispatch: Bool
canDeleteDispatch: Bool

// Tasks permissions
canViewTasks: Bool
canEditTasks: Bool
canDeleteTasks: Bool

// Contacts permissions
canViewContacts: Bool
canEditContacts: Bool

// Settings permissions
canManageUsers: Bool       // Add/remove AccessControl
canViewSettings: Bool
canEditSettings: Bool

Creating AccessControl

Owner grants permissions to participant:

func grantPermissions(to userName: String, for company: Companies) {
    let access = AccessControl(context: viewContext)
    access.companyID = company.companyID
    access.userName = userName
    access.isAdmin = false
    
    // Grant specific permissions
    access.canViewInventory = true
    access.canEditInventory = false  // View-only for inventory
    access.canViewOrders = true
    access.canEditOrders = true      // Can edit orders
    
    try viewContext.save()
}

Result: User can view inventory but not edit, can view and edit orders.

Checking Permissions

Permission Helper:

extension AccessControl {
    static func hasPermission(
        _ permission: PermissionType,
        for company: Companies,
        user: String,
        in context: NSManagedObjectContext
    ) -> Bool {
        // Owners have all permissions
        if company.ownerName == user {
            return true
        }
        
        // Fetch AccessControl
        let request: NSFetchRequest<AccessControl> = AccessControl.fetchRequest()
        request.predicate = NSPredicate(
            format: "companyID == %@ AND userName == %@",
            company.companyID as CVarArg,
            user
        )
        request.fetchLimit = 1
        
        guard let access = try? context.fetch(request).first else {
            return false // No access record = no permission
        }
        
        // Admins have all permissions
        if access.isAdmin == true {
            return true
        }
        
        // Check specific permission
        switch permission {
        case .viewInventory:
            return access.canViewInventory
        case .editInventory:
            return access.canEditInventory
        case .viewOrders:
            return access.canViewOrders
        case .editOrders:
            return access.canEditOrders
        // ... other cases
        default:
            return false
        }
    }
}

enum PermissionType {
    case viewInventory, editInventory, deleteInventory
    case viewOrders, editOrders, deleteOrders, approveOrders
    case viewDispatch, editDispatch, deleteDispatch
    case viewTasks, editTasks, deleteTasks
    case viewContacts, editContacts
    case manageUsers, viewSettings, editSettings
}

UI Enforcement

Disable buttons for unauthorized actions:

struct InventoryDetailView: View {
    @ObservedObject var item: InventoryItem
    let company: Companies
    let currentUser: String
    
    @Environment(\.managedObjectContext) private var viewContext
    
    var canEdit: Bool {
        AccessControl.hasPermission(.editInventory, for: company, user: currentUser, in: viewContext)
    }
    
    var body: some View {
        VStack {
            Text(item.itemName)
            
            Button("Edit") {
                // Edit action
            }
            .disabled(!canEdit)
        }
    }
}

Result: "Edit" button disabled if user lacks permission.

Backend Enforcement

Validate before save:

func updateInventoryItem(_ item: InventoryItem, newQty: Int, user: String, company: Companies) throws {
    // Check permission
    guard AccessControl.hasPermission(.editInventory, for: company, user: user, in: viewContext) else {
        throw PermissionError.unauthorized
    }
    
    // Perform update
    item.itemQty = Int64(newQty)
    item.updatedAt = Date()
    item.updatedBy = user
    
    try viewContext.save()
}

Result: Save blocked if user lacks permission.

Role Presets

Convenience: Create common role configurations.

enum Role {
    case viewer       // Read-only
    case editor       // Read + Edit
    case manager      // Read + Edit + Delete
    case admin        // All permissions
}

func applyRole(_ role: Role, to access: AccessControl) {
    switch role {
    case .viewer:
        access.canViewInventory = true
        access.canViewOrders = true
        access.canViewDispatch = true
        access.canViewTasks = true
        access.canViewContacts = true
        // All edit/delete permissions = false (default)
        
    case .editor:
        access.canViewInventory = true
        access.canEditInventory = true
        access.canViewOrders = true
        access.canEditOrders = true
        access.canViewDispatch = true
        access.canEditDispatch = true
        access.canViewTasks = true
        access.canEditTasks = true
        access.canViewContacts = true
        access.canEditContacts = true
        
    case .manager:
        applyRole(.editor, to: access)
        access.canDeleteInventory = true
        access.canDeleteOrders = true
        access.canDeleteDispatch = true
        access.canDeleteTasks = true
        access.canApproveOrders = true
        
    case .admin:
        access.isAdmin = true
        // Admins have all permissions (checked dynamically)
    }
}

Usage:

let access = AccessControl(context: viewContext)
access.companyID = company.companyID
access.userName = "[email protected]"
applyRole(.editor, to: access)
try viewContext.save()

Permission Sync

AccessControl is company-scoped: Syncs via CloudKit like other entities.

Owner creates AccessControl:

1. Owner's device saves AccessControl → Private Store

2. CloudKit exports to Private Database

3. CKShare enlistment (if company shared)

4. CloudKit syncs to Shared Database

5. Participant's device imports → Shared Store

6. Participant sees updated permissions

Timing: Permissions propagate in ~5-60 seconds.

Revoking Access

Remove Participant from CKShare:

func removeParticipant(_ participant: CKShare.Participant, from share: CKShare) async {
    share.removeParticipant(participant)
    try await container.save(share)
}

Delete AccessControl:

func revokeAccess(for userName: String, company: Companies) {
    let request: NSFetchRequest<AccessControl> = AccessControl.fetchRequest()
    request.predicate = NSPredicate(
        format: "companyID == %@ AND userName == %@",
        company.companyID as CVarArg,
        userName
    )
    
    if let access = try? viewContext.fetch(request).first {
        viewContext.delete(access)
        try? viewContext.save()
    }
}

Best Practice: Remove from CKShare first (revokes CloudKit access), then delete AccessControl.

Auditing Permission Changes

Log permission grants/revokes:

func logPermissionChange(action: String, user: String, company: Companies) {
    let log = AuditLog(context: viewContext)
    log.action = action // "granted_editor_role", "revoked_access"
    log.userName = user
    log.companyID = company.companyID
    log.timestamp = Date()
    try? viewContext.save()
}

View audit trail in Settings → Access Control → History.

---

Related: AccessControl Guide, Ownership Rules, Security Model