Authorization Helpers

Pre-built validation callbacks cover common authorization patterns so you don't have to write them from scratch. Import them from the /helpers subpath:

import clientCertificateAuth from 'client-certificate-auth';
import {
  allowCA, allowCN, allowEmail, allowFingerprints, allowIssuer, allowOrganization,
  allowOU, allowSAN, allowSerial, allowSubject, allOf, anyOf
} from 'client-certificate-auth/helpers';
import { readFileSync } from 'node:fs';

CommonJS note

In CommonJS, the /helpers subpath export provides a load() function for async access. See the CommonJS section for details.

Basic Helpers

Each helper returns a callback suitable for passing directly to clientCertificateAuth():

// Allowlist by Common Name
app.use(clientCertificateAuth(allowCN(['service-a', 'service-b'])));

// Allowlist by fingerprint
app.use(clientCertificateAuth(allowFingerprints([
  'SHA256:AB:CD:EF:...',  // matched against cert.fingerprint256
  'AB:CD:EF:...'          // SHA-1, matched against cert.fingerprint
])));

// 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'])));

// Verify the certificate chains to a CA you control (needed behind passthrough proxies)
// The header carries only the public certificate: the app must be reachable only through the proxy.
app.use(clientCertificateAuth(allowCA(readFileSync('ca.pem')), {
  certificateSource: 'aws-alb',
  includeChain: true
}));

allowSAN values without a type prefix match under any SAN type. Matching is case-insensitive except within URIs, where only the scheme and host are folded; userinfo, path, query, and fragment must match exactly.

Field Matching

Match certificates by issuer or subject fields. All specified fields must match for the callback to return true:

// 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

Use allOf and anyOf to compose multiple helpers into a single authorization check:

// 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'])
)));

Both combinators invoke every callback up front and await the results with Promise.all, so a false result or a rejected promise from one callback does not stop the others from running. A synchronous throw does: it interrupts the invocation loop before the remaining callbacks are called.

These combinators accept any number of callbacks, including custom functions, so you can mix helpers with your own logic:

app.use(clientCertificateAuth(allOf(
  allowIssuer({ O: 'My Company' }),
  (cert) => !isRevoked(cert.serialNumber)
)));

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)
allowCA(cas, options?)	Verify the chain against your own CA certificates
allOf(...callbacks)	AND combinator - all must pass
anyOf(...callbacks)	OR combinator - at least one must pass

For full parameter types and return values, see the helpers API reference.