Merge branch 'link-to-other-docs' into 'main'

mostly link to magic-folder docs

See merge request !4

designs/lightweight-design.md

@@ -137,9 +137,11 @@ _Focus on external and internal interfaces, how externally-triggered system even
 
 ## Device linking protocol overview
 
-Below is described a protocol for inviting a "read-only" device to an existing magic-folder.
-"Existing magic-folder" implies that some other device (i.e. Desktop Private Storage) has created such a folder, and is the administrator of it.
+The magic-folder documentation [describing the invite protocol](https://magic-folder.readthedocs.io/en/main/invites.html#inviting-laptop) cover what we'll need for the mobile application.
+
+We do not need the read-write parts, so we briefly describe the process and changes here.
 
+"Existing magic-folder" implies that some other device (i.e. Desktop Private Storage) has created such a folder, and is the administrator of it.
 "Read-only" means that there is no support for handling or spending ZKAPs, which means no support for writing to or creating any mutables.
 
 We currently assume both devices already have access to the same Grid.
@@ -158,6 +160,8 @@ We do _not_ use the "Transit" portion of Magic Wormhole: all communications are
 1. The Desktop device allocates a Wormhole code
   - uses AppID `private.storage/wormhole/invites`
   - this means the Desktop is connected to the Wormhole mailbox server, has an allocated mailbox, and has a user-friendly code ready to present to the user
+  - the default wormhole server is the public one, howerver we will use `mailbox.mw.leastauthority.com` instead (so must reflect this when creating our magic-folder)
+  - `magic-wormhole set-config --wormhole-uri wss://mailbox.mw.leastauthority.com` (needs implementation)
 
 2. Transcribe the code to the mobile device
  - (this could simply be typed in by the user -- simple to implement: first cut?)
@@ -176,84 +180,20 @@ We do _not_ use the "Transit" portion of Magic Wormhole: all communications are
   - they know this because a magic-wormhole `versions` message has been exchanged (serving as key-verification). See [Magic Wormhole documentation](https://github.com/magic-wormhole/magic-wormhole/blob/master/docs/client-protocol.md) for more details.
 
 4. Ensure protocol compatibility
- - We use the "app-versions" feature of Magic Wormhole, which is exchanged during the `versions` message mentioned above.
- - Application can include arbitrary keys here. We use this to specifiy what versions of messages are supported.
- - This will look like this::
-
-    "magic-folder": {
-        "supported-messages": [
-            "invite-v1",
-        ]
-    }
- - This is part of the magic-wormhole protocol. For example, in the Python API, this would be passed as `versions={"magic-folder": ...}` in the `wormhole.create()` call.
- - As additional message kinds are added, they should be added here too.
- - In individual messages, the `"protocol": ...` key shall correspond to a `"supported-messages"` value.
+ - Follow the protocol described in [the magic-folder repository](https://magic-folder.readthedocs.io/en/main/invites.html#inviting-laptop) to determine version compatibility.
  - A peer MUST only send messages for protocols the other side supports.
 
 
 ## Part Two: Join a Folder
 
-Once communications are established, we're ready to send and receive application messages via the mailbox.
-All such messages are JSON encoded.
-All such messages include a `kind` field.
-All such messages include a `protocol` field indicating which protocol they correspond to (see "app_versions" in "Establish Communications").
-
-Note that although we only specifiy a single sort of message here, there will likely be more messages in the future.
-
-The inviting device sends an "invite" message to the read-only device::
-
-    {
-        "kind": "join-folder",
-        "protocol": "invite-v1",
-        "folder-name": "arbitrary string",
-        "collective-dmd": "<read-only Directory URI>",
-        "participant-name": "arbitrary string",
-        "mode": "read-only",
-    }
-
-The "`folder-name`" is an arbitrary string which is what the admin device calls this folder;
-it may be re-used by the read-only device or ignored (e.g. the UI may allow the read-only application to call this folder whatever they want).
-
-The "`collective-dmd`" is a read-only Tahoe-LAFS directory URI and represents all participants in the magic-folder.
-It could serve as a unique identifier for the magic-folder.
-
-The administrating device decides all participant names, and tells the read-only device what its name will be in "`participant-name`" (i.e. a sub-directory by this name will ultimately appear in the Collective).
-This name is arbitrary (i.e. the human using the administration device types it in).
-
-For these kinds of invites, the only `"mode"` supported is `"read-only"`.
-A read-only device receiving an invite with any other `"mode"` SHOULD reply with an error.
-
-Upon receipt of such an invite, the read-only device MUST respond with a reply message.
-This message can be affirmative or not -- for example, a UI may ask the read-only device user for confirmation.
-An affirmative reply is essentially empty and looks like::
-
-    {
-        "protocol": "invite-v1",
-        "kind": "join-folder-okay",
-    }
-
-A rejection reply says why we are rejecting the invite and looks like::
-
-    {
-        "protocol": "invite-v1",
-        "kind": "join-folder-reject",
-        "reject-reason": "<arbitrary string>",
-    }
-
-If the inviting device receives a rejection message, it MUST NOT add the participant to the Collective.
-When receiving an affirmative reply, the inviting device adds a read-only, immutable, empty directory to the Collective under the given name.
-This entry indicates to all devices in the Collective that a given device has read-only access.
-
-The inviter side sends back a final acknowledgement to the invited device.
-This indicates whether the participant was added successfully or not with the `"success"` field::
+On the inviting device, a UI will call the [.../invite](https://magic-folder.readthedocs.io/en/main/invites.html#post-invite) endpoint in a magic-folder daemon.
+This will initiate the wormhole and give back a wormhole code.
+The [.../invite-wait](https://magic-folder.readthedocs.io/en/main/invites.html#post-invite-wait) API may be used to learn when it is completed.
 
-    {
-        "protocol": "invite-v1",
-        "kind": "join-folder-ack",
-        "success": True,
-    }
+The invitee side will get a read-only invite message as [described in the magic-folder docs](https://magic-folder.readthedocs.io/en/main/invites.html#accepting-the-invitation).
+The mobile side must respond with [one of the final messages](https://magic-folder.readthedocs.io/en/main/invites.html#finalizing-the-invite).
 
-This concludes the protocol and both sides close their mailboxes.
+This will conclude the invite flow.
 
 **Future enhancement**: a participant could be invited to multiple folders by doing multiple rounds of the above communication. This then needs a way to associate replies to requests (e.g. unique IDs, or enforced sequential answers, or some other technique)