ci(security): allow reviewed lock transitions

[jyaunches]

Summary

Allow the trusted reviewed npm audit to recognize an explicitly reviewed lock transition.
This lets the current OpenClaw runtime lock and the pending brace-expansion@5.0.9 lock pass the same base-trusted policy without accepting any unreviewed lock bytes.

Related Issue

Prerequisite for #8156.

Changes

• Advance the reviewed npm audit configuration to schema 3 and replace each single lock digest with a nonempty, unique list of reviewed digests.
• Select the exact target lock digest only when it appears in that trusted list, then pass the selected digest through the existing strict source-lock and installed-package verification.
• Temporarily list both the current and pending OpenClaw runtime lock digests; keep the mcporter graph restricted to its current digest.
• Update focused contracts to cover accepted and rejected transition locks and the shared OpenClaw audit authority.

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: The exact-head review confirmed the trusted-base boundary remains intact, unlisted lock bytes fail closed, and both existing strict lock verifiers receive one exact selected digest.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: no-docs-needed
• Evidence: The schema transition is internal CI policy and does not change a supported API, CLI, user configuration, workflow, default, or user-facing error.
• 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 — command/result or justification: vitest focused integration tests passed, 22/22.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: Not applicable to this narrow audit-control change.
• 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)

Additional validation:

• npm run source-shape:check passed.
• npm run build:cli and npm run typecheck passed.
• Biome, test title, and Vitest project membership checks passed.
• Normal pre-commit and commit-message hooks passed.

---

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

Summary by CodeRabbit

• Security

  • Improved dependency audit verification to support multiple approved lockfile revisions.
  • Added stricter validation to detect unapproved or mismatched dependency lockfiles before and after installation.
  • Enhanced error reporting to clearly identify expected and actual lockfile checksums.

• Tests

  • Expanded coverage for approved lockfile selection and checksum mismatch scenarios.

[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: 16ef1e0d-2e77-4ddd-ae50-97df0fe66cf9

📥 Commits

Reviewing files that changed from the base of the PR and between f12ae8d and e7d2be9.

📒 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

---

📝 Walkthrough

Walkthrough

The audit schema advances from version 2 to version 3. Locked graphs now store approved lockfile SHA-256 arrays. The workflow validates and selects the actual digest before installation and reuses it afterward. Tests cover matching and rejected digests.

Changes

Reviewed lock digest selection

Layer / File(s)	Summary
Digest schema and audit metadata scripts/audit-reviewed-npm-graph.mts, ci/reviewed-npm-audit.json	The schema advances to version 3. Locked graphs use nonempty, unique reviewedLockSha256 arrays with lowercase SHA-256 values. OpenClaw lists two digests, and mcporter lists one.
Lockfile digest selection and verification scripts/audit-reviewed-npm-graph.mts	The workflow hashes lockfiles, selects an approved digest, reports expected and actual values on mismatch, and reuses the selected digest for pre-install and post-install verification.
Digest selection test coverage test/openclaw-locked-install.test.ts, test/reviewed-npm-audit-workflow.test.ts	Tests cover array-based audit metadata, accepted reviewed digests, rejected digests, and temporary-file cleanup.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• NVIDIA/NemoClaw#8126: Modifies the same audit script and workflow tests for production dependency auditing.
• NVIDIA/NemoClaw#8131: Extends the same reviewed npm graph auditing and lockfile verification logic.
• NVIDIA/NemoClaw#8156: Updates the same audit metadata and OpenClaw lockfile digest approval fields.

Suggested labels: area: ci

Suggested reviewers: cv

🚥 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 summarizes the main change: allowing explicitly reviewed npm lockfile transitions.
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 docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/allow-reviewed-openclaw-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 e7d2be9 in the codex/allow-reviewed... branch remains at 96%, unchanged from commit c63e7eb in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit e7d2be9 in the codex/allow-reviewed... branch remains at 81%, unchanged from commit c63e7eb in the main branch.

Show a code coverage summary of the most impacted files.

File	main c63e7eb	codex/allow-reviewed... e7d2be9	+/-
src/lib/domain/.../connect-env.ts	97%	89%	-8%
src/lib/sandbox...rce-identity.ts	88%	88%	0%
src/lib/state/m...-acquisition.ts	75%	75%	0%

---

_{Updated August 03, 2026 19:37 UTC}

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / low confidence
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions
Status: Partial review preserved 0 canonical finding(s) and 2 terminology decision(s) before the advisor stopped.

Model lanes

• GPT-5.6 Terra (primary): Failed after a partial review · low confidence · 0 blockers · 0 warnings · 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.

2 semantic terminology decisions

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

• established — reviewed lock at test/reviewed-npm-audit-workflow.test.ts:52: Retain `reviewed lock`; it matches established repository security and installer terminology.
• justified — dependency transition at test/reviewed-npm-audit-workflow.test.ts:52: Retain `dependency transition`; the modifier identifies the temporary two-digest policy case.

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.

[cv]

Commit SHA e7d2be90d is not safe to merge as written.

The OpenClaw transition list authorizes fdbee91a3f3a0222ec2e8e34864d09dfcff4711e86ac6bfa4d475af0593acd51.
That digest belongs to a 5.0.9 lock entry with stale engines.node = "18 || 20 || >=22" metadata.
The published package uses 20 || >=22; the corrected reviewed lock digest is 847f68ac46f18d17efcd47dd3d8a5944b9dbcd205bc4d1e821ff82aa543eec20.

The arbitrary digest-array schema is also broader than the current one-successor transition requires.
A schema-2 lockSha256 plus one optional replacementLockSha256 keeps the current identity explicit, limits the temporary authority to one successor, and makes post-merge promotion and removal unambiguous.

The current reviewed-npm-audit failure is independently blocking: the base-owned audit still finds GHSA-rgw5-rvv9-x895 in the current OpenClaw lock.
This creates a circular gate with #8156 because the remediation cannot introduce its corrected lock until the transition authority is present in the base SHA.
Do not bypass or waive the failed security check.
The repository needs an explicit governance-approved bootstrap path before this prerequisite can merge.

After the technical contract changes, rerun the security and documentation reviews for the new commit SHA and update the PR description using repository vocabulary.