libmoshpit 0.8.21

// Copyright (c) 2025 moshpit developers
//
// Licensed under the Apache License, Version 2.0
// <LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0> or the MIT
// license <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
// option. All files in the project carrying such notice may not be copied,
// modified, or distributed except according to those terms.

//! Core library powering the moshpit suite of tools ([`mp`], [`mps`], [`mpa`]).
//!
//! moshpit provides encrypted, resilient remote terminal sessions.  A client (`mp`) authenticates
//! to a server (`mps`) over TCP, then switches to an encrypted UDP channel for low-latency
//! terminal I/O that survives IP roaming, NAT rebinding, and short network outages.
//!
//! [`mp`]: https://github.com/rustyhorde/moshpit#moshpit-client-mp
//! [`mps`]: https://github.com/rustyhorde/moshpit#moshpits-server-mps
//! [`mpa`]: https://github.com/rustyhorde/moshpit#moshpit-agent-mpa
//!
//! # Connection model
//!
//! **Phase 1 — TCP key exchange**: the client opens a TCP connection and performs mutual
//! asymmetric-key authentication.  A per-session AEAD key is derived via KDF and the TCP
//! connection is closed.  See [`run_key_exchange`], [`Kex`], [`KexStateMachine`].
//!
//! **Phase 2 — UDP session**: all terminal I/O is encrypted with the negotiated AEAD cipher and
//! delivered over UDP.  The server maintains a full VT100 emulator state and sends a clean screen
//! snapshot on reconnect.  See [`UdpClient`], [`UdpSender`], [`UdpReader`], [`DiffMode`].
//!
//! # Cryptography
//!
//! All crypto goes through [`aws-lc-rs`](https://github.com/aws/aws-lc-rs) (no system OpenSSL).
//!
//! | Layer | Default | Alternatives |
//! |-------|---------|--------------|
//! | Identity key exchange | X25519 ([`KEX_X25519_SHA256`]) | P-384, P-256, ML-KEM-512/768/1024 |
//! | Session encryption (AEAD) | AES-256-GCM-SIV ([`AEAD_AES256_GCM_SIV`]) | AES-256-GCM, ChaCha20-Poly1305, AES-128-GCM-SIV |
//! | Frame authentication (MAC) | HMAC-SHA-512 ([`MAC_HMAC_SHA512`]) | HMAC-SHA-256 |
//! | Key derivation (KDF) | HKDF-SHA-256 ([`KDF_HKDF_SHA256`]) | HKDF-SHA-384, HKDF-SHA-512 |
//!
//! Algorithm negotiation follows SSH "first-match-wins" semantics ([`negotiate`]).
//!
//! # Wire protocol and framing
//!
//! Two bincode-serialized frame enums carry everything on the wire. [`Frame`]
//! (`frames/frame.rs`) is the TCP key-exchange message; [`EncryptedFrame`]
//! (`frames/encframe.rs`) is the payload of every encrypted UDP datagram. Each UDP
//! packet is laid out as `[nonce (12)] [seq (8)] [hmac tag] [length (8)]
//! [ciphertext]`; the sequence number is authenticated by the HMAC and reused as
//! the AEAD AAD, so a frame can be retransmitted verbatim without re-encryption.
//! See [`EncryptedFrame::parse`].
//!
//! Both peers advertise a [`ProtocolSupport`] range (min/max) in their
//! [`Frame::KexInit`] frame, and [`negotiate_protocol_version`] picks the highest
//! commonly supported [`PROTOCOL_VERSION`]. Any change to a [`Frame`] or
//! [`EncryptedFrame`] variant is a wire-format change: bump [`PROTOCOL_VERSION`]
//! (leaving [`MIN_PROTOCOL_VERSION`] in place so older peers still negotiate) and
//! gate the new behaviour on the negotiated value, reachable via
//! [`Kex::protocol_version`] / [`ServerKex::protocol_version`] — never on the
//! crate version. See `kex/negotiate.rs` for the full bump/retirement policy.
//!
//! # Terminal emulation and prediction
//!
//! The server runs a VT100 state machine ([`Emulator`]) on the PTY output and sends compressed
//! diffs to the client.  The client optionally renders predicted keystrokes ([`PredictionEngine`],
//! [`DisplayPreference`]) to eliminate perceived latency.
//!
//! # Key agent
//!
//! `mpa` is an optional key-agent daemon.  The [`agent`] module provides the Unix-socket
//! protocol types ([`AgentRequest`], [`AgentResponse`]) and an async client ([`AgentClient`])
//! that `mp` uses to delegate identity-key operations without reading key files directly.
//!
//! # Feature flags
//!
//! | Flag | Effect |
//! |------|--------|
//! | `unstable` | Enables ML-DSA post-quantum identity key support (`KEY_ALGORITHM_ML_DSA_44`, `KEY_ALGORITHM_ML_DSA_65`, `KEY_ALGORITHM_ML_DSA_87`) |

// rustc lints
#![cfg_attr(
    all(feature = "unstable", nightly),
    feature(
        multiple_supertrait_upcastable,
        must_not_suspend,
        non_exhaustive_omitted_patterns_lint,
        strict_provenance_lints,
        unqualified_local_imports,
    )
)]
#![cfg_attr(nightly, allow(single_use_lifetimes))]
#![cfg_attr(
    nightly,
    deny(
        absolute_paths_not_starting_with_crate,
        ambiguous_glob_imports,
        ambiguous_glob_reexports,
        ambiguous_negative_literals,
        ambiguous_wide_pointer_comparisons,
        anonymous_parameters,
        array_into_iter,
        asm_sub_register,
        async_fn_in_trait,
        bad_asm_style,
        bare_trait_objects,
        boxed_slice_into_iter,
        break_with_label_and_loop,
        clashing_extern_declarations,
        closure_returning_async_block,
        coherence_leak_check,
        confusable_idents,
        const_evaluatable_unchecked,
        const_item_mutation,
        dangling_pointers_from_temporaries,
        dead_code,
        dependency_on_unit_never_type_fallback,
        deprecated,
        deprecated_in_future,
        deprecated_safe_2024,
        deprecated_where_clause_location,
        deref_into_dyn_supertrait,
        deref_nullptr,
        double_negations,
        drop_bounds,
        dropping_copy_types,
        dropping_references,
        duplicate_macro_attributes,
        dyn_drop,
        edition_2024_expr_fragment_specifier,
        elided_lifetimes_in_paths,
        ellipsis_inclusive_range_patterns,
        explicit_outlives_requirements,
        exported_private_dependencies,
        ffi_unwind_calls,
        forbidden_lint_groups,
        forgetting_copy_types,
        forgetting_references,
        for_loops_over_fallibles,
        function_item_references,
        hidden_glob_reexports,
        if_let_rescope,
        impl_trait_overcaptures,
        impl_trait_redundant_captures,
        improper_ctypes,
        improper_ctypes_definitions,
        inline_no_sanitize,
        internal_features,
        invalid_from_utf8,
        invalid_macro_export_arguments,
        invalid_nan_comparisons,
        invalid_value,
        irrefutable_let_patterns,
        keyword_idents_2018,
        keyword_idents_2024,
        large_assignments,
        late_bound_lifetime_arguments,
        legacy_derive_helpers,
        let_underscore_drop,
        macro_use_extern_crate,
        map_unit_fn,
        meta_variable_misuse,
        mismatched_lifetime_syntaxes,
        missing_abi,
        missing_copy_implementations,
        missing_debug_implementations,
        missing_docs,
        missing_unsafe_on_extern,
        mixed_script_confusables,
        named_arguments_used_positionally,
        never_type_fallback_flowing_into_unsafe,
        no_mangle_generic_items,
        non_ascii_idents,
        non_camel_case_types,
        non_contiguous_range_endpoints,
        non_fmt_panics,
        non_local_definitions,
        non_shorthand_field_patterns,
        non_snake_case,
        non_upper_case_globals,
        noop_method_call,
        opaque_hidden_inferred_bound,
        out_of_scope_macro_calls,
        overlapping_range_endpoints,
        path_statements,
        private_bounds,
        private_interfaces,
        ptr_to_integer_transmute_in_consts,
        redundant_imports,
        redundant_lifetimes,
        redundant_semicolons,
        refining_impl_trait_internal,
        refining_impl_trait_reachable,
        renamed_and_removed_lints,
        repr_transparent_non_zst_fields,
        rust_2021_incompatible_closure_captures,
        rust_2021_incompatible_or_patterns,
        rust_2021_prefixes_incompatible_syntax,
        rust_2021_prelude_collisions,
        rust_2024_guarded_string_incompatible_syntax,
        rust_2024_incompatible_pat,
        rust_2024_prelude_collisions,
        self_constructor_from_outer_item,
        semicolon_in_expressions_from_macros,
        single_use_lifetimes,
        special_module_name,
        stable_features,
        static_mut_refs,
        suspicious_double_ref_op,
        tail_expr_drop_order,
        trivial_bounds,
        trivial_casts,
        trivial_numeric_casts,
        type_alias_bounds,
        tyvar_behind_raw_pointer,
        uncommon_codepoints,
        unconditional_recursion,
        uncovered_param_in_projection,
        unexpected_cfgs,
        unfulfilled_lint_expectations,
        ungated_async_fn_track_caller,
        uninhabited_static,
        unit_bindings,
        unknown_lints,
        unknown_or_malformed_diagnostic_attributes,
        unnameable_test_items,
        unnameable_types,
        unpredictable_function_pointer_comparisons,
        unreachable_code,
        unreachable_patterns,
        unreachable_pub,
        unsafe_attr_outside_unsafe,
        unsafe_code,
        unsafe_op_in_unsafe_fn,
        unstable_name_collisions,
        unstable_syntax_pre_expansion,
        unused_allocation,
        unused_assignments,
        unused_associated_type_bounds,
        unused_attributes,
        unused_braces,
        unused_comparisons,
        unused_crate_dependencies,
        unused_doc_comments,
        unused_extern_crates,
        unused_features,
        unused_import_braces,
        unused_imports,
        unused_labels,
        unused_lifetimes,
        unused_macro_rules,
        unused_macros,
        unused_must_use,
        unused_mut,
        unused_parens,
        unused_qualifications,
        unused_results,
        unused_unsafe,
        unused_variables,
        useless_ptr_null_checks,
        uses_power_alignment,
        variant_size_differences,
        while_true,
    )
)]
// If nightly and unstable, allow `incomplete_features` and `unstable_features`
#![cfg_attr(
    all(feature = "unstable", nightly),
    allow(incomplete_features, unstable_features)
)]
// If nightly and not unstable, deny `incomplete_features` and `unstable_features`
#![cfg_attr(
    all(not(feature = "unstable"), nightly),
    deny(incomplete_features, unstable_features)
)]
// The unstable lints
#![cfg_attr(
    all(feature = "unstable", nightly),
    deny(
        fuzzy_provenance_casts,
        lossy_provenance_casts,
        multiple_supertrait_upcastable,
        must_not_suspend,
        non_exhaustive_omitted_patterns,
        unqualified_local_imports,
    )
)]
// Allow unsafe code on Windows (required for Windows Security API calls)
#![cfg_attr(all(nightly, windows), allow(unsafe_code, unsafe_op_in_unsafe_fn))]
// clippy lints
#![cfg_attr(nightly, deny(clippy::all, clippy::pedantic))]
// rustdoc lints
#![cfg_attr(
    nightly,
    deny(
        rustdoc::bare_urls,
        rustdoc::broken_intra_doc_links,
        rustdoc::invalid_codeblock_attributes,
        rustdoc::invalid_html_tags,
        rustdoc::missing_crate_level_docs,
        rustdoc::private_doc_tests,
        rustdoc::private_intra_doc_links,
    )
)]
#![cfg_attr(all(docsrs), feature(doc_cfg))]
#![cfg_attr(coverage_nightly, feature(coverage_attribute))]

pub mod agent;
mod config;
mod error;
mod frames;
mod kex;
mod keygen;
mod session;
mod tcp;
mod term;
mod tracing;
mod udp;
mod utils;
mod uuid;

#[cfg(unix)]
pub use self::agent::AgentClient;
pub use self::agent::AgentIdentityInfo;
pub use self::agent::AgentRequest;
pub use self::agent::AgentResponse;
pub use self::config::KexConfig;
pub use self::config::PathDefaults;
pub use self::config::config_file_path;
pub use self::config::load;
pub use self::config::mps::Mps;
pub use self::config::tracing::FileLayer;
pub use self::config::tracing::Layer;
pub use self::config::tracing::Tracing;
pub use self::error::Error as MoshpitError;
pub use self::error::clap_or_error;
pub use self::error::success;
pub use self::frames::encframe::EncryptedFrame;
pub use self::frames::frame::Frame;
pub use self::kex::HostKeyMismatchFn;
pub use self::kex::Kex;
pub use self::kex::KexEvent;
pub use self::kex::KexMode;
pub use self::kex::KexState;
pub use self::kex::KexStateMachine;
pub use self::kex::ServerKex;
pub use self::kex::TofuFn;
pub use self::kex::env_var_matches;
pub use self::kex::negotiate::AEAD_AES128_GCM_SIV;
pub use self::kex::negotiate::AEAD_AES256_GCM;
pub use self::kex::negotiate::AEAD_AES256_GCM_SIV;
pub use self::kex::negotiate::AEAD_CHACHA20_POLY1305;
pub use self::kex::negotiate::AlgorithmList;
pub use self::kex::negotiate::KDF_HKDF_SHA256;
pub use self::kex::negotiate::KDF_HKDF_SHA384;
pub use self::kex::negotiate::KDF_HKDF_SHA512;
pub use self::kex::negotiate::KEX_ML_KEM_512_SHA256;
pub use self::kex::negotiate::KEX_ML_KEM_768_SHA256;
pub use self::kex::negotiate::KEX_ML_KEM_1024_SHA256;
pub use self::kex::negotiate::KEX_P256_SHA256;
pub use self::kex::negotiate::KEX_P384_SHA384;
pub use self::kex::negotiate::KEX_X25519_SHA256;
pub use self::kex::negotiate::MAC_HMAC_SHA256;
pub use self::kex::negotiate::MAC_HMAC_SHA512;
pub use self::kex::negotiate::MIN_PROTOCOL_VERSION;
pub use self::kex::negotiate::NegotiatedAlgorithms;
pub use self::kex::negotiate::PROTOCOL_VERSION;
pub use self::kex::negotiate::ProtocolSupport;
pub use self::kex::negotiate::local_protocol_support;
pub use self::kex::negotiate::negotiate;
pub use self::kex::negotiate::negotiate_protocol_version;
pub use self::kex::negotiate::supported_algorithms;
pub use self::kex::reader::KexReader;
pub use self::kex::run_key_exchange;
pub use self::kex::sender::KexSender;
pub use self::keygen::AEADCipher;
pub use self::keygen::EncryptedKeyPair;
pub use self::keygen::IdentityKeyPair;
#[cfg(feature = "unstable")]
pub use self::keygen::KEY_ALGORITHM_ML_DSA_44;
#[cfg(feature = "unstable")]
pub use self::keygen::KEY_ALGORITHM_ML_DSA_65;
#[cfg(feature = "unstable")]
pub use self::keygen::KEY_ALGORITHM_ML_DSA_87;
pub use self::keygen::KEY_ALGORITHM_P256;
pub use self::keygen::KEY_ALGORITHM_P384;
pub use self::keygen::KEY_ALGORITHM_X25519;
pub use self::keygen::KeyPair;
pub use self::keygen::UnencryptedKeyPair;
pub use self::keygen::decrypt_private_key;
pub use self::keygen::load_identity_key;
pub use self::keygen::load_private_key;
pub use self::keygen::load_public_key;
pub use self::keygen::pk::extract_public_key_bytes;
pub use self::keygen::pk::fingerprint;
pub use self::keygen::pk::randomart;
pub use self::keygen::pk::verify_fingerprint;
pub use self::keygen::validate_identity_key_pair;
pub use self::session::SessionRegistry;
pub use self::session::new_session_registry;
pub use self::tcp::reader::ConnectionReader;
pub use self::tcp::writer::ConnectionWriter;
pub use self::term::TerminalMessage;
pub use self::term::{
    DisplayPreference, Emulator, OverlayCell, OverlayCursor, PredictionEngine, Renderer,
    paint_overlays_to_ansi, render_prediction_update, render_server_update,
};
pub use self::tracing::{TracingConfigExt, init_tracing};
pub use self::udp::DiffMode;
pub use self::udp::UdpClient;
pub use self::udp::reader::{ClientRenderCtx, UdpReader};
pub use self::udp::sender::MAX_UDP_PAYLOAD;
pub use self::udp::sender::UdpSender;
pub use self::utils::is_exit_title;
pub use self::utils::parse_server_destination;
pub use self::utils::to_path_buf;
pub use self::uuid::UuidWrapper;