@push.rocks/smartdns 6.2.0 → 6.2.1

package/npmextra.json

@@ -9,14 +9,17 @@
       "npmPackagename": "@push.rocks/smartdns",
       "license": "MIT",
       "keywords": [
-        "DNS",
         "TypeScript",
+        "DNS",
+        "DNS records",
+        "DNS resolution",
+        "DNS management",
+        "DNSSEC",
         "Node.js",
         "Google DNS",
         "Cloudflare",
-        "DNS records",
-        "DNS resolution",
-        "DNSSEC"
+        "UDP DNS",
+        "HTTPS DNS"
       ]
     }
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartdns",
-  "version": "6.2.0",
+  "version": "6.2.1",
   "private": false,
   "description": "A TypeScript library for smart DNS methods, supporting various DNS records and providers.",
   "exports": {
@@ -13,14 +13,17 @@
     "url": "https://code.foss.global/push.rocks/smartdns.git"
   },
   "keywords": [
-    "DNS",
     "TypeScript",
+    "DNS",
+    "DNS records",
+    "DNS resolution",
+    "DNS management",
+    "DNSSEC",
     "Node.js",
     "Google DNS",
     "Cloudflare",
-    "DNS records",
-    "DNS resolution",
-    "DNSSEC"
+    "UDP DNS",
+    "HTTPS DNS"
   ],
   "author": "Lossless GmbH",
   "license": "MIT",

package/readme.md

@@ -1,6 +1,5 @@
 # @push.rocks/smartdns
-
-smart dns methods written in TypeScript
+A TypeScript library for smart DNS methods, supporting various DNS records and providers.
 
 ## Install
 
@@ -16,7 +15,7 @@ Or with `yarn`:
 yarn add @push.rocks/smartdns
 ```
 
-Make sure you have a TypeScript environment setup to utilize the library effectively.
+Make sure you have a TypeScript environment set up to utilize the library effectively.
 
 ## Usage
 
@@ -39,6 +38,8 @@ Often, the need arises to fetch various DNS records for a domain. `@push.rocks/s
 To fetch an "A" record for a domain:
 
 ```typescript
+import { Smartdns } from '@push.rocks/smartdns';
+
 const dnsManager = new Smartdns({});
 const aRecords = await dnsManager.getRecordsA('example.com');
 console.log(aRecords);
@@ -53,6 +54,15 @@ const aaaaRecords = await dnsManager.getRecordsAAAA('example.com');
 console.log(aaaaRecords);
 ```
 
+#### Fetching TXT Records
+
+For "TXT" records:
+
+```typescript
+const txtRecords = await dnsManager.getRecordsTxt('example.com');
+console.log(txtRecords);
+```
+
 ### Advanced DNS Management
 
 Beyond simple queries, `@push.rocks/smartdns` offers functionalities suitable for more complex DNS management scenarios.
@@ -94,6 +104,258 @@ if (featureFlags['NewFeature']) {
 }
 ```
 
+### DNS Server Implementation
+
+To implement a DNS server, `@push.rocks/smartdns` includes classes and methods to set up a UDP and HTTPS DNS server supporting DNSSEC.
+
+#### Basic DNS Server Example
+
+Here's a basic example of a UDP/HTTPS DNS server:
+
+```typescript
+import { DnsServer } from '@push.rocks/smartdns';
+
+const dnsServer = new DnsServer({
+  httpsKey: 'path/to/key.pem',
+  httpsCert: 'path/to/cert.pem',
+  httpsPort: 443,
+  udpPort: 53,
+  dnssecZone: 'example.com',
+});
+
+dnsServer.registerHandler('*.example.com', ['A'], (question) => ({
+  name: question.name,
+  type: 'A',
+  class: 'IN',
+  ttl: 300,
+  data: '127.0.0.1',
+}));
+
+dnsServer.start().then(() => console.log('DNS Server started'));
+```
+
+### DNSSEC Support
+
+`@push.rocks/smartdns` provides support for DNSSEC, including the generation, signing, and validation of DNS records.
+
+#### DNSSEC Configuration
+
+To configure DNSSEC for your DNS server:
+
+```typescript
+import { DnsServer } from '@push.rocks/smartdns';
+
+const dnsServer = new DnsServer({
+  httpsKey: 'path/to/key.pem',
+  httpsCert: 'path/to/cert.pem',
+  httpsPort: 443,
+  udpPort: 53,
+  dnssecZone: 'example.com',
+});
+
+dnsServer.registerHandler('*.example.com', ['A'], (question) => ({
+  name: question.name,
+  type: 'A',
+  class: 'IN',
+  ttl: 300,
+  data: '127.0.0.1',
+}));
+
+dnsServer.start().then(() => console.log('DNS Server with DNSSEC started'));
+```
+
+This setup ensures that DNS records are signed and can be verified for authenticity.
+
+### Handling DNS Queries Over Different Protocols
+
+The library supports handling DNS queries over UDP and HTTPS.
+
+#### Handling UDP Queries
+
+UDP is the traditional means of DNS query transport. 
+
+```typescript
+import { DnsServer } from '@push.rocks/smartdns';
+import dgram from 'dgram';
+
+dnsServer.registerHandler('*.example.com', ['A'], (question) => ({
+  name: question.name,
+  type: 'A',
+  class: 'IN',
+  ttl: 300,
+  data: '127.0.0.1',
+}));
+
+dnsServer.start().then(() => {
+  console.log('UDP DNS Server started on port', dnsServer.getOptions().udpPort);
+});
+
+const client = dgram.createSocket('udp4');
+
+client.on('message', (msg, rinfo) => {
+  console.log(`Received ${msg} from ${rinfo.address}:${rinfo.port}`);
+});
+
+client.send(Buffer.from('example DNS query'), dnsServer.getOptions().udpPort, 'localhost');
+```
+
+#### Handling HTTPS Queries
+
+DNS over HTTPS (DoH) is increasingly adopted for privacy and security.
+
+```typescript
+import { DnsServer } from '@push.rocks/smartdns';
+import https from 'https';
+import fs from 'fs';
+
+const dnsServer = new DnsServer({
+  httpsKey: fs.readFileSync('path/to/key.pem'),
+  httpsCert: fs.readFileSync('path/to/cert.pem'),
+  httpsPort: 443,
+  udpPort: 53,
+  dnssecZone: 'example.com',
+});
+
+dnsServer.registerHandler('*.example.com', ['A'], (question) => ({
+  name: question.name,
+  type: 'A',
+  class: 'IN',
+  ttl: 300,
+  data: '127.0.0.1',
+}));
+
+dnsServer.start().then(() => console.log('HTTPS DNS Server started'));
+
+const client = https.request({
+  hostname: 'localhost',
+  port: 443,
+  path: '/dns-query',
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/dns-message'
+  }
+}, (res) => {
+  res.on('data', (d) => {
+    process.stdout.write(d);
+  });
+});
+
+client.on('error', (e) => {
+  console.error(e);
+});
+
+client.write(Buffer.from('example DNS query'));
+client.end();
+```
+
+### Testing
+
+To ensure that the DNS server behaves as expected, it is important to write tests for various scenarios.
+
+#### DNS Server Tests
+
+Here is an example of how to test the DNS server with TAP:
+
+```typescript
+import { expect, tap } from '@push.rocks/tapbundle';
+
+import { DnsServer } from '@push.rocks/smartdns';
+
+let dnsServer: DnsServer;
+
+tap.test('should create an instance of DnsServer', async () => {
+  dnsServer = new DnsServer({
+    httpsKey: 'path/to/key.pem',
+    httpsCert: 'path/to/cert.pem',
+    httpsPort: 443,
+    udpPort: 53,
+    dnssecZone: 'example.com',
+  });
+  expect(dnsServer).toBeInstanceOf(DnsServer);
+});
+
+tap.test('should start the server', async () => {
+  await dnsServer.start();
+  expect(dnsServer.isRunning()).toBeTrue();
+});
+
+tap.test('should add a DNS handler', async () => {
+  dnsServer.registerHandler('*.example.com', ['A'], (question) => ({
+    name: question.name,
+    type: 'A',
+    class: 'IN',
+    ttl: 300,
+    data: '127.0.0.1',
+  }));
+
+  const response = dnsServer.processDnsRequest({
+    type: 'query',
+    id: 1,
+    flags: 0,
+    questions: [
+      {
+        name: 'test.example.com',
+        type: 'A',
+        class: 'IN',
+      },
+    ],
+    answers: [],
+  });
+
+  expect(response.answers[0]).toEqual({
+    name: 'test.example.com',
+    type: 'A',
+    class: 'IN',
+    ttl: 300,
+    data: '127.0.0.1',
+  });
+});
+
+tap.test('should query the server over HTTP', async () => {
+  // Assuming fetch or any HTTP client is available
+  const query = dnsPacket.encode({
+    type: 'query',
+    id: 2,
+    flags: dnsPacket.RECURSION_DESIRED,
+    questions: [
+      {
+        name: 'test.example.com',
+        type: 'A',
+        class: 'IN',
+      },
+    ],
+  });
+
+  const response = await fetch('https://localhost:443/dns-query', {
+    method: 'POST',
+    body: query,
+    headers: {
+      'Content-Type': 'application/dns-message',
+    }
+  });
+
+  expect(response.status).toEqual(200);
+
+  const responseData = await response.arrayBuffer();
+  const dnsResponse = dnsPacket.decode(Buffer.from(responseData));
+
+  expect(dnsResponse.answers[0]).toEqual({
+    name: 'test.example.com',
+    type: 'A',
+    class: 'IN',
+    ttl: 300,
+    data: '127.0.0.1',
+  });
+});
+
+tap.test('should stop the server', async () => {
+  await dnsServer.stop();
+  expect(dnsServer.isRunning()).toBeFalse();
+});
+
+await tap.start();
+```
+
 ### Conclusion
 
 `@push.rocks/smartdns` offers a versatile set of tools for DNS querying and management, tailored for applications at any scale. The examples provided illustrate the library's potential use cases, highlighting its applicability in various scenarios from basic lookups to facilitating complex application features through DNS.
@@ -102,8 +364,6 @@ For the full spectrum of functionalities, including detailed method documentatio
 
 Remember, DNS changes might take time to propagate worldwide, and the utility methods provided by `@push.rocks/smartdns` for checking record availability will be invaluable in managing these changes seamlessly.
 
-
-
 ## License and Legal Information
 
 This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.