Commit to payment_metadata in inbound payment HMAC

[TheBlueMatt]

When payment_metadata is set in a BOLT 11 invoice, users expect to
receive it back as-is in the payment onion. In order to ensure it
isn't tampered with, they presumably will add an HMAC, or worse, not
add one and forget that it can be tampered with.

Instead, here we include it in the HMAC computation for the payment
secret. This ensures that the sender must relay the correct
metadata for the payment to be accepted by the receiver, binding
the metadata to the payment cryptographically.

The metadata is only included in the HMAC when present, so existing
payments without metadata continue to verify correctly. However,
this does break receiving payments with metadata today. On an
upgrade this seems acceptable to me given we have seen almost no
use of payment metadata in practice.

[ldk-reviews-bot]

I've assigned @valentinewallace as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

[ldk-claude-review-bot]

Typo: "comitted" → "committed"

Suggested change

	* Payment metadata is now comitted to in the HMAC used to build payment secrets.
	* Payment metadata is now committed to in the HMAC used to build payment secrets.

[ldk-claude-review-bot]

Design consideration: None and Some(&[]) are cryptographically indistinguishable here (and at every other HMAC site in this PR) since hmac.input(&[]) is a no-op. This means:

• A payment created with payment_metadata = None will verify successfully if the sender sends payment_metadata = Some(vec![]) in the onion (and vice versa).

In practice this seems harmless since empty metadata carries no information, but if you want to formally distinguish "no metadata" from "empty metadata", you could prefix the HMAC input with a flag byte (e.g., hmac.input(&[1u8]) when metadata is Some, hmac.input(&[0u8]) when None).

[ldk-claude-review-bot]

The doc comment for this public API method doesn't mention the new payment_metadata parameter. Callers need to know that if a payment was created with payment_metadata via create_inbound_payment, the same metadata must be provided here for preimage derivation to succeed. Without this documentation, a caller may pass None and get a confusing APIMisuseError.

[ldk-claude-review-bot]

The doc comment for create_inbound_payment doesn't document the new payment_metadata parameter. Worth adding a note explaining that when provided, the metadata is committed to in the payment secret HMAC, so the sender must relay it exactly for payment verification to succeed.

[ldk-claude-review-bot]

Review Summary

Inline comments posted:

1. pending_changelog/matt-commit-to-metadata.txt:2 — Typo: "comitted" → "committed"

2. lightning/src/ln/inbound_payment.rs:174-176 — None vs Some(&[]) metadata are cryptographically indistinguishable since hmac.input(&[]) is a no-op. This applies to all HMAC sites (create, create_from_hash, verify, derive_ldk_payment_preimage). Not a security issue in practice, but a design consideration.

3. lightning/src/ln/channelmanager.rs:14983-14985 — get_payment_preimage public API lacks documentation for the new payment_metadata parameter. Callers who created payments with metadata must pass the same metadata here or get an opaque error.

4. lightning/src/ln/channelmanager.rs:14904 — create_inbound_payment public API lacks documentation for the new payment_metadata parameter.

Cross-cutting observations:

• The core cryptographic change is correct: metadata is consistently included in HMAC computation during creation (create, create_from_hash) and verification (verify, derive_ldk_payment_preimage, get_payment_preimage).

• create_inbound_payment_for_hash (line 14963-14966) similarly lacks docs for its new payment_metadata parameter.

• The _create_phantom_invoice function (invoice_utils.rs:194, 207) hardcodes None for payment_metadata. This is fine for now but means phantom invoices cannot use the metadata commitment feature.

• All test changes correctly thread the new parameter. The get_payment_hash! macro in max_payment_path_len_tests.rs properly generates committed payment secrets for each metadata variant.