@brightchain/node-express-suite 0.25.0 → 0.26.0

package/README.md

@@ -1,11 +1,360 @@
-# brightchain-node-express-suite
+# @brightchain/node-express-suite
 
-This library was generated with [Nx](https://nx.dev).
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+The BrightStack parallel to [`@digitaldefiance/node-express-suite`](https://github.com/Digital-Defiance/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](https://github.com/Digital-Defiance/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
+
+```bash
+yarn add @brightchain/node-express-suite
+```
+
+### Peer Dependencies
+
+```json
+{
+  "@digitaldefiance/branded-interface": "^0.0.5",
+  "@digitaldefiance/node-ecies-lib": "^4.20.0",
+  "@digitaldefiance/node-express-suite": "^4.20.1",
+  "@brightchain/brightchain-lib": "^0.25.0",
+  "@brightchain/db": "^0.25.0"
+}
+```
+
+## Quick Start
+
+### Basic Application Setup
+
+```typescript
+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
+
+```typescript
+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;
+  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.
+
+```typescript
+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: 'alice@example.com' });
+const user = await users.findOne({ name: 'Alice' }).exec();
+await users.updateOne({ name: 'Alice' }, { email: 'alice@new.com' });
+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:
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+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](./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:
+
+```typescript
+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
+
+```bash
+yarn nx test brightchain-node-express-suite
+```
 
 ## Building
 
-Run `nx build brightchain-node-express-suite` to build the library.
+```bash
+yarn nx build brightchain-node-express-suite
+```
 
-## Running unit tests
+## License
 
-Run `nx test brightchain-node-express-suite` to execute the unit tests via [Jest](https://jestjs.io).
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brightchain/node-express-suite",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "private": false,
   "type": "commonjs",
   "main": "./src/index.js",