Release v0.4.0: bump version and finalize CHANGELOG date

Bump the crate version from 0.4.0-dev to 0.4.0 and stamp the 0.4.0 CHANGELOG heading with the release date.
packaging(openwrt): default .apk WAN port to DSA name 'wan'
2026-07-30 19:46:15 +00:00 · 2026-06-27 15:57:58 +00:00 · 2026-06-26 03:31:17 +00:00 · 2026-06-21 14:40:50 +00:00 · 2026-06-21 13:45:19 +00:00 · 2026-06-20 14:56:54 +00:00
38 changed files with 2654 additions and 489 deletions
@@ -17,7 +17,7 @@ jobs:
    runs-on: ubuntu-latest

    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6

      - name: Patch PKGBUILD-git b2sums for local assets
        run: |
@@ -41,7 +41,7 @@ jobs:
          set -euo pipefail
          pacman -Sy --noconfirm --needed base-devel namcap git curl

-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6

      - name: Resolve package version
        id: ver
@@ -176,7 +176,7 @@ jobs:
          echo "version=${TAG#v}" >> "$GITHUB_OUTPUT"
          echo "pkgrel=${PKGREL}" >> "$GITHUB_OUTPUT"

-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
        with:
          ref: ${{ steps.tag.outputs.tag }}

@@ -56,7 +56,7 @@ jobs:
    name: Format check
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
      - uses: actions-rust-lang/setup-rust-toolchain@v1
        with:
          components: rustfmt
@@ -68,7 +68,7 @@ jobs:
    name: Clippy
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
      - name: Install system dependencies
        run: sudo apt-get update && sudo apt-get install -y libdbus-1-dev
      - uses: actions-rust-lang/setup-rust-toolchain@v1
@@ -77,7 +77,7 @@ jobs:
          cache: false
          rustflags: ''
      - name: Cache Cargo registry + build
-        uses: actions/cache@v4
+        uses: actions/cache@v5
        with:
          path: |
            ~/.cargo/registry
@@ -102,7 +102,7 @@ jobs:
          - os: windows-latest

    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6

      - name: Set SOURCE_DATE_EPOCH from git (Unix)
        if: runner.os != 'Windows'
@@ -130,7 +130,7 @@ jobs:
          rustflags: ''

      - name: Cache Cargo registry + build
-        uses: actions/cache@v4
+        uses: actions/cache@v5
        with:
          path: |
            ~/.cargo/registry
@@ -159,7 +159,7 @@ jobs:
      # Upload the Linux binary so integration jobs can use it without rebuilding
      - name: Upload Linux binary
        if: matrix.os == 'ubuntu-latest'
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
        with:
          name: fips-linux
          path: |
@@ -180,7 +180,7 @@ jobs:
    runs-on: ubuntu-latest
    needs: [build]
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6

      - name: Set SOURCE_DATE_EPOCH from git
        run: echo "SOURCE_DATE_EPOCH=$(git log -1 --format=%ct)" >> "$GITHUB_ENV"
@@ -195,7 +195,7 @@ jobs:
          rustflags: ''

      - name: Cache Cargo registry + build
-        uses: actions/cache@v4
+        uses: actions/cache@v5
        with:
          path: |
            ~/.cargo/registry
@@ -236,7 +236,7 @@ jobs:
    runs-on: macos-latest
    needs: [build]
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6

      - name: Set SOURCE_DATE_EPOCH from git
        run: echo "SOURCE_DATE_EPOCH=$(git log -1 --format=%ct)" >> "$GITHUB_ENV"
@@ -248,7 +248,7 @@ jobs:
          rustflags: ''

      - name: Cache Cargo registry + build
-        uses: actions/cache@v4
+        uses: actions/cache@v5
        with:
          path: |
            ~/.cargo/registry
@@ -271,7 +271,7 @@ jobs:
    name: Unit tests (Windows)
    runs-on: windows-latest
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6

      - name: Install Rust toolchain
        uses: actions-rust-lang/setup-rust-toolchain@v1
@@ -280,7 +280,7 @@ jobs:
          rustflags: ''

      - name: Cache Cargo registry + build
-        uses: actions/cache@v4
+        uses: actions/cache@v5
        with:
          path: |
            ~/.cargo/registry
@@ -309,7 +309,7 @@ jobs:
    name: PowerShell lint (Windows packaging)
    runs-on: windows-latest
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6

      - name: Run PSScriptAnalyzer
        shell: pwsh
@@ -478,11 +478,11 @@ jobs:
            type: dns-resolver

    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6

      # Fetch the pre-built Linux binary from job 1
      - name: Download Linux binary
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
        with:
          name: fips-linux
          path: _bin
@@ -668,7 +668,7 @@ jobs:

      - name: Upload sim results on failure (chaos)
        if: matrix.type == 'chaos' && failure()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
        with:
          name: sim-results-${{ matrix.scenario }}
          path: testing/chaos/sim-results/
@@ -19,7 +19,7 @@ jobs:
    outputs:
      linux_package_version: ${{ steps.linux_version.outputs.linux_package_version }}
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

@@ -61,7 +61,7 @@ jobs:
            deb_arch: arm64

    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

@@ -79,7 +79,7 @@ jobs:

      - name: Cache Cargo registry + build
        if: ${{ env.ACT != 'true' }}
-        uses: actions/cache@v4
+        uses: actions/cache@v5
        with:
          path: |
            ~/.cargo/registry
@@ -140,7 +140,7 @@ jobs:

      - name: Upload artifact (GitHub only)
        if: ${{ env.ACT != 'true' }}
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
        with:
          name: fips_${{ needs.determine-versioning.outputs.linux_package_version }}_${{ matrix.artifact_arch }}_linux
          path: |
@@ -164,7 +164,7 @@ jobs:

    steps:
      - name: Download Linux artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
        with:
          path: dist
          merge-multiple: true
@@ -19,7 +19,7 @@ jobs:
    outputs:
      macos_package_version: ${{ steps.macos_version.outputs.macos_package_version }}
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

@@ -61,7 +61,7 @@ jobs:
            target: x86_64-apple-darwin

    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

@@ -76,7 +76,7 @@ jobs:
          rustflags: ''

      - name: Cache Cargo registry + build
-        uses: actions/cache@v4
+        uses: actions/cache@v5
        with:
          path: |
            ~/.cargo/registry
@@ -209,7 +209,7 @@ jobs:
          ( cd "$(dirname "$PKG")" && shasum -a 256 "$(basename "$PKG")" | tee "$(basename "$PKG").sha256" )

      - name: Upload artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
        with:
          name: fips_${{ needs.determine-versioning.outputs.macos_package_version }}_${{ matrix.arch }}_macos
          path: |
@@ -229,7 +229,7 @@ jobs:

    steps:
      - name: Download macOS artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
        with:
          path: dist
          merge-multiple: true
@@ -283,7 +283,7 @@ jobs:

    steps:
      - name: Download macOS artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
        with:
          path: dist
          merge-multiple: true
@@ -24,9 +24,10 @@ jobs:
    runs-on: ubuntu-latest
    outputs:
      package_version: ${{ steps.version.outputs.package_version }}
+      apk_version: ${{ steps.version.outputs.apk_version }}
      release_channel: ${{ steps.channel.outputs.release_channel }}
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

@@ -35,13 +36,20 @@ jobs:
        shell: bash
        run: |
          : ${GITHUB_OUTPUT:=/tmp/github_output}
+          # package_version is the human-readable label used in artifact
+          # filenames; apk_version is the apk-tools-compatible string embedded
+          # in the .apk metadata. apk_version is built directly from the same
+          # structured inputs (tag, or commit height) — no reparse of the
+          # flattened package_version. See packaging/openwrt-apk/apk-version.sh.
          if [[ "$GITHUB_REF" == refs/tags/* ]]; then
            echo "package_version=${GITHUB_REF_NAME}" >> "$GITHUB_OUTPUT"
+            echo "apk_version=$(sh packaging/openwrt-apk/apk-version.sh tag "${GITHUB_REF_NAME}")" >> "$GITHUB_OUTPUT"
          else
            BRANCH=$(echo "$GITHUB_REF_NAME" | sed 's|/|-|g')
            HEIGHT=$(git rev-list --count HEAD)
            HASH=$(git rev-parse --short HEAD)
            echo "package_version=${BRANCH}.${HEIGHT}.${HASH}" >> "$GITHUB_OUTPUT"
+            echo "apk_version=$(sh packaging/openwrt-apk/apk-version.sh dev "${HEIGHT}")" >> "$GITHUB_OUTPUT"
          fi

      - name: Determine release channel
@@ -64,8 +72,8 @@ jobs:
            echo "release_channel=dev" >> "$GITHUB_OUTPUT"
          fi

-  build:
-    name: Build .ipk (${{ matrix.openwrt_arch }})
+  compile-binaries:
+    name: Cross-compile (${{ matrix.openwrt_arch }})
    runs-on: ubuntu-latest
    needs: determine-versioning

@@ -96,18 +104,10 @@ jobs:
            # x86 routers / VMs

    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

-      - name: Set SOURCE_DATE_EPOCH from git
-        run: echo "SOURCE_DATE_EPOCH=$(git log -1 --format=%ct)" >> "$GITHUB_ENV"
-
-      - name: Initialize
-        run: |
-          PACKAGE_FILENAME=${{ env.PACKAGE_NAME }}_${{ needs.determine-versioning.outputs.package_version }}_${{ matrix.openwrt_arch }}.ipk
-          echo "PACKAGE_FILENAME=$PACKAGE_FILENAME" >> $GITHUB_ENV
-
      - name: Install Rust toolchain (stable)
        if: matrix.rust_channel == 'stable'
        uses: actions-rust-lang/setup-rust-toolchain@v1
@@ -124,7 +124,7 @@ jobs:

      - name: Cache Cargo registry + build
        if: ${{ env.ACT != 'true' }}
-        uses: actions/cache@v4
+        uses: actions/cache@v5
        with:
          path: |
            ~/.cargo/registry
@@ -153,6 +153,64 @@ jobs:
      - name: Install llvm-strip
        run: sudo apt-get update && sudo apt-get install -y --no-install-recommends llvm

+      # Cross-compile + strip once; both the .ipk and .apk packagers consume
+      # these artifacts via --bin-dir, so the Rust build runs a single time
+      # per architecture instead of once per package format.
+      - name: Cross-compile and strip binaries
+        run: |
+          set -euo pipefail
+          cargo zigbuild --release --target ${{ matrix.rust_target }} \
+            --bin fips --bin fipsctl --bin fipstop --bin fips-gateway
+          RELEASE_DIR="target/${{ matrix.rust_target }}/release"
+          mkdir -p out
+          for b in fips fipsctl fipstop fips-gateway; do
+            llvm-strip "$RELEASE_DIR/$b" 2>/dev/null || true
+            cp "$RELEASE_DIR/$b" "out/$b"
+          done
+          ls -lh out/
+
+      - name: Upload binaries artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: fips-bins-${{ matrix.openwrt_arch }}
+          path: out/
+          retention-days: 1
+
+  build:
+    name: Build .ipk (${{ matrix.openwrt_arch }})
+    runs-on: ubuntu-latest
+    needs: [determine-versioning, compile-binaries]
+
+    strategy:
+      fail-fast: false
+      matrix:
+        # Must be a subset of compile-binaries' arches (this job consumes those
+        # binary artifacts). Currently both ship aarch64 + x86_64.
+        include:
+          - build_arch: aarch64
+            openwrt_arch: aarch64_cortex-a53
+          - build_arch: x86_64
+            openwrt_arch: x86_64
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set SOURCE_DATE_EPOCH from git
+        run: echo "SOURCE_DATE_EPOCH=$(git log -1 --format=%ct)" >> "$GITHUB_ENV"
+
+      - name: Initialize
+        run: |
+          PACKAGE_FILENAME=${{ env.PACKAGE_NAME }}_${{ needs.determine-versioning.outputs.package_version }}_${{ matrix.openwrt_arch }}.ipk
+          echo "PACKAGE_FILENAME=$PACKAGE_FILENAME" >> $GITHUB_ENV
+
+      - name: Download prebuilt binaries
+        uses: actions/download-artifact@v8
+        with:
+          name: fips-bins-${{ matrix.openwrt_arch }}
+          path: bins
+
      - name: Install nak
        shell: bash
        run: |
@@ -201,8 +259,7 @@ jobs:
      - name: Build .ipk
        env:
          PKG_VERSION: ${{ needs.determine-versioning.outputs.package_version }}
-          LLVM_STRIP: llvm-strip
-        run: ./packaging/openwrt-ipk/build-ipk.sh --arch ${{ matrix.build_arch }}
+        run: ./packaging/openwrt-ipk/build-ipk.sh --arch ${{ matrix.build_arch }} --bin-dir "$GITHUB_WORKSPACE/bins"

      - name: Install shellcheck (if missing)
        shell: bash
@@ -389,13 +446,13 @@ jobs:
      - name: SHA-256 hashes
        run: |
          echo "==> Binaries:"
-          sha256sum target/${{ matrix.rust_target }}/release/fips target/${{ matrix.rust_target }}/release/fipsctl target/${{ matrix.rust_target }}/release/fipstop
+          sha256sum bins/fips bins/fipsctl bins/fipstop
          echo "==> Package:"
          sha256sum dist/${{ env.PACKAGE_FILENAME }}

      - name: Upload artifact (GitHub only)
        if: ${{ env.ACT != 'true' }}
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
        with:
          name: ${{ env.PACKAGE_FILENAME }}
          path: dist/${{ env.PACKAGE_FILENAME }}
@@ -403,6 +460,7 @@ jobs:

      - name: Upload to Blossom
        id: blossom_upload
+        continue-on-error: true
        shell: bash
        env:
          BLOSSOM_SERVER: "https://blossom.primal.net"
@@ -410,17 +468,30 @@ jobs:
        run: |
          : ${GITHUB_OUTPUT:=/tmp/github_output}

-          UPLOAD_RESPONSE=$(nak blossom upload \
-            --server "$BLOSSOM_SERVER" \
-            --sec "$NSEC" \
-            "dist/${{ env.PACKAGE_FILENAME }}" < /dev/null)
+          FILE_HASH=""
+          for attempt in 1 2 3; do
+            if UPLOAD_RESPONSE=$(nak blossom upload \
+              --server "$BLOSSOM_SERVER" \
+              --sec "$NSEC" \
+              "dist/${{ env.PACKAGE_FILENAME }}" < /dev/null); then
+              echo "Upload response (attempt $attempt):"
+              echo "$UPLOAD_RESPONSE"
+              FILE_HASH=$(echo "$UPLOAD_RESPONSE" | jq -r '.sha256')
+              if [ -n "$FILE_HASH" ] && [ "$FILE_HASH" != "null" ]; then
+                break
+              fi
+              echo "Upload response had no sha256 (attempt $attempt)"
+            else
+              echo "Blossom upload timed out or failed (attempt $attempt)"
+            fi
+            FILE_HASH=""
+            [ "$attempt" -lt 3 ] && sleep $((attempt * 10))
+          done

-          echo "Upload response:"
-          echo "$UPLOAD_RESPONSE"
-
-          FILE_HASH=$(echo "$UPLOAD_RESPONSE" | jq -r '.sha256')
          if [ -z "$FILE_HASH" ] || [ "$FILE_HASH" = "null" ]; then
-            echo "Failed to extract hash from upload response"
+            echo "Blossom upload did not succeed after 3 attempts; non-fatal."
+            echo "The package still ships as a GitHub release artifact; only the"
+            echo "supplementary Blossom/nostr distribution is skipped this run."
            exit 1
          fi

@@ -431,6 +502,7 @@ jobs:

      - name: Publish NIP-94 release event
        id: publish
+        if: steps.blossom_upload.outcome == 'success'
        shell: bash
        env:
          RELAYS: "wss://relay.damus.io wss://nos.lol wss://nostr.mom wss://offchain.pub"
@@ -452,6 +524,7 @@ jobs:
            --tag A="${{ matrix.openwrt_arch }}" \
            --tag v="$VERSION" \
            --tag n="${{ env.PACKAGE_NAME }}" \
+            --tag format="ipk" \
            --tag compression="none" \
            > event.json 2> event.err

@@ -509,23 +582,351 @@ jobs:
          echo "  Release EventId: ${{ steps.publish.outputs.eventId }}"
          echo "  Blossom URL: ${{ steps.blossom_upload.outputs.url }}"

+  build-apk:
+    name: Build .apk (${{ matrix.openwrt_arch }})
+    runs-on: ubuntu-latest
+    needs: [determine-versioning, compile-binaries]
+
+    strategy:
+      fail-fast: false
+      matrix:
+        # Must be a subset of compile-binaries' arches.
+        include:
+          - build_arch: aarch64
+            openwrt_arch: aarch64_cortex-a53
+            # MT3000, MT6000, Flint 2, RPi 3/4/5 on OpenWrt 25+
+          - build_arch: x86_64
+            openwrt_arch: x86_64
+            # x86 routers / VMs on OpenWrt 25+
+
+    env:
+      # apk-tools commit OpenWrt pins for the .apk (ADB) format. Keep in sync
+      # with package/system/apk/Makefile in the targeted OpenWrt release so the
+      # packages we produce are readable by the apk on the device.
+      APK_TOOLS_VERSION: "3.0.5"
+      APK_TOOLS_COMMIT: "b5a31c0d865342ad80be10d68f1bb3d3ad9b0866"
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set SOURCE_DATE_EPOCH from git
+        run: echo "SOURCE_DATE_EPOCH=$(git log -1 --format=%ct)" >> "$GITHUB_ENV"
+
+      - name: Initialize
+        run: |
+          PACKAGE_FILENAME=${{ env.PACKAGE_NAME }}_${{ needs.determine-versioning.outputs.package_version }}_${{ matrix.openwrt_arch }}.apk
+          echo "PACKAGE_FILENAME=$PACKAGE_FILENAME" >> $GITHUB_ENV
+
+      - name: Download prebuilt binaries
+        uses: actions/download-artifact@v8
+        with:
+          name: fips-bins-${{ matrix.openwrt_arch }}
+          path: bins
+
+      - name: Install fakeroot
+        run: sudo apt-get update && sudo apt-get install -y --no-install-recommends fakeroot
+
+      # apk mkpkg lives in apk-tools v3, which is not packaged for Ubuntu, so we
+      # build the pinned release from source. This is the SDK-free equivalent of
+      # how the .ipk path uses plain tar — one small C tool, no OpenWrt SDK.
+      - name: Build apk-tools (${{ env.APK_TOOLS_VERSION }}) from source
+        run: |
+          set -euo pipefail
+          sudo apt-get install -y --no-install-recommends \
+            git ca-certificates build-essential meson ninja-build pkg-config \
+            zlib1g-dev libssl-dev libzstd-dev liblzma-dev lua5.4-dev scdoc
+          git clone --quiet https://gitlab.alpinelinux.org/alpine/apk-tools.git /tmp/apk-tools
+          cd /tmp/apk-tools
+          git checkout --quiet "${APK_TOOLS_COMMIT}"
+          meson setup build
+          ninja -C build src/apk
+          APK_BIN=/tmp/apk-tools/build/src/apk
+          "$APK_BIN" --version 2>/dev/null || "$APK_BIN" version 2>/dev/null || true
+          echo "APK_BIN=$APK_BIN" >> "$GITHUB_ENV"
+
+      - name: Build .apk
+        env:
+          PKG_VERSION: ${{ needs.determine-versioning.outputs.package_version }}
+          APK_VERSION: ${{ needs.determine-versioning.outputs.apk_version }}
+        run: ./packaging/openwrt-apk/build-apk.sh --arch ${{ matrix.build_arch }} --bin-dir "$GITHUB_WORKSPACE/bins"
+
+      - name: Verify apk structural integrity
+        shell: bash
+        run: |
+          set -euo pipefail
+          APK="dist/${{ env.PACKAGE_FILENAME }}"
+          if [ ! -s "$APK" ]; then
+            echo "FAIL: produced apk not found or empty at $APK"
+            exit 1
+          fi
+          echo "==> file type:"; file "$APK"
+
+          # apk v3 packages are ADB containers; dump the whole manifest with the
+          # apk-tools we just built. Print it in full so the exact schema is
+          # always visible in the log if an assertion needs adjusting.
+          DUMP=$(mktemp)
+          "$APK_BIN" adbdump "$APK" > "$DUMP" 2>/dev/null || {
+            echo "FAIL: 'apk adbdump' could not read $APK"; exit 1; }
+          echo "==> full adbdump:"; cat "$DUMP"
+
+          fail=0
+          # Package metadata (flat keys under info:).
+          for needle in "name: fips" "version: ${{ needs.determine-versioning.outputs.apk_version }}" "arch: ${{ matrix.openwrt_arch }}"; do
+            if grep -qF "$needle" "$DUMP"; then
+              echo "  PASS meta: $needle"
+            else
+              echo "  FAIL meta: missing '$needle'"; fail=1
+            fi
+          done
+
+          # installed-size reflects the bundled binaries (4 stripped Rust
+          # binaries, several MB). A payload regression that drops them shows up
+          # here regardless of how the path tree is formatted.
+          SIZE=$(awk '/^[[:space:]]*installed-size:/ {print $2; exit}' "$DUMP")
+          echo "  installed-size: ${SIZE:-unknown}"
+          if [ -z "${SIZE:-}" ] || [ "$SIZE" -lt 1000000 ]; then
+            echo "  FAIL: installed-size implausibly small (binaries missing?)"; fail=1
+          else
+            echo "  PASS: installed-size >= 1MB"
+          fi
+
+          # The adbdump paths: block is hierarchical. Each directory is a
+          # top-level list item "- name: <full relative dir>"; its files are
+          # "- name: <basename>" nested one indent level deeper under "files:".
+          # (There are no "path:" keys.) Reconstruct full file paths by keying
+          # off the indentation of the directory-level list items.
+          RECON=$(awk '
+            /^paths:/ {p=1; diri=-1; next}
+            p && /^[^ #-]/ {p=0}                 # a new top-level key ends paths:
+            !p {next}
+            match($0, /^ *- /) {
+              ind=RLENGTH; rest=substr($0, RLENGTH+1)
+              if (diri==-1) diri=ind             # first list item = directory indent
+              if (ind==diri) {                   # directory entry (or the root acl: entry)
+                if (rest ~ /^name: /) { dir=rest; sub(/^name: /,"",dir) } else dir=""
+                next
+              }
+              if (rest ~ /^name: /) {            # deeper item = a file under files:
+                f=rest; sub(/^name: /,"",f); print (dir==""?f:dir"/"f)
+              }
+            }
+          ' "$DUMP")
+          echo "==> reconstructed paths:"; printf '%s\n' "$RECON"
+
+          for path in \
+            usr/bin/fips usr/bin/fipsctl usr/bin/fipstop usr/bin/fips-gateway \
+            etc/init.d/fips etc/init.d/fips-gateway \
+            etc/fips/fips.yaml etc/fips/firewall.sh etc/dnsmasq.d/fips.conf \
+            etc/sysctl.d/fips-gateway.conf etc/sysctl.d/fips-bridge.conf \
+            etc/hotplug.d/net/99-fips etc/uci-defaults/90-fips-setup \
+            lib/upgrade/keep.d/fips; do
+            if printf '%s\n' "$RECON" | grep -qxF "$path"; then
+              echo "  PASS path: $path"
+            else
+              echo "  FAIL path: missing $path"; fail=1
+            fi
+          done
+
+          if [ "$fail" -ne 0 ]; then
+            echo "apk structural verification FAILED"
+            exit 1
+          fi
+          echo "apk structural verification PASS"
+
+      - name: SHA-256 hashes
+        run: |
+          echo "==> Binaries:"
+          sha256sum bins/fips bins/fipsctl bins/fipstop
+          echo "==> Package:"
+          sha256sum dist/${{ env.PACKAGE_FILENAME }}
+
+      - name: Upload artifact (GitHub only)
+        if: ${{ env.ACT != 'true' }}
+        uses: actions/upload-artifact@v7
+        with:
+          name: ${{ env.PACKAGE_FILENAME }}
+          path: dist/${{ env.PACKAGE_FILENAME }}
+          retention-days: 30
+
+      - name: Install nak
+        shell: bash
+        run: |
+          NAK_VERSION="0.16.2"
+          ARCH=$(uname -m)
+          case "$ARCH" in
+            x86_64|amd64) NAK_ARCH="amd64" ;;
+            aarch64|arm64) NAK_ARCH="arm64" ;;
+            *) echo "Unsupported architecture: $ARCH"; exit 1 ;;
+          esac
+          curl -fsSL "https://github.com/fiatjaf/nak/releases/download/v${NAK_VERSION}/nak-v${NAK_VERSION}-linux-${NAK_ARCH}" \
+            -o /usr/local/bin/nak
+          chmod +x /usr/local/bin/nak
+          nak --version
+
+      - name: Install jq
+        run: |
+          if ! command -v jq &>/dev/null; then
+            sudo apt-get update && sudo apt-get install -y jq
+          fi
+
+      # Priority: HIVE_CI_NSEC from env (loom job) > repo secret > generate ephemeral
+      - name: Resolve signing key
+        id: keys
+        shell: bash
+        env:
+          SECRET_NSEC: ${{ secrets.HIVE_CI_NSEC }}
+        run: |
+          : ${GITHUB_OUTPUT:=/tmp/github_output}
+          if [ -n "${HIVE_CI_NSEC:-}" ]; then
+            echo "Using HIVE_CI_NSEC from loom job environment"
+            NSEC="$HIVE_CI_NSEC"
+          elif [ -n "$SECRET_NSEC" ]; then
+            echo "Using HIVE_CI_NSEC from repository secrets"
+            NSEC="$SECRET_NSEC"
+          else
+            echo "No nsec provided -- generating ephemeral keypair"
+            NSEC=$(nak key generate)
+          fi
+
+          PUBKEY=$(echo "$NSEC" | nak key public)
+          echo "::add-mask::$NSEC"
+          echo "nsec=$NSEC" >> "$GITHUB_OUTPUT"
+          echo "pubkey=$PUBKEY" >> "$GITHUB_OUTPUT"
+          echo "Publisher pubkey (hex): $PUBKEY"
+
+      - name: Upload to Blossom
+        id: blossom_upload
+        continue-on-error: true
+        shell: bash
+        env:
+          BLOSSOM_SERVER: "https://blossom.primal.net"
+          NSEC: ${{ steps.keys.outputs.nsec }}
+        run: |
+          : ${GITHUB_OUTPUT:=/tmp/github_output}
+
+          FILE_HASH=""
+          for attempt in 1 2 3; do
+            if UPLOAD_RESPONSE=$(nak blossom upload \
+              --server "$BLOSSOM_SERVER" \
+              --sec "$NSEC" \
+              "dist/${{ env.PACKAGE_FILENAME }}" < /dev/null); then
+              echo "Upload response (attempt $attempt):"
+              echo "$UPLOAD_RESPONSE"
+              FILE_HASH=$(echo "$UPLOAD_RESPONSE" | jq -r '.sha256')
+              if [ -n "$FILE_HASH" ] && [ "$FILE_HASH" != "null" ]; then
+                break
+              fi
+              echo "Upload response had no sha256 (attempt $attempt)"
+            else
+              echo "Blossom upload timed out or failed (attempt $attempt)"
+            fi
+            FILE_HASH=""
+            [ "$attempt" -lt 3 ] && sleep $((attempt * 10))
+          done
+
+          if [ -z "$FILE_HASH" ] || [ "$FILE_HASH" = "null" ]; then
+            echo "Blossom upload did not succeed after 3 attempts; non-fatal."
+            echo "The package still ships as a GitHub release artifact; only the"
+            echo "supplementary Blossom/nostr distribution is skipped this run."
+            exit 1
+          fi
+
+          BLOSSOM_URL="${BLOSSOM_SERVER}/${FILE_HASH}"
+          echo "url=$BLOSSOM_URL" >> "$GITHUB_OUTPUT"
+          echo "hash=$FILE_HASH" >> "$GITHUB_OUTPUT"
+          echo "Uploaded to Blossom: $BLOSSOM_URL"
+
+      - name: Publish NIP-94 release event
+        id: publish
+        if: steps.blossom_upload.outcome == 'success'
+        shell: bash
+        env:
+          RELAYS: "wss://relay.damus.io wss://nos.lol wss://nostr.mom wss://offchain.pub"
+          NSEC: ${{ steps.keys.outputs.nsec }}
+        run: |
+          : ${GITHUB_OUTPUT:=/tmp/github_output}
+          set -e
+
+          VERSION="${{ needs.determine-versioning.outputs.package_version }}"
+          CHANNEL="${{ needs.determine-versioning.outputs.release_channel }}"
+
+          nak event --sec "$NSEC" -k 1063 \
+            -c "FIPS Package: ${{ env.PACKAGE_NAME }} for ${{ matrix.openwrt_arch }} (apk)" \
+            --tag url="${{ steps.blossom_upload.outputs.url }}" \
+            --tag m="application/octet-stream" \
+            --tag x="${{ steps.blossom_upload.outputs.hash }}" \
+            --tag ox="${{ steps.blossom_upload.outputs.hash }}" \
+            --tag filename="${{ env.PACKAGE_FILENAME }}" \
+            --tag A="${{ matrix.openwrt_arch }}" \
+            --tag v="$VERSION" \
+            --tag n="${{ env.PACKAGE_NAME }}" \
+            --tag format="apk" \
+            --tag compression="none" \
+            > event.json 2> event.err
+
+          if [ ! -s event.json ]; then
+            echo "Failed to create event"
+            cat event.err 2>/dev/null || true
+            exit 1
+          fi
+
+          echo "=== Event JSON ==="
+          cat event.json
+          echo "=================="
+
+          EVENT_ID=$(jq -r '.id' event.json)
+          if [ -z "$EVENT_ID" ] || [ "$EVENT_ID" = "null" ]; then
+            echo "Failed to extract event ID"
+            exit 1
+          fi
+
+          # Publish to relays
+          cat event.json | nak event $RELAYS 2>&1
+
+          echo "eventId=$EVENT_ID" >> "$GITHUB_OUTPUT"
+          echo "Published NIP-94 event: $EVENT_ID"
+
+      - name: Build Summary
+        run: |
+          echo "Build Summary for ${{ matrix.openwrt_arch }} (apk):"
+          echo "  Package: ${{ env.PACKAGE_FILENAME }}"
+          echo "  apk version: ${{ needs.determine-versioning.outputs.apk_version }}"
+          echo "  Release EventId: ${{ steps.publish.outputs.eventId }}"
+          echo "  Blossom URL: ${{ steps.blossom_upload.outputs.url }}"
+
  release:
    name: Publish GitHub Release (github only)
    runs-on: ubuntu-latest
-    needs: build
+    needs: [build, build-apk]
    if: startsWith(github.ref, 'refs/tags/')
    permissions:
      contents: write

    steps:
-      - name: Download all .ipk artifacts
-        uses: actions/download-artifact@v4
+      - name: Download package artifacts
+        uses: actions/download-artifact@v8
        with:
+          # Only the .ipk/.apk packages (named fips_<ver>_<arch>.*), not the
+          # fips-bins-* raw-binary artifacts shared between the build jobs.
+          pattern: fips_*
          path: dist
          merge-multiple: true

+      - name: Generate OpenWrt release checksums
+        run: |
+          cd dist
+          find . -maxdepth 1 -type f \( -name '*.ipk' -o -name '*.apk' \) -printf '%P\n' \
+            | LC_ALL=C sort \
+            | xargs sha256sum \
+            > checksums-openwrt.txt
+
      - name: Create release
        uses: softprops/action-gh-release@v2
        with:
-          files: dist/*.ipk
+          files: |
+            dist/*.ipk
+            dist/*.apk
+            dist/checksums-openwrt.txt
          generate_release_notes: true
@@ -19,7 +19,7 @@ jobs:
    outputs:
      package_version: ${{ steps.version.outputs.package_version }}
    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

@@ -52,7 +52,7 @@ jobs:
    needs: determine-versioning

    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

@@ -69,7 +69,7 @@ jobs:
          rustflags: ''

      - name: Cache Cargo registry + build
-        uses: actions/cache@v4
+        uses: actions/cache@v5
        with:
          path: |
            ~/.cargo/registry
@@ -146,7 +146,7 @@ jobs:
          }

      - name: Upload artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
        with:
          name: fips_${{ needs.determine-versioning.outputs.package_version }}_x86_64_windows
          path: deploy/fips-*-windows-*.zip
@@ -170,7 +170,7 @@ jobs:

    steps:
      - name: Download Windows artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
        with:
          path: dist
          merge-multiple: true
@@ -9,6 +9,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 ### Added

+### Changed
+
+### Fixed
+
+## [0.4.0] - 2026-06-27
+
+### Added
+
+#### Transports (Nym, mDNS LAN discovery)
+
 - Nym mixnet transport (`transports.nym`) for outbound peer links
  tunneled through a local `nym-socks5-client` SOCKS5 proxy into the
  Nym mixnet, as a privacy transport alongside Tor. Outbound-only and
@@ -16,6 +26,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  crate dependencies. A single-container example
  (`examples/sidecar-nostr-mixnet-relay/`) demonstrates FIPS peering
  across the mixnet end to end.
+- Opt-in mDNS / DNS-SD LAN discovery for sub-second pairing of peers on
+  the same local link, without a relay or NAT-traversal roundtrip.
+  Disabled by default; operators enable it with
+  `node.discovery.lan.enabled: true`. Configurable service type and an
+  optional `node.discovery.lan.scope` that isolates discovery to peers
+  sharing the same private-network scope. The advertised UDP port is
+  chosen from a non-bootstrap operational UDP transport using a stable
+  selector, so it is deterministic across restarts.
+
+#### Admission / peer-list management
+
+- `Node::update_peers` for runtime peer-list refresh, returning an
+  `UpdatePeersOutcome` summarizing added, removed, and retained peers.
+  Re-derives active peer connections from a new peer configuration
+  without dropping links to peers that remain in the set.
+  `PeerAddress` gains a `seen_at_ms` recency field (with
+  `with_seen_at_ms`) used to prefer more recently observed addresses.
+
+#### Data-plane / metrics / observability
+
 - Typed `RejectReason` classification for receive-path silent-rejection
  sites across the node. Each rejection-and-return path now passes a
  typed reason to `NodeStats::record_reject`, which routes it to a
@@ -28,47 +58,73 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  site that was previously silent. Several handshake, MMP, tree, and
  discovery rejection paths that had no counter at all are now counted,
  including the `send_lookup_response` no-route drop
-  (`DiscoveryStats::resp_no_route`). Existing
-  direct counters at the bloom / discovery / forwarding sites are
-  retained alongside the new dispatch while the rollout is in progress;
-  a later change collapses the duplicate increment.
+  (`DiscoveryStats::resp_no_route`).
 - Internal atomic metric registry (`Arc<MetricsRegistry>`) that shadows
  the plain-`u64` `NodeStats` counters, written alongside them and
  validated by a whole-struct debug-build parity check. Covers the
  forwarding receive counters, the full discovery counter family, and the
-  tree, bloom, congestion, and error-signal counter families so far, with
+  tree, bloom, congestion, and error-signal counter families, with
  the hottest counters cache-line padded. Behavior-neutral:
  `NodeStats` remains the serving path. Groundwork for sampling metrics
  without contending the receive loop.
- `Node::update_peers` for runtime peer-list refresh, returning an
-  `UpdatePeersOutcome` summarizing added, removed, and retained peers.
-  Re-derives active peer connections from a new peer configuration
-  without dropping links to peers that remain in the set.
-  `PeerAddress` gains a `seen_at_ms` recency field (with
-  `with_seen_at_ms`) used to prefer more recently observed addresses.
- Opt-in mDNS / DNS-SD LAN discovery for sub-second pairing of peers on
-  the same local link, without a relay or NAT-traversal roundtrip.
-  Disabled by default; operators enable it with
-  `node.discovery.lan.enabled: true`. Configurable service type and an
-  optional `node.discovery.lan.scope` that isolates discovery to peers
-  sharing the same private-network scope. The advertised UDP port is
-  chosen from a non-bootstrap operational UDP transport using a stable
-  selector, so it is deterministic across restarts.
+- `fipsctl stats metrics`, backed by a new counter-only `show_metrics`
+  control query that dumps the atomic metric registry as flat counter
+  name/value pairs. Serves a Prometheus-style scraper that samples node
+  counters without contending the receive loop.
 - `pool_inbound` and `pool_outbound` counters on the TCP and Tor
  transport stats (`TcpStats`, `TorStats`). Per-direction accounting
  is updated at every pool-insert and receive-loop-exit site, plus on
  transport stop and on send-failure-driven removal. Surfaces through
  `TcpStatsSnapshot` and `TorStatsSnapshot` for `show_transports`.
- `fipsctl stats metrics`, backed by a new counter-only `show_metrics`
-  control query that dumps the atomic metric registry as flat counter
-  name/value pairs. Serves a Prometheus-style scraper that samples node
-  counters without contending the receive loop.
+
+#### Spanning-tree / mesh-size / routing
+
+- Six route-class transit counters that partition transit-forwarded
+  packets by their tree relationship to the chosen next hop: tree-up
+  (peer is our ancestor), tree-down (peer is our descendant and the
+  destination is within its subtree), tree-down-cross (peer is our
+  descendant but the destination is outside its subtree), cross-link
+  descend (lateral peer, destination within its subtree), cross-link
+  ascend (lateral peer, destination outside its subtree), and
+  direct-peer. The six classes sum to `forwarded_packets` (asserted by a
+  unit test) and are computed from tree coordinates at the transit
+  chokepoint, so error-signal routing callers are excluded. They surface
+  through the forwarding stats snapshot via `show_routing` and
+  `show_status`.
 - Discovery now counts `LookupRequest`s dropped when the dedup cache is
  full. A saturated `recent_requests` cache
  (`MAX_RECENT_DISCOVERY_REQUESTS`) previously dropped requests
  silently; a new `DiscoveryStats::req_dedup_cache_full` counter (typed
  reject reason `DiscoveryReject::ReqDedupCacheFull`) makes the drop
  visible through `show_routing`.
+
+#### Packaging & deployment
+
+- OpenWrt `.apk` packaging (`packaging/openwrt-apk/`, `make apk`) for
+  OpenWrt 25+, where apk-tools is the mandatory package manager (the
+  existing `.ipk` continues to cover OpenWrt 24.x and earlier). Built
+  SDK-free: it reuses the `.ipk` cross-compile (`cargo-zigbuild`) and the
+  shared installed-filesystem payload, and assembles the package with
+  `apk mkpkg` from apk-tools 3.0.5 built from source — no OpenWrt SDK
+  image. A `build-apk` CI job (aarch64, x86_64) builds and structurally
+  verifies the package; releases now publish `.apk` artifacts and
+  checksums alongside `.ipk`. Packages are unsigned, installed with
+  `apk add --allow-untrusted`, matching the `.ipk` posture.
+- Nix flake (`flake.nix` at the project root) for reproducible
+  from-source builds on Nix/NixOS. Builds all four binaries (`fips`,
+  `fipsctl`, `fips-gateway`, `fipstop`), pins the exact toolchain from
+  `rust-toolchain.toml` via fenix, and wires the build-time native
+  dependencies (`libclang` for `bindgen`, plus `dbus` and `pkg-config`),
+  so it needs no host setup beyond Nix with flakes enabled. Flake inputs
+  are lock-pinned (`flake.lock` committed) for reproducibility, and the
+  flake exposes `nix build`, `nix run`, a `nix develop` dev shell with the
+  pinned toolchain, and `nix flake check`. The flake produces binaries
+  (and a NixOS `packages.<system>.fips` output); the systemd/service
+  integration that the `.deb`/tarball installers provide is handled
+  through the NixOS configuration instead.
+
+#### Docs & contributor tooling
+
 - [`PR-REVIEW.md`](PR-REVIEW.md) — the 13-criteria PR review checklist
  the maintainer runs against every incoming PR, published at the
  repo root so contributors can run the same pass on their own change
@@ -90,17 +146,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 ### Changed

+#### FMP/FSP rekey reliability
+
 - `complete_rekey_msg2` now returns the remote peer's startup epoch
  alongside the new Noise session, so the rekey path can detect a peer
  restart and clear stale session state.
- Active-peer path selection now sorts address candidates by recency
-  (`seen_at_ms`), preferring the most recently observed address when
-  racing concurrent path probes.
- Per-tick work budgets bound the connection churn done in a single
-  node tick: `MAX_DISCOVERY_CONNECTS_PER_TICK`,
-  `MAX_RETRY_CONNECTIONS_PER_TICK`, and
-  `MAX_PARALLEL_PATH_CANDIDATES_PER_PEER`. Work beyond a tick's budget
-  is deferred to the next tick rather than discarded.
+
+#### NAT traversal / Nostr discovery
+
 - Nostr discovery startup is now non-blocking. `Node::start` no
  longer waits for relay connect, subscribe, or initial advert
  publish before returning. A slow or unreachable relay no longer
@@ -109,6 +162,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  Subscribe retries with exponential backoff (2 s base, 60 s cap),
  publish attempts time out at 10 s, and the new tasks are aborted
  cleanly on `Node::stop`.
+
+#### Spanning-tree / mesh-size / routing
+
+- Active-peer path selection now sorts address candidates by recency
+  (`seen_at_ms`), preferring the most recently observed address when
+  racing concurrent path probes.
+- Per-tick work budgets bound the connection churn done in a single
+  node tick: `MAX_DISCOVERY_CONNECTS_PER_TICK`,
+  `MAX_RETRY_CONNECTIONS_PER_TICK`, and
+  `MAX_PARALLEL_PATH_CANDIDATES_PER_PEER`. Work beyond a tick's budget
+  is deferred to the next tick rather than discarded.
+
+#### Admission / peer caps
+
 - `node.bloom.max_inbound_fpr` default raised from `0.05` to `0.10`. The
  cap rejects inbound `FilterAnnounce` whose FPR (`fill^k`) exceeds it. On
  the fixed 1 KB / k=5 filter, `0.05` corresponds to fill 0.549 (~1,300
@@ -124,6 +191,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  per-transport `max_inbound_connections`, then node-wide
  `max_connections`, then the built-in default of 256. Established peers
  remain bounded node-wide by `add_connection`.
+
+#### Data-plane / worker-pool / metrics / observability
+
 - The control-socket read surface is now served off the `rx_loop`.
  Every pure-read `show_*` query — `show_status`, the `show_stats_*`
  family, `show_listening_sockets`, the new `show_metrics`,
@@ -148,11 +218,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  snapshot fields above. Built on a ratatui `TestBackend`
  render-snapshot harness that asserts the text grid and per-cell
  style of every `ui::draw_*` against canned `show_*` JSON.
- Static host aliases in `/etc/fips/hosts` now hot-reload on mtime
-  change instead of only at daemon startup, so `fipsctl`/`fipstop`
-  display names reflect edits without a restart. The peer ACL and host
-  map both reload once per node tick through a new lock-free
-  `Reloadable` snapshot.
 - Steady-state log noise reduced on saturated public-mesh nodes.
  Routine per-peer connection-lifecycle and capacity-cap events are
  demoted from info/warn to debug — FMP K-bit cutover promotion,
@@ -163,43 +228,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  are no longer drowned out. An exhausted FMP-msg1 / FSP-msg3 rekey
  retransmission-budget abort (an expected, self-limiting outcome on
  lossy or high-latency links) is likewise demoted from warn to debug.
- Sidecar example (`examples/sidecar-nostr-relay`): `udp.mtu` is now
-  overridable via the `FIPS_UDP_MTU` environment variable, defaulting to
-  1472 (preserving prior behavior). Plumbed through `docker-compose.yml`
-  and documented in the README env-var table. Annotated the static-CI
-  node template `mtu: 1472` literal with the same Docker-bridge
-  rationale and a pointer at the daemon's 1280 default.
- Overhauled `CONTRIBUTING.md`: replaced generic Rust-template framing
-  with a FIPS-specific entry point covering the four-layer
-  architecture, branch model and PR-target selection, structured bug
-  reporting, scope discipline and local-CI requirements, an AI coding
-  assistant policy, and project communication channels. Added
-  `docs/branching.md` as the long-form companion covering the release
-  workflow, version conventions, and merge-direction rationale.
- CI and release-publish workflows hardened:
-  - `ci.yml` declares a top-level `concurrency` block keyed on
-    `(workflow, ref)` with `cancel-in-progress: true`. Force-pushes
-    and rapid successive pushes to the same ref now retire any
-    in-flight run rather than letting superseded and current-tip runs
-    both burn runner minutes.
-  - `aur-publish.yml` rewritten to fetch the upstream source tarball
-    and compute its `b2sum` in CI, then patch `pkgver` and the
-    `b2sums` SKIP placeholder in `PKGBUILD` in-place. Previously
-    `updpkgsums: true` downloaded the tarball into the AUR working
-    tree, where it was rejected by AUR's 488 KiB max-blob hook —
-    silently no-op'ing the v0.3.0 stable AUR push. `fips.sysusers` /
-    `fips.tmpfiles` asset b2sums are recomputed in the same step to
-    stay in sync with the local files. `workflow_dispatch` gains a
-    tag input so historical release tags can be re-published
-    manually, and `continue-on-error: true` is dropped so future
-    regressions surface in CI.
-  - New `aur-publish-git.yml` workflow for the `fips-git` VCS
-    PKGBUILD, triggered on master pushes touching `PKGBUILD-git` or
-    companion files plus `workflow_dispatch`. `pkgver` is computed at
-    build time by the PKGBUILD's `pkgver()` function, so this workflow
-    is not tied to release tags.
-  - Tag-triggered `package-*` release-build workflows remain
-    untouched.
 - macOS UDP receive path now batches up to 32 datagrams per kernel
  wakeup via `recvmsg_x(2)`, matching the Linux `recvmmsg(2)`
  amortization shape introduced in v0.3.0. Previously macOS fell
@@ -272,6 +300,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  and the connected-UDP drain no longer busy-spins on a poll error
  (#106).

+#### Transports & config
+
+- Static host aliases in `/etc/fips/hosts` now hot-reload on mtime
+  change instead of only at daemon startup, so `fipsctl`/`fipstop`
+  display names reflect edits without a restart. The peer ACL and host
+  map both reload once per node tick through a new lock-free
+  `Reloadable` snapshot.
+- Sidecar example (`examples/sidecar-nostr-relay`): `udp.mtu` is now
+  overridable via the `FIPS_UDP_MTU` environment variable, defaulting to
+  1472 (preserving prior behavior). Plumbed through `docker-compose.yml`
+  and documented in the README env-var table. Annotated the static-CI
+  node template `mtu: 1472` literal with the same Docker-bridge
+  rationale and a pointer at the daemon's 1280 default.
+
+#### Packaging & deployment
+
 - The Debian package no longer ships `/etc/fips/fips.yaml` as a dpkg
  conf-file. The default configuration is installed as an example at
  `/usr/share/fips/fips.yaml.example`, and `postinst` seeds
@@ -283,6 +327,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  example is placed under `/usr/share/fips`, deliberately outside
  `/usr/share/doc`, which minimal and container installs path-exclude
  (so the install-time seed source is never dropped).
+- openwrt: the `.apk` package now defaults `ethernet.wan` to the
+  OpenWrt 25 DSA port name `wan`; the `.ipk` package keeps `eth0` for
+  OpenWrt 24 and earlier.
+
+#### CI & test-harness reliability
+
+- CI and release-publish workflows hardened:
+  - `ci.yml` declares a top-level `concurrency` block keyed on
+    `(workflow, ref)` with `cancel-in-progress: true`. Force-pushes
+    and rapid successive pushes to the same ref now retire any
+    in-flight run rather than letting superseded and current-tip runs
+    both burn runner minutes.
+  - `aur-publish.yml` rewritten to fetch the upstream source tarball
+    and compute its `b2sum` in CI, then patch `pkgver` and the
+    `b2sums` SKIP placeholder in `PKGBUILD` in-place. Previously
+    `updpkgsums: true` downloaded the tarball into the AUR working
+    tree, where it was rejected by AUR's 488 KiB max-blob hook —
+    silently no-op'ing the v0.3.0 stable AUR push. `fips.sysusers` /
+    `fips.tmpfiles` asset b2sums are recomputed in the same step to
+    stay in sync with the local files. `workflow_dispatch` gains a
+    tag input so historical release tags can be re-published
+    manually, and `continue-on-error: true` is dropped so future
+    regressions surface in CI.
+  - New `aur-publish-git.yml` workflow for the `fips-git` VCS
+    PKGBUILD, triggered on master pushes touching `PKGBUILD-git` or
+    companion files plus `workflow_dispatch`. `pkgver` is computed at
+    build time by the PKGBUILD's `pkgver()` function, so this workflow
+    is not tied to release tags.
+  - Tag-triggered `package-*` release-build workflows remain
+    untouched.
 - Local and GitHub CI integration coverage brought into parity, and
  the Rust toolchain selection given a single source of truth:
  - The `admission-cap` integration suite, previously run only by
@@ -305,39 +379,70 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
    `-D warnings` is newly imposed. The OpenWrt nightly Tier-3 leg
    keeps `@nightly`.

+#### Docs & contributor tooling
+
+- Overhauled `CONTRIBUTING.md`: replaced generic Rust-template framing
+  with a FIPS-specific entry point covering the four-layer
+  architecture, branch model and PR-target selection, structured bug
+  reporting, scope discipline and local-CI requirements, an AI coding
+  assistant policy, and project communication channels. Added
+  `docs/branching.md` as the long-form companion covering the release
+  workflow, version conventions, and merge-direction rationale.
+
 ### Fixed

- The Tor transport now increments its `connect_refused` statistic (the
-  "Refused" line in fipstop) when a SOCKS5 connection is actively
-  refused, instead of recording every connect failure as a generic
-  SOCKS5 error. The counter previously stayed at zero.
- MMP sender metrics now ignore duplicate or regressed receiver reports
-  before updating RTT, loss, goodput, or ETX. Receiver reports also
-  suppress timestamp echo when dwell time overflows, so stale reports
-  cannot inflate SRTT.
- Six discovery counters (`req_decode_error`, `req_duplicate`,
-  `req_ttl_exhausted`, `resp_decode_error`, `resp_identity_miss`,
-  `resp_proof_failed`) no longer double-count. Each was incremented both
-  by a direct bump and again through the typed reject dispatch; the
-  redundant direct increment is removed, so each counts once per event.
- Six bloom counters (`decode_error`, `invalid`, `non_v1`,
-  `unknown_peer`, `stale`, `fill_exceeded`) no longer double-count. Each
-  was incremented both by a direct bump and again through the typed
-  reject dispatch; the redundant direct increment is removed, so each
-  counts once per event.
- Five forwarding reject packet counters (`decode_error_packets`,
-  `ttl_exhausted_packets`, `drop_no_route_packets`,
-  `drop_mtu_exceeded_packets`, `drop_send_error_packets`) no longer
-  double-count. Each was incremented both by the byte-aware outcome
-  recorder and again through the typed reject dispatch; the two calls are
-  collapsed into a single byte-aware reject entry point, so packets and
-  bytes each count once per event.
+#### FMP/FSP rekey reliability
+
+- FMP link-layer rekey is now reliable under packet loss, bringing it up
+  to the FSP session layer's rekey discipline. The rekey msg1
+  retransmission driver was previously uncapped and never abandoned, so a
+  rekey that never completed resent msg1 forever; it now uses a bounded
+  retransmission budget (`handshake_max_resends` with exponential
+  backoff) and abandons the rekey cycle cleanly once the budget is
+  exhausted, mirroring the FSP rekey msg3 driver. With the cap in place
+  the link-dead heartbeat is rekey-aware: `check_link_heartbeats` no
+  longer reaps a link that is still actively carrying rekey-handshake
+  traffic, while a genuinely dead link is still reaped once the budget
+  abandons. At the K-bit cutover the receiver now authenticates an
+  inbound frame against the pending session before promoting it, instead
+  of promoting on the bare header K-bit; under jitter a node could
+  otherwise promote a stale pending session, leaving the two endpoints on
+  different keys and silently dropping traffic until the link died — the
+  same failure class already closed on FSP, now closed on FMP.
+- FSP session rekey is now hitless under packet loss and reordering.
+  Previously, a rekey could leave the two endpoints holding different
+  key sets for a brief window — if a handshake message was lost in
+  transit one side rotated keys while the other did not, and traffic
+  sealed in one key epoch reached a peer still on the other epoch and
+  failed to decrypt, producing bursts of AEAD decryption failures and
+  dropped connectivity until a later rekey reconverged the pair. The
+  receive path now trial-decrypts each frame against every live key
+  epoch (current, pending, and the draining previous session) for the
+  duration of the rekey transition, so no rotation ordering and no
+  packet reordering can cause a decryption failure. The previous-epoch
+  slot is retained as long as the peer keeps using it, with its drain
+  deadline anchored on the last frame the peer authenticates against
+  it rather than a fixed wall-clock timer, so a peer that did not
+  receive the new keys is not stranded by a silent permanent decrypt
+  failure. The lost-handshake case is closed by retransmitting the
+  third rekey handshake message until the peer is confirmed on the
+  new keys, with a bounded retry budget after which the rekey cycle
+  is cleanly abandoned and retried. There are no FSP decryption
+  failures across a rekey under lossy, jittery links.
+- ±15s symmetric jitter is applied per session to the FMP and FSP rekey
+  timer trigger, eliminating the steady-state dual-initiation race in
+  symmetric-start meshes (previously the smaller-NodeAddr tie-breaker
+  resolved correctness only after every cycle's collision).
+  `node.rekey.after_secs` becomes the nominal interval rather than a
+  floor; the mean is preserved.
 - A stale FSP (session-layer) session is now cleared when a peer
  restart is detected during FMP rekey or cross-connection promotion.
  Previously the old session could linger after the peer came back
  with a new startup epoch, leaving the session-layer map out of sync
  with the freshly promoted peer.

+#### NAT traversal / Nostr discovery
+
 - Two nodes that each `auto_connect` to the other no longer stall their
  Nostr-mediated NAT-traversal handshake. Each side ran both an
  initiator and a responder traversal session, binding a separate UDP
@@ -350,43 +455,55 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  its own NodeAddr is smaller — so one matching socket pair survives on
  both ends and the peer's redundant initiator times out harmlessly.
  One-sided (asymmetric) `auto_connect` has no co-active initiator and is
-  never suppressed, so connectivity is preserved. (Distinct from the
-  cross-init adoption tie-breaker below, which dedups two simultaneous
-  punches but does not stop each node from running redundant
-  initiator + responder sessions.)
- FMP link-layer rekey is now reliable under packet loss, bringing it up
-  to the FSP session layer's rekey discipline:
-  - The rekey msg1 retransmission driver was uncapped and never
-    abandoned, so a rekey that never completed resent msg1 forever. It
-    now uses a bounded retransmission budget (`handshake_max_resends`
-    with exponential backoff) and abandons the rekey cycle cleanly once
-    the budget is exhausted, mirroring the FSP rekey msg3 driver. With
-    the cap in place the link-dead heartbeat is rekey-aware:
-    `check_link_heartbeats` no longer reaps a link that is still
-    actively carrying rekey-handshake traffic, while a genuinely dead
-    link is still reaped once the budget abandons.
-  - At the K-bit cutover the receiver now authenticates an inbound frame
-    against the pending session before promoting it, instead of
-    promoting on the bare header K-bit. Under jitter a node could
-    otherwise promote a stale pending session, leaving the two endpoints
-    on different keys and silently dropping traffic until the link died
-    — the same failure class already closed on FSP, now closed on FMP.
- Node-level multi-node tests no longer flake under parallel CPU load.
-  They previously delivered handshake packets over real localhost UDP,
-  whose kernel receive buffer could overflow and drop a packet when many
-  tests ran concurrently, panicking the large-network convergence tests.
-  A `cfg(test)`-only loopback `TransportHandle` variant now delivers
-  packets directly between nodes over an unbounded in-process channel, so
-  there is no socket buffer to overflow, and the previously-quarantined
-  large-network tests run in the default suite again. The shipping daemon
-  build is unaffected (the variant is test-gated).
- Integration suites that wait for the mesh to converge no longer
-  false-fail under concurrent CI load. The rekey, static-mesh, and
-  sidecar suites replace a fixed wall-clock baseline timeout (and a blind
-  sleep) with a progress-aware wait that polls the suite's own pairwise
-  pings, returns as soon as every pair is reachable, extends its deadline
-  while the reachable-pair count is still climbing, and gives up only
-  when progress stalls.
+  never suppressed, so connectivity is preserved.
+- NAT-traversal cross-init adoption is now deterministic under
+  simultaneous dual-initiation. Previously, when two peers'
+  Nostr-mediated UDP punches completed within the same scheduling
+  window, each side's bootstrap-completion event arrived with an
+  in-flight handshake already recorded against the other peer (each
+  side had received an inbound msg1 from the other's pre-punch
+  outbound attempt). The deduplication skip then fired on both
+  sides, neither installed the fresh traversal socket as canonical,
+  and the 45-second peer-adoption budget expired with both nodes
+  stuck waiting for an adoption that never happened. The handler now
+  applies the same deterministic NodeAddr tie-breaker the codebase
+  already uses for rekey dual-initiation and cross-connection
+  resolution: the smaller NodeAddr wins as adopter, tears down its
+  in-flight handshake state, and proceeds with adoption; the larger
+  NodeAddr keeps the skip semantics, and its in-flight outbound is
+  reconciled by the cross-connection logic when the winner's fresh
+  msg1 arrives over the adopted socket. The dual cross-init stall is
+  eliminated; cross-init NAT-traversal completes in well under a
+  second even under host CPU contention.
+- Nostr-discovered NAT-traversal events (`BootstrapEvent::Established`
+  and `BootstrapEvent::Failed`) for peers that are already connected
+  or actively handshaking are now short-circuited at the
+  `poll_nostr_discovery` dispatch sites before any cooldown
+  bookkeeping or fallback retry scheduling runs. Stale `Failed` events
+  previously poisoned the per-peer failure-state cooldown of healthy
+  peers and could trigger redundant retraversal attempts via
+  `schedule_retry` / `try_peer_addresses`; stale `Established`
+  handoffs could attempt to adopt a second socket against a live
+  connection. A defense-in-depth guard was added to
+  `adopt_established_traversal` so the same invariant holds if a
+  future caller bypasses the outer dispatch check. As a side benefit,
+  narrows a cooldown-poisoning vector previously available to an
+  attacker injecting stale failure events for an active peer.
+- Nostr discovery now filters unroutable direct UDP/TCP advert
+  endpoints. Publisher and validator retain only endpoints that parse as
+  concrete socket addresses with routable IPs and nonzero ports;
+  `udp:nat` rendezvous endpoints and Tor endpoints pass through
+  unchanged. Adverts that collapse to zero usable endpoints after
+  filtering are rejected with a clear "missing publicly routable
+  endpoints" error. Before this change, misconfigured nodes could
+  publish RFC1918, loopback, link-local, CGNAT 100.64/10, IPv6 ULA,
+  or IPv6 link-local endpoints into Nostr discovery, and consumers
+  would cache and dial them; in mixed LAN/VPN/NAT environments, that
+  could prefer a misleading one-way private path over the intended
+  `udp:nat` bootstrap.
+
+#### Admission / peer caps
+
 - TCP and Tor `max_inbound_connections` admission cap is now compared
  against the per-direction inbound count (`pool_inbound`) rather than
  the combined pool size. Outbound connect-on-send connections share
@@ -415,10 +532,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  reconnect / cross-connection bypass for known peers still fires) and
  before index allocation + Msg2 wire send. The late cap check inside
  `promote_connection` is intentionally retained as
-  defense-in-depth. Wire savings observed in a 45 s ops tcpdump at
+  defense-in-depth. Wire savings observed in a 45 s tcpdump at
  saturation: ~3.6 cap-denials/s × Msg2 (~104 B + AEAD compute) each.
  Bigger win is cleaner peer-side semantics — no fake-completed
  handshake whose subsequent data frames fail decryption on this side.
+
+#### Spanning-tree / mesh-size / routing
+
 - The mesh-size estimator (`compute_mesh_size`) no longer over-counts
  under filter overlap. It previously summed the per-filter cardinality
  of the parent and each child filter, which assumes the filters are
@@ -429,12 +549,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  nearly-but-not-exactly doubling during rebalancing). The estimator now
  computes the cardinality of the OR-union over self plus every
  connected peer's inbound filter, dropping the parent/child tree gating
-  entirely.
-  OR is idempotent, so any overlap is deduplicated — the result equals
-  the old sum in the disjoint case, stays correct under overlap, damps
-  the parent-switch flap, and removes the estimate's dependence on
-  tree-declaration cache freshness. The per-peer 500 ms rate-limiter and
-  overall recompute cadence are unchanged.
+  entirely. OR is idempotent, so any overlap is deduplicated — the
+  result equals the old sum in the disjoint case, stays correct under
+  overlap, damps the parent-switch flap, and removes the estimate's
+  dependence on tree-declaration cache freshness. The per-peer 500 ms
+  rate-limiter and overall recompute cadence are unchanged.
 - Spanning-tree state distribution is now eventually-consistent.
  Previously every `send_tree_announce_to_all` call site fired only
  on a local state-change event (parent switch, self-root promotion,
@@ -472,7 +591,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  that peer, provoking the better-rooted peer to re-push its real
  position immediately. The echo fires only in that one direction and is
  bounded by the existing per-peer rate limiter.
-
+- Coord cache invalidation made surgical at parent-position-change
+  and root-change sites. Replaces the previous unconditional
+  `CoordCache::clear()` calls with two targeted methods:
+  `invalidate_via_node(node_addr)` (drops entries whose cached
+  ancestry contains the changed node, used at parent-switch /
+  become-root / loop-detection sites) and `invalidate_other_roots`
+  (drops entries from a different tree, used at root-change sites).
+  The previous global flush left `find_next_hop` returning `None`
+  for every non-direct-peer destination after every parent switch
+  until the cache passively re-warmed; surgical invalidation
+  preserves entries that remain correct across the topology change.
+  Peer-removal retains the original "no invalidation" behavior
+  (`find_next_hop` already recomputes against the current peer set
+  every call, and Discovery handles "no route" on demand).
 - `rx_loop` tick-arm stall under convergence-phase mesh pressure
  is eliminated. Previously, the tick body's per-peer `check_*`
  loops (heartbeats, bloom announces, MMP reports, tree announces)
@@ -504,45 +636,133 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  synchronous connect (e.g., explicit operator-driven
  `fipsctl connect`); the tick path just no longer trips it.

- NAT-traversal cross-init adoption is now deterministic under
-  simultaneous dual-initiation. Previously, when two peers'
-  Nostr-mediated UDP punches completed within the same scheduling
-  window, each side's bootstrap-completion event arrived with an
-  in-flight handshake already recorded against the other peer (each
-  side had received an inbound msg1 from the other's pre-punch
-  outbound attempt). The deduplication skip then fired on both
-  sides, neither installed the fresh traversal socket as canonical,
-  and the 45-second peer-adoption budget expired with both nodes
-  stuck waiting for an adoption that never happened. The handler now
-  applies the same deterministic NodeAddr tie-breaker the codebase
-  already uses for rekey dual-initiation and cross-connection
-  resolution: the smaller NodeAddr wins as adopter, tears down its
-  in-flight handshake state, and proceeds with adoption; the larger
-  NodeAddr keeps the skip semantics, and its in-flight outbound is
-  reconciled by the cross-connection logic when the winner's fresh
-  msg1 arrives over the adopted socket. The dual cross-init stall is
-  eliminated; cross-init NAT-traversal completes in well under a
-  second even under host CPU contention.
- FSP session rekey is now hitless under packet loss and reordering.
-  Previously, a rekey could leave the two endpoints holding different
-  key sets for a brief window — if a handshake message was lost in
-  transit one side rotated keys while the other did not, and traffic
-  sealed in one key epoch reached a peer still on the other epoch and
-  failed to decrypt, producing bursts of AEAD decryption failures and
-  dropped connectivity until a later rekey reconverged the pair. The
-  receive path now trial-decrypts each frame against every live key
-  epoch (current, pending, and the draining previous session) for the
-  duration of the rekey transition, so no rotation ordering and no
-  packet reordering can cause a decryption failure. The previous-epoch
-  slot is retained as long as the peer keeps using it, with its drain
-  deadline anchored on the last frame the peer authenticates against
-  it rather than a fixed wall-clock timer, so a peer that did not
-  receive the new keys is not stranded by a silent permanent decrypt
-  failure. The lost-handshake case is closed by retransmitting the
-  third rekey handshake message until the peer is confirmed on the
-  new keys, with a bounded retry budget after which the rekey cycle
-  is cleanly abandoned and retried. There are no FSP decryption
-  failures across a rekey under lossy, jittery links.
+#### Data-plane / metrics / observability
+
+- The Tor transport now increments its `connect_refused` statistic (the
+  "Refused" line in fipstop) when a SOCKS5 connection is actively
+  refused, instead of recording every connect failure as a generic
+  SOCKS5 error. The counter previously stayed at zero.
+- MMP sender metrics now ignore duplicate or regressed receiver reports
+  before updating RTT, loss, goodput, or ETX. Receiver reports also
+  suppress timestamp echo when dwell time overflows, so stale reports
+  cannot inflate SRTT.
+- Reject-reason counters no longer double-count now that the rollout's
+  interim direct increments are removed. Six discovery counters
+  (`req_decode_error`, `req_duplicate`, `req_ttl_exhausted`,
+  `resp_decode_error`, `resp_identity_miss`, `resp_proof_failed`), six
+  bloom counters (`decode_error`, `invalid`, `non_v1`, `unknown_peer`,
+  `stale`, `fill_exceeded`), and five forwarding reject packet counters
+  (`decode_error_packets`, `ttl_exhausted_packets`,
+  `drop_no_route_packets`, `drop_mtu_exceeded_packets`,
+  `drop_send_error_packets`) were each incremented both by a direct bump
+  and again through the typed reject dispatch. The redundant direct
+  increments are removed — for the forwarding family the two calls are
+  collapsed into a single byte-aware reject entry point — so each counter
+  (and, for forwarding, its byte tally) counts once per event.
+- Transport-layer mutex poisoning no longer cascades. Ten
+  `Mutex::lock().unwrap()` sites across the UDP, BLE, and Ethernet
+  transports would turn a single panic (poisoning the mutex) into a
+  cascade of panics on every subsequent lock. Each is replaced with
+  `lock().unwrap_or_else(|e| e.into_inner())`, recovering the guarded
+  data with no new dependency and no call-graph change; four
+  `local_addr.unwrap()` calls on the UDP start/adopt paths get a
+  provably-safe sentinel fallback. The critical sections are short,
+  locally-scoped, and not reachable from peer input, so this is
+  robustness hardening, not a remotely-triggerable fix.
+
+#### Peer lifecycle / gateway
+
+- A manual `fipsctl disconnect` now notifies the peer so teardown is
+  symmetric. Previously a manual disconnect tore down only the local
+  side and sent the peer nothing, so the peer kept its session and never
+  re-emitted its tree and filter announcements; on reconnect it was
+  never re-adopted as a child and its bloom filter was never recorded.
+  The local side now sends the disconnected peer a scoped `Disconnect`
+  (the same message graceful shutdown sends), so both ends tear down and
+  re-handshake cleanly on the next connection.
+- `fips-gateway` no longer drops long-lived or DNS-cached client
+  mappings while traffic is still flowing. The virtual-IP pool's TTL
+  clock advanced only on DNS re-query, never on traffic, and the mapping
+  TTL is wired equal to the DNS TTL, so an in-use mapping was forced to
+  drain at TTL and reclaimed at the first zero-conntrack tick — breaking
+  long-lived, bursty, or DNS-cached clients. The tick now refreshes the
+  mapping's last-referenced time whenever conntrack reports active
+  sessions, and recovers a draining mapping to active (with a fresh
+  grace window) when traffic resumes; only genuinely idle mappings
+  drain.
+
+#### macOS self-traffic / resolver
+
+- Self-addressed mesh traffic is now delivered locally on macOS instead
+  of being dropped, for both `ping6` and full TCP/UDP. The point-to-point
+  `utun` interface egresses self-addressed traffic into the daemon, which
+  previously pushed it onto the mesh outbound path where it was dropped
+  for lack of a route to self; such packets are now hairpinned back to
+  the TUN for inbound delivery. macOS first routes self-addressed packets
+  as loopback (a `LOCAL` route via `lo0`), which leaves their transport
+  TX checksum offloaded and unfinished, so re-injecting them verbatim
+  made the local stack drop every segment whose checksum MSS clamping did
+  not happen to rewrite (the SYN and SYN-ACK got through, but the bare
+  ACK, data, and FIN were dropped, so connections to a node's own
+  `<npub>.fips` service half-opened and hung). The hairpin path now
+  recomputes the TCP/UDP checksum before re-injection, so full
+  self-connections — not just `ping6` — to a node's own `<npub>.fips`
+  address work. Linux was unaffected (the kernel already loops
+  self-traffic via `lo`). (#117)
+- macOS `.fips` name resolution now works on a fresh install: the
+  shipped resolver shim points at `::1`, matching the daemon's default
+  IPv6 DNS listener, instead of `127.0.0.1`. The mismatched shim
+  (`nameserver 127.0.0.1` while the daemon listens on `::1`) broke
+  `getaddrinfo` for `.fips` on every macOS install since the resolver
+  was introduced.
+
+#### CI & test-harness reliability
+
+- Node-level multi-node tests no longer flake under parallel CPU load.
+  They previously delivered handshake packets over real localhost UDP,
+  whose kernel receive buffer could overflow and drop a packet when many
+  tests ran concurrently, panicking the large-network convergence tests.
+  A `cfg(test)`-only loopback `TransportHandle` variant now delivers
+  packets directly between nodes over an unbounded in-process channel, so
+  there is no socket buffer to overflow, and the previously-quarantined
+  large-network tests run in the default suite again. The shipping daemon
+  build is unaffected (the variant is test-gated).
+- Integration suites that wait for the mesh to converge no longer
+  false-fail under concurrent CI load. The rekey, static-mesh, and
+  sidecar suites replace a fixed wall-clock baseline timeout (and a blind
+  sleep) with a progress-aware wait that polls the suite's own pairwise
+  pings, returns as soon as every pair is reachable, extends its deadline
+  while the reachable-pair count is still climbing, and gives up only
+  when progress stalls.
+- Rekey integration test (`testing/static/scripts/rekey-test.sh`) no
+  longer false-fails on GitHub runners under packet loss and CPU
+  contention. Phase 1, Phase 3, and Phase 5 strict per-pair pings retry
+  up to 4 attempts (configurable via `MAX_PING_ATTEMPTS` /
+  `PING_RETRY_DELAY`) — under 1% per-direction loss, single-shot 20-pair
+  ping_all misses ~33% per phase from ICMP noise alone, and the
+  4-attempt retry brings that floor to ~3.2e-6 per phase; the
+  `wait_for_full_baseline` convergence loop stays single-shot so retries
+  there cannot conflate transient ping loss with still-converging routing
+  state. Phase 1 baseline-convergence headroom is bumped from 36s to 60s
+  to eliminate the intermittent Phase 1 timeout that previously required
+  a `gh run rerun --failed`, and a post-second-rekey settle window is
+  added in Phase 5 (mirroring Phase 3's 12-second pattern) to close the
+  post-rekey per-pair-ping flake from convergence exceeding the per-ping
+  5-second timeout. Test scaffold only; no daemon code changes, and the
+  success path is unchanged because the wait loops return as soon as all
+  20 pairs converge.
+- ACL-allowlist integration test (`testing/acl-allowlist/test.sh`):
+  converted `assert_log_contains` from a one-shot `docker logs | grep`
+  snapshot into a bounded poll with the same wait-with-timeout shape
+  as `wait_for_peers_exact`. Absorbs the millisecond-to-second
+  variance in the XX-handshake cross-connection tie-breaker: the
+  inbound-handshake-context rejection can land tens of milliseconds
+  after the test's previous one-shot grep gave up, producing a
+  pre-existing flake on CI. Success-path cost is unchanged — the helper
+  returns as soon as the pattern appears.
+
+#### Packaging & deployment
+
 - AUR packaging: the `fips` and `fips-git` PKGBUILDs now install the
  `fips-dns-setup` and `fips-dns-teardown` helpers into
  `/usr/lib/fips/`, matching the Debian package. The AUR `package()`
@@ -564,113 +784,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  the arch-named file is present and carries a SHA-256 integrity
  chain from the build runner through to `gh release upload`, so a
  recurrence fails CI instead of publishing.
- Nostr discovery: filter unroutable direct UDP/TCP advert endpoints.
-  Publisher and validator now retain only endpoints that parse as
-  concrete socket addresses with routable IPs and nonzero ports.
-  `udp:nat` rendezvous endpoints and Tor endpoints pass through
-  unchanged. Adverts that collapse to zero usable endpoints after
-  filtering are rejected with a clear "missing publicly routable
-  endpoints" error. Before this change, misconfigured nodes could
-  publish RFC1918, loopback, link-local, CGNAT 100.64/10, IPv6 ULA,
-  or IPv6 link-local endpoints into Nostr discovery, and consumers
-  would cache and dial them; in mixed LAN/VPN/NAT environments, that
-  could prefer a misleading one-way private path over the intended
-  `udp:nat` bootstrap.
- Coord cache invalidation made surgical at parent-position-change
-  and root-change sites. Replaces the previous unconditional
-  `CoordCache::clear()` calls with two targeted methods:
-  `invalidate_via_node(node_addr)` (drops entries whose cached
-  ancestry contains the changed node, used at parent-switch /
-  become-root / loop-detection sites) and `invalidate_other_roots`
-  (drops entries from a different tree, used at root-change sites).
-  The previous global flush left `find_next_hop` returning `None`
-  for every non-direct-peer destination after every parent switch
-  until the cache passively re-warmed; surgical invalidation
-  preserves entries that remain correct across the topology change.
-  Peer-removal retains the original "no invalidation" behavior
-  (`find_next_hop` already recomputes against the current peer set
-  every call, and Discovery handles "no route" on demand).
- Rekey integration test (`testing/static/scripts/rekey-test.sh`):
-  Phase 1, Phase 3, and Phase 5 strict per-pair pings now retry up
-  to 4 attempts (configurable via `MAX_PING_ATTEMPTS` /
-  `PING_RETRY_DELAY`). Under low-level packet loss (1% per
-  direction), single-shot 20-pair ping_all misses with probability
-  ~33% per phase from ICMP noise alone, masking the routing-state
-  signal the asserts target. The 4-attempt retry brings that floor
-  to ~3.2e-6 per phase. The `wait_for_full_baseline` convergence
-  loop itself stays single-shot — retries there would conflate
-  transient ping loss with still-converging routing state. Test
-  scaffold only; no daemon code changes.
- Apply ±15s symmetric jitter per session to the FMP and FSP rekey
-  timer trigger. Eliminates the steady-state dual-initiation race
-  in symmetric-start meshes; previously the smaller-NodeAddr
-  tie-breaker resolved correctness after every cycle's collision.
-  `node.rekey.after_secs` becomes the nominal interval rather than
-  a floor; mean is preserved.
- Rekey integration test (`testing/static/scripts/rekey-test.sh`):
-  bumped Phase 1 baseline-convergence headroom from 36s to 60s.
-  Eliminates the intermittent GitHub-runner Phase 1 timeout that
-  previously required `gh run rerun --failed`. Cost on the success
-  path is unchanged because the wait loop returns as soon as all 20
-  pairs converge.
- Rekey integration test (`testing/static/scripts/rekey-test.sh`):
-  added a post-second-rekey settle window in Phase 5, mirroring
-  Phase 3's existing 12-second pattern. Closes the intermittent
-  GitHub-runner Phase 5 per-pair-ping flake caused by post-rekey
-  routing convergence exceeding the per-ping 5-second timeout under
-  runner CPU contention. Cost on the success path is a fixed 12s per
-  suite run.
- ACL-allowlist integration test (`testing/acl-allowlist/test.sh`):
-  converted `assert_log_contains` from a one-shot `docker logs | grep`
-  snapshot into a bounded poll with the same wait-with-timeout shape
-  as `wait_for_peers_exact`. Absorbs the millisecond-to-second
-  variance in the XX-handshake cross-connection tie-breaker: the
-  inbound-handshake-context rejection can land tens of milliseconds
-  after the test's previous one-shot grep gave up, producing a
-  pre-existing flake on next-branch CI. Success-path cost is
-  unchanged — the helper returns as soon as the pattern appears.
- Nostr-discovered NAT-traversal events (`BootstrapEvent::Established`
-  and `BootstrapEvent::Failed`) for peers that are already connected
-  or actively handshaking are now short-circuited at the
-  `poll_nostr_discovery` dispatch sites before any cooldown
-  bookkeeping or fallback retry scheduling runs. Stale `Failed` events
-  previously poisoned the per-peer failure-state cooldown of healthy
-  peers and could trigger redundant retraversal attempts via
-  `schedule_retry` / `try_peer_addresses`; stale `Established`
-  handoffs could attempt to adopt a second socket against a live
-  connection. A defense-in-depth guard was added to
-  `adopt_established_traversal` so the same invariant holds if a
-  future caller bypasses the outer dispatch check. As a side benefit,
-  narrows a cooldown-poisoning vector previously available to an
-  attacker injecting stale failure events for an active peer.
- A manual `fipsctl disconnect` now notifies the peer so teardown is
-  symmetric. Previously a manual disconnect tore down only the local
-  side and sent the peer nothing, so the peer kept its session and never
-  re-emitted its tree and filter announcements; on reconnect it was
-  never re-adopted as a child and its bloom filter was never recorded.
-  The local side now sends the disconnected peer a scoped `Disconnect`
-  (the same message graceful shutdown sends), so both ends tear down and
-  re-handshake cleanly on the next connection.
- `fips-gateway` no longer drops long-lived or DNS-cached client
-  mappings while traffic is still flowing. The virtual-IP pool's TTL
-  clock advanced only on DNS re-query, never on traffic, and the mapping
-  TTL is wired equal to the DNS TTL, so an in-use mapping was forced to
-  drain at TTL and reclaimed at the first zero-conntrack tick — breaking
-  long-lived, bursty, or DNS-cached clients. The tick now refreshes the
-  mapping's last-referenced time whenever conntrack reports active
-  sessions, and recovers a draining mapping to active (with a fresh
-  grace window) when traffic resumes; only genuinely idle mappings
-  drain.
- Transport-layer mutex poisoning no longer cascades. Ten
-  `Mutex::lock().unwrap()` sites across the UDP, BLE, and Ethernet
-  transports would turn a single panic (poisoning the mutex) into a
-  cascade of panics on every subsequent lock. Each is replaced with
-  `lock().unwrap_or_else(|e| e.into_inner())`, recovering the guarded
-  data with no new dependency and no call-graph change; four
-  `local_addr.unwrap()` calls on the UDP start/adopt paths get a
-  provably-safe sentinel fallback. The critical sections are short,
-  locally-scoped, and not reachable from peer input, so this is
-  robustness hardening, not a remotely-triggerable fix.
+
+#### fipstop
+
 - `fipstop` no longer renders a garbled screen on startup or leaves
  stray bytes on quit, most visible over SSH and inside tmux. Startup
  forces a full repaint (`terminal.clear()`) before the first draw so
@@ -678,12 +794,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  stdin-poll thread a stop flag and joins it before restoring the
  terminal, so post-raw-mode keystrokes or terminal query responses no
  longer echo onto the restored screen.
- macOS `.fips` name resolution now works on a fresh install: the
-  shipped resolver shim points at `::1`, matching the daemon's default
-  IPv6 DNS listener, instead of `127.0.0.1`. The mismatched shim
-  (`nameserver 127.0.0.1` while the daemon listens on `::1`) broke
-  `getaddrinfo` for `.fips` on every macOS install since the resolver
-  was introduced.

 ## [0.3.0] - 2026-05-11

@@ -42,6 +42,10 @@ and fail without it. BLE-capable builds additionally need `bluez`,
 `libdbus-1-dev`, and `pkg-config` installed; the default build picks
 up BLE if those are present and skips it cleanly if not.

+On Nix, `nix develop` provides the pinned toolchain and all of these
+build prerequisites without any manual install; see the Nix / NixOS
+section of [packaging/README.md](packaging/README.md).
+
 For multi-node integration runs, Docker is required. The harness
 under [testing/](testing/) starts containerized topologies and
 exercises real mesh behavior; see [testing/README.md](testing/README.md)
@@ -1074,7 +1074,7 @@ checksum = "9844ddc3a6e533d62bba727eb6c28b5d360921d5175e9ff0f1e621a5c590a4d5"

 [[package]]
 name = "fips"
-version = "0.4.0-rc.1"
+version = "0.4.0"
 dependencies = [
 "arc-swap",
 "bech32",
@@ -1,6 +1,6 @@
 [package]
 name = "fips"
-version = "0.4.0-rc.1"
+version = "0.4.0"
 edition = "2024"
 description = "A distributed, decentralized network routing protocol for mesh nodes connecting over arbitrary transports"
 license = "MIT"
@@ -3,7 +3,7 @@
 ![banner](docs/logos/fips_banner.png)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Rust](https://img.shields.io/badge/rust-1.85%2B-orange.svg)](https://www.rust-lang.org/)
-[![Status](https://img.shields.io/badge/status-v0.4.0--dev-green.svg)](#status--roadmap)
+[![Status](https://img.shields.io/badge/status-v0.4.0-green.svg)](#status--roadmap)

 A self-organizing encrypted mesh network built on Nostr identities,
 capable of operating over arbitrary transports without central
@@ -98,9 +98,9 @@ This installs the daemon, CLI tools (`fipsctl`, `fipstop`), the
 optional `fips-gateway` service, systemd units, and a default
 `/etc/fips/fips.yaml` you can edit before starting.

-For macOS, Windows, OpenWrt, the systemd tarball, or a from-source
-build, see [docs/getting-started.md](docs/getting-started.md) for
-the full multi-platform installation guide.
+For macOS, Windows, OpenWrt, the systemd tarball, a Nix flake, or a
+from-source build, see [docs/getting-started.md](docs/getting-started.md)
+for the full multi-platform installation guide.

 To join a live mesh and reach your first peer, follow the new-user
 tutorial progression starting at
@@ -143,6 +143,12 @@ Nym (mixnet) transport builds on all desktop platforms. The OpenWrt
 availability on the target; it will flip to ✅ only if confirmed
 buildable there.

+Alternatively, the repo ships a [Nix flake](flake.nix): `nix develop`
+drops you into a shell with the pinned toolchain and every build
+prerequisite (libclang, dbus, pkg-config) already provided, and
+`nix build .#fips` builds all four binaries with no host setup. See the
+Nix / NixOS section of [packaging/README.md](packaging/README.md).
+
 ## Documentation

 `docs/` is organised by reader purpose:
@@ -1,6 +1,6 @@
 # FIPS v0.4.0

-**Released**: 2026-06-DD (provisional)
+**Released**: 2026-06-21 (provisional)

 v0.4.0 is the throughput-and-observability release on the v0.3.x wire
 format. It adds two new ways for nodes to find and reach each other (the
@@ -31,6 +31,11 @@ across a mesh in any order.
  hot-path cost.
 - Reworked `fipstop` TUI on a machine-verified render-snapshot base.
 - Rekey is now hitless under loss and reordering in both directions.
+- New packaging targets: an OpenWrt `.apk` for OpenWrt 25+ and a Nix
+  flake for reproducible from-source builds on Nix/NixOS.
+- Six route-class transit counters partition forwarded traffic by its
+  tree relationship to the next hop, visible via `show_routing` and
+  `show_status`.

 ## What's new

@@ -115,6 +120,14 @@ returns a counter-only snapshot of every metric family. It is the
 enabler for a Prometheus scraper that pulls node counters at no hot-path
 cost.

+Six **route-class transit counters** partition transit-forwarded packets
+by their tree relationship to the chosen next hop — tree-up, tree-down,
+tree-down-cross, cross-link descend, cross-link ascend, and direct-peer
+— and the six classes sum to `forwarded_packets`. They surface through
+`show_routing` and `show_status`, and the `fipstop` routing tab is
+reorganized so its two columns separate own/endpoint traffic from
+forwarded/transit traffic with the tree-down-cross line visually flagged.
+
 ### Reworked fipstop TUI

 `fipstop` gets a rendering, navigation, and read-surface overhaul on a
@@ -155,6 +168,22 @@ The net operator takeaway: rekey completes cleanly without dropping
 traffic, even on lossy or high-latency links, and the log no longer
 cries wolf when a rekey gives up and retries.

+### New packaging targets
+
+- **OpenWrt `.apk`.** A new `.apk` package targets OpenWrt 25+, where
+  apk-tools is the mandatory package manager; the existing `.ipk`
+  continues to cover OpenWrt 24.x and earlier. It is built SDK-free,
+  reusing the `.ipk` cross-compile and installed-filesystem payload, and
+  releases publish `.apk` artifacts and checksums alongside `.ipk`. Like
+  the `.ipk`, the package is unsigned and installed with
+  `apk add --allow-untrusted`.
+- **Nix flake.** A `flake.nix` at the project root builds all four
+  binaries (`fips`, `fipsctl`, `fips-gateway`, `fipstop`) from source on
+  Nix/NixOS, pinning the exact toolchain and wiring the native build
+  dependencies so no host setup is needed beyond Nix with flakes
+  enabled. It exposes `nix build`, `nix run`, a `nix develop` dev shell,
+  and `nix flake check`, with `flake.lock` committed for reproducibility.
+
 ## Behavior changes worth flagging

 These affect operators on upgrade.
@@ -223,6 +252,15 @@ subset of fixes for behavior that shipped in v0.3.0.
  advertising a strictly worse root echoes its own declaration back,
  provoking the better-rooted peer to re-push its real position
  immediately.
+- **macOS self-connections work end to end (#117).** Traffic a macOS
+  node sends to its own `<npub>.fips` address is now delivered locally
+  for full TCP/UDP, not just `ping6`. The point-to-point `utun` egresses
+  self-addressed packets into the daemon with an unfinished transport
+  checksum (macOS offloads it on the `lo0` loopback route), so
+  re-injecting them verbatim made the local stack drop every segment the
+  MSS-clamp rewrite did not happen to fix and self-connections
+  half-opened and hung. The hairpin path now recomputes the TCP/UDP
+  checksum before re-injection. Linux was unaffected.

 ## Upgrade notes

@@ -253,10 +291,14 @@ Operator-actionable items moving from v0.3.0 to v0.4.0:
 - **Arch Linux**: `fips` from the AUR.
 - **macOS**: `.pkg` at the v0.4.0 release page.
 - **Windows**: ZIP at the v0.4.0 release page.
- **OpenWrt**: `.ipk` at the v0.4.0 release page.
+- **OpenWrt**: `.ipk` (OpenWrt 24.x and earlier) or `.apk` (OpenWrt 25+)
+  at the v0.4.0 release page.
 - **From source**: `cargo build --release` from a checkout of the v0.4.0
  tag (Rust 1.94.1 per `rust-toolchain.toml`; `libclang-dev` is a
  required Linux build prerequisite).
+- **Nix / NixOS**: `nix build .#fips` from a checkout of the v0.4.0 tag
+  builds the binaries from source with the pinned toolchain and no manual
+  prerequisites (see the Nix section of `packaging/README.md`).

 The full per-commit changelog lives in
 [`CHANGELOG.md`](../../CHANGELOG.md). Issues and discussion at
@@ -88,6 +88,23 @@ See [packaging/README.md](../packaging/README.md) for per-format
 build details, cross-target options, and the full `make` target
 list.

+### With Nix (flake)
+
+On Nix/NixOS, a [flake](../flake.nix) at the project root builds the
+binaries from source with the pinned toolchain and no manual
+prerequisite install:
+
+```sh
+nix build .#fips          # all four binaries, into ./result/bin
+nix develop               # dev shell with the toolchain + build deps
+```
+
+This path produces binaries only — it does not run the installer, so
+there are no systemd units, no `fips` group, and no default `fips.yaml`.
+On NixOS, wire the daemon in through your system configuration using the
+flake's `packages.<system>.fips` output instead. See the Nix / NixOS
+section of [packaging/README.md](../packaging/README.md).
+
 ## What's installed and running

 Here's what the installer leaves on your machine, what's
@@ -1,6 +1,6 @@
 # FIPS v0.4.0

-**Released**: 2026-06-DD (provisional)
+**Released**: 2026-06-21 (provisional)

 v0.4.0 is the throughput-and-observability release on the v0.3.x wire
 format. It adds two new ways for nodes to find and reach each other (the
@@ -31,6 +31,11 @@ across a mesh in any order.
  hot-path cost.
 - Reworked `fipstop` TUI on a machine-verified render-snapshot base.
 - Rekey is now hitless under loss and reordering in both directions.
+- New packaging targets: an OpenWrt `.apk` for OpenWrt 25+ and a Nix
+  flake for reproducible from-source builds on Nix/NixOS.
+- Six route-class transit counters partition forwarded traffic by its
+  tree relationship to the next hop, visible via `show_routing` and
+  `show_status`.

 ## What's new

@@ -115,6 +120,14 @@ returns a counter-only snapshot of every metric family. It is the
 enabler for a Prometheus scraper that pulls node counters at no hot-path
 cost.

+Six **route-class transit counters** partition transit-forwarded packets
+by their tree relationship to the chosen next hop — tree-up, tree-down,
+tree-down-cross, cross-link descend, cross-link ascend, and direct-peer
+— and the six classes sum to `forwarded_packets`. They surface through
+`show_routing` and `show_status`, and the `fipstop` routing tab is
+reorganized so its two columns separate own/endpoint traffic from
+forwarded/transit traffic with the tree-down-cross line visually flagged.
+
 ### Reworked fipstop TUI

 `fipstop` gets a rendering, navigation, and read-surface overhaul on a
@@ -155,6 +168,22 @@ The net operator takeaway: rekey completes cleanly without dropping
 traffic, even on lossy or high-latency links, and the log no longer
 cries wolf when a rekey gives up and retries.

+### New packaging targets
+
+- **OpenWrt `.apk`.** A new `.apk` package targets OpenWrt 25+, where
+  apk-tools is the mandatory package manager; the existing `.ipk`
+  continues to cover OpenWrt 24.x and earlier. It is built SDK-free,
+  reusing the `.ipk` cross-compile and installed-filesystem payload, and
+  releases publish `.apk` artifacts and checksums alongside `.ipk`. Like
+  the `.ipk`, the package is unsigned and installed with
+  `apk add --allow-untrusted`.
+- **Nix flake.** A `flake.nix` at the project root builds all four
+  binaries (`fips`, `fipsctl`, `fips-gateway`, `fipstop`) from source on
+  Nix/NixOS, pinning the exact toolchain and wiring the native build
+  dependencies so no host setup is needed beyond Nix with flakes
+  enabled. It exposes `nix build`, `nix run`, a `nix develop` dev shell,
+  and `nix flake check`, with `flake.lock` committed for reproducibility.
+
 ## Behavior changes worth flagging

 These affect operators on upgrade.
@@ -223,6 +252,15 @@ subset of fixes for behavior that shipped in v0.3.0.
  advertising a strictly worse root echoes its own declaration back,
  provoking the better-rooted peer to re-push its real position
  immediately.
+- **macOS self-connections work end to end (#117).** Traffic a macOS
+  node sends to its own `<npub>.fips` address is now delivered locally
+  for full TCP/UDP, not just `ping6`. The point-to-point `utun` egresses
+  self-addressed packets into the daemon with an unfinished transport
+  checksum (macOS offloads it on the `lo0` loopback route), so
+  re-injecting them verbatim made the local stack drop every segment the
+  MSS-clamp rewrite did not happen to fix and self-connections
+  half-opened and hung. The hairpin path now recomputes the TCP/UDP
+  checksum before re-injection. Linux was unaffected.

 ## Upgrade notes

@@ -253,10 +291,14 @@ Operator-actionable items moving from v0.3.0 to v0.4.0:
 - **Arch Linux**: `fips` from the AUR.
 - **macOS**: `.pkg` at the v0.4.0 release page.
 - **Windows**: ZIP at the v0.4.0 release page.
- **OpenWrt**: `.ipk` at the v0.4.0 release page.
+- **OpenWrt**: `.ipk` (OpenWrt 24.x and earlier) or `.apk` (OpenWrt 25+)
+  at the v0.4.0 release page.
 - **From source**: `cargo build --release` from a checkout of the v0.4.0
  tag (Rust 1.94.1 per `rust-toolchain.toml`; `libclang-dev` is a
  required Linux build prerequisite).
+- **Nix / NixOS**: `nix build .#fips` from a checkout of the v0.4.0 tag
+  builds the binaries from source with the pinned toolchain and no manual
+  prerequisites (see the Nix section of `packaging/README.md`).

 The full per-commit changelog lives in
 [`CHANGELOG.md`](../../CHANGELOG.md). Issues and discussion at
@@ -0,0 +1,100 @@
+{
+  "nodes": {
+    "fenix": {
+      "inputs": {
+        "nixpkgs": [
+          "nixpkgs"
+        ],
+        "rust-analyzer-src": "rust-analyzer-src"
+      },
+      "locked": {
+        "lastModified": 1781527054,
+        "narHash": "sha256-1fX9ev2Fh5QoKQ41G9dYutjo5j/jywu6tZse5Eb1Ck4=",
+        "owner": "nix-community",
+        "repo": "fenix",
+        "rev": "8c2e51dffefc040a21975da7abf6f252c8c9b783",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-community",
+        "repo": "fenix",
+        "type": "github"
+      }
+    },
+    "flake-utils": {
+      "inputs": {
+        "systems": "systems"
+      },
+      "locked": {
+        "lastModified": 1731533236,
+        "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1781074563,
+        "narHash": "sha256-md8WlXOlfnIeHeOScMTTHFyf2d6iaTwPl2apR5EQ3P4=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "9ae611a455b90cf061d8f332b977e387bda8e1ca",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "fenix": "fenix",
+        "flake-utils": "flake-utils",
+        "nixpkgs": "nixpkgs"
+      }
+    },
+    "rust-analyzer-src": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1781453968,
+        "narHash": "sha256-+V3nK4pCngbmgyVGXY6Kkrlevp4ocPkJJLf2aqwkDNA=",
+        "owner": "rust-lang",
+        "repo": "rust-analyzer",
+        "rev": "cc272809a173c2c11d0e479d639c811c1eacf049",
+        "type": "github"
+      },
+      "original": {
+        "owner": "rust-lang",
+        "ref": "nightly",
+        "repo": "rust-analyzer",
+        "type": "github"
+      }
+    },
+    "systems": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}
@@ -0,0 +1,128 @@
+{
+  description = "FIPS — a distributed, decentralized network routing protocol for mesh nodes connecting over arbitrary transports";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    flake-utils.url = "github:numtide/flake-utils";
+    fenix = {
+      url = "github:nix-community/fenix";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+  };
+
+  outputs =
+    {
+      self,
+      nixpkgs,
+      flake-utils,
+      fenix,
+    }:
+    flake-utils.lib.eachDefaultSystem (
+      system:
+      let
+        pkgs = import nixpkgs { inherit system; };
+
+        # Honor the toolchain the repo pins in rust-toolchain.toml
+        # (channel 1.94.1 + rustfmt, clippy) so Nix builds match CI and the
+        # AUR/Debian packaging exactly, including the edition-2024 frontend.
+        rustToolchain = fenix.packages.${system}.fromToolchainFile {
+          file = ./rust-toolchain.toml;
+          sha256 = "sha256-zC8E38iDVJ1oPIzCqTk/Ujo9+9kx9dXq7wAwPMpkpg0=";
+        };
+
+        rustPlatform = pkgs.makeRustPlatform {
+          cargo = rustToolchain;
+          rustc = rustToolchain;
+        };
+
+        cargoToml = pkgs.lib.importTOML ./Cargo.toml;
+
+        # libdbus-sys (pulled in transitively by `bluer`, Linux/glibc only)
+        # runs `bindgen` against the system D-Bus headers at build time.
+        nativeBuildInputs = [
+          pkgs.pkg-config
+          rustPlatform.bindgenHook # sets LIBCLANG_PATH + clang for bindgen
+        ];
+
+        buildInputs = pkgs.lib.optionals pkgs.stdenv.isLinux [
+          pkgs.dbus # libdbus-1.so.3, linked via bluer→libdbus-sys
+          pkgs.stdenv.cc.cc.lib # libgcc_s.so.1, needed by every Rust binary
+        ];
+
+        fips = rustPlatform.buildRustPackage {
+          pname = "fips";
+          version = cargoToml.package.version;
+
+          src = pkgs.lib.cleanSourceWith {
+            src = ./.;
+            # Drop the build dir and the usual editor/VCS noise so the source
+            # hash is stable and unrelated edits don't trigger rebuilds.
+            filter =
+              path: type:
+              (pkgs.lib.cleanSourceFilter path type) && (baseNameOf path != "target");
+          };
+
+          cargoLock.lockFile = ./Cargo.lock;
+
+          inherit buildInputs;
+
+          # autoPatchelfHook rewrites the RPATH of the built binaries so the
+          # daemon finds libdbus-1.so.3 (linked via bluer→libdbus-sys) in the
+          # Nix store at runtime — without it the `fips` binary fails to load
+          # on NixOS where there is no global /usr/lib.
+          nativeBuildInputs =
+            nativeBuildInputs ++ pkgs.lib.optionals pkgs.stdenv.isLinux [ pkgs.autoPatchelfHook ];
+
+          # The test suite exercises TUN devices, raw sockets and mDNS, none of
+          # which exist in the build sandbox. The AUR/Debian packaging likewise
+          # ships the release binaries without running the integration tests
+          # here, so keep the package build hermetic and skip them.
+          doCheck = false;
+
+          meta = {
+            description = cargoToml.package.description;
+            homepage = cargoToml.package.homepage;
+            license = pkgs.lib.licenses.mit;
+            mainProgram = "fips";
+            platforms = pkgs.lib.platforms.linux ++ pkgs.lib.platforms.darwin;
+          };
+        };
+
+        mkApp = name: {
+          type = "app";
+          program = "${fips}/bin/${name}";
+          meta.description = "Run the ${name} binary from the FIPS package";
+        };
+      in
+      {
+        packages = {
+          default = fips;
+          fips = fips;
+        };
+
+        apps = {
+          default = mkApp "fips";
+          fips = mkApp "fips";
+          fipsctl = mkApp "fipsctl";
+          fips-gateway = mkApp "fips-gateway";
+          fipstop = mkApp "fipstop";
+        };
+
+        # `nix flake check` builds the package (and thus validates the flake on
+        # the current system).
+        checks.fips = fips;
+
+        devShells.default = pkgs.mkShell {
+          inherit buildInputs;
+          nativeBuildInputs = nativeBuildInputs ++ [
+            rustToolchain
+            pkgs.cargo-edit
+          ];
+          # Point rust-analyzer at the matching std sources.
+          RUST_SRC_PATH = "${rustToolchain}/lib/rustlib/src/rust/library";
+        };
+
+        formatter = pkgs.nixfmt;
+      }
+    );
+}
@@ -6,7 +6,8 @@
 # Usage:
 #   make deb        Build a Debian/Ubuntu .deb package
 #   make tarball    Build a systemd install tarball
-#   make ipk        Build an OpenWrt .ipk package
+#   make ipk        Build an OpenWrt .ipk package (opkg, OpenWrt 24.x and earlier)
+#   make apk        Build an OpenWrt .apk package (apk-tools, mandatory on OpenWrt 25+)
 #   make aur        Build fips-git AUR package and validate with namcap
 #   make pkg        Build a macOS .pkg installer
 #   make zip        Build a Windows .zip package
@@ -17,7 +18,7 @@ SHELL := /bin/bash
 PACKAGING_DIR := $(dir $(abspath $(lastword $(MAKEFILE_LIST))))
 PROJECT_ROOT  := $(abspath $(PACKAGING_DIR)/..)

-.PHONY: all deb tarball ipk aur pkg zip clean
+.PHONY: all deb tarball ipk apk aur pkg zip clean

 all: deb tarball

@@ -30,6 +31,9 @@ tarball:
 ipk:
 	@bash $(PACKAGING_DIR)/openwrt-ipk/build-ipk.sh

+apk:
+	@bash $(PACKAGING_DIR)/openwrt-apk/build-apk.sh
+
 aur:
 	@bash $(PACKAGING_DIR)/aur/build-aur.sh

@@ -8,7 +8,8 @@ All build outputs go to `deploy/` at the project root.
 ```sh
 make deb        # Debian/Ubuntu .deb
 make tarball    # systemd install tarball
-make ipk        # OpenWrt .ipk
+make ipk        # OpenWrt .ipk (opkg, OpenWrt 24.x and earlier)
+make apk        # OpenWrt .apk (apk-tools, mandatory on OpenWrt 25+)
 make aur        # Arch Linux AUR package (fips-git, local build + namcap)
 make pkg        # macOS .pkg installer
 make zip        # Windows .zip package
@@ -46,7 +47,8 @@ packaging/
  debian/         Debian/Ubuntu .deb packaging via cargo-deb
  macos/          macOS .pkg installer via pkgbuild
  systemd/        Generic Linux systemd tarball packaging
-  openwrt/        OpenWrt .ipk packaging via cargo-zigbuild
+  openwrt-ipk/    OpenWrt .ipk packaging via cargo-zigbuild (opkg)
+  openwrt-apk/    OpenWrt .apk packaging via cargo-zigbuild + apk mkpkg
  windows/        Windows .zip package with service scripts
 ```

@@ -100,7 +102,7 @@ sudo ./fips-<version>-linux-<arch>/install.sh
 See [systemd/README.install.md](systemd/README.install.md) for full
 installation and configuration instructions.

-### OpenWrt (`.ipk`)
+### OpenWrt (`.ipk`, opkg — OpenWrt 24.x and earlier)

 Cross-compiled with cargo-zigbuild and assembled as a standard `.ipk`
 archive. Supports aarch64, mipsel, mips, arm, and x86\_64 targets.
@@ -110,12 +112,33 @@ archive. Supports aarch64, mipsel, mips, arm, and x86\_64 targets.
 make ipk

 # Build for a specific architecture
-bash packaging/openwrt/build-ipk.sh --arch mipsel
+bash packaging/openwrt-ipk/build-ipk.sh --arch mipsel
 ```

-See [openwrt/README.md](openwrt/README.md) for router-specific
+See [openwrt-ipk/README.md](openwrt-ipk/README.md) for router-specific
 installation instructions.

+### OpenWrt (`.apk`, apk-tools — mandatory on OpenWrt 25+)
+
+OpenWrt 25 makes apk-tools the mandatory package manager (it is opt-in on
+24.10). Same SDK-free approach
+(cargo-zigbuild), but the `.apk` container is assembled by `apk mkpkg`
+rather than hand-rolled, so the build additionally needs an apk-tools v3
+`apk` binary built from source. The installed-filesystem payload is shared
+with the `.ipk` package.
+
+```sh
+# Build (default: aarch64; also x86_64)
+make apk
+
+# Build for a specific architecture
+bash packaging/openwrt-apk/build-apk.sh --arch x86_64
+```
+
+Packages are unsigned; install with `apk add --allow-untrusted`. See
+[openwrt-apk/README.md](openwrt-apk/README.md) for building apk-tools and
+router-specific installation.
+
 ### macOS (`.pkg`)

 Built with `pkgbuild` (included with Xcode command-line tools). Installs
@@ -177,6 +200,27 @@ yay -S fips        # release build from latest tag
 See [aur/README.md](aur/README.md) for AUR publication instructions
 and maintainer guide.

+### Nix / NixOS (flake)
+
+A [flake](../flake.nix) at the project root builds all four binaries
+(`fips`, `fipsctl`, `fips-gateway`, `fipstop`) from source. It pins the
+exact toolchain from `rust-toolchain.toml` via
+[fenix](https://github.com/nix-community/fenix) and wires up the
+build-time native dependencies (`libclang` for `bindgen`, plus `dbus`
+and `pkg-config` for BLE), so it needs no system setup beyond Nix with
+flakes enabled.
+
+```sh
+nix build .#fips          # build the package (all four binaries)
+nix run .#fips -- --help  # run a binary directly
+nix run .#fipsctl -- status
+nix develop               # dev shell with the pinned toolchain + cargo-edit
+nix flake check           # build + validate the flake
+```
+
+Add to a NixOS configuration via the flake's `packages.<system>.fips`
+output, e.g. `environment.systemPackages = [ fips.packages.${system}.default ];`.
+
 ## Shared Assets

 `common/` contains assets used across packaging formats:
@@ -0,0 +1,98 @@
+# FIPS OpenWrt Package (apk)
+
+Builds a FIPS `.apk` for **OpenWrt 25+**, where apk-tools is the mandatory
+package manager. apk is also available opt-in on **24.10** (where opkg remains
+the default). For OpenWrt 24.x and earlier, the `.ipk` package in
+[`../openwrt-ipk/`](../openwrt-ipk/) still works.
+
+Like the `.ipk` build, this is **SDK-free**: it cross-compiles with
+`cargo-zigbuild` and assembles the package directly — no OpenWrt SDK image. The
+`.ipk` format is a plain tar.gz we can hand-roll, but the `.apk` (apk-tools v3
+ADB) container is not, so we drive the official `apk mkpkg` applet — the same
+tool OpenWrt's own [`include/package-pack.mk`](https://github.com/openwrt/openwrt/blob/main/include/package-pack.mk)
+calls. The only extra requirement over the `.ipk` build is the `apk` binary.
+
+## Layout
+
+| File | Purpose |
+|---|---|
+| `build-apk.sh` | Cross-compile + assemble the `.apk` via `apk mkpkg` |
+| `apk-version.sh` | Map a release tag / commit height to an apk-tools-valid version |
+| `apk-version.test.sh` | Case-table test for `apk-version.sh` (`sh apk-version.test.sh`) |
+
+The installed-filesystem payload (init scripts, `fips.yaml`, sysctl drop-ins,
+hotplug, uci-defaults, …) is **shared** with the `.ipk` package — there is one
+canonical copy in [`../openwrt-ipk/files/`](../openwrt-ipk/files/). `build-apk.sh`
+stages from there, so the two packages always ship the same files. Keep the
+staging block in `build-apk.sh` in sync with `../openwrt-ipk/build-ipk.sh`.
+
+## Versioning
+
+apk-tools enforces a strict version grammar
+(`<digit>(.<digit>)*(_<suffix><digit>*)*(-r<N>)`). `apk-version.sh` builds a
+valid version from structured inputs rather than rewriting an already-flattened
+string:
+
+| Input | apk version |
+|---|---|
+| `tag v1.2.3` | `1.2.3-r0` |
+| `tag v1.2.3-rc1` | `1.2.3_rc1-r0` |
+| `dev 1234` (commit height) | `0.0.0_git1234-r0` |
+
+The human-readable version (`v1.2.3`, `master.123.abcdef0`) is still used for the
+artifact filename; only the metadata embedded in the package is normalized.
+
+## Building
+
+### Prerequisites
+
+| Requirement | Notes |
+|---|---|
+| `cargo install cargo-zigbuild` + `zig` | Rust musl cross-compilation (as for `.ipk`) |
+| apk-tools v3 `apk` binary | Provides `apk mkpkg`; not packaged for most distros — build from source |
+| `fakeroot` | Optional; makes packaged files root-owned on an unprivileged build host |
+
+apk-tools is not in Debian/Ubuntu repos, so build the pinned release from source.
+Pin the same commit the targeted OpenWrt release ships (see
+`package/system/apk/Makefile` upstream) so the `.apk` is readable by the device's
+`apk`. CI builds **3.0.5** (`b5a31c0d…`):
+
+```bash
+sudo apt-get install -y build-essential meson ninja-build pkg-config \
+  zlib1g-dev libssl-dev libzstd-dev liblzma-dev lua5.4-dev scdoc
+git clone https://gitlab.alpinelinux.org/alpine/apk-tools.git
+cd apk-tools && git checkout b5a31c0d865342ad80be10d68f1bb3d3ad9b0866
+meson setup build && ninja -C build src/apk
+export APK_BIN="$PWD/build/src/apk"
+```
+
+### Build the package
+
+```bash
+# from the repo root
+./packaging/openwrt-apk/build-apk.sh --arch aarch64    # or x86_64, mipsel, mips, arm
+```
+
+Output: `dist/fips_<version>_<openwrt-arch>.apk`. Override the version with
+`PKG_VERSION` (filename) and `APK_VERSION` (embedded metadata); otherwise both are
+derived from git.
+
+## Installing on the router
+
+Packages are **unsigned** (the same posture as our `.ipk`), so install with
+`--allow-untrusted`:
+
+```bash
+scp -O dist/fips_<version>_<arch>.apk root@192.168.1.1:/tmp/
+ssh root@192.168.1.1 apk add --allow-untrusted /tmp/fips_<version>_<arch>.apk
+```
+
+On OpenWrt 25.x, installing from a *signed repository* requires the publisher's
+key; a single `--allow-untrusted` package install does not. If we ever publish an
+apk feed, add ECDSA (prime256v1) signing via `apk mkpkg --sign` and distribute the
+public key to `/etc/apk/keys/`.
+
+`/etc/fips/fips.yaml` is marked as a config file (via
+`/lib/apk/packages/fips.conffiles`), so apk preserves local edits across upgrades,
+and `/lib/upgrade/keep.d/fips` preserves `/etc/fips/` across `sysupgrade` — the
+same guarantees as the `.ipk` package.
@@ -0,0 +1,74 @@
+#!/bin/sh
+# Emit an apk-tools-compatible version string for FIPS.
+#
+# apk-tools enforces a strict version grammar:
+#   <digit>(.<digit>)*(_<suffix><digit>*)*(-r<N>)
+# where <suffix> is a recognised pre-release/post-release token
+# (alpha, beta, pre, rc, cvs, svn, git, hg, p).
+#
+# Unlike a regex rewrite of an already-flattened version string, this
+# helper builds the apk version directly from the *structured* inputs the
+# caller already has (a release tag, or a commit height). There is no
+# parsing-back-out of a "branch.height.hash" blob, so there is no fragile
+# reparse step to get wrong.
+#
+# Usage:
+#   apk-version.sh tag  <git-tag>     # e.g. v1.2.3, v1.2.3-rc1
+#   apk-version.sh dev  <height>      # e.g. 1234  (git rev-list --count HEAD)
+#   apk-version.sh auto               # derive from the current git checkout
+#
+# Examples:
+#   apk-version.sh tag v1.2.3       -> 1.2.3-r0
+#   apk-version.sh tag v1.2.3-rc1   -> 1.2.3_rc1-r0
+#   apk-version.sh dev 1234         -> 0.0.0_git1234-r0
+set -eu
+
+mode="${1:-auto}"
+
+case "$mode" in
+    tag) raw_tag="${2:?tag mode requires a tag argument}"; height="" ;;
+    dev) raw_tag=""; height="${2:?dev mode requires a height argument}" ;;
+    auto)
+        if raw_tag="$(git describe --exact-match --tags 2>/dev/null)"; then
+            height=""
+        else
+            raw_tag=""
+            height="$(git rev-list --count HEAD 2>/dev/null || echo 0)"
+        fi
+        ;;
+    *)
+        echo "usage: $0 [auto | tag <git-tag> | dev <height>]" >&2
+        exit 2
+        ;;
+esac
+
+if [ -n "$raw_tag" ]; then
+    # Release tag: vX.Y.Z or vX.Y.Z-<pre>. Strip the leading 'v', split the
+    # core (X.Y.Z) from the pre-release token, and map our hyphen separator
+    # to apk's '_' pre-release marker.
+    body="${raw_tag#v}"
+    core="${body%%-*}"
+    case "$body" in
+        *-*) pre="${body#*-}" ;;
+        *)   pre="" ;;
+    esac
+
+    case "$pre" in
+        "")                    suffix="" ;;
+        alpha*|beta*|pre*|rc*) suffix="_${pre}" ;;
+        *)
+            # Unknown pre-release token: apk would reject or misorder it, so
+            # drop it rather than emit an invalid version. The human-readable
+            # PACKAGE_VERSION (the raw tag) is still used for the filename.
+            suffix=""
+            ;;
+    esac
+
+    printf '%s%s-r0\n' "$core" "$suffix"
+else
+    # Untagged build: no meaningful semver, so anchor at 0.0.0 and encode the
+    # monotonic commit height as a _git pre-release component. This keeps apk's
+    # ordering sane across dev builds without smuggling the hash/branch into a
+    # field that cannot represent them.
+    printf '0.0.0_git%s-r0\n' "${height:-0}"
+fi
@@ -0,0 +1,45 @@
+#!/bin/sh
+# Case-table test for apk-version.sh. Run: sh apk-version.test.sh
+set -eu
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+SUT="$HERE/apk-version.sh"
+
+fail=0
+check() {
+    # check <expected> <args...>
+    expected="$1"; shift
+    actual="$(sh "$SUT" "$@")"
+    if [ "$actual" = "$expected" ]; then
+        printf '  PASS  %-22s -> %s\n' "$*" "$actual"
+    else
+        printf '  FAIL  %-22s -> %s (expected %s)\n' "$*" "$actual" "$expected"
+        fail=1
+    fi
+}
+
+echo "== apk-version.sh =="
+
+# Plain release tags.
+check "1.2.3-r0"        tag v1.2.3
+check "0.4.0-r0"        tag v0.4.0
+check "10.20.30-r0"     tag v10.20.30
+
+# Pre-release tags: hyphen separator becomes apk's '_' marker.
+check "1.2.3_rc1-r0"    tag v1.2.3-rc1
+check "1.2.3_alpha1-r0" tag v1.2.3-alpha1
+check "1.2.3_beta2-r0"  tag v1.2.3-beta2
+check "1.2.3_pre1-r0"   tag v1.2.3-pre1
+
+# Unknown pre-release token is dropped (apk cannot represent it).
+check "1.2.3-r0"        tag v1.2.3-weird9
+
+# Dev builds: monotonic commit height as a _git component.
+check "0.0.0_git1234-r0" dev 1234
+check "0.0.0_git0-r0"    dev 0
+
+if [ "$fail" -ne 0 ]; then
+    echo "FAILED"
+    exit 1
+fi
+echo "OK"
@@ -0,0 +1,296 @@
+#!/bin/bash
+# Build a FIPS .apk package for OpenWrt without the OpenWrt SDK.
+#
+# apk-tools (.apk) is the mandatory package manager from OpenWrt 25 onward; it
+# is also available opt-in on 24.10, where opkg (.ipk) remains the default. The
+# .ipk package in ../openwrt-ipk/ still covers OpenWrt 24.x and earlier; this
+# .apk package is what you need on 25+. Unlike the .ipk format (a plain tar.gz
+# of tarballs that we
+# assemble by hand in ../openwrt-ipk/build-ipk.sh), the .apk container is the
+# apk-tools v3 ADB format, which is impractical to hand-roll. Instead we drive
+# the official `apk mkpkg` applet — the same tool OpenWrt's build system calls
+# in include/package-pack.mk — so no SDK is required, only the `apk` binary.
+#
+# Usage:
+#   ./packaging/openwrt-apk/build-apk.sh [--arch <name>]
+#
+# Architectures (--arch): aarch64 [default], x86_64, mipsel, mips, arm
+#   (the apk CI matrix ships aarch64 + x86_64; the rest are buildable locally).
+#
+# Output: dist/fips_<version>_<openwrt-arch>.apk
+#
+# Prerequisites:
+#   cargo install cargo-zigbuild           (Rust musl cross-compilation)
+#   apk-tools v3 `apk` binary on PATH, or pointed at via APK_BIN=/path/to/apk
+#     (build from source — see README.md; CI builds apk-tools 3.0.5).
+#   fakeroot (optional but recommended; makes packaged files root-owned).
+#
+# Install on a router (packages are unsigned, like our .ipk):
+#   scp -O dist/fips_<version>_<arch>.apk root@192.168.1.1:/tmp/
+#   ssh root@192.168.1.1 apk add --allow-untrusted /tmp/fips_<version>_<arch>.apk
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# Arguments
+# ---------------------------------------------------------------------------
+
+ARCH="aarch64"
+BIN_DIR=""   # if set, use prebuilt binaries from here instead of compiling
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --arch) ARCH="$2"; shift 2 ;;
+        --arch=*) ARCH="${1#*=}"; shift ;;
+        --bin-dir) BIN_DIR="$2"; shift 2 ;;
+        --bin-dir=*) BIN_DIR="${1#*=}"; shift ;;
+        *) echo "Unknown argument: $1" >&2; exit 1 ;;
+    esac
+done
+
+# ---------------------------------------------------------------------------
+# Architecture mapping
+#
+# RUST_TARGET   — passed to cargo --target
+# OPENWRT_ARCH  — apk "arch:" field and the package filename
+#
+# Kept in sync with ../openwrt-ipk/build-ipk.sh (same target table).
+# ---------------------------------------------------------------------------
+
+case "$ARCH" in
+    aarch64)
+        RUST_TARGET="aarch64-unknown-linux-musl"
+        OPENWRT_ARCH="aarch64_cortex-a53"
+        ;;
+    mipsel)
+        RUST_TARGET="mipsel-unknown-linux-musl"
+        OPENWRT_ARCH="mipsel_24kc"
+        ;;
+    mips)
+        RUST_TARGET="mips-unknown-linux-musl"
+        OPENWRT_ARCH="mips_24kc"
+        ;;
+    arm)
+        RUST_TARGET="arm-unknown-linux-musleabihf"
+        OPENWRT_ARCH="arm_cortex-a7"
+        ;;
+    x86_64)
+        RUST_TARGET="x86_64-unknown-linux-musl"
+        OPENWRT_ARCH="x86_64"
+        ;;
+    *)
+        echo "Unknown arch: $ARCH" >&2
+        echo "Valid: aarch64, mipsel, mips, arm, x86_64" >&2
+        exit 1
+        ;;
+esac
+
+# ---------------------------------------------------------------------------
+# Paths
+# ---------------------------------------------------------------------------
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+# The installed-filesystem payload (init scripts, config, sysctl, etc.) is
+# shared with the .ipk package; there is one canonical copy in openwrt-ipk/.
+FILES_DIR="$PROJECT_ROOT/packaging/openwrt-ipk/files"
+DIST_DIR="$PROJECT_ROOT/dist"
+
+PKG_NAME="fips"
+# Human-readable version for the filename (e.g. v0.4.0 or master.123.abcdef0),
+# mirroring the .ipk artifacts and the CI/NIP-94 plumbing.
+PKG_VERSION="${PKG_VERSION:-$(cd "$PROJECT_ROOT" && git describe --tags --always --dirty 2>/dev/null || echo "0.1.0")}"
+# apk-tools-compatible version embedded inside the package metadata.
+APK_VERSION="${APK_VERSION:-$(cd "$PROJECT_ROOT" && sh "$SCRIPT_DIR/apk-version.sh" auto)}"
+
+APK_BIN="${APK_BIN:-apk}"
+if ! command -v "$APK_BIN" >/dev/null 2>&1; then
+    echo "Error: apk-tools binary not found (looked for '$APK_BIN')." >&2
+    echo "  Build apk-tools v3 from source or set APK_BIN=/path/to/apk." >&2
+    echo "  See packaging/openwrt-apk/README.md." >&2
+    exit 1
+fi
+
+echo "==> Building $PKG_NAME $PKG_VERSION (apk version $APK_VERSION) for $OPENWRT_ARCH ($RUST_TARGET)"
+
+# ---------------------------------------------------------------------------
+# 1. Obtain binaries
+#
+# Either use a directory of prebuilt binaries (--bin-dir; CI cross-compiles
+# once in a shared job and hands them to both the .ipk and .apk packagers), or
+# compile from source here for a self-contained local build.
+# ---------------------------------------------------------------------------
+
+if [ -n "$BIN_DIR" ]; then
+    RELEASE_DIR="$BIN_DIR"
+    echo "==> Using prebuilt binaries from $RELEASE_DIR"
+    for bin in fips fipsctl fipstop fips-gateway; do
+        [ -f "$RELEASE_DIR/$bin" ] || {
+            echo "Error: prebuilt binary not found: $RELEASE_DIR/$bin" >&2
+            exit 1
+        }
+    done
+else
+    if ! command -v cargo-zigbuild &>/dev/null; then
+        echo "Error: cargo-zigbuild not found." >&2
+        echo "  Install: cargo install cargo-zigbuild" >&2
+        exit 1
+    fi
+
+    if ! rustup target list --installed | grep -q "^$RUST_TARGET$"; then
+        echo "==> Adding Rust target $RUST_TARGET..."
+        rustup target add "$RUST_TARGET"
+    fi
+
+    echo "==> Compiling..."
+    cd "$PROJECT_ROOT"
+    cargo zigbuild \
+        --release \
+        --target "$RUST_TARGET" \
+        --bin fips \
+        --bin fipsctl \
+        --bin fipstop \
+        --bin fips-gateway
+
+    RELEASE_DIR="$PROJECT_ROOT/target/$RUST_TARGET/release"
+
+    echo "==> Stripping binaries..."
+    STRIP="${LLVM_STRIP:-strip}"
+    for bin in fips fipsctl fipstop fips-gateway; do
+        "$STRIP" "$RELEASE_DIR/$bin" 2>/dev/null || true
+    done
+fi
+
+SIZE=$(du -sh "$RELEASE_DIR/fips" | cut -f1)
+echo "    fips: $SIZE"
+
+# ---------------------------------------------------------------------------
+# 2. Stage the installed filesystem tree (--files root for apk mkpkg)
+# ---------------------------------------------------------------------------
+# This block is the same payload as ../openwrt-ipk/build-ipk.sh; keep the two
+# in sync. The CI apk structural check asserts every path below is present.
+
+WORK_DIR="$(mktemp -d)"
+trap 'rm -rf "$WORK_DIR"' EXIT
+
+STAGE_DIR="$WORK_DIR/root"        # becomes the package's filesystem
+SCRIPTS_DIR="$WORK_DIR/scripts"   # maintainer scripts (metadata, not payload)
+mkdir -p "$STAGE_DIR" "$SCRIPTS_DIR"
+
+install -d "$STAGE_DIR/usr/bin"
+install -m 0755 "$RELEASE_DIR/fips"         "$STAGE_DIR/usr/bin/fips"
+install -m 0755 "$RELEASE_DIR/fipsctl"      "$STAGE_DIR/usr/bin/fipsctl"
+install -m 0755 "$RELEASE_DIR/fipstop"      "$STAGE_DIR/usr/bin/fipstop"
+install -m 0755 "$RELEASE_DIR/fips-gateway" "$STAGE_DIR/usr/bin/fips-gateway"
+
+install -d "$STAGE_DIR/etc/init.d"
+install -m 0755 "$FILES_DIR/etc/init.d/fips"         "$STAGE_DIR/etc/init.d/fips"
+install -m 0755 "$FILES_DIR/etc/init.d/fips-gateway" "$STAGE_DIR/etc/init.d/fips-gateway"
+
+install -d "$STAGE_DIR/etc/fips"
+install -m 0600 "$FILES_DIR/etc/fips/fips.yaml"   "$STAGE_DIR/etc/fips/fips.yaml"
+install -m 0755 "$FILES_DIR/etc/fips/firewall.sh" "$STAGE_DIR/etc/fips/firewall.sh"
+
+# The shared fips.yaml ships ethernet.wan.interface: "eth0", the OpenWrt 24
+# default. This .apk package targets OpenWrt 25+ (DSA), where the WAN port is
+# named "wan", so ship "wan" as the default. Patching the staged copy keeps the
+# as-installed config correct for the platform without maintaining a second copy
+# of the file; operators can still edit /etc/fips/fips.yaml for non-standard boards.
+sed -i 's|interface: "eth0"|interface: "wan"|' "$STAGE_DIR/etc/fips/fips.yaml"
+
+install -d "$STAGE_DIR/etc/dnsmasq.d"
+install -m 0644 "$FILES_DIR/etc/dnsmasq.d/fips.conf" "$STAGE_DIR/etc/dnsmasq.d/fips.conf"
+
+install -d "$STAGE_DIR/etc/sysctl.d"
+install -m 0644 "$FILES_DIR/etc/sysctl.d/fips-bridge.conf"  "$STAGE_DIR/etc/sysctl.d/fips-bridge.conf"
+install -m 0644 "$FILES_DIR/etc/sysctl.d/fips-gateway.conf" "$STAGE_DIR/etc/sysctl.d/fips-gateway.conf"
+
+install -d "$STAGE_DIR/etc/hotplug.d/net"
+install -m 0755 "$FILES_DIR/etc/hotplug.d/net/99-fips" "$STAGE_DIR/etc/hotplug.d/net/99-fips"
+
+install -d "$STAGE_DIR/etc/uci-defaults"
+install -m 0755 "$FILES_DIR/etc/uci-defaults/90-fips-setup" "$STAGE_DIR/etc/uci-defaults/90-fips-setup"
+
+install -d "$STAGE_DIR/lib/upgrade/keep.d"
+install -m 0644 "$FILES_DIR/lib/upgrade/keep.d/fips" "$STAGE_DIR/lib/upgrade/keep.d/fips"
+
+# ---- conffiles ----
+# apk mkpkg discovers config files from /lib/apk/packages/<name>.conffiles
+# inside the --files tree (same mechanism OpenWrt's package-pack.mk uses).
+# Listing fips.yaml here makes apk preserve user edits across upgrades, the
+# apk equivalent of opkg's conffiles handling.
+install -d "$STAGE_DIR/lib/apk/packages"
+cat > "$STAGE_DIR/lib/apk/packages/${PKG_NAME}.conffiles" <<'EOF'
+/etc/fips/fips.yaml
+EOF
+
+# ---- maintainer scripts ----
+# Map our opkg maintainer scripts onto apk's lifecycle phases:
+#   opkg postinst -> apk post-install   (enable + start services)
+#   opkg prerm    -> apk pre-deinstall  (stop + disable services)
+
+cat > "$SCRIPTS_DIR/post-install" <<'EOF'
+#!/bin/sh
+# Run first-boot UCI setup (the script deletes itself when done).
+if [ -x /etc/uci-defaults/90-fips-setup ]; then
+    /etc/uci-defaults/90-fips-setup && rm -f /etc/uci-defaults/90-fips-setup
+fi
+
+/etc/init.d/fips enable
+/etc/init.d/fips start
+/etc/init.d/fips-gateway enable
+/etc/init.d/fips-gateway start
+exit 0
+EOF
+
+cat > "$SCRIPTS_DIR/pre-deinstall" <<'EOF'
+#!/bin/sh
+/etc/init.d/fips-gateway stop    2>/dev/null || true
+/etc/init.d/fips-gateway disable 2>/dev/null || true
+/etc/init.d/fips stop            2>/dev/null || true
+/etc/init.d/fips disable         2>/dev/null || true
+exit 0
+EOF
+
+chmod 0755 "$SCRIPTS_DIR/post-install" "$SCRIPTS_DIR/pre-deinstall"
+
+# ---------------------------------------------------------------------------
+# 3. Assemble the .apk via apk mkpkg
+# ---------------------------------------------------------------------------
+# fakeroot makes the packaged files root-owned even though CI runs unprivileged.
+
+DESCRIPTION="FIPS Mesh Network Daemon. Distributed, decentralized mesh networking over UDP, TCP, and raw Ethernet, with a TUN interface (fips0), ULA IPv6 addressing, and a .fips DNS responder."
+DEPENDS="kmod-tun kmod-br-netfilter kmod-nft-nat kmod-nf-conntrack ip-full"
+
+PKG_FILENAME="${PKG_NAME}_${PKG_VERSION}_${OPENWRT_ARCH}.apk"
+mkdir -p "$DIST_DIR"
+
+FAKEROOT=""
+if command -v fakeroot >/dev/null 2>&1; then
+    FAKEROOT="fakeroot"
+else
+    echo "Warning: fakeroot not found — packaged files will be owned by the build user." >&2
+fi
+
+$FAKEROOT "$APK_BIN" mkpkg \
+    --info "name:$PKG_NAME" \
+    --info "version:$APK_VERSION" \
+    --info "description:$DESCRIPTION" \
+    --info "arch:$OPENWRT_ARCH" \
+    --info "license:MIT" \
+    --info "origin:$PKG_NAME" \
+    --info "url:https://github.com/jmcorgan/fips" \
+    --info "maintainer:FIPS Network" \
+    --info "depends:$DEPENDS" \
+    --script "post-install:$SCRIPTS_DIR/post-install" \
+    --script "pre-deinstall:$SCRIPTS_DIR/pre-deinstall" \
+    --files "$STAGE_DIR" \
+    --output "$DIST_DIR/$PKG_FILENAME"
+
+echo ""
+echo "==> Done: dist/$PKG_FILENAME"
+echo "    $(du -sh "$DIST_DIR/$PKG_FILENAME" | cut -f1)"
+echo ""
+echo "Install on router (OpenWrt 25+, or 24.10 with apk enabled):"
+echo "    scp -O dist/$PKG_FILENAME root@192.168.1.1:/tmp/"
+echo "    ssh root@192.168.1.1 apk add --allow-untrusted /tmp/$PKG_FILENAME"
@@ -132,7 +132,10 @@ The default config enables:

 For Ethernet transport, uncomment the `ethernet:` section and set the correct
 physical interface names for your router. **Always use physical port names
-(`eth0`, `eth1`), never bridge names (`br-lan`).** See
+(`eth0`, `eth1`, or DSA port names like `wan`/`lan1`), never bridge names
+(`br-lan`).** The shipped default WAN port is `eth0` (OpenWrt 24); on OpenWrt
+25 (DSA) boards the WAN port is named `wan` — the `.apk` package ships that
+default. Run `ip link show` to confirm the names on your board. See
 [`deploy/native/README.md`](../../deploy/native/README.md) for details.

 ## Service management
@@ -27,11 +27,14 @@ set -euo pipefail
 # ---------------------------------------------------------------------------

 ARCH="aarch64"
+BIN_DIR=""   # if set, use prebuilt binaries from here instead of compiling

 while [[ $# -gt 0 ]]; do
    case "$1" in
        --arch) ARCH="$2"; shift 2 ;;
        --arch=*) ARCH="${1#*=}"; shift ;;
+        --bin-dir) BIN_DIR="$2"; shift 2 ;;
+        --bin-dir=*) BIN_DIR="${1#*=}"; shift ;;
        *) echo "Unknown argument: $1" >&2; exit 1 ;;
    esac
 done
@@ -86,44 +89,55 @@ PKG_VERSION="${PKG_VERSION:-$(cd "$PROJECT_ROOT" && git describe --tags --always
 echo "==> Building $PKG_NAME $PKG_VERSION for $OPENWRT_ARCH ($RUST_TARGET)"

 # ---------------------------------------------------------------------------
-# Prerequisites
+# 1. Obtain binaries
+#
+# Either use a directory of prebuilt binaries (--bin-dir; CI cross-compiles
+# once in a shared job and hands them to both the .ipk and .apk packagers), or
+# compile from source here for a self-contained local build.
 # ---------------------------------------------------------------------------

-if ! command -v cargo-zigbuild &>/dev/null; then
-    echo "Error: cargo-zigbuild not found." >&2
-    echo "  Install: cargo install cargo-zigbuild" >&2
-    exit 1
+if [ -n "$BIN_DIR" ]; then
+    RELEASE_DIR="$BIN_DIR"
+    echo "==> Using prebuilt binaries from $RELEASE_DIR"
+    for bin in fips fipsctl fipstop fips-gateway; do
+        [ -f "$RELEASE_DIR/$bin" ] || {
+            echo "Error: prebuilt binary not found: $RELEASE_DIR/$bin" >&2
+            exit 1
+        }
+    done
+else
+    if ! command -v cargo-zigbuild &>/dev/null; then
+        echo "Error: cargo-zigbuild not found." >&2
+        echo "  Install: cargo install cargo-zigbuild" >&2
+        exit 1
+    fi
+
+    if ! rustup target list --installed | grep -q "^$RUST_TARGET$"; then
+        echo "==> Adding Rust target $RUST_TARGET..."
+        rustup target add "$RUST_TARGET"
+    fi
+
+    echo "==> Compiling..."
+    cd "$PROJECT_ROOT"
+    cargo zigbuild \
+        --release \
+        --target "$RUST_TARGET" \
+        --bin fips \
+        --bin fipsctl \
+        --bin fipstop \
+        --bin fips-gateway
+
+    RELEASE_DIR="$PROJECT_ROOT/target/$RUST_TARGET/release"
+
+    echo "==> Stripping binaries..."
+    STRIP="${LLVM_STRIP:-strip}"
+    for bin in fips fipsctl fipstop fips-gateway; do
+        "$STRIP" "$RELEASE_DIR/$bin" 2>/dev/null || true
+    done
 fi

-if ! rustup target list --installed | grep -q "^$RUST_TARGET$"; then
-    echo "==> Adding Rust target $RUST_TARGET..."
-    rustup target add "$RUST_TARGET"
-fi
-
-# ---------------------------------------------------------------------------
-# 1. Build
-# ---------------------------------------------------------------------------
-
-echo "==> Compiling..."
-cd "$PROJECT_ROOT"
-cargo zigbuild \
-    --release \
-    --target "$RUST_TARGET" \
-    --bin fips \
-    --bin fipsctl \
-    --bin fipstop \
-    --bin fips-gateway
-
-RELEASE_DIR="$PROJECT_ROOT/target/$RUST_TARGET/release"
-
-echo "==> Stripping binaries..."
-STRIP="${LLVM_STRIP:-strip}"
-for bin in fips fipsctl fipstop fips-gateway; do
-    "$STRIP" "$RELEASE_DIR/$bin" 2>/dev/null || true
-done
-
 SIZE=$(du -sh "$RELEASE_DIR/fips" | cut -f1)
-echo "    fips: $SIZE after strip"
+echo "    fips: $SIZE"

 # ---------------------------------------------------------------------------
 # 2. Assemble .ipk
@@ -12,6 +12,17 @@ start_service() {
 	# Ensure TUN module is loaded before starting the daemon.
 	modprobe tun 2>/dev/null || true

+	# Pre-create the control-socket runtime directory so the daemon binds the
+	# canonical /run/fips/control.sock instead of falling back to /tmp. This is
+	# the procd equivalent of the systemd unit's RuntimeDirectory=fips (and the
+	# fips.tmpfiles "d /run/fips 0750 root fips" entry); OpenWrt was the only
+	# platform missing it. Without it, fips-gateway — which creates /run/fips
+	# for its own gateway.sock — makes fipsctl/fipstop resolve a control socket
+	# under /run/fips that the daemon actually bound under /tmp.
+	mkdir -p /run/fips
+	chmod 0750 /run/fips
+	chgrp fips /run/fips 2>/dev/null || true
+
 	procd_open_instance
 	procd_set_param command "$PROG" --config "$CONFIG"
 	# Respawn: restart after 5 s, give up after 5 consecutive failures within
@@ -83,6 +83,35 @@ fn fwd_value(data: &serde_json::Value, pkt_key: &str, byte_key: &str) -> String
    format!("{} pkts ({})", pkts, helpers::format_bytes(bytes))
 }

+/// Read a raw forwarding counter as a u64 (0 if missing), for arithmetic
+/// (percentages, derived totals) that the string-returning helpers can't do.
+fn fwd_count(data: &serde_json::Value, key: &str) -> u64 {
+    data.get("forwarding")
+        .and_then(|f| f.get(key))
+        .and_then(|v| v.as_u64())
+        .unwrap_or(0)
+}
+
+/// Total mesh egress = locally-originated + transit-forwarded, formatted as
+/// "N pkts (B)". There is no single daemon counter for everything this node
+/// transmits to peers, so it is derived from its two contributors.
+fn mesh_tx_value(data: &serde_json::Value) -> String {
+    let pkts = fwd_count(data, "originated_packets") + fwd_count(data, "forwarded_packets");
+    let bytes = fwd_count(data, "originated_bytes") + fwd_count(data, "forwarded_bytes");
+    format!("{} pkts ({})", pkts, helpers::format_bytes(bytes))
+}
+
+/// Format a route-class count as "N (xx.x%)" where the percentage is the class's
+/// share of total forwarded (transit) packets. Zero forwarded yields "0.0%".
+fn route_class_value(count: u64, total_forwarded: u64) -> String {
+    let pct = if total_forwarded > 0 {
+        count as f64 / total_forwarded as f64 * 100.0
+    } else {
+        0.0
+    };
+    format!("{count} ({pct:.1}%)")
+}
+
 /// Build a section: a styled header line followed by the kv pairs rendered
 /// through the group helper so the section's values share a left edge.
 fn section(title: &str, pairs: &[(&str, String)]) -> Vec<Line<'static>> {
@@ -110,49 +139,39 @@ fn draw_routing_stats(
    let err = |key: &str| helpers::nested_u64(data, "error_signals", key);
    let cong = |key: &str| helpers::nested_u64(data, "congestion", key);

-    // Left column: Forwarding + Discovery. Each section's values share a left
-    // edge via the kv_lines group helper.
+    // The node is an interface adapter between the local host stack and the
+    // mesh; the left column reads each side as a Transmitted/Received pair.
+    //
+    // Local Stack — traffic crossing the TUN / local-origination boundary:
+    // Transmitted is what the host injects into the mesh (originated), Received
+    // is what the mesh hands up to the host (delivered).
    let mut left = section(
-        "Forwarding",
+        "Local Stack",
        &[
+            (
+                "Transmitted",
+                fwd_value(data, "originated_packets", "originated_bytes"),
+            ),
+            (
+                "Received",
+                fwd_value(data, "delivered_packets", "delivered_bytes"),
+            ),
+        ],
+    );
+    left.push(Line::from(""));
+    // Mesh — traffic crossing the peer-link boundary: Transmitted is everything
+    // this node puts on the wire (originated + forwarded, derived), Received is
+    // the ingress aggregate from peers (own-delivered + transit + drops).
+    left.extend(section(
+        "Mesh",
+        &[
+            ("Transmitted", mesh_tx_value(data)),
            (
                "Received",
                fwd_value(data, "received_packets", "received_bytes"),
            ),
-            (
-                "Delivered",
-                fwd_value(data, "delivered_packets", "delivered_bytes"),
-            ),
-            (
-                "Forwarded",
-                fwd_value(data, "forwarded_packets", "forwarded_bytes"),
-            ),
-            (
-                "Originated",
-                fwd_value(data, "originated_packets", "originated_bytes"),
-            ),
-            (
-                "Decode Error",
-                fwd_value(data, "decode_error_packets", "decode_error_bytes"),
-            ),
-            (
-                "TTL Exhausted",
-                fwd_value(data, "ttl_exhausted_packets", "ttl_exhausted_bytes"),
-            ),
-            (
-                "No Route",
-                fwd_value(data, "drop_no_route_packets", "drop_no_route_bytes"),
-            ),
-            (
-                "MTU Exceeded",
-                fwd_value(data, "drop_mtu_exceeded_packets", "drop_mtu_exceeded_bytes"),
-            ),
-            (
-                "Send Error",
-                fwd_value(data, "drop_send_error_packets", "drop_send_error_bytes"),
-            ),
        ],
-    );
+    ));
    left.push(Line::from(""));
    left.extend(section(
        "Discovery Requests",
@@ -184,15 +203,89 @@ fn draw_routing_stats(
        ],
    ));

-    // Right column: Error Signals + Congestion
+    // Right column — "Forwarded" (transit / routed through this node).
+    // Forwarded total, then the route-class breakdown (a percentage partition
+    // of the total), then the transit-path drop reasons.
+    let fwd_total = fwd_count(data, "forwarded_packets");
    let mut right = section(
+        "Forwarded",
+        &[(
+            "Forwarded",
+            fwd_value(data, "forwarded_packets", "forwarded_bytes"),
+        )],
+    );
+    // Blank separator after the Forwarded total, matching the spacing between
+    // every other section pair; the total and its route-class breakdown read
+    // as two distinct groups.
+    right.push(Line::from(""));
+    // Route-class breakdown: a partition of Forwarded, each line annotated with
+    // its share of the total. Tree-down cross — the dive-to-tree-child
+    // cut-through — is the last class; Tree-down + Tree-down cross sum to the
+    // pre-split tree-down total.
+    right.extend(section(
+        "Route Class",
+        &[
+            (
+                "Direct Peer",
+                route_class_value(fwd_count(data, "route_direct_peer"), fwd_total),
+            ),
+            (
+                "Tree-down",
+                route_class_value(fwd_count(data, "route_tree_down"), fwd_total),
+            ),
+            (
+                "Tree-up",
+                route_class_value(fwd_count(data, "route_tree_up"), fwd_total),
+            ),
+            (
+                "Cross-link descend",
+                route_class_value(fwd_count(data, "route_crosslink_descend"), fwd_total),
+            ),
+            (
+                "Cross-link ascend",
+                route_class_value(fwd_count(data, "route_crosslink_ascend"), fwd_total),
+            ),
+            (
+                "Tree-down cross",
+                route_class_value(fwd_count(data, "route_tree_down_cross"), fwd_total),
+            ),
+        ],
+    ));
+    right.push(Line::from(""));
+    right.extend(section(
+        "Dropped",
+        &[
+            (
+                "No Route",
+                fwd_value(data, "drop_no_route_packets", "drop_no_route_bytes"),
+            ),
+            (
+                "TTL Exhausted",
+                fwd_value(data, "ttl_exhausted_packets", "ttl_exhausted_bytes"),
+            ),
+            (
+                "Decode Error",
+                fwd_value(data, "decode_error_packets", "decode_error_bytes"),
+            ),
+            (
+                "MTU Exceeded",
+                fwd_value(data, "drop_mtu_exceeded_packets", "drop_mtu_exceeded_bytes"),
+            ),
+            (
+                "Send Error",
+                fwd_value(data, "drop_send_error_packets", "drop_send_error_bytes"),
+            ),
+        ],
+    ));
+    right.push(Line::from(""));
+    right.extend(section(
        "Error Signals",
        &[
            ("Coords Required", err("coords_required")),
            ("Path Broken", err("path_broken")),
            ("MTU Exceeded", err("mtu_exceeded")),
        ],
-    );
+    ));
    right.push(Line::from(""));
    right.extend(section(
        "Congestion",
@@ -1134,7 +1134,12 @@ fn routing_focused_pane_scrolls() {
    let mut app1 = app_with(Tab::Routing, data);
    app1.data.insert(Tab::Cache, json!({}));
    app1.focused_pane.insert(Tab::Routing, 2);
-    app1.scroll_offsets.insert((Tab::Routing, 2), 6);
+    // Congestion is the last section of the right ("Forwarded") column, below
+    // the route-class breakdown, Dropped, and Error Signals groups. The left
+    // column is the taller of the two, so scrolling fully to the bottom would
+    // over-scroll the right column past Congestion; this offset lands the
+    // Congestion region inside the short window instead.
+    app1.scroll_offsets.insert((Tab::Routing, 2), 24);
    let buf1 = testkit::render(100, 20, |frame, area| {
        super::routing::draw(frame, &app1, area);
    });
@@ -53,6 +53,12 @@
      "originated_packets": 0,
      "received_bytes": 0,
      "received_packets": 0,
+      "route_crosslink_ascend": 0,
+      "route_crosslink_descend": 0,
+      "route_direct_peer": 0,
+      "route_tree_down": 0,
+      "route_tree_down_cross": 0,
+      "route_tree_up": 0,
      "ttl_exhausted_bytes": 0,
      "ttl_exhausted_packets": 0
    },
@@ -22,6 +22,12 @@
      "originated_packets": 0,
      "received_bytes": 0,
      "received_packets": 0,
+      "route_crosslink_ascend": 0,
+      "route_crosslink_descend": 0,
+      "route_direct_peer": 0,
+      "route_tree_down": 0,
+      "route_tree_down_cross": 0,
+      "route_tree_up": 0,
      "ttl_exhausted_bytes": 0,
      "ttl_exhausted_packets": 0
    },
@@ -151,6 +151,11 @@ impl Node {
            }
        } else {
            self.metrics().forwarding.record_forwarded(encoded.len());
+            // Classify this transit forward by route class (partition of
+            // forwarded_packets). Done here, at the data-plane chokepoint, so
+            // the error-signal routing callers of find_next_hop are excluded.
+            let class = self.classify_forward(&datagram.dest_addr, &next_hop_addr);
+            self.metrics().forwarding.record_route_class(class);
            if outgoing_ce {
                self.metrics().congestion.ce_forwarded.inc();
            }
@@ -81,6 +81,51 @@ pub struct ForwardingMetrics {
    pub drop_send_error_bytes: Counter,
    pub originated_packets: Counter,
    pub originated_bytes: Counter,
+    pub route_tree_up: Counter,
+    pub route_tree_down: Counter,
+    pub route_tree_down_cross: Counter,
+    pub route_crosslink_descend: Counter,
+    pub route_crosslink_ascend: Counter,
+    pub route_direct_peer: Counter,
+}
+
+/// Route class of a transit-forwarded packet, classified from tree
+/// coordinates at the forwarding decision point. The six variants
+/// partition `forwarded_packets` exactly.
+///
+/// Two variants are up-and-over forwards (destination not in the chosen
+/// peer's subtree); they differ in whether they depend on a child
+/// advertising cross-link reach *upward* to its parent:
+/// - `TreeDownCross`: the chosen peer is our tree descendant, but the
+///   destination is *not* in that child's subtree. The forward only fired
+///   because the child advertised cross-link reach upward to us, beyond its
+///   own subtree. If children advertised only their subtree upward, this
+///   forward would route up instead, so its count measures how much
+///   forwarding depends on the upward cross-link advertisement — the
+///   dive-to-tree-child cut-through.
+/// - `CrosslinkAscend`: the chosen peer is lateral (neither ancestor nor
+///   descendant) and the destination is not in its subtree. This is a node
+///   using its *own* cross-link, learned via the peer's split-horizon
+///   advertisement to its neighbors, so it does not depend on any upward
+///   advertisement. Tracked alongside `TreeDownCross` as the lateral
+///   up-and-over contrast.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RouteClass {
+    /// Chosen peer is our ancestor (tree-up).
+    TreeUp,
+    /// Chosen peer is our descendant and dest is in its subtree (canonical
+    /// tree-down).
+    TreeDown,
+    /// Chosen peer is our descendant but dest is *not* in its subtree: the
+    /// dive-to-tree-child cut-through enabled by upward cross-link
+    /// advertisement.
+    TreeDownCross,
+    /// Chosen peer is lateral and dest is in its subtree (subtree entry).
+    CrosslinkDescend,
+    /// Chosen peer is lateral and dest is not in its subtree (up-and-over).
+    CrosslinkAscend,
+    /// Chosen peer is the destination itself (degenerate direct hop).
+    DirectPeer,
 }

 impl ForwardingMetrics {
@@ -112,6 +157,21 @@ impl ForwardingMetrics {
        self.originated_bytes.add(bytes as u64);
    }

+    /// Record the route class of a transit-forwarded packet. The five
+    /// classes partition `forwarded_packets`, so this is called exactly
+    /// once per `record_forwarded` (transit chokepoint only).
+    #[inline]
+    pub fn record_route_class(&self, class: RouteClass) {
+        match class {
+            RouteClass::TreeUp => self.route_tree_up.inc(),
+            RouteClass::TreeDown => self.route_tree_down.inc(),
+            RouteClass::TreeDownCross => self.route_tree_down_cross.inc(),
+            RouteClass::CrosslinkDescend => self.route_crosslink_descend.inc(),
+            RouteClass::CrosslinkAscend => self.route_crosslink_ascend.inc(),
+            RouteClass::DirectPeer => self.route_direct_peer.inc(),
+        }
+    }
+
    /// Mirror of `ForwardingStats::record_reject_bytes`: route a typed
    /// forwarding rejection of `bytes` payload to its packet and byte
    /// counters.
@@ -163,6 +223,12 @@ impl ForwardingMetrics {
            drop_send_error_bytes: self.drop_send_error_bytes.get(),
            originated_packets: self.originated_packets.get(),
            originated_bytes: self.originated_bytes.get(),
+            route_tree_up: self.route_tree_up.get(),
+            route_tree_down: self.route_tree_down.get(),
+            route_tree_down_cross: self.route_tree_down_cross.get(),
+            route_crosslink_descend: self.route_crosslink_descend.get(),
+            route_crosslink_ascend: self.route_crosslink_ascend.get(),
+            route_direct_peer: self.route_direct_peer.get(),
        }
    }
 }
@@ -2666,6 +2666,86 @@ impl Node {
        self.peers.get(&next_hop_id).filter(|p| p.can_send())
    }

+    /// Classify a transit forward by route class from tree coordinates.
+    ///
+    /// Called at the transit chokepoint after `find_next_hop` returns a peer,
+    /// so the six classes partition `forwarded_packets` exactly. The branch
+    /// that `find_next_hop` took (bloom vs greedy-tree) is *not* the route
+    /// class: a peer can be selected by either, so the cut-through splits
+    /// (`TreeDownCross`, `CrosslinkAscend`) are decided here from coordinates,
+    /// not from which branch fired.
+    ///
+    /// Inputs: our coords (`tree_state.my_coords`), the chosen peer's coords
+    /// (`tree_state.peer_coords`), and the destination coords (re-read from the
+    /// coord cache, which `find_next_hop` just touched). Both the tree-down and
+    /// cross-link branches split on whether the destination is in the chosen
+    /// peer's subtree; when the dest coords are unavailable that test defaults
+    /// to "not in subtree", i.e. the up-and-over variant (`TreeDownCross` for a
+    /// descendant peer, `CrosslinkAscend` for a lateral one).
+    pub(crate) fn classify_forward(
+        &self,
+        dest: &NodeAddr,
+        chosen_peer: &NodeAddr,
+    ) -> metrics::RouteClass {
+        // Degenerate: the next hop is the destination itself (Branch 2).
+        if chosen_peer == dest {
+            return metrics::RouteClass::DirectPeer;
+        }
+
+        let my_addr = self.node_addr();
+        let my_coords = self.tree_state.my_coords();
+
+        // Tree-up: the chosen peer is our ancestor.
+        if my_coords.has_ancestor(chosen_peer) {
+            return metrics::RouteClass::TreeUp;
+        }
+
+        // Whether the destination is in the chosen peer's subtree. Both the
+        // tree-down and cross-link splits below turn on this same test, so it
+        // is computed once. On the live transit path the dest coords are
+        // always present here: `find_next_hop` looks them up with an early
+        // return, so a coord-cache miss yields no next hop to classify (the
+        // caller signals `CoordsRequired` instead of forwarding). The miss
+        // branch below is therefore defensive — reachable only by direct
+        // unit-test calls — and defaults the test to "not in subtree", i.e.
+        // the up-and-over variant of whichever branch fires (TreeDownCross for
+        // a descendant peer, CrosslinkAscend for a lateral one), matching the
+        // original cross-link default-to-ascend.
+        let now_ms = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .map(|d| d.as_millis() as u64)
+            .unwrap_or(0);
+        let dest_in_peer_subtree = self
+            .coord_cache
+            .get(dest, now_ms)
+            .is_some_and(|dest_coords| dest_coords.has_ancestor(chosen_peer));
+
+        // Tree-down: the chosen peer is our descendant (we are its ancestor).
+        // Split by subtree membership: a dest genuinely below the child is the
+        // canonical tree-down; a dest *not* below it means we only forwarded
+        // down because the child advertised cross-link reach upward, beyond its
+        // own subtree — the dive-to-tree-child cut-through (TreeDownCross).
+        if let Some(peer_coords) = self.tree_state.peer_coords(chosen_peer)
+            && peer_coords.has_ancestor(my_addr)
+        {
+            return if dest_in_peer_subtree {
+                metrics::RouteClass::TreeDown
+            } else {
+                metrics::RouteClass::TreeDownCross
+            };
+        }
+
+        // Cross-link (lateral): split by whether the destination is in the
+        // chosen peer's subtree. Descend = subtree entry; ascend = up-and-over
+        // via the node's own cross-link (learned from the peer's split-horizon
+        // advertisement, independent of any upward advertisement).
+        if dest_in_peer_subtree {
+            return metrics::RouteClass::CrosslinkDescend;
+        }
+
+        metrics::RouteClass::CrosslinkAscend
+    }
+
    /// Select the best peer from a set of bloom filter candidates.
    ///
    /// Uses distance from each candidate's tree coordinates to the destination
@@ -229,6 +229,12 @@ pub struct ForwardingStatsSnapshot {
    pub drop_send_error_bytes: u64,
    pub originated_packets: u64,
    pub originated_bytes: u64,
+    pub route_tree_up: u64,
+    pub route_tree_down: u64,
+    pub route_tree_down_cross: u64,
+    pub route_crosslink_descend: u64,
+    pub route_crosslink_ascend: u64,
+    pub route_direct_peer: u64,
 }

 #[derive(Clone, Debug, Default, Serialize)]
@@ -1110,3 +1110,226 @@ async fn test_routing_source_only_coords_100_nodes() {

    cleanup_nodes(&mut nodes).await;
 }
+
+// === Route-class classification (transit-forward partition) ===
+
+use crate::node::metrics::{ForwardingMetrics, RouteClass};
+
+/// Current epoch millis, matching the cache-insert idiom used above.
+fn now_ms() -> u64 {
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|d| d.as_millis() as u64)
+        .unwrap_or(0)
+}
+
+#[test]
+fn test_classify_forward_tree_up() {
+    // my_coords = [me, parent, root]; the chosen peer is our parent (an
+    // ancestor in our path) → tree-up.
+    let mut node = make_node();
+    let me = *node.node_addr();
+    let parent = make_node_addr(10);
+    let root = make_node_addr(1);
+    node.tree_state_mut()
+        .set_my_coords_for_test(TreeCoordinate::from_addrs(vec![me, parent, root]).unwrap());
+
+    // Destination somewhere above us; routed via the parent.
+    let dest = make_node_addr(50);
+    node.coord_cache_mut().insert(
+        dest,
+        TreeCoordinate::from_addrs(vec![dest, root]).unwrap(),
+        now_ms(),
+    );
+
+    assert_eq!(
+        node.classify_forward(&dest, &parent),
+        RouteClass::TreeUp,
+        "chosen peer is our ancestor"
+    );
+}
+
+#[test]
+fn test_classify_forward_tree_down() {
+    // Chosen peer is our descendant: its coords name us as an ancestor.
+    let mut node = make_node();
+    let me = *node.node_addr();
+    let root = make_node_addr(1);
+    node.tree_state_mut()
+        .set_my_coords_for_test(TreeCoordinate::from_addrs(vec![me, root]).unwrap());
+
+    let child = make_node_addr(20);
+    node.tree_state_mut().update_peer(
+        ParentDeclaration::new(child, me, 1, 1000),
+        TreeCoordinate::from_addrs(vec![child, me, root]).unwrap(),
+    );
+
+    // Destination below the child; routed down to it.
+    let dest = make_node_addr(60);
+    node.coord_cache_mut().insert(
+        dest,
+        TreeCoordinate::from_addrs(vec![dest, child, me, root]).unwrap(),
+        now_ms(),
+    );
+
+    assert_eq!(
+        node.classify_forward(&dest, &child),
+        RouteClass::TreeDown,
+        "chosen peer is our descendant, dest in its subtree"
+    );
+}
+
+#[test]
+fn test_classify_forward_tree_down_cross() {
+    // Chosen peer is our descendant (a tree child), but the destination is NOT
+    // in that child's subtree: we are diving down to the child only because it
+    // advertised cross-link reach upward, beyond its own subtree. This is the
+    // dive-to-tree-child cut-through.
+    let mut node = make_node();
+    let me = *node.node_addr();
+    let root = make_node_addr(1);
+    node.tree_state_mut()
+        .set_my_coords_for_test(TreeCoordinate::from_addrs(vec![me, root]).unwrap());
+
+    let child = make_node_addr(20);
+    node.tree_state_mut().update_peer(
+        ParentDeclaration::new(child, me, 1, 1000),
+        TreeCoordinate::from_addrs(vec![child, me, root]).unwrap(),
+    );
+
+    // Destination lives elsewhere (directly under root), NOT under the child;
+    // reachable from the child only via a cross-link.
+    let dest = make_node_addr(60);
+    node.coord_cache_mut().insert(
+        dest,
+        TreeCoordinate::from_addrs(vec![dest, root]).unwrap(),
+        now_ms(),
+    );
+
+    assert_eq!(
+        node.classify_forward(&dest, &child),
+        RouteClass::TreeDownCross,
+        "descendant peer, dest not in its subtree (dive-to-tree-child cut-through)"
+    );
+}
+
+#[test]
+fn test_classify_forward_crosslink_descend() {
+    // Chosen peer is lateral (not in our path, we are not in its path) and the
+    // destination is inside the peer's subtree → cross-link descend.
+    let mut node = make_node();
+    let me = *node.node_addr();
+    let root = make_node_addr(1);
+    let sibling_parent = make_node_addr(2);
+    node.tree_state_mut()
+        .set_my_coords_for_test(TreeCoordinate::from_addrs(vec![me, root]).unwrap());
+
+    let peer = make_node_addr(30);
+    node.tree_state_mut().update_peer(
+        ParentDeclaration::new(peer, sibling_parent, 1, 1000),
+        TreeCoordinate::from_addrs(vec![peer, sibling_parent, root]).unwrap(),
+    );
+
+    // Destination is under the cross-link peer.
+    let dest = make_node_addr(70);
+    node.coord_cache_mut().insert(
+        dest,
+        TreeCoordinate::from_addrs(vec![dest, peer, sibling_parent, root]).unwrap(),
+        now_ms(),
+    );
+
+    assert_eq!(
+        node.classify_forward(&dest, &peer),
+        RouteClass::CrosslinkDescend,
+        "lateral peer, dest in its subtree"
+    );
+}
+
+#[test]
+fn test_classify_forward_crosslink_ascend() {
+    // Chosen peer is lateral and the destination is NOT in its subtree → the
+    // up-and-over case (the Bloom v2 behavior delta).
+    let mut node = make_node();
+    let me = *node.node_addr();
+    let root = make_node_addr(1);
+    let sibling_parent = make_node_addr(2);
+    node.tree_state_mut()
+        .set_my_coords_for_test(TreeCoordinate::from_addrs(vec![me, root]).unwrap());
+
+    let peer = make_node_addr(40);
+    node.tree_state_mut().update_peer(
+        ParentDeclaration::new(peer, sibling_parent, 1, 1000),
+        TreeCoordinate::from_addrs(vec![peer, sibling_parent, root]).unwrap(),
+    );
+
+    // Destination lives elsewhere (under root directly), NOT under the peer.
+    let dest = make_node_addr(80);
+    node.coord_cache_mut().insert(
+        dest,
+        TreeCoordinate::from_addrs(vec![dest, root]).unwrap(),
+        now_ms(),
+    );
+
+    assert_eq!(
+        node.classify_forward(&dest, &peer),
+        RouteClass::CrosslinkAscend,
+        "lateral peer, dest not in its subtree"
+    );
+}
+
+#[test]
+fn test_classify_forward_direct_peer() {
+    // Degenerate case: the next hop is the destination itself.
+    let mut node = make_node();
+    let me = *node.node_addr();
+    let root = make_node_addr(1);
+    node.tree_state_mut()
+        .set_my_coords_for_test(TreeCoordinate::from_addrs(vec![me, root]).unwrap());
+
+    let dest = make_node_addr(90);
+    assert_eq!(
+        node.classify_forward(&dest, &dest),
+        RouteClass::DirectPeer,
+        "next hop is the destination"
+    );
+}
+
+#[test]
+fn test_route_class_partition_sums_to_forwarded() {
+    // The six route classes partition forwarded_packets: bumping
+    // record_forwarded once per record_route_class keeps the sum of the class
+    // counters equal to forwarded_packets.
+    let m = ForwardingMetrics::default();
+    let classes = [
+        RouteClass::TreeUp,
+        RouteClass::TreeUp,
+        RouteClass::TreeDown,
+        RouteClass::TreeDownCross,
+        RouteClass::TreeDownCross,
+        RouteClass::CrosslinkDescend,
+        RouteClass::CrosslinkAscend,
+        RouteClass::CrosslinkAscend,
+        RouteClass::CrosslinkAscend,
+        RouteClass::DirectPeer,
+    ];
+    for &c in &classes {
+        m.record_forwarded(100);
+        m.record_route_class(c);
+    }
+
+    let snap = m.snapshot();
+    let class_sum = snap.route_tree_up
+        + snap.route_tree_down
+        + snap.route_tree_down_cross
+        + snap.route_crosslink_descend
+        + snap.route_crosslink_ascend
+        + snap.route_direct_peer;
+    assert_eq!(
+        class_sum, snap.forwarded_packets,
+        "route classes must partition forwarded_packets"
+    );
+    assert_eq!(snap.route_tree_up, 2);
+    assert_eq!(snap.route_tree_down_cross, 2);
+    assert_eq!(snap.route_crosslink_ascend, 3);
+    assert_eq!(snap.route_direct_peer, 1);
+}
@@ -92,6 +92,15 @@ impl TreeState {
        &self.my_coords
    }

+    /// Test-only override of this node's coordinates, bypassing the
+    /// parent/declaration state machine. Lets routing tests place the node at
+    /// an arbitrary tree position to exercise coordinate-based classification.
+    #[cfg(test)]
+    pub(crate) fn set_my_coords_for_test(&mut self, coords: TreeCoordinate) {
+        self.root = *coords.root_id();
+        self.my_coords = coords;
+    }
+
    /// Get the current root.
    pub fn root(&self) -> &NodeAddr {
        &self.root
@@ -115,8 +115,8 @@ pub fn clamp_tcp_mss(ipv6_packet: &mut [u8], max_mss: u16) -> bool {
            if current_mss > max_mss {
                ipv6_packet[i + 2..i + 4].copy_from_slice(&max_mss.to_be_bytes());

-                // Recalculate TCP checksum
-                recalculate_tcp_checksum(ipv6_packet, tcp_start);
+                // Recompute the now-stale checksum over the rewritten header.
+                recalculate_l4_checksum(ipv6_packet);

                modified = true;
            }
@@ -129,41 +129,39 @@ pub fn clamp_tcp_mss(ipv6_packet: &mut [u8], max_mss: u16) -> bool {
    modified
 }

-/// Recalculate TCP checksum after modifying the packet.
-fn recalculate_tcp_checksum(ipv6_packet: &mut [u8], tcp_start: usize) {
-    // Zero out existing checksum
-    ipv6_packet[tcp_start + 16] = 0;
-    ipv6_packet[tcp_start + 17] = 0;
-
-    // Extract addresses
-    let src = &ipv6_packet[8..24];
-    let dst = &ipv6_packet[24..40];
-
-    // Get TCP segment length
+/// Recalculate the TCP or UDP checksum (IPv6 pseudo-header + segment) in place.
+///
+/// Completes the checksum macOS leaves offloaded on hairpinned self-traffic, and
+/// is reused by MSS clamping. No-op for other next-headers (e.g. ICMPv6) and for
+/// malformed packets. Assumes the L4 header follows the 40-byte IPv6 header, as
+/// all FIPS packets do.
+pub fn recalculate_l4_checksum(ipv6_packet: &mut [u8]) {
+    if ipv6_packet.len() < 40 || ipv6_packet[0] >> 4 != 6 {
+        return;
+    }
    let payload_len = u16::from_be_bytes([ipv6_packet[4], ipv6_packet[5]]) as usize;
-    let tcp_segment = &ipv6_packet[tcp_start..tcp_start + payload_len];
+    if payload_len == 0 || 40 + payload_len > ipv6_packet.len() {
+        return;
+    }

-    // Calculate checksum with pseudo-header
+    // Transport checksum field offset within the packet: TCP at 16, UDP at 6.
+    let proto = ipv6_packet[6];
+    let csum = match proto {
+        6 if payload_len >= TCP_HEADER_MIN_LEN => 40 + 16,
+        17 if payload_len >= 8 => 40 + 6,
+        _ => return,
+    };
+    ipv6_packet[csum] = 0;
+    ipv6_packet[csum + 1] = 0;
+
+    // Pseudo-header (src + dst are contiguous at 8..40), length, next header,
    let mut sum: u32 = 0;
-
-    // Pseudo-header: source address
-    for chunk in src.chunks(2) {
+    for chunk in ipv6_packet[8..40].chunks(2) {
        sum += u16::from_be_bytes([chunk[0], chunk[1]]) as u32;
    }
-
-    // Pseudo-header: destination address
-    for chunk in dst.chunks(2) {
-        sum += u16::from_be_bytes([chunk[0], chunk[1]]) as u32;
-    }
-
-    // Pseudo-header: TCP length
-    sum += payload_len as u32;
-
-    // Pseudo-header: next header (TCP = 6)
-    sum += 6;
-
-    // TCP segment
-    for chunk in tcp_segment.chunks(2) {
+    sum += payload_len as u32 + proto as u32;
+    // then the transport segment itself (with the checksum field zeroed above).
+    for chunk in ipv6_packet[40..40 + payload_len].chunks(2) {
        let value = if chunk.len() == 2 {
            u16::from_be_bytes([chunk[0], chunk[1]])
        } else {
@@ -171,15 +169,16 @@ fn recalculate_tcp_checksum(ipv6_packet: &mut [u8], tcp_start: usize) {
        };
        sum += value as u32;
    }
-
-    // Fold 32-bit sum to 16 bits
    while sum >> 16 != 0 {
        sum = (sum & 0xffff) + (sum >> 16);
    }

-    // One's complement
-    let checksum = !sum as u16;
-    ipv6_packet[tcp_start + 16..tcp_start + 18].copy_from_slice(&checksum.to_be_bytes());
+    // IPv6 forbids an all-zero UDP checksum; send 0xffff instead (TCP keeps 0).
+    let checksum = match (!sum as u16, proto) {
+        (0, 17) => 0xffff,
+        (c, _) => c,
+    };
+    ipv6_packet[csum..csum + 2].copy_from_slice(&checksum.to_be_bytes());
 }

 #[cfg(test)]
@@ -216,7 +215,7 @@ mod tests {
        packet[tcp_start + 24] = 0;

        // Calculate checksum
-        recalculate_tcp_checksum(&mut packet, tcp_start);
+        recalculate_l4_checksum(&mut packet);

        packet
    }
@@ -277,4 +276,126 @@ mod tests {

        assert!(!modified);
    }
+
+    // ========================================================================
+    // recalculate_l4_checksum — finish macOS's offloaded self-traffic
+    // checksums (the bug that left ACK/data/FIN segments undeliverable).
+    // ========================================================================
+
+    /// True if the packet's TCP/UDP checksum verifies (folded ones-complement
+    /// sum over pseudo-header + segment, including the checksum field, == 0xffff).
+    fn l4_checksum_valid(pkt: &[u8]) -> bool {
+        let payload_len = u16::from_be_bytes([pkt[4], pkt[5]]) as usize;
+        let mut sum: u32 = 0;
+        for chunk in pkt[8..40].chunks(2) {
+            sum += u16::from_be_bytes([chunk[0], chunk[1]]) as u32;
+        }
+        sum += payload_len as u32;
+        sum += pkt[6] as u32; // next header
+        for chunk in pkt[40..40 + payload_len].chunks(2) {
+            let v = if chunk.len() == 2 {
+                u16::from_be_bytes([chunk[0], chunk[1]])
+            } else {
+                u16::from_be_bytes([chunk[0], 0])
+            };
+            sum += v as u32;
+        }
+        while sum >> 16 != 0 {
+            sum = (sum & 0xffff) + (sum >> 16);
+        }
+        sum as u16 == 0xffff
+    }
+
+    const SELF_ADDR: [u8; 16] = [0xfd, 0x12, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0x55];
+
+    /// A self-addressed 20-byte TCP ACK (no options) carrying a deliberately
+    /// wrong checksum — the shape macOS hands us for hairpinned non-SYN traffic.
+    fn make_tcp_ack_packet() -> Vec<u8> {
+        let mut p = vec![0u8; 40 + 20];
+        p[0] = 0x60;
+        p[4..6].copy_from_slice(&20u16.to_be_bytes()); // payload length
+        p[6] = 6; // TCP
+        p[7] = 64;
+        p[8..24].copy_from_slice(&SELF_ADDR);
+        p[24..40].copy_from_slice(&SELF_ADDR);
+        let t = 40;
+        p[t..t + 2].copy_from_slice(&52097u16.to_be_bytes());
+        p[t + 2..t + 4].copy_from_slice(&9999u16.to_be_bytes());
+        p[t + 4..t + 8].copy_from_slice(&1000u32.to_be_bytes()); // seq
+        p[t + 8..t + 12].copy_from_slice(&2000u32.to_be_bytes()); // ack
+        p[t + 12] = 0x50; // data offset = 5 (20-byte header)
+        p[t + 13] = 0x10; // ACK
+        p[t + 14..t + 16].copy_from_slice(&2049u16.to_be_bytes()); // window
+        p[t + 16] = 0x8e; // bogus checksum (macOS pseudo-header partial)
+        p[t + 17] = 0xce;
+        p
+    }
+
+    #[test]
+    fn recompute_fixes_tcp_non_syn_checksum() {
+        let mut pkt = make_tcp_ack_packet();
+        assert!(
+            !l4_checksum_valid(&pkt),
+            "fixture should start with a bad checksum"
+        );
+        recalculate_l4_checksum(&mut pkt);
+        assert!(
+            l4_checksum_valid(&pkt),
+            "TCP checksum must verify after recompute"
+        );
+    }
+
+    #[test]
+    fn recompute_fixes_udp_checksum() {
+        let mut p = vec![0u8; 40 + 12]; // 8-byte UDP header + 4-byte payload
+        p[0] = 0x60;
+        p[4..6].copy_from_slice(&12u16.to_be_bytes());
+        p[6] = 17; // UDP
+        p[7] = 64;
+        p[8..24].copy_from_slice(&SELF_ADDR);
+        p[24..40].copy_from_slice(&SELF_ADDR);
+        let u = 40;
+        p[u..u + 2].copy_from_slice(&40000u16.to_be_bytes()); // src port
+        p[u + 2..u + 4].copy_from_slice(&5354u16.to_be_bytes()); // dst port
+        p[u + 4..u + 6].copy_from_slice(&12u16.to_be_bytes()); // UDP length
+        p[u + 6] = 0x8e; // bogus checksum
+        p[u + 7] = 0xce;
+        p[u + 8..u + 12].copy_from_slice(&[0xde, 0xad, 0xbe, 0xef]); // payload
+
+        assert!(!l4_checksum_valid(&p), "fixture should start invalid");
+        recalculate_l4_checksum(&mut p);
+        assert!(
+            l4_checksum_valid(&p),
+            "UDP checksum must verify after recompute"
+        );
+        assert_ne!(
+            &p[u + 6..u + 8],
+            &[0, 0],
+            "IPv6 UDP checksum must not be zero"
+        );
+    }
+
+    #[test]
+    fn recompute_is_noop_for_non_transport() {
+        // Next-header 59 (No Next Header): nothing to checksum.
+        let mut pkt = vec![0u8; 60];
+        pkt[0] = 0x60;
+        pkt[4..6].copy_from_slice(&20u16.to_be_bytes());
+        pkt[6] = 59;
+        let before = pkt.clone();
+        recalculate_l4_checksum(&mut pkt);
+        assert_eq!(pkt, before, "non-transport packet must be left untouched");
+    }
+
+    #[test]
+    fn recompute_ignores_truncated_packet() {
+        // payload_len claims 20 bytes of TCP but only 10 are present.
+        let mut pkt = vec![0u8; 40 + 10];
+        pkt[0] = 0x60;
+        pkt[4..6].copy_from_slice(&20u16.to_be_bytes());
+        pkt[6] = 6;
+        let before = pkt.clone();
+        recalculate_l4_checksum(&mut pkt); // must not panic
+        assert_eq!(pkt, before, "truncated packet must be left untouched");
+    }
 }
@@ -693,7 +693,7 @@ fn handle_tun_packet(
    path_mtu_lookup: &PathMtuLookup,
 ) -> bool {
    use super::icmp::{DestUnreachableCode, build_dest_unreachable, should_send_icmp_error};
-    use super::tcp_mss::clamp_tcp_mss;
+    use super::tcp_mss::{clamp_tcp_mss, recalculate_l4_checksum};

    log_ipv6_packet(packet);

@@ -704,6 +704,30 @@ fn handle_tun_packet(

    // Check if destination is a FIPS address (fd::/8 prefix)
    if packet[24] == crate::identity::FIPS_ADDRESS_PREFIX {
+        // Loopback: a packet to our own mesh address must be delivered
+        // locally, not pushed into the mesh (we have no session/route to
+        // ourselves, so it would just be dropped). Hairpin it back to the TUN
+        // writer for inbound delivery.
+        //
+        // Platform note: in practice this branch is reached only on macOS.
+        // macOS point-to-point `utun` interfaces egress self-addressed traffic
+        // down the tunnel into this reader, so the daemon has to loop it back
+        // itself. On Linux the kernel routes traffic to our own bound
+        // addresses via `lo` before it ever reaches the TUN, so this branch
+        // never fires there. The check is kept unconditional anyway, both as a
+        // platform-independent self-delivery invariant and so the path stays
+        // exercised by the Linux-only CI unit tests.
+        if packet[24..40] == *our_addr.as_bytes() {
+            trace!(name = %name, "Hairpinning self-addressed packet back to TUN (loopback)");
+            // Finish the checksum macOS leaves offloaded on self-traffic, else the
+            // local stack drops every non-SYN segment. See recalculate_l4_checksum.
+            recalculate_l4_checksum(packet);
+            if tun_tx.send(packet.to_vec()).is_err() {
+                return false; // Channel closed, shutdown
+            }
+            return true;
+        }
+
        // Per-destination clamp: if discovery has learned a smaller path
        // MTU for this destination, tighten the ceiling for this flow.
        let effective_max_mss = per_flow_max_mss(path_mtu_lookup, &packet[24..40], max_mss);
@@ -1520,6 +1544,88 @@ mod tests {
        assert_eq!(per_flow_max_mss(&lookup, b.as_bytes(), 1360), 1315);
    }

+    // ========================================================================
+    // handle_tun_packet — self-addressed loopback hairpin
+    //
+    // A packet destined for our own mesh address must be delivered back to
+    // the local stack via the TUN writer, never pushed into the mesh (there
+    // is no session/route to ourselves). On macOS the kernel egresses such
+    // self-traffic down the utun into the reader, so the daemon has to loop
+    // it back itself.
+    // ========================================================================
+
+    /// Build a minimal 40-byte IPv6 packet (no upper-layer payload) addressed
+    /// to `dst`, sourced from a distinct fips address.
+    fn ipv6_packet_to(dst: &FipsAddress) -> Vec<u8> {
+        let mut pkt = vec![0u8; 40];
+        pkt[0] = 0x60; // version 6
+        pkt[6] = 59; // next header = No Next Header (skips MSS clamp)
+        pkt[7] = 64; // hop limit
+        pkt[8] = crate::identity::FIPS_ADDRESS_PREFIX; // src in fd::/8
+        pkt[24..40].copy_from_slice(dst.as_bytes()); // dst
+        pkt
+    }
+
+    #[test]
+    fn self_addressed_packet_is_hairpinned_to_tun() {
+        let our_addr = fips_addr_with_node_byte(0x55);
+        let (tun_tx, tun_rx) = mpsc::channel::<Vec<u8>>();
+        let (outbound_tx, mut outbound_rx) = tokio::sync::mpsc::channel::<Vec<u8>>(4);
+        let lookup = empty_lookup();
+        let mut pkt = ipv6_packet_to(&our_addr);
+
+        assert!(handle_tun_packet(
+            &mut pkt,
+            1360,
+            "test0",
+            our_addr,
+            &tun_tx,
+            &outbound_tx,
+            &lookup,
+        ));
+
+        // Delivered locally via the TUN writer...
+        let looped = tun_rx
+            .try_recv()
+            .expect("self-addressed packet should be hairpinned to the TUN");
+        assert_eq!(&looped[24..40], our_addr.as_bytes());
+        // ...and never handed to the mesh.
+        assert!(
+            outbound_rx.try_recv().is_err(),
+            "self-addressed packet must not be pushed into the mesh"
+        );
+    }
+
+    #[test]
+    fn other_fips_packet_goes_to_mesh() {
+        let our_addr = fips_addr_with_node_byte(0x55);
+        let peer = fips_addr_with_node_byte(0x66);
+        let (tun_tx, tun_rx) = mpsc::channel::<Vec<u8>>();
+        let (outbound_tx, mut outbound_rx) = tokio::sync::mpsc::channel::<Vec<u8>>(4);
+        let lookup = empty_lookup();
+        let mut pkt = ipv6_packet_to(&peer);
+
+        assert!(handle_tun_packet(
+            &mut pkt,
+            1360,
+            "test0",
+            our_addr,
+            &tun_tx,
+            &outbound_tx,
+            &lookup,
+        ));
+
+        // A non-self fips destination is routed into the mesh, not looped back.
+        assert!(
+            outbound_rx.try_recv().is_ok(),
+            "non-self fips destination should be sent to the mesh"
+        );
+        assert!(
+            tun_rx.try_recv().is_err(),
+            "non-self fips destination must not be hairpinned"
+        );
+    }
+
    // ========================================================================
    // macOS utun packet-info header (AF_INET6 4-byte big-endian prefix)
    //
Author	SHA1	Message	Date
Johnathan Corgan	d5ee526f0e	Release v0.4.0: bump version and finalize CHANGELOG date Bump the crate version from 0.4.0-dev to 0.4.0 and stamp the 0.4.0 CHANGELOG heading with the release date.	2026-06-27 15:57:58 +00:00
ArjenandJohnathan Corgan	22a5b3e5c6	packaging(openwrt): default .apk WAN port to DSA name 'wan' The shared fips.yaml ships ethernet.wan.interface: "eth0", the default WAN port on OpenWrt 24 and earlier. OpenWrt 25 (DSA) boards, which the .apk package targets, name the WAN port "wan" instead. Rewrite the staged copy at build time so the as-installed config binds the Ethernet transport to the right port out of the box, without maintaining a second copy of the config file. The .ipk package keeps "eth0". Update the openwrt README to document eth0 (24) vs wan (25/DSA) and add a CHANGELOG entry.	2026-06-26 03:31:17 +00:00
Johnathan Corgan	3ea7ca1fd1	ci(openwrt): retry Blossom upload and skip nostr event on failure A transient timeout uploading the built .ipk to the Blossom CDN (blossom.primal.net) failed the entire OpenWrt Package run, and because the GitHub release job depends on the build jobs, a CDN blip would block every OpenWrt artifact from the release. Blossom/nostr distribution is supplementary; the package already ships as a GitHub release artifact. Wrap the upload in a 3-attempt retry with backoff to absorb transient timeouts, mark the step continue-on-error so a persistent outage no longer fails the build, and guard the NIP-94 publish on the upload succeeding so no event is created with an empty URL. Applied to both the .ipk and .apk build jobs. Claude-Session: https://claude.ai/code/session_01A2pYfSypNmmG4HyHwZuLex	2026-06-21 14:40:50 +00:00
Johnathan Corgan	262d98a8eb	Finalize v0.4.0 release content: CHANGELOG, release notes, README Prepare the source tree for the v0.4.0 release cut, leaving the version at 0.4.0-dev (the version bump rides a separate release-candidate commit). - CHANGELOG: backfill the missing entry for the route-class transit counters and fipstop routing-tab reorg, then reorganize the Unreleased block from a flat per-commit list into topic-grouped subsections mirroring the 0.3.0 entry (coalescing interim fixes into net-effect descriptions without dropping technical detail), and stamp it as [0.4.0] - 2026-06-21 with a fresh empty Unreleased block. The date is provisional and reconfirmed at the final tag. - Release notes: refresh both RELEASE-NOTES.md and the versioned archive (kept byte-identical) to cover the OpenWrt .apk packaging, the Nix flake, the macOS self-traffic checksum fix (#117), and the route-class transit counters. - README: bump the status badge to v0.4.0 so it matches the prose. Claude-Session: https://claude.ai/code/session_01A2pYfSypNmmG4HyHwZuLex	2026-06-21 13:45:19 +00:00
Johnathan Corgan	274b09d4ff	node: classify transit forwards by route class; regroup fipstop routing tab Add six forwarding counters that partition transit-forwarded packets by their tree relationship to the chosen next hop: tree-up (peer is our ancestor), tree-down (peer is our descendant and the destination is within its subtree), tree-down-cross (peer is our descendant but the destination is outside its subtree), cross-link descend (lateral peer, destination within its subtree), cross-link ascend (lateral peer, destination outside its subtree), and direct-peer. The six classes sum to forwarded_packets, asserted by a unit test. Classification is computed from tree coordinates at the transit chokepoint, so the error-signal routing callers are excluded. The two "outside the chosen peer's subtree" classes are both up-and-over forwards but differ in what they depend on. Tree-down-cross is the dive-to-tree-child cut-through: we forward down to our own child for a destination not beneath it, which is only possible because the child advertised cross-link reach upward to us, beyond its own subtree. Its count measures how much forwarding depends on that upward advertisement, i.e. what would change if cross-link advertisements were narrowed to subtree-entry only. Cross-link ascend, by contrast, uses the node's own lateral cross-link learned from a peer's split-horizon advertisement, so it does not depend on any upward advertisement. Surface the counters through the forwarding stats snapshot (control socket, show_routing and show_status) and reorganize the fipstop routing tab so its two columns separate own/endpoint traffic (received, delivered, originated) from forwarded/transit traffic (the route-class breakdown and drop reasons), with the tree-down-cross line visually flagged.	2026-06-20 14:56:54 +00:00
ArjenandJohnathan Corgan	0f1fd18c25	packaging(openwrt): SDK-free .apk build for OpenWrt 25+ and control-socket fix Add OpenWrt .apk packaging for OpenWrt 25+, where apk-tools is the mandatory package manager. The existing .ipk continues to cover OpenWrt 24.x and earlier. Built SDK-free like the .ipk: it reuses the cargo-zigbuild cross-compile and the shared installed-filesystem payload under openwrt-ipk/files, and assembles the ADB container with the official `apk mkpkg` applet from apk-tools 3.0.5 built from source, so no OpenWrt SDK image is needed. The package-openwrt workflow is refactored so a single compile-binaries job cross-compiles and strips each arch once; both the .ipk and .apk packagers consume the binaries via a new --bin-dir flag instead of each recompiling. A build-apk job (aarch64, x86_64) builds apk-tools, packages, and structurally verifies the .apk with `apk adbdump`. Releases now publish .apk artifacts and checksums alongside .ipk; the release download is scoped to fips_* so the shared raw-binary artifacts are not swept into the published release. apk-version.sh maps a release tag or commit height to an apk-tools-valid version, covered by a case-table test. Packages are unsigned, installed with `apk add --allow-untrusted`, matching the .ipk posture. Also fix the OpenWrt control socket: the init script now pre-creates /run/fips before starting the daemon, the procd equivalent of the systemd unit's RuntimeDirectory=fips. Without it, on a fresh boot the daemon resolves its control socket to /tmp (since /run/fips does not yet exist), while fips-gateway later creates /run/fips for its own gateway.sock, leaving fipsctl/fipstop resolving a /run/fips/control.sock the daemon never bound.	2026-06-20 14:44:05 +00:00
ArjenandGitHub	225fab29ab	fix(tun): complete L4 checksum on hairpinned self-traffic (macOS) (#117 ) Self-addressed TCP/UDP connections to a node's own <npub>.fips address half-opened and hung on macOS. macOS routes self-traffic as loopback (a LOCAL route via lo0), which defers the transport TX checksum, but the point-to-point utun then egresses the packet into the daemon with only the pseudo-header partial checksum present. The hairpin path added in `9a9e90a` re-injected these verbatim, so the local stack dropped every segment whose checksum MSS clamping didn't happen to rewrite: the SYN/SYN-ACK got through (clamping recomputes them) but the bare ACK, data, and FIN were dropped for a bad checksum, leaving the listener stuck in SYN_RCVD. Recompute the TCP/UDP checksum for self-addressed packets on the hairpin path before re-injection, completing the self-delivery `9a9e90a` started (which only covered ICMP and the TCP handshake). Linux is unaffected: it loops self-traffic via lo before the TUN, so the hairpin branch never fires and checksums are already valid. Confirmed on macOS: a self-connect that previously timed out now completes in ~9ms with payload delivered.	2026-06-18 08:36:57 -07:00
ArjenandJohnathan Corgan	effd69bd53	ci(openwrt): bump Node 20 actions to Node 24 majors checkout v4->v6, cache v4->v5, upload-artifact v4->v7, download-artifact v4->v8 to clear the Node 20 runner deprecation.	2026-06-17 17:58:37 +00:00
Johnathan Corgan	3749853716	packaging(openwrt): publish checksums-openwrt.txt alongside .ipk artifacts The linux/macos/windows package workflows each publish a checksums-<platform>.txt sha256 file with their release artifacts, but the OpenWrt workflow attached only the .ipk files with no checksum coverage. Generate checksums-openwrt.txt over the .ipk outputs using the same sha256sum idiom as the other platforms and add it to the release file set.	2026-06-17 17:58:37 +00:00
ArjenandJohnathan Corgan	289e5f8571	ci: bump Node 20 actions to Node 24 majors Clear the GitHub Node 20 runner deprecation across CI, AUR, and the Linux/macOS/Windows packaging workflows: actions/checkout v4 -> v6 actions/cache v4 -> v5 actions/upload-artifact v4 -> v7 actions/download-artifact v4 -> v8 package-openwrt.yml is handled separately on fix/openwrt-checksums.	2026-06-17 17:58:37 +00:00
sandwichandJohnathan Corgan	3733349d33	packaging(nix): add a Nix flake for reproducible from-source builds Add a flake that builds all four binaries (fips, fipsctl, fips-gateway, fipstop) on Linux and macOS, pinning the exact toolchain from rust-toolchain.toml (1.94.1 + rustfmt/clippy) via fenix so Nix builds match CI and the AUR/Debian packaging. Wire up the build-time native deps the source tree needs: pkg-config and bindgenHook (libclang) for the rustables/libdbus-sys bindgen step, and dbus for bluer's BLE support. autoPatchelfHook rewrites the binary RPATHs so the daemon resolves libdbus-1.so.3 and libgcc_s.so.1 from the Nix store at runtime — without it `fips` fails to load on NixOS, which has no global /usr/lib. Outputs: packages.{default,fips}, apps for each binary, checks.fips, and a devShell with the pinned toolchain plus cargo-edit. Tests are skipped in the package build since they exercise TUN devices, raw sockets, and mDNS that aren't available in the sandbox, mirroring the AUR/Debian packaging. Verified end-to-end in a pure Nix store (nixos/nix container): nix build, nix flake check, and running all four binaries succeed against the committed flake.lock. Documented across the install and developer docs: a Nix / NixOS section in packaging/README.md, the from-source guide in docs/getting-started.md (noting the flake produces binaries only, with NixOS system integration through the system configuration rather than the installer), the CHANGELOG, README, CONTRIBUTING, and the v0.4.0 release notes. Co-authored-by: Johnathan Corgan <johnathan@corganlabs.com>	2026-06-17 16:36:38 +00:00
ArjenandJohnathan Corgan	9a9e90a32c	fix(tun): loop back self-addressed packets for local delivery A packet destined for our own mesh address reached the TUN reader on macOS (utun egresses self-traffic into the daemon despite the lo0 host route) and was pushed onto the mesh outbound path, where it was dropped for lack of a session/route to self. Hairpin self-addressed packets back to the TUN writer instead, so ping6 and connections to our own <npub>.fips address are delivered locally. On Linux the kernel already loops self-traffic via `lo` before it reaches the TUN, so the branch never fires there; the check is kept unconditional as a daemon-level delivery invariant and to keep it covered by Linux CI.	2026-06-17 14:32:17 +00:00