Documentation
¶
Overview ¶
Package git is the HARDENED git read/fetch layer (plan §7.6 + §15). A connected repo is attacker-controlled: merely fetching, diffing, or checking out can run code via .gitattributes filter/textconv, LFS smudge, fsmonitor/sshCommand, hooks, and submodule ext::. Every invocation here is run config-/attribute- proof with static argv (never a shell); file bytes are read via `cat-file` from the object store (no worktree, no smudge); symlink/gitlink tree modes are rejected; and the remote URL passes an SSRF allowlist.
Index ¶
- Constants
- func RawStderr(err error) string
- func RepoHostName(raw string) string
- func RepoScheme(raw string) string
- func StaleLock(err error) bool
- func ValidateRepoURL(raw string) error
- type CommitInfo
- type Creds
- type DiffResult
- type FileChange
- type Repo
- func (r *Repo) ArchiveTo(ctx context.Context, sha, destDir string) error
- func (r *Repo) CatFile(ctx context.Context, sha, path string) ([]byte, error)
- func (r *Repo) CommitsBehind(ctx context.Context, from, to string) (int, error)
- func (r *Repo) Diff(ctx context.Context, from, to string) (DiffResult, error)
- func (r *Repo) Fetch(ctx context.Context, repoURL, ref string, creds Creds) (string, error)
- func (r *Repo) FileExists(ctx context.Context, sha, path string) bool
- func (r *Repo) IsAncestor(ctx context.Context, a, b string) (bool, error)
- func (r *Repo) LsFiles(ctx context.Context, sha string) ([]string, error)
- func (r *Repo) LsTreeRoot(ctx context.Context, sha string) ([]string, error)
- func (r *Repo) RefSha(ctx context.Context, ref string) string
- func (r *Repo) ResolveRef(ctx context.Context, ref string) (string, error)
- func (r *Repo) SetDeployedRef(ctx context.Context, sha string) error
Constants ¶
const ( StagedRef = "refs/mooring/staged" DeployedRef = "refs/mooring/deployed" )
Ref names. The object store is per-app, so a single staged/deployed ref each.
Variables ¶
This section is empty.
Functions ¶
func RawStderr ¶ added in v0.11.3
RawStderr returns the bounded, redacted raw git stderr behind a classified git error (for OPERATOR journald logs only — it makes an opaque "repository or ref not found" show the actual git message), or "" if err isn't a classified git error.
func RepoHostName ¶ added in v0.14.1
RepoHostName returns a repo URL's host (e.g. "github.com"), or "" if it can't be determined.
func RepoScheme ¶ added in v0.14.1
RepoScheme returns a repo URL's transport ("https" or "ssh"), or "" if it can't be determined. Callers use it to match a credential type to the URL (an SSH key can't auth an https:// URL).
func StaleLock ¶ added in v0.11.5
StaleLock reports whether a classified git error is the stale-lock error (used by the fetch self-heal to decide whether to clear the lock and retry).
func ValidateRepoURL ¶
ValidateRepoURL enforces the §15 SSRF allowlist on a git remote: scheme ∈ {https, ssh} (incl. scp-like git@host:path), and a literal-IP host may not be loopback/link-local/metadata. Credentials must never be embedded in the URL.
Types ¶
type CommitInfo ¶
CommitInfo is one sanitized commit summary for the diff preview.
type Creds ¶
type Creds struct {
Token string // https PAT (username defaults to x-access-token)
SSHKey string // ssh private key (PEM)
KnownHosts string // pinned known_hosts for ssh (required for ssh)
}
Creds carries fetch credentials. They are written to a 0700 PrivateTmp dir and passed to git via an askpass helper / GIT_SSH_COMMAND — NEVER in the URL argv.
type DiffResult ¶
type DiffResult struct {
CommitsBehind int
Commits []CommitInfo
Files []FileChange
Truncated bool
}
DiffResult is the hostile-data-safe, capped pending-update preview.
type FileChange ¶
FileChange is one sanitized changed-file entry.
type Repo ¶
type Repo struct {
// contains filtered or unexported fields
}
Repo is a per-app bare object store with hardened git access.
func (*Repo) ArchiveTo ¶
ArchiveTo extracts the commit's tree into destDir via `git archive` + an in-process tar reader that REJECTS symlinks/hardlinks/devices and confines every path under destDir (no worktree, no smudge, no hooks).
func (*Repo) CatFile ¶
CatFile reads a file's bytes from the pinned commit's tree — object-store only, no worktree, no smudge. It first rejects any symlink/gitlink on the path: a single ls-tree resolves the path THROUGH real trees, so a regular-blob result guarantees no symlink/gitlink component (git can't descend a blob).
func (*Repo) CommitsBehind ¶
CommitsBehind counts commits in to that are not in from (from "" → count all reachable from to).
func (*Repo) Diff ¶
Diff builds the pending-update preview between from and to. ALL fields are sanitized (strip NUL/CR/LF/ANSI, cap length) — the operator's session is the most privileged; an oversized/hostile diff must truncate, never OOM.
func (*Repo) Fetch ¶
Fetch fetches the fully-qualified ref into the staged ref and returns its sha. It performs NO worktree change and runs nothing live (read-plane).
func (*Repo) FileExists ¶
FileExists reports whether path is a regular file in the commit (no symlink).
func (*Repo) IsAncestor ¶
IsAncestor reports whether commit a is an ancestor of commit b (i.e. b fast-forwards from a). A "no" on two real commits means history diverged / was rewritten (e.g. a force-push) — the FSM surfaces that as history_rewritten.
func (*Repo) LsFiles ¶
LsFiles returns up to a cap of regular-file paths in the commit (for the compose-path wizard; never a filesystem walk).
func (*Repo) LsTreeRoot ¶
LsTreeRoot lists the names directly under the commit's ROOT tree (NOT recursive), so callers that only care about top-level files (e.g. the mooring*.yaml discovery) never depend on a capped full-tree walk that could drop a root entry behind 5000 nested files. Bounded by the number of root entries (and the shared output cap).
func (*Repo) ResolveRef ¶
ResolveRef returns the commit sha a ref or sha points at (verified to exist).
Source Files