client-certificate-auth 1.3.5 → 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
 
@@ -171,7 +172,7 @@ Returns Express middleware.
 
 | Name | Type | Description |
 |------|------|-------------|
-| `callback` | `(cert, req?) => boolean \| Promise<boolean>` | Receives the client certificate and request, returns `true` to allow access |
+| `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.certificateHeader` | `string` | Custom header name to read certificate from |
 | `options.headerEncoding` | `string` | Encoding format: `'url-pem'`, `'url-pem-aws'`, `'xfcc'`, `'base64-der'`, `'rfc9440'` |
@@ -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

@@ -19,6 +19,19 @@ async function loadModule() {
     return _default;
 }
 
+/**
+ * Duck-typed thenable check per Promises/A+: an object or function with
+ * a callable `.then` method. Matches the set of values `Promise.resolve`
+ * natively adopts as thenables.
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isThenable(value) {
+    return value !== null
+        && (typeof value === 'object' || typeof value === 'function')
+        && typeof value.then === 'function';
+}
+
 /**
  * Options not supported by the sync CJS wrapper.
  * These require the ESM module's async header parsing.
@@ -90,6 +103,18 @@ function clientCertificateAuth(callback, options = {}) {
             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) {
@@ -105,7 +130,7 @@ function clientCertificateAuth(callback, options = {}) {
         req.clientCertificate = cert;
 
         function doneAuthorizing(authorized) {
-            if (authorized) {
+            if (authorized === true) {
                 safeCallHook(onAuthenticated, cert, req);
                 return next();
             } else {
@@ -118,8 +143,8 @@ function clientCertificateAuth(callback, options = {}) {
 
         try {
             const result = callback(cert, req);
-            if (result instanceof Promise) {
-                result.then(doneAuthorizing).catch((err) => {
+            if (isThenable(result)) {
+                Promise.resolve(result).then(doneAuthorizing).catch((err) => {
                     safeCallHook(onRejected, cert, req, err.message || 'callback_threw');
                     if (err.status === undefined) {
                         err.status = 401;

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.
@@ -94,7 +109,7 @@ export interface ClientCertificateAuthOptions {
 export type ValidationCallback = (
     cert: PeerCertificate | DetailedPeerCertificate,
     req?: ClientCertRequest
-) => boolean | Promise<boolean>;
+) => boolean | PromiseLike<boolean>;
 
 export type Middleware = (
     req: ClientCertRequest,

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;
@@ -123,7 +139,7 @@ export interface ClientCertificateAuthOptions {
 export type ValidationCallback = (
     cert: PeerCertificate | DetailedPeerCertificate,
     req?: ClientCertRequest
-) => boolean | Promise<boolean>;
+) => boolean | PromiseLike<boolean>;
 
 export type Middleware = (
     req: ClientCertRequest,
@@ -135,7 +151,8 @@ export type Middleware = (
  * Express/Connect middleware for client SSL certificate authentication.
  *
  * @param callback - Validation function that receives the client certificate
- *   and returns true/false (sync) or `Promise<boolean>` (async).
+ *   and returns true/false (sync) or `PromiseLike<boolean>` (async,
+ *   including native Promises and any thenable resolving to a boolean).
  * @param options - Configuration options
  * @returns Express middleware function
  *

package/lib/clientCertificateAuth.js

@@ -5,10 +5,23 @@
  * @license MIT
  */
 
-import { extractClientCertificate } from './extractor.js';
+import { extractClientCertificate, validateExtractorOptions } from './extractor.js';
 
 /**
- * @typedef {import('http').IncomingMessage & { secure?: boolean; socket: import('tls').TLSSocket & { authorized?: boolean; authorizationError?: string }; clientCertificate?: import('tls').PeerCertificate }} ClientCertRequest
+ * Duck-typed thenable check per Promises/A+: an object or function with
+ * a callable `.then` method. Matches the set of values `Promise.resolve`
+ * natively adopts as thenables.
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isThenable(value) {
+  return value !== null
+    && (typeof value === 'object' || typeof value === 'function')
+    && typeof /** @type {{then?: unknown}} */ (value).then === 'function';
+}
+
+/**
+ * @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
  */
@@ -33,6 +46,7 @@ import { extractClientCertificate } from './extractor.js';
  *   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] -
@@ -44,12 +58,13 @@ import { extractClientCertificate } from './extractor.js';
  * passed the client certificate information for additional validation.
  *
  * The callback receives the certificate (as obtained through
- * `req.socket.getPeerCertificate()` or extracted from headers) and must 
- * return `true` (or a Promise resolving to `true`) for the request to proceed.
+ * `req.socket.getPeerCertificate()` or extracted from headers) and must
+ * return `true` (or a thenable resolving to `true`) for the request to proceed.
  *
- * @param {(cert: import('tls').PeerCertificate, req: ClientCertRequest) => boolean | Promise<boolean>} callback
+ * @param {(cert: import('tls').PeerCertificate, req: ClientCertRequest) => boolean | PromiseLike<boolean>} callback
  *   Validation function that receives the client certificate and the request
- *   object. Returns true/false (sync) or a `Promise<boolean>` (async) to
+ *   object. Returns true/false (sync) or a `PromiseLike<boolean>` (async,
+ *   including native Promises and any thenable resolving to a boolean) to
  *   allow/deny access.
  * @param {ClientCertificateAuthOptions} [options={}]
  * @returns {Middleware}
@@ -76,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,
@@ -88,12 +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'
-    );
-  }
-
   /**
    * Safely call a hook function without blocking or throwing.
    * Deferred via queueMicrotask to ensure truly non-blocking behavior.
@@ -161,10 +172,10 @@ export default function clientCertificateAuth(callback, options = {}) {
     req.clientCertificate = cert;
 
     /**
-     * @param {boolean} authorized
+     * @param {unknown} authorized
      */
     function doneAuthorizing(authorized) {
-      if (authorized) {
+      if (authorized === true) {
         safeCallHook(onAuthenticated, cert, req);
         return next();
       } else {
@@ -177,8 +188,8 @@ export default function clientCertificateAuth(callback, options = {}) {
 
     try {
       const callbackResult = callback(cert, req);
-      if (callbackResult instanceof Promise) {
-        callbackResult.then(doneAuthorizing).catch((err) => {
+      if (isThenable(callbackResult)) {
+        Promise.resolve(callbackResult).then(doneAuthorizing).catch((err) => {
           safeCallHook(onRejected, cert, req, err.message || 'callback_threw');
           if (err.status === undefined) {
             err.status = 401;

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": "1.3.5",
+  "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": {
@@ -75,12 +75,13 @@
     "@arethetypeswrong/cli": "^0.18.2",
     "@commitlint/cli": "^20.4.3",
     "@commitlint/config-conventional": "^20.5.0",
+    "@eslint/js": "^10.0.1",
     "@stryker-mutator/core": "^9.6.0",
     "@stryker-mutator/jest-runner": "^9.6.1",
     "@types/express": "^5.0.6",
     "@types/node": "^25.6.0",
     "c8": "^11.0.0",
-    "eslint": "^9.39.4",
+    "eslint": "^10.2.1",
     "globals": "^17.5.0",
     "husky": "^9.1.7",
     "jest": "^30.3.0",