Middleware

Apply auth, permission, and audit middleware on controllers — register plugin-wide filters with @Module globalFilter / globalExceptionsFilter — or build your own with @Middleware.

Usage

Decorate a controller class (all routes) or a single method. Stack middlewares in the order they should run — auth before permission is typical for admin APIs. For every request across the app, use globalFilter on the root @Module instead.

TSXusage

import {
  AuditLogMiddleware,
  AuthenticatedUserOnly,
  CheckAPIPermission,
  Controller,
  Get,
  ResponseDto,
} from "@quan-erp/shared-backend-core";

@Controller("/admin-dashboard")
export class AdminDashboardController {
  @Get("/stats")
  @AuthenticatedUserOnly()
  @CheckAPIPermission()
  @AuditLogMiddleware((req) => `View stats`)
  async getStats() {
    return ResponseDto.ok(data);
  }
}

Builtin middleware

@AuthenticatedUserOnly() — reject unauthenticated callers with 401; use on any logged-in endpoint
@CheckAPIPermission() — check the user’s role against allowed APIs for the current method + URL; pair with @AuthenticatedUserOnly on admin routes
@AuditLogMiddleware(action) — static string or (req) => string for audit trail entries on sensitive actions

TSXaudit

import {
  AuditLogMiddleware,
  Controller,
  Get,
  Put,
} from "@quan-erp/shared-backend-core";

@Controller("/branch")
export class BranchController {
  @AuditLogMiddleware("View all branches")
  @Get("/")
  async getAll() { /* … */ }

  @AuditLogMiddleware((req) => `Update branch ${req.params.id}`)
  @Put("/:id")
  async update() { /* … */ }
}

Global middleware (module)

Register filters on the root @Module so they run for every request (not just one controller). Use globalFilter for request middleware and globalExceptionsFilter for error handlers. Core unregisters them when the plugin is uninstalled.

globalFilter: { position, handler }[] — app-wide request middleware
globalExceptionsFilter: handler[] — app-wide exception middleware (IExceptionMiddleware)
MiddlewarePosition.BEFORE_ROOT_ROUTE — run before plugin root routes (typical for auth / resolve-user / logging)
MiddlewarePosition.AFTER_ROOT_ROUTE — run after the root stack
Handler — Express RequestHandler or a class implementing IExpressMiddleware / IExceptionMiddleware
Required on every class middleware: @MiddlewareMetadata({ plugin: metadata.name })

TSXglobalFilter on @Module

import {
  MiddlewareMetadata,
  MiddlewarePosition,
  Module,
} from "@quan-erp/shared-backend-core";
import type {
  IExceptionMiddleware,
  IExpressMiddleware,
} from "@quan-erp/shared-backend-core";
import type { NextFunction, Request, Response } from "express";
import metadata from "../../module.metadata.json" with { type: "json" };
import { MyController } from "./my.controller.js";
import { MyService } from "./my.service.js";

@MiddlewareMetadata({ plugin: metadata.name })
export class RequestIdMiddleware implements IExpressMiddleware {
  handler(req: Request, res: Response, next: NextFunction) {
    res.setHeader("x-request-plugin", metadata.name);
    return next();
  }
}

@MiddlewareMetadata({ plugin: metadata.name })
export class PluginErrorFilter implements IExceptionMiddleware {
  handler(error: Error, req: Request, res: Response, next: NextFunction) {
    if (res.headersSent) return next(error);
    res.status(500).json({ message: error.message });
  }
}

@Module({
  name: metadata.name,
  providers: [MyService],
  controllers: [MyController],
  entities: [],
  globalFilter: [
    {
      position: MiddlewarePosition.BEFORE_ROOT_ROUTE,
      handler: RequestIdMiddleware,
    },
  ],
  globalExceptionsFilter: [PluginErrorFilter],
})
export class MyPluginModule {}

Creating custom middleware

Wrap logic with Middleware(...) as a decorator for controller/method scope, or implement IExpressMiddleware / IExceptionMiddleware for DI-aware handlers (also used in globalFilter). Every class middleware MUST declare @MiddlewareMetadata({ plugin: metadata.name }) so the core resolves it in the correct plugin DI scope. Apply route middleware with @MyDecorator() or @Middleware(MyClass).

Required: @MiddlewareMetadata({ plugin: metadata.name }) on every class that implements IExpressMiddleware / IExceptionMiddleware
Decorator-based — return Middleware(async (req, res, next) => { … }) from a factory (no MiddlewareMetadata — function handlers)
Class-based (IExpressMiddleware) — handler(req, res, next); @Inject works without @Service()
Exception middleware (IExceptionMiddleware) — handler(error, req, res, next)
Keep middleware focused; put business rules in services when possible

TSXdecorator middleware

import {
  HttpStatus,
  Middleware,
  ResponseDto,
} from "@quan-erp/shared-backend-core";

export function MyCustomAuth(): MethodDecorator & ClassDecorator {
  return Middleware(async (req, res, next) => {
    if (req.headers["x-custom-header"] === "secret-value") return next();
    return res
      .status(HttpStatus.UNAUTHORIZED)
      .json(ResponseDto.error("Unauthorized", HttpStatus.UNAUTHORIZED));
  });
}

TSXclass middleware

import type { NextFunction, Request, Response } from "express";
import {
  Controller,
  Inject,
  Middleware,
  MiddlewareMetadata,
} from "@quan-erp/shared-backend-core";
import type { IExpressMiddleware } from "@quan-erp/shared-backend-core";
import metadata from "../../module.metadata.json" with { type: "json" };
import { MyService } from "./my.service.js";

@MiddlewareMetadata({ plugin: metadata.name })
export class MyComplexMiddleware implements IExpressMiddleware {
  @Inject(MyService)
  private myService: MyService;

  async handler(req: Request, res: Response, next: NextFunction) {
    if (await this.myService.validate(req.body)) return next();
    res.status(400).send("Invalid request");
  }
}

@Middleware(MyComplexMiddleware)
@Controller("/complex")
export class ComplexController {}