Architecture and diagrams

1. Overview

The product promise is operational zero-knowledge in the SaaS sense: the operator routes and stores opaque ciphertext and signed metadata, but does not possess plaintext repository data or repo content keys. The trust boundary is the user's signed native binary — a browser session is a convenience tier, not a root of trust.

System-level diagram

2. Trust model

hushgit assumes an active server-side attacker that can read, modify, reorder, replay, or equivocate over all server-side data. Confidentiality therefore depends on client-side encryption and integrity depends on signed writes plus client-pinned state. There are four distinct trust tiers in the product:

3. Workspace layout

The monorepo is split by language and by what owns the security-critical path. Everything that touches keys, signatures, or ciphertext is in Rust. The TypeScript surface is the convenience UI plus a thin SDK that mirrors the protocol types.

.
├── apps/
│   ├── hushgit-cli/               Rust CLI: keys · auth · repo · pr · doctor
│   ├── hushgit-server/            Rust HTTP API (Axum + sqlx + S3)
│   ├── hushgit-runner/            Rust self-custodied CI runner
│   ├── hushgit-desktop-sidecar/   Rust IPC sidecar — native authority for Electron
│   ├── git-remote-hushgit/        Rust Git remote-helper entrypoint
│   ├── web/                       Vite + React encrypted repo/PR browser (convenience)
│   ├── desktop/                   Electron renderer + main process
│   └── landing/                   Astro static site, waitlist on Cloudflare D1
├── crates/
│   ├── hushgit-core/              Client orchestration (device store, sessions, remotes)
│   ├── hushgit-crypto/            Envelopes, ChaCha20Poly1305, Ed25519, X25519
│   ├── hushgit-events/            Signed event DAG, manifest, merge-cert verifiers
│   ├── hushgit-git/               Hardened shell-out to the git CLI, refs/packs/bundles
│   ├── hushgit-keys/              Key hierarchy, keyring draft, recipient models
│   ├── hushgit-native-client/     Account/device flows requiring native custody
│   ├── hushgit-protocol/          Shared wire types: events, manifest, keyring, HTTP, CBOR
│   ├── hushgit-server-client/     Hardened HTTP client for server calls
│   ├── hushgit-storage/           ChunkStore trait + local backend
│   └── hushgit-wasm/              Future browser bindings (placeholder)
├── packages/
│   ├── sdk/                       TS protocol mirror + browser HushgitClient
│   └── ui/                        Shared React components (PR, shell, status)
├── api/openapi.yaml               Pinned HTTP contract
├── docs/                          Threat model · whitepaper · ADRs · this file
├── infra/dev/                     Docker compose for local Postgres + MinIO
└── xtask/                         Rust workspace maintenance

4. Layered architecture

Crates form a strict three-layer stack. The foundation owns wire types and primitive crypto. A middle orchestration layer composes those primitives into device stores, keyrings, sessions, and remotes. Apps sit at the top and are the only place where I/O, argument parsing, and process boundaries live.

5. Crate dependency graph

Concrete inter-crate edges. Foundation crates have no inbound dependencies from other hushgit crates and are deliberately small. The hub is hushgit-core, which every native app links against.

Edge summary

Checked against each crate's runtime [dependencies] by cargo run -p xtask -- check-architecture-deps (part of make check); dev-dependencies are not edges here. Note that hushgit-runner depends on protocol, crypto, core, and native-client (signed-manifest verification, checkout materialization, and shared transparency verification); it does not link hushgit-events, so its event verification helpers come from local hushgit-protocol payload helpers plus hushgit-crypto signatures rather than the events crate.

6. Cryptographic envelopes

Every byte that crosses the trust boundary is wrapped in a single envelope type. The envelope carries the algorithm, purpose, and key identifier as plaintext fields and binds them as authenticated associated data, so the server cannot strip the header or cross-mount ciphertext between purposes.

pub struct EncryptedEnvelope {
    pub version: u32,             // currently 1
    pub algorithm: String,        // "ChaCha20Poly1305+BLAKE3-Derive/v1"
    pub purpose: CryptoPurpose,   // domain separator (enum)
    pub key_id: String,           // logical key id, e.g. "repo-key-v1"
    pub nonce: Vec<u8>,           // 12 random bytes
    pub ciphertext: Vec<u8>,      // AEAD ciphertext + 16-byte tag
}

pub enum CryptoPurpose {
    Chunk,         // encrypted Git pack chunk
    Manifest,      // signed encrypted manifest
    Refs,          // reserved
    PullRequest,   // PR payload
    Comment,       // review comment
    EventPayload,  // generic event payload
    Keyring,       // encrypted keyring snapshot
    DeviceStore,   // local on-disk device key store
}

7. Key hierarchy

Every repository has a single 32-byte symmetric content key per epoch. The keyring WrappedRepoKey list wraps that key to each authorized device and each active personal recovery key (the WrappedRepoKeyRecipient enum also includes User and Org variants for future per-user / per-org wrapping). The server stores wrap blobs but never the content key itself.

Device key shape

Every device holds two distinct Ed25519/X25519 keypairs:

• Signing keypair (Ed25519). Signs repo events, signed manifests, keyring changes, chunk uploads, and runner approvals. The public key is recorded in the keyring's authorized_devices and in repo_signing_keys on the server.
• Wrapping keypair (X25519, static). Used to wrap the repo content key with X25519-HKDF-SHA256+ChaCha20Poly1305/v1 (see REPO_KEY_WRAP_ALGORITHM). The public key is recorded in the keyring; the private key never leaves the device.

A device id is bound to its signing key — rotating signing material requires provisioning a new device, not re-registering the same id. Convenience accounts hold a browser_convenience Ed25519 key used only to identify the browser session for account-scoped reads.

8. Keyrings & epoch rotation

Keyring state is the authorization root for a repository. It is modeled as a signed encrypted snapshot plus a linear log of signed keyring-change events. Clients never trust a snapshot in isolation — they replay the change log from a locally pinned trusted head and compare the replayed state to the candidate snapshot before using any device or recovery signer.

pub struct EncryptedKeyring {
    pub signature: Vec<u8>,
    pub signer: KeyringSigner,
    pub version: u32,
    pub repo_id: RepoId,
    pub sequence: u64,
    pub keyring_epoch: u64,
    pub key_epoch: KeyEpoch,
    pub authorized_devices: Vec<AuthorizedDevice>,
    pub revoked_devices: Vec<RevokedDevice>,
    pub wrapped_repo_keys: Vec<WrappedRepoKey>,
    pub keyring_event_head_ids: Vec<EventId>,
    pub recovery_policy: Option<RecoveryPolicy>,
}

9. Signed event log

Every mutating action is a SignedEvent appended to a per-repository append-only log. Events form a parent-linked DAG so clients can detect truncation, reordering, replay, and equivocation. Runner audit lives in a separate per-repo repo_runner_events stream that may reference repo events as parent hints.

pub struct SignedEvent {
    pub version: u32,
    pub event_id: EventId,
    pub repo_id: RepoId,
    pub actor_user_id: UserId,
    pub signer_device_id: DeviceId,
    pub kind: RepoEventKind,
    pub encrypted_payload_chunk_id: Option<ChunkId>,
    pub parent_event_ids: Vec<EventId>,
    pub created_at_unix_ms: i64,
    pub signature: Vec<u8>,
}

pub enum RepoEventKind {
    Push,
    RefUpdate,
    PolicyUpdate,
    PullRequestCreate,
    PullRequestUpdate,
    CommentCreate,
    CommentUpdate,
    CommentDelete,
    ReviewSubmit,
    MergeIntent,
    MergeCertificate,
    KeyringChange,
}

10. Signed manifest

A signed manifest is the per-repository state snapshot: refs, pack chunks, the keyring epoch in force, and the content-key epoch used to seal everything inside the envelope. Manifest validation pins all three so an attacker cannot replay an old manifest under a newer keyring or pair new refs with an old keyring.

Protected branch policy

Protected-branch policy bytes are signed as part of the encrypted manifest. The server stores signed events, encrypted chunks, packs, and the signed manifest under CAS, but it does not decide Git ancestry or whether a merge satisfies policy. Clients validate protected refs against the manifest:

• required_approvals — distinct eligible approving users, excluding the pull request author and merge certificate signer.
• direct_push — Deny / AllowAll / Allow{ users[], devices[]? }.
• protected_from_object_id — pins the object that protection started from, so advancement that bypasses the signed update log is detectable.
• MergeCertificate — detached signature over PR id, source/target/result object ids, pull request author, approval event ids (up to 64), signer device, timestamp. Protected refs advance only via a valid cert or an explicit policy-authorized direct push.

11. End-to-end push & fetch

The Git remote helper (git-remote-hushgit) is the only place where Git's transport talks to the network. git push hushgit::<url> main ends up generating an encrypted pack chunk, signing the upload, signing a Push event, and CAS-updating the manifest.

Fetch reverses this: the helper fetches the manifest, validates its signature and bindings, validates the keyring change log up to keyring_event_head_ids, downloads referenced encrypted chunks, decrypts them locally, and imports the resulting pack into a temporary mirror that Git fetches from. Ciphertext reads are themselves authenticated: chunk and repo-object GETs carry a timestamped fetch statement signed by an active native-trusted repo signer (x-hushgit-chunk-fetch-signature / x-hushgit-repo-object-fetch-signature), so a session bearer alone cannot bulk-download ciphertext.

12. Server storage model

The server is split into two planes: a relational metadata plane in Postgres (managed by sqlx migrations under apps/hushgit-server/migrations/) and a content plane on an S3-compatible blob store. All values that cross the trust boundary are opaque ciphertext or signed envelopes; the server never sees plaintext.

HTTP surface, grouped

13. Self-custodied CI runner

The first CI product is bring-your-own-machine. The runner is a repo-scoped principal, not an account device — its signing key authorizes job claim, heartbeat, completion, and runner audit events, plus lease-gated job-scoped fetches of the encrypted job spec, signed manifest, and pack chunks, and encrypted result-chunk uploads. Repo key material reaches the runner only through owner-controlled handoff: the owner CLI exports a repo content key file that the operator places on the runner host — the runner is never a keyring recipient. With that material the runner verifies the owner-signed manifest and materializes a checkout in an isolated workspace before executing the job.

14. Trust-tier matrix

Concrete summary of which client tier can do what. Anything outside this matrix is by construction either client-side computation or denied by the protocol.

✓ allowed and authoritative · "read" allowed but ciphertext-only · "via sidecar"/"via session" delegated through native authority · "runner events · job results" the runner key signs runner job/audit routes and job-scoped result uploads · "job-scoped" fetch statements bind job, attempt, and lease ids and require an active lease

15. Threat-model notes worth memorising

16. Glossary