teekit

A minimal, end-to-end verifiable TEE stack.

Background

Trusted execution environments make it possible to build private and verifiable web services, but one issue that makes this harder is that web pages cannot natively verify that they're connected to a TEE. Browsers don't expose X.509 certificate extensions that can be used to prove a connection terminates inside the secured environment, so proxies like Cloudflare can trivially see and modify traffic to TEEs forwarded through them. Anyone hosting a TEE app can easily insert their own TLS proxy in front of it, breaking privacy and extracting session data that lets them impersonate the user.

To work around this, some TEE application hosts implement their own proxy in front of the TEE, but this reintroduces trust assumptions around the proxy. Hosts can also use certificate log monitoring to boost security, but this happens out-of-band and doesn't directly protect the connection between the user and the TEE.

This repository implements protocols for remotely-attested HTTPS and WSS channels, which web pages can use to establish secure connections that verifiably terminate inside trusted execution environments (currently Intel TDX/SGX).

Applications using teekit can treat TEEs like a regular web server, and use public certificate authorities like Let's Encrypt and Cloudflare without custom configuration. Developers can also host copies of the same application on IPFS or other immutable cloud services.

Components

• @teekit/tunnel:
  • Establishes tunneled connections to a TEE through an encrypted WebSocket, with key exchange, quote validation, and CRL/TCB validation
  • Supports encrypted HTTP requests via a fetch-compatible API
  • Supports encrypted WebSockets via a WebSocket-compatible API
  • Includes a ServiceWorker for upgrading all HTTP requests from a browser page to use the encrypted channel
• @teekit/qvl:
  • WebCrypto-based SGX/TDX quote verification library
  • Validates the full chain of trust from the root CA, down to binding the public key of the encrypted channel in report_data
  • Includes optional CRL/TCB validation inside the browser. (TCB info cannot be fetched from Intel in the browser without a CORS proxy.)
• @teekit/demo:
  • A demo application that supports HTTPS and WSS requests over the encrypted channel, both with and without the embedded ServiceWorker.

Usage

On the client, create a TunnelClient() object. You should switch out unencrypted Node.js fetch and WebSocket instances for our fetch and WebSocket wrappers, exposed on the TunnelClient().

It is your responsibility to configure TunnelClient with the expected mrtd and report_data measurements, certificate revocation lists, and manually verify the TCB inside any custom quote validator.

Your client will validate all measurements, quote signatures, and additional CRL/TCB info before opening a connection.

import { TunnelClient } from "@teekit/tunnel"
import { hex, parseTdxQuote } from "@teekit/qvl"

async function main() {
  const origin = "http://127.0.0.1:3000"

  // You can validate against expected mrtd/report_data or provide a custom matcher.
  // Below shows fixed values; compute these from an expected quote if you have one.
  const expectedMrtd = '...' /* hex string */
  const expectedReportData = '...' /* hex string */

  const client = await TunnelClient.initialize(origin, {
    mrtd: expectedMrtd,
    report_data: expectedReportData,
    crl: [], // certificate revocation list
    verifyTcb: ({ fmspc, cpuSvn, pceSvn, quote }) => {
      // Check for TCB freshness and return true if valid
      return true
    },
    // sgx: true // defaults to TDX otherwise
  })

  // HTTP over tunnel
  const res = await client.fetch("/hello")
  console.log(await res.text()) // server replies "world"

  // WebSocket over tunnel
  const ws = new client.WebSocket(origin.replace(/^http/, "ws"))
  ws.addEventListener("open", () => ws.send("ping"))
  ws.addEventListener("message", (evt: any) => console.log(String(evt.data)))
}

main()

On the server, add a TunnelServer middleware to your Node.js/Express server. We only support Node.js now, but future versions will support arbitrary backends through Nginx.

import express from "express"
import { TunnelServer } from "@teekit/tunnel"

async function main() {
  const app = express()
  app.get("/hello", (_req, res) => res.status(200).send("world"))

  async function getQuote(x25519PublicKey: Uint8Array): Promise<Uint8Array> {
    // Return a Uint8Array bound to x25519PublicKey. See packages/demo/server
    // for an example that uses `trustauthority-cli` and --user-data binding.
    return new Uint8Array(Buffer.from('...', 'hex'))
  }
  const tunnelServer = await TunnelServer.initialize(app, getQuote)

  // Optional: WebSocket support via the built-in mock server
  tunnelServer.wss.on("connection", (ws) => {
    ws.on("message", (data: any) => ws.send(data))
  })

  tunnelServer.server.listen(3000, () => {
    console.log("teekit service listening on :3000")
  })
}

main()

You may also use the included ServiceWorker to transparently upgrade HTTP GET/POST requests to go over the encrypted channel to your TunnelServer.

To do this, first add the ServiceWorker plugin to your bundler. You can use an included Vite plugin to handle this, or manually serve __ra-serviceworker__.js at your web root from node_modules/@teekit/tunnel/lib/sw.build.js:

// vite.config.js
import react from "@vitejs/plugin-react"
import { defineConfig } from "vite"
import { includeRaServiceWorker } from "@teekit/tunnel/sw"

export default defineConfig({
  plugins: [react(), includeRaServiceWorker()],
})

Then, register the ServiceWorker at app startup, pointed at your tunnel origin:

// src/main.tsx (or similar)
import { registerServiceWorker } from "@teekit/tunnel/register"

const baseUrl = "http://127.0.0.1:3000" // your TunnelServer origin
registerServiceWorker(baseUrl)

Note that different browsers vary in their support of ServiceWorkers, and some browsers may block ServiceWorkers from being installed, in which case your application will be silently downgraded to lose privacy. For this reason we recommend using the default @teekit/tunnel APIs whenever possible.

By default, ServiceWorkers intercept link clicks, location.assign() calls, subresource requests, and fetch() / XMLHttpRequest requests (but not WebSockets).

Demo

The packages/demo directory contains a demo of a chat app that relays WebSocket messages and fetch requests over an encrypted channel.

Node v22 is expected.

Run the client using tsx:

npm run dev

Run the server using Node.js:

npm run server

Architecture

The tunnel performs a key exchange and attestation check before allowing any traffic. After the handshake, all payloads are CBOR encoded and encrypted with the XSalsa20‑Poly1305 stream cipher (libsodium crypto_secretbox).

1. Client opens a control WebSocket to the server at ws(s)://<host>:<port>/__ra__.
2. Server immediately sends server_kx with an X25519 public key and a TDX/SGX attestation quote.
3. Client verifies the quote (using @teekit/qvl), optionally enforces mrtd/report_data or a custom matcher, generates a symmetric key, and sends it sealed to the server via client_kx (libsodium crypto_box_seal).
4. All subsequent messages are encrypted envelopes { type: "enc", nonce, ciphertext } carrying tunneled HTTP and WebSocket messages.

Limitations

• For security reasons, we currently require that all WebSocket connections to the HTTP server go through the encrypted channel. Mixing and matching unencrypted WebSockets and @teekit/tunnel is not supported.
• One keypair is generated per server. No key rotation (yet) or support for load balancing across TEEs.
• HTTP request/response bodies are buffered end-to-end; very large payloads cannot be streamed.
• HTTP request bodies: string, Uint8Array, ArrayBuffer, ReadableStream (no FormData).
• Our WebSocket.send does not accept Blob. Convert blobs to ArrayBuffer or Uint8Array first.
• The default client request timeout is 30 seconds, and this is not configurable at this time.
• WebSocket messages queued before open are automatically flushed once the socket opens.

License

MIT (C) 2025