Registry / auth-security / passport-trusted-header

passport-trusted-header

JSON →
library1.1.0jsnpmunverified

Passport.js strategy for authentication by trusted HTTP headers, typically used when TLS is terminated at a front-end proxy (e.g., nginx). Version 1.1.0 is current, with no recent updates. Key differentiators: specifically for proxied setups, complements passport-client-cert for direct TLS. Security warning about proxy whitelisting is critical; alternatives include passport-client-cert.

auth-securityweb-framework
npm install passport-trusted-header
github ↗package ↗
INSTALL
IMPORT
SIG · PASSPORT-TRUSTED-H
P
passport-trusted-header
auth-securityjavascriptv1.1.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Strategy
✓ import { Strategy } from 'passport-trusted-header'
✗ const Strategy = require('passport-trusted-header').Strategy
Package supports both ESM and CJS; named export 'Strategy' is the main class.
passport-trusted-header
✓ const Strategy = require('passport-trusted-header').Strategy
CommonJS require works; if using ESM, use named import.
default import
✓ import pkg from 'passport-trusted-header'; const Strategy = pkg.Strategy
✗ import { default as Strategy } from 'passport-trusted-header'
No default export; use named import or require with destructuring.

Initializes passport-trusted-header strategy with custom headers and a verify callback; shows Express usage.

const passport = require('passport'); const { Strategy } = require('passport-trusted-header'); const options = { headers: ['X-Client-DN', 'X-Client-CN'] }; passport.use(new Strategy(options, (requestHeaders, done) => { const userDn = requestHeaders['X-Client-DN']; const userCn = requestHeaders['X-Client-CN']; // Authentication logic if (userDn === 'CN=test-user') { return done(null, { name: 'Test User' }); } return done(null, false); })); // Express example const express = require('express'); const app = express(); app.use(passport.initialize()); app.get('/login', passport.authenticate('trusted-header', { session: false }), (req, res) => { res.json({ user: req.user }); });
Debug
Known issues
gotchaIf the front-end proxy does not whitelist or strip incoming headers, external users can spoof authentication headers.
fix
Configure your proxy (e.g., nginx) to set and only accept trusted headers from internal network; ensure no external traffic reaches the Node app directly.
affects: >=0.0.0
gotchaAll specified headers must be present; otherwise authentication fails. Missing headers cause 401.
fix
Ensure the proxy forwards all required headers; maybe include optional headers by separate logic.
affects: >=0.0.0
gotchaThe verify callback receives header names in an object, not string values; accessing non-existent headers yields undefined.
fix
Access headers with bracket notation (e.g., requestHeaders['TLS_CLIENT_DN']) and handle missing keys.
affects: >=0.0.0
gotchapassReqToCallback changes callback signature; mixing up arguments causes runtime errors.
fix
When passReqToCallback: true, use callback signature (req, requestHeaders, done). Otherwise use (requestHeaders, done).
affects: >=0.0.0
gotchaThe package only extracts headers, does not validate TLS or proxy integrity; security depends entirely on deployment.
fix
Implement additional security measures: use HTTPS between proxy and app, restrict network access, and validate proxy identity (e.g., shared secret).
affects: >=0.0.0
Errors
Common errors & fixes
Error: Unknown authentication strategy 'trusted-header'
Strategy name mismatch: passport.authenticate() uses a different name than the strategy's registered name.
fix
Ensure the strategy is registered with the same name: passport.use('trusted-header', new Strategy(...)) or use passport.authenticate('trusted-header'). Default name might be 'trusted-header' if not specified.
TypeError: Cannot read properties of undefined (reading 'TLS_CLIENT_DN')
Request headers object is undefined or missing because the verify callback signature was used incorrectly with passReqToCallback option.
fix
Check passReqToCallback setting: if true, first argument is req, second is headers; if false, first is headers. Access requestHeaders.TLS_CLIENT_DN only after checking it exists.
Error: No headers specified for authentication
Options object does not include a 'headers' array.
fix
Add a headers array with at least one header name, e.g., { headers: ['X-Client-DN'] }.
Upgrade
Version history
1.1.0latest on npm
Audit
Dependencies
passportrequiredPeer dependency required to use the strategy with passport.js
Agent activity
9 hits · last 30 days
node
8
OpenAI (training)
1
Resources
githubhttps://github.com/ripjar/passport-trusted-header ↗
packagehttps://www.npmjs.com/package/passport-trusted-header ↗
passport-trusted-header — npm install passport-trusted-header · libregistry