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,33 @@ 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 the static invoice server 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 will be surfaced when the async recipient eventually sends a
+		/// corresponding [`ServeStaticInvoice`] message, and can be used to rate limit the recipient.
+		///
+		/// [`Offer::paths`]: crate::offers::offer::Offer::paths
+		/// [`ServeStaticInvoice`]: crate::onion_message::async_payments::ServeStaticInvoice
+		recipient_id_nonce: Nonce,
+		/// Authentication code for the [`OfferPathsRequest`].
+		///
+		/// Prevents nodes from requesting offer paths from the static invoice server without having
+		/// been previously configured with a [`BlindedMessagePath`] that the server 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 as an async
 	/// recipient in corresponding [`OfferPaths`] messages from the static invoice server.
 	///
@@ -581,6 +608,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

@@ -11013,6 +11013,36 @@ where
 		inbound_payment::get_payment_preimage(payment_hash, payment_secret, &self.inbound_payment_key)
 	}
 
+	/// [`BlindedMessagePath`]s for an async recipient to communicate with this node and interactively
+	/// build [`Offer`]s and [`StaticInvoice`]s for receiving async payments.
+	///
+	/// ## Usage
+	/// 1. Static invoice server calls [`Self::blinded_paths_for_async_recipient`]
+	/// 2. Static invoice server communicates the resulting paths out-of-band to the async recipient,
+	///     who includes these paths in their [`UserConfig::paths_to_static_invoice_server`]
+	/// 3. Async recipient automatically sends [`OfferPathsRequest`]s over the configured paths, and
+	///     uses the resulting paths from the server's [`OfferPaths`] response to build their async
+	///     receive offer
+	///
+	/// 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)
+	}
+
 	#[cfg(any(test, async_payments))]
 	#[rustfmt::skip]
 	pub(super) fn duration_since_epoch(&self) -> Duration {

lightning/src/offers/flow.rs

@@ -232,6 +232,51 @@ impl<MR: Deref> OffersMessageFlow<MR>
 where
 	MR::Target: MessageRouter,
 {
+	/// [`BlindedMessagePath`]s for an async recipient to communicate with this node and interactively
+	/// build [`Offer`]s and [`StaticInvoice`]s for receiving async payments.
+	///
+	/// ## Usage
+	/// 1. Static invoice server calls [`Self::blinded_paths_for_async_recipient`]
+	/// 2. Static invoice server communicates the resulting paths out-of-band to the async recipient,
+	///     who includes these paths in their [`UserConfig::paths_to_static_invoice_server`]
+	/// 3. Async recipient automatically sends [`OfferPathsRequest`]s to the server over the
+	///     configured paths, and uses the paths from the server's [`OfferPaths`] response to build
+	///     their async receive offer
+	///
+	/// 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<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,11 @@ const ASYNC_PAYMENTS_OFFER_PATHS_INPUT: &[u8; 16] = &[10; 16];
 #[cfg(async_payments)]
 const ASYNC_PAYMENTS_STATIC_INV_PERSISTED_INPUT: &[u8; 16] = &[11; 16];
 
+/// HMAC input used in `AsyncPaymentsContext::OfferPathsRequest` to authenticate inbound
+/// offer_paths_request onion messages.
+#[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 +586,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,