Files
headroom/e2e/wrap/tools/README.md
Parideboy f6fbac3a49 fix(deps): move the wrap E2E harness to npm 12.2.2 and drop the fixed audit exceptions (#4778)
## Description

`e2e/wrap/tools/npm-audit-exceptions.json` excepted 8 advisories in npm
12.2.1's bundled copies and gave "no newer npm release is available" as
part of the reason. npm 12.2.2 is published and bundles cleanness for 6
of those 8: undici 6.29.0 → 6.29.1 and ip-address 10.7.2 → 10.7.5.
Moving the harness pin drops those exceptions; glob 13.0.6 and minimatch
10.2.5 are unchanged, so their two exceptions stay and the file's expiry
moves off the 2026-11-15 cliff, where the security job would otherwise
fail every PR.

Closes #4774

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `e2e/wrap/tools/package.json` and `e2e/wrap/Dockerfile`: pin npm
12.2.2 instead of 12.2.1, in both the dependency override and the
image's global install.
- `e2e/wrap/tools/package-lock.json`: regenerated by installing the lock
with npm 12.2.2 itself. `npm install --package-lock-only` does **not**
refresh the `inBundle` child entries, so it left undici at 6.29.0; a
real `npm install --ignore-scripts` updated them. Only the bundled
copies npm 12.2.2 changed moved — `@npmcli/promise-spawn` 10.0.1,
`bin-links` 7.0.1, `ip-address` 10.7.5, `libnpmexec` 11.0.5, `pacote`
22.0.1, `semver` 7.8.6, `undici` 6.29.1 — with no unrelated transitive
drift and the npm entry itself at 12.2.2 with the registry's
`dist.integrity`.
- `e2e/wrap/tools/npm-audit-exceptions.json`: removed the 5 undici and 1
ip-address entries, corrected the reason (they are fixed in what 12.2.2
bundles), and moved `expires` to 2026-12-15 so the two glob/minimatch
exceptions left are not a four-day fuse.
- `e2e/wrap/tools/README.md`: the pin references, the paragraph
describing which bundled copies the audit still reports, and a separate
procedure for bumping the `npm` override, since `npm install
--package-lock-only` does not refresh npm's `inBundle` children.
- `e2e/wrap/tools/dependency-regression.test.cjs` and
`e2e/wrap/Dockerfile`: a regression test that reads npm's bundled undici
and ip-address versions, fails if either is below its fixed floor
(6.29.1, 10.7.5) or still has an entry in `npm-audit-exceptions.json`,
and runs in the image too.

## Testing

- [ ] Unit tests pass (`pytest`)
- [ ] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
# npm 12.2.2 tarball, from registry.npmjs.org (sha512 matches dist.integrity)
$ tar -xzf npm-12.2.2.tgz
undici 6.29.1
ip-address 10.7.5
glob 13.0.6
minimatch 10.2.5
12.2.2

# every bundled copy the registry tarball ships, vs npm 12.2.1
changed: 7
@npmcli/promise-spawn: 10.0.0 -> 10.0.1
bin-links: 7.0.0 -> 7.0.1
ip-address: 10.7.2 -> 10.7.5
libnpmexec: 11.0.4 -> 11.0.5
pacote: 22.0.0 -> 22.0.1
semver: 7.8.5 -> 7.8.6
undici: 6.29.0 -> 6.29.1

# CI's audit step from .github/workflows/security.yml, run locally on the new lock
$ cd e2e/wrap/tools && npm audit --package-lock-only --json > audit.json && python3 ci_audit_check.py audit.json
Only excepted bundled advisories remain (2), until 2026-12-15.

# same script, same lock, with the runner's npm 11 instead of 12.2.2
Only excepted bundled advisories remain (2), until 2026-12-15.

# raw audit totals, before -> after
{"moderate":33,"high":1,"total":34}   # undici high + ip-address moderate
{"moderate":33,"high":0,"total":33}   # glob + minimatch only; the rest inherit from them

# clean install of the new lock with npm 12.2.2, in a scratch prefix like /opt/wrap-tools
$ npm ci --prefix <dir> --no-fund --no-audit --strict-allow-scripts
added 363 packages in 28s
$ npm test                      # this branch
1..4
# tests 4
# pass 4
# fail 0

# the same test file against base (npm 12.2.1 + its 8 exceptions), installed from the old lock
$ node node_modules/npm/bin/npm-cli.js test
not ok 1 - npm bundles the fixed undici and ip-address instead of excepting them
  error: 'npm bundles undici 6.29.0, below the fixed 6.29.1'
# pass 3
# fail 1

# and against npm 12.2.2 while the old exceptions file is still in place
not ok 1 - npm bundles the fixed undici and ip-address instead of excepting them
# (fails on the leftover exception entries, as intended)
```

## Real Behavior Proof

- Environment: Windows 11, Node 26.10.0, npm 12.2.2 taken from the
downloaded registry tarball; no Docker engine on this machine.
- Exact command / steps: (1) unpack `npm-12.2.2.tgz` and read the
bundled `package.json` versions, comparing all 132 entries against
12.2.1. (2) `npm install --ignore-scripts` into a copy of
`e2e/wrap/tools` so the lock's `inBundle` entries regenerate. (3) `npm
audit --package-lock-only` on that lock, then the Python exception check
copied verbatim from `.github/workflows/security.yml`. (4) `npm ci
--prefix <dir> --no-fund --no-audit --strict-allow-scripts`, then `npm
test`, `openclaw --version`, `codex --version` in that prefix. (5)
Cross-check every one of the 147 `node_modules/npm/node_modules/*` lock
entries against the tree npm 12.2.2 actually installed. (6) Run the new
test file against base's lock installed with npm 12.2.1, and against the
same tree with base's exceptions file restored.
- Observed result: the lock resolves npm 12.2.2 and its 7 new bundled
copies. The CI check prints `Only excepted bundled advisories remain
(2), until 2026-12-15.` with exit 0, for both the bundled npm 12.2.2 and
the runner's npm 11. The high-severity undici finding is gone, and no
`STALE EXCEPTION` line appears because the removed entries and their
advisories are gone together. The prefix install is byte-consistent with
the lock: 147/147 bundled entries match, 0 mismatches. `npm test` is 4/4
on this branch; the new check fails on base with `npm bundles undici
6.29.0, below the fixed 6.29.1`, and also fails on 12.2.2 if the old
exception entries are put back. `openclaw --version` → `OpenClaw
2026.10.10 (7dc3350)`, `codex --version` → `codex-cli 0.166.0`.
- Not tested: the Docker image build and the wrap E2E run itself —
neither can run here without Docker. `docker-native-e2e` and Wrap E2E
cover that in this PR, since their path filters include `e2e/**`. The
installed CLIs were exercised only via `--version`, not a full
Codex/OpenClaw session.

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a, dependency pins for the E2E harness only
- Stable/default behavior changed: no. The wheel, SDK and plugins are
untouched; this only changes the npm the E2E image installs with and the
lock the harness installs from.
- Kill switch / disable path: none needed
- Unsafe override required: no
- Qualification impact: none; no shipped artifact embeds npm or these
bundled copies
- Rollback path: revert this commit

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [ ] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` - it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

N/A

## Additional Notes

**Dependency justification** (CONTRIBUTING, "Dependencies & supply
chain"):

| Package | Why this version | Maintainer, activity | Install surface |
|---|---|---|---|
| `npm` 12.2.1 → 12.2.2 | Security patch in the bundled copies: 12.2.2
ships undici 6.29.1 and ip-address 10.7.5, which clear 5 undici
advisories (GHSA-4qv8-2p9j-2685, GHSA-xjj6-f33q-929c,
GHSA-2m5v-pch6-74hx, GHSA-qrxm-fqhp-jwvm, GHSA-9fm3-97px-rjf6) and
GHSA-rxp7-6hxx-x8q5 that 12.2.1's undici 6.29.0 and ip-address 10.7.2
carried. It is also `latest` and the only release that closes them. |
npm, Inc., maintained at [npm/cli](https://github.com/npm/cli) under the
same release process as every other npm; monthly minors, patch releases
within days of a bundled-dependency fix. | Same as the 12.2.1 pin it
replaces: a global CLI install in the E2E image only. No new package, no
new install script, no native code. Registry tarball carries
`dist.integrity`, which the lock now pins. |

The six bundled copies also move (`@npmcli/promise-spawn`, `bin-links`,
`libnpmexec`, `pacote`, `semver` patch bumps — they are npm's own
release, not a resolution I chose). None is reachable from the wheel or
SDK; the whole tree lives in `/opt/wrap-tools` inside the E2E image.

Why the expiry moves rather than disappearing: glob GHSA-3g3m-2fjr-6pw4
(fixed only in glob 14.0.2) and minimatch GHSA-g3hv-75wg-m249 (fixed
only in 11.0.1) still apply, because npm 12.2.2 bundles glob 13.0.6 and
minimatch 10.2.5 — both majors npm does not bundle. Deleting the file
would fail the security job on those two; keeping 2026-11-15 would fail
it in four days regardless of this change. 2026-12-15 is one month,
matching the cadence the file had.

N/A items: `pytest`, `ruff`, `mypy` — no Python changed. The new test is
the one CONTRIBUTING asks for on a bug fix: it fails on base (`npm
bundles undici 6.29.0, below the fixed 6.29.1`) and passes here, and it
keeps holding the invariant for the next npm bump rather than only
pinning this one. The remaining glob/minimatch exceptions are still
verified by the security job's own check, which rejects stale entries.

Answering the two review comments: both are addressed — the regression
test is the new `dependency-regression.test.cjs` case, and the README
now documents the npm override bump as its own procedure with the reason
`--package-lock-only` is not enough.
2026-11-11 09:49:01 -06:00

4.3 KiB

Wrap E2E CLI dependencies

The Docker harness installs Codex and OpenClaw here using npm 12.2.2 and npm ci. Keep the manifest and lockfile together: pinning only the CLI versions still lets transitive dependency ranges change on every image build. That broke main during an AWS SDK publication on 2026-09-09 (ETARGET and tarball 404).

The image installs into /opt/wrap-tools and exposes node_modules/.bin on PATH. npm ci does not support global installs, so diagnostics must also use npm list --prefix /opt/wrap-tools.

After editing a CLI version in package.json, regenerate the lockfile using Node 24.22.1+ within the Node 24 line and npm 12.2.2 on Linux (the pinned OpenClaw version no longer supports Node 22):

cd e2e/wrap/tools
npm install --package-lock-only --no-fund --no-audit
npm ci --no-fund --no-audit
npm test
cd ../../..
docker build -f e2e/wrap/Dockerfile -t headroom-wrap-e2e .
docker run --rm headroom-wrap-e2e

npm test runs the Ajv URI, minimatch pattern-expansion, Express body-parser and npm bundled-copy regression checks against the installed locked dependencies. The Dockerfile runs the same command from /opt/wrap-tools after npm ci, so failures stop the image build in both the existing Wrap E2E workflow and CI's Docker-native wrap E2E job. Their path filters include e2e/**, covering dependency and regression-test updates.

To intentionally refresh transitive versions without changing the pinned CLI versions, use npm update --package-lock-only --no-fund --no-audit in this directory instead of npm install --package-lock-only, then run the same installation and Docker checks above.

Changing the npm override is a separate procedure. npm install --package-lock-only does not refresh npm's inBundle children, so the lock keeps the old bundled versions and the audit keeps reporting them. Bump the override, then run a real install in a scratch copy of this directory (with the package.json, .npmrc and old lock), and copy its package-lock.json back:

cp package.json .npmrc package-lock.json /tmp/npm-bump/
cd /tmp/npm-bump && npm install --ignore-scripts --no-fund --no-audit
cp package-lock.json /path/to/e2e/wrap/tools/

Review that diff: only the bundled copies npm changed between the two releases should move (node_modules/npm/node_modules/*), plus the npm entry itself. Then update the npm@ pin in the Dockerfile, recheck npm-audit-exceptions.json against the new bundled versions, and run the checks above.

Review the lockfile diff and justify dependency changes in the PR. A lockfile fixes resolution and checks package integrity; it cannot make the npm registry available during an outage. Do not delete the lockfile or add fallback installs to make a build pass.

These are existing test tools, not new product dependencies. Codex is maintained by OpenAI; OpenClaw and its transitive dependencies retain their upstream maintainers. Their install surface includes registry downloads, native optional packages and lifecycle scripts, as before. OpenClaw 2026.10.10 and its fixed Undici override follow the upstream #4453 security repair.

The raw audit still reports npm 12.2.2's bundled glob and minimatch copies. npm-audit-exceptions.json records the upstream-approved E2E-only risk acceptance, restricted to exact advisory/path/version combinations and expiring on 2026-12-15. Security CI rejects other findings and expired or stale entries; these exceptions are not a claim that the contained packages are patched.

The root allowScripts policy approves only the exact locked install-script identities reviewed for this harness: @google/genai@2.27.0 (no-op preinstall), esbuild@0.28.2 (native binary validation/fallback acquisition), protobufjs@7.6.6 (dependency version-scheme warning), and openclaw@2026.10.10 (package-manager/runtime validation and bundled-plugin/native prebuild maintenance). These scripts execute package code and may spawn helpers; esbuild may acquire its platform binary. No wildcard or blanket approval is used. The local .npmrc enables strict review: a new install-script identity fails installation until its script and version are reviewed. npm12 otherwise blocks unreviewed scripts while merely warning, which is insufficient proof that the normal lifecycle ran. Bundled npm dependency copies do not run separate scripts.