ci(installer): trust Homebrew formula transition

[sandl99]

Summary

Allow the base-trusted installer verifier to accept either the current archive-only installer template with its exact eight-asset table or the reviewed formula installer template with those same eight assets plus openshell.rb. Each trusted template hash is bound to its exact asset set, so this prerequisite lets #7319 pass base-SHA verification without allowing a formula pin before its consumer or arbitrary release assets and templates.

Related Issue

Refs #6903

Prerequisite for #7319.

Changes

• Bind the current archive-only installer template to exactly the current eight installer assets.
• Bind the reviewed formula installer template to exactly those same eight assets plus openshell.rb until feat(gateway): manage the default gateway service #7319 lands and tightens the rule.
• Download and verify the formula release asset directly, with regression coverage for both valid template/asset contracts, crossed contracts, duplicate pins, and digest mismatches.

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 is a temporary internal CI trust boundary and does not change user-facing installation 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 trust-boundary review binds each accepted operational template hash to one exact asset set; the formula is fetched over HTTPS and checked against its pinned SHA-256. CodeRabbit follow-up added duplicate-pin and digest-mismatch coverage.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

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 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 — command/result or justification: npx vitest run --project integration test/installer-hash-check.test.ts (74 passed); the trusted checker also passed against this PR's archive-only installer, the actual feat(gateway): manage the default gateway service #7319 formula-consuming installer, and the OpenShell v0.0.85 release assets.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: npm run check completed every pre-commit gate successfully, then reached the 20-minute local timeout during the manual coverage stage.
• 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: San Dang sdang@nvidia.com

Summary by CodeRabbit

• Bug Fixes
  • Improved installer hash verification for OpenShell release assets, including the Homebrew formula (openshell.rb).
  • Updated installer pin-table validation to allow a transitional asset set and to use computed expectations instead of fixed totals.
  • Enhanced template hashing by verifying against an allowlist of trusted SHA-256 values.
• Tests
  • Expanded installer-hash verification fixtures to cover formula hashing (success and mismatch), transitional template mappings, and duplicate-asset failure 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: ab2bb909-db49-4877-b7cb-98b42a9266d0

📥 Commits

Reviewing files that changed from the base of the PR and between 72e4b38 and febfda3.

📒 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

Installer hash validation now supports the transitional openshell.rb formula asset, accepts multiple trusted template hashes, computes expected asset counts dynamically, and adds fixture coverage for successful, mismatched, policy, and duplicate-pin verification.

Changes

Installer hash transition

Layer / File(s)	Summary
Pin validation and trusted template contracts scripts/checks/extract-installer-pins.mts	Installer asset validation is coupled to the matched trusted template hash; installer and Brev template hashes are checked against allowlists.
Release asset checksum verification scripts/check-installer-hash.sh	OpenShell verification accepts eight or nine pinned assets, hashes openshell.rb directly, and derives the expected matched-reference count.
Formula fixture and verification coverage test/installer-hash-check.test.ts	Fixtures optionally include the formula, simulate its download and digest, and cover transition, mismatch, policy, and duplicate-pin cases.

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

Sequence Diagram(s)

sequenceDiagram
  participant InstallerPins
  participant TemplateVerifier
  participant AssetSetValidator
  participant ReleaseVerifier
  participant OpenShellRelease
  InstallerPins->>TemplateVerifier: validate installer template against trusted hashes
  TemplateVerifier-->>InstallerPins: matched template SHA
  InstallerPins->>AssetSetValidator: validate template-specific asset set
  ReleaseVerifier->>OpenShellRelease: download openshell.rb
  OpenShellRelease-->>ReleaseVerifier: formula payload
  ReleaseVerifier->>ReleaseVerifier: compare computed digest with pinned value

Loading

Suggested labels: area: security

Suggested reviewers: cv, ericksoa, apurvvkumaria

🚥 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 summarizes the main change: a CI installer trust transition to include the Homebrew formula.
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/installer-hash-formula-trust-anchor

---

_{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 848dcfb in the fix/installer-hash-f... branch remains at 96%, unchanged from commit f992494 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 848dcfb in the fix/installer-hash-f... branch remains at 80%, unchanged from commit f992494 in the main branch.

Show a code coverage summary of the most impacted files.

File	main f992494	fix/installer-hash-f... 848dcfb	+/-
src/lib/onboard...ndbox-create.ts	83%	33%	-50%
src/lib/onboard...-create-plan.ts	88%	75%	-13%
src/lib/onboard...-desktop-gpu.ts	89%	77%	-12%
src/lib/onboard...ndbox-create.ts	91%	83%	-8%
src/lib/sandbox...rce-identity.ts	87%	87%	0%
src/lib/shields/index.ts	71%	72%	+1%

---

_{Updated July 22, 2026 14:45 UTC}

[coderabbitai]

Actionable comments posted: 2

🤖 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 `@scripts/checks/extract-installer-pins.mts`:
- Around line 175-184: Reject duplicate asset names in assertInstallerAssetSet
before selecting the expected 8-or-9 asset set, rather than relying on
assertExactAssetSet’s deduplicated comparison. Add a test fixture in
test/installer-hash-check.test.ts covering a duplicate archive pin and assert
that trusted verification rejects it.

In `@test/installer-hash-check.test.ts`:
- Around line 625-652: Extend the formula-specific sha256sum stub in the
installer hash test to support a mismatching-digest mode, while preserving the
existing successful FORMULA_DIGEST behavior. Add a test case that enables this
mode, invokes the direct-hash validation path, and asserts a nonzero result
containing STALE.

🪄 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: 10cdac1b-60b2-4cd1-9c8d-6942577cbf62

📥 Commits

Reviewing files that changed from the base of the PR and between 6e70994 and e4d4178.

📒 Files selected for processing (3)

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

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high confidence
Next action: Review the warnings below.
Findings: 0 blockers · 1 warning · 0 suggestions
Status: Canonical ledger: 0 blocker(s), 1 warning(s), 0 suggestion(s).

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 1 warning · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported the same number of blockers, 1 fewer warning, the same number of suggestions.

Nemotron output stays in workflow artifacts and does not change the assessment above.

E2E guidance

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

Recommended E2E: None

2 optional E2E recommendations

• openshell-version-pin
• bootstrap-install-smoke

1 warning · 0 suggestions

Warnings

Warnings do not block.

PRA-1 Warning — Cover formula-download failure

• Location: test/installer-hash-check.test.ts:792
• Category: tests
• Problem: The changed formula tests cover a matching digest and a mismatching digest, but none makes curl fail only for `openshell.rb`. Existing download-failure fixtures use the archive-only pin set, so they do not execute the new direct formula-fetch error branch.
• Impact: A future change can make an unavailable formula download pass, report success, or bypass the failure count without a regression test detecting it.
• Recommendation: Add a formula-template fixture where curl fails only for `openshell.rb`. Assert that the checker exits 1 and does not print the success message.
• Verification: Inspect `runFixture` and the curl fixture. Confirm that no formula-enabled invocation returns a curl error for `openshell.rb`.
• Test coverage: A formula-enabled trusted-checkout fixture that makes the `openshell.rb` curl request fail and asserts exit status 1 with no `All installer hashes are current` output.
• Evidence: `formula-mismatch` changes the SHA-256 result after the formula file is written. The `failure` and `partial-manifest-missing` fixtures do not enable the formula template and pin. `check_openshell_release_assets` now has a separate `fetch_file` failure branch for `openshell.rb`.

Workflow run details

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

[cjagwani]

Approved after refreshing onto the current base and completing the exact-revision trust-boundary review. The checker accepts only two exact operational templates, maps each to an exact immutable asset set, rejects duplicate or malformed pins, and fails closed on manifest, formula, hash, and count errors. I also ran the trusted parser and live verifier against the dependent formula transition: all three manifests, eight archives, openshell.rb, and both Brev assets matched their pinned SHA-256 values. All 51 current checks are green, contributor compliance passes, and the advisor has no blocker; its formula-download regression warning is non-blocking because the reviewed branch uses the same bounded fetch_file failure path and returns the accumulated failure count.