checkd is a Cloudflare Workers-based server implementation for Apple's DeviceCheck framework, enabling easy validation of requests made by valid Apple devices. This project provides both the core service worker (checkd) and example projects (checkr iOS app and worker) to demonstrate how to use checkd in an end-to-end workflow.

1. Core Implementation
2. Examples for End-to-End Workflow
3. Setup and Installation
4. Contributing
5. License

The checkd service worker provides the functionality to validate whether an Apple device token is legitimate by interfacing with Apple's DeviceCheck API. Here’s how it works:

1. Environment Configuration:

   • Needs the following environment secrets: APPLE_KEY_ID, APPLE_PRIVATE_KEY, and APPLE_DEVELOPER_ID.
   • You can follow instructions on generating a private key with your Apple ID here

2. OAuth JWT Generation:

   • Uses the jose library to create a JWT (JSON Web Token) for authenticating requests to Apple's DeviceCheck API.

3. Device Token Validation:

   • Receives the device token from incoming requests.
   • Constructs a JWT containing the device token and other required claim information.
   • Sends the JWT to Apple's DeviceCheck API for validation.

4. Response Handling:

   • Processes the response from Apple's DeviceCheck API to return whether the validation succeeded or failed.

• src/index.ts: The main worker file where the functionality resides.
• wrangler.toml: Configuration file for deploying the worker with Cloudflare Wrangler.
• tsconfig.json: TypeScript configuration file.
• Environment Variables: These include APPLE_KEY_ID, APPLE_PRIVATE_KEY, APPLE_DEVELOPER_ID.

To showcase the functionality of checkd, the project includes example implementations—a companion worker (checkr) and an iOS app (checkr).

The checkr worker acts as an intermediary between the client (iOS app) and the checkd service worker.

The checkr iOS App demonstrates client-side implementation:

1. Device Token Generation:

   • Uses Apple's DCDevice to generate a device token on an iOS device.

2. Request to Checkr Worker:

   • Sends the generated device token to the checkr worker.

3. Validation Workflow:

   • The checkr worker forwards the request to the checkd service worker.
   • The checkd worker then validates the device token with Apple's DeviceCheck API.
   • Returns the validation result back through the checkr worker to the iOS app.

• Worker: The main implementation file src/index.ts and configuration files (wrangler.toml, tsconfig.json).
• iOS App: ContentView.swift managing the UI flow, and SessionHandler.swift handling the DeviceCheck logic.

To set up and run the checkd project, follow these steps:

git clone https://github.com/yourusername/checkd.git
cd checkd

For the checkd worker:

cd checkd
npm install

For the checkr worker:

cd checkd/examples/worker
npm install

For the iOS app:

cd checkd/examples/app/checkr
# Open the Xcode project or workspace file, resolve dependencies if needed

Define the required environment variables (APPLE_KEY_ID, APPLE_PRIVATE_KEY, APPLE_DEVELOPER_ID) in the wrangler.toml file or via the Cloudflare Dashboard.

Deploy the checkd and checkr workers:

For checkd:

cd checkd
npm run deploy

For checkr:

cd checkd/examples/worker
npm run deploy

Open checkd/examples/app/checkr/checkr.xcodeproj in Xcode, configure your signing information, and build and run the app on a physical device. Device tokens cannot be generated in a simulator.

We welcome contributions to enhance checkd. Feel free to open issues and submit PRs on our GitHub repository.

1. Fork the repository on GitHub.
2. Clone the fork to your local machine.
3. Create a new branch for your feature or bugfix.
4. Make your changes.
5. Push the branch to GitHub and open a pull request.

Make sure to add tests for your changes. Ensure that all existing and new tests pass before submitting a pull request.

checkd is licensed under the MIT License. See the LICENSE file for more details.