Files

T

feat(client): persist virtual MAC identity

Remote clients need a stable locally administered MAC address so the relay,
gateway, DHCP lease, and LAN peers keep seeing the same tunnel identity across
runs. Requiring users to pass `--virtual-mac` made that responsibility manual.

Add a platform-neutral client identity store that loads a JSON identity file or
generates a new valid virtual MAC with OS randomness and persists it. The file
stores the MAC in the same string form shown by the CLI. The Windows client now
uses `lanparty-client-identity.json` by default while keeping `--virtual-mac` as
a manual test override.

TAP binding still remains future work; this slice only owns the client identity
that will be assigned to the TAP adapter.

Test Plan:
- cargo fmt --check
- cargo test --workspace
- cargo clippy --workspace --all-targets -- -D warnings
- git diff --check

Refs: PLAN.md MAC identity

2026-05-21 18:35:20 +02:00

4.0 KiB

Raw Blame History

softlan-vpn

Monorepo for a Layer 2 over QUIC LAN party bridge.

Workspace crates

lanparty-proto: shared frame format, MAC validation, MTU helpers.
lanparty-ctrl: control-plane messages (join/hello/role/version).
lanparty-obs: shared diagnostics/logging event models.
lanparty-client-core: platform-agnostic client session state.
lanparty-client-win: Windows TAP + route/metric handling binary.
lanparty-gateway: Linux AF_PACKET gateway binary.
lanparty-relay: public QUIC relay binary.

`lanparty-proto`

Transport-agnostic tunnel contract shared by all binaries:

overlay datagram header encoding and decoding
Ethernet frame header parsing
MAC address parsing and identity validation
QUIC datagram to TAP MTU budget helpers

`lanparty-ctrl`

Reliable control-plane schema shared by the QUIC stream handlers:

endpoint hello messages with role, room, MAC, and datagram budget
server welcome, reject, peer lifecycle, stats, and disconnect messages
room-code, role/MAC, peer-id, and effective-MTU validation
length-prefixed JSON control frames for reliable QUIC streams

`lanparty-obs`

Shared diagnostics and structured logging vocabulary:

gateway/relay frame logs with MACs, ethertype, length, peer, and action
tunnel counters shared by control messages and runtime diagnostics
client connectivity/TAP diagnostics and user-facing status messages

`lanparty-client-core`

Platform-neutral remote client relay session:

relay QUIC connection with pinned relay certificate trust
client hello with room, virtual MAC, and datagram budget
welcome/reject handling with assigned peer id and effective TAP MTU
Ethernet frame send/receive helpers over QUIC DATAGRAM

`lanparty-relay`

Public relay binary and relay-owned room state:

QUIC endpoint binding and first-stream hello/welcome admission
room admission for clients and gateways
one gateway per room, duplicate client MAC rejection, and room limits
stable effective room MTU chosen before Ethernet datagrams flow
live Ethernet datagram forwarding with no ingress reflection
L2 safety filters for jumbo, switch-control, DHCP-server, and IPv6-RA frames
peer leave cleanup for room membership and MAC indexes

Build

cargo check --workspace

Relay

cargo run -p lanparty-relay -- --listen 443/udp --dev-cert-der-out relay-cert.der

--listen accepts either a socket address or a UDP port shorthand such as 443/udp. The relay binds a QUIC endpoint, accepts a control-stream hello, replies with welcome or reject, and forwards live Ethernet QUIC datagrams between accepted peers in the same room. It currently uses a generated self-signed development certificate; --dev-cert-der-out writes that certificate so the gateway and client can pin it in development. Production certificate handling remains future work.

Gateway

cargo run -p lanparty-gateway -- \
  --relay 203.0.113.10:443 \
  --server-name lanparty-relay.local \
  --relay-ca-cert relay-cert.der \
  --room ROOM1 \
  --interface eth0

The gateway connects to the relay as role = gateway, completes the control-stream hello/welcome handshake, opens an AF_PACKET socket on the LAN interface, and bridges Ethernet frames between the relay and wired LAN until shutdown. It tracks remote-client source MACs seen from relay traffic and periodically emits small CAM refresh frames so the physical switch keeps those MACs associated with the gateway port.

Windows Client

cargo run -p lanparty-client-win -- \
  --relay 203.0.113.10:443 \
  --server-name lanparty-relay.local \
  --relay-ca-cert relay-cert.der \
  --room ROOM1

The Windows client binary currently connects to the relay as role = client with a generated locally administered virtual MAC persisted in lanparty-client-identity.json, completes the control-stream hello/welcome handshake, and then waits for shutdown. --virtual-mac can still override the stored identity for manual testing. TAP adapter binding and route pinning are not wired yet.

4.0 KiB Raw Blame History