@sourceregistry/node-wireguard 1.0.0

package/src/WireGuardClient.h

@@ -0,0 +1,32 @@
+#pragma once
+
+#include "netlink/NlSocket.h"
+
+#include <memory>
+#include <napi.h>
+
+// N-API class mirroring wgctrl-go's *wgctrl.Client, extended with interface
+// lifecycle (createDevice/deleteDevice) since this addon — unlike wgctrl-go —
+// also owns creating/destroying the WireGuard link itself (see plan decision:
+// "full lifecycle"). One instance owns one genetlink socket for its lifetime.
+class WireGuardClient : public Napi::ObjectWrap<WireGuardClient> {
+public:
+    static Napi::Object Init(Napi::Env env, Napi::Object exports);
+    explicit WireGuardClient(const Napi::CallbackInfo &info);
+
+private:
+    Napi::Value CreateDevice(const Napi::CallbackInfo &info);
+    Napi::Value DeleteDevice(const Napi::CallbackInfo &info);
+    Napi::Value Devices(const Napi::CallbackInfo &info);
+    Napi::Value Device(const Napi::CallbackInfo &info);
+    Napi::Value ConfigureDevice(const Napi::CallbackInfo &info);
+    Napi::Value SetUp(const Napi::CallbackInfo &info);
+    Napi::Value SetDown(const Napi::CallbackInfo &info);
+    Napi::Value SetAddress(const Napi::CallbackInfo &info);
+    Napi::Value DeleteAddress(const Napi::CallbackInfo &info);
+    Napi::Value Close(const Napi::CallbackInfo &info);
+
+    // Shared (not owned exclusively) so an in-flight AsyncWorker keeps the
+    // socket alive even if the JS wrapper is closed/GC'd before it finishes.
+    std::shared_ptr<netlink::NlSocket> sock_;
+};

package/src/WireGuardTypes.h

@@ -0,0 +1,68 @@
+#pragma once
+
+#include <array>
+#include <cstdint>
+#include <optional>
+#include <string>
+#include <vector>
+
+namespace wg {
+
+constexpr size_t kKeyLen = 32;
+using Key = std::array<uint8_t, kKeyLen>;
+
+struct AllowedIP {
+    std::string ip;   // textual IPv4/IPv6 address
+    uint8_t family;   // AF_INET or AF_INET6
+    uint8_t cidr;
+};
+
+// Read-only peer status, as returned by WG_CMD_GET_DEVICE (mirrors wgtypes.Peer).
+struct Peer {
+    Key publicKey{};
+    std::optional<Key> presharedKey;
+    std::optional<std::string> endpoint; // "host:port"
+    uint16_t persistentKeepaliveInterval = 0; // seconds
+    int64_t lastHandshakeTimeSec = 0;         // unix seconds, 0 = never
+    uint64_t receiveBytes = 0;
+    uint64_t transmitBytes = 0;
+    std::vector<AllowedIP> allowedIPs;
+    uint32_t protocolVersion = 0;
+};
+
+// Read-only device snapshot, as returned by WG_CMD_GET_DEVICE or the UAPI
+// `get=1` request (mirrors wgtypes.Device, plus `userspace` to record which
+// backend produced it - see DeviceToJs in WireGuardClient.cpp).
+struct Device {
+    std::string name;
+    bool userspace = false; // true if fetched via the UAPI socket backend, not kernel netlink
+    std::optional<Key> privateKey;
+    std::optional<Key> publicKey;
+    uint16_t listenPort = 0;
+    uint32_t firewallMark = 0;
+    std::vector<Peer> peers;
+};
+
+// Peer configuration input for WG_CMD_SET_DEVICE (mirrors wgtypes.PeerConfig).
+// optional<T> absent == "leave unchanged"; present (even zero-valued) == "apply this value".
+struct PeerConfig {
+    Key publicKey{};
+    bool remove = false;
+    bool updateOnly = false;
+    std::optional<Key> presharedKey;
+    std::optional<std::string> endpoint; // "host:port"
+    std::optional<uint16_t> persistentKeepaliveInterval; // seconds; 0 clears
+    bool replaceAllowedIPs = false;
+    std::vector<AllowedIP> allowedIPs;
+};
+
+// Device configuration input for WG_CMD_SET_DEVICE (mirrors wgtypes.Config).
+struct Config {
+    std::optional<Key> privateKey; // all-zero key clears the private key
+    std::optional<uint16_t> listenPort;
+    std::optional<uint32_t> firewallMark; // 0 clears
+    bool replacePeers = false;
+    std::vector<PeerConfig> peers;
+};
+
+} // namespace wg

package/src/crypto/Key.cpp

@@ -0,0 +1,77 @@
+#include "Key.h"
+
+#include <algorithm>
+#include <sodium.h>
+#include <stdexcept>
+#include <vector>
+
+namespace crypto {
+
+namespace {
+void ClampScalar(wg::Key &key) {
+    key[0] &= 248;
+    key[31] &= 127;
+    key[31] |= 64;
+}
+} // namespace
+
+wg::Key GeneratePrivateKey() {
+    wg::Key key{};
+    randombytes_buf(key.data(), wg::kKeyLen);
+    ClampScalar(key);
+    return key;
+}
+
+wg::Key GeneratePresharedKey() {
+    wg::Key key{};
+    randombytes_buf(key.data(), wg::kKeyLen);
+    return key;
+}
+
+wg::Key PublicKeyFromPrivate(const wg::Key &privateKey) {
+    wg::Key pub{};
+    if (crypto_scalarmult_base(pub.data(), privateKey.data()) != 0) {
+        throw std::runtime_error("crypto_scalarmult_base failed");
+    }
+    return pub;
+}
+
+std::string KeyToBase64(const wg::Key &key) {
+    // sodium_base64_ENCODED_LEN includes the null terminator.
+    std::vector<char> out(sodium_base64_ENCODED_LEN(wg::kKeyLen, sodium_base64_VARIANT_ORIGINAL));
+    sodium_bin2base64(out.data(), out.size(), key.data(), wg::kKeyLen, sodium_base64_VARIANT_ORIGINAL);
+    return std::string(out.data());
+}
+
+wg::Key KeyFromBase64(const std::string &b64) {
+    wg::Key key{};
+    size_t decodedLen = 0;
+    if (sodium_base642bin(key.data(), wg::kKeyLen, b64.c_str(), b64.size(), nullptr, &decodedLen,
+                           nullptr, sodium_base64_VARIANT_ORIGINAL) != 0 ||
+        decodedLen != wg::kKeyLen) {
+        throw std::invalid_argument("invalid base64-encoded WireGuard key: " + b64);
+    }
+    return key;
+}
+
+std::string KeyToHex(const wg::Key &key) {
+    std::vector<char> out(wg::kKeyLen * 2 + 1); // 2 hex chars/byte + '\0', per sodium_bin2hex's hex_maxlen contract
+    sodium_bin2hex(out.data(), out.size(), key.data(), wg::kKeyLen);
+    return std::string(out.data());
+}
+
+wg::Key KeyFromHex(const std::string &hex) {
+    wg::Key key{};
+    size_t decodedLen = 0;
+    if (sodium_hex2bin(key.data(), wg::kKeyLen, hex.c_str(), hex.size(), nullptr, &decodedLen, nullptr) != 0 ||
+        decodedLen != wg::kKeyLen) {
+        throw std::invalid_argument("invalid hex-encoded WireGuard key: " + hex);
+    }
+    return key;
+}
+
+bool IsZeroKey(const wg::Key &key) {
+    return std::all_of(key.begin(), key.end(), [](uint8_t b) { return b == 0; });
+}
+
+} // namespace crypto

package/src/crypto/Key.h

@@ -0,0 +1,30 @@
+#pragma once
+
+#include "../WireGuardTypes.h"
+
+namespace crypto {
+
+// Generates a 32-byte Curve25519 private key, clamped per RFC7748 (same
+// clamping `wg genkey` applies), from libsodium's CSPRNG.
+wg::Key GeneratePrivateKey();
+
+// Generates an opaque 32-byte preshared key (raw random bytes, not a scalar).
+wg::Key GeneratePresharedKey();
+
+// Computes the X25519 public key for a (clamped) private key.
+wg::Key PublicKeyFromPrivate(const wg::Key &privateKey);
+
+// Base64 (standard, padded) encode/decode, matching wgtypes.Key.String()/ParseKey().
+std::string KeyToBase64(const wg::Key &key);
+wg::Key KeyFromBase64(const std::string &b64); // throws std::invalid_argument if not 32 bytes decoded
+
+// Lowercase hex encode/decode - the key encoding the cross-platform userspace
+// UAPI protocol uses (https://www.wireguard.com/xplatform/), distinct from the
+// base64 form used by the kernel netlink path / `wg` CLI.
+std::string KeyToHex(const wg::Key &key);
+wg::Key KeyFromHex(const std::string &hex); // throws std::invalid_argument if not 32 bytes decoded
+
+// True if every byte is zero - the UAPI/netlink convention for "field unset".
+bool IsZeroKey(const wg::Key &key);
+
+} // namespace crypto

package/src/helpers/Array.h

@@ -0,0 +1,26 @@
+#pragma once
+
+#include <napi.h>
+#include <string>
+#include <vector>
+
+namespace helpers {
+
+inline Napi::Array StringVectorToJS(Napi::Env env, const std::vector<std::string> &items) {
+    Napi::Array arr = Napi::Array::New(env, items.size());
+    for (size_t i = 0; i < items.size(); i++) {
+        arr.Set(i, Napi::String::New(env, items[i]));
+    }
+    return arr;
+}
+
+inline std::vector<std::string> JSArrayToStringVector(const Napi::Array &arr) {
+    std::vector<std::string> out;
+    out.reserve(arr.Length());
+    for (uint32_t i = 0; i < arr.Length(); i++) {
+        out.push_back(arr.Get(i).As<Napi::String>().Utf8Value());
+    }
+    return out;
+}
+
+} // namespace helpers

package/src/helpers/AsyncPromise.h

@@ -0,0 +1,91 @@
+#pragma once
+
+#include <napi.h>
+#include <cerrno>
+#include <functional>
+#include <stdexcept>
+#include <string>
+
+namespace helpers {
+
+// Thrown from inside a PromiseWorker's execute function when a syscall fails;
+// carries the errno so the JS side gets a matching err.code (e.g. 'ENODEV', 'EEXIST').
+class SystemError : public std::runtime_error {
+public:
+    SystemError(int errnoCode, const std::string &message)
+        : std::runtime_error(message), errnoCode_(errnoCode) {}
+
+    int Code() const { return errnoCode_; }
+
+private:
+    int errnoCode_;
+};
+
+// Generic AsyncWorker -> Promise bridge. `execute` runs off the JS thread and
+// either returns normally or throws (std::exception / SystemError); `resolve`
+// runs back on the JS thread to build the resolved value from any captured state.
+class PromiseWorker : public Napi::AsyncWorker {
+public:
+    using ExecuteFn = std::function<void()>;
+    using ResolveFn = std::function<Napi::Value(Napi::Env)>;
+
+    PromiseWorker(Napi::Env env, ExecuteFn execute, ResolveFn resolve = nullptr)
+        : Napi::AsyncWorker(env),
+          deferred_(Napi::Promise::Deferred::New(env)),
+          execute_(std::move(execute)),
+          resolve_(std::move(resolve)) {}
+
+    Napi::Promise Promise() { return deferred_.Promise(); }
+
+protected:
+    void Execute() override {
+        try {
+            execute_();
+        } catch (const SystemError &e) {
+            errnoCode_ = e.Code();
+            SetError(e.what());
+        } catch (const std::exception &e) {
+            SetError(e.what());
+        }
+    }
+
+    void OnOK() override {
+        Napi::Env env = Env();
+        Napi::HandleScope scope(env);
+        deferred_.Resolve(resolve_ ? resolve_(env) : env.Undefined());
+    }
+
+    void OnError(const Napi::Error &e) override {
+        Napi::Env env = Env();
+        Napi::HandleScope scope(env);
+        Napi::Object errorObj = e.Value();
+        if (errnoCode_ != 0) {
+            errorObj.Set("code", Napi::String::New(env, ErrnoName(errnoCode_)));
+            errorObj.Set("errno", Napi::Number::New(env, errnoCode_));
+        }
+        deferred_.Reject(errorObj);
+    }
+
+private:
+    // Maps the small set of errno values this addon actually raises (see
+    // WireGuardClient.cpp) to their symbolic names; falls back to "EUNKNOWN".
+    static const char *ErrnoName(int code) {
+        switch (code) {
+            case ENODEV: return "ENODEV";
+            case EEXIST: return "EEXIST";
+            case ENOENT: return "ENOENT";
+            case EPERM:  return "EPERM";
+            case EACCES: return "EACCES";
+            case EINVAL: return "EINVAL";
+            case EBUSY:  return "EBUSY";
+            default:     return "EUNKNOWN";
+        }
+    }
+
+    Napi::Promise::Deferred deferred_;
+    ExecuteFn execute_;
+    ResolveFn resolve_;
+    int errnoCode_ = 0;
+};
+
+} // namespace helpers

package/src/helpers/IfName.cpp

@@ -0,0 +1,27 @@
+#include "IfName.h"
+
+#include <net/if.h>
+#include <stdexcept>
+
+namespace helpers {
+
+void ValidateIfName(const std::string &name) {
+    if (name.empty()) {
+        throw std::invalid_argument("interface name must not be empty");
+    }
+    if (name == "." || name == "..") {
+        throw std::invalid_argument("invalid interface name: " + name);
+    }
+    // IFNAMSIZ includes the terminating NUL the kernel appends.
+    if (name.size() > IFNAMSIZ - 1) {
+        throw std::invalid_argument("interface name too long (max " + std::to_string(IFNAMSIZ - 1) +
+                                     " bytes): " + name);
+    }
+    for (char c : name) {
+        if (c == '\0' || c == '/' || static_cast<unsigned char>(c) <= ' ') {
+            throw std::invalid_argument("invalid character in interface name: " + name);
+        }
+    }
+}
+
+} // namespace helpers

package/src/helpers/IfName.h

@@ -0,0 +1,17 @@
+#pragma once
+
+#include <string>
+
+namespace helpers {
+
+// Validates `name` as a Linux network interface name: non-empty, no NUL or
+// '/' characters, not "." or "..", and short enough to fit IFNAMSIZ
+// (including the kernel's terminating NUL). Throws std::invalid_argument
+// otherwise. Every native entry point that turns a JS-supplied string into
+// an ifname (netlink attribute, rtnetlink lookup, or UAPI socket path) must
+// call this first - mnl_attr_put_strz does not bounds-check, and an
+// unvalidated name can also be used for path traversal against the UAPI
+// socket directory.
+void ValidateIfName(const std::string &name);
+
+} // namespace helpers