Skip to content

chore(openshell): trust v0.0.101 release identities - #8616

Open
apurvvkumaria wants to merge 4 commits into
mainfrom
codex/8598-openshell-v101-release-trust
Open

chore(openshell): trust v0.0.101 release identities#8616
apurvvkumaria wants to merge 4 commits into
mainfrom
codex/8598-openshell-v101-release-trust

Conversation

@apurvvkumaria

@apurvvkumaria apurvvkumaria commented Aug 8, 2026

Copy link
Copy Markdown
Collaborator

Summary

Establish base-trusted identities for the published OpenShell v0.0.101 release without changing NemoClaw's active v0.0.99 selection. The checker now binds checksum manifests, the Homebrew formula, and standalone sandbox fallback binaries to reviewed release identities so a later selector PR cannot authorize its own artifacts.

Related Issue

Fixes #8598

Changes

  • Add exact v0.0.101 CLI, gateway, and sandbox checksum-manifest hashes to the existing trusted allowlist.
  • Bind every allowlisted Homebrew formula to its exact release version, canonical GitHub asset URL, and SHA-256 digest.
  • Bind the installer's standalone sandbox fallback map to base-reviewed version/digest pairs, including dormant v0.0.101 x86_64 and arm64 identities.
  • Model all 20 official v0.0.101 manifest entries and verify positive, legacy, malformed, missing, remapped, and self-authorization paths through the trusted checker/parser boundary.

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: The change adds dormant supply-chain trust anchors and verifier hardening; supported selectors, installer/blueprint pins, CLI behavior, configuration, defaults, and user-facing errors remain on v0.0.99.
  • 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: Independent nine-category review of exact commit 6ace3b8d657d3d65589d9ce61fe4672400f30955 returned PASS with no blocker. It independently recomputed the v0.0.101 artifacts and confirmed the base-owned formula tuple and standalone sandbox version/digest sets close both candidate self-authorization paths.
  • 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: No documentation paths changed. The reviewer inspected the exact four-file diff plus the documentation rules/navigation and confirmed this is dormant trust data with fail-closed verifier enforcement only; stable runtime, blueprint, installer, and Brev selectors remain on v0.0.99 with no user-facing behavior or configuration change.
  • Agent: Codex Desktop

DGX Station Hardware Evidence

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

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: installer checker tests (78 passed); sandbox identity tests (12 passed); four changed-contract consumer files (51 passed, with one local-load timeout rerun unchanged at a 60-second bound); live scripts/check-installer-hash.sh passed on the current v0.0.99 selection.
  • 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 dormant trust data and its verifier boundary. npm run validate:pr, npm run checks:repository, npm run typecheck:cli, npm run test:changed, test-size/source-shape checks, shfmt, and ShellCheck 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: Apurv Kumaria akumaria@nvidia.com

Summary by CodeRabbit

  • Security

    • Strengthened installer verification with trusted release digests, Homebrew formula records, and sandbox-build identities.
    • Added safeguards against missing, duplicate, malformed, unauthorized, or mismatched release metadata.
    • Improved diagnostics to distinguish formula digest mismatches from installer pin mismatches.
  • Release Support

    • Added verification coverage for OpenShell 0.0.101 and other supported releases.
  • Testing

    • Expanded automated coverage for release integrity and metadata validation.

Signed-off-by: Apurv Kumaria <akumaria@nvidia.com>
Signed-off-by: Apurv Kumaria <akumaria@nvidia.com>
@apurvvkumaria apurvvkumaria self-assigned this Aug 8, 2026
@coderabbitai

coderabbitai Bot commented Aug 8, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

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: 8e337266-f198-42bb-aa4a-9b400a30447d

📥 Commits

Reviewing files that changed from the base of the PR and between 6ace3b8 and a69b6c9.

📒 Files selected for processing (1)
  • test/installer-hash-check.test.ts

📝 Walkthrough

Walkthrough

The installer trust checks now use allowlisted Homebrew formulas and trusted sandbox-build identities. Tests cover OpenShell 0.0.101, malformed trust data, mismatched digests, duplicate entries, alternate releases, and parser mutations.

Changes

OpenShell release trust

Layer / File(s) Summary
Trusted Homebrew formula verification
scripts/check-installer-hash.sh, test/installer-hash-check.test.ts
The checker selects exactly one allowlisted formula, validates its URL and upstream digest, then compares the installer pin separately. Tests cover formula mismatches, self-authorization, malformed entries, duplicates, and invalid URLs.
Trusted sandbox-build identity validation
scripts/checks/extract-installer-pins.mts, test/installer-sandbox-build-trust.test.ts
The parser validates required and selected-release sandbox identities against the trusted allowlist. Tests reject arbitrary, incomplete, duplicated, malformed, and release-mismatched identities.
Release fixture and end-to-end validation
test/installer-hash-check.test.ts
Fixtures now index trusted manifests, asset digests, formula entries, and sandbox identities by release. End-to-end tests verify OpenShell 0.0.101 and reject untrusted alternate-release prerequisites.

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

Sequence Diagram(s)

sequenceDiagram
  participant Installer as Installer
  participant Checker as check-installer-hash.sh
  participant Formula as Homebrew formula
  participant Parser as extract-installer-pins.mts
  Installer->>Checker: Submit release and installer pins
  Checker->>Formula: Download allowlisted formula
  Formula-->>Checker: Return formula content
  Checker->>Checker: Verify upstream digest and formula pin
  Checker->>Parser: Validate extracted sandbox-build pins
  Parser-->>Checker: Return trusted identity result
  Checker-->>Installer: Accept or reject release identities
Loading

Possibly related issues

  • NVIDIA/NemoClaw issue 8590 — Covers the OpenShell v0.0.101 release-trust and installer-pin requirements addressed here.

Possibly related PRs

Suggested labels: release-target, v0.0.105

Suggested reviewers: cv, senthilr-nv

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Linked Issues check ⚠️ Warning The PR adds v0.0.101 trust data, but the provided changes do not show required v0.0.99/v0.0.85 baselines or supervisor and VM driver identities from [#8598]. Add the missing baseline and artifact identities, or document where existing trusted entries satisfy those requirements before merging.
✅ 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 identifies the main change: adding trust for OpenShell v0.0.101 release identities.
Out of Scope Changes check ✅ Passed The scripts and tests directly support release-identity trust validation and do not change selectors, runtime behavior, policy behavior, or documentation.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
✨ Finishing Touches 💡 1
🛠️ Fix failing CI checks 💡
  • Create stacked PR
  • Commit on current branch
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/8598-openshell-v101-release-trust

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

@github-code-quality

github-code-quality Bot commented Aug 8, 2026

Copy link
Copy Markdown
Contributor

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit 414de88 in the codex/8598-openshell... branch remains at 96%, unchanged from commit c6fb802 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 414de88 in the codex/8598-openshell... branch remains at 81%, unchanged from commit a76e297 in the main branch.

Show a code coverage summary of the most impacted files.
File main a76e297 codex/8598-openshell... 414de88 +/-
src/lib/onboard...an-lifecycle.ts 95% 79% -16%
src/lib/policy/index.ts 63% 61% -2%
src/lib/onboard...trap/adapter.ts 68% 70% +2%
src/lib/onboard...mo-lifecycle.ts 84% 86% +2%
src/lib/onboard...cker-journal.ts 70% 75% +5%
src/lib/onboard...ne-authority.ts 84% 91% +7%
src/lib/onboard...strap/docker.ts 64% 72% +8%
src/lib/onboard.../docker-spec.ts 65% 74% +9%
src/lib/onboard...shared-state.ts 73% 90% +17%
src/lib/policy/...ateway-state.ts 56% 73% +17%

Updated August 08, 2026 13:17 UTC

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
test/installer-hash-check.test.ts (1)

639-691: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Assert that anchored mutations actually change the source.

CHECKER_MUTATIONS and PARSER_MUTATIONS use String.prototype.replace with long literal anchors, for example "readonly -a OPENSHELL_RELEASE_FORMULA_ALLOWLIST=(\n" at line 651 and "const TRUSTED_SANDBOX_BUILD_PINS: readonly TrustedSandboxBuildPin[] = [\n" at line 682. If a later refactor changes those anchors, replace returns the source unchanged and the mutation becomes a silent no-op.

A silent no-op does not make the negative tests error. It makes them pass for the wrong reason. For example, trusted-sandbox-alternate-version at line 1146 expects failure. If trustAlternateSandboxBuilds no-ops, the run still fails, but because the sandbox identities were never trusted, not because the release lacks an allowlist entry.

test/installer-sandbox-build-trust.test.ts already guards this at lines 49-53. Apply the same guard here.

♻️ Proposed guard for anchored replacements
+const replaceAnchored = (source: string, anchor: string, replacement: string): string => {
+  const mutated = source.replace(anchor, replacement);
+  if (mutated === source) {
+    throw new Error(`fixture mutation anchor no longer matches: ${anchor}`);
+  }
+  return mutated;
+};

Then route the anchored mutations through it, for example:

-const trustAlternateSandboxBuilds = (source: string): string => {
-  const digests = SYNTHETIC_SANDBOX_BUILD_DIGESTS;
-  return source.replace(
-    "const TRUSTED_SANDBOX_BUILD_PINS: readonly TrustedSandboxBuildPin[] = [\n",
-    `const TRUSTED_SANDBOX_BUILD_PINS: readonly TrustedSandboxBuildPin[] = [
-  { required: false, sha256: "${digests[0]}", version: "9.9.9" },
-  { required: false, sha256: "${digests[1]}", version: "9.9.9" },
-`,
-  );
-};
+const trustAlternateSandboxBuilds = (source: string): string => {
+  const digests = SYNTHETIC_SANDBOX_BUILD_DIGESTS;
+  return replaceAnchored(
+    source,
+    "const TRUSTED_SANDBOX_BUILD_PINS: readonly TrustedSandboxBuildPin[] = [\n",
+    `const TRUSTED_SANDBOX_BUILD_PINS: readonly TrustedSandboxBuildPin[] = [
+  { required: false, sha256: "${digests[0]}", version: "9.9.9" },
+  { required: false, sha256: "${digests[1]}", version: "9.9.9" },
+`,
+  );
+};

Apply the same treatment to the allowlisted-alternate-version, duplicate-trusted-formula, malformed-trusted-formula, mismatched-trusted-formula-url, and trusted-formula-mismatch entries.

🤖 Prompt for 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.

In `@test/installer-hash-check.test.ts` around lines 639 - 691, Add a shared
checked-replacement helper in the installer hash-check tests that asserts each
anchor is found and the resulting source changes, then use it for the anchored
replacements in CHECKER_MUTATIONS and trustAlternateSandboxBuilds, including the
allowlisted, duplicate, malformed, URL-mismatch, and digest-mismatch formula
mutations. Preserve each mutation’s existing replacement behavior while
preventing silent no-ops.

Source: Path instructions

🤖 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.

Nitpick comments:
In `@test/installer-hash-check.test.ts`:
- Around line 639-691: Add a shared checked-replacement helper in the installer
hash-check tests that asserts each anchor is found and the resulting source
changes, then use it for the anchored replacements in CHECKER_MUTATIONS and
trustAlternateSandboxBuilds, including the allowlisted, duplicate, malformed,
URL-mismatch, and digest-mismatch formula mutations. Preserve each mutation’s
existing replacement behavior while preventing silent no-ops.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 856b1b40-dbb4-438c-9b26-ee3384dc64dc

📥 Commits

Reviewing files that changed from the base of the PR and between a76e297 and 6ace3b8.

📒 Files selected for processing (4)
  • scripts/check-installer-hash.sh
  • scripts/checks/extract-installer-pins.mts
  • test/installer-hash-check.test.ts
  • test/installer-sandbox-build-trust.test.ts

@github-actions

github-actions Bot commented Aug 8, 2026

Copy link
Copy Markdown
Contributor

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): Failed after a partial review · low confidence · 0 blockers · 0 warnings · 0 suggestions

Second-opinion terminology and E2E selections are advisory. Live E2E does not run automatically for pull requests.

3 semantic terminology decisions

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

  • established — base-trusted at scripts/check-installer-hash.sh:53: Keep base-trusted for verifier code and identity data that execute from the base commit.
  • justified — standalone sandbox binary identities at scripts/checks/extract-installer-pins.mts:691: Keep standalone sandbox binary identities when distinguishing extracted fallback binaries from release-asset identities.
  • justified — formula allowlist at scripts/check-installer-hash.sh:223: Keep formula allowlist for the Homebrew formula identity records.

E2E guidance

Advisory only. A maintainer can dispatch the default E2E suite against this exact revision.

Recommended E2E: managed-image-multiarch-startup

Workflow run details

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

Signed-off-by: Apurv Kumaria <akumaria@nvidia.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Record OpenShell v0.0.101 baselines and release trust

2 participants