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.
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:
-
Environment Configuration:
- Needs the following environment secrets:
APPLE_KEY_ID
,APPLE_PRIVATE_KEY
, andAPPLE_DEVELOPER_ID
. - You can follow instructions on generating a private key with your Apple ID here
- Needs the following environment secrets:
-
OAuth JWT Generation:
- Uses the
jose
library to create a JWT (JSON Web Token) for authenticating requests to Apple's DeviceCheck API.
- Uses the
-
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.
-
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:
-
Device Token Generation:
- Uses Apple's
DCDevice
to generate a device token on an iOS device.
- Uses Apple's
-
Request to Checkr Worker:
- Sends the generated device token to the
checkr
worker.
- Sends the generated device token to the
-
Validation Workflow:
- The
checkr
worker forwards the request to thecheckd
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.
- The
- Worker: The main implementation file
src/index.ts
and configuration files (wrangler.toml
,tsconfig.json
). - iOS App:
ContentView.swift
managing the UI flow, andSessionHandler.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.
- Fork the repository on GitHub.
- Clone the fork to your local machine.
- Create a new branch for your feature or bugfix.
- Make your changes.
- 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.