feat(npmprofile): Pin the publish npm CLI and Node.js toolchain with digest-verified provisioning - #131

- Add the pinned runtime table (Node.js 24.21.0, bundled npm 11.19.0)
  to the build and pack specification with
  internal/toolchainpins/node-runtime.json as the single shared
  machine-readable definition and a CI drift check.
- Specify the pre-install pair assertion: exact node/npm version
  equality with the recorded pair before the first npm invocation in
  each job that uses the bundled npm, failing closed with
  toolchain-pair-mismatch; the publish job runs the assertion in
  node-only mode under ADR 0082/0084.
- Replace floating Node.js 24 descriptions in the build-pack and
  package-profile specifications with the exact pinned patch; retain
  the npm >= 11.5.1 floor and runtime.npm_version recording semantics
  as defense in depth.
- Complete the PURL-derivation compatibility fixture keying with the
  build-side half and register toolchain-pair-mismatch and
  toolchain-pin-drift in the closed registry and shared taxonomy.

Signed-off-by: Yunseo Kim <[email protected]>

Create internal/toolchainpins holding the two builder-owned
machine-readable records as embedded files with strictly decoded,
concurrency-safe typed loaders:

- publish-npm.json: the ADR 0082/0084 publish-stage npm pin
  (npm 11.21.0, exact registry tarball URL, SHA-512 SRI byte-identical
  to the packument dist.integrity).
- node-runtime.json: the ADR 0085 build toolchain pair
  (Node.js 24.21.0, bundled npm 11.19.0).

Decoding reuses canonicaljson duplicate-member rejection, rejects
unknown fields, and validates exact three-part SemVer versions,
uncredentialed HTTPS tarball URLs, and sha512 SRI form with a 64-byte
digest. go:embed makes the single-shared-definition property
structural: the provisioning step, publish-side pin validation, and
the pair assertion all read these records by import.

Signed-off-by: Yunseo Kim <[email protected]>

…rball

Implement ADR 0084 provisioning and the npm-profile-provision-npm
subcommand:

- Download only the embedded pin URL through the hardened fetcher,
  verify the compressed SHA-512 against the pinned SRI before creating
  any directory, extract into a private per-job directory with the
  existing no-links archive policy (duplicate-entry rejection, bounded
  decompressed bytes and entry count, gzip drain against truncation),
  and validate the extracted package.json version and CLI entry
  against the pin.
- Emit a private launcher named npm that execs the resolved absolute
  node path against package/bin/npm-cli.js; provisioning executes
  neither node nor npm, keeping every failure pre-execution and
  pre-mutation. Partial extractions are removed on failure.
- Map failures to the registered diagnostics npm-provision-download,
  npm-provision-digest-mismatch, npm-provision-archive-unsafe, and
  npm-provision-version-mismatch (check npm.publish.provision).
- Register FuzzExtractNPMDistribution in both fuzz CI matrices per the
  testing guide.

Verified live (SLSA_BUILDER_LIVE_TOOLCHAIN=1): the recorded URL
serves bytes whose SHA-512 equals the pinned SRI and the provisioned
launcher reports npm 11.21.0.

Signed-off-by: Yunseo Kim <[email protected]>

Implement ADR 0085 pre-install pair assertion and the
npm-profile-toolchain-assert subcommand:

- Observe node --version and npm --version through the exec boundary
  and require exact equality with the embedded pair record
  (Node.js 24.21.0, bundled npm 11.19.0) before any install, build,
  or pack step; mismatch fails closed with toolchain-pair-mismatch
  (check npm.build.toolchain).
- --node-only mode asserts the Node.js runtime without looking up or
  executing npm, for the publish job where the bundled npm is never
  invoked (ADR 0082/0084).
- The npm >= 11.5.1 floor and Node-major-24 gate in toolchain.go are
  unchanged as defense in depth.

Real-surface evidence: npm-profile-toolchain-assert --node-only
passes on the pinned development runtime (node v24.21.0).

Signed-off-by: Yunseo Kim <[email protected]>

Extend the closed diagnostic_metadata report shape with the optional
publish_npm_version string member (exact three-part SemVer, non-trust
observational metadata, never merged into the build-time
externalParameters.runtime.npm_version record), following the
package_manifest extension precedent, and name the exact placement in
the publish pin-validation section: the outcome report's
diagnostic_metadata on success and on observed failures, plus the
failing diagnostic's evidence on pin mismatch.

Signed-off-by: Yunseo Kim <[email protected]>

Replace the publish-side build/publish npm-version equality check
with ADR 0082 pin validation:

- validateNPMVersion now compares the observed publish npm version
  against the embedded allowlist pin (npm 11.21.0); a mismatch fails
  closed with publish-npm-pin-mismatch (check npm.publish.toolchain)
  before any registry mutation, carrying the observed version in the
  failing diagnostic's evidence.
- The observed publish npm version is recorded as
  diagnostic_metadata.publish_npm_version on success and on failures
  after observation, per the extended closed report contract
  (diagnostic.go + strict metadata decoding in metadata_json.go).
- The build-stage externalParameters.runtime.npm_version recording
  and the --npm-executable path validation are unchanged; failed or
  malformed version observation keeps the existing
  builder-version-mismatch fallback without fabricated metadata.

RED-first semantic proof: publish 11.21.0 with build-observed 11.19.0
now passes, and publish 11.20.0 equal to the build record now fails
against the pin with no mutation attempted.

Signed-off-by: Yunseo Kim <[email protected]>

Teach the static workflow checker the ADR 0082/0084/0085 contract:

- All three jobs of the npm reusable workflow must set up Node.js at
  the exact patch from the embedded pair record (24.21.0), replacing
  the floating "24" literal in the build job and adding the check to
  the provenance-sign and publish jobs.
- Build and sign jobs must run npm-profile-toolchain-assert before
  any step whose run block invokes npm.
- The publish job must run npm-profile-toolchain-assert --node-only,
  then an identified npm-profile-provision-npm step ordered before
  the diagnostics and publish steps; every npm reference in the job
  must bind to the provisioning step's output expression, and ambient
  npm resolution (including command -v npm) is rejected.

Command-layer writer tests now use an inline conforming fixture
instead of the (currently nonconforming) production workflow; the
production workflow check itself is the expected-RED gate until the
workflow is updated.

Signed-off-by: Yunseo Kim <[email protected]>

Implement the ADR 0084/0085 drift gate:

- pin-check compares the disk records against the human-readable spec
  tables: the publish allowlist row (version, tarball URL, SHA-512
  SRI) in the provenance-publish spec and the runtime pair row in the
  build-pack spec, requiring exact equality and failing with
  toolchain-pin-drift (check toolchain.pins.drift) on any drift,
  missing table, or unparsable row. Markdown table parsing tolerates
  Prettier padding and inline-code delimiters but is exact on data
  values.
- Wire pin-check into the existing Go job in lint.yml with no
  permission or hardening changes.

Real-surface artifacts: repo-state run prints "Toolchain pin records
match specification tables." (exit 0); a spec copy with one flipped
SRI character fails exit 1 with a canonical toolchain-pin-drift
report.

Signed-off-by: Yunseo Kim <[email protected]>

Land the ADR 0082/0084/0085 toolchain contract on the npm reusable
workflow:

- All three jobs set up Node.js at the exact pinned patch 24.21.0.
- The build and provenance-sign jobs assert the pinned toolchain pair
  (Node.js 24.21.0, bundled npm 11.19.0) immediately after setup,
  before any npm invocation.
- The publish job asserts the pinned Node.js runtime in node-only
  mode, then provisions the digest-verified npm 11.21.0 CLI before
  any npm invocation including diagnostics; the diagnostics and
  publish steps invoke npm only through the provisioning step's
  npm-executable output, and ambient npm resolution is gone from the
  job.

Verified: actionlint clean, prettier clean, and workflow-check
--profile npm-only passes with the pinned-toolchain contract checks.

Signed-off-by: Yunseo Kim <[email protected]>

Add the spec-required PURL-derivation compatibility fixture family,
one key per supported npm CLI version with scoped and unscoped
coverage:

- npm-purl-publish-11-21-0-{scoped,unscoped}-valid, keyed to the
  publish allowlist pin npm 11.21.0 (ADR 0082).
- npm-purl-build-11-19-0-{scoped,unscoped}-valid, keyed to the
  build-stage pair npm 11.19.0 bundled with Node.js 24.21.0
  (ADR 0085).

Each fixture records the npm CLI version its expectation was verified
against and the expected Package URL, asserted against the producer's
NPMPackagePURL derivation; the live CLI cross-check rides with the
gated Live tests. Registered in internal/fixture/registry.go,
testdata/fixtures/index.json, and the expected-case map. Pre-existing
fixtures are byte-untouched.

Signed-off-by: Yunseo Kim <[email protected]>

- Retarget the verification procedure to the pending v0.1.3 retry:
  v0.1.3 dispatch and evidence expectations, tag identity recorded at
  dispatch time rather than pinned to attempt-4 values, the caller
  pin bump to a slsa-builder main SHA carrying the ADR 0082/0084/0085
  pinned-toolchain implementation, and the note that the provisioned
  pinned npm 11.21.0 carries the upstream npm/cli#9882 fix so the
  Windlass-signed bundle attaches as-is under trusted publishing. The
  existing 0.1.2 publication from run 31840088262 remains the Phase
  6.4 foreign-conflict target.
- Record the attempt-4 evidence file and retarget its forward-looking
  metadata (tag refs/tags/v0.1.3, peeled commit pending) for the
  retry.
- README (English and Korean): the npm support-window paragraph now
  states the build stage uses the npm bundled with the exactly pinned
  Node.js 24.21.0 patch (npm 11.19.0, asserted before first use per
  ADR 0085) and the publish stage provisions a separately pinned,
  digest-verified npm CLI (npm 11.21.0) per ADR 0082/0084.
- AGENTS.md standing item: pin selected as npm 11.21.0 per ADR 0083's
  11-line preference; provisioning and pair pin landed on the feature
  branch; remaining steps are the vers-js caller pin bump and the
  v0.1.3 dispatch with runbook phases 1-6.
- CHANGELOG [Unreleased]: Added entries for the publish npm pin and
  provisioning, the toolchain pair pin and assertion, the publish pin
  validation with publish_npm_version outcome evidence, and the
  pin-check drift CI gate.

Signed-off-by: Yunseo Kim <[email protected]>

Clarify in both the provenance-publish and build-pack specifications
that every npm-invocation requirement (the ADR 0084 before-any-
invocation provisioning clause and the ADR 0085 first-invocation pair
assertion) governs invocations of the npm CLI by a step of the job's
workflow, and that the pinned setup mechanism's internal, read-only
environment logging, such as the version reporting actions/setup-node
performs after installing Node.js, is part of the authenticated
toolchain setup and is not an npm invocation. ADR 0085 authenticates
the bundled npm through the pinned setup mechanism's own checksum
verification, so the setup action's version logging is inherent to
the authenticated setup; it touches no package operation, and the npm
it reports is the pair-pinned bundled npm the assertion validates.

Signed-off-by: Yunseo Kim <[email protected]>

The same-run already-committed convergence path returned success
before version validation, so the converged run's outcome report
omitted diagnostic_metadata.publish_npm_version even though the job
observed the provisioned npm. Validate the provisioned npm against
the allowlist pin on every path that reaches Publish, including
convergence: the read-only --version observation runs after
provisioning per the ADR 0084 ordering, the observed version is
recorded in the report metadata, a pin mismatch fails with
publish-npm-pin-mismatch instead of converging silently, and
validation failures preserve the classified registry state. Registry
classification order is unchanged.

Signed-off-by: Yunseo Kim <[email protected]>

Close the compatibility-evidence gap for the npm PURL fixtures with
the Live-gated TestNPMPURLCLICompatibilityLive: for each supported
npm CLI version and each fixture package it exercises the CLI's own
provenance subject derivation (npm-package-arg toPurl, the exact code
path libnpmpublish uses to build and exact-match the provenance
subject) and asserts equality with both the fixture-recorded PURL and
NPMPackagePURL. npm 11.21.0 is provisioned through the
digest-verified ProvisionNPM path; npm 11.19.0 is the pair-pinned
bundled CLI. Verified 12026-10-13: 4/4 fixture cases pass, and the
four fixture READMEs now record the completed cross-check evidence.
The comparison publishes nothing and contacts no registry.

Signed-off-by: Yunseo Kim <[email protected]>

…s at prose

Address PR #131 review findings against the pin records and drift gate.

- decodePublishPin checked URL.Host, which is non-empty for a port-only
  authority such as https://:443/npm.tgz. Require a nonempty Hostname so
  malformed pins are rejected before provisioning.
- The specification table scan treated a prose line directly after the last
  row as an unparsable row. The scan now stops at the first non-pipe line
  while pipe-prefixed malformed rows are still rejected, so harmless
  formatting changes do not fail pin-check.

Signed-off-by: Yunseo Kim <[email protected]>

Address a PR #131 review finding against the closed metadata contract.

The top-level null check did not cover members nested inside package_manifest,
so inputs such as {"package_manifest":{"description":null}} and
{"package_manifest":{"keywords":[null]}} were accepted after decoding erased
the null values. The specification requires explicit nulls to fail with
diagnostics-contract-invalid at any depth ("Absent source fields are omitted;
null ... fail"). UnmarshalJSON now scans each raw member value for null at any
depth after duplicate-member rejection, with the whole-member check keeping its
existing message.

Signed-off-by: Yunseo Kim <[email protected]>

…table bindings, and structural argument validation

Address three P1 PR #131 review findings against the static toolchain contract.

- Step conditions: contract-relevant steps in a job must all carry the exact
  same whitespace-normalized if: expression (or none), and constant-false
  conditions are rejected, so an assertion can never be skipped while an npm
  operation runs. The production publish segment's uniform upstream-success
  gate remains compatible.
- Executable binding: the publish diagnostics and publish steps must resolve
  NPM_EXECUTABLE to exactly the provisioning step output expression, at step
  or job env scope, rejecting ambient or hardcoded rebinding.
- Argument validation: shell comments are stripped before matching and the
  --npm-executable argument token must be exactly the pinned expression;
  comment-supplied evidence, duplicate flags, concatenated tokens, unknown
  variables, and single-quoted literal variable names are rejected.
- Preflight report contract: the node-only assertion and provisioning steps
  must now pass --report-path "$REPORT_PATH" with REPORT_PATH bound to the
  outcome report path, so the persistence wiring added for the outcome-report
  finding cannot be dropped silently. Fixtures model the production shape.

Signed-off-by: Yunseo Kim <[email protected]>

…ror branches

Address PR #131 review findings against the command adapters and outcome
reporting.

- npm-profile-provision-npm and npm-profile-toolchain-assert accept an
  optional --report-path and persist their typed failure report there
  atomically (0600) in addition to the stdout report; a successful run writes
  no file. The publish job wires REPORT_PATH and the flag into both preflight
  steps, so a provisioning or assertion failure uploads the specific
  diagnostic instead of the finalizer's generic input-unavailable.
- Add deterministic coverage for adapter flag-validation failures and
  downstream failure propagation across the provision, assert, and pin-check
  adapters, plus dispatch and flags edge cases.
- TestWorkflowCheckAcceptsProductionWorkflow runs the workflowcheck contract
  against the real js-ts-npm-package-slsa3.yml, so unit tests catch production
  conformance regressions alongside the lint.yml CLI gate.

Signed-off-by: Yunseo Kim <[email protected]>

…ifications

Address PR #131 review findings against the specification documents.

- The build specification claimed the bundled npm is authenticated through
  the pinned setup mechanism's checksum verification. The pinned
  actions/setup-node performs no Node.js artifact checksum verification, so
  the contract now states the honest guarantee: version identity is pinned
  observationally by the pair assertion, and artifact integrity rests on the
  runner image and the setup mechanism's TLS download.
- The pair-assertion sentence now defines the Node.js version
  canonicalization (strip the single leading v; npm compared verbatim),
  matching toolchain_assert.go, and names the pair assertion as the exempt
  preflight so the wording is not circular under the npm-invocation
  definition.
- The provenance/publish source ADR inventory gains ADR 0085, and the
  runtime.node_version rule is clarified as a defense-in-depth floor with the
  exact pinned pair asserted before first use; stale examples move to the
  pinned pair (24.21.0 / 11.19.0).
- The diagnostics taxonomy now documents the complete archive-safety
  rejection set (link and special-file entries) and both pin-record/spec
  comparisons covered by toolchain-pin-drift.
- The npmprofile live-test inventory includes npm_purl_live_test.go.

Signed-off-by: Yunseo Kim <[email protected]>

Address a PR #131 review finding against the Phase 0 runbook.

Phase 0 recorded the caller file blob SHA but never verified that publish.yml
actually references the selected builder commit, so a stale caller could
dispatch the old reusable workflow and bypass the pinned npm. The runbook now
requires updating the caller's uses: reference to the full 40-hex merged
builder SHA, fetching and decoding the file, failing closed unless the SHAs
match, and recording both the caller blob SHA and the builder SHA before
dispatch.

Signed-off-by: Yunseo Kim <[email protected]>

…k fixture

Align the command-level workflow fixture with the production publish job: the
node-only assertion and provisioning steps bind REPORT_PATH and pass
--report-path, matching the workflowcheck contract added in 049796e.

Signed-off-by: Yunseo Kim <[email protected]>