agent

type AddOptions struct {
	EditOptions
	Spec       DeploymentSpec
	CreateDirs bool
}

type Agent struct {

	// Random returns a value in [0,1); tests inject stable independent streams.
	Random func() float64

	// Version, OS, Arch and PackageFormat are reported to the server.
	Version, OS, Arch string
	PackageFormat     string
	// StandaloneAddr is where challenge: standalone listens (":80").
	StandaloneAddr string
	// Now and Sleep: the clock and the wait; tests replace them.
	Now   func() time.Time
	Sleep func(ctx context.Context, d time.Duration) error
	// contains filtered or unexported fields
}

type Config struct {
	// Server is agent.base_url of the server, e.g. https://pki.homelab.lan:8444.
	Server string `yaml:"server"`
	// CABundle is the trust anchor (PEM) for the agent listener and ACME.
	CABundle string `yaml:"ca_bundle"`
	// Hostname is the FQDN the agent proves at enrollment; "" = the host's name.
	Hostname string `yaml:"hostname"`
	// ACMEDirectory is the directory URL of any ACME CA.
	ACMEDirectory string `yaml:"acme_directory"`
	// Proxy is an http(s) proxy for both connections; environment variables
	// (HTTPS_PROXY, HTTP_PROXY, NO_PROXY) are never used (owner 2026-10-24).
	Proxy string `yaml:"proxy"`
	// StateDir holds the agent's key, certificate and enrollment.
	StateDir string `yaml:"state_dir"`
	// LogLevel: debug, info, warn, error.
	LogLevel string `yaml:"log_level"`

	Enrollment Enrollment `yaml:"enrollment"`
	// DNSProviders are the dns-01 settings a deployment refers to by name
	// (docs/PHASE3.md §13.2). They never hold a secret, only the path of the
	// credentials file.
	DNSProviders map[string]DNSProvider `yaml:"dns_providers"`
	Hooks        map[string][]string    `yaml:"hooks"`
	Paths        []string               `yaml:"paths"`
	Sandbox      Sandbox                `yaml:"sandbox"`
	// SystemTrust asks for the root in the system trust store of the host
	// (docs/PHASE3.md §15). nil is off, and off is the default. The service never
	// acts on it: "trust install" and "trust remove" do, run by root.
	SystemTrust *SystemTrust `yaml:"system_trust"`
	Deployments []Deployment `yaml:"deployments"`
}

type DNSProvider struct {
	// Type is rfc2136 or cloudflare.
	Type string `yaml:"type"`
	// CredentialsFile is an absolute path, read at the start of every issuance.
	CredentialsFile string `yaml:"credentials_file"`
	// Nameserver is host or host:port (default port 53); rfc2136 only.
	Nameserver string `yaml:"nameserver"`
	// Zone is the zone to update; rfc2136 only, "" = found by an SOA lookup.
	Zone string `yaml:"zone"`
	// TTL of the TXT record in seconds (default 120).
	TTL int `yaml:"ttl"`
	// Resolver is IP or IP:port used for SOA, CNAME and propagation queries.
	Resolver string `yaml:"resolver"`
	// Propagation is authoritative (default), resolver or wait.
	Propagation string `yaml:"propagation"`
	// PropagationWait is a pause in seconds before the first check (default 0).
	PropagationWait int `yaml:"propagation_wait"`
	// PropagationTimeout is how long the agent polls, in seconds (default 120).
	PropagationTimeout int `yaml:"propagation_timeout"`
}

type DNSProviderStatus struct {
	Name   string
	Type   string
	Path   string
	State  string   // ok, missing, wrong mode, ...
	Detail string   // what to change; never a value
	Users  []string // deployments that use the provider
}

type DNSTest struct {
	// CloudflareURL is the API base of the stub, "" for the real API.
	CloudflareURL string
	// CloudflareRoots trusts the stub's certificate.
	CloudflareRoots *x509.CertPool
	// Poll replaces the 2 s interval of the propagation check (0 = unchanged).
	Poll time.Duration
}

type Deployment struct {
	Name      string   `yaml:"name"`
	Profile   string   `yaml:"profile"`
	Names     []string `yaml:"names"`
	Challenge string   `yaml:"challenge"`
	Webroot   string   `yaml:"webroot"`
	// DNSProvider names an entry of dns_providers; required for dns-01.
	DNSProvider string `yaml:"dns_provider"`
	Dir         string `yaml:"dir"`
	Files       Files  `yaml:"files"`
	Owner       string `yaml:"owner"`
	Group       string `yaml:"group"`
	KeyMode     string `yaml:"key_mode"`
	TestHook    string `yaml:"test_hook"`
	ReloadHook  string `yaml:"reload_hook"`
	Check       string `yaml:"check"`
	// CheckName is the TLS server name (SNI) of the local check; "" = the
	// first name without "*". A wildcard is not a host name, so a deployment
	// of wildcard names only needs it when it has a check.
	CheckName string `yaml:"check_name"`
}

type DeploymentAddCommand struct {
	ConfigPath string
	DryRun     bool
	Restart    bool
	CreateDirs bool
	Spec       DeploymentSpec
}

type DeploymentResult struct {
	Name                  string    `json:"name"`
	State                 string    `json:"state"`
	Serial                string    `json:"serial,omitempty"`
	NotAfter              time.Time `json:"not_after,omitempty"`
	Fingerprint           string    `json:"fingerprint,omitempty"`
	WrittenFingerprint    string    `json:"written_fingerprint,omitempty"`
	CheckConfigured       bool      `json:"check_configured"`
	DeployedAt            time.Time `json:"deployed_at,omitempty"`
	LastError             string    `json:"last_error,omitempty"`
	AttemptedAt           time.Time `json:"attempted_at,omitempty"`
	Failures              int       `json:"failures,omitempty"`
	NextAttempt           time.Time `json:"next_attempt,omitempty"`
	HandledRenewalVersion int64     `json:"handled_renewal_version,omitempty"`
}

type DeploymentSpec struct {
	Name          string
	Profile       string
	Names         []string
	Challenge     string
	Webroot       string
	Dir           string
	Files         Files
	Owner         string
	Group         string
	KeyMode       string
	Hooks         []HookSpec
	TestHook      string
	ReloadHook    string
	Check         string
	SandboxWrite  []string
	LowPorts      bool
	ACMEDirectory string

	// CheckName is the TLS server name of Check (check_name).
	CheckName string
	// DNSProvider names the dns_providers entry of a dns-01 deployment. The
	// DNS fields below define that entry when it is new: they are written
	// only for a name that agent.yaml does not have yet, and they must match
	// the definition of one that it has (docs/PHASE3.md §13.1, step 42).
	DNSProvider    string
	DNSType        string
	DNSCredentials string
	DNSNameserver  string
	DNSZone        string
	DNSResolver    string

	// Recipe names the recipe the spec was filled from ("" = none); it only
	// changes what is printed.
	Recipe string
	// contains filtered or unexported fields
}

type DropinOptions struct {
	// LowPorts wants 20-low-ports.conf although the configuration does not
	// imply it (setup --low-ports, deployment add --low-ports).
	LowPorts bool
	// Prune drops entries of 10-paths.conf that agent.yaml does not explain.
	Prune bool
	// Drop names entries to drop although Prune is off: paths this very
	// operation took out of agent.yaml. Entries that are still derived stay.
	Drop []string
}

type DropinPlan struct {
	// Paths is the content of 10-paths.conf; it equals the file as found
	// when PathsChanged is false.
	Paths        []byte
	PathsChanged bool
	// Added and Removed are the entries this plan puts into or takes out of
	// the file; Kept are the entries found that agent.yaml does not explain.
	Added, Removed, Kept []string

	LowPorts     LowPortsAction
	LowPortsData []byte
	// Notes are one-line remarks for the operator.
	Notes []string
}

type DropinState struct {
	Paths        []byte
	HavePaths    bool
	LowPorts     []byte
	HaveLowPorts bool
}

type DryRunHost struct {
	// Root is a directory that stands for "/": every absolute path of the
	// command (directories, files, hook commands) is looked for below it.
	Root string
	// ConfigPath and UnitPath are the real files of the host, already below
	// Root (agent.yaml and the unit; the drop-ins are the unit's .d directory).
	ConfigPath string
	UnitPath   string
	// Stderr receives warnings and hints; nil discards them.
	Stderr io.Writer
}

type EditOptions struct {
	ConfigPath string
	UnitPath   string
	DropinDir  string
	ExampleDir string
	DryRun     bool
	Restart    bool
	Stdout     io.Writer
	Stderr     io.Writer
	// contains filtered or unexported fields
}

type Enrollment struct {
	Challenge string `yaml:"challenge"`
	Webroot   string `yaml:"webroot"`
}

type Files struct {
	Certificate string `yaml:"certificate"`
	Chain       string `yaml:"chain"`
	Fullchain   string `yaml:"fullchain"`
	Key         string `yaml:"key"`
}

type HookSpec struct {
	Name    string
	Command []string
}

type LowPortsAction int

type Material struct {
	Certificate []byte            `json:"-"`
	Chain       []byte            `json:"-"`
	Fullchain   []byte            `json:"-"`
	Key         []byte            `json:"-"`
	Leaf        *x509.Certificate `json:"-"`
	// Notice is a problem that does not make the issuance fail, for the
	// deployment's status (a dns-01 record that could not be removed). It is
	// free of secrets and of provider text.
	Notice string `json:"-"`
}

type RemoveOptions struct {
	EditOptions
	Name       string
	PrunePaths bool
}

type Result struct {
	State   agentv1.EnrollState
	Message string
	AgentID string
}

type Sandbox struct {
	// Write lists directories that hooks (not the agent) write, for example
	// /var/log/nginx for "nginx -t". Only ReadWritePaths gets them.
	Write []string `yaml:"write"`
	// LowPorts is the 20-low-ports.conf drop-in (CAP_NET_BIND_SERVICE).
	// Unset: written when any challenge is standalone, otherwise left as
	// found. false removes it; true writes it.
	LowPorts *bool `yaml:"low_ports"`
}

type SetupOptions struct {
	Server        string
	CABundle      string
	RootSHA256    string
	TokenFile     string
	Webroot       string
	LowPorts      bool
	Hostname      string
	ConfigPath    string
	StateDir      string
	UnitPath      string
	DropinDir     string
	ExampleDir    string
	Version       string
	PackageFormat string
	ACMEDirectory string // https URL of the ACME directory, written into a new agent.yaml
	// SystemTrust installs the root into the system trust store after enrollment
	// and records system_trust in agent.yaml (docs/PHASE3.md §15).
	SystemTrust bool
	Stdout      io.Writer
	Stderr      io.Writer
}

type Status struct {
	Hostname    string
	AgentID     string
	Enrolled    bool
	NotAfter    time.Time
	Serial      string
	Enrollment  string // the open enrollment's last message
	Deployments []DeploymentResult
}

type SyncOptions struct {
	EditOptions
	Adopt bool
	Prune bool
}

type SystemTrust struct {
	// RootSHA256 is the SHA-256 of the DER of the root, 64 hexadecimal digits.
	RootSHA256 string `yaml:"root_sha256"`
}

type TrustOptions struct {
	ConfigPath string
	// RootSHA256 is the pin given on the command line: required for install,
	// optional for remove and status (agent.yaml has the pin of an installed host).
	RootSHA256 string
	// NoRecord (install): do not write system_trust into agent.yaml, for a file
	// that another tool owns and renders (the Salt formula with config_source).
	NoRecord bool
	// Quiet (status): print nothing, the exit code answers.
	Quiet  bool
	Stdout io.Writer
	Stderr io.Writer
}

type UsageError struct{ Message string }