git-remote-iroh

What

Serve and access Git repositories over iroh.

git-remote-iroh is a Git protocol helper that connects repositories over iroh p2p network endpoints.

Why

Git is supposed to be a distributed version control system. Centralized hub repositories are an existential risk to free software and the free exchange of code and ideas. They're a prime target for supply chain attacks, authoritarian regimes, surveillance capitalism, and abusive scraping.

How

Install:

cargo install git-remote-iroh

Serve a bare git repository on one machine:

git-remote-iroh --git-dir=/path/to/repo.git

The iroh:// address will log to stderr.

Access the remote repository from another machine:

git clone iroh://{public key} my-project

Set up authorization: gathering developer identities

In order to allow remote write access, developers' public key peer identity needs to be added to the repository server.

Gather each developer's public key, which they can each obtain with git-remote-iroh whoami:

alice$ git-remote-iroh whoami
ft5g4b13ituz99s69denhjwgx3qhmmzy4so3jj6ie1md5dwyrr1o /var/home/alice/.config/git-remote-iroh/keys/default

bob$ git-remote-iroh whoami
sdazih54na3m6pzwkogcyxbdtfkx1k4nez65rg9yaocwbbfhraao /var/home/bob/.config/git-remote-iroh/keys/default

carol$ git-remote-iroh whoami
qzbemfskctk4e4zmrjbhjg7ufx5rqj4kcej5ehq4dtb3coppj3ay /var/home/carol/.config/git-remote-iroh/keys/default

Set up authorization: granting access on the repository server

On the repository server, add each developer's peer key:

$ git-remote-iroh peer add alice ft5g4b13ituz99s69denhjwgx3qhmmzy4so3jj6ie1md5dwyrr1o
$ git-remote-iroh peer add bob sdazih54na3m6pzwkogcyxbdtfkx1k4nez65rg9yaocwbbfhraao
$ git-remote-iroh peer add carol qzbemfskctk4e4zmrjbhjg7ufx5rqj4kcej5ehq4dtb3coppj3ay

List the server's authorized peers.

$ git-remote-iroh peer
alice ft5g4b13ituz99s69denhjwgx3qhmmzy4so3jj6ie1md5dwyrr1o
bob sdazih54na3m6pzwkogcyxbdtfkx1k4nez65rg9yaocwbbfhraao
carol qzbemfskctk4e4zmrjbhjg7ufx5rqj4kcej5ehq4dtb3coppj3ay

Usage

git-remote-iroh uses GIT_DIR to locate the repository, whether in client or server mode.

Client mode

When performing client operations, git invokes git-remote-iroh to handle iroh:// remote URLs automatically.

Server mode

When serving a repository, git-remote-iroh supports the --config-dir and --git-dir options. These can also be set with environment variables. The included Dockerfile builds an OCI image that uses /config and /repo for these, respectively.

Iroh can't connect to the same public key address that's being served on the same host. The repository server will need to use a distinct public key identity from the one you use to connect to the repository. This can be arranged by setting a different --config-dir, or by running the server in a container.

Serve a bare git clone for best results. Git will refuse receive-pack on a git clone with a working tree, unless specifically configured to allow this (not recommended).

User mode

git-remote-iroh can also be invoked with subcommands to display the user's public key identity or administer a repository server.

See git-remote-iroh --help for details.

Debugging

Set RUST_LOG=git_remote_iroh=debug to see more detailed debug logs. You can also set RUST_LOG=debug which will also add iroh debug messages.

Internals

git-remote-iroh uses iroh-rings to manage authorization. Rings are collections of named peers which can be granted permission to access various resources.

The peer add command does several things:

• Adds the named peer to a default ring
• Grants the default ring write access to the push:<repo> resource, read access to the fetch:<repo> resource

The push and fetch operations need to be permissioned separately, because iroh-rings does not pass the granted permission to the Transfer implementation. The grant must be bound to the actual operation being performed.

Caveats

Protocol is unstable. No guarantees of compatibility from minor revision 0.x releases. This is still very experimental.

Secret keys are not encrypted at rest.

Access policy is minimal, just enough to enable open source collaboration without total chaos.

Multiple repositories, branch protection, and other typical SCM features are missing.

More ideas

Beyond the above limitations:

• Leverage SSH public key identities. Bootstrap iroh authentication from SSH keys, or offer iroh+ssh?
• Leverage DNS records to define access control rings.
• Local-first SCM built around this. No hubs just spokes.

Credits

Inspired by https://tangled.org/notplants.bsky.social/git-remote-iroh. Originally tried using that project, but it wasn't quite functional and ended up rewriting. I claimed the crate name in crates.io. Hope that's ok.