client-certificate-auth 2.0.0 → 2.0.1

package/README.md

@@ -8,11 +8,12 @@ Comprehensive toolkit for client SSL certificate authentication (mTLS) in Node.j
 [![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)
 
 [**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)).
+**Fanatically Tested** - 100% line/branch/function/statement coverage, plus mutation testing and E2E tests against real nginx/Envoy/Traefik containers. ~5,224 lines of test code for ~788 lines of source (measured by [cloc](https://github.com/AlDanial/cloc)).
 
 ## Installation
 
@@ -814,6 +815,15 @@ 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
 
+## Upgrading from 1.x
+
+v2.0.0 introduced two behavior changes:
+
+- **Validation callbacks must return exactly `true`.** Previously any truthy value (`'admin'`, `1`, an object) authorized; now only `true` (or a `Promise`/thenable resolving to `true`) does. Callbacks that returned ad-hoc truthy values (e.g., `return cert.subject.CN`) must be rewritten to explicit `return true` / `return false`.
+- **Header options are validated at construction.** Typos like `certificateSource: 'aws-alp'` now throw at app startup instead of failing at request time.
+
+See the [CHANGELOG](./CHANGELOG.md) for the full v2.0.0 entry.
+
 ## Troubleshooting
 
 ### `DEPTH_ZERO_SELF_SIGNED_CERT` error

package/lib/clientCertificateAuth.cjs

@@ -98,12 +98,23 @@ function clientCertificateAuth(callback, options = {}) {
         // Ensure that the certificate was validated at the protocol level
         if (!req.socket?.authorized) {
             safeCallHook(onRejected, null, req, 'socket_not_authorized');
-            const authError = req.socket?.authorizationError || 'unknown';
-            const e = new Error(`Unauthorized: Client certificate required (${authError})`);
+            const e = new Error('Unauthorized: Client certificate required');
             e.status = 401;
             return next(e);
         }
 
+        // Socket may report authorized: true without exposing TLS methods (mocks,
+        // misconfigured non-TLS path that nonetheless sets authorized). Mirrors the
+        // guard in the ESM extractor (lib/extractor.js).
+        if (typeof req.socket.getPeerCertificate !== 'function') {
+            safeCallHook(onRejected, null, req, 'certificate_not_retrievable');
+            const e = new Error(
+                'Client certificate was authenticated but certificate information could not be retrieved.'
+            );
+            e.status = 500;
+            return next(e);
+        }
+
         // Obtain certificate details
         const cert = req.socket.getPeerCertificate(includeChain);
         if (!cert || Object.keys(cert).length === 0) {

package/lib/clientCertificateAuth.d.cts

@@ -1,5 +1,6 @@
 import type { IncomingMessage, ServerResponse } from 'http';
-import type { TLSSocket, PeerCertificate, DetailedPeerCertificate } from 'tls';
+import type { Socket } from 'net';
+import type { PeerCertificate, DetailedPeerCertificate } from 'tls';
 import type {
     ClientCertificateAuthOptions as EsmOptions,
     ValidationCallback as EsmValidationCallback,
@@ -24,17 +25,31 @@ export interface HttpError extends Error {
 }
 
 /**
- * Extended request object with TLS socket and optional Express properties.
+ * Extended request object compatible with Node's `http.IncomingMessage`,
+ * Express's `Request`, and Connect-style request objects.
+ *
+ * The socket is typed as the broader `net.Socket` with TLS-specific fields
+ * marked optional so the middleware accepts requests from any of those
+ * frameworks without a framework-specific type dependency. The runtime
+ * guards in the middleware check for `getPeerCertificate` before calling it.
  */
 export interface ClientCertRequest extends IncomingMessage {
-    /** True if connection is over HTTPS (Express-specific) */
+    /** True if connection is over HTTPS (Express-specific, optional). */
     secure?: boolean;
-    /** TLS socket with authorization properties */
-    socket: TLSSocket & {
-        /** Whether the client certificate was authorized at the TLS layer */
+    /**
+     * Underlying socket. Typed as the broader `net.Socket` so this interface
+     * is satisfied by both Node's `IncomingMessage.socket` and Express's
+     * `Request.socket`. TLS-specific fields (`authorized`, `authorizationError`,
+     * `getPeerCertificate`) are present at runtime when the request arrived
+     * over TLS and are detected by the middleware via runtime feature checks.
+     */
+    socket: Socket & {
+        /** Whether the client certificate was authorized at the TLS layer. */
         authorized?: boolean;
-        /** Error message if authorization failed */
-        authorizationError?: string;
+        /** Error from TLS authorization, if any. */
+        authorizationError?: Error | string;
+        /** TLS getPeerCertificate, present on TLSSocket only. */
+        getPeerCertificate?: (detailed?: boolean) => PeerCertificate | DetailedPeerCertificate;
     };
     /**
      * Client certificate attached by clientCertificateAuth middleware.

package/lib/clientCertificateAuth.d.ts

@@ -1,5 +1,6 @@
 import type { IncomingMessage, ServerResponse } from 'http';
-import type { TLSSocket, PeerCertificate, DetailedPeerCertificate } from 'tls';
+import type { Socket } from 'net';
+import type { PeerCertificate, DetailedPeerCertificate } from 'tls';
 import type { CertificateSource, HeaderEncoding } from './parsers.js';
 
 export type { CertificateSource, HeaderEncoding };
@@ -22,17 +23,31 @@ export interface HttpError extends Error {
 }
 
 /**
- * Extended request object with TLS socket and optional Express properties.
+ * Extended request object compatible with Node's `http.IncomingMessage`,
+ * Express's `Request`, and Connect-style request objects.
+ *
+ * The socket is typed as the broader `net.Socket` with TLS-specific fields
+ * marked optional so the middleware accepts requests from any of those
+ * frameworks without a framework-specific type dependency. The runtime
+ * guards in the middleware check for `getPeerCertificate` before calling it.
  */
 export interface ClientCertRequest extends IncomingMessage {
-    /** True if connection is over HTTPS (Express-specific) */
+    /** True if connection is over HTTPS (Express-specific, optional). */
     secure?: boolean;
-    /** TLS socket with authorization properties */
-    socket: TLSSocket & {
-        /** Whether the client certificate was authorized at the TLS layer */
+    /**
+     * Underlying socket. Typed as the broader `net.Socket` so this interface
+     * is satisfied by both Node's `IncomingMessage.socket` and Express's
+     * `Request.socket`. TLS-specific fields (`authorized`, `authorizationError`,
+     * `getPeerCertificate`) are present at runtime when the request arrived
+     * over TLS and are detected by the middleware via runtime feature checks.
+     */
+    socket: Socket & {
+        /** Whether the client certificate was authorized at the TLS layer. */
         authorized?: boolean;
-        /** Error message if authorization failed */
-        authorizationError?: string;
+        /** Error from TLS authorization, if any. */
+        authorizationError?: Error | string;
+        /** TLS getPeerCertificate, present on TLSSocket only. */
+        getPeerCertificate?: (detailed?: boolean) => PeerCertificate | DetailedPeerCertificate;
     };
     /**
      * Client certificate attached by clientCertificateAuth middleware.
@@ -91,6 +106,7 @@ export interface ClientCertificateAuthOptions {
     /**
      * Expected value indicating successful certificate verification.
      * If verifyHeader is set, requests are rejected unless the header matches this value.
+     * Comparison is exact (case-sensitive, no whitespace trimming).
      * Example: 'SUCCESS' for nginx.
      */
     verifyValue?: string;

package/lib/clientCertificateAuth.js

@@ -5,10 +5,7 @@
  * @license MIT
  */
 
-import { extractClientCertificate } from './extractor.js';
-import { PRESETS } from './parsers.js';
-
-const VALID_ENCODINGS = ['url-pem', 'url-pem-aws', 'xfcc', 'base64-der', 'rfc9440'];
+import { extractClientCertificate, validateExtractorOptions } from './extractor.js';
 
 /**
  * Duck-typed thenable check per Promises/A+: an object or function with
@@ -24,7 +21,7 @@ function isThenable(value) {
 }
 
 /**
- * @typedef {import('http').IncomingMessage & { secure?: boolean; socket: import('tls').TLSSocket & { authorized?: boolean; authorizationError?: string }; clientCertificate?: import('tls').PeerCertificate }} ClientCertRequest
+ * @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
  * @typedef {(req: ClientCertRequest, res: ClientCertResponse, next: (err?: Error) => void) => void} Middleware
  */
@@ -49,6 +46,7 @@ function isThenable(value) {
  *   upstream proxy (e.g., 'X-SSL-Client-Verify'). Must be used with verifyValue.
  * @property {string} [verifyValue] - Expected value indicating successful verification (e.g., 'SUCCESS').
  *   If verifyHeader is set, requests are rejected unless the header matches this value.
+ *   Comparison is exact (case-sensitive, no whitespace trimming); set this to the exact string your proxy emits.
  * @property {(cert: import('tls').PeerCertificate, req: ClientCertRequest) => void | Promise<void>} [onAuthenticated] -
  *   Called when a client is successfully authenticated. Fire-and-forget.
  * @property {(cert: import('tls').PeerCertificate | null, req: ClientCertRequest, reason: string) => void | Promise<void>} [onRejected] -
@@ -93,6 +91,8 @@ export default function clientCertificateAuth(callback, options = {}) {
     throw new TypeError('client-certificate-auth: callback must be a function');
   }
 
+  validateExtractorOptions(options);
+
   const {
     certificateSource,
     certificateHeader,
@@ -105,30 +105,6 @@ export default function clientCertificateAuth(callback, options = {}) {
     onRejected,
   } = options;
 
-  if ((verifyHeader && !verifyValue) || (!verifyHeader && verifyValue)) {
-    throw new Error(
-      'client-certificate-auth: verifyHeader and verifyValue must both be provided together, or both omitted'
-    );
-  }
-
-  if (certificateSource && !Object.hasOwn(PRESETS, certificateSource)) {
-    throw new Error(
-      `client-certificate-auth: unknown certificateSource '${certificateSource}'. Valid values: ${Object.keys(PRESETS).join(', ')}`
-    );
-  }
-
-  if (headerEncoding && !VALID_ENCODINGS.includes(headerEncoding)) {
-    throw new Error(
-      `client-certificate-auth: unknown headerEncoding '${headerEncoding}'. Valid values: ${VALID_ENCODINGS.join(', ')}`
-    );
-  }
-
-  if (certificateHeader && !certificateSource && !headerEncoding) {
-    throw new Error(
-      'client-certificate-auth: certificateHeader requires headerEncoding (or a certificateSource preset that supplies one)'
-    );
-  }
-
   /**
    * Safely call a hook function without blocking or throwing.
    * Deferred via queueMicrotask to ensure truly non-blocking behavior.
@@ -171,19 +147,15 @@ export default function clientCertificateAuth(callback, options = {}) {
       let statusCode = 401;
 
       switch (result.reason) {
-        case 'verification_header_mismatch': {
-          const verifyStatus = req.headers[verifyHeader.toLowerCase()];
-          errorMessage = `Unauthorized: Certificate verification failed (${verifyStatus || 'header missing'})`;
+        case 'verification_header_mismatch':
+          errorMessage = 'Unauthorized: Certificate verification failed';
           break;
-        }
         case 'header_missing_or_malformed':
           errorMessage = 'Unauthorized: Client certificate header missing or malformed';
           break;
-        case 'socket_not_authorized': {
-          const authError = req.socket?.authorizationError || 'unknown';
-          errorMessage = `Unauthorized: Client certificate required (${authError})`;
+        case 'socket_not_authorized':
+          errorMessage = 'Unauthorized: Client certificate required';
           break;
-        }
         case 'certificate_not_retrievable':
           errorMessage = 'Client certificate was authenticated but certificate information could not be retrieved.';
           statusCode = 500;

package/lib/extractor.d.ts

@@ -58,6 +58,13 @@ export function extractClientCertificate(req: {
         getPeerCertificate?: (detailed: boolean) => import("tls").PeerCertificate;
     };
 }, options?: ExtractorOptions): ExtractionResult;
+/**
+ * Validate options shared by `extractClientCertificate` and the middleware constructor.
+ * Throws on unknown `certificateSource`, unknown `headerEncoding`,
+ * `certificateHeader` without an encoding source, or only one of `verifyHeader`/`verifyValue`.
+ * Omitted or `undefined` options are treated as the empty object; explicit `null` throws.
+ */
+export function validateExtractorOptions(options?: ExtractorOptions): void;
 export type ExtractionResult = {
     /**
      * - Whether extraction succeeded

package/lib/extractor.js

@@ -4,7 +4,47 @@
  * @license MIT
  */
 
-import { getCertificateFromHeaders } from './parsers.js';
+import { getCertificateFromHeaders, PRESETS } from './parsers.js';
+
+const VALID_ENCODINGS = ['url-pem', 'url-pem-aws', 'xfcc', 'base64-der', 'rfc9440'];
+
+/**
+ * Validate options shared by `extractClientCertificate` and the middleware
+ * constructor. Throws on misconfiguration (unknown preset, unknown encoding,
+ * `certificateHeader` without an encoding source, or only one of
+ * `verifyHeader`/`verifyValue`). Omitted or `undefined` options are treated
+ * as the empty object; explicit `null` will throw a `TypeError`.
+ *
+ * @param {ExtractorOptions} [options]
+ * @throws {Error} when options are malformed
+ */
+export function validateExtractorOptions(options = {}) {
+  const { certificateSource, certificateHeader, headerEncoding, verifyHeader, verifyValue } = options;
+
+  if ((verifyHeader && !verifyValue) || (!verifyHeader && verifyValue)) {
+    throw new Error(
+      'client-certificate-auth: verifyHeader and verifyValue must both be provided together, or both omitted'
+    );
+  }
+
+  if (certificateSource && !Object.hasOwn(PRESETS, certificateSource)) {
+    throw new Error(
+      `client-certificate-auth: unknown certificateSource '${certificateSource}'. Valid values: ${Object.keys(PRESETS).join(', ')}`
+    );
+  }
+
+  if (headerEncoding && !VALID_ENCODINGS.includes(headerEncoding)) {
+    throw new Error(
+      `client-certificate-auth: unknown headerEncoding '${headerEncoding}'. Valid values: ${VALID_ENCODINGS.join(', ')}`
+    );
+  }
+
+  if (certificateHeader && !certificateSource && !headerEncoding) {
+    throw new Error(
+      'client-certificate-auth: certificateHeader requires headerEncoding (or a certificateSource preset that supplies one)'
+    );
+  }
+}
 
 /**
  * @typedef {Object} ExtractionResult
@@ -66,6 +106,8 @@ import { getCertificateFromHeaders } from './parsers.js';
  * });
  */
 export function extractClientCertificate(req, options = {}) {
+  validateExtractorOptions(options);
+
   const {
     certificateSource,
     certificateHeader,
@@ -76,13 +118,6 @@ export function extractClientCertificate(req, options = {}) {
     verifyValue,
   } = options;
 
-  // Validate verifyHeader/verifyValue pairing
-  if ((verifyHeader && !verifyValue) || (!verifyHeader && verifyValue)) {
-    throw new Error(
-      'extractClientCertificate: verifyHeader and verifyValue must both be provided together, or both omitted'
-    );
-  }
-
   const useHeaders = Boolean(certificateSource || certificateHeader);
   let cert = null;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "client-certificate-auth",
-  "version": "2.0.0",
+  "version": "2.0.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": {
@@ -72,6 +72,7 @@
     "node": ">= 20"
   },
   "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.2",
     "@commitlint/cli": "^20.4.3",
     "@commitlint/config-conventional": "^20.5.0",
     "@eslint/js": "^10.0.1",
@@ -143,5 +144,8 @@
     "lib/**/*.cjs",
     "lib/**/*.d.ts",
     "lib/**/*.d.cts"
-  ]
+  ],
+  "overrides": {
+    "fflate": "0.8.2"
+  }
 }