@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/authentication/references/passkeys.md

@@ -1,183 +1,147 @@
-# Passkey Authentication Patterns
+# Passkeys
 
-Use this reference when implementing app-native passkey registration, passkey
-sign-in, AutoFill-assisted passkey suggestions, or physical security key
-fallbacks with AuthenticationServices.
+A passkey is a public/private key pair. For platform passkeys the private key
+sits in iCloud Keychain and syncs across the person's devices; the
+relying-party server keeps the public credential material and verifies every
+ceremony. Back to the [skill overview](../SKILL.md).
 
-## Contents
+## Before writing code
 
-- [Prerequisites](#prerequisites)
-- [Registration](#registration)
-- [Assertion Sign-In](#assertion-sign-in)
-- [Handling Results](#handling-results)
-- [AutoFill-Assisted Requests](#autofill-assisted-requests)
-- [Physical Security Keys](#physical-security-keys)
-- [Common Failure Modes](#common-failure-modes)
-- [References](#references)
+1. Turn on the **Associated Domains** capability for the target.
+2. Add `webcredentials:<domain>` for the relying party, for example
+   `webcredentials:accounts.tasknest.app`.
+3. Host the `apple-app-site-association` JSON on the domain, with the app's ID listed under `webcredentials`.
+4. Get every registration and assertion challenge from the server.
 
-## Prerequisites
+The relying party identifier is normally the bare domain, such as
+`tasknest.app`, not the bundle ID.
 
-Passkeys are public-private key credentials. The device keeps the private key
-in iCloud Keychain for platform passkeys, and your server, the relying party,
-stores and verifies the public credential material.
+## Registering a passkey
 
-Before making registration or assertion requests:
-
-1. Add the Associated Domains capability.
-2. Add `webcredentials:example.com` for the relying party domain.
-3. Host a valid apple-app-site-association file for that domain.
-4. Request every registration or assertion challenge from the server.
-
-The relying party identifier passed to
-`ASAuthorizationPlatformPublicKeyCredentialProvider` is normally the domain
-name, such as `example.com`. The app cannot use passkeys for services that are
-not configured as associated domains.
-
-## Registration
-
-Registration creates a new platform passkey for an account. The server should
-generate a challenge and stable user ID bytes for the relying-party account.
+The server creates the challenge and a stable user ID (bytes, not an email)
+for the account.
 
 ```swift
 import AuthenticationServices
 
-func beginPasskeyRegistration(username: String) async throws {
-    let challenge: Data = try await server.registrationChallenge(for: username)
-    let userID: Data = try await server.passkeyUserID(for: username)
-
-    let provider = ASAuthorizationPlatformPublicKeyCredentialProvider(
-        relyingPartyIdentifier: "example.com"
-    )
-    let request = provider.createCredentialRegistrationRequest(
-        challenge: challenge,
-        name: username,
-        userID: userID
-    )
-
-    let controller = ASAuthorizationController(authorizationRequests: [request])
-    controller.delegate = passkeyDelegate
-    controller.presentationContextProvider = presentationProvider
-    controller.performRequests()
+@MainActor
+final class PasskeyEnrollment: NSObject {
+    private let relyingParty = "tasknest.app"
+    weak var anchorProvider: ASAuthorizationControllerPresentationContextProviding?
+    weak var resultHandler: ASAuthorizationControllerDelegate?
+
+    func enroll(username: String) async throws {
+        let options = try await PasskeyAPI.registrationOptions(for: username)  // challenge + userID
+        let provider = ASAuthorizationPlatformPublicKeyCredentialProvider(relyingPartyIdentifier: relyingParty)
+        let request = provider.createCredentialRegistrationRequest(
+            challenge: options.challenge,
+            name: username,
+            userID: options.userID
+        )
+        let controller = ASAuthorizationController(authorizationRequests: [request])
+        controller.delegate = resultHandler
+        controller.presentationContextProvider = anchorProvider
+        controller.performRequests()
+    }
 }
 ```
 
-After the delegate receives
-`ASAuthorizationPlatformPublicKeyCredentialRegistration`, send the registration
-response to the server. The server verifies the challenge and stores the public
-credential data for future assertions.
+When the registration credential comes back, post it to the server. The server
+checks the challenge, validates the attestation it asked for, and stores the
+public credential.
 
-## Assertion Sign-In
-
-Assertion signs in with an existing passkey. Always use a fresh server challenge.
+## Signing in
 
 ```swift
-func beginPasskeySignIn(usernameHint: String?) async throws {
-    let challenge: Data = try await server.assertionChallenge(usernameHint)
-
-    let provider = ASAuthorizationPlatformPublicKeyCredentialProvider(
-        relyingPartyIdentifier: "example.com"
-    )
-    let request = provider.createCredentialAssertionRequest(challenge: challenge)
-
-    let controller = ASAuthorizationController(authorizationRequests: [request])
-    controller.delegate = passkeyDelegate
-    controller.presentationContextProvider = presentationProvider
-    controller.performRequests()
+func signInRequest(challenge: Data) -> ASAuthorizationPlatformPublicKeyCredentialAssertionRequest {
+    let provider = ASAuthorizationPlatformPublicKeyCredentialProvider(relyingPartyIdentifier: "tasknest.app")
+    return provider.createCredentialAssertionRequest(challenge: challenge)
 }
 ```
 
-If the user has no passkey for the relying party, the request fails. Offer
-registration, password sign-in, or Sign in with Apple as appropriate for the
-account recovery flow.
-
-## Handling Results
+Use a fresh challenge from the server each time, optionally scoped by a
+username hint. If the person has no passkey for this relying party the request
+fails; offer to create one, or fall back to a password or Sign in with Apple.
 
-Handle passkey credentials in the same `ASAuthorizationControllerDelegate`
-method as Sign in with Apple and password credentials:
+## One delegate for every credential type
 
 ```swift
-func authorizationController(
-    controller: ASAuthorizationController,
-    didCompleteWithAuthorization authorization: ASAuthorization
-) {
-    switch authorization.credential {
-    case let registration as ASAuthorizationPlatformPublicKeyCredentialRegistration:
-        Task { try await server.finishRegistration(registration) }
-
-    case let assertion as ASAuthorizationPlatformPublicKeyCredentialAssertion:
-        Task { try await server.finishAssertion(assertion) }
-
-    case let credential as ASAuthorizationAppleIDCredential:
-        handleAppleIDCredential(credential)
-
-    case let password as ASPasswordCredential:
-        signIn(username: password.user, password: password.password)
-
-    default:
-        break
+func authorizationController(controller: ASAuthorizationController,
+                             didCompleteWithAuthorization authorization: ASAuthorization) {
+    Task {
+        switch authorization.credential {
+        case let created as ASAuthorizationPlatformPublicKeyCredentialRegistration:
+            try await PasskeyAPI.finishRegistration(
+                credentialID: created.credentialID,
+                clientData: created.rawClientDataJSON,
+                attestation: created.rawAttestationObject)
+        case let proof as ASAuthorizationPlatformPublicKeyCredentialAssertion:
+            try await PasskeyAPI.finishSignIn(
+                credentialID: proof.credentialID,
+                clientData: proof.rawClientDataJSON,
+                authenticatorData: proof.rawAuthenticatorData,
+                signature: proof.signature,
+                userID: proof.userID)
+        case let apple as ASAuthorizationAppleIDCredential:
+            try await SessionAPI.exchange(token: apple.identityToken, code: apple.authorizationCode)
+        case let saved as ASPasswordCredential:
+            try await SessionAPI.passwordLogin(user: saved.user, password: saved.password)
+        default:
+            break
+        }
     }
 }
 ```
 
-Do not treat a local passkey result as the final proof of authentication. The
-relying-party server must verify the challenge and credential response before
-issuing an app session.
+What arrives on the device is not the final word. Issue a session only after
+the server has verified the challenge and the signed response.
 
-## AutoFill-Assisted Requests
+## Inline suggestions with AutoFill
 
-Use AutoFill-assisted requests when the login screen has a username text field
-and should show inline passkey suggestions.
+If the login form includes a username box, let the QuickType bar suggest passkeys
+instead of opening a modal right away:
 
 ```swift
-usernameField.textContentType = .username
-
-let request = provider.createCredentialAssertionRequest(challenge: challenge)
-let controller = ASAuthorizationController(authorizationRequests: [request])
-controller.delegate = passkeyDelegate
-controller.presentationContextProvider = presentationProvider
-controller.performAutoFillAssistedRequests()
+typealias PasskeyUIHost = ASAuthorizationControllerDelegate & ASAuthorizationControllerPresentationContextProviding
+
+@MainActor
+func armPasskeySuggestions(for field: UITextField, host: PasskeyUIHost) async throws -> ASAuthorizationController {
+    field.textContentType = .username
+    let assertion = signInRequest(challenge: try await PasskeyAPI.freshChallenge())
+    let controller = ASAuthorizationController(authorizationRequests: [assertion])
+    controller.delegate = host
+    controller.presentationContextProvider = host
+    controller.performAutoFillAssistedRequests()
+    return controller          // keep a reference while the login screen is visible
+}
 ```
 
-The controller presents UI when a text field with the appropriate content type
-gets focus. This is usually better than immediately showing a modal sheet on a
-username/password screen.
+The system shows its UI once a field with the matching content type gains
+focus, which usually feels better than an immediate sheet.
 
-## Physical Security Keys
+## Physical security keys
 
-Use `ASAuthorizationSecurityKeyPublicKeyCredentialProvider` only when the user
-needs a physical FIDO security key over NFC, USB, or Lightning. Keep this as a
-separate branch from platform passkeys because the provider, registration
-request, and UX differ:
+`ASAuthorizationSecurityKeyPublicKeyCredentialProvider(relyingPartyIdentifier:)`
+covers hardware FIDO keys over NFC, USB or Lightning. Use it only when a
+physical key is a requirement and keep it on its own code path: the provider,
+request type and user experience all differ. When the relying party accepts
+both, a single controller can carry a platform assertion request and a
+security-key assertion request together.
 
-```swift
-let provider = ASAuthorizationSecurityKeyPublicKeyCredentialProvider(
-    relyingPartyIdentifier: "example.com"
-)
-let request = provider.createCredentialAssertionRequest(challenge: challenge)
-```
+## Failure modes
+
+- No `webcredentials:` entitlement, or the domain's association file does not list the app.
+- Reusing a challenge, or generating challenges on the device.
+- Treating the assertion credential as a finished login before server verification.
+- Sending the bundle ID as the relying-party identifier while the backend registered a web domain.
+- Forgetting `performAutoFillAssistedRequests()`, so no inline suggestions appear.
+- Choosing the platform provider even though policy calls for a hardware key.
+
+## Apple documentation
 
-Apps can offer both platform and security-key assertion requests in the same
-`ASAuthorizationController` when the relying party supports both.
-
-## Common Failure Modes
-
-- Missing `webcredentials:` Associated Domains entitlement or AASA entry for
-  the relying-party domain.
-- Reusing challenges or generating challenges on device instead of on the
-  relying-party server.
-- Treating `ASAuthorizationPlatformPublicKeyCredentialAssertion` as complete
-  authentication before server verification.
-- Using the app bundle ID as the relying party identifier when the server's
-  WebAuthn relying party is a domain.
-- Forgetting `performAutoFillAssistedRequests()` for inline passkey suggestions.
-- Using the platform provider when the product requirement is a physical
-  security key.
-
-## References
-
-- [Supporting passkeys](https://sosumi.ai/documentation/authenticationservices/supporting-passkeys)
-- [ASAuthorizationPlatformPublicKeyCredentialProvider](https://sosumi.ai/documentation/authenticationservices/asauthorizationplatformpublickeycredentialprovider)
-- [ASAuthorizationPlatformPublicKeyCredentialRegistration](https://sosumi.ai/documentation/authenticationservices/asauthorizationplatformpublickeycredentialregistration)
-- [ASAuthorizationPlatformPublicKeyCredentialAssertion](https://sosumi.ai/documentation/authenticationservices/asauthorizationplatformpublickeycredentialassertion)
-- [ASAuthorizationSecurityKeyPublicKeyCredentialProvider](https://sosumi.ai/documentation/authenticationservices/asauthorizationsecuritykeypublickeycredentialprovider)
-- [ASAuthorizationController.performAutoFillAssistedRequests](https://sosumi.ai/documentation/authenticationservices/asauthorizationcontroller/performautofillassistedrequests())
+- [Supporting passkeys](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys)
+- [ASAuthorizationPlatformPublicKeyCredentialProvider](https://developer.apple.com/documentation/authenticationservices/asauthorizationplatformpublickeycredentialprovider)
+- [ASAuthorizationPlatformPublicKeyCredentialRegistration](https://developer.apple.com/documentation/authenticationservices/asauthorizationplatformpublickeycredentialregistration)
+- [ASAuthorizationPlatformPublicKeyCredentialAssertion](https://developer.apple.com/documentation/authenticationservices/asauthorizationplatformpublickeycredentialassertion)
+- [ASAuthorizationSecurityKeyPublicKeyCredentialProvider](https://developer.apple.com/documentation/authenticationservices/asauthorizationsecuritykeypublickeycredentialprovider)
+- [performAutoFillAssistedRequests()](https://developer.apple.com/documentation/authenticationservices/asauthorizationcontroller/performautofillassistedrequests())