dirkmc/js-ipns

Utilities for creating, parsing, and validating IPNS records

IPNS

ipns record definitions

This module contains all the necessary code for creating, understanding and validating IPNS records.

Lead Maintainer

Vasco Santos.

Table of Contents

• Install
• Usage
  • Create Record
  • Validate Record
  • Embed public key to record
  • Extract public key from record
  • Datastore key
• API
• Contribute
• License

Install

npm install ipns

Usage

Create record

const ipns = require('ipns')

ipns.create(privateKey, value, sequenceNumber, lifetime, (err, entryData) => {
  // your code goes here
})

Validate record

const ipns = require('ipns')

ipns.validate(publicKey, ipnsEntry, (err) => {
  // your code goes here
  // if no error, the record is valid
})

Embed public key to record

const ipns = require('ipns')

ipns.embedPublicKey(publicKey, ipnsEntry, (err, ipnsEntryWithEmbedPublicKey) => {
  // your code goes here
})

Extract public key from record

const ipns = require('ipns')

ipns.extractPublicKey(peerId, ipnsEntry, (err, publicKey) => {
  // your code goes here
})

Datastore key

const ipns = require('ipns')

ipns.getLocalKey(peerId)

Returns a key to be used for storing the ipns entry locally, that is:

/ipns/${base32(<HASH>)}

Marshal data with proto buffer

const ipns = require('ipns')

ipns.create(privateKey, value, sequenceNumber, lifetime, (err, entryData) => {
  // ...
  const marshalledData = ipns.marshal(entryData)
  // ...
})

Returns the entry data serialized.

Unmarshal data from proto buffer

const ipns = require('ipns')

const data = ipns.unmarshal(storedData)

Returns the entry data structure after being serialized.

Validator

const ipns = require('ipns')

const validator = ipns.validator

Contains an object with validate (marshalledData, key, callback) and select (dataA, dataB, [callback]) functions.

The validate function aims to verify if an IPNS record is valid. First the record is unmarshalled, then the public key is obtained and finally the record is validated (signature and validity are verified).

The select function is responsible for deciding which ipns record is the best (newer) between two records. Both records are unmarshalled and their sequence numbers are compared. If the first record provided is the newer, the operation result will be 0, otherwise the operation result will be 1. If a callback is not provided, the response is returned.

API

Create record

ipns.create(privateKey, value, sequenceNumber, lifetime, [callback])

Create an IPNS record for being stored in a protocol buffer.

• privateKey (PrivKey RSA Instance): key to be used for cryptographic operations.
• value (string): ipfs path of the object to be published.
• sequenceNumber (Number): number representing the current version of the record.
• lifetime (string): lifetime of the record (in milliseconds).
• callback (function): operation result.

callback must follow function (err, ipnsEntry) {} signature, where err is an error if the operation was not successful. ipnsEntry is an object that contains the entry's properties, such as:

{
  value: '/ipfs/QmWEekX7EZLUd9VXRNMRXW3LXe4F6x7mB8oPxY5XLptrBq',
  signature: Buffer,
  validityType: 0,
  validity: '2018-06-27T14:49:14.074000000Z',
  sequence: 2
}

Validate record

ipns.validate(publicKey, ipnsEntry, [callback])

Validate an IPNS record previously stored in a protocol buffer.

• publicKey (PubKey RSA Instance): key to be used for cryptographic operations.
• ipnsEntry (Object): ipns entry record (obtained using the create function).
• callback (function): operation result.

callback must follow function (err) {} signature, where err is an error if the operation was not successful. This way, if no error, the validation was successful.

Datastore key

ipns.getDatastoreKey(peerId)

Get a key for storing the ipns entry in the datastore.

• peerId (Uint8Array): peer identifier.

Marshal data with proto buffer

const marshalledData = ipns.marshal(entryData)

Returns the entry data serialized.

• entryData (Object): ipns entry record (obtained using the create function).

Unmarshal data from proto buffer

const data = ipns.unmarshal(storedData)

Returns the entry data structure after being serialized.

• storedData (Buffer): ipns entry record serialized.

Embed public key to record

ipns.embedPublicKey(publicKey, ipnsEntry, [callback])

Embed a public key in an IPNS entry. If it is possible to extract the public key from the peer-id, there is no need to embed.

• publicKey (PubKey RSA Instance): key to be used for cryptographic operations.
• ipnsEntry (Object): ipns entry record (obtained using the create function).
• callback (function): operation result.

callback must follow function (err, resultEntry) {} signature, where err is an error if the operation was not successful. This way, if no error, the operation was successful. If the resultEntry is also null, the peer-id allows to extract the public key from the peer-id and there is no need in extracting it.

Extract public key from record

ipns.extractPublicKey(peerId, ipnsEntry, [callback])

Extract a public key from an IPNS entry.

• peerId (PeerId Instance): peer identifier object.
• ipnsEntry (Object): ipns entry record (obtained using the create function).
• callback (function): operation result.

callback must follow function (err, publicKey) {} signature, where err is an error if the operation was not successful. This way, if no error, the validation was successful. The public key (PubKey RSA Instance): may be used for cryptographic operations.

Namespace

Namespace constants for records.

ipns.namespace

// '/ipns/'

ipns.namespaceLength

// 6

Contribute

Feel free to join in. All welcome. Open an issue!

This repository falls under the IPFS Code of Conduct.

License

Copyright (c) Protocol Labs, Inc. under the MIT License. See LICENSE file for details.