Define native Dosh workflow parity requirements

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: