client-certificate-auth 1.3.1 → 1.3.3

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,477 lines of test code for ~679 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).
+
+The certificate is parsed into a standard `tls.PeerCertificate` object and passed to your callback for authorization logic.
 
-Compatible with Express, Connect, and any Node.js HTTP server framework that uses standard `req.socket` and `req.headers`.
+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:
@@ -413,7 +422,11 @@ app.use(clientCertificateAuth(checkAuth, {
 | `aws-alb` | `X-Amzn-Mtls-Clientcert` | URL-encoded PEM (AWS variant) |
 | `envoy` | `X-Forwarded-Client-Cert` | XFCC structured format |
 | `cloudflare` | `Cf-Client-Cert-Der-Base64` | Base64-encoded DER |
-| `traefik` | `X-Forwarded-Tls-Client-Cert` | Base64-encoded DER |
+| `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.
+
+> **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'`.
 
 ### Custom Headers
 
@@ -604,7 +617,7 @@ import clientCertificateAuth from 'client-certificate-auth';
 import { allowCN, allowFingerprints, allowIssuer, allOf, anyOf } from 'client-certificate-auth/helpers';
 ```
 
-> **Note:** The `/helpers` and `/parsers` subpath exports are ESM-only. They are not available via `require()`. Use the main CJS entry point with `require('client-certificate-auth').load()` for full features in CommonJS.
+> **Note:** In CommonJS, the `/helpers`, `/parsers`, and `/extractor` subpath exports provide a `load()` function for async access. See the [CommonJS](#commonjs) section for details.
 
 ### Basic Helpers
 
@@ -762,13 +775,24 @@ The `load()` function dynamically imports the ESM module and caches it. Subseque
 | `verifyHeader` / `verifyValue` | No | Yes |
 | `fallbackToSocket` | No | Yes |
 
-The `/helpers` and `/parsers` subpath exports are ESM-only and cannot be loaded via `require()`. If you need helpers in a CJS project, use dynamic `import()`:
+### Subpath Exports in CJS
+
+The `/helpers`, `/parsers`, and `/extractor` subpath exports each provide a `load()` function for async access in CommonJS. The individual functions are not synchronously available via `require()`.
 
 ```javascript
-async function setup() {
-  const { allowCN, allOf, allowIssuer } = await import('client-certificate-auth/helpers');
-  // ...
-}
+// Helpers
+const { load } = require('client-certificate-auth/helpers');
+const { allowCN, allOf, allowIssuer } = await load();
+
+// Extractor
+const { load: loadExtractor } = require('client-certificate-auth/extractor');
+const { extractClientCertificate } = await loadExtractor();
+```
+
+Alternatively, you can use dynamic `import()`:
+
+```javascript
+const { allowCN } = await import('client-certificate-auth/helpers');
 ```
 
 ## Testing
@@ -886,7 +910,31 @@ const clientCertificateAuth = await require('client-certificate-auth').load();
 
 The sync CJS wrapper does not support reverse proxy options (`certificateSource`, `certificateHeader`, etc.). Passing these options will throw a descriptive error. Use `load()` to access the full ESM module from CJS code. See the [CommonJS](#commonjs) section for details.
 
-The `/helpers` and `/parsers` subpath exports are ESM-only. In CJS, use dynamic `import()` to access them.
+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
 

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

@@ -46,7 +46,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/helpers.js

@@ -85,6 +85,7 @@ export function allowFingerprints(fingerprints) {
  */
 export function allowIssuer(match) {
     const entries = Object.entries(match);
+    if (entries.length === 0) {return () => false;}
     return (cert) => {
         if (!cert.issuer) {return false;}
         return entries.every(([key, value]) => toArray(cert.issuer[key]).includes(value));
@@ -103,6 +104,7 @@ export function allowIssuer(match) {
  */
 export function allowSubject(match) {
     const entries = Object.entries(match);
+    if (entries.length === 0) {return () => false;}
     return (cert) => {
         if (!cert.subject) {return false;}
         return entries.every(([key, value]) => toArray(cert.subject[key]).includes(value));

package/lib/parsers.js

@@ -93,7 +93,51 @@ export function parseUrlPemAws(headerValue) {
         // Must escape before decodeURIComponent or + becomes space
         const escaped = headerValue.replace(/\+/g, '%2B');
         const pem = decodeURIComponent(escaped);
-        return pemToCertificate(pem);
+
+        // 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];
     } catch {
         return null;
     }

package/package.json

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