@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.1

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

@@ -1,46 +1,35 @@
 ---
 name: authentication
-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."
+description: "iOS sign-in with AuthenticationServices and LocalAuthentication: Sign in with Apple, passkey (WebAuthn) sign-up and login via ASAuthorizationPlatformPublicKeyCredentialProvider, ASAuthorizationController credential state and revocation, ASWebAuthenticationSession OAuth, third-party login, Password AutoFill, server identity-token validation, LAContext biometric re-auth prompts and policy. Use when adding or reviewing account flows."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
 # Authentication
 
-Implement authentication flows on iOS using the AuthenticationServices
-framework, including Sign in with Apple, passkeys, OAuth/third-party web
-auth, Password AutoFill, and biometric re-authentication.
-
-## Contents
-
-- [Sign in with Apple](#sign-in-with-apple)
-- [Credential Handling](#credential-handling)
-- [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)
-- [References](#references)
+This skill owns the account-facing side of identity on iOS: Sign in with
+Apple, passkeys, Password AutoFill, `ASAuthorizationController`, presenting an
+OAuth session with `ASWebAuthenticationSession`, credential state, and local
+biometric re-authentication. Code samples assume iOS 26 with Swift 6.3.
+
+Deeper material:
+
+- [Passkeys](references/passkeys.md) - prerequisites, registration, sign-in, AutoFill, security keys, failure modes
+- [Keychain and biometrics](references/keychain-biometric.md) - token storage, `LAContext`, access-controlled items
 
 ## Sign in with Apple
 
-Add the "Sign in with Apple" capability in Xcode before using these APIs.
+Before any code, add the Apple sign-in capability to the app target in Signing & Capabilities.
 
-### UIKit: ASAuthorizationController Setup
+### Starting the request (UIKit)
 
 ```swift
 import AuthenticationServices
+import UIKit
 
-final class LoginViewController: UIViewController {
-    func startSignInWithApple() {
-        let provider = ASAuthorizationAppleIDProvider()
-        let request = provider.createRequest()
+final class WelcomeViewController: UIViewController {
+    func beginAppleSignIn() {
+        let request = ASAuthorizationAppleIDProvider().createRequest()
         request.requestedScopes = [.fullName, .email]
 
         let controller = ASAuthorizationController(authorizationRequests: [request])
@@ -50,445 +39,352 @@ final class LoginViewController: UIViewController {
     }
 }
 
-extension LoginViewController: ASAuthorizationControllerPresentationContextProviding {
+extension WelcomeViewController: ASAuthorizationControllerPresentationContextProviding {
     func presentationAnchor(for controller: ASAuthorizationController) -> ASPresentationAnchor {
-        view.window!
+        guard let window = view.window else {
+            preconditionFailure("Start Sign in with Apple only while this screen is on screen")
+        }
+        return window   // ASPresentationAnchor is UIWindow; UIWindow() is deprecated in iOS 26
     }
 }
 ```
 
-### Delegate: Handling Success and Failure
+### Delegate callbacks
 
 ```swift
-extension LoginViewController: ASAuthorizationControllerDelegate {
-    func authorizationController(
-        controller: ASAuthorizationController,
-        didCompleteWithAuthorization authorization: ASAuthorization
-    ) {
-        guard let credential = authorization.credential
-            as? ASAuthorizationAppleIDCredential else { return }
-
-        let userID = credential.user  // Stable, unique, per-team identifier
-        let email = credential.email  // nil after first authorization
-        let fullName = credential.fullName  // nil after first authorization
-        let identityToken = credential.identityToken  // JWT for server validation
-        let authCode = credential.authorizationCode  // Short-lived code for server exchange
-
-        // Save userID to Keychain for credential state checks
-        // See references/keychain-biometric.md for Keychain patterns
-        saveUserID(userID)
-
-        // Send identityToken and authCode to your server
-        authenticateWithServer(identityToken: identityToken, authCode: authCode)
+extension WelcomeViewController: ASAuthorizationControllerDelegate {
+    func authorizationController(controller: ASAuthorizationController,
+                                 didCompleteWithAuthorization authorization: ASAuthorization) {
+        let credential = authorization.credential
+        guard let apple = credential as? ASAuthorizationAppleIDCredential else { return }
+        AccountVault.shared.rememberAppleUser(apple.user)          // stable per-team ID
+        if let name = apple.fullName { ProfileDraft.shared.name = name }  // first time only
+        if let mail = apple.email { ProfileDraft.shared.email = mail }    // first time only
+        Task { try await SessionAPI.exchange(token: apple.identityToken, code: apple.authorizationCode) }
     }
 
-    func authorizationController(
-        controller: ASAuthorizationController,
-        didCompleteWithError error: any Error
-    ) {
-        let authError = error as? ASAuthorizationError
-        switch authError?.code {
-        case .canceled:
-            break  // User dismissed
-        case .failed:
-            showError("Authorization failed")
-        case .invalidResponse:
-            showError("Invalid response")
-        case .notHandled:
-            showError("Not handled")
-        case .notInteractive:
-            break  // Non-interactive request failed -- expected for silent checks
+    func authorizationController(controller: ASAuthorizationController,
+                                 didCompleteWithError error: Error) {
+        guard let authError = error as? ASAuthorizationError else { return }
+        switch authError.code {
+        case .canceled:        break                       // user closed the sheet
+        case .notInteractive:  break                       // silent check found nothing
+        case .failed, .invalidResponse, .notHandled:
+            showSignInProblem(authError)
         default:
-            showError("Unknown error")
+            showSignInProblem(authError)
         }
     }
 }
 ```
 
-## Credential Handling
-
-`ASAuthorizationAppleIDCredential` properties and their behavior:
+`user` is a stable identifier scoped to your team; save it in the Keychain so
+you can check credential state later. `identityToken` is a JWT for the server
+and `authorizationCode` is a short-lived code the server exchanges; send both.
 
-| Property | Type | First Auth | Subsequent Auth |
-|---|---|---|---|
-| `user` | `String` | Always | Always |
-| `email` | `String?` | Provided if requested | `nil` |
-| `fullName` | `PersonNameComponents?` | Provided if requested | `nil` |
-| `identityToken` | `Data?` | JWT encoded as UTF-8 data | JWT encoded as UTF-8 data |
-| `authorizationCode` | `Data?` | Short-lived code | Short-lived code |
-| `realUserStatus` | `ASUserDetectionStatus` | Fraud-prevention signal | Do not rely on later attempts |
+### What the credential contains
 
-**Critical:** `email` and `fullName` are provided ONLY on the first
-authorization. Cache them immediately during the initial sign-up flow. If the
-user later deletes and re-adds the app, these values will not be returned.
+| Property | Type | Availability |
+|---|---|---|
+| `user` | `String` | Every time |
+| `email` | `String?` | First authorization only, if requested |
+| `fullName` | `PersonNameComponents?` | First authorization only, if requested |
+| `identityToken` | `Data?` | Every time, a UTF-8 JWT |
+| `authorizationCode` | `Data?` | Every time, short-lived |
+| `realUserStatus` | `ASUserDetectionStatus` | Anti-fraud hint; do not count on it after the first attempt |
 
-```swift
-func handleCredential(_ credential: ASAuthorizationAppleIDCredential) {
-    // Always persist the user identifier
-    let userID = credential.user
-
-    // Cache name and email IMMEDIATELY -- only available on first auth
-    if let fullName = credential.fullName {
-        let name = PersonNameComponentsFormatter().string(from: fullName)
-        UserProfile.saveName(name)  // Persist to your backend
-    }
-    if let email = credential.email {
-        UserProfile.saveEmail(email)  // Persist to your backend
-    }
-}
-```
+Capture name and email the moment they arrive and send them to your backend.
+Apple never sends them again, and deleting and reinstalling the app does not
+bring them back. Format a name with
+`PersonNameComponentsFormatter().string(from:)` before storing it.
 
-## Credential State Checking
+### Credential state
 
-Check credential state on every app launch. The user may revoke access at
-any time via Settings > Apple Account > Sign-In & Security.
+People can revoke the app at any time under Settings > Apple Account >
+Sign-In & Security, so check on every launch:
 
 ```swift
-func checkCredentialState() {
+@MainActor
+func verifyAppleCredential(for userID: String) async {
     let provider = ASAuthorizationAppleIDProvider()
-    guard let userID = loadSavedUserID() else {
-        showLoginScreen()
+    let credentialState: ASAuthorizationAppleIDProvider.CredentialState
+    do {
+        credentialState = try await provider.credentialState(forUserID: userID)
+    } catch {
+        SessionStore.shared.presentLogin()
         return
     }
-
-    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()
-            }
-        }
+    switch credentialState {
+    case .authorized:  SessionStore.shared.resume()
+    case .revoked:     SessionStore.shared.signOutAndWipe()
+    case .notFound:    SessionStore.shared.presentLogin()
+    case .transferred: SessionStore.shared.migrateTransferredUser(userID)
+    @unknown default:  SessionStore.shared.presentLogin()
     }
 }
 ```
 
-### Credential Revocation Notification
+The function runs on the main actor and awaits the async form of
+`getCredentialState(forUserID:completion:)`, so the session calls need no hop
+back to the main queue.
 
-```swift
-NotificationCenter.default.addObserver(
-    forName: ASAuthorizationAppleIDProvider.credentialRevokedNotification,
-    object: nil,
-    queue: .main
-) { _ in
-    // Sign out immediately
-    AuthManager.shared.signOut()
-}
-```
+`.transferred` means the app moved to a different developer team and the user
+identifier must be migrated. Also subscribe to
+`ASAuthorizationAppleIDProvider.credentialRevokedNotification` and sign the
+user out as soon as it fires.
 
-## Token Validation
+### Server validation
 
-The `identityToken` is a JWT. Send it to your server for validation --
-never trust it client-side alone.
+Never accept the identity token on the device alone. Hand both values to your
+backend and keep only what it returns:
 
 ```swift
-func sendTokenToServer(credential: ASAuthorizationAppleIDCredential) async throws {
-    guard let tokenData = credential.identityToken,
-          let token = String(data: tokenData, encoding: .utf8),
-          let authCodeData = credential.authorizationCode,
-          let authCode = String(data: authCodeData, encoding: .utf8) else {
-        throw AuthError.missingToken
-    }
-
-    var request = URLRequest(url: URL(string: "https://api.example.com/auth/apple")!)
-    request.httpMethod = "POST"
-    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
-    request.httpBody = try JSONEncoder().encode(
-        ["identityToken": token, "authorizationCode": authCode]
-    )
-
-    let (data, response) = try await URLSession.shared.data(for: request)
-    guard (response as? HTTPURLResponse)?.statusCode == 200 else {
-        throw AuthError.serverValidationFailed
+enum SessionAPI {
+    struct Session: Decodable { let accessToken: String }
+    private static let transport = URLSession(configuration: .ephemeral)
+
+    static func exchange(token: Data?, code: Data?) async throws {
+        guard let token, let code,
+              let jwt = String(data: token, encoding: .utf8),
+              let grant = String(data: code, encoding: .utf8) else { throw URLError(.badServerResponse) }
+
+        guard let endpoint = URL(string: "https://api.tasknest.app/auth/apple") else { throw URLError(.badURL) }
+        var call = URLRequest(url: endpoint)
+        call.httpMethod = "POST"
+        call.addValue("application/json", forHTTPHeaderField: "Content-Type")
+        let body = try JSONEncoder().encode(["identity_token": jwt, "authorization_code": grant])
+        let (bytes, reply) = try await transport.upload(for: call, from: body)
+        let status = (reply as? HTTPURLResponse)?.statusCode ?? 0
+        if status != 200 { throw URLError(.userAuthenticationRequired) }
+
+        let session = try JSONDecoder().decode(Session.self, from: bytes)
+        try TokenVault(service: "auth").store(Data(session.accessToken.utf8), account: "access")
     }
-    let session = try JSONDecoder().decode(SessionResponse.self, from: data)
-    // Store session token in Keychain -- see references/keychain-biometric.md
-    try KeychainHelper.save(session.accessToken, forKey: "accessToken")
 }
 ```
 
-Server-side, validate the JWT against Apple's public keys at
-`https://appleid.apple.com/auth/keys` (JWKS). Verify: `iss` is
-`https://appleid.apple.com`, `aud` matches your bundle ID, `exp` not passed.
+`TokenVault` is in the [Keychain reference](references/keychain-biometric.md). The
+server verifies the JWT signature against Apple's published key set (the JWKS
+document served from `appleid.apple.com` under `/auth/keys`) and checks that `iss` is
+`https://appleid.apple.com`, `aud` is your bundle ID, and `exp` is in the future.
 
-## Existing Account Setup Flows
+### Existing accounts first
 
-On launch, silently check for existing Sign in with Apple and password
-credentials before showing a login screen:
+Before showing a login screen, quietly ask the system whether the person
+already has an Apple ID credential or a saved password for the app:
 
 ```swift
-func performExistingAccountSetupFlows() {
-    let appleIDRequest = ASAuthorizationAppleIDProvider().createRequest()
-    let passwordRequest = ASAuthorizationPasswordProvider().createRequest()
-
-    let controller = ASAuthorizationController(
-        authorizationRequests: [appleIDRequest, passwordRequest]
-    )
-    controller.delegate = self
-    controller.presentationContextProvider = self
-    controller.performRequests(
-        options: .preferImmediatelyAvailableCredentials
-    )
+extension WelcomeViewController {
+    func offerSavedCredentials() {
+        let requests: [ASAuthorizationRequest] = [
+            ASAuthorizationAppleIDProvider().createRequest(),
+            ASAuthorizationPasswordProvider().createRequest(),
+        ]
+        let controller = ASAuthorizationController(authorizationRequests: requests)
+        controller.delegate = self
+        controller.presentationContextProvider = self
+        controller.performRequests(options: .preferImmediatelyAvailableCredentials)
+    }
 }
 ```
 
-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()
-```
+Run it from `viewDidAppear` or during launch. When nothing is stored, the
+delegate receives `.notInteractive`; treat that silently and show the usual
+login.
 
-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:
+### SwiftUI button
 
 ```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
+import AuthenticationServices
+import SwiftUI
+
+struct AppleSignInRow: View {
+    let model: LoginModel
+
+    var body: some View {
+        SignInWithAppleButton(.continue) { request in
+            request.requestedScopes = [.fullName, .email]
+        } onCompletion: { outcome in
+            switch outcome {
+            case .success(let auth):
+                if let apple = auth.credential as? ASAuthorizationAppleIDCredential {
+                    model.completeAppleSignIn(apple)   // same server validation as UIKit
+                }
+            case .failure(let error):
+                model.report(error)
+            }
+        }
+        .signInWithAppleButtonStyle(.whiteOutline)
+        .frame(height: 48)
+    }
 }
 ```
 
-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.
+The button lives in AuthenticationServices but needs SwiftUI imported in the
+same file.
 
-## ASWebAuthenticationSession (OAuth)
+## Passkeys
 
-Use `ASWebAuthenticationSession` for OAuth and third-party authentication
-(Google, GitHub, etc.). Never use `WKWebView` for auth flows.
+Passkeys replace passwords with WebAuthn credentials for both account creation and login. They need
+the Associated Domains entitlement with a `webcredentials:` entry for the
+relying-party domain; requests for a domain that is not associated fail.
+Platform passkeys sync through iCloud Keychain.
 
-```swift
-import AuthenticationServices
+- Create `ASAuthorizationPlatformPublicKeyCredentialProvider(relyingPartyIdentifier:)`.
+- Register with `createCredentialRegistrationRequest(challenge:name:userID:)` using a
+  challenge and user ID `Data` from the server.
+- Sign in with `createCredentialAssertionRequest(challenge:)` and a fresh server challenge.
+- Results arrive as `ASAuthorizationPlatformPublicKeyCredentialRegistration` or
+  `ASAuthorizationPlatformPublicKeyCredentialAssertion`; the relying-party server verifies them.
+- For inline suggestions, mark the username field `.username`, include an
+  assertion request, and call `performAutoFillAssistedRequests()`.
+- Reach for `ASAuthorizationSecurityKeyPublicKeyCredentialProvider` only when a
+  physical security key is required.
 
-final class OAuthController: NSObject, ASWebAuthenticationPresentationContextProviding {
-    private weak var presentationAnchor: ASPresentationAnchor?
+Details and code: [passkeys reference](references/passkeys.md).
 
-    init(presentationAnchor: ASPresentationAnchor) {
-        self.presentationAnchor = presentationAnchor
-    }
+## OAuth with `ASWebAuthenticationSession`
+
+Third-party logins (Google, GitHub and similar) go through
+`ASWebAuthenticationSession`, never an embedded `WKWebView`.
 
-    func startOAuthFlow() {
-        let authURL = URL(string:
-            "https://provider.com/oauth/authorize?client_id=YOUR_ID&redirect_uri=myapp://callback&response_type=code"
-        )!
-        let session = ASWebAuthenticationSession(
-            url: authURL, callback: .customScheme("myapp")
-        ) { callbackURL, error in
-            guard let callbackURL, error == nil,
-                  let code = URLComponents(url: callbackURL, resolvingAgainstBaseURL: false)?
-                      .queryItems?.first(where: { $0.name == "code" })?.value else { return }
-            Task { await self.exchangeCodeForTokens(code) }
+```swift
+final class GitHubLogin: NSObject, ASWebAuthenticationPresentationContextProviding {
+    private var session: ASWebAuthenticationSession?
+
+    func start(authorizeURL: URL) {
+        let session = ASWebAuthenticationSession(url: authorizeURL,
+                                                 callback: .customScheme("tasknest")) { url, error in
+            guard error == nil, let url,
+                  let items = URLComponents(url: url, resolvingAgainstBaseURL: false)?.queryItems,
+                  let code = items.first(where: { $0.name == "code" })?.value else { return }
+            Task { try await OAuthBackend.redeem(code: code) }
         }
         session.presentationContextProvider = self
-        session.prefersEphemeralWebBrowserSession = true  // No shared cookies
+        session.prefersEphemeralWebBrowserSession = true   // no shared browser cookies
         session.start()
+        self.session = session
     }
 
-    func presentationAnchor(for session: ASWebAuthenticationSession) -> ASPresentationAnchor {
-        guard let presentationAnchor else {
-            fatalError("ASWebAuthenticationSession needs the active window")
-        }
-        return presentationAnchor
+    func presentationAnchor(for webSession: ASWebAuthenticationSession) -> ASPresentationAnchor {
+        let scenes = UIApplication.shared.connectedScenes.compactMap { $0 as? UIWindowScene }
+        if let key = scenes.compactMap(\.keyWindow).first { return key }
+        guard let scene = scenes.first else { preconditionFailure("No window scene to present from") }
+        return ASPresentationAnchor(windowScene: scene)
     }
 }
 ```
 
-In SwiftUI, use `@Environment(\.webAuthenticationSession)` and call
+In SwiftUI, read `@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.
+with `.customScheme(...)` or `.https(host:path:)`. Ask for the `.ephemeral`
+browser session only when the provider's flow should not share cookies.
 
-## Password AutoFill Credentials
+## Password AutoFill
 
-Use `ASAuthorizationPasswordProvider` to offer saved keychain credentials
-alongside Sign in with Apple:
+`ASAuthorizationPasswordProvider` puts saved Keychain passwords in the same
+controller as Sign in with Apple. The delegate then branches on the credential:
 
 ```swift
-func performSignIn() {
-    let appleIDRequest = ASAuthorizationAppleIDProvider().createRequest()
-    appleIDRequest.requestedScopes = [.fullName, .email]
-
-    let passwordRequest = ASAuthorizationPasswordProvider().createRequest()
-
-    let controller = ASAuthorizationController(
-        authorizationRequests: [appleIDRequest, passwordRequest]
-    )
-    controller.delegate = self
-    controller.presentationContextProvider = self
-    controller.performRequests()
-}
-
-// In delegate:
-func authorizationController(
-    controller: ASAuthorizationController,
-    didCompleteWithAuthorization authorization: ASAuthorization
-) {
-    switch authorization.credential {
-    case let appleIDCredential as ASAuthorizationAppleIDCredential:
-        handleAppleIDLogin(appleIDCredential)
-    case let passwordCredential as ASPasswordCredential:
-        // User selected a saved password from keychain
-        signInWithPassword(
-            username: passwordCredential.user,
-            password: passwordCredential.password
-        )
-    default:
-        break
-    }
+switch authorization.credential {
+case let apple as ASAuthorizationAppleIDCredential:
+    finishApple(apple)
+case let saved as ASPasswordCredential:
+    signIn(username: saved.user, password: saved.password)
+default:
+    break
 }
 ```
 
-Set `textContentType` on text fields for AutoFill to work:
-
-```swift
-usernameField.textContentType = .username
-passwordField.textContentType = .password
-```
+AutoFill only lights up when the text fields declare `textContentType`
+`.username` and `.password`.
 
-## Biometric Authentication
+## Biometric re-authentication
 
-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.
+Use `LAContext` to confirm the device owner before opening account settings or
+a sensitive action. The `Bool` it returns is a UI gate, not permission to read
+a secret. Put Keychain access control on anything valuable (see
+[Keychain and biometrics](references/keychain-biometric.md)).
 
 ```swift
 import LocalAuthentication
 
-func authenticateWithBiometrics() async throws -> Bool {
+func confirmOwner() async -> Bool {
     let context = LAContext()
-    var error: NSError?
-
-    guard context.canEvaluatePolicy(
-        .deviceOwnerAuthenticationWithBiometrics, error: &error
-    ) else {
-        throw AuthError.biometricsUnavailable
+    var problem: NSError?
+    guard context.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: &problem) else {
+        return false
     }
-
-    return try await context.evaluatePolicy(
-        .deviceOwnerAuthenticationWithBiometrics,
-        localizedReason: "Sign in to your account"
-    )
+    let reason = "Confirm it's you to change your email"
+    let passed = try? await context.evaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, localizedReason: reason)
+    return passed == true
 }
 ```
 
-**Required:** Add `NSFaceIDUsageDescription` to Info.plist. Missing this
-key crashes on Face ID devices.
-
-## Security Boundaries
-
-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.
-
-## SwiftUI SignInWithAppleButton
-
-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(...)`.
-
-## Common Mistakes
-
-- 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
+Info.plist must include `NSFaceIDUsageDescription`, the same rule the
+`swift-security` skill sets for biometric keychain items. The `LAContext` header
+asks apps to supply it: its string is shown the first time the app uses Face ID,
+and once the user denies Face ID for the app, evaluations fail with
+`LAError.biometryNotAvailable`.
+
+## Security boundaries
+
+This skill covers: Apple ID sign-in, passkeys, AutoFill of saved passwords, the
+`ASAuthorizationController` flow, presenting OAuth web sessions, checking
+credential state, and biometric re-authentication on the device.
+
+The minimum storage rule stays here too: tokens and secrets live in the
+Keychain, and `LAContext.evaluatePolicy` on its own must never unlock a
+protected secret.
+
+Hand off to `swift-security`: Keychain architecture and migration,
+biometric-gated keychain items and their access-control policy, CryptoKit, Secure Enclave, certificate pinning
+and trust evaluation, sharing items between apps, hardening local storage, and
+mapping against OWASP MASVS/MASTG. App and device attestation belongs to `device-integrity`.
+
+## Common mistakes
+
+- Assuming a cached session means Apple has not revoked the link. Check state at launch and react to the revocation notification.
+- Jumping straight to the login form without first asking for saved credentials;
+  `.notInteractive` is simply the "nothing saved" answer.
+- Force-unwrapping `email` or `fullName`.
+- Building an `ASAuthorizationController` with no presentation context provider.
+- Writing JWTs from Apple, one-time codes, session tokens, passwords or
+  passkey server records into `UserDefaults`, plain files or Core Data. Use the
+  Keychain, and keep passkey verification on the server.
+- Passkey requests without a `webcredentials:` Associated Domains entry, or
+  using app passkeys for an unrelated website.
+- Drifting into CryptoKit, Secure Enclave, pinning or MASVS work instead of
+  routing it to `swift-security`.
+
+## Review checklist
+
+- [ ] Sign in with Apple capability enabled
 - [ ] `ASAuthorizationControllerPresentationContextProviding` implemented
-- [ ] 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
-- [ ] Tokens stored in Keychain, not UserDefaults or files
-- [ ] `performExistingAccountSetupFlows` called before showing login UI
-- [ ] Error cases handled: `.canceled`, `.failed`, `.notInteractive`
-- [ ] `NSFaceIDUsageDescription` in Info.plist for biometric auth
-- [ ] `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`
+- [ ] `getCredentialState(forUserID:completion:)` runs on every launch
+- [ ] `credentialRevokedNotification` observed and signs the user out
+- [ ] `email` and `fullName` saved on first authorization
+- [ ] `identityToken` validated by the server
+- [ ] Tokens kept in the Keychain
+- [ ] Existing-account flows run before the login UI
+- [ ] `.canceled`, `.failed` and `.notInteractive` handled
+- [ ] `NSFaceIDUsageDescription` present
+- [ ] OAuth uses `ASWebAuthenticationSession`, not `WKWebView`
+- [ ] `prefersEphemeralWebBrowserSession` set where cookie isolation matters
+- [ ] `textContentType` set on username and password fields
+- [ ] Passkey relying party listed under `webcredentials:` Associated Domains
+- [ ] Passkey challenges issued and verified by the server
+- [ ] Deep Keychain, CryptoKit, Secure Enclave, pinning and MASVS questions routed to `swift-security`
 
 ## References
 
-- 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)
+- [AuthenticationServices](https://developer.apple.com/documentation/authenticationservices)
+- [ASAuthorizationAppleIDProvider](https://developer.apple.com/documentation/authenticationservices/asauthorizationappleidprovider)
+- [ASAuthorizationAppleIDCredential](https://developer.apple.com/documentation/authenticationservices/asauthorizationappleidcredential)
+- [ASAuthorizationController](https://developer.apple.com/documentation/authenticationservices/asauthorizationcontroller)
+- [ASWebAuthenticationSession](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession)
+- [Supporting passkeys](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys)
+- [ASAuthorizationPlatformPublicKeyCredentialProvider](https://developer.apple.com/documentation/authenticationservices/asauthorizationplatformpublickeycredentialprovider)
+- [ASAuthorizationPasswordProvider](https://developer.apple.com/documentation/authenticationservices/asauthorizationpasswordprovider)
+- [SignInWithAppleButton](https://developer.apple.com/documentation/authenticationservices/signinwithapplebutton)
+- Sample code: the AuthenticationServices sample on implementing user authentication with Apple ID sign-in