Created
September 17, 2026 03:05
-
-
Save another-guy/31e19df277bea9bfab2beb9147e95684 to your computer and use it in GitHub Desktop.
openapi-fetch-with-pfx-certificate.ts
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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