felhom-agent/internal/reconcile/classify.go

package reconcile

// The benign/destructive classifier (doc 03 §4). The gate decides whether an intended
// action needs an operator signature by **provenance + data-bearing-ness, NOT by
// verb**. The op CLASS encodes the semantic intent (a "detach storage" is its own
// destructive class, not just another PUT) so classification never turns on the HTTP
// method.

// OpClass is the semantic class of an intended action. This vocabulary is the
// agent-side contract: the signed-op `op` field (doc 04 §2.1) and slice-10's hub /
// operator CLI match these exact strings. The committed slice-2 fixture
// (op="guest_destroy") seeds it.
type OpClass string

const (
	// Benign-on-existing-guest set — wired to live execution this slice.
	ClassStart     OpClass = "start"
	ClassStop      OpClass = "stop"
	ClassSetConfig OpClass = "set_config" // benign sizing/description changes only
	ClassResize    OpClass = "resize"     // GROW-only rootfs/volume resize (slice 5 Phase B)

	// Benign storage attach — re-mount-by-UUID of a known target whose device returned
	// (slice 5 Phase B). Additive (no data loss), so benign by construction.
	ClassStorageMount OpClass = "storage_mount"

	// Benign by construction — classified now, executors land in later slices.
	ClassCreate  OpClass = "create"  // provision a NEW guest (restore-to-new, slice 7)
	ClassRestart OpClass = "restart" // heal a crashed controller in-place (§4)

	// Destructive set — destroying/overwriting the only/primary copy of customer
	// data. Classified and gated now; NOT wired to live execution this slice (nothing
	// serves destructive deltas until slice 10).
	ClassGuestDestroy     OpClass = "guest_destroy"
	ClassStorageWipe      OpClass = "storage_wipe"      // storage detach/wipe
	ClassRestoreOverwrite OpClass = "restore_overwrite" // restore OVER an existing guest
	ClassDecommission     OpClass = "decommission"

	// Key-rotation re-pin (doc 04 §4) — destructive-class, role-scoped: the cold
	// recovery key authorizes ONLY this; the operational key authorizes this + ordinary
	// destructive ops.
	ClassKeyRotation OpClass = "key_rotation"

	// Agent self-update (TASK D1) — replacing the root-adjacent host binary. Destructive-class by
	// definition (the operator signs the exact version + sha256; the pinned sha is the ONLY
	// integrity root — neither hub nor Gitea can substitute a binary). Operational-key only, like
	// every ordinary destructive op. Note the classifier's default case already fails safe to
	// Destructive for unknown classes — this named constant documents the class and keeps the
	// signed-op vocabulary explicit, it does not (and must not) loosen anything.
	ClassAgentUpdate OpClass = "agent_update"
)

// Disposition is the classifier verdict.
type Disposition string

const (
	// Benign — the reconciler/executor MAY act without an operator signature.
	Benign Disposition = "benign"
	// Destructive — an operator signature bound to the action is REQUIRED.
	Destructive Disposition = "destructive"
	// CustomerConfirmable — a USER-DATA storage wipe: authorized by the customer's informed-
	// confirmation bound to the device's durable id, NOT an operator signature. This tier is
	// reachable ONLY for ClassStorageWipe on an agent-classified user-data device (see
	// Gate.AuthorizeStorageWipe). A user-data drive is already within the in-guest controller's
	// blast radius (it bind-mounts /mnt), so customer-confirmation adds no new reach — the data was
	// already destroyable. Every OTHER destructive class keeps the operator signature.
	CustomerConfirmable Disposition = "customer_confirmable"
)

// Storage ROLE values — the protection tier the AGENT assigns a device by its own inspection
// (mirrors storage.DeviceRole). Kept as plain strings here to avoid a storage→reconcile import edge:
// the localapi adapter passes the agent's classification through verbatim. The gate NEVER derives the
// role from a caller's claim — it only consumes the agent's verdict.
const (
	StorageRoleSystem   = "system"
	StorageRoleBackup   = "backup"
	StorageRoleUserData = "user-data"
)

// Provenance is AGENT-INTERNAL evidence that an otherwise-destructive action is
// actually safe (doc 03 §4). It is recorded in the operation journal by the agent's
// own bookkeeping and is **NEVER populated from the hub or any external input** — else
// a compromised hub could relabel a data-bearing guest as scratch to walk the gate.
// The zero value (no internal evidence) is the only value an externally-sourced intent
// may carry.
type Provenance struct {
	// SameTxnCreated: the agent created this resource earlier in the SAME journaled
	// transaction, so destroying it is a compensating rollback (§10), not data loss.
	SameTxnCreated bool
	// AgentTaggedScratch: the agent tagged this resource ephemeral/scratch (e.g. a
	// restore-test scratch guest, §8). Journal-recorded provenance only.
	AgentTaggedScratch bool
}

// internalEvidence reports whether agent-internal provenance makes a destroy benign.
func (p Provenance) internalEvidence() bool {
	return p.SameTxnCreated || p.AgentTaggedScratch
}

// Classify returns the disposition for an op class given agent-internal provenance.
//
// Rules (doc 03 §4):
//   - create/start/stop/restart/benign-set_config → always Benign.
//   - destroy/overwrite of a data-bearing resource → Destructive, UNLESS agent-internal
//     provenance (same-transaction create, or agent-tagged scratch) makes it benign.
//   - key-rotation → always Destructive (signed); role-scoping picks the allowed key.
//   - an UNKNOWN class fails safe → Destructive (require a signature).
func Classify(class OpClass, prov Provenance) Disposition {
	switch class {
	case ClassStart, ClassStop, ClassSetConfig, ClassResize, ClassStorageMount, ClassCreate, ClassRestart:
		return Benign
	case ClassGuestDestroy, ClassStorageWipe, ClassRestoreOverwrite, ClassDecommission:
		if prov.internalEvidence() {
			return Benign // compensating rollback / scratch teardown
		}
		return Destructive
	case ClassKeyRotation:
		return Destructive
	case ClassAgentUpdate:
		// Never benign — no agent-internal provenance can make replacing the agent binary
		// unsigned-safe (a compromised process must not be able to self-bless an update).
		return Destructive
	default:
		return Destructive // fail safe: an unrecognized op is treated as destructive
	}
}

// classOfAction maps a benign reconcile ActionKind to its OpClass, so every reconcile
// mutation is classified and passed through the gate like any other intent.
func classOfAction(k ActionKind) OpClass {
	switch k {
	case ActionStart:
		return ClassStart
	case ActionStop:
		return ClassStop
	case ActionSetConfig:
		return ClassSetConfig
	case ActionResize:
		return ClassResize
	case ActionDecommission:
		return ClassDecommission
	default:
		return OpClass(k)
	}
}