@zeke-02/tinfoil 0.0.5 → 0.0.6

package/README.md

@@ -2,8 +2,9 @@
 
 [![Build Status](https://github.com/tinfoilsh/tinfoil-node/actions/workflows/test.yml/badge.svg)](https://github.com/tinfoilsh/tinfoil-node/actions)
 [![NPM version](https://img.shields.io/npm/v/tinfoil.svg)](https://npmjs.org/package/tinfoil)
+[![Documentation](https://img.shields.io/badge/docs-tinfoil.sh-blue)](https://docs.tinfoil.sh/sdk/node-sdk)
 
-This client library provides secure and convenient access to the Tinfoil Priavate Inference endpoints from TypeScript or JavaScript.
+This client library provides secure and convenient access to the Tinfoil Private Inference endpoints from TypeScript or JavaScript.
 
 It is a wrapper around the OpenAI client that verifies enclave attestation and routes traffic to the Tinfoil Private Inference endpoints through an [EHBP](https://github.com/tinfoilsh/encrypted-http-body-protocol)-secured transport. EHBP encrypts all payloads directly to an attested enclave using [HPKE (RFC 9180)](https://www.rfc-editor.org/rfc/rfc9180.html).
 
@@ -69,7 +70,7 @@ const completion = await client.chat.completions.create({
 
 ## Verification helpers
 
-This package exposes verification helpers that load the Go-based WebAssembly verifier once per process and provide structured, stepwise attestation results you can use in applications (e.g., to show progress, log transitions, or gate features).
+This package exposes verification helpers that load the Go-based WebAssembly verifier and provide end-to-end attestation with structured, stepwise results you can use in applications (e.g., to show progress, log transitions, or gate features).
 
 The verification functionality is contained in `verifier.ts`.
 
@@ -79,51 +80,62 @@ The verification functionality is contained in `verifier.ts`.
 ```typescript
 import { Verifier } from "tinfoil";
 
-const verifier = new Verifier();
-
-// Perform runtime attestation
-const runtime = await verifier.verifyEnclave("enclave.host.com");
-// Returns: { measurement: AttestationMeasurement, tlsPublicKeyFingerprint: string, hpkePublicKey: string }
-
-// Perform code attestation
-const code = await verifier.verifyCode("tinfoilsh/repo", "digest-hash");
-// Returns: { measurement: AttestationMeasurement }
-
-// Fetch latest digest from GitHub releases
-const digest = await verifier.fetchLatestDigest("tinfoilsh/repo");
+const verifier = new Verifier({ serverURL: "https://enclave.host.com" });
+
+// Perform full end-to-end verification
+const attestation = await verifier.verify();
+// Returns: AttestationResponse with measurement and cryptographic keys
+// This performs all verification steps atomically:
+// 1. Fetches the latest release digest from GitHub
+// 2. Verifies code provenance using Sigstore
+// 3. Performs runtime attestation against the enclave
+// 4. Verifies hardware measurements (for TDX platforms)
+// 5. Compares code and runtime measurements
+
+// Access detailed verification results
+const doc = verifier.getVerificationDocument();
+// Returns: VerificationDocument with step-by-step status including
+// measurements, fingerprints, and cryptographic keys
 ```
 
 ### Verification Document
 
-The `SecureClient` provides access to a comprehensive verification document that tracks all verification steps, including failures:
+The `Verifier` provides access to a comprehensive verification document that tracks all verification steps, including failures:
 
 ```typescript
-import { SecureClient } from "tinfoil";
+import { Verifier } from "tinfoil";
 
-const client = new SecureClient();
+const verifier = new Verifier({ serverURL: "https://enclave.host.com" });
 
 try {
-  await client.ready();
-  const response = await client.fetch('https://api.example.com/data');
+  const attestation = await verifier.verify();
+  const doc = verifier.getVerificationDocument();
+  console.log('Security verified:', doc.securityVerified);
+  console.log('TLS fingerprint:', attestation.tlsPublicKeyFingerprint);
+  console.log('HPKE public key:', attestation.hpkePublicKey);
 } catch (error) {
   // Even on error, you can access the verification document
-  const doc = await client.getVerificationDocument();
+  const doc = verifier.getVerificationDocument();
 
   // The document contains detailed step information:
   // - fetchDigest: GitHub release digest retrieval
   // - verifyCode: Code measurement verification
   // - verifyEnclave: Runtime attestation verification
   // - compareMeasurements: Code vs runtime measurement comparison
-  // - createTransport: Transport initialization (optional)
-  // - verifyHPKEKey: HPKE key verification (optional)
   // - otherError: Catch-all for unexpected errors (optional)
 
-  console.log('Security verified:', doc.securityVerified);
-
   // Check individual steps
   if (doc.steps.verifyEnclave.status === 'failed') {
     console.log('Enclave verification failed:', doc.steps.verifyEnclave.error);
   }
+
+  // Error messages are prefixed with the failing step:
+  // - "fetchDigest:" - Failed to fetch GitHub release digest
+  // - "verifyCode:" - Failed to verify code provenance
+  // - "verifyEnclave:" - Failed runtime attestation
+  // - "verifyHardware:" - Failed TDX hardware verification
+  // - "validateTLS:" - TLS public key validation failed
+  // - "measurements:" - Measurement comparison failed
 }
 ```
 
@@ -156,6 +168,8 @@ See [examples/README.md](https://github.com/tinfoilsh/tinfoil-node/blob/main/exa
 
 ## API Documentation
 
+For complete documentation on using the Tinfoil Node SDK, including advanced examples and API reference, visit the [official documentation](https://docs.tinfoil.sh/sdk/node-sdk).
+
 This library mirrors the official OpenAI Node.js client for common endpoints (e.g., chat, images, embeddings) and types, and is designed to feel familiar. Some less commonly used surfaces may not be fully covered. See the [OpenAI client](https://github.com/openai/openai-node) for complete API usage and documentation.
 
 ## Reporting Vulnerabilities

package/dist/ai-sdk-provider.d.ts

@@ -3,5 +3,5 @@ interface CreateTinfoilAIOptions {
     enclaveURL?: string;
     configRepo?: string;
 }
-export declare function createTinfoilAI(apiKey: string, options?: CreateTinfoilAIOptions): Promise<import("@ai-sdk/openai-compatible").OpenAICompatibleProvider<string, string, string, string>>;
+export declare function createTinfoilAI(apiKey: string, options?: CreateTinfoilAIOptions, headers?: Record<string, string>): Promise<import("@ai-sdk/openai-compatible").OpenAICompatibleProvider<string, string, string, string>>;
 export {};

package/dist/ai-sdk-provider.js

@@ -4,7 +4,7 @@ exports.createTinfoilAI = createTinfoilAI;
 const openai_compatible_1 = require("@ai-sdk/openai-compatible");
 const config_1 = require("./config");
 const secure_client_1 = require("./secure-client");
-async function createTinfoilAI(apiKey, options = {}) {
+async function createTinfoilAI(apiKey, options = {}, headers = {}) {
     const baseURL = options.baseURL;
     const enclaveURL = options.enclaveURL;
     const configRepo = options.configRepo || config_1.TINFOIL_CONFIG.INFERENCE_PROXY_REPO;
@@ -24,5 +24,6 @@ async function createTinfoilAI(apiKey, options = {}) {
         baseURL: finalBaseURL,
         apiKey: apiKey,
         fetch: secureClient.fetch,
+        headers,
     });
 }

package/dist/esm/ai-sdk-provider.d.ts

@@ -3,5 +3,5 @@ interface CreateTinfoilAIOptions {
     enclaveURL?: string;
     configRepo?: string;
 }
-export declare function createTinfoilAI(apiKey: string, options?: CreateTinfoilAIOptions): Promise<import("@ai-sdk/openai-compatible").OpenAICompatibleProvider<string, string, string, string>>;
+export declare function createTinfoilAI(apiKey: string, options?: CreateTinfoilAIOptions, headers?: Record<string, string>): Promise<import("@ai-sdk/openai-compatible").OpenAICompatibleProvider<string, string, string, string>>;
 export {};

package/dist/esm/ai-sdk-provider.mjs

@@ -1,7 +1,7 @@
 import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
 import { TINFOIL_CONFIG } from "./config.mjs";
 import { SecureClient } from "./secure-client.mjs";
-export async function createTinfoilAI(apiKey, options = {}) {
+export async function createTinfoilAI(apiKey, options = {}, headers = {}) {
     const baseURL = options.baseURL;
     const enclaveURL = options.enclaveURL;
     const configRepo = options.configRepo || TINFOIL_CONFIG.INFERENCE_PROXY_REPO;
@@ -21,5 +21,6 @@ export async function createTinfoilAI(apiKey, options = {}) {
         baseURL: finalBaseURL,
         apiKey: apiKey,
         fetch: secureClient.fetch,
+        headers,
     });
 }

package/dist/esm/secure-client.mjs

@@ -82,12 +82,20 @@ export class SecureClient {
                     releaseDigest: "",
                     codeMeasurement: { type: "", registers: [] },
                     enclaveMeasurement: { measurement: { type: "", registers: [] } },
+                    tlsPublicKey: "",
+                    hpkePublicKey: "",
+                    hardwareMeasurement: undefined,
+                    codeFingerprint: "",
+                    enclaveFingerprint: "",
+                    selectedRouterEndpoint: new URL(this.enclaveURL).hostname,
                     securityVerified: false,
                     steps: {
                         fetchDigest: { status: "pending" },
                         verifyCode: { status: "pending" },
                         verifyEnclave: { status: "pending" },
                         compareMeasurements: { status: "pending" },
+                        createTransport: undefined,
+                        verifyHPKEKey: undefined,
                         otherError: { status: "failed", error: error.message },
                     },
                 };

package/dist/esm/verifier.d.ts

@@ -5,6 +5,14 @@ export interface AttestationMeasurement {
     type: string;
     registers: string[];
 }
+/**
+ * Hardware measurement from TDX platform verification
+ */
+export interface HardwareMeasurement {
+    ID: string;
+    MRTD: string;
+    RTMR0: string;
+}
 /**
  * Attestation response containing cryptographic keys and measurements
  * At least one of tlsPublicKeyFingerprint or hpkePublicKey must be present
@@ -31,6 +39,12 @@ export interface VerificationDocument {
     releaseDigest: string;
     codeMeasurement: AttestationMeasurement;
     enclaveMeasurement: AttestationResponse;
+    tlsPublicKey: string;
+    hpkePublicKey: string;
+    hardwareMeasurement?: HardwareMeasurement;
+    codeFingerprint: string;
+    enclaveFingerprint: string;
+    selectedRouterEndpoint: string;
     securityVerified: boolean;
     steps: {
         fetchDigest: VerificationStepState;
@@ -42,29 +56,19 @@ export interface VerificationDocument {
         otherError?: VerificationStepState;
     };
 }
-export interface MeasurementComparisonResult {
-    match: boolean;
-    error?: Error;
-}
-export declare function compareMeasurementsDetailed(codeMeasurement: AttestationMeasurement, runtimeMeasurement: AttestationMeasurement): MeasurementComparisonResult;
-/**
- * Compare two measurements according to platform-specific rules
- * This is predicate function for comparing attestation measurements
- * taken from https://github.com/tinfoilsh/verifier/blob/main/attestation/attestation.go
- *
- * @param codeMeasurement - Expected measurement from code attestation
- * @param runtimeMeasurement - Actual measurement from runtime attestation
- * @returns true if measurements match according to platform rules
- */
-export declare function compareMeasurements(codeMeasurement: AttestationMeasurement, runtimeMeasurement: AttestationMeasurement): boolean;
 /**
  * Verifier performs attestation verification for Tinfoil enclaves
  *
- * The verifier loads a WebAssembly module that:
+ * The verifier loads a WebAssembly module (compiled from Go) that performs
+ * end-to-end attestation verification:
  * 1. Fetches the latest code release digest from GitHub
- * 2. Performs runtime attestation against the enclave
- * 3. Performs code attestation using the digest
- * 4. Compares measurements using platform-specific logic
+ * 2. Verifies code provenance using Sigstore/Rekor
+ * 3. Performs runtime attestation against the enclave
+ * 4. Verifies hardware measurements (for TDX platforms)
+ * 5. Compares code and runtime measurements using platform-specific logic
+ *
+ * Primary method: verify() - Returns AttestationResponse with cryptographic keys
+ * Verification details: getVerificationDocument() - Returns step-by-step results
  */
 export declare class Verifier {
     private static goInstance;
@@ -86,56 +90,52 @@ export declare class Verifier {
      */
     private static executeWithWasm;
     /**
-     * Fetch the latest release digest from GitHub
-     * @param configRepo - Repository name (e.g., "tinfoilsh/confidential-model-router")
-     * @returns The digest hash
-     */
-    fetchLatestDigest(configRepo?: string): Promise<string>;
-    /**
-     * Perform runtime attestation on the enclave
-     * @param enclaveHost - The enclave hostname
-     * @returns Attestation response with measurement and keys
-     */
-    verifyEnclave(enclaveHost?: string): Promise<AttestationResponse>;
-    /**
-     * Perform code attestation
-     * @param configRepo - Repository name
-     * @param digest - Code digest hash
-     * @returns Code measurement
-     */
-    verifyCode(configRepo: string, digest: string): Promise<{
-        measurement: AttestationMeasurement;
-    }>;
-    /**
-     * Perform attestation verification
+     * Perform end-to-end attestation verification
      *
-     * This method:
+     * This method performs all verification steps atomically via the Go WASM verify() function:
      * 1. Fetches the latest code digest from GitHub releases
-     * 2. Calls verifyCode to get the expected measurement for the code
-     * 3. Calls verifyEnclave to get the actual runtime measurement
-     * 4. Compares measurements using platform-specific logic (see `compareMeasurements()`)
-     * 5. Returns the attestation response if verification succeeds
+     * 2. Verifies code provenance using Sigstore/Rekor
+     * 3. Performs runtime attestation against the enclave
+     * 4. Verifies hardware measurements (for TDX platforms)
+     * 5. Compares code and runtime measurements using platform-specific logic
      *
      * The WASM runtime is automatically initialized and cleaned up within this method.
+     * A detailed verification document is saved and can be accessed via getVerificationDocument().
      *
-     * @throws Error if measurements don't match or verification fails
+     * @returns AttestationResponse containing cryptographic keys (TLS/HPKE) and enclave measurement
+     * @throws Error if measurements don't match or verification fails at any step
      */
     verify(): Promise<AttestationResponse>;
+    /**
+     * Save a failed verification document
+     */
+    private saveFailedVerificationDocument;
     /**
      * Internal verification logic that runs within WASM context
      */
     private verifyInternal;
     /**
-     * Returns the full verification document from the last successful verify() call
+     * Returns the verification document from the last verify() call
+     *
+     * The document contains detailed step-by-step verification results including:
+     * - Step status (pending/success/failed) for each verification phase
+     * - Measurements, fingerprints, and cryptographic keys
+     * - Error messages for any failed steps
+     *
+     * Available even if verification failed, allowing inspection of which step failed.
+     *
+     * @returns VerificationDocument with complete verification details, or undefined if verify() hasn't been called
      */
     getVerificationDocument(): VerificationDocument | undefined;
 }
 /**
  * Control WASM log output
  *
- * The Go WASM runtime outputs logs through a polyfilled fs.writeSync.
+ * The Go WASM runtime outputs logs (stdout/stderr) through a polyfilled fs.writeSync.
  * This function allows suppressing those logs without affecting other console output.
+ * By default, WASM logs are suppressed to reduce noise.
  *
  * @param suppress - Whether to suppress WASM logs (default: true)
+ * @returns void
  */
 export declare function suppressWasmLogs(suppress?: boolean): void;