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 either:

• Emailing security@tinfoil.sh

• Opening an issue on GitHub on this repository

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

Documentation

Index

• type Annotation
• type BlockedSearch
• type Client
  • func NewClient(openaiOpts ...option.RequestOption) (*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) Verify() (*client.GroundTruth, error)
• type ReasoningItem
• type SummaryPart
• type URLCitation
• type WebSearchAction
• type WebSearchCall
• type WebSearchChoice
• type WebSearchDelta
• type WebSearchMessage
  • func ParseWebSearchMessage(body []byte) (*WebSearchMessage, error)
  • func ParseWebSearchResponse(body io.Reader) (*WebSearchMessage, error)
• type WebSearchStream
  • func NewWebSearchStream(body io.ReadCloser) *WebSearchStream
  • func SimulateWebSearchStream(data string) *WebSearchStream
  • func (s *WebSearchStream) Close() error
  • func (s *WebSearchStream) Current() *WebSearchStreamEvent
  • func (s *WebSearchStream) Err() error
  • func (s *WebSearchStream) Next() bool
• type WebSearchStreamEvent
  • func (e *WebSearchStreamEvent) IsWebSearchCall() bool
  • func (e *WebSearchStreamEvent) ToWebSearchCall() *WebSearchCall

Types

type Annotation

type Annotation struct {
	Type        string      `json:"type"` // "url_citation"
	URLCitation URLCitation `json:"url_citation"`
}

Annotation represents a citation or reference in the response.

type BlockedSearch

type BlockedSearch struct {
	ID     string `json:"id"`
	Query  string `json:"query"`
	Reason string `json:"reason,omitempty"`
}

BlockedSearch represents a search that was blocked due to PII.

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

func (*Client) Enclave

func (c *Client) Enclave() string

func (*Client) HTTPClient

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

HTTPClient returns the underlying HTTP client that is configured with automatic certificate re-verification and is restricted to TLS connections to the verified enclave. This can be used for secure, direct HTTP requests to the enclave.

func (*Client) Repo

func (c *Client) Repo() string

func (*Client) Verify

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

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

type ReasoningItem

type ReasoningItem struct {
	ID      string        `json:"id"`
	Type    string        `json:"type"` // "reasoning"
	Summary []SummaryPart `json:"summary,omitempty"`
}

ReasoningItem represents a reasoning step from the agent model.

type SummaryPart

type SummaryPart struct {
	Type string `json:"type"` // "summary_text"
	Text string `json:"text"`
}

SummaryPart represents a part of the reasoning summary.

type URLCitation

type URLCitation struct {
	Title         string `json:"title"`
	URL           string `json:"url"`
	Content       string `json:"content,omitempty"`
	PublishedDate string `json:"published_date,omitempty"`
}

URLCitation contains details about a cited source.

type WebSearchAction

type WebSearchAction struct {
	Type  string `json:"type"`  // Always "search"
	Query string `json:"query"` // The search query
}

WebSearchAction contains the search query details.

type WebSearchCall

type WebSearchCall struct {
	Type   string           `json:"type"`             // Always "web_search_call"
	ID     string           `json:"id"`               // Unique identifier (e.g., "ws_abc123")
	Status string           `json:"status"`           // "in_progress", "completed", "failed", or "blocked"
	Reason string           `json:"reason,omitempty"` // Present when status is "failed" or "blocked"
	Action *WebSearchAction `json:"action,omitempty"`
}

WebSearchCall represents a web search event emitted during streaming. These events are emitted before chat completion chunks and track search progress.

type WebSearchChoice

type WebSearchChoice struct {
	Index        int             `json:"index"`
	Delta        *WebSearchDelta `json:"delta,omitempty"`
	FinishReason string          `json:"finish_reason,omitempty"`
}

WebSearchChoice represents a choice in the chat completion chunk with web search metadata.

type WebSearchDelta

type WebSearchDelta struct {
	Content         string          `json:"content,omitempty"`
	Annotations     []Annotation    `json:"annotations,omitempty"`
	SearchReasoning string          `json:"search_reasoning,omitempty"`
	ReasoningItems  []ReasoningItem `json:"reasoning_items,omitempty"`
}

WebSearchDelta extends the standard delta with web search metadata. These fields appear in the metadata chunk before content chunks.

type WebSearchMessage

type WebSearchMessage struct {
	Content         string          `json:"content"`
	Annotations     []Annotation    `json:"annotations,omitempty"`
	SearchReasoning string          `json:"search_reasoning,omitempty"`
	ReasoningItems  []ReasoningItem `json:"reasoning_items,omitempty"`
	BlockedSearches []BlockedSearch `json:"blocked_searches,omitempty"`
}

WebSearchMessage extends the standard message with web search metadata. Used in non-streaming responses.

func ParseWebSearchMessage

func ParseWebSearchMessage(body []byte) (*WebSearchMessage, error)

ParseWebSearchMessage parses a non-streaming response body into a WebSearchMessage.

func ParseWebSearchResponse

func ParseWebSearchResponse(body io.Reader) (*WebSearchMessage, error)

ParseWebSearchResponse is a convenience function that reads and parses a response body.

type WebSearchStream

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

WebSearchStream wraps a streaming response and parses web search events.

func NewWebSearchStream

func NewWebSearchStream(body io.ReadCloser) *WebSearchStream

NewWebSearchStream creates a new WebSearchStream from a streaming HTTP response body.

func SimulateWebSearchStream

func SimulateWebSearchStream(data string) *WebSearchStream

SimulateWebSearchStream creates a WebSearchStream from raw SSE data (useful for testing).

func (*WebSearchStream) Close

func (s *WebSearchStream) Close() error

Close closes the underlying reader.

func (*WebSearchStream) Current

func (s *WebSearchStream) Current() *WebSearchStreamEvent

Current returns the current event in the stream. Must be called after Next() returns true.

func (*WebSearchStream) Err

func (s *WebSearchStream) Err() error

Err returns any error that occurred during streaming.

func (*WebSearchStream) Next

func (s *WebSearchStream) Next() bool

Next advances to the next event in the stream. Returns true if there is a next event, false if the stream is exhausted or an error occurred.

type WebSearchStreamEvent

type WebSearchStreamEvent struct {
	// WebSearchCall fields (present when Type == "web_search_call")
	Type   string           `json:"type,omitempty"`
	ID     string           `json:"id,omitempty"`
	Status string           `json:"status,omitempty"`
	Reason string           `json:"reason,omitempty"`
	Action *WebSearchAction `json:"action,omitempty"`

	// Chat completion chunk fields (present when Type is empty or not "web_search_call")
	Choices []WebSearchChoice `json:"choices,omitempty"`
}

WebSearchStreamEvent represents either a WebSearchCall or a chat completion chunk. Use IsWebSearchCall() to determine the event type.

func (*WebSearchStreamEvent) IsWebSearchCall

func (e *WebSearchStreamEvent) IsWebSearchCall() bool

IsWebSearchCall returns true if this event is a web search call event.

func (*WebSearchStreamEvent) ToWebSearchCall

func (e *WebSearchStreamEvent) ToWebSearchCall() *WebSearchCall

ToWebSearchCall converts this event to a WebSearchCall. Returns nil if this is not a web search call event.