Documentation as attack surface: npm libraries teaching insecure patterns in README examples

Summary

Across 4 reviews of high-profile npm libraries — totaling ~180 million weekly downloads — I found the same pattern: the library code handles security correctly, but the README teaches developers to copy insecure patterns.

One finding resulted in a GitHub Security Advisory (GHSA-8wrj-g34g-4865) filed at the maintainer's request.

This isn't a bug in any single library. It's a systemic issue in how the npm ecosystem documents security-sensitive operations.

Findings

1. axios — beforeRedirect bypasses credential-stripping (65M weekly downloads)

The README example re-injects credentials via beforeRedirect after follow-redirects deliberately strips them on protocol downgrades (HTTPS→HTTP). The callback fires after the security mechanism (follow-redirects line 478), directly bypassing it.

• CWE: CWE-319 (Cleartext Transmission of Sensitive Information)
• Issue: axios/axios#10614
• Advisory: GHSA-8wrj-g34g-4865
• Fix PR: axios/axios#10624

2. node-jsonwebtoken — Unanchored regex audience matching (76M weekly downloads)

Documentation allows jwt.verify(token, key, { audience: /api\.myapp\.com/ }) without ^/$ anchors. An attacker can bypass with aud: "evil-api.myapp.com.attacker.com".

• Issue: auth0/node-jsonwebtoken#1019

3. cors — Unanchored regex origin validation (25M weekly downloads)

README example /example\.com$/ matches evil-example.com. Combined with credentials: true, allows authenticated CORS access from attacker-controlled domains. The library's own test suite uses the correct pattern.

• Issue: expressjs/cors#408

4. multer — Math.random() for filenames (13.5M weekly downloads)

README's diskStorage example uses Math.random() (~30 bits entropy) while the library's default uses crypto.randomBytes(16) (128 bits). If uploads are web-accessible, filenames can be enumerated.

• Issue: expressjs/multer#1386

The Pattern

Three forces create this systematically:

1. Simplicity bias. README examples optimize for "getting started," not production security. The simplest version is often the insecure version.
2. Documentation lag. Libraries get security hardening over time, but README examples are written once. The code evolves; the docs fossilize.
3. Copy-paste as learning. Developers copy README examples. A library's documentation IS its API for most users. When the docs teach Math.random(), that's what gets deployed.

Potential Actions for the WG

1. Guidance for maintainers. A checklist or section in the WG's best practices on treating README code examples as security-critical code.
2. Documentation security in review processes. Encourage README examples to undergo the same review standards as src/ changes.
3. Security-annotated examples. When a simplified example omits a security property, annotate it: "⚠️ This uses Math.random() for simplicity. In production, use crypto.randomBytes()."
4. Automated documentation linting. Explore running security linters on README code blocks (e.g., if eslint-plugin-security flags Math.random() in source, flag it in docs too).

Methodology

Each library was reviewed by examining README code examples against the library's actual implementation, looking for cases where the documentation teaches a weaker pattern than what the library provides by default. Findings were verified by reading the library source code.

Full review reports and meta-pattern analysis: gist

Start by reviewing the linked library issues, advisories, README examples, and the methodology described in the issue. Decide which WG deliverable is in scope—maintainer guidance, review guidance, annotated examples, or documentation linting—and define completion as an agreed recommendation or proposal with a documented review process.