client-certificate-auth 2.0.2 → 2.1.1

package/README.md

@@ -13,7 +13,27 @@ Comprehensive toolkit for client SSL certificate authentication (mTLS) in Node.j
 
 **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. ~5,224 lines of test code for ~788 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. ~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
 
@@ -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.
@@ -39,6 +52,7 @@ function isThenable(value) {
 const UNSUPPORTED_OPTIONS = [
     'certificateSource',
     'certificateHeader',
+    'chainHeader',
     'headerEncoding',
     'fallbackToSocket',
     'verifyHeader',
@@ -144,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;
@@ -154,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.d.ts

@@ -77,6 +77,15 @@ export interface ClientCertificateAuthOptions {
      */
     certificateHeader?: string;
 
+    /**
+     * Optional second header carrying the certificate chain alongside the leaf.
+     * Split on commas per RFC 9440, each item parsed with the same
+     * headerEncoding, results linked via issuerCertificate. For non-RFC-9440
+     * encodings the comma split may not match the encoding's list convention.
+     * Same trust boundary as certificateHeader.
+     */
+    chainHeader?: string;
+
     /**
      * How to decode the header value.
      * Required when using certificateHeader without certificateSource.

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
@@ -28,7 +41,7 @@ function isThenable(value) {
 
 /**
  * @typedef {Object} ClientCertificateAuthOptions
- * @property {'aws-alb' | 'envoy' | 'cloudflare' | 'traefik'} [certificateSource] - Use a preset
+ * @property {'aws-alb' | 'aws-alb-verify' | 'azure-app-service' | 'cloudflare' | 'cloudflare-rfc9440' | 'envoy' | 'traefik'} [certificateSource] - Use a preset
  *   configuration for a known reverse proxy. Header-based certs are only checked if this or
  *   certificateHeader is set. Trust boundary: the proxy must strip the preset's header from
  *   external requests; any source that can set it is trusted to assert client identity.
@@ -36,7 +49,11 @@ function isThenable(value) {
  *   Overrides preset header name if also using certificateSource. Trust boundary: the proxy
  *   must strip this header from external requests; any source that can set it is trusted to
  *   assert client identity.
- * @property {'url-pem' | 'url-pem-aws' | 'xfcc' | 'base64-der' | 'rfc9440'} [headerEncoding] - 
+ * @property {string} [chainHeader] - Optional second header carrying the certificate chain
+ *   alongside the leaf in certificateHeader (or the preset's header). Split on commas per
+ *   RFC 9440, each item parsed with the same headerEncoding, results linked via
+ *   issuerCertificate. Same trust boundary as certificateHeader.
+ * @property {'url-pem' | 'url-pem-aws' | 'xfcc' | 'base64-der' | 'rfc9440'} [headerEncoding] -
  *   How to decode the header value. Required when using certificateHeader without certificateSource.
  * @property {boolean} [fallbackToSocket=false] - If header-based extraction is configured but 
  *   fails (header absent or malformed), try socket.getPeerCertificate() instead of returning 401.
@@ -96,6 +113,7 @@ export default function clientCertificateAuth(callback, options = {}) {
   const {
     certificateSource,
     certificateHeader,
+    chainHeader,
     headerEncoding,
     fallbackToSocket = false,
     includeChain = false,
@@ -132,6 +150,7 @@ export default function clientCertificateAuth(callback, options = {}) {
     const result = extractClientCertificate(req, {
       certificateSource,
       certificateHeader,
+      chainHeader,
       headerEncoding,
       fallbackToSocket,
       includeChain,
@@ -189,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;
@@ -199,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/extractor.d.ts

@@ -12,8 +12,9 @@
  */
 /**
  * @typedef {Object} ExtractorOptions
- * @property {'aws-alb' | 'envoy' | 'cloudflare' | 'traefik'} [certificateSource] - Preset configuration
+ * @property {'aws-alb' | 'aws-alb-verify' | 'azure-app-service' | 'cloudflare' | 'cloudflare-rfc9440' | 'envoy' | 'traefik'} [certificateSource] - Preset configuration
  * @property {string} [certificateHeader] - Custom header name
+ * @property {string} [chainHeader] - Optional second header carrying the certificate chain
  * @property {'url-pem' | 'url-pem-aws' | 'xfcc' | 'base64-der' | 'rfc9440'} [headerEncoding] - Header encoding
  * @property {boolean} [fallbackToSocket=false] - Try socket if header extraction fails
  * @property {boolean} [includeChain=false] - Include issuerCertificate chain
@@ -89,11 +90,15 @@ export type ExtractorOptions = {
     /**
      * - Preset configuration
      */
-    certificateSource?: "aws-alb" | "envoy" | "cloudflare" | "traefik";
+    certificateSource?: "aws-alb" | "aws-alb-verify" | "azure-app-service" | "cloudflare" | "cloudflare-rfc9440" | "envoy" | "traefik";
     /**
      * - Custom header name
      */
     certificateHeader?: string;
+    /**
+     * - Optional second header carrying the certificate chain
+     */
+    chainHeader?: string;
     /**
      * - Header encoding
      */

package/lib/extractor.js

@@ -4,22 +4,23 @@
  * @license MIT
  */
 
-import { getCertificateFromHeaders, PRESETS } from './parsers.js';
+import { getCertificateFromHeaders, parseHeaderValue, 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`.
+ * `certificateHeader` without an encoding source, `chainHeader` without a
+ * leaf header 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;
+  const { certificateSource, certificateHeader, chainHeader, headerEncoding, verifyHeader, verifyValue } = options;
 
   if ((verifyHeader && !verifyValue) || (!verifyHeader && verifyValue)) {
     throw new Error(
@@ -44,6 +45,12 @@ export function validateExtractorOptions(options = {}) {
       'client-certificate-auth: certificateHeader requires headerEncoding (or a certificateSource preset that supplies one)'
     );
   }
+
+  if (chainHeader && !certificateSource && !certificateHeader) {
+    throw new Error(
+      'client-certificate-auth: chainHeader requires certificateSource or certificateHeader (chain header must accompany a leaf header configuration)'
+    );
+  }
 }
 
 /**
@@ -61,12 +68,16 @@ export function validateExtractorOptions(options = {}) {
 
 /**
  * @typedef {Object} ExtractorOptions
- * @property {'aws-alb' | 'envoy' | 'cloudflare' | 'traefik'} [certificateSource] - Preset
+ * @property {'aws-alb' | 'aws-alb-verify' | 'azure-app-service' | 'cloudflare' | 'cloudflare-rfc9440' | 'envoy' | 'traefik'} [certificateSource] - Preset
  *   configuration. Trust boundary: the proxy must strip the preset's header from external
  *   requests; any source that can set it is trusted to assert client identity.
  * @property {string} [certificateHeader] - Custom header name. Trust boundary: the proxy must
  *   strip this header from external requests; any source that can set it is trusted to assert
  *   client identity.
+ * @property {string} [chainHeader] - Optional second header carrying the certificate chain
+ *   alongside the leaf. Split on commas per RFC 9440, each item parsed with the same
+ *   `headerEncoding`, results linked via `issuerCertificate`. For non-RFC-9440 encodings
+ *   the comma split may not match the encoding's list convention.
  * @property {'url-pem' | 'url-pem-aws' | 'xfcc' | 'base64-der' | 'rfc9440'} [headerEncoding] - Header encoding
  * @property {boolean} [fallbackToSocket=false] - Try socket if header extraction fails
  * @property {boolean} [includeChain=false] - Include issuerCertificate chain
@@ -111,6 +122,7 @@ export function extractClientCertificate(req, options = {}) {
   const {
     certificateSource,
     certificateHeader,
+    chainHeader,
     headerEncoding,
     fallbackToSocket = false,
     includeChain = false,
@@ -142,6 +154,32 @@ export function extractClientCertificate(req, options = {}) {
       headerEncoding,
     });
 
+    // Append chain from a separate chain header if configured.
+    // Resolve: explicit chainHeader > preset.chainHeader; explicit encoding > preset.encoding.
+    // Split on commas per RFC 9440, parse each item, link via issuerCertificate.
+    if (cert) {
+      const preset = certificateSource ? PRESETS[certificateSource] : null;
+      const chainHeaderName = (chainHeader ?? preset?.chainHeader)?.toLowerCase();
+      const chainEncoding = headerEncoding ?? preset?.encoding;
+      if (chainHeaderName && chainEncoding) {
+        const chainHeaderValue = req.headers[chainHeaderName];
+        if (chainHeaderValue && !Array.isArray(chainHeaderValue)) {
+          const chainCerts = chainHeaderValue
+            .split(',')
+            .map(item => item.trim())
+            .filter(Boolean)
+            .map(item => parseHeaderValue(item, chainEncoding))
+            .filter(Boolean);
+          if (chainCerts.length > 0) {
+            cert.issuerCertificate = chainCerts[0];
+            for (let i = 0; i < chainCerts.length - 1; i++) {
+              chainCerts[i].issuerCertificate = chainCerts[i + 1];
+            }
+          }
+        }
+      }
+    }
+
     // Normalize: strip chain unless includeChain is true
     if (cert && !includeChain && 'issuerCertificate' in cert) {
       delete cert.issuerCertificate;

package/lib/fetch.cjs

@@ -0,0 +1,20 @@
+/*!
+ * client-certificate-auth/fetch - CommonJS wrapper
+ * Copyright (C) 2013-2026 Tony Gies
+ * @license MIT
+ */
+
+'use strict';
+
+let _module;
+
+async function load() {
+    // Stryker disable next-line ConditionalExpression,BlockStatement: test ordering caches _module from prior test; ConditionalExpression→true (always re-import) re-imports same module successfully; BlockStatement→{} uses cached value
+    if (!_module) {
+        // Stryker disable next-line StringLiteral: test ordering caches _module; StringLiteral→"" fails import but cached value masks it
+        _module = await import('./fetch.js');
+    }
+    return _module;
+}
+
+module.exports = { load };

package/lib/fetch.d.cts

@@ -0,0 +1,13 @@
+/*!
+ * client-certificate-auth/fetch - CommonJS type declarations
+ * Copyright (C) 2013-2026 Tony Gies
+ * @license MIT
+ */
+
+import type * as FetchModule from './fetch.js';
+
+declare const fetchAdapter: {
+    load(): Promise<typeof FetchModule>;
+};
+
+export = fetchAdapter;

package/lib/fetch.d.ts

@@ -0,0 +1,28 @@
+/*!
+ * client-certificate-auth/fetch - TypeScript declarations
+ * Copyright (C) 2013-2026 Tony Gies
+ * @license MIT
+ */
+
+import type { ExtractorOptions, ExtractionResult } from './extractor.js';
+
+/**
+ * Any object whose `headers` field iterates as `[name, value]` tuples.
+ * Web `Request`, undici `Headers`, Bun, Deno, and Node 18+ `Headers`
+ * all work without modification.
+ */
+export interface RequestLike {
+    headers: Iterable<[string, string]>;
+}
+
+/**
+ * Extract a client certificate from a Web standard `Request` or any
+ * object with iterable headers. Header-only (no TLS socket in Web Request).
+ *
+ * @param request - A Web Request or any object with iterable headers
+ * @param options - Same options as `extractClientCertificate`. Header options only.
+ */
+export declare function extractClientCertificateFromRequest(
+    request: RequestLike,
+    options?: ExtractorOptions
+): ExtractionResult;

package/lib/fetch.js

@@ -0,0 +1,59 @@
+/*!
+ * client-certificate-auth/fetch - Web Request adapter
+ * Copyright (C) 2013-2026 Tony Gies
+ * @license MIT
+ */
+
+import { extractClientCertificate } from './extractor.js';
+
+/**
+ * @typedef {import('./extractor.js').ExtractorOptions} ExtractorOptions
+ * @typedef {import('./extractor.js').ExtractionResult} ExtractionResult
+ */
+
+/**
+ * Extract a client certificate from a Web standard `Request` (or any object
+ * with an iterable `headers` field that yields `[name, value]` tuples).
+ *
+ * Normalizes header names to lowercase and delegates to the core
+ * `extractClientCertificate`. Header-only: Web `Request` has no TLS socket,
+ * so `fallbackToSocket` is stripped and has no effect.
+ *
+ * @param {{ headers: Iterable<[string, string]> }} request - A Web Request or any object whose `headers` iterates `[name, value]` pairs.
+ * @param {ExtractorOptions} [options={}] - Same options as `extractClientCertificate`. Header-extraction options only; socket options are ignored.
+ * @returns {ExtractionResult}
+ *
+ * @example
+ * // Hono
+ * import { extractClientCertificateFromRequest } from 'client-certificate-auth/fetch';
+ *
+ * app.get('/secure', async (c) => {
+ *   const result = extractClientCertificateFromRequest(c.req.raw, {
+ *     certificateSource: 'cloudflare-rfc9440',
+ *   });
+ *   if (!result.success) return c.text('Unauthorized', 401);
+ *   return c.text(`Hello ${result.certificate.subject.CN}`);
+ * });
+ *
+ * @example
+ * // Next.js Route Handler
+ * export async function GET(request) {
+ *   const result = extractClientCertificateFromRequest(request, {
+ *     certificateSource: 'aws-alb',
+ *   });
+ *   if (!result.success) return new Response('Unauthorized', { status: 401 });
+ *   return Response.json({ user: result.certificate.subject.CN });
+ * }
+ */
+export function extractClientCertificateFromRequest(request, options = {}) {
+  // Web Headers normalizes to lowercase, but Map and other iterables
+  // preserve casing. Normalize here for the core extractor's lowercase lookup.
+  const headers = {};
+  for (const [name, value] of request.headers) {
+    headers[name.toLowerCase()] = value;
+  }
+
+  const { fallbackToSocket: _ignored, ...rest } = options;
+
+  return extractClientCertificate({ headers }, rest);
+}

package/lib/lambda.cjs

@@ -0,0 +1,20 @@
+/*!
+ * client-certificate-auth/lambda - CommonJS wrapper
+ * Copyright (C) 2013-2026 Tony Gies
+ * @license MIT
+ */
+
+'use strict';
+
+let _module;
+
+async function load() {
+    // Stryker disable next-line ConditionalExpression,BlockStatement: test ordering caches _module from prior test; ConditionalExpression→true (always re-import) re-imports same module successfully; BlockStatement→{} uses cached value
+    if (!_module) {
+        // Stryker disable next-line StringLiteral: test ordering caches _module; StringLiteral→"" fails import but cached value masks it
+        _module = await import('./lambda.js');
+    }
+    return _module;
+}
+
+module.exports = { load };

package/lib/lambda.d.cts

@@ -0,0 +1,13 @@
+/*!
+ * client-certificate-auth/lambda - CommonJS type declarations
+ * Copyright (C) 2013-2026 Tony Gies
+ * @license MIT
+ */
+
+import type * as LambdaModule from './lambda.js';
+
+declare const lambda: {
+    load(): Promise<typeof LambdaModule>;
+};
+
+export = lambda;

package/lib/lambda.d.ts

@@ -0,0 +1,78 @@
+/*!
+ * client-certificate-auth/lambda - TypeScript declarations
+ * Copyright (C) 2013-2026 Tony Gies
+ * @license MIT
+ */
+
+import type { PeerCertificate } from 'tls';
+
+/**
+ * Client certificate object from the API Gateway Lambda event.
+ * Common to v1 and v2 payload formats. Compatible with `@types/aws-lambda`
+ * without requiring it as a dependency.
+ */
+export interface LambdaClientCert {
+    /** PEM-encoded client certificate with BEGIN/END delimiters. */
+    clientCertPem: string;
+    /** Optional subject distinguished name string, parsed by API Gateway. */
+    subjectDN?: string;
+    /** Optional issuer distinguished name string, parsed by API Gateway. */
+    issuerDN?: string;
+    /** Optional certificate serial number string, parsed by API Gateway. */
+    serialNumber?: string;
+    /** Optional validity window parsed by API Gateway. */
+    validity?: {
+        notBefore?: string;
+        notAfter?: string;
+    };
+}
+
+/**
+ * Lambda event subset declaring only the cert-bearing paths.
+ * Accepts HTTP API (v2.0) and REST API (v1.0) payload formats.
+ */
+export interface LambdaEventWithClientCert {
+    requestContext?: {
+        /** v2.0 payload format: HTTP API. */
+        authentication?: {
+            clientCert?: LambdaClientCert;
+        };
+        /** v1.0 payload format: REST API. */
+        identity?: {
+            clientCert?: LambdaClientCert;
+        };
+    };
+}
+
+/**
+ * Result returned by `extractClientCertificateFromLambdaEvent`.
+ * Matches the core extractor's `ExtractionResult`.
+ */
+export interface LambdaExtractionResult {
+    /** Whether extraction succeeded. */
+    success: boolean;
+    /** Extracted certificate (null on failure). */
+    certificate: PeerCertificate | null;
+    /**
+     * Rejection reason code (null on success). Lambda-specific reasons:
+     * - 'lambda_event_missing_clientcert'
+     * - 'lambda_event_clientcert_malformed'
+     */
+    reason: string | null;
+}
+
+/**
+ * Extract a client certificate from an AWS API Gateway Lambda event. Handles
+ * both v2.0 payload format (`event.requestContext.authentication.clientCert`)
+ * and v1.0 payload format (`event.requestContext.identity.clientCert`).
+ *
+ * Also accepts `null` and `undefined`, returning
+ * `lambda_event_missing_clientcert`.
+ *
+ * @param event - The Lambda event from API Gateway, or null/undefined
+ *
+ * @see https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-mutual-tls.html
+ */
+export declare function extractClientCertificateFromLambdaEvent(
+    event: LambdaEventWithClientCert | null | undefined
+): LambdaExtractionResult;

package/lib/lambda.js

@@ -0,0 +1,73 @@
+/*!
+ * client-certificate-auth/lambda - AWS Lambda event adapter
+ * Copyright (C) 2013-2026 Tony Gies
+ * @license MIT
+ */
+
+import { pemToCertificate } from './parsers.js';
+
+/**
+ * @typedef {import('./extractor.js').ExtractionResult} ExtractionResult
+ */
+
+/**
+ * Extract a client certificate from an AWS API Gateway Lambda event.
+ *
+ * API Gateway HTTP API (v2.0 payload) delivers the validated mTLS client
+ * certificate as a pre-parsed object at
+ * `event.requestContext.authentication.clientCert`. The legacy REST API
+ * (v1.0 payload) delivers it at `event.requestContext.identity.clientCert`.
+ * Both payloads carry a `clientCertPem` field plus parsed `subjectDN`,
+ * `issuerDN`, `serialNumber`, and `validity` fields.
+ *
+ * Parses `clientCertPem` into a `PeerCertificate` so the same validation
+ * logic used with `getPeerCertificate()` or `extractClientCertificate()`
+ * works inside a Lambda handler. If both v1 and v2 fields are present,
+ * v2 takes precedence.
+ *
+ * @param {object | null | undefined} event - The Lambda event object from API Gateway (also accepts null/undefined)
+ * @returns {ExtractionResult}
+ *
+ * Rejection reasons:
+ * - 'lambda_event_missing_clientcert' - No clientCertPem at either v1 or v2 location
+ * - 'lambda_event_clientcert_malformed' - clientCertPem present but parsing failed
+ *
+ * @example
+ * import { extractClientCertificateFromLambdaEvent } from 'client-certificate-auth/lambda';
+ *
+ * export const handler = async (event) => {
+ *   const result = extractClientCertificateFromLambdaEvent(event);
+ *   if (!result.success) return { statusCode: 401, body: result.reason };
+ *   if (result.certificate.subject.CN !== 'authorized-client') {
+ *     return { statusCode: 403 };
+ *   }
+ *   return { statusCode: 200, body: 'OK' };
+ * };
+ */
+export function extractClientCertificateFromLambdaEvent(event) {
+  const v2 = event?.requestContext?.authentication?.clientCert;
+  const v1 = event?.requestContext?.identity?.clientCert;
+  const clientCert = v2 ?? v1;
+
+  if (!clientCert?.clientCertPem) {
+    return {
+      success: false,
+      certificate: null,
+      reason: 'lambda_event_missing_clientcert',
+    };
+  }
+
+  try {
+    return {
+      success: true,
+      certificate: pemToCertificate(clientCert.clientCertPem),
+      reason: null,
+    };
+  } catch {
+    return {
+      success: false,
+      certificate: null,
+      reason: 'lambda_event_clientcert_malformed',
+    };
+  }
+}

package/lib/parsers.d.ts

@@ -14,7 +14,14 @@ export type HeaderEncoding = 'url-pem' | 'url-pem-aws' | 'xfcc' | 'base64-der' |
 /**
  * Supported certificate source presets.
  */
-export type CertificateSource = 'aws-alb' | 'envoy' | 'cloudflare' | 'traefik';
+export type CertificateSource =
+    | 'aws-alb'
+    | 'aws-alb-verify'
+    | 'azure-app-service'
+    | 'cloudflare'
+    | 'cloudflare-rfc9440'
+    | 'envoy'
+    | 'traefik';
 
 /**
  * Preset configuration for a reverse proxy.
@@ -22,6 +29,12 @@ export type CertificateSource = 'aws-alb' | 'envoy' | 'cloudflare' | 'traefik';
 export interface PresetConfig {
     /** HTTP header name (lowercase) */
     header: string;
+    /**
+     * Optional second header carrying the certificate chain. Set on
+     * two-header schemes like RFC 9440 (Client-Cert + Client-Cert-Chain).
+     * Lowercased per Node convention.
+     */
+    chainHeader?: string;
     /** Encoding format used by this proxy */
     encoding: HeaderEncoding;
 }

package/lib/parsers.js

@@ -13,7 +13,8 @@ import { X509Certificate } from 'node:crypto';
 
 /**
  * Preset configurations for common reverse proxies.
- * Maps preset name to { header, encoding } configuration.
+ * Maps preset name to { header, encoding } configuration, with optional
+ * `chainHeader` for two-header schemes (RFC 9440).
  */
 export const PRESETS = {
     /**
@@ -25,21 +26,55 @@ export const PRESETS = {
         encoding: 'url-pem-aws',
     },
     /**
-     * Envoy proxy / Istio service mesh using XFCC header.
-     * @see https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers#x-forwarded-client-cert
+     * AWS Application Load Balancer in mTLS verify mode. ALB validates the
+     * client certificate against a configured trust store and forwards the
+     * leaf as URL-encoded PEM (the leaf only, not the chain) plus parsed
+     * subject/issuer/serial/validity headers for convenience.
+     * @see https://docs.aws.amazon.com/elasticloadbalancing/latest/application/mutual-authentication.html
      */
-    'envoy': {
-        header: 'x-forwarded-client-cert',
-        encoding: 'xfcc',
+    'aws-alb-verify': {
+        header: 'x-amzn-mtls-clientcert-leaf',
+        encoding: 'url-pem-aws',
+    },
+    /**
+     * Azure App Service mTLS forwarding. App Service injects the bare
+     * base64-encoded DER (the body of a PEM cert without delimiters) into
+     * `X-ARR-ClientCert`. Same header convention is used by IIS/ARR.
+     * @see https://learn.microsoft.com/en-us/azure/app-service/app-service-web-configure-tls-mutual-auth
+     */
+    'azure-app-service': {
+        header: 'x-arr-clientcert',
+        encoding: 'base64-der',
     },
     /**
-     * Cloudflare with client_certificate_forwarding enabled.
+     * Cloudflare with client_certificate_forwarding enabled (legacy
+     * Cf-Client-Cert-* header family).
      * @see https://developers.cloudflare.com/api-shield/security/mtls/configure/
      */
     'cloudflare': {
         header: 'cf-client-cert-der-base64',
         encoding: 'base64-der',
     },
+    /**
+     * Cloudflare with RFC 9440 forwarding enabled (March 2026 feature).
+     * Operators set `Client-Cert` and `Client-Cert-Chain` headers via
+     * Transform Rules. Leaf is `:base64:`-wrapped; chain is a structured
+     * field list of `:base64:` items separated by commas.
+     * @see https://developers.cloudflare.com/changelog/post/2026-03-25-rfc9440-mtls-fields/
+     */
+    'cloudflare-rfc9440': {
+        header: 'client-cert',
+        chainHeader: 'client-cert-chain',
+        encoding: 'rfc9440',
+    },
+    /**
+     * Envoy proxy / Istio service mesh using XFCC header.
+     * @see https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers#x-forwarded-client-cert
+     */
+    'envoy': {
+        header: 'x-forwarded-client-cert',
+        encoding: 'xfcc',
+    },
     /**
      * Traefik with PassTLSClientCert middleware (pem: true).
      * Traefik sends raw base64 (no PEM delimiters, not URL-encoded).
@@ -126,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);
@@ -322,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.0.2",
+  "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": {
@@ -51,6 +51,26 @@
         "types": "./lib/extractor.d.cts",
         "default": "./lib/extractor.cjs"
       }
+    },
+    "./lambda": {
+      "import": {
+        "types": "./lib/lambda.d.ts",
+        "default": "./lib/lambda.js"
+      },
+      "require": {
+        "types": "./lib/lambda.d.cts",
+        "default": "./lib/lambda.cjs"
+      }
+    },
+    "./fetch": {
+      "import": {
+        "types": "./lib/fetch.d.ts",
+        "default": "./lib/fetch.js"
+      },
+      "require": {
+        "types": "./lib/fetch.d.cts",
+        "default": "./lib/fetch.cjs"
+      }
     }
   },
   "main": "./lib/clientCertificateAuth.cjs",
@@ -65,6 +85,12 @@
       ],
       "extractor": [
         "./lib/extractor.d.ts"
+      ],
+      "lambda": [
+        "./lib/lambda.d.ts"
+      ],
+      "fetch": [
+        "./lib/fetch.d.ts"
       ]
     }
   },
@@ -73,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",
@@ -85,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",
@@ -146,6 +172,7 @@
     "lib/**/*.d.cts"
   ],
   "overrides": {
-    "fflate": "0.8.2"
+    "fflate": "0.8.2",
+    "qs": "^6.15.2"
   }
 }