Supply-chain security

Check before you trust

Most JavaScript projects run code that other people wrote. That code comes as packages. A package is a folder of code that someone published so that others can reuse it. A package your project needs is called a dependency.

Supply-chain security means checking outside code before it runs. Outside code can run in four places:

• on your own laptop;
• in CI, the server that tests and builds your project after every change;
• inside a build tool;
• in your user's browser.

JavaScript makes reusing code easy. This lesson shows how to reuse it without trusting it blindly.

This lesson builds on npm & package.json. That lesson explains version ranges, lockfiles, and install scripts. This lesson also links back to transpilers and polyfills. In 2024 a polyfill CDN, Polyfill.io, started sending harmful code to some visitors. You will also see why bundlers, Web Crypto, text encoding, and XSS defenses matter here.

The chain is bigger than the packages you install yourself. It includes:

• direct dependencies, the packages you list in package.json;
• transitive dependencies, the packages that your packages need;
• build tools, registries, and the CI machines that run them;
• tokens, lockfiles, CDNs, and scripts the browser loads;
• the people and bots that are allowed to publish any of these.

The table lists each part. Read across: what the part is, then how you check it.

Most of the chain is transitive dependencies. Each package you add can bring its own packages, and those bring more. This repository shows how big the gap is. A script read the root package-lock.json, the lockfile npm writes. It found:

• 832 package entries, not counting the project itself;
• only 56 different direct dependency names. They come from the 3 projects in the repository, called workspaces, each with its own package.json.

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");

This is a Node.js script, so it does not run in the browser. Here is what its lines do:

• Line 2 reads the lockfile and turns its JSON text into an object.
• Line 4 counts every package entry except the root one, whose path is "".
• Lines 5 to 7 keep the workspace entries: the ones outside node_modules/ that have a name.
• Lines 8 to 13 put every dependency name from those workspaces into a Set. A Set keeps each name only once.
• Lines 14 and 15 print both counts.

Each event below really happened. Each one shows a different way the chain can fail:

• a package disappears, and builds break;
• a new maintainer, the person who looks after a package, adds harmful code;
• an attacker steals a maintainer's account;
• a maintainer breaks their own package on purpose, as a protest;
• an attacker spends years winning a project's trust;
• a CDN gets a new owner;
• phishing, a fake email or page, steals a login;
• a package copies itself to other packages while it installs, like a worm.

Each row is one event. Read when it happened, then what it teaches.

xz-utils is not an npm package. It is a compression library that operating systems use. It still matters to JavaScript developers. Build machines depend on operating-system libraries, CI images, and maintainers you may never meet.

The Shai-Hulud reports matter for another reason. Installing a package can run its code before your app even starts. If that code steals npm, GitHub, or cloud passwords, the attacker can publish more harmful packages.

npm audit checks your installed packages against a list of advisories. An advisory is a public warning that some versions of a package have a security problem. For each match, the report shows:

• how serious the problem is, called its severity;
• which of your packages pulls in the weak one;
• which version fixes it;
• sometimes, a command that applies the fix.

It has two limits:

• It knows nothing about a brand-new attack until someone publishes an advisory.
• It can warn about code your app never runs, or code that only development tools use.

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

These are terminal commands, not browser code. Line by line:

1. npm audit --audit-level=high lists advisories. It fails only when one is high or critical.
2. npm audit fix installs fixed versions that stay inside the version ranges you allow.
3. npm audit fix --force also allows bigger jumps, such as a new major version. Treat it like a move to a new version: review the changes and run your tests.
4. npm ci installs exactly what the lockfile says. It is meant for CI.
5. npm install --ignore-scripts installs without running the packages' install scripts.

npm ci treats the lockfile as the truth:

• It stops with an error if package.json and package-lock.json disagree.
• It deletes the old node_modules folder first.
• It never changes package.json or package-lock.json.

If a setting such as --legacy-peer-deps was used to make the lockfile, CI must use the same setting. Teams usually save it in the project's .npmrc file, npm's settings file.

A lockfile does not remove risk. It records the exact version and an integrity hash of every package, so the same packages install again next time. An integrity hash is a short fingerprint computed from a file's bytes. If any byte changes, the fingerprint changes.

Teams pick one of two ways to set versions:

• Pin every version exactly. You get fewer surprises, but updates take more work.
• Allow a range in package.json, such as ^5.1.0, and commit the lockfile. The ^ means "any 5.x version from 5.1.0 up". This is the usual choice for apps. You update on purpose, CI repeats the lockfile exactly, and update tools open a pull request for each change.

const manifestRange = "^5.1.0";
const lockedVersion = "5.3.2";

console.log(manifestRange + " -> " + lockedVersion);

Line 1 is the range that package.json allows. Line 2 is the one exact version that the lockfile recorded. Line 4 prints ^5.1.0 -> 5.3.2.

The arrow in that output is only text. It is not a real version check. npm checks the real lockfile, and npm ci installs the recorded version without picking a newer one.

An integrity hash catches bytes that differ from the file npm saw when it wrote the lockfile. It does not tell you who wrote those bytes. It also does not tell you whether the package was safe at that moment. So review lockfile changes the way you review code changes. Look closely when a package name, version, download address, or integrity value changes.

npm audit only knows published advisories. It does not scan for malware, and it does not check whether your app really uses the weak code. A clean report means no published advisory matched. It cannot clear a stolen account or a new harmful release. The report also sends your package names to your registry, private names included. Check your company's rules before you run it in CI.

const scripts = { postinstall: "node ./build.js" };
const hookNames = ["preinstall", "install", "postinstall"];
const installHooks = Object.keys(scripts).filter((name) => hookNames.includes(name));

console.log(installHooks.join(", ") || "no install hooks");

This small example prints postinstall. It only reads the script names. It never runs build.js.

• Line 1 is a scripts object, like the one in a package.json. It has one postinstall script.
• Line 2 lists the three script names that npm runs during install.
• Line 3 keeps only the names in scripts that are install scripts.
• Line 5 prints those names, or no install hooks if there are none.

In a real review, also read what the script does, and the files it runs. Then decide whether a normal install is fine.

Some pages load scripts from a CDN. If the CDN's file changes, your page runs the new code without asking you. Subresource Integrity, or SRI, stops that. In the HTML, you write the hash the file should have. The browser then:

1. downloads the file;
2. computes the hash of the bytes it got;
3. compares that hash with the integrity attribute;
4. runs the file only if they match. If they differ, it refuses the file.

The hash method here is SHA-384. It turns any bytes into a 48-byte fingerprint. SRI fits files that should never change, such as a CDN file with its version number in its address.

1<script2  src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/js/bootstrap.bundle.min.js"3  integrity="sha384-FKyoEForCGlyvwx9Hj09JcYn3nv7wiPVlz7YYwJrWVcXK/BmnVDxM+D2scQbITxI"4  crossorigin="anonymous"5></script>

• Line 2 is the file's address. The exact version, 5.3.8, is part of it.
• Line 3 is the expected hash: sha384-, then the fingerprint written in base64. Base64 is a way to write bytes as letters, digits, +, and /.
• Line 4, crossorigin="anonymous", lets the browser check a file from another site. It is explained below.

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);

crossorigin="anonymous" asks the browser to download the file with CORS and without cookies. CORS is the browser's rule for reading files from another site. The browser needs it to check many files that come from other sites.

If the CDN changes even one byte, the hash changes, and the browser refuses the file. So SRI does not fit files that change at the same address. Two examples:

• a latest.js file that always holds the newest version;
• a service like the old Polyfill.io, which built different code for each visitor.

Typosquatting means publishing a package under a name that looks like a popular one. The attacker hopes people will mistype the name. The fake name can be:

• a typo, such as loadsh instead of lodash;
• the right name without its scope;
• a word that looks almost the same.

A scope is the @name/ part at the start of names like @acme/tools. It groups packages under one owner.

Dependency confusion is a different attack. Say your company has a private package for its own use. If npm is not told where that name lives, it may fetch a package with the same name from the public registry instead. An attacker may have published one there on purpose.

Each row below is one attack. Read what goes wrong, then the first defense to use.

The playground below runs a small name checker. It compares the name you type with a list of popular names. It counts edits: how many single letters you must add, remove, or change to turn one name into the other. This count is called the Levenshtein distance.

1const popularPackages = ["lodash", "react", "express", "next", "axios"];2function normalizePackageName(name) {3  return name.toLowerCase().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(/[^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")));

A scope helps when your company owns it and every tool uses the same registry setting. Put private packages under your private scope. Then tell npm to fetch @acme/* from your private registry, not from the public one.

1@acme:registry=https://npm.acme.internal/2//npm.acme.internal/:_authToken=${NPM_TOKEN}

This is npm's settings file, not a shell script.

• Line 1 sends every @acme package to the private registry.
• Line 2 gives the login token for that registry only. The token comes from ${NPM_TOKEN}, an environment variable: a value set outside the code.

Never write the token itself in a file you commit. Check this setting in CI as well as on your laptop.

Slopsquatting is a newer kind of typosquatting. AI coding assistants sometimes make up package names that sound right but do not exist. Attackers then publish packages under those names. So treat an install command from an AI as a suggestion, not a fact. Before you run it:

• search the registry for the name;
• read the package page;
• check who maintains it and where its source code lives;
• ask whether you need a package at all.

The safest dependency is the one you do not need. Browsers and JavaScript now include many tools that older projects installed as packages:

• fetch sends network requests;
• URL and URLSearchParams build and read web addresses;
• Intl formats dates, numbers, and lists for many languages;
• structuredClone makes a deep copy of an object;
• Array.isArray tests whether a value is an array;
• crypto.subtle computes hashes;
• TextEncoder turns text into bytes.

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"]));

• Line 2 makes a deep copy, so line 3 adds "reviewed" to the copy only.
• Line 5 prints security, because the original did not change.
• Line 6 builds a full address: https://completefrontend.com/javascript/npm.
• Line 7 prints fetch, URL, and structuredClone.

Ask the questions in this table before you add a package. Read across: the question, what to look at, and the habit that helps.

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");

• Lines 2 to 6 record what you found about the package.
• Line 9 prints prefer platform code, because needed is false.
• Line 10 prints inspect scripts, because the package has a postinstall script.

Vendoring means copying a small piece of code you have reviewed into your own repository, instead of installing it as a package. It suits small helpers that rarely change. Nothing runs at install time, and no extra packages come along. But the code is now yours: fixes, license rules, and updates are your job.

Install a package instead when the code is large, security-related, well looked after, and hard to get right yourself.

Tools and a review routine

Tools help most when you read what they find, instead of letting them decide for you:

• Dependabot and Renovate open a pull request for each dependency update.
• Socket and Snyk flag risky packages, known malware, and known security problems. Some also check whether your code reaches the weak part.
• npm provenance and registry signatures add proof about how a package was published, when the package and registry support them.

1npm publish --provenance2npm audit signatures

These are terminal commands.

• A registry signature is a mark the registry adds to a package. npm uses it to check that the package's name, version, and hash are what the registry published.
• Provenance is a public record that links a published package to its source repository and to the build that made it.

Line 1 publishes a package with provenance. Line 2, npm audit signatures, checks the signatures and provenance records of your installed packages, where they exist. Neither one proves that the source code is harmless.

1name: Publish package2on:3  release:4    types: [published]5permissions:6  contents: read7jobs:8  publish:9    runs-on: ubuntu-latest10    permissions:11      contents: read12      id-token: write13    steps:14      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.115      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.016        with:17          node-version: 2218          registry-url: https://registry.npmjs.org19      - run: npm ci20      - run: npm publish --provenance --access public

This is a GitHub Actions workflow file, not code you can run here. A GitHub Action is a reusable step that someone else wrote, so it is part of your supply chain too. Line by line:

• Lines 10 to 12 let the job only read the repository, plus id-token: write. That lets it get a short-lived OIDC token for trusted publishing, instead of a saved npm token.
• Lines 14 and 15 pin each action to a full commit SHA: the long ID of one exact version of its code. A tag such as v7 can be moved to other code; a SHA cannot. The comment shows the matching version.
• Line 19 installs exactly what the lockfile says.
• Line 20 publishes the package with provenance.

Read each action's code at that commit. Update the pins through reviewed pull requests, for example ones that Dependabot opens. A pin keeps one version fixed. It does not make that version safe, and you still need to update it.

Each defense in this table catches some problems and misses others. Read across: what it catches, then what it does not catch.

Put together, a review routine looks like this:

1. Start with the need. Skip the package if a built-in tool or a few lines of your own code do the job.
2. Before the first install, check the name, scope, owner, source code, license, past releases, and install scripts.
3. Install with a committed lockfile, read the lockfile changes, and use npm ci in CI.
4. Run npm audit and other risk tools. Apply updates through pull requests, with tests.
5. Pin GitHub Actions to full SHAs you have reviewed. Give workflows the fewest permissions they need. Update pins through reviewed pull requests.
6. Use SRI, or host the file yourself, for scripts the browser loads from other sites. Publish your own packages with provenance.

Common misconceptions

• "A clean npm audit means safe." It means no published advisory matched your packages. It says nothing about owners, names, install scripts, or new releases.
• "A lockfile stops attacks." A lockfile stops surprise version changes. It can also keep a bad version until you update on purpose.
• "SRI solves every CDN risk." SRI protects the exact bytes of a file that never changes. It does not help with files that change, or with a hash copied from a file that was already harmful.
• "Popular packages are safe." Popular packages are attractive to attackers. Popularity is one clue, not proof.
• "Install scripts are always harmful." Many are normal, especially for packages that compile code. The point is to know when you are running someone else's code.
• "An install command from an AI is a fact." AI assistants can make up package names that sound right. Attackers publish packages under those names.

Each row is advice you may hear. Read the question to ask, then a better habit.

Key takeaways

• The supply chain is every package, the packages they bring, build tools, registries, CDNs, CI, tokens, and publish steps.
• npm audit reports published advisories. A lockfile and npm ci make installs repeatable, not safe.
• SRI makes the browser hash a CDN file and refuse it if the hash differs. It only fits files that never change.
• Typosquatting, dependency confusion, and slopsquatting all trick you with a name. Check names, scopes, and registry settings.
• Fewer, better dependencies are easier to check. Use built-in tools, read install scripts, and treat tool results as clues to review.

One-line summary: treat every new package and outside script like a code change you review, and use hashes, lockfiles, provenance, and fewer packages so you can check what you trust.

Up next: the isolation and sandboxing lesson shows how to run code you do not trust behind stronger walls, for the times when checking is not enough.