client-certificate-auth 2.1.1 → 2.1.3

package/README.md

@@ -1,6 +1,8 @@
 # client-certificate-auth
 
-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.
+Comprehensive zero-dependency 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.
+
+This library lets you make additional auth decisions based on specific information within a client certificate after the client certificate is accepted at the socket level (i.e. by Node's `https` or a reverse proxy). This allows for fine-grained access control on top of the all-or-nothing allow/deny access control afforded by basic mTLS.
 
 [![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)
@@ -15,9 +17,13 @@ Comprehensive toolkit for client SSL certificate authentication (mTLS) in Node.j
 
 **Fanatically Tested** - 100% line/branch/function/statement coverage, plus mutation testing and E2E tests against real nginx/Envoy/Traefik containers. ~6,207 lines of test code for ~937 lines of source (measured by [cloc](https://github.com/AlDanial/cloc)).
 
+**Maintained since 2013** - Originally released for Node 0.10!
+
+**Zero runtime dependencies** - Entirely self-contained, with straightforward, readable logic, no behavior hidden inside dependencies, no bloat, and no transitive-dependency security headaches.
+
 ## What Is This?
 
-This library authenticates HTTP clients by their TLS client certificates, a scheme usually called mutual TLS (mTLS). Instead of presenting a password, API key, or bearer token, the client presents an X.509 certificate during the TLS handshake and proves possession of its private key; the server checks that the certificate was issued by a CA it trusts. The certificate is the credential.
+This library authenticates HTTP clients by their TLS client certificates, a scheme usually called mutual TLS (mTLS). Instead of presenting a password, API key, or bearer token, the client presents an X.509 certificate during the TLS handshake and proves possession of its private key; the server checks that the certificate was issued by a CA it trusts. The certificate is the credential. The certificate signature verification is typically accomplished at the socket level by Node's `https` or a reverse proxy; this library's purpose is to allow you to easily inspect the properties of a verified certificate and make fine-grained access control decisions based on them.
 
 Typical uses:
 
@@ -185,8 +191,9 @@ Returns Express middleware.
 | Name | Type | Description |
 |------|------|-------------|
 | `callback` | `(cert, req?) => boolean \| PromiseLike<boolean>` | Receives the client certificate and request, returns `true` to allow access |
-| `options.certificateSource` | `string` | Use a preset for a known proxy: `'aws-alb'`, `'envoy'`, `'cloudflare'`, `'traefik'` |
+| `options.certificateSource` | `string` | Use a preset for a known proxy: `'aws-alb'`, `'aws-alb-verify'`, `'azure-app-service'`, `'cloudflare'`, `'cloudflare-rfc9440'`, `'envoy'`, `'traefik'` |
 | `options.certificateHeader` | `string` | Custom header name to read certificate from |
+| `options.chainHeader` | `string` | Second header carrying the certificate chain alongside the leaf (RFC 9440 style) |
 | `options.headerEncoding` | `string` | Encoding format: `'url-pem'`, `'url-pem-aws'`, `'xfcc'`, `'base64-der'`, `'rfc9440'` |
 | `options.fallbackToSocket` | `boolean` | If header extraction fails, try `socket.getPeerCertificate()` (default: `false`) |
 | `options.includeChain` | `boolean` | If `true`, include full certificate chain via `cert.issuerCertificate` (default: `false`) |
@@ -407,21 +414,36 @@ When your application runs behind a TLS-terminating reverse proxy, the client ce
 For common proxies, use the `certificateSource` option:
 
 ```javascript
-// AWS Application Load Balancer
+// AWS Application Load Balancer (mTLS passthrough)
 app.use(clientCertificateAuth(checkAuth, {
   certificateSource: 'aws-alb'
 }));
 
+// AWS Application Load Balancer (mTLS verify mode)
+app.use(clientCertificateAuth(checkAuth, {
+  certificateSource: 'aws-alb-verify'
+}));
+
+// Azure App Service
+app.use(clientCertificateAuth(checkAuth, {
+  certificateSource: 'azure-app-service'
+}));
+
 // Envoy / Istio
 app.use(clientCertificateAuth(checkAuth, {
   certificateSource: 'envoy'
 }));
 
-// Cloudflare
+// Cloudflare (legacy Cf-Client-Cert-Der-Base64 header)
 app.use(clientCertificateAuth(checkAuth, {
   certificateSource: 'cloudflare'
 }));
 
+// Cloudflare (RFC 9440 Client-Cert / Client-Cert-Chain headers, March 2026+)
+app.use(clientCertificateAuth(checkAuth, {
+  certificateSource: 'cloudflare-rfc9440'
+}));
+
 // Traefik
 app.use(clientCertificateAuth(checkAuth, {
   certificateSource: 'traefik'
@@ -430,16 +452,21 @@ app.use(clientCertificateAuth(checkAuth, {
 
 ### Preset Details
 
-| Preset | Header | Encoding |
-|--------|--------|----------|
+| Preset | Header(s) | Encoding |
+|--------|-----------|----------|
 | `aws-alb` | `X-Amzn-Mtls-Clientcert` | URL-encoded PEM (AWS variant) |
-| `envoy` | `X-Forwarded-Client-Cert` | XFCC structured format |
+| `aws-alb-verify` | `X-Amzn-Mtls-Clientcert-Leaf` | URL-encoded PEM (AWS variant) |
+| `azure-app-service` | `X-ARR-ClientCert` | Base64-encoded DER |
 | `cloudflare` | `Cf-Client-Cert-Der-Base64` | Base64-encoded DER |
+| `cloudflare-rfc9440` | `Client-Cert` + `Client-Cert-Chain` | RFC 9440 |
+| `envoy` | `X-Forwarded-Client-Cert` | XFCC structured format |
 | `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.
+> ⚠️ **Passthrough presets do not validate the certificate.** ALB mTLS passthrough mode (`aws-alb`) and Azure App Service (`azure-app-service`) forward whatever certificate the client presented during the handshake, without checking it against a trust store. The middleware parses the certificate, but your callback is responsible for trust verification: matching the issuer against an expected CA, checking the validity window, and checking revocation if applicable. A callback that only checks `cert.subject.CN` (including the `allowCN` helper) will accept any well-formed certificate a client presents. To rely on proxy-side validation instead, use ALB verify mode (`aws-alb-verify`), which validates against a configured trust store, or pin the certificate with `allowFingerprints`.
+
+> \* **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. This applies to Traefik v2.9.4 and later and all of v3; Traefik 2.8 through 2.9.1 URL-escaped the value, which this preset does not decode.
 
-> **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'`.
+> **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'`. For the RFC 9440 forwarding feature (March 2026 and later), use the `cloudflare-rfc9440` preset, which pairs the `Client-Cert` header with `Client-Cert-Chain` via the `chainHeader` option.
 
 ### Custom Headers
 
@@ -452,9 +479,9 @@ app.use(clientCertificateAuth(checkAuth, {
   headerEncoding: 'url-pem'
 }));
 
-// Google Cloud Load Balancer (RFC 9440)
+// Google Cloud Load Balancer (custom header populated from {client_cert_leaf}, RFC 9440)
 app.use(clientCertificateAuth(checkAuth, {
-  certificateHeader: 'X-SSL-Whatever-You-Use',
+  certificateHeader: 'X-Client-Cert-Leaf',
   headerEncoding: 'rfc9440'
 }));
 
@@ -469,11 +496,13 @@ app.use(clientCertificateAuth(checkAuth, {
 
 | Encoding | Description | Used By |
 |----------|-------------|---------|
-| `url-pem` | URL-encoded PEM certificate | nginx, HAProxy |
+| `url-pem` | URL-encoded PEM certificate | nginx (`$ssl_client_escaped_cert`) |
 | `url-pem-aws` | URL-encoded PEM (AWS variant, `+` as safe char) | AWS ALB |
 | `xfcc` | Envoy's structured `Key=Value;...` format | Envoy, Istio |
-| `base64-der` | Base64-encoded DER certificate | Cloudflare, Traefik |
-| `rfc9440` | RFC 9440 format: `:base64-der:` | Google Cloud LB |
+| `base64-der` | Base64-encoded DER certificate | Cloudflare, Traefik, Azure App Service, HAProxy (`ssl_c_der,base64`) |
+| `rfc9440` | RFC 9440 format: `:base64-der:` | Cloudflare (RFC 9440 forwarding), Google Cloud LB |
+
+HAProxy's native certificate forwarding (`http-request set-header ... %[ssl_c_der,base64]`) is base64 DER, so pair it with `base64-der`. HAProxy has no built-in URL-encoded-PEM output; `url-pem` from HAProxy requires a custom Lua `url_enc` converter.
 
 ### Fallback Mode
 
@@ -640,8 +669,8 @@ app.use(clientCertificateAuth(allowCN(['service-a', 'service-b'])));
 
 // Allowlist by fingerprint
 app.use(clientCertificateAuth(allowFingerprints([
-  'SHA256:AB:CD:EF:...',
-  'AB:CD:EF:...'  // SHA256: prefix optional
+  'SHA256:AB:CD:EF:...',  // matched against cert.fingerprint256
+  'AB:CD:EF:...'          // SHA-1, matched against cert.fingerprint
 ])));
 
 // Allowlist by Organization

package/lib/extractor.js

@@ -163,7 +163,8 @@ export function extractClientCertificate(req, options = {}) {
       const chainEncoding = headerEncoding ?? preset?.encoding;
       if (chainHeaderName && chainEncoding) {
         const chainHeaderValue = req.headers[chainHeaderName];
-        if (chainHeaderValue && !Array.isArray(chainHeaderValue)) {
+        // Only a non-empty string is parseable; anything else leaves the leaf unchained.
+        if (typeof chainHeaderValue === 'string' && chainHeaderValue) {
           const chainCerts = chainHeaderValue
             .split(',')
             .map(item => item.trim())

package/lib/fetch.js

@@ -48,7 +48,7 @@ import { extractClientCertificate } from './extractor.js';
 export function extractClientCertificateFromRequest(request, options = {}) {
   // Web Headers normalizes to lowercase, but Map and other iterables
   // preserve casing. Normalize here for the core extractor's lowercase lookup.
-  const headers = {};
+  const headers = Object.create(null);
   for (const [name, value] of request.headers) {
     headers[name.toLowerCase()] = value;
   }

package/lib/parsers.js

@@ -403,6 +403,11 @@ export function derToCertificate(der) {
  * @returns {PeerCertificate | null} Parsed certificate or null on failure
  */
 export function parseHeaderValue(headerValue, encoding) {
+    // Only strings are parseable; a header name like 'constructor' resolves
+    // to a function on plain-object header maps.
+    if (typeof headerValue !== 'string') {
+        return null;
+    }
     switch (encoding) {
         // Stryker disable next-line ConditionalExpression: parseUrlPem/parseUrlPemAws are equivalent for inputs without + chars
         case 'url-pem':
@@ -468,6 +473,7 @@ export function getCertificateFromHeaders(headers, config) {
 
     // Node.js HTTP consolidates duplicate headers into string[].
     // Parsers expect a single string; reject arrays to fail safely.
+    // Stryker disable next-line ConditionalExpression,BlockStatement: →false/{} equivalent (parseHeaderValue rejects non-strings); →true killed by valid header extraction tests
     if (Array.isArray(headerValue)) {
         return null;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "client-certificate-auth",
-  "version": "2.1.1",
+  "version": "2.1.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": {
@@ -105,7 +105,7 @@
     "@stryker-mutator/core": "^9.6.0",
     "@stryker-mutator/jest-runner": "^9.6.1",
     "@types/express": "^5.0.6",
-    "@types/node": "^25.6.0",
+    "@types/node": "^26.1.1",
     "c8": "^11.0.0",
     "eslint": "^10.2.1",
     "globals": "^17.5.0",