adorn-api 1.1.12 → 1.1.14

package/src/core/auth.ts

@@ -25,26 +25,44 @@ export interface AuthOptions {
 /**
  * Function to extract user from request.
  */
-export type AuthExtractor = (req: any) => AuthUser | null | Promise<AuthUser | null>;
+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.
  */
-export interface AuthMiddlewareOptions {
-  /** Function to extract user from request */
-  extractor: AuthExtractor;
-  /** Property name to attach user to request (default: "user") */
-  userProperty?: string;
+export interface AuthMiddlewareOptions {
+  /** Function to extract user from request */
+  extractor: AuthExtractor;
+  /** Property name to attach user to request (default: "user") */
+  userProperty?: string;
   /** Custom unauthorized response */
   onUnauthorized?: (req: any, res: any) => void;
   /** Custom forbidden response */
-  onForbidden?: (req: any, res: any, reason?: string) => void;
-}
+  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) */
@@ -208,11 +226,27 @@ function hasAnyRole(user: AuthUser, roles: string[]): boolean {
 /**
  * Checks if user has all required roles.
  */
-function hasAllRoles(user: AuthUser, roles: string[]): boolean {
-  if (!roles.length) return true;
-  if (!user.roles?.length) return false;
-  return roles.every((role) => user.roles!.includes(role));
-}
+function hasAllRoles(user: AuthUser, roles: string[]): boolean {
+  if (!roles.length) return true;
+  if (!user.roles?.length) return false;
+  return roles.every((role) => user.roles!.includes(role));
+}
+
+/**
+ * Extracts a token from the Authorization: Bearer <token> header.
+ */
+export function extractBearerToken(req: any): string | undefined {
+  const headers = req?.headers as Record<string, unknown> | undefined;
+  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.
@@ -220,8 +254,8 @@ function hasAllRoles(user: AuthUser, roles: string[]): boolean {
  * @param options - Auth middleware options
  * @returns Express middleware function
  */
-export function createAuthMiddleware(options: AuthMiddlewareOptions) {
-  const userProperty = options.userProperty ?? "user";
+export function createAuthMiddleware(options: AuthMiddlewareOptions) {
+  const userProperty = options.userProperty ?? "user";
 
   return async (req: any, res: any, next: (err?: any) => void): Promise<void> => {
     try {
@@ -233,8 +267,78 @@ export function createAuthMiddleware(options: AuthMiddlewareOptions) {
     } catch (error) {
       next(error);
     }
-  };
-}
+  };
+}
+
+/**
+ * Verifies a bearer token from the request and attaches the user when valid.
+ */
+export async function authenticateBearerRequest(
+  req: any,
+  options: BearerAuthOptions
+): Promise<AuthUser | null> {
+  const token = extractBearerToken(req);
+  if (!token) {
+    return null;
+  }
+
+  const user = await options.verifyToken(token, req);
+  if (user) {
+    (req as Record<string, unknown>)[options.userProperty ?? "user"] = user;
+  }
+  return user;
+}
+
+/**
+ * Creates middleware that extracts and verifies Authorization bearer tokens.
+ */
+export function createBearerAuthMiddleware(options: BearerAuthOptions) {
+  return async (req: any, _res: any, next: (err?: any) => void): Promise<void> => {
+    try {
+      await authenticateBearerRequest(req, options);
+      next();
+    } catch (error) {
+      next(error);
+    }
+  };
+}
+
+/**
+ * Applies route auth metadata to a request that may already have a user attached.
+ */
+export async function assertRouteAuthorized(
+  authMeta: AuthMeta | undefined,
+  req: any,
+  options: { userProperty?: string } = {}
+): Promise<void> {
+  if (!authMeta || authMeta.isPublic || !authMeta.requiresAuth) {
+    return;
+  }
+
+  const userProperty = options.userProperty ?? "user";
+  const requestRecord = req as Record<string, unknown>;
+  const rawRecord = (req?.raw ?? {}) as Record<string, unknown>;
+  const user = (requestRecord[userProperty] ?? rawRecord[userProperty]) as AuthUser | undefined;
+
+  if (!user) {
+    throw new HttpError(401, "Unauthorized");
+  }
+
+  if (authMeta.roles?.length && !hasAnyRole(user, authMeta.roles)) {
+    throw new HttpError(403, "Insufficient permissions");
+  }
+
+  if (authMeta.allRoles?.length && !hasAllRoles(user, authMeta.allRoles)) {
+    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");
+    }
+  }
+}
 
 /**
  * Creates a route guard middleware that checks auth metadata.
@@ -243,44 +347,18 @@ export function createAuthMiddleware(options: AuthMiddlewareOptions) {
  * @param options - Auth middleware options
  * @returns Express middleware function
  */
-export function createRouteGuard(
-  controller: Constructor,
-  handlerName: string | symbol,
-  options: { userProperty?: string } = {}
-) {
-  const userProperty = options.userProperty ?? "user";
-  const authMeta = getRouteAuthMeta(controller, handlerName);
-
-  return async (req: any, res: any, next: (err?: any) => void): Promise<void> => {
-    if (!authMeta || authMeta.isPublic || !authMeta.requiresAuth) {
-      next();
-      return;
-    }
-
-    const user = (req as unknown as Record<string, unknown>)[userProperty] as AuthUser | undefined;
-
-    if (!user) {
-      throw new HttpError(401, "Unauthorized");
-    }
-
-    if (authMeta.roles?.length && !hasAnyRole(user, authMeta.roles)) {
-      throw new HttpError(403, "Insufficient permissions");
-    }
-
-    if (authMeta.allRoles?.length && !hasAllRoles(user, authMeta.allRoles)) {
-      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");
-      }
-    }
-
-    next();
-  };
-}
+export function createRouteGuard(
+  controller: Constructor,
+  handlerName: string | symbol,
+  options: { userProperty?: string } = {}
+) {
+  const authMeta = getRouteAuthMeta(controller, handlerName);
+
+  return async (req: any, _res: any, next: (err?: any) => void): Promise<void> => {
+    await assertRouteAuthorized(authMeta, req, options);
+    next();
+  };
+}
 
 /**
  * Helper to get user from request in controllers.

package/src/core/openapi.ts

@@ -6,6 +6,7 @@ import {
   buildSchemaFromSource
 } from "./schema-builder";
 import { getAllControllers, getDtoMeta } from "./metadata";
+import { getRouteAuthMeta } from "./auth";
 import type { SchemaNode, SchemaSource } from "./schema";
 
 /**
@@ -93,6 +94,8 @@ export interface OpenApiDocument {
   components: {
     /** Schema definitions */
     schemas: Record<string, JsonSchema>;
+    /** Reusable security scheme definitions */
+    securitySchemes?: Record<string, unknown>;
   };
 }
 
@@ -106,6 +109,7 @@ export function buildOpenApi(options: OpenApiOptions): OpenApiDocument {
   
   const controllers = filterControllers(options.controllers);
   const paths: Record<string, Record<string, unknown>> = {};
+  let hasBearerAuth = false;
 
   for (const controller of controllers) {
     const tagFallback = controller.meta.tags ?? [controller.meta.controller.name];
@@ -127,6 +131,14 @@ export function buildOpenApi(options: OpenApiOptions): OpenApiDocument {
       const requestBody = hasFiles
         ? buildMultipartRequestBody(route.files!, route.body, context)
         : buildRequestBody(route.body, context);
+      const authMeta = 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)}`,
@@ -135,6 +147,7 @@ export function buildOpenApi(options: OpenApiOptions): OpenApiDocument {
         tags: route.tags ?? tagFallback,
         parameters: parameters.length ? parameters : undefined,
         requestBody,
+        security,
         responses
       };
     }
@@ -147,7 +160,15 @@ export function buildOpenApi(options: OpenApiOptions): OpenApiDocument {
     servers: options.servers,
     paths,
     components: {
-      schemas: context.components
+      schemas: context.components,
+      securitySchemes: hasBearerAuth
+        ? {
+            bearerAuth: {
+              type: "http",
+              scheme: "bearer"
+            }
+          }
+        : undefined
     }
   };
   

package/tests/e2e/bearer-auth.e2e.test.ts

@@ -0,0 +1,158 @@
+import { describe, expect, it } from "vitest";
+import request from "supertest";
+import {
+  Auth,
+  Controller,
+  Get,
+  Public,
+  Roles,
+  createExpressApp,
+  createFastifyApp,
+  createNativeApp,
+  shutdownNativeApp,
+  type AuthUser
+} from "../../src";
+
+@Controller("/bearer")
+class BearerController {
+  @Get("/public")
+  @Public()
+  public() {
+    return { message: "public" };
+  }
+
+  @Get("/protected")
+  @Auth()
+  protected() {
+    return { message: "protected" };
+  }
+
+  @Get("/admin")
+  @Roles("admin")
+  admin() {
+    return { message: "admin" };
+  }
+}
+
+function verifyToken(token: string): AuthUser | null {
+  if (token === "valid") {
+    return { id: "1", roles: ["user"] };
+  }
+  if (token === "admin") {
+    return { id: "2", roles: ["admin"] };
+  }
+  return null;
+}
+
+function createMockNativeRequest(path: string, token?: string): any {
+  return {
+    method: "GET",
+    url: path,
+    headers: token ? { authorization: `Bearer ${token}` } : {}
+  };
+}
+
+function createMockNativeResponse(): any {
+  const res: any = {
+    statusCode: 0,
+    headers: {},
+    setHeader(name: string, value: string) {
+      this.headers[name] = value;
+    },
+    getHeader(name: string) {
+      return this.headers[name];
+    },
+    end(data: string) {
+      this.body = data;
+    }
+  };
+  return res;
+}
+
+describe("Bearer auth adapters", () => {
+  it("Express blocks protected routes without token", async () => {
+    const app = await createExpressApp({
+      controllers: [BearerController],
+      bearerAuth: { verifyToken }
+    });
+
+    const response = await request(app).get("/bearer/protected");
+
+    expect(response.status).toBe(401);
+  });
+
+  it("Express allows protected routes with a valid bearer token", async () => {
+    const app = await createExpressApp({
+      controllers: [BearerController],
+      bearerAuth: { verifyToken }
+    });
+
+    const response = await request(app)
+      .get("/bearer/protected")
+      .set("Authorization", "Bearer valid");
+
+    expect(response.status).toBe(200);
+    expect(response.body).toEqual({ message: "protected" });
+  });
+
+  it("Express blocks role routes when bearer user lacks role", async () => {
+    const app = await createExpressApp({
+      controllers: [BearerController],
+      bearerAuth: { verifyToken }
+    });
+
+    const response = await request(app)
+      .get("/bearer/admin")
+      .set("Authorization", "Bearer valid");
+
+    expect(response.status).toBe(403);
+  });
+
+  it("Fastify blocks, allows, and applies roles with bearer tokens", async () => {
+    const app = await createFastifyApp({
+      controllers: [BearerController],
+      bearerAuth: { verifyToken }
+    });
+    await app.ready();
+
+    const blocked = await app.inject({ method: "GET", url: "/bearer/protected" });
+    const allowed = await app.inject({
+      method: "GET",
+      url: "/bearer/protected",
+      headers: { authorization: "Bearer valid" }
+    });
+    const forbidden = await app.inject({
+      method: "GET",
+      url: "/bearer/admin",
+      headers: { authorization: "Bearer valid" }
+    });
+
+    expect(blocked.statusCode).toBe(401);
+    expect(allowed.statusCode).toBe(200);
+    expect(allowed.json()).toEqual({ message: "protected" });
+    expect(forbidden.statusCode).toBe(403);
+  });
+
+  it("Native blocks, allows, and applies roles with bearer tokens", async () => {
+    const app = await createNativeApp({
+      controllers: [BearerController],
+      bearerAuth: { verifyToken }
+    });
+
+    const blocked = createMockNativeResponse();
+    await app.handle(createMockNativeRequest("/bearer/protected"), blocked);
+
+    const allowed = createMockNativeResponse();
+    await app.handle(createMockNativeRequest("/bearer/protected", "valid"), allowed);
+
+    const forbidden = createMockNativeResponse();
+    await app.handle(createMockNativeRequest("/bearer/admin", "valid"), forbidden);
+
+    expect(blocked.statusCode).toBe(401);
+    expect(allowed.statusCode).toBe(200);
+    expect(JSON.parse(allowed.body)).toEqual({ message: "protected" });
+    expect(forbidden.statusCode).toBe(403);
+
+    await shutdownNativeApp();
+  });
+});

package/tests/typecheck/query-params.typecheck.ts

@@ -0,0 +1,42 @@
+import type {
+  PagedQueryParams,
+  PaginationQueryParams,
+  SortDirection,
+  SortingQueryParams
+} from "../../src/index";
+
+type Assert<T extends true> = T;
+type IsEqual<A, B> =
+  (<T>() => T extends A ? 1 : 2) extends
+    (<T>() => T extends B ? 1 : 2)
+    ? true
+    : false;
+
+type _SortDirectionMatchesPublicType = Assert<
+  IsEqual<SortingQueryParams["sortDirection"], SortDirection | undefined>
+>;
+
+const paginationOnly: PaginationQueryParams = {
+  page: 1,
+  pageSize: 25
+};
+
+const sortingOnly: SortingQueryParams = {
+  sortBy: "createdAt",
+  sortDirection: "desc"
+};
+
+const pagedWithSorting: PagedQueryParams = {
+  page: paginationOnly.page,
+  pageSize: paginationOnly.pageSize,
+  sortBy: sortingOnly.sortBy,
+  sortDirection: "asc"
+};
+
+// @ts-expect-error sortDirection accepts only "asc" | "desc"
+const invalidSorting: SortingQueryParams = { sortDirection: "ASC" };
+
+void paginationOnly;
+void sortingOnly;
+void pagedWithSorting;
+void invalidSorting;

package/tests/unit/auth.test.ts

@@ -5,14 +5,16 @@ import {
   Roles,
   AllRoles,
   Public,
-  getRouteAuthMeta,
-  getControllerAuthMeta,
-  createAuthMiddleware,
-  createRouteGuard,
-  getUser,
-  requireUser,
-  type AuthUser
-} from "../../src/core/auth";
+  getRouteAuthMeta,
+  getControllerAuthMeta,
+  createAuthMiddleware,
+  createBearerAuthMiddleware,
+  createRouteGuard,
+  extractBearerToken,
+  getUser,
+  requireUser,
+  type AuthUser
+} from "../../src/core/auth";
 import { Controller } from "../../src/core/decorators";
 import { HttpError } from "../../src/core/errors";
 
@@ -176,7 +178,7 @@ describe("getRouteAuthMeta", () => {
   });
 });
 
-describe("createAuthMiddleware", () => {
+describe("createAuthMiddleware", () => {
   it("extracts user and attaches to request", async () => {
     const user: AuthUser = { id: "123", roles: ["user"] };
     const middleware = createAuthMiddleware({
@@ -238,9 +240,91 @@ describe("createAuthMiddleware", () => {
 
     expect((req as unknown as Record<string, unknown>).user).toBe(user);
   });
-});
-
-describe("createRouteGuard", () => {
+});
+
+describe("extractBearerToken", () => {
+  it("returns undefined when authorization header is missing", () => {
+    expect(extractBearerToken(createMockRequest())).toBeUndefined();
+  });
+
+  it("extracts token from Bearer authorization header", () => {
+    const req = createMockRequest({ headers: { authorization: "Bearer abc123" } });
+    expect(extractBearerToken(req)).toBe("abc123");
+  });
+
+  it("extracts token from case-insensitive bearer scheme", () => {
+    const req = createMockRequest({ headers: { authorization: "bearer abc123" } });
+    expect(extractBearerToken(req)).toBe("abc123");
+  });
+
+  it("returns undefined for invalid authorization formats", () => {
+    expect(extractBearerToken(createMockRequest({ headers: { authorization: "Basic abc123" } }))).toBeUndefined();
+    expect(extractBearerToken(createMockRequest({ headers: { authorization: "Bearer" } }))).toBeUndefined();
+    expect(extractBearerToken(createMockRequest({ headers: { authorization: "Bearer abc def" } }))).toBeUndefined();
+  });
+});
+
+describe("createBearerAuthMiddleware", () => {
+  it("attaches user for a valid bearer token", async () => {
+    const user: AuthUser = { id: "bearer-user", roles: ["user"] };
+    const middleware = createBearerAuthMiddleware({
+      verifyToken: vi.fn().mockResolvedValue(user)
+    });
+    const req = createMockRequest({ headers: { authorization: "Bearer valid" } });
+    const res = createMockResponse();
+    const next = vi.fn();
+
+    await middleware(req, res, next);
+
+    expect((req as unknown as Record<string, unknown>).user).toBe(user);
+    expect(next).toHaveBeenCalledWith();
+  });
+
+  it("does not attach user for an invalid bearer token", async () => {
+    const middleware = createBearerAuthMiddleware({
+      verifyToken: vi.fn().mockResolvedValue(null)
+    });
+    const req = createMockRequest({ headers: { authorization: "Bearer invalid" } });
+    const res = createMockResponse();
+    const next = vi.fn();
+
+    await middleware(req, res, next);
+
+    expect((req as unknown as Record<string, unknown>).user).toBeUndefined();
+    expect(next).toHaveBeenCalledWith();
+  });
+
+  it("passes verifier errors to next", async () => {
+    const error = new Error("verifier failed");
+    const middleware = createBearerAuthMiddleware({
+      verifyToken: vi.fn().mockRejectedValue(error)
+    });
+    const req = createMockRequest({ headers: { authorization: "Bearer bad" } });
+    const res = createMockResponse();
+    const next = vi.fn();
+
+    await middleware(req, res, next);
+
+    expect(next).toHaveBeenCalledWith(error);
+  });
+
+  it("uses custom user property", async () => {
+    const user: AuthUser = { id: "custom" };
+    const middleware = createBearerAuthMiddleware({
+      userProperty: "currentUser",
+      verifyToken: vi.fn().mockResolvedValue(user)
+    });
+    const req = createMockRequest({ headers: { authorization: "Bearer valid" } });
+    const res = createMockResponse();
+    const next = vi.fn();
+
+    await middleware(req, res, next);
+
+    expect((req as unknown as Record<string, unknown>).currentUser).toBe(user);
+  });
+});
+
+describe("createRouteGuard", () => {
   it("allows public routes without user", async () => {
     @Controller("/api")
     class ApiController {

package/tests/unit/openapi-parameters.test.ts

@@ -1,8 +1,9 @@
 import { describe, expect, it, beforeEach } from "vitest";
-import { t } from "../../src/core/schema";
-import { registerController } from "../../src/core/metadata";
-import { buildOpenApi } from "../../src/core/openapi";
-import { createInputCoercer } from "../../src/adapter/express/coercion";
+import { t } from "../../src/core/schema";
+import { registerController } from "../../src/core/metadata";
+import { buildOpenApi } from "../../src/core/openapi";
+import { createInputCoercer } from "../../src/adapter/express/coercion";
+import { Auth, Controller, Get, Public } from "../../src";
 
 describe("OpenAPI query parameter serialization", () => {
   class QueryArrayController {}
@@ -74,7 +75,7 @@ describe("OpenAPI query parameter serialization", () => {
   });
 });
 
-describe("Query array coercion – CSV support", () => {
+describe("Query array coercion – CSV support", () => {
   it("?ids=1&ids=2 -> [1,2] via repeated keys", () => {
     const coerce = createInputCoercer(
       { schema: { kind: "object", properties: { ids: t.array(t.integer()) } } },
@@ -94,4 +95,51 @@ describe("Query array coercion – CSV support", () => {
     const result = coerce({ ids: "1,2" });
     expect(result.ids).toEqual([1, 2]);
   });
-});
+});
+
+describe("OpenAPI bearer auth security", () => {
+  @Controller("/secure-docs")
+  class SecureDocsController {
+    @Get("/public")
+    @Public()
+    publicRoute() {
+      return {};
+    }
+
+    @Get("/protected")
+    @Auth()
+    protectedRoute() {
+      return {};
+    }
+  }
+
+  it("adds bearerAuth security scheme when protected routes exist", () => {
+    new SecureDocsController();
+
+    const doc = buildOpenApi({
+      info: { title: "test", version: "1.0.0" },
+      controllers: [SecureDocsController]
+    });
+
+    expect(doc.components.securitySchemes).toEqual({
+      bearerAuth: {
+        type: "http",
+        scheme: "bearer"
+      }
+    });
+  });
+
+  it("adds security only to protected operations", () => {
+    new SecureDocsController();
+
+    const doc = buildOpenApi({
+      info: { title: "test", version: "1.0.0" },
+      controllers: [SecureDocsController]
+    });
+
+    expect((doc.paths["/secure-docs/protected"] as any).get.security).toEqual([
+      { bearerAuth: [] }
+    ]);
+    expect((doc.paths["/secure-docs/public"] as any).get.security).toBeUndefined();
+  });
+});