feat: auth flow router

Author: DrewImm

docs/authentication.md

@@ -241,8 +241,26 @@ class ApiKeyScheme extends InlineAuthenticationScheme {
 
 **Key Methods:**
 - `getAuthFlow()` - Define the authentication flow steps used to obtain a session
+- `getAuthRouter(basePath?)` - Generate a router that automatically exposes all auth steps as API endpoints
 - `getMiddleware()` - Middleware that checks the session on each request (inherited)
 
+**Usage:**
+```typescript
+// Create your session authentication scheme
+const oauth2 = new OAuth2Scheme();
+
+// Include in your main router
+class MainRouter extends BaseApiRouter {
+  async routes() {
+    return [
+      oauth2.getAuthRouter('/auth'), // Auth endpoints
+      SecureApiRouter,         // Protected API (uses oauth2 as authentication)
+      PublicRouter,            // Public endpoints
+    ];
+  }
+}
+```
+
 **Use cases:**
 - OAuth2 with authorization code flow
 - SAML-based authentication

src/authentication/auth-flow.ts

@@ -1,4 +1,4 @@
-import { AuthStep } from './auth-step';
+import { AuthStepConstructor } from './auth-step';
 
 /**
  * A named collection of authentication steps
@@ -11,4 +11,4 @@ import { AuthStep } from './auth-step';
  * The flow represents the entire authentication process
  * Steps are executed in the order they're defined
  */
-export type AuthFlow = Record<string, typeof AuthStep>;
+export type AuthFlow = Record<string, AuthStepConstructor>;

src/authentication/auth-step.ts

@@ -4,3 +4,7 @@ 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

@@ -3,7 +3,12 @@ import {
 	SecuritySchemeObject,
 	SecurityRequirementObject,
 } from 'auto-oas/oas/v3.1';
-import { ApiNextFunction, ApiRequest, ApiResponse } from '../router';
+import {
+	ApiNextFunction,
+	ApiRequest,
+	ApiResponse,
+	BaseApiRouter,
+} from '../router';
 import { SessionDriver } from '../session/session-driver';
 import { AuthenticatedRequest } from './authenticated-request';
 import { AuthFlow } from './auth-flow';
@@ -103,6 +108,26 @@ export abstract class SessionAuthenticationScheme extends AuthenticationScheme {
 	 */
 	public abstract getAuthFlow(): AuthFlow;
 
+	/**
+	 * Generate a router that exposes all auth steps as API endpoints
+	 * Each step in the AuthFlow becomes a route in the router
+	 *
+	 * @param basePath - Optional base path for the router (default: empty)
+	 * @returns Router with all auth steps as endpoints
+	 */
+	public getAuthRouter(basePath = ''): BaseApiRouter {
+		const flow = this.getAuthFlow();
+		const steps = Object.values(flow);
+
+		return new (class extends BaseApiRouter {
+			override path = basePath;
+
+			async routes() {
+				return steps;
+			}
+		})();
+	}
+
 	public getMiddleware(): RequestHandler {
 		return async (
 			request: AuthenticatedRequest,

src/router/base.ts

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

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

@@ -4,6 +4,7 @@ import {
 	AuthFlow,
 	AuthStep,
 } from '../../../src/authentication';
+import { BaseApiRouter } from '../../../src/router';
 import { InMemorySessionDriver } from '../../../src/session';
 import { SessionDriver } from '../../../src/session';
 import { Session } from '../../../src/session/session';
@@ -471,4 +472,145 @@ describe('SessionAuthenticationScheme', () => {
 			});
 		});
 	});
+
+	describe('getAuthRouter()', () => {
+		it('should return a router instance', () => {
+			const scheme = new TestSessionScheme();
+			const router = scheme.getAuthRouter();
+
+			expect(router).toBeDefined();
+			expect(router.path).toBe('');
+		});
+
+		it('should set router path from basePath parameter', () => {
+			const scheme = new TestSessionScheme();
+			const router = scheme.getAuthRouter('/auth');
+
+			expect(router.path).toBe('/auth');
+		});
+
+		it('should expose all auth steps as routes', () => {
+			class ChallengeStep extends AuthStep {
+				override path = '/challenge';
+				async handle() {
+					return { challenge: 'test' };
+				}
+			}
+
+			class AuthStep2 extends AuthStep {
+				override path = '/authorize';
+				async handle() {
+					return { code: 'abc123' };
+				}
+			}
+
+			class TokenStep extends AuthStep {
+				override path = '/token';
+				async handle() {
+					return { token: 'xyz789' };
+				}
+			}
+
+			class TestSchemeWithSteps extends SessionAuthenticationScheme {
+				public readonly schemeName = 'TestScheme';
+				public readonly type = 'oauth2' as const;
+
+				public getSecurityScheme(): SecuritySchemeObject {
+					return {
+						type: 'oauth2' as const,
+						flows: {
+							authorizationCode: {
+								authorizationUrl: 'http://example.com/auth',
+								tokenUrl: 'http://example.com/token',
+								scopes: {},
+							},
+						},
+					};
+				}
+
+				public getAuthFlow(): AuthFlow {
+					return {
+						challenge: ChallengeStep,
+						authorize: AuthStep2,
+						token: TokenStep,
+					};
+				}
+			}
+
+			const scheme = new TestSchemeWithSteps();
+			const router = scheme.getAuthRouter('/oauth');
+
+			// Verify router has correct path and is a BaseApiRouter
+			expect(router).toBeDefined();
+			expect(router.path).toBe('/oauth');
+			expect(router).toBeInstanceOf(BaseApiRouter);
+		});
+
+		it('should work with empty basePath', () => {
+			const scheme = new TestSessionScheme();
+			const router = scheme.getAuthRouter();
+
+			expect(router.path).toBe('');
+		});
+
+		it('should return different router instances on each call', () => {
+			const scheme = new TestSessionScheme();
+			const router1 = scheme.getAuthRouter('/auth');
+			const router2 = scheme.getAuthRouter('/auth');
+
+			expect(router1).not.toBe(router2);
+		});
+
+		it('should return auth steps from routes() method', async () => {
+			class ChallengeStep extends AuthStep {
+				override path = '/challenge';
+				async handle() {
+					return { challenge: 'test' };
+				}
+			}
+
+			class TokenStep extends AuthStep {
+				override path = '/token';
+				async handle() {
+					return { token: 'xyz789' };
+				}
+			}
+
+			class TestSchemeWithRoutes extends SessionAuthenticationScheme {
+				public readonly schemeName = 'TestScheme';
+				public readonly type = 'oauth2' as const;
+
+				public getSecurityScheme(): SecuritySchemeObject {
+					return {
+						type: 'oauth2' as const,
+						flows: {
+							authorizationCode: {
+								authorizationUrl: 'http://example.com/auth',
+								tokenUrl: 'http://example.com/token',
+								scopes: {},
+							},
+						},
+					};
+				}
+
+				public getAuthFlow(): AuthFlow {
+					return {
+						challenge: ChallengeStep,
+						token: TokenStep,
+					};
+				}
+			}
+
+			const scheme = new TestSchemeWithRoutes();
+			const router = scheme.getAuthRouter('/auth');
+
+			// eslint-disable-next-line @typescript-eslint/no-explicit-any
+			const routes = await (router as any).routes();
+
+			expect(routes).toBeDefined();
+			expect(routes.length).toBe(2);
+			expect(routes[0]).toBe(ChallengeStep);
+			expect(routes[1]).toBe(TokenStep);
+		});
+	});
 });