@enbox/dwn-sdk-js 0.0.2 → 0.0.4

package/README.md

@@ -1,352 +1,103 @@
-<!-- @format -->
-# Decentralized Web Node (DWN) SDK <!-- omit in toc -->
+# Decentralized Web Node (DWN) SDK
 
-[![NPM](https://img.shields.io/npm/v/@enbox/dwn-sdk-js.svg?logo=npm)](https://www.npmjs.com/package/@enbox/dwn-sdk-js)
-[![codecov](https://codecov.io/github/enboxorg/enbox/dwn-sdk-js/graphs/badge.svg)](https://codecov.io/github/enboxorg/enbox/dwn-sdk-js)
-[![Build Status](https://img.shields.io/github/actions/workflow/status/enboxorg/enbox/dwn-sdk-js/npm-publish-unstable.yml?branch=main&logo=github)](https://github.com/enboxorg/enbox/dwn-sdk-js/actions/workflows/npm-publish-unstable.yml)
-[![License](https://img.shields.io/npm/l/@enbox/dwn-sdk-js.svg?logo=apache)](https://github.com/enboxorg/enbox/dwn-sdk-js/blob/main/LICENSE)
-[![Chat](https://img.shields.io/badge/chat-on%20discord-7289da.svg?logo=discord)](https://discord.com/channels/937858703112155166/1068273971432280196)
+> **Research Preview** — Enbox is under active development. APIs may change without notice.
 
+[![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/LiranCohen/02d15f39a46173a612a8862ec6d7cfcf/raw/dwn-sdk-js.json)](https://github.com/enboxorg/enbox/actions/workflows/ci.yml)
 
-- [Introduction](#introduction)
-- [Installation](#installation)
-- [Additional Steps](#additional-steps)
-  - [Node.js \<= 18](#nodejs--18)
-  - [React Native](#react-native)
-  - [Usage in Browser:](#usage-in-browser)
-    - [Vanilla HTML / JS](#vanilla-html--js)
-    - [Webpack \>= 5](#webpack--5)
-    - [Vite](#vite)
-    - [esbuild](#esbuild)
-- [Usage](#usage)
-- [Release/Build Process](#releasebuild-process)
-  - [Stable Build](#stable-build)
-  - [Unstable Build](#unstable-build)
-- [Some projects that use this library:](#some-projects-that-use-this-library)
-- [Architecture](#architecture)
-- [Project Resources](#project-resources)
+A TypeScript implementation of [Decentralized Web Nodes](https://identity.foundation/decentralized-web-node/spec/) — protocol-driven personal datastores that users control.
 
-## 🎉 Hacktoberfest 2024 🎉
+## Overview
 
-`dwn-sdk-js` is a participating project in Hacktoberfest 2024! We’re so excited for your contributions, and have created a wide variety of issues so that anyone can contribute. Whether you're a seasoned developer or a first-time open source contributor, there's something for everyone.
-
-### To get started:
-1. Read the [contributing guide](https://github.com/enboxorg/enbox/dwn-sdk-js/blob/main/CONTRIBUTING.md).
-2. Read the [code of conduct](https://github.com/enboxorg/enbox/dwn-sdk-js/blob/main/CODE_OF_CONDUCT.md).
-3. Choose a task from this project's Hacktoberfest issues in our [Project Hub](https://github.com/enboxorg/enbox/dwn-sdk-js/issues/806) and follow the instructions. Each issue has the 🏷️ `hacktoberfest` label.
-
-Have questions? Connecting with us in our [Discord community](https://discord.gg/tbd) in the `#hacktoberfest` project channel.
-
----
-
-## Introduction
-
-This repository contains a reference implementation of Decentralized Web Node (DWN) as per the [specification](https://identity.foundation/decentralized-web-node/spec/). This specification is in a draft state and very much so a WIP. For the foreseeable future, a lot of the work on DWN will be split across this repo and the [repo that houses the specification](https://github.com/decentralized-identity/decentralized-web-node). The current implementation does not include all interfaces described in the DWN spec, but is enough to begin building test applications.
-
-This project is used as a dependency by several other projects.
-
-Proposals and issues for the specification itself should be submitted as pull requests to the [spec repo](https://github.com/decentralized-identity/decentralized-web-node).
-
-## Running online environment
-
-Interested in contributing instantly? You can make your updates directly without cloning in the running CodeSandbox environment.
-
-[![Button to click to edit code in CodeSandbox](https://assets.codesandbox.io/github/button-edit-lime.svg)](https://codesandbox.io/p/github/enboxorg/enbox/dwn-sdk-js/main)
+This package is the core DWN engine used by the rest of the Enbox stack. It handles message processing, protocol authorization, record storage, and encryption. Most applications should use [`@enbox/api`](../api/) rather than this package directly.
 
 ## Installation
 
-If you are interested in using DWNs and web5 in your web app, you probably want to look at enbox, instead of this repository. Head on over here: https://github.com/enboxorg/enbox/enbox.
-
-For advanced users wishing to use this repo directly:
-
 ```bash
-npm install @enbox/dwn-sdk-js
-```
-
-## Additional Steps
-
-This package has dependency on [`@noble/ed25519`](https://github.com/paulmillr/noble-ed25519#usage) and [`@noble/secp256k1`](https://github.com/paulmillr/noble-secp256k1#usage) v2, additional steps are needed for some environments:
-
-### Node.js <= 18
-
-```js
-// node.js 18 and earlier,  needs globalThis.crypto polyfill
-import { webcrypto } from "node:crypto";
-// @ts-ignore
-if (!globalThis.crypto) globalThis.crypto = webcrypto;
-```
-
-### React Native
-Usage of DWN SDK in react native requires a bit of set up at the moment. To simplify, we've [published an npm package](https://www.npmjs.com/package/@enbox/web5-react-native-polyfills) that can be used to set everything up. Follow the instructions to get started.
-
-### Usage in Browser:
-
-`dwn-sdk-js` requires 2 polyfills: `crypto` and `stream`. we recommend using `crypto-browserify` and `stream-browserify`. Both of these polyfills can be installed using npm. e.g. `npm install --save crypto-browserify stream-browserify`
-
-#### Vanilla HTML / JS
-
-DWN SDK includes a polyfilled distribution that can imported in a `module` script tag. e.g.
-
-```html
-<!DOCTYPE html>
-<html lang="en">
-<body>
-  <script type="module">
-     // Import necessary modules from external sources using ES6 modules.
-    import { Dwn, DataStream, DidKeyResolver, Jws, RecordsWrite } from 'https://cdn.jsdelivr.net/npm/@enbox/dwn-sdk-js@0.1.1/dist/bundles/dwn.js'
-    import { MessageStoreLevel, DataStoreLevel, EventLogLevel } from 'https://cdn.jsdelivr.net/npm/@enbox/dwn-sdk-js@0.1.1/dist/bundles/level-stores.js'
-
-    // Create instances of various components from the imported modules.
-    const messageStore = new MessageStoreLevel();
-    const dataStore = new DataStoreLevel();
-    const eventLog = new EventLogLevel();
-    const dwn = await Dwn.create({ messageStore, dataStore, eventLog });
-
-    // Generate a did:key DID (Decentralized Identifier).
-    const didKey = await TestDataGenerator.generateDidKeyPersona();
-
-    // Create some data to be stored.
-    const encoder = new TextEncoder();
-    const data = encoder.encode('Hello, World!');
-
-    // Create a RecordsWrite message to be stored in DWN.
-    const recordsWrite = await RecordsWrite.create({
-      data,
-      dataFormat: 'application/json',
-      published: true,
-      schema: 'yeeter/post',  // Specify a schema for the data.
-      signer: Jws.createSigner(didKey) // Sign the data using the generated DID key.
-    });
-
-    // Create a readable stream from the data to be stored.
-    const dataStream = DataStream.fromBytes(data);
-    // Process the RecordsWrite message using the DWN instance.
-    const result = await dwn.processMessage(didKey.did, recordsWrite.message, { dataStream });
-
-    // Log the processing result status and perform an assertion.
-    console.log(result.status);
-    console.assert(result.status.code === 202)
-
-    // Close the DWN instance, freeing up resources.
-    await dwn.close()
-
-  </script>
-</body>
-
-</html>
-```
-
-#### Webpack >= 5
-
-Add the following to the top level of your webpack config (`webpack.config.js`)
-
-```js
-resolve: {
-  fallback: {
-    stream: require.resolve("stream-browserify"),
-    crypto: require.resolve("crypto-browserify")
-  }
-}
-```
-
-#### Vite
-Add the following to the top level of your vite config (`vite.config.js`)
-
-```js
-define: {
-  global: 'globalThis'
-},
-resolve: {
-  alias: {
-    'crypto': 'crypto-browserify',
-    'stream': 'stream-browserify'
-  }
-}
-```
-
-#### esbuild
-We recommend using `node-stdlib-browser` instead of `crypto-browserify` and `stream-browserify` individually. Example usage:
-
-```js
-import esbuild from 'esbuild'
-import stdLibBrowser from 'node-stdlib-browser'
-import polyfillProviderPlugin from 'node-stdlib-browser/helpers/esbuild/plugin'
-
-import { createRequire } from 'node:module';
-
-const require = createRequire(import.meta.url);
-
-// Build the project using esbuild.
-esbuild.build({
-  entryPoints: ['dwn-sdk-test.js'],
-  platform: 'browser',
-  bundle: true,
-  format: 'esm',
-  outfile: 'dist/dwn-sdk-test.js',
-
-  // Inject the specified shim for Node.js standard library browser compatibility.
-  inject      : [require.resolve('node-stdlib-browser/helpers/esbuild/shim')],
-  // Use the polyfillProviderPlugin to provide polyfills for Node.js standard library.
-  plugins     : [polyfillProviderPlugin(stdLibBrowser)],
-  // Define 'global' as 'globalThis' to ensure compatibility with global objects.
-  define      : {
-    'global': 'globalThis'
-  }
-})
+bun add @enbox/dwn-sdk-js
 ```
 
 ## Usage
 
-[API docs](https://enboxorg/enbox.github.io/dwn-sdk-js/)
-
 ```ts
+import { Dwn, DataStream, Jws, RecordsWrite } from '@enbox/dwn-sdk-js';
+import { DataStoreLevel, MessageStoreLevel, StateIndexLevel } from '@enbox/dwn-sdk-js';
 
-import { Dwn, DataStream, DidKeyResolver, Jws, RecordsWrite } from '@enbox/dwn-sdk-js';
-import { DataStoreLevel, EventLogLevel, MessageStoreLevel } from '@enbox/dwn-sdk-js/stores';
-
-// Initialize the required stores and components for the DWN SDK.
 const messageStore = new MessageStoreLevel();
 const dataStore = new DataStoreLevel();
-const eventLog = new EventLogLevel();
-const dwn = await Dwn.create({ messageStore, dataStore, eventLog });
+const stateIndex = new StateIndexLevel();
+const dwn = await Dwn.create({ messageStore, dataStore, stateIndex });
 
-// Generate a did:key DID (Decentralized Identifier).
-const didKey = await TestDataGenerator.generateDidKeyPersona();
-
-// Create some data to be stored.
-const encoder = new TextEncoder();
-const data = encoder.encode('Hello, World!');
-
-// Create a RecordsWrite message to be stored in the DWN.
+// Create and process a RecordsWrite message
+const data = new TextEncoder().encode('Hello, World!');
 const recordsWrite = await RecordsWrite.create({
   data,
-  dataFormat: 'application/json',
-  published: true, // Mark the data as published.
-  schema: 'yeeter/post', // Specify a schema for the data.
-  signer: Jws.createSigner(didKey) // Sign the data using the generated DID key.
+  dataFormat  : 'application/json',
+  published   : true,
+  schema      : 'example/post',
+  signer      : Jws.createSigner(persona),
 });
 
-// Create a readable stream from the data to be stored.
 const dataStream = DataStream.fromBytes(data);
-// Process the RecordsWrite message using the DWN instance.
-const result = await dwn.processMessage(didKey.did, recordsWrite.message, { dataStream });
-// Log the processing result status.
-console.log(result.status);
+const result = await dwn.processMessage(persona.did, recordsWrite.message, { dataStream });
+console.log(result.status); // { code: 202, detail: 'Accepted' }
 
-```
-
-With a web wallet installed:
-
-```javascript
-const result = await window.web5.dwn.processMessage({
-  method: "RecordsQuery",
-  message: {
-    filter: {
-      schema: "http://some-schema-registry.org/todo",
-    },
-    dateSort: "createdAscending",
-  },
-});
+await dwn.close();
 ```
 
 ### Custom Tenant Gating
-By default, all DIDs are allowed as tenants. A custom tenant gate implementation can be provided when initializing the DWN.
+
+By default all DIDs are allowed as tenants. Provide a custom `TenantGate` to restrict access:
+
 ```ts
-import { ActiveTenantCheckResult, Dwn, TenantGate, DataStoreLevel, EventLogLevel, MessageStoreLevel } from '@enbox/dwn-sdk-js';
+import { ActiveTenantCheckResult, Dwn, TenantGate } from '@enbox/dwn-sdk-js';
 
-// Define a custom implementation of the TenantGate interface.
 class CustomTenantGate implements TenantGate {
-  public async isActiveTenant(did): Promise<ActiveTenantCheckResult> {
-    // Custom implementation
+  public async isActiveTenant(did: string): Promise<ActiveTenantCheckResult> {
+    // custom logic
   }
 }
 
-// Initialize the required stores and components for the DWN SDK.
-const messageStore = new MessageStoreLevel();
-const dataStore = new DataStoreLevel();
-const eventLog = new EventLogLevel();
-// Create an instance of the custom TenantGate.
-const tenantGate = new CustomTenantGate();
-// Create a DWN instance with configured stores, logs, and the custom TenantGate.
-const dwn = await Dwn.create({ messageStore, dataStore, eventLog, tenantGate });
+const dwn = await Dwn.create({ messageStore, dataStore, stateIndex, tenantGate: new CustomTenantGate() });
 ```
 
-### Custom Signature Signer
-If you have the private key readily available, it is recommended to use the built-in `PrivateKeySigner`. Otherwise, you can implement a customer signer to interface with external signing service, API, HSM, TPM etc and use it for signing your DWN messages:
+### Custom Signer
+
+Use `PrivateKeySigner` if you have a key available, or implement the `Signer` interface to integrate with an external signing service, HSM, etc.:
 
 ```ts
-// Create a custom signer implementing the Signer interface.
+import type { Signer } from '@enbox/dwn-sdk-js';
+
 class CustomSigner implements Signer {
-  public keyId = 'did:example:alice#key1'; // Specify the key ID.
-  public algorithm = 'EdDSA'; // Specify the signing algorithm (valid `alg` value published).
-  https://www.iana.org/assignments/jose/jose.xhtml
-  public async sign (content: Uint8Array): Promise<Uint8Array> {
-    ... // custom signing logic
+  public keyId = 'did:example:alice#key1';
+  public algorithm = 'EdDSA';
+  public async sign(content: Uint8Array): Promise<Uint8Array> {
+    // custom signing logic
   }
 }
-
-// Create an instance of the custom signer for authorization.
-const signer = new CustomSigner();
-
-// Define options for creating a RecordsWrite message.
-const options: RecordsWriteOptions = {
-  ...
-  signer // Use the custom signer for authorization.
-};
-
-// Create a RecordsWrite message with the specified options.
-const recordsWrite = await RecordsWrite.create(options);
 ```
 
+## Architecture
 
-## Release/Build Process
-
-The DWN JS SDK releases builds to [npmjs.com](https://www.npmjs.com/package/@enbox/dwn-sdk-js). There are two build types: stable build and unstable build.
-
-### Stable Build
-
-This is triggered manually by:
-
-1.  Increment `version` in `package.json` in [Semantic Versioning (semver)](https://semver.org/) format.
-2.  Merge the change into `main` branch
-3.  Create a release from GitHub.
-
-An official build with version matching the `package.json` will be published to [npmjs.com](https://www.npmjs.com/package/@enbox/dwn-sdk-js).
-
-### Unstable Build
-
-Every push to the `main` branch will automatically trigger an unstable build to [npmjs.com](https://www.npmjs.com/package/@enbox/dwn-sdk-js) for developers to experiment and test.
-
-The version string contains the date as well as the commit hash of the last change.
-
-An example version string:
-
-`0.0.26-unstable-2023-03-16-36ec2ce`
+<img src="./images/dwn-architecture.png" alt="DWN architecture diagram" width="700">
 
-- `0.0.26` came from `version` in `package.json`
-- `2023-03-16` indicates the date of March 16th 2023
-- `36ec2ce` is the commit hash of the last change
+> The diagram is a conceptual view; actual component names in source may differ.
 
-## Some projects that use this library:
+## Development
 
-- [Web5 JS SDK](https://github.com/enboxorg/enbox/enbox)
-- [Example CLI](https://github.com/enboxorg/enbox/dwn-cli)
-- [Example with a web wallet](https://github.com/enboxorg/enbox/incubating-web5-labs/)
-- [Server side aggregator](https://github.com/enboxorg/enbox/dwn-server)
+```bash
+# Build
+bun run build
 
-## Architecture
+# Test
+bun run test:node
 
-<img src="./images/dwn-architecture.png" alt="Architecture diagram of DWN SDN" width="700">
+# Test with grep filter (from this package directory)
+GREP="ProtocolsConfigure" bun run test:node-grep
 
-> NOTE: The diagram is a conceptual view of the architecture, the actual component abstraction and names in source file may differ.
+# Lint
+bun run lint
+```
 
-## Project Resources
+## License
 
-| Resource                                                                                     | Description                                                                   |
-| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| [CODEOWNERS](https://github.com/enboxorg/enbox/dwn-sdk-js/blob/main/CODEOWNERS)                 | Outlines the project lead(s)                                                  |
-| [CODE_OF_CONDUCT.md](https://github.com/enboxorg/enbox/dwn-sdk-js/blob/main/CODE_OF_CONDUCT.md) | Expected behavior for project contributors, promoting a welcoming environment |
-| [CONTRIBUTING.md](https://github.com/enboxorg/enbox/dwn-sdk-js/blob/main/CONTRIBUTING.md)       | Developer guide to build, test, run, access CI, chat, discuss, file issues    |
-| [GOVERNANCE.md](https://github.com/enboxorg/enbox/dwn-sdk-js/blob/main/GOVERNANCE.md)           | Project governance                                                            |
-| [LICENSE](https://github.com/enboxorg/enbox/dwn-sdk-js/blob/main/LICENSE)                       | Apache License, Version 2.0                                                   |
-| [Q_AND_A.md](https://github.com/enboxorg/enbox/dwn-sdk-js/blob/main/Q_AND_A.md)                 | Questions and answers on DWN                                                  |
+Apache-2.0