@routstr/sdk 0.3.11 → 0.3.13

package/dist/client/index.d.mts

@@ -3,6 +3,7 @@ import { P as ProviderRegistry, W as WalletAdapter, S as StorageAdapter, a as St
 import { S as SdkStore, c as UsageTrackingDriver } from '../store-CuXwe5Rg.mjs';
 import { CashuSpender, BalanceManager } from '../wallet/index.mjs';
 import { Transform } from 'stream';
+import { SecureClient, VerificationDocument } from 'tinfoil';
 import 'zustand/vanilla';
 import '../interfaces-Cv1k2EUK.mjs';
 
@@ -264,6 +265,9 @@ declare class RoutstrClient {
      * Make the API request with failover support
      */
     private _makeRequest;
+    /**
+     * Store request details to a file in the reqs/ folder before fetch.
+     */
     /**
      * Handle error responses with failover
      */
@@ -272,6 +276,11 @@ declare class RoutstrClient {
      * Handle post-response balance update for all modes
      */
     private _handlePostResponseBalanceUpdate;
+    /**
+     * Extract sats cost from EHBP/Tinfoil response headers as a last-resort
+     * fallback when neither balance delta nor SSE/body usage provides a cost.
+     */
+    private _headerSatsCost;
     private _trackResponseUsage;
     /**
      * Check wallet balance and throw if insufficient
@@ -289,6 +298,13 @@ declare class RoutstrClient {
      * Attach auth headers using the active client mode
      */
     private _withAuthHeader;
+    /**
+     * Attach auth headers and preserve the plaintext model hint required by the
+     * Routstr proxy for Tinfoil/EHBP requests. EHBP encrypts the JSON body, so
+     * retries/failover must not rebuild headers from baseHeaders alone or the
+     * proxy cannot route/price the encrypted request.
+     */
+    private _withAuthAndTinfoilHeaders;
 }
 
 /**
@@ -372,6 +388,15 @@ interface UsageTrackingData {
 declare function extractUsageFromResponseBody(body: unknown, fallbackSatsCost?: number): UsageTrackingData | null;
 declare function extractResponseId(body: unknown): string | undefined;
 declare function extractUsageFromSSEJson(parsed: any, fallbackSatsCost?: number): UsageTrackingData | null;
+/**
+ * Extract cost/usage from EHBP/Tinfoil response headers.
+ *
+ * For EHBP requests the proxy cannot inject cost into the JSON/SSE body
+ * (the body is opaque encrypted). Instead it returns cost as response
+ * headers. This parses those headers into the same UsageTrackingData
+ * shape used for SSE/body extraction, so callers can merge or fall back.
+ */
+declare function extractUsageFromResponseHeaders(headers: Headers | Record<string, string>): UsageTrackingData | null;
 declare function toUsageStats(usage: UsageTrackingData | null | undefined): UsageStats | undefined;
 
 /**
@@ -413,6 +438,65 @@ declare function inspectSSEWebStream(stream: ReadableStream<Uint8Array>, onUsage
  */
 declare function createSSEParserTransform(onUsage: (usage: UsageTrackingData) => void, onResponseId?: (responseId: string) => void): Transform;
 
+/**
+ * TinfoilSecure - EHBP transport encryption + enclave attestation for Tinfoil models.
+ *
+ * Any model whose id starts with `tinfoil-` is routed through Tinfoil EHBP.
+ * SecureClient performs attestation (`ready()`) and verifies the enclave code
+ * fingerprint. The SDK then uses EHBP request encryption so only the attested
+ * enclave can decrypt request bodies.
+ *
+ * Unlike Venice E2EE, there is no per-field message encryption and no custom SSE
+ * decrypt transform. Successful enclave responses are decrypted before normal
+ * SDK response handling sees them. Plaintext proxy-side errors (for example
+ * auth/balance failures before the request reaches the enclave) are preserved
+ * with their real status/body.
+ */
+
+interface TinfoilClientContext {
+    client: SecureClient;
+    verification: VerificationDocument;
+}
+interface TinfoilClientOptions {
+    /** Routstr/provider base URL that will receive the EHBP-wrapped request. */
+    baseUrl: string;
+    /** Optional explicit attestation bundle origin. Defaults to Tinfoil's ATC. */
+    attestationBundleURL?: string;
+    /** Optional explicit enclave URL for custom Tinfoil deployments. */
+    enclaveURL?: string;
+    /** Optional source repo for code verification when enclaveURL is explicit. */
+    configRepo?: string;
+}
+/** Check if a model ID should use Tinfoil EHBP transport. */
+declare function isTinfoilModel(modelId: string): boolean;
+/**
+ * Return the model id sent inside the EHBP-encrypted request body.
+ *
+ * Strips the `tinfoil-` prefix so the attested enclave receives the bare
+ * model id it expects (e.g. "kimi-k2-6"), not the caller-facing routstr id.
+ */
+declare function getTinfoilUpstreamModelId(modelId: string): string;
+/**
+ * Attest and return a cached Tinfoil SecureClient for a provider base URL.
+ */
+declare function prepareTinfoilClient(options: TinfoilClientOptions): Promise<TinfoilClientContext>;
+/**
+ * Fetch through Tinfoil EHBP while preserving plaintext proxy error responses.
+ *
+ * Tinfoil's stock SecureClient.fetch throws ProtocolError when a response to an
+ * encrypted request lacks Ehbp-Response-Nonce. That is correct for successful
+ * enclave responses, but Routstr proxy-side auth/balance errors are plaintext
+ * and need to flow through the SDK's normal error handling with their real
+ * status/body. This wrapper performs the same request-body encryption and
+ * response decryption, but returns non-EHBP responses unchanged.
+ *
+ * It also keeps SecureClient's key-rotation behavior: an EHBP key-config
+ * mismatch response triggers one fresh attestation and one retry.
+ */
+declare function fetchTinfoilPreservingPlaintextErrors(options: TinfoilClientOptions, input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+/** Clear cached Tinfoil clients, mainly useful for tests or forced re-attest. */
+declare function clearTinfoilClientCache(): void;
+
 /**
  * Options for fetching AI response
  */
@@ -451,4 +535,4 @@ interface FetchAIResponseDeps {
  */
 declare function fetchAIResponse(options: FetchOptions, callbacks: StreamingCallbacks, deps: FetchAIResponseDeps): Promise<void>;
 
-export { type AlertLevel, type DebugLevel, type FetchAIResponseDeps, type ModelProviderPrice, ProviderManager, type RequestResponseLogRequestInput, type RequestResponseLogSink, type RouteRequestParams, RoutstrClient, type RoutstrClientConfig, type RoutstrClientMode, type StreamCallbacks, StreamProcessor, type UsageTrackingData, createSSEParserTransform, extractResponseId, extractUsageFromResponseBody, extractUsageFromSSEJson, fetchAIResponse, inspectSSEWebStream, toUsageStats };
+export { type AlertLevel, type DebugLevel, type FetchAIResponseDeps, type ModelProviderPrice, ProviderManager, type RequestResponseLogRequestInput, type RequestResponseLogSink, type RouteRequestParams, RoutstrClient, type RoutstrClientConfig, type RoutstrClientMode, type StreamCallbacks, StreamProcessor, type TinfoilClientContext, type TinfoilClientOptions, type UsageTrackingData, clearTinfoilClientCache, createSSEParserTransform, extractResponseId, extractUsageFromResponseBody, extractUsageFromResponseHeaders, extractUsageFromSSEJson, fetchAIResponse, fetchTinfoilPreservingPlaintextErrors, getTinfoilUpstreamModelId, inspectSSEWebStream, isTinfoilModel, prepareTinfoilClient, toUsageStats };

package/dist/client/index.d.ts

@@ -3,6 +3,7 @@ import { P as ProviderRegistry, W as WalletAdapter, S as StorageAdapter, a as St
 import { S as SdkStore, c as UsageTrackingDriver } from '../store-CAQLSbEj.js';
 import { CashuSpender, BalanceManager } from '../wallet/index.js';
 import { Transform } from 'stream';
+import { SecureClient, VerificationDocument } from 'tinfoil';
 import 'zustand/vanilla';
 import '../interfaces-iL7CWeG5.js';
 
@@ -264,6 +265,9 @@ declare class RoutstrClient {
      * Make the API request with failover support
      */
     private _makeRequest;
+    /**
+     * Store request details to a file in the reqs/ folder before fetch.
+     */
     /**
      * Handle error responses with failover
      */
@@ -272,6 +276,11 @@ declare class RoutstrClient {
      * Handle post-response balance update for all modes
      */
     private _handlePostResponseBalanceUpdate;
+    /**
+     * Extract sats cost from EHBP/Tinfoil response headers as a last-resort
+     * fallback when neither balance delta nor SSE/body usage provides a cost.
+     */
+    private _headerSatsCost;
     private _trackResponseUsage;
     /**
      * Check wallet balance and throw if insufficient
@@ -289,6 +298,13 @@ declare class RoutstrClient {
      * Attach auth headers using the active client mode
      */
     private _withAuthHeader;
+    /**
+     * Attach auth headers and preserve the plaintext model hint required by the
+     * Routstr proxy for Tinfoil/EHBP requests. EHBP encrypts the JSON body, so
+     * retries/failover must not rebuild headers from baseHeaders alone or the
+     * proxy cannot route/price the encrypted request.
+     */
+    private _withAuthAndTinfoilHeaders;
 }
 
 /**
@@ -372,6 +388,15 @@ interface UsageTrackingData {
 declare function extractUsageFromResponseBody(body: unknown, fallbackSatsCost?: number): UsageTrackingData | null;
 declare function extractResponseId(body: unknown): string | undefined;
 declare function extractUsageFromSSEJson(parsed: any, fallbackSatsCost?: number): UsageTrackingData | null;
+/**
+ * Extract cost/usage from EHBP/Tinfoil response headers.
+ *
+ * For EHBP requests the proxy cannot inject cost into the JSON/SSE body
+ * (the body is opaque encrypted). Instead it returns cost as response
+ * headers. This parses those headers into the same UsageTrackingData
+ * shape used for SSE/body extraction, so callers can merge or fall back.
+ */
+declare function extractUsageFromResponseHeaders(headers: Headers | Record<string, string>): UsageTrackingData | null;
 declare function toUsageStats(usage: UsageTrackingData | null | undefined): UsageStats | undefined;
 
 /**
@@ -413,6 +438,65 @@ declare function inspectSSEWebStream(stream: ReadableStream<Uint8Array>, onUsage
  */
 declare function createSSEParserTransform(onUsage: (usage: UsageTrackingData) => void, onResponseId?: (responseId: string) => void): Transform;
 
+/**
+ * TinfoilSecure - EHBP transport encryption + enclave attestation for Tinfoil models.
+ *
+ * Any model whose id starts with `tinfoil-` is routed through Tinfoil EHBP.
+ * SecureClient performs attestation (`ready()`) and verifies the enclave code
+ * fingerprint. The SDK then uses EHBP request encryption so only the attested
+ * enclave can decrypt request bodies.
+ *
+ * Unlike Venice E2EE, there is no per-field message encryption and no custom SSE
+ * decrypt transform. Successful enclave responses are decrypted before normal
+ * SDK response handling sees them. Plaintext proxy-side errors (for example
+ * auth/balance failures before the request reaches the enclave) are preserved
+ * with their real status/body.
+ */
+
+interface TinfoilClientContext {
+    client: SecureClient;
+    verification: VerificationDocument;
+}
+interface TinfoilClientOptions {
+    /** Routstr/provider base URL that will receive the EHBP-wrapped request. */
+    baseUrl: string;
+    /** Optional explicit attestation bundle origin. Defaults to Tinfoil's ATC. */
+    attestationBundleURL?: string;
+    /** Optional explicit enclave URL for custom Tinfoil deployments. */
+    enclaveURL?: string;
+    /** Optional source repo for code verification when enclaveURL is explicit. */
+    configRepo?: string;
+}
+/** Check if a model ID should use Tinfoil EHBP transport. */
+declare function isTinfoilModel(modelId: string): boolean;
+/**
+ * Return the model id sent inside the EHBP-encrypted request body.
+ *
+ * Strips the `tinfoil-` prefix so the attested enclave receives the bare
+ * model id it expects (e.g. "kimi-k2-6"), not the caller-facing routstr id.
+ */
+declare function getTinfoilUpstreamModelId(modelId: string): string;
+/**
+ * Attest and return a cached Tinfoil SecureClient for a provider base URL.
+ */
+declare function prepareTinfoilClient(options: TinfoilClientOptions): Promise<TinfoilClientContext>;
+/**
+ * Fetch through Tinfoil EHBP while preserving plaintext proxy error responses.
+ *
+ * Tinfoil's stock SecureClient.fetch throws ProtocolError when a response to an
+ * encrypted request lacks Ehbp-Response-Nonce. That is correct for successful
+ * enclave responses, but Routstr proxy-side auth/balance errors are plaintext
+ * and need to flow through the SDK's normal error handling with their real
+ * status/body. This wrapper performs the same request-body encryption and
+ * response decryption, but returns non-EHBP responses unchanged.
+ *
+ * It also keeps SecureClient's key-rotation behavior: an EHBP key-config
+ * mismatch response triggers one fresh attestation and one retry.
+ */
+declare function fetchTinfoilPreservingPlaintextErrors(options: TinfoilClientOptions, input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+/** Clear cached Tinfoil clients, mainly useful for tests or forced re-attest. */
+declare function clearTinfoilClientCache(): void;
+
 /**
  * Options for fetching AI response
  */
@@ -451,4 +535,4 @@ interface FetchAIResponseDeps {
  */
 declare function fetchAIResponse(options: FetchOptions, callbacks: StreamingCallbacks, deps: FetchAIResponseDeps): Promise<void>;
 
-export { type AlertLevel, type DebugLevel, type FetchAIResponseDeps, type ModelProviderPrice, ProviderManager, type RequestResponseLogRequestInput, type RequestResponseLogSink, type RouteRequestParams, RoutstrClient, type RoutstrClientConfig, type RoutstrClientMode, type StreamCallbacks, StreamProcessor, type UsageTrackingData, createSSEParserTransform, extractResponseId, extractUsageFromResponseBody, extractUsageFromSSEJson, fetchAIResponse, inspectSSEWebStream, toUsageStats };
+export { type AlertLevel, type DebugLevel, type FetchAIResponseDeps, type ModelProviderPrice, ProviderManager, type RequestResponseLogRequestInput, type RequestResponseLogSink, type RouteRequestParams, RoutstrClient, type RoutstrClientConfig, type RoutstrClientMode, type StreamCallbacks, StreamProcessor, type TinfoilClientContext, type TinfoilClientOptions, type UsageTrackingData, clearTinfoilClientCache, createSSEParserTransform, extractResponseId, extractUsageFromResponseBody, extractUsageFromResponseHeaders, extractUsageFromSSEJson, fetchAIResponse, fetchTinfoilPreservingPlaintextErrors, getTinfoilUpstreamModelId, inspectSSEWebStream, isTinfoilModel, prepareTinfoilClient, toUsageStats };