fix(security): restrict reviewed lock transition

[jyaunches]

Summary

Restricts the reviewed npm lock transition introduced by #8157 to one explicit successor. The trusted audit configuration now authorizes the current OpenClaw lock plus only the corrected 5.0.9 lock digest required by #8156.

Changes

• Keep reviewed npm audit schema 2 with required lockSha256 and one optional replacementLockSha256.
• Require the replacement digest to be a distinct lowercase SHA-256 value.
• Replace the stale fdbee91a... transition digest with 847f68ac..., produced by the published brace-expansion@5.0.9 metadata (engines.node = "20 || >=22").
• Test acceptance of the current digest and single replacement, rejection of any other digest, and the exact OpenClaw transition configuration.
• Removal condition: when fix(security): close managed runtime audit gaps #8156 lands the 847f68ac... lock, promote that digest to lockSha256 and remove replacementLockSha256 in the same change.

This is a prerequisite correction for #8156 and a follow-up to #8157.

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 corrects internal trusted CI audit authority without changing a supported API, CLI, configuration, workflow, default, or user-facing error.
• 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 exact-head security review at 778b8f2b7 found no code vulnerability and confirmed the transition is limited to one distinct successor. Merge remains blocked on the bootstrap approval below.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue: no acceptance or waiver requested; reviewed-npm-audit must remain blocking until a security maintainer approves an explicit bootstrap path.

Security Review

Verdict: WARNING. The exact-head code correction is security-preserving, but this PR is not ready to merge until a security maintainer approves an explicit bootstrap path for the circular reviewed-npm-audit failure. Do not bypass or waive that failed audit.

Category	Verdict	Evidence
Secrets and credentials	PASS	No credentials or sensitive values added.
Input validation	PASS	Both digests must be lowercase 64-character SHA-256 values; the optional replacement must differ from the current digest.
Authentication and authorization	PASS	No authentication or authorization surface changes.
Dependencies	PASS	No dependency or registry changes.
Error handling and logging	PASS	A non-reviewed lock reports only expected and actual digests.
Cryptography and data protection	PASS	Existing SHA-256 identity enforcement is retained.
Configuration	PASS	Authority is narrowed from an arbitrary-length list to one current digest and one optional successor.
Security testing	PASS	Focused tests accept the current and successor identities and reject an unreviewed identity.
System security	WARNING	The base OpenClaw graph still triggers GHSA-rgw5-rvv9-x895; governance approval is required to bootstrap this prerequisite without weakening the audit gate.

Files reviewed: ci/reviewed-npm-audit.json, scripts/audit-reviewed-npm-graph.mts, test/openclaw-locked-install.test.ts, and test/reviewed-npm-audit-workflow.test.ts.

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: no-docs-needed
• Evidence: Exact-head review confirmed this is an internal trusted CI audit correction with no user-visible behavior change; the schema-removal assertion is identity-safe, an unreviewed third digest is rejected during transition, and focused tests passed 22/22.
• Agent: Codex Desktop

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 commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run validate:pr passed after refreshing origin/main when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — vitest run --project integration test/openclaw-locked-install.test.ts test/reviewed-npm-audit-workflow.test.ts: 22 tests passed; source-shape check passed.
• Applicable broad gate passed — not applicable; this is a narrow trusted-audit contract correction covered by focused tests and normal hooks.
• 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: fce18db1-cad7-4d66-a9ba-9dc21fb9290e

📥 Commits

Reviewing files that changed from the base of the PR and between 23653a5 and 778b8f2.

📒 Files selected for processing (1)

• test/reviewed-npm-audit-workflow.test.ts

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

• test/reviewed-npm-audit-workflow.test.ts

---

📝 Walkthrough

Walkthrough

The reviewed npm audit metadata changes from schema version 3 to version 2. Locked graphs now use primary and optional replacement lockfile digests. Validation, lock selection, metadata expectations, and workflow tests use the new fields.

Changes

Reviewed npm digest schema

Layer / File(s)	Summary
Audit metadata contract ci/reviewed-npm-audit.json, scripts/audit-reviewed-npm-graph.mts, test/openclaw-locked-install.test.ts	The schema now uses version 2. Locked graphs store lockSha256 and optional replacementLockSha256 values. OpenClaw and mcporter metadata tests use the updated fields.
Digest validation and lock selection scripts/audit-reviewed-npm-graph.mts, test/reviewed-npm-audit-workflow.test.ts	Validation checks hexadecimal digest values and rejects duplicate primary and replacement values. Lock selection accepts either digest and returns the matching lockfile digest. Tests cover current, replacement, and unavailable replacement locks.

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

Possibly related PRs

• NVIDIA/NemoClaw#8156: Both PRs modify OpenClaw lock metadata and related test expectations.
• NVIDIA/NemoClaw#8157: This PR revises the audit schema and digest fields introduced by that PR.
• NVIDIA/NemoClaw#8165: Both PRs modify the reviewed npm schema and selectReviewedLockSha256.

Suggested labels: area: security, dependencies

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the security fix that restricts reviewed lock transitions, which is the primary change in the pull request.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / low confidence
Next action: Review the warnings below.
Findings: 0 blockers · 1 warning · 0 suggestions
Status: Partial review preserved 1 canonical finding(s) and 0 terminology decision(s) before the advisor stopped.

Model lanes

• GPT-5.6 Terra (primary): Failed after a partial review · low confidence · 0 blockers · 1 warning · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions

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

E2E guidance

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

Recommended E2E: None

1 warning · 0 suggestions

Warnings

Warnings do not block.

PRA-1 Warning — Make the temporary replacement lock authority self-retiring

• Location: ci/reviewed-npm-audit.json:66
• Category: correctness
• Problem: The OpenClaw graph authorizes both the current and replacement lock digests, but the trusted configuration does not identify the successor state or the condition that removes the old digest.
• Impact: After the replacement lock becomes the committed runtime lock, the audit can still accept the obsolete lock. This weakens the intended one-way transition boundary and permits a regression to the prior reviewed graph.
• Recommendation: Record the successor state and removal condition next to the temporary replacement digest. When the successor lock is committed, promote it to lockSha256 and remove replacementLockSha256.
• Verification: Inspect the OpenClaw lockedGraphs entry and the successor lock update together; confirm that the final configuration contains only the successor digest.
• Test coverage: Add a configuration contract that models completion of the transition and asserts the successor is lockSha256 with no replacementLockSha256.
• Evidence: ci/reviewed-npm-audit.json:64-66 defines both lockSha256 and replacementLockSha256 for the OpenClaw graph. scripts/audit-reviewed-npm-graph.mts:237-254 accepts either configured digest and has no transition-completion state.

Workflow run details

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

[jyaunches]

Superseded by #8165, which merged the bounded reviewed-lock transition for the final OpenClaw and mcporter successor digests required by #8156. Closing this duplicate bootstrap path to keep one canonical implementation and audit trail.