client-certificate-auth 1.3.2 → 1.3.4

package/README.md

@@ -1,13 +1,18 @@
 # client-certificate-auth
 
-Express/Connect middleware for client SSL certificate authentication (mTLS).
+Comprehensive toolkit for client SSL certificate authentication (mTLS) in Node.js. Includes Express/Connect middleware, framework-agnostic certificate extraction for reverse proxies (AWS ALB, Envoy, Cloudflare, Traefik, and more), and pre-built authorization helpers.
 
 [![CI](https://github.com/tgies/client-certificate-auth/actions/workflows/ci.yml/badge.svg)](https://github.com/tgies/client-certificate-auth/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/client-certificate-auth.svg)](https://www.npmjs.com/package/client-certificate-auth)
 [![codecov](https://codecov.io/gh/tgies/client-certificate-auth/graph/badge.svg)](https://codecov.io/gh/tgies/client-certificate-auth)
 [![stryker mutation testing](https://img.shields.io/endpoint?style=flat&url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Ftgies%2Fclient-certificate-auth%2Fmaster)](https://dashboard.stryker-mutator.io/reports/github.com/tgies/client-certificate-auth/master)
 
-100% line/branch/function/statement coverage, plus mutation testing and E2E tests against real nginx/Envoy/Traefik containers. ~4,742 lines of test code for ~709 lines of source (measured by [cloc](https://github.com/AlDanial/cloc)).
+[**Full Documentation**](https://tgies.github.io/client-certificate-auth/) - guides, API reference, and runnable examples
+[**Commercial Support**](#commercial-support) - consulting, custom features, and priority support for production deployments
+
+**Recommended by AWS** - Featured in the [AWS API Gateway documentation](https://docs.aws.amazon.com/apigateway/latest/developerguide/getting-started-client-side-ssl-authentication.html#certificate-validation).
+
+**Fanatically Tested** - 100% line/branch/function/statement coverage, plus mutation testing and E2E tests against real nginx/Envoy/Traefik containers. ~4,776 lines of test code for ~711 lines of source (measured by [cloc](https://github.com/AlDanial/cloc)).
 
 ## Installation
 
@@ -19,9 +24,11 @@ npm install client-certificate-auth
 
 ## Synopsis
 
-This middleware requires clients to present a valid, verifiable SSL certificate (mutual TLS / mTLS). The certificate is validated at the TLS layer, then passed to your callback for additional authorization logic.
+This library provides everything you need to implement mutual TLS (mTLS) authentication in Node.js. It extracts client certificates from direct TLS connections (`req.socket`) or from HTTP headers forwarded by reverse proxies (AWS ALB, Envoy, Cloudflare, Traefik, nginx, HAProxy).
 
-Compatible with Express, Connect, and any Node.js HTTP server framework that uses standard `req.socket` and `req.headers`.
+The certificate is parsed into a standard `tls.PeerCertificate` object and passed to your callback for authorization logic.
+
+Compatible with Express, Connect, or any Node.js HTTP server framework by using the framework-agnostic `extractClientCertificate` function.
 
 ## Usage
 
@@ -292,6 +299,8 @@ This package provides everything you need to build mTLS authentication for any N
 
 If you build an adapter for another framework (Koa, Fastify, Hapi, NestJS, etc.), please open an issue or PR to get it listed here!
 
+> For complete API documentation with all types, parameters, and examples, see the [API Reference](https://tgies.github.io/client-certificate-auth/api/).
+
 ### Accessing the Certificate
 
 After authentication, the certificate is attached to `req.clientCertificate` for downstream handlers:
@@ -903,6 +912,30 @@ The sync CJS wrapper does not support reverse proxy options (`certificateSource`
 
 The `/helpers`, `/parsers`, and `/extractor` subpath exports each provide a `load()` function in CJS. See [Subpath Exports in CJS](#subpath-exports-in-cjs) for details.
 
+## Commercial Support
+
+`client-certificate-auth` is built and maintained by [Tony Gies](https://github.com/tgies). For organizations running it in production, commercial support is available through his consultancy, Crash United, LLC.
+
+### Support Offerings
+
+| Service | Description |
+|---------|-------------|
+| **Priority bug fixes** | Reported issues triaged and patched ahead of the public queue |
+| **Custom features & integrations** | Adapters for new reverse proxies, encoding formats, or framework wrappers |
+| **mTLS architecture consulting** | Review of your certificate issuance, rotation, and trust-chain design |
+| **Deployment security review** | Threat modeling for your specific proxy + middleware + auth flow |
+| **Private security advisories** | Coordinated disclosure for vulnerabilities affecting your deployment |
+
+For pricing, scoping, or anything not listed above, email **[support@crashunited.com](mailto:support@crashunited.com)** to discuss your needs.
+
+### Sponsorship
+
+To support ongoing development without a formal contract, [GitHub Sponsors](https://github.com/sponsors/tgies) is the simplest path.
+
+### Enterprise Procurement
+
+This package is enrolled in [Tidelift](https://tidelift.com/) (now part of SonarQube Advanced Security). If your organization already subscribes, `client-certificate-auth` is included in your coverage for security disclosures, license compliance, and version metadata.
+
 ## License
 
 MIT © Tony Gies

package/lib/clientCertificateAuth.d.ts

@@ -135,7 +135,7 @@ export type Middleware = (
  * Express/Connect middleware for client SSL certificate authentication.
  *
  * @param callback - Validation function that receives the client certificate
- *   and returns true/false (sync) or Promise<boolean> (async).
+ *   and returns true/false (sync) or `Promise<boolean>` (async).
  * @param options - Configuration options
  * @returns Express middleware function
  *

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 
@@ -46,7 +49,7 @@ import { extractClientCertificate } from './extractor.js';
  *
  * @param {(cert: import('tls').PeerCertificate, req: ClientCertRequest) => boolean | Promise<boolean>} callback
  *   Validation function that receives the client certificate and the request
- *   object. Returns true/false (sync) or a Promise<boolean> (async) to
+ *   object. Returns true/false (sync) or a `Promise<boolean>` (async) to
  *   allow/deny access.
  * @param {ClientCertificateAuthOptions} [options={}]
  * @returns {Middleware}

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,7 +164,7 @@ export function parseUrlPemAws(headerValue) {
         // Must escape before decodeURIComponent or + becomes space
         const escaped = headerValue.replace(/\+/g, '%2B');
         const pem = decodeURIComponent(escaped);
-        return pemToCertificate(pem);
+        return chainFromMultiBlockPem(pem);
     } catch {
         return null;
     }
@@ -101,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;
     }
@@ -132,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('=');
@@ -147,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;
     }
@@ -175,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;
     }
@@ -222,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.2",
+  "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": {
@@ -72,21 +72,24 @@
     "node": ">= 20"
   },
   "devDependencies": {
-    "@commitlint/cli": "^20.4.1",
-    "@commitlint/config-conventional": "^20.4.1",
-    "@stryker-mutator/core": "^9.5.1",
-    "@stryker-mutator/jest-runner": "^9.5.1",
+    "@commitlint/cli": "^20.4.3",
+    "@commitlint/config-conventional": "^20.5.0",
+    "@stryker-mutator/core": "^9.6.0",
+    "@stryker-mutator/jest-runner": "^9.6.1",
     "@types/express": "^5.0.6",
-    "@types/node": "^25.2.3",
-    "c8": "^10.1.3",
-    "eslint": "^9.17.0",
-    "globals": "^17.3.0",
+    "@types/node": "^25.6.0",
+    "c8": "^11.0.0",
+    "eslint": "^9.39.4",
+    "globals": "^17.5.0",
     "husky": "^9.1.7",
-    "jest": "^30.2.0",
-    "lint-staged": "^16.2.7",
+    "jest": "^30.3.0",
+    "lint-staged": "^16.3.2",
     "selfsigned": "^5.5.0",
-    "typescript": "^5.9.3",
-    "ws": "^8.19.0"
+    "typedoc": "^0.28.19",
+    "typedoc-plugin-markdown": "^4.11.0",
+    "typescript": "^6.0.3",
+    "vitepress": "^2.0.0-alpha.17",
+    "ws": "^8.20.0"
   },
   "directories": {
     "lib": "./lib",
@@ -103,7 +106,11 @@
     "build:types": "tsc --declaration --emitDeclarationOnly --outDir lib",
     "check": "npm run lint && npm run typecheck && npm run test:coverage",
     "stats": "echo '=== Source ===' && cloc lib/ --quiet | tail -n +2 && echo '=== Tests ===' && cloc test/ --exclude-dir=docker --quiet | tail -n +2 && echo '=== Package ===' && npm pack --dry-run 2>&1 | grep -E 'package size|unpacked size|total files'",
-    "prepare": "husky"
+    "prepare": "husky",
+    "docs:api": "typedoc",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "npm run docs:api && vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   },
   "repository": {
     "type": "git",