fix(npm): explain aube trust downgrade failures

[jdx]

Summary

• explain that an embedded aube trust downgrade is a supply-chain signal rather than ordinary version resolution
• tell users to inspect the npm release, source, publisher identity, and tarball for tampering
• direct users to report inconsistent publishing evidence upstream before bypassing the check
• recommend version-scoped trust_policy_excludes entries and describe the broader risk of package-wide exclusions or npm.shell_out=true
• add the same investigation guidance to the npm backend docs

Context

mise replaces aube's .npmrc-oriented remediation because mise owns the synthetic install project and exposes trust_policy_excludes as a tool option. That replacement needs to retain the richer security context being added in jdx/aube#1110.

Validation

• cargo fmt --check
• cargo test test_build_aube_install_error_message_trust_downgrade
• mise run docs:build
• mise run lint-fix

The pre-existing untracked .claude/worktrees/ and xtasks/fig/ directories were not included.

---

Note

Low Risk
User-facing error text and documentation only; no install or trust-policy behavior changes.

Overview
Expands embedded aube trust-downgrade remediation so ERR_AUBE_TRUST_DOWNGRADE is framed as a supply-chain signal (weaker trust evidence vs an earlier release), not a normal version-resolution error.

The npm backend’s build_aube_install_error_message now walks users through investigation before bypass: review release metadata, source, publisher, and tarball; compare with npmjs.org; report drift to maintainers vs registry operators. It recommends version-scoped trust_policy_excludes (<package>@<version>), warns that bare package names exempt all versions, and treats npm.shell_out=true as a last resort that skips the check, with a link to aube’s trust-policy docs.

Docs add a matching Investigating trust downgrades section under trust_policy_excludes in the npm backend guide. Unit tests assert the new message content.

^{Reviewed by Cursor Bugbot for commit b9a5bab. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• Bug Fixes

  • Improved trust-downgrade error messages for npm to include clearer supply-chain/provenance investigation steps.
  • Recommend adding narrowly scoped <package>@<version> exceptions for affected releases.

• Documentation

  • Added troubleshooting guidance for npm trust-policy failures, including validation steps, reporting inconsistencies upstream, and a reference guide.
  • Documented when and how npm.shell_out=true bypasses the trust-policy check.

[coderabbitai]

📝 Walkthrough

Walkthrough

Expanded npm trust-downgrade error messaging, updated its test assertions, and added documentation covering investigation steps, version-scoped exclusions, bypass behavior, and related aube resources.

Changes

npm trust downgrade guidance

Layer / File(s)	Summary
Runtime error guidance src/backend/npm.rs	The ERR_AUBE_TRUST_DOWNGRADE message now provides detailed provenance investigation, narrow version-scoped exclusion, bypass, and guide-link guidance; tests assert the revised content.
Investigation documentation docs/dev-tools/backends/npm.md	Documents the meaning of trustPolicy=no-downgrade, investigation checklist, exception strategy, bypass setting, and aube resources.

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

Possibly related PRs

• jdx/mise#11226: Updates the same npm trust-downgrade error handling and related tests.

Poem

I’m a rabbit with a careful ear,
Chasing trust clues far and near.
Version by version, paths made clear,
Safe little exceptions hop here.
Aube’s guide shines bright—no fear!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and accurately highlights the main change: improved npm/aube trust-downgrade failure guidance.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[greptile-apps]

Greptile Summary

Improves guidance for npm trust-downgrade failures.

• Expands the aube error message with investigation and reporting steps.
• Recommends version-scoped trust-policy exceptions and warns against broad bypasses.
• Adds equivalent guidance to the npm backend documentation.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
src/backend/npm.rs	Expands trust-downgrade remediation text and updates unit assertions without changing install or trust-policy behavior.
docs/dev-tools/backends/npm.md	Documents investigation, reporting, and narrowly scoped exception guidance for trust downgrades.

_{Reviews (2): Last reviewed commit: "fix(npm): refine trust downgrade guidanc..." | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 3

🤖 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 `@src/backend/npm.rs`:
- Around line 1182-1186: Update the user-facing trust-failure wording in
src/backend/npm.rs lines 1182-1186 and docs/dev-tools/backends/npm.md lines
301-303 to describe the selected release as having weaker trust evidence, rather
than implying trust evidence is completely absent. Keep both paths consistent
with Aube’s tiered trust policy and preserve the surrounding explanation.
- Around line 1184-1190: Revise the warning text in src/backend/npm.rs lines
1184-1190 and the corresponding documentation in docs/dev-tools/backends/npm.md
lines 309-312 so it does not assert that the package maintainer’s release
process failed; instruct users to report inconsistent trust evidence to the
relevant upstream owner or registry operator, since either may need to correct
stripped or missing metadata.
- Around line 1196-1197: Fix the broken trust-policy investigation link by
either publishing the missing route or replacing it with a live canonical URL.
Update both occurrences: src/backend/npm.rs lines 1196-1197 in the user-facing
guidance and docs/dev-tools/backends/npm.md lines 319-320, keeping both
references consistent.

🪄 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: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: ddcbc8dd-27fe-4c8b-806c-1e43dea4f583

📥 Commits

Reviewing files that changed from the base of the PR and between 623967f and d2ec432.

📒 Files selected for processing (2)

• docs/dev-tools/backends/npm.md
• src/backend/npm.rs

[github-actions]

Hyperfine Performance

mise x -- echo

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2026.7.13 x -- echo	17.7 ± 0.8	16.3	27.1	1.00
mise x -- echo	19.3 ± 1.3	17.6	33.2	1.09 ± 0.09

mise env

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2026.7.13 env	16.7 ± 0.7	15.5	19.8	1.00
mise env	18.1 ± 0.7	16.8	21.6	1.08 ± 0.06

mise hook-env

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2026.7.13 hook-env	17.6 ± 0.7	16.1	21.3	1.00
mise hook-env	19.0 ± 0.9	17.6	23.9	1.08 ± 0.07

mise ls

Command	Mean [ms]	Min [ms]	Max [ms]	Relative
mise-2026.7.13 ls	14.9 ± 0.6	13.7	17.6	1.00
mise ls	16.2 ± 0.8	14.7	21.3	1.09 ± 0.07

xtasks/test/perf

Command	mise-2026.7.13	mise	Variance
install (cached)	149ms	164ms	-9%
ls (cached)	56ms	58ms	-3%
bin-paths (cached)	58ms	61ms	-4%
task-ls (cached)	121ms	125ms	-3%