Add initial warnings against OHTTP request reuse (payjoin#828)

# Document OHTTP Request Non-Reusability

This PR addresses payjoin#819 by documenting that OHTTP-encapsulated requests
must not be reused or retried, due to the risk of retransmitting
ciphertext and violating OHTTP's privacy guarantees.

### What's Included:
A top-level warning was added to the receive module docs (//!) to
highlight the security implications of request reuse.

Closes payjoin#819

Author: nothingmuch

payjoin-ffi/src/send/mod.rs

@@ -214,6 +214,10 @@ impl WithReplyKey {
     }
 
     /// Extract serialized Request and Context from a Payjoin Proposal.
+    ///
+    /// Important: This request must not be retried or reused on failure.
+    /// Retransmitting the same ciphertext breaks OHTTP privacy properties.
+    /// The specific concern is that the relay can see that a request is being retried.
     pub fn extract_v2(
         &self,
         ohttp_relay: String,

payjoin-ffi/src/send/uni.rs

@@ -229,6 +229,11 @@ impl WithReplyKey {
 
     /// Extract serialized Request and Context from a Payjoin Proposal.
     ///
+    /// Important: This request must not be retried or reused on failure.
+    /// Retransmitting the same ciphertext breaks OHTTP privacy properties.
+    /// The specific concern is that the relay can see that a request is being retried,
+    /// which leaks that it's all the same request.
+    ///
     /// This method requires the `rs` pubkey to be extracted from the endpoint
     /// and has no fallback to v1.
     pub fn extract_v2(

payjoin/src/core/receive/v1/mod.rs

@@ -23,6 +23,13 @@
 //! 21](https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki) request URI.
 //!
 //! [reference implementation](https://github.com/payjoin/rust-payjoin/tree/master/payjoin-cli)
+//!
+//! OHTTP Privacy Warning
+//! Encapsulated requests whether GET or POST—**must not be retried or reused**.
+//! Retransmitting the same ciphertext (including via automatic retries) breaks the unlinkability and privacy guarantees of OHTTP,
+//! as it allows the relay to correlate requests by comparing ciphertexts.
+//! Note: Even fresh requests may be linkable via metadata (e.g. client IP, request timing),
+//! but request reuse makes correlation trivial for the relay.
 
 use std::cmp::{max, min};
 use std::collections::BTreeMap;

payjoin/src/core/receive/v2/mod.rs

@@ -1,4 +1,11 @@
 //! Receive BIP 77 Payjoin v2
+//!
+//! OHTTP Privacy Warning
+//! Encapsulated requests whether GET or POST—**must not be retried or reused**.
+//! Retransmitting the same ciphertext (including via automatic retries) breaks the unlinkability and privacy guarantees of OHTTP,
+//! as it allows the relay to correlate requests by comparing ciphertexts.
+//! Note: Even fresh requests may be linkable via metadata (e.g. client IP, request timing),
+//! but request reuse makes correlation trivial for the relay.
 use std::str::FromStr;
 use std::time::{Duration, SystemTime};
 

payjoin/src/core/send/mod.rs

@@ -8,6 +8,13 @@
 //!
 //! If you specifically need to use
 //! version 1, refer to the `send::v1` module documentation after enabling the `v1` feature.
+//!
+//! OHTTP Privacy Warning
+//! Encapsulated requests whether GET or POST—**must not be retried or reused**.
+//! Retransmitting the same ciphertext (including via automatic retries) breaks the unlinkability and privacy guarantees of OHTTP,
+//! as it allows the relay to correlate requests by comparing ciphertexts.
+//! Note: Even fresh requests may be linkable via metadata (e.g. client IP, request timing),
+//! but request reuse makes correlation trivial for the relay.
 
 use std::str::FromStr;
 

payjoin/src/core/send/multiparty/mod.rs

@@ -38,6 +38,10 @@ impl<'a> SenderBuilder<'a> {
 pub struct Sender(v2::Sender<v2::WithReplyKey>);
 
 impl Sender {
+    /// Important: This request must not be retried or reused on failure.
+    /// Retransmitting the same ciphertext breaks OHTTP privacy properties.
+    /// The specific concern is that the relay can see that a request is being retried,
+    /// which leaks that it's all the same request.
     pub fn extract_v2(
         &self,
         ohttp_relay: impl IntoUrl,

payjoin/src/core/send/v2/mod.rs

@@ -20,6 +20,13 @@
 //! [`nolooking`](https://github.com/chaincase-app/nolooking) for LND, or
 //! [`bitmask-core`](https://github.com/diba-io/bitmask-core) BDK integration. Bring your own
 //! wallet and http client.
+//!
+//! OHTTP Privacy Warning
+//! Encapsulated requests whether GET or POST—**must not be retried or reused**.
+//! Retransmitting the same ciphertext (including via automatic retries) breaks the unlinkability and privacy guarantees of OHTTP,
+//! as it allows the relay to correlate requests by comparing ciphertexts.
+//! Note: Even fresh requests may be linkable via metadata (e.g. client IP, request timing),
+//! but request reuse makes correlation trivial for the relay.
 
 use bitcoin::hashes::{sha256, Hash};
 pub use error::{CreateRequestError, EncapsulationError};
@@ -206,11 +213,16 @@ pub struct WithReplyKey {
 impl State for WithReplyKey {}
 
 impl Sender<WithReplyKey> {
-    /// Extract serialized V1 Request and Context from a Payjoin Proposal
+    /// Extract serialized V1 Request and Context from a Payjoin Proposal.
     pub fn extract_v1(&self) -> (Request, v1::V1Context) { self.v1.extract_v1() }
 
     /// Extract serialized Request and Context from a Payjoin Proposal.
     ///
+    /// Important: This request must not be retried or reused on failure.
+    /// Retransmitting the same ciphertext breaks OHTTP privacy properties.
+    /// The specific concern is that the relay can see that a request is being retried,
+    /// which leaks that it's all the same request.
+    ///
     /// This method requires the `rs` pubkey to be extracted from the endpoint
     /// and has no fallback to v1.
     pub fn extract_v2(