Skip to content

Instantly share code, notes, and snippets.

@another-guy
Created September 17, 2026 03:05
Show Gist options
  • Select an option

  • Save another-guy/31e19df277bea9bfab2beb9147e95684 to your computer and use it in GitHub Desktop.

Select an option

Save another-guy/31e19df277bea9bfab2beb9147e95684 to your computer and use it in GitHub Desktop.
openapi-fetch-with-pfx-certificate.ts
The typed way is openapi-fetch's requestInitExt option combined with an undici Agent. There are no as casts and no any, and all of the certificate settings are type-checked by undici's own types.
// mtlsClient.ts
import { readFileSync } from "node:fs";
import createClient, { type Client } from "openapi-fetch";
import { Agent, type RequestInit as UndiciRequestInit } from "undici";
import type { paths } from "./generated/api"; // your openapi-typescript output
export interface MtlsClientOptions {
baseUrl: string;
pfxPath: string;
passphrase: string;
/** PEM CA bundle, only needed if the service uses a private/internal CA. */
caPath?: string;
}
export function createMtlsClient(options: MtlsClientOptions): Client<paths> {
const dispatcher = new Agent({
connect: {
pfx: readFileSync(options.pfxPath),
passphrase: options.passphrase,
ca: options.caPath ? readFileSync(options.caPath) : undefined,
},
});
const requestInitExt = { dispatcher } satisfies Pick<UndiciRequestInit, "dispatcher">;
return createClient<paths>({
baseUrl: options.baseUrl,
requestInitExt,
});
}
Usage:
const client = createMtlsClient({
baseUrl: process.env.SERVICE_BASE_URL!,
pfxPath: process.env.CLIENT_CERT_PFX_PATH!,
passphrase: process.env.CLIENT_CERT_PASSPHRASE!,
});
const { data, error } = await client.GET("/some/path"); // still fully typed from your spec
Why this approach
- Why not a custom fetch wrapper: if you write fetch: (req) => fetch(req, { dispatcher }), TypeScript rejects it with 'dispatcher' does not exist in type 'RequestInit', so it only compiles with a cast. requestInitExt avoids that.
- What requestInitExt does: openapi-fetch passes it as the second argument in fetch(request, requestInitExt). That's the only place dispatcher can go. If you put it in the regular top-level options, it's dropped when openapi-fetch builds its Request, and the certificate is never sent.
- What satisfies adds: requestInitExt itself is typed as Record<string, unknown>. satisfies Pick<UndiciRequestInit, "dispatcher"> makes the compiler check that dispatcher really is an undici Dispatcher.
I tested it
I set up a scratch project with openapi-fetch 0.17.0, undici 8.10.2, Node 26, and TypeScript in strict mode:
- Type check: the code compiles with no errors.
- Real mTLS server: I ran a local HTTPS server that requires a client certificate, plus a PFX protected by a passphrase.
- With createMtlsClient, the request returned 200, and the server read the certificate's name (test-client).
- A plain createClient with no certificate failed with fetch failed.
Notes
- Version requirements: you need openapi-fetch 0.13 or newer for requestInitExt. Your installed undici major version should also match the one built into Node (check with node -p process.versions.undici), because Node's built-in fetch is what uses the Agent.
- Reuse the client: create it once, for example in a worker-scoped Playwright fixture, rather than on every request. That keeps connections pooled and reads the PFX file only once.
- caPath: leave it out if the service's server certificate comes from a public CA.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment