firewall

type AddOptions struct {
	// Elevated, when true, asks the backend to perform the rule
	// install with administrative privileges (Windows: UAC prompt
	// via Start-Process -Verb RunAs; Linux: sudo). When false,
	// the backend may still elevate if the platform requires it
	// — the flag is a hint, not a guarantee.
	Elevated bool
}

type AddResult struct {
	// AddedRules lists the Rule.Name values that were freshly
	// created. Already-present rules are skipped (idempotent
	// install) and do NOT appear here.
	AddedRules []string

	// SkippedRules lists rules that were already present at the
	// requested name. Reported separately so the CLI can show a
	// neutral "already configured" message instead of a misleading
	// "added" success.
	SkippedRules []string
}

type Backend interface {
	// Detect probes the host firewall and reports whether
	// clawtool needs to install rules.
	Detect() (BackendState, error)

	// HasRule returns true when a rule with the given name is
	// currently installed on the host firewall.
	HasRule(name string) (bool, error)

	// AddRules installs every rule in `rules` that isn't already
	// present. Idempotent: already-present rules are reported in
	// SkippedRules, not re-added. Returns ErrElevationDeclined
	// when the platform required elevation and the user declined
	// (e.g. UAC "No" on Windows).
	AddRules(rules []Rule, opts AddOptions) (AddResult, error)

	// RemoveRules deletes the named rules. Missing rules are
	// silently skipped — RemoveRules is best-effort cleanup.
	RemoveRules(names []string) error

	// List returns every clawtool-* rule currently installed.
	// Used by `clawtool firewall status`. Returns an empty slice
	// (not nil) when no rules are present.
	List() ([]Rule, error)
}

type BackendState struct {
	// Active is true when the platform's firewall is enabled
	// and would block unknown inbound traffic. False on macOS
	// (default-allow pf) and on Linux when ufw is inactive.
	Active bool

	// NeedsRules is true when Active is true AND at least one of
	// the expected clawtool rules is missing. The serve auto-hook
	// keys off this — false skips the UAC prompt entirely.
	NeedsRules bool

	// Reason is a short human-readable explanation of the state,
	// surfaced by `clawtool firewall status`.
	Reason string
}

type Rule struct {
	// Name is the canonical clawtool-* identifier the backend
	// uses to look the rule up later. Must be unique across
	// clawtool rules; the `clawtool firewall remove` path treats
	// every rule with the `clawtool-` prefix as in scope.
	Name string

	// Description is a human-readable string shown in the
	// platform's firewall UI. Optional.
	Description string

	// Protocol is "TCP" or "UDP". Other values are rejected at
	// AddRules time.
	Protocol string

	// LocalPort is the inbound port the rule allows. Always
	// >0; zero means "rule is malformed".
	LocalPort int

	// RemoteCIDR is the source CIDR allowed to reach LocalPort.
	// Empty string means "any source" (UDP 5353 mDNS). For the
	// daemon TCP rule the backend fills in the detected LAN
	// range (e.g. 192.168.1.0/24) so the listener isn't reachable
	// from arbitrary internet sources.
	RemoteCIDR string

	// Profile is the Windows firewall profile selector
	// ("Private", "Domain", or "Private,Domain"). Ignored on
	// non-Windows backends. Public is intentionally excluded by
	// default — clawtool's LAN surface shouldn't fire on a
	// coffee-shop Wi-Fi the operator marked Public.
	Profile string
}