git-remote-pqcrypt

THIS IS AN EXPERIMENTAL PROJECT, there hasnt been a formal security audit. DO NOT rely on this for any critical repositories.

git-remote-pqcrypt is an encrypted Git remote helper similar to gcrypt. It stores Git packfiles and repository metadata encrypted at rest. Access is with post-quantum XWing wrapping.

Current crate version: 0.2.0.

How it works

1. git-remote-pqcrypt init creates a repository master key.
2. The master key is wrapped for each user with their public key.
3. Git packfiles and manifest are encrypted using the master key.
4. Git uses pqcrypt through the git-remote-pqcrypt remote helper.
5. The master key is decrypted locally by the helper and then packfiles are decrypted to the local repository.

Example files of remote storage:

keys.json
manifest.enc
objects/
    pack-.....pack.enc

keys.json contains metadata and encrypted master key wrappings.

Installation

Fast install with Cargo

Install the default build from Git:

cargo install --git https://github.com/Torm0r/git-remote-pqcrypt --locked

This installs git-remote-pqcrypt to Cargo's binary directory, usually ~/.cargo/bin.

Make sure Cargo's binary directory is in your PATH, then check that it works:

git-remote-pqcrypt --help

The default build includes local filesystem and Git-backed storage support.

To install with SFTP support on Unix-like systems:

cargo install --git https://github.com/Torm0r/git-remote-pqcrypt --locked --features sftp

The sftp feature is currently not supported on Windows.

Build from source

Build with default backend support:

cargo build --release

This includes local filesystem and Git-backed storage support.

To build with SFTP support on Unix-like systems:

cargo build --release --features sftp

Install the binary to your PATH:

sudo cp target/release/git-remote-pqcrypt /usr/local/bin/

The binary name must remain git-remote-pqcrypt, because Git finds remote helpers by looking for git-remote-[name].

Check that it works:

git-remote-pqcrypt --help

Requirements

• Rust toolchain for building from source
• git must be installed
• For Git-backed storage, working Git credentials and a configured Git identity are required
• For SSH/SFTP access, existing SSH authentication must be configured
• SFTP support requires building with --features sftp and is currently Unix-like only

Quick start

1. Go to an existing Git repository or make one.

2. Initialize pqcrypt storage.

Local path:

git-remote-pqcrypt init pqcrypt:///path/to/encrypted-store

SFTP requires building with the sftp feature and is currently supported only on Unix-like systems:

git-remote-pqcrypt init pqcrypt::sftp://[email protected]/path/to/store

Git-backed:

git-remote-pqcrypt init pqcrypt::[email protected]:org/store.git

If no private key exists, one is generated at ~/.config/pqcrypt/key and the public key is printed.

You will be prompted for an optional key comment, for example personal or work-laptop.

After init, a Git remote named pqcrypt is added:

git remote -v

Example:

pqcrypt  pqcrypt::/path/to/encrypted-store (fetch)
pqcrypt  pqcrypt::/path/to/encrypted-store (push)

3. Push:

git push pqcrypt main

4. Clone or fetch:

git clone pqcrypt::[email protected]:Torm0r/pqcrypt-test.git my-clone

5. Add another user.

They must generate a keypair with:

git-remote-pqcrypt keygen

They can get their public key with:

git-remote-pqcrypt pubgen ~/.config/pqcrypt/key

Or they can copy the public key printed by keygen.

Then an existing authorized user adds them to the repository:

git-remote-pqcrypt add-user <base64-public-key>

Run this for more options:

git-remote-pqcrypt add-user -h

By default, add-user looks for a local Git remote whose URL starts with pqcrypt and adds the public key there.

Push behavior

pqcrypt distinguishes normal pushes from force pushes by the Git refspec.

Normal pushes are fast-forward checked and rejected if they would overwrite remote history.

Remote-helper behavior

Git invokes pqcrypt as a remote helper through the git-remote-pqcrypt binary.

When invoked by Git, the helper expects the remote-helper argument shape used by Git, for example:

git-remote-pqcrypt origin pqcrypt::/path/to/store

Direct CLI subcommands such as init, add-user, keygen, pubgen, and help are treated as normal user commands, not remote-helper invocations.

The binary entrypoint delegates to the library runtime, so the application logic is testable through the crate library as well as through the installed binary.

Git-backed storage cache

For Git-backed storage URLs, pqcrypt maintains a local cache under the system cache directory, for example:

~/.cache/pqcrypt/

pqcrypt fetches encrypted state from the backing Git repository before operations and pushes encrypted state after updates.

If cache corruption or cache loss is detected, pqcrypt attempts to recreate the cache automatically by refetching from the backing Git repository.

URL formats

pqcrypt::, pqcrypt://, and pqcrypt: are all accepted and normalized internally to pqcrypt::.

These are equivalent:

git-remote-pqcrypt init pqcrypt:///path/to/store
git-remote-pqcrypt init pqcrypt::/path/to/store
git-remote-pqcrypt init pqcrypt:/path/to/store

Backend is determined by the storage path:

Examples:

pqcrypt::/tmp/store
pqcrypt:///tmp/store
pqcrypt:/tmp/store
pqcrypt::[email protected]:org/store.git
pqcrypt::https://github.com/org/store.git
pqcrypt::sftp://[email protected]/path/to/store

Private key discovery logic

During decryption pqcrypt looks for a private key in this order:

1. PQCRYPT_KEY_PATH environment variable
2. git config pqcrypt.keypath
3. .pqcrypt/key in the current directory
4. Any matching key file in ~/.config/pqcrypt, where all are tested

For multi-key setups, for example work and personal keys:

git config pqcrypt.keypath ~/.config/pqcrypt/work-key

The key must be one that was used during init or added via add-user.

Development

Run the full test suite:

cargo test

Run with SFTP enabled on Unix-like systems:

cargo test --features sftp

Some end-to-end tests that depend on Unix-like local path behavior are ignored on Windows.

CI builds

GitHub Actions builds the project on Linux, macOS, and Windows. Workflow artifacts may contain binaries from CI runs, but these are not official releases.

Security info

• Repository contents are encrypted using XChaCha20Poly1305.
• The repository master key is wrapped for users using HPKE with XWing.
• Each authorized public key receives its own encrypted copy of the master key.
• Comments attached to keys are authenticated as HPKE associated data. This means that if comment metadata is corrupted, the master key may no longer decrypt for that wrapping.
• Git refs and packfile metadata are stored inside the encrypted manifest.
• Private key files are created with 0600 permissions on Unix-like systems.

Limitations

• This project is experimental and has not received a formal security audit.
• Currently only local filesystem, Git-backed, and optional SFTP storage backends are supported.
• SFTP support is behind the optional sftp feature and is currently not supported on Windows.
• SFTP/Git backends lack robust distributed locking, so concurrent pushes might lead to data loss.
• Git remote-helper behavior is still relatively minimal and may not support every Git workflow or CI/CD operation.
• Force pushes are supported, but they can rewrite encrypted remote history just like normal Git force pushes.
• HPKE crate depends on a git source because XWing is not supported yet on published crate releases. This will be changed once HPKE is updated.
• No way to revoke or remove user access. Since users can recover the master key from Git history, the best course of action is to re-init the repository with a new master key and wipe the remote.
• The storage format might change in future versions.
• Git-backed storage requires working Git credentials and a configured Git identity for commits.
• For Git, SSH, or SFTP authentication, pqcrypt relies on existing SSH/Git credentials.
• ssh and git must be installed.