Dispatch SMTP Relay — full implementation (relay engine, SQL config, dashboard, security, installers)

.dockerignore

@@ -0,0 +1,17 @@
+# Keep the build context small + avoid copying host build output into the image.
+**/bin
+**/obj
+**/node_modules
+**/dist
+src/Dispatch.Web/wwwroot
+.git
+.github
+installer
+docs
+publish
+staging
+TestResults
+**/*.user
+.vs
+.vscode
+*.md

.github/dependabot.yml

@@ -0,0 +1,30 @@
+version: 2
+updates:
+  # Keep GitHub Actions current. Third-party actions are pinned to commit SHAs (supply-chain hardening);
+  # Dependabot bumps those SHAs (and the trailing version comment) when new releases ship, so pinning
+  # doesn't mean going stale. Grouped into one PR to keep the noise down.
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ["*"]
+
+  # Frontend dependencies (npm) for the dashboard.
+  - package-ecosystem: npm
+    directory: "/src/Dispatch.UI"
+    schedule:
+      interval: weekly
+    groups:
+      ui:
+        patterns: ["*"]
+
+  # .NET NuGet dependencies.
+  - package-ecosystem: nuget
+    directory: "/"
+    schedule:
+      interval: weekly
+    groups:
+      nuget:
+        patterns: ["*"]

.github/workflows/appliance.yml

@@ -0,0 +1,180 @@
+name: Appliance
+
+# Builds the downloadable virtual appliances for ALL hypervisors in one job: customizes the Ubuntu 24.04
+# cloud image with libguestfs (no Hyper-V host / nested virt needed) into a Gen2/UEFI image with SQL Server
+# Express + Dispatch baked in, emits it as VHDX (Hyper-V), OVA (VMware), and qcow2 (KVM/Proxmox), then boots
+# it under QEMU/UEFI to prove the service comes up on first boot. Artifacts: dispatch-appliance-hyperv,
+# dispatch-appliance-vmware, dispatch-appliance-kvm.
+on:
+  # Dispatch-only: the Build workflow kicks this off automatically AFTER its tests + lint pass (see the
+  # trigger-appliance job in build.yml), so the appliance is never built from un-validated code and never
+  # races Build. Also runnable by hand from the Actions tab.
+  workflow_dispatch:
+
+env:
+  DOTNET_NOLOGO: "true"
+  DOTNET_CLI_TELEMETRY_OPTOUT: "true"
+
+jobs:
+  # ONE job builds all three appliance formats (Hyper-V VHDX, VMware OVA, KVM/Proxmox qcow2) from a
+  # single image, then uploads them as three separate downloads near the end. The name reflects that
+  # it is not Hyper-V-only.
+  build-appliances:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-dotnet@v5
+        with:
+          dotnet-version: "10.0.x"
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: "24"
+          cache: npm
+          cache-dependency-path: src/Dispatch.UI/package-lock.json
+
+      - name: Build + embed the web UI
+        run: |
+          ( cd src/Dispatch.UI && npm ci && npm run build )
+          rm -rf src/Dispatch.Web/wwwroot && mkdir -p src/Dispatch.Web/wwwroot
+          cp -r src/Dispatch.UI/dist/* src/Dispatch.Web/wwwroot/
+          test -f src/Dispatch.Web/wwwroot/index.html || { echo "embedded UI missing index.html"; exit 1; }
+
+      - name: Publish self-contained (linux-x64)
+        run: dotnet publish src/Dispatch.Service -c Release -r linux-x64 --self-contained true -o publish/linux
+
+      - name: Install image-build tooling
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libguestfs-tools qemu-utils
+          # libguestfs's appliance must be able to read the host kernel image.
+          sudo chmod 0644 /boot/vmlinuz-* || true
+
+      - name: Build the appliance VHDX
+        env:
+          VERSION: ${{ github.ref_type == 'tag' && github.ref_name || format('ci-{0}', github.run_number) }}
+        run: |
+          sudo env PREBUILT_DIR="$PWD/publish/linux" VERSION="$VERSION" \
+            OUT="$PWD/dispatch-appliance.vhdx" OVA_OUT="$PWD/dispatch-appliance.ova" \
+            QCOW2_OUT="$PWD/dispatch-appliance.qcow2" \
+            LIBGUESTFS_BACKEND=direct ./appliance/build-appliance.sh
+          sudo chown "$USER" dispatch-appliance.vhdx dispatch-appliance.ova dispatch-appliance.qcow2
+
+      - name: Validate the OVA (structure, OVF XML, manifest checksums)
+        run: |
+          echo "=== tar contents (must be ovf, then mf, then vmdk) ==="
+          tar -tf dispatch-appliance.ova
+          first=$(tar -tf dispatch-appliance.ova | head -1)
+          case "$first" in *.ovf) ;; *) echo "ERROR: first OVA entry must be the .ovf, got $first"; exit 1;; esac
+          mkdir -p ova-check && tar -xf dispatch-appliance.ova -C ova-check
+          python3 -c "import xml.dom.minidom,glob,sys; xml.dom.minidom.parse(glob.glob('ova-check/*.ovf')[0]); print('OVF XML parses')"
+          ( cd ova-check && while read -r line; do
+              f=$(echo "$line" | sed -n 's/^SHA256(\(.*\))=.*/\1/p'); h=$(echo "$line" | sed -n 's/.*= *//p')
+              [ -n "$f" ] || continue
+              act=$(sha256sum "$f" | cut -d' ' -f1)
+              [ "$act" = "$h" ] && echo "ok: $f" || { echo "ERROR: checksum mismatch for $f"; exit 1; }
+            done < ./*.mf )
+          echo "OVA structure + checksums valid"
+
+      # One self-contained download per hypervisor: each artifact downloads as a single zip (GitHub wraps
+      # it) holding that format's image + its README + helper - so the user unzips ONCE, no nested zip.
+      - name: Stage per-type downloads + checksums
+        run: |
+          mkdir -p out/hyperv out/vmware out/kvm
+          # Hyper-V: raw VHDX (GitHub compresses the artifact) + import helper + instructions.
+          mv dispatch-appliance.vhdx out/hyperv/
+          cp appliance/Import-DispatchAppliance.ps1 out/hyperv/
+          cp appliance/hyperv-README.txt out/hyperv/README.txt
+          ( cd out/hyperv && sha256sum dispatch-appliance.vhdx > dispatch-appliance.vhdx.sha256 )
+          # VMware: the OVA + instructions.
+          mv dispatch-appliance.ova out/vmware/
+          cp appliance/vmware-README.txt out/vmware/README.txt
+          ( cd out/vmware && sha256sum dispatch-appliance.ova > dispatch-appliance.ova.sha256 )
+          # KVM / Proxmox: qcow2 + import helpers + instructions.
+          mv dispatch-appliance.qcow2 out/kvm/
+          cp appliance/import-libvirt.sh appliance/import-proxmox.sh out/kvm/
+          cp appliance/kvm-README.txt out/kvm/README.txt
+          ( cd out/kvm && sha256sum dispatch-appliance.qcow2 > dispatch-appliance.qcow2.sha256 )
+
+      # Upload before the boot smoke so the artifacts are available even if the smoke fails.
+      - name: Upload Hyper-V appliance
+        uses: actions/upload-artifact@v6
+        with: { name: dispatch-appliance-hyperv, path: out/hyperv/*, if-no-files-found: error }
+      - name: Upload VMware appliance
+        uses: actions/upload-artifact@v6
+        with: { name: dispatch-appliance-vmware, path: out/vmware/*, if-no-files-found: error }
+      - name: Upload KVM/Proxmox appliance
+        uses: actions/upload-artifact@v6
+        with: { name: dispatch-appliance-kvm, path: out/kvm/*, if-no-files-found: error }
+
+      - name: Boot smoke (UEFI) - service comes up on first boot
+        run: |
+          sudo apt-get install -y qemu-system-x86 ovmf imagemagick
+          code=$(ls /usr/share/OVMF/OVMF_CODE*.fd | head -1)
+          varsrc=$(ls /usr/share/OVMF/OVMF_VARS*.fd | head -1)
+          cp "$varsrc" vars.fd
+          echo "OVMF: $code / $varsrc"
+          # -cpu host requires KVM; under the TCG fallback use a TCG-compatible CPU model.
+          if [ -e /dev/kvm ]; then echo "KVM available"; ACCEL="-enable-kvm -cpu host"; else echo "KVM NOT available - TCG (slow)"; ACCEL="-accel tcg -cpu max"; fi
+          # Boot the image as qcow2 (rules out QEMU's vhdx driver - Hyper-V reads the vhdx itself) and attach
+          # it as an explicit virtio-blk device with bootindex=0, so OVMF (empty NVRAM) actually boots it.
+          # -vga std + a QMP socket let us screenshot the VGA console (firmware/GRUB output goes there, not serial).
+          qemu-img convert -O qcow2 out/hyperv/dispatch-appliance.vhdx boot.qcow2
+          # shellcheck disable=SC2086
+          sudo qemu-system-x86_64 -machine q35 $ACCEL -m 4096 -smp 2 -no-reboot \
+            -drive if=pflash,format=raw,readonly=on,file="$code" \
+            -drive if=pflash,format=raw,file=vars.fd \
+            -drive file=boot.qcow2,format=qcow2,if=none,id=hd0 \
+            -device virtio-blk-pci,drive=hd0,bootindex=0 \
+            -netdev user,id=n0,hostfwd=tcp::8420-:8420,hostfwd=tcp::2526-:25 -device virtio-net-pci,netdev=n0 \
+            -vga std -display none -serial file:console.log -qmp unix:qmp.sock,server,nowait -daemonize 2>qemu.err \
+            || { echo "=== qemu failed to launch ==="; cat qemu.err; exit 1; }
+          screenshot() {  # capture the VGA framebuffer via QMP -> $1 (png)
+            sudo python3 appliance/qmp-screendump.py qmp.sock /tmp/screen.ppm || true
+            sudo convert /tmp/screen.ppm "$1" 2>/dev/null && echo "captured $1" || echo "no screenshot"
+          }
+          ok=0
+          for i in $(seq 1 90); do          # up to ~8 min (KVM boot is fast; this is mostly SQL first-run)
+            if curl -fsSk -m 3 https://localhost:8420/health >/dev/null 2>&1; then ok=1; break; fi
+            [ "$i" = 18 ] && screenshot boot-90s.png   # ~90s in: capture whatever's on screen
+            sleep 5
+          done
+          if [ "$ok" != 1 ]; then
+            screenshot boot-final.png
+            echo "=== qemu.err ==="; cat qemu.err 2>/dev/null || true
+            echo "=== serial console ==="; cat console.log 2>/dev/null || echo "(serial console empty)"
+            echo "=== qemu still running? ==="; pgrep -f qemu-system >/dev/null && echo "(qemu running)" || echo "(qemu not running)"
+            # qemu (sudo) owns these root-only; make them readable so upload-artifact can collect them.
+            sudo chmod -f a+r boot-90s.png boot-final.png console.log qemu.err 2>/dev/null || true
+            echo "appliance did not serve /health within the timeout"; exit 1
+          fi
+          echo "appliance /health OK"
+
+          # Prove the appliance bound the privileged SMTP port (25, via CAP_NET_BIND_SERVICE on the systemd
+          # unit) and that STARTTLS negotiates with the self-signed fallback cert. Guest 25 is forwarded to
+          # host 2526; openssl completes a real TLS handshake (BEGIN CERTIFICATE) on success.
+          tls_ok=0
+          for _ in $(seq 1 12); do
+            if echo QUIT | openssl s_client -starttls smtp -connect localhost:2526 -crlf 2>/dev/null | grep -q 'BEGIN CERTIFICATE'; then
+              tls_ok=1; break
+            fi
+            sleep 5
+          done
+          if [ "$tls_ok" != 1 ]; then
+            echo "=== serial console ==="; sudo chmod -f a+r console.log 2>/dev/null || true; cat console.log 2>/dev/null || true
+            echo "appliance SMTP STARTTLS check failed on port 25 (forwarded to 2526)"; exit 1
+          fi
+          echo "appliance SMTP STARTTLS on port 25 OK"
+
+      - name: Upload boot diagnostics
+        if: failure()
+        uses: actions/upload-artifact@v6
+        with:
+          name: appliance-boot-diagnostics
+          path: |
+            boot-90s.png
+            boot-final.png
+            console.log
+            qemu.err
+          if-no-files-found: warn

.github/workflows/build.yml

@@ -0,0 +1,117 @@
+name: Build
+
+on:
+  push:
+  pull_request:
+
+env:
+  # The actions/* @v4 run on Node 20 (deprecated); opt them into Node 24 now (forced default 2026-06-16).
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
+jobs:
+  build-test:
+    runs-on: ubuntu-latest
+
+    services:
+      # SQL Server 2022 service container (GitHub-hosted runners are free for this public repo). Same wire
+      # protocol / T-SQL as the dev Azure SQL Edge container; app code is unchanged. The Data test fixture
+      # waits up to 90s for the engine to accept connections, so no container health-cmd is needed.
+      sql:
+        image: mcr.microsoft.com/mssql/server:2022-latest
+        env:
+          ACCEPT_EULA: "Y"
+          # Dev-only SA password. Override by setting the MSSQL_SA_PASSWORD repo/org secret; the literal is
+          # only a fallback and grants nothing beyond the ephemeral CI container.
+          MSSQL_SA_PASSWORD: ${{ secrets.MSSQL_SA_PASSWORD || 'Dispatch_Dev_Pass123' }}
+        ports:
+          - 1433:1433
+
+    env:
+      # Drives the Dispatch.Data integration tests against the SQL service container.
+      DISPATCH_TEST_SQL: "Server=localhost,1433;User Id=sa;Password=${{ secrets.MSSQL_SA_PASSWORD || 'Dispatch_Dev_Pass123' }};TrustServerCertificate=True;Encrypt=True"
+      # Make the integration tests fail loudly if the connection string is ever missing, instead of skipping.
+      DISPATCH_REQUIRE_SQL: "1"
+      DOTNET_NOLOGO: "true"
+      DOTNET_CLI_TELEMETRY_OPTOUT: "true"
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Setup .NET 10
+        uses: actions/setup-dotnet@v5
+        with:
+          dotnet-version: "10.0.x"
+
+      - name: Setup Node
+        uses: actions/setup-node@v5
+        with:
+          node-version: "24"
+          cache: npm
+          cache-dependency-path: src/Dispatch.UI/package-lock.json
+
+      - name: Build React UI
+        working-directory: src/Dispatch.UI
+        run: |
+          npm ci
+          npm run build
+
+      - name: Embed UI into Dispatch.Web
+        run: |
+          rm -rf src/Dispatch.Web/wwwroot
+          mkdir -p src/Dispatch.Web/wwwroot
+          cp -r src/Dispatch.UI/dist/* src/Dispatch.Web/wwwroot/
+          # Fail fast if the embed produced nothing (stale/empty dist would otherwise ship a blank dashboard).
+          test -s src/Dispatch.Web/wwwroot/index.html || { echo "::error::Embedded UI is missing index.html"; exit 1; }
+
+      - name: Restore
+        run: dotnet restore Dispatch.slnx
+
+      - name: Build
+        run: dotnet build Dispatch.slnx --configuration Release --no-restore
+
+      - name: Test
+        run: dotnet test Dispatch.slnx --configuration Release --no-build --verbosity normal --logger "trx;LogFileName=test-results.trx" --results-directory TestResults
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v6
+        with:
+          name: test-results
+          path: TestResults/**/*.trx
+          if-no-files-found: ignore
+
+  # Keep em dashes out of the tree: they break Windows PowerShell parsing (a mis-decoded em-dash byte
+  # becomes a smart-quote string delimiter) and the project standardizes on ASCII '-'.
+  no-em-dash:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: Reject em dashes (use ASCII '-')
+        run: |
+          matches=$(grep -rlIP '\x{2014}' . --exclude-dir=.git --exclude-dir=node_modules || true)
+          if [ -n "$matches" ]; then
+            echo "::error::Em dash (U+2014) found - replace with an ASCII hyphen '-'. Files:"
+            echo "$matches"
+            exit 1
+          fi
+          echo "OK: no em dashes."
+
+  # After a green Build on a working branch, rebuild the appliance from THIS validated commit so the image
+  # always has the latest tested code and never races Build. workflow_run can't be used (it only fires from
+  # the default branch), so we dispatch the Appliance workflow with GITHUB_TOKEN (workflow_dispatch is an
+  # allowed GITHUB_TOKEN trigger). `needs: build-test` gates it on success.
+  trigger-appliance:
+    needs: [build-test, no-em-dash]
+    if: ${{ github.event_name == 'push' && (github.ref_name == 'main' || github.ref_name == 'feat/relay-engine-web-providers') }}
+    runs-on: ubuntu-latest
+    permissions:
+      actions: write
+    steps:
+      - uses: actions/checkout@v5
+      - name: Build the appliance from this validated commit
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh workflow run appliance.yml --ref "${{ github.ref_name }}"
+
+  # NOTE: tagged releases (refs/tags/v*) are handled by release.yml, which builds the signed Windows
+  # installer + Linux tarball and publishes a GitHub Release. This workflow only runs build + tests.

.github/workflows/docker.yml

@@ -0,0 +1,47 @@
+name: Docker
+
+# Builds the container image and runs the full stack (Dispatch + SQL via docker-compose), failing unless
+# the service comes up and serves /health - the container equivalent of the installer smoke tests. Docker is
+# native on the runner, so this needs no QEMU/nested virtualization. The release workflow builds+pushes the
+# multi-arch image; this proves it actually runs before that.
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - "Dockerfile"
+      - "docker-compose.yml"
+      - "src/Dispatch.Service/**"
+      - "src/Dispatch.Web/**"
+      - "src/Dispatch.Core/**"
+      - "src/Dispatch.Data/**"
+      - "src/Dispatch.Providers/**"
+      - "src/Dispatch.UI/**"
+      - ".github/workflows/docker.yml"
+
+jobs:
+  build-and-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Build image + start the stack (Dispatch + SQL)
+        run: docker compose up --build -d
+
+      - name: Wait for the dashboard /health
+        run: |
+          ok=0
+          for _ in $(seq 1 60); do          # up to 5 min: image already built; SQL start + DB init + service
+            if curl -fsSk -m 5 https://localhost:8420/health >/dev/null 2>&1; then ok=1; break; fi
+            sleep 5
+          done
+          if [ "$ok" != 1 ]; then
+            echo "=== compose ps ==="; docker compose ps
+            echo "=== dispatch logs ==="; docker compose logs --tail 150 dispatch || true
+            echo "=== sql logs ==="; docker compose logs --tail 40 sql || true
+            echo "dispatch /health did not respond"; exit 1
+          fi
+          echo "Docker stack /health OK"
+
+      - name: Tear down
+        if: always()
+        run: docker compose down -v || true