Skip to content

fix(link): verify recorded runtime paths before probing - #840

Draft
luvs01 wants to merge 5 commits into
devfrom
fix/remote-recorded-runtime-trust
Draft

luvs01 wants to merge 5 commits into
devfrom
fix/remote-recorded-runtime-trust

Conversation

@luvs01

@luvs01 luvs01 commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Summary

Remote Link treats a recorded runtime path as a discovery hint. Previously its first version probe could execute the recorded binary or package entrypoint before checking who controls that path.

  • Verify the executable and optional entrypoint before any version probe in POSIX discovery, pinned sync, runtime inspection and full-install census.
  • Admit recorded targets on Linux only: require a regular file owned by the SSH account without group/world write bits, and walk original and symlink-target components to check directory replacement authority. Trusted sticky directories remain compatible; traversal is bounded.
  • Preserve the original verified Linux path spelling for package-prefix and entrypoint compatibility. Missing ownership/stat/readlink/platform evidence, symlink loops and ambiguous newline targets skip the record.
  • Skip macOS records as discovery authority before probing that candidate. Mode bits omit ACL grants, and Apple's ls can silently treat an ACL read failure as an absent ACL. Reusing macOS hints needs a native ACL reader that distinguishes those outcomes along the entire path. Existing Desktop, system and PATH discovery continues.
  • Update the owning Remote Link contract and English/Korean operator guidance.

Addresses the Daybreak finding and the macOS ACL review finding.

Current base: c36793a9336b70cfe5bc3b7f6e6f751e730fb6fc. Current head: 06ba9b29f68e9ccf997b2d142dddc8b11516d3d0. Independently reviewed current tree: 80cead81554d9047e432c33e4f92c49af11642f5.

The earlier implementation and verification below used base e87572127d7804216ebfcf0feecaf4c22c181748 and tree 8beec34186cc08bd34d214a233425c5dcfcc5d15.

Compatibility and limits

A macOS installation available only through its runtime record is no longer selected or detected. Add it to the SSH account's PATH or install it in an existing discovery location. Full-install census, including the --require-ephemeral check, can only detect the remaining known install locations on macOS; it may proceed when a record-only full install exists. This change does not execute or remove that undiscovered installation.

This change removes the extra execution authority provided by arbitrary census paths. Existing Desktop/system locations and the SSH account's PATH retain their prior executable/version checks; this PR does not add ownership or ACL validation to those fallback locations. A path rejected through the census can still execute if it is independently selected through one of those locations. A controlled writable-Desktop fixture produces the same calls across all four consumers with and without a census record, confirming that this is an existing fallback policy rather than authority granted by the record.

The checks do not claim protection against root or unrestricted same-account mutation. The shell checks do not bind an opened executable descriptor through execution.

Verification

Current maintenance verification — 2026-11-17

  • Merged current dev c36793a without dropping either the recorded-runtime trust contract or the newer Windows census/packed-script contract. The test-layout fixture retains all 3,285 base mappings plus this PR's new trust test, in the existing compact format.
  • Corrected the BSD stat fallback to %u %Mp%03Lp: the middle field preserves sticky/setuid/setgid bits, and the zero-padded low field preserves values such as 1007 and 4005. GNU formatting and the Linux-only admission gate are unchanged. This follows Apple's field handling and format specification.
  • The BSD metadata shim now models both the old and corrected formats. The strengthened regression fails on the previous production source because a sticky ancestor is read as non-sticky; it passes with the correction and checks both zero-padding examples.
  • Final focused run: 74 passed / 18 Windows skips / 0 failed / 393 assertions across discovery and trust tests. Typecheck (2,565 files), structure, privacy, file-size ratchet and whitespace checks passed. An independent review of the final two-file change found no blocker.
  • Earlier merge verification: 206 passed / 22 platform skips across eight functional/layout files, then 9 size-ratchet tests / 85 assertions passed. The earlier merge's documentation CI built successfully.
  • Final-head hosted CI passed: main workflow, attempt 2, Catalog async contracts, PR gates and CodeQL. All five Linux shards and the requested build/package checks succeeded.
  • The first post-merge CI run reached batch 62 of 63 in Linux shard 2/5 before its 15-minute job limit. On the final head's first attempt, the other four shards passed; shard 3/5 completed all 64 batches with zero failed tests, then hit the 15-minute limit during finalization. The job annotation confirmed the timeout. Only that cancelled job was retried; successful jobs were retained, and no timeout or assertion threshold was relaxed.
  • The sticky-bit review thread is resolved. Native macOS/Windows execution, live SSH, and installed-application validation are not claimed. The local BSD behavior uses a semantic shim on Linux. The PR remains Draft for maintainer security review and platform acceptance.

Historical verification before this maintenance pass

Verification on Linux, Bun 1.4.4, isolated local filesystem and harmless executable fixtures:

  • Production candidate cefa181: 235 passed / 20 Windows skips / 0 failed / 1,491 assertions across link-served-runtime-trust, link-ssh-argv-discovery, link-gated-ocx-argv, link-pinned-sync-argv, link-child-update-launcher, link-full-install-census, link-ssh-argv, both test-layout guards and the file-size ratchet.
  • Final test-fixture correction 1f312fd: 74 passed / 18 Windows skips / 0 failed / 383 assertions across discovery and trust tests; typecheck, privacy, size and whitespace checks passed again. The correction keeps trust tools present when census-tool regressions are tested, without changing production code or the default fixture tools.
  • The trust file contains 30 cases: all four consumers reject writable binaries and entrypoints before execution; owner/ancestor/symlink/missing-tool/newline cases cover the Linux gate. Eight Darwin cases prove both binary and package records are skipped before any probe and that controlled known-install fallbacks still work. Unknown platforms also fail closed.
  • The original final 20-case regression file on unchanged base production source: 17 failed / 3 compatibility controls passed. The final 30-case file on prior published head 7b6a9a17: 10 new platform regressions failed / 20 Linux controls passed.
  • bun run typecheck: 2,537 files, no errors. bun run structure:check, bun run privacy:scan, bun scripts/file-size-ratchet.ts and staged whitespace checks passed.
  • Documentation build: 775 pages / 117,814 internal links. It reused already-installed dependencies whose package manifest and lockfile matched this checkout.
  • Independent source review of both the original resolver and the final Linux-only correction found no remaining concrete blocker. The review covered shared consumer ordering, symlink/sticky-parent checks, original path spelling, fallback behavior and the macOS detection tradeoff.

Foreign-owner and BSD-format metadata use local shims. Darwin behavior uses a synthetic uname fixture, not a macOS host. No live SSH endpoint, provider, real credential, Windows runtime or installed application was exercised.

The broad local suite and test:changed were not run because the broader graph previously selected a real provider. Focused scripts execute only generated shell against local fixtures. Historical automatic CI passed for head 1f312fd00ffc81246889d5f3bb35b13f3c538717: main workflow and Catalog async contracts. The main workflow tested PR merge preview 795de27612d26baf833427413563cd24bede5f46; all 15 executed jobs, including all five Ubuntu test shards, passed. Native macOS/Windows lanes were skipped by repository policy. Final-head hygiene and Devin status also passed; the two original review threads were resolved. CodeRabbit completed its full review on cefa181 with one fixture-isolation comment, addressed in 1f312fd after independent review. The macOS ACL finding was also fixed and Devin confirmed it resolved. At that earlier stage, a new full CodeRabbit request was not made after the included review allowance was exhausted. This PR remains Draft for maintainer security review and platform acceptance.

Checklist

  • Scope stays focused and avoids unrelated cleanup.
  • Docs or release notes were updated when needed.
  • Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

The last item records implementation and independent source review, not maintainer approval.

Summary by CodeRabbit

  • Security
    • Linux Remote Link now uses recorded installations only when their ownership and permissions can be verified; otherwise, it skips them.
    • macOS skips recorded installations because their access permissions cannot be reliably verified.
    • Both platforms continue to discover installations through Desktop, system locations, and PATH. On macOS, installations available only through recorded paths must be made discoverable another way.
  • Documentation
    • Updated the Remote Link guides to explain these checks and clarify that a successful version response alone does not verify ownership.

@coderabbitai

coderabbitai Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Explain Change →

Walkthrough

The SSH runtime flow now checks recorded executable and package-entry paths before attempting them. Linux paths must pass ownership and permission checks. Recorded candidates are skipped on macOS and unverified platforms. Tests and documentation cover these rules and fallback discovery.

Changes: Recorded Runtime Trust

Layer / File(s) Summary
Validate recorded runtime paths
src/link/remote-runtime-trust.ts, src/link/ssh-argv.ts, structure/remote-link.md, docs-site/src/content/docs/guides/remote-link.md, docs-site/src/content/docs/ko/guides/remote-link.md
The shared check validates Linux served paths, including ownership, permissions, path components, and symlink traversal. The SSH runtime flow checks the binary and any supplied package entry before attempting the recorded runtime. The documentation describes platform-specific checks and discovery behavior.
Test trust checks and fallback behavior
tests/clients/link-served-runtime-trust.test.ts, tests/clients/link-*-argv.test.ts, tests/clients/link-child-update-launcher.test.ts, scripts/test-layout/layout-clients.json, tests/fixtures/test-layout-expected.json
Tests cover trusted and untrusted recorded paths, platform-specific skips, and fallback when required tools are unavailable. POSIX fixtures provide Linux-reporting uname commands and path-inspection utilities. The new test is classified in the client layout.

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

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant RemoteSSH
  participant TrustedServedPath
  participant RecordedRuntime
  participant DiscoveryFallback
  RemoteSSH->>TrustedServedPath: Validate recorded binary path
  TrustedServedPath-->>RemoteSSH: Return path or reject
  RemoteSSH->>TrustedServedPath: Validate supplied package entry
  TrustedServedPath-->>RemoteSSH: Return path or reject
  RemoteSSH->>RecordedRuntime: Attempt runtime when paths pass
  RemoteSSH->>DiscoveryFallback: Continue discovery when validation fails
Loading

Suggested reviewers: lidge-jun, ingwannu

Merge Risk: Low · up to 1f62b

Recorded runtime paths are now verified before use, and macOS skips them. A small test-fixture/fallback gap could make some tests fail on macOS developer machines whose temp directory resolves through a sticky /tmp. Production behavior is not affected, so merge risk is low.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title "fix(link): verify recorded runtime paths before probing" states the main change. The changeset adds trust checks (ownership, permissions, symlinks, path components) for recorded runtime pat…
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.
Full details: Title check

Explanation

The title "fix(link): verify recorded runtime paths before probing" states the main change. The changeset adds trust checks (ownership, permissions, symlinks, path components) for recorded runtime paths and runs them before version probes in POSIX discovery, pinned sync, inspection, and census. The title is short, specific, and uses a conventional commit prefix. It does not mention the macOS skip behavior, but that is a secondary effect.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

✅ Deterministic PR hygiene checks passed.

@github-actions github-actions Bot added the bug Something isn't working label Nov 16, 2026
devin-ai-integration[bot]

This comment was marked as resolved.

luvs01 commented Nov 16, 2026

Copy link
Copy Markdown
Owner Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Action not completed

Review rate limited.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

luvs01 commented Nov 16, 2026

Copy link
Copy Markdown
Owner Author

@coderabbitai review

Please review the latest head cefa181f516c69414f395625128c50c2cc33b95b, including the fail-closed treatment of recorded runtime hints on Darwin and unknown platforms.

@coderabbitai

coderabbitai Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

coderabbitai[bot]

This comment was marked as resolved.

Preserve POSIX recorded-path trust checks and current Windows census and packed-command behavior. Preserve both sides of the test-layout registry without changing its established formatting.

Validation: focused synthetic/loopback coverage, typecheck, structure and privacy checks; file-size gate passed after retaining the upstream registry format. Independent conflict-resolution review found no blocker.
@luvs01

luvs01 commented Nov 17, 2026

Copy link
Copy Markdown
Owner Author

No description provided.

coderabbitai[bot]

This comment was marked as resolved.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant