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.
This commit is contained in:
1 parent
70815e22a0
commit
8f73da5d12
21 files changed
+1669
No files matched your search
@@ -0,0 +1,46 @@
|
||||
# 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)
|
||||
Reference in new issue
Block a user