Send offer paths in response to requests

As part of serving static invoices to payers on behalf of often-offline
recipients, we need to provide the async recipient with blinded message paths
to include in their offers.

Support responding to inbound requests for offer paths from async recipients.

Author: valentinewallace

lightning/src/blinded_path/message.rs

@@ -36,6 +36,7 @@ use bitcoin::hashes::sha256::Hash as Sha256;
 
 use core::mem;
 use core::ops::Deref;
+use core::time::Duration;
 
 /// A blinded path to be used for sending or receiving a message, hiding the identity of the
 /// recipient.
@@ -343,6 +344,47 @@ pub enum OffersContext {
 		/// [`Offer`]: crate::offers::offer::Offer
 		nonce: Nonce,
 	},
+	/// Context used by a [`BlindedMessagePath`] within the [`Offer`] of an async recipient.
+	///
+	/// This variant is received by the static invoice server when handling an [`InvoiceRequest`] on
+	/// behalf of said async recipient.
+	///
+	/// [`StaticInvoice`]: crate::offers::static_invoice::StaticInvoice
+	/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
+	StaticInvoiceRequested {
+		/// An identifier for the async recipient for whom the static invoice server is serving
+		/// [`StaticInvoice`]s. Used to look up a corresponding [`StaticInvoice`] to return to the payer
+		/// if the recipient is offline.
+		///
+		/// Also useful for the server to rate limit the number of [`InvoiceRequest`]s it will respond
+		/// to on recipient's behalf.
+		///
+		/// [`StaticInvoice`]: crate::offers::static_invoice::StaticInvoice
+		/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
+		recipient_id_nonce: Nonce,
+
+		/// A nonce used for authenticating that a received [`InvoiceRequest`] is valid for a preceding
+		/// [`OfferPaths`] message sent by the static invoice server.
+		///
+		/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
+		/// [`OfferPaths`]: crate::onion_message::async_payments::OfferPaths
+		nonce: Nonce,
+
+		/// Authentication code for the [`InvoiceRequest`].
+		///
+		/// Prevents nodes from creating their own blinded path to the static invoice server and causing
+		/// them to unintentionally hit their database looking for a [`StaticInvoice`] to return.
+		///
+		/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
+		/// [`StaticInvoice`]: crate::offers::static_invoice::StaticInvoice
+		hmac: Hmac<Sha256>,
+
+		/// The time as duration since the Unix epoch at which this path expires and messages sent over
+		/// it should be ignored.
+		///
+		/// Useful to timeout async recipients that are no longer supported as clients.
+		path_absolute_expiry: Duration,
+	},
 	/// Context used by a [`BlindedMessagePath`] within a [`Refund`] or as a reply path for an
 	/// [`InvoiceRequest`].
 	///
@@ -459,6 +501,43 @@ pub enum AsyncPaymentsContext {
 		/// offer paths if we are no longer configured to accept paths from them.
 		path_absolute_expiry: core::time::Duration,
 	},
+	/// Context used by a reply path to an [`OfferPaths`] message, provided back to the static invoice
+	/// server in corresponding [`ServeStaticInvoice`] messages.
+	///
+	/// [`OfferPaths`]: crate::onion_message::async_payments::OfferPaths
+	/// [`ServeStaticInvoice`]: crate::onion_message::async_payments::ServeStaticInvoice
+	ServeStaticInvoice {
+		/// An identifier for the async recipient that is requesting that a [`StaticInvoice`] be served
+		/// on their behalf.
+		///
+		/// Useful as a key to retrieve the invoice when payers send an [`InvoiceRequest`] to the static
+		/// invoice server. Also useful to rate limit the invoices being persisted on behalf of a
+		/// particular recipient.
+		///
+		/// [`StaticInvoice`]: crate::offers::static_invoice::StaticInvoice
+		/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
+		/// [`Offer::paths`]: crate::offers::offer::Offer::paths
+		recipient_id_nonce: Nonce,
+		/// A nonce used for authenticating that a [`ServeStaticInvoice`] message is valid for a preceding
+		/// [`OfferPaths`] message.
+		///
+		/// [`ServeStaticInvoice`]: crate::onion_message::async_payments::ServeStaticInvoice
+		/// [`OfferPaths`]: crate::onion_message::async_payments::OfferPaths
+		nonce: Nonce,
+		/// Authentication code for the [`ServeStaticInvoice`] message.
+		///
+		/// Prevents nodes from creating their own blinded path to the static invoice server and causing
+		/// them to persist an unintended [`StaticInvoice`].
+		///
+		/// [`ServeStaticInvoice`]: crate::onion_message::async_payments::ServeStaticInvoice
+		/// [`StaticInvoice`]: crate::offers::static_invoice::StaticInvoice
+		hmac: Hmac<Sha256>,
+		/// The time as duration since the Unix epoch at which this path expires and messages sent over
+		/// it should be ignored.
+		///
+		/// Useful to timeout async recipients that are no longer supported as clients.
+		path_absolute_expiry: core::time::Duration,
+	},
 	/// Context used by a reply path to a [`ServeStaticInvoice`] message, provided back to us in
 	/// corresponding [`StaticInvoicePersisted`] messages.
 	///
@@ -580,6 +659,12 @@ impl_writeable_tlv_based_enum!(OffersContext,
 		(1, nonce, required),
 		(2, hmac, required)
 	},
+	(3, StaticInvoiceRequested) => {
+		(0, recipient_id_nonce, required),
+		(2, nonce, required),
+		(4, hmac, required),
+		(6, path_absolute_expiry, required),
+	},
 );
 
 impl_writeable_tlv_based_enum!(AsyncPaymentsContext,
@@ -613,6 +698,12 @@ impl_writeable_tlv_based_enum!(AsyncPaymentsContext,
 		(2, hmac, required),
 		(4, path_absolute_expiry, required),
 	},
+	(5, ServeStaticInvoice) => {
+		(0, recipient_id_nonce, required),
+		(2, nonce, required),
+		(4, hmac, required),
+		(6, path_absolute_expiry, required),
+	},
 );
 
 /// Contains a simple nonce for use in a blinded path's context.

lightning/src/ln/channelmanager.rs

@@ -12887,6 +12887,21 @@ where
 		&self, _message: OfferPathsRequest, _context: AsyncPaymentsContext,
 		_responder: Option<Responder>,
 	) -> Option<(OfferPaths, ResponseInstruction)> {
+		#[cfg(async_payments)]
+		{
+			let peers = self.get_peers_for_blinded_path();
+			let (message, reply_path_context) = match self.flow.handle_offer_paths_request(
+				_context,
+				peers,
+				&*self.entropy_source,
+			) {
+				Some(msg) => msg,
+				None => return None,
+			};
+			_responder.map(|resp| (message, resp.respond_with_reply_path(reply_path_context)))
+		}
+
+		#[cfg(not(async_payments))]
 		None
 	}
 

lightning/src/offers/flow.rs

@@ -228,6 +228,10 @@ const OFFERS_MESSAGE_REQUEST_LIMIT: usize = 10;
 #[cfg(async_payments)]
 const TEMP_REPLY_PATH_RELATIVE_EXPIRY: Duration = Duration::from_secs(7200);
 
+// Default to async receive offers and the paths used to update them lasting 1 year.
+#[cfg(async_payments)]
+const DEFAULT_ASYNC_RECEIVE_OFFER_EXPIRY: Duration = Duration::from_secs(365 * 24 * 60 * 60);
+
 impl<MR: Deref> OffersMessageFlow<MR>
 where
 	MR::Target: MessageRouter,
@@ -1314,6 +1318,84 @@ where
 		}
 	}
 
+	/// Handles an incoming [`OfferPathsRequest`] onion message from an often-offline recipient who
+	/// wants us (the static invoice server) to serve [`StaticInvoice`]s to payers on their behalf.
+	/// Sends out [`OfferPaths`] onion messages in response.
+	#[cfg(async_payments)]
+	pub(crate) fn handle_offer_paths_request<ES: Deref>(
+		&self, context: AsyncPaymentsContext, peers: Vec<MessageForwardNode>, entropy: ES,
+	) -> Option<(OfferPaths, MessageContext)>
+	where
+		ES::Target: EntropySource,
+	{
+		let expanded_key = &self.inbound_payment_key;
+		let duration_since_epoch = self.duration_since_epoch();
+
+		// First verify the message context to make sure we created the blinded path that this message
+		// was received over.
+		let recipient_id_nonce = match context {
+			AsyncPaymentsContext::OfferPathsRequest {
+				recipient_id_nonce,
+				hmac,
+				path_absolute_expiry,
+			} => {
+				if let Err(()) = signer::verify_offer_paths_request_context(
+					recipient_id_nonce,
+					hmac,
+					expanded_key,
+				) {
+					return None;
+				}
+				if duration_since_epoch > path_absolute_expiry {
+					return None;
+				}
+				recipient_id_nonce
+			},
+			_ => return None,
+		};
+
+		// Next create the blinded paths that will be included in the async recipient's offer.
+		let (offer_paths, paths_expiry) = {
+			let path_absolute_expiry =
+				duration_since_epoch.saturating_add(DEFAULT_ASYNC_RECEIVE_OFFER_EXPIRY);
+			let nonce = Nonce::from_entropy_source(&*entropy);
+			let hmac = signer::hmac_for_async_recipient_invreq_context(nonce, expanded_key);
+			let context = OffersContext::StaticInvoiceRequested {
+				recipient_id_nonce,
+				nonce,
+				hmac,
+				path_absolute_expiry,
+			};
+			match self.create_blinded_paths_using_absolute_expiry(
+				context,
+				Some(path_absolute_expiry),
+				peers,
+			) {
+				Ok(paths) => (paths, path_absolute_expiry),
+				Err(()) => return None,
+			}
+		};
+
+		// Finally create a reply path so that the recipient can respond to our offer_paths message with
+		// the static invoice that they create, that corresponds to the offer containing our paths.
+		let reply_path_context = {
+			let nonce = Nonce::from_entropy_source(entropy);
+			let path_absolute_expiry =
+				duration_since_epoch.saturating_add(DEFAULT_ASYNC_RECEIVE_OFFER_EXPIRY);
+			let hmac = signer::hmac_for_serve_static_invoice_context(nonce, expanded_key);
+			MessageContext::AsyncPayments(AsyncPaymentsContext::ServeStaticInvoice {
+				nonce,
+				recipient_id_nonce,
+				hmac,
+				path_absolute_expiry,
+			})
+		};
+
+		let offer_paths_om =
+			OfferPaths { paths: offer_paths, paths_absolute_expiry: Some(paths_expiry) };
+		return Some((offer_paths_om, reply_path_context));
+	}
+
 	/// Handles an incoming [`OfferPaths`] message from the static invoice server, sending out
 	/// [`ServeStaticInvoice`] onion messages in response if we want to use the paths we've received
 	/// to build and cache an async receive offer.

lightning/src/offers/signer.rs

@@ -70,6 +70,16 @@ const ASYNC_PAYMENTS_STATIC_INV_PERSISTED_INPUT: &[u8; 16] = &[11; 16];
 #[cfg(async_payments)]
 const ASYNC_PAYMENTS_OFFER_PATHS_REQUEST_INPUT: &[u8; 16] = &[12; 16];
 
+/// HMAC input used in `OffersContext::StaticInvoiceRequested` to authenticate inbound invoice
+/// requests that are being serviced on behalf of async recipients.
+#[cfg(async_payments)]
+const ASYNC_PAYMENTS_INVREQ: &[u8; 16] = &[13; 16];
+
+/// HMAC input used in `AsyncPaymentsContext::ServeStaticInvoice` to authenticate inbound
+/// serve_static_invoice onion messages.
+#[cfg(async_payments)]
+const ASYNC_PAYMENTS_SERVE_STATIC_INVOICE_INPUT: &[u8; 16] = &[14; 16];
+
 /// Message metadata which possibly is derived from [`MetadataMaterial`] such that it can be
 /// verified.
 #[derive(Clone)]
@@ -599,6 +609,17 @@ pub(crate) fn hmac_for_offer_paths_request_context(
 	Hmac::from_engine(hmac)
 }
 
+#[cfg(async_payments)]
+pub(crate) fn verify_offer_paths_request_context(
+	nonce: Nonce, hmac: Hmac<Sha256>, expanded_key: &ExpandedKey,
+) -> Result<(), ()> {
+	if hmac_for_offer_paths_request_context(nonce, expanded_key) == hmac {
+		Ok(())
+	} else {
+		Err(())
+	}
+}
+
 #[cfg(async_payments)]
 pub(crate) fn hmac_for_offer_paths_context(
 	nonce: Nonce, expanded_key: &ExpandedKey,
@@ -623,6 +644,19 @@ pub(crate) fn verify_offer_paths_context(
 	}
 }
 
+#[cfg(async_payments)]
+pub(crate) fn hmac_for_serve_static_invoice_context(
+	nonce: Nonce, expanded_key: &ExpandedKey,
+) -> Hmac<Sha256> {
+	const IV_BYTES: &[u8; IV_LEN] = b"LDK Serve Inv~~~";
+	let mut hmac = expanded_key.hmac_for_offer();
+	hmac.input(IV_BYTES);
+	hmac.input(&nonce.0);
+	hmac.input(ASYNC_PAYMENTS_SERVE_STATIC_INVOICE_INPUT);
+
+	Hmac::from_engine(hmac)
+}
+
 #[cfg(async_payments)]
 pub(crate) fn hmac_for_static_invoice_persisted_context(
 	nonce: Nonce, expanded_key: &ExpandedKey,
@@ -646,3 +680,16 @@ pub(crate) fn verify_static_invoice_persisted_context(
 		Err(())
 	}
 }
+
+#[cfg(async_payments)]
+pub(crate) fn hmac_for_async_recipient_invreq_context(
+	nonce: Nonce, expanded_key: &ExpandedKey,
+) -> Hmac<Sha256> {
+	const IV_BYTES: &[u8; IV_LEN] = b"LDK Async Invreq";
+	let mut hmac = expanded_key.hmac_for_offer();
+	hmac.input(IV_BYTES);
+	hmac.input(&nonce.0);
+	hmac.input(ASYNC_PAYMENTS_INVREQ);
+
+	Hmac::from_engine(hmac)
+}