Add per-peer onion message interception API to OnionMessenger

Add `register_peer_for_interception()` and
`deregister_peer_for_interception()` methods to `OnionMessenger`,
allowing specific peers to be registered for onion message interception
without enabling blanket interception for all offline peers.

When a registered peer is offline and an onion message needs to be
forwarded to them, `Event::OnionMessageIntercepted` is emitted. When
a registered peer connects, `Event::OnionMessagePeerConnected` is
emitted. This works alongside the existing global
`new_with_offline_peer_interception()` flag — if either the global flag
is set or the peer is specifically registered, interception occurs.

This enables LSPS2 services to intercept onion messages only for peers
with active JIT channel sessions, rather than intercepting messages for
all offline peers.

Co-Authored-By: HAL 9000

Author: tnull

lightning/src/onion_message/messenger.rs

@@ -125,6 +125,82 @@ impl<
 	}
 }
 
+/// A trait for registering peers and SCIDs for onion message interception.
+///
+/// When a peer is registered for interception and is currently offline, any onion messages
+/// intended to be forwarded to them will generate an [`Event::OnionMessageIntercepted`] instead
+/// of being dropped. When a registered peer connects, an [`Event::OnionMessagePeerConnected`]
+/// will be generated.
+///
+/// Additionally, SCIDs (short channel IDs) can be registered for interception. When an onion
+/// message is forwarded with a [`NextMessageHop::ShortChannelId`] that cannot be resolved via
+/// [`NodeIdLookUp`] but is registered here, an [`Event::OnionMessageIntercepted`] will be
+/// generated using the associated peer's node ID. This enables compact SCID-based encoding in
+/// blinded message paths for scenarios like LSPS2 JIT channels where the SCID is a fake
+/// intercept SCID that does not correspond to a real channel.
+///
+/// [`OnionMessenger`] implements this trait, but it is also useful as a trait object to allow
+/// external components (e.g., an LSPS2 service) to register peers for interception without
+/// needing to know the concrete [`OnionMessenger`] type.
+///
+/// [`NextMessageHop::ShortChannelId`]: crate::blinded_path::message::NextMessageHop::ShortChannelId
+/// [`Event::OnionMessageIntercepted`]: crate::events::Event::OnionMessageIntercepted
+/// [`Event::OnionMessagePeerConnected`]: crate::events::Event::OnionMessagePeerConnected
+pub trait OnionMessageInterceptor {
+	/// Registers a peer for onion message interception.
+	///
+	/// See [`OnionMessenger::register_peer_for_interception`] for more details.
+	fn register_peer_for_interception(&self, peer_node_id: PublicKey);
+
+	/// Deregisters a peer from onion message interception.
+	///
+	/// See [`OnionMessenger::deregister_peer_for_interception`] for more details.
+	///
+	/// Returns whether the peer was previously registered.
+	fn deregister_peer_for_interception(&self, peer_node_id: &PublicKey) -> bool;
+
+	/// Registers a short channel ID for onion message interception.
+	///
+	/// See [`OnionMessenger::register_scid_for_interception`] for more details.
+	fn register_scid_for_interception(&self, scid: u64, peer_node_id: PublicKey);
+
+	/// Deregisters a short channel ID from onion message interception.
+	///
+	/// See [`OnionMessenger::deregister_scid_for_interception`] for more details.
+	///
+	/// Returns whether the SCID was previously registered.
+	fn deregister_scid_for_interception(&self, scid: u64) -> bool;
+}
+
+impl<
+		ES: EntropySource,
+		NS: NodeSigner,
+		L: Logger,
+		NL: NodeIdLookUp,
+		MR: MessageRouter,
+		OMH: OffersMessageHandler,
+		APH: AsyncPaymentsMessageHandler,
+		DRH: DNSResolverMessageHandler,
+		CMH: CustomOnionMessageHandler,
+	> OnionMessageInterceptor for OnionMessenger<ES, NS, L, NL, MR, OMH, APH, DRH, CMH>
+{
+	fn register_peer_for_interception(&self, peer_node_id: PublicKey) {
+		OnionMessenger::register_peer_for_interception(self, peer_node_id)
+	}
+
+	fn deregister_peer_for_interception(&self, peer_node_id: &PublicKey) -> bool {
+		OnionMessenger::deregister_peer_for_interception(self, peer_node_id)
+	}
+
+	fn register_scid_for_interception(&self, scid: u64, peer_node_id: PublicKey) {
+		OnionMessenger::register_scid_for_interception(self, scid, peer_node_id)
+	}
+
+	fn deregister_scid_for_interception(&self, scid: u64) -> bool {
+		OnionMessenger::deregister_scid_for_interception(self, scid)
+	}
+}
+
 /// A sender, receiver and forwarder of [`OnionMessage`]s.
 ///
 /// # Handling Messages
@@ -273,6 +349,8 @@ pub struct OnionMessenger<
 	dns_resolver_handler: DRH,
 	custom_handler: CMH,
 	intercept_messages_for_offline_peers: bool,
+	peers_registered_for_interception: Mutex<HashSet<PublicKey>>,
+	scids_registered_for_interception: Mutex<HashMap<u64, PublicKey>>,
 	pending_intercepted_msgs_events: Mutex<Vec<Event>>,
 	pending_peer_connected_events: Mutex<Vec<Event>>,
 	pending_events_processor: AtomicBool,
@@ -1453,6 +1531,8 @@ impl<
 			dns_resolver_handler: dns_resolver,
 			custom_handler,
 			intercept_messages_for_offline_peers,
+			peers_registered_for_interception: Mutex::new(new_hash_set()),
+			scids_registered_for_interception: Mutex::new(new_hash_map()),
 			pending_intercepted_msgs_events: Mutex::new(Vec::new()),
 			pending_peer_connected_events: Mutex::new(Vec::new()),
 			pending_events_processor: AtomicBool::new(false),
@@ -1470,6 +1550,65 @@ impl<
 		self.async_payments_handler = async_payments_handler;
 	}
 
+	/// Registers a peer for onion message interception.
+	///
+	/// When an onion message needs to be forwarded to a registered peer that is currently offline,
+	/// an [`Event::OnionMessageIntercepted`] will be generated, allowing the message to be stored
+	/// and forwarded later when the peer reconnects.
+	///
+	/// Similarly, when a registered peer connects, an [`Event::OnionMessagePeerConnected`] will
+	/// be generated.
+	///
+	/// This is useful for services like LSPS2 that need to intercept onion messages for specific
+	/// peers (e.g., those with active JIT channel sessions) without enabling blanket interception
+	/// for all offline peers via [`Self::new_with_offline_peer_interception`].
+	///
+	/// Use [`Self::deregister_peer_for_interception`] to stop intercepting messages for this peer.
+	///
+	/// [`Event::OnionMessageIntercepted`]: crate::events::Event::OnionMessageIntercepted
+	/// [`Event::OnionMessagePeerConnected`]: crate::events::Event::OnionMessagePeerConnected
+	pub fn register_peer_for_interception(&self, peer_node_id: PublicKey) {
+		self.peers_registered_for_interception.lock().unwrap().insert(peer_node_id);
+	}
+
+	/// Deregisters a peer from onion message interception.
+	///
+	/// After this call, onion messages for this peer will no longer be intercepted (unless
+	/// blanket interception is enabled via [`Self::new_with_offline_peer_interception`]).
+	///
+	/// Returns whether the peer was previously registered.
+	pub fn deregister_peer_for_interception(&self, peer_node_id: &PublicKey) -> bool {
+		self.peers_registered_for_interception.lock().unwrap().remove(peer_node_id)
+	}
+
+	/// Registers a short channel ID for onion message interception, associating it with
+	/// `peer_node_id`.
+	///
+	/// When an onion message is forwarded with a [`NextMessageHop::ShortChannelId`] that cannot
+	/// be resolved via [`NodeIdLookUp`] but matches a registered SCID, an
+	/// [`Event::OnionMessageIntercepted`] will be generated using the associated `peer_node_id`.
+	///
+	/// This is useful for services like LSPS2 where fake intercept SCIDs are used in compact
+	/// blinded message paths. The SCID does not correspond to a real channel, so
+	/// [`NodeIdLookUp`] cannot resolve it, but the message should still be intercepted rather
+	/// than dropped.
+	///
+	/// Use [`Self::deregister_scid_for_interception`] to stop intercepting messages for this
+	/// SCID.
+	///
+	/// [`NextMessageHop::ShortChannelId`]: crate::blinded_path::message::NextMessageHop::ShortChannelId
+	/// [`Event::OnionMessageIntercepted`]: crate::events::Event::OnionMessageIntercepted
+	pub fn register_scid_for_interception(&self, scid: u64, peer_node_id: PublicKey) {
+		self.scids_registered_for_interception.lock().unwrap().insert(scid, peer_node_id);
+	}
+
+	/// Deregisters a short channel ID from onion message interception.
+	///
+	/// Returns whether the SCID was previously registered.
+	pub fn deregister_scid_for_interception(&self, scid: u64) -> bool {
+		self.scids_registered_for_interception.lock().unwrap().remove(&scid).is_some()
+	}
+
 	/// Sends an [`OnionMessage`] based on its [`MessageSendInstructions`].
 	pub fn send_onion_message<T: OnionMessageContents>(
 		&self, contents: T, instructions: MessageSendInstructions,
@@ -1664,8 +1803,30 @@ impl<
 			NextMessageHop::ShortChannelId(scid) => match self.node_id_lookup.next_node_id(scid) {
 				Some(pubkey) => pubkey,
 				None => {
-					log_trace!(self.logger, "Dropping forwarded onion messager: unable to resolve next hop using SCID {} {}", scid, log_suffix);
-					return Err(SendError::GetNodeIdFailed);
+					// The SCID is unknown to NodeIdLookUp (not a real channel). Check
+					// if it's registered for SCID-based interception before dropping.
+					match self.scids_registered_for_interception.lock().unwrap().get(&scid).copied()
+					{
+						Some(peer_node_id) => {
+							log_trace!(
+								self.logger,
+								"Generating OnionMessageIntercepted event for \
+								 SCID {} (peer {}) {}",
+								scid,
+								peer_node_id,
+								log_suffix
+							);
+							self.enqueue_intercepted_event(Event::OnionMessageIntercepted {
+								peer_node_id,
+								message: onion_message,
+							});
+							return Ok(());
+						},
+						None => {
+							log_trace!(self.logger, "Dropping forwarded onion message: unable to resolve next hop using SCID {} {}", scid, log_suffix);
+							return Err(SendError::GetNodeIdFailed);
+						},
+					}
 				},
 			},
 		};
@@ -1686,6 +1847,9 @@ impl<
 			.entry(next_node_id)
 			.or_insert_with(|| OnionMessageRecipient::ConnectedPeer(VecDeque::new()));
 
+		let should_intercept = self.intercept_messages_for_offline_peers
+			|| self.peers_registered_for_interception.lock().unwrap().contains(&next_node_id);
+
 		match message_recipients.entry(next_node_id) {
 			hash_map::Entry::Occupied(mut e)
 				if matches!(e.get(), OnionMessageRecipient::ConnectedPeer(..)) =>
@@ -1699,7 +1863,7 @@ impl<
 				);
 				Ok(())
 			},
-			_ if self.intercept_messages_for_offline_peers => {
+			_ if should_intercept => {
 				log_trace!(
 					self.logger,
 					"Generating OnionMessageIntercepted event for peer {} {}",
@@ -2142,7 +2306,15 @@ impl<
 					.or_insert_with(|| OnionMessageRecipient::ConnectedPeer(VecDeque::new()))
 					.mark_connected();
 			}
-			if self.intercept_messages_for_offline_peers {
+			let is_registered =
+				self.peers_registered_for_interception.lock().unwrap().contains(&their_node_id);
+			let is_registered_by_scid = self
+				.scids_registered_for_interception
+				.lock()
+				.unwrap()
+				.values()
+				.any(|nid| *nid == their_node_id);
+			if self.intercept_messages_for_offline_peers || is_registered || is_registered_by_scid {
 				let mut pending_peer_connected_events =
 					self.pending_peer_connected_events.lock().unwrap();
 				pending_peer_connected_events