Flat files with structure. Serverless auth. Encrypted reads and writes.
NBSON is the flatFile backend for BeTTY,
powering the persistence of BettyDocs: a low-overhead, local-first document storage
engine with native encryption-at-rest.
Each file is line-delimited like NDJSON ("Newline Delimited JavaScript Object Notation"),
enriched with inherited JSON-LD context, indexed, and compressed to binary bson.
"NBSON" is either an acronym for
a) "NBSON is Betty's Standard Object Notation" or
b) "Nota Betty Sunt Objectia Notatio" in Latin.
NBSON files use a unique structural concept we've named "Poor Richard's Pseudo-Homomorphism" that allows appends to encrypted files even when the writer does not have the ability to decrypt or read the file (a.k.a. blind-append).
For more technical detail, read the NBSON/PRPH RFC.
NBSON reads and writes data as a sequence of self-contained lines.
Context is layered using lightweight JSON-LD references,
allowing shared semantics without global schemas.
On disk, each directory may include a small .nbxs file (inspired by Apache's .htaccess) that defines overrides, references, and compression rules for the files it contains.
Similarly, any tag may impose indexing requirements on associated documents, which requires repopulating the meta.indices key in each BettyDoc, as well as the associated index documents in the internal dataspace bettyd uses for searches.
The result: a storage layer that is both human-auditable and machine-precise. Text when you need to read it, binary when you need to store it, and structure that persists through both.
BeTTY's LUMA verbs are actually executed by nbson on disk, allowing users to List, Upsert, Message, and Append BettyDocs across the federated network of bettyland.
By combining semantic references with flat files, nbson offers a middle ground between human legibility and system efficiency, while remaining extremely lightweight in terms of external dependencies. NBSON allows bettyd to deliver on BeTTY's guarantees:
| Function | Conventional Paradigm | NBSON Strategy |
|---|---|---|
| Encryption | Optional "encryption-at-rest" can mean storing unencrypted data on a LUKS partition | Each file is stored with its own encryption vector. If you don't have the private key, you can't read the file. |
| Compression | Cloud storage charges by the byte; compression is optimized for transit | All file contents are compressed and stored in binary format before encrypting on-disk |
| Indexing | Hierarchical schemas define indexed fields by table (relational) or collection (NoSQL) | Tags can implement independent indexing requirements on tagged documents, whose values are then stored in index files and embedded into the BettyDoc's meta.indices key. |
| Searchability | Slow full-text searches on unencrypted data at-rest, fast index searches | Only indexed data readable to the node owner can be searched through bettyd, as data stored encrypted to the node key. Plugins may allow full-text searching by iterating through documents (hopefully with some type of B-tree). |
NBSON is built to deploy a unique approach to secrecy BeTTY calls "Poor Richard's Pseudo-Homomorphism" which allows the system to store, write, and update documents without having a decryption key for the file. This is crucial for things like public inboxes and encrypted logfiles.
See the NBSON/PRPH RFC for more details.
The lakehouse plugin for bettyd allows users to
Storage backends use a special extension of the directory filetype called volume. A volume is a directory where each key corresponds to a file in some backend, and the value of the key contains the meta data which describes that file.
The basic volume type is a virtual filesystem contained in a JSON object. From this we extend the tarballVol, which represents the files in a UNIX tar archive as a BettyDoc. From tarballVol we extend the fileDirVol fileType, and this is the basis for the NBSON plugin.
NBSON, like the rest of the BeTTY stack, can be forked or replaced with other open-source projects fulfilling the same functional promise. For BeTTY, the imperative for future sotrage engines and database connectors, we only insist that they be able to deliver the above guarantees for BeTTY-compliant encryption, indexing and searchability (while optionally handling their own compression needs).