diff --git a/.claude/settings.json b/.claude/settings.json index 3e7810321..816ffb418 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -8,9 +8,11 @@ "excludedCommands": [ "uv run --project ~/.claude/magpie/vetted-ops vetted-op-read *", "uv run --project ~/.claude/magpie/vetted-ops vetted-op-tracker *", + "uv run --project ~/.claude/magpie/vetted-ops vetted-op-git *", "uv run --project ~/.claude/magpie/vetted-ops vetted-op *", "uvx --from ~/.claude/magpie/vetted-ops vetted-op-read *", "uvx --from ~/.claude/magpie/vetted-ops vetted-op-tracker *", + "uvx --from ~/.claude/magpie/vetted-ops vetted-op-git *", "uvx --from ~/.claude/magpie/vetted-ops vetted-op *" ], "filesystem": { @@ -135,6 +137,8 @@ "Bash(uv run --project ~/.claude/magpie/vetted-ops vetted-op-tracker *)", "Bash(uvx --from ~/.claude/magpie/vetted-ops vetted-op-tracker *)", "Bash(uvx --from ~/.claude/magpie/security-tools/cve-tool cve-tool *)", + "Bash(uv run --project ~/.claude/magpie/vetted-ops vetted-op-git *)", + "Bash(uvx --from ~/.claude/magpie/vetted-ops vetted-op-git *)", "Bash(uv run --project ~/.claude/magpie/vetted-ops vetted-op *)", "Bash(uvx --from ~/.claude/magpie/vetted-ops vetted-op *)", "Bash(gh api -X*)", diff --git a/docs/setup/secure-agent-setup.md b/docs/setup/secure-agent-setup.md index b2591470f..66e055b05 100644 --- a/docs/setup/secure-agent-setup.md +++ b/docs/setup/secure-agent-setup.md @@ -525,6 +525,10 @@ The full block below is the two merged, annotated. // bodies read only from the workspace, so the exclusion exposes less than // the bare `gh *` above. Both keep their `ask` below, never `allow`: the // prompt is the gate on every write (sandbox-lint enforces the pairing). + // `vetted-op-git` is excluded because what it does cannot happen inside: + // an SSH push gets no TCP through the sandbox's proxy, and a linked + // worktree's administrative directory is read-only there. It keeps its + // `ask` too (see "Git operations the sandbox blocks" below). // The adversarial-review tool runs the reviewer CLIs, which need network // and their own credentials. Like the vetted-ops entries, it names the // fixed link its plugin's SessionStart hook maintains, never a `*` where @@ -542,6 +546,8 @@ The full block below is the two merged, annotated. "uvx --from ~/.claude/magpie/vetted-ops vetted-op-read *", "uv run --project ~/.claude/magpie/vetted-ops vetted-op-tracker *", "uvx --from ~/.claude/magpie/vetted-ops vetted-op-tracker *", + "uv run --project ~/.claude/magpie/vetted-ops vetted-op-git *", + "uvx --from ~/.claude/magpie/vetted-ops vetted-op-git *", "uv run --project ~/.claude/magpie/vetted-ops vetted-op *", "uvx --from ~/.claude/magpie/vetted-ops vetted-op *", "uvx --from ~/.claude/magpie/adversarial-review adversarial-review *", @@ -776,6 +782,8 @@ The full block below is the two merged, annotated. "Bash(uv run --project ~/.claude/magpie/vetted-ops vetted-op-tracker *)", // the tracker rollup / body-field procedures: excluded from the sandbox above, so never `allow` "Bash(uvx --from ~/.claude/magpie/vetted-ops vetted-op-tracker *)", "Bash(uvx --from ~/.claude/magpie/security-tools/cve-tool cve-tool *)", // cve-tool: excluded from the sandbox above, and it changes CVE records, so every call asks + "Bash(uv run --project ~/.claude/magpie/vetted-ops vetted-op-git *)", // push / worktree moves outside the sandbox: never `allow` + "Bash(uvx --from ~/.claude/magpie/vetted-ops vetted-op-git *)", // gh WRITE subcommands, listed one by one. Claude Code evaluates deny, // then ask, then allow, and "a matching ask rule prompts even when a // more specific allow rule also matches the same call" — so a catch-all @@ -964,7 +972,10 @@ If even the read-widening matters for your threat model, keep the policy in a path the sandbox does not grant write to and point `vetted-op-read --config` at it. -`vetted-op-tracker` and `vetted-op` are the write-capable entry points excluded from the sandbox. +`vetted-op-tracker`, `vetted-op-git` and `vetted-op` are the write-capable entry points excluded from the sandbox. +`vetted-op-git` runs four git operations a sandboxed agent cannot (see +[vetted-ops → Git operations the sandbox blocks](../../tools/vetted-ops/README.md#git-operations-the-sandbox-blocks)), +each bounded by the approved policy's `[git]` table. `vetted-op-tracker` refuses every operation except the tracker rollup / body-field procedures before it reads the policy, and their runner refuses any `gh` call outside `repos//`. `vetted-op` runs the whole write catalogue, but each operation is a fixed `gh` argv with no shell, @@ -1032,7 +1043,7 @@ Codex is the exception that proves the rule: its execpolicy cannot match `~`, so They are what makes an unprompted read safe to allow: the `allow` rests on the catalogue's shape, so the agent that calls the dispatcher must not be able to edit it. A missing rule is a must-fix. -5. `sandbox.excludedCommands` keeps the `vetted-op-read`, `vetted-op-tracker` and `vetted-op` exclusions in both `~` launcher forms, as in [the framework's own settings](#the-frameworks-own-claudesettingsjson). +5. `sandbox.excludedCommands` keeps the `vetted-op-read`, `vetted-op-tracker`, `vetted-op-git` and `vetted-op` exclusions in both `~` launcher forms, as in [the framework's own settings](#the-frameworks-own-claudesettingsjson). Without them, an allowed call runs inside the sandbox, where its `gh` cannot verify TLS: a silent failure again. 6. The agent-guard plugin is installed, so the `vetted-ops-spelling` guard turns an expanded spelling into a refusal instead of a sandboxed call that fails silently. @@ -1042,7 +1053,7 @@ Codex is the exception that proves the rule: its execpolicy cannot match `~`, so "excludedCommands": [ "uvx --from ~/.claude/magpie/vetted-ops vetted-op-read *", "uv run --project ~/.claude/magpie/vetted-ops vetted-op-read *" - // ...plus the two vetted-op-tracker and two vetted-op entries + // ...plus the two vetted-op-tracker, two vetted-op-git and two vetted-op entries ] }, "permissions": { @@ -4033,7 +4044,7 @@ never delete it: is ✗ and worth stopping for: it grants every operation in the catalogue, because the operation's caller name is chosen by whoever runs the command. - - `vetted-op-tracker` and `vetted-op` are each in `ask` and in + - `vetted-op-tracker`, `vetted-op-git` and `vetted-op` are each in `ask` and in `sandbox.excludedCommands` (both forms), never in `allow`; an exclusion without its `ask` is ✗ (the prompt is the only gate on an unsandboxed write). diff --git a/plugins/magpie-agent-guard/tools/agent-guard/src/agent_guard/__init__.py b/plugins/magpie-agent-guard/tools/agent-guard/src/agent_guard/__init__.py index a6537d126..1d6925ee2 100644 --- a/plugins/magpie-agent-guard/tools/agent-guard/src/agent_guard/__init__.py +++ b/plugins/magpie-agent-guard/tools/agent-guard/src/agent_guard/__init__.py @@ -2063,6 +2063,7 @@ def guard_empty_rebase(seg: Segment, cwd: str | None) -> str | None: "vetted-op": "vetted-ops", "vetted-op-read": "vetted-ops", "vetted-op-tracker": "vetted-ops", + "vetted-op-git": "vetted-ops", "adversarial-review": "adversarial-review", } VETTED_STABLE_BASE = "~/.claude/magpie/" diff --git a/plugins/magpie-setup/skills/setup/setup_preflight/isolated_fingerprint.py b/plugins/magpie-setup/skills/setup/setup_preflight/isolated_fingerprint.py index 2ea344ed9..9dcb2a0e9 100644 --- a/plugins/magpie-setup/skills/setup/setup_preflight/isolated_fingerprint.py +++ b/plugins/magpie-setup/skills/setup/setup_preflight/isolated_fingerprint.py @@ -21,4 +21,4 @@ for installs that do not carry the framework source (see `isolated.py`). """ -FRAMEWORK_FINGERPRINT = "sha256:5ef56166ec29b5d7" +FRAMEWORK_FINGERPRINT = "sha256:2b2d856e6cb8f098" diff --git a/plugins/magpie-vetted-ops/tools/vetted-ops/README.md b/plugins/magpie-vetted-ops/tools/vetted-ops/README.md index a1fe276e2..a1f41af66 100644 --- a/plugins/magpie-vetted-ops/tools/vetted-ops/README.md +++ b/plugins/magpie-vetted-ops/tools/vetted-ops/README.md @@ -21,6 +21,7 @@ - [The pr-management-stats reads](#the-pr-management-stats-reads) - [Tracker procedures: rollup and body-field writes](#tracker-procedures-rollup-and-body-field-writes) - [Tracker backends](#tracker-backends) + - [Git operations the sandbox blocks](#git-operations-the-sandbox-blocks) - [Wiring it into settings](#wiring-it-into-settings) - [Codex native rules](#codex-native-rules) - [Tests](#tests) @@ -151,6 +152,7 @@ scripts over one catalogue: |---|---|---| | `vetted-op-read` | never — refused before policy is consulted | `allow` | | `vetted-op-tracker` | only the [tracker procedures](#tracker-procedures-rollup-and-body-field-writes) — everything else refused before policy is consulted | `ask`, and excluded from the sandbox | +| `vetted-op-git` | only the [git operations](#git-operations-the-sandbox-blocks) — no `gh` operation exists there | `ask`, and excluded from the sandbox | | `vetted-op` | yes, subject to policy | `ask` (or unlisted) | That split is what lets the read path lose its prompts without the write path @@ -766,6 +768,109 @@ On a non-GitHub tracker the `number` parameter of a tracker operation takes the backend's own IDs (`SEC-0012`, `FOOSEC-12`, `2024-007-xss`): letters, digits, `-` and `_` only, so an ID can never name a path. +## Git operations the sandbox blocks + +Three git steps fail in a sandboxed session however the agent phrases them, and +used to end in a command the user pasted into their own terminal: + +- **Pushing over SSH.** The sandbox routes network through an HTTP proxy, so an + SSH transport gets no TCP at all, and a hardware key's touch prompt never + reaches the user. +- **Moving a linked worktree** to a rebased or pushed commit. Harnesses keep + `.git/worktrees//` read-only for worktrees the session did not create, + so `git reset`, `git fetch` and `git rebase` in such a worktree stop half-way. +- **Adding or removing a linked worktree**, for the same reason. + +`vetted-op-git` runs exactly those four steps outside the sandbox, as closed +shapes, behind the harness's confirmation like `vetted-op`: + +| Operation | Parameters | What it does | +|---|---|---| +| `git-push-branch` | `checkout branch target remote_branch expected` | Pushes local `branch`'s commit to `remote_branch` of the policy's `fork` or `upstream` repository, with `--force-with-lease=refs/heads/:` and `--no-verify`. `expected` is the remote branch's current full SHA, or `new`. Run the pre-push checks in the sandbox first. | +| `git-worktree-sync` | `worktree commit` | Moves a clean linked worktree's branch to `commit` with `git reset --keep`, and prints the commit it was on. | +| `git-worktree-add` | `checkout path branch start` | Creates a linked worktree at `path`, directly inside a `worktree_roots` directory, on a new `branch` at `start`. | +| `git-worktree-remove` | `worktree` | Removes a linked worktree that has no changes (never `--force`). | + +```bash +uvx --from ~/.claude/magpie/vetted-ops vetted-op-git --caller git-push-branch \ + ~/code/project fix-thing fork fix-thing 0123…(40 hex) +``` + +The policy's `[git]` table bounds them: + +```toml +[git] +# Main checkouts the operations may act on; their linked worktrees count too. +checkouts = ["~/code/project"] +# Pushed over git@:.git (transport = "https" for https:///.git). +fork = "alice/project" +# Branches a push may create or move on [repos] upstream. Empty or absent: never. +upstream_push = ["ci-*", "stack/*"] +# Added to the built-in list (main, master, trunk, develop, gh-pages, release*, v*-test, v*-stable, *-stable, asf-site). +protected = ["prod"] +# Directories new worktrees may be created in, directly. +worktree_roots = ["~/code/project/files"] +``` + +What makes running git unsandboxed acceptable here: + +- **Closed destinations.** A push goes to a URL built from the policy's + repository names, never to a remote the repository configures. Protected + branches are refused whatever the policy says, and upstream takes only + branches matching `upstream_push`. +- **Nothing lost silently.** Every push carries a lease on the full SHA the + caller expects (`new` for a branch that must not exist yet), so a branch + someone else moved is never overwritten, and moving a branch to a commit with + nothing over a remote's default branch (an emptied rebase, which would close + the pull request it heads) is refused, as agent-guard's `empty-rebase` guard + refuses the plain `git push`. A worktree moves only when it has + no local changes, and the previous commit is printed and stays in the reflog. +- **No repository configuration steers git.** Keys such as `core.sshCommand`, + `url.*.insteadOf`, `filter.*`, `core.fsmonitor`, `core.hooksPath` or + `include.path` can be planted in a repository's own config; the operation + refuses to run while the local or worktree config holds any key outside a + short list of inert ones (remotes, branch tracking, `user.name`, …). Global + and system configuration are the user's own and stay in effect, so an SSH + wrapper or touch overlay configured there keeps working. The check covers + every working tree the operation runs git in, and runs again right before + the command that acts. +- **Pinned on every call**, so a key added between that check and the command + cannot take effect: no file-system monitor, no automatic gc or maintenance, + only `https` and `ssh` transports, `core.sshCommand` set to the user's global + value (or `ssh`), and hooks off wherever they are not wanted. Attributes are + read from the empty tree, so no `.gitattributes` can switch on a filter + (the cost: a worktree is checked out without LFS smudging or line-ending + conversion). A push sends the one ref, never tags (`--no-follow-tags`), and + `GIT_ALLOW_PROTOCOL` limits transports whatever the configuration says. +- **Directories are held, not named.** Each validated directory is opened + without following a symlink at any component, and git runs inside it by + descriptor, so a directory swapped for a symlink after the checks cannot + send git elsewhere. A new worktree is created through its root's descriptor + and added as `.`, so git names its administrative directory `-` (`-1`, …). + A URL rewrite (`url.*.insteadOf`) cannot be pinned away: that it cannot + appear while the confirmed command runs rests on the harness keeping + `.git/config` write-protected, as Claude Code's sandbox does. +- **No environment steers git.** Every `GIT_*` variable is dropped, `HOME` + comes from the password database and `XDG_CONFIG_HOME` is dropped, so the + global configuration git reads is the account's own. +- **Hooks never run.** No operation runs a hook: the worktree operations set + `core.hooksPath=/dev/null`, and a push also passes `--no-verify`. A + `pre-push` hook is code the agent can write (`.git/hooks/pre-push`, or a + hook manager reading its configuration from the working tree), and the + confirmation shows the push, not what the hook would execute, so running it + here would run agent-written code outside the sandbox. The push-time checks + still run: the caller runs them inside the sandbox first (for prek, + `prek run --hook-stage pre-push --from-ref --to-ref `), fixes + what they report, and only then pushes. +- **Unapproved policy, dry run.** `--dry-run` against a policy that is not an + approved copy checks the parameters and runs no git command; only an + approved policy prints the command it would run. + +Everything else git does in a sandboxed session stays there. Rewriting history +for a branch checked out in a worktree you did not create is done in a scratch +clone (`git clone --shared `), fetched back into the main +checkout, pushed with `git-push-branch` and applied with `git-worktree-sync`. + ## Wiring it into settings Replace the wildcard `ask` rules with one `allow` entry, and keep an `ask` on @@ -786,7 +891,9 @@ anything still invoked directly: "Bash(uv run --project ~/.claude/magpie/vetted-ops vetted-op *)", "Bash(uvx --from ~/.claude/magpie/vetted-ops vetted-op *)", "Bash(uv run --project ~/.claude/magpie/vetted-ops vetted-op-tracker *)", - "Bash(uvx --from ~/.claude/magpie/vetted-ops vetted-op-tracker *)" + "Bash(uvx --from ~/.claude/magpie/vetted-ops vetted-op-tracker *)", + "Bash(uv run --project ~/.claude/magpie/vetted-ops vetted-op-git *)", + "Bash(uvx --from ~/.claude/magpie/vetted-ops vetted-op-git *)" ], "deny": [ // `Edit(path)` is the path rule for every file-writing tool — Write and @@ -820,6 +927,8 @@ fails the same way: "uvx --from ~/.claude/magpie/vetted-ops vetted-op-read *", "uv run --project ~/.claude/magpie/vetted-ops vetted-op-tracker *", "uvx --from ~/.claude/magpie/vetted-ops vetted-op-tracker *", + "uv run --project ~/.claude/magpie/vetted-ops vetted-op-git *", + "uvx --from ~/.claude/magpie/vetted-ops vetted-op-git *", "uv run --project ~/.claude/magpie/vetted-ops vetted-op *", "uvx --from ~/.claude/magpie/vetted-ops vetted-op *" ] diff --git a/plugins/magpie-vetted-ops/tools/vetted-ops/pyproject.toml b/plugins/magpie-vetted-ops/tools/vetted-ops/pyproject.toml index 3ad293a6d..5381537db 100644 --- a/plugins/magpie-vetted-ops/tools/vetted-ops/pyproject.toml +++ b/plugins/magpie-vetted-ops/tools/vetted-ops/pyproject.toml @@ -32,6 +32,7 @@ dependencies = [] vetted-op = "vetted_ops:main" vetted-op-read = "vetted_ops:main_read" vetted-op-tracker = "vetted_ops:main_tracker" +vetted-op-git = "vetted_ops.git_ops:main" vetted-ops-codex-rules = "vetted_ops.codex:main" [tool.hatch.build.targets.wheel] diff --git a/plugins/magpie-vetted-ops/tools/vetted-ops/src/vetted_ops/codex.py b/plugins/magpie-vetted-ops/tools/vetted-ops/src/vetted_ops/codex.py index d8715924a..ec62f8bdd 100644 --- a/plugins/magpie-vetted-ops/tools/vetted-ops/src/vetted_ops/codex.py +++ b/plugins/magpie-vetted-ops/tools/vetted-ops/src/vetted_ops/codex.py @@ -46,7 +46,7 @@ def render_rules(tool_root: Path) -> str: "# Generated by vetted-ops-codex-rules; review before installing.", ] for launcher in (("uv", "run", "--project"), ("uvx", "--from")): - for entry in ("vetted-op-read", "vetted-op", "vetted-op-tracker"): + for entry in ("vetted-op-read", "vetted-op", "vetted-op-tracker", "vetted-op-git"): pattern = [*launcher, base, entry] decision = "allow" if entry == "vetted-op-read" else "prompt" lines.append(f"prefix_rule(pattern = {json.dumps(pattern)}, decision = {json.dumps(decision)})") diff --git a/plugins/magpie-vetted-ops/tools/vetted-ops/src/vetted_ops/config.py b/plugins/magpie-vetted-ops/tools/vetted-ops/src/vetted_ops/config.py index 366f38e72..3040b79a5 100644 --- a/plugins/magpie-vetted-ops/tools/vetted-ops/src/vetted_ops/config.py +++ b/plugins/magpie-vetted-ops/tools/vetted-ops/src/vetted_ops/config.py @@ -166,6 +166,8 @@ class Config: #: The non-GitHub security tracker, when ``[tracker] platform`` selects one. #: ``None`` means GitHub: tracker operations run their ``gh`` builders. tracker_backend: TrackerBackend | None = None + #: The raw ``[git]`` table, validated by `git_ops.git_policy` for `vetted-op-git`. + git: object = None def as_mapping(self) -> dict[str, object]: """The mapping handed to an operation's ``build`` callable.""" @@ -421,6 +423,7 @@ def load(path: Path | None = None, *, cwd: Path | None = None, approved_only: bo endpoints=endpoints, callers=callers, tracker_backend=_tracker_backend(raw.get("tracker")), + git=raw.get("git"), ) @@ -435,6 +438,7 @@ def describe(config: Config) -> str: "endpoints": dict(sorted(config.endpoints.items())), "callers": {k: sorted(v) for k, v in sorted(config.callers.items())}, "tracker_backend": (dict(vars(config.tracker_backend)) if config.tracker_backend else "github"), + "git": config.git, }, indent=2, sort_keys=True, diff --git a/plugins/magpie-vetted-ops/tools/vetted-ops/src/vetted_ops/git_ops.py b/plugins/magpie-vetted-ops/tools/vetted-ops/src/vetted_ops/git_ops.py new file mode 100644 index 000000000..77dd49d1b --- /dev/null +++ b/plugins/magpie-vetted-ops/tools/vetted-ops/src/vetted_ops/git_ops.py @@ -0,0 +1,918 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +""" +``vetted-op-git``: the git operations a sandboxed agent cannot run, as closed shapes. + +Three things a sandboxed session routinely cannot do, and used to hand to the +user as a command to paste: + +* **Push over SSH.** The sandbox routes network through an HTTP proxy, so an + SSH transport gets no TCP at all, and a hardware key's touch prompt cannot + reach the user from inside it. +* **Write a linked worktree's administrative directory.** Harnesses keep + ``.git/worktrees//`` read-only for worktrees the session did not + create, so moving such a worktree to a rebased commit fails half-way. +* **Add or remove a linked worktree**, for the same reason. + +Each operation here is one of those, with every parameter validated and every +target bounded by the approved policy's ``[git]`` table. The entry point runs +outside the sandbox and stays behind the harness's confirmation (``ask``), like +``vetted-op``: it removes the copy and paste, not the human decision. + +What makes running git outside the sandbox safe here, beyond the closed shapes: + +* **The pre-push checks run in the sandbox, not here.** A push never runs a + hook. Whatever a ``pre-push`` hook would run — ``.git/hooks/pre-push``, or a + hook manager reading its configuration from the working tree — is code the + agent can write, and running it here would run that code outside the + sandbox; the harness confirmation shows the push, not the code the hook + would execute. The caller runs the same checks inside the sandbox first + (for prek: ``prek run --hook-stage pre-push --from-ref --to-ref + ``), fixes what they report, and only then pushes. The checks still + run; they just run where working-tree code belongs. +* **No repository code runs.** Every operation switches hooks off + (``core.hooksPath=/dev/null``, plus ``--no-verify`` on the push), so neither + a ``pre-push`` nor a ``post-checkout`` hook can run code from the working + tree. +* **No repository configuration steers git.** A key that makes git run a + program, rewrite a URL, or pick credentials (``core.sshCommand``, + ``url.*.insteadOf``, ``filter.*``, ``core.fsmonitor``, ``include.path``, …) + can be planted in a repository's own config by anything that writes it. The + operation refuses to run when the local or worktree config holds any key + outside a short list of inert ones (`SAFE_LOCAL_KEY`). Global and system + configuration are the user's own and stay in effect, so an SSH wrapper or a + signing setup there keeps working. +* **No environment steers git.** Every ``GIT_*`` variable is dropped, and + ``HOME`` comes from the password database, so the global configuration read + is the account's own. +* **What is re-checked cannot change in between.** The configuration check + runs again right before the command that acts, and the keys that could start + a program in that window are pinned on the command line (`PINNED_CONFIG`, + ``core.sshCommand`` set to the user's global value, hooks off where they are + not wanted). Attributes come from the empty tree, so no ``.gitattributes`` + can switch on a filter. ``GIT_ALLOW_PROTOCOL`` limits transports whatever + the configuration says. Validated directories are opened without following + a symlink and git runs inside them by descriptor, so a directory swapped for + a symlink after the checks cannot redirect it. Git itself still finds a + repository's ``.git`` by name; its identity is re-checked, by name, right + before the acting command, and a linked worktree's validated git directory + is passed explicitly (``--git-dir``, ``--work-tree=.``) so its agent-writable + ``.git`` file is never read again. That the git directory cannot be swapped + in the moment between rests, like the next point, on the harness protecting + it. A rewrite + such as ``url.*.insteadOf`` cannot be + pinned away; that it cannot appear while the confirmed command runs rests on + the harness keeping ``.git/config`` write-protected, as Claude Code's sandbox + does. +* **The destination is not addressable.** A push goes to a URL built from the + policy's repository names, never to a remote the repository configures. + Protected branches are refused whatever the policy says, and the upstream + repository accepts only branches matching the policy's globs. +* **Nothing is lost silently.** A push always uses ``--force-with-lease`` with + the full SHA the caller expects the remote branch to have (or ``new``), and + a worktree moves with ``reset --keep`` only when it has no local changes; + the previous commit is printed and stays in the reflog. +""" + +from __future__ import annotations + +import argparse +import dataclasses +import fnmatch +import os +import re +import stat +import subprocess +import sys +from collections.abc import Callable, Sequence +from dataclasses import dataclass, field +from pathlib import Path + +from .config import Config, ConfigError, _expand_home, account_home, describe, load + +EXIT_OK = 0 +EXIT_USAGE = 2 +EXIT_POLICY = 3 +EXIT_COMMAND = 4 + +PROG = "vetted-op-git" + +#: A full object name. Short SHAs are refused: they can become ambiguous, and +#: the caller always has the full one from `git rev-parse` or the forge. +_SHA = re.compile(r"^(?:[0-9a-f]{40}|[0-9a-f]{64})$") +#: A branch name, before `git check-ref-format --branch` has its say. +_BRANCH = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._/+-]{0,199}$") +#: The last component of a new worktree's path. +_WORKTREE_NAME = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._+-]{0,99}$") +#: `owner/name`, as in `config._REPO`. +_REPO = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,100}/[A-Za-z0-9][A-Za-z0-9._-]{0,100}$") +_HOST = re.compile(r"^[A-Za-z0-9][A-Za-z0-9.-]{0,252}$") + +#: Branches no operation pushes to, whatever the policy adds or grants. +DEFAULT_PROTECTED = ( + "main", + "master", + "trunk", + "develop", + "gh-pages", + "release", + "release/*", + "release-*", + "v*-test", + "v*-stable", + "*-stable", + "asf-site", +) + +#: Repository-scope configuration keys that cannot make git run a program, +#: pick a credential, change a destination or transform file contents. Every +#: other key at `local` or `worktree` scope makes an operation refuse. +SAFE_LOCAL_KEY = re.compile( + r"""^(?: + core\.(?:repositoryformatversion|filemode|bare|logallrefupdates|ignorecase|precomposeunicode + |symlinks|autocrlf|eol|safecrlf|quotepath|abbrev|commitgraph|untrackedcache + |splitindex|multipackindex|sparsecheckout|sparsecheckoutcone|checkstat|trustctime) + | extensions\.(?:worktreeconfig|objectformat|refstorage|preciousobjects|partialclone|noop) + # A remote name without `:` or `/`: git applies the settings of a remote named exactly + # like the URL a push goes to, so a URL-shaped name could redirect it. + | remote\.[A-Za-z0-9._-]+\.(?:url|pushurl|fetch|tagopt|prune|prunetags|promisor|partialclonefilter + |mirror|skipdefaultupdate|skipfetchall|gh-resolved) + | branch\.[^\x00]+\.(?:remote|pushremote|merge|rebase|description|vscode-merge-base) + | user\.(?:name|email) + | (?:pull|fetch)\.(?:rebase|ff|prune|prunetags|parallel|writecommitgraph) + | push\.(?:default|autosetupremote|followtags) + | rerere\.(?:enabled|autoupdate) + | gc\.(?:auto|autopacklimit|autodetach|reflogexpire|reflogexpireunreachable|prunexpire|worktreepruneexpire) + | maintenance\.(?:auto|strategy|repo) + | index\.(?:version|threads|skiphash) + | feature\.(?:manyfiles|experimental) + | color\.[a-z.]+ + | advice\.[a-z]+ + | (?:commit|tag)\.gpgsign + | init\.defaultbranch + | merge\.conflictstyle + | diff\.(?:renames|algorithm|colormoved) + | log\.(?:date|decorate|follow) + | status\.(?:showuntrackedfiles|submodulesummary) + )$""", + re.VERBOSE, +) + + +class GitRefused(ValueError): + """A parameter or the repository state that the operation does not accept.""" + + +class GitFailed(RuntimeError): + """A git command that ran and failed.""" + + def __init__(self, argv: Sequence[str], returncode: int, stderr: str, stdout: str = "") -> None: + command = " ".join(a for a in argv if a != "-c" and "=" not in a) + super().__init__(f"{command} exited {returncode}") + self.returncode = returncode + self.stderr = stderr + #: A hook may explain its failure on stdout; it is shown with stderr. + self.stdout = stdout + + +@dataclass(frozen=True) +class GitPolicy: + """The validated ``[git]`` table of the policy.""" + + #: Main checkouts (their top-level directories) the operations may act on, + #: together with the linked worktrees that share their ``.git``. + checkouts: tuple[Path, ...] + upstream_repo: str + fork_repo: str | None = None + #: Globs of the branches a push may create or move on the upstream + #: repository. Empty: no push to upstream at all. + upstream_push: tuple[str, ...] = () + protected: tuple[str, ...] = DEFAULT_PROTECTED + #: Directories new linked worktrees may be created in (directly). + worktree_roots: tuple[Path, ...] = () + host: str = "github.com" + transport: str = "ssh" + + def push_url(self, repo: str) -> str: + if self.transport == "https": + return f"https://{self.host}/{repo}.git" + return f"git@{self.host}:{repo}.git" + + +def _absolute_real_dir(raw: object, key: str) -> Path: + if not isinstance(raw, str) or not raw or not _expand_home(raw).is_absolute(): + raise ConfigError(f"[git] {key} entries must be absolute paths (or start with ~/), got {raw!r}") + path = Path(os.path.abspath(_expand_home(raw))) + if str(path) != os.path.realpath(path): + raise ConfigError( + f"[git] {key} entry {raw!r} must be an absolute path with no symlink on it " + f"(its real location is {os.path.realpath(path)!r})" + ) + return path + + +def _str_list(table: dict[str, object], key: str) -> list[str]: + value = table.get(key, []) + if not isinstance(value, list) or not all(isinstance(v, str) and v for v in value): + raise ConfigError(f"[git] {key} must be a list of non-empty strings") + return list(value) + + +def git_policy(config: Config) -> GitPolicy: + """Validate the policy's ``[git]`` table; without one, every operation refuses.""" + table = config.git + if table is None: + raise ConfigError("the policy has no [git] table, so no git operation may run") + if not isinstance(table, dict): + raise ConfigError("[git] must be a table") + checkouts = tuple(_absolute_real_dir(raw, "checkouts") for raw in _str_list(table, "checkouts")) + if not checkouts: + raise ConfigError("[git] checkouts must name at least one main checkout") + fork = table.get("fork") + if fork is not None and (not isinstance(fork, str) or not _REPO.match(fork)): + raise ConfigError(f"[git] fork must be an 'owner/name' string, got {fork!r}") + host = table.get("host", "github.com") + if not isinstance(host, str) or not _HOST.match(host): + raise ConfigError(f"[git] host must be a host name, got {host!r}") + transport = table.get("transport", "ssh") + if transport not in ("ssh", "https"): + raise ConfigError(f"[git] transport must be 'ssh' or 'https', got {transport!r}") + return GitPolicy( + checkouts=checkouts, + upstream_repo=config.upstream_repo, + fork_repo=fork, + upstream_push=tuple(_str_list(table, "upstream_push")), + protected=DEFAULT_PROTECTED + tuple(_str_list(table, "protected")), + worktree_roots=tuple( + _absolute_real_dir(raw, "worktree_roots") for raw in _str_list(table, "worktree_roots") + ), + host=host, + transport=transport, + ) + + +# --- running git ----------------------------------------------------------- + + +def clean_env(environ: dict[str, str] | None = None) -> dict[str, str]: + """The caller's environment, minus everything that would let it reconfigure git. + + Every ``GIT_*`` variable is dropped (``GIT_DIR``, ``GIT_SSH_COMMAND``, + ``GIT_CONFIG_GLOBAL``, ``GIT_CONFIG_PARAMETERS``, …), and the global + configuration is pinned to the account's own: ``HOME`` comes from the + password database, never from the caller, and ``XDG_CONFIG_HOME`` is + dropped, so a configuration written somewhere the agent can write is never + read as the user's global one. What remains (``PATH``, ``SSH_AUTH_SOCK``, + ``GNUPGHOME``, …) is what the user's own git and ssh setup needs. + """ + source = os.environ if environ is None else environ + env = {k: v for k, v in source.items() if not k.startswith("GIT_") and k != "XDG_CONFIG_HOME"} + env["HOME"] = str(account_home()) + env["GIT_TERMINAL_PROMPT"] = "0" + return env + + +#: Runs ``argv`` with ``env``, in the directory open as ``cwd_fd`` when one is given. +Runner = Callable[[list[str], dict[str, str], "int | None"], "subprocess.CompletedProcess[str]"] + + +def _default_runner( + argv: list[str], env: dict[str, str], cwd_fd: int | None +) -> subprocess.CompletedProcess[str]: + if cwd_fd is None: + return subprocess.run(argv, check=False, capture_output=True, text=True, env=env) + return subprocess.run( + argv, + check=False, + capture_output=True, + text=True, + env=env, + pass_fds=(cwd_fd,), + preexec_fn=lambda: os.fchdir(cwd_fd), + ) + + +def open_dir(path: Path) -> int: + """Open ``path`` as a directory, refusing a symlink at any component. + + Walked one component at a time from ``/`` with ``O_NOFOLLOW``, so the + descriptor is the directory the name led to when it was checked. Git then + runs *in* that descriptor rather than at the name, and swapping a directory + on the path for a symlink afterwards (the agent can write inside a + checkout) cannot send git somewhere else. + """ + flags = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW + fd = os.open("/", os.O_RDONLY | os.O_DIRECTORY) + try: + for part in path.parts[1:]: + child = os.open(part, flags, dir_fd=fd) + os.close(fd) + fd = child + except OSError as exc: + os.close(fd) + raise GitRefused( + f"{str(path)!r} is not a directory reachable without a symlink: {exc.strerror}" + ) from None + return fd + + +#: Pinned on every call, so a key the repository's configuration gains between +#: `check_repository_config` and the command cannot take effect: no file-system +#: monitor program, no automatic gc or maintenance (their hooks are commands), +#: and only network transports (a local path would run that repository's +#: receive-pack and hooks here). The same pins as the local tracker's git. +PINNED_CONFIG = ("core.fsmonitor=false", "gc.auto=0", "maintenance.auto=false", "protocol.allow=never") + +#: The first git that honours ``GIT_ATTR_SOURCE``. +MIN_GIT_VERSION = (2, 42) + +#: The empty tree, per object format: attributes are read from it, so no +#: `.gitattributes` in the working tree can switch on a filter or driver. +EMPTY_TREE = { + "sha1": "4b825dc642cb6eb9a060e54bf8d69288fbee4904", + "sha256": "6ef19b41225c5369f1c104d45d8d85efa9b057b53b14b4b9b939dd74decc5321", +} + + +@dataclass +class Git: + """Runs git with the pins above; injectable for tests.""" + + runner: Runner = field(default=_default_runner) + #: Transports a push may use. Tests add ``file``; production cannot. + protocols: tuple[str, ...] = ("https", "ssh") + #: The user's global ``core.sshCommand`` (or plain ``ssh``), pinned on every + #: call so the repository's configuration cannot replace it. + _ssh_command: str | None = field(default=None, repr=False) + #: Set once the object format is known (see `check_repository_config`). + attr_source: str | None = None + #: Validated directories, open (see `open_dir`); git runs in these, never at the name. + anchors: dict[Path, int] = field(default_factory=dict) + #: Validated working tree -> its git directory. Git gets these explicitly + #: (``--git-dir``, ``--work-tree=.``) and never reads the ``.git`` file of a + #: linked worktree again: that file is in the tree the agent can write. + git_dirs: dict[Path, Path] = field(default_factory=dict) + + def anchor(self, path: Path, fd: int | None = None) -> int: + """Return the open descriptor for ``path``, opening it on first use. + + Takes ownership of a passed ``fd``: it is kept until `close`, or closed + at once when ``path`` already has a descriptor. + """ + if path in self.anchors: + if fd is not None and fd != self.anchors[path]: + os.close(fd) + else: + self.anchors[path] = open_dir(path) if fd is None else fd + return self.anchors[path] + + def close(self) -> None: + for fd in self.anchors.values(): + os.close(fd) + self.anchors.clear() + + def check_version(self) -> None: + """Refuse a git older than `MIN_GIT_VERSION`, which ignores ``GIT_ATTR_SOURCE``.""" + found = self.runner(["git", "version"], clean_env(), None) + match = re.search(r"(\d+)\.(\d+)", found.stdout or "") + version = (int(match.group(1)), int(match.group(2))) if match else (0, 0) + if found.returncode != 0 or version < MIN_GIT_VERSION: + raise GitRefused( + f"git {'.'.join(map(str, MIN_GIT_VERSION))} or later is required (found " + f"{(found.stdout or '').strip() or 'none'}): an older git ignores GIT_ATTR_SOURCE, so a " + ".gitattributes could switch on a filter outside the sandbox" + ) + + def ssh_command(self) -> str: + if self._ssh_command is None: + argv = ["git", "config", "--global", "--get", "core.sshCommand"] + found = self.runner(argv, clean_env(), None) + value = found.stdout.strip() if found.returncode == 0 else "" + self._ssh_command = value if value and "\n" not in value else "ssh" + return self._ssh_command + + def argv(self, directory: Path, *args: str, hooks: bool = False) -> list[str]: + """A git command in ``directory``, with hooks switched off unless ``hooks``. + + An anchored directory is entered by descriptor (see `open_dir`), so the + argv names it only when it is not anchored (dry runs print the name). + """ + pins = [*PINNED_CONFIG, *(f"protocol.{p}.allow=always" for p in self.protocols)] + pins.append(f"core.sshCommand={self.ssh_command()}") + if not hooks: + pins.append("core.hooksPath=/dev/null") + where = [] if directory in self.anchors else ["-C", str(directory)] + if directory in self.git_dirs: + where += [f"--git-dir={self.git_dirs[directory]}", "--work-tree=."] + return ["git", *(arg for pin in pins for arg in ("-c", pin)), *where, *args] + + def _env(self) -> dict[str, str]: + env = clean_env() + # Overrides every protocol.* setting, the repository's included. + env["GIT_ALLOW_PROTOCOL"] = ":".join(self.protocols) + if self.attr_source is not None: + env["GIT_ATTR_SOURCE"] = self.attr_source + return env + + def _call( + self, directory: Path, *args: str, hooks: bool = False + ) -> tuple[list[str], subprocess.CompletedProcess[str]]: + argv = self.argv(directory, *args, hooks=hooks) + return argv, self.runner(argv, self._env(), self.anchors.get(directory)) + + def run(self, directory: Path, *args: str, hooks: bool = False) -> str: + argv, completed = self._call(directory, *args, hooks=hooks) + if completed.returncode != 0: + raise GitFailed(argv, completed.returncode, completed.stderr or "", completed.stdout or "") + return completed.stdout + + def ok(self, directory: Path, *args: str) -> bool: + return self._call(directory, *args)[1].returncode == 0 + + +# --- validation ------------------------------------------------------------ + + +def _param(raw: str, name: str) -> str: + if not raw or raw.startswith("-") or "\x00" in raw or "\n" in raw: + raise GitRefused(f"parameter {name!r} may not be empty, start with '-' or span lines: {raw!r}") + return raw + + +def sha(raw: str, name: str) -> str: + if not _SHA.match(_param(raw, name)): + raise GitRefused(f"{name} must be a full lowercase commit SHA, got {raw!r}") + return raw + + +def branch_name(git: Git, directory: Path, raw: str, name: str) -> str: + _param(raw, name) + if not _BRANCH.match(raw) or ".." in raw or raw.endswith((".lock", "/", ".")): + raise GitRefused(f"{name} is not an acceptable branch name: {raw!r}") + if not git.ok(directory, "check-ref-format", "--branch", raw): + raise GitRefused(f"{name} is not a valid branch name: {raw!r}") + return raw + + +def is_protected(branch: str, policy: GitPolicy) -> bool: + return any(fnmatch.fnmatchcase(branch, glob) for glob in policy.protected) + + +def _absolute(raw: str, name: str) -> Path: + expanded = _expand_home(_param(raw, name)) + if not expanded.is_absolute(): + raise GitRefused(f"{name} must be an absolute path (or start with ~/), got {raw!r}") + return Path(os.path.abspath(expanded)) + + +def _real_dir(raw: str, name: str) -> Path: + path = _absolute(raw, name) + if str(path) != os.path.realpath(path): + raise GitRefused(f"{name} {raw!r} has a symlink on its path; name its real location") + return path + + +@dataclass(frozen=True) +class Worktree: + """A working tree of one of the policy's checkouts.""" + + path: Path + checkout: Path + #: (device, inode) of the checkout's `.git` directory when it was validated. + git_dir_id: tuple[int, int] = (0, 0) + #: The worktree's own git directory: `.git` for the main checkout, the + #: registered `.git/worktrees/` for a linked one. + git_dir: Path = Path("/nonexistent") + + @property + def linked(self) -> bool: + return self.path != self.checkout + + +def resolve_worktree(git: Git, raw: str, policy: GitPolicy, name: str = "worktree") -> Worktree: + """The working tree at ``raw``, if it is a policy checkout or one of its linked worktrees.""" + path = _real_dir(raw, name) + if not path.is_dir(): + raise GitRefused(f"{name} {str(path)!r} is not a directory") + git.anchor(path) + lines = git.run(path, "rev-parse", "--path-format=absolute", "--show-toplevel", "--git-common-dir") + top, common = (Path(os.path.realpath(line)) for line in lines.splitlines()[:2]) + if top != path: + raise GitRefused(f"{name} {str(path)!r} is not the top of a working tree (that is {str(top)!r})") + for checkout in policy.checkouts: + if common == checkout / ".git" and (checkout / ".git").is_dir(): + git.anchor(checkout) + worktree = Worktree(path=path, checkout=checkout, git_dir_id=git_dir_identity(checkout)) + worktree = _check_registered(git, worktree, name) + git.git_dirs[path] = worktree.git_dir + git.git_dirs.setdefault(checkout, checkout / ".git") + return worktree + allowed = ", ".join(str(c) for c in policy.checkouts) + raise GitRefused(f"{name} {str(path)!r} does not belong to a checkout the policy names ({allowed})") + + +def git_dir_identity(checkout: Path) -> tuple[int, int]: + """The checkout's `.git`, looked up by name now, with no symlink anywhere on the way. + + Looked up afresh each time rather than through an anchor, so a directory + swapped anywhere on the path since the last look shows as a different one. + """ + fd = open_dir(checkout) + try: + found = os.stat(".git", dir_fd=fd, follow_symlinks=False) + except OSError as exc: + raise GitRefused(f"cannot read {str(checkout / '.git')!r}: {exc.strerror}") from None + finally: + os.close(fd) + if not stat.S_ISDIR(found.st_mode): + raise GitRefused(f"{str(checkout / '.git')!r} is not a directory") + return (found.st_dev, found.st_ino) + + +def _check_registered(git: Git, worktree: Worktree, name: str) -> Worktree: + """A linked worktree must be one git registered for this path, not a copy pointing at `.git`.""" + git_dir = Path(os.path.realpath(git.run(worktree.path, "rev-parse", "--absolute-git-dir").strip())) + main = worktree.checkout / ".git" + if not worktree.linked: + if git_dir != main: + raise GitRefused(f"{name} {str(worktree.path)!r} does not use {str(main)!r} as its git directory") + return dataclasses.replace(worktree, git_dir=main) + if git_dir.parent != main / "worktrees": + raise GitRefused( + f"{name} {str(worktree.path)!r} is not a linked worktree registered with {str(main)!r}" + ) + try: + registered = (git_dir / "gitdir").read_text().strip() + except OSError: + registered = "" + if Path(os.path.realpath(registered)) != worktree.path / ".git": + raise GitRefused(f"{name} {str(worktree.path)!r} is not where git registered {git_dir.name!r}") + return dataclasses.replace(worktree, git_dir=git_dir) + + +def parse_config_scopes(output: str) -> list[tuple[str, str]]: + """``git config --list --show-scope --name-only -z`` output as (scope, key) pairs.""" + items = [item for item in output.split("\x00") if item] + pairs: list[tuple[str, str]] = [] + pending: str | None = None + for item in items: + if "\t" in item: + scope, key = item.split("\t", 1) + pairs.append((scope, key)) + elif pending is None: + pending = item + else: + pairs.append((pending, item)) + pending = None + return pairs + + +def check_repository_config(git: Git, worktree: Worktree) -> None: + """Refuse a repository whose own configuration holds a key outside `SAFE_LOCAL_KEY`. + + Checked in every working tree an operation runs git in (a linked worktree + has its own ``config.worktree``), and again right before the command that + acts, so a key added after the first check is still caught; what cannot + be re-checked in between is pinned by `PINNED_CONFIG`. + """ + git.check_version() + if git_dir_identity(worktree.checkout) != worktree.git_dir_id: + raise GitRefused(f"{str(worktree.checkout / '.git')!r} changed since it was validated") + # A linked worktree's common directory comes from its `commondir` file, which + # can be rewritten after `resolve_worktree` looked: ask git again, through the + # same pinned git directory the command will use, and require the same answer. + lines = git.run( + worktree.path, "rev-parse", "--path-format=absolute", "--git-common-dir", "--absolute-git-dir" + ) + common, git_dir = (Path(os.path.realpath(line)) for line in lines.splitlines()[:2]) + if common != worktree.checkout / ".git": + raise GitRefused( + f"the common git directory of {str(worktree.path)!r} is now {str(common)!r}, " + f"not {str(worktree.checkout / '.git')!r}" + ) + if git_dir != worktree.git_dir: + raise GitRefused(f"the git directory of {str(worktree.path)!r} changed since it was validated") + for directory in dict.fromkeys((worktree.path, worktree.checkout)): + _check_config_in(git, directory) + object_format = git.run(worktree.path, "rev-parse", "--show-object-format").strip() + if object_format not in EMPTY_TREE: + raise GitRefused(f"unsupported object format {object_format!r}") + git.attr_source = EMPTY_TREE[object_format] + + +def _check_config_in(git: Git, directory: Path) -> None: + output = git.run(directory, "config", "--list", "--show-scope", "--name-only", "--includes", "-z") + unsafe = sorted( + { + key + for scope, key in parse_config_scopes(output) + # `command` scope is this module's own `-c` pins; `GIT_CONFIG_*` is dropped. + if scope in ("local", "worktree") and not SAFE_LOCAL_KEY.match(key.lower()) + } + ) + if unsafe: + raise GitRefused( + f"the repository configuration of {str(directory)!r} sets {', '.join(unsafe)}; " + "git runs outside the sandbox here, so only inert repository settings are accepted. " + "Move those settings to your global git configuration, or remove them, and retry" + ) + + +def resolve_commit(git: Git, directory: Path, commit: str, name: str) -> str: + if not git.ok(directory, "cat-file", "-e", f"{commit}^{{commit}}"): + raise GitRefused(f"{name} {commit} is not a commit in this repository") + return commit + + +# --- operations ------------------------------------------------------------ + + +@dataclass(frozen=True) +class GitOp: + name: str + params: tuple[str, ...] + summary: str + run: Callable[[Git, GitPolicy, dict[str, str], bool], str] + + +def _refuse_empty_branch(git: Git, worktree: Worktree, commit: str, local: str) -> None: + """The agent-guard `empty-rebase` rule, for the push this dispatcher runs. + + Moving an existing branch to a commit with nothing over a default branch + (a rebase that dropped every commit) closes the pull request it heads and + revokes maintainers' push access to it. The bases are the remotes' default + branches (`refs/remotes/*/HEAD`); with none known, nothing is refused, as + in the guard. There is no override: closing a pull request is not a push. + """ + heads = git.run(worktree.path, "for-each-ref", "--format=%(symref)", "refs/remotes/*/HEAD") + for base in sorted({line for line in heads.splitlines() if line}): + if git.run(worktree.path, "rev-list", "--count", f"{base}..{commit}").strip() == "0": + raise GitRefused( + f"{local!r} has no commits over {base.removeprefix('refs/remotes/')}; force-pushing it " + "would empty the branch, which closes a pull request it heads. Check the rebase result" + ) + + +def push_branch(git: Git, policy: GitPolicy, p: dict[str, str], dry_run: bool) -> str: + """Push a local branch's commit to the fork or upstream, with a lease on the expected SHA.""" + worktree = resolve_worktree(git, p["checkout"], policy, "checkout") + check_repository_config(git, worktree) + local = branch_name(git, worktree.path, p["branch"], "branch") + remote_branch = branch_name(git, worktree.path, p["remote_branch"], "remote_branch") + if is_protected(remote_branch, policy): + raise GitRefused(f"{remote_branch!r} is a protected branch; no operation pushes to it") + target = _param(p["target"], "target") + if target == "fork": + if policy.fork_repo is None: + raise GitRefused("the policy names no [git] fork, so nothing may be pushed to one") + repo = policy.fork_repo + elif target == "upstream": + if not any(fnmatch.fnmatchcase(remote_branch, glob) for glob in policy.upstream_push): + raise GitRefused( + f"{remote_branch!r} matches no [git] upstream_push glob " + f"({', '.join(policy.upstream_push) or 'none declared'}), so it may not be pushed upstream" + ) + repo = policy.upstream_repo + else: + raise GitRefused(f"target must be 'fork' or 'upstream', got {target!r}") + expected = p["expected"] + lease = "" if expected == "new" else sha(expected, "expected") + if not git.ok(worktree.path, "show-ref", "--verify", "--quiet", f"refs/heads/{local}"): + raise GitRefused(f"there is no local branch {local!r}") + commit = git.run(worktree.path, "rev-parse", "--verify", f"refs/heads/{local}^{{commit}}").strip() + if lease: + _refuse_empty_branch(git, worktree, commit, local) + args = [ + "push", + # The pre-push checks run in the sandbox before this call (see the module + # docstring): a hook here would run working-tree code outside it. + "--no-verify", + # Only the one ref: `push.followTags` would also publish reachable tags. + "--no-follow-tags", + "--porcelain", + f"--force-with-lease=refs/heads/{remote_branch}:{lease}", + policy.push_url(repo), + f"{commit}:refs/heads/{remote_branch}", + ] + if dry_run: + return " ".join(git.argv(worktree.path, *args)) + check_repository_config(git, worktree) + git.run(worktree.path, *args) + was = "created" if not lease else f"was {lease}" + return f"pushed {commit} to {repo} {remote_branch} ({was})" + + +def worktree_sync(git: Git, policy: GitPolicy, p: dict[str, str], dry_run: bool) -> str: + """Move a clean linked worktree's branch to a commit (``reset --keep``).""" + worktree = resolve_worktree(git, p["worktree"], policy) + if not worktree.linked: + raise GitRefused("worktree-sync moves linked worktrees only; this is the main checkout") + check_repository_config(git, worktree) + commit = resolve_commit(git, worktree.path, sha(p["commit"], "commit"), "commit") + if not git.ok(worktree.path, "symbolic-ref", "--quiet", "HEAD"): + raise GitRefused(f"{str(worktree.path)!r} has a detached HEAD; check out its branch first") + branch = git.run(worktree.path, "symbolic-ref", "--short", "HEAD").strip() + if git.run(worktree.path, "status", "--porcelain", "--untracked-files=no").strip(): + raise GitRefused(f"{str(worktree.path)!r} has uncommitted changes; commit or set them aside first") + previous = git.run(worktree.path, "rev-parse", "HEAD").strip() + args = ["reset", "--keep", commit] + if dry_run: + return " ".join(git.argv(worktree.path, *args)) + check_repository_config(git, worktree) + git.run(worktree.path, *args) + return f"moved {branch} in {worktree.path} from {previous} to {commit}" + + +def worktree_add(git: Git, policy: GitPolicy, p: dict[str, str], dry_run: bool) -> str: + """Create a linked worktree on a new branch, inside a policy worktree root.""" + checkout = resolve_worktree(git, p["checkout"], policy, "checkout") + if checkout.linked: + raise GitRefused("checkout must be the main checkout, not a linked worktree") + check_repository_config(git, checkout) + path = _absolute(p["path"], "path") + if not _WORKTREE_NAME.match(path.name): + raise GitRefused(f"the new worktree's directory name is not acceptable: {path.name!r}") + if not any( + path.parent == root and str(root) == os.path.realpath(path.parent) for root in policy.worktree_roots + ): + roots = ", ".join(str(r) for r in policy.worktree_roots) or "none declared" + raise GitRefused(f"{str(path)!r} is not directly inside a [git] worktree_roots directory ({roots})") + if os.path.lexists(path): + raise GitRefused(f"{str(path)!r} already exists") + branch = branch_name(git, checkout.path, p["branch"], "branch") + if git.ok(checkout.path, "show-ref", "--verify", "--quiet", f"refs/heads/{branch}"): + raise GitRefused(f"branch {branch!r} already exists; worktree-add creates a new one") + start = resolve_commit(git, checkout.path, sha(p["start"], "start"), "start") + if dry_run: + return " ".join(git.argv(checkout.path, "worktree", "add", "-b", branch, str(path), start)) + check_repository_config(git, checkout) + # Created through the root's descriptor and entered by descriptor, then + # added as `.`: a root swapped for a symlink after the checks above still + # cannot make git write anywhere but this new, empty directory. (Git names + # its administrative directory after the path given, so it is `-` here.) + root_fd = open_dir(path.parent) + try: + os.mkdir(path.name, 0o777, dir_fd=root_fd) + new_fd = os.open(path.name, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=root_fd) + git.anchor(path, new_fd) + try: + git.run( + path, f"--git-dir={checkout.checkout / '.git'}", "worktree", "add", "-b", branch, ".", start + ) + except GitFailed: + os.rmdir(path.name, dir_fd=root_fd) + raise + finally: + os.close(root_fd) + return f"created {path} on new branch {branch} at {start}" + + +def worktree_remove(git: Git, policy: GitPolicy, p: dict[str, str], dry_run: bool) -> str: + """Remove a linked worktree that has no changes (never ``--force``).""" + worktree = resolve_worktree(git, p["worktree"], policy) + if not worktree.linked: + raise GitRefused("worktree-remove removes linked worktrees only; this is the main checkout") + check_repository_config(git, worktree) + args = ["worktree", "remove", str(worktree.path)] + if dry_run: + return " ".join(git.argv(worktree.checkout, *args)) + # Without --force git itself refuses a worktree with modified or untracked files. + check_repository_config(git, worktree) + git.run(worktree.checkout, *args) + return f"removed {worktree.path}" + + +OPS: dict[str, GitOp] = { + op.name: op + for op in ( + GitOp( + "git-push-branch", + ("checkout", "branch", "target", "remote_branch", "expected"), + "push local to of the fork or upstream; is the " + "remote branch's current full SHA, or 'new'. No hook runs: run the pre-push checks " + "in the sandbox first", + push_branch, + ), + GitOp( + "git-worktree-sync", + ("worktree", "commit"), + "move a clean linked worktree's branch to (reset --keep)", + worktree_sync, + ), + GitOp( + "git-worktree-add", + ("checkout", "path", "branch", "start"), + "create a linked worktree at on a new starting at ", + worktree_add, + ), + GitOp( + "git-worktree-remove", + ("worktree",), + "remove a linked worktree that has no changes", + worktree_remove, + ), + ) +} + + +def main(argv: list[str] | None = None, *, git: Git | None = None) -> int: + """The ``vetted-op-git`` console script.""" + raw = list(sys.argv[1:] if argv is None else argv) + parser = argparse.ArgumentParser( + prog=PROG, + description="Run one fixed, policy-scoped git operation outside the sandbox. No pass-through arguments.", + ) + parser.add_argument("--caller", help="the skill or plugin invoking this operation") + parser.add_argument("--dry-run", action="store_true", help="validate, print the git command, run nothing") + parser.add_argument("operation", nargs="?", help="operation name, or 'list-ops' / 'policy'") + parser.add_argument("params", nargs="*", help="operation parameters, positionally") + args = parser.parse_args(raw) + + if args.operation in (None, "list-ops"): + for name, entry in sorted(OPS.items()): + print(f"write {name:<22} {' '.join(entry.params)}\n {entry.summary}") + return EXIT_OK + + if sum(1 for a in raw if a == "--caller" or a.startswith("--caller=")) > 1: + print(f"{PROG}: refused: --caller given more than once", file=sys.stderr) + return EXIT_POLICY + + # Like every entry point that runs outside the sandbox: only a policy the user + # placed in the approved directory themselves drives git. A dry run against + # one that is not approved yet still checks its parameters, but runs no git + # command at all: even read-only git, out here, is steered by that policy. + approved = True + try: + try: + config = load(approved_only=args.operation != "policy") + except ConfigError: + if not args.dry_run: + raise + config = load(approved_only=False) + approved = False + policy = git_policy(config) + except ConfigError as exc: + print(f"{PROG}: config error: {exc}", file=sys.stderr) + return EXIT_POLICY + + if args.operation == "policy": + print(describe(config)) + return EXIT_OK + + if not args.caller: + print(f"{PROG}: --caller is required for any operation", file=sys.stderr) + return EXIT_USAGE + + op = OPS.get(args.operation) + try: + if op is None: + raise GitRefused(f"unknown operation {args.operation!r}; see '{PROG} list-ops'") + permitted = config.ops_for(args.caller) + if op.name not in permitted: + raise GitRefused( + f"caller {args.caller!r} is not permitted to run {op.name!r}; " + f"permitted: {', '.join(sorted(permitted)) or '(none)'}" + ) + if len(args.params) != len(op.params): + raise GitRefused( + f"operation {op.name!r} takes {len(op.params)} parameter(s) ({', '.join(op.params)}), " + f"got {len(args.params)}" + ) + params = dict(zip(op.params, args.params, strict=True)) + for name, value in params.items(): + _param(value, name) + if not approved: + print( + f"{PROG}: dry run against a policy that is not approved: the parameters are well formed; " + "no git command was run. Approve the policy to see the command it would run." + ) + return EXIT_OK + runner = git or Git() + try: + print(op.run(runner, policy, params, args.dry_run)) + finally: + runner.close() + except (GitRefused, ConfigError) as exc: + print(f"{PROG}: refused: {exc}", file=sys.stderr) + return EXIT_POLICY + except GitFailed as exc: + sys.stderr.write(exc.stdout) + sys.stderr.write(exc.stderr) + print(f"{PROG}: {op.name if op else args.operation} failed: {exc}", file=sys.stderr) + return EXIT_COMMAND + return EXIT_OK diff --git a/tools/agent-guard/src/agent_guard/__init__.py b/tools/agent-guard/src/agent_guard/__init__.py index a6537d126..1d6925ee2 100644 --- a/tools/agent-guard/src/agent_guard/__init__.py +++ b/tools/agent-guard/src/agent_guard/__init__.py @@ -2063,6 +2063,7 @@ def guard_empty_rebase(seg: Segment, cwd: str | None) -> str | None: "vetted-op": "vetted-ops", "vetted-op-read": "vetted-ops", "vetted-op-tracker": "vetted-ops", + "vetted-op-git": "vetted-ops", "adversarial-review": "adversarial-review", } VETTED_STABLE_BASE = "~/.claude/magpie/" diff --git a/tools/agent-isolation/gpg-touch-overlay.sh b/tools/agent-isolation/gpg-touch-overlay.sh index 1454549a3..c0fb5e02f 100755 --- a/tools/agent-isolation/gpg-touch-overlay.sh +++ b/tools/agent-isolation/gpg-touch-overlay.sh @@ -337,7 +337,9 @@ readonly KEY_SUBCOMMANDS='commit|tag|merge|rebase|revert|cherry-pick|am|push|pul # keeps `ssh-agent` (starts one, never asks the key) and `sshuttle` out # while leaving `ssh-keygen -Y sign` and `ssh-add -l` in. Longer names # lead the alternation so the match cannot stop short at `ssh`. -readonly KEY_COMMANDS='ssh-keygen|ssh-add|ssh|scp|sftp|sshfs|rsync|svn|gpg2|gpg' +# `vetted-op-git` pushes over ssh outside the sandbox (tools/vetted-ops), and +# it is launched through uv, so no git word precedes the push it runs. +readonly KEY_COMMANDS='vetted-op-git|ssh-keygen|ssh-add|ssh|scp|sftp|sshfs|rsync|svn|gpg2|gpg' # gh runs git for these, over ssh when its git_protocol is ssh: `create` # pushes a branch or repository that is not on GitHub yet. Options diff --git a/tools/agent-isolation/tests/test_gpg_touch_overlay.py b/tools/agent-isolation/tests/test_gpg_touch_overlay.py index 3da2b6fb1..890e38e46 100644 --- a/tools/agent-isolation/tests/test_gpg_touch_overlay.py +++ b/tools/agent-isolation/tests/test_gpg_touch_overlay.py @@ -201,6 +201,9 @@ def test_stays_quiet_for_commands_that_cannot_sign(command: str) -> None: "gpg --detach-sign --armor apache-magpie-0.2.0.tar.gz", "gpg2 --clearsign message.txt", "gpg --decrypt secrets.asc", + # The vetted git dispatcher pushes over ssh, in both launcher forms. + "uvx --from ~/.claude/magpie/vetted-ops vetted-op-git --caller x git-push-branch ~/code/p b fork b new verify", + "uv run --project ~/.claude/magpie/vetted-ops vetted-op-git --caller x git-push-branch ~/code/p b fork b new verify", # The ssh-format signer and the agent query, invoked directly. "ssh-keygen -Y sign -f ~/.ssh/id_rsa_yubikey.pub -n file x", "ssh-add -l", diff --git a/tools/sandbox-lint/expected.json b/tools/sandbox-lint/expected.json index 4328d52fd..edfa526b2 100644 --- a/tools/sandbox-lint/expected.json +++ b/tools/sandbox-lint/expected.json @@ -11,6 +11,8 @@ "uvx --from ~/.claude/magpie/vetted-ops vetted-op-read *", "uv run --project ~/.claude/magpie/vetted-ops vetted-op-tracker *", "uvx --from ~/.claude/magpie/vetted-ops vetted-op-tracker *", + "uv run --project ~/.claude/magpie/vetted-ops vetted-op-git *", + "uvx --from ~/.claude/magpie/vetted-ops vetted-op-git *", "uv run --project ~/.claude/magpie/vetted-ops vetted-op *", "uvx --from ~/.claude/magpie/vetted-ops vetted-op *", "uvx --from ~/.claude/magpie/adversarial-review adversarial-review *", @@ -176,6 +178,8 @@ "Bash(git push --force-with-lease *)", "Bash(uv run --project ~/.claude/magpie/vetted-ops vetted-op-tracker *)", "Bash(uvx --from ~/.claude/magpie/vetted-ops vetted-op-tracker *)", + "Bash(uv run --project ~/.claude/magpie/vetted-ops vetted-op-git *)", + "Bash(uvx --from ~/.claude/magpie/vetted-ops vetted-op-git *)", "Bash(uv run --project ~/.claude/magpie/vetted-ops vetted-op *)", "Bash(uvx --from ~/.claude/magpie/vetted-ops vetted-op *)", "Bash(uvx --from ~/.claude/magpie/security-tools/cve-tool cve-tool *)", diff --git a/tools/sandbox-lint/src/sandbox_lint/__init__.py b/tools/sandbox-lint/src/sandbox_lint/__init__.py index 20ab5199a..059cc67eb 100644 --- a/tools/sandbox-lint/src/sandbox_lint/__init__.py +++ b/tools/sandbox-lint/src/sandbox_lint/__init__.py @@ -155,12 +155,12 @@ def registry_errors(floor: dict[str, Any], registry: dict[str, Any]) -> list[str # allow, and the prompt is then the gate on every remote mutation. VETTED_OP_WRITE_SAMPLE_COMMANDS = tuple( f"{launcher} {VETTED_OPS_BASE} {name} --caller sandbox-lint pr-add-label 1 sandbox-lint" - for name in ("vetted-op-tracker", "vetted-op") + for name in ("vetted-op-tracker", "vetted-op-git", "vetted-op") for launcher in VETTED_OP_READ_LAUNCHERS ) # Spellings that name a dispatcher: `vetted-op ` carries its trailing space so # the `vetted-ops` path segment alone does not count. -VETTED_OP_DISPATCHER_NAMES = ("vetted-op-read", "vetted-op-tracker", "vetted-op ") +VETTED_OP_DISPATCHER_NAMES = ("vetted-op-read", "vetted-op-tracker", "vetted-op-git", "vetted-op ") # The tamper protection that makes the unprompted read safe to allow. REQUIRED_VETTED_OPS_DENY = ( "Edit(~/.claude/plugins/cache/apache-magpie/magpie-vetted-ops/**)", @@ -317,6 +317,8 @@ def registry_errors(floor: dict[str, Any], registry: dict[str, Any]) -> list[str "uv run --project ~/.claude/magpie/vetted-ops vetted-op-tracker *", "uvx --from ~/.claude/magpie/vetted-ops vetted-op-read *", "uvx --from ~/.claude/magpie/vetted-ops vetted-op-tracker *", + "uv run --project ~/.claude/magpie/vetted-ops vetted-op-git *", + "uvx --from ~/.claude/magpie/vetted-ops vetted-op-git *", "uv run --project ~/.claude/magpie/vetted-ops vetted-op *", "uvx --from ~/.claude/magpie/vetted-ops vetted-op *", "uvx --from ~/.claude/magpie/adversarial-review adversarial-review *", @@ -1041,7 +1043,7 @@ def _vetted_op_read_never_prompts( def _vetted_op_writes_prompt(perms: dict[str, Any], ask: set[str], excluded: list[str]) -> list[str]: """Violations of the always-prompt shape for the vetted-ops write dispatchers. - `vetted-op` and `vetted-op-tracker` run outside the sandbox (a sandboxed + `vetted-op`, `vetted-op-tracker` and `vetted-op-git` run outside the sandbox (a sandboxed `gh` cannot verify TLS), which is safe only while every call still asks. A write command that is excluded or allowed must therefore match an `ask` rule. """ diff --git a/tools/vetted-ops/README.md b/tools/vetted-ops/README.md index c774148fd..5c6700973 100644 --- a/tools/vetted-ops/README.md +++ b/tools/vetted-ops/README.md @@ -21,6 +21,7 @@ - [The pr-management-stats reads](#the-pr-management-stats-reads) - [Tracker procedures: rollup and body-field writes](#tracker-procedures-rollup-and-body-field-writes) - [Tracker backends](#tracker-backends) + - [Git operations the sandbox blocks](#git-operations-the-sandbox-blocks) - [Wiring it into settings](#wiring-it-into-settings) - [Codex native rules](#codex-native-rules) - [Tests](#tests) @@ -151,6 +152,7 @@ scripts over one catalogue: |---|---|---| | `vetted-op-read` | never — refused before policy is consulted | `allow` | | `vetted-op-tracker` | only the [tracker procedures](#tracker-procedures-rollup-and-body-field-writes) — everything else refused before policy is consulted | `ask`, and excluded from the sandbox | +| `vetted-op-git` | only the [git operations](#git-operations-the-sandbox-blocks) — no `gh` operation exists there | `ask`, and excluded from the sandbox | | `vetted-op` | yes, subject to policy | `ask` (or unlisted) | That split is what lets the read path lose its prompts without the write path @@ -766,6 +768,109 @@ On a non-GitHub tracker the `number` parameter of a tracker operation takes the backend's own IDs (`SEC-0012`, `FOOSEC-12`, `2024-007-xss`): letters, digits, `-` and `_` only, so an ID can never name a path. +## Git operations the sandbox blocks + +Three git steps fail in a sandboxed session however the agent phrases them, and +used to end in a command the user pasted into their own terminal: + +- **Pushing over SSH.** The sandbox routes network through an HTTP proxy, so an + SSH transport gets no TCP at all, and a hardware key's touch prompt never + reaches the user. +- **Moving a linked worktree** to a rebased or pushed commit. Harnesses keep + `.git/worktrees//` read-only for worktrees the session did not create, + so `git reset`, `git fetch` and `git rebase` in such a worktree stop half-way. +- **Adding or removing a linked worktree**, for the same reason. + +`vetted-op-git` runs exactly those four steps outside the sandbox, as closed +shapes, behind the harness's confirmation like `vetted-op`: + +| Operation | Parameters | What it does | +|---|---|---| +| `git-push-branch` | `checkout branch target remote_branch expected` | Pushes local `branch`'s commit to `remote_branch` of the policy's `fork` or `upstream` repository, with `--force-with-lease=refs/heads/:` and `--no-verify`. `expected` is the remote branch's current full SHA, or `new`. Run the pre-push checks in the sandbox first. | +| `git-worktree-sync` | `worktree commit` | Moves a clean linked worktree's branch to `commit` with `git reset --keep`, and prints the commit it was on. | +| `git-worktree-add` | `checkout path branch start` | Creates a linked worktree at `path`, directly inside a `worktree_roots` directory, on a new `branch` at `start`. | +| `git-worktree-remove` | `worktree` | Removes a linked worktree that has no changes (never `--force`). | + +```bash +uvx --from ~/.claude/magpie/vetted-ops vetted-op-git --caller git-push-branch \ + ~/code/project fix-thing fork fix-thing 0123…(40 hex) +``` + +The policy's `[git]` table bounds them: + +```toml +[git] +# Main checkouts the operations may act on; their linked worktrees count too. +checkouts = ["~/code/project"] +# Pushed over git@:.git (transport = "https" for https:///.git). +fork = "alice/project" +# Branches a push may create or move on [repos] upstream. Empty or absent: never. +upstream_push = ["ci-*", "stack/*"] +# Added to the built-in list (main, master, trunk, develop, gh-pages, release*, v*-test, v*-stable, *-stable, asf-site). +protected = ["prod"] +# Directories new worktrees may be created in, directly. +worktree_roots = ["~/code/project/files"] +``` + +What makes running git unsandboxed acceptable here: + +- **Closed destinations.** A push goes to a URL built from the policy's + repository names, never to a remote the repository configures. Protected + branches are refused whatever the policy says, and upstream takes only + branches matching `upstream_push`. +- **Nothing lost silently.** Every push carries a lease on the full SHA the + caller expects (`new` for a branch that must not exist yet), so a branch + someone else moved is never overwritten, and moving a branch to a commit with + nothing over a remote's default branch (an emptied rebase, which would close + the pull request it heads) is refused, as agent-guard's `empty-rebase` guard + refuses the plain `git push`. A worktree moves only when it has + no local changes, and the previous commit is printed and stays in the reflog. +- **No repository configuration steers git.** Keys such as `core.sshCommand`, + `url.*.insteadOf`, `filter.*`, `core.fsmonitor`, `core.hooksPath` or + `include.path` can be planted in a repository's own config; the operation + refuses to run while the local or worktree config holds any key outside a + short list of inert ones (remotes, branch tracking, `user.name`, …). Global + and system configuration are the user's own and stay in effect, so an SSH + wrapper or touch overlay configured there keeps working. The check covers + every working tree the operation runs git in, and runs again right before + the command that acts. +- **Pinned on every call**, so a key added between that check and the command + cannot take effect: no file-system monitor, no automatic gc or maintenance, + only `https` and `ssh` transports, `core.sshCommand` set to the user's global + value (or `ssh`), and hooks off wherever they are not wanted. Attributes are + read from the empty tree, so no `.gitattributes` can switch on a filter + (the cost: a worktree is checked out without LFS smudging or line-ending + conversion). A push sends the one ref, never tags (`--no-follow-tags`), and + `GIT_ALLOW_PROTOCOL` limits transports whatever the configuration says. +- **Directories are held, not named.** Each validated directory is opened + without following a symlink at any component, and git runs inside it by + descriptor, so a directory swapped for a symlink after the checks cannot + send git elsewhere. A new worktree is created through its root's descriptor + and added as `.`, so git names its administrative directory `-` (`-1`, …). + A URL rewrite (`url.*.insteadOf`) cannot be pinned away: that it cannot + appear while the confirmed command runs rests on the harness keeping + `.git/config` write-protected, as Claude Code's sandbox does. +- **No environment steers git.** Every `GIT_*` variable is dropped, `HOME` + comes from the password database and `XDG_CONFIG_HOME` is dropped, so the + global configuration git reads is the account's own. +- **Hooks never run.** No operation runs a hook: the worktree operations set + `core.hooksPath=/dev/null`, and a push also passes `--no-verify`. A + `pre-push` hook is code the agent can write (`.git/hooks/pre-push`, or a + hook manager reading its configuration from the working tree), and the + confirmation shows the push, not what the hook would execute, so running it + here would run agent-written code outside the sandbox. The push-time checks + still run: the caller runs them inside the sandbox first (for prek, + `prek run --hook-stage pre-push --from-ref --to-ref `), fixes + what they report, and only then pushes. +- **Unapproved policy, dry run.** `--dry-run` against a policy that is not an + approved copy checks the parameters and runs no git command; only an + approved policy prints the command it would run. + +Everything else git does in a sandboxed session stays there. Rewriting history +for a branch checked out in a worktree you did not create is done in a scratch +clone (`git clone --shared `), fetched back into the main +checkout, pushed with `git-push-branch` and applied with `git-worktree-sync`. + ## Wiring it into settings Replace the wildcard `ask` rules with one `allow` entry, and keep an `ask` on @@ -786,7 +891,9 @@ anything still invoked directly: "Bash(uv run --project ~/.claude/magpie/vetted-ops vetted-op *)", "Bash(uvx --from ~/.claude/magpie/vetted-ops vetted-op *)", "Bash(uv run --project ~/.claude/magpie/vetted-ops vetted-op-tracker *)", - "Bash(uvx --from ~/.claude/magpie/vetted-ops vetted-op-tracker *)" + "Bash(uvx --from ~/.claude/magpie/vetted-ops vetted-op-tracker *)", + "Bash(uv run --project ~/.claude/magpie/vetted-ops vetted-op-git *)", + "Bash(uvx --from ~/.claude/magpie/vetted-ops vetted-op-git *)" ], "deny": [ // `Edit(path)` is the path rule for every file-writing tool — Write and @@ -820,6 +927,8 @@ fails the same way: "uvx --from ~/.claude/magpie/vetted-ops vetted-op-read *", "uv run --project ~/.claude/magpie/vetted-ops vetted-op-tracker *", "uvx --from ~/.claude/magpie/vetted-ops vetted-op-tracker *", + "uv run --project ~/.claude/magpie/vetted-ops vetted-op-git *", + "uvx --from ~/.claude/magpie/vetted-ops vetted-op-git *", "uv run --project ~/.claude/magpie/vetted-ops vetted-op *", "uvx --from ~/.claude/magpie/vetted-ops vetted-op *" ] diff --git a/tools/vetted-ops/pyproject.toml b/tools/vetted-ops/pyproject.toml index 3ad293a6d..5381537db 100644 --- a/tools/vetted-ops/pyproject.toml +++ b/tools/vetted-ops/pyproject.toml @@ -32,6 +32,7 @@ dependencies = [] vetted-op = "vetted_ops:main" vetted-op-read = "vetted_ops:main_read" vetted-op-tracker = "vetted_ops:main_tracker" +vetted-op-git = "vetted_ops.git_ops:main" vetted-ops-codex-rules = "vetted_ops.codex:main" [tool.hatch.build.targets.wheel] diff --git a/tools/vetted-ops/src/vetted_ops/codex.py b/tools/vetted-ops/src/vetted_ops/codex.py index d8715924a..ec62f8bdd 100644 --- a/tools/vetted-ops/src/vetted_ops/codex.py +++ b/tools/vetted-ops/src/vetted_ops/codex.py @@ -46,7 +46,7 @@ def render_rules(tool_root: Path) -> str: "# Generated by vetted-ops-codex-rules; review before installing.", ] for launcher in (("uv", "run", "--project"), ("uvx", "--from")): - for entry in ("vetted-op-read", "vetted-op", "vetted-op-tracker"): + for entry in ("vetted-op-read", "vetted-op", "vetted-op-tracker", "vetted-op-git"): pattern = [*launcher, base, entry] decision = "allow" if entry == "vetted-op-read" else "prompt" lines.append(f"prefix_rule(pattern = {json.dumps(pattern)}, decision = {json.dumps(decision)})") diff --git a/tools/vetted-ops/src/vetted_ops/config.py b/tools/vetted-ops/src/vetted_ops/config.py index 366f38e72..3040b79a5 100644 --- a/tools/vetted-ops/src/vetted_ops/config.py +++ b/tools/vetted-ops/src/vetted_ops/config.py @@ -166,6 +166,8 @@ class Config: #: The non-GitHub security tracker, when ``[tracker] platform`` selects one. #: ``None`` means GitHub: tracker operations run their ``gh`` builders. tracker_backend: TrackerBackend | None = None + #: The raw ``[git]`` table, validated by `git_ops.git_policy` for `vetted-op-git`. + git: object = None def as_mapping(self) -> dict[str, object]: """The mapping handed to an operation's ``build`` callable.""" @@ -421,6 +423,7 @@ def load(path: Path | None = None, *, cwd: Path | None = None, approved_only: bo endpoints=endpoints, callers=callers, tracker_backend=_tracker_backend(raw.get("tracker")), + git=raw.get("git"), ) @@ -435,6 +438,7 @@ def describe(config: Config) -> str: "endpoints": dict(sorted(config.endpoints.items())), "callers": {k: sorted(v) for k, v in sorted(config.callers.items())}, "tracker_backend": (dict(vars(config.tracker_backend)) if config.tracker_backend else "github"), + "git": config.git, }, indent=2, sort_keys=True, diff --git a/tools/vetted-ops/src/vetted_ops/git_ops.py b/tools/vetted-ops/src/vetted_ops/git_ops.py new file mode 100644 index 000000000..77dd49d1b --- /dev/null +++ b/tools/vetted-ops/src/vetted_ops/git_ops.py @@ -0,0 +1,918 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +""" +``vetted-op-git``: the git operations a sandboxed agent cannot run, as closed shapes. + +Three things a sandboxed session routinely cannot do, and used to hand to the +user as a command to paste: + +* **Push over SSH.** The sandbox routes network through an HTTP proxy, so an + SSH transport gets no TCP at all, and a hardware key's touch prompt cannot + reach the user from inside it. +* **Write a linked worktree's administrative directory.** Harnesses keep + ``.git/worktrees//`` read-only for worktrees the session did not + create, so moving such a worktree to a rebased commit fails half-way. +* **Add or remove a linked worktree**, for the same reason. + +Each operation here is one of those, with every parameter validated and every +target bounded by the approved policy's ``[git]`` table. The entry point runs +outside the sandbox and stays behind the harness's confirmation (``ask``), like +``vetted-op``: it removes the copy and paste, not the human decision. + +What makes running git outside the sandbox safe here, beyond the closed shapes: + +* **The pre-push checks run in the sandbox, not here.** A push never runs a + hook. Whatever a ``pre-push`` hook would run — ``.git/hooks/pre-push``, or a + hook manager reading its configuration from the working tree — is code the + agent can write, and running it here would run that code outside the + sandbox; the harness confirmation shows the push, not the code the hook + would execute. The caller runs the same checks inside the sandbox first + (for prek: ``prek run --hook-stage pre-push --from-ref --to-ref + ``), fixes what they report, and only then pushes. The checks still + run; they just run where working-tree code belongs. +* **No repository code runs.** Every operation switches hooks off + (``core.hooksPath=/dev/null``, plus ``--no-verify`` on the push), so neither + a ``pre-push`` nor a ``post-checkout`` hook can run code from the working + tree. +* **No repository configuration steers git.** A key that makes git run a + program, rewrite a URL, or pick credentials (``core.sshCommand``, + ``url.*.insteadOf``, ``filter.*``, ``core.fsmonitor``, ``include.path``, …) + can be planted in a repository's own config by anything that writes it. The + operation refuses to run when the local or worktree config holds any key + outside a short list of inert ones (`SAFE_LOCAL_KEY`). Global and system + configuration are the user's own and stay in effect, so an SSH wrapper or a + signing setup there keeps working. +* **No environment steers git.** Every ``GIT_*`` variable is dropped, and + ``HOME`` comes from the password database, so the global configuration read + is the account's own. +* **What is re-checked cannot change in between.** The configuration check + runs again right before the command that acts, and the keys that could start + a program in that window are pinned on the command line (`PINNED_CONFIG`, + ``core.sshCommand`` set to the user's global value, hooks off where they are + not wanted). Attributes come from the empty tree, so no ``.gitattributes`` + can switch on a filter. ``GIT_ALLOW_PROTOCOL`` limits transports whatever + the configuration says. Validated directories are opened without following + a symlink and git runs inside them by descriptor, so a directory swapped for + a symlink after the checks cannot redirect it. Git itself still finds a + repository's ``.git`` by name; its identity is re-checked, by name, right + before the acting command, and a linked worktree's validated git directory + is passed explicitly (``--git-dir``, ``--work-tree=.``) so its agent-writable + ``.git`` file is never read again. That the git directory cannot be swapped + in the moment between rests, like the next point, on the harness protecting + it. A rewrite + such as ``url.*.insteadOf`` cannot be + pinned away; that it cannot appear while the confirmed command runs rests on + the harness keeping ``.git/config`` write-protected, as Claude Code's sandbox + does. +* **The destination is not addressable.** A push goes to a URL built from the + policy's repository names, never to a remote the repository configures. + Protected branches are refused whatever the policy says, and the upstream + repository accepts only branches matching the policy's globs. +* **Nothing is lost silently.** A push always uses ``--force-with-lease`` with + the full SHA the caller expects the remote branch to have (or ``new``), and + a worktree moves with ``reset --keep`` only when it has no local changes; + the previous commit is printed and stays in the reflog. +""" + +from __future__ import annotations + +import argparse +import dataclasses +import fnmatch +import os +import re +import stat +import subprocess +import sys +from collections.abc import Callable, Sequence +from dataclasses import dataclass, field +from pathlib import Path + +from .config import Config, ConfigError, _expand_home, account_home, describe, load + +EXIT_OK = 0 +EXIT_USAGE = 2 +EXIT_POLICY = 3 +EXIT_COMMAND = 4 + +PROG = "vetted-op-git" + +#: A full object name. Short SHAs are refused: they can become ambiguous, and +#: the caller always has the full one from `git rev-parse` or the forge. +_SHA = re.compile(r"^(?:[0-9a-f]{40}|[0-9a-f]{64})$") +#: A branch name, before `git check-ref-format --branch` has its say. +_BRANCH = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._/+-]{0,199}$") +#: The last component of a new worktree's path. +_WORKTREE_NAME = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._+-]{0,99}$") +#: `owner/name`, as in `config._REPO`. +_REPO = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,100}/[A-Za-z0-9][A-Za-z0-9._-]{0,100}$") +_HOST = re.compile(r"^[A-Za-z0-9][A-Za-z0-9.-]{0,252}$") + +#: Branches no operation pushes to, whatever the policy adds or grants. +DEFAULT_PROTECTED = ( + "main", + "master", + "trunk", + "develop", + "gh-pages", + "release", + "release/*", + "release-*", + "v*-test", + "v*-stable", + "*-stable", + "asf-site", +) + +#: Repository-scope configuration keys that cannot make git run a program, +#: pick a credential, change a destination or transform file contents. Every +#: other key at `local` or `worktree` scope makes an operation refuse. +SAFE_LOCAL_KEY = re.compile( + r"""^(?: + core\.(?:repositoryformatversion|filemode|bare|logallrefupdates|ignorecase|precomposeunicode + |symlinks|autocrlf|eol|safecrlf|quotepath|abbrev|commitgraph|untrackedcache + |splitindex|multipackindex|sparsecheckout|sparsecheckoutcone|checkstat|trustctime) + | extensions\.(?:worktreeconfig|objectformat|refstorage|preciousobjects|partialclone|noop) + # A remote name without `:` or `/`: git applies the settings of a remote named exactly + # like the URL a push goes to, so a URL-shaped name could redirect it. + | remote\.[A-Za-z0-9._-]+\.(?:url|pushurl|fetch|tagopt|prune|prunetags|promisor|partialclonefilter + |mirror|skipdefaultupdate|skipfetchall|gh-resolved) + | branch\.[^\x00]+\.(?:remote|pushremote|merge|rebase|description|vscode-merge-base) + | user\.(?:name|email) + | (?:pull|fetch)\.(?:rebase|ff|prune|prunetags|parallel|writecommitgraph) + | push\.(?:default|autosetupremote|followtags) + | rerere\.(?:enabled|autoupdate) + | gc\.(?:auto|autopacklimit|autodetach|reflogexpire|reflogexpireunreachable|prunexpire|worktreepruneexpire) + | maintenance\.(?:auto|strategy|repo) + | index\.(?:version|threads|skiphash) + | feature\.(?:manyfiles|experimental) + | color\.[a-z.]+ + | advice\.[a-z]+ + | (?:commit|tag)\.gpgsign + | init\.defaultbranch + | merge\.conflictstyle + | diff\.(?:renames|algorithm|colormoved) + | log\.(?:date|decorate|follow) + | status\.(?:showuntrackedfiles|submodulesummary) + )$""", + re.VERBOSE, +) + + +class GitRefused(ValueError): + """A parameter or the repository state that the operation does not accept.""" + + +class GitFailed(RuntimeError): + """A git command that ran and failed.""" + + def __init__(self, argv: Sequence[str], returncode: int, stderr: str, stdout: str = "") -> None: + command = " ".join(a for a in argv if a != "-c" and "=" not in a) + super().__init__(f"{command} exited {returncode}") + self.returncode = returncode + self.stderr = stderr + #: A hook may explain its failure on stdout; it is shown with stderr. + self.stdout = stdout + + +@dataclass(frozen=True) +class GitPolicy: + """The validated ``[git]`` table of the policy.""" + + #: Main checkouts (their top-level directories) the operations may act on, + #: together with the linked worktrees that share their ``.git``. + checkouts: tuple[Path, ...] + upstream_repo: str + fork_repo: str | None = None + #: Globs of the branches a push may create or move on the upstream + #: repository. Empty: no push to upstream at all. + upstream_push: tuple[str, ...] = () + protected: tuple[str, ...] = DEFAULT_PROTECTED + #: Directories new linked worktrees may be created in (directly). + worktree_roots: tuple[Path, ...] = () + host: str = "github.com" + transport: str = "ssh" + + def push_url(self, repo: str) -> str: + if self.transport == "https": + return f"https://{self.host}/{repo}.git" + return f"git@{self.host}:{repo}.git" + + +def _absolute_real_dir(raw: object, key: str) -> Path: + if not isinstance(raw, str) or not raw or not _expand_home(raw).is_absolute(): + raise ConfigError(f"[git] {key} entries must be absolute paths (or start with ~/), got {raw!r}") + path = Path(os.path.abspath(_expand_home(raw))) + if str(path) != os.path.realpath(path): + raise ConfigError( + f"[git] {key} entry {raw!r} must be an absolute path with no symlink on it " + f"(its real location is {os.path.realpath(path)!r})" + ) + return path + + +def _str_list(table: dict[str, object], key: str) -> list[str]: + value = table.get(key, []) + if not isinstance(value, list) or not all(isinstance(v, str) and v for v in value): + raise ConfigError(f"[git] {key} must be a list of non-empty strings") + return list(value) + + +def git_policy(config: Config) -> GitPolicy: + """Validate the policy's ``[git]`` table; without one, every operation refuses.""" + table = config.git + if table is None: + raise ConfigError("the policy has no [git] table, so no git operation may run") + if not isinstance(table, dict): + raise ConfigError("[git] must be a table") + checkouts = tuple(_absolute_real_dir(raw, "checkouts") for raw in _str_list(table, "checkouts")) + if not checkouts: + raise ConfigError("[git] checkouts must name at least one main checkout") + fork = table.get("fork") + if fork is not None and (not isinstance(fork, str) or not _REPO.match(fork)): + raise ConfigError(f"[git] fork must be an 'owner/name' string, got {fork!r}") + host = table.get("host", "github.com") + if not isinstance(host, str) or not _HOST.match(host): + raise ConfigError(f"[git] host must be a host name, got {host!r}") + transport = table.get("transport", "ssh") + if transport not in ("ssh", "https"): + raise ConfigError(f"[git] transport must be 'ssh' or 'https', got {transport!r}") + return GitPolicy( + checkouts=checkouts, + upstream_repo=config.upstream_repo, + fork_repo=fork, + upstream_push=tuple(_str_list(table, "upstream_push")), + protected=DEFAULT_PROTECTED + tuple(_str_list(table, "protected")), + worktree_roots=tuple( + _absolute_real_dir(raw, "worktree_roots") for raw in _str_list(table, "worktree_roots") + ), + host=host, + transport=transport, + ) + + +# --- running git ----------------------------------------------------------- + + +def clean_env(environ: dict[str, str] | None = None) -> dict[str, str]: + """The caller's environment, minus everything that would let it reconfigure git. + + Every ``GIT_*`` variable is dropped (``GIT_DIR``, ``GIT_SSH_COMMAND``, + ``GIT_CONFIG_GLOBAL``, ``GIT_CONFIG_PARAMETERS``, …), and the global + configuration is pinned to the account's own: ``HOME`` comes from the + password database, never from the caller, and ``XDG_CONFIG_HOME`` is + dropped, so a configuration written somewhere the agent can write is never + read as the user's global one. What remains (``PATH``, ``SSH_AUTH_SOCK``, + ``GNUPGHOME``, …) is what the user's own git and ssh setup needs. + """ + source = os.environ if environ is None else environ + env = {k: v for k, v in source.items() if not k.startswith("GIT_") and k != "XDG_CONFIG_HOME"} + env["HOME"] = str(account_home()) + env["GIT_TERMINAL_PROMPT"] = "0" + return env + + +#: Runs ``argv`` with ``env``, in the directory open as ``cwd_fd`` when one is given. +Runner = Callable[[list[str], dict[str, str], "int | None"], "subprocess.CompletedProcess[str]"] + + +def _default_runner( + argv: list[str], env: dict[str, str], cwd_fd: int | None +) -> subprocess.CompletedProcess[str]: + if cwd_fd is None: + return subprocess.run(argv, check=False, capture_output=True, text=True, env=env) + return subprocess.run( + argv, + check=False, + capture_output=True, + text=True, + env=env, + pass_fds=(cwd_fd,), + preexec_fn=lambda: os.fchdir(cwd_fd), + ) + + +def open_dir(path: Path) -> int: + """Open ``path`` as a directory, refusing a symlink at any component. + + Walked one component at a time from ``/`` with ``O_NOFOLLOW``, so the + descriptor is the directory the name led to when it was checked. Git then + runs *in* that descriptor rather than at the name, and swapping a directory + on the path for a symlink afterwards (the agent can write inside a + checkout) cannot send git somewhere else. + """ + flags = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW + fd = os.open("/", os.O_RDONLY | os.O_DIRECTORY) + try: + for part in path.parts[1:]: + child = os.open(part, flags, dir_fd=fd) + os.close(fd) + fd = child + except OSError as exc: + os.close(fd) + raise GitRefused( + f"{str(path)!r} is not a directory reachable without a symlink: {exc.strerror}" + ) from None + return fd + + +#: Pinned on every call, so a key the repository's configuration gains between +#: `check_repository_config` and the command cannot take effect: no file-system +#: monitor program, no automatic gc or maintenance (their hooks are commands), +#: and only network transports (a local path would run that repository's +#: receive-pack and hooks here). The same pins as the local tracker's git. +PINNED_CONFIG = ("core.fsmonitor=false", "gc.auto=0", "maintenance.auto=false", "protocol.allow=never") + +#: The first git that honours ``GIT_ATTR_SOURCE``. +MIN_GIT_VERSION = (2, 42) + +#: The empty tree, per object format: attributes are read from it, so no +#: `.gitattributes` in the working tree can switch on a filter or driver. +EMPTY_TREE = { + "sha1": "4b825dc642cb6eb9a060e54bf8d69288fbee4904", + "sha256": "6ef19b41225c5369f1c104d45d8d85efa9b057b53b14b4b9b939dd74decc5321", +} + + +@dataclass +class Git: + """Runs git with the pins above; injectable for tests.""" + + runner: Runner = field(default=_default_runner) + #: Transports a push may use. Tests add ``file``; production cannot. + protocols: tuple[str, ...] = ("https", "ssh") + #: The user's global ``core.sshCommand`` (or plain ``ssh``), pinned on every + #: call so the repository's configuration cannot replace it. + _ssh_command: str | None = field(default=None, repr=False) + #: Set once the object format is known (see `check_repository_config`). + attr_source: str | None = None + #: Validated directories, open (see `open_dir`); git runs in these, never at the name. + anchors: dict[Path, int] = field(default_factory=dict) + #: Validated working tree -> its git directory. Git gets these explicitly + #: (``--git-dir``, ``--work-tree=.``) and never reads the ``.git`` file of a + #: linked worktree again: that file is in the tree the agent can write. + git_dirs: dict[Path, Path] = field(default_factory=dict) + + def anchor(self, path: Path, fd: int | None = None) -> int: + """Return the open descriptor for ``path``, opening it on first use. + + Takes ownership of a passed ``fd``: it is kept until `close`, or closed + at once when ``path`` already has a descriptor. + """ + if path in self.anchors: + if fd is not None and fd != self.anchors[path]: + os.close(fd) + else: + self.anchors[path] = open_dir(path) if fd is None else fd + return self.anchors[path] + + def close(self) -> None: + for fd in self.anchors.values(): + os.close(fd) + self.anchors.clear() + + def check_version(self) -> None: + """Refuse a git older than `MIN_GIT_VERSION`, which ignores ``GIT_ATTR_SOURCE``.""" + found = self.runner(["git", "version"], clean_env(), None) + match = re.search(r"(\d+)\.(\d+)", found.stdout or "") + version = (int(match.group(1)), int(match.group(2))) if match else (0, 0) + if found.returncode != 0 or version < MIN_GIT_VERSION: + raise GitRefused( + f"git {'.'.join(map(str, MIN_GIT_VERSION))} or later is required (found " + f"{(found.stdout or '').strip() or 'none'}): an older git ignores GIT_ATTR_SOURCE, so a " + ".gitattributes could switch on a filter outside the sandbox" + ) + + def ssh_command(self) -> str: + if self._ssh_command is None: + argv = ["git", "config", "--global", "--get", "core.sshCommand"] + found = self.runner(argv, clean_env(), None) + value = found.stdout.strip() if found.returncode == 0 else "" + self._ssh_command = value if value and "\n" not in value else "ssh" + return self._ssh_command + + def argv(self, directory: Path, *args: str, hooks: bool = False) -> list[str]: + """A git command in ``directory``, with hooks switched off unless ``hooks``. + + An anchored directory is entered by descriptor (see `open_dir`), so the + argv names it only when it is not anchored (dry runs print the name). + """ + pins = [*PINNED_CONFIG, *(f"protocol.{p}.allow=always" for p in self.protocols)] + pins.append(f"core.sshCommand={self.ssh_command()}") + if not hooks: + pins.append("core.hooksPath=/dev/null") + where = [] if directory in self.anchors else ["-C", str(directory)] + if directory in self.git_dirs: + where += [f"--git-dir={self.git_dirs[directory]}", "--work-tree=."] + return ["git", *(arg for pin in pins for arg in ("-c", pin)), *where, *args] + + def _env(self) -> dict[str, str]: + env = clean_env() + # Overrides every protocol.* setting, the repository's included. + env["GIT_ALLOW_PROTOCOL"] = ":".join(self.protocols) + if self.attr_source is not None: + env["GIT_ATTR_SOURCE"] = self.attr_source + return env + + def _call( + self, directory: Path, *args: str, hooks: bool = False + ) -> tuple[list[str], subprocess.CompletedProcess[str]]: + argv = self.argv(directory, *args, hooks=hooks) + return argv, self.runner(argv, self._env(), self.anchors.get(directory)) + + def run(self, directory: Path, *args: str, hooks: bool = False) -> str: + argv, completed = self._call(directory, *args, hooks=hooks) + if completed.returncode != 0: + raise GitFailed(argv, completed.returncode, completed.stderr or "", completed.stdout or "") + return completed.stdout + + def ok(self, directory: Path, *args: str) -> bool: + return self._call(directory, *args)[1].returncode == 0 + + +# --- validation ------------------------------------------------------------ + + +def _param(raw: str, name: str) -> str: + if not raw or raw.startswith("-") or "\x00" in raw or "\n" in raw: + raise GitRefused(f"parameter {name!r} may not be empty, start with '-' or span lines: {raw!r}") + return raw + + +def sha(raw: str, name: str) -> str: + if not _SHA.match(_param(raw, name)): + raise GitRefused(f"{name} must be a full lowercase commit SHA, got {raw!r}") + return raw + + +def branch_name(git: Git, directory: Path, raw: str, name: str) -> str: + _param(raw, name) + if not _BRANCH.match(raw) or ".." in raw or raw.endswith((".lock", "/", ".")): + raise GitRefused(f"{name} is not an acceptable branch name: {raw!r}") + if not git.ok(directory, "check-ref-format", "--branch", raw): + raise GitRefused(f"{name} is not a valid branch name: {raw!r}") + return raw + + +def is_protected(branch: str, policy: GitPolicy) -> bool: + return any(fnmatch.fnmatchcase(branch, glob) for glob in policy.protected) + + +def _absolute(raw: str, name: str) -> Path: + expanded = _expand_home(_param(raw, name)) + if not expanded.is_absolute(): + raise GitRefused(f"{name} must be an absolute path (or start with ~/), got {raw!r}") + return Path(os.path.abspath(expanded)) + + +def _real_dir(raw: str, name: str) -> Path: + path = _absolute(raw, name) + if str(path) != os.path.realpath(path): + raise GitRefused(f"{name} {raw!r} has a symlink on its path; name its real location") + return path + + +@dataclass(frozen=True) +class Worktree: + """A working tree of one of the policy's checkouts.""" + + path: Path + checkout: Path + #: (device, inode) of the checkout's `.git` directory when it was validated. + git_dir_id: tuple[int, int] = (0, 0) + #: The worktree's own git directory: `.git` for the main checkout, the + #: registered `.git/worktrees/` for a linked one. + git_dir: Path = Path("/nonexistent") + + @property + def linked(self) -> bool: + return self.path != self.checkout + + +def resolve_worktree(git: Git, raw: str, policy: GitPolicy, name: str = "worktree") -> Worktree: + """The working tree at ``raw``, if it is a policy checkout or one of its linked worktrees.""" + path = _real_dir(raw, name) + if not path.is_dir(): + raise GitRefused(f"{name} {str(path)!r} is not a directory") + git.anchor(path) + lines = git.run(path, "rev-parse", "--path-format=absolute", "--show-toplevel", "--git-common-dir") + top, common = (Path(os.path.realpath(line)) for line in lines.splitlines()[:2]) + if top != path: + raise GitRefused(f"{name} {str(path)!r} is not the top of a working tree (that is {str(top)!r})") + for checkout in policy.checkouts: + if common == checkout / ".git" and (checkout / ".git").is_dir(): + git.anchor(checkout) + worktree = Worktree(path=path, checkout=checkout, git_dir_id=git_dir_identity(checkout)) + worktree = _check_registered(git, worktree, name) + git.git_dirs[path] = worktree.git_dir + git.git_dirs.setdefault(checkout, checkout / ".git") + return worktree + allowed = ", ".join(str(c) for c in policy.checkouts) + raise GitRefused(f"{name} {str(path)!r} does not belong to a checkout the policy names ({allowed})") + + +def git_dir_identity(checkout: Path) -> tuple[int, int]: + """The checkout's `.git`, looked up by name now, with no symlink anywhere on the way. + + Looked up afresh each time rather than through an anchor, so a directory + swapped anywhere on the path since the last look shows as a different one. + """ + fd = open_dir(checkout) + try: + found = os.stat(".git", dir_fd=fd, follow_symlinks=False) + except OSError as exc: + raise GitRefused(f"cannot read {str(checkout / '.git')!r}: {exc.strerror}") from None + finally: + os.close(fd) + if not stat.S_ISDIR(found.st_mode): + raise GitRefused(f"{str(checkout / '.git')!r} is not a directory") + return (found.st_dev, found.st_ino) + + +def _check_registered(git: Git, worktree: Worktree, name: str) -> Worktree: + """A linked worktree must be one git registered for this path, not a copy pointing at `.git`.""" + git_dir = Path(os.path.realpath(git.run(worktree.path, "rev-parse", "--absolute-git-dir").strip())) + main = worktree.checkout / ".git" + if not worktree.linked: + if git_dir != main: + raise GitRefused(f"{name} {str(worktree.path)!r} does not use {str(main)!r} as its git directory") + return dataclasses.replace(worktree, git_dir=main) + if git_dir.parent != main / "worktrees": + raise GitRefused( + f"{name} {str(worktree.path)!r} is not a linked worktree registered with {str(main)!r}" + ) + try: + registered = (git_dir / "gitdir").read_text().strip() + except OSError: + registered = "" + if Path(os.path.realpath(registered)) != worktree.path / ".git": + raise GitRefused(f"{name} {str(worktree.path)!r} is not where git registered {git_dir.name!r}") + return dataclasses.replace(worktree, git_dir=git_dir) + + +def parse_config_scopes(output: str) -> list[tuple[str, str]]: + """``git config --list --show-scope --name-only -z`` output as (scope, key) pairs.""" + items = [item for item in output.split("\x00") if item] + pairs: list[tuple[str, str]] = [] + pending: str | None = None + for item in items: + if "\t" in item: + scope, key = item.split("\t", 1) + pairs.append((scope, key)) + elif pending is None: + pending = item + else: + pairs.append((pending, item)) + pending = None + return pairs + + +def check_repository_config(git: Git, worktree: Worktree) -> None: + """Refuse a repository whose own configuration holds a key outside `SAFE_LOCAL_KEY`. + + Checked in every working tree an operation runs git in (a linked worktree + has its own ``config.worktree``), and again right before the command that + acts, so a key added after the first check is still caught; what cannot + be re-checked in between is pinned by `PINNED_CONFIG`. + """ + git.check_version() + if git_dir_identity(worktree.checkout) != worktree.git_dir_id: + raise GitRefused(f"{str(worktree.checkout / '.git')!r} changed since it was validated") + # A linked worktree's common directory comes from its `commondir` file, which + # can be rewritten after `resolve_worktree` looked: ask git again, through the + # same pinned git directory the command will use, and require the same answer. + lines = git.run( + worktree.path, "rev-parse", "--path-format=absolute", "--git-common-dir", "--absolute-git-dir" + ) + common, git_dir = (Path(os.path.realpath(line)) for line in lines.splitlines()[:2]) + if common != worktree.checkout / ".git": + raise GitRefused( + f"the common git directory of {str(worktree.path)!r} is now {str(common)!r}, " + f"not {str(worktree.checkout / '.git')!r}" + ) + if git_dir != worktree.git_dir: + raise GitRefused(f"the git directory of {str(worktree.path)!r} changed since it was validated") + for directory in dict.fromkeys((worktree.path, worktree.checkout)): + _check_config_in(git, directory) + object_format = git.run(worktree.path, "rev-parse", "--show-object-format").strip() + if object_format not in EMPTY_TREE: + raise GitRefused(f"unsupported object format {object_format!r}") + git.attr_source = EMPTY_TREE[object_format] + + +def _check_config_in(git: Git, directory: Path) -> None: + output = git.run(directory, "config", "--list", "--show-scope", "--name-only", "--includes", "-z") + unsafe = sorted( + { + key + for scope, key in parse_config_scopes(output) + # `command` scope is this module's own `-c` pins; `GIT_CONFIG_*` is dropped. + if scope in ("local", "worktree") and not SAFE_LOCAL_KEY.match(key.lower()) + } + ) + if unsafe: + raise GitRefused( + f"the repository configuration of {str(directory)!r} sets {', '.join(unsafe)}; " + "git runs outside the sandbox here, so only inert repository settings are accepted. " + "Move those settings to your global git configuration, or remove them, and retry" + ) + + +def resolve_commit(git: Git, directory: Path, commit: str, name: str) -> str: + if not git.ok(directory, "cat-file", "-e", f"{commit}^{{commit}}"): + raise GitRefused(f"{name} {commit} is not a commit in this repository") + return commit + + +# --- operations ------------------------------------------------------------ + + +@dataclass(frozen=True) +class GitOp: + name: str + params: tuple[str, ...] + summary: str + run: Callable[[Git, GitPolicy, dict[str, str], bool], str] + + +def _refuse_empty_branch(git: Git, worktree: Worktree, commit: str, local: str) -> None: + """The agent-guard `empty-rebase` rule, for the push this dispatcher runs. + + Moving an existing branch to a commit with nothing over a default branch + (a rebase that dropped every commit) closes the pull request it heads and + revokes maintainers' push access to it. The bases are the remotes' default + branches (`refs/remotes/*/HEAD`); with none known, nothing is refused, as + in the guard. There is no override: closing a pull request is not a push. + """ + heads = git.run(worktree.path, "for-each-ref", "--format=%(symref)", "refs/remotes/*/HEAD") + for base in sorted({line for line in heads.splitlines() if line}): + if git.run(worktree.path, "rev-list", "--count", f"{base}..{commit}").strip() == "0": + raise GitRefused( + f"{local!r} has no commits over {base.removeprefix('refs/remotes/')}; force-pushing it " + "would empty the branch, which closes a pull request it heads. Check the rebase result" + ) + + +def push_branch(git: Git, policy: GitPolicy, p: dict[str, str], dry_run: bool) -> str: + """Push a local branch's commit to the fork or upstream, with a lease on the expected SHA.""" + worktree = resolve_worktree(git, p["checkout"], policy, "checkout") + check_repository_config(git, worktree) + local = branch_name(git, worktree.path, p["branch"], "branch") + remote_branch = branch_name(git, worktree.path, p["remote_branch"], "remote_branch") + if is_protected(remote_branch, policy): + raise GitRefused(f"{remote_branch!r} is a protected branch; no operation pushes to it") + target = _param(p["target"], "target") + if target == "fork": + if policy.fork_repo is None: + raise GitRefused("the policy names no [git] fork, so nothing may be pushed to one") + repo = policy.fork_repo + elif target == "upstream": + if not any(fnmatch.fnmatchcase(remote_branch, glob) for glob in policy.upstream_push): + raise GitRefused( + f"{remote_branch!r} matches no [git] upstream_push glob " + f"({', '.join(policy.upstream_push) or 'none declared'}), so it may not be pushed upstream" + ) + repo = policy.upstream_repo + else: + raise GitRefused(f"target must be 'fork' or 'upstream', got {target!r}") + expected = p["expected"] + lease = "" if expected == "new" else sha(expected, "expected") + if not git.ok(worktree.path, "show-ref", "--verify", "--quiet", f"refs/heads/{local}"): + raise GitRefused(f"there is no local branch {local!r}") + commit = git.run(worktree.path, "rev-parse", "--verify", f"refs/heads/{local}^{{commit}}").strip() + if lease: + _refuse_empty_branch(git, worktree, commit, local) + args = [ + "push", + # The pre-push checks run in the sandbox before this call (see the module + # docstring): a hook here would run working-tree code outside it. + "--no-verify", + # Only the one ref: `push.followTags` would also publish reachable tags. + "--no-follow-tags", + "--porcelain", + f"--force-with-lease=refs/heads/{remote_branch}:{lease}", + policy.push_url(repo), + f"{commit}:refs/heads/{remote_branch}", + ] + if dry_run: + return " ".join(git.argv(worktree.path, *args)) + check_repository_config(git, worktree) + git.run(worktree.path, *args) + was = "created" if not lease else f"was {lease}" + return f"pushed {commit} to {repo} {remote_branch} ({was})" + + +def worktree_sync(git: Git, policy: GitPolicy, p: dict[str, str], dry_run: bool) -> str: + """Move a clean linked worktree's branch to a commit (``reset --keep``).""" + worktree = resolve_worktree(git, p["worktree"], policy) + if not worktree.linked: + raise GitRefused("worktree-sync moves linked worktrees only; this is the main checkout") + check_repository_config(git, worktree) + commit = resolve_commit(git, worktree.path, sha(p["commit"], "commit"), "commit") + if not git.ok(worktree.path, "symbolic-ref", "--quiet", "HEAD"): + raise GitRefused(f"{str(worktree.path)!r} has a detached HEAD; check out its branch first") + branch = git.run(worktree.path, "symbolic-ref", "--short", "HEAD").strip() + if git.run(worktree.path, "status", "--porcelain", "--untracked-files=no").strip(): + raise GitRefused(f"{str(worktree.path)!r} has uncommitted changes; commit or set them aside first") + previous = git.run(worktree.path, "rev-parse", "HEAD").strip() + args = ["reset", "--keep", commit] + if dry_run: + return " ".join(git.argv(worktree.path, *args)) + check_repository_config(git, worktree) + git.run(worktree.path, *args) + return f"moved {branch} in {worktree.path} from {previous} to {commit}" + + +def worktree_add(git: Git, policy: GitPolicy, p: dict[str, str], dry_run: bool) -> str: + """Create a linked worktree on a new branch, inside a policy worktree root.""" + checkout = resolve_worktree(git, p["checkout"], policy, "checkout") + if checkout.linked: + raise GitRefused("checkout must be the main checkout, not a linked worktree") + check_repository_config(git, checkout) + path = _absolute(p["path"], "path") + if not _WORKTREE_NAME.match(path.name): + raise GitRefused(f"the new worktree's directory name is not acceptable: {path.name!r}") + if not any( + path.parent == root and str(root) == os.path.realpath(path.parent) for root in policy.worktree_roots + ): + roots = ", ".join(str(r) for r in policy.worktree_roots) or "none declared" + raise GitRefused(f"{str(path)!r} is not directly inside a [git] worktree_roots directory ({roots})") + if os.path.lexists(path): + raise GitRefused(f"{str(path)!r} already exists") + branch = branch_name(git, checkout.path, p["branch"], "branch") + if git.ok(checkout.path, "show-ref", "--verify", "--quiet", f"refs/heads/{branch}"): + raise GitRefused(f"branch {branch!r} already exists; worktree-add creates a new one") + start = resolve_commit(git, checkout.path, sha(p["start"], "start"), "start") + if dry_run: + return " ".join(git.argv(checkout.path, "worktree", "add", "-b", branch, str(path), start)) + check_repository_config(git, checkout) + # Created through the root's descriptor and entered by descriptor, then + # added as `.`: a root swapped for a symlink after the checks above still + # cannot make git write anywhere but this new, empty directory. (Git names + # its administrative directory after the path given, so it is `-` here.) + root_fd = open_dir(path.parent) + try: + os.mkdir(path.name, 0o777, dir_fd=root_fd) + new_fd = os.open(path.name, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=root_fd) + git.anchor(path, new_fd) + try: + git.run( + path, f"--git-dir={checkout.checkout / '.git'}", "worktree", "add", "-b", branch, ".", start + ) + except GitFailed: + os.rmdir(path.name, dir_fd=root_fd) + raise + finally: + os.close(root_fd) + return f"created {path} on new branch {branch} at {start}" + + +def worktree_remove(git: Git, policy: GitPolicy, p: dict[str, str], dry_run: bool) -> str: + """Remove a linked worktree that has no changes (never ``--force``).""" + worktree = resolve_worktree(git, p["worktree"], policy) + if not worktree.linked: + raise GitRefused("worktree-remove removes linked worktrees only; this is the main checkout") + check_repository_config(git, worktree) + args = ["worktree", "remove", str(worktree.path)] + if dry_run: + return " ".join(git.argv(worktree.checkout, *args)) + # Without --force git itself refuses a worktree with modified or untracked files. + check_repository_config(git, worktree) + git.run(worktree.checkout, *args) + return f"removed {worktree.path}" + + +OPS: dict[str, GitOp] = { + op.name: op + for op in ( + GitOp( + "git-push-branch", + ("checkout", "branch", "target", "remote_branch", "expected"), + "push local to of the fork or upstream; is the " + "remote branch's current full SHA, or 'new'. No hook runs: run the pre-push checks " + "in the sandbox first", + push_branch, + ), + GitOp( + "git-worktree-sync", + ("worktree", "commit"), + "move a clean linked worktree's branch to (reset --keep)", + worktree_sync, + ), + GitOp( + "git-worktree-add", + ("checkout", "path", "branch", "start"), + "create a linked worktree at on a new starting at ", + worktree_add, + ), + GitOp( + "git-worktree-remove", + ("worktree",), + "remove a linked worktree that has no changes", + worktree_remove, + ), + ) +} + + +def main(argv: list[str] | None = None, *, git: Git | None = None) -> int: + """The ``vetted-op-git`` console script.""" + raw = list(sys.argv[1:] if argv is None else argv) + parser = argparse.ArgumentParser( + prog=PROG, + description="Run one fixed, policy-scoped git operation outside the sandbox. No pass-through arguments.", + ) + parser.add_argument("--caller", help="the skill or plugin invoking this operation") + parser.add_argument("--dry-run", action="store_true", help="validate, print the git command, run nothing") + parser.add_argument("operation", nargs="?", help="operation name, or 'list-ops' / 'policy'") + parser.add_argument("params", nargs="*", help="operation parameters, positionally") + args = parser.parse_args(raw) + + if args.operation in (None, "list-ops"): + for name, entry in sorted(OPS.items()): + print(f"write {name:<22} {' '.join(entry.params)}\n {entry.summary}") + return EXIT_OK + + if sum(1 for a in raw if a == "--caller" or a.startswith("--caller=")) > 1: + print(f"{PROG}: refused: --caller given more than once", file=sys.stderr) + return EXIT_POLICY + + # Like every entry point that runs outside the sandbox: only a policy the user + # placed in the approved directory themselves drives git. A dry run against + # one that is not approved yet still checks its parameters, but runs no git + # command at all: even read-only git, out here, is steered by that policy. + approved = True + try: + try: + config = load(approved_only=args.operation != "policy") + except ConfigError: + if not args.dry_run: + raise + config = load(approved_only=False) + approved = False + policy = git_policy(config) + except ConfigError as exc: + print(f"{PROG}: config error: {exc}", file=sys.stderr) + return EXIT_POLICY + + if args.operation == "policy": + print(describe(config)) + return EXIT_OK + + if not args.caller: + print(f"{PROG}: --caller is required for any operation", file=sys.stderr) + return EXIT_USAGE + + op = OPS.get(args.operation) + try: + if op is None: + raise GitRefused(f"unknown operation {args.operation!r}; see '{PROG} list-ops'") + permitted = config.ops_for(args.caller) + if op.name not in permitted: + raise GitRefused( + f"caller {args.caller!r} is not permitted to run {op.name!r}; " + f"permitted: {', '.join(sorted(permitted)) or '(none)'}" + ) + if len(args.params) != len(op.params): + raise GitRefused( + f"operation {op.name!r} takes {len(op.params)} parameter(s) ({', '.join(op.params)}), " + f"got {len(args.params)}" + ) + params = dict(zip(op.params, args.params, strict=True)) + for name, value in params.items(): + _param(value, name) + if not approved: + print( + f"{PROG}: dry run against a policy that is not approved: the parameters are well formed; " + "no git command was run. Approve the policy to see the command it would run." + ) + return EXIT_OK + runner = git or Git() + try: + print(op.run(runner, policy, params, args.dry_run)) + finally: + runner.close() + except (GitRefused, ConfigError) as exc: + print(f"{PROG}: refused: {exc}", file=sys.stderr) + return EXIT_POLICY + except GitFailed as exc: + sys.stderr.write(exc.stdout) + sys.stderr.write(exc.stderr) + print(f"{PROG}: {op.name if op else args.operation} failed: {exc}", file=sys.stderr) + return EXIT_COMMAND + return EXIT_OK diff --git a/tools/vetted-ops/tests/test_codex.py b/tools/vetted-ops/tests/test_codex.py index e2760c5aa..b7f492875 100644 --- a/tools/vetted-ops/tests/test_codex.py +++ b/tools/vetted-ops/tests/test_codex.py @@ -37,7 +37,8 @@ def test_rules_keep_stable_path_and_never_allow_writes(tmp_path: Path) -> None: text = render_rules(stable) assert str(target) not in text assert text.count('decision = "allow"') == 2 - assert text.count('decision = "prompt"') == 4 + assert text.count('decision = "prompt"') == 6 + assert '"vetted-op-git"], decision = "prompt"' in text assert str(stable) in text diff --git a/tools/vetted-ops/tests/test_git_ops.py b/tools/vetted-ops/tests/test_git_ops.py new file mode 100644 index 000000000..2bda4234d --- /dev/null +++ b/tools/vetted-ops/tests/test_git_ops.py @@ -0,0 +1,751 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +"""`vetted-op-git` against real repositories in a temporary directory.""" + +from __future__ import annotations + +import dataclasses +import os +import subprocess +from collections.abc import Callable +from dataclasses import dataclass +from pathlib import Path + +import pytest + +from vetted_ops import git_ops +from vetted_ops.config import Config, ConfigError, account_home +from vetted_ops.git_ops import Git, GitPolicy, GitRefused + + +def _git(directory: Path, *args: str) -> str: + env = git_ops.clean_env() + env.update( + GIT_AUTHOR_NAME="t", + GIT_AUTHOR_EMAIL="t@example.org", + GIT_COMMITTER_NAME="t", + GIT_COMMITTER_EMAIL="t@example.org", + GIT_CONFIG_GLOBAL=os.devnull, + ) + return subprocess.run( + ["git", "-c", "commit.gpgsign=false", "-C", str(directory), *args], + check=True, + capture_output=True, + text=True, + env=env, + ).stdout.strip() + + +def _commit(directory: Path, name: str) -> str: + (directory / name).write_text(name) + _git(directory, "add", name) + _git(directory, "commit", "-q", "-m", name) + return _git(directory, "rev-parse", "HEAD") + + +@dataclass(frozen=True) +class LocalPolicy(GitPolicy): + """Pushes to bare repositories on disk instead of a forge.""" + + remotes: Path = Path("/nonexistent") + + def push_url(self, repo: str) -> str: + return str(self.remotes / f"{repo.replace('/', '__')}.git") + + +@pytest.fixture +def git() -> Git: + return Git(runner=_runner(os.devnull), protocols=("https", "ssh", "file")) + + +def _runner(global_config: str) -> git_ops.Runner: + def runner(argv: list[str], env: dict[str, str], cwd_fd: int | None) -> subprocess.CompletedProcess[str]: + return git_ops._default_runner(argv, {**env, "GIT_CONFIG_GLOBAL": global_config}, cwd_fd) + + return runner + + +@pytest.fixture +def repo(tmp_path: Path) -> Path: + root = Path(os.path.realpath(tmp_path)) + checkout = root / "checkout" + checkout.mkdir() + _git(checkout, "init", "-q", "-b", "main") + _commit(checkout, "one") + (root / "worktrees").mkdir() + remotes = root / "remotes" + remotes.mkdir() + for name in ("me__project", "acme__project"): + _git(remotes, "init", "-q", "--bare", f"{name}.git") + return checkout + + +@pytest.fixture +def policy(repo: Path) -> LocalPolicy: + root = repo.parent + return LocalPolicy( + checkouts=(repo,), + upstream_repo="acme/project", + fork_repo="me/project", + upstream_push=("feature-*",), + worktree_roots=(root / "worktrees",), + remotes=root / "remotes", + ) + + +def _remote_head(policy: LocalPolicy, repo: str, branch: str) -> str: + return _git(Path(policy.push_url(repo)), "rev-parse", f"refs/heads/{branch}") + + +def _push( + git: Git, + policy: GitPolicy, + repo: Path, + branch: str, + target: str, + remote_branch: str, + expected: str, + dry_run: bool = False, +) -> str: + return git_ops.push_branch( + git, + policy, + { + "checkout": str(repo), + "branch": branch, + "target": target, + "remote_branch": remote_branch, + "expected": expected, + }, + dry_run, + ) + + +def test_push_creates_then_moves_a_branch_under_a_lease(git: Git, policy: LocalPolicy, repo: Path) -> None: + _git(repo, "checkout", "-q", "-b", "topic") + first = _commit(repo, "two") + assert "created" in _push(git, policy, repo, "topic", "fork", "topic", "new") + assert _remote_head(policy, "me/project", "topic") == first + + _git(repo, "commit", "-q", "--amend", "-m", "rewritten") + rewritten = _git(repo, "rev-parse", "HEAD") + _push(git, policy, repo, "topic", "fork", "topic", first) + assert _remote_head(policy, "me/project", "topic") == rewritten + + +def test_push_refuses_when_the_remote_moved(git: Git, policy: LocalPolicy, repo: Path) -> None: + _git(repo, "checkout", "-q", "-b", "topic") + first = _commit(repo, "two") + _push(git, policy, repo, "topic", "fork", "topic", "new") + second = _commit(repo, "three") + + with pytest.raises(git_ops.GitFailed): + _push(git, policy, repo, "topic", "fork", "topic", "0" * 40) + assert _remote_head(policy, "me/project", "topic") == first + _push(git, policy, repo, "topic", "fork", "topic", first) + assert _remote_head(policy, "me/project", "topic") == second + + +@pytest.mark.parametrize( + ("target", "remote_branch", "message"), + [ + pytest.param("fork", "main", "protected", id="protected-on-fork"), + pytest.param("upstream", "v3-1-test", "protected", id="protected-release-branch"), + pytest.param("upstream", "topic", "upstream_push", id="upstream-outside-globs"), + pytest.param("elsewhere", "topic", "target must be", id="unknown-target"), + ], +) +def test_push_refuses_destinations_outside_the_policy( + git: Git, policy: LocalPolicy, repo: Path, target: str, remote_branch: str, message: str +) -> None: + _git(repo, "branch", "topic") + with pytest.raises(GitRefused, match=message): + _push(git, policy, repo, "topic", target, remote_branch, "new") + + +def test_push_to_upstream_inside_the_globs(git: Git, policy: LocalPolicy, repo: Path) -> None: + _git(repo, "branch", "feature-x") + _push(git, policy, repo, "feature-x", "upstream", "feature-x", "new") + assert _remote_head(policy, "acme/project", "feature-x") == _git(repo, "rev-parse", "feature-x") + + +@pytest.mark.parametrize( + ("key", "value"), + [ + ("core.sshCommand", "touch /tmp/pwned"), + ("url.file:///tmp/evil.insteadOf", "git@github.com:"), + ("filter.x.smudge", "touch /tmp/pwned"), + ("core.fsmonitor", "touch /tmp/pwned"), + ("remote.origin.receivepack", "touch /tmp/pwned"), + ("include.path", "/tmp/elsewhere"), + ("core.hooksPath", "/tmp/hooks"), + ], +) +def test_repository_config_that_steers_git_is_refused( + git: Git, policy: LocalPolicy, repo: Path, key: str, value: str +) -> None: + _git(repo, "branch", "topic") + _git(repo, "config", key, value) + with pytest.raises(GitRefused, match="repository configuration"): + _push(git, policy, repo, "topic", "fork", "topic", "new") + + +def test_the_main_checkouts_worktree_config_is_checked_for_a_linked_worktree( + git: Git, policy: LocalPolicy, repo: Path +) -> None: + start = _git(repo, "rev-parse", "HEAD") + path = policy.worktree_roots[0] / "wt" + git_ops.worktree_add( + git, policy, {"checkout": str(repo), "path": str(path), "branch": "t", "start": start}, False + ) + _git(repo, "config", "extensions.worktreeConfig", "true") + _git(repo, "config", "--worktree", "core.sshCommand", "touch /tmp/pwned") + with pytest.raises(GitRefused, match=r"core\.sshcommand"): + git_ops.worktree_remove(git, policy, {"worktree": str(path)}, False) + assert path.exists() + + +def test_config_added_after_the_first_check_is_caught_before_the_command( + git: Git, policy: LocalPolicy, repo: Path +) -> None: + _git(repo, "branch", "topic") + checks = 0 + real_runner = git.runner + + def runner(argv: list[str], env: dict[str, str], cwd_fd: int | None) -> subprocess.CompletedProcess[str]: + nonlocal checks + if "--show-scope" in argv: + checks += 1 + if checks == 2: + _git(repo, "config", "core.sshCommand", "touch /tmp/pwned") + return real_runner(argv, env, cwd_fd) + + with pytest.raises(GitRefused, match=r"core\.sshcommand"): + _push(Git(runner=runner, protocols=git.protocols), policy, repo, "topic", "fork", "topic", "new") + with pytest.raises(subprocess.CalledProcessError): + _remote_head(policy, "me/project", "topic") + + +def test_every_git_call_carries_the_pins(git: Git, repo: Path) -> None: + argv = git.argv(repo, "status", hooks=True) + for pin in (*git_ops.PINNED_CONFIG, "core.sshCommand=ssh", "protocol.ssh.allow=always"): + assert pin in argv + assert "core.hooksPath=/dev/null" not in argv + assert "core.hooksPath=/dev/null" in git.argv(repo, "status") + + +def test_ssh_command_is_pinned_to_the_users_global_one(repo: Path, tmp_path: Path) -> None: + global_config = tmp_path / "gitconfig" + global_config.write_text("[core]\n\tsshCommand = my-ssh-wrapper\n") + git = Git(runner=_runner(str(global_config))) + assert "core.sshCommand=my-ssh-wrapper" in git.argv(repo, "status") + + +def test_a_local_transport_is_refused_in_production(policy: LocalPolicy, repo: Path) -> None: + _git(repo, "branch", "topic") + with pytest.raises(git_ops.GitFailed): + _push(Git(runner=_runner(os.devnull)), policy, repo, "topic", "fork", "topic", "new") + + +def test_reachable_tags_are_not_pushed(git: Git, policy: LocalPolicy, repo: Path) -> None: + _git(repo, "config", "push.followTags", "true") + _git(repo, "tag", "-a", "v1", "-m", "v1") + _git(repo, "branch", "topic") + _push(git, policy, repo, "topic", "fork", "topic", "new") + with pytest.raises(subprocess.CalledProcessError): + _git(Path(policy.push_url("me/project")), "rev-parse", "refs/tags/v1") + + +def test_attributes_cannot_switch_on_a_filter(policy: LocalPolicy, repo: Path, tmp_path: Path) -> None: + marker = tmp_path / "filter-ran" + global_config = tmp_path / "gitconfig" + global_config.write_text(f'[filter "x"]\n\tsmudge = touch {marker}; cat\n') + (repo / ".gitattributes").write_text("* filter=x\n") + _git(repo, "add", ".gitattributes") + _git(repo, "commit", "-q", "-m", "attributes") + start = _git(repo, "rev-parse", "HEAD") + git = Git(runner=_runner(str(global_config)), protocols=("https", "ssh", "file")) + path = policy.worktree_roots[0] / "wt" + git_ops.worktree_add( + git, policy, {"checkout": str(repo), "path": str(path), "branch": "t", "start": start}, False + ) + assert path.exists() + assert not marker.exists() + + +def test_clean_env_takes_home_from_the_account_and_drops_xdg() -> None: + env = git_ops.clean_env({"HOME": "/tmp/fake", "XDG_CONFIG_HOME": "/tmp/fake", "PATH": "/bin"}) + assert env["HOME"] == str(account_home()) + assert "XDG_CONFIG_HOME" not in env + + +def test_a_remote_named_like_the_destination_cannot_redirect_the_push( + git: Git, policy: LocalPolicy, repo: Path +) -> None: + _git(repo, "branch", "topic") + destination = policy.push_url("me/project") + _git(repo, "config", f"remote.{destination}.pushurl", policy.push_url("acme/project")) + with pytest.raises(GitRefused, match="repository configuration"): + _push(git, policy, repo, "topic", "fork", "topic", "new") + + +@pytest.mark.parametrize(("output", "refused"), [("git version 2.41.0", True), ("git version 2.42.0", False)]) +def test_git_older_than_2_42_is_refused(repo: Path, output: str, refused: bool) -> None: + def runner(argv: list[str], env: dict[str, str], cwd_fd: int | None) -> subprocess.CompletedProcess[str]: + return subprocess.CompletedProcess(argv, 0, stdout=output, stderr="") + + git = Git(runner=runner) + if refused: + with pytest.raises(GitRefused, match=r"2\.42 or later"): + git.check_version() + else: + git.check_version() + + +def test_a_root_swapped_for_a_symlink_after_the_checks_cannot_redirect_the_worktree( + git: Git, policy: LocalPolicy, repo: Path, tmp_path: Path +) -> None: + start = _git(repo, "rev-parse", "HEAD") + root = policy.worktree_roots[0] + elsewhere = Path(os.path.realpath(tmp_path)) / "elsewhere" + elsewhere.mkdir() + real_open_dir = git_ops.open_dir + + def swapping_open_dir(path: Path) -> int: + fd = real_open_dir(path) + if path == root: + # The swap lands after the root was opened, i.e. after every check. + root.rename(root.with_name("moved-root")) + root.symlink_to(elsewhere, target_is_directory=True) + return fd + + git_ops.open_dir = swapping_open_dir + try: + git_ops.worktree_add( + git, + policy, + {"checkout": str(repo), "path": str(root / "wt"), "branch": "t", "start": start}, + False, + ) + finally: + git_ops.open_dir = real_open_dir + assert list(elsewhere.iterdir()) == [] + assert (root.with_name("moved-root") / "wt" / "one").exists() + + +def test_a_symlinked_worktree_path_is_refused(git: Git, policy: LocalPolicy, repo: Path) -> None: + start = _git(repo, "rev-parse", "HEAD") + path = policy.worktree_roots[0] / "wt" + git_ops.worktree_add( + git, policy, {"checkout": str(repo), "path": str(path), "branch": "t", "start": start}, False + ) + link = policy.worktree_roots[0] / "link" + link.symlink_to(path, target_is_directory=True) + with pytest.raises(GitRefused, match="symlink"): + git_ops.worktree_sync(git, policy, {"worktree": str(link), "commit": start}, False) + + +def test_protocols_are_limited_through_the_environment(git: Git) -> None: + assert git._env()["GIT_ALLOW_PROTOCOL"] == "https:ssh:file" + assert Git()._env()["GIT_ALLOW_PROTOCOL"] == "https:ssh" + + +def test_a_copy_of_the_main_checkout_is_not_a_linked_worktree( + git: Git, policy: LocalPolicy, repo: Path +) -> None: + start = _git(repo, "rev-parse", "HEAD") + copy = policy.worktree_roots[0] / "copy" + copy.mkdir() + (copy / "one").write_text("one") + (copy / ".git").write_text(f"gitdir: {repo / '.git'}\n") + with pytest.raises(GitRefused, match="registered"): + git_ops.worktree_sync(git, policy, {"worktree": str(copy), "commit": start}, False) + + +def test_a_git_directory_swapped_after_validation_is_refused( + git: Git, policy: LocalPolicy, repo: Path +) -> None: + _git(repo, "branch", "topic") + worktree = git_ops.resolve_worktree(git, str(repo), policy, "checkout") + (repo / ".git").rename(repo / "real-git") + (repo / ".git").mkdir() + with pytest.raises(GitRefused, match="changed since it was validated"): + git_ops.check_repository_config(git, worktree) + + +def test_a_linked_worktrees_git_file_is_not_read_after_validation( + git: Git, policy: LocalPolicy, repo: Path, tmp_path: Path +) -> None: + start = _git(repo, "rev-parse", "HEAD") + path = policy.worktree_roots[0] / "wt" + git_ops.worktree_add( + git, policy, {"checkout": str(repo), "path": str(path), "branch": "t", "start": start}, False + ) + other = Path(os.path.realpath(tmp_path)) / "other" + other.mkdir() + _git(other, "init", "-q", "-b", "main") + worktree = git_ops.resolve_worktree(git, str(path), policy) + (path / ".git").write_text(f"gitdir: {other / '.git'}\n") + assert git.run(path, "rev-parse", "--absolute-git-dir").strip() == str(worktree.git_dir) + + +def test_a_commondir_rewritten_after_validation_is_refused_before_the_command( + git: Git, policy: LocalPolicy, repo: Path, tmp_path: Path +) -> None: + """A linked worktree's common directory comes from a file that can change after the check.""" + start = _git(repo, "rev-parse", "HEAD") + path = policy.worktree_roots[0] / "wt" + git_ops.worktree_add( + git, policy, {"checkout": str(repo), "path": str(path), "branch": "t", "start": start}, False + ) + other = Path(os.path.realpath(tmp_path)) / "other" + other.mkdir() + _git(other, "init", "-q", "-b", "main") + worktree = git_ops.resolve_worktree(git, str(path), policy) + git_ops.check_repository_config(git, worktree) # passes as validated + (worktree.git_dir / "commondir").write_text(f"{other / '.git'}\n") + with pytest.raises(GitRefused, match="common git directory"): + git_ops.check_repository_config(git, worktree) + + +def test_a_checkout_ancestor_swapped_after_validation_is_refused( + git: Git, policy: LocalPolicy, repo: Path +) -> None: + worktree = git_ops.resolve_worktree(git, str(repo), policy, "checkout") + moved = repo.with_name("moved") + repo.rename(moved) + repo.symlink_to(moved, target_is_directory=True) + with pytest.raises(GitRefused, match="symlink"): + git_ops.check_repository_config(git, worktree) + + +def _track_default_branch(repo: Path, commit: str) -> None: + _git(repo, "update-ref", "refs/remotes/upstream/main", commit) + _git(repo, "symbolic-ref", "refs/remotes/upstream/HEAD", "refs/remotes/upstream/main") + + +def test_moving_a_branch_to_an_empty_rebase_is_refused(git: Git, policy: LocalPolicy, repo: Path) -> None: + base = _git(repo, "rev-parse", "HEAD") + _track_default_branch(repo, base) + _git(repo, "checkout", "-q", "-b", "topic") + first = _commit(repo, "two") + _push(git, policy, repo, "topic", "fork", "topic", "new") + _git(repo, "reset", "-q", "--hard", base) + with pytest.raises(GitRefused, match="no commits over upstream/main"): + _push(git, policy, repo, "topic", "fork", "topic", first) + assert _remote_head(policy, "me/project", "topic") == first + + +def test_a_branch_with_commits_over_the_default_branch_is_pushed( + git: Git, policy: LocalPolicy, repo: Path +) -> None: + _track_default_branch(repo, _git(repo, "rev-parse", "HEAD")) + _git(repo, "checkout", "-q", "-b", "topic") + first = _commit(repo, "two") + _push(git, policy, repo, "topic", "fork", "topic", "new") + second = _commit(repo, "three") + _push(git, policy, repo, "topic", "fork", "topic", first) + assert _remote_head(policy, "me/project", "topic") == second + + +def test_inert_repository_config_is_accepted(git: Git, policy: LocalPolicy, repo: Path) -> None: + _git(repo, "branch", "topic") + _git(repo, "config", "remote.origin.url", "git@github.com:me/project.git") + _git(repo, "config", "branch.topic.remote", "origin") + _git(repo, "config", "user.name", "someone") + _push(git, policy, repo, "topic", "fork", "topic", "new") + + +def _hook(repo: Path, name: str, marker: Path, exit_code: int = 0) -> None: + hook = repo / ".git" / "hooks" / name + hook.write_text(f"#!/bin/sh\ntouch {marker}\nexit {exit_code}\n") + hook.chmod(0o755) + + +def test_a_push_never_runs_a_pre_push_hook(git: Git, policy: LocalPolicy, repo: Path, tmp_path: Path) -> None: + """The hook is working-tree code; it runs in the sandbox before the push, never out here.""" + marker = tmp_path / "hook-ran" + _hook(repo, "pre-push", marker, exit_code=1) + _git(repo, "branch", "topic") + _push(git, policy, repo, "topic", "fork", "topic", "new") + assert not marker.exists() + assert _remote_head(policy, "me/project", "topic") == _git(repo, "rev-parse", "topic") + + +def test_a_push_has_no_hooks_parameter() -> None: + assert "hooks" not in git_ops.OPS["git-push-branch"].params + + +def test_worktree_operations_never_run_hooks( + git: Git, policy: LocalPolicy, repo: Path, tmp_path: Path +) -> None: + marker = tmp_path / "hook-ran" + _hook(repo, "post-checkout", marker) + start = _git(repo, "rev-parse", "HEAD") + path = policy.worktree_roots[0] / "wt" + git_ops.worktree_add( + git, policy, {"checkout": str(repo), "path": str(path), "branch": "t", "start": start}, False + ) + git_ops.worktree_sync(git, policy, {"worktree": str(path), "commit": start}, False) + assert not marker.exists() + + +@pytest.mark.parametrize( + ("field", "value", "message"), + [ + ("expected", "abc123", "full lowercase commit SHA"), + ("branch", "--upload-pack=x", "may not"), + ("remote_branch", "a..b", "branch name"), + ("checkout", "relative/path", "absolute"), + ], +) +def test_push_validates_parameters( + git: Git, policy: LocalPolicy, repo: Path, field: str, value: str, message: str +) -> None: + _git(repo, "branch", "topic") + params = { + "checkout": str(repo), + "branch": "topic", + "target": "fork", + "remote_branch": "topic", + "expected": "new", + field: value, + } + with pytest.raises(GitRefused, match=message): + git_ops.push_branch(git, policy, params, False) + + +def test_a_checkout_the_policy_does_not_name_is_refused( + git: Git, policy: LocalPolicy, tmp_path: Path +) -> None: + other = Path(os.path.realpath(tmp_path)) / "other" + other.mkdir() + _git(other, "init", "-q") + _commit(other, "x") + with pytest.raises(GitRefused, match="does not belong"): + _push(git, policy, other, "master", "fork", "topic", "new") + + +def test_worktree_add_sync_remove(git: Git, policy: LocalPolicy, repo: Path) -> None: + start = _git(repo, "rev-parse", "HEAD") + path = policy.worktree_roots[0] / "wt-topic" + git_ops.worktree_add( + git, policy, {"checkout": str(repo), "path": str(path), "branch": "topic", "start": start}, False + ) + assert _git(path, "rev-parse", "--abbrev-ref", "HEAD") == "topic" + + _git(repo, "checkout", "-q", "-b", "rebased") + target = _commit(repo, "two") + message = git_ops.worktree_sync(git, policy, {"worktree": str(path), "commit": target}, False) + assert start in message + assert _git(path, "rev-parse", "HEAD") == target + + git_ops.worktree_remove(git, policy, {"worktree": str(path)}, False) + assert not path.exists() + + +def test_worktree_sync_refuses_local_changes(git: Git, policy: LocalPolicy, repo: Path) -> None: + start = _git(repo, "rev-parse", "HEAD") + path = policy.worktree_roots[0] / "wt" + git_ops.worktree_add( + git, policy, {"checkout": str(repo), "path": str(path), "branch": "t", "start": start}, False + ) + (path / "one").write_text("changed") + with pytest.raises(GitRefused, match="uncommitted"): + git_ops.worktree_sync(git, policy, {"worktree": str(path), "commit": start}, False) + + +def test_worktree_sync_refuses_the_main_checkout(git: Git, policy: LocalPolicy, repo: Path) -> None: + start = _git(repo, "rev-parse", "HEAD") + with pytest.raises(GitRefused, match="linked worktrees only"): + git_ops.worktree_sync(git, policy, {"worktree": str(repo), "commit": start}, False) + + +@pytest.mark.parametrize( + "where", + [ + pytest.param(lambda p, r: r.parent / "outside", id="outside-roots"), + pytest.param(lambda p, r: p.worktree_roots[0] / "nested" / "wt", id="not-directly-inside"), + pytest.param(lambda p, r: p.worktree_roots[0] / "-flag", id="bad-name"), + ], +) +def test_worktree_add_refuses_paths_outside_the_roots( + git: Git, policy: LocalPolicy, repo: Path, where: Callable[[LocalPolicy, Path], Path] +) -> None: + start = _git(repo, "rev-parse", "HEAD") + params = {"checkout": str(repo), "path": str(where(policy, repo)), "branch": "t", "start": start} + with pytest.raises(GitRefused): + git_ops.worktree_add(git, policy, params, False) + + +def test_worktree_add_refuses_an_existing_branch(git: Git, policy: LocalPolicy, repo: Path) -> None: + start = _git(repo, "rev-parse", "HEAD") + params = { + "checkout": str(repo), + "path": str(policy.worktree_roots[0] / "wt"), + "branch": "main", + "start": start, + } + with pytest.raises(GitRefused, match="already exists"): + git_ops.worktree_add(git, policy, params, False) + + +def test_worktree_remove_keeps_a_worktree_with_changes(git: Git, policy: LocalPolicy, repo: Path) -> None: + start = _git(repo, "rev-parse", "HEAD") + path = policy.worktree_roots[0] / "wt" + git_ops.worktree_add( + git, policy, {"checkout": str(repo), "path": str(path), "branch": "t", "start": start}, False + ) + (path / "untracked").write_text("x") + with pytest.raises(git_ops.GitFailed): + git_ops.worktree_remove(git, policy, {"worktree": str(path)}, False) + assert path.exists() + + +def test_dry_run_changes_nothing(git: Git, policy: LocalPolicy, repo: Path) -> None: + _git(repo, "branch", "topic") + printed = _push(git, policy, repo, "topic", "fork", "topic", "new", dry_run=True) + assert "--force-with-lease=refs/heads/topic:" in printed + assert "core.hooksPath=/dev/null" in printed + assert "--no-verify" in printed + assert "--no-follow-tags" in printed + with pytest.raises(subprocess.CalledProcessError): + _remote_head(policy, "me/project", "topic") + + +def _config(git_table: object) -> Config: + return Config( + tracker_repo=None, + upstream_repo="acme/project", + workspace=Path("/tmp"), + values={}, + endpoints={}, + callers={}, + git=git_table, + ) + + +def test_git_policy_defaults_and_protected_branches(tmp_path: Path) -> None: + checkout = Path(os.path.realpath(tmp_path)) + policy = git_ops.git_policy(_config({"checkouts": [str(checkout)], "protected": ["prod"]})) + assert policy.push_url("acme/project") == "git@github.com:acme/project.git" + assert git_ops.is_protected("prod", policy) + assert git_ops.is_protected("main", policy) + assert not policy.upstream_push + + +@pytest.mark.parametrize( + "table", + [ + pytest.param(None, id="no-table"), + pytest.param({"checkouts": []}, id="no-checkouts"), + pytest.param({"checkouts": ["relative"]}, id="relative-checkout"), + pytest.param({"checkouts": ["/"], "fork": "not a repo"}, id="bad-fork"), + pytest.param({"checkouts": ["/"], "transport": "ftp"}, id="bad-transport"), + ], +) +def test_git_policy_refuses_malformed_tables(table: object) -> None: + with pytest.raises(ConfigError): + git_ops.git_policy(_config(table)) + + +def test_clean_env_drops_git_variables() -> None: + env = git_ops.clean_env({"PATH": "/bin", "GIT_SSH_COMMAND": "evil", "GIT_DIR": "/x"}) + assert env == {"PATH": "/bin", "HOME": str(account_home()), "GIT_TERMINAL_PROMPT": "0"} + + +def test_parse_config_scopes_handles_both_separators() -> None: + assert git_ops.parse_config_scopes("local\x00core.bare\x00global\x00user.name\x00") == [ + ("local", "core.bare"), + ("global", "user.name"), + ] + assert git_ops.parse_config_scopes("local\tcore.bare\x00") == [("local", "core.bare")] + + +class _ExplodingGit(Git): + """Fails the test the moment anything would run git.""" + + def __init__(self) -> None: + super().__init__(runner=_runner(os.devnull), protocols=("https", "ssh", "file")) + + def run(self, *args: object, **kwargs: object) -> str: + raise AssertionError("a dry run against an unapproved policy ran git") + + def ok(self, *args: object, **kwargs: object) -> bool: + raise AssertionError("a dry run against an unapproved policy ran git") + + +def test_a_dry_run_against_an_unapproved_policy_runs_no_git( + policy: LocalPolicy, repo: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +) -> None: + """Even read-only git, outside the sandbox, is steered by the policy: an unapproved one runs none.""" + config = dataclasses.replace(_config({}), callers={"skill": frozenset({"git-push-branch"})}) + loads: list[bool] = [] + + def fake_load(*, approved_only: bool = False, **_: object) -> Config: + loads.append(approved_only) + if approved_only: + raise ConfigError("the policy is not an approved copy") + return config + + monkeypatch.setattr(git_ops, "load", fake_load) + monkeypatch.setattr(git_ops, "git_policy", lambda _config: policy) + argv = ["--caller", "skill", "--dry-run", "git-push-branch", str(repo), "topic", "fork", "topic", "new"] + assert git_ops.main(argv, git=_ExplodingGit()) == git_ops.EXIT_OK + assert loads == [True, False] # the approved policy is always tried first + assert "no git command was run" in capsys.readouterr().out + + +def test_a_real_run_against_an_unapproved_policy_is_refused( + policy: LocalPolicy, repo: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + def fake_load(*, approved_only: bool = False, **_: object) -> Config: + raise ConfigError("the policy is not an approved copy") + + monkeypatch.setattr(git_ops, "load", fake_load) + argv = ["--caller", "skill", "git-push-branch", str(repo), "topic", "fork", "topic", "new"] + assert git_ops.main(argv, git=_ExplodingGit()) == git_ops.EXIT_POLICY + + +def _is_open(fd: int) -> bool: + try: + os.fstat(fd) + except OSError: + return False + return True + + +def test_anchor_closes_a_passed_descriptor_for_a_path_it_already_holds(git: Git, tmp_path: Path) -> None: + path = Path(os.path.realpath(tmp_path)) + first = git.anchor(path) + second = os.open(path, os.O_RDONLY | os.O_DIRECTORY) + assert git.anchor(path, second) == first + assert not _is_open(second) + assert _is_open(first) + git.close() + assert not _is_open(first) + + +def test_anchor_keeps_a_passed_descriptor_for_a_new_path_until_close(git: Git, tmp_path: Path) -> None: + path = Path(os.path.realpath(tmp_path)) + fd = os.open(path, os.O_RDONLY | os.O_DIRECTORY) + assert git.anchor(path, fd) == fd + assert git.anchor(path, fd) == fd + assert _is_open(fd) + git.close() + assert not _is_open(fd)