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.mdindex 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 bewritten 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 denieddiff --git a/doc/graft/LIMITATIONS.md b/doc/graft/LIMITATIONS.mdindex 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/`, whateverthe 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` symbolicreference, 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.goindex 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()