Implement SSH identity authentication

docs/git-synchronization.md

@@ -32,10 +32,7 @@ repository mutation instead of treating its configuration as malformed.
 ## HTTPS transport
 
 HTTPS credentials are requested with the configured server ID and application
-ID and remain outside Git configuration. The SSH session, host-verification,
-authentication, and pack-protocol implementations are separate milestone work;
-until those layers are present, network operations on SSH endpoints return the
-typed unsupported-transport result.
+ID and remain outside Git configuration.
 
 Fetch uses the embedded Rust smart-HTTP client with an explicit credential
 callback, so Git's credential cascade is never entered. Push implements the
@@ -45,6 +42,24 @@ requests `report-status`, and accepts the update only after both unpack and ref
 status succeed. HTTP redirects are disabled so authorization cannot cross an
 origin boundary.
 
+## SSH authentication
+
+With the optional `ssh` feature, storage opens an in-process Russh client and
+verifies the server key before any authentication or command. Known-host files
+are read with size and line bounds; exact, hashed, and bracketed non-default
+port entries are supported. Unknown keys require an explicit call to persist
+the confirmed key atomically. Changed keys always fail and are never replaced.
+
+Authentication uses one configured OpenSSH private-key file (Ed25519, ECDSA,
+or RSA) or one exact SHA-256 fingerprint from an already-running SSH agent.
+Encrypted-key passphrases come from `SecretBytes` in the operating-system
+secret store. Identity attempts are bounded and deterministic; IronStorage
+does not spray keys, use passwords or keyboard-interactive authentication,
+read OpenSSH configuration, start/probe an agent process, or run proxy/helper
+commands. SHA-1 host signatures and `ssh-rsa` authentication are excluded.
+Cancellation interrupts connection and authentication without changing Git,
+known hosts, or secure storage.
+
 Pull refuses a dirty worktree. It fast-forwards when possible and otherwise
 uses the embedded three-way tree merge. Unresolved paths are returned as typed
 `MergeConflicts`; no conflict markers or partial checkout are written. Checkout