e060442017
Radicle's Visibility::Private is enforced entirely by access control at
the replication layer -- git objects for a private repo are plain,
unencrypted objects, protected only by "unauthorized peers are never
given them" (identity/doc.rs). That protection has no jurisdiction over
IPFS's own block-exchange layer: once a legitimate collaborator's IPFS
daemon pins content and joins the network, anyone who obtains the CID by
any means can fetch the plaintext directly.
Adds envelope encryption for private repos: a random per-object content
key encrypts the file (XChaCha20-Poly1305), wrapped once per authorized
recipient (delegates + private allow-list) via ECDH between Radicle
identity keys (already Ed25519, no separate keypair needed) plus HKDF.
The wrapped keys travel in the same refs/notes/rad-lfs note as the CID.
New:
- crates/radicle-cli/src/lfs_crypto.rs -- encryption core (envelope
schema, encrypt/decrypt, key wrapping, recipient resolution, signer
loading).
- `rad lfs store`/`rad lfs fetch` -- plumbing commands that now own the
entire IPFS add/cat + git-notes read/write step (encrypting/decrypting
as needed), replacing what the pre-commit hook and rad-lfs-transfer
used to do directly. This collapses what would've become a third copy
of the note-format logic down to one canonical implementation.
- `rad lfs rekey` -- since Radicle's access control is retroactive (a
newly-authorized DID can replicate full history) but encrypted objects
aren't automatically re-wrapped for new recipients, this command lets
an already-authorized collaborator grant a newly-authorized one access
to previously-committed objects, without re-encrypting or re-uploading
content. Revocation remains unsolved, matching Radicle's own model
(already-replicated/decrypted content can't be un-known).
Operational requirement: private-repo LFS operations need a signer
capable of ECDH, which only an unencrypted keystore or RAD_PASSPHRASE
provides (an ssh-agent-only signer can sign but not do key agreement).
Fails fast with an actionable error rather than hanging on a passphrase
prompt inside a non-interactive git hook.
Breaking change: the refs/notes/rad-lfs note format moves from bare
`cid=<cid>` text to JSON (`{"v":1,"cid":"...","enc":...}`). No migration
path -- prototype, no external users yet.
Verified end-to-end with real Radicle profiles/identities (not just the
transfer-agent protocol): a private repo's IPFS-stored content is
confirmed ciphertext (byte-different from plaintext, +16 bytes AEAD tag);
an authorized peer decrypts correctly; an unauthorized peer is denied
with a clear error and no leaked content; RAD_PASSPHRASE is required and
enforced with a fast, clear failure; and rekey correctly grants a
newly-authorized peer access to a pre-existing object while leaving other
recipients' entries untouched.
|
||
|---|---|---|
| .cargo | ||
| .config | ||
| .github | ||
| .radicle | ||
| build | ||
| crates | ||
| debian | ||
| radicle-lfs-transfer@d67ac79f40 | ||
| scripts | ||
| simulation | ||
| systemd | ||
| windows | ||
| .codespellrc | ||
| .dockerignore | ||
| .env.seed | ||
| .envrc.sample | ||
| .git-blame-ignore-revs | ||
| .gitignore | ||
| .gitmodules | ||
| .gitsigners | ||
| .rustfmt.toml | ||
| .typos.toml | ||
| ARCHITECTURE.md | ||
| CHANGELOG.md | ||
| CONTRIBUTING.md | ||
| Cargo.lock | ||
| Cargo.toml | ||
| DCO | ||
| HACKING.md | ||
| LFS-IPFS.md | ||
| LICENSE-APACHE | ||
| LICENSE-MIT | ||
| README.md | ||
| RELEASE.md | ||
| VERSIONING.md | ||
| build.rs | ||
| clippy.toml | ||
| deny.toml | ||
| flake.lock | ||
| flake.nix | ||
| git-remote-rad.1.adoc | ||
| justfile | ||
| rad-id.1.adoc | ||
| rad-patch.1.adoc | ||
| rad.1.adoc | ||
| radicle-node.1.adoc | ||
| rust-toolchain.toml | ||
README.md
❤️🪵
Fork: Git LFS support, backed by IPFS
This is a fork of upstream
radicle-dev/heartwoodadding Git LFS (large file) support, with large file content stored on each contributor's own local IPFS node rather than a central server. Everything below the horizontal rule is upstream's own README, unchanged. SeeLFS-IPFS.mdfor the full design, troubleshooting, and background — this section is just the quick start.The LFS byte-transfer logic lives in a separate, small companion repository: radicle-lfs-transfer, included here as a git submodule.
Dependencies (Arch Linux)
# To build and install rad/radicle-node/radicle-lfs-transfer sudo pacman -S --needed rust git openssh base-devel # To actually use Git LFS (not needed to build/install anything) sudo pacman -S --needed git-lfs kuboOn other distributions: a Rust toolchain (e.g. via rustup), Git, OpenSSH, a C toolchain — and, only for using
rad lfs, Git LFS and Kubo.Zero to usable
# Clone with the submodule git clone --branch rad-lfs-ipfs --recurse-submodules \ ssh://git@git.hswro.org:9022/mab122/radicle-heartwood-lfs.git cd radicle-heartwood-lfs # Build & install rad, radicle-node, git-remote-rad, and rad-lfs-transfer to one place cargo install --path crates/radicle-cli --force --locked --root ~/.radicle cargo install --path crates/radicle-node --force --locked --root ~/.radicle cargo install --path crates/radicle-remote-helper --force --locked --root ~/.radicle cargo install --path radicle-lfs-transfer --force --locked --root ~/.radicle # Add the install root to your PATH (e.g. in ~/.bashrc / ~/.zshrc) export PATH="$HOME/.radicle/bin:$PATH" # Verify rad --versionFrom here, use
radexactly as upstream describes below (rad auth,rad init, etc). The only new commands arerad lfs init(run once per repository you want large-file support in) andrad lfs rekey(run after granting a new collaborator access to a private repository, so they can decrypt previously-committed LFS objects too) — seeLFS-IPFS.mdfor that workflow and how private-repo content gets encrypted before it reaches IPFS. Nothing above requires IPFS; Git LFS support specifically needs a runningipfs daemon, andrad lfs initwill tell you plainly if one isn't reachable rather than failing confusingly later.
Radicle Heartwood Protocol & Stack
Heartwood is the third iteration of the Radicle Protocol, a powerful
peer-to-peer code collaboration and publishing stack. The repository contains a
full implementation of Heartwood, complete with a user-friendly command-line
interface (rad) and network daemon (radicle-node).
Radicle was designed to be a secure, decentralized and powerful alternative to code forges such as GitHub and GitLab that preserves user sovereignty and freedom.
See the Radicle home page for general information, and the Zulip chat to talk to the project.
See the Protocol Guide for an in-depth description of how Radicle works.
Installation
Requirements
- Linux or Unix based operating system.
- Git 2.34 or later
- OpenSSH 9.1 or later with
ssh-agent
📀 From binaries
Requires
curlandtar.
Run the following command to install the latest binary release:
curl -sSf https://radicle.dev/install | sh
Or visit our download page.
📦 From source
Requires the Rust toolchain.
You can install the Radicle stack from source, by running the following commands from inside this repository:
cargo install --path crates/radicle-cli --force --locked --root ~/.radicle
cargo install --path crates/radicle-node --force --locked --root ~/.radicle
cargo install --path crates/radicle-remote-helper --force --locked --root ~/.radicle
Or directly from our seed node:
cargo install --force --locked --root ~/.radicle \
--git https://seed.radicle.dev/z3gqcJUoA1n9HaHKufZs5FCSGazv5.git \
crates/radicle-cli crates/radicle-node crates/radicle-remote-helper
Running
Systemd unit files are provided for the node under the /systemd folder.
They can be used as a starting point for further customization.
For running in debug mode, see HACKING.md.
Feedback
If you have feedback, feel free to create issues using rad issue, join
our Zulip, or email feedback@radicle.dev.
Emails sent to this address are automatically posted to
our public #feedback channel on Zulip, revealing the
From header (which usually contains your name and email
address). This allows us to discuss your feedback on Zulip, and, if necessary,
respond to you via email.
Contributing
See CONTRIBUTING.md and HACKING.md for an introduction to contributing to Radicle.
License
Radicle is distributed under the terms of both the MIT license and the Apache License (Version 2.0).
See LICENSE-APACHE and LICENSE-MIT for details.