@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

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

@@ -1,439 +1,316 @@
 ---
 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 a backend architecture."
+description: "DeviceCheck and App Attest: DCDevice tokens and per-device bits, DCAppAttestService key generation, attestation and assertions. Use when adding fraud prevention, detecting compromised devices, validating app authenticity with Apple's servers, protecting sensitive endpoints with attested requests, or designing backend device verification. Not for sign-in, OAuth, JWT sessions, TLS or pinning."
 metadata:
-  source: "dpearson2699/swift-ios-skills (PolyForm Perimeter 1.0.0)"
+  source: multi-agent-pipeline
 ---
 
 # Device Integrity
 
-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.
+Two frameworks let a backend decide whether a request really originates from
+real Apple hardware running an unmodified build of your app:
 
-## Contents
+- **DeviceCheck** (`DCDevice`) hands your server a token it can trade with Apple
+  for two developer-defined bits per device. Good for simple flags such as
+  "this phone already redeemed the trial".
+- **App Attest** (`DCAppAttestService`) creates a hardware key inside the Secure
+  Enclave, has Apple certify it, and then signs chosen requests with it. Good
+  for cryptographic proof on sensitive calls.
 
-- [DCDevice (DeviceCheck Tokens)](#dcdevice-devicecheck-tokens)
-- [DCAppAttestService (App Attest)](#dcappattestservice-app-attest)
-- [App Attest Key Generation](#app-attest-key-generation)
-- [App Attest Attestation Flow](#app-attest-attestation-flow)
-- [App Attest Assertion Flow](#app-attest-assertion-flow)
-- [Server Verification Guidance](#server-verification-guidance)
-- [Error Handling](#error-handling)
-- [Common Patterns](#common-patterns)
-- [Common Mistakes](#common-mistakes)
-- [Review Checklist](#review-checklist)
-- [References](#references)
+Server algorithms, retries, rejected-key recovery, an integration outline and
+rollout advice live in the [patterns reference](references/device-integrity-patterns.md).
+The `IntegrityError` enum used below is defined there too.
 
-## DCDevice (DeviceCheck Tokens)
+## DeviceCheck tokens (`DCDevice`, iOS 11+)
 
-[`DCDevice`](https://sosumi.ai/documentation/devicecheck/dcdevice) generates a
-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
+`DCDevice` produces an ephemeral token that identifies the device to Apple.
+Each token is single-use: create a fresh one for every server operation and
+never cache it. The server forwards the token to Apple to read or change the
+two bits.
 
 ```swift
 import DeviceCheck
 
-func generateDeviceToken() async throws -> Data {
-    guard DCDevice.current.isSupported else {
-        throw DeviceIntegrityError.deviceCheckUnsupported
-    }
-
-    return try await DCDevice.current.generateToken()
+func sendJSON(_ fields: [String: String], to url: URL) async throws -> Bool {
+    var req = URLRequest(url: url)
+    req.httpMethod = "POST"
+    req.addValue("application/json", forHTTPHeaderField: "Content-Type")
+    let payload = try JSONEncoder().encode(fields)
+    let (_, reply) = try await URLSession.shared.upload(for: req, from: payload)
+    return (reply as? HTTPURLResponse).map { $0.statusCode == 200 } ?? false
 }
-```
-
-### Sending the Token to Your Server
 
-```swift
-func sendTokenToServer(_ token: Data) async throws {
-    let tokenString = token.base64EncodedString()
-
-    var request = URLRequest(url: serverURL.appending(path: "verify-device"))
-    request.httpMethod = "POST"
-    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
-    request.httpBody = try JSONEncoder().encode(["device_token": tokenString])
-
-    let (_, response) = try await URLSession.shared.data(for: request)
-    guard let httpResponse = response as? HTTPURLResponse,
-          httpResponse.statusCode == 200 else {
-        throw DeviceIntegrityError.serverVerificationFailed
-    }
+func claimTrial(at endpoint: URL) async throws {
+    guard DCDevice.current.isSupported else { throw IntegrityError.deviceCheckUnsupported }
+    let token = try await DCDevice.current.generateToken()   // new token every call
+    let accepted = try await sendJSON(["device_token": token.base64EncodedString()], to: endpoint)
+    if !accepted { throw IntegrityError.serverVerificationFailed }
 }
 ```
 
-### Server-Side Overview
-
-Your server uses the device token to call Apple's DeviceCheck API endpoints:
-
-| Endpoint | Purpose |
-|----------|---------|
-| `https://api.devicecheck.apple.com/v1/query_two_bits` | Read the two bits for a device |
-| `https://api.devicecheck.apple.com/v1/update_two_bits` | Set the two bits for a device |
-| `https://api.devicecheck.apple.com/v1/validate_device_token` | Validate a device token without reading bits |
+### What the server does
 
-The server authenticates with a DeviceCheck private key from the Apple Developer
-portal, creating a signed JWT for each request.
+All three calls live under `/v1/` on the DeviceCheck host:
 
-Use `https://api.development.devicecheck.apple.com` only while testing; use
-`https://api.devicecheck.apple.com` for production.
+| Path | Purpose |
+|---|---|
+| `query_two_bits` | Returns the current bit values |
+| `update_two_bits` | Changes one or both bits |
+| `validate_device_token` | Confirms a token is real, bits untouched |
 
-### What the Two Bits Are For
+The server signs a JWT for each call with a DeviceCheck private key created in
+the Developer portal. Hosts: `api.devicecheck.apple.com` for production traffic,
+and `api.development.devicecheck.apple.com` only while testing.
 
-Apple stores two Boolean values per device per developer team. You decide what
-they mean. Common uses:
+### The two bits
 
-- **Bit 0:** Device has claimed a promotional offer.
-- **Bit 1:** Device has been flagged for fraud.
+Apple keeps two Booleans per device for each developer team, and you decide
+what they mean. For example bit 0 might record "promo redeemed" and bit 1
+"flagged for abuse". They survive deleting and reinstalling the app; only
+your server can reset them through the API.
 
-Bits persist across app reinstall. You control when to reset them via the
-server API.
+## App Attest (`DCAppAttestService`, iOS 14+)
 
-## DCAppAttestService (App Attest)
+App Attest ties a specific app instance on a specific device to a Secure
+Enclave key. It runs in three phases:
 
-[`DCAppAttestService`](https://sosumi.ai/documentation/devicecheck/dcappattestservice)
-validates that a specific instance of your app on a specific device is
-legitimate. It uses a hardware-backed key in the Secure Enclave to create
-cryptographic attestations and assertions. Available on iOS 14+.
+1. **Key generation** - the Secure Enclave makes a key pair.
+2. **Attestation** - Apple vouches that this key sits on real hardware inside
+   your app.
+3. **Assertion** - sign chosen requests with the attested key.
 
-The flow has three phases:
-1. **Key generation** -- create a key pair in the Secure Enclave.
-2. **Attestation** -- Apple certifies the key belongs to a genuine Apple device running your app.
-3. **Assertion** -- sign server requests with the attested key to prove ongoing legitimacy.
-
-### Checking Support
+### Support check
 
 ```swift
-import DeviceCheck
-
-let attestService = DCAppAttestService.shared
-
-guard attestService.isSupported else {
-    // Fall back to DCDevice token or other risk assessment.
-    // App Attest is not available on simulators or all device models.
-    return
+let attest = DCAppAttestService.shared
+if !attest.isSupported {
+    // Fall back to a DCDevice token or another risk signal.
 }
 ```
 
-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`.
+The service is unavailable in the Simulator and on some hardware. For app
+extensions only Action, extensible single sign-on and watchOS extensions are
+supported; treat any other extension type as unsupported even when
+`isSupported` returns true.
 
-## App Attest Key Generation
+### Key generation
 
-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
+Make one key for each signed-in account on a given device. Its private half never leaves
+the Secure Enclave and the returned `keyId` is your only handle to it, so store
+it and reuse it for that account on that device. Never share a key between
+users, and avoid regenerating: every new key moves Apple's per-device key
+count, which feeds risk metrics. Treat a `keyId` as usable only once your
+server accepts its attestation; if verification fails, discard it and make a
 new key before retrying.
 
 ```swift
 import DeviceCheck
+import Foundation
+import Security
 
-actor AppAttestManager {
+actor AttestKeyStore {
     private let service = DCAppAttestService.shared
-    private var keyId: String?
+    private let accountID: String
+    var keyID: String?
 
-    /// Generate and record a key pair for App Attest.
-    func generateKeyIfNeeded() async throws -> String {
-        if let existingKeyId = loadKeyIdFromKeychain() {
-            self.keyId = existingKeyId
-            return existingKeyId
-        }
-
-        let newKeyId = try await service.generateKey()
-        saveKeyIdToKeychain(newKeyId)
-        self.keyId = newKeyId
-        return newKeyId
-    }
+    init(accountID: String) { self.accountID = accountID }
 
-    // MARK: - Keychain helpers (simplified)
+    private var keychainAccount: String { "attest-key.\(accountID)" }
 
-    private func saveKeyIdToKeychain(_ keyId: String) {
-        let data = Data(keyId.utf8)
-        let query: [String: Any] = [
+    var baseQuery: [String: Any] {
+        [
             kSecClass as String: kSecClassGenericPassword,
-            kSecAttrAccount as String: "app-attest-key-id-\(currentAccountID)",
-            kSecAttrService as String: Bundle.main.bundleIdentifier ?? "",
-            kSecValueData as String: data,
-            kSecAttrAccessible as String: kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
+            kSecAttrService as String: Bundle.main.bundleIdentifier ?? "attest",
+            kSecAttrAccount as String: keychainAccount,
         ]
-        SecItemDelete(query as CFDictionary) // Remove old if exists
-        SecItemAdd(query as CFDictionary, nil)
     }
 
-    private func loadKeyIdFromKeychain() -> String? {
-        let query: [String: Any] = [
-            kSecClass as String: kSecClassGenericPassword,
-            kSecAttrAccount as String: "app-attest-key-id-\(currentAccountID)",
-            kSecAttrService as String: Bundle.main.bundleIdentifier ?? "",
-            kSecReturnData as String: true,
-            kSecMatchLimit as String: kSecMatchLimitOne
-        ]
-        var result: AnyObject?
-        let status = SecItemCopyMatching(query as CFDictionary, &result)
-        guard status == errSecSuccess, let data = result as? Data else { return nil }
-        return String(data: data, encoding: .utf8)
-    }
-}
-```
-
-**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
-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
-
-```swift
-import DeviceCheck
-import CryptoKit
-
-extension AppAttestManager {
-    /// Attest the key with Apple. Send the attestation object to your server.
-    func attestKey() async throws -> Data {
-        guard let keyId else {
-            throw DeviceIntegrityError.keyNotGenerated
+    func generateKeyIfNeeded() async throws -> String {
+        if let keyID { return keyID }
+        if let stored = loadKeyID() {
+            keyID = stored
+            return stored
         }
-
-        // 1. Request a one-time challenge from your server
-        let challenge = try await fetchServerChallenge()
-
-        // 2. Hash the challenge (Apple requires a SHA-256 hash)
-        let challengeHash = Data(SHA256.hash(data: challenge))
-
-        // 3. Ask Apple to attest the key
-        let attestation = try await service.attestKey(keyId, clientDataHash: challengeHash)
-
-        // 4. Send the attestation object to your server for verification
-        try await sendAttestationToServer(
-            keyId: keyId,
-            attestation: attestation,
-            challenge: challenge
-        )
-
-        return attestation
+        let fresh = try await service.generateKey()
+        try saveKeyID(fresh)
+        keyID = fresh
+        return fresh
     }
 
-    private func fetchServerChallenge() async throws -> Data {
-        let url = serverURL.appending(path: "attest/challenge")
-        let (data, _) = try await URLSession.shared.data(from: url)
-        return data
+    private func saveKeyID(_ value: String) throws {
+        SecItemDelete(baseQuery as CFDictionary)
+        var item = baseQuery
+        item[kSecValueData as String] = Data(value.utf8)
+        item[kSecAttrAccessible as String] = kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly
+        let status = SecItemAdd(item as CFDictionary, nil)
+        guard status == errSecSuccess else { throw IntegrityError.keyNotGenerated }
     }
 
-    private func sendAttestationToServer(
-        keyId: String,
-        attestation: Data,
-        challenge: Data
-    ) async throws {
-        var request = URLRequest(url: serverURL.appending(path: "attest/verify"))
-        request.httpMethod = "POST"
-        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
-
-        let payload: [String: String] = [
-            "key_id": keyId,
-            "attestation": attestation.base64EncodedString(),
-            "challenge": challenge.base64EncodedString()
-        ]
-        request.httpBody = try JSONEncoder().encode(payload)
-
-        let (_, response) = try await URLSession.shared.data(for: request)
-        guard let httpResponse = response as? HTTPURLResponse,
-              httpResponse.statusCode == 200 else {
-            throw DeviceIntegrityError.attestationVerificationFailed
-        }
+    private func loadKeyID() -> String? {
+        var query = baseQuery
+        query[kSecReturnData as String] = true
+        query[kSecMatchLimit as String] = kSecMatchLimitOne
+        var found: CFTypeRef?
+        let status = SecItemCopyMatching(query as CFDictionary, &found)
+        guard status == errSecSuccess, let bytes = found as? Data else { return nil }
+        return String(data: bytes, encoding: .utf8)
     }
 }
 ```
 
-### Server-Side Attestation Verification
+Save, load and delete all build on the same `baseQuery`, so the account
+attribute always carries the account suffix. The delete path in the
+[rejected-key section](references/device-integrity-patterns.md#rejected-keys)
+reuses it for that reason.
 
-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.
+### Attestation
 
-## App Attest Assertion Flow
+Attestation proves the key was created on a real device inside your genuine
+app. Do it once per key. The server records the public key and receipt it verified;
+the app keeps using the `keyId` for assertions once the server has accepted it.
 
-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
+Client order: ask the server for a one-time challenge, hash it with SHA-256,
+call `attestKey(_:clientDataHash:)`, and upload the result.
 
 ```swift
-import DeviceCheck
 import CryptoKit
 
-extension AppAttestManager {
-    /// 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
-        }
-
-        let clientDataHash = Data(SHA256.hash(data: clientData))
+extension AttestKeyStore {
+    func attest(challenge: Data, uploadTo url: URL) async throws {
+        let keyID = try await generateKeyIfNeeded()
+        let hash = Data(SHA256.hash(data: challenge))
+        let attestation = try await DCAppAttestService.shared.attestKey(keyID, clientDataHash: hash)
 
-        return try await service.generateAssertion(keyId, clientDataHash: clientDataHash)
+        let accepted = try await sendJSON([
+            "key_id": keyID,
+            "attestation": attestation.base64EncodedString(),
+            "challenge": challenge.base64EncodedString(),
+        ], to: url)
+        guard accepted else { throw IntegrityError.attestationVerificationFailed }
     }
 }
 ```
 
-### Using Assertions in Network Requests
+On the server: parse the CBOR object, walk its certificates up to Apple's
+App Attest root, check the nonce, then persist the public key and receipt. The
+nonce is **not** `SHA256(challenge)`. It is `SHA256(authData || SHA256(challenge))`,
+and it has to match the octet string stored under OID `1.2.840.113635.100.8.2`
+in the leaf certificate.
+
+### Assertion
+
+An assertion signs one sensitive request and embeds a server-issued, one-time
+challenge so a captured request cannot be replayed. Call
+`generateAssertion(_:clientDataHash:)` with the SHA-256 of encoded client data
+that holds the challenge plus request context.
 
 ```swift
-struct AppAttestClientData: Encodable {
+struct SignedRequestContext: Codable {
     let challenge: String
     let method: String
     let path: String
-    let bodySHA256: String
+    let bodyDigest: String
 }
 
-extension AppAttestManager {
-    /// Perform an attested API request.
-    func makeAttestedRequest(
-        to url: URL,
-        method: String = "POST",
-        body: Data
-    ) async throws -> (Data, URLResponse) {
-        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
-            )
+extension AttestKeyStore {
+    func signed(_ original: URLRequest, body: Data, challenge: Data) async throws -> URLRequest {
+        var request = original
+        let keyID = try await generateKeyIfNeeded()
+        let context = SignedRequestContext(
+            challenge: challenge.base64EncodedString(),
+            method: request.httpMethod ?? "GET",
+            path: request.url?.path ?? "/",
+            bodyDigest: SHA256.hash(data: body).map { String(format: "%02x", $0) }.joined()
         )
-        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-Attest-Assertion")
-        request.setValue(clientData.base64EncodedString(), forHTTPHeaderField: "X-App-Attest-Client-Data")
+        let encoded = try JSONEncoder().encode(context)
+        let assertion = try await DCAppAttestService.shared.generateAssertion(
+            keyID, clientDataHash: Data(SHA256.hash(data: encoded))
+        )
+        let headers = [
+            "X-App-Attest-Assertion": assertion.base64EncodedString(),
+            "X-App-Attest-Client-Data": encoded.base64EncodedString(),
+        ]
+        headers.forEach { request.addValue($0.value, forHTTPHeaderField: $0.key) }
         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)
+        return request
     }
 }
 ```
 
-### Server-Side Assertion Verification
-
-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
-
-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.
-
-### Security Boundaries
-
-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
-
-Handle `DCError` codes from DeviceCheck operations. Key cases:
-
-- `.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`
-
-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
-
-### Environment Entitlement
-
-Set the App Attest environment in your entitlements file. Use `development`
-during testing and `production` for App Store builds:
-
-```xml
-<key>com.apple.developer.devicecheck.appattest-environment</key>
-<string>production</string>
-```
-
-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.
-
-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 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
-
-- [ ] `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
+Fetch a new assertion challenge from your challenge endpoint for every request.
+
+Server side: decode the CBOR assertion, inspect authenticator data and its
+counter, hash the client data it received to get `clientDataHash` again, check
+that the stored public key signed `SHA256(authenticatorData || clientDataHash)`,
+and make sure the challenge and the request context both line up.
+
+## Security boundaries
+
+App Attest says "this request came from a genuine instance of the app". It
+says nothing about who the user is. Sign-in, OAuth or JWT sessions, how API
+tokens are designed, paid-feature and subscription checks, TLS and certificate
+pinning all remain separate jobs. Keep enforcing authentication and authorization after the
+attestation check passes. Hand-offs:
+
+- Apple ID sign-in, passkeys, OAuth flows, credential state: `authentication`
+- Keychain policy, Secure Enclave, pinning, storage hardening: `swift-security`
+- Hashing and signing primitives: `cryptokit`
+- Transport, request pipelines, TLS configuration: `ios-networking`
+
+## Errors
+
+| `DCError.Code` | Meaning | Action |
+|---|---|---|
+| `.serverUnavailable` | Apple's service is temporarily unreachable | Retry with exponential backoff |
+| `.invalidKey` | Key already attested, assertion with an unattested key, or key rejected | Find out which, then recover |
+| `.featureUnsupported` | Device or OS lacks App Attest | Use `DCDevice` tokens instead |
+| `.invalidInput` | Malformed `clientDataHash` or `keyId` | Fix the caller |
+
+When `attestKey` reports `.serverUnavailable`, try again later passing the
+**same** `keyId` and the **same** `clientDataHash`. Any other attestation
+failure means the key identifier is spent: drop it and make a fresh key first.
+
+## Environment entitlement
+
+The App Attest environment entitlement
+(`com.apple.developer.devicecheck.appattest-environment`) takes `development`
+for testing or `production` for release. Without it, development builds talk
+to the App Attest sandbox. TestFlight, App Store and Enterprise Program builds
+ignore the value and always use production.
+
+## Common mistakes
+
+- Generating a key on every launch instead of once per account per device.
+- Caching or reusing a `DCDevice` token.
+- No fallback path for unsupported devices or extension types.
+- Trusting attestation on the client. Only the server can verify it.
+- Signing just the raw body. Include the one-time challenge and request context.
+- Checking the nonce as `SHA256(challenge)`.
+- No replay defense. The backend has to accept each challenge once and keep the per-key counter moving forward.
+- Mixing environments. Sandbox keys and receipts fail against production and the reverse.
+- Regenerating on `invalidKey` without knowing why. Establish whether the key
+  was already attested, never attested, or rejected, and only replace it when
+  its state is known to be bad.
+
+## Review checklist
+
+- [ ] A new `DCDevice` token per operation; none cached
+- [ ] `isSupported` checked, with a fallback for devices and extension types that lack App Attest
+- [ ] One key per account per device; `keyId` stored only for that account on that device
+- [ ] Keychain save, load and delete all use the same account-scoped query
+- [ ] One attestation per key; server keeps the public key and receipt
+- [ ] Attestation verifier covers: certificates, App ID hash, `aaguid` for the environment, credential ID, and a nonce of `SHA256(authData || SHA256(challenge))`
+- [ ] Each assertion signs a challenge plus request context; the backend checks the signature, RP ID, counter, the challenge and how it binds to the request
+- [ ] Protected endpoints still require user authentication and authorization
+- [ ] `DCError` handled: `.serverUnavailable` retried with same key and hash, bad keys discarded and regenerated
+- [ ] Environment entitlement agrees with sandbox or production server routing
+- [ ] Rollout gated behind a feature flag
 
 ## 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)
+- [Patterns reference](references/device-integrity-patterns.md) - server verification steps, architecture, retries, rejected keys, rollout
+- Apple documentation: [DeviceCheck](https://developer.apple.com/documentation/devicecheck),
+  [DCDevice](https://developer.apple.com/documentation/devicecheck/dcdevice),
+  [DCAppAttestService](https://developer.apple.com/documentation/devicecheck/dcappattestservice),
+  plus the DeviceCheck articles on app integrity, server-side validation,
+  attestation objects and the environment entitlement (see the patterns reference)