Security model
Assets
- source and release integrity;
- local file snapshots in the Git object database;
- checkpoint and pending attribution metadata;
refs/notes/byline;- managed Git
pre-pushnote sharing; - generated local HTML dashboards;
- user and project agent configuration;
- Git hooks and shell configuration;
- maintainer credentials and GitHub settings;
- published archives, checksums, and SBOMs.
Trust boundaries
Hook input, paths, patch text, Git configuration, repository content, issue text, pull request code, dependencies, downloaded tools, and release files are untrusted.
Every Git subprocess drops the GIT_ variables it inherits, like GIT_DIR
or GIT_INDEX_FILE, so the operation that runs a hook cannot point
git-byline at another repository or index. Only GIT_CONFIG_NOSYSTEM,
GIT_CONFIG_SYSTEM, and GIT_CONFIG_GLOBAL stay. Git reads the system, global, and repository
configuration the same way the user's own Git does, so ignore rules from
core.excludesFile, line endings, and long paths match. Git for Windows
keeps these settings in its system file. A snapshot never includes a path
that the user's Git ignores.
The production binary opens no background network connections. Production
code imports no network packages; the only network access is the curl
subprocess that update and version --check run through internal/runner
against the pinned GitHub release repository, HTTPS-only, with -q so a
local curlrc cannot weaken the flags. The update path verifies the download
against checksums.txt, then checks the staged binary's reported version
before the swap. The managed pre-push hook invokes Git to fetch
attribution notes from the selected remote and to publish them there unless
installation used --local-notes. The hook reads only refs/notes/byline,
and only from the URL the push goes to, and it pushes the notes to that
same URL. The fetch sets fetch.fsckObjects, so Git refuses malformed
objects before it stores them. git-byline merge-notes merges the fetched
notes offline and never contacts the remote. It accepts a fetched history
only when every object it adds is a notes commit, a notes tree, or a note
blob of at most 16 MiB, and only notes that the remote side adds; a remote
change or removal of a local note stops the push. After the update, Git's
own notes listing must match the expected notes, or the ref goes back, so a
tree that git-byline and Git read differently changes nothing. Fetched notes
are untrusted input, validated when read, like notes fetched by hand.
Droid and Claude Code hook payloads do not name a model. When an AI checkpoint
would carry the unknown model, the binary reads the session transcript named
by the untrusted transcript_path field, then the session settings file next
to it, to recover the model identifier. Both reads are bounded, accept only
absolute regular-file paths, and skip symlinks. Only the extracted model name
is kept; transcript or settings content is never copied into any record.
checkpoint accepts an edit path only inside a worktree of the repository
where the hook runs. Agent hooks often run in the main checkout while the
agent edits a linked worktree, so a path in another worktree of the same
repository is recorded in that worktree's own checkpoint log and retention
ref. The candidate worktrees come from git worktree list in the hook's
repository, never from the payload. Each candidate is reopened and accepted
only when Git reports the same root and the same common Git directory, so a
removed, replaced, or foreign directory at a registered path receives
nothing. The owning worktree applies the usual checks for .git, ignore
rules, symlink escapes, regular files, size, and text. The resolved path only
picks the owner. The path itself moves in the form the owner's own hook would
send, so its symlink components are still checked, and a relative path that
reaches another worktree only through a symlink stays in the hook's worktree
and is rejected there. Paths outside every worktree of the repository stay
rejected. Shell events keep using the dirty paths of the hook's own worktree.
The managed reference-transaction hook has the opposite failure contract.
It exits immediately when GIT_BYLINE_NESTED is set, starts the binary only
for the committed phase, ignores refs outside HEAD, refs/heads/*,
refs/stash, and MERGE_AUTOSTASH, and always exits zero. The phase check
is a shell case, not an early exit, so user hook code below the managed
block still runs for every phase. This hook runs on the critical path of commands such as git status,
reset, stash, pull, and branch switching. The wrapper keeps the never-nonzero
contract; the binary parses and filters transaction lines before repository
discovery. A provenance failure must not break repository operations.
The post-rewrite and post-merge hooks fail closed because their work is
recoverable and an incomplete rewrite could otherwise leave attribution
silently detached. post-checkout also fails open because checkout must not
be blocked by pending attribution repair.
Forge merge workflows are separate from the binary trust boundary. git byline ci run reads only commits and notes already fetched into the local repository,
then writes attribution notes locally. It never calls a forge service and never
pushes. The generated workflow performs the Git fetch and notes push.
install-hooks --git provisions the workflow file locally from the embedded
template when the origin remote host is github.com or gitlab.com; it refuses to
replace a different existing file and never contacts the forge. A workflow
that differs from the embedded template only in the release tag on its
version pin line still counts as managed, so a git-byline upgrade does not
orphan it. uninstall removes the file only while it still matches the
embedded template apart from that tag.
The marketplace action is an alternative delivery of the same reconstruction.
Its metadata lives at the repository root, where the GitHub Marketplace
listing requires it, and a byte-identical copy under action/ keeps the
subdirectory reference working; the validate gate fails when the two drift.
It runs in the calling workflow's context: the caller grants
contents: write, the action downloads a release binary from the pinned
git-byline repository, verifies it against the release checksums.txt, and
pushes only refs/notes/byline. The generated workflows install a release
the same way, pinned by their version line; the action installs the release
named by its version input.
The GitHub workflow requests only contents: write. It needs read access to
the repository and write access to refs/notes/byline; it does not need issue,
pull request, package, deployment, or administrative permissions. The workflow
uses immutable action commit pins and pushes only the notes ref with
--no-verify.
The GitLab workflow is a trusted post-merge push pipeline on the project
default branch. Merge-request and external fork pipelines are explicitly
blocked. It expects a project access token in GITLAB_TOKEN with only the
write_repository scope because the job uses Git-over-HTTP ls-remote,
fetch, and push operations only. The token is the password of HTTP basic
authentication with the user name oauth2, which Git over HTTPS accepts;
the PRIVATE-TOKEN header works only for REST calls. The encoded credential
is passed through Git's in-memory http.extraHeader for each command, the
token is removed from the shell environment before the binary runs, and
neither is written to the repository. It is not used by the binary. The job
stops before it builds the header when GIT_BYLINE_REMOTE_URL, which is
CI_PROJECT_URL by default, is not an https:// URL, so the header never
travels without TLS. GitLab masks the raw token in job logs, not the encoded
header, so do not enable CI_DEBUG_TRACE for this job. The generated
GitLab job is stored under .gitlab/ci/git-byline.yml and must be included
from the project's .gitlab-ci.yml. It installs the release named by
GIT_BYLINE_VERSION from GIT_BYLINE_RELEASES_URL, the pinned git-byline
repository by default, over HTTPS only. It verifies the archive against that
release's checksums.txt and the binary's reported version, and deletes the
download after the run, also when a check or the run fails. A mirror URL
moves trust for both files to the mirror.
Both workflows reconstruct from the actual post-merge target commit. The
GitHub workflow uses the merge commit's second parent as the source tip for a
true merge, with its first parent as GIT_BYLINE_CI_BASE. A single-parent
result, whether a squash or a rebase merge, uses the merged pull request head
as the source and derives the base from the merge base of that head and the
target, so a multi-commit rebase range stays complete. The GitLab
workflow derives its base from the pushed commit's first parent and its source
from the second parent. A squash merge leaves the merge request commits, and
their notes, only on the merge request head. When the target commit message
names the merge request as <project path>!<iid>, the workflow fetches
refs/merge-requests/<iid>/head and uses it as the source only when its diff
from the merge base has the same stable patch ID as the diff the target commit
brings, so a wrong or edited reference cannot move notes onto other changes.
Otherwise a single-parent result has an empty source range and is skipped
safely. The workflow runs the pinned release binary, not code from
that merge commit, before pushing notes. Before every token-bearing Git
operation, it re-pins the
canonical remote URL, disables repository hooks with an empty
core.hooksPath, and disables system and global Git configuration. No branch,
tag, source file, or workflow ref is pushed by the generated job.
Each provider serializes note publication with a concurrency or resource group,
so concurrent jobs do not race on refs/notes/byline. Reconstruction allows at
most 10,000 aggregate PatchID calls and has a two-minute pairing deadline.
Commits beyond either budget stay untracked, with a warning, and never fail
the workflow. A CI run with empty source and target ranges succeeds with a
warning and writes no notes.
Threats and controls
| Threat | Prevention | Detection | Recovery |
|---|---|---|---|
| Path escapes worktree | Normalize path, reject .git, traversal, symlink escape; accept only paths inside a worktree of the hook's repository | Path tests and warnings | Skip snapshot, preserve prior state |
| Stale or replaced linked worktree | Candidates come only from git worktree list; each must report the same root and common Git directory | Skip warning names the path and worktree | Skip snapshot, preserve prior state |
| Secret file enters Git ODB | Skip Git-ignored and non-regular files | Repository scans and review | Remove local object after retention ends |
| Malicious hook payload | Bounded input, strict event and metadata validation, path validation | Parser tests and explicit errors | No checkpoint written |
| Malicious transcript path | Absolute regular-file check, final-symlink and reparse rejection, single-handle or identity-bound opens, bounded reads, model revalidated before use | Transcript resolver tests | Model stays unknown |
| Git command injection | Argument slices, no shell, bounded output | Fake and integration command tests | Fail operation without state advance |
| Checkpoint loss during Git GC | Retention ref written before JSONL append | Aggressive GC integration test | Reuse protected blob |
| Oversized local state exhausts memory | Stream checkpoint reads, cap logs at 64 MiB and 100,000 records, cap state at 64 MiB | Limit regression tests | Preserve and inspect local state before repair |
| Concurrent state corruption | Advisory locks and fixed lock order | Contention tests | Process exit releases locks |
| Partial persistence | Idempotent note writes and atomic state replacement | Retry scenarios | Rerun annotate |
| Malicious or stale note | Version and blob validation | Warning and untracked fallback | Preserve note for manual review |
| Oversized attribution note exhausts memory | Reject notes above 16 MiB or 500 files before full decode | Note limit regression tests | Inspect or replace the invalid note |
| Attribution metadata is shared unexpectedly | Installation output and documentation disclose default note sharing; --local-notes opts out | Inspect managed pre-push hook and remote notes ref | Reinstall with --local-notes, then remove remote notes deliberately |
| Note publication fails | Managed pre-push exits non-zero and stops the branch push | Git push error | Fix remote access or opt out with --local-notes |
| Remote notes replace or remove a local note | Pre-push merge accepts only notes the remote side adds, uses the manual strategy under the notes lock, aborts every conflict, and pushes without force; the fetch writes only a per-worktree ref with an empty --refmap | Conflict message names the commit and prints the manual merge steps | Local notes stay unchanged; review, merge by hand, then push again |
| Fetched notes carry a tag, a tree, other files, or malformed objects | The fetch sets fetch.fsckObjects; both notes refs must point to commits, every object the fetched history adds must be a notes commit, a notes tree, or a note blob of at most 16 MiB named by an object ID, and Git's notes listing after the update must match the expected notes | Merge error stops the push | Local notes stay unchanged or go back; inspect the remote notes ref |
| Notes sync reaches another repository | The fetch and the notes push use only the URL Git runs the hook for, and the sync runs only when the working directory finds the hook's repository | Hook tests with separate and multiple push URLs and an outside Git dir | The branch push goes on with the plain notes push, which never forces |
| Reference transaction attribution fails | Nested and irrelevant refs exit immediately; all other failures are swallowed and hook exits zero | Hook and rewrite tests | Run git byline rewrite manually after the repository operation |
| Dashboard content injects HTML or script | Validate attribution, escape untrusted values with html/template, restrictive CSP | Renderer and CLI tests | Delete report and regenerate |
| Dashboard exposes source or metadata | Private temporary file mode, no external resources, no automatic publication | User review and repository scans | Delete local report |
| Hook config overwrite | Structural merge, backup, managed markers | Idempotency and preservation tests | Restore .git-byline.bak |
| Fork reaches write token | Post-merge default-branch rules, explicit fork rejection, token only in fetch and push steps | Pipeline rule checks | Disable workflow and rotate token |
| Commit message names another merge request | Numeric merge request ID only; its head is used only when its stable patch ID equals the target diff | Job warning names the rejected merge request | Lines stay untracked |
| Compromised action or tool | Immutable action pins and pinned tool versions | Renovate, dependency review, CodeQL | Pause automation, pin or remove tool |
| Invalid release | Tag validation, tests, archive checks, checksums, SBOM | Release workflow and manual install | Withdraw release and publish patch |
Stored data
Checkpoint JSON includes repository-relative paths, timestamps, agent names,
model names, session identifiers, Git object IDs, and optional assistant
message IDs with per-turn aggregate token counts. Notes contain repository
paths, timestamps, agent names, model names, session identifiers, Git object
IDs, line ranges, per-session token totals, and a human identity token on human
and human-override ranges. Assistant message IDs stay in the local checkpoint
log and are not copied into notes. The identity token is derived from the
commit author Git already publishes in every commit object, reduced to the
email local part. Managed hooks publish attribution notes by default unless
installation used --local-notes. Stash ownership notes contain only a
SHA-256 digest of the exact stash attribution note. Snapshot blobs contain
full selected file content.
Raw hook payloads, prompts, transcripts, tool responses, environment variables, authorization data, and logs are not persisted.
Generated dashboards contain committed source lines, repository-relative
paths, commit and blob IDs, attribution states, agent and model names, human
identity tokens, and local status. Default reports use a private temporary file. Explicit output
paths are created with mode 0600 where supported and never replace an
existing file. Reports are self-contained and make no network requests.
After Git hooks are installed, ordinary pushes publish the notes ref before
the branch ref. A later branch rejection can therefore leave note metadata on
the remote before its target commit arrives. Before that notes push, the hook
merges the notes already on the push remote into refs/notes/byline, so
notes others published land in local notes. Normal fetches still do not
retrieve notes without an explicit refspec. Worktree retention refs are never
published by managed hooks.
Residual risks
- A user can explicitly transfer local metadata or snapshot objects.
- A successful notes push can precede a rejected branch push.
- Duplicate equal lines cannot prove staging order.
- First-parent merge attribution cannot prove content from other parents.
- A compromised local account can read Git objects and hook configuration.
- A user can copy or publish a generated dashboard containing source and attribution metadata.
- A compromised maintainer token can alter public source or releases until repository controls contain it.
- The update fetch trusts GitHub TLS for
checksums.txtand the archive, like the installer does; a compromised release source can offer a matching pair.
Changes to storage, notes, hooks, releases, or the network-access rule require security review.