Tinfoil TypeScript SDK

A TypeScript client for verifiably private AI inference with the Tinfoil API. Supports the OpenAI API format and the Vercel AI SDK.

Tinfoil runs LLMs inside secure enclaves—isolated environments on hardware where even Tinfoil cannot access your data. This SDK encrypts your requests using HPKE (RFC 9180) via the EHBP protocol, so that only the verified enclave can decrypt them.

It also supports TLS certificate pinning as an alternative transport mode, where all connections are encrypted and terminated to a verified secure enclave.

Installation

npm install tinfoil

Requires Node 20+. Works in browsers with ES2020 support, Electron, and Bun (see Bun Support).

Quick Start

You'll need an API key to get started.

import { TinfoilAI } from "tinfoil";

const client = new TinfoilAI({
  apiKey: "<YOUR_API_KEY>", // or use TINFOIL_API_KEY env var
});

const completion = await client.chat.completions.create({
  messages: [{ role: "user", content: "Hello!" }],
  model: "llama3-3-70b", // See all models: https://docs.tinfoil.sh/models/catalog
});

Browser Usage

Use bearerToken for browser authentication (e.g., JWT from your auth system):

import { TinfoilAI } from 'tinfoil';

const client = new TinfoilAI({
  bearerToken: 'your-jwt-token' // From your auth system
});

await client.ready(); // Wait for verification to complete

const completion = await client.chat.completions.create({
  model: 'llama3-3-70b',
  messages: [{ role: 'user', content: 'Hello!' }]
});

Warning: Never use apiKey in browser code—it exposes your key in page source. Use bearerToken with your backend authentication. If you must use apiKey instead of bearerToken in the browser, set dangerouslyAllowBrowser: true.

Using with OpenAI SDK

If you prefer the OpenAI SDK directly, use SecureClient to get a verified fetch function:

import OpenAI from "openai";
import { SecureClient } from "tinfoil";

const secureClient = new SecureClient();
await secureClient.ready();

const openai = new OpenAI({
  apiKey: "<YOUR_API_KEY>",
  baseURL: secureClient.getBaseURL(),
  fetch: secureClient.fetch,
});

const completion = await openai.chat.completions.create({
  model: "llama3-3-70b",
  messages: [{ role: "user", content: "Hello!" }],
});

Using with Vercel AI SDK

Full support for the Vercel AI SDK in both server and browser environments.

AI Server SDK (Node.js / Next.js)

Use createTinfoilAI for server-side AI SDK functions:

import { createTinfoilAI } from "tinfoil";
import { generateText, streamText } from "ai";

const tinfoil = await createTinfoilAI("<YOUR_API_KEY>");

const { text } = await generateText({
  model: tinfoil("llama3-3-70b"),
  prompt: "Hello!",
});

For Next.js API routes, initialize once at module level to avoid repeated verification:

// app/api/chat/route.ts
const tinfoilPromise = createTinfoilAI(process.env.TINFOIL_API_KEY!);

export async function POST(req: Request) {
  const tinfoil = await tinfoilPromise;
  // ...
}

See the Vercel AI Server SDK Example for more details.

AI Browser SDK (React / Vue / etc.)

For browser apps, use SecureClient with DefaultChatTransport. A proxy server is required to keep your API key secret.

import { SecureClient } from "tinfoil";
import { DefaultChatTransport } from "ai";

const secureClient = new SecureClient({
  baseURL: "https://your-proxy.com/",
});
await secureClient.ready(); // Wait for attestation

const transport = new DefaultChatTransport({
  api: "/v1/chat/completions",
  fetch: secureClient.fetch,
});

See the Vercel AI Browser SDK Example for complete React patterns with useChat, context providers, and error handling.

How Verification Works

When you create a client, the SDK automatically:

1. Verifies the enclave — Fetches attestation and checks AMD SEV-SNP hardware signatures to prove it's a genuine secure enclave
2. Verifies the code — Confirms the running code matches the signed GitHub release (via Sigstore)
3. Establishes encryption — Creates an encrypted connection that only the verified enclave can decrypt

Your requests are encrypted before leaving your machine. Even Tinfoil cannot read them—only the verified enclave can decrypt and process your data.

Transport Modes:

• HPKE (default): End-to-end encrypted via RFC 9180, works through proxies
• TLS Pinning: Direct TLS certificate pinning to the enclave (requires direct connection, no proxy support)

For a deeper understanding, see How It Works, Confidentiality, Verifiability and Attestation Architecture.

Verification API

The Verifier class is for advanced use cases where you want to verify an enclave before creating a client, or verify arbitrary enclaves independently.

import { Verifier } from "tinfoil";

const verifier = new Verifier({
  serverURL: "https://enclave.host.com",
  configRepo: "tinfoilsh/confidential-model-router",
});

const attestation = await verifier.verify();
console.log(attestation.tlsPublicKeyFingerprint);
console.log(attestation.hpkePublicKey);

const doc = verifier.getVerificationDocument();
console.log(doc.securityVerified);
console.log(doc.steps); // fetchDigest, verifyCode, verifyEnclave, compareMeasurements

Proxy Support

Route requests through your own backend while keeping request bodies encrypted end-to-end. This lets you:

• Keep API keys on your server
• Add authentication, rate limiting, logging
• The proxy sees headers/URLs but cannot decrypt request or response bodies

import { SecureClient } from "tinfoil";

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

await client.ready();
// Requests go to your proxy, bodies remain encrypted to the enclave

For full proxy server implementation (Go example, CORS config, header handling), see the Encrypted Request Proxying guide.

Examples

Working examples are in packages/tinfoil/examples/:

Example	Description
chat/	Basic chat completion with TinfoilAI
streaming/	Server-sent events streaming
ai-sdk/	Vercel AI SDK server-side integration
ai-sdk-react/	Vercel AI SDK React/browser integration
secure_client/	Direct SecureClient usage for custom HTTP
unverified_client/	Development/testing without attestation (tinfoil/unsafe)

Run any example:

cd packages/tinfoil/examples/chat
npx ts-node main.ts

Documentation

Guides

• Encrypted Request Proxying — Set up a proxy server
• Tool Calling — Function calling with AI models
• Structured Outputs — JSON schema validation
• Image Processing — Multi-modal AI
• Document Processing — PDF/document handling

Understanding the Security

• How It Works — Confidential computing overview
• Confidentiality — Data privacy guarantees
• Verifiability — Attestation explanation
• Attestation Architecture — Technical deep-dive
• EHBP Protocol — Encryption protocol specification

Tutorials

• Cline with Tinfoil — Private AI-assisted coding in VS Code
• Private RAG with Verba — Build private RAG applications

Resources

• Model Catalog — Available models
• Getting an API Key — Sign up
• SDK Overview — All Tinfoil SDKs
• Status — Service status
• Changelog — What's new

Project Structure

This is a monorepo with two packages:

Package	Description
packages/tinfoil	Main SDK (published as tinfoil)
packages/verifier	Attestation verifier (published as @tinfoilsh/verifier)

Development

# Install dependencies
npm install

# Build all packages
npm run build

# Run tests
npm test                    # Unit tests
npm run test:all            # All tests (unit + integration + browser)
npm run test:integration    # Integration tests (real network requests)
npm run test:browser        # Browser tests
npm run test:bun -w tinfoil # Bun tests

Reporting Vulnerabilities

Email security@tinfoil.sh or open a GitHub issue.