api-machine 1.3.0 → 1.4.0

package/CHANGELOG.md

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

package/LICENSE.md

@@ -1,20 +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.
+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

@@ -1,275 +1,275 @@
-# API-Machine
-
-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
-
-### Example with Options
-
-```typescript
-const server = new MyApiServer({
-  port: 8080,
-  maxPayloadSizeMB: 20,
-  maxUrlEncodedSizeMB: 2,
-  log: myCustomLogger
-});
-```
-
-#### 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 {};
-	}
-}
-```
-
-#### Pre-Built Endpoints
-
-##### HealthCheckEndpoint
-
-A ready-to-use health check endpoint that returns system status information. Simply include it in your router. 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:**
-- 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 ObjectValSan members on your endpoint classes for `body`, `query`, `params`, or `headers`:
-
-```typescript
-import { ObjectValSan, EmailValidator } from 'valsan';
-import { NameValSan } from './examples/complete-example/users/name-valsan';
-
-class CreateUserEndpoint extends PostEndpoint {
-	override path = '/users';
-
-	override body = new ObjectValSan({
-		schema: {
-			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 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!
+# API-Machine
+
+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
+
+### Example with Options
+
+```typescript
+const server = new MyApiServer({
+  port: 8080,
+  maxPayloadSizeMB: 20,
+  maxUrlEncodedSizeMB: 2,
+  log: myCustomLogger
+});
+```
+
+#### 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 {};
+	}
+}
+```
+
+#### Pre-Built Endpoints
+
+##### HealthCheckEndpoint
+
+A ready-to-use health check endpoint that returns system status information. Simply include it in your router. 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:**
+- 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 ObjectValSan members on your endpoint classes for `body`, `query`, `params`, or `headers`:
+
+```typescript
+import { ObjectValSan, EmailValidator } from 'valsan';
+import { NameValSan } from './examples/complete-example/users/name-valsan';
+
+class CreateUserEndpoint extends PostEndpoint {
+	override path = '/users';
+
+	override body = new ObjectValSan({
+		schema: {
+			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 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/authentication-scheme.d.ts

@@ -40,6 +40,11 @@ export declare abstract class AuthenticationScheme {
      */
     abstract getMiddleware(): RequestHandler;
 }
+export interface AuthenticationProtectionResult {
+    allowed: boolean;
+    retryAfterSeconds?: number;
+}
+export declare function throwIfAuthenticationBlocked(result: AuthenticationProtectionResult): void;
 export declare abstract class InlineAuthenticationScheme extends AuthenticationScheme {
     abstract getCredentials(request: ApiRequest): unknown;
     abstract authenticate(options: {

package/authentication/authentication-scheme.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SessionAuthenticationScheme = exports.InlineAuthenticationScheme = exports.AuthenticationScheme = void 0;
+exports.SessionAuthenticationScheme = exports.InlineAuthenticationScheme = exports.throwIfAuthenticationBlocked = exports.AuthenticationScheme = void 0;
 const router_1 = require("../router");
+const error_1 = require("../error");
 /**
  * Abstract base class for authentication schemes
  * Extend this class to create custom authentication schemes that integrate
@@ -21,6 +22,18 @@ class AuthenticationScheme {
     }
 }
 exports.AuthenticationScheme = AuthenticationScheme;
+function throwIfAuthenticationBlocked(result) {
+    if (result.allowed) {
+        return;
+    }
+    throw new error_1.TooManyRequestsError('Authentication temporarily unavailable', {
+        retryAfter: typeof result.retryAfterSeconds === 'number' &&
+            result.retryAfterSeconds > 0
+            ? result.retryAfterSeconds
+            : undefined,
+    });
+}
+exports.throwIfAuthenticationBlocked = throwIfAuthenticationBlocked;
 class InlineAuthenticationScheme extends AuthenticationScheme {
     /**
      * Generate the Express middleware that enforces this authentication

package/authentication/authentication-scheme.js.map

@@ -1 +1 @@
-{"version":3,"file":"authentication-scheme.js","sourceRoot":"","sources":["../../../src/authentication/authentication-scheme.ts"],"names":[],"mappings":";;;AAKA,sCAKmB;AASnB;;;;GAIG;AACH,MAAsB,oBAAoB;IACzC,6DAA6D;IAC7D,YAAmB,UAAuC,EAAE,IAAG,CAAC;IAehE;;;;;OAKG;IACI,sBAAsB;QAC5B,OAAO,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,EAAE,CAAC;IAClC,CAAC;CAUD;AAnCD,oDAmCC;AAED,MAAsB,0BAA2B,SAAQ,oBAAoB;IAO5E;;;;;OAKG;IACI,aAAa;QACnB,OAAO,KAAK,EACX,OAA6B,EAC7B,QAAqB,EACrB,IAAqB,EACpB,EAAE;YACH,MAAM,WAAW,GAAG,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;YACjD,MAAM,IAAI,CAAC,YAAY,CAAC,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,CAAC;YAElD,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;YAE7B,OAAO,IAAI,EAAE,CAAC;QACf,CAAC,CAAC;IACH,CAAC;CACD;AA3BD,gEA2BC;AAED,MAAsB,2BAA4B,SAAQ,oBAAoB;IACnE,aAAa,CAAgB;IAEvC,YAAmB,OAAyC;QAC3D,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;IAC5C,CAAC;IAWD;;;;OAIG;IACI,YAAY;QAClB,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QAChC,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAED;;;;;;OAMG;IACI,aAAa,CAAC,QAAQ,GAAG,EAAE;QACjC,MAAM,SAAS,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;QAEtC,OAAO,IAAI,CAAC,KAAM,SAAQ,sBAAa;YAC7B,IAAI,GAAG,QAAQ,CAAC;YAEzB,KAAK,CAAC,MAAM;gBACX,OAAO,SAAS,CAAC;YAClB,CAAC;SACD,CAAC,EAAE,CAAC;IACN,CAAC;IAEM,aAAa;QACnB,OAAO,KAAK,EACX,OAA6B,EAC7B,QAAqB,EACrB,IAAqB,EACpB,EAAE;YACH,MAAM,IAAI,CAAC,aAAa,CAAC,YAAY,CAAC;gBACrC,8DAA8D;gBAC9D,SAAS,EAAG,OAAe,CAAC,SAAS;aACrC,CAAC,CAAC;YAEH,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;YAC7B,OAAO,IAAI,EAAE,CAAC;QACf,CAAC,CAAC;IACH,CAAC;CACD;AA7DD,kEA6DC"}
+{"version":3,"file":"authentication-scheme.js","sourceRoot":"","sources":["../../../src/authentication/authentication-scheme.ts"],"names":[],"mappings":";;;AAKA,sCAKmB;AAEnB,oCAAgD;AAQhD;;;;GAIG;AACH,MAAsB,oBAAoB;IACzC,6DAA6D;IAC7D,YAAmB,UAAuC,EAAE,IAAG,CAAC;IAehE;;;;;OAKG;IACI,sBAAsB;QAC5B,OAAO,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,EAAE,CAAC;IAClC,CAAC;CAUD;AAnCD,oDAmCC;AAOD,SAAgB,4BAA4B,CAC3C,MAAsC;IAEtC,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,OAAO;IACR,CAAC;IAED,MAAM,IAAI,4BAAoB,CAAC,wCAAwC,EAAE;QACxE,UAAU,EACT,OAAO,MAAM,CAAC,iBAAiB,KAAK,QAAQ;YAC5C,MAAM,CAAC,iBAAiB,GAAG,CAAC;YAC3B,CAAC,CAAC,MAAM,CAAC,iBAAiB;YAC1B,CAAC,CAAC,SAAS;KACb,CAAC,CAAC;AACJ,CAAC;AAdD,oEAcC;AAED,MAAsB,0BAA2B,SAAQ,oBAAoB;IAO5E;;;;;OAKG;IACI,aAAa;QACnB,OAAO,KAAK,EACX,OAA6B,EAC7B,QAAqB,EACrB,IAAqB,EACpB,EAAE;YACH,MAAM,WAAW,GAAG,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;YACjD,MAAM,IAAI,CAAC,YAAY,CAAC,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,CAAC;YAElD,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;YAE7B,OAAO,IAAI,EAAE,CAAC;QACf,CAAC,CAAC;IACH,CAAC;CACD;AA3BD,gEA2BC;AAED,MAAsB,2BAA4B,SAAQ,oBAAoB;IACnE,aAAa,CAAgB;IAEvC,YAAmB,OAAyC;QAC3D,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;IAC5C,CAAC;IAWD;;;;OAIG;IACI,YAAY;QAClB,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QAChC,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAED;;;;;;OAMG;IACI,aAAa,CAAC,QAAQ,GAAG,EAAE;QACjC,MAAM,SAAS,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;QAEtC,OAAO,IAAI,CAAC,KAAM,SAAQ,sBAAa;YAC7B,IAAI,GAAG,QAAQ,CAAC;YAEzB,KAAK,CAAC,MAAM;gBACX,OAAO,SAAS,CAAC;YAClB,CAAC;SACD,CAAC,EAAE,CAAC;IACN,CAAC;IAEM,aAAa;QACnB,OAAO,KAAK,EACX,OAA6B,EAC7B,QAAqB,EACrB,IAAqB,EACpB,EAAE;YACH,MAAM,IAAI,CAAC,aAAa,CAAC,YAAY,CAAC;gBACrC,8DAA8D;gBAC9D,SAAS,EAAG,OAAe,CAAC,SAAS;aACrC,CAAC,CAAC;YAEH,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;YAC7B,OAAO,IAAI,EAAE,CAAC;QACf,CAAC,CAAC;IACH,CAAC;CACD;AA7DD,kEA6DC"}

package/authentication/index.d.ts

@@ -1,4 +1,4 @@
 export { AuthenticatedRequest } from './authenticated-request';
-export { AuthenticationScheme, InlineAuthenticationScheme, SessionAuthenticationScheme, } from './authentication-scheme';
+export { AuthenticationScheme, InlineAuthenticationScheme, SessionAuthenticationScheme, throwIfAuthenticationBlocked, AuthenticationProtectionResult, } from './authentication-scheme';
 export { AuthFlow } from './auth-flow';
 export * from './schemes';

package/authentication/index.js

@@ -1,10 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SessionAuthenticationScheme = exports.InlineAuthenticationScheme = exports.AuthenticationScheme = void 0;
+exports.throwIfAuthenticationBlocked = exports.SessionAuthenticationScheme = exports.InlineAuthenticationScheme = 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; } });
 Object.defineProperty(exports, "InlineAuthenticationScheme", { enumerable: true, get: function () { return authentication_scheme_1.InlineAuthenticationScheme; } });
 Object.defineProperty(exports, "SessionAuthenticationScheme", { enumerable: true, get: function () { return authentication_scheme_1.SessionAuthenticationScheme; } });
+Object.defineProperty(exports, "throwIfAuthenticationBlocked", { enumerable: true, get: function () { return authentication_scheme_1.throwIfAuthenticationBlocked; } });
 tslib_1.__exportStar(require("./schemes"), exports);
 //# sourceMappingURL=index.js.map

package/authentication/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/authentication/index.ts"],"names":[],"mappings":";;;;AACA,iEAIiC;AAHhC,6HAAA,oBAAoB,OAAA;AACpB,mIAAA,0BAA0B,OAAA;AAC1B,oIAAA,2BAA2B,OAAA;AAG5B,oDAA0B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/authentication/index.ts"],"names":[],"mappings":";;;;AACA,iEAMiC;AALhC,6HAAA,oBAAoB,OAAA;AACpB,mIAAA,0BAA0B,OAAA;AAC1B,oIAAA,2BAA2B,OAAA;AAC3B,qIAAA,4BAA4B,OAAA;AAI7B,oDAA0B"}

package/authentication/schemes/client-credentials-oauth2-scheme.d.ts

@@ -0,0 +1,64 @@
+import { AuthenticationSchemeOptions, InlineAuthenticationScheme } from '../authentication-scheme';
+import { SecuritySchemeObject } from 'auto-oas/oas/v3.1';
+import { LogInterface } from '../../log';
+import { ApiRequest } from '../../router';
+export type CheckTokenFunction = (token: string) => Promise<boolean>;
+export interface ClientCredentialsOAuth2SchemeOptions extends AuthenticationSchemeOptions {
+    /**
+     * The name of the security scheme in OpenAPI
+     * @default 'OAuth2ClientCredentials'
+     */
+    schemeName?: string;
+    /**
+     * Description of the authentication scheme
+     * Appears in the OpenAPI documentation
+     */
+    description?: string;
+    /**
+     * URL of the OAuth2 authorization server's token endpoint
+     * Used for OpenAPI documentation
+     * @default 'http://localhost:3000/oauth/token'
+     */
+    tokenUrl?: string;
+    /**
+     * Function to validate the access token
+     * Should return true if the token is valid, false otherwise
+     */
+    checkToken: CheckTokenFunction;
+    /**
+     * Optional logger for security events
+     */
+    log?: LogInterface;
+}
+/**
+ * OAuth2 Client Credentials authentication scheme
+ * Validates access tokens from the Authorization header using Bearer scheme
+ * Implements the OAuth2 Client Credentials flow for server-to-server authentication
+ * Automatically generates OpenAPI security scheme documentation
+ *
+ * Usage example:
+ * ```typescript
+ * const oauth2 = new ClientCredentialsOAuth2Scheme({
+ *   checkToken: async (token: string) => {
+ *     // Validate against your token store or OAuth2 provider
+ *     return validTokens.includes(token);
+ *   },
+ *   tokenUrl: 'https://auth-server.example.com/oauth/token',
+ *   schemeName: 'OAuth2',
+ * });
+ * ```
+ */
+export declare class ClientCredentialsOAuth2Scheme extends InlineAuthenticationScheme {
+    readonly schemeName: string;
+    protected readonly description?: string;
+    protected readonly tokenUrl: string;
+    protected readonly checkToken: CheckTokenFunction;
+    protected readonly log?: LogInterface;
+    constructor(options: ClientCredentialsOAuth2SchemeOptions);
+    getSecurityScheme(): SecuritySchemeObject;
+    getCredentials(request: ApiRequest): unknown;
+    authenticate(options: {
+        credentials: string;
+        request: ApiRequest;
+    }): Promise<void>;
+}

package/authentication/schemes/client-credentials-oauth2-scheme.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClientCredentialsOAuth2Scheme = void 0;
+const authentication_scheme_1 = require("../authentication-scheme");
+const error_1 = require("../../error");
+const primitives_1 = require("valsan/primitives");
+/**
+ * OAuth2 Client Credentials authentication scheme
+ * Validates access tokens from the Authorization header using Bearer scheme
+ * Implements the OAuth2 Client Credentials flow for server-to-server authentication
+ * Automatically generates OpenAPI security scheme documentation
+ *
+ * Usage example:
+ * ```typescript
+ * const oauth2 = new ClientCredentialsOAuth2Scheme({
+ *   checkToken: async (token: string) => {
+ *     // Validate against your token store or OAuth2 provider
+ *     return validTokens.includes(token);
+ *   },
+ *   tokenUrl: 'https://auth-server.example.com/oauth/token',
+ *   schemeName: 'OAuth2',
+ * });
+ * ```
+ */
+class ClientCredentialsOAuth2Scheme extends authentication_scheme_1.InlineAuthenticationScheme {
+    schemeName;
+    description;
+    tokenUrl;
+    checkToken;
+    log;
+    constructor(options) {
+        super(options);
+        this.schemeName = options.schemeName || 'OAuth2ClientCredentials';
+        this.description = options.description;
+        this.tokenUrl = options.tokenUrl || 'http://localhost:3000/oauth/token';
+        this.checkToken = options.checkToken;
+        this.log = options.log;
+    }
+    getSecurityScheme() {
+        const scheme = {
+            type: 'oauth2',
+            flows: {
+                clientCredentials: {
+                    tokenUrl: this.tokenUrl,
+                    scopes: {},
+                },
+            },
+        };
+        if (this.description) {
+            scheme.description = this.description;
+        }
+        return scheme;
+    }
+    getCredentials(request) {
+        const authHeader = request.headers['authorization'] ||
+            request.headers['Authorization'];
+        if (!authHeader) {
+            const msg = 'Unauthorized access attempt from ' +
+                request.ip +
+                ' - No access token provided';
+            this.log?.warn(msg);
+            throw new error_1.UnauthorizedError('Authorization header is missing', {
+                scheme: 'Bearer',
+            });
+        }
+        return authHeader;
+    }
+    async authenticate(options) {
+        const { credentials, request } = options;
+        if (!credentials) {
+            throw new error_1.UnauthorizedError('Authorization header is missing', {
+                scheme: 'Bearer',
+            });
+        }
+        const validationResult = await new primitives_1.BearerTokenValSan().run(credentials);
+        if (!validationResult.success || !validationResult.data) {
+            const msg = 'Unauthorized access attempt from ' +
+                request.ip +
+                ' - Invalid access token format';
+            const details = JSON.stringify(validationResult.errors, null, 2);
+            this.log?.warn(msg, details);
+            throw new error_1.UnauthorizedError('Access token is empty or invalid', {
+                scheme: 'Bearer',
+                details: validationResult.errors,
+            });
+        }
+        if (!(await this.checkToken(validationResult.data))) {
+            const msg = 'Unauthorized access attempt from ' +
+                request.ip +
+                ' - Access token validation failed';
+            this.log?.warn(msg);
+            throw new error_1.UnauthorizedError('Access token validation failed', {
+                scheme: 'Bearer',
+            });
+        }
+    }
+}
+exports.ClientCredentialsOAuth2Scheme = ClientCredentialsOAuth2Scheme;
+//# sourceMappingURL=client-credentials-oauth2-scheme.js.map

package/authentication/schemes/client-credentials-oauth2-scheme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-credentials-oauth2-scheme.js","sourceRoot":"","sources":["../../../../src/authentication/schemes/client-credentials-oauth2-scheme.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "api-machine",
-	"version": "1.3.0",
+	"version": "1.4.0",
 	"description": "api-machine",
 	"typescript-template": {
 		"base": "1.0.1",

package/di/container.d.ts

@@ -1,31 +0,0 @@
-export declare class DependencyContainer {
-    protected dependencies: Map<string, any>;
-    protected parent?: DependencyContainer;
-    constructor(parent?: DependencyContainer);
-    /**
-     * Register a dependency
-     * @param key The key to register the dependency under
-     * @param value The dependency value
-     */
-    register<T>(key: string, value: T): void;
-    /**
-     * Get a dependency, searching up the parent chain if not found locally
-     * @param key The key of the dependency to retrieve
-     * @returns The dependency value, or undefined if not found
-     */
-    get<T>(key: string): T | undefined;
-    /**
-     * Check if a dependency exists in the container or its parents
-     * @param key The key to check
-     */
-    has(key: string): boolean;
-    /**
-     * Create a child container that inherits from this one
-     */
-    createChild(): DependencyContainer;
-    /**
-     * Set the parent container
-     * @internal
-     */
-    setParent(parent: DependencyContainer): void;
-}

package/di/container.js

@@ -1,57 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DependencyContainer = void 0;
-class DependencyContainer {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    dependencies = new Map();
-    // eslint-disable-next-line no-use-before-define
-    parent;
-    // eslint-disable-next-line no-use-before-define
-    constructor(parent) {
-        this.parent = parent;
-    }
-    /**
-     * Register a dependency
-     * @param key The key to register the dependency under
-     * @param value The dependency value
-     */
-    register(key, value) {
-        this.dependencies.set(key, value);
-    }
-    /**
-     * Get a dependency, searching up the parent chain if not found locally
-     * @param key The key of the dependency to retrieve
-     * @returns The dependency value, or undefined if not found
-     */
-    get(key) {
-        if (this.dependencies.has(key)) {
-            return this.dependencies.get(key);
-        }
-        if (this.parent) {
-            return this.parent.get(key);
-        }
-        return undefined;
-    }
-    /**
-     * Check if a dependency exists in the container or its parents
-     * @param key The key to check
-     */
-    has(key) {
-        return this.dependencies.has(key) || (this.parent?.has(key) ?? false);
-    }
-    /**
-     * Create a child container that inherits from this one
-     */
-    createChild() {
-        return new DependencyContainer(this);
-    }
-    /**
-     * Set the parent container
-     * @internal
-     */
-    setParent(parent) {
-        this.parent = parent;
-    }
-}
-exports.DependencyContainer = DependencyContainer;
-//# sourceMappingURL=container.js.map

package/di/container.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"container.js","sourceRoot":"","sources":["../../../src/di/container.ts"],"names":[],"mappings":";;;AAAA,MAAa,mBAAmB;IAC/B,8DAA8D;IACpD,YAAY,GAAqB,IAAI,GAAG,EAAE,CAAC;IACrD,gDAAgD;IACtC,MAAM,CAAuB;IAEvC,gDAAgD;IAChD,YAAY,MAA4B;QACvC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACtB,CAAC;IAED;;;;OAIG;IACI,QAAQ,CAAI,GAAW,EAAE,KAAQ;QACvC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACnC,CAAC;IAED;;;;OAIG;IACI,GAAG,CAAI,GAAW;QACxB,IAAI,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAChC,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAM,CAAC;QACxC,CAAC;QAED,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAI,GAAG,CAAC,CAAC;QAChC,CAAC;QAED,OAAO,SAAS,CAAC;IAClB,CAAC;IAED;;;OAGG;IACI,GAAG,CAAC,GAAW;QACrB,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,CAAC;IACvE,CAAC;IAED;;OAEG;IACI,WAAW;QACjB,OAAO,IAAI,mBAAmB,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC;IAED;;;OAGG;IACI,SAAS,CAAC,MAA2B;QAC3C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACtB,CAAC;CACD;AA3DD,kDA2DC"}