Commit 0c350955d4d016bb592f6ad98c2db14db35339b1
improve readme
Dominic Tarr committed on 2/2/2019, 9:13:54 PMParent: 1c3ff8af7e971a4642a078aec191c4a869a2c163
Files changed
| README.md | changed |
| README.md | |||
|---|---|---|---|
| @@ -44,13 +44,14 @@ | |||
| 44 | 44 … | ``` | |
| 45 | 45 … | >sbot userInvites.openInvite {invite_code} | |
| 46 | 46 … | { private:..., reveal:...} | |
| 47 | 47 … | ``` | |
| 48 | -to see what you are inviting them to. this can contain a welcome | ||
| 49 | -message. The `private` section is only readable by them, | ||
| 50 | -but the `reveal` section is made public once they accept the invite. | ||
| 48 … | +This shows what you have been invited to. This can contain a welcome | ||
| 49 … | +message, or access to private groups (TODO). | ||
| 50 … | +The `private` section is only readable by the guest, | ||
| 51 … | +but the `reveal` section is made public once the guest accepts the invite. | ||
| 51 | 52 … | ||
| 52 | -to actually accept the invite, they do: | ||
| 53 … | +then, to actually accept the invite, they do: | ||
| 53 | 54 … | ||
| 54 | 55 … | ``` | |
| 55 | 56 … | >sbot userInvites.acceptInvite {invite_code} | |
| 56 | 57 … | accept_message... | |
| @@ -75,13 +76,8 @@ | |||
| 75 | 76 … | on their own feed (`type: 'user-invite/accept'`), and then pass that to the pub, | |
| 76 | 77 … | who then publishes a confirm message (`type: user-invite/confirm'`). | |
| 77 | 78 … | Now peers who replicate the pub's feed can see the guest has arrived. | |
| 78 | 79 … | ||
| 79 | -## TODO | ||
| 80 | - | ||
| 81 | -* decide on encoding. must contain: `seed, invite, pubs+` | ||
| 82 | -* test that it works on unreliable connections and end points. | ||
| 83 | - | ||
| 84 | 80 … | ## api | |
| 85 | 81 … | ||
| 86 | 82 … | ### userInvites.create({id?, public?, reveal?, hops?}, cb(err, invite)) | |
| 87 | 83 … | ||
| @@ -124,9 +120,9 @@ | |||
| 124 | 120 … | ## example | |
| 125 | 121 … | ||
| 126 | 122 … | Alice wishes to invite Bob to her corner of the ssb | |
| 127 | 123 … | network. But she is does not have a pub server. | |
| 128 | -She creates a user invite, indicating that she | ||
| 124 … | +She creates a _user invite_, indicating that she | ||
| 129 | 125 … | is creating an invite. This is just a message on her feed. | |
| 130 | 126 … | ||
| 131 | 127 … | ``` js | |
| 132 | 128 … | var seed = random(32) //32 bytes of randomness | |
| @@ -153,27 +149,28 @@ | |||
| 153 | 149 … | that alice created the invite code, and so that no one | |
| 154 | 150 … | else can claim they invited alice's friend. | |
| 155 | 151 … | The signature has an `invite_cap` so that it cannot be confused with another type of signature. | |
| 156 | 152 … | ||
| 157 | -*** TODO *** alice encodes the seed, the message id, | ||
| 153 … | +Alice encodes the seed, the invite message id, | ||
| 158 | 154 … | and the addresses of some pubs that are likely | |
| 159 | 155 … | to replicate bob. this is called the "invite code" | |
| 160 | 156 … | ||
| 161 | 157 … | she then gives the invite code to bob via a channel | |
| 162 | 158 … | she already trusts, say, a 1:1 chat app. | |
| 163 | 159 … | ||
| 164 | 160 … | bob then connects to one of the pubs in the invite | |
| 165 | -code, using the guest id derived from the seed | ||
| 166 | -(which the pub will recognise as alice's guest) | ||
| 161 … | +code, using the seed to derive a private key. | ||
| 162 … | +(which the pub will recognise as alice's guest id) | ||
| 167 | 163 … | ||
| 168 | -bob then requests the invite message, and probably | ||
| 164 … | +bob then requests the invite message id, and probably | ||
| 169 | 165 … | alice's feed. if the invite has reveal and public | |
| 170 | -fields, bob decrypts them. | ||
| 166 … | +fields, bob decrypts them by hashing the seed. | ||
| 171 | 167 … | ||
| 172 | -if bob accepts the invite, | ||
| 168 … | +If bob accepts the invite, | ||
| 173 | 169 … | bob then creates an "user-invite/accept" message, | |
| 174 | 170 … | which is a proof that he has the seed, and knows | |
| 175 | -who's invite he is accepting. | ||
| 171 … | +who's invite he is accepting, and indicates the long term | ||
| 172 … | +key he will be using. At this point, he can forget the seed. | ||
| 176 | 173 … | ||
| 177 | 174 … | ``` js | |
| 178 | 175 … | var invite_key = ssbKeys.generate(null, seed) | |
| 179 | 176 … | var invite_cap = require('ssb-config').caps.invite | |
| @@ -190,9 +187,9 @@ | |||
| 190 | 187 … | }) | |
| 191 | 188 … | ``` | |
| 192 | 189 … | ||
| 193 | 190 … | This is then passed to the pub, who verifies it, | |
| 194 | -and if is correct, posts a new message containing it. | ||
| 191 … | +and if is correct, posts a confirm message. | ||
| 195 | 192 … | ||
| 196 | 193 … | ``` js | |
| 197 | 194 … | sbot_pub.publish({ | |
| 198 | 195 … | type: 'user-invite/confirm', | |
| @@ -205,9 +202,9 @@ | |||
| 205 | 202 … | that bob created. this makes the message available | |
| 206 | 203 … | for other peers to validate, since they do not follow | |
| 207 | 204 … | bob yet. | |
| 208 | 205 … | ||
| 209 | -the pub now knows that bob and alice are friends, | ||
| 206 … | +The pub now knows that bob and alice are friends, | ||
| 210 | 207 … | and will start replicating bob. Other friends | |
| 211 | 208 … | of alice who replicate the pub will also see this, | |
| 212 | 209 … | and they will also start replicating bob. Thus | |
| 213 | 210 … | alice's friends can welcome bob, knowing it's a friend | |
| @@ -287,4 +284,11 @@ | |||
| 287 | 284 … | ||
| 288 | 285 … | ||
| 289 | 286 … | ||
| 290 | 287 … | ||
| 288 … | + | ||
| 289 … | + | ||
| 290 … | + | ||
| 291 … | + | ||
| 292 … | + | ||
| 293 … | + | ||
| 294 … | + | ||
Built with git-ssb-web