1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
|
# MeshBay
MeshBay is a platform for **private, encrypted, self-hosted groups with an
application store**. A group is a set of people, a set of directories on
somebody's machine, and a set of applications over them — chat, files, video,
music, photos. Files stay on the machine that shares them and travel encrypted,
peer to peer; the hub only introduces machines to each other and never sees a
file, a message or a key.
It is not a public file-sharing network. Public groups are an optional hub
feature, and they are off on the reference deployment, [meshbay.org](https://meshbay.org).
```
your machine hub a member
──────────── ─── ────────
meshbay-node ◄─── signalling ────► accounts, ◄─── sign-in ───► browser
holds the files group list, or desktop
holds the group key introductions client
│ │
└──────────── encrypted, peer to peer, direct ───────────────────┘
```
## Getting started
- **Using MeshBay:** [`docs/QUICKSTART.md`](docs/QUICKSTART.md) turns one Linux
machine into a node and invites a second person;
[`docs/USERGUIDE.md`](docs/USERGUIDE.md) explains every step.
- **Running your own hub:** [`docs/PACKAGING-GUIDE.md`](docs/PACKAGING-GUIDE.md),
[`docs/HTTPS.md`](docs/HTTPS.md) and [`docs/MAIL-SERVER.md`](docs/MAIL-SERVER.md).
- **How it works:** [`docs/MESHBAY_DESIGN.md`](docs/MESHBAY_DESIGN.md) is the
architecture specification, and
[`docs/MESHBAY_NODE_PROTOCOL.md`](docs/MESHBAY_NODE_PROTOCOL.md) the wire format.
- **Programming against it:** [`docs/MESHBAY_HTTP_API.md`](docs/MESHBAY_HTTP_API.md)
lists every route of the hub and of the node's control API, and
[`examples/`](examples/) has small Python programs that use them.
## Repository layout
| Path | Contents |
|---|---|
| `packages/meshbay-common/` | Shared cryptography and protocol types |
| `packages/meshbay-hub/` | Hub server (FastAPI + PostgreSQL) and the web client it serves |
| `packages/meshbay-node/` | Node daemon, its CLI and its local control UI |
| `packaging/` | `.deb`, `.rpm` and Windows packaging, systemd units, Caddy and firewall configuration |
| `docs/` | Design specification, protocol, HTTP API, user and operator guides |
| `examples/` | Small Python programs using the hub, a node and its control API |
| `man/` | Manual page for `meshbay-node` |
| `site/` | Static website pages (not deployed) |
| `poc/` | Early proof-of-concept scripts, kept for reference |
## Development
Python 3.12 or later. All dependencies are declared in the packages'
`pyproject.toml` files:
```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e "packages/meshbay-common[dev]" -e "packages/meshbay-hub[dev]" \
-e "packages/meshbay-node[dev]"
.venv/bin/pytest
```
## Licence
MeshBay is free software.
| Component | Licence |
|---|---|
| `packages/meshbay-common/` — the protocol and its cryptography, in Python | [LGPL-3.0-or-later](packages/meshbay-common/COPYING.LESSER) (with the [GPL-3.0](packages/meshbay-common/COPYING) it builds on) |
| The same layer in the clients: the files marked `SPDX-License-Identifier: LGPL-3.0-or-later` — in the interface, `keyderive.js`, `crypto.js`, `playlist-crypto.js`, `transport.js` and `transport-*.js`; on the desktop, `keyring.js`, `transcripts.js` and `argon2-wasm.js`; on Android, `keys/Kdf.kt`, `keys/Keyring.kt` and `keys/Transcripts.kt` | LGPL-3.0-or-later |
| Everything else — hub, node, the rest of the interface, the desktop and Android shells | [AGPL-3.0-or-later](LICENSE) |
The line is the protocol. Whatever a program needs to speak to a hub and a node —
key derivation, the identity bundle, sealing and opening, what is signed, the
wire codec and the transport — is under the Lesser GPL, in every language it
exists in, so a client may use it whatever its own licence; changes to those
files themselves stay under the LGPL. A file without an SPDX line has its
package's licence. Talking to a hub or a node over the network needs none of
this code and carries no condition at all. The rest is under the Affero GPL:
whoever runs a modified hub or node for other people must offer them its
source. The licence texts travel with the interface, in `static/licenses/`.
Group applications — the application store — may be under any licence, free
or not: the interface grants them that in an additional permission,
[`static/licenses/APPLICATION-EXCEPTION.txt`](packages/meshbay-hub/src/meshbay_hub/static/licenses/APPLICATION-EXCEPTION.txt),
as long as they use it only through the documented application interface
(`docs/MESHBAY_DESIGN.md` §9.2–9.4 and the modules the permission names). The
reference application, `helloworld-app.js` and its settings pane, is under 0BSD:
copy it to start one.
The Android application adds one permission to the AGPL, for the Google Play
services libraries the cast to a television goes through:
[`packages/meshbay-android/LICENSE-EXCEPTION.txt`](packages/meshbay-android/LICENSE-EXCEPTION.txt).
Third-party code keeps its own licence: the vendored browser libraries are
listed in [`static/vendor/PROVENANCE.md`](packages/meshbay-hub/src/meshbay_hub/static/vendor/PROVENANCE.md)
with their texts in `LICENSES.txt` beside it, and every package build carries a
`THIRD-PARTY-NOTICES.txt` generated from what it actually ships
([`packaging/third_party_notices.py`](packaging/third_party_notices.py)).
## Source
The repository is published read-only at <https://git.meshbay.org/>, and can be
cloned with:
```bash
git clone https://git.meshbay.org/meshbay.git
```
|