alkgit/docs/research/vision.md

alkgit Phase 0: Vision and Guiding Principles

Status: draft v1 — 2026-09-19 Phase: 0 (exploration) — this document captures WHAT we are building and WHY before architecture (phase 1) commits to HOW.

Vision

A self-hosted, single-binary git server in Rust: alkgitd serves repositories over http and ssh interfaces with an authenticated-by-default surface, built on the alk stack (alkcall, alkhttp, alktls, alkvault) and gitoxide. It exists because self-hosted git platforms (gitea/gitlab) are large multi-component applications with a long-tail of exposed APIs, plaintext secret storage, and web-UI attack surface — and because CVE-2026-59774 (gitea) demonstrated that a single logic bug in an internally-exposed API is enough for full compromise of the host. Our blast-radius and exposure model is designed from day one, not retrofitted.

The problem, precisely

1. Exposure model: mainstream self-hosted git servers expose a large HTTP API surface regardless of auth (openapi describes everything; enforcement is somewhere else). alkcall inverts this: only operations the caller has privileges for are visible on the wire, and Visibility::Internal ops are structurally unreachable. alkgit inherits that property by using alkcall as the transport/protocol substrate.
2. Secret hygiene: gitea stores secrets plaintext in its DB. alkgit uses alkvault for anything credential-shaped; the metadata store holds vault references, never plaintext secrets.
3. Footprint: a git server is a small program (storage + smart protocol + two front doors). The platform features (issues, PRs, wikis, CI) are where the CVEs live. alkgit v1 is deliberately just the git server; everything else stays out.
4. Language: the whole serving path is Rust (memory-safe, no C deps in the packet path).

Guiding principles (architecture must honor)

1. Authenticated by default — no unauthenticated endpoint exists unless a repo is explicitly marked public; even then, advertisement is the only anonymous surface, and push is always authenticated.
2. Visible-surface = authorized-surface — the alkcall model end to end; no endpoint exists on the wire that a caller cannot see themselves authorized for; internal/admin ops are never wire-reachable.
3. No plaintext secrets at rest — alkvault or nothing.
4. Thin interfaces, one core — http and ssh are adapters that authenticate, resolve a repo, and hand a duplex stream to the transport layer. Policy lives in exactly one place. The core never knows which front door is talking (see "ALPN as a service" below).
5. Honest capability advertisement — the git protocol advertises only what we actually serve (this is both protocol correctness and the security pattern: promise/enforce in the same place).
6. gitoxide for storage/wire primitives — never shell out to the git binary (no GPL dependency, no process injection surface); own the smart protocol server layer ourselves on gitoxide primitives.
7. Bounded resources — every protocol session carries wall-clock, size, and round limits; git servers are internet-facing by definition.

Non-goals for v1

• Web UI of any kind.
• Issues/PR/review features.
• Git LFS (later phase, separate decision).
• federation/replication between alkgit instances (later phase).
• Serving as a general sshd (only the git command surface).
• Windows as a serving platform (linux first; keep code portable-ish but don't test it).

Sub-crate shape (provisional, matches workspace skeleton)

crate	role
alkgit-core	storage: repos, refs, odb, pack read/write, access-rule types
alkgit-transport	smart protocol: pkt-line sessions, advertise, ls-refs, fetch, receive-pack
alkgit-http	http front door (smart-http endpoints + admin API via alkhttp)
alkgit-ssh	ssh front door (git commands over alkcall channels)
alkgitd	binary: config, assembly, TLS/ACME, serving loops

Composability: "ALPN as a service"

alkgit is the git member of the alk "ALPN as a service" family — alktty, alktunnels, and alksocks (socks5) follow the same pattern, and the alknet mono-repo is being decomposed into exactly these pieces for rewrite. The pattern's load-bearing rule: alkgit-core + alkgit-transport never know which front door is talking. The transport layer consumes (identity, repo id, duplex stream, limits) and speaks git; everything above the stream is the adapter's problem. That is what keeps alkgit composable for downstream use:

• A future gitea/gitlab-like application should be able to embed alkgit-core + alkgit-transport (or talk to alkgitd) and add its own UI/issues/PR layer without forking anything here.
• The admin API is a set of alkcall ops, not an embedded web framework — a downstream app can either use it or replace it.
• Nothing in the core may reach upward into alkhttp/alkssh concerns (no http types, no channel types below the transport boundary).

The v1 reduction follows from this: storage + ACL + protocol adapters. A simple static/template web UI for the public repo listing is explicitly out of scope here (would be a separate downstream thing on top).

Primary deployment target

Our own use case is the design anchor: public self-hosted repos with anonymous clone over http, authenticated push, no gitea-style app features in use. So:

• Anonymous fetch (clone/fetch advertisement + pack) on explicitly-public repos is a first-class path, not an afterthought.
• Push is always authenticated, on every repo, no exceptions.
• ACL must be simple enough to reason about completely: repo visibility (public/private) + identity-based read/write, nothing richer in v1.

What phase 0 must still produce before phase 1

• gitoxide capability + version research (gitoxide.md)
• alk stack fit + integration surface (alk-stack.md)
• server-side protocol inventory (git-protocol.md)
• license/reference policy (reference-policy.md)
• POC-1: real git clone over alkcall BiStream using gix-packetline (validates BiStream fit + packetline async codec end-to-end)
• POC-2: server-side pack generation composition (bundle-write vs entries-to-bytes) for a small want/have set
• POC-3: http smart-endpoint streaming shape through alkhttp (chunked pack response, unbuffered receive-pack POST ingestion)
• Convergence: recommended approach summary feeding phase 1 architecture

Immediate threat-model notes carried into architecture

• The admin API (repo/user/permission management) is alkcall Visibility::Internal ops over an admin-only listener; it is never part of the git traffic surface.
• Repo names arriving on the wire are registry IDs, never paths; storage roots are configured server-side only.
• The advertisement phase runs ACL before the first ref line is emitted.
• receive-pack applies ref updates via CAS transactions; hooks/plugins do not exist in v1 (no arbitrary code execution surface at all).