dns-worker 1.0.24 → 1.1.1-canary.e00a6a3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/README.md +141 -109
  2. package/dist/serverfull.mjs +5513 -983
  3. package/migrations/0052_add_e2ee_to_logs.sql +6 -0
  4. package/migrations/0053_add_e2ee_key_tables.sql +31 -0
  5. package/migrations/0054_drop_hourly_rollups.sql +12 -0
  6. package/migrations/0055_add_is_active_to_user_log_keys.sql +2 -0
  7. package/migrations/0056_add_kem_keys_and_encrypt_version.sql +21 -0
  8. package/migrations/0057_add_idx_logs_kem_key_id.sql +2 -0
  9. package/package.json +10 -7
  10. package/static/_headers +8 -0
  11. package/static/assets/AccountView-CdfTI-rw.js +4 -0
  12. package/static/assets/AnalyticsView-DE25Td6t.js +2 -0
  13. package/static/assets/AuthView-DeKX1gG-.js +2 -0
  14. package/static/assets/DestinationMap-CRCdjD4S.js +1 -0
  15. package/static/assets/FilteringView-9SF7vAn0.js +1 -0
  16. package/static/assets/LogsView-DGXuCkRb.js +5 -0
  17. package/static/assets/QRCodeCanvas-9YjBSnzo.js +2 -0
  18. package/static/assets/RulesView-C8mXn9m8.js +1 -0
  19. package/static/assets/SettingsView-yiZeyh7q.js +1 -0
  20. package/static/assets/SetupView-r5GQKPN4.js +1 -0
  21. package/static/assets/{SwipeableDrawer-CzMJdF3W.js → SwipeableDrawer-DuXKmSrw.js} +1 -1
  22. package/static/assets/{TrendChart-Dl9UU7gA.js → TrendChart-BbPOeC8w.js} +3 -3
  23. package/static/assets/browser-BqNNtPRD.js +1 -0
  24. package/static/assets/date-dnUzoLoj.js +1 -0
  25. package/static/assets/de-DE-Bvn6LW48.js +10 -0
  26. package/static/assets/es-ES-BHMlKDw4.js +10 -0
  27. package/static/assets/fr-FR-DEgfea4H.js +10 -0
  28. package/static/assets/index-Ct0QwtUk.js +14 -0
  29. package/static/assets/index-D53KGRYV.css +2 -0
  30. package/static/assets/ja-JP-C1UasoOt.js +10 -0
  31. package/static/assets/ko-KR-DRVmuXAK.js +10 -0
  32. package/static/assets/ru-RU-BrUQ8HMM.js +10 -0
  33. package/static/assets/services-unF2tLc7.js +1 -0
  34. package/static/assets/sqlite.worker-C50yoTbX.js +186 -0
  35. package/static/assets/sqlite3-Con_VOcu.wasm +0 -0
  36. package/static/assets/sqlite3-opfs-async-proxy-Ck-yCayi.js +881 -0
  37. package/static/assets/sqlite3-opfs-async-proxy.js +881 -0
  38. package/static/assets/sqlite3-worker1-DZ2OAEkd.js +44 -0
  39. package/static/assets/vendor-react-GZisTXSQ.js +11 -0
  40. package/static/assets/{vendor-ui-core-CCxBtqRD.js → vendor-ui-core-BjAOArGo.js} +1 -1
  41. package/static/assets/vendor-utils-C-1rF3VB.js +9 -0
  42. package/static/assets/vi-VN-_fj_hwx9.js +10 -0
  43. package/static/assets/zh-CN-DRUEP9Sg.js +10 -0
  44. package/static/assets/zh-TW-v7FvDwjG.js +10 -0
  45. package/static/index.html +5 -5
  46. package/static/sqlite3-opfs-async-proxy.js +881 -0
  47. package/static/sw.js +1 -1
  48. package/static/assets/AccountView-yBM8r7xk.js +0 -4
  49. package/static/assets/AnalyticsView-CW9l8krm.js +0 -2
  50. package/static/assets/AuthView-BpLHhuif.js +0 -2
  51. package/static/assets/DestinationMap-DUZnyLyb.js +0 -1
  52. package/static/assets/FilteringView-BvOw_liH.js +0 -1
  53. package/static/assets/LogsView-CYxZaJPW.js +0 -5
  54. package/static/assets/QRCodeCanvas-vzXe_hzQ.js +0 -2
  55. package/static/assets/RulesView-CbToiqT1.js +0 -1
  56. package/static/assets/SettingsView-mSkxdlrh.js +0 -1
  57. package/static/assets/SetupView-Dzbc8NmG.js +0 -1
  58. package/static/assets/browser-BskSZoIg.js +0 -1
  59. package/static/assets/date-WF-_cJDs.js +0 -1
  60. package/static/assets/de-DE-CXKS_pep.js +0 -10
  61. package/static/assets/es-ES-B2e3ea35.js +0 -10
  62. package/static/assets/fr-FR-1qQHEpoW.js +0 -10
  63. package/static/assets/index-DLmOvLdX.js +0 -16
  64. package/static/assets/index-DdQuGqR5.css +0 -2
  65. package/static/assets/ja-JP-CCVeJXwX.js +0 -10
  66. package/static/assets/ko-KR-bQ1okpC2.js +0 -10
  67. package/static/assets/ru-RU-DeRsms_o.js +0 -10
  68. package/static/assets/services-C-uSOjyn.js +0 -1
  69. package/static/assets/vendor-react-DifRgRH3.js +0 -11
  70. package/static/assets/vendor-utils-D17P9mkD.js +0 -9
  71. package/static/assets/vi-VN-BcXfqmzH.js +0 -10
  72. package/static/assets/zh-CN-D8YK7j27.js +0 -12
  73. package/static/assets/zh-TW-C2_-uaZk.js +0 -12
package/README.md CHANGED
@@ -1,7 +1,7 @@
1
1
  <div align="center">
2
2
  <img src="https://raw.githubusercontent.com/Obein/DNS-Worker/main/web/src/assets/obex_cat_eye_logo-256.webp" alt="DNS Worker Logo" width="128">
3
3
  <h1>DNS Worker</h1>
4
- <p>Protective DNS resolver based on Cloudflare Workers & D1</p>
4
+ <p>Privacy-First Protective DNS Resolver & DoH / DoT Server</p>
5
5
  <p>Protect your first hop on the internet</p>
6
6
  <p align="center">
7
7
  English | <a href="README_zh-CN.md">中文 (简体)</a> | <a href="README_zh-TW.md">中文 (正體)</a>
@@ -9,49 +9,45 @@
9
9
 
10
10
  [![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](LICENSE)
11
11
  [![Platform: Cloudflare Workers](https://img.shields.io/badge/Platform-Cloudflare%20Workers-orange.svg)](https://workers.cloudflare.com/)
12
+ [![Runtime: Node.js >= 22.5](https://img.shields.io/badge/Runtime-Node.js%20%3E%3D%2022.5-green.svg)](https://nodejs.org/)
13
+ [![Security: NIST FIPS 203 PQC](https://img.shields.io/badge/Security-NIST%20FIPS%20203%20PQC-purple.svg)](https://csrc.nist.gov/pubs/fips/203/final)
14
+ [![Protocols: UDP 53 · DoT 853 · DoH](https://img.shields.io/badge/Protocols-UDP%2053%20%7C%20DoT%20853%20%7C%20DoH-brightgreen.svg)](#-dual-engine-architecture--deployment-matrix)
12
15
  </div>
13
16
 
14
17
  ---
15
18
 
16
19
  ## 📖 Introduction
17
20
 
18
- **DNS Worker** is a lightweight, scalable, and privacy-focused DNS resolution system. It runs entirely on Cloudflare's edge network, leveraging the ultra-fast response of Workers and the efficient storage of D1 database to provide users with a granular DNS (over HTTPS) control experience.
21
+ **DNS Worker**, a privacy-first protective DNS resolution system built with a **Dual-Engine Architecture**. It can be deployed either as a zero-maintenance serverless application on Cloudflare Workers edge network, or run completely independent of Cloudflare as a standalone server on your own VPS, home server, or bare-metal machine (Linux, macOS, Windows) with native SQLite storage.
19
22
 
20
23
  [![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/Obein/DNS-Worker)
21
24
 
22
- ### Why DNS Worker?
25
+ ### What is DNS over HTTPS (DoH) & DNS over TLS (DoT)?
23
26
 
24
- | | Traditional DNS Services | DNS Worker |
25
- |---|---|---|
26
- | **Hosting** | Requires a VPS or home server | Runs on Cloudflare's free tier — no server needed |
27
- | **Latency** | Depends on server location | Edge-computed in 300+ cities worldwide |
28
- | **Maintenance** | Manual updates, OS patches | Zero-maintenance serverless deployment |
29
- | **Scaling** | Limited by hardware | Scales automatically with Cloudflare's network |
30
- | **Cost** | Server fees + electricity | Free for most personal usage |
31
-
32
- > Deploy your own privacy-respecting DNS resolver in under 5 minutes — no credit card, no server, no DevOps.
33
-
34
- ### What is DNS over HTTPS (DoH)?
35
-
36
- DoH (RFC 8484) is a protocol for performing DNS queries via encrypted HTTPS connections. Compared to traditional plaintext DNS, DoH can:
37
- * **Prevent Hijacking**: Prevents ISPs or third parties from tampering with DNS responses.
38
- * **Enhance Privacy**: Hides your browsing history through an encrypted tunnel.
39
- * **Bypass Censorship**: Provides more stable resolution in restricted network environments.
27
+ * **DNS over HTTPS (DoH / RFC 8484)**: Performs DNS queries over encrypted HTTPS connections. DNS Worker exposes DoH endpoints compatible with all modern browsers, operating systems, and stub resolvers.
28
+ * **DNS over TLS (DoT / RFC 7858)**: Encrypts DNS queries directly over TLS on dedicated port 853. DNS Worker Standalone mode natively routes incoming DoT requests to isolated user profiles using TLS Server Name Indication (SNI), making it ideal for Android 9+ native Private DNS.
40
29
 
41
30
  ---
42
31
 
43
32
  ## ✨ Core Features
44
33
 
45
- - 🚀 **Ultra-fast Resolution**: Fully based on edge computing with extremely low global latency.
46
- - 🗒️ **Multi-profile Management**: Supports creating multiple independent configurations, each with a unique endpoint.
34
+ - 🌐 **Dual-Engine Deployment**: Run serverless on Cloudflare Workers edge, or run standalone on any VPS / home server with zero Cloudflare dependency.
35
+ - ⚡ **Full-Stack Protocol Support**:
36
+ - **Classic UDP 53**: Standard RFC 1035 DNS for routers and LAN devices.
37
+ - **DoT 853 (DNS over TLS)**: RFC 7858 encrypted DNS with TLS SNI profile routing (`<profile_key>.dns.example.com`), natively compatible with Android Private DNS.
38
+ - **DoH (DNS over HTTPS)**: RFC 8484 encrypted DNS over HTTP/2 and HTTP/3.
39
+ - 🚀 **Ultra-fast Resolution**: Edge-accelerated caching and multi-tier memory pipelines for sub-millisecond query responses.
40
+ - 🗒️ **Multi-Profile Management**: Create independent configurations with isolated endpoints, rules, and upstream settings.
47
41
  - 🛡️ **Granular Filtering**:
48
- - **Allow/Block Lists**: Supports exact domain and subdomain wildcard matching.
49
- - **Third-party Rule Sets**: Supports subscribing to external blocklists in formats like AdGuard.
50
- - **Custom Redirection**: Supports custom overrides for A, AAAA, TXT, and CNAME records.
51
- - 📊 **Real-time Stats & Logs**: Visual dashboard recording every request's hit reason, geo-location, and upstream latency.
52
- - 🔐 **Privacy Enhancement**: Flexible ECS (EDNS Client Subnet) configuration (Forward, Custom, or Hidden).
53
- - 🔒 **Rewrite ECH & ECH Fronting**: Automatically injects/rewrites ECH (Encrypted Client Hello) parameters and customizable Outer SNI (ECH Fronting) for HTTPS (Type 65) / SVCB (Type 64) queries to eliminate plaintext SNI leakage. *(Note: ECH rewriting is exclusively supported for domains proxied by Cloudflare)*.
54
- - 🌗 **Modern UI**: Dark mode support, high-density management panel built with React + BlueprintJS.
42
+ - **Allow/Block Lists**: Exact domain and wildcard subdomain matching.
43
+ - **Third-Party Rule Sets**: Subscribe to external blocklists (AdGuard, EasyList, hosts syntax) with fast Bloom filter matching.
44
+ - **Custom Redirections**: Override A, AAAA, TXT, and CNAME records with custom answers.
45
+ - 📊 **Real-time Stats & Logs**: Visual dashboard recording query type, hit reason, client geo-location, and upstream latency.
46
+ - 🔐 **Privacy Controls**: Flexible ECS (EDNS Client Subnet) management (Forward, Custom, or Hidden).
47
+ - 🔒 **Rewrite ECH & ECH Fronting**: Automatically injects/rewrites Encrypted Client Hello (ECH) parameters and outer SNI for HTTPS (Type 65) / SVCB (Type 64) queries to eliminate plaintext SNI leakage *(Note: ECH rewriting is supported for domains proxied by Cloudflare)*.
48
+ - ⚡ **Local-First Architecture**: Embedded in-browser SQLite (WASM + OPFS) and Web Workers deliver instant 0ms log filtering and aggregation without cloud queries. Background bidirectional sync keeps data aligned while saving database read quotas.
49
+ - 🛡️ **Post-Quantum Zero-Knowledge E2EE**: Hardware Passkey (WebAuthn) and Recovery Key protected End-to-End Encryption for query logs. Implements NIST FIPS 203 **P256-MLKEM768** hybrid lattice cryptography with hourly rotating KEM DEKs. Persistent storage holds only irreversible ciphertexts; decryption occurs strictly on your authorized client devices.
50
+ - 🌗 **Modern UI**: High-density management panel with dark mode, built with React + BlueprintJS.
55
51
 
56
52
  ---
57
53
 
@@ -92,14 +88,20 @@ DoH (RFC 8484) is a protocol for performing DNS queries via encrypted HTTPS conn
92
88
  ### Code Structure
93
89
  ```text
94
90
  ├── src/
95
- │ ├── index.ts # Entry point, handles HTTP routing & middleware
91
+ │ ├── index.ts # Cloudflare Worker entry point, handles HTTP routing & DoH
92
+ │ ├── serverfull/ # Standalone Server entry point (UDP 53, DoT 853, HTTP 3000)
93
+ │ │ ├── index.ts # Serverfull CLI & Master bootstrap
94
+ │ │ ├── udp.ts # Classic RFC 1035 UDP 53 DNS Server
95
+ │ │ ├── dot.ts # RFC 7858 DoT 853 Server with SNI Profile routing
96
+ │ │ ├── http.ts # Web Dashboard & DoH HTTP server
97
+ │ │ └── db.ts # Native Node.js SQLite (node:sqlite) adapter & migrator
96
98
  │ ├── types.ts # Type definitions
97
99
  │ ├── api/ # API Controllers (Auth, Account, Profiles)
98
- │ ├── lib/ # Core logic (RBAC, Rule filtering)
99
- │ ├── models/ # D1 Database models
100
- │ ├── pipeline/ # DNS Resolution Pipeline (Core business logic)
100
+ │ ├── lib/ # Core logic (RBAC, Rule filtering, PQC Crypto, DEK manager)
101
+ │ ├── models/ # Database models (Unified D1 & SQLite)
102
+ │ ├── pipeline/ # DNS Resolution Pipeline (Unified core business logic)
101
103
  │ └── utils/ # Utilities (Cache, GeoIP, DNS Codec, Bloom Filter)
102
- ├── web/ # React/BlueprintJS UI frontend project
104
+ ├── web/ # React/BlueprintJS UI frontend (Local-First WASM + OPFS)
103
105
  │ ├── public/ # Public static files
104
106
  │ ├── src/ # Frontend source code
105
107
  │ │ ├── assets/ # Static assets (images, icons, etc.)
@@ -112,14 +114,15 @@ DoH (RFC 8484) is a protocol for performing DNS queries via encrypted HTTPS conn
112
114
  │ │ └── utils/ # Utility helpers and functions
113
115
  │ └── package.json # Frontend dependencies configuration
114
116
  ├── static/ # Compiled static resources
115
- ├── migrations/ # D1 Database migration scripts
117
+ ├── scripts/ # Automation scripts (e.g., Linux systemd service generator)
118
+ ├── migrations/ # Unified SQL Database migration scripts
116
119
  └── wrangler.toml # Cloudflare deployment configuration
117
120
  ```
118
121
 
119
122
  ### Resolution Pipeline
120
123
  When a DNS request arrives, it goes through the following processing stages:
121
124
  1. **Memory Cache Check**: Checks if a valid response for the query exists in the edge node's memory.
122
- 2. **Config Loading**: Layers profile settings loading from Memory -> Cache API -> D1 Database.
125
+ 2. **Config Loading**: Layers profile settings loading from Memory -> Cache API -> Database (D1 or SQLite).
123
126
  3. **Local Rule Matching**:
124
127
  - **Whitelist**: If hit, forwards directly to upstream and returns.
125
128
  - **Redirection**: If hit, returns custom records.
@@ -127,72 +130,23 @@ When a DNS request arrives, it goes through the following processing stages:
127
130
  4. **External List Filtering**:
128
131
  - Use a **Bloom filter** for fast filtering.
129
132
  5. **Upstream Resolution**: If none of the above hit, requests the upstream DoH server based on configuration, with optional ECS support.
130
- 6. **Async Logging & Caching**: Asynchronously records resolution logs, fetches target GeoIP, and writes results to various cache levels.
133
+ 6. **Async Logging & Caching**: Asynchronously records resolution logs (with optional PQC E2EE encryption), fetches target GeoIP, and writes results to various cache levels.
131
134
 
132
135
  ---
133
136
 
134
137
  ## 🚀 Deployment Guide
135
138
 
136
- ### Online Deployment (Cloudflare Dashboard)
137
-
138
- 1. **Fork this repo**: Click the `Fork` button at the top right to clone the repository to your own GitHub account.
139
- 2. **Create D1 Database**: Log in to the Cloudflare dashboard, go to `Workers & Pages` > `D1`, and create a new database (e.g., named `dns_worker_db`), and copy the created database ID.
140
- 3. **Configure Database ID**: In your forked repository, edit the `wrangler.toml` file and replace `database_id` with the ID of the database you just created.
141
- 4. **Create Worker**: Go to Cloudflare dashboard `Workers & Pages` > `Create application`.
142
- 5. **Import from GitHub & Complete Initial Deployment**: On the deployment page, select `Continue with GitHub`, connect your forked project, and complete the authorized deployment. Under the Build & Deploy settings, configure as follows:
143
- * **Build command**: `npm run build`
144
- * **Deploy command**: `npm run deploy`
145
- * **Root directory (Path)**: `/`
146
- > ⚠️ **Note**: Environment variables entered in the initial project setup wizard are only injected into the build container and will not take effect as runtime secrets. Proceed with the "Deploy" button directly, and configure runtime secrets in your Worker's settings after the initial deployment finishes.
147
- 6. **Configure JWT Secret**: After the initial deployment completes, go to Cloudflare Dashboard -> `Workers & Pages` -> click on your Worker -> `Settings` -> `Runtime variables and secrets` (or `Variables and secrets`) -> click `Add`. Set the Name to `JWT_SECRET`, choose type `Secret`, input a secure random string as Value, and click `Deploy` (or `Save and Deploy`).
148
- 7. **Configure KEK for Envelope Encryption (Optional)**: In the same `Settings` > `Runtime variables and secrets` section after deployment, to enable server-side envelope encryption for sensitive credentials (such as TOTP keys and recovery keys) in D1, add a variable named `KEK_v1`, type `Secret`, and input a secure key value. When you need to rotate the KEK key, add a new secret `KEK_v(N+1)` (e.g. `KEK_v2` -> `KEK_v3`, etc.) sequentially.
149
-
150
- ### Local Development & Manual Deployment
139
+ DNS Worker offers two deployment methods tailored to different operational needs:
140
+ * **Option A: 🖥️ Standalone Server / VPS (Cloudflare-Free, Full Sovereignty)** — Best if you want complete control, classic UDP 53 for routers, and native Android DoT 853 on your own machine.
141
+ * **Option B: ☁️ Cloudflare Workers Edge (Serverless, Zero Maintenance)** — Best if you want a globally distributed, zero-cost, zero-maintenance DoH resolver on 300+ edge PoPs.
151
142
 
152
- #### Development Environment
153
- - **Node.js**: v18.x or later
154
- - **Package Manager**: npm
155
- - **Cloudflare Account**: Workers and D1 permissions required
156
-
157
- #### Local Setup & Deployment Steps
158
- 1. Clone the repository and install dependencies:
159
-
160
- ```bash
161
- npm install
162
- ```
163
-
164
- 2. Initialize D1 Database:
165
-
166
- ```bash
167
- npm run db:setup
168
- npm run db:migrate:dev
169
- ```
170
-
171
- 3. Configure environment variables:
172
- * Create a `.dev.vars` file in the root directory and add a secure random JWT secret (required for session token signing):
173
- ```env
174
- JWT_SECRET=your_secure_random_string_here
175
- ```
176
- * (Optional) Enable Envelope Encryption for sensitive credentials (like TOTP secrets and recovery keys) by adding a Key Encryption Key (KEK):
177
- ```env
178
- KEK_v1=your_secure_kek_v1_key_string
179
- ```
180
-
181
- 4. Start the development server:
182
-
183
- ```bash
184
- npm run dev
185
- ```
186
-
187
- 5. Deploy manually:
143
+ ---
188
144
 
189
- ```bash
190
- npm run deploy
191
- ```
145
+ ### Option A: 🖥️ Standalone Server / VPS (Cloudflare-Free, Full Sovereignty)
192
146
 
193
- ### Serverfull Mode Deployment (Standalone Server / VPS)
147
+ Run DNS Worker directly on any Linux, Windows, or macOS host with Node.js `>= 22.5.0` (using built-in `node:sqlite`). No Cloudflare account, tokens, or external databases required.
194
148
 
195
- DNS Worker can run completely independent of Cloudflare Workers as a standalone service on your Linux, Windows, or macOS server. Serverfull mode provides:
149
+ #### Features in Standalone Mode
196
150
  * **Classic UDP DNS (Port 53)**: Standard RFC 1035 UDP DNS resolution service for routers or system DNS settings.
197
151
  * **DNS over TLS / DoT (Port 853)**: RFC 7858 encrypted DNS, natively supported by Android 9+ "Private DNS", with SNI-based Profile routing (e.g. `<profile_key>.dns.example.com`).
198
152
  * **Web Dashboard & DoH (Default Port 3000)**: Full-featured React management dashboard and REST API.
@@ -214,25 +168,83 @@ DNS Worker can run completely independent of Cloudflare Workers as a standalone
214
168
 
215
169
  #### Quick Start
216
170
 
217
- 1. Configure environment variables:
218
- The project provides an out-of-the-box configuration file `.env.serverfull` (the server automatically loads system environment variables, `.env`, or `.env.serverfull` by priority). You can directly modify `.env.serverfull`, or copy it to `.env` for customization:
171
+ 1. Clone repository and install dependencies:
172
+ ```bash
173
+ git clone https://github.com/Obein/DNS-Worker.git DNS-Worker
174
+ cd DNS-Worker
175
+ npm install
176
+ ```
177
+
178
+ 2. Configure environment variables:
179
+ The project provides an out-of-the-box configuration template `.env.serverfull`. You can modify it directly or copy it to `.env`:
219
180
  ```bash
220
- # Edit .env.serverfull directly (or copy via cp .env.serverfull .env first)
221
- nano .env.serverfull
181
+ cp .env.serverfull .env
182
+ nano .env
222
183
  ```
223
184
 
224
- 2. Build frontend and start Serverfull service:
185
+ 3. Build frontend and start Standalone Server:
225
186
  ```bash
226
187
  npm run start:serverfull
227
188
  ```
228
189
 
229
- 3. Register as a Linux systemd background service:
190
+ 4. Production deployment as a Linux systemd background service:
230
191
  ```bash
231
192
  sudo npm run service-create:linux
232
193
  sudo systemctl start dns-worker
233
194
  sudo systemctl status dns-worker
234
195
  ```
235
- This generates `/etc/systemd/system/dns-worker.service` configured with `CAP_NET_BIND_SERVICE` privileges to bind ports 53 and 853 with automatic restart on boot.
196
+ This generates `/etc/systemd/system/dns-worker.service` configured with `CAP_NET_BIND_SERVICE` privileges to bind privileged ports 53 and 853 without running as root, with automatic restart on reboot.
197
+
198
+ ---
199
+
200
+ ### Option B: ☁️ Cloudflare Workers Edge (Serverless, Zero Maintenance)
201
+
202
+ Run DNS Worker across 300+ edge locations worldwide on Cloudflare Workers and D1 database.
203
+
204
+ [![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/Obein/DNS-Worker)
205
+
206
+ #### 1. Online Deployment (Cloudflare Dashboard)
207
+
208
+ 1. **Fork this repo**: Click the `Fork` button at the top right to clone the repository to your own GitHub account.
209
+ 2. **Create D1 Database**: Log in to the Cloudflare dashboard, go to `Workers & Pages` > `D1`, and create a new database (e.g., named `dns_worker_db`), and copy the created database ID.
210
+ 3. **Configure Database ID**: In your forked repository, edit the `wrangler.toml` file and replace `database_id` with the ID of the database you just created.
211
+ 4. **Create Worker**: Go to Cloudflare dashboard `Workers & Pages` > `Create application`.
212
+ 5. **Import from GitHub & Complete Initial Deployment**: On the deployment page, select `Continue with GitHub`, connect your forked project, and complete the authorized deployment. Under the Build & Deploy settings, configure as follows:
213
+ * **Build command**: `npm run build`
214
+ * **Deploy command**: `npm run deploy`
215
+ * **Root directory (Path)**: `/`
216
+ > ⚠️ **Note**: Environment variables entered in the initial project setup wizard are only injected into the build container and will not take effect as runtime secrets. Proceed with the "Deploy" button directly, and configure runtime secrets in your Worker's settings after the initial deployment finishes.
217
+ 6. **Configure JWT Secret**: After the initial deployment completes, go to Cloudflare Dashboard -> `Workers & Pages` -> click on your Worker -> `Settings` -> `Runtime variables and secrets` (or `Variables and secrets`) -> click `Add`. Set the Name to `JWT_SECRET`, choose type `Secret`, input a secure random string as Value, and click `Deploy` (or `Save and Deploy`).
218
+ 7. **Configure KEK for Envelope Encryption (Optional)**: In the same `Settings` > `Runtime variables and secrets` section after deployment, to enable server-side envelope encryption for sensitive credentials (such as TOTP keys and recovery keys) in D1, add a variable named `KEK_v1`, type `Secret`, and input a secure key value. When you need to rotate the KEK key, add a new secret `KEK_v(N+1)` (e.g. `KEK_v2` -> `KEK_v3`, etc.) sequentially.
219
+
220
+ #### 2. Local Development & CLI Deployment
221
+
222
+ ##### Prerequisites
223
+ - **Node.js**: v18.x or later (v22.5.0+ recommended)
224
+ - **Package Manager**: npm
225
+ - **Cloudflare Account**: Workers and D1 permissions required
226
+
227
+ ##### Setup & Deployment Steps
228
+ ```bash
229
+ # 1. Clone repository and install dependencies
230
+ npm install
231
+
232
+ # 2. Initialize and migrate local D1 database
233
+ npm run db:setup
234
+ npm run db:migrate:dev
235
+
236
+ # 3. Configure local environment variables (.dev.vars)
237
+ echo "JWT_SECRET=your_secure_random_string_here" > .dev.vars
238
+ echo "KEK_v1=your_secure_kek_v1_key_string" >> .dev.vars
239
+
240
+ # 4. Start local development server
241
+ npm run dev
242
+
243
+ # 5. Deploy to Cloudflare Workers
244
+ npm run deploy
245
+ ```
246
+
247
+ ---
236
248
 
237
249
  ### Online Deployment to Cloudflare Pages (⚠️ Not Recommended)
238
250
 
@@ -252,17 +264,37 @@ If you wish to deploy the project using Cloudflare Pages (Advanced Mode):
252
264
  * **D1 database**: Select your `dns_worker_db` database.
253
265
  5. Redeploy the Pages project for the bindings to take effect.
254
266
 
267
+ ### ⚖️ Dual-Engine Architecture & Deployment Matrix
268
+
269
+ Whether you need global edge resolution across 300+ cities or 100% self-hosted data sovereignty with classic UDP 53 and native Android Private DNS (DoT 853), DNS Worker provides an enterprise-grade resolver with granular filtering, instant local-first analytics, and post-quantum end-to-end encrypted query logs.
270
+
271
+ | Feature / Capability | 🖥️ Standalone Server / VPS (Cloudflare-Free) | ☁️ Cloudflare Workers Edge |
272
+ |---|---|---|
273
+ | **Primary Use Case** | Complete data sovereignty, home lab, direct router DNS, Android DoT | Zero-maintenance, global low-latency edge resolution |
274
+ | **Hosting & Runtime** | Linux / VPS / macOS / Windows (`Node.js >= 22.5.0`) | Cloudflare Workers Edge Network (300+ PoPs worldwide) |
275
+ | **Storage Backend** | Native Node.js SQLite (`node:sqlite`) on local NVMe/SSD | Cloudflare D1 (Global distributed serverless database) |
276
+ | **Supported Protocols** | **UDP 53** (RFC 1035) + **DoT 853** (RFC 7858) + **DoH** (RFC 8484) | **DoH** (RFC 8484 over HTTPS) |
277
+ | **Data Sovereignty** | **100% Self-Sovereign** — zero cloud vendor lock-in | Edge-encrypted; hosted on Cloudflare infrastructure |
278
+ | **Router & LAN DNS** | **Direct UDP 53 listener** (point router/LAN DNS directly to server) | Requires a DoH client, proxy, or stub resolver upstream |
279
+ | **Android Private DNS** | **Native DoT 853** with SNI Profile routing (`<profile_key>.dns.example.com`) | Supported via DoH URL or third-party DNS app |
280
+ | **Zero-Knowledge PQC E2EE** | ✅ NIST FIPS 203 **P256-MLKEM768** + Passkey WebAuthn | ✅ NIST FIPS 203 **P256-MLKEM768** + Passkey WebAuthn |
281
+ | **Local-First Web UI** | ✅ In-browser SQLite WASM + OPFS 0ms instant analysis | ✅ In-browser SQLite WASM + OPFS 0ms instant analysis |
282
+ | **Maintenance & Scaling** | Simple systemd service (`npm run service-create:linux`) | Zero server maintenance; scales automatically |
283
+ | **Cost** | Runs on existing VPS or home server hardware | Free tier for personal usage |
284
+
255
285
  ---
256
286
 
257
287
  ## 💪 Powered by
258
288
 
259
- * [Cloudflare Workers](https://workers.cloudflare.com/)
289
+ * [Cloudflare Workers](https://workers.cloudflare.com/) & [D1 Database](https://developers.cloudflare.com/d1/)
290
+ * [Node.js](https://nodejs.org/) (Native `node:sqlite` Engine)
260
291
 
261
292
  ## 🚚 Dependencies
262
293
 
263
- * [Blueprint](https://github.com/palantir/blueprint) (at Palantir)
294
+ * [React](https://github.com/facebook/react) & [Blueprint](https://github.com/palantir/blueprint) (Modern high-density UI)
264
295
  * [Tailwind CSS](https://github.com/tailwindlabs/tailwindcss)
265
- * [React](https://github.com/facebook/react)
296
+ * [NIST FIPS 203](https://csrc.nist.gov/pubs/fips/203/final) (ML-KEM-768 Post-Quantum Cryptography)
297
+ * [wa-sqlite](https://github.com/rhashimoto/wa-sqlite) (WebAssembly SQLite & OPFS Local-First Storage)
266
298
 
267
299
  ---
268
300
 
@@ -274,15 +306,15 @@ This project is licensed under the [AGPLv3](LICENSE) License.
274
306
 
275
307
  ## 📝 Summary
276
308
 
277
- DNS Worker gives you full control over your DNS resolution — with no servers to rent, no infrastructure to manage, and no compromises on privacy. By leveraging Cloudflare Workers' global edge network and D1 database, it delivers a production-ready Protective DNS service that is:
309
+ DNS Worker gives you full control over your DNS resolution — with zero compromises on privacy, performance, or flexibility. By supporting both a high-efficiency standalone Node.js server and Cloudflare Workers global edge, it delivers an enterprise-grade Protective DNS system that is:
278
310
 
279
- - **Free to run** on Cloudflare's generous free tier
280
- - **Fast everywhere** thanks to 300+ edge locations worldwide
281
- - **Fully customizable** with per-profile rules, allowlists, blocklists, and third-party filter subscriptions
282
- - **Privacy-first** with encrypted DoH and flexible ECS controls
283
- - **Easy to deploy** in minutes via one-click deploy or a simple `npm run deploy`
311
+ - **Dual-Engine Versatility**: Run completely Cloudflare-free on your own VPS with classic UDP 53 & DoT 853, or deploy globally on Cloudflare Workers edge for zero-maintenance DoH.
312
+ - **Full-Stack Protocol Support**: Classic UDP 53 for routers, Android Private DNS (DoT 853 with SNI profile routing), and DoH (RFC 8484).
313
+ - **Post-Quantum E2EE**: Protects sensitive DNS query logs using NIST FIPS 203 **P256-MLKEM768** lattice cryptography and hardware Passkeys (WebAuthn).
314
+ - **Local-First Speed**: Instant 0ms log filtering and analytics in your browser via SQLite WASM + OPFS, eliminating unnecessary database read quotas.
315
+ - **Granular Governance**: Multi-profile isolation, custom record redirection, ECH parameter rewriting, and Bloom-filter-accelerated adblocking subscriptions.
284
316
 
285
- Whether you're protecting a single device or managing DNS for your family, DNS Worker offers an elegant, self-hosted alternative to commercial DNS filtering services — without the cost or complexity.
317
+ Whether protecting a single device, an entire home network, or a distributed organization, DNS Worker provides an elegant, self-sovereign alternative to commercial DNS filtering services.
286
318
 
287
319
  <div align="center">
288
320
  <br>