English | 中文
An automated Web Key Directory (WKD) distribution solution based on Cloudflare Workers & Assets. Simply store your PGP public keys in the repository to automatically deploy a globally distributed public key query service.
What is WKD? | Automated z-base-32 hash mapping | Zero-maintenance
- Automated Build: No need to manually calculate complex WKD hashes. GitHub Actions automatically parses the directory and generates the mappings.
- Global Acceleration: Leverages the Cloudflare Edge network to provide ultra-fast public key retrieval responses worldwide.
- Strong Compatibility: Supports both Advanced and Direct WKD query modes simultaneously.
- GitOps Workflow: Manage your public keys just like code. Adding a new user is as simple as a
git push.
Click the Fork button at the top of the repository to create a new private or public repository.
Note: For repositories created via Fork, GitHub disables Actions by default. Please go to the Actions tab of your repository and click the "I understand my workflows, go ahead and enable them" button.
To prevent deploying sample data, please clean up the directory first:
- Clean Directory: Delete all existing subfolders under the
keys/folder (i.e., remove the example domain and keys). - Export Keys: Export your binary public key (must contain the Email you want to host):
# Export public key, recommended to strip third-party signatures to reduce size (Recommended) # If your email is alice@example.com, your filename must be alice.gpg gpg --export --export-options export-clean alice@example.com > alice.gpg # If you want to include all third-party signatures, omit --export-options export-clean. gpg --export alice@example.com > alice.gpg
- Store by Structure: Place the exported
.gpgfile into the folder corresponding to the domain:- Path format:
keys/{domain}/{username}.gpg - Example:
keys/example.com/alice.gpg
- Path format:
Add the following Repository Secrets in your GitHub repository under Settings -> Secrets and variables -> Actions:
CLOUDFLARE_API_KEY: Your Cloudflare API Token (Must have Workers deployment permissions; the "Edit Cloudflare Workers" template is recommended).CLOUDFLARE_ACCOUNT_ID: Your Cloudflare Account ID.
Simply push your changes to Git, and GitHub Actions will automatically calculate the hashes and deploy:
git add .
git commit -m "feat: setup my wkd keys"
git push origin mainAfter Github Actions completes the deployment, go to the Cloudflare Dashboard.
Find the gpg-wkd-worker Worker. Under Settings -> Domains & Routes, add your email domain to the Worker:
- Supports both
openpgpkey.<email-domain>and<email-domain>formats; both can be used simultaneously.
If you want to develop locally or prefer manual deployment via CLI, follow these steps. Since key-manifest.json is generated dynamically, you need to run the generation script manually.
Ensure Node.js is installed (Node.js v22+ required) and login to Wrangler:
npm install
npx wrangler loginBefore deploying, you must place the keys correctly in the keys/ directory and run the script to generate src/key-manifest.json:
# Run the generation script (Ensure you are in the project root directory)
node generate-manifest.mjsUpon success, you should see a prompt indicating the number of generated keys in the terminal.
npx wrangler deployAfter the deployment is complete, go to the Cloudflare Dashboard.
Find the gpg-wkd-worker Worker. Under Settings -> Domains & Routes, add your email domain to the Worker. Supports both openpgpkey.<email-domain> and <email-domain> formats; both can be used simultaneously.
After deployment, you can verify if the service is working normally in two ways:
Method 1: Command Line Verification (GnuPG)
# Locate external keys using GnuPG directly
gpg --locate-external-keys --auto-key-locate wkd your-email@example.comIf successful, you should see a message indicating the public key has been automatically imported.
Method 2: Online Tool Verification
Visit the Web Key Directory Validator and enter your Email address for testing.