butttons/hodor

Self-hosted token-injecting HTTP reverse proxy — one stable subdomain per API integration, credentials handled. Cloudflare Workers

Summary

Hodor is a self-hosted, token-injecting HTTP reverse proxy written in TypeScript and deployed through Cloudflare Workers. It gives each configured API integration a stable subdomain and injects the provider credential at request time, allowing callers to use one Hodor key instead of separate upstream credentials.

What it is useful for

Use Hodor when scripts, agents, cron jobs, browsers, or other HTTP clients need to reach several external APIs without carrying raw provider keys in every call. For example, a registry entry can send requests to api.openai.com/v1 while adding a bearer token from an encrypted KV secret; a client then calls openai.example.com/v1/models.

Signed consumer keys can restrict allowed integrations and methods: one key could leave Stripe unrestricted while limiting Razorpay to GET and HEAD. Per-integration rules only narrow global permissions, and except takes precedence. The audit log records callers, destinations, outcomes, rejections, and upstream failures.

How engineers can use it

The documented manual Cloudflare setup starts with:

npx wrangler kv namespace create HODOR_KV
cd apps/proxy-worker
npx wrangler deploy --secrets-file .dev.vars

Put the returned namespace ID in apps/proxy-worker/wrangler.jsonc. The first deployment uploads two required secrets: HODOR_ENCRYPTION_KEY (generated with openssl rand -base64 32) and HODOR_JWT_SECRET (generated with openssl rand -hex 32).

After deployment, mint an admin key through POST /_/keys using the JWT secret, store an upstream key with PUT /_/admin/secrets/OPENAI_API_KEY, and register the integration with PATCH /_/admin/registry/openai. Set its target host and path to api.openai.com and /v1, and its authorization header to 'Bearer ' + kv('OPENAI_API_KEY'). The README’s hcurl helper sends the Hodor token as X-Authorization.

DNS is a separate step: add a proxied A record for *.example.com pointing to 192.0.2.0, and attach example.com as a custom domain. A worker route does not create the wildcard DNS record, so deployment can succeed while subdomain requests remain unavailable.

Registry behavior also depends on the mode. Live-KV writes take effect immediately. Snapshot-mode writes return 202 with redeployRequired; fetch GET /_/admin/registry/snapshot, write it to src/generated/registry.json, and run npx wrangler deploy. Snapshot files should remain in deploy copies because they describe integration topology. Wildcards cover first-level subdomains only. For Node/Bun deployment, follow apps/proxy-worker/README.md; the main README does not provide those setup steps.