feat: remove AuthStep so that flow steps can be endpoint derivatives

Author: DrewImm

docs/authentication.md

@@ -268,7 +268,7 @@ class MainRouter extends BaseApiRouter {
 - Session-based systems where session state must be maintained
 
 ```typescript
-import { SessionAuthenticationScheme, AuthFlow, AuthStep } from 'api-machine';
+import { SessionAuthenticationScheme, AuthFlow, BaseApiEndpoint } from 'api-machine';
 
 class OAuth2Scheme extends SessionAuthenticationScheme {
   getSecurityScheme() {
@@ -287,7 +287,7 @@ class OAuth2Scheme extends SessionAuthenticationScheme {
   getAuthFlow(): AuthFlow {
     return {
       // Challenge step
-      challenge: class extends AuthStep {
+      challenge: class extends BaseApiEndpoint {
         override path = '/challenge';
         override description = 'Generate authorization challenge (PKCE)';
 
@@ -297,7 +297,7 @@ class OAuth2Scheme extends SessionAuthenticationScheme {
         }
       },
       // Authorization step
-      authorization: class extends AuthStep {
+      authorization: class extends BaseApiEndpoint {
         override path = '/authorize';
         override description = 'User authorizes application at OAuth2 provider';
 
@@ -308,7 +308,7 @@ class OAuth2Scheme extends SessionAuthenticationScheme {
         }
       },
       // Token exchange step
-      tokenExchange: class extends AuthStep {
+      tokenExchange: class extends BaseApiEndpoint {
         override path = '/token';
         override description = 'Exchange authorization code for access token and session';
 
@@ -330,11 +330,11 @@ After a session is obtained through the auth flow, each request:
 3. Validates the session is not expired
 4. Sets `request.authenticated = true` and allows request to continue
 
-## AuthFlow & AuthStep
+## AuthFlow & BaseApiEndpoint
 
-An `AuthFlow` is a named collection of `AuthStep` classes representing the complete multi-step authentication process used to obtain a session.
+An `AuthFlow` is a named collection of `BaseApiEndpoint` classes representing the complete multi-step authentication process used to obtain a session.
 
-**AuthStep** is an abstract class that extends `BaseApiEndpoint`, allowing each step to leverage endpoint features:
+**BaseApiEndpoint** is the abstract class used for authentication flow steps, allowing each step to leverage endpoint features:
 - Request validation (body, query, params, headers via valsan)
 - Middleware support
 - Standardized error handling
@@ -349,7 +349,7 @@ See [src/authentication/auth-step.ts](../src/authentication/auth-step.ts) and [s
 
 **Step example with validation:**
 ```typescript
-class TokenExchangeStep extends AuthStep {
+class TokenExchangeStep extends BaseApiEndpoint {
   override path = '/token';
   override description = 'Exchange code for tokens';
 
@@ -436,7 +436,7 @@ The authentication module exports the following. See [src/authentication/index.t
 - `AuthenticationScheme` - Base class for all schemes
 - `InlineAuthenticationScheme` - For credential-based auth
 - `SessionAuthenticationScheme` - For stateful multi-step auth
-- `AuthStep` - Interface for auth flow steps
+- `BaseApiEndpoint` - Base class for auth flow steps
 - `AuthFlow` - Type for collections of steps
 - `BearerAuthenticationScheme` - Built-in Bearer token scheme
 - `AuthenticatedRequest` - Request type with auth flag

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

@@ -10,7 +10,6 @@ import {
 	BaseApiEndpoint,
 	SessionAuthenticationScheme,
 	AuthFlow,
-	AuthStep,
 	InMemorySessionDriver,
 	ApiRequest,
 	ApiResponse,
@@ -56,7 +55,7 @@ class OAuth2Scheme extends SessionAuthenticationScheme {
 		/**
 		 * Challenge step - generates a random challenge for CSRF prevention
 		 */
-		class ChallengeStep extends AuthStep {
+		class ChallengeStep extends BaseApiEndpoint {
 			override path = '/challenge';
 			override method = EndpointMethod.POST;
 			override description = 'Generate authentication challenge';
@@ -73,7 +72,7 @@ class OAuth2Scheme extends SessionAuthenticationScheme {
 		/**
 		 * Authorization step - validates credentials
 		 */
-		class AuthorizationStep extends AuthStep {
+		class AuthorizationStep extends BaseApiEndpoint {
 			override path = '/authorize';
 			override method = EndpointMethod.POST;
 			override description = 'Authorize with username and password';
@@ -128,7 +127,7 @@ class OAuth2Scheme extends SessionAuthenticationScheme {
 		/**
 		 * Token exchange step - exchanges code for session
 		 */
-		class TokenStep extends AuthStep {
+		class TokenStep extends BaseApiEndpoint {
 			override path = '/token';
 			override method = EndpointMethod.POST;
 			override description = 'Exchange authorization code for session';

src/authentication/auth-flow.ts

@@ -1,14 +1,14 @@
-import { AuthStepConstructor } from './auth-step';
+import { ApiEndpoint } from '../router';
 
 /**
  * A named collection of authentication steps
  * Each step is identified by a key
  * (e.g., 'challenge', 'authorization', 'tokenExchange')
  *
- * Steps are classes extending AuthStep (which extends BaseApiEndpoint)
+ * Steps are classes extending BaseApiEndpoint
  * This allows each step to use endpoint features like validation and middleware
  *
  * The flow represents the entire authentication process
  * Steps are executed in the order they're defined
  */
-export type AuthFlow = Record<string, AuthStepConstructor>;
+export type AuthFlow = Record<string, ApiEndpoint>;

src/authentication/auth-step.ts

@@ -1,10 +0,0 @@
-import { BaseApiEndpoint } from '../router';
-
-/**
- * Abstract base class for authentication flow steps
- */
-export abstract class AuthStep extends BaseApiEndpoint {}
-
-export type AuthStepConstructor = new (
-	...params: ConstructorParameters<typeof AuthStep>
-) => AuthStep;

src/authentication/authentication-scheme.ts

@@ -60,7 +60,7 @@ export abstract class AuthenticationScheme {
 
 	/**
 	 * Get the Express middleware for this authentication scheme
-	 * For InlineAuthenticationScheme: runs AuthStep
+	 * For InlineAuthenticationScheme: runs endpoint
 	 * For SessionAuthenticationScheme: verifies session
 	 *
 	 * @returns Express RequestHandler middleware

src/authentication/index.ts

@@ -4,6 +4,5 @@ export {
 	InlineAuthenticationScheme,
 	SessionAuthenticationScheme,
 } from './authentication-scheme';
-export { AuthStep } from './auth-step';
 export { AuthFlow } from './auth-flow';
 export * from './schemes';

src/router/endpoint.ts

@@ -124,4 +124,6 @@ export abstract class BaseApiEndpoint extends BaseApiRoute {
 	}
 }
 
-export type ApiEndpoint = { new (): BaseApiEndpoint };
+export type ApiEndpoint = new (
+	...params: ConstructorParameters<typeof BaseApiEndpoint>
+) => BaseApiEndpoint;

test/spec/authentication/session-scheme.spec.ts

@@ -2,9 +2,8 @@ import 'jasmine';
 import {
 	SessionAuthenticationScheme,
 	AuthFlow,
-	AuthStep,
 } from '../../../src/authentication';
-import { BaseApiRouter } from '../../../src/router';
+import { BaseApiRouter, BaseApiEndpoint } from '../../../src/router';
 import { InMemorySessionDriver } from '../../../src/session';
 import { SessionDriver } from '../../../src/session';
 import { Session } from '../../../src/session/session';
@@ -20,7 +19,7 @@ type AnyResponse = any;
 abstract class TestSessionDriverImport extends SessionDriver {}
 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
-abstract class TestAuthFlowImport extends AuthStep {}
+abstract class TestAuthFlowImport extends BaseApiEndpoint {}
 
 /**
  * Test implementation of SessionAuthenticationScheme
@@ -46,7 +45,7 @@ class TestSessionScheme extends SessionAuthenticationScheme {
 
 	public getAuthFlow(): AuthFlow {
 		return {
-			testStep: class extends AuthStep {
+			testStep: class extends BaseApiEndpoint {
 				override description = 'Test step';
 				async handle() {
 					return {};
@@ -273,7 +272,7 @@ describe('SessionAuthenticationScheme', () => {
 
 				public getAuthFlow(): AuthFlow {
 					return {
-						customStep: class extends AuthStep {
+						customStep: class extends BaseApiEndpoint {
 							override description = 'Custom step';
 							async handle() {
 								return {};
@@ -506,21 +505,21 @@ describe('SessionAuthenticationScheme', () => {
 		});
 
 		it('should expose all auth steps as routes', () => {
-			class ChallengeStep extends AuthStep {
+			class ChallengeStep extends BaseApiEndpoint {
 				override path = '/challenge';
 				async handle() {
 					return { challenge: 'test' };
 				}
 			}
 
-			class AuthStep2 extends AuthStep {
+			class AuthStep2 extends BaseApiEndpoint {
 				override path = '/authorize';
 				async handle() {
 					return { code: 'abc123' };
 				}
 			}
 
-			class TokenStep extends AuthStep {
+			class TokenStep extends BaseApiEndpoint {
 				override path = '/token';
 				async handle() {
 					return { token: 'xyz789' };
@@ -588,14 +587,14 @@ describe('SessionAuthenticationScheme', () => {
 		});
 
 		it('should return auth steps from routes() method', async () => {
-			class ChallengeStep extends AuthStep {
+			class ChallengeStep extends BaseApiEndpoint {
 				override path = '/challenge';
 				async handle() {
 					return { challenge: 'test' };
 				}
 			}
 
-			class TokenStep extends AuthStep {
+			class TokenStep extends BaseApiEndpoint {
 				override path = '/token';
 				async handle() {
 					return { token: 'xyz789' };
@@ -676,14 +675,14 @@ describe('SessionAuthenticationScheme', () => {
 
 				public getAuthFlow(): AuthFlow {
 					return {
-						login: class extends AuthStep {
+						login: class extends BaseApiEndpoint {
 							override path = '/login';
 							override description = 'Login step';
 							async handle() {
 								return { token: 'abc123' };
 							}
 						},
-						logout: class extends AuthStep {
+						logout: class extends BaseApiEndpoint {
 							override path = '/logout';
 							override description = 'Logout step';
 							async handle() {
@@ -731,21 +730,21 @@ describe('SessionAuthenticationScheme', () => {
 				}
 
 				public getAuthFlow(): AuthFlow {
-					class Step1 extends AuthStep {
+					class Step1 extends BaseApiEndpoint {
 						override path = '/step1';
 						async handle() {
 							return { step: 1 };
 						}
 					}
 
-					class Step2 extends AuthStep {
+					class Step2 extends BaseApiEndpoint {
 						override path = '/step2';
 						async handle() {
 							return { step: 2 };
 						}
 					}
 
-					class Step3 extends AuthStep {
+					class Step3 extends BaseApiEndpoint {
 						override path = '/step3';
 						async handle() {
 							return { step: 3 };
@@ -764,7 +763,7 @@ describe('SessionAuthenticationScheme', () => {
 			const endpoints = scheme.getEndpoints();
 
 			expect(endpoints.length).toBe(3);
-			// All should be AuthStep classes
+			// All should be endpoint classes
 			endpoints.forEach((endpoint) => {
 				// eslint-disable-next-line @typescript-eslint/no-explicit-any
 				expect(typeof endpoint).toBe('function');
@@ -831,13 +830,13 @@ describe('SessionAuthenticationScheme', () => {
 
 				public getAuthFlow(): AuthFlow {
 					return {
-						auth: class extends AuthStep {
+						auth: class extends BaseApiEndpoint {
 							override path = '/auth';
 							async handle() {
 								return { authenticated: true };
 							}
 						},
-						verify: class extends AuthStep {
+						verify: class extends BaseApiEndpoint {
 							override path = '/verify';
 							async handle() {
 								return { verified: true };