smartdns/readme.md

# @push.rocks/smartdns

A TypeScript library for smart DNS methods, supporting various DNS records and providers.

## Install

To install `@push.rocks/smartdns`, use the following command with npm:

```bash
npm install @push.rocks/smartdns --save
```

Or with `yarn`:

```bash
yarn add @push.rocks/smartdns
```

Make sure you have a TypeScript environment set up to utilize the library effectively.

## Usage

`@push.rocks/smartdns` is a comprehensive library aimed at facilitating smart DNS operations, leveraging TypeScript for enhanced development experience. This section aims to cover several real-world scenarios demonstrating the library's capabilities, from basic DNS lookups to more advanced DNS management tasks.

### Getting Started

First, ensure you import the module into your TypeScript project:

```typescript
import { Smartdns } from '@push.rocks/smartdns';
```

### Basic DNS Record Lookup

Often, the need arises to fetch various DNS records for a domain. `@push.rocks/smartdns` simplifies this by providing intuitive methods. A DNS record is essentially a map from a domain name to information about that domain, such as its IP address, mail exchange server, etc.

#### Fetching A Records

To fetch an "A" record for a domain, which resolves the domain to an IPv4 address, use the following approach:

```typescript
import { Smartdns } from '@push.rocks/smartdns';

const dnsManager = new Smartdns({});
const aRecords = await dnsManager.getRecordsA('example.com');
console.log(aRecords);
```

This will return an array of records that include the IPv4 addresses mapped to the domain `example.com`.

#### Fetching AAAA Records

For resolving a domain to an IPv6 address, you can fetch "AAAA" records in a similar manner:

```typescript
const aaaaRecords = await dnsManager.getRecordsAAAA('example.com');
console.log(aaaaRecords);
```

These queries are quite common where IPv6 addresses have been prevalent due to the scarcity of IPv4 addresses.

#### Fetching TXT Records

TXT records store arbitrary text data associated with a domain. They are often used to hold information such as SPF records for email validation or Google site verification token.

```typescript
const txtRecords = await dnsManager.getRecordsTxt('example.com');
console.log(txtRecords);
```

TXT records have increasingly become significant with the growth of security features and integrations that require domain verification.

### Advanced DNS Management

The `@push.rocks/smartdns` doesn't just stop at querying— it offers more advanced DNS management utilities, which are crucial for real-world applications involving DNS operations.

#### Checking DNS Propagation

When changing DNS records, ensuring that the new records have propagated fully is crucial. `@push.rocks/smartdns` facilitates this with a method to check if a DNS record is available globally. This can be critical for ensuring that users worldwide are able to access your updated records in a consistent manner.

```typescript
const recordType = 'TXT'; // Record type: A, AAAA, CNAME, TXT etc.
const expectedValue = 'your_expected_value';
const isAvailable = await dnsManager.checkUntilAvailable('example.com', recordType, expectedValue);

if (isAvailable) {
  console.log('Record propagated successfully.');
} else {
  console.log('Record propagation failed or timed out.');
}
```

This method repeatedly queries DNS servers until the expected DNS record appears, making sure that the changes made are visible globally.

### Leveraging DNS for Application Logic

DNS records can function beyond their typical usage of domain-to-IP resolution. They can be extremely useful in application logic such as feature flagging or environment-specific configurations.

#### Example: Feature Flagging via TXT Records

One such advanced use case is using TXT records for enabling or disabling features dynamically without needing to redeploy or change the actual application code:

```typescript
const txtRecords = await dnsManager.getRecordsTxt('features.example.com');
const featureFlags = txtRecords.reduce((acc, record) => {
  const [flag, isEnabled] = record.value.split('=');
  acc[flag] = isEnabled === 'true';
  return acc;
}, {});

if (featureFlags['NewFeature']) {
  // Logic to enable the new feature
  console.log('New Feature enabled');
}
```

This approach enables applications to be more flexible and responsive to business needs as feature toggles can be managed through DNS.

### DNS Server Implementation

`@push.rocks/smartdns` includes powerful features that allow you to implement your very own DNS server, complete with UDP and HTTPS protocols support and DNSSEC compliance.

#### Basic DNS Server Example

Implementing a DNS server involves setting it up to respond to various DNS queries. Here's how you can set up a basic DNS server using UDP and HTTPS protocols:

```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'));
```

This sets up a basic DNS server responding to A records for the domain `example.com` and mirrors the common structure used in production applications.

### DNSSEC Support

DNS Security Extensions (DNSSEC) adds an additional layer of security to DNS, protecting against various types of attacks. With `@push.rocks/smartdns`, setting up a DNS server with DNSSEC is straightforward.

#### DNSSEC Configuration

To configure DNSSEC for your DNS server, you’ll need to establish DNSSEC parameters including zone signatures and enabling key management. This setup ensures that DNS records are signed and can be verified for authenticity.

```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'));
```

### Handling DNS Queries Over Different Protocols

The library supports handling DNS queries over UDP and HTTPS. This functionality allows for the flexible use and management of DNS inquiries and resolves, accommodating various protocol needs.

#### Handling UDP Queries

UDP is the traditional DNS protocol used for quick, non-persistent queries. Here’s how you can set up a DNS server to respond to UDP queries:

```typescript
import { DnsServer } from '@push.rocks/smartdns';
import dgram from 'dgram';

const dnsServer = new DnsServer({
  udpPort: 53,
  httpsPort: 443,
});

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');
```

This segment of code creates a UDP server that listens for incoming DNS requests and responds accordingly.

#### Handling HTTPS Queries

DNS over HTTPS (DoH) offers a heightened level of privacy and security, where DNS queries are transmitted over HTTPS to prevent eavesdropping and man-in-the-middle attacks.

```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();
```

This ensures that DNS requests can be securely transmitted over the web, maintaining privacy for the clients querying the DNS server.

### Testing

Like any crucial application component, DNS servers require thorough testing to ensure reliability and correctness in different scenarios. Here we use TAP (Test Anything Protocol) to test various functionalities.

#### DNS Server Tests

`@push.rocks/smartdns` integrates seamlessly with TAP, allowing for comprehensive testing of server functionalities.

Here's an example of how you might set up tests for your DNS server:

```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 () => {
  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();
```

The above tests ensure that the DNS server setup, query handling, and proper stopping of the server are all functioning as intended.

In a realistic production environment, additional tests would include edge cases such as malformed requests, large queries, concurrent access handling, and integration tests with various DNS resolvers. These tests ensure robustness and reliability of DNS services provided by the server.

This comprehensive guide demonstrates how to implement, manage, and test a DNS server using `@push.rocks/smartdns`, making it an ideal tool for developers tasked with handling DNS management and setup in TypeScript projects. The library supports the full scope of DNS operations needed for modern applications, from basic record query to full-scale DNS server operations with advanced security extensions.

## 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. 

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

### Company Information

Task Venture Capital GmbH  
Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.