# VeloraMesh v1 Release Notes

v1.0.0-rc2 commit=1e28ecb9 date=2026-09-05T23:21:02Z

RC2 is the current VeloraMesh v1 source and package line. It supersedes the
published RC1 packages, which remain available as an immutable archive and are
not rebuilt from this tree.

RC2 keeps the same self-hosted, direct-P2P product model while strengthening
authorization, overload behavior, network-change recovery, platform coverage,
operations, and release reproducibility. This document records the release
delta and package boundary. The normative architecture and security contracts
remain in `VELORAMESH-V1-TECHNICAL-SPEC.md` and `SECURITY-MODEL.md`.

## Changes Since RC1

### Reliability And Installation

- Keep desktop installer action menus available with source, location, and
  endpoint overrides, including over an existing installation. Explicit
  operations and enrollment inputs still select the direct flow.
- Wait for Windows client commands to exit before interpreting errors or
  restoring files. Native stderr no longer interrupts the installer transaction
  before the command has finished under Windows PowerShell 5.1.
- Stop the Windows service before restoring package files during rollback.
  Retry transient file-sharing locks within a fixed bound and preserve recovery
  files when a persistent lock prevents restoration instead of hiding the error.
  Reject invalid candidates without stopping the untouched installation; report
  rollback restart errors and permit a retry without removing restored files.
- Remove uncommitted client binaries after a failed first Linux/macOS install.
  Ubuntu rollback stages restored files before replacement, keeps services
  stopped if file restoration fails, and retains private recovery snapshots
  whenever rollback cannot complete.
- Publish release directories with bounded filesystem rename retries. Existing
  targets are never merged; Windows sharing locks leave the source intact, and
  failed staging publication restores the previous release for a later retry.
- Isolate transient TUN write pressure to the affected packet instead of
  restarting the mesh runtime. Permanent device failures still require recovery.
- Recheck authenticated receive activity during liveness removal so a stale
  monitor observation cannot remove a recovered or replaced peer session.
- Honor explicit startup for existing Linux and macOS services while preserving
  their descriptors. Ordinary updates retain a stopped service's state; invalid
  fresh/start combinations are rejected before removing the installation.
- Roll back API-only and all-in-one installation if edge-ticket key generation
  fails; do not report success or retain a partial installation.
- Encode Linux client and Ubuntu server unit paths using systemd syntax,
  including literal spaces and percent specifiers. Validate server installation
  directories before modifying files.
- Update Android's notification peer count from current privacy-safe connection
  and removal events without waiting for the periodic stats interval. Remove
  obsolete identity-based log parsing; retain unknown count during reconnect
  until the new runtime reports its state. This changes notification display,
  not handshake, endpoint selection, or reconnect timing.
- Parse UTC timestamp-prefixed Android runtime records alongside unprefixed
  stats so startup, recovery, and peer counts reach the notification state.
- Coalesce Android runtime notification changes in fixed 250 ms windows using
  one pending callback and the latest text. Suppress unchanged notifications
  and invalidate pending callbacks and old runtime log sessions on stop or
  replacement. Explicit service lifecycle notifications remain immediate.
- Reject not-yet-valid TLS certificates before replacement or service restart,
  alongside expired and mismatched pairs. Same-key renewal and explicitly
  approved key rotation retain their existing behavior.

### Authorization And Exposure

- Added request-proof v2 with canonical method, escaped path, normalized query,
  exact body size/hash, timestamp, nonce, identity, and session-token binding.
- Moved cryptographic proof authentication ahead of route lookup and request-body
  reads. Ambiguous framing, `Expect: 100-continue`, transfer encoding, duplicate
  security headers, invalid proof, and pre-authentication overload now converge
  on the same empty response without exposing valid method/path pairs.
- Kept network join secrets on the client: PBKDF2-HMAC-SHA256 with 600000
  iterations derives an Ed25519 join key locally, while the server stores only
  an opaque selector and public verifier key. Public client and server commands
  accept secrets only from bounded local files; guided installers use private
  temporary files so secrets do not enter process arguments or inherited
  environments.
- Added short-lived signed membership tickets to peer metadata and peer
  handshakes, preventing removed or blocked members from minting fresh peer
  authorization.
- Bound virtual source addresses to authenticated network membership.
- Required edge attestations for public endpoint reports; private, ULA, and
  CGNAT candidates remain available without public-address redirection.
- Split the HTTPS control plane and stateless UDP discovery edge into explicit
  all-in-one, API-only, and edge-only deployment roles.
- Removed cleartext discovery identifiers. Discovery requests are ticket-bound,
  encrypted, padded, and ignored without a valid proof.

### Resource And Abuse Boundaries

- Added fixed ingress, authenticated-device, connection, HTTP/2 stream, and
  in-flight request budgets for the control plane.
- Canonicalized direct and trusted-proxy source IPs and applied ingress admission
  before scarce in-flight work slots, preventing textual-address and rejected
  source traffic from weakening overload isolation.
- Added source and authenticated-identity budgets for UDP discovery.
- Made network membership capacity enforcement atomic across memory, JSON, and
  SQLite stores, including concurrent join behavior and orphan cleanup.
- Made SQLite/WAL the server's default persistence backend. The explicit JSON
  development backend now rejects oversized input and output instead of
  permitting an accidentally large local store to exhaust process memory.
- Bounded peer synchronization, handshake subscribers, endpoint probes, packet
  queues, and shutdown waits; malformed wire lengths now fail explicitly.
- Added race, overload, parser, capacity, and denial-of-service regression
  coverage to the default quality gate, including HTTP/1.1 and HTTP/2
  route-independent stealth-response probes.

### Connectivity And Runtime

- Added encrypted endpoint quality probes, make-before-break endpoint upgrades,
  verified roaming, and temporary retention of recently authenticated paths.
- Renewed verified membership authorization leases in place so healthy peer
  sessions no longer perform periodic full handshakes or replace their active
  endpoints when short-lived tickets rotate.
- Added payload-aware endpoint stickiness: active application traffic pins a
  healthy authenticated path, while verified failover remains available when
  that path genuinely stops responding. The final transition rechecks activity
  atomically, rejects stale probe snapshots, and applies the same protection to
  authenticated roaming candidates.
- Added equal-jitter exponential recovery backoff to prevent disconnected peers
  from remaining synchronized in non-overlapping handshake retry cycles.
- Added single-flight network-change recovery for Android Wi-Fi/mobile
  transitions without stacking reconnect loops. Android 12 and newer follow
  the platform-selected physical path; IPv6 privacy-address churn and transient
  changes that settle inside the debounce window no longer restart the tunnel.
  A delayed restart callback cannot replace a runtime started by a later user action.
- Replaced the legacy full-square Android launcher bitmap with canonical
  adaptive, round, and monochrome layers constrained to the platform safe zone.
- Explicitly excluded every Android application-data domain from cloud backup
  and device-to-device transfer so device identity and enrollment state are not
  migrated outside the supported lifecycle.
- Preserved Android's requested-running state when the platform recreates its
  sticky VPN service process, keeping later physical-network recovery active.
- Added live peer add/remove reconciliation, immutable network-ID binding,
  server-controlled underlay family policy, configurable virtual IPv4 pools,
  and LAN discovery broadcast policy.
- Added bounded packet reuse, UDP socket tuning, MTU/MSS diagnostics, timed
  rekey, and permanent data-plane allocation/throughput benchmarks. Rekey now
  preserves the active path across one-way loss beyond the retry window and is
  covered by sustained bidirectional traffic tests.
- Removed per-frame plaintext allocation from the authenticated router receive
  path and per-frame ciphertext allocation from its unicast send path by reusing
  single-owner decrypt and encrypt buffers. Android now also reuses its
  single-reader TUN buffer instead of allocating one MTU-sized slice per packet.
- Reused the desktop TUN native write vector, removing its remaining per-packet
  heap allocation from sustained inbound traffic.
- Removed the per-packet broadcast-policy copy and reused bounded peer/ciphertext
  scratch storage during LAN broadcast fanout, including high-fanout game
  discovery traffic.
- Replaced the inbound UDP payload clone with pooled immutable datagram storage
  and explicit reference-counted ownership across data-plane and handshake
  queues. Queue eviction, oversize rejection, and subscription shutdown release
  storage deterministically.
- Drained complete native TUN read batches so Linux GSO traffic cannot terminate
  the router with an undersized single-packet read and queued segments avoid
  redundant device reads.
- Coalesced authenticated `last_seen_at` persistence to bound store writes while
  keeping operator liveness data current.

### Platforms And Operations

- Centralized bounded secret-file validation across client and server commands;
  installers preserve supplied bytes and reject invalid content without silent
  truncation or embedded-newline removal. POSIX rollback also restores package
  metadata alongside the binary and service descriptor.
- Standardized architecture-specific package identity and validation across
  Windows, macOS, Linux, and Ubuntu amd64/arm64 targets.
- Aligned Windows Service, macOS LaunchDaemon, Linux systemd, and Android
  foreground VPN lifecycle behavior around the shared client contract.
- Added installer self-tests, data-minimal atomically written doctor bundles,
  bounded Windows/macOS log rotation, and role-aware Ubuntu status, backup,
  restore, reset, and purge.
- Replaced topology-bearing background client logs with aggregate event classes,
  counters, retry delays, and latency measurements; explicit operator
  diagnostics remain available on demand.
- Minimized control-plane and edge failure logs to bounded operation classes;
  network IDs, device IDs, endpoint/source addresses, and raw handler failures
  are not written by public request paths.
- Replaced the standard HTTP/TLS server error stream with fixed, rate-limited
  transport classes so malformed handshakes cannot disclose source addresses
  or amplify an unauthenticated log-flood attempt.
- Made Windows, macOS, Linux, and Ubuntu install/update transactional: staged
  binaries are validated, prior service state is preserved, and failed
  replacement restores the previous installation. Removal and purge now stop
  and verify managed services before deleting units, binaries, configuration,
  or secrets; failed service shutdown leaves the installation intact. Windows
  package metadata and Wintun updates share the binary rollback boundary, and
  service replacement updates the existing SCM record transactionally and must
  reach the running state before the installer commits the update.
- Made first-run desktop identity creation atomic. A failed network join keeps
  one reusable local identity for the retry, concurrent initialization cannot
  overwrite an enrollment, and failed config creation releases any external
  Linux/macOS private-key file it created.
- Enforced the Ubuntu edge-only storage boundary: clean and existing edge hosts
  update normally, while API/all-in-one hosts require an explicit Fresh
  Edge-only reset before they can assume the isolated edge role.
- Added validated Ubuntu TLS renewal and explicit SPKI key-rotation handling.
  Android can persist the approved replacement identity without clearing app
  data or rejoining, and restarts the VPN runtime on the new trust set.
- Separated public API/edge host and port prompts from local listener bind host
  and port prompts.
- Added installer-configurable default virtual IPv4 CIDR with per-network
  override at network creation.

### Build And Publication

- Centralized source release identity in `release/release.json` and public
  current/archive inventory in `html/release-catalog.json`.
- Pinned production builds to Go 1.27.1 with ambient Go workspace, user config,
  experiments, and compatibility overrides disabled.
- Updated and pinned the Go dependency graph, Gradle 9.7.1, Android Gradle
  Plugin 9.3.2, API 37, JDK 17, Staticcheck 0.8.1, gosec 2.29.0, and
  govulncheck 1.7.0.
- Added architecture-aware official Wintun validation, Android signing-certificate
  validation, legal/brand payload checks, SHA-256 verification, atomic website
  synchronization, and immutable RC1 archive checks.

## RC2 Package Matrix

| Package role | Architecture |
| --- | --- |
| Windows client | amd64, arm64 |
| macOS client | amd64, arm64 |
| Linux client | amd64, arm64 |
| Ubuntu server | amd64, arm64 |
| Android client | signed release APK, API 24+ |

Each Ubuntu server package contains both `veloramesh-server` and
`veloramesh-edge`; the guided manager installs all-in-one, API-only, or edge-only
without requiring a different archive.

Every desktop/server archive includes its manifest, release notes, legal files,
brand assets, and platform installer. The website publication set also includes
`SHA256SUMS.txt` for desktop/server archives and `SHA256SUMS-android.txt` for the
Android APK.

## Compatibility Boundary

- RC2 uses the current request-proof, discovery-ticket, membership-ticket,
  endpoint-attestation, and peer-handshake contracts. RC1 components are not a
  mixed-version deployment target.
- RC2 uses persistence schema version 2 and intentionally does not migrate the
  earlier join-verifier representation. Clean RC2 server reset and complete
  client re-enrollment are the supported rollout path.
- Existing RC1 packages remain downloadable only as their original immutable
  artifacts; their checksums and provenance must not be replaced.
- iOS is an active source track, not an RC2 release artifact.

## Deliberately Not Included

- Relay service or full-tunnel exit node.
- Private mesh DNS or hostname resolution.
- Hosted cloud control plane, team-management SaaS, or public developer API.
- Native desktop tray/GUI.
- Signed desktop/server installer and public automatic update channel.
- Independent external security audit or penetration-test certification.

## Remaining Field Gates

- Repeat Windows service-before-logon RDP validation across more environments.
- Repeat macOS LaunchDaemon and Linux systemd reboot/network-change validation.
- Complete Android Doze, long screen-off, and multi-hour RDP soak tests.
- Complete controlled 64, 100, and 255 member field validation.
- Complete independent security review and penetration testing before making
  claims that require external assurance.

## Publication Validation

Run from `v1` before publishing RC2:

```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 -WintunDir .\.run\verify-release-windows\wintun
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\release-audit.ps1 -RequireAndroid -AndroidVariant Release
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\sync-web-release.ps1
```

`RELEASE-QUALITY-GATES.md` defines the complete acceptance contract and artifact
inspection rules.
