Implement embedded HTTPS Git synchronization

docs/git-synchronization.md

@@ -0,0 +1,47 @@
+# 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 could name an executable is rejected.
+
+`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.
+
+## HTTPS transport
+
+Remote URLs must be absolute, credential-free HTTPS URLs. SSH, scp syntax,
+`git://`, `file://`, local paths, helper transports, URL rewrites, separate push
+URLs, and unknown schemes are rejected before transport. Credentials are
+requested with the configured server ID and application 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
+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.
+
+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 smart-HTTP boundary is injectable for deterministic compatibility tests.
+Tests can inspect credentials, advertisements, receive-pack commands, object
+counts, pack checksums, non-fast-forward behavior, and server status without a
+runtime helper or external Git installation.

docs/recipient-policies.md

@@ -53,5 +53,5 @@ no-op, and must restore any staging state before returning an error. The policy
 manager then restores repository bytes. `NoGitCommitter` represents a path not
 contained in a Git work tree; it is not used for a discovered repository.
 
-The later embedded-Git implementation owns concrete staging and commits, while
-this module owns the all-or-nothing storage mutation contract it invokes.
+The embedded Git implementation owns concrete staging and commits, while this
+module owns the all-or-nothing storage mutation contract it invokes.