dns-worker 1.0.24 → 1.1.1-canary.0b671ea
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.
- package/README.md +141 -109
- package/dist/serverfull.mjs +184 -11668
- package/dist/serverfull.mjs.map +7 -0
- package/migrations/0052_add_e2ee_to_logs.sql +6 -0
- package/migrations/0053_add_e2ee_key_tables.sql +31 -0
- package/migrations/0054_drop_hourly_rollups.sql +12 -0
- package/migrations/0055_add_is_active_to_user_log_keys.sql +2 -0
- package/migrations/0056_add_kem_keys_and_encrypt_version.sql +21 -0
- package/migrations/0057_add_idx_logs_kem_key_id.sql +2 -0
- package/package.json +13 -10
- package/static/_headers +8 -0
- package/static/assets/AccountView-CdfTI-rw.js +4 -0
- package/static/assets/AnalyticsView-DE25Td6t.js +2 -0
- package/static/assets/AuthView-DeKX1gG-.js +2 -0
- package/static/assets/DestinationMap-CRCdjD4S.js +1 -0
- package/static/assets/FilteringView-9SF7vAn0.js +1 -0
- package/static/assets/LogsView-DGXuCkRb.js +5 -0
- package/static/assets/QRCodeCanvas-9YjBSnzo.js +2 -0
- package/static/assets/RulesView-C8mXn9m8.js +1 -0
- package/static/assets/SettingsView-yiZeyh7q.js +1 -0
- package/static/assets/SetupView-r5GQKPN4.js +1 -0
- package/static/assets/{SwipeableDrawer-CzMJdF3W.js → SwipeableDrawer-DuXKmSrw.js} +1 -1
- package/static/assets/{TrendChart-Dl9UU7gA.js → TrendChart-BbPOeC8w.js} +3 -3
- package/static/assets/browser-BqNNtPRD.js +1 -0
- package/static/assets/date-dnUzoLoj.js +1 -0
- package/static/assets/de-DE-Bvn6LW48.js +10 -0
- package/static/assets/es-ES-BHMlKDw4.js +10 -0
- package/static/assets/fr-FR-DEgfea4H.js +10 -0
- package/static/assets/index-Ct0QwtUk.js +14 -0
- package/static/assets/index-D53KGRYV.css +2 -0
- package/static/assets/ja-JP-C1UasoOt.js +10 -0
- package/static/assets/ko-KR-DRVmuXAK.js +10 -0
- package/static/assets/ru-RU-BrUQ8HMM.js +10 -0
- package/static/assets/services-unF2tLc7.js +1 -0
- package/static/assets/sqlite.worker-C50yoTbX.js +186 -0
- package/static/assets/sqlite3-Con_VOcu.wasm +0 -0
- package/static/assets/sqlite3-opfs-async-proxy-Ck-yCayi.js +881 -0
- package/static/assets/sqlite3-opfs-async-proxy.js +881 -0
- package/static/assets/sqlite3-worker1-DZ2OAEkd.js +44 -0
- package/static/assets/vendor-react-GZisTXSQ.js +11 -0
- package/static/assets/{vendor-ui-core-CCxBtqRD.js → vendor-ui-core-BjAOArGo.js} +1 -1
- package/static/assets/vendor-utils-C-1rF3VB.js +9 -0
- package/static/assets/vi-VN-_fj_hwx9.js +10 -0
- package/static/assets/zh-CN-DRUEP9Sg.js +10 -0
- package/static/assets/zh-TW-v7FvDwjG.js +10 -0
- package/static/index.html +5 -5
- package/static/sqlite3-opfs-async-proxy.js +881 -0
- package/static/sw.js +1 -1
- package/static/assets/AccountView-yBM8r7xk.js +0 -4
- package/static/assets/AnalyticsView-CW9l8krm.js +0 -2
- package/static/assets/AuthView-BpLHhuif.js +0 -2
- package/static/assets/DestinationMap-DUZnyLyb.js +0 -1
- package/static/assets/FilteringView-BvOw_liH.js +0 -1
- package/static/assets/LogsView-CYxZaJPW.js +0 -5
- package/static/assets/QRCodeCanvas-vzXe_hzQ.js +0 -2
- package/static/assets/RulesView-CbToiqT1.js +0 -1
- package/static/assets/SettingsView-mSkxdlrh.js +0 -1
- package/static/assets/SetupView-Dzbc8NmG.js +0 -1
- package/static/assets/browser-BskSZoIg.js +0 -1
- package/static/assets/date-WF-_cJDs.js +0 -1
- package/static/assets/de-DE-CXKS_pep.js +0 -10
- package/static/assets/es-ES-B2e3ea35.js +0 -10
- package/static/assets/fr-FR-1qQHEpoW.js +0 -10
- package/static/assets/index-DLmOvLdX.js +0 -16
- package/static/assets/index-DdQuGqR5.css +0 -2
- package/static/assets/ja-JP-CCVeJXwX.js +0 -10
- package/static/assets/ko-KR-bQ1okpC2.js +0 -10
- package/static/assets/ru-RU-DeRsms_o.js +0 -10
- package/static/assets/services-C-uSOjyn.js +0 -1
- package/static/assets/vendor-react-DifRgRH3.js +0 -11
- package/static/assets/vendor-utils-D17P9mkD.js +0 -9
- package/static/assets/vi-VN-BcXfqmzH.js +0 -10
- package/static/assets/zh-CN-D8YK7j27.js +0 -12
- 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
|
|
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)
|
|
11
11
|
[](https://workers.cloudflare.com/)
|
|
12
|
+
[](https://nodejs.org/)
|
|
13
|
+
[](https://csrc.nist.gov/pubs/fips/203/final)
|
|
14
|
+
[](#-dual-engine-architecture--deployment-matrix)
|
|
12
15
|
</div>
|
|
13
16
|
|
|
14
17
|
---
|
|
15
18
|
|
|
16
19
|
## 📖 Introduction
|
|
17
20
|
|
|
18
|
-
**DNS Worker
|
|
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
|
[](https://deploy.workers.cloudflare.com/?url=https://github.com/Obein/DNS-Worker)
|
|
21
24
|
|
|
22
|
-
###
|
|
25
|
+
### What is DNS over HTTPS (DoH) & DNS over TLS (DoT)?
|
|
23
26
|
|
|
24
|
-
|
|
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
|
-
-
|
|
46
|
-
-
|
|
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**:
|
|
49
|
-
- **Third-
|
|
50
|
-
- **Custom
|
|
51
|
-
- 📊 **Real-time Stats & Logs**: Visual dashboard recording
|
|
52
|
-
- 🔐 **Privacy
|
|
53
|
-
- 🔒 **Rewrite ECH & ECH Fronting**: Automatically injects/rewrites
|
|
54
|
-
-
|
|
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 #
|
|
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
|
|
100
|
-
│ ├── pipeline/ # DNS Resolution Pipeline (
|
|
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
|
|
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
|
-
├──
|
|
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
|
|
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
|
-
|
|
137
|
-
|
|
138
|
-
|
|
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
|
-
|
|
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
|
-
|
|
190
|
-
npm run deploy
|
|
191
|
-
```
|
|
145
|
+
### Option A: 🖥️ Standalone Server / VPS (Cloudflare-Free, Full Sovereignty)
|
|
192
146
|
|
|
193
|
-
|
|
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
|
-
|
|
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.
|
|
218
|
-
|
|
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
|
-
|
|
221
|
-
nano .env
|
|
181
|
+
cp .env.serverfull .env
|
|
182
|
+
nano .env
|
|
222
183
|
```
|
|
223
184
|
|
|
224
|
-
|
|
185
|
+
3. Build frontend and start Standalone Server:
|
|
225
186
|
```bash
|
|
226
187
|
npm run start:serverfull
|
|
227
188
|
```
|
|
228
189
|
|
|
229
|
-
|
|
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
|
|
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
|
+
[](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) (
|
|
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
|
-
* [
|
|
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
|
|
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
|
-
- **
|
|
280
|
-
- **
|
|
281
|
-
- **
|
|
282
|
-
- **
|
|
283
|
-
- **
|
|
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
|
|
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>
|