ipns

ipns record definitions

Table of contents

• Install
  • Browser <script> tag
• Lead Maintainer
• Usage
  • • Create record
    • Validate record
    • Embed public key to record
    • Extract public key from record
    • Datastore key
    • Marshal data with proto buffer
    • Unmarshal data from proto buffer
    • Validator
• API
  • • Create record
    • Validate record
    • Datastore key
    • Marshal data with proto buffer
    • Unmarshal data from proto buffer
    • Embed public key to record
    • Extract public key from record
    • Namespace
• Contribute
• API Docs
• License
• Contribute

Install

$ npm i ipns

Browser <script> tag

Loading this module through a script tag will make it's exports available as Ipns in the global namespace.

<script src="https://unpkg.com/ipns/dist/index.min.js"></script>

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

Lead Maintainer

Vasco Santos.

Usage

Create record

import * as ipns from 'ipns'

const entryData = await ipns.create(privateKey, value, sequenceNumber, lifetime)

Validate record

import * as ipns from 'ipns'

await ipns.validate(publicKey, ipnsEntry)
// if no error thrown, the record is valid

Embed public key to record

import * as ipns from 'ipns'

const ipnsEntryWithEmbedPublicKey = await ipns.embedPublicKey(publicKey, ipnsEntry)

Extract public key from record

import * as ipns from 'ipns'

const publicKey = ipns.extractPublicKey(peerId, ipnsEntry)

Datastore key

import * as ipns from '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

import * as ipns from 'ipns'

const entryData = await ipns.create(privateKey, value, sequenceNumber, lifetime)
// ...
const marshalledData = ipns.marshal(entryData)
// ...

Returns the entry data serialized.

Unmarshal data from proto buffer

import * as ipns from 'ipns'

const data = ipns.unmarshal(storedData)

Returns the entry data structure after being serialized.

Validator

import * as ipns from 'ipns'

const validator = ipns.validator

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

The validate async 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 (signatureV2 of CBOR data is 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.

API

Create record

ipns.create(privateKey, value, sequenceNumber, lifetime)

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

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

Returns a Promise that resolves to an object with the entry's properties eg:

{
  value: Uint8Array,
  signature: Uint8Array, // V1 (legacy, ignored)
  validityType: 0,
  validity: Uint8Array,
  sequence: 2,
  signatureV2: Uint8Array, // V2 signature of data field
  data: Uint8Array // DAG-CBOR that was signed
}

Validate record

ipns.validate(publicKey, ipnsEntry)

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).

Returns a Promise, which may be rejected if the validation was not 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 (Uint8Array): ipns entry record serialized.

Embed public key to record

const recordWithPublicKey = await ipns.embedPublicKey(publicKey, ipnsEntry)

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).

Returns a Promise. If the promise resolves to null it means the public key can be extracted directly from the peer-id.

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).

The returned 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.

API Docs

• https://ipfs.github.io/js-ipns

License

Licensed under either of

• Apache 2.0, (LICENSE-APACHE / http://www.apache.org/licenses/LICENSE-2.0)
• MIT (LICENSE-MIT / http://opensource.org/licenses/MIT)

Contribute

Contributions welcome! Please check out the issues.

Also see our contributing document for more information on how we work, and about contributing in general.

Please be aware that all interactions related to this repo are subject to the IPFS Code of Conduct.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.