Create User Password

Detailed guide to creating and managing user passwords in TheCompanyApp.

What is UserPass?

UserPass is TheCompanyApp's company-level authentication system. It provides:

• Secondary Authentication: Beyond iCloud sign-in

• Multi-User Support: Multiple users in shared companies have their own credentials

• Access Control: Combined with AccessControl for permission enforcement

• Privacy: Credentials stored only in private iCloud database

Why Passwords Are Required

For Company Owners

• Protect company data on your device

• Authenticate when accessing sensitive operations

• Enable access auditing (future feature)

For Team Members

• Each team member maintains individual credentials

• Credentials are not shared via CloudKit sharing

• Each user creates their own UserPass locally

Security Model

iCloud Account (Primary Auth)
    ↓
Device with TheCompanyApp
    ↓
UserPass (Secondary Auth per Company)
    ↓
Company Data Access

Creating UserPass: First Time

During Company Creation

After creating a new company, you're automatically prompted:

Screen: CreatePassWordCView.swift

Fields:

1. Username

   • Required

   • Unique per company (not validated globally)

   • Used for login on all your devices

   • Cannot be changed after creation

2. Password

   • Required

   • Minimum 6 characters (12+ recommended)

   • Not validated for complexity (use strong password)

   • Stored securely in private iCloud

3. Confirm Password

   • Required

   • Must match Password field

   • Prevents typos

4. Email Address

   • Optional

   • Used for future features (password recovery, notifications)

   • Not currently validated

5. Profile Image

   • Optional

   • Tap camera icon to capture or select image

   • Used in team member displays

   • Automatically optimized for storage

6. Super User Flag

   • Automatically set to true for company owners

   • Grants elevated permissions

   • Cannot be modified by user

Create Button: Tap to save credentials.

What Happens Internally

When you tap "Create":

1. Validation

   guard !userName.isEmpty,
         !password.isEmpty,
         password == confirmPassword else {
       // Show error
       return
   }

2. UserPass Entity Creation

   let userPass = UserPass(context: viewContext)
   userPass.userID = UUID()
   userPass.companyID = company.companyID
   userPass.userName = userName
   userPass.password = password  // Plain text (consider encryption in production)
   userPass.emailAddress = email
   userPass.isSuperUser = true  // For owners
   userPass.timestamp = Date()
   userPass.companyName = company.name
   
   // Relationship
   userPass.companies = company

3. Save to Core Data

   try viewContext.save()

4. CloudKit Sync

   • UserPass syncs to Private Database only

   • Never shared via CKShare

   • Available on all your devices

5. Navigation

   • Returns to company list or dashboard

   • Company is now fully set up

Creating UserPass: Joining a Shared Company

When you accept a company share invitation, you must create your own credentials:

Flow

1. Accept Share (via share URL)

2. Company data syncs to your Shared Store

3. App detects missing UserPass for this company

4. Login Screen appears with "Create Account" option

5. Tap "Create Account"

6. Fill in UserPass form (same as above)

7. Credentials saved to your Private Store (not shared)

Key Difference

• Shared company data is in Shared Store

• Your UserPass is in Private Store

• Other team members cannot see your credentials

Managing Existing UserPass

Viewing UserPass

To view your credentials for a company:

1. Settings tab → User Management

2. Select the company

3. View current username (password is hidden)

Changing Password

Current Implementation: Password changes are not implemented in UI.

Workaround:

1. Delete existing UserPass

2. Create new one with updated password

Planned Enhancement: Password change flow with confirmation.

Changing Username

Current Limitation: Usernames cannot be changed after creation.

Reason: Username may be referenced in audit logs and access control.

Workaround: Create new company and migrate data.

Deleting UserPass

Warning: Deleting UserPass logs you out of that company.

To delete:

1. Settings → User Management

2. Select company

3. Tap "Delete Credentials"

4. Confirm deletion

Effect:

• You're logged out immediately

• Re-access requires creating new UserPass

• Company data remains intact (if shared)

UserPass Storage and Sync

Where UserPass Is Stored

Local:

• Core Data: TheCompanyApp.sqlite (Private Store)

• Encrypted by iOS FileVault (device encryption)

iCloud:

• CloudKit Private Database

• Zone: com.apple.coredata.cloudkit.zone

• Record type: CD_UserPass

Not Stored:

• ❌ Shared Store

• ❌ CloudKit Shared Database

• ❌ Any third-party server

Multi-Device Sync

Your UserPass credentials automatically sync to all your devices:

Example:

1. Create company on iPhone

2. Create UserPass on iPhone

3. Company syncs to iPad via Private Database

4. UserPass syncs to iPad via Private Database

5. On iPad, you can log in with same credentials

Sync Time: Usually 1-5 seconds, up to 1 minute on slow networks.

What Others See

When you join a shared company:

• Others see: Your display name, profile image (from AccessControl)

• Others don't see: Your username, password, email (UserPass is private)

Security Considerations

Password Strength

Current Implementation: No enforcement.

Recommendations:

• Minimum 12 characters

• Mix of uppercase, lowercase, numbers, symbols

• Unique per company

• Use a password manager

Password Storage

Current Implementation: Plain text in Core Data.

Security Layers:

• iOS device encryption

• iCloud encryption in transit (TLS)

• iCloud encryption at rest

• Biometric unlock (device level)

Planned Enhancement: Hash passwords using bcrypt or Argon2.

Password Recovery

Current Implementation: No password recovery.

If You Forget Password:

• Cannot recover (no server to reset)

• Must delete UserPass and create new one

• No data loss (only re-authentication needed)

Planned Enhancement: Security questions or email recovery.

Login with UserPass

See Login Flow for detailed authentication process.

Summary:

1. Select company from list

2. Enter username and password

3. Credentials validated against stored UserPass

4. On success, access granted to company data

Common Questions

Do I need UserPass for each company?

Yes. Each company requires a separate UserPass for access control.

Can I use the same username for multiple companies?

Yes. Usernames are scoped to individual companies, not global.

Do invited team members share my password?

No. Each user creates their own unique credentials. Passwords are never shared.

What if I lose my password?

Currently, no recovery option. Delete UserPass and create new one. Consider using a password manager.

Can I see other team members' passwords?

No. UserPass is private to each user and never syncs to shared databases.

Is my password encrypted?

Device is encrypted by iOS. Password is plain text in Core Data (enhancement planned).

Can I import passwords from another source?

No bulk import available. Passwords must be created individually per company.

Technical Reference

Entity Schema

UserPass (TheCompanyApp.xcdatamodel)

<entity name="UserPass">
    <attribute name="companyID" attributeType="UUID"/>
    <attribute name="companyName" attributeType="String"/>
    <attribute name="emailAddress" attributeType="String"/>
    <attribute name="image" attributeType="Binary"/>
    <attribute name="isSuperUser" attributeType="Boolean"/>
    <attribute name="password" attributeType="String"/>
    <attribute name="timestamp" attributeType="Date"/>
    <attribute name="userID" attributeType="UUID"/>
    <attribute name="userName" attributeType="String"/>
    <relationship name="companies" 
                 destinationEntity="Companies" 
                 inverseName="userPasses"/>
</entity>

Configuration: Not in "Shared" configuration (private only).

Creating UserPass Programmatically

func createUserPass(
    for company: Companies,
    userName: String,
    password: String,
    email: String? = nil,
    context: NSManagedObjectContext
) -> UserPass {
    let userPass = UserPass(context: context)
    userPass.userID = UUID()
    userPass.companyID = company.companyID
    userPass.userName = userName
    userPass.password = password
    userPass.emailAddress = email
    userPass.isSuperUser = true  // Or false for regular users
    userPass.timestamp = Date()
    userPass.companyName = company.name
    userPass.companies = company
    
    try? context.save()
    return userPass
}

Fetching UserPass

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

Validating Credentials

func validateLogin(
    companyID: UUID,
    userName: String,
    password: String,
    context: NSManagedObjectContext
) -> Bool {
    let request: NSFetchRequest<UserPass> = UserPass.fetchRequest()
    request.predicate = NSPredicate(
        format: "companyID == %@ AND userName == %@ AND password == %@",
        companyID as CVarArg,
        userName,
        password
    )
    request.fetchLimit = 1
    return (try? context.fetch(request).first) != nil
}

---

Next: Login Flow Related: Security Model, Credential Storage