Refund metadata and payer id derivation

Add support for deriving a transient payer id for each Refund from an
ExpandedKey and a nonce. This facilitates payer privacy by not tying any
Refund to any other nor to the payer's node id.

Additionally, support stateless Invoice verification by setting payer
metadata using an HMAC over the nonce and the remaining TLV records,
which will be later verified when receiving an Invoice response.

Author: jkczyz

lightning/src/offers/refund.rs

@@ -80,12 +80,14 @@ use core::time::Duration;
 use crate::io;
 use crate::ln::PaymentHash;
 use crate::ln::features::InvoiceRequestFeatures;
+use crate::ln::inbound_payment::{ExpandedKey, Nonce};
 use crate::ln::msgs::{DecodeError, MAX_VALUE_MSAT};
 use crate::offers::invoice::{BlindedPayInfo, InvoiceBuilder};
 use crate::offers::invoice_request::{InvoiceRequestTlvStream, InvoiceRequestTlvStreamRef};
 use crate::offers::offer::{OfferTlvStream, OfferTlvStreamRef};
 use crate::offers::parse::{Bech32Encode, ParseError, ParsedMessage, SemanticError};
 use crate::offers::payer::{PayerContents, PayerTlvStream, PayerTlvStreamRef};
+use crate::offers::signer::{MetadataMaterial, DerivedPubkey};
 use crate::onion_message::BlindedPath;
 use crate::util::ser::{SeekReadable, WithoutLength, Writeable, Writer};
 use crate::util::string::PrintableString;
@@ -102,6 +104,7 @@ use std::time::SystemTime;
 /// [module-level documentation]: self
 pub struct RefundBuilder {
 	refund: RefundContents,
+	metadata_material: Option<MetadataMaterial>,
 }
 
 impl RefundBuilder {
@@ -123,7 +126,53 @@ impl RefundBuilder {
 			quantity: None, payer_id, payer_note: None,
 		};
 
-		Ok(RefundBuilder { refund })
+		Ok(RefundBuilder { refund, metadata_material: None })
+	}
+
+	/// Similar to [`RefundBuilder::new`] except it:
+	/// - derives the payer id such that a different key can be used for each refund, and
+	/// - sets the metadata when [`RefundBuilder::build`] is called such that it can be used by
+	///   [`Invoice::verify`] to determine if the refund was produced using a base [`ExpandedKey`]
+	///   from which the payer id was derived.
+	///
+	/// [`Invoice::verify`]: crate::offers::invoice::Invoice::verify
+	/// [`ExpandedKey`]: crate::ln::inbound_payment::ExpandedKey
+	#[allow(unused)]
+	pub(crate) fn deriving_payer_id(
+		description: String, payer_id: DerivedPubkey, amount_msats: u64
+	) -> Result<Self, SemanticError> {
+		if amount_msats > MAX_VALUE_MSAT {
+			return Err(SemanticError::InvalidAmount);
+		}
+
+		let (payer_id, metadata_material) = payer_id.into_parts();
+		let refund = RefundContents {
+			payer: PayerContents(vec![]), description, absolute_expiry: None, issuer: None,
+			paths: None, chain: None, amount_msats, features: InvoiceRequestFeatures::empty(),
+			quantity: None, payer_id, payer_note: None,
+		};
+
+		Ok(RefundBuilder { refund, metadata_material: Some(metadata_material) })
+	}
+
+	/// Sets the [`Refund::metadata`] derived from the given `key` and any fields set prior to
+	/// calling [`Refund::build`]. Allows for stateless verification of an [`Invoice`] when using a
+	/// public node id as the [`Refund::payer_id`] instead of a derived one.
+	///
+	/// Errors if already called or if the builder was constructed with [`Self::deriving_payer_id`].
+	///
+	/// [`Invoice`]: crate::offers::invoice::Invoice
+	#[allow(unused)]
+	pub(crate) fn metadata_derived(
+		mut self, key: &ExpandedKey, nonce: Nonce
+	) -> Result<Self, SemanticError> {
+		if self.metadata_material.is_some() {
+			return Err(SemanticError::UnexpectedMetadata);
+		}
+
+		self.refund.payer = PayerContents(vec![]);
+		self.metadata_material = Some(MetadataMaterial::new(nonce, key));
+		Ok(self)
 	}
 
 	/// Sets the [`Refund::absolute_expiry`] as seconds since the Unix epoch. Any expiry that has
@@ -190,6 +239,17 @@ impl RefundBuilder {
 			self.refund.chain = None;
 		}
 
+		// Create the metadata for stateless verification of an Invoice.
+		if let Some(mut metadata_material) = self.metadata_material {
+			debug_assert!(self.refund.payer.0.is_empty());
+			let mut tlv_stream = self.refund.as_tlv_stream();
+			tlv_stream.0.metadata = None;
+			tlv_stream.2.payer_id = None;
+			tlv_stream.write(&mut metadata_material).unwrap();
+
+			self.refund.payer.0 = metadata_material.into_metadata();
+		}
+
 		let mut bytes = Vec::new();
 		self.refund.write(&mut bytes).unwrap();