wrap

type Config struct {
	Profile profile.Profile
	Runtime runtime.Runtime

	// RawName is the session name as typed; Slug is its path-safe form. The
	// raw name reaches the agent as its display name, so what you typed is
	// what you see; only the paths use the slug.
	RawName string
	Slug    string

	Workspace string
	// EphemeralHome is set when brig chose Workspace because the run named
	// none. `brig rm` deletes such a home with the sandbox.
	EphemeralHome bool
	// RemovedHome is the home Remove deleted, or "" when it kept one.
	RemovedHome string
	// HomeErr is why Remove could not delete an ephemeral home, or nil.
	HomeErr error

	VMName string
	// HostConfig are host directories seeded into the workspace, empty unless
	// the run opted in. See hostProjections.
	HostConfig []hostSeed
	Image      string
	Pull       string
	Mem        int
	CPUs       int

	// ReadyTimeout is how long to wait for the guest agent after the runtime
	// reports the sandbox running. The two are not the same moment: the VMM
	// process is up several seconds before the in-guest agent binds its
	// listener.
	ReadyTimeout time.Duration

	// Env is what the guest sees, with BRIG_FORWARD_ENV already applied. See
	// envOverride for what that override does and does not reach. The
	// requirement list it may read from stays on Profile: one list, one place.
	Env []profile.EnvBinding
	// OpenStore returns the secret store, and is called only when the profile
	// declares secrets -- opening it unconditionally would raise a keychain
	// prompt for runs that read nothing. Replaced in tests.
	OpenStore func() (creds.SecretReader, error)
	// MacOSVersion reports the host's macOS version like "14.5", or "" off
	// macOS. A field so a test can pin the version the hypervisor preflight
	// sees without running on the OS in question; Load sets it to the real
	// host reader. See preflightHypervisor.
	MacOSVersion func() string

	GitConfig       bool
	GitHosts        []string
	GitIdentity     bool
	GitUser         string
	GitUserFromHost bool
	GitName         string
	GitEmail        string

	TrustWorkspace bool

	// Verify is how strictly the guest image is checked before boot, and
	// VerifyPolicy is what counts as ours.
	Verify       verify.Mode
	VerifyPolicy verify.Policy
	// RuntimePolicy is who signs the Linux runtime bundle's releases, whose
	// record vouches for the kernel and initrd the bundle carries. A zero
	// value is the bundle's own release workflow.
	RuntimePolicy verify.Policy
	// Network is the posture this run was resolved to, which is the one the
	// next boot gets. Held here so the envelope, the report and the spec
	// handed to the runtime cannot disagree about what a reader was told. A
	// sandbox already up can run with another; see networkLine.
	Network Network

	// Publish is every guest port this sandbox offers on the host: what
	// --publish asked for on this line, and what the sandbox was already
	// publishing. PublishAsked is the first half alone.
	//
	// A publication belongs to the sandbox rather than to one run of it, so a
	// later `brig run` with no --publish keeps what is already published. The
	// envelope names all of them on every run, which is what keeps that from
	// being a hole nobody was told about.
	Publish      []runtime.Publication
	PublishAsked []runtime.Publication
	// Egress is the merged rule set of every policy bound to this run, and
	// Policies the names it came from. Empty Egress.Default means no policy
	// applies, which is every run before one is attached.
	//
	// Resolved with the posture above rather than at boot, because a policy
	// decides the posture: see the note there.
	Egress   policy.Egress
	Policies []string
	// BootDigest is the registry digest verifyDigest resolved and checked, set
	// only on a runtime that boots by digest. EnsureRunning hands it to the
	// runtime so the object that boots is the object that verified; empty means
	// boot the tag as given, which is every hull run and any path that could not
	// resolve a digest.
	BootDigest string

	AllowRefs   bool
	AllowDenied bool
	// Cwd is the host directory the command was invoked from, and GuestCwd is
	// where that lands inside the guest.
	Cwd      string
	GuestCwd string

	// Project is the host directory this run was told to mount beside the
	// guest home, and GuestProject is where it lands in the guest. Both are
	// empty on a run that named none, which is what every path below reads to
	// tell the two shapes apart.
	//
	// A second mount rather than a redirection of the first, because the guest
	// home IS the agent's home: its dotfiles, its onboarding state, its
	// caches. Pointing that mount at a repository would put all of it in the
	// repository. So the home stays brig's own and the project arrives
	// alongside it, outside the home -- see GuestProject.
	//
	// Per run, not per session: the session's identity is its ref, which is
	// the agent and the label, which is the home. Two runs of one session on
	// two projects are the same session, so nothing here reaches the sandbox
	// name or the slug. See mountProject and sessionEntry.
	Project      string
	GuestProject string

	// ProjectReal is the project with every link resolved. It is what the
	// PROJECT row prints. Project is what the runtime is handed, and
	// mountProject says why the two reach the same directory.
	ProjectReal string

	// NoTerminal declares that this run has no terminal to put a question to,
	// whatever this process's own stdin happens to be. brigd sets it: started
	// from a shell its stdin is a terminal, but it is the daemon's terminal and
	// not the client's, so a question asked there is asked of nobody while the
	// caller waits for an answer that cannot arrive. See confirm.
	NoTerminal bool

	Out io.Writer
	Err io.Writer

	// Progress is where the run narrates what it is doing -- the line that says
	// a boot has started, and nothing that anybody has to act on.
	//
	// Separate from Err because a caller that collects what a run said and
	// hands it to somebody else has to be able to tell the two apart. brigd is
	// that caller: it returns Err to the client as the request's warnings, and
	// with the narration in there a boot that went perfectly came back carrying
	// "starting sandbox ..." as a warning about itself. On a terminal the
	// distinction does not arise, both being lines on the same stderr, which is
	// why it went unnoticed for as long as the CLI was the only caller.
	Progress io.Writer

	// Verbosity decides how much of the above is written. See the type: Err
	// carries warnings and goes quiet only under -q, and Progress carries
	// narration and stays empty until --verbose asks for it. Out is not
	// levelled -- it is the report `brig info` was asked for by name.
	Verbosity Verbosity
	// contains filtered or unexported fields
}

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

type InfoCredential struct {
	Name   string `json:"name"`
	Source string `json:"source,omitempty"`
}

type InfoDeny struct {
	Off       bool     `json:"off"`
	Forwarded []string `json:"forwarded,omitempty"`
	Withheld  []string `json:"withheld,omitempty"`
}

type InfoDocument struct {
	Session     string           `json:"session,omitempty"`
	Profile     string           `json:"profile"`
	Sandbox     string           `json:"sandbox"`
	Runtime     InfoRuntime      `json:"runtime"`
	Isolation   string           `json:"isolation"`
	Workspace   string           `json:"workspace"`
	Project     *InfoProject     `json:"project,omitempty"`
	Image       InfoImage        `json:"image"`
	Verify      InfoVerify       `json:"verify"`
	Network     string           `json:"network"`
	Credentials []InfoCredential `json:"credentials"`
	Deny        *InfoDeny        `json:"deny,omitempty"`
	Git         InfoGit          `json:"git"`
	// ArgvExposed is the values BRIG_ENV_ARGV would put on the runtime's command
	// line, by name. Empty -- and omitted -- when the hatch is off, which is the
	// default. The names are variable names, never values.
	ArgvExposed []string         `json:"argvExposed,omitempty"`
	GuestLogin  []InfoGuestLogin `json:"guestLogin,omitempty"`
	Identity    *InfoIdentity    `json:"identity,omitempty"`

	// ProjectRefused is why the project this session remembers was not
	// mounted, and so why Project is absent. It is omitted when nothing was
	// refused, so a script can tell a refusal from a run with --no-project.
	ProjectRefused string `json:"projectRefused,omitempty"`
}

type InfoGit struct {
	Enabled bool     `json:"enabled"`
	User    string   `json:"user,omitempty"`
	Hosts   []string `json:"hosts,omitempty"`
}

type InfoGuestLogin struct {
	Name    string `json:"name,omitempty"`
	Source  string `json:"source,omitempty"`
	Expired bool   `json:"expired,omitempty"`
}

type InfoIdentity struct {
	Cwd   string `json:"cwd"`
	Name  string `json:"name,omitempty"`
	Email string `json:"email,omitempty"`
}

type InfoImage struct {
	Ref  string `json:"ref"`
	Pull string `json:"pull"`
}

type InfoProject struct {
	// Host is the path as typed, which is what the runtime is handed. The
	// envelope's PROJECT row prints the directory it resolves to, and the two
	// differ only above the trusted split, as /tmp and /private/tmp do on
	// macOS. See mountProject.
	Host  string `json:"host"`
	Guest string `json:"guest"`
}

type InfoRuntime struct {
	Kind      string `json:"kind,omitempty"`
	Bin       string `json:"bin,omitempty"`
	Available bool   `json:"available"`
}

type InfoVerify struct {
	Mode   string `json:"mode"`
	Policy string `json:"policy"`
}

type Network string

type Notices struct {
	// W is where the warnings go. nil is the process's stderr, read at each
	// write, so a test that swaps os.Stderr sees them.
	W io.Writer
	// NoTerminal says W has no person reading it, whatever it is. See
	// Config.NoTerminal.
	NoTerminal bool
	// contains filtered or unexported fields
}

type Options struct {
	Name      string // session name, as typed
	Image     string
	Workspace string
	// Project is the directory named as run's positional argument, to be
	// mounted beside the guest home. Relative is fine: it is resolved against
	// the directory the command was invoked from, because `brig run claude .`
	// is the line the positional exists for.
	Project string
	// NoProject asks for this run to have no project at all, and is the only
	// way to say so once a project is remembered: a positional names a
	// directory, and no directory names absence. Without it a session handed a
	// project keeps it for the rest of its life, since every later flagless
	// verb inherits it.
	NoProject bool
	Mem       int
	CPUs      int
	// Skills opts in to projecting the host's own agent config (skills,
	// plugins) read-only into the guest. Off unless asked for: it is the
	// user's real config, and handing it to a sandbox should be a decision.
	Skills bool
	// Network is the posture asked for on the command line, and beats both the
	// setting and the profile. Empty means nothing was asked for.
	Network string
	// Publish are the --publish values on the command line, unparsed. Each opens
	// a guest port on the host; see runtime.ParsePublication for the grammar.
	Publish []string
	// Verbosity is how much this invocation was asked to say: --verbose and
	// -q, which are read left of the verb. The zero value is the default
	// level, so a caller with no opinion -- brigd, and every test that builds
	// Options by hand -- gets what a person reads.
	Verbosity Verbosity
}

type PlanCredential struct {
	Name     string `json:"name"`
	Delivery string `json:"delivery"`
	Source   string `json:"source,omitempty"`
	Secret   string `json:"secret,omitempty"`
	Required bool   `json:"required"`
	State    string `json:"state"`
	Reason   string `json:"reason,omitempty"`
}

type PlanDocument struct {
	Session string `json:"session,omitempty"`
	Profile string `json:"profile"`
	Sandbox string `json:"sandbox"`
	// Refused is why `brig run` refuses this run, from the checks it makes
	// before it prepares anything that a plan can ask without writing (see
	// Plan), and absent when none of them refuses. The plan still describes
	// the run, and the command still exits 0.
	Refused   *PlanRefusal `json:"refused,omitempty"`
	Runtime   PlanRuntime  `json:"runtime"`
	Isolation string       `json:"isolation"`
	Home      PlanMount    `json:"home"`
	Project   *PlanMount   `json:"project,omitempty"`
	// ProjectRefused is why the project this session remembers is not
	// mounted, as in the Info payload. Refused carries the same reason,
	// because the run stops on it.
	ProjectRefused string `json:"projectRefused,omitempty"`
	// Skills are the host directories --skills copies into the guest home.
	Skills []PlanMount `json:"skills"`
	Image  InfoImage   `json:"image"`
	Verify InfoVerify  `json:"verify"`
	// Network is the sentence the Info payload carries, and Posture the word
	// for the next boot, or unknown when the run refuses a sandbox whose
	// network brig cannot read.
	Network string   `json:"network"`
	Posture string   `json:"posture"`
	Ports   []string `json:"ports"`
	// Policies names every policy bound to this run. NoPolicy says none is,
	// so a reader does not have to infer it from an empty list.
	Policies    []string         `json:"policies"`
	NoPolicy    bool             `json:"noPolicy"`
	Egress      *PlanEgress      `json:"egress,omitempty"`
	Credentials []PlanCredential `json:"credentials"`
	// ArgvExposed names what the Info payload's field of the same name
	// names: the values BRIG_ENV_ARGV would put on the runtime's command
	// line. Sorted, where info keeps the order the run adds them in, because
	// the order of a profile's bindings is not a permission. Omitted when the
	// setting is off, which is the default.
	ArgvExposed []string   `json:"argvExposed,omitempty"`
	Limits      PlanLimits `json:"limits"`
	// Digest is sha256 over the compact encoding of this document with
	// Digest empty. See planDigest.
	Digest string `json:"digest"`
}

type PlanEgress struct {
	Default string        `json:"default"`
	Allow   []policy.Rule `json:"allow"`
	Deny    []policy.Rule `json:"deny"`
}

type PlanLimits struct {
	Mem  int `json:"mem"`
	CPUs int `json:"cpus"`
}

type PlanMount struct {
	Host  string `json:"host"`
	Guest string `json:"guest"`
	Mode  string `json:"mode"`
}

type PlanRefusal struct {
	// Reason is the refusal as `brig run` prints it.
	Reason string `json:"reason"`
}

type PlanRuntime struct {
	InfoRuntime
	Backend string `json:"backend,omitempty"`
}

type Verbosity int

type VerifyRefusedError struct{ Err error }