dappy-lookup

A library written in Typescript that resolves names from Dappy name system (DappyNS).

DappyNS is a next generation name system which:

• Is compliant with DNS RFC 1035
• Security-first designed by implementing DNS over HTTPS (RFC 8484)
• Persisted and distributed by blockchain RChain
• Enable clients to query in a trustless manner name records on the blockchain using:
  • A network of dappy name servers highly secured
  • A co-resolution mecanism to distribute the trust over the network

DappyNS is a trustless and secure way to distribute your public data with your partners, clients or devices (IOT). PKI certificates are good candidates. DappyNS can also help to organize and publish your DAO data due to to its hierarchical nature.

DappyNS documentation

You can find documentation here.

Installing

Node.js

npm i -S dappy-lookup

You don't have a dappy name ? Mint in one.

Using dappy-cli ...

Examples

Stand-alone dappy lookup

Here is an example to get you started:

import { lookup } from 'dappy-lookup';

async function run() {
    // lookup the A records for example.dappy on d network
    const recordsA = await lookup('example.dappy', 'A');
    console.log(recordsA);

    // lookup the AAAA records for example.dappy on d network
    const recordsAAAA = await lookup('example.dappy', 'AAAA');
    console.log(recordsAAAA);

    // lookup the CERT records for example.dappy on d network
    const recordsCERT = await lookup('example.dappy', 'CERT');
    console.log(recordsCERT);
});

run();

This example above will resolve a name on default dappy network which is the d network, which is the DappyNS production ready network.

Next example do the same but on gamma network (used for testing purposes)

import { lookup } from 'dappy-lookup';

async function run() {
    // lookup the A records for example.dappy on gamma network
    const recordA = await lookup('example.dappy', 'A', { network: 'gamma' });
    console.log(recordA);
});

run();

NodeJS request using dappy-lookup with CA certificate retrieval

It's a really a pain point to get a valid CA certificate and to install it at operating system level.

On DappyNS, name servers not only distribute IPv4 (A records) and IPv6 addresses (AAAA records) but also certificates to trust over CERT records (alternative of DANE). It enable dappy-lookup client to fetch dynamically and in a trusted manner (using coresolution mecanism) CA certificates.

The example below demonstrates how to do this:

import { lookup, nodeLookup } from 'dappy-lookup';

https.get('https://example.dappy/', {
    lookup: nodeLookup,
    ca: await lookup('example.dappy', 'CERT'),
}, (res) => {
  ...
});

NodeJS enables to override lookup function for HTTP and HTTPS native modules.

So dappy-lookup provide a lookup function (created with nodeLookup) with the same signature as dns.lookup provided by NodeJS.

NodeJS requests using dappy-lookup

The example below shows how to replace native NodeJS lookup function with the dappy-lookup equivalent function. In this example the certificate is not recovered dynamically, it is installed previously on the operating system.

import { nodeLookup } from 'dappy-lookup';

https.get('https://example.dappy/', {
    lookup: nodeLookup,
}, (res) => {
  ...
});

API

lookup()

function lookup(
  name: string,
  recordType: 'A' | 'AAAA' | 'CERT',
  options: {
    cacheMaxHit: number;
    cacheTTL: number;
    dappyNetwork: 'd' | 'gamma';
  }
) =>
  Promise<NamePacket>;

export type NamePacket = {
  version: string;
  type: 'query' | 'response';
  rcode: ReturnCode;
  id?: number;
  flags: number;
  questions: {
    type: 'A' | 'AAAA' | 'CERT';
    class: 'IN';
    name: string;
  }[];
  answers: {
    type: 'A' | 'AAAA' | 'CERT';
    class: 'IN';
    name: string;
    ttl: number;
    data: string;
  }[];
  additionals: [];
  authorities: [];
};

export enum ReturnCode {
  NOERROR, // DNS Query completed successfully
  FORMERR, //  DNS Query Format Error
  SERVFAIL, // Server failed to complete the DNS request
  NXDOMAIN, //  Domain name does not exist.
  NOTIMP, //  Function not implemented
  REFUSED, // The server refused to answer for the query
  YXDOMAIN, //  Name that should not exist, does exist
  XRRSET, //  RRset that should not exist, does exist
  NOTAUTH, //  Server not authoritative for the zone
  NOTZONE, //  Name not in zone
}

Resolve A record on DappyNS.

Example:

const recordA = await lookup('example.dappy', 'A');
console.log(recordA);

nodeLookup()

 function nodeLookup(
    name: string,
    options?: {
      all?: boolean;
      family?: number;
      hints?: number;
      verbatim?: boolean;
    },
    callback: (err: Error, address: string, family: number) => void;
  ) => void;
}

lookup() can be used by HTTP and HTTPS NodeJS modules to resolve names.

Example:

import { nodeLookup, lookup } from 'dappy-lookup';

https.get('https://example.dappy', {
  lookup: nodeLookup,
  ca: await lookup('example.dappy', 'CERT'),
}, (res) => {
  ...
});