Dark Crystal API

Returns a set of functions as an API for validating, building, publishing and reading records dictated by ssb-dark-crystal-schema.

Instantiate

var DarkCrystal = require('scuttle-dark-crystal')
var darkCrystal = DarkCrystal(server) // a scuttlebutt server or connection to one

API Methods

The easiest way to see which methods are exposed is to check out ./methods.js

Secret share method

darkCrystal.share.async.share(opts, callback)

Where opts is an object with required properties:

• name a name referring to the secret
• secret the secret string itself
• recps an array of ssb feedIds for the shard recipients
• quorum the minimum number of shards required to recombine

The secret is sharded and a root message, ritual message and one shard message for each recipient are published. If successful, the published messages will be passed as an object to the callback.

Secret recovery methods

darkCrystal.recover.async.request(rootId, recipients, callback)

This method publishes invite messages with a request to return a shard. If recipients is falsey, invite messages to all shardholders associated with the given rootId will be published. If recipients is an array containing one or more feedIds, invite messages to only the given recipients will be published, provided they hold shards associated with the given rootId. If successful, the published invite messages are passed to the callback.

This method can also be called : darkCrystal.recover.async.request(rootId, callback) and it will send requests to al shard-holders

darkCrystal.recover.async.reply(inviteId, callback)

This will respond to a given invite message, by decrypting the associated shard and publishing an invite-reply message providing the shard in the body property. If successful, the reply message is passed to the callback.

darkCrystal.recover.async.recombine(rootId, callback)

This will attempt to recombine the decrypted shards included in reply messages associated with a given rootId. If successful the secret will be passed to the callback.

This also works for forwarded shards, you just need to provide the root from on of the fwds.

Root methods

darkCrystal.root.async.publish(name, callback)

Takes a secret name as an argument and publishes a root message. If successful, the published message will be passed to the callback.

darkCrystal.ritual.async.publish ({ root, shards, quorum }, callback)

Takes an object with properties:

• root the ID of the root message
• shards the number of shards
• quorum the minimum number of shards required to recombine

A ritual message is published. If successful, the published message will be passed to the callback.

Shard methods

darkCrystal.shard.async.publishAll( { shards, recps, rootId }, callback)

Takes an object with properties:

• shards an array of shard strings
• recps an array of ssb feedIds for the shard recipients
• rootId the ID of the root message

For each shard, a shard message will be published to both the recipient and the sender. If successful, the published messages will be passed to the callback. In the case of at least one validation error, no messages will be published.

darkCrystal.shard.pull.byRoot(rootId, opts)

Returns a stream of shard messages identified by root id. Takes opts - standard stream options.

darkCrystal.shard.pull.fromOthers(opts)

Returns a stream of shards others have shared with you. Takes opts - standard stream options like live, reverse etc.

Shard forward methods

darkCrystal.forward.async.publish(root, recp, callback)

Takes arguments

• root the id of the root message with which the shard is associated
• recp the feedId of the recipient of the forwarded shard

Publishes a forward message which allows a shard to be sent to someone other than the owner of the secret.

darkCrystal.forward.pull.byRoot(rootId, opts)

Returns a stream of forwarded shard messages identified by root id. Takes opts - standard stream options.

darkCrystal.forward.pull.fromOthers(opts)

Returns a stream of all forwarded shards you have recieved. Takes opts - standard stream options like live, reverse etc.

Validators

darkCrystal.sync.isRitual(ritual)

darkCrystal.sync.isRoot(root)

darkCrystal.sync.isShard(shard)

darkCrystal.sync.isForward(shard)

These are validation methods for each message type as described in ssb-dark-crystal-schema.

darkCrystal.sync.isRequest(shard)

darkCrystal.sync.isReply(shard)

The request + reply schema is described by ssb-invite-schema, but there's additional validation added by the module to check the payload is shard-like