Introduction
Getting started with the Enbox SDK — decentralised identity, data, and authentication for TypeScript.
What is Enbox?
Enbox is a TypeScript SDK for building applications where users own their data. Instead of storing user data in your database, Enbox gives each user a Decentralized Web Node (DWN) — a personal data vault they control. Your app reads and writes to it with their permission.
The SDK handles:
- Identity — Decentralized Identifiers (DIDs) that users own, not your server
- Storage — Protocol-defined records in personal DWN vaults, synced across devices
- Authentication — Passwordless auth with vault encryption, recovery phrases, and multi-identity
- Encryption — End-to-end encrypted records with ECDH key agreement
Installation
bun add @enbox/apiQuick start
1. Define a protocol
A protocol describes the data your app works with — its schema, structure, and access rules.
import { defineProtocol } from '@enbox/api';
const TaskProtocol = defineProtocol({
protocol: 'https://example.com/tasks',
published: true,
types: {
task: {
schema: 'https://example.com/schemas/task',
dataFormats: ['application/json'],
},
},
structure: {
task: {},
},
});2. Connect and use
import { Enbox } from '@enbox/api';
const enbox = Enbox.connect({ agent, connectedDid: did });
const tasks = enbox.using(TaskProtocol);
await tasks.configure();Enbox.connect() takes an agent and connectedDid — the agent manages signing keys and DWN sync, while connectedDid is the user's DID. If you use @enbox/auth, you can pass the session directly:
const enbox = Enbox.connect({ session });3. CRUD operations
// Create
const { record } = await tasks.records.create('task', {
data: { title: 'Buy milk', done: false },
});
// Read
const task = await record.data.json(); // { title: 'Buy milk', done: false }
const raw = await record.data.text(); // raw JSON string
const blob = await record.data.blob(); // Blob
const bytes = await record.data.bytes(); // Uint8Array
// Update
await record.update({
data: { title: 'Buy milk', done: true },
});
// Query all tasks
const { records } = await tasks.records.query('task');
for (const r of records) {
console.log(await r.data.json());
}
// Delete
await record.delete();4. Real-time subscriptions
const { liveQuery } = await tasks.records.subscribe('task');
liveQuery.on('create', (record) => {
console.log('New task:', record.id);
});
liveQuery.on('update', (record) => {
console.log('Task updated:', record.id);
});
liveQuery.on('delete', (record) => {
console.log('Task deleted:', record.id);
});Packages
| Package | Description |
|---|---|
@enbox/api | High-level SDK — Enbox.connect(), typed protocols, records CRUD |
@enbox/auth | Authentication — connect, lock, disconnect, multi-identity |
@enbox/dwn-server | Self-hostable DWN server with PostgreSQL, MySQL, SQLite |
@enbox/agent | Low-level agent runtime for DID and DWN operations |
@enbox/protocols | Protocol definitions and type-safe schema helpers |
@enbox/dids | DID creation, resolution, and key management |
@enbox/crypto | Cryptographic primitives (JOSE, key wrapping, ECDH) |
@enbox/common | Shared utilities (TTL cache, LevelStore) |
@enbox/dwn-sdk-js | Decentralized Web Node protocol engine |
@enbox/dwn-sql-store | SQL storage backends for the DWN |
@enbox/dwn-clients | HTTP and WebSocket DWN transport clients |