README

OCN Notary JavaScript Package

This readme contains specific information pertaining to the JavaScript package of the Open Charging Network Notary, including: how to test, build, publish, install and use.

This package is written in TypeScript to provide type definitions for developers.

Install

npm install @shareandcharge/ocn-notary

Usage

Signing a request:

First, create a request object containing the headers, url-encoded parameters and body of the OCPI request.

const Notary = require("@sharecharge/ocn-notary")

const request = {
    headers: {
        "X-Correlation-ID": "123"
        ...
    },
    body: {
        "id": "LOC1",
        ...
    }
}

Next, instantiate an empty notary object and sign the request with your Ethereum private key.

const notary = new Notary()
await notary.sign(request, privateKey)

The OCN-Signature is a base64-encoded, JSON serialized string of the Notary. Retrieving it is possible with the Notary's serialize method.

const ocnSignature = notary.serialize()
console.log(ocnSignature)
// eyJmaWVsZHMiOlsiJFsnaGVhZGVycyddWyd4LWNvcnJlbGF0aW9uLWlkJ10iLCIkWydoZWFkZXJzJ11bJ...

This string should be appended to your headers with the key OCN-Signature before sending a request to the Open Charging Network.

Verifying a request:

In order to verify the request, first deserialize the OCN-Signature header received from a counterparty.

const notary = Notary.deserialize(ocnSignature)

Then, call the verify method on the notary object with the headers, url-encoded parameters and body of the request received (see above for how this looks like).

const isValid = notary.verify(request)
console.log(isValid)
// true

Modifying a request:

It might be the case that an OCN node needs to modify a request before forwarding it to the recipient, such as in the case where the sender has specified a response_url. In order to do this, we can stash the values that will be changed:

const notary = Notary.deserialize(ocnSignature)
notary.stash({
    "$['body']['response_url']": "https://amazing.msp.org/commands/START_SESSION/42"
})

It is important to sign the new request afterwards:

await notary.sign(modifiedRequest, someOtherPrivateKey)

And finally, include the signature in the forwarded request by serializing the notary object:

headers["OCN-Signature"] = notary.serialize()

Usage no npm install needed!