create-phoenixjs 0.1.0

package/template/framework/routing/Router.ts

@@ -0,0 +1,280 @@
+/**
+ * PhoenixJS - Router
+ * 
+ * Laravel-style router with fluent API, route groups, and middleware support.
+ */
+
+import { RouteRegistry, type HttpMethod, type RouteHandler, type Route, type RouteMatch } from '@framework/routing/RouteRegistry';
+import type { MiddlewareResolvable } from '@framework/middleware/Middleware';
+
+/**
+ * Route group options
+ */
+export interface RouteGroupOptions {
+	/** Prefix to add to all routes in the group */
+	prefix?: string;
+	/** Middleware to apply to all routes in the group */
+	middleware?: MiddlewareResolvable[];
+	/** Name prefix for named routes */
+	as?: string;
+}
+
+/**
+ * Context for the current route group
+ */
+interface GroupContext {
+	prefix: string;
+	middleware: MiddlewareResolvable[];
+	namePrefix: string;
+}
+
+/**
+ * Router class
+ * 
+ * Provides a fluent API for defining routes with Laravel-like syntax.
+ * 
+ * @example
+ * ```typescript
+ * Router.get('/users', 'UserController@index');
+ * Router.post('/users', 'UserController@store').middleware('auth');
+ * 
+ * Router.group({ prefix: '/api', middleware: ['auth'] }, () => {
+ *   Router.get('/users/:id', 'UserController@show');
+ * });
+ * ```
+ */
+export class Router {
+	private static instance: Router | null = null;
+	private registry: RouteRegistry;
+	private groupStack: GroupContext[] = [];
+	private lastRoute: Route | null = null;
+	private middlewareMap: Map<string, MiddlewareResolvable> = new Map();
+
+	private constructor() {
+		this.registry = new RouteRegistry();
+	}
+
+	/**
+	 * Get the singleton router instance
+	 */
+	static getInstance(): Router {
+		if (!Router.instance) {
+			Router.instance = new Router();
+		}
+		return Router.instance;
+	}
+
+	/**
+	 * Reset the router (for testing)
+	 */
+	static reset(): void {
+		if (Router.instance) {
+			Router.instance.registry.clear();
+			Router.instance.groupStack = [];
+			Router.instance.lastRoute = null;
+			Router.instance.middlewareMap.clear();
+		}
+	}
+
+	/**
+	 * Register a route alias for middleware
+	 */
+	static aliasMiddleware(name: string, middleware: MiddlewareResolvable): void {
+		Router.getInstance().middlewareMap.set(name, middleware);
+	}
+
+	/**
+	 * GET route
+	 */
+	static get(path: string, handler: RouteHandler): typeof Router {
+		return Router.addRoute('GET', path, handler);
+	}
+
+	/**
+	 * POST route
+	 */
+	static post(path: string, handler: RouteHandler): typeof Router {
+		return Router.addRoute('POST', path, handler);
+	}
+
+	/**
+	 * PUT route
+	 */
+	static put(path: string, handler: RouteHandler): typeof Router {
+		return Router.addRoute('PUT', path, handler);
+	}
+
+	/**
+	 * PATCH route
+	 */
+	static patch(path: string, handler: RouteHandler): typeof Router {
+		return Router.addRoute('PATCH', path, handler);
+	}
+
+	/**
+	 * DELETE route
+	 */
+	static delete(path: string, handler: RouteHandler): typeof Router {
+		return Router.addRoute('DELETE', path, handler);
+	}
+
+	/**
+	 * OPTIONS route
+	 */
+	static options(path: string, handler: RouteHandler): typeof Router {
+		return Router.addRoute('OPTIONS', path, handler);
+	}
+
+	/**
+	 * Match multiple HTTP methods
+	 */
+	static match(methods: HttpMethod[], path: string, handler: RouteHandler): typeof Router {
+		const router = Router.getInstance();
+		for (const method of methods) {
+			Router.addRoute(method, path, handler);
+		}
+		return Router;
+	}
+
+	/**
+	 * Match any HTTP method
+	 */
+	static any(path: string, handler: RouteHandler): typeof Router {
+		return Router.match(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'], path, handler);
+	}
+
+	/**
+	 * Create a route group
+	 */
+	static group(options: RouteGroupOptions, callback: () => void): void {
+		const router = Router.getInstance();
+
+		// Get current context
+		const currentPrefix = router.getCurrentPrefix();
+		const currentMiddleware = router.getCurrentMiddleware();
+		const currentNamePrefix = router.getCurrentNamePrefix();
+
+		// Push new context
+		router.groupStack.push({
+			prefix: currentPrefix + (options.prefix || ''),
+			middleware: [...currentMiddleware, ...(options.middleware || [])],
+			namePrefix: currentNamePrefix + (options.as || ''),
+		});
+
+		// Execute callback
+		callback();
+
+		// Pop context
+		router.groupStack.pop();
+	}
+
+	/**
+	 * Add middleware to the last registered route
+	 * For fluent API: Router.get('/').middleware('auth')
+	 */
+	static middleware(...middleware: MiddlewareResolvable[]): typeof Router {
+		const router = Router.getInstance();
+		if (router.lastRoute) {
+			router.lastRoute.middleware.push(...middleware);
+		}
+		return Router;
+	}
+
+	/**
+	 * Name the last registered route
+	 * For fluent API: Router.get('/').name('home')
+	 */
+	static name(name: string): typeof Router {
+		const router = Router.getInstance();
+		if (router.lastRoute) {
+			const prefix = router.getCurrentNamePrefix();
+			router.lastRoute.name = prefix + name;
+		}
+		return Router;
+	}
+
+	/**
+	 * Resolve a route from method and path
+	 */
+	static resolve(method: string, path: string): RouteMatch | null {
+		return Router.getInstance().registry.match(method, path);
+	}
+
+	/**
+	 * Get all registered routes
+	 */
+	static routes(): Route[] {
+		return Router.getInstance().registry.all();
+	}
+
+	/**
+	 * Find a route by name
+	 */
+	static route(name: string): Route | undefined {
+		return Router.getInstance().registry.findByName(name);
+	}
+
+	/**
+	 * Get route count
+	 */
+	static count(): number {
+		return Router.getInstance().registry.count();
+	}
+
+	/**
+	 * Resolve middleware alias to actual middleware
+	 */
+	static resolveMiddleware(name: string): MiddlewareResolvable | undefined {
+		return Router.getInstance().middlewareMap.get(name);
+	}
+
+	/**
+	 * Get registered middleware map
+	 */
+	static getMiddlewareMap(): Map<string, MiddlewareResolvable> {
+		return Router.getInstance().middlewareMap;
+	}
+
+	/**
+	 * Add a route to the registry
+	 */
+	private static addRoute(method: HttpMethod, path: string, handler: RouteHandler): typeof Router {
+		const router = Router.getInstance();
+
+		// Apply group prefix
+		const fullPath = router.getCurrentPrefix() + path;
+
+		// Apply group middleware
+		const middleware = [...router.getCurrentMiddleware()];
+
+		// Register the route
+		router.lastRoute = router.registry.add(method, fullPath, handler, middleware);
+
+
+		return Router;
+	}
+
+	/**
+	 * Get current prefix from group stack
+	 */
+	private getCurrentPrefix(): string {
+		if (this.groupStack.length === 0) return '';
+		return this.groupStack[this.groupStack.length - 1].prefix;
+	}
+
+	/**
+	 * Get current middleware from group stack
+	 */
+	private getCurrentMiddleware(): MiddlewareResolvable[] {
+		if (this.groupStack.length === 0) return [];
+		return [...this.groupStack[this.groupStack.length - 1].middleware];
+	}
+
+	/**
+	 * Get current name prefix from group stack
+	 */
+	private getCurrentNamePrefix(): string {
+		if (this.groupStack.length === 0) return '';
+		return this.groupStack[this.groupStack.length - 1].namePrefix;
+	}
+}

package/template/framework/security/CorsMiddleware.ts

@@ -0,0 +1,151 @@
+/**
+ * PhoenixJS - CORS Middleware
+ * 
+ * Handles Cross-Origin Resource Sharing (CORS) headers and preflight requests.
+ */
+
+import type { Middleware, NextFunction } from '@framework/middleware/Middleware';
+import type { FrameworkRequest } from '@framework/http/Request';
+import type { CorsConfig } from '@/config/security';
+
+export class CorsMiddleware implements Middleware {
+	constructor(private config: CorsConfig) { }
+
+	async handle(request: FrameworkRequest, next: NextFunction): Promise<Response> {
+		const origin = request.header('Origin') || '';
+
+		// Handle preflight requests
+		if (request.method() === 'OPTIONS') {
+			return this.handlePreflight(request, origin);
+		}
+
+		// Process the request through the pipeline
+		const response = await next(request);
+
+		// Add CORS headers to the response
+		return this.addCorsHeaders(response, origin);
+	}
+
+	/**
+	 * Handle preflight (OPTIONS) requests
+	 */
+	private handlePreflight(request: FrameworkRequest, origin: string): Response {
+		const headers: Record<string, string> = {};
+
+		// Check if origin is allowed
+		if (this.isOriginAllowed(origin)) {
+			headers['Access-Control-Allow-Origin'] = this.getAllowedOrigin(origin);
+
+			if (this.config.credentials) {
+				headers['Access-Control-Allow-Credentials'] = 'true';
+			}
+		}
+
+		// Set allowed methods
+		headers['Access-Control-Allow-Methods'] = this.config.methods.join(', ');
+
+		// Set allowed headers
+		const requestedHeaders = request.header('Access-Control-Request-Headers');
+		if (requestedHeaders) {
+			headers['Access-Control-Allow-Headers'] = this.config.allowedHeaders.join(', ');
+		}
+
+		// Set max age
+		headers['Access-Control-Max-Age'] = this.config.maxAge.toString();
+
+		return new Response(null, {
+			status: 204,
+			headers,
+		});
+	}
+
+	/**
+	 * Add CORS headers to a response
+	 */
+	private addCorsHeaders(response: Response, origin: string): Response {
+		const headers = new Headers(response.headers);
+
+		// Check if origin is allowed
+		if (this.isOriginAllowed(origin)) {
+			headers.set('Access-Control-Allow-Origin', this.getAllowedOrigin(origin));
+
+			if (this.config.credentials) {
+				headers.set('Access-Control-Allow-Credentials', 'true');
+			}
+		}
+
+		// Set exposed headers
+		if (this.config.exposedHeaders.length > 0) {
+			headers.set('Access-Control-Expose-Headers', this.config.exposedHeaders.join(', '));
+		}
+
+		return new Response(response.body, {
+			status: response.status,
+			statusText: response.statusText,
+			headers,
+		});
+	}
+
+	/**
+	 * Check if an origin is allowed
+	 */
+	private isOriginAllowed(origin: string): boolean {
+		const configOrigin = this.config.origin;
+
+		// Wildcard allows all
+		if (configOrigin === '*') {
+			return true;
+		}
+
+		// String match
+		if (typeof configOrigin === 'string') {
+			return origin === configOrigin;
+		}
+
+		// Array of origins
+		if (Array.isArray(configOrigin)) {
+			return configOrigin.includes(origin);
+		}
+
+		// Regex match
+		if (configOrigin instanceof RegExp) {
+			return configOrigin.test(origin);
+		}
+
+		// Function check
+		if (typeof configOrigin === 'function') {
+			return configOrigin(origin);
+		}
+
+		return false;
+	}
+
+	/**
+	 * Get the allowed origin value for the header
+	 */
+	private getAllowedOrigin(origin: string): string {
+		// If wildcard and no credentials, return *
+		if (this.config.origin === '*' && !this.config.credentials) {
+			return '*';
+		}
+
+		// Otherwise return the requesting origin (if allowed)
+		return origin;
+	}
+}
+
+/**
+ * Create a CORS middleware instance with the given config
+ */
+export function cors(config: Partial<CorsConfig> = {}): CorsMiddleware {
+	const defaultConfig: CorsConfig = {
+		origin: '*',
+		methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+		allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With'],
+		exposedHeaders: [],
+		credentials: false,
+		maxAge: 86400,
+	};
+
+	return new CorsMiddleware({ ...defaultConfig, ...config });
+}

package/template/framework/security/CsrfMiddleware.ts

@@ -0,0 +1,121 @@
+/**
+ * PhoenixJS - CSRF Middleware
+ * 
+ * Provides Cross-Site Request Forgery protection.
+ */
+
+import type { Middleware, NextFunction } from '@framework/middleware/Middleware';
+import type { FrameworkRequest } from '@framework/http/Request';
+import type { CsrfConfig } from '@/config/security';
+import { FrameworkResponse } from '@framework/http/Response';
+
+export class CsrfMiddleware implements Middleware {
+	private tokens: Map<string, { token: string; expires: number }> = new Map();
+
+	constructor(private config: CsrfConfig) { }
+
+	async handle(request: FrameworkRequest, next: NextFunction): Promise<Response> {
+		// Skip if CSRF is disabled
+		if (!this.config.enabled) {
+			return next(request);
+		}
+
+		// Skip safe methods (GET, HEAD, OPTIONS)
+		if (this.config.safeMethods.includes(request.method())) {
+			const response = await next(request);
+			return this.attachCsrfCookie(response, request);
+		}
+
+		// Validate CSRF token for non-safe methods
+		if (!this.validateToken(request)) {
+			return FrameworkResponse.json(
+				{
+					error: true,
+					message: 'CSRF token mismatch',
+				},
+				403
+			);
+		}
+
+		return next(request);
+	}
+
+	/**
+	 * Validate the CSRF token from the request
+	 */
+	private validateToken(request: FrameworkRequest): boolean {
+		// Get token from header
+		const headerToken = request.header(this.config.headerName);
+
+		// Get token from cookie
+		const cookieToken = request.cookie(this.config.cookieName);
+
+		// Both must exist and match
+		if (!headerToken || !cookieToken) {
+			return false;
+		}
+
+		// Tokens must match
+		return headerToken === cookieToken;
+	}
+
+	/**
+	 * Attach CSRF cookie to response
+	 */
+	private attachCsrfCookie(response: Response, request: FrameworkRequest): Response {
+		// Check if token already exists in cookie
+		const existingToken = request.cookie(this.config.cookieName);
+
+		// Generate or use existing token
+		const token = existingToken || this.generateToken();
+
+		// Clone response with CSRF cookie
+		const headers = new Headers(response.headers);
+		const cookieValue = `${this.config.cookieName}=${token}; Path=/; SameSite=Strict`;
+		headers.append('Set-Cookie', cookieValue);
+
+		return new Response(response.body, {
+			status: response.status,
+			statusText: response.statusText,
+			headers,
+		});
+	}
+
+	/**
+	 * Generate a cryptographically secure random token
+	 */
+	generateToken(): string {
+		const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+		const array = new Uint8Array(this.config.tokenLength);
+		crypto.getRandomValues(array);
+
+		let token = '';
+		for (let i = 0; i < this.config.tokenLength; i++) {
+			token += chars[array[i] % chars.length];
+		}
+
+		return token;
+	}
+
+	/**
+	 * Create a token for testing
+	 */
+	createTestToken(): string {
+		return this.generateToken();
+	}
+}
+
+/**
+ * Create a CSRF middleware instance with the given config
+ */
+export function csrf(config: Partial<CsrfConfig> = {}): CsrfMiddleware {
+	const defaultConfig: CsrfConfig = {
+		enabled: true,
+		cookieName: 'XSRF-TOKEN',
+		headerName: 'X-CSRF-Token',
+		tokenLength: 32,
+		safeMethods: ['GET', 'HEAD', 'OPTIONS'],
+	};
+
+	return new CsrfMiddleware({ ...defaultConfig, ...config });
+}

package/template/framework/security/HelmetMiddleware.ts

@@ -0,0 +1,138 @@
+/**
+ * PhoenixJS - Helmet Middleware
+ * 
+ * Sets security-related HTTP headers (inspired by Helmet.js).
+ */
+
+import type { Middleware, NextFunction } from '@framework/middleware/Middleware';
+import type { FrameworkRequest } from '@framework/http/Request';
+import type { HelmetConfig } from '@/config/security';
+
+export class HelmetMiddleware implements Middleware {
+	constructor(private config: HelmetConfig) { }
+
+	async handle(request: FrameworkRequest, next: NextFunction): Promise<Response> {
+		// Process the request through the pipeline
+		const response = await next(request);
+
+		// Add security headers to the response
+		return this.addSecurityHeaders(response);
+	}
+
+	/**
+	 * Add security headers to a response
+	 */
+	private addSecurityHeaders(response: Response): Response {
+		const headers = new Headers(response.headers);
+
+		// X-Frame-Options
+		if (this.config.frameOptions) {
+			headers.set('X-Frame-Options', this.config.frameOptions);
+		}
+
+		// X-Content-Type-Options
+		if (this.config.contentTypeOptions) {
+			headers.set('X-Content-Type-Options', 'nosniff');
+		}
+
+		// X-XSS-Protection
+		if (this.config.xssProtection) {
+			headers.set('X-XSS-Protection', '1; mode=block');
+		}
+
+		// Strict-Transport-Security (HSTS)
+		if (this.config.hsts.enabled) {
+			let hstsValue = `max-age=${this.config.hsts.maxAge}`;
+			if (this.config.hsts.includeSubDomains) {
+				hstsValue += '; includeSubDomains';
+			}
+			if (this.config.hsts.preload) {
+				hstsValue += '; preload';
+			}
+			headers.set('Strict-Transport-Security', hstsValue);
+		}
+
+		// Content-Security-Policy
+		if (this.config.contentSecurityPolicy.enabled) {
+			const csp = this.buildCsp(this.config.contentSecurityPolicy.directives);
+			headers.set('Content-Security-Policy', csp);
+		}
+
+		// Referrer-Policy
+		if (this.config.referrerPolicy) {
+			headers.set('Referrer-Policy', this.config.referrerPolicy);
+		}
+
+		// X-Permitted-Cross-Domain-Policies
+		if (this.config.crossDomainPolicy) {
+			headers.set('X-Permitted-Cross-Domain-Policies', this.config.crossDomainPolicy);
+		}
+
+		// X-Download-Options (IE)
+		if (this.config.downloadOptions) {
+			headers.set('X-Download-Options', 'noopen');
+		}
+
+		return new Response(response.body, {
+			status: response.status,
+			statusText: response.statusText,
+			headers,
+		});
+	}
+
+	/**
+	 * Build Content-Security-Policy header value
+	 */
+	private buildCsp(directives: Record<string, string | string[]>): string {
+		const parts: string[] = [];
+
+		for (const [directive, value] of Object.entries(directives)) {
+			const directiveName = this.camelToKebab(directive);
+			const directiveValue = Array.isArray(value) ? value.join(' ') : value;
+			parts.push(`${directiveName} ${directiveValue}`);
+		}
+
+		return parts.join('; ');
+	}
+
+	/**
+	 * Convert camelCase to kebab-case
+	 */
+	private camelToKebab(str: string): string {
+		return str.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+	}
+}
+
+/**
+ * Create a Helmet middleware instance with the given config
+ */
+export function helmet(config: Partial<HelmetConfig> = {}): HelmetMiddleware {
+	const defaultConfig: HelmetConfig = {
+		frameOptions: 'DENY',
+		contentTypeOptions: true,
+		xssProtection: true,
+		hsts: {
+			enabled: true,
+			maxAge: 31536000,
+			includeSubDomains: true,
+			preload: false,
+		},
+		contentSecurityPolicy: {
+			enabled: false,
+			directives: {},
+		},
+		referrerPolicy: 'no-referrer',
+		crossDomainPolicy: 'none',
+		downloadOptions: true,
+	};
+
+	return new HelmetMiddleware({
+		...defaultConfig,
+		...config,
+		hsts: { ...defaultConfig.hsts, ...(config.hsts || {}) },
+		contentSecurityPolicy: {
+			...defaultConfig.contentSecurityPolicy,
+			...(config.contentSecurityPolicy || {}),
+		},
+	});
+}