@lenne.tech/nest-server 11.31.2 → 11.32.0

package/src/core/modules/hub/services/core-hub-db.service.ts

@@ -0,0 +1,185 @@
+import { Inject, Injectable, Logger, Optional } from '@nestjs/common';
+import { InjectConnection } from '@nestjs/mongoose';
+import * as mongo from 'mongodb';
+import { Connection, Types } from 'mongoose';
+
+import { ModelRegistry } from '../../../common/services/model-registry.service';
+import { HubActionMessage } from '../hub-action-messages';
+import { HUB_CONFIG } from '../hub.constants';
+import { buildErDiagram, HubModelDescriptor, HubModelField } from '../helpers/hub-mermaid.helper';
+import { HubDbData, HubFilesData, HubModelsData, HubUnavailable } from '../interfaces/hub-panels.interface';
+import { ResolvedHubConfig } from '../interfaces/hub-config.interface';
+
+/**
+ * Read-only MongoDB introspection for the DB, Models/ERD and Files panels.
+ *
+ * Native driver access (`connection.db.*`) is used deliberately and only for admin read-only
+ * operations (stats, listings) — allowed per docs/native-driver-security.md. No writes here.
+ */
+@Injectable()
+export class CoreHubDbService {
+  protected readonly logger = new Logger(CoreHubDbService.name);
+
+  constructor(
+    @Inject(HUB_CONFIG) protected readonly config: ResolvedHubConfig,
+    @Optional() @InjectConnection() protected readonly connection?: Connection,
+  ) {}
+
+  /** Database + per-collection statistics. */
+  async getDbStats(): Promise<HubDbData | HubUnavailable> {
+    const dbConfig = this.config.db;
+    if (dbConfig === false) {
+      return { available: false, hint: 'The database panel is disabled (hub.db: false).' };
+    }
+    const db = this.connection?.db;
+    if (!db) {
+      return { available: false, hint: 'No MongoDB connection is available.' };
+    }
+    const includeIndexes = dbConfig.includeIndexes;
+
+    try {
+      const dbStats = await db.stats();
+      const collectionInfos = await db.listCollections({}, { nameOnly: true }).toArray();
+
+      // Read every collection's storage stats concurrently — sequential awaits made the DB panel's
+      // latency scale linearly with the collection count.
+      const collections = await Promise.all(
+        collectionInfos.map(async (info) => {
+          try {
+            const [stats] = await db
+              .collection(info.name)
+              .aggregate([{ $collStats: { storageStats: {} } }])
+              .toArray();
+            const storage = stats?.storageStats ?? {};
+            return {
+              avgObjSize: storage.avgObjSize,
+              count: storage.count ?? 0,
+              indexCount: includeIndexes ? storage.nindexes : undefined,
+              indexSize: includeIndexes ? storage.totalIndexSize : undefined,
+              name: info.name,
+              size: storage.size ?? 0,
+              storageSize: storage.storageSize ?? 0,
+            };
+          } catch {
+            return { count: 0, name: info.name, size: 0, storageSize: 0 };
+          }
+        }),
+      );
+
+      collections.sort((a, b) => b.size - a.size);
+
+      return {
+        collections,
+        stats: {
+          collections: dbStats.collections ?? collections.length,
+          dataSize: dbStats.dataSize ?? 0,
+          indexSize: dbStats.indexSize ?? 0,
+          objects: dbStats.objects ?? 0,
+          storageSize: dbStats.storageSize ?? 0,
+        },
+      };
+    } catch (error) {
+      this.logger.warn(`Failed to read DB stats: ${error instanceof Error ? error.message : String(error)}`);
+      return { available: false, hint: 'Failed to read database statistics.' };
+    }
+  }
+
+  /**
+   * Delete a GridFS file by id. When `expectedFilename` is given it must match the stored filename
+   * (the type-to-confirm keyword). Returns the filename; throws when not found or the name mismatches.
+   */
+  async deleteFile(id: string, expectedFilename?: string, bucket = 'fs'): Promise<{ filename: string; id: string }> {
+    const db = this.connection?.db;
+    if (!db) {
+      throw new Error(HubActionMessage.mongoUnavailable);
+    }
+    if (!Types.ObjectId.isValid(id)) {
+      throw new Error(HubActionMessage.invalidFileId);
+    }
+    const objectId = new Types.ObjectId(id);
+    const [doc] = await db.collection(`${bucket}.files`).find({ _id: objectId }, { limit: 1 }).toArray();
+    if (!doc) {
+      throw new Error(HubActionMessage.fileNotFound);
+    }
+    if (expectedFilename !== undefined && expectedFilename !== doc.filename) {
+      throw new Error(HubActionMessage.confirmationFilenameMismatch);
+    }
+    const gridFs = new mongo.GridFSBucket(db as unknown as mongo.Db, { bucketName: bucket });
+    await gridFs.delete(objectId as unknown as mongo.ObjectId);
+    return { filename: doc.filename, id };
+  }
+
+  /** GridFS file inventory for the given bucket (default `fs`). */
+  async getFiles(bucket = 'fs', skip = 0, limit = 100): Promise<HubFilesData | HubUnavailable> {
+    const db = this.connection?.db;
+    if (!db) {
+      return { available: false, hint: 'No MongoDB connection is available.' };
+    }
+    const filesCollection = `${bucket}.files`;
+    try {
+      const cursor = db
+        .collection(filesCollection)
+        .find({}, { limit: Math.min(limit, 500), skip, sort: { uploadDate: -1 } });
+      const docs = await cursor.toArray();
+      const total = await db.collection(filesCollection).countDocuments();
+      return {
+        bucket,
+        files: docs.map((doc) => ({
+          contentType: doc.contentType ?? doc.metadata?.contentType,
+          filename: doc.filename,
+          id: String(doc._id),
+          length: doc.length ?? 0,
+          uploadDate: doc.uploadDate ? new Date(doc.uploadDate).toISOString() : undefined,
+        })),
+        total,
+      };
+    } catch (error) {
+      this.logger.warn(`Failed to list GridFS files: ${error instanceof Error ? error.message : String(error)}`);
+      return { available: false, hint: `No GridFS bucket "${bucket}" or it is empty.` };
+    }
+  }
+
+  /** Model inventory + a Mermaid ER diagram derived from the registered Mongoose schemas. */
+  getModels(): HubModelsData {
+    const descriptors = this.collectModelDescriptors();
+    const mermaid = buildErDiagram(descriptors);
+    const relationCount = descriptors.reduce((sum, m) => sum + m.fields.filter((f) => f.ref).length, 0);
+    return {
+      entities: descriptors.map((d) => ({ fields: d.fields, name: d.name })),
+      mermaid,
+      modelCount: descriptors.length,
+      relationCount,
+    };
+  }
+
+  /** Walk the live Mongoose connection's schemas into value-free descriptors for the ERD builder. */
+  protected collectModelDescriptors(): HubModelDescriptor[] {
+    const models = this.connection?.models ?? {};
+    const registered = ModelRegistry.getAll();
+    const names = new Set<string>([...Object.keys(models), ...registered.keys()]);
+    const descriptors: HubModelDescriptor[] = [];
+
+    for (const name of names) {
+      const schema = models[name]?.schema;
+      if (!schema) {
+        descriptors.push({ fields: [], name });
+        continue;
+      }
+      const fields: HubModelField[] = [];
+      schema.eachPath((pathName: string, schemaType: any) => {
+        if (pathName === '__v') {
+          return;
+        }
+        fields.push({
+          name: pathName,
+          ref: schemaType?.options?.ref ?? schemaType?.caster?.options?.ref,
+          type: schemaType?.instance ?? 'Mixed',
+        });
+      });
+      descriptors.push({ fields, name });
+    }
+
+    descriptors.sort((a, b) => a.name.localeCompare(b.name));
+    return descriptors;
+  }
+}

package/src/core/modules/hub/services/core-hub-email.service.ts

@@ -0,0 +1,158 @@
+import { Inject, Injectable, Logger, Optional } from '@nestjs/common';
+import { existsSync, readdirSync } from 'fs';
+import { join, resolve } from 'path';
+
+import { ConfigService } from '../../../common/services/config.service';
+import { TemplateService } from '../../../common/services/template.service';
+import { HUB_CONFIG } from '../hub.constants';
+import { HubEmailsData, HubUnavailable } from '../interfaces/hub-panels.interface';
+import { ResolvedHubConfig } from '../interfaces/hub-config.interface';
+
+/** Sample data used to render an email template preview. Values are illustrative, never real user data. */
+const SAMPLE_PAYLOAD: Record<string, unknown> = {
+  appName: 'Nest Server',
+  email: 'jane.doe@example.com',
+  firstName: 'Jane',
+  lastName: 'Doe',
+  link: 'https://example.com/verify?token=SAMPLE',
+  name: 'Jane Doe',
+  token: 'SAMPLE-TOKEN',
+  url: 'https://example.com/verify?token=SAMPLE',
+  username: 'jane.doe',
+};
+
+/**
+ * Enumerates and previews EJS email templates for the Email Preview panel.
+ *
+ * Templates come from the project templates dir (`config.templates.path`, what `TemplateService`
+ * actually renders) and the framework fallback dir; both are scanned so a project sees the full set.
+ * Preview is rendered server-side with illustrative sample data.
+ */
+@Injectable()
+export class CoreHubEmailService {
+  protected readonly logger = new Logger(CoreHubEmailService.name);
+
+  constructor(
+    @Inject(HUB_CONFIG) protected readonly config: ResolvedHubConfig,
+    protected readonly configService: ConfigService,
+    @Optional() protected readonly templateService?: TemplateService,
+  ) {}
+
+  /** Whether the email preview panel is enabled (`hub.emailPreview`). */
+  get previewEnabled(): boolean {
+    return this.config.emailPreview !== false;
+  }
+
+  /** Inventory of available templates, grouped by base name with detected locale variants. */
+  getTemplates(): HubEmailsData {
+    const projectDir = this.projectTemplatesDir();
+    const frameworkDir = this.frameworkTemplatesDir();
+
+    const grouped = new Map<string, { locales: Set<string>; source: 'framework' | 'project' }>();
+    const add = (dir: string, source: 'framework' | 'project'): void => {
+      for (const file of this.listEjs(dir)) {
+        const { base, locale } = this.parseName(file);
+        const entry = grouped.get(base) ?? { locales: new Set<string>(), source };
+        if (locale) {
+          entry.locales.add(locale);
+        }
+        // Project templates win the source label (they override framework fallbacks).
+        if (source === 'project') {
+          entry.source = 'project';
+        }
+        grouped.set(base, entry);
+      }
+    };
+    add(frameworkDir, 'framework');
+    if (projectDir && projectDir !== frameworkDir) {
+      add(projectDir, 'project');
+    } else if (projectDir === frameworkDir) {
+      // Framework acts as its own project (e.g. this repo's e2e run) — label as project.
+      for (const [, entry] of grouped) {
+        entry.source = 'project';
+      }
+    }
+
+    return {
+      templates: [...grouped.entries()]
+        .map(([name, e]) => ({ locales: [...e.locales].sort(), name, source: e.source }))
+        .sort((a, b) => a.name.localeCompare(b.name)),
+    };
+  }
+
+  /** Render a template preview with sample data. The name is validated against the inventory (no traversal). */
+  async renderPreview(templateName: string, locale?: string): Promise<HubUnavailable | { html: string }> {
+    if (!this.previewEnabled) {
+      return { available: false, hint: 'The email preview panel is disabled (hub.emailPreview: false).' };
+    }
+    if (!this.templateService) {
+      return { available: false, hint: 'TemplateService is not available.' };
+    }
+    const inventory = this.getTemplates().templates;
+    const match = inventory.find((t) => t.name === templateName);
+    if (!match) {
+      return { available: false, hint: `Unknown template "${templateName}".` };
+    }
+    // Resolve the actual file name: prefer the requested locale variant, then the base file, then
+    // fall back to the first available locale variant.
+    let fileName = templateName;
+    if (locale && match.locales.includes(locale)) {
+      fileName = `${templateName}-${locale}`;
+    } else if (
+      !existsSyncTemplate(this.projectTemplatesDir(), this.frameworkTemplatesDir(), templateName) &&
+      match.locales.length
+    ) {
+      fileName = `${templateName}-${match.locales[0]}`;
+    }
+
+    try {
+      const html = await this.templateService.renderTemplate(fileName, SAMPLE_PAYLOAD);
+      return { html };
+    } catch (error) {
+      this.logger.warn(
+        `Failed to render template "${fileName}": ${error instanceof Error ? error.message : String(error)}`,
+      );
+      return { available: false, hint: `Failed to render template "${templateName}".` };
+    }
+  }
+
+  protected frameworkTemplatesDir(): string {
+    // From src/core/modules/hub/services → src/templates (same relative offset in dist/).
+    return resolve(__dirname, '../../../../templates');
+  }
+
+  protected listEjs(dir: string): string[] {
+    if (!dir || !existsSync(dir)) {
+      return [];
+    }
+    try {
+      return readdirSync(dir)
+        .filter((f) => f.endsWith('.ejs'))
+        .map((f) => f.slice(0, -4));
+    } catch {
+      return [];
+    }
+  }
+
+  /** Split `email-verification-de` → `{ base: 'email-verification', locale: 'de' }`. */
+  protected parseName(file: string): { base: string; locale?: string } {
+    const match = /^(.*)-([a-z]{2})$/.exec(file);
+    if (match) {
+      return { base: match[1], locale: match[2] };
+    }
+    return { base: file };
+  }
+
+  protected projectTemplatesDir(): string {
+    const path = this.configService.getFastButReadOnly('templates.path');
+    return typeof path === 'string' ? path : '';
+  }
+}
+
+/** Does a non-locale-suffixed template file exist in either dir? */
+function existsSyncTemplate(projectDir: string, frameworkDir: string, name: string): boolean {
+  return (
+    (projectDir && existsSync(join(projectDir, `${name}.ejs`))) ||
+    (frameworkDir && existsSync(join(frameworkDir, `${name}.ejs`)))
+  );
+}

package/src/core/modules/hub/services/core-hub-mailbox.service.spec.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it } from 'vitest';
+
+import { CoreHubMailboxService } from './core-hub-mailbox.service';
+import { ResolvedHubConfig } from '../interfaces/hub-config.interface';
+
+function makeConfig(overrides: Partial<ResolvedHubConfig> = {}): ResolvedHubConfig {
+  return {
+    actions: true,
+    allowPublicAccessInProduction: false,
+    collectors: { logs: false, queries: false, traces: false },
+    db: false,
+    emailPreview: true,
+    env: 'local',
+    links: {},
+    loginEndpoint: '/iam/sign-in/email',
+    logoutEndpoint: '/iam/sign-out',
+    mailbox: { capacity: 3, maxMailSize: 100, mode: 'capture' },
+    migrations: false,
+    path: 'hub',
+    pollIntervalMs: 5000,
+    roles: ['admin'],
+    version: '1.0.0',
+    ...overrides,
+  };
+}
+
+describe('CoreHubMailboxService', () => {
+  it('captures a mail and returns true to skip transport in capture mode', () => {
+    const service = new CoreHubMailboxService(makeConfig());
+    const skip = service.capture({ html: '<b>hi</b>', subject: 'Hello', to: 'a@b.com' });
+
+    expect(skip).toBe(true);
+    const data = service.getMailbox();
+    expect(data.mode).toBe('capture');
+    expect(data.mails).toHaveLength(1);
+    expect(data.mails[0].subject).toBe('Hello');
+    expect(data.mails[0].to).toBe('a@b.com');
+    expect(data.mails[0].hasHtml).toBe(true);
+  });
+
+  it('returns false in copy mode (mail is still sent)', () => {
+    const service = new CoreHubMailboxService(makeConfig({ mailbox: { capacity: 3, maxMailSize: 100, mode: 'copy' } }));
+    const skip = service.capture({ subject: 'Copy', to: 'a@b.com' });
+
+    expect(skip).toBe(false);
+    expect(service.getMailbox().mails).toHaveLength(1);
+  });
+
+  it('redacts tokens from the stored body in COPY mode (the real mail was still delivered)', () => {
+    const service = new CoreHubMailboxService(
+      makeConfig({ mailbox: { capacity: 3, maxMailSize: 5000, mode: 'copy' } }),
+    );
+    const seq = service.captureAndGetSeq({
+      html: '<a href="https://app.example.com/reset?token=SUPERSECRETVALUE123">Reset</a>',
+      subject: 'Reset',
+      to: 'a@b.com',
+    });
+    const html = service.getMailHtml(seq);
+    expect(html).toBeDefined();
+    // The captured audit copy must not expose a replayable reset token.
+    expect(html).not.toContain('SUPERSECRETVALUE123');
+  });
+
+  it('keeps the raw body in CAPTURE mode (dev/test needs the clickable link; nothing was sent)', () => {
+    const service = new CoreHubMailboxService(makeConfig());
+    const seq = service.captureAndGetSeq({
+      html: '<a href="https://app.example.com/reset?token=SUPERSECRETVALUE123">Reset</a>',
+      subject: 'Reset',
+      to: 'a@b.com',
+    });
+    expect(service.getMailHtml(seq)).toContain('SUPERSECRETVALUE123');
+  });
+
+  it('evicts old mails beyond capacity (ring buffer)', () => {
+    const service = new CoreHubMailboxService(makeConfig());
+    for (const n of [1, 2, 3, 4, 5]) {
+      service.capture({ subject: `Mail ${n}`, to: 'a@b.com' });
+    }
+    const data = service.getMailbox();
+    expect(data.mails).toHaveLength(3);
+    expect(data.mails.map((m) => m.subject)).toEqual(['Mail 3', 'Mail 4', 'Mail 5']);
+  });
+
+  it('truncates oversized bodies to the per-mail cap', () => {
+    const service = new CoreHubMailboxService(makeConfig());
+    const big = 'x'.repeat(500);
+    const seq = service.captureAndGetSeq({ html: big, subject: 'Big', to: 'a@b.com' });
+    const html = service.getMailHtml(seq);
+    expect(html).toBeDefined();
+    expect((html as string).length).toBeLessThanOrEqual(100 + 40); // cap + truncation marker
+  });
+
+  it('serves stored HTML by seq for the preview iframe', () => {
+    const service = new CoreHubMailboxService(makeConfig());
+    const seq = service.captureAndGetSeq({ html: '<p>Body</p>', subject: 'S', to: 'a@b.com' });
+    expect(service.getMailHtml(seq)).toContain('<p>Body</p>');
+    expect(service.getMailHtml(9999)).toBeUndefined();
+  });
+
+  it('clear() empties the mailbox', () => {
+    const service = new CoreHubMailboxService(makeConfig());
+    service.capture({ subject: 'S', to: 'a@b.com' });
+    service.clear();
+    expect(service.getMailbox().mails).toHaveLength(0);
+  });
+
+  it('supports cursor-based polling via since', () => {
+    const service = new CoreHubMailboxService(makeConfig());
+    service.capture({ subject: 'A', to: 'a@b.com' });
+    const first = service.getMailbox();
+    service.capture({ subject: 'B', to: 'a@b.com' });
+    const next = service.getMailbox(first.cursor);
+    expect(next.mails).toHaveLength(1);
+    expect(next.mails[0].subject).toBe('B');
+  });
+});

package/src/core/modules/hub/services/core-hub-mailbox.service.ts

@@ -0,0 +1,121 @@
+import { Inject, Injectable } from '@nestjs/common';
+
+import { redactSensitiveText } from '../../../common/helpers/logging.helper';
+import { HUB_CONFIG } from '../hub.constants';
+import { HubRingBuffer } from '../hub-ring-buffer';
+import { HubMailboxData, HubMailboxEntry } from '../interfaces/hub-panels.interface';
+import { IHubCapturedMailInput, IHubEmailCapture, ResolvedHubConfig } from '../interfaces/hub-config.interface';
+
+/** A captured mail: the list metadata plus the (truncated) bodies kept for the preview iframe. */
+interface StoredMail extends HubMailboxEntry {
+  html?: string;
+  text?: string;
+}
+
+const TRUNCATION_MARKER = '… [truncated]';
+
+/**
+ * The built-in mailbox — a Mailpit-style capture of outgoing mail for local/test use.
+ *
+ * Implements {@link IHubEmailCapture}: `EmailService` calls `capture()` before the transport. In
+ * `mode: 'capture'` the mail is recorded and NOT sent (`capture()` returns true); in `mode: 'copy'`
+ * it is recorded and still sent (returns false). Bodies are capped per mail and the buffer is a fixed
+ * ring, so memory stays bounded.
+ */
+@Injectable()
+export class CoreHubMailboxService implements IHubEmailCapture {
+  protected readonly buffer: HubRingBuffer<StoredMail>;
+  protected readonly mode: 'capture' | 'copy';
+
+  constructor(@Inject(HUB_CONFIG) protected readonly config: ResolvedHubConfig) {
+    const mailbox =
+      config.mailbox === false ? { capacity: 100, maxMailSize: 262144, mode: 'capture' as const } : config.mailbox;
+    this.mode = mailbox.mode;
+    this.buffer = new HubRingBuffer<StoredMail>(mailbox.capacity);
+  }
+
+  /** Record a mail. Returns true when the caller should SKIP the transport (capture mode). */
+  capture(mail: IHubCapturedMailInput): boolean {
+    this.store(mail);
+    return this.mode === 'capture';
+  }
+
+  /** Convenience for tests/actions: capture and return the assigned seq. */
+  captureAndGetSeq(mail: IHubCapturedMailInput): number {
+    return this.store(mail).seq;
+  }
+
+  /** Drop all captured mails. */
+  clear(): void {
+    this.buffer.clear();
+  }
+
+  /** Stored HTML (or text fallback) for a mail, for the sandboxed preview iframe. */
+  getMailHtml(seq: number): string | undefined {
+    const mail = this.buffer.recent().find((m) => m.seq === seq);
+    if (!mail) {
+      return undefined;
+    }
+    return mail.html ?? (mail.text ? `<pre>${escapeForPre(mail.text)}</pre>` : undefined);
+  }
+
+  /** Mailbox listing (metadata only), oldest→newest, optionally since a cursor. */
+  getMailbox(since?: number): HubMailboxData {
+    const entries = since === undefined ? this.buffer.recent() : this.buffer.since(since);
+    return {
+      cursor: this.buffer.lastSeq,
+      dropped: this.buffer.firstRetainedSeq,
+      mails: entries.map(toEntry),
+      mode: this.mode,
+    };
+  }
+
+  protected store(mail: IHubCapturedMailInput): StoredMail {
+    const cap = this.config.mailbox === false ? 262144 : this.config.mailbox.maxMailSize;
+    // 'copy' mode: the real mail is delivered to the recipient and the stored copy is only an
+    // admin-facing audit view — best-effort redact tokens/links (JWTs, Bearer, `?token=`/`password=`
+    // query values) so a captured reset/verification link can't be replayed from the mailbox by an
+    // admin. 'capture' mode (dev/test only, never sent, blocked in prod/staging) keeps the raw body so
+    // the link stays clickable.
+    const redact = (value?: string): string | undefined =>
+      this.mode === 'copy' && value ? redactSensitiveText(value) : value;
+    return this.buffer.add({
+      bcc: mail.bcc,
+      cc: mail.cc,
+      from: mail.from,
+      hasHtml: !!mail.html,
+      hasText: !!mail.text,
+      html: truncate(redact(mail.html), cap),
+      subject: mail.subject,
+      templateName: mail.templateName,
+      text: truncate(redact(mail.text), cap),
+      to: mail.to,
+    } as Omit<StoredMail, 'seq' | 'timestamp'>);
+  }
+}
+
+function escapeForPre(text: string): string {
+  return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+function toEntry(mail: StoredMail): HubMailboxEntry {
+  return {
+    bcc: mail.bcc,
+    cc: mail.cc,
+    from: mail.from,
+    hasHtml: mail.hasHtml,
+    hasText: mail.hasText,
+    seq: mail.seq,
+    subject: mail.subject,
+    templateName: mail.templateName,
+    timestamp: mail.timestamp,
+    to: mail.to,
+  };
+}
+
+function truncate(value: string | undefined, cap: number): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  return value.length > cap ? value.slice(0, cap) + TRUNCATION_MARKER : value;
+}