chore: bump version to 0.10.3

* fix: escape dots and special characters in DNS label text per RFC 1035 §5.1

Closes #36

read_qname was pushing raw label bytes directly into the output string,
producing ambiguous text for labels containing dots, backslashes, or
non-printable bytes. fanf2 spotted this on HN: wire format
`[8]exa.mple[3]com[0]` (two labels, first containing a literal 0x2E)
was rendered as `exa.mple.com`, indistinguishable from three labels.

Fix both sides of the text representation per RFC 1035 §5.1:

read_qname — when rendering wire bytes to text:
- literal `.` within a label → `\.`
- literal `\` → `\\`
- bytes outside 0x21..=0x7E → `\DDD` (3-digit decimal)
- printable ASCII passes through unchanged

write_qname — when parsing text back to wire:
- `\.` produces a literal 0x2E inside the current label (not a separator)
- `\\` produces a literal 0x5C
- `\DDD` produces the byte with that decimal value (0..=255)
- unescaped `.` still separates labels, empty labels still skipped
- rejects trailing `\`, short `\DD`, and `\DDD` > 255

Impact in practice is low — real-world domains don't contain dots in
labels — but it's a correctness bug in the wire format parser that
could cause round-trip failures with adversarial input. The parser is
the core of the project, so correctness bugs take priority over
practical impact.

Adds 16 unit tests in a new `#[cfg(test)] mod tests` block covering:
plain domain read/write, literal-dot escaping on both sides, backslash
escaping, non-printable + space decimal escapes, full round-trip
preservation, and the three rejection cases for malformed escapes.

Credit: fanf2 (https://news.ycombinator.com/item?id=47612321)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor: stream label writes directly into buffer (review feedback)

The first cut of this fix delegated write_qname to a helper
(parse_escaped_labels) that built Vec<Vec<u8>> up-front, then iterated
to emit the wire bytes. On a plain-ASCII domain like "www.google.com"
that's ~4 heap allocations per write_qname call, and record.rs calls
write_qname ~6 times per response — so this PR would regress
bench_buffer_serialize by roughly 24 extra allocations per response
vs. main, where the old non-escaping code had zero.

Rewrite write_qname as a streaming byte-level loop that reserves the
length byte up-front, writes the label body directly into the buffer,
then backpatches the length via set(). Zero intermediate allocations
on the common path, and the 63-byte label cap is now checked
incrementally so oversized labels fail fast.

Byte-level scanning is safe for UTF-8 input: continuation bytes are
always in 0x80..=0xBF, so they can never collide with the ASCII `.`
(0x2E) or `\` (0x5C) that drive label splitting and escape parsing.

Also inline the \DDD rendering in read_qname to avoid the per-byte
format!() allocation on non-printable input. Plain-ASCII reads hit
the unchanged push(c as char) fast path, so the common case has zero
regression.

The parse_escaped_labels helper is deleted — no remaining callers.

All 158 tests pass, clippy + fmt clean. Collapses three review
findings (HIGH allocation regression, MEDIUM format! allocation,
MEDIUM .unwrap() after digit guard) in one pass.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: route dnssec::name_to_wire through write_qname for escape handling

Closes #55.

dnssec::name_to_wire was a parallel implementation of the old
write_qname's splitting loop — it iterated qname.split('.') and pushed
raw bytes. It predated and duplicated the buffer.rs logic, and it did
not understand RFC 1035 §5.1 text escapes. After the read_qname fix in
this PR, names that come out of read_qname can contain \., \\, or
\DDD sequences; feeding those back into the old name_to_wire would
split on the literal '.' inside a \. sequence and produce corrupt
RRSIG signed-data blobs.

The underlying bug predates this PR — the old read_qname was broken
too, so both sides of the DNSSEC canonical form pipeline were
silently wrong in the same way. Making read_qname correct exposed the
divergence, so it's fixed here in the same PR that introduced the
exposure.

Reimplement name_to_wire on top of BytePacketBuffer::write_qname:
reserve a scratch buffer, let write_qname handle the escape parsing
and length-byte framing, copy the emitted bytes into a Vec, then
walk the wire once more to lowercase label bodies (length bytes stay
untouched). Canonical form per RFC 4034 §6.2 requires the
lowercasing, and it has to happen post-escape-resolution — a
decimal escape like \065 produces 0x41 ('A'), which must be
lowercased to 'a' in the final wire bytes.

Call sites in build_signed_data, record_to_canonical_wire,
record_rdata_canonical, and nsec3_hash are unchanged — the public
signature stays the same, infallible Vec<u8> return.

Tests:
- name_to_wire_escaped_dot_in_label_is_not_a_separator — verifies
  the fanf2 example round-trips correctly through canonical form
- name_to_wire_decimal_escape_is_lowercased — verifies post-escape
  lowercasing (the subtle correctness requirement)
- existing name_to_wire_root, name_to_wire_domain, ds_verification
  tests still pass unchanged

Test count: 158 → 160.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor: tighten name_to_wire per review feedback

- Replace hand-rolled per-byte lowercase loop with stdlib
  [u8]::make_ascii_lowercase(). Shorter and idiomatic.
- Tighten the .expect() message to state the actual invariant
  (parseable DNS name) instead of vague "well-formed" language.
- Replace the doc comment's "see #55" with the real invariant —
  issue numbers rot, and by merge time #55 is closed anyway. The
  comment now explains WHY the lowercase pass has to happen
  post-escape-resolution (\065 → 'A' → 'a') instead of during
  write_qname.
- Drop the redundant `\065` test comment (the one-liner version
  is enough with the assertion showing the transform).

No behavior change; 160 tests still pass, clippy + fmt clean.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* test: cover label cap and empty-label rollback; trim doc comments

Closes coverage gaps left by PR #54:

- write_rejects_label_over_63_bytes: pins the incremental 63-byte cap
  inside write_qname's inner loop (boundary at 63 vs 64).
- write_skips_empty_labels: pins the rollback branch (pos = len_pos)
  triggered by leading or consecutive dots.

Doc comments tightened:

- write_qname: drop the streaming-impl walkthrough and the escape-grammar
  restatement (already documented on read_qname).
- name_to_wire: drop the implementation explanation; keep the
  post-escape lowercasing rationale, which pins behavior a future
  refactor could silently break.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.SRCINFO

@@ -0,0 +1,19 @@
+pkgbase = numa-git
+	pkgdesc = Portable DNS resolver in Rust — .numa local domains, ad blocking, developer overrides, DNS-over-HTTPS
+	pkgver = 0.10.1.r0.g0000000
+	pkgrel = 1
+	url = https://github.com/razvandimescu/numa
+	arch = x86_64
+	license = MIT
+	options = !lto
+	makedepends = cargo
+	makedepends = git
+	depends = gcc-libs
+	depends = glibc
+	provides = numa
+	conflicts = numa
+	backup = etc/numa.toml
+	source = numa::git+https://github.com/razvandimescu/numa.git
+	sha256sums = SKIP
+
+pkgname = numa-git

.github/dependabot.yml

@@ -0,0 +1,34 @@
+version: 2
+updates:
+  - package-ecosystem: "cargo"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    commit-message:
+      prefix: "chore(deps)"
+    groups:
+      minor-and-patch:
+        patterns: ["*"]
+        update-types: ["minor", "patch"]
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    commit-message:
+      prefix: "chore(deps)"
+    groups:
+      minor-and-patch:
+        patterns: ["*"]
+        update-types: ["minor", "patch"]
+
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    commit-message:
+      prefix: "chore(deps)"
+    groups:
+      minor-and-patch:
+        patterns: ["*"]
+        update-types: ["minor", "patch"]

.github/workflows/ci.yml

@@ -13,7 +13,7 @@ jobs:
   check:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: dtolnay/rust-toolchain@stable
         with:
           components: rustfmt, clippy
@@ -30,7 +30,7 @@ jobs:
   check-macos:
     runs-on: macos-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: dtolnay/rust-toolchain@stable
       - uses: Swatinem/rust-cache@v2
       - name: clippy
@@ -41,7 +41,7 @@ jobs:
   check-windows:
     runs-on: windows-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: dtolnay/rust-toolchain@stable
       - uses: Swatinem/rust-cache@v2
       - name: build
@@ -51,7 +51,7 @@ jobs:
       - name: test
         run: cargo test
       - name: Upload binary
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: numa-windows-x86_64
           path: target/debug/numa.exe

.github/workflows/homebrew-bump.yml

@@ -0,0 +1,77 @@
+name: Bump Homebrew Tap
+
+on:
+  workflow_call:
+    inputs:
+      version:
+        description: 'Version to bump (e.g. 0.10.0 or v0.10.0)'
+        type: string
+        required: true
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to bump (e.g. 0.10.0 or v0.10.0)'
+        required: true
+
+permissions:
+  contents: read
+
+jobs:
+  bump:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Determine version
+        id: ver
+        env:
+          INPUT_VERSION: ${{ inputs.version }}
+        run: |
+          V="${INPUT_VERSION#v}"
+          echo "version=$V" >> "$GITHUB_OUTPUT"
+
+      - name: Fetch sha256 checksums from release assets
+        id: shas
+        env:
+          V: ${{ steps.ver.outputs.version }}
+        run: |
+          set -euo pipefail
+          base="https://github.com/razvandimescu/numa/releases/download/v${V}"
+          for t in macos-aarch64 macos-x86_64 linux-aarch64 linux-x86_64; do
+            sha=$(curl -fsSL "${base}/numa-${t}.tar.gz.sha256" | awk '{print $1}')
+            if [ -z "$sha" ]; then
+              echo "ERROR: failed to fetch sha256 for $t" >&2
+              exit 1
+            fi
+            key=$(echo "$t" | tr '[:lower:]-' '[:upper:]_')
+            echo "SHA_${key}=${sha}" >> "$GITHUB_ENV"
+          done
+
+      - name: Clone homebrew-tap
+        env:
+          HOMEBREW_TAP_GITHUB_TOKEN: ${{ secrets.HOMEBREW_TAP_GITHUB_TOKEN }}
+        run: |
+          git clone "https://x-access-token:${HOMEBREW_TAP_GITHUB_TOKEN}@github.com/razvandimescu/homebrew-tap.git" tap
+
+      - name: Update formula
+        env:
+          VERSION: ${{ steps.ver.outputs.version }}
+        run: |
+          python3 scripts/update-homebrew-formula.py tap/numa.rb
+          echo "--- updated numa.rb ---"
+          cat tap/numa.rb
+
+      - name: Commit and push
+        working-directory: tap
+        env:
+          V: ${{ steps.ver.outputs.version }}
+        run: |
+          if git diff --quiet; then
+            echo "numa.rb already at v${V}, nothing to commit"
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add numa.rb
+          git commit -m "chore: bump numa to v${V}"
+          git push origin main

.github/workflows/publish-aur.yml

@@ -0,0 +1,159 @@
+# `publish-aur.yml` - Arch Linux AUR Package Workflow
+# --------------------
+# This workflow automates the validation and publishing of the 'numa-git' package to the
+# Arch User Repository (AUR). The AUR is a community-driven repository for Arch Linux users.
+#
+# Workflow Overview:
+# 1. Validate: Builds and tests the package for Arch Linux x86_64 using a clean
+#    Arch Linux container.
+# 2. Audit: Checks Rust dependencies for known security vulnerabilities using
+#    'cargo-audit'.
+# 3. Publish: If on the 'main' branch, it pushes the updated PKGBUILD and
+#    .SRCINFO to the AUR.
+#
+# Security Best Practices:
+# - SHA Pinning: All GitHub Actions are pinned to a full-length commit SHA (e.g., v6.0.2 @ SHA)
+#   to ensure the code is immutable and protects against supply-chain attacks where a tag
+#   might be maliciously moved to a compromised commit.
+# - SSH Hygiene: Uses ssh-agent to keep the private key in memory rather than on disk.
+# - Audit: Runs 'cargo audit' to prevent publishing known vulnerable dependencies.
+
+name: Publish - Arch Linux AUR Package
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  # The 'validate' job ensures that the PKGBUILD is correct and the software builds/tests
+  # successfully on Arch Linux before we attempt to publish it.
+  validate:
+    name: Validate PKGBUILD (${{ matrix.arch }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        arch: [x86_64]
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Build and Test Package
+        timeout-minutes: 60
+        env:
+          AUR_PKGNAME: ${{ secrets.AUR_PACKAGE_NAME }}
+        run: |
+          # We use a temporary directory to avoid Docker permission issues with the workspace.
+          mkdir -p build-dir
+          cp PKGBUILD build-dir/
+
+          docker run --rm -v $PWD/build-dir:/pkg -w /pkg archlinux:latest /bin/bash -c "
+            # ARCH LINUX SECURITY REQUIREMENT:
+            # 'makepkg' (the tool that builds Arch packages) refuses to run as root for safety.
+            # We must create a standard user and give them sudo access.
+
+            # Install build-time dependencies.
+            # 'base-devel' includes essential tools like gcc, make, and binutils.
+            # Install 'rust' directly to avoid the interactive virtual-package
+            # prompt for 'cargo' on current Arch images.
+            pacman -Syu --noconfirm --needed base-devel rust git sudo cargo-audit
+
+            useradd -m builduser
+            chown -R builduser:builduser /pkg
+
+            # Allow the build user to install dependencies during the build process.
+            echo 'builduser ALL=(ALL) NOPASSWD: ALL' > /etc/sudoers.d/builduser
+
+            # Fetch the source tree first so pkgver() and cargo-audit have a
+            # real Cargo.lock to inspect.
+            sudo -u builduser makepkg -o --nobuild --nocheck --nodeps --noprepare
+
+            # SECURITY AUDIT:
+            # Fail early if any dependencies have known security vulnerabilities.
+            sudo -u builduser sh -lc 'cd /pkg/src/numa && cargo audit'
+
+            # BUILD & TEST:
+            # 'makepkg -s' will:
+            # 1. Download source files (cloning this repo)
+            # 2. Run prepare(), build(), and check() (running cargo test)
+            # 3. Create the final .pkg.tar.zst package
+            sudo -u builduser makepkg -s --noconfirm
+          "
+
+  # The 'publish' job updates the AUR repository with our latest PKGBUILD and .SRCINFO.
+  publish:
+    name: Publish to AUR
+    needs: validate
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      # Securely configure SSH for AUR access.
+      - name: Configure SSH
+        run: |
+          mkdir -p ~/.ssh
+          # Official AUR Ed25519 fingerprint (prevents Man-in-the-Middle attacks).
+          echo "aur.archlinux.org ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEuBKrPzbawxA/k2g6NcyV5jmqwJ2s+zpgZGZ7tpLIcN" >> ~/.ssh/known_hosts
+
+          # Use ssh-agent to keep the private key in memory rather than writing it to disk.
+          eval $(ssh-agent -s)
+          echo "${{ secrets.AUR_SSH_PRIVATE_KEY }}" | tr -d '\r' | ssh-add -
+
+          # Export the agent socket so subsequent 'git' commands can use it.
+          echo "SSH_AUTH_SOCK=$SSH_AUTH_SOCK" >> $GITHUB_ENV
+          echo "SSH_AGENT_PID=$SSH_AGENT_PID" >> $GITHUB_ENV
+
+      - name: Push to AUR
+        env:
+          AUR_PKGNAME: ${{ secrets.AUR_PACKAGE_NAME }}
+          AUR_EMAIL: ${{ secrets.AUR_EMAIL }}
+          AUR_USER: ${{ secrets.AUR_USERNAME }}
+        run: |
+          # AUR repos are managed via Git. Each package has its own repo at:
+          # ssh://aur@aur.archlinux.org/<package-name>.git
+          git clone ssh://aur@aur.archlinux.org/$AUR_PKGNAME.git aur-repo
+
+          cp PKGBUILD aur-repo/
+          cd aur-repo
+
+          # METADATA GENERATION:
+          # '.SRCINFO' is a machine-readable version of the PKGBUILD.
+          # We must run this as a non-root user ('builduser') inside the container.
+          docker run --rm -v $(pwd):/pkg archlinux:latest /bin/bash -c "
+            pacman -Syu --noconfirm --needed binutils git sudo
+            useradd -m builduser
+            chown -R builduser:builduser /pkg
+            cd /pkg
+            sudo -u builduser git config --global --add safe.directory '*'
+            # makepkg -od fetches the source first so pkgver() can calculate the version.
+            # --noprepare skips the prepare() function, which invokes cargo and would
+            # otherwise require a full rust toolchain in this metadata-only container.
+            # pkgver() runs before prepare(), so .SRCINFO still gets the correct version.
+            sudo -u builduser makepkg -od --noprepare && sudo -u builduser makepkg --printsrcinfo > .SRCINFO
+          "
+
+          # Reclaim ownership: the in-container 'chown -R builduser:builduser /pkg'
+          # propagates through the bind mount, leaving .git/ owned by the container's
+          # builduser UID. Without this, subsequent 'git config' on the host fails with
+          # "could not lock config file .git/config: Permission denied".
+          sudo chown -R "$(id -u):$(id -g)" .
+
+          # Set the commit identity using secrets for security and auditability.
+          git config user.name "$AUR_USER"
+          git config user.email "$AUR_EMAIL"
+
+          # Stage and commit both the human-readable PKGBUILD and machine-readable .SRCINFO.
+          git add PKGBUILD .SRCINFO
+
+          if ! git diff --cached --quiet; then
+            git commit -m "chore: update PKGBUILD to ${{ github.sha }}"
+            git push origin master
+          else
+            echo "No changes to commit (metadata and PKGBUILD are already up-to-date)."
+          fi

.github/workflows/release.yml

@@ -31,7 +31,7 @@ jobs:
 
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Install Rust
         uses: dtolnay/rust-toolchain@stable
@@ -70,7 +70,7 @@ jobs:
           (Get-FileHash "${{ matrix.name }}.zip" -Algorithm SHA256).Hash.ToLower() + "  ${{ matrix.name }}.zip" | Out-File "${{ matrix.name }}.zip.sha256" -Encoding ascii
 
       - name: Upload artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: ${{ matrix.name }}
           path: |
@@ -82,7 +82,7 @@ jobs:
   publish:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Install Rust
         uses: dtolnay/rust-toolchain@stable
@@ -96,7 +96,7 @@ jobs:
     needs: [build, publish]
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v8
         with:
           merge-multiple: true
 
@@ -108,3 +108,10 @@ jobs:
             *.tar.gz
             *.zip
             *.sha256
+
+  bump-homebrew:
+    needs: release
+    uses: ./.github/workflows/homebrew-bump.yml
+    with:
+      version: ${{ github.ref_name }}
+    secrets: inherit

.github/workflows/static.yml

@@ -30,18 +30,18 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
       - name: Install pandoc
         run: sudo apt-get install -y pandoc
       - name: Generate blog HTML
         run: make blog
       - name: Setup Pages
-        uses: actions/configure-pages@v5
+        uses: actions/configure-pages@v6
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v4
         with:
           # Upload entire repository
           path: './site'
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5

.gitignore

@@ -1,4 +1,5 @@
 /target
+/build-dir
 CLAUDE.md
 docs/
 site/blog/posts/

Cargo.lock

@@ -17,6 +17,15 @@ dependencies = [
  "memchr",
 ]
 
+[[package]]
+name = "alloca"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e5a7d05ea6aea7e9e64d25b9156ba2fee3fdd659e34e41063cd2fc7cd020d7f4"
+dependencies = [
+ "cc",
+]
+
 [[package]]
 name = "anes"
 version = "0.1.6"
@@ -75,18 +84,18 @@ dependencies = [
 
 [[package]]
 name = "arc-swap"
-version = "1.9.0"
+version = "1.9.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a07d1f37ff60921c83bdfc7407723bdefe89b44b98a9b772f225c8f9d67141a6"
+checksum = "6a3a1fd6f75306b68087b831f025c712524bcb19aad54e557b1129cfa0a2b207"
 dependencies = [
  "rustversion",
 ]
 
 [[package]]
 name = "asn1-rs"
-version = "0.6.2"
+version = "0.7.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5493c3bedbacf7fd7382c6346bbd66687d12bbaad3a89a2d2c303ee6cf20b048"
+checksum = "56624a96882bb8c26d61312ae18cb45868e5a9992ea73c58e45c3101e56a1e60"
 dependencies = [
  "asn1-rs-derive",
  "asn1-rs-impl",
@@ -94,15 +103,15 @@ dependencies = [
  "nom",
  "num-traits",
  "rusticata-macros",
- "thiserror 1.0.69",
+ "thiserror",
  "time",
 ]
 
 [[package]]
 name = "asn1-rs-derive"
-version = "0.5.1"
+version = "0.6.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "965c2d33e53cb6b267e148a4cb0760bc01f4904c1cd4bb4002a085bb016d1490"
+checksum = "3109e49b1e4909e9db6515a30c633684d68cdeaa252f215214cb4fa1a5bfee2c"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -368,25 +377,24 @@ dependencies = [
 
 [[package]]
 name = "criterion"
-version = "0.5.1"
+version = "0.8.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f2b12d017a929603d80db1831cd3a24082f8137ce19c69e6447f54f5fc8d692f"
+checksum = "950046b2aa2492f9a536f5f4f9a3de7b9e2476e575e05bd6c333371add4d98f3"
 dependencies = [
+ "alloca",
  "anes",
  "cast",
  "ciborium",
  "clap",
  "criterion-plot",
- "is-terminal",
  "itertools",
  "num-traits",
- "once_cell",
  "oorandom",
+ "page_size",
  "plotters",
  "rayon",
  "regex",
  "serde",
- "serde_derive",
  "serde_json",
  "tinytemplate",
  "walkdir",
@@ -394,9 +402,9 @@ dependencies = [
 
 [[package]]
 name = "criterion-plot"
-version = "0.5.0"
+version = "0.8.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6b50826342786a51a89e2da3a28f1c32b06e387201bc2d19791f622c673706b1"
+checksum = "d8d80a2f4f5b554395e47b5d8305bc3d27813bacb73493eb1001e8f76dae29ea"
 dependencies = [
  "cast",
  "itertools",
@@ -441,9 +449,9 @@ checksum = "d7a1e2f27636f116493b8b860f5546edb47c8d8f8ea73e1d2a20be88e28d1fea"
 
 [[package]]
 name = "der-parser"
-version = "9.0.0"
+version = "10.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5cd0a5c643689626bec213c4d8bd4d96acc8ffdb4ad4bb6bc16abf27d5f4b553"
+checksum = "07da5016415d5a3c4dd39b11ed26f915f52fc4e0dc197d87908bc916e51bc1a6"
 dependencies = [
  "asn1-rs",
  "displaydoc",
@@ -702,12 +710,6 @@ version = "0.16.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "841d1cc9bed7f9236f321df977030373f4a4163ae1a7dbfe1a51a2c1a51d9100"
 
-[[package]]
-name = "hermit-abi"
-version = "0.5.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fc0fef456e4baa96da950455cd02c081ca953b141298e41db3fc7e36b1da849c"
-
 [[package]]
 name = "http"
 version = "1.4.0"
@@ -755,9 +757,9 @@ checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9"
 
 [[package]]
 name = "hyper"
-version = "1.8.1"
+version = "1.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2ab2d4f250c3d7b1c9fcdff1cece94ea4e2dfbec68614f7b87cb205f24ca9d11"
+checksum = "6299f016b246a94207e63da54dbe807655bf9e00044f73ded42c3ac5305fbcca"
 dependencies = [
  "atomic-waker",
  "bytes",
@@ -770,7 +772,6 @@ dependencies = [
  "httpdate",
  "itoa",
  "pin-project-lite",
- "pin-utils",
  "smallvec",
  "tokio",
  "want",
@@ -810,7 +811,7 @@ dependencies = [
  "libc",
  "percent-encoding",
  "pin-project-lite",
- "socket2 0.6.3",
+ "socket2",
  "tokio",
  "tower-service",
  "tracing",
@@ -944,17 +945,6 @@ dependencies = [
  "serde",
 ]
 
-[[package]]
-name = "is-terminal"
-version = "0.4.17"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3640c1c38b8e4e43584d8df18be5fc6b0aa314ce6ebf51b53313d4306cca8e46"
-dependencies = [
- "hermit-abi",
- "libc",
- "windows-sys 0.61.2",
-]
-
 [[package]]
 name = "is_terminal_polyfill"
 version = "1.70.2"
@@ -963,9 +953,9 @@ checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
 
 [[package]]
 name = "itertools"
-version = "0.10.5"
+version = "0.13.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b0fd2260e829bddf4cb6ea802289de2f86d6a7a690192fbe91b3f46e0f2c8473"
+checksum = "413ee7dfc52ee1a4949ceeb7dbc8a33f2d6c088194d9f922fb8318faf1f01186"
 dependencies = [
  "either",
 ]
@@ -1143,7 +1133,7 @@ dependencies = [
 
 [[package]]
 name = "numa"
-version = "0.10.0"
+version = "0.10.3"
 dependencies = [
  "arc-swap",
  "axum",
@@ -1162,7 +1152,7 @@ dependencies = [
  "rustls-pemfile",
  "serde",
  "serde_json",
- "socket2 0.5.10",
+ "socket2",
  "time",
  "tokio",
  "tokio-rustls",
@@ -1172,9 +1162,9 @@ dependencies = [
 
 [[package]]
 name = "oid-registry"
-version = "0.7.1"
+version = "0.8.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a8d8034d9489cdaf79228eb9f6a3b8d7bb32ba00d6645ebd48eef4077ceb5bd9"
+checksum = "12f40cff3dde1b6087cc5d5f5d4d65712f34016a03ed60e9c08dcc392736b5b7"
 dependencies = [
  "asn1-rs",
 ]
@@ -1197,6 +1187,16 @@ version = "11.1.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d6790f58c7ff633d8771f42965289203411a5e5c68388703c06e14f24770b41e"
 
+[[package]]
+name = "page_size"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "30d5b2194ed13191c1999ae0704b7839fb18384fa22e49b57eeaa97d79ce40da"
+dependencies = [
+ "libc",
+ "winapi",
+]
+
 [[package]]
 name = "pem"
 version = "3.0.6"
@@ -1219,12 +1219,6 @@ version = "0.2.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
 
-[[package]]
-name = "pin-utils"
-version = "0.1.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8b870d8c151b6f2fb93e84a13146138f05d02ed11c7e7c54f8826aaaf7c9f184"
-
 [[package]]
 name = "plotters"
 version = "0.3.7"
@@ -1314,8 +1308,8 @@ dependencies = [
  "quinn-udp",
  "rustc-hash",
  "rustls",
- "socket2 0.6.3",
+ "socket2",
- "thiserror 2.0.18",
+ "thiserror",
  "tokio",
  "tracing",
  "web-time",
@@ -1336,7 +1330,7 @@ dependencies = [
  "rustls",
  "rustls-pki-types",
  "slab",
- "thiserror 2.0.18",
+ "thiserror",
  "tinyvec",
  "tracing",
  "web-time",
@@ -1351,7 +1345,7 @@ dependencies = [
  "cfg_aliases",
  "libc",
  "once_cell",
- "socket2 0.6.3",
+ "socket2",
  "tracing",
  "windows-sys 0.60.2",
 ]
@@ -1422,9 +1416,9 @@ dependencies = [
 
 [[package]]
 name = "rcgen"
-version = "0.13.2"
+version = "0.14.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "75e669e5202259b5314d1ea5397316ad400819437857b90861765f24c4cf80a2"
+checksum = "10b99e0098aa4082912d4c649628623db6aba77335e4f4569ff5083a6448b32e"
 dependencies = [
  "pem",
  "ring",
@@ -1655,11 +1649,11 @@ dependencies = [
 
 [[package]]
 name = "serde_spanned"
-version = "0.6.9"
+version = "1.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bf41e0cfaf7226dca15e8197172c295a782857fcb97fad1808a166870dee75a3"
+checksum = "6662b5879511e06e8999a8a235d848113e942c9124f211511b16466ee2995f26"
 dependencies = [
- "serde",
+ "serde_core",
 ]
 
 [[package]]
@@ -1698,16 +1692,6 @@ version = "1.15.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "67b1b7a3b5fe4f1376887184045fcf45c69e92af734b7aaddc05fb777b6fbd03"
 
-[[package]]
-name = "socket2"
-version = "0.5.10"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e22376abed350d73dd1cd119b57ffccad95b4e585a7cda43e286245ce23c0678"
-dependencies = [
- "libc",
- "windows-sys 0.52.0",
-]
-
 [[package]]
 name = "socket2"
 version = "0.6.3"
@@ -1761,33 +1745,13 @@ dependencies = [
  "syn",
 ]
 
-[[package]]
-name = "thiserror"
-version = "1.0.69"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b6aaf5339b578ea85b50e080feb250a3e8ae8cfcdff9a461c9ec2904bc923f52"
-dependencies = [
- "thiserror-impl 1.0.69",
-]
-
 [[package]]
 name = "thiserror"
 version = "2.0.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4288b5bcbc7920c07a1149a35cf9590a2aa808e0bc1eafaade0b80947865fbc4"
 dependencies = [
- "thiserror-impl 2.0.18",
+ "thiserror-impl",
-]
-
-[[package]]
-name = "thiserror-impl"
-version = "1.0.69"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn",
 ]
 
 [[package]]
@@ -1869,24 +1833,24 @@ checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
 
 [[package]]
 name = "tokio"
-version = "1.50.0"
+version = "1.51.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "27ad5e34374e03cfffefc301becb44e9dc3c17584f414349ebe29ed26661822d"
+checksum = "f66bf9585cda4b724d3e78ab34b73fb2bbaba9011b9bfdf69dc836382ea13b8c"
 dependencies = [
  "bytes",
  "libc",
  "mio",
  "pin-project-lite",
- "socket2 0.6.3",
+ "socket2",
  "tokio-macros",
  "windows-sys 0.61.2",
 ]
 
 [[package]]
 name = "tokio-macros"
-version = "2.6.1"
+version = "2.7.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5c55a2eff8b69ce66c84f85e1da1c233edc36ceb85a2058d11b0d6a3c7e7569c"
+checksum = "385a6cb71ab9ab790c5fe8d67f1645e6c450a7ce006a33de03daa956cf70a496"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -1918,44 +1882,42 @@ dependencies = [
 
 [[package]]
 name = "toml"
-version = "0.8.23"
+version = "1.1.2+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dc1beb996b9d83529a9e75c17a1686767d148d70663143c7854d8b4a09ced362"
+checksum = "81f3d15e84cbcd896376e6730314d59fb5a87f31e4b038454184435cd57defee"
-dependencies = [
- "serde",
- "serde_spanned",
- "toml_datetime",
- "toml_edit",
-]
-
-[[package]]
-name = "toml_datetime"
-version = "0.6.11"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "22cddaf88f4fbc13c51aebbf5f8eceb5c7c5a9da2ac40a13519eb5b0a0e8f11c"
-dependencies = [
- "serde",
-]
-
-[[package]]
-name = "toml_edit"
-version = "0.22.27"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "41fe8c660ae4257887cf66394862d21dbca4a6ddd26f04a3560410406a2f819a"
 dependencies = [
  "indexmap",
- "serde",
+ "serde_core",
  "serde_spanned",
  "toml_datetime",
- "toml_write",
+ "toml_parser",
+ "toml_writer",
  "winnow",
 ]
 
 [[package]]
-name = "toml_write"
+name = "toml_datetime"
-version = "0.1.2"
+version = "1.1.1+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5d99f8c9a7727884afe522e9bd5edbfc91a3312b36a77b5fb8926e4c31a41801"
+checksum = "3165f65f62e28e0115a00b2ebdd37eb6f3b641855f9d636d3cd4103767159ad7"
+dependencies = [
+ "serde_core",
+]
+
+[[package]]
+name = "toml_parser"
+version = "1.1.2+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a2abe9b86193656635d2411dc43050282ca48aa31c2451210f4202550afb7526"
+dependencies = [
+ "winnow",
+]
+
+[[package]]
+name = "toml_writer"
+version = "1.1.1+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "756daf9b1013ebe47a8776667b466417e2d4c5679d441c26230efd9ef78692db"
 
 [[package]]
 name = "tower"
@@ -2188,6 +2150,22 @@ dependencies = [
  "rustls-pki-types",
 ]
 
+[[package]]
+name = "winapi"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419"
+dependencies = [
+ "winapi-i686-pc-windows-gnu",
+ "winapi-x86_64-pc-windows-gnu",
+]
+
+[[package]]
+name = "winapi-i686-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6"
+
 [[package]]
 name = "winapi-util"
 version = "0.1.11"
@@ -2197,6 +2175,12 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "winapi-x86_64-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
+
 [[package]]
 name = "windows-link"
 version = "0.2.1"
@@ -2361,12 +2345,9 @@ checksum = "d6bbff5f0aada427a1e5a6da5f1f98158182f26556f345ac9e04d36d0ebed650"
 
 [[package]]
 name = "winnow"
-version = "0.7.15"
+version = "1.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "df79d97927682d2fd8adb29682d1140b343be4ac0f08fd68b7765d9c059d3945"
+checksum = "09dac053f1cd375980747450bfc7250c264eaae0583872e845c0c7cd578872b5"
-dependencies = [
- "memchr",
-]
 
 [[package]]
 name = "wit-bindgen"
@@ -2382,9 +2363,9 @@ checksum = "9edde0db4769d2dc68579893f2306b26c6ecfbe0ef499b013d731b7b9247e0b9"
 
 [[package]]
 name = "x509-parser"
-version = "0.16.0"
+version = "0.18.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fcbc162f30700d6f3f82a24bf7cc62ffe7caea42c0b2cba8bf7f3ae50cf51f69"
+checksum = "d43b0f71ce057da06bc0851b23ee24f3f86190b07203dd8f567d0b706a185202"
 dependencies = [
  "asn1-rs",
  "data-encoding",
@@ -2394,7 +2375,7 @@ dependencies = [
  "oid-registry",
  "ring",
  "rusticata-macros",
- "thiserror 1.0.69",
+ "thiserror",
  "time",
 ]
 

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "numa"
-version = "0.10.0"
+version = "0.10.3"
 authors = ["razvandimescu <razvan@dimescu.com>"]
 edition = "2021"
 description = "Portable DNS resolver in Rust — .numa local domains, ad blocking, developer overrides, DNS-over-HTTPS"
@@ -14,7 +14,7 @@ tokio = { version = "1", features = ["rt-multi-thread", "macros", "net", "time",
 axum = "0.8"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
-toml = "0.8"
+toml = "1.1"
 log = "0.4"
 env_logger = "0.11"
 reqwest = { version = "0.12", features = ["rustls-tls", "gzip", "http2"], default-features = false }
@@ -22,8 +22,8 @@ hyper = { version = "1", features = ["client", "http1", "server"] }
 hyper-util = { version = "0.1", features = ["client-legacy", "http1", "tokio"] }
 http-body-util = "0.1"
 futures = "0.3"
-socket2 = { version = "0.5", features = ["all"] }
+socket2 = { version = "0.6", features = ["all"] }
-rcgen = { version = "0.13", features = ["pem", "x509-parser"] }
+rcgen = { version = "0.14", features = ["pem", "x509-parser"] }
 time = "0.3"
 rustls = "0.23"
 tokio-rustls = "0.26"
@@ -32,7 +32,7 @@ ring = "0.17"
 rustls-pemfile = "2.2.0"
 
 [dev-dependencies]
-criterion = { version = "0.5", features = ["html_reports"] }
+criterion = { version = "0.8", features = ["html_reports"] }
 tower = { version = "0.5", features = ["util"] }
 http = "1"
 

Dockerfile

@@ -1,4 +1,4 @@
-FROM rust:1.88-alpine AS builder
+FROM rust:1.94-alpine AS builder
 RUN apk add --no-cache musl-dev cmake make perl
 WORKDIR /app
 COPY Cargo.toml Cargo.lock ./
@@ -11,7 +11,7 @@ COPY numa.toml com.numa.dns.plist numa.service ./
 RUN touch src/main.rs src/lib.rs
 RUN cargo build --release
 
-FROM alpine:3.20
+FROM alpine:3.23
 COPY --from=builder /app/target/release/numa /usr/local/bin/numa
 EXPOSE 53/udp 80/tcp 443/tcp 853/tcp 5380/tcp
 ENTRYPOINT ["numa"]

PKGBUILD

@@ -0,0 +1,62 @@
+# Maintainer: razvandimescu <razvan@dimescu.com>
+pkgname=numa-git
+_pkgname=numa
+pkgver=0.10.1.r0.g0000000 # Placeholder — pkgver() rewrites this on each makepkg run
+pkgrel=1
+pkgdesc="Portable DNS resolver in Rust — .numa local domains, ad blocking, developer overrides, DNS-over-HTTPS"
+arch=('x86_64')
+url="https://github.com/razvandimescu/numa"
+license=('MIT')
+options=('!lto')
+depends=('gcc-libs' 'glibc')
+makedepends=('cargo' 'git')
+provides=("$_pkgname")
+conflicts=("$_pkgname")
+backup=('etc/numa.toml')
+source=("$_pkgname::git+$url.git")
+sha256sums=('SKIP')
+
+pkgver() {
+  cd "$srcdir/$_pkgname"
+  ( set -o pipefail
+    git describe --long --tags 2>/dev/null | sed 's/\([^-]*-g\)/r\1/;s/-/./g' ||
+    printf "r%s.%s" "$(git rev-list --count HEAD)" "$(git rev-parse --short HEAD)"
+  ) | sed 's/^v//'
+}
+
+prepare() {
+  cd "$srcdir/$_pkgname"
+  # numa v0.10.1+ uses FHS-compliant paths on Linux by default
+  # (/var/lib/numa for data, journalctl for logs), so no source
+  # patching is needed. The earlier sed targeted /usr/local/bin/numa,
+  # which only appears in a comment in current main.
+  export RUSTUP_TOOLCHAIN=stable
+  cargo fetch --locked
+}
+
+build() {
+  cd "$srcdir/$_pkgname"
+  export RUSTUP_TOOLCHAIN=stable
+  cargo build --frozen --release
+}
+
+check() {
+  cd "$srcdir/$_pkgname"
+  export RUSTUP_TOOLCHAIN=stable
+  cargo test --frozen
+}
+
+package() {
+  cd "$srcdir/$_pkgname"
+  install -Dm755 "target/release/$_pkgname" "$pkgdir/usr/bin/$_pkgname"
+
+  # numa.service uses {{exe_path}} as a placeholder substituted by
+  # `numa install` at runtime via replace_exe_path(). For an AUR
+  # package install (no `numa install` step), we substitute it
+  # statically here so systemd gets a real ExecStart path.
+  sed 's|{{exe_path}}|/usr/bin/numa /etc/numa.toml|g' numa.service > numa.service.patched
+  install -Dm644 "numa.service.patched" "$pkgdir/usr/lib/systemd/system/numa.service"
+
+  install -Dm644 "numa.toml" "$pkgdir/etc/numa.toml"
+  install -Dm644 "LICENSE" "$pkgdir/usr/share/licenses/$pkgname/LICENSE"
+}

README.md

@@ -21,6 +21,9 @@ brew install razvandimescu/tap/numa
 # Linux
 curl -fsSL https://raw.githubusercontent.com/razvandimescu/numa/main/install.sh | sh
 
+# Arch Linux (AUR)
+yay -S numa-git
+
 # Windows — download from GitHub Releases
 # All platforms
 cargo install numa
@@ -69,7 +72,7 @@ DNSSEC validates the full chain of trust: RRSIG signatures, DNSKEY verification,
 
 **DNS-over-TLS listener** (RFC 7858) — accept encrypted queries on port 853 from strict clients like iOS Private DNS, systemd-resolved, or stubby. Two modes:
 
-- **Self-signed** (default) — numa generates a local CA automatically. Works on any network with zero DNS setup, but clients must manually trust the CA (on macOS/Linux add to the system trust store; on iOS install a `.mobileconfig`).
+- **Self-signed** (default) — numa generates a local CA automatically. `numa install` adds it to the system trust store on macOS, Linux (Debian/Ubuntu, Fedora/RHEL/SUSE, Arch), and Windows. On iOS, install the `.mobileconfig` from `numa setup-phone`. Firefox keeps its own NSS store and ignores the system one — trust the CA there manually if you need HTTPS for `.numa` services in Firefox.
 - **Bring-your-own cert** — point `[dot] cert_path` / `key_path` at a publicly-trusted cert (e.g., Let's Encrypt via DNS-01 challenge on a domain pointing at your numa instance). Clients connect without any trust-store setup — same UX as AdGuard Home or Cloudflare `1.1.1.1`.
 
 ALPN `"dot"` is advertised and enforced in both modes; a handshake with mismatched ALPN is rejected as a cross-protocol confusion defense.

numa.toml

@@ -2,11 +2,12 @@
 bind_addr = "0.0.0.0:53"
 api_port = 5380
 # api_bind_addr = "127.0.0.1"  # default; set to "0.0.0.0" for LAN dashboard access
-# data_dir = "/usr/local/var/numa"  # where numa stores TLS CA and cert material
+# data_dir = "/var/lib/numa"  # where numa stores TLS CA and cert material
-                                    # (default: /usr/local/var/numa on unix,
+                              # Defaults: /var/lib/numa on linux (FHS),
-                                    # %PROGRAMDATA%\numa on windows). Override for
+                              # /usr/local/var/numa on macos (homebrew prefix),
-                                    # containerized deploys or tests that can't
+                              # %PROGRAMDATA%\numa on windows. Override for
-                                    # write to the system path.
+                              # containerized deploys or tests that can't
+                              # write to the system path.
 
 # [upstream]
 # mode = "forward"                              # "forward" (default) — relay to upstream

scripts/update-homebrew-formula.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+"""Rewrite a Homebrew formula in place: bump version, URL paths, and sha256 lines.
+
+Reads the formula path from argv[1], and the following env vars:
+  VERSION              e.g. "0.10.0" (no leading v)
+  SHA_MACOS_AARCH64
+  SHA_MACOS_X86_64
+  SHA_LINUX_AARCH64
+  SHA_LINUX_X86_64
+
+Assumptions about the formula:
+  - Has `version "X.Y.Z"` somewhere
+  - Has `url "...releases/download/vX.Y.Z/numa-<target>.tar.gz"` lines
+  - May or may not already have `sha256 "..."` lines immediately after each url
+"""
+import os
+import re
+import sys
+
+formula_path = sys.argv[1]
+version = os.environ["VERSION"].lstrip("v")
+shas = {
+    "macos-aarch64": os.environ["SHA_MACOS_AARCH64"],
+    "macos-x86_64": os.environ["SHA_MACOS_X86_64"],
+    "linux-aarch64": os.environ["SHA_LINUX_AARCH64"],
+    "linux-x86_64": os.environ["SHA_LINUX_X86_64"],
+}
+
+with open(formula_path) as f:
+    content = f.read()
+
+content = re.sub(r'version "[^"]*"', f'version "{version}"', content)
+content = re.sub(
+    r"releases/download/v[\d.]+/numa-",
+    f"releases/download/v{version}/numa-",
+    content,
+)
+content = re.sub(r'\n[ \t]*sha256 "[^"]*"', "", content)
+
+
+def add_sha(match: re.Match) -> str:
+    indent = match.group(1)
+    target = match.group(2)
+    if target not in shas:
+        return match.group(0)
+    return f'{match.group(0)}\n{indent}sha256 "{shas[target]}"'
+
+
+content = re.sub(
+    r'^([ \t]+)url "[^"]*numa-([\w-]+)\.tar\.gz"',
+    add_sha,
+    content,
+    flags=re.MULTILINE,
+)
+
+with open(formula_path, "w") as f:
+    f.write(content)

src/api.rs

@@ -906,7 +906,7 @@ async fn remove_route(
 }
 
 async fn serve_ca(State(ctx): State<Arc<ServerCtx>>) -> Result<impl IntoResponse, StatusCode> {
-    let ca_path = ctx.data_dir.join("ca.pem");
+    let ca_path = ctx.data_dir.join(crate::tls::CA_FILE_NAME);
     let bytes = tokio::task::spawn_blocking(move || std::fs::read(ca_path))
         .await
         .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?

src/buffer.rs

@@ -84,6 +84,11 @@ impl BytePacketBuffer {
 
     /// Read a qname, handling label compression (pointer jumps).
     /// Converts wire format like [3]www[6]google[3]com[0] into "www.google.com".
+    ///
+    /// Label bytes are escaped per RFC 1035 §5.1:
+    /// - literal `.` within a label → `\.`
+    /// - literal `\` → `\\`
+    /// - bytes outside `0x21..=0x7E` (excluding `.` and `\`) → `\DDD` (3-digit decimal)
     pub fn read_qname(&mut self, outstr: &mut String) -> Result<()> {
         let mut pos = self.pos();
         let mut jumped = false;
@@ -121,7 +126,18 @@ impl BytePacketBuffer {
 
                 let str_buffer = self.get_range(pos, len as usize)?;
                 for &b in str_buffer {
-                    outstr.push(b.to_ascii_lowercase() as char);
+                    let c = b.to_ascii_lowercase();
+                    match c {
+                        b'.' => outstr.push_str("\\."),
+                        b'\\' => outstr.push_str("\\\\"),
+                        0x21..=0x7E => outstr.push(c as char),
+                        _ => {
+                            outstr.push('\\');
+                            outstr.push((b'0' + c / 100) as char);
+                            outstr.push((b'0' + (c / 10) % 10) as char);
+                            outstr.push((b'0' + c % 10) as char);
+                        }
+                    }
                 }
 
                 delim = ".";
@@ -163,24 +179,68 @@ impl BytePacketBuffer {
         Ok(())
     }
 
+    /// Write a qname in wire format, parsing RFC 1035 §5.1 text escapes.
+    /// See `read_qname` for the escape grammar.
     pub fn write_qname(&mut self, qname: &str) -> Result<()> {
         if qname.is_empty() || qname == "." {
             self.write_u8(0)?;
             return Ok(());
         }
 
-        for label in qname.split('.') {
+        let bytes = qname.as_bytes();
-            let len = label.len();
+        let mut i = 0;
-            if len == 0 {
+        while i < bytes.len() {
-                continue; // skip empty labels from trailing dot
+            let len_pos = self.pos;
-            }
+            self.write_u8(0)?; // placeholder length byte, backpatched below
-            if len > 0x3f {
+            let body_start = self.pos;
-                return Err("Single label exceeds 63 characters of length".into());
+
+            while i < bytes.len() && bytes[i] != b'.' {
+                let b = bytes[i];
+                if b == b'\\' {
+                    i += 1;
+                    let c1 = *bytes.get(i).ok_or("trailing backslash in qname")?;
+                    if c1.is_ascii_digit() {
+                        let c2 = *bytes
+                            .get(i + 1)
+                            .ok_or("invalid \\DDD escape: expected 3 digits")?;
+                        let c3 = *bytes
+                            .get(i + 2)
+                            .ok_or("invalid \\DDD escape: expected 3 digits")?;
+                        if !c2.is_ascii_digit() || !c3.is_ascii_digit() {
+                            return Err("invalid \\DDD escape: expected 3 digits".into());
+                        }
+                        let val =
+                            (c1 - b'0') as u16 * 100 + (c2 - b'0') as u16 * 10 + (c3 - b'0') as u16;
+                        if val > 255 {
+                            return Err(format!("\\DDD escape out of range: {}", val).into());
+                        }
+                        self.write_u8(val as u8)?;
+                        i += 3;
+                    } else {
+                        // \. \\ and any other \X → literal next byte
+                        self.write_u8(c1)?;
+                        i += 1;
+                    }
+                } else {
+                    self.write_u8(b)?;
+                    i += 1;
+                }
+
+                if self.pos - body_start > 0x3f {
+                    return Err("Single label exceeds 63 characters of length".into());
+                }
             }
 
-            self.write_u8(len as u8)?;
+            let label_len = self.pos - body_start;
-            for b in label.as_bytes() {
+            if label_len == 0 && i < bytes.len() {
-                self.write_u8(*b)?;
+                // Empty label from leading/consecutive dots — roll back the placeholder.
+                self.pos = len_pos;
+            } else {
+                self.set(len_pos, label_len as u8)?;
+            }
+
+            if i < bytes.len() && bytes[i] == b'.' {
+                i += 1;
             }
         }
 
@@ -212,3 +272,160 @@ impl BytePacketBuffer {
         Ok(())
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn roundtrip(wire: &[u8]) -> String {
+        let mut buf = BytePacketBuffer::from_bytes(wire);
+        let mut out = String::new();
+        buf.read_qname(&mut out).unwrap();
+        out
+    }
+
+    fn write_then_read(text: &str) -> String {
+        let mut buf = BytePacketBuffer::new();
+        buf.write_qname(text).unwrap();
+        let wire_end = buf.pos();
+        buf.seek(0).unwrap();
+        let mut out = String::new();
+        buf.read_qname(&mut out).unwrap();
+        assert_eq!(
+            buf.pos(),
+            wire_end,
+            "reader should consume exactly what writer wrote"
+        );
+        out
+    }
+
+    #[test]
+    fn read_plain_domain() {
+        // [3]www[6]google[3]com[0]
+        let wire = b"\x03www\x06google\x03com\x00";
+        assert_eq!(roundtrip(wire), "www.google.com");
+    }
+
+    #[test]
+    fn read_label_with_literal_dot_is_escaped() {
+        // fanf2's example: [8]exa.mple[3]com[0] — two labels, first contains 0x2E
+        let wire = b"\x08exa.mple\x03com\x00";
+        assert_eq!(roundtrip(wire), "exa\\.mple.com");
+    }
+
+    #[test]
+    fn read_label_with_backslash_is_escaped() {
+        // [4]a\bc[3]com[0]
+        let wire = b"\x04a\\bc\x03com\x00";
+        assert_eq!(roundtrip(wire), "a\\\\bc.com");
+    }
+
+    #[test]
+    fn read_label_with_nonprintable_byte_uses_decimal_escape() {
+        // [4]\x00foo[3]com[0] — null byte at label start
+        let wire = b"\x04\x00foo\x03com\x00";
+        assert_eq!(roundtrip(wire), "\\000foo.com");
+    }
+
+    #[test]
+    fn read_label_with_space_uses_decimal_escape() {
+        // Space (0x20) is outside 0x21..=0x7E, so it must be decimal-escaped.
+        let wire = b"\x05a b c\x00";
+        assert_eq!(roundtrip(wire), "a\\032b\\032c");
+    }
+
+    #[test]
+    fn write_plain_domain() {
+        let mut buf = BytePacketBuffer::new();
+        buf.write_qname("www.google.com").unwrap();
+        assert_eq!(&buf.buf[..buf.pos], b"\x03www\x06google\x03com\x00");
+    }
+
+    #[test]
+    fn write_escaped_dot_does_not_split_label() {
+        let mut buf = BytePacketBuffer::new();
+        buf.write_qname("exa\\.mple.com").unwrap();
+        assert_eq!(&buf.buf[..buf.pos], b"\x08exa.mple\x03com\x00");
+    }
+
+    #[test]
+    fn write_escaped_backslash() {
+        let mut buf = BytePacketBuffer::new();
+        buf.write_qname("a\\\\bc.com").unwrap();
+        assert_eq!(&buf.buf[..buf.pos], b"\x04a\\bc\x03com\x00");
+    }
+
+    #[test]
+    fn write_decimal_escape_yields_raw_byte() {
+        let mut buf = BytePacketBuffer::new();
+        buf.write_qname("\\000foo.com").unwrap();
+        assert_eq!(&buf.buf[..buf.pos], b"\x04\x00foo\x03com\x00");
+    }
+
+    #[test]
+    fn write_skips_empty_labels() {
+        // Leading dot — first (empty) label is rolled back.
+        let mut buf = BytePacketBuffer::new();
+        buf.write_qname(".foo.com").unwrap();
+        assert_eq!(&buf.buf[..buf.pos], b"\x03foo\x03com\x00");
+
+        // Consecutive dots — middle empty label is rolled back.
+        let mut buf = BytePacketBuffer::new();
+        buf.write_qname("foo..com").unwrap();
+        assert_eq!(&buf.buf[..buf.pos], b"\x03foo\x03com\x00");
+    }
+
+    #[test]
+    fn write_rejects_out_of_range_decimal_escape() {
+        let mut buf = BytePacketBuffer::new();
+        assert!(buf.write_qname("\\999foo.com").is_err());
+    }
+
+    #[test]
+    fn write_rejects_trailing_backslash() {
+        let mut buf = BytePacketBuffer::new();
+        assert!(buf.write_qname("foo\\").is_err());
+    }
+
+    #[test]
+    fn write_rejects_short_decimal_escape() {
+        let mut buf = BytePacketBuffer::new();
+        assert!(buf.write_qname("\\1").is_err());
+    }
+
+    #[test]
+    fn write_rejects_label_over_63_bytes() {
+        // 64 bytes exceeds the wire-format label cap.
+        let mut buf = BytePacketBuffer::new();
+        assert!(buf.write_qname(&"a".repeat(64)).is_err());
+
+        // 63 bytes is the maximum permitted label length.
+        let mut buf = BytePacketBuffer::new();
+        assert!(buf.write_qname(&"a".repeat(63)).is_ok());
+    }
+
+    #[test]
+    fn roundtrip_preserves_dot_in_label() {
+        assert_eq!(write_then_read("exa\\.mple.com"), "exa\\.mple.com");
+    }
+
+    #[test]
+    fn roundtrip_preserves_backslash_in_label() {
+        assert_eq!(write_then_read("a\\\\b.com"), "a\\\\b.com");
+    }
+
+    #[test]
+    fn roundtrip_preserves_nonprintable_byte() {
+        assert_eq!(write_then_read("\\000foo.com"), "\\000foo.com");
+    }
+
+    #[test]
+    fn root_name_empty_and_dot_both_produce_single_zero() {
+        let mut a = BytePacketBuffer::new();
+        a.write_qname("").unwrap();
+        let mut b = BytePacketBuffer::new();
+        b.write_qname(".").unwrap();
+        assert_eq!(&a.buf[..a.pos], b"\x00");
+        assert_eq!(&b.buf[..b.pos], b"\x00");
+    }
+}

src/dnssec.rs

@@ -5,6 +5,7 @@ use log::{debug, trace};
 use ring::digest;
 use ring::signature;
 
+use crate::buffer::BytePacketBuffer;
 use crate::cache::{DnsCache, DnssecStatus};
 use crate::packet::DnsPacket;
 use crate::question::QueryType;
@@ -720,22 +721,29 @@ pub fn verify_ds(ds: &DnsRecord, dnskey: &DnsRecord, owner: &str) -> bool {
 
 // -- Canonical wire format --
 
+/// Encode a DNS name in canonical wire form per RFC 4034 §6.2:
+/// uncompressed, with ASCII letters lowercased.
+///
+/// Lowercasing happens *after* escape resolution because `\065` yields
+/// `'A'`, which canonical form must convert to `'a'`.
 pub fn name_to_wire(name: &str) -> Vec<u8> {
-    let mut wire = Vec::with_capacity(name.len() + 2);
+    let mut buf = BytePacketBuffer::new();
-    if name == "." || name.is_empty() {
+    buf.write_qname(name)
-        wire.push(0);
+        .expect("name_to_wire: input must parse as a valid DNS name");
-        return wire;
+    let mut wire = buf.filled().to_vec();
-    }
+
-    for label in name.split('.') {
+    let mut i = 0;
-        if label.is_empty() {
+    while i < wire.len() {
-            continue;
+        let label_len = wire[i] as usize;
-        }
+        if label_len == 0 {
-        wire.push(label.len() as u8);
+            break;
-        for &b in label.as_bytes() {
-            wire.push(b.to_ascii_lowercase());
         }
+        i += 1;
+        let end = i + label_len;
+        wire[i..end].make_ascii_lowercase();
+        i = end;
     }
-    wire.push(0);
+
     wire
 }
 
@@ -1475,6 +1483,23 @@ mod tests {
         );
     }
 
+    #[test]
+    fn name_to_wire_escaped_dot_in_label_is_not_a_separator() {
+        // `exa\.mple.com` is two labels: `exa.mple` (8 bytes including the 0x2E) and `com`.
+        let wire = name_to_wire("exa\\.mple.com");
+        assert_eq!(
+            wire,
+            vec![8, b'e', b'x', b'a', b'.', b'm', b'p', b'l', b'e', 3, b'c', b'o', b'm', 0]
+        );
+    }
+
+    #[test]
+    fn name_to_wire_decimal_escape_is_lowercased() {
+        // \065 = 'A', must become 'a' in canonical form.
+        let wire = name_to_wire("\\065bc.com");
+        assert_eq!(wire, vec![3, b'a', b'b', b'c', 3, b'c', b'o', b'm', 0]);
+    }
+
     #[test]
     fn parent_zone_cases() {
         assert_eq!(parent_zone("example.com"), "com");

src/lib.rs

@@ -26,7 +26,10 @@ pub type Error = Box<dyn std::error::Error + Send + Sync>;
 pub type Result<T> = std::result::Result<T, Error>;
 
 /// Shared config directory for persistent data (services.json, etc).
-/// Unix: ~/.config/numa/ (or /usr/local/var/numa/ when running as root daemon)
+/// Unix users: ~/.config/numa/
+/// Linux root daemon: /var/lib/numa (FHS) — falls back to /usr/local/var/numa
+///                    if a pre-v0.10.1 install already lives there.
+/// macOS root daemon: /usr/local/var/numa (Homebrew prefix)
 /// Windows: %APPDATA%\numa
 pub fn config_dir() -> std::path::PathBuf {
     #[cfg(windows)]
@@ -63,13 +66,15 @@ fn config_dir_unix() -> std::path::PathBuf {
     }
 
     // Running as root daemon (launchd/systemd) — use system-wide path
-    std::path::PathBuf::from("/usr/local/var/numa")
+    daemon_data_dir()
 }
 
 /// Default system-wide data directory for TLS certs. Overridable via
 /// `[server] data_dir = "..."` in numa.toml — this function only provides
 /// the fallback when the config doesn't set it.
-/// Unix: /usr/local/var/numa
+/// Linux: /var/lib/numa (FHS) — falls back to /usr/local/var/numa if a
+///        pre-v0.10.1 install already has data there.
+/// macOS: /usr/local/var/numa (Homebrew prefix)
 /// Windows: %PROGRAMDATA%\numa
 pub fn data_dir() -> std::path::PathBuf {
     #[cfg(windows)]
@@ -81,6 +86,62 @@ pub fn data_dir() -> std::path::PathBuf {
     }
     #[cfg(not(windows))]
     {
+        daemon_data_dir()
+    }
+}
+
+/// Resolve the system-wide data directory for the running platform.
+/// Honors backwards compatibility with pre-v0.10.1 installs that still
+/// have their CA cert + services.json under `/usr/local/var/numa`.
+#[cfg(not(windows))]
+fn daemon_data_dir() -> std::path::PathBuf {
+    #[cfg(target_os = "linux")]
+    {
+        std::path::PathBuf::from(resolve_linux_data_dir(
+            std::path::Path::new("/usr/local/var/numa").exists(),
+            std::path::Path::new("/var/lib/numa").exists(),
+        ))
+    }
+    #[cfg(target_os = "macos")]
+    {
+        // macOS uses the Homebrew prefix convention; no FHS migration needed.
         std::path::PathBuf::from("/usr/local/var/numa")
     }
 }
+
+/// Extracted as a pure function so the migration logic is unit-testable
+/// without touching the real filesystem.
+#[cfg(any(target_os = "linux", test))]
+fn resolve_linux_data_dir(legacy_exists: bool, fhs_exists: bool) -> &'static str {
+    if legacy_exists && !fhs_exists {
+        "/usr/local/var/numa"
+    } else {
+        "/var/lib/numa"
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn linux_data_dir_fresh_install_uses_fhs() {
+        assert_eq!(resolve_linux_data_dir(false, false), "/var/lib/numa");
+    }
+
+    #[test]
+    fn linux_data_dir_upgrading_install_keeps_legacy() {
+        // Migration must keep legacy so the user doesn't lose their CA on upgrade.
+        assert_eq!(resolve_linux_data_dir(true, false), "/usr/local/var/numa");
+    }
+
+    #[test]
+    fn linux_data_dir_after_migration_uses_fhs() {
+        assert_eq!(resolve_linux_data_dir(true, true), "/var/lib/numa");
+    }
+
+    #[test]
+    fn linux_data_dir_only_fhs_uses_fhs() {
+        assert_eq!(resolve_linux_data_dir(false, true), "/var/lib/numa");
+    }
+}

src/main.rs

@@ -223,7 +223,11 @@ async fn main() -> numa::Result<()> {
         ) {
             Ok(tls_config) => Some(ArcSwap::from(tls_config)),
             Err(e) => {
-                log::warn!("TLS setup failed, HTTPS proxy disabled: {}", e);
+                if let Some(advisory) = numa::tls::try_data_dir_advisory(&e, &resolved_data_dir) {
+                    eprint!("{}", advisory);
+                } else {
+                    log::warn!("TLS setup failed, HTTPS proxy disabled: {}", e);
+                }
                 None
             }
         }
@@ -231,8 +235,21 @@ async fn main() -> numa::Result<()> {
         None
     };
 
+    let socket = match UdpSocket::bind(&config.server.bind_addr).await {
+        Ok(s) => s,
+        Err(e) => {
+            if let Some(advisory) =
+                numa::system_dns::try_port53_advisory(&config.server.bind_addr, &e)
+            {
+                eprint!("{}", advisory);
+                std::process::exit(1);
+            }
+            return Err(e.into());
+        }
+    };
+
     let ctx = Arc::new(ServerCtx {
-        socket: UdpSocket::bind(&config.server.bind_addr).await?,
+        socket,
         zone_map: build_zone_map(&config.zones)?,
         cache: RwLock::new(DnsCache::new(
             config.cache.max_entries,

src/system_dns.rs

@@ -2,6 +2,17 @@ use std::net::SocketAddr;
 
 use log::info;
 
+fn print_recursive_hint() {
+    let is_recursive = crate::config::load_config("numa.toml")
+        .map(|c| c.config.upstream.mode == crate::config::UpstreamMode::Recursive)
+        .unwrap_or(false);
+    if !is_recursive {
+        eprintln!("  Want full DNS sovereignty? Add to numa.toml:");
+        eprintln!("    [upstream]");
+        eprintln!("    mode = \"recursive\"\n");
+    }
+}
+
 fn is_loopback_or_stub(addr: &str) -> bool {
     matches!(addr, "127.0.0.1" | "127.0.0.53" | "0.0.0.0" | "::1" | "")
 }
@@ -46,6 +57,60 @@ pub fn discover_system_dns() -> SystemDnsInfo {
     }
 }
 
+/// Advisory for port-53 bind failures (EADDRINUSE or EACCES); `None`
+/// if not applicable so the caller can fall back to the raw error.
+pub fn try_port53_advisory(bind_addr: &str, err: &std::io::Error) -> Option<String> {
+    if !is_port_53(bind_addr) {
+        return None;
+    }
+    let (title, cause) = match err.kind() {
+        std::io::ErrorKind::AddrInUse => (
+            "port 53 is already in use",
+            "Another process is already bound to port 53. On Linux this is\n  \
+             typically systemd-resolved; on Windows, the DNS Client service.",
+        ),
+        std::io::ErrorKind::PermissionDenied => (
+            "permission denied",
+            "Port 53 is privileged — binding it requires root on Linux/macOS\n  \
+             or Administrator on Windows.",
+        ),
+        _ => return None,
+    };
+    let o = "\x1b[1;38;2;192;98;58m"; // bold orange
+    let r = "\x1b[0m";
+    Some(format!(
+        "
+{o}Numa{r} — cannot bind to {bind_addr}: {title}.
+
+  {cause}
+
+  Fix — pick one:
+
+    1. Install Numa as the system resolver (frees port 53):
+
+         sudo numa install       (on Windows, run as Administrator)
+
+    2. Run on a non-privileged port for testing.
+       Create ~/.config/numa/numa.toml with:
+
+         [server]
+         bind_addr = \"127.0.0.1:5354\"
+         api_port  = 5380
+
+       Then run:  numa
+       Test with: dig @127.0.0.1 -p 5354 example.com
+
+"
+    ))
+}
+
+fn is_port_53(bind_addr: &str) -> bool {
+    bind_addr
+        .parse::<SocketAddr>()
+        .map(|s| s.port() == 53)
+        .unwrap_or(false)
+}
+
 #[cfg(target_os = "macos")]
 fn discover_macos() -> SystemDnsInfo {
     use log::{debug, warn};
@@ -174,6 +239,9 @@ fn discover_linux() -> SystemDnsInfo {
     let default_upstream = if let Some(ns) = upstream {
         info!("detected system upstream: {}", ns);
         Some(ns)
+    } else if let Some(ns) = resolvectl_dns_server() {
+        info!("detected system upstream via resolvectl: {}", ns);
+        Some(ns)
     } else {
         // Fallback to backup from a previous `numa install`
         let backup = {
@@ -214,7 +282,18 @@ fn discover_linux() -> SystemDnsInfo {
     }
 }
 
-/// Parse resolv.conf in a single pass, extracting both the first non-loopback
+/// Yield each `nameserver` address from resolv.conf content. No filtering —
+/// callers decide what counts as a real upstream.
+#[cfg(any(target_os = "linux", test))]
+fn iter_nameservers(content: &str) -> impl Iterator<Item = &str> {
+    content.lines().filter_map(|line| {
+        let mut parts = line.split_whitespace();
+        (parts.next() == Some("nameserver")).then_some(())?;
+        parts.next()
+    })
+}
+
+/// Parse resolv.conf in a single pass, extracting the first non-loopback
 /// nameserver and all search domains.
 #[cfg(target_os = "linux")]
 fn parse_resolv_conf(path: &str) -> (Option<String>, Vec<String>) {
@@ -222,19 +301,13 @@ fn parse_resolv_conf(path: &str) -> (Option<String>, Vec<String>) {
         Ok(t) => t,
         Err(_) => return (None, Vec::new()),
     };
-    let mut upstream = None;
+    let upstream = iter_nameservers(&text)
+        .find(|ns| !is_loopback_or_stub(ns))
+        .map(str::to_string);
     let mut search_domains = Vec::new();
     for line in text.lines() {
         let line = line.trim();
-        if line.starts_with("nameserver") {
+        if line.starts_with("search") || line.starts_with("domain") {
-            if upstream.is_none() {
-                if let Some(ns) = line.split_whitespace().nth(1) {
-                    if !is_loopback_or_stub(ns) {
-                        upstream = Some(ns.to_string());
-                    }
-                }
-            }
-        } else if line.starts_with("search") || line.starts_with("domain") {
             for domain in line.split_whitespace().skip(1) {
                 search_domains.push(domain.to_string());
             }
@@ -243,6 +316,21 @@ fn parse_resolv_conf(path: &str) -> (Option<String>, Vec<String>) {
     (upstream, search_domains)
 }
 
+/// True if the resolv.conf *content* appears to be written by numa itself,
+/// or has no real upstream — either way, it's not a safe source of truth
+/// for a backup.
+#[cfg(any(target_os = "linux", test))]
+fn resolv_conf_is_numa_managed(content: &str) -> bool {
+    content.contains("Generated by Numa") || !resolv_conf_has_real_upstream(content)
+}
+
+/// True if the resolv.conf content has at least one non-loopback, non-stub
+/// nameserver. An all-loopback resolv.conf is self-referential.
+#[cfg(any(target_os = "linux", test))]
+fn resolv_conf_has_real_upstream(content: &str) -> bool {
+    iter_nameservers(content).any(|ns| !is_loopback_or_stub(ns))
+}
+
 /// Query resolvectl for the real upstream DNS server (e.g. VPC resolver on AWS).
 #[cfg(target_os = "linux")]
 fn resolvectl_dns_server() -> Option<String> {
@@ -526,9 +614,19 @@ fn enable_dnscache() {
         .status();
 }
 
+/// True if the backup map has at least one real upstream (non-loopback, non-stub).
+#[cfg(any(windows, test))]
+fn backup_has_real_upstream_windows(
+    interfaces: &std::collections::HashMap<String, WindowsInterfaceDns>,
+) -> bool {
+    interfaces
+        .values()
+        .any(|iface| iface.servers.iter().any(|s| !is_loopback_or_stub(s)))
+}
+
 #[cfg(windows)]
 fn install_windows() -> Result<(), String> {
-    let interfaces = get_windows_interfaces()?;
+    let mut interfaces = get_windows_interfaces()?;
     if interfaces.is_empty() {
         return Err("no active network interfaces found".to_string());
     }
@@ -538,9 +636,30 @@ fn install_windows() -> Result<(), String> {
         std::fs::create_dir_all(parent)
             .map_err(|e| format!("failed to create {}: {}", parent.display(), e))?;
     }
-    let json = serde_json::to_string_pretty(&interfaces)
+
-        .map_err(|e| format!("failed to serialize backup: {}", e))?;
+    // Preserve an existing useful backup rather than overwriting it with
-    std::fs::write(&path, json).map_err(|e| format!("failed to write backup: {}", e))?;
+    // numa-managed state (which would be self-referential after uninstall).
+    let existing: Option<std::collections::HashMap<String, WindowsInterfaceDns>> =
+        std::fs::read_to_string(&path)
+            .ok()
+            .and_then(|json| serde_json::from_str(&json).ok());
+    let has_useful_existing = existing
+        .as_ref()
+        .map(backup_has_real_upstream_windows)
+        .unwrap_or(false);
+
+    if has_useful_existing {
+        eprintln!("  Existing DNS backup preserved at {}", path.display());
+    } else {
+        // Filter loopback/stub addresses before saving so a fresh backup
+        // captured from already-numa-managed state isn't self-referential.
+        for iface in interfaces.values_mut() {
+            iface.servers.retain(|s| !is_loopback_or_stub(s));
+        }
+        let json = serde_json::to_string_pretty(&interfaces)
+            .map_err(|e| format!("failed to serialize backup: {}", e))?;
+        std::fs::write(&path, json).map_err(|e| format!("failed to write backup: {}", e))?;
+    }
 
     for name in interfaces.keys() {
         let status = std::process::Command::new("netsh")
@@ -570,16 +689,17 @@ fn install_windows() -> Result<(), String> {
     let needs_reboot = disable_dnscache()?;
     register_autostart();
 
-    eprintln!("\n  Original DNS saved to {}", path.display());
+    eprintln!();
+    if !has_useful_existing {
+        eprintln!("  Original DNS saved to {}", path.display());
+    }
     eprintln!("  Run 'numa uninstall' to restore.\n");
     if needs_reboot {
         eprintln!("  *** Reboot required. Numa will start automatically. ***\n");
     } else {
         eprintln!("  Numa will start automatically on next boot.\n");
     }
-    eprintln!("  Want full DNS sovereignty? Add to numa.toml:");
+    print_recursive_hint();
-    eprintln!("    [upstream]");
-    eprintln!("    mode = \"recursive\"\n");
     Ok(())
 }
 
@@ -754,27 +874,60 @@ fn get_dns_servers(service: &str) -> Result<Vec<String>, String> {
     }
 }
 
+/// True if the backup map has at least one real upstream (non-loopback, non-stub).
+/// An all-loopback backup is self-referential — restoring it is a no-op.
+#[cfg(any(target_os = "macos", test))]
+fn backup_has_real_upstream_macos(
+    servers: &std::collections::HashMap<String, Vec<String>>,
+) -> bool {
+    servers
+        .values()
+        .any(|list| list.iter().any(|s| !is_loopback_or_stub(s)))
+}
+
 #[cfg(target_os = "macos")]
 fn install_macos() -> Result<(), String> {
     use std::collections::HashMap;
 
     let services = get_network_services()?;
-    let mut original: HashMap<String, Vec<String>> = HashMap::new();
-
-    // Save current DNS for each service
-    for service in &services {
-        let servers = get_dns_servers(service)?;
-        original.insert(service.clone(), servers);
-    }
-
-    // Save backup
     let dir = numa_data_dir();
     std::fs::create_dir_all(&dir)
         .map_err(|e| format!("failed to create {}: {}", dir.display(), e))?;
 
-    let json = serde_json::to_string_pretty(&original)
+    // If a useful backup already exists (at least one non-loopback upstream),
-        .map_err(|e| format!("failed to serialize backup: {}", e))?;
+    // preserve it — overwriting would destroy the original DNS state when
-    std::fs::write(backup_path(), json).map_err(|e| format!("failed to write backup: {}", e))?;
+    // re-installing on top of a numa-managed configuration.
+    let existing_backup: Option<HashMap<String, Vec<String>>> =
+        std::fs::read_to_string(backup_path())
+            .ok()
+            .and_then(|json| serde_json::from_str(&json).ok());
+    let has_useful_existing = existing_backup
+        .as_ref()
+        .map(backup_has_real_upstream_macos)
+        .unwrap_or(false);
+
+    if has_useful_existing {
+        eprintln!(
+            "  Existing DNS backup preserved at {}",
+            backup_path().display()
+        );
+    } else {
+        // Capture fresh, filtering out loopback and stub addresses so we
+        // never record a self-referential backup.
+        let mut original: HashMap<String, Vec<String>> = HashMap::new();
+        for service in &services {
+            let servers: Vec<String> = get_dns_servers(service)?
+                .into_iter()
+                .filter(|s| !is_loopback_or_stub(s))
+                .collect();
+            original.insert(service.clone(), servers);
+        }
+
+        let json = serde_json::to_string_pretty(&original)
+            .map_err(|e| format!("failed to serialize backup: {}", e))?;
+        std::fs::write(backup_path(), json)
+            .map_err(|e| format!("failed to write backup: {}", e))?;
+    }
 
     // Set DNS to 127.0.0.1 and add "numa" search domain for each service
     for service in &services {
@@ -795,7 +948,10 @@ fn install_macos() -> Result<(), String> {
             .status();
     }
 
-    eprintln!("\n  Original DNS saved to {}", backup_path().display());
+    eprintln!();
+    if !has_useful_existing {
+        eprintln!("  Original DNS saved to {}", backup_path().display());
+    }
     eprintln!("  Run 'sudo numa uninstall' to restore.\n");
 
     Ok(())
@@ -990,14 +1146,23 @@ fn install_service_macos() -> Result<(), String> {
     std::fs::write(PLIST_DEST, plist)
         .map_err(|e| format!("failed to write {}: {}", PLIST_DEST, e))?;
 
-    // Load the service first so numa is listening before DNS redirect
+    // Modern launchctl API: explicitly tear down any existing in-memory
+    // state, then bootstrap fresh from the on-disk plist. The deprecated
+    // `load -w` returns exit 0 even when it cannot actually reload (label
+    // already in launchd state), silently leaving the daemon running a
+    // stale binary path after `numa install` rewrites the plist on disk —
+    // which is exactly what `brew upgrade numa` does.
+    let _ = std::process::Command::new("launchctl")
+        .args(["bootout", "system", PLIST_DEST])
+        .status();
+
     let status = std::process::Command::new("launchctl")
-        .args(["load", "-w", PLIST_DEST])
+        .args(["bootstrap", "system", PLIST_DEST])
         .status()
         .map_err(|e| format!("failed to run launchctl: {}", e))?;
 
     if !status.success() {
-        return Err("launchctl load failed".to_string());
+        return Err("launchctl bootstrap failed".to_string());
     }
 
     // Wait for numa to be ready before redirecting DNS
@@ -1010,7 +1175,7 @@ fn install_service_macos() -> Result<(), String> {
     if !api_up {
         // Service failed to start — don't redirect DNS to a dead endpoint
         let _ = std::process::Command::new("launchctl")
-            .args(["unload", PLIST_DEST])
+            .args(["bootout", "system", PLIST_DEST])
             .status();
         return Err(
             "numa service did not start (port 53 may be in use). Service unloaded.".to_string(),
@@ -1025,9 +1190,7 @@ fn install_service_macos() -> Result<(), String> {
     eprintln!("  Numa will auto-start on boot and restart if killed.");
     eprintln!("  Logs: /usr/local/var/log/numa.log");
     eprintln!("  Run 'sudo numa uninstall' to restore original DNS.\n");
-    eprintln!("  Want full DNS sovereignty? Add to numa.toml:");
+    print_recursive_hint();
-    eprintln!("    [upstream]");
-    eprintln!("    mode = \"recursive\"\n");
     Ok(())
 }
 
@@ -1038,22 +1201,25 @@ fn uninstall_service_macos() -> Result<(), String> {
         eprintln!("  warning: failed to restore system DNS: {}", e);
     }
 
-    // Remove plist first so service won't restart on boot even if unload fails
+    // Bootout the service from launchd's in-memory state BEFORE removing
-    if let Err(e) = std::fs::remove_file(PLIST_DEST) {
+    // the plist. The modern API needs the file path as the specifier;
-        if e.kind() != std::io::ErrorKind::NotFound {
+    // doing this in the wrong order would leave the service loaded in
-            return Err(format!("failed to remove {}: {}", PLIST_DEST, e));
+    // memory until reboot. (Deprecated `unload -w` had the same issue.)
+    let bootout_status = std::process::Command::new("launchctl")
+        .args(["bootout", "system", PLIST_DEST])
+        .status();
+    if let Ok(s) = bootout_status {
+        if !s.success() {
+            eprintln!(
+                "  warning: launchctl bootout returned non-zero (service may not have been loaded)"
+            );
         }
     }
 
-    // Unload the service
+    // Remove plist so the service won't restart on boot
-    let status = std::process::Command::new("launchctl")
+    if let Err(e) = std::fs::remove_file(PLIST_DEST) {
-        .args(["unload", "-w", PLIST_DEST])
+        if e.kind() != std::io::ErrorKind::NotFound {
-        .status();
+            return Err(format!("failed to remove {}: {}", PLIST_DEST, e));
-    if let Ok(s) = status {
-        if !s.success() {
-            eprintln!(
-                "  warning: launchctl unload returned non-zero (service may still be running)"
-            );
         }
     }
 
@@ -1132,11 +1298,31 @@ fn install_linux() -> Result<(), String> {
             .map_err(|e| format!("failed to create {}: {}", parent.display(), e))?;
     }
 
-    // Back up current resolv.conf (ignore NotFound)
+    // Back up current resolv.conf, but never overwrite a useful existing
-    match std::fs::copy(resolv, &backup) {
+    // backup with a numa-managed file — that would leave uninstall with
-        Ok(_) => eprintln!("  Saved /etc/resolv.conf to {}", backup.display()),
+    // nothing to restore to.
-        Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
+    let current = std::fs::read_to_string(resolv).ok();
-        Err(e) => return Err(format!("failed to backup /etc/resolv.conf: {}", e)),
+    let current_is_numa_managed = current
+        .as_deref()
+        .map(resolv_conf_is_numa_managed)
+        .unwrap_or(false);
+    let existing_backup_is_useful = std::fs::read_to_string(&backup)
+        .ok()
+        .as_deref()
+        .map(resolv_conf_has_real_upstream)
+        .unwrap_or(false);
+
+    if existing_backup_is_useful {
+        eprintln!(
+            "  Existing resolv.conf backup preserved at {}",
+            backup.display()
+        );
+    } else if current_is_numa_managed {
+        eprintln!("  warning: /etc/resolv.conf is already numa-managed; no fresh backup written");
+    } else if let Some(content) = current.as_deref() {
+        std::fs::write(&backup, content)
+            .map_err(|e| format!("failed to backup /etc/resolv.conf: {}", e))?;
+        eprintln!("  Saved /etc/resolv.conf to {}", backup.display());
     }
 
     if resolv
@@ -1209,9 +1395,7 @@ fn install_service_linux() -> Result<(), String> {
     eprintln!("  Numa will auto-start on boot and restart if killed.");
     eprintln!("  Logs: journalctl -u numa -f");
     eprintln!("  Run 'sudo numa uninstall' to restore original DNS.\n");
-    eprintln!("  Want full DNS sovereignty? Add to numa.toml:");
+    print_recursive_hint();
-    eprintln!("    [upstream]");
-    eprintln!("    mode = \"recursive\"\n");
     Ok(())
 }
 
@@ -1278,102 +1462,209 @@ fn run_systemctl(args: &[&str]) -> Result<(), String> {
 
 // --- CA trust management ---
 
+/// One Linux trust-store backend (Debian, Fedora pki, Arch p11-kit).
+#[cfg(target_os = "linux")]
+struct LinuxTrustStore {
+    name: &'static str,
+    anchor_dir: &'static str,
+    anchor_file: &'static str,
+    refresh_install: &'static [&'static str],
+    refresh_uninstall: &'static [&'static str],
+}
+
+// If you change this table, update tests/docker/install-trust.sh to match —
+// it asserts the same paths/commands against real distro images.
+#[cfg(target_os = "linux")]
+const LINUX_TRUST_STORES: &[LinuxTrustStore] = &[
+    // Debian / Ubuntu / Mint
+    LinuxTrustStore {
+        name: "debian",
+        anchor_dir: "/usr/local/share/ca-certificates",
+        anchor_file: "numa-local-ca.crt",
+        refresh_install: &["update-ca-certificates"],
+        refresh_uninstall: &["update-ca-certificates", "--fresh"],
+    },
+    // Fedora / RHEL / CentOS / SUSE (p11-kit via update-ca-trust wrapper)
+    LinuxTrustStore {
+        name: "pki",
+        anchor_dir: "/etc/pki/ca-trust/source/anchors",
+        anchor_file: "numa-local-ca.pem",
+        refresh_install: &["update-ca-trust", "extract"],
+        refresh_uninstall: &["update-ca-trust", "extract"],
+    },
+    // Arch / Manjaro (raw p11-kit)
+    LinuxTrustStore {
+        name: "p11kit",
+        anchor_dir: "/etc/ca-certificates/trust-source/anchors",
+        anchor_file: "numa-local-ca.pem",
+        refresh_install: &["trust", "extract-compat"],
+        refresh_uninstall: &["trust", "extract-compat"],
+    },
+];
+
+#[cfg(target_os = "linux")]
+fn detect_linux_trust_store() -> Option<&'static LinuxTrustStore> {
+    LINUX_TRUST_STORES
+        .iter()
+        .find(|s| std::path::Path::new(s.anchor_dir).is_dir())
+}
+
 fn trust_ca() -> Result<(), String> {
-    let ca_path = crate::data_dir().join("ca.pem");
+    let ca_path = crate::data_dir().join(crate::tls::CA_FILE_NAME);
     if !ca_path.exists() {
         return Err("CA not generated yet — start numa first to create certificates".into());
     }
 
     #[cfg(target_os = "macos")]
-    {
+    let result = trust_ca_macos(&ca_path);
-        let status = std::process::Command::new("security")
-            .args([
-                "add-trusted-cert",
-                "-d",
-                "-r",
-                "trustRoot",
-                "-k",
-                "/Library/Keychains/System.keychain",
-            ])
-            .arg(&ca_path)
-            .status()
-            .map_err(|e| format!("security: {}", e))?;
-        if !status.success() {
-            return Err("security add-trusted-cert failed".into());
-        }
-        eprintln!("  Trusted Numa CA in system keychain");
-    }
-
     #[cfg(target_os = "linux")]
-    {
+    let result = trust_ca_linux(&ca_path);
-        let dest = std::path::Path::new("/usr/local/share/ca-certificates/numa-local-ca.crt");
+    #[cfg(windows)]
-        std::fs::copy(&ca_path, dest).map_err(|e| format!("copy CA: {}", e))?;
+    let result = trust_ca_windows(&ca_path);
-        let status = std::process::Command::new("update-ca-certificates")
+    #[cfg(not(any(target_os = "macos", target_os = "linux", windows)))]
-            .status()
+    let result = Err::<(), String>("CA trust not supported on this OS".to_string());
-            .map_err(|e| format!("update-ca-certificates: {}", e))?;
-        if !status.success() {
-            return Err("update-ca-certificates failed".into());
-        }
-        eprintln!("  Trusted Numa CA system-wide");
-    }
 
-    #[cfg(not(any(target_os = "macos", target_os = "linux")))]
+    result
-    {
-        Err("CA trust not supported on this OS".into())
-    }
-
-    #[cfg(any(target_os = "macos", target_os = "linux"))]
-    Ok(())
 }
 
 fn untrust_ca() -> Result<(), String> {
-    let ca_path = crate::data_dir().join("ca.pem");
-
     #[cfg(target_os = "macos")]
+    let result = untrust_ca_macos();
+    #[cfg(target_os = "linux")]
+    let result = untrust_ca_linux();
+    #[cfg(windows)]
+    let result = untrust_ca_windows();
+    #[cfg(not(any(target_os = "macos", target_os = "linux", windows)))]
+    let result = Ok::<(), String>(());
+
+    result
+}
+
+#[cfg(target_os = "macos")]
+fn trust_ca_macos(ca_path: &std::path::Path) -> Result<(), String> {
+    let status = std::process::Command::new("security")
+        .args([
+            "add-trusted-cert",
+            "-d",
+            "-r",
+            "trustRoot",
+            "-k",
+            "/Library/Keychains/System.keychain",
+        ])
+        .arg(ca_path)
+        .status()
+        .map_err(|e| format!("security: {}", e))?;
+    if !status.success() {
+        return Err("security add-trusted-cert failed".into());
+    }
+    eprintln!("  Trusted Numa CA in system keychain");
+    Ok(())
+}
+
+#[cfg(target_os = "macos")]
+fn untrust_ca_macos() -> Result<(), String> {
+    if let Ok(out) = std::process::Command::new("security")
+        .args([
+            "find-certificate",
+            "-c",
+            crate::tls::CA_COMMON_NAME,
+            "-a",
+            "-Z",
+            "/Library/Keychains/System.keychain",
+        ])
+        .output()
     {
-        // Find all Numa CA certs by hash and delete each one
+        let stdout = String::from_utf8_lossy(&out.stdout);
-        if let Ok(out) = std::process::Command::new("security")
+        for line in stdout.lines() {
-            .args([
+            if let Some(hash) = line.strip_prefix("SHA-1 hash: ") {
-                "find-certificate",
+                let hash = hash.trim();
-                "-c",
+                let _ = std::process::Command::new("security")
-                "Numa Local CA",
+                    .args([
-                "-a",
+                        "delete-certificate",
-                "-Z",
+                        "-Z",
-                "/Library/Keychains/System.keychain",
+                        hash,
-            ])
+                        "/Library/Keychains/System.keychain",
-            .output()
+                    ])
-        {
+                    .output();
-            let stdout = String::from_utf8_lossy(&out.stdout);
-            for line in stdout.lines() {
-                if let Some(hash) = line.strip_prefix("SHA-1 hash: ") {
-                    let hash = hash.trim();
-                    let _ = std::process::Command::new("security")
-                        .args([
-                            "delete-certificate",
-                            "-Z",
-                            hash,
-                            "/Library/Keychains/System.keychain",
-                        ])
-                        .output();
-                }
             }
         }
-        eprintln!("  Removed Numa CA from system keychain");
     }
+    eprintln!("  Removed Numa CA from system keychain");
+    Ok(())
+}
 
-    #[cfg(target_os = "linux")]
+#[cfg(target_os = "linux")]
-    {
+fn trust_ca_linux(ca_path: &std::path::Path) -> Result<(), String> {
-        let dest = std::path::Path::new("/usr/local/share/ca-certificates/numa-local-ca.crt");
+    let store = detect_linux_trust_store().ok_or_else(|| {
-        if dest.exists() {
+        let names: Vec<&str> = LINUX_TRUST_STORES.iter().map(|s| s.name).collect();
-            let _ = std::fs::remove_file(dest);
+        format!(
-            let _ = std::process::Command::new("update-ca-certificates")
+            "no supported CA trust store found (tried: {}). \
-                .arg("--fresh")
+             Please report at https://github.com/razvandimescu/numa/issues",
-                .status();
+            names.join(", ")
-            eprintln!("  Removed Numa CA from system trust store");
+        )
+    })?;
+
+    let dest = std::path::Path::new(store.anchor_dir).join(store.anchor_file);
+    std::fs::copy(ca_path, &dest).map_err(|e| format!("copy CA to {}: {}", dest.display(), e))?;
+
+    run_refresh(store.name, store.refresh_install)?;
+    eprintln!("  Trusted Numa CA system-wide ({})", store.name);
+    Ok(())
+}
+
+#[cfg(target_os = "linux")]
+fn untrust_ca_linux() -> Result<(), String> {
+    let Some(store) = detect_linux_trust_store() else {
+        return Ok(());
+    };
+
+    let dest = std::path::Path::new(store.anchor_dir).join(store.anchor_file);
+    match std::fs::remove_file(&dest) {
+        Ok(()) => {
+            let _ = run_refresh(store.name, store.refresh_uninstall);
+            eprintln!("  Removed Numa CA from system trust store ({})", store.name);
         }
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
+        Err(_) => {} // best-effort uninstall
     }
+    Ok(())
+}
 
-    let _ = ca_path; // suppress unused warning on other platforms
+#[cfg(target_os = "linux")]
+fn run_refresh(store_name: &str, argv: &[&str]) -> Result<(), String> {
+    let (cmd, args) = argv
+        .split_first()
+        .expect("refresh command must be non-empty");
+    let status = std::process::Command::new(cmd)
+        .args(args)
+        .status()
+        .map_err(|e| format!("{} ({}): {}", cmd, store_name, e))?;
+    if !status.success() {
+        return Err(format!("{} ({}) failed", cmd, store_name));
+    }
+    Ok(())
+}
+
+#[cfg(windows)]
+fn trust_ca_windows(ca_path: &std::path::Path) -> Result<(), String> {
+    let status = std::process::Command::new("certutil")
+        .args(["-addstore", "-f", "Root"])
+        .arg(ca_path)
+        .status()
+        .map_err(|e| format!("certutil: {}", e))?;
+    if !status.success() {
+        return Err("certutil -addstore Root failed (run as Administrator?)".into());
+    }
+    eprintln!("  Trusted Numa CA in Windows Root store");
+    Ok(())
+}
+
+#[cfg(windows)]
+fn untrust_ca_windows() -> Result<(), String> {
+    let _ = std::process::Command::new("certutil")
+        .args(["-delstore", "Root", crate::tls::CA_COMMON_NAME])
+        .status();
+    eprintln!("  Removed Numa CA from Windows Root store");
     Ok(())
 }
 
@@ -1432,6 +1723,82 @@ Wireless LAN adapter Wi-Fi:
         assert!(!result.contains("{{exe_path}}"));
     }
 
+    #[test]
+    fn macos_backup_real_upstream_detection() {
+        use std::collections::HashMap;
+        let mut map: HashMap<String, Vec<String>> = HashMap::new();
+
+        // Empty backup → no real upstream
+        assert!(!backup_has_real_upstream_macos(&map));
+
+        // All-loopback backup → still no real upstream (the bug case)
+        map.insert("Wi-Fi".into(), vec!["127.0.0.1".into()]);
+        map.insert("Ethernet".into(), vec!["::1".into()]);
+        assert!(!backup_has_real_upstream_macos(&map));
+
+        // One real entry → useful
+        map.insert("Tailscale".into(), vec!["192.168.1.1".into()]);
+        assert!(backup_has_real_upstream_macos(&map));
+    }
+
+    #[test]
+    fn windows_backup_filters_loopback() {
+        use std::collections::HashMap;
+        let mut map: HashMap<String, WindowsInterfaceDns> = HashMap::new();
+
+        // Empty backup → no real upstream
+        assert!(!backup_has_real_upstream_windows(&map));
+
+        // All-loopback backup → still no real upstream (the bug case)
+        map.insert(
+            "Wi-Fi".into(),
+            WindowsInterfaceDns {
+                dhcp: false,
+                servers: vec!["127.0.0.1".into()],
+            },
+        );
+        map.insert(
+            "Ethernet".into(),
+            WindowsInterfaceDns {
+                dhcp: false,
+                servers: vec!["::1".into(), "0.0.0.0".into()],
+            },
+        );
+        assert!(!backup_has_real_upstream_windows(&map));
+
+        // One real entry alongside loopback → useful
+        map.insert(
+            "Ethernet 2".into(),
+            WindowsInterfaceDns {
+                dhcp: false,
+                servers: vec!["192.168.1.1".into()],
+            },
+        );
+        assert!(backup_has_real_upstream_windows(&map));
+    }
+
+    #[test]
+    fn resolv_conf_real_upstream_detection() {
+        let real = "nameserver 192.168.1.1\nsearch lan\n";
+        assert!(resolv_conf_has_real_upstream(real));
+        assert!(!resolv_conf_is_numa_managed(real));
+
+        let self_ref = "nameserver 127.0.0.1\nsearch numa\n";
+        assert!(!resolv_conf_has_real_upstream(self_ref));
+        assert!(resolv_conf_is_numa_managed(self_ref));
+
+        let numa_marker =
+            "# Generated by Numa — run 'sudo numa uninstall' to restore\nnameserver 127.0.0.1\nsearch numa\n";
+        assert!(resolv_conf_is_numa_managed(numa_marker));
+
+        let systemd_stub = "nameserver 127.0.0.53\noptions edns0\n";
+        assert!(!resolv_conf_has_real_upstream(systemd_stub));
+
+        let mixed = "nameserver 127.0.0.1\nnameserver 1.1.1.1\n";
+        assert!(resolv_conf_has_real_upstream(mixed));
+        assert!(!resolv_conf_is_numa_managed(mixed));
+    }
+
     #[test]
     fn parse_ipconfig_skips_disconnected() {
         let sample = "\
@@ -1448,4 +1815,43 @@ Wireless LAN adapter Wi-Fi:
         assert_eq!(result.len(), 1);
         assert!(result.contains_key("Wi-Fi"));
     }
+
+    #[test]
+    fn try_port53_advisory_addr_in_use() {
+        let err = std::io::Error::from(std::io::ErrorKind::AddrInUse);
+        let msg = try_port53_advisory("0.0.0.0:53", &err).expect("should advise on port 53");
+        assert!(msg.contains("cannot bind to"));
+        assert!(msg.contains("already in use"));
+        assert!(msg.contains("numa install"));
+        assert!(msg.contains("bind_addr"));
+    }
+
+    #[test]
+    fn try_port53_advisory_permission_denied() {
+        let err = std::io::Error::from(std::io::ErrorKind::PermissionDenied);
+        let msg = try_port53_advisory("0.0.0.0:53", &err).expect("should advise on port 53");
+        assert!(msg.contains("cannot bind to"));
+        assert!(msg.contains("permission denied"));
+        assert!(msg.contains("numa install"));
+        assert!(msg.contains("bind_addr"));
+    }
+
+    #[test]
+    fn try_port53_advisory_skips_non_53_ports() {
+        let err = std::io::Error::from(std::io::ErrorKind::AddrInUse);
+        assert!(try_port53_advisory("127.0.0.1:5354", &err).is_none());
+        assert!(try_port53_advisory("[::]:853", &err).is_none());
+    }
+
+    #[test]
+    fn try_port53_advisory_skips_unrelated_error_kinds() {
+        let err = std::io::Error::from(std::io::ErrorKind::NotFound);
+        assert!(try_port53_advisory("0.0.0.0:53", &err).is_none());
+    }
+
+    #[test]
+    fn try_port53_advisory_skips_malformed_bind_addr() {
+        let err = std::io::Error::from(std::io::ErrorKind::AddrInUse);
+        assert!(try_port53_advisory("not-an-address", &err).is_none());
+    }
 }

src/tls.rs

@@ -5,7 +5,9 @@ use std::sync::Arc;
 use log::{info, warn};
 
 use crate::ctx::ServerCtx;
-use rcgen::{BasicConstraints, CertificateParams, DnType, IsCa, KeyPair, KeyUsagePurpose, SanType};
+use rcgen::{
+    BasicConstraints, CertificateParams, DnType, IsCa, Issuer, KeyPair, KeyUsagePurpose, SanType,
+};
 use rustls::pki_types::{CertificateDer, PrivateKeyDer, PrivatePkcs8KeyDer};
 use rustls::ServerConfig;
 use time::{Duration, OffsetDateTime};
@@ -13,6 +15,13 @@ use time::{Duration, OffsetDateTime};
 const CA_VALIDITY_DAYS: i64 = 3650; // 10 years
 const CERT_VALIDITY_DAYS: i64 = 365; // 1 year
 
+/// Common Name on Numa's local CA. Referenced by trust-store helpers
+/// (`security`, `certutil`) when locating the cert for removal.
+pub const CA_COMMON_NAME: &str = "Numa Local CA";
+
+/// Filename of the CA certificate inside the data dir.
+pub const CA_FILE_NAME: &str = "ca.pem";
+
 /// Collect all service + LAN peer names and regenerate the TLS cert.
 pub fn regenerate_tls(ctx: &ServerCtx) {
     let tls = match &ctx.tls_config {
@@ -33,6 +42,40 @@ pub fn regenerate_tls(ctx: &ServerCtx) {
     }
 }
 
+/// Advisory for TLS-setup failures caused by a non-writable data dir;
+/// `None` if not applicable so the caller can fall back to the raw error.
+pub fn try_data_dir_advisory(err: &crate::Error, data_dir: &Path) -> Option<String> {
+    let io_err = err.downcast_ref::<std::io::Error>()?;
+    if io_err.kind() != std::io::ErrorKind::PermissionDenied {
+        return None;
+    }
+    let o = "\x1b[1;38;2;192;98;58m";
+    let r = "\x1b[0m";
+    Some(format!(
+        "
+{o}Numa{r} — HTTPS proxy disabled: cannot write TLS CA to {}.
+
+  The data directory is not writable by the current user. Numa needs
+  to persist a local Certificate Authority there to serve .numa over
+  HTTPS. DNS resolution and plain-HTTP proxy continue to work.
+
+  Fix — pick one:
+
+    1. Install Numa as the system resolver (sets up a writable data dir):
+
+         sudo numa install       (on Windows, run as Administrator)
+
+    2. Point data_dir at a path you can write.
+       Create ~/.config/numa/numa.toml with:
+
+         [server]
+         data_dir = \"/path/you/can/write\"
+
+",
+        data_dir.display()
+    ))
+}
+
 /// Build a TLS config with a cert covering all provided service names.
 /// Wildcards under single-label TLDs (*.numa) are rejected by browsers,
 /// so we list each service explicitly as a SAN.
@@ -46,8 +89,8 @@ pub fn build_tls_config(
     alpn: Vec<Vec<u8>>,
     data_dir: &Path,
 ) -> crate::Result<Arc<ServerConfig>> {
-    let (ca_cert, ca_key) = ensure_ca(data_dir)?;
+    let (ca_der, issuer) = ensure_ca(data_dir)?;
-    let (cert_chain, key) = generate_service_cert(&ca_cert, &ca_key, tld, service_names)?;
+    let (cert_chain, key) = generate_service_cert(&ca_der, &issuer, tld, service_names)?;
 
     // Ensure a crypto provider is installed (rustls needs one)
     let _ = rustls::crypto::ring::default_provider().install_default();
@@ -65,18 +108,20 @@ pub fn build_tls_config(
     Ok(Arc::new(config))
 }
 
-fn ensure_ca(dir: &Path) -> crate::Result<(rcgen::Certificate, KeyPair)> {
+fn ensure_ca(dir: &Path) -> crate::Result<(CertificateDer<'static>, Issuer<'static, KeyPair>)> {
     let ca_key_path = dir.join("ca.key");
-    let ca_cert_path = dir.join("ca.pem");
+    let ca_cert_path = dir.join(CA_FILE_NAME);
 
     if ca_key_path.exists() && ca_cert_path.exists() {
         let key_pem = std::fs::read_to_string(&ca_key_path)?;
         let cert_pem = std::fs::read_to_string(&ca_cert_path)?;
         let key_pair = KeyPair::from_pem(&key_pem)?;
-        let params = CertificateParams::from_ca_cert_pem(&cert_pem)?;
+        let ca_der = rustls_pemfile::certs(&mut cert_pem.as_bytes())
-        let cert = params.self_signed(&key_pair)?;
+            .next()
+            .ok_or("empty CA PEM file")??;
+        let issuer = Issuer::from_ca_cert_der(&ca_der, key_pair)?;
         info!("loaded CA from {:?}", ca_cert_path);
-        return Ok((cert, key_pair));
+        return Ok((ca_der, issuer));
     }
 
     // Generate new CA
@@ -86,7 +131,7 @@ fn ensure_ca(dir: &Path) -> crate::Result<(rcgen::Certificate, KeyPair)> {
     let mut params = CertificateParams::default();
     params
         .distinguished_name
-        .push(DnType::CommonName, "Numa Local CA");
+        .push(DnType::CommonName, CA_COMMON_NAME);
     params.is_ca = IsCa::Ca(BasicConstraints::Unconstrained);
     params.key_usages = vec![KeyUsagePurpose::KeyCertSign, KeyUsagePurpose::CrlSign];
     params.not_before = OffsetDateTime::now_utc();
@@ -104,14 +149,16 @@ fn ensure_ca(dir: &Path) -> crate::Result<(rcgen::Certificate, KeyPair)> {
     }
 
     info!("generated CA at {:?}", ca_cert_path);
-    Ok((cert, key_pair))
+    let ca_der = cert.der().clone();
+    let issuer = Issuer::new(params, key_pair);
+    Ok((ca_der, issuer))
 }
 
 /// Generate a cert with explicit SANs for each service name.
 /// Always regenerated at startup (~5ms) — no disk caching needed.
 fn generate_service_cert(
-    ca_cert: &rcgen::Certificate,
+    ca_der: &CertificateDer<'static>,
-    ca_key: &KeyPair,
+    issuer: &Issuer<'_, KeyPair>,
     tld: &str,
     service_names: &[String],
 ) -> crate::Result<(Vec<CertificateDer<'static>>, PrivateKeyDer<'static>)> {
@@ -146,7 +193,7 @@ fn generate_service_cert(
     params.not_before = OffsetDateTime::now_utc();
     params.not_after = OffsetDateTime::now_utc() + Duration::days(CERT_VALIDITY_DAYS);
 
-    let cert = params.signed_by(&key_pair, ca_cert, ca_key)?;
+    let cert = params.signed_by(&key_pair, issuer)?;
 
     info!(
         "generated TLS cert for: {}",
@@ -157,9 +204,39 @@ fn generate_service_cert(
             .join(", ")
     );
 
-    let cert_der = CertificateDer::from(cert.der().to_vec());
+    let cert_der = cert.der().clone();
-    let ca_der = CertificateDer::from(ca_cert.der().to_vec());
+    let ca_cert_der = ca_der.clone();
     let key_der = PrivateKeyDer::Pkcs8(PrivatePkcs8KeyDer::from(key_pair.serialize_der()));
 
-    Ok((vec![cert_der, ca_der], key_der))
+    Ok((vec![cert_der, ca_cert_der], key_der))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::path::PathBuf;
+
+    #[test]
+    fn try_data_dir_advisory_permission_denied() {
+        let err: crate::Error =
+            Box::new(std::io::Error::from(std::io::ErrorKind::PermissionDenied));
+        let path = PathBuf::from("/usr/local/var/numa");
+        let msg = try_data_dir_advisory(&err, &path).expect("should advise");
+        assert!(msg.contains("HTTPS proxy disabled"));
+        assert!(msg.contains("/usr/local/var/numa"));
+        assert!(msg.contains("numa install"));
+        assert!(msg.contains("data_dir"));
+    }
+
+    #[test]
+    fn try_data_dir_advisory_skips_other_io_kinds() {
+        let err: crate::Error = Box::new(std::io::Error::from(std::io::ErrorKind::NotFound));
+        assert!(try_data_dir_advisory(&err, &PathBuf::from("/x")).is_none());
+    }
+
+    #[test]
+    fn try_data_dir_advisory_skips_non_io_errors() {
+        let err: crate::Error = "rcgen failure".into();
+        assert!(try_data_dir_advisory(&err, &PathBuf::from("/x")).is_none());
+    }
 }

tests/docker/install-trust.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+#
+# Cross-distro CA trust contract test for issue #35.
+#
+# Runs the exact shell commands `src/system_dns.rs::trust_ca_linux` would run
+# on each Linux trust-store family (Debian, Fedora pki, Arch p11-kit), and
+# asserts the certificate ends up in (and is removed from) the system bundle.
+#
+# This is a contract test, not an integration test: it doesn't drive the Rust
+# code (that would need systemd-in-container). It verifies the assumptions in
+# `LINUX_TRUST_STORES` against the real distro behavior. If you change that
+# table in src/system_dns.rs, update the per-distro cases below to match.
+#
+# Requirements: docker, openssl (host).
+# Usage:        ./tests/docker/install-trust.sh
+
+set -euo pipefail
+
+cd "$(dirname "$0")/../.."
+
+GREEN="\033[32m"; RED="\033[31m"; RESET="\033[0m"
+
+# Self-signed CA fixture, mounted into each container as ca.pem.
+# basicConstraints=CA:TRUE is required — without it, Debian's
+# update-ca-certificates silently skips the cert during bundle build.
+FIXTURE_DIR=$(mktemp -d)
+trap 'rm -rf "$FIXTURE_DIR"' EXIT
+openssl req -x509 -newkey rsa:2048 -nodes -days 1 \
+    -keyout "$FIXTURE_DIR/ca.key" \
+    -out    "$FIXTURE_DIR/ca.pem" \
+    -subj   "/CN=Numa Local CA Test $(date +%s)" \
+    -addext "basicConstraints=critical,CA:TRUE" \
+    -addext "keyUsage=critical,keyCertSign,cRLSign" >/dev/null 2>&1
+
+# Distro bundles store certs differently — Debian writes raw PEM only,
+# Fedora prepends "# CN" comment headers, Arch via extract-compat is
+# raw PEM. To detect cert presence uniformly we grep for a deterministic
+# substring of the base64 body (first base64 line is unique per cert).
+CERT_TAG=$(sed -n '2p' "$FIXTURE_DIR/ca.pem")
+
+PASSED=0; FAILED=0
+
+run_case() {
+    local distro="$1"; shift
+    local image="$1"; shift
+    local platform="$1"; shift
+    local script="$1"
+
+    printf "── %s (%s) ──\n" "$distro" "$image"
+    if docker run --rm \
+        --platform "$platform" \
+        --security-opt seccomp=unconfined \
+        -e CERT_TAG="$CERT_TAG" \
+        -e DEBIAN_FRONTEND=noninteractive \
+        -v "$FIXTURE_DIR/ca.pem:/fixture/ca.pem:ro" \
+        "$image" bash -c "$script"; then
+        printf "${GREEN}✓${RESET} %s\n\n" "$distro"
+        PASSED=$((PASSED + 1))
+    else
+        printf "${RED}✗${RESET} %s\n\n" "$distro"
+        FAILED=$((FAILED + 1))
+    fi
+}
+
+# Debian / Ubuntu / Mint — anchor: /usr/local/share/ca-certificates/*.crt
+run_case "debian" "debian:stable" "linux/amd64" '
+    set -e
+    apt-get update -qq
+    apt-get install -qq -y ca-certificates >/dev/null
+    install -m 0644 /fixture/ca.pem /usr/local/share/ca-certificates/numa-local-ca.crt
+    update-ca-certificates >/dev/null 2>&1
+    grep -q "$CERT_TAG" /etc/ssl/certs/ca-certificates.crt
+    echo "  install: cert present in bundle"
+    rm /usr/local/share/ca-certificates/numa-local-ca.crt
+    update-ca-certificates --fresh >/dev/null 2>&1
+    if grep -q "$CERT_TAG" /etc/ssl/certs/ca-certificates.crt; then
+        echo "  uninstall: cert STILL present (regression)" >&2
+        exit 1
+    fi
+    echo "  uninstall: cert removed from bundle"
+'
+
+# Fedora / RHEL / CentOS / SUSE — anchor: /etc/pki/ca-trust/source/anchors/*.pem
+run_case "fedora" "fedora:latest" "linux/amd64" '
+    set -e
+    dnf install -q -y ca-certificates >/dev/null
+    install -m 0644 /fixture/ca.pem /etc/pki/ca-trust/source/anchors/numa-local-ca.pem
+    update-ca-trust extract
+    grep -q "$CERT_TAG" /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem
+    echo "  install: cert present in bundle"
+    rm /etc/pki/ca-trust/source/anchors/numa-local-ca.pem
+    update-ca-trust extract
+    if grep -q "$CERT_TAG" /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem; then
+        echo "  uninstall: cert STILL present (regression)" >&2
+        exit 1
+    fi
+    echo "  uninstall: cert removed from bundle"
+'
+
+# Arch / Manjaro — anchor: /etc/ca-certificates/trust-source/anchors/*.pem
+# archlinux:latest is x86_64-only; --platform forces emulation on Apple Silicon.
+run_case "arch" "archlinux:latest" "linux/amd64" '
+    set -e
+    # pacman 7+ filters syscalls in its own sandbox; disable for Rosetta/qemu emulation.
+    sed -i "s/^#DisableSandboxSyscalls/DisableSandboxSyscalls/" /etc/pacman.conf
+    pacman -Sy --noconfirm --needed ca-certificates p11-kit >/dev/null 2>&1
+    install -m 0644 /fixture/ca.pem /etc/ca-certificates/trust-source/anchors/numa-local-ca.pem
+    trust extract-compat
+    grep -q "$CERT_TAG" /etc/ssl/certs/ca-certificates.crt
+    echo "  install: cert present in bundle"
+    rm /etc/ca-certificates/trust-source/anchors/numa-local-ca.pem
+    trust extract-compat
+    if grep -q "$CERT_TAG" /etc/ssl/certs/ca-certificates.crt; then
+        echo "  uninstall: cert STILL present (regression)" >&2
+        exit 1
+    fi
+    echo "  uninstall: cert removed from bundle"
+'
+
+printf "── summary ──\n"
+printf "  ${GREEN}passed${RESET}: %d\n" "$PASSED"
+printf "  ${RED}failed${RESET}: %d\n" "$FAILED"
+[ "$FAILED" -eq 0 ]

tests/docker/smoke-arch.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+#
+# Arch Linux compatibility smoke test.
+#
+# Builds numa from source inside an archlinux:latest container, runs it
+# in forward mode on port 5354, and verifies a single DNS query returns
+# an A record. Validates the "Arch compatible" claim end-to-end before
+# release announcements.
+#
+# Dogfooding: the test numa forwards to the host's running numa via
+# host.docker.internal (Docker Desktop's host gateway). This avoids the
+# Docker NAT/UDP issues with public resolvers and exercises the realistic
+# numa-on-numa shape. Requires the host to be running numa on port 53.
+#
+# First run is slow (~8-12 min): image pull + pacman + cold cargo build.
+# No caching across runs.
+#
+# Requirements: docker, host running numa on 0.0.0.0:53
+# Usage:        ./tests/docker/smoke-arch.sh
+
+set -euo pipefail
+
+cd "$(dirname "$0")/../.."
+
+GREEN="\033[32m"; RED="\033[31m"; RESET="\033[0m"
+
+# Precondition: the test numa-on-arch forwards to the host numa as its
+# upstream (dogfood pattern). Fail fast with a clear error if there is
+# no working DNS on the host, rather than letting the dig inside the
+# container time out with "deadline has elapsed".
+if ! dig @127.0.0.1 google.com A +short +time=1 +tries=1 >/dev/null 2>&1; then
+    printf "${RED}error:${RESET} host numa is not answering on 127.0.0.1:53\n" >&2
+    echo "  This test forwards to the host numa via host.docker.internal." >&2
+    echo "  Start numa on the host first (sudo numa install), then rerun." >&2
+    exit 1
+fi
+
+echo "── building + running numa on archlinux:latest ──"
+echo "  (first run is slow: image pull + pacman + cold cargo build, ~8-12 min)"
+echo
+
+docker run --rm \
+    --platform linux/amd64 \
+    --security-opt seccomp=unconfined \
+    -v "$PWD:/src:ro" \
+    -v numa-arch-cargo:/root/.cargo \
+    -v numa-arch-target:/work/target \
+    archlinux:latest bash -c '
+    set -e
+
+    # pacman 7+ filters syscalls in its own sandbox; disable for Rosetta/qemu
+    sed -i "s/^#DisableSandboxSyscalls/DisableSandboxSyscalls/" /etc/pacman.conf
+
+    echo "── pacman: installing build + runtime deps ──"
+    pacman -Sy --noconfirm --needed rust gcc pkgconf cmake make perl bind 2>&1 | tail -3
+    echo
+
+    # Copy source to a writable workdir, skipping target/ + .git so we
+    # do not pull in the host (macOS) build artifacts.
+    mkdir -p /work
+    tar -C /src --exclude=./target --exclude=./.git -cf - . | tar -C /work -xf -
+    cd /work
+
+    echo "── cargo build --release --locked ──"
+    cargo build --release --locked 2>&1 | tail -5
+    echo
+
+    # Dogfood: forward to the host numa via host.docker.internal.
+    # numa parses upstream.address as a literal SocketAddr, so we resolve
+    # the hostname to an IPv4 address first (force v4 — getent hosts may
+    # return IPv6 first, and IPv6 addresses need bracketed addr:port form).
+    HOST_IP=$(getent ahostsv4 host.docker.internal | awk "/STREAM/ {print \$1; exit}")
+    if [ -z "$HOST_IP" ]; then
+        echo "  ✗ could not resolve host.docker.internal to IPv4 (not on Docker Desktop?)"
+        exit 1
+    fi
+    echo "── starting numa on :5354 (forward to host numa at $HOST_IP:53) ──"
+    # Intentionally NOT setting [server] data_dir — we want to exercise the
+    # default code path (data_dir() → daemon_data_dir() → /var/lib/numa) so
+    # the FHS-path assertion below verifies the live wiring, not just the
+    # unit-tested helper.
+    cat > /tmp/numa.toml <<EOF
+[server]
+bind_addr = "127.0.0.1:5354"
+api_port = 5381
+
+[upstream]
+mode = "forward"
+address = "$HOST_IP"
+port = 53
+EOF
+
+    ./target/release/numa /tmp/numa.toml > /tmp/numa.log 2>&1 &
+    NUMA_PID=$!
+
+    # Poll for readiness — numa is ready when it answers a query
+    READY=0
+    for i in 1 2 3 4 5 6 7 8; do
+        sleep 1
+        if dig @127.0.0.1 -p 5354 google.com A +short +time=1 +tries=1 2>/dev/null \
+            | grep -qE "^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$"; then
+            READY=1
+            break
+        fi
+    done
+
+    if [ "$READY" -ne 1 ]; then
+        echo "  ✗ numa did not return an A record after 8s"
+        echo "  numa log:"
+        cat /tmp/numa.log
+        kill $NUMA_PID 2>/dev/null || true
+        exit 1
+    fi
+
+    echo "── dig @127.0.0.1 -p 5354 google.com A ──"
+    ANSWER=$(dig @127.0.0.1 -p 5354 google.com A +short +time=2 +tries=1)
+    echo "$ANSWER" | sed "s/^/  /"
+
+    kill $NUMA_PID 2>/dev/null || true
+
+    # FHS path assertion: the default data dir on Linux must be /var/lib/numa
+    # (not the legacy /usr/local/var/numa). The CA cert generated at startup
+    # is the canonical proof that numa wrote to the right place.
+    echo
+    echo "── FHS path check ──"
+    if [ -f /var/lib/numa/ca.pem ]; then
+        echo "  ✓ CA cert at /var/lib/numa/ca.pem (FHS path)"
+    else
+        echo "  ✗ CA cert NOT at /var/lib/numa/ca.pem"
+        echo "  ls /var/lib/numa/:"
+        ls -la /var/lib/numa/ 2>&1 | sed "s/^/    /"
+        echo "  ls /usr/local/var/numa/:"
+        ls -la /usr/local/var/numa/ 2>&1 | sed "s/^/    /"
+        exit 1
+    fi
+    if [ -e /usr/local/var/numa ]; then
+        echo "  ✗ legacy path /usr/local/var/numa unexpectedly exists on a fresh container"
+        exit 1
+    fi
+    echo "  ✓ legacy path /usr/local/var/numa absent (fresh install used FHS)"
+
+    echo
+    echo "  ✓ numa built, ran, answered a forward query, and used the FHS data dir on Arch"
+'
+
+echo
+printf "${GREEN}── smoke-arch passed ──${RESET}\n"

tests/docker/smoke-port53.sh

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+#
+# Port-53 conflict advisory integration test.
+#
+# Builds numa from source inside a debian:bookworm container, pre-binds
+# port 53 with a UDP socket, then runs numa bare (default bind_addr
+# 0.0.0.0:53). Verifies:
+#   - process exits with code 1
+#   - stderr contains the advisory ("cannot bind to")
+#   - stderr contains both fix suggestions ("numa install", "bind_addr")
+#
+# This is the end-to-end test for the fix in:
+#   src/main.rs — AddrInUse match arm → eprint advisory + process::exit(1)
+#
+# No systemd-resolved needed — the conflict is simulated by a Python
+# UDP socket held open before numa starts.
+#
+# Requirements: docker
+# Usage:        ./tests/docker/smoke-port53.sh
+
+set -euo pipefail
+
+cd "$(dirname "$0")/../.."
+
+GREEN="\033[32m"; RED="\033[31m"; RESET="\033[0m"
+
+pass() { printf "  ${GREEN}✓${RESET} %s\n" "$1"; }
+fail() { printf "  ${RED}✗${RESET} %s\n" "$1"; printf "    %s\n" "$2"; FAILED=$((FAILED+1)); }
+FAILED=0
+
+echo "── smoke-port53: building + testing numa on debian:bookworm ──"
+echo "  (first run is slow: image pull + cold cargo build, ~5-8 min)"
+echo
+
+OUTPUT=$(docker run --rm \
+    --platform linux/amd64 \
+    -v "$PWD:/src:ro" \
+    -v numa-port53-cargo:/root/.cargo \
+    -v numa-port53-target:/work/target \
+    debian:bookworm bash -c '
+set -e
+
+apt-get update -qq && apt-get install -y -qq curl build-essential python3 2>&1 | tail -3
+
+# Install rustup if not already in the cargo cache volume
+if ! command -v cargo &>/dev/null; then
+    curl -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal --quiet
+fi
+. "$HOME/.cargo/env"
+
+# Copy source to a writable workdir
+mkdir -p /work
+tar -C /src --exclude=./target --exclude=./.git -cf - . | tar -C /work -xf -
+cd /work
+
+echo "── cargo build --release --locked ──"
+cargo build --release --locked 2>&1 | tail -5
+echo
+
+# Write the holder script to a file to avoid quoting hell.
+# Holds port 53 until killed — no sleep race.
+cat > /tmp/hold53.py << '"'"'PYEOF'"'"'
+import socket, signal
+s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 0)
+s.bind(("", 53))
+signal.pause()
+PYEOF
+
+python3 /tmp/hold53.py &
+HOLDER_PID=$!
+
+# Verify the holder is actually up before proceeding
+sleep 0.3
+if ! kill -0 $HOLDER_PID 2>/dev/null; then
+    echo "holder_failed=1"
+    exit 1
+fi
+
+echo "── running numa with port 53 already bound ──"
+# timeout 5: guards against numa not exiting (advisory not fired, bug present)
+# Capture stderr to a file so the exit code is not clobbered by || or $()
+set +e
+timeout 5 ./target/release/numa > /tmp/numa-stderr.txt 2>&1
+EXIT_CODE=$?
+set -e
+STDERR=$(cat /tmp/numa-stderr.txt)
+
+kill $HOLDER_PID 2>/dev/null || true
+
+echo "exit_code=$EXIT_CODE"
+printf "%s" "$STDERR" | sed "s/^/  numa: /"
+' 2>&1)
+
+echo "$OUTPUT"
+
+echo
+echo "── assertions ──"
+
+if echo "$OUTPUT" | grep -q "holder_failed=1"; then
+    echo "  SETUP FAILED: could not pre-bind port 53 inside container"
+    exit 1
+fi
+
+EXIT_CODE=$(echo "$OUTPUT" | grep '^exit_code=' | cut -d= -f2)
+
+if [ "${EXIT_CODE:-}" = "1" ]; then
+    pass "exits with code 1"
+else
+    fail "exits with code 1" "got: exit_code=${EXIT_CODE:-<missing>}"
+fi
+
+if echo "$OUTPUT" | grep -q "cannot bind to"; then
+    pass "advisory printed to stderr"
+else
+    fail "advisory printed to stderr" "stderr did not contain 'cannot bind to'"
+fi
+
+if echo "$OUTPUT" | grep -q "numa install"; then
+    pass "advisory offers 'sudo numa install'"
+else
+    fail "advisory offers 'sudo numa install'" "not found in output"
+fi
+
+if echo "$OUTPUT" | grep -q "bind_addr"; then
+    pass "advisory offers non-privileged port alternative"
+else
+    fail "advisory offers non-privileged port alternative" "'bind_addr' not found in output"
+fi
+
+echo
+if [ "$FAILED" -eq 0 ]; then
+    printf "${GREEN}── smoke-port53 passed ──${RESET}\n"
+    exit 0
+else
+    printf "${RED}── smoke-port53 failed ($FAILED assertion(s)) ──${RESET}\n"
+    exit 1
+fi

tests/manual/install-trust-macos.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+#
+# Manual macOS CA trust contract test.
+#
+# Mirrors src/system_dns.rs::trust_ca_macos / untrust_ca_macos by running
+# the same `security` shell commands against a fixture cert with a unique
+# CN. Safe to run alongside a production numa install:
+#
+#   - Test cert CN = "Numa Local CA Test <pid-ts>", always strictly longer
+#     than the production CN "Numa Local CA". `security find-certificate -c`
+#     does substring matching, so the test's search for $TEST_CN can never
+#     match the production cert (the search term is longer than the prod CN).
+#   - All deletes use `delete-certificate -Z <hash>`, which only touches the
+#     cert with that exact hash. Production and test certs have different
+#     hashes by construction (different key material), so the delete cannot
+#     reach the production cert even if a CN search somehow returned both.
+#
+# Mutates the System keychain (briefly). Cleans up on success or interrupt.
+# Requires sudo for `security add-trusted-cert` and `delete-certificate`.
+#
+# Usage: ./tests/manual/install-trust-macos.sh
+
+set -euo pipefail
+
+if [[ "$OSTYPE" != darwin* ]]; then
+    echo "This test is macOS-only." >&2
+    exit 1
+fi
+
+GREEN="\033[32m"; RED="\033[31m"; RESET="\033[0m"
+
+# Production constant from src/tls.rs::CA_COMMON_NAME — keep in sync.
+PROD_CN="Numa Local CA"
+KEYCHAIN="/Library/Keychains/System.keychain"
+
+# Notice if production numa is already installed. We proceed regardless —
+# see header for why coexistence is safe (unique CN + by-hash deletion).
+if security find-certificate -c "$PROD_CN" "$KEYCHAIN" >/dev/null 2>&1; then
+    echo "  note: production '$PROD_CN' detected — proceeding alongside (test cert can't touch it)"
+    echo
+fi
+
+# Unique CN ensures the test cert can never collide with production.
+TEST_CN="Numa Local CA Test $$-$(date +%s)"
+FIXTURE_DIR=$(mktemp -d)
+
+cleanup() {
+    # Best-effort: remove any test certs by hash if still present.
+    if security find-certificate -c "$TEST_CN" "$KEYCHAIN" >/dev/null 2>&1; then
+        echo "  cleanup: removing leftover test cert"
+        security find-certificate -c "$TEST_CN" -a -Z "$KEYCHAIN" 2>/dev/null \
+            | awk '/^SHA-1 hash:/ {print $NF}' \
+            | while read -r hash; do
+                sudo security delete-certificate -Z "$hash" "$KEYCHAIN" >/dev/null 2>&1 || true
+            done
+    fi
+    rm -rf "$FIXTURE_DIR"
+}
+trap cleanup EXIT
+
+echo "── generating fixture CA ──"
+openssl req -x509 -newkey rsa:2048 -nodes -days 1 \
+    -keyout "$FIXTURE_DIR/ca.key" \
+    -out    "$FIXTURE_DIR/ca.pem" \
+    -subj   "/CN=$TEST_CN" \
+    -addext "basicConstraints=critical,CA:TRUE" \
+    -addext "keyUsage=critical,keyCertSign,cRLSign" >/dev/null 2>&1
+echo "  CN: $TEST_CN"
+echo
+
+echo "── trust step (mirrors trust_ca_macos) ──"
+sudo security add-trusted-cert -d -r trustRoot -k "$KEYCHAIN" "$FIXTURE_DIR/ca.pem"
+if security find-certificate -c "$TEST_CN" "$KEYCHAIN" >/dev/null 2>&1; then
+    printf "  ${GREEN}✓${RESET} test cert found in keychain\n"
+else
+    printf "  ${RED}✗${RESET} test cert NOT found after add-trusted-cert\n"
+    exit 1
+fi
+echo
+
+echo "── untrust step (mirrors untrust_ca_macos) ──"
+security find-certificate -c "$TEST_CN" -a -Z "$KEYCHAIN" 2>/dev/null \
+    | awk '/^SHA-1 hash:/ {print $NF}' \
+    | while read -r hash; do
+        sudo security delete-certificate -Z "$hash" "$KEYCHAIN" >/dev/null
+    done
+if security find-certificate -c "$TEST_CN" "$KEYCHAIN" >/dev/null 2>&1; then
+    printf "  ${RED}✗${RESET} test cert STILL present after delete (regression)\n"
+    exit 1
+fi
+printf "  ${GREEN}✓${RESET} test cert removed from keychain\n"
+echo
+
+printf "${GREEN}all checks passed${RESET}\n"