client-certificate-auth 0.3.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2013-2026 Tony Gies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,114 +1,470 @@
-client-certificate-auth
-========
+# client-certificate-auth
 
-middleware for Node.js implementing client SSL certificate
-authentication/authorization
+Express/Connect middleware for client SSL certificate authentication (mTLS).
 
-Copyright © 2013 Tony Gies
+[![CI](https://github.com/tgies/client-certificate-auth/actions/workflows/ci.yml/badge.svg)](https://github.com/tgies/client-certificate-auth/actions/workflows/ci.yml)
+[![npm version](https://badge.fury.io/js/client-certificate-auth.svg)](https://www.npmjs.com/package/client-certificate-auth)
+[![codecov](https://codecov.io/gh/tgies/client-certificate-auth/graph/badge.svg)](https://codecov.io/gh/tgies/client-certificate-auth)
 
-April 30, 2013
+## Installation
 
-[![Build Status](https://travis-ci.org/tgies/client-certificate-auth.png)](https://travis-ci.org/tgies/client-certificate-auth)
+```bash
+npm install client-certificate-auth
+```
 
-installing
-----------
+**Requirements:** Node.js >= 18
 
-client-certificate-auth is available from [npm](https://npmjs.org/package/client-certificate-auth.).
+## Synopsis
 
-    $ npm install client-certificate-auth
+This middleware requires clients to present a valid, verifiable SSL certificate (mutual TLS / mTLS). The certificate is validated at the TLS layer, then passed to your callback for additional authorization logic.
 
-requirements
-------------
+Compatible with Express, Connect, and any Node.js HTTP server framework that uses standard `req.socket` and `req.headers`.
 
-client-certificate-auth is tested against Node.js versions 0.6, 0.8, and 0.10.
-It has no external dependencies (other than any middleware framework with which
-you may wish to use it); however, to run the tests, you will need [mocha](https://npmjs.org/package/mocha) and
-[should](https://npmjs.org/package/should).
+## Usage
 
-synopsis
---------
+### Basic Setup
 
-client-certificate-auth provides HTTP middleware for Node.js (in particular
-Connect/Express) to require that a valid, verifiable client SSL certificate is
-provided, and passes information about that certificate to a callback which must
-return `true` for the request to proceed; otherwise, the client is considered 
-unauthorized and the request is aborted.
+Configure your HTTPS server to request and validate client certificates:
 
-usage
------
+```javascript
+import express from 'express';
+import https from 'node:https';
+import fs from 'node:fs';
+import clientCertificateAuth from 'client-certificate-auth';
 
-The https server must be set up to request a client certificate and validate it 
-against an issuer/CA certificate. What follows is a typical example using
-[Express](http://expressjs.com):
+const app = express();
 
-```javascript
-var express = require('express');
-var fs = require('fs');
-var https = require('https');
-var clientCertificateAuth = require('client-certificate-auth');
+// Validate certificate against your authorization rules
+const checkAuth = (cert) => {
+  return cert.subject.CN === 'trusted-client';
+};
+
+// Apply to all routes
+app.use(clientCertificateAuth(checkAuth));
+
+app.get('/', (req, res) => {
+  res.send('Authorized!');
+});
 
-var opts = {
-  // Server SSL private key and certificate
+// HTTPS server configuration
+const opts = {
   key: fs.readFileSync('server.key'),
   cert: fs.readFileSync('server.pem'),
-  // issuer/CA certificate against which the client certificate will be
-  // validated. A certificate that is not signed by a provided CA will be
-  // rejected at the protocol layer.
-  ca: fs.readFileSync('cacert.pem'),
-  // request a certificate, but don't necessarily reject connections from
-  // clients providing an untrusted or no certificate. This lets us protect only
-  // certain routes, or send a helpful error message to unauthenticated clients.
-  requestCert: true,
-  rejectUnauthorized: false
+  ca: fs.readFileSync('ca.pem'),       // CA that signed client certs
+  requestCert: true,                    // Request client certificate
+  rejectUnauthorized: false             // Let middleware handle errors
 };
 
-var app = express();
+https.createServer(opts, app).listen(443);
+```
 
-// add clientCertificateAuth to the middleware stack, passing it a callback
-// which will do further examination of the provided certificate.
-app.use(clientCertificateAuth(checkAuth));
-app.use(app.router);
-app.use(function(err, req, res, next) { console.log(err); next(); });
+### Per-Route Protection
 
-app.get('/', function(req, res) {
-  res.send('Authorized!');
+```javascript
+app.get('/public', (req, res) => {
+  res.send('Hello world');
 });
 
-var checkAuth = function(cert) {
- /*
-  * allow access if certificate subject Common Name is 'Doug Prishpreed'.
-  * this is one of many ways you can authorize only certain authenticated
-  * certificate-holders; you might instead choose to check the certificate
-  * fingerprint, or apply some sort of role-based security based on e.g. the OU
-  * field of the certificate. You can also link into another layer of
-  * auth or session middleware here; for instance, you might pass the subject CN
-  * as a username to log the user in to your underlying authentication/session
-  * management layer.
-  */
-  return cert.subject.CN === 'Doug Prishpreed';
+app.get('/admin', clientCertificateAuth(checkAuth), (req, res) => {
+  res.send('Hello admin');
+});
+```
+
+### Async Authorization
+
+```javascript
+const checkAuth = async (cert) => {
+  const user = await db.findByFingerprint(cert.fingerprint);
+  return user !== null;
 };
 
-https.createServer(opts, app).listen(4000);
+app.use(clientCertificateAuth(checkAuth));
 ```
 
-Or secure only certain routes:
+### Custom Error Messages
+
+Throw errors for granular authorization feedback instead of returning `false`:
 
 ```javascript
-app.get('/unsecure', function(req, res) {
-  res.send('Hello world');
+const checkAuth = (cert) => {
+  if (isRevoked(cert.serialNumber)) {
+    throw new Error('Certificate has been revoked');
+  }
+  if (!allowlist.includes(cert.fingerprint)) {
+    throw new Error('Certificate not in allowlist');
+  }
+  return true;
+};
+
+// Thrown errors are passed to Express error handlers with:
+// - error.message = your custom message
+// - error.status = 401 (unless you set a different status)
+```
+
+To use a different status code, set it on the error before throwing:
+
+```javascript
+const err = new Error('Access forbidden');
+err.status = 403;
+throw err;
+```
+
+## API
+
+### `clientCertificateAuth(callback, options?)`
+
+Returns Express middleware.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `callback` | `(cert) => boolean \| Promise<boolean>` | Receives the client certificate, 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'` |
+| `options.fallbackToSocket` | `boolean` | If header extraction fails, try `socket.getPeerCertificate()` (default: `false`) |
+| `options.includeChain` | `boolean` | If `true`, include full certificate chain via `cert.issuerCertificate` (default: `false`) |
+| `options.verifyHeader` | `string` | Header name containing verification status from proxy (e.g., `'X-SSL-Client-Verify'`) |
+| `options.verifyValue` | `string` | Expected value indicating successful verification (e.g., `'SUCCESS'`) |
+
+**Certificate Object:**
+
+The `cert` parameter contains fields from [`tls.PeerCertificate`](https://nodejs.org/api/tls.html#certificate-object):
+
+- `subject.CN` - Common Name
+- `subject.O` - Organization
+- `issuer` - Issuer information
+- `fingerprint` - Certificate fingerprint
+- `valid_from`, `valid_to` - Validity period
+- `issuerCertificate` - Issuer's certificate (only when `includeChain: true`)
+
+### Accessing the Certificate
+
+After authentication, the certificate is attached to `req.clientCertificate` for downstream handlers:
+
+```javascript
+app.use(clientCertificateAuth(checkAuth));
+
+app.get('/whoami', (req, res) => {
+  res.json({
+    cn: req.clientCertificate.subject.CN,
+    fingerprint: req.clientCertificate.fingerprint
+  });
 });
+```
+
+The certificate is attached before the authorization callback runs, so it's available even if authorization fails (useful for logging).
 
-app.get('/secure', clientCertificateAuth(checkAuth), function(req, res) {
-  res.send('Hello authorized user');
+### Certificate Chain Access
+
+For enterprise PKI scenarios, you may need to inspect intermediate CAs or the root CA:
+
+```javascript
+app.use(clientCertificateAuth((cert) => {
+  // Check issuer's organization
+  if (cert.issuerCertificate) {
+    return cert.issuerCertificate.subject.O === 'Trusted Root CA';
+  }
+  return false;
+}, { includeChain: true }));
+```
+
+When `includeChain: true`, the certificate object includes `issuerCertificate` linking to the issuer's certificate (and so on up the chain). This works consistently for both socket-based and header-based extraction.
+
+### User Login
+
+Client certificates provide cryptographically-verified identity, making them ideal for user authentication. Map certificate fields to user accounts in your database:
+
+```javascript
+app.use(clientCertificateAuth(async (cert) => {
+  // Option 1: Lookup by fingerprint (most secure - immutable per certificate)
+  const user = await db.users.findOne({ certFingerprint: cert.fingerprint });
+  
+  // Option 2: Lookup by email (from subject or SAN)
+  // const user = await db.users.findOne({ email: cert.subject.emailAddress });
+  
+  // Option 3: Lookup by Common Name
+  // const user = await db.users.findOne({ certCN: cert.subject.CN });
+  
+  if (!user) {
+    throw new Error('Certificate not registered to any user');
+  }
+  
+  return true;
+}));
+```
+
+To make the user available to downstream handlers, attach it to the request:
+
+```javascript
+app.use(clientCertificateAuth(async (cert, req) => {
+  const user = await db.users.findOne({ certFingerprint: cert.fingerprint });
+  if (!user) throw new Error('Unknown certificate');
+  
+  req.user = user;  // Attach for downstream routes
+  return true;
+}));
+
+app.get('/profile', (req, res) => {
+  res.json({ 
+    name: req.user.name,
+    certificateCN: req.clientCertificate.subject.CN 
+  });
 });
 ```
 
-`checkAuth` can also be asynchronous:
+**Lookup strategies:**
+
+| Field | Pros | Cons |
+|-------|------|------|
+| `fingerprint` | Unique, immutable | Must register each cert |
+| `subject.emailAddress` | Human-readable | Ensure uniqueness |
+| `subject.CN` | Simple to configure | May not be unique |
+| `serialNumber` + issuer | Traceable to your CA | More complex queries |
+
+## Reverse Proxy / Load Balancer Support
+
+When your application runs behind a TLS-terminating reverse proxy, the client certificate is available via HTTP headers instead of the TLS socket. This middleware supports reading certificates from headers for common proxies.
+
+### Using Presets
+
+For common proxies, use the `certificateSource` option:
+
+```javascript
+// AWS Application Load Balancer
+app.use(clientCertificateAuth(checkAuth, {
+  certificateSource: 'aws-alb'
+}));
+
+// Envoy / Istio
+app.use(clientCertificateAuth(checkAuth, {
+  certificateSource: 'envoy'
+}));
+
+// Cloudflare
+app.use(clientCertificateAuth(checkAuth, {
+  certificateSource: 'cloudflare'
+}));
+
+// Traefik
+app.use(clientCertificateAuth(checkAuth, {
+  certificateSource: 'traefik'
+}));
+```
+
+### Preset Details
+
+| Preset | Header | Encoding |
+|--------|--------|----------|
+| `aws-alb` | `X-Amzn-Mtls-Clientcert` | URL-encoded PEM (AWS variant) |
+| `envoy` | `X-Forwarded-Client-Cert` | XFCC structured format |
+| `cloudflare` | `Cf-Client-Cert-Der-Base64` | Base64-encoded DER |
+| `traefik` | `X-Forwarded-Tls-Client-Cert` | Base64-encoded DER |
+
+### Custom Headers
+
+For nginx, HAProxy, Google Cloud Load Balancer, or other proxies with configurable headers:
+
+```javascript
+// nginx with $ssl_client_escaped_cert
+app.use(clientCertificateAuth(checkAuth, {
+  certificateHeader: 'X-SSL-Whatever-You-Use',
+  headerEncoding: 'url-pem'
+}));
+
+// Google Cloud Load Balancer (RFC 9440)
+app.use(clientCertificateAuth(checkAuth, {
+  certificateHeader: 'X-SSL-Whatever-You-Use',
+  headerEncoding: 'rfc9440'
+}));
+
+// HAProxy with base64 DER
+app.use(clientCertificateAuth(checkAuth, {
+  certificateHeader: 'X-SSL-Whatever-You-Use',
+  headerEncoding: 'base64-der'
+}));
+```
+
+### Encoding Formats
+
+| Encoding | Description | Used By |
+|----------|-------------|---------|
+| `url-pem` | URL-encoded PEM certificate | nginx, HAProxy |
+| `url-pem-aws` | URL-encoded PEM (AWS variant, `+` as safe char) | AWS ALB |
+| `xfcc` | Envoy's structured `Key=Value;...` format | Envoy, Istio |
+| `base64-der` | Base64-encoded DER certificate | Cloudflare, Traefik |
+| `rfc9440` | RFC 9440 format: `:base64-der:` | Google Cloud LB |
+
+### Fallback Mode
+
+If your proxy might not always forward certificates (e.g., direct connections bypass the proxy), enable fallback:
+
+```javascript
+app.use(clientCertificateAuth(checkAuth, {
+  certificateSource: 'aws-alb',
+  fallbackToSocket: true  // Try socket if header missing
+}));
+```
+
+### Security Considerations
+
+> ⚠️ **Important:** When using header-based authentication, your reverse proxy **must** strip any incoming certificate headers from external requests to prevent spoofing.
+
+Configure your proxy to:
+1. **Strip** the certificate header from incoming requests
+2. **Set** the header only for authenticated mTLS connections
+3. **Never** trust certificate headers from untrusted sources
+
+#### Verification Header (Defense in Depth)
+
+For additional protection, use `verifyHeader` and `verifyValue` to validate that your proxy has actually verified the certificate. This guards against proxy misconfiguration (e.g., `ssl_verify_client optional` passing unverified certs):
 
 ```javascript
-function checkAuth(cert, callback) {
-  callback(true);
+app.use(clientCertificateAuth(checkAuth, {
+  certificateHeader: 'X-SSL-Client-Cert',
+  headerEncoding: 'url-pem',
+  verifyHeader: 'X-SSL-Client-Verify',
+  verifyValue: 'SUCCESS'
+}));
+```
+
+Example nginx configuration:
+```nginx
+# Strip any existing headers from clients
+proxy_set_header X-SSL-Client-Cert "";
+proxy_set_header X-SSL-Client-Verify "";
+
+# Always send verification status
+proxy_set_header X-SSL-Client-Verify $ssl_client_verify;
+
+# Only send cert if verified
+if ($ssl_client_verify = SUCCESS) {
+    proxy_set_header X-SSL-Client-Cert $ssl_client_escaped_cert;
 }
+```
+
+## Authorization Helpers
+
+Pre-built validation callbacks for common authorization patterns, available as a separate import:
 
-app.use(checkAuth);
+```javascript
+import clientCertificateAuth from 'client-certificate-auth';
+import { allowCN, allowFingerprints, allowIssuer, allOf, anyOf } from 'client-certificate-auth/helpers';
 ```
+
+### Basic Helpers
+
+```javascript
+// Allowlist by Common Name
+app.use(clientCertificateAuth(allowCN(['service-a', 'service-b'])));
+
+// Allowlist by fingerprint
+app.use(clientCertificateAuth(allowFingerprints([
+  'SHA256:AB:CD:EF:...',
+  'AB:CD:EF:...'  // SHA256: prefix optional
+])));
+
+// Allowlist by Organization
+app.use(clientCertificateAuth(allowOrganization(['My Company'])));
+
+// Allowlist by Organizational Unit
+app.use(clientCertificateAuth(allowOU(['Engineering', 'DevOps'])));
+
+// Allowlist by email (checks SAN and subject.emailAddress)
+app.use(clientCertificateAuth(allowEmail(['admin@example.com'])));
+
+// Allowlist by serial number
+app.use(clientCertificateAuth(allowSerial(['01:23:45:67:89:AB:CD:EF'])));
+
+// Allowlist by Subject Alternative Name
+app.use(clientCertificateAuth(allowSAN(['DNS:api.example.com', 'email:service@example.com'])));
+```
+
+### Field Matching
+
+Match certificates by issuer or subject fields (all specified fields must match):
+
+```javascript
+// Match by issuer
+app.use(clientCertificateAuth(allowIssuer({ O: 'My Company', CN: 'Internal CA' })));
+
+// Match by subject
+app.use(clientCertificateAuth(allowSubject({ O: 'Partner Corp', ST: 'California' })));
+```
+
+### Combining Helpers
+
+```javascript
+// AND - all conditions must pass
+app.use(clientCertificateAuth(allOf(
+  allowIssuer({ O: 'My Company' }),
+  allowOU(['Engineering', 'DevOps'])
+)));
+
+// OR - at least one condition must pass
+app.use(clientCertificateAuth(anyOf(
+  allowCN(['admin']),
+  allowOU(['Administrators'])
+)));
+```
+
+### Available Helpers
+
+| Helper | Description |
+|--------|-------------|
+| `allowCN(names)` | Match by Common Name |
+| `allowFingerprints(fps)` | Match by certificate fingerprint |
+| `allowIssuer(match)` | Match by issuer fields (partial) |
+| `allowSubject(match)` | Match by subject fields (partial) |
+| `allowOU(ous)` | Match by Organizational Unit |
+| `allowOrganization(orgs)` | Match by Organization |
+| `allowSerial(serials)` | Match by serial number |
+| `allowSAN(values)` | Match by Subject Alternative Name |
+| `allowEmail(emails)` | Match by email (SAN or subject) |
+| `allOf(...callbacks)` | AND combinator |
+| `anyOf(...callbacks)` | OR combinator |
+
+## TypeScript
+
+Types are included:
+
+```typescript
+import clientCertificateAuth from 'client-certificate-auth';
+import type { ClientCertRequest } from 'client-certificate-auth';
+import type { PeerCertificate } from 'tls';
+
+const checkAuth = (cert: PeerCertificate): boolean => {
+  return cert.subject.CN === 'admin';
+};
+
+app.use(clientCertificateAuth(checkAuth));
+
+// Access certificate in downstream handlers
+app.get('/whoami', (req: ClientCertRequest, res) => {
+  res.json({ cn: req.clientCertificate?.subject.CN });
+});
+
+// With reverse proxy
+app.use(clientCertificateAuth(checkAuth, {
+  certificateSource: 'aws-alb'
+}));
+```
+
+## CommonJS
+
+```javascript
+const clientCertificateAuth = require('client-certificate-auth');
+
+app.use(clientCertificateAuth((cert) => cert.subject.CN === 'admin'));
+```
+
+## Security Notes
+
+- Set `rejectUnauthorized: false` on your HTTPS server to let this middleware provide helpful error messages, rather than dropping connections silently
+- **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
+
+## License
+
+MIT © Tony Gies

package/lib/clientCertificateAuth.cjs

@@ -0,0 +1,115 @@
+/*!
+ * client-certificate-auth - CommonJS wrapper
+ * Copyright (C) 2013-2026 Tony Gies
+ * @license MIT
+ */
+
+'use strict';
+
+// Dynamic import of the ES module
+let _default;
+
+async function loadModule() {
+    if (!_default) {
+        const mod = await import('./clientCertificateAuth.js');
+        _default = mod.default;
+    }
+    return _default;
+}
+
+/**
+ * Options not supported by the sync CJS wrapper.
+ * These require the ESM module's async header parsing.
+ */
+const UNSUPPORTED_OPTIONS = [
+    'certificateSource',
+    'certificateHeader',
+    'headerEncoding',
+    'fallbackToSocket',
+    'verifyHeader',
+    'verifyValue'
+];
+
+/**
+ * CommonJS wrapper for client-certificate-auth.
+ * 
+ * This sync wrapper supports socket-based certificate extraction only.
+ * For full features (header-based extraction, reverse proxy support),
+ * use the async loader: `const auth = await require('client-certificate-auth').load();`
+ * 
+ * @param {Function} callback - Validation callback
+ * @param {Object} [options] - Options
+ * @param {boolean} [options.includeChain=false] - Include certificate chain
+ * @returns {Function} Express middleware
+ * @throws {Error} If unsupported options are passed
+ */
+function clientCertificateAuth(callback, options = {}) {
+    // Validate that no unsupported options are passed
+    const used = UNSUPPORTED_OPTIONS.filter(k => k in options);
+    if (used.length) {
+        throw new Error(
+            `CJS sync wrapper does not support: ${used.join(', ')}. ` +
+            'Use require(...).load() for full features.'
+        );
+    }
+
+    const { includeChain = false } = options;
+
+    return function middleware(req, res, next) {
+        // Ensure that the certificate was validated at the protocol level
+        if (!req.socket?.authorized) {
+            const authError = req.socket?.authorizationError || 'unknown';
+            const e = new Error(`Unauthorized: Client certificate required (${authError})`);
+            e.status = 401;
+            return next(e);
+        }
+
+        // Obtain certificate details
+        const cert = req.socket.getPeerCertificate(includeChain);
+        if (!cert || Object.keys(cert).length === 0) {
+            const e = new Error(
+                'Client certificate was authenticated but certificate information could not be retrieved.'
+            );
+            e.status = 500;
+            return next(e);
+        }
+
+        // Attach certificate to request for downstream access
+        req.clientCertificate = cert;
+
+        function doneAuthorizing(authorized) {
+            if (authorized) {
+                return next();
+            } else {
+                const e = new Error('Unauthorized');
+                e.status = 401;
+                return next(e);
+            }
+        }
+
+        try {
+            const result = callback(cert);
+            if (result instanceof Promise) {
+                result.then(doneAuthorizing).catch((err) => {
+                    if (err.status === undefined) {
+                        err.status = 401;
+                    }
+                    next(err);
+                });
+            } else {
+                doneAuthorizing(result);
+            }
+        } catch (err) {
+            if (err.status === undefined) {
+                err.status = 401;
+            }
+            next(err);
+        }
+    };
+}
+
+module.exports = clientCertificateAuth;
+module.exports.default = clientCertificateAuth;
+
+// Also expose async loader for those who want the ES module (full features)
+module.exports.load = loadModule;