anda_web3_client 0.17.0

//! Concrete Web3 client for ICP, COSE, HTTPS, and signing operations.
//!
//! The client implements the capability traits consumed by `anda_engine`
//! contexts, including canister calls, signed HTTP calls, and deterministic
//! key derivation.

use crate::{
    crypto, ecdsa_digest,
    request::{check_url, rpc_body, send_request},
};
use anda_core::{BoxError, BoxPinFut, HttpFeatures, cbor_rpc};
use anda_engine::context::Web3ClientFeatures;
use candid::{
    CandidType, Decode, Principal,
    utils::{ArgumentEncoder, encode_args},
};
use cbor2::{from_slice, to_canonical_vec};
use ic_agent::identity::{AnonymousIdentity, BasicIdentity, Secp256k1Identity};
use ic_auth_verifier::envelope::SignedEnvelope;
use ic_cose::client::CoseSDK;
use ic_cose_types::{
    CanisterCaller,
    cose::{
        ed25519::ed25519_verify,
        k256::{secp256k1_verify_bip340, secp256k1_verify_ecdsa},
        sha3_256,
    },
};
use serde::{Serialize, de::DeserializeOwned};
use std::{future::ready, sync::Arc, time::Duration};
use zeroize::Zeroizing;

pub use ic_agent::{Agent, Identity};

use anda_engine::APP_USER_AGENT;

/// Client for interacting with outside services (includes ICP and other blockchains)
///
/// Provides cryptographic operations, canister communication, and HTTP features.
/// Manages both internal and external HTTP clients
/// with different configurations for secure communication.
#[derive(Clone)]
pub struct Client {
    outer_http: reqwest::Client,
    // Kept in a `Zeroizing` wrapper so the long-lived copy of the root secret is
    // wiped from memory on drop, reducing the window in which it could leak.
    root_secret: Option<Zeroizing<[u8; 48]>>,
    identity: Arc<dyn Identity>,
    principal: Principal,
    agent: Agent,
    cose_canister: Principal,
    allow_http: bool,
}

/// Builder for creating a new Client with custom configuration
#[non_exhaustive]
pub struct ClientBuilder {
    ic_host: String,
    root_secret: Option<Zeroizing<[u8; 48]>>,
    identity: Option<Arc<dyn Identity>>,
    agent: Option<Agent>,
    cose_canister: Principal,
    outer_http: Option<reqwest::Client>,
    allow_http: bool,
}

/// Returns a new Ed25519 identity from a 32-byte secret
pub fn identity_from_secret(id_secret: [u8; 32]) -> Box<dyn Identity> {
    Box::new(BasicIdentity::from_raw_key(&id_secret))
}

/// Loads an ICP identity from a PEM file (generated by dfx or other tools, supports both Ed25519 and Secp256k1)
pub fn identity_from_pem(path: &str) -> Result<Box<dyn Identity>, BoxError> {
    let content = std::fs::read_to_string(path)?;
    if let Ok(identity) = Secp256k1Identity::from_pem(content.as_bytes()) {
        return Ok(Box::new(identity));
    }
    // Report the actual PEM parse failure instead of masking it, so a malformed
    // key file is not mistaken for the wrong key type. The path is safe to echo
    // (it is a file location, not secret material).
    match BasicIdentity::from_pem(content.as_bytes()) {
        Ok(identity) => Ok(Box::new(identity)),
        Err(err) => Err(format!(
            "failed to parse PEM identity {path:?} as Secp256k1 or Ed25519: {err}"
        )
        .into()),
    }
}

/// Loads an identity from a PEM file path or a 32-byte hex-encoded secret.
///
/// The literal `"Anonymous"` returns the anonymous identity.
pub fn load_identity(id_secret_or_path: &str) -> Result<Box<dyn Identity>, BoxError> {
    if id_secret_or_path == "Anonymous" {
        return Ok(Box::new(AnonymousIdentity));
    }

    // When the input points at an existing file, treat it as a PEM identity and
    // surface the real PEM parse error, rather than silently falling back to hex
    // decoding and masking the cause as a generic "invalid id_secret".
    if std::path::Path::new(id_secret_or_path).is_file() {
        return identity_from_pem(id_secret_or_path);
    }

    // Otherwise treat the input as a 32-byte hex-encoded secret.
    // Never echo the input back: it may be a (mistyped) secret.
    let id_secret = hex::decode(id_secret_or_path)
        .map_err(|_| "invalid id_secret: expected a PEM file path or a 32-byte hex secret")?;
    let id_secret: [u8; 32] = id_secret.try_into().map_err(|secret: Vec<u8>| {
        format!(
            "invalid id_secret length: expected 32 bytes, got {}",
            secret.len()
        )
    })?;
    Ok(identity_from_secret(id_secret))
}

impl Default for ClientBuilder {
    fn default() -> Self {
        Self {
            ic_host: "https://icp-api.io".to_string(),
            root_secret: None,
            identity: None,
            agent: None,
            cose_canister: Principal::anonymous(),
            outer_http: None,
            allow_http: false,
        }
    }
}

impl ClientBuilder {
    /// Sets the base URL of the ICP network, default is `https://icp-api.io`
    pub fn with_ic_host(mut self, ic_host: &str) -> Self {
        self.ic_host = ic_host.to_string();
        self
    }

    /// Sets the persistent 48-byte root secret for key derivation.
    ///
    /// There is no default secret. Without one, key operations return an error.
    /// All-zero secrets are rejected at build time. Store a securely generated
    /// secret persistently to retain access to the same derived keys.
    pub fn with_root_secret(mut self, root_secret: [u8; 48]) -> Self {
        self.root_secret = Some(Zeroizing::new(root_secret));
        self
    }

    /// Sets the COSE canister principal. Configure it before using `CoseSDK`;
    /// the default anonymous principal does not identify a COSE canister.
    pub fn with_cose_canister(mut self, cose_canister: Principal) -> Self {
        self.cose_canister = cose_canister;
        self
    }

    /// Sets the identity for canister calls and HTTP/envelope signatures.
    ///
    /// If omitted, the identity is derived from the configured root secret.
    /// This does not supply a root secret for key derivation; identity-only
    /// clients can make authenticated requests but cannot derive keys.
    pub fn with_identity(mut self, identity: Arc<dyn Identity>) -> Self {
        self.identity = Some(identity);
        self
    }

    /// Sets the agent for canister communication, preserving its configuration.
    ///
    /// Its principal must match the client identity. Supply an agent explicitly
    /// to configure a local root key or opt out of query-signature verification.
    pub fn with_agent(mut self, agent: Agent) -> Self {
        self.agent = Some(agent);
        self
    }

    /// Sets the external HTTP client for making requests, default is a secure client
    pub fn with_http_client(mut self, http_client: reqwest::Client) -> Self {
        self.outer_http = Some(http_client);
        self
    }

    /// Allow HTTP connections (default is false)
    pub fn with_allow_http(mut self, allow_http: bool) -> Self {
        self.allow_http = allow_http;
        self
    }

    /// Builds a [`Client`] with the configured identity, agent, and HTTP client.
    ///
    /// Requires an identity or a nonzero root secret. The default agent verifies
    /// query signatures. For an `http://` IC host, fetching the replica root key
    /// must succeed within ten seconds; rebuild after resolving any failure.
    pub async fn build(self) -> Result<Client, BoxError> {
        if self
            .root_secret
            .as_ref()
            .is_some_and(|secret| secret.iter().all(|&b| b == 0))
        {
            return Err("root secret must not be all zeros".into());
        }

        let identity = match self.identity {
            Some(identity) => identity,
            None => {
                let secret = self
                    .root_secret
                    .as_ref()
                    .ok_or("configure an identity or a root secret before building a Client")?;
                Arc::from(identity_from_secret(sha3_256(&secret[..])))
            }
        };
        let principal = identity
            .sender()
            .map_err(|err| format!("failed to get the principal from identity: {err}"))?;

        let agent = match self.agent {
            Some(agent) => {
                if agent
                    .get_principal()
                    .map_err(|err| format!("invalid agent identity: {err}"))?
                    != principal
                {
                    return Err("agent principal does not match the client identity".into());
                }
                agent
            }
            None => {
                let agent = Agent::builder()
                    .with_url(&self.ic_host)
                    .with_arc_identity(identity.clone())
                    .build()?;

                if reqwest::Url::parse(&self.ic_host)?.scheme() == "http" {
                    tokio::time::timeout(Duration::from_secs(10), agent.fetch_root_key())
                        .await
                        .map_err(|_| "fetching replica root key timed out after 10 seconds")?
                        .map_err(|err| format!("failed to fetch replica root key: {err}"))?;
                }
                agent
            }
        };

        let outer_http = match self.outer_http {
            Some(http_client) => http_client,
            None => reqwest::Client::builder()
                .use_rustls_tls()
                .https_only(!self.allow_http)
                .http2_keep_alive_interval(Some(Duration::from_secs(25)))
                .http2_keep_alive_timeout(Duration::from_secs(15))
                .http2_keep_alive_while_idle(true)
                .connect_timeout(Duration::from_secs(10))
                .timeout(Duration::from_secs(120))
                .gzip(true)
                .user_agent(APP_USER_AGENT)
                .build()?,
        };

        Ok(Client {
            outer_http,
            root_secret: self.root_secret,
            identity,
            principal,
            agent,
            cose_canister: self.cose_canister,
            allow_http: self.allow_http,
        })
    }
}

impl Client {
    /// Creates a client builder with secure defaults.
    pub fn builder() -> ClientBuilder {
        ClientBuilder::default()
    }

    /// Returns the principal of the client identity, resolved at build time.
    pub fn get_principal(&self) -> Principal {
        self.principal
    }

    /// Signs a message digest with the client identity.
    pub async fn sign_envelope(
        &self,
        message_digest: [u8; 32],
    ) -> Result<SignedEnvelope, BoxError> {
        self.envelope(message_digest)
    }

    fn envelope(&self, message_digest: [u8; 32]) -> Result<SignedEnvelope, BoxError> {
        Ok(SignedEnvelope::sign_digest(
            &self.identity,
            message_digest.into(),
        )?)
    }

    fn root_secret(&self) -> Result<&[u8; 48], BoxError> {
        self.root_secret
            .as_deref()
            .ok_or_else(|| "key derivation requires ClientBuilder::with_root_secret".into())
    }

    /// Signs `message_digest` with the client identity and merges the
    /// authorization headers into `headers`.
    fn sign_headers(
        &self,
        message_digest: [u8; 32],
        headers: Option<http::HeaderMap>,
    ) -> Result<http::HeaderMap, BoxError> {
        let se = self.envelope(message_digest)?;
        let mut headers = headers.unwrap_or_default();
        se.to_authorization(&mut headers)?;
        Ok(headers)
    }

    /// Builds the signed authorization headers and CBOR body for a signed RPC
    /// request with CBOR-encoded `params`.
    fn signed_rpc_request(
        &self,
        method: &str,
        params: Vec<u8>,
    ) -> Result<(http::HeaderMap, Vec<u8>), BoxError> {
        let body = rpc_body(method, params)?;
        let digest: [u8; 32] = sha3_256(&body);
        let headers = self.sign_headers(digest, None)?;
        Ok((headers, body))
    }
}

// Local cryptographic operations return ready futures without copying inputs or
// dispatching each operation to a blocking pool. Hosts with sustained signing
// workloads can benchmark and schedule those workloads separately.
impl Web3ClientFeatures for Client {
    fn get_principal(&self) -> Principal {
        self.principal
    }

    fn sign_envelope(
        &self,
        message_digest: [u8; 32],
    ) -> BoxPinFut<Result<SignedEnvelope, BoxError>> {
        Box::pin(ready(self.envelope(message_digest)))
    }

    fn a256gcm_key(&self, derivation_path: Vec<Vec<u8>>) -> BoxPinFut<Result<[u8; 32], BoxError>> {
        let res = self
            .root_secret()
            .map(|root| crypto::a256gcm_key(root, derivation_path));
        Box::pin(ready(res))
    }

    fn ed25519_sign_message(
        &self,
        derivation_path: Vec<Vec<u8>>,
        message: &[u8],
    ) -> BoxPinFut<Result<[u8; 64], BoxError>> {
        let res = self
            .root_secret()
            .map(|root| crypto::ed25519_sign_message(root, derivation_path, message));
        Box::pin(ready(res))
    }

    fn ed25519_verify(
        &self,
        derivation_path: Vec<Vec<u8>>,
        message: &[u8],
        signature: &[u8],
    ) -> BoxPinFut<Result<(), BoxError>> {
        let res = self.root_secret().and_then(|root| {
            let (pk, _) = crypto::ed25519_public_key(root, derivation_path);
            ed25519_verify(&pk, message, signature).map_err(|e| e.into())
        });
        Box::pin(ready(res))
    }

    fn ed25519_public_key(
        &self,
        derivation_path: Vec<Vec<u8>>,
    ) -> BoxPinFut<Result<[u8; 32], BoxError>> {
        let res = self
            .root_secret()
            .map(|root| crypto::ed25519_public_key(root, derivation_path).0);
        Box::pin(ready(res))
    }

    fn secp256k1_sign_message_bip340(
        &self,
        derivation_path: Vec<Vec<u8>>,
        message: &[u8],
    ) -> BoxPinFut<Result<[u8; 64], BoxError>> {
        let res = self
            .root_secret()
            .map(|root| crypto::secp256k1_sign_message_bip340(root, derivation_path, message));
        Box::pin(ready(res))
    }

    fn secp256k1_verify_bip340(
        &self,
        derivation_path: Vec<Vec<u8>>,
        message: &[u8],
        signature: &[u8],
    ) -> BoxPinFut<Result<(), BoxError>> {
        let res = self.root_secret().and_then(|root| {
            let (pk, _) = crypto::secp256k1_public_key(root, derivation_path);
            secp256k1_verify_bip340(&pk, message, signature).map_err(|e| e.into())
        });
        Box::pin(ready(res))
    }

    fn secp256k1_sign_message_ecdsa(
        &self,
        derivation_path: Vec<Vec<u8>>,
        message: &[u8],
    ) -> BoxPinFut<Result<[u8; 64], BoxError>> {
        let res = self
            .root_secret()
            .map(|root| crypto::secp256k1_sign_message_ecdsa(root, derivation_path, message));
        Box::pin(ready(res))
    }

    fn secp256k1_sign_digest_ecdsa(
        &self,
        derivation_path: Vec<Vec<u8>>,
        message_hash: &[u8],
    ) -> BoxPinFut<Result<[u8; 64], BoxError>> {
        let res = ecdsa_digest(message_hash).and_then(|digest| {
            self.root_secret()
                .map(|root| crypto::secp256k1_sign_digest_ecdsa(root, derivation_path, digest))
        });
        Box::pin(ready(res))
    }

    fn secp256k1_verify_ecdsa(
        &self,
        derivation_path: Vec<Vec<u8>>,
        message_hash: &[u8],
        signature: &[u8],
    ) -> BoxPinFut<Result<(), BoxError>> {
        let res = ecdsa_digest(message_hash).and_then(|digest| {
            let (pk, _) = crypto::secp256k1_public_key(self.root_secret()?, derivation_path);
            secp256k1_verify_ecdsa(&pk, digest, signature).map_err(|e| e.into())
        });
        Box::pin(ready(res))
    }

    fn secp256k1_public_key(
        &self,
        derivation_path: Vec<Vec<u8>>,
    ) -> BoxPinFut<Result<[u8; 33], BoxError>> {
        let res = self
            .root_secret()
            .map(|root| crypto::secp256k1_public_key(root, derivation_path).0);
        Box::pin(ready(res))
    }

    fn https_call(
        &self,
        url: String,
        method: http::Method,
        headers: Option<http::HeaderMap>,
        body: Option<Vec<u8>>, // default is empty
    ) -> BoxPinFut<Result<reqwest::Response, BoxError>> {
        let url = match check_url(&url, self.allow_http) {
            Ok(url) => url,
            Err(err) => return Box::pin(ready(Err(err))),
        };

        Box::pin(send_request(
            self.outer_http.clone(),
            url,
            method,
            headers,
            body,
        ))
    }

    fn https_signed_call(
        &self,
        url: String,
        method: http::Method,
        message_digest: [u8; 32],
        headers: Option<http::HeaderMap>,
        body: Option<Vec<u8>>, // default is empty
    ) -> BoxPinFut<Result<reqwest::Response, BoxError>> {
        let url = match check_url(&url, self.allow_http) {
            Ok(url) => url,
            Err(err) => return Box::pin(ready(Err(err))),
        };
        let headers = match self.sign_headers(message_digest, headers) {
            Ok(headers) => headers,
            Err(err) => return Box::pin(ready(Err(err))),
        };

        Box::pin(send_request(
            self.outer_http.clone(),
            url,
            method,
            Some(headers),
            body,
        ))
    }

    fn https_signed_rpc_raw(
        &self,
        endpoint: String,
        method: String,
        args: Vec<u8>,
    ) -> BoxPinFut<Result<Vec<u8>, BoxError>> {
        if let Err(err) = check_url(&endpoint, self.allow_http) {
            return Box::pin(ready(Err(err)));
        }
        let (headers, body) = match self.signed_rpc_request(&method, args) {
            Ok(req) => req,
            Err(err) => return Box::pin(ready(Err(err))),
        };

        let outer_http = self.outer_http.clone();
        Box::pin(async move {
            let res = cbor_rpc(&outer_http, &endpoint, &method, Some(headers), body).await?;
            Ok(res.into_vec())
        })
    }
}

impl HttpFeatures for Client {
    async fn https_call(
        &self,
        url: &str,
        method: http::Method,
        headers: Option<http::HeaderMap>,
        body: Option<Vec<u8>>, // default is empty
    ) -> Result<reqwest::Response, BoxError> {
        let url = check_url(url, self.allow_http)?;
        send_request(self.outer_http.clone(), url, method, headers, body).await
    }

    async fn https_signed_call(
        &self,
        url: &str,
        method: http::Method,
        message_digest: [u8; 32],
        headers: Option<http::HeaderMap>,
        body: Option<Vec<u8>>, // default is empty
    ) -> Result<reqwest::Response, BoxError> {
        let url = check_url(url, self.allow_http)?;
        let headers = self.sign_headers(message_digest, headers)?;
        send_request(self.outer_http.clone(), url, method, Some(headers), body).await
    }

    async fn https_signed_rpc<T>(
        &self,
        endpoint: &str,
        method: &str,
        args: impl Serialize + Send,
    ) -> Result<T, BoxError>
    where
        T: DeserializeOwned,
    {
        check_url(endpoint, self.allow_http)?;
        let args = to_canonical_vec(&args)?;
        let (headers, body) = self.signed_rpc_request(method, args)?;
        let res = cbor_rpc(&self.outer_http, endpoint, method, Some(headers), body).await?;
        let res = from_slice(&res[..])?;
        Ok(res)
    }
}

/// Implements the `CoseSDK` trait for Client to enable IC-COSE canister API calls
///
/// This implementation provides the necessary interface to interact with the
/// [IC-COSE](https://github.com/ldclabs/ic-cose) canister, allowing cryptographic
/// operations through the COSE (CBOR Object Signing and Encryption) protocol.
impl CoseSDK for Client {
    fn canister(&self) -> &Principal {
        &self.cose_canister
    }
}

impl CanisterCaller for Client {
    /// Performs a query call to a canister (read-only, no state changes)
    ///
    /// # Arguments
    /// * `canister` - Target canister principal
    /// * `method` - Method name to call
    /// * `args` - Input arguments encoded in Candid format
    async fn canister_query<
        In: ArgumentEncoder + Send,
        Out: CandidType + for<'a> candid::Deserialize<'a>,
    >(
        &self,
        canister: &Principal,
        method: &str,
        args: In,
    ) -> Result<Out, BoxError> {
        let input = encode_args(args)?;
        let res = self
            .agent
            .query(canister, method)
            .with_arg(input)
            .call()
            .await?;
        let output = Decode!(res.as_slice(), Out)?;
        Ok(output)
    }

    /// Performs an update call to a canister (may modify state)
    ///
    /// # Arguments
    /// * `canister` - Target canister principal
    /// * `method` - Method name to call
    /// * `args` - Input arguments encoded in Candid format
    async fn canister_update<
        In: ArgumentEncoder + Send,
        Out: CandidType + for<'a> candid::Deserialize<'a>,
    >(
        &self,
        canister: &Principal,
        method: &str,
        args: In,
    ) -> Result<Out, BoxError> {
        let input = encode_args(args)?;
        let res = self
            .agent
            .update(canister, method)
            .with_arg(input)
            .call_and_wait()
            .await?;
        let output = Decode!(res.as_slice(), Out)?;
        Ok(output)
    }
}