net-cli 0.35.0

//! Lazy substrate context — config + identity + in-process SDK.
//!
//! Subcommands that touch the substrate call
//! [`CliContext::build`] to spin a `MeshOsDaemonSdk` + a
//! `DeckClient` configured against the resolved profile + the
//! operator identity. The build is one-shot per binary
//! invocation — every subcommand gets its own context (the CLI
//! is single-shot by design; long-running watches reuse the
//! same context for their lifetime).
//!
//! # Remote-attach
//!
//! Subcommands that need to call a remote daemon (today: every
//! `net-mesh aggregator` write/query verb) build through
//! [`CliContext::build_with_remote`] and pass a
//! [`RemoteAttach`]. The context boots a local ephemeral
//! `MeshNode` on `127.0.0.1:0`, completes the Noise handshake
//! with the remote, starts the receive loop, and exposes the
//! `Arc<MeshNode>` via [`CliContext::mesh_node`] for typed
//! clients (`RegistryClient` / `FoldQueryClient`) to route
//! through.

use std::net::SocketAddr;
use std::path::{Path, PathBuf};
use std::sync::Arc;
use std::time::Duration;

use net_sdk::deck::{DeckClient, OperatorIdentity};
use net_sdk::meshos::{EntityKeypair, LoggingDispatcher, MeshOsConfig, MeshOsDaemonSdk};

use crate::config::Profile;
use crate::error::{connection_failure, generic, invalid_args, sdk, CliError};
use crate::parsers::{hex_decode_32, parse_u64_flexible};
use crate::secret::{zeroize_string, ScrubbedBytes, ScrubbedString};

/// Resolved remote-attach target. Built from subcommand flags +
/// profile fallbacks via [`resolve_remote_attach`]. Carrying it
/// as a typed struct (rather than three optional strings) makes
/// the bootstrap path infallible — every field is validated at
/// resolve time.
#[derive(Debug, Clone)]
pub struct RemoteAttach {
    pub addr: SocketAddr,
    pub public_key: [u8; 32],
    pub node_id: u64,
    pub psk: [u8; 32],
}

/// Live substrate context wrapping the SDK + DeckClient.
pub struct CliContext {
    _sdk: MeshOsDaemonSdk,
    deck: Arc<DeckClient>,
    identity: OperatorIdentity,
    /// Connected `Mesh` when the context was built via
    /// [`CliContext::build_with_remote`]. `None` for in-process
    /// (read-local) subcommands. Holds the underlying UDP socket
    /// and receive loop alive for the lifetime of the context;
    /// `Mesh::node_arc()` hands out the `Arc<MeshNode>` typed
    /// clients (`RegistryClient` / `FoldQueryClient`) consume.
    mesh: Option<net_sdk::Mesh>,
}

impl CliContext {
    pub fn deck(&self) -> Arc<DeckClient> {
        Arc::clone(&self.deck)
    }

    pub fn identity(&self) -> &OperatorIdentity {
        &self.identity
    }

    /// Connected `MeshNode` for typed RPC clients. `None` when
    /// the context was built without a remote-attach target.
    /// Connected `Arc<MeshNode>` for typed RPC clients. Derived
    /// from the held `Mesh` so there's a single source of truth
    /// for the connection lifetime. `None` when the context was
    /// built without a remote-attach target. A-2 onward consumes
    /// this from the aggregator subcommands.
    #[allow(dead_code)]
    pub fn mesh_node(&self) -> Option<Arc<net_sdk::MeshNode>> {
        self.mesh.as_ref().map(|m| m.node_arc())
    }

    /// Connected `Mesh` handle for SDK surfaces that take `&Mesh`
    /// (the `net_sdk::transport` blob/dir helpers). `None` when the
    /// context was built without a remote-attach target. The
    /// transfer subcommands consume this — they run `serve_blob_transfer`
    /// then `fetch_blob` / `fetch_dir` through the same connected handle
    /// the aggregator RPC clients route through.
    pub fn mesh(&self) -> Option<&net_sdk::Mesh> {
        self.mesh.as_ref()
    }

    /// Like [`Self::mesh`] but returns a typed error when the context
    /// was built via [`Self::build`] (no remote attach). Transfer
    /// verbs that always connect to a holder call this so the
    /// "should be unreachable" branch isn't restated per call site.
    pub fn require_mesh(&self) -> Result<&net_sdk::Mesh, CliError> {
        self.mesh().ok_or_else(|| {
            crate::error::sdk(
                "internal: remote-attach context returned no mesh — \
                 build_with_remote always populates it, this should be unreachable",
            )
        })
    }

    /// Same as [`Self::mesh_node`] but returns a typed error when
    /// the context was built via [`Self::build`] instead of
    /// [`Self::build_with_remote`]. Subcommands that always
    /// remote-attach (`net-mesh aggregator query`/`spawn`/`scale`/
    /// `ls --remote`) call this rather than re-implementing the
    /// "should be unreachable" sdk-error per call site.
    #[allow(dead_code)]
    pub fn require_mesh_node(&self) -> Result<Arc<net_sdk::MeshNode>, CliError> {
        self.mesh_node().ok_or_else(|| {
            crate::error::sdk(
                "internal: remote-attach context returned no mesh — \
                 build_with_remote always populates it, this should be unreachable",
            )
        })
    }

    /// Build a fresh context. Resolves the operator identity
    /// from (in priority order): `identity_override`,
    /// `profile.identity`, an ephemeral random keypair (with a
    /// diagnostic warning on stderr).
    ///
    /// `require_identity = true` refuses the ephemeral-fallback
    /// path; the admin / ICE write surfaces pass this so a missing
    /// identity can't silently sign a commit with a throwaway key
    /// whose operator id no audit consumer will recognize.
    pub async fn build(
        profile: &Profile,
        identity_override: Option<&Path>,
        node_id: u64,
        require_identity: bool,
    ) -> Result<Self, CliError> {
        Self::build_inner(profile, identity_override, node_id, require_identity, None).await
    }

    /// Like [`Self::build`] but also handshakes with a remote
    /// daemon and exposes the connected `Arc<MeshNode>` via
    /// [`Self::mesh_node`]. Used by subcommands that route typed
    /// RPC clients (`RegistryClient` / `FoldQueryClient`) to a
    /// target node. A-2 onward consumes this from the
    /// aggregator subcommands.
    #[allow(dead_code)]
    pub async fn build_with_remote(
        profile: &Profile,
        identity_override: Option<&Path>,
        node_id: u64,
        require_identity: bool,
        remote: RemoteAttach,
    ) -> Result<Self, CliError> {
        Self::build_inner(
            profile,
            identity_override,
            node_id,
            require_identity,
            Some(remote),
        )
        .await
    }

    async fn build_inner(
        profile: &Profile,
        identity_override: Option<&Path>,
        node_id: u64,
        require_identity: bool,
        remote: Option<RemoteAttach>,
    ) -> Result<Self, CliError> {
        // Endpoint check — Phase 1 supports only in-process.
        if let Some(endpoint) = profile.endpoint.as_deref() {
            if endpoint != "in-process" {
                return Err(invalid_args(format!(
                    "endpoint `{endpoint}` is not supported in this build; \
                     only `in-process` is available until the substrate \
                     remote-attach surface lands"
                )));
            }
        }

        // Identity resolution. Generates an ephemeral one as a
        // last resort so read-only subcommands work without
        // ceremony; writes pass `require_identity = true` so the
        // ephemeral branch becomes a typed error instead of a
        // silent warn-and-proceed.
        let keypair = match identity_override.or(profile.identity.as_deref()) {
            Some(path) => load_identity_keypair(path).await?,
            None => {
                if require_identity {
                    return Err(invalid_args(
                        "no operator identity configured; pass --identity <PATH> \
                         or set `identity = \"...\"` under your profile in the \
                         config file. Admin / ICE commits refuse to sign with \
                         an ephemeral keypair.",
                    ));
                }
                tracing::warn!(
                    "no operator identity configured; using an ephemeral \
                     keypair. Run `net-mesh identity generate --out <PATH>` and \
                     point your profile at the result for stable operator id."
                );
                EntityKeypair::generate()
            }
        };

        let mut cfg = MeshOsConfig::default();
        cfg.this_node = node_id;
        cfg.tick_interval = Duration::from_millis(250);
        let dispatcher = Arc::new(LoggingDispatcher::new());

        let sdk = MeshOsDaemonSdk::start(cfg, dispatcher);
        let identity = OperatorIdentity::from_keypair(keypair);
        let deck = Arc::new(DeckClient::from_runtime(sdk.runtime(), identity.clone()));

        // Remote-attach branch: stand up a local ephemeral mesh
        // on 127.0.0.1:0, handshake with the target, start the
        // receive loop. The Mesh owns the socket + dispatch loop;
        // `mesh_node()` hands out the `Arc<MeshNode>` view typed
        // clients consume.
        let mesh = match remote {
            Some(remote) => Some(build_remote_mesh(remote).await?),
            None => None,
        };

        Ok(Self {
            _sdk: sdk,
            deck,
            identity,
            mesh,
        })
    }
}

/// Stand up a local ephemeral mesh that has handshaked with the
/// supplied remote target. Internal — used by
/// [`CliContext::build_with_remote`].
///
/// Uses [`net_sdk::Mesh::connect_via`] (routed handshake) rather
/// than the direct [`net_sdk::Mesh::connect`] path: direct
/// handshakes require the responder to pre-`accept(peer_node_id)`
/// before `start()` (mesh.rs:2409-2417 documents the gap), which
/// the daemon can't do for ephemeral CLI clients whose
/// `node_id` it doesn't know in advance. The routed path's
/// `handle_routed_handshake` Case 2 handles fresh msg1 from
/// new initiators against a running dispatch loop. The relay
/// hop is degenerate (relay == final dest == the daemon).
async fn build_remote_mesh(remote: RemoteAttach) -> Result<net_sdk::Mesh, CliError> {
    // In-process remote attach: loopback bind, ephemeral (anonymous) identity.
    build_attached_mesh("127.0.0.1:0", None, &remote).await
}

/// Build a local mesh bound to `bind`, optionally under an operator
/// `identity`, and join `remote` via the routed handshake. The single
/// implementation behind the in-process attach ([`build_remote_mesh`],
/// anonymous + loopback) and the `net-mesh wrap` / `net-mesh mcp serve` shims (which pass
/// their operator identity and bind `0.0.0.0:0` so the served / consumed
/// capabilities carry a stable, owner-scoped origin reachable by the peer).
pub(crate) async fn build_attached_mesh(
    bind: &str,
    identity: Option<net_sdk::identity::Identity>,
    remote: &RemoteAttach,
) -> Result<net_sdk::Mesh, CliError> {
    let mut builder = net_sdk::MeshBuilder::new(bind, &remote.psk)
        .map_err(|e| connection_failure(format!("mesh builder rejected bind address: {e}")))?;
    if let Some(id) = identity {
        builder = builder.identity(id);
    }
    let mesh = builder
        .build()
        .await
        .map_err(|e| connection_failure(format!("mesh build failed: {e}")))?;
    // `connect_via` registers a pending-initiator entry then
    // awaits msg2 from the dispatch loop, so start() must run
    // before the call — otherwise no consumer picks up msg2.
    mesh.start();
    mesh.connect_via(&remote.addr.to_string(), &remote.public_key, remote.node_id)
        .await
        .map_err(|e| {
            connection_failure(format!(
                "routed handshake with {} (node_id={}) failed: {e}",
                remote.addr, remote.node_id
            ))
        })?;
    Ok(mesh)
}

/// Resolve a [`RemoteAttach`] from subcommand-level flags +
/// profile fallbacks. Returns `Ok(Some(_))` when the operator
/// supplied (or has configured) at least one remote-attach
/// signal; `Ok(None)` when the call is in-process.
///
/// Validation is up-front: a partially-specified remote (e.g.
/// `--node-addr` without `--node-pubkey`) is a typed error
/// rather than a runtime handshake failure. A-2 onward consumes
/// this from the aggregator subcommands.
#[allow(dead_code)]
pub fn resolve_remote_attach(
    profile: &Profile,
    addr: Option<&str>,
    pubkey: Option<&str>,
    node_id: Option<&str>,
    psk_hex: Option<&str>,
) -> Result<Option<RemoteAttach>, CliError> {
    let addr_str = addr.or(profile.node_addr.as_deref());
    let pubkey_str = pubkey.or(profile.node_pubkey.as_deref());
    let node_id_str = node_id.or(profile.node_id.as_deref());
    let psk_str = psk_hex.or(profile.psk_hex.as_deref());

    let any_set =
        addr_str.is_some() || pubkey_str.is_some() || node_id_str.is_some() || psk_str.is_some();
    if !any_set {
        return Ok(None);
    }

    let addr_str = addr_str.ok_or_else(|| {
        invalid_args("remote-attach requires --node-addr (or `node_addr` in the profile)")
    })?;
    let pubkey_str = pubkey_str.ok_or_else(|| {
        invalid_args("remote-attach requires --node-pubkey (or `node_pubkey` in the profile)")
    })?;
    let node_id_str = node_id_str.ok_or_else(|| {
        invalid_args("remote-attach requires --node-id (or `node_id` in the profile)")
    })?;
    let psk_str = psk_str.ok_or_else(|| {
        invalid_args("remote-attach requires --psk-hex (or `psk_hex` in the profile)")
    })?;

    let addr: SocketAddr = addr_str.parse().map_err(|e| {
        invalid_args(format!(
            "--node-addr `{addr_str}` is not a valid IP:port: {e}"
        ))
    })?;
    let public_key =
        hex_decode_32(pubkey_str).map_err(|e| invalid_args(format!("--node-pubkey: {e}")))?;
    let node_id =
        parse_u64_flexible(node_id_str).map_err(|e| invalid_args(format!("--node-id: {e}")))?;
    let psk = hex_decode_32(psk_str).map_err(|e| invalid_args(format!("--psk-hex: {e}")))?;

    Ok(Some(RemoteAttach {
        addr,
        public_key,
        node_id,
        psk,
    }))
}

/// Resolve remote-attach to a concrete [`RemoteAttach`], or fail with
/// `missing` when no target is configured (flags + profile both empty).
/// Shared by every remote-only verb (`aggregator`, `transfer`, `typegen`)
/// so the resolve-then-require pattern lives in one place; `missing` lets
/// each command phrase its own "needs a target" guidance.
pub fn require_remote_attach(
    profile: &Profile,
    args: &crate::commands::aggregator::RemoteAttachArgs,
    missing: impl FnOnce() -> CliError,
) -> Result<RemoteAttach, CliError> {
    resolve_remote_attach(
        profile,
        args.node_addr.as_deref(),
        args.node_pubkey.as_deref(),
        args.remote_node_id.as_deref(),
        args.psk_hex.as_deref(),
    )?
    .ok_or_else(missing)
}

pub(crate) async fn load_identity_keypair(path: &Path) -> Result<EntityKeypair, CliError> {
    Ok(EntityKeypair::from_bytes(load_identity_seed(path).await?))
}

/// Load and validate the raw 32-byte seed from a `seed_hex = "..."` identity
/// TOML file. The one place the read + parse + hex-decode + length checks live,
/// shared by [`load_identity_keypair`] (→ `EntityKeypair`) and
/// [`load_operator_identity`] (→ `Identity`) so the two never drift.
pub(crate) async fn load_identity_seed(path: &Path) -> Result<[u8; 32], CliError> {
    // §10 — the READ side of the identity seed, shared by `net-mesh wrap`,
    // `net-mesh mcp serve` and `net-mesh cap`. Three separate copies of the private key
    // pass through here and all three used to drop un-zeroed: the whole file
    // text, the parsed `seed_hex`, and the decoded bytes. The write side was
    // hardened for §10; this side was not.
    let text = ScrubbedString::new(tokio::fs::read_to_string(path).await.map_err(|e| {
        generic(format!(
            "failed to read identity file {}: {e}",
            path.display()
        ))
    })?);
    // NEVER interpolate the parse error. `toml::de::Error`'s `Display` embeds
    // the offending SOURCE LINE, which for this file is `seed_hex = "..."` —
    // so a malformed identity file printed the operator's private key to
    // stderr. `org.rs` omits it for exactly this reason at both its parse
    // sites; this one did not.
    let mut parsed: PartialIdentityFile = toml::from_str(text.as_str()).map_err(|_| {
        invalid_args(format!(
            "identity file {} failed to parse as identity TOML",
            path.display()
        ))
    })?;
    let decoded = hex::decode(&parsed.seed_hex).map_err(|e| {
        invalid_args(format!(
            "identity file {} `seed_hex` is not valid hex: {e}",
            path.display()
        ))
    });
    // Scrub the parsed field before ANY early return below, including the
    // hex-decode failure.
    zeroize_string(&mut parsed.seed_hex);
    let seed_bytes = ScrubbedBytes::new(decoded?);
    if seed_bytes.as_slice().len() != 32 {
        return Err(invalid_args(format!(
            "identity file {} `seed_hex` decodes to {} bytes; expected 32",
            path.display(),
            seed_bytes.as_slice().len()
        )));
    }
    let mut arr = [0u8; 32];
    arr.copy_from_slice(seed_bytes.as_slice());
    Ok(arr)
}

/// Load an operator [`Identity`](net_sdk::identity::Identity) from an identity
/// TOML file. Shared by `net-mesh wrap` and `net-mesh mcp serve`, which build a mesh
/// under this identity so served / consumed capabilities carry a stable,
/// owner-scoped origin.
pub(crate) async fn load_operator_identity(
    path: &Path,
) -> Result<net_sdk::identity::Identity, CliError> {
    let seed = load_identity_seed(path).await?;
    net_sdk::identity::Identity::from_bytes(&seed).map_err(|e| {
        invalid_args(format!(
            "identity file {} `seed_hex` is not a valid 32-byte seed: {e:?}",
            path.display()
        ))
    })
}

#[derive(serde::Deserialize)]
struct PartialIdentityFile {
    seed_hex: String,
}

/// Resolve the active profile + identity path. Centralises the
/// `--identity` / `profile.identity` / env-var precedence so
/// subcommands don't reimplement it.
pub async fn resolve_profile(
    config_path: Option<&Path>,
    profile_name: &str,
) -> Result<Profile, CliError> {
    let file = crate::config::ConfigFile::load(config_path)
        .await
        .map_err(|e| sdk(format!("config load: {e}")))?;
    Ok(file.profile(profile_name))
}

#[allow(dead_code)]
pub fn resolved_identity_path(profile: &Profile, overide_: Option<&Path>) -> Option<PathBuf> {
    overide_
        .map(Path::to_path_buf)
        .or_else(|| profile.identity.clone())
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::error::ExitCodeKind;

    fn valid_pubkey() -> &'static str {
        "0101010101010101010101010101010101010101010101010101010101010101"
    }

    fn valid_psk() -> &'static str {
        "0x4242424242424242424242424242424242424242424242424242424242424242"
    }

    #[test]
    fn resolve_returns_none_when_nothing_set() {
        let profile = Profile::default();
        let out = resolve_remote_attach(&profile, None, None, None, None).unwrap();
        assert!(out.is_none());
    }

    #[test]
    fn resolve_pulls_full_target_from_flags() {
        let profile = Profile::default();
        let out = resolve_remote_attach(
            &profile,
            Some("127.0.0.1:51820"),
            Some(valid_pubkey()),
            Some("0x42"),
            Some(valid_psk()),
        )
        .unwrap()
        .expect("remote-attach resolved");
        assert_eq!(out.addr.port(), 51820);
        assert_eq!(out.node_id, 0x42);
        assert_eq!(out.public_key[0], 0x01);
        assert_eq!(out.psk[0], 0x42);
    }

    #[test]
    fn flags_override_profile_defaults() {
        let profile = Profile {
            node_addr: Some("10.0.0.1:1".into()),
            node_pubkey: Some(valid_pubkey().into()),
            node_id: Some("1".into()),
            psk_hex: Some(valid_psk().into()),
            ..Profile::default()
        };
        let out = resolve_remote_attach(&profile, Some("127.0.0.1:9999"), None, None, None)
            .unwrap()
            .expect("resolved");
        assert_eq!(out.addr.port(), 9999);
    }

    #[test]
    fn missing_pubkey_is_typed_invalid_args() {
        let profile = Profile::default();
        let err = resolve_remote_attach(
            &profile,
            Some("127.0.0.1:1"),
            None,
            Some("1"),
            Some(valid_psk()),
        )
        .expect_err("should reject partial remote spec");
        assert_eq!(err.kind(), ExitCodeKind::InvalidArgs);
    }

    #[test]
    fn bad_pubkey_length_is_typed_invalid_args() {
        let profile = Profile::default();
        let err = resolve_remote_attach(
            &profile,
            Some("127.0.0.1:1"),
            Some("0xaa"),
            Some("1"),
            Some(valid_psk()),
        )
        .expect_err("should reject short pubkey");
        assert_eq!(err.kind(), ExitCodeKind::InvalidArgs);
    }

    #[test]
    fn bad_addr_is_typed_invalid_args() {
        let profile = Profile::default();
        let err = resolve_remote_attach(
            &profile,
            Some("not-an-addr"),
            Some(valid_pubkey()),
            Some("1"),
            Some(valid_psk()),
        )
        .expect_err("should reject garbage addr");
        assert_eq!(err.kind(), ExitCodeKind::InvalidArgs);
    }
    /// §10 — a malformed identity file must not print the seed.
    ///
    /// `toml::de::Error`'s `Display` embeds the OFFENDING SOURCE LINE. For an
    /// identity file that line is `seed_hex = "<the operator's private key>"`,
    /// so interpolating the parse error into the CLI's stderr message leaked
    /// the key to the terminal, to CI logs, and to any shell that captured it.
    /// `org.rs` omits the error at both its parse sites for exactly this
    /// reason; this reader did not.
    #[tokio::test]
    async fn a_malformed_identity_file_never_echoes_the_seed() {
        let dir = tempfile::tempdir().expect("tempdir");
        let path = dir.path().join("operator.toml");
        // Valid TOML shape, but `seed_hex` is the wrong TYPE — enough to make
        // serde fail while quoting the offending line.
        let seed = "aa".repeat(32);
        std::fs::write(
            &path,
            format!("operator_id_hex = \"0x1\"\nseed_hex = [\"{seed}\"]\n"),
        )
        .expect("write");

        let err = load_identity_seed(&path)
            .await
            .expect_err("a malformed identity file must be refused");
        let rendered = format!("{err}");
        assert!(
            !rendered.contains(&seed),
            "the parse failure echoed the seed: {rendered}",
        );
        assert!(
            !rendered.contains("seed_hex"),
            "the parse failure quoted the seed_hex line, which carries the key \
             in a well-formed file: {rendered}",
        );
    }
}