gitproxy

type Credential struct {
	Username string
	Password string
	// GrantID and LeaseID are audit bookkeeping. Neither is secret.
	GrantID string
	LeaseID string
}

type Decision struct {
	Update RefUpdate
	Err    error
}

type DenyReason string

type Event struct {
	Kind      EventKind `json:"kind"`
	SessionID string    `json:"session_id,omitempty"`
	RepoPath  string    `json:"repo_path,omitempty"`
	ProjectID string    `json:"project_id,omitempty"`
	TaskID    string    `json:"task_id,omitempty"`
	Actor     string    `json:"actor,omitempty"`
	// RunID is the run the session serves, on a push_secret_refused row: what
	// the hub files the refusal in the run's history by.
	RunID string `json:"run_id,omitempty"`
	// Refs are the ref names the request touched, with any of the run's
	// credentials a name carries taken out.
	Refs []string `json:"refs,omitempty"`
	// Detail is a human-readable reason or summary.
	Detail string `json:"detail,omitempty"`
	// Findings are where a push_secret_refused push carries a credential.
	Findings []ScanFinding `json:"findings,omitempty"`
	// Scan is set on a push the scan refused (Task 20436): ScanResultSecret
	// on a push_secret_refused row, ScanResultLimit or ScanResultUnreadable
	// on a push_denied one.
	Scan string    `json:"scan,omitempty"`
	At   time.Time `json:"at"`
}

type EventKind string

type MintRequest struct {
	// Upstream is the real https repository URL the proxy will forward to —
	// or, when RepoPatterns is set, the forge host base (https://github.com)
	// beneath which the allowlisted repositories live.
	Upstream string
	// RepoPatterns, when non-empty, mints a *scoped* session: one that admits
	// every repository matching an owner/name glob, rather than the single
	// repository Upstream names. Upstream must then be a bare host base.
	//
	// This is the mode a user's GitHub PAT grant uses, because its allowlist
	// ("acme/*") names a set that only the forge can enumerate. See scope.go.
	RepoPatterns []string
	// ForgeHost is the forge host Credential is good against (Task 20423):
	// github.com, or the GitHub Enterprise Server host the grant names. The
	// session is served on that host's route alone, and a pinned session's
	// Upstream must be on it, as must a scoped one's for any host but
	// github.com. Empty is github.com for a scoped session and Upstream's own
	// host for a pinned one — what every request meant before hosts were
	// recorded.
	ForgeHost string
	// Credential authenticates the proxy upstream. Optional: a public
	// repository needs none, though pushing to one generally does.
	Credential Credential
	// CredentialExpiresAt is when the forge stops honouring Credential — a
	// GitHub App installation token's hour. Zero for a credential that does
	// not expire on a clock the hub knows (a PAT).
	CredentialExpiresAt time.Time
	// Refresh, when set, re-mints Credential before CredentialExpiresAt
	// (Task 20375). The session calls it from its request path once
	// CredentialRefreshWindow or less of the credential's life remains,
	// single-flight, presents the result to every later upstream request, and
	// retires the superseded credential once no request presents it. Requires
	// CredentialExpiresAt. See refresh.go.
	Refresh RefreshFunc
	// Policy is what the sandbox may do. Zero value gets WriteBackPolicy.
	Policy Policy
	// TTL bounds the session. 0 means DefaultSessionTTL; anything above
	// MaxSessionTTL is an error rather than a silent clamp, because a caller
	// that asked for a day and got twelve hours would discover it as a failed
	// push halfway through.
	TTL time.Duration

	ProjectID  string
	TaskID     string
	ExecutorID string
	Actor      string
	// RunID names the run the session is for, recorded with it.
	RunID string

	// Durable records the session in the registry's Store (Task 20383), so
	// that the hub process adopting its run after this one stops can restore
	// it under the same id and token. The lease path sets it: its sessions
	// stand on the run's lease, which the adopter takes over and re-derives
	// the upstream credential from. A session no lease is taken over for —
	// a workspace's, whose credential stands on a lease of its own — would
	// have nothing to be restored with, and is left out.
	Durable bool

	// OnEnd, when set, runs once after the session has left the registry —
	// closed, reaped after its TTL, or closed at shutdown — on the goroutine
	// that ended it and outside the registry's lock.
	//
	// It is for releasing what the upstream credential stands on. A GitHub
	// App installation token is destroyed at GitHub when the lease that
	// minted it is released, and a session presents that token upstream for
	// its whole life: releasing the lease when the credential was *delivered*
	// left the session holding a dead token (Task 20349).
	OnEnd func()
}

type Minted struct {
	Session *Session
	// Token is the plaintext session token. The registry keeps only its hash,
	// so this is the only copy that will ever exist.
	Token string
	// RepoURL is what the sandbox uses as its remote: the proxy's public base
	// with the session's repository path — or, for a scoped session, the route
	// its forge host's URLs are rewritten to (ForgeRoute). It carries no
	// credential.
	RepoURL string
}

type Options struct {
	// Transport carries the proxy's requests to the forge. nil gets a
	// hardened default. It exists so an operator whose forge sits behind a
	// private CA can supply one — the same case pkg/tlsconf exists for — and
	// so a test can point the upstream leg at a self-signed fixture without
	// weakening the default.
	Transport http.RoundTripper

	// Fallback, when set, is offered every request whose credential names a
	// session this registry has never heard of, before it is refused
	// (Task 20354). Several hub processes may serve one control plane, each
	// with its own registry, and a sandbox's request reaches whichever of
	// them the network sends it to; the hub forwards it to the process that
	// minted the session. It reports whether it answered the request.
	// Credentials naming a session this registry knows — right or wrong
	// token, live or expired — are always decided here.
	Fallback func(w http.ResponseWriter, r *http.Request, sessionID string) bool

	// Routes hands requests under other path prefixes on the proxy's
	// listener to other handlers, ahead of git routing: the hub serves its
	// model relay for sandboxed runs beside the git proxy (Task 20435), so a
	// sandbox reaches both at one address, over one certificate, through one
	// firewall rule. A prefix must begin "/_" — no forge owner begins with
	// an underscore, so no repository path can be taken for one (as for
	// ForgeRouteSegment) — and is matched at a "/" boundary.
	Routes []Route

	// PushScan decides how a push through a session is scanned for the
	// credentials its run holds (Task 20436): the mode, the values, the
	// limits. nil scans every push in ScanValues mode for the one value the
	// proxy knows without being told — the session's own upstream token —
	// within the default limits. Whatever it returns, the session's upstream
	// token is matched too.
	PushScan PushScanFunc
}

type Policy struct {
	// AllowedRefs are glob patterns over full ref names. A pattern without a
	// refs/ prefix is read as a branch name and gets refs/heads/ prepended, so
	// "cloop/*" and "refs/heads/cloop/*" mean the same thing.
	//
	// Matching follows path.Match: "*" does not cross a "/". A trailing "/**"
	// matches any depth below the prefix, which is what a per-task namespace
	// like cloop/task-42/fixup needs.
	AllowedRefs []string `json:"allowed_refs,omitempty"`

	// AllowCreate permits a push that brings a ref into existence. Creating a
	// new branch under an allowed namespace is the ordinary write-back case, so
	// this is the one authority a caller almost always wants.
	AllowCreate bool `json:"allow_create,omitempty"`

	// AllowUpdate permits moving an existing allowed ref to a new commit. A
	// retried task legitimately replaces its own predecessor.
	AllowUpdate bool `json:"allow_update,omitempty"`

	// AllowDelete permits removing an allowed ref. Off by default: deleting is
	// not something a write-back ever needs, and a name-only allowlist that
	// forgot about deletes would let a sandbox destroy the very branches it was
	// scoped to.
	AllowDelete bool `json:"allow_delete,omitempty"`

	// AllowFetch permits the read half of the protocol — git-upload-pack — over
	// the same session. A sandbox that clones through the proxy needs it; one
	// that only pushes back a tree it was handed does not.
	AllowFetch bool `json:"allow_fetch,omitempty"`

	// MaxCommands caps ref updates per push. 0 means DefaultMaxCommands.
	MaxCommands int `json:"max_commands,omitempty"`

	// MaxPackBytes caps the request body. 0 means DefaultMaxPackBytes.
	MaxPackBytes int64 `json:"max_pack_bytes,omitempty"`

	// RestrictRefs is a second allowlist that a ref must *also* match. Empty
	// means no second restriction, so only AllowedRefs applies.
	//
	// It exists so that one party can narrow another's allowlist without
	// either rewriting it. The hub's configured allowlist is AllowedRefs, the
	// ceiling; a grant that says "this project may push to feature/* only"
	// arrives here, and a ref has to clear both. The alternative, computing
	// one list that is the intersection of the two, is not possible in
	// general: the intersection of two sets of globs is not always a third
	// set of globs. Two lists that both have to match are always exact.
	//
	// Patterns take the same syntax and normalisation as AllowedRefs. Unlike
	// AllowedRefs, an empty list gets no default. Silence here means "the
	// grant added nothing", not "fall back to the write-back namespace".
	RestrictRefs []string `json:"restrict_refs,omitempty"`
}

type Proxy struct {
	// contains filtered or unexported fields
}

type PushScan struct {
	Mode ScanMode
	// Secrets are the values the session's run holds. The session's own
	// upstream credential is added to them by the proxy.
	Secrets []ScanSecret
	Limits  ScanLimits
}

type PushScanFunc func(sess *Session) PushScan

type ReceivePack struct {
	// Commands are the ref updates, in wire order.
	Commands []RefUpdate
	// Capabilities are the tokens the client advertised after the NUL on the
	// first command line — "report-status", "side-band-64k", "agent=git/2.43"
	// and so on.
	Capabilities []string
	// Shallow lists the object names from any shallow lines. They are carried
	// so a caller can see them; nothing here decides on them.
	Shallow []string
}

type RefDenial struct {
	Reason  DenyReason
	Message string
	// Ref, when set, is the ref the refusal is about. Error names it, so the
	// error is self-contained wherever it is logged; Decision.Reason leaves it
	// out, because git's status line already prints it and the reason is cut
	// to one short line (see Decide).
	Ref string
}

type RefUpdate struct {
	Old string
	New string
	Ref string
}

type RefreshFunc func(ctx context.Context, held string) (Refreshed, error)

type Refreshed struct {
	// Credential is presented upstream from now on.
	Credential Credential
	// ExpiresAt is when the forge stops honouring it.
	ExpiresAt time.Time
	// Retire ends the credential this one superseded — destroys a GitHub App
	// token at GitHub. The session calls it once, after the last request
	// presenting the old credential has finished. Nil when there is nothing to
	// retire, which is also what a refresher returns when another caller had
	// already renewed the credential.
	Retire func()
}

type Registry struct {
	// BaseURL is the https base the sandbox reaches the proxy at, e.g.
	// "https://hub.internal:8443". Sessions render their RepoURL beneath it.
	BaseURL string
	// Now is the clock, injectable for tests. nil means time.Now.
	Now func() time.Time
	// OnEvent, if set, receives every authorisation decision. It runs on the
	// request goroutine, so an implementation that blocks blocks a push.
	OnEvent func(Event)
	// Store, if set, records every Durable session and its end (durable.go),
	// so another hub process can restore it. Nil keeps sessions in memory
	// only, as every registry did before Task 20383.
	Store SessionStore
	// contains filtered or unexported fields
}

type RestoreRequest struct {
	// Record is the session as its Store recorded it.
	Record SessionRecord
	// Credential is presented upstream on the session's behalf: re-derived by
	// the caller from the grant the session stands on, never read from the
	// record, which has none. CredentialExpiresAt and Refresh are as on
	// MintRequest.
	Credential          Credential
	CredentialExpiresAt time.Time
	Refresh             RefreshFunc
	// OnEnd is as on MintRequest.
	OnEnd func()
	// From names the hub process the session was taken over from, for the
	// restored row.
	From string
}

type Route struct {
	Prefix  string
	Handler http.Handler
}

type ScanFinding struct {
	// Object is the object's id. Empty for a delta, whose id the proxy does
	// not resolve: it would need the base, which may be on the forge.
	Object string `json:"object,omitempty"`
	// Type is commit, tree, blob or tag, or "delta".
	Type string `json:"type"`
	// Base is what a delta is a delta against: an object id, or the pack
	// offset of an object in the same pack whose id is not known.
	Base string `json:"base,omitempty"`
	// Where says which part of the push carries it: "content", "message",
	// "an inserted range", "a ref name", "a push option".
	Where string `json:"where"`
	// Path is where a tree in the same pack names the object: the full path
	// when every tree above it is in the pack whole, or its name alone when
	// only a delta inserting it was seen.
	Path string `json:"path,omitempty"`
	// PathPartial reports that Path is the object's name alone.
	PathPartial bool `json:"path_partial,omitempty"`
	// Commit is the commit that carries the object, when the pack says.
	Commit string `json:"commit,omitempty"`
	// Ref is the ref a finding in the command section is about, or the ref
	// whose tip is named when the carrying commit could not be told.
	Ref string `json:"ref,omitempty"`
	// Tag is an annotated tag's name, for a finding in a tag object.
	Tag string `json:"tag,omitempty"`
	// Grant, Secret and Field are the matched value's provenance; Form is
	// the encoding it was found in ("as delivered", "base64",
	// "percent-encoded", "a line of a PEM block"). A shapes-mode finding
	// carries the detector's label in Field and no grant.
	Grant  string `json:"grant,omitempty"`
	Secret string `json:"secret,omitempty"`
	Field  string `json:"field"`
	Form   string `json:"form,omitempty"`
}

type ScanLimits struct {
	MaxObjectBytes int64
	MaxPushBytes   int64
	MaxDuration    time.Duration
}

type ScanMode string

type ScanSecret struct {
	Value string
	// Grant and Secret name the grant and the secret the run was delivered
	// the value through. Either may be empty for a value no grant carried —
	// the session's own token, or an egress session's.
	Grant  string
	Secret string
	// Field says which part of the delivery it is: "env API_KEY", "the
	// kubeconfig's token for user ci", "the session's upstream token".
	Field string
}

type Session struct {
	// ID identifies the session and is the username half of the basic
	// credential the sandbox presents. Not secret.
	ID string
	// RepoPath is the "owner/name" the sandbox addresses, and the path the
	// proxy serves this session under. Pinning it means a session minted for
	// one repository cannot be replayed against another the same proxy happens
	// to be serving.
	//
	// Empty on a scoped session, where RepoPatterns takes over. See scope.go.
	RepoPath string
	// RepoPatterns is an owner/name glob allowlist. When non-empty the session
	// is *scoped* rather than pinned: it admits every repository the allowlist
	// matches, which is what lets one session stand in for a user's PAT grant
	// whose allowlist the hub cannot enumerate. See scope.go.
	RepoPatterns []string
	// Upstream is the real https clone URL — or, for a scoped session, the
	// forge host base beneath which repository paths are resolved. Either way
	// it never reaches the sandbox, and it is the only source of the host the
	// credential is ever presented to.
	Upstream string
	// ForgeHost is the forge host the session's credential is good against,
	// canonical: github.com, or a GitHub Enterprise Server host (Task 20423).
	// The proxy serves the session on that host's route only (forge.go).
	// Upstream is on this host, except for a scoped github.com session's,
	// which is the hub's to point at github.com or, in a test, a stand-in.
	ForgeHost string
	// Policy is what this session may do.
	Policy Policy

	// Labels for the audit trail.
	ProjectID  string
	TaskID     string
	ExecutorID string
	Actor      string
	// RunID, GrantID and LeaseID say which run the session serves and which
	// grant of which lease its upstream credential stands on (Task 20383): the
	// lease it is closed with, and the record a restore finds it by. None is
	// secret.
	RunID   string
	GrantID string
	LeaseID string

	IssuedAt time.Time
	// contains filtered or unexported fields
}

type SessionRecord struct {
	ID string
	// TokenSHA256 is the hex SHA-256 of the session token.
	TokenSHA256  string
	RepoPath     string
	RepoPatterns []string
	// Upstream is the forge URL or host base; it carries no credential (Mint
	// refuses one with userinfo).
	Upstream string
	// ForgeHost is the forge host the session's credential is good against
	// (Task 20423). A record written before hosts were recorded has none, and
	// reads as github.com for a scoped session and its upstream's host for a
	// pinned one — what it was minted for.
	ForgeHost  string
	Policy     Policy
	ProjectID  string
	TaskID     string
	ExecutorID string
	Actor      string
	RunID      string
	GrantID    string
	LeaseID    string
	IssuedAt   time.Time
	ExpiresAt  time.Time
	// RenewedAt is when Renew last moved ExpiresAt, zero for a session never
	// renewed: what a restore bounds the recorded deadline from (Task 20422).
	RenewedAt time.Time
}

type SessionStore interface {
	// SaveSession records a session this process now serves.
	SaveSession(rec SessionRecord) error
	// CloseSession records that a session this process served has ended,
	// and why. A session another process took over is not this process's to
	// close; an implementation fences the write on its own holder.
	CloseSession(id, reason string, at time.Time) error
	// RenewSession records a session's deadline moved to expiresAt by a
	// renewal at renewedAt, fenced on the holder as CloseSession is.
	RenewSession(id string, expiresAt, renewedAt time.Time) error
}

type Stats struct {
	Pushes    int64 `json:"pushes"`
	Fetches   int64 `json:"fetches"`
	Denied    int64 `json:"denied"`
	BytesUp   int64 `json:"bytes_up"`
	BytesDown int64 `json:"bytes_down"`
}