ipns

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

• 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
• License

Install

npm install ipns

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

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,
  validityType: 0,
  validity: Uint8Array,
  sequence: 2
}

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.

License

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

Changelog

1.0.0 (2022-04-13)

⚠ BREAKING CHANGES

• this module is now ESM-only

Features

• convert to typescript (#154) (dd308f0)

chore

• update deps (#149) (87068ad)

BREAKING CHANGES

• requires node 15+