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.

• 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' + algorithm:'aes-256-cbc' + Securitykey, business messages encrypted to the recipient's EOA user PGP, delivery ACK encrypted to the route B key. Each POST wraps inner armor to that entry's route public key. Clients never set X-CoNET-Hop-Sigs.
• 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).

┌────────────────────────── 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   │
└──────────────────────────────────────────────────────────────────────────┘

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):

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

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)

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.

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

Follows src/docs/gitbook/l0/si-developer-guide.md, conet-p2p-mailbox-routing-protocol, and beamio-conet-chat-protocol:

• POST /post: body is only { data: "<OpenPGP armor>" }. Never add sibling fields.
• Send business messages: encrypt to the recipient's EOA user PGP, POST to a healthy entry A ≠ mailbox B.
• Mailbox work / NoPush: if mailbox B must skip APNs, wrap { data: <user-PGP armor>, NoPush: true } to B route PGP, then POST that armor as { data } (optional entry wrap). Do not put NoPush on the HTTP JSON.
• Recipient listen: encrypt { command:'mining', listenKind:'chat', algorithm:'aes-256-cbc', Securitykey } to the mailbox B route key, SSE-connect via entry C ≠ B. Omitting listenKind is treated as mining.
• Delivery ACK / presence: encrypt the SI command to the mailbox B route key, POST via entry C ≠ B.
• Outer wrap (default runtime.outerWrap: true): after the inner armor is built, encrypt that raw armor string again to this POST's entry route public key. Each fan-out entry is wrapped separately. Skip wrap when the entry key equals the inner encryption key (SI same-node peel → end).
• Hop-sigs: clients must not set X-CoNET-Hop-Sigs. Only SI→SI HTTP :80 appends it (max 3 hops).
• SSE inbound: live SI still writes plaintext JSON { data: pgpMessage }. Keep sending Securitykey on listen; do not assume AES-CBC frames yet.
• Never connect directly to mailbox B; never target the recipient's AA (must be EOA user PGP).
• Client → entry may use HTTPS (PWA default). SI→SI is HTTP :80 only.

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.

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".

• 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' + Securitykey; never connect directly to mailbox B.
• Never set X-CoNET-Hop-Sigs on client POST /post.
• Sender receipts should use sendMessage(..., { beamioNoPush: true }) (mailbox work wrap; requires the sender mailbox route key).
• point- has CoNET-private semantics; public-gateway retrieval relies on CIDv1 mapping and must be documented.

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)
  envelope.ts       # POST body, route-command encrypt, per-entry outer wrap
  nodes.ts          # node probing + `postUrl` (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:

• src/docs/gitbook/l0/si-developer-guide.md — SI /post peel, outer wrap, hop-sigs
• 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

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