client-certificate-auth API Reference

---

client-certificate-auth API Reference / clientCertificateAuth / ClientCertificateAuthOptions

Interface: ClientCertificateAuthOptions

Defined in: clientCertificateAuth.js:43

Properties

certificateHeader?

optional certificateHeader?: string

Defined in: clientCertificateAuth.js:48

Custom header name to read certificate from. Overrides preset header name if also using certificateSource. Trust boundary: the proxy must strip this header from external requests; any source that can set it is trusted to assert client identity.

---

certificateSource?

optional certificateSource?: "aws-alb" | "aws-alb-verify" | "azure-app-service" | "cloudflare" | "cloudflare-rfc9440" | "envoy" | "traefik"

Defined in: clientCertificateAuth.js:44

Use a preset configuration for a known reverse proxy. Header-based certs are only checked if this or certificateHeader is set. Trust boundary: the proxy must strip the preset's header from external requests; any source that can set it is trusted to assert client identity.

---

chainHeader?

optional chainHeader?: string

Defined in: clientCertificateAuth.js:52

Optional second header carrying the certificate chain alongside the leaf in certificateHeader (or the preset's header). Split on commas per RFC 9440, each item parsed with the same headerEncoding, results linked via issuerCertificate. Same trust boundary as certificateHeader.

---

fallbackToSocket?

optional fallbackToSocket?: boolean

Defined in: clientCertificateAuth.js:58

If header-based extraction is configured but fails (header absent or malformed), try socket.getPeerCertificate() instead of returning 401.

---

headerEncoding?

optional headerEncoding?: "url-pem" | "url-pem-aws" | "xfcc" | "base64-der" | "rfc9440"

Defined in: clientCertificateAuth.js:56

How to decode the header value. Required when using certificateHeader without certificateSource.

---

includeChain?

optional includeChain?: boolean

Defined in: clientCertificateAuth.js:60

If true, include the full certificate chain via cert.issuerCertificate. Applies to both socket and header-based extraction.

---

onAuthenticated?

optional onAuthenticated?: (cert, req) => void | Promise<void>

Defined in: clientCertificateAuth.js:67

Called when a client is successfully authenticated. Fire-and-forget.

Parameters

cert

PeerCertificate

req

ClientCertRequest

Returns

void | Promise<void>

---

onRejected?

optional onRejected?: (cert, req, reason) => void | Promise<void>

Defined in: clientCertificateAuth.js:69

Called when authentication is rejected. Fire-and-forget.

Parameters

cert

PeerCertificate | null

req

ClientCertRequest

reason

string

Returns

void | Promise<void>

---

verifyHeader?

optional verifyHeader?: string

Defined in: clientCertificateAuth.js:62

Header name containing certificate verification status from upstream proxy (e.g., 'X-SSL-Client-Verify'). Must be used with verifyValue.

---

verifyValue?

optional verifyValue?: string

Defined in: clientCertificateAuth.js:64

Expected value indicating successful verification (e.g., 'SUCCESS'). If verifyHeader is set, requests are rejected unless the header matches this value. Comparison is exact (case-sensitive, no whitespace trimming); set this to the exact string your proxy emits.