From 908d140231d1bccb3625eb749aefb9aed6d5e219 Mon Sep 17 00:00:00 2001 From: Aiden Cline <63023139+rekram1-node@users.noreply.github.com> Date: Fri, 13 Nov 2026 00:56:44 -0600 Subject: [PATCH] feat(core): present a provider's client certificate on model requests (#61832) --- bun.lock | 1 + .../protocols/utils/responses-compaction.ts | 2 +- packages/ai/src/route/executor-service.ts | 9 ++++ packages/ai/src/route/executor.ts | 19 ++++++++- packages/ai/src/route/media.ts | 10 +++-- packages/ai/src/route/transport/http.ts | 5 ++- packages/ai/src/schema/options.ts | 10 +++++ .../client/src/promise/generated/types.ts | 4 ++ packages/core/package.json | 7 ++++ packages/core/src/aisdk.ts | 9 +++- packages/core/src/effect/app-node-platform.ts | 42 +++++++++++++++++-- .../src/effect/client-tls/client-tls.bun.ts | 8 ++++ .../src/effect/client-tls/client-tls.node.ts | 17 ++++++++ .../core/src/effect/client-tls/client-tls.ts | 12 ++++++ .../effect/client-tls/client-tls.workerd.ts | 8 ++++ packages/core/src/model-resolver.ts | 15 +++++-- packages/core/src/provider.ts | 8 ++++ packages/protocol/openapi.json | 24 +++++++++++ packages/schema/src/provider.ts | 9 ++++ services/site/src/docs/content/network.mdx | 34 ++++++++++++++- 20 files changed, 236 insertions(+), 17 deletions(-) create mode 100644 packages/core/src/effect/client-tls/client-tls.bun.ts create mode 100644 packages/core/src/effect/client-tls/client-tls.node.ts create mode 100644 packages/core/src/effect/client-tls/client-tls.ts create mode 100644 packages/core/src/effect/client-tls/client-tls.workerd.ts diff --git a/bun.lock b/bun.lock index 1d3b9f1ef05..b4572e69a87 100644 --- a/bun.lock +++ b/bun.lock @@ -247,6 +247,7 @@ "jose": "6.0.11", "jsonc-parser": "3.3.1", "mime-types": "3.0.2", + "undici": "8.12.3", "which": "6.0.1", "zod": "catalog:", }, diff --git a/packages/ai/src/protocols/utils/responses-compaction.ts b/packages/ai/src/protocols/utils/responses-compaction.ts index d276e5246ec..3500019b7b0 100644 --- a/packages/ai/src/protocols/utils/responses-compaction.ts +++ b/packages/ai/src/protocols/utils/responses-compaction.ts @@ -117,7 +117,7 @@ export const make = ( auth: route.auth, encodeBody: Schema.encodeSync(Schema.fromJsonString(Body)), }) - const response = yield* executor.execute( + const response = yield* RequestExecutor.withTls(executor.execute, request.http?.tls)( ProviderShared.jsonPost({ url: parts.url, body: parts.bodyText, diff --git a/packages/ai/src/route/executor-service.ts b/packages/ai/src/route/executor-service.ts index 20539b6635c..4eb33784d6e 100644 --- a/packages/ai/src/route/executor-service.ts +++ b/packages/ai/src/route/executor-service.ts @@ -1,6 +1,7 @@ import { Context, type Effect } from "effect" import type { Headers, HttpClientRequest, HttpClientResponse } from "effect/http" import { HttpContext, type AIError } from "../schema/errors.js" +import type { ClientTls } from "../schema/options.js" // The service tag lives in its own leaf module so `Media.Asset` (imported by the schema layer) can require the // executor without pulling the full executor implementation, and therefore the schema barrel, into a cycle. @@ -23,6 +24,14 @@ export class RequestExecutorService extends Context.Service("@opencode/AI/RequestExecutor/CurrentTls", { + defaultValue: () => undefined, +}) export type Service = RequestExecutorService export const headerDetails = (headers: Headers.Headers) => diff --git a/packages/ai/src/route/executor.ts b/packages/ai/src/route/executor.ts index 11082ef4e81..51c789a8d14 100644 --- a/packages/ai/src/route/executor.ts +++ b/packages/ai/src/route/executor.ts @@ -9,9 +9,17 @@ import { } from "effect/http" import { HttpContext, HttpRateLimitDetails, AIError, TransportError } from "../schema/index.js" import { classifyProviderFailure, providerErrorMessage } from "../provider-error.js" -import { headerDetails, responseHttp, Service, type HttpMiddleware, type Interface } from "./executor-service.js" +import { + CurrentTls, + headerDetails, + responseHttp, + Service, + type HttpMiddleware, + type Interface, +} from "./executor-service.js" +import type { ClientTls } from "../schema/options.js" -export { responseHttp, Service } from "./executor-service.js" +export { CurrentTls, responseHttp, Service } from "./executor-service.js" export type { HttpHandler, HttpMiddleware, Interface, RequestExecutorService } from "./executor-service.js" const normalizedHeaders = (headers: Headers.Headers) => @@ -253,6 +261,13 @@ export const layer: Layer.Layer = Layer.e export const fetchLayer = layer.pipe(Layer.provide(FetchHttpClient.layer)) +/** + * Sends through `execute`, presenting `tls` on each request. Apply it only where a provider request is sent, so + * downloads made through the plain executor never carry the certificate. The executor's HTTP client reads `CurrentTls`. + */ +export const withTls = (execute: Interface["execute"], tls: ClientTls | undefined): Interface["execute"] => + tls ? (request, middleware) => execute(request, middleware).pipe(Effect.provideService(CurrentTls, tls)) : execute + /** * Per-call middleware that sends through `fetch` instead of the executor's HTTP client. Executor middleware and * `middleware` still wrap the call, and status classification still applies. diff --git a/packages/ai/src/route/media.ts b/packages/ai/src/route/media.ts index 5df443a0931..37228f11988 100644 --- a/packages/ai/src/route/media.ts +++ b/packages/ai/src/route/media.ts @@ -347,7 +347,7 @@ const makeTransport = ( body: encoded.text, headers: encoded.headers, }) - const response = yield* execute( + const response = yield* RequestExecutor.withTls(execute, call.request.http?.tls)( encoded.apply(HttpClientRequest.make(call.method)(url).pipe(HttpClientRequest.setHeaders(headers))), RequestExecutor.withFetch(fetch), ) @@ -375,9 +375,11 @@ const makeTransport = ( protocol.prepare === undefined ? request : yield* protocol.prepare(request, (path, body) => - send({ method: "POST", url: baseURL(path), headers, request, body }, request.fetch, execute).pipe( - Effect.map((sent) => sent.response), - ), + send( + { method: "POST", url: baseURL(path), headers, request: { ...request, http }, body }, + request.fetch, + execute, + ).pipe(Effect.map((sent) => sent.response)), ) // Sanitize after merging so model-level overlays are covered; the model value is restored, not sanitized. const resolved: Request = { diff --git a/packages/ai/src/route/transport/http.ts b/packages/ai/src/route/transport/http.ts index 7924bbf02b3..daca308c631 100644 --- a/packages/ai/src/route/transport/http.ts +++ b/packages/ai/src/route/transport/http.ts @@ -109,7 +109,10 @@ export const httpJson = (input: HttpJsonInput): HttpJs const limits = timeoutConfig(request.timeout) // Unlike the header and chunk limits, the whole-request budget has no default. const total = limits.total ? Duration.millis(limits.total) : Duration.infinity - const response = yield* runtime.http.execute(prepared.request, prepared.middleware).pipe( + const response = yield* RequestExecutor.withTls(runtime.http.execute, request.http?.tls)( + prepared.request, + prepared.middleware, + ).pipe( Effect.timeoutOrElse({ duration: Duration.min(timeoutDuration(limits.headers), total), orElse: () => timeout("request", "Timed out waiting for response headers"), diff --git a/packages/ai/src/schema/options.ts b/packages/ai/src/schema/options.ts index f9d6bff13ef..48bb876901c 100644 --- a/packages/ai/src/schema/options.ts +++ b/packages/ai/src/schema/options.ts @@ -72,6 +72,15 @@ export interface HttpOptions { readonly body?: Record /** Compression for JSON request bodies. Only set it for endpoints known to decode it. */ readonly encoding?: RequestEncoding + /** Client certificate presented to HTTPS endpoints that request one (mutual TLS). */ + readonly tls?: ClientTls +} + +/** PEM client certificate and private key, with the passphrase of an encrypted key. */ +export interface ClientTls { + readonly cert: string + readonly key: string + readonly passphrase?: string } /** Per-phase time limits in milliseconds. */ @@ -127,6 +136,7 @@ export const mergeTransport = (...items: ReadonlyArray item?.query)), body: mergeJsonRecords(...http.map((item) => item?.body)), encoding: last(http.map((item) => item?.encoding)), + tls: last(http.map((item) => item?.tls)), }), } } diff --git a/packages/client/src/promise/generated/types.ts b/packages/client/src/promise/generated/types.ts index cac31d2b577..591a8731ebc 100644 --- a/packages/client/src/promise/generated/types.ts +++ b/packages/client/src/promise/generated/types.ts @@ -31,6 +31,8 @@ export type ProviderTransport = "http" | "websocket" export type ProviderEncoding = "zstd" | "gzip" | "none" +export type ProviderTls = { cert: string; key: string; passphrase?: string } + export type AgentColor = string export type PermissionEffect = "allow" | "deny" | "ask" @@ -1065,6 +1067,7 @@ export type ProviderSettings = { cache?: ProviderCache transport?: ProviderTransport encoding?: ProviderEncoding + tls?: ProviderTls } & { [x: string]: any } export type ModelSettings = { compaction?: ProviderCompaction; cache?: ProviderCache; encoding?: ProviderEncoding } & { @@ -1079,6 +1082,7 @@ export type ConfigProviderSettings = { cache?: ProviderCache transport?: ProviderTransport encoding?: ProviderEncoding + tls?: ProviderTls } & { [x: string]: JsonValue | null } export type ConfigModelSettings = { diff --git a/packages/core/package.json b/packages/core/package.json index b85d38e81ed..17d3523e170 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -64,6 +64,12 @@ "node": "./src/image/photon-wasm.node.ts", "default": "./src/image/photon-wasm.bun.ts" }, + "#client-tls": { + "workerd": "./src/effect/client-tls/client-tls.workerd.ts", + "bun": "./src/effect/client-tls/client-tls.bun.ts", + "node": "./src/effect/client-tls/client-tls.node.ts", + "default": "./src/effect/client-tls/client-tls.bun.ts" + }, "#v1-migration": { "types": "./src/database/v1-migration.bun.ts", "bun": "./src/database/v1-migration.bun.ts", @@ -128,6 +134,7 @@ "jose": "6.0.11", "jsonc-parser": "3.3.1", "mime-types": "3.0.2", + "undici": "8.12.3", "which": "6.0.1", "zod": "catalog:" }, diff --git a/packages/core/src/aisdk.ts b/packages/core/src/aisdk.ts index 990ecdb1e92..37aefadb497 100644 --- a/packages/core/src/aisdk.ts +++ b/packages/core/src/aisdk.ts @@ -3,6 +3,7 @@ export * as AISDK from "./aisdk.js" import { makeLocationNode } from "@opencode/util/effect/app-node" import { httpFetch } from "@opencode/util/effect/app-node-platform" import { APICallError } from "@ai-sdk/provider" +import { ClientTls } from "#client-tls" import type { JSONSchema7, JSONValue, @@ -134,6 +135,7 @@ function prepareOptions(model: RuntimeInfo, pkg: string, outbound: Fetch) { const customFetch = settings.fetch const timeouts = Provider.timeouts(settings) + const tls = Provider.tls(settings) options.fetch = async (input: Parameters[0], init?: RequestInit) => { const opts = { ...(init ?? {}) } // A plain AbortSignal.timeout would keep running into the body stream, so the header limit uses @@ -160,7 +162,12 @@ function prepareOptions(model: RuntimeInfo, pkg: string, outbound: Fetch) { } } - const send: Fetch = isFetch(customFetch) ? customFetch : outbound + const https = String(input instanceof Request ? input.url : input).startsWith("https:") + const certified = tls && https ? ClientTls.sender(tls) : undefined + if (tls && https && !certified) throw new Error("Client certificates aren't supported on this runtime") + // A followed redirect keeps the TLS options, so it would present the client certificate to another host. + if (certified) Object.assign(opts, certified.init, { redirect: "error" }) + const send: Fetch = certified ? certified.fetch : isFetch(customFetch) ? customFetch : outbound const middleware = httpMiddleware.getStore() const res = await ( middleware diff --git a/packages/core/src/effect/app-node-platform.ts b/packages/core/src/effect/app-node-platform.ts index 5b5aee62f6c..d4de27864ef 100644 --- a/packages/core/src/effect/app-node-platform.ts +++ b/packages/core/src/effect/app-node-platform.ts @@ -1,9 +1,10 @@ import { LLMClient, RequestExecutor } from "@opencode/ai/route" -import { Effect, Layer } from "effect" -import { FetchHttpClient, HttpClient } from "effect/http" +import { Effect, Layer, Option } from "effect" +import { FetchHttpClient, HttpClient, HttpClientError } from "effect/http" import { Socket } from "effect/socket" import { makeGlobalNode } from "@opencode/util/effect/app-node" import { httpClient } from "@opencode/util/effect/app-node-platform" +import { ClientTls } from "#client-tls" import { WebSocketConstructor } from "./websocket-constructor.js" // Bun's fetch ends a request after five quiet minutes, before provider routes' own header and chunk timeouts. @@ -18,9 +19,44 @@ const withoutBunTimeout = Layer.effect( }), ) +// Presents the model's client certificate (provider `settings.tls`) on its HTTPS requests, through this runtime's +// certificate-capable fetch. The TLS handshake only sends it to servers that request one. +const withClientCertificate = Layer.effect( + HttpClient.HttpClient, + Effect.gen(function* () { + const client = yield* HttpClient.HttpClient + return HttpClient.transform(client, (effect, request) => + Effect.gen(function* () { + const tls = yield* RequestExecutor.CurrentTls + if (!tls || !request.url.startsWith("https:")) return yield* effect + const sender = ClientTls.sender(tls) + if (!sender) + return yield* new HttpClientError.HttpClientError({ + reason: new HttpClientError.TransportError({ + request, + description: "Client certificates aren't supported on this runtime", + }), + }) + const init: RequestInit = Option.getOrElse(yield* Effect.serviceOption(FetchHttpClient.RequestInit), () => ({})) + return yield* HttpClient.execute(request).pipe( + Effect.provide(FetchHttpClient.layer), + Effect.provideService(FetchHttpClient.Fetch, sender.fetch), + Effect.provideService(FetchHttpClient.RequestInit, { + ...init, + ...sender.init, + // A followed redirect keeps the TLS options, so it would present the certificate to whatever host the + // server names. + redirect: init.redirect === "manual" ? "manual" : "error", + }), + ) + }), + ) + }), +) + export const requestExecutor = makeGlobalNode({ service: RequestExecutor.Service, - layer: RequestExecutor.layer.pipe(Layer.provide(withoutBunTimeout)), + layer: RequestExecutor.layer.pipe(Layer.provide(withoutBunTimeout), Layer.provide(withClientCertificate)), deps: [httpClient], }) diff --git a/packages/core/src/effect/client-tls/client-tls.bun.ts b/packages/core/src/effect/client-tls/client-tls.bun.ts new file mode 100644 index 00000000000..1ab10156444 --- /dev/null +++ b/packages/core/src/effect/client-tls/client-tls.bun.ts @@ -0,0 +1,8 @@ +import type { Sender, Tls } from "./client-tls.js" + +// Bun's fetch takes the client certificate per request. +export function sender(tls: Tls): Sender | undefined { + return { fetch: globalThis.fetch, init: { tls } } +} + +export * as ClientTls from "./client-tls.bun.js" diff --git a/packages/core/src/effect/client-tls/client-tls.node.ts b/packages/core/src/effect/client-tls/client-tls.node.ts new file mode 100644 index 00000000000..f4ea00d0345 --- /dev/null +++ b/packages/core/src/effect/client-tls/client-tls.node.ts @@ -0,0 +1,17 @@ +// The deep path keeps Vite, which runs under Bun where "undici" is a built-in, from leaving the import external. +import { Agent, fetch } from "undici/index.js" +import type { Sender, Tls } from "./client-tls.js" + +// Node's fetch only takes a client certificate through an undici dispatcher, and a dispatcher from the npm package +// only works with that package's own fetch, not Node's bundled one. One agent per certificate keeps its connections. +const agents = new Map() + +export function sender(tls: Tls): Sender | undefined { + const id = JSON.stringify([tls.cert, tls.key, tls.passphrase]) + const agent = agents.get(id) ?? new Agent({ connect: { cert: tls.cert, key: tls.key, passphrase: tls.passphrase } }) + agents.set(id, agent) + // SAFETY: undici's fetch implements the WHATWG fetch contract that FetchHttpClient and the AI SDK call. + return { fetch: fetch as unknown as typeof globalThis.fetch, init: { dispatcher: agent } } +} + +export * as ClientTls from "./client-tls.node.js" diff --git a/packages/core/src/effect/client-tls/client-tls.ts b/packages/core/src/effect/client-tls/client-tls.ts new file mode 100644 index 00000000000..ac62d4680df --- /dev/null +++ b/packages/core/src/effect/client-tls/client-tls.ts @@ -0,0 +1,12 @@ +/** PEM client certificate and private key, with the passphrase of an encrypted key. */ +export interface Tls { + readonly cert: string + readonly key: string + readonly passphrase?: string +} + +/** The `fetch` and request options that present a client certificate on this runtime. */ +export interface Sender { + readonly fetch: typeof globalThis.fetch + readonly init: Record +} diff --git a/packages/core/src/effect/client-tls/client-tls.workerd.ts b/packages/core/src/effect/client-tls/client-tls.workerd.ts new file mode 100644 index 00000000000..f1adea63fdb --- /dev/null +++ b/packages/core/src/effect/client-tls/client-tls.workerd.ts @@ -0,0 +1,8 @@ +import type { Sender, Tls } from "./client-tls.js" + +// Workers' fetch can't present a client certificate. Embedders use an mTLS certificate binding's fetch instead. +export function sender(_tls: Tls): Sender | undefined { + return undefined +} + +export * as ClientTls from "./client-tls.workerd.js" diff --git a/packages/core/src/model-resolver.ts b/packages/core/src/model-resolver.ts index 48a339fe9ec..75c622c0df2 100644 --- a/packages/core/src/model-resolver.ts +++ b/packages/core/src/model-resolver.ts @@ -260,7 +260,7 @@ const resolveCatalogModel = Effect.fn("ModelResolver.resolveCatalogModel")(funct ...runtime.options, ...mergeTransport(runtime.options, { timeout: { total: timeouts.timeout, headers: timeouts.headerTimeout, chunk: timeouts.chunkTimeout }, - http: { encoding: Provider.encoding(configured) }, + http: { encoding: Provider.encoding(configured), tls: Provider.tls(configured) }, }), }, }) @@ -315,7 +315,8 @@ const fromCatalogMedia = Effect.fn("ModelResolver.fromCatalogMedia")(function* < credential?: Credential.Value, dependencies?: Dependencies, ) { - const { resolved, module, settings } = yield* loadCatalogPackage(model, credential, dependencies) + const { resolved, configured, module, settings } = yield* loadCatalogPackage(model, credential, dependencies) + const tls = Provider.tls(configured) const runtime: unknown = yield* Effect.try({ try: () => module.model(resolved.modelID ?? resolved.id, settings), catch: (cause) => constructionError(resolved, cause), @@ -330,7 +331,12 @@ const fromCatalogMedia = Effect.fn("ModelResolver.fromCatalogMedia")(function* < }) : runtime if (!is(adapted)) return yield* unsupported(resolved) - return adapted + if (!tls || !(adapted instanceof DecisionModel || adapted instanceof ImageModel)) return adapted + // Media and decision models are plain classes with readonly fields, so copy onto the same prototype. + const copy: Runtime = Object.assign(Object.create(Object.getPrototypeOf(adapted)), adapted, { + http: { ...adapted.http, tls }, + }) + return copy }) const constructionError = (model: RuntimeInfo, cause: unknown) => @@ -504,7 +510,8 @@ export const layer = Layer.effect( limit: selected.limit, compaction: runtimeInfo.settings?.compaction, cache: runtimeInfo.settings?.cache, - transport: provider?.settings?.transport, + // The WebSocket transport can't present a client certificate, so `tls` keeps the model on HTTP. + transport: Provider.tls(provider?.settings ?? {}) ? "http" : provider?.settings?.transport, chunkTimeout: Provider.timeout(provider?.settings?.chunkTimeout), } }) diff --git a/packages/core/src/provider.ts b/packages/core/src/provider.ts index 6ae06181e5a..fec21c9c463 100644 --- a/packages/core/src/provider.ts +++ b/packages/core/src/provider.ts @@ -270,6 +270,14 @@ export function encoding(settings: Readonly>) { return Option.getOrUndefined(decodeEncoding(settings.encoding)) } +const decodeTls = Schema.decodeUnknownOption(Provider.Tls) + +/** Client certificate from provider settings. An empty `cert` or `key`, such as a missing `{file:}`, leaves it unset. */ +export function tls(settings: Readonly>) { + const value = Option.getOrUndefined(decodeTls(settings.tls)) + return value?.cert && value.key ? value : undefined +} + export const Request = Provider.Request export type Request = Provider.Request diff --git a/packages/protocol/openapi.json b/packages/protocol/openapi.json index ea2002a49b6..61d2670118d 100644 --- a/packages/protocol/openapi.json +++ b/packages/protocol/openapi.json @@ -17165,6 +17165,9 @@ }, "encoding": { "$ref": "#/components/schemas/Provider.Encoding" + }, + "tls": { + "$ref": "#/components/schemas/Provider.Tls" } }, "allOf": [ @@ -22017,6 +22020,9 @@ }, "encoding": { "$ref": "#/components/schemas/Provider.Encoding" + }, + "tls": { + "$ref": "#/components/schemas/Provider.Tls" } }, "allOf": [ @@ -22026,6 +22032,24 @@ } ] }, + "Provider.Tls": { + "type": "object", + "properties": { + "cert": { + "type": "string", + "description": "PEM client certificate, usually `{file:/path/to/client.pem}`" + }, + "key": { + "type": "string", + "description": "PEM private key, usually `{file:/path/to/client.key}`" + }, + "passphrase": { + "type": "string" + } + }, + "required": ["cert", "key"], + "additionalProperties": false + }, "Provider.Transport": { "type": "string", "enum": ["http", "websocket"] diff --git a/packages/schema/src/provider.ts b/packages/schema/src/provider.ts index 7248d46cb40..e5ee0c2106d 100644 --- a/packages/schema/src/provider.ts +++ b/packages/schema/src/provider.ts @@ -79,6 +79,14 @@ export type Encoding = typeof Encoding.Type const Timeout = Schema.Union([Schema.Finite, Schema.Literal(false)]).pipe(optional) +/** Client certificate for gateways that require mutual TLS. Values are PEM text; use `{file:...}` to read a file. */ +export const Tls = Schema.Struct({ + cert: Schema.String.annotate({ description: "PEM client certificate, usually `{file:/path/to/client.pem}`" }), + key: Schema.String.annotate({ description: "PEM private key, usually `{file:/path/to/client.key}`" }), + passphrase: Schema.String.pipe(optional).annotate({ description: "Passphrase for an encrypted private key" }), +}).annotate({ identifier: "Provider.Tls" }) +export type Tls = typeof Tls.Type + // The named fields are the settings OpenCode reads itself; every other key is a provider option for the provider package. export const Settings = Schema.StructWithRest( Schema.Struct({ @@ -89,6 +97,7 @@ export const Settings = Schema.StructWithRest( cache: Cache.pipe(optional), transport: Transport.pipe(optional), encoding: Encoding.pipe(optional), + tls: Tls.pipe(optional), }), [Schema.Record(Schema.String, Schema.Any)], ).annotate({ identifier: "Provider.Settings" }) diff --git a/services/site/src/docs/content/network.mdx b/services/site/src/docs/content/network.mdx index ab952dd25f2..202cf616a8d 100644 --- a/services/site/src/docs/content/network.mdx +++ b/services/site/src/docs/content/network.mdx @@ -1,6 +1,6 @@ --- title: Network -description: Configure proxies and custom certificate authorities. +description: Configure proxies, custom certificate authorities and client certificates. --- Set the standard proxy variables and exclude loopback addresses. OpenCode uses local HTTP connections between the CLI and @@ -92,6 +92,38 @@ Fix it in one of two ways: - Export the inspection certificate authority as a PEM file and trust it with `NODE_EXTRA_CA_CERTS`, as shown in [Certificates](#certificates). +## Client certificates + +Set `settings.tls` on a provider whose gateway requires mutual TLS. Its model requests present the certificate, and the +TLS handshake only sends it to servers that ask for one. + +```jsonc title="opencode.jsonc" +{ + "providers": { + "company": { + "package": "@opencode/ai/providers/openai-compatible", + "settings": { + "baseURL": "https://llm.company.example/v1", + "tls": { + "cert": "{file:/etc/company/client.pem}", + "key": "{file:/etc/company/client.key}", + "passphrase": "{env:CLIENT_KEY_PASSPHRASE}", + }, + }, + }, + }, +} +``` + +- `cert` and `key` are PEM text. Use `{file:...}` to read them from files. A file that can't be read leaves `tls` unset. +- `passphrase` is only needed for an encrypted key. +- Works on the Bun and Node builds. A server on Cloudflare Workers can't present a client certificate through `fetch`. +- Requests with a client certificate don't follow redirects, so the certificate isn't presented to another host. + +Every model request of that provider presents the certificate: chat, compaction, image and decision models. A provider +with `tls` uses HTTP instead of WebSockets. Tools such as webfetch, remote MCP servers and plugin installs don't present +it. + ## Foreground `--standalone` and `serve` use the environment of their own process. `opencode service set env` does not configure these