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