Send static invoice in response to offer paths

As an async recipient, we need to interactively build a static invoice that an
always-online node will serve to payers on our behalf.

As part of this process, the static invoice server sends us blinded message
paths to include in our offer so they'll receive invoice requests from senders
trying to pay us while we're offline. On receipt of these paths, create an
offer and static invoice and send the invoice back to the server so they can
provide the invoice to payers.

Author: valentinewallace

lightning/src/blinded_path/message.rs

@@ -23,6 +23,8 @@ use crate::ln::channelmanager::PaymentId;
 use crate::ln::msgs::DecodeError;
 use crate::ln::onion_utils;
 use crate::offers::nonce::Nonce;
+use crate::offers::offer::Offer;
+use crate::onion_message::messenger::Responder;
 use crate::onion_message::packet::ControlTlvs;
 use crate::routing::gossip::{NodeId, ReadOnlyNetworkGraph};
 use crate::sign::{EntropySource, NodeSigner, Recipient};
@@ -417,6 +419,58 @@ 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 a [`ServeStaticInvoice`] message, provided back to us in
+	/// corresponding [`StaticInvoicePersisted`] messages.
+	///
+	/// [`ServeStaticInvoice`]: crate::onion_message::async_payments::ServeStaticInvoice
+	/// [`StaticInvoicePersisted`]: crate::onion_message::async_payments::StaticInvoicePersisted
+	StaticInvoicePersisted {
+		/// The offer corresponding to the [`StaticInvoice`] that has been persisted. This invoice is
+		/// now ready to be provided by the static invoice server in response to [`InvoiceRequest`]s.
+		///
+		/// [`StaticInvoice`]: crate::offers::static_invoice::StaticInvoice
+		/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
+		offer: Offer,
+		/// A [`Nonce`] useful for updating the [`StaticInvoice`] that corresponds to the
+		/// [`AsyncPaymentsContext::StaticInvoicePersisted::offer`], since the offer may be much longer
+		/// lived than the invoice.
+		///
+		/// [`StaticInvoice`]: crate::offers::static_invoice::StaticInvoice
+		offer_nonce: Nonce,
+		/// Useful to determine how far an offer is into its lifespan, to decide whether the offer is
+		/// expiring soon and we should start building a new one.
+		offer_created_at: core::time::Duration,
+		/// A [`Responder`] useful for updating the [`StaticInvoice`] that corresponds to the
+		/// [`AsyncPaymentsContext::StaticInvoicePersisted::offer`], since the offer may be much longer
+		/// lived than the invoice.
+		///
+		/// [`StaticInvoice`]: crate::offers::static_invoice::StaticInvoice
+		update_static_invoice_path: Responder,
+		/// The time as duration since the Unix epoch at which the [`StaticInvoice`] expires, used to track
+		/// when we need to generate and persist a new invoice with the static invoice server.
+		///
+		/// [`StaticInvoice`]: crate::offers::static_invoice::StaticInvoice
+		static_invoice_absolute_expiry: core::time::Duration,
+		/// A nonce used for authenticating that a [`StaticInvoicePersisted`] message is valid for a
+		/// preceding [`ServeStaticInvoice`] message.
+		///
+		/// [`StaticInvoicePersisted`]: crate::onion_message::async_payments::StaticInvoicePersisted
+		/// [`ServeStaticInvoice`]: crate::onion_message::async_payments::ServeStaticInvoice
+		nonce: Nonce,
+		/// Authentication code for the [`StaticInvoicePersisted`] message.
+		///
+		/// Prevents nodes from creating their own blinded path to us and causing us to cache an
+		/// unintended async receive offer.
+		///
+		/// [`StaticInvoicePersisted`]: crate::onion_message::async_payments::StaticInvoicePersisted
+		hmac: Hmac<Sha256>,
+		/// The time as duration since the Unix epoch at which this path expires and messages sent over
+		/// it should be ignored.
+		///
+		/// Prevents a static invoice server from causing an async recipient to cache an old offer if
+		/// the recipient is no longer configured to use that server.
+		path_absolute_expiry: core::time::Duration,
+	},
 	/// Context contained within the reply [`BlindedMessagePath`] we put in outbound
 	/// [`HeldHtlcAvailable`] messages, provided back to us in corresponding [`ReleaseHeldHtlc`]
 	/// messages.
@@ -502,6 +556,16 @@ impl_writeable_tlv_based_enum!(AsyncPaymentsContext,
 	(2, OfferPaths) => {
 		(0, path_absolute_expiry, required),
 	},
+	(3, StaticInvoicePersisted) => {
+		(0, offer, required),
+		(2, offer_nonce, required),
+		(4, offer_created_at, required),
+		(6, update_static_invoice_path, required),
+		(8, static_invoice_absolute_expiry, required),
+		(10, nonce, required),
+		(12, hmac, required),
+		(14, path_absolute_expiry, required),
+	},
 );
 
 /// Contains a simple nonce for use in a blinded path's context.

lightning/src/ln/channelmanager.rs

@@ -13042,7 +13042,30 @@ where
 	fn handle_offer_paths(
 		&self, _message: OfferPaths, _context: AsyncPaymentsContext, _responder: Option<Responder>,
 	) -> Option<(ServeStaticInvoice, ResponseInstruction)> {
-		None
+		#[cfg(async_payments)]
+		{
+			let responder = match _responder {
+				Some(responder) => responder,
+				None => return None,
+			};
+			let (serve_static_invoice, reply_context) = match self.flow.handle_offer_paths(
+				_message,
+				_context,
+				responder.clone(),
+				self.get_peers_for_blinded_path(),
+				self.list_usable_channels(),
+				&*self.entropy_source,
+				&*self.router,
+			) {
+				Some((msg, ctx)) => (msg, ctx),
+				None => return None,
+			};
+			let response_instructions = responder.respond_with_reply_path(reply_context);
+			return Some((serve_static_invoice, response_instructions));
+		}
+
+		#[cfg(not(async_payments))]
+		return None;
 	}
 
 	fn handle_serve_static_invoice(

lightning/src/ln/inbound_payment.rs

@@ -214,7 +214,7 @@ pub fn create_from_hash(
 }
 
 #[cfg(async_payments)]
-pub(super) fn create_for_spontaneous_payment(
+pub(crate) fn create_for_spontaneous_payment(
 	keys: &ExpandedKey, min_value_msat: Option<u64>, invoice_expiry_delta_secs: u32,
 	current_time: u64, min_final_cltv_expiry_delta: Option<u16>,
 ) -> Result<PaymentSecret, ()> {

lightning/src/offers/async_receive_offer_cache.rs

@@ -17,6 +17,8 @@ use crate::io::Read;
 use crate::ln::msgs::DecodeError;
 use crate::offers::nonce::Nonce;
 use crate::offers::offer::Offer;
+#[cfg(async_payments)]
+use crate::onion_message::async_payments::OfferPaths;
 use crate::onion_message::messenger::Responder;
 use crate::prelude::*;
 use crate::util::ser::{Readable, Writeable, Writer};
@@ -158,6 +160,9 @@ const MAX_UPDATE_ATTEMPTS: u8 = 3;
 #[cfg(async_payments)]
 const OFFER_REFRESH_THRESHOLD: Duration = Duration::from_secs(2 * 60 * 60);
 
+#[cfg(async_payments)]
+const MIN_OFFER_PATHS_RELATIVE_EXPIRY_SECS: u64 = 3 * 60 * 60;
+
 #[cfg(async_payments)]
 impl AsyncReceiveOfferCache {
 	/// Remove expired offers from the cache, returning whether new offers are needed.
@@ -183,6 +188,27 @@ impl AsyncReceiveOfferCache {
 			&& self.offer_paths_request_attempts < MAX_UPDATE_ATTEMPTS
 	}
 
+	/// Returns whether the new paths we've just received from the static invoice server should be used
+	/// to build a new offer.
+	pub(super) fn should_build_offer_with_paths(
+		&self, message: &OfferPaths, duration_since_epoch: Duration,
+	) -> bool {
+		if !self.needs_new_offers(duration_since_epoch) {
+			return false;
+		}
+
+		// Require the offer that would be built using these paths to last at least a few hours.
+		let min_offer_paths_absolute_expiry =
+			duration_since_epoch.as_secs().saturating_add(MIN_OFFER_PATHS_RELATIVE_EXPIRY_SECS);
+		let offer_paths_absolute_expiry = message.paths_absolute_expiry.unwrap_or(u64::MAX);
+		if offer_paths_absolute_expiry < min_offer_paths_absolute_expiry {
+			return false;
+		}
+
+		// Check that we don't have any current offers that already contain these paths
+		self.offers.iter().all(|offer| offer.offer.paths() != message.paths)
+	}
+
 	/// Returns a bool indicating whether new offers are needed in the cache.
 	fn needs_new_offers(&self, duration_since_epoch: Duration) -> bool {
 		// We always want to have the freshest offer possible when a user goes to retrieve a cached

lightning/src/offers/flow.rs

@@ -65,8 +65,14 @@ use {
 	crate::blinded_path::payment::AsyncBolt12OfferContext,
 	crate::offers::offer::Amount,
 	crate::offers::signer,
-	crate::offers::static_invoice::{StaticInvoice, StaticInvoiceBuilder},
-	crate::onion_message::async_payments::{HeldHtlcAvailable, OfferPathsRequest},
+	crate::offers::static_invoice::{
+		StaticInvoice, StaticInvoiceBuilder,
+		DEFAULT_RELATIVE_EXPIRY as STATIC_INVOICE_DEFAULT_RELATIVE_EXPIRY,
+	},
+	crate::onion_message::async_payments::{
+		HeldHtlcAvailable, OfferPaths, OfferPathsRequest, ServeStaticInvoice,
+	},
+	crate::onion_message::messenger::Responder,
 };
 
 #[cfg(feature = "dnssec")]
@@ -1184,6 +1190,163 @@ where
 		Ok(())
 	}
 
+	/// 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.
+	///
+	/// Returns `None` if we have enough offers cached already, verification of `message` fails, or we
+	/// fail to create blinded paths.
+	#[cfg(async_payments)]
+	pub(crate) fn handle_offer_paths<ES: Deref, R: Deref>(
+		&self, message: OfferPaths, context: AsyncPaymentsContext, responder: Responder,
+		peers: Vec<MessageForwardNode>, usable_channels: Vec<ChannelDetails>, entropy: ES,
+		router: R,
+	) -> Option<(ServeStaticInvoice, MessageContext)>
+	where
+		ES::Target: EntropySource,
+		R::Target: Router,
+	{
+		let expanded_key = &self.inbound_payment_key;
+		let duration_since_epoch = self.duration_since_epoch();
+
+		match context {
+			AsyncPaymentsContext::OfferPaths { nonce, hmac, path_absolute_expiry } => {
+				if let Err(()) = signer::verify_offer_paths_context(nonce, hmac, expanded_key) {
+					return None;
+				}
+				if duration_since_epoch > path_absolute_expiry {
+					return None;
+				}
+			},
+			_ => return None,
+		}
+
+		{
+			// Only respond with `ServeStaticInvoice` if we actually need a new offer built.
+			let cache = self.async_receive_offer_cache.lock().unwrap();
+			if !cache.should_build_offer_with_paths(&message, duration_since_epoch) {
+				return None;
+			}
+		}
+
+		let (mut offer_builder, offer_nonce) =
+			match self.create_async_receive_offer_builder(&*entropy, message.paths) {
+				Ok((builder, nonce)) => (builder, nonce),
+				Err(_) => return None, // Only reachable if OfferPaths::paths is empty
+			};
+		if let Some(paths_absolute_expiry) = message.paths_absolute_expiry {
+			offer_builder =
+				offer_builder.absolute_expiry(Duration::from_secs(paths_absolute_expiry));
+		}
+		let offer = match offer_builder.build() {
+			Ok(offer) => offer,
+			Err(_) => {
+				debug_assert!(false);
+				return None;
+			},
+		};
+
+		let (serve_invoice_message, reply_path_context) = match self
+			.create_serve_static_invoice_message(
+				offer,
+				offer_nonce,
+				duration_since_epoch,
+				peers,
+				usable_channels,
+				responder,
+				&*entropy,
+				router,
+			) {
+			Ok((msg, context)) => (msg, context),
+			Err(()) => return None,
+		};
+
+		let context = MessageContext::AsyncPayments(reply_path_context);
+		Some((serve_invoice_message, context))
+	}
+
+	/// Creates a [`ServeStaticInvoice`] onion message, including reply path context for the static
+	/// invoice server to respond with [`StaticInvoicePersisted`].
+	///
+	/// [`StaticInvoicePersisted`]: crate::onion_message::async_payments::StaticInvoicePersisted
+	#[cfg(async_payments)]
+	fn create_serve_static_invoice_message<ES: Deref, R: Deref>(
+		&self, offer: Offer, offer_nonce: Nonce, offer_created_at: Duration,
+		peers: Vec<MessageForwardNode>, usable_channels: Vec<ChannelDetails>,
+		update_static_invoice_path: Responder, entropy: ES, router: R,
+	) -> Result<(ServeStaticInvoice, AsyncPaymentsContext), ()>
+	where
+		ES::Target: EntropySource,
+		R::Target: Router,
+	{
+		let expanded_key = &self.inbound_payment_key;
+		let duration_since_epoch = self.duration_since_epoch();
+		let secp_ctx = &self.secp_ctx;
+
+		let offer_relative_expiry = offer
+			.absolute_expiry()
+			.map(|exp| exp.saturating_sub(duration_since_epoch))
+			.unwrap_or_else(|| Duration::from_secs(u64::MAX));
+
+		// We limit the static invoice lifetime to STATIC_INVOICE_DEFAULT_RELATIVE_EXPIRY, meaning we'll
+		// need to refresh the static invoice using the reply path to the `OfferPaths` message if the
+		// offer expires later than that.
+		let static_invoice_relative_expiry = core::cmp::min(
+			offer_relative_expiry.as_secs(),
+			STATIC_INVOICE_DEFAULT_RELATIVE_EXPIRY.as_secs(),
+		) as u32;
+
+		let payment_secret = inbound_payment::create_for_spontaneous_payment(
+			expanded_key,
+			None, // The async receive offers we create are always amount-less
+			static_invoice_relative_expiry,
+			self.duration_since_epoch().as_secs(),
+			None,
+		)?;
+
+		let invoice = self
+			.create_static_invoice_builder(
+				&router,
+				&*entropy,
+				&offer,
+				offer_nonce,
+				payment_secret,
+				static_invoice_relative_expiry,
+				usable_channels,
+				peers.clone(),
+			)
+			.and_then(|builder| builder.build_and_sign(secp_ctx))
+			.map_err(|_| ())?;
+
+		let nonce = Nonce::from_entropy_source(&*entropy);
+		let context = MessageContext::Offers(OffersContext::InvoiceRequest { nonce });
+		let forward_invoice_request_path = self
+			.create_blinded_paths(peers, context)
+			.and_then(|paths| paths.into_iter().next().ok_or(()))?;
+
+		let reply_path_context = {
+			let nonce = Nonce::from_entropy_source(entropy);
+			let hmac = signer::hmac_for_static_invoice_persisted_context(nonce, expanded_key);
+			let static_invoice_absolute_expiry =
+				invoice.created_at().saturating_add(invoice.relative_expiry());
+			let path_absolute_expiry =
+				duration_since_epoch.saturating_add(TEMP_REPLY_PATH_RELATIVE_EXPIRY);
+			AsyncPaymentsContext::StaticInvoicePersisted {
+				offer,
+				offer_nonce,
+				offer_created_at,
+				update_static_invoice_path,
+				static_invoice_absolute_expiry,
+				nonce,
+				hmac,
+				path_absolute_expiry,
+			}
+		};
+
+		let msg = ServeStaticInvoice { invoice, forward_invoice_request_path, replace_offer: None };
+		Ok((msg, reply_path_context))
+	}
+
 	/// Get the `AsyncReceiveOfferCache` for persistence.
 	pub(crate) fn writeable_async_receive_offer_cache(&self) -> impl Writeable + '_ {
 		&self.async_receive_offer_cache

lightning/src/offers/signer.rs

@@ -55,6 +55,11 @@ const PAYMENT_TLVS_HMAC_INPUT: &[u8; 16] = &[8; 16];
 #[cfg(async_payments)]
 const ASYNC_PAYMENTS_HELD_HTLC_HMAC_INPUT: &[u8; 16] = &[9; 16];
 
+// HMAC input used in `AsyncPaymentsContext::StaticInvoicePersisted` to authenticate inbound
+// static_invoice_persisted onion messages.
+#[cfg(async_payments)]
+const ASYNC_PAYMENTS_STATIC_INV_PERSISTED_INPUT: &[u8; 16] = &[11; 16];
+
 /// Message metadata which possibly is derived from [`MetadataMaterial`] such that it can be
 /// verified.
 #[derive(Clone)]
@@ -570,3 +575,27 @@ pub(crate) fn verify_held_htlc_available_context(
 		Err(())
 	}
 }
+
+#[cfg(async_payments)]
+pub(crate) fn verify_offer_paths_context(
+	nonce: Nonce, hmac: Hmac<Sha256>, expanded_key: &ExpandedKey,
+) -> Result<(), ()> {
+	if hmac_for_offer_paths_context(nonce, expanded_key) == hmac {
+		Ok(())
+	} else {
+		Err(())
+	}
+}
+
+#[cfg(async_payments)]
+pub(crate) fn hmac_for_static_invoice_persisted_context(
+	nonce: Nonce, expanded_key: &ExpandedKey,
+) -> Hmac<Sha256> {
+	const IV_BYTES: &[u8; IV_LEN] = b"LDK InvPersisted";
+	let mut hmac = expanded_key.hmac_for_offer();
+	hmac.input(IV_BYTES);
+	hmac.input(&nonce.0);
+	hmac.input(ASYNC_PAYMENTS_STATIC_INV_PERSISTED_INPUT);
+
+	Hmac::from_engine(hmac)
+}