repo.box Spec: Tech Stack

Language: Rust

Chosen for type safety (security-critical permission engine), crypto ecosystem alignment (alloy, foundry, reth), and prior art (Radicle Heartwood proves Rust + git works).

Core Libraries

Git

• gitoxide (gix) — Pure Rust git implementation. Handles object storage, pack protocol, refs, diffs. Actively maintained by Sebastian Thiel (also maintainer of git2 Rust bindings). Used for all local git operations.
• Git Smart HTTP Protocol — Implement info/refs, git-upload-pack, git-receive-pack endpoints using gitoxide for pack negotiation and object transfer.

Ethereum / Crypto

• alloy — Modern Rust Ethereum library (by Paradigm). For ERC-8128 signature verification (ecrecover), ERC-1271 smart contract calls, and onchain group resolver eth_calls.
• alloy-signer — For client-side request signing (server auth, post-hackathon).
• alloy-provider — JSON-RPC provider for server-side onchain calls.

HTTP

• axum — Async HTTP framework (by Tokio team). For the git smart HTTP endpoints, REST API, and ERC-8128 middleware.
• tower — Middleware layer. ERC-8128 verification as a tower middleware that extracts identity before hitting route handlers.

Config

• serde + serde_yaml — Parse .repobox/config.yml YAML.
• Custom permission parser for the free-form permission syntax.

Storage

• Filesystem — Bare git repos on disk (standard git storage).
• redb or SQLite (rusqlite) — Nonce dedup store, resolver cache, metadata indexes.

CLI

• clap — Argument parsing for the binary.
• Single binary that operates in two modes: git shim (invoked as git, intercepts commands) and server (repobox serve).

Architecture

┌─────────────────────────────────────────────┐
│              Git Shim (local)                │
│  (intercepts: commit, push, merge, branch)   │
│                                              │
│  ┌──────────┐  ┌──────────┐  ┌───────────┐  │
│  │ Identity │  │Permission│  │  Real Git  │  │
│  │ (local)  │  │ Engine   │  │ (delegate) │  │
│  └──────────┘  └──────────┘  └───────────┘  │
│        │              │             │        │
│  ┌─────────────────────────────────────────┐ │
│  │    .repobox/config.yml parser + gitoxide diffs   │ │
│  └─────────────────────────────────────────┘ │
└─────────────────────────────────────────────┘
                      │
                  ERC-8128
                  signed HTTP
                  (post-MVP)
                      │
┌─────────────────────────────────────────────┐
│              reporepobox serve (server)               │
│                                              │
│  ┌──────────────────────────────────────┐    │
│  │  axum HTTP server                    │    │
│  │                                      │    │
│  │  ┌────────────┐  ┌───────────────┐   │    │
│  │  │ ERC-8128   │  │ Git Smart     │   │    │
│  │  │ middleware  │  │ HTTP protocol │   │    │
│  │  └────────────┘  └───────────────┘   │    │
│  └──────────────────────────────────────┘    │
│                                              │
│  ┌──────────┐  ┌──────────┐  ┌───────────┐  │
│  │ Identity │  │Permission│  │ Workflow   │  │
│  │ (verify) │  │ Engine   │  │ Engine     │  │
│  └──────────┘  └──────────┘  └───────────┘  │
│        │              │             │        │
│  ┌──────────┐  ┌──────────┐  ┌───────────┐  │
│  │  Group   │  │  Config  │  │  Nonce /   │  │
│  │ Resolvers│  │  Parser  │  │  Cache DB  │  │
│  │(onchain/ │  │ (.repobox    │  │ (redb/     │  │
│  │ http)    │  │  config) │  │  sqlite)   │  │
│  └──────────┘  └──────────┘  └───────────┘  │
│        │                                     │
│  ┌─────────────────────────────────────────┐ │
│  │          gitoxide (repo storage)        │ │
│  └─────────────────────────────────────────┘ │
└─────────────────────────────────────────────┘

Key Design Decisions

Single Binary

Single binary, two modes:

Git shim mode (invoked as git via PATH/symlink):

• Intercepts git commit, git merge, git push, git checkout -b, git branch
• Checks permissions against .repobox/config.yml, then delegates to real git
• Read-only commands pass through unchanged
• git repobox init — set up a repo with .repobox/config.yml
• git repobox lint, git repobox check — config tooling

Server mode:

• repobox serve — start the HTTP git server with ERC-8128 auth (post-hackathon)

Shared Engine

The permission engine and workflow engine are library crates shared between CLI and server. Same code, same rules, enforced in both places.

ERC-8128 as axum Middleware

// Pseudocode
async fn erc8128_middleware(req: Request, next: Next) -> Response {
    let result = verify_erc8128(&req).await;
    match result {
        Ok(identity) => {
            req.extensions_mut().insert(identity);
            next.run(req).await
        }
        Err(e) => Response::unauthorized(e),
    }
}

Every request hits the middleware first. By the time a route handler runs, the identity is already verified and available.

Async Runtime

Tokio. Required by axum, alloy, and beneficial for concurrent onchain resolver calls.

Crate Structure

repobox/
  crates/
    reporepobox-core/          # Identity types, group interface, permission engine
    repobox-config/        # .repobox/config.yml YAML parser, permission syntax parser
    reporepobox-git/           # gitoxide wrappers, smart HTTP protocol
    reporepobox-auth/          # ERC-8128 verification, alloy integration
    reporepobox-groups/        # Group resolvers (static, onchain, http)
    reporepobox-workflows/     # Workflow engine, state machine, JSONL
    reporepobox-server/        # axum HTTP server, middleware, API routes
    reporepobox-shim/          # git shim, command interception, local enforcement
  src/
    main.rs            # Binary entry point (dispatches to CLI or server)

Prior Art We're Building On

What We Don't Build (v1)

• Web UI — CLI and API first. Web UI is a future layer on top of the API.
• Federation/P2P — Single server. Not Radicle's gossip model.
• CI/CD — Webhook actions trigger external CI. We don't run builds.
• Package registry — Out of scope.
• Git LFS — Future addition.