Hardening the JavaScript Registry: A Zero-Trust Architecture Against Package Poisoning

Current Situation Analysis

The JavaScript ecosystem has shifted from a code-quality problem to a pipeline-security problem. For years, teams focused on static analysis, dependency CVE scanning, and runtime sandboxing. Meanwhile, the actual attack surface migrated to the boundaries between version control, continuous integration, and package registries. The npm registry operates on a trust model that assumes published artifacts are clean and installation scripts are benign. That assumption is no longer viable.

The May 2026 TanStack campaign demonstrated how quickly a single pipeline misconfiguration can cascade into a registry-wide incident. Attackers submitted a standard pull request, triggered a CI workflow, and extracted the GitHub Actions cache write token. They used that token to inject malicious payloads into the shared build cache. When the official release workflow later consumed the cache, it compiled and published 84 compromised versions across 42 packages. The payload executed during the prepare lifecycle hook, exfiltrating AWS credentials, GCP tokens, Kubernetes secrets, and SSH keys from every developer who installed the affected versions.

This vector is frequently misunderstood because teams treat CI, publishing, and installation as isolated phases. In reality, they form a continuous trust chain. A compromised cache token enables artifact poisoning. A long-lived registry token enables silent publishing. Unrestricted lifecycle scripts enable immediate execution. When these weaknesses intersect, the blast radius expands from a single repository to every downstream consumer.

Data from 2025 and 2026 shows hundreds of npm packages compromised through similar vectors: cache poisoning, tag-swap attacks on GitHub Actions, fork PR secret leakage, and malicious postinstall/prepare scripts. The common denominator is not sophisticated exploit code, but predictable pipeline configurations that grant excessive permissions, mutable references, and unscoped execution contexts.

WOW Moment: Key Findings

The critical insight is that supply chain security is not a single control, but a layered containment strategy. Traditional setups leave multiple attack vectors open simultaneously. A zero-trust pipeline architecture collapses the blast radius by enforcing strict boundaries at each phase.

Approach	Credential Blast Radius	Attack Vector Coverage	Mean Time to Contain
Traditional CI/CD	Full registry + all downstream installs	Cache, tokens, scripts, tags, forks	48-72 hours (manual revocation)
Zero-Trust Pipeline	Scoped to single workflow run	Blocked at 6+ independent layers	<15 minutes (automated quarantine)

This finding matters because it shifts security from reactive patching to proactive containment. When each layer operates independently, compromising one component does not cascade. The OIDC exchange prevents token theft. Staged publishing prevents silent releases. Script allowlisting prevents execution. SHA pinning prevents tag swaps. Secret isolation prevents fork leakage. Freshness policies delay malicious adoption. Together, they transform a single point of failure into a distributed defense grid.

Core Solution

The architecture below implements eight independent controls. Each control addresses a specific failure mode. The implementation uses modern tooling, explicit permissions, and deterministic references.

Phase 1: Publish with Short-Lived Identity

Long-lived registry tokens are the highest-value target in npm supply chain attacks. Once stolen, they enable silent publishing of malicious code. The solution replaces static secrets with short-lived OIDC tokens issued at publish time.

Architecture Decision: Use npm Trusted Publisher with GitHub Actions OIDC. This eliminates stored secrets entirely. npm validates the token against the repository, branch, and workflow file before granting publish rights.

# .github/workflows/publish.yml
name: Publish Package
on:
  push:
    branches: [main]

permissions:
  id-token: write
  contents: read

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - uses: actions/setup-node@48b55a... # v6
        with:
          node-version: 20
          registry-url: 'https://registry.npmjs.org'

      - name: Install dependencies
        run: npm ci --ignore-scripts

      - name: Build artifacts
        run: npm run build

      - name: Publish to registry
        run: npm publish --provenance
        env:
          NODE_AUTH_TOKEN: '' # OIDC handles authentication

Rationale: The id-token: write permission requests a short-lived JWT from GitHub's OIDC provider. npm verifies the JWT signature, repository ownership, and workflow path. If the workflow is compromised, the token expires within minutes and cannot be reused. The explicit empty NODE_AUTH_TOKEN prevents accidental fallback to legacy authentication.

Phase 2: Enforce Human Approval Gates

Automated publishing removes human oversight. Even with OIDC, a compromised pipeline could publish malicious code automatically. Staged publishing introduces a mandatory review step before artifacts reach the public registry.

Architecture Decision: Separate build and publish phases. CI stages packages to a holding area. Maintainers review diffs, verify signatures, and approve with 2FA.

// scripts/stage-release.ts
import { execSync } from 'child_process';
import { readFileSync } from 'fs';
import { join } from 'path';

const PACKAGES = ['core', 'cli', 'utils'];

for (const pkg of PACKAGES) {
  const manifest = JSON.parse(
    readFileSync(join('packages', pkg, 'package.json'), 'utf-8')
  );
  
  const currentVersion = manifest.version;
  const registryCheck = execSync(
    `npm view @acme/${pkg}@${currentVersion} version 2>/dev/null || echo "not-found"`,
    { encoding: 'utf-8' }
  ).trim();

  if (registryCheck === currentVersion) {
    console.log(`@acme/${pkg}@${currentVersion} already published. Skipping.`);
    continue;
  }

  console.log(`Staging @acme/${pkg}@${currentVersion}...`);
  execSync(`cd packages/${pkg} && npm pack --dry-run`, { stdio: 'inherit' });
  execSync(`cd packages/${pkg} && npm publish --tag staging`, { stdio: 'inherit' });
}

console.log('All packages staged. Awaiting manual approval via registry dashboard.');

Rationale: The staging tag isolates unreviewed artifacts. Maintainers verify the package contents, run local tests, and promote to latest only after approval. This breaks the automation chain that attackers rely on for silent distribution.

Phase 3: Restrict Lifecycle Script Execution

Most supply chain payloads execute during dependency installation. The postinstall and prepare hooks run automatically, making them ideal delivery mechanisms. Blocking all scripts by default and explicitly allowing only verified packages eliminates this vector.

Architecture Decision: Use .npmrc to disable scripts globally. Override only for native modules that require compilation.

# .npmrc
ignore-scripts=true

// package.json
{
  "name": "@acme/registry-tools",
  "version": "1.2.0",
  "pnpm": {
    "onlyBuiltDependencies": [
      "esbuild",
      "sharp",
      "@swc/core"
    ]
  }
}

Rationale: Native modules like esbuild and sharp require binary compilation during installation. The onlyBuiltDependencies field explicitly permits their lifecycle scripts while blocking everything else. This reduces the execution surface from hundreds of dependencies to a verified subset.

Phase 4: Immutable Workflow References

GitHub Actions tags are mutable. An attacker with repository write access can move v4 to point at malicious code. Every workflow using @v4 executes the compromised version.

Architecture Decision: Pin all actions to full commit SHAs. Maintain version comments for dependency update tools.

# Before: Mutable tag
- uses: actions/checkout@v4

# After: Immutable reference
- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4

Rationale: SHAs are cryptographically immutable. Even if the upstream repository is compromised, the workflow continues using the verified commit. Tools like Dependabot or Renovate can still propose SHA updates via pull requests, maintaining maintainability without sacrificing immutability.

Phase 5: Secret Boundary Enforcement

Fork pull requests should never access production secrets. The TanStack attack succeeded because the PR workflow inherited cache write tokens and environment variables.

Architecture Decision: Separate PR and push workflows. Restrict secret-dependent jobs to push events. Add explicit fork validation.

# .github/workflows/ci.yml
name: Continuous Integration
on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  dependency-review:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
      - uses: actions/dependency-review-action@v4

  security-scan:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
      - name: Run static analysis
        run: npm run lint:security
        env:
          SCAN_API_KEY: ${{ secrets.SECURITY_SCAN_KEY }}

Rationale: The if condition ensures secret-dependent jobs only run on trusted branches. Fork PRs execute read-only checks without access to tokens or keys. This prevents cache poisoning and credential exfiltration at the source.

Phase 6: Freshness Policy Enforcement

Malicious packages often target early adopters. A freshness policy delays adoption of newly published versions, giving the community time to detect and report anomalies.

Architecture Decision: Configure a minimum release age in .npmrc.

# .npmrc
min-release-age=7

Rationale: The package manager rejects any version published less than 7 days ago. This creates a detection window. The tradeoff is delayed adoption of urgent security patches. For most projects, the supply chain protection outweighs the patch latency. Teams can override this policy for critical CVEs using explicit version pins.

Phase 7: Automated Verification Pipeline

Static checks and manual reviews are insufficient. Automated scanning must run at every stage: PR, push, and publish.

Architecture Decision: Integrate multiple scanning tools with complementary coverage.

Tool	Trigger	Coverage
Socket.dev	Pull Request	Malicious patterns, obfuscated code, typosquatting
pnpm audit	Pull Request	Known CVEs in production dependencies
CodeQL	Push to main	Injection, auth bypass, data flow analysis
Dependency Review	Pull Request	License compliance, new dependency risk

Rationale: Each tool operates at a different abstraction level. Socket.dev catches behavioral anomalies. pnpm audit tracks known vulnerabilities. CodeQL analyzes source code patterns. Dependency Review enforces policy. Together, they cover the full spectrum from dependency metadata to runtime behavior.

Phase 8: Provenance and Artifact Tracking

Verification requires cryptographic proof of origin. Provenance attestation and Software Bill of Materials (SBOM) provide auditable trails.

Architecture Decision: Enable npm provenance attestation and generate CycloneDX SBOMs on every release.

# Verify package origin
npm audit signatures

# Generate SBOM during CI
npm run sbom:generate -- --output cyclonedx.json

Rationale: Provenance links the published package to the exact GitHub commit, workflow, and runner. SBOMs track every dependency and version included in the build. If a downstream vulnerability emerges, teams can instantly identify affected releases and revoke them.

Pitfall Guide

1. Assuming OIDC Eliminates All Publishing Risks

Explanation: OIDC only secures the authentication handshake. It does not prevent compromised CI pipelines from building malicious artifacts or bypassing review gates. Fix: Combine OIDC with staged publishing, artifact signing, and human approval. Treat OIDC as a credential control, not a complete publishing solution.

2. Over-Allowlisting Lifecycle Scripts

Explanation: Adding too many packages to onlyBuiltDependencies defeats the purpose of ignore-scripts. Attackers frequently compromise popular build tools. Fix: Audit allowlisted packages quarterly. Remove any that no longer require native compilation. Use containerized builds for untrusted dependencies when possible.

3. Pinning SHAs Without Update Automation

Explanation: Immutable references prevent tag-swap attacks but create maintenance debt. Stale action versions miss security patches and feature updates. Fix: Configure Dependabot or Renovate to propose SHA updates via pull requests. Review and merge updates within a defined SLA. Never manually update SHAs without verifying the upstream commit.

4. Running Secret-Dependent Jobs on Fork PRs

Explanation: Fork PRs inherit workflow definitions but should never inherit production secrets. Cache write tokens, API keys, and registry credentials are frequently exfiltrated this way. Fix: Restrict secret access to push events or explicitly validated branches. Use github.event.pull_request.head.repo.full_name == github.repository guards. Never expose secrets to pull_request_target without strict validation.

5. Confusing prepare and postinstall Execution Contexts

Explanation: postinstall runs after installation in consumer projects. prepare runs during local development and publishing. Attackers target both, but they execute in different contexts. Fix: Block both lifecycle hooks by default. Verify native modules require prepare for compilation, not runtime execution. Use npm pack to inspect published artifacts before approval.

6. Treating min-release-age as a Universal Solution

Explanation: Freshness policies delay adoption but break urgent security patching. Enterprise environments with strict compliance requirements may require immediate CVE remediation. Fix: Implement a bypass mechanism for critical vulnerabilities. Use version pins or explicit overrides when CVE severity exceeds a defined threshold. Document the override process for audit compliance.

7. Skipping SBOM Verification in Downstream Projects

Explanation: Generating SBOMs is useless if consumers do not verify them. Teams often publish artifacts without providing attestation data or SBOM archives. Fix: Attach SBOMs as CI artifacts. Publish provenance attestations to the registry. Provide verification commands in documentation. Require SBOM validation in downstream CI pipelines.

Production Bundle

Action Checklist

• Replace NPM_TOKEN with npm Trusted Publisher OIDC configuration
• Implement staged publishing with manual approval gates
• Add ignore-scripts=true to .npmrc and audit allowlisted packages
• Pin all GitHub Actions to commit SHAs with version comments
• Restrict secret-dependent jobs to push events and validate fork origins
• Configure min-release-age=7 in .npmrc with documented override procedures
• Integrate Socket.dev, pnpm audit, CodeQL, and Dependency Review into CI
• Enable provenance attestation and generate CycloneDX SBOMs on release

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Internal enterprise tool	Full zero-trust pipeline + strict freshness policy	High compliance requirements, limited external exposure	Low (internal tooling only)
Public open-source library	OIDC + staged publishing + script allowlisting	Balances security with community contribution velocity	Medium (review overhead)
High-frequency release cycle	OIDC + automated scanning + SBOM tracking	Rapid releases require fast verification without manual gates	Low-Medium (automation investment)
Legacy monorepo migration	Phased rollout: SHA pinning → script blocking → OIDC	Reduces risk incrementally without breaking existing workflows	High (initial refactoring)

Configuration Template

# .github/workflows/pipeline.yml
name: Secure Pipeline
on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

permissions:
  id-token: write
  contents: read

jobs:
  validate:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
      - uses: actions/setup-node@48b55a... # v6
        with:
          node-version: 20
      - run: npm ci --ignore-scripts
      - run: npm run lint
      - run: npm audit --audit-level=high

  build:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
      - uses: actions/setup-node@48b55a... # v6
        with:
          node-version: 20
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci --ignore-scripts
      - run: npm run build
      - run: npm run sbom:generate
      - run: npm publish --provenance --tag staging
        env:
          NODE_AUTH_TOKEN: ''

# .npmrc
ignore-scripts=true
min-release-age=7

// package.json
{
  "pnpm": {
    "onlyBuiltDependencies": ["esbuild", "sharp"]
  }
}

Quick Start Guide

1. Configure OIDC: Navigate to npmjs.com → Package Settings → Trusted Publishers. Add your repository, branch, and workflow file. Delete existing NPM_TOKEN secrets.
2. Update .npmrc: Add ignore-scripts=true and min-release-age=7. Audit dependencies and populate onlyBuiltDependencies in package.json.
3. Pin Actions: Replace all @vX references in workflows with full commit SHAs. Add version comments for update tracking.
4. Restrict Secrets: Move secret-dependent jobs to push events. Add fork validation guards. Verify PR workflows run without credentials.
5. Enable Attestation: Add --provenance to publish commands. Configure SBOM generation in CI. Verify with npm audit signatures after first release.