Tinfoil TypeScript SDK

Secure OpenAI-compatible client for the Tinfoil API. This SDK verifies enclave attestation and encrypts all payloads using HPKE (RFC 9180) via the EHBP protocol. It also supports a fallback mode to TLS certificate pinning, where all connections are encrypted and terminated to a verified secure enclave.

Installation

npm install tinfoil

Requires Node 20+. Works in browsers with ES2022 support.

Quick Start

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",
});

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'
});

await client.ready();

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

Warning: Using API keys in the browser exposes them to anyone viewing your page source. If you must use apiKey instead of bearerToken in the browser, set dangerouslyAllowBrowser: true.

Using with OpenAI SDK

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

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!" }],
});

Verification API

import { Verifier } from "tinfoil";

const verifier = new Verifier({ serverURL: "https://enclave.host.com" });

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

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)

Browser builds use *.browser.ts files selected via conditional exports.

Development

# Install dependencies
npm install

# Build all packages (verifier first, then tinfoil)
npm run build

# Run all unit tests
npm test

# Run browser unit tests
npm run test:browser

# Run integration tests (makes real network requests)
npm run test:integration
npm run test:browser:integration

# Clean build artifacts
npm run clean

Documentation

• TinfoilAI SDK Documentation
• OpenAI Client Reference (API is compatible)
• Examples

Reporting Vulnerabilities

Email [email protected] or open a GitHub issue.