htlcswitch: add read-only reputation hooks and panic guard

Add three nil-guarded hooks at the switch's circuit-matching layer
(handlePacketAdd/handlePacketSettle/handlePacketFail) that feed forwarded
HTLC add/settle/fail events to an optional ReputationManager. The switch
defines the interface; it never imports the reputation package, keeping the
dependency a black box that can only call observation methods.

The hooks pass copies of scalar values (circuit keys, amounts, cltv, the
accountable bit) — no pointers into switch state — so they cannot mutate
forwarding. A guardedReputationManager wraps the manager in a recover()
boundary: because the hooks run on the forwarding goroutine, a panic in the
(log-only) subsystem must never take down HTLC forwarding, so on a panic the
guard logs, disables the subsystem, and forwarding continues unaffected.

Author: GeorgeTsagk

htlcswitch/interfaces.go

@@ -489,6 +489,25 @@ type htlcNotifier interface {
 		info channeldb.FinalHtlcInfo)
 }
 
+// ReputationManager is the read-only seam through which the switch feeds HTLC
+// forwarding lifecycle events to the (optional) local reputation subsystem.
+// It is a black box that only observes events to update internal reputation
+// state; it never affects forwarding decisions or the wire (log-only). When no
+// reputation manager is configured this is nil and the hooks are skipped.
+type ReputationManager interface {
+	// OnForward observes a forwarded HTLC at the point the switch
+	// commits to forwarding it to the outgoing channel.
+	OnForward(incoming, outgoing CircuitKey, incomingAmt,
+		outgoingAmt lnwire.MilliSatoshi, incomingCltv uint32,
+		accountable bool)
+
+	// OnSettle observes the successful resolution of a forwarded HTLC.
+	OnSettle(incoming, outgoing CircuitKey)
+
+	// OnFail observes the failed resolution of a forwarded HTLC.
+	OnFail(incoming, outgoing CircuitKey)
+}
+
 // AuxHtlcModifier is an interface that allows the sender to modify the outgoing
 // HTLC of a payment by changing the amount or the wire message tlv records.
 type AuxHtlcModifier interface {

htlcswitch/reputation_guard.go

@@ -0,0 +1,82 @@
+package htlcswitch
+
+import (
+	"sync/atomic"
+
+	"github.com/lightningnetwork/lnd/lnwire"
+)
+
+// guardedReputationManager wraps a ReputationManager so that a panic in any of
+// its hooks can never propagate into the switch's forwarding goroutine. The
+// reputation subsystem is log-only and MUST NOT be able to degrade forwarding;
+// if a hook panics we log it, permanently disable the subsystem (fail open),
+// and continue forwarding unaffected.
+//
+// The hooks run synchronously on the switch's forwarding goroutine, so this is
+// the boundary that keeps a subsystem bug — a nil deref, a bad map access, an
+// arithmetic panic — from taking down the node's HTLC forwarding.
+type guardedReputationManager struct {
+	inner    ReputationManager
+	disabled atomic.Bool
+}
+
+// NewGuardedReputationManager wraps the given ReputationManager with a panic
+// boundary. It returns nil when inner is nil, so the switch's existing nil
+// check still short-circuits a disabled subsystem with zero overhead.
+func NewGuardedReputationManager(inner ReputationManager) ReputationManager {
+	if inner == nil {
+		return nil
+	}
+
+	return &guardedReputationManager{inner: inner}
+}
+
+// OnForward forwards the observation to the wrapped manager behind a panic
+// boundary.
+func (g *guardedReputationManager) OnForward(incoming, outgoing CircuitKey,
+	incomingAmt, outgoingAmt lnwire.MilliSatoshi, incomingCltv uint32,
+	accountable bool) {
+
+	if g.disabled.Load() {
+		return
+	}
+	defer g.recoverHook("OnForward")
+
+	g.inner.OnForward(
+		incoming, outgoing, incomingAmt, outgoingAmt, incomingCltv,
+		accountable,
+	)
+}
+
+// OnSettle forwards the observation to the wrapped manager behind a panic
+// boundary.
+func (g *guardedReputationManager) OnSettle(incoming, outgoing CircuitKey) {
+	if g.disabled.Load() {
+		return
+	}
+	defer g.recoverHook("OnSettle")
+
+	g.inner.OnSettle(incoming, outgoing)
+}
+
+// OnFail forwards the observation to the wrapped manager behind a panic
+// boundary.
+func (g *guardedReputationManager) OnFail(incoming, outgoing CircuitKey) {
+	if g.disabled.Load() {
+		return
+	}
+	defer g.recoverHook("OnFail")
+
+	g.inner.OnFail(incoming, outgoing)
+}
+
+// recoverHook recovers from a panic in a reputation hook, logging it and
+// permanently disabling the subsystem so a deterministic bug cannot panic on
+// every forwarded HTLC. Forwarding is never affected.
+func (g *guardedReputationManager) recoverHook(method string) {
+	if r := recover(); r != nil {
+		log.Errorf("Reputation %s hook panicked; disabling reputation "+
+			"subsystem (forwarding is unaffected): %v", method, r)
+		g.disabled.Store(true)
+	}
+}