Login Flow

Complete guide to authentication and login in TheCompanyApp.

Authentication Architecture

TheCompanyApp uses a two-tier authentication system:

Primary Auth: iCloud

• Device-level authentication via Apple ID

• Required for app installation and iCloud sync

• Handled by iOS automatically

Secondary Auth: UserPass

• Company-level authentication

• Required for accessing specific company data

• User-configurable credentials per company

Login Flow Overview

App Launch
    ↓
Check iCloud Status
    ↓
Load Companies List
    ↓
Select Company
    ↓
Check UserPass Exists
    ↓
Login Screen
    ↓
Validate Credentials
    ↓
Grant Access to Company Data

Step-by-Step Login Process

Step 1: App Launch

When you open TheCompanyApp:

1. Splash Screen displays briefly

2. App checks iCloud sign-in status

3. Core Data container initializes with dual stores

If Not Signed In to iCloud:

• Alert appears: "iCloud Required"

• Instructions to sign in via Settings app

• App cannot proceed without iCloud

If Signed In:

• Continue to company list loading

Step 2: Load Companies List

TheCompanyApp fetches all companies accessible to you:

Query Logic (ContentView.swift):

@FetchRequest(
    sortDescriptors: [NSSortDescriptor(keyPath: \Companies.timestamp, ascending: false)],
    animation: .default
)
var allCompanies: FetchedResults<Companies>

This retrieves:

• Private Store: Companies you own

• Shared Store: Companies shared with you

Companies List View:

• Displays all available companies

• Shows company name, logo, tier

• Indicates if you're owner or participant

Step 3: Company Selection

First Launch (No Companies):

• Welcome screen appears

• Options: "Create Company" or "Join with Share Link"

Returning User:

• Last selected company auto-selected (via @AppStorage("selectedCompanyID"))

• Or tap different company from list

Selecting a Company:

1. Tap company row in list

2. App stores selection in AppStorage

3. Proceeds to login check

Step 4: UserPass Check

For the selected company, app checks:

func fetchUserPass(for companyID: UUID) -> UserPass? {
    let request: NSFetchRequest<UserPass> = UserPass.fetchRequest()
    request.predicate = NSPredicate(format: "companyID == %@", companyID as CVarArg)
    request.fetchLimit = 1
    return try? viewContext.fetch(request).first
}

If UserPass Exists:

• Show login screen with username/password fields

• Pre-fill username from UserPass

If UserPass Missing (shared company, first access):

• Show "Create Account" option

• User creates their own UserPass (see Create User Password)

Step 5: Login Screen

Screen: LoginEdit.swift

UI Elements:

1. Company Name (header)

2. Username Field

   • Pre-filled if UserPass exists

   • Keyboard type: Default

3. Password Field

   • Secure text entry (dots)

   • Keyboard type: Default

4. Login Button

5. Create Account Button (if no UserPass)

User Actions:

1. Enter username (or verify pre-filled)

2. Enter password

3. Tap "Login"

Step 6: Credential Validation

When "Login" is tapped (LoginEdit.swift):

func login() {
    // Fetch UserPass for this company
    let request: NSFetchRequest<UserPass> = UserPass.fetchRequest()
    request.predicate = NSPredicate(
        format: "companyID == %@ AND userName == %@ AND password == %@",
        companyID as CVarArg,
        enteredUsername,
        enteredPassword
    )
    
    guard let userPass = try? viewContext.fetch(request).first else {
        // Invalid credentials
        showError = true
        errorMessage = "Invalid username or password"
        return
    }
    
    // Success
    isAuthenticated = true
    navigateToDashboard()
}

Validation:

• Username must match exactly (case-sensitive)

• Password must match exactly

• No lockout after failed attempts (currently)

On Success:

• isAuthenticated state set to true

• Navigation to MainTabView

On Failure:

• Error alert: "Invalid username or password"

• Username and password fields cleared (password only)

• User can retry

Step 7: Access Granted

Upon successful login:

1. Set Company Context

   • @AppStorage("selectedCompanyID") = companyID

   • All views now filter by selected company

2. Load Company Data

   • Fetch AccessControl for permissions

   • Load company details

   • Initialize NotificationManager

3. Navigate to Dashboard

   • MainTabView appears

   • Default tab: Dashboard

   • Bottom tab bar visible

4. Background Sync

   • CloudKit starts syncing any pending changes

   • Remote change notifications begin listening

Login Persistence

Session Management

TheCompanyApp uses persistent login:

• Once logged in, you stay authenticated

• No re-login required on app restart

• Session tied to @AppStorage("selectedCompanyID")

How It Works:

@AppStorage("selectedCompanyID") var selectedCompanyIDString: String = ""

var body: some View {
    if selectedCompanyIDString.isEmpty {
        // Show company selection
        CompanyListView()
    } else {
        // Show main app
        MainTabView()
    }
}

If selectedCompanyID is set, app assumes you're logged in and loads the dashboard.

Logout

To logout (change company):

Method 1: Select Different Company

1. Tap company name in header

2. Select different company from list

3. selectedCompanyIDString updates

4. App reloads with new company context

Method 2: Logout Button (if implemented):

1. Settings → Logout

2. Clears selectedCompanyID

3. Returns to company selection screen

Note: CurrentLY no explicit "Logout" button. Changing companies effectively logs out of previous one.

Multi-Device Login

Automatic Sync

Your credentials sync via CloudKit Private Database:

Scenario:

1. Create company on iPhone

2. Create UserPass on iPhone

3. Open app on iPad (same Apple ID)

4. Companies list syncs automatically

5. UserPass syncs automatically

6. Login with same credentials on iPad

Sync Time: Typically 1-60 seconds depending on network.

Company Selection Per Device

Each device maintains its own selectedCompanyID:

• iPhone can be logged into "Company A"

• iPad can be logged into "Company B"

• Switching on one device doesn't affect others

Security Features

Failed Login Attempts

Current Implementation: No lockout or rate limiting.

Behavior:

• Unlimited login attempts

• No account lockout

• No CAPTCHA

Recommendation: Implement rate limiting (planned enhancement).

Session Expiry

Current Implementation: Sessions never expire.

Behavior:

• Once logged in, remain authenticated indefinitely

• No timeout after inactivity

• No forced re-authentication

Recommendation: Optional session timeout setting (planned enhancement).

Password Visibility

During login:

• Password field uses SecureField (dots)

• No "show password" toggle (currently)

• Copy/paste allowed

Biometric Auth

Current Status: Not implemented.

Planned Enhancement:

• Face ID / Touch ID support

• "Use Face ID to Login" setting

• Falls back to password if biometric fails

Troubleshooting Login Issues

"Invalid Username or Password"

Cause: Credentials don't match UserPass record.

Solutions:

1. Verify correct company selected

2. Check username spelling (case-sensitive)

3. Check password (case-sensitive, no spaces)

4. Try re-creating UserPass if forgotten

Company Not Appearing in List

Cause: CloudKit sync delay or sharing issue.

Solutions:

1. Pull down to refresh company list

2. Check internet connection

3. Verify iCloud is enabled

4. Wait 1-2 minutes for sync

5. Check share invitation email for correct link

"Cannot Access Company Data"

Cause: UserPass missing or AccessControl not found.

Solutions:

1. Create UserPass if prompted

2. Contact company owner to verify share status

3. Check AccessControl exists in Core Data

App Crashes on Login

Cause: Core Data fetch error or relationship issue.

Solutions:

1. Force quit and restart app

2. Check Console logs for error details

3. Reinstall app (data preserved in iCloud)

Technical Details

Authentication State Management

State Variables (ContentView.swift):

@AppStorage("selectedCompanyID") var selectedCompanyIDString: String = ""
@State private var isAuthenticated: Bool = false
@State private var currentCompany: Companies?
@State private var currentUserPass: UserPass?
@State private var currentAccessControl: AccessControl?

Company Resolution

extension NSManagedObjectContext {
    func resolveCompany(selectedCompanyIDString: String) -> Companies? {
        guard !selectedCompanyIDString.isEmpty,
              let uuid = UUID(uuidString: selectedCompanyIDString) else {
            return nil
        }
        
        let request: NSFetchRequest<Companies> = Companies.fetchRequest()
        request.fetchLimit = 1
        request.predicate = NSPredicate(format: "companyID == %@", uuid as CVarArg)
        
        return try? self.fetch(request).first
    }
}

Login Validation Logic

func validateAndLogin(username: String, password: String, companyID: UUID) -> Bool {
    let request: NSFetchRequest<UserPass> = UserPass.fetchRequest()
    request.predicate = NSPredicate(
        format: "companyID == %@ AND userName == %@ AND password == %@",
        companyID as CVarArg,
        username,
        password
    )
    request.fetchLimit = 1
    
    if let userPass = try? viewContext.fetch(request).first {
        // Store authenticated user
        currentUserPass = userPass
        
        // Load AccessControl
        loadAccessControl(for: userPass.userID!, companyID: companyID)
        
        return true
    }
    
    return false
}

---

Next: Company Switching Related: Create User Password, Security Model