adorn-api 1.1.12 → 1.1.14

package/examples/bearer-auth-swagger/index.ts

@@ -0,0 +1,20 @@
+import { createApp } from "./app";
+import { startExampleServer } from "../utils/start-server";
+
+async function start() {
+  const app = await createApp();
+  startExampleServer(app, {
+    name: "Bearer Auth Swagger Demo",
+    port: 3001,
+    extraLogs: [
+      (port) => `Swagger UI: http://localhost:${port}/docs`,
+      (port) => `OpenAPI JSON: http://localhost:${port}/openapi.json`,
+      () => "Try tokens in Swagger Authorize: user-token or admin-token"
+    ]
+  });
+}
+
+start().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/examples/bearer-auth-swagger/session.dtos.ts

@@ -0,0 +1,19 @@
+import { Dto, Field, t } from "../../src";
+
+@Dto({ description: "Authenticated user session returned by protected routes." })
+export class SessionDto {
+  @Field(t.string({ description: "User identifier." }))
+  id!: string;
+
+  @Field(t.array(t.string(), { description: "Roles granted to the bearer token." }))
+  roles!: string[];
+
+  @Field(t.string({ description: "Human-readable route result." }))
+  message!: string;
+}
+
+@Dto({ description: "Public health response." })
+export class PublicStatusDto {
+  @Field(t.string())
+  status!: string;
+}

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "adorn-api",
-  "version": "1.1.12",
+  "version": "1.1.14",
   "description": "Decorator-first web framework with OpenAPI 3.1 schema generation.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "pretest": "npm run build",
     "dev": "tsx examples/basic/index.ts",
     "test": "vitest run",
     "test:watch": "vitest",
+    "typecheck:tests": "tsc -p tsconfig.typecheck.json --noEmit",
     "example": "node scripts/run-example.js",
     "check": "tsc -p tsconfig.json --noEmit && npm test",
     "lint": "eslint . --ext .ts,.tsx,.js"

package/src/adapter/express/controllers.ts

@@ -1,8 +1,9 @@
 import type { Express, Request, Response, NextFunction } from "express";
-import type { Constructor } from "../../core/types";
-import type { SchemaSource } from "../../core/schema";
-import { getControllerMeta } from "../../core/metadata";
-import { isHttpError, type HttpError } from "../../core/errors";
+import type { Constructor } from "../../core/types";
+import type { SchemaSource } from "../../core/schema";
+import { getControllerMeta } from "../../core/metadata";
+import { assertRouteAuthorized, getRouteAuthMeta } from "../../core/auth";
+import { isHttpError, type HttpError } from "../../core/errors";
 import { isHttpResponse } from "../../core/response";
 import type { InputCoercionSetting, MultipartOptions, RequestContext, ValidationOptions } from "./types";
 import { createInputCoercer } from "./coercion";
@@ -25,13 +26,14 @@ import { ValidationErrors, isValidationErrors } from "../../core/validation-erro
  * @param inputCoercion - Input coercion setting
  * @param multipart - Multipart file upload configuration
  */
-export async function attachControllers(
-  app: Express,
-  controllers: Constructor[],
-  inputCoercion: InputCoercionSetting = "safe",
-  multipart?: boolean | MultipartOptions,
-  validation?: boolean | ValidationOptions
-): Promise<void> {
+export async function attachControllers(
+  app: Express,
+  controllers: Constructor[],
+  inputCoercion: InputCoercionSetting = "safe",
+  multipart?: boolean | MultipartOptions,
+  validation?: boolean | ValidationOptions,
+  auth?: { userProperty?: string }
+): Promise<void> {
   const multipartOptions = normalizeMultipartOptions(multipart);
   for (const controller of controllers) {
     const meta = getControllerMeta(controller);
@@ -68,13 +70,16 @@ export async function attachControllers(
         middlewares.push(createMultipartMiddleware(route.files!, multipartOptions));
       }
 
-      // Determine if validation is enabled for this route
-      const isValidationEnabled = validation !== false && (validation as ValidationOptions)?.enabled !== false;
-
-      // Main route handler
-      const routeHandler = async (req: Request, res: Response, next: NextFunction) => {
-        try {
-          const files = extractFiles(req);
+      // Determine if validation is enabled for this route
+      const isValidationEnabled = validation !== false && (validation as ValidationOptions)?.enabled !== false;
+      const authMeta = getRouteAuthMeta(controller, route.handlerName);
+
+      // Main route handler
+      const routeHandler = async (req: Request, res: Response, next: NextFunction) => {
+        try {
+          await assertRouteAuthorized(authMeta, req, auth);
+
+          const files = extractFiles(req);
 
           // Create context
           const ctx = {

package/src/adapter/express/index.ts

@@ -4,6 +4,7 @@ import { attachCors } from "./cors";
 import { attachControllers } from "./controllers";
 import { attachOpenApi } from "./openapi";
 import { lifecycleRegistry } from "../../core/lifecycle";
+import { createBearerAuthMiddleware } from "../../core/auth";
 
 export * from "./types";
 export { attachCors } from "./cors";
@@ -23,8 +24,18 @@ export async function createExpressApp(options: ExpressAdapterOptions): Promise<
   if (options.jsonBody ?? true) {
     app.use(express.json({ limit: options.jsonLimit }));
   }
+  if (options.bearerAuth) {
+    app.use(createBearerAuthMiddleware(options.bearerAuth));
+  }
   const inputCoercion = options.inputCoercion ?? "safe";
-  await attachControllers(app, options.controllers, inputCoercion, options.multipart, options.validation);
+  await attachControllers(
+    app,
+    options.controllers,
+    inputCoercion,
+    options.multipart,
+    options.validation,
+    { userProperty: options.bearerAuth?.userProperty }
+  );
   if (options.openApi) {
     attachOpenApi(app, options.controllers, options.openApi);
   }

package/src/adapter/express/types.ts

@@ -1,9 +1,10 @@
-import type {
-  Constructor,
-  RequestContext as CoreRequestContext,
-  UploadedFileInfo
-} from "../../core/types";
-import type { OpenApiInfo, OpenApiServer } from "../../core/openapi";
+import type {
+  Constructor,
+  RequestContext as CoreRequestContext,
+  UploadedFileInfo
+} from "../../core/types";
+import type { OpenApiInfo, OpenApiServer } from "../../core/openapi";
+import type { BearerAuthOptions } from "../../core/auth";
 
 export { UploadedFileInfo };
 
@@ -112,10 +113,12 @@ export interface ExpressAdapterOptions {
   openApi?: OpenApiExpressOptions;
   /** Input coercion setting */
   inputCoercion?: InputCoercionSetting;
-  /** CORS configuration. Set to true for permissive defaults, or provide options. */
-  cors?: boolean | CorsOptions;
-  /** Multipart file upload configuration. Set to true for defaults, or provide options. */
-  multipart?: boolean | MultipartOptions;
+  /** CORS configuration. Set to true for permissive defaults, or provide options. */
+  cors?: boolean | CorsOptions;
+  /** Built-in bearer token authentication for protected routes. */
+  bearerAuth?: BearerAuthOptions;
+  /** Multipart file upload configuration. Set to true for defaults, or provide options. */
+  multipart?: boolean | MultipartOptions;
   /** Validation configuration. Set to false to disable validation, or provide options. */
   validation?: boolean | ValidationOptions;
 }

package/src/adapter/fastify/controllers.ts

@@ -1,9 +1,9 @@
 import type { FastifyInstance, FastifyRequest, FastifyReply } from "fastify";
-import type { Constructor, RequestContext } from "../../core/types";
-import type { SchemaSource } from "../../core/schema";
-import { getControllerMeta } from "../../core/metadata";
-import { getRouteAuthMeta } from "../../core/auth";
-import { isHttpError, HttpError } from "../../core/errors";
+import type { Constructor, RequestContext } from "../../core/types";
+import type { SchemaSource } from "../../core/schema";
+import { getControllerMeta } from "../../core/metadata";
+import { assertRouteAuthorized, getRouteAuthMeta } from "../../core/auth";
+import { isHttpError } from "../../core/errors";
 import { isHttpResponse } from "../../core/response";
 import type { InputCoercionSetting, MultipartOptions, ValidationOptions } from "./types";
 import { createInputCoercer } from "./coercion";
@@ -21,13 +21,14 @@ import { ValidationErrors, isValidationErrors } from "../../core/validation-erro
 /**
  * Attaches controllers to a Fastify application.
  */
-export async function attachControllers(
-  app: FastifyInstance,
-  controllers: Constructor[],
-  inputCoercion: InputCoercionSetting = "safe",
-  multipart?: boolean | MultipartOptions,
-  validation?: boolean | ValidationOptions
-): Promise<void> {
+export async function attachControllers(
+  app: FastifyInstance,
+  controllers: Constructor[],
+  inputCoercion: InputCoercionSetting = "safe",
+  multipart?: boolean | MultipartOptions,
+  validation?: boolean | ValidationOptions,
+  auth?: { userProperty?: string }
+): Promise<void> {
   const multipartOptions = normalizeMultipartOptions(multipart);
 
   for (const controller of controllers) {
@@ -68,35 +69,9 @@ export async function attachControllers(
         method: route.httpMethod.toUpperCase() as any,
         url: path,
         handler: async (req: FastifyRequest, reply: FastifyReply) => {
-          try {
-            // Apply auth guard if metadata exists
-            if (authMeta && authMeta.requiresAuth && !authMeta.isPublic) {
-              const user = (req as any).user || (req.raw as any).user;
-              if (!user) {
-                throw new HttpError(401, "Unauthorized");
-              }
-
-              if (authMeta.roles?.length) {
-                const hasRole = authMeta.roles.some((role: string) => user.roles?.includes(role));
-                if (!hasRole) {
-                  throw new HttpError(403, "Insufficient permissions");
-                }
-              }
-
-              if (authMeta.allRoles?.length) {
-                const hasAllRoles = authMeta.allRoles.every((role: string) => user.roles?.includes(role));
-                if (!hasAllRoles) {
-                  throw new HttpError(403, "Insufficient permissions");
-                }
-              }
-
-              if (authMeta.guard) {
-                const allowed = await authMeta.guard(user, req);
-                if (!allowed) {
-                  throw new HttpError(403, "Access denied by guard");
-                }
-              }
-            }
+          try {
+            // Apply auth guard if metadata exists
+            await assertRouteAuthorized(authMeta, req, auth);
 
             let files: any = undefined;
             if (multipartOptions && hasFileUploads(route.files)) {

package/src/adapter/fastify/index.ts

@@ -2,9 +2,10 @@ import fastify from "fastify";
 import type { FastifyAdapterOptions } from "./types";
 import { attachControllers } from "./controllers";
 import { attachOpenApi } from "./openapi";
-import { lifecycleRegistry } from "../../core/lifecycle";
-import cors from "@fastify/cors";
-import multipart from "@fastify/multipart";
+import { lifecycleRegistry } from "../../core/lifecycle";
+import { authenticateBearerRequest } from "../../core/auth";
+import cors from "@fastify/cors";
+import multipart from "@fastify/multipart";
 
 export * from "./types";
 export { attachControllers } from "./controllers";
@@ -24,16 +25,29 @@ export async function createFastifyApp(options: FastifyAdapterOptions): Promise<
     app.register(cors, options.cors === true ? {} : options.cors);
   }
 
-  if (options.multipart) {
-    app.register(multipart, {
-      limits: {
-        fileSize: typeof options.multipart === "object" ? options.multipart.maxFileSize : undefined
-      }
-    });
-  }
-
-  const inputCoercion = options.inputCoercion ?? "safe";
-  await attachControllers(app, options.controllers, inputCoercion, options.multipart, options.validation);
+  if (options.multipart) {
+    app.register(multipart, {
+      limits: {
+        fileSize: typeof options.multipart === "object" ? options.multipart.maxFileSize : undefined
+      }
+    });
+  }
+
+  if (options.bearerAuth) {
+    app.addHook("preHandler", async (req) => {
+      await authenticateBearerRequest(req, options.bearerAuth!);
+    });
+  }
+
+  const inputCoercion = options.inputCoercion ?? "safe";
+  await attachControllers(
+    app,
+    options.controllers,
+    inputCoercion,
+    options.multipart,
+    options.validation,
+    { userProperty: options.bearerAuth?.userProperty }
+  );
 
   if (options.openApi) {
     attachOpenApi(app, options.controllers, options.openApi);

package/src/adapter/fastify/types.ts

@@ -1,9 +1,10 @@
-import type {
-  Constructor,
-  RequestContext as CoreRequestContext,
-  UploadedFileInfo
-} from "../../core/types";
-import type { OpenApiInfo, OpenApiServer } from "../../core/openapi";
+import type {
+  Constructor,
+  RequestContext as CoreRequestContext,
+  UploadedFileInfo
+} from "../../core/types";
+import type { OpenApiInfo, OpenApiServer } from "../../core/openapi";
+import type { BearerAuthOptions } from "../../core/auth";
 
 /**
  * Request context provided to Fastify route handlers.
@@ -110,10 +111,12 @@ export interface FastifyAdapterOptions {
   openApi?: OpenApiFastifyOptions;
   /** Input coercion setting */
   inputCoercion?: InputCoercionSetting;
-  /** CORS configuration. Set to true for permissive defaults, or provide options. */
-  cors?: boolean | CorsOptions;
-  /** Multipart file upload configuration. Set to true for defaults, or provide options. */
-  multipart?: boolean | MultipartOptions;
+  /** CORS configuration. Set to true for permissive defaults, or provide options. */
+  cors?: boolean | CorsOptions;
+  /** Built-in bearer token authentication for protected routes. */
+  bearerAuth?: BearerAuthOptions;
+  /** Multipart file upload configuration. Set to true for defaults, or provide options. */
+  multipart?: boolean | MultipartOptions;
   /** Validation configuration. Set to false to disable validation, or provide options. */
   validation?: boolean | ValidationOptions;
 }

package/src/adapter/metal-orm/index.ts

@@ -78,6 +78,7 @@ export type {
   PaginationConfig,
   PaginationOptions,
   ParsedPagination,
+  PaginationQueryParams,
   Filter,
   FilterMapping,
   FilterFieldMapping,
@@ -89,6 +90,8 @@ export type {
   ParseSortOptions,
   ParsedSort,
   SortDirection,
+  SortingQueryParams,
+  PagedQueryParams,
   CrudListSortTerm,
   RunPagedListOptions,
   ExecuteCrudListOptions,

package/src/adapter/metal-orm/types.ts

@@ -74,6 +74,16 @@ export interface ParsedPagination {
   pageSize: number;
 }
 
+/**
+ * Pagination query params for consumer-side TypeScript interfaces.
+ */
+export interface PaginationQueryParams {
+  /** Page number */
+  page?: number;
+  /** Page size */
+  pageSize?: number;
+}
+
 /**
  * Filter field mapping.
  */
@@ -155,6 +165,21 @@ export interface ParseFilterOptions<T = Record<string, unknown>> {
  */
 export type SortDirection = "asc" | "desc";
 
+/**
+ * Sorting query params for consumer-side TypeScript interfaces.
+ */
+export interface SortingQueryParams {
+  /** Requested sort key */
+  sortBy?: string;
+  /** Sort direction */
+  sortDirection?: SortDirection;
+}
+
+/**
+ * Combined pagination + sorting query params.
+ */
+export interface PagedQueryParams extends PaginationQueryParams, SortingQueryParams {}
+
 /**
  * Sort parsing options.
  */

package/src/adapter/native/controllers.ts

@@ -1,9 +1,9 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
-import type { Constructor, RequestContext } from "../../core/types";
-import type { SchemaSource } from "../../core/schema";
-import { getControllerMeta } from "../../core/metadata";
-import { getRouteAuthMeta } from "../../core/auth";
-import { isHttpError, HttpError } from "../../core/errors";
+import type { Constructor, RequestContext } from "../../core/types";
+import type { SchemaSource } from "../../core/schema";
+import { getControllerMeta } from "../../core/metadata";
+import { assertRouteAuthorized, getRouteAuthMeta } from "../../core/auth";
+import { isHttpError } from "../../core/errors";
 import { isHttpResponse } from "../../core/response";
 import type { InputCoercionSetting, ValidationOptions, RequestContext as NativeRequestContext } from "./types";
 import { createInputCoercer } from "./coercion";
@@ -45,13 +45,14 @@ export async function dispatchRequest(
   match: any,
   options: {
     inputCoercion: InputCoercionSetting;
-    validation?: boolean | ValidationOptions;
-    body?: any;
-    query?: Record<string, any>;
-  }
-): Promise<void> {
-  const { controller: instance, route, params: rawParams } = match;
-  const { inputCoercion, validation, body: rawBody, query: rawQuery } = options;
+    validation?: boolean | ValidationOptions;
+    body?: any;
+    query?: Record<string, any>;
+    auth?: { userProperty?: string };
+  }
+): Promise<void> {
+  const { controller: instance, route, params: rawParams } = match;
+  const { inputCoercion, validation, body: rawBody, query: rawQuery, auth } = options;
 
   const handler = instance[route.handlerName];
   if (typeof handler !== "function") {
@@ -75,35 +76,9 @@ export async function dispatchRequest(
 
   const authMeta = getRouteAuthMeta(instance.constructor as Constructor, route.handlerName);
 
-  try {
-    // Apply auth guard if metadata exists
-    if (authMeta && authMeta.requiresAuth && !authMeta.isPublic) {
-      const user = (req as any).user;
-      if (!user) {
-        throw new HttpError(401, "Unauthorized");
-      }
-
-      if (authMeta.roles?.length) {
-        const hasRole = authMeta.roles.some((role: string) => user.roles?.includes(role));
-        if (!hasRole) {
-          throw new HttpError(403, "Insufficient permissions");
-        }
-      }
-
-      if (authMeta.allRoles?.length) {
-        const hasAllRoles = authMeta.allRoles.every((role: string) => user.roles?.includes(role));
-        if (!hasAllRoles) {
-          throw new HttpError(403, "Insufficient permissions");
-        }
-      }
-
-      if (authMeta.guard) {
-        const allowed = await authMeta.guard(user, req);
-        if (!allowed) {
-          throw new HttpError(403, "Access denied by guard");
-        }
-      }
-    }
+  try {
+    // Apply auth guard if metadata exists
+    await assertRouteAuthorized(authMeta, req, auth);
 
     const body = (coerceBody && rawBody) ? coerceBody(rawBody) : rawBody;
     const query = (coerceQuery && rawQuery) ? coerceQuery(rawQuery) : rawQuery;

package/src/adapter/native/index.ts

@@ -1,9 +1,10 @@
 import { createServer, IncomingMessage, ServerResponse } from "node:http";
 import type { NativeAdapterOptions, NativeApp } from "./types";
 import { registerControllers, dispatchRequest } from "./controllers";
-import { registerOpenApi } from "./openapi";
-import { lifecycleRegistry } from "../../core/lifecycle";
-import { Router } from "./router";
+import { registerOpenApi } from "./openapi";
+import { lifecycleRegistry } from "../../core/lifecycle";
+import { authenticateBearerRequest } from "../../core/auth";
+import { Router } from "./router";
 
 export * from "./types";
 export { registerControllers as attachControllers } from "./controllers";
@@ -28,12 +29,23 @@ export async function createNativeApp(options: NativeAdapterOptions): Promise<Na
     const url = new URL(req.url || "/", `http://${req.headers.host || "localhost"}`);
     const match = router.match(req.method || "GET", url.pathname);
 
-    if (!match) {
-      res.statusCode = 404;
-      res.setHeader("Content-Type", "application/json");
-      res.end(JSON.stringify({ message: `Not Found: ${req.method} ${url.pathname}` }));
-      return;
-    }
+    if (!match) {
+      res.statusCode = 404;
+      res.setHeader("Content-Type", "application/json");
+      res.end(JSON.stringify({ message: `Not Found: ${req.method} ${url.pathname}` }));
+      return;
+    }
+
+    if (options.bearerAuth) {
+      try {
+        await authenticateBearerRequest(req, options.bearerAuth);
+      } catch {
+        res.statusCode = 500;
+        res.setHeader("Content-Type", "application/json");
+        res.end(JSON.stringify({ message: "Internal server error" }));
+        return;
+      }
+    }
 
     const query: Record<string, any> = {};
     url.searchParams.forEach((value, key) => {
@@ -60,12 +72,13 @@ export async function createNativeApp(options: NativeAdapterOptions): Promise<Na
       }
     }
 
-    await dispatchRequest(req, res, match, {
-      inputCoercion,
-      validation: options.validation,
-      body,
-      query
-    });
+    await dispatchRequest(req, res, match, {
+      inputCoercion,
+      validation: options.validation,
+      body,
+      query,
+      auth: { userProperty: options.bearerAuth?.userProperty }
+    });
   };
 
   await lifecycleRegistry.callOnApplicationBootstrap();

package/src/adapter/native/types.ts

@@ -1,10 +1,11 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
-import type {
-  Constructor,
-  RequestContext as CoreRequestContext,
-  UploadedFileInfo
-} from "../../core/types";
-import type { OpenApiInfo, OpenApiServer } from "../../core/openapi";
+import type {
+  Constructor,
+  RequestContext as CoreRequestContext,
+  UploadedFileInfo
+} from "../../core/types";
+import type { OpenApiInfo, OpenApiServer } from "../../core/openapi";
+import type { BearerAuthOptions } from "../../core/auth";
 
 export { UploadedFileInfo };
 
@@ -79,10 +80,12 @@ export interface NativeAdapterOptions {
   bodyLimit?: number;
   /** OpenAPI configuration */
   openApi?: OpenApiNativeOptions;
-  /** Input coercion setting */
-  inputCoercion?: InputCoercionSetting;
-  /** Validation configuration. Set to false to disable validation, or provide options. */
-  validation?: boolean | ValidationOptions;
+  /** Input coercion setting */
+  inputCoercion?: InputCoercionSetting;
+  /** Built-in bearer token authentication for protected routes. */
+  bearerAuth?: BearerAuthOptions;
+  /** Validation configuration. Set to false to disable validation, or provide options. */
+  validation?: boolean | ValidationOptions;
 }
 
 /**