alkgit/docs/architecture/decisions/011-per-repo-authorization.md

ADR-011: Per-repo authorization — grants live in repo records

Status

Accepted (resolves OQ-08; grant action set + policy domain amended by ADR-015)

Context

OQ-08 (narrowed by ADR-010) asked for the registry's identity model: what an identity is to the GitRegistry, what identity records exist, where they live, and where credential material goes.

The family precedents constrain the answer:

• alkcall resolves credentials to a stable logical Identity (IdentityProvider, ADR-003; PeerEntry.peer_id stability across key and token rotation, ADR-025). AccessControl::check (ADR-017) is a flat scope/resource match against that resolved identity.
• Doors own credential presentation (alkhttp bearer → token; ssh → fingerprint) and resolve identity before alkgit sees anything.
• alktty/alktunnels gate with a single scope constant because their resources are session- or deployment-scoped. Git cannot use that shape: its authorization is per-repo, and its primary deployment target (vision §"Primary deployment target") makes anonymous fetch on explicitly-public repos first-class — which an identity-scoped gate cannot express, since a static AccessControl with restrictions fails closed on identity: None.

So the git analog of TTY_OPEN_SCOPE is not a scope constant — it is the per-repo check itself, at ADR-007's step-3 position. The gap is real and known: ADR-007 already states "anonymous access on explicitly-public repos grants the same full read path," a clause the static ACL engine cannot express.

Two sub-questions rode along: whether identity records (credential paths, scopes) live in the git metadata store, and what vault material metadata must hold.

Decision

1. Identity space is alkcall's; alkgit stores no identity records. The subject of every authorization decision is the resolved alkcall Identity, keyed by its stable logical id (Identity.id — the alkcall ADR-025 peer_id property, referenced here, not reimplemented). Credential material, fingerprints, and token hashes remain in the door/assembly identity-provider seam (alkcall ADR-003, ADR-025). alkgit's metadata store holds no identity records.

2. Grants live in repo records, keyed on the logical identity id. RepoRecord carries visibility (Public/Private) and grants: identity_id → {read, write} (amended by ADR-015: the action set gains manage — grants: identity_id → {read, write, manage}, a flat set with no hierarchy; manage ⊇ write ⊇ read). Per-repo grants are repo lifecycle data — created with the repo, administered with it — so they are stored with the record, not folded into Identity.resources (which is static identity-provider data resolved per credential path; per-repo entries would bend that model). (Also amended by ADR-015: the grant-key id format is deliberately an opaque string — the identity namespace is the embedder's to define.)

3. Authorization is a policy function in alkgit core, evaluated against the record:

   authorize(record, identity: Option<&Identity>, action: read|write) -> bool
   

   (Amended by ADR-015: the action domain extends to read|write|manage; manage requires identity plus a manage grant, and the grant check is monotonic — a manage grant satisfies write and read checks. The repo-op gate "admin scope OR manage grant" is defined there.)

   • read on a Public repo → allowed for anyone, including None (anonymous-first-class; ADR-007's operative clause).
   • read on a Private repo → identity required with a read grant.
   • write → identity required and a write grant, on every repo (push is always authenticated — vision §"Primary deployment target"; ADR-007).

   Enforcement timing is unchanged: resolve → authorize → authorized-repo marker → transport (ADR-007 steps 1–4). Unknown-repo and unauthorized remain indistinguishable (ADR-008).

4. Data and policy are split across the backend seam. The GitRegistry trait returns the record (resolve); the policy function is alkgit-core code evaluated on it. An embedder with an existing permission system implements resolve and maps its own ACL into grants at resolve time — no policy hook is needed, and none is offered in v1 (a custom-policy override would be an additive default method, a two-way door, added when an embedder needs it).

5. Vault placement: nothing to place in v1. With no identity records and no credentials in metadata (AGENTS.md convention 4), alkvault holds nothing for alkgit in v1. Vault references enter later only if a record grows credential-shaped material (the plausible case: mirroring/remotes records in the consumer half's orbit) — and by then the rule is already fixed: metadata holds references, never secrets.

6. resolve is async. Unlike alkcall's accept-loop identity reads (alknet ADR-035's sync-hot-path constraint — that trait stays sync), the registry resolve runs once per session/request before the first protocol byte; an .await there costs nothing and keeps the backend trait family uniform (ADR-010 sub-decision 4). No cache-invalidation machinery is load-bearing in alkgit v1 — the hot paths (pack generation, ref listing) hit the object DB, not metadata. Backing stores that need invalidation strategies own that inside their impl.

Consequences

• Positive: anonymous-public fetch is expressible without bending AccessControl (the clause ADR-007 pinned is now mechanically true); per-repo grants are administered with the repo, in one store; policy is one function, tested once, in core; the embedder seam for foreign permission systems is resolve-time mapping (no hook, no trait growth); no vault placement question remains for v1.
• Negative: two authorization data sources exist by design — op ACL (scopes, for platform-level capability) and repo grants (for per-repo capability). This split is deliberate but is a thing a reader must hold both of. (Amended by ADR-015: repo administration is the manage grant — the record is the single per-repo authz surface; "ownership never implies git access" is superseded — creation seeds manage, which is a grant, not an ownership-derived bypass, and grants are promotable via update_repo.)
• Neutral: identity-id stability (key rotation) is inherited from alkcall's PeerEntry model, not guaranteed here — alkgit's contract is only "grants key on the stable logical id."

References

• OQ-08 (resolved by this ADR), OQ-16 (the grant-key identity-namespace question this ADR's opaque-string rule defers)
• ADR-007 (enforcement point, anonymous-public read rule), ADR-008 (registry-resolved ids), ADR-010 (trait family, no-doors rule)
• ADR-015 (the manage grant tier — amends this ADR's action set and policy domain)
• alkcall ADR-003/025 (IdentityProvider, PeerEntry stable logical id), ADR-017 (the static ACL engine this complements)
• alktty tty:open posture (the scope-constant pattern this ADR deliberately does NOT reuse)
• vision.md §"Primary deployment target", §"Guiding principles" 1–2
• backend.md §"The trait family" (GitRegistry), ADR-012 (record store + op set)