# Supply-chain security

> Provenance links a package to its build. A 24-hour release-age floor delays new versions, and `ignore-scripts=true` prevents dependency lifecycle scripts from running during installation.

npm worm campaigns ship in waves: `chalk`/`debug` in September 2025, `node-ipc` in May 2026, the @tanstack/* compromise on 2026-05-11. The pattern is consistent: a single phished maintainer or one CI cache-poisoning bug becomes thousands of downstream installs in minutes. DaloyJS is built and shipped with that threat model in mind, and we recommend the same defaults for your project.

## How DaloyJS itself is published

**Diagram: The publish pipeline, tag to tarball**

1. **Signed tag push** (trigger) - release.yml only. Fork PRs can't
2. **Protected environment** (gate) - maintainer approval required
3. **harden-runner egress block** (runner) - npm + GitHub + Sigstore only
4. **OIDC trusted publish** (auth) - no long-lived NPM_TOKEN
5. **--provenance via Sigstore** (attest) - tarball bound to commit + run

Only a signed tag can start a release, and only after maintainer approval on a network-restricted runner. There is no long-lived publish token to steal, and every tarball carries a provenance attestation back to its source commit.

- Releases run in a separate workflow (`release.yml`) that is triggered *only* by a signed tag push and gated by a protected GitHub Environment requiring maintainer approval. Fork PRs cannot touch it.
- npm trusted publishing (OIDC) with `--provenance`: every `@daloyjs/core` tarball is bound to its source commit and workflow run via Sigstore. There is no long-lived `NPM_TOKEN` in repo secrets to steal.
- `id-token: write` is granted only to the publish job, on the post-approval runner, with egress blocked to everything except npm, GitHub, and Sigstore (via `step-security/harden-runner`).
- No GitHub Actions cache in the standard CI workflow. Cache scope bridges fork PRs and pushes to `main`, which is the poisoning channel that bridged TanStack's PR pipeline into its release pipeline.
- No `pull_request_target` that runs fork code. CI uses the safe `pull_request` trigger. The one narrow exception (a workflow that auto-closes external PRs) never checks out, installs, or runs any PR code. A `zizmor` check on every PR fails the build on the dangerous `pull_request_target`-plus-fork-checkout pattern.
- Third-party GitHub Actions are SHA-pinned so a retargeted version tag cannot silently change what CI executes.
- CodeQL, OpenSSF Scorecard, Dependabot all run continuously, and `CODEOWNERS` blocks any change to `.github/`, `package.json`, the lockfile, or `.npmrc` without a maintainer review.
- ClusterFuzzLite continuously fuzzes the untrusted-input parsers with Jazzer.js, on every PR that touches `src/` and again in a daily batch run (see below).
- Lockfile source verification runs in CI via `pnpm verify:lockfile` and fails if `pnpm-lock.yaml` introduces git dependency sources or non-registry tarball URLs.

Full policy and incident-response playbook: [SECURITY.md](https://github.com/daloyjs/daloy/blob/main/SECURITY.md).

## How the framework itself is fuzzed

Beyond static analysis, the untrusted-input parsers in `@daloyjs/core` are continuously fuzzed with [Jazzer.js](https://github.com/CodeIntelligenceTesting/jazzer.js) wired through [ClusterFuzzLite](https://google.github.io/clusterfuzzlite/). A per-PR `code-change` run fuzzes anything that touches `src/`, and a daily batch job fuzzes the full corpus. This is also what earns the OpenSSF Scorecard **Fuzzing** check.

Each target asserts the function's documented contract, not only "does not crash". A declared rejection (for example a `BadRequestError` on malformed input) is correct behavior and is ignored. Any other thrown error, or a hang, is a finding:

- `safeJsonParse`: only throws `BadRequestError`, and never returns an object carrying a `__proto__` / `constructor` / `prototype` own key.
- `readRequestCookie`: never throws while parsing an untrusted `Cookie` header.
- `decodeCursor`: only throws `BadRequestError` on a malformed pagination cursor.
- `parseCron`: only throws `CronParseError`.
- `parseIp`: never throws (returns `undefined` on unrecognized input).
- `sanitizeHeaderName` / `sanitizeHeaderValue`: only throw `BadRequestError`, and an accepted value never contains CR, LF, or NUL.

The harness, including the per-target oracle and the digest-pinned OSS-Fuzz build image, lives in [.clusterfuzzlite/](https://github.com/daloyjs/daloy/tree/main/.clusterfuzzlite).

## Defaults you get from `pnpm create daloy`

Every project scaffolded with `create-daloy` ships with an`.npmrc` and `pnpm-workspace.yaml` that turn on the install-time controls below when you choose `pnpm`. Keep them on.

```ini
# .npmrc, shipped by create-daloy

# Block transitive postinstall/preinstall/prepare hooks, which is the
# execution channel used by chalk/debug, node-ipc, and Shai-Hulud.
ignore-scripts=true

# Wait 24h before resolving a freshly published version. npm worm
# campaigns are typically detected and unpublished within hours.
minimum-release-age=1440

# Reproducible installs.
prefer-frozen-lockfile=true
verify-store-integrity=true
strict-peer-dependencies=true
```

When (and only when) you scaffold with `--package-manager npm`, the CLI adds an `npm >= 12` floor to `engines` and swaps the pnpm `.npmrc` for an npm-native one containing `engine-strict=true`, so npm *refuses* to install on an older CLI instead of only printing a warning. pnpm scaffolds get the equivalent guard: a `pnpm >= 11` floor in `engines.pnpm`, which pnpm always enforces at install time. This matters because pnpm older than 11 silently ignores the `minimumReleaseAge` setting in `pnpm-workspace.yaml`, which disables the 24-hour release-age cooldown. The CLI also warns during scaffolding when the installed pnpm is below the floor. Yarn and Bun scaffolds never run npm or pnpm, so they get neither floor. This keeps npm users on a CLI new enough for the modern lockfile and provenance-verification behavior the project relies on.

## Optional CI bundle for user projects

`create-daloy --with-ci` adds the GitHub-side controls that do not come from a package install: CI with top-level `permissions: {}`, SHA-pinned actions, `harden-runner`, no package-manager cache, disabled lifecycle scripts, lockfile-source verification, CodeQL, OpenSSF Scorecard, zizmor, Dependabot, CODEOWNERS, and `SECURITY.md`. Templates can also get a manual-only `deploy.yml` starter: container templates publish a Docker image to GHCR, while Vercel and Cloudflare templates run their platform CLIs with credentials from GitHub Actions secrets and variables. The scaffolder deliberately omits npm publishing workflows because generated projects are REST API services, not reusable libraries.

```bash
pnpm create daloy@latest my-api --template node-basic --package-manager pnpm --with-ci --code-owner @acme/security
```

GitHub settings are still your responsibility: replace the CODEOWNERS owner if needed, enable branch protection, require the generated checks, and turn on secret scanning plus push protection.

On GitLab, Bitbucket, Azure DevOps, Jenkins, or an on-prem runner, you still inherit the runtime guardrails, `@daloyjs/core`'s zero-runtime-dependency package, SBOM and npm provenance, and the pnpm install-time controls if you choose pnpm. Translate the GitHub workflow rules above into your CI host: start from no default write permissions, avoid shared dependency caches for untrusted code, keep installs reproducible, and isolate any job that can publish or deploy.

## If you legitimately need a postinstall

`ignore-scripts=true` is global. To allow a build script for a package you actually trust (e.g. `esbuild`), allowlist it explicitly in `package.json`:

```json
{
  "pnpm": {
    "onlyBuiltDependencies": ["esbuild"]
  }
}
```

DaloyJS itself uses the pnpm 11+ equivalent, an `allowBuilds` allowlist in `pnpm-workspace.yaml` (`package.json#pnpm.onlyBuiltDependencies` is the pre-v11 form). Each entry should be reviewed in PR.

## Avoid git and tarball dependencies

DaloyJS also checks its root lockfile for dependency sources that bypass the normal npm registry path. In this repo, `pnpm verify:lockfile` fails on git dependencies and non-registry tarball URLs so a transitive source change cannot slip through as ordinary version churn.

## Optional: install-time malware scanners

The 24-hour `minimum-release-age` cooldown is what bridges the gap between a malicious version being published and the registry yanking it. Aikido's [“quantum incident response”](https://www.aikido.dev/blog/quantum-incident-response) write-up makes the point that you cannot out-react an npm worm once it lands: prevention at install time is the only viable defense. DaloyJS's install defaults already implement that thesis (cooldown, no transitive lifecycle hooks, zero runtime deps in `@daloyjs/core`, frozen + verified store). For belt-and-braces beyond the cooldown, install a real-time scanner that intercepts package-manager calls and checks each requested version against a live malware feed before it touches disk:

```bash
# Aikido Safe Chain, free, no account required.
# Wraps npm / pnpm / yarn / npx / pnpx and refuses known-malicious
# package versions before they install.
npm install -g @aikidosec/safe-chain
safe-chain setup
```

DaloyJS deliberately does **not** add `safe-chain` (or any other third-party scanner) as a dependency or scaffold default. `@daloyjs/core` ships zero runtime dependencies by policy and any install-time tool you run is your trust decision, not the framework's. Equivalent commercial offerings (Socket, Snyk Advisor, JFrog Curation, npm's own Package Trust) sit at the same layer. Pick one or run none, but understand that `minimum-release-age=1440` is already doing most of the work the article recommends.

## Mapped to the ENISA package-manager advisory

ENISA's [Technical Advisory for Secure Use of Package Managers](https://www.enisa.europa.eu/publications/enisa-technical-advisory-for-secure-use-of-package-managers) (v1.1, March 2026) is the EU reference checklist for consuming third-party packages, organised across a four-stage life cycle. DaloyJS implements the integration checklist **as shipped defaults**, including the two controls ENISA itself flags as “optional” or “more suited for high-security environments.”

**Diagram: ENISA package-consumption life cycle**

- **Select** (stage 1) - trustworthy, verified, maintained
- **Integrate** (stage 2) - integrity, source, scripts, pinning
- **Monitor** (stage 3) - scan, track CVEs, ownership changes
- **Mitigate** (stage 4) - assess, prioritise, patch, document

DaloyJS meets or exceeds the Select and Integrate controls as defaults. Monitor is daily SCA plus Dependabot. Per-app CVE reachability triage in Mitigate is the consumer's job.

| ENISA recommendation | DaloyJS control |
| --- | --- |
| Installation script prevention (`ignore-scripts`; ENISA flags as “high-security”) | Default, not opt-in: `ignore-scripts=true` + `pnpm verify:no-lifecycle-scripts` |
| Release-age delay (`--before`; ENISA flags as “optional and situational”) | Standing policy: `minimum-release-age=1440` (24h) |
| Integrity / lockfile verification (SHA-512) | `frozen-lockfile` + `verify-store-integrity` + `pnpm verify:lockfile` |
| Package source enforcement (trusted registry only) | `registry=` pinned + `pnpm verify:lockfile` |
| SBOM creation | CycloneDX 1.5 + SPDX 2.3 per release + `pnpm verify:sbom` |
| Trusted Publishing + provenance | OIDC trusted publishing (no long-lived token) + `--provenance` Sigstore |
| Internal allowlist of approved package names | `pnpm verify:known-dep-names` |
| Reduce dependencies (“is the dependency needed?”) | `@daloyjs/core` ships zero runtime deps (`verify:no-runtime-deps`) |

ENISA section 5.2 names **slopsquatting** (attackers pre-registering hallucinated package names that AI tools emit) as a first-class AI-era threat. DaloyJS closes both axes: `verify:known-dep-names` forces every top-level dependency onto an explicit allowlist (name axis), and `minimum-release-age=1440` waits out the window in which a slop-squat is typically detected and unpublished (time axis). Full recommendation-by-control table: [SECURITY.md → ENISA mapping](https://github.com/daloyjs/daloy/blob/main/SECURITY.md#enisa-technical-advisory-for-secure-use-of-package-managers-march-2026-mapping).

ENISA section 5.2's concern is backed by survey data. Aikido's [State of AI in Security & Development 2026](https://www.aikido.dev/state-of-ai-security-development-2026) report (450 practitioners) found that 69% of organizations have uncovered vulnerabilities introduced by AI-generated code and 1 in 5 had a serious incident tied to it, and that automated CI gates reduce incidents while manual review and tool sprawl do not. That is the case for DaloyJS's posture here: secure-by-default output means AI-generated code starts safe, and the fail-closed `verify:*` gates are exactly the kind of automated, low-false-positive guardrail the report associates with fewer incidents.

## What to do if a maintainer account is phished

The September 2025 chalk/debug compromise started with a single fake `npmjs.help` 2FA-reset email. If you suspect a maintainer (yours or an upstream's) was phished:

1. Pin every direct dependency that lists the affected maintainer to the last known-good version in your lockfile.
2. `pnpm audit --prod` and rotate any deployment credential the install host had access to (npm token, GitHub token, AWS keys, SSH keys).
3. Bump `minimum-release-age` in `.npmrc` further (e.g. `4320` for 72h) until the campaign settles.
4. Subscribe to [GitHub Security Advisories](https://github.com/advisories) for your dependency tree.

## Hardening your own GitHub Actions

If you publish your own application's artifacts from CI, copy these rules:

- Never use `pull_request_target` to check out fork code.
- Top-level `permissions: {}`; opt back in per job.
- Pin third-party actions to a commit SHA (Dependabot will keep them updated). A retargeted tag has the same blast radius as cache poisoning.
- Separate the publish job. Do not put `id-token: write` on a workflow that runs untrusted code in any earlier step. OIDC tokens have been pulled from runner memory in real attacks.
- Use `step-security/harden-runner` on the publish job with `egress-policy: block` and an explicit allowlist.
- Use a protected GitHub Environment (required reviewers) for any job that can publish.

## Further reading

- [Aikido: Quantum incident response](https://www.aikido.dev/blog/quantum-incident-response): why traditional IR cannot catch an npm worm, and why install-time prevention (cooldowns, blocked scripts, malware-feed scanners) is the only viable defense.
- [TanStack 2026-05-11 postmortem](https://tanstack.com/blog/npm-supply-chain-compromise-postmortem): the cache-poisoning + OIDC-extraction chain in detail.
- [TanStack incident follow-up](https://tanstack.com/blog/incident-followup): what they changed afterwards.
- [GitHub Security Lab: preventing pwn requests](https://securitylab.github.com/research/github-actions-preventing-pwn-requests/).
- [npm provenance documentation](https://docs.npmjs.com/generating-provenance-statements).
- [ENISA: Technical Advisory for Secure Use of Package Managers](https://www.enisa.europa.eu/publications/enisa-technical-advisory-for-secure-use-of-package-managers) (March 2026), and Socket's [summary](https://socket.dev/blog/enisa-technical-advisory-on-secure-package-manager-use).
- [Aikido: State of AI in Security & Development 2026](https://www.aikido.dev/state-of-ai-security-development-2026) (survey of AI-generated-code incident rates).

---

Source: https://daloyjs.dev/docs/security/supply-chain