cosigner_client/

lib.rs

//! Signers for Arch Network transactions, local or through the
//! `arch-cosigner` custody proxy.
//!
//! [`ArchSignerT`] is the signing interface: implementors provide
//! [`pubkey`](ArchSignerT::pubkey) and
//! [`sign_message`](ArchSignerT::sign_message), and inherit transaction
//! assembly ([`sign_transaction`](ArchSignerT::sign_transaction),
//! [`sign_transaction_mixed`](ArchSignerT::sign_transaction_mixed)).
//! [`LocalSigner`] signs with an in-memory keypair; [`RemoteSigner`] delegates
//! to the proxy's `POST /v1/sign` and verifies every response. [`ArchSigner`]
//! wraps both behind one type so the deployment environment can choose the
//! backend ([`ArchSigner::from_env`]).
//!
//! # Examples
//!
//! ```
//! use cosigner_client::{ArchSigner, ArchSignerT, SignError};
//!
//! async fn submit(
//!     message: arch_program::sanitized::ArchMessage,
//! ) -> Result<arch_sdk::RuntimeTransaction, SignError> {
//!     let signer = ArchSigner::from_env()?;
//!     signer.sign_transaction(message).await
//! }
//! ```

#![warn(missing_docs)]

mod env;

use std::str::FromStr;
use std::time::Duration;

use arch_program::pubkey::Pubkey;
use arch_program::sanitized::ArchMessage;
use arch_sdk::{RuntimeTransaction, Signature};
use async_trait::async_trait;
use base64::Engine;
use bitcoin::key::UntweakedKeypair;
use bitcoin::secp256k1::{Secp256k1, SecretKey, XOnlyPublicKey};

/// Error surface for signer construction and signing.
#[derive(Debug, thiserror::Error)]
pub enum SignError {
    /// Signer configuration is missing, ambiguous, or invalid.
    #[error("signer configuration: {0}")]
    Config(String),
    /// Producing a signature failed, or a required signer key has no matching
    /// signer.
    #[error("signing failed: {0}")]
    Signing(String),
    /// The cosigner proxy answered with a non-success status, or the request
    /// did not complete.
    #[error("cosigner proxy error{}: {detail}", fmt_status(.status))]
    Proxy {
        /// HTTP status answered by the proxy; `None` for transport failures
        /// (connect errors and timeouts).
        status: Option<u16>,
        /// Detail from the proxy's error body, or the transport error text.
        detail: String,
    },
    /// A proxy response failed the checks described on [`RemoteSigner`].
    #[error("response verification failed: {0}")]
    Verification(String),
}

fn fmt_status(status: &Option<u16>) -> String {
    match status {
        Some(code) => format!(" (http {code})"),
        None => String::new(),
    }
}

/// A signature over a message's BIP322 digest, with backend metadata.
#[derive(Debug, Clone)]
pub struct SignResponse {
    /// 64-byte BIP340 signature over the message's BIP322 digest.
    pub signature: [u8; 64],
    /// The Arch account key the signature verifies under.
    pub arch_account_pubkey: [u8; 32],
    /// Digest the proxy reports having signed, hex; `None` for local signing.
    pub digest_hex: Option<String>,
    /// Turnkey activity id for audit reconciliation; `None` for local signing.
    pub turnkey_activity_id: Option<String>,
}

impl SignResponse {
    /// Returns the 64-byte BIP340 signature.
    pub fn signature(&self) -> &[u8; 64] {
        &self.signature
    }
}

/// Signing interface shared by local and remote backends.
///
/// Implementors supply [`pubkey`](Self::pubkey) and
/// [`sign_message`](Self::sign_message); the transaction-assembly methods are
/// provided. Object-safe: `&dyn ArchSignerT` works.
#[async_trait]
pub trait ArchSignerT: Send + Sync {
    /// Returns the Arch account key this signer signs for.
    fn pubkey(&self) -> Pubkey;

    /// Signs the message's BIP322 digest.
    ///
    /// # Errors
    /// [`SignError::Signing`] when producing the signature fails.
    /// [`RemoteSigner`] also returns [`SignError::Proxy`] and
    /// [`SignError::Verification`] as described on its type documentation.
    async fn sign_message(&self, message: &ArchMessage) -> Result<SignResponse, SignError>;

    /// Signs a transaction whose only required signer is this signer.
    ///
    /// # Errors
    /// As for [`sign_transaction_mixed`](Self::sign_transaction_mixed) with no
    /// cosigners.
    async fn sign_transaction(
        &self,
        message: ArchMessage,
    ) -> Result<RuntimeTransaction, SignError> {
        self.sign_transaction_mixed(message, &[]).await
    }

    /// Signs a transaction with this signer plus local cosigner keypairs.
    ///
    /// Each of the first `num_required_signatures` entries of
    /// `message.account_keys` receives a signature at its own position: this
    /// signer's key is signed via [`sign_message`](Self::sign_message), a
    /// cosigner key is signed with its keypair, and the assembled
    /// [`RuntimeTransaction`] carries the signatures in `account_keys` order.
    ///
    /// # Errors
    /// Propagates [`sign_message`](Self::sign_message) errors;
    /// [`SignError::Signing`] when a required key matches neither this signer
    /// nor a cosigner, or when a cosigner signature fails.
    async fn sign_transaction_mixed(
        &self,
        message: ArchMessage,
        local_cosigners: &[UntweakedKeypair],
    ) -> Result<RuntimeTransaction, SignError> {
        let digest = message.hash();
        let required = message.header.num_required_signatures as usize;
        let mut signatures = Vec::with_capacity(required);

        for key in message.account_keys.iter().take(required) {
            if *key == self.pubkey() {
                signatures.push(Signature(self.sign_message(&message).await?.signature));
            } else if let Some(kp) = local_cosigners
                .iter()
                .find(|kp| XOnlyPublicKey::from_keypair(kp).0.serialize() == key.serialize())
            {
                // BIP-0322 P2TR signatures are network-independent (the
                // script_pubkey carries no network), so Bitcoin is safe for
                // ephemeral cosigners regardless of deployment network.
                let sig = arch_sdk::sign_message_bip322(kp, &digest, bitcoin::Network::Bitcoin)
                    .map_err(|e| SignError::Signing(e.to_string()))?;
                signatures.push(Signature(sig));
            } else {
                return Err(SignError::Signing(format!(
                    "no signer for required key {}",
                    hex::encode(key.serialize())
                )));
            }
        }

        Ok(RuntimeTransaction {
            version: 0,
            signatures,
            message,
        })
    }
}

/// Signs with an in-memory keypair via [`arch_sdk::sign_message_bip322`].
#[derive(Clone)]
pub struct LocalSigner {
    keypair: UntweakedKeypair,
    pubkey: Pubkey,
    network: bitcoin::Network,
}

impl LocalSigner {
    /// Wraps an in-memory keypair, with the network defaulting to Bitcoin.
    pub fn new(keypair: UntweakedKeypair) -> Self {
        let pubkey = Pubkey::from_slice(&XOnlyPublicKey::from_keypair(&keypair).0.serialize());
        Self {
            keypair,
            pubkey,
            network: bitcoin::Network::Bitcoin,
        }
    }

    /// Loads a keypair from a file in [`arch_sdk::with_secret_key_file`]
    /// format: a hex-encoded secret key or a JSON byte array.
    ///
    /// Never generates or writes a key.
    ///
    /// # Errors
    /// [`SignError::Config`] when the file is unreadable or does not parse
    /// as a secret key.
    pub fn from_key_file(path: &str) -> Result<Self, SignError> {
        let content = std::fs::read_to_string(path)
            .map_err(|e| SignError::Config(format!("reading key file {path}: {e}")))?;
        let secret = parse_secret_key(&content)
            .map_err(|e| SignError::Config(format!("key file {path}: {e}")))?;
        Ok(Self::new(UntweakedKeypair::from_secret_key(
            &Secp256k1::new(),
            &secret,
        )))
    }

    /// Returns this signer with `network` used for BIP322 digests.
    pub fn with_network(mut self, network: bitcoin::Network) -> Self {
        self.network = network;
        self
    }

    /// Returns the Arch account key derived from the wrapped keypair.
    pub fn pubkey(&self) -> Pubkey {
        self.pubkey
    }

    /// Returns the network used for BIP322 digests.
    pub fn network(&self) -> bitcoin::Network {
        self.network
    }
}

/// Parses the two encodings accepted by [`arch_sdk::with_secret_key_file`]:
/// a hex secret key, or a JSON byte array whose first 32 bytes are the key.
fn parse_secret_key(content: &str) -> Result<SecretKey, String> {
    if let Ok(secret) = SecretKey::from_str(content) {
        return Ok(secret);
    }
    let bytes: Vec<u8> = serde_json::from_str(content)
        .map_err(|_| "neither a hex secret key nor a JSON byte array".to_string())?;
    let head = bytes
        .get(..32)
        .ok_or_else(|| format!("byte array holds {} bytes, need 32", bytes.len()))?;
    SecretKey::from_slice(head).map_err(|e| e.to_string())
}

#[async_trait]
impl ArchSignerT for LocalSigner {
    fn pubkey(&self) -> Pubkey {
        self.pubkey
    }

    async fn sign_message(&self, message: &ArchMessage) -> Result<SignResponse, SignError> {
        let signature = arch_sdk::sign_message_bip322(&self.keypair, &message.hash(), self.network)
            .map_err(|e| SignError::Signing(e.to_string()))?;
        Ok(SignResponse {
            signature,
            arch_account_pubkey: self.pubkey.serialize(),
            digest_hex: None,
            turnkey_activity_id: None,
        })
    }
}

/// Signs by delegating to an `arch-cosigner` proxy over `POST /v1/sign`.
///
/// Every response is verified before it is returned: the response's
/// `arch_account_pubkey` must equal the configured [`pubkey`](Self::pubkey),
/// and the signature must BIP322-verify for the exact submitted message under
/// that key (DEFAULT-then-ALL sighash, the validator's order). A failed check
/// is [`SignError::Verification`].
///
/// [`sign_message`](ArchSignerT::sign_message) retries `Proxy` errors with
/// status 502 and transport failures (`Proxy` with status `None`) up to the
/// configured retry count, with exponential backoff. Every other error,
/// including a 503 from a halted proxy, returns on first occurrence.
#[derive(Clone)]
pub struct RemoteSigner {
    http: reqwest::Client,
    url: String,
    token: String,
    role: String,
    intent: String,
    pubkey: Pubkey,
    network: bitcoin::Network,
    retries: u32,
    backoff: Duration,
}

impl RemoteSigner {
    /// Creates a signer for `role` at the proxy base `url`, verifying every
    /// response against `pubkey`.
    ///
    /// Defaults: network Bitcoin, 35 s request timeout, 2 retries, intent
    /// "unlabeled", 250 ms retry backoff.
    pub fn new(url: &str, token: &str, role: &str, pubkey: Pubkey) -> Self {
        Self {
            // The default timeout covers the proxy's worst case of
            // (1 + retries) × turnkey_timeout + backoff ≈ 31 s.
            http: http_client(Duration::from_secs(35)),
            url: url.trim_end_matches('/').to_string(),
            token: token.to_string(),
            role: role.to_string(),
            intent: "unlabeled".to_string(),
            pubkey,
            network: bitcoin::Network::Bitcoin,
            retries: 2,
            backoff: Duration::from_millis(250),
        }
    }

    /// Returns this signer with `network` used for response verification.
    pub fn with_network(mut self, network: bitcoin::Network) -> Self {
        self.network = network;
        self
    }

    /// Returns this signer with the intent label recorded in the proxy's
    /// audit log.
    pub fn with_intent(mut self, intent: &str) -> Self {
        self.intent = intent.to_string();
        self
    }

    /// Returns this signer with the retry budget for retryable errors.
    pub fn with_retries(mut self, retries: u32) -> Self {
        self.retries = retries;
        self
    }

    /// Returns this signer with the per-request HTTP timeout.
    pub fn with_timeout(mut self, timeout: Duration) -> Self {
        self.http = http_client(timeout);
        self
    }

    /// Returns the Arch account key responses are verified against.
    pub fn pubkey(&self) -> Pubkey {
        self.pubkey
    }

    /// Returns the network used for response verification.
    pub fn network(&self) -> bitcoin::Network {
        self.network
    }

    /// Returns the proxy base URL with any trailing `/` trimmed.
    pub fn base_url(&self) -> &str {
        &self.url
    }

    /// One `POST /v1/sign` round trip, verified; no retries at this level.
    async fn sign_once(
        &self,
        message_b64: &str,
        message: &ArchMessage,
    ) -> Result<SignResponse, SignError> {
        let resp = self
            .http
            .post(format!("{}/v1/sign", self.url))
            .bearer_auth(&self.token)
            .json(&serde_json::json!({
                "role": self.role,
                "intent_type": self.intent,
                "unsigned_message_b64": message_b64,
            }))
            .send()
            .await
            .map_err(|e| SignError::Proxy {
                status: None,
                detail: e.to_string(),
            })?;

        let status = resp.status().as_u16();
        let body: serde_json::Value = match resp.json().await {
            Ok(body) => body,
            // A 200 whose body fails to arrive is a transport failure;
            // error-status bodies only feed the detail string below.
            Err(e) if status == 200 => {
                return Err(SignError::Proxy {
                    status: None,
                    detail: format!("response body: {e}"),
                })
            }
            Err(_) => serde_json::Value::Null,
        };
        if status != 200 {
            let detail = body["error"]
                .as_str()
                .or_else(|| body["halted"].as_str())
                .unwrap_or("<no detail>")
                .to_string();
            return Err(SignError::Proxy {
                status: Some(status),
                detail,
            });
        }

        let signature: [u8; 64] = hex::decode(body["signature_hex"].as_str().unwrap_or_default())
            .ok()
            .and_then(|v| v.try_into().ok())
            .ok_or_else(|| {
                SignError::Verification("signature_hex missing or not 64 bytes".into())
            })?;

        let expected_pubkey = hex::encode(self.pubkey.serialize());
        if body["arch_account_pubkey"].as_str() != Some(expected_pubkey.as_str()) {
            return Err(SignError::Verification(format!(
                "proxy signed with {} but this signer is configured for {expected_pubkey}",
                body["arch_account_pubkey"]
            )));
        }

        let digest = message.hash();
        arch_sdk::verify_message_bip322(
            &digest,
            self.pubkey.serialize(),
            signature,
            false,
            self.network,
        )
        .or_else(|_| {
            arch_sdk::verify_message_bip322(
                &digest,
                self.pubkey.serialize(),
                signature,
                true,
                self.network,
            )
        })
        .map_err(|e| SignError::Verification(e.to_string()))?;

        Ok(SignResponse {
            signature,
            arch_account_pubkey: self.pubkey.serialize(),
            digest_hex: body["digest_hex"].as_str().map(str::to_string),
            turnkey_activity_id: body["turnkey_activity_id"].as_str().map(str::to_string),
        })
    }
}

impl std::fmt::Debug for RemoteSigner {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("RemoteSigner")
            .field("url", &self.url)
            .field("token", &"<redacted>")
            .field("role", &self.role)
            .field("intent", &self.intent)
            .field("pubkey", &self.pubkey)
            .field("network", &self.network)
            .field("retries", &self.retries)
            .finish_non_exhaustive()
    }
}

fn http_client(timeout: Duration) -> reqwest::Client {
    reqwest::Client::builder()
        .timeout(timeout)
        .build()
        .expect("client construction with static config cannot fail")
}

fn is_retryable(err: &SignError) -> bool {
    matches!(
        err,
        SignError::Proxy {
            status: Some(502) | None,
            ..
        }
    )
}

#[async_trait]
impl ArchSignerT for RemoteSigner {
    fn pubkey(&self) -> Pubkey {
        self.pubkey
    }

    async fn sign_message(&self, message: &ArchMessage) -> Result<SignResponse, SignError> {
        let message_b64 = base64::engine::general_purpose::STANDARD.encode(message.serialize());
        let mut attempt = 0;
        loop {
            match self.sign_once(&message_b64, message).await {
                Err(err) if attempt < self.retries && is_retryable(&err) => {
                    tokio::time::sleep(self.backoff.saturating_mul(2u32.saturating_pow(attempt)))
                        .await;
                    attempt += 1;
                }
                result => return result,
            }
        }
    }
}

/// A signer whose backend, local or remote, is chosen at runtime.
#[derive(Clone)]
pub enum ArchSigner {
    /// In-process signing with a [`LocalSigner`].
    Local(LocalSigner),
    /// Proxy-delegated signing with a [`RemoteSigner`].
    Remote(RemoteSigner),
}

impl ArchSigner {
    /// Wraps `keypair` as a [`LocalSigner`].
    pub fn local(keypair: UntweakedKeypair) -> Self {
        Self::Local(LocalSigner::new(keypair))
    }

    /// Loads a [`LocalSigner`] from a key file.
    ///
    /// # Errors
    /// [`SignError::Config`] as described on [`LocalSigner::from_key_file`].
    pub fn local_from_key_file(path: &str) -> Result<Self, SignError> {
        Ok(Self::Local(LocalSigner::from_key_file(path)?))
    }

    /// Creates a [`RemoteSigner`] for `role` at the proxy base `url`.
    pub fn remote(url: &str, token: &str, role: &str, pubkey: Pubkey) -> Self {
        Self::Remote(RemoteSigner::new(url, token, role, pubkey))
    }

    /// Resolves a signer from bare environment variables.
    ///
    /// Remote configuration reads `COSIGNER_URL`, `COSIGNER_TOKEN`,
    /// `COSIGNER_ROLE`, and `COSIGNER_PUBKEY` (64 hex characters); local
    /// configuration reads `ARCH_KEY_PATH`. Exactly one of `COSIGNER_URL` and
    /// `ARCH_KEY_PATH` must be set, and empty values count as unset. The
    /// network is not read from the environment: it defaults to Bitcoin and
    /// is set with [`with_network`](Self::with_network).
    ///
    /// # Errors
    /// [`SignError::Config`] when neither or both backends are configured,
    /// when a required remote variable is missing (the message names every
    /// missing variable), or when `COSIGNER_PUBKEY` is not 64 hex characters.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// use cosigner_client::ArchSigner;
    ///
    /// # fn main() -> Result<(), cosigner_client::SignError> {
    /// let signer = ArchSigner::from_env()?.with_intent("sweep");
    /// # let _ = signer;
    /// # Ok(())
    /// # }
    /// ```
    pub fn from_env() -> Result<Self, SignError> {
        env::resolve("")
    }

    /// Resolves a signer from `{prefix}_`-prefixed environment variables,
    /// falling back to the bare names.
    ///
    /// Each variable from [`from_env`](Self::from_env) is first looked up as
    /// `{prefix}_{NAME}`. The backend is chosen at the most specific level
    /// that sets a backend-selecting variable (`{prefix}_COSIGNER_URL` or
    /// `{prefix}_ARCH_KEY_PATH`); when the prefixed level sets neither, the
    /// bare level decides. After the backend is chosen, every variable fills
    /// per-variable with the prefixed value first, so one bare `COSIGNER_URL`
    /// can serve several prefixed tokens. Trailing underscores in `prefix`
    /// are ignored, and an empty `prefix` behaves exactly like
    /// [`from_env`](Self::from_env).
    ///
    /// # Errors
    /// [`SignError::Config`] under the conditions listed on
    /// [`from_env`](Self::from_env), with the ambiguity check applied at the
    /// deciding level.
    pub fn from_prefixed_env(prefix: &str) -> Result<Self, SignError> {
        env::resolve(prefix)
    }

    /// Returns this signer with `network` applied to either variant.
    pub fn with_network(self, network: bitcoin::Network) -> Self {
        match self {
            Self::Local(s) => Self::Local(s.with_network(network)),
            Self::Remote(s) => Self::Remote(s.with_network(network)),
        }
    }

    /// Returns this signer with the intent label set on the remote variant;
    /// no-op for a local signer.
    pub fn with_intent(self, intent: &str) -> Self {
        match self {
            Self::Remote(s) => Self::Remote(s.with_intent(intent)),
            local => local,
        }
    }

    /// Returns this signer with the retry budget set on the remote variant;
    /// no-op for a local signer.
    pub fn with_retries(self, retries: u32) -> Self {
        match self {
            Self::Remote(s) => Self::Remote(s.with_retries(retries)),
            local => local,
        }
    }

    /// Returns this signer with the HTTP timeout set on the remote variant;
    /// no-op for a local signer.
    pub fn with_timeout(self, timeout: Duration) -> Self {
        match self {
            Self::Remote(s) => Self::Remote(s.with_timeout(timeout)),
            local => local,
        }
    }

    /// Returns the configured network.
    pub fn network(&self) -> bitcoin::Network {
        match self {
            Self::Local(s) => s.network(),
            Self::Remote(s) => s.network(),
        }
    }

    /// Returns whether this signer delegates to a proxy.
    pub fn is_remote(&self) -> bool {
        matches!(self, Self::Remote(_))
    }

    /// Returns the local variant, if any.
    pub fn as_local(&self) -> Option<&LocalSigner> {
        match self {
            Self::Local(s) => Some(s),
            Self::Remote(_) => None,
        }
    }

    /// Returns the remote variant, if any.
    pub fn as_remote(&self) -> Option<&RemoteSigner> {
        match self {
            Self::Local(_) => None,
            Self::Remote(s) => Some(s),
        }
    }
}

#[async_trait]
impl ArchSignerT for ArchSigner {
    fn pubkey(&self) -> Pubkey {
        match self {
            Self::Local(s) => s.pubkey(),
            Self::Remote(s) => s.pubkey(),
        }
    }

    async fn sign_message(&self, message: &ArchMessage) -> Result<SignResponse, SignError> {
        match self {
            Self::Local(s) => s.sign_message(message).await,
            Self::Remote(s) => s.sign_message(message).await,
        }
    }
}