SEA API

SEA (Security, Encryption and Authorization) provides the functions the User API uses to create keys, sign, verify and encrypt data. They're useful in your own code too, so they're available via holster.SEA:

const pair = await holster.SEA.pair()

SEA can also be imported on its own, without the rest of Holster:

import SEA from "@mblaney/holster/src/sea.js"

Every function can be awaited, and each also accepts a callback as its last parameter, which receives the same result. A function that fails, or is given a pair without the keys it needs, returns null.

Pair objects

Most functions take a "pair object", which holds some or all of these keys:

Key

Used for

pub

Verifying signatures.

priv

Signing.

epub

Creating shared secrets.

epriv

Encrypting and decrypting.

pair() generates all four. A logged in user's user.is is a pair object too, so it can be passed straight to these functions. Each function only needs some of the keys, so you can pass just those: for example {pub: somePublicKey} is enough to verify a signature.

Encrypting data

Anyone can read data stored with Holster, including data in user space. To keep it private, encrypt it before writing it. Only the values are hidden: keys, which properties exist, and any values left unencrypted can still be read.

Data only you can read

Encrypt with the logged in user's own keys. Only that account can decrypt it:

const enc = await holster.SEA.encrypt("for my eyes only", user.is)
await user.get("private").put(enc)

See Private notes for a full example.

Data for another account

Create a key shared with the other account using secret(), from their public epub key. They create the same key from yours to decrypt it:

const bobEpub = await user.get([bobPub, "epub"])
const toBob = await holster.SEA.secret({epub: bobEpub}, user.is)
await user.get("for-bob").put(await holster.SEA.encrypt("hi Bob", toBob))

See Data shared by the host for a full example.

Data for a group

To share data with several accounts, encrypt it once with a group key, then share the group key with each member. encrypt() only needs an epriv, and any random string works as one:

const groupKey = crypto.randomUUID()
await user
  .get("group")
  .next("notes")
  .put(await holster.SEA.encrypt("Meet at 6", {epriv: groupKey}))

// Share the group key with each member, encrypted for just them.
for (const member of members) {
  const toMember = await holster.SEA.secret({epub: member.epub}, user.is)
  const key = await holster.SEA.encrypt(groupKey, toMember)
  await user.get("group").next("keys").next(member.pub).put(key)
}

A member decrypts their copy of the group key, then the data:

const shared = await user.get([ownerPub, "group"]).next("keys").next(user.is.pub)
const ownerEpub = await user.get([ownerPub, "epub"])
const fromOwner = await holster.SEA.secret({epub: ownerEpub}, user.is)
const groupKey = await holster.SEA.decrypt(shared, fromOwner)
const notes = await user.get([ownerPub, "group"]).next("notes")
console.log(await holster.SEA.decrypt(notes, {epriv: groupKey}))
// Meet at 6

Adding a member only means sharing the existing key with them. Removing one means creating a new group key, encrypting the data again with it, and sharing it with the members who are left, since the removed member still has the old key.