Release 0.2.0: DNS rebinding protection, dnscrypt-proxy over DoH support, DNS stamps generator, Query logs card expansion & block reasons

.github/workflows/integration_tests.yml

@@ -1,4 +1,4 @@
-name: Smoke / integration tests
+name: Smoke / backend E2E tests
 
 on:
   push:
@@ -30,7 +30,9 @@ jobs:
           python_certs_path=`python -m certifi`
           echo "Python CA store path: ${python_certs_path}"
           echo "PYTHON_CERTS_PATH=${python_certs_path}" >> $GITHUB_ENV
-          echo "IVPN_CERT_PATH=./certs/moddns_dev_development_CA.crt" >> $GITHUB_ENV
+          # Absolute: consumed both from the repo root (cert setup step below) and
+          # from tests/ (pytest CWD, via libs/dns_lib.py for DoT/DoQ verification).
+          echo "IVPN_CERT_PATH=${GITHUB_WORKSPACE}/certs/moddns_dev_development_CA.crt" >> $GITHUB_ENV
 
       - name: SSL cert setup
         run: |
@@ -41,6 +43,14 @@ jobs:
         run: |
           sudo echo "127.0.0.1 moddns.dev" | sudo tee -a /etc/hosts
 
+      # dnscrypt-proxy client for the DoH-stamp E2E test (dns_tests/test_dnscrypt_proxy.py).
+      # The pinned version + URL + sha256 live in tests/libs/dnscrypt_proxy.py (single
+      # source of truth); this invokes that module to download + checksum-verify the
+      # binary and export its path. Fails loudly here; the test itself skips if unset.
+      - name: Install dnscrypt-proxy client (pinned)
+        run: |
+          echo "MODDNS_DNSCRYPT_PROXY_BIN=$(cd tests && python -m libs.dnscrypt_proxy)" >> "$GITHUB_ENV"
+
       - name: Prepare .env from sample
         run: |
           if [ ! -f tests/.env ]; then
@@ -64,5 +74,11 @@ jobs:
             fi
           done < tests/.env
 
-      - name: Run integration tests
+      - name: Run backend E2E tests
         run: cd tests/; make test_ci
+
+      # Destructive (stops/starts the Redis replica container), so it is
+      # excluded from the default invocation via pytest addopts and runs
+      # here as its own session with a fresh compose stack.
+      - name: Run Redis failover backend E2E tests
+        run: cd tests/; make test_failover

Makefile

@@ -27,8 +27,7 @@ down: ## Stops all of the services.
 	-f compose.dnscheck.yml \
 	-f compose.sdns.yml \
 	-f compose.knot.yml \
-	down; \
-	docker kill -a
+	down
 
 up_dns: ## Starts the DNS services (both recursors: sdns + knot).
 	docker compose \
@@ -137,7 +136,7 @@ gen_ts_client: ## Generates the typescript client from swagger spec.
 	rm -rf app/src/api/client/ || true
 	docker run -v ${CWD}:/app -w /app/api/docs --user $$(id -u):$$(id -g) --rm openapitools/openapi-generator-cli generate --package-name idns -i swagger.yaml -g typescript-axios -o /app/app/src/api/client --skip-validate-spec
 
-build_tests_image: ## Builds the smoke / integration tests image.
+build_tests_image: ## Builds the smoke / backend E2E tests image.
 	docker build -f tests/Dockerfile -t dns_tests:latest .
 
 dev_tests: ## Starts the development tests docker container.

README-dev.md

@@ -41,7 +41,7 @@ mkcert automatically installs its root CA into the system trust store, so browse
 
 > [!NOTE]
 > The certificates committed under `certs/` (`moddns.dev+4.pem` / `moddns.dev+4-key.pem`, signed by
-> `moddns_dev_development_CA.crt`) are what the integration tests use. mkcert is only needed if you want a
+> `moddns_dev_development_CA.crt`) are what the backend E2E tests use. mkcert is only needed if you want a
 > CA your **browser** trusts automatically for local dev. See `certs/README.md` for the regeneration recipe.
 
 ## Local DNS overrides with dnsmasq

README.md

@@ -20,71 +20,77 @@ modDNS is a full-stack DNS security platform that combines encrypted DNS transpo
 modDNS is built as a microservices architecture with the following components:
 
 ```
-┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
-│              │───▶│              │───▶│              │───▶│              │
-│  Web Client  │    │ Nginx Proxy  │    │   Frontend   │    │ API Server   │
-│              │    │              │    │   (React)    │    │              │
-└──────────────┘    └──────────────┘    └──────────────┘    └──────┬───────┘
-                                                                   │
-                                                        ┌──────────┴──────────┐
-                                                        │                     │
-                                                        ▼                     ▼
-                                                ┌──────────────┐      ┌──────────────┐
-                                                │              │      │              │
-                                                │    Redis     │      │   MongoDB    │
-                                                │  (Caching)   │      │  (Storage)   │
-                                                └──────────────┘      └──────────────┘
-                                                        ▲
-                                                        │
-┌──────────────┐    ┌──────────────┐                    │
-│              │───▶│              │────────────────────┘
-│ DNS Clients  │    │  DNS Proxy   │
-│              │    │              │
-└──────────────┘    └──────┬───────┘
-                           │
-                           ▼
-                    ┌──────────────┐
-                    │              │
-                    │ DNS Resolver │
-                    │(SDNS/Unbound)│
-                    └──────────────┘
+┌──────────────┐   ┌──────────────┐   ┌──────────────┐
+│  Web Client  │──▶│    Nginx     │──▶│   Frontend   │
+│  (browser)   │   │ (:80, static)│   │ (React SPA)  │
+└──────┬───────┘   └──────────────┘   └──────────────┘
+       │ REST API (:3000)
+       ▼
+┌──────────────┐   ┌──────────────────────┐
+│  API Server  │──▶│        Redis         │
+│  (Go/Fiber)  │   │ (master + 2 replicas │
+└──────┬───────┘   │     + sentinel)      │
+       │           └──────────▲───────────┘
+       ▼                      │ profile/rule reads
+┌──────────────┐              │ (dns replica)
+│   MongoDB    │   ┌──────────┴───┐   ┌──────────────────┐
+│              │◀──│  DNS Proxy   │──▶│    Recursors     │
+└──────────────┘   │  (TLS term.) │   │  (sdns + Knot)   │
+   query logs &    └──────▲───────┘   └──────────────────┘
+   statistics             │ DoH / DoT / DoQ
+                   ┌──────┴───────┐
+                   │ DNS Clients  │
+                   └──────────────┘
 ```
 
+Additional services not shown above:
+
+- **blocklists** — periodically downloads and ingests filter lists (AdGuard, Hagezi, OISD, StevenBlack, …) into Redis/MongoDB.
+- **dnscheck** — standalone DNS diagnostics microservice with GeoIP (MaxMind) lookup.
+
+Note that the DNS proxy terminates TLS for the encrypted DNS transports itself; Nginx only serves the web frontend. The API is exposed directly on port 3000.
+
 ## Core Technologies
 
 **Backend Services**
 - Go & Fiber for high-performance APIs
-- MongoDB for persistent storage of accounts, profiles, and telemetry
-- Redis for caching and background jobs
-- SDNS/Unbound for DNS resolution and policy enforcement
+- MongoDB for persistent storage of accounts, profiles, query logs, and statistics
+- Redis (master + two replicas + sentinel) for caching and distributing profile configuration to the proxy
+- sdns and Knot Resolver as bundled recursors (Knot is the default)
 
 **Frontend**
 - React + TypeScript SPA (shadcn/ui & Radix UI component system)
 - Tailwind CSS for utility-first styling
+- PWA with offline support and in-app update flow
 
 **Infrastructure**
 - Docker & Docker Compose for local orchestration
-- Nginx as the public ingress & TLS termination layer
+- Nginx serving the web frontend (the DNS proxy terminates TLS for encrypted DNS transports itself)
 - GitHub Actions for CI/CD automation
 
 ## Features
 
 **Encrypted DNS**
-- DNS over HTTPS (DoH)
-- DNS over TLS (DoT)
-- DNS over QUIC (DoQ)
+- DNS over HTTPS (DoH), DNS over TLS (DoT), DNS over QUIC (DoQ)
+- Per-profile DNS stamps (`sdns://`) calculator and dnscrypt-proxy (via DoH) setup support
+- DNSSEC validation (per profile, enabled by default)
 
 **Content Filtering**
 - Built-in blocklists (ads, malware, trackers)
-- Custom allow/deny rules per profile
+- Custom allow/deny rules per profile — domains and IPs, with rule groups and precedence
+- Service-based blocking presets backed by ASN lookup (Google, Meta, TikTok, Netflix, …)
+- DNS rebinding protection
 
 **User & Profile Management**
 - Multi-profile accounts with individualized policies
-- MFA, email verification, and secure password workflows
+- MFA (TOTP and WebAuthn/passkeys), email verification, and secure password workflows
+- Profile settings export & import
+- In-app announcements
 
 **Observability**
-- Near real-time DNS query logging
-- Exportable analytics for auditing
+- Near real-time DNS query logging with outcome classification and quick-rule creation from log entries (opt-in, configurable retention from 1 hour to 1 month)
+- Statistics and exportable analytics for auditing
+- Prometheus metrics exposed by the proxy
 
 **Apple Device Integration**
 - Managed `.mobileconfig` profiles
@@ -95,12 +101,27 @@ modDNS is built as a microservices architecture with the following components:
 ### Prerequisites
 - Docker & Docker Compose
 - Make (for the provided automation scripts)
-- Node.js 18+ and npm (for the React application)
-- Go 1.25+ (for backend services)
+- Node.js 22+ and npm (for the React application)
+- Go 1.25.8+ (toolchain version pinned in the `go.mod` files)
+- Python 3.11 (for the backend E2E tests)
 - mkcert (optional, for trusted local TLS certificates)
 
 ### Quick Start
 
+Before the first `make up`, create the required (gitignored) environment files from the tracked samples and provide the GeoLite2 databases:
+
+```bash
+# 1. Environment files
+cp api/.env.sample api/.env
+cp proxy/.env.sample proxy/.env
+cp dnscheck/.env.sample dnscheck/.env
+
+# 2. MaxMind GeoLite2 databases (mounted by the proxy and dnscheck)
+#    Place them under bootstrap/GeoLite2-ASN/ and bootstrap/GeoLite2-City/
+```
+
+Then:
+
 ```bash
 make up          # Build and start every service stack
 make down        # Stop and remove containers
@@ -120,6 +141,9 @@ Certificates for local HTTPS access live in `certs/`. You can either generate th
 | `proxy/`  | DNS proxy implementation
 | `tests/`  | Integration and regression suites (pytest + testcontainers)
 | `bootstrap/`, `compose.*.yml` | Docker-compose orchestration and bootstrap assets
+| `certs/`  | Development TLS certificates and local CA
+| `scripts/` | Helper scripts
+| `.github/` | CI workflows (GitHub Actions), lint configs, issue/PR templates
 
 ## Development Workflow
 
@@ -132,36 +156,39 @@ npm run lint
 npm run tsc
 npm run build
 ```
+`npm run dev` sources `app/env/.env.local`, which is gitignored — create it first (see the tracked `app/env/.env.production`, `.env.staging`, and `.env.test` for reference).
 
 ### API service (`api/`)
 ```bash
 cd api
 go mod tidy
 make test
 ```
-(See `api/Makefile` for additional targets like `make lint`, `make dev`, etc.)
+(See `api/Makefile` for additional targets like `make lint`, `make gow` (live reload), `make swag`, and `make mockery`. From the repo root, `make dev_api` runs live reload inside the running container.)
 
 ### Proxy service (`proxy/`)
 ```bash
-cd api
+cd proxy
 go mod tidy
 make test
 ```
-(See `proxy/Makefile` for additional targets like `make lint`, `make dev`, etc.)
+(See `proxy/Makefile` for additional targets like `make lint`, `make gow`, and `make mockery`. From the repo root, `make dev_proxy` runs live reload inside the running container.)
 
-### Integration tests (`tests/`)
+### Backend E2E tests (`tests/`)
 ```bash
-python -m venv tests/venv
-source tests/venv/bin/activate
-pip install -r tests/requirements.txt
-make test_ci     # spins up containers via testcontainers
+cd tests
+python3.11 -m venv venv
+source venv/bin/activate
+make install_test_dependencies
+make test_ci        # spins up the stack via testcontainers
+make test_failover  # destructive Redis failover tests (excluded from test_ci, run separately)
 ```
 
 ## Testing
 
 - **Web client**: `npm run lint && npm run tsc && npm run test` (unit) and `npm run test:e2e` (Playwright)
 - **Go services**: `go test ./...` inside each Go module (`api/`, `blocklists/`, `proxy/`, etc.)
-- **Integration**: `source tests/venv/bin/activate && make test_ci`
+- **Integration**: `cd tests && source venv/bin/activate && make test_ci`
 - **Static analysis**: `make lint` in relevant directories (Go linters + ESLint)
 
 ## Contributing

api/api/dnsstamp.go

@@ -0,0 +1,54 @@
+package api
+
+import (
+	"strings"
+
+	"github.com/gofiber/fiber/v2"
+
+	"github.com/ivpn/dns/api/api/requests"
+	"github.com/ivpn/dns/api/api/responses"
+	"github.com/ivpn/dns/api/internal/auth"
+)
+
+// @Summary Generate DNS Stamps for a modDNS profile
+// @Description Returns DoH, DoT, and DoQ sdns:// strings for the given profile,
+// @Description optionally scoped to a specific device label. Stamps are
+// @Description consumed by clients that don't expose separate hostname/path
+// @Description fields (UniFi Network, dnscrypt-proxy, AdGuard Home upstreams, etc.).
+// @Tags DNS Stamps
+// @Accept json
+// @Produce json
+// @Security ApiKeyAuth
+// @Param body body requests.DNSStampReq true "Generate DNS stamp request"
+// @Success 200 {object} responses.DNSStampResponse
+// @Failure 400 {object} ErrResponse
+// @Failure 404 {object} ErrResponse
+// @Failure 500 {object} ErrResponse
+// @Router /api/v1/dnsstamp [post]
+func (s *APIServer) generateDNSStamps() fiber.Handler {
+	return func(c *fiber.Ctx) error {
+		p := new(requests.DNSStampReq)
+		if err := c.BodyParser(p); err != nil {
+			return HandleError(c, err, ErrInvalidRequestBody.Error())
+		}
+
+		errMsgs := s.Validator.ValidateRequest(c, p, ErrFailedToGenerateDNSStamp.Error())
+		if len(errMsgs) > 0 {
+			return HandleError(c, ErrInvalidRequestBody, strings.Join(errMsgs, " and "))
+		}
+
+		// Ownership check — identical pattern to mobileconfig.go.
+		accountId := auth.GetAccountID(c)
+		if _, err := s.Service.GetProfile(c.Context(), accountId, p.ProfileId); err != nil {
+			return HandleError(c, err, ErrFailedToGenerateDNSStamp.Error())
+		}
+
+		resp, err := s.Service.GenerateStamps(c.Context(), *p)
+		if err != nil {
+			return HandleError(c, err, ErrFailedToGenerateDNSStamp.Error())
+		}
+
+		c.Set("Content-Type", "application/json")
+		return c.Status(fiber.StatusOK).JSON(responses.DNSStampResponse(resp))
+	}
+}