fix(openshell): trust sandbox build pin data

[ericksoa]

Summary

Extend the base-trusted installer parser so a separately reviewed dependency pin PR can add standalone sandbox binary identities as release data without authorizing operational installer changes. This is the remaining base-branch prerequisite for #6726 after #6778 landed.

Changes

• Parse pinned_sandbox_build_version as a strict literal digest-to-version case map before normalizing it as release data.
• Require a unique SHA-256 per entry, literal X.Y.Z versions, a fail-closed default branch, and at least one identity for the selected release.
• Bind DEV_MIN_VERSION to the same selected release as the installer tables and other stable selectors.
• Add positive coverage for a v0.0.82 sandbox identity addition and negative coverage for control-flow, unknown-command, duplicate-digest, and malformed-version edits.

The complete v0.0.82 upgrade tree passes this base-trusted checker against all three release manifests and all ten consumed archives.

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 only the base-owned dependency verification boundary; active selectors remain on v0.0.72.
• 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: author review confirmed only the fully parsed release-data function and literal selectors are normalized; all other installer text remains locked by the trusted template hash.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Verification

• PR description includes the DCO sign-off declaration and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — npx vitest run test/installer-hash-check.test.ts (67/67), npm run build:cli, npm run typecheck, and the base-trusted checker against chore(openshell): upgrade supported version to 0.0.82 #6726
• 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 focused verifier grammar extension; normal hooks, typecheck, and focused integration coverage passed.
• 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: Aaron Erickson aerickson@nvidia.com

Summary by CodeRabbit

• Security & Reliability
  • Strengthened installer verification by adding trusted “sandbox build version” pin checks alongside existing checksum and command pin validation.
  • Installers now fail closed if sandbox build pins or development minimum version selectors are missing, malformed, inconsistent, or altered.
  • Updated trusted installer template expectations to improve detection of unauthorized changes and version drift.
• Testing
  • Expanded installer-hash tests with new sandbox build mutation scenarios, including both allowed pin changes and multiple rejected tampering cases, plus development-version drift coverage.

[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: 601031c6-3a5e-464d-885c-de641d21163e

📥 Commits

Reviewing files that changed from the base of the PR and between 76f3017 and 6905184.

📒 Files selected for processing (2)

• scripts/checks/extract-installer-pins.mts
• test/installer-hash-check.test.ts

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

• scripts/checks/extract-installer-pins.mts

---

📝 Walkthrough

Walkthrough

The installer verifier now parses trusted sandbox build pins and DEV_MIN_VERSION, validates them against the shared release version, locks multiple trusted functions, and adds fixture mutations and tests for sandbox-build and version-drift scenarios.

Changes

Installer verification

Layer / File(s)	Summary
Trusted installer parsing and locking scripts/checks/extract-installer-pins.mts	Adds strict sandbox pin extraction, DEV_MIN_VERSION parsing, multi-function template locking, and the updated trusted template hash.
Runtime installer consistency checks scripts/checks/extract-installer-pins.mts	Validates sandbox pins and DEV_MIN_VERSION against releaseVersion and locks both installer release-data functions.
Sandbox mutation fixtures and assertions test/installer-hash-check.test.ts	Adds sandbox-build and DEV_MIN_VERSION mutations, updates fixture rendering, and verifies accepted and rejected mutation cases.

Estimated code review effort: 4 (Complex) | ~45 minutes

Suggested labels: feature, area: cli

Suggested reviewers: jyaunches

Sequence Diagram(s)

sequenceDiagram
  participant InstallerSource
  participant runCli
  participant TrustedTemplate
  InstallerSource->>runCli: Extract sandbox pins and DEV_MIN_VERSION
  runCli->>runCli: Validate releaseVersion consistency
  runCli->>TrustedTemplate: Lock trusted installer functions
  TrustedTemplate-->>runCli: Return template verification result

Loading

🚥 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 reflects the main change: adding trusted handling for sandbox build pin data in openshell.
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 fix/openshell-sandbox-build-pin-trust

---

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

[github-actions]

E2E Advisor Recommendation

Required E2E: None
Optional E2E: None

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• None. No existing live E2E job is needed: this PR changes CI-only installer integrity verification and its unit/regression tests, not installer execution, onboarding, sandbox lifecycle, credentials, network policy, inference, deployment, or assistant user flows. The Security / Installer Hash Check workflow and test/installer-hash-check.test.ts directly validate the changed trust-boundary parser.

Optional E2E

• None.

New E2E recommendations

• None.

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage remains at 96%, unchanged from the main branch.

TypeScript / code-coverage/cli

The overall coverage in the fix/openshell-sandbo... branch remains at 79%, unchanged from the main branch.

Show a code coverage summary of the most impacted files.

File	main 73b35fc	fix/openshell-sandbo... 6905184	+/-
src/lib/name-validation.ts	100%	94%	-6%
src/lib/runner.ts	75%	72%	-3%
src/lib/inferen...time-context.ts	96%	94%	-2%
src/lib/messagi.../persistence.ts	90%	89%	-1%
src/lib/securit...ntial-filter.ts	99%	98%	-1%
src/lib/state/gateway.ts	88%	90%	+2%
src/lib/security/redact.ts	95%	99%	+4%
src/lib/inference/local.ts	71%	77%	+6%
src/lib/actions...ge-preflight.ts	74%	89%	+15%
src/lib/inferen...del-registry.ts	66%	100%	+34%

---

_{Updated July 13, 2026 18:24 UTC
Code Coverage is in Public Preview. Learn more and provide us with your feedback.}

[github-actions]

PR Review Advisor — No blocking findings

Merge posture: No blocking advisor findings
Primary next action: No advisor follow-up required beyond maintainer review.
Findings: 0 required · 0 warnings · 0 optional suggestions
Since last review: 1 prior item resolved · 0 still apply · 0 new items found

Workflow run details

This is an automated review. Required findings need action before merge. Warnings and optional suggestions do not require a response or follow-up. A human maintainer makes the final merge decision.

[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/installer-hash-check.test.ts`:
- Around line 199-207: Make mutateSandboxBuildFunction require both
function-boundary markers and throw or assert when either is missing or
mutate(functionSource) returns the unchanged source. In
test/installer-hash-check.test.ts lines 273-285, replace the unchecked global
replacement used for pin addition with this strict helper so the positive test
proves its mutation was applied.

🪄 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: 347fa08d-7890-4375-a221-2c58b3f16b18

📥 Commits

Reviewing files that changed from the base of the PR and between 73b35fc and 76f3017.

📒 Files selected for processing (2)

• scripts/checks/extract-installer-pins.mts
• test/installer-hash-check.test.ts