client-certificate-auth 2.1.3 → 2.2.0

package/README.md

@@ -354,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:

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:

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,7 +417,7 @@ 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
@@ -433,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "client-certificate-auth",
-  "version": "2.1.3",
+  "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": {