@breadstone/archipel-mcp 0.0.11 → 0.0.14

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

@@ -1,240 +0,0 @@
----
-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 |

package/data/guides/document-generation.md

@@ -1,174 +0,0 @@
----
-title: Document Generation
-description: Generate PDF and DOCX documents from templates with variable substitution and image processing.
-order: 11
----
-
-# Document Generation
-
-This guide covers generating documents with `platform-documents`: template setup, variable substitution, image processing, and rendering to PDF or DOCX.
-
----
-
-## Installation
-
-```bash
-yarn add @breadstone/archipel-platform-documents
-```
-
----
-
-## Module Registration
-
-```typescript
-import { Module } from '@nestjs/common';
-import { DocumentModule } from '@breadstone/archipel-platform-documents';
-
-@Module({
-  imports: [
-    DocumentModule.forRoot({
-      maxImageWidth: 1920,
-      maxImageHeight: 1080,
-      delimiters: { start: '[[', end: ']]' },
-    }),
-  ],
-})
-export class AppModule {}
-```
-
-### Options
-
-| Option           | Default | Description                                       |
-| ---------------- | ------- | ------------------------------------------------- |
-| `maxImageWidth`  | `1920`  | Maximum width for embedded images (in pixels)     |
-| `maxImageHeight` | `1080`  | Maximum height for embedded images (in pixels)    |
-| `delimiters`     | `[[ ]]` | Start and end delimiters for template variables   |
-| `debug`          | `false` | Enable verbose logging for the rendering pipeline |
-
----
-
-## Creating Templates
-
-Templates are document files (DOCX) with placeholder variables. By default, placeholders use double brackets:
-
-```
-Dear [[customerName]],
-
-Your order [[orderId]] has been confirmed.
-Total: [[orderTotal]]
-
-Thank you for your business.
-```
-
-You can change the delimiter format:
-
-```typescript
-DocumentModule.forRoot({
-  delimiters: { start: '{{', end: '}}' },
-});
-```
-
----
-
-## Rendering Documents
-
-Use `DocumentEngine` to render templates with data:
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { DocumentEngine } from '@breadstone/archipel-platform-documents';
-
-@Injectable()
-export class InvoiceService {
-  private readonly _documentEngine: DocumentEngine;
-
-  constructor(documentEngine: DocumentEngine) {
-    this._documentEngine = documentEngine;
-  }
-
-  public async generateInvoice(orderId: string, data: Record<string, unknown>): Promise<Buffer> {
-    return this._documentEngine.render({
-      template: 'invoice-template.docx',
-      data: {
-        customerName: data['customerName'],
-        orderId,
-        orderTotal: data['total'],
-        date: new Date().toLocaleDateString(),
-      },
-      format: 'pdf', // or 'docx'
-    });
-  }
-}
-```
-
-### Supported Output Formats
-
-| Format | Renderer      | Description                           |
-| ------ | ------------- | ------------------------------------- |
-| `pdf`  | PDF Renderer  | Convert template to PDF               |
-| `docx` | DOCX Renderer | Keep as DOCX with filled placeholders |
-
----
-
-## Image Processing
-
-The `SharpImageProcessor` automatically optimizes embedded images:
-
-- Resizes images that exceed `maxImageWidth` or `maxImageHeight`
-- Preserves aspect ratio
-- Compresses images for smaller file sizes
-
-This is useful for templates that include dynamic images (logos, product photos, signatures).
-
----
-
-## Serving Documents via HTTP
-
-```typescript
-import { Controller, Get, Res, Param } from '@nestjs/common';
-import { Response } from 'express';
-
-@Controller('invoices')
-export class InvoiceController {
-  private readonly _invoiceService: InvoiceService;
-
-  constructor(invoiceService: InvoiceService) {
-    this._invoiceService = invoiceService;
-  }
-
-  @Get(':orderId/pdf')
-  public async downloadInvoice(@Param('orderId') orderId: string, @Res() res: Response): Promise<void> {
-    const pdf = await this._invoiceService.generateInvoice(orderId, {
-      /* ... */
-    });
-
-    res.set({
-      'Content-Type': 'application/pdf',
-      'Content-Disposition': `attachment; filename="invoice-${orderId}.pdf"`,
-    });
-
-    res.send(pdf);
-  }
-}
-```
-
----
-
-## Debug Mode
-
-Enable debug logging to trace the rendering pipeline:
-
-```typescript
-DocumentModule.forRoot({
-  debug: true,
-});
-```
-
-This logs each step of the rendering process: template loading, placeholder parsing, variable substitution, image processing, and final output generation.
-
----
-
-## Next Steps
-
-- See the [Blob Storage](/guides/blob-storage) guide for storing generated documents
-- Browse the [platform-documents API reference](/packages/platform-documents/api/) for complete method signatures

package/data/guides/email-delivery.md

@@ -1,196 +0,0 @@
----
-title: Email Delivery
-description: Send transactional emails with multiple providers, template engines, and email verification flows.
-order: 8
----
-
-# Email Delivery
-
-This guide covers sending emails with `platform-mailing`: choosing a delivery provider, configuring template rendering, sending transactional emails, and integrating email verification flows.
-
----
-
-## Installation
-
-```bash
-yarn add @breadstone/archipel-platform-mailing
-```
-
----
-
-## Choose a Delivery Strategy
-
-`platform-mailing` supports multiple email providers. You select the strategy via environment variables — no code changes required to switch providers.
-
-| Strategy     | Value for `MAIL_DELIVERY_STRATEGY` | When to use                          |
-| ------------ | ---------------------------------- | ------------------------------------ |
-| **SMTP**     | `smtp`                             | Any SMTP server (self-hosted, relay) |
-| **Postmark** | `postmark`                         | Postmark transactional email         |
-| **Resend**   | `resend`                           | Resend API                           |
-| **SendGrid** | `sendgrid`                         | Twilio SendGrid                      |
-| **Mailgun**  | `mailgun`                          | Mailgun API                          |
-| **Log**      | `log`                              | Development only — logs to console   |
-
----
-
-## Module Registration
-
-`MailModule` is a global module. Register it once in your root module:
-
-```typescript
-import { Module } from '@nestjs/common';
-import { MailModule } from '@breadstone/archipel-platform-mailing';
-
-@Module({
-  imports: [MailModule],
-})
-export class AppModule {}
-```
-
-The module reads all configuration from environment variables. No `register()` call is needed.
-
----
-
-## Configuration
-
-### Core Variables
-
-```env
-MAIL_DELIVERY_STRATEGY=resend
-MAIL_TEMPLATE_STRATEGY=file
-MAIL_TEMPLATE_ENGINE_FORMAT=html
-MAIL_FROM_ADDRESS=noreply@yourapp.com
-MAIL_FROM_NAME=YourApp
-```
-
-### Provider-Specific Variables
-
-#### SMTP
-
-```env
-MAIL_SMTP_HOST=smtp.example.com
-MAIL_SMTP_PORT=587
-MAIL_SMTP_USER=user@example.com
-MAIL_SMTP_PASS=password
-MAIL_SMTP_SECURE=true
-```
-
-#### Resend
-
-```env
-MAIL_RESEND_API_KEY=re_...
-```
-
-#### Postmark
-
-```env
-MAIL_POSTMARK_API_KEY=...
-```
-
-#### SendGrid
-
-```env
-MAIL_SENDGRID_API_KEY=SG...
-```
-
-#### Mailgun
-
-```env
-MAIL_MAILGUN_API_KEY=key-...
-MAIL_MAILGUN_DOMAIN=mg.yourapp.com
-```
-
-### Template Strategies
-
-Templates can be loaded from the filesystem or from blob storage:
-
-| Strategy | Value for `MAIL_TEMPLATE_STRATEGY` | Description                                 |
-| -------- | ---------------------------------- | ------------------------------------------- |
-| **File** | `file`                             | Load templates from a local directory       |
-| **Blob** | `blob`                             | Load templates from `platform-blob-storage` |
-
-For file-based templates, place your `.html` or `.txt` files in the configured template directory.
-
----
-
-## Sending Emails
-
-Inject `MailService` to send emails with templates:
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { MailService } from '@breadstone/archipel-platform-mailing';
-
-@Injectable()
-export class NotificationService {
-  private readonly _mailService: MailService;
-
-  constructor(mailService: MailService) {
-    this._mailService = mailService;
-  }
-
-  public async sendWelcomeEmail(email: string, userName: string): Promise<void> {
-    await this._mailService.send({
-      to: email,
-      subject: 'Welcome to YourApp',
-      template: 'welcome',
-      context: {
-        userName,
-        dashboardUrl: 'https://yourapp.com/dashboard',
-      },
-    });
-  }
-}
-```
-
-The `template` field is the template name (without extension). The `context` object is passed to the template engine for variable substitution.
-
----
-
-## Email Verification
-
-`MailVerificationService` provides a complete email verification flow:
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { MailVerificationService } from '@breadstone/archipel-platform-mailing';
-import { VerificationService } from '@breadstone/archipel-platform-authentication';
-
-@Injectable()
-export class RegistrationService {
-  private readonly _mailVerification: MailVerificationService;
-  private readonly _verification: VerificationService;
-
-  constructor(mailVerification: MailVerificationService, verification: VerificationService) {
-    this._mailVerification = mailVerification;
-    this._verification = verification;
-  }
-
-  public async sendVerificationEmail(userId: string, email: string): Promise<void> {
-    const token = await this._verification.exhibitToken({ userId, email });
-
-    await this._mailVerification.sendVerification(email, token);
-  }
-}
-```
-
----
-
-## Health Checks
-
-`MailHealthIndicator` is registered automatically and verifies connectivity to the configured mail provider. It appears in your `/health` endpoint alongside other health indicators.
-
----
-
-## Development Tips
-
-- Use `MAIL_DELIVERY_STRATEGY=log` during local development to see email content in the console without sending real emails.
-- Use the **blob** template strategy when templates are shared across multiple services or managed by a CMS.
-- Template variables use the format defined by the template engine. Place templates in a well-organized directory structure (e.g., `templates/mail/welcome.html`).
-
----
-
-## Next Steps
-
-- See the [Authentication & Authorization](/guides/authentication-and-authorization) guide for integrating email verification into the login flow
-- Browse the [platform-mailing API reference](/packages/platform-mailing/api/) for complete method signatures