summaryrefslogtreecommitdiffstats
path: root/docs/QUICKSTART.md
Commit message (Collapse)AuthorAgeFilesLines
* feat(hub): make mailing an invitation a remembered choiceChristophe Besson2 days1-1/+3
| | | | | | | | A "Send the invitation by e-mail" box under the Invite member field, checked by default and stored as the invite_email preference. Unchecked, invite-notify is never called and the hub never sees the code. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs: the node key is linked from Profile, not SettingsChristophe Besson6 days1-2/+9
| | | | | | | | | QUICKSTART Step 4 named the wrong page. Recorded in §15.3 alongside it: the key is read from `meshbay-node status` or the desktop client and from nowhere else, which is a decision rather than a gap — anyone linking a node is already at a shell prompt. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* docs: add a quickstart and a user guideChristophe Besson7 days1-0/+380
| | | | | | | | | | | | | QUICKSTART takes one Linux machine from downloaded packages to a working group with a second member. USERGUIDE covers using a group and running a node, for a reader who is not a developer. Windows stays in PACKAGING-GUIDE.md. Both are written from the code — the CLI, ops.py, the systemd units and the interface catalogue — rather than from the specification, and they state what is not built as readily as what is. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* docs: remove the documents MESHBAY_DESIGN.md replacesChristophe Besson2026-09-111-243/+0
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Twenty-four files, about 17 000 lines: the two architecture drafts, the three security reviews, eleven design notes, the roadmap, the decisions file, the v1–v4 archive, the deprecated user guide and the stale quickstart. Their content is in MESHBAY_DESIGN.md, and git history holds the originals. The reason to delete rather than keep bannered: a document that is superseded but present still gets read, and a reader cannot always tell which of two accounts of one mechanism is the live one. That was the argument for retiring the user guide rather than repairing it, and it applies to the whole set. What made this safe is the concordance. Roughly 290 comments and docstrings cite these files by section — `musicbay.md §6`, `mediacenter.md §5.5`, `draft-v6 §2.11` — and section 16 maps every one onto its replacement, so not a single comment needs editing to stay followable. It now says plainly that the files are gone and where to recover them, and it gained rows for the three reviews (their findings are section 13), and for the two guides. Four kept documents pointed into the set and were repointed first: `playlists.md` (nine references — it is a live proposal and must not dangle), `WINDOWS-PORT.md`, and CLAUDE.md's example. No dangling reference remains outside section 16. Two files were dropped from the list after checking what they hold. `HTTPS.md` is an operational runbook — Caddy, certificate renewal, DNS, troubleshooting — and MESHBAY_DESIGN.md deliberately covers no operations, so nothing would replace it; the versioned Caddyfile is the config, not the procedure. `cast-smart-tv.md` is the plan for the unbuilt DLNA phase of a feature whose first two phases ship, and section 11.4 summarises it in four lines rather than carrying the SSDP/UPnP work. There is no user guide now, and section 0.1 says so rather than leaving a reader to discover it. Suites green: 2258 passed, 4 skipped. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YVoHVCcfBqud6ZjG4db3y7
* refactor(node): JSON-only control API, Node page absorbs the admin dashboardChristophe Besson2026-09-011-3/+4
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Remove the node daemon's server-rendered admin UI (GET / and /audit, the _render_* helpers and inline templates) and the `meshbay-node ui` CLI verb. The loopback control API stays; it is now JSON only, ruff-clean, and 453 lines (was 1074). Also drop three never-wired endpoints (/api/config, /api/chat/history, /ws/chat, plus broadcast_chat) and the pointless 18000/tcp firewall profiles. The desktop client's Node page (static/node-page.js) takes over what the dashboard showed, reorganised into six tabs (Overview, Groups, Roster, Peers, Audit, Settings): - Overview: version, node id, QUIC port, hub, index-cache maintenance - Roster: node-wide view with unpin - Peers and Audit: auto-load on open, no Load button - Audit: real usernames and group names (resolved from the roster and node.toml), Previous/Next pagination newest-first, Export CSV of every matching row - Settings: node settings, STUN, ICE, denylist, then Unlink from hub Backend: audit.get_entries gains `offset`; /api/audit and /api/peers resolve ids to names via a new _display_names helper; CSP tightened to default-src 'none' now that no HTML is served. draft-v6 sections 2.11 and 2.12 corrected -- the Node page uses the loopback API, not MNP. One capability is intentionally dropped: browser-based admin on a headless server. The CLI covers every operation there. See docs/refactor-node-ui.md. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MQCaZnde4Bjjdu84dhSuF5
* docs: account deletion, notifications, and the APIs that no longer existChristophe Besson2026-08-151-8/+10
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Account deletion is the headline, in the user guide and in draft-v5 §6.1, and the important half is what deletion does *not* do. It releases the username, clears the email and password hash, drops memberships, notifications, refresh tokens and node registrations, and refuses any access token still inside its hour. It does not touch a node: files, the pinned identity and the keypair bundle stay on machines the hub does not command, which is the same sovereignty §5.5 relies on — so deleting a hub account is not an erasure request to the operators hosting you. The IP log survives too, attributable, for its legal retention period. The claims table in §2 gets a row saying exactly this, adversary by adversary. Notifications get a section: one entry per conversation rather than per message, never one for your own message, invitations that clear when you join, muting that lives on the hub so it works from any browser. Then the corrections, which is most of the diff. The guide still described a node HTTP API — `GET /index`, `GET /file/{id}`, an HLS playlist, and a `player.js` that does not exist — with curl examples inviting the reader to expose port 19001. That surface was removed in 0.2.0 as findings C1 and C6, precisely because it served files outside the handshake that decides what a peer may see. Sections 6, 7 and the API reference now describe MNP message pairs, and the quickstart says the same in French. Also corrected: the JWT table advertised a `pk_user` claim that no longer exists (it was what let the token issuer decide who could delete a file), `/pubkeys` no longer returns identity keys, and the GEK-distribution endpoints are gone entirely rather than merely unused. draft-v5 §5.2 had uploads landing in `.uploads/{user_id}/`; they land in `uploads/`, chat attachments included. §6.1 now says the hub learns the author's user_id from chat_notify — a stable identifier, and a metadata leak worth naming rather than leaving as "by whom". CLAUDE.md records why the deployed hub broke this week: create_all() creates missing tables, never missing columns, so a schema change passes every test (fresh DB per run) and never reaches production. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* fix: complete pyproject.toml deps + graceful QUIC fallbackChristophe Besson2026-08-091-8/+21
| | | | | | | | | | | | | | | | | | | | meshbay-node/pyproject.toml: add aioquic>=1.0 (was commented 'v2'), websockets>=12.0 (revocation push). Both are production code since Phase 5. meshbay-hub/pyproject.toml: add aiosqlite (tests without PostgreSQL), slowapi (rate limiting), websockets (revocation push), PyJWT (explicit). transport/__init__.py: QUIC imports wrapped in try/except — node works without aioquic (TCP+TLS + HTTP fallback). QUIC_AVAILABLE flag exported. QUICKSTART.md: replace manual pip list with 'pip install -e' that pulls all deps from pyproject.toml automatically. Add dependency table. CLAUDE.md: clarify that all deps go in pyproject.toml, not manual installs. 81/81 tests. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
* fix: venv --clear required when copying repo across OS (Fedora→Ubuntu)Christophe Besson2026-08-091-11/+8
| | | | | | | | | | | | | Root cause: certifi.where() in the Fedora venv points to /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem which does not exist on Ubuntu. 'python3 -m venv .venv' without --clear keeps the Fedora certifi paths. Fix: always use --clear when recreating a venv on a different OS. Documented in QUICKSTART.md and CLAUDE.md. rsync command updated to exclude .venv/ (in QE/server-state, not versioned). Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
* fix: document pip SSL_CERT_FILE workaround for Python 3.14 on Ubuntu/FedoraChristophe Besson2026-08-091-4/+17
| | | | | | | | pip + Python 3.14 fails with FileNotFoundError in certifi.where() on fresh venvs (truststore bug). Fix: SSL_CERT_FILE pointing to system CA bundle. Documented in CLAUDE.md (Python environment section) and QUICKSTART.md. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
* feat: password-based key derivation + operational QUICKSTARTChristophe Besson2026-08-091-358/+141
| | | | | | | | | | | | | | | | | | | | | keyderive.py: derive Ed25519+X25519 from username+password via Argon2id. Same credentials → same keys on any device. Encrypt/decrypt keypair bundle (AES-256-GCM) for hub storage (web clients). 7/7 tests. Full suite: 81/81. keyderive.js: browser counterpart using PBKDF2-SHA512 + random keypairs encrypted for hub storage. Avoids algorithm mismatch with Python. hub/models.py + users.py: keypair_bundle field added to User, stored on registration, returned in login response for web client key recovery. QUICKSTART.md: fully rewritten. 3 operational scripts in QE/demo-v1/: setup_demo.py — create accounts, group, distribute GEK run_node.py — start HTTP node (watches shared/ directory) download.py — bob login → GEK fetch → decrypt → save All tested locally end-to-end. No invented URLs. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
* docs: add QUICKSTART.md and USERGUIDE.mdChristophe Besson2026-08-091-0/+434
QUICKSTART (434 lines): 6-step guide tested against live https://meshbay.org — demo accounts alice_test/bob_test, real transfer of README.txt (23ms) and 1MB chunk (275ms recv, 2.4ms decrypt), exact Python commands with measured output. USERGUIDE (785 lines): 11-section reference — architecture, account management, group/node config, file sharing, HLS streaming, security model, moderation/CSAM, troubleshooting, full API table. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>