@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/swift-security/references/keychain-sharing.md

@@ -1,496 +1,399 @@
-# Keychain Sharing: Access Groups, Extensions, and Cross-Device Sync
+# Keychain Sharing Across Apps and Extensions
 
-> Scope: Access-group design and entitlement correctness for sharing keychain items across app targets, extensions, and devices.
+Access groups are the one mechanism for letting several apps and extensions read the
+same Keychain items. Getting them right takes three things together: the exact Team ID
+prefix, an entitlement on every target that participates, and an explicit
+`kSecAttrAccessGroup` in the code.
 
-Keychain access groups are the sole mechanism for sharing credentials between apps and extensions on Apple platforms. Correct configuration requires exact Team ID prefixes, per-target entitlements, and explicit `kSecAttrAccessGroup` usage in code  -  three requirements that most AI-generated code gets wrong. This reference covers access group mechanics, the two entitlement systems, correct and incorrect Swift patterns, macOS-specific requirements, iCloud sync, platform edge cases, and debugging strategies. All guidance reflects current behavior through iOS 18, macOS Sequoia 15, and the 2025-2026 developer landscape.
-
-**Authoritative sources:** Apple "Sharing Access to Keychain Items Among a Collection of Apps" documentation, TN3137 "On Mac Keychain APIs and Implementations," Apple Platform Security Guide (iCloud Keychain syncing), Quinn "The Eskimo!" DTS forum posts "SecItem: Fundamentals" and "SecItem: Pitfalls and Best Practices" (updated May 2025), Configuring Keychain Sharing documentation.
-
----
+Behaviour described here holds through iOS 18 and macOS Sequoia 15. It is based on
+Apple's "Sharing Access to Keychain Items Among a Collection of Apps", TN3137 (On Mac
+keychain APIs and implementations), the iCloud Keychain chapter of the Platform
+Security Guide, "Configuring Keychain Sharing", and guidance from Apple DTS engineers
+on the developer forums (updated May 2025).
 
 ## Contents
 
-- [How Access Groups Work](#how-access-groups-work)
-- [Two Entitlements, Two Formats, Different Purposes](#two-entitlements-two-formats-different-purposes)
-  - [Keychain Sharing (`keychain-access-groups`)](#keychain-sharing-keychain-access-groups)
-  - [App Groups (`com.apple.security.application-groups`)](#app-groups-comapplesecurityapplication-groups)
-  - [Comparison Table](#comparison-table)
-- [Code Patterns: Correct and Incorrect](#code-patterns-correct-and-incorrect)
-  - [Storing an item with an explicit access group](#storing-an-item-with-an-explicit-access-group)
-  - [Access group without Team ID prefix (most common AI mistake)](#access-group-without-team-id-prefix-most-common-ai-mistake)
-  - [App extension reading a shared keychain item](#app-extension-reading-a-shared-keychain-item)
-  - [Extension that fails because it lacks the entitlement](#extension-that-fails-because-it-lacks-the-entitlement)
-  - [iCloud Keychain sync with `kSecAttrSynchronizable`](#icloud-keychain-sync-with-ksecattrsynchronizable)
-  - [Assuming items sync by default](#assuming-items-sync-by-default)
-- [Cross-Target Entitlements Setup](#cross-target-entitlements-setup)
-  - [Xcode Configuration Steps](#xcode-configuration-steps)
-  - [Required Entitlements Matrix](#required-entitlements-matrix)
-- [The macOS Keychain Split](#the-macos-keychain-split)
-  - [Cross-platform macOS support with `kSecUseDataProtectionKeychain`](#cross-platform-macos-support-with-ksecusedataprotectionkeychain)
-- [Migrating Items Between Access Groups](#migrating-items-between-access-groups)
-- [Lifecycle Edge Cases](#lifecycle-edge-cases)
-  - [Keychain items persist after app uninstall](#keychain-items-persist-after-app-uninstall)
-  - [App transfers between teams break keychain access](#app-transfers-between-teams-break-keychain-access)
-  - [Cross-developer sharing is impossible via access groups](#cross-developer-sharing-is-impossible-via-access-groups)
-- [Platform-Specific Patterns](#platform-specific-patterns)
-  - [watchOS](#watchos)
-  - [Widget Extensions (WidgetKit)](#widget-extensions-widgetkit)
-- [Build and Distribution Considerations](#build-and-distribution-considerations)
-- [Debugging When Keychain Sharing Breaks](#debugging-when-keychain-sharing-breaks)
-  - [Essential Error Codes](#essential-error-codes)
-  - [Debugging Checklist](#debugging-checklist)
-  - [Test Matrix](#test-matrix)
-- [Security Threat Model Notes](#security-threat-model-notes)
-- [What Changed in 2024-2026](#what-changed-in-20242026)
-- [Cross-References](#cross-references)
-- [Conclusion](#conclusion)
-- [Summary Checklist](#summary-checklist)
-
-## How Access Groups Work
-
-Every app belongs to one or more **access groups**  -  string identifiers that tag which processes can read and write specific keychain items. An app can belong to many groups, but each keychain item belongs to **exactly one**. The `securityd` daemon enforces access by checking the calling process's entitlements against the item's group at runtime.
-
-The system constructs a virtual array of access groups for each app by concatenating three sources **in this exact order**:
-
-1. **Keychain access groups** from the `keychain-access-groups` entitlement
-2. **Application identifier**  -  automatically generated as `TeamID.BundleID` (e.g., `SKMME9E2Y8.com.example.MyApp`)
-3. **App groups** from the `com.apple.security.application-groups` entitlement (iOS 8+)
-
-**The first item in this concatenated list becomes the default access group.** When `SecItemAdd` is called without specifying `kSecAttrAccessGroup`, the item lands in that default group. When `SecItemCopyMatching` is called without specifying a group, the search spans **all** groups the app belongs to. This ordering means a keychain access group can be the default (it appears first), but an app group can never be the default because the application identifier always precedes it.
-
-Example for an app with one keychain group and one app group:
-
-```text
-[SKMME9E2Y8.com.example.SharedItems,    ← keychain access group (default)
- SKMME9E2Y8.com.example.MyApp,          ← application identifier (automatic)
- group.com.example.AppSuite]             ← app group
-```
-
-**Sharing is restricted to a single development team.** Apps from different developer teams cannot share keychain items through access groups. The Team ID prefix on every group identifier, enforced through code-signed provisioning profiles, prevents cross-team access. The only way different developers' apps can share credentials is through iCloud Keychain + Associated Domains (password autofill based on web domain ownership), which is an entirely different mechanism.
-
----
-
-## Two Entitlements, Two Formats, Different Purposes
+- [How access groups work](#how-access-groups-work)
+- [Two entitlements with two formats](#two-entitlements-with-two-formats)
+- [Code](#code)
+- [Setting up every target](#setting-up-every-target)
+- [macOS has two keychains](#macos-has-two-keychains)
+- [Moving an item to another group](#moving-an-item-to-another-group)
+- [Lifecycle surprises](#lifecycle-surprises)
+- [Platform notes](#platform-notes)
+- [Signing and distribution](#signing-and-distribution)
+- [When sharing breaks](#when-sharing-breaks)
+- [Threat model](#threat-model)
+- [2024 to 2026](#2024-to-2026)
+- [Related](#related)
+- [Checklist](#checklist)
 
-The most common developer mistake is **confusing Keychain Sharing with App Groups**. These are separate capabilities with different entitlement keys, different identifier formats, and different scopes.
+## How access groups work
 
-### Keychain Sharing (`keychain-access-groups`)
+An app can belong to many access groups. Every item belongs to exactly one.
+`securityd` compares the calling process's entitlements with the item's group on every
+call.
 
-This entitlement exists solely for sharing keychain items between apps. Identifiers are prefixed with the Team ID:
+The system builds the app's list of groups in this order:
 
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
-  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-    <key>keychain-access-groups</key>
-    <array>
-        <string>$(AppIdentifierPrefix)com.example.SharedItems</string>
-    </array>
-</dict>
-</plist>
-```
+1. Entries of the `keychain-access-groups` entitlement.
+2. The application identifier, `TeamID.BundleID`, added automatically.
+3. Entries of `com.apple.security.application-groups` (iOS 8 and later).
 
-The `$(AppIdentifierPrefix)` build variable resolves at signing time to the Team ID followed by a dot (e.g., `SKMME9E2Y8.`). In code, the fully resolved string is required  -  `"SKMME9E2Y8.com.example.SharedItems"`  -  not just `"com.example.SharedItems"`.
+The first entry in that list is the default: `SecItemAdd` without
+`kSecAttrAccessGroup` puts the item there. `SecItemCopyMatching` without a group
+searches all of the app's groups.
 
-### App Groups (`com.apple.security.application-groups`)
+Because the application identifier always comes before app groups, a keychain access
+group can be the default but an app group never can.
 
-App Groups share more than keychain items: shared file containers, `UserDefaults(suiteName:)`, and IPC. The identifier uses a `group.` prefix with **no Team ID**:
+Sharing is limited to one development team; the signed provisioning profile enforces
+the Team ID prefix. Between different teams the only route is iCloud Keychain
+together with Associated Domains, which serves password autofill rather than shared
+app data.
 
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
-  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-    <key>com.apple.security.application-groups</key>
-    <array>
-        <string>group.com.example.AppSuite</string>
-    </array>
-</dict>
-</plist>
-```
+## Two entitlements with two formats
 
-Since iOS 8, app group names double as keychain access groups  -  `"group.com.example.AppSuite"` can be used as the `kSecAttrAccessGroup` value. However, App Groups appear last in the access group array and **can never be the default group for new items**. A critical macOS caveat: **app groups cannot be used as keychain access groups on macOS**  -  this is an iOS/iPadOS-only feature.
+Mixing up Keychain Sharing and App Groups is the most common mistake.
 
-### Comparison Table
+| | Keychain Sharing | App Groups |
+| --- | --- | --- |
+| Entitlement | `keychain-access-groups` | `com.apple.security.application-groups` |
+| Value in entitlements | `$(AppIdentifierPrefix)com.example.vault` | `group.com.example.suite` |
+| Resolved value | `A1B2C3D4E5.com.example.vault` | `group.com.example.suite` (no Team ID) |
+| Shares | Keychain items | Containers, `UserDefaults(suiteName:)`, IPC, and on iOS also Keychain items |
 
-| Aspect                     | Keychain Sharing                           | App Groups                                                   |
-| -------------------------- | ------------------------------------------ | ------------------------------------------------------------ |
-| **Entitlement key**        | `keychain-access-groups`                   | `com.apple.security.application-groups`                      |
-| **Format**                 | `$(AppIdentifierPrefix)com.example.shared` | `group.com.example.shared`                                   |
-| **Team ID prefix**         | Yes (automatic via build variable)         | No (`group.` prefix instead)                                 |
-| **Shares**                 | Keychain items only                        | Containers, UserDefaults, IPC, and keychain items (iOS only) |
-| **Can be default group**   | Yes (if first in array)                    | No                                                           |
-| **macOS keychain sharing** | Yes (with data protection keychain)        | No                                                           |
+`$(AppIdentifierPrefix)` is replaced with `TEAMID.` at signing time. Code never sees
+that substitution, so it must use the full resolved string.
 
-Both entitlements can be used simultaneously. If only keychain sharing is needed, use Keychain Sharing. If App Groups are already in use for shared UserDefaults or file containers, they can piggyback for keychain sharing on iOS  -  but always specify `kSecAttrAccessGroup` explicitly.
+Since iOS 8 an app group name can be used as a `kSecAttrAccessGroup` value, though
+never as the default. On macOS app groups cannot act as keychain access groups; that
+is iOS and iPadOS only. On macOS, Keychain Sharing groups work only in the data
+protection keychain.
 
----
+Both entitlements can coexist. If you only need shared credentials, add Keychain
+Sharing. If the apps already share an App Group, it can carry Keychain items on iOS as
+long as every call names it explicitly.
 
-## Code Patterns: Correct and Incorrect
+## Code
 
-### Storing an item with an explicit access group
+Writing to a shared group:
 
 ```swift
 import Security
 
-let teamID = "SKMME9E2Y8"
-let accessGroup = "\(teamID).com.example.SharedItems"
-
-let password = "s3cretT0ken".data(using: .utf8)!
-let addQuery: [String: Any] = [
-    kSecClass as String:            kSecClassGenericPassword,
-    kSecAttrService as String:      "com.example.authService",
-    kSecAttrAccount as String:      "user@example.com",
-    kSecAttrAccessGroup as String:  accessGroup,
-    kSecAttrAccessible as String:   kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly,
-    kSecValueData as String:        password
-]
-
-let status = SecItemAdd(addQuery as CFDictionary, nil)
-guard status == errSecSuccess else {
-    print("Keychain add failed: \(status)")  // -34018 = missing entitlement
-    return
+enum SharedVault {
+    static let group = "A1B2C3D4E5.com.example.vault"
+    static let service = "com.example.vault.session"
 }
-```
-
-The Team ID must be the **literal 10-character string** from the Apple Developer account, not a build variable  -  `$(AppIdentifierPrefix)` only works in entitlements plists, not in Swift code.
 
-### Access group without Team ID prefix (most common AI mistake)
-
-```swift
-// ❌ WRONG  -  Missing Team ID prefix
-let accessGroup = "com.example.SharedItems"
-
-let addQuery: [String: Any] = [
-    kSecClass as String:            kSecClassGenericPassword,
-    kSecAttrService as String:      "com.example.authService",
-    kSecAttrAccount as String:      "user@example.com",
-    kSecAttrAccessGroup as String:  accessGroup,  // Will fail!
-    kSecValueData as String:        password
-]
-// Returns errSecMissingEntitlement (-34018) on iOS 13+
-// Returns errSecItemNotFound (-25300) on older versions
-```
-
-Xcode's Keychain Sharing UI shows `com.example.SharedItems` without the prefix, which misleads developers and AI generators alike. **In code, the full `TEAMID.com.example.SharedItems` string is always required.**
-
-### App extension reading a shared keychain item
-
-The extension target must have its own Keychain Sharing capability with the same group:
-
-```swift
-// In a widget extension, share extension, or other app extension
-let teamID = "SKMME9E2Y8"
-let accessGroup = "\(teamID).com.example.SharedItems"
-
-let readQuery: [String: Any] = [
-    kSecClass as String:            kSecClassGenericPassword,
-    kSecAttrService as String:      "com.example.authService",
-    kSecAttrAccount as String:      "user@example.com",
-    kSecAttrAccessGroup as String:  accessGroup,
-    kSecReturnData as String:       true
-]
-
-var result: AnyObject?
-let status = SecItemCopyMatching(readQuery as CFDictionary, &result)
-if status == errSecSuccess, let data = result as? Data {
-    let token = String(data: data, encoding: .utf8)
-    // Use the shared token
+func publishSessionToken(_ token: Data) -> OSStatus {
+    let identity: [String: Any] = [
+        kSecClass as String: kSecClassGenericPassword,
+        kSecAttrAccessGroup as String: SharedVault.group,
+        kSecAttrService as String: SharedVault.service,
+        kSecAttrAccount as String: "active-user"
+    ]
+    var insert = identity
+    insert[kSecValueData as String] = token
+    insert[kSecAttrAccessible as String] = kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
+
+    let added = SecItemAdd(insert as CFDictionary, nil)
+    guard added == errSecDuplicateItem else { return added }   // -34018: entitlement missing
+    let changes: [String: Any] = [kSecValueData as String: token]
+    return SecItemUpdate(identity as CFDictionary, changes as CFDictionary)
 }
 ```
 
-### Extension that fails because it lacks the entitlement
+The Team ID in code is the literal ten-character string. `$(AppIdentifierPrefix)`
+works only inside the entitlements plist.
 
 ```swift
-// ❌ This code is syntactically correct, but the extension target is
-// missing the Keychain Sharing capability in Xcode → Signing & Capabilities.
-// The main app has it, but extensions are SEPARATE executable targets.
-// Result: errSecMissingEntitlement (-34018)
+// Broken: group without the Team ID prefix
+let wrongGroup = "com.example.vault"
 ```
 
-**Each executable target  -  main app, widget extension, share extension, notification extension  -  needs its own Keychain Sharing entitlement.** Frameworks do not have entitlements; only the targets linking them do. In Xcode: select the extension target → Signing & Capabilities → + Capability → Keychain Sharing → add the same group name.
+This fails with `errSecMissingEntitlement` (-34018) on iOS 13 and later, and with
+`errSecItemNotFound` (-25300) on earlier versions. Xcode's Keychain Sharing editor
+shows the name without its prefix, which is why this keeps happening.
 
-### iCloud Keychain sync with `kSecAttrSynchronizable`
+Reading it from an extension:
 
 ```swift
-let syncQuery: [String: Any] = [
-    kSecClass as String:                kSecClassGenericPassword,
-    kSecAttrService as String:          "com.example.authService",
-    kSecAttrAccount as String:          "user@example.com",
-    kSecAttrAccessGroup as String:      "\(teamID).com.example.SharedItems",
-    kSecAttrSynchronizable as String:   kCFBooleanTrue!,
-    kSecAttrAccessible as String:       kSecAttrAccessibleAfterFirstUnlock,
-    kSecValueData as String:            password
-]
-let status = SecItemAdd(syncQuery as CFDictionary, nil)
+func readSessionTokenInExtension() -> Data? {
+    let query: [String: Any] = [
+        kSecClass as String: kSecClassGenericPassword,
+        kSecAttrAccessGroup as String: SharedVault.group,
+        kSecAttrService as String: SharedVault.service,
+        kSecAttrAccount as String: "active-user",
+        kSecReturnData as String: true,
+        kSecMatchLimit as String: kSecMatchLimitOne
+    ]
+    var found: CFTypeRef?
+    guard SecItemCopyMatching(query as CFDictionary, &found) == errSecSuccess else { return nil }
+    return found as? Data
+}
 ```
 
-**Critical constraints:**
-
-- Synchronizable items **cannot** use `kSecAttrAccessible` values ending in `ThisDeviceOnly`  -  the item would never sync. Attempting this silently fails to sync across devices.
-- When querying for synchronizable items, include `kSecAttrSynchronizable: true` or `kSecAttrSynchronizableAny`  -  otherwise the search excludes them.
-- The user must have iCloud Keychain enabled and be signed into the same Apple ID on all target devices.
-- Synchronization is orthogonal to on-device sharing: an item can be both in a shared access group and synchronizable across devices.
+An extension that lacks its own Keychain Sharing capability gets -34018 here even
+when the host app has the capability. Every executable target (app, widget, share
+extension, notification service extension) needs the entitlement itself. Frameworks
+carry no entitlements; only the targets that link them do.
 
-```swift
-// ✅ Query that finds both sync and non-sync items
-let findQuery: [String: Any] = [
-    kSecClass as String:                kSecClassGenericPassword,
-    kSecAttrService as String:          "com.example.authService",
-    kSecAttrSynchronizable as String:   kSecAttrSynchronizableAny,
-    kSecReturnData as String:           true
-]
-```
+### iCloud sync
 
-### Assuming items sync by default
+Syncing is a separate, per-item opt-in:
 
 ```swift
-// ❌ WRONG  -  This item will NOT sync to iCloud Keychain.
-// kSecAttrSynchronizable defaults to false when omitted.
-let addQuery: [String: Any] = [
-    kSecClass as String:       kSecClassGenericPassword,
-    kSecAttrService as String: "com.example.authService",
-    kSecAttrAccount as String: "user@example.com",
-    kSecValueData as String:   password
-    // No kSecAttrSynchronizable → stays on this device only
-]
+func publishSyncedPreferenceKey(_ secret: Data) -> OSStatus {
+    let identity: [String: Any] = [
+        kSecClass as String: kSecClassGenericPassword,
+        kSecAttrAccessGroup as String: SharedVault.group,
+        kSecAttrService as String: "com.example.vault.sync",
+        kSecAttrAccount as String: "reader-settings-key",
+        kSecAttrSynchronizable as String: kCFBooleanTrue as Any
+    ]
+    var insert = identity
+    insert[kSecValueData as String] = secret
+    insert[kSecAttrAccessible as String] = kSecAttrAccessibleAfterFirstUnlock
+
+    let added = SecItemAdd(insert as CFDictionary, nil)
+    guard added == errSecDuplicateItem else { return added }
+    return SecItemUpdate(identity as CFDictionary,
+                         [kSecValueData as String: secret] as CFDictionary)
+}
 ```
 
-iCloud Keychain sync is **strictly opt-in per item**. Omitting `kSecAttrSynchronizable` or setting it to `false` means the item exists only on the current device. Synchronized items benefit from end-to-end encryption  -  Apple cannot decrypt the data.
-
----
-
-## Cross-Target Entitlements Setup
+Rules for synced items:
 
-Extensions are separate sandboxed executable targets that do **not** inherit capabilities from their containing app.
+- Apple documents that a synchronizable item may not use an accessibility value
+  ending in `ThisDeviceOnly`. `SecItemAdd` rejects the combination with `errSecParam`
+  (-50); nothing is stored and nothing syncs. Use `AfterFirstUnlock` or `WhenUnlocked`.
+- Every query, update and delete that should see synced items must include
+  `kSecAttrSynchronizable: true` or `kSecAttrSynchronizableAny`; without it, synced
+  items are excluded from the match.
+- Sync needs iCloud Keychain turned on and the same Apple Account on each device. It
+  is independent of which access group the item is in.
+- `kSecAttrSynchronizable` defaults to false. Nothing syncs unless you ask for it item
+  by item. Synced items are end-to-end encrypted; Apple cannot read them.
 
-### Xcode Configuration Steps
+## Setting up every target
 
-1. Select the main application target → Signing & Capabilities → + Capability → Keychain Sharing.
-2. Add the desired group identifier (e.g., `com.example.shared`). Xcode auto-prefixes with Team ID in the entitlements file.
-3. **Repeat for every extension target**  -  select the extension target, add Keychain Sharing, add the **exact same** group identifier.
-4. For App Groups: add the App Groups capability to each target and use the same `group.` identifier.
+Extensions do not inherit capabilities from the app that contains them.
 
-### Required Entitlements Matrix
+1. Select the app target, open Signing & Capabilities, click + Capability, add
+   Keychain Sharing and enter the group. Xcode applies the Team ID prefix.
+2. Do exactly the same for each extension target.
+3. If App Groups are used too, add the same `group.` identifier to each target.
 
-| Target                | `keychain-access-groups`    | `application-groups`         | Notes                                |
-| --------------------- | --------------------------- | ---------------------------- | ------------------------------------ |
-| **Main app**          | `TEAMID.com.example.shared` | `group.com.example.appsuite` | First entry defines default group    |
-| **Share extension**   | `TEAMID.com.example.shared` | `group.com.example.appsuite` | Must match exactly                   |
-| **Widget extension**  | `TEAMID.com.example.shared` | `group.com.example.appsuite` | Independent signing and provisioning |
-| **Notification ext.** | `TEAMID.com.example.shared` | `group.com.example.appsuite` | Same rules apply                     |
+| Target | keychain-access-groups | application-groups |
+| --- | --- | --- |
+| Main app | `A1B2C3D4E5.com.example.vault` (first entry, so the default) | `group.com.example.suite` |
+| Share extension | `A1B2C3D4E5.com.example.vault` | `group.com.example.suite` |
+| Widget extension | `A1B2C3D4E5.com.example.vault` | `group.com.example.suite` |
+| Notification extension | `A1B2C3D4E5.com.example.vault` | `group.com.example.suite` |
 
----
+Each target is signed with its own provisioning profile.
 
-## The macOS Keychain Split
+## macOS has two keychains
 
-macOS maintains **two completely separate keychain implementations**, and confusing them is a source of endless bugs. Per Apple's TN3137:
+- **File-based keychain.** The legacy implementation: `.keychain-db` files and
+  `SecAccess` ACLs. On macOS it is where `SecItem` calls go by default. It has no
+  iCloud Keychain, no biometrics, no Secure Enclave keys and no access groups.
+- **Data protection keychain.** The iOS implementation, on macOS since 10.9 through
+  iCloud Keychain. It has access groups, `SecAccessControl`, sync, Touch ID and
+  Secure Enclave keys. It is available only in a user login context, so `launchd`
+  daemons cannot use it.
 
-**File-based keychain**  -  the legacy system dating back to Mac OS X. Uses Access Control Lists (`SecAccess`), stores items in `.keychain-db` files, and is the default target for `SecItem` API calls on macOS. Does not support iCloud Keychain, biometrics, Secure Enclave keys, or access groups.
-
-**Data protection keychain**  -  originated on iOS and arrived on macOS via iCloud Keychain in 10.9. Uses keychain access groups + `SecAccessControl`, supports iCloud sync, Touch ID/Face ID, and Secure Enclave. Available only in user-login contexts  -  **`launchd` daemons cannot use it**.
-
-### Cross-platform macOS support with `kSecUseDataProtectionKeychain`
+On macOS `kSecAttrAccessGroup` is ignored without an error unless the call targets the
+data protection keychain:
 
 ```swift
-var query: [String: Any] = [
-    kSecClass as String:                        kSecClassGenericPassword,
-    kSecAttrService as String:                  "com.example.authService",
-    kSecAttrAccount as String:                  "user@example.com",
-    kSecAttrAccessGroup as String:              "\(teamID).com.example.SharedItems",
-    kSecUseDataProtectionKeychain as String:     true,
-    kSecValueData as String:                     password
+let macQuery: [String: Any] = [
+    kSecClass as String: kSecClassGenericPassword,
+    kSecAttrService as String: SharedVault.service,
+    kSecAttrAccessGroup as String: SharedVault.group,
+    kSecUseDataProtectionKeychain as String: true
 ]
-let status = SecItemAdd(query as CFDictionary, nil)
 ```
 
-On macOS, `kSecAttrAccessGroup` **is silently ignored** unless the data protection keychain is targeted. Setting `kSecUseDataProtectionKeychain` to `true` opts into iOS-style keychain behavior. On iOS, tvOS, and watchOS this key is ignored (those platforms always use data protection).
-
-Two ways to target the data protection keychain on macOS: set `kSecUseDataProtectionKeychain` to `true`, or set `kSecAttrSynchronizable` to `true` (which also enables iCloud sync). Mac Catalyst and iOS Apps on Mac use data protection exclusively  -  the flag is ignored there.
+Either `kSecUseDataProtectionKeychain: true` or `kSecAttrSynchronizable: true` routes
+a call there. Mac Catalyst apps and iOS apps running on a Mac always use it.
 
-| Platform/Runtime   | Default keychain  | Access groups supported | Required flag                         |
-| ------------------ | ----------------- | ----------------------- | ------------------------------------- |
-| **iOS/iPadOS**     | Data Protection   | Yes                     | None                                  |
-| **Mac Catalyst**   | Data Protection   | Yes                     | None                                  |
-| **macOS (AppKit)** | Legacy file-based | No (by default)         | `kSecUseDataProtectionKeychain: true` |
+| Platform | Default keychain | Access groups by default | Flag needed |
+| --- | --- | --- | --- |
+| iOS, iPadOS, Mac Catalyst | Data protection | Yes | No |
+| macOS (AppKit) | File-based | No | `kSecUseDataProtectionKeychain` |
 
-Apple's TN3137 states the file-based keychain is **"on the road to deprecation."** `SecKeychainCreate` was deprecated in the macOS 12 SDK. New code should target data protection exclusively, with the sole exception of `launchd` daemons that lack a user context.
+TN3137 describes the file-based keychain as on the road to deprecation;
+`SecKeychainCreate` is deprecated as of the macOS 12 SDK. Only `launchd` daemons with no
+user context should keep using it.
 
----
+## Moving an item to another group
 
-## Migrating Items Between Access Groups
-
-`kSecAttrAccessGroup` is **immutable** for an existing keychain item  -  it cannot be changed via `SecItemUpdate`. Migration requires a read-add-delete sequence:
-
-1. **Read**: Retrieve the complete item from its original access group via `SecItemCopyMatching`.
-2. **Add**: Call `SecItemAdd` with the new `kSecAttrAccessGroup`.
-3. **Delete**: Only after `SecItemAdd` returns `errSecSuccess`, delete the original item via `SecItemDelete`.
-
-If the add operation fails, the original item remains untouched, preventing data loss. This pattern is safe because it never deletes until the new copy is confirmed.
-
----
-
-## Lifecycle Edge Cases
-
-### Keychain items persist after app uninstall
-
-This behavior is undocumented but has been consistent since iOS's early days. Apple attempted to delete keychain items on app removal in iOS 10.3 beta but rolled it back before release due to compatibility issues. Quinn "The Eskimo!" has warned this behavior **could change without notice**. If shared keychain items exist between App A and App B, deleting App A leaves all shared items intact for App B. Even deleting all apps in a shared group does not remove orphaned items  -  only a factory reset clears them reliably.
-
-A common workaround for detecting fresh installs (since `UserDefaults` _are_ wiped on uninstall):
+`SecItemUpdate` cannot change `kSecAttrAccessGroup`. To move an item, read it with
+`SecItemCopyMatching`, add a copy in the new group, and delete the original only after
+that add returned `errSecSuccess`. If the add fails, the original is untouched.
 
 ```swift
-func clearKeychainOnFreshInstall() {
-    let hasLaunchedBefore = UserDefaults.standard.bool(forKey: "hasLaunchedBefore")
-    if !hasLaunchedBefore {
-        // Scope deletion to specific service/group to avoid nuking shared items
-        let query: [String: Any] = [
-            kSecClass as String: kSecClassGenericPassword,
-            kSecAttrService as String: "com.example.authService"
-        ]
-        SecItemDelete(query as CFDictionary)
-        UserDefaults.standard.set(true, forKey: "hasLaunchedBefore")
-    }
+func moveItem(account: String, from oldGroup: String, to newGroup: String) -> Bool {
+    let source: [String: Any] = [
+        kSecClass as String: kSecClassGenericPassword,
+        kSecAttrService as String: SharedVault.service,
+        kSecAttrAccount as String: account,
+        kSecAttrAccessGroup as String: oldGroup
+    ]
+    var lookup = source
+    lookup[kSecReturnData as String] = true
+    var value: CFTypeRef?
+    guard SecItemCopyMatching(lookup as CFDictionary, &value) == errSecSuccess,
+          let secret = value as? Data else { return false }
+
+    var target = source
+    target[kSecAttrAccessGroup as String] = newGroup
+    target[kSecValueData as String] = secret
+    target[kSecAttrAccessible as String] = kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
+    let added = SecItemAdd(target as CFDictionary, nil)
+    guard added == errSecSuccess || added == errSecDuplicateItem else { return false }
+
+    return SecItemDelete(source as CFDictionary) == errSecSuccess
 }
 ```
 
-> For the complete versioned migration approach and fresh-install detection pattern, see `migration-legacy-stores.md` section First-Launch Keychain Cleanup.
-> Key point: The pattern above handles the basic sharing-context case; the canonical file covers multi-version migration coordination, safe deletion ordering, and CI implications.
-
-### App transfers between teams break keychain access
-
-Items are tied to the original Team ID. If an app is transferred to another developer account, keychain items stored under the old Team ID become inaccessible. Recommended workaround: transfer the app back, release an update that exports/migrates keychain data to an external store, then transfer again.
-
-### Cross-developer sharing is impossible via access groups
-
-The Team ID prefix enforcement, through code-signed provisioning profiles, prevents apps from different teams from accessing each other's keychain items. Cross-developer credential sharing requires iCloud Keychain + Associated Domains (password autofill based on web domain ownership).
+## Lifecycle surprises
 
----
+- Keychain items survive uninstalling the app. This is long-standing but
+  undocumented; an iOS 10.3 beta deleted them on removal and the change was reverted.
+  Apple DTS has warned it could change without notice.
+- Deleting app A leaves group items in place for app B. Deleting every app in the group
+  still leaves the items as orphans; only erasing the device reliably removes them.
+- A fresh install therefore can find old items. UserDefaults is removed on uninstall,
+  so a flag there tells a first launch apart:
 
-## Platform-Specific Patterns
-
-### watchOS
-
-watchOS 2+ runs a **separate keychain** not connected to the paired iPhone's keychain through access groups. Sharing credentials between iPhone and Watch requires either iCloud Keychain sync (`kSecAttrSynchronizable: true`, available since watchOS 6.2) or WatchConnectivity data transfer. For watchOS apps, add Keychain Sharing to the **WatchKit Extension target**, not the WatchKit App target.
-
-### Widget Extensions (WidgetKit)
-
-Widget extensions follow the same rules as all app extensions  -  add Keychain Sharing or App Groups capabilities to the widget extension target independently. Widgets commonly need auth tokens for network requests. Store these in the shared keychain group rather than `UserDefaults(suiteName:)`, which lacks keychain-level encryption. App Group shared containers use only standard filesystem encryption (`NSFileProtectionCompleteUntilFirstUserAuthentication`), making the keychain the more secure choice for sensitive credentials.
-
----
-
-## Build and Distribution Considerations
-
-The entitlement format and Team ID prefix rules are consistent across all build configurations: development, Ad Hoc, TestFlight, and App Store distribution. The Team ID is inherent to the developer account and does not change between configurations.
-
-However, the specific **provisioning profile** for each distribution type dictates which entitlements are allowed and embeds the correct `AppIdentifierPrefix`. Verify that the provisioning profile for each build type correctly authorizes the required access groups.
-
-**Legacy account caveat:** Most modern accounts use the Team ID as the App ID prefix, but legacy accounts (pre-June 2011) may have per-app prefixes that differ from the Team ID. Adding capabilities like Associated Domains to one target but not another has been reported to change the prefix, causing `-34018` errors. Ensure all targets sharing a keychain group have identical capabilities.
-
----
-
-## Debugging When Keychain Sharing Breaks
-
-### Essential Error Codes
-
-| Code       | Constant                      | Meaning                                                          |
-| ---------- | ----------------------------- | ---------------------------------------------------------------- |
-| **0**      | `errSecSuccess`               | Operation succeeded                                              |
-| **-25299** | `errSecDuplicateItem`         | Item exists; use `SecItemUpdate` instead                         |
-| **-25300** | `errSecItemNotFound`          | No match found; also returned pre-iOS 13 for unauthorized groups |
-| **-34018** | `errSecMissingEntitlement`    | App lacks entitlement for the specified access group             |
-| **-25308** | `errSecInteractionNotAllowed` | Device locked and item requires `WhenUnlocked` access            |
-| **-50**    | `errSecParam`                 | Invalid parameter (missing `kSecClass`, wrong value types)       |
-
-Starting with **iOS 13**, querying an unauthorized access group returns the explicit `errSecMissingEntitlement` (-34018) instead of the ambiguous `errSecItemNotFound`. This makes debugging significantly easier on modern OS versions.
-
-### Debugging Checklist
-
-**1. Verify entitlements on the built binary**  -  not the `.entitlements` source file:
-
-```bash
-codesign -d --entitlements :- /path/to/YourApp.app
-codesign -d --entitlements :- /path/to/YourExtension.appex
-```
-
-Compare the `keychain-access-groups` arrays  -  they must contain a common group.
-
-**2. Inspect the provisioning profile:**
-
-```bash
-security cms -D -i YourApp.app/embedded.mobileprovision
+```swift
+func purgeLeftoversOnFreshInstall() {
+    let marker = "vault.didLaunch"
+    guard !UserDefaults.standard.bool(forKey: marker) else { return }
+    let scoped: [String: Any] = [
+        kSecClass as String: kSecClassGenericPassword,
+        kSecAttrService as String: SharedVault.service,
+        kSecAttrAccessGroup as String: SharedVault.group
+    ]
+    SecItemDelete(scoped as CFDictionary)
+    UserDefaults.standard.set(true, forKey: marker)
+}
 ```
 
-Verify that `keychain-access-groups`, `com.apple.security.application-groups`, and `com.apple.developer.team-identifier` are present and correct.
-
-**3. Test on a physical device.** The iOS Simulator does not use real provisioning profiles and may not surface entitlement issues. Keychain Sharing behavior in the Simulator can differ from device behavior.
-
-**4. Monitor system logs.** Open Console.app, select the connected device, filter for "keychain", and reproduce the issue. The system logs explicit messages when an entitlement check fails, identifying the missing group.
-
-**5. Check for App ID prefix mismatches** across all sharing targets  -  especially if any target has different capabilities enabled.
-
-### Test Matrix
-
-| Scenario                                   | Main App | Share Ext | Widget Ext | Expected                                  |
-| ------------------------------------------ | :------: | :-------: | :--------: | ----------------------------------------- |
-| Write/read in `TeamID.com.example.shared`  |   Pass   |   Pass    |    Pass    | All targets see same item                 |
-| Write/read in `group.com.example.appsuite` |   Pass   |   Pass    |    Pass    | Only when `kSecAttrAccessGroup` specified |
-| iCloud sync (non-`ThisDeviceOnly`)         |   Pass   |    N/A    |    N/A     | Item appears on second device             |
-| Missing entitlement in extension           |   N/A    |   Fail    |    N/A     | `-34018` or `-25300`                      |
-
----
-
-## Security Threat Model Notes
-
-- **End-to-end encryption:** Synchronized iCloud Keychain items are encrypted end-to-end; Apple cannot decrypt them.
-- **Malicious device risk:** A device joined to the user's iCloud account could potentially access or poison synchronized keychain items. Always scope secrets minimally and validate data retrieved from shared or synchronized keychains.
-- **Over-sharing risk:** Items placed in a shared access group are readable by all apps in that group. Use the narrowest possible access group  -  do not share an access group across apps that do not need the same credentials.
-- **Orphaned items:** After all apps in a shared group are uninstalled, keychain items remain on-device until factory reset. Consider this when storing highly sensitive data.
-
----
-
-## What Changed in 2024-2026
-
-The core `SecItem` API has **not changed**. No new keychain-sharing-specific APIs were introduced in iOS 17, 18, or macOS 14/15. Apple still has not shipped a Swift-native keychain wrapper; the C-based Security framework remains the only official interface.
-
-The **Passwords app** introduced in iOS 18 and macOS Sequoia (WWDC 2024) provides a dedicated user-facing interface for managing passwords, passkeys, and verification codes. This is a UI layer over iCloud Keychain  -  it does not affect the `SecItem` API or access group mechanics.
-
-**Passkey enhancements** continued through WWDC 2024-2025, including automatic passkey upgrades and credential import/export APIs (`ASCredentialExportManager`). These operate at the credential-manager level and do not introduce new keychain-sharing mechanisms.
-
-`kSecAttrAccessibleAlways` and `kSecAttrAccessibleAlwaysThisDeviceOnly` remain deprecated since iOS 12. Use `kSecAttrAccessibleAfterFirstUnlock` or the more restrictive `kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly`.
-
----
-
-## Cross-References
-
-- `keychain-fundamentals.md`  -  SecItem CRUD patterns, `kSecUseDataProtectionKeychain` on macOS, query dictionary construction
-- `keychain-access-control.md`  -  Accessibility constants for shared items, `ThisDeviceOnly` vs syncable implications
-- `keychain-item-classes.md`  -  Composite primary keys and how `kSecAttrAccessGroup` interacts with each `kSecClass`
-- `common-anti-patterns.md`  -  Anti-pattern #5 (missing `kSecAttrAccessible`), which compounds in shared contexts
-- `credential-storage-patterns.md`  -  OAuth token sharing between app and extensions
-
----
-
-## Conclusion
-
-Keychain sharing on Apple platforms is a precise, entitlement-driven system where small configuration errors  -  a missing Team ID prefix, a capability not added to an extension target, a forgotten `kSecUseDataProtectionKeychain` on macOS  -  produce cryptic errors with no runtime warnings. The access group array's three-source concatenation order determines defaults and search scope in ways that catch developers off guard.
-
-Three rules prevent most issues: always include the full Team ID prefix in code (`TEAMID.com.example.shared`, never just `com.example.shared`); add Keychain Sharing to every executable target that needs access, not just the main app; and set `kSecUseDataProtectionKeychain` to `true` on macOS for iOS-consistent behavior. For iCloud sync, remember that `kSecAttrSynchronizable` defaults to `false` and that queries must explicitly opt in to find synchronizable items.
-
----
-
-## Summary Checklist
-
-1. **Team ID prefix in code**  -  Access group strings in Swift must use the fully resolved `TEAMID.com.example.shared` format; `$(AppIdentifierPrefix)` only works in entitlements plists.
-2. **Per-target entitlements**  -  Every executable target (main app, each extension) must independently have the Keychain Sharing capability added in Xcode with the same group identifier.
-3. **Keychain Sharing vs App Groups**  -  These are separate entitlements with different formats (`keychain-access-groups` with Team ID prefix vs `com.apple.security.application-groups` with `group.` prefix). App Groups cannot serve as keychain access groups on macOS.
-4. **Default access group awareness**  -  The first entry in the concatenated access group array (keychain groups → app identifier → app groups) becomes the default. App Groups can never be the default.
-5. **Explicit `kSecAttrAccessGroup`**  -  Always specify the access group in both `SecItemAdd` and `SecItemCopyMatching` calls. Omitting it on add uses the default group (which may be unexpected); omitting it on query searches all groups (which may be slow or overly broad).
-6. **iCloud sync is opt-in**  -  `kSecAttrSynchronizable` defaults to `false`. Sync requires non-`ThisDeviceOnly` accessibility, and queries must include `kSecAttrSynchronizable: true` or `kSecAttrSynchronizableAny` to find synced items.
-7. **macOS data protection keychain**  -  Set `kSecUseDataProtectionKeychain: true` on all macOS `SecItem` calls. Without it, `kSecAttrAccessGroup` is silently ignored and the legacy file-based keychain is used.
-8. **Items persist after uninstall**  -  Keychain items survive app deletion. Use a `UserDefaults` flag to detect fresh installs and clean up stale items. Scope deletion carefully to avoid nuking shared items.
-9. **`kSecAttrAccessGroup` is immutable**  -  Moving an item between groups requires a read-add-delete sequence, not an update.
-10. **Verify built binary entitlements**  -  Use `codesign -d --entitlements :-` on the built `.app`/`.appex` to confirm entitlements, not the source `.entitlements` file. Test on physical devices; the Simulator may not surface entitlement issues.
-11. **watchOS is isolated**  -  The Apple Watch has a separate keychain not connected via access groups. Use iCloud Keychain sync or WatchConnectivity for cross-device credential sharing.
+  Scope the delete by service and group; never wipe everything in a shared group,
+  because sibling apps may still be installed and using it. The complete launch
+  sequence is in [migration-legacy-stores.md](migration-legacy-stores.md).
+- Transferring an app to another developer team orphans its items under the old Team
+  ID. The only workaround is to transfer back, ship an update that exports or migrates
+  the data somewhere else, then transfer again.
+- Access groups cannot be shared with another developer's apps. Use iCloud Keychain
+  with Associated Domains for that.
+
+## Platform notes
+
+- **watchOS.** Since watchOS 2 the watch has its own keychain, not joined to the
+  iPhone's through access groups. Share through iCloud Keychain sync
+  (`kSecAttrSynchronizable: true`, watchOS 6.2+) or send data over WatchConnectivity.
+  Add Keychain Sharing to the WatchKit extension target, not the WatchKit app target.
+- **Widgets.** Put the capabilities on the widget target itself. Keep auth tokens in
+  the shared keychain group, not in `UserDefaults(suiteName:)`.
+- **App Group containers** get only standard file protection
+  (`NSFileProtectionCompleteUntilFirstUserAuthentication`). The Keychain is the safer
+  home for credentials.
+
+## Signing and distribution
+
+- The entitlement format and Team ID prefix are the same for development, Ad Hoc,
+  TestFlight and App Store builds.
+- Each distribution profile decides which entitlements are allowed and embeds the
+  `AppIdentifierPrefix`. Check that every one of them authorizes the groups.
+- Accounts created before June 2011 may have per-app prefixes that differ from the
+  Team ID. There are reports that adding a capability (Associated Domains, for example)
+  to one target but not another changes that target's prefix and produces -34018. Keep
+  capabilities identical across targets that share a group.
+
+## When sharing breaks
+
+| Status | Meaning |
+| --- | --- |
+| 0 `errSecSuccess` | Worked |
+| -25299 `errSecDuplicateItem` | Item exists; update it instead |
+| -25300 `errSecItemNotFound` | No match; before iOS 13 also the result for a group you are not entitled to |
+| -34018 `errSecMissingEntitlement` | The target is not entitled to that group (iOS 13+) |
+| -25308 `errSecInteractionNotAllowed` | Device locked and the item is WhenUnlocked |
+| -50 `errSecParam` | Bad query: missing `kSecClass`, wrong value types, or sync combined with ThisDeviceOnly |
+| -128 `errSecUserCanceled` | The user dismissed an authentication prompt |
+
+From iOS 13 an unauthorized group reports -34018 rather than -25300.
+
+Steps:
+
+1. Inspect the entitlements actually signed into the build:
+   `codesign -d --entitlements :- MyApp.app` and the same for `MyWidget.appex`. The
+   arrays must share the group.
+2. Decode the embedded profile: `security cms -D -i MyApp.app/embedded.mobileprovision`.
+   Check `keychain-access-groups`, `com.apple.security.application-groups` and
+   `com.apple.developer.team-identifier`.
+3. Test on a physical device. The Simulator lacks real provisioning and can hide
+   entitlement problems.
+4. Watch the device in Console.app filtered on "keychain"; failed entitlement checks
+   name the group.
+5. Compare App ID prefixes across all targets.
+
+| Test | Expected |
+| --- | --- |
+| Team-ID group item read by app, share extension, widget | All succeed |
+| Item in a `group.` group | Works only with explicit `kSecAttrAccessGroup` |
+| Synced item (not ThisDeviceOnly) | Appears on a second device on the same account |
+| Extension without the entitlement | -34018 (or -25300 before iOS 13) |
+
+## Threat model
+
+- Synced items are end-to-end encrypted.
+- Any device the user adds to their iCloud account can read, and could tamper with,
+  synced items. Sync as little as possible and validate what you read back.
+- Every app in a group can read every item in it. Use the narrowest group.
+- Orphaned items persist until the device is erased; weigh that for very sensitive
+  data.
+
+## 2024 to 2026
+
+- The `SecItem` API is unchanged. iOS 17/18 and macOS 14/15 added no sharing APIs, and
+  there is still no Apple Swift-native Keychain wrapper.
+- The Passwords app in iOS 18 and macOS Sequoia is a front end to iCloud Keychain; it
+  changes no API or group behaviour.
+- Passkey work (automatic upgrades, `ASCredentialExportManager` import and export)
+  happens at the credential-manager level and adds no sharing mechanism.
+- The `Always` accessibility constants have been deprecated since iOS 12. Use
+  `AfterFirstUnlock` or `WhenPasscodeSetThisDeviceOnly`.
+
+## Related
+
+[keychain-fundamentals.md](keychain-fundamentals.md) for the SecItem contract,
+[keychain-access-control.md](keychain-access-control.md) for accessibility classes,
+[keychain-item-classes.md](keychain-item-classes.md) for primary keys,
+[common-anti-patterns.md](common-anti-patterns.md) (#5, wrong data protection class),
+and [credential-storage-patterns.md](credential-storage-patterns.md) for sharing tokens
+with extensions.
+
+## Checklist
+
+- [ ] Code uses the full `TEAMID.` prefixed group string.
+- [ ] Keychain Sharing is on every executable target.
+- [ ] Keychain Sharing and App Groups formats are not mixed up; App Groups are not
+      used for Keychain on macOS.
+- [ ] Default group understood: keychain groups, then app id, then app groups; an app
+      group is never the default.
+- [ ] `kSecAttrAccessGroup` set explicitly on every add and query.
+- [ ] Sync is opt-in, never with ThisDeviceOnly, and queries include
+      `kSecAttrSynchronizable: true` or `kSecAttrSynchronizableAny`.
+- [ ] macOS calls set `kSecUseDataProtectionKeychain: true`.
+- [ ] Leftover items after reinstall handled with a UserDefaults flag and a scoped
+      delete.
+- [ ] Group changes done as read, add, then delete.
+- [ ] Built entitlements checked with `codesign`; tested on a device.
+- [ ] watchOS treated as a separate keychain; shared through sync or WatchConnectivity.