@digitaldefiance/node-express-suite 3.6.20 → 3.6.21

package/src/registry/email-service-registry.ts

@@ -0,0 +1,53 @@
+import {
+  SuiteCoreStringKey,
+  TranslatableSuiteError,
+} from '@digitaldefiance/suite-core-lib';
+import { IEmailService } from '../interfaces/email-service';
+
+class EmailServiceRegistry {
+  private service?: IEmailService;
+
+  setService(service: IEmailService): void {
+    this.service = service;
+  }
+
+  getService(): IEmailService {
+    if (!this.service) {
+      throw new TranslatableSuiteError(
+        SuiteCoreStringKey.Error_EmailService_NotConfigured,
+      );
+    }
+    return this.service;
+  }
+
+  /**
+   * Check if any email service is registered
+   */
+  hasService(): boolean {
+    return this.service !== undefined;
+  }
+
+  /**
+   * Check if the registered service is an instance of a specific class
+   * @param serviceClass The class/constructor to check against
+   * @returns true if the registered service is an instance of the given class
+   * @example
+   * emailServiceRegistry.isServiceType(EmailService) // true if EmailService is registered
+   * emailServiceRegistry.isServiceType(DummyEmailService) // true if DummyEmailService is registered
+   */
+  isServiceType<T extends IEmailService>(
+    serviceClass: new (...args: any[]) => T,
+  ): boolean {
+    return this.service !== undefined && this.service instanceof serviceClass;
+  }
+
+  /**
+   * Get the constructor name of the registered service
+   * @returns The name of the service class, or undefined if no service is registered
+   */
+  getServiceTypeName(): string | undefined {
+    return this.service?.constructor.name;
+  }
+}
+
+export const emailServiceRegistry = new EmailServiceRegistry();

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

@@ -1,2 +1 @@
 export { emailServiceRegistry } from './email-service-registry';
-//# sourceMappingURL=index.d.ts.map

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

@@ -1,2 +1 @@
 export * from './response-builder';
-//# sourceMappingURL=index.d.ts.map

package/src/responses/response-builder.ts

@@ -0,0 +1,86 @@
+import { CoreLanguageCode } from '@digitaldefiance/i18n-lib';
+import {
+  getSuiteCoreTranslation,
+  SuiteCoreStringKey,
+} from '@digitaldefiance/suite-core-lib';
+import { IStatusCodeResponse } from '../interfaces';
+import { ApiResponse } from '../types';
+
+export class ResponseBuilder<T extends ApiResponse = ApiResponse> {
+  private statusCode: number = 200;
+  private responseData: Partial<T> = {};
+  private responseHeaders?: Record<string, string>;
+
+  static ok<T extends ApiResponse = ApiResponse>(): ResponseBuilder<T> {
+    return new ResponseBuilder<T>().status(200);
+  }
+
+  static created<T extends ApiResponse = ApiResponse>(): ResponseBuilder<T> {
+    return new ResponseBuilder<T>().status(201);
+  }
+
+  static accepted<T extends ApiResponse = ApiResponse>(): ResponseBuilder<T> {
+    return new ResponseBuilder<T>().status(202);
+  }
+
+  static noContent(): ResponseBuilder<ApiResponse> {
+    return new ResponseBuilder<ApiResponse>().status(204);
+  }
+
+  static badRequest<T extends ApiResponse = ApiResponse>(): ResponseBuilder<T> {
+    return new ResponseBuilder<T>().status(400);
+  }
+
+  static unauthorized<
+    T extends ApiResponse = ApiResponse,
+  >(): ResponseBuilder<T> {
+    return new ResponseBuilder<T>().status(401);
+  }
+
+  static forbidden<T extends ApiResponse = ApiResponse>(): ResponseBuilder<T> {
+    return new ResponseBuilder<T>().status(403);
+  }
+
+  static notFound<T extends ApiResponse = ApiResponse>(): ResponseBuilder<T> {
+    return new ResponseBuilder<T>().status(404);
+  }
+
+  static error<T extends ApiResponse = ApiResponse>(): ResponseBuilder<T> {
+    return new ResponseBuilder<T>().status(500);
+  }
+
+  status(code: number): this {
+    this.statusCode = code;
+    return this;
+  }
+
+  message(
+    key: SuiteCoreStringKey,
+    params?: Record<string, string>,
+    language?: string,
+  ): this {
+    (this.responseData as T & { message?: string }).message =
+      getSuiteCoreTranslation(key, params, language as CoreLanguageCode);
+    return this;
+  }
+
+  data(data: Partial<T>): this {
+    this.responseData = { ...this.responseData, ...data };
+    return this;
+  }
+
+  headers(headers: Record<string, string>): this {
+    this.responseHeaders = headers;
+    return this;
+  }
+
+  build(): IStatusCodeResponse<T> {
+    return {
+      statusCode: this.statusCode,
+      response: this.responseData as T,
+      ...(this.responseHeaders ? { headers: this.responseHeaders } : {}),
+    };
+  }
+}
+
+export const Response = ResponseBuilder;

package/src/routers/api.ts

@@ -0,0 +1,196 @@
+import { IECIESConfig } from '@digitaldefiance/ecies-lib';
+import { Types } from '@digitaldefiance/mongoose-types';
+import { ECIESService } from '@digitaldefiance/node-ecies-lib';
+import {
+  ITokenRole,
+  ITokenUser,
+  IUserBase,
+} from '@digitaldefiance/suite-core-lib';
+import { ServiceKeys } from '../container';
+import { UserController } from '../controllers/user';
+import { IBaseDocument } from '../documents';
+import { Environment } from '../environment';
+import { IConstants } from '../interfaces';
+import { IApplication } from '../interfaces/application';
+import { IEmailService } from '../interfaces/email-service';
+import { emailServiceRegistry } from '../registry';
+import { BackupCodeService } from '../services/backup-code';
+import { JwtService } from '../services/jwt';
+import { KeyWrappingService } from '../services/key-wrapping';
+import { RoleService } from '../services/role';
+import { UserService } from '../services/user';
+import { BaseRouter } from './base';
+
+/**
+ * Router for the API
+ */
+export class ApiRouter<
+  I extends Types.ObjectId | string,
+  D extends Date,
+  S extends string,
+  A extends string,
+  TUser extends IUserBase<I, D, S, A> = IUserBase<I, D, S, A>,
+  TTokenRole extends ITokenRole<I, D> = ITokenRole<I, D>,
+  TBaseDocument extends IBaseDocument<any, Types.ObjectId> = IBaseDocument<
+    any,
+    Types.ObjectId
+  >,
+  TTokenUser extends ITokenUser = ITokenUser,
+  TConstants extends IConstants = IConstants,
+  TEnvironment extends Environment = Environment,
+  TApplication extends IApplication = IApplication,
+> extends BaseRouter<TApplication> {
+  private readonly userController: UserController<
+    I,
+    D,
+    S,
+    A,
+    TUser,
+    TTokenRole,
+    TTokenUser,
+    TApplication
+  >;
+  private readonly jwtService: JwtService<
+    I,
+    D,
+    TTokenRole,
+    TTokenUser,
+    TApplication
+  >;
+  private readonly emailService: IEmailService;
+  private readonly userService: UserService<
+    any,
+    I,
+    D,
+    S,
+    A,
+    TEnvironment,
+    TConstants,
+    TBaseDocument,
+    TUser,
+    TTokenRole,
+    TApplication
+  >;
+  private readonly roleService: RoleService<I, D, TTokenRole>;
+  private readonly keyWrappingService: KeyWrappingService;
+  private readonly eciesService: ECIESService;
+  private readonly backupCodeService: BackupCodeService<
+    I,
+    D,
+    TTokenRole,
+    TApplication
+  >;
+  /**
+   * Constructor for the API router
+   * @param connection The mongoose connection
+   * @param getModel The function to get a mongoose model by name
+   */
+  constructor(application: TApplication) {
+    super(application);
+    this.registerServices();
+    this.jwtService = application.services.get(ServiceKeys.JWT);
+    this.roleService = application.services.get(ServiceKeys.ROLE);
+    this.emailService = application.services.get(ServiceKeys.EMAIL);
+    this.keyWrappingService = application.services.get(
+      ServiceKeys.KEY_WRAPPING,
+    );
+    this.eciesService = application.services.get(ServiceKeys.ECIES);
+    this.backupCodeService = application.services.get(ServiceKeys.BACKUP_CODE);
+    this.userService = application.services.get(ServiceKeys.USER);
+    this.userController = new UserController<
+      I,
+      D,
+      S,
+      A,
+      TUser,
+      TTokenRole,
+      TTokenUser,
+      TApplication
+    >(
+      application,
+      this.jwtService,
+      this.userService,
+      this.backupCodeService,
+      this.roleService,
+      this.eciesService,
+    );
+    this.router.use('/user', this.userController.router);
+  }
+
+  private registerServices(): void {
+    const app = this.application;
+
+    if (!app.services.has(ServiceKeys.JWT)) {
+      app.services.register(ServiceKeys.JWT, () => new JwtService(app));
+    }
+    if (!app.services.has(ServiceKeys.ROLE)) {
+      app.services.register(
+        ServiceKeys.ROLE,
+        () => new RoleService<I, D, TTokenRole>(app),
+      );
+    }
+    if (!app.services.has(ServiceKeys.EMAIL)) {
+      app.services.register(ServiceKeys.EMAIL, () =>
+        emailServiceRegistry.getService(),
+      );
+    }
+    if (!app.services.has(ServiceKeys.KEY_WRAPPING)) {
+      app.services.register(
+        ServiceKeys.KEY_WRAPPING,
+        () => new KeyWrappingService(),
+      );
+    }
+    if (!app.services.has(ServiceKeys.ECIES)) {
+      app.services.register(ServiceKeys.ECIES, () => {
+        const config: IECIESConfig = {
+          curveName: app.constants.ECIES.CURVE_NAME,
+          primaryKeyDerivationPath:
+            app.constants.ECIES.PRIMARY_KEY_DERIVATION_PATH,
+          mnemonicStrength: app.constants.ECIES.MNEMONIC_STRENGTH,
+          symmetricAlgorithm:
+            app.constants.ECIES.SYMMETRIC_ALGORITHM_CONFIGURATION,
+          symmetricKeyBits: app.constants.ECIES.SYMMETRIC.KEY_BITS,
+          symmetricKeyMode: app.constants.ECIES.SYMMETRIC.MODE,
+        };
+        return new ECIESService(config);
+      });
+    }
+    if (!app.services.has(ServiceKeys.BACKUP_CODE)) {
+      app.services.register(
+        ServiceKeys.BACKUP_CODE,
+        () =>
+          new BackupCodeService<I, D, TTokenRole, TApplication>(
+            app,
+            app.services.get(ServiceKeys.ECIES),
+            app.services.get(ServiceKeys.KEY_WRAPPING),
+            app.services.get(ServiceKeys.ROLE),
+          ),
+      );
+    }
+    if (!app.services.has(ServiceKeys.USER)) {
+      app.services.register(
+        ServiceKeys.USER,
+        () =>
+          new UserService<
+            any,
+            I,
+            D,
+            S,
+            A,
+            TEnvironment,
+            TConstants,
+            TBaseDocument,
+            TUser,
+            TTokenRole,
+            TApplication
+          >(
+            app,
+            app.services.get(ServiceKeys.ROLE),
+            app.services.get(ServiceKeys.EMAIL),
+            app.services.get(ServiceKeys.KEY_WRAPPING),
+            app.services.get(ServiceKeys.BACKUP_CODE),
+          ),
+      );
+    }
+  }
+}

package/src/routers/app.ts

@@ -0,0 +1,333 @@
+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';
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+function keepEJS() {
+  ejs.compile(''); // Compile an empty string, doesn't generate anything meaningful
+}
+
+/**
+ * Application router
+ * Sets up the API and static file serving
+ */
+export class AppRouter<TApplication extends IApplication = IApplication> {
+  protected readonly viewsPath: string;
+  protected readonly indexPath: string;
+  protected readonly assetsDir: string;
+  protected readonly reactDistDir: string;
+
+  protected readonly apiRouter: BaseRouter<TApplication>;
+  protected readonly application: TApplication;
+
+  constructor(apiRouter: BaseRouter<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;
+  }
+
+  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;
+    }
+  }
+
+  // Allow subclasses to register additional catch-all handlers before rendering the index page.
+  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,
+    };
+  }
+
+  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);
+    });
+  }
+
+  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.
+   */
+  protected registerAdditionalRenderHooks(app: Application): void {
+    void app;
+  }
+
+  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);
+  }
+
+  /**
+   * Initialize the application router
+   * @param app Express application
+   * @param debugRoutes Whether to log routes
+   */
+  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,13 @@
+import { Router } from 'express';
+import { IApplication } from '../interfaces/application';
+
+export abstract class BaseRouter<
+  TApplication extends IApplication = IApplication,
+> {
+  public readonly router: Router;
+  public readonly application: TApplication;
+  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