Cubby — Shared Homes

The archivist reviews the current state of affairs

Current Architecture

Data Models SwiftData @Model

• Home → has many StorageLocations (cascade delete)
• StorageLocation → belongs to Home, has parent/child locations (tree), has many InventoryItems
• InventoryItem → belongs to StorageLocation, has title, description, tags, emoji, photo filename

CloudKit Integration

• Uses SwiftData's built-in CloudKit sync via ModelConfiguration(cloudKitDatabase: .private(...))
• Backed by NSPersistentCloudKitContainer under the hood
• Syncs to the private database only — single-user sync across devices
• No CKSyncEngine usage — automatic SwiftData/CloudKit integration
• CloudSyncCoordinator polls CloudKit availability status; does NOT manage sync itself

Photos

• Stored locally in Documents/ItemPhotos/ as JPEG files
• Referenced by photoFileName on InventoryItem
• NOT synced via CloudKit — photos are device-local only
• This is already a problem for single-user multi-device sync

Entitlements

• CloudKit enabled: iCloud.com.barronroth.Cubby
• Push notifications (aps-environment: production)
• App Sandbox enabled

Architecture Options, Ranked

The chosen path forward

Recommended Approach

Core Data + NSPersistentCloudKitContainer Sharing

This is the only Apple-supported path for sharing structured data between iCloud accounts with automatic sync.

Key Concepts

Three CloudKit Database Scopes

1. Private — User's own data (current Cubby behavior)
2. Shared — Data shared with this user by others (received shares)
3. Public — App-wide data visible to all users (not relevant here)

CKShare

A CKShare is a CloudKit record that represents a sharing relationship. It lives in a shared zone in the owner's private database, contains participant info, has a url property for generating share links, and supports read-only or read-write permissions per participant.

How NSPersistentCloudKitContainer Sharing Works

1. Owner creates a CKShare for a Core Data object (the Home)
2. The container automatically creates a shared CloudKit zone for that object and its relationships
3. Owner sends the share URL to the participant
4. Participant opens the URL, triggering userDidAcceptCloudKitShareWith in the app
5. The container automatically mirrors shared records into the participant's shared persistent store
6. Both users see the same data; changes sync automatically

Architecture Design

You need two persistent store descriptions: one for the private CloudKit database (user's own data) and one for the shared CloudKit database (data shared by others).

Setting Up the Container

Swiftimport CoreData
import CloudKit

class PersistenceController {
    static let shared = PersistenceController()

    let container: NSPersistentCloudKitContainer

    // The store that maps to the private CloudKit database
    private var privatePersistentStore: NSPersistentStore?
    // The store that maps to the shared CloudKit database
    private var sharedPersistentStore: NSPersistentStore?

    init() {
        container = NSPersistentCloudKitContainer(name: "Cubby")

        // Private store
        guard let privateDescription = container.persistentStoreDescriptions.first else {
            fatalError("No store descriptions found")
        }
        privateDescription.url = Self.privateStoreURL
        privateDescription.cloudKitContainerOptions = NSPersistentCloudKitContainerOptions(
            containerIdentifier: "iCloud.com.barronroth.Cubby"
        )
        privateDescription.cloudKitContainerOptions?.databaseScope = .private

        // Shared store — separate SQLite file
        let sharedDescription = NSPersistentStoreDescription(url: Self.sharedStoreURL)
        sharedDescription.cloudKitContainerOptions = NSPersistentCloudKitContainerOptions(
            containerIdentifier: "iCloud.com.barronroth.Cubby"
        )
        sharedDescription.cloudKitContainerOptions?.databaseScope = .shared

        container.persistentStoreDescriptions = [privateDescription, sharedDescription]

        // Enable persistent history tracking (required)
        for description in container.persistentStoreDescriptions {
            description.setOption(true as NSNumber, forKey: NSPersistentHistoryTrackingKey)
            description.setOption(true as NSNumber,
                forKey: NSPersistentStoreRemoteChangeNotificationPostOptionKey)
        }

        container.loadPersistentStores { description, error in
            if let error { fatalError("Failed to load store: \(error)") }
        }

        // Assign store references
        for store in container.persistentStoreCoordinator.persistentStores {
            let scope = store.cloudKitContainerOptions?.databaseScope
            if scope == .private { privatePersistentStore = store }
            else if scope == .shared { sharedPersistentStore = store }
        }

        container.viewContext.automaticallyMergesChangesFromParent = true
        container.viewContext.mergePolicy = NSMergeByPropertyObjectTrumpMergePolicy
    }
}

Creating a Share

Swiftextension PersistenceController {
    func shareHome(
        _ home: Home,
        completion: @escaping (CKShare?, Error?) -> Void
    ) {
        guard let privatePersistentStore else { return }

        // Shares the Home AND all relationships (StorageLocations, Items)
        container.share(
            [home],
            to: nil, // nil = create new share
            completion: { objectIDs, share, container, error in
                if let error {
                    completion(nil, error)
                    return
                }
                share?[CKShare.SystemFieldKey.title] = home.name
                share?.publicPermission = .none
                self.container.persistCKSharesAndWait()
                completion(share, nil)
            }
        )
    }
}

Presenting the Share UI

Swiftstruct CloudSharingView: UIViewControllerRepresentable {
    let share: CKShare
    let container: NSPersistentCloudKitContainer

    func makeUIViewController(context: Context) -> UICloudSharingController {
        let controller = UICloudSharingController(
            share: share,
            container: CKContainer(identifier: "iCloud.com.barronroth.Cubby")
        )
        controller.delegate = context.coordinator
        controller.availablePermissions = [.allowReadWrite, .allowPrivate]
        return controller
    }
    // ... coordinator with UICloudSharingControllerDelegate
}

Accepting a Share

Swift@main
struct CubbyApp: App {
    let persistenceController = PersistenceController.shared

    var body: some Scene {
        WindowGroup {
            ContentView()
                .environment(\.managedObjectContext,
                    persistenceController.container.viewContext)
                .onOpenURL { url in
                    acceptShare(from: url)
                }
        }
    }

    private func acceptShare(from url: URL) {
        let ckContainer = CKContainer(identifier: "iCloud.com.barronroth.Cubby")
        CKContainer.default().fetchShareMetadata(with: url) { metadata, error in
            guard let metadata else { return }
            persistenceController.container.acceptShareInvitations(
                from: [metadata],
                into: persistenceController.sharedPersistentStore!
            ) { _, error in
                if let error { print("Failed to accept share: \(error)") }
            }
        }
    }
}

Querying Across Both Stores

Swift// Fetch all homes (both private and shared)
let request = NSFetchRequest<Home>(entityName: "Home")

// Only shared homes:
request.affectedStores = [sharedPersistentStore!]

// Only private homes:
request.affectedStores = [privatePersistentStore!]

// Is a specific object shared?
func isShared(_ object: NSManagedObject) -> Bool {
    guard let store = object.objectID.persistentStore else { return false }
    return store == sharedPersistentStore
}

// Determine edit permissions
func canEdit(_ home: Home) -> Bool {
    guard let share = share(for: home) else { return true }
    if share.currentUserParticipant?.role == .owner { return true }
    return share.currentUserParticipant?.permission == .readWrite
}

Alternative: Direct CloudKit

If you want to avoid Core Data entirely, you could use CKSyncEngine (iOS 17+) with shared zones. However:

• CKSyncEngine supports shared zones via CKSyncEngine.State.PendingZoneShare
• You'd need to manually map between SwiftData models and CKRecords
• You lose all automatic relationship handling that NSPersistentCloudKitContainer provides
• Apple's documentation on CKSyncEngine + sharing is sparse

Moving in — the user experience

User Flow Design

Sharing a Home (Owner)

1. Owner taps "Share" button on a Home's detail/settings screen
2. App creates a CKShare via NSPersistentCloudKitContainer.share(_:to:completion:)
3. System presents UICloudSharingController — Apple's standard share sheet
4. Owner chooses sharing method: iMessage, Mail, AirDrop, copy link
5. Owner sets permissions: Read Only or Read & Write
6. Share link is sent to the participant

Accepting a Share (Participant)

1. Participant taps the share link (e.g., in iMessage)
2. iOS opens the Cubby app (or App Store if not installed)
3. App handles the URL in onOpenURL / userDidAcceptCloudKitShareWith
4. acceptShareInvitations(from:into:) processes it
5. Shared home data syncs into participant's shared store
6. Home appears in the home list with a Shared badge

Managing a Share

• Owner can add/remove participants via UICloudSharingController
• Owner can change permissions per participant
• Owner can stop sharing entirely (removes from all participants)
• Participant can leave a share (removes it from their device)

Required Codebase Changes

1. Migration from SwiftData to Core Data Major

This is the biggest change:

• Create a .xcdatamodeld Core Data model matching current SwiftData models
• Replace @Model classes with NSManagedObject subclasses
• Replace ModelContainer / ModelContext with NSPersistentCloudKitContainer / NSManagedObjectContext
• Replace SwiftData @Query with @FetchRequest or NSFetchedResultsController

Model Mapping

2. Dual Persistent Store Setup

• Configure private + shared NSPersistentStoreDescriptions
• Set databaseScope on CloudKit container options
• Enable persistent history tracking on both stores

3. Share UI

• Add a "Share" button on Home detail/settings
• Wrap UICloudSharingController in UIViewControllerRepresentable
• Handle share URL acceptance in app lifecycle
• Show share status/participants in UI
• Add Shared badge on received homes

4. Permission-Aware UI

• Check canEdit() before allowing modifications
• Show read-only UI for participants without write permission
• Handle share revocation gracefully (home disappears)

5. Entitlements

Photo Sharing Strategy

Limitations & Gotchas

NSPersistentCloudKitContainer Quirks

1. Entire zone is shared, not individual records. When you share a Home, ALL records in that zone are shared. This is actually what you want.
2. Conflict resolution is last-writer-wins. No merge strategy for field-level conflicts. For a household inventory app, this is acceptable.
3. Shared store is read-only from the container's perspective. Write operations for shared data go through the same context, but under the hood they write to the owner's zone.
4. No real-time sync. Eventually consistent. Changes typically propagate in seconds to minutes.
5. CloudKit quotas. ~25 MB free per user. Large photo libraries could hit limits.
6. Offline behavior. Changes queue locally and sync on reconnect. Conflicts resolved by last-writer-wins.
7. Share acceptance requires the app. If not installed, share link goes to App Store. Participant must tap link again after install.
8. UICloudSharingController is UIKit. Needs a UIViewControllerRepresentable wrapper. Not SwiftUI-native.
9. Testing is painful. Two different iCloud accounts on two devices. Simulator support is limited.
10. Schema migration. Adding fields is easy (additive). Removing/changing types requires careful handling.

What You Lose by Moving to Core Data

• SwiftData's @Model macro convenience
• SwiftData's @Query property wrapper
• SwiftData's simpler ModelContainer setup
• SwiftData's automatic schema generation

What You Gain

• Full CloudKit sharing support
• Battle-tested persistence layer (Core Data is 20+ years old)
• More control over sync behavior
• Access to NSPersistentCloudKitContainer's sharing APIs

Migration Strategy

Given that Cubby is relatively early-stage and the model layer is simple (3 entities, straightforward relationships), the cleanest path is a full Core Data migration:

1. Create Core Data model (.xcdatamodeld) matching current SwiftData models
2. Build PersistenceController with dual private/shared stores
3. Create NSManagedObject subclasses (or use Xcode codegen)
4. Port views from @Query to @FetchRequest / @SectionedFetchRequest
5. Add sharing UI (share button, UICloudSharingController wrapper, share acceptance)
6. Add data migration for existing users (read SwiftData → write Core Data → delete SwiftData store)
7. Port photo storage to Core Data binary attribute with external storage
8. Test thoroughly with two iCloud accounts

Timeline Estimate

Sharing is caring — subscription mechanics

Subscription Sharing: How Participants Get Pro

Added 2026-02-16 — How does the owner's Pro subscription extend to participants in a shared home?

This is the most nuanced architectural decision in the sharing feature. Three viable approaches exist, each with distinct security/complexity tradeoffs.

Option A: RevenueCat Backend Verification

Owner's RevenueCat app_user_id is stored in the CloudKit Home metadata. Participant's app calls a lightweight Cloud Function, which checks the owner's entitlement via RC's REST API.

┌───────────────┐ ┌────────────────┐ ┌───────────────────┐ │ Owner App │────▶│ CloudKit │◀────│ Participant App │ │ (RC SDK) │ │ (Home data │ │ (RC SDK for │ │ │ │ + owner │ │ own purchases) │ └───────────────┘ │ RC user ID) │ └─────────┬─────────┘ └────────────────┘ │ "Is owner subscribed?" ▼ ┌────────────────────┐ │ Cloud Function │ │ (Firebase / CF) │ └─────────┬──────────┘ ▼ ┌────────────────────┐ │ RevenueCat │ │ REST API │ └────────────────────┘

Pros

• Server-side verification — can't be spoofed client-side
• RevenueCat handles all subscription lifecycle (renewals, cancellations, refunds, grace periods)
• Single Cloud Function (~50 lines), essentially free to run
• RC free tier covers up to $2.5k MTR

Cons

• Requires a server component (Cloud Function)
• RC REST API rate limit ~60 req/min per API key (fine for indie scale)
• Adds RevenueCat as a dependency

Edge Cases

• Cancellation: Entitlement stays active until period end (correct behavior)
• Refund: Entitlement revoked immediately
• Offline: Cache last-known status with TTL locally (4–12 hours)
• Owner changes RC account: Update CloudKit Home metadata on identity change
• Grace period (billing issues): RC still reports active during 6–16 day grace period

Security

Attack	Risk	Mitigation
Participant spoofs owner's RC ID	Medium	Validate requesting user is a participant of that Home
Owner shares RC ID for free Pro without home	Low	Only honor checks for users in the same CloudKit sharing group
Replay cached "active" after cancel	Low	Short TTL caches (1–4 hours)
Direct Cloud Function calls	Medium	Firebase Auth / App Check

---

Option B: CloudKit Metadata + JWS Verification (No Server)

Owner stores their StoreKit 2 signed transaction (JWS — Apple-signed JWT) in the shared CloudKit record. Participant verifies Apple's signature locally.

How It Works

1. Owner subscribes → gets Transaction.jwsRepresentation (signed by Apple)
2. Owner writes JWS + ownerUserRecordName to CloudKit shared record
3. Participant reads the record and:
   • Decodes the JWS (standard JWT — header.payload.signature)
   • Verifies signature against Apple's public keys (x5c chain in header)
   • Checks bundleId matches your app
   • Checks productId matches your Pro subscription
   • Checks expiresDate is in the future
   • Checks CKRecord.creatorUserRecordID matches the ownerUserRecordName field

Swift// Owner side — after purchase
func writeSubscriptionToCloudKit(transaction: Transaction) async {
    let record = // fetch or create subscription CKRecord in shared zone
    record["subscriptionJWS"] = transaction.jwsRepresentation
    record["productId"] = transaction.productID
    record["expiresDate"] = transaction.expirationDate
    // save to CloudKit
}

// Participant side — checking entitlement
func verifySharedSubscription(record: CKRecord) -> Bool {
    guard let jws = record["subscriptionJWS"] as? String else { return false }

    // 1. Parse JWT structure
    // 2. Verify x5c certificate chain roots to Apple
    // 3. Verify signature
    // 4. Check bundleId == your app
    // 5. Check productId is a Pro subscription
    // 6. Check expiresDate > now
    // 7. Check environment == "Production"
    return isValid
}

---

Spoofing Analysis: Can This Be Gamed?

🔴 Critical Finding: Fake Owner Attack

Without JWS verification, a plain boolean field in CloudKit is trivially spoofable. Anyone creates an iCloud account, writes subscriptionActive = true, shares the zone. No purchase needed. This is the #1 threat unique to the CloudKit sharing approach.

Attack Vector Analysis

Attack Vector	Typical User	Determined Attacker	Overall Risk
Fake owner account (write true, share zone)	Low–Med	Trivial	Critical
Local SQLite cache modification	Low	High	Medium-High
Jailbreak runtime hooks	Very Low	Very High	High (universal)
MITM CloudKit traffic	None	Very Low	Very Low
CloudKit API direct modification	Low	Medium	Medium

What JWS Verification Defeats

• ✅ Fake owner — can't produce a valid Apple-signed JWS for your bundle ID without purchasing
• ✅ Local cache modification — can't forge Apple's JWS signature
• ✅ API modification — same reason
• ❌ Jailbreak runtime hooks — attacker can hook verification code itself (true of ALL client-side checks)

How Other Apps Handle This

• Apple Family Sharing: Server-side entitlement checking. Not spoofable via CloudKit.
• Serious apps: Own server as the authority on subscription status
• RevenueCat users: Server-side receipt validation
• Small indie apps: Honor system (trust the CloudKit field)

No major app relies on CloudKit record fields alone for subscription verification.

---

Mitigations Deep Dive

Tier 1: JWS + Bundle ID + Owner Identity Binding No Server

Best practical approach without a server. Store the Apple-signed JWS in CloudKit, verify on the participant side. Bind to owner identity via CKRecord.creatorUserRecordID.

Tier 2: Lightweight Server Validation Strongest

Add a Cloud Function that validates via App Store Server API and returns a short-lived signed token. Owner stores this in CloudKit. Adds revocation checking and real-time validity.

Tier 3: Apple Family Sharing Limited

If the sharing model maps to Apple's Family concept (≤6 people, one payer), enable Family Sharing for the IAP. Zero custom code. But limited to Apple family groups — not roommates, friends, or nannies.

---

Option C: Apple Family Sharing Deprioritized

• Requires users to be in the same Apple Family group (max 6)
• Most households sharing Cubby (roommates, partners, nannies) are NOT on the same Apple Family plan
• Zero implementation complexity, but the UX requirement is a dealbreaker for most users

---

Subscription Sharing Recommendation

Approach	Security	Complexity	Server?	UX Friction
RevenueCat + Cloud Function	Strong	Medium	Yes (lightweight)	Low
CloudKit + JWS local verification	Good	Medium	No	Low
Apple Family Sharing	Strong	Low	No	High
Plain CloudKit boolean	Trivially spoofable	Low	No	Low

✅ Verdict for Cubby

Start with CloudKit + JWS (no server dependency, good security). If abuse appears later, upgrade to RevenueCat + Cloud Function. Skip Apple Family Sharing as the primary mechanism — too much user friction.

The verdict is in

Summary

Bottom line: Migrate to Core Data + NSPersistentCloudKitContainer with dual private/shared stores. It's the only Apple-supported path for CloudKit sharing with a local database, and it's mature enough for production use. The migration from SwiftData is the main cost, but Cubby's simple 3-entity model makes this manageable.

Implementation Checklist

• Set up RevenueCat with identified users (not anonymous)
• Store owner's Purchases.shared.appUserID in CloudKit Home CKRecord
• Create Cloud Function: owner RC ID → RC REST API → active/inactive
• Secure Cloud Function (Firebase App Check or Auth token)
• Participant app: on opening shared Home, call Cloud Function with owner's RC ID
• Cache result locally with TTL (4–12 hours suggested)
• Handle edge cases: owner changes account, refunds, offline mode
• Optional: Set up RC webhooks for faster lookups
• Test in sandbox with short subscription periods