IronStorage/docs/git-synchronization.md

# Embedded Git and synchronization

All Git behavior is implemented in `crates/storage`. IronStorage never launches
`git`, a credential helper, an SSH client, a hook, a filter, or a merge driver.
Repositories are opened with isolated configuration and environment access;
repository-local configuration that can affect an operation is rejected.
Upstream `pass git init` deliberately writes `diff.gpg.binary` and a
`diff.gpg.textconv` GnuPG command. IronStorage preserves these passive keys for
compatibility but never evaluates them: it reads Git blobs and renders decrypted
diffs through Rust storage APIs. Frontends cannot add or change diff drivers.
This behavior follows the
[upstream password-store initialization](https://git.zx2c4.com/password-store/tree/src/password-store.sh)
while keeping runtime helper execution disabled.

`GitRepository` initializes and opens password-store worktrees, selects the
innermost repository for a nested entry, and implements status, log, diff, add,
commit, remote, and local-config operations. Successful insert, edit, generate,
recipient-policy, remove, move, and copy transactions use the same concrete
committer. Only their affected paths are staged, unrelated index state is
preserved, no-op mutations create no commit, and commit failures restore the
index so the storage transaction can roll back its files.

## Remote endpoint contract

Storage parses credential-free HTTPS URLs plus feature-gated `ssh://` and
scp-like SSH URLs into one typed endpoint contract. Local paths, `git://`,
`file://`, helper transports, URL rewrites, separate push URLs, embedded
credentials, and unknown schemes are rejected before transport. A build
without the `ssh` feature reports SSH as unsupported before connection or
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. macOS resolves them solely through
the standard Internet-password credential for the same HTTPS endpoint.

Fetch uses the embedded Rust smart-HTTP client with an explicit credential
callback, so Git's credential cascade is never entered. Push implements the
receive-pack protocol directly: it validates the advertisement, checks the
remote tip is an ancestor, creates a complete Git pack with a SHA-1 trailer,
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.

Desktop applications take remote names and URLs from the password-store's
`.git/config`. Authentication uses the matching `~/.ssh/config` identity or an
explicit 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,
start/probe an agent process or run proxy/helper commands. The in-process
client reads `Host`, `HostName`, `User`, `Port`, and `IdentityFile`; executable
OpenSSH directives remain disabled. The explicit client allowlist excludes SHA-1 key exchange/MAC,
RSA/SHA-1 signatures, DSA, CBC, `none`, compression, and host certificates.
Cancellation interrupts connection and authentication without changing Git,
known hosts, or secure storage.

The standard CLI, TUI, and desktop applications compile this transport and pass
their Git actions through storage's typed endpoint selection. They display both
SSH URL forms without reparsing them. An unknown key opens an explicit native
confirmation showing the host, port, algorithm, and fingerprint; a changed key
is a non-bypassable error. Encrypted-key prompts use hidden or masked input and
retain a supplied passphrase only after SSH authentication and the requested Git
operation succeed. Cancelling either prompt leaves the repository, known hosts,
and secure storage unchanged.

## SSH upload-pack

With the same feature enabled, branch discovery, clone, fetch, and pull open a
session channel without a PTY and request only `git-upload-pack '<path>'`.
Storage single-quotes the repository as one shell argument, preserving the
absolute, account-relative, and tilde path semantics of the two supported SSH
URL forms while preventing whitespace, quotes, metacharacters, environment
assignments, or options from selecting another command. No local Git, SSH,
shell, transport helper, or fetch-pack process is involved.

The channel is a bounded adapter into gix's existing pack-protocol client.
Stdout carries only protocol bytes; stderr is retained only as a bounded,
single-line remote-service diagnostic. Storage requires a zero exit status and
clean channel completion, distinguishes malformed advertisements and packs from
network, trust, authentication, service, and cancellation failures, and closes
the channel promptly when cancellation is requested. Gix continues to own pack
verification, object limits, and atomic ref updates, while the existing
IronStorage code continues to own clone staging, checkout, merge, conflict, and
rollback behavior.

SSH push opens the same verified and authenticated session-channel boundary for
`git-receive-pack '<path>'`. Storage validates the advertisement, rejects
non-fast-forward updates before sending, constructs the complete reachable
object pack, then half-closes channel input and drains the status and bounded
stderr streams. The remote-tracking ref advances only after `unpack ok`, an
`ok` for the selected ref, a zero service exit, and clean channel completion.
Unpack and ref-policy rejections remain typed failures; a malformed response,
disconnect, or cancellation after sending is an unknown outcome that requires
a fresh fetch before retrying and is never replayed automatically. Synchronize
always completes pull first and cannot open receive-pack after a failed,
cancelled, or conflicted pull.

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
prevalidates tree entries, rejects links and submodules, writes private files
atomically, updates the real Git index, and rolls the worktree/index back if the
reference update fails. `sync` performs pull before push, while clone builds in
a private sibling directory and installs the completed vault with a rename.

Commit signing is optional. The embedded OpenPGP key store signs the canonical
unsigned commit bytes and adds an ASCII-armored `gpgsig` header compatible with
Git/GPG without invoking `gpg`.

The transport boundary is injectable for deterministic compatibility tests.
HTTPS tests inspect credentials, advertisements, receive-pack commands, object
counts, pack checksums, non-fast-forward behavior, and server status. SSH tests
use a pure-Rust in-process Russh server and upload-pack fixture to exercise
chunked reference and pack streams, end-to-end clone/fetch/pull, command
quoting, cancellation, and rollback without an external Git or SSH executable.
Frontend tests cover typed transport display, prompt masking and cancellation,
retry routing, conflicts, authentication failures, and successful HTTPS
regression paths without duplicating protocol logic.

The final two-URL lifecycle, adversarial failure, dependency, target, and
artifact matrix is maintained in `ssh-transport-audit.md`.