Implement VC API (#1657)

## Issue Addressed

NA

## Proposed Changes

- Implements a HTTP API for the validator client.
- Creates EIP-2335 keystores with an empty `description` field, instead of a missing `description` field. Adds option to set name.
- Be more graceful with setups without any validators (yet)
    - Remove an error log when there are no validators.
    - Create the `validator` dir if it doesn't exist.
- Allow building a `ValidatorDir` without a withdrawal keystore (required for the API method where we only post a voting keystore).
- Add optional `description` field to `validator_definitions.yml`

## TODO

- [x] Signature header, as per https://github.com/sigp/lighthouse/issues/1269#issuecomment-649879855
- [x] Return validator descriptions
- [x] Return deposit data
- [x] Respect the mnemonic offset
- [x] Check that mnemonic can derive returned keys
- [x] Be strict about non-localhost
- [x] Allow graceful start without any validators (+ create validator dir)
- [x] Docs final pass
- [x] Swap to EIP-2335 description field. 
- [x] Fix Zerioze TODO in VC api types.
- [x] Zeroize secp256k1 key

## Endpoints

- [x] `GET /lighthouse/version`
- [x] `GET /lighthouse/health`
- [x] `GET /lighthouse/validators` 
- [x] `POST /lighthouse/validators/hd`
- [x] `POST /lighthouse/validators/keystore`
- [x] `PATCH /lighthouse/validators/:validator_pubkey`
- [ ] ~~`POST /lighthouse/validators/:validator_pubkey/exit/:epoch`~~ Future works


## Additional Info

TBC

common/eth2/src/lib.rs

@@ -9,6 +9,7 @@
 
 #[cfg(feature = "lighthouse")]
 pub mod lighthouse;
+pub mod lighthouse_vc;
 pub mod types;
 
 use self::types::*;
@@ -30,6 +31,14 @@ pub enum Error {
     StatusCode(StatusCode),
     /// The supplied URL is badly formatted. It should look something like `http://127.0.0.1:5052`.
     InvalidUrl(Url),
+    /// The supplied validator client secret is invalid.
+    InvalidSecret(String),
+    /// The server returned a response with an invalid signature. It may be an impostor.
+    InvalidSignatureHeader,
+    /// The server returned a response without a signature header. It may be an impostor.
+    MissingSignatureHeader,
+    /// The server returned an invalid JSON response.
+    InvalidJson(serde_json::Error),
 }
 
 impl Error {
@@ -40,6 +49,10 @@ impl Error {
             Error::ServerMessage(msg) => StatusCode::try_from(msg.code).ok(),
             Error::StatusCode(status) => Some(*status),
             Error::InvalidUrl(_) => None,
+            Error::InvalidSecret(_) => None,
+            Error::InvalidSignatureHeader => None,
+            Error::MissingSignatureHeader => None,
+            Error::InvalidJson(_) => None,
         }
     }
 }
@@ -531,7 +544,7 @@ impl BeaconNodeHttpClient {
         self.get(path).await
     }
 
-    /// `GET config/fork_schedule`
+    /// `GET config/spec`
     pub async fn get_config_spec(&self) -> Result<GenericResponse<YamlConfig>, Error> {
         let mut path = self.eth_path()?;
 

common/eth2/src/lighthouse_vc/http_client.rs

@@ -0,0 +1,331 @@
+use super::{types::*, PK_LEN, SECRET_PREFIX};
+use crate::Error;
+use account_utils::ZeroizeString;
+use bytes::Bytes;
+use reqwest::{
+    header::{HeaderMap, HeaderValue},
+    IntoUrl,
+};
+use ring::digest::{digest, SHA256};
+use secp256k1::{Message, PublicKey, Signature};
+use serde::{de::DeserializeOwned, Serialize};
+
+pub use reqwest;
+pub use reqwest::{Response, StatusCode, Url};
+
+/// A wrapper around `reqwest::Client` which provides convenience methods for interfacing with a
+/// Lighthouse Validator Client HTTP server (`validator_client/src/http_api`).
+#[derive(Clone)]
+pub struct ValidatorClientHttpClient {
+    client: reqwest::Client,
+    server: Url,
+    secret: ZeroizeString,
+    server_pubkey: PublicKey,
+}
+
+/// Parse an API token and return a secp256k1 public key.
+pub fn parse_pubkey(secret: &str) -> Result<PublicKey, Error> {
+    let secret = if !secret.starts_with(SECRET_PREFIX) {
+        return Err(Error::InvalidSecret(format!(
+            "secret does not start with {}",
+            SECRET_PREFIX
+        )));
+    } else {
+        &secret[SECRET_PREFIX.len()..]
+    };
+
+    serde_utils::hex::decode(&secret)
+        .map_err(|e| Error::InvalidSecret(format!("invalid hex: {:?}", e)))
+        .and_then(|bytes| {
+            if bytes.len() != PK_LEN {
+                return Err(Error::InvalidSecret(format!(
+                    "expected {} bytes not {}",
+                    PK_LEN,
+                    bytes.len()
+                )));
+            }
+
+            let mut arr = [0; PK_LEN];
+            arr.copy_from_slice(&bytes);
+            PublicKey::parse_compressed(&arr)
+                .map_err(|e| Error::InvalidSecret(format!("invalid secp256k1 pubkey: {:?}", e)))
+        })
+}
+
+impl ValidatorClientHttpClient {
+    pub fn new(server: Url, secret: String) -> Result<Self, Error> {
+        Ok(Self {
+            client: reqwest::Client::new(),
+            server,
+            server_pubkey: parse_pubkey(&secret)?,
+            secret: secret.into(),
+        })
+    }
+
+    pub fn from_components(
+        server: Url,
+        client: reqwest::Client,
+        secret: String,
+    ) -> Result<Self, Error> {
+        Ok(Self {
+            client,
+            server,
+            server_pubkey: parse_pubkey(&secret)?,
+            secret: secret.into(),
+        })
+    }
+
+    async fn signed_body(&self, response: Response) -> Result<Bytes, Error> {
+        let sig = response
+            .headers()
+            .get("Signature")
+            .ok_or_else(|| Error::MissingSignatureHeader)?
+            .to_str()
+            .map_err(|_| Error::InvalidSignatureHeader)?
+            .to_string();
+
+        let body = response.bytes().await.map_err(Error::Reqwest)?;
+
+        let message =
+            Message::parse_slice(digest(&SHA256, &body).as_ref()).expect("sha256 is 32 bytes");
+
+        serde_utils::hex::decode(&sig)
+            .ok()
+            .and_then(|bytes| {
+                let sig = Signature::parse_der(&bytes).ok()?;
+                Some(secp256k1::verify(&message, &sig, &self.server_pubkey))
+            })
+            .filter(|is_valid| *is_valid)
+            .ok_or_else(|| Error::InvalidSignatureHeader)?;
+
+        Ok(body)
+    }
+
+    async fn signed_json<T: DeserializeOwned>(&self, response: Response) -> Result<T, Error> {
+        let body = self.signed_body(response).await?;
+        serde_json::from_slice(&body).map_err(Error::InvalidJson)
+    }
+
+    fn headers(&self) -> Result<HeaderMap, Error> {
+        let header_value = HeaderValue::from_str(&format!("Basic {}", self.secret.as_str()))
+            .map_err(|e| {
+                Error::InvalidSecret(format!("secret is invalid as a header value: {}", e))
+            })?;
+
+        let mut headers = HeaderMap::new();
+        headers.insert("Authorization", header_value);
+
+        Ok(headers)
+    }
+
+    /// Perform a HTTP GET request.
+    async fn get<T: DeserializeOwned, U: IntoUrl>(&self, url: U) -> Result<T, Error> {
+        let response = self
+            .client
+            .get(url)
+            .headers(self.headers()?)
+            .send()
+            .await
+            .map_err(Error::Reqwest)?;
+        let response = ok_or_error(response).await?;
+        self.signed_json(response).await
+    }
+
+    /// Perform a HTTP GET request, returning `None` on a 404 error.
+    async fn get_opt<T: DeserializeOwned, U: IntoUrl>(&self, url: U) -> Result<Option<T>, Error> {
+        let response = self
+            .client
+            .get(url)
+            .headers(self.headers()?)
+            .send()
+            .await
+            .map_err(Error::Reqwest)?;
+        match ok_or_error(response).await {
+            Ok(resp) => self.signed_json(resp).await.map(Option::Some),
+            Err(err) => {
+                if err.status() == Some(StatusCode::NOT_FOUND) {
+                    Ok(None)
+                } else {
+                    Err(err)
+                }
+            }
+        }
+    }
+
+    /// Perform a HTTP POST request.
+    async fn post<T: Serialize, U: IntoUrl, V: DeserializeOwned>(
+        &self,
+        url: U,
+        body: &T,
+    ) -> Result<V, Error> {
+        let response = self
+            .client
+            .post(url)
+            .headers(self.headers()?)
+            .json(body)
+            .send()
+            .await
+            .map_err(Error::Reqwest)?;
+        let response = ok_or_error(response).await?;
+        self.signed_json(response).await
+    }
+
+    /// Perform a HTTP PATCH request.
+    async fn patch<T: Serialize, U: IntoUrl>(&self, url: U, body: &T) -> Result<(), Error> {
+        let response = self
+            .client
+            .patch(url)
+            .headers(self.headers()?)
+            .json(body)
+            .send()
+            .await
+            .map_err(Error::Reqwest)?;
+        let response = ok_or_error(response).await?;
+        self.signed_body(response).await?;
+        Ok(())
+    }
+
+    /// `GET lighthouse/version`
+    pub async fn get_lighthouse_version(&self) -> Result<GenericResponse<VersionData>, Error> {
+        let mut path = self.server.clone();
+
+        path.path_segments_mut()
+            .map_err(|()| Error::InvalidUrl(self.server.clone()))?
+            .push("lighthouse")
+            .push("version");
+
+        self.get(path).await
+    }
+
+    /// `GET lighthouse/health`
+    pub async fn get_lighthouse_health(&self) -> Result<GenericResponse<Health>, Error> {
+        let mut path = self.server.clone();
+
+        path.path_segments_mut()
+            .map_err(|()| Error::InvalidUrl(self.server.clone()))?
+            .push("lighthouse")
+            .push("health");
+
+        self.get(path).await
+    }
+
+    /// `GET lighthouse/spec`
+    pub async fn get_lighthouse_spec(&self) -> Result<GenericResponse<YamlConfig>, Error> {
+        let mut path = self.server.clone();
+
+        path.path_segments_mut()
+            .map_err(|()| Error::InvalidUrl(self.server.clone()))?
+            .push("lighthouse")
+            .push("spec");
+
+        self.get(path).await
+    }
+
+    /// `GET lighthouse/validators`
+    pub async fn get_lighthouse_validators(
+        &self,
+    ) -> Result<GenericResponse<Vec<ValidatorData>>, Error> {
+        let mut path = self.server.clone();
+
+        path.path_segments_mut()
+            .map_err(|()| Error::InvalidUrl(self.server.clone()))?
+            .push("lighthouse")
+            .push("validators");
+
+        self.get(path).await
+    }
+
+    /// `GET lighthouse/validators/{validator_pubkey}`
+    pub async fn get_lighthouse_validators_pubkey(
+        &self,
+        validator_pubkey: &PublicKeyBytes,
+    ) -> Result<Option<GenericResponse<ValidatorData>>, Error> {
+        let mut path = self.server.clone();
+
+        path.path_segments_mut()
+            .map_err(|()| Error::InvalidUrl(self.server.clone()))?
+            .push("lighthouse")
+            .push("validators")
+            .push(&validator_pubkey.to_string());
+
+        self.get_opt(path).await
+    }
+
+    /// `POST lighthouse/validators`
+    pub async fn post_lighthouse_validators(
+        &self,
+        validators: Vec<ValidatorRequest>,
+    ) -> Result<GenericResponse<PostValidatorsResponseData>, Error> {
+        let mut path = self.server.clone();
+
+        path.path_segments_mut()
+            .map_err(|()| Error::InvalidUrl(self.server.clone()))?
+            .push("lighthouse")
+            .push("validators");
+
+        self.post(path, &validators).await
+    }
+
+    /// `POST lighthouse/validators/mnemonic`
+    pub async fn post_lighthouse_validators_mnemonic(
+        &self,
+        request: &CreateValidatorsMnemonicRequest,
+    ) -> Result<GenericResponse<Vec<CreatedValidator>>, Error> {
+        let mut path = self.server.clone();
+
+        path.path_segments_mut()
+            .map_err(|()| Error::InvalidUrl(self.server.clone()))?
+            .push("lighthouse")
+            .push("validators")
+            .push("mnemonic");
+
+        self.post(path, &request).await
+    }
+
+    /// `POST lighthouse/validators/keystore`
+    pub async fn post_lighthouse_validators_keystore(
+        &self,
+        request: &KeystoreValidatorsPostRequest,
+    ) -> Result<GenericResponse<ValidatorData>, Error> {
+        let mut path = self.server.clone();
+
+        path.path_segments_mut()
+            .map_err(|()| Error::InvalidUrl(self.server.clone()))?
+            .push("lighthouse")
+            .push("validators")
+            .push("keystore");
+
+        self.post(path, &request).await
+    }
+
+    /// `PATCH lighthouse/validators/{validator_pubkey}`
+    pub async fn patch_lighthouse_validators(
+        &self,
+        voting_pubkey: &PublicKeyBytes,
+        enabled: bool,
+    ) -> Result<(), Error> {
+        let mut path = self.server.clone();
+
+        path.path_segments_mut()
+            .map_err(|()| Error::InvalidUrl(self.server.clone()))?
+            .push("lighthouse")
+            .push("validators")
+            .push(&voting_pubkey.to_string());
+
+        self.patch(path, &ValidatorPatchRequest { enabled }).await
+    }
+}
+
+/// Returns `Ok(response)` if the response is a `200 OK` response. Otherwise, creates an
+/// appropriate error message.
+async fn ok_or_error(response: Response) -> Result<Response, Error> {
+    let status = response.status();
+
+    if status == StatusCode::OK {
+        Ok(response)
+    } else if let Ok(message) = response.json().await {
+        Err(Error::ServerMessage(message))
+    } else {
+        Err(Error::StatusCode(status))
+    }
+}

common/eth2/src/lighthouse_vc/mod.rs

@@ -0,0 +1,9 @@
+pub mod http_client;
+pub mod types;
+
+/// The number of bytes in the secp256k1 public key used as the authorization token for the VC API.
+pub const PK_LEN: usize = 33;
+
+/// The prefix for the secp256k1 public key when it is used as the authorization token for the VC
+/// API.
+pub const SECRET_PREFIX: &str = "api-token-";

common/eth2/src/lighthouse_vc/types.rs

@@ -0,0 +1,58 @@
+use account_utils::ZeroizeString;
+use eth2_keystore::Keystore;
+use serde::{Deserialize, Serialize};
+
+pub use crate::lighthouse::Health;
+pub use crate::types::{GenericResponse, VersionData};
+pub use types::*;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct ValidatorData {
+    pub enabled: bool,
+    pub description: String,
+    pub voting_pubkey: PublicKeyBytes,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct ValidatorRequest {
+    pub enable: bool,
+    pub description: String,
+    #[serde(with = "serde_utils::quoted_u64")]
+    pub deposit_gwei: u64,
+}
+
+#[derive(Clone, PartialEq, Serialize, Deserialize)]
+pub struct CreateValidatorsMnemonicRequest {
+    pub mnemonic: ZeroizeString,
+    #[serde(with = "serde_utils::quoted_u32")]
+    pub key_derivation_path_offset: u32,
+    pub validators: Vec<ValidatorRequest>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct CreatedValidator {
+    pub enabled: bool,
+    pub description: String,
+    pub voting_pubkey: PublicKeyBytes,
+    pub eth1_deposit_tx_data: String,
+    #[serde(with = "serde_utils::quoted_u64")]
+    pub deposit_gwei: u64,
+}
+
+#[derive(Clone, PartialEq, Serialize, Deserialize)]
+pub struct PostValidatorsResponseData {
+    pub mnemonic: ZeroizeString,
+    pub validators: Vec<CreatedValidator>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct ValidatorPatchRequest {
+    pub enabled: bool,
+}
+
+#[derive(Clone, PartialEq, Serialize, Deserialize)]
+pub struct KeystoreValidatorsPostRequest {
+    pub password: ZeroizeString,
+    pub enable: bool,
+    pub keystore: Keystore,
+}