Util for blinded paths to configure an async recipient

As part of serving static invoices to payers on behalf of often-offline
recipients, these recipients need a way to contact the static invoice server to
retrieve blinded paths to include in their offers.

Add a utility to create blinded paths for this purpose as a static invoice
server. The recipient will be configured with the resulting paths and use them
to request offer paths on startup.

Author: valentinewallace

lightning/src/blinded_path/message.rs

@@ -406,6 +406,34 @@ pub enum OffersContext {
 /// [`AsyncPaymentsMessage`]: crate::onion_message::async_payments::AsyncPaymentsMessage
 #[derive(Clone, Debug)]
 pub enum AsyncPaymentsContext {
+	/// Context used by a [`BlindedMessagePath`] that an async recipient is configured with in
+	/// [`UserConfig::paths_to_static_invoice_server`], provided back to us in corresponding
+	/// [`OfferPathsRequest`]s.
+	///
+	/// [`UserConfig::paths_to_static_invoice_server`]: crate::util::config::UserConfig::paths_to_static_invoice_server
+	/// [`OfferPathsRequest`]: crate::onion_message::async_payments::OfferPathsRequest
+	OfferPathsRequest {
+		/// An identifier for the async recipient that is requesting blinded paths to include in their
+		/// [`Offer::paths`]. This ID is intended to be included in the reply path to our [`OfferPaths`]
+		/// response, and subsequently rate limit [`ServeStaticInvoice`] messages from recipients.
+		///
+		/// [`Offer::paths`]: crate::offers::offer::Offer::paths
+		/// [`OfferPaths`]: crate::onion_message::async_payments::OfferPaths
+		/// [`ServeStaticInvoice`]: crate::onion_message::async_payments::ServeStaticInvoice
+		recipient_id_nonce: Nonce,
+		/// Authentication code for the [`OfferPathsRequest`].
+		///
+		/// Prevents nodes from requesting offer paths from us without having been previously configured
+		/// with a [`BlindedMessagePath`] that we generated.
+		///
+		/// [`OfferPathsRequest`]: crate::onion_message::async_payments::OfferPathsRequest
+		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 an [`OfferPathsRequest`], provided back to us in corresponding
 	/// [`OfferPaths`] messages.
 	///
@@ -581,6 +609,11 @@ impl_writeable_tlv_based_enum!(AsyncPaymentsContext,
 		(12, hmac, required),
 		(14, path_absolute_expiry, required),
 	},
+	(4, OfferPathsRequest) => {
+		(0, recipient_id_nonce, required),
+		(2, hmac, required),
+		(4, path_absolute_expiry, required),
+	},
 );
 
 /// Contains a simple nonce for use in a blinded path's context.

lightning/src/ln/channelmanager.rs

@@ -10725,6 +10725,29 @@ where
 	}
 
 	#[cfg(any(test, async_payments))]
+	/// [`BlindedMessagePath`]s that an async recipient will be configured with via
+	/// [`UserConfig::paths_to_static_invoice_server`], enabling the recipient to request blinded
+	/// paths from us for inclusion in their [`Offer::paths`].
+	///
+	/// If `relative_expiry` is unset, the [`BlindedMessagePath`]s expiry will default to
+	/// [`DEFAULT_CONFIG_PATH_RELATIVE_EXPIRY`].
+	///
+	/// Returns the paths to be included in the recipient's
+	/// [`UserConfig::paths_to_static_invoice_server`] as well as a nonce that uniquely identifies the
+	/// recipient that has been configured with these paths. // TODO link to events that surface this nonce
+	///
+	/// [`UserConfig::paths_to_static_invoice_server`]: crate::util::config::UserConfig::paths_to_static_invoice_server
+	/// [`Offer::paths`]: crate::offers::offer::Offer::paths
+	/// [`DEFAULT_CONFIG_PATH_RELATIVE_EXPIRY`]: crate::onion_message::async_payments::DEFAULT_CONFIG_PATH_RELATIVE_EXPIRY
+	#[cfg(async_payments)]
+	pub fn blinded_paths_for_async_recipient(
+		&self, relative_expiry: Option<Duration>
+	) -> Result<(Vec<BlindedMessagePath>, Nonce), ()> {
+		let peers = self.get_peers_for_blinded_path();
+		let entropy = &*self.entropy_source;
+		self.flow.blinded_paths_for_async_recipient(peers, relative_expiry, entropy)
+	}
+
 	pub(super) fn duration_since_epoch(&self) -> Duration {
 		#[cfg(not(feature = "std"))]
 		let now = Duration::from_secs(

lightning/src/offers/flow.rs

@@ -229,6 +229,43 @@ impl<MR: Deref> OffersMessageFlow<MR>
 where
 	MR::Target: MessageRouter,
 {
+	/// [`BlindedMessagePath`]s that an async recipient will be configured with via
+	/// [`UserConfig::paths_to_static_invoice_server`], enabling the recipient to request blinded
+	/// paths from us for inclusion in their [`Offer::paths`].
+	///
+	/// If `relative_expiry` is unset, the resulting [`BlindedMessagePath`]s will not expire.
+	///
+	/// Returns the paths to be included in the recipient's
+	/// [`UserConfig::paths_to_static_invoice_server`] as well as a nonce that uniquely identifies the
+	/// recipient that has been configured with these paths.
+	///
+	/// [`UserConfig::paths_to_static_invoice_server`]: crate::util::config::UserConfig::paths_to_static_invoice_server
+	/// [`Offer::paths`]: crate::offers::offer::Offer::paths
+	/// [`DEFAULT_CONFIG_PATH_RELATIVE_EXPIRY`]: crate::onion_message::async_payments::DEFAULT_CONFIG_PATH_RELATIVE_EXPIRY
+	#[cfg(async_payments)]
+	pub fn blinded_paths_for_async_recipient<ES: Deref>(
+		&self, peers: Vec<MessageForwardNode>, relative_expiry: Option<Duration>, entropy: ES,
+	) -> Result<(Vec<BlindedMessagePath>, Nonce), ()>
+	where
+		ES::Target: EntropySource,
+	{
+		let expanded_key = &self.inbound_payment_key;
+
+		let path_absolute_expiry = relative_expiry
+			.unwrap_or(Duration::from_secs(u64::MAX))
+			.saturating_add(self.duration_since_epoch());
+
+		let recipient_id_nonce = Nonce::from_entropy_source(entropy);
+		let hmac = signer::hmac_for_offer_paths_request_context(recipient_id_nonce, expanded_key);
+
+		let context = MessageContext::AsyncPayments(AsyncPaymentsContext::OfferPathsRequest {
+			recipient_id_nonce,
+			hmac,
+			path_absolute_expiry,
+		});
+		self.create_blinded_paths(peers, context).map(|paths| (paths, recipient_id_nonce))
+	}
+
 	/// Creates a collection of blinded paths by delegating to [`MessageRouter`] based on
 	/// the path's intended lifetime.
 	///

lightning/src/offers/signer.rs

@@ -65,6 +65,10 @@ const ASYNC_PAYMENTS_OFFER_PATHS_INPUT: &[u8; 16] = &[10; 16];
 #[cfg(async_payments)]
 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];
+
 /// Message metadata which possibly is derived from [`MetadataMaterial`] such that it can be
 /// verified.
 #[derive(Clone)]
@@ -581,6 +585,19 @@ pub(crate) fn verify_held_htlc_available_context(
 	}
 }
 
+#[cfg(async_payments)]
+pub(crate) fn hmac_for_offer_paths_request_context(
+	nonce: Nonce, expanded_key: &ExpandedKey,
+) -> Hmac<Sha256> {
+	const IV_BYTES: &[u8; IV_LEN] = b"LDK Paths Please"; // TODO
+	let mut hmac = expanded_key.hmac_for_offer();
+	hmac.input(IV_BYTES);
+	hmac.input(&nonce.0);
+	hmac.input(ASYNC_PAYMENTS_OFFER_PATHS_REQUEST_INPUT);
+
+	Hmac::from_engine(hmac)
+}
+
 #[cfg(async_payments)]
 pub(crate) fn hmac_for_offer_paths_context(
 	nonce: Nonce, expanded_key: &ExpandedKey,