haraka-tld/README.md

Haraka TLD utilities

[![Build Status][ci-img]][ci-url]
[![Code Coverage][cov-img]][cov-url]
[![Code Quality][qlty-img]][qlty-url]

# haraka-tld

Haraka TLD utilities

## Installation

```sh
npm install haraka-tld
```

## Usage

```js
const tlds = require('haraka-tld')
if (tlds.get_organizational_domain('mail.example.com') === 'example.com') {
  // do something
}
```

## Functions exported

### get_organizational_domain

Reduces a hostname to an Organizational Domain.

The O.D. is the portion of a domain name immediately delegated by a registrar and the portion that is no longer 'Public'

    com               <-- TLD (or Public Suffix)
    example.com       <-- Organizational Domain
    mail.example.com  <-- hostmame

get_organizational_domain('mail.example.com'); // -> example.com

### Haraka usage example:

```js
const tlds = require('haraka-tld')
const from_dom = tlds.get_organizational_domain(connection.transaction.mail_from.host)
const to_dom = tlds.get_organizational_domain(connection.transaction.rcpt_to.host)
if (from_dom == to_dom) {
  // the envelope sender domain matches the envelope receiver domain
  // eg: root@mail.example.com would match sysadmin@example.com
}
```

### split_hostname

Split FQDN to host and domain

```js
const split = tlds.split_hostname('host.sub1.sub2.domain.com')
// split[0] = 'host.sub1.sub2';
// split[1] = 'domain.com';
```

### asParts

Splits the FQDN into domain boundaries:

```js
tlds.asParts('host.sub1.sub2.domain.com')
```

returns:

```js
{
  tld: 'com',
  org: 'domain',
  host: 'host.sub1.sub2'
}
```

### is_public_suffix

    if (tlds.is_public_suffix('com')) {
        // true
    }
    if (tlds.is_public_suffix('wikipedia.org')) {
        // false
    }

## Directly access lists

### Check for a TLD

    if (tlds.top_level_tlds.has('com')) {
        // true
    }

`top_level_tlds`, `two_level_tlds`, and `three_level_tlds` are `Set`s;
`public_suffix_list` is a `Map`. Use `.has(name)` for membership checks.

## The following files are included

- public-suffix-list

A list of all Public Suffixes (the parts of a domain name exactly
one level below the registrar). Includes punycoded international domains, is
maintained by the Mozilla project, and accomplishes roughly the same task
as the \*-tlds files.

- top-level-tlds

The list of TLDs valid on the internet. [Update URL](http://data.iana.org/TLD/tlds-alpha-by-domain.txt)

- two-level-tlds

A list of 2nd level TLDs. [Update URL](http://www.surbl.org/static/two-level-tlds)

- three-level-tlds

A list of 3rd level TLDs. [Update URL](http://www.surbl.org/tld/three-level-tlds)

- extra-tlds

This allows for additional 2nd and 3rd level TLDs from a single file. Used for site customizations or for the URIBL hosters.txt. [Update URL](http://rss.uribl.com/hosters/hosters.txt)

## Updating

- update the TLD files with `./update_tld_files`
- use the .release scripts to roll a new release. If the .release dir is empty (first time), populate it with `git submodule update --init --recursive`.

```sh
.release/start.sh patch
$edit CHANGELOG.md
git add . && git commit
.release/submit.sh
```

[ci-img]: https://github.com/haraka/haraka-tld/actions/workflows/ci.yml/badge.svg
[ci-url]: https://github.com/haraka/haraka-tld/actions/workflows/ci.yml
[cov-img]: https://codecov.io/github/haraka/haraka-tld/coverage.svg
[cov-url]: https://codecov.io/github/haraka/haraka-tld
[qlty-img]: https://qlty.sh/gh/haraka/projects/haraka-tld/maintainability.svg
[qlty-url]: https://qlty.sh/gh/haraka/projects/haraka-tld