Git designed for AI agents.
Merge commit 'ff87d5e' into c1-conflicts
Federico Elia4f0cfd60cc6c
diff --cc doc/graft/AGENT-SECURITY.mdindex b12cb8f,65135aa..fbea000--- a/doc/graft/AGENT-SECURITY.md+++ b/doc/graft/AGENT-SECURITY.md@@@ -57,91 -62,9 +62,92 @@@ These can never be enabled, not even th- `RemoteService` `UpdateRemoteMirror`, `FindRemoteRepository` and`FindRemoteRootRef`, which push to or query a URL the caller chooses.- `CleanupService`, `ObjectPoolService`, `HookService`, `InternalGitaly`,- `PartitionService`.+ `PartitionService`, and `StorageCoreService` (imports, checkpoints and+ garbage collection, which deletes packs of the bucket).+An agent does not see `refs/graft/` at all (`internal/graft/agentrefs`): the+agent guard refuses a request whose revision, reference or pattern names a+reference under it (including the short forms `graft/proposals/...` and+`graft/green/...`, which git completes to the server's namespaces; other+`graft/...` short names, such as the workspace's temporary branches, are+branches), and removes such references from every response; git upload-pack and+receive-pack hide the prefix from agents. Git's pseudo references reach every+reference without naming one, so every git command of an agent that walks them+(`rev-list`, `log`, `show`, `rev-parse`, `bundle`, `fast-export`,+`format-patch`) gets `--exclude-hidden=uploadpack` before each `--all` and+`--glob`, in its arguments and on its stdin, with `uploadpack.hideRefs` set to+`refs/graft/`: `--all` and `--glob=refs/*` in `ListCommits` or `ListBlobs`,+`FindCommits` with `all`, or any other RPC or field that asks for such a walk,+leave the namespace out (`internal/git/gitcmd/agent_walk.go`). `--alternate-refs`+walks the references of the object pool, which mirrors the member's references,+`refs/graft/` included: for an agent it walks only the pool's branches and tags+(`core.alternateRefsPrefixes`). A test classifies,+by message and field, every string, bytes, bool and enum field of every RPC+agents may call by default, so a new field cannot escape the filter; RPCs added+with `graft.agent_rpcs` are checked by field name. Other callers still see+graft-verify's green references, which are documented for consumers.++Revisions reach git one per line on its standard input, so the line is what git+reads, not what the request said. Four layers keep that from being a way past+the hiding:++1. **Input validation (every caller).** A revision with an ASCII control+ character (below space, or DEL) is refused with `InvalidArgument`, the+ pseudo-revisions `--glob=`, `--branches=` and `--tags=` and their patterns+ included, and so is a line feed or carriage return in the path of a+ path-scoped revision (`rev:path`). Before this, those patterns took any bytes,+ and `--glob=x` followed by a line feed and `refs/graft/green/main` was a+ second revision, naming a hidden reference that the request check had read as+ part of the pattern. Compatibility: this applies to other callers too. A+ control character in a revision never named a reference (`git+ check-ref-format` forbids them), and a line break in the path of+ `ListBlobs` or `ListLFSPointers` could not be read by `git rev-list --stdin`+ as a path anyway. The three RPCs whose revisions git reads NUL-delimited+ (`git cat-file -Z`: `CheckObjectsExist`, `DiffBlobs`, `CheckBlobsGenerated`) keep+ accepting a line break in a path (`AllowLineBreaksInPath`), as their tests+ require. A path with a tab, a space or other special characters is allowed+ everywhere.+2. **The sinks.** Every writer of revisions into a newline-delimited git stdin+ (`git rev-list --stdin`) refuses a revision with a line feed, a carriage+ return or a NUL, whatever its caller validated, through+ `git.ValidateStdinRevision`. Today there are three: `gitpipe.Revlist` (ListCommits,+ ListBlobs, ListLFSPointers, GetTagSignatures and the other revision walks),+ `ObjectsSize`, and `CreateBundleFromRefList`, whose patterns go to+ `git bundle create --stdin`. A test (`internal/git/stdin_writers_test.go`)+ parses the code and lists every file that gives a git command a flag that+ makes it read its stdin (`--stdin`, `--revs`, `--batch` and the flags that+ begin with them) by how it is safe: a request's revisions through the helper+ (the test finds the call in the syntax tree, not a word in a comment);+ NUL-delimited (`-z`, `-Z`); or input the server builds from object IDs (a+ request's revisions are resolved to object IDs first), packs, content or+ paths of its own. It fails on a writer it does not know, so a new one is+ classified when it is added.+3. **The filter reads lines as git does.** The `--exclude-hidden` flag is put+ before a line that git reads as `--all` or `--glob=...`: without its line+ feed and the carriage return before it, and cut at the first NUL.+4. **The request check splits at the same separators.** `RevisionHidden` also+ splits at line feed, carriage return, tab and NUL.++What the hiding covers, and what it does not: it covers the reference **names**+under `refs/graft/` and the reachability that goes through them. An agent can+neither address those references nor walk to their objects through them, so it+can neither depend on a proposal reference nor learn of one from a listing. It+does **not** make the objects secret. A proposal's commits and blobs are+ordinary objects of the repository: `ListAllBlobs` and `ListAllLFSPointers`+enumerate every blob, `GetObjects` reads any object by its ID, and an agent with+access to the repository can read their content, a proposal's message included. The goal is+that agents can neither address nor depend on `refs/graft/`, not object+confidentiality; anything that must stay secret from an agent must not be+written into a repository the agent can read.++Whatever the RPC and whatever the policy says, an agent never creates,+updates or deletes a reference under `refs/graft/`: the reference-transaction+hook refuses it, so a push, `UpdateReferences`, `DeleteRefs`, `WriteRef` or an+operation RPC that would do so fails. The namespace is the server's: the+proposals of a land (`refs/graft/proposals/`, hidden from advertisement and+push, written by the server) and graft-verify's green references (written with+the shared token).+Every other RPC that is not on the allowlist (for example the other`OperationService` RPCs such as `UserMergeBranch`, or `SSHService`) is deniedby default and can be enabled with `graft.agent_rpcs`.