client-certificate-auth 1.3.4 → 2.0.0

package/README.md

@@ -171,7 +171,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'` |

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.
@@ -106,7 +119,7 @@ function clientCertificateAuth(callback, options = {}) {
         req.clientCertificate = cert;
 
         function doneAuthorizing(authorized) {
-            if (authorized) {
+            if (authorized === true) {
                 safeCallHook(onAuthenticated, cert, req);
                 return next();
             } else {
@@ -119,8 +132,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

@@ -94,7 +94,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

@@ -123,7 +123,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 +135,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

@@ -6,6 +6,22 @@
  */
 
 import { extractClientCertificate } from './extractor.js';
+import { PRESETS } from './parsers.js';
+
+const VALID_ENCODINGS = ['url-pem', 'url-pem-aws', 'xfcc', 'base64-der', 'rfc9440'];
+
+/**
+ * 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('tls').TLSSocket & { authorized?: boolean; authorizationError?: string }; clientCertificate?: import('tls').PeerCertificate }} ClientCertRequest
@@ -44,12 +60,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}
@@ -94,6 +111,24 @@ export default function clientCertificateAuth(callback, options = {}) {
     );
   }
 
+  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.
@@ -165,10 +200,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 {
@@ -181,8 +216,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "client-certificate-auth",
-  "version": "1.3.4",
+  "version": "2.0.0",
   "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": {
@@ -74,12 +74,13 @@
   "devDependencies": {
     "@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",