refactor(offers): extract payer key derivation helpers

Move the invoice/refund payer key derivation logic into reusable helpers so
payer proofs can derive the same signing keys without duplicating the metadata
and signer flow.

Author: vincenzopalazzo

lightning/src/offers/invoice.rs

@@ -131,7 +131,8 @@ use crate::offers::invoice_request::{
 	IV_BYTES as INVOICE_REQUEST_IV_BYTES,
 };
 use crate::offers::merkle::{
-	self, SignError, SignFn, SignatureTlvStream, SignatureTlvStreamRef, TaggedHash, TlvStream,
+	self, SignError, SignFn, SignatureTlvStream, SignatureTlvStreamRef, TaggedHash, TlvRecord,
+	TlvStream,
 };
 use crate::offers::nonce::Nonce;
 use crate::offers::offer::{
@@ -1032,6 +1033,34 @@ impl Bolt12Invoice {
 		)
 	}
 
+	/// Re-derives the payer's signing keypair for payer proof creation.
+	///
+	/// This performs the same key derivation that occurs during invoice request creation
+	/// with `deriving_signing_pubkey`, allowing the payer to recover their signing keypair.
+	///
+	/// The `nonce` and `payment_id` must be the same ones used when creating the original
+	/// invoice request. In the common proof-of-payment flow, callers can instead use
+	/// `PaidBolt12Invoice::prove_payer_derived` together with the `payment_id` from
+	/// [`Event::PaymentSent`].
+	///
+	/// [`Event::PaymentSent`]: crate::events::Event::PaymentSent
+	pub fn derive_payer_signing_keys<T: secp256k1::Signing>(
+		&self, payment_id: PaymentId, nonce: Nonce, key: &ExpandedKey, secp_ctx: &Secp256k1<T>,
+	) -> Result<Keypair, ()> {
+		let iv_bytes = match &self.contents {
+			InvoiceContents::ForOffer { .. } => INVOICE_REQUEST_IV_BYTES,
+			InvoiceContents::ForRefund { .. } => REFUND_IV_BYTES_WITHOUT_METADATA,
+		};
+		self.contents.derive_payer_signing_keys(
+			&self.bytes,
+			payment_id,
+			nonce,
+			key,
+			iv_bytes,
+			secp_ctx,
+		)
+	}
+
 	pub(crate) fn as_tlv_stream(&self) -> FullInvoiceTlvStreamRef<'_> {
 		let (
 			payer_tlv_stream,
@@ -1317,20 +1346,8 @@ impl InvoiceContents {
 		&self, bytes: &[u8], metadata: &Metadata, key: &ExpandedKey, iv_bytes: &[u8; IV_LEN],
 		secp_ctx: &Secp256k1<T>,
 	) -> Result<PaymentId, ()> {
-		const EXPERIMENTAL_TYPES: core::ops::Range<u64> =
-			EXPERIMENTAL_OFFER_TYPES.start..EXPERIMENTAL_INVOICE_REQUEST_TYPES.end;
-
-		let offer_records = TlvStream::new(bytes).range(OFFER_TYPES);
-		let invreq_records = TlvStream::new(bytes).range(INVOICE_REQUEST_TYPES).filter(|record| {
-			match record.r#type {
-				PAYER_METADATA_TYPE => false, // Should be outside range
-				INVOICE_REQUEST_PAYER_ID_TYPE => !metadata.derives_payer_keys(),
-				_ => true,
-			}
-		});
-		let experimental_records = TlvStream::new(bytes).range(EXPERIMENTAL_TYPES);
-		let tlv_stream = offer_records.chain(invreq_records).chain(experimental_records);
-
+		let exclude_payer_id = metadata.derives_payer_keys();
+		let tlv_stream = Self::payer_tlv_stream(bytes, exclude_payer_id);
 		let signing_pubkey = self.payer_signing_pubkey();
 		signer::verify_payer_metadata(
 			metadata.as_ref(),
@@ -1342,6 +1359,46 @@ impl InvoiceContents {
 		)
 	}
 
+	fn derive_payer_signing_keys<T: secp256k1::Signing>(
+		&self, bytes: &[u8], payment_id: PaymentId, nonce: Nonce, key: &ExpandedKey,
+		iv_bytes: &[u8; IV_LEN], secp_ctx: &Secp256k1<T>,
+	) -> Result<Keypair, ()> {
+		let tlv_stream = Self::payer_tlv_stream(bytes, true);
+		let signing_pubkey = self.payer_signing_pubkey();
+		signer::derive_payer_keys(
+			payment_id,
+			nonce,
+			key,
+			iv_bytes,
+			signing_pubkey,
+			tlv_stream,
+			secp_ctx,
+		)
+	}
+
+	/// Builds the TLV stream used for payer metadata verification and key derivation.
+	///
+	/// When `exclude_payer_id` is true, the payer signing pubkey (type 88) is excluded
+	/// from the stream, which is needed when deriving payer keys.
+	fn payer_tlv_stream(
+		bytes: &[u8], exclude_payer_id: bool,
+	) -> impl core::iter::Iterator<Item = TlvRecord<'_>> {
+		const EXPERIMENTAL_TYPES: core::ops::Range<u64> =
+			EXPERIMENTAL_OFFER_TYPES.start..EXPERIMENTAL_INVOICE_REQUEST_TYPES.end;
+
+		let offer_records = TlvStream::new(bytes).range(OFFER_TYPES);
+		let invreq_records =
+			TlvStream::new(bytes).range(INVOICE_REQUEST_TYPES).filter(move |record| {
+				match record.r#type {
+					PAYER_METADATA_TYPE => false,
+					INVOICE_REQUEST_PAYER_ID_TYPE => !exclude_payer_id,
+					_ => true,
+				}
+			});
+		let experimental_records = TlvStream::new(bytes).range(EXPERIMENTAL_TYPES);
+		offer_records.chain(invreq_records).chain(experimental_records)
+	}
+
 	fn as_tlv_stream(&self) -> PartialInvoiceTlvStreamRef<'_> {
 		let (payer, offer, invoice_request, experimental_offer, experimental_invoice_request) =
 			match self {

lightning/src/offers/signer.rs

@@ -321,6 +321,34 @@ pub(super) fn derive_keys(nonce: Nonce, expanded_key: &ExpandedKey) -> Keypair {
 	Keypair::from_secret_key(&secp_ctx, &privkey)
 }
 
+/// Re-derives the payer signing keypair from the given components.
+///
+/// Performs the same derivation as keys created by [`Metadata::derive_from`] when using
+/// [`Metadata::DerivedSigningPubkey`] with a [`MetadataMaterial`] built from a `payment_id`.
+///
+/// The `tlv_stream` must contain the records matching what was used during the original
+/// key derivation.
+pub(super) fn derive_payer_keys<'a, T: secp256k1::Signing>(
+	payment_id: PaymentId, nonce: Nonce, expanded_key: &ExpandedKey, iv_bytes: &[u8; IV_LEN],
+	signing_pubkey: PublicKey, tlv_stream: impl core::iter::Iterator<Item = TlvRecord<'a>>,
+	secp_ctx: &Secp256k1<T>,
+) -> Result<Keypair, ()> {
+	let metadata = Metadata::payer_data(payment_id, nonce, expanded_key);
+	let metadata_ref = metadata.as_ref();
+
+	match verify_payer_metadata_inner(
+		metadata_ref,
+		expanded_key,
+		iv_bytes,
+		signing_pubkey,
+		tlv_stream,
+		secp_ctx,
+	)? {
+		Some(keys) => Ok(keys),
+		None => Err(()),
+	}
+}
+
 /// Verifies data given in a TLV stream was used to produce the given metadata, consisting of:
 /// - a 256-bit [`PaymentId`],
 /// - a 128-bit [`Nonce`], and possibly
@@ -339,6 +367,34 @@ pub(super) fn verify_payer_metadata<'a, T: secp256k1::Signing>(
 		return Err(());
 	}
 
+	verify_payer_metadata_inner(
+		metadata,
+		expanded_key,
+		iv_bytes,
+		signing_pubkey,
+		tlv_stream,
+		secp_ctx,
+	)?;
+
+	let mut encrypted_payment_id = [0u8; PaymentId::LENGTH];
+	encrypted_payment_id.copy_from_slice(&metadata[..PaymentId::LENGTH]);
+	let nonce = Nonce::try_from(&metadata[PaymentId::LENGTH..][..Nonce::LENGTH]).unwrap();
+	let payment_id = expanded_key.crypt_for_offer(encrypted_payment_id, nonce);
+
+	Ok(PaymentId(payment_id))
+}
+
+/// Shared core of [`verify_payer_metadata`] and [`derive_payer_keys`].
+///
+/// Builds the payer HMAC from the given metadata and TLV stream, then verifies it against the
+/// `signing_pubkey`. The `metadata` must be at least `PaymentId::LENGTH` bytes, with the first
+/// `PaymentId::LENGTH` bytes being the encrypted payment ID and the remainder being the nonce
+/// (and possibly an HMAC).
+fn verify_payer_metadata_inner<'a, T: secp256k1::Signing>(
+	metadata: &[u8], expanded_key: &ExpandedKey, iv_bytes: &[u8; IV_LEN],
+	signing_pubkey: PublicKey, tlv_stream: impl core::iter::Iterator<Item = TlvRecord<'a>>,
+	secp_ctx: &Secp256k1<T>,
+) -> Result<Option<Keypair>, ()> {
 	let mut encrypted_payment_id = [0u8; PaymentId::LENGTH];
 	encrypted_payment_id.copy_from_slice(&metadata[..PaymentId::LENGTH]);
 
@@ -352,12 +408,7 @@ pub(super) fn verify_payer_metadata<'a, T: secp256k1::Signing>(
 		Hmac::from_engine(hmac),
 		signing_pubkey,
 		secp_ctx,
-	)?;
-
-	let nonce = Nonce::try_from(&metadata[PaymentId::LENGTH..][..Nonce::LENGTH]).unwrap();
-	let payment_id = expanded_key.crypt_for_offer(encrypted_payment_id, nonce);
-
-	Ok(PaymentId(payment_id))
+	)
 }
 
 /// Verifies data given in a TLV stream was used to produce the given metadata, consisting of: