filebase/js-ipns

Utilities for creating, parsing, and validating IPNS records

ipns

IPNS Record definitions

Table of contents

• Install
  • Browser <script> tag
• 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
  • Marshal data with proto buffer
  • Unmarshal data from proto buffer
  • Extract public key from record
  • Namespace
• 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.

Usage

Create record

import * as ipns from 'ipns'

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

Validate record

import * as ipns from 'ipns'

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

Embed public key to record

import * as ipns from 'ipns'

const ipnsRecordWithEmbeddedPublicKey = await ipns.embedPublicKey(publicKey, ipnsRecord)

Extract public key from record

import * as ipns from 'ipns'

const publicKey = await ipns.extractPublicKey(peerId, ipnsRecord)

Datastore key

import * as ipns from 'ipns'

ipns.getLocalKey(peerId)

Returns a key to be used for storing the IPNS record locally, that is:

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

Marshal data with proto buffer

import * as ipns from 'ipns'

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

Returns the record data serialized.

Unmarshal data from proto buffer

import * as ipns from 'ipns'

const ipnsRecord = ipns.unmarshal(storedData)

Returns the IPNSRecord after being deserialized.

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, options)

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

• privateKey (PrivateKey): 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 (Number): lifetime of the record (in milliseconds).
• options (CreateOptions): additional creation options.

Returns a Promise that resolves to an object with a IPNSRecord.

Validate record

ipns.validate(publicKey, ipnsRecord)

Validate an IPNS record previously stored in a protocol buffer.

• publicKey (PublicKey): key to be used for cryptographic operations.
• ipnsRecord (IPNSRecord): IPNS record (obtained using the create function).

Returns a Promise, which may be rejected if the validation was not successful.

Marshal data with proto buffer

const marshalledData = ipns.marshal(ipnsRecord)

Returns the serialized IPNS record.

• ipnsRecord (IPNSRecord): ipns record (obtained using the create function).

Unmarshal data from proto buffer

const data = ipns.unmarshal(storedData)

Returns a IPNSRecord after being serialized.

• storedData (Uint8Array): ipns record serialized.

Extract public key from record

const publicKey = await ipns.extractPublicKey(peerId, ipnsRecord)

Extract a public key from an IPNS record.

• peerId (PeerId): peer identifier object.
• ipnsRecord (IPNSRecord): ipns record (obtained using the create function).

Returns a Promise which resolves to public key (PublicKey ): may be used for cryptographic operations.

Namespace

Namespace constants for records.

ipns.namespace

// '/ipns/'

ipns.namespaceLength

// 6

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.