tinfoil

README

Tinfoil Go Client

Installation

tinfoil-go currently relies on a specific feature in go-sev-guest that hasn't been upstreamed yet. This requires adding the following line to your go.mod:

replace github.com/google/go-sev-guest v0.0.0-00010101000000-000000000000 => github.com/jraman567/go-sev-guest v0.0.0-20250117204014-6339110611c9

Then run:

go get github.com/tinfoilsh/tinfoil-go

Quick Start

The Tinfoil Go client is a wrapper around the OpenAI Go client and provides secure communication with Tinfoil enclaves. It has the same API as the OpenAI client, with additional security features:

• Automatic attestation validation to ensure enclave integrity verification
• TLS certificate pinning to prevent man-in-the-middle attacks

package main

import (
	"context"
	"fmt"

	"github.com/openai/openai-go"
	"github.com/openai/openai-go/option"
	"github.com/tinfoilsh/tinfoil-go" // imported as tinfoil
)

func main() {
	// Create a client for a specific enclave and model repository
	client, err := tinfoil.NewClientWithParams(
		"enclave.example.com",
		"org/model-repo",
		option.WithAPIKey("your-api-key"),
	)
	if err != nil {
		panic(err.Error())
	}

	// Make requests using the OpenAI client API
	// Note: enclave verification happens automatically
	chatCompletion, err := client.Chat.Completions.New(context.TODO(), openai.ChatCompletionNewParams{
		Messages: []openai.ChatCompletionMessageParamUnion{
			openai.UserMessage("Say this is a test"),
		},
		Model: "llama3-3-70b", // see https://docs.tinfoil.sh for supported models
	})

	if err != nil {
		panic(err.Error())
	}

	fmt.Println(chatCompletion.Choices[0].Message.Content)
}

Usage

// 1. Create a client
client, err := tinfoil.NewClientWithParams(
	"enclave.example.com",  // Enclave hostname
	"org/repo",             // GitHub repository
	option.WithAPIKey("your-api-key"),
)
if err != nil {
	panic(err.Error())
}

// 2. Use client as you would openai.Client 
// see https://pkg.go.dev/github.com/openai/openai-go for API documentation

Advanced Functionality

// For manual verification and direct HTTP access, use SecureClient directly
secureClient := tinfoil.NewSecureClient("enclave.example.com", "org/repo")

// Manual verification
groundTruth, err := secureClient.Verify()
if err != nil {
	return fmt.Errorf("verification failed: %w", err)
}

// Get the raw HTTP client 
httpClient, err := secureClient.HTTPClient()
if err != nil {
	return fmt.Errorf("failed to get HTTP client: %w", err)
}

// Make HTTP requests directly 
resp, err := secureClient.Get("/api/status", map[string]string{
	"Authorization": "Bearer token",
})

Foreign Function Interface (FFI) Support

For usage in other languages through FFI, additional functions are available which avoid using FFI incompatible data structures (e.g., Go maps):

// Create a SecureClient for FFI usage
secureClient := tinfoil.NewSecureClient("enclave.example.com", "org/repo")

// Initialize a request and get an ID
requestID, err := secureClient.InitPostRequest("/api/submit", []byte(`{"key":"value"}`))

// Add headers individually
secureClient.AddHeader(requestID, "Content-Type", "application/json")
secureClient.AddHeader(requestID, "Authorization", "Bearer token")

// Execute the request
resp, err := secureClient.ExecuteRequest(requestID)

API Documentation

This library is a drop-in replacement for the official OpenAI Go client that can be used with Tinfoil. All methods and types are identical. See the OpenAI Go client documentation for complete API usage and documentation.

Reporting Vulnerabilities

Please report security vulnerabilities by either:

• Emailing security@tinfoil.sh

• Opening an issue on GitHub on this repository

We aim to respond to security reports within 24 hours and will keep you updated on our progress.

Documentation

Index

• Variables
• type Client
  • func NewClient(openaiOpts ...option.RequestOption) (*Client, error)
  • func NewClientWithParams(enclave, repo string, openaiOpts ...option.RequestOption) (*Client, error)
• type Enclave
• type GroundTruth
• type LoadBalancer
  • func NewLoadBalancer(enclaves []Enclave, openaiOpts ...option.RequestOption) (*LoadBalancer, error)
  • func (lb *LoadBalancer) NextClient() *Client
• type Response
• type SecureClient
  • func NewSecureClient() *SecureClient
  • func NewSecureClientWithParams(enclave, repo string) *SecureClient
  • func (s *SecureClient) AddHeader(requestID int64, key string, value string) error
  • func (s *SecureClient) ExecuteRequest(requestID int64) (*Response, error)
  • func (s *SecureClient) Get(url string, headers map[string]string) (*Response, error)
  • func (s *SecureClient) GroundTruth() *GroundTruth
  • func (s *SecureClient) HTTPClient() (*http.Client, error)
  • func (s *SecureClient) InitGetRequest(url string) (int64, error)
  • func (s *SecureClient) InitPostRequest(url string, body []byte) (int64, error)
  • func (s *SecureClient) Post(url string, headers map[string]string, body []byte) (*Response, error)
  • func (s *SecureClient) Verify() (*GroundTruth, error)
• type TLSBoundRoundTripper
  • func (t *TLSBoundRoundTripper) RoundTrip(r *http.Request) (*http.Response, error)

Variables

var (
	ErrNoTLS              = errors.New("no TLS connection")
	ErrCertMismatch       = errors.New("certificate fingerprint mismatch")
	ErrNoValidCertificate = errors.New("no valid certificate")
)

Types

type Client

type Client struct {
	*openai.Client
	// contains filtered or unexported fields
}

Client wraps the OpenAI client to provide secure inference through Tinfoil

func NewClient

func NewClient(openaiOpts ...option.RequestOption) (*Client, error)

NewClient creates a new secure OpenAI client using default parameters

func NewClientWithParams

func NewClientWithParams(enclave, repo string, openaiOpts ...option.RequestOption) (*Client, error)

NewClientWithParams creates a new secure OpenAI client with explicit enclave and repo parameters

type Enclave

type Enclave struct {
	Host string
	Repo string
}

type GroundTruth

type GroundTruth struct {
	PublicKeyFP string
	Digest      string
	Measurement string
}

GroundTruth represents the "known good" verified state of the enclave

type LoadBalancer

type LoadBalancer struct {
	// contains filtered or unexported fields
}

func NewLoadBalancer

func NewLoadBalancer(enclaves []Enclave, openaiOpts ...option.RequestOption) (*LoadBalancer, error)

func (*LoadBalancer) NextClient

func (lb *LoadBalancer) NextClient() *Client

NextClient returns the next client in round robin fashion using atomic operations

type Response

type Response struct {
	Status     string
	StatusCode int
	Body       []byte
}

type SecureClient

type SecureClient struct {
	// contains filtered or unexported fields
}

SecureClient provides a way to securely communicate with a verified enclave

func NewSecureClient

func NewSecureClient() *SecureClient

NewSecureClient creates a new client for secure communications with the enclave using default parameters

func NewSecureClientWithParams

func NewSecureClientWithParams(enclave, repo string) *SecureClient

NewSecureClientWithParams creates a new client for secure communications with the enclave using custom parameters

func (*SecureClient) AddHeader

func (s *SecureClient) AddHeader(requestID int64, key string, value string) error

AddHeader adds a header to a pending request

func (*SecureClient) ExecuteRequest

func (s *SecureClient) ExecuteRequest(requestID int64) (*Response, error)

ExecuteRequest executes a pending request and returns the response

func (*SecureClient) Get

func (s *SecureClient) Get(url string, headers map[string]string) (*Response, error)

Get makes an HTTP GET request

func (*SecureClient) GroundTruth

func (s *SecureClient) GroundTruth() *GroundTruth

GroundTruth returns the last verified enclave state

func (*SecureClient) HTTPClient

func (s *SecureClient) HTTPClient() (*http.Client, error)

HTTPClient returns an HTTP client that only accepts TLS connections to the verified enclave

func (*SecureClient) InitGetRequest

func (s *SecureClient) InitGetRequest(url string) (int64, error)

InitGetRequest initializes a new GET request and returns a unique request ID

func (*SecureClient) InitPostRequest

func (s *SecureClient) InitPostRequest(url string, body []byte) (int64, error)

InitPostRequest initializes a new POST request and returns a unique request ID

func (*SecureClient) Post

func (s *SecureClient) Post(url string, headers map[string]string, body []byte) (*Response, error)

Post makes an HTTP POST request

func (*SecureClient) Verify

func (s *SecureClient) Verify() (*GroundTruth, error)

Verify fetches the latest verification information from GitHub and Sigstore and stores the ground truth results in the client

type TLSBoundRoundTripper

type TLSBoundRoundTripper struct {
	ExpectedPublicKey string
}

func (*TLSBoundRoundTripper) RoundTrip

func (t *TLSBoundRoundTripper) RoundTrip(r *http.Request) (*http.Response, error)