Skip to content

Git designed for AI agents.

docs, e2e: where refs/graft/ is enforced for agents

Federico Eliafc80a9e03cd3
diff --git a/doc/graft/AGENT-SECURITY.md b/doc/graft/AGENT-SECURITY.md
index 222fab5..c288521 100644
--- a/doc/graft/AGENT-SECURITY.md
+++ b/doc/graft/AGENT-SECURITY.md
@@ -141,12 +141,28 @@ 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).
+updates or deletes a reference under `refs/graft/`. 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). Three layers enforce it, in the
+order a write meets them:
+
+1. A push (when an operator opens `SSHReceivePack` or the HTTP push to agents):
+ `git-receive-pack` runs with `receive.hideRefs=refs/graft/` for agents, so
+ git refuses the update ("deny updating a hidden ref") before any hook.
+2. The RPCs that update references without the pre-receive hook
+ (`UserMergeToRef`, `UserRebaseToRef` when opened with `agent_rpcs`) check the
+ reservation with the policy before they write (`CheckAgentPolicy`), and
+ answer `PermissionDenied`. The other agent RPCs write only `refs/heads/`.
+ `UpdateReferences`, `DeleteRefs` and `WriteRef` are never open to agents.
+3. The reference-transaction hook refuses every agent update under
+ `refs/graft/` while the references are locked, whatever reached it.
+
+`TestPolicyHoldsOnAgentPushes` in `internal/graft/e2e` pins the first layer on a
+real push, and `TestPolicyHookDecidesForAgentUpdates` the third one alone (the
+real hook, run by `git update-ref` with the payload of an agent's write). The
+pre-receive hook judges the policy only; it does not check the reservation,
+because no agent write reaches it with a `refs/graft/` update.
Every other RPC that is not on the allowlist (for example the other
`OperationService` RPCs such as `UserMergeBranch`, or `SSHService`) is denied
diff --git a/doc/graft/LIMITATIONS.md b/doc/graft/LIMITATIONS.md
index b8af125..580f09f 100644
--- a/doc/graft/LIMITATIONS.md
+++ b/doc/graft/LIMITATIONS.md
@@ -62,7 +62,10 @@ reference-transaction hook.
Agents never create, update or delete a reference under `refs/graft/`, whatever
the policy says: that namespace is the server's (land proposals, graft-verify's
-references), and the reference-transaction hook refuses it.
+references). A push of it is refused by `git-receive-pack`, which hides the
+namespace from agents; `UserMergeToRef` and `UserRebaseToRef` refuse it before
+they write; and the reference-transaction hook refuses it as the last layer.
+See [AGENT-SECURITY](AGENT-SECURITY.md).
The policy governs the references under `refs/` and the `HEAD` symbolic
reference, so an agent cannot repoint `HEAD` to get around a protected branch.
diff --git a/internal/graft/e2e/policy_test.go b/internal/graft/e2e/policy_test.go
index 8756020..6570866 100644
--- a/internal/graft/e2e/policy_test.go
+++ b/internal/graft/e2e/policy_test.go
@@ -20,6 +20,12 @@ import (
// policy checks. A denied land names the policy rule, without a GitLab prefix,
// and the planner may move main with UserLand. No changeset on main may name
// the builder. Covers WP1, WP2 and WP15.
+//
+// The layers it reaches: WriteRef, DeleteRefs and RemoveRepository stop at the
+// agent allowlist, and the land stops at the pre-receive hook. It does not reach
+// the reference-transaction hook: TestPolicyHoldsOnAgentPushes covers the push
+// path (receive.hideRefs, then the pre-receive hook), and
+// TestPolicyHookDecidesForAgentUpdates the reference-transaction hook alone.
func TestPolicyHoldsForEveryReferenceUpdate(t *testing.T) {
t.Parallel()