client-certificate-auth 1.3.3 → 1.3.4

package/lib/clientCertificateAuth.js

@@ -15,11 +15,14 @@ import { extractClientCertificate } from './extractor.js';
 
 /**
  * @typedef {Object} ClientCertificateAuthOptions
- * @property {'aws-alb' | 'envoy' | 'cloudflare' | 'traefik'} [certificateSource] - Use a preset 
+ * @property {'aws-alb' | 'envoy' | 'cloudflare' | 'traefik'} [certificateSource] - Use a preset
  *   configuration for a known reverse proxy. Header-based certs are only checked if this or
- *   certificateHeader is set.
+ *   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.
  * @property {string} [certificateHeader] - Custom header name to read certificate from.
- *   Overrides preset header name if also using certificateSource.
+ *   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.
  * @property {'url-pem' | 'url-pem-aws' | 'xfcc' | 'base64-der' | 'rfc9440'} [headerEncoding] - 
  *   How to decode the header value. Required when using certificateHeader without certificateSource.
  * @property {boolean} [fallbackToSocket=false] - If header-based extraction is configured but 

package/lib/extractor.js

@@ -21,8 +21,12 @@ import { getCertificateFromHeaders } from './parsers.js';
 
 /**
  * @typedef {Object} ExtractorOptions
- * @property {'aws-alb' | 'envoy' | 'cloudflare' | 'traefik'} [certificateSource] - Preset configuration
- * @property {string} [certificateHeader] - Custom header name
+ * @property {'aws-alb' | 'envoy' | 'cloudflare' | 'traefik'} [certificateSource] - Preset
+ *   configuration. 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.
+ * @property {string} [certificateHeader] - Custom header name. Trust boundary: the proxy must
+ *   strip this header from external requests; any source that can set it is trusted to assert
+ *   client identity.
  * @property {'url-pem' | 'url-pem-aws' | 'xfcc' | 'base64-der' | 'rfc9440'} [headerEncoding] - Header encoding
  * @property {boolean} [fallbackToSocket=false] - Try socket if header extraction fails
  * @property {boolean} [includeChain=false] - Include issuerCertificate chain

package/lib/helpers.js

@@ -245,6 +245,9 @@ export function allowEmail(emails) {
  * )));
  */
 export function allOf(...callbacks) {
+    if (callbacks.length === 0) {
+        return () => false;
+    }
     return async (cert, req) => {
         const results = await Promise.all(callbacks.map((cb) => cb(cert, req)));
         return results.every((r) => r === true);

package/lib/parsers.js

@@ -60,7 +60,7 @@ export const PRESETS = {
  * @returns {PeerCertificate | null} Parsed certificate or null on failure
  */
 export function parseUrlPem(headerValue) {
-    // Stryker disable next-line BlockStatement: falsy input falls through to try-catch → same null return
+    // Stryker disable next-line BlockStatement,ConditionalExpression: falsy input falls through to try-catch → same null return
     if (!headerValue) {
         return null;
     }
@@ -73,17 +73,88 @@ export function parseUrlPem(headerValue) {
     }
 }
 
+/**
+ * Split a string of concatenated PEM CERTIFICATE blocks into an array of
+ * individual PEM strings. Uses indexOf scanning (O(N) in input length) rather
+ * than regex to avoid polynomial-time backtracking on adversarial input
+ * (e.g., many unterminated BEGIN markers).
+ *
+ * @param {string} pem - Concatenated PEM blocks
+ * @returns {string[]} Individual PEM blocks (empty array if none found)
+ */
+function splitPemBlocks(pem) {
+    // Stryker disable next-line ArrayDeclaration: sentinel-array mutant pushes a non-PEM string that pemToCertificate rejects and .filter(Boolean) drops downstream — same chain output
+    const blocks = [];
+    // Stryker disable next-line StringLiteral: empty beginMarker → indexOf returns scanPos every iteration; END markers still bracket the same blocks correctly
+    const beginMarker = '-----BEGIN CERTIFICATE-----';
+    const endMarker = '-----END CERTIFICATE-----';
+    let scanPos = 0;
+    while (true) {
+        const begin = pem.indexOf(beginMarker, scanPos);
+        if (begin === -1) {break;}
+        const end = pem.indexOf(endMarker, begin + beginMarker.length);
+        if (end === -1) {break;}
+        blocks.push(pem.substring(begin, end + endMarker.length));
+        // Stryker disable next-line ArithmeticOperator: end-endMarker.length backs up before the END marker, but the next BEGIN is past it so indexOf still advances correctly
+        scanPos = end + endMarker.length;
+    }
+    return blocks;
+}
+
+/**
+ * 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.
+ *
+ * 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
+ * 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
+ */
+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
+    if (pemBlocks.length === 0) {
+        return null;
+    }
+
+    const certs = pemBlocks.map(block => {
+        try {
+            return pemToCertificate(block);
+        } catch {
+            // Stryker disable next-line BlockStatement: empty catch returns undefined which .filter(Boolean) drops alongside null — same chain output
+            return null;
+        }
+    }).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
+    for (let i = 0; i < certs.length - 1; i++) {
+        certs[i].issuerCertificate = certs[i + 1];
+    }
+
+    return certs[0];
+}
+
 /**
  * Parse URL-encoded PEM certificate with AWS ALB safe character handling.
  * AWS ALB uses +, =, / as safe characters (not encoded), but decodeURIComponent
- * interprets + as space, so we must escape it first.
- * 
+ * interprets + as space, so we must escape it first. AWS sends the full chain
+ * as concatenated PEM blocks, which we split and link via issuerCertificate.
+ *
  * @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
  */
 export function parseUrlPemAws(headerValue) {
-    // Stryker disable next-line BlockStatement: falsy input falls through to try-catch → same null return
+    // Stryker disable next-line BlockStatement,ConditionalExpression: falsy input falls through to try-catch → same null return
     if (!headerValue) {
         return null;
     }
@@ -93,51 +164,7 @@ export function parseUrlPemAws(headerValue) {
         // Must escape before decodeURIComponent or + becomes space
         const escaped = headerValue.replace(/\+/g, '%2B');
         const pem = decodeURIComponent(escaped);
-
-        // AWS sends the full chain as concatenated PEM blocks. Split into
-        // individual blocks and parse each, then link via issuerCertificate
-        // (mirrors parseBase64Der's chain handling for Traefik/Cloudflare).
-        // Node's X509Certificate throws on multi-block input, so without this
-        // split the entire request fails when AWS forwards a real chain.
-        //
-        // Uses indexOf scanning rather than regex to avoid polynomial-time
-        // backtracking on adversarial input (e.g., many unterminated BEGIN
-        // markers). Total work is O(N) in the input length.
-        const pemBlocks = [];
-        const beginMarker = '-----BEGIN CERTIFICATE-----';
-        const endMarker = '-----END CERTIFICATE-----';
-        let scanPos = 0;
-        while (true) {
-            const begin = pem.indexOf(beginMarker, scanPos);
-            if (begin === -1) {break;}
-            const end = pem.indexOf(endMarker, begin + beginMarker.length);
-            if (end === -1) {break;}
-            pemBlocks.push(pem.substring(begin, end + endMarker.length));
-            scanPos = end + endMarker.length;
-        }
-
-        if (pemBlocks.length === 0) {
-            return null;
-        }
-
-        const certs = pemBlocks.map(block => {
-            try {
-                return pemToCertificate(block);
-            } catch {
-                return null;
-            }
-        }).filter(Boolean);
-
-        if (certs.length === 0) {
-            return null;
-        }
-
-        // Link the cert chain via issuerCertificate
-        for (let i = 0; i < certs.length - 1; i++) {
-            certs[i].issuerCertificate = certs[i + 1];
-        }
-
-        return certs[0];
+        return chainFromMultiBlockPem(pem);
     } catch {
         return null;
     }
@@ -145,14 +172,17 @@ export function parseUrlPemAws(headerValue) {
 
 /**
  * Parse Envoy XFCC (X-Forwarded-Client-Cert) structured header format.
- * Format: Key=Value;Key=Value;... where Cert or Chain contains URL-encoded PEM.
- * 
+ * Format: Key=Value;Key=Value;... where Cert (single URL-encoded PEM) or
+ * Chain (URL-encoded multi-block PEM with the full chain incl. leaf) carry
+ * the certificate. When both are present we prefer Chain because it carries
+ * more information, and link the chain via issuerCertificate.
+ *
  * @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
  */
 export function parseXfcc(headerValue) {
-    // Stryker disable next-line BlockStatement: falsy input falls through to try-catch → same null return
+    // Stryker disable next-line BlockStatement,ConditionalExpression: falsy input falls through to try-catch → same null return
     if (!headerValue) {
         return null;
     }
@@ -176,8 +206,11 @@ export function parseXfcc(headerValue) {
         }
         const firstElement = headerValue.substring(0, endOfFirst);
 
-        // Parse key=value pairs separated by semicolons
+        // Parse key=value pairs separated by semicolons. Collect Cert and
+        // Chain values; prefer Chain when both are present.
         const pairs = firstElement.split(';');
+        let certValue = null;
+        let chainValue = null;
 
         for (const pair of pairs) {
             const eqIndex = pair.indexOf('=');
@@ -191,19 +224,32 @@ export function parseXfcc(headerValue) {
             // Stryker disable next-line MethodExpression: defensive normalization, no real proxy sends whitespace
             let value = pair.substring(eqIndex + 1).trim();
 
-            // Cert or Chain contain the certificate
             if (key === 'Cert' || key === 'Chain') {
-                // Remove surrounding quotes if present
+                // Stryker disable next-line LogicalOperator,MethodExpression,StringLiteral,BlockStatement: quote-stripping mutations are equivalent given the secondary unbalanced-quote reject below and lenient PEM marker scan downstream — broken quotes either trigger reject or produce a stripped value that fails to parse, both yielding null
                 if (value.startsWith('"') && value.endsWith('"')) {
+                    // Stryker disable next-line MethodExpression: skipping the slice leaves quotes around the value; PEM marker scan still finds BEGIN/END inside them and parses the cert content correctly — equivalent for tests
                     value = value.slice(1, -1);
+                } else if (value.startsWith('"') || value.endsWith('"')) {
+                    // Unbalanced quote indicates malformed XFCC. Reject rather
+                    // than parse the cert content out of the broken wrapping.
+                    return null;
+                }
+                if (key === 'Chain') {
+                    chainValue = value;
+                } else {
+                    certValue = value;
                 }
-
-                const pem = decodeURIComponent(value);
-                return pemToCertificate(pem);
             }
         }
 
-        return null;
+        const value = chainValue ?? certValue;
+        // Stryker disable next-line BlockStatement,ConditionalExpression: short-circuit; falling through with null hands "null" string to chainFromMultiBlockPem which finds no PEM markers and returns null
+        if (!value) {
+            return null;
+        }
+
+        const pem = decodeURIComponent(value);
+        return chainFromMultiBlockPem(pem);
     } catch {
         return null;
     }
@@ -219,7 +265,7 @@ export function parseXfcc(headerValue) {
  * @returns {PeerCertificate | null} Parsed certificate or null on failure
  */
 export function parseBase64Der(headerValue) {
-    // Stryker disable next-line BlockStatement: falsy input falls through to try-catch → same null return
+    // Stryker disable next-line BlockStatement,ConditionalExpression: falsy input falls through to try-catch → same null return
     if (!headerValue) {
         return null;
     }
@@ -266,7 +312,7 @@ export function parseBase64Der(headerValue) {
  * @returns {PeerCertificate | null} Parsed certificate or null on failure
  */
 export function parseRfc9440(headerValue) {
-    // Stryker disable next-line BlockStatement: falsy input falls through to try-catch → same null return
+    // Stryker disable next-line BlockStatement,ConditionalExpression: falsy input falls through to try-catch → same null return
     if (!headerValue) {
         return null;
     }

package/package.json

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