client-certificate-auth 1.3.2 → 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,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

@@ -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/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.2",
+  "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",