npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@bsv/group-messaging

v0.1.1

Published

End-to-end encrypted group messaging for BRC-100 wallets — MLS group state over wallet-to-wallet transport

Readme

@bsv/group-messaging

End-to-end encrypted group messaging for BRC-100 wallets. Group state is MLS (RFC 9420) by way of ts-mls; identity is the wallet's own secp256k1 key, bound into each member's MLS credential so a peer cannot join a group under a name that is not theirs.

The library opens no database and no network connection of its own. It uses the storage and transport the host already has.

⚠️ Security status

Early release, 0.x, and not yet something to put a user's safety on.

ts-mls, which is the entire cryptographic core here, states that it has not undergone a formal security audit. That applies to this package by inheritance. The layer added on top of it — the wallet attestation carried inside each MLS credential — has had no external audit either; it has been reviewed by reading, and the forgery paths it is meant to stop are covered by tests, which is not the same thing as an audit having been done.

It has not been tested against any other MLS implementation. The content envelope and the bootstrap wire format are versioned but not frozen, and ts-mls is pinned exactly rather than by range because its releases have changed the key schedule inside a minor bump — peers on different ts-mls versions may not interoperate.

Provided as-is. Use at your own discretion.

Install

npm install @bsv/group-messaging @bsv/sdk

@bsv/sdk is a required peer dependency. The package supports Node.js 22 and newer, runs in the browser, and publishes ESM and CommonJS entry points.

Quick start

import { GroupMessagingClient } from '@bsv/group-messaging'
import { WalletClient } from '@bsv/sdk'

const client = await GroupMessagingClient.create({
  wallet: new WalletClient(),
  storage: sqlDriver, // whatever database the host already has
  transport: messageBoxClient
})

const minted = await client.keyPackages.create() // keep the private half

const group = await client.createGroup({
  chatId: 'project-alpha',
  members: [bobKeyPackage],
  privateKeyPackage: minted.privateKeyPackage
})

await group.sendText('hello')

client.on('message', ({ chatId, sender, content }) => {
  console.log(chatId, sender, content)
})

create() is async because a wallet may prompt the user for their identity key and a database may need its tables created. It also starts listening; call listen() yourself only if you constructed the client directly.

Inputs

Each of the three inputs accepts several shapes, so the client can sit on top of whatever the host already runs.

| Input | Accepts | | ----------- | ------------------------------------------------------------------------------------------- | | wallet | a BRC-100 WalletClient, a KeyDeriver, or a bare root PrivateKey | | storage | a SqlDriver, an IDBDatabase, a Map, a StorageProvider, "memory", or "indexeddb" | | transport | a MessageBoxClient, a TransportBackend, or a TransportService |

storage: "indexeddb" is the one case where the library opens something itself, for a browser caller with no database to hand. Every other backend is supplied.

Storage is scoped to the client's identity: one host database serves however many accounts the wallet manages, because the client narrows the provider with StorageProvider.scopeTo(identityKey) before using it.

Live delivery

Delivery polls the box. That is the guarantee, and it is on whatever the host asked for. A live socket is an optimisation laid over it: joinRoom replays no backlog, so anything stored while the socket was away is reachable only by listing, and the poll is what lists it.

Pass the client with its options to turn the socket on:

const client = await GroupMessagingClient.create({
  wallet: new WalletClient(),
  storage: sqlDriver,
  transport: { client: messageBoxClient, live: true, pollIntervalMs: 5000 }
})

While the socket carries this box's room the poll relaxes to LIVE_BACKSTOP_INTERVAL_MS (30s). The moment it does not — reconnecting, closed, or live but no longer joined to the room — the poll returns to pollIntervalMs. The transport decides that from what the client reports and never from guesswork, so nothing here tears a socket down or counts strikes against it; @bsv/message-box-client 2.7.0 and newer reconnect and rejoin their own rooms, and a client too old to report one leaves the poll at pollIntervalMs throughout.

The socket needs a relay that serves WebSockets. Not every MessageBox host does, and DEFAULT_MESSAGE_BOX_HOST is not a promise that this one will: against a relay without them the socket never connects, delivery falls to the poll, and onLiveStatus says so. Point MessageBoxClient at a host you know serves them before setting live: true.

The transport owns the socket's lifetime while this is set — it connects on start and disconnects on close — so a host sharing one MessageBoxClient with other consumers should know that before turning it on.

To watch what the socket is doing, build the transport yourself and subscribe:

import { MessageBoxTransport, TransportService } from '@bsv/group-messaging'

const transport = new MessageBoxTransport(messageBoxClient, { live: true })
transport.onLiveStatus(({ phase, source, detail }) => {
  console.log(phase, source ?? '', detail ?? '')
})

const client = await GroupMessagingClient.create({
  wallet: new WalletClient(),
  storage: sqlDriver,
  transport: new TransportService(transport)
})

phase is connecting, subscribed, delivered, reconnecting or closed. Only transitions are reported. subscribed means the socket is live and holding this box's room, which is the only state in which anything will be pushed here; delivered carries source so a host can tell which producer carried a message.

The invitation handshake

A group cannot be built until the inviter holds the invitee's KeyPackage, so membership starts with a bootstrap exchange over the transport. Alice invites Bob:

// Alice asks Bob for a KeyPackage.
const inviteId = await alice.invites.send(bobIdentityKey, { chatName: 'Project Alpha' })

// Bob is asked. Nothing is minted until he accepts.
bob.on('inviteReceived', async ({ inviteId }) => {
  const minted = await bob.keyPackages.create()
  await keepSomewhereSafe(minted.ref, minted.privateKeyPackage) // the host's job
  await bob.invites.accept(inviteId, minted.keyPackage)
})

// Alice gets an answer whose credential proves it is Bob's.
alice.on('keyPackageReceived', async ({ keyPackage }) => {
  const own = await alice.keyPackages.create()
  await alice.createGroup({
    chatId: 'project-alpha',
    members: [keyPackage],
    privateKeyPackage: own.privateKeyPackage
  })
})

// Bob is added. Nothing is joined until he says so.
bob.on('welcomeReceived', async ({ inviteId, ref }) => {
  if (ref === undefined) return // not encrypted to a KeyPackage we hold
  await bob.joinFromWelcome({
    inviteId,
    chatId: 'project-alpha',
    privateKeyPackage: privateHalfFor(ref)
  })
})

Two refusals are worth handling rather than ignoring:

  • keyPackageRejected — a peer answered with a KeyPackage whose credential names somebody else, or one that could not be read. The KeyPackage is deliberately not carried on the event, because there is no safe use for it. The invitation is consumed either way, so the exchange must restart.
  • bootstrapRefused — a peer answered an invitation this client never issued. The library refused it; the event is the only record. This is the check that stops a stranger inserting their KeyPackage into someone else's exchange.

Bootstrap envelopes carry no signature of their own, so peer on an invite is exactly as trustworthy as the transport's sender authentication and no more. Over MessageBox that is a BRC-31 authenticated identity. Over a transport that does not authenticate senders, treat it as a hint.

KeyPackage lifecycle

This is the part most easily got wrong, because a KeyPackage looks like a long-lived key and is not one.

A KeyPackage is an entry ticket, not a chat key. It is consumed once, at the moment its holder enters a group. Its init key exists to decrypt exactly one Welcome; its leaf node becomes that member's leaf in the ratchet tree. After that, the member's position in the group is maintained by the tree — and the leaf key rotates on every Commit. Nothing about continued access depends on the KeyPackage still existing. RFC 9420 §10 is explicit that KeyPackages "are intended to be used only once and SHOULD NOT be reused."

The library stores the public half only. keyPackages.create() returns both halves and keeps only the public one, keyed by its RFC 9420 ref. The private half is handed back once and forgotten — storing it is the host's job and this library's prohibition.

const minted = await client.keyPackages.create()
minted.ref // stored here, so a Welcome can be matched to it
minted.keyPackage // public: publish this, send it to an inviter
minted.privateKeyPackage // yours to keep, and yours alone to destroy

A ref is spent at two points:

| Point | What consumed it | | -------------------------- | --------------------------------------- | | joinFromWelcome succeeds | the init key decrypted the Welcome | | createGroup succeeds | the leaf node became the founder's leaf |

After either, that ref should be retired and the matching private half destroyed. Both halves matter, and only one of them is reachable from here:

  • Retiring the public ref stops it matching future Welcomes. keyPackages.refFor() matches any Welcome ref still in storage, so a ref that is never retired stays eligible forever — and a second Welcome encrypted to the same init key is precisely the reuse RFC 9420 warns against.
  • Destroying the private half is what preserves forward secrecy. An init private key kept after joining lets anyone who later compromises the device decrypt a captured Welcome and recover the group secrets of that epoch. The library cannot do this for you; it never had the bytes.

Retiring the public half is automatic: a successful joinFromWelcome or createGroup forgets the ref it spent and emits keyPackageConsumed naming it. That event is the signal to destroy the private half, which is the part the library cannot reach.

client.on('keyPackageConsumed', ({ ref }) => {
  secureStore.delete(ref) // the half that forward secrecy turns on
})

Destroying it does not cost you the group. PrivateKeyPackageBytes carries three keys, and entering a group consumes only one of them: the init key, which decrypts a single Welcome and which a founder never uses at all. The other two — the leaf encryption key and the signature key — are copied into the MLS group state when you join or create, and that state is what putGroup persists. Your standing in the tree, and your ability to commit, update and send afterwards, lives there and not in the KeyPackage.

A ref that was never spent — expired, or a pool entry being rotated — is retired on request:

await client.keyPackages.retire(ref)

Nothing is retired when the operation fails, so a join that threw can be retried with the same pair.

Publish a small pool, not one forever. Retiring a ref means this device cannot be invited anywhere until it mints and publishes another. That is why MLS deployments keep a handful of unconsumed KeyPackages available, hand out one per invitation, retire on consumption, and top the pool up. keyPackages.list() and keyPackages.get(ref) exist for exactly that bookkeeping — get returns the public bytes of an unconsumed KeyPackage so it can be republished.

Leaving a chat is unrelated. By then the ref was consumed at join, long before; leaving is an MLS removal plus dropping local state, and touches no KeyPackage.

Sending and receiving

Group carries the content helpers:

await group.sendText('hello')
await group.sendMarkdown('# heading')
await group.sendReaction({ messageId, emoji: '+1' })
await group.sendReply({ messageId, body: 'agreed' })
await group.sendRemoteAttachment(attachment, 'the spec')
await group.sendContent(content) // the v1 JSON envelope directly
await group.send(bytes) // opaque payload, no envelope

Membership and state:

await group.info()
await group.addMembers([keyPackage])
await group.removeMembers([identityKey])
await group.update() // rotate this member's leaf key
await group.delete() // drop local state for the chat

Inbound traffic is delivered through events. A subscriber that throws is isolated: it cannot abort the delivery loop or stall a queue drain, and its error surfaces as processingFailed.

| Event | Meaning | | ------------------ | --------------------------------------------------------------------------- | | message | an application message, decrypted, with the epoch it was sent in | | membership | members added or removed | | epochMismatch | queued while awaiting the opening Commit, or dropped when unrecoverable | | deliveryFailed | delivery failed for some members; the group still advanced locally | | processingFailed | an inbound payload could not be processed; delivery continues |

A message more than four epochs behind the group cannot be opened — ts-mls retains keys for four epochs — so it is dropped and reported rather than retried forever.

Composing the layers

GroupMessagingClient is a facade. Every layer under it is exported for callers who want to compose them differently or swap one out: IdentityService, StorageProvider, TransportService, MlsEngine, InviteService, and the storage and transport backends.

MlsEngine is the only module permitted to import ts-mls.

Design notes for consumers

  • chatId is local and never goes on the wire. mlsGroupId is the only cross-party identifier. Likewise inviteId is local; the wire carries requestId.
  • Branded types are a guard rail. KeyPackageBytes and PrivateKeyPackageBytes are distinct types so the wrong one cannot be sent. Do not cast between them.
  • One client per identity per process. Identity scoping lets several accounts share one database; it does not let two clients share one account. Group locks are per-instance, so two clients built for the same identity will race on group writes.
  • close() waits for an in-flight poll. That is deliberate — it is what stops a poll acknowledging messages no subscriber received — but a host that cannot trust its own handlers should put a timeout around shutdown.

API

See API.md, generated from src/index.ts:

npm run doc

License

Licensed under the Apache License 2.0; see LICENSE.

SDK4 hotfix peer requirement

The SDK4 peer alternative starts at @bsv/sdk ^4.0.1, which restores numeric wallet results and legacy wire compatibility. Existing SDK2/3 alternatives and lower bounds remain unchanged. SDK4 users should install the 4.0.1 hotfix; no application-wallet wire or data migration is required.