@breadstone/archipel-mcp 0.0.53 → 0.0.55

package/data/packages/platform-core/index.md

@@ -1,504 +0,0 @@
----
-title: platform-core
-description: Foundation library providing mapping, templates, event pub/sub, and shared utilities.
-order: 1
-tags: [core, mapping, templates, event-hub]
-package: '@breadstone/archipel-platform-core'
----
-
-# platform-core
-
-The foundation library that every other Archipel package depends on. Provides object mapping, template engines, event pub/sub, and shared utilities.
-
-> **Note:** Configuration has moved to [`platform-configuration`](../platform-configuration/), caching to [`platform-caching`](../platform-caching/), cryptography/OTP to [`platform-cryptography`](../platform-cryptography/), mapping to [`platform-mapping`](../platform-mapping/), resource management to [`platform-resources`](../platform-resources/), and health checks to [`platform-health`](../platform-health/). Re-exports are still available from `platform-core` for backward compatibility.
-
-**Package:** `@breadstone/archipel-platform-core`
-
-<InstallTabs />
-
-## Installation
-
-```typescript
-import {
-  ConfigModule,
-  ConfigRegistry,
-  MappingModule,
-  MappingService,
-  BcryptService,
-  CryptoService,
-  OtpService,
-  MemoryLayeredCache,
-  RedisLayeredCache,
-  ContentTemplateEngine,
-  EventHub,
-} from '@breadstone/archipel-platform-core';
-```
-
----
-
-## Configuration System
-
-> **Extracted:** Configuration has been extracted into [`platform-configuration`](../platform-configuration/). The imports below still work via re-exports for backward compatibility. New code should import from `@breadstone/archipel-platform-configuration` directly.
->
-> See the [Configuration Management guide](../../guides/configuration) for full documentation.
-
-### Defining Config Keys
-
-```typescript
-import { createConfigKey, type IConfigRegistryEntry } from '@breadstone/archipel-platform-core';
-
-// Type-safe config keys with phantom types
-const SMTP_HOST = createConfigKey<string>('SMTP_HOST');
-const SMTP_PORT = createConfigKey<number>('SMTP_PORT');
-const SMTP_SECURE = createConfigKey<boolean>('SMTP_SECURE');
-
-export const MY_MODULE_CONFIG_ENTRIES: ReadonlyArray<IConfigRegistryEntry> = [
-  { key: SMTP_HOST, module: 'my-module', required: true, description: 'SMTP server hostname' },
-  { key: SMTP_PORT, module: 'my-module', required: false, defaultValue: 587, description: 'SMTP port' },
-  { key: SMTP_SECURE, module: 'my-module', required: false, defaultValue: true },
-];
-```
-
-### Registering in a Module
-
-```typescript
-import { Module } from '@nestjs/common';
-import { ConfigModule } from '@breadstone/archipel-platform-core';
-import { MY_MODULE_CONFIG_ENTRIES } from './env';
-
-@Module({
-  imports: [ConfigModule.register('my-module', MY_MODULE_CONFIG_ENTRIES)],
-})
-export class MyModule {}
-```
-
-### Using the ConfigService
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { ConfigService } from '@breadstone/archipel-platform-core';
-
-@Injectable()
-export class SmtpClient {
-  private readonly _host: string;
-  private readonly _port: number;
-
-  constructor(configService: ConfigService) {
-    this._host = configService.get<string>('SMTP_HOST');
-    this._port = configService.tryGet<number>('SMTP_PORT', 587);
-  }
-}
-```
-
-### ConfigRegistry (Static Access)
-
-```typescript
-import { ConfigRegistry } from '@breadstone/archipel-platform-core';
-
-// List all registered modules
-const modules = ConfigRegistry.getModules(); // ['my-module', 'platform-auth', ...]
-
-// Get all required entries
-const required = ConfigRegistry.getRequired();
-
-// Get entries grouped by module
-const grouped = ConfigRegistry.getByModule();
-```
-
----
-
-## Caching
-
-Layered caching with pluggable backends, metrics, and stale-while-revalidate support.
-
-### ILayeredCache Interface
-
-```typescript
-interface ILayeredCache<TKey, TValue> {
-  get(key: TKey): TValue | undefined;
-  getAsync(key: TKey): Promise<TValue | undefined>;
-  set(key: TKey, value: TValue): void;
-  setAsync(key: TKey, value: TValue): Promise<void>;
-  invalidate(key: TKey): void;
-  invalidateAsync(key: TKey): Promise<void>;
-  warm?(key: TKey): Promise<TValue | undefined>;
-  stats?(): ICacheStats;
-}
-```
-
-### MemoryLayeredCache
-
-In-memory LRU cache with TTL and stale-while-revalidate.
-
-```typescript
-import { MemoryLayeredCache } from '@breadstone/archipel-platform-core';
-
-const productCache = new MemoryLayeredCache<string, IProduct>(
-  async (key) => {
-    // Load function — called on cache miss
-    return await this._productRepository.findById(key);
-  },
-  {
-    ttlMs: 60_000, // 60 seconds TTL
-    staleWhileRevalidate: true, // Serve stale data while refreshing
-    maxEntries: 1000, // LRU eviction after 1000 entries
-    cacheName: 'products', // For metrics labeling
-    metricsRecorder: telemetryRecorder,
-  },
-);
-
-// Usage
-const product = await productCache.getAsync('prod-123');
-
-// Invalidate after mutation
-productCache.invalidate('prod-123');
-
-// Check stats
-const stats = productCache.stats();
-// → { hits: 142, misses: 23, loads: 23, loadErrors: 0, evictions: 0 }
-```
-
-### RedisLayeredCache
-
-Redis-backed distributed cache for multi-instance deployments.
-
-```typescript
-import { RedisLayeredCache } from '@breadstone/archipel-platform-core';
-
-const sessionCache = new RedisLayeredCache<string, ISessionData>(
-  async (key) => await this._sessionStore.findByToken(key),
-  {
-    url: 'redis://localhost:6379',
-    keyPrefix: 'session:',
-    ttlSeconds: 3600,
-    serialize: (value) => JSON.stringify(value),
-    deserialize: (raw) => JSON.parse(raw),
-    cacheName: 'sessions',
-  },
-);
-```
-
-### ICacheMetricsRecorder
-
-Integrate cache metrics with your observability stack.
-
-```typescript
-import type { ICacheMetricsRecorder } from '@breadstone/archipel-platform-core';
-
-class MyMetricsRecorder implements ICacheMetricsRecorder {
-  public recordHit(cache: string): void {
-    /* prometheus counter */
-  }
-  public recordMiss(cache: string): void {
-    /* prometheus counter */
-  }
-  public recordLoadSuccess(cache: string): void {
-    /* ... */
-  }
-  public recordLoadError(cache: string): void {
-    /* ... */
-  }
-  public recordEviction(cache: string): void {
-    /* ... */
-  }
-}
-```
-
----
-
-## Mapping Service
-
-> **Extracted:** Mapping functionality now lives in [`platform-mapping`](/packages/platform-mapping/). The imports below still work via backward-compatible re-exports from `platform-core`, but new code should import from `@breadstone/archipel-platform-mapping` directly.
-
-Centralized object mapping with type-safe keys and profiles.
-
-### Defining Mapping Keys
-
-```typescript
-import { createMappingKey } from '@breadstone/archipel-platform-core';
-import type { IUserEntity } from './entities';
-import type { UserResponse } from './responses';
-
-export const USER_TO_RESPONSE = createMappingKey<IUserEntity, UserResponse>('UserEntity→UserResponse');
-export const USER_TO_SUMMARY = createMappingKey<IUserEntity, UserSummary>('UserEntity→UserSummary');
-```
-
-### Creating a Mapping Profile
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { MappingProfileBase, type IMappingBuilder } from '@breadstone/archipel-platform-core';
-import { USER_TO_RESPONSE, USER_TO_SUMMARY } from './mapping-keys';
-
-@Injectable()
-export class UserMappingProfile extends MappingProfileBase {
-  public override configure(builder: IMappingBuilder): void {
-    builder.createKeyedMap(USER_TO_RESPONSE, (source) => ({
-      id: source.id,
-      name: source.userName,
-      email: source.email,
-      verified: source.isVerified,
-      roles: [...source.roles],
-    }));
-
-    builder.createKeyedMap(USER_TO_SUMMARY, (source) => ({
-      id: source.id,
-      displayName: source.userName ?? source.email ?? 'Anonymous',
-    }));
-  }
-}
-```
-
-### Registering Profiles in a Module
-
-```typescript
-import { Module } from '@nestjs/common';
-import { MappingModule } from '@breadstone/archipel-platform-core';
-import { UserMappingProfile } from './mappers/UserMappingProfile';
-import { OrderMappingProfile } from './mappers/OrderMappingProfile';
-
-@Module({
-  imports: [MappingModule.withProfiles([UserMappingProfile, OrderMappingProfile])],
-})
-export class AppModule {}
-```
-
-### Using in a Controller
-
-```typescript
-import { Controller, Get, Param } from '@nestjs/common';
-import { MappingService } from '@breadstone/archipel-platform-core';
-import { USER_TO_RESPONSE } from './mapping-keys';
-
-@Controller('users')
-export class UserController {
-  constructor(
-    private readonly _userService: UserService,
-    private readonly _mappingService: MappingService,
-  ) {}
-
-  @Get(':id')
-  public async getUser(@Param('id') id: string): Promise<UserResponse> {
-    const entity = await this._userService.findById(id);
-    return this._mappingService.map(USER_TO_RESPONSE, entity);
-  }
-}
-```
-
----
-
-## Cryptography & OTP
-
-### BcryptService
-
-Password hashing with bcrypt.
-
-```typescript
-import { BcryptService } from '@breadstone/archipel-platform-core';
-
-@Injectable()
-export class AccountService {
-  constructor(private readonly _bcrypt: BcryptService) {}
-
-  public async register(password: string): Promise<void> {
-    const hash = await this._bcrypt.hash(password);
-    // Store hash in database
-  }
-
-  public async verifyPassword(input: string, storedHash: string): Promise<boolean> {
-    return this._bcrypt.compare(input, storedHash);
-  }
-}
-```
-
-### CryptoService
-
-UUID-based identifier generation.
-
-```typescript
-import { CryptoService } from '@breadstone/archipel-platform-core';
-
-const crypto = new CryptoService();
-const token = crypto.getRandomGuid('verify');
-// → "verify-a1b2c3d4-e5f6-7890-abcd-ef1234567890"
-```
-
-### OtpService
-
-TOTP one-time password generation and verification (otplib).
-
-```typescript
-import { OtpService } from '@breadstone/archipel-platform-core';
-import type { IOtpService } from '@breadstone/archipel-platform-core';
-
-@Injectable()
-export class MfaSetupService {
-  constructor(@Inject(OTP_SERVICE_TOKEN) private readonly _otp: IOtpService) {}
-
-  public setup(userEmail: string): { secret: string; uri: string } {
-    const secret = this._otp.generateSecret();
-    const uri = this._otp.generateUri({
-      issuer: 'MyApp',
-      label: userEmail,
-      secret,
-    });
-    return { secret, uri };
-  }
-
-  public verify(token: string, secret: string): boolean {
-    return this._otp.verify(token, secret);
-    // Window = 1 → accepts current + previous 30s interval
-  }
-}
-```
-
----
-
-## Event System
-
-Type-safe publish/subscribe with RxJS.
-
-### Defining Events
-
-```typescript
-import { createEventKey, type IEventMap } from '@breadstone/archipel-platform-core';
-
-interface IOrderEvents extends IEventMap {
-  'order.created': { orderId: string; userId: string };
-  'order.shipped': { orderId: string; trackingNumber: string };
-  'order.cancelled': { orderId: string; reason: string };
-}
-
-export const ORDER_CREATED = createEventKey<IOrderEvents, 'order.created'>('order.created');
-export const ORDER_SHIPPED = createEventKey<IOrderEvents, 'order.shipped'>('order.shipped');
-```
-
-### Publishing & Subscribing
-
-```typescript
-import { EventHub } from '@breadstone/archipel-platform-core';
-import { ORDER_CREATED, ORDER_SHIPPED } from './events';
-
-@Injectable()
-export class OrderService {
-  constructor(private readonly _events: EventHub) {}
-
-  public async createOrder(userId: string): Promise<void> {
-    const orderId = '...';
-    // ... create order logic
-
-    this._events.publish(ORDER_CREATED, { orderId, userId });
-  }
-}
-
-@Injectable()
-export class NotificationService {
-  constructor(events: EventHub) {
-    events.subscribe(ORDER_CREATED, (payload) => {
-      // payload is typed as { orderId: string; userId: string }
-      this.sendOrderConfirmation(payload.userId, payload.orderId);
-    });
-  }
-}
-```
-
----
-
-## Content Template Engine
-
-Handlebars-style template compilation with block helpers.
-
-```typescript
-import { ContentTemplateEngine } from '@breadstone/archipel-platform-core';
-
-const engine = new ContentTemplateEngine();
-
-// Simple variable substitution
-const result = engine.compileTemplate('Hello {{name}}, welcome to {{app}}!', { name: 'Alice', app: 'MyApp' });
-// → "Hello Alice, welcome to MyApp!"
-
-// Block helpers
-const list = engine.compileTemplate('{{#each items}}- {{this.name}}: {{this.price}}€\n{{/each}}', {
-  items: [
-    { name: 'Widget', price: 9.99 },
-    { name: 'Gadget', price: 19.99 },
-  ],
-});
-
-// Conditionals
-const conditional = engine.compileTemplate('{{#if isPremium}}Premium Member{{/if}}{{#if !isPremium}}Free Tier{{/if}}', {
-  isPremium: true,
-});
-```
-
----
-
-## Identifier Generation
-
-Pluggable ID generation via `IdentifierModule`.
-
-```typescript
-import { IdentifierModule, ID_GENERATOR_TOKEN, type IIdGenerator } from '@breadstone/archipel-platform-core';
-
-// Module setup — choose strategy
-@Module({
-  imports: [IdentifierModule.register('CUID')],
-})
-export class AppModule {}
-
-// Usage in a service
-@Injectable()
-export class OrderService {
-  constructor(@Inject(ID_GENERATOR_TOKEN) private readonly _idGen: IIdGenerator) {}
-
-  public createOrder(): string {
-    return this._idGen.generate(); // CUID, UUID, or GUID depending on registration
-  }
-}
-```
-
----
-
-## Utility Services
-
-| Service                      | Purpose                                                                  |
-| ---------------------------- | ------------------------------------------------------------------------ |
-| `DeviceParserService`        | Parse `User-Agent` headers into `IDeviceInfo` (browser, OS, device type) |
-| `HostService`                | Host configuration (title, logo, features, health endpoints)             |
-| `UserAvatarGeneratorService` | Generate deterministic avatars from user identifiers                     |
-| `UsernameGeneratorService`   | Generate random usernames from word lists                                |
-| `SseHub`                     | Server-Sent Events hub — bounded to 10,000 event subjects                |
-| `maskSensitiveFields()`      | Recursively masks sensitive keys (password, token, apikey, etc.) in objects for safe logging |
-| `maskSensitive()`            | Serializes a value to JSON with sensitive keys masked                    |
-
----
-
-## HTTP Logger Middleware
-
-The `HttpLoggerMiddleware` logs incoming requests with automatic masking of sensitive data in query parameters, route params, and request bodies. Sensitive fields (passwords, tokens, API keys, emails, etc.) are replaced with `'***'` before logging.
-
----
-
-## Module Summary
-
-| Export                  | Type          | Description                                                                         |
-| ----------------------- | ------------- | ----------------------------------------------------------------------------------- |
-| `ConfigModule`          | NestJS Module | Configuration registration and validation (re-export from `platform-configuration`) |
-| `MappingModule`         | NestJS Module | Mapping profile registration (re-export from `platform-mapping`)                    |
-| `EventModule`           | NestJS Module | Event pub/sub system                                                                |
-| `IdentifierModule`      | NestJS Module | ID generation strategy                                                              |
-| `HostModule`            | NestJS Module | Host services and templates                                                         |
-| `HealthModule`          | NestJS Module | Health check orchestration (re-export from `platform-health`)                       |
-| `ResourceModule`        | NestJS Module | Resource loading strategies (re-export from `platform-resources`)                   |
-| `MappingService`        | Service       | Central object mapping (re-export from `platform-mapping`)                          |
-| `ConfigService`         | Service       | Type-safe config access (re-export from `platform-configuration`)                   |
-| `BcryptService`         | Service       | Password hashing                                                                    |
-| `CryptoService`         | Service       | UUID generation                                                                     |
-| `OtpService`            | Service       | TOTP generation/verification                                                        |
-| `EventHub`              | Service       | Event publish/subscribe                                                             |
-| `ContentTemplateEngine` | Service       | Template compilation                                                                |
-| `MemoryLayeredCache`    | Class         | In-memory LRU cache                                                                 |
-| `RedisLayeredCache`     | Class         | Redis-backed cache                                                                  |
-| `maskSensitiveFields()` | Utility       | Recursively masks sensitive keys in objects for safe logging                        |
-| `maskSensitive()`       | Utility       | JSON-serializes values with sensitive keys masked                                   |
-| `HttpLoggerMiddleware`  | Middleware    | Request logging with automatic sensitive data masking                               |

package/data/packages/platform-cryptography/index.md

@@ -1,142 +0,0 @@
----
-title: platform-cryptography
-description: Bcrypt password hashing, prefixed UUID generation, and TOTP multi-factor authentication.
-order: 17
-tags: [cryptography, bcrypt, uuid, totp, otp, mfa, hashing]
-package: '@breadstone/archipel-platform-cryptography'
----
-
-# platform-cryptography
-
-Cryptographic building blocks for NestJS applications: bcrypt password hashing, prefixed UUID generation, and TOTP-based multi-factor authentication. All services are `@Injectable()` and ready for constructor injection.
-
-**Package:** `@breadstone/archipel-platform-cryptography`
-
-<InstallTabs />
-
-## Quick Start
-
-```typescript
-import { BcryptService, CryptoService } from '@breadstone/archipel-platform-cryptography';
-
-// OTP is a tree-shakable sub-export
-import { OtpService, OTP_SERVICE_TOKEN } from '@breadstone/archipel-platform-cryptography/otp';
-```
-
----
-
-## Password Hashing (BcryptService)
-
-Secure password hashing with auto-generated salts.
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { BcryptService } from '@breadstone/archipel-platform-cryptography';
-
-@Injectable()
-export class AccountService {
-  constructor(private readonly _bcrypt: BcryptService) {}
-
-  async createAccount(password: string): Promise<void> {
-    const hashed = await this._bcrypt.hash(password);
-    // store hashed password
-  }
-
-  async verifyPassword(password: string, hash: string): Promise<boolean> {
-    return this._bcrypt.compare(password, hash);
-  }
-}
-```
-
-| Method                     | Description                                   |
-| -------------------------- | --------------------------------------------- |
-| `hash(data)`               | Hashes a string with a generated bcrypt salt. |
-| `compare(data, encrypted)` | Compares plain text against a bcrypt hash.    |
-
----
-
-## Prefixed UUIDs (CryptoService)
-
-Generates random UUIDs prefixed with a domain identifier for readable, collision-free identifiers.
-
-```typescript
-import { CryptoService } from '@breadstone/archipel-platform-cryptography';
-
-const crypto = new CryptoService();
-
-crypto.getRandomGuid('usr'); // → 'usr-a1b2c3d4-...'
-crypto.getRandomGuid('ord'); // → 'ord-e5f6a7b8-...'
-crypto.getRandomGuid('inv'); // → 'inv-c9d0e1f2-...'
-```
-
-| Method                  | Description                                           |
-| ----------------------- | ----------------------------------------------------- |
-| `getRandomGuid(prefix)` | Returns `{prefix}-{uuid}`. Throws if prefix is empty. |
-
----
-
-## TOTP Multi-Factor Authentication (OtpService)
-
-TOTP enrollment and verification backed by otplib v13, injected via the `OTP_SERVICE_TOKEN` symbol.
-
-### Injection Setup
-
-```typescript
-import { Module } from '@nestjs/common';
-import { OtpService, OTP_SERVICE_TOKEN } from '@breadstone/archipel-platform-cryptography/otp';
-
-@Module({
-  providers: [{ provide: OTP_SERVICE_TOKEN, useClass: OtpService }],
-  exports: [OTP_SERVICE_TOKEN],
-})
-export class SecurityModule {}
-```
-
-### Usage
-
-```typescript
-import { Inject, Injectable } from '@nestjs/common';
-import { OTP_SERVICE_TOKEN, IOtpService } from '@breadstone/archipel-platform-cryptography/otp';
-
-@Injectable()
-export class MfaService {
-  constructor(@Inject(OTP_SERVICE_TOKEN) private readonly _otp: IOtpService) {}
-
-  enroll(issuer: string, label: string) {
-    const secret = this._otp.generateSecret();
-    const uri = this._otp.generateUri({ issuer, label, secret });
-    return { secret, uri }; // uri → QR code
-  }
-
-  verify(token: string, secret: string): boolean {
-    return this._otp.verify(token, secret);
-  }
-}
-```
-
-### Tolerance
-
-The default `TOTP_EPOCH_TOLERANCE` is 30 seconds (±1 time step):
-
-| `epochTolerance` | Accepted range    |
-| ---------------- | ----------------- |
-| 0                | Current step only |
-| 30               | ±1 step (±30 s)   |
-| 60               | ±2 steps (±60 s)  |
-| 90               | ±3 steps (±90 s)  |
-
----
-
-## Error Handling
-
-`CryptoService` throws `CryptoValidationError` when provided with invalid input (e.g. empty UUID prefix). The error carries a `code` property set to `'CRYPTO_VALIDATION'`.
-
-```typescript
-import { CryptoValidationError } from '@breadstone/archipel-platform-cryptography';
-```
-
----
-
-## API Reference
-
-See the full [API documentation](./api/) for all exported types and classes.