BridgeSwarm/README.md

BridgeSwarm

A bridge that brings the Hyperswarm P2P stack into normal desktop browsers (Chrome, Edge, Firefox) without forking the browser. A Bare-based native host runs the real modules; the extension injects APIs into the page and talks to the host via Chrome/Firefox native messaging.

License	AGPL-3.0
Publisher	HoneyPeer, LLC

Why BridgeSwarm?

Traditional web applications use a client-server model - all communication goes through a central server. This creates:

• Single point of failure - if the server goes down, everyone is affected
• Latency - messages travel through the server, adding delay
• Bandwidth costs - the server handles ALL traffic
• Privacy concerns - all data passes through the server

BridgeSwarm enables peer-to-peer (P2P) communication directly between browsers:

flowchart LR
  subgraph Traditional["Traditional client–server"]
    B1[Browser] -->|HTTP| S[Server]
    S -->|HTTP| B2[Browser]
  end

  subgraph P2P["BridgeSwarm P2P"]
    P1[Browser] <-->|Noise / Hyperswarm| P2[Browser]
  end

Features

P2P Networking

• Topic-based discovery - Join a topic to find other peers interested in the same thing
• NAT traversal - Works behind home routers and firewalls via UDP hole-punching
• End-to-end encryption - All connections use Noise protocol
• Unique identities - Each tab gets its own cryptographic key pair

Data Storage (Built-in)

• Hypercore - Append-only log
• Hyperbee - Key/value B-tree store
• Hyperdrive - P2P file system
• Autobase - Multi-writer linearized log
• Hyperdb - Schema-based P2P database

Protocols

• Protomux - Protocol multiplexing over connections
• HRPC - Remote procedure calls with streaming support

Optional capabilities (default host)

• Media — bare-media + bare-ffmpeg (BridgeSwarm.media.*) — batch jobs and live VP9 encode
• Files — allowlisted BridgeSwarm.fs.* under storage files/
• SQLite — BridgeSwarm.sqlite.* under storage sqlite/
• Net — BridgeSwarm.net.fetch to public http(s) only

See docs/CAPABILITIES.md.

Quick Start

Easy install (recommended)

Downloads prebuilt native-host binaries and the extension from the rolling Gitea release latest-main. No Node.js or git clone required.

macOS / Linux:

curl -fsSL https://install-bridgeswarm.honeypeer.com | bash

Windows (PowerShell):

irm https://git.ssh.surf/snxraven/BridgeSwarm/raw/branch/main/scripts/install.ps1 | iex

This installs the host to ~/.bridgeswarm/ (or %LOCALAPPDATA%\bridgeswarm\ on Windows) and saves BridgeSwarm-*.zip / .xpi to ~/Downloads.

Load the Extension

Chrome / Edge:

1. Open chrome://extensions
2. Enable Developer mode
3. Drag & drop ~/Downloads/BridgeSwarm-1.0.0.zip onto the page (or Load unpacked after extracting)
4. Extension ID should be jhmbaojjfkkpoolhkoohklbjokdmbdpm
5. Restart the browser

Firefox: temporary via about:debugging → Load Temporary Add-on, or permanent on Nightly/Dev Edition via Install Add-on From File (.xpi).

Develop from source

git clone https://git.ssh.surf/snxraven/BridgeSwarm.git
cd BridgeSwarm
npm run setup          # or ./scripts/install-from-source.sh
# Load unpacked: extension/

Build release artifacts locally:

npm run pack                    # extension zip + xpi
npm run build:dist:package      # all-platform host zips (needs bare-build; best on CI)

Try the examples

In the extension Settings (or Dashboard → Settings), enable Examples server. Open http://127.0.0.1:4173/ (do not use file://). Pick a demo and open it in two tabs.

Dev alternative from the repo: npm run examples (same URL).

Your First P2P App

// Create a swarm
const swarm = new BridgeSwarm({ appName: 'my-app' });

// Join a topic to discover peers
await swarm.join('my-topic');

// Handle incoming connections
swarm.on('connection', (conn, peerInfo) => {
  console.log('Peer connected:', peerInfo.publicKey);
  
  // Receive messages
  conn.on('data', (data) => {
    console.log('Received:', new TextDecoder().decode(data));
  });
  
  // Send messages
  conn.write(new TextEncoder().encode('Hello, peer!'));
});

// Clean up when done
await swarm.leave('my-topic');
swarm.destroy();

Building Blocks

Technology	Purpose
Hyperswarm	P2P networking, DHT discovery, NAT traversal
Corestore	Multi-Hypercore storage
Hypercore	Append-only log
Hyperbee	Key/value B-tree
Hyperdrive	P2P file system
Autobase	Multi-writer log
Hyperdb	Schema-based P2P database
Protomux	Protocol multiplexing
HRPC	Typed RPC with streaming

Architecture

flowchart TB
  subgraph Page["Web page"]
    API["window.BridgeSwarm<br/>join / write / request / media.*"]
  end

  subgraph Ext["Browser extension MV3"]
    CS["content.js<br/>injects api.js"]
    BG["background.js<br/>service worker"]
    OPT["Settings / Dashboard<br/>autosave + examples toggle"]
  end

  subgraph Host["Native host Bare"]
    NH["host.js<br/>Hyperswarm · Hyper* · HRPC"]
    CAP["Capability packs<br/>media · fs · sqlite · net"]
    EX["examples-server<br/>http://127.0.0.1:4173/"]
  end

  API <-->|postMessage| CS
  CS <-->|runtime.sendMessage| BG
  BG <-->|native messaging<br/>4-byte LE + JSON| NH
  NH --> CAP
  BG -->|examplesServer.start/stop| EX
  OPT --> BG

How It Works

1. Extension (Manifest V3): Background service worker maintains the native messaging port; content script injects api.js into pages. Settings autosave to bridgeSwarmSettings (including the examples-server toggle).
2. Native host (Bare runtime): Runs Hyperswarm, Hyper* data stores, HRPC/Protomux attachment, default media capabilities, and the optional local examples HTTP server.
3. Protocol: 4-byte LE length prefix + JSON; binary data base64-encoded (NMH ~1 MB limit).

Security

Important Warnings

The native host runs with your user privileges and can:

• Make network connections
• Read/write files
• Access system resources

Only install from sources you trust!

Built-in Protections

Threat	Protection
Connection flooding	maxPeers option
Malicious peers	swarm.setFirewall({ mode, keys }), swarm.ban(publicKey), peerInfo.ban()
Data interception	Noise encryption (automatic)
Identity spoofing	Cryptographic key pairs
DHT attacks	Rate limiting (built-in)

See theory/bridgeswarm-for-dummies.md for detailed security documentation.

API Reference

BridgeSwarm Class

// Wait for API to be ready
await BridgeSwarm.ready();

// Create swarm
const swarm = new BridgeSwarm({
  appName: 'my-app',    // Required for Hyperswarm
  maxPeers: 50          // Optional: limit connections
});

// Join topic
await swarm.join('my-topic');

// Handle connections
swarm.on('connection', (conn, peerInfo) => {
  // conn: BridgeSwarmConnection
  // peerInfo: { publicKey: 'abc123...', topics: [...] }
});

// Get current connections
const connections = swarm.connections();

// Leave topic
await swarm.leave('my-topic');

// Destroy swarm
swarm.destroy();

Connection

conn.on('data', (data) => {
  // data is Uint8Array
});

conn.on('end', () => {
  // Peer disconnected
});

conn.on('error', (err) => {
  // Connection error
});

// Send data (returns Promise)
await conn.write(new TextEncoder().encode('Hello!'));
// or
await conn.write('Hello!'); // String auto-encoded

Data API

// Hyperbee (key/value)
await BridgeSwarm.request('beePut', { key: 'name', value: 'Alice' });
const result = await BridgeSwarm.request('beeGet', { key: 'name' });

// Hyperdrive (files)
await BridgeSwarm.request('drivePut', { path: '/file.txt', base64: '...' });

// Hyperdb (database)
await BridgeSwarm.request('hyperdbInsert', { 
  collection: 'records', 
  doc: { id: '1', value: 'data' } 
});

Events

// Native host disconnected
window.addEventListener('bridge-swarm-host-disconnect', () => {
  console.log('Host disconnected!');
});

Extension Settings

Open Options or the Dashboard → Settings. Changes save automatically (no Save button).

• Swarm defaults: Default app name, max peers
• Requests: Default request timeout (ms)
• API: Default ready timeout (ms)
• Injection: Skip injection on file:// URLs
• Notifications: Show notification on host disconnect
• Examples: Enable the bundled demos server at http://127.0.0.1:4173/ (native host)
• Debug: Enable debug logging

Examples

Example	Description
chat-advanced	Full-featured P2P chat with rooms, presence, emoji, file sharing
chat	Minimal P2P chat
firewall-room	Peer firewall allowlist/denylist + ban
data-demo	Hyperbee, Hyperdrive, Hyperdb
sync-demo	Auto-replicate Hyper* resources
sdk-demo	BridgeSwarm + Protomux
hrpc-demo	HRPC (unary + streaming)
whiteboard	Collaborative drawing
screenshare	P2P screen sharing (WebRTC + BridgeSwarm signaling)
live-encode	Live VP9/WebM encode via host bare-ffmpeg → MSE
media-demo	Batch media transforms / transcode
clip-studio	Nearline clip tooling on the media pack
local-power	Allowlisted files, SQLite, and public host fetch

Enable Examples server in Settings, then open http://127.0.0.1:4173/ (not file://).

Theory & Documentation

For comprehensive documentation, see:

• theory/bridgeswarm-for-dummies.md - Complete guide covering everything from basics to advanced security
• docs/ARCHITECTURE.md - System architecture and message flow
• docs/API-REFERENCE.md - Full API reference
• docs/DATA-API.md - Data storage API
• docs/CAPABILITIES.md - Bare capability packs (media)
• docs/DEFAULT-MODULES.md - Modules shipped in the default host
• docs/PROTOMUX.md - Protocol multiplexing
• docs/HRPC.md - RPC with streaming
• docs/living/ - Living status, Holepunch notes, and the continued-development plan

Troubleshooting

"Native host has exited"

The launcher runs Bare via Node (node …/node_modules/bare/bin/bare …/index.mjs). Re-run ./scripts/install.sh (or npm install in native-host/ and npm run build:host) so the local bare dependency and launcher paths are correct.

"Access to the specified native messaging host is forbidden"

Extension ID mismatch. Run ./scripts/update-native-manifest-extension-id.sh YOUR_EXTENSION_ID.

"hrpc not available"

Run npm run build:hrpc to generate the HRPC spec.

Users not showing in each other's lists

• Ensure all tabs are joined to the same topic
• Check that events are being routed correctly (enable debug in settings)
• Verify swarms are properly registered

Development

Build Commands

npm test                      # Host helper unit checks (net allowlist)
npm run examples              # Dev: serve demos at http://127.0.0.1:4173/ (or use Settings toggle)
npm run sync:examples         # Copy examples/ into extension + native-host for packaging
npm run brand:build           # Regenerate bridgeswarm-branding/ + sync runtime icons
npm run brand:sync            # Sync existing branding package into extension/assets
npm run build:protomux        # Rebuild Protomux bundle
npm run build:hrpc            # Rebuild HRPC spec (+ mirror into native-host/spec)
npm run build                 # host launcher + protomux + hrpc
npm run pack                  # Package extension (includes examples) → releases/
npm run build:dist            # Standalone host binary (current platform)
npm run build:dist:package    # All platforms + zip archives (CI)

Releases (Gitea)

• Push to main → CI builds artifacts and updates rolling prerelease tag latest-main
• Push tag v*.*.* → versioned Gitea release
• Requires repo secret RELEASE_TOKEN and self-hosted runner label ssh (same as holesail-browser)

File Layout

flowchart TB
  root[BridgeSwarm]

  root --> theory["theory/<br/>guides + essays"]
  root --> docs["docs/<br/>ARCHITECTURE · API · CAPABILITIES · living/"]
  root --> examples["examples/<br/>source of truth for demos"]
  root --> brand["bridgeswarm-branding/<br/>master brand package"]
  root --> extension["extension/<br/>MV3 + synced examples/"]
  root --> native["native-host/<br/>Bare host + examples-server"]
  root --> scripts["scripts/<br/>install · pack · sync-examples · brand"]

  examples --> demos["chat · firewall-room · live-encode · media-demo · …"]
  brand --> brandOut["logo · favicons · app-icons · tokens"]
  extension --> extFiles["api.js · background.js · content.js · options · dashboard"]
  native --> hostFiles["host.js · messenger.js · capabilities/ · examples-server.js"]

npm run sync:examples / npm run pack copy examples/ into extension/examples/ and native-host/examples/ for packaging.

npm run brand:build regenerates bridgeswarm-branding/ and syncs icons into extension/icons/, assets/brand/, assets/logo/, and assets/favicons/.

Compatibility

• Chrome 88+, Edge, Firefox 79+
• Desktop only (native messaging not available on mobile)
• Release install: prebuilt Bare host binaries (darwin/linux/win32) — no Node required for end users
• From-source / CI: Node.js for tooling; Bare >=1.29.4 via the bare npm dependency

License

GNU Affero General Public License v3.0 (AGPL-3.0).

If you modify BridgeSwarm and let others interact with it over a network, review AGPL source-offer obligations (AGPL §13).

Owned and engineered by HoneyPeer, LLC (DeKalb County, Georgia, USA). Legal: [email protected].