worker

PGP Worker

Cloudflare Worker for pgp.kareem.one that serves the public key material and WKD endpoints from a durable KV cache with an automatic GitHub fallback.

Overview

• Serves static PGP assets (e.g. /shaquille.asc, /.well-known/openpgpkey/...) with CORS and WKD-friendly headers.
• Reads from the PGP_ASSETS KV namespace first; on a miss it fetches from the public GitHub mirror and writes the response back to KV.
• Stores KV payloads as base64-encoded bytes in bulk manifests to preserve binary WKD packets.
• Keeps assets in KV for 30 days by default — rotation workflows refresh the content ahead of key changes.
• Requests to / are rewritten to the asset defined by ROOT_OBJECT (defaults to /public-masterkey.asc) and returned with text/plain so the root URL streams the ASCII-armored key directly.
• WKD hu/<hash> aliases are generated automatically from hu/<hash>/<email>.pub files, and shared host / policy files are aliased into the advanced /<domain>/... paths, so standard WKD lookup URLs resolve without web-server rewrites.

Setup

1. Install dependencies:

   cd worker
   npm install

2. Create the KV namespaces (production + preview):

   wrangler kv namespace create pgp-assets
   wrangler kv namespace create pgp-assets-preview --preview

   Copy the resulting IDs into wrangler.toml (id for production, preview_id for preview).

3. (Optional but recommended) Restrict traffic to the intended hostnames by editing ALLOWED_HOSTS in wrangler.toml.

4. Point DNS (pgp CNAME pgp-worker.<account>.workers.dev) and ensure routes in wrangler.toml cover:

   • pgp.kareem.one/*
   • kareem.one/.well-known/openpgpkey/*
   • openpgpkey.kareem.one/.well-known/openpgpkey/*

Syncing Assets

Generate a KV bulk upload manifest from the repository contents:

cd worker
npm run kv:sync -- --out dist/kv-assets.json
npm run kv:validate -- --manifest dist/kv-assets.json

Then push to KV (remote namespaces):

wrangler kv bulk put dist/kv-assets.json --binding=PGP_ASSETS --remote --preview=false
wrangler kv bulk put dist/kv-assets.json --binding=PGP_ASSETS --remote --preview

The worker will now serve content directly from KV. When new keys or WKD files land in the repo, re-run the sync workflow so updates are available instantly without waiting on the GitHub fallback.

The sync script skips files that are absent (e.g. shaquille.asc), so it is safe to run before every rotation.

Pushes to main that touch key material, WKD files, or worker code also trigger ../.github/workflows/refresh-cache.yml, which regenerates the manifest and bulk-uploads the production KV cache automatically.

Developing & Deploying

• npm run dev – local development (requires wrangler authentication).
• npm run deploy – publish the worker once all bindings are configured.

The worker mirrors from https://raw.githubusercontent.com/kareemlukitomo/pgp/main by default. Override GITHUB_MIRROR_BASE in wrangler.toml if you prefer another mirror (e.g. a Forgejo origin).