feat: refactor auth system for stateful & multi-step schemes

Author: DrewImm

docs/authentication.md

@@ -36,6 +36,26 @@ const server = new RestServer({
 });
 ```
 
+## Authentication Architecture
+
+api-machine supports two main types of authentication schemes:
+
+### Inline Authentication Schemes
+Run authentication inline **on every request**. Credentials are extracted and validated immediately:
+- Extract credentials from the request (e.g., Bearer tokens from Authorization header)
+- Validate credentials synchronously
+- Middleware runs for every incoming request
+- Examples: `BearerAuthenticationScheme`, API key schemes, JWT validation
+- Use for: Stateless authentication (tokens, API keys)
+
+### Session Authentication Schemes
+Provide an `AuthFlow` to **obtain a session**, then verify that session **on every request**:
+- Define multi-step authentication process using `AuthFlow` (e.g., challenge → authorization → token exchange)
+- Session is obtained once through the auth flow
+- Session is then validated by checking the session ID on each subsequent request
+- Examples: OAuth2, SAML, session-based authentication
+- Use for: Stateful authentication flows requiring multiple steps
+
 ## Authentication Cascading
 
 Authentication follows a priority hierarchy:
@@ -50,7 +70,7 @@ Authentication follows a priority hierarchy:
 ```typescript
 class PublicRouter extends BaseApiRouter {
   override path = '/public';
-  override authentication = null;  // Bypass server auth
+  override authentication = null;
 
   async routes() {
     return [PublicEndpoint];
@@ -61,7 +81,7 @@ class AdminEndpoint extends BaseApiEndpoint {
   override path = '/admin';
   override authentication = new BearerAuthenticationScheme({
     checkToken: async (token) => token === 'admin-token',
-  });  // Override router auth
+  });
 
   async handle() {
     return { admin: true };
@@ -73,7 +93,7 @@ class AdminEndpoint extends BaseApiEndpoint {
 
 ### Bearer Authentication
 
-Validates Bearer tokens from the `Authorization` header.
+Validates Bearer tokens from the `Authorization` header on **every request**. Uses `InlineAuthenticationScheme` for synchronous inline token validation.
 
 ```typescript
 import { BearerAuthenticationScheme } from 'api-machine';
@@ -89,12 +109,18 @@ const auth = new BearerAuthenticationScheme({
 });
 ```
 
-**Features:**
-- Automatically validates `Authorization: Bearer <token>` header format
+**How it works:**
+- Middleware runs for every incoming request
+- Extracts `Authorization: Bearer <token>` header
+- Validates token using `checkToken()` 
 - Returns 401 Unauthorized if token missing or invalid
-- Integrates with OpenAPI security schemes
 - Sets `request.authenticated = true` on successful validation
 
+**Architecture:**
+- Extends `InlineAuthenticationScheme` for stateless credential-based auth
+- `getCredentials()` - Extracts Bearer token from Authorization header on each request
+- `authenticate()` - Validates extracted token using `checkToken()` on each request
+
 ## Server-Level Authentication
 
 Apply authentication to all endpoints by default:
@@ -145,6 +171,143 @@ class AdminEndpoint extends BaseApiEndpoint {
 }
 ```
 
+## Inline Authentication Schemes
+
+`InlineAuthenticationScheme` runs authentication inline **on every request**. Credentials are extracted from the request and validated immediately, without requiring a separate session object.
+
+**How it works:**
+1. Middleware runs for each incoming request
+2. `getCredentials(request)` extracts credentials from the request
+3. `authenticate({ credentials, request })` validates the credentials
+4. If validation succeeds, request continues; otherwise an error is thrown
+5. No session is created or stored
+
+**Key Methods:**
+- `getCredentials(request)` - Extract credentials from the request
+- `authenticate({ credentials, request })` - Validate the extracted credentials
+
+**Use cases:**
+- API key validation (fixed key in header)
+- JWT token validation (stateless bearer tokens)
+- Basic authentication (username/password in header)
+- Any credential that can be validated synchronously on each request
+
+```typescript
+import { InlineAuthenticationScheme } from 'api-machine';
+import { ApiRequest } from 'api-machine';
+
+class ApiKeyScheme extends InlineAuthenticationScheme {
+  constructor(private apiKey: string) {
+    super();
+  }
+  
+  getSecurityScheme() {
+    return {
+      type: 'apiKey' as const,
+      in: 'header' as const,
+      name: 'X-API-Key',
+    };
+  }
+  
+  getCredentials(request: ApiRequest): unknown {
+    const key = request.headers['x-api-key'];
+    if (!key) {
+      throw new UnauthorizedError('API key is required');
+    }
+    return key;
+  }
+  
+  async authenticate(options: {
+    credentials: string;
+    request: ApiRequest;
+  }): Promise<void> {
+    if (options.credentials !== this.apiKey) {
+      throw new UnauthorizedError('Invalid API key');
+    }
+  }
+}
+```
+
+## Session Authentication Schemes
+
+`SessionAuthenticationScheme` manages stateful authentication. It provides an `AuthFlow` to **obtain a session**, and then verifies that session **on each request**.
+
+**How it works:**
+1. `getAuthFlow()` defines the multi-step authentication process (e.g., challenge → authorization → token exchange)
+2. User goes through the auth flow to obtain a session
+3. Session ID is stored (typically in cookies or request state)
+4. On each subsequent request, middleware calls `checkSession()` to verify the session exists and is valid
+5. Only after session is verified, the request continues
+
+**Key Methods:**
+- `getAuthFlow()` - Define the authentication flow steps used to obtain a session
+- `getMiddleware()` - Middleware that checks the session on each request (inherited)
+
+**Use cases:**
+- OAuth2 with authorization code flow
+- SAML-based authentication
+- Multi-step authentication requiring user interaction
+- Session-based systems where session state must be maintained
+
+```typescript
+import { SessionAuthenticationScheme, AuthFlow, AuthStep } from 'api-machine';
+import { ApiRequest, ApiResponse } from 'api-machine';
+
+class OAuth2Scheme extends SessionAuthenticationScheme {
+  getSecurityScheme() {
+    return {
+      type: 'oauth2' as const,
+      flows: {
+        authorizationCode: {
+          authorizationUrl: 'https://provider.com/oauth/authorize',
+          tokenUrl: 'https://provider.com/oauth/token',
+          scopes: { 'read:data': 'Read data' },
+        },
+      },
+    };
+  }
+  
+  getAuthFlow(): AuthFlow {
+    return {
+      challenge: {
+        description: 'Generate authorization challenge (PKCE)',
+        async handle(request: ApiRequest, response: ApiResponse) {
+          const challenge = generateChallenge();
+          return { challenge };
+        },
+      },
+      authorization: {
+        description: 'User authorizes application at OAuth2 provider',
+        async handle(request: ApiRequest, response: ApiResponse) {
+          // User is redirected to provider, returns with authorization code
+          const code = request.query.code as string;
+          return { code };
+        },
+      },
+      tokenExchange: {
+        description: 'Exchange authorization code for access token and session',
+        async handle(request: ApiRequest, response: ApiResponse) {
+          const accessToken = await exchangeCodeForToken(request.body.code);
+          const session = await createSession(accessToken);
+          return { session };
+        },
+      },
+    };
+  }
+}
+```
+
+**Session Validation Flow:**
+After a session is obtained through the auth flow, each request:
+1. Extracts the session ID (from cookies, headers, etc.)
+2. Calls `checkSession()` to verify the session still exists
+3. Validates the session is not expired
+4. Sets `request.authenticated = true` and allows request to continue
+
+## AuthFlow & AuthStep
+
+An `AuthFlow` is a named collection of `AuthStep` objects representing the complete multi-step authentication process used to obtain a session. See [src/authentication/auth-flow.ts](../src/authentication/auth-flow.ts) and [src/authentication/auth-step.ts](../src/authentication/auth-step.ts) for type definitions.
+
 ## Public Routes
 
 Make routes explicitly public by setting `authentication = null`:
@@ -164,63 +327,104 @@ This bypasses any parent router or server authentication.
 
 ## Custom Authentication Schemes
 
-Create custom authentication by extending `AuthenticationScheme`:
+Create custom authentication by extending `InlineAuthenticationScheme` or `SessionAuthenticationScheme` depending on your needs.
+
+**For credential-based auth** (API keys, tokens):
 
 ```typescript
-import { AuthenticationScheme } from 'api-machine';
-import { RequestHandler } from 'express';
+import { InlineAuthenticationScheme } from 'api-machine';
+import { ApiRequest } from 'api-machine';
 
-class ApiKeyAuthenticationScheme extends AuthenticationScheme {
-  constructor(private apiKey: string) {
-    super();
-  }
-  
+class CustomKeyScheme extends InlineAuthenticationScheme {
   getSecurityScheme() {
     return {
       type: 'apiKey' as const,
       in: 'header' as const,
-      name: 'X-API-Key',
+      name: 'X-Custom-Key',
     };
   }
 
-  getMiddleware(): RequestHandler {
-    return async (req, res, next) => {
-      const apiKey = req.headers['x-api-key'];
-      
-      if (apiKey !== this.apiKey) {
-        throw new UnauthorizedError('Invalid API key');
-      }
-      
-      next();
-    };
+  getCredentials(request: ApiRequest): unknown {
+    return request.headers['x-custom-key'];
+  }
+  
+  async authenticate(options: {
+    credentials: string;
+    request: ApiRequest;
+  }): Promise<void> {
+    if (!await this.validateKey(options.credentials)) {
+      throw new UnauthorizedError('Invalid key');
+    }
+  }
+  
+  private async validateKey(key: string): Promise<boolean> {
+    // Your validation logic
+    return key === 'valid-key';
   }
 }
 ```
 
 **Required Methods:**
 - `getSecurityScheme()`: Returns OpenAPI SecuritySchemeObject
-- `getMiddleware()`: Returns Express middleware function
+- `getMiddleware()`: Returns Express middleware function (inherited)
 - `getSecurityRequirement()`: Optional, returns OpenAPI SecurityRequirementObject
 
+## Available Exports
+
+The authentication module exports the following. See [src/authentication/index.ts](../src/authentication/index.ts) for the complete list:
+
+- `AuthenticationScheme` - Base class for all schemes
+- `InlineAuthenticationScheme` - For credential-based auth
+- `SessionAuthenticationScheme` - For stateful multi-step auth
+- `AuthStep` - Interface for auth flow steps
+- `AuthFlow` - Type for collections of steps
+- `BearerAuthenticationScheme` - Built-in Bearer token scheme
+- `AuthenticatedRequest` - Request type with auth flag
+
 ## OpenAPI Integration
 
 Authentication schemes automatically generate OpenAPI security definitions:
 
 ```typescript
-const auth = new BearerAuthenticationScheme({
+const bearerAuth = new BearerAuthenticationScheme({
   checkToken: async (token) => await validate(token),
   schemeName: 'BearerAuth',
   description: 'JWT Bearer Authentication',
 });
+
+const oauth2Auth = new OAuth2Scheme();
+// Automatically generates OAuth2 security scheme in OpenAPI spec
 ```
 
 ## Best Practices
 
-1. **Use server-level auth as default** - Apply authentication at the server level and override only where needed
-2. **Make public routes explicit** - Use `authentication = null` to clearly mark public endpoints
-3. **Validate tokens properly** - Always validate tokens against a secure source (database, JWT verification, etc.)
-4. **Use descriptive scheme names** - Help API consumers understand authentication requirements
-5. **Leverage cascading** - Set auth at the appropriate level (server/router/endpoint) based on your needs
+1. **Choose the right scheme type:**
+   - Use `InlineAuthenticationScheme` for **stateless** auth that happens on every request (API keys, JWT tokens, bearer tokens)
+   - Use `SessionAuthenticationScheme` for **stateful** auth with multi-step flows that obtain a session once, then check it on each request (OAuth2, SAML, login forms)
+
+2. **Inline scheme design:**
+   - Keep `getCredentials()` focused on extraction only
+   - Keep `authenticate()` focused on validation only
+   - Runs on every request, so keep it fast
+
+3. **Session scheme design:**
+   - Define clear, distinct steps in `AuthFlow` (challenge → authorization → tokenExchange)
+   - Session is obtained once, then validated on subsequent requests
+   - Use efficient session lookup/validation to minimize request overhead
+
+4. **Use server-level auth as default** - Apply authentication at the server level and override only where needed
+
+5. **Make public routes explicit** - Use `authentication = null` to clearly mark public endpoints
+
+6. **Validate thoroughly:**
+   - For inline: validate credentials against secure sources (database, JWT verification)
+   - For session: verify session exists and hasn't expired
+
+7. **Use descriptive names** - Help API consumers understand your authentication approach
+   - Inline: use scheme names like "BearerAuth", "ApiKeyAuth"
+   - Session: use clear auth flow step names (e.g., 'challenge', 'authorization', 'tokenExchange')
+
+8. **Leverage cascading** - Set auth at the appropriate level (server/router/endpoint) based on your needs
 
 ## Examples
 

src/authentication/auth-flow.ts

@@ -0,0 +1,11 @@
+import { AuthStep } from './auth-step';
+
+/**
+ * A named collection of authentication steps
+ * Each step is identified by a key
+ *  (e.g., 'challenge', 'authorization', 'tokenExchange')
+ *
+ * The flow represents the entire authentication process
+ * Steps are executed in the order they're defined
+ */
+export type AuthFlow = Record<string, AuthStep>;

src/authentication/auth-step.ts

@@ -0,0 +1,26 @@
+import { ApiRequest, ApiResponse } from '../router';
+
+/**
+ * Represents a single step in an authentication flow
+ * Can be used for inline schemes (as middleware)
+ *  or session schemes (as endpoint)
+ */
+export interface AuthStep {
+	/**
+	 * Human-readable description
+	 */
+	description?: string;
+
+	/**
+	 * Execute this authentication step
+	 * Called when processing requests for this step
+	 *
+	 * @param request - The incoming request
+	 * @returns Result indicating success/failure
+	 * @throws HTTPError for authentication failures
+	 */
+	handle(
+		request: ApiRequest,
+		response: ApiResponse
+	): Promise<Record<string, unknown>>;
+}