交互认证与本机 AgentInteractive Auth & Local Agent
本页说明认证整改候选版的交互认证与本机 SSH Agent。源码已通过隔离真实协议测试,但不表示当前商店旧版已经支持;请以安装版本的认证选项和发布说明为准。
交互认证 / MFA
主机编辑器选择「交互 / MFA」,或使用密码/密钥作为第一因素、按服务端要求继续挑战。先确认 SSH 主机指纹,再核对弹层中的主机和用户名。支持多轮、多个输入项与通知;取消、120 秒等待超时或锁定会结束当前请求。
回答只用于当前 SSH 认证,不保存、不参与同步、诊断或 AI。不要输入另一个服务的验证码。MFA 的具体因素由服务器配置决定,选中该认证方式不等于服务器已经启用双因素。
Mac App Store 沙箱为何需要连接器
macOS 沙箱不能直接访问另一个进程的 UNIX Agent socket。不要关闭 App 沙箱、授予全磁盘访问,或把私钥交给 AI。候选版提供独立的 shellby-agent-bridge,由你主动启动;只监听 127.0.0.1 随机端口,每次启动生成新的 256-bit 配对令牌。
源码构建(开发者)
当前指南提供源码构建路径,不提供未经公证的下载链接,也不要求移除下载隔离标记。需要完整 Xcode/Swift 工具链,在与你的 App 候选版对应的 Shellby 源码目录中运行:
swift build -c release --product shellby-agent-bridge
BIN_DIR="$(swift build -c release --show-bin-path)"
"$BIN_DIR/shellby-agent-bridge" --socket "$SSH_AUTH_SOCK"
仅当你已在本机启动了可信 SSH Agent 并设置正确的 socket 时运行。也可显式提供自己的绝对 socket 路径。不要把 socket 指向远程机器。停止连接器用 Ctrl-C。
配对与撤销
- 连接器终端会显示敏感配对码,不要截图、贴到聊天或写入 shell 历史。
- 主机编辑器选择 SSH Agent,打开「配置本机安全连接器」,粘贴并保存配对码。
- 连接器优先于直接 socket。保存只代表本机保存了配对,不表示已经完成服务器认证;连接时仍要验证主机和 Agent 授权。
- 退出连接器立即撤销其连接;重启必须重新配对。App 中「移除配对」删除本机能力凭据;连接器运行期间请同时停止它,撤销已经复制的旧码。
配对码只存本机安全存储,不进同步、导出、AI 或诊断。连接器只接受身份枚举和 SSH 会话绑定的认证签名,拒绝任意数据签名、私钥导出及 Agent forwarding。仍请只给可信本机应用配对;持有码的程序能请求 SSH 认证签名,不能把它当作无害连接地址。
平台边界
- macOS 沙箱版本:使用本机连接器。
- 非沙箱 Mac / Linux 桌面源码版本:可直接使用本机 UNIX Agent socket。
- Windows 桌面源码版本:支持本机命名管道,默认
\\.\pipe\openssh-ssh-agent;不访问远程 UNC 管道。Windows 真机与各 Agent 厂商兼容性仍需单独验收。 - iOS / iPadOS / Android / HarmonyOS:不宣称提供桌面系统 Agent socket,使用密钥或交互认证。是否显示候选功能取决于渠道版本。
This guide describes the authentication remediation candidate, verified against an isolated real SSH protocol server. It does not claim these features exist in older store releases. Check your installed version's authentication options and release notes.
Interactive authentication / MFA
Select Interactive / MFA, or authenticate with a password/key first and continue with server-required challenges. Verify the host fingerprint before answering, then check the displayed host and username. Multiple rounds, multiple fields and notifications are supported. Cancel, a 120-second wait timeout or app locking ends the request.
Answers are used only for this SSH authentication, never saved, synced, included in diagnostics or sent to AI. Never enter codes belonging to another service. The server determines its factors; selecting this mode does not enable MFA on the server.
Why the Mac App Store sandbox needs a connector
The macOS sandbox cannot directly access another process's UNIX agent socket. Do not disable the sandbox, grant full-disk access or hand private keys to AI. The candidate provides a separate shellby-agent-bridge you run deliberately. It binds only a random 127.0.0.1 port with a fresh 256-bit capability each launch.
Building from source (developers)
This guide provides a source-build route, not an unnotarized download or quarantine-removal instructions. With the full Xcode/Swift toolchain, run inside the Shellby source directory matching your app candidate:
swift build -c release --product shellby-agent-bridge
BIN_DIR="$(swift build -c release --show-bin-path)"
"$BIN_DIR/shellby-agent-bridge" --socket "$SSH_AUTH_SOCK"
Run only with your trusted local agent already started and the correct socket configured. You can supply its absolute path explicitly. Never point it at a remote host. Stop with Ctrl-C.
Pairing and revocation
- The connector prints a sensitive pairing code. Do not screenshot it, paste it into chats or put it in shell history.
- Select SSH Agent in the host editor, open Configure Local Secure Connector, paste the code and save.
- The connector takes priority over a direct socket. Saving pairing is not a successful server authentication; host verification and agent approval still apply.
- Stopping the connector revokes its connections; restarting requires pairing again. Forgetting pairing removes the app's local capability. Also stop the connector to revoke any already copied code.
Pairing stays in local secure storage, outside sync, exports, AI and diagnostics. The connector allows identity enumeration and session-bound SSH authentication signatures only, not arbitrary-data signing, private-key export or forwarding. Pair only trusted local apps: anyone holding the code can request SSH authentication signatures; it is not a harmless address.
Platform boundaries
- Sandboxed macOS: use the local connector.
- Non-sandboxed Mac / Linux desktop source builds: direct local UNIX sockets are available.
- Windows desktop source builds: local named pipes, default
\\.\pipe\openssh-ssh-agent, never remote UNC pipes. Windows device and vendor-agent compatibility require separate acceptance. - iOS / iPadOS / Android / HarmonyOS: no desktop system-agent socket is claimed; use keys or interactive authentication. Candidate feature visibility depends on the channel/version.