Supply-chain security

Trust, but verify

Supply-chain security is the practice of verifying code you did not write before it can run on your laptop, in CI, in a build tool, or in a user's browser. JavaScript makes reuse easy, so professional teams need habits that keep reuse from becoming blind trust.

This lesson builds on npm & package.json for semver, lockfiles, and lifecycle scripts. It also links back to transpilers and polyfills because the 2024 Polyfill.io incident turned a compatibility CDN into a supply-chain warning. You will also see why bundlers, the concurrent Web Crypto lesson, text encoding, and XSS defenses matter here.

The chain is bigger than the packages you import directly. It includes your direct dependencies, their dependencies, build tools, package registries, CI images, release tokens, lockfiles, CDNs, browser-loaded scripts, and the people or bots allowed to publish any of those pieces.

Transitive dependencies dominate because every direct package can bring its own tree. In this checkout, a script over the root package-lock.json counts 611 package entries excluding the root project, but only 35 unique direct dependency names across the workspace manifests recorded in that lockfile. That gap is why lockfiles, review tools, and fewer dependencies matter.

1const fs = require("node:fs");2const lock = JSON.parse(fs.readFileSync("package-lock.json", "utf8"));3const entries = Object.entries(lock.packages ?? {});4const lockfilePackageEntries = entries.filter(([path]) => path !== "").length;5const workspaces = entries.filter(([path, entry]) =>6  path !== "" && !path.startsWith("node_modules/") && entry.name7);8const direct = new Set();9for (const [, entry] of workspaces) {10  for (const bucket of ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"]) {11    for (const name of Object.keys(entry[bucket] ?? {})) direct.add(name);12  }13}14console.log(lockfilePackageEntries + " lockfile package entries");15console.log(direct.size + " direct dependency names across workspace manifests");

These incidents are not trivia. Each one teaches a different failure mode: availability, maintainer transfer, account hijack, protestware, long social engineering, CDN ownership, phishing, and install-time worm behavior.

The xz-utils backdoor was not an npm package, but it is essential for JavaScript developers because build systems rely on operating-system libraries, CI images, and maintainers you may never see. The Shai-Hulud reports matter because a package install can run code before your app starts; stolen npm, GitHub, or cloud credentials can then publish more compromised packages.

npm audit compares your resolved dependency graph with published advisories. It reports severity, vulnerable paths, patched versions, and sometimes fix commands. It does not know about a brand-new hijack before an advisory exists, and it can be noisy when a vulnerable package is unreachable in your app or only used by development tooling.

1npm audit --audit-level=high2npm audit fix3npm audit fix --force4npm ci5npm install --ignore-scripts

Use npm audit fix for reviewed patch-level or compatible updates. Treat npm audit fix --force as a migration, because it may cross major versions or replace packages in ways that require tests and code review. Use npm ci in CI so the lockfile is the source of truth; it refuses drift between package.json and package-lock.json.

Lockfiles do not remove risk. They record exact versions and integrity hashes so the same graph installs again. Pinning every dependency exactly can reduce surprise but makes updates harder to receive. Semver ranges plus a committed lockfile are the common app trade-off: development can update intentionally, CI repeats exactly, and review tools open explicit changes.

Subresource Integrity, or SRI, lets HTML say “download this external file only if its bytes hash to this exact value.” It is most useful for versioned CDN assets that should be immutable. The browser fetches the file, computes the declared hash, compares it with the integrity attribute, and refuses to execute or apply the resource on mismatch.

1<script2  src="https://cdn.example.com/app.v1.js"3  integrity="sha384-Tf2FyVXw3trfCQ/AHspPELVdH6/5BICrCwHkiQtu+pcIUQZpzFtsc+Fajj2ob/4e"4  crossorigin="anonymous"5></script>

1async function computeSriHash(source) {2  const bytes = new TextEncoder().encode(source);3  const digest = await crypto.subtle.digest("SHA-384", bytes);4  const base64 = btoa(String.fromCharCode(...new Uint8Array(digest)));5  return `sha384-${base64}`;6}7 8const file = 'console.log("CompleteFrontend");\n';Run9computeSriHash(file).then(console.log);

1async function computeSriHash(source) {2  const bytes = new TextEncoder().encode(source);3  const digest = await crypto.subtle.digest("SHA-384", bytes);4  const base64 = btoa(String.fromCharCode(...new Uint8Array(digest)));5  return `sha384-${base64}`;6}7 8const file = 'console.log("CompleteFrontend");\n';9computeSriHash(file).then(console.log);

The crossorigin="anonymous" attribute lets the browser perform the CORS-enabled fetch needed for many cross-origin integrity checks without sending credentials. If the CDN changes a byte, the hash changes and the browser fails closed. That is why SRI does not fit resources that intentionally change behind the same URL, such as a live latest.js endpoint or the old Polyfill.io style of generating different code per request.

Typosquatting registers a name that looks like the package you meant: loadsh instead of lodash, a swapped letter, a missing scope, or a lookalike word. Dependency confusion is different: internal package names accidentally resolve from a public registry, often because private scopes or registry rules are not configured clearly.

1const popularPackages = ["lodash", "react", "express", "next", "axios"];2function normalizePackageName(name) {3  return name.toLowerCase().replace(/^@[^/]+[/]/, "").replace(/[^a-z0-9]/g, "");4}5function levenshteinDistance(left, right) {6  const previous = Array.from({ length: right.length + 1 }, (_, index) => index);7  for (let row = 1; row <= left.length; row += 1) {8    const current = [row];9    for (let column = 1; column <= right.length; column += 1) {10      const cost = left[row - 1] === right[column - 1] ? 0 : 1;11      current[column] = Math.min(current[column - 1] + 1, previous[column] + 1, previous[column - 1] + cost);12    }13    previous.splice(0, previous.length, ...current);14  }15  return previous[right.length];16}17function checkSuspiciousPackageName(candidate) {18  const normalized = normalizePackageName(candidate);19  const closest = popularPackages20    .map((packageName) => ({ packageName, distance: levenshteinDistance(normalized, normalizePackageName(packageName)) }))21    .sort((left, right) => left.distance - right.distance)[0];22  const suspicious = closest.distance > 0 && closest.distance <= 2;23  return { candidate, closest: closest.packageName, distance: closest.distance, suspicious };24}25console.log(JSON.stringify(checkSuspiciousPackageName("loadsh")));

1const popularPackages = ["lodash", "react", "express", "next", "axios"];Run2function normalizePackageName(name) {3  return name.toLowerCase().replace(/^@[^/]+[/]/, "").replace(/[^a-z0-9]/g, "");4}5function levenshteinDistance(left, right) {6  const previous = Array.from({ length: right.length + 1 }, (_, index) => index);7  for (let row = 1; row <= left.length; row += 1) {8    const current = [row];9    for (let column = 1; column <= right.length; column += 1) {10      const cost = left[row - 1] === right[column - 1] ? 0 : 1;11      current[column] = Math.min(current[column - 1] + 1, previous[column] + 1, previous[column - 1] + cost);12    }13    previous.splice(0, previous.length, ...current);14  }15  return previous[right.length];16}17function checkSuspiciousPackageName(candidate) {18  const normalized = normalizePackageName(candidate);19  const closest = popularPackages20    .map((packageName) => ({ packageName, distance: levenshteinDistance(normalized, normalizePackageName(packageName)) }))21    .sort((left, right) => left.distance - right.distance)[0];22  const suspicious = closest.distance > 0 && closest.distance <= 2;23  return { candidate, closest: closest.packageName, distance: closest.distance, suspicious };24}25console.log(JSON.stringify(checkSuspiciousPackageName("loadsh")));

Scoped packages reduce ambiguity when the organization controls the scope and every tool uses the same registry mapping. Put private packages behind a private scope and configure npm so @acme/* goes to the private registry instead of the public default.

1@acme:registry=https://npm.acme.internal/2//npm.acme.internal/:_authToken=${NPM_TOKEN}3always-auth=true

Slopsquatting is the AI-era cousin of typosquatting: attackers register package names that coding assistants are likely to hallucinate. Treat generated install commands as suggestions, not facts. Search the registry, read the package page, verify maintainers and source, and ask whether the package should exist at all.

The most reliable dependency is the one you did not need. Modern JavaScript and browsers already provide many APIs that older projects used packages for: fetch, URL, URLSearchParams, Intl, structuredClone, Array.isArray, crypto.subtle, and TextEncoder cover many small helpers.

1const original = { user: { name: "Ada" }, tags: ["security"] };2const copy = structuredClone(original);3copy.tags.push("reviewed");4 5console.log(original.tags.join(", "));6console.log(new URL("/javascript/npm", "https://completefrontend.com").href);7console.log(new Intl.ListFormat("en").format(["fetch", "URL", "structuredClone"]));

1const packageChecklist = {2  name: "left-pad-alternative",3  needed: false,4  maintenance: "last release 3 years ago",5  installScripts: ["postinstall"],6  license: "MIT",7};8 9console.log(packageChecklist.needed ? "review deeply" : "prefer platform code");10console.log(packageChecklist.installScripts.includes("postinstall") ? "inspect scripts" : "no install script");

Vendoring means copying a small, reviewed piece of code into your repository. It can be a good choice for stable, tiny helpers when you want no install-time behavior and no transitive graph. It also makes you responsible for fixes, license compliance, and updates. Depending is better when the library is complex, security-sensitive, actively maintained, and hard to get right yourself.

Tooling and workflow

Tools help when they are used as evidence rather than as autopilot. Dependabot and Renovate open dependency update pull requests. Socket and Snyk add package-risk, malware, reachability, and vulnerability signals. npm provenance and signatures add publish-time evidence when a package and registry support them.

1npm publish --provenance2npm audit signatures

1. Start with need: remove the dependency if a platform API or a few maintained lines solve it.
2. Verify the name, scope, owner, repository, license, release history, and install scripts before first install.
3. Install with a committed lockfile, review the diff, and use npm ci in CI.
4. Run audit and risk tooling, then apply updates through pull requests with tests.
5. Use SRI or self-hosting for browser-loaded third-party assets, and prefer provenance-aware publishing for your own packages.

Common misconceptions

• “npm audit clean means safe.” It means no known advisory matched the resolved graph. It does not prove maintainers, names, scripts, or new releases are safe.
• “A lockfile prevents attacks.” A lockfile prevents accidental drift. It can also preserve a bad version until you update it intentionally.
• “SRI solves all CDN risk.” SRI protects exact bytes for immutable resources. It does not help dynamic resources or a hash copied from already-compromised code.
• “Popular packages are automatically trustworthy.” Popular packages are attractive targets. Popularity is one signal, not a security model.
• “Install scripts are always malicious.” Many are legitimate, especially for native modules. The point is to know when you are running third-party code.
• “AI-generated install commands are facts.” Slopsquatting exists because plausible package names can be hallucinated and then registered by attackers.

Key takeaways

• The supply chain includes dependencies, transitive dependencies, build tools, registries, CDNs, CI, tokens, and publish workflows.
• npm audit reports known advisories; lockfiles and npm ci make installs reproducible, not automatically safe.
• SRI hashes exact CDN bytes with Web Crypto-style algorithms and fails closed on mismatches, but only for immutable resources.
• Typosquatting, dependency confusion, and slopsquatting are name-resolution problems. Verify names, scopes, and registry configuration.
• Fewer, better dependencies are easier to audit. Prefer platform APIs, review install scripts, and use update tooling as evidence.

One-line summary: treat dependency installation and third-party scripts as code review events, then use hashes, lockfiles, provenance, and smaller graphs to make trust verifiable.

Up next: the concurrent isolation and sandboxing lesson shows how to run untrusted code or content with stronger boundaries when verification is not enough.