feat(api): Get Signed Tree Head consistency proof

src/api/endpoints.rs

@@ -78,3 +78,25 @@ pub const ADD_PRE_CHAIN: Endpoint = (reqwest::Method::POST, "/ct/v1/add-pre-chai
 ///    tree_head_signature:  A TreeHeadSignature for the above data.
 /// ```
 pub const GET_STH: Endpoint = (reqwest::Method::GET, "/ct/v1/get-sth");
+
+/// Reference: https://datatracker.ietf.org/doc/html/rfc6962#section-4.4
+/// ```txt
+/// GET https://<log server>/ct/v1/get-sth-consistency
+///
+/// Inputs:
+///
+///    first:  The tree_size of the first tree, in decimal.
+///
+///    second:  The tree_size of the second tree, in decimal.
+///
+/// Both tree sizes must be from existing v1 STHs (Signed Tree Heads).
+///
+/// Outputs:
+///
+///    consistency:  An array of Merkle Tree nodes, base64 encoded.
+///
+/// Note that no signature is required on this data, as it is used to
+/// verify an STH, which is signed.
+/// ```
+pub const GET_STH_CONSISTENCY: Endpoint =
+	(reqwest::Method::GET, "/ct/v1/get-sth-consistency");

src/api/mod.rs

@@ -1,5 +1,10 @@
 use reqwest::Url;
-use responses::{AddChainRequest, AddChainResponse, GetSthResponse};
+use responses::{
+	AddChainRequest,
+	AddChainResponse,
+	GetSthConsistencyResponse,
+	GetSthResponse
+};
 
 pub mod endpoints;
 pub mod responses;
@@ -98,4 +103,34 @@ impl CtApiClient {
 			.json()
 			.await
 	}
+
+	/// Fetches the Signed Tree Head consistency proof for a specified start
+	/// tree_size and end tree_size.
+	///
+	/// See: [`endpoints::GET_STH_CONSISTENCY`]
+	///
+	/// ## Errors
+	///
+	/// This may error if either the request failed (due to lack of internet or
+	/// invalid domain, for example), or if the CT log gave a 4xx/5xx response.
+	/// The CT log may error the response if your first and second tree sizes
+	/// are invalid, for example if the second is smaller than the first or if
+	/// the tree has never contained a size specified in `first` or `second`.
+	pub async fn get_signed_tree_head_consistency(
+		&self,
+		first: u64,
+		second: u64
+	) -> reqwest::Result<GetSthConsistencyResponse> {
+		self.inner_client
+			.request(
+				endpoints::GET_STH_CONSISTENCY.0,
+				self.log_url.to_string() + endpoints::GET_STH_CONSISTENCY.1
+			)
+			.query(&[("first", first), ("second", second)])
+			.send()
+			.await?
+			.error_for_status()?
+			.json()
+			.await
+	}
 }

src/api/responses.rs

@@ -32,3 +32,12 @@ pub struct GetSthResponse {
 	pub sha256_root_hash: String,
 	pub tree_head_signature: String
 }
+
+/// A response given when fetching the Signed Tree Head consistency proof of a
+/// CT log
+///
+/// See: [`super::endpoints::GET_STH_CONSISTENCY`]
+#[derive(Debug, Deserialize)]
+pub struct GetSthConsistencyResponse {
+	pub consistency: Vec<String>
+}