beardthelion
338ff83584
* feat(node): add has_path_scoped_rule predicate for withheld-walk short-circuit Shared predicate (rules.iter().any(path_glob != "/")) both serve and replication paths will use to skip the per-blob withheld walk when no rule can withhold. Doc records the "/"-gate precondition and the validate_path_glob dependency. Adds unit tests plus a gate-aware safety invariant test. * fix(node): skip withheld-walk when no path-scoped rule can withhold (#50) The serve path (git_upload_pack) ran the full per-ref withheld_blob_oids walk on every clone/fetch before falling back to a plain upload_pack, even for repos with no path-scoped rules where the walk can never withhold anything. Cost grew with #42 (per-ref git ls-tree -r). Guard both call sites on has_path_scoped_rule: the serve path skips the spawn_blocking walk entirely and serves upload_pack directly; the replication path generalizes its is_empty() short-circuit to also cover root-only rule sets. Safe because the whole-repo "/" gate runs before both sites, so a denying root rule 404s/withholds upstream and never reaches the predicate. No change to served-pack contents on the success path. * fix(node): gate encrypt-then-pin walk on has_path_scoped_rule (#50) The post-push encrypt-then-pin block in git_receive_pack gated the withheld_blob_recipients call on `!r.is_empty()`, which is true for a root-only `/` rule set. withheld_blob_recipients then runs the same per-ref `git ls-tree` walk (withheld_blob_oids) the short-circuit is meant to avoid, and returns an empty recipient map anyway. Gate it on has_path_scoped_rule to match the serve and replication sites; the skip is behavior-preserving (empty map -> encrypt_and_pin is a no-op). Also align the two remaining call sites to the visibility_pack import alias for consistency. * test(node): cover the serve decision across both has_path_scoped_rule branches Drives the git_upload_pack serve decision over a real bare repo for the INV-2 caller (a reader allowed at whole-repo "/" but denied a path-scoped subtree), exercising both branches the predicate selects: root-only rules skip the walk and serve the full pack (asserting the walk would withhold nothing, so the skip is sound), and a /secret/** rule runs the walk and excludes the secret blob from the served set while keeping the public one.
Gitlawb Node
Decentralized git infrastructure for developers, AI agents, and app delivery.
Gitlawb Node is the open-source node software behind the Gitlawb network. It lets anyone run a self-hosted node, publish repositories under a DID, sign writes with Ed25519 HTTP signatures, replicate git activity across peers, and move toward a resilient app-delivery network where code and build assets can be served closer to users.
Gitlawb is not trying to be only “another git host.” The long-term direction is:
Decentralized GitHub
+ signed agent-native workflows
+ resilient repo replication
+ CDN-style app/code delivery
The mission is simple: once code is pushed to the network, it should not disappear because one server went down.
What is in this repository?
This is a Rust workspace with four crates:
| Crate | Purpose |
|---|---|
gitlawb-node |
The node daemon: Axum HTTP server, git smart-HTTP, Postgres metadata, libp2p gossip, optional S3/Tigris/IPFS/Arweave/Base PoS hooks. |
gl |
The Gitlawb CLI for identity, repos, issues, PRs, bounties, tasks, peers, node status, MCP, and setup flows. |
git-remote-gitlawb |
Git remote helper for gitlawb:// URLs, so normal git clone, git fetch, and git push can talk to Gitlawb nodes. |
gitlawb-core |
Shared primitives: Ed25519 identities, did:key, CIDs, RFC 9421 HTTP signatures, certificates, and UCAN tokens. |
Why Gitlawb Nodes?
Most git hosting today depends on a small number of centralized platforms. Gitlawb Nodes are designed for a different model:
- Own your identity — every user, agent, and node is an Ed25519 keypair represented as
did:key:z6Mk.... - Signed writes by default — write requests use RFC 9421 HTTP Signatures instead of passwords.
- Git-native transport — repositories are still real git repositories served over smart HTTP.
- Agent-native workflows — the
glCLI and MCP server expose repo, issue, task, PR, and UCAN flows to AI agents. - Peer-aware delivery — nodes can announce, discover, gossip, and sync with each other.
- App CDN direction — the network can evolve from decentralized code storage into code + asset + app delivery.
Current status
Gitlawb Node is live early infrastructure. It is useful today, but some security and reliability features are intentionally staged for compatibility with existing nodes.
Good today:
- Local or Docker node startup.
- Postgres-backed repo metadata.
- Bare git repository storage.
- Git smart-HTTP clone/fetch/push.
- RFC 9421-signed writes.
- DID identities.
glCLI workflows.- libp2p peer discovery/gossip foundation.
- Optional Tigris/S3 storage.
- Optional IPFS/Pinata and Arweave/Irys hooks.
- Optional Base node-operator staking/heartbeat hooks.
Known limitations:
- Private repository read enforcement is not wired yet. Treat public nodes as public infrastructure unless you restrict access at your proxy/firewall.
- UCAN chain validation and revocation are not complete.
- Repository write authorization is not capability-complete yet; HTTP signatures prove identity, not full authorization policy.
- Peer writes are signed by upgraded nodes, but strict signed-peer enforcement is opt-in during rolling upgrades.
- GraphQL mutations need mutation-aware auth before becoming a public write surface.
See:
Quickstart: run a local node
The fastest path is Docker Compose. It starts a node and Postgres.
git clone https://github.com/Gitlawb/node.git
cd node
cp .env.example .env
docker compose up -d
Your local node will serve:
| Service | Default |
|---|---|
| HTTP API + git smart-HTTP | http://localhost:7545 |
| libp2p QUIC/UDP | 7546 |
| Postgres | compose-managed |
Verify:
curl http://localhost:7545/health
curl http://localhost:7545/api/v1/stats
Expected health response:
{ "status": "ok" }
Stop it:
docker compose down
Install the CLI
Use the installer once releases are available for your platform:
curl -fsSL https://gitlawb.com/install.sh | sh
Or build from source:
cargo build --release -p gl -p git-remote-gitlawb -p gitlawb-node
Put these binaries on your PATH:
target/release/gl
target/release/git-remote-gitlawb
target/release/gitlawb-node
Check your setup:
gl doctor
First repo flow
Create an identity:
gl identity new
gl identity show
Register against your local node:
gl register --node http://localhost:7545
Create a repo:
gl repo create my-repo --description "My first Gitlawb repo" --node http://localhost:7545
Use the git remote helper:
export GITLAWB_NODE=http://localhost:7545
git clone gitlawb://did:key:z6Mk.../my-repo
For public-network use, make sure GITLAWB_NODE points to the node you want. The helper defaults to localhost for local development.
Architecture
┌──────────────────────────┐
│ gl CLI / git / AI agents │
└────────────┬─────────────┘
│ signed HTTP writes / git smart-HTTP
↓
┌──────────────────────────┐
│ gitlawb-node │
│ Axum API + git routes │
└────────────┬─────────────┘
│
┌────────┴────────┐
↓ ↓
Postgres Bare git repos
metadata local disk / optional S3
│ │
└────────┬────────┘
↓
libp2p peers
gossip + discovery + sync
↓
optional IPFS / Arweave / Base PoS
Core concepts
| Concept | Meaning |
|---|---|
| DID | A user, agent, or node identity derived from an Ed25519 public key. |
| HTTP Signature | RFC 9421 signature proving control of the DID key for write requests. |
| Ref certificate | Signed record of a ref update. Useful for audit and replication. |
| UCAN | Delegation token for future capability-based workflows. |
| Peer announce | Node-to-node HTTP announcement of DID + public URL. |
| Gossipsub | libp2p topic for ref-update events. |
| Smart HTTP | Standard git protocol over HTTP for clone/fetch/push. |
API surface
The node exposes both git smart-HTTP routes and JSON APIs.
Common public read routes:
GET /health
GET /
GET /api/v1/stats
GET /api/v1/contracts
GET /api/v1/repos
GET /api/v1/repos/{owner}/{repo}
GET /api/v1/repos/{owner}/{repo}/tree
GET /api/v1/repos/{owner}/{repo}/blob/{path}
GET /api/v1/repos/{owner}/{repo}/issues
GET /api/v1/repos/{owner}/{repo}/pulls
GET /api/v1/peers
GET /{owner}/{repo}/info/refs
POST /{owner}/{repo}/git-upload-pack
Signed write routes include:
POST /api/v1/repos
POST /api/register
POST /api/v1/repos/{owner}/{repo}/fork
POST /api/v1/repos/{owner}/{repo}/issues
POST /api/v1/repos/{owner}/{repo}/pulls
POST /api/v1/repos/{owner}/{repo}/pulls/{number}/merge
POST /api/v1/repos/{owner}/{repo}/hooks
POST /api/v1/bounties/{id}/...
POST /{owner}/{repo}/git-receive-pack
Peer write routes support staged rollout:
POST /api/v1/peers/announce
POST /api/v1/sync/notify
POST /api/v1/sync/trigger
When GITLAWB_REQUIRE_SIGNED_PEER_WRITES=false, unsigned legacy peers are accepted, but signed requests are verified when signature headers are present. Once all live peers upgrade, operators can set:
GITLAWB_REQUIRE_SIGNED_PEER_WRITES=true
Configuration
All configuration is via environment variables. See .env.example for the full reference.
Minimum required for a persistent node:
DATABASE_URL=postgresql://gitlawb:changeme@localhost:5432/gitlawb
Important node settings:
| Variable | Purpose |
|---|---|
GITLAWB_HOST / GITLAWB_PORT |
HTTP bind address and port. |
GITLAWB_REPOS_DIR |
Local bare repo storage directory. |
GITLAWB_PUBLIC_URL |
Public HTTP URL announced to peers. |
GITLAWB_P2P_PORT |
libp2p QUIC/UDP port. Use 0 to disable. |
GITLAWB_BOOTSTRAP_PEERS |
Comma-separated HTTP peer URLs. |
GITLAWB_P2P_BOOTSTRAP |
Comma-separated libp2p multiaddrs. |
GITLAWB_BOOTSTRAP_DISABLE_SEEDS |
Disable embedded seed peers for isolated dev/test networks. |
GITLAWB_REQUIRE_SIGNED_PEER_WRITES |
Require signed peer announce/sync writes. |
GITLAWB_AUTO_SYNC |
Enable automatic sync from known peers. |
GITLAWB_MAX_PACK_BYTES |
Max git pack body size for smart-HTTP routes. |
GITLAWB_TIGRIS_BUCKET |
Optional S3/Tigris shared repo storage bucket. |
GITLAWB_PINATA_JWT |
Optional Pinata/IPFS warm-storage pinning. |
GITLAWB_IRYS_URL |
Optional Irys/Arweave permanent anchoring. |
Production note: change the default Postgres password before exposing a node publicly.
Optional node staking
Gitlawb Node includes optional Base L2 node-operator hooks. Operators can register a node DID, stake $GITLAWB, and post heartbeats.
PoS is disabled unless these are configured:
GITLAWB_CONTRACT_NODE_STAKING=0x...
GITLAWB_OPERATOR_PRIVATE_KEY=0x...
GITLAWB_CHAIN_RPC_URL=https://mainnet.base.org
Recommended for operators:
GITLAWB_OPERATOR_STRICT_MODE=true
GITLAWB_HEARTBEAT_INTERVAL_HOURS=20
Read:
Use a dedicated low-balance operator wallet. Do not use a treasury wallet as the heartbeat key.
Building from source
Requires Rust 1.91+.
cargo build --release -p gitlawb-node -p gl -p git-remote-gitlawb
Run tests:
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
Run the node from source:
DATABASE_URL=postgresql://gitlawb:changeme@localhost:5432/gitlawb \
cargo run -p gitlawb-node --release
macOS menu bar app
A native Swift/AppKit menu bar app is included for managing a local Docker Compose stack without living in the terminal.
Requirements:
- macOS 26+
- Xcode Command Line Tools
- Docker Desktop, OrbStack, or Colima
Build:
./scripts/build-macos-app.sh
Output:
dist/Gitlawb Node.app
dist/Gitlawb Node.dmg
Features:
- Start/stop local node stack.
- Status indicator.
- Settings GUI.
- Auto-start on login.
- Docker runtime detection.
Unsigned local build:
xattr -cr "dist/Gitlawb Node.app"
Roadmap
The current maintainer focus is live-network stability first.
Short-term priorities:
- Keep CI green: fmt, clippy, tests, release build.
- Add Docker and installer smoke tests.
- Improve operator docs and
gl doctorchecks. - Harden peer writes and publish the signed-peer rollout plan.
- Implement repo write authorization: owner checks, protected branches, and UCAN capability checks.
- Implement private-read enforcement or remove private repo affordances until it exists.
- Add metrics for pushes, fetches, pack sizes, peer sync, failed auth, and webhooks.
Product direction:
- Reliable repo replication.
- Health-aware peer syncing.
- CDN-style clone/fetch routing to healthy replicas.
- App asset/build delivery from nodes.
- Operator dashboard and desktop UX.
Read the maintainer roadmap:
docs/MAINTAINER-ROADMAP.md
Contributing
Start here:
Good first contribution areas:
- docs and install polish
- Docker smoke tests
- CLI error messages
gl doctorchecks- operator dashboard UX
- test coverage for peer sync and signed writes
Security issues should follow SECURITY.md.
License
Licensed under either of:
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project shall be dual licensed as above, without any additional terms or conditions.