@sourceregistry/node-wireguard 1.0.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +14 -13
- package/bin/x86_64-linux-gnu/node-wireguard.node +0 -0
- package/package.json +14 -3
package/README.md
CHANGED
|
@@ -6,23 +6,24 @@
|
|
|
6
6
|
[](package.json)
|
|
7
7
|
[](LICENSE)
|
|
8
8
|
|
|
9
|
-
Native Node.js (N-API) addon for managing WireGuard interfaces and peers on Linux, with a TypeScript API on top. Talks directly to the kernel's `wireguard` generic-netlink family
|
|
9
|
+
Native Node.js (N-API) addon for managing WireGuard interfaces and peers on Linux, with a TypeScript API on top. Talks directly to the kernel's `wireguard` generic-netlink family, the same wire protocol [wgctrl-go](https://github.com/WireGuard/wgctrl-go)'s Linux backend uses, plus rtnetlink for interface lifecycle. No shelling out to `wg`/`ip`.
|
|
10
10
|
|
|
11
|
-
Built for [WireGuard
|
|
11
|
+
Built for [WireGuard](https://www.wireguard.com/), a registered trademark of Jason A. Donenfeld. This is an independent, unofficial project, not affiliated with or endorsed by the WireGuard project.
|
|
12
12
|
|
|
13
13
|
## Features
|
|
14
14
|
|
|
15
|
-
- **Full interface lifecycle
|
|
16
|
-
- **Address + link state
|
|
17
|
-
- **Device + peer configuration
|
|
18
|
-
- **Device + peer inspection
|
|
19
|
-
- **Userspace (UAPI) backend fallback
|
|
20
|
-
- **Key utilities
|
|
21
|
-
- All blocking netlink syscalls run off the JS thread via `Napi::AsyncWorker
|
|
15
|
+
- **Full interface lifecycle:** `createDevice()` / `deleteDevice()` (rtnetlink `RTM_NEWLINK`/`RTM_DELLINK`, `IFLA_INFO_KIND=wireguard`). Goes beyond wgctrl-go, which assumes the link already exists.
|
|
16
|
+
- **Address + link state:** `setAddress()` / `deleteAddress()` (rtnetlink `RTM_NEWADDR`/`RTM_DELADDR`) and `setUp()` / `setDown()` (`RTM_NEWLINK` + `IFF_UP`). A freshly created device has no address and is down by default. These are what make it actually pass traffic.
|
|
17
|
+
- **Device + peer configuration:** `configureDevice()` sets private key, listen port, firewall mark, and peers (add/update/remove, allowed-IPs, preshared key, endpoint, persistent keepalive). Mirrors wgtypes' "pointer-optional" semantics: omit a field to leave it unchanged, set it (even to `0`/`''`) to apply/clear it explicitly.
|
|
18
|
+
- **Device + peer inspection:** `devices()` / `device(name)` return live status: peers, handshake times, rx/tx byte counters, allowed-IPs.
|
|
19
|
+
- **Userspace (UAPI) backend fallback:** `devices()`/`device()`/`configureDevice()` automatically use the cross-platform UAPI socket (`/var/run/wireguard/<name>.sock`) for interfaces backed by a userspace implementation like `wireguard-go`, instead of kernel netlink, transparently (`device.type` reports which). Interface lifecycle (`createDevice`/`setUp`/`setAddress`/etc.) is unaffected - those are still plain rtnetlink and work the same either way, since wireguard-go creates a real kernel-visible TUN interface.
|
|
20
|
+
- **Key utilities:** `generatePrivateKey()`, `generatePresharedKey()`, `publicKey()` via libsodium X25519, matching `wg genkey`/`wg genpsk`/`wg pubkey` output (base64, 32 bytes).
|
|
21
|
+
- All blocking netlink syscalls run off the JS thread via `Napi::AsyncWorker`; every `WireGuardClient` method returns a `Promise`.
|
|
22
22
|
|
|
23
23
|
## Requirements
|
|
24
24
|
|
|
25
25
|
- Linux with the WireGuard kernel module/support loaded (`modprobe wireguard` or built-in).
|
|
26
|
+
- Node.js 22 or newer. CI tests Node 22 for backward compatibility and Node 24 as the latest LTS line.
|
|
26
27
|
- `CAP_NET_ADMIN` (typically: run as root) for `createDevice`/`deleteDevice`/`configureDevice`.
|
|
27
28
|
- Build deps: `libmnl-dev`, `libsodium-dev`, `pkg-config`, a C++17 toolchain.
|
|
28
29
|
|
|
@@ -33,7 +34,7 @@ npm install
|
|
|
33
34
|
npm run build
|
|
34
35
|
```
|
|
35
36
|
|
|
36
|
-
Or use the bundled `.devcontainer` (works on Windows too, via Docker Desktop/WSL2)
|
|
37
|
+
Or use the bundled `.devcontainer` (works on Windows too, via Docker Desktop/WSL2). See below.
|
|
37
38
|
|
|
38
39
|
## Usage
|
|
39
40
|
|
|
@@ -71,8 +72,8 @@ More examples in [`examples/`](./examples): `list-devices`, `get-device`, `gener
|
|
|
71
72
|
|
|
72
73
|
- Linux only (the UAPI backend means a wireguard-go *peer* anywhere works fine, but this addon itself only runs on Linux).
|
|
73
74
|
- UAPI socket lookup only checks `/var/run/wireguard/<name>.sock` - not `$XDG_RUNTIME_DIR/wireguard/` (which wgctrl-go's wguser backend also checks).
|
|
74
|
-
- Route management (beyond the implicit route rtnetlink installs for an assigned address's own subnet) is left to the caller
|
|
75
|
-
- Calls on one `WireGuardClient` instance are serialized internally (queued, run one at a time in call order)
|
|
75
|
+
- Route management (beyond the implicit route rtnetlink installs for an assigned address's own subnet) is left to the caller. Use `ip route` or rtnetlink directly for anything beyond that.
|
|
76
|
+
- Calls on one `WireGuardClient` instance are serialized internally (queued, run one at a time in call order). Issuing several without awaiting each is safe but not parallel. Use separate instances if you want calls to actually run concurrently.
|
|
76
77
|
|
|
77
78
|
## Development
|
|
78
79
|
|
|
@@ -82,7 +83,7 @@ npm run build:ts # tsc
|
|
|
82
83
|
npm test # node:test; kernel/UAPI-backed tests auto-skip unless root + the relevant backend is present
|
|
83
84
|
```
|
|
84
85
|
|
|
85
|
-
A `.devcontainer` is included (Dockerfile + `devcontainer.json`, `capAdd: NET_ADMIN`) so the addon builds and the full test suite
|
|
86
|
+
A `.devcontainer` is included (Dockerfile + `devcontainer.json`, `capAdd: NET_ADMIN`) so the addon builds and the full test suite, including real interface create/configure/delete, runs the same way on Windows (via Docker Desktop/WSL2) as on Linux.
|
|
86
87
|
|
|
87
88
|
## Packaging / CI
|
|
88
89
|
|
|
Binary file
|
package/package.json
CHANGED
|
@@ -1,9 +1,20 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sourceregistry/node-wireguard",
|
|
3
|
-
"version": "1.0.
|
|
4
|
-
"description": "Native N-API addon for managing WireGuard interfaces and peers
|
|
3
|
+
"version": "1.0.1",
|
|
4
|
+
"description": "Native N-API addon for managing WireGuard interfaces and peers on Linux via kernel netlink, rtnetlink, and UAPI",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"author": "ProjectSource V.O.F.",
|
|
7
|
+
"keywords": [
|
|
8
|
+
"wireguard",
|
|
9
|
+
"vpn",
|
|
10
|
+
"linux",
|
|
11
|
+
"netlink",
|
|
12
|
+
"rtnetlink",
|
|
13
|
+
"uapi",
|
|
14
|
+
"native-addon",
|
|
15
|
+
"napi",
|
|
16
|
+
"node-addon-api"
|
|
17
|
+
],
|
|
7
18
|
"repository": {
|
|
8
19
|
"type": "git",
|
|
9
20
|
"url": "git+https://github.com/SourceRegistry/node-wireguard.git"
|
|
@@ -14,7 +25,7 @@
|
|
|
14
25
|
"linux"
|
|
15
26
|
],
|
|
16
27
|
"engines": {
|
|
17
|
-
"node": ">=
|
|
28
|
+
"node": ">=22.0.0"
|
|
18
29
|
},
|
|
19
30
|
"publishConfig": {
|
|
20
31
|
"access": "public"
|