Merge pull request #105 from jplomas/main

Audit remediations

Author: jplomas

.github/workflows/ci.yml

@@ -11,6 +11,11 @@ on:
 permissions:
   contents: read
 
+# Single source of truth for jobs that pin one Node version. Referenced by both
+# the `setup-node` input and the step name so the two can never drift apart.
+env:
+  NODE_VERSION: 22.x
+
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
@@ -22,6 +27,11 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
+        # The advertised floor (engines.node: >=20.19.0) is NOT exercised here: the dev
+        # toolchain cannot install on it (.npmrc sets engine-strict=true and
+        # semantic-release requires ^22.14.0 || >=24.10.0). The floor is proven instead
+        # where it actually matters — against published tarballs, on 20.19.0, in
+        # release.yml's smoke job — plus scripts/doctor.js and the package_engines test.
         node-version: [22.x, 24.x]
 
     steps:
@@ -47,11 +57,15 @@ jobs:
       - name: Check repository hygiene
         run: pnpm run hygiene
 
+      # Build before lint: type-aware ESLint rules need built cross-package types to resolve.
+      - name: Build packages
+        run: pnpm run build
+
       - name: Lint workspace
         run: pnpm run lint
 
-      - name: Build packages
-        run: pnpm run build
+      - name: Enforce lint warning budget
+        run: pnpm run lint:budget
 
       - name: Build browser bundle
         run: pnpm run build:web
@@ -71,9 +85,15 @@ jobs:
       # `pnpm audit` calls npm's retired /security/audits endpoint (HTTP 410), so
       # scan the lockfile with Trivy instead, failing on HIGH/CRITICAL. Accepted
       # advisories are documented in .trivyignore.
+      #
+      # `version` is pinned rather than left to the action's default so this leg
+      # and `pnpm run audit:supply-chain` (which runs the same Trivy release from
+      # a digest-pinned image) cannot drift apart. scripts/doctor.js fails if the
+      # two stop agreeing; bump both together.
       - name: Trivy vulnerability scan (high/critical)
         uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
         with:
+          version: v0.70.0
           scan-type: fs
           scan-ref: pnpm-lock.yaml
           scanners: vuln
@@ -90,10 +110,10 @@ jobs:
         with:
           persist-credentials: false
 
-      - name: Use Node.js 20.x
+      - name: Use Node.js ${{ env.NODE_VERSION }}
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
-          node-version: 22.x
+          node-version: ${{ env.NODE_VERSION }}
 
       - name: Enable pnpm
         run: corepack enable
@@ -127,10 +147,10 @@ jobs:
         with:
           persist-credentials: false
 
-      - name: Use Node.js 20.x
+      - name: Use Node.js ${{ env.NODE_VERSION }}
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
-          node-version: 22.x
+          node-version: ${{ env.NODE_VERSION }}
 
       - name: Enable pnpm
         run: corepack enable
@@ -176,10 +196,10 @@ jobs:
         with:
           persist-credentials: false
 
-      - name: Use Node.js 20.x
+      - name: Use Node.js ${{ env.NODE_VERSION }}
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
-          node-version: 22.x
+          node-version: ${{ env.NODE_VERSION }}
 
       - name: Enable pnpm
         run: corepack enable

.github/workflows/release.yml

@@ -12,6 +12,12 @@ concurrency:
 permissions:
   contents: read
 
+# The exact floor advertised by every published manifest (engines.node). The
+# tarball smoke runs on this precise version so the advertised floor is proven
+# rather than assumed. Keep in step with the root package.json engines.node.
+env:
+  NODE_FLOOR_VERSION: 20.19.0
+
 jobs:
   ci:
     name: CI
@@ -116,8 +122,8 @@ jobs:
             dist/checksums-sha512.txt
           retention-days: 5
 
-  smoke-node20:
-    name: Smoke Tarballs (Node 20)
+  smoke-node-floor:
+    name: Smoke Tarballs (advertised Node floor)
     needs: prepare
     if: needs.prepare.outputs.released == 'true'
     runs-on: ubuntu-latest
@@ -127,14 +133,15 @@ jobs:
         with:
           persist-credentials: false
 
-      - name: Use Node.js
+      - name: Use Node.js ${{ env.NODE_FLOOR_VERSION }}
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           # Smoke test runs `npm install` against the published tarballs in a
           # fresh temp dir; it never installs the monorepo's devDependencies,
           # so the semantic-release Node 22+ engine constraint does not apply.
-          # Stay on Node 20 here to verify consumer-facing `engines.node: >=20`.
-          node-version: 20.x
+          # Pin the exact advertised floor here so consumers on the oldest
+          # supported Node are covered, not just the newest 20.x release.
+          node-version: ${{ env.NODE_FLOOR_VERSION }}
 
       - name: Download release candidate tarballs
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
@@ -147,7 +154,7 @@ jobs:
 
   publish:
     name: Publish
-    needs: [prepare, smoke-node20]
+    needs: [prepare, smoke-node-floor]
     if: needs.prepare.outputs.released == 'true'
     runs-on: ubuntu-latest
     environment: npm-publish
@@ -171,8 +178,13 @@ jobs:
           registry-url: https://registry.npmjs.org/
 
       - name: Use npm 11 for trusted publishing
+        # zizmor: ignore[adhoc-packages]
+        # npm trusted publishing (OIDC provenance) requires npm >= 11.5.1, which
+        # is newer than the npm bundled with the pinned Node in setup-node above.
+        # The version is pinned exactly (not @latest), so this is a deliberate,
+        # reviewed exception rather than an unpinned ad-hoc install.
         run: |
-          npm install -g npm@^11.5.1
+          npm install -g npm@11.5.1
           npm --version
 
       - name: Download release candidate tarballs

.gitignore

@@ -6,6 +6,10 @@
 # Secrets
 .secrets.json
 
+# Ephemeral TLS fixtures generated for Firefox system tests
+templates/cypress/.cert/
+*.pem
+
 # Logs
 logs
 *.log

.lint-budget.json

@@ -0,0 +1,26 @@
+{
+	"description": "Per-package ESLint warning budget enforced by scripts/lint-budget.js. A package that emits more warnings than its budget fails CI. Lower a budget with `pnpm run lint:budget -- --update` after removing warnings; never raise one to hide a new warning.",
+	"budgets": {
+		"packages/abi": 1865,
+		"packages/web3": 869,
+		"packages/web3-core": 1056,
+		"packages/web3-errors": 224,
+		"packages/web3-net": 108,
+		"packages/web3-providers-http": 339,
+		"packages/web3-providers-ipc": 235,
+		"packages/web3-providers-ws": 296,
+		"packages/web3-qrl": 2622,
+		"packages/web3-qrl-abi": 202,
+		"packages/web3-qrl-accounts": 1557,
+		"packages/web3-qrl-contract": 1391,
+		"packages/web3-qrl-iban": 91,
+		"packages/web3-qrl-qrns": 549,
+		"packages/web3-rpc-methods": 476,
+		"packages/web3-types": 62,
+		"packages/web3-utils": 1293,
+		"packages/web3-validator": 882,
+		"tools/eslint-config-base-web3": 0,
+		"tools/web3-packagetemplate": 7,
+		"tools/web3-plugin-example": 40
+	}
+}

.trivyignore

@@ -1 +1,11 @@
+# Accepted vulnerability advisories for `pnpm run audit:supply-chain` and the
+# matching CI scan in .github/workflows/ci.yml.
+#
+# Both scans read this file, so an entry here suppresses the finding locally and
+# in CI alike. Add one only with a maintainer's reason for why the advisory is
+# unreachable and a time-bounded follow-up, per docs/supply-chain-security.md.
+# One advisory ID per line, e.g.:
+#
+#   CVE-0000-00000  # unreachable: <reason>; revisit by <date>
+
 # (none)

RELEASE.md

@@ -14,7 +14,7 @@ Release publishing is guarded by:
 - The repository variable `RELEASES_ENABLED` must be set to `true`.
 - The protected GitHub environment `npm-publish` must approve the job.
 - The CI workflow must pass first.
-- Release tarballs must pass CommonJS and ESM smoke tests on Node 20 before publish.
+- Release tarballs must pass CommonJS and ESM smoke tests on Node 20.19.0 (the advertised `engines.node` floor) before publish.
 - npm publishing must run from Node 22.14 or newer with npm 11.5.1 or newer so npm trusted publishing can use OIDC.
 - npm publishing must use provenance (`NPM_CONFIG_PROVENANCE=true`).
 
@@ -81,7 +81,7 @@ The release workflow:
 8. Packs released packages.
 9. Generates SHA-256 and SHA-512 checksums.
 10. Uploads tarballs and release metadata as a short-lived workflow artefact.
-11. Downloads the tarballs in a Node 20 job and smoke-tests CommonJS `require()` and ESM `import`.
+11. Downloads the tarballs in a Node 20.19.0 job (the advertised floor) and smoke-tests CommonJS `require()` and ESM `import`.
 12. Publishes the already-tested tarballs from a Node 22.14/npm 11 job using npm trusted publishing.
 13. Generates SPDX and CycloneDX SBOMs.
 14. Creates GitHub attestations for release artefacts and SBOMs.

SECURITY.md

@@ -31,6 +31,45 @@ Please include as much of the following as possible:
 The QRL team will triage private reports, coordinate fixes, and publish
 security advisories or release notes when appropriate.
 
+## Key Material & Memory Security
+
+The secret protected by this library is the wallet **seed** (and the extended seed / mnemonic that
+contain it). Anyone with the seed can derive the ML-DSA-87 secret key and sign arbitrary
+transactions, so it is critical material.
+
+**JavaScript does not provide guaranteed secure memory handling.** Unlike languages that expose raw
+buffers, a JS runtime may keep copies of a secret that the application cannot reach or erase — the
+garbage collector may relocate or retain copies, the JIT may materialise additional copies, and the
+value may reach swap or a core dump. This is a platform limitation, not a defect in this library, and
+it is the same constraint documented for [`@theqrl/wallet.js`](https://github.com/theQRL/wallet.js)
+(see its `SECURITY.md` "Memory Security").
+
+**Seeds are held as immutable strings.** `web3.qrl.accounts` exposes the seed as a hex string
+(`account.seed`). A JavaScript string is immutable, so — unlike a `Uint8Array` — it **cannot be
+zeroized/overwritten** after use. Best-effort scrubbing therefore does not apply to the seed as this
+API exposes it; treat any seed string as unrecoverably resident in memory for the process lifetime.
+
+What this library **does** do to reduce accidental exposure:
+
+- `account.seed` is defined **non-enumerable**, so it does not appear in a spread, `Object.keys`, or
+  a naive `for…in`.
+- `account.toJSON()` **redacts** the seed (`'<redacted>'`), so `JSON.stringify(account)` and most
+  loggers will not serialise it.
+
+Recommendations for applications handling seeds:
+
+- **Minimise seed lifetime.** Derive what you need and drop references promptly; do not hold seeds in
+  long-lived state, closures, or global caches.
+- **Never log or serialise raw seeds.** Rely on the redaction above rather than passing the seed to a
+  logger, telemetry, or error report yourself.
+- **Prefer the encrypted keystore at rest.** Store seeds as an encrypted V1 keystore (Argon2id +
+  AES-256-GCM), never as plaintext.
+- **For tighter in-memory control**, operate on the lower-level `Uint8Array`-backed primitives in
+  [`@theqrl/wallet.js`](https://github.com/theQRL/wallet.js) and call its `zeroize()` when done —
+  understanding that this is **best-effort** protection, not a cryptographic guarantee.
+- **For high-value use**, consider a hardware security module, a dedicated signer process, or a
+  worker with a constrained lifetime rather than holding seeds in a general-purpose runtime.
+
 ## Release Verification
 
 After the first audited release, published packages are expected to be verifiable

docs/audit-evidence.md

@@ -21,7 +21,7 @@ corepack enable
 
 Expected result:
 
-- Node is within the supported `>=20` range.
+- Node is within the supported `>=20.19.0` range.
 - pnpm is the Corepack-managed pnpm 10 line used by the lockfile.
 - `corepack enable` exits `0`.
 
@@ -51,10 +51,16 @@ Expected result:
 
 Required GitHub status checks should match the commands above:
 
-- `Verify (Node 20.x)`, `Verify (Node 22.x)`, and `Verify (Node 24.x)` run
-  frozen ignored-script install, doctor, hygiene, lint, build, browser build,
-  and unit tests.
-- `Supply Chain Audit` runs the production high/critical audit.
+- `Verify (Node 22.x)` and `Verify (Node 24.x)` run frozen ignored-script
+  install, doctor, hygiene, lint, build, browser build, and unit tests. The
+  advertised `engines.node` floor (`>=20.19.0`) is deliberately not exercised
+  here — the dev toolchain cannot install on it (`.npmrc` sets
+  `engine-strict=true`; `semantic-release` requires `^22.14.0 || >=24.10.0`).
+  The floor is proven against published tarballs on 20.19.0 by the release
+  smoke job, plus `scripts/doctor.js` and the `package_engines` metadata test.
+- `Supply Chain Audit` runs the pinned Trivy 0.70.0 lockfile scan, failing on
+  HIGH/CRITICAL. Reproduce locally with `pnpm run audit:supply-chain` (same
+  version, from a digest-pinned image).
 - `Package Inspection` builds, inspects, packs, and smoke-tests release
   tarballs.
 - `Unit Coverage` runs unit coverage and uploads configured JSON artefacts to

docs/dependency-warning-triage.md

@@ -21,20 +21,21 @@ not block a release solely because a known warning below is still present.
 - Migrated linting to ESLint 10 flat config and removed the deprecated
   `eslint-plugin-deprecation` rule because its latest release does not declare
   compatibility with ESLint 10.
-- The npm registry's latest ESLint release observed during the migration was
-  `10.3.0`, but it was published on 2026-05-01 and is inside the seven-day
-  `minimumReleaseAge` quarantine. The lockfile therefore uses the newest
-  policy-eligible ESLint release, `10.2.1`.
+- ESLint tracks the newest release that is outside the seven-day
+  `minimumReleaseAge` quarantine rather than the newest release on the registry.
+  The pinned version lives in the workspace manifests (root `package.json` and
+  each package's `devDependencies`), which are the source of truth; it is not
+  restated here because it moves every time the quarantine window clears.
 
 ## Accepted For The Current Lockfile
 
 - Some release-tool transitive warnings are inherited from
   `multi-semantic-release`, `semantic-release`, conventional-changelog tooling,
-  and the current docs/build stack. They remain acceptable while the production
-  high/critical audit gate is green.
-- `@typescript-eslint` is locked at `8.59.0` and `globals` at `17.5.0` for the
-  same reason: the newest registry releases observed on 2026-05-01 were still
-  inside the seven-day quarantine window.
+  and the current docs/build stack. They remain acceptable while the
+  high/critical audit gate (`pnpm run audit:supply-chain`) is green.
+- `@typescript-eslint` and `globals` follow the same rule as ESLint above: they
+  track the newest release outside the quarantine window, and the manifests —
+  not this document — record which version that currently is.
 - ESLint 10 reports additional type-safety and stale-disable warnings. These
   are tracked as cleanup debt, not release blockers for this tooling migration,
   because `pnpm run lint` passes with zero errors across all package/tool

docs/package.json

@@ -49,7 +49,7 @@
 		]
 	},
 	"engines": {
-		"node": ">=20"
+		"node": ">=20.19.0"
 	},
 	"packageManager": "pnpm@10.27.0"
 }