Client

PrivatemodeAI is a drop-in replacement for the official OpenAI client that verifies the Privatemode deployment and encrypts all inference traffic end-to-end. See Getting started for installation and usage examples.

PrivatemodeAI

Secure OpenAI-compatible client backed by the encrypted Privatemode transport. Attestation and secret establishment happen lazily before the first OpenAI request.

Besides its own members, the client exposes the resources of the official OpenAI client: chat.completions, embeddings, and audio.transcriptions are routed through the encrypted transport.

See Getting started for the supported OpenAI resources.

Constructor

new PrivatemodeAI(options: PrivatemodeAIOptions)

optionsPrivatemodeAIOptionsrequired

`withOptions()`

withOptions(options: Partial<PrivatemodeOpenAIClientOptions>): this

Create a configured client that reuses this client's verified state.

optionsPartial<PrivatemodeOpenAIClientOptions>required

`verify()`

verify(): Promise<VerifyResult>

Verify the Privatemode deployment by fetching and verifying the attestation document of the coordinator, and initialize the encryption secret. If the encryption secret has already been initialized, the verification is still performed, keeping the existing secret.

Returns: The verification result.

Throws: If verification fails.

`initializeOffline()`

initializeOffline(manifestBytes: Uint8Array): Promise<void>

Initialize the client offline without performing attestation. This loads the Wasm module and sets up the API key and base URL, but skips remote attestation. Use this together with importSecret to restore a previously cached secret.

manifestBytesUint8Arrayrequired

Manifest bytes to set on the client (e.g. from a previous session's cache).

`refreshSecret()`

refreshSecret(): Promise<void>

Update the encryption secret. verify must have been called before calling this. Most callers will want to call this in some sort of loop to keep the secret up-to-date.

Throws: If the secret update fails or verify hasn't been called.

`exportSecret()`

exportSecret(): ExportedSecret

Export the current encryption secret so it can be cached and restored later with importSecret, avoiding a full HPKE handshake on reload.

verify and refreshSecret must have been called first.

Returns: The exported secret.

Throws: If no secret has been established yet.

`importSecret()`

importSecret(secret: ExportedSecret): void

Import a previously exported secret, restoring the encryption state without performing a new HPKE handshake.

verify must have been called first.

secretExportedSecretrequired

A secret previously obtained from exportSecret.

Throws: If the import fails.

`close()`

close(): void

Release the Wasm resources backing this client, including clients created from it with withOptions. Any further use of the client throws. Closing an already-closed client is a no-op.

`manifest`

get manifest(): Manifest | null

The current manifest in use. If no manifest has been set or fetched yet, this returns null. To save/restore the manifest use manifestBytes instead of this function, as JSON encoding/decoding may alter the bytes and cause verification to fail.

`manifestBytes`

get manifestBytes(): Uint8Array | null

The current manifest in use as raw bytes. Use this for caching the manifest or initializing the client offline with initializeOffline.

PrivatemodeAIOptions

Options for the OpenAI-compatible Privatemode client.

apiKeystring

Privatemode API key to authenticate with. Shorthand for an auth provider that always returns this key. Mutually exclusive with auth.

authAuthProvider

Authentication provider, invoked before every request to obtain the credential to use. Use this to authenticate with a Clerk JWT or anonymously, or to rotate short-lived credentials. Mutually exclusive with apiKey.

apiBaseURLstringdefault: https://api.privatemode.ai

API base URL.

manifestBytesUint8Array

Override for the manifest used to verify the Privatemode deployment. By default, the manifest is fetched from the Privatemode CDN. The bytes must be valid JSON matching the Manifest schema.

dangerouslyAllowBrowserbooleandefault: false

Whether to allow usage in a browser, which exposes the API key to the user and also increases vulnerability to cross-site attacks that might try to steal the key. Note that using Privatemode in a browser environment requires careful consideration of the security implications and appropriate mitigations (e.g. in response to cross-site attacks) to retain the security guarantees of Privatemode.

wasmURLstring | URL

URL or filesystem path of the Wasm module. In Node.js, the SDK loads the privatemode.wasm file shipped beside its JavaScript output by default.

The Wasm module is instantiated once per JavaScript realm: the first client to load it determines the binary, and later clients reuse the loaded module, ignoring their own wasmURL. Client state is still isolated per instance.

browserWasmURLstringdefault: ./privatemode.wasm

URL to load the Wasm module from in a browser environment. Ignored in Node.js. Takes precedence over wasmURL in browsers.

enableWasmLoggingbooleandefault: true

Surface the logs emitted by the Wasm module in the JavaScript console.

expectedWasmHashstring

Expected SHA-256 hash of the Wasm binary (hex-encoded). If provided, the loaded Wasm module is verified against this hash before instantiation. If the module was already loaded (see wasmURL), the hash is compared against the hash of the first load; it fails on a mismatch, and also if the module was loaded without a hash.

onManifestUpdate(manifestBytes: Uint8Array) => void

Optional callback invoked when the manifest is updated internally (e.g., due to a manifest mismatch during verification).

onSecretUpdate(secret: ExportedSecret) => void

Optional callback invoked when the encryption secret is refreshed or updated.

openAIOptionsPrivatemodeOpenAIClientOptions

Options forwarded to the official OpenAI client.

PrivatemodeOpenAIClientOptions

OpenAI client options whose values aren't controlled by Privatemode.

type PrivatemodeOpenAIClientOptions = Omit<
  ClientOptions,
  | 'adminAPIKey'
  | 'apiKey'
  | 'baseURL'
  | 'defaultQuery'
  | 'fetch'
  | 'fetchOptions'
  | 'provider'
  | 'workloadIdentity'
>;