node-epp

    1.0.10 • Public • Published

    nodepp

    An EPP implementation in node.js

    Docker Repository on Quay.io

    Build Status

    Description

    This is a service for communicating with registries over EPP. It takes datastructures in JSON, converts them to XML, sends them to the registry, and then does the whole thing in reverse with the response.

    There are two separate server scripts:

    1. lib/node-epp-server.js is designed to function as a RESTful interface where you can POST and receive json requests.
    2. lib/rabbit-epp.js, runs as an RPC server that accepts requests via RabbitMQ.

    Installation

    1. Clone the repository: git clone https://github.com/heytrav/nodepp.git.
    2. cd nodepp
    3. npm install to install node dependencies.
    4. source nodepp.rc to include ./node_modules/.bin in the $PATH. This is necessary for testing or if you plan on running it as a daemon.

    Configuration

    In config/epp-config-example.json you'll find something that looks like this:

    {
        "registries": {
            "registry-test1": {
              // registry1 data
            },
            "registry-test2": {
              // registry2
            }
        },
        "rabbitmq": {
            "connection": {
              // RabbitMQ connection
            }
        },
        "whitelisted_ips": []
    }

    For your development and production environments, I recommend copying this file to config/epp-config-devel.json and config/epp-config-production.json, respectively, and modifying each to fit your needs. You will need to add your own login/password as well as the paths to any SSL certificates and keys. You can of course replace the keys registry-test1, registry-test2, etc. with something more descriptive of the registry.

    When you've got the config setup the way you like it, symlink this to config/epp-config.json to run the application.

    ln -s <path to app>/config/epp-config-devel.json <path to app>/config/epp-config.json
    

    You can add as many registries as you like. You may even need to add the same registry multiple times with different logins, etc. This is practical for testing if you need to simulate transferring domains between two separate registrars.

    The whitelisted_ips tells the REST application to only accept certain hosts.

    Testing

        npm test
    

    Note that a number of tests are currently set to skip automatically. These require a running RabbitMQ instance and that you have set up the configuration accordingly. They also assume that you have an online testing environment (OTE) account with some registry or registrar.

    Running the web service

    The REST app is based on express.js and listens for POST requests on port 3000. The general URL scheme is as follows:

    http://<host>:3000/command/<registry>/<command>
    

    So to run a checkDomain for registry1 on a local instance of the server, POST your request to:

    http://localhost:3000/command/registry1/checkDomain
    

    You can start it as follows:

    node lib/node-epp-server.js -r registry1 -r registry2
    

    The -r option specifies which registries the script should log into and can be used multiple times. These should correspond to the registries listed in the configuration file. In this case, the client will log into into registry1 and registry2.

    Alternatively you can start it as a daemon:

    foreverd start -o nodepp-stout.log -e nodepp-sterr.log lib/node-epp-server.js \
        -r registry-test1 -r registry-test2 -r registry-test3
    

    This tells it to open connections to three different registries.

    To stop the service:

    foreverd stop lib/node-epp-server.js
    

    You can test the script by posting JSON requests to the server instance. I recommend using the program Postman which can be installed in Chrome/Firefox as an extension. However, you can also use curl or the scripting language of your choice. I put an example of this down below.

    Running the RabbitMQ service

    This is a RPC service that listens for connections on RabbitMQ. Have a look at the rabbitmq section of the configuration file if you would like to run this. To run the application:

    node lib/rabbit-epp.js -r registry-test1
    

    Or as a daemon:

    foreverd start -o nodepp-stout.log -e nodepp-sterr.log lib/rabbit-epp.js \
        -r registry-test1 -r registry-test2 -r registry-test3
    

    To stop it:

    foreverd stop lib/rabbit-epp.js
    

    Note that for all commands documented below, the datastructure that is sent via RabbitMQ needs to be modified as follows:

     {
        "command": "<command name>",
        "data": <request data>
     }
    

    I wrote some scripts for interacting with the RabbitMQ service in my epp-reg project. Feel free to use those as you like.

    EPP Commands

    checkContact

    {"id": "P-12345xyz"}

    or

    {"contact": "P-12345xyz"}

    infoContact

    {"id": "P-12345xyz"}

    or

    {"contact": "P-12345xyz"}

    createContact

    {
        "id": "my-id-1234",
        "voice": "+1.9405551234",
        "fax": "+1.9405551233",
        "email": "john.doe@null.com",
        "authInfo": {
            "pw": "xyz123"
        },
        "postalInfo": [{
            "name": "John Doe",
            "org": "Example Ltd",
            "type": "int",
            "addr": [{
                "street": ["742 Evergreen Terrace", "Apt b"],
                "city": "Springfield",
                "sp": "OR",
                "pc": "97801",
                "cc": "US"
            }]
        }]
    }

    Some registries set the id by default. In such cases it's common to use auto. The value for type may also vary for different registries. Some require loc and some require int. EPP allows for up to 2 postaInfo entries, however I've never seen a registry that accepts more than 1. For that reason, you can just specify it as a single object:

    "postalInfo": {
        "name": "John Doe",
        "org": "Example Ltd",
        "type": "int",
        "addr": [{
            "street": ["742 Evergreen Terrace", "Apt b"],
            "city": "Springfield",
            "sp": "OR",
            "pc": "97801",
            "cc": "US"
        }]
    }

    It will be passed to the registry in the appropriate format. The same applies to the addr field (in postalInfo), which can also be specified as an Array or single object.

    "addr": {
        "street": ["742 Evergreen Terrace", "Apt b"],
        "city": "Springfield",
        "sp": "OR",
        "pc": "97801",
        "cc": "US"
    }

    updateContact

    {
        id: "p-12345",
        add: ['clientDeleteProhibited'],
        rem: ['clientTransferProhibited'],
        chg: {
            "postalInfo": [{
                "name": "John Doe",
                "org": "Example Ltd",
                "type": "loc",
                "addr": [{
                    "street": ["742 Evergreen Terrace", "Apt b"],
                    "city": "Eugene",
                    "sp": "OR",
                    "pc": "97801",
                    "cc": "US"
                }]
            }],
            "voice": "+1.9405551234",
            "fax": "+1.9405551233",
            "email": "john.doe@null.com",
            "authInfo": {
                "pw": "xyz123"
            },
            "disclose": {
                "flag": 0,
                "disclosing": ["voice", "email"]
            }
        }
    }

    checkDomain

    The following are equivalent:

    {"domain": "something.com"}

    or

    {"name": "something.com"}

    It is possible to check more than one domain at a time.

            {"domain": ["test-domain.com", "test-domain2.com", "test-domain3.com"]}

    infoDomain

            {"domain": "something.com"}

    In case you are wondering if you can send multiple domains like in checkDomain, the answer is no. That's not possible in EPP. The result that you will get back in one infoDomain will be complicated enough.

    createDomain

    {
        "name": "iwmn-test-101-domain.com",
        "period": {
            "unit": "y",
            "value": 1
        },
        "ns":[
            "ns1.hexonet.net",
            "ns2.hexonet.net"
        ],
            "registrant": "my-id-1234",
        "contact": [
            { "admin": "my-id-1235" },
            { "tech": "my-id-1236" },
            {"billing": "my-id-1236"}
        ],
        "authInfo": {
            "pw": "Axri3k.XXjp"
        }
    }

    See comments below regarding alternative formats for ns, period, and authInfo fields.

    deleteDomain

            {"domain": "something.com"}

    renewDomain

    {
        "domain": "something.com",
        "curExpDate": "2016-04-03",
        "period": {
            "unit": 'y',
            "value": 1
        }
    }

    period is optional and will default to 1 year.

    transferDomain

    {
        "name": "test-domain.com",
        "op": "request",
        "period": 1,
        "authInfo": {
            "roid": "P-12345", // optional
            "pw": "2fooBAR"
        }
    }

    Valid values for op are approve, cancel, query, reject, and request. There uses are:

    • Requesting side

      1. request to request a transfer.
      2. cancel to cancel a transfer.
      3. query to find out if a transfer is pending (although we should get info via polling)
    • Domain holder side

      1. approve to approve a transfer request from another registrar.
      2. reject to reject a transfer request from another registrar.

    updateDomain

    {
        "name": "test-domain.com",
        "add": {
            "ns": ["ns3.test.com", "ns4.whatever.com"],
            "contact": [{
                "admin": "P-9876"
            },
            {
                "billing": "PX143"
            }],
            "status": ["clientUpdateProhibited", {
                "s": "clientHold",
                "lang": "en",
                "value": "Payment Overdue"
            }]
        },
        "rem": {
            "ns": [{
                "host": "ns1.test-domain.com",
                "addr": {
                    "type": "v4",
                    "ip": "192.68.2.132"
                }
            }],
            "contact": [{
                "billing": "PX147"
            }],
            "status": ["clientTransferProhibited", {
                "s": "clientWhatever",
                "lang": "en",
                "value": "Payment Overdue"
            }]
        },
        "chg": {
            "registrant": "P-49023",
            "authInfo": {
                "pw": "TestPass2"
            }
        }
    }

    This is a very complicated example but at least shows what is possible in an updateDomain. At least 1 of add, rem, or chg is required. The chg field, if provided, must contain either a registrant and/or an authInfo. add and rem elements, if provided, must contain any one or more ns, contact, or status fields.

    createHost

    {
        "name": "ns1.host.com",
        "addr": ["23.84.43.123", {
            "ip": "22.4.22.5"
        },
        {
            "ip": "::F3:34::BA:",
            "type": "v6"
        }]
    }

    updateHost

    {
        "name": "ns1.host.com",
        "chg": {
            "name": "ns2.host.com",
        },
        "add": {
            "addr": {
                "ip": "::F3:34::BA:",
                "type": "v6"
            },
            "status": ["clientUpdateProhibited"]
        },
        "rem": {
            "addr": ["23.84.43.123", {
                "ip": "22.4.22.5"
            }],
            "status": ["clientTransferProhibited", "sneezeAchoo"]
        }
    }

    General stuff

    Some of the required datastructures might seem a bit weird. EPP has a fairly complex grammar that is probably intended to make granular control of domain related entities possible. There are no flat datastructures and some things must be specified explicitly that would be assumed in systems that use key=value APIs. For example, to remove nameservers from a domain, it is necessary to remove them explicitly. Simply updating domain with the new nameservers will not work. The same goes for contact objects.

    Host objects

    In createDomain and updateDomain I've tried to account for 2 different types of host objects. In the simplest version you can just pass an array of strings:

        ["ns1.host.com", "ns2.host.tld"]

    In cases where IP addresses are required, the following variants can be used:

        [{host: "ns1.host.com", addr: "62.47.23.1"}]
        [{host: "ns2.host.com", addr:[ "62.47.23.1", {ip: "53.23.1.3"}    ]}]
        [{host: "ns3.host.com", addr:[ {ip: "::F3:E2:23:::", type: "v6"}, {ip:"47.23.43.1", type: "v4"} ]}]

    type is v4 by default. You'll have to specify v6 explicitly for IPv6 addresses.

    It's up to you to know which cases glue records are required. This implementation has no way to know that.

    authInfo

    createContact, createDomain, transferDomain and updateDomain accept an authInfo parameter.

    Following are equivalent:

        authInfo: "te2tP422t"

    or

        authInfo: {
            pw: "te2tP422t"
        }

    In some cases you may need to supply a roid in addition to the authInfo. This is used to identify the registrant or contact object if and only if the given authInfo is associated with a registrant or contact object, and not the domain object itself.

    authInfo: {
            pw: "te2tP422t",
            roid: "P-1234"
    }

    period

    The period argument in createDomain, renewDomain and transferDomain can be specified as follows:

    1 year registration

    period: 1

    24 month registration

    period: {
        unit: "m",
        value: 24
    }

    The default unit is y for year and default period is 1.

    transactionId

    A transactionId is optional. It can be added at the top level of the JSON data structure. By default it will be set to iwmn-<epoch timestamp>.

    Extensions

    You can optionally add an extension property to some commands. This varies from registry to registry like everything else. A good example is when adding DNSSEC data to a createDomain:

    {
        "name": "iwmn-test-101-domain.com",
        "period": {
            "unit": "y",
            "value": 1
        },
        "ns":["ns1.hexonet.net","ns2.hexonet.net"],
            "registrant": "my-id-1234",
        "contact": [
            { "admin": "my-id-1235" },
            { "tech": "my-id-1236" },
            {"billing": "my-id-1236"}
        ],
        "authInfo": {
            "pw": "Axri3k.XXjp"
        },
        "extension": {
            "DNSSEC": {
                "maxSigLife": 604800,
                "dsData": {
                    "keyTag": 12345,
                    "alg": 3,
                    "digestType": 1,
                    "digest": "49FD46E6C4B45C55D4AC",
                    "keyData": {
                        "flags": 257,
                        "protocol": 3,
                        "alg": 1,
                        "pubKey": "AQPJ////4Q=="
                    }
                }
            }
        }
    }

    DNSSEC

    I've implemented DNSSEC EPP generation for create and update.

    Following are some variations that you can send (I'm leaving out the standard part of the EPP request):

    createDomain

    Create a domain with the dsData interface:

    "extension": {
        "DNSSEC": {
            "maxSigLife": 604800,
            "dsData": {
                "keyTag": 12345,
                "alg": 3,
                "digestType": 1,
                "digest": "49FD46E6C4B45C55D4AC"
            }
        }
    }

    with the keyData interface:

    "extension": {
        "DNSSEC": {
            "keyData":{
                "flags": 257,
                "protocol": 3,
                "alg": 1,
                "pubKey": "AQPJ////4Q=="
            }
        }
    }

    with the keyData in the dsData element:

    "extension": {
        "DNSSEC": {
            "maxSigLife": 604800,
            "dsData": {
                "keyTag": 12345,
                "alg": 3,
                "digestType": 1,
                "digest": "49FD46E6C4B45C55D4AC",
                "keyData":{
                    "flags": 257,
                    "protocol": 3,
                    "alg": 1,
                    "pubKey": "AQPJ////4Q=="
                }
            }
        }
    }

    updateDomain

    Add a dsData key and remove a keyData key and change the maxSigLife of the key

    "extension": {
        "DNSSEC": {
            "add": {
                "dsData": {
                    "keyTag": 12345,
                    "alg": 3,
                    "digestType": 1,
                    "digest": "49FD46E6C4B45C55D4AC"
                }
            },
            "rem": {
                "keyData": {
                    "flags": 257,
                    "protocol": 3,
                    "alg": 1,
                    "pubKey": "AQPJ////4Q=="
                }
            },
            "chg": {
                "maxSigLife": 604800
            }
        }
    }

    Remove all existing key info and replace it with something new:

    "extension": {
        "DNSSEC": {
            "rem": {
                "all": true
            },
            "add": {
                "dsData": {
                    "keyTag": 12345,
                    "alg": 3,
                    "digestType": 1,
                    "digest": "49FD46E6C4B45C55D4AC"
                }
            }
        }
    }

    Example usage

    Post the following to http://localhost:3000/command/hexonet/checkDomain

    prompt$ time curl -H "Content-Type: application/json" \
        -d '{"domain": "test-domain.com"}'  \
                http://localhost:3000/command/<registry>/checkDomain
    

    Note I just put time in there to show what the execution time is. YMMV

    You should get the following response (or something similar):

        "result":{
            "code":1000,"msg":"Command completed successfully"},
            "resData":{
                "domain:chkData": {
                    "xmlns:domain":"urn:ietf:params:xml:ns:domain-1.0",
                    "xsi:schemaLocation":"urn:ietf:params:xml:ns:domain-1.0 domain-1.0.xsd",
                "domain:cd":{
                    "domain:name":{
                        "avail":0,
                        "$t":"test-domain.com"
                        },
                    "domain:reason":"Domain exists"
                    }
                }
            },
    

    I plan to get rid of some of the EPP cruft in the near future.

    Install

    npm i node-epp

    DownloadsWeekly Downloads

    1

    Version

    1.0.10

    License

    ISC

    Last publish

    Collaborators

    • heytrav