fix: harden CI verification, fuzzing, and release pipeline

- pin all verification upstreams by SHA: go-qrllib (v0.8.0 dilithium5 leg /
  v0.9.0 mldsa87), pq-crystals, NIST ACVP, Wycheproof
- run check-shared in CI lint + release preflight; add Node 24 to matrix
- port all four fuzz harnesses to dilithium5; budget corpus writes (expected
  throws no longer persisted); weekly scheduled campaign, deep reserved for
  audit-level review; corpus-size guard with --clean-corpus
- verify packages are live on npm before attaching release assets
- zeroizePolyVec helper, seed-secrecy warnings, deterministic-mode and
  hygiene cleanups; mark internal exports @deprecated ahead of next major
- codecov targets 100% with documented c8-ignore rationale policy; add
  CONTRIBUTING.md (shared-file rule, pin-bump procedure, error/invariant
  policy inherited from go-qrllib); security contact security@theqrl.org

Signed-off-by: JP Lomas <jp@theqrl.org>

Author: jplomas

.github/workflows/actionlint.yml

@@ -47,12 +47,14 @@ jobs:
         run: pipx install zizmor
 
       - name: Run zizmor
-        uses: zizmorcore/zizmor-action@b1d7e1fb5de872772f31590499237e7cce841e8e # v0.5.3
-        # about, including stylistic findings like missing job concurrency
+        # Pedantic persona: zizmor reports everything it knows about,
+        # including stylistic findings like missing job concurrency
         # limits, undocumented permissions, and template-injection
         # candidates. We hold the entire workflow surface to that bar —
         # any new finding at any severity fails the build. Configuration
-        with:
+        # exceptions live in .github/zizmor.yml (currently only the SLSA
         # reusable workflow ref-pin).
+        uses: zizmorcore/zizmor-action@b1d7e1fb5de872772f31590499237e7cce841e8e # v0.5.3
+        with:
           persona: pedantic
           config: .github/zizmor.yml

.github/workflows/acvp.yml

@@ -14,6 +14,12 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
+# Pinned to an explicit upstream commit so vector changes (or upstream
+# compromise) cannot silently alter what "verification passed" means.
+# Bump procedure: CONTRIBUTING.md "Updating pinned verification upstreams".
+env:
+  ACVP_SERVER_PIN: 15c0f3deeefbfa8cb6cd32a99e1ca3b738c66bf0 # 2026-04-16
+
 jobs:
   mldsa87-acvp:
     name: ML-DSA-87 ACVP Verification
@@ -28,20 +34,20 @@ jobs:
         with:
           node-version: 22.x
 
-      - name: Clone NIST ACVP-Server (sparse)
+      - name: Clone NIST ACVP-Server (sparse, pinned)
         run: |
           # Sparse checkout of just the ML-DSA keyGen + sigGen vector
-          # directories — the repo is large. Tracking master gives us
-          # upstream additions automatically; pin to a specific commit
-          # here if a future vector starts producing legitimate failures.
-          git clone --depth 1 --no-checkout --filter=blob:none \
+          # directories — the repo is large. Blobless clone + sparse
+          # checkout fetches only the blobs under the selected paths at
+          # the pinned commit.
+          git clone --no-checkout --filter=blob:none \
             https://github.com/usnistgov/ACVP-Server.git /tmp/acvp-server
           cd /tmp/acvp-server
           git sparse-checkout init --cone
           git sparse-checkout set \
             gen-val/json-files/ML-DSA-keyGen-FIPS204 \
             gen-val/json-files/ML-DSA-sigGen-FIPS204
-          git checkout
+          git checkout "$ACVP_SERVER_PIN"
           echo "ACVP-Server commit: $(git rev-parse --short HEAD)"
           echo "ACVP-Server date:   $(git log -1 --format=%ci)"
           ls -la gen-val/json-files/ML-DSA-keyGen-FIPS204/prompt.json

.github/workflows/ci.yml

@@ -29,13 +29,15 @@ jobs:
           node-version: '22.x'
       - run: npm ci
       - run: npm run lint
+      - name: Shared-file sync (dilithium5 ↔ mldsa87)
+        run: npm run check-shared
 
   test:
     name: Test (Node ${{ matrix.node-version }})
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [20.x, 22.x]
+        node-version: [20.x, 22.x, 24.x]
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:

.github/workflows/coverage.yml

@@ -29,6 +29,9 @@ jobs:
       - run: npm ci
       - run: npm test
       - run: npm run report-coverage
+      # Push uploads gate hard (fail_ci_if_error: true); PR uploads are
+      # best-effort so a Codecov hiccup can't block a PR — the coverage
+      # status checks themselves still come from codecov.yml targets.
       - name: Upload dilithium5 coverage to Codecov
         if: github.repository == 'theQRL/qrypto.js' && github.event_name == 'push'
         uses: codecov/codecov-action@57e3a136b779b570ffcdbf80b3bdc90e7fab3de2 # v6.0.0
@@ -45,3 +48,19 @@ jobs:
           files: ./packages/mldsa87/coverage.lcov
           flags: mldsa87
           fail_ci_if_error: true
+      - name: Upload dilithium5 coverage to Codecov (PR)
+        if: github.repository == 'theQRL/qrypto.js' && github.event_name == 'pull_request'
+        uses: codecov/codecov-action@57e3a136b779b570ffcdbf80b3bdc90e7fab3de2 # v6.0.0
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./packages/dilithium5/coverage.lcov
+          flags: dilithium5
+          fail_ci_if_error: false
+      - name: Upload mldsa87 coverage to Codecov (PR)
+        if: github.repository == 'theQRL/qrypto.js' && github.event_name == 'pull_request'
+        uses: codecov/codecov-action@57e3a136b779b570ffcdbf80b3bdc90e7fab3de2 # v6.0.0
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./packages/mldsa87/coverage.lcov
+          flags: mldsa87
+          fail_ci_if_error: false

.github/workflows/cross-verify.yml

@@ -14,6 +14,22 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
+# All upstream repositories are pinned to explicit commit SHAs so that a
+# change (or compromise) upstream cannot silently alter what "verification
+# passed" means, and so PR results are reproducible. Bump procedure:
+# CONTRIBUTING.md "Updating pinned verification upstreams".
+#
+# GO_QRLLIB_DILITHIUM5_PIN is permanently historical: upstream go-qrllib
+# removed crypto/dilithium in v0.9.0 (1ae1760, PR #109, 2026-06-10).
+# b2ee4790 = v0.8.0, the last release containing it; this leg verifies
+# interop with the frozen legacy implementation. The mldsa87 go-qrllib leg
+# tracks a current pin and should be bumped routinely.
+env:
+  GO_QRLLIB_DILITHIUM5_PIN: b2ee4790ef041104d2a48ae87cf68c0de621c89e # v0.8.0 (2026-06-08), last release with crypto/dilithium
+  GO_QRLLIB_MLDSA87_PIN: 6f9978367906233874b406bd5d55b0e8b8d01d9c # v0.9.0 (2026-06-10)
+  PQCRYSTALS_DILITHIUM5_PIN: ac743d588c6532aed027ccb1e7a24bfe6e35a120 # Round 3 (pre-FIPS) reference
+  PQCRYSTALS_MLDSA87_PIN: d35ba3fe5449bee3e6d43e1f296c3ca818bd36be # 2026-06-03, FIPS 204 reference
+
 jobs:
   dilithium5-cross-verify:
     name: Dilithium5 Cross-Verification (qrypto.js ↔ go-qrllib)
@@ -37,11 +53,11 @@ jobs:
       - name: Install qrypto.js dependencies
         run: npm ci
 
-      - name: Clone go-qrllib
+      - name: Clone go-qrllib (pinned)
         run: |
-          git clone --depth 1 https://github.com/theQRL/go-qrllib.git /tmp/go-qrllib
-          cd /tmp/go-qrllib
-          echo "go-qrllib commit: $(git rev-parse --short HEAD)"
+          git clone https://github.com/theQRL/go-qrllib.git /tmp/go-qrllib
+          git -C /tmp/go-qrllib checkout "$GO_QRLLIB_DILITHIUM5_PIN"
+          echo "go-qrllib commit: $(git -C /tmp/go-qrllib rev-parse --short HEAD)"
 
       - name: Generate qrypto.js Dilithium5 signature
         run: node .github/cross-verify/dilithium5_sign.js
@@ -85,11 +101,11 @@ jobs:
       - name: Install qrypto.js dependencies
         run: npm ci
 
-      - name: Clone go-qrllib
+      - name: Clone go-qrllib (pinned)
         run: |
-          git clone --depth 1 https://github.com/theQRL/go-qrllib.git /tmp/go-qrllib
-          cd /tmp/go-qrllib
-          echo "go-qrllib commit: $(git rev-parse --short HEAD)"
+          git clone https://github.com/theQRL/go-qrllib.git /tmp/go-qrllib
+          git -C /tmp/go-qrllib checkout "$GO_QRLLIB_MLDSA87_PIN"
+          echo "go-qrllib commit: $(git -C /tmp/go-qrllib rev-parse --short HEAD)"
 
       - name: Generate qrypto.js ML-DSA-87 signature
         run: node .github/cross-verify/mldsa87_sign.js
@@ -128,12 +144,11 @@ jobs:
       - name: Install qrypto.js dependencies
         run: npm ci
 
-      - name: Clone pq-crystals Dilithium (Round 3)
+      - name: Clone pq-crystals Dilithium (pinned, Round 3)
         run: |
           git clone https://github.com/pq-crystals/dilithium.git /tmp/dilithium-ref
-          cd /tmp/dilithium-ref
-          git checkout ac743d5  # Round 3 (pre-FIPS)
-          echo "Reference commit: $(git rev-parse --short HEAD)"
+          git -C /tmp/dilithium-ref checkout "$PQCRYSTALS_DILITHIUM5_PIN"
+          echo "Reference commit: $(git -C /tmp/dilithium-ref rev-parse --short HEAD)"
 
       - name: Generate qrypto.js Dilithium5 signature
         run: node .github/cross-verify/dilithium5_sign.js
@@ -186,11 +201,11 @@ jobs:
       - name: Install qrypto.js dependencies
         run: npm ci
 
-      - name: Clone pq-crystals Dilithium (FIPS 204 / ML-DSA)
+      - name: Clone pq-crystals Dilithium (pinned, FIPS 204 / ML-DSA)
         run: |
-          git clone --depth 1 https://github.com/pq-crystals/dilithium.git /tmp/mldsa-ref
-          cd /tmp/mldsa-ref
-          echo "Reference commit: $(git rev-parse --short HEAD)"
+          git clone https://github.com/pq-crystals/dilithium.git /tmp/mldsa-ref
+          git -C /tmp/mldsa-ref checkout "$PQCRYSTALS_MLDSA87_PIN"
+          echo "Reference commit: $(git -C /tmp/mldsa-ref rev-parse --short HEAD)"
 
       - name: Generate qrypto.js ML-DSA-87 signature
         run: node .github/cross-verify/mldsa87_sign.js

.github/workflows/fuzz-scheduled.yml

@@ -0,0 +1,80 @@
+name: Scheduled Fuzz
+
+# The per-push CI fuzz job runs the 10k-iteration quick profile only.
+# This workflow runs the 100k-iteration weekly profile every Sunday.
+# The 1M-iteration deep profile is deliberately NOT scheduled — it is
+# reserved for audit-level code review and can be launched on demand via
+# workflow_dispatch (or locally: scripts/fuzz/run-campaign.mjs --profile deep).
+on:
+  schedule:
+    - cron: '41 4 * * 0' # weekly profile, Sundays 04:41 UTC
+  workflow_dispatch:
+    inputs:
+      profile:
+        description: 'Fuzz profile (quick | weekly | deep)'
+        required: false
+        default: 'weekly'
+        type: choice
+        options:
+          - quick
+          - weekly
+          - deep
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  fuzz:
+    name: Fuzz campaign
+    runs-on: ubuntu-latest
+    # Deep (manual) is 1M iterations across all harnesses; leave generous
+    # headroom under the 360-minute job ceiling so artifacts still upload.
+    timeout-minutes: 350
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Use Node.js 22.x
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: '22.x'
+
+      - run: npm ci
+      - run: npm run build
+
+      - name: Select profile
+        id: select
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          PROFILE_INPUT: ${{ inputs.profile }}
+        run: |
+          set -euo pipefail
+          if [ "${EVENT_NAME}" = "workflow_dispatch" ]; then
+            profile="${PROFILE_INPUT:-weekly}"
+          else
+            profile="weekly"
+          fi
+          echo "profile=${profile}" >> "$GITHUB_OUTPUT"
+          echo "Selected profile: ${profile}"
+
+      - name: Run fuzz campaign
+        env:
+          PROFILE: ${{ steps.select.outputs.profile }}
+          # run_id makes the campaign reproducible: the engine derives all
+          # mutations deterministically from the master seed.
+          MASTER_SEED: ${{ github.run_id }}
+        run: node scripts/fuzz/run-campaign.mjs --profile "$PROFILE" --seed "$MASTER_SEED"
+
+      - name: Upload campaign results
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: fuzz-results-${{ github.run_id }}
+          path: fuzz-results/
+          retention-days: 30
+          if-no-files-found: warn

.github/workflows/release.yml

@@ -37,6 +37,7 @@ jobs:
 
       - run: npm ci
       - run: npm run lint
+      - run: npm run check-shared
       - run: npm test
       - run: npm run build
       - name: Verify dist/ is up to date
@@ -246,6 +247,34 @@ jobs:
             npm publish "dist/tarballs/${tarball_name}" --access public
           done < dist/released-packages.tsv
 
+      # Tags and GitHub releases were already created by multi-semantic-release
+      # in the prepare job; if npm publishing silently failed we would otherwise
+      # ship a tag/release with no npm artifact (this exact failure orphaned
+      # wallet.js v6.2.0). Verify the registry actually serves every released
+      # version before attaching release assets. Recovery runbook: RELEASE.md
+      # "Recovering an orphaned release".
+      - name: Verify packages are live on npm
+        run: |
+          set -euo pipefail
+          while IFS=$'\t' read -r _package_path package_name package_version _release_tag _tarball_name; do
+            echo "Verifying ${package_name}@${package_version} on the npm registry"
+            ok=""
+            for attempt in 1 2 3 4 5 6 7 8 9 10; do
+              served="$(npm view "${package_name}@${package_version}" version 2>/dev/null || true)"
+              if [ "${served}" = "${package_version}" ]; then
+                echo "  confirmed on attempt ${attempt}"
+                ok=1
+                break
+              fi
+              echo "  not yet visible (attempt ${attempt}/10); retrying in 15s"
+              sleep 15
+            done
+            if [ -z "${ok}" ]; then
+              echo "::error::${package_name}@${package_version} was published but is not served by the registry after 10 attempts. Tag and GitHub release exist without an npm artifact — follow RELEASE.md 'Recovering an orphaned release'."
+              exit 1
+            fi
+          done < dist/released-packages.tsv
+
       - name: Generate SBOM SPDX
         uses: anchore/sbom-action@e22c389904149dbc22b58101806040fa8d37a610 # v0.24.0
         with:

.github/workflows/wycheproof.yml

@@ -14,6 +14,12 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
+# Pinned to an explicit upstream commit so vector changes (or upstream
+# compromise) cannot silently alter what "verification passed" means.
+# Bump procedure: CONTRIBUTING.md "Updating pinned verification upstreams".
+env:
+  WYCHEPROOF_PIN: 6d7cccd0fcb1917368579adeeac10fe802f1b521 # 2026-06-06
+
 jobs:
   mldsa87-wycheproof:
     name: ML-DSA-87 Wycheproof Verification
@@ -28,18 +34,18 @@ jobs:
         with:
           node-version: 22.x
 
-      - name: Clone C2SP/wycheproof (sparse)
+      - name: Clone C2SP/wycheproof (sparse, pinned)
         run: |
           # Sparse checkout of testvectors_v1/ only; the repo is large
-          # and we only need the ML-DSA JSON files. Tracking master gives
-          # us upstream additions automatically; pin to a specific commit
-          # here if a future vector starts producing legitimate failures.
-          git clone --depth 1 --no-checkout --filter=blob:none \
+          # and we only need the ML-DSA JSON files. Blobless clone +
+          # sparse checkout fetches only the blobs under the selected
+          # paths at the pinned commit.
+          git clone --no-checkout --filter=blob:none \
             https://github.com/C2SP/wycheproof.git /tmp/wycheproof
           cd /tmp/wycheproof
           git sparse-checkout init --cone
           git sparse-checkout set testvectors_v1
-          git checkout
+          git checkout "$WYCHEPROOF_PIN"
           echo "Wycheproof commit: $(git rev-parse --short HEAD)"
           echo "Wycheproof date:   $(git log -1 --format=%ci)"
           ls -la testvectors_v1/mldsa_87_*.json