adorn-api 1.1.13 → 1.1.14

package/dist/adapter/express/controllers.d.ts

@@ -8,4 +8,6 @@ import type { InputCoercionSetting, MultipartOptions, ValidationOptions } from "
  * @param inputCoercion - Input coercion setting
  * @param multipart - Multipart file upload configuration
  */
-export declare function attachControllers(app: Express, controllers: Constructor[], inputCoercion?: InputCoercionSetting, multipart?: boolean | MultipartOptions, validation?: boolean | ValidationOptions): Promise<void>;
+export declare function attachControllers(app: Express, controllers: Constructor[], inputCoercion?: InputCoercionSetting, multipart?: boolean | MultipartOptions, validation?: boolean | ValidationOptions, auth?: {
+    userProperty?: string;
+}): Promise<void>;

package/dist/adapter/express/controllers.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.attachControllers = attachControllers;
 const metadata_1 = require("../../core/metadata");
+const auth_1 = require("../../core/auth");
 const errors_1 = require("../../core/errors");
 const response_1 = require("../../core/response");
 const coercion_1 = require("./coercion");
@@ -18,7 +19,7 @@ const validation_errors_1 = require("../../core/validation-errors");
  * @param inputCoercion - Input coercion setting
  * @param multipart - Multipart file upload configuration
  */
-async function attachControllers(app, controllers, inputCoercion = "safe", multipart, validation) {
+async function attachControllers(app, controllers, inputCoercion = "safe", multipart, validation, auth) {
     const multipartOptions = (0, multipart_1.normalizeMultipartOptions)(multipart);
     for (const controller of controllers) {
         const meta = (0, metadata_1.getControllerMeta)(controller);
@@ -51,9 +52,11 @@ async function attachControllers(app, controllers, inputCoercion = "safe", multi
             }
             // Determine if validation is enabled for this route
             const isValidationEnabled = validation !== false && validation?.enabled !== false;
+            const authMeta = (0, auth_1.getRouteAuthMeta)(controller, route.handlerName);
             // Main route handler
             const routeHandler = async (req, res, next) => {
                 try {
+                    await (0, auth_1.assertRouteAuthorized)(authMeta, req, auth);
                     const files = (0, multipart_1.extractFiles)(req);
                     // Create context
                     const ctx = {

package/dist/adapter/express/index.js

@@ -25,6 +25,7 @@ const cors_1 = require("./cors");
 const controllers_1 = require("./controllers");
 const openapi_1 = require("./openapi");
 const lifecycle_1 = require("../../core/lifecycle");
+const auth_1 = require("../../core/auth");
 __exportStar(require("./types"), exports);
 var cors_2 = require("./cors");
 Object.defineProperty(exports, "attachCors", { enumerable: true, get: function () { return cors_2.attachCors; } });
@@ -45,8 +46,11 @@ async function createExpressApp(options) {
     if (options.jsonBody ?? true) {
         app.use(express_1.default.json({ limit: options.jsonLimit }));
     }
+    if (options.bearerAuth) {
+        app.use((0, auth_1.createBearerAuthMiddleware)(options.bearerAuth));
+    }
     const inputCoercion = options.inputCoercion ?? "safe";
-    await (0, controllers_1.attachControllers)(app, options.controllers, inputCoercion, options.multipart, options.validation);
+    await (0, controllers_1.attachControllers)(app, options.controllers, inputCoercion, options.multipart, options.validation, { userProperty: options.bearerAuth?.userProperty });
     if (options.openApi) {
         (0, openapi_1.attachOpenApi)(app, options.controllers, options.openApi);
     }

package/dist/adapter/express/types.d.ts

@@ -1,5 +1,6 @@
 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 };
 /**
  * Request context provided to route handlers.
@@ -94,6 +95,8 @@ export interface ExpressAdapterOptions {
     inputCoercion?: InputCoercionSetting;
     /** 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. */

package/dist/adapter/fastify/controllers.d.ts

@@ -4,4 +4,6 @@ import type { InputCoercionSetting, MultipartOptions, ValidationOptions } from "
 /**
  * Attaches controllers to a Fastify application.
  */
-export declare function attachControllers(app: FastifyInstance, controllers: Constructor[], inputCoercion?: InputCoercionSetting, multipart?: boolean | MultipartOptions, validation?: boolean | ValidationOptions): Promise<void>;
+export declare function attachControllers(app: FastifyInstance, controllers: Constructor[], inputCoercion?: InputCoercionSetting, multipart?: boolean | MultipartOptions, validation?: boolean | ValidationOptions, auth?: {
+    userProperty?: string;
+}): Promise<void>;

package/dist/adapter/fastify/controllers.js

@@ -15,7 +15,7 @@ const validation_errors_1 = require("../../core/validation-errors");
 /**
  * Attaches controllers to a Fastify application.
  */
-async function attachControllers(app, controllers, inputCoercion = "safe", multipart, validation) {
+async function attachControllers(app, controllers, inputCoercion = "safe", multipart, validation, auth) {
     const multipartOptions = (0, multipart_1.normalizeMultipartOptions)(multipart);
     for (const controller of controllers) {
         const meta = (0, metadata_1.getControllerMeta)(controller);
@@ -48,30 +48,7 @@ async function attachControllers(app, controllers, inputCoercion = "safe", multi
                 handler: async (req, reply) => {
                     try {
                         // Apply auth guard if metadata exists
-                        if (authMeta && authMeta.requiresAuth && !authMeta.isPublic) {
-                            const user = req.user || req.raw.user;
-                            if (!user) {
-                                throw new errors_1.HttpError(401, "Unauthorized");
-                            }
-                            if (authMeta.roles?.length) {
-                                const hasRole = authMeta.roles.some((role) => user.roles?.includes(role));
-                                if (!hasRole) {
-                                    throw new errors_1.HttpError(403, "Insufficient permissions");
-                                }
-                            }
-                            if (authMeta.allRoles?.length) {
-                                const hasAllRoles = authMeta.allRoles.every((role) => user.roles?.includes(role));
-                                if (!hasAllRoles) {
-                                    throw new errors_1.HttpError(403, "Insufficient permissions");
-                                }
-                            }
-                            if (authMeta.guard) {
-                                const allowed = await authMeta.guard(user, req);
-                                if (!allowed) {
-                                    throw new errors_1.HttpError(403, "Access denied by guard");
-                                }
-                            }
-                        }
+                        await (0, auth_1.assertRouteAuthorized)(authMeta, req, auth);
                         let files = undefined;
                         if (multipartOptions && (0, multipart_1.hasFileUploads)(route.files)) {
                             files = await (0, multipart_1.extractFiles)(req);

package/dist/adapter/fastify/index.js

@@ -24,6 +24,7 @@ const fastify_1 = __importDefault(require("fastify"));
 const controllers_1 = require("./controllers");
 const openapi_1 = require("./openapi");
 const lifecycle_1 = require("../../core/lifecycle");
+const auth_1 = require("../../core/auth");
 const cors_1 = __importDefault(require("@fastify/cors"));
 const multipart_1 = __importDefault(require("@fastify/multipart"));
 __exportStar(require("./types"), exports);
@@ -50,8 +51,13 @@ async function createFastifyApp(options) {
             }
         });
     }
+    if (options.bearerAuth) {
+        app.addHook("preHandler", async (req) => {
+            await (0, auth_1.authenticateBearerRequest)(req, options.bearerAuth);
+        });
+    }
     const inputCoercion = options.inputCoercion ?? "safe";
-    await (0, controllers_1.attachControllers)(app, options.controllers, inputCoercion, options.multipart, options.validation);
+    await (0, controllers_1.attachControllers)(app, options.controllers, inputCoercion, options.multipart, options.validation, { userProperty: options.bearerAuth?.userProperty });
     if (options.openApi) {
         (0, openapi_1.attachOpenApi)(app, options.controllers, options.openApi);
     }

package/dist/adapter/fastify/types.d.ts

@@ -1,5 +1,6 @@
 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.
  */
@@ -93,6 +94,8 @@ export interface FastifyAdapterOptions {
     inputCoercion?: InputCoercionSetting;
     /** 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. */

package/dist/adapter/native/controllers.d.ts

@@ -14,4 +14,7 @@ export declare function dispatchRequest(req: IncomingMessage, res: ServerRespons
     validation?: boolean | ValidationOptions;
     body?: any;
     query?: Record<string, any>;
+    auth?: {
+        userProperty?: string;
+    };
 }): Promise<void>;

package/dist/adapter/native/controllers.js

@@ -34,7 +34,7 @@ async function registerControllers(router, controllers) {
  */
 async function dispatchRequest(req, res, match, options) {
     const { controller: instance, route, params: rawParams } = match;
-    const { inputCoercion, validation, body: rawBody, query: rawQuery } = options;
+    const { inputCoercion, validation, body: rawBody, query: rawQuery, auth } = options;
     const handler = instance[route.handlerName];
     if (typeof handler !== "function") {
         throw new Error(`Handler "${String(route.handlerName)}" is not a function.`);
@@ -52,30 +52,7 @@ async function dispatchRequest(req, res, match, options) {
     const authMeta = (0, auth_1.getRouteAuthMeta)(instance.constructor, route.handlerName);
     try {
         // Apply auth guard if metadata exists
-        if (authMeta && authMeta.requiresAuth && !authMeta.isPublic) {
-            const user = req.user;
-            if (!user) {
-                throw new errors_1.HttpError(401, "Unauthorized");
-            }
-            if (authMeta.roles?.length) {
-                const hasRole = authMeta.roles.some((role) => user.roles?.includes(role));
-                if (!hasRole) {
-                    throw new errors_1.HttpError(403, "Insufficient permissions");
-                }
-            }
-            if (authMeta.allRoles?.length) {
-                const hasAllRoles = authMeta.allRoles.every((role) => user.roles?.includes(role));
-                if (!hasAllRoles) {
-                    throw new errors_1.HttpError(403, "Insufficient permissions");
-                }
-            }
-            if (authMeta.guard) {
-                const allowed = await authMeta.guard(user, req);
-                if (!allowed) {
-                    throw new errors_1.HttpError(403, "Access denied by guard");
-                }
-            }
-        }
+        await (0, auth_1.assertRouteAuthorized)(authMeta, req, auth);
         const body = (coerceBody && rawBody) ? coerceBody(rawBody) : rawBody;
         const query = (coerceQuery && rawQuery) ? coerceQuery(rawQuery) : rawQuery;
         const params = (coerceParams && rawParams) ? coerceParams(rawParams) : rawParams;

package/dist/adapter/native/index.js

@@ -21,6 +21,7 @@ const node_http_1 = require("node:http");
 const controllers_1 = require("./controllers");
 const openapi_1 = require("./openapi");
 const lifecycle_1 = require("../../core/lifecycle");
+const auth_1 = require("../../core/auth");
 const router_1 = require("./router");
 __exportStar(require("./types"), exports);
 var controllers_2 = require("./controllers");
@@ -48,6 +49,17 @@ async function createNativeApp(options) {
             res.end(JSON.stringify({ message: `Not Found: ${req.method} ${url.pathname}` }));
             return;
         }
+        if (options.bearerAuth) {
+            try {
+                await (0, auth_1.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 = {};
         url.searchParams.forEach((value, key) => {
             if (query[key]) {
@@ -78,7 +90,8 @@ async function createNativeApp(options) {
             inputCoercion,
             validation: options.validation,
             body,
-            query
+            query,
+            auth: { userProperty: options.bearerAuth?.userProperty }
         });
     };
     await lifecycle_1.lifecycleRegistry.callOnApplicationBootstrap();

package/dist/adapter/native/types.d.ts

@@ -1,6 +1,7 @@
 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 { BearerAuthOptions } from "../../core/auth";
 export { UploadedFileInfo };
 /**
  * Request context provided to native route handlers.
@@ -63,6 +64,8 @@ export interface NativeAdapterOptions {
     openApi?: OpenApiNativeOptions;
     /** 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;
 }

package/dist/core/auth.d.ts

@@ -22,6 +22,10 @@ export interface AuthOptions {
  * Function to extract user from request.
  */
 export type AuthExtractor = (req: any) => AuthUser | null | Promise<AuthUser | null>;
+/**
+ * Function to validate a bearer token and resolve the authenticated user.
+ */
+export type BearerTokenVerifier = (token: string, req: any) => AuthUser | null | Promise<AuthUser | null>;
 /**
  * Options for creating auth middleware.
  */
@@ -35,10 +39,19 @@ export interface AuthMiddlewareOptions {
     /** Custom forbidden response */
     onForbidden?: (req: any, res: any, reason?: string) => void;
 }
+/**
+ * Options for built-in Bearer authentication.
+ */
+export interface BearerAuthOptions {
+    /** Function to validate token and return user context */
+    verifyToken: BearerTokenVerifier;
+    /** Property name to attach user to request (default: "user") */
+    userProperty?: string;
+}
 /**
  * Metadata for authentication on routes/controllers.
  */
-interface AuthMeta {
+export interface AuthMeta {
     /** Whether authentication is required */
     requiresAuth: boolean;
     /** Whether route is public (overrides controller-level auth) */
@@ -85,6 +98,10 @@ export declare function getRouteAuthMeta(controller: Constructor, handlerName: s
  * Gets auth metadata for a controller.
  */
 export declare function getControllerAuthMeta(controller: Constructor): AuthMeta | undefined;
+/**
+ * Extracts a token from the Authorization: Bearer <token> header.
+ */
+export declare function extractBearerToken(req: any): string | undefined;
 /**
  * Creates Express middleware for authentication.
  * Use this as a global middleware, then use route-level checks.
@@ -92,6 +109,20 @@ export declare function getControllerAuthMeta(controller: Constructor): AuthMeta
  * @returns Express middleware function
  */
 export declare function createAuthMiddleware(options: AuthMiddlewareOptions): (req: any, res: any, next: (err?: any) => void) => Promise<void>;
+/**
+ * Verifies a bearer token from the request and attaches the user when valid.
+ */
+export declare function authenticateBearerRequest(req: any, options: BearerAuthOptions): Promise<AuthUser | null>;
+/**
+ * Creates middleware that extracts and verifies Authorization bearer tokens.
+ */
+export declare function createBearerAuthMiddleware(options: BearerAuthOptions): (req: any, _res: any, next: (err?: any) => void) => Promise<void>;
+/**
+ * Applies route auth metadata to a request that may already have a user attached.
+ */
+export declare function assertRouteAuthorized(authMeta: AuthMeta | undefined, req: any, options?: {
+    userProperty?: string;
+}): Promise<void>;
 /**
  * Creates a route guard middleware that checks auth metadata.
  * @param controller - Controller class
@@ -101,7 +132,7 @@ export declare function createAuthMiddleware(options: AuthMiddlewareOptions): (r
  */
 export declare function createRouteGuard(controller: Constructor, handlerName: string | symbol, options?: {
     userProperty?: string;
-}): (req: any, res: any, next: (err?: any) => void) => Promise<void>;
+}): (req: any, _res: any, next: (err?: any) => void) => Promise<void>;
 /**
  * Helper to get user from request in controllers.
  * @param req - Raw request
@@ -117,4 +148,3 @@ export declare function getUser<T extends AuthUser = AuthUser>(req: any, userPro
  * @throws HttpError if user not found
  */
 export declare function requireUser<T extends AuthUser = AuthUser>(req: any, userProperty?: string): T;
-export {};

package/dist/core/auth.js

@@ -6,7 +6,11 @@ exports.AllRoles = AllRoles;
 exports.Public = Public;
 exports.getRouteAuthMeta = getRouteAuthMeta;
 exports.getControllerAuthMeta = getControllerAuthMeta;
+exports.extractBearerToken = extractBearerToken;
 exports.createAuthMiddleware = createAuthMiddleware;
+exports.authenticateBearerRequest = authenticateBearerRequest;
+exports.createBearerAuthMiddleware = createBearerAuthMiddleware;
+exports.assertRouteAuthorized = assertRouteAuthorized;
 exports.createRouteGuard = createRouteGuard;
 exports.getUser = getUser;
 exports.requireUser = requireUser;
@@ -153,6 +157,19 @@ function hasAllRoles(user, roles) {
         return false;
     return roles.every((role) => user.roles.includes(role));
 }
+/**
+ * Extracts a token from the Authorization: Bearer <token> header.
+ */
+function extractBearerToken(req) {
+    const headers = req?.headers;
+    const rawHeader = headers?.authorization ?? headers?.Authorization;
+    const header = Array.isArray(rawHeader) ? rawHeader[0] : rawHeader;
+    if (typeof header !== "string") {
+        return undefined;
+    }
+    const match = header.match(/^Bearer\s+(\S+)$/i);
+    return match?.[1];
+}
 /**
  * Creates Express middleware for authentication.
  * Use this as a global middleware, then use route-level checks.
@@ -174,6 +191,61 @@ function createAuthMiddleware(options) {
         }
     };
 }
+/**
+ * Verifies a bearer token from the request and attaches the user when valid.
+ */
+async function authenticateBearerRequest(req, options) {
+    const token = extractBearerToken(req);
+    if (!token) {
+        return null;
+    }
+    const user = await options.verifyToken(token, req);
+    if (user) {
+        req[options.userProperty ?? "user"] = user;
+    }
+    return user;
+}
+/**
+ * Creates middleware that extracts and verifies Authorization bearer tokens.
+ */
+function createBearerAuthMiddleware(options) {
+    return async (req, _res, next) => {
+        try {
+            await authenticateBearerRequest(req, options);
+            next();
+        }
+        catch (error) {
+            next(error);
+        }
+    };
+}
+/**
+ * Applies route auth metadata to a request that may already have a user attached.
+ */
+async function assertRouteAuthorized(authMeta, req, options = {}) {
+    if (!authMeta || authMeta.isPublic || !authMeta.requiresAuth) {
+        return;
+    }
+    const userProperty = options.userProperty ?? "user";
+    const requestRecord = req;
+    const rawRecord = (req?.raw ?? {});
+    const user = (requestRecord[userProperty] ?? rawRecord[userProperty]);
+    if (!user) {
+        throw new errors_1.HttpError(401, "Unauthorized");
+    }
+    if (authMeta.roles?.length && !hasAnyRole(user, authMeta.roles)) {
+        throw new errors_1.HttpError(403, "Insufficient permissions");
+    }
+    if (authMeta.allRoles?.length && !hasAllRoles(user, authMeta.allRoles)) {
+        throw new errors_1.HttpError(403, "Insufficient permissions");
+    }
+    if (authMeta.guard) {
+        const allowed = await authMeta.guard(user, req);
+        if (!allowed) {
+            throw new errors_1.HttpError(403, "Access denied by guard");
+        }
+    }
+}
 /**
  * Creates a route guard middleware that checks auth metadata.
  * @param controller - Controller class
@@ -182,29 +254,9 @@ function createAuthMiddleware(options) {
  * @returns Express middleware function
  */
 function createRouteGuard(controller, handlerName, options = {}) {
-    const userProperty = options.userProperty ?? "user";
     const authMeta = getRouteAuthMeta(controller, handlerName);
-    return async (req, res, next) => {
-        if (!authMeta || authMeta.isPublic || !authMeta.requiresAuth) {
-            next();
-            return;
-        }
-        const user = req[userProperty];
-        if (!user) {
-            throw new errors_1.HttpError(401, "Unauthorized");
-        }
-        if (authMeta.roles?.length && !hasAnyRole(user, authMeta.roles)) {
-            throw new errors_1.HttpError(403, "Insufficient permissions");
-        }
-        if (authMeta.allRoles?.length && !hasAllRoles(user, authMeta.allRoles)) {
-            throw new errors_1.HttpError(403, "Insufficient permissions");
-        }
-        if (authMeta.guard) {
-            const allowed = await authMeta.guard(user, req);
-            if (!allowed) {
-                throw new errors_1.HttpError(403, "Access denied by guard");
-            }
-        }
+    return async (req, _res, next) => {
+        await assertRouteAuthorized(authMeta, req, options);
         next();
     };
 }

package/dist/core/openapi.d.ts

@@ -49,6 +49,8 @@ export interface OpenApiDocument {
     components: {
         /** Schema definitions */
         schemas: Record<string, JsonSchema>;
+        /** Reusable security scheme definitions */
+        securitySchemes?: Record<string, unknown>;
     };
 }
 /**

package/dist/core/openapi.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildOpenApi = buildOpenApi;
 const schema_builder_1 = require("./schema-builder");
 const metadata_1 = require("./metadata");
+const auth_1 = require("./auth");
 /**
  * Validates that all registered DTOs have non-empty field metadata.
  * Throws an error with helpful diagnostic information if empty schemas are found.
@@ -39,6 +40,7 @@ function buildOpenApi(options) {
     const context = (0, schema_builder_1.createSchemaContext)();
     const controllers = filterControllers(options.controllers);
     const paths = {};
+    let hasBearerAuth = false;
     for (const controller of controllers) {
         const tagFallback = controller.meta.tags ?? [controller.meta.controller.name];
         for (const route of controller.meta.routes) {
@@ -56,6 +58,13 @@ function buildOpenApi(options) {
             const requestBody = hasFiles
                 ? buildMultipartRequestBody(route.files, route.body, context)
                 : buildRequestBody(route.body, context);
+            const authMeta = (0, auth_1.getRouteAuthMeta)(controller.meta.controller, route.handlerName);
+            const security = authMeta?.requiresAuth && !authMeta.isPublic
+                ? [{ bearerAuth: [] }]
+                : undefined;
+            if (security) {
+                hasBearerAuth = true;
+            }
             pathItem[route.httpMethod] = {
                 operationId: `${controller.meta.controller.name}.${String(route.handlerName)}`,
                 summary: route.summary,
@@ -63,6 +72,7 @@ function buildOpenApi(options) {
                 tags: route.tags ?? tagFallback,
                 parameters: parameters.length ? parameters : undefined,
                 requestBody,
+                security,
                 responses
             };
         }
@@ -74,7 +84,15 @@ function buildOpenApi(options) {
         servers: options.servers,
         paths,
         components: {
-            schemas: context.components
+            schemas: context.components,
+            securitySchemes: hasBearerAuth
+                ? {
+                    bearerAuth: {
+                        type: "http",
+                        scheme: "bearer"
+                    }
+                }
+                : undefined
         }
     };
     validateSchemas(context.components);

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

@@ -0,0 +1,28 @@
+import { createExpressApp, type AuthUser } from "../../src";
+import { AuthDemoController } from "./auth.controller";
+
+function verifyToken(token: string): AuthUser | null {
+  if (token === "user-token") {
+    return { id: "user-1", roles: ["user"] };
+  }
+  if (token === "admin-token") {
+    return { id: "admin-1", roles: ["user", "admin"] };
+  }
+  return null;
+}
+
+export async function createApp() {
+  return createExpressApp({
+    controllers: [AuthDemoController],
+    bearerAuth: { verifyToken },
+    openApi: {
+      info: {
+        title: "Bearer Auth Swagger Demo",
+        version: "1.0.0",
+        description: "Demo for Authorization: Bearer <token> with protected OpenAPI routes."
+      },
+      path: "/openapi.json",
+      docs: true
+    }
+  });
+}

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

@@ -0,0 +1,45 @@
+import {
+  Auth,
+  Controller,
+  Get,
+  Public,
+  Returns,
+  Roles,
+  getUser,
+  type AuthUser
+} from "../../src";
+import { PublicStatusDto, SessionDto } from "./session.dtos";
+
+@Controller("/auth-demo")
+export class AuthDemoController {
+  @Get("/public")
+  @Public()
+  @Returns(PublicStatusDto)
+  publicStatus() {
+    return { status: "public route, no bearer token required" };
+  }
+
+  @Get("/me")
+  @Auth()
+  @Returns(SessionDto)
+  me(ctx: any) {
+    const user = getUser<AuthUser>(ctx.req)!;
+    return {
+      id: user.id,
+      roles: user.roles ?? [],
+      message: "Bearer token accepted"
+    };
+  }
+
+  @Get("/admin")
+  @Roles("admin")
+  @Returns(SessionDto)
+  admin(ctx: any) {
+    const user = getUser<AuthUser>(ctx.req)!;
+    return {
+      id: user.id,
+      roles: user.roles ?? [],
+      message: "Admin role accepted"
+    };
+  }
+}

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,6 +1,6 @@
 {
   "name": "adorn-api",
-  "version": "1.1.13",
+  "version": "1.1.14",
   "description": "Decorator-first web framework with OpenAPI 3.1 schema generation.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",