Home

Awesome

<!-- SPDX-FileCopyrightText: 2022 Andre 'Staltz' Medeiros <contact@staltz.com> SPDX-License-Identifier: CC0-1.0 -->

ssb-tribes2

A secret-stack plugin that makes it easy to create, manage, and publish messages in SSB "Private Groups", following this spec. This module is made to work with ssb-db2 as the database and with metafeeds, where your content in the group is placed on a dedicated feed in your metafeed tree. Replication of those group-specific feeds at scale is handled by ssb-replication-scheduler.

Successor of ssb-tribes.

Installation

npm install ssb-tribes2

Usage in ssb-db2

 const ssb = SecretStack({ caps: require('ssb-caps') })
   .use(require('ssb-master'))
+  .use(require('ssb-db2'))
   .use(require('ssb-conn'))
+  .use(require('ssb-bendy-butt'))
+  .use(require('ssb-meta-feeds'))
+  .use(require('ssb-tribes2'))
   .use(require('ssb-blobs'))
   .call(null, config)

Then to create a group and publish to it,

// This is needed to automatically create an additions feed, needed to be able to send and receive invites
ssb.tribes2.start()

// Create a new group, no further details required, thus the empty object
ssb.tribes2.create({}, (err, group) => {
  // Publish a new message to the group, notice the recps
  ssb.tribes2.publish(
    {
      type: 'post',
      text: 'welcome to the group',
      recps: [group.id],
    },
    cb
  )
})

If you want to add more members to the group:

// You need to know your friends' (bob and carol) *root* metafeed IDs
ssb.tribes2.addMembers(group.id, [bobRootId, carolRootId], {}, (err, msg) => {
  // msg is the message that was published on your invitations feed
})

Then you list the current members of the group:

pull(
  ssb.tribes2.listMembers(group.id),
  pull.collect((err, members) => {
    // `members` is an Array of root metafeed IDs
  })
)

Finally, you can list all the groups you are a member of:

pull(
  ssb.tribes2.list(),
  pull.collect((err, groups) => {
    // `groups` is an Array of group objects like { id, secret }
  })
)

API

All methods with callbacks return a promise instead if a callback isn't provided.

ssb.tribes2.create(opts, cb)

Creates a new private group. This creates an encryption key, sets up a sub-feed for the group, and initializes the group with a group/init message, and group/add-member to signal you were added. Calls back with important info about the group. NOTE: If create finds an empty (i.e. seemingly unused) group feed, it will start using that feed instead of creating a new one.

ssb.tribes2.get(groupId, cb)

Gets information about a specific group.

ssb.tribes2.list({ live, excluded }) => source

Creates a pull-stream source which emits group data of each private group you're a part of. If live is true then it also outputs all new groups you join. If excluded is true then it only outputs groups that you've been excluded from, instead of just ones you haven't. (Same format as group object returned by #create)

ssb.tribes2.addMembers(groupId, feedIds, opts, cb)

Publish group/add-member messages to a group of peers, which gives them all the details they need to join the group. Newly added members will need to accept the invite using acceptInvite() before they start replicating the group.

`ssb.tribes2.excludeMembers(groupId, feedIds, opts, cb)

Excludes some current members of the group, by creating a new key and group feed and reinviting everyone to that key except for the excluded members.

ssb.tribes2.publish(content, opts, cb)

Publishes any kind of message encrypted to the group. The function wraps ssb.db.create() but handles adding tangles and using the correct encryption for the content.recps that you've provided. Mutates content.

ssb.tribes2.listMembers(groupId, { live, allAdded }) => source

Returns a pull stream source listing the root feed id of every member of the group with id groupId. Note: lists members whether or not they've accepted the invite.

If live is true, then it keeps the stream open and also outputs updates to membership as new members are added / excluded.

If allAdded is true then excludes are ignored and any peer that has ever been a member of the group is listed.

Each update emitted from the source is the updated complete state of the group in the format:

{
  added: [feedId, feedId, ...],
  toExclude: [feedId, ...]
}

ssb.tribes2.listInvites() => source

Returns a pull stream source listing invites (another user sent you one with addMembers) that you haven't accepted yet. The invites are on the same format as that of #create.

ssb.tribes2.acceptInvite(groupId, cb)

Accepts an invite (addition) for a group, if you've received one, and starts to replicate and decrypt it. Does not publish any message.

ssb.tribes2.start(cb)

Makes sure that you're set up to send and receive group invites, by creating an additions feed for you.

Config

You can set the secret stack config config.tribes2.timeoutLow and config.tribes2.timeoutHigh to control how slowly the client should try to fix a conflicting state, where other clients might be trying to fix the same conflict at the same time. The defaults are 5 and 30 respectively, which gives a random timeout between 5s-30s. A higher value reduces the risk of creating new conflicts since other clients don't do the same conflict resolution at the same time, but increase the time that the group is in an unstable state. A lower number corrects things faster but increases the risk of ending up in new conflicts. Should not be 0 or close to it.

You need to set config.tribes2.recoverExclude to true (default false) for the above mentioned conflict recovery to happen at all. The recovery is a bit unreliable but might sometimes be needed to repair broken state.

Security considerations

While we have tried our best to create a secure end-to-end encrypted communication protocol, this module is not fit for use in safety critical situations. Neither the code nor the specification has been vetted by an independent party. Even assuming a solid implementation, and a bug-free spec, we have intentionally left out several security features that are considered state of the art in other apps such as Signal, such as "forward secrecy".

Because of this, we advise that anyone that uses this module in an app, includes prominent UI that warns the user about possible risks.

Links

License

LGPL-3.0-only