client-certificate-auth 2.1.0 → 2.1.1

package/README.md

@@ -15,6 +15,26 @@ 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)).
 
+## 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.
+
+Typical uses:
+
+- **Service-to-service APIs**: internal microservices or partner integrations where each caller holds its own certificate rather than a shared secret.
+- **Machine and device authentication**: CI runners, IoT devices, daemons. Certificates are issued per machine and revoked per machine.
+- **Restricting sensitive endpoints**: admin interfaces, metrics, internal tooling that only known clients should reach.
+- **Certificate-based user login**: enterprise PKI and smart-card environments, where certificates map to user accounts.
+
+The TLS handshake proves who the client is; your application decides whether that client is allowed in. This library covers the part in between: it extracts the verified certificate from the request wherever your TLS terminates, parses it into a standard [`tls.PeerCertificate`](https://nodejs.org/api/tls.html#certificate-object) object, and passes it to your authorization callback. Supported certificate sources:
+
+- **TLS terminated directly in Node.js**: the certificate is read from the TLS socket.
+- **A TLS-terminating reverse proxy or load balancer** that forwards the certificate in an HTTP header: AWS ALB, Envoy/Istio, Cloudflare, Traefik, Azure App Service, nginx, HAProxy, and any proxy that implements RFC 9440 (e.g. Google Cloud Load Balancer).
+- **AWS Lambda** behind API Gateway mTLS, via `client-certificate-auth/lambda`.
+- **Web-standard `Request` runtimes** (Hono, Next.js, SvelteKit, Cloudflare Workers, Bun, Deno), via `client-certificate-auth/fetch`.
+
+Express and Connect get drop-in middleware. Other frameworks use the same extraction logic through `extractClientCertificate()`. Pre-built authorization helpers cover the common policies (allowlist by CN, fingerprint, issuer, OU, SAN, and more).
+
 ## Installation
 
 ```bash
@@ -23,14 +43,6 @@ npm install client-certificate-auth
 
 **Requirements:** Node.js >= 20
 
-## Synopsis
-
-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, or any Node.js HTTP server framework by using the framework-agnostic `extractClientCertificate` function.
-
 ## Usage
 
 ### Basic Setup

package/lib/clientCertificateAuth.cjs

@@ -32,6 +32,19 @@ function isThenable(value) {
         && typeof value.then === 'function';
 }
 
+/**
+ * Wrap primitive values thrown or rejected by the validation callback in an
+ * Error so `.message` and `.status` access is safe; objects pass through.
+ * @param {unknown} err
+ * @returns {any}
+ */
+function normalizeCallbackError(err) {
+    if (err !== null && (typeof err === 'object' || typeof err === 'function')) {
+        return err;
+    }
+    return new Error(err === null || err === undefined ? '' : String(err));
+}
+
 /**
  * Options not supported by the sync CJS wrapper.
  * These require the ESM module's async header parsing.
@@ -145,7 +158,8 @@ function clientCertificateAuth(callback, options = {}) {
         try {
             const result = callback(cert, req);
             if (isThenable(result)) {
-                Promise.resolve(result).then(doneAuthorizing).catch((err) => {
+                Promise.resolve(result).then(doneAuthorizing).catch((rejection) => {
+                    const err = normalizeCallbackError(rejection);
                     safeCallHook(onRejected, cert, req, err.message || 'callback_threw');
                     if (err.status === undefined) {
                         err.status = 401;
@@ -155,7 +169,8 @@ function clientCertificateAuth(callback, options = {}) {
             } else {
                 doneAuthorizing(result);
             }
-        } catch (err) {
+        } catch (thrown) {
+            const err = normalizeCallbackError(thrown);
             safeCallHook(onRejected, cert, req, err.message || 'callback_threw');
             if (err.status === undefined) {
                 err.status = 401;

package/lib/clientCertificateAuth.js

@@ -20,6 +20,19 @@ function isThenable(value) {
     && typeof /** @type {{then?: unknown}} */ (value).then === 'function';
 }
 
+/**
+ * Wrap primitive values thrown or rejected by the validation callback in an
+ * Error so `.message` and `.status` access is safe; objects pass through.
+ * @param {unknown} err
+ * @returns {any}
+ */
+function normalizeCallbackError(err) {
+  if (err !== null && (typeof err === 'object' || typeof err === 'function')) {
+    return err;
+  }
+  return new Error(err === null || err === undefined ? '' : String(err));
+}
+
 /**
  * @typedef {import('http').IncomingMessage & { secure?: boolean; socket: import('net').Socket & { authorized?: boolean; authorizationError?: Error | string; getPeerCertificate?: (detailed?: boolean) => import('tls').PeerCertificate | import('tls').DetailedPeerCertificate }; clientCertificate?: import('tls').PeerCertificate }} ClientCertRequest
  * @typedef {import('http').ServerResponse & { redirect: (statusOrUrl: number | string, url?: string) => void }} ClientCertResponse
@@ -195,7 +208,8 @@ export default function clientCertificateAuth(callback, options = {}) {
     try {
       const callbackResult = callback(cert, req);
       if (isThenable(callbackResult)) {
-        Promise.resolve(callbackResult).then(doneAuthorizing).catch((err) => {
+        Promise.resolve(callbackResult).then(doneAuthorizing).catch((rejection) => {
+          const err = normalizeCallbackError(rejection);
           safeCallHook(onRejected, cert, req, err.message || 'callback_threw');
           if (err.status === undefined) {
             err.status = 401;
@@ -205,7 +219,8 @@ export default function clientCertificateAuth(callback, options = {}) {
       } else {
         doneAuthorizing(callbackResult);
       }
-    } catch (err) {
+    } catch (thrown) {
+      const err = normalizeCallbackError(thrown);
       safeCallHook(onRejected, cert, req, err.message || 'callback_threw');
       if (err.status === undefined) {
         err.status = 401;

package/lib/fetch.js

@@ -53,7 +53,6 @@ export function extractClientCertificateFromRequest(request, options = {}) {
     headers[name.toLowerCase()] = value;
   }
 
-  // Stryker disable next-line ObjectLiteral: destructure-discard strips fallbackToSocket
   const { fallbackToSocket: _ignored, ...rest } = options;
 
   return extractClientCertificate({ headers }, rest);

package/lib/parsers.js

@@ -161,7 +161,7 @@ function chainFromMultiBlockPem(pem) {
         try {
             return pemToCertificate(block);
         } catch {
-            // Stryker disable next-line BlockStatement: empty catch returns undefined which .filter(Boolean) drops alongside null — same chain output
+            // Equivalent mutant (undefined also filtered by .filter(Boolean)) — catch-body BlockStatement unsuppressible via Stryker comments
             return null;
         }
     }).filter(Boolean);
@@ -357,7 +357,7 @@ export function parseRfc9440(headerValue) {
         let base64 = headerValue;
         // Stryker disable next-line BlockStatement,ConditionalExpression,StringLiteral,LogicalOperator,MethodExpression: colon-stripping is defensive; all valid RFC 9440 inputs use :base64: format, so base64 decoder ignores colons either way
         if (base64.startsWith(':') && base64.endsWith(':')) {
-            // Stryker disable next-line BlockStatement,MethodExpression: removing or no-oping the assignment is equivalent — base64 decoder ignores colons
+            // Stryker disable next-line MethodExpression: no-oping the assignment is equivalent — base64 decoder ignores colons
             base64 = base64.slice(1, -1);
         }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "client-certificate-auth",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "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": {
@@ -99,8 +99,8 @@
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
-    "@commitlint/cli": "^20.4.3",
-    "@commitlint/config-conventional": "^20.5.0",
+    "@commitlint/cli": "^21.0.0",
+    "@commitlint/config-conventional": "^21.0.0",
     "@eslint/js": "^10.0.1",
     "@stryker-mutator/core": "^9.6.0",
     "@stryker-mutator/jest-runner": "^9.6.1",
@@ -111,7 +111,7 @@
     "globals": "^17.5.0",
     "husky": "^9.1.7",
     "jest": "^30.3.0",
-    "lint-staged": "^16.3.2",
+    "lint-staged": "^17.0.4",
     "selfsigned": "^5.5.0",
     "typedoc": "^0.28.19",
     "typedoc-plugin-markdown": "^4.11.0",
@@ -172,6 +172,7 @@
     "lib/**/*.d.cts"
   ],
   "overrides": {
-    "fflate": "0.8.2"
+    "fflate": "0.8.2",
+    "qs": "^6.15.2"
   }
 }