WIP

Author: martinsaposnic

lightning-liquidity/src/lsps5/client.rs

@@ -29,7 +29,9 @@ use super::service::TimeProvider;
 
 use alloc::collections::VecDeque;
 use alloc::string::String;
+
 use bitcoin::secp256k1::PublicKey;
+
 use lightning::ln::msgs::{ErrorAction, LightningError};
 use lightning::sign::EntropySource;
 use lightning::util::logger::Level;
@@ -129,33 +131,38 @@ impl PeerState {
 	}
 }
 
-/// LSPS5 client handler.
+/// Client‐side handler for the LSPS5 (bLIP-55) webhook registration protocol.
+///
+/// `LSPS5ClientHandler` is the primary interface for LSP clients
+/// to register, list, and remove webhook endpoints with an LSP, and to parse
+/// and validate incoming signed notifications.
+///
+/// # Core Capabilities
+///
+///  - `set_webhook(peer, app_name, url)` -> register or update a webhook (`lsps5.set_webhook`)
+///  - `list_webhooks(peer)` -> retrieve all registered webhooks (`lsps5.list_webhooks`)
+///  - `remove_webhook(peer, name)` -> delete a webhook (`lsps5.remove_webhook`)
+///  - `parse_webhook_notification(...)` -> verify signature, timestamp, replay, and emit event
+///
+/// [`bLIP-55 / LSPS5 specification`]: https://github.com/lightning/blips/pull/55/files
 pub struct LSPS5ClientHandler<ES: Deref>
 where
 	ES::Target: EntropySource,
 {
-	/// Pending messages to be sent.
 	pending_messages: Arc<MessageQueue>,
-	/// Event queue for emitting events.
 	pending_events: Arc<EventQueue>,
-	/// Entropy source.
 	entropy_source: ES,
-	/// Per peer state for tracking requests.
 	per_peer_state: RwLock<HashMap<PublicKey, Mutex<PeerState>>>,
-	/// Client configuration.
 	config: LSPS5ClientConfig,
-	/// Time provider for LSPS5 service.
 	time_provider: Arc<dyn TimeProvider>,
-	/// Map of recently used signatures to prevent replay attacks.
 	recent_signatures: Mutex<VecDeque<(String, LSPSDateTime)>>,
 }
 
 impl<ES: Deref> LSPS5ClientHandler<ES>
 where
 	ES::Target: EntropySource,
 {
-	/// Creates a new LSPS5 client handler with the provided entropy source, message queue,
-	/// event queue, and LSPS5ClientConfig.
+	/// Constructs an `LSPS5ClientHandler`.
 	#[cfg(feature = "time")]
 	pub(crate) fn new(
 		entropy_source: ES, pending_messages: Arc<MessageQueue>, pending_events: Arc<EventQueue>,
@@ -171,6 +178,8 @@ where
 		)
 	}
 
+	/// Constructs an `LSPS5ClientHandler` with a custom time provider.
+	/// Useful for non-std environments that don't have access to the system clock.
 	pub(crate) fn new_with_custom_time_provider(
 		entropy_source: ES, pending_messages: Arc<MessageQueue>, pending_events: Arc<EventQueue>,
 		config: LSPS5ClientConfig, time_provider: Arc<dyn TimeProvider>,
@@ -204,20 +213,27 @@ where
 		Ok(f(&mut *peer_state_lock))
 	}
 
-	/// Register a webhook with the LSP.
+	/// Register or update a webhook endpoint under a human-readable name.
 	///
-	/// Implements the `lsps5.set_webhook` method from bLIP-55.
+	/// Sends a `lsps5.set_webhook` JSON-RPC request to the given LSP peer.
 	///
 	/// # Parameters
-	/// * `app_name` - A human-readable UTF-8 string that gives a name to the webhook (max 64 bytes).
-	/// * `webhook` - The URL of the webhook that the LSP can use to push notifications (max 1024 chars).
+	/// - `counterparty_node_id`: The LSP node ID to contact.
+	/// - `app_name`: A UTF-8 name for this webhook.
+	/// - `webhook_url`: HTTPS URL for push notifications.
 	///
 	/// # Returns
-	/// * Success - the request ID that was used.
-	/// * Error - validation error or error sending the request.
+	/// A unique `LSPSRequestId` for correlating the asynchronous response.
 	///
-	/// Response will be provided asynchronously through the event queue as a
-	/// WebhookRegistered or WebhookRegistrationFailed event.
+	/// Response from the LSP peer will be provided asynchronously through
+	/// the event queue as a WebhookRegistered or WebhookRegistrationFailed event.
+	///
+	/// **Note**: Ensure the app name is valid and its length does not exceed [`MAX_APP_NAME_LENGTH`].
+	/// **Note**: Ensure the URL is valid and its length does not exceed [`MAX_WEBHOOK_URL_LENGTH`]
+	/// and that the URL points to a public host.
+	///
+	/// [`MAX_WEBHOOK_URL_LENGTH`]: super::msgs::MAX_WEBHOOK_URL_LENGTH
+	/// [`MAX_APP_NAME_LENGTH`]: super::msgs::MAX_APP_NAME_LENGTH
 	pub fn set_webhook(
 		&self, counterparty_node_id: PublicKey, app_name: String, webhook_url: String,
 	) -> Result<LSPSRequestId, LightningError> {
@@ -254,13 +270,16 @@ where
 		Ok(request_id)
 	}
 
-	/// List all registered webhooks.
+	/// List all webhook names currently registered with the LSP.
+	///
+	/// Sends a `lsps5.list_webhooks` JSON-RPC request to the peer.
 	///
-	/// Implements the `lsps5.list_webhooks` method from bLIP-55.
+	/// # Parameters
+	/// - `counterparty_node_id`: The LSP node ID to query.
 	///
 	/// # Returns
-	/// * Success - the request ID that was used.
-	/// * Error - error sending the request.
+	/// A unique `LSPSRequestId` for correlating the asynchronous response.
+	///
 	///
 	/// Response will be provided asynchronously through the event queue as a
 	/// WebhooksListed or WebhooksListFailed event.
@@ -282,16 +301,16 @@ where
 		Ok(request_id)
 	}
 
-	/// Remove a webhook by app_name.
+	/// Remove a previously registered webhook by its name.
 	///
-	/// Implements the `lsps5.remove_webhook` method from bLIP-55.
+	/// Sends a `lsps5.remove_webhook` JSON-RPC request to the peer.
 	///
 	/// # Parameters
-	/// * `app_name` - The name of the webhook to remove.
+	/// - `counterparty_node_id`: The LSP node ID to contact.
+	/// - `app_name`: The name of the webhook to remove.
 	///
 	/// # Returns
-	/// * Success - the request ID that was used.
-	/// * Error - error sending the request.
+	/// A unique `LSPSRequestId` for correlating the asynchronous response.
 	///
 	/// Response will be provided asynchronously through the event queue as a
 	/// WebhookRemoved or WebhookRemovalFailed event.
@@ -320,7 +339,6 @@ where
 		Ok(request_id)
 	}
 
-	/// Handle received messages from the LSP.
 	fn handle_message(
 		&self, message: LSPS5Message, counterparty_node_id: &PublicKey,
 	) -> Result<(), LightningError> {
@@ -462,20 +480,7 @@ where
 		}
 	}
 
-	/// Verify a webhook notification signature from an LSP.
-	///
-	/// This can be used by a notification delivery service to verify
-	/// the authenticity of notifications received from an LSP.
-	///
-	/// # Parameters
-	/// * `timestamp` - The ISO8601 timestamp from the notification.
-	/// * `signature` - The signature string from the notification.
-	/// * `notification` - The webhook notification object.
-	///
-	/// # Returns
-	/// * On success: `true` if the signature is valid.
-	/// * On error: LightningError with error description.
-	pub fn verify_notification_signature(
+	fn verify_notification_signature(
 		&self, counterparty_node_id: PublicKey, signature_timestamp: &LSPSDateTime,
 		signature: &str, notification: &WebhookNotification,
 	) -> Result<bool, LightningError> {
@@ -512,7 +517,6 @@ where
 		}
 	}
 
-	/// Check if a signature has been used before.
 	fn check_signature_exists(&self, signature: &str) -> Result<(), LightningError> {
 		let recent_signatures = self.recent_signatures.lock().unwrap();
 
@@ -528,7 +532,6 @@ where
 		Ok(())
 	}
 
-	/// Store a signature with timestamp for replay attack prevention.
 	fn store_signature(&self, signature: String) -> Result<(), LightningError> {
 		let now =
 			LSPSDateTime::new_from_duration_since_epoch(self.time_provider.duration_since_epoch());
@@ -552,20 +555,35 @@ where
 		Ok(())
 	}
 
-	/// Parse a webhook notification received from an LSP.
+	/// Parse and validate a webhook notification received from an LSP.
 	///
-	/// This can be used by a client implementation to handle webhook
-	/// notifications after they're delivered through a push notification
-	/// system.
+	/// Implements the bLIP-55 / LSPS5 webhook delivery rules:
+	/// 1. Parses `notification_json` into a `WebhookNotification` (JSON-RPC 2.0).
+	/// 2. Checks that `timestamp` (from `x-lsps5-timestamp`) is within ±10 minutes of local time.
+	/// 3. Ensures `signature` (from `x-lsps5-signature`) has not been replayed within the
+	///    configured retention window.
+	/// 4. Reconstructs the exact string
+	///    `"LSPS5: DO NOT SIGN THIS MESSAGE MANUALLY: LSP: At {timestamp} I notify {body}"`
+	///    and verifies the zbase32 LN-style signature against the LSP’s node ID.
 	///
 	/// # Parameters
-	/// * `timestamp` - The ISO8601 timestamp from the notification.
-	/// * `signature` - The signature from the notification.
-	/// * `notification_json` - The JSON string of the notification object.
+	/// - `counterparty_node_id`: the LSP’s public key, used to verify the signature.
+	/// - `timestamp`: ISO8601 time when the LSP created the notification.
+	/// - `signature`: the zbase32-encoded LN signature over timestamp+body.
+	/// - `notification_json`: the JSON string of the JSON-RPC notification object.
 	///
-	/// # Returns
-	/// * On success: The parsed webhook notification.
-	/// * On error: LightningError with error description.
+	/// On success, emits `LSPS5ClientEvent::WebhookNotificationReceived`
+	/// and returns the parsed `WebhookNotification`.
+	///
+	/// Failure reasons include:
+	/// - Timestamp too old (drift > 10 minutes)
+	/// - Replay attack detected (signature reused)
+	/// - Invalid signature (crypto check fails)
+	/// - JSON parse errors for malformed `notification_json`
+	///
+	/// Clients should call this method upon receiving a SendWebhookNotifications
+	/// event, before taking action on the notification. This guarantees that only authentic,
+	/// non-replayed notifications reach your application.
 	pub fn parse_webhook_notification(
 		&self, counterparty_node_id: PublicKey, timestamp: &LSPSDateTime, signature: &str,
 		notification_json: &str,