v0.23.0: device-ROLE classification + tiered storage-wipe gate (user-data customer-confirmable; system/backup operator-only)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-11 21:29:18 +02:00
parent 9e3513557f
commit 15f7529a1c
10 changed files with 759 additions and 106 deletions
@@ -27,10 +27,31 @@ type DiskOps interface {
 }

 // StorageGate authorizes a DESTRUCTIVE storage op (a data-bearing wipe/format) through the
-// slice-4 reversibility gate. Satisfied by an adapter over reconcile.Gate in main.go. In 8C an
-// unsigned destructive op returns (false, "pending_signature"); the signed path is slice 10.
+// reversibility gate, TIERED by the agent's authoritative device-role verdict. Satisfied by an
+// adapter over reconcile.Gate in main.go.
+//   - user-data  → customer-confirmable: allowed iff the request carries the customer's confirmation
+//     bound to the device's durable id (no operator signature).
+//   - system/backup → operator-signature only (unsigned → pending_signature; Confirmed is ignored).
 type StorageGate interface {
-	AuthorizeWipe(device string) (allowed bool, reason string)
+	AuthorizeWipe(req WipeRequest) WipeDecision
+}
+
+// WipeRequest is the inspection-derived input to the wipe gate. Role + DeviceDurableID are
+// AGENT-INTERNAL (the agent classified the role and re-resolved the durable id); Confirmed +
+// ConfirmDurableID are the caller's claim, honored ONLY for user-data and ONLY on a durable-id match.
+type WipeRequest struct {
+	Role             string // "system" | "backup" | "user-data" (agent-classified)
+	DeviceDurableID  string // agent-re-resolved durable id of the device ("" if unresolvable)
+	Confirmed        bool
+	ConfirmDurableID string
+}
+
+// WipeDecision is the gate's verdict.
+type WipeDecision struct {
+	Allowed           bool
+	Tier              string // "customer_confirmable" | "destructive"
+	Reason            string // machine reason (audit/UI)
+	NeedsConfirmation bool   // user-data, not-yet-confirmed → ask the customer (NOT a signature)
 }

 // GuestLister lists the host's guests (to map a mount to the guests that depend on it for the
@@ -49,6 +70,11 @@ type DiskInfo struct {
 	BackingDevice string `json:"backing_device"` // /dev/sdb1, … ("" for network/lvm)
 	MountPath     string `json:"mount_path"`
 	Class         string `json:"class"`        // fast | slow | ""
+	// Role is the agent's AUTHORITATIVE protection tier (system | backup | user-data), derived from
+	// the agent's own storage view + host topology — never from the controller. The controller drives
+	// the UI from it: system/backup get a lock badge and NO destructive controls; user-data is
+	// customer-manageable. Defense in depth — the agent re-enforces role at wipe time regardless.
+	Role          string `json:"role"`
 	DataBearing   bool   `json:"data_bearing"` // agent device-inspection verdict (UI hint)
 	DataReason    string `json:"data_reason,omitempty"`
 	// DurableID is the target's stable identity (e.g. "uuid:<fs-uuid>" for usb/local-dir). The
@@ -68,12 +94,16 @@ func (s *Server) handleDisks(w http.ResponseWriter, r *http.Request, vmid int) {
 		writeErr(w, http.StatusBadGateway, "could not read storage view")
 		return
 	}
+	// Resolve the OS/system disks ONCE for this request — role classification is agent-authoritative
+	// (the agent's own mount/topology read, never the caller's claim).
+	sysDisks, sysKnown := storage.SystemDisks(storage.NewProcHostReader())
 	out := make([]DiskInfo, 0, len(targets))
 	for _, t := range targets {
 		di := DiskInfo{
 			Name: t.Name, Type: t.Type, State: t.State,
 			BackingDevice: t.BackingDevice, MountPath: t.MountPath, Class: t.ClassHint,
 			DurableID: t.DurableID,
+			Role:      string(storage.RoleForStorage(t.Type, t.BackingDevice, sysDisks, sysKnown)),
 		}
 		// Inspect the backing device for the UI's data-bearing hint (the authoritative check
 		// is re-run at format time on the actual device).
@@ -159,7 +189,14 @@ type formatRequest struct {
 	VMID   int    `json:"vmid"`
 	Device string `json:"device"`
 	FSType string `json:"fstype"`
-	// NOTE: any caller-supplied "blank"/"force" claim is deliberately IGNORED — the agent
+	// Confirmed + DurableID authorize a USER-DATA data-bearing wipe by the customer's informed-
+	// confirmation bound to the device's durable id. The agent RE-RESOLVES the device's durable id
+	// and matches it against DurableID — a confirmation for one disk can't wipe another. Both are
+	// INERT for system/backup devices (those stay operator-signature only — the role is the agent's,
+	// never the caller's, so confirmed:true on a system device is refused).
+	Confirmed bool   `json:"confirmed"`
+	DurableID string `json:"durable_id"`
+	// NOTE: any caller-supplied "blank"/"force" claim is still deliberately IGNORED — the agent
 	// inspects the device itself (8C invariant).
 }

@@ -174,7 +211,14 @@ type FormatResponse struct {
 	Formatted   bool   `json:"formatted"`
 	DataBearing bool   `json:"data_bearing"`
 	Reason      string `json:"reason"`
-	// PendingOp is set on a data-bearing refusal — the exact op to sign (slice 10B).
+	// Role is the agent's authoritative tier for the device (system | backup | user-data).
+	Role string `json:"role,omitempty"`
+	// NeedsConfirmation is set on a USER-DATA data-bearing refusal: the customer must re-submit with
+	// confirmed:true + DurableID (below) after the controller's type-to-confirm UI. NOT an operator
+	// signature — the customer authorizes the wipe of their own data drive.
+	NeedsConfirmation bool   `json:"needs_confirmation,omitempty"`
+	DurableID         string `json:"durable_id,omitempty"` // the durable id to confirm against (user-data)
+	// PendingOp is set on a SYSTEM/BACKUP data-bearing refusal — the exact op the operator must sign.
 	PendingOp *PendingOp `json:"pending_op,omitempty"`
 }

@@ -217,44 +261,89 @@ func (s *Server) handleDiskFormat(w http.ResponseWriter, r *http.Request, vmid i
 		s.logger.Error("local-api: format device inspect", "device", req.Device, "err", err)
 		// inspect error → fail-safe data-bearing (probe.DataBearing() is true on !Probed)
 	}
-	if probe.DataBearing() {
-		// Destructive: route through the gate. With no operator signature → pending_signature.
-		allowed, reason := s.diskGate.AuthorizeWipe(req.Device)
-		if !allowed {
-			// Surface the bound op the operator must sign (slice 10B): derive the DURABLE device id
-			// so the signed wipe binds to this exact physical disk (not the mutable path), and the
-			// runner can re-resolve it at execution. A durable-id derivation failure is non-fatal —
-			// the refusal still stands; we just can't pre-fill the durable id.
-			var pending *PendingOp
-			if durableID, derr := storage.DeviceDurableID(req.Device); derr == nil {
-				pending = &PendingOp{Op: "storage_wipe", HostScope: s.hostID, DurableID: durableID, FSType: req.FSType}
-				s.logger.Warn("local-api: data-bearing format refused — PENDING OPERATOR SIGNATURE",
-					"vmid", vmid, "device", req.Device, "durable_id", durableID, "fstype", req.FSType,
-					"why", probe.Reason(), "to_authorize", "felhom-opsign -op storage_wipe -host "+s.hostID+" -durable-id "+durableID)
-			} else {
-				s.logger.Warn("local-api: data-bearing format refused (no durable id)",
-					"vmid", vmid, "device", req.Device, "why", probe.Reason(), "derive_err", derr)
-			}
-			writeStatus(w, http.StatusForbidden, false,
-				FormatResponse{VMID: vmid, Device: req.Device, Formatted: false, DataBearing: true, Reason: probe.Reason(), PendingOp: pending},
-				"device is data-bearing — format requires an operator signature ("+reason+")")
+	if !probe.DataBearing() {
+		// Blank device → benign → mkfs (role is irrelevant; there is nothing to destroy).
+		if err := s.disks.Format(r.Context(), req.Device, req.FSType); err != nil {
+			s.logger.Error("local-api: format", "vmid", vmid, "device", req.Device, "err", err)
+			writeErr(w, http.StatusBadGateway, "format failed: "+err.Error())
 			return
 		}
-		// A signed wipe is executed by the signed-jobs runner (queue → verify gate → durable
-		// re-resolve + re-inspect → mkfs), NOT this synchronous path. This branch (gate ALLOWED a
-		// data-bearing format inline) is unreachable: the inline path passes signed=nil → always
-		// pending. Fail safe.
-		writeErr(w, http.StatusForbidden, "data-bearing format must be completed via a signed job (felhom-opsign → hub queue)")
+		writeOK(w, FormatResponse{VMID: vmid, Device: req.Device, Formatted: true, DataBearing: false, Reason: "blank device formatted " + req.FSType})
 		return
 	}

-	// Blank device → benign → mkfs.
-	if err := s.disks.Format(r.Context(), req.Device, req.FSType); err != nil {
-		s.logger.Error("local-api: format", "vmid", vmid, "device", req.Device, "err", err)
-		writeErr(w, http.StatusBadGateway, "format failed: "+err.Error())
+	// Data-bearing → TIER by the agent's authoritative role classification (its own inspection,
+	// never the caller's claim). The agent also re-resolves the device's durable id; the customer's
+	// confirmation must bind to it.
+	role := s.deviceRole(r.Context(), req.Device)
+	deviceDurable, derr := storage.DeviceDurableID(req.Device)
+	if derr != nil {
+		deviceDurable = "" // refusal still stands; binding/pending-op just lack the id
+	}
+	dec := s.diskGate.AuthorizeWipe(WipeRequest{
+		Role: string(role), DeviceDurableID: deviceDurable,
+		Confirmed: req.Confirmed, ConfirmDurableID: req.DurableID,
+	})
+
+	if dec.Allowed {
+		// USER-DATA, customer-confirmed (durable-id-bound). The gate already AUDITED it. Wipe.
+		if err := s.disks.Format(r.Context(), req.Device, req.FSType); err != nil {
+			s.logger.Error("local-api: customer-confirmed format", "vmid", vmid, "device", req.Device, "err", err)
+			writeErr(w, http.StatusBadGateway, "format failed: "+err.Error())
+			return
+		}
+		s.logger.Warn("local-api: USER-DATA data-bearing format — CUSTOMER CONFIRMED (no operator signature)",
+			"vmid", vmid, "device", req.Device, "durable_id", deviceDurable, "fstype", req.FSType, "why", probe.Reason())
+		writeOK(w, FormatResponse{VMID: vmid, Device: req.Device, Formatted: true, DataBearing: true,
+			Role: string(role), DurableID: deviceDurable, Reason: "customer-confirmed wipe (" + probe.Reason() + ")"})
 		return
 	}
-	writeOK(w, FormatResponse{VMID: vmid, Device: req.Device, Formatted: true, DataBearing: false, Reason: "blank device formatted " + req.FSType})
+
+	if dec.Tier == "customer_confirmable" {
+		// USER-DATA refusal: either awaiting the customer's confirmation, or the confirmation didn't
+		// bind to THIS device. Surface the durable id to confirm against — NOT an operator signature.
+		msg := "device is data-bearing — customer confirmation required"
+		if !dec.NeedsConfirmation {
+			msg = "confirmation does not match this device — refused (" + dec.Reason + ")"
+		}
+		s.logger.Warn("local-api: user-data data-bearing format refused",
+			"vmid", vmid, "device", req.Device, "durable_id", deviceDurable, "reason", dec.Reason, "why", probe.Reason())
+		writeStatus(w, http.StatusForbidden, false,
+			FormatResponse{VMID: vmid, Device: req.Device, Formatted: false, DataBearing: true, Role: string(role),
+				NeedsConfirmation: dec.NeedsConfirmation, DurableID: deviceDurable, Reason: probe.Reason()}, msg)
+		return
+	}
+
+	// SYSTEM / BACKUP refusal: operator signature required. Surface the bound op to sign (the durable
+	// id binds the signed wipe to THIS exact physical disk). confirmed:true was ignored — by role.
+	var pending *PendingOp
+	if deviceDurable != "" {
+		pending = &PendingOp{Op: "storage_wipe", HostScope: s.hostID, DurableID: deviceDurable, FSType: req.FSType}
+		s.logger.Warn("local-api: protected (system/backup) data-bearing format refused — PENDING OPERATOR SIGNATURE",
+			"vmid", vmid, "device", req.Device, "role", role, "durable_id", deviceDurable, "fstype", req.FSType,
+			"why", probe.Reason(), "to_authorize", "felhom-opsign -op storage_wipe -host "+s.hostID+" -durable-id "+deviceDurable)
+	} else {
+		s.logger.Warn("local-api: protected data-bearing format refused (no durable id)",
+			"vmid", vmid, "device", req.Device, "role", role, "why", probe.Reason())
+	}
+	writeStatus(w, http.StatusForbidden, false,
+		FormatResponse{VMID: vmid, Device: req.Device, Formatted: false, DataBearing: true, Role: string(role), PendingOp: pending, Reason: probe.Reason()},
+		"device is system/backup-protected — format requires an operator signature ("+dec.Reason+")")
+}
+
+// deviceRole resolves a device's AUTHORITATIVE protection tier. It prefers a known storage target's
+// role (so a PBS-backed device is recognized as backup), falling back to a raw-device classification
+// (for a fresh disk not yet a PVE storage — the init flow). Defaults to system on ambiguity.
+func (s *Server) deviceRole(ctx context.Context, device string) storage.DeviceRole {
+	sysDisks, sysKnown := storage.SystemDisks(storage.NewProcHostReader())
+	if targets, err := s.storage.Observe(ctx); err == nil {
+		for _, t := range targets {
+			if t.BackingDevice != "" && t.BackingDevice == device {
+				return storage.RoleForStorage(t.Type, t.BackingDevice, sysDisks, sysKnown)
+			}
+		}
+	}
+	return storage.RoleForRawDevice(device, sysDisks, sysKnown)
 }

 // dependentGuests returns the VMIDs whose config has a mount whose storage backs the ejected