byu-imaal / dohjs

DNS over HTTPS client for use in the browser

Javascript library for DNS over HTTPS lookups in web apps

---

Try sending DoH lookups from your browser - https://dohjs.org

Contents

• Why DoHjs
  • Features
• Installation
• Quickstart
• Examples
• Docs
• Tests
• Web interface
• CORS Issues
• License

Why dohjs

The purpose of dohjs is described well in the Internet standard document for DNS over HTTPS (RFC 8484):

allowing web applications to access DNS information via existing browser APIs in a safe way consistent with Cross Origin Resource Sharing (CORS)

Features

• Fully compliant DNS over HTTPS client implementation
• Supports GET and POST wireformat queries
• Command line DNS over HTTPS lookup tool
• Web interface to try dohjs
• CORS proxy to get past CORS errors associated with DoH (source code here). This is mainly for use on https://dohjs.org.

Installation

If you're not using npm, you can skip to quickstart.

npm install dohjs

If you want to just use the command line tool dohjs to issue DoH lookups, install it globally (or use npx):

npm install -g dohjs

NOTE: The above command may need to be run as root (how to fix this)

Quickstart

A simple way to start is to include doh.js in your HTML file. You can include it from jsdelivr or your local installation.

<!-- from CDN -->
<script src="https://cdn.jsdelivr.net/npm/dohjs@latest/dist/doh.min.js"></script>
<!-- from local installation -->
<script src="/path/to/node_modules/dohjs/dist/doh.min.js"></script>

If your project is mostly nodejs-style (e.g. you're using browserify), you can require() dohjs like so:

const doh = require('dohjs');

Now here's a quick example of a DoH lookup using dohjs:

// create your stub resolver
const resolver = new doh.DohResolver('https://1.1.1.1/dns-query');

// lookup the A records for example.com and log the IP addresses to the console
resolver.query('example.com', 'A')
  .then(response => {
    response.answers.forEach(ans => console.log(ans.data));
  })
  .catch(err => console.error(err));

Examples

Checkout our examples to see dohjs in action. See examples/README for a description of the examples.

To serve thr examples, run npm start. Your browser will open up to an index of your current directory, then just navigate to the examples and open whatever html file you were wanting to look at.

Docs

API documentation for dohjs can be found in docs/README.md.

Documentation for the dohjs CLI is in docs/cli.md.

Contributing

We love contributors!

If you find a bug in dohjs, or you have a feature you'd like added, please open an issue and/or submit a pull request.

Tests

To run tests, clone the repo, and run:

npm test

Web interface

The web interface is available at https://dohjs.org.

See the gh-pages branch for code.

CORS issues

You'll probably get some CORS errors when sending DoH queries. A few ways to get around those are:

• Use a CORS proxy. At dohjs.org, there is an option to use a CORS proxy if you want to try it out.
• Disable CORS when you launch your browser sometimes works (e.g. google-chrome --user-data-dir=/tmp/asdf --disable-web-security)
• Run your own DoH server that sets the Access-Control-Allow-Origin header appropriately (e.g. Access-Control-Allow-Origin: * to allow everyone)

License

MIT (see LICENSE)

dohjs's Issues

Support for URI queries?

I wasn't able to find URI queries in your API Documentation or examples. Does dohjs support this?

Use cases and examples

We need more example use cases for dohjs. For each example use case, we should do the following:

• Make a subdirectory in the examples directory that contains the example code
• Edit examples/README.md to explain the example use case

Possible use case(s) for dohjs:

• validate a user's email address (e.g. with an MX lookup and maybe a subsequent A lookup)

<doh-img> tag

Similar to <doh-script>, but to fetch images. We'll want to make <doh-img> allow usual img attributes (alt, width, height, etc) and just apply them to a child <img> element or something.

Example:

<doh-img src="https://example.com/my-image.png" 
 resolver="https://example.com/dns-query" 
 alt="asdf"></doh-img>

This will require looking into correct accept headers for images.

Add More Validation to Library (and expose it)

While working on the web interface, it seemed it'd be nice to validate fields in a more exact manner than blank vs. content. However, it seems like it may make more sense for validation to be in the library itself for use by any interface. A method per parameter (or maybe just a map of parameter -> regex) could be useful.

For example isValidQname(qname) returns true if qname is a valid domain (at least one . only A-Za-z0-9\-\.). It probably doesn't have to be perfect, but it should be sufficient for most cases and never classify something valid as invalid.

Interfaces and DoHjs itself can then use the method for validation.

Caching responses

It would probably help performance if we implemented some sort of caching of responses.

TypeError: transport.request is not a function

Installed withnpm install dohjs.

  import { DohResolver } from 'dohjs';
  const resolver = new DohResolver('https://1.1.1.1/dns-query');
  resolver.query('example.com', 'A')

and I get the error:

browserify should be replaced

Hi thank you, for this project!

It is possible to remove the dependency on browserify. There have been no updates from this package for a long time now

npm WARN deprecated [email protected]: The querystring API is considered Legacy. new code should use the URLSearchParams API instead.

Tests

We should probably have some tests for dohjs. I have an exceptionally lame test script written for the command line tool (https://github.com/byu-imaal/dohjs/blob/master/test.sh). We probably want some automated unit tests to run before and after merges. I know there are a bunch of javascript testing frameworks out there we could use.

Some Thoughts (maybe I'll work on them at some point)

• hint text for resolver is missing colon after https

• Could have some common resolvers in a combobox as well

• Method should be a combo box since there's only 2 options

• query type could also be a combo box, but with typing still

• include console error message in interface (looks like you'd have to hook the function)

• If there's a CORS error, automatically create CORS url and try again (notify user of change). Maybe this is insecure and not something that should be done.

• Could also be a checkbox to auto CORS-ify when needed.

set global resolver for all <doh-script> and related tags

Currently, you have to use the resolver attribute to specify the DoH resolver on a per-script basis.
It would be nice to be able to set a global DoH resolver for all the <doh-script> and any other <doh-whatever> tags on the page. Not sure how this would fit into dohjs, but I think it might be worth looking into.

Improve Suggestion Dropdowns

On Firefox there's no indication of a dropdown and it only appears on double click. An implementation that doesn't rely on browsers would be beneficial

<doh-style> tag

This will be similar to the <doh-script> tag, but allow you to fetch css instead of javascript.

Example:

<doh-style src="https://my-style.com/my-style.css" 
 resolver="https://example.com/dns-query"></doh-style>

How to query A and AAAA types at the same time

I need ipv4 and ipv6 at the same time, how to query A and AAAA types at the same time?

show different visualization color for DNSSEC-only versus DNSSEC+DANE

Currently:

• domains which only have DNSSEC are visualized with a green color padlock in the right side of the URL but.
• domains which have DNSSEC+DANE are also visualized with a green color padlock in the right side of the URL.

This is non-ideal. Now when I want to find out which one is it, I have to click the padlock to then see the popup saying DNSSEC or DNSSEC secured + DANE valid.

Feature request: Could you please show a different visualization that communicates that DNSSEC is good but DANE (which as DNSSEC as a prerequisite) is better?

Since very few websites currently are DANE secured, it would be nice if this add-on could contribute the encourage getting the best possible security (DANE) visualization. Maybe one or another user would contact the site owner and suggest adding DANE. Your add-on has certainly motivated me to start working on adding DANE support for all websites where I am a sysadmin, thank you!

Suggestion:

• DNSSEC-only domains: keep the currently used light green padlock
• DNSSEC+DANE domains: use a darker green, perhaps a bigger green field spelling out DANE

The implementation specifics (colors, styles) on how to have visual distinction are of course just the first thing coming to mind. If there are better ways to illustrate it, even better.

Uncaught TypeError: can't access property "length", buf is undefined if nameserver_url is invalid

If the nameserver_url is invalid (e.g. https://cloudflare-dns.com/dns-query-wrong) causing the server to return a non-200 (e.g. 404) DoHjs will error out with an unhandled type error causing makeQuery to never resolve nor reject.

You can test it on dohjs.org making any query to an invalid nameserver_url

Would be useful to reject the promise so i can handle the error accordingly without a try/catch

Only works on node 10 or later

Apparently it only works starting from node v10

ReferenceError: URL is not defined
at Promise (..../node_modules/dohjs/lib/index.js:175:5)

User-Agent version is incorrect

The version number for the default User-Agent header is hardcoded, and is currently out of date. It may be worth auto-updating this value during the build to match the value in the package.json file.

https://github.com/byu-imaal/dohjs/blob/ecf8077e628db214c183ebbedb10f17e83cde045/lib/index.js#L165

Feature request: DNSSEC validation

This is an incredibly useful library, but it still appears to leave the verification of RRSIG records to the application. Would/might/could this be considered in-scope?

(My use-case / the reason I'm interested in DoH in the first place is so I can access and inspect DNS data from a WebExtension, to check things like CAA and TLSA records against active connections.)

Add examples/enhanced support for different frameworks

Add example code and documentation for using different web frameworks. Also add enhanced support as appropriate (e.g. type hints) per framework.

Some frameworks we could focus on

• Angular
• React
• Vue

Improve results view in web interface

It’s not very pleasing to just get json text. Interface could be improve to use nested bootstrap lists of key, value pairs or something similar. It would also be beneficial to highlight important parts of the packet e.g. the answers.

Optionally save interface parameters to local storage

This would involve saving fields, such as the resolver URL and HTTPS method to local storage. This should be enabled via a checkbox (possible under the advanced dropdown in #12).

Support for DNS JSON API

Google and Cloudflare have DNS JSON APIs. I think I may already have some JavaScript code for sending them queries.

Improve About page contents

• Update about page to include info on package
• Update thanks section to include IMAAL

Expose more dnsPacket features in web interface

• DNSSEC_OK and ECS seem to be supported by dohjs already so those should be fairly easy.
• Bonus features would be adding arbitrary EDNS option (similar to dig with (opt_code, payload) tuples)
• Anything else outside of EDNS that could be beneficial? It gets tricky with adding features, but not going overboard allowing manipulation of every bit
• Could probably put these in an "advanced" drop down

Find real-world examples of more obscure records / verify dns-packet code

One concern right now is that we aren't entirely sure how dns-packet handles some of the more obscure records (e.g. DNSSEC records, HWINFO, SRV, ENDS). Knowing this would help us in certain cases like #13.

This issue could be tackled two ways:

1. Verify how the dns-packet code works and create sample json responses for each record type.
2. Find real world servers that have these records available.

The second option may be a bit more useful, but I don't know of an easy way to go about it.

Add a Timeout parameter

I would like to be able to specify a timeout in milliseconds for the DoH request.

There are some fetchWithTimeout(URL,Timeout) functions available online that would probably work just fine...

add functionality to just pass in a dnsPacket

When you need more granular control over your DNS queries, it'd be nice to be able to pass in a dnsPacket (see mafintosh/dns-packet). RIght now our dohLookup function has some of those options, but you can't set all of the flags, for example, or add custom EDNS options.

Maybe a function with three params:

1. where - the URL of the DoH provider (where to send the DNS query)
2. method - GET or POST
3. the dnsPacket