install

type Artifact struct {
	// Path is absolute on the device (before any Installer.Root prefix).
	Path string
	// Mode is the file's permission bits.
	Mode os.FileMode
	// Content is the file body.
	Content string
	// Secret marks content that must never be logged, printed by --dry-run,
	// or written world-readable.
	Secret bool
	// Owned marks a file that should be chowned to the service user.
	Owned bool
}

type BinaryIdentity struct {
	// Version is the build version it reported, e.g. "v0.1.0" or
	// "dev+g4f7b5bc". Never empty for a successful probe.
	Version string
	// Protocol and MinProtocol are the executor-agent protocol versions it
	// speaks. Zero means it did not report them — a build older than the
	// machine-readable version report. Zero is "unknown", never "none": a
	// caller must not read it as "speaks no protocol".
	Protocol, MinProtocol int
	// OS and Arch are the platform it was built for, empty when unreported.
	OS, Arch string
	// Commit is the full commit it says it was built from, and Sequence that
	// commit's first-parent position on main (Task 20380). Empty and zero for
	// a build that does not report them — a developer's unstamped build, and
	// every build made before builds were stamped with a sequence. Zero is
	// "carries none", never "position zero".
	Commit   string
	Sequence int
	// Structured records that the machine-readable form was available, which
	// is what makes the protocol fields meaningful.
	Structured bool
}

type BootstrapParams struct {
	// Server is the WebSocket URL agents dial, e.g.
	// wss://cloop.example.com/api/executors/connect.
	Server string
	// Pin is the hub's SPKI fingerprint, or "" when the hub has no
	// configured certificate. An empty pin makes the script say so rather
	// than quietly install an unpinned agent.
	Pin string
	// ServiceName overrides the installed unit's name.
	ServiceName string

	// HubVersion and HubProtocol are the build the hub runs and the executor
	// protocol it speaks (Task 20421). The script refuses to install an agent
	// that speaks an older protocol — one it downloads, one already on the
	// device, or CLOOP_BIN — because such an agent connects and is then
	// refused everything the hub needs the newer protocol for. A HubProtocol
	// of zero leaves the check out.
	HubVersion  string
	HubProtocol int
	// EdgeCommit is the full commit of the hub's own build when CI signed and
	// published it on the edge channel: what `--channel edge` installs. Empty
	// when there is none, and EdgeUnavailable then says why, for the script's
	// refusal of --channel edge.
	EdgeCommit      string
	EdgeUnavailable string
}

type Dir struct {
	Path string
	Mode os.FileMode
}

type Installer struct {
	// Root prefixes every path. Empty means the real filesystem root.
	// A non-empty Root also disables command execution entirely: a staged
	// install describes a device that is not this machine, so running
	// systemctl or useradd against this one would be wrong even if it
	// happened to work.
	Root string

	// Run executes a command. Nil uses exec.Command. Ignored when Root is
	// set.
	Run Runner

	// Exec runs a candidate cloop binary during upgrade verification. Nil
	// uses exec.CommandContext; a staged installer with no Exec skips
	// verification rather than running a binary built for another machine.
	Exec Prober

	// Logf receives progress messages. Nil discards them.
	Logf func(format string, args ...any)
}

type Output string

type PacketFilterChange int

type Plan struct {
	Output Output
	Spec   Spec

	// Dirs are created before Artifacts are written.
	Dirs []Dir

	// Artifacts are the files to write.
	Artifacts []Artifact

	// Display is the operator-facing rendering for --dry-run. It never
	// contains credential material.
	Display string

	// Next lists the follow-up steps Apply performs (or that the operator
	// must perform when the plan targets a system this machine is not).
	Next []string

	// Remove lists files an earlier install may have left that this plan must
	// not keep — today, the packet-filter drop-in of a device now installed
	// without it. Absent files are fine: removing is about the state after.
	Remove []string
}

type Prober func(ctx context.Context, path string, args ...string) ([]byte, error)

type RemoteUpgradeChange int

type Runner func(name string, args ...string) error

type Spec struct {
	// ServiceName names the unit, the container, the init script, the
	// system user's home and the state directory. One name so an operator
	// greps for one string.
	ServiceName string

	// User and Group own the credential file and run the process. Empty
	// defaults to ServiceName.
	User  string
	Group string

	// BinaryPath is the cloop binary on the device.
	BinaryPath string

	// StateDir holds the credential file, the agent's long-lived identity,
	// and (by default) the workload root. Empty defaults to
	// /var/lib/<ServiceName>.
	StateDir string

	// UnitDir is where the systemd unit is written. Empty defaults to
	// /etc/systemd/system.
	UnitDir string

	// InitDir is where the OutputShell init script is written. Empty defaults
	// to /etc/init.d.
	//
	// It exists for the same reason UnitDir does. Without it the shell output
	// was the one artifact in this package with no redirectable destination,
	// which made every OutputShell path untestable except against the real
	// /etc/init.d: as root a test would overwrite the host's own service
	// script, and as anyone else it failed outright.
	InitDir string

	// CredentialsFile is the 0600 file the enrollment material is written
	// to. Empty defaults to <StateDir>/enrollment.
	//
	// There is deliberately no way to put the token on the command line
	// instead: a flag that inlines a credential into ExecStart is a flag
	// that will be used, and the resulting unit is world-readable.
	CredentialsFile string

	// AgentCredential is where the agent persists the long-lived identity
	// it receives in exchange for the enrollment token. Empty defaults to
	// <StateDir>/agent.json.
	AgentCredential string

	// WorkDirRoot confines every workload on the device. Empty defaults to
	// <StateDir>/work.
	WorkDirRoot string

	// Server is the control-plane WebSocket URL the agent dials.
	Server string

	// Pin is the hub's SPKI fingerprint ("sha256:<base64>", comma-separated
	// to stage a key rotation). Empty means ordinary PKI verification, which
	// is a real downgrade — see remote.Bundle.
	Pin string

	// Bundle is the encoded enrollment bundle (server + token + pin in one
	// blob). Either this or Token must be set for a first install; both are
	// empty when re-installing over an agent that already holds a
	// credential.
	Bundle string

	// Token is a bare enrollment token, for an operator who has one without
	// a bundle.
	Token string

	// RootCAFile is a PEM bundle to trust in addition to the system store,
	// for a hub behind a private CA.
	RootCAFile string

	// MaxConcurrent bounds simultaneous workloads. Zero lets the agent
	// choose (number of CPUs).
	MaxConcurrent int

	// Labels are scheduler selectors baked into the unit.
	Labels map[string]string

	// Image is the container image for OutputDocker.
	Image string

	// NoStart installs the unit without enabling or starting it, for
	// golden-image builds where the device must not enroll until first boot.
	NoStart bool

	// PacketFilter grants the agent what it needs to install a virtual
	// executor's IP firewall on the host (Task 20345): CAP_NET_ADMIN, and the
	// netlink socket family nft(8) speaks. It is written as a drop-in beside
	// the unit (PacketFilterDropIn) rather than into it, and a plan without it
	// removes a drop-in an earlier install or upgrade left, so the flag always
	// describes the device afterwards. systemd output only.
	//
	// `cloop executor agent install` grants it unless told
	// --packet-filter=false (Task 20352): a device that cannot install a
	// firewall refuses every sandbox that has one, and the grant stays with
	// the agent — pkg/caps keeps it from every program the agent starts except
	// nft(8), so a workload never holds it. The zero value withholds it, for
	// callers that build a Spec themselves.
	PacketFilter bool

	// RemoteUpgrade installs the root helper that carries out an upgrade the
	// hub asked the agent for (Task 20376): <service>-upgrade.service and the
	// .path unit that starts it when the agent files a request. Without it a
	// device installed with the hardened defaults cannot be upgraded from the
	// Executors panel or by auto-update — the agent cannot replace a
	// root-owned binary or restart itself — and it says so when asked.
	// systemd output only. `cloop executor agent install` installs it unless
	// told --remote-upgrade=false; the zero value withholds it.
	RemoteUpgrade bool

	// Channel is the update channel the device follows (Task 20376). Empty or
	// stable: releases only, and no drop-in. Edge: the channel drop-in, which
	// lets the device be upgraded to signed builds of main as well. systemd
	// output only, and decided here, on the device: the hub has no way to
	// set it.
	Channel provenance.Channel
}

type UpgradeOptions struct {
	// Source is the new cloop binary to install. Empty means the running
	// executable, which is the common case: an operator copies a new cloop to
	// the device and runs it with --upgrade.
	Source string
	// Force replaces the binary and restarts the service even when the
	// installed binary is already byte-identical. For recovering from a
	// truncated or mis-permissioned install, where the bytes match but the
	// service is not actually running the binary on disk.
	//
	// It also permits a deliberate rollback: installing a build older than
	// the one in place, or one speaking a protocol this control plane no
	// longer accepts. It does *not* permit installing a binary that failed
	// verification — see ErrBinaryUnusable for why that line is where it is —
	// nor one earlier on main than the installed binary, which takes
	// AllowRollback.
	Force bool

	// AllowRollback permits installing a build whose sequence is lower than
	// the installed binary's, or one carrying none when the installed binary
	// does (ErrRollback, Task 20380).
	//
	// It is not Force, because Force arrives from places that must not be able
	// to do this: the upgrade request the agent files for the root helper, and
	// the upgrade frame the hub sends an agent running as root, both carry a
	// force flag, and a compromised agent or hub could set either. Only the
	// CLI sets this, from --force on an `install --upgrade` run by root on the
	// device — never from --apply-request, whose target the request names.
	AllowRollback bool
	// DryRun performs every check and reports what would happen without
	// writing a byte or restarting anything.
	//
	// It is a real mode rather than a courtesy, because this command bounces a
	// service on a device an operator may not be able to reach again quickly.
	// The checks it runs are the expensive ones — is anything installed, does
	// the source exist, is it even a different build, does the new binary run
	// at all — so a dry run answers "will this do what I think" rather than
	// merely echoing the flags back.
	DryRun bool

	// Bundle is the Sigstore bundle proving the source binary's provenance.
	// Empty looks for one beside the source, at <source>.sigstore.json, which
	// is where a release download leaves it.
	Bundle string

	// SkipVerify installs a binary whose provenance has not been proven.
	//
	// The escape hatch for an air-gapped site that cannot reach Sigstore, and
	// for a developer installing a locally built binary — which has no
	// signature and cannot have one. It is a separate flag from Force on
	// purpose: Force means "I know this is a downgrade", which is a statement
	// about versions, and conflating it with "I do not know where this binary
	// came from" would let a routine rollback silently drop a security check.
	SkipVerify bool

	// ProvenanceEstablished states that the caller has already proven this
	// binary's provenance against a signed artifact, and that there is
	// therefore no bundle to find beside it (Task 20331).
	//
	// It exists for exactly one caller: a remote agent upgrading itself. The
	// release signs the *archive*, not the executable inside it, so by the time
	// pkg/upgrade has verified the signature and extracted the binary there is
	// no bundle that would match the extracted file — the check has already
	// happened, one layer up, and cannot be repeated here.
	//
	// It is deliberately not spelled as SkipVerify. Reusing that flag would
	// work and would be a lie in two directions: it would print a warning
	// saying provenance was not checked when it was, and it would record
	// ProvenanceVerified=false in the result an operator reads afterwards.
	// Distinguishing "verified elsewhere" from "not verified" is the difference
	// between an audit trail and a plausible one.
	//
	// Like SkipVerify, this is settable only in-process. Nothing an agent
	// receives from the control plane reaches it; see the security argument in
	// pkg/executor/remote/upgradeproto.go.
	ProvenanceEstablished bool

	// PacketFilter grants or withdraws the packet-filter drop-in (Task 20352)
	// as part of the upgrade. The zero value leaves it as the device has it.
	//
	// It is how a device installed before the installer granted CAP_NET_ADMIN
	// gets the grant without the enrollment bundle a full install needs, and it
	// applies even when the binary is already current: the drop-in is written,
	// systemd reloaded, and the agent restarted, with the same rollback as a
	// binary swap if it does not come back.
	PacketFilter PacketFilterChange

	// Channel moves the device to another update channel (Task 20376): edge
	// writes the channel drop-in, stable removes it, empty keeps it. Like the
	// packet filter it applies even when the binary is current, and it is
	// decided here, on the device — the hub has no way to set it.
	Channel provenance.Channel

	// RemoteUpgrade installs or removes the root helper that carries out an
	// upgrade the hub asks for (remoteupgrade.go). The zero value keeps it.
	RemoteUpgrade RemoteUpgradeChange

	// ExpectVersion, when set, is the version the staged binary must report
	// when it is run. An edge build's signed manifest names it (Task 20376):
	// the signature proves edge.yml built *a* commit, the manifest says which,
	// and this is what proves the bytes being installed are that build rather
	// than another genuine one renamed. Unlike a downgrade, a mismatch is not
	// overridable by Force.
	ExpectVersion string

	// ExpectCommit and ExpectSequence are the rest of what the signed manifest
	// says about the build (Task 20380): the full commit it was made from and
	// that commit's place on main. Checked whenever ExpectVersion is set,
	// against what the binary reports when it is run, and not overridable: a
	// validly signed manifest for one commit paired with a binary of another
	// is refused even when the versions happen to agree. ExpectSequence zero
	// means the manifest names none (schema 1), and then the binary must carry
	// none either.
	ExpectCommit   string
	ExpectSequence int

	// SettleTimeout bounds the wait for a restarted service to report itself
	// active before the upgrade concludes the new build is bad and rolls back.
	// Zero uses serviceSettleTimeout.
	//
	// Exposed because the right value is a property of the device, not of
	// cloop. The default is generous for a laptop and can still be short for a
	// heavily loaded single-core gateway paging in a 40 MB executable off slow
	// flash — and there, a timeout that fires early does not merely report a
	// problem, it reverts a good upgrade.
	SettleTimeout time.Duration
}

type UpgradeRequest struct {
	TargetVersion string `json:"target_version"`
	Force         bool   `json:"force,omitempty"`
	SettleSeconds int    `json:"settle_seconds,omitempty"`
	Reason        string `json:"reason,omitempty"`
	RequestedAt   string `json:"requested_at"`
}

type UpgradeResult struct {
	// Spec is the normalised spec the upgrade ran against.
	Spec Spec
	// Output is the supervision system involved.
	Output Output
	// Source is the binary that was installed from.
	Source string
	// AlreadyCurrent reports that the installed binary was byte-identical and
	// nothing was changed.
	AlreadyCurrent bool
	// BinaryCurrent reports that the installed binary was already this build,
	// so none was copied — whether or not something else, the packet-filter
	// drop-in, changed.
	BinaryCurrent bool
	// BinaryReplaced reports that the service binary was rewritten.
	BinaryReplaced bool
	// Restarted reports that the service was asked to restart. False with
	// BinaryReplaced true means the service was not running, so the new binary
	// is in place and will be used whenever it is next started.
	Restarted bool
	// DryRun echoes that nothing was actually changed, so a caller cannot
	// render a result as done when it was only planned.
	DryRun bool
	// StagedBuild is what the new binary said about itself when it was run,
	// and InstalledBuild is what the one being replaced said. A zero
	// StagedBuild means verification was skipped — see Verified.
	StagedBuild, InstalledBuild BinaryIdentity
	// Verified reports that the staged binary was executed and identified
	// itself before anything was replaced. False means the check was skipped
	// because the installer is staged (its target is another machine, whose
	// binary may legitimately not run here), and the result must not be
	// rendered as though the binary had been proven good.
	Verified bool
	// ProvenanceVerified reports that the source binary's signature was
	// checked against cloop's release workflow before anything was executed or
	// written. False means --insecure-skip-verify was passed, and the result
	// must not be rendered as though the binary's origin were known.
	ProvenanceVerified bool
	// BackupPath is where the replaced binary was kept, so an operator can
	// roll back by hand. Empty when nothing was replaced.
	BackupPath string
	// RolledBack reports that the service did not come back on the new binary
	// and the previous one was restored. It travels with a non-nil error:
	// the upgrade failed, and this says the device was left working.
	RolledBack bool

	// PacketFilterChanged reports that the upgrade wrote or removed the
	// packet-filter drop-in, and PacketFilterChange says how, for the log.
	PacketFilterChanged bool
	PacketFilterChange  string
	// PacketFilterGranted reports whether the device's unit grants the agent
	// what installing a sandbox firewall takes, once the upgrade is done. Only
	// meaningful for OutputSystemd.
	PacketFilterGranted bool

	// ChannelChanged reports that the upgrade moved the device to another
	// update channel, and Channel is the channel it follows afterwards.
	ChannelChanged bool
	Channel        provenance.Channel
	// RemoteUpgradeChanged reports that the upgrade installed or removed the
	// remote-upgrade helper, and RemoteUpgradeInstalled whether the device has
	// it afterwards.
	RemoteUpgradeChanged   bool
	RemoteUpgradeInstalled bool
	// UnitChanges says, one line each, what the upgrade changed beside the
	// binary — or, for a dry run, would change.
	UnitChanges []string

	// PreviousChecksum and NewChecksum are SHA-256 sums of the old and new
	// binaries, for an operator correlating a rollout across a fleet.
	//
	// "Checksum" rather than "digest" deliberately. These are content sums of a
	// public binary used to answer "are these the same bytes", not credential
	// material, so comparing them with == is correct — and the security suite's
	// constant-time scanner reads any identifier containing "digest" as a
	// secret. Naming them for what they are keeps that check meaningful instead
	// of adding an exception to it.
	PreviousChecksum string
	NewChecksum      string
}