diff --git a/docs/NATIVE_V1_SPEC.md b/docs/NATIVE_V1_SPEC.md index 8ec9f67..f14bbed 100644 --- a/docs/NATIVE_V1_SPEC.md +++ b/docs/NATIVE_V1_SPEC.md @@ -32,6 +32,10 @@ Compatibility expectations: - SSH bootstrap remains available with `--auth=ssh` and is used automatically when native auth is disabled or cannot complete. +Native v1 is complete only if a normal interactive user can switch their daily +workflow from `ssh` to `dosh` without keeping SSH open in another tab for routine +tasks. + Non-goals for v1: - RFC-compatible SSH server/client behavior. @@ -41,7 +45,74 @@ Non-goals for v1: - Multi-user daemon mode with privileged account switching. - Replacing OpenSSH on hosts that do not run `dosh-server`. -## 2. Security Contract +## 2. SSH Workflow Parity Target + +Native v1 targets the SSH workflows interactive users actually use, not the entire +OpenSSH feature universe. + +Must work in v1: + +- Interactive shell: `dosh host`. +- Remote command: `dosh host command...`. +- Fresh terminal by default. +- Named persistent terminal: `dosh --session work host`. +- Shared/view-only session: `dosh --view-only --session work host`. +- Local forwarding: `dosh -L [bind:]listen:target:target_port host`. +- Remote forwarding: `dosh -R [bind:]listen:target:target_port host`. +- Dynamic forwarding: `dosh -D [bind:]listen host`, if stream flow control is proven; + otherwise it is the first v1.1 item and must be called out honestly. +- Multiple forwards in one connection. +- Forward-only mode: `dosh -N -L ... host`. +- Background forwarding: `dosh -f -N -L ... host`, or an equivalent supervised + user-service mode. +- SSH-agent authentication. +- Encrypted OpenSSH private-key authentication with prompt. +- `~/.ssh/config` host aliases for `Host`, `HostName`, `User`, `Port`, + `IdentityFile`, `ProxyJump`, `UserKnownHostsFile`, and `IdentitiesOnly`. +- Dosh host config overrides for Dosh-specific UDP host/port/auth policy. +- Clear host-key trust and mismatch errors. +- Clear auth failure errors that name the attempted key source. +- Stable reconnect after sleep, network switch, NAT rebinding, and server packet loss. +- `dosh update`. +- `dosh doctor host` for config/auth/UDP reachability diagnostics. +- `dosh sessions host` for session visibility. + +Should work in v1 if it does not compromise the transport schedule: + +- Agent forwarding with an explicit opt-in flag and clear warning. +- `ProxyJump` through SSH for bootstrap/trust and through Dosh-native relay later. +- `SendEnv`/`SetEnv` equivalent for explicit environment variables. +- Clipboard integration as a separate opt-in channel. + +Explicitly not v1: + +- X11 forwarding. +- SFTP/SCP wire compatibility. +- Full OpenSSH config language. +- Full `sshd` replacement for arbitrary SSH clients. +- Forced-command subsystems beyond fail-closed enforcement. + +## 3. Stability Contract + +Native v1 must be boring under real use: + +- A closed laptop must not kill the remote session. +- A client crash must not kill the remote session. +- Server restart may drop live PTYs in v1 unless session persistence is implemented, + but the client must fail clearly and reconnect cleanly afterward. +- Decrypt failures from stale packets must be ignored or trigger reconnect, never + terminate the terminal by themselves. +- Terminal cleanup must restore cursor, mouse mode, bracketed paste, alternate + screen, and raw mode on exit. +- Forwarding streams must close cleanly without leaving orphan listeners. +- Every public error must be actionable: host trust, auth failure, UDP blocked, + forwarding denied, version mismatch, or server unavailable. +- `dosh host` must never attach to another active unnamed terminal by accident. +- The default install must be secure without hand-editing configs. +- Upgrades must preserve existing trusted host keys and credentials unless explicitly + rotated. + +## 4. Security Contract Native Dosh must match the security properties users rely on from SSH for this use case: @@ -60,7 +131,7 @@ case: Native Dosh does not claim SSH's full protocol security surface. It claims equivalent security for Dosh terminal and forwarding sessions on Dosh-installed servers. -## 3. Threat Model +## 5. Threat Model In scope: @@ -79,7 +150,7 @@ Out of scope: - Malicious kernel, terminal emulator, or PTY implementation. - Protecting against a server that is already authorized and then becomes malicious. -## 4. Cryptographic Building Blocks +## 6. Cryptographic Building Blocks Allowed primitives: @@ -100,7 +171,7 @@ Disallowed: - Unauthenticated encryption. - MD5/SHA-1 signatures for user auth. -## 5. Identity And Trust +## 7. Identity And Trust ### Server Identity @@ -167,7 +238,7 @@ Authorized-key options required in v1: Unsupported restrictive options must fail closed. -## 6. Native Auth Handshake +## 8. Native Auth Handshake Native auth runs over UDP on the same Dosh port. It establishes a short-lived authenticated control channel and returns the same terminal attach material that SSH @@ -254,7 +325,7 @@ Fields: `AuthOk` is AEAD-encrypted under the handshake traffic key. -## 7. Key Schedule +## 9. Key Schedule Handshake transcript: @@ -284,7 +355,7 @@ s2c_key = HKDF-SHA256(handshake_key, H, "dosh/native/s2c/v1") Attach ticket PSKs and rotated session keys must be derived independently from server secret material and fresh randomness. They must not reuse handshake traffic keys. -## 8. Attach Tickets And Cache +## 10. Attach Tickets And Cache Native attach tickets replace most cold auth after first login. @@ -317,7 +388,7 @@ Cache entries must include: - attach ticket - attach ticket PSK -## 9. Transport +## 11. Transport Post-auth terminal traffic continues to use the current Dosh UDP packet model: @@ -338,7 +409,7 @@ Required v1 changes: - Connection migration must be accepted after any valid encrypted packet from a new source address. -## 10. Forwarding +## 12. Forwarding Native forwarding is a Dosh stream multiplexer over the encrypted transport. @@ -368,8 +439,46 @@ Forwarding rules: - Server enforces `no-port-forwarding` and `permitopen=`. - Remote listeners bind to loopback by default. - Non-loopback remote bind requires explicit config. +- `-N` opens forwarding without creating a PTY. +- `-f` backgrounds only after all requested listeners are successfully active. +- Listener setup failures fail the entire command unless `--partial-forwarding` is + explicitly requested. +- Forwarding reconnect must preserve listeners and re-open streams after network + migration when protocol state allows it. +- Stream packet scheduling must enforce terminal priority; a large port-forward copy + cannot make shell keystrokes lag. -## 11. Config +## 13. Diagnostics And Operations + +Native v1 must include operations commands: + +```bash +dosh doctor host +dosh trust host +dosh trust --remove host +dosh sessions host +dosh update +``` + +`dosh doctor host` checks: + +- host alias resolution +- Dosh known-host state +- SSH fallback reachability +- native UDP reachability +- server version +- native auth enabled/disabled +- usable keys from ssh-agent and identity files +- server authorization result without opening a terminal +- configured forwarding policy + +`dosh trust host` checks: + +- fetch Dosh host key through SSH fallback when available +- show fingerprint before writing trust +- refuse overwrite on mismatch unless `--replace` is explicit + +## 14. Config Client: @@ -381,6 +490,8 @@ known_hosts = "~/.config/dosh/known_hosts" credential_cache = "~/.local/share/dosh/credentials" identity_files = ["~/.ssh/id_ed25519"] use_ssh_agent = true +forward_agent = false +forwardings = [] ``` Server: @@ -393,9 +504,10 @@ native_auth_rate_limit_per_minute = 30 attach_ticket_ttl_secs = 86400 allow_tcp_forwarding = true allow_remote_forwarding = false +allow_agent_forwarding = false ``` -## 12. Migration Plan +## 15. Migration Plan Milestone 1: host identity and trust @@ -419,7 +531,8 @@ Milestone 3: default native auth Milestone 4: forwarding -- Add stream mux and `-L`. +- Add stream mux. +- Add `-L`, `-N`, and `-f`. - Add `-R`. - Add `-D` only after flow control is proven. @@ -429,7 +542,15 @@ Milestone 5: hardening - Add hostile-network integration tests. - Add external review checklist before public security claims. -## 13. Verification +Milestone 6: workflow parity + +- Implement `dosh doctor`. +- Implement complete host-trust management. +- Implement private-key prompt flow. +- Implement forwarding policy diagnostics. +- Run daily-driver soak on macOS and Linux clients. + +## 16. Verification Native v1 is not complete until all are true: @@ -447,10 +568,18 @@ Native v1 is not complete until all are true: - Cached attach remains near network RTT plus local render overhead. - `-L` forwarding works without delaying terminal input. - `-R` forwarding enforces bind and permission policy. +- `-N -L` forward-only mode does not allocate a PTY. +- `-f -N -L` backgrounds only after listener readiness. +- Multiple forwards in one command work. +- `dosh doctor` identifies UDP-blocked, auth-denied, host-key-mismatch, and + forwarding-denied states. +- Closing the laptop for at least 30 minutes does not kill the remote session. +- Three concurrent Dosh terminals remain independent unless explicitly named. +- Large forwarded transfers do not add visible terminal input lag. - Fuzz targets run in CI. - Threat model is updated with any accepted residual risks. -## 14. Public Claim Gate +## 17. Public Claim Gate Dosh may claim "native SSH replacement for Dosh-installed servers" only after: