# BridgeSwarm

<p align="center">
  <img src="bridgeswarm-branding/logo/bridgeswarm-icon-512.png" alt="BridgeSwarm" width="160">
</p>

A bridge that brings the **Hyperswarm P2P stack** into normal desktop browsers (Chrome, Edge, Firefox) without forking the browser. A [Bare](https://www.npmjs.com/package/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](LICENSE)** |
| 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:

```mermaid
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](docs/CAPABILITIES.md).

## Quick Start

### Easy install (recommended)

Downloads prebuilt native-host binaries and the extension from the rolling Gitea release [`latest-main`](https://git.ssh.surf/snxraven/BridgeSwarm/releases/tag/latest-main). No Node.js or git clone required.

**macOS / Linux:**
```bash
curl -fsSL https://install-bridgeswarm.honeypeer.com | bash
```

**Windows (PowerShell):**
```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

```bash
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:
```bash
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

```javascript
// 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

```mermaid
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](theory/bridgeswarm-for-dummies.md) for detailed security documentation.

## API Reference

### BridgeSwarm Class

```javascript
// 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

```javascript
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

```javascript
// 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

```javascript
// 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](theory/bridgeswarm-for-dummies.md)** - Complete guide covering everything from basics to advanced security
- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** - System architecture and message flow
- **[docs/API-REFERENCE.md](docs/API-REFERENCE.md)** - Full API reference
- **[docs/DATA-API.md](docs/DATA-API.md)** - Data storage API
- **[docs/CAPABILITIES.md](docs/CAPABILITIES.md)** - Bare capability packs (media)
- **[docs/DEFAULT-MODULES.md](docs/DEFAULT-MODULES.md)** - Modules shipped in the default host
- **[docs/PROTOMUX.md](docs/PROTOMUX.md)** - Protocol multiplexing
- **[docs/HRPC.md](docs/HRPC.md)** - RPC with streaming
- **[docs/living/](docs/living/README.md)** - 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

```bash
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

```mermaid
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/`](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](LICENSE)** ([AGPL-3.0](https://www.gnu.org/licenses/agpl-3.0.html)).

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: [legal@honeypeer.com](mailto:legal@honeypeer.com).