tinfoil

README

Tinfoil Go Client

For complete documentation, see the Go SDK documentation.

Installation

Add the Tinfoil SDK to your project:

go get github.com/tinfoilsh/tinfoil-go

Quick Start

The Tinfoil Go client is a wrapper around the OpenAI Go client v3 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
• Supports Encrypted HTTP Body Protocol to provide direct-to-enclave encrypted communication with attested public keys
• Supports a fallback mode with TLS certificate pinning using attested certificates to provide direct-to-enclave encrypted communication over TLS

package main

import (
	"context"
	"fmt"
	"log"

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

func main() {
	// Create a client
	client, err := tinfoil.NewClient(
		option.WithAPIKey("<YOUR_API_KEY>"),
	)
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}

	// Make requests using the OpenAI client API
	// Note: enclave verification and direct-to-enclave encryption 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/models/catalog for supported models
	})

	if err != nil {
		log.Fatalf("Chat completion error: %v", err)
	}

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

Usage

// 1. Create a client
client, err := tinfoil.NewClient(
	option.WithAPIKey(os.Getenv("TINFOIL_API_KEY")),
)
if err != nil {
	log.Printf("Failed to create client: %v", err)
	return
}

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

Advanced Functionality

// Create a secure client with explicit enclave and repo parameters
client, err := tinfoil.NewClientWithParams(enclave, repo)
if err != nil {
	return fmt.Errorf("Failed to create client: %v", err)
}

// For direct HTTP access, use the underlying HTTPClient
httpClient := client.HTTPClient()
endpoint := fmt.Sprintf("https://%s/health", enclave)
resp, err := httpClient.Get(endpoint)
if err != nil {
	return fmt.Errorf("Request failed: %v", err)
}

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 emailing security@tinfoil.sh.

We aim to respond to (legitimate) security reports within 24 hours.

Documentation

Index

• type Client
  • func NewClient(openaiOpts ...option.RequestOption) (*Client, error)
  • func NewClientWithOptions(opts ...ClientOption) (*Client, error)
  • func NewClientWithParams(enclave, repo string, openaiOpts ...option.RequestOption) (*Client, error)
  • func (c *Client) Enclave() string
  • func (c *Client) HTTPClient() *http.Client
  • func (c *Client) Repo() string
  • func (c *Client) Transport() TransportMode
  • func (c *Client) Verify() (*client.GroundTruth, error)
• type ClientOption
  • func WithAttestationBundleURL(attestationBundleURL string) ClientOption
  • func WithBaseURL(baseURL string) ClientOption
  • func WithEnclave(enclave string) ClientOption
  • func WithOpenAIOptions(opts ...option.RequestOption) ClientOption
  • func WithRepo(repo string) ClientOption
  • func WithTransport(mode TransportMode) ClientOption
• type TransportMode

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 NewClientWithOptions

func NewClientWithOptions(opts ...ClientOption) (*Client, error)

NewClientWithOptions creates a secure OpenAI client configured through functional options. By default it selects a router automatically, verifies against the default config repository, and uses the EHBP transport.

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

func (*Client) Enclave

func (c *Client) Enclave() string

func (*Client) HTTPClient

func (c *Client) HTTPClient() *http.Client

HTTPClient returns the underlying HTTP client used to reach the enclave. It re-verifies attestation automatically when the enclave rotates its key, and it is bound to the verified enclave (and the configured proxy, if any): requests to any other host, or over plain http, are refused because request headers are not encrypted. This can be used for secure, direct HTTP requests to the enclave.

func (*Client) Repo

func (c *Client) Repo() string

func (*Client) Transport

func (c *Client) Transport() TransportMode

Transport returns the transport mode used to secure traffic to the enclave.

func (*Client) Verify

func (c *Client) Verify() (*client.GroundTruth, error)

Verify re-verifies the enclave attestation and returns the ground truth

type ClientOption

type ClientOption func(*clientConfig)

ClientOption configures a Client created with NewClientWithOptions.

func WithAttestationBundleURL

func WithAttestationBundleURL(attestationBundleURL string) ClientOption

WithAttestationBundleURL fetches the attestation bundle from the given base URL (for example your own proxy) instead of attesting the enclave directly, so the client only needs to reach a single origin. The bundle is still verified client-side. The enclave host is taken from the verified bundle.

func WithBaseURL

func WithBaseURL(baseURL string) ClientOption

WithBaseURL routes requests through the given base URL (for example your own proxy) instead of sending them directly to the enclave. Request bodies stay encrypted end-to-end to the verified enclave; when the base URL's origin differs from the enclave's, the SDK adds the X-Tinfoil-Enclave-Url header so the proxy can forward the encrypted request to the right enclave. Only supported with the EHBP transport.

func WithEnclave

func WithEnclave(enclave string) ClientOption

WithEnclave sets the enclave host to verify and connect to. When unset, a router is selected automatically.

func WithOpenAIOptions

func WithOpenAIOptions(opts ...option.RequestOption) ClientOption

WithOpenAIOptions appends options passed through to the underlying OpenAI client.

func WithRepo

func WithRepo(repo string) ClientOption

WithRepo sets the GitHub repository used for code measurement verification.

func WithTransport

func WithTransport(mode TransportMode) ClientOption

WithTransport selects the transport mode. Defaults to TransportEHBP.

type TransportMode

type TransportMode string

TransportMode selects how the SDK secures traffic to the enclave.

const (
	// TransportEHBP encrypts request bodies end-to-end with HPKE via the
	// Encrypted HTTP Body Protocol. Only the verified enclave can decrypt them,
	// so it works through proxies. This is the default.
	TransportEHBP TransportMode = "ehbp"

	// TransportTLS pins the enclave's TLS certificate. All traffic is encrypted
	// and terminated at the verified enclave, which requires a direct
	// connection (requests through a proxy will fail).
	TransportTLS TransportMode = "tls"
)