| README.mdView |
|---|
| 1 | | -# secure-scuttlebutt |
| 1 | +# ssb-db |
| 2 | 2 | |
| 3 | 3 | A database of unforgeable append-only feeds, optimized for efficient replication for peer to peer protocols. |
| 4 | 4 | |
| 5 | 5 | ## What does it do? |
| 6 | 6 | |
| 7 | | -Secure-scuttlebutt provides tools for dealing with unforgeable append-only message |
| 7 | +ssb-db provides tools for dealing with unforgeable append-only message |
| 8 | 8 | feeds. You can create a feed, post messages to that feed, verify a feed created by |
| 9 | 9 | someone else, stream messages to and from feeds, and more (see [API](#api)). |
| 10 | 10 | |
| 11 | 11 | "Unforgeable" means that only the owner of a feed can modify that feed, as |
| 12 | 12 | enforced by digital signing (see [Security properties](#security-properties)). |
| 13 | | -This property makes secure-scuttlebutt useful for peer-to-peer applications. |
| 14 | | -Secure-scuttlebutt also makes it easy to encrypt messages. |
| 13 | +This property makes ssb-db useful for peer-to-peer applications. ssb-db also |
| 14 | +makes it easy to encrypt messages. |
| 15 | 15 | |
| 16 | 16 | ## Example |
| 17 | 17 | |
| 18 | 18 | In this example, we create a feed, post a signed message to it, then create a stream |
| 19 | 19 | that reads from the feed. |
| 20 | 20 | |
| 21 | 21 | ``` js |
| 22 | 22 | /** |
| 23 | | - * create a secure scuttlebutt instance and add a message to it. |
| 23 | + * create an ssb-db instance and add a message to it. |
| 24 | 24 | */ |
| 25 | 25 | |
| 26 | 26 | var pull = require('pull-stream') |
| 27 | 27 | var fs = require('fs') |
| 40 | 40 | // create the db instance. |
| 41 | 41 | // - uses leveldb. |
| 42 | 42 | // - can only open one instance at a time. |
| 43 | 43 | |
| 44 | | -var ssb = require('secure-scuttlebutt/create')(pathToDB) |
| 44 | +var ssb = require('ssb-db/create')(pathToDB) |
| 45 | 45 | |
| 46 | 46 | // create a feed. |
| 47 | 47 | // - this represents a write access / user. |
| 48 | 48 | // - you must pass in keys. |
| 80 | 80 | ``` |
| 81 | 81 | |
| 82 | 82 | ## Concepts |
| 83 | 83 | |
| 84 | | -Building upon secure-scuttlebutt requires understanding a few concepts |
| 85 | | -that it uses to ensure the unforgeability of message feeds. |
| 84 | +Building upon ssb-db requires understanding a few concepts that it uses to |
| 85 | +ensure the unforgeability of message feeds. |
| 86 | 86 | |
| 87 | 87 | ### Identities |
| 88 | 88 | |
| 89 | 89 | An identity is simply a public/private key pair. |
| 103 | 103 | |
| 104 | 104 | Note that append-only really means append-only: you cannot delete an |
| 105 | 105 | existing message. If you want to enable entities to be deleted or |
| 106 | 106 | modified in your data model, that can be implemented in a layer on top |
| 107 | | -of secure-scuttlebutt using |
| 108 | | -[delta encoding](https://en.wikipedia.org/wiki/Delta_encoding). |
| 107 | +of ssb-db using |
| 108 | +[delta encoding](https://en.wikipedia.org/wiki/Delta_encoding). |
| 109 | 109 | |
| 110 | 110 | ### Messages |
| 111 | 111 | |
| 112 | 112 | Each message contains: |
| 130 | 130 | any order after it's been replicated. |
| 131 | 131 | |
| 132 | 132 | ### Object ids |
| 133 | 133 | |
| 134 | | -The text inside a message can refer to three types of secure-scuttlebutt |
| 134 | +The text inside a message can refer to three types of ssb-db |
| 135 | 135 | entities: messages, feeds, and blobs (i.e. attachments). Messages and |
| 136 | 136 | blobs are referred to by their hashes, but a feed is referred to by its |
| 137 | 137 | signing public key. Thus, a message within a feed can refer to another |
| 138 | 138 | feed, or to a particular point _within_ a feed. |
| 139 | 139 | |
| 140 | 140 | Object ids begin with a sigil `@` `%` and `&` for a `feedId`, `msgId` |
| 141 | 141 | and `blobId` respectively. |
| 142 | 142 | |
| 143 | | -Note that secure-scuttlebutt does not include facilities for retrieving |
| 144 | | -a blob given the hash. |
| 143 | +Note that ssb-db does not include facilities for retrieving a blob given the |
| 144 | +hash. |
| 145 | 145 | |
| 146 | 146 | ### Replication |
| 147 | 147 | |
| 148 | | -It is possible to easily replicate data between two SecureScuttlebutts. |
| 148 | +It is possible to easily replicate data between two instances of ssb-db. |
| 149 | 149 | First, they exchange maps of their newest data. Then, each one downloads |
| 150 | 150 | all data newer than its newest data. |
| 151 | 151 | |
| 152 | 152 | [Scuttlebot](https://github.com/ssbc/scuttlebot) is a tool that |
| 153 | | -makes it easy to replicate multiple SecureScuttlebutts using a |
| 153 | +makes it easy to replicate multiple instances of ssb-db using a |
| 154 | 154 | decentralized network. |
| 155 | 155 | |
| 156 | 156 | ### Security properties |
| 157 | | -Secure-scuttlebutt maintains useful security properties even when it is |
| 158 | | -connected to a malicious secure-scuttlebutt database. This makes it ideal |
| 157 | + |
| 158 | +ssb-db maintains useful security properties even when it is |
| 159 | +connected to a malicious ssb-db database. This makes it ideal |
| 159 | 160 | as a store for peer-to-peer applications. |
| 160 | 161 | |
| 161 | 162 | Imagine that we want to read from a feed for which we know the identity, |
| 162 | | -but we're connected to a malicious secure-scuttlebutt instance. As |
| 163 | | -long as the malicious database does not have the private key: |
| 163 | +but we're connected to a malicious ssb-db instance. As long as the malicious |
| 164 | +database does not have the private key: |
| 164 | 165 | |
| 165 | 166 | - The malicious database cannot create a new feed with the same identifier |
| 166 | 167 | - The malicious database cannot write new fake messages to the feed |
| 167 | 168 | - The malicious database cannot reorder the messages in the feed |
| 173 | 174 | |
| 174 | 175 | |
| 175 | 176 | ## API |
| 176 | 177 | |
| 177 | | -### ssb = require('secure-scuttlebutt/create')(path) |
| 178 | +### ssb = require('ssb-db/create')(path) |
| 178 | 179 | |
| 179 | | -Create a secure-scuttlebutt database at the given path, |
| 180 | | -returns an instance. |
| 180 | +Create an ssb-db database at the given path, returns an instance. |
| 181 | 181 | |
| 182 | | -### require('secure-scuttlebutt')(db, opts) |
| 182 | +### require('ssb-db')(db, opts) |
| 183 | 183 | |
| 184 | 184 | Pass in a [levelup](https://github.com/rvagg/node-levelup) instance |
| 185 | 185 | (it must have [sublevel](https://github.com/dominictarr/level-sublevel) installed), |
| 186 | 186 | and an options object. The options object provides the crypto |
| 187 | 187 | and encoding functions, that are not directly tied into how |
| 188 | | -secure-scuttlebutt works. |
| 188 | +ssb-db works. |
| 189 | 189 | |
| 190 | | -The following methods all apply to a `SecureScuttlebutt` instance |
| 190 | +The following methods all apply to a `ssb-db` instance |
| 191 | 191 | |
| 192 | | -### SecureScuttlebutt#createFeed (keys?) |
| 192 | +### SSBdb#createFeed (keys?) |
| 193 | 193 | |
| 194 | 194 | Create a Feed object. A feed is a chain of messages signed |
| 195 | 195 | by a single key (the identity of the feed). |
| 196 | 196 | This handles the state needed to append valid messages to a feed. |
| 217 | 217 | #### Feed#keys |
| 218 | 218 | |
| 219 | 219 | the key pair for this feed. |
| 220 | 220 | |
| 221 | | -### SecureScuttlebutt#createFeedStream (opts) -> PullSource |
| 221 | +### ssbDb#createFeedStream (opts) -> PullSource |
| 222 | 222 | |
| 223 | 223 | Create a [pull-stream](https://github.com/dominictarr/pull-stream) |
| 224 | 224 | of all the feeds in the database, ordered by timestamps. |
| 225 | 225 | All [pull-level](https://github.com/dominictarr/pull-level) options |
| 226 | 226 | are allowed (start, end, reverse, tail) |
| 227 | 227 | |
| 228 | | -### SecureScuttlebutt#createLogStream({gt: ts, tail: boolean}) -> PullSource |
| 228 | +### ssbDb#createLogStream({gt: ts, tail: boolean}) -> PullSource |
| 229 | 229 | |
| 230 | 230 | create a stream of the messages that have been written to this instance |
| 231 | 231 | in the order they arrived. This is mainly intended for building views. |
| 232 | 232 | The objects in this stream will be of the form: |
| 238 | 238 | ``` |
| 239 | 239 | `timestamp` is generated by |
| 240 | 240 | [monotonic-timestamp](https://github.com/dominictarr/monotonic-timestamp) |
| 241 | 241 | |
| 242 | | -### SecureScuttlebutt#createHistoryStream ({id: feedId, seq: int?, live: bool?, limit: int?, keys: bool?, values: bool?}) -> PullSource |
| 242 | +### ssbDb#createHistoryStream ({id: feedId, seq: int?, live: bool?, limit: int?, keys: bool?, values: bool?}) -> PullSource |
| 243 | 243 | |
| 244 | 244 | Create a stream of the history of `id`. If `seq > 0`, then |
| 245 | 245 | only stream messages with sequence numbers greater than `seq`. |
| 246 | 246 | if `live` is true, the stream will be a |
| 247 | 247 | [live mode](https://github.com/dominictarr/pull-level#example---reading) |
| 248 | 248 | |
| 249 | | -### SecureScuttlebutt#messagesByType ({type: string, live: bool?}) -> PullSource |
| 249 | +### ssbDb#messagesByType ({type: string, live: bool?}) -> PullSource |
| 250 | 250 | |
| 251 | 251 | retrieve messages with a given type. All messages must have a type, |
| 252 | 252 | so this is a good way to select messages that an application might use. |
| 253 | 253 | Returns a source pull-stream. This function takes all the options from [pull-level#read](https://github.com/dominictarr/pull-level#example---reading) |
| 254 | 254 | (gt, lt, gte, lte, limit, reverse, live) |
| 255 | 255 | |
| 256 | 256 | |
| 257 | | -### SecureScuttlebutt#links ({source: feedId?, dest: feedId|msgId|blobId?, rel: string?, meta: true?, keys: true?, values: false?, live:false?, reverse: false?}) -> PullSource |
| 257 | +### ssbDb#links ({source: feedId?, dest: feedId|msgId|blobId?, rel: string?, meta: true?, keys: true?, values: false?, live:false?, reverse: false?}) -> PullSource |
| 258 | 258 | |
| 259 | 259 | Get a stream of links from a feed to a blob/msg/feed id. |
| 260 | 260 | |
| 261 | 261 | The objects in this stream will be of the form: |
| 276 | 276 | > Note: if `source`, and `dest` is provided, but not `rel`, ssb will |
| 277 | 277 | > have to scan all the links from source, and then filter by dest. |
| 278 | 278 | > your query will be more efficient if you also provide `rel`. |
| 279 | 279 | |
| 280 | | -### SecureScuttlebutt#addMap (fn) |
| 280 | +### ssbDb#addMap (fn) |
| 281 | 281 | |
| 282 | 282 | Add a map function to be applied to all messages on *read*. The `fn` function |
| 283 | 283 | is should expect `(msg, cb)`, and must eventually call `cb(err, msg)` to finish. |
| 284 | 284 | |
| 290 | 290 | may only be made *after* the original value is saved in `msg.value.meta.original`. |
| 291 | 291 | |
| 292 | 292 | |
| 293 | 293 | ```js |
| 294 | | -SecureScuttlebutt.addMap(function (msg, cb) { |
| 294 | +ssbDb.addMap(function (msg, cb) { |
| 295 | 295 | if (!msg.value.meta) { |
| 296 | 296 | msg.value.meta = {} |
| 297 | 297 | } |
| 298 | 298 | |
| 302 | 302 | msg.value.meta.buzz = true |
| 303 | 303 | cb(null, msg) |
| 304 | 304 | }) |
| 305 | 305 | |
| 306 | | -const metaBackup = require('secure-scuttlebutt/util').metaBackup |
| 306 | +const metaBackup = require('ssb-db/util').metaBackup |
| 307 | 307 | |
| 308 | | -SecureScuttlebutt.addMap(function (msg, cb) { |
| 308 | +ssbDb.addMap(function (msg, cb) { |
| 309 | 309 | // This could instead go in the first map function, but it's added as a second |
| 310 | 310 | // function for demonstration purposes to show that `msg` is passed serially. |
| 311 | 311 | if (msg.value.meta.fizz && msg.value.meta.buzz) { |
| 312 | 312 | msg.meta = metaBackup(msg.value, 'content') |
| 327 | 327 | ## License |
| 328 | 328 | |
| 329 | 329 | MIT |
| 330 | 330 | |
| 331 | | - |
| 332 | | - |
| 333 | | - |