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
|
# MeshBay — Project Conventions
## What this project is
MeshBay is a decentralized peer-to-peer platform for file sharing, video streaming, and group messaging.
See `docs/meshbay-draft-v3.md` for the architecture specification.
## Repository structure
```
meshbay/
├── packages/
│ ├── meshbay-common/ # Shared crypto + protocol — python3-meshbay-common RPM
│ ├── meshbay-hub/ # Hub server (FastAPI + PostgreSQL) — meshbay-hub RPM
│ └── meshbay-node/ # Node daemon + local UI — meshbay-node RPM
├── poc/ # POC spike scripts (reference, not production)
└── docs/ # Architecture drafts and POC plans
```
## Python environment
- **Minimum Python:** 3.12
- **Package manager:** uv (`uv sync` at root installs all workspace packages in editable mode)
- **Build backend:** hatchling (per package `pyproject.toml`)
```bash
# Install dev environment
uv sync
# Run hub (dev mode)
uv run meshbay-hub
# Run node (dev mode)
uv run meshbay-node
# Run tests
uv run pytest
```
## Code conventions
- **Linter/formatter:** ruff (`uv run ruff check .` / `uv run ruff format .`)
- **Line length:** 100
- **Type hints:** required on all public functions
- **Comments:** only when the WHY is non-obvious; no docstrings restating the function name
- **No prints in library code** — use `logging` module
## Versioning
### Package versions (SemVer)
- Format: `MAJOR.MINOR.PATCH`
- Pre-1.0: breaking changes bump MINOR, not MAJOR
- All three packages share the same version number (released together)
### Protocol versions (independent)
- MNP: `0.1` → bumped independently of package version
- MHP: `0.1` → bumped independently of package version
- Every wire message carries a `v` field
- Breaking change → MAJOR bump; backward-compatible → MINOR bump
- N-2 MINOR backward compatibility guaranteed
## Commit messages (Conventional Commits)
```
feat(node): add directory watcher with watchdog
fix(hub): include jti in all JWT tokens
chore(common): add Argon2id calibration to crypto.py
docs: update draft v3 with POC findings
test(common): add wrap/unwrap GEK round-trip test
```
Types: `feat`, `fix`, `chore`, `docs`, `test`, `refactor`, `perf`
Scope: `hub`, `node`, `common`, or omitted for cross-cutting
## Security rules
- **Never commit private keys** (hub_private.pem, *.key, unlock.key, keystore.enc)
- **Never commit node_state.json or bob_state.json** (contain private key material)
- **Never log GEK, private keys, or plaintext passwords** — even at DEBUG level
- **meshbay.org is internet-facing** — kill all test processes after spikes, close test UFW ports
## Known calibration TODOs
- Argon2id `memory_cost`: currently 65536 (64 MB, 78ms) — increase to 262144 (256 MB) before prod
to target ~500ms on typical home server hardware. Implement a `calibrate` CLI command.
## meshbay.org server
- OS: Ubuntu 26.04 LTS, Python 3.14.4
- SSH: `ssh cbesson@meshbay.org`
- Web proxy: Caddy (to be installed) behind ports 80/443
- UFW rules: only 22/tcp, 80/tcp, 443/tcp
- **Always close test ports after spikes** (`sudo ufw delete allow <port>/<proto>`)
- Hub POC files: `~/meshbay-poc/` (reference only, not production)
|