client-certificate-auth 1.3.0 → 1.3.2

package/README.md

@@ -7,7 +7,7 @@ Express/Connect middleware for client SSL certificate authentication (mTLS).
 [![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)).
+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)).
 
 ## Installation
 
@@ -413,7 +413,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 +608,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 +766,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 +901,7 @@ 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.
 
 ## License
 

package/lib/helpers.js

@@ -9,6 +9,17 @@
  * @typedef {(cert: PeerCertificate, req?: import('http').IncomingMessage) => boolean | Promise<boolean>} ValidationCallback
  */
 
+/**
+ * Normalize a certificate DN field value to an array.
+ * Node.js returns string for single-valued and string[] for multi-valued DN attributes.
+ * @param {string | string[] | undefined} value
+ * @returns {string[]}
+ */
+function toArray(value) {
+    if (value === undefined || value === null) {return [];}
+    return Array.isArray(value) ? value : [value];
+}
+
 /**
  * Create a validation callback that allows certificates with matching Common Names.
  *
@@ -20,7 +31,7 @@
  */
 export function allowCN(names) {
     const allowed = new Set(names);
-    return (cert) => allowed.has(cert.subject?.CN);
+    return (cert) => toArray(cert.subject?.CN).some((cn) => allowed.has(cn));
 }
 
 /**
@@ -74,9 +85,10 @@ 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]) => cert.issuer[key] === value);
+        return entries.every(([key, value]) => toArray(cert.issuer[key]).includes(value));
     };
 }
 
@@ -92,9 +104,10 @@ 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]) => cert.subject[key] === value);
+        return entries.every(([key, value]) => toArray(cert.subject[key]).includes(value));
     };
 }
 
@@ -109,7 +122,7 @@ export function allowSubject(match) {
  */
 export function allowOU(ous) {
     const allowed = new Set(ous);
-    return (cert) => allowed.has(cert.subject?.OU);
+    return (cert) => toArray(cert.subject?.OU).some((ou) => allowed.has(ou));
 }
 
 /**
@@ -123,7 +136,7 @@ export function allowOU(ous) {
  */
 export function allowOrganization(orgs) {
     const allowed = new Set(orgs);
-    return (cert) => allowed.has(cert.subject?.O);
+    return (cert) => toArray(cert.subject?.O).some((o) => allowed.has(o));
 }
 
 /**
@@ -196,9 +209,9 @@ export function allowEmail(emails) {
     const allowed = new Set(emails.map((e) => e.toLowerCase()));
 
     return (cert) => {
-        // Check subject.emailAddress
+        // Check subject.emailAddress (may be string or string[] for multi-valued)
         if (cert.subject?.emailAddress) {
-            if (allowed.has(cert.subject.emailAddress.toLowerCase())) {
+            if (toArray(cert.subject.emailAddress).some((e) => allowed.has(e.toLowerCase()))) {
                 return true;
             }
         }

package/package.json

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