Skip to content

Git designed for AI agents.

Merge commit 'ff87d5e' into c1-conflicts

Federico Elia4f0cfd60cc6c
diff --cc doc/graft/AGENT-SECURITY.md
index 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 denied
by default and can be enabled with `graft.agent_rpcs`.