@mmerterden/multi-agent-pipeline 8.6.1 → 10.0.6

package/pipeline/skills/shared/external/authentication/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: authentication
-description: "Implement iOS authentication patterns including Sign in with Apple (ASAuthorizationAppleIDProvider, ASAuthorizationController, ASAuthorizationAppleIDCredential), credential state checking, identity token validation, ASWebAuthenticationSession for OAuth and third-party auth flows, ASAuthorizationPasswordProvider for AutoFill credential suggestions, and biometric authentication with LAContext. Use when implementing Sign in with Apple, handling Apple ID credentials, building OAuth login flows, integrating Password AutoFill, checking credential revocation state, or validating identity tokens server-side."
+description: "Implement iOS authentication flows with AuthenticationServices and LocalAuthentication. Use when building Sign in with Apple, passkey/WebAuthn registration or sign-in with ASAuthorizationPlatformPublicKeyCredentialProvider, ASAuthorizationController credential state and revocation handling, ASWebAuthenticationSession OAuth or third-party login, Password AutoFill, identity-token server validation, or local biometric re-authentication with LAContext."
 ---
 
 # Authentication
 
 Implement authentication flows on iOS using the AuthenticationServices
-framework, including Sign in with Apple, OAuth/third-party web auth,
-Password AutoFill, and biometric authentication.
+framework, including Sign in with Apple, passkeys, OAuth/third-party web
+auth, Password AutoFill, and biometric re-authentication.
 
 ## Contents
 
@@ -16,9 +16,11 @@ Password AutoFill, and biometric authentication.
 - [Credential State Checking](#credential-state-checking)
 - [Token Validation](#token-validation)
 - [Existing Account Setup Flows](#existing-account-setup-flows)
+- [Passkeys](#passkeys)
 - [ASWebAuthenticationSession (OAuth)](#aswebauthenticationsession-oauth)
 - [Password AutoFill Credentials](#password-autofill-credentials)
 - [Biometric Authentication](#biometric-authentication)
+- [Security Boundaries](#security-boundaries)
 - [SwiftUI SignInWithAppleButton](#swiftui-signinwithapplebutton)
 - [Common Mistakes](#common-mistakes)
 - [Review Checklist](#review-checklist)
@@ -110,9 +112,9 @@ extension LoginViewController: ASAuthorizationControllerDelegate {
 | `user` | `String` | Always | Always |
 | `email` | `String?` | Provided if requested | `nil` |
 | `fullName` | `PersonNameComponents?` | Provided if requested | `nil` |
-| `identityToken` | `Data?` | JWT (Base64) | JWT (Base64) |
+| `identityToken` | `Data?` | JWT encoded as UTF-8 data | JWT encoded as UTF-8 data |
 | `authorizationCode` | `Data?` | Short-lived code | Short-lived code |
-| `realUserStatus` | `ASUserDetectionStatus` | `.likelyReal` / `.unknown` | `.unknown` |
+| `realUserStatus` | `ASUserDetectionStatus` | Fraud-prevention signal | Do not rely on later attempts |
 
 **Critical:** `email` and `fullName` are provided ONLY on the first
 authorization. Cache them immediately during the initial sign-up flow. If the
@@ -140,33 +142,31 @@ Check credential state on every app launch. The user may revoke access at
 any time via Settings > Apple Account > Sign-In & Security.
 
 ```swift
-func checkCredentialState() async {
+func checkCredentialState() {
     let provider = ASAuthorizationAppleIDProvider()
     guard let userID = loadSavedUserID() else {
         showLoginScreen()
         return
     }
 
-    do {
-        let state = try await provider.credentialState(forUserID: userID)
-        switch state {
-        case .authorized:
-            proceedToMainApp()
-        case .revoked:
-            // User revoked -- sign out and clear local data
-            signOut()
-            showLoginScreen()
-        case .notFound:
-            showLoginScreen()
-        case .transferred:
-            // App transferred to new team -- migrate user identifier
-            migrateUser()
-        @unknown default:
-            showLoginScreen()
+    provider.getCredentialState(forUserID: userID) { state, _ in
+        DispatchQueue.main.async {
+            switch state {
+            case .authorized:
+                proceedToMainApp()
+            case .revoked:
+                // User revoked -- sign out and clear local data
+                signOut()
+                showLoginScreen()
+            case .notFound:
+                showLoginScreen()
+            case .transferred:
+                // App transferred to new team -- migrate user identifier
+                migrateUser()
+            @unknown default:
+                showLoginScreen()
+            }
         }
-    } catch {
-        // Network error -- allow offline access or retry
-        proceedToMainApp()
     }
 }
 ```
@@ -244,6 +244,58 @@ Call this in `viewDidAppear` or on app launch. If no existing credentials
 are found, the delegate receives a `.notInteractive` error -- handle it
 silently and show your normal login UI.
 
+## Passkeys
+
+Use passkeys for passwordless WebAuthn-style registration and sign-in. The
+app must have an Associated Domains entitlement for the relying party domain
+using the `webcredentials:` service; passkey requests fail for services the app
+has not configured as associated domains.
+
+For platform passkeys synced through iCloud Keychain, request a server-provided
+challenge and create requests with `ASAuthorizationPlatformPublicKeyCredentialProvider`:
+
+```swift
+let challenge: Data = try await server.registrationChallenge()
+let userID: Data = try await server.passkeyUserID()
+let provider = ASAuthorizationPlatformPublicKeyCredentialProvider(
+    relyingPartyIdentifier: "example.com"
+)
+let request = provider.createCredentialRegistrationRequest(
+    challenge: challenge,
+    name: username,
+    userID: userID
+)
+
+let controller = ASAuthorizationController(authorizationRequests: [request])
+controller.delegate = self
+controller.presentationContextProvider = self
+controller.performRequests()
+```
+
+For sign-in, use `createCredentialAssertionRequest(challenge:)` with a fresh
+server challenge, then send the resulting registration or assertion object to
+the relying-party server for verification:
+
+```swift
+let request = provider.createCredentialAssertionRequest(challenge: challenge)
+
+switch authorization.credential {
+case let registration as ASAuthorizationPlatformPublicKeyCredentialRegistration:
+    try await server.finishPasskeyRegistration(registration)
+case let assertion as ASAuthorizationPlatformPublicKeyCredentialAssertion:
+    try await server.finishPasskeySignIn(assertion)
+default:
+    break
+}
+```
+
+For inline passkey suggestions, set the username field's `textContentType` to
+`.username`, include the passkey assertion request in the controller, and call
+`performAutoFillAssistedRequests()`. Use `ASAuthorizationSecurityKeyPublicKeyCredentialProvider`
+only when the user must authenticate with a physical security key. See
+[references/passkeys.md](references/passkeys.md) for complete registration,
+assertion, AutoFill, and security-key patterns.
+
 ## ASWebAuthenticationSession (OAuth)
 
 Use `ASWebAuthenticationSession` for OAuth and third-party authentication
@@ -253,6 +305,12 @@ Use `ASWebAuthenticationSession` for OAuth and third-party authentication
 import AuthenticationServices
 
 final class OAuthController: NSObject, ASWebAuthenticationPresentationContextProviding {
+    private weak var presentationAnchor: ASPresentationAnchor?
+
+    init(presentationAnchor: ASPresentationAnchor) {
+        self.presentationAnchor = presentationAnchor
+    }
+
     func startOAuthFlow() {
         let authURL = URL(string:
             "https://provider.com/oauth/authorize?client_id=YOUR_ID&redirect_uri=myapp://callback&response_type=code"
@@ -271,33 +329,18 @@ final class OAuthController: NSObject, ASWebAuthenticationPresentationContextPro
     }
 
     func presentationAnchor(for session: ASWebAuthenticationSession) -> ASPresentationAnchor {
-        ASPresentationAnchor()
-    }
-}
-```
-
-### SwiftUI WebAuthenticationSession
-
-```swift
-struct OAuthLoginView: View {
-    @Environment(\.webAuthenticationSession) private var webAuthSession
-
-    var body: some View {
-        Button("Sign in with Provider") {
-            Task {
-                let url = URL(string: "https://provider.com/oauth/authorize?client_id=YOUR_ID")!
-                let callbackURL = try await webAuthSession.authenticate(
-                    using: url, callback: .customScheme("myapp")
-                )
-                // Extract authorization code from callbackURL
-            }
+        guard let presentationAnchor else {
+            fatalError("ASWebAuthenticationSession needs the active window")
         }
+        return presentationAnchor
     }
 }
 ```
 
-Callback types: `.customScheme("myapp")` for URL scheme redirects;
-`.https(host:path:)` for universal link redirects (preferred).
+In SwiftUI, use `@Environment(\.webAuthenticationSession)` and call
+`authenticate(using:callback:preferredBrowserSession:additionalHeaderFields:)`
+with `.customScheme("myapp")` or `.https(host:path:)`; prefer `.ephemeral`
+only when the provider flow should avoid shared browser cookies.
 
 ## Password AutoFill Credentials
 
@@ -348,10 +391,11 @@ passwordField.textContentType = .password
 
 ## Biometric Authentication
 
-Use `LAContext` from LocalAuthentication for Face ID / Touch ID as a
-sign-in or re-authentication mechanism. For protecting Keychain items
-with biometric access control (`SecAccessControl`, `.biometryCurrentSet`),
-see the `ios-security` skill.
+Use `LAContext` from LocalAuthentication for local re-authentication before
+showing account settings or starting sensitive actions. Do not treat a returned
+`Bool` as proof to unlock a stored secret; protect secrets with Keychain access
+control instead. See [references/keychain-biometric.md](references/keychain-biometric.md)
+for `SecAccessControl` and `.biometryCurrentSet` patterns.
 
 ```swift
 import LocalAuthentication
@@ -376,102 +420,48 @@ func authenticateWithBiometrics() async throws -> Bool {
 **Required:** Add `NSFaceIDUsageDescription` to Info.plist. Missing this
 key crashes on Face ID devices.
 
-## SwiftUI SignInWithAppleButton
-
-```swift
-import AuthenticationServices
-
-struct AppleSignInView: View {
-    @Environment(\.colorScheme) var colorScheme
-
-    var body: some View {
-        SignInWithAppleButton(.signIn) { request in
-            request.requestedScopes = [.fullName, .email]
-        } onCompletion: { result in
-            switch result {
-            case .success(let authorization):
-                guard let credential = authorization.credential
-                    as? ASAuthorizationAppleIDCredential else { return }
-                handleCredential(credential)
-            case .failure(let error):
-                handleError(error)
-            }
-        }
-        .signInWithAppleButtonStyle(
-            colorScheme == .dark ? .white : .black
-        )
-        .frame(height: 50)
-    }
-}
-```
-
-## Common Mistakes
-
-### 1. Not checking credential state on app launch
-
-```swift
-// DON'T: Assume the user is still authorized
-func appDidLaunch() {
-    if UserDefaults.standard.bool(forKey: "isLoggedIn") {
-        showMainApp()  // User may have revoked access!
-    }
-}
-
-// DO: Check credential state every launch
-func appDidLaunch() async {
-    await checkCredentialState()  // See "Credential State Checking" above
-}
-```
-
-### 2. Not performing existing account setup flows
-
-```swift
-// DON'T: Always show a full login screen on launch
-// DO: Call performExistingAccountSetupFlows() first;
-//     show login UI only if .notInteractive error received
-```
+## Security Boundaries
 
-### 3. Assuming email/name are always provided
+This skill owns user-facing account authentication: Sign in with Apple,
+passkeys, Password AutoFill, ASAuthorizationController, OAuth session
+presentation, credential state, and local biometric re-authentication. Route
+deep security work to `swift-security`: Keychain architecture/migration,
+CryptoKit, Secure Enclave, certificate pinning/trust, keychain sharing, storage
+hardening, and OWASP MASVS/MASTG. Keep only the storage minimum here: tokens and
+secrets belong in Keychain; `LAContext.evaluatePolicy` alone must not release
+protected secrets.
 
-```swift
-// DON'T: Force-unwrap email or fullName
-let email = credential.email!  // Crashes on subsequent logins
-
-// DO: Handle nil gracefully -- only available on first authorization
-if let email = credential.email {
-    saveEmail(email)  // Persist immediately
-}
-```
-
-### 4. Not implementing ASAuthorizationControllerPresentationContextProviding
-
-```swift
-// DON'T: Skip the presentation context provider
-controller.delegate = self
-controller.performRequests()  // May not display UI correctly
-
-// DO: Always set the presentation context provider
-controller.delegate = self
-controller.presentationContextProvider = self  // Required for proper UI
-controller.performRequests()
-```
+## SwiftUI SignInWithAppleButton
 
-### 5. Storing identityToken in UserDefaults
+Use `SignInWithAppleButton` in SwiftUI views when the login surface is SwiftUI.
+Request `.fullName` and `.email`, handle `.success` and `.failure`, downcast to
+`ASAuthorizationAppleIDCredential`, and send the credential through the same
+server-validation flow as UIKit. Style with `.signInWithAppleButtonStyle(...)`.
 
-```swift
-// DON'T: Store tokens in UserDefaults
-UserDefaults.standard.set(tokenString, forKey: "identityToken")
+## Common Mistakes
 
-// DO: Store in Keychain
-// See references/keychain-biometric.md for Keychain patterns
-try KeychainHelper.save(tokenData, forKey: "identityToken")
-```
+- Assuming a saved local session means the Apple ID credential is still valid.
+  Check credential state at launch and handle revocation notifications.
+- Showing a full login screen before trying existing account setup flows.
+  Treat `.notInteractive` as the normal "no local credential" path.
+- Force-unwrapping `email` or `fullName`. Cache them on first authorization and
+  handle `nil` later.
+- Creating an `ASAuthorizationController` without a presentation context
+  provider. Authorization UI needs the active presentation anchor.
+- Storing identity tokens, authorization codes, access tokens, passwords, or
+  passkey server state in `UserDefaults`, files, or Core Data. Store secrets in
+  Keychain and keep relying-party passkey verification server-side.
+- Adding passkey requests without `webcredentials:` Associated Domains for the
+  relying-party domain, or trying to use app-native passkeys for unrelated
+  websites.
+- Expanding authentication work into CryptoKit, Secure Enclave, certificate
+  pinning, or OWASP MASVS. Route those to `swift-security`.
 
 ## Review Checklist
 
 - [ ] "Sign in with Apple" capability added in Xcode project
 - [ ] `ASAuthorizationControllerPresentationContextProviding` implemented
-- [ ] Credential state checked on every app launch (`credentialState(forUserID:)`)
+- [ ] Credential state checked on every app launch (`getCredentialState(forUserID:completion:)`)
 - [ ] `credentialRevokedNotification` observer registered; sign-out handled
 - [ ] `email` and `fullName` cached on first authorization (not assumed available later)
 - [ ] `identityToken` sent to server for validation, not trusted client-side only
@@ -482,15 +472,21 @@ try KeychainHelper.save(tokenData, forKey: "identityToken")
 - [ ] `ASWebAuthenticationSession` used for OAuth (not `WKWebView`)
 - [ ] `prefersEphemeralWebBrowserSession` set for OAuth when appropriate
 - [ ] `textContentType` set on username/password fields for AutoFill
+- [ ] Passkey relying party has `webcredentials:` Associated Domains configured
+- [ ] Passkey registration/assertion challenges come from the server and are verified server-side
+- [ ] Deep Keychain, CryptoKit, Secure Enclave, certificate pinning, and MASVS work routed to `swift-security`
 
 ## References
 
-- Keychain & biometric patterns: `references/keychain-biometric.md`
+- Keychain & biometric patterns: [references/keychain-biometric.md](references/keychain-biometric.md)
+- Passkey patterns: [references/passkeys.md](references/passkeys.md)
 - [AuthenticationServices](https://sosumi.ai/documentation/authenticationservices)
 - [ASAuthorizationAppleIDProvider](https://sosumi.ai/documentation/authenticationservices/asauthorizationappleidprovider)
 - [ASAuthorizationAppleIDCredential](https://sosumi.ai/documentation/authenticationservices/asauthorizationappleidcredential)
 - [ASAuthorizationController](https://sosumi.ai/documentation/authenticationservices/asauthorizationcontroller)
 - [ASWebAuthenticationSession](https://sosumi.ai/documentation/authenticationservices/aswebauthenticationsession)
+- [Supporting passkeys](https://sosumi.ai/documentation/authenticationservices/supporting-passkeys)
+- [ASAuthorizationPlatformPublicKeyCredentialProvider](https://sosumi.ai/documentation/authenticationservices/asauthorizationplatformpublickeycredentialprovider)
 - [ASAuthorizationPasswordProvider](https://sosumi.ai/documentation/authenticationservices/asauthorizationpasswordprovider)
 - [SignInWithAppleButton](https://sosumi.ai/documentation/authenticationservices/signinwithapplebutton)
 - [Implementing User Authentication with Sign in with Apple](https://sosumi.ai/documentation/authenticationservices/implementing-user-authentication-with-sign-in-with-apple)

package/pipeline/skills/shared/external/authentication/evals/evals.json

@@ -0,0 +1,48 @@
+{
+  "skill_name": "authentication",
+  "evals": [
+    {
+      "id": 0,
+      "name": "passkey-registration-and-signin",
+      "prompt": "We're adding passwordless sign-in to our iOS app for accounts on example.com. The server can mint WebAuthn challenges, and product wants passkeys first, a physical security key fallback, and inline suggestions in the username field. What should the implementation checklist and core AuthenticationServices flow look like?",
+      "expected_output": "A passkey implementation checklist that covers associated domains, platform passkey registration/assertion, AutoFill-assisted requests, physical security key boundaries, and server-side verification.",
+      "files": [],
+      "expectations": [
+        "Names the Associated Domains requirement with the `webcredentials:` service for the relying-party domain.",
+        "Uses `ASAuthorizationPlatformPublicKeyCredentialProvider(relyingPartyIdentifier:)` for platform passkeys and distinguishes registration from assertion requests.",
+        "States that registration and assertion challenges come from the relying-party server and that passkey results must be verified server-side before issuing a session.",
+        "Mentions `performAutoFillAssistedRequests()` with a username text field using `.username` for inline passkey suggestions.",
+        "Uses `ASAuthorizationSecurityKeyPublicKeyCredentialProvider` only for physical security key fallback, not as the default platform passkey provider."
+      ]
+    },
+    {
+      "id": 1,
+      "name": "sign-in-with-apple-oauth-review",
+      "prompt": "Review this iOS login plan before implementation: Sign in with Apple for new accounts, saved password suggestions for returning users, GitHub OAuth, cached account profile data, local Face ID re-auth before account deletion, and token storage. What are the must-have AuthenticationServices and LocalAuthentication checks?",
+      "expected_output": "A review checklist that covers Sign in with Apple setup, credential handling, existing account flows, OAuth session presentation, biometric re-auth boundaries, and secure token storage.",
+      "files": [],
+      "expectations": [
+        "Requires the Sign in with Apple capability plus `ASAuthorizationControllerPresentationContextProviding` for authorization UI.",
+        "Explains that `email` and `fullName` must be cached during first authorization and handled as optional later.",
+        "Requires Apple ID credential state checks with `getCredentialState(forUserID:completion:)` and handling credential revocation notifications.",
+        "Sends `identityToken` and `authorizationCode` to the server for validation instead of trusting them only on device.",
+        "Uses `ASWebAuthenticationSession` for GitHub OAuth, avoids `WKWebView`, and returns a real active presentation anchor.",
+        "Stores secrets in Keychain and treats `LAContext.evaluatePolicy` as local re-authentication rather than standalone proof for releasing stored secrets."
+      ]
+    },
+    {
+      "id": 2,
+      "name": "security-boundary-routing",
+      "prompt": "A team asks the authentication skill to design the whole account security layer: Sign in with Apple, passkeys, refresh-token storage, CryptoKit encryption, certificate pinning, biometric unlock, and OWASP MASVS mapping. Give a concise scope review that says what this skill should cover and what belongs in sibling security work.",
+      "expected_output": "A boundary-aware scope review that keeps AuthenticationServices auth flows in scope while routing deep Keychain, CryptoKit, certificate trust, and compliance work to the security skill.",
+      "files": [],
+      "expectations": [
+        "Keeps Sign in with Apple, passkeys, Password AutoFill, ASAuthorizationController flows, ASWebAuthenticationSession OAuth, and local biometric re-authentication in the authentication skill scope.",
+        "Routes detailed Keychain architecture, CryptoKit encryption, Secure Enclave, certificate pinning, and OWASP MASVS mapping to the sibling security skill instead of expanding the authentication answer into those domains.",
+        "Still states that auth tokens and secrets should be stored in Keychain, not UserDefaults, files, or Core Data.",
+        "Warns that `LAContext.evaluatePolicy` alone should not release stored secrets and that Keychain access control is the right handoff for protected token/key reads.",
+        "Does not claim that the authentication skill owns backend WebAuthn relying-party implementation beyond requiring server challenges and server verification."
+      ]
+    }
+  ]
+}

package/pipeline/skills/shared/external/authentication/references/keychain-biometric.md

@@ -1,19 +1,25 @@
 # Keychain Token Storage & Biometric Authentication
 
 Self-contained reference for storing authentication tokens in Keychain and
-protecting them with biometric authentication (Face ID / Touch ID). Covers
-the patterns most commonly needed alongside Sign in with Apple and OAuth flows.
+protecting them with Keychain-bound biometric authentication (Face ID /
+Touch ID). Covers the patterns most commonly needed alongside Sign in with
+Apple, passkey, and OAuth flows.
+
+This is an authentication-adjacent quick reference, not a full security
+architecture guide. Route Keychain migration, access-control policy design,
+CryptoKit encryption, Secure Enclave keys, certificate pinning, keychain
+sharing, storage-hardening strategy, and OWASP MASVS/MASTG mapping to
+`swift-security`.
 
 ## Contents
 
 - [Storing Tokens in Keychain](#storing-tokens-in-keychain)
 - [Reading Tokens from Keychain](#reading-tokens-from-keychain)
 - [Deleting Tokens from Keychain](#deleting-tokens-from-keychain)
-- [kSecAttrAccessible Values](#ksecattracccessible-values)
 - [Biometric Authentication with LAContext](#biometric-authentication-with-lacontext)
 - [Biometric-Protected Keychain Items](#biometric-protected-keychain-items)
-- [SecAccessControl Flags](#secaccesscontrol-flags)
 - [Keychain Error Handling](#keychain-error-handling)
+- [References](#references)
 
 ## Storing Tokens in Keychain
 
@@ -88,26 +94,23 @@ func deleteFromKeychain(account: String, service: String) throws {
 }
 ```
 
-## kSecAttrAccessible Values
+Use a `ThisDeviceOnly` accessibility class for sensitive app credentials unless
+the product explicitly requires restore or sharing behavior. Choose broader
+Keychain accessibility, migration, or sharing strategy in `swift-security`, not
+in this authentication skill.
 
-| Value | When Available | Device-Only | Use For |
-|---|---|---|---|
-| `kSecAttrAccessibleWhenUnlocked` | Device unlocked | No | General credentials |
-| `kSecAttrAccessibleWhenUnlockedThisDeviceOnly` | Device unlocked | Yes | Sensitive credentials |
-| `kSecAttrAccessibleAfterFirstUnlock` | After first unlock | No | Background-accessible tokens |
-| `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly` | After first unlock | Yes | Background tokens, no backup |
-| `kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly` | Passcode set + unlocked | Yes | Highest security |
+Do not use `kSecAttrAccessibleAlways` for app credentials; Apple marks it as not
+recommended for application use because items remain accessible regardless of
+lock state.
 
-Rules:
-- Use `ThisDeviceOnly` variants for sensitive data. Prevents backup/restore to other devices.
-- Use `AfterFirstUnlock` for tokens needed by background operations.
-- Use `WhenPasscodeSetThisDeviceOnly` for most sensitive data. Item is deleted if passcode is removed.
-- NEVER use `kSecAttrAccessibleAlways` (deprecated and insecure).
 
 ## Biometric Authentication with LAContext
 
 Use `LAContext` from LocalAuthentication for Face ID / Touch ID prompts before
-accessing sensitive data or performing protected actions.
+showing sensitive screens or performing protected actions. This is a local
+interaction gate, not proof that a stored secret is safe to release. For tokens,
+private keys, or high-value credentials, bind access to the Keychain item with
+`SecAccessControl` and let `SecItemCopyMatching` perform the authentication.
 
 ```swift
 import LocalAuthentication
@@ -172,22 +175,36 @@ let query: [String: Any] = [
     kSecClass as String: kSecClassGenericPassword,
     kSecAttrAccount as String: "auth-token",
     kSecValueData as String: tokenData,
-    kSecAttrAccessControl as String: access,
-    kSecUseAuthenticationContext as String: LAContext()
+    kSecAttrAccessControl as String: access
 ]
 ```
 
-## SecAccessControl Flags
+Read the protected item with an authentication context so Keychain, not app
+logic, controls release of the secret:
+
+```swift
+let context = LAContext()
+context.localizedReason = "Authenticate to access your account"
+
+let query: [String: Any] = [
+    kSecClass as String: kSecClassGenericPassword,
+    kSecAttrAccount as String: "auth-token",
+    kSecReturnData as String: true,
+    kSecMatchLimit as String: kSecMatchLimitOne,
+    kSecUseAuthenticationContext as String: context
+]
+
+var result: AnyObject?
+let status = SecItemCopyMatching(query as CFDictionary, &result)
+guard status == errSecSuccess, let tokenData = result as? Data else {
+    throw KeychainError.readFailed(status)
+}
+```
 
-| Flag | Behavior |
-|------|----------|
-| `.biometryCurrentSet` | Requires biometry, invalidated if enrollment changes. Most secure. |
-| `.biometryAny` | Requires biometry, survives enrollment changes. |
-| `.userPresence` | Biometry or passcode. Most flexible. |
+Use `.biometryCurrentSet` when an auth token must be invalidated after biometric
+enrollment changes. Route broader SecAccessControl flag selection and policy
+tradeoffs to `swift-security`.
 
-Use `.biometryCurrentSet` for high-security items (tokens, keys). Use
-`.userPresence` when you want to allow passcode fallback without a separate
-`LAContext` evaluation.
 
 ## Keychain Error Handling
 
@@ -209,3 +226,13 @@ enum KeychainError: Error {
     }
 }
 ```
+
+## References
+
+- [Restricting keychain item accessibility](https://sosumi.ai/documentation/security/restricting-keychain-item-accessibility)
+- [Accessing Keychain Items with Face ID or Touch ID](https://sosumi.ai/documentation/localauthentication/accessing-keychain-items-with-face-id-or-touch-id)
+- [LAContext](https://sosumi.ai/documentation/localauthentication/lacontext)
+- [NSFaceIDUsageDescription](https://sosumi.ai/documentation/bundleresources/information-property-list/nsfaceidusagedescription)
+- [kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly](https://sosumi.ai/documentation/security/ksecattraccessiblewhenpasscodesetthisdeviceonly)
+- [SecAccessControlCreateFlags.userPresence](https://sosumi.ai/documentation/security/secaccesscontrolcreateflags/userpresence)
+- [SecAccessControlCreateFlags.biometryCurrentSet](https://sosumi.ai/documentation/security/secaccesscontrolcreateflags/biometrycurrentset)