Skip to main content

​
Introduction

When building applications on top of Tinfoil’s private inference API, you often need to add your own infrastructure layer between your client applications and the inference enclave. Perhaps you want to authenticate your users, track API usage, implement rate limiting, or add custom routing logic. The challenge is doing this without compromising the end-to-end encryption. This is where the Encrypted HTTP Body Protocol (EHBP) becomes useful. EHBP encrypts HTTP message bodies at the application layer using Hybrid Public Key Encryption (HPKE), completely separate from transport layer security like TLS. This separation means you can run a proxy server that inspects headers and metadata, while the actual request and response bodies remain encrypted end-to-end between your client and the Tinfoil enclave. Moreover, our JavaScript SDK automatically checks and validates the HPKE key to ensure it is generated inside an attested secure enclave. Your proxy server becomes an intermediary that can be used add your Tinfoil API keys, authenticate and authorize your users with custom logic, track usage metrics and implement rate limiting, add custom routing headers based on your business logic, and log metadata for debugging and monitoring—all while the actual inference data remains encrypted throughout the entire journey.

​
The Challenge

When you’re building a production application with Tinfoil, you typically face a dilemma. On one hand, you need to keep your TINFOIL_API_KEY secret—exposing it to client browsers would allow anyone to use your API quota. On the other hand, you want your sensitive prompts and completions to be encrypted end-to-end to the attested enclave, not just to your backend server.

​
The Solution using EHBP

Your proxy server sits between your client and the Tinfoil enclave, handling authentication and metadata, while the actual inference data flows through it encrypted. The proxy receives encrypted requests from your client application, adds your TINFOIL_API_KEY as the Authorization header, preserves the encryption headers required by the protocol, forwards the encrypted payload to Tinfoil’s enclave, and returns the encrypted response to your client. This architecture gives you control over what the proxy can and cannot access. The proxy has full visibility into HTTP headers, allowing you to read custom request headers (like X-User-ID or X-Request-ID) for authentication or routing decisions, add custom response headers (like X-Rate-Limit-Remaining or X-Request-Cost) for rate limiting or cost tracking, and log metadata for debugging and monitoring. But the request and response bodies—the actual prompts, completions, and inference data—remain encrypted from client to enclave using keys the proxy never possesses.

​
How It Works

The data flow shows how encryption is maintained throughout the request lifecycle:

​
Client Setup

Setting up the client is straightforward. First, install the Tinfoil SDK: 
npm install tinfoil
Proxy support with SecureClient is available in the JavaScript SDK (Node.js and browsers).
The key detail is that you configure the Tinfoil client with your proxy’s URL as baseURL. The SDK automatically fetches the enclave URL and configuration from the router, so you only need to specify where to send requests. This ensures that even though your proxy handles the HTTP routing, only the enclave can decrypt the request bodies. When the SDK sends requests through a proxy (i.e., baseURL differs from enclaveURL), it includes the enclave URL in the X-Tinfoil-Enclave-Url header. Your proxy should use this header to determine where to forward requests, ensuring the encrypted payload reaches the same enclave that the client verified. By default, the SDK fetches encryption keys directly from the enclave even when requests are sent through your proxy. If you want your proxy to also handle key fetching (for example, to avoid direct client-to-enclave connections), set both baseURL and enclaveURL to your proxy URL. Your proxy must then forward the key fetching requests to the enclave. 
import { SecureClient } from "tinfoil";

const client = new SecureClient({
  baseURL: "https://your-proxy-server.com/",
});

// Wait for the client to fetch encryption keys and perform verification
await client.ready();

// Make encrypted requests
const response = await client.fetch("/v1/chat/completions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Accept: "text/event-stream",
    // Optional: Add custom headers for your proxy to read
    "Your-Custom-Request-Header": "custom-value",
  },
  body: JSON.stringify({
    model: "gpt-oss-120b",
    messages: [{ role: "user", content: "Hello!" }],
    stream: true,
  }),
});
When you call await client.ready(), the client fetches the enclave’s public key and performs verification. From that point on, all request bodies are encrypted using that key before being sent to your proxy, and all response bodies are decrypted after being received.

​
Proxy Server Setup

One of the important aspects of EHBP is that the proxy requires no special cryptographic libraries or dependencies. Since the proxy doesn’t participate in encryption or decryption, it only needs basic HTTP handling capabilities available in any web framework. Your proxy’s job is simple: preserve the EHBP protocol headers that coordinate encryption between client and enclave, add your authentication credentials, and forward the encrypted payload. While we provide an example implementation in Go below, the proxy pattern works with any language that can handle HTTP requests. The example repository provides a complete reference implementation with a Go proxy and a TypeScript client that you can adapt to Python, Node.js, Rust, or any other language.

​
Required Headers to Preserve

The EHBP protocol uses specific headers to coordinate encryption keys between the client and enclave. Your proxy must forward these headers unchanged in both directions. For requests, you need to preserve Ehbp-Encapsulated-Key (the HPKE encapsulated key, hex-encoded, 64 characters). For responses, you need to preserve Ehbp-Response-Nonce (the 32-byte nonce used in response key derivation, hex-encoded, 64 characters). Understanding the body framing format isn’t necessary for proxy implementation, but it helps explain why these headers are critical—they contain the cryptographic material needed for key derivation and decryption.

​
CORS Configuration

If your proxy will be called from browser-based applications, you’ll need to configure CORS headers to allow the browser to send and read the encryption headers. The key requirement is exposing the EHBP headers in both directions: 
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST, OPTIONS
Access-Control-Allow-Headers: Accept, Authorization, Content-Type, Ehbp-Encapsulated-Key, X-Tinfoil-Enclave-Url
Access-Control-Expose-Headers: Ehbp-Response-Nonce

​
Implementation Example

package main

import (
	"io"
	"log"
	"net/http"
	"os"
)

var (
	ehbpRequestHeaders  = []string{"Ehbp-Encapsulated-Key"}
	ehbpResponseHeaders = []string{"Ehbp-Response-Nonce"}
)

func proxyHandler(w http.ResponseWriter, r *http.Request) {
	// Set CORS headers
	w.Header().Set("Access-Control-Allow-Origin", "*")
	w.Header().Set("Access-Control-Allow-Methods", "POST, OPTIONS")
	w.Header().Set("Access-Control-Allow-Headers", "Accept, Authorization, Content-Type, Ehbp-Encapsulated-Key, X-Tinfoil-Enclave-Url")
	w.Header().Set("Access-Control-Expose-Headers", "Ehbp-Response-Nonce")

	if r.Method == http.MethodOptions {
		w.WriteHeader(http.StatusNoContent)
		return
	}

	// Get upstream URL from the X-Tinfoil-Enclave-Url header
	upstreamBase := r.Header.Get("X-Tinfoil-Enclave-Url")
	if upstreamBase == "" {
		http.Error(w, "X-Tinfoil-Enclave-Url header required", http.StatusBadRequest)
		return
	}
	upstreamURL := upstreamBase + r.URL.Path

	// Create upstream request
	req, err := http.NewRequestWithContext(r.Context(), http.MethodPost, upstreamURL, r.Body)
	if err != nil {
		http.Error(w, err.Error(), http.StatusInternalServerError)
		return
	}

	req.Header.Set("Content-Type", "application/json")
	if accept := r.Header.Get("Accept"); accept != "" {
		req.Header.Set("Accept", accept)
	}

	// Add your API key
	apiKey := os.Getenv("TINFOIL_API_KEY")
	if apiKey == "" {
		http.Error(w, "TINFOIL_API_KEY not set", http.StatusInternalServerError)
		return
	}
	req.Header.Set("Authorization", "Bearer "+apiKey)

	// Copy encryption headers
	copyHeaders(req.Header, r.Header, ehbpRequestHeaders...)

	// Forward request
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		http.Error(w, err.Error(), http.StatusBadGateway)
		return
	}
	defer resp.Body.Close()

	// Copy encryption headers from response
	copyHeaders(w.Header(), resp.Header, ehbpResponseHeaders...)

	if ct := resp.Header.Get("Content-Type"); ct != "" {
		w.Header().Set("Content-Type", ct)
	}

	// Handle chunked transfer encoding for streaming responses
	if te := resp.Header.Get("Transfer-Encoding"); te != "" {
		w.Header().Set("Transfer-Encoding", te)
		w.Header().Del("Content-Length")
	}

	w.WriteHeader(resp.StatusCode)

	// Stream response with flushing for SSE/streaming support
	if flusher, ok := w.(http.Flusher); ok {
		buf := make([]byte, 1024)
		for {
			n, err := resp.Body.Read(buf)
			if n > 0 {
				w.Write(buf[:n])
				flusher.Flush()
			}
			if err != nil {
				break
			}
		}
		return
	}

	io.Copy(w, resp.Body)
}

func copyHeaders(dst, src http.Header, keys ...string) {
	for _, key := range keys {
		if value := src.Get(key); value != "" {
			dst.Set(key, value)
		}
	}
}

func main() {
	http.HandleFunc("/v1/chat/completions", proxyHandler)
	log.Println("Proxy listening on :8080")
	log.Fatal(http.ListenAndServe(":8080", nil))
}

​
Working with Custom Headers

Beyond the required EHBP headers, you can use custom headers to implement your own application-level protocols between the client and proxy. This is where you build your authentication, rate limiting, user tracking, and other business logic.

​
Request Headers

Your client can include custom headers that the proxy reads but the enclave never sees. This is perfect for user authentication tokens, request IDs, feature flags, or any other metadata: 
const response = await client.fetch("/v1/chat/completions", {
  headers: {
    "X-User-ID": "user-123",
    "X-Request-ID": crypto.randomUUID(),
    "Your-Custom-Request-Header": "custom-value",
  },
  // ...
});
Your proxy can then read and strip these headers for logging, routing decisions, or authentication checks before forwarding the encrypted request to the enclave: 
// In your proxy server
if customHeader := r.Header.Get("Your-Custom-Request-Header"); customHeader != "" {
    log.Printf("Custom request header received: %s", customHeader)
    // These headers are not forwarded to the enclave
}
Just remember to add any custom headers you use to your CORS Access-Control-Allow-Headers configuration so browsers can send them.

​
Response Headers

Similarly, your proxy can add custom headers to responses that the client can read. This is useful for communicating rate limit information, cost tracking, request IDs for debugging, or any other metadata: 
// In your proxy server
w.Header().Set("Your-Custom-Response-Header", "response-value")
w.Header().Set("X-Rate-Limit-Remaining", "100")
The client can then access these headers: 
// Optional: Read custom headers from the response
const customHeader = response.headers.get("Your-Custom-Response-Header");
const remaining = response.headers.get("X-Rate-Limit-Remaining");
As with request headers, you’ll need to expose custom response headers in your CORS Access-Control-Expose-Headers configuration for browsers to access them.

​
Security Considerations

While EHBP encrypts the request and response bodies, the HTTP headers remain visible throughout the proxy chain. This design is intentional—it’s what allows proxies to route and manage requests—but it has important security implications.
Always keep your TINFOIL_API_KEY secret. Never expose it to client applications. The entire purpose of the proxy architecture is to keep this key on your backend.
First and foremost, use HTTPS in production. While the request and response bodies are encrypted at the application layer, HTTP headers are transmitted in the clear. Using HTTPS provides transport-layer encryption for headers, protecting metadata like user IDs, request IDs, and other information you might include in custom headers. Second, validate and sanitize custom headers from clients. Since your proxy reads these headers for authentication and routing decisions, treat them as untrusted input. Validate formats, check for injection attacks, and implement proper authentication before trusting any client-provided header values. Finally, always preserve and forward the EHBP headers (Ehbp-Encapsulated-Key for requests, Ehbp-Response-Nonce for responses). These headers are critical for the encryption protocol to work. Dropping or modifying them will cause decryption to fail on the client or server.

​
Next Steps

For a complete working example, check out the encrypted-request-proxy-example repository. It includes a Go proxy implementation with streaming support, a TypeScript browser client demonstrating the SecureClient, and custom header handling examples.

Example Repository

Go proxy server with TypeScript browser client

Encrypted HTTP Body Protocol

Deep dive into the EHBP specification

​
Usage Tracking and Monitoring

Your proxy server can use the Admin API to programmatically track usage and monitor your infrastructure. This allows you to retrieve detailed usage statistics by time period, get per-key token usage and costs, monitor usage patterns with time-series data, and track model-specific usage across your API keys. This enables you to build custom dashboards, implement alerting based on usage thresholds, or analyze cost patterns across your infrastructure.