@breadstone/archipel-mcp 0.0.9 → 0.0.11

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 |

package/data/guides/document-generation.md

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

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