alkgit/docs/research/alk-stack.md

# Research: alk stack fit for a git server

**Status**: initial pass complete
**Date**: 2026-09-19
**Sources**: local sibling crates at `/workspace/@alkdev/{alkcall,alkhttp,alktls,alkvault}`
(all MIT OR Apache-2.0; alkcall/alkhttp/alktls published on crates.io,
alkvault published at 0.1.0).

## TL;DR

The alk stack covers the parts of a self-hosted git server that were
historically the attack surface: the HTTP and SSH front doors, the wire
framing, TLS/ACME, and secret storage. alkgit contributes the git brain
(storage + smart protocol + repo/permission model) and the server binary that
assembles everything. The architectural match with alkcall is unusually good:
**alkcall's `BiStream` is exactly the byte-stream abstraction git's
packetline-based protocol wants underneath it** — the smart protocol is a
pair of unidirectional streams with request/response framing, which maps
cleanly onto `BiStream::write_half` / `read_half`.

## How the pieces map

| alkgit need | alk crate | mechanism |
|---|---|---|
| Authenticated transport with per-peer identity | alkcall | `Connection`, `Identity`, `IdentityProvider` |
| Internal/external operation split | alkcall | `Visibility::Internal` ops are never wire-callable (ADR-017/024) |
| Per-repo/per-op authorization | alkcall | `AccessControl::check(peer_identity)` + `required_scopes` |
| HTTP front door for git smart-http + admin API | alkhttp | HTTP/1.1 + HTTP/2 serving, adapters for call protocol |
| TLS + ACME for the HTTP endpoint | alktls | rustls server configs, cert resolvers, ACME state machine |
| Encrypted storage of tokens/keys at rest | alkvault | AES-256-GCM vault |
| Byte streams under pkt-line | alkcall | `BiStream` handed to handlers via `ProtocolHandler::connected` |

## The gitea lesson, restated as alkgit design constraints

The pwned-gitea incident (CVE-2026-59774) was reachable because an internal
API was exposed over the internet regardless of auth — the openapi-spec
pattern of "describe everything, enforce somewhere" is the structural
antipattern. alkcall already fixes the API-exposure half: only ops the caller
has privileges for are even visible, and internal ops are structurally
unreachable from the wire. alkgit must extend the same philosophy:

1. **No unauthenticated surface by default.** Even `info/refs` advertisement
   requires an authenticated session unless a repo is explicitly public.
   Anonymous-clone is a per-repo opt-in, not a global default.
2. **Admin API = internal ops.** Repo/user/permission management rides the
   call protocol as `Visibility::Internal` ops over the admin interface
   (or via alkhttp with auth); there is no admin endpoint that exists on the
   same unauthenticated surface as git traffic.
   *(Superseded by ADR-012 §3 / ADR-015 for alkgit's repo ops: the ops are
   `Visibility::External`, gated by scope + the per-repo `manage` grant —
   the gitea lesson is served by the ACL (visible-surface =
   authorized-surface), not by hiding the ops. "Right mechanism, wrong
   axis.")*
3. **No plaintext secrets in the DB.** Credentials/tokens go through
   alkvault; the metadata store holds references, not keys.
4. **Blast-radius thinking carries into the design**: single binary, no
   plugin execution, no markdown renderer by default (a web UI, if it ever
   exists, is a separate phase and separate threat model).

## Interfaces in alkcall terms

Git transport framing per interface:

- **SSH**: the alkcall channels protocol carries a channel whose stream is
  the git pkt-line conversation. The client (`git clone ssh://...`) expects
  an exec of `git-upload-pack '<repo>'`; with alkcall the "SSH channel-like"
  layer provides the framing and identity, and we dispatch on the requested
  command string. alkcall's channel model (channel 0 = call registry, data
  channels = `BiStream`) maps to: one data channel per git session.
- **HTTP**: alkhttp hosts the smart-http endpoints (`GET
  /<repo>/info/refs?service=git-upload-pack`, `POST /<repo>/git-upload-pack`,
  `POST /<repo>/git-receive-pack`). Smart-http is stateless per request
  (V0/V1) or one-shot (V2), which fits the http adapter model; the response
  body is a pkt-line stream we generate.

Both interfaces converge on the same core: **a `BiStream`-like duplex
session + repo identity + caller identity** → `alkgit-transport` runs the
smart protocol and produces/consumes packs via `alkgit-core`. The interfaces
are thin adapters; all policy (auth, ACL, limits) lives before the transport
layer gets the stream. This is the same "ALPN as a service" shape as
alktty/alktunnels/alksocks: the git member of the family, one core, many
front doors, and nothing below the transport boundary knows or cares which
door produced the stream.

## What to verify before architecture commits (POC candidates)

1. **BiStream ↔ pkt-line fit**: run a real `git clone` handshake over an
   alkcall `Connection` using `gix-packetline` async codec end-to-end.
   **Verified (POC-1, 2026-09-20)**: real git 2.43 clones/fetches
   fsck-clean over `Connection → BiStream → tokio-util compat →
   gix-packetline`. See `poc-1-findings.md`.
2. **HTTP smart protocol shape**: confirm alkhttp's streaming response body
   can carry a pack (chunked) and that request bodies stream in without
   buffering the whole POST in memory (receive-pack can be gigabytes).
   **Verified (POC-3, 2026-09-21)**: real git 2.43 clones/fetches
   fsck-clean over `Connection → HttpAdapter → axum custom routes`;
   request bodies stream (`BodyDataStream`, one hyper-read chunk per
   `poll_next` — measured with a dribble probe and git's forced-chunked
   POST path); pack responses stream under back pressure (bounded mpsc →
   `Body::from_stream`, O(counts) RSS on a 60k-object clone). See
   `poc3-findings.md`.
3. **alkcall backpressure/limits vs git sessions**: large clones are
   long-lived, high-throughput, single-direction streams; confirm channels
   buffer limits (ADR-040) don't fight pack streaming, or route git sessions
   as raw duplex streams rather than chunk-framed channels if needed.
4. **alktls ACME**: config shape for the http endpoint; likely trivial.

## Composability boundary (what "ALPN as a service" implies here)

Same family pattern as alktty/alktunnels/alksocks (alknet decomposition):
one core that is front-door-blind, adapters that each speak one door. For
alkgit the boundary is concrete:

- `alkgit-core` + `alkgit-transport` depend on alkcall types only
  (`BiStream`, identity/ACL types); they never depend on alkhttp or
  alkgit-ssh, and carry no http/channel-specific types below the stream.
- The http and ssh crates are replaceable: a downstream app (gitea-like)
  embeds the core + transport and brings its own front doors.
- Admin API = alkcall ops, usable as-is or replaced by a downstream app.

## Version pins in workspace manifests

- `alkcall 0.8` (published), `alkhttp 0.5` (published), `alktls 0.1`
  (published), `alkvault 0.1` (published). The workspace root already pins
  these; bump via workspace.dependencies when siblings release.