alkdev/alkgit

0 Fork 0

Files

T

glm-5.3-flash 8f73da5d12 docs(architecture): phase 1 bootstrap — specs, 9 ADRs, OQ tracker

Architecture documentation structure per sdd_process phase 1:

- README index (doc table, ADR table, lifecycle), overview with crate
  map, dependency rules, and security invariants
- Component specs: storage, transport, http, ssh, alkgitd (all draft)
- ADRs 001-009: crate decomposition, front-door-blind core, V2-first
  protocol, pack pipeline (data::output generation / data::input
  ingestion), session substrate types, http adapter composition
  (proposed, OQ-01), ACL-before-advertisement, registry-resolved repo
  identity, bounded-resources budgets
- open-questions.md: OQ-01..08 with two deferred(scope), one
  deferred(unclear), door-type definitions, blocker tracker tasks in
  tasks/architecture/
- v1 ssh-door decision recorded: russh terminates wire SSH in alkgitd;
  alkcall channels stay the internal substrate (OQ-03 partially
  resolved)

Two review rounds (fresh-context subagent): 4 critical + 17 warnings
fixed in round one; zero critical + 4 warnings + 5 suggestions fixed in
round two. All ADR/OQ cross-references verified resolving.

2026-09-21 03:55:33 +00:00

2.0 KiB

Raw Blame History

ADR-008: Wire repo names are registry IDs, never paths

Status

Accepted

Context

Repo names arrive on the wire in three shapes: the git:// first-request line (git-upload-pack '<repo>'\0host=…), the ssh exec command string (git-upload-pack '<repo>'), and the http path segment (/<repo>/info/refs). All three are attacker-controlled. Treating them as filesystem paths (even with ad-hoc sanitization) is the classic git-server traversal bug — and docs/research/git-protocol.md §"Security-relevant protocol notes" flags exactly this.

Decision

Wire-supplied repo names are IDs: opaque registry keys resolved server-side to configured storage roots.

The registry is alkgit's authoritative (repo id → storage root + visibility + ACL scope) mapping, owned by alkgit-core.
Resolution failure and authorization failure are indistinguishable to the caller (ADR-007 step 2's no-existence-oracle rule).
Wire names are never joined, normalized, or canonicalized into paths. Path construction happens only from registry-resolved roots.
The same never-execute rule covers the ssh exec command string: it is parsed (fixed grammar: service name + quoted repo argument), never interpreted by a shell and never passed to a subprocess (convention 6's no-shelling-out invariant). Unknown commands get a fixed refusal.
The registry's own backing store is a separate decision (OQ-06).

Consequences

Path traversal is structurally impossible on the serving path.
Repo renames/migrations are registry edits, not filesystem moves (the storage root indirection absorbs them).
The registry must be available (or cached) at session start; its unavailability is a config/ops error surfaced as session failure, never a path-guessing fallback.

References

docs/research/git-protocol.md §"Security-relevant protocol notes"
docs/research/vision.md §"Immediate threat-model notes"
ADR-007 (the resolve-then-authorize order)
storage.md §registry, OQ-06 (registry backing)

2.0 KiB Raw Blame History