Update onion message handler docs for new auth scheme

In the previous commit, we stopped authenticating incoming onion messages via
an explicit nonce and hmac encoded in the message context, and entirely
switched to authenticating via the new NodeSigner::get_receive_auth_key more or
less included as AAD in the ChaCha20Poly1305 de/encoding for the messages. As
such, the message handler docs need updating to describe the new authentication
scheme.

Author: valentinewallace

lightning/src/blinded_path/message.rs

@@ -608,10 +608,8 @@ impl_writeable_tlv_based_enum!(AsyncPaymentsContext,
 /// [`DNSSECProof`]: crate::onion_message::dns_resolution::DNSSECProof
 #[derive(Clone, Debug, Hash, PartialEq, Eq)]
 pub struct DNSResolverContext {
-	/// A nonce which uniquely describes a DNS resolution.
-	///
-	/// When we receive a DNSSEC proof message, we should check that it was sent over the blinded
-	/// path we included in the request by comparing a stored nonce with this one.
+	/// A nonce which uniquely describes a DNS resolution, useful for looking up metadata about the
+	/// request.
 	pub nonce: [u8; 16],
 }
 

lightning/src/onion_message/async_payments.rs

@@ -28,7 +28,11 @@ const RELEASE_HELD_HTLC_TLV_TYPE: u64 = 74;
 
 /// A handler for an [`OnionMessage`] containing an async payments message as its payload.
 ///
+/// The [`AsyncPaymentsContext`]s provided to each method was authenticated by the
+/// [`OnionMessenger`] as coming from a blinded path that we created.
+///
 /// [`OnionMessage`]: crate::ln::msgs::OnionMessage
+/// [`OnionMessenger`]: crate::onion_message::messenger::OnionMessenger
 pub trait AsyncPaymentsMessageHandler {
 	/// Handle an [`OfferPathsRequest`] message. If we are a static invoice server and the message was
 	/// sent over paths that we previously provided to an async recipient, an [`OfferPaths`] message

lightning/src/onion_message/dns_resolution.rs

@@ -68,7 +68,12 @@ pub trait DNSResolverMessageHandler {
 
 	/// Handle a [`DNSSECProof`] message (in response to a [`DNSSECQuery`] we presumably sent).
 	///
+	/// The provided [`DNSResolverContext`] was authenticated by the [`OnionMessenger`] as coming from
+	/// a blinded path that we created.
+	///
 	/// With this, we should be able to validate the DNS record we requested.
+	///
+	/// [`OnionMessenger`]: crate::onion_message::messenger::OnionMessenger
 	fn handle_dnssec_proof(&self, message: DNSSECProof, context: DNSResolverContext);
 
 	/// Gets the node feature flags which this handler itself supports. Useful for setting the

lightning/src/onion_message/messenger.rs

@@ -906,6 +906,9 @@ pub trait CustomOnionMessageHandler {
 
 	/// Called with the custom message that was received, returning a response to send, if any.
 	///
+	/// If the provided `context` is `Some`, then the message was sent to a blinded path that we
+	/// created and was authenticated as such by the [`OnionMessenger`].
+	///
 	/// The returned [`Self::CustomMessage`], if any, is enqueued to be sent by [`OnionMessenger`].
 	fn handle_custom_message(
 		&self, message: Self::CustomMessage, context: Option<Vec<u8>>, responder: Option<Responder>,

lightning/src/onion_message/offers.rs

@@ -40,6 +40,15 @@ pub trait OffersMessageHandler {
 	/// Handles the given message by either responding with an [`Bolt12Invoice`], sending a payment,
 	/// or replying with an error.
 	///
+	/// If the provided [`OffersContext`] is `Some`, then the message was sent to a blinded path that we
+	/// created and was authenticated as such by the [`OnionMessenger`]. There are two exceptions to
+	/// this:
+	/// - [`OffersContext::InvoiceRequest`]
+	/// - [`OffersContext::OutboundPayment`]
+	/// In order to support offers and refunds created prior to LDK 0.2, these blinded path contexts
+	/// are not authenticated by the [`OnionMessenger`]. It is the responsibility of message handling
+	/// code to authenticate the provided [`OffersContext`] in these cases.
+	///
 	/// The returned [`OffersMessage`], if any, is enqueued to be sent by [`OnionMessenger`].
 	///
 	/// [`OnionMessenger`]: crate::onion_message::messenger::OnionMessenger