Host-Binding Encryption: The Architecture Behind KeyVault Edge

API keys as issued by providers (OpenAI, Stripe, AWS, etc.) have one catastrophic property: they are origin-independent. A key issued to your account can be used from any IP address, any network, any country - as long as the key string is known.

This means that the security of your API access reduces entirely to the security of the key string itself. If the string leaks through any channel - source code, CI logs, a developer's email, a stolen laptop - the attacker has full access to your API account with no further barrier.

Host-binding adds that barrier at the proxy layer, without provider cooperation. The proxy only injects the real key into requests whose origin matches the token's allowlist, and the real key is never returned to the caller.

A sanitized token is a self-contained, signed envelope. It starts with kvt_, followed by a base64url body and an HMAC-SHA256 signature over that body.

kvt_<body>.<signature>

body (base64url), in order:
  version           1 byte
  DEK nonce         12 bytes
  wrapped DEK       32-byte data key + 16-byte GCM tag,
                    encrypted with the edge master key (KEK)
  payload nonce     12 bytes
  payload           AES-256-GCM ciphertext under the DEK

signature           HMAC-SHA256(body), base64url

The encrypted payload holds the real provider key plus the token's policy: the allowed hosts, rate limits, an optional expiry and monthly cost cap, and the endpoint patterns it may call. Each token gets its own data key (DEK), and the DEK is wrapped by a key-encryption key that only the edge proxy holds. Without that key, the token is ciphertext.

The allowed hosts travel inside the encrypted, signed payload, so whoever holds the token can't edit them. The proxy enforces them on every request.

When the proxy receives a request with a token in the X-KV-Token header, it:

1. 1.Verifies the HMAC signature; a tampered or forged token is rejected with 403
2. 2.Unwraps the token's data key with the edge master key and decrypts the payload in Worker memory
3. 3.Takes the request's Origin header (falling back to Referer, then Host) and compares its hostname with the token's allowed hosts, exact or *.wildcard
4. 4.On a mismatch: returns 403, discards the decrypted payload and records a breach event
5. 5.Checks expiry, revocation, rate limits and the monthly cost cap
6. 6.Injects the real key into the provider's auth header and forwards the request
7. 7.Strips its own X-KV-* headers and Cloudflare client headers from the upstream request
8. 8.Streams the provider response back to the caller

The proxy runs on Cloudflare Workers. The choice is architectural, not operational: V8 isolates provide a fundamentally different security boundary than traditional server processes.

// ─── What happens at the network layer ───────────────────────────────────
// 1. Your app sends:  POST <proxy>/v1/chat/completions
//                     X-KV-Token:  kvt_...
//                     X-KV-Target: https://api.openai.com
//                     Origin:      https://yourdomain.com
//
// 2. Worker verifies the HMAC, decrypts the token in memory,
//    and checks yourdomain.com against the token's allowed hosts
// 3. Forwards:        POST https://api.openai.com/v1/chat/completions
//                     Authorization: Bearer <real key from the token>
//                     (X-KV-* and Cloudflare client headers removed)
//
// 4. Streams the response back to your app
// ─────────────────────────────────────────────────────────────────────────

For streaming responses the Worker forwards chunks as they arrive; the decrypt-and-check step happens once, before the request is forwarded.

When a token fails validation (bad signature, wrong origin, expired or malformed), the proxy records a breach event in the background and rejects the request. The event contains:

{
  token_prefix:   "kvt_AbCdEfGh",
  event_type:     "domain_mismatch",
  attacker_ip:    "203.0.113.42",
  attempted_host: "evil.example",
  user_agent:     "...",
  geo_location:   "City, Country"
}

The event appears in your dashboard and is sent to the alert channels you configure:

• Email
• Slack
• Your own webhook endpoint

Request bodies are not logged.