diff options
Diffstat (limited to 'docs/USERGUIDE.md')
| -rw-r--r-- | docs/USERGUIDE.md | 72 |
1 files changed, 61 insertions, 11 deletions
diff --git a/docs/USERGUIDE.md b/docs/USERGUIDE.md index fc9cf40..eb9452e 100644 --- a/docs/USERGUIDE.md +++ b/docs/USERGUIDE.md @@ -185,6 +185,10 @@ identity: it asks for your passphrase, unlocks the copy of your keys kept there, and you are in. No second code, nobody to ask — which is another reason the passphrase is worth choosing well. +That copy exists only if your account allows browsers. An account created in the +desktop application does not until you say so (below): a browser then cannot +open your groups with the passphrase alone, and tells you why. + ### The desktop application Worth installing if you use MeshBay more than occasionally: @@ -193,7 +197,7 @@ Worth installing if you use MeshBay more than occasionally: |---|---|---| | Install | none | a package | | Interface comes from | the hub, on every visit | inside the package, from disk | -| Keys | in the browser, plus a copy on each node | in the OS keyring, never bundled anywhere | +| Keys | in the browser, plus a copy on each node | kept by the application in the OS keyring; a copy on each node only if you allow browsers | | Downloads | to disk where the browser allows it | native, streamed, no size limit | | Casting to a TV | — | yes | @@ -203,6 +207,23 @@ any. So the application is the one to prefer for anything you care about. The browser stays, and is a perfectly reasonable way to use MeshBay — being able to open a group on someone else's laptop with nothing installed is worth having. +**Browser access** (Profile → Browser access, in the application) decides whether +a browser can open your groups with your passphrase. With it off — the default for +an account created in the application — your keys stay on this computer and +nothing of them is left on anybody's node. With it on, the application leaves a +locked copy on each node, as a browser would. The change reaches each group the +next time it opens. A browser can also be approved from the application for +itself, group by group: the browser shows a linking code (*Get a linking code*), +and you enter it in the application under *Your devices on this node*. That gives +the browser keys of its own without turning browser access on. + +The application asks in a small window of its own, not in the page, before it +hosts a group on this computer, shares a folder you did not pick in its folder +dialog, replaces a group's key, clears the denylist, turns browser access on, or +points the node at another account. A folder you pick in the folder dialog is not asked about +twice. That window belongs to the application, so nothing displayed in the page +— which shows content from other people's nodes — can answer it for you. + --- ## 4. Joining a group @@ -212,7 +233,9 @@ Someone who runs a node invites you. You need an account on the same hub first. 1. **They send you a code** — eight characters like `K7P2-9WQX`, by message, mail, or read out loud. It is good for 7 days by default, works once, and only for your account in that one group. -2. **You sign in**, and the group is already in your sidebar. +2. **You sign in**, and the group is waiting under **Invitations** on your + home page. **Accept** it — until you do, nothing connects to it — and it + joins your sidebar. **Decline** if you did not expect it. 3. **You open it.** It says *"This node needs to recognise you"*. Paste the code. 4. Done — the machine hosting the group recognises you from now on, and the @@ -361,6 +384,11 @@ resume. - **Browsing is never queued.** Posters, thumbnails, opening a photo or a document to look at it — none of it takes a transfer slot. A busy group browses exactly like an idle one. +- **In a browser, Open is offered for PDFs, pictures, music, video and plain + text.** A web page, an SVG image or anything else that could run code is + not opened in a tab: the page would run as MeshBay, with your session. The + file is saved all the same — open it from your downloads folder. The + desktop application opens every file with your system's own program. ### Casting to a TV @@ -566,10 +594,19 @@ meshbay-node member invite alice_dupont Or the group's **Members** tab, from a paired browser. -They need an account on the same hub first. The invitation registers their -membership on the hub and produces a code that never goes near it. Send the -code out of band; they enter it the first time they open the group. You do not -need to be online then. +They need an account on the same hub first. The invitation appears on their +home page, where they accept it, and produces a code that never goes near the +hub. Send the code out of band; they enter it the first time they open the +group. You do not need to be online then. + +### Other nodes hosting your group + +Your own nodes serve your groups without asking. Any other node — a member's, +say, offering a second copy — serves one of your groups only after you approve +it: it appears in the group's settings under **Hosts**, and you are notified +the first time it asks. **Approve** or **Refuse**; either can be changed later. +A member's node holds the same group key as everyone, so a node you did not +approve could otherwise present itself to your members as the group's host. **Inviting someone who has no account yet** is a link: @@ -722,9 +759,12 @@ deciding what belongs in a group and what is better kept elsewhere. browser downloads its code from the hub every time you open it; the application carries its own and never asks the hub for any. For anything you would rather not stake on the hub behaving, prefer the application. -- **Your passphrase is what guards your keys.** A copy of them, locked with it, - sits on each machine you have joined. A long one puts that out of reach; a - guessable one does not. This is the single thing most worth getting right. +- **Your passphrase is what guards your keys.** When your account allows + browsers, a copy of them sits on each machine you have joined, locked with your + passphrase and a second secret your hub keeps, so the people running those + machines cannot sit and guess at it. Whoever runs the hub holds that second + secret, though, and for them a guessable passphrase is still a weak one. A long + one puts it out of reach. This is the single thing most worth getting right. - **An open group is open.** Anybody can walk into one, which is what open means. Invite-only is the default, and is what you want for anything personal. - **The hub sees who is in which group, and when.** Never what was said or @@ -769,8 +809,18 @@ namespace, so a volume mounted after it started is invisible to it. The browser is not paired. `meshbay-node operator pair`, then enter the code in the Members tab. -**A member changed their passphrase while the node was down.** -`meshbay-node member unpin <user>`, then a fresh invitation code. +**A member changed their passphrase in a browser while the node was down.** +`meshbay-node member unpin <user>`, then a fresh invitation code. The desktop +application catches up by itself the next time it reaches the node. + +**"This node holds your identity in a format this version no longer reads."** +The member's keys on that node were locked the way versions before 0.17 did it, +which this version refuses. `meshbay-node member unpin <user>` on the node, then a +fresh invitation code. + +**"Browser access is off for this account."** +The account keeps its keys in the desktop application. Turn browser access on +there (Profile), or approve this browser from it. **Video says the codec is not supported.** The source codec has no decoder in that browser and transcoding is off, or |