@digitaldefiance/node-express-suite 3.7.4 → 3.7.5

package/src/routers/app.ts

@@ -0,0 +1,395 @@
+/**
+ * @fileoverview Application router for serving React frontend and API routes.
+ * Handles static file serving, EJS template rendering, and catch-all routing.
+ * @module routers/app
+ */
+
+import {
+  CoreI18nComponentId,
+  TranslatableGenericError,
+} from '@digitaldefiance/i18n-lib';
+import {
+  getSuiteCoreTranslation,
+  SuiteCoreStringKey,
+  TranslatableSuiteError,
+} from '@digitaldefiance/suite-core-lib';
+import ejs from 'ejs';
+import {
+  Application,
+  static as expressStatic,
+  NextFunction,
+  Request,
+  Response,
+} from 'express';
+import { existsSync, readdirSync } from 'fs';
+import { resolve, sep } from 'path';
+import { IApplication } from '../interfaces/application';
+import { debugLog, handleError, sendApiMessageResponse } from '../utils';
+import { BaseRouter } from './base';
+import type { PlatformID } from '@digitaldefiance/node-ecies-lib';
+
+/**
+ * Dummy function to ensure EJS is included in the bundle.
+ * @private
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+function keepEJS() {
+  ejs.compile(''); // Compile an empty string, doesn't generate anything meaningful
+}
+
+/**
+ * Application router for serving React frontend and API routes.
+ * Sets up static file serving, EJS template rendering, and catch-all routing for SPA.
+ * @template TID Platform-specific ID type
+ * @template TApplication Application instance type
+ */
+export class AppRouter<
+  TID extends PlatformID = Buffer,
+  TApplication extends IApplication<TID> = IApplication<TID>,
+> {
+  /** Path to EJS views directory */
+  protected readonly viewsPath: string;
+  /** Path to index.html file */
+  protected readonly indexPath: string;
+  /** Path to assets directory */
+  protected readonly assetsDir: string;
+  /** Path to React distribution directory */
+  protected readonly reactDistDir: string;
+
+  /** API router instance */
+  protected readonly apiRouter: BaseRouter<TID, TApplication>;
+  /** Application instance */
+  protected readonly application: TApplication;
+
+  /**
+   * Creates a new application router instance.
+   * Validates and resolves all paths to prevent directory traversal attacks.
+   * @param apiRouter API router instance to mount under /api
+   * @throws {TranslatableSuiteError} If paths contain invalid traversal sequences
+   */
+  constructor(apiRouter: BaseRouter<TID, TApplication>) {
+    this.application = apiRouter.application;
+    this.apiRouter = apiRouter;
+
+    // Validate paths don't contain traversal sequences
+    if (
+      this.application.environment.apiDistDir.includes('..') ||
+      this.application.environment.reactDistDir.includes('..')
+    ) {
+      throw new TranslatableSuiteError(
+        SuiteCoreStringKey.Error_InvalidPathContainsParentDirectoryReference,
+      );
+    }
+
+    const normalizedApiDistDir = resolve(
+      this.application.environment.apiDistDir,
+    );
+    const viewsPath = resolve(normalizedApiDistDir, 'views');
+    if (
+      !viewsPath.startsWith(normalizedApiDistDir + sep) &&
+      viewsPath !== normalizedApiDistDir
+    ) {
+      throw new TranslatableSuiteError(
+        SuiteCoreStringKey.Error_InvalidViewsPathEscapesBaseDirectory,
+      );
+    }
+    this.viewsPath = viewsPath;
+
+    const normalizedReactDistDir = resolve(
+      this.application.environment.reactDistDir,
+    );
+    this.reactDistDir = normalizedReactDistDir;
+
+    const indexPath = resolve(normalizedReactDistDir, 'index.html');
+    if (
+      !indexPath.startsWith(normalizedReactDistDir + sep) &&
+      indexPath !== normalizedReactDistDir
+    ) {
+      throw new TranslatableSuiteError(
+        SuiteCoreStringKey.Error_InvalidIndexPathEscapesBaseDirectory,
+      );
+    }
+    this.indexPath = indexPath;
+
+    const assetsPath = resolve(normalizedReactDistDir, 'assets');
+    if (
+      !assetsPath.startsWith(normalizedReactDistDir + sep) &&
+      assetsPath !== normalizedReactDistDir
+    ) {
+      throw new TranslatableSuiteError(
+        SuiteCoreStringKey.Error_InvalidAssetsPathEscapesBaseDirectory,
+      );
+    }
+    this.assetsDir = assetsPath;
+  }
+
+  /**
+   * Gets the filename of an asset matching a pattern.
+   * @param assetDir Directory to search in
+   * @param pattern Regular expression pattern to match
+   * @returns Filename if found, undefined otherwise
+   */
+  public getAssetFilename(
+    assetDir: string,
+    pattern: RegExp,
+  ): string | undefined {
+    try {
+      // Prevent path traversal by validating assetDir is within expected directory
+      // amazonq-ignore-next-line already addressed
+      if (
+        // amazonq-ignore-next-line
+        assetDir.includes('..') ||
+        !assetDir.startsWith(this.reactDistDir)
+      ) {
+        return undefined;
+      }
+      const files = readdirSync(assetDir, 'utf8');
+      return files.find((f) => pattern.test(f));
+    } catch {
+      return undefined;
+    }
+  }
+
+  /**
+   * Gets base view locals for EJS template rendering.
+   * Subclasses can override to add additional locals.
+   * @param req Express request
+   * @param res Express response
+   * @returns Object containing base template variables
+   */
+  protected getBaseViewLocals(
+    req: Request,
+    res: Response,
+  ): Record<string, unknown> {
+    const SiteName = this.application.constants.Site;
+    const SiteTagline = this.application.constants.SiteTagline;
+    const SiteDescription = this.application.constants.SiteDescription;
+    const hostname = req.hostname;
+    const server =
+      (req.socket.localPort === 443 && req.protocol === 'https') ||
+      (req.socket.localPort === 80 && req.protocol === 'http')
+        ? `${req.protocol}://${hostname}`
+        : `${req.protocol}://${hostname}:${req.socket.localPort}`;
+
+    return {
+      cspNonce: res.locals['cspNonce'],
+      title: SiteName,
+      tagline: SiteTagline,
+      description: SiteDescription,
+      server,
+      siteUrl: this.apiRouter.application.environment.serverUrl,
+      baseHref: this.apiRouter.application.environment.basePath,
+      hostname,
+      siteTitle: SiteName,
+    };
+  }
+
+  /**
+   * Renders an EJS template with the provided locals.
+   * @param req Express request
+   * @param res Express response
+   * @param next Express next function
+   * @param template Template name to render
+   * @param locals Template variables
+   */
+  protected renderTemplate(
+    req: Request,
+    res: Response,
+    next: NextFunction,
+    template: string,
+    locals: Record<string, unknown>,
+  ): void {
+    if (!/^[\w/-]+$/.test(template)) {
+      next(new Error('Invalid template name requested'));
+      return;
+    }
+
+    const sanitizedUrl = (req.url || '').replace(/[\r\n]/g, ' ');
+    debugLog(
+      this.apiRouter.application.environment.debug,
+      'log',
+      `Rendering view "${template}" for ${sanitizedUrl}`,
+    );
+
+    res.render(template, locals, (err, html) => {
+      if (err) {
+        const errMsg =
+          err && typeof err === 'object' && 'message' in err
+            ? String(err.message).replace(/[\r\n]/g, ' ')
+            : 'Unknown error';
+        console.error('Error rendering: ' + errMsg);
+        const normalizedError = err instanceof Error ? err : new Error(errMsg);
+        if (!res.headersSent) {
+          res.status(500).send('An error occurred');
+        }
+        next(normalizedError);
+        return;
+      }
+
+      if (!html) {
+        next(new Error(`Rendered template "${template}" returned empty HTML`));
+        return;
+      }
+
+      debugLog(
+        this.apiRouter.application.environment.debug,
+        'log',
+        `Rendered view "${template}" for ${sanitizedUrl}`,
+      );
+
+      res.send(html);
+    });
+  }
+
+  /**
+   * Creates a view renderer function for a specific template.
+   * @param template Template name to render
+   * @param localsFactory Optional function to generate additional locals
+   * @returns Express middleware function
+   */
+  protected createViewRenderer(
+    template: string,
+    localsFactory?: (req: Request, res: Response) => Record<string, unknown>,
+  ): (req: Request, res: Response, next: NextFunction) => void {
+    return (req, res, next) => {
+      const baseLocals = this.getBaseViewLocals(req, res);
+      const extraLocals = localsFactory ? localsFactory(req, res) : {};
+      this.renderTemplate(req, res, next, template, {
+        ...baseLocals,
+        ...extraLocals,
+      });
+    };
+  }
+
+  /**
+   * Override to register additional routes (e.g. other EJS pages) before the index catch-all.
+   * @param app Express application
+   */
+  protected registerAdditionalRenderHooks(app: Application): void {
+    void app;
+  }
+
+  /**
+   * Renders the index.html page with injected asset paths.
+   * @param req Express request
+   * @param res Express response
+   * @param next Express next function
+   */
+  public renderIndex(req: Request, res: Response, next: NextFunction): void {
+    if (req.url.endsWith('.js')) {
+      res.type('application/javascript');
+    }
+
+    const jsFile = this.getAssetFilename(this.assetsDir, /^index-.*\.js$/);
+    const cssFile = this.getAssetFilename(this.assetsDir, /^index-.*\.css$/);
+    const locals = {
+      ...this.getBaseViewLocals(req, res),
+      jsFile: jsFile ? `assets/${jsFile}` : undefined,
+      cssFile: cssFile ? `assets/${cssFile}` : undefined,
+    };
+
+    this.renderTemplate(req, res, next, 'index', locals);
+  }
+
+  /**
+   * Initializes the application router with all routes and middleware.
+   * Sets up API routes, static file serving, and catch-all routing.
+   * @param app Express application
+   * @throws {TranslatableGenericError} If index file not found or invalid paths
+   */
+  public init(app: Application) {
+    const reactDistHasDistSegment = this.reactDistDir
+      .split(sep)
+      .filter((segment) => segment.length > 0)
+      .some((segment) => segment.toLowerCase() === 'dist');
+    if (!reactDistHasDistSegment) {
+      throw new TranslatableGenericError<SuiteCoreStringKey>(
+        CoreI18nComponentId,
+        SuiteCoreStringKey.Error_AppDoesNotAppearToBeRunningWithinDistTemplate,
+        { dir: this.apiRouter.application.environment.reactDistDir },
+      );
+    }
+    if (!existsSync(this.indexPath)) {
+      throw new TranslatableGenericError<SuiteCoreStringKey>(
+        CoreI18nComponentId,
+        SuiteCoreStringKey.Error_IndexFileNotFoundTemplate,
+        { path: this.indexPath },
+      );
+    }
+
+    if (this.apiRouter.application.environment.debug) {
+      app.use((req, res, next) => {
+        const port =
+          (req.socket.localPort === 443 && req.protocol === 'https') ||
+          (req.socket.localPort === 80 && req.protocol === 'http')
+            ? ''
+            : `:${req.socket.localPort}`;
+        // amazonq-ignore-next-line
+        console.log(
+          getSuiteCoreTranslation(SuiteCoreStringKey.Admin_ServingRoute) +
+            ': method=' +
+            req.method +
+            ' url=' +
+            req.protocol +
+            '://' +
+            req.hostname +
+            port +
+            (req.url || '').replace(/[\r\n]/g, ' '),
+        );
+        next();
+      });
+    }
+
+    app.use('/api', this.apiRouter.router);
+
+    app.set('views', this.viewsPath);
+    app.set('view engine', 'ejs');
+
+    // Serve static files from the React app build directory (validated in constructor)
+    app.use('/assets', expressStatic(this.assetsDir));
+    const serveStaticWithLogging = expressStatic(this.reactDistDir);
+    app.use('/static/js', expressStatic(this.reactDistDir));
+    app.use((req, res, next) => {
+      if (req.url === '/') {
+        next();
+        return;
+      }
+      debugLog(
+        this.apiRouter.application.environment.debug,
+        'log',
+        `Trying to serve static for ${(req.url || '').replace(/[\r\n]/g, ' ')}`,
+      );
+      if (req.url.endsWith('.js')) {
+        res.type('application/javascript');
+      }
+      serveStaticWithLogging(req, res, (err) => {
+        if (err) {
+          const sanitizedErr =
+            err instanceof Error
+              ? err.message.replace(/[\r\n]/g, ' ')
+              : String(err).replace(/[\r\n]/g, ' ');
+          debugLog(
+            this.apiRouter.application.environment.debug,
+            'error',
+            'Error serving static file:',
+            sanitizedErr,
+          );
+          handleError(err, res, sendApiMessageResponse, next);
+          return;
+        }
+        next();
+      });
+    });
+
+    // The "catchall" handler: for any request that doesn't
+    // match one above, send back React's index.html file.
+    // app.get('*', (req, res) => {
+    //   res.sendFile(path.join(__dirname,'..', '..', '..', 'myapp-react', 'index.html'));
+    // });
+    this.registerAdditionalRenderHooks(app);
+
+    app.use((req: Request, res: Response, next: NextFunction) => {
+      this.renderIndex(req, res, next);
+    });
+  }
+}

package/src/routers/base.ts

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview Base router class providing common router functionality.
+ * All routers extend this class to access application context and Express router.
+ * @module routers/base
+ */
+
+import { Router } from 'express';
+import { IApplication } from '../interfaces/application';
+import type { PlatformID } from '@digitaldefiance/node-ecies-lib';
+
+/**
+ * Abstract base class for all routers in the application.
+ * Provides access to the Express router and application instance.
+ * @template TID Platform-specific ID type (Buffer, ObjectId, etc.)
+ * @template TApplication Application instance type
+ */
+export abstract class BaseRouter<
+  TID extends PlatformID = Buffer,
+  TApplication extends IApplication<TID> = IApplication<TID>,
+> {
+  /** Express router instance for registering routes */
+  public readonly router: Router;
+  /** Application instance providing access to services and configuration */
+  public readonly application: TApplication;
+
+  /**
+   * Creates a new base router instance.
+   * @param application Application instance
+   */
+  protected constructor(application: TApplication) {
+    this.application = application;
+    this.router = Router();
+  }
+}

package/src/routers/{index.d.ts → index.ts}

@@ -1,4 +1,3 @@
 export * from './api';
 export * from './app';
 export * from './base';
-//# sourceMappingURL=index.d.ts.map

package/src/routers/router-config.ts

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview Router configuration interface and defaults.
+ * Defines configuration options for router setup including static paths, view engine, and middleware.
+ * @module routers/router-config
+ */
+
+import { RequestHandler } from 'express';
+
+/**
+ * Configuration interface for router setup.
+ */
+export interface RouterConfig {
+  /** Array of static path configurations with prefix and directory */
+  staticPaths?: Array<{ prefix: string; directory: string }>;
+  /** View engine configuration with name and views path */
+  viewEngine?: { name: string; viewsPath: string };
+  /** Array of middleware functions to apply */
+  middleware?: RequestHandler[];
+  /** CORS configuration options */
+  cors?: {
+    /** Allowed origin(s) for CORS */
+    origin?: string | string[];
+    /** Whether to allow credentials */
+    credentials?: boolean;
+  };
+}
+
+/**
+ * Default router configuration with empty arrays.
+ */
+export const DefaultRouterConfig: RouterConfig = {
+  staticPaths: [],
+  middleware: [],
+};

package/src/routing/index.ts

@@ -0,0 +1 @@
+export * from './route-builder';

package/src/routing/route-builder.ts

@@ -0,0 +1,214 @@
+/**
+ * @fileoverview Route builder for fluent route configuration.
+ * Provides builder pattern for defining Express routes.
+ * @module routing/route-builder
+ */
+
+import { RequestHandler } from 'express';
+import { ValidationChain } from 'express-validator';
+import { z } from 'zod';
+
+/**
+ * Builder for constructing route configurations with fluent API.
+ * @template TLanguage - Language code type (defaults to string)
+ */
+export class RouteBuilder<TLanguage extends string = string> {
+  private config: {
+    method?: 'get' | 'post' | 'put' | 'delete' | 'patch';
+    path?: string;
+    handler?: RequestHandler;
+    auth?: boolean;
+    cryptoAuth?: boolean;
+    validation?: ValidationChain[] | ((lang: TLanguage) => ValidationChain[]);
+    schema?: z.ZodSchema;
+    middleware?: RequestHandler[];
+    transaction?: boolean;
+    transactionTimeout?: number;
+    rawJson?: boolean;
+  } = {};
+
+  /**
+   * Creates a new RouteBuilder instance.
+   * @template T - Language code type
+   * @returns {RouteBuilder<T>} New builder instance
+   */
+  static create<T extends string = string>(): RouteBuilder<T> {
+    return new RouteBuilder<T>();
+  }
+
+  /**
+   * Sets GET method and path.
+   * @param {string} path - Route path
+   * @returns {this} This builder for chaining
+   */
+  get(path: string): this {
+    this.config.method = 'get';
+    this.config.path = path;
+    return this;
+  }
+
+  /**
+   * Sets POST method and path.
+   * @param {string} path - Route path
+   * @returns {this} This builder for chaining
+   */
+  post(path: string): this {
+    this.config.method = 'post';
+    this.config.path = path;
+    return this;
+  }
+
+  /**
+   * Sets PUT method and path.
+   * @param {string} path - Route path
+   * @returns {this} This builder for chaining
+   */
+  put(path: string): this {
+    this.config.method = 'put';
+    this.config.path = path;
+    return this;
+  }
+
+  /**
+   * Sets DELETE method and path.
+   * @param {string} path - Route path
+   * @returns {this} This builder for chaining
+   */
+  delete(path: string): this {
+    this.config.method = 'delete';
+    this.config.path = path;
+    return this;
+  }
+
+  /**
+   * Sets PATCH method and path.
+   * @param {string} path - Route path
+   * @returns {this} This builder for chaining
+   */
+  patch(path: string): this {
+    this.config.method = 'patch';
+    this.config.path = path;
+    return this;
+  }
+
+  /**
+   * Enables authentication.
+   * @param {boolean} [enabled=true] - Whether to enable authentication
+   * @returns {this} This builder for chaining
+   */
+  auth(enabled = true): this {
+    this.config.auth = enabled;
+    return this;
+  }
+
+  /**
+   * Enables crypto authentication.
+   * @param {boolean} [enabled=true] - Whether to enable crypto authentication
+   * @returns {this} This builder for chaining
+   */
+  cryptoAuth(enabled = true): this {
+    this.config.cryptoAuth = enabled;
+    return this;
+  }
+
+  /**
+   * Sets validation chains.
+   * @param {ValidationChain[] | Function} validation - Validation chains or factory function
+   * @returns {this} This builder for chaining
+   */
+  validate(
+    validation: ValidationChain[] | ((lang: TLanguage) => ValidationChain[]),
+  ): this {
+    this.config.validation = validation;
+    return this;
+  }
+
+  /**
+   * Sets Zod schema for validation.
+   * @param {z.ZodSchema} schema - Zod schema
+   * @returns {this} This builder for chaining
+   */
+  schema(schema: z.ZodSchema): this {
+    this.config.schema = schema;
+    return this;
+  }
+
+  /**
+   * Adds middleware to the route.
+   * @param {...RequestHandler[]} middleware - Middleware functions
+   * @returns {this} This builder for chaining
+   */
+  use(...middleware: RequestHandler[]): this {
+    this.config.middleware = [...(this.config.middleware || []), ...middleware];
+    return this;
+  }
+
+  /**
+   * Enables transaction support.
+   * @param {boolean} [enabled=true] - Whether to enable transactions
+   * @param {number} [timeout] - Transaction timeout in milliseconds
+   * @returns {this} This builder for chaining
+   */
+  transaction(enabled = true, timeout?: number): this {
+    this.config.transaction = enabled;
+    if (timeout) this.config.transactionTimeout = timeout;
+    return this;
+  }
+
+  /**
+   * Enables raw JSON handling.
+   * @param {boolean} [enabled=true] - Whether to enable raw JSON
+   * @returns {this} This builder for chaining
+   */
+  rawJson(enabled = true): this {
+    this.config.rawJson = enabled;
+    return this;
+  }
+
+  /**
+   * Builds the route configuration with handler.
+   * @param {RequestHandler} handler - Route handler function
+   * @returns {RouteConfig<TLanguage>} Complete route configuration
+   * @throws {Error} If method or path not set
+   */
+  handle(handler: RequestHandler): RouteConfig<TLanguage> {
+    if (!this.config.method || !this.config.path) {
+      throw new Error('Method and path must be set before calling handle()');
+    }
+    return {
+      method: this.config.method,
+      path: this.config.path,
+      handler,
+      options: {
+        auth: this.config.auth,
+        cryptoAuth: this.config.cryptoAuth,
+        validation: this.config.validation,
+        schema: this.config.schema,
+        middleware: this.config.middleware,
+        transaction: this.config.transaction,
+        transactionTimeout: this.config.transactionTimeout,
+        rawJson: this.config.rawJson,
+      },
+    };
+  }
+}
+
+/**
+ * Route configuration interface.
+ * @template TLanguage - Language code type (defaults to string)
+ */
+export interface RouteConfig<TLanguage extends string = string> {
+  method: 'get' | 'post' | 'put' | 'delete' | 'patch';
+  path: string;
+  handler: RequestHandler;
+  options: {
+    auth?: boolean;
+    cryptoAuth?: boolean;
+    validation?: ValidationChain[] | ((lang: TLanguage) => ValidationChain[]);
+    schema?: z.ZodSchema;
+    middleware?: RequestHandler[];
+    transaction?: boolean;
+    transactionTimeout?: number;
+    rawJson?: boolean;
+  };
+}