@emberclaw/wg-native

Userspace WireGuard bindings for Emberclaw. Wraps boringtun 0.7 as a Node native addon via napi-rs. Both emberclaw-plugin and the emberclaw-app Electron main process consume this package.

Private during integration (Lanes W1–W4). Published to npm in Lane W5 as @emberclaw/wg-native + per-platform subpackages.

Build + smoke test

npm install
npm run build
node smoke.mjs

The smoke test runs a full handshake + data round-trip between two in-process Tunnel instances. Prints ✓ round-trip success on pass. Takes under a second after build.

API

export function generatePrivateKey(): Buffer
export function derivePublicKey(secret: Buffer): Buffer

export class Tunnel {
  constructor(staticPrivate: Buffer, peerPublic: Buffer, index: number)
  formatHandshakeInitiation(): Buffer
  encapsulate(src: Buffer): Buffer | null
  decapsulate(wire: Buffer): { kind: 'done' | 'write_to_network' | 'write_to_tunnel'; data: Buffer | null }
  drain(): { kind; data }
  updateTimers(): Buffer | null
}

Two gotchas (read before integrating)

1. Wrap payloads in a 20-byte IPv4 header before encapsulate. boringtun validates decrypted output as an IP datagram and rejects anything else. See emberclaw-architecture/10-wireguard-transport.md §"The two quirks" for the exact header format.

2. Call drain() in a loop after every decapsulate. Pre-handshake encapsulate queues data internally; the queue flushes via decapsulate(empty) which the binding exposes as drain(). Also handles the keepalive boringtun emits on handshake completion.

Cross-compilation

Local cross-compile from macOS does not work (ring 0.17.x + zigbuild interaction). Build natively on GitHub Actions, one job per target. See the architecture doc for the runner matrix.

Upgrading boringtun

Exact-pinned at =0.7.0 in Cargo.toml on purpose. To bump:

1. Check the boringtun changelog.
2. Update the pin, run cargo update, rebuild, run smoke.
3. Re-read Tunn::new, encapsulate, decapsulate signatures — boringtun's API has shifted between 0.5, 0.6, and 0.7.
4. Commit Cargo.lock.

Files

• src/lib.rs — the napi-rs binding
• smoke.mjs — local round-trip test
• Cargo.toml, Cargo.lock — Rust deps, committed
• package.json — npm metadata, private during development
• index.js, index.d.ts — generated by napi build, not committed

See also

• emberclaw-architecture/10-wireguard-transport.md — full spec
• emberclaw-docs/docs/architecture/wireguard.md — engineering quick-ref