@brightchain/brightchain-lib 0.20.0 → 0.21.0

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "@brightchain/brightchain-lib",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "BrightChain core library - browser-compatible blockchain storage",
   "main": "src/index.js",
   "types": "src/index.d.ts",
   "browser": "src/browser.js",
+  "files": [
+    "src",
+    "README.md"
+  ],
   "exports": {
     ".": {
       "types": "./src/index.d.ts",

package/brightchain-lib/BLOCK_COVERAGE_AUDIT.md

@@ -1,169 +0,0 @@
-# Block Test Coverage Audit
-
-**Date**: 2026-01-24
-**Overall Coverage**: 61.6% statements, 46.76% branches, 51.8% functions, 62.04% lines
-
-## Block Files Below 90% Coverage
-
-### Critical Block Files (Core Block Types)
-
-| File | Statements | Branches | Functions | Lines | Priority |
-|------|-----------|----------|-----------|-------|----------|
-| `lib/blocks/encrypted.ts` | 25.66% | 22% | 30.43% | 25.66% | **HIGH** |
-| `lib/blocks/extendedCbl.ts` | 6.06% | 0% | 0% | 6.06% | **HIGH** |
-| `lib/blocks/cblBase.ts` | 50.96% | 49.09% | 47.61% | 51.45% | **HIGH** |
-| `lib/blocks/ephemeral.ts` | 66.36% | 60.46% | 93.75% | 66.36% | **MEDIUM** |
-| `lib/blocks/handleTuple.ts` | 60.34% | 26.31% | 58.33% | 59.61% | **MEDIUM** |
-| `lib/blocks/memoryTuple.ts` | 21.21% | 12.5% | 20% | 21.31% | **MEDIUM** |
-| `lib/blocks/parity.ts` | 85.71% | 75% | 100% | 85.71% | **LOW** |
-| `lib/blocks/base.ts` | 81.25% | 58.33% | 73.68% | 80.43% | **LOW** |
-| `lib/blocks/cbl.ts` | 71.42% | 100% | 33.33% | 71.42% | **LOW** |
-| `lib/blocks/whitened.ts` | 70.76% | 90.9% | 78.57% | 70.96% | **LOW** |
-| `lib/blocks/random.ts` | 70.73% | 90% | 83.33% | 71.79% | **LOW** |
-
-### Block Metadata Files
-
-| File | Statements | Branches | Functions | Lines | Priority |
-|------|-----------|----------|-----------|-------|----------|
-| `lib/encryptedBlockMetadata.ts` | 61.53% | 53.84% | 50% | 61.53% | **MEDIUM** |
-| `lib/cblBlockMetadata.ts` | 0% | 100% | 0% | 0% | **HIGH** |
-| `lib/extendedCblBlockMetadata.ts` | 0% | 100% | 0% | 0% | **HIGH** |
-
-### Block-Related Services
-
-| File | Statements | Branches | Functions | Lines | Priority |
-|------|-----------|----------|-----------|-------|----------|
-| `lib/services/blockService.ts` | 26.95% | 10% | 25% | 26.69% | **HIGH** |
-| `lib/services/tuple.service.ts` | 32.54% | 18.36% | 42.1% | 33.33% | **HIGH** |
-
-## Coverage Gaps by Category
-
-### 1. Edge Cases Not Tested
-
-#### Empty Data Blocks
-- **Missing**: Tests for blocks with zero-length data
-- **Files affected**: `base.ts`, `rawData.ts`, `ephemeral.ts`
-- **Lines uncovered**: Base block constructor edge cases
-
-#### Maximum Size Blocks
-- **Missing**: Tests for blocks at BlockSize limits (Small=1024, Medium=4096, Large=32768, Huge=262144)
-- **Files affected**: All block types
-- **Lines uncovered**: Size validation paths
-
-#### Invalid Checksum Handling
-- **Missing**: Comprehensive tests for checksum mismatch scenarios
-- **Files affected**: `base.ts` (lines 248-261), `rawData.ts` (lines 86-97)
-- **Lines uncovered**: Checksum validation error paths
-
-#### Boundary Conditions
-- **Missing**: Tests for:
-  - Blocks exactly at size boundaries
-  - Blocks with padding edge cases
-  - Blocks with maximum tuple counts
-- **Files affected**: `cblBase.ts`, `handleTuple.ts`, `memoryTuple.ts`
-
-### 2. Error Conditions Not Tested
-
-#### EncryptedBlock Errors (25.66% coverage)
-- **Uncovered lines**: 53, 267-271, 300-314, 317, 325-354, 382, 399, 410-777
-- **Missing error tests**:
-  - Decryption failures with invalid keys
-  - Encryption with missing recipients
-  - Malformed encrypted data parsing
-  - ECIES encryption/decryption errors
-  - Multi-recipient encryption edge cases
-
-#### ExtendedCBL Errors (6.06% coverage)
-- **Uncovered lines**: 32-269 (almost entire file)
-- **Missing error tests**:
-  - Invalid file name encoding
-  - Invalid MIME type
-  - Extended header parsing failures
-  - File name length validation
-
-#### CBLBase Errors (50.96% coverage)
-- **Uncovered lines**: 108, 221-225, 248-249, 272-273, 288-330, 340, 356-390
-- **Missing error tests**:
-  - Invalid address count
-  - Tuple size validation failures
-  - Circular dependency scenarios
-  - Cache invalidation edge cases
-
-#### BlockService Errors (26.95% coverage)
-- **Uncovered lines**: 46-120, 154, 156, 158, 172, 230-699, 764-833
-- **Missing error tests**:
-  - Service initialization failures
-  - Block creation with invalid parameters
-  - Encryption service unavailable
-  - Validation service failures
-
-### 3. Constructor Invariants Not Property-Tested
-
-#### Missing Property Tests for:
-1. **BaseBlock**: Constructor should maintain data integrity
-2. **EphemeralBlock**: Creator ID should be preserved
-3. **EncryptedBlock**: Encryption details should be cached correctly
-4. **CBLBase**: Address count should match parsed addresses
-5. **ExtendedCBL**: File metadata should round-trip correctly
-6. **WhitenedBlock**: Whitening should be reversible
-7. **RandomBlock**: Random data should have correct entropy
-8. **HandleTuple**: Tuple handles should be valid
-9. **MemoryTuple**: Memory tuples should maintain consistency
-
-## Recommended Test Additions
-
-### High Priority (Task 12.2 - Edge Cases)
-1. **Empty data block tests** - All block types with zero-length data
-2. **Maximum size block tests** - All block types at size limits
-3. **Invalid checksum tests** - Comprehensive checksum mismatch scenarios
-4. **Boundary condition tests** - Size boundaries, padding edge cases
-
-### High Priority (Task 12.3 - Error Conditions)
-1. **EncryptedBlock error tests** - All encryption/decryption failure paths
-2. **ExtendedCBL error tests** - File metadata validation failures
-3. **CBLBase error tests** - Address validation and cache errors
-4. **BlockService error tests** - Service initialization and operation failures
-
-### High Priority (Task 12.4 - Property Tests)
-1. **Block constructor property tests** - Invariants for all block types
-2. **Serialization round-trip property tests** - All block types
-3. **Immutability property tests** - Already implemented (passing)
-4. **Cache consistency property tests** - CBL and EncryptedBlock caches
-
-## Files Requiring Immediate Attention
-
-### Critical (< 30% coverage)
-1. `lib/blocks/encrypted.ts` (25.66%) - Core encryption functionality
-2. `lib/services/blockService.ts` (26.95%) - Core block operations
-3. `lib/blocks/memoryTuple.ts` (21.21%) - Tuple storage
-4. `lib/blocks/extendedCbl.ts` (6.06%) - Extended CBL functionality
-5. `lib/cblBlockMetadata.ts` (0%) - CBL metadata
-6. `lib/extendedCblBlockMetadata.ts` (0%) - Extended CBL metadata
-
-### Important (30-70% coverage)
-1. `lib/blocks/cblBase.ts` (50.96%) - CBL base functionality
-2. `lib/blocks/ephemeral.ts` (66.36%) - Ephemeral blocks
-3. `lib/blocks/handleTuple.ts` (60.34%) - Handle tuples
-4. `lib/encryptedBlockMetadata.ts` (61.53%) - Encrypted metadata
-5. `lib/services/tuple.service.ts` (32.54%) - Tuple service
-
-## Coverage Goal
-
-**Target**: 90% coverage for all block-related files
-**Current**: 61.6% overall, with critical block files at 25-50%
-**Gap**: Need to add approximately 200-300 test cases to reach target
-
-## Notes
-
-- Existing property tests are passing and provide good coverage for:
-  - XOR operations (constantTimeXor)
-  - Type guards (typeGuards)
-  - Date utilities (dateUtils)
-  - Block immutability (immutability.property.spec.ts)
-  - CBL consistency (cbl.consistency.property.spec.ts)
-
-- Need to focus on:
-  - EncryptedBlock encryption/decryption paths
-  - ExtendedCBL file metadata handling
-  - BlockService initialization and operations
-  - Error condition coverage across all block types

package/brightchain-lib/BROWSER_COMPAT.md

@@ -1,54 +0,0 @@
-# Browser Compatibility Guide — `brightchain-lib`
-
-`brightchain-lib` is the shared library used by both frontend (`brightchain-react`) and backend (`brightchain-api-lib`, `brightchain-db`) packages. It should remain browser-compatible wherever possible so that types, interfaces, and core logic can be consumed by web applications without Node.js polyfills.
-
-## Platform Detection Boundary Pattern
-
-When Node.js-specific code is unavoidable, `brightchain-lib` uses a **platform detection boundary** to isolate it. The canonical example is [`src/lib/crypto/platformCrypto.ts`](src/lib/crypto/platformCrypto.ts):
-
-```typescript
-import { isBrowserEnvironment } from './platformCrypto';
-
-if (isBrowserEnvironment()) {
-  // Use Web Crypto API (window.crypto.getRandomValues)
-} else {
-  // Lazy-load Node.js crypto via require('crypto')
-}
-```
-
-Key rules for this pattern:
-
-1. **Never import Node.js modules at the top level.** Use dynamic `require()` inside a runtime branch so bundlers can tree-shake the Node.js path.
-2. **Detect the environment at call time**, not at module load time. Use `isBrowserEnvironment()` / `isNodeEnvironment()` from `platformCrypto.ts`.
-3. **Prefer cross-platform libraries** (`@noble/hashes`, `@noble/curves`, `TextEncoder`/`TextDecoder`) over platform-specific APIs when performance is acceptable.
-
-## Known Platform-Specific Files
-
-| File                                        | Node.js Dependency                             | Why It Exists                                                                                                       | Notes                                                                                                                         |
-| ------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `src/lib/crypto/platformCrypto.ts`          | `require('crypto')` (lazy)                     | `getRandomBytes()` needs a CSPRNG; Web Crypto API has a 65 KB limit per call                                        | Already behind platform detection boundary — the correct pattern                                                              |
-| `src/lib/services/messaging/emailParser.ts` | `Buffer.from()`                                | Base64/quoted-printable decoding and charset conversion (ISO-8859-1, ASCII, etc.) in RFC 2047 encoded-word handling | Could be replaced with `TextDecoder` + `atob()` for browser use, or moved to `brightchain-api-lib`                            |
-| `src/lib/types/checksum.ts`                 | `Buffer` type in `fromBuffer()` / `toBuffer()` | Convenience methods for Node.js callers                                                                             | Both methods are **deprecated** — use `fromUint8Array()` / `toUint8Array()` instead. Internal storage is already `Uint8Array` |
-
-## Guidelines for Contributors
-
-### Do
-
-- Use `Uint8Array` in all new interfaces and shared types. `Buffer` is a Node.js-only global.
-- Use `TextEncoder` / `TextDecoder` for string ↔ bytes conversion.
-- Use `@noble/hashes` and `@noble/curves` for cryptographic operations (already project dependencies).
-- Use `crypto.getRandomValues()` (Web Crypto API) for random bytes in browser-targeted code.
-- Mark any unavoidable Node.js code with `@platform Node.js` in its JSDoc.
-
-### Don't
-
-- Import `fs`, `path`, `crypto`, `os`, `net`, `child_process`, or `buffer` at the top level of any file in `brightchain-lib`.
-- Use `Buffer` in interface definitions — use `Uint8Array` with a generic type parameter (`<TData>`) if backend code needs `Buffer`.
-- Add Node.js-only dependencies to `brightchain-lib`'s `package.json`. If a dependency requires Node.js, the code belongs in `brightchain-api-lib` or `brightchain-db`.
-
-### When Node.js Code Is Unavoidable
-
-1. Isolate it behind the platform detection boundary (see pattern above).
-2. Add a `@platform Node.js` JSDoc tag explaining what Node.js API is used and why.
-3. Add an entry to the table in this file.
-4. Consider whether the code should live in `brightchain-api-lib` instead.

package/brightchain-lib/DEPRECATIONS.md

@@ -1,454 +0,0 @@
-# BrightChain Deprecations
-
-This document lists all deprecated APIs in BrightChain and their recommended replacements.
-
-## Overview
-
-Deprecated APIs are marked with `@deprecated` JSDoc tags and will emit warnings when used. All deprecated APIs will be removed in version 3.0.0.
-
-**Timeline:**
-- **v2.0**: Deprecated APIs marked, warnings added
-- **v2.x**: Deprecated APIs still functional
-- **v3.0**: Deprecated APIs removed (planned Q4 2024)
-
-## Deprecated APIs
-
-### Checksum Types
-
-#### ChecksumBuffer
-**Status:** Deprecated in v2.0, will be removed in v3.0
-
-**Old:**
-```typescript
-import { ChecksumBuffer } from 'brightchain-lib';
-const checksum: ChecksumBuffer = Buffer.from(...);
-```
-
-**New:**
-```typescript
-import { Checksum } from 'brightchain-lib';
-const checksum = Checksum.fromBuffer(Buffer.from(...));
-```
-
-**Reason:** Unified checksum type system provides better type safety and consistent API.
-
----
-
-#### ChecksumUint8Array
-**Status:** Deprecated in v2.0, will be removed in v3.0
-
-**Old:**
-```typescript
-import { ChecksumUint8Array } from 'brightchain-lib';
-const checksum: ChecksumUint8Array = new Uint8Array(...);
-```
-
-**New:**
-```typescript
-import { Checksum } from 'brightchain-lib';
-const checksum = Checksum.fromUint8Array(new Uint8Array(...));
-```
-
-**Reason:** Unified checksum type system provides better type safety and consistent API.
-
----
-
-### ChecksumService Methods
-
-#### calculateChecksum()
-**Status:** Deprecated in v2.0, will be removed in v3.0
-
-**Old:**
-```typescript
-const checksum = checksumService.calculateChecksum(data);
-```
-
-**New:**
-```typescript
-const checksum = checksumService.calculateChecksumAsClass(data);
-```
-
-**Reason:** New method returns Checksum class instance with helpful methods.
-
----
-
-#### calculateChecksumForBuffers()
-**Status:** Deprecated in v2.0, will be removed in v3.0
-
-**Old:**
-```typescript
-const checksum = checksumService.calculateChecksumForBuffers(buffers);
-```
-
-**New:**
-```typescript
-const checksum = checksumService.calculateChecksumForBuffersAsClass(buffers);
-```
-
-**Reason:** New method returns Checksum class instance with helpful methods.
-
----
-
-#### calculateChecksumForString()
-**Status:** Deprecated in v2.0, will be removed in v3.0
-
-**Old:**
-```typescript
-const checksum = checksumService.calculateChecksumForString(str);
-```
-
-**New:**
-```typescript
-const checksum = checksumService.calculateChecksumForStringAsClass(str);
-```
-
-**Reason:** New method returns Checksum class instance with helpful methods.
-
----
-
-#### calculateChecksumForFile()
-**Status:** Deprecated in v2.0, will be removed in v3.0
-
-**Old:**
-```typescript
-const checksum = await checksumService.calculateChecksumForFile(file);
-```
-
-**New:**
-```typescript
-const checksum = await checksumService.calculateChecksumForFileAsClass(file);
-```
-
-**Reason:** New method returns Checksum class instance with helpful methods.
-
----
-
-#### calculateChecksumForStream()
-**Status:** Deprecated in v2.0, will be removed in v3.0
-
-**Old:**
-```typescript
-const checksum = await checksumService.calculateChecksumForStream(stream);
-```
-
-**New:**
-```typescript
-const checksum = await checksumService.calculateChecksumForStreamAsClass(stream);
-```
-
-**Reason:** New method returns Checksum class instance with helpful methods.
-
----
-
-### Checksum Utility Functions
-
-#### checksumToBuffer()
-**Status:** Deprecated in v2.0, will be removed in v3.0
-
-**Old:**
-```typescript
-import { checksumToBuffer } from 'brightchain-lib';
-const buffer = checksumToBuffer(checksum);
-```
-
-**New:**
-```typescript
-const buffer = checksum.toBuffer();
-```
-
-**Reason:** Checksum class provides built-in conversion methods.
-
----
-
-#### checksumToUint8Array()
-**Status:** Deprecated in v2.0, will be removed in v3.0
-
-**Old:**
-```typescript
-import { checksumToUint8Array } from 'brightchain-lib';
-const array = checksumToUint8Array(checksum);
-```
-
-**New:**
-```typescript
-const array = checksum.toUint8Array();
-```
-
-**Reason:** Checksum class provides built-in conversion methods.
-
----
-
-#### checksumToHex()
-**Status:** Deprecated in v2.0, will be removed in v3.0
-
-**Old:**
-```typescript
-import { checksumToHex } from 'brightchain-lib';
-const hex = checksumToHex(checksum);
-```
-
-**New:**
-```typescript
-const hex = checksum.toHex();
-```
-
-**Reason:** Checksum class provides built-in conversion methods.
-
----
-
-#### checksumFromHex()
-**Status:** Deprecated in v2.0, will be removed in v3.0
-
-**Old:**
-```typescript
-import { checksumFromHex } from 'brightchain-lib';
-const checksum = checksumFromHex(hex);
-```
-
-**New:**
-```typescript
-const checksum = Checksum.fromHex(hex);
-```
-
-**Reason:** Checksum class provides built-in factory methods.
-
----
-
-#### checksumFromBuffer()
-**Status:** Deprecated in v2.0, will be removed in v3.0
-
-**Old:**
-```typescript
-import { checksumFromBuffer } from 'brightchain-lib';
-const checksum = checksumFromBuffer(buffer);
-```
-
-**New:**
-```typescript
-const checksum = Checksum.fromBuffer(buffer);
-```
-
-**Reason:** Checksum class provides built-in factory methods.
-
----
-
-#### checksumFromUint8Array()
-**Status:** Deprecated in v2.0, will be removed in v3.0
-
-**Old:**
-```typescript
-import { checksumFromUint8Array } from 'brightchain-lib';
-const checksum = checksumFromUint8Array(array);
-```
-
-**New:**
-```typescript
-const checksum = Checksum.fromUint8Array(array);
-```
-
-**Reason:** Checksum class provides built-in factory methods.
-
----
-
-### Other Deprecated APIs
-
-#### IConstants Interface
-**Status:** Deprecated in v2.0, will be removed in v3.0
-
-**Old:**
-```typescript
-import { IConstants } from 'brightchain-lib';
-const constants: IConstants = { ... };
-```
-
-**New:**
-```typescript
-import { ICBLConsts, IFECConsts, ITupleConsts } from 'brightchain-lib';
-const cblConsts: ICBLConsts = { ... };
-```
-
-**Reason:** Specific constant interfaces provide better type safety.
-
----
-
-#### CBLService.CreatorLength (static)
-**Status:** Deprecated in v2.0, will be removed in v3.0
-
-**Old:**
-```typescript
-const length = CBLService.CreatorLength;
-```
-
-**New:**
-```typescript
-const cblService = new CBLService(...);
-const length = cblService.creatorLength;
-```
-
-**Reason:** Instance method provides better encapsulation.
-
----
-
-#### StringLanguages
-**Status:** Deprecated in v2.0, will be removed in v3.0
-
-**Old:**
-```typescript
-import { StringLanguages } from 'brightchain-lib';
-const lang = StringLanguages.EN_US;
-```
-
-**New:**
-```typescript
-import { LanguageCodes } from '@digitaldefiance/i18n-lib';
-const lang = LanguageCodes.EN_US;
-```
-
-**Reason:** Use the canonical i18n-lib implementation.
-
----
-
-#### registerTranslation()
-**Status:** Deprecated in v2.0, will be removed in v3.0
-
-**Old:**
-```typescript
-import { registerTranslation } from 'brightchain-lib';
-registerTranslation(enumObj, translations);
-```
-
-**New:**
-```typescript
-// Use i18n-lib directly for translation management
-import { i18n } from '@digitaldefiance/i18n-lib';
-```
-
-**Reason:** Stub function, use i18n-lib directly.
-
----
-
-#### EnumLanguageTranslation Type
-**Status:** Deprecated in v2.0, will be removed in v3.0
-
-**Old:**
-```typescript
-import { EnumLanguageTranslation } from 'brightchain-lib';
-type MyTranslation = EnumLanguageTranslation<MyEnum>;
-```
-
-**New:**
-```typescript
-// Use i18n-lib types directly
-import { TranslationMap } from '@digitaldefiance/i18n-lib';
-```
-
-**Reason:** Stub type, use i18n-lib directly.
-
----
-
-#### createTranslations()
-**Status:** Deprecated in v2.0, will be removed in v3.0
-
-**Old:**
-```typescript
-import { createTranslations } from 'brightchain-lib';
-const translations = createTranslations({ ... });
-```
-
-**New:**
-```typescript
-// Use i18n-lib directly for translation management
-import { i18n } from '@digitaldefiance/i18n-lib';
-```
-
-**Reason:** Stub function, use i18n-lib directly.
-
----
-
-## Migration Strategy
-
-### Step 1: Identify Usage
-Search your codebase for deprecated API usage:
-
-```bash
-# Search for deprecated imports
-grep -r "ChecksumBuffer\|ChecksumUint8Array" src/
-
-# Search for deprecated methods
-grep -r "calculateChecksum\|checksumTo\|checksumFrom" src/
-
-# Search for deprecated utilities
-grep -r "StringLanguages\|registerTranslation" src/
-```
-
-### Step 2: Update Imports
-Replace deprecated imports with new ones:
-
-```typescript
-// Old
-import { ChecksumBuffer, ChecksumUint8Array } from 'brightchain-lib';
-
-// New
-import { Checksum } from 'brightchain-lib';
-```
-
-### Step 3: Update Usage
-Replace deprecated API calls with new ones:
-
-```typescript
-// Old
-const checksum = checksumService.calculateChecksum(data);
-const hex = Buffer.from(checksum).toString('hex');
-
-// New
-const checksum = checksumService.calculateChecksumAsClass(data);
-const hex = checksum.toHex();
-```
-
-### Step 4: Test
-Run your test suite to ensure everything works:
-
-```bash
-npm test
-```
-
-### Step 5: Remove Warnings
-Verify no deprecation warnings appear in console output.
-
-## Automated Migration
-
-We provide scripts to help automate migration:
-
-```bash
-# Run migration scripts
-npm run migrate:checksums
-npm run migrate:properties
-
-# Validate migration
-npm run validate:migration
-```
-
-See [MIGRATION.md](./MIGRATION.md) for detailed migration instructions.
-
-## Getting Help
-
-If you need help migrating:
-
-1. Check the [Migration Guide](./MIGRATION.md)
-2. Review [Code Examples](./examples/)
-3. Search [GitHub Issues](https://github.com/Digital-Defiance/BrightChain/issues)
-4. Ask in [GitHub Discussions](https://github.com/Digital-Defiance/BrightChain/discussions)
-
-## Deprecation Policy
-
-BrightChain follows semantic versioning:
-
-- **Minor versions (2.x)**: Deprecations added, old APIs still work
-- **Major versions (3.0)**: Deprecated APIs removed
-
-We maintain deprecated APIs for at least one major version to give you time to migrate.
-
----
-
-**Last Updated:** January 2024  
-**Applies to:** BrightChain v2.0+