HyperNS

Name service for Keet identities, based on hyperdb.

Install

npm i hyperns

Warning: Race Conditions

This module does NOT handle race conditions when modifying the database, so be sure to use some sort of lock or mutex when modifying the database, otherwise it can enter an inconsistent state.

Note that if the hyperns module is used as an autobase view, the fact that it is only updated inside an apply function provides sufficient lock semantics to safely use hyperns.

Data model

The hyperns database contains attested identity records of form { publicKey, name, data: { clock }, attestation }:

• publicKey is the public key of a key pair, identifying someone
• name is the name linked with the public key
• data:
  • clock is a vector clock, used to safely modify data (only relevant when updating a record)
• attestation is a proof of the correctness of the record, signed by the secret key corresponding to the record's public key.

There is a 1-to-1 relationship between public keys and names, except that names are allowed to point to nothing. This happens when a user updated their name.

The database is indexed on keys and names, so look-ups are efficient.

API

const nsDb = new HyperNS(core, opts)

Create a new HyperNS instance.

core is a Hypercore.

opts include:

• extension: whether to create the Hyperbee with extensions enabled (default true. Set to false when used with autobase)

nsDb.key

Get the key of the underlying hypercore.

nsDb.discoveryKey

Get the discovery key of the underlying hypercore.

const attestedRecord = HyperNS.createAttestatedRecord(unattestedIdentity, keyPair)

Create an attested identity record, by signing it with your key pair. The resulting attestation is verifiable by the key pair's public key.

keyPair is of form { publicKey, secretKey }.

unattestedIdentity is an attestedIdentity without the attestation field: { publicKey, name, data }

It returns an attestedIdentity of form { publicKey, name, data, attestation }, where attestation is a signed proof of the correctness of the record (and the other fields are unchanged).

const isValid = HyperNS.verifyAttestation(identityRecord)

Verify the attestation of an identity record (as stored in the database, or as generated by HyperNS.createAttestatedRecord(...)).

Returns true if it is valid, false otherwise.

await nsDb.insert(attestedRecord)

Insert a new record in the database. It is recommended to use HyperNS.createAttestatedRecord(...) to create the record.

await nsDb.update(attestedRecord)

Updates an existing record. It is recommended to use HyperNS.createAttestatedRecord(...) to create the attested record.

publicKey should already exist in the database, and clock should be higher than the clock of the existing record, otherwise an error is thrown.

const attestedRecord = await nsDb.get (name)

Get the attested record corresponding to the name, or null if none is found.

const attestedRecord = await nsDb.getByKey (key)

Get the attested record corresponding to the key, or null if none is found.

const attestedRecord = await nsDb.has (name)

Returns true if a record with the specified name exists, false otherwise.

const attestedRecord = await nsDb.hasKey (key)

Returns true if a record with the specified key exists, false otherwise.

const attestedRecord = nsDb.search (prefix, findOpts = {})

Performs a prefix search, returning a stream of identity records starting with prefix.

findOpts includes limit (default 10). See hyperdb for all options.

const attestedRecord = nsDb.list (query = {}, findOpts = {})

Returns a stream of identity records matching the query and findOpts (see hyperdb for their semantics).

const changeStream = nsDb.createWatcher({ initLength = 0})

Returns a stream that yields all changes, starting at the specified initial length.

Development

Generate tests

To be run whenever a new test file is added (not needed when adding tests to an existing file):

npm run test:generate