43f2bd64

Add a design for repository governance

a73x 2026-08-09 14:01

Commit message

Add a design for repository governance

docs/superpowers/specs/2026-08-09-repo-governance-design.md

@@ @@ -0,0 +1,307 @@ @@
+# Repository Governance — Design
+Date: 2026-08-09
+Status: Draft — open questions at the end must be settled before implementation
+## Purpose
+Make the server's governance a property of the repositories it serves, rather
+than of files on the host. Who may reach the server, who may move a repository's
+canonical state, and who may contribute to it all become git objects: reviewable,
+attributable, and revertable.
+## Deployment context
+Single-tenant. One operator working from several machines, plus agent identities
+that contribute code to individual repositories. The server runs as a pod;
+out-of-band recovery is `kubectl exec`, and does not depend on the service being
+governed. The web UI is internet-facing.
+## Threat model
+The adversary is **a compromised agent credential**. It can open an SSH
+connection and push. It must not be able to:
+- move any repository's canonical state,
+- widen its own access,
+- reach a repository it was not granted,
+- create repositories.
+Governance is deliberately **readable** by anyone who can read the repository it
+governs. Hiding it would require excluding a ref from the fetch advertisement,
+and a contributor is entitled to know the rules it is subject to.
+An adversary with write access to the storage directory is out of scope, because
+the SSH host private key already lives there (`main.rs:38`,
+`<repos_dir>/.server/host_key`). Anyone who can reach that directory can
+impersonate the server outright. If the host key moves out of `repos_dir`, revisit
+this — the internet-facing HTTP server runs in the same process and uid
+(`main.rs:87-102`), so it is the shortest path to that directory.
+## Governing invariant
+**Governance lives on refs its subject cannot write.**
+A policy tracked in the working tree of the repository it governs fails this —
+write access would become admin access. A policy on a ref that ordinary pushes
+cannot touch satisfies it, and keeps governance in the same repository as the
+thing governed, so there is no second repository to clone and no state to keep in
+sync.
+Satisfying the invariant requires the server to authorize **individual ref
+updates**.
+## Model
+### Ref classes
+Every push falls into exactly one class, and the class determines who may make
+it. This replaces per-principal write flags entirely.
+| Class | Refs | Who may write |
+|---|---|---|
+| Canonical | `refs/heads/*`, `refs/tags/*` | Delegates |
+| Governance | `refs/collab/policy` | Delegates, threshold-signed |
+| Collaboration | `refs/collab/issues/*`, `refs/collab/patches/*`, `refs/collab/archive/*` | Any reader |
+| Contribution | `refs/for/<branch>` (virtual) | Any reader |
+An unclassified ref is denied. `refs/collab/archive/*` is in the collaboration
+class because `sync` pushes it (`sync.rs:226-243`) and `patch merge` writes to it
+(`patch.rs:696`); omitting it would break both for every non-delegate.
+A contributor never needs write access to a branch. A compromised agent
+credential cannot move canonical state in any repository — there is no setting
+that grants it.
+### Contribution via `refs/for`
+`refs/for/<branch>` is virtual: no such ref exists in storage. A push to it is
+converted server-side into a patch, or a new revision of the contributor's
+existing patch for that branch. The refname names only the target branch, so a
+contributor needs no local state beyond a remote.
+The revision model, interdiff (`patch.rs:501`) and revision-anchored inline
+comments (`state.rs:193`) already exist; this adds the push-side entry point.
+Note that plain thread comments carry no revision (`state.rs:77`) — only inline
+comments and reviews do.
+### Delegates
+A repository's policy names its delegates and the threshold of delegate
+signatures required to amend it. A repository begins with one delegate, its
+creator, and a single-delegate amendment is self-accepting, so ordinary
+single-operator use involves no review step.
+### Identity
+One namespace throughout: SSH key fingerprints, the string `ssh-keygen -lf`
+prints, prefixed with `key:`. The same string appears in every list.
+## Policy document
+`refs/collab/policy` carries a single TOML document.
+```toml
+delegates = ["key:SHA256:Gzb/mmBlyDmoWq3hMyPjb3SRWklPJ/yDAoD1K+ATvJA"]
+threshold = 1
+visibility = "public"          # omitted ⇒ private
+description = "build tooling"
+[ui]
+anonymous = true               # omitted ⇒ false; browse the web UI
+[http]
+anonymous_clone = true         # omitted ⇒ false; clone and download releases
+[access]
+read = ["key:SHA256:…agent"]   # omitted ⇒ empty; "*" means any authenticated principal
+```
+Every default is the closed value; an absent field denies. `RepoPolicy`'s current
+serde defaults are the opposite (`repos.rs:129` returns `["*"]`, `repos.rs:125`
+returns `Public`), so the governance policy type defines its own closed defaults
+rather than deriving them.
+`access.read` is the only per-principal list, and governs authenticated access.
+`visibility`, `ui.anonymous` and `http.anonymous_clone` govern the anonymous HTTP
+surface, where no principal exists — they are a separate axis, not a shorthand
+for `access.read`.
+A policy push is authorized against the **previous** revision's `delegates` and
+`threshold`, never its own, so a policy cannot authorize itself. Signatures are
+carried as commit signatures on the policy ref.
+## Enforcement
+Authorization happens at two points, because the server learns the repository and
+the verb at one moment and the refs being written at a later one.
+### At dispatch, once
+Immediately after the requested path is resolved and before the command is
+dispatched (`session.rs:506`), so every exec verb inherits it — `git-upload-pack`,
+`git-receive-pack`, and each `collab-release` subcommand, including verbs added
+later.
+| Operation | Rule |
+|---|---|
+| Open SSH connection | Principal is a recognized identity (see Q1) |
+| Clone / fetch | Delegate, or in `access.read`, or public and anonymous |
+| Any push | May read the repository — ref classes are checked later |
+| Release upload / delete | Delegate |
+| Release list | May read the repository |
+| Create a repository | See Q2 |
+Release *download* has no SSH verb; it is an HTTP route
+(`http/repo/releases.rs:72`) gated by `http.anonymous_clone`. The releases listing
+page is gated by `ui.anonymous` — two different knobs on one page, retained
+deliberately so a repository can publish artifacts without publishing a browsable
+UI.
+### At receive, per ref
+A server-managed `pre-receive` hook applies the ref-class table. It receives the
+authenticated principal in its environment. Today `run_git_command`
+(`session.rs:708`) spawns `git-receive-pack` with the server's inherited
+environment and nothing per-request, so the principal plumbing is new, as is hook
+installation — there are no hooks anywhere in the tree.
+Two adjacent changes are required for a hook to work at all: the child's stderr
+is currently piped and never read (`session.rs:711-716`), so a hook's rejection
+text is discarded and a chatty hook can fill the pipe buffer and wedge the child.
+### Refusal behaviour
+Dispatch-time refusals — unknown repository, unreadable repository — return an
+identical `repository not found` reply and exit status, so a scoped credential
+cannot map what else exists.
+Ref-class refusals are necessarily distinguishable: by the time a hook runs, the
+ref advertisement has already disclosed the repository's refs, and the rejection
+surfaces as a per-ref status line. This is acceptable because the principal has
+already passed the read check for that repository — it learns nothing it was not
+entitled to.
+### Repository lookup key
+The key is the resolved path relative to the storage directory with one trailing
+`.git` removed, `/` separators preserved, matched byte-exactly. Nested paths are
+keys in full: `private/tools.git` and `tools.git` are distinct repositories with
+distinct policies.
+Path resolution already accepts nested paths (`session.rs:967`), but `discover`
+is non-recursive (`repos.rs:217`) and HTTP resolves by final component
+(`repos.rs:241`), so nested repositories are currently unreachable over HTTP and
+`tools.git` and `tools` in the same directory already collide there. Nested keys
+therefore require reworking HTTP resolution and the URL scheme, not only the SSH
+path.
+### Limits
+Release storage is capped per repository in aggregate as well as per file. Only
+the per-file cap exists today (`releases.rs:123`, one global `max_release_size`);
+without an aggregate cap, filling the storage volume is a reachable way to force
+the IO-error path in Failure modes.
+## Bootstrap
+The server reads its storage location and listener addresses before it can read
+any git object, so these become startup flags: `--repos-dir`, `--http-bind`,
+`--ssh-bind`. They are config-file fields today (`config.rs:7-18`); the existing
+`--config` flag and the file itself are removed.
+Of the remaining `server.toml` fields, `site_title` and `max_release_size` become
+git objects. `authorized_keys` holds a *path* to an OpenSSH-format file read on
+every auth attempt (`session.rs:417`); whether that file survives at all depends
+on Q1, and moving it into a git object also replaces the per-attempt reload.
+Server-level authority, if it exists (Q2), is rooted at a pinned genesis commit
+passed as `--genesis <oid>`. The admin chain is a ref whose each revision must be
+signed by a threshold of the previous revision's admins; the pinned genesis
+distinguishes the operator's chain from one an attacker substitutes. Key
+rotation, adding a machine, and removing a compromised credential are signed
+commits on that chain, and the out-of-band residue is one hash.
+## Failure modes
+| Condition | Behaviour |
+|---|---|
+| Policy ref absent | Delegates only |
+| Object read fails (IO) | Last known good, bounded; then closed |
+| Document malformed | Deny that repository |
+The stale window is bounded by both elapsed time and consecutive failures;
+exceeding either closes the repository. Unbounded staleness would leave a
+superseded policy in force after a revocation lands, with no visible symptom.
+Both bounds need values before implementation.
+Classification is by `git2::ErrorCode`, not by inspecting messages: a `NotFound`
+on the ref or blob is an authoritative absence and closes; only a genuine IO
+error is eligible for the stale path.
+Server-level authority, where it exists, is evaluated before any repository
+policy is read and is unaffected by all of the above.
+## Testing
+Behavioural, through the existing server harness. The harness supports one
+repository and one client key at a fixed path, truncates its authorized-keys file
+on generation (`tests/common/mod.rs:704`), and asserts success on every git
+invocation (`:558`), so multiple repositories, multiple principals, a bare-repo
+commit helper and a non-panicking push wrapper are prerequisites.
+- A contributor pushes `refs/for/main`; a patch revision appears.
+- The same credential pushing `refs/heads/main` is refused.
+- The same credential pushing `refs/collab/policy` is refused.
+- The same credential pushing `refs/collab/issues/*` and `refs/collab/archive/*`
+  succeeds, and a full `git-collab sync` completes.
+- A delegate pushes `refs/heads/main` and `refs/collab/policy` successfully.
+- A policy push signed by a key named only in the *new* revision's delegates is
+  refused.
+- A repository naming neither `access.read` nor the principal is invisible:
+  clone, release download and every HTTP route refuse identically.
+- A policy document parsed from the empty string denies everything.
+- `private/tools.git` and `tools.git` resolve to distinct policies.
+- A malformed policy denies that repository.
+- A policy push takes effect on the next request, with no restart.
+- A rejected ref-class push surfaces the hook's message to the client.
+## Open questions
+**Q1 · Enrolled keys or certificates.**
+*Enrolled keys*: a git-controlled key set; revocation is a commit; credentials do
+not expire. *Certificates*: a CA public key pinned at startup; credentials expire
+without a revocation commit, which suits short-lived agents; no roster to store.
+`russh` verifies a certificate before dispatching to the handler
+(`server/encrypted.rs:788-810`), but dispatch is either/or — the current handler
+implements only `auth_publickey` (`session.rs:411`), so certificates are rejected
+by the default implementation until `auth_openssh_certificate` is implemented, and
+pinning the CA is the handler's job since `verify_signature` only proves the
+certificate is self-consistent. Decides whether a key set exists to be stored.
+**Q2 · Whether server-level authority exists.**
+It is needed only because repository creation consumes a shared namespace: two
+principals cannot both create `tools.git`. *Keep it*: a genesis-rooted admin chain
+on a ref in one otherwise-empty repository. *Drop it*: namespace repositories by
+key, so creation never collides and nothing central is required, at the cost of
+longer paths and changes to path resolution, HTTP resolution and the URL scheme.
+Decides whether anything central survives, and interacts with the lookup key
+above.
+Q1 constrains Q2: with certificates and no key set, the admin chain is the only
+remaining reason for a central repository.
+**Q3 · Where `refs/for` conversion lives.**
+A `pre-receive` hook can accept or reject a ref update; it cannot rewrite a
+virtual ref into a patch. Converting the push requires code that owns the received
+objects — either a hook that writes the patch DAG itself and then rejects the
+virtual ref, or a receive-pack wrapper. This is unassigned and is the largest
+unknown in the design.
+## Out of scope
+- Multi-tenant delegation and repository handover.
+- Web UI authentication. HTTP remains anonymous and read-only (`http/mod.rs:19-59`);
+  all writes are over SSH.
+- Signature verification of anything other than the policy ref and the admin chain.