{"id":18657,"library":"passport-trusted-header","title":"passport-trusted-header","description":"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.","status":"active","version":"1.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/ripjar/passport-trusted-header","tags":["javascript","passport","tls","ssl","client","cert","certificate","auth","authentication"],"install":[{"cmd":"npm install passport-trusted-header","lang":"bash","label":"npm"},{"cmd":"yarn add passport-trusted-header","lang":"bash","label":"yarn"},{"cmd":"pnpm add passport-trusted-header","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required to use the strategy with passport.js","package":"passport","optional":false}],"imports":[{"note":"Package supports both ESM and CJS; named export 'Strategy' is the main class.","wrong":"const Strategy = require('passport-trusted-header').Strategy","symbol":"Strategy","correct":"import { Strategy } from 'passport-trusted-header'"},{"note":"CommonJS require works; if using ESM, use named import.","wrong":"","symbol":"passport-trusted-header","correct":"const Strategy = require('passport-trusted-header').Strategy"},{"note":"No default export; use named import or require with destructuring.","wrong":"import { default as Strategy } from 'passport-trusted-header'","symbol":"default import","correct":"import pkg from 'passport-trusted-header'; const Strategy = pkg.Strategy"}],"quickstart":{"code":"const passport = require('passport');\nconst { Strategy } = require('passport-trusted-header');\n\nconst options = {\n  headers: ['X-Client-DN', 'X-Client-CN']\n};\n\npassport.use(new Strategy(options, (requestHeaders, done) => {\n  const userDn = requestHeaders['X-Client-DN'];\n  const userCn = requestHeaders['X-Client-CN'];\n  // Authentication logic\n  if (userDn === 'CN=test-user') {\n    return done(null, { name: 'Test User' });\n  }\n  return done(null, false);\n}));\n\n// Express example\nconst express = require('express');\nconst app = express();\napp.use(passport.initialize());\napp.get('/login', passport.authenticate('trusted-header', { session: false }), (req, res) => {\n  res.json({ user: req.user });\n});","lang":"javascript","description":"Initializes passport-trusted-header strategy with custom headers and a verify callback; shows Express usage."},"warnings":[{"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.","message":"If the front-end proxy does not whitelist or strip incoming headers, external users can spoof authentication headers.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Ensure the proxy forwards all required headers; maybe include optional headers by separate logic.","message":"All specified headers must be present; otherwise authentication fails. Missing headers cause 401.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Access headers with bracket notation (e.g., requestHeaders['TLS_CLIENT_DN']) and handle missing keys.","message":"The verify callback receives header names in an object, not string values; accessing non-existent headers yields undefined.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"When passReqToCallback: true, use callback signature (req, requestHeaders, done). Otherwise use (requestHeaders, done).","message":"passReqToCallback changes callback signature; mixing up arguments causes runtime errors.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Implement additional security measures: use HTTPS between proxy and app, restrict network access, and validate proxy identity (e.g., shared secret).","message":"The package only extracts headers, does not validate TLS or proxy integrity; security depends entirely on deployment.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"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.","cause":"Strategy name mismatch: passport.authenticate() uses a different name than the strategy's registered name.","error":"Error: Unknown authentication strategy 'trusted-header'"},{"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.","cause":"Request headers object is undefined or missing because the verify callback signature was used incorrectly with passReqToCallback option.","error":"TypeError: Cannot read properties of undefined (reading 'TLS_CLIENT_DN')"},{"fix":"Add a headers array with at least one header name, e.g., { headers: ['X-Client-DN'] }.","cause":"Options object does not include a 'headers' array.","error":"Error: No headers specified for authentication"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}