diff --git a/README.md b/README.md index 5c30c84..32bf766 100644 --- a/README.md +++ b/README.md @@ -27,9 +27,21 @@ flowchart LR The desktop app reads concrete SSH aliases from `~/.ssh/config`, resolves them with OpenSSH, and starts the remote Codex app server through the remote user's login shell. `codex` must therefore be on that shell's `PATH`. +### Account and profile boundary + +A reachable SSH host is not enough: the alias's `User` chooses the remote Windows account and therefore its profile, projects, Codex CLI installation, and local authentication state. Treat these as one deliberate mapping: + +| Item | Must identify | Why it matters | +| --- | --- | --- | +| SSH alias | One host **and** one `User` | A previously working alias can still log in as the wrong Windows account. | +| Target Windows profile | The account that owns the intended desktop/Codex project | `%USERPROFILE%`, `%LOCALAPPDATA%`, project files, and Codex state are profile-specific. | +| Recovery access | A separate, tested alias/key | Keep it intact while adding or changing a profile-specific Codex connection. | + +If the work must run in a particular signed-in Windows desktop profile, select that account first. Do not repoint an existing host alias merely because it reaches the same machine; create a new, clearly named alias for the intended profile and keep the old recovery alias until the new one passes preflight. + ## Status and verification boundary -**Last reviewed:** 2026-08-16. This guide is based on one community reproduction, not a compatibility guarantee. The optional reference bridge source is experimental and has only local build/self-test coverage in this repository; validate it on an isolated host before relying on it. +**Last reviewed:** 2026-08-17. This guide is based on community reproductions, not a compatibility guarantee. The optional reference bridge source is experimental and has only local build/self-test coverage in this repository; validate it on an isolated host before relying on it. | Component | Community reference baseline | | --- | --- | @@ -51,8 +63,9 @@ OpenAI documents generic SSH-host remote projects: concrete aliases, a usable re ### Remote Windows host - Windows OpenSSH Server, reachable only over LAN, VPN, or a mesh network. +- A known target Windows user profile. If the project must share a particular desktop profile, that exact account must be used by the SSH alias. - A dedicated, least-privilege Windows user. -- Codex CLI installed and authenticated for that remote user. +- Codex CLI installed and authenticated for that exact remote user/profile. - A login shell where `codex --version` succeeds. - A remote project folder. @@ -60,7 +73,13 @@ OpenAI documents generic SSH-host remote projects: concrete aliases, a usable re ## Quick setup -### 1. Create a dedicated SSH key locally +### 1. Choose the target remote Windows profile + +Before generating a key or changing an existing SSH alias, write down the intended remote Windows account, project folder, and whether it is the account currently signed in at the target desktop. A host nickname such as `` is not an account selection. + +If an older alias already reaches the host, treat it as recovery access only until you prove which account it uses. Do not copy a Codex auth file, a private key, or a profile directory from that old account to the new one. + +### 2. Create a dedicated SSH key locally In local PowerShell: @@ -72,7 +91,7 @@ ssh-keygen -t ed25519 ` Keep `id_ed25519_codex_win` private. Install only `id_ed25519_codex_win.pub` on the remote host. -### 2. Install the public key on the remote host +### 3. Install the public key on the remote host Using an existing secure administrative route, add the public-key line to: @@ -80,6 +99,8 @@ Using an existing secure administrative route, add the public-key line to: C:\Users\\.ssh\authorized_keys ``` +On Windows, confirm the target account's *effective* `AuthorizedKeysFile` locally before editing: an OpenSSH administrator match rule can select a different file. An administrator can inspect it with `sshd -T -C user=,host=localhost,addr=127.0.0.1`; keep that output private. Do not assume another account's key path is correct. + Use restrictive ownership and ACLs on `.ssh` and `authorized_keys`. Prefer a non-administrator account dedicated to this purpose. Test the key in a second session before changing server authentication policy. If you administer the SSH server and intend to disable passwords, do that only after key authentication and a recovery path are verified: @@ -90,14 +111,14 @@ PasswordAuthentication no KbdInteractiveAuthentication no ``` -### 3. Add a concrete SSH alias locally +### 4. Add a concrete SSH alias locally Create or update `%USERPROFILE%\.ssh\config`: ```sshconfig -Host codex-win +Host codex-win-target HostName - User + User IdentityFile ~/.ssh/id_ed25519_codex_win IdentitiesOnly yes PreferredAuthentications publickey @@ -105,15 +126,19 @@ Host codex-win KbdInteractiveAuthentication no ``` -Use a literal alias such as `codex-win`; pattern-only `Host` entries are not discoverable by Codex. +Use a literal, profile-specific alias such as `codex-win-target`; pattern-only `Host` entries are not discoverable by Codex. Do not overwrite an existing alias that may intentionally use another Windows account. -### 4. Verify before using the desktop app +### 5. Verify the target profile before using the desktop app ```powershell -ssh -o BatchMode=yes codex-win "codex --version" -ssh -G codex-win +$alias = 'codex-win-target' +ssh -G $alias +ssh -T -o BatchMode=yes $alias "whoami" +ssh -T -o BatchMode=yes $alias "codex --version" ``` +Confirm that `whoami` is the intended Windows account, not merely an account that can reach the same host. If it is wrong, stop and create a new profile-specific alias/key; do not reuse the old account's Codex files or tokens. + On the remote login shell, also check: ```bash @@ -122,12 +147,12 @@ codex --version printf 'SHELL=%s\n' "$SHELL" ``` -Then run the [manual preflight](docs/preflight.md). A successful `codex --version` alone can be a false positive on Windows: it does not prove that Codex's multiline POSIX bootstrap and clean stdio proxy will work. +Then run the [manual preflight](docs/preflight.md). A successful `codex --version` alone can be a false positive on Windows: it does not prove that Codex's multiline POSIX bootstrap, the intended profile's `$SHELL`, and a clean stdio proxy will work. -### 5. Add the remote project in the desktop app +### 6. Add the remote project in the desktop app 1. Open **Settings → Connections → SSH**. -2. Add or enable `codex-win`. +2. Add or enable `codex-win-target`. 3. Choose the remote project folder. 4. Start a chat in that remote project. @@ -137,15 +162,17 @@ Commands, files, tools, credentials, and approvals belong to the remote host and | Symptom | Likely meaning | Safe check | | --- | --- | --- | -| `Permission denied (publickey)` | Key, account, or ACL problem | `ssh -vvv codex-win` | -| The host is absent from the app | Alias is not concrete or config cannot be resolved | `ssh -G codex-win` | +| `Permission denied (publickey)` | Key, account, or ACL problem | `ssh -vvv ` | +| The host is absent from the app | Alias is not concrete or config cannot be resolved | `ssh -G ` | +| Authentication succeeds but the expected project, Codex state, or desktop profile is missing | The alias selected a different Windows account | Compare `ssh -G ` with `ssh -T "whoami"`; create a new alias for the intended profile and retain the old recovery alias | | Authenticated, then `codex: command not found` | Login-shell `PATH` is incomplete | `command -v codex` on the remote shell | -| `unexpected EOF` or quote errors after authentication | Windows SSH may be passing a POSIX bootstrap through an incompatible command interpreter | Validate the configured login shell; use a reviewed bridge only as an advanced workaround | +| `unexpected EOF` or quote errors after authentication | Windows SSH may be passing a POSIX bootstrap through an incompatible command interpreter | Validate the configured login shell and target profile; use a reviewed bridge only as an advanced workaround | +| `codex --version` passes, but Desktop still fails or reports shell noise | `$SHELL` can still point to an incompatible command interpreter, or an interactive shell can emit non-protocol bytes | Run the optional inner-shell probe in the [manual preflight](docs/preflight.md); use a reviewed bridge only if the account-specific path needs it | | `socket hangup` | Network/sleep/app state, CLI-version drift, noisy shell output, or a stale control process/socket can all contribute | Check reachability, host sleep, Desktop and CLI versions, then sanitized metadata-only logs; never delete a socket owned by a live process | ### Advanced Windows shell workaround -Some Windows OpenSSH installations default to `cmd.exe`, which can corrupt multi-line POSIX shell bootstrap commands. The preferred fix is an administrator-reviewed POSIX-compatible default login shell with a correct `PATH`. +Some Windows OpenSSH installations default to `cmd.exe`, which can corrupt multi-line POSIX shell bootstrap commands. The preferred fix is an administrator-reviewed POSIX-compatible default login shell with a correct `PATH`. Verify it under the selected target profile: changing the server shell alone may not correct a stale `$SHELL` environment variable or interactive-shell diagnostics. If that is impossible, use a **separate key reserved for the bridge** and a reviewed native bridge that preserves SSH stdin/stdout/stderr unchanged. This does **not** make the key Codex-confined: a bridge that accepts arbitrary `SSH_ORIGINAL_COMMAND` can still execute commands as the remote Windows user if the key is compromised. Keep an unforced recovery key, do not log raw protocol streams, and treat the bridge as an advanced deployment artifact—not a universal copy-paste fix. @@ -157,6 +184,7 @@ Read the [bridge boundary and threat model](docs/security-model.md) before deplo - [ ] The private key stays on the local computer. - [ ] The repository, SSH config, and logs contain no passwords, private keys, tokens, real hostnames, or IP addresses. +- [ ] Each Codex alias maps to the intended Windows account/profile; a previously working host alias is retained as recovery access until the new profile passes preflight. - [ ] The remote account is least privilege and separate from an administrator account. - [ ] NTFS ACLs limit that remote account to the intended project data; Codex auth/token files are never copied between hosts. - [ ] The SSH host-key fingerprint is verified out of band on first connection; never use `StrictHostKeyChecking=no`. diff --git a/README.zh-TW.md b/README.zh-TW.md index c7a93f1..a350dc0 100644 --- a/README.zh-TW.md +++ b/README.zh-TW.md @@ -27,9 +27,21 @@ flowchart LR Desktop 會從 `~/.ssh/config` 讀取具體 SSH alias、以 OpenSSH 解析,並透過遠端使用者的登入 shell 啟動 remote Codex app-server。因此 `codex` 必須能在該登入 shell 的 `PATH` 找到。 +### 帳號與使用者設定檔邊界 + +SSH 主機可連線還不夠:alias 裡的 `User` 決定遠端 Windows 帳號,也就決定其使用者設定檔、專案、Codex CLI 安裝位置與本機授權狀態。請把下列項目視為同一個明確對應: + +| 項目 | 必須先確認 | 為何重要 | +| --- | --- | --- | +| SSH alias | 一台主機**與**一個 `User` | 原本可用的 alias 仍可能登入錯的 Windows 帳號。 | +| 目標 Windows 使用者設定檔 | 擁有預期桌面/Codex 專案的帳號 | `%USERPROFILE%`、`%LOCALAPPDATA%`、專案檔與 Codex 狀態都屬於各自的 profile。 | +| 復原連線 | 另一組已驗證的 alias/key | 新增或改用特定 profile 的 Codex 連線時,保留它。 | + +若工作必須在特定已登入的 Windows 桌面 profile 中執行,先選定那個帳號。不要只因為既有 alias 能連到同一台主機就直接改它;應為目標 profile 建立名稱清楚的新 alias,並在它通過 preflight 前保留舊 alias 作為復原路徑。 + ## 支援狀態與驗證邊界 -**最後檢視:** 2026-08-16。本文件源自一套社群實作環境,不是相容性保證。選用的 reference bridge 原始碼仍是實驗性質;本 repo 目前只有本機 build/self-test 覆蓋,部署前務必先在隔離主機驗證。 +**最後檢視:** 2026-08-17。本文件源自社群實作環境,不是相容性保證。選用的 reference bridge 原始碼仍是實驗性質;本 repo 目前只有本機 build/self-test 覆蓋,部署前務必先在隔離主機驗證。 | 元件 | 社群參考基線 | | --- | --- | @@ -51,8 +63,9 @@ OpenAI 文件說明的是通用 SSH 遠端專案:具體 alias、可用的遠 ### 遠端 Windows 主機 - 正在執行 Windows OpenSSH Server,且只能由 LAN、VPN 或 mesh network 到達。 +- 一個已確認的目標 Windows 使用者設定檔;若專案要與特定桌面 profile 共用,SSH alias 必須使用該帳號。 - 一個低權限的專用 Windows 帳號。 -- 已在該遠端帳號下安裝並完成授權的 Codex CLI。 +- 已在該**正確遠端帳號/profile**下安裝並完成授權的 Codex CLI。 - 一個能成功執行 `codex --version` 的登入 shell。 - 遠端專案資料夾。 @@ -60,7 +73,13 @@ OpenAI 文件說明的是通用 SSH 遠端專案:具體 alias、可用的遠 ## 快速設定 -### 1. 在本機建立專用 SSH 金鑰 +### 1. 先選擇目標遠端 Windows profile + +建立金鑰或修改既有 SSH alias 前,先寫下預期的遠端 Windows 帳號、專案資料夾,以及它是否就是目標電腦目前登入桌面的帳號。像 `` 這類主機暱稱不是帳號選擇。 + +若舊 alias 已能連到主機,在確認它登入哪個帳號之前,只把它當成復原連線。不要從舊帳號複製 Codex auth、私鑰或整個 profile 到新帳號。 + +### 2. 在本機建立專用 SSH 金鑰 在本機 PowerShell 執行: @@ -72,7 +91,7 @@ ssh-keygen -t ed25519 ` `id_ed25519_codex_win` 是私鑰,僅留在本機。遠端只能安裝 `id_ed25519_codex_win.pub`。 -### 2. 在遠端安裝公開金鑰 +### 3. 在遠端安裝公開金鑰 透過既有且安全的管理管道,將公開金鑰的完整單行內容加入: @@ -80,6 +99,8 @@ ssh-keygen -t ed25519 ` C:\Users\\.ssh\authorized_keys ``` +在 Windows 上編輯前,先在本機確認目標帳號**實際套用的** `AuthorizedKeysFile`:OpenSSH 的 administrator match rule 可能選用不同檔案。管理員可用 `sshd -T -C user=,host=localhost,addr=127.0.0.1` 查核;輸出請自行保留。不可假設另一個帳號的 key path 也正確。 + `.ssh` 與 `authorized_keys` 要有嚴格的擁有者與 ACL。建議使用專用的一般帳號,不要使用管理員帳號。改動 server 驗證規則前,務必先以另一個工作階段驗證金鑰連線。 若你管理 SSH server 且要關閉密碼驗證,請只在金鑰與復原管道都驗證成功後設定: @@ -90,14 +111,14 @@ PasswordAuthentication no KbdInteractiveAuthentication no ``` -### 3. 在本機建立具體 SSH alias +### 4. 在本機建立具體 SSH alias 建立或修改 `%USERPROFILE%\.ssh\config`: ```sshconfig -Host codex-win +Host codex-win-target HostName - User + User IdentityFile ~/.ssh/id_ed25519_codex_win IdentitiesOnly yes PreferredAuthentications publickey @@ -105,15 +126,19 @@ Host codex-win KbdInteractiveAuthentication no ``` -請使用像 `codex-win` 這樣具體的 alias;只有 pattern 的 `Host` 項目不會被 Codex 自動發現。 +請使用像 `codex-win-target` 這樣具體、且能辨識 profile 的 alias;只有 pattern 的 `Host` 項目不會被 Codex 自動發現。不要覆寫可能刻意使用另一個 Windows 帳號的既有 alias。 -### 4. 在開啟 Desktop 前驗證 +### 5. 在開啟 Desktop 前驗證目標 profile ```powershell -ssh -o BatchMode=yes codex-win "codex --version" -ssh -G codex-win +$alias = 'codex-win-target' +ssh -G $alias +ssh -T -o BatchMode=yes $alias "whoami" +ssh -T -o BatchMode=yes $alias "codex --version" ``` +確認 `whoami` 顯示的是預期 Windows 帳號,而不是只要能登入同一台主機的另一個帳號。若不正確,請停止並建立新的 profile 專用 alias/key;不要重用舊帳號的 Codex 檔案或 token。 + 登入遠端 shell 後,也應確認: ```bash @@ -122,12 +147,12 @@ codex --version printf 'SHELL=%s\n' "$SHELL" ``` -接著執行[手動 preflight](docs/preflight.zh-TW.md)。單靠 `codex --version` 成功可能是 Windows 的假陽性:它不能證明 Codex 的多行 POSIX bootstrap 與乾淨的 stdio proxy 能正常運作。 +接著執行[手動 preflight](docs/preflight.zh-TW.md)。單靠 `codex --version` 成功可能是 Windows 的假陽性:它不能證明 Codex 的多行 POSIX bootstrap、目標 profile 的 `$SHELL` 與乾淨的 stdio proxy 能正常運作。 -### 5. 在 Desktop 加入遠端專案 +### 6. 在 Desktop 加入遠端專案 1. 開啟 **Settings → Connections → SSH**。 -2. 新增或啟用 `codex-win`。 +2. 新增或啟用 `codex-win-target`。 3. 選擇遠端專案資料夾。 4. 在該遠端專案中開始對話。 @@ -137,15 +162,17 @@ printf 'SHELL=%s\n' "$SHELL" | 現象 | 最可能意義 | 安全檢查方式 | | --- | --- | --- | -| `Permission denied (publickey)` | 金鑰、帳號或 ACL 有問題 | `ssh -vvv codex-win` | -| Desktop 看不到主機 | alias 不具體,或設定無法解析 | `ssh -G codex-win` | +| `Permission denied (publickey)` | 金鑰、帳號或 ACL 有問題 | `ssh -vvv ` | +| Desktop 看不到主機 | alias 不具體,或設定無法解析 | `ssh -G ` | +| 已驗證成功,但看不到預期的專案、Codex 狀態或桌面 profile | alias 選到了另一個 Windows 帳號 | 比對 `ssh -G ` 與 `ssh -T "whoami"`;為目標 profile 建立新 alias,並保留舊 alias 作為復原連線 | | 已驗證但出現 `codex: command not found` | 登入 shell 的 `PATH` 不完整 | 在遠端 shell 執行 `command -v codex` | -| 驗證後出現 `unexpected EOF` 或引號錯誤 | Windows SSH 可能將 POSIX bootstrap 交給不相容的命令直譯器 | 檢查登入 shell;bridge 只應作為進階且經檢視的 workaround | +| 驗證後出現 `unexpected EOF` 或引號錯誤 | Windows SSH 可能將 POSIX bootstrap 交給不相容的命令直譯器 | 檢查登入 shell 與目標 profile;bridge 只應作為進階且經檢視的 workaround | +| `codex --version` 已通過,但 Desktop 仍失敗或出現 shell 雜訊 | `$SHELL` 仍可能指向不相容的命令直譯器,或互動 shell 輸出非協定位元組 | 執行[手動 preflight](docs/preflight.zh-TW.md)中的選用內層 shell probe;只有特定帳號路徑確實需要時才使用經檢視的 bridge | | `socket hangup` | 網路、休眠、Desktop/CLI 版本差異、shell 雜訊或殘留 control process/socket 都可能造成 | 先檢查連線、主機休眠、Desktop 與 CLI 版本,再看去識別化 metadata;不可刪除仍被活程序使用的 socket | ### 進階:Windows shell bridge -有些 Windows OpenSSH 安裝會預設使用 `cmd.exe`,它可能破壞多行 POSIX bootstrap 指令。首選方案是讓管理員設定一個受審核、POSIX 相容且 `PATH` 正確的預設登入 shell。 +有些 Windows OpenSSH 安裝會預設使用 `cmd.exe`,它可能破壞多行 POSIX bootstrap 指令。首選方案是讓管理員設定一個受審核、POSIX 相容且 `PATH` 正確的預設登入 shell。必須在選定的目標 profile 下驗證:只改 server shell 未必能修正殘留的 `$SHELL` 環境變數或互動 shell 診斷訊息。 若無法這麼做,請使用**專門保留給 bridge 的獨立 key**與經檢視的 native bridge。它必須原樣傳遞 SSH 的 stdin/stdout/stderr;但這不代表 key 被限制為只能操作 Codex:若 bridge 接受任意 `SSH_ORIGINAL_COMMAND`,key 遭竊時仍可能以遠端 Windows 使用者身分執行指令。保留未 forced 的復原 key;不可記錄原始 protocol stream。bridge 應被視為進階部署工件,不是通用的複製貼上解法。 @@ -157,6 +184,7 @@ printf 'SHELL=%s\n' "$SHELL" - [ ] 私鑰只保留在本機。 - [ ] Repo、SSH config 與 log 沒有密碼、私鑰、Token、真實主機名稱或 IP。 +- [ ] 每個 Codex alias 都對應到預期 Windows 帳號/profile;新 profile 通過 preflight 前,原本可用的主機 alias 仍保留作為復原連線。 - [ ] 遠端帳號是低權限帳號,並與管理員帳號分開。 - [ ] NTFS ACL 將遠端帳號限制在預期的專案資料;不可在主機之間複製 Codex auth/token 檔案。 - [ ] 首次連線以獨立管道核對 SSH host-key fingerprint;絕不可設定 `StrictHostKeyChecking=no`。 diff --git a/docs/preflight.md b/docs/preflight.md index 088e332..69e7828 100644 --- a/docs/preflight.md +++ b/docs/preflight.md @@ -2,27 +2,47 @@ This is a manual preflight. It catches common false positives before opening a remote project, but it cannot prove full Desktop/app-server compatibility. The repository's local [reference-bridge self-test](../tests/Test-ReferenceBridge.ps1) only verifies compilation and selected argument rules; it is not an SSH/Desktop integration test. -Use placeholders from the main guide: `codex-win` is a concrete local SSH alias and no command below contains live credentials. +Use placeholders from the main guide: `codex-win-target` is a concrete local SSH alias and no command below contains live credentials. Keep the old working alias/key intact as recovery access while testing a new profile. -## 1. Resolve the SSH alias +## 1. Prove the intended Windows profile + +On the intended remote Windows desktop, open PowerShell as that signed-in user and run: + +```powershell +whoami +``` + +Keep that result private. It is the account the SSH alias must select; the host name, a working old alias, and the visible desktop are not interchangeable account identifiers. + +From the local computer, verify the alias reaches that same account: + +```powershell +$alias = 'codex-win-target' +ssh -T -o BatchMode=yes $alias "whoami" +``` + +The two results must match. If they do not, stop here: create a new concrete alias and dedicated key for the intended account. Do not copy the other account's Codex auth files, private keys, or profile directory. A Windows OpenSSH `DefaultShell` setting is host-wide; it changes a shell choice, not the selected desktop account. + +## 2. Resolve the SSH alias In local PowerShell: ```powershell -ssh -G codex-win +$alias = 'codex-win-target' +ssh -G $alias ``` Confirm the resolved host, user, and identity file are the intended values. Verify the host-key fingerprint through an independent trusted channel on the first connection; never bypass this with `StrictHostKeyChecking=no`. -## 2. Check key authentication and remote Codex +## 3. Check key authentication and remote Codex ```powershell -ssh -T -o BatchMode=yes codex-win "codex --version" +ssh -T -o BatchMode=yes $alias "codex --version" ``` This must return a Codex version without a password prompt. It verifies the key, basic remote command execution, and that `codex` is available. It does **not** prove that the Windows login-shell bridge can carry Codex's multiline POSIX bootstrap. -## 3. Check POSIX shell execution +## 4. Check POSIX shell execution Create a harmless POSIX payload and send it over SSH standard input: @@ -32,7 +52,7 @@ set -eu printf '%s\n' 'CODEX_SSH_POSIX_OK' '@ -$posixProbe | & ssh.exe -T -o BatchMode=yes codex-win "sh -s" +$posixProbe | & ssh.exe -T -o BatchMode=yes $alias "sh -s" ``` Expected output is exactly one line: @@ -43,14 +63,14 @@ CODEX_SSH_POSIX_OK If this fails after public-key authentication succeeds, resolve the remote login-shell/command-interpreter problem before adding the host to Desktop. -## 4. Check a clean stdin/stdout path +## 5. Check a clean stdin/stdout path ```powershell $stdoutPath = Join-Path $env:TEMP 'codex-ssh-probe.stdout.txt' $stderrPath = Join-Path $env:TEMP 'codex-ssh-probe.stderr.txt' 'CODEX_SSH_STDIO_OK' | - & ssh.exe -T -o BatchMode=yes codex-win "cat" 1> $stdoutPath 2> $stderrPath + & ssh.exe -T -o BatchMode=yes $alias "cat" 1> $stdoutPath 2> $stderrPath Get-Content -LiteralPath $stdoutPath -Raw Get-Content -LiteralPath $stderrPath -Raw @@ -58,7 +78,26 @@ Get-Content -LiteralPath $stderrPath -Raw Expected stdout is `CODEX_SSH_STDIO_OK` plus a newline, and stderr is empty. Remove the two temporary probe files manually after inspecting them. Do not reuse this redirection pattern around `codex app-server proxy`: its stdio is a protocol channel and must not be logged or transformed. -## 5. Open the remote project +## 6. Check the inner login shell (recommended on Windows) + +The desktop workflow can invoke the remote `$SHELL` with login/interactive flags. A basic `codex --version` or `sh -s` success does not prove that this nested shell is quiet and POSIX-compatible. + +```powershell +$loginShellProbe = @' +set -eu +"$SHELL" -lic 'printf "%s\n" "CODEX_SSH_LOGIN_SHELL_OK"' +'@ + +$loginShellProbe | + & ssh.exe -T -o BatchMode=yes $alias "sh -s" 1> $stdoutPath 2> $stderrPath + +Get-Content -LiteralPath $stdoutPath -Raw +Get-Content -LiteralPath $stderrPath -Raw +``` + +Expected stdout is exactly `CODEX_SSH_LOGIN_SHELL_OK` plus a newline, and stderr is empty. If this fails or emits warnings such as non-TTY job-control messages, do not filter or redirect the real protocol stream. Fix the login-shell path or use the reviewed account-specific bridge path, then repeat the preflight. + +## 7. Open the remote project Only after the preceding checks pass: @@ -72,8 +111,9 @@ If Desktop fails despite all checks passing, capture only sanitized metadata: De | Result | Next action | | --- | --- | -| Step 2 fails | Fix public-key authentication, account selection, ACLs, or `codex` availability. | -| Step 2 passes but 3/4 fails | Fix the Windows login-shell/command-interpreter boundary. A stock `cmd.exe` path is not adequate for a POSIX bootstrap. | +| Step 1 fails | Fix the alias `User`/key selection before changing a shell or installing Codex. | +| Step 3 fails | Fix public-key authentication, account selection, ACLs, or `codex` availability. | +| Step 3 passes but 4/5/6 fails | Fix the Windows login-shell/command-interpreter boundary. A stock `cmd.exe` path is not adequate for a POSIX bootstrap, and a noisy interactive shell is not protocol-safe. | | All steps pass but Desktop fails | Check sleep/network state, app and CLI version drift, and sanitized logs. Do not delete a live control socket. | See the [main guide](../README.md) and [threat model](security-model.md). diff --git a/docs/preflight.zh-TW.md b/docs/preflight.zh-TW.md index c9e4cf8..07845c3 100644 --- a/docs/preflight.zh-TW.md +++ b/docs/preflight.zh-TW.md @@ -2,27 +2,47 @@ 這是手動 preflight。它可在加入遠端專案前抓出常見假陽性,但不能保證 Desktop/app-server 完整相容。本 repo 的本機 [reference-bridge self-test](../tests/Test-ReferenceBridge.ps1) 只驗證編譯與部分參數規則;它不是 SSH/Desktop 整合測試。 -以下範例沿用主文件的 `codex-win` 具體 SSH alias,所有命令都不含實際認證資料。 +以下範例沿用主文件的 `codex-win-target` 具體 SSH alias,所有命令都不含實際認證資料。測試新 profile 時,請保留原本已能使用的 alias/key 作為復原連線。 -## 1. 解析 SSH alias +## 1. 證明登入的是預期 Windows profile + +在目標遠端 Windows 的預期桌面帳號中,以該已登入使用者開啟 PowerShell,執行: + +```powershell +whoami +``` + +結果請自行保留,不要發佈。它才是 SSH alias 必須選到的帳號;主機名稱、既有可用 alias 與目前可見的桌面,不能互相當作帳號識別。 + +在本機確認 alias 登入的正是同一帳號: + +```powershell +$alias = 'codex-win-target' +ssh -T -o BatchMode=yes $alias "whoami" +``` + +兩邊結果必須一致。若不一致,請在此停止:為目標帳號建立新的具體 alias 與專用 key。不可複製另一個帳號的 Codex auth、私鑰或整個 profile。Windows OpenSSH 的 `DefaultShell` 是主機層級設定;它只能改 shell 選擇,不能選擇桌面帳號。 + +## 2. 解析 SSH alias 在本機 PowerShell 執行: ```powershell -ssh -G codex-win +$alias = 'codex-win-target' +ssh -G $alias ``` 確認解析出的 host、user 與 identity file 都是預期值。第一次連線時,要透過獨立且可信任的管道核對 host-key fingerprint;不要用 `StrictHostKeyChecking=no` 跳過它。 -## 2. 檢查金鑰驗證與遠端 Codex +## 3. 檢查金鑰驗證與遠端 Codex ```powershell -ssh -T -o BatchMode=yes codex-win "codex --version" +ssh -T -o BatchMode=yes $alias "codex --version" ``` 它必須無密碼提示地回傳 Codex 版本。這會驗證金鑰、基本遠端命令與 `codex` 是否可用;但**不能**證明 Windows login-shell bridge 能承載 Codex 的多行 POSIX bootstrap。 -## 3. 檢查 POSIX shell 執行 +## 4. 檢查 POSIX shell 執行 建立無害的 POSIX payload,再透過 SSH 標準輸入送出: @@ -32,7 +52,7 @@ set -eu printf '%s\n' 'CODEX_SSH_POSIX_OK' '@ -$posixProbe | & ssh.exe -T -o BatchMode=yes codex-win "sh -s" +$posixProbe | & ssh.exe -T -o BatchMode=yes $alias "sh -s" ``` 預期輸出剛好是一行: @@ -43,14 +63,14 @@ CODEX_SSH_POSIX_OK 若公開金鑰已驗證成功但這一步失敗,請先處理遠端 login shell/命令直譯器問題,再把主機加入 Desktop。 -## 4. 檢查乾淨的 stdin/stdout 路徑 +## 5. 檢查乾淨的 stdin/stdout 路徑 ```powershell $stdoutPath = Join-Path $env:TEMP 'codex-ssh-probe.stdout.txt' $stderrPath = Join-Path $env:TEMP 'codex-ssh-probe.stderr.txt' 'CODEX_SSH_STDIO_OK' | - & ssh.exe -T -o BatchMode=yes codex-win "cat" 1> $stdoutPath 2> $stderrPath + & ssh.exe -T -o BatchMode=yes $alias "cat" 1> $stdoutPath 2> $stderrPath Get-Content -LiteralPath $stdoutPath -Raw Get-Content -LiteralPath $stderrPath -Raw @@ -58,7 +78,26 @@ Get-Content -LiteralPath $stderrPath -Raw 預期 stdout 是 `CODEX_SSH_STDIO_OK` 加換行,stderr 必須是空的。檢查完成後,手動刪除這兩個暫存檔。不可把此重導向方式套用在 `codex app-server proxy`:它的 stdio 是 protocol channel,不能記錄或轉換。 -## 5. 開啟遠端專案 +## 6. 檢查內層 login shell(Windows 建議必做) + +Desktop workflow 可能以 login/interactive flags 呼叫遠端 `$SHELL`。僅 `codex --version` 或 `sh -s` 成功,不能證明這個內層 shell 安靜且與 POSIX 相容。 + +```powershell +$loginShellProbe = @' +set -eu +"$SHELL" -lic 'printf "%s\n" "CODEX_SSH_LOGIN_SHELL_OK"' +'@ + +$loginShellProbe | + & ssh.exe -T -o BatchMode=yes $alias "sh -s" 1> $stdoutPath 2> $stderrPath + +Get-Content -LiteralPath $stdoutPath -Raw +Get-Content -LiteralPath $stderrPath -Raw +``` + +預期 stdout 剛好是 `CODEX_SSH_LOGIN_SHELL_OK` 加換行,stderr 必須是空的。若失敗或輸出非 TTY job-control 類警告,不可過濾或重導向真正的 protocol stream。先修正 login-shell path,或使用已審核且只對該帳號設定的 bridge 路徑,再重新執行 preflight。 + +## 7. 開啟遠端專案 只有上述檢查皆成功後才進行: @@ -72,8 +111,9 @@ Get-Content -LiteralPath $stderrPath -Raw | 結果 | 下一步 | | --- | --- | -| 第 2 步失敗 | 修正公開金鑰驗證、帳號選擇、ACL 或 `codex` 是否可用。 | -| 第 2 步通過,但第 3/4 步失敗 | 修正 Windows login shell/命令直譯器邊界。標準 `cmd.exe` 路徑不適合承載 POSIX bootstrap。 | +| 第 1 步失敗 | 先修正 alias 的 `User`/key 選擇,再變更 shell 或安裝 Codex。 | +| 第 3 步失敗 | 修正公開金鑰驗證、帳號選擇、ACL 或 `codex` 是否可用。 | +| 第 3 步通過,但第 4/5/6 步失敗 | 修正 Windows login shell/命令直譯器邊界。標準 `cmd.exe` 路徑不適合承載 POSIX bootstrap;會輸出雜訊的 interactive shell 也不適合 protocol。 | | 所有步驟通過但 Desktop 失敗 | 檢查休眠/網路狀態、App 和 CLI 版本差異與去識別化 log。不可刪除活程序使用的 control socket。 | 請搭配[主文件](../README.zh-TW.md)與 [威脅模型](security-model.zh-TW.md)使用。 diff --git a/docs/reference-bridge.md b/docs/reference-bridge.md index d54fe28..0b1710b 100644 --- a/docs/reference-bridge.md +++ b/docs/reference-bridge.md @@ -20,6 +20,19 @@ alias and a remote login shell where `codex` is on `PATH`, but it does not prescribe Git Bash or this bridge. Prefer an administrator-reviewed POSIX-compatible default login shell when that is practical. +## Choose the Windows account before deploying + +The bridge does not choose, attach to, or control a visible Windows desktop session. It runs as the Windows account selected by the SSH alias's `User` and by the matching public key. That account owns its own profile, `%LOCALAPPDATA%`, Codex CLI/authentication state, project files, and bridge temporary-script location. + +Before building or deploying the bridge for a desktop workflow: + +1. On the intended Windows desktop, run `whoami` privately. +2. Create a **new, concrete alias** and dedicated key for exactly that account; do not repoint a previously working alias for another profile. +3. Verify `ssh -T -o BatchMode=yes "whoami"` matches the desktop result, then install/authenticate Codex under that same account and run the full [manual preflight](preflight.md). +4. Keep the old alias/key as recovery access until the new profile completes a real read-only remote-project task. + +`bridge.ini` selects a shell executable; it cannot switch Windows accounts. Likewise, a Windows OpenSSH `DefaultShell` setting is host-wide and does not choose a user profile. If the target account differs from an existing bridge account, configure and validate a separate profile-specific connection instead of copying Codex files or credentials. + ## Security boundary This bridge does **not** reduce the Windows account's permissions. A dedicated @@ -92,6 +105,8 @@ the deployment manually: 5. Confirm the configured `bash.exe` exists at a local, non-UNC path. Run each executable's `--self-test`, then run the [manual SSH preflight](preflight.md). +Before editing any key file, verify the effective `AuthorizedKeysFile` for the target account with an administrator-reviewed local `sshd -T -C ...` check. Windows OpenSSH can apply a different path through an administrator match rule; do not assume every account uses `%USERPROFILE%\\.ssh\\authorized_keys`, and do not publish the resulting paths or output. + The self-test checks selected source behaviors; it does not load `bridge.ini` or prove Git Bash, SSH transport, or ChatGPT desktop compatibility. Do not edit `authorized_keys`, `sshd_config`, firewall rules, or password authentication @@ -100,8 +115,8 @@ until the recovery path and full preflight have succeeded. ## Add only a dedicated bridge key Keep the recovery key session open. In a separate administrative session, add -a **new** public-key line to the remote user's `authorized_keys`, prefixing only -that new line with: +a **new** public-key line to the selected target account's effective +`authorized_keys`, prefixing only that new line with: ```text command="C:/ProgramData/CodexSshBridge/codex-ssh-bridge.exe" diff --git a/docs/reference-bridge.zh-TW.md b/docs/reference-bridge.zh-TW.md index a762a89..5d96776 100644 --- a/docs/reference-bridge.zh-TW.md +++ b/docs/reference-bridge.zh-TW.md @@ -17,6 +17,19 @@ OpenAI 文件說明通用的 SSH 遠端專案:需要具體 SSH alias,以及 找到 `codex` 的遠端登入 shell;它沒有指定 Git Bash 或這個 bridge。若可行, 仍優先請管理員設定經審核的 POSIX 相容預設登入 shell。 +## 部署前先選定 Windows 帳號 + +bridge 不會選擇、附著或控制可見的 Windows 桌面工作階段。它會以 SSH alias 的 `User` 與配對 public key 所選出的 Windows 帳號執行。該帳號各自擁有 profile、`%LOCALAPPDATA%`、Codex CLI/授權狀態、專案檔與 bridge 暫存 script 位置。 + +要為桌面 workflow 建置或部署 bridge 前: + +1. 在預期 Windows 桌面上私下執行 `whoami`。 +2. 為**完全相同的帳號**建立新的、具體的 alias 與專用 key;不可把原本可用於另一個 profile 的 alias 直接改指向它。 +3. 驗證 `ssh -T -o BatchMode=yes "whoami"` 與桌面結果一致,再在同一帳號下安裝/授權 Codex,並完成[手動 preflight](preflight.zh-TW.md)。 +4. 新 profile 完成實際的小型唯讀遠端專案任務前,保留舊 alias/key 作為復原連線。 + +`bridge.ini` 只選擇 shell executable,不能切換 Windows 帳號。Windows OpenSSH 的 `DefaultShell` 同樣是主機層級設定,不能選擇 user profile。若目標帳號不同於既有 bridge 帳號,應設定並驗證另一條 profile 專用連線,而不是複製 Codex 檔案或認證資料。 + ## 安全邊界 這個 bridge **不會**降低 Windows 帳號本身的權限。可抵達接受 @@ -83,14 +96,16 @@ Windows 內附的 .NET Framework C# compiler;不需要 NuGet、密碼、金鑰 5. 確認設定的 `bash.exe` 是存在的本機非 UNC path。對兩個執行檔執行 `--self-test`,再執行[手動 SSH preflight](preflight.zh-TW.md)。 +編輯任何 key file 前,先由管理員在本機以 `sshd -T -C ...` 核對目標帳號實際套用的 `AuthorizedKeysFile`。Windows OpenSSH 可能因 administrator match rule 而使用不同路徑;不可假設每個帳號都使用 `%USERPROFILE%\\.ssh\\authorized_keys`,也不可公開產生的 path 或 output。 + self-test 只檢查部分原始碼行為;它不會載入 `bridge.ini`,也不證明 Git Bash、 SSH transport 或 ChatGPT Desktop 相容。recovery path 與完整 preflight 成功前, 不可修改 `authorized_keys`、`sshd_config`、Firewall 規則或密碼驗證。 ## 只加入專用的 bridge key -保持 recovery key 的連線工作階段開啟。在另一個已提高權限的工作階段,於遠端使用者 -的 `authorized_keys` 新增**一行新的** public key,僅在這個新行前加上: +保持 recovery key 的連線工作階段開啟。在另一個已提高權限的工作階段,於選定目標帳號實際套用的 +`authorized_keys` 新增**一行新的** public key,僅在這個新行前加上: ```text command="C:/ProgramData/CodexSshBridge/codex-ssh-bridge.exe"