tessera-cloudflare-worker

A Cloudflare Worker that transparently proxies OpenAI-compatible LLM API calls and emits a signed Tessera compute-spec-v0.1 certificate for every chat completion.

Status: v0.1 — non-streaming chat completions only. Streaming (SSE) is on the v0.2 roadmap. See Limitations for the honest list.

What it does

You point your application's OPENAI_BASE_URL at the worker. The worker:

1. Forwards the request unchanged to the configured upstream (default: https://api.openai.com).
2. Reads the response body.
3. Builds a Tessera compute-spec-v0.1 certificate recording the model, provider, latency, token counts, and hashes of the prompt and output (full payloads only embedded if you opt in).
4. Signs the certificate with your Ed25519 issuer key.
5. Asynchronously dispatches the cert to KV, R2, and/or a webhook destination via ctx.waitUntil — so the client response is not delayed.
6. Returns the upstream response unmodified.

Your application code is unchanged. Your developers don't need to know the worker exists.

When to use this vs. tessera-litellm

Use case	Recommended
You're already running LiteLLM as a proxy	tessera-litellm (Python plugin, no separate deployment)
You're calling OpenAI directly from Node.js, Go, or other non-Python languages	This worker
You want global edge capture without running your own proxy	This worker
You want zero-latency capture (Workers add ~5 ms)	This worker
You want capture of raw API calls outside any framework	This worker

The two tools are designed to be interoperable — both produce identical compute-spec-v0.1 envelopes that any Tessera verifier accepts.

Architecture

┌────────┐                ┌────────────────────┐                ┌──────────────┐
│ Client │ ─── request ──▶│  Tessera Worker    │ ── forward ──▶ │ OpenAI / etc │
│        │                │ (Cloudflare edge)  │ ◀── reply ──── │              │
│        │ ◀── reply ──── │                    │                └──────────────┘
└────────┘                │  build + sign cert │
                          │  ▼                 │
                          │  KV / R2 / webhook │
                          └────────────────────┘

Quick start

1. Clone and install

git clone https://github.com/smq9sn5jck-coder/tessera-cloudflare-worker.git
cd tessera-cloudflare-worker
pnpm install

2. Generate an Ed25519 issuer key

The worker signs every cert with this key. The public key is embedded in each cert so verifiers don't need a key directory.

openssl genpkey -algorithm Ed25519 -out tessera-issuer.pem
# Inspect: openssl pkey -in tessera-issuer.pem -text -noout

Upload the private PEM as a Worker secret:

wrangler secret put TESSERA_ISSUER_PRIVATE_PEM < tessera-issuer.pem

Treat this PEM the way you'd treat your OpenAI API key. Anyone with it can issue certs that look like they came from you.

3. Pick a destination for certs

Edit wrangler.toml and uncomment the relevant binding(s):

[[kv_namespaces]]
binding = "TESSERA_CERT_KV"
id = "<run wrangler kv:namespace create TESSERA_CERT_KV to get this>"

[[r2_buckets]]
binding = "TESSERA_CERT_R2"
bucket_name = "tessera-certs"

Or set a webhook URL in the [vars] block. The webhook should be an endpoint you control that accepts a single signed cert as the JSON request body — typically your own anchor-log ingest, an HTTP-to-queue bridge, or a private archival service:

[vars]
TESSERA_WEBHOOK_URL = "https://anchor-log.your-org.example/ingest"

Important: do not point this at the public Tessera VaaS vaas.verify endpoint. VaaS is a verifier, not an ingest service — it will not store your certs, and the request shape it expects (a tRPC envelope) does not match what this worker POSTs (the raw cert). Use VaaS for ad-hoc re-verification of certs you have already archived elsewhere; see step 6 below.

You can configure all three (KV + R2 + webhook). Certs are dispatched in parallel; failures of one destination don't affect the others.

4. Deploy

pnpm wrangler deploy

Wrangler prints the worker URL, e.g. https://tessera-cloudflare-worker.<your-account>.workers.dev.

5. Point your client at the worker

export OPENAI_BASE_URL=https://tessera-cloudflare-worker.<your-account>.workers.dev/v1

That's it. Every chat completion now produces a signed cert.

6. Verify a cert

curl https://tessera-cloudflare-worker.<your-account>.workers.dev/__tessera/health
# {"status":"ok","service":"tessera-cloudflare-worker", ...}

POST a captured cert to the Tessera VaaS verify endpoint:

curl -X POST https://<your-vaas>.manus.space/api/trpc/vaas.verify \
  -H 'content-type: application/json' \
  -d '{"json":{"certificate":<paste cert here>}}'

Configuration

All variables live in wrangler.toml under [vars] (non-secret) or as Worker secrets (sensitive).

Variable	Type	Default	Purpose
TESSERA_UPSTREAM_URL	var	https://api.openai.com	Upstream LLM API. Any OpenAI-compatible endpoint works (Anthropic via OpenAI-compat shim, Together, Groq, Azure OpenAI).
TESSERA_PROVIDER	var	openai	String embedded in the cert as the provider field.
TESSERA_WEBHOOK_URL	var	""	If set, each signed cert is POSTed to this URL as JSON (raw cert in the body, not a tRPC envelope). Should be a deployer-owned ingest endpoint — not the public VaaS verify endpoint.
TESSERA_INCLUDE_PAYLOADS	var	"false"	When "true", the full prompt and output text are embedded in the cert instead of only their SHA-256 hashes.
TESSERA_ISSUER_PRIVATE_PEM	secret	(required)	Ed25519 PKCS#8 PEM private key.
TESSERA_CERT_KV	binding	(optional)	KV namespace for 90-day cert archive.
TESSERA_CERT_R2	binding	(optional)	R2 bucket for long-term cert storage.

Privacy defaults (read this)

By default, prompt and output text are not embedded in certs. Only their SHA-256 hashes are. This means:

• A cert proves "this exact prompt was sent and this exact response was received" without leaking either.
• A regulator or insurer auditing the cert chain can detect tampering but can't read the conversation.
• If a dispute later requires the actual content, the deployer who has the application logs can produce them, and the hash in the cert proves they're authentic.

Set TESSERA_INCLUDE_PAYLOADS = "true" only if you need the contents in-cert (e.g., for a strictly internal compliance pipeline). The default is the right setting for the overwhelming majority of deployments.

Limitations

Honest scope of v0.1:

• Streaming responses (SSE) are passed through without a cert. Building the cert correctly for streamed responses requires assembling the full output before signing, which adds complexity we're deferring to v0.2. Non-streaming requests work normally.
• OpenAI chat-completion shape only. Other shapes (Anthropic native, embeddings, image generation) pass through opaquely without a cert.
• No per-request rate limiting. That's the deployer's responsibility (Cloudflare Worker dashboard or cloudflare-rate-limiting rules).
• No verification on the worker. The worker only issues. To verify, send the cert to the Tessera VaaS or use the Python verifier.
• No anchoring on the worker. Certs are signed but not yet OTS-stamped or written to a hash-chained ledger. Run the Tessera ADL/OTS upgrader on a back-end host (or use the VaaS) to add those layers — they're independent of where the cert was issued.

Development

pnpm install
pnpm test         # 24 vitest tests
pnpm typecheck    # tsc --noEmit
pnpm dev          # wrangler dev (local with miniflare)

The test suite uses node-pool vitest because the Tessera modules (jcs, signing, cert) are pure JS with no Worker-specific APIs. The full integration test (worker + KV + R2 + webhook) is run via wrangler dev against a local HTTP fixture — see examples/.

License

MIT — see LICENSE.

Related

• Tessera — the core protocol and verifier.
• tessera-litellm — the LiteLLM Python plugin (interoperable cert format).
• Tessera VaaS — public verification-as-a-service web app.