client-certificate-auth 1.1.1 → 1.1.2

package/README.md

@@ -600,12 +600,71 @@ app.use(clientCertificateAuth(checkAuth, {
 
 ## CommonJS
 
+The main entry point works with `require()` out of the box for socket-based mTLS:
+
 ```javascript
 const clientCertificateAuth = require('client-certificate-auth');
 
 app.use(clientCertificateAuth((cert) => cert.subject.CN === 'admin'));
 ```
 
+The sync CJS wrapper supports `includeChain`, `onAuthenticated`, and `onRejected` options:
+
+```javascript
+const clientCertificateAuth = require('client-certificate-auth');
+
+app.use(clientCertificateAuth(
+  (cert) => cert.subject.CN === 'admin',
+  {
+    includeChain: true,
+    onAuthenticated: (cert, req) => {
+      console.log(`Authenticated: ${cert.subject.CN}`);
+    }
+  }
+));
+```
+
+### Full Features via `load()`
+
+Reverse proxy support (header-based certificate extraction) requires async initialization. Use the `load()` function to get the full-featured ESM module:
+
+```javascript
+const { load } = require('client-certificate-auth');
+
+async function setup() {
+  const clientCertificateAuth = await load();
+
+  app.use(clientCertificateAuth(checkAuth, {
+    certificateSource: 'aws-alb'  // Now supported
+  }));
+}
+
+setup();
+```
+
+The `load()` function dynamically imports the ESM module and caches it. Subsequent calls return the cached module immediately.
+
+### CJS Limitations
+
+| Feature | `require()` (sync) | `load()` (async) |
+|---------|---------------------|-------------------|
+| Socket-based mTLS | Yes | Yes |
+| `includeChain` | Yes | Yes |
+| `onAuthenticated` / `onRejected` | Yes | Yes |
+| `certificateSource` presets | No | Yes |
+| `certificateHeader` / `headerEncoding` | No | Yes |
+| `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()`:
+
+```javascript
+async function setup() {
+  const { allowCN, allOf, allowIssuer } = await import('client-certificate-auth/helpers');
+  // ...
+}
+```
+
 ## Testing
 
 This library has comprehensive test coverage across multiple layers:
@@ -625,6 +684,104 @@ The E2E tests spin up real reverse proxies, generate fresh certificates, and ver
 - **When using header-based auth**, ensure your proxy strips certificate headers from external requests
 - Use `verifyHeader`/`verifyValue` as defense-in-depth when using header-based authentication
 
+## Troubleshooting
+
+### `DEPTH_ZERO_SELF_SIGNED_CERT` error
+
+This error occurs when the TLS layer rejects a self-signed client certificate. Set `rejectUnauthorized: false` in your HTTPS server options to let the middleware handle authorization instead of dropping the connection:
+
+```javascript
+const opts = {
+  key: fs.readFileSync('server.key'),
+  cert: fs.readFileSync('server.pem'),
+  ca: fs.readFileSync('ca.pem'),
+  requestCert: true,
+  rejectUnauthorized: false  // Required for self-signed certs
+};
+
+https.createServer(opts, app).listen(443);
+```
+
+> **Warning:** In production, prefer certificates signed by your own CA rather than self-signed certificates. If you must use self-signed certs, ensure you set `ca` to the self-signed certificate so Node.js can verify the chain.
+
+### Certificate not reaching middleware
+
+If the middleware always rejects with "socket not authorized", verify that your HTTPS server has `requestCert: true` set. Without this option, Node.js will not ask clients for a certificate during the TLS handshake:
+
+```javascript
+const opts = {
+  // ...
+  requestCert: true,           // Must be true
+  rejectUnauthorized: false
+};
+```
+
+Also confirm that the client is actually sending a certificate. Tools like `openssl s_client` can verify this:
+
+```bash
+openssl s_client -connect localhost:443 -cert client.pem -key client.key
+```
+
+### Reverse proxy headers not working
+
+When using header-based certificate extraction behind a reverse proxy:
+
+1. **Verify the proxy is setting the correct header.** Check your proxy logs or use a test endpoint to inspect incoming headers.
+
+2. **Ensure the `certificateSource` or `certificateHeader`/`headerEncoding` options match your proxy's configuration.** A mismatch will result in unparseable or missing certificate data.
+
+3. **Confirm the proxy strips certificate headers from external requests.** If external clients can set these headers directly, they can bypass authentication. See [Security Considerations](#security-considerations).
+
+4. **Consider using `verifyHeader`/`verifyValue`** for defense-in-depth, so the middleware validates that the proxy actually verified the certificate.
+
+### WebSocket authentication failing
+
+For WebSocket connections using the `ws` library with `noServer: true`, you must handle the `upgrade` event yourself and run the middleware manually. The middleware needs a response-like object and a `next` callback:
+
+```javascript
+server.on('upgrade', (req, socket, head) => {
+  const middleware = clientCertificateAuth(checkAuth);
+  const res = { writeHead: () => {}, end: () => {}, redirect: () => {} };
+
+  middleware(req, res, (err) => {
+    if (err) {
+      socket.write(`HTTP/1.1 ${err.status} ${err.message}\r\n\r\n`);
+      socket.destroy();
+      return;
+    }
+    wss.handleUpgrade(req, socket, head, (ws) => {
+      wss.emit('connection', ws, req);
+    });
+  });
+});
+```
+
+See the full [WebSocket Support](#websocket-support) section for complete examples with `ws` and Socket.IO.
+
+### ESM vs CJS import differences
+
+This package is an ES module (`"type": "module"` in package.json) with a CJS compatibility wrapper.
+
+**ESM** (recommended):
+```javascript
+import clientCertificateAuth from 'client-certificate-auth';
+import { allowCN } from 'client-certificate-auth/helpers';
+```
+
+**CJS** (sync, socket-only):
+```javascript
+const clientCertificateAuth = require('client-certificate-auth');
+```
+
+**CJS** (async, full features):
+```javascript
+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.
+
 ## License
 
 MIT © Tony Gies

package/lib/clientCertificateAuth.d.cts

@@ -45,11 +45,9 @@ export interface ClientCertRequest extends IncomingMessage {
 }
 
 /**
- * Extended response object with redirect method.
+ * Response object for client certificate auth middleware.
  */
-export interface ClientCertResponse extends ServerResponse {
-    redirect(statusOrUrl: number | string, url?: string): void;
-}
+export type ClientCertResponse = ServerResponse;
 
 /**
  * Options for the synchronous CommonJS wrapper.

package/lib/clientCertificateAuth.d.ts

@@ -43,11 +43,9 @@ export interface ClientCertRequest extends IncomingMessage {
 }
 
 /**
- * Extended response object with redirect method.
+ * Response object for client certificate auth middleware.
  */
-export interface ClientCertResponse extends ServerResponse {
-    redirect(statusOrUrl: number | string, url?: string): void;
-}
+export type ClientCertResponse = ServerResponse;
 
 export interface ClientCertificateAuthOptions {
     /**

package/lib/helpers.d.ts

@@ -4,12 +4,13 @@
  * @license MIT
  */
 
-import type { PeerCertificate } from 'tls';
+import type { PeerCertificate, DetailedPeerCertificate } from 'tls';
+import type { ClientCertRequest } from './clientCertificateAuth.js';
 
 /**
  * Validation callback for clientCertificateAuth middleware.
  */
-export type ValidationCallback = (cert: PeerCertificate, req?: import('http').IncomingMessage) => boolean | Promise<boolean>;
+export type ValidationCallback = (cert: PeerCertificate | DetailedPeerCertificate, req?: ClientCertRequest) => boolean | Promise<boolean>;
 
 /**
  * Distinguished Name fields for matching.
@@ -37,7 +38,9 @@ export declare function allowCN(names: string[]): ValidationCallback;
 
 /**
  * Create a validation callback that allows certificates with matching fingerprints.
- * Supports both full format (e.g., "SHA256:AB:CD:...") and raw hex.
+ * Supports SHA-1 fingerprints (compared against cert.fingerprint) and SHA-256
+ * fingerprints with "SHA256:" prefix (compared against cert.fingerprint256).
+ * Fingerprints without a prefix are treated as SHA-1.
  * @param fingerprints - Allowed fingerprints
  */
 export declare function allowFingerprints(fingerprints: string[]): ValidationCallback;

package/lib/helpers.js

@@ -25,25 +25,40 @@ export function allowCN(names) {
 
 /**
  * Create a validation callback that allows certificates with matching fingerprints.
- * Supports both full format (e.g., "SHA256:AB:CD:...") and raw hex.
+ * Supports SHA-1 fingerprints (compared against cert.fingerprint) and SHA-256
+ * fingerprints with "SHA256:" prefix (compared against cert.fingerprint256).
+ * Fingerprints without a prefix are treated as SHA-1.
  *
  * @param {string[]} fingerprints - Allowed fingerprints
  * @returns {ValidationCallback}
  *
  * @example
  * app.use(clientCertificateAuth(allowFingerprints([
- *   'SHA256:AB:CD:EF:...',
- *   'AB:CD:EF:...'
+ *   'SHA256:AB:CD:EF:...',  // matched against cert.fingerprint256
+ *   'AB:CD:EF:...'          // matched against cert.fingerprint (SHA-1)
  * ])));
  */
 export function allowFingerprints(fingerprints) {
-    // Normalize fingerprints: uppercase, remove SHA256: prefix if present
-    const normalize = (fp) => fp.toUpperCase().replace(/^SHA256:/i, '');
-    const allowed = new Set(fingerprints.map(normalize));
+    const sha256Allowed = new Set();
+    const sha1Allowed = new Set();
+
+    for (const fp of fingerprints) {
+        const upper = fp.toUpperCase();
+        if (upper.startsWith('SHA256:')) {
+            sha256Allowed.add(upper.slice(7));
+        } else {
+            sha1Allowed.add(upper);
+        }
+    }
 
     return (cert) => {
-        if (!cert.fingerprint) {return false;}
-        return allowed.has(normalize(cert.fingerprint));
+        if (sha1Allowed.size > 0 && cert.fingerprint) {
+            if (sha1Allowed.has(cert.fingerprint.toUpperCase())) {return true;}
+        }
+        if (sha256Allowed.size > 0 && cert.fingerprint256) {
+            if (sha256Allowed.has(cert.fingerprint256.toUpperCase())) {return true;}
+        }
+        return false;
     };
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "client-certificate-auth",
-  "version": "1.1.1",
-  "description": "Middleware for Node.js implementing client SSL certificate authentication/authorization",
+  "version": "1.1.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": {
     "url": "https://github.com/tgies/client-certificate-auth/issues"
@@ -46,12 +46,12 @@
     "@stryker-mutator/core": "^9.4.0",
     "@stryker-mutator/jest-runner": "^9.4.0",
     "@types/express": "^5.0.0",
-    "@types/node": "^22.10.2",
+    "@types/node": "^25.2.1",
     "c8": "^10.1.3",
     "eslint": "^9.17.0",
     "globals": "^17.0.0",
     "husky": "^9.1.7",
-    "jest": "^29.7.0",
+    "jest": "^30.2.0",
     "lint-staged": "^16.2.7",
     "selfsigned": "^5.4.0",
     "typescript": "^5.7.2",
@@ -86,7 +86,13 @@
     "client-certificate",
     "express",
     "connect",
-    "middleware"
+    "middleware",
+    "mutual-tls",
+    "zero-trust",
+    "pki",
+    "x509",
+    "reverse-proxy",
+    "certificate-authentication"
   ],
   "author": "Tony Gies <tony.gies@gruppe86.net> (https://github.com/tgies)",
   "license": "MIT",