/devicecheck-app-attest-workflow

name: devicecheck-app-attest-workflow
description: Guide DeviceCheck and App Attest adoption in Apple-platform apps using DCDevice, DCAppAttestService, app IDs, entitlements, server challenges, attestation objects, assertions, receipts, fraud-risk metrics, sandbox/production environments, rollout planning, and explicit client/server handoffs. Use when implementing or diagnosing DeviceCheck per-device two-bit state, App Attest app-instance integrity, Apple server API validation, App Attest environment setup, macOS App Attest verification, App Clip key-sharing, supported extension contexts, or fraud-risk integration that must be checked against current Apple documentation.

DeviceCheck App Attest Workflow

Purpose

Guide DeviceCheck and App Attest implementation decisions without confusing app-side Apple framework calls with server-side trust decisions.

The practical decision is whether the app needs DeviceCheck two-bit device state, App Attest app-instance integrity, both signals, or a different auth/session/sync workflow. The skill keeps Apple docs, Xcode signing state, server challenges, replay protection, rollout constraints, and backend handoffs visible before implementation starts.

When To Use

• Use this skill when adding or diagnosing `DCDevice`, `generateToken(completionHandler:)`, Apple DeviceCheck query/update/validate endpoints, or the two per-device bits Apple stores for an app.
• Use this skill when adding or diagnosing `DCAppAttestService`, `generateKey(completionHandler:)`, `attestKey(_:clientDataHash:completionHandler:)`, `generateAssertion(_:clientDataHash:completionHandler:)`, or `DCError`.
• Use this skill when the work involves App Attest App ID registration, DeviceCheck capabilities, the `com.apple.developer.devicecheck.appattest-environment` entitlement, sandbox versus production behavior, TestFlight or App Store rollout, Enterprise distribution, Developer ID, or macOS signing validation.
• Use this skill when the app and server need a challenge, attestation, assertion, receipt, public-key, counter, or fraud-risk metric contract.
• Use this skill when replacing custom device identifiers, local-only jailbreak checks, receipt-only abuse checks, or ad hoc risk flags with Apple-supported DeviceCheck or App Attest signals.
• Recommend `swift-openapi-client-workflow` when the primary task is generated API client setup for the app-to-server transport.
• Recommend `xcode-build-run-workflow` when the next step is target setup, entitlements, signing, App ID capability wiring, build, run, simulator, device, or guarded Xcode project mutation.
• Recommend `xcode-testing-workflow` when the next step is repeatable XCTest, XCUITest, simulator/device matrix checks, or test-plan setup.
• Recommend server-side Swift, OpenAPI, RPC, or backend-specific workflows when the primary task is implementing server verification, persistence, JWT generation, API routes, or fraud-risk policy.
• Recommend the broader client auth and sync workflow when the request is really Keychain storage, Sign in with Apple, `ASWebAuthenticationSession`, token refresh, logout, multi-account state, or app sync.

Single-Path Workflow

1. Classify the integrity request:

• DeviceCheck two-bit state with `DCDevice`
• App Attest app-instance integrity with `DCAppAttestService`
• combined DeviceCheck plus App Attest risk signal
• App ID, entitlement, signing, or environment setup
• server verification, receipt, counter, or fraud metric work
• broader auth, Keychain, token refresh, generated client, or app-sync work

2. Apply the Apple docs gate before recommending shape:

• read the relevant DeviceCheck, App Attest, entitlement, CryptoKit, code-signing, or platform documentation first
• state the documented Apple behavior being relied on
• if Apple docs and current code disagree, stop and surface that conflict
• if no relevant Apple documentation can be found, say that explicitly before proceeding

3. Choose the supported signal:

• use DeviceCheck when the server needs Apple-hosted per-device two-bit state for a narrow abuse, promotion, or fraud flag
• use App Attest when the server needs evidence that a request comes from a legitimate app instance using an attested key
• use both only when the risk policy has a concrete reason to combine per-device state with app-instance assertions
• do not use either as a replacement for user authentication, authorization, server-side rate limiting, or normal abuse monitoring

4. Plan the client/server boundary:

• app checks availability and requests server challenges
• app generates DeviceCheck tokens, App Attest keys, attestations, or assertions
• server verifies tokens, attestations, assertions, receipts, counters, app identifiers, environments, and replay protections
• server owns the risk decision and user-visible fallback behavior

5. Plan storage and lifecycle:

• persist App Attest key identifiers because the private key is not directly readable and the key ID cannot be recovered later
• do not persist server challenges for reuse
• keep development/sandbox and production App Attest records separate
• expect App Attest keys to survive ordinary app updates but not reinstall, migration, or device restore
• keep DeviceCheck bit meanings documented server-side

6. Plan rollout and validation:

• handle unsupported devices gracefully on both client and server
• model sandbox and production endpoint differences before rollout
• avoid immediate large-population App Attest onboarding when Apple guidance calls for ramping
• route Xcode signing, entitlements, build, run, simulator, and device checks to Xcode skills

7. Return one recommendation path with:

• selected signal
• documented Apple behavior relied on
• app calls and storage plan
• server verification and persistence plan
• environment and entitlement plan
• validation and rollout plan
• explicit handoffs for Xcode,