sandbox

type Availability struct {
	// CanEnforce is false when the backend cannot enforce at all (binary
	// missing, wrong OS, kernel too old, version below the pin). The daemon
	// must fail closed in that case.
	CanEnforce bool
	// Degraded is true when enforcement works but some controls are missing
	// (e.g. Landlock present but no network-filtering ABI). Filesystem
	// confinement still holds; the daemon runs but should surface the state.
	Degraded bool
	// Detail is a human-readable explanation for logs / doctor / errors.
	Detail string
}

type Backend interface {
	// Name is the config value that selects this backend.
	Name() string
	// Availability reports whether this backend can enforce on this host now,
	// given the controls the policy requires. command overrides the backend
	// binary; empty uses the backend default.
	Availability(command string, req Requirements) Availability
	// Wrap returns the command and args to exec so the child runs sandboxed.
	Wrap(command string, args []string, opts WrapOpts) (string, []string, error)
}

type Denial struct {
	// Time is the log timestamp (best-effort: the leading date+time of the
	// compact log line), empty if it couldn't be located.
	Time string
	// Process is the name of the process whose access was denied.
	Process string
	// PID is that process's PID, used to filter by a session's process tree.
	PID int
	// Operation is the Seatbelt operation, e.g. "file-read-data",
	// "network-outbound", "mach-lookup".
	Operation string
	// Path is the target resource (a filesystem path for file-* operations),
	// possibly empty for operations that don't name one.
	Path string
	// Raw is the full log line, kept so nothing is lost if parsing is partial.
	Raw string
}

type DenialGroup struct {
	Process   string
	Operation string
	Path      string
	Count     int
	LastTime  string
	LastPID   int
}

type NetworkPolicy struct {
	// Block denies all outbound network (nono network.block = true).
	Block bool
	// AllowDomains is the L7 proxy allowlist (nono network.allow_domain).
	AllowDomains []string
}

type Requirements struct {
	// Network is true when a network policy is requested. On Linux this
	// requires Landlock ABI v4; a host that only supports filesystem
	// enforcement must fail closed rather than pretend to block egress.
	Network bool
}

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

type WhyQuery struct {
	// Path + Op form a filesystem query.
	Path string
	Op   string // "read", "write", or "readwrite"

	// Host + Port form a network query.
	Host string
	Port int
}

type WhyResult struct {
	Status       string `json:"status"`
	Reason       string `json:"reason,omitempty"`
	Details      string `json:"details,omitempty"`
	Access       string `json:"access,omitempty"`
	GrantedPath  string `json:"granted_path,omitempty"`
	Source       string `json:"source,omitempty"`
	PolicySource string `json:"policy_source,omitempty"`
	SuggestFlag  string `json:"suggested_flag,omitempty"`
}

type WrapOpts struct {
	// Backend selects the sandbox backend. Empty is invalid at the daemon
	// layer (backend must be chosen explicitly); Wrap defaults it to safehouse
	// for backward compatibility of the low-level helper.
	Backend string

	WorktreeDir string
	ReadDirs    []string
	WriteDirs   []string
	// ReadFiles / WriteFiles grant single files rather than whole directories,
	// for paths that can't be a directory grant without over-sharing (notably
	// single files directly in $HOME, e.g. an agent's ~/.claude.json). Paths are
	// already ~/glob-expanded and absolute. ReadFiles is read-only (nono
	// filesystem.read_file); WriteFiles is read+write (nono filesystem.allow_file,
	// like WriteDirs → allow, not the write-only filesystem.write). The safehouse
	// backend folds them into its read-only / read-write dir lists.
	ReadFiles  []string
	WriteFiles []string
	// UnixSockets grants connect access to existing Unix domain sockets (e.g.
	// the graith daemon socket, so a sandboxed agent can reach the daemon for
	// `gr msg`, `gr status`, etc.). Connecting to a socket is NOT file access:
	// both Seatbelt and Landlock classify it as network egress, so neither a
	// read-only nor a read/write path grant permits it. nono maps these to
	// filesystem.unix_socket (the same field the "ssh" feature uses for
	// $SSH_AUTH_SOCK). safehouse has no socket flag, so the backend emits a
	// Seatbelt fragment with `(allow network-outbound (remote unix-socket …))`
	// and appends it via --append-profile. Paths are already absolute.
	UnixSockets []string
	Features    []string
	EnvKeys     []string

	// SignalMode maps to nono's security.signal_mode ("isolated",
	// "allow_same_sandbox", "allow_all"). Empty inherits nono's default. The
	// safehouse backend ignores it.
	SignalMode string

	// Profile (nono only) is the base profile the generated profile extends
	// (nono's "extends" field). Empty means "default" (nono's audited deny
	// groups + base system paths). A maintained registry profile such as
	// "always-further/claude" inherits that agent's upstream file grants. nono
	// MERGES the base with graith's generated profile — collection fields
	// (filesystem.allow/read, environment.allow_vars, …) are unioned, so
	// graith's grants are always present but its env allowlist can only widen
	// the base profile's, never narrow it. A custom base profile is only as
	// tight as the operator has audited it. The safehouse backend ignores it.
	Profile string

	// Network is the optional egress policy. Nil means no network restriction
	// (nono is allow-by-default). When set, the nono backend emits a
	// network.block / network.allow_domain section; the safehouse backend has
	// no network primitive and warns that it cannot enforce it.
	Network *NetworkPolicy

	// BackendCommand overrides the backend binary name/path. Empty means the
	// backend's own default ("safehouse" / "nono"). Formerly SafehouseCommand.
	BackendCommand string

	// ProfilePath, for the nono backend, is where the generated per-session
	// profile is written. The daemon points it under RuntimeDir so it is
	// readable inside the sandbox and survives for the process lifetime and
	// resume. Empty means the backend writes to an os.CreateTemp file.
	ProfilePath string

	// SafehouseFragmentPath, for the safehouse backend, is where the generated
	// per-session Seatbelt fragment (the --append-profile file granting
	// unix-socket connect access) is written. Like ProfilePath the daemon points
	// it under RuntimeDir so it survives resume and is cleaned up on delete;
	// empty means the backend writes to an os.CreateTemp file. Used whenever any
	// socket needs a connect grant: opts.UnixSockets (e.g. the daemon socket)
	// and/or $SSH_AUTH_SOCK when the "ssh" feature is enabled. A caller that
	// grants a socket but leaves this empty (e.g. a sandboxed MCP server that has
	// the "ssh" feature but no daemon-socket grant) gets an os.CreateTemp
	// fragment, mirroring the nono temp-profile fallback for path-less callers.
	SafehouseFragmentPath string
}