librats 1.0.2 → 2.2.0

package/native-src/src/librats/peer/peer_table.h

@@ -0,0 +1,148 @@
+#pragma once
+
+/**
+ * @file peer_table.h
+ * @brief Control-plane registry: PeerId → route + metadata.
+ *
+ * This is the only shared peer structure in the redesign, and it is deliberately
+ * **off the per-byte data path**: it is touched on connect/disconnect and on
+ * explicit by-id lookups (send-by-id, peers()), never per inbound/outbound frame
+ * (those use the route carried in the Connection/Peer handle). It is therefore
+ * read-mostly and guarded by a shared_mutex with short critical sections — a
+ * world away from the old global peers_mutex_ held across recv/send.
+ */
+
+#include "librats/util/rats_export.h"
+#include "librats/core/types.h"   // ConnId
+#include "librats/peer/peer_id.h"
+#include "librats/peer/peer_info.h"
+
+#include <atomic>
+#include <cstdint>
+#include <memory>
+#include <optional>
+#include <shared_mutex>
+#include <unordered_map>
+#include <vector>
+
+namespace librats {
+
+/// Where a peer's live connection lives: which reactor owns it, and its ConnId.
+/// (reactor, conn) identifies a connection globally and is never reused while it
+/// is alive, so it is the stable key for matching a teardown to a directory entry.
+struct PeerRoute {
+    uint8_t reactor = 0;
+    ConnId  conn    = kInvalidConnId;
+
+    bool operator==(const PeerRoute& o) const noexcept { return reactor == o.reactor && conn == o.conn; }
+    bool operator!=(const PeerRoute& o) const noexcept { return !(*this == o); }
+};
+
+class RATS_API PeerTable {
+public:
+    enum class AddResult {
+        NewPeer,   ///< First connection to this peer — caller should fire "connected".
+        Updated,   ///< Same connection re-registered; metadata refreshed only.
+        Replaced,  ///< A previous connection was superseded (`close` holds its route).
+        Rejected,  ///< An existing connection was kept; the new one (`close`) must close.
+    };
+    struct AddOutcome {
+        AddResult                result = AddResult::NewPeer;
+        std::optional<PeerRoute> close;  ///< Loser of a duplicate race; tear it down.
+    };
+
+    /// Register a connection for a peer, resolving duplicates deterministically.
+    /// Both ends resolve the same pair of connections independently, so each rule
+    /// reads only what looks identical from either side — never arrival order:
+    ///   - opposite roles ⇒ a simultaneous cross-connect. `prefer_outbound` (which
+    ///     BOTH peers compute identically from a symmetric rule over their ids)
+    ///     picks the surviving link, so both converge on the same one.
+    ///   - same role, different transports ⇒ a dial race whose attempts both got
+    ///     through; the datagram link wins at both ends.
+    ///   - same role and transport ⇒ a reconnect, so the newcomer wins.
+    /// Taken together these are a total order, mirrored at the two ends, which is
+    /// what makes the verdict independent of the order connections arrive in. See
+    /// peer_table.cpp for why each rule is the one it is.
+    /// The loser's route is returned in `close`. Write lock.
+    AddOutcome add(const PeerInfo& info, PeerRoute route, bool prefer_outbound);
+
+    /// Drop a peer, but only if its current route matches `route` — so a stale
+    /// connection's teardown cannot evict a newer one that replaced it. Write lock.
+    /// Returns true iff an entry was actually removed.
+    bool remove(const PeerId& id, PeerRoute route);
+
+    /// Route to a peer's live connection, if connected. Read lock.
+    std::optional<PeerRoute> route(const PeerId& id) const;
+
+    /// Merge dialable addresses into a peer's metadata, de-duplicated and bounded
+    /// to kMaxAddressesPerPeer. Applies only if `route` is still the peer's live
+    /// route (a stale connection's late identify cannot mutate a newer link).
+    /// Returns the addresses actually added (i.e. not already known). Write lock.
+    std::vector<Address> add_addresses(const PeerId& id, PeerRoute route,
+                                       const std::vector<Address>& addresses);
+
+    /// Record which transports a peer advertised in its identify message. Applies
+    /// only while `route` is still the peer's live route. Write lock.
+    void set_supported_transports(const PeerId& id, PeerRoute route, uint8_t mask);
+
+    /// A peer's live route together with whether its send queue has room, in one
+    /// lookup — the send path needs both and should not pay for two.
+    struct Destination {
+        PeerRoute route;
+        bool      writable = true;
+        /// The peer's in-transit counter (see Entry::owed). Shared, not copied,
+        /// so the caller charges the same counter the reactor task discharges.
+        std::shared_ptr<std::atomic<size_t>> owed;
+    };
+    std::optional<Destination> destination(const PeerId& id) const;
+
+    /// Whether every connected peer's send queue has room — what broadcast()
+    /// answers, since "may I send more?" to a fan-out is only usefully answered
+    /// by its slowest recipient.
+    bool all_writable() const;
+
+    /// Record that a peer's send queue filled up or drained. Applies only while
+    /// `route` is still the peer's live route. Write lock, but only ever taken
+    /// when the mark is actually crossed, which is rare.
+    void set_writable(const PeerId& id, PeerRoute route, bool writable);
+
+    /// Upper bound on stored addresses per peer — caps memory and stops a peer
+    /// from flooding us with bogus addresses via the identify/PEX path.
+    static constexpr size_t kMaxAddressesPerPeer = 32;
+
+    /// Metadata snapshot for a peer. Read lock.
+    std::optional<PeerInfo> info(const PeerId& id) const;
+
+    bool contains(const PeerId& id) const;
+
+    /// Snapshot of all known peers (for the public API / persistence). Read lock.
+    std::vector<PeerInfo> snapshot() const;
+
+    size_t size() const noexcept { return count_.load(std::memory_order_relaxed); }
+
+private:
+    struct Entry {
+        PeerInfo  info;
+        PeerRoute route;
+        /// Whether this peer's send queue has room. Maintained by the reactor as
+        /// the queue crosses its low-water mark, read by send() so a caller on
+        /// any thread gets an answer without having to reach into a connection it
+        /// does not own. Advisory by nature — it is a snapshot of a queue that is
+        /// draining as it is read, which is exactly what a backpressure hint is.
+        bool      writable = true;
+        /// Bytes handed to the owning reactor by send() that it has not taken up
+        /// yet. The queue itself lives on the reactor thread and `writable` above
+        /// only ever reports what the reactor has already seen — so a caller in a
+        /// tight loop could hand over megabytes before a single one of them was
+        /// counted. This is that backlog, incremented by the caller and decremented
+        /// by the reactor task, so the answer covers both halves.
+        std::shared_ptr<std::atomic<size_t>> owed =
+            std::make_shared<std::atomic<size_t>>(0);
+    };
+
+    mutable std::shared_mutex mutex_;
+    std::unordered_map<PeerId, Entry, PeerId::Hash> peers_;
+    std::atomic<size_t> count_{0};
+};
+
+} // namespace librats

package/native-src/src/librats/security/handshaker.h

@@ -0,0 +1,66 @@
+#pragma once
+
+/**
+ * @file handshaker.h
+ * @brief Secure-channel handshake driver and the provider that creates one.
+ *
+ * A Handshaker is fed handshake messages until it yields a Session and the
+ * remote PeerId (or fails). It is transport-agnostic: the Connection frames its
+ * `out` bytes as Handshake frames and feeds inbound Handshake payloads back in.
+ *
+ * A SecurityProvider configures the whole node (one keypair / policy) and mints
+ * a fresh Handshaker per connection. Swapping NoiseSecurity ⇄ PlaintextSecurity
+ * changes the entire security posture without touching the transport.
+ */
+
+#include "librats/util/rats_export.h"
+#include "librats/core/bytes.h"
+#include "librats/core/types.h"   // ConnRole
+#include "librats/peer/peer_id.h"
+#include "librats/security/session.h"
+
+#include <memory>
+#include <string>
+
+namespace librats {
+
+/// Canonical bytes identifying an application protocol. Bound into the handshake
+/// — as the Noise prologue, or exchanged-and-checked in the plaintext handshake —
+/// so peers whose protocol differs cannot connect. The protocol string is an
+/// opaque identity compared for exact equality; by convention it is "<name>/
+/// <version>" (e.g. "librats/1.0"), but any difference at all is a distinct
+/// protocol. A fixed context tag namespaces it away from other prologue uses.
+inline std::string protocol_id(const std::string& protocol) {
+    return std::string("librats-proto\x1f", 14) + protocol;  // tag + opaque id
+}
+
+class RATS_API Handshaker {
+public:
+    struct Outcome {
+        enum Status { NeedMore, Done, Failed } status = NeedMore;
+        std::unique_ptr<Session> session;   ///< valid iff status == Done
+        PeerId                   remote_id; ///< valid iff status == Done
+    };
+
+    virtual ~Handshaker() = default;
+
+    /// Called once when the transport is up. Appends the initial message, if
+    /// any (e.g. the initiator's first Noise message), to `out`. False on error.
+    virtual bool start(Bytes& out) = 0;
+
+    /// Consume one received handshake message; append any reply to `out`.
+    virtual Outcome consume(ByteView incoming, Bytes& out) = 0;
+};
+
+class RATS_API SecurityProvider {
+public:
+    virtual ~SecurityProvider() = default;
+
+    /// Create a handshaker for a new connection in the given role.
+    virtual std::unique_ptr<Handshaker> create(ConnRole role) = 0;
+
+    /// This node's own identity.
+    virtual const PeerId& local_id() const = 0;
+};
+
+} // namespace librats

package/native-src/src/librats/security/identity.h

@@ -0,0 +1,43 @@
+#pragma once
+
+/**
+ * @file identity.h
+ * @brief A node's cryptographic identity: a static keypair and its derived PeerId.
+ *
+ * The PeerId is SHA-256 of the static public key, so identity travels with the
+ * key. Generate a fresh identity for an ephemeral node, or rebuild one from a
+ * persisted private key to keep a stable PeerId across restarts.
+ */
+
+#include "librats/util/rats_export.h"
+#include "librats/peer/peer_id.h"
+#include "librats/crypto/noise.h"
+
+#include <cstring>
+
+namespace librats {
+
+struct RATS_API Identity {
+    librats::NoiseKeyPair static_keypair;
+    PeerId             id;
+
+    /// Create a brand-new random identity.
+    static Identity generate() {
+        Identity ident;
+        librats::noise_generate_keypair(ident.static_keypair);
+        ident.id = PeerId::from_public_key(ident.static_keypair.public_key, librats::NOISE_DH_SIZE);
+        return ident;
+    }
+
+    /// Rebuild a stable identity from a persisted 32-byte private key.
+    static Identity from_private_key(const uint8_t private_key[librats::NOISE_DH_SIZE]) {
+        Identity ident;
+        std::memcpy(ident.static_keypair.private_key, private_key, librats::NOISE_DH_SIZE);
+        librats::noise_derive_public_key(private_key, ident.static_keypair.public_key);
+        ident.static_keypair.has_keys = true;
+        ident.id = PeerId::from_public_key(ident.static_keypair.public_key, librats::NOISE_DH_SIZE);
+        return ident;
+    }
+};
+
+} // namespace librats

package/native-src/src/librats/security/noise_security.cpp

@@ -0,0 +1,122 @@
+#include "librats/security/noise_security.h"
+#include "librats/crypto/noise.h"
+#include "librats/util/logger.h"
+
+namespace librats {
+namespace {
+
+// Human-readable Noise failure reason for handshake diagnostics. Kept local: the
+// crypto layer deliberately exposes only the enum, and this is its sole logger.
+const char* noise_error_name(librats::NoiseError e) {
+    switch (e) {
+        case librats::NoiseError::OK:                         return "ok";
+        case librats::NoiseError::INVALID_STATE:              return "invalid-state";
+        case librats::NoiseError::DECRYPT_FAILED:             return "decrypt-failed";
+        case librats::NoiseError::MESSAGE_TOO_LARGE:          return "message-too-large";
+        case librats::NoiseError::HANDSHAKE_NOT_COMPLETE:     return "handshake-not-complete";
+        case librats::NoiseError::HANDSHAKE_ALREADY_COMPLETE: return "handshake-already-complete";
+        case librats::NoiseError::INVALID_KEY:                return "invalid-key";
+        case librats::NoiseError::INTERNAL_ERROR:             return "internal-error";
+    }
+    return "unknown";
+}
+
+/// Session backed by a completed librats::NoiseSession (owns its transport ciphers).
+class NoiseSessionAdapter final : public Session {
+public:
+    NoiseSessionAdapter(std::unique_ptr<librats::NoiseSession> session, PeerId remote)
+        : session_(std::move(session)), remote_id_(remote) {}
+
+    bool encrypt(ByteView plain, Bytes& out) override {
+        out.resize(plain.size() + librats::NOISE_TAG_SIZE);
+        const size_t n = session_->encrypt(plain.data(), plain.size(), out.data());
+        if (n == 0 && plain.size() != 0) return false;
+        out.resize(n);
+        return true;
+    }
+
+    bool decrypt(ByteView cipher, Bytes& out) override {
+        if (cipher.size() < librats::NOISE_TAG_SIZE) return false;
+        out.resize(cipher.size());  // plaintext is always shorter than ciphertext
+        const size_t n = session_->decrypt(cipher.data(), cipher.size(), out.data());
+        if (n == librats::NOISE_DECRYPT_FAILED) return false;  // 0 is a valid (empty) frame
+        out.resize(n);
+        return true;
+    }
+
+    const PeerId& remote_id() const override { return remote_id_; }
+    bool is_secure() const override { return true; }
+
+private:
+    std::unique_ptr<librats::NoiseSession> session_;
+    PeerId                              remote_id_;
+};
+
+/// Drives the Noise XX message exchange via librats::NoiseSession::handshake_step.
+class NoiseHandshaker final : public Handshaker {
+public:
+    NoiseHandshaker(const Identity& identity, bool initiator, ByteView prologue)
+        : session_(std::make_unique<librats::NoiseSession>()), initiator_(initiator) {
+        session_->start(initiator, &identity.static_keypair,
+                        prologue.empty() ? nullptr : prologue.data(), prologue.size());
+    }
+
+    bool start(Bytes& out) override {
+        if (!initiator_) return true;     // responder waits for the first message
+        return step(nullptr, 0, out);
+    }
+
+    Outcome consume(ByteView incoming, Bytes& out) override {
+        Outcome oc;
+        if (!step(incoming.data(), incoming.size(), out)) {
+            oc.status = Outcome::Failed;
+            return oc;
+        }
+        if (session_->is_handshake_complete()) {
+            oc.remote_id = PeerId::from_public_key(session_->get_remote_static_public(),
+                                                   librats::NOISE_DH_SIZE);
+            oc.session   = std::make_unique<NoiseSessionAdapter>(std::move(session_), oc.remote_id);
+            oc.status    = Outcome::Done;
+        }
+        return oc;
+    }
+
+private:
+    // Run one handshake step; append the outgoing message (if any) to `out`.
+    bool step(const uint8_t* received, size_t received_len, Bytes& out) {
+        // A Noise transport message is capped at 65535 bytes; reject anything
+        // larger before it reaches the state machine. Defense in depth: the
+        // block layer admits frames up to kMaxBlockSize (64 MB), so without
+        // this an oversized handshake frame would be fed straight in.
+        if (received_len > librats::NOISE_MAX_MESSAGE_SIZE) {
+            LOG_DEBUG("noise", "Rejecting oversized handshake message (" << received_len << " B)");
+            return false;
+        }
+
+        uint8_t buffer[librats::NOISE_MAX_MESSAGE_SIZE];
+        size_t  len = sizeof(buffer);
+        bool    need_to_send = false;
+        const auto err = session_->handshake_step(received, received_len, buffer, &len, &need_to_send);
+        if (err != librats::NoiseError::OK) {
+            LOG_DEBUG("noise", "Handshake step failed: " << noise_error_name(err)
+                      << " (" << (initiator_ ? "initiator" : "responder") << ")");
+            return false;
+        }
+        if (need_to_send) out.insert(out.end(), buffer, buffer + len);
+        return true;
+    }
+
+    std::unique_ptr<librats::NoiseSession> session_;
+    bool                                initiator_;
+};
+
+} // namespace
+
+NoiseSecurity::NoiseSecurity(Identity identity, std::string protocol)
+    : identity_(identity), prologue_(protocol_id(protocol)) {}
+
+std::unique_ptr<Handshaker> NoiseSecurity::create(ConnRole role) {
+    return std::make_unique<NoiseHandshaker>(identity_, role == ConnRole::Outbound, ByteView(prologue_));
+}
+
+} // namespace librats

package/native-src/src/librats/security/noise_security.h

@@ -0,0 +1,37 @@
+#pragma once
+
+/**
+ * @file noise_security.h
+ * @brief Noise_XX_25519_ChaChaPoly_SHA256 secure channel with self-certifying ids.
+ *
+ * Wraps the existing librats::NoiseSession (src/noise.h) behind the
+ * SecurityProvider/Handshaker/Session contract. The XX pattern mutually
+ * authenticates both static keys, and each side derives the other's PeerId from
+ * the static key it proved — so a completed handshake is also identity proof.
+ */
+
+#include "librats/util/rats_export.h"
+#include "librats/security/handshaker.h"
+#include "librats/security/identity.h"
+
+#include <memory>
+#include <string>
+
+namespace librats {
+
+class RATS_API NoiseSecurity final : public SecurityProvider {
+public:
+    /// @param protocol Application protocol id, bound into the Noise handshake
+    ///        prologue. Peers whose protocol differs cannot complete a handshake
+    ///        — cross-application isolation, enforced cryptographically (a
+    ///        mismatch fails the handshake MAC). By convention "<name>/<version>".
+    explicit NoiseSecurity(Identity identity, std::string protocol = "librats/1.0");
+    std::unique_ptr<Handshaker> create(ConnRole role) override;
+    const PeerId& local_id() const override { return identity_.id; }
+
+private:
+    Identity    identity_;
+    std::string prologue_;  ///< length-prefixed name+version, mixed into every handshake
+};
+
+} // namespace librats

package/native-src/src/librats/security/plaintext_security.h

@@ -0,0 +1,106 @@
+#pragma once
+
+/**
+ * @file plaintext_security.h
+ * @brief Unencrypted "secure channel": exchanges PeerIds, encrypts nothing.
+ *
+ * Useful for local/testing setups and as the trivial reference implementation
+ * of the SecurityProvider/Handshaker/Session contract. The handshake exchanges
+ * one message each way carrying the protocol id and the PeerId; the resulting
+ * Session is a passthrough. Note the identity here is NOT authenticated (no key
+ * proof) — that is the inherent trade-off of running without encryption.
+ *
+ * The protocol id is still checked (so two apps with different protocol can't
+ * cross-connect even unencrypted), but unlike the Noise prologue it is not
+ * cryptographically bound — a plaintext peer can claim any protocol. That is
+ * acceptable for the plaintext mode's trusted/testing use cases.
+ *
+ * Handshake message: [proto_len:u16][protocol id][peer id: 32 bytes].
+ */
+
+#include "librats/security/handshaker.h"
+#include "librats/security/identity.h"
+
+#include <cstring>
+#include <memory>
+#include <string>
+
+namespace librats {
+
+/// Passthrough session: encrypt/decrypt just copy the bytes.
+class PlaintextSession final : public Session {
+public:
+    explicit PlaintextSession(PeerId remote) : remote_id_(remote) {}
+    bool encrypt(ByteView plain, Bytes& out) override { out.assign(plain.begin(), plain.end()); return true; }
+    bool decrypt(ByteView cipher, Bytes& out) override { out.assign(cipher.begin(), cipher.end()); return true; }
+    const PeerId& remote_id() const override { return remote_id_; }
+    bool is_secure() const override { return false; }
+private:
+    PeerId remote_id_;
+};
+
+/// One-message-each exchange of [protocol id][PeerId].
+class PlaintextHandshaker final : public Handshaker {
+public:
+    PlaintextHandshaker(PeerId local, bool initiator, std::string proto)
+        : local_(local), proto_(std::move(proto)), initiator_(initiator) {}
+
+    bool start(Bytes& out) override {
+        if (initiator_) append_message(out);  // initiator announces first
+        return true;
+    }
+
+    Outcome consume(ByteView incoming, Bytes& out) override {
+        Outcome oc;
+        const uint8_t* p = incoming.data();
+        const size_t   n = incoming.size();
+        if (n < 2) { oc.status = Outcome::Failed; return oc; }
+
+        const size_t proto_len = (static_cast<size_t>(p[0]) << 8) | p[1];
+        if (n < 2 + proto_len + PeerId::kSize) { oc.status = Outcome::Failed; return oc; }
+
+        // Reject a peer announcing a different protocol id.
+        if (proto_len != proto_.size() ||
+            std::memcmp(p + 2, proto_.data(), proto_len) != 0) {
+            oc.status = Outcome::Failed;
+            return oc;
+        }
+
+        auto remote = PeerId::from_bytes(ByteView(p + 2 + proto_len, PeerId::kSize));
+        if (!remote) { oc.status = Outcome::Failed; return oc; }
+
+        if (!initiator_) append_message(out);  // responder replies
+        oc.status    = Outcome::Done;
+        oc.remote_id = *remote;
+        oc.session   = std::make_unique<PlaintextSession>(*remote);
+        return oc;
+    }
+
+private:
+    void append_message(Bytes& out) {
+        out.push_back(static_cast<uint8_t>((proto_.size() >> 8) & 0xFF));
+        out.push_back(static_cast<uint8_t>(proto_.size() & 0xFF));
+        out.insert(out.end(), proto_.begin(), proto_.end());
+        const auto& b = local_.bytes();
+        out.insert(out.end(), b.begin(), b.end());
+    }
+
+    PeerId      local_;
+    std::string proto_;
+    bool        initiator_;
+};
+
+class PlaintextSecurity final : public SecurityProvider {
+public:
+    explicit PlaintextSecurity(Identity identity, std::string protocol = "librats/1.0")
+        : identity_(identity), proto_(protocol_id(protocol)) {}
+    std::unique_ptr<Handshaker> create(ConnRole role) override {
+        return std::make_unique<PlaintextHandshaker>(identity_.id, role == ConnRole::Outbound, proto_);
+    }
+    const PeerId& local_id() const override { return identity_.id; }
+private:
+    Identity    identity_;
+    std::string proto_;
+};
+
+} // namespace librats

package/native-src/src/librats/security/session.h

@@ -0,0 +1,37 @@
+#pragma once
+
+/**
+ * @file session.h
+ * @brief Post-handshake symmetric session: encrypts/decrypts transport frames.
+ *
+ * A Session is produced by a Handshaker once the secure channel is established.
+ * The Connection holds it and runs every outbound frame through encrypt() and
+ * every inbound frame through decrypt(). The plaintext mode supplies a
+ * passthrough Session so the Connection code path is identical with or without
+ * encryption — no `if (encrypted)` scattered through the hot path.
+ */
+
+#include "librats/util/rats_export.h"
+#include "librats/core/bytes.h"
+#include "librats/peer/peer_id.h"
+
+namespace librats {
+
+class RATS_API Session {
+public:
+    virtual ~Session() = default;
+
+    /// Encrypt `plain` into `out` (resized to fit). Returns false on failure.
+    virtual bool encrypt(ByteView plain, Bytes& out) = 0;
+
+    /// Decrypt `cipher` into `out` (resized to fit). Returns false on failure.
+    virtual bool decrypt(ByteView cipher, Bytes& out) = 0;
+
+    /// The remote peer's identity, proven during the handshake.
+    virtual const PeerId& remote_id() const = 0;
+
+    /// True if traffic is actually encrypted (false for the plaintext passthrough).
+    virtual bool is_secure() const = 0;
+};
+
+} // namespace librats