Client-side Decryption SDK
Decrypt a KeyVault Edge token directly in your own runtime — no proxy hop required. Use this when you control the execution environment and have access to the encryption keys, such as inside a Cloudflare Worker, a backend service, or a CLI tool.
Server-side only
The decrypt SDK requires MASTER_KEY and HMAC_KEY. These are your root encryption keys — never include them in browser bundles, mobile apps, or any code that reaches untrusted environments. If you need to use an API key in the browser, use Ephemeral Sessions instead.
When to use the decrypt SDK
Cloudflare Worker / Edge Runtime
Decrypt inline inside a Worker without a round-trip to another service. Web Crypto API is available natively.
Backend microservice
Your service stores tokens in a DB and needs to call an upstream API — decrypt at call time, never at rest.
CLI tools & scripts
Automate API calls using tokens stored in a secrets manager without hardcoding keys.
Custom proxy middleware
Build your own forwarding layer with full control over headers, retries, and observability.
Install
npm install @keyvault-edge/decryptUsage
import { decryptToken } from "@keyvault-edge/decrypt"; // Run this server-side (Node.js, Edge Runtime, Cloudflare Worker)// NEVER in browser code — the MASTER_KEY must stay secret.const realKey = await decryptToken({ token: "kvt_hb_...", // the sanitised token from your DB masterKey: process.env.MASTER_KEY!, hmacKey: process.env.HMAC_KEY!, host: "api.yourdomain.com", // must match the host the token was bound to}); // realKey = "sk-proj-abc123..." (your original API key)console.log(realKey);The host parameter must match one of the allowedHosts the token was bound to at creation time. A mismatch throws a HostBindingError.
What happens inside the SDK
// Full decrypt pipeline (what the SDK does internally)://// 1. Base64-decode the token payload// 2. Verify HMAC-SHA256 signature (rejects tampered tokens immediately)// 3. Check expiry timestamp// 4. Verify host binding — "api.yourdomain.com" must be in allowedHosts// 5. Unwrap the DEK (data encryption key) using the KEK (MASTER_KEY, AES-256-GCM)// 6. Decrypt the provider key using the unwrapped DEK (AES-256-GCM)// 7. Return the plaintext API key import { decryptToken } from "@keyvault-edge/decrypt"; const realKey = await decryptToken({ token, masterKey, hmacKey, host });The full decrypt pipeline runs in ~0.5 ms using native Web Crypto (JavaScript) or the platform's equivalent. There are no network calls — everything is local cryptographic operations.
Error types
| Error | Cause |
|---|---|
| InvalidTokenError | Token is malformed or not a valid kvt_ token |
| HMACVerificationError | Signature mismatch — token was tampered with or wrong HMAC_KEY |
| TokenExpiredError | Token has passed its expiry timestamp |
| HostBindingError | Provided host is not in the token's allowedHosts list |
| DecryptionError | AES-GCM decryption failed — wrong MASTER_KEY or corrupted payload |
Decrypt SDK vs. proxy
| Decrypt SDK | Proxy (hosted / BYOP) | |
|---|---|---|
| Latency overhead | ~0 ms (local crypto) | 1–30 ms (network) |
| Requires MASTER_KEY at runtime | Yes | No |
| Breach detection | You implement it | Built-in |
| Rate limiting | You implement it | Built-in |
| Audit logging | You implement it | Built-in |
| Works in the browser | No | Via ephemeral sessions |