Decentralized Web Node (DWN) SDK

Research Preview — Enbox is under active development. APIs may change without notice.

A TypeScript implementation of Decentralized Web Nodes — module-driven personal datastores that users control.

Overview

This package is the core DWN engine used by the rest of the Enbox stack. It handles message processing, module authorization, record storage, and encryption. Most applications should use @enbox/api rather than this package directly.

Installation

bun add @enbox/dwn-sdk-js

Usage

import { Dwn, DataStream, Jws, RecordsWrite } from '@enbox/dwn-sdk-js';
import { DataStoreLevel, MessageStoreLevel, ResumableTaskStoreLevel } from '@enbox/dwn-sdk-js/stores/level';

const messageStore = new MessageStoreLevel();
const dataStore = new DataStoreLevel();
const resumableTaskStore = new ResumableTaskStoreLevel();
const dwn = await Dwn.create({ messageStore, dataStore, resumableTaskStore });

// Create and process a RecordsWrite message
const data = new TextEncoder().encode('Hello, World!');
const recordsWrite = await RecordsWrite.create({
  data,
  dataFormat  : 'application/json',
  published   : true,
  schema      : 'example/post',
  signer      : Jws.createSigner(persona),
});

const dataStream = DataStream.fromBytes(data);
const result = await dwn.processMessage(persona.did, recordsWrite.message, { dataStream });
console.log(result.status); // { code: 202, detail: 'Accepted' }

await dwn.close();

Level-backed store implementations are exported from @enbox/dwn-sdk-js/stores/level so applications that only need message and module APIs do not load the Level store module graph by default. Shared blockstore helpers used by alternative store implementations are available from @enbox/dwn-sdk-js/stores/blockstore.

Context role preference

resolveModuleContextRoles(graph, contextPath) returns the root's direct-child role paths granting read, in $actions array order. That order declares client following preference for this exact root; object property order does not affect it. It does not change DWN authorization, imply role inheritance, or modify role assignments. The high-level shared-context API derives its role candidates from this same resolved module graph.

See context role preference for the definition convention and a notebook example with editor and viewer roles.

Custom Tenant Gating

By default all DIDs are allowed as tenants. Provide a custom TenantGate to restrict access:

import { ActiveTenantCheckResult, Dwn, TenantGate } from '@enbox/dwn-sdk-js';

class CustomTenantGate implements TenantGate {
  public async isActiveTenant(did: string): Promise<ActiveTenantCheckResult> {
    // custom logic
  }
}

const dwn = await Dwn.create({ messageStore, dataStore, resumableTaskStore, tenantGate: new CustomTenantGate() });

Custom Signer

Use PrivateKeySigner if you have a key available, or implement the Signer interface to integrate with an external signing service, HSM, etc.:

import type { Signer } from '@enbox/dwn-sdk-js';

class CustomSigner implements Signer {
  public keyId = 'did:example:alice#key1';
  public algorithm = 'EdDSA';
  public async sign(content: Uint8Array): Promise<Uint8Array> {
    // custom signing logic
  }
}

Architecture

The diagram is a conceptual view; actual component names in source may differ.

Development

# Build
bun run build

# Test
bun run test:node

# Test with grep filter (from this package directory)
GREP="ModulesConfigure" bun run test:node-grep

# Lint
bun run lint

License

Apache-2.0