@brightchain/node-express-suite

The BrightStack parallel to @digitaldefiance/node-express-suite. Where the upstream library provides a complete MERN (Mongo, Express, React, Node) backend framework, this library provides the same application architecture backed by BrightChain's content-addressable block store instead of MongoDB - enabling the BrightStack (BrightDB, Express, React, Node) development path.

Part of BrightChain

What is node-express-suite?

@digitaldefiance/node-express-suite is an opinionated, secure, extensible Node.js/Express service framework built on Digital Defiance cryptography libraries. It provides complete backend infrastructure including:

• JWT authentication with mnemonic and ECIES crypto auth
• Role-based access control (RBAC)
• Dynamic model registry for extensible document schemas
• Plugin-based database architecture (IDatabasePlugin)
• Service container with base service classes
• Multi-language i18n support
• Email token workflows (verification, password reset, recovery)
• ECIES encryption/decryption and PBKDF2 key derivation
• Decorator-based controller API with automatic OpenAPI generation
• Transaction management, session adapters, and middleware pipeline
• Runtime configuration registry

All of this is built around MongoDB/Mongoose as the storage layer.

What does this library do?

@brightchain/node-express-suite replaces the MongoDB/Mongoose storage layer with BrightChain's content-addressable block store while preserving the upstream's application architecture, plugin system, service patterns, and API contracts. Every Mongoose-specific component has a BrightDB parallel:

| Upstream (MERN) | BrightStack | Role | |---|---|---| | MongoBaseService | BrightDbBaseService | Base class for database-aware services | | MongooseCollection | BrightDbCollection | Collection adapter implementing ICollection | | MongooseDocumentStore | BlockDocumentStore | Document store with Mongoose-compatible query API | | MongooseSessionAdapter | BrightChainSessionAdapter | JWT session management | | MongoDatabasePlugin | BrightDbDatabasePlugin | IDatabasePlugin implementation for app lifecycle | | MongoAuthenticationProvider | BrightDbAuthenticationProvider | User lookup and JWT verification | | ModelRegistry | BrightDbModelRegistry | Singleton collection registration | | TransactionManager | BrightDbTransactionManager | Transaction lifecycle with retry/timeout | | BaseEnvironment + .mongo | BrightDbEnvironment | Environment config with block store settings | | IMongoApplication | IBrightDbApplication | Typed application interface |

This means code written against the upstream's service patterns, plugin architecture, and controller decorators works with BrightDB by swapping the database layer - the Express infrastructure, auth, i18n, RBAC, and middleware all carry over from upstream.

What BrightStack adds beyond the upstream

Beyond the 1:1 Mongoose replacements, this library adds capabilities unique to BrightChain:

• Content-addressable storage where document identity is derived from content (SHA3-512)
• Quorum-based document encryption via QuorumService - documents are sealed so that multiple members must cooperate to decrypt
• Per-document access control with hasAccess(), findAccessibleBy(), and findByIdDecrypted()
• Multiple storage backends: local disk, in-memory (dev/test), Azure Blob Storage, and Amazon S3
• Block-level deduplication - identical documents are stored once

Architecture

@digitaldefiance/node-express-suite    (upstream MERN framework)
        |
        | extends
        v
@brightchain/node-express-suite        (this library - BrightStack database layer)
        |
        | extends
        v
@brightchain/brightchain-api-lib       (domain-specific BrightChain API)

The upstream provides the Express application skeleton, plugin system, auth, i18n, decorators, and middleware. This library slots in the BrightDB database layer. Domain-specific code (member stores, energy accounts, etc.) lives in brightchain-api-lib which extends this library further.

Installation

yarn add @brightchain/node-express-suite

Peer Dependencies

{
  "@digitaldefiance/branded-interface": "^0.0.5",
  "@digitaldefiance/node-ecies-lib": "^4.20.0",
  "@digitaldefiance/node-express-suite": "^4.23.1",
  "@brightchain/brightchain-lib": "^0.25.0",
  "@brightchain/db": "^0.25.0"
}

Quick Start

Basic Application Setup

import {
  BrightDbApplication,
  BrightDbEnvironment,
  configureBrightDbApp,
} from '@brightchain/node-express-suite';

// Environment reads from .env / process.env
const environment = new BrightDbEnvironment();

// Create application (extends upstream Application)
const app = new BrightDbApplication(environment);

// Register the BrightDB database plugin
const { plugin } = configureBrightDbApp(app, environment);

// Connect - no URI needed, uses environment-based block store config
await plugin.connect();

// Start the Express server
await app.start();

Database Initialization

import { brightchainDatabaseInit } from '@brightchain/node-express-suite';

const result = await brightchainDatabaseInit(environment, {
  modelRegistrations: async (db, blockStore) => {
    // Register domain-specific collections here
    const users = db.collection('users');
    const projects = db.collection('projects');
  },
});

if (result.success) {
  const { blockStore, db } = result.backend; // db is a BrightDb instance
  console.log('BrightDB connected');
}

Core Components

BrightDbEnvironment

Extends the upstream BaseEnvironment with BrightDB-specific configuration parsed from environment variables:

| Variable | Type | Default | Description | |---|---|---|---| | BRIGHTCHAIN_BLOCKSTORE_PATH | string | - | Path to the on-disk block store | | BRIGHTCHAIN_BLOCKSIZE_BYTES | string | Medium | Comma-separated block sizes | | BRIGHTCHAIN_BLOCKSTORE_TYPE | string | disk | Storage backend: disk, azure-blob, s3 | | USE_MEMORY_DOCSTORE | boolean | false | Use in-memory store (no persistence) | | DEV_DATABASE | string | - | Pool name for ephemeral dev database | | MEMBER_POOL_NAME | string | BrightChain | Member pool name |

Azure and S3 backends require additional variables - see the BrightDbEnvironment class for details.

BlockDocumentStore

Content-addressable document store backed by BrightChain blocks. Implements a Mongoose-compatible query API so existing code migrates with minimal changes.

import { BlockDocumentStore } from '@brightchain/node-express-suite';

const store = new BlockDocumentStore(blockStore);
const users = store.collection('users');

// CRUD operations - same API as Mongoose
await users.create({ name: 'Alice', email: '[email protected]' });
const user = await users.findOne({ name: 'Alice' }).exec();
await users.updateOne({ name: 'Alice' }, { email: '[email protected]' });
await users.deleteOne({ name: 'Alice' });

Encrypted Documents (Quorum Sealing)

Documents can be encrypted using BrightChain's quorum-based sealing, where multiple members must cooperate to decrypt:

const store = new BlockDocumentStore(blockStore, quorumService);
const secrets = store.encryptedCollection('secrets');

// Create an encrypted document
await secrets.create(
  { data: 'sensitive payload' },
  {
    encrypt: true,
    agent: sealingMember,
    memberIds: [member1Id, member2Id, member3Id],
    sharesRequired: 2,
  },
);

// Check access
const hasAccess = await secrets.hasAccess(docId, memberHexId);

// Decrypt with sufficient member keys
const decrypted = await secrets.findByIdDecrypted(docId, {
  membersWithPrivateKey: [member1, member2],
});

BrightDbDatabasePlugin

Implements the upstream IDatabasePlugin interface for the express-suite plugin architecture:

import {
  BrightDbDatabasePlugin,
  BrightDbEnvironment,
} from '@brightchain/node-express-suite';

const plugin = new BrightDbDatabasePlugin(environment);
await plugin.connect(); // No URI - uses environment config

// Access the underlying stores
const blockStore = plugin.blockStore;
const db = plugin.brightDb;

// Cleanup
await plugin.disconnect();

BrightDbModelRegistry

Singleton registry for BrightDB collections, parallel to upstream's ModelRegistry for Mongoose models:

import {
  BrightDbModelRegistry,
  BrightDbCollection,
} from '@brightchain/node-express-suite';

// Register a collection
BrightDbModelRegistry.instance.register({
  collectionName: 'organizations',
  collection: new BrightDbCollection(db.collection('organizations')),
  schema: orgSchema,
});

// Retrieve anywhere in the app
const orgReg = BrightDbModelRegistry.instance.get('organizations');

BrightDbTransactionManager

Session-based transaction support with retry logic and timeouts:

import { BrightDbTransactionManager } from '@brightchain/node-express-suite';

const txMgr = new BrightDbTransactionManager(db, true);

await txMgr.execute(
  async (session) => {
    // Operations within a transaction
    await users.create({ name: 'Bob' });
    await accounts.create({ owner: 'Bob', balance: 0 });
  },
  { maxRetries: 2, timeoutMs: 5000 },
);

BrightChainSessionAdapter

JWT session management backed by BrightDB:

import { BrightChainSessionAdapter } from '@brightchain/node-express-suite';

const sessions = new BrightChainSessionAdapter(db);

// Create a session (token is SHA-256 hashed for storage)
const sessionId = await sessions.createSession(memberId, jwtToken, ttlMs);

// Validate a token
const session = await sessions.validateToken(jwtToken);

// Cleanup expired sessions
const removed = await sessions.cleanExpired();

BrightDbAuthenticationProvider

Generic authentication provider with JWT verification and user lookup from BrightDB:

import { BrightDbAuthenticationProvider } from '@brightchain/node-express-suite';

const auth = new BrightDbAuthenticationProvider(db, jwtSecret);

const user = await auth.findUserById(userId);
const tokenUser = await auth.verifyToken(jwtToken);
const requestUser = await auth.buildRequestUserDTO(userId);

BrightDbBaseService

Base class for services that need typed access to the BrightDB application:

import { BrightDbBaseService } from '@brightchain/node-express-suite';

class ProjectService extends BrightDbBaseService {
  async getProjects() {
    const col = this.application.getModel('projects');
    return col.find({}).exec();
  }
}

Upstream Re-exports

For convenience, this library re-exports key upstream symbols so consumers don't need to depend on @digitaldefiance/node-express-suite directly:

• Application, AppRouter, createExpressConstants (classes/functions)
• IApplication, IConstants, IAuthenticationProvider, IDatabasePlugin, IEnvironment (interfaces)

It also re-exports from @brightchain/db (BrightDb, Collection) and @brightchain/brightchain-lib (BlockSize, BlockStoreType, IBlockStore).

Storage Backends

| Backend | Env Config | Description | |---|---|---| | Disk | BRIGHTCHAIN_BLOCKSTORE_TYPE=disk | Persistent local storage at BRIGHTCHAIN_BLOCKSTORE_PATH | | Memory | DEV_DATABASE=<pool-name> | Ephemeral in-memory store for development/testing | | Azure Blob | BRIGHTCHAIN_BLOCKSTORE_TYPE=azure-blob | Azure Blob Storage (requires AZURE_STORAGE_* vars) | | S3 | BRIGHTCHAIN_BLOCKSTORE_TYPE=s3 | Amazon S3 (requires AWS_S3_BUCKET_NAME and credentials) |

MERN to BrightStack Migration

See MIGRATION.md for a step-by-step guide to migrate from @digitaldefiance/node-express-suite (Mongoose/MongoDB) to @brightchain/node-express-suite (BrightDB).

Testing

A test utility is included for creating in-memory BrightDB instances:

import { createTestApp } from '@brightchain/node-express-suite';

const { plugin, environment, teardown } = await createTestApp();

// Use plugin.brightDb for test operations
const db = plugin.brightDb;
const users = db.collection('users');

// Cleanup
await teardown();

Running Tests

yarn nx test brightchain-node-express-suite

Building

yarn nx build brightchain-node-express-suite

License

MIT