@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

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

@@ -1,515 +1,514 @@
 # Keychain Item Classes
 
-> Scope: Correct class selection and attribute usage for all five `kSecClass` types, with emphasis on uniqueness rules, AutoFill behavior, and migration safety.
-
-The five `kSecClass` types  -  GenericPassword, InternetPassword, Key, Certificate, and Identity  -  each serve distinct roles with unique attribute requirements that AI code generators routinely get wrong. **Choosing the wrong class** causes silent AutoFill failures, query collisions, and subtle security degradation. This reference covers every class with its composite primary key, required and optional attributes, correct Swift patterns, and the specific mistakes to watch for.
-
-The keychain is an encrypted SQLite database optimized for small secrets. Each item class defines a set of attributes forming a **composite primary key**  -  adding an item whose primary key matches an existing item returns `errSecDuplicateItem` (-25299). Understanding these primary keys is the single most important concept for correct keychain usage.
-
-**Sources:** Apple Keychain Services documentation, TN3137 ("On Mac keychain APIs and implementations"), Quinn "The Eskimo!" DTS posts ("SecItem: Fundamentals," "SecItem: Pitfalls and Best Practices"), Apple Platform Security Guide, WWDC 2022-2024 passkey sessions, OWASP MASVS/MASTG.
-
----
+The keychain stores five kinds of item: `kSecClassGenericPassword`,
+`kSecClassInternetPassword`, `kSecClassKey`, `kSecClassCertificate` and
+`kSecClassIdentity`. Choosing the wrong one does not crash anything. It shows up
+later as Password AutoFill that never offers the credential, queries that
+collide with unrelated items, or keys stored with weaker handling than they
+should get.
+
+Each class has its own composite primary key. A second add whose primary-key
+attributes equal an existing item's fails with `errSecDuplicateItem` (-25299).
+The save pattern (add, then update on duplicate) is in
+[keychain-fundamentals.md](keychain-fundamentals.md).
 
 ## Contents
 
-- [Composite Primary Keys by Class](#composite-primary-keys-by-class)
-- [kSecClassGenericPassword  -  App-Specific Secrets](#ksecclassgenericpassword-app-specific-secrets)
-  - [The kSecAttrGeneric trap](#the-ksecattrgeneric-trap)
-- [kSecClassInternetPassword  -  AutoFill and Credential Sharing](#ksecclassinternetpassword-autofill-and-credential-sharing)
-  - [How AutoFill Integration Works](#how-autofill-integration-works)
-  - [Protocol and Authentication Constants](#protocol-and-authentication-constants)
-  - [Credential Provider Extensions (iOS 12+)](#credential-provider-extensions-ios-12)
-- [kSecClassKey  -  Cryptographic Key Management](#ksecclasskey-cryptographic-key-management)
-  - [ApplicationTag vs ApplicationLabel  -  The Critical Distinction](#applicationtag-vs-applicationlabel-the-critical-distinction)
-  - [SecKeyCreateRandomKey  -  The Preferred API](#seckeycreaterandomkey-the-preferred-api)
-  - [CryptoKit Key Storage Mapping](#cryptokit-key-storage-mapping)
-- [kSecClassCertificate  -  DER-Encoded Certificate Storage](#ksecclasscertificate-der-encoded-certificate-storage)
-- [kSecClassIdentity  -  The Virtual Join](#ksecclassidentity-the-virtual-join)
-  - [Why SecItemAdd with kSecClassIdentity Fails](#why-secitemadd-with-ksecclassidentity-fails)
-  - [Three Correct Approaches to Creating an Identity](#three-correct-approaches-to-creating-an-identity)
-- [Correctness Issues AI Generators Get Wrong](#correctness-issues-ai-generators-get-wrong)
-  - [1. GenericPassword for Everything](#1-genericpassword-for-everything)
-  - [2. Direct Identity Creation](#2-direct-identity-creation)
-  - [3. Missing Key Type Attributes](#3-missing-key-type-attributes)
-  - [4. ApplicationTag / ApplicationLabel Confusion](#4-applicationtag-applicationlabel-confusion)
-  - [5. No Duplicate Handling](#5-no-duplicate-handling)
-  - [6. Missing kSecUseDataProtectionKeychain on macOS](#6-missing-ksecusedataprotectionkeychain-on-macos)
-  - [7. Storing Large Blobs in Keychain](#7-storing-large-blobs-in-keychain)
-- [Modern API Patterns and Platform Differences](#modern-api-patterns-and-platform-differences)
-  - [kSecUseDataProtectionKeychain Unifies Cross-Platform Behavior](#ksecusedataprotectionkeychain-unifies-cross-platform-behavior)
-  - [TN3137 Key Takeaways](#tn3137-key-takeaways)
-  - [iCloud Keychain Sync Restrictions](#icloud-keychain-sync-restrictions)
-- [Size Limits, Performance, and When to Use Files](#size-limits-performance-and-when-to-use-files)
-  - [Performance Architecture](#performance-architecture)
-  - [Envelope Encryption for Large Data](#envelope-encryption-for-large-data)
-  - [Querying with kSecReturnAttributes for Metadata Inspection](#querying-with-ksecreturnattributes-for-metadata-inspection)
-- [Testing Matrix for Class Correctness](#testing-matrix-for-class-correctness)
-- [Migration: GenericPassword to InternetPassword](#migration-genericpassword-to-internetpassword)
-- [Cross-Reference Index](#cross-reference-index)
-- [Conclusion](#conclusion)
-- [Summary Checklist](#summary-checklist)
-
-## Composite Primary Keys by Class
-
-Every `kSecClass` defines a specific attribute set forming its uniqueness constraint. `kSecAttrAccessGroup` and `kSecAttrSynchronizable` participate in the primary key for all classes.
-
-| Class                | Primary Key Attributes                                                                                                                                | Typical Use                                       |
-| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
-| **GenericPassword**  | `kSecAttrService` + `kSecAttrAccount`                                                                                                                 | App-specific secrets, API tokens, encryption keys |
-| **InternetPassword** | `kSecAttrServer` + `kSecAttrProtocol` + `kSecAttrPort` + `kSecAttrPath` + `kSecAttrAccount` + `kSecAttrSecurityDomain` + `kSecAttrAuthenticationType` | Web credentials, server passwords, AutoFill       |
-| **Key**              | `kSecAttrApplicationLabel` + `kSecAttrApplicationTag` + `kSecAttrKeyClass` + `kSecAttrKeyType` + `kSecAttrKeySizeInBits` + `kSecAttrEffectiveKeySize` | RSA/EC keys, symmetric keys                       |
-| **Certificate**      | `kSecAttrCertificateType` + `kSecAttrIssuer` + `kSecAttrSerialNumber`                                                                                 | X.509 certificates                                |
-| **Identity**         | Same as Certificate (virtual join, not a stored item)                                                                                                 | TLS client auth, code signing                     |
-
-Omitting a primary key attribute does not cause an error  -  the system uses a nil/empty default. But a second add with the same defaults produces `errSecDuplicateItem`, which is a frequent source of confusion.
-
----
-
-## kSecClassGenericPassword  -  App-Specific Secrets
-
-GenericPassword is the correct choice for API tokens, OAuth refresh tokens, encryption keys, and any secret that does not represent a web login credential. Its primary key is effectively **`kSecAttrService` + `kSecAttrAccount`**.
-
-**Required for meaningful usage** (not enforced by the API, but omitting them causes collisions): `kSecAttrService` (CFString  -  typically bundle ID or service identifier) and `kSecAttrAccount` (CFString  -  the account or key name). The actual secret goes in `kSecValueData` as `Data`.
-
-**Optional metadata attributes:** `kSecAttrLabel` (human-readable name), `kSecAttrDescription` (item kind), `kSecAttrComment` (user-editable note), `kSecAttrCreator` and `kSecAttrType` (FourCharCode as CFNumber), `kSecAttrGeneric` (arbitrary CFData for custom metadata), `kSecAttrIsInvisible`/`kSecAttrIsNegative` (boolean flags). System-managed read-only: `kSecAttrCreationDate`, `kSecAttrModificationDate`.
-
-### The kSecAttrGeneric trap
-
-`kSecAttrGeneric` is **NOT part of the primary key** despite its name suggesting otherwise. Two items with identical `kSecAttrService` + `kSecAttrAccount` but different `kSecAttrGeneric` values still collide  -  the second add fails with `errSecDuplicateItem`. Yet querying by `kSecAttrGeneric` that does not match returns `errSecItemNotFound` even though an item with that service+account exists. This inconsistency is a major source of bugs.
+- [Primary Keys per Class](#primary-keys-per-class)
+- [Generic Password](#generic-password)
+- [Internet Password](#internet-password)
+- [Key](#key)
+- [Certificate](#certificate)
+- [Identity](#identity)
+- [Mistakes Generated Code Makes](#mistakes-generated-code-makes)
+- [Platform Differences](#platform-differences)
+- [Size and When to Use a File](#size-and-when-to-use-a-file)
+- [Tests That Prove the Class Is Right](#tests-that-prove-the-class-is-right)
+- [Moving Web Logins to Internet Passwords](#moving-web-logins-to-internet-passwords)
+- [Checklist](#checklist)
+- [Related Files](#related-files)
+
+## Primary Keys per Class
+
+For every class, `kSecAttrAccessGroup` and `kSecAttrSynchronizable` are also
+part of the key.
+
+| Class | Primary-key attributes | Use it for |
+| --- | --- | --- |
+| Generic password | `kSecAttrService`, `kSecAttrAccount` | app secrets, API tokens, raw key bytes |
+| Internet password | `kSecAttrAccount`, `kSecAttrServer`, `kSecAttrPath`, `kSecAttrPort`, `kSecAttrProtocol`, `kSecAttrAuthenticationType`, `kSecAttrSecurityDomain` | website logins, AutoFill |
+| Key | `kSecAttrApplicationTag`, `kSecAttrApplicationLabel`, `kSecAttrKeyType`, `kSecAttrKeyClass`, `kSecAttrEffectiveKeySize`, `kSecAttrKeySizeInBits` | `SecKey` objects |
+| Certificate | `kSecAttrIssuer`, `kSecAttrSerialNumber`, `kSecAttrCertificateType` | X.509 certificates |
+| Identity | same as certificate | not stored; a join of certificate and private key |
+
+Leaving a primary-key attribute out is legal. The attribute then takes an empty
+default, and the next add that also leaves it out collides with the first.
+
+## Generic Password
+
+Pick this class for OAuth refresh tokens, API tokens, symmetric key bytes and
+any secret that is not a website login.
+
+- Set `kSecAttrService` (the bundle identifier or a service name) and
+  `kSecAttrAccount`. The API will not insist on them, but without them unrelated
+  items collide. Put the secret itself, as `Data`, under `kSecValueData`.
+- Optional descriptive attributes: `kSecAttrLabel`, `kSecAttrDescription`,
+  `kSecAttrComment`, `kSecAttrCreator` and `kSecAttrType` (FourCharCode as
+  `CFNumber`), `kSecAttrGeneric` (`CFData`), `kSecAttrIsInvisible`,
+  `kSecAttrIsNegative`. The system maintains `kSecAttrCreationDate` and
+  `kSecAttrModificationDate`; they are read-only.
+- `kSecAttrGeneric` does not count toward uniqueness. Two adds that differ only in
+  `kSecAttrGeneric` still collide, yet a query that filters on a different
+  `kSecAttrGeneric` value reports the item as missing.
 
 ```swift
-// ✅ GenericPassword for an app-specific API token
-let addQuery: [String: Any] = [
-    kSecClass as String: kSecClassGenericPassword,
-    kSecAttrService as String: "com.myapp.api",
-    kSecAttrAccount as String: "oauth-refresh-token",
-    kSecValueData as String: tokenString.data(using: .utf8)!,
-    kSecAttrAccessible as String: kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly,
-    kSecUseDataProtectionKeychain as String: true
-]
-let status = SecItemAdd(addQuery as CFDictionary, nil)
+func addLicenseKey(_ bytes: Data) -> OSStatus {
+    var entry: [String: Any] = [
+        kSecClass as String: kSecClassGenericPassword,
+        kSecAttrService as String: "com.example.editor",
+        kSecAttrAccount as String: "license",
+        kSecValueData as String: bytes,
+        kSecAttrAccessible as String: kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
+    ]
+    #if os(macOS)
+    entry[kSecUseDataProtectionKeychain as String] = true
+    #endif
+    return SecItemAdd(entry as CFDictionary, nil)
+}
 ```
 
-**When to choose GenericPassword vs InternetPassword:** If the credential belongs to a web domain and you want AutoFill, use InternetPassword. GenericPassword's `kSecAttrService` is an opaque string with no semantic meaning to the system  -  it cannot trigger Password AutoFill.
-
----
-
-## kSecClassInternetPassword  -  AutoFill and Credential Sharing
+The caller switches on the returned status and updates on
+`errSecDuplicateItem`.
 
-InternetPassword exists specifically for credentials associated with network services. Its **7-attribute composite primary key** enables the system to match credentials to domains for Password AutoFill, Safari integration, and cross-device sync.
+Decision rule: a credential for a web domain that should appear in Password
+AutoFill belongs in an internet password. To the system, a generic password's
+service string is an opaque label, so AutoFill never offers it.
 
-Primary key attributes: `kSecAttrServer` (hostname), `kSecAttrProtocol` (e.g., `kSecAttrProtocolHTTPS`), `kSecAttrPort` (CFNumber), `kSecAttrPath` (URL path), `kSecAttrAccount` (username), `kSecAttrSecurityDomain` (HTTP realm), `kSecAttrAuthenticationType` (e.g., `kSecAttrAuthenticationTypeHTMLForm`).
+## Internet Password
 
-**Notable:** `kSecAttrGeneric` and `kSecAttrService` are **NOT available** for InternetPassword  -  the server/protocol/path attributes serve the equivalent purpose.
+The seven-attribute key is what lets the system connect a credential to a
+domain for AutoFill, Safari and syncing across devices.
 
-### How AutoFill Integration Works
+| Attribute | Meaning |
+| --- | --- |
+| `kSecAttrServer` | host name |
+| `kSecAttrProtocol` | for example `kSecAttrProtocolHTTPS` |
+| `kSecAttrPort` | `CFNumber` |
+| `kSecAttrPath` | path on the server |
+| `kSecAttrAccount` | the user name |
+| `kSecAttrSecurityDomain` | the HTTP realm |
+| `kSecAttrAuthenticationType` | for example `kSecAttrAuthenticationTypeHTMLForm` |
 
-Password AutoFill matches credentials to apps and websites by comparing `kSecAttrServer` against associated domains. Full integration requires three pieces:
+`kSecAttrService` and `kSecAttrGeneric` do not exist on this class.
 
-1. **Store credentials as InternetPassword** with `kSecAttrServer` set to the website domain
-2. **Configure Associated Domains** by adding `webcredentials:<domain>` to the app's entitlements
-3. **Host an apple-app-site-association file** at `https://<domain>/.well-known/apple-app-site-association` containing `{"webcredentials": {"apps": ["TEAMID.com.example.app"]}}`
+AutoFill needs three things together:
 
-When all three are in place, the iOS QuickType bar automatically suggests matching credentials. Safari stores all web passwords as `kSecClassInternetPassword`  -  using GenericPassword for web credentials means the system can never suggest them for AutoFill.
+1. the credential stored as an internet password with `kSecAttrServer` set;
+2. the Associated Domains entitlement containing `webcredentials:<domain>`;
+3. the domain's association file, published over HTTPS under the
+   `.well-known` directory, with a `webcredentials.apps` array that lists
+   `TEAMID.bundle.identifier`.
 
-```swift
-// ✅ InternetPassword enabling AutoFill
-let addQuery: [String: Any] = [
-    kSecClass as String: kSecClassInternetPassword,
-    kSecAttrServer as String: "example.com",
-    kSecAttrProtocol as String: kSecAttrProtocolHTTPS,
-    kSecAttrPort as String: 443,
-    kSecAttrPath as String: "/login",
-    kSecAttrAccount as String: "user@example.com",
-    kSecAttrAuthenticationType as String: kSecAttrAuthenticationTypeHTMLForm,
-    kSecValueData as String: "password123".data(using: .utf8)!,
-    kSecUseDataProtectionKeychain as String: true
-]
-let status = SecItemAdd(addQuery as CFDictionary, nil)
-```
+Safari itself keeps every web password as an internet password, and a web
+login stored as a generic password is never suggested.
 
 ```swift
-// ❌ GenericPassword for web credentials  -  AutoFill will never find these
-let badQuery: [String: Any] = [
-    kSecClass as String: kSecClassGenericPassword,       // WRONG CLASS
-    kSecAttrService as String: "example.com",             // Opaque to AutoFill
-    kSecAttrAccount as String: "user@example.com",
-    kSecValueData as String: "password123".data(using: .utf8)!
+// Wrong: the domain is hidden in an opaque service string; AutoFill ignores it.
+let hidden: [String: Any] = [
+    kSecClass as String: kSecClassGenericPassword,
+    kSecAttrService as String: "forum.example.org",
+    kSecAttrAccount as String: "rhea",
+    kSecValueData as String: Data("pw".utf8)
 ]
 ```
 
-### Protocol and Authentication Constants
-
-Protocol constants span **30+ values** including `kSecAttrProtocolHTTPS`, `kSecAttrProtocolHTTP`, `kSecAttrProtocolSSH`, `kSecAttrProtocolFTP`, `kSecAttrProtocolIMAPS`, `kSecAttrProtocolSMTP`, and many more. Authentication types include `kSecAttrAuthenticationTypeHTMLForm`, `kSecAttrAuthenticationTypeHTTPBasic`, `kSecAttrAuthenticationTypeHTTPDigest`, and `kSecAttrAuthenticationTypeDefault`.
-
-### Credential Provider Extensions (iOS 12+)
-
-For third-party password managers, `ASCredentialProviderViewController` enables credential provider extensions. Apps subclass this controller, populate `ASCredentialIdentityStore` with `ASPasswordCredentialIdentity` instances, and override `provideCredentialWithoutUserInteraction(for:)` for tap-to-fill behavior.
-
----
-
-## kSecClassKey  -  Cryptographic Key Management
-
-Key items require **`kSecAttrKeyType`** and **`kSecAttrKeySizeInBits`** for generation  -  omitting either from `SecKeyCreateRandomKey` returns `errSecParam` (-50). The `kSecAttrKeyClass` attribute (`kSecAttrKeyClassPublic`, `kSecAttrKeyClassPrivate`, `kSecAttrKeyClassSymmetric`) is set automatically during generation but must be specified when querying.
-
-### ApplicationTag vs ApplicationLabel  -  The Critical Distinction
-
-This confusion is the single most common keychain mistake for cryptographic keys, and AI generators get it wrong constantly:
-
-- **`kSecAttrApplicationTag`** (CFData): **Developer-set** binary tag for finding and organizing keys. You choose its content  -  typically a reverse-DNS string encoded as Data. Part of the primary key. **Use this for lookup.**
-- **`kSecAttrApplicationLabel`** (CFData): **System-generated** SHA-1 hash of the public key bytes (the `subjectPublicKey` element per RFC 5280 section4.1). Part of the primary key. **Used internally for identity formation**  -  it must match a certificate's `kSecAttrPublicKeyHash` to synthesize a `SecIdentity`. Never set this manually for asymmetric keys.
-- **`kSecAttrLabel`** (CFString): Human-readable display name. NOT part of the primary key. Shows in Keychain Access on macOS.
-
-### SecKeyCreateRandomKey  -  The Preferred API
-
-`SecKeyCreateRandomKey` (iOS 10+, macOS 10.12+) generates keys atomically, returns a `SecKey` reference directly, auto-computes `kSecAttrApplicationLabel`, and supports Secure Enclave generation via `kSecAttrTokenID: kSecAttrTokenIDSecureEnclave`. Apple recommends storing **only the private key** and deriving the public key via `SecKeyCopyPublicKey()`.
-
 ```swift
-// ✅ EC key creation with SecKeyCreateRandomKey
-let tag = "com.myapp.keys.signing".data(using: .utf8)!
-let attributes: [String: Any] = [
-    kSecAttrKeyType as String: kSecAttrKeyTypeECSECPrimeRandom,
-    kSecAttrKeySizeInBits as String: 256,
-    kSecPrivateKeyAttrs as String: [
-        kSecAttrIsPermanent as String: true,
-        kSecAttrApplicationTag as String: tag
+func webLogin(user: String, secret: Data) -> [String: Any] {
+    [
+        kSecClass as String: kSecClassInternetPassword,
+        kSecAttrServer as String: "forum.example.org",
+        kSecAttrProtocol as String: kSecAttrProtocolHTTPS,
+        kSecAttrPort as String: 443,
+        kSecAttrPath as String: "/login",
+        kSecAttrAccount as String: user,
+        kSecAttrAuthenticationType as String: kSecAttrAuthenticationTypeHTMLForm,
+        kSecValueData as String: secret,
+        kSecAttrAccessible as String: kSecAttrAccessibleWhenUnlocked,
+        kSecUseDataProtectionKeychain as String: true
     ]
-]
-var error: Unmanaged<CFError>?
-guard let privateKey = SecKeyCreateRandomKey(attributes as CFDictionary, &error) else {
-    throw error!.takeRetainedValue() as Error
 }
-let publicKey = SecKeyCopyPublicKey(privateKey)!
 ```
 
+There are more than thirty protocol constants (`kSecAttrProtocolHTTPS`,
+`kSecAttrProtocolHTTP`, `kSecAttrProtocolSSH`, `kSecAttrProtocolFTP`,
+`kSecAttrProtocolIMAPS`, `kSecAttrProtocolSMTP`, ...). Authentication types
+include `kSecAttrAuthenticationTypeHTMLForm`, `kSecAttrAuthenticationTypeHTTPBasic`,
+`kSecAttrAuthenticationTypeHTTPDigest` and `kSecAttrAuthenticationTypeDefault`.
+
+A password manager that wants to supply credentials system-wide builds a
+credential provider extension (iOS 12+): subclass
+`ASCredentialProviderViewController`, publish `ASPasswordCredentialIdentity`
+values to `ASCredentialIdentityStore`, and override
+`provideCredentialWithoutUserInteraction(for:)`.
+
+## Key
+
+- `kSecAttrKeyType` and `kSecAttrKeySizeInBits` are required to generate a key.
+  `SecKeyCreateRandomKey` without either returns `errSecParam`.
+- `kSecAttrKeyClass` (`kSecAttrKeyClassPublic`, `kSecAttrKeyClassPrivate`,
+  `kSecAttrKeyClassSymmetric`) is filled in on generation, but queries must name
+  it.
+- `kSecAttrApplicationTag` (`CFData`) is yours to set, is part of the key, and
+  is the attribute to look keys up by. Encode a reverse-DNS name to `Data` for
+  it.
+- `kSecAttrApplicationLabel` (`CFData`) is computed by the system as the SHA-1
+  of the public key (the `subjectPublicKey` bit string from RFC 5280 section
+  4.1). It is part of the key, and it has to equal a certificate's
+  `kSecAttrPublicKeyHash` for the pair to form a `SecIdentity`. Do not set it
+  yourself on asymmetric keys.
+- `kSecAttrLabel` (`CFString`) is only a display name. It is not part of the key
+  and is what Keychain Access shows on macOS.
+
+Prefer `SecKeyCreateRandomKey` (available from iOS 10 and macOS 10.12) as the way to make a
+key: it generates and stores in one step, returns a `SecKey`, computes the
+application label, and can target the Secure Enclave with
+`kSecAttrTokenID: kSecAttrTokenIDSecureEnclave`. Apple suggests persisting only
+the private key and obtaining the public half with `SecKeyCopyPublicKey()`.
+
 ```swift
-// ✅ Secure Enclave key with biometric protection
-var accessError: Unmanaged<CFError>?
-guard let accessControl = SecAccessControlCreateWithFlags(
-    kCFAllocatorDefault,
-    kSecAttrAccessibleWhenUnlockedThisDeviceOnly,
-    [.privateKeyUsage, .userPresence],
-    &accessError
-) else { throw accessError!.takeRetainedValue() as Error }
-
-let tag = "com.myapp.keys.se-signing".data(using: .utf8)!
-let attributes: [String: Any] = [
-    kSecAttrKeyType as String: kSecAttrKeyTypeECSECPrimeRandom,
-    kSecAttrKeySizeInBits as String: 256,
-    kSecAttrTokenID as String: kSecAttrTokenIDSecureEnclave,
-    kSecPrivateKeyAttrs as String: [
-        kSecAttrIsPermanent as String: true,
-        kSecAttrApplicationTag as String: tag,
-        kSecAttrAccessControl as String: accessControl
+func makeReceiptSigningKey() throws -> SecKey {
+    let tag = Data("com.example.receipts.signing".utf8)
+    let spec: [String: Any] = [
+        kSecAttrKeyType as String: kSecAttrKeyTypeECSECPrimeRandom,
+        kSecAttrKeySizeInBits as String: 256,
+        kSecPrivateKeyAttrs as String: [
+            kSecAttrIsPermanent as String: true,
+            kSecAttrApplicationTag as String: tag
+        ]
     ]
-]
-var genError: Unmanaged<CFError>?
-guard let privateKey = SecKeyCreateRandomKey(attributes as CFDictionary, &genError) else {
-    throw genError!.takeRetainedValue() as Error
+    var failure: Unmanaged<CFError>?
+    guard let key = SecKeyCreateRandomKey(spec as CFDictionary, &failure) else {
+        throw (failure?.takeRetainedValue() as Error?) ?? KeychainError(status: errSecParam)
+    }
+    return key
 }
 ```
 
-Direct `SecItemAdd` for keys is appropriate only when importing  -  Apple's "import, then add" pattern via `SecKeyCreateWithData`. Always create a `SecKey` object first; avoid adding raw key data directly.
-
-### CryptoKit Key Storage Mapping
-
-CryptoKit's NIST keys (P256, P384, P521) map to `SecKey` via `SecKeyCreateWithData` with `kSecAttrKeyTypeECSECPrimeRandom`, stored as `kSecClassKey`. **Non-NIST keys** (Curve25519, SymmetricKey) have no `SecKey` equivalent and must be stored as **`kSecClassGenericPassword`** items with raw key data in `kSecValueData`. Secure Enclave keys (`SecureEnclave.P256.Signing.PrivateKey`) export an encrypted blob that only the originating SE can restore  -  this blob is also stored as a generic password, not a key item.
-
----
-
-## kSecClassCertificate  -  DER-Encoded Certificate Storage
-
-Certificates are **not encrypted** by the keychain (they are public data). The primary key is `kSecAttrCertificateType` + `kSecAttrIssuer` + `kSecAttrSerialNumber`.
-
-Creation follows a two-step pattern: first create a `SecCertificate` from DER data, then add via `kSecValueRef`:
+For a Secure Enclave key, create the access control first and put it inside the
+private-key attributes. The flags always include `.privateKeyUsage`:
 
 ```swift
-// ✅ Adding a certificate
-guard let certificate = SecCertificateCreateWithData(nil, derData as CFData) else {
-    throw CertificateError.invalidDER  // Only accepts DER, not PEM
+func makeEnclaveKey() throws -> SecKey {
+    var failure: Unmanaged<CFError>?
+    guard let policy = SecAccessControlCreateWithFlags(
+        nil, kSecAttrAccessibleWhenUnlockedThisDeviceOnly,
+        [.privateKeyUsage, .userPresence], &failure) else {
+        throw (failure?.takeRetainedValue() as Error?) ?? KeychainError(status: errSecParam)
+    }
+    let spec: [String: Any] = [
+        kSecAttrKeyType as String: kSecAttrKeyTypeECSECPrimeRandom,
+        kSecAttrKeySizeInBits as String: 256,
+        kSecAttrTokenID as String: kSecAttrTokenIDSecureEnclave,
+        kSecPrivateKeyAttrs as String: [
+            kSecAttrIsPermanent as String: true,
+            kSecAttrApplicationTag as String: Data("com.example.enclave.auth".utf8),
+            kSecAttrAccessControl as String: policy
+        ]
+    ]
+    guard let key = SecKeyCreateRandomKey(spec as CFDictionary, &failure) else {
+        throw (failure?.takeRetainedValue() as Error?) ?? KeychainError(status: errSecParam)
+    }
+    return key
 }
-let addQuery: [String: Any] = [
-    kSecClass as String: kSecClassCertificate,
-    kSecValueRef as String: certificate,
-    kSecUseDataProtectionKeychain as String: true
-]
-let status = SecItemAdd(addQuery as CFDictionary, nil)
 ```
 
-When you pass a `SecCertificate` via `kSecValueRef`, the system **automatically extracts** `kSecAttrIssuer`, `kSecAttrSerialNumber`, `kSecAttrSubject`, `kSecAttrPublicKeyHash`, `kSecAttrCertificateType`, and `kSecAttrCertificateEncoding` from the certificate data. The critical attribute for identity formation is **`kSecAttrPublicKeyHash`**  -  the hash of the certificate's public key that must match a private key's `kSecAttrApplicationLabel`.
-
-**Common pitfall (Apple DTS):** `kSecAttrApplicationTag` is **NOT a valid attribute for certificates** (only for keys). Using it with `kSecClassCertificate` causes `errSecParam` (-50) on the data protection keychain or mysterious silent failures on the file-based keychain.
-
----
-
-## kSecClassIdentity  -  The Virtual Join
+`KeychainError` is the status wrapper from
+[keychain-fundamentals.md](keychain-fundamentals.md).
 
-**The keychain does not store digital identities as discrete items.** An identity is a logical join of a certificate and its matching private key, synthesized at query time when `kSecAttrPublicKeyHash` of a certificate matches `kSecAttrApplicationLabel` of a private key  -  both values being the SHA-1 hash of the public key.
+Call `SecItemAdd` for a key yourself only when importing one: build a `SecKey`
+from external bytes with `SecKeyCreateWithData`, then add it through
+`kSecValueRef`. Never add raw key bytes as a key item.
 
-### Why SecItemAdd with kSecClassIdentity Fails
+Mapping CryptoKit keys to storage:
 
-Attempting `SecItemAdd` with `kSecClass: kSecClassIdentity` will fail with `errSecParam` (-50). The system has no "identity table." Identity items appear only when the matching relationship exists between separately stored certificate and key items.
+| CryptoKit type | How to store |
+| --- | --- |
+| `P256`, `P384`, `P521` private keys | `SecKeyCreateWithData` with `kSecAttrKeyTypeECSECPrimeRandom`, then a `kSecClassKey` item |
+| `Curve25519` keys, `SymmetricKey` | no `SecKey` form; store the raw bytes as a generic password |
+| `SecureEnclave.P256` keys | keep the encrypted `dataRepresentation` blob in a generic password item |
 
-Cascading implications:
-
-- Adding a **certificate** can implicitly create an identity if a matching private key already exists
-- Adding a **private key** can implicitly create an identity if a matching certificate exists
-- Deleting a certificate or key can implicitly destroy an identity
-- The identity "set" changes without any explicit identity operations
-
-```swift
-// ❌ Attempting to create an identity directly  -  fails with errSecParam (-50)
-let attributes: [String: Any] = [
-    kSecClass as String: kSecClassIdentity,
-    kSecAttrLabel as String: "MyInvalidIdentity"
-]
-let status = SecItemAdd(attributes as CFDictionary, nil)
-// status == errSecParam (-50)
-```
+Details for the enclave case are in [secure-enclave.md](secure-enclave.md);
+the CryptoKit side is in [cryptokit-symmetric.md](cryptokit-symmetric.md) and
+[cryptokit-public-key.md](cryptokit-public-key.md).
 
-### Three Correct Approaches to Creating an Identity
+## Certificate
 
-**Method 1: PKCS#12 import** (most common for server-issued certificates):
+- Certificates are public, so the keychain does not encrypt them.
+- Adding one takes two steps: `SecCertificateCreateWithData(nil, der)` (DER
+  bytes only; strip PEM armor first), then `SecItemAdd` with `kSecValueRef`.
+- Passing the certificate by `kSecValueRef` lets the keychain extract issuer,
+  serial number, subject, `kSecAttrPublicKeyHash`, certificate type and
+  encoding for you.
+- `kSecAttrPublicKeyHash` has to match a private key's
+  `kSecAttrApplicationLabel` for an identity to appear.
+- `kSecAttrApplicationTag` is not valid on certificates: the data protection
+  keychain returns `errSecParam`, and the file-based keychain fails without
+  telling you.
 
 ```swift
-// ✅ Import identity from .p12 file
-let options: [String: Any] = [kSecImportExportPassphrase as String: "p12password"]
-var items: CFArray?
-let status = SecPKCS12Import(p12Data as CFData, options as CFDictionary, &items)
-guard status == errSecSuccess,
-      let results = items as? [[String: Any]],
-      let identity = results.first?[kSecImportItemIdentity as String] as? SecIdentity else {
-    throw IdentityError.importFailed
+func storeServerRoot(der: Data) throws {
+    guard let cert = SecCertificateCreateWithData(nil, der as CFData) else {
+        throw KeychainError(status: errSecParam)
+    }
+    let entry: [String: Any] = [
+        kSecClass as String: kSecClassCertificate,
+        kSecValueRef as String: cert,
+        kSecAttrLabel as String: "Internal root"
+    ]
+    let status = SecItemAdd(entry as CFDictionary, nil)
+    guard status == errSecSuccess || status == errSecDuplicateItem else {
+        throw KeychainError(status: status)
+    }
 }
-// Extract components
-var certificate: SecCertificate?
-SecIdentityCopyCertificate(identity, &certificate)
-var privateKey: SecKey?
-SecIdentityCopyPrivateKey(identity, &privateKey)
 ```
 
-**Method 2: Add certificate and key separately** with matching public key hashes. Both items must be in the same keychain implementation  -  on macOS, both must use `kSecUseDataProtectionKeychain: true` or both must be in the file-based keychain.
-
-**Method 3: macOS-only**  -  `SecIdentityCreateWithCertificate` searches keychains for a matching private key given a certificate reference.
-
----
+A duplicate certificate is by definition the same certificate, so there is
+nothing to update. Trust evaluation and pinning are in
+[certificate-trust.md](certificate-trust.md).
 
-## Correctness Issues AI Generators Get Wrong
+## Identity
 
-### 1. GenericPassword for Everything
+There is no identity table. The keychain presents an identity whenever a
+certificate's `kSecAttrPublicKeyHash` equals a private key's
+`kSecAttrApplicationLabel` (both the SHA-1 of the public key).
 
-AI code almost universally uses `kSecClassGenericPassword` with `kSecAttrService` for web credentials, completely missing AutoFill integration. The correct pattern uses `kSecClassInternetPassword` with `kSecAttrServer` and associated domains.
+- `SecItemAdd` with `kSecClassIdentity` returns `errSecParam` (-50).
+- Adding a certificate or a key can make an identity appear; deleting either
+  makes it disappear.
 
-### 2. Direct Identity Creation
+Three ways to get one:
 
-Generated code attempts `SecItemAdd` with `kSecClassIdentity` as if it were a storable item class. Identities must be created through PKCS#12 import or by adding matching certificate and key items separately.
-
-### 3. Missing Key Type Attributes
-
-Code omits `kSecAttrKeyType` from key queries, producing ambiguous matches across RSA and EC keys. Since key type is part of the composite primary key, this is a correctness bug, not a style issue.
-
-### 4. ApplicationTag / ApplicationLabel Confusion
-
-Generated code sets `kSecAttrApplicationLabel` as a human-readable string, not understanding it is an auto-generated public key hash used for identity matching. The developer-set tag for lookup is `kSecAttrApplicationTag`.
-
-### 5. No Duplicate Handling
-
-AI code calls `SecItemAdd` without handling `errSecDuplicateItem`. The correct pattern either attempts update-first-then-add, or catches the duplicate error and calls `SecItemUpdate`:
+1. Import a PKCS#12 file with `SecPKCS12Import`, passing the password under
+   `kSecImportExportPassphrase`. Take `kSecImportItemIdentity` from the result,
+   and split it with `SecIdentityCopyCertificate` and
+   `SecIdentityCopyPrivateKey` when you need the parts.
+2. Add the certificate and the private key separately so their hashes match.
+   On macOS both must live in the same implementation (both data protection or
+   both file-based).
+3. On macOS only, `SecIdentityCreateWithCertificate` finds the private key that
+   belongs to a certificate.
 
 ```swift
-// ✅ Update-first pattern (preferred)
-var status = SecItemUpdate(searchQuery as CFDictionary, updateAttrs as CFDictionary)
-if status == errSecItemNotFound {
-    var addQuery = searchQuery
-    addQuery.merge(updateAttrs) { _, new in new }
-    status = SecItemAdd(addQuery as CFDictionary, nil)
+func importClientIdentity(p12: Data, password: String) throws -> SecIdentity {
+    let options = [kSecImportExportPassphrase as String: password]
+    var items: CFArray?
+    let status = SecPKCS12Import(p12 as CFData, options as CFDictionary, &items)
+    guard status == errSecSuccess,
+          let first = (items as? [[String: Any]])?.first,
+          let identity = first[kSecImportItemIdentity as String] else {
+        throw KeychainError(status: status)
+    }
+    return identity as! SecIdentity
 }
 ```
 
-### 6. Missing kSecUseDataProtectionKeychain on macOS
-
-Without this flag, macOS defaults to the legacy file-based keychain, causing `kSecAttrAccessible`, `kSecAttrAccessGroup`, and biometric access controls to be silently ignored or behave unexpectedly.
-
-### 7. Storing Large Blobs in Keychain
-
-The keychain is designed for small secrets. Storing large data degrades performance due to Secure Enclave decryption latency per item retrieval. Use envelope encryption for anything beyond a few KB.
-
----
-
-## Modern API Patterns and Platform Differences
-
-### kSecUseDataProtectionKeychain Unifies Cross-Platform Behavior
-
-On **iOS/tvOS/watchOS**, the data protection keychain is the only implementation  -  this flag is ignored. On **macOS native apps**, `SecItem` defaults to the legacy file-based keychain. Setting `kSecUseDataProtectionKeychain: true` switches to the data protection keychain, giving iOS-identical behavior. On **Mac Catalyst** apps, data protection is the default.
-
-Apple explicitly recommends setting this flag to `true` for all keychain operations. The file-based keychain is on the path to deprecation (`SecKeychainCreate` deprecated in macOS 12).
-
-### TN3137 Key Takeaways
-
-TN3137 documents macOS's **three keychain APIs** (legacy Keychain, SecKeychain, and the recommended SecItem) and **two implementations** (file-based and data protection). Critical routing rule: only `SecItem` can target either implementation; `SecKeychain` always targets file-based. The data protection keychain requires code signing and a provisioning profile on macOS.
-
-Subtle behavioral difference: `SecItemDelete` defaults to `kSecMatchLimitAll` on the data protection keychain (deleting ALL matching items) but `kSecMatchLimitOne` on the file-based keychain  -  an inconsistency documented in Apple's bug tracker (r. 105800863).
-
-### iCloud Keychain Sync Restrictions
-
-`kSecAttrSynchronizable` must be explicitly set to `true`  -  items never sync by default. **All five classes** support sync on iOS 14+ / macOS 11+ / watchOS 7+; earlier versions only sync password classes.
-
-Key restrictions:
-
-- Items with "ThisDeviceOnly" accessibility **cannot** sync  -  combining `kSecAttrSynchronizable: true` with any `ThisDeviceOnly` accessibility returns `errSecParam` (-50)
-- Persistent references are unsupported for synchronizable items
-- tvOS accepts the attribute but never actually syncs
-- Updates and deletes propagate to all copies across devices
-
----
-
-## Size Limits, Performance, and When to Use Files
-
-Apple describes the keychain as storing **"small secrets"** without publishing a hard size limit. The underlying SQLite supports items up to approximately **16 MB** (`SQLITE_MAX_LENGTH`), but this is emphatically not the intended use.
-
-### Performance Architecture
-
-The keychain has a direct performance implication: **metadata is encrypted with a cached Application Processor key** (enabling fast attribute queries), while **secret values require a Secure Enclave round trip** per access. This means `kSecReturnAttributes`-only queries are substantially faster than `kSecReturnData` queries. Always request only what you need.
-
-Query optimization rules:
-
-1. **Use full composite keys**  -  broad queries force `securityd` to perform slow database scans
-2. **Limit matches**  -  use `kSecMatchLimitOne` when expecting a single item to terminate search early
-3. **Fetch metadata first**  -  if you only need to check existence, do not request `kSecReturnData`
-
-### Envelope Encryption for Large Data
-
-For data beyond a few kilobytes, use the **DEK/KEK pattern**: store a 32-byte AES-256 Data Encryption Key (DEK) in the keychain, encrypt the actual data with that key, and write the ciphertext to a file protected by `NSFileProtection`. OWASP MASTG recommends this pattern for MASVS L2 compliance.
-
-Accessibility-to-file-protection mapping:
-
-- `kSecAttrAccessibleWhenUnlocked` → `NSFileProtectionComplete`
-- `kSecAttrAccessibleAfterFirstUnlock` → `NSFileProtectionCompleteUntilFirstUserAuthentication`
-
-### Querying with kSecReturnAttributes for Metadata Inspection
+(`SecIdentity` is a CF type, so the conditional cast always succeeds once the
+value is present; the forced cast is the idiomatic way to bridge it.)
+
+## Mistakes Generated Code Makes
+
+1. A web login saved as a generic password with the domain in the service.
+   AutoFill never offers it. Use an internet password with `kSecAttrServer` and
+   associated domains.
+2. Adding an identity directly. Import PKCS#12, or add certificate and key
+   separately.
+3. Key queries without `kSecAttrKeyType`. Type is part of the key, so an RSA
+   key and an EC key with the same tag are both candidates, and the query can
+   return the wrong one.
+4. Writing a human-readable string into `kSecAttrApplicationLabel`. The lookup
+   attribute is `kSecAttrApplicationTag`.
+5. No duplicate handling. Save with add-or-update:
+
+   ```swift
+   func upsert(match: [String: Any], payload: [String: Any]) throws {
+       let added = SecItemAdd(match.merging(payload) { _, new in new } as CFDictionary, nil)
+       switch added {
+       case errSecSuccess:
+           return
+       case errSecDuplicateItem:
+           let changed = SecItemUpdate(match as CFDictionary, payload as CFDictionary)
+           guard changed == errSecSuccess else { throw KeychainError(status: changed) }
+       default:
+           throw KeychainError(status: added)
+       }
+   }
+   ```
+
+   `match` holds the class and primary-key attributes; `payload` holds the
+   value and the accessibility (accessibility is accepted in an update).
+6. macOS code without `kSecUseDataProtectionKeychain`. It lands in the
+   file-based keychain, which ignores or mishandles `kSecAttrAccessible`,
+   `kSecAttrAccessGroup` and biometric access control.
+7. Large blobs. Every read of `kSecValueData` pays for a Secure Enclave
+   decrypt. Past a few kilobytes, switch to envelope encryption (below).
+
+## Platform Differences
+
+- iOS, tvOS and watchOS have only the data protection keychain;
+  `kSecUseDataProtectionKeychain` is ignored there.
+- A native macOS app defaults to the file-based keychain. Mac Catalyst defaults
+  to the data protection keychain.
+- Apple recommends `kSecUseDataProtectionKeychain: true` on every operation.
+  `SecKeychainCreate` is deprecated as of macOS 12.
+- TN3137 describes three macOS keychain APIs (the legacy Keychain API,
+  `SecKeychain`, and `SecItem`) over two implementations. Only `SecItem` can
+  reach either implementation; `SecKeychain` always works on the file-based one.
+- On a Mac, reaching the data protection keychain needs a code-signed app
+  that carries a provisioning profile.
+- The match limit a delete assumes differs by backend: all matching items on
+  the data protection keychain, only one on the file-based keychain
+  (reported to Apple as bug 105800863). Write delete queries that are precise
+  enough for either.
+
+### Synchronization
+
+- Items sync only when `kSecAttrSynchronizable` is set to `true`. Nothing syncs
+  by default.
+- Every one of the five classes can sync from iOS 14, macOS 11 and watchOS 7; before
+  that, only the two password classes.
+- A synchronizable item cannot use an accessibility value ending in
+  `ThisDeviceOnly`. Apple documents the combination as not allowed, and the add
+  fails with `errSecParam` (-50).
+- Synchronizable items cannot be fetched through persistent references.
+- tvOS accepts the attribute and never syncs.
+- Updating or deleting a synced item changes it on every device.
+
+Access groups and iCloud Keychain are covered in
+[keychain-sharing.md](keychain-sharing.md).
+
+## Size and When to Use a File
+
+Apple publishes no hard limit and describes the keychain as a place for small
+secrets. The SQLite column limit (`SQLITE_MAX_LENGTH`, about 16 MB) is not an
+invitation.
+
+- Query with the full composite key, use `kSecMatchLimitOne` when you expect
+  one item, and skip `kSecReturnData` when you only need to know an item exists.
+- For bulk data, use envelope encryption: keep a data encryption key (AES-256,
+  32 bytes) in the keychain, encrypt the payload with it, and write the
+  ciphertext to a file that also has `NSFileProtection` set. OWASP MASTG
+  recommends this layout for MASVS L2.
+- File protection counterparts: `kSecAttrAccessibleWhenUnlocked` matches
+  `NSFileProtectionComplete`; `kSecAttrAccessibleAfterFirstUnlock` matches
+  `NSFileProtectionCompleteUntilFirstUserAuthentication`.
+
+Requesting data and attributes together returns a dictionary:
 
 ```swift
-// ✅ Inspect all metadata for a GenericPassword item
-let query: [String: Any] = [
-    kSecClass as String: kSecClassGenericPassword,
-    kSecAttrService as String: "com.myapp.api",
-    kSecReturnAttributes as String: true,
-    kSecReturnData as String: true,
-    kSecMatchLimit as String: kSecMatchLimitOne
-]
-var item: CFTypeRef?
-let status = SecItemCopyMatching(query as CFDictionary, &item)
-guard status == errSecSuccess, let attrs = item as? [String: Any] else { return }
-
-// Available metadata in the returned dictionary:
-let account = attrs[kSecAttrAccount as String] as? String
-let service = attrs[kSecAttrService as String] as? String
-let created = attrs[kSecAttrCreationDate as String] as? Date
-let modified = attrs[kSecAttrModificationDate as String] as? Date
-let accessible = attrs[kSecAttrAccessible as String] as? String
-let syncable = attrs[kSecAttrSynchronizable as String] as? Bool
-let secretData = attrs[kSecValueData as String] as? Data
+func describeLicense() throws -> [String: Any]? {
+    let query: [String: Any] = [
+        kSecClass as String: kSecClassGenericPassword,
+        kSecAttrService as String: "com.example.editor",
+        kSecAttrAccount as String: "license",
+        kSecReturnAttributes as String: true,
+        kSecReturnData as String: true,
+        kSecMatchLimit as String: kSecMatchLimitOne
+    ]
+    var out: CFTypeRef?
+    let status = SecItemCopyMatching(query as CFDictionary, &out)
+    if status == errSecItemNotFound { return nil }
+    guard status == errSecSuccess else { throw KeychainError(status: status) }
+    return out as? [String: Any]
+}
 ```
 
-When both `kSecReturnAttributes` and `kSecReturnData` are true with `kSecMatchLimitOne`, the result is a single dictionary containing all metadata plus the secret data under `kSecValueData`. With `kSecMatchLimitAll`, it is an array of such dictionaries.
-
----
+The dictionary includes the account (`acct`), service (`svce`), creation and
+modification dates, accessibility, the synchronizable flag, and the secret
+under `kSecValueData`. Read them with the `kSec...` constants, not the short
+strings. Switch to `kSecMatchLimitAll` and you get back a list of them.
 
-## Testing Matrix for Class Correctness
+## Tests That Prove the Class Is Right
 
-| Test Scenario                                            | Expected OSStatus              | Rationale                                         |
-| -------------------------------------------------------- | ------------------------------ | ------------------------------------------------- |
-| Add `kSecClassIdentity` via `SecItemAdd`                 | `errSecParam` (-50)            | Identities must be imported, not created directly |
-| Add `kSecClassKey` without `kSecAttrKeyType`             | `errSecParam` (-50)            | Crypto metadata is strictly required              |
-| Add item with identical composite primary key            | `errSecDuplicateItem` (-25299) | Requires `SecItemUpdate` or delete-then-add       |
-| Sync `true` + `ThisDeviceOnly` accessibility             | `errSecParam` (-50)            | Contradictory constraints                         |
-| Use `kSecAttrApplicationTag` with `kSecClassCertificate` | `errSecParam` (-50)            | Tag is only valid for key items                   |
-| Query `kSecClassKey` without `kSecAttrKeyClass`          | May return wrong key class     | Ambiguous match across public/private/symmetric   |
+| Action | Expected status |
+| --- | --- |
+| Add with `kSecClassIdentity` | `errSecParam` |
+| Add a key without `kSecAttrKeyType` | `errSecParam` |
+| Add twice with the same primary key | `errSecDuplicateItem` |
+| Add with synchronizable `true` and a `ThisDeviceOnly` value | `errSecParam` |
+| Add a certificate with `kSecAttrApplicationTag` | `errSecParam` |
+| Query a key without `kSecAttrKeyClass` | may match the wrong class |
 
----
+The harness for these tests is in
+[testing-security-code.md](testing-security-code.md).
 
-## Migration: GenericPassword to InternetPassword
-
-If your application currently stores web credentials as `kSecClassGenericPassword`, migrate to `kSecClassInternetPassword` to enable AutoFill:
+## Moving Web Logins to Internet Passwords
 
 ```swift
-// ✅ Migration pattern: GenericPassword → InternetPassword
-func migrateWebCredentials() throws {
-    // 1. Query existing GenericPassword items for web credentials
-    let oldQuery: [String: Any] = [
+func promoteWebLogins(oldService: String, host: String) throws {
+    let find: [String: Any] = [
         kSecClass as String: kSecClassGenericPassword,
-        kSecAttrService as String: "www.example.com",
+        kSecAttrService as String: oldService,
         kSecReturnAttributes as String: true,
         kSecReturnData as String: true,
         kSecMatchLimit as String: kSecMatchLimitAll
     ]
-
-    var items: CFTypeRef?
-    let fetchStatus = SecItemCopyMatching(oldQuery as CFDictionary, &items)
-    guard fetchStatus == errSecSuccess,
-          let results = items as? [[String: Any]] else { return }
-
-    for item in results {
-        guard let account = item[kSecAttrAccount as String] as? String,
-              let data = item[kSecValueData as String] as? Data else { continue }
-
-        // 2. Add as InternetPassword with proper attributes
-        let newQuery: [String: Any] = [
+    var out: CFTypeRef?
+    let status = SecItemCopyMatching(find as CFDictionary, &out)
+    if status == errSecItemNotFound { return }
+    guard status == errSecSuccess, let rows = out as? [[String: Any]] else {
+        throw KeychainError(status: status)
+    }
+    for row in rows {
+        guard let user = row[kSecAttrAccount as String] as? String,
+              let secret = row[kSecValueData as String] as? Data else { continue }
+        let match: [String: Any] = [
             kSecClass as String: kSecClassInternetPassword,
-            kSecAttrServer as String: "www.example.com",
+            kSecAttrServer as String: host,
             kSecAttrProtocol as String: kSecAttrProtocolHTTPS,
-            kSecAttrAccount as String: account,
-            kSecValueData as String: data,
+            kSecAttrAccount as String: user,
             kSecUseDataProtectionKeychain as String: true
         ]
-        let addStatus = SecItemAdd(newQuery as CFDictionary, nil)
-        guard addStatus == errSecSuccess || addStatus == errSecDuplicateItem else { continue }
-
-        // 3. Delete old GenericPassword item
-        let deleteQuery: [String: Any] = [
+        try upsert(match: match, payload: [
+            kSecValueData as String: secret,
+            kSecAttrAccessible as String: kSecAttrAccessibleWhenUnlocked
+        ])
+        let removeOld: [String: Any] = [
             kSecClass as String: kSecClassGenericPassword,
-            kSecAttrService as String: "www.example.com",
-            kSecAttrAccount as String: account
+            kSecAttrService as String: oldService,
+            kSecAttrAccount as String: user
         ]
-        SecItemDelete(deleteQuery as CFDictionary)
+        let removed = SecItemDelete(removeOld as CFDictionary)
+        guard removed == errSecSuccess || removed == errSecItemNotFound else {
+            throw KeychainError(status: removed)
+        }
     }
 }
 ```
 
----
-
-## Cross-Reference Index
-
-- **SecItem CRUD operations, query dictionaries, error handling** → `keychain-fundamentals.md`
-- **Accessibility constants, SecAccessControl flags** → `keychain-access-control.md`
-- **Biometric protection for keys and passwords** → `biometric-authentication.md`
-- **Secure Enclave key generation and constraints** → `secure-enclave.md`
-- **CryptoKit key types and keychain storage mapping** → `cryptokit-symmetric.md`, `cryptokit-public-key.md`
-- **OAuth tokens, API keys, credential lifecycle** → `credential-storage-patterns.md`
-- **Access groups, app extensions, sharing** → `keychain-sharing.md`
-- **SecCertificate, SecTrust, trust evaluation** → `certificate-trust.md`
-- **Legacy migration patterns** → `migration-legacy-stores.md`
-- **AI-generated code anti-patterns** → `common-anti-patterns.md`
-- **OWASP MASVS/MASTG compliance** → `compliance-owasp-mapping.md`
-
----
-
-## Conclusion
-
-The keychain's five classes form a precise taxonomy: GenericPassword for app-local secrets, InternetPassword for domain-associated credentials enabling AutoFill, Key for cryptographic material with its tag/label distinction, Certificate for public X.509 data, and Identity as a virtual construct emerging from matching certificate and key items. The most impactful decisions are choosing InternetPassword over GenericPassword for web credentials, always setting `kSecUseDataProtectionKeychain` for cross-platform consistency, understanding that identities cannot be directly created, and recognizing `kSecAttrApplicationTag` (developer-set, for lookup) versus `kSecAttrApplicationLabel` (system-generated, for identity matching) as fundamentally different attributes despite their similar names.
-
----
-
-## Summary Checklist
-
-1. **Correct class selection**  -  Use `kSecClassInternetPassword` (not GenericPassword) for any credential associated with a web domain to enable AutoFill
-2. **Composite primary key completeness**  -  Include all primary key attributes for the chosen class to avoid `errSecDuplicateItem` collisions and query misses
-3. **kSecAttrGeneric is NOT a primary key**  -  Do not rely on it for uniqueness in GenericPassword items; it causes asymmetric add/query behavior
-4. **ApplicationTag vs ApplicationLabel**  -  Use `kSecAttrApplicationTag` (developer-set, CFData) for key lookup; never manually set `kSecAttrApplicationLabel` (system-generated hash for identity formation)
-5. **Identity creation via import**  -  Never `SecItemAdd` with `kSecClassIdentity`; use `SecPKCS12Import` or add matching certificate + key pairs separately
-6. **Key type and size required**  -  Always specify `kSecAttrKeyType` and `kSecAttrKeySizeInBits` when creating or querying `kSecClassKey` items
-7. **kSecUseDataProtectionKeychain on macOS**  -  Set to `true` for all operations to get iOS-identical behavior and avoid silent legacy keychain fallback
-8. **Sync and accessibility agreement**  -  Never combine `kSecAttrSynchronizable: true` with "ThisDeviceOnly" accessibility values
-9. **Small secrets only**  -  Use envelope encryption (DEK in keychain, ciphertext in `NSFileProtection`-guarded file) for data beyond a few KB
-10. **Certificate attributes**  -  Never use `kSecAttrApplicationTag` with `kSecClassCertificate`; let the system extract metadata via `kSecValueRef`
-11. **Duplicate handling**  -  Always handle `errSecDuplicateItem` with an update-first-then-add or delete-then-add pattern
+The old item is removed only after the new one was written. Broader migration
+guidance is in [migration-legacy-stores.md](migration-legacy-stores.md).
+
+## Checklist
+
+- Web-domain credentials are internet passwords.
+- Every primary-key attribute for the class is set.
+- Nothing depends on `kSecAttrGeneric` for uniqueness.
+- Keys are found by `kSecAttrApplicationTag`; `kSecAttrApplicationLabel` is left
+  to the system.
+- Identities come from `SecPKCS12Import` or a matching certificate and key.
+- Key items always state type and size.
+- macOS code sets `kSecUseDataProtectionKeychain: true`.
+- Synchronizable items never use a `ThisDeviceOnly` accessibility value.
+- Only small secrets go in the keychain; larger data uses envelope encryption.
+- Certificates carry no application tag and get their metadata from
+  `kSecValueRef`.
+- `errSecDuplicateItem` leads to `SecItemUpdate` (add, then update).
+
+## Related Files
+
+[keychain-fundamentals.md](keychain-fundamentals.md),
+[keychain-access-control.md](keychain-access-control.md),
+[biometric-authentication.md](biometric-authentication.md),
+[credential-storage-patterns.md](credential-storage-patterns.md),
+[common-anti-patterns.md](common-anti-patterns.md),
+[compliance-owasp-mapping.md](compliance-owasp-mapping.md).