client-certificate-auth 2.1.2 → 2.2.0

package/README.md

@@ -191,8 +191,9 @@ Returns Express middleware.
 | Name | Type | Description |
 |------|------|-------------|
 | `callback` | `(cert, req?) => boolean \| PromiseLike<boolean>` | Receives the client certificate and request, returns `true` to allow access |
-| `options.certificateSource` | `string` | Use a preset for a known proxy: `'aws-alb'`, `'envoy'`, `'cloudflare'`, `'traefik'` |
+| `options.certificateSource` | `string` | Use a preset for a known proxy: `'aws-alb'`, `'aws-alb-verify'`, `'azure-app-service'`, `'cloudflare'`, `'cloudflare-rfc9440'`, `'envoy'`, `'traefik'` |
 | `options.certificateHeader` | `string` | Custom header name to read certificate from |
+| `options.chainHeader` | `string` | Second header carrying the certificate chain alongside the leaf (RFC 9440 style) |
 | `options.headerEncoding` | `string` | Encoding format: `'url-pem'`, `'url-pem-aws'`, `'xfcc'`, `'base64-der'`, `'rfc9440'` |
 | `options.fallbackToSocket` | `boolean` | If header extraction fails, try `socket.getPeerCertificate()` (default: `false`) |
 | `options.includeChain` | `boolean` | If `true`, include full certificate chain via `cert.issuerCertificate` (default: `false`) |
@@ -353,6 +354,8 @@ app.use(clientCertificateAuth((cert) => {
 
 When `includeChain: true`, the certificate object includes `issuerCertificate` linking to the issuer's certificate (and so on up the chain). This works consistently for both socket-based and header-based extraction.
 
+For header-based extraction the first certificate in the header is the leaf. If it is empty or unparseable the header is rejected with `header_missing_or_malformed` rather than promoting the next certificate into the leaf position. See [Reverse Proxy Setup](https://tgies.github.io/client-certificate-auth/guide/reverse-proxy#chains-in-a-single-header) for the per-encoding details.
+
 ### User Login
 
 Client certificates provide cryptographically-verified identity, making them ideal for user authentication. Map certificate fields to user accounts in your database:
@@ -413,21 +416,36 @@ When your application runs behind a TLS-terminating reverse proxy, the client ce
 For common proxies, use the `certificateSource` option:
 
 ```javascript
-// AWS Application Load Balancer
+// AWS Application Load Balancer (mTLS passthrough)
 app.use(clientCertificateAuth(checkAuth, {
   certificateSource: 'aws-alb'
 }));
 
+// AWS Application Load Balancer (mTLS verify mode)
+app.use(clientCertificateAuth(checkAuth, {
+  certificateSource: 'aws-alb-verify'
+}));
+
+// Azure App Service
+app.use(clientCertificateAuth(checkAuth, {
+  certificateSource: 'azure-app-service'
+}));
+
 // Envoy / Istio
 app.use(clientCertificateAuth(checkAuth, {
   certificateSource: 'envoy'
 }));
 
-// Cloudflare
+// Cloudflare (legacy Cf-Client-Cert-Der-Base64 header)
 app.use(clientCertificateAuth(checkAuth, {
   certificateSource: 'cloudflare'
 }));
 
+// Cloudflare (RFC 9440 Client-Cert / Client-Cert-Chain headers, March 2026+)
+app.use(clientCertificateAuth(checkAuth, {
+  certificateSource: 'cloudflare-rfc9440'
+}));
+
 // Traefik
 app.use(clientCertificateAuth(checkAuth, {
   certificateSource: 'traefik'
@@ -436,16 +454,21 @@ app.use(clientCertificateAuth(checkAuth, {
 
 ### Preset Details
 
-| Preset | Header | Encoding |
-|--------|--------|----------|
+| Preset | Header(s) | Encoding |
+|--------|-----------|----------|
 | `aws-alb` | `X-Amzn-Mtls-Clientcert` | URL-encoded PEM (AWS variant) |
-| `envoy` | `X-Forwarded-Client-Cert` | XFCC structured format |
+| `aws-alb-verify` | `X-Amzn-Mtls-Clientcert-Leaf` | URL-encoded PEM (AWS variant) |
+| `azure-app-service` | `X-ARR-ClientCert` | Base64-encoded DER |
 | `cloudflare` | `Cf-Client-Cert-Der-Base64` | Base64-encoded DER |
+| `cloudflare-rfc9440` | `Client-Cert` + `Client-Cert-Chain` | RFC 9440 |
+| `envoy` | `X-Forwarded-Client-Cert` | XFCC structured format |
 | `traefik` | `X-Forwarded-Tls-Client-Cert` | Base64-encoded DER \* |
 
-> \* **Traefik note:** The `traefik` preset targets Traefik v3's `PassTLSClientCert` middleware with `pem: true`. Despite Traefik's docs describing this as "PEM format", the wire format is the base64 body without PEM headers — equivalent to base64-encoded DER. Behavior may differ in Traefik v2.
+> ⚠️ **Passthrough presets do not validate the certificate.** ALB mTLS passthrough mode (`aws-alb`) and Azure App Service (`azure-app-service`) forward whatever certificate the client presented during the handshake, without checking it against a trust store. The middleware parses the certificate, but your callback is responsible for trust verification: matching the issuer against an expected CA, checking the validity window, and checking revocation if applicable. A callback that only checks `cert.subject.CN` (including the `allowCN` helper) will accept any well-formed certificate a client presents. To rely on proxy-side validation instead, use ALB verify mode (`aws-alb-verify`), which validates against a configured trust store, or pin the certificate with `allowFingerprints`.
 
-> **Cloudflare note:** Cloudflare also provides certificates via the `CF-Client-Cert-PEM` header (URL-encoded PEM). If you use that header instead, configure manually with `certificateHeader: 'CF-Client-Cert-PEM'` and `headerEncoding: 'url-pem'`.
+> \* **Traefik note:** The `traefik` preset targets Traefik v3's `PassTLSClientCert` middleware with `pem: true`. Despite Traefik's docs describing this as "PEM format", the wire format is the base64 body without PEM headers, equivalent to base64-encoded DER. This applies to Traefik v2.9.4 and later and all of v3; Traefik 2.8 through 2.9.1 URL-escaped the value, which this preset does not decode.
+
+> **Cloudflare note:** Cloudflare also provides certificates via the `CF-Client-Cert-PEM` header (URL-encoded PEM). If you use that header instead, configure manually with `certificateHeader: 'CF-Client-Cert-PEM'` and `headerEncoding: 'url-pem'`. For the RFC 9440 forwarding feature (March 2026 and later), use the `cloudflare-rfc9440` preset, which pairs the `Client-Cert` header with `Client-Cert-Chain` via the `chainHeader` option.
 
 ### Custom Headers
 
@@ -458,9 +481,9 @@ app.use(clientCertificateAuth(checkAuth, {
   headerEncoding: 'url-pem'
 }));
 
-// Google Cloud Load Balancer (RFC 9440)
+// Google Cloud Load Balancer (custom header populated from {client_cert_leaf}, RFC 9440)
 app.use(clientCertificateAuth(checkAuth, {
-  certificateHeader: 'X-SSL-Whatever-You-Use',
+  certificateHeader: 'X-Client-Cert-Leaf',
   headerEncoding: 'rfc9440'
 }));
 
@@ -475,11 +498,13 @@ app.use(clientCertificateAuth(checkAuth, {
 
 | Encoding | Description | Used By |
 |----------|-------------|---------|
-| `url-pem` | URL-encoded PEM certificate | nginx, HAProxy |
+| `url-pem` | URL-encoded PEM certificate | nginx (`$ssl_client_escaped_cert`) |
 | `url-pem-aws` | URL-encoded PEM (AWS variant, `+` as safe char) | AWS ALB |
 | `xfcc` | Envoy's structured `Key=Value;...` format | Envoy, Istio |
-| `base64-der` | Base64-encoded DER certificate | Cloudflare, Traefik |
-| `rfc9440` | RFC 9440 format: `:base64-der:` | Google Cloud LB |
+| `base64-der` | Base64-encoded DER certificate | Cloudflare, Traefik, Azure App Service, HAProxy (`ssl_c_der,base64`) |
+| `rfc9440` | RFC 9440 format: `:base64-der:` | Cloudflare (RFC 9440 forwarding), Google Cloud LB |
+
+HAProxy's native certificate forwarding (`http-request set-header ... %[ssl_c_der,base64]`) is base64 DER, so pair it with `base64-der`. HAProxy has no built-in URL-encoded-PEM output; `url-pem` from HAProxy requires a custom Lua `url_enc` converter.
 
 ### Fallback Mode
 
@@ -646,8 +671,8 @@ app.use(clientCertificateAuth(allowCN(['service-a', 'service-b'])));
 
 // Allowlist by fingerprint
 app.use(clientCertificateAuth(allowFingerprints([
-  'SHA256:AB:CD:EF:...',
-  'AB:CD:EF:...'  // SHA256: prefix optional
+  'SHA256:AB:CD:EF:...',  // matched against cert.fingerprint256
+  'AB:CD:EF:...'          // SHA-1, matched against cert.fingerprint
 ])));
 
 // Allowlist by Organization

package/lib/clientCertificateAuth.d.cts

@@ -1,6 +1,7 @@
 import type { IncomingMessage, ServerResponse } from 'http';
 import type { Socket } from 'net';
 import type { PeerCertificate, DetailedPeerCertificate } from 'tls';
+import type { ChainedPeerCertificate } from './parsers.js';
 import type {
     ClientCertificateAuthOptions as EsmOptions,
     ValidationCallback as EsmValidationCallback,
@@ -56,7 +57,7 @@ export interface ClientCertRequest extends IncomingMessage {
      * Available after successful certificate extraction.
      * Contains issuerCertificate chain if includeChain option is true.
      */
-    clientCertificate?: PeerCertificate | DetailedPeerCertificate;
+    clientCertificate?: ChainedPeerCertificate;
 }
 
 /**
@@ -88,7 +89,7 @@ export interface ClientCertificateAuthOptions {
      * @param req - The HTTP request object
      */
     onAuthenticated?: (
-        cert: PeerCertificate | DetailedPeerCertificate,
+        cert: ChainedPeerCertificate,
         req: ClientCertRequest
     ) => void | Promise<void>;
 
@@ -100,14 +101,14 @@ export interface ClientCertificateAuthOptions {
      * @param reason - Why authentication was rejected
      */
     onRejected?: (
-        cert: PeerCertificate | DetailedPeerCertificate | null,
+        cert: ChainedPeerCertificate | null,
         req: ClientCertRequest,
         reason: string
     ) => void | Promise<void>;
 }
 
 export type ValidationCallback = (
-    cert: PeerCertificate | DetailedPeerCertificate,
+    cert: ChainedPeerCertificate,
     req?: ClientCertRequest
 ) => boolean | PromiseLike<boolean>;
 

package/lib/clientCertificateAuth.d.ts

@@ -1,6 +1,7 @@
 import type { IncomingMessage, ServerResponse } from 'http';
 import type { Socket } from 'net';
 import type { PeerCertificate, DetailedPeerCertificate } from 'tls';
+import type { ChainedPeerCertificate } from './parsers.js';
 import type { CertificateSource, HeaderEncoding } from './parsers.js';
 
 export type { CertificateSource, HeaderEncoding };
@@ -54,7 +55,7 @@ export interface ClientCertRequest extends IncomingMessage {
      * Available after successful certificate extraction, before authorization callback.
      * Contains issuerCertificate chain if includeChain option is true.
      */
-    clientCertificate?: PeerCertificate | DetailedPeerCertificate;
+    clientCertificate?: ChainedPeerCertificate;
 }
 
 /**
@@ -127,7 +128,7 @@ export interface ClientCertificateAuthOptions {
      * @param req - The HTTP request object
      */
     onAuthenticated?: (
-        cert: PeerCertificate | DetailedPeerCertificate,
+        cert: ChainedPeerCertificate,
         req: ClientCertRequest
     ) => void | Promise<void>;
 
@@ -139,14 +140,14 @@ export interface ClientCertificateAuthOptions {
      * @param reason - Why authentication was rejected
      */
     onRejected?: (
-        cert: PeerCertificate | DetailedPeerCertificate | null,
+        cert: ChainedPeerCertificate | null,
         req: ClientCertRequest,
         reason: string
     ) => void | Promise<void>;
 }
 
 export type ValidationCallback = (
-    cert: PeerCertificate | DetailedPeerCertificate,
+    cert: ChainedPeerCertificate,
     req?: ClientCertRequest
 ) => boolean | PromiseLike<boolean>;
 

package/lib/clientCertificateAuth.js

@@ -34,7 +34,7 @@ function normalizeCallbackError(err) {
 }
 
 /**
- * @typedef {import('http').IncomingMessage & { secure?: boolean; socket: import('net').Socket & { authorized?: boolean; authorizationError?: Error | string; getPeerCertificate?: (detailed?: boolean) => import('tls').PeerCertificate | import('tls').DetailedPeerCertificate }; clientCertificate?: import('tls').PeerCertificate }} ClientCertRequest
+ * @typedef {import('http').IncomingMessage & { secure?: boolean; socket: import('net').Socket & { authorized?: boolean; authorizationError?: Error | string; getPeerCertificate?: (detailed?: boolean) => import('tls').PeerCertificate | import('tls').DetailedPeerCertificate }; clientCertificate?: import('./parsers.js').ChainedPeerCertificate }} ClientCertRequest
  * @typedef {import('http').ServerResponse & { redirect: (statusOrUrl: number | string, url?: string) => void }} ClientCertResponse
  * @typedef {(req: ClientCertRequest, res: ClientCertResponse, next: (err?: Error) => void) => void} Middleware
  */
@@ -64,9 +64,9 @@ function normalizeCallbackError(err) {
  * @property {string} [verifyValue] - 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.
- * @property {(cert: import('tls').PeerCertificate, req: ClientCertRequest) => void | Promise<void>} [onAuthenticated] -
+ * @property {(cert: import('./parsers.js').ChainedPeerCertificate, req: ClientCertRequest) => void | Promise<void>} [onAuthenticated] -
  *   Called when a client is successfully authenticated. Fire-and-forget.
- * @property {(cert: import('tls').PeerCertificate | null, req: ClientCertRequest, reason: string) => void | Promise<void>} [onRejected] -
+ * @property {(cert: import('./parsers.js').ChainedPeerCertificate | null, req: ClientCertRequest, reason: string) => void | Promise<void>} [onRejected] -
  *   Called when authentication is rejected. Fire-and-forget.
  */
 
@@ -78,7 +78,7 @@ function normalizeCallbackError(err) {
  * `req.socket.getPeerCertificate()` or extracted from headers) and must
  * return `true` (or a thenable resolving to `true`) for the request to proceed.
  *
- * @param {(cert: import('tls').PeerCertificate, req: ClientCertRequest) => boolean | PromiseLike<boolean>} callback
+ * @param {(cert: import('./parsers.js').ChainedPeerCertificate, req: ClientCertRequest) => boolean | PromiseLike<boolean>} callback
  *   Validation function that receives the client certificate and the request
  *   object. Returns true/false (sync) or a `PromiseLike<boolean>` (async,
  *   including native Promises and any thenable resolving to a boolean) to

package/lib/extractor.d.ts

@@ -1,7 +1,7 @@
 /**
  * @typedef {Object} ExtractionResult
  * @property {boolean} success - Whether extraction succeeded
- * @property {import('tls').PeerCertificate | null} certificate - Extracted certificate (null on failure)
+ * @property {import('./parsers.js').ChainedPeerCertificate | null} certificate - Extracted certificate (null on failure)
  * @property {string | null} reason - Rejection reason code (null on success)
  *
  * Rejection reasons:
@@ -74,7 +74,7 @@ export type ExtractionResult = {
     /**
      * - Extracted certificate (null on failure)
      */
-    certificate: import("tls").PeerCertificate | null;
+    certificate: import("./parsers.js").ChainedPeerCertificate | null;
     /**
      * - Rejection reason code (null on success)
      *

package/lib/extractor.js

@@ -56,7 +56,7 @@ export function validateExtractorOptions(options = {}) {
 /**
  * @typedef {Object} ExtractionResult
  * @property {boolean} success - Whether extraction succeeded
- * @property {import('tls').PeerCertificate | null} certificate - Extracted certificate (null on failure)
+ * @property {import('./parsers.js').ChainedPeerCertificate | null} certificate - Extracted certificate (null on failure)
  * @property {string | null} reason - Rejection reason code (null on success)
  *
  * Rejection reasons:
@@ -163,7 +163,8 @@ export function extractClientCertificate(req, options = {}) {
       const chainEncoding = headerEncoding ?? preset?.encoding;
       if (chainHeaderName && chainEncoding) {
         const chainHeaderValue = req.headers[chainHeaderName];
-        if (chainHeaderValue && !Array.isArray(chainHeaderValue)) {
+        // Only a non-empty string is parseable; anything else leaves the leaf unchained.
+        if (typeof chainHeaderValue === 'string' && chainHeaderValue) {
           const chainCerts = chainHeaderValue
             .split(',')
             .map(item => item.trim())

package/lib/parsers.d.ts

@@ -6,6 +6,14 @@
 
 import type { PeerCertificate } from 'tls';
 
+/**
+ * A certificate with an optional issuer chain. Header-extracted chains end at
+ * the topmost certificate, while Node's socket chains self-reference at the root.
+ */
+export type ChainedPeerCertificate = PeerCertificate & {
+    issuerCertificate?: ChainedPeerCertificate;
+};
+
 /**
  * Supported header encoding formats.
  */
@@ -60,26 +68,26 @@ export interface CertificateHeaderConfig {
  * Parse URL-encoded PEM certificate (nginx, HAProxy format).
  * @see https://nginx.org/en/docs/http/ngx_http_ssl_module.html#var_ssl_client_escaped_cert
  */
-export declare function parseUrlPem(headerValue: string): PeerCertificate | null;
+export declare function parseUrlPem(headerValue: string): ChainedPeerCertificate | null;
 
 /**
  * Parse URL-encoded PEM certificate with AWS ALB safe character handling.
  * @see https://docs.aws.amazon.com/elasticloadbalancing/latest/application/mutual-authentication.html
  */
-export declare function parseUrlPemAws(headerValue: string): PeerCertificate | null;
+export declare function parseUrlPemAws(headerValue: string): ChainedPeerCertificate | null;
 
 /**
  * Parse Envoy XFCC (X-Forwarded-Client-Cert) structured header format.
  * @see https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers#x-forwarded-client-cert
  */
-export declare function parseXfcc(headerValue: string): PeerCertificate | null;
+export declare function parseXfcc(headerValue: string): ChainedPeerCertificate | null;
 
 /**
  * Parse base64-encoded DER certificate (Cloudflare, Traefik format).
  * Also handles Traefik's comma-separated cert chains.
  * @see https://developers.cloudflare.com/api-shield/security/mtls/configure/
  */
-export declare function parseBase64Der(headerValue: string): PeerCertificate | null;
+export declare function parseBase64Der(headerValue: string): ChainedPeerCertificate | null;
 
 /**
  * Parse RFC 9440 format certificate (used by Google Cloud Load Balancer).
@@ -103,7 +111,7 @@ export declare function derToCertificate(der: Buffer): PeerCertificate;
 export declare function parseHeaderValue(
     headerValue: string,
     encoding: HeaderEncoding
-): PeerCertificate | null;
+): ChainedPeerCertificate | null;
 
 /**
  * Get certificate from request headers using configuration.
@@ -111,4 +119,4 @@ export declare function parseHeaderValue(
 export declare function getCertificateFromHeaders(
     headers: Record<string, string | string[] | undefined>,
     config: CertificateHeaderConfig
-): PeerCertificate | null;
+): ChainedPeerCertificate | null;

package/lib/parsers.js

@@ -11,6 +11,12 @@ import { X509Certificate } from 'node:crypto';
  * @typedef {import('tls').PeerCertificate} PeerCertificate
  */
 
+/**
+ * A certificate with an optional issuer chain. Header-extracted chains end at
+ * the topmost certificate, while Node's socket chains self-reference at the root.
+ * @typedef {PeerCertificate & { issuerCertificate?: ChainedPeerCertificate }} ChainedPeerCertificate
+ */
+
 /**
  * Preset configurations for common reverse proxies.
  * Maps preset name to { header, encoding } configuration, with optional
@@ -89,10 +95,11 @@ export const PRESETS = {
 /**
  * Parse URL-encoded PEM certificate (nginx, HAProxy format).
  * Uses standard URL encoding via $ssl_client_escaped_cert or similar.
+ * Concatenated PEM blocks are split and linked via issuerCertificate.
  * 
  * @see https://nginx.org/en/docs/http/ngx_http_ssl_module.html#var_ssl_client_escaped_cert
  * @param {string} headerValue - URL-encoded PEM certificate
- * @returns {PeerCertificate | null} Parsed certificate or null on failure
+ * @returns {ChainedPeerCertificate | null} Parsed certificate or null on failure
  */
 export function parseUrlPem(headerValue) {
     // Stryker disable next-line BlockStatement,ConditionalExpression: falsy input falls through to try-catch → same null return
@@ -102,7 +109,7 @@ export function parseUrlPem(headerValue) {
 
     try {
         const pem = decodeURIComponent(headerValue);
-        return pemToCertificate(pem);
+        return chainFromMultiBlockPem(pem);
     } catch {
         return null;
     }
@@ -138,36 +145,48 @@ function splitPemBlocks(pem) {
 
 /**
  * Parse a multi-block PEM blob into a chained PeerCertificate. Splits the
- * input into individual blocks, parses each, drops blocks that fail to
- * parse, and links the remainder via issuerCertificate.
+ * input into individual blocks and links them via issuerCertificate. The
+ * first block is the leaf and must parse; later blocks that fail to parse
+ * are dropped and the chain links past them.
  *
  * Used by parsers whose proxies forward the full chain in a single field
- * (parseUrlPemAws, parseXfcc Chain). Without explicit chain linking, calling
- * X509Certificate() on a multi-block PEM returns just the leaf with no
+ * (parseUrlPem, parseUrlPemAws, parseXfcc Chain). Without explicit chain
+ * linking, calling X509Certificate() on a multi-block PEM returns just the leaf with no
  * issuerCertificate (toLegacyObject drops the property), silently losing
  * chain information for `includeChain: true` consumers.
  *
  * @param {string} pem - Concatenated PEM blocks
- * @returns {PeerCertificate | null} Leaf cert with chain via issuerCertificate, or null if no blocks parse
+ * @returns {ChainedPeerCertificate | null} Leaf cert with chain via issuerCertificate, or null if the leaf does not parse
  */
 function chainFromMultiBlockPem(pem) {
     const pemBlocks = splitPemBlocks(pem);
-    // Stryker disable next-line BlockStatement,ConditionalExpression: short-circuit; falling through hits the next certs.length===0 check with the same null result
+    // Stryker disable next-line BlockStatement,ConditionalExpression: short-circuit; falling through hands undefined to pemToCertificate, which throws for the same null result
     if (pemBlocks.length === 0) {
         return null;
     }
 
-    const certs = pemBlocks.map(block => {
+    // Junk ahead of the leaf block means the leaf was damaged past recognition;
+    // the next block must not slide into its place. Leading whitespace is fine.
+    if (pem.slice(0, pem.indexOf(pemBlocks[0])).trim() !== '') {
+        return null;
+    }
+
+    // An unparseable leaf rejects the whole blob. Promoting the next block
+    // would authenticate the request as whichever certificate parsed first.
+    let leaf;
+    try {
+        leaf = pemToCertificate(pemBlocks[0]);
+    } catch {
+        return null;
+    }
+
+    const certs = [leaf];
+    for (const block of pemBlocks.slice(1)) {
         try {
-            return pemToCertificate(block);
+            certs.push(pemToCertificate(block));
         } catch {
-            // Equivalent mutant (undefined also filtered by .filter(Boolean)) — catch-body BlockStatement unsuppressible via Stryker comments
-            return null;
+            // Dropped; the chain links past it.
         }
-    }).filter(Boolean);
-
-    if (certs.length === 0) {
-        return null;
     }
 
     // Stryker disable next-line EqualityOperator: setting issuerCertificate = undefined on last cert is same as not setting it
@@ -186,7 +205,7 @@ function chainFromMultiBlockPem(pem) {
  *
  * @see https://docs.aws.amazon.com/elasticloadbalancing/latest/application/mutual-authentication.html
  * @param {string} headerValue - AWS ALB URL-encoded PEM certificate
- * @returns {PeerCertificate | null} Parsed certificate or null on failure
+ * @returns {ChainedPeerCertificate | null} Parsed certificate or null on failure
  */
 export function parseUrlPemAws(headerValue) {
     // Stryker disable next-line BlockStatement,ConditionalExpression: falsy input falls through to try-catch → same null return
@@ -214,7 +233,7 @@ export function parseUrlPemAws(headerValue) {
  *
  * @see https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers#x-forwarded-client-cert
  * @param {string} headerValue - XFCC formatted header value
- * @returns {PeerCertificate | null} Parsed certificate or null on failure
+ * @returns {ChainedPeerCertificate | null} Parsed certificate or null on failure
  */
 export function parseXfcc(headerValue) {
     // Stryker disable next-line BlockStatement,ConditionalExpression: falsy input falls through to try-catch → same null return
@@ -297,7 +316,7 @@ export function parseXfcc(headerValue) {
  * 
  * @see https://developers.cloudflare.com/api-shield/security/mtls/configure/
  * @param {string} headerValue - Base64-encoded DER certificate(s)
- * @returns {PeerCertificate | null} Parsed certificate or null on failure
+ * @returns {ChainedPeerCertificate | null} Parsed certificate or null on failure
  */
 export function parseBase64Der(headerValue) {
     // Stryker disable next-line BlockStatement,ConditionalExpression: falsy input falls through to try-catch → same null return
@@ -306,27 +325,25 @@ export function parseBase64Der(headerValue) {
     }
 
     // Handle comma-separated cert chains (Traefik format)
-    // Stryker disable next-line MethodExpression: .trim() no-op (base64 ignores whitespace); .filter(Boolean) redundant (empty strings throw in X509Certificate, caught below)
-    const certParts = headerValue.split(',').map(s => s.trim()).filter(Boolean);
+    // Stryker disable next-line MethodExpression: .trim() no-op (base64 ignores whitespace)
+    const certParts = headerValue.split(',').map(s => s.trim());
 
-    // Stryker disable next-line BlockStatement,ConditionalExpression: →false equivalent (empty array → zero certs → certs.length===0 catches it); →true killed by valid base64-der tests
-    if (certParts.length === 0) {
+    // An empty or unparseable leaf rejects the whole header. Promoting the next
+    // entry would authenticate the request as whichever certificate parsed first.
+    let leaf;
+    try {
+        leaf = derToCertificate(Buffer.from(certParts[0], 'base64'));
+    } catch {
         return null;
     }
 
-    // Parse all certs in the chain
-    const certs = certParts.map(base64 => {
+    const certs = [leaf];
+    for (const base64 of certParts.slice(1)) {
         try {
-            const derBuffer = Buffer.from(base64, 'base64');
-            return derToCertificate(derBuffer);
+            certs.push(derToCertificate(Buffer.from(base64, 'base64')));
         } catch {
-            // Equivalent mutant (undefined also filtered by .filter(Boolean)) — catch-body BlockStatement unsuppressible via Stryker comments
-            return null;
+            // Dropped; the chain links past it.
         }
-    }).filter(Boolean);
-
-    if (certs.length === 0) {
-        return null;
     }
 
     // Link the cert chain via issuerCertificate
@@ -400,9 +417,14 @@ export function derToCertificate(der) {
  * 
  * @param {string} headerValue - Raw header value
  * @param {'url-pem' | 'url-pem-aws' | 'xfcc' | 'base64-der' | 'rfc9440'} encoding - Encoding format
- * @returns {PeerCertificate | null} Parsed certificate or null on failure
+ * @returns {ChainedPeerCertificate | null} Parsed certificate or null on failure
  */
 export function parseHeaderValue(headerValue, encoding) {
+    // Only strings are parseable; a header name like 'constructor' resolves
+    // to a function on plain-object header maps.
+    if (typeof headerValue !== 'string') {
+        return null;
+    }
     switch (encoding) {
         // Stryker disable next-line ConditionalExpression: parseUrlPem/parseUrlPemAws are equivalent for inputs without + chars
         case 'url-pem':
@@ -428,7 +450,7 @@ export function parseHeaderValue(headerValue, encoding) {
  * @param {string} [config.certificateSource] - Preset name (aws-alb, envoy, cloudflare, traefik)
  * @param {string} [config.certificateHeader] - Custom header name (overrides preset)
  * @param {string} [config.headerEncoding] - Encoding format (required if certificateHeader is set)
- * @returns {PeerCertificate | null} Parsed certificate or null if not found/invalid
+ * @returns {ChainedPeerCertificate | null} Parsed certificate or null if not found/invalid
  */
 export function getCertificateFromHeaders(headers, config) {
     let headerName;
@@ -468,6 +490,7 @@ export function getCertificateFromHeaders(headers, config) {
 
     // Node.js HTTP consolidates duplicate headers into string[].
     // Parsers expect a single string; reject arrays to fail safely.
+    // Stryker disable next-line ConditionalExpression,BlockStatement: →false/{} equivalent (parseHeaderValue rejects non-strings); →true killed by valid header extraction tests
     if (Array.isArray(headerValue)) {
         return null;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "client-certificate-auth",
-  "version": "2.1.2",
+  "version": "2.2.0",
   "description": "Express/Connect middleware for mTLS client certificate authentication with reverse proxy support (AWS ALB, Envoy, Cloudflare, Traefik)",
   "homepage": "https://github.com/tgies/client-certificate-auth",
   "bugs": {
@@ -105,7 +105,7 @@
     "@stryker-mutator/core": "^9.6.0",
     "@stryker-mutator/jest-runner": "^9.6.1",
     "@types/express": "^5.0.6",
-    "@types/node": "^25.6.0",
+    "@types/node": "^26.1.1",
     "c8": "^11.0.0",
     "eslint": "^10.2.1",
     "globals": "^17.5.0",