runner

type AttachOptions struct {
	Cols uint16
	Rows uint16
}

type Capabilities struct {
	Driver                    string                            `json:"driver"`                                // e.g. "docker"
	ConfinementClasses        []types.ConfinementClass          `json:"confinement_classes"`                   // strongest last
	Resolved                  map[types.ConfinementClass]string `json:"confinement_substrates,omitempty"`      // substrate label per class, for /healthz
	StructuralEgress          bool                              `json:"structural_egress"`                     // L0: no default route, sole egress = wardyn-proxy
	NetworkPolicy             bool                              `json:"network_policy"`                        // L1 (nftables / NetworkPolicy default-deny)
	NetworkPolicyAcknowledged bool                              `json:"network_policy_acknowledged,omitempty"` // operator accepted a canary failure as expected rather than proven
	SessionRecording          bool                              `json:"session_recording"`                     // wardyn-rec sidecar support
	// UserDrives and ManagedFiles are fail-closed: false means the control
	// plane refuses rather than admit a request the driver would reject.
	UserDrives   bool `json:"user_drives,omitempty"`
	ManagedFiles bool `json:"managed_files,omitempty"` // can deliver SandboxSpec.ManagedFiles (root-owned, AGENT CANNOT MODIFY)
	// EphemeralDiskEnforcement names what binds Resources.DiskMiB:
	// `filesystem` (docker quota), `eviction` (k8s, never refuses the write),
	// or `none`/empty. Aggregated as the WEAKEST across substrates.
	EphemeralDiskEnforcement types.StorageEnforcement `json:"ephemeral_disk_enforcement,omitempty"`
	// Freeze reports, PER CLASS, pause/resume support; runsc/Kata pause is
	// UNVERIFIED and never claimed here. Callers MUST check per the run's class.
	Freeze map[types.ConfinementClass]bool `json:"freeze,omitempty"`
}

type DriveProbe struct {
	Result DriveProbeResult
	Detail string // operator-facing context; never shown to the member
}

type DriveProbeResult string

type DriveProber interface {
	// ProbeDrive answers whether mount would be readable by the sandbox's
	// uid, bounded by ctx. Called BEFORE a sandbox exists and MUST honour
	// ctx's deadline.
	ProbeDrive(ctx context.Context, mount types.DriveMount) (DriveProbe, error)
}

type DriveReclaimOutcome string

type DriveReclaimer interface {
	// ReclaimDrive destroys the storage object mount names, bounded by ctx.
	// MUST refuse rather than destroy when the object is not this drive's
	// (ErrDriveNotReclaimable) or is still held by a sandbox (ErrDriveInUse),
	// and MUST answer DriveReclaimAlreadyAbsent, not an error, when nothing
	// answers to the name.
	ReclaimDrive(ctx context.Context, mount types.DriveMount) (DriveReclaimOutcome, error)
}

type ExecSession struct {
	// Stdin writes to the exec's stdin. Close HALF-closes the write side only
	// — implementations MUST NOT tear down Stdout/Stderr when Stdin.Close is
	// called.
	Stdin io.WriteCloser
	// Stdout carries standard output; with ExecSpec.TTY=true it ALSO carries
	// stderr — see Stderr.
	Stdout io.Reader
	// Stderr carries standard error as a SEPARATE stream when TTY is false.
	// STREAMING CONTRACT: Stdout and Stderr are UNBUFFERED io.Pipes fed by one
	// demux goroutine off ONE connection — an undrained stderr byte blocks the
	// demux, Stdout, AND Wait. Callers MUST drain Stderr concurrently.
	Stderr io.Reader
	Resize func(cols, rows uint16) error // no-op returning nil with no TTY
	Wait   func() (int, error)
	Close  func() error // tears down ONLY this exec stream — never the sandbox, agent, or any sidecar
}

type ExecSpec struct {
	Argv []string
	Env  []string // additional exec-scoped environment, on top of the sandbox's own
	// TTY requests a pseudo-terminal, which MERGES stdout and stderr onto
	// ExecSession.Stdout — a binary protocol on stdout (SFTP, socat) would be
	// corrupted by interleaved stderr without one.
	TTY        bool
	Cols, Rows uint16 // initial PTY window size (TTY only); zero => implementation default
}

type Freezer interface {
	FreezeSandbox(ctx context.Context, ref string) error
	ThawSandbox(ctx context.Context, ref string) error
}

type ImageChecker interface {
	ImagePresent(ctx context.Context, ref string) (bool, error) // present in the substrate's local image store right now
}

type ImageRemover interface {
	ImageRemove(ctx context.Context, ref string) error // a ref already absent is NOT an error
}

type InjectionGrant struct {
	GrantID uuid.UUID            `json:"grant_id"`
	Rule    egress.InjectionRule `json:"rule"`
}

type ManagedFile struct {
	// Path is the absolute in-sandbox path, already cleaned. See
	// ValidateManagedFiles for the shape both substrates can honour.
	Path string
	// Mode is the file's permission bits. Zero means DefaultManagedFileMode.
	// Group- and other-writable modes are refused: the file would be writable
	// by the agent's own supplementary groups, which defeats the field.
	Mode fs.FileMode
	// Content is the exact file body. Delivered byte for byte; no trailing
	// newline is added.
	Content []byte
}

type Mount struct {
	Source   string `json:"source"`
	Target   string `json:"target"`
	ReadOnly bool   `json:"read_only"`
	// MemberAuthored marks a bind whose SOURCE a MEMBER chose. ONLY these are
	// re-checked against SandboxSpec.UserMountRoots at bind time.
	MemberAuthored bool `json:"member_authored,omitempty"`
	// DriveAuthored marks the ONE bind a driver synthesizes from
	// SandboxSpec.Drive. A LABEL, NEVER A GATE: WARDYN_USER_DRIVE_HOST_ROOTS
	// runs on EVERY host_path drive regardless of this flag.
	DriveAuthored bool `json:"drive_authored,omitempty"`
}

type ProxyConfig struct {
	RunToken          string // authenticates the sidecars to the control plane (NOT usable outside the platform)
	ControlPlaneURL   string // where sidecars stream decisions/recordings
	ControlPlaneCAPEM string // wardynd's internal CA; empty with a loopback http URL only
	// Policy is the run's egress policy, handed verbatim to the wardyn-proxy
	// sidecar. Drivers MUST deliver it at launch: a proxy without a policy
	// fails closed and the sandbox has no working egress at all.
	Policy    types.RunPolicySpec
	Injection []InjectionGrant // auto-mintable api_key grants the proxy resolves at startup (values live only in proxy memory)
	// MITMCACertPEM / MITMCAKeyPEM are the OPTIONAL per-run TLS-MITM CA. The
	// private key reaches ONLY the proxy, never the sandbox. Empty => opaque
	// CONNECT passthrough.
	MITMCACertPEM string
	MITMCAKeyPEM  string
	MITMHosts     []string                  // OPERATOR-CONFIGURED corp hosts the proxy may TLS-MITM; NEVER attacker-controlled
	MITMLLM       bool                      // TLS-MITM of the built-in LLM hosts intended for this run; see proxy.Config.MITMLLM
	GitGrants     map[string]uuid.UUID      // git-broker per-repo allowlist; token stays proxy-side
	PATGrants     map[string]proxy.PATGrant // git_pat broker's per-HOST allowlist; PAT minted proxy-side, never enters the sandbox
	ADOGrant      *proxy.ADOGrantConfig     // per-person Azure DevOps grant for the proxy's REST gate
	// UpstreamProxyURL is the OPTIONAL corporate parent proxy the sidecar
	// chains egress through; control-plane calls bypass it. Empty => direct dial.
	UpstreamProxyURL string
	// TrustedCAPEM is the operator's corporate CA bundle, forwarded so the
	// sidecar's egress TLS additionally trusts it. Empty => system roots only.
	TrustedCAPEM  string
	InternalHosts []types.InternalHost // operator-declared internal hostnames eligible for the proxy's private-IP-guard lift
	// UpstreamProxyNoProxy: hosts/CIDRs whose dials skip the corporate
	// upstream proxy — still faces the private-IP guard and the run's policy.
	UpstreamProxyNoProxy []string
	LLMUpstreams         map[string]string // public vendor host -> operator model gateway base URL
	LLMUnavailableDetail string            // reason for the brokered-LLM 404 when no credential backs it
	Unattended           bool              // a run nobody is driving: a held push is refused instead
}

type ProxyReviver interface {
	CanReplaceProxy(ctx context.Context, ref string) error
	ReplaceProxy(ctx context.Context, ref string, cfgJSON []byte) error
	// EnsureProxyImage pulls the proxy sidecar image if not already present.
	// Called BEFORE the revive claim so a slow pull doesn't widen the window
	// a watcher sweep must leave the run alone in.
	EnsureProxyImage(ctx context.Context) error
}

type ProxyStopper interface {
	StopProxy(ctx context.Context, ref string) error
}

type Resources struct {
	CPUMillis int64
	MemoryMiB int64
	PidsLimit int64 // fork-bomb guard; zero => driver default
	// DiskMiB caps writable storage; WHAT BINDS IT DIFFERS BY SUBSTRATE (see
	// Capabilities.EphemeralDiskEnforcement): docker quotas only when
	// supported, else uncapped; k8s enforces via kubelet EVICTION.
	DiskMiB int64
	// DiskMiBFilled says DiskMiB was FILLED IN from the org default rather
	// than policy-authored: the desktop tier fails closed only for a
	// POLICY-AUTHORED value; a FILLED default degrades to uncapped instead.
	DiskMiBFilled bool
}

type Runner interface {
	Name() string
	Capabilities(ctx context.Context) (Capabilities, error)
	CreateSandbox(ctx context.Context, spec SandboxSpec) (Sandbox, error) // L0 confinement: no default route, egress only via the proxy
	// Exec starts the agent process; returns once started, not finished.
	// Persist agentExecID for restart-safe liveness via AgentStatus.
	Exec(ctx context.Context, ref string, argv []string) (agentExecID string, err error)
	Wait(ctx context.Context, ref string) (exitCode int, err error) // blocks until Exec's process exits; valid only after Exec on the same ref
	// Attach opens a NEW interactive shell, SEPARATE from the agent process.
	// Bounded by the SAME L0 egress envelope (invariant 3); callers MUST
	// record the human principal (invariant 4).
	Attach(ctx context.Context, ref string, opts AttachOptions) (Session, error)
	// ExecStream launches spec.Argv as a fresh, streamable exec. UNLIKE Exec,
	// MUST be repeatable against the SAME ref. SECURITY: opens no new network
	// path (invariant 3); callers MUST record the human principal (invariant 4).
	ExecStream(ctx context.Context, ref string, spec ExecSpec) (*ExecSession, error)
	Status(ctx context.Context, ref string) (Status, error)
	AgentStatus(ctx context.Context, ref, agentExecID string) (Status, error) // restart-safe; falls back to Status when agentExecID is ""
	StopSandbox(ctx context.Context, ref string) error                        // graceful path (lifecycle auto-stop)
	// KillSandbox is the kill-switch path: immediate teardown. The control
	// plane cascades identity + credential revocation around this call.
	KillSandbox(ctx context.Context, ref string) error
}

type Sandbox struct {
	Ref           string // container ID / pod name
	Driver        string
	EnforcedClass types.ConfinementClass // what the driver actually applied (>= requested or error)
}

type SandboxEnder interface {
	EndSandbox(ctx context.Context, ref string) error
}

type SandboxSpec struct {
	RunID            uuid.UUID
	Image            string // resolved agent/workspace OCI image
	ConfinementClass types.ConfinementClass
	// Env is non-secret environment. Credential material NEVER passes through
	// here; it rides SecretEnv.
	Env map[string]string
	// SecretEnv is CREDENTIAL-BEARING environment, DISJOINT from Env. The k8s
	// driver MUST route these through the per-run Secret via
	// ValueFrom.SecretKeyRef (an inline EnvVar.Value is readable by anyone
	// holding pods/get); docker passes them as container env, readable only
	// through the daemon socket — the same trust boundary as the run token.
	SecretEnv map[string]string
	// ProxyConfig wires the L0 path: the sandbox's only egress is the
	// wardyn-proxy sidecar identified here.
	ProxyConfig ProxyConfig
	Resources   Resources         // hard caps (cgroups / ResourceQuota)
	Labels      map[string]string // attached for attestation selectors and audit
	// Mounts are operator/policy-controlled host bind mounts. SECURITY:
	// POLICY-controlled, NEVER attacker-controlled. Drivers bind-mount these
	// AND enforce a deny-list defense-in-depth. Default ReadOnly.
	Mounts []Mount
	// UserMountRoots, non-nil, marks a run whose mounts were MEMBER-authored
	// and carries the roots those mounts must resolve inside, re-checked at
	// BIND time. Nil elsewhere — never narrows an operator mount.
	UserMountRoots []string
	// Drive is the acting principal's USER DRIVE, already resolved by the
	// control plane — nil if none was asked for. NOT a Mount: the request
	// carried a flag rather than a path.
	Drive *types.DriveMount
	// ManagedFiles are operator-authored files the AGENT CANNOT MODIFY —
	// root-owned, unwritable, present BEFORE the main process runs.
	// POLICY-controlled. A driver that doesn't advertise
	// Capabilities.ManagedFiles MUST refuse rather than start without them.
	ManagedFiles []ManagedFile
	// OnWaiting, non-nil, reports WHY the sandbox isn't up yet, each time the
	// reason CHANGES. Called SYNCHRONOUSLY on CreateSandbox's own goroutine
	// (must not block). Call NotifyWaiting, never the field.
	OnWaiting func(detail string) `json:"-"`
	// Interactive marks a run that comes up idle for `wardyn run attach`; a
	// driver prepares the workspace on the idle main process for it.
	Interactive bool
}

type SandboxStarter interface {
	StartSandbox(ctx context.Context, ref string) error
}

type Session interface {
	Read(p []byte) (int, error)                          // io.EOF when the shell exits or closes
	Write(p []byte) (int, error)                         // sends keystrokes
	Resize(ctx context.Context, cols, rows uint16) error // new PTY window size
	// Close tears down ONLY the interactive exec stream — not the sandbox,
	// the agent process, or any sidecar.
	Close() error
}

type Status struct {
	State    types.RunState
	ExitCode *int
	Message  string
}

type UserMountPolicy struct {
	// Roots is the shared allowlist (WARDYN_USER_WORKSPACE_ROOTS): absolute,
	// cleaned host prefixes any member's local_dir source must resolve into.
	Roots []string
	// RootsByPrincipal (WARDYN_USER_WORKSPACE_ROOTS_MAP) is the per-member
	// override. A principal with an entry uses ONLY that entry — per-member
	// REPLACES shared, since it exists to be the more restrictive control,
	// and a union would make adding a row widen rather than narrow. Keys are
	// lowercased principals (OIDC sub or email).
	RootsByPrincipal map[string][]string
	// WritableRoots (WARDYN_USER_WRITABLE_ROOTS) is where a member may mark
	// their own mount writable. Empty = nowhere.
	WritableRoots []string
	// WritableDeny (WARDYN_USER_WRITABLE_DENY) carves holes in WritableRoots.
	// Deny WINS over allow, and is checked first.
	WritableDeny []string
}