api-machine 1.0.0

package/CHANGELOG.md

@@ -0,0 +1 @@
+# api-machine - Changelog

package/LICENSE.md

@@ -0,0 +1,20 @@
+Copyright (c) 2022 api-machine and others
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,383 @@
+# api-machine - REST API Server Framework
+
+A lightweight, TypeScript-first REST API framework built on Express with a class-based routing architecture.
+
+## Installation
+
+```bash
+npm i api-machine
+```
+
+## Features
+
+- **TypeScript-First**: Fully typed API development with TypeScript
+- **Self-documenting** - Automatically hosts Swagger & OpenAPI (when enabled)
+- **Class-Based Architecture**: Organize your API with classes for servers, routers, and endpoints
+- **Built on Express**: Leverages the power and ecosystem of Express.js
+- **Secure by Default**: Automatic security headers and server fingerprinting protection
+- **CORS Support**: Built-in CORS handling
+- **Error Handling**: Automatic error handling with standardized responses
+- **Configurable**: Flexible configuration for ports, payload sizes, and logging
+
+## Quick Start
+
+See the [Quick Start Example](examples/quick-start/) for a complete, runnable example.
+
+Here's the basic structure:
+
+### 1. Endpoints
+
+```typescript
+class HelloEndpoint extends BaseApiEndpoint {
+	override path = '/hello';
+
+	override async handle(request, response) {
+		return { message: 'Hello, World!' };
+	}
+}
+```
+
+### 2. Routers
+
+```typescript
+class MyRouter extends BaseApiRouter {
+	override path = '/api';
+
+	override async routes() {
+		return [HelloEndpoint, /* UsersRouter */];
+	}
+}
+```
+
+### 3. Servers
+
+```typescript
+class MyApiServer extends RestServer {
+	override router = MyRouter;
+}
+
+const server = new MyApiServer({
+	port: 4000,
+	swaggerEnabled: process.env?.NODE_ENV === 'development'
+})
+```
+
+### Swagger
+
+Navigate to http://localhost:4000/docs to browse your swagger API docs
+
+## Examples
+
+The [`examples/`](examples/) directory contains comprehensive examples:
+
+- **[Quick Start](examples/quick-start/README.md)** - Basic server setup demonstrating the fundamental concepts
+  - Simple server, router, and endpoint structure
+  - Default GET endpoints
+  - Basic JSON responses
+  - Minimal configuration
+
+- **[Complete Example](examples/complete-example/README.md)** - Advanced features and production patterns
+  - Full CRUD operations (GET, POST, PUT, DELETE)
+  - Route parameters and validation
+  - Error handling with proper status codes
+  - Custom logger configuration (ts-tiny-log)
+  - Express integration (headers, query params)
+  - Request body validation
+  - Structured error responses
+
+## Configuration
+
+### Server Options
+#### port `number = 5000`
+
+The port number on which the server will listen for incoming requests.
+
+#### maxPayloadSizeMB `number = 10`
+
+Maximum size in megabytes for JSON request payloads that the server will accept.
+
+#### maxUrlEncodedSizeMB `number = 1`
+
+Maximum size in megabytes for URL-encoded request payloads that the server will accept.
+
+#### log `LogInterface = console`
+
+Custom logger interface for handling server logging (e.g. `ts-tiny-log`). Must implement the LogInterface contract.
+
+#### securityHeaders `SecurityHeadersOptions`
+
+Configuration for HTTP security headers. By default, api-machine is **secure by default** with:
+- X-Powered-By header removed (prevents server fingerprinting)
+- X-Content-Type-Options: nosniff (prevents MIME sniffing)
+- X-Frame-Options: DENY (prevents clickjacking)
+- X-XSS-Protection: 1; mode=block (legacy XSS protection)
+
+See **[Security Headers Documentation](docs/security-headers.md)** for detailed configuration options and best practices.
+
+### Example with Options
+
+```typescript
+const server = new MyServer({
+  port: 8080,
+  maxPayloadSizeMB: 20,
+  maxUrlEncodedSizeMB: 2,
+  log: myCustomLogger
+});
+```
+
+## API Summary
+
+### RestServer
+
+Abstract class for creating REST API servers.
+
+**Methods:**
+- `start()`: Starts the server
+- `stop()`: Stops the server
+
+
+### BaseApiRouter
+
+Abstract class for creating route groups.
+
+**Properties:**
+- `path`: The base path for the router (e.g., `/api`)
+
+**Methods:**
+- `routes()`: Abstract method to define endpoints (must be implemented)
+
+### BaseApiEndpoint
+
+Abstract class for creating API endpoints.
+
+**Properties:**
+- `path`: The endpoint path (default: `''`)
+- `method`: The HTTP method (default: `GET`). Can be:
+	- `EndpointMethods.GET`
+	- `EndpointMethods.POST`
+	- `EndpointMethods.PATCH`
+	- `EndpointMethods.PUT`
+	- `EndpointMethods.DELETE`
+
+**Methods:**
+- `handle(request, response, next)`: Abstract method to handle requests (must be implemented)
+
+#### Using Different HTTP Methods
+
+api-machine provides convenience classes for each HTTP method with appropriate default status codes:
+
+```typescript
+// GET endpoint (200 OK by default)
+class GetUsersEndpoint extends GetEndpoint {
+	override path = '/users';
+	
+	async handle(request, response) {
+		return [{ id: 1, name: 'John' }];
+	}
+}
+
+// POST endpoint
+class CreateUserEndpoint extends PostEndpoint {
+	override path = '/users';
+	
+	async handle(request, response) {
+		const newUser = {
+			id: Date.now(),
+			name: request.body.name
+		};
+
+		return newUser;
+	}
+}
+
+// PUT endpoint
+class UpdateUserEndpoint extends PutEndpoint {
+	override path = '/users/:id';
+	
+	async handle(request, response) {
+		const id = parseInt(request.params['id'], 10);
+
+		// Update entire user resource
+		return { id, ...request.body };
+	}
+}
+
+// PATCH endpoint
+class PatchUserEndpoint extends PatchEndpoint {
+	override path = '/users/:id';
+	
+	async handle(request, response) {
+		const id = parseInt(request.params['id'], 10);
+
+		// Update only provided fields
+		return { id, ...request.body };
+	}
+}
+
+// DELETE endpoint (204 No Content by default)
+class DeleteUserEndpoint extends DeleteEndpoint {
+	override path = '/users/:id';
+	
+	async handle(request, response) {
+		const id = parseInt(request.params['id'], 10);
+
+		// Deletion logic here
+		return {};
+	}
+}
+```
+
+**Available Endpoint Classes:**
+- `GetEndpoint` - GET requests (200 OK)
+- `PostEndpoint` - POST requests (201 Created)
+- `PutEndpoint` - PUT requests (200 OK)
+- `PatchEndpoint` - PATCH requests (200 OK)
+- `DeleteEndpoint` - DELETE requests (204 No Content)
+- `HealthCheckEndpoint` - Pre-built health check endpoint (GET /health)
+
+You can also use `BaseApiEndpoint` and manually set the `method` and `statusCode` properties if needed for custom behavior.
+
+#### Pre-Built Endpoints
+
+##### HealthCheckEndpoint
+
+A ready-to-use health check endpoint that returns system status information. Simply include it in your router:
+
+```typescript
+import { BaseApiRouter, HealthCheckEndpoint } from 'api-machine';
+
+class MyRouter extends BaseApiRouter {
+	override path = '/api';
+	
+	async routes() {
+		return [
+			HealthCheckEndpoint,  // Available at GET /api/health
+			// ... other endpoints
+		];
+	}
+}
+```
+
+**Response Format:**
+```json
+{
+	"status": "ok",
+	"timestamp": "2025-11-08T12:00:00.000Z",
+	"uptime": 123.45,
+	"environment": "development"
+}
+```
+
+**Customizing the Path:**
+```typescript
+class CustomHealthCheck extends HealthCheckEndpoint {
+	override path = '/status';  // Available at GET /api/status
+}
+```
+
+For advanced usage, extending the health check with custom checks, and deployment examples (Kubernetes, Docker, monitoring), see the **[Health Check Endpoint Documentation](docs/health-check-endpoint.md)**.
+
+## Error Handling
+
+api-machine provides a comprehensive set of HTTP error classes for standardized error responses. All errors extend `HTTPError` and automatically format responses with proper status codes and headers.
+
+```typescript
+import { NotFoundError, BadRequestError, UnauthorizedError } from 'api-machine';
+
+class GetUserEndpoint extends GetEndpoint {
+	override path = '/users/:id';
+	
+	async handle(request, response) {
+		const id = parseInt(request.params['id'], 10);
+		const user = await findUser(id);
+		
+		if (!user) {
+			throw new NotFoundError('User not found', {
+				details: { userId: id }
+			});
+		}
+		
+		return user;
+	}
+}
+```
+
+**Key Features:**
+- 29 built-in error classes covering HTTP status codes 400-451
+- Automatic JSON error responses with timestamps
+- Support for custom headers (e.g., `WWW-Authenticate`, `Retry-After`)
+- Optional `details` field for additional context
+- User-provided headers override defaults
+
+**Common Error Classes:**
+- `BadRequestError` (400)
+- `UnauthorizedError` (401) 
+- `ForbiddenError` (403)
+- `NotFoundError` (404)
+- `ConflictError` (409)
+- `UnprocessableEntityError` (422)
+- `TooManyRequestsError` (429)
+
+For the complete list of error classes, usage examples, and custom error creation, see the **[HTTP Errors Documentation](docs/http-errors.md)**.
+
+## Validation & Sanitization
+
+api-machine supports request validation and sanitization using [valsan](https://www.npmjs.com/package/valsan). You can declare ObjectSanitizer members on your endpoint classes for `body`, `query`, `params`, or `headers`:
+
+```typescript
+import { ObjectSanitizer, EmailValidator } from 'valsan';
+import { NameValSan } from './examples/complete-example/users/name-valsan';
+
+class CreateUserEndpoint extends PostEndpoint {
+  override path = '/users';
+
+  override body = new ObjectSanitizer({
+    name: new NameValSan(),
+    email: new EmailValidator(),
+  });
+
+  async handle(request, response) {
+    // request.body is validated & sanitized
+    // ...
+  }
+}
+```
+
+- If validation fails, a 400 error is returned with details.
+- If validation succeeds, the sanitized values are available in `request.body`, `request.query`, etc.
+
+You can create custom validators by extending `ComposedValSan` from valsan. See the [valsan documentation](../valsan/README.md) for more details.
+
+## Authentication
+
+api-machine provides a declarative authentication system with cascading support across server, router, and endpoint levels:
+
+```typescript
+class SecureRouter extends BaseApiRouter {
+  override path = '/api';
+  override authentication = new BearerAuthenticationScheme({
+    checkToken: async (token: string) => await validateToken(token),
+  });
+  
+  async routes() {
+    return [ProtectedEndpoint];
+  }
+}
+```
+
+**Key Features:**
+- **Cascading authentication** - Server → Router → Endpoint priority
+- **Bearer token support** - Built-in Bearer authentication scheme
+- **OpenAPI integration** - Automatic security scheme generation
+- **Public routes** - Set `authentication = null` to bypass parent auth
+- **Custom schemes** - Extend `AuthenticationScheme` for custom auth
+
+See **[Authentication Documentation](docs/authentication.md)** for complete usage, cascading examples, and custom authentication schemes.
+
+## Middleware
+
+Routers and endpoints support Express-style middleware for logging, validation, and more. See [Middleware Support](docs/middleware.md) for usage and examples.
+
+## Contributing & Development
+
+See [contributing.md](docs/contributing/contributing.md) for information on how to develop or contribute to this project!

package/authentication/authenticated-request.d.ts

@@ -0,0 +1,4 @@
+import { Request } from 'express';
+export interface AuthenticatedRequest extends Request {
+    authenticated?: boolean;
+}

package/authentication/authenticated-request.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=authenticated-request.js.map

package/authentication/authenticated-request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authenticated-request.js","sourceRoot":"","sources":["../../../src/authentication/authenticated-request.ts"],"names":[],"mappings":""}

package/authentication/authentication-scheme.d.ts

@@ -0,0 +1,38 @@
+import { RequestHandler } from 'express';
+import { SecuritySchemeObject, SecurityRequirementObject } from 'auto-oas/oas/v3.1';
+/**
+ * Abstract base class for authentication schemes
+ * Extend this class to create custom authentication schemes that integrate
+ * with both Express middleware and OpenAPI specification generation
+ */
+export declare abstract class AuthenticationScheme {
+    /**
+     * Unique name for this authentication scheme
+     * This will be used as the key in OpenAPI securitySchemes
+     */
+    abstract readonly schemeName: string;
+    /**
+     * The type of security scheme as defined by OpenAPI
+     */
+    abstract readonly type: 'http' | 'apiKey' | 'oauth2' | 'openIdConnect';
+    /**
+     * Generate the OpenAPI security scheme object
+     * This will be added to components.securitySchemes in the OpenAPI spec
+     * @returns SecuritySchemeObject compliant with OpenAPI 3.1
+     */
+    abstract getSecurityScheme(): SecuritySchemeObject;
+    /**
+     * Generate the OpenAPI security requirement
+     * This defines which security scheme is required for an operation
+     * Can be overridden for schemes that require specific scopes (OAuth2)
+     * @returns SecurityRequirementObject compliant with OpenAPI 3.1
+     */
+    getSecurityRequirement(): SecurityRequirementObject;
+    /**
+     * Generate the Express middleware that enforces this authentication
+     * The middleware should validate the authentication and throw appropriate
+     * HTTPError instances if authentication fails
+     * @returns Express RequestHandler middleware
+     */
+    abstract getMiddleware(): RequestHandler;
+}

package/authentication/authentication-scheme.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthenticationScheme = void 0;
+/**
+ * Abstract base class for authentication schemes
+ * Extend this class to create custom authentication schemes that integrate
+ * with both Express middleware and OpenAPI specification generation
+ */
+class AuthenticationScheme {
+    /**
+     * Generate the OpenAPI security requirement
+     * This defines which security scheme is required for an operation
+     * Can be overridden for schemes that require specific scopes (OAuth2)
+     * @returns SecurityRequirementObject compliant with OpenAPI 3.1
+     */
+    getSecurityRequirement() {
+        return { [this.schemeName]: [] };
+    }
+}
+exports.AuthenticationScheme = AuthenticationScheme;
+//# sourceMappingURL=authentication-scheme.js.map

package/authentication/authentication-scheme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authentication-scheme.js","sourceRoot":"","sources":["../../../src/authentication/authentication-scheme.ts"],"names":[],"mappings":";;;AAMA;;;;GAIG;AACH,MAAsB,oBAAoB;IAuBzC;;;;;OAKG;IACI,sBAAsB;QAC5B,OAAO,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,EAAE,CAAC;IAClC,CAAC;CASD;AAxCD,oDAwCC"}

package/authentication/index.d.ts

@@ -0,0 +1,4 @@
+export { AuthenticatedRequest } from './authenticated-request';
+export { AuthenticationScheme } from './authentication-scheme';
+export * from './middleware';
+export * from './schemes';

package/authentication/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthenticationScheme = void 0;
+const tslib_1 = require("tslib");
+var authentication_scheme_1 = require("./authentication-scheme");
+Object.defineProperty(exports, "AuthenticationScheme", { enumerable: true, get: function () { return authentication_scheme_1.AuthenticationScheme; } });
+tslib_1.__exportStar(require("./middleware"), exports);
+tslib_1.__exportStar(require("./schemes"), exports);
+//# sourceMappingURL=index.js.map

package/authentication/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/authentication/index.ts"],"names":[],"mappings":";;;;AACA,iEAA+D;AAAtD,6HAAA,oBAAoB,OAAA;AAC7B,uDAA6B;AAC7B,oDAA0B"}

package/authentication/middleware/bearer-authentication.d.ts

@@ -0,0 +1,12 @@
+import { Response, NextFunction } from 'express';
+import { AuthenticatedRequest } from '../authenticated-request';
+import { LogInterface } from '../../log';
+export interface BearerAuthenticationMiddlewareOptions {
+    checkToken: (token: string) => Promise<boolean>;
+    log?: LogInterface;
+}
+/**
+ * Bearer token authentication middleware
+ * Validates the Authorization header against the configured bearer token
+ */
+export declare function bearerAuthenticationMiddleware(options: BearerAuthenticationMiddlewareOptions): (req: AuthenticatedRequest, res: Response, next: NextFunction) => Promise<void>;

package/authentication/middleware/bearer-authentication.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bearerAuthenticationMiddleware = void 0;
+const error_1 = require("../../error");
+const valsan_1 = require("valsan");
+/**
+ * Bearer token authentication middleware
+ * Validates the Authorization header against the configured bearer token
+ */
+function bearerAuthenticationMiddleware(options) {
+    return async function (req, res, next) {
+        const authHeader = req.headers['authorization'] || req.headers['Authorization'];
+        if (!authHeader) {
+            options.log?.warn('Unauthorized access attempt from ' +
+                req.ip +
+                ' - No token provided');
+            throw new error_1.UnauthorizedError('Authorization header is missing', {
+                scheme: 'Bearer',
+            });
+        }
+        const validationResult = await new valsan_1.BearerTokenValSan().run(authHeader);
+        let token;
+        if (validationResult.success) {
+            token = validationResult.data;
+        }
+        else {
+            options.log?.warn('Unauthorized access attempt from ' +
+                req.ip +
+                ' - Invalid token format', JSON.stringify(validationResult.errors, null, 2));
+            throw new error_1.UnauthorizedError('Bearer token is empty or invalid', {
+                scheme: 'Bearer',
+                details: validationResult.errors,
+            });
+        }
+        if (!(await options.checkToken(token))) {
+            options.log?.warn('Unauthorized access attempt from ' +
+                req.ip +
+                ' - Check token failed');
+            throw new error_1.UnauthorizedError('Bearer token check failed', {
+                scheme: 'Bearer',
+            });
+        }
+        req.authenticated = true;
+        next();
+        return;
+    };
+}
+exports.bearerAuthenticationMiddleware = bearerAuthenticationMiddleware;
+//# sourceMappingURL=bearer-authentication.js.map

package/authentication/middleware/bearer-authentication.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bearer-authentication.js","sourceRoot":"","sources":["../../../../src/authentication/middleware/bearer-authentication.ts"],"names":[],"mappings":";;;AACA,uCAAgD;AAEhD,mCAA2C;AAQ3C;;;GAGG;AACH,SAAgB,8BAA8B,CAC7C,OAA8C;IAE9C,OAAO,KAAK,WACX,GAAyB,EACzB,GAAa,EACb,IAAkB;QAElB,MAAM,UAAU,GACf,GAAG,CAAC,OAAO,CAAC,eAAe,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;QAE9D,IAAI,CAAC,UAAU,EAAE,CAAC;YACjB,OAAO,CAAC,GAAG,EAAE,IAAI,CAChB,mCAAmC;gBAClC,GAAG,CAAC,EAAE;gBACN,sBAAsB,CACvB,CAAC;YAEF,MAAM,IAAI,yBAAiB,CAAC,iCAAiC,EAAE;gBAC9D,MAAM,EAAE,QAAQ;aAChB,CAAC,CAAC;QACJ,CAAC;QAED,MAAM,gBAAgB,GAAG,MAAM,IAAI,0BAAiB,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACvE,IAAI,KAAa,CAAC;QAElB,IAAI,gBAAgB,CAAC,OAAO,EAAE,CAAC;YAC9B,KAAK,GAAG,gBAAgB,CAAC,IAAK,CAAC;QAChC,CAAC;aACI,CAAC;YACL,OAAO,CAAC,GAAG,EAAE,IAAI,CAChB,mCAAmC;gBAClC,GAAG,CAAC,EAAE;gBACN,yBAAyB,EAC1B,IAAI,CAAC,SAAS,CAAC,gBAAgB,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAChD,CAAC;YAEF,MAAM,IAAI,yBAAiB,CAAC,kCAAkC,EAAE;gBAC/D,MAAM,EAAE,QAAQ;gBAChB,OAAO,EAAE,gBAAgB,CAAC,MAAM;aAChC,CAAC,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,CAAC,MAAM,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;YACxC,OAAO,CAAC,GAAG,EAAE,IAAI,CAChB,mCAAmC;gBAClC,GAAG,CAAC,EAAE;gBACN,uBAAuB,CACxB,CAAC;YAEF,MAAM,IAAI,yBAAiB,CAAC,2BAA2B,EAAE;gBACxD,MAAM,EAAE,QAAQ;aAChB,CAAC,CAAC;QACJ,CAAC;QAED,GAAG,CAAC,aAAa,GAAG,IAAI,CAAC;QACzB,IAAI,EAAE,CAAC;QAEP,OAAO;IACR,CAAC,CAAC;AACH,CAAC;AA5DD,wEA4DC"}

package/authentication/middleware/index.d.ts

@@ -0,0 +1 @@
+export { bearerAuthenticationMiddleware } from './bearer-authentication';

package/authentication/middleware/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bearerAuthenticationMiddleware = void 0;
+var bearer_authentication_1 = require("./bearer-authentication");
+Object.defineProperty(exports, "bearerAuthenticationMiddleware", { enumerable: true, get: function () { return bearer_authentication_1.bearerAuthenticationMiddleware; } });
+//# sourceMappingURL=index.js.map

package/authentication/middleware/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/authentication/middleware/index.ts"],"names":[],"mappings":";;;AAAA,iEAAyE;AAAhE,uIAAA,8BAA8B,OAAA"}

package/authentication/schemes/bearer-authentication-scheme.d.ts

@@ -0,0 +1,37 @@
+import { RequestHandler } from 'express';
+import { AuthenticationScheme } from '../authentication-scheme';
+import { SecuritySchemeObject } from 'auto-oas/oas/v3.1';
+import { BearerAuthenticationMiddlewareOptions } from '../middleware/bearer-authentication';
+export interface BearerAuthenticationSchemeOptions extends BearerAuthenticationMiddlewareOptions {
+    /**
+     * The name of the security scheme in OpenAPI
+     * @default 'BearerAuth'
+     */
+    schemeName?: string;
+    /**
+     * Format of the bearer token (e.g., 'JWT')
+     * This is informational and appears in the OpenAPI spec
+     * @default 'JWT'
+     */
+    bearerFormat?: string;
+    /**
+     * Description of the authentication scheme
+     * Appears in the OpenAPI documentation
+     */
+    description?: string;
+}
+/**
+ * Bearer token authentication scheme
+ * Validates the Authorization header with Bearer token
+ * Automatically generates OpenAPI security scheme documentation
+ */
+export declare class BearerAuthenticationScheme extends AuthenticationScheme {
+    readonly type: "http";
+    readonly schemeName: string;
+    private readonly bearerFormat;
+    private readonly description?;
+    private readonly middlewareOptions;
+    constructor(options: BearerAuthenticationSchemeOptions);
+    getSecurityScheme(): SecuritySchemeObject;
+    getMiddleware(): RequestHandler;
+}

package/authentication/schemes/bearer-authentication-scheme.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BearerAuthenticationScheme = void 0;
+const authentication_scheme_1 = require("../authentication-scheme");
+const bearer_authentication_1 = require("../middleware/bearer-authentication");
+/**
+ * Bearer token authentication scheme
+ * Validates the Authorization header with Bearer token
+ * Automatically generates OpenAPI security scheme documentation
+ */
+class BearerAuthenticationScheme extends authentication_scheme_1.AuthenticationScheme {
+    type = 'http';
+    schemeName;
+    bearerFormat;
+    description;
+    middlewareOptions;
+    constructor(options) {
+        super();
+        this.schemeName = options.schemeName || 'BearerAuth';
+        this.bearerFormat = options.bearerFormat || 'JWT';
+        this.description = options.description;
+        this.middlewareOptions = {
+            checkToken: options.checkToken,
+            log: options.log,
+        };
+    }
+    getSecurityScheme() {
+        const scheme = {
+            type: 'http',
+            scheme: 'bearer',
+            bearerFormat: this.bearerFormat,
+        };
+        if (this.description) {
+            scheme.description = this.description;
+        }
+        return scheme;
+    }
+    getMiddleware() {
+        return (0, bearer_authentication_1.bearerAuthenticationMiddleware)(this.middlewareOptions);
+    }
+}
+exports.BearerAuthenticationScheme = BearerAuthenticationScheme;
+//# sourceMappingURL=bearer-authentication-scheme.js.map

package/authentication/schemes/bearer-authentication-scheme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bearer-authentication-scheme.js","sourceRoot":"","sources":["../../../../src/authentication/schemes/bearer-authentication-scheme.ts"],"names":[],"mappings":";;;AACA,oEAAgE;AAEhE,+EAG6C;AAwB7C;;;;GAIG;AACH,MAAa,0BAA2B,SAAQ,4CAAoB;IACnD,IAAI,GAAG,MAAe,CAAC;IACvB,UAAU,CAAS;IAElB,YAAY,CAAS;IACrB,WAAW,CAAU;IACrB,iBAAiB,CAAwC;IAE1E,YAAY,OAA0C;QACrD,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,YAAY,CAAC;QACrD,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,KAAK,CAAC;QAClD,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;QACvC,IAAI,CAAC,iBAAiB,GAAG;YACxB,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,GAAG,EAAE,OAAO,CAAC,GAAG;SAChB,CAAC;IACH,CAAC;IAEM,iBAAiB;QACvB,MAAM,MAAM,GAAyB;YACpC,IAAI,EAAE,MAAM;YACZ,MAAM,EAAE,QAAQ;YAChB,YAAY,EAAE,IAAI,CAAC,YAAY;SAC/B,CAAC;QAEF,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACtB,MAAM,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACvC,CAAC;QAED,OAAO,MAAM,CAAC;IACf,CAAC;IAEM,aAAa;QACnB,OAAO,IAAA,sDAA8B,EAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;IAC/D,CAAC;CACD;AApCD,gEAoCC"}

package/authentication/schemes/index.d.ts

@@ -0,0 +1 @@
+export { BearerAuthenticationScheme } from './bearer-authentication-scheme';