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.

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:

Traditional:     [Browser] ──────► [Server] ──────► [Browser]
P2P:            [Browser] ◄──────► [Browser]
                      (Direct connection)

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

Media - Host-side image/video via bare-media + bare-ffmpeg (BridgeSwarm.media.*) — included in the default host; see docs/CAPABILITIES.md and docs/DEFAULT-MODULES.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://git.ssh.surf/snxraven/BridgeSwarm/raw/branch/main/scripts/web-installer.sh | 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:

Open chrome://extensions
Enable Developer mode
Drag & drop ~/Downloads/BridgeSwarm-1.0.0.zip onto the page (or Load unpacked after extracting)
Extension ID should be jhmbaojjfkkpoolhkoohklbjokdmbdpm
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

npm run examples

Opens http://127.0.0.1:4173/ (do not use file:// — browsers treat each local file as a unique origin). Pick a demo and open it in two tabs.

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

┌─────────────────────────────────────────────────────────────┐
│                        Your Web Page                        │
│                                                             │
│   window.BridgeSwarm                                        │
│   ├── new BridgeSwarm({ appName })                          │
│   ├── swarm.join(topic)                                     │
│   ├── swarm.on('connection', ...)                           │
│   ├── conn.write(data)                                      │
│   └── BridgeSwarm.request('beeGet', { key })                │
└─────────────────────────────────────────────────────────────┘
                              │
                              │ window.postMessage
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   Chrome Extension                          │
│                                                             │
│   content.js ─────► background.js ─────► native host        │
│   (injects API)    (service worker)    (P2P networking)     │
└─────────────────────────────────────────────────────────────┘

How It Works

Extension (Manifest V3): Background service worker maintains native messaging port; content script injects api.js into pages
Native host (Bare runtime): Runs Hyperswarm, data stores, handles connections
Protocol: 4-byte LE length prefix + JSON; binary data base64-encoded

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

Right-click the extension icon → Options:

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
Debug: Enable debug logging

Examples

Example	Description
chat-advanced	Full-featured P2P chat with rooms, user presence, emoji, file sharing, typing indicators
chat	Minimal P2P chat - join topic, send messages
data-demo	Data API demo - Hyperbee, Hyperdrive, Hyperdb
sdk-demo	BridgeSwarm + Protomux usage
hrpc-demo	HRPC ping demo
whiteboard	Collaborative drawing
screenshare	P2P screen sharing (WebRTC + BridgeSwarm)

Open any example's index.html in your browser to try it.

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

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 run examples              # Serve demos at http://127.0.0.1:4173/ (not file://)
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 → releases/BridgeSwarm-*.zip|.xpi
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

BridgeSwarm/
├── theory/                          # Comprehensive documentation
│   └── bridgeswarm-for-dummies.md   # Complete guide
├── docs/                            # API documentation
│   ├── ARCHITECTURE.md
│   ├── API-REFERENCE.md
│   ├── DATA-API.md
│   ├── CAPABILITIES.md
│   ├── DEFAULT-MODULES.md
│   ├── PROTOMUX.md
│   └── HRPC.md
├── examples/                         # Example applications
│   ├── chat-advanced/               # Full-featured chat
│   ├── chat/                        # Basic chat
│   ├── data-demo/                   # Data API demo
│   ├── sdk-demo/                    # SDK demo
│   ├── hrpc-demo/                   # HRPC demo
│   ├── whiteboard/                  # Collaborative whiteboard
│   └── screenshare/                 # Screen sharing
├── extension/                        # Browser extension (MV3)
│   ├── api.js                       # Main API
│   ├── background.js                 # Service worker
│   ├── content.js                   # Content script
│   └── manifest.json
└── native-host/                      # Native messaging host
    ├── host.js                      # Main host logic
    ├── messenger.js                 # Protocol handler
    └── index.mjs                   # Entry point

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

MIT