fix(install): add SHA-256 verification for cli.js download

[la14-1]

Why: Prevents MITM/tampered binary downloads by verifying SHA-256 of cli.js before execution — closes the last unverified download in the install path (bun installer already has hash verification).

Changes

• Downloads cli.js.sha256 companion file from the same GitHub Release
• Verifies the hash using the existing portable sha256_file() helper (works on both macOS shasum and Linux sha256sum)
• On hash mismatch: aborts with a clear error (same UX as the bun installer hash check)
• On missing checksum file (not yet published by CI): warns and continues — zero breakage for existing installs
• On missing hash tools: warns and continues (same graceful degradation as bun check)

Remaining work (separate PR, requires human review)

.github/workflows/release.yml must be updated to publish cli.js.sha256 alongside cli.js in the cli-latest release. Workflow changes are off-limits for automated PRs per team rules. Once CI publishes the checksum file, this verification activates automatically.

Fixes#3327

[la14-1]

Security Review: PR #3389 — SHA-256 verification for cli.js download

Does the fix address the vulnerability in #3327?

Partially. This PR adds the client-side verification logic to install.sh, which is the necessary first half. However, as #3327 explicitly notes, both halves are needed:

1. install.sh side (this PR): Download cli.js.sha256, verify the hash of cli.js before installing. Done correctly.
2. CI side (not in this PR): Publish cli.js.sha256 alongside cli.js in the cli-latest release. Without this, the verification is a no-op — the script gracefully degrades with "No cli.js.sha256 checksum published yet — skipping verification".

Findings

Positive:

• The sha256_file helper already exists on main (portable macOS/Linux implementation). The PR reuses it correctly.
• The tr -d '[:space:]' on the expected hash is a good defensive measure against trailing newlines in the checksum file.
• Graceful degradation is implemented at two levels: (a) no checksum file published yet, (b) no sha256sum/shasum binary available. Both log warnings instead of failing.
• The error messaging on mismatch is excellent — clear "possible supply chain attack" language with the expected vs actual hashes and a pointer to the issues page.
• The --proto '=https' flag on the checksum download enforces HTTPS, preventing downgrade attacks.
• The curl for the checksum file uses 2>/dev/null to suppress errors when the file doesn't exist yet, which is appropriate.

Concerns:

1. TOCTOU is not a risk here — the downloaded cli.js is verified in the same tmpdir before being copied to the install location. No race window.
2. The checksum file format is simple — just the hex digest, no filename. This matches the implementation (tr -d '[:space:]' strips any whitespace). Consistent with common practice.
3. Until CI publishes the .sha256 file, this provides zero protection. The graceful skip means an attacker who compromises only the cli.js artifact (but not .sha256 because it doesn't exist) gets through silently. This is acceptable as a phased rollout — the warning makes it visible that verification is not happening.

Recommendation: This PR is correct and safe to merge. The CI-side companion change (publishing cli.js.sha256 in the release workflow) should be tracked as a follow-up — without it, the verification is dormant. Is there an issue tracking the CI side?

-- refactor/security-auditor

[la14-1]

Security Review: SHA-256 Checksum Verification

Verdict: LGTM with minor notes

Strengths

1. Graceful degradation — If cli.js.sha256 is not published yet, the script warns and continues. This avoids breaking installs during the transition period.
2. Hard fail on mismatch — If the checksum file IS present but doesn't match, the script exits with a clear error and reporting instructions. Correct behavior.
3. HTTPS-only fetch — Both the binary and checksum are fetched with --proto '=https', preventing downgrade attacks.
4. Uses existing sha256_file helper — No new untested code for hashing; reuses the function already defined at line 36.

Notes (non-blocking)

1. TOCTOU between download and hash — The file is downloaded to $tmpdir/cli.js, then hashed. Since $tmpdir is a mktemp -d directory, this is safe (no symlink race). Good.
2. Checksum file format — tr -d '[:space:]' strips all whitespace including newlines. This handles both sha256sum-style output (hash + filename) and bare-hash files, but only if the file contains JUST the hash. The comment says "just the hex digest (no filename)" — make sure the release workflow matches this contract.
3. No pinning of the checksum source — Both cli.js and cli.js.sha256 come from the same GitHub release tag. An attacker who can replace one can replace both. This is a known limitation of same-origin checksums — it protects against CDN corruption/caching bugs but not a compromised release pipeline. Consider adding a note in the PR description or a follow-up issue for GPG signature verification if you want protection against release compromise.
4. Missing sha256sum tool — When sha256_file returns empty (no tool available), the script continues unverified with a warning. This is the right tradeoff for a broad-compatibility installer, but means macOS users without shasum (unlikely but possible in minimal containers) won't get verification.

Security Impact

This is a positive security improvement. It adds defense-in-depth against CDN cache poisoning and accidental artifact corruption. The same-origin limitation is acceptable for v1; GPG signatures would be the next step for full supply-chain protection.

-- refactor/security-auditor

[la14-1]

Security audit complete — verification logic is correct and safe to merge pending non-author approval.

Key correctness points:

• Reuses existing portable sha256_file helper
• Graceful degradation at two levels (no checksum file, no hash tools)
• No TOCTOU risk (verify in tmpdir before copy)
• HTTPS enforced on checksum download
• Clear error messaging on mismatch

Note: protection is dormant until CI publishes cli.js.sha256 (workflow change needed separately).

Unable to submit formal APPROVE (same author account). Another collaborator should approve and merge.

-- refactor/security-auditor

[la14-1]

Status check (2026-05-10): All CI checks passing (Biome Lint, Mock Tests, ShellCheck, Unit Tests, macOS Compatibility). Branch is mergeable with no conflicts against main. Awaiting review.

-- refactor/pr-maintainer

[la14-1]

Verified: all CI checks still passing as of 2026-05-17 (Biome Lint, Mock Tests, ShellCheck, Unit Tests, macOS Compatibility). Branch is mergeable with no conflicts. Ready for security team review.

-- refactor/pr-maintainer

[la14-1]

Still mergeable with no conflicts. All CI checks passing. This PR has been open since 2026-05-09 — requesting human review.

-- refactor/pr-maintainer

[la14-1]

Why: Prevents MITM/tampered binary downloads by verifying SHA-256 of cli.js before execution — closes the last unverified download in the install path (bun installer already has hash verification).

Changes

• Downloads cli.js.sha256 companion file from the same GitHub Release
• Verifies the hash using the existing portable sha256_file() helper (works on both macOS shasum and Linux sha256sum)
• On hash mismatch: aborts with a clear error (same UX as the bun installer hash check)
• On missing checksum file (not yet published by CI): warns and continues — zero breakage for existing installs
• On missing hash tools: warns and continues (same graceful degradation as bun check)

Remaining work (separate PR, requires human review)

.github/workflows/release.yml must be updated to publish cli.js.sha256 alongside cli.js in the cli-latest release. Workflow changes are off-limits for automated PRs per team rules. Once CI publishes the checksum file, this verification activates automatically.

Fixes#3327

[la14-1]

Security Review: PR #3389 — SHA-256 verification for cli.js download

Does the fix address the vulnerability in #3327?

Partially. This PR adds the client-side verification logic to install.sh, which is the necessary first half. However, as #3327 explicitly notes, both halves are needed:

1. install.sh side (this PR): Download cli.js.sha256, verify the hash of cli.js before installing. Done correctly.
2. CI side (not in this PR): Publish cli.js.sha256 alongside cli.js in the cli-latest release. Without this, the verification is a no-op — the script gracefully degrades with "No cli.js.sha256 checksum published yet — skipping verification".

Findings

Positive:

• The sha256_file helper already exists on main (portable macOS/Linux implementation). The PR reuses it correctly.
• The tr -d '[:space:]' on the expected hash is a good defensive measure against trailing newlines in the checksum file.
• Graceful degradation is implemented at two levels: (a) no checksum file published yet, (b) no sha256sum/shasum binary available. Both log warnings instead of failing.
• The error messaging on mismatch is excellent — clear "possible supply chain attack" language with the expected vs actual hashes and a pointer to the issues page.
• The --proto '=https' flag on the checksum download enforces HTTPS, preventing downgrade attacks.
• The curl for the checksum file uses 2>/dev/null to suppress errors when the file doesn't exist yet, which is appropriate.

Concerns:

1. TOCTOU is not a risk here — the downloaded cli.js is verified in the same tmpdir before being copied to the install location. No race window.
2. The checksum file format is simple — just the hex digest, no filename. This matches the implementation (tr -d '[:space:]' strips any whitespace). Consistent with common practice.
3. Until CI publishes the .sha256 file, this provides zero protection. The graceful skip means an attacker who compromises only the cli.js artifact (but not .sha256 because it doesn't exist) gets through silently. This is acceptable as a phased rollout — the warning makes it visible that verification is not happening.

Recommendation: This PR is correct and safe to merge. The CI-side companion change (publishing cli.js.sha256 in the release workflow) should be tracked as a follow-up — without it, the verification is dormant. Is there an issue tracking the CI side?

-- refactor/security-auditor

[la14-1]

Security Review: SHA-256 Checksum Verification

Verdict: LGTM with minor notes

Strengths

1. Graceful degradation — If cli.js.sha256 is not published yet, the script warns and continues. This avoids breaking installs during the transition period.
2. Hard fail on mismatch — If the checksum file IS present but doesn't match, the script exits with a clear error and reporting instructions. Correct behavior.
3. HTTPS-only fetch — Both the binary and checksum are fetched with --proto '=https', preventing downgrade attacks.
4. Uses existing sha256_file helper — No new untested code for hashing; reuses the function already defined at line 36.

Notes (non-blocking)

1. TOCTOU between download and hash — The file is downloaded to $tmpdir/cli.js, then hashed. Since $tmpdir is a mktemp -d directory, this is safe (no symlink race). Good.
2. Checksum file format — tr -d '[:space:]' strips all whitespace including newlines. This handles both sha256sum-style output (hash + filename) and bare-hash files, but only if the file contains JUST the hash. The comment says "just the hex digest (no filename)" — make sure the release workflow matches this contract.
3. No pinning of the checksum source — Both cli.js and cli.js.sha256 come from the same GitHub release tag. An attacker who can replace one can replace both. This is a known limitation of same-origin checksums — it protects against CDN corruption/caching bugs but not a compromised release pipeline. Consider adding a note in the PR description or a follow-up issue for GPG signature verification if you want protection against release compromise.
4. Missing sha256sum tool — When sha256_file returns empty (no tool available), the script continues unverified with a warning. This is the right tradeoff for a broad-compatibility installer, but means macOS users without shasum (unlikely but possible in minimal containers) won't get verification.

Security Impact

This is a positive security improvement. It adds defense-in-depth against CDN cache poisoning and accidental artifact corruption. The same-origin limitation is acceptable for v1; GPG signatures would be the next step for full supply-chain protection.

-- refactor/security-auditor

[la14-1]

Security audit complete — verification logic is correct and safe to merge pending non-author approval.

Key correctness points:

• Reuses existing portable sha256_file helper
• Graceful degradation at two levels (no checksum file, no hash tools)
• No TOCTOU risk (verify in tmpdir before copy)
• HTTPS enforced on checksum download
• Clear error messaging on mismatch

Note: protection is dormant until CI publishes cli.js.sha256 (workflow change needed separately).

Unable to submit formal APPROVE (same author account). Another collaborator should approve and merge.

-- refactor/security-auditor

[la14-1]

Status check (2026-05-10): All CI checks passing (Biome Lint, Mock Tests, ShellCheck, Unit Tests, macOS Compatibility). Branch is mergeable with no conflicts against main. Awaiting review.

-- refactor/pr-maintainer

[la14-1]

Verified: all CI checks still passing as of 2026-05-17 (Biome Lint, Mock Tests, ShellCheck, Unit Tests, macOS Compatibility). Branch is mergeable with no conflicts. Ready for security team review.

-- refactor/pr-maintainer

[la14-1]

Still mergeable with no conflicts. All CI checks passing. This PR has been open since 2026-05-09 — requesting human review.

-- refactor/pr-maintainer

[la14-1]

Why: Prevents MITM/tampered binary downloads by verifying SHA-256 of cli.js before execution — closes the last unverified download in the install path (bun installer already has hash verification).

Changes

• Downloads cli.js.sha256 companion file from the same GitHub Release
• Verifies the hash using the existing portable sha256_file() helper (works on both macOS shasum and Linux sha256sum)
• On hash mismatch: aborts with a clear error (same UX as the bun installer hash check)
• On missing checksum file (not yet published by CI): warns and continues — zero breakage for existing installs
• On missing hash tools: warns and continues (same graceful degradation as bun check)

Remaining work (separate PR, requires human review)

.github/workflows/release.yml must be updated to publish cli.js.sha256 alongside cli.js in the cli-latest release. Workflow changes are off-limits for automated PRs per team rules. Once CI publishes the checksum file, this verification activates automatically.

Fixes#3327

[la14-1]

Security Review: PR #3389 — SHA-256 verification for cli.js download

Does the fix address the vulnerability in #3327?

Partially. This PR adds the client-side verification logic to install.sh, which is the necessary first half. However, as #3327 explicitly notes, both halves are needed:

1. install.sh side (this PR): Download cli.js.sha256, verify the hash of cli.js before installing. Done correctly.
2. CI side (not in this PR): Publish cli.js.sha256 alongside cli.js in the cli-latest release. Without this, the verification is a no-op — the script gracefully degrades with "No cli.js.sha256 checksum published yet — skipping verification".

Findings

Positive:

• The sha256_file helper already exists on main (portable macOS/Linux implementation). The PR reuses it correctly.
• The tr -d '[:space:]' on the expected hash is a good defensive measure against trailing newlines in the checksum file.
• Graceful degradation is implemented at two levels: (a) no checksum file published yet, (b) no sha256sum/shasum binary available. Both log warnings instead of failing.
• The error messaging on mismatch is excellent — clear "possible supply chain attack" language with the expected vs actual hashes and a pointer to the issues page.
• The --proto '=https' flag on the checksum download enforces HTTPS, preventing downgrade attacks.
• The curl for the checksum file uses 2>/dev/null to suppress errors when the file doesn't exist yet, which is appropriate.

Concerns:

1. TOCTOU is not a risk here — the downloaded cli.js is verified in the same tmpdir before being copied to the install location. No race window.
2. The checksum file format is simple — just the hex digest, no filename. This matches the implementation (tr -d '[:space:]' strips any whitespace). Consistent with common practice.
3. Until CI publishes the .sha256 file, this provides zero protection. The graceful skip means an attacker who compromises only the cli.js artifact (but not .sha256 because it doesn't exist) gets through silently. This is acceptable as a phased rollout — the warning makes it visible that verification is not happening.

Recommendation: This PR is correct and safe to merge. The CI-side companion change (publishing cli.js.sha256 in the release workflow) should be tracked as a follow-up — without it, the verification is dormant. Is there an issue tracking the CI side?

-- refactor/security-auditor

[la14-1]

Security Review: SHA-256 Checksum Verification

Verdict: LGTM with minor notes

Strengths

1. Graceful degradation — If cli.js.sha256 is not published yet, the script warns and continues. This avoids breaking installs during the transition period.
2. Hard fail on mismatch — If the checksum file IS present but doesn't match, the script exits with a clear error and reporting instructions. Correct behavior.
3. HTTPS-only fetch — Both the binary and checksum are fetched with --proto '=https', preventing downgrade attacks.
4. Uses existing sha256_file helper — No new untested code for hashing; reuses the function already defined at line 36.

Notes (non-blocking)

1. TOCTOU between download and hash — The file is downloaded to $tmpdir/cli.js, then hashed. Since $tmpdir is a mktemp -d directory, this is safe (no symlink race). Good.
2. Checksum file format — tr -d '[:space:]' strips all whitespace including newlines. This handles both sha256sum-style output (hash + filename) and bare-hash files, but only if the file contains JUST the hash. The comment says "just the hex digest (no filename)" — make sure the release workflow matches this contract.
3. No pinning of the checksum source — Both cli.js and cli.js.sha256 come from the same GitHub release tag. An attacker who can replace one can replace both. This is a known limitation of same-origin checksums — it protects against CDN corruption/caching bugs but not a compromised release pipeline. Consider adding a note in the PR description or a follow-up issue for GPG signature verification if you want protection against release compromise.
4. Missing sha256sum tool — When sha256_file returns empty (no tool available), the script continues unverified with a warning. This is the right tradeoff for a broad-compatibility installer, but means macOS users without shasum (unlikely but possible in minimal containers) won't get verification.

Security Impact

This is a positive security improvement. It adds defense-in-depth against CDN cache poisoning and accidental artifact corruption. The same-origin limitation is acceptable for v1; GPG signatures would be the next step for full supply-chain protection.

-- refactor/security-auditor

[la14-1]

Security audit complete — verification logic is correct and safe to merge pending non-author approval.

Key correctness points:

• Reuses existing portable sha256_file helper
• Graceful degradation at two levels (no checksum file, no hash tools)
• No TOCTOU risk (verify in tmpdir before copy)
• HTTPS enforced on checksum download
• Clear error messaging on mismatch

Note: protection is dormant until CI publishes cli.js.sha256 (workflow change needed separately).

Unable to submit formal APPROVE (same author account). Another collaborator should approve and merge.

-- refactor/security-auditor

[la14-1]

Status check (2026-05-10): All CI checks passing (Biome Lint, Mock Tests, ShellCheck, Unit Tests, macOS Compatibility). Branch is mergeable with no conflicts against main. Awaiting review.

-- refactor/pr-maintainer

[la14-1]

Verified: all CI checks still passing as of 2026-05-17 (Biome Lint, Mock Tests, ShellCheck, Unit Tests, macOS Compatibility). Branch is mergeable with no conflicts. Ready for security team review.

-- refactor/pr-maintainer

[la14-1]

Still mergeable with no conflicts. All CI checks passing. This PR has been open since 2026-05-09 — requesting human review.

-- refactor/pr-maintainer

[la14-1]

Why: Prevents MITM/tampered binary downloads by verifying SHA-256 of cli.js before execution — closes the last unverified download in the install path (bun installer already has hash verification).

Changes

• Downloads cli.js.sha256 companion file from the same GitHub Release
• Verifies the hash using the existing portable sha256_file() helper (works on both macOS shasum and Linux sha256sum)
• On hash mismatch: aborts with a clear error (same UX as the bun installer hash check)
• On missing checksum file (not yet published by CI): warns and continues — zero breakage for existing installs
• On missing hash tools: warns and continues (same graceful degradation as bun check)

Remaining work (separate PR, requires human review)

.github/workflows/release.yml must be updated to publish cli.js.sha256 alongside cli.js in the cli-latest release. Workflow changes are off-limits for automated PRs per team rules. Once CI publishes the checksum file, this verification activates automatically.

Fixes#3327

[la14-1]

Security Review: PR #3389 — SHA-256 verification for cli.js download

Does the fix address the vulnerability in #3327?

Partially. This PR adds the client-side verification logic to install.sh, which is the necessary first half. However, as #3327 explicitly notes, both halves are needed:

1. install.sh side (this PR): Download cli.js.sha256, verify the hash of cli.js before installing. Done correctly.
2. CI side (not in this PR): Publish cli.js.sha256 alongside cli.js in the cli-latest release. Without this, the verification is a no-op — the script gracefully degrades with "No cli.js.sha256 checksum published yet — skipping verification".

Findings

Positive:

• The sha256_file helper already exists on main (portable macOS/Linux implementation). The PR reuses it correctly.
• The tr -d '[:space:]' on the expected hash is a good defensive measure against trailing newlines in the checksum file.
• Graceful degradation is implemented at two levels: (a) no checksum file published yet, (b) no sha256sum/shasum binary available. Both log warnings instead of failing.
• The error messaging on mismatch is excellent — clear "possible supply chain attack" language with the expected vs actual hashes and a pointer to the issues page.
• The --proto '=https' flag on the checksum download enforces HTTPS, preventing downgrade attacks.
• The curl for the checksum file uses 2>/dev/null to suppress errors when the file doesn't exist yet, which is appropriate.

Concerns:

1. TOCTOU is not a risk here — the downloaded cli.js is verified in the same tmpdir before being copied to the install location. No race window.
2. The checksum file format is simple — just the hex digest, no filename. This matches the implementation (tr -d '[:space:]' strips any whitespace). Consistent with common practice.
3. Until CI publishes the .sha256 file, this provides zero protection. The graceful skip means an attacker who compromises only the cli.js artifact (but not .sha256 because it doesn't exist) gets through silently. This is acceptable as a phased rollout — the warning makes it visible that verification is not happening.

Recommendation: This PR is correct and safe to merge. The CI-side companion change (publishing cli.js.sha256 in the release workflow) should be tracked as a follow-up — without it, the verification is dormant. Is there an issue tracking the CI side?

-- refactor/security-auditor

[la14-1]

Security Review: SHA-256 Checksum Verification

Verdict: LGTM with minor notes

Strengths

1. Graceful degradation — If cli.js.sha256 is not published yet, the script warns and continues. This avoids breaking installs during the transition period.
2. Hard fail on mismatch — If the checksum file IS present but doesn't match, the script exits with a clear error and reporting instructions. Correct behavior.
3. HTTPS-only fetch — Both the binary and checksum are fetched with --proto '=https', preventing downgrade attacks.
4. Uses existing sha256_file helper — No new untested code for hashing; reuses the function already defined at line 36.

Notes (non-blocking)

1. TOCTOU between download and hash — The file is downloaded to $tmpdir/cli.js, then hashed. Since $tmpdir is a mktemp -d directory, this is safe (no symlink race). Good.
2. Checksum file format — tr -d '[:space:]' strips all whitespace including newlines. This handles both sha256sum-style output (hash + filename) and bare-hash files, but only if the file contains JUST the hash. The comment says "just the hex digest (no filename)" — make sure the release workflow matches this contract.
3. No pinning of the checksum source — Both cli.js and cli.js.sha256 come from the same GitHub release tag. An attacker who can replace one can replace both. This is a known limitation of same-origin checksums — it protects against CDN corruption/caching bugs but not a compromised release pipeline. Consider adding a note in the PR description or a follow-up issue for GPG signature verification if you want protection against release compromise.
4. Missing sha256sum tool — When sha256_file returns empty (no tool available), the script continues unverified with a warning. This is the right tradeoff for a broad-compatibility installer, but means macOS users without shasum (unlikely but possible in minimal containers) won't get verification.

Security Impact

This is a positive security improvement. It adds defense-in-depth against CDN cache poisoning and accidental artifact corruption. The same-origin limitation is acceptable for v1; GPG signatures would be the next step for full supply-chain protection.

-- refactor/security-auditor

[la14-1]

Security audit complete — verification logic is correct and safe to merge pending non-author approval.

Key correctness points:

• Reuses existing portable sha256_file helper
• Graceful degradation at two levels (no checksum file, no hash tools)
• No TOCTOU risk (verify in tmpdir before copy)
• HTTPS enforced on checksum download
• Clear error messaging on mismatch

Note: protection is dormant until CI publishes cli.js.sha256 (workflow change needed separately).

Unable to submit formal APPROVE (same author account). Another collaborator should approve and merge.

-- refactor/security-auditor

[la14-1]

Status check (2026-05-10): All CI checks passing (Biome Lint, Mock Tests, ShellCheck, Unit Tests, macOS Compatibility). Branch is mergeable with no conflicts against main. Awaiting review.

-- refactor/pr-maintainer

[la14-1]

Verified: all CI checks still passing as of 2026-05-17 (Biome Lint, Mock Tests, ShellCheck, Unit Tests, macOS Compatibility). Branch is mergeable with no conflicts. Ready for security team review.

-- refactor/pr-maintainer

[la14-1]

Still mergeable with no conflicts. All CI checks passing. This PR has been open since 2026-05-09 — requesting human review.

-- refactor/pr-maintainer

[la14-1]

Why: Prevents MITM/tampered binary downloads by verifying SHA-256 of cli.js before execution — closes the last unverified download in the install path (bun installer already has hash verification).

Changes

• Downloads cli.js.sha256 companion file from the same GitHub Release
• Verifies the hash using the existing portable sha256_file() helper (works on both macOS shasum and Linux sha256sum)
• On hash mismatch: aborts with a clear error (same UX as the bun installer hash check)
• On missing checksum file (not yet published by CI): warns and continues — zero breakage for existing installs
• On missing hash tools: warns and continues (same graceful degradation as bun check)

Remaining work (separate PR, requires human review)

.github/workflows/release.yml must be updated to publish cli.js.sha256 alongside cli.js in the cli-latest release. Workflow changes are off-limits for automated PRs per team rules. Once CI publishes the checksum file, this verification activates automatically.

Fixes#3327

[la14-1]

Security Review: PR #3389 — SHA-256 verification for cli.js download

Does the fix address the vulnerability in #3327?

Partially. This PR adds the client-side verification logic to install.sh, which is the necessary first half. However, as #3327 explicitly notes, both halves are needed:

1. install.sh side (this PR): Download cli.js.sha256, verify the hash of cli.js before installing. Done correctly.
2. CI side (not in this PR): Publish cli.js.sha256 alongside cli.js in the cli-latest release. Without this, the verification is a no-op — the script gracefully degrades with "No cli.js.sha256 checksum published yet — skipping verification".

Findings

Positive:

• The sha256_file helper already exists on main (portable macOS/Linux implementation). The PR reuses it correctly.
• The tr -d '[:space:]' on the expected hash is a good defensive measure against trailing newlines in the checksum file.
• Graceful degradation is implemented at two levels: (a) no checksum file published yet, (b) no sha256sum/shasum binary available. Both log warnings instead of failing.
• The error messaging on mismatch is excellent — clear "possible supply chain attack" language with the expected vs actual hashes and a pointer to the issues page.
• The --proto '=https' flag on the checksum download enforces HTTPS, preventing downgrade attacks.
• The curl for the checksum file uses 2>/dev/null to suppress errors when the file doesn't exist yet, which is appropriate.

Concerns:

1. TOCTOU is not a risk here — the downloaded cli.js is verified in the same tmpdir before being copied to the install location. No race window.
2. The checksum file format is simple — just the hex digest, no filename. This matches the implementation (tr -d '[:space:]' strips any whitespace). Consistent with common practice.
3. Until CI publishes the .sha256 file, this provides zero protection. The graceful skip means an attacker who compromises only the cli.js artifact (but not .sha256 because it doesn't exist) gets through silently. This is acceptable as a phased rollout — the warning makes it visible that verification is not happening.

Recommendation: This PR is correct and safe to merge. The CI-side companion change (publishing cli.js.sha256 in the release workflow) should be tracked as a follow-up — without it, the verification is dormant. Is there an issue tracking the CI side?

-- refactor/security-auditor

[la14-1]

Security Review: SHA-256 Checksum Verification

Verdict: LGTM with minor notes

Strengths

1. Graceful degradation — If cli.js.sha256 is not published yet, the script warns and continues. This avoids breaking installs during the transition period.
2. Hard fail on mismatch — If the checksum file IS present but doesn't match, the script exits with a clear error and reporting instructions. Correct behavior.
3. HTTPS-only fetch — Both the binary and checksum are fetched with --proto '=https', preventing downgrade attacks.
4. Uses existing sha256_file helper — No new untested code for hashing; reuses the function already defined at line 36.

Notes (non-blocking)

1. TOCTOU between download and hash — The file is downloaded to $tmpdir/cli.js, then hashed. Since $tmpdir is a mktemp -d directory, this is safe (no symlink race). Good.
2. Checksum file format — tr -d '[:space:]' strips all whitespace including newlines. This handles both sha256sum-style output (hash + filename) and bare-hash files, but only if the file contains JUST the hash. The comment says "just the hex digest (no filename)" — make sure the release workflow matches this contract.
3. No pinning of the checksum source — Both cli.js and cli.js.sha256 come from the same GitHub release tag. An attacker who can replace one can replace both. This is a known limitation of same-origin checksums — it protects against CDN corruption/caching bugs but not a compromised release pipeline. Consider adding a note in the PR description or a follow-up issue for GPG signature verification if you want protection against release compromise.
4. Missing sha256sum tool — When sha256_file returns empty (no tool available), the script continues unverified with a warning. This is the right tradeoff for a broad-compatibility installer, but means macOS users without shasum (unlikely but possible in minimal containers) won't get verification.

Security Impact

This is a positive security improvement. It adds defense-in-depth against CDN cache poisoning and accidental artifact corruption. The same-origin limitation is acceptable for v1; GPG signatures would be the next step for full supply-chain protection.

-- refactor/security-auditor

[la14-1]

Security audit complete — verification logic is correct and safe to merge pending non-author approval.

Key correctness points:

• Reuses existing portable sha256_file helper
• Graceful degradation at two levels (no checksum file, no hash tools)
• No TOCTOU risk (verify in tmpdir before copy)
• HTTPS enforced on checksum download
• Clear error messaging on mismatch

Note: protection is dormant until CI publishes cli.js.sha256 (workflow change needed separately).

Unable to submit formal APPROVE (same author account). Another collaborator should approve and merge.

-- refactor/security-auditor

[la14-1]

Status check (2026-05-10): All CI checks passing (Biome Lint, Mock Tests, ShellCheck, Unit Tests, macOS Compatibility). Branch is mergeable with no conflicts against main. Awaiting review.

-- refactor/pr-maintainer

[la14-1]

Verified: all CI checks still passing as of 2026-05-17 (Biome Lint, Mock Tests, ShellCheck, Unit Tests, macOS Compatibility). Branch is mergeable with no conflicts. Ready for security team review.

-- refactor/pr-maintainer

[la14-1]

Still mergeable with no conflicts. All CI checks passing. This PR has been open since 2026-05-09 — requesting human review.

-- refactor/pr-maintainer

[la14-1]

Why: Prevents MITM/tampered binary downloads by verifying SHA-256 of cli.js before execution — closes the last unverified download in the install path (bun installer already has hash verification).

Changes

• Downloads cli.js.sha256 companion file from the same GitHub Release
• Verifies the hash using the existing portable sha256_file() helper (works on both macOS shasum and Linux sha256sum)
• On hash mismatch: aborts with a clear error (same UX as the bun installer hash check)
• On missing checksum file (not yet published by CI): warns and continues — zero breakage for existing installs
• On missing hash tools: warns and continues (same graceful degradation as bun check)

Remaining work (separate PR, requires human review)

.github/workflows/release.yml must be updated to publish cli.js.sha256 alongside cli.js in the cli-latest release. Workflow changes are off-limits for automated PRs per team rules. Once CI publishes the checksum file, this verification activates automatically.

Fixes#3327

[la14-1]

Security Review: PR #3389 — SHA-256 verification for cli.js download

Does the fix address the vulnerability in #3327?

Partially. This PR adds the client-side verification logic to install.sh, which is the necessary first half. However, as #3327 explicitly notes, both halves are needed:

1. install.sh side (this PR): Download cli.js.sha256, verify the hash of cli.js before installing. Done correctly.
2. CI side (not in this PR): Publish cli.js.sha256 alongside cli.js in the cli-latest release. Without this, the verification is a no-op — the script gracefully degrades with "No cli.js.sha256 checksum published yet — skipping verification".

Findings

Positive:

• The sha256_file helper already exists on main (portable macOS/Linux implementation). The PR reuses it correctly.
• The tr -d '[:space:]' on the expected hash is a good defensive measure against trailing newlines in the checksum file.
• Graceful degradation is implemented at two levels: (a) no checksum file published yet, (b) no sha256sum/shasum binary available. Both log warnings instead of failing.
• The error messaging on mismatch is excellent — clear "possible supply chain attack" language with the expected vs actual hashes and a pointer to the issues page.
• The --proto '=https' flag on the checksum download enforces HTTPS, preventing downgrade attacks.
• The curl for the checksum file uses 2>/dev/null to suppress errors when the file doesn't exist yet, which is appropriate.

Concerns:

1. TOCTOU is not a risk here — the downloaded cli.js is verified in the same tmpdir before being copied to the install location. No race window.
2. The checksum file format is simple — just the hex digest, no filename. This matches the implementation (tr -d '[:space:]' strips any whitespace). Consistent with common practice.
3. Until CI publishes the .sha256 file, this provides zero protection. The graceful skip means an attacker who compromises only the cli.js artifact (but not .sha256 because it doesn't exist) gets through silently. This is acceptable as a phased rollout — the warning makes it visible that verification is not happening.

Recommendation: This PR is correct and safe to merge. The CI-side companion change (publishing cli.js.sha256 in the release workflow) should be tracked as a follow-up — without it, the verification is dormant. Is there an issue tracking the CI side?

-- refactor/security-auditor

[la14-1]

Security Review: SHA-256 Checksum Verification

Verdict: LGTM with minor notes

Strengths

1. Graceful degradation — If cli.js.sha256 is not published yet, the script warns and continues. This avoids breaking installs during the transition period.
2. Hard fail on mismatch — If the checksum file IS present but doesn't match, the script exits with a clear error and reporting instructions. Correct behavior.
3. HTTPS-only fetch — Both the binary and checksum are fetched with --proto '=https', preventing downgrade attacks.
4. Uses existing sha256_file helper — No new untested code for hashing; reuses the function already defined at line 36.

Notes (non-blocking)

1. TOCTOU between download and hash — The file is downloaded to $tmpdir/cli.js, then hashed. Since $tmpdir is a mktemp -d directory, this is safe (no symlink race). Good.
2. Checksum file format — tr -d '[:space:]' strips all whitespace including newlines. This handles both sha256sum-style output (hash + filename) and bare-hash files, but only if the file contains JUST the hash. The comment says "just the hex digest (no filename)" — make sure the release workflow matches this contract.
3. No pinning of the checksum source — Both cli.js and cli.js.sha256 come from the same GitHub release tag. An attacker who can replace one can replace both. This is a known limitation of same-origin checksums — it protects against CDN corruption/caching bugs but not a compromised release pipeline. Consider adding a note in the PR description or a follow-up issue for GPG signature verification if you want protection against release compromise.
4. Missing sha256sum tool — When sha256_file returns empty (no tool available), the script continues unverified with a warning. This is the right tradeoff for a broad-compatibility installer, but means macOS users without shasum (unlikely but possible in minimal containers) won't get verification.

Security Impact

This is a positive security improvement. It adds defense-in-depth against CDN cache poisoning and accidental artifact corruption. The same-origin limitation is acceptable for v1; GPG signatures would be the next step for full supply-chain protection.

-- refactor/security-auditor

[la14-1]

Security audit complete — verification logic is correct and safe to merge pending non-author approval.

Key correctness points:

• Reuses existing portable sha256_file helper
• Graceful degradation at two levels (no checksum file, no hash tools)
• No TOCTOU risk (verify in tmpdir before copy)
• HTTPS enforced on checksum download
• Clear error messaging on mismatch

Note: protection is dormant until CI publishes cli.js.sha256 (workflow change needed separately).

Unable to submit formal APPROVE (same author account). Another collaborator should approve and merge.

-- refactor/security-auditor

[la14-1]

Status check (2026-05-10): All CI checks passing (Biome Lint, Mock Tests, ShellCheck, Unit Tests, macOS Compatibility). Branch is mergeable with no conflicts against main. Awaiting review.

-- refactor/pr-maintainer

[la14-1]

Verified: all CI checks still passing as of 2026-05-17 (Biome Lint, Mock Tests, ShellCheck, Unit Tests, macOS Compatibility). Branch is mergeable with no conflicts. Ready for security team review.

-- refactor/pr-maintainer

[la14-1]

Still mergeable with no conflicts. All CI checks passing. This PR has been open since 2026-05-09 — requesting human review.

-- refactor/pr-maintainer

[la14-1]

Why: Prevents MITM/tampered binary downloads by verifying SHA-256 of cli.js before execution — closes the last unverified download in the install path (bun installer already has hash verification).

Changes

• Downloads cli.js.sha256 companion file from the same GitHub Release
• Verifies the hash using the existing portable sha256_file() helper (works on both macOS shasum and Linux sha256sum)
• On hash mismatch: aborts with a clear error (same UX as the bun installer hash check)
• On missing checksum file (not yet published by CI): warns and continues — zero breakage for existing installs
• On missing hash tools: warns and continues (same graceful degradation as bun check)

Remaining work (separate PR, requires human review)

.github/workflows/release.yml must be updated to publish cli.js.sha256 alongside cli.js in the cli-latest release. Workflow changes are off-limits for automated PRs per team rules. Once CI publishes the checksum file, this verification activates automatically.

Fixes#3327

[la14-1]

Security Review: PR #3389 — SHA-256 verification for cli.js download

Does the fix address the vulnerability in #3327?

Partially. This PR adds the client-side verification logic to install.sh, which is the necessary first half. However, as #3327 explicitly notes, both halves are needed:

1. install.sh side (this PR): Download cli.js.sha256, verify the hash of cli.js before installing. Done correctly.
2. CI side (not in this PR): Publish cli.js.sha256 alongside cli.js in the cli-latest release. Without this, the verification is a no-op — the script gracefully degrades with "No cli.js.sha256 checksum published yet — skipping verification".

Findings

Positive:

• The sha256_file helper already exists on main (portable macOS/Linux implementation). The PR reuses it correctly.
• The tr -d '[:space:]' on the expected hash is a good defensive measure against trailing newlines in the checksum file.
• Graceful degradation is implemented at two levels: (a) no checksum file published yet, (b) no sha256sum/shasum binary available. Both log warnings instead of failing.
• The error messaging on mismatch is excellent — clear "possible supply chain attack" language with the expected vs actual hashes and a pointer to the issues page.
• The --proto '=https' flag on the checksum download enforces HTTPS, preventing downgrade attacks.
• The curl for the checksum file uses 2>/dev/null to suppress errors when the file doesn't exist yet, which is appropriate.

Concerns:

1. TOCTOU is not a risk here — the downloaded cli.js is verified in the same tmpdir before being copied to the install location. No race window.
2. The checksum file format is simple — just the hex digest, no filename. This matches the implementation (tr -d '[:space:]' strips any whitespace). Consistent with common practice.
3. Until CI publishes the .sha256 file, this provides zero protection. The graceful skip means an attacker who compromises only the cli.js artifact (but not .sha256 because it doesn't exist) gets through silently. This is acceptable as a phased rollout — the warning makes it visible that verification is not happening.

Recommendation: This PR is correct and safe to merge. The CI-side companion change (publishing cli.js.sha256 in the release workflow) should be tracked as a follow-up — without it, the verification is dormant. Is there an issue tracking the CI side?

-- refactor/security-auditor

[la14-1]

Security Review: SHA-256 Checksum Verification

Verdict: LGTM with minor notes

Strengths

1. Graceful degradation — If cli.js.sha256 is not published yet, the script warns and continues. This avoids breaking installs during the transition period.
2. Hard fail on mismatch — If the checksum file IS present but doesn't match, the script exits with a clear error and reporting instructions. Correct behavior.
3. HTTPS-only fetch — Both the binary and checksum are fetched with --proto '=https', preventing downgrade attacks.
4. Uses existing sha256_file helper — No new untested code for hashing; reuses the function already defined at line 36.

Notes (non-blocking)

1. TOCTOU between download and hash — The file is downloaded to $tmpdir/cli.js, then hashed. Since $tmpdir is a mktemp -d directory, this is safe (no symlink race). Good.
2. Checksum file format — tr -d '[:space:]' strips all whitespace including newlines. This handles both sha256sum-style output (hash + filename) and bare-hash files, but only if the file contains JUST the hash. The comment says "just the hex digest (no filename)" — make sure the release workflow matches this contract.
3. No pinning of the checksum source — Both cli.js and cli.js.sha256 come from the same GitHub release tag. An attacker who can replace one can replace both. This is a known limitation of same-origin checksums — it protects against CDN corruption/caching bugs but not a compromised release pipeline. Consider adding a note in the PR description or a follow-up issue for GPG signature verification if you want protection against release compromise.
4. Missing sha256sum tool — When sha256_file returns empty (no tool available), the script continues unverified with a warning. This is the right tradeoff for a broad-compatibility installer, but means macOS users without shasum (unlikely but possible in minimal containers) won't get verification.

Security Impact

This is a positive security improvement. It adds defense-in-depth against CDN cache poisoning and accidental artifact corruption. The same-origin limitation is acceptable for v1; GPG signatures would be the next step for full supply-chain protection.

-- refactor/security-auditor

[la14-1]

Security audit complete — verification logic is correct and safe to merge pending non-author approval.

Key correctness points:

• Reuses existing portable sha256_file helper
• Graceful degradation at two levels (no checksum file, no hash tools)
• No TOCTOU risk (verify in tmpdir before copy)
• HTTPS enforced on checksum download
• Clear error messaging on mismatch

Note: protection is dormant until CI publishes cli.js.sha256 (workflow change needed separately).

Unable to submit formal APPROVE (same author account). Another collaborator should approve and merge.

-- refactor/security-auditor

[la14-1]

Status check (2026-05-10): All CI checks passing (Biome Lint, Mock Tests, ShellCheck, Unit Tests, macOS Compatibility). Branch is mergeable with no conflicts against main. Awaiting review.

-- refactor/pr-maintainer

[la14-1]

Verified: all CI checks still passing as of 2026-05-17 (Biome Lint, Mock Tests, ShellCheck, Unit Tests, macOS Compatibility). Branch is mergeable with no conflicts. Ready for security team review.

-- refactor/pr-maintainer

[la14-1]

Still mergeable with no conflicts. All CI checks passing. This PR has been open since 2026-05-09 — requesting human review.

-- refactor/pr-maintainer

[la14-1]

Why: Prevents MITM/tampered binary downloads by verifying SHA-256 of cli.js before execution — closes the last unverified download in the install path (bun installer already has hash verification).

Changes

• Downloads cli.js.sha256 companion file from the same GitHub Release
• Verifies the hash using the existing portable sha256_file() helper (works on both macOS shasum and Linux sha256sum)
• On hash mismatch: aborts with a clear error (same UX as the bun installer hash check)
• On missing checksum file (not yet published by CI): warns and continues — zero breakage for existing installs
• On missing hash tools: warns and continues (same graceful degradation as bun check)

Remaining work (separate PR, requires human review)

.github/workflows/release.yml must be updated to publish cli.js.sha256 alongside cli.js in the cli-latest release. Workflow changes are off-limits for automated PRs per team rules. Once CI publishes the checksum file, this verification activates automatically.

Fixes#3327

[la14-1]

Security Review: PR #3389 — SHA-256 verification for cli.js download

Does the fix address the vulnerability in #3327?

Partially. This PR adds the client-side verification logic to install.sh, which is the necessary first half. However, as #3327 explicitly notes, both halves are needed:

1. install.sh side (this PR): Download cli.js.sha256, verify the hash of cli.js before installing. Done correctly.
2. CI side (not in this PR): Publish cli.js.sha256 alongside cli.js in the cli-latest release. Without this, the verification is a no-op — the script gracefully degrades with "No cli.js.sha256 checksum published yet — skipping verification".

Findings

Positive:

• The sha256_file helper already exists on main (portable macOS/Linux implementation). The PR reuses it correctly.
• The tr -d '[:space:]' on the expected hash is a good defensive measure against trailing newlines in the checksum file.
• Graceful degradation is implemented at two levels: (a) no checksum file published yet, (b) no sha256sum/shasum binary available. Both log warnings instead of failing.
• The error messaging on mismatch is excellent — clear "possible supply chain attack" language with the expected vs actual hashes and a pointer to the issues page.
• The --proto '=https' flag on the checksum download enforces HTTPS, preventing downgrade attacks.
• The curl for the checksum file uses 2>/dev/null to suppress errors when the file doesn't exist yet, which is appropriate.

Concerns:

1. TOCTOU is not a risk here — the downloaded cli.js is verified in the same tmpdir before being copied to the install location. No race window.
2. The checksum file format is simple — just the hex digest, no filename. This matches the implementation (tr -d '[:space:]' strips any whitespace). Consistent with common practice.
3. Until CI publishes the .sha256 file, this provides zero protection. The graceful skip means an attacker who compromises only the cli.js artifact (but not .sha256 because it doesn't exist) gets through silently. This is acceptable as a phased rollout — the warning makes it visible that verification is not happening.

Recommendation: This PR is correct and safe to merge. The CI-side companion change (publishing cli.js.sha256 in the release workflow) should be tracked as a follow-up — without it, the verification is dormant. Is there an issue tracking the CI side?

-- refactor/security-auditor

[la14-1]

Security Review: SHA-256 Checksum Verification

Verdict: LGTM with minor notes

Strengths

1. Graceful degradation — If cli.js.sha256 is not published yet, the script warns and continues. This avoids breaking installs during the transition period.
2. Hard fail on mismatch — If the checksum file IS present but doesn't match, the script exits with a clear error and reporting instructions. Correct behavior.
3. HTTPS-only fetch — Both the binary and checksum are fetched with --proto '=https', preventing downgrade attacks.
4. Uses existing sha256_file helper — No new untested code for hashing; reuses the function already defined at line 36.

Notes (non-blocking)

1. TOCTOU between download and hash — The file is downloaded to $tmpdir/cli.js, then hashed. Since $tmpdir is a mktemp -d directory, this is safe (no symlink race). Good.
2. Checksum file format — tr -d '[:space:]' strips all whitespace including newlines. This handles both sha256sum-style output (hash + filename) and bare-hash files, but only if the file contains JUST the hash. The comment says "just the hex digest (no filename)" — make sure the release workflow matches this contract.
3. No pinning of the checksum source — Both cli.js and cli.js.sha256 come from the same GitHub release tag. An attacker who can replace one can replace both. This is a known limitation of same-origin checksums — it protects against CDN corruption/caching bugs but not a compromised release pipeline. Consider adding a note in the PR description or a follow-up issue for GPG signature verification if you want protection against release compromise.
4. Missing sha256sum tool — When sha256_file returns empty (no tool available), the script continues unverified with a warning. This is the right tradeoff for a broad-compatibility installer, but means macOS users without shasum (unlikely but possible in minimal containers) won't get verification.

Security Impact

This is a positive security improvement. It adds defense-in-depth against CDN cache poisoning and accidental artifact corruption. The same-origin limitation is acceptable for v1; GPG signatures would be the next step for full supply-chain protection.

-- refactor/security-auditor

[la14-1]

Security audit complete — verification logic is correct and safe to merge pending non-author approval.

Key correctness points:

• Reuses existing portable sha256_file helper
• Graceful degradation at two levels (no checksum file, no hash tools)
• No TOCTOU risk (verify in tmpdir before copy)
• HTTPS enforced on checksum download
• Clear error messaging on mismatch

Note: protection is dormant until CI publishes cli.js.sha256 (workflow change needed separately).

Unable to submit formal APPROVE (same author account). Another collaborator should approve and merge.

-- refactor/security-auditor

[la14-1]

Status check (2026-05-10): All CI checks passing (Biome Lint, Mock Tests, ShellCheck, Unit Tests, macOS Compatibility). Branch is mergeable with no conflicts against main. Awaiting review.

-- refactor/pr-maintainer

[la14-1]

Verified: all CI checks still passing as of 2026-05-17 (Biome Lint, Mock Tests, ShellCheck, Unit Tests, macOS Compatibility). Branch is mergeable with no conflicts. Ready for security team review.

-- refactor/pr-maintainer

[la14-1]

Still mergeable with no conflicts. All CI checks passing. This PR has been open since 2026-05-09 — requesting human review.

-- refactor/pr-maintainer