@conet-project/chat-sdk

Beamio CoNET Chat SDK — runs the gossip transport entirely inside a Web Worker (zero main-thread openpgp decrypt/encrypt, zero ethers.verifyMessage), plus fragmented, symmetrically-encrypted IPFS history. UI-agnostic, reusable across SilentPassUI / bizSite / Alliance / POS.

Motivation: running openpgp.decrypt + ethers.verifyMessage on the main thread caused a "UI freeze for tens of seconds after startup". This SDK moves all inbound decryption, outbound encryption, signing, and SSE connect/reconnect into a Worker. The main thread only orchestrates postMessage and dispatches events.

---

Features

• Worker-first: every heavy crypto operation runs inside the Worker; the UI never blocks.
• UI-agnostic: pure TS/ESM + .d.ts, no React and no app-specific imports. The host injects private keys, RPC, node discovery, IPFS, and persistence.
• Zero-trust routing built in: send via entry A, listen via entry C (≠ mailbox B), listenKind:'chat', business messages encrypted to the recipient's EOA user PGP, delivery ACK encrypted to the route B key.
• Encrypted fragmented history: HKDF domain separation + ratcheting fragment keys + AES-256-GCM fragments + encrypted index manifest + server-side point- pointers + IndexedDB local-first.
• Private keys never persist inside the SDK: keys are used only in Worker memory to derive an ethers.Wallet and the history master. The host decides whether to persist locally (consumers/POS may store; bizSite keeps session memory only).

---

Architecture

┌────────────────────────── Main thread (host UI) ──────────────────────────┐
│  BeamioChatClient                                                          │
│   • init() → getNodes() → postMessage(init)                               │
│   • sendMessage / queryPresence / setRoutes / setNodes                    │
│   • on('message'|'delivery'|'presence'|'status'|'log'|historyBuffer)      │
│   • history.load / history.append / history.onBuffer                      │
│   ▲ plaintext env.line → host's existing addNewMessage serial queue       │
└──────────────┬───────────────────────────────▲───────────────────────────┘
        postMessage(Command)                  postMessage(Event/Receipt)
┌──────────────▼───────────────────────────────┴───────────────────────────┐
│  Web Worker (worker/entry.ts)                                             │
│   • GossipCore: SSE connect/reconnect, openpgp decrypt/encrypt,           │
│                 EIP-191 sign, presence wallet_online_query, delivery ACK  │
│   • HistoryStore: master + HKDF + ratcheting fragments + AES-GCM + IPFS   │
└──────────────────────────────────────────────────────────────────────────┘

---

Installation

Install as a dependency (per src-subprojects-are-independent: each sub-project owns formal dependencies; never cross-../.. import).

npm install @conet-project/chat-sdk

Peer dependencies (provided by the host):

Package	Version
ethers	^6.0.0
openpgp	^5.0.0 || ^6.0.0

Runtime: a browser / WebView with Worker + crypto.subtle (PWA inside iOS/Android native shells is supported). Node >=18 for build/test only.

---

Quick start

The host creates the Worker (the SDK does not hardcode a worker URL, to stay bundler-agnostic):

import { createBeamioChatClient, type BeamioChatConfig } from '@conet-project/chat-sdk'

const config: BeamioChatConfig = {
  identity: {
    eoaAddress,                 // 0x… (SDK normalizes internally)
    privateKeyHex,              // raw EOA private key hex, used only inside the Worker
    pgpPrivateKeyArmored,       // armored PGP private key (decrypt inbound)
    pgpPassphrase: '',
    pgpPublicKeyArmored,        // armored PGP public key (keyID / diagnostics)
    ownRouteArmoredPublicKey,   // your mailbox B route public key
  },
  conetRpcUrl: 'https://rpc1.conet.network',
  addressPgpContractAddress: CONET_ADDRESS_PGP,
  getNodes: async () => fetchHealthyNodes(),   // host owns node discovery/caching
  ipfsBaseUrl: 'https://ipfs.conet.network/api',
  chainId: 224422,             // chainId used in the history-master derivation domain (default 224422 CoNET L1)
}

const client = createBeamioChatClient(config, {
  workerFactory: () =>
    new Worker(new URL('@conet-project/chat-sdk/worker', import.meta.url), { type: 'module' }),
})

await client.init()                 // start Worker + inject keys/nodes; the Worker begins listening

// inbound plaintext lines → hand to the host's existing serial checkSign/parse queue
const off = client.on('message', (env) => {
  addNewMessage(env.line)           // env.line already carries _beamioPgpArmorHash for delivery ACK
})

// later, update the contacts to listen for / probe
client.setRoutes(myContactRoutes)

Worker creation per bundler

Environment	workerFactory
Vite	() => new Worker(new URL('@conet-project/chat-sdk/worker', import.meta.url), { type: 'module' })
Webpack 5 / CRA (Craco)	same as above; Webpack 5 statically recognizes new Worker(new URL(...)) and emits a separate worker chunk
Vendored (see below)	() => new Worker(new URL('../vendor/beamio-chat-sdk/worker/entry.ts', import.meta.url), { type: 'module', name: 'beamio-chat-gossip' })

---

Configuration: BeamioChatConfig

Field	Type	Description
identity	ChatIdentity	see below
conetRpcUrl	string	CoNET DePIN RPC (reads AddressPGP, etc.)
addressPgpContractAddress	string	AddressPGP contract address
getNodes	() => Promise<NodeInfo[]>	returns a snapshot of currently healthy nodes (host owns discovery/caching)
ipfsBaseUrl	string	IPFS fragment gateway base, e.g. https://ipfs.conet.network/api
ipfsWriteBaseUrl?	string	IPFS write base (defaults to ipfsBaseUrl)
persistence?	PersistenceAdapter	IndexedDB adapter (optional; history is memory-only without it)
runtime?	ChatRuntimeOptions	sendFanout (default 3), reconnectBaseMs (4000), reconnectMaxMs (30000)
chainId?	number	chainId in the history-master derivation domain (default 224422 CoNET L1)

ChatIdentity (key injection)

Field	Description
eoaAddress	EOA address
privateKeyHex	raw private key hex (with or without 0x). Used only inside the Worker for EIP-191 signing and history-master derivation
pgpPrivateKeyArmored	armored PGP private key, decrypts inbound
pgpPassphrase?	PGP private key passphrase (if any)
pgpPublicKeyArmored?	armored PGP public key
ownRouteArmoredPublicKey?	your mailbox B route public key (listen encryption target)

One-time key generation + registerChatRoute route registration stay on the host (curve25519 generation is fast and not a freeze source). Inject the generated keys via identity.

ChatRoute (contact routes)

Field	Description
address	contact EOA (lowercase)
userPublicKeyArmored	recipient's user PGP public key — business-message encryption target
routerArmoredPublicKey?	recipient's mailbox B route public key — listen / ACK encryption target
routePgpKeyID?	route keyID (optional)

---

API reference

BeamioChatClient

Method	Description
init(): Promise<void>	start Worker, inject config/nodes; the Worker begins listening. Idempotent (no-op if already running)
sendMessage(to, payload, opts?)	encrypt and send a business payload to a contact via entry A ≠ B. Returns { sendId }
queryPresence(contacts)	probe mailbox listen-pool presence; returns Record<addrLower, boolean> (only ok:true counts)
setRoutes(routes)	update the set of contacts to listen for / probe
setNodes(nodes)	push a refreshed node snapshot (host owns discovery)
postMailboxCommand(routerArmoredPublicKey, command)	encrypt an arbitrary mailbox command (e.g. gossip_delivery_ack) to route B, sent via entry C ≠ B
on(event, cb): Unsubscribe	subscribe to events (below); returns an unsubscribe function
history	BeamioChatHistory (below)
pause() / resume()	pause/resume Worker listening
destroy()	tear down the Worker and all listeners (idempotent)

Events (client.on(...))

Event	Payload	Description
message	InboundEnvelope	env.line = host-ready JSON plaintext line (carries _beamioPgpArmorHash), handed to the host's serial checkSign/parse queue
delivery	DeliveryReceiptEvent	delivery receipt (sendId / deliveredAt / from); host marks its own bubble as delivered
presence	PresenceEvent	online: Record<addr, boolean>, reliable results only
status	StatusEvent	idle/connecting/listening/reconnecting/paused/error; listening fires on each heartbeat to refresh main-thread staleness
log	ChatLogEvent	structured log (never contains private keys / plaintext / full ciphertext)
historyBuffer	HistoryBufferEvent	incremental batches during history restore/append, fed to the UI incrementally

client.history

Method	Description
load(options?)	restore encrypted history: locate index (point-${L} / IndexedDB) → decrypt → decrypt the tail first → backfill in the background; emits historyBuffer incrementally
append(entry)	write a newly received/sent entry to encrypted history + local mirror
onBuffer(cb): Unsubscribe	subscribe to incremental batches during restore/append

HistoryLoadOptions: peer? (single contact or all), tailCount? (default 60, i.e. "last 2 screens"), localOnly? (IndexedDB only, for instant display).

---

Zero-trust routing (built into the SDK)

Follows conet-p2p-mailbox-routing-protocol and beamio-conet-chat-protocol:

• Send business messages: encrypt to the recipient's EOA user PGP, POST to a healthy entry A ≠ mailbox B.
• Recipient listen: encrypt to the mailbox B route key, SSE-connect via entry C ≠ B, and always include listenKind:'chat'.
• Delivery ACK: encrypt to the mailbox B route key.
• Never connect directly to mailbox B; never target the recipient's AA (must be EOA user PGP).

---

Encrypted fragmented history

master     = keccak256( EOA_sign("beamio.chat.history.v1|chainId|eoa") )   // private key never leaves the Worker
locator L  = HKDF(master, "index-locator")     // hidden in a hash ocean; server-side point-${L} points to the current index
indexKey   = HKDF(master, "index-enc")         // AES-256-GCM encrypts the ordered index manifest
fragment ratchet  k_i = HKDF(master, `frag|${seq}|${cid_{i-1}}`)   // cid_{-1}=HKDF(master,"frag-genesis")
           cipher_i = AES-GCM(k_i, plaintext_i);  cid_i = keccak256(cipher_i)   // uploaded as a fragment

• Every cid_{i-1} is recorded in the index, so any k_i is O(1) to derive — enabling newest-first restore.
• IndexedDB local-first: localOnly for instant display; network failures do not overwrite trusted local history (beamio-trusted-vs-untrusted-fetch).
• Server-side point- pointers: content is still stored as keccak(content)=hash1, with an extra alias point-${L} → hash1. Requires EOA signature + owner binding + monotonic timestamp (blocks hijacking/replay). See x402sdk/src/endpoint/fragmentClusterServer.ts.

---

Integrating into SilentPassUI (vendored example)

Because sub-projects live in separate Git repos and file: deps are awkward on remote builds, SilentPassUI vendors the SDK source into src/vendor/beamio-chat-sdk/, bridged via services/chatWorkerBridge.ts:

// services/chatWorkerBridge.ts (key points)
import { createBeamioChatClient } from '../vendor/beamio-chat-sdk'

function makeGossipWorker(): Worker {
  return new Worker(new URL('../vendor/beamio-chat-sdk/worker/entry.ts', import.meta.url), {
    type: 'module',
    name: 'beamio-chat-gossip',
  })
}

const client = createBeamioChatClient(config, { workerFactory: makeGossipWorker })
client.on('message', (env) => { if (env.line) onLine(env.line) })   // → App.tsx addNewMessage
client.on('status', (st) => { if (st.status === 'listening') noteGossipActivity() })
await client.init()

In services/chat.ts, connectToGossipNode only parses routes + healthy entries (for delivery ACK) on the main thread; the inbound LISTEN loop is fully delegated to the Worker. Decrypted plaintext lines flow through onLine → newMessage → App.tsx addNewMessage (unchanged serial queue).

Keep the vendored copy in sync with the source; changes to this SDK must be mirrored into src/SilentPassUI/src/vendor/beamio-chat-sdk/. Vendored relative imports strip .js suffixes to match CRA moduleResolution:"node".

---

Security & compliance

• Private keys / plaintext / full ciphertext must never be logged; log events emit structured summaries only.
• The history master lives only in Worker memory; consumers/POS may store keys locally, bizSite keeps session memory only (policy owned by the host; the SDK never self-persists).
• Always send listenKind:'chat'; never connect directly to mailbox B.
• point- has CoNET-private semantics; public-gateway retrieval relies on CIDv1 mapping and must be documented.

---

Build / directory layout

npm run build       # tsc -p tsconfig.json → dist/ (ESM + .d.ts)
npm run typecheck   # tsc --noEmit
npm run clean       # rm -rf dist

src/
  index.ts          # public entry: createBeamioChatClient + types
  client.ts         # main-thread BeamioChatClient (starts worker + postMessage protocol)
  protocol.ts       # main ↔ worker postMessage protocol
  types.ts          # public types (UI-agnostic)
  crypto.ts         # WebCrypto + keccak/HKDF/AES-GCM (worker & main thread)
  nodes.ts          # node probing (worker & main thread)
  worker/
    entry.ts        # worker entry (imported only in a Worker context)
    gossip-core.ts  # SSE + openpgp decrypt/encrypt + sign + presence + ACK
    history.ts      # encrypted fragmented IPFS history + IndexedDB

Package exports:

Entry	Usage
@conet-project/chat-sdk	main-thread API (createBeamioChatClient + types)
@conet-project/chat-sdk/worker	worker entry; only used as the target of new Worker(...)

---

Related rules / references

• conet-p2p-mailbox-routing-protocol / beamio-conet-chat-protocol — routing and envelopes
• conet-depin-chat-app-dev — app practices (receipts / presence / listenKind)
• beamio-trusted-vs-untrusted-fetch — failures never overwrite trusted local state
• x402sdk/src/endpoint/fragmentClusterServer.ts — point- pointer server
• src-subprojects-are-independent — sub-projects are independent; no cross-repo imports

License

MIT (private release, publishConfig.access = restricted).