# VeloraMesh v1 Release Notes

v1.0.0-rc1 commit=118df3e1 date=2026-06-02T10:10:19Z

This is the first production-oriented release candidate for VeloraMesh v1.

It is intended for controlled field testing of the direct-P2P mesh VPN core. It is not a final security certification and should not be marketed as independently audited or unbreakable.

## Included

- Ubuntu control plane with HTTPS, named-network join, authenticated device rename, signed sessions, edge discovery-ticket issuance, endpoint reporting, endpoint freshness, peer metadata, SQLite/JSON persistence, rate limits, and audit-safe logs.
- Stealth control-plane request proof on all public API routes: join requests carry HMAC-SHA256 proof derived from the join secret, while session/authenticated requests carry Ed25519 device signatures bound to canonical request data, timestamp, nonce, body hash, and session-token hash where applicable.
- Server-signed short-lived membership tickets in peer metadata and P2P handshakes. Removed or blocked devices cannot mint fresh peer-authorization proof, active direct sessions are bounded by ticket expiry if control-plane refresh is unavailable, and clients ignore unsigned peer metadata instead of falling back to a weaker mode.
- Client doctor now samples the control-plane HTTPS `Date` header and reports clock drift before time-bound request proofs, discovery tickets, or membership tickets turn into confusing peer negotiation failures.
- Local Ubuntu server admin CLI and manager script with role-aware all-in-one, API-only, and Edge-only guided install/update, fresh install/reset by role, TLS attachment, first-network creation, networks, members, endpoints, blocked devices, network/device rename, store backup/restore, and service operations.
- Server manager service operations are role-aware: API-only hosts report API status/logs without treating a missing edge unit as an error, Edge-only hosts report edge status/logs without treating a missing API unit as an error, and store backup/restore actions are exposed only where the control-plane store exists.
- Server and edge local bind settings are install-time configurable. The guided manager now asks for bind host and port separately, then writes normalized `VELORAMESH_API_BIND_ADDR` and `VELORAMESH_EDGE_BIND_ADDR` values. The packaged defaults remain all-interfaces `2053/tcp` for API and all-interfaces `3478/udp` for edge, but guided setup can set deployment-specific local listener ports, and normal updates preserve existing custom values. Public DNS names and URLs are intentionally rejected in bind fields.
- Server manager guided flows run a non-blocking self-test for binary, env file, systemd unit, and service state after install/fresh setup.
- Separate `veloramesh-edge` UDP discovery service on UDP `3478`, authenticated by opaque API-issued discovery tickets, without control-plane DB access or peer traffic relay.
- UDP discovery no longer exposes the discovery ID in request/response headers; the visible wire payload is ticket plus encrypted nonce/ciphertext, ticketless packets are ignored without a response, and bounded padding plus jittered retry intervals reduce traffic-analysis fingerprints.
- Shared protocol derivation for discovery session material, so client, API, and edge stay on one source of truth for UDP discovery identity/key generation.
- Windows x86_64/ARM64, macOS x86_64/ARM64, and Linux x86_64/ARM64 client packages with guided install/update, navigable network/service operation menus, fresh reset, uninstall/purge menus, and optional background service/daemon paths.
- Ubuntu server packages for both x86_64 and ARM64 hosts, including the control-plane API and UDP discovery edge binaries in each server package.
- Desktop and Android guided client setup collect API host/domain, API HTTPS port, edge discovery host/domain, and edge UDP port as separate fields, while normalized runtime config still stores the HTTPS API URL and encrypted UDP discovery endpoint.
- Release packages include distribution-facing `VELORAMESH-EULA.md`, `THIRD-PARTY-NOTICES.md`, `PRIVACY.md`, and `SECURITY.md`; Android APK output now receives the same files plus manifest metadata, and release audit fails if legal/compliance files are missing.
- Release packages include the VeloraMesh brand mark assets under `brand/`, and release audit now fails if those assets are missing from package directories, ZIP files, or manifests.
- Release packaging writes SHA256 checksum files for desktop/server ZIPs and Android APK output artifacts, and release audit verifies those hashes before publication.
- Desktop client installers now run a non-blocking doctor self-test after setup, including encrypted UDP edge discovery reachability when a discovery endpoint is configured. Windows service logs and macOS LaunchDaemon stdout/stderr logs are rotated at 5 MiB with five backups; Linux service logs remain under journald.
- macOS LaunchDaemon and Linux systemd client services use explicit system secret directories, avoiding `$HOME` dependencies in background tunnel startup.
- Consistent installer guardrails for required prompts, join-secret length, retryable join failures, retryable TLS path mistakes, and idempotent uninstall/purge flows.
- SQLite store startup repair for membership tables missing the required primary key, preventing preserved stores from failing network join during install/update.
- Server installer and manager repair for SQLite store ownership and permissions, preventing readonly database failures after manual copies, previous root-owned runs, or local admin operations performed before the service starts.
- Control-plane liveness timestamps are refreshed by endpoint reporting and network peer-list heartbeats: device `last_seen_at` follows authenticated endpoint/session activity, and membership `last_seen_at` follows the selected network's peer refresh path.
- Android API 24+ client project with edge-to-edge layout, selected-network virtual IP display, VpnService, Android Keystore, trust-on-first-use SPKI capture, redirect-free identity probing, foreground notification, notification Stop teardown hardening, repeated-tap join/trust/VPN-start guards, and Go mobile mesh bridge.
- Android launcher, in-app header, and foreground VPN notification now use the VeloraMesh mark consistently.
- Android shows battery-optimization status and links to system battery settings for long screen-off and Doze preparation.
- Android monitors physical Wi-Fi/mobile/link-address changes and refreshes the local native runtime after a short debounce. The refresh path is single-flight, so endpoint candidates are recomputed after network transitions without a manual VPN restart or overlapping reconnect loops.
- Direct authenticated UDP peer negotiation, pairwise encrypted peer-hello envelopes, opaque encrypted data-plane frames, replay protection, padded/jittered keepalive control traffic, endpoint roaming, and timed in-band rekey.
- Handshake construction returns explicit errors for invalid wire-length inputs instead of relying on runtime panics.
- TUN routing through Windows Wintun, macOS utun, Linux TUN, and Android VpnService, with platform-specific packet headroom for Windows, BSD/macOS, and Linux virtio/GRO TUN paths.
- Installer-configurable default virtual IPv4 pool, with per-network override at creation time. The packaged default remains `10.253.0.0/16`; accepted pools are private `10.0.0.0/8` or `172.16.0.0/12` CIDRs with `/16` through `/24`, avoiding ISP CGNAT `100.64.0.0/10` and common home LAN `192.168.0.0/16` overlap.
- Store-backed virtual IPv4 allocation now rejects duplicate or network-pool-external membership values across memory, JSON, and SQLite stores before issuing peer metadata.
- Client and Windows installer now report control-plane rate limiting as a short cooldown condition instead of a generic join failure.
- Policy-driven peer manager with eager, hybrid, and on-demand behavior for larger rooms.
- Low-latency bounded demux queues, drop-oldest overload behavior, packet buffer reuse, tunable UDP socket buffers, MTU diagnostics, optional MSS clamp, server-controlled UDP broadcast/directed-broadcast/multicast forwarding for LAN discovery tests, and optional local TCP/UDP packet policy.
- Network-level `broadcast_mode=filtered|all` so trusted lab rooms can enable all UDP LAN discovery broadcasts from the server without changing every client or choosing application-specific port lists.
- Server-controlled network policy fields: `underlay_ip_mode`, `endpoint_ttl_seconds`, `virtual_ipv4_cidr`, and `policy_revision`. The default underlay policy is `ipv4-only`; operators can switch a network to `dual-stack` or `ipv6-only`, and clients refresh/report/dial endpoint candidates according to the current policy.
- Endpoint freshness is controlled only by per-network `endpoint_ttl_seconds`; the server installer no longer exposes a parallel global freshness knob.
- Immutable network-ID binding after join, so server-side network renames do not require reinstalling or reconfiguring joined tunnel runtimes.
- Runtime membership removal handling: selected-network `403`/`404` drops active peers, removes the local network profile, and stops persistent reconnect attempts until the user joins again.
- Endpoint candidate ordering is shared across clients: discovery-reflexive UDP endpoints are reported before platform local-address fallbacks, endpoint families are filtered by server `underlay_ip_mode`, local interface reports place IPv4 before IPv6 fallbacks in dual-stack mode, and IPv4 edge discovery endpoints are tried before IPv6. Peer connection attempts then prefer same-subnet local endpoints, IPv4, public IPv6, and finally private IPv6/ULA fallback when the active policy permits them; endpoint replacements are handshake-verified when the current verified endpoint cannot be kept.
- Hot-path peer refresh keeps the current verified endpoint while it is still advertised, and also holds recently authenticated roamed endpoints briefly while server endpoint reports catch up. This prevents private-address overlap such as unrelated `192.168.1.x` networks from causing unverified endpoint jumps and peer-count flapping. The default liveness window is now five keepalive periods.
- Receiver-side endpoint admission now requires confirmation before a healthy active peer path is roamed to a new UDP source. Decrypted packets from candidate endpoints are still accepted, stale paths can recover quickly, and endpoint-churn abuse cannot move active paths on a single packet.
- Make-before-break endpoint upgrades now use encrypted UDP quality probes. Preferred candidate endpoints are tested in a bounded parallel probe window, compared against the current path by RTT, and installed only when reachable and materially better.
- Initial small-mesh startup keeps a bounded completion grace after the first successful peer, reducing multi-device startup inconsistency without waiting for every stale/offline endpoint.
- Public control-plane surface is network-scoped; obsolete pairwise peer-connect diagnostics are removed from the production API and client debug surface.
- Unique network names with non-unique device display names; security-sensitive device operations use device IDs.
- Product-shaped CLI surface: `config`, `device`, `network`, `doctor`, `service`, `run-network`, `mtu-info`, `version`, and scoped `debug` diagnostics.
- `network peers`, `doctor`, and periodic `mesh_stats` include clearer peer diagnostics: endpoint quality family counts, active peer count, and optional `doctor -discovery <host:port>` edge reachability. `doctor -bundle <zip>` writes a sanitized support bundle with redacted config and bounded log tails.

## Not Included

- Relay server.
- Public remote server management API.
- GUI/tray shell.
- Signed public release/update channel.
- Independent cryptographic review or penetration test.
- Final production claim for highly sensitive daily use.

## Required Validation Before Broader Production Claims

- Windows service-owned tunnel from clean reboot before user logon.
- RDP-specific validation from the service path.
- macOS LaunchDaemon field validation.
- Linux systemd field validation.
- Android Doze, long screen-off, and multi-hour RDP soak.
- Real 64, 100, and 255 member field validation.
- Signed artifacts, checksums, and update/rollback procedure.
- External security review.

## Package Validation

Run before publishing artifacts:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\test-all.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\build-android-apk.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\build-android-apk.ps1 -Task lintRelease
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\build-release.ps1 -Version v1.0.0-rc1 -WintunDir .\.run\verify-release-windows\wintun
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\release-audit.ps1 -Version v1.0.0-rc1 -RequireAndroid -AndroidVariant Release
```
