example: added authentication examples

Author: DrewImm

examples/complete-example/README.md

@@ -72,6 +72,51 @@ curl "http://localhost:3000/api/express/search?q=test&page=2&limit=20"
 curl http://localhost:3000/api/health
 ```
 
+### Bearer Token Authentication (Inline, Stateless)
+
+Bearer authentication validates a token on every request without maintaining session state.
+
+```bash
+# Test protected endpoint with valid token
+curl -H "Authorization: Bearer demo-token" \
+  http://localhost:3000/api/bearer/protected
+
+# Test without token (should return 401)
+curl http://localhost:3000/api/bearer/protected
+
+# Public endpoint in bearer router (no auth required)
+curl http://localhost:3000/api/bearer/public
+```
+
+### OAuth2 Session-Based Authentication (Stateful)
+
+Session-based authentication uses a multi-step OAuth2-like flow to obtain a session, then validates it on each request.
+
+```bash
+# Step 1: Get a challenge
+CHALLENGE=$(curl -s -X POST http://localhost:3000/oauth/challenge \
+  -H "Content-Type: application/json" -d '{}' | \
+  grep -o '"challenge":"[^"]*"' | cut -d'"' -f4)
+
+# Step 2: Authorize with credentials
+CODE=$(curl -s -X POST http://localhost:3000/oauth/authorize \
+  -H "Content-Type: application/json" \
+  -d "{\"username\": \"demo\", \"password\": \"demo\", \"challenge\": \"$CHALLENGE\"}" | \
+  grep -o '"code":"[^"]*"' | cut -d'"' -f4)
+
+# Step 3: Exchange code for session
+SESSIONID=$(curl -s -X POST http://localhost:3000/oauth/token \
+  -H "Content-Type: application/json" \
+  -d "{\"code\": \"$CODE\"}" | \
+  grep -o '"sessionId":"[^"]*"' | cut -d'"' -f4)
+
+# Step 4: Access protected resource with session
+curl -s -H "Cookie: sessionId=$SESSIONID" \
+  http://localhost:3000/oauth/protected && echo ""
+
+# Demo credentials: demo/demo or admin/admin
+```
+
 ## Key Points
 
 ### Domain-Driven Organization
@@ -120,6 +165,7 @@ complete-example/
 ├── index.ts                                   # Entry point
 ├── server.ts                                  # Server with custom logger
 ├── router.ts                                  # Main router (groups domain routers)
+├── authentication.ts                          # Bearer and OAuth2 auth schemes
 ├── users/                                     # User management domain
 │   ├── users-router.ts                        # Groups under /api/users
 │   ├── list-users-endpoint.ts                 # GET /api/users
@@ -143,4 +189,24 @@ After completing the quick-start example, this example demonstrates:
 5. How to validate input and handle errors gracefully
 6. How to configure and use custom loggers
 7. How to leverage Express features within your endpoints
-8. Best practices for structuring a production-ready API
+8. How to implement Bearer token authentication (inline, stateless)
+9. How to implement OAuth2 session-based authentication (stateful, multi-step)
+10. Best practices for structuring a production-ready API with authentication
+
+## Authentication Approaches
+
+This example demonstrates two authentication approaches:
+
+### Bearer Token (Inline) Authentication
+- **When to use**: Stateless APIs, JWT validation, API key authentication
+- **How it works**: Token is validated on every request
+- **Credentials**: Bearer token in Authorization header
+- **Session**: None - token itself is the credential
+- **Example**: `authentication.ts` - `BearerAuthRouter`
+
+### OAuth2 Session-Based Authentication
+- **When to use**: Stateful flows, user login, multi-factor auth
+- **How it works**: Multi-step flow to obtain session, then session is validated
+- **Credentials**: Username/password exchanged for session
+- **Session**: Server-side session ID in cookies
+- **Example**: `authentication.ts` - `OAuth2Router` and `oauth2Scheme`

examples/complete-example/auth/inline-auth.ts

@@ -0,0 +1,73 @@
+/**
+ * Inline (Bearer Token) Authentication
+ *
+ * This module demonstrates stateless, token-based authentication.
+ * Token validation occurs on every request without session storage.
+ */
+
+import {
+	BaseApiRouter,
+	BaseApiEndpoint,
+	BearerAuthenticationScheme,
+	ApiRequest,
+	ApiResponse,
+} from '../../../src/index';
+
+/**
+ * Bearer authentication for simple token-based APIs
+ * Token validation on every request
+ */
+export const bearerAuth = new BearerAuthenticationScheme({
+	checkToken: async (token: string) => {
+		// In production: validate JWT signature, check expiration, etc.
+		const validTokens = ['demo-token', 'admin-token', 'user-token'];
+		return validTokens.includes(token);
+	},
+	schemeName: 'BearerAuth',
+	bearerFormat: 'JWT',
+	description: 'Bearer token authentication',
+});
+
+/**
+ * Protected endpoint that requires Bearer token authentication
+ */
+export class BearerProtectedEndpoint extends BaseApiEndpoint {
+	override path = '/protected';
+	override description = 'Protected resource requiring Bearer token';
+
+	async handle(request: ApiRequest, response: ApiResponse) {
+		return {
+			message: 'You accessed a protected resource',
+			timestamp: new Date().toISOString(),
+		};
+	}
+}
+
+/**
+ * Public endpoint in the Bearer router (no auth required)
+ */
+export class BearerPublicEndpoint extends BaseApiEndpoint {
+	override path = '/public';
+	override description = 'Public resource (no authentication)';
+	override authentication = null;
+
+	async handle(request: ApiRequest, response: ApiResponse) {
+		return {
+			message: 'Public data',
+			authType: 'Bearer Token',
+		};
+	}
+}
+
+/**
+ * Router for Bearer token authentication endpoints
+ */
+export class BearerAuthRouter extends BaseApiRouter {
+	override path = '/bearer';
+	override description = 'Bearer token authentication endpoints';
+	override authentication = bearerAuth;
+
+	async routes() {
+		return [BearerProtectedEndpoint, BearerPublicEndpoint];
+	}
+}

examples/complete-example/auth/session-auth.ts

@@ -0,0 +1,234 @@
+/**
+ * Session-Based (OAuth2-like) Authentication
+ *
+ * This module demonstrates stateful, multi-step authentication.
+ * Implements a challenge-based flow similar to OAuth2 authorization code flow.
+ */
+
+import {
+	BaseApiRouter,
+	BaseApiEndpoint,
+	SessionAuthenticationScheme,
+	AuthFlow,
+	AuthStep,
+	InMemorySessionDriver,
+	ApiRequest,
+	ApiResponse,
+	UnauthorizedError,
+} from '../../../src/index';
+import { EndpointMethod } from '../../../src/router/endpoint';
+import { SecuritySchemeObject } from 'auto-oas/oas/v3.1';
+
+// Simple in-memory storage for demonstration
+const storedChallenges = new Map<string, { timestamp: number }>();
+const storedAuthCodes = new Map<
+	string,
+	{ username: string; timestamp: number }
+>();
+
+/**
+ * Session-based OAuth2-like authentication scheme
+ */
+class OAuth2Scheme extends SessionAuthenticationScheme {
+	public readonly schemeName = 'OAuth2';
+	public readonly type = 'oauth2' as const;
+
+	constructor() {
+		super({ sessionDriver: new InMemorySessionDriver() });
+	}
+
+	public getSecurityScheme(): SecuritySchemeObject {
+		return {
+			type: 'oauth2' as const,
+			flows: {
+				authorizationCode: {
+					authorizationUrl: 'http://localhost:3000/oauth/authorize',
+					tokenUrl: 'http://localhost:3000/oauth/token',
+					scopes: { 'read:data': 'Read data' },
+				},
+			},
+		};
+	}
+
+	public getAuthFlow(): AuthFlow {
+		const sessionDriver = this.sessionDriver;
+
+		/**
+		 * Challenge step - generates a random challenge for CSRF prevention
+		 */
+		class ChallengeStep extends AuthStep {
+			override path = '/challenge';
+			override method = EndpointMethod.POST;
+			override description = 'Generate authentication challenge';
+
+			async handle(request: ApiRequest, response: ApiResponse) {
+				const challenge =
+					Math.random().toString(36).substring(2, 15) +
+					Math.random().toString(36).substring(2, 15);
+				storedChallenges.set(challenge, { timestamp: Date.now() });
+				return { challenge, expiresIn: 300 };
+			}
+		}
+
+		/**
+		 * Authorization step - validates credentials
+		 */
+		class AuthorizationStep extends AuthStep {
+			override path = '/authorize';
+			override method = EndpointMethod.POST;
+			override description = 'Authorize with username and password';
+
+			async handle(request: ApiRequest, response: ApiResponse) {
+				// eslint-disable-next-line @typescript-eslint/no-explicit-any
+				const { username, password, challenge } = request.body as any;
+
+				if (!username || !password || !challenge) {
+					throw new UnauthorizedError('Missing required fields');
+				}
+
+				const storedChallenge = storedChallenges.get(challenge);
+				if (!storedChallenge) {
+					throw new UnauthorizedError('Invalid or expired challenge');
+				}
+
+				if (Date.now() - storedChallenge.timestamp > 5 * 60 * 1000) {
+					storedChallenges.delete(challenge);
+					throw new UnauthorizedError('Challenge expired');
+				}
+
+				// Demo: accept demo/demo or admin/admin
+				const validUsers = [
+					{ username: 'demo', password: 'demo' },
+					{ username: 'admin', password: 'admin' },
+				];
+
+				const user = validUsers.find(
+					(u) => u.username === username && u.password === password
+				);
+
+				if (!user) {
+					throw new UnauthorizedError('Invalid credentials');
+				}
+
+				const code =
+					'code-' +
+					Math.random().toString(36).substring(2, 15) +
+					Math.random().toString(36).substring(2, 15);
+
+				storedAuthCodes.set(code, {
+					username: user.username,
+					timestamp: Date.now(),
+				});
+				storedChallenges.delete(challenge);
+
+				return { code, expiresIn: 60 };
+			}
+		}
+
+		/**
+		 * Token exchange step - exchanges code for session
+		 */
+		class TokenStep extends AuthStep {
+			override path = '/token';
+			override method = EndpointMethod.POST;
+			override description = 'Exchange authorization code for session';
+
+			async handle(request: ApiRequest, response: ApiResponse) {
+				// eslint-disable-next-line @typescript-eslint/no-explicit-any
+				const { code } = request.body as any;
+
+				if (!code) {
+					throw new UnauthorizedError('Missing authorization code');
+				}
+
+				const storedCode = storedAuthCodes.get(code);
+				if (!storedCode) {
+					throw new UnauthorizedError('Invalid or expired code');
+				}
+
+				if (Date.now() - storedCode.timestamp > 1 * 60 * 1000) {
+					storedAuthCodes.delete(code);
+					throw new UnauthorizedError('Code expired');
+				}
+
+				const sessionId =
+					'session-' +
+					Math.random().toString(36).substring(2, 15) +
+					Math.random().toString(36).substring(2, 15);
+
+				// Create session in the driver
+				sessionDriver.createSession({
+					id: sessionId,
+					username: storedCode.username,
+					createdAt: new Date(),
+					expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
+					// TODO: Fix session type
+					// eslint-disable-next-line max-len
+					// eslint-disable-next-line @typescript-eslint/no-explicit-any
+				} as any);
+
+				response.cookie('sessionId', sessionId, {
+					httpOnly: true,
+					maxAge: 24 * 60 * 60 * 1000,
+				});
+
+				storedAuthCodes.delete(code);
+
+				return {
+					sessionId,
+					username: storedCode.username,
+					expiresIn: 86400,
+				};
+			}
+		}
+
+		return {
+			challenge: ChallengeStep,
+			authorize: AuthorizationStep,
+			token: TokenStep,
+		};
+	}
+}
+
+/**
+ * Session-based authentication scheme instance
+ */
+export const oauth2Scheme = new OAuth2Scheme();
+
+/**
+ * Protected endpoint requiring session authentication
+ */
+export class SessionProtectedEndpoint extends BaseApiEndpoint {
+	override path = '/protected';
+	override description = 'Protected resource requiring session';
+	override authentication = oauth2Scheme;
+
+	async handle(request: ApiRequest, response: ApiResponse) {
+		return {
+			message: 'You accessed a session-protected resource',
+			timestamp: new Date().toISOString(),
+		};
+	}
+}
+
+/**
+ * Router for session-based OAuth2 authentication
+ */
+export class OAuth2Router extends BaseApiRouter {
+	override path = '/oauth';
+	override description = 'OAuth2 session-based authentication';
+	// Don't apply authentication to the auth steps themselves
+	override authentication = null;
+
+	async routes() {
+		// Return both auth flow steps and protected endpoint
+		const endpoints = oauth2Scheme.getEndpoints();
+
+		// Protected endpoint requires oauth2 authentication
+		class OAuth2ProtectedEndpoint extends SessionProtectedEndpoint {
+			override authentication = oauth2Scheme;
+		}
+
+		return [...endpoints, OAuth2ProtectedEndpoint];
+	}
+}