fix(security): bound reviewed lock transition

[jyaunches]

Summary

Restrict each reviewed npm lock transition to its current digest and one optional replacement, then authorize the final OpenClaw and mcporter locks from #8156. This is the base-trusted bootstrap needed before the remediation PR can pass the reviewed npm audit gate.

Supersedes #8164.

Changes

• Keep schema 2 with required lockSha256 and optional replacementLockSha256 fields.
• Reject a replacement digest that is invalid or duplicates the current digest, with driver-level regression coverage.
• Authorize fix(security): close managed runtime audit gaps #8156's final OpenClaw successor 759b31779f40867f35f15065b582eb1d3efb8fddb1fe43c207507c905fa2a421.
• Authorize fix(security): close managed runtime audit gaps #8156's final mcporter successor 962dee34f6b0a493521d1619d1cf030e2630cbdfce8bf0598217202f57078793.
• Continue to accept only the current digest or its one exact successor and reject an unreviewed third digest.

The successor bytes were independently hashed from #8156 head 914d3471b561a5226cdf3b2bd8c776865ba9438d. After #8156 lands, promote each successor to lockSha256 and remove its temporary replacementLockSha256.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification: This changes an internal base-trusted CI audit policy and no supported user-facing behavior.
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: Codex Desktop completed the nine-category security review at exact head d04bf1f7f36a8a54d4b593a35130e71e4bfde8d2; no blocker was found. The exact-head maintainer exception is recorded at fix(security): bound reviewed lock transition #8165 (comment).
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue: exact-head acceptance covers the circular reviewed-npm-audit / aggregate checks failure and unchanged image-build / downstream E2E failures. The rationale, limits, and removal condition are recorded at fix(security): bound reviewed lock transition #8165 (comment); the production npm audit remediation remains tracked by [Ubuntu 24.04][Security] npm audit --omit=dev reports 3 HIGH CVEs in production install (brace-expansion, fast-uri, js-yaml) #8116.

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: no-docs-needed
• Evidence: The change updates internal reviewed-npm-audit lock authority and its test contracts; it does not change a user-visible product or contributor workflow. The committed diff matches the independently reviewed change set.
• Agent: Codex Desktop documentation writer subagent

Security Review

Category	Verdict	Evidence
Secrets and Credentials	PASS	No secret-bearing values or credential paths changed; gitleaks passed.
Input Validation and Data Sanitization	PASS	SHA-256 syntax, current/successor inequality, exact graph identity, and third-digest rejection remain fail-closed.
Authentication and Authorization	PASS	No authentication or authorization behavior changed.
Dependencies and Third-Party Libraries	PASS	This PR selects no package version. Both successor lock bytes exactly match the independently reviewed #8156 head.
Error Handling and Logging	PASS	Existing mismatch diagnostics remain bounded and contain no secrets.
Cryptography and Data Protection	PASS	Exact SHA-256 lock binding remains mandatory; no cryptographic behavior is weakened.
Configuration and Security Headers	PASS	Each graph permits only its current digest and one optional exact successor.
Security Testing	PASS	Current, successor, invalid, duplicate, legacy, and unreviewed-third-digest cases are covered.
System Security	PASS	No sandbox, privilege, network, process, or image-hardening behavior changes.

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit:
• Station profile/scenario:
• Result:
• Supporting evidence:

Verification

• PR description includes a Signed-off-by: line and every pushed commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed at exact head d04bf1f7f36a8a54d4b593a35130e71e4bfde8d2
• Targeted behavior tests pass for the current change set — npm exec -- vitest run --project integration test/openclaw-locked-install.test.ts test/reviewed-npm-audit-workflow.test.ts passed, 23/23. npm run typecheck:cli, npm run checks:repository, and git diff --check also passed.
• Applicable broad gate passed — command/result: not applicable to this focused four-file audit-policy update; exact targeted, repository, type, hook, and required CI evidence is recorded above.
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Julie Yaunches jyaunches@nvidia.com

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: e03f2292-fa09-46d7-9ac3-ad7d92ba210b

📥 Commits

Reviewing files that changed from the base of the PR and between 8524e9b and d04bf1f.

📒 Files selected for processing (4)

• ci/reviewed-npm-audit.json
• scripts/audit-reviewed-npm-graph.mts
• test/openclaw-locked-install.test.ts
• test/reviewed-npm-audit-workflow.test.ts

🚧 Files skipped from review as they are similar to previous changes (3)

• test/openclaw-locked-install.test.ts
• ci/reviewed-npm-audit.json
• scripts/audit-reviewed-npm-graph.mts

---

📝 Walkthrough

Walkthrough

The audit metadata schema changes from version 3 to version 2. Locked graphs now store primary and optional replacement lockfile SHA-256 digests. Validation, lock selection, metadata assertions, and workflow tests use the new fields.

Changes

Reviewed npm audit digest handling

Layer / File(s)	Summary
Digest schema and metadata scripts/audit-reviewed-npm-graph.mts, ci/reviewed-npm-audit.json	LockedGraph and audit metadata now use lockSha256 and optional replacementLockSha256 fields. The schema version is now 2.
Digest validation and lock selection scripts/audit-reviewed-npm-graph.mts	parseAuditConfig validates 64-character hexadecimal digests and rejects duplicate primary and replacement digests. Lock verification uses both values.
Audit verification tests test/openclaw-locked-install.test.ts, test/reviewed-npm-audit-workflow.test.ts	Tests assert the new metadata shape and cover actual-lock acceptance, replacement-lock fallback, duplicate digest rejection, and unreviewed-lock rejection.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• NVIDIA/NemoClaw#8156: Both PRs modify OpenClaw and mcporter reviewed lockfile digests.
• NVIDIA/NemoClaw#8157: Both PRs modify the audit schema, digest validation, lock selection, and related tests.
• NVIDIA/NemoClaw#8164: Both PRs modify reviewed npm audit schema and lock digest handling.

Suggested reviewers: cv

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: limiting reviewed npm lockfile transitions.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/bound-reviewed-lock-transition

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit d04bf1f in the codex/bound-reviewed... branch remains at 96%, unchanged from commit 03fbf5e in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit d04bf1f in the codex/bound-reviewed... branch remains at 81%, unchanged from commit d756d15 in the main branch.

Show a code coverage summary of the most impacted files.

File	main d756d15	codex/bound-reviewed... d04bf1f	+/-
src/lib/onboard...cker-journal.ts	86%	83%	-3%
src/lib/onboard...mage-runtime.ts	50%	48%	-2%
src/lib/onboard...test-fixture.ts	98%	96%	-2%
src/lib/onboard...shared-state.ts	73%	73%	0%
src/lib/onboard...trap/adapter.ts	67%	68%	+1%
src/lib/shields/index.ts	68%	69%	+1%
src/lib/inferen...ompatibility.ts	94%	95%	+1%
src/lib/onboard...-transaction.ts	78%	80%	+2%
src/lib/onboard...strap/docker.ts	60%	66%	+6%
src/lib/domain/.../connect-env.ts	89%	97%	+8%

---

_{Updated August 03, 2026 22:01 UTC}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@test/openclaw-locked-install.test.ts`:
- Line 380: Update the OpenClaw assertion in the test to locate the relevant
locked graph by its PACKAGE_SPEC or id, rather than using audit.lockedGraphs[0].
Assert that the identified graph does not have the legacy reviewedLockSha256
property, while preserving the existing graph identity validation.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 6e5f2db4-b4c3-435f-aad9-d4130ce0a259

📥 Commits

Reviewing files that changed from the base of the PR and between 03fbf5e and b91ad1d.

📒 Files selected for processing (4)

• ci/reviewed-npm-audit.json
• scripts/audit-reviewed-npm-graph.mts
• test/openclaw-locked-install.test.ts
• test/reviewed-npm-audit-workflow.test.ts

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized terminology decisions differ; normalized E2E selections match; severity counts match.

4 terminology differences from the second opinion

Advisory only. These are normalized differences from the primary terminology receipt.

• replacement lock at test/reviewed-npm-audit-workflow.test.ts:75: selected only by the second-opinion lane as conflict.
• replacementLockSha256 at ci/reviewed-npm-audit.json:74: selected only by the second-opinion lane as define.
• lockSha256 at ci/reviewed-npm-audit.json:73: selected only by the second-opinion lane as replace.
• reviewedLockSha256 at test/openclaw-locked-install.test.ts:394: selected only by the second-opinion lane as replace.

Second-opinion terminology and E2E selections are advisory. They do not change the primary assessment or E2E / PR Gate.

1 semantic terminology decision

Terminology decisions are advisory. They affect the assessment only when a separate finding identifies concrete semantic impact.

• justified — replacement lock digest at test/reviewed-npm-audit-workflow.test.ts:75: Keep “replacement lock digest” for the optional successor digest; the test states the necessary distinction.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: None

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[senthilr-nv]

Approved at exact head 8524e9b. The reviewed npm lock transition remains bounded to one independently verified successor digest, rejects invalid, duplicate, and third digests, and preserves the selected digest through pre/post-install validation. The CodeRabbit graph-identity test finding is addressed. Focused tests pass 22/22 and npm run validate:pr passed on the preceding refreshed head; the final change is a test-only type annotation. No docs update is needed. This approval does not waive the expected reviewed-npm-audit bootstrap gate or other required CI.

[jyaunches]

Maintainer bootstrap exception — exact head d04bf1f7f36a8a54d4b593a35130e71e4bfde8d2

As repository administrator, I accept the following non-success checks for this exact head so the base-trusted npm audit policy can authorize the remediated locks in #8156:

• reviewed-npm-audit and the aggregate checks: the vulnerable locks are still on main, while the base-trusted audit cannot recognize fix(security): close managed runtime audit gaps #8156's replacement locks until this bounded policy transition lands.
• build-sandbox-images-x64, build-sandbox-images-arm64, and downstream E2E coordination: these independently fail on the unchanged MCP tool-discovery runtime's fast-uri / ip-address audit findings. That remediation remains tracked by [Ubuntu 24.04][Security] npm audit --omit=dev reports 3 HIGH CVEs in production install (brace-expansion, fast-uri, js-yaml) #8116 and is outside this four-file policy change.

This is not a general CI bypass. The transition remains limited to one exact successor per graph and rejects invalid, duplicate, or unreviewed third digests. The authorized successors were independently hashed from #8156 head 914d3471b561a5226cdf3b2bd8c776865ba9438d:

• OpenClaw: 759b31779f40867f35f15065b582eb1d3efb8fddb1fe43c207507c905fa2a421
• mcporter: 962dee34f6b0a493521d1619d1cf030e2630cbdfce8bf0598217202f57078793

After #8156 lands, each successor must become lockSha256 and its temporary replacementLockSha256 must be removed. #8165 supersedes #8164.

The earlier human approval explicitly did not waive CI; this comment is the separate, narrow maintainer exception for the failures named above.

[jyaunches]

Exception clarification for exact head d04bf1f7f36a8a54d4b593a35130e71e4bfde8d2: the required E2E / PR Gate observer remains pending because it treats the completed prerequisite-CI coordination failure as retryable and waits for another verdict. The terminal coordination receipt dispatched no live E2E solely because reviewed-npm-audit and its aggregate checks failed. This pending observer is therefore part of the downstream E2E condition accepted in the exact-head bootstrap exception above; it is not evidence of an additional code or test failure.