@breadstone/archipel-mcp 0.0.14 → 0.0.16

package/data/guides/configuration.md

@@ -0,0 +1,242 @@
+---
+title: Configuration Management
+description: Type-safe, strategy-based configuration for NestJS modules with centralized discovery.
+order: 2
+---
+
+# Configuration Management
+
+This guide covers the `platform-configuration` package — the type-safe configuration system that all other Archipel packages depend on.
+
+> **Migration Note:** Configuration was extracted from `platform-core` into its own package. Re-exports are still available from `platform-core` for backward compatibility. New code should import directly from `@breadstone/archipel-platform-configuration`.
+
+## Installation
+
+```bash
+yarn add @breadstone/archipel-platform-configuration
+```
+
+---
+
+## Core Concepts
+
+### 1. Typed Config Keys
+
+Instead of scattering `process.env['SOME_KEY']` across your codebase, you define typed config keys once:
+
+```typescript
+import { createConfigKey } from '@breadstone/archipel-platform-configuration';
+
+export const DATABASE_URL = createConfigKey<string>('DATABASE_URL');
+export const CACHE_TTL = createConfigKey<number>('CACHE_TTL');
+export const FEATURE_ENABLED = createConfigKey<boolean>('FEATURE_ENABLED');
+```
+
+Each key carries its expected value type at compile time. The runtime shape is minimal — just a `{ key: string }` object.
+
+### 2. Strategy Pattern
+
+Configuration values are resolved through a strategy. The package ships two strategies:
+
+- **`EnvironmentConfigStrategy`** — reads from `process.env`
+- **`FileConfigStrategy`** — reads from a `.env` file via dotenv
+
+You can create custom strategies by extending `ConfigStrategyBase` (e.g. Azure App Configuration, AWS Parameter Store, HashiCorp Vault).
+
+### 3. Central Registry
+
+Every library registers the configuration it depends on. The `ConfigRegistry` collects all entries globally, enabling:
+
+- Startup validation (fail fast on missing required keys)
+- Discovery (list every env var the application needs)
+- Documentation generation
+
+---
+
+## Bootstrap (Application Root)
+
+Call `ConfigModule.forRoot()` once in your root module to create the global `ConfigService`:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { ConfigModule, EnvironmentConfigStrategy } from '@breadstone/archipel-platform-configuration';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({
+      strategyFactory: () => new EnvironmentConfigStrategy(),
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Static Overrides
+
+You can inject compile-time values that override or supplement the strategy:
+
+```typescript
+ConfigModule.forRoot({
+  strategyFactory: () => new EnvironmentConfigStrategy(),
+  statics: {
+    APP_VERSION: '2.1.0',
+    BUILD_SHA: 'abc123',
+  },
+});
+```
+
+---
+
+## Library Registration
+
+Each library module declares the configuration it depends on via `ConfigModule.register()`:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { ConfigModule, createConfigKey, type IConfigRegistryEntry } from '@breadstone/archipel-platform-configuration';
+
+const SMTP_HOST = createConfigKey<string>('SMTP_HOST');
+const SMTP_PORT = createConfigKey<number>('SMTP_PORT');
+const SMTP_SECURE = createConfigKey<boolean>('SMTP_SECURE');
+
+export const MAIL_CONFIG_ENTRIES: ReadonlyArray<IConfigRegistryEntry> = [
+  { key: SMTP_HOST, module: 'mailing', required: true, description: 'SMTP server hostname' },
+  { key: SMTP_PORT, module: 'mailing', required: false, defaultValue: 587, description: 'SMTP port' },
+  { key: SMTP_SECURE, module: 'mailing', required: false, defaultValue: true, description: 'Use TLS' },
+];
+
+@Module({
+  imports: [ConfigModule.register('mailing', MAIL_CONFIG_ENTRIES)],
+})
+export class MailModule {}
+```
+
+This makes the entries visible in the global `ConfigRegistry` for validation and documentation.
+
+---
+
+## Using ConfigService
+
+Inject `ConfigService` anywhere to read configuration values:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { ConfigService } from '@breadstone/archipel-platform-configuration';
+
+@Injectable()
+export class SmtpClient {
+  private readonly _host: string;
+  private readonly _port: number;
+
+  constructor(configService: ConfigService) {
+    this._host = configService.get<string>('SMTP_HOST'); // throws if missing
+    this._port = configService.tryGet<number>('SMTP_PORT', 587); // returns fallback if missing
+  }
+}
+```
+
+The service automatically parses string values into the appropriate types (numbers, booleans, null).
+
+---
+
+## Custom Strategies
+
+Extend `ConfigStrategyBase` for custom configuration sources:
+
+```typescript
+import { ConfigStrategyBase } from '@breadstone/archipel-platform-configuration';
+
+export class VaultConfigStrategy extends ConfigStrategyBase {
+  private _cache: Map<string, string>;
+
+  public constructor(private readonly _vaultUrl: string) {
+    super();
+    this._cache = new Map();
+  }
+
+  public initialize(): void {
+    // Fetch all secrets from Vault at startup
+  }
+
+  public resolve<T>(key: string): T {
+    const value = this._cache.get(key);
+    if (value === undefined) {
+      throw new ConfigKeyNotFoundError(key, 'vault');
+    }
+    return value as T;
+  }
+
+  public tryResolve<T>(key: string, fallback: T): T {
+    return (this._cache.get(key) as T) ?? fallback;
+  }
+
+  public has(key: string): boolean {
+    return this._cache.has(key);
+  }
+}
+```
+
+Register it:
+
+```typescript
+ConfigModule.forRoot({
+  strategyFactory: () => new VaultConfigStrategy('https://vault.example.com'),
+});
+```
+
+---
+
+## File-Based Configuration
+
+For local development, use `FileConfigStrategy` to load from a `.env` file:
+
+```typescript
+import { FileConfigStrategy } from '@breadstone/archipel-platform-configuration';
+
+ConfigModule.forRoot({
+  strategyFactory: () => new FileConfigStrategy('.env'),
+});
+```
+
+The strategy reads and parses the file using dotenv. If the file does not exist, the strategy initializes with an empty config (subsequent `get()` calls will throw `ConfigKeyNotFoundError`).
+
+---
+
+## Discovery & Validation
+
+Use `ConfigRegistry` to inspect all registered configuration at startup:
+
+```typescript
+import { ConfigRegistry } from '@breadstone/archipel-platform-configuration';
+
+// List all entries grouped by module
+const grouped = ConfigRegistry.getByModule();
+for (const [module, entries] of grouped) {
+  console.log(`Module: ${module}`);
+  for (const entry of entries) {
+    console.log(`  ${entry.key.key} — ${entry.required ? 'required' : 'optional'}`);
+  }
+}
+```
+
+This is useful for:
+
+- **Health checks** — verify all required config exists before accepting traffic
+- **Documentation** — auto-generate `.env.example` files
+- **CI/CD** — validate that deployment configs match what the application expects
+
+---
+
+## Migration from platform-core
+
+If you previously imported configuration from `platform-core`:
+
+```typescript
+// Before
+import { ConfigModule, ConfigService, createConfigKey } from '@breadstone/archipel-platform-core';
+
+// After
+import { ConfigModule, ConfigService, createConfigKey } from '@breadstone/archipel-platform-configuration';
+```
+
+Re-exports from `platform-core` continue to work for backward compatibility, but new code should use the dedicated package.

package/data/guides/cryptography-and-otp.md

@@ -0,0 +1,240 @@
+---
+title: Cryptography & OTP
+description: Hash passwords with bcrypt, generate prefixed UUIDs, and implement TOTP-based multi-factor authentication with QR code enrollment.
+order: 17
+---
+
+# Cryptography & OTP
+
+This guide covers cryptographic utilities provided by `platform-cryptography`: password hashing with bcrypt, prefixed UUID generation, and TOTP-based one-time password flows for multi-factor authentication.
+
+---
+
+## Installation
+
+```bash
+yarn add @breadstone/archipel-platform-cryptography
+```
+
+---
+
+## Password Hashing with Bcrypt
+
+`BcryptService` wraps the `bcrypt` library to hash and verify passwords securely. It generates a unique salt per hash automatically.
+
+### Hashing a Password
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { BcryptService } from '@breadstone/archipel-platform-cryptography';
+
+@Injectable()
+export class UserService {
+  private readonly _bcrypt: BcryptService;
+
+  constructor(bcrypt: BcryptService) {
+    this._bcrypt = bcrypt;
+  }
+
+  public async createUser(email: string, password: string): Promise<void> {
+    const hashedPassword = await this._bcrypt.hash(password);
+    // Store hashedPassword in the database — never the plain password
+    await this._userRepository.create({ email, password: hashedPassword });
+  }
+}
+```
+
+### Verifying a Password
+
+```typescript
+public async authenticate(email: string, password: string): Promise<boolean> {
+  const user = await this._userRepository.findByEmail(email);
+  if (!user) {
+    return false;
+  }
+
+  return this._bcrypt.compare(password, user.password);
+}
+```
+
+`compare()` returns `true` if the plain-text password matches the stored hash.
+
+---
+
+## Generating Prefixed UUIDs
+
+`CryptoService` generates UUIDs with a configurable prefix. This is useful for creating human-readable identifiers that indicate their resource type.
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { CryptoService } from '@breadstone/archipel-platform-cryptography';
+
+@Injectable()
+export class OrderService {
+  private readonly _crypto: CryptoService;
+
+  constructor(crypto: CryptoService) {
+    this._crypto = crypto;
+  }
+
+  public createOrderId(): string {
+    return this._crypto.getRandomGuid('ord');
+    // Example: "ord-a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+  }
+}
+```
+
+The prefix is required and must be a non-empty string. Use short, descriptive prefixes that represent the resource type:
+
+| Resource     | Prefix | Example                                    |
+| ------------ | ------ | ------------------------------------------ |
+| Order        | `ord`  | `ord-550e8400-e29b-41d4-a716-446655440000` |
+| Invoice      | `inv`  | `inv-6ba7b810-9dad-11d1-80b4-00c04fd430c8` |
+| Subscription | `sub`  | `sub-f47ac10b-58cc-4372-a567-0e02b2c3d479` |
+| User         | `usr`  | `usr-7c9e6679-7425-40de-944b-e07fc1f90ae7` |
+
+---
+
+## TOTP Multi-Factor Authentication
+
+`OtpService` implements TOTP (Time-Based One-Time Password) as defined in [RFC 6238](https://datatracker.ietf.org/doc/html/rfc6238). It supports QR code enrollment and token verification.
+
+### Injecting OtpService
+
+`OtpService` is provided behind the `OTP_SERVICE_TOKEN` injection token so consumers depend on the `IOtpService` interface:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { OtpService, OTP_SERVICE_TOKEN } from '@breadstone/archipel-platform-cryptography';
+
+@Module({
+  providers: [
+    {
+      provide: OTP_SERVICE_TOKEN,
+      useClass: OtpService,
+    },
+  ],
+  exports: [OTP_SERVICE_TOKEN],
+})
+export class SecurityModule {}
+```
+
+### Enrolling a User
+
+Generate a secret and a QR code URI for the user's authenticator app:
+
+```typescript
+import { Inject, Injectable } from '@nestjs/common';
+import { OTP_SERVICE_TOKEN, type IOtpService } from '@breadstone/archipel-platform-cryptography';
+
+@Injectable()
+export class MfaService {
+  private readonly _otp: IOtpService;
+
+  constructor(@Inject(OTP_SERVICE_TOKEN) otp: IOtpService) {
+    this._otp = otp;
+  }
+
+  public async enroll(userId: string, email: string): Promise<{ secret: string; uri: string }> {
+    const secret = this._otp.generateSecret();
+    const uri = this._otp.generateUri({
+      issuer: 'MyApp',
+      label: email,
+      secret: secret,
+    });
+
+    // Store the secret securely alongside the user record
+    await this._userRepository.updateMfaSecret(userId, secret);
+
+    return { secret, uri };
+    // The URI can be encoded as a QR code for scanning with Google Authenticator, Authy, etc.
+  }
+}
+```
+
+### Verifying a Token
+
+Verify a 6-digit TOTP code entered by the user:
+
+```typescript
+public verifyToken(token: string, secret: string): boolean {
+  return this._otp.verify(token, secret);
+}
+```
+
+Verification uses a configurable tolerance window (`TOTP_EPOCH_TOLERANCE`). The default tolerance is **30 seconds** (±1 time step), meaning the current code and the immediately preceding/following codes are accepted. This compensates for minor clock drift between the server and the user's device.
+
+### Tolerance Configuration
+
+The `TOTP_EPOCH_TOLERANCE` constant controls the verification window:
+
+| `TOTP_EPOCH_TOLERANCE` | Accepted range    |
+| ---------------------- | ----------------- |
+| `0`                    | Current step only |
+| `30`                   | ±1 step (±30 s)   |
+| `60`                   | ±2 steps (±60 s)  |
+| `90`                   | ±3 steps (±90 s)  |
+
+The default value is `30` (±1 step).
+
+---
+
+## Combining Services
+
+A typical MFA login flow uses all three services:
+
+```typescript
+@Injectable()
+export class AuthService {
+  private readonly _bcrypt: BcryptService;
+  private readonly _otp: IOtpService;
+  private readonly _crypto: CryptoService;
+
+  constructor(bcrypt: BcryptService, @Inject(OTP_SERVICE_TOKEN) otp: IOtpService, crypto: CryptoService) {
+    this._bcrypt = bcrypt;
+    this._otp = otp;
+    this._crypto = crypto;
+  }
+
+  public async login(email: string, password: string, totpCode?: string): Promise<IAuthResult> {
+    const user = await this._userRepository.findByEmail(email);
+    if (!user) {
+      throw new UnauthorizedException();
+    }
+
+    // Step 1: Verify password
+    const validPassword = await this._bcrypt.compare(password, user.password);
+    if (!validPassword) {
+      throw new UnauthorizedException();
+    }
+
+    // Step 2: Verify TOTP (if MFA is enabled)
+    if (user.mfaEnabled) {
+      if (!totpCode) {
+        return { status: 'mfa-required' };
+      }
+      const validTotp = this._otp.verify(totpCode, user.mfaSecret);
+      if (!validTotp) {
+        throw new UnauthorizedException('Invalid MFA code');
+      }
+    }
+
+    // Step 3: Issue session
+    const sessionId = this._crypto.getRandomGuid('ses');
+    return { status: 'authenticated', sessionId };
+  }
+}
+```
+
+---
+
+## Security Best Practices
+
+| Practice                            | Why                                                       |
+| ----------------------------------- | --------------------------------------------------------- |
+| Never store plain-text passwords    | Always use `BcryptService.hash()` before persisting       |
+| Store MFA secrets encrypted at rest | The TOTP secret is equivalent to a password               |
+| Use rate limiting on verification   | Prevents brute-force attacks on 6-digit TOTP codes        |
+| Generate backup codes on enrollment | Users may lose access to their authenticator device       |
+| Log MFA events, not secrets         | Never log secrets, tokens, or plain-text passwords        |
+| Use `OTP_SERVICE_TOKEN` for DI      | Depend on `IOtpService` interface, not the concrete class |