exec

type Command ¶

type Command struct {
	Name      string    // resolved to an absolute path before escalation
	Args      []string  // operands; the caller pre-applies SeparatePositionals
	Dir       string    // "" = inherit cwd
	Env       []string  // extra KEY=VALUE; screened by the env hijack blocklist
	Stdin     io.Reader // "" = no stdin
	ChildPath string    // explicit, isolating child PATH; "" = inherit/sanitized
	Escalate  bool      // run through the privilege backend
}

Command describes one execution. The zero value is invalid — Name is required. The capability layer fills this in and sets Escalate per operation; it is escalation-method-agnostic. The Runner alone turns Escalate into the concrete sudo/doas/bare invocation.

There is no locale knob: the Runner ALWAYS forces a deterministic environment (LC_ALL=C, LANG=C, NO_COLOR=1) on every command so the SDK's parsing of tool output is locale/format-stable by construction. It is not overridable — those names are rejected if passed via Env. (TZ is deliberately left to the device.)

type CommandError ¶

type CommandError struct {
	Name     string // the command that failed, e.g. "useradd"
	ExitCode int
	Stderr   string
	Err      error // underlying cause, if any
}

CommandError is the typed error the capability layer wraps a failed command in (Decision 3). The Runner itself does NOT treat a non-zero exit as an error (callers branch on specific codes — cryptsetup 2 = wrong passphrase, etc.); the capability layer decides when a non-zero exit becomes a CommandError. It carries the exit code and captured stderr so callers can branch on them via errors.As without importing internals.

func (e *CommandError) Error() string

func (e *CommandError) Unwrap() error

type OutputCallback ¶

type OutputCallback func(streamType StreamType, line string, seq int64)

OutputCallback is called for each line of output during streaming execution. streamType is the typed StreamType (Go's type system rejects implicit int↔StreamType conversion, so taking int here would mean every comparison needed an explicit cast). line is the output line including its trailing newline. seq is a stream-local monotonic ordering counter.

type PrivilegeBackend ¶

type PrivilegeBackend int

PrivilegeBackend selects how a Runner escalates privilege for a Command whose Escalate flag is set. The zero value is INVALID (fail-closed): NewRunner rejects it with ErrUnknownBackend. Valid values start at 1 (Decision 5/6).

const (
	// Sudo escalates via `sudo -n` (non-interactive; never prompts).
	Sudo PrivilegeBackend = iota + 1
	// Doas escalates via `doas -n`.
	Doas
	// Direct runs with no wrapper — the process is already root. Rolling our
	// own no-op pass-through avoids sudo's distro-varying "root must be in
	// sudoers" check (opensuse rejects it by default) and the cost of forking
	// sudo just to re-exec the same binary.
	Direct
)

func Detect(ctx context.Context) []PrivilegeBackend

type Result ¶

type Result struct {
	ExitCode int
	Stdout   string
	Stderr   string
}

Result holds the output of a command execution.

type Runner ¶

type Runner interface {
	// Run executes c and returns its captured output. A non-zero exit is
	// reported in Result.ExitCode, NOT as an error; a non-nil error means the
	// command could not be executed (binary not found, blocked env var, ctx
	// cancelled) or escalation failed (ErrEscalation*).
	Run(ctx context.Context, c Command) (Result, error)
	// Stream is Run with real-time line delivery via onLine.
	Stream(ctx context.Context, c Command, onLine OutputCallback) (Result, error)
	// Backend reports the privilege backend, so a capability (e.g. fs) can pick
	// its fd-safe vs sudo code path.
	Backend() PrivilegeBackend
}

Runner abstracts command execution + privilege escalation. It is injected into every capability constructor (Decision 2) so the SDK keeps no global escalation state and the whole capability layer is unit-testable with a fake (see exectest.FakeRunner) — no host, no sudo, no container.

func NewRunner(b PrivilegeBackend) (Runner, error)

type Secret ¶

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

Secret wraps a sensitive string such as a password or private key so it cannot reach a log or formatted string by accident: String, GoString, and the %v/%s/%#v verbs all render "[REDACTED]". The plaintext is retrievable only via Reveal.

func NewMultilineSecret(v string) Secret

func NewSecret(v string) (Secret, error)

func (s Secret) GoString() string

func (s Secret) HasNewline() bool

func (s Secret) IsZero() bool

func (s Secret) Reveal() string

func (s Secret) String() string

type StreamType ¶

type StreamType int

StreamType identifies which standard stream a line of streaming output came from. The named type lets the compiler reject a stray `int` literal where the contract is "stdout or stderr". Numeric values are stable across SDK releases.

const (
	// StreamStdout is the streamType passed to OutputCallback for
	// stdout lines.
	StreamStdout StreamType = 1
	// StreamStderr is the streamType passed to OutputCallback for
	// stderr lines.
	StreamStderr StreamType = 2
)