Skip to content

fix(link): a link with an explicit route reads no ssh_config - #8657

Merged
lidge-jun merged 5 commits into
devfrom
fix/link-explicit-route-no-ssh-config
Nov 13, 2026
Merged

lidge-jun merged 5 commits into
devfrom
fix/link-explicit-route-no-ssh-config

Conversation

@lidge-jun

@lidge-jun lidge-jun commented Nov 13, 2026 •

Copy link
Copy Markdown
Owner

Summary

A Home-initiated link enrolled with an explicit, exclusive route (ocx link add <alias> --proxy-command <cmd> --ssh-user <user> --ssh-port <port> --exclusive, which a hub passes for the disposable machines it attaches) still read the owner's ~/.ssh/config and /etc/ssh/ssh_config. The route options win on the command line where a setting has a single value. List-valued settings add to them, though, and other settings apply untouched. Shown with ssh -G against a hostile config on OpenSSH 9.6:

  • Forwards: the tunnel picked up the config's Local, Remote and Dynamic forwards next to its own -R. No command-line option can remove a configured forward, and ClearAllForwardings would remove the tunnel's own -R too.
  • Environment, keys, agent and GSSAPI: SendEnv, SetEnv, extra IdentityFile and CertificateFile entries, IdentityAgent, GSSAPI delegation, Tunnel and CanonicalizeHostname applied to every command.
  • RemoteCommand: a configured RemoteCommand made every exec of the link fail ("Cannot execute command-line and remote command").
  • The stock system config: the stock Ubuntu /etc/ssh/ssh_config alone already adds SendEnv LANG LC_* and GSSAPIAuthentication yes.

Now the shared option list in src/link/ssh-argv.ts starts with -F none whenever the record carries an explicit route. The decision is made from the route itself (routeOptions returns the -F none part for every route, placed before every -o), not from whether the route produced any options. This applies to every command such a link runs: the tunnel, every exec (enrollment, plant, revoke and purge, platform discovery, Child operations, ocx sync fan-out), the probe and confirm-host, the route probe and the Windows probe. Each one now uses only the route's ProxyCommand, user and port, the pinned HostKeyAlias and private known_hosts file, and the link's own options.

The tunnel keeps a single -R with ExitOnForwardFailure=yes and no ClearAllForwardings. Every link SSH command is built in ssh-argv.ts; src/link/remote-windows.ts builds only the remote PowerShell command, and the SSH runner passes argv through unchanged.

What -F none takes away

ssh then reads no configuration file, so the Home's identity comes only from two places:

  • the agent named by SSH_AUTH_SOCK in the OpenCodex process's environment;
  • the default ~/.ssh/id_* key files.

An IdentityFile, CertificateFile or IdentityAgent set in ssh_config is no longer used. On macOS, UseKeychain and Apple's other ssh_config defaults stop applying too. A dev user whose explicit-route link relied on an IdentityFile in ssh_config will see that link failed with reason auth after this change, and a new enrollment of such a machine fails with probe_failed. The key must be in the Home's agent or in a default ~/.ssh/id_* file; the guide says so. No release contains explicit routes (#8615 is in no tag; the latest release, v2.100.2, predates it), so nobody on a release is affected. The route carries no identity field in this PR. Notes for that follow-up (link.route/2):

  • IdentitiesOnly stays at its default, so a Home with many agent keys offers all of them. A server with a low MaxAuthTries then answers "Too many authentication failures", which also reads as auth.
  • A caller whose machines are configured with IdentityFile and IdentitiesOnly yes in ssh_config must load that key into the Home's agent when it uses explicit routes, or the route needs an identity field.

What stays unchanged

Links without an explicit route read ssh_config exactly as before: ordinary alias links, which need it for HostName, User, Port, ProxyJump and IdentityFile, plus Child-initiated links and messaging. Their argv is byte-identical to dev, pinned by the literal argv of all five builders in tests/clients/link-explicit-route.test.ts. ocx link routes add is unaffected, because an exclusive link already refuses added routes.

  • OpenSSH versions: -F none exists since OpenSSH 7.1, below the client the link options already require (KnownHostsCommand needs 8.5).
  • Windows: Win32-OpenSSH treats -F none the same way; no NUL device is involved.

Verification

Test-first: tests/clients/link-explicit-route-no-ssh-config.test.ts (new, registered in the test layout).

  • Argv per builder: each of the five has -F none exactly once, before the destination. The tunnel has one forward, ExitOnForwardFailure=yes and no ClearAllForwardings. Builders without a route contain no -F.
  • Older ssh -G check: the check in tests/clients/link-explicit-route.test.ts still reads a hostile ssh_config on purpose. It is named and commented as the second line of defence: the route on the command line would win even if ssh_config were read.
  • Real ssh -G (connects to nothing, never runs the ProxyCommand): a hostile config in a temp directory includes another file and sets forwards, SendEnv, SetEnv, IdentityFile, CertificateFile, IdentityAgent, ControlPersist, GSSAPI with delegation, Tunnel and RemoteCommand. The test first swaps the link's -F none for -F <hostile file> and shows that the hostile values appear and that an exec then fails. It then runs the real argv of each builder and shows that none of them appear and that the tunnel's only forward is its own. Skipped on Windows and where ssh is not on PATH.
  • Failing first: four of the six tests failed on dev, because there was no -F none. The two that passed pin behaviour that does not change: the tunnel's single forward, and the absence of -F without a route.

Commands on f85f252 (bun 1.4.4, TMPDIR=/tmp):

  • bun run typecheck → exit 0
  • bun run privacy:scan → exit 0
  • bun run structure:check → exit 0
  • bun run skill:surface:check → exit 0
  • bun scripts/test.ts --parallel=2 over tests/clients/link-, tests/server/link-, tests/cli/cli-link*, the remote messaging tests, the test-layout, layout-tooling, file-size ratchet, structure, skill-ocx, docs-spanish-localization, docs-remote-hub-claims and docs-link-targets tests, and tests/lab/core-link-boundary and core-lab-boundary (128 files) → exit 1: 2126 pass, 23 skip, 3 fail. The 3 failures are the Rust-toolchain cases under NOT RUN; they fail the same way on dev.
  • git merge-tree --write-tree origin/dev HEAD → exit 0 against dev 6f58f62 (with feat(link): recover a force-revoked ephemeral Child by its link id (ocx-child owner record /2, detach --expect-link, ocx link recover) #8612).

NOT RUN:

  • the full bun run test suite (this machine runs focused files only);
  • tests/clients/link-ocx-child-e2e.test.ts (2 cases) and the Rust conformance runner in tests/clients/link-ocx-child-conformance.test.ts, which need a Rust toolchain this machine lacks;
  • a real SSH connection through an explicit route;
  • Windows and macOS (the real ssh -G test ran on Linux only).

Review: an independent read-only reviewer covered the first two commits in one round and reported no findings at any level; it ran the explicit-route test files, the real ssh -G cases included (85 pass). The final review then approved with three nits, fixed in the last three commits: the -F none decision now follows from the route itself, the older ssh -G check is named as the second line of defence, and the guide says what a user sees when the key is not offered.

Docs: structure/remote-link.md "Explicit route" says why the link reads no ssh_config and what that takes away. The Remote Link guide (English and Spanish) says the same in one paragraph, including what a user sees when the key is not offered. The --proxy-command capability text (ocx link probe and ocx link add) and its generated skill reference say "the link then reads no ssh_config (-F none): the Home offers its SSH agent's keys or a default ~/.ssh/id_* key".

Checklist

  • Targets dev
  • Behaviour changes in src/ have focused regression tests in their domain folders, registered in the test layout maps
  • Owned structure doc updated in the same change
  • Links without an explicit route are unchanged (pinned)
  • No GUI change

The final review of GOAT's disposable-machines groundwork showed with ssh -G
that the owner's ~/.ssh/config and /etc/ssh/ssh_config still apply to a link
enrolled with an explicit exclusive route: list-valued settings (Local, Remote
and Dynamic forwards, SendEnv, IdentityFile, CertificateFile) add to ours,
SetEnv, IdentityAgent, GSSAPI delegation and Tunnel apply, a configured
RemoteCommand makes every exec fail ("Cannot execute command-line and remote
command"), and no command-line option can remove a configured forward from the
tunnel.

The shared option list now starts with -F none when the record carries an
explicit route, for every command such a link runs (tunnel, exec, probe, route
probe, Windows probe). The route already names the transport, user and port, and
the host key is pinned. The tunnel keeps its single -R with ExitOnForwardFailure
and no ClearAllForwardings, which would remove its own forward. Links without an
explicit route keep reading ssh_config; their argv is unchanged.
… key comes from

structure/remote-link.md, the Remote Link guide (English and Spanish) and the
--proxy-command capability text (with the generated skill reference) now say
that a link with an explicit route reads no SSH configuration (-F none), why,
and what that takes away: the Home offers only its SSH agent's keys and the
default ~/.ssh/id_* keys, so an IdentityFile set in ssh_config is not used, and
on macOS UseKeychain and Apple's other defaults stop applying.
@coderabbitai

coderabbitai Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 4 seconds.

Check out review usage here.

View limit details

Limit details: You’ve used all 10 included reviews currently available.

Learn how review limits work.

Review configuration:

Run configuration

Commits

Reviewing files that changed from the base of the PR and between f23910a and f85f252.

Files selected for processing: 10

  • docs-site/src/content/docs/es/guides/remote-link.md
  • docs-site/src/content/docs/guides/remote-link.md
  • scripts/test-layout/layout-clients.json
  • skills/ocx/references/01_surface_access-remote.md
  • src/cli/capabilities-base.ts
  • src/link/ssh-argv.ts
  • structure/remote-link.md
  • tests/clients/link-explicit-route-no-ssh-config.test.ts
  • tests/clients/link-explicit-route.test.ts
  • tests/fixtures/test-layout-expected.json
  • 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 13, 2026 •

Copy link
Copy Markdown
Contributor

✅ Deterministic PR hygiene checks passed.

@github-actions github-actions Bot added the bug Something isn't working label Nov 13, 2026
…-empty option list

Final review of #8657 (P3): commonOptions added -F none when the route's option list was non-empty, an indirect test for 'this link has an explicit route'; a future route form whose options were empty would silently read ssh_config again. routeOptions now returns {configFile, options}, with configFile ["-F", "none"] for every route and placed first in the argv, before every -o. The argv is unchanged; the pinned literal tests and the -F none tests pass.
Final review of #8657 (P3): the effective() helper slices the argv from its first -o and so drops -F none; the test 'an ssh_config edit after enrollment' checks what ssh would use if it read ssh_config, which the code no longer does. It stays as a second line of defence (the route on the command line would still win), now said in its name and a comment.
… offered

Final review of #8657 (P3): after the sentence that an IdentityFile from ssh_config is no longer used, the Remote Link guide (English and Spanish) now says what follows when the machine expects another key: an existing link reads failed with reason auth, a new enrollment fails with probe_failed, and the key must be in the Home's agent or a default ~/.ssh/id_* file.
@lidge-jun lidge-jun closed this Nov 13, 2026
@lidge-jun lidge-jun reopened this Nov 13, 2026
@lidge-jun lidge-jun closed this Nov 13, 2026
@lidge-jun lidge-jun reopened this Nov 13, 2026
@lidge-jun
lidge-jun marked this pull request as ready for review November 13, 2026 07:39
@lidge-jun
lidge-jun requested a review from Ingwannu as a code owner November 13, 2026 07:39
@lidge-jun
lidge-jun merged commit a7402e8 into dev Nov 13, 2026
77 of 96 checks passed
@lidge-jun
lidge-jun deleted the fix/link-explicit-route-no-ssh-config branch November 13, 2026 07:39
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-13T07:40:20.624756Z f85f252 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@lidge-jun

Copy link
Copy Markdown
Owner Author

Maintainer integration record for the squash merge a7402e8.

lidge-jun added a commit that referenced this pull request Nov 13, 2026
One conflict, docs-site/src/content/docs/es/guides/remote-link.md: this branch
keeps the journal paragraph before the recover paragraph (the English order),
and the recover paragraph is #8661's updated one, with its new alias_linked
sentence. capabilities-base.ts carries #8657's -F none sentence once in each of
the two --proxy-command flags (probe and add) beside this branch's edits; the
skills reference is regenerated on the merged tree (51 declared capabilities).
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