session

User session management utilities.

session
Static Members
init(options)
login(k, key)
loginAsNewUser(options)
logOut()
getKey()
getPubKey()
getMyName()
channelIds

public

Get a public space where only the specified user (public key) can write. Others can read.

public(pub: string?): Node
Parameters
pub (string?) The public key of the user. Defaults to the current user from session.
Returns
Node: The user space.

private

Private channel that only you and publicKey can read/write.

private(publicKey: any, chatLink: string?): Channel
Parameters
publicKey (any = session.getKey())
chatLink (string?)
Returns
Channel:

group

Aggregates public data from all users in the group.

For example, the public message feed, message replies and likes are aggregated using this.

group(groupName: any): any
Parameters
groupName (any = 'everyone')
Returns
any: object

local

Get a state that is only synced in memory and local storage.

Useful for storing things like UI state, local indexes or logged in user.

local(): Node
Returns
Node:

static

Content-addressed storage

static
Static Members
get(hash, callback)
put(value)

peers

Networking and peer management utilities

peers
Static Members
add(peer)
remove(url)
disconnect(peerFromGun)
reset()
connect(url)
disable(url, peerFromGun)

Node

Our very own implementation of the Gun API

new Node(id: string, parent: (Node | null))
Parameters
id (string = '')
parent ((Node | null) = null)
Instance Members
get(key)
put(value)
once(callback?, event?, returnIfUndefined)
on(callback)
map(callback)

SignedMessage

Signed message object. Your friends can index and relay your messages, while others can still verify that they were signed by you.

Fields: signedData, signer (public key) and signature.

signedData has an author, signer, type, time and optionally other fields.

signature covers the utf8 string representation of signedData. Since messages are digitally signed, users only need to care about the message signer and not who relayed it or whose index it was found from.

signer is the entity that verified its origin. In other words: message author and signer can be different entities, and only the signer needs to use Iris.

For example, a crawler can import and sign other people's messages from Twitter. Only the users who trust the crawler will see the messages.

Constructor: creates a message from the param obj.signedData that must contain at least the mandatory fields: author, type and time.

new SignedMessage(obj: any)
Parameters
obj (any)
Example
https://github.com/irislib/iris-lib/blob/master/__tests__/SignedMessage.js

Verification message:
{
  signedData: {
    author: {name:'Alice', key:'ABCD1234'},
    recipient: {
      name: 'Bob',
      email: ['bob@example.com', 'bob.saget@example.com'],
      bitcoin: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa'
    },
    type: 'verification'
  },
  signer: 'ABCD1234',
  signature: '1234ABCD'
}
Static Members
create(signedData, signingKey)
deserialize(s)
Instance Members
sign(key)
getHash()
verify()
serialize()

Channel

Private communication channel between two or more participants (Gun public keys). Can be used independently of other Iris stuff.

Used as a core element of iris-messenger.

You can use iris.private(pub) to always use the same Channel object for a given pub.


Key-value API

channel.put(key, value) and channel.on(key, callback).

Note that each participant has their own versions of each key-value — they don't overwrite each other. channel.on() callback returns them all by default and has a parameter that indicates whose value you got.

While values are encrypted, encryption of keys is not implemented yet.

Message API

channel.send() and channel.getMessages() for timestamp-indexed chat-style messaging.

Message data is encrypted, but timestamps are public so that peers can return your messages in a sequential order.


You can open a channel with yourself for a private key-value space or a "note to self" type chat with yourself.

Privacy disclaimer: Channel ids, data values and messages are encrypted, but message timestamps are unencrypted so that peers can return them to you in a sequential order. By looking at the unencrypted timestamps (or Gun subscriptions), it is possible to guess who are communicating with each other. This could be improved by indexing messages by day only, so making the guess would be more difficult, while you could still return them in a semi-sequential order.

new Channel(options: Object)
Parameters
options (Object)
Name Description
options.key string your keypair
options.gun Object gun instance
options.participants any (optional) string or string array or permissions object ({'pub1':{read:true,write:true,admin:false},'pub2'...}) of participant public keys (your own key is included by default)
options.chatLink string (optional) chat link instead of participants list
options.uuid string (group channels only) unique channel identifier. Leave out for new channel.
options.name string (group channels only) channel name
Example
// Copy & paste this to console at https://iris.to or other page that has gun, sea and iris-lib
// Due to an unsolved bug, someoneElse's messages only start showing up after a reload

var gun1 = new Gun('https://gun-us.herokuapp.com/gun');
var gun2 = new Gun('https://gun-us.herokuapp.com/gun');
var myKey = await iris.Key.getDefault();
var someoneElse = localStorage.getItem('someoneElsesKey');
if (someoneElse) {
 someoneElse = JSON.parse(someoneElse);
} else {
 someoneElse = await iris.Key.generate();
 localStorage.setItem('someoneElsesKey', JSON.stringify(someoneElse));
}

iris.Channel.initUser(gun1, myKey); // saves myKey.epub to gun.user().get('epub')
iris.Channel.initUser(gun2, someoneElse);

var ourChannel = new iris.Channel({key: myKey, gun: gun1, participants: someoneElse.pub});
var theirChannel = new iris.Channel({key: someoneElse, gun: gun2, participants: myKey.pub});

var myChannels = {}; // you can list them in a user interface
function printMessage(msg, info) {
 console.log(`[${new Date(msg.time).toLocaleString()}] ${info.from.slice(0,8)}: ${msg.text}`)
}
iris.Channel.getChannels(gun1, myKey, channel => {
 var pub = channel.getCurrentParticipants()[0];
 gun1.user(pub).get('profile').get('name').on(name => channel.name = name);
 myChannels[pub] = channel;
 channel.getMessages(printMessage);
 channel.on('mood', (mood, from) => console.log(from.slice(0,8) + ' is feeling ' + mood));
});

// you can play with these in the console:
ourChannel.send('message from myKey');
theirChannel.send('message from someoneElse');

ourChannel.put('mood', 'blessed');
theirChannel.put('mood', 'happy');
https://github.com/irislib/iris-lib/blob/master/__tests__/Channel.js
Static Members
getOurSecretChannelId(pub, pair)
getTheirSecretChannelId(pub, pair)
getChannels(callback, listenToChatLinks, keypair)
addChatButton(options)
setActivity(activity)
getActivity(pubKey, callback)
deleteChannel(key, pub)
deleteGroup(key, uuid)
Instance Members
mute(participant)
block(participant)
getCurrentParticipants()
getParticipants(callback)
getId()
getMessages(callback)
getLatestMsg(callback)
setMyMsgsLastSeenTime(time)
getMyMsgsLastSeenTime(callback)
getTheirMsgsLastSeenTime(callback)
addParticipant(pub, save, permissions?, subscribe?)
send(msg)
save()
put(key, value)
on(key, callback, from)
setTyping(isTyping, timeout)
getTyping(callback, timeout)
getChatBox()