enbox

The decentralized backend for web apps.

Caution

Research Preview -- Not Production Ready

Enbox is under active development. APIs may break, preview DWN servers may be wiped, and the code has not been externally audited. Do not store sensitive or irreplaceable data yet. We are not accepting external contributions while the core APIs are still changing.

What Enbox Provides

Enbox is a Bun/TypeScript monorepo for building apps on Decentralized Web Nodes (DWNs). It includes:

• A high-level app SDK with typed protocols, record CRUD, subscriptions, and DID helpers.
• A headless auth layer for local vaults, wallet connect, session restore, and sync startup.
• An agent runtime with encrypted identity/key stores and live/durable DWN sync.
• A self-hostable DWN server with HTTP/WebSocket APIs and SQL-backed persistence.
• Shared DID, crypto, protocol, browser, CLI, and codegen packages.

The model is protocol-first: apps define portable record schemas and access rules, users control their DIDs and DWN endpoints, and encrypted data can move between apps that understand the same protocol.

Quick Start

bun add @enbox/api

import { Enbox, defineProtocol } from '@enbox/api';

const { enbox, session } = await Enbox.connect({
  password      : userPassword,
  createIdentity: true,
  dwnEndpoints  : ['https://enbox-dwn.fly.dev'],
});

const BookmarkProtocol = defineProtocol({
  protocol  : 'https://example.com/bookmarks',
  published : false,
  types     : {
    bookmark: {
      schema             : 'https://example.com/schemas/bookmark',
      dataFormats        : ['application/json'],
      encryptionRequired : true,
    },
  },
  structure: {
    bookmark: {
      $tags: { category: { type: 'string' } },
    },
  },
} as const, {} as {
  bookmark: { url: string; title: string; note?: string };
});

const bookmarks = enbox.using(BookmarkProtocol);

const { record } = await bookmarks.records.create('bookmark', {
  data : { url: 'https://example.com', title: 'Example' },
  tags : { category: 'reading' },
});

const { records } = await bookmarks.records.query('bookmark', {
  filter: { tags: { category: 'reading' } },
});

const { liveQuery } = await bookmarks.records.subscribe('bookmark');
liveQuery.on('create', async (created) => {
  console.log(await created.data.json());
});

console.log(session.did, record.id, records.length);

For browser apps, @enbox/browser re-exports the main app APIs and adds browser-specific connect helpers and DRL polyfills. For terminal tools, @enbox/cli provides the same app APIs with a relay/PIN connect handler that prints a QR code or opens the wallet approval link.

See packages/api/README.md and the public docs site for more examples.

Runtime Model

1. The app talks to an Enbox agent and local DWN.
2. The agent signs DWN messages with the active DID.
3. Sync pushes/pulls records to remote DWN servers over HTTP/WebSocket.
4. Other devices and authorized apps converge through the same remote DWN feed.

Encryption has two layers: the local vault protects identity material, and protocol types with encryptionRequired: true encrypt record data at the DWN layer using the tenant's key agreement key.

DWN Servers

Use the preview endpoints only for development:

Node	URL	Notes
Fly.io	https://enbox-dwn.fly.dev	SQLite-backed preview node
AWS	https://dev.aws.dwn.enbox.id	Aurora PostgreSQL preview node

Run your own node with @enbox/dwn-server:

git clone https://github.com/enboxorg/enbox.git
cd enbox
docker compose up dwn-server

See docs/HOSTING.md and packages/dwn-server/README.md for hosting configuration, storage backends, and registration options.

Packages

Package	Role
@enbox/api	High-level SDK: Enbox.connect(), typed protocols, records, subscriptions
@enbox/auth	Headless auth, local vault connect, wallet connect, session restore
@enbox/browser	Browser helpers and polyfills
@enbox/cli	CLI helpers and relay/PIN wallet connect handler
@enbox/protocols	Shared protocol definitions and JSON Schemas
@enbox/protocol-codegen	TypeScript generation from protocol definitions and schemas
@enbox/agent	Identity vault, key management, local DWN, sync engine
@enbox/dids	DID creation and resolution
@enbox/crypto	Crypto primitives, JWE, local key management
@enbox/common	Shared utilities and storage helpers
@enbox/dwn-sdk-js	Core DWN engine and message handlers
@enbox/dwn-clients	DWN HTTP/WebSocket clients and registration client
@enbox/dwn-server	Multi-tenant DWN server
@enbox/dwn-sql-store	SQL-backed DWN storage

@enbox/dwn-relay lives in a separate repository: https://github.com/enboxorg/dwn-relay.

Development

bun install
bun run build
bun run lint

Several test suites require Docker services and a local Pkarr relay:

docker compose -f docker-compose.test.yaml up -d --wait
export DID_DHT_GATEWAY_URI=http://localhost:7527
export DID_DHT_ALLOW_PRIVATE_GATEWAY=1
bun run test:node

See AGENTS.md for contributor workflow, style, release, and CI rules. See docs/TESTING.md for local service setup and the coverage pipeline.

Security

Do not open public issues for vulnerabilities. Email security@enboxorg.com with details.

License

Apache-2.0

Resources

• Documentation
• DWN Specification
• DID Core Specification

_{This monorepo consolidates packages from the decentralized-identity organization, including dwn-sdk-js, dwn-server, dwn-sql-store, and the web5-js monorepo.}