---
name: Secure Chat Addon Plan
overview: "Cursor plan document for the BackOne Secure Chat addon: a minimal text-only UI addon bundled as `backone-addon-secure-chat`, using WebHub WebSocket signaling (same network/auth as backone-cli) with auto-resolved install paths."
todos:
  - id: verify-implementation
    content: Verify addons/secure-chat source, packaging targets, and main.js navOrder match this plan
    status: pending
  - id: align-debian-deps
    content: Align debian/backone-addon-secure-chat/DEBIAN/control Depends with debian/control (add backone-addon-webhub)
    status: pending
  - id: deploy-test
    content: Run install-addon-secure-chat + rebuild-manifest + restart backone/webhub and execute test checklist
    status: pending
isProject: false
---

# Secure Chat Addon Plan

## Purpose

Add a **Secure Chat** BackOne addon (`secure-chat`) as a separate installable package (`backone-addon-secure-chat`). It provides a **minimal text-only chat UI** modeled on [`addons/chat`](addons/chat), sharing the same BackOne core network and auth token as `backone-cli`, but without attachments or connection-bar chrome.

This document is the **Cursor plan reference** for the addon (implementation is largely in place).

---

## Architecture

```mermaid
flowchart LR
  subgraph ui [SecureChatUI]
    A["addons/secure-chat/frontend/index.js"]
  end
  subgraph shell [AppShell]
    B["addon-loader.js"]
    C["main.js nav"]
    D["webhub-client.js"]
  end
  subgraph signaling [WebHubSidecar]
    E["backone-webhub :9994"]
  end
  subgraph core [BackOneCore]
    F["backone / backone-cli"]
  end
  A -->|subscribe chat_message| D
  A -->|send chat_message| D
  D <-->|WebSocket authtoken| E
  B -->|dynamic import| A
  C -->|mount| A
  F -->|peers networks status| A
```

**Key design choices (current codebase):**

| Aspect | Secure Chat | Chat P2P |
|--------|-------------|----------|
| Signaling | WebHub `chat_message` via [`BackOneWebHubClient`](app-shell/dist/webhub-client.js) | Same |
| UI | Text-only, no file input | Text + attachments |
| Connection bar | Omitted | `BackOneCommLayout` bar |
| Message storage | In-memory session only | In-memory session only |
| Dependencies | `comms-core`, `webhub` | `comms-core`, `webhub` |
| Nav order | First (`secure-chat`) | Second (`chat`) |

> **Note:** An earlier design used a dedicated HTTP route `POST/GET /controller/comms/network/{nwid}/secure-chat` in `AddonHost.cpp`. The current implementation uses **WebHub** instead (aligned with voice/video/chat signaling). No separate C++ comms route is required for secure-chat today.

---

## Source layout

```
addons/secure-chat/
├── addon.json              # manifest (id, requires, frontend, backend metadata)
└── frontend/
    └── index.js            # window.BackOneAddons['secure-chat'] factory
```

### Manifest — [`addons/secure-chat/addon.json`](addons/secure-chat/addon.json)

- `id`: `"secure-chat"`
- `name`: `"Secure Chat"`
- `requires`: `["comms-core", "webhub"]`
- `frontend.entry`: `/app/addons/secure-chat/index.js`
- `frontend.navLabel`: `"Secure Chat"`
- `backend.websocketEvents`: `["secure_chat_message"]` (declared; uses shared `chat_message` over WebHub at runtime)

### Frontend — [`addons/secure-chat/frontend/index.js`](addons/secure-chat/frontend/index.js)

Minimal UI pattern (from chat reference):

- **Keep:** `comm-split-layout`, `BackOnePeerPicker`, `BackOneNetworkSession`, `escapeHtml`, message meta/time styling, `BackOneAuth` / core session
- **Omit:** file attachment input, `BackOneCommLayout` connection bar, persisted localStorage history

**Send path:**

```javascript
BackOneWebHubClient.send({
  type: 'chat_message',
  networkId,
  targetId: selectedPeer.peerId,
  senderName: name,
  body
});
```

**Receive path:** `BackOneWebHubClient.subscribe('chat_message', handler)` — filters by `networkId` and selected peer.

---

## Runtime registration flow

1. `backone` service loads addons from `/usr/lib/backone/addons/` via [`service/AddonHost.cpp`](service/AddonHost.cpp)
2. [`addons/updater/rebuild-addon-manifest.sh`](addons/updater/rebuild-addon-manifest.sh) writes `$BACKONE_HOME/app/addons/manifest.json`
3. App shell [`app-shell/dist/addon-loader.js`](app-shell/dist/addon-loader.js) fetches manifest and `import()`s each `frontend.entry`
4. [`app-shell/dist/main.js`](app-shell/dist/main.js) builds nav (`navOrder: ['secure-chat', 'chat', 'video', 'voice']`) and calls `mount(panel)`
5. [`app-shell/dist/main.js`](app-shell/dist/main.js) connects `BackOneWebHubClient` on init; WebHub sidecar started by `backone-webhub.service`

---

## Bundling and packaging

### Make install — [`make/install-addons.mk`](make/install-addons.mk)

| Target | Installs to (Linux defaults) |
|--------|------------------------------|
| `install-addon-secure-chat` | `addon.json` → `/usr/lib/backone/addons/secure-chat/` |
| | `index.js` → `/var/lib/backone/app/addons/secure-chat/` |

Install paths **auto-resolve** from [`pkg/common/platform-paths.sh`](pkg/common/platform-paths.sh) via [`pkg/common/resolve-install-path.sh`](pkg/common/resolve-install-path.sh):

- Empty `DESTDIR` → live system paths (same defaults as `backone-cli` / updater)
- `DESTDIR=/tmp/stage` → packaging staging prefix

### Debian — [`debian/control`](debian/control)

- Package: `backone-addon-secure-chat`
- Depends: `backone`, `backone-addon-comms-core`, `backone-addon-webhub`, `backone-app-shell`
- Rules: [`debian/rules`](debian/rules) → `install-addon-secure-chat`
- Metadata: [`debian/backone-addon-secure-chat/DEBIAN/`](debian/backone-addon-secure-chat/DEBIAN/)

### macOS / Windows

- [`pkg/mac/build-addon-pkgs.sh`](pkg/mac/build-addon-pkgs.sh) — `backone-addon-secure-chat`
- [`pkg/windows/build-addon-packages.ps1`](pkg/windows/build-addon-packages.ps1) — `backone-addon-secure-chat`

### Version bump

- [`ci/scripts/bump_version.sh`](ci/scripts/bump_version.sh) includes `secure-chat` in addon version loop

---

## Install and deploy

**Live install (no DESTDIR):**

```bash
sudo make install-addon-secure-chat
sudo make install-addon-manifest    # or: sudo backone-updater rebuild-manifest
sudo systemctl restart backone
sudo systemctl restart backone-webhub   # if webhub not running
```

**Package staging:**

```bash
make install-addon-secure-chat DESTDIR=/tmp/backone-stage
make install-addon-manifest DESTDIR=/tmp/backone-stage
```

**Debian package:**

```bash
sudo dpkg -i backone-addon-secure-chat_*.deb
sudo backone-updater rebuild-manifest
sudo systemctl restart backone backone-webhub
```

---

## Test checklist

1. Web UI shows **Secure Chat** nav tab (first in order)
2. Join a BackOne network (same as `backone-cli join`)
3. Select a peer, send text — message appears locally
4. Peer receives `chat_message` over WebHub (if second client connected)
5. Regular **Chat P2P** addon still works (attachments, connection bar)
6. `backone-addon-secure-chat` absent → empty-state hint mentions package name
7. `manifest.json` lists `secure-chat` after install + rebuild-manifest

---

## Scope boundaries

**In scope**

- New `secure-chat` addon source + `backone-addon-secure-chat` package
- Minimal UI (chat reference, text-only)
- WebHub real-time signaling
- Make / Debian / macOS / Windows bundle entries
- Auto-resolved install paths via `platform-paths.sh`

**Out of scope**

- Client-side E2E encryption (Web Crypto)
- Postgres / file-backed message persistence
- Dedicated `/controller/comms/.../secure-chat` HTTP API (superseded by WebHub)
- Changes to voice/video addons

---

## Known gap (optional follow-up)

[`debian/backone-addon-secure-chat/DEBIAN/control`](debian/backone-addon-secure-chat/DEBIAN/control) binary metadata lists `backone-addon-comms-core` + `backone-app-shell` but omits `backone-addon-webhub`; source [`debian/control`](debian/control) includes webhub. Align binary `Depends` with source control for consistent `dpkg` dependency resolution.