Registry / database / ssb-db

ssb-db

JSON →
library20.4.1jsnpmunverified

ssb-db is a core component within the Secure Scuttlebutt (SSB) ecosystem, providing a secure, replicatable, append-only database for cryptographic message feeds. It is built as a plugin for secret-stack applications, enabling peer-to-peer data synchronization and communication without a central authority. The package ensures message unforgeability through digital signing tied to unique public/private key pairs, forming immutable "feeds." Currently at version 20.4.1, ssb-db has a moderate release cadence, with several minor versions released in recent history (v20.x in 2024), indicating active maintenance and feature development. Key differentiators include its foundational role in the decentralized SSB protocol, strict append-only data model (though flexible through delta encoding for "deletions"), and built-in support for message encryption and indexing. It's designed for applications requiring resilient, offline-first, and censorship-resistant data storage.

npm install ssb-db
INSTALL
IMPORT
SIG · SSB-DB
S
ssb-db
databasejavascriptv20.4.1
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

createApp
✓ const createApp = require('secret-stack')
✗ import { createApp } from 'secret-stack'
`secret-stack` and `ssb-db` are typically used in a CommonJS Node.js environment. ESM `import` is not directly supported for these packages.
ssb-db (plugin object)
✓ .use(require('ssb-db'))
✗ import ssbdb from 'ssb-db'
`ssb-db` is instantiated by `secret-stack` when registered via `.use()`. Direct `require()` is for the *plugin object*, not the running instance.
pull
✓ var pull = require('pull-stream')
✗ import pull from 'pull-stream'
`pull-stream` is a widely used streaming library in the SSB ecosystem. Ensure correct `require` syntax for older Node.js contexts.

This example demonstrates initializing an `ssb-db` instance using `secret-stack`, publishing a new message to the current identity's feed, and then streaming all messages from the log and specifically from the current identity's history. It showcases basic message creation and retrieval patterns.

/** * create an ssb-db instance and add a message to it. */ var pull = require('pull-stream') //create a secret-stack instance and add ssb-db, for persistence. var createApp = require('secret-stack')({}) .use(require('ssb-db')) // create the db instance. // Only one instance may be created at a time due to os locks on port and database files. var app = createApp(require('ssb-config')) //your public key, the default key of this instance. console.log("App ID:", app.id) //or, called remotely app.whoami(function (err, data) { if (err) return console.error(err) console.log("Whoami ID:", data.id) //your id }) // publish a message to default identity // - feed.add appends a message to your key's chain. // - the `type` attribute is required. app.publish({ type: 'post', text: 'My First Post!' }, function (err, msg) { if (err) return console.error(err) // the message as it appears in the database: console.log("Published message:", msg) // and its hash: console.log("Message key:", msg.key) // collect all the messages into an array, calls back, and then ends // https://github.com/pull-stream/pull-stream/blob/master/docs/sinks/collect.md pull( app.createLogStream(), pull.collect(function (err, messagesArray) { if (err) return console.error(err) console.log("All messages in log:", messagesArray) }) ) // collect all messages for a particular keypair into an array, calls back, and then ends // https://github.com/pull-stream/pull-stream/blob/master/docs/sinks/collect.md pull( app.createHistoryStream({id: app.id}), pull.collect(function (err, messagesArray) { if (err) return console.error(err) console.log("Messages for app.id:", messagesArray) app.close() // Close the app instance to release locks }) ) })
Debug
Known issues
breakingThe `addBoxer` API changed in v20.3.0 to provide the `previous` messageId, which is required for modules like `ssb-tribes`. Existing implementations of `addBoxer` will need updates to function correctly.
fix
Update custom `addBoxer` implementations to accept and utilize the `previous` messageId parameter.
affects: >=20.3.0
breakingIn v20.2.0, the `addBoxer` method was modified to accept an `init` method, and `ssb-db` methods now wait for boxer initialization. This impacts custom boxer implementations and their lifecycle.
fix
Review and update custom `addBoxer` implementations to include an `init` method if necessary and account for initialization delays, ensuring they complete before dependent db operations.
affects: >=20.2.0
breakingWith v20.0.1, `addBoxer` / `addUnboxer` methods were exposed with an initialization step, and `ssb-private1` was extracted as a standalone module. When including a *new* unboxer, you *must* rebuild your indexes to correctly process and expose unboxed content, which can be a time-consuming operation.
fix
After adding a new unboxer (e.g., for a new private group format), call the `rebuild` function (exposed since v20.1.0) on your `ssb-db` instance to ensure all flume indexes are consistent.
affects: >=20.0.1
deprecatedVersion 20.0.0 deprecated behavior by exposing unboxed messages on certain methods that other plugins were also exposing. This could lead to conflicts or unexpected data exposure if multiple plugins tried to expose or modify the same message format.
fix
Review how unboxed messages are handled if using v20.0.0 and update to a later version to ensure consistent behavior, or modify downstream plugins accordingly to avoid conflicts.
affects: =20.0.0
gotcha`ssb-db` instances acquire OS-level locks on port and database files. Therefore, only *one instance* of `ssb-db` can be created and run at a time on a given system/directory without conflicts.
fix
Ensure only one `secret-stack` application using `ssb-db` is running at any given time, or configure different database directories and network ports for multiple instances if necessary.
affects: >=1.0.0
Errors
Common errors & fixes
Error: EADDRINUSE: address already in use :::[PORT_NUMBER] or file lock errors (e.g., EBUSY)
Attempting to run multiple `ssb-db` instances simultaneously using the same database directory or network port, or failing to properly close a previous instance, resulting in resource contention.
fix
Ensure all `ssb-db` instances are properly closed (`app.close()` in `secret-stack`) before attempting to start a new one, or configure each instance to use a unique database directory and port.
Error: message.type is required (or similar validation error in `app.publish` callback)
Publishing a message to `app.publish()` without including the mandatory `type` attribute in the message object.
fix
Always include a `type` property in the message object passed to `app.publish()`, for example: `{ type: 'post', text: 'My message' }`.
Unboxed private messages not appearing or incorrect data in indexes after adding new unboxers
New unboxers (e.g., for private group formats) are added to an `ssb-db` instance, but the existing flume indexes, which process encrypted messages, are not rebuilt, leading to unboxed content not appearing in views or queries.
fix
After registering a new unboxer, explicitly call `app.rebuild()` (exposed since v20.1.0) on your `ssb-db` instance to ensure all flume indexes are reprocessed with the new unboxer.
Upgrade
Version history
20.4.1latest on npm
Audit
Dependencies
secret-stackrequiredssb-db functions as a plugin for secret-stack, which is the extensible framework used in SSB applications.
ssb-configrequiredUsed for loading configuration for the ssb-db instance, including file paths and network settings.
pull-streamrequiredThe API exposes pull-stream methods for data manipulation and streaming, making it a common peer dependency for consuming its streams.
Agent activity
27 hits · last 30 days
node
22
Amazon
1
OpenAI (training)
1
Resources
ssb-db — npm install ssb-db · libregistry