@enbox/dwn-server 0.0.3 → 0.0.5

package/LICENSE

@@ -1,3 +1,4 @@
+
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
@@ -186,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2025 Liran Cohen
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
@@ -198,4 +199,4 @@
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
-   limitations under the License.
+   limitations under the License.

package/README.md

@@ -1,118 +1,92 @@
 # DWN Server
 
-Exposes a multi-tenanted DWN (aka Decentralized Web Node) through a JSON-RPC API over `http:` and `ws:`
+> **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-server.json)](https://github.com/enboxorg/enbox/actions/workflows/ci.yml)
+
+A multi-tenant Decentralized Web Node exposed via JSON-RPC over HTTP and WebSocket, powered by `Bun.serve()`.
 
 - [Supported DBs](#supported-dbs)
 - [Installation](#installation)
-- [Package usage](#package-usage)
-- [Running The Server](#running-the-server)
+- [Running the Server](#running-the-server)
 - [JSON-RPC API](#json-rpc-api)
-  - [Available Methods](#available-methods)
-    - [`dwn.processMessage`](#dwnprocessmessage)
-      - [Params](#params)
-      - [Example Request Message](#example-request-message)
-      - [Example Success Response](#example-success-response)
-      - [Example Error Response](#example-error-response)
-      - [Transporting large amounts of data](#transporting-large-amounts-of-data)
-      - [Receiving large amounts of data](#receiving-large-amounts-of-data)
-- [npm scripts](#npm-scripts)
 - [Configuration](#configuration)
-  - [Storage Options](#storage-options)
+- [Hosting Your Own DWN Server](#hosting-your-own-dwn-server)
+- [Registration Requirements](#registration-requirements)
 
 ## Supported DBs
 
-- LevelDB :heavy_check_mark:
-- SQLite :heavy_check_mark:
-- MySQL :heavy_check_mark:
-- PostgreSQL :heavy_check_mark:
-
-See more in [Storage Options](#storage-options)
-
-## Running online environment
+- LevelDB
+- SQLite
+- MySQL
+- PostgreSQL
 
-Interested in contributing instantly? You can make your updates directly without cloning in the running CodeSandbox environment.
-
-[![Button to click and edit the code in CodeSandbox](https://assets.codesandbox.io/github/button-edit-lime.svg)](https://codesandbox.io/p/github/enboxorg/enbox/main)
+See [Storage Options](#storage-options) for details.
 
 ## Installation
 
 ```bash
-npm install @enbox/dwn-server
+bun add @enbox/dwn-server
 ```
 
-## Package usage
+## Package Usage
 
 ```typescript
 import { DwnServer } from '@enbox/dwn-server';
 
 const server = new DwnServer();
-
 server.start();
 ```
 
-## Running the server
+## Running the Server
 
-### Running via docker
+### Via Docker
 
-`docker run -p 3000:3000 -v myvolume:/dwn-server/data ghcr.io/enboxorg/dwn-server:main`
-
-This can run on services like AWS, GCP, VPS, home server (with ngrok or cloudflare), fly.io, render.com etc.
-Ideally the volume is persistent so that data is kept (or has to be synced back from another DWN instance).
+```bash
+docker run -p 3000:3000 -v myvolume:/dwn-server/data ghcr.io/enboxorg/dwn-server:main
+```
 
-### Running a specific version
+This can run on AWS, GCP, VPS, home server (with ngrok or Cloudflare tunnel), Fly.io, Render, etc. Use a persistent volume so data is kept (or synced back from another DWN instance).
 
-Running the command above will run the latest version at the time the image is pulled. If you need to run a specific version (and in many cases this is recommended) [you can see the list published images here](https://github.com/enboxorg/enbox/pkgs/container/dwn-server/versions)
+To run a specific version, [see published images](https://github.com/enboxorg/enbox/pkgs/container/dwn-server/versions):
 
-To run a specific image:
-`docker pull ghcr.io/enboxorg/dwn-server@sha256:870e0f0f12016e6607060a81ea31458443f7439522fab2688d7a6706ab366c58`
+```bash
+docker pull ghcr.io/enboxorg/dwn-server@sha256:<hash>
+```
 
-### Running Locally for Development
+### Locally for Development
 
 ```bash
 git clone https://github.com/enboxorg/enbox.git
-cd enbox/packages/dwn-server
-npm install
-npm run server
+cd enbox
+bun install
+bun run --filter @enbox/dwn-server build
+bun run --filter @enbox/dwn-server server
 ```
 
-### Building a docker image locally
+### Building a Docker Image Locally
 
-A docker image is continuously published from this repository, but if you want to build it locally run:
-`docker build -t dwn-server .`
+```bash
+docker build -t dwn-server .
+```
 
 ## JSON-RPC API
 
-[JSON-RPC](https://www.jsonrpc.org/specification) is a lightweight remote procedure call (RPC) protocol that uses JSON as a data format for exchanging information between a client and a server over a network. JSON-RPC is language-independent and transport-agnostic which makes it usable in a variety of contexts (e.g. browser, server-side)
-
-With JSON-RPC, a client sends a request message to a server over a network, and the server responds with a response message.
+[JSON-RPC](https://www.jsonrpc.org/specification) is a lightweight RPC protocol using JSON, language-independent and transport-agnostic.
 
-The request message consists of:
-
-- a method name (`method`)
-- a set of parameters (`params`)
-- an identifier (`id`).
-
-The response message contains:
-
-- the same identifier that was sent with the request message (`id`)
-- the result of the method invocation (`result`)
-- an error message if the method invocation failed (`error`)
-
-### Available Methods
-
-#### `dwn.processMessage`
+### `dwn.processMessage`
 
 Used to send DWeb Messages to the server.
 
-##### Params
+#### Params
 
-| Property      | Required (Y/N) | Description                                                               |
-| ------------- | -------------- | ------------------------------------------------------------------------- |
-| `target`      | Y              | The DID that the message is intended for                                  |
-| `message`     | Y              | The DWeb Message                                                          |
-| `encodedData` | N              | Data associated to the message (e.g. data associated to a `RecordsWrite`) |
+| Property      | Required | Description                                                               |
+| ------------- | -------- | ------------------------------------------------------------------------- |
+| `target`      | Y        | The DID that the message is intended for                                  |
+| `message`     | Y        | The DWeb Message                                                          |
+| `encodedData` | N        | Data associated to the message (e.g. data associated to a `RecordsWrite`) |
 
-##### Example Request Message
+#### Example Request
 
 ```json
 {
@@ -131,15 +105,7 @@ Used to send DWeb Messages to the server.
         "dateModified": "2023-04-30T22:49:37.713976Z",
         "dataFormat": "application/json"
       },
-      "authorization": {
-        "payload": "eyJyZWNvcmRJZCI6ImJhZnlyZWlkdGl4Nmdoam1zYmc3ZWl0ZXhzbXd6dmp4YzdhZWxhZ3NxYXN5Ym1xbDd6cm1zMzRqdTZpIiwiZGVzY3JpcHRvckNpZCI6ImJhZnlyZWlheTVwNWZ1bzJhc2hqZXRvbzR1M3p1b282dW02cGlzNHl5NnUzaHE1emxsdmZhN2ZubXY0In0",
-        "signatures": [
-          {
-            "protected": "eyJhbGciOiJFZERTQSIsImtpZCI6ImRpZDprZXk6ejZNa3UxaDRMZGtoWFczSG5uQktBTnhnVWFRMTYyY3ZXbVJ1emNiZDJZZThWc3RaI2RpZDprZXk6ejZNa3UxaDRMZGtoWFczSG5uQktBTnhnVWFRMTYyY3ZXbVJ1emNiZDJZZThWc3RaI3o2TWt1MWg0TGRraFhXM0hubkJLQU54Z1VhUTE2MmN2V21SdXpjYmQyWWU4VnN0WiJ9",
-            "signature": "cy_RtWjjVK2mmKkI_35qiv54_1Pp_f7SjAx0z75PBL4th-fgfjuLZmF-V3czCWwFYMMnN0W4zl3LJ2jEf_t9DQ"
-          }
-        ]
-      }
+      "authorization": { "..." : "..." }
     },
     "target": "did:key:z6Mku1h4LdkhXW3HnnBKANxgUaQ162cvWmRuzcbd2Ye8VstZ",
     "encodedData": "ub3-FwUsSs4GgZWqt5eXSH41RKlwCx41y3dgio9Di74"
@@ -147,7 +113,7 @@ Used to send DWeb Messages to the server.
 }
 ```
 
-##### Example Success Response
+#### Example Success Response
 
 ```json
 {
@@ -155,16 +121,13 @@ Used to send DWeb Messages to the server.
   "id": "18eb421f-4750-4e31-a062-412b71139546",
   "result": {
     "reply": {
-      "status": {
-        "code": 202,
-        "detail": "Accepted"
-      }
+      "status": { "code": 202, "detail": "Accepted" }
     }
   }
 }
 ```
 
-##### Example Error Response
+#### Example Error Response
 
 ```json
 {
@@ -177,166 +140,92 @@ Used to send DWeb Messages to the server.
 }
 ```
 
-##### Transporting large amounts of data
-
-`RecordsWrite` data can be of any size. If needed, large amounts of data can be streamed to the server over http by:
-
-- including the JSON-RPC request message in a `dwn-request` request header
-- setting the `content-type` request header to `application/octet-stream`
-- sending binary data in the request body.
-
-> :bulb: Examples can be found in the [`examples`](./examples) directory.
+#### Transporting Large Data
 
-##### Receiving large amounts of data
+`RecordsWrite` data can be of any size. Large data can be streamed over HTTP by:
 
-`RecordsWrite` data can be of any size. `RecordsWrite` messages returned as the result of a `RecordsQuery` will include `encodedData` _if_ the `RecordsWrite` data is under `9.77KB`. Data larger than this will need to be fetched using `RecordsRead` which can be done over http. The response to a `RecordsRead` includes:
+- Including the JSON-RPC request message in a `dwn-request` request header
+- Setting `content-type` to `application/octet-stream`
+- Sending binary data in the request body
 
-- The JSON-RPC response message in a `dwn-response` header
-- The associated data as binary in the response body.
+#### Receiving Large Data
 
-Examples can be found in the `examples` directory.
+`RecordsWrite` messages returned from a `RecordsQuery` include `encodedData` only if the data is under ~9.77KB. Larger data must be fetched via `RecordsRead` over HTTP, which returns:
 
-> :bulb: **TODO**: Add examples in `examples` directory
+- The JSON-RPC response in a `dwn-response` header
+- The binary data in the response body
 
-## Hosting your own DWN-server
-
-By default, when you call `Enbox.connect()` there will be some bootstrap DWN nodes included which allow people to reach you via your DID.
+## Configuration
 
-You may want to run a DWN server just for you, or as a public service for you and your friends and family.
-DWNs can be as simple as a docker image or a node process running somewhere.
+All configuration is via environment variables:
 
-DWN-servers can run anywhere you can run node.js or docker. http and websocket need to be available to the DWN server.
-See below for some suggestions.
+| Env Var                                           | Description                                                                                                                    | Default                |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------- |
+| `DS_PORT`                                         | Port the server listens on                                                                                                     | `3000`                 |
+| `DS_MAX_RECORD_DATA_SIZE`                         | Maximum size for `RecordsWrite` data (`b`, `kb`, `mb`, `gb`)                                                                   | `1gb`                  |
+| `DS_WEBSOCKET_SERVER`                             | Enable WebSocket listener: `on` / `off`                                                                                        | `on`                   |
+| `DWN_BASE_URL`                                    | Base external URL of this DWN                                                                                                  | `http://localhost`     |
+| `DWN_STORAGE`                                     | Default storage URL. See [Storage Options](#storage-options)                                                                   | `level://data`         |
+| `DWN_STORAGE_MESSAGES`                            | Message store URL (overrides `DWN_STORAGE`)                                                                                    | value of `DWN_STORAGE` |
+| `DWN_STORAGE_DATA`                                | Data store URL (overrides `DWN_STORAGE`)                                                                                       | value of `DWN_STORAGE` |
+| `DWN_STORAGE_RESUMABLE_TASKS`                     | Resumable task store URL                                                                                                       | value of `DWN_STORAGE` |
+| `DWN_STORAGE_STATE_INDEX`                         | State index store URL                                                                                                          | value of `DWN_STORAGE` |
+| `DWN_EVENT_STREAM_PLUGIN_PATH`                    | Path to custom Event Stream plugin                                                                                             | unset                  |
+| `DWN_REGISTRATION_STORE_URL`                      | URL for registered DID storage. Unset = open for all                                                                           | unset                  |
+| `DWN_REGISTRATION_PROOF_OF_WORK_ENABLED`          | Require proof-of-work for registration                                                                                         | `false`                |
+| `DWN_REGISTRATION_PROOF_OF_WORK_SEED`             | Seed for challenge nonce (cluster consistency)                                                                                  | unset                  |
+| `DWN_REGISTRATION_PROOF_OF_WORK_INITIAL_MAX_HASH` | Initial max hash (64 char hex). More leading zeros = higher difficulty                                                          | `000000FF...`          |
+| `DWN_TERMS_OF_SERVICE_FILE_PATH`                  | Path to terms of service file. Unset = no ToS requirement                                                                      | unset                  |
+| `DWN_TTL_CACHE_URL`                               | TTL cache URL (SQL databases only)                                                                                             | `sqlite://`            |
 
-### Running on render.com
+### Storage Options
 
-You can run an instance on the render.com service:
+| Database   | Example                                               | Notes                                                                            |
+| ---------- | ----------------------------------------------------- | -------------------------------------------------------------------------------- |
+| LevelDB    | `level://data`                                        | Two slashes for relative paths, three for absolute                               |
+| SQLite     | `sqlite://dwn.db`                                     | Two slashes for relative paths, three for absolute                               |
+| MySQL      | `mysql://user:pass@host/db?debug=true&timezone=-0700` | [Options](https://github.com/mysqljs/mysql#connection-options)                   |
+| PostgreSQL | `postgres:///dwn`                                     | Also supports [standard env vars](https://node-postgres.com/features/connecting) |
 
-- Create a render.com account
-- Fork this repo
-- Upgrade your render.com account to a paid account
-- Create a new "Web service" type application
-- Choose the forked repo to run (or you can point to the main repo)
-- Choose the "starter" size instance
-- Create a 1GB (or larger) disk, and mount it on /dwn-server/data
+### Plugins
 
-### Running with ngrok
+Custom implementations of `DataStore`, `MessageStore`, `ResumableDataStore`, `StateIndex`, or `EventStream` can be loaded by pointing the corresponding env var to the absolute path of a `.js` file. The file must default-export a class with a no-arg constructor.
 
-You can run a DWN-server on your local machine or home server and expose it to the internet using ngrok.
+## Hosting Your Own DWN Server
 
-First, install [ngrok](https://ngrok.com/download)
+By default, `Enbox.connect()` uses bootstrap DWN nodes. You can run your own for yourself or your community. DWNs can run anywhere you can run Bun or Docker — HTTP and WebSocket must be reachable.
 
-Then run:
+### With ngrok
 
 ```bash
 docker run -p 3000:3000 -v myvolume:/dwn-server/data ghcr.io/enboxorg/dwn-server:main
 
-## in another terminal:
+# In another terminal:
 ngrok http 3000
 ```
 
-Note the resulting publicly addressable https url for your DWN instance.
-
-### Running with cloudflared
-
-Cloudflare has a tunnel service that you can use to expose your DWN server to the internet, if you run it on a server at home.
-With [cloudflared](https://github.com/cloudflare/cloudflared) installed, run the following commands:
+### With Cloudflare Tunnel
 
 ```bash
-git clone https://github.com/enboxorg/enbox.git
-cd enbox/packages/dwn-server
-npm install
-npm run server
-
-## in another terminal:
-
+# Start the server, then:
 cloudflared tunnel --url http://localhost:3000
 ```
 
-### Running on GCP
-
-... check back soon ...
-(enterprising people I am sure can work it out)
-
-## `npm` scripts
-
-| Script                 | Description                                                        |
-| ---------------------- | ------------------------------------------------------------------ |
-| `npm run build:esm`    | compiles typescript into ESM JS                                    |
-| `npm run build:cjs`    | compiles typescript into CommonJS                                  |
-| `npm run build`        | compiles typescript into ESM JS & CommonJS                         |
-| `npm run clean`        | deletes compiled JS                                                |
-| `npm run lint`         | runs linter                                                        |
-| `npm run lint:fix`     | runs linter and fixes auto-fixable problems                        |
-| `npm run test`         | runs tests                                                         |
-| `npm run server`       | starts server                                                      |
-| `npm run prepare`      | prepares husky for pre-commit hooks (auto-runs with `npm install`) |
-
-## Configuration
-
-Configuration can be set using environment variables
-
-| Env Var                                           | Description                                                                                                                    | Default                |
-| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------- |
-| `DS_PORT`                                         | Port that the server listens on                                                                                                | `3000`                 |
-| `DS_MAX_RECORD_DATA_SIZE`                         | Maximum size for `RecordsWrite` data. use `b`, `kb`, `mb`, `gb` for value                                                      | `1gb`                  |
-| `DS_WEBSOCKET_SERVER`                             | Whether to enable listening over `ws:`. values: `on`,`off`                                                                     | `on`                   |
-| `DWN_BASE_URL`                                    | Base external URL of this DWN. Used to construct URL paths such as the `Request URI` for the Enbox Connect flow.              | `http://localhost`     |
-| `DWN_EVENT_STREAM_PLUGIN_PATH`                    | Path to DWN Event Stream plugin to use. Default single-node implementation will be used if left empty.                         | unset                  |
-| `DWN_REGISTRATION_STORE_URL`                      | URL to use for storage of registered DIDs. Leave unset to if DWN does not require registration (ie. open for all)              | unset                  |
-| `DWN_REGISTRATION_PROOF_OF_WORK_SEED`             | Optional seed to generate the challenge nonce from, this allows all DWN instances in a cluster to generate the same challenge. | unset                  |
-| `DWN_REGISTRATION_PROOF_OF_WORK_ENABLED`          | Require new users to complete a proof-of-work challenge                                                                        | `false`                |
-| `DWN_REGISTRATION_PROOF_OF_WORK_INITIAL_MAX_HASH` | Initial maximum allowed hash in 64 char HEX string. The more leading zeros (smaller number) the higher the difficulty.         | `000000FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF` |
-| `DWN_STORAGE`                                     | URL to use for storage by default. See [Storage Options](#storage-options) for details                                         | `level://data`         |
-| `DWN_STORAGE_MESSAGES`                            | Connection URL or file path to custom plugin to use for the message store.                                                     | value of `DWN_STORAGE` |
-| `DWN_STORAGE_DATA`                                | Connection URL or file path to custom plugin to use for the data store.                                                        | value of `DWN_STORAGE` |
-| `DWN_STORAGE_RESUMABLE_TASKS`                     | Connection URL or file path to custom plugin to use for the resumable task store.                                              | value of `DWN_STORAGE` |
-| `DWN_STORAGE_EVENTS`                              | Connection URL or file path to custom plugin to use for the event store.                                                       | value of `DWN_STORAGE` |
-| `DWN_TERMS_OF_SERVICE_FILE_PATH`                  | Required terms of service agreement if set. Value is path to the terms of service file.                                        | unset                  |
-| `DWN_TTL_CACHE_URL`                               | URL of the TTL cache used by the DWN. Currently only supports SQL databases.                                                   | `sqlite://`            |
-
-### Storage Options
+### On Render.com
 
-Several built storage options are supported, and may be configured with the `DWN_STORAGE_*` environment variables:
-
-| Database   | Example                                               | Notes                                                                                                                                                                                 |
-| ---------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| LevelDB    | `level://data`                                        | use three slashes for absolute paths, two for relative. Example shown uses directory `data` in the current working directory                                                          |
-| Sqlite     | `sqlite://dwn.db`                                     | use three slashes for absolute paths, two for relative. Example shown creates a file `dwn.db` in the current working directory                                                        |
-| MySQL      | `mysql://user:pass@host/db?debug=true&timezone=-0700` | [all URL options documented here](https://github.com/mysqljs/mysql#connection-options)                                                                                                |
-| PostgreSQL | `postgres:///dwn`                                     | any options other than the URL scheme (`postgres://`) may also be specified via [standard environment variables](https://node-postgres.com/features/connecting#environment-variables) |
-
-### Plugins
-
-In some scenarios, you may want to provide a custom implementation of a pluggable module for the DWN Server. The following interfaces defined in `dwn-sdk-js` package are supported:
-
-- `DataStore`
-- `MessageStore`
-- `ResumableDataStore`
-- `EventLog`
-- `EventStream`
-
-To load your custom plugin, specify the absolute path to the `.js` file of your custom implementation using the corresponding environment variable. For instance, use `DWN_STORAGE_DATA` for a custom DWN Data Store.
-
-Refer to the `tests/plugins/*.ts` files for examples of plugin implementations. In summary, you need to:
-
-- Implement the corresponding interface from the `dwn-sdk-js` package. For example, implement the `DataStore` interface for a DWN Data Store.
-- Ensure that the built `.js` file that will be referenced by the DWN Server config environment variable contains a class that:
-  1. Is a default export. This is how DWN Server locates the correct class for instantiation.
-  1. Has a public constructor that does not take any arguments. This is how DWN Server instantiates the plugin.
+Fork this repo, create a "Web service" on Render, point it at the fork, choose the starter size, and mount a 1GB+ disk at `/dwn-server/data`.
 
 ## Registration Requirements
 
-There are multiple optional registration gates, each of which can be enabled (all are disabled by default). Tenants (DIDs) must comply with whatever
-requirements are enabled before they are allowed to use the server. Tenants that have not completed the registration requirements will be met with a 401. Note that registration is tracked in a database, and only SQL-based databases are supported (LevelDB is not supported). Current registration
-requirements are available at the `/info` endpoint.
+Optional registration gates (all disabled by default). Tenants that haven't completed registration get a 401. Registration is tracked in a SQL database (LevelDB not supported). Current requirements are exposed at `/info`.
+
+- **Proof of Work** (`DWN_REGISTRATION_PROOF_OF_WORK_ENABLED=true`): GET `/registration/proof-of-work` for a challenge, compute a nonce where `sha256(challenge + nonce)` starts with the required number of zeros, POST it back. Challenges expire after 5 minutes.
 
-- **Proof of Work** (`DWN_REGISTRATION_PROOF_OF_WORK_ENABLED=true`) - new tenants must GET `/registration/proof-of-work` for a challenge, then generate a nonce that produces a string that has a sha256 hex sum starting with the specified (`complexity`) number of zeros (`0`) when added to the end of the challenge (`sha256(challenge + nonce)`). This nonce should be POSTed to `/registration/proof-of-work` with a JSON body including the `challenge`, the nonce in field `response` and `did`. Challenges expire after 5 minutes, and complexity will increase based on the number of successful proof-of-work registrations that have been completed within the last hour. This registration requirement is listed in `/info` as `proof-of-work-sha256-v0`.
-- **Terms of Service** (`DWN_TERMS_OF_SERVICE_FILE_PATH=/path/to/terms-of-service.txt`) - new tenants must GET `/registration/terms-of-service` to fetch the terms. These terms must be displayed to the human end-user, who must actively accept them. When the user accepts the terms, send the sha256 hash of the accepted terms and the user's did via POST `/registration/terms-of-service`. The JSON body should have fields `termsOfServiceHash` and `did`. To change the terms, update the file and restart the server. Users that accepted the old terms will be blocked until they accept the new terms. This registration requirement is listed in `/info` as `terms-of-service`.
+- **Terms of Service** (`DWN_TERMS_OF_SERVICE_FILE_PATH=/path/to/tos.txt`): GET `/registration/terms-of-service`, display to user, POST `{ termsOfServiceHash, did }` on acceptance. Changing the file invalidates old acceptances.
 
-## Server info
+## Server Info
 
-the server exposes information about itself via the `/info` endpoint, which returns data in the following format:
+The `/info` endpoint returns:
 
 ```json
 {
@@ -349,5 +238,16 @@ the server exposes information about itself via the `/info` endpoint, which retu
 }
 ```
 
-- `server` is read from the `process.env.npm_package_name` variable that `npm` provides. If that does not exist, it will check for a `DWN_SERVER_PACKAGE_NAME` environment variable set by the user, or otherwise it will default to `@enbox/dwn-server`.
-- `version` and `sdkVersion` are read from the `package.json` file. It will locate the file's path either from the `process.env.npm_package_json` variable that `npm` provides. If that does not exist, it will check for a `DWN_SERVER_PACKAGE_JSON` environment variable set by the user, or otherwise it will default to `/dwn-server/package.json` which is the path within the default Docker container build.
+## Development
+
+```bash
+bun run build        # compile TypeScript
+bun run test         # run tests
+bun run lint         # lint
+bun run lint:fix     # auto-fix lint issues
+bun run server       # start the server
+```
+
+## License
+
+Apache-2.0

package/dist/esm/src/admin/activity-log.d.ts

@@ -0,0 +1,44 @@
+import type { AdminActivityEvent } from './types.js';
+/** Default maximum number of events retained in the ring buffer. */
+export declare const DEFAULT_ACTIVITY_LOG_CAPACITY = 10000;
+/**
+ * In-memory ring buffer that captures recent DWN request activity.
+ *
+ * Events are assigned a monotonically increasing `id` that acts as a cursor.
+ * When the buffer reaches capacity, the oldest events are evicted. This is
+ * **not** a persistent audit log — it is designed for real-time admin
+ * observability.
+ */
+export declare class ActivityLog {
+    #private;
+    constructor(capacity?: number);
+    /**
+     * Records a new activity event. If the buffer is full, the oldest event is
+     * evicted.
+     */
+    record(event: Omit<AdminActivityEvent, 'id' | 'timestamp'>): void;
+    /**
+     * Returns recent events, optionally filtered by a cursor (returns events
+     * with `id > since`) and limited to `limit` entries.
+     */
+    getEvents(options?: {
+        since?: number;
+        limit?: number;
+    }): {
+        events: AdminActivityEvent[];
+        cursor?: number;
+    };
+    /**
+     * Returns the current number of events in the buffer.
+     */
+    get size(): number;
+    /**
+     * Returns the configured capacity of the ring buffer.
+     */
+    get capacity(): number;
+    /**
+     * Clears all events from the buffer.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=activity-log.d.ts.map

package/dist/esm/src/admin/activity-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-log.d.ts","sourceRoot":"","sources":["../../../../src/admin/activity-log.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,oEAAoE;AACpE,eAAO,MAAM,6BAA6B,QAAS,CAAC;AAEpD;;;;;;;GAOG;AACH,qBAAa,WAAW;;gBAKV,QAAQ,GAAE,MAAsC;IAK5D;;;OAGG;IACI,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,kBAAkB,EAAE,IAAI,GAAG,WAAW,CAAC,GAAG,IAAI;IAmBxE;;;OAGG;IACI,SAAS,CAAC,OAAO,CAAC,EAAE;QACzB,KAAK,CAAC,EAAG,MAAM,CAAC;QAChB,KAAK,CAAC,EAAG,MAAM,CAAC;KACjB,GAAG;QAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;IA0BrD;;OAEG;IACH,IAAW,IAAI,IAAI,MAAM,CAExB;IAED;;OAEG;IACH,IAAW,QAAQ,IAAI,MAAM,CAE5B;IAED;;OAEG;IACI,KAAK,IAAI,IAAI;CAGrB"}

package/dist/esm/src/admin/activity-log.js

@@ -0,0 +1,85 @@
+/** Default maximum number of events retained in the ring buffer. */
+export const DEFAULT_ACTIVITY_LOG_CAPACITY = 10_000;
+/**
+ * In-memory ring buffer that captures recent DWN request activity.
+ *
+ * Events are assigned a monotonically increasing `id` that acts as a cursor.
+ * When the buffer reaches capacity, the oldest events are evicted. This is
+ * **not** a persistent audit log — it is designed for real-time admin
+ * observability.
+ */
+export class ActivityLog {
+    #capacity;
+    #buffer;
+    #nextId = 1;
+    constructor(capacity = DEFAULT_ACTIVITY_LOG_CAPACITY) {
+        this.#capacity = Math.max(1, capacity);
+        this.#buffer = [];
+    }
+    /**
+     * Records a new activity event. If the buffer is full, the oldest event is
+     * evicted.
+     */
+    record(event) {
+        const entry = {
+            id: this.#nextId++,
+            timestamp: new Date().toISOString(),
+            tenant: event.tenant,
+            interface: event.interface,
+            method: event.method,
+            statusCode: event.statusCode,
+            transport: event.transport,
+            dataSizeBytes: event.dataSizeBytes,
+        };
+        if (this.#buffer.length >= this.#capacity) {
+            this.#buffer.shift();
+        }
+        this.#buffer.push(entry);
+    }
+    /**
+     * Returns recent events, optionally filtered by a cursor (returns events
+     * with `id > since`) and limited to `limit` entries.
+     */
+    getEvents(options) {
+        const since = options?.since ?? 0;
+        const limit = options?.limit ?? 50;
+        // Binary search for the start index (events are ordered by id).
+        let startIdx = 0;
+        if (since > 0 && this.#buffer.length > 0) {
+            let lo = 0;
+            let hi = this.#buffer.length;
+            while (lo < hi) {
+                const mid = (lo + hi) >>> 1;
+                if (this.#buffer[mid].id <= since) {
+                    lo = mid + 1;
+                }
+                else {
+                    hi = mid;
+                }
+            }
+            startIdx = lo;
+        }
+        const events = this.#buffer.slice(startIdx, startIdx + limit);
+        const cursor = events.length > 0 ? events[events.length - 1].id : undefined;
+        return { events, cursor };
+    }
+    /**
+     * Returns the current number of events in the buffer.
+     */
+    get size() {
+        return this.#buffer.length;
+    }
+    /**
+     * Returns the configured capacity of the ring buffer.
+     */
+    get capacity() {
+        return this.#capacity;
+    }
+    /**
+     * Clears all events from the buffer.
+     */
+    clear() {
+        this.#buffer.length = 0;
+    }
+}
+//# sourceMappingURL=activity-log.js.map

package/dist/esm/src/admin/activity-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-log.js","sourceRoot":"","sources":["../../../../src/admin/activity-log.ts"],"names":[],"mappings":"AAEA,oEAAoE;AACpE,MAAM,CAAC,MAAM,6BAA6B,GAAG,MAAM,CAAC;AAEpD;;;;;;;GAOG;AACH,MAAM,OAAO,WAAW;IACb,SAAS,CAAS;IAClB,OAAO,CAAuB;IACvC,OAAO,GAAG,CAAC,CAAC;IAEZ,YAAY,WAAmB,6BAA6B;QAC1D,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;QACvC,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;IACpB,CAAC;IAED;;;OAGG;IACI,MAAM,CAAC,KAAmD;QAC/D,MAAM,KAAK,GAAuB;YAChC,EAAE,EAAc,IAAI,CAAC,OAAO,EAAE;YAC9B,SAAS,EAAO,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACxC,MAAM,EAAU,KAAK,CAAC,MAAM;YAC5B,SAAS,EAAO,KAAK,CAAC,SAAS;YAC/B,MAAM,EAAU,KAAK,CAAC,MAAM;YAC5B,UAAU,EAAM,KAAK,CAAC,UAAU;YAChC,SAAS,EAAO,KAAK,CAAC,SAAS;YAC/B,aAAa,EAAG,KAAK,CAAC,aAAa;SACpC,CAAC;QAEF,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YAC1C,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACvB,CAAC;QAED,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IAED;;;OAGG;IACI,SAAS,CAAC,OAGhB;QACC,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,IAAI,CAAC,CAAC;QAClC,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC;QAEnC,gEAAgE;QAChE,IAAI,QAAQ,GAAG,CAAC,CAAC;QACjB,IAAI,KAAK,GAAG,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzC,IAAI,EAAE,GAAG,CAAC,CAAC;YACX,IAAI,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;YAC7B,OAAO,EAAE,GAAG,EAAE,EAAE,CAAC;gBACf,MAAM,GAAG,GAAG,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC;gBAC5B,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,KAAK,EAAE,CAAC;oBAClC,EAAE,GAAG,GAAG,GAAG,CAAC,CAAC;gBACf,CAAC;qBAAM,CAAC;oBACN,EAAE,GAAG,GAAG,CAAC;gBACX,CAAC;YACH,CAAC;YACD,QAAQ,GAAG,EAAE,CAAC;QAChB,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,QAAQ,GAAG,KAAK,CAAC,CAAC;QAC9D,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QAE5E,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,IAAW,IAAI;QACb,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,IAAW,QAAQ;QACjB,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED;;OAEG;IACI,KAAK;QACV,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;IAC1B,CAAC;CACF"}