CB / @cavalierblanc/cb

Security-by-design core library for Node.js applications.

Features

• ESM-only — Modern ES Modules with full TypeScript support
• Security-first — Automatic PII sanitization and safe error handling
• JSON:API compliant — Standardized metadata and error responses
• AI-Native — Discovery API for O(1) test utility navigation

Installation

npm install @cavalierblanc/cb

Requirements

• Node.js >= 24.5.0
• npm >= 11.5.0

Optional Peer Dependencies

Install peer dependencies based on your use case:

| Dependency | When Required | |-----------------------------|------------------------------------------------| | @modelcontextprotocol/sdk | MCP server/client development | | vitest | Using test utilities (lib/technology/vitest) |

# For MCP development
npm install @modelcontextprotocol/sdk

# For test utilities
npm install vitest --save-dev

Quick Start

import { BaseError, GeneralErrorCode } from '@cavalierblanc/cb/core/error';

const error = new BaseError('Operation failed', {
  code: GeneralErrorCode.Validation,
  safeMessage: 'The request could not be processed',
  sourceModule: 'my-module',
});

console.log(error.safeMessage); // PII automatically sanitized

Modules

Core (Implemented)

| Module | Description | |-----------------------------------|-----------------------------------------------| | @cavalierblanc/cb/core/error | Normalized error handling with PII protection | | @cavalierblanc/cb/core/config | Correlation ID management | | @cavalierblanc/cb/core/metadata | JSON:API metadata pipeline | | @cavalierblanc/cb/core/security | Sanitization utilities |

Core (Scaffolding — Planned)

| Module | Description | |------------------------------------|------------------------------------| | @cavalierblanc/cb/core/protocol | JSON-RPC protocol abstraction | | @cavalierblanc/cb/core/transport | Transport layer abstraction | | @cavalierblanc/cb/core/lifecycle | Server/client lifecycle management |

Test Utilities

| Module | Description | |-------------------------------------------|------------------------------------------------| | @cavalierblanc/cb/lib/technology/vitest | Discovery API, assertions, factories, fixtures |

import { 
  assertThrowsNormalizedError,
  createTestError,
  queryByUseCase
} from '@cavalierblanc/cb/lib/technology/vitest';

// O(1) discovery of test utilities by use case
const utilities = queryByUseCase('error-normalization');

License

MIT © 2026 Cavalier Blanc Inc.