@mmerterden/multi-agent-pipeline 8.6.1 → 10.0.6

package/pipeline/skills/shared/external/device-integrity/SKILL.md

@@ -1,14 +1,15 @@
 ---
 name: device-integrity
-description: "Verify device legitimacy and app integrity using DeviceCheck (DCDevice per-device bits) and App Attest (DCAppAttestService key generation, attestation, and assertion flows). Use when implementing fraud prevention, detecting compromised devices, validating app authenticity with Apple's servers, protecting sensitive API endpoints with attested requests, or adding device verification to your backend architecture."
+description: "Verify device legitimacy and app integrity using DeviceCheck (DCDevice per-device bits) and App Attest (DCAppAttestService key generation, attestation, and assertion flows). Use when implementing fraud prevention, detecting compromised devices, validating app authenticity with Apple's servers, protecting sensitive API endpoints with attested requests, or adding device verification to a backend architecture."
 ---
 
 # Device Integrity
 
-Verify that requests to your server come from a genuine Apple device running
-your unmodified app. DeviceCheck provides per-device bits for simple flags
-(e.g., "claimed promo offer"). App Attest uses Secure Enclave keys and Apple
-attestation to cryptographically prove app legitimacy on each request.
+Verify that requests to your server come from a genuine Apple device running a
+legitimate instance of your app. DeviceCheck provides per-device bits for
+simple flags (e.g., "claimed promo offer"). App Attest uses Secure Enclave keys
+and Apple attestation to cryptographically prove app legitimacy on sensitive
+requests.
 
 ## Contents
 
@@ -22,13 +23,15 @@ attestation to cryptographically prove app legitimacy on each request.
 - [Common Patterns](#common-patterns)
 - [Common Mistakes](#common-mistakes)
 - [Review Checklist](#review-checklist)
+- [References](#references)
 
 ## DCDevice (DeviceCheck Tokens)
 
 [`DCDevice`](https://sosumi.ai/documentation/devicecheck/dcdevice) generates a
-unique, ephemeral token that identifies a device. The token is sent to your
-server, which then communicates with Apple's servers to read or set two
-per-device bits. Available on iOS 11+.
+unique, ephemeral token that identifies a device. Treat each token as
+single-use: generate a new token for each server operation instead of caching or
+reusing one. The token is sent to your server, which then communicates with
+Apple's servers to read or set two per-device bits. Available on iOS 11+.
 
 ### Token Generation
 
@@ -76,6 +79,9 @@ Your server uses the device token to call Apple's DeviceCheck API endpoints:
 The server authenticates with a DeviceCheck private key from the Apple Developer
 portal, creating a signed JWT for each request.
 
+Use `https://api.development.devicecheck.apple.com` only while testing; use
+`https://api.devicecheck.apple.com` for production.
+
 ### What the Two Bits Are For
 
 Apple stores two Boolean values per device per developer team. You decide what
@@ -84,8 +90,8 @@ they mean. Common uses:
 - **Bit 0:** Device has claimed a promotional offer.
 - **Bit 1:** Device has been flagged for fraud.
 
-Bits persist across app reinstall; device reset does not clear them. You control
-when to reset them via the server API.
+Bits persist across app reinstall. You control when to reset them via the
+server API.
 
 ## DCAppAttestService (App Attest)
 
@@ -113,11 +119,20 @@ guard attestService.isSupported else {
 }
 ```
 
+For app extensions, App Attest is supported only in Action, extensible SSO, and
+watchOS extensions. Treat other extension types as unsupported even if
+`isSupported` returns `true`.
+
 ## App Attest Key Generation
 
-Generate a cryptographic key pair stored in the Secure Enclave. The returned
-`keyId` is a string identifier you persist (e.g., in Keychain) for later
-attestation and assertion calls.
+Generate one cryptographic key pair per user account on each device. The
+private key stays in the Secure Enclave. The returned `keyId` is the only
+identifier your app can later use to access the key, so record and reuse the
+account/device-scoped `keyId`; do not share one key across users. Avoid
+unnecessary regeneration because each new key affects App Attest key-count risk
+metrics. Only treat the `keyId` as usable after your server verifies
+attestation. If server verification fails, discard the `keyId` and generate a
+new key before retrying.
 
 ```swift
 import DeviceCheck
@@ -126,7 +141,7 @@ actor AppAttestManager {
     private let service = DCAppAttestService.shared
     private var keyId: String?
 
-    /// Generate and persist a key pair for App Attest.
+    /// Generate and record a key pair for App Attest.
     func generateKeyIfNeeded() async throws -> String {
         if let existingKeyId = loadKeyIdFromKeychain() {
             self.keyId = existingKeyId
@@ -145,7 +160,7 @@ actor AppAttestManager {
         let data = Data(keyId.utf8)
         let query: [String: Any] = [
             kSecClass as String: kSecClassGenericPassword,
-            kSecAttrAccount as String: "app-attest-key-id",
+            kSecAttrAccount as String: "app-attest-key-id-\(currentAccountID)",
             kSecAttrService as String: Bundle.main.bundleIdentifier ?? "",
             kSecValueData as String: data,
             kSecAttrAccessible as String: kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
@@ -157,7 +172,7 @@ actor AppAttestManager {
     private func loadKeyIdFromKeychain() -> String? {
         let query: [String: Any] = [
             kSecClass as String: kSecClassGenericPassword,
-            kSecAttrAccount as String: "app-attest-key-id",
+            kSecAttrAccount as String: "app-attest-key-id-\(currentAccountID)",
             kSecAttrService as String: Bundle.main.bundleIdentifier ?? "",
             kSecReturnData as String: true,
             kSecMatchLimit as String: kSecMatchLimitOne
@@ -170,14 +185,16 @@ actor AppAttestManager {
 }
 ```
 
-**Important:** Generate the key once and persist the `keyId`. Generating a new
-key invalidates any previous attestation.
+**Important:** Generate the key once per user account on a device, persist that
+account/device `keyId`, and keep the key count low. Generating unnecessary keys
+pollutes App Attest risk metrics.
 
 ## App Attest Attestation Flow
 
 Attestation proves that the key was generated on a genuine Apple device running
-your unmodified app. You perform attestation once per key, then store the
-attestation object on your server.
+a legitimate instance of your app. You perform attestation once per key, then
+store the verified public key and receipt on your server. The app stores the
+`keyId` for future assertions after the server accepts the attestation.
 
 ### Client-Side Attestation
 
@@ -244,18 +261,20 @@ extension AppAttestManager {
 
 ### Server-Side Attestation Verification
 
-Your server must:
-1. Verify the attestation object is a valid CBOR-encoded structure.
-2. Extract the certificate chain and validate it against Apple's App Attest root CA.
-3. Verify the `nonce` in the attestation matches `SHA256(challenge)`.
-4. Extract and store the public key and receipt for future assertion verification.
-
-See [Validating apps that connect to your server](https://sosumi.ai/documentation/devicecheck/validating-apps-that-connect-to-your-server) for the full server verification algorithm.
+Your server validates the attestation object (CBOR), verifies the certificate
+chain against Apple's App Attest root CA, checks Apple's nonce calculation, and
+stores the verified public key and receipt for future assertion verification.
+The attestation nonce is not `SHA256(challenge)` alone; it is
+`SHA256(authData || SHA256(challenge))` and is compared with the credential
+certificate extension `1.2.840.113635.100.8.2`. See
+[references/device-integrity-patterns.md](references/device-integrity-patterns.md)
+for the full server verification flow.
 
 ## App Attest Assertion Flow
 
-After attestation, use assertions to sign individual requests. Each assertion
-proves the request came from the attested app instance.
+After attestation, use assertions to sign sensitive requests. Each assertion
+proves the request came from the attested app instance and includes a
+server-issued, one-time challenge to prevent replay.
 
 ### Client-Side Assertion
 
@@ -264,16 +283,14 @@ import DeviceCheck
 import CryptoKit
 
 extension AppAttestManager {
-    /// Generate an assertion to accompany a server request.
-    /// - Parameter requestData: The request payload to sign (e.g., JSON body).
-    /// - Returns: The assertion data to include with the request.
-    func generateAssertion(for requestData: Data) async throws -> Data {
+    /// Generate an assertion for encoded client data.
+    /// Client data should include a one-time server challenge and request context.
+    func generateAssertion(for clientData: Data) async throws -> Data {
         guard let keyId else {
             throw DeviceIntegrityError.keyNotGenerated
         }
 
-        // Hash the request data -- the server will verify this matches
-        let clientDataHash = Data(SHA256.hash(data: requestData))
+        let clientDataHash = Data(SHA256.hash(data: clientData))
 
         return try await service.generateAssertion(keyId, clientDataHash: clientDataHash)
     }
@@ -283,6 +300,13 @@ extension AppAttestManager {
 ### Using Assertions in Network Requests
 
 ```swift
+struct AppAttestClientData: Encodable {
+    let challenge: String
+    let method: String
+    let path: String
+    let bodySHA256: String
+}
+
 extension AppAttestManager {
     /// Perform an attested API request.
     func makeAttestedRequest(
@@ -290,146 +314,75 @@ extension AppAttestManager {
         method: String = "POST",
         body: Data
     ) async throws -> (Data, URLResponse) {
-        let assertion = try await generateAssertion(for: body)
+        let challenge = try await fetchAssertionChallenge()
+        let bodyHash = Data(SHA256.hash(data: body)).base64EncodedString()
+        let clientData = try JSONEncoder().encode(
+            AppAttestClientData(
+                challenge: challenge,
+                method: method,
+                path: url.path,
+                bodySHA256: bodyHash
+            )
+        )
+        let assertion = try await generateAssertion(for: clientData)
 
         var request = URLRequest(url: url)
         request.httpMethod = method
         request.setValue("application/json", forHTTPHeaderField: "Content-Type")
-        request.setValue(assertion.base64EncodedString(), forHTTPHeaderField: "X-App-Assertion")
+        request.setValue(assertion.base64EncodedString(), forHTTPHeaderField: "X-App-Attest-Assertion")
+        request.setValue(clientData.base64EncodedString(), forHTTPHeaderField: "X-App-Attest-Client-Data")
         request.httpBody = body
 
         return try await URLSession.shared.data(for: request)
     }
+
+    private func fetchAssertionChallenge() async throws -> String {
+        let url = serverURL.appending(path: "assert/challenge")
+        let (data, _) = try await URLSession.shared.data(from: url)
+        return String(decoding: data, as: UTF8.self)
+    }
 }
 ```
 
 ### Server-Side Assertion Verification
 
-Your server must:
-1. Decode the assertion (CBOR).
-2. Verify the authenticator data, including the counter (must be greater than the stored counter).
-3. Verify the signature using the stored public key from attestation.
-4. Confirm the `clientDataHash` matches the SHA-256 of the received request body.
-5. Update the stored counter to prevent replay attacks.
+Your server decodes the assertion (CBOR), verifies the authenticator data and
+counter, recomputes `clientDataHash` from the submitted client data, verifies
+the signature over `SHA256(authenticatorData || clientDataHash)` with the
+stored public key, and confirms the embedded challenge and request context. See
+[references/device-integrity-patterns.md](references/device-integrity-patterns.md)
+for step-by-step server verification.
 
 ## Server Verification Guidance
 
-### Attestation vs. Assertion
-
-| Phase | When | What It Proves | Frequency |
-|-------|------|---------------|-----------|
-| **Attestation** | After key generation | The key lives on a genuine Apple device running your unmodified app | Once per key |
-| **Assertion** | With each sensitive request | The request came from the attested app instance | Per request |
+See [references/device-integrity-patterns.md](references/device-integrity-patterns.md) for full server architecture guidance including attestation vs. assertion comparison, recommended endpoint design, and risk assessment.
 
-### Recommended Server Architecture
+### Security Boundaries
 
-1. **Challenge endpoint** -- generate a random nonce, store it server-side with a short TTL (e.g., 5 minutes).
-2. **Attestation verification endpoint** -- validate the attestation object, store the public key and receipt keyed by `keyId`.
-3. **Assertion verification middleware** -- verify assertions on sensitive endpoints (purchases, account changes).
-
-### Risk Assessment
-
-Combine App Attest with [fraud risk assessment](https://sosumi.ai/documentation/devicecheck/assessing-fraud-risk) for defense in depth. App Attest alone does not guarantee the user is not abusing the app -- it confirms the app is genuine.
+App Attest proves app-instance integrity for selected requests. It does not
+replace user authentication, OAuth/JWT/session handling, API token design,
+entitlement or subscription authorization, TLS, certificate pinning, or general
+networking security. Treat those as handoffs to authentication, networking, or
+broader security guidance, and still enforce normal authentication and
+authorization after App Attest passes.
 
 ## Error Handling
 
-### DCError Codes
-
-```swift
-import DeviceCheck
-
-func handleAttestError(_ error: Error) {
-    if let dcError = error as? DCError {
-        switch dcError.code {
-        case .unknownSystemFailure:
-            // Transient system error -- retry with exponential backoff
-            break
-        case .featureUnsupported:
-            // Device or OS does not support this feature
-            // Fall back to alternative verification
-            break
-        case .invalidKey:
-            // Key is corrupted or was invalidated
-            // Generate a new key and re-attest
-            break
-        case .invalidInput:
-            // The clientDataHash or keyId was malformed
-            break
-        case .serverUnavailable:
-            // Apple's attestation server is unreachable -- retry later
-            break
-        @unknown default:
-            break
-        }
-    }
-}
-```
-
-### Retry Strategy
-
-```swift
-extension AppAttestManager {
-    func attestKeyWithRetry(maxAttempts: Int = 3) async throws -> Data {
-        var lastError: Error?
-
-        for attempt in 0..<maxAttempts {
-            do {
-                return try await attestKey()
-            } catch let error as DCError where error.code == .serverUnavailable {
-                lastError = error
-                let delay = UInt64(pow(2.0, Double(attempt))) * 1_000_000_000
-                try await Task.sleep(nanoseconds: delay)
-            } catch {
-                throw error // Non-retryable errors propagate immediately
-            }
-        }
-
-        throw lastError ?? DeviceIntegrityError.attestationFailed
-    }
-}
-```
+Handle `DCError` codes from DeviceCheck operations. Key cases:
 
-### Handling Invalidated Keys
+- `.serverUnavailable`  -  retry with exponential backoff
+- `.invalidKey`  -  the key was already attested, assertion used an unattested key, or the service rejected the key
+- `.featureUnsupported`  -  fall back to `DCDevice` tokens
+- `.invalidInput`  -  malformed `clientDataHash` or `keyId`
 
-If `attestKey` returns `DCError.invalidKey`, the Secure Enclave key has been
-invalidated (e.g., OS update, Secure Enclave reset). Delete the stored `keyId`
-from Keychain and generate a new key:
-
-```swift
-extension AppAttestManager {
-    func handleInvalidKey() async throws -> String {
-        deleteKeyIdFromKeychain()
-        keyId = nil
-        return try await generateKeyIfNeeded()
-    }
-
-    private func deleteKeyIdFromKeychain() {
-        let query: [String: Any] = [
-            kSecClass as String: kSecClassGenericPassword,
-            kSecAttrAccount as String: "app-attest-key-id",
-            kSecAttrService as String: Bundle.main.bundleIdentifier ?? ""
-        ]
-        SecItemDelete(query as CFDictionary)
-    }
-}
-```
+For `attestKey`, retry `.serverUnavailable` later with the same `keyId` and the
+same `clientDataHash`. For other attestation errors, discard the key identifier
+and create a new key before retrying. See
+[references/device-integrity-patterns.md](references/device-integrity-patterns.md)
+for full error handling code, retry strategy, and rejected-key recovery.
 
 ## Common Patterns
 
-### Full Integration Manager
-
-Combine the patterns above into a single `actor` that manages the full lifecycle:
-1. Check `isSupported` and fall back to `DCDevice` tokens on unsupported devices.
-2. Call `generateKeyIfNeeded()` on launch to create or load the persisted key.
-3. Call `attestKeyWithRetry()` once after key generation.
-4. Use `generateAssertion(for:)` on each sensitive server request.
-5. Handle `DCError.invalidKey` by regenerating and re-attesting.
-
-### Gradual Rollout
-
-Apple recommends a gradual rollout. Gate App Attest behind a remote feature
-flag and fall back to `DCDevice` tokens on unsupported devices.
-
 ### Environment Entitlement
 
 Set the App Attest environment in your entitlements file. Use `development`
@@ -440,38 +393,45 @@ during testing and `production` for App Store builds:
 <string>production</string>
 ```
 
-When the entitlement is missing, the system uses `development` in debug builds
-and `production` for App Store and TestFlight builds.
+When the entitlement is omitted during development, the app uses the App Attest
+sandbox by default. After distribution through TestFlight, the App Store, or the
+Apple Developer Enterprise Program, the app ignores the entitlement value and
+uses production.
 
-### Error Type
-
-```swift
-enum DeviceIntegrityError: Error {
-    case deviceCheckUnsupported
-    case keyNotGenerated
-    case attestationFailed
-    case attestationVerificationFailed
-    case assertionFailed
-    case serverVerificationFailed
-}
-```
+See [references/device-integrity-patterns.md](references/device-integrity-patterns.md) for the full integration manager pattern, gradual rollout guidance, and error type definition.
 
 ## Common Mistakes
 
-1. **Generating a new key on every launch.** Generate once, persist the `keyId` in Keychain.
-2. **Skipping the fallback for unsupported devices.** Not all devices support App Attest. Use `DCDevice` tokens as fallback.
-3. **Trusting attestation client-side.** All verification must happen on your server.
-4. **Not implementing replay protection.** The server must track and increment the assertion counter.
-5. **Missing the environment entitlement.** Without it, debug builds use `development` and App Store uses `production`. Mismatches cause attestation failures.
-6. **Not handling `DCError.invalidKey`.** Keys can be invalidated by OS updates. Detect and regenerate.
+1. **Generating a new key on every launch.** Generate once per user account on a device, persist the `keyId`, and keep key counts low.
+2. **Reusing `DCDevice` tokens.** Treat generated tokens as single-use. Generate a new token for each server operation.
+3. **Skipping the fallback for unsupported devices or extensions.** Not all devices and extension types support App Attest. Use `DCDevice` tokens or other risk assessment as fallback.
+4. **Trusting attestation client-side.** All verification must happen on your server.
+5. **Signing only the raw request body.** Assertion client data must include a one-time server challenge and enough request context for the server to bind the assertion to the request.
+6. **Verifying the wrong attestation nonce.** Compare the certificate extension with `SHA256(authData || SHA256(challenge))`, not `SHA256(challenge)` alone.
+7. **Not implementing replay protection.** The server must validate one-time challenges and track the assertion counter.
+8. **Mixing development and production environments.** Sandbox keys and receipts do not work in production, and production keys and receipts do not work in sandbox.
+9. **Not handling `DCError.invalidKey`.** Check for repeated attestation, unattested assertion keys, or service rejection; regenerate only after the state is known bad.
 
 ## Review Checklist
 
-- [ ] `DCAppAttestService.isSupported` checked before use; fallback to `DCDevice` when unsupported
-- [ ] Key generated once and `keyId` persisted in Keychain
-- [ ] Attestation performed once per key; attestation object sent to server
-- [ ] Server validates attestation against Apple's App Attest root CA
-- [ ] Assertions generated for each sensitive request; server verifies signature and counter
-- [ ] `DCError` cases handled: `.serverUnavailable` with retry, `.invalidKey` with key regeneration
-- [ ] App Attest environment entitlement set correctly for debug vs. production
+- [ ] `DCDevice` tokens generated per server operation and never cached for reuse
+- [ ] `DCAppAttestService.isSupported` checked before use; unsupported devices and extension types have a fallback
+- [ ] Key generated once per user account on each device and `keyId` persisted only for that app account/device
+- [ ] Attestation performed once per key; server stores verified public key and receipt
+- [ ] Server validates attestation certificate chain, App ID hash, environment `aaguid`, credential ID, and nonce `SHA256(authData || SHA256(challenge))`
+- [ ] Assertions include one-time challenge plus request context; server verifies signature, RP ID, counter, challenge, and request binding
+- [ ] Protected endpoints still enforce normal user authentication and entitlement authorization after App Attest passes
+- [ ] `DCError` cases handled: `.serverUnavailable` retries attestation with the same key/hash; bad keys are discarded and regenerated
+- [ ] App Attest environment entitlement and sandbox/production server routing are consistent
 - [ ] Gradual rollout considered; feature flag in place for enabling/disabling
+
+## References
+
+- Extended patterns: [references/device-integrity-patterns.md](references/device-integrity-patterns.md)
+- [DeviceCheck framework](https://sosumi.ai/documentation/devicecheck)
+- [DCDevice](https://sosumi.ai/documentation/devicecheck/dcdevice)
+- [DCAppAttestService](https://sosumi.ai/documentation/devicecheck/dcappattestservice)
+- [Establishing your app's integrity](https://sosumi.ai/documentation/devicecheck/establishing-your-app-s-integrity)
+- [Validating apps that connect to your server](https://sosumi.ai/documentation/devicecheck/validating-apps-that-connect-to-your-server)
+- [Attestation Object Validation Guide](https://sosumi.ai/documentation/devicecheck/attestation-object-validation-guide)
+- [App Attest Environment](https://sosumi.ai/documentation/bundleresources/entitlements/com.apple.developer.devicecheck.appattest-environment)

package/pipeline/skills/shared/external/device-integrity/evals/evals.json

@@ -0,0 +1,45 @@
+{
+  "skill_name": "device-integrity",
+  "evals": [
+    {
+      "id": 0,
+      "name": "app-attest-attestation-verifier",
+      "prompt": "We're adding server-side App Attest verification for an iOS app. The client sends keyId, attestationObject, and the original one-time challenge. What exact checks should the verifier perform before storing anything?",
+      "expected_output": "A source-grounded App Attest attestation verification checklist that covers CBOR/certificate validation, nonce composition, App ID and environment checks, credential ID/keyId checks, and storing verified public key plus receipt.",
+      "files": [],
+      "expectations": [
+        "Computes `clientDataHash = SHA256(challenge)`, then verifies the certificate nonce against `SHA256(authData || clientDataHash)` rather than `SHA256(challenge)` alone.",
+        "Names the credential certificate extension OID `1.2.840.113635.100.8.2` as the source of the nonce value to compare.",
+        "Verifies the App ID/RP ID hash, environment `aaguid`, initial counter, `credentialId`, and keyId/public-key hash relationship.",
+        "Stores the verified public key and receipt for future assertion and fraud-risk use instead of treating the raw attestation object as the trusted durable record."
+      ]
+    },
+    {
+      "id": 1,
+      "name": "app-attest-sensitive-request-assertion",
+      "prompt": "Design the App Attest assertion contract for a premium-content download endpoint. The app already has an attested key. What should the client sign and what should the server verify on every sensitive request?",
+      "expected_output": "A replay-safe assertion design that signs client data containing a server challenge and request context, then verifies assertion CBOR, signature, RP ID, counter, challenge, and request binding server-side.",
+      "files": [],
+      "expectations": [
+        "Requires a fresh one-time server challenge for the assertion flow and embeds it in the client data.",
+        "Includes request context or a request-body hash in the signed client data so the assertion is bound to the sensitive request.",
+        "Verifies the assertion signature over `SHA256(authenticatorData || SHA256(clientData))` using the public key stored from attestation.",
+        "Checks the RP ID hash, monotonically increasing counter, and embedded challenge before accepting the request."
+      ]
+    },
+    {
+      "id": 2,
+      "name": "device-integrity-boundary-and-errors",
+      "prompt": "Review this plan: cache a DCDevice token for the whole install, use one App Attest key for all users, retry any attestKey failure with a new key immediately, treat invalidKey as an OS update problem, and add OAuth/session-token/certificate-pinning advice to the same device-integrity checklist. What should be corrected?",
+      "expected_output": "A boundary-aware correction list that fixes DeviceCheck token reuse, App Attest key scope, retry/error handling, environment behavior, and routes unrelated authentication/network security work to sibling guidance.",
+      "files": [],
+      "expectations": [
+        "States that `DCDevice.generateToken()` tokens are single-use and should not be cached for the whole install.",
+        "Requires App Attest keys to be unique per user account on each device and warns against unnecessary key generation because it affects risk metrics.",
+        "For `serverUnavailable`, retries attestation later with the same key and same `clientDataHash`; for other attestation errors, discards the key identifier before a new-key retry.",
+        "Describes `invalidKey` using Apple-documented causes: already-attested key, unattested assertion key, or service rejection, without attributing it to OS updates or Secure Enclave resets.",
+        "Keeps OAuth/session-token design, certificate pinning, and broad networking security out of the device-integrity checklist except as sibling-skill handoffs."
+      ]
+    }
+  ]
+}