Registry / http-networking / hpkp

hpkp

JSON →
library3.0.0jsnpmunverified

The `hpkp` package provides HTTP Public Key Pinning (HPKP) middleware for Express and Connect applications. It facilitates adding the `Public-Key-Pins` or `Public-Key-Pins-Report-Only` headers to web responses, which allows sites to declare cryptographic identities for web servers. However, HPKP as a security standard has been widely deprecated by browser vendors, including Chrome, due to significant risks of misuse and the potential for self-inflicted denial-of-service by rendering a website permanently inaccessible to legitimate users. The package is currently at version 3.0.0 and is explicitly in maintenance mode, indicating it will not receive new feature development but will be maintained for critical bug fixes. Developers are strongly advised against implementing HPKP in new projects and should consider alternatives like Certificate Transparency and Expect-CT headers.

http-networkingauth-security
npm install hpkp
github ↗package ↗
INSTALL
IMPORT
SIG · HPKP
H
hpkp
http-networkingjavascriptv3.0.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.

hpkp
✓ import hpkp from 'hpkp'
✗ import { hpkp } from 'hpkp'
The `hpkp` package exports the middleware function as its default export.
hpkp
✓ const hpkp = require('hpkp')
CommonJS import for Node.js environments. This is shown in the official usage example.
HpkpOptions
✓ import type { HpkpOptions } from 'hpkp'
✗ import { HpkpOptions } from 'hpkp'
If using TypeScript, `HpkpOptions` is the interface for the configuration object passed to the `hpkp` middleware. Use `import type` as it's a type-only import.

This quickstart demonstrates how to integrate the `hpkp` middleware into an Express.js application, setting a Public Key Pinning header with example SHA256 hashes and optional configurations. It highlights the use of `maxAge`, `sha256s`, and conditional header setting via `setIf`.

const express = require("express"); const hpkp = require("hpkp"); const app = express(); const ninetyDaysInSeconds = 7776000; // 90 days app.use( hpkp({ maxAge: ninetyDaysInSeconds, sha256s: [ // These should be your actual SPKI hashes for primary and backup keys "AbCdEf123=", "ZyXwVu456=" ], includeSubDomains: true, // optional reportUri: "https://example.com/hpkp-report", // optional reportOnly: false, // optional, set to true for testing // Set the header based on a condition. This is optional. setIf(req, res) { return req.secure; // Only set HPKP for HTTPS requests }, }), ); app.get('/', (req, res) => { res.send('HPKP header should be set if using HTTPS'); }); app.listen(3000, () => { console.log('Server running on port 3000'); console.log('Remember HPKP is deprecated and risky. Use with extreme caution.'); });
Debug
Known issues
deprecatedThe HTTP Public Key Pinning (HPKP) standard itself has been widely deprecated by browser vendors, including Chrome, due to its inherent risks and potential for website self-DDoS.
fix
Avoid using HPKP in new applications. For existing applications, strongly consider migrating to alternative security mechanisms like Certificate Transparency and Expect-CT headers, which offer similar protections with fewer risks.
affects: >=1.0.0
breakingMisconfiguration of HPKP, particularly incorrect `sha256s` or loss of access to pinned keys, can permanently block legitimate users from accessing your website, as their browsers will refuse connections.
fix
Always use `reportOnly: true` and a very short `maxAge` (e.g., 60 seconds) during initial deployment and testing. Ensure robust processes for key rotation and backup key management. Never deploy HPKP without a verified fallback strategy for pin mismatches.
affects: >=1.0.0
gotchaThe `hpkp` package is in maintenance mode and will not receive new feature development. This means it may not adapt to future security best practices or changes in related web standards.
fix
Consider that the underlying technology is no longer actively developed or recommended. If you must use it, be aware of its static nature and potential for obsolescence.
affects: >=3.0.0
gotchaThe `sha256s` array must contain Base64-encoded Subject Public Key Information (SPKI) fingerprints. Using incorrect hash formats or non-SPKI hashes will lead to pinning failures.
fix
Ensure that the provided hashes are correctly derived from the SPKI of your active and backup certificates, and are properly Base64 encoded. Tools are available to generate these from certificate files.
affects: >=1.0.0
gotchaBrowser support for HPKP is inconsistent and has been largely removed. Modern browsers like Chrome have dropped support, rendering the header ineffective for many users.
fix
Before deploying, understand that the impact of HPKP will be limited to older or specific browser versions that still honor the header. The security benefits are minimal given current browser landscape.
affects: >=1.0.0
Errors
Common errors & fixes
NET::ERR_SSL_PINNING_FAILURE
The public key pins declared in the `Public-Key-Pins` HTTP header do not match the public key of the server's certificate presented during a TLS handshake.
fix
During testing, verify `sha256s` values. If in production, and users are locked out, you must either deploy a certificate matching one of the original pinned keys, or if no backup key is available, wait for `maxAge` to expire (which could be months). Using `reportOnly: true` initially can help avoid this.
My HPKP header isn't being set on my Express/Connect application.
The `hpkp` middleware might be placed incorrectly in the middleware chain, or the `setIf` option is preventing it from being applied under current request conditions (e.g., not an HTTPS request).
fix
Ensure the `hpkp` middleware is applied before any routes that should be protected. Check your `setIf` function's logic to confirm it evaluates to `true` for the requests you intend to pin. Verify that `maxAge` is a positive integer.
Upgrade
Version history
3.0.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
13 hits · last 30 days
node
12
OpenAI (training)
1
Resources
githubhttps://github.com/helmetjs/hpkp ↗
packagehttps://www.npmjs.com/package/hpkp ↗