@stacksjs/bun-router 0.0.14 → 0.0.15

package/dist/middleware/security.d.ts

@@ -0,0 +1,69 @@
+import type { EnhancedRequest, NextFunction } from '../types';
+export interface SecurityOptions {
+    inputValidation?: {
+        enabled?: boolean;
+        maxBodySize?: number;
+        maxUrlLength?: number;
+        maxHeaderSize?: number;
+        allowedContentTypes?: string[];
+        sanitizeInput?: boolean;
+        validateEncoding?: boolean;
+    };
+    requestFiltering?: {
+        enabled?: boolean;
+        blockSuspiciousPatterns?: boolean;
+        maxRequestsPerMinute?: number;
+        blockUserAgents?: string[];
+        allowedMethods?: string[];
+        requireUserAgent?: boolean;
+    };
+    ipFiltering?: {
+        enabled?: boolean;
+        whitelist?: string[];
+        blacklist?: string[];
+        blockPrivateIPs?: boolean;
+        blockCloudProviders?: boolean;
+        geoBlocking?: {
+            enabled?: boolean;
+            allowedCountries?: string[];
+            blockedCountries?: string[];
+        };
+    };
+    attackPrevention?: {
+        enabled?: boolean;
+        sqlInjection?: boolean;
+        xss?: boolean;
+        pathTraversal?: boolean;
+        commandInjection?: boolean;
+        ldapInjection?: boolean;
+        xxe?: boolean;
+        customPatterns?: Array<{
+            name: string;
+            pattern: RegExp;
+            action: 'block' | 'log' | 'sanitize';
+        }>;
+    };
+    responseSecurity?: {
+        enabled?: boolean;
+        removeServerHeaders?: boolean;
+        addSecurityHeaders?: boolean;
+        sanitizeErrors?: boolean;
+        preventInfoDisclosure?: boolean;
+    };
+}
+export default class Security {
+    private options;
+    private suspiciousPatterns;
+    private sqlInjectionPatterns;
+    private xssPatterns;
+    private pathTraversalPatterns;
+    private commandInjectionPatterns;
+    constructor(options?: SecurityOptions);
+    private initializePatterns;
+    private getClientIP;
+    private isPrivateIP;
+    private validateInput;
+    private sanitizeInput;
+    handle(req: EnhancedRequest, next: NextFunction): Promise<Response>;
+}
+export declare function security(options?: SecurityOptions): (req: EnhancedRequest, next: NextFunction) => Promise<Response>;

package/dist/middleware/security_suite.d.ts

@@ -0,0 +1,46 @@
+import type { EnhancedRequest, MiddlewareHandler, NextFunction } from '../types';
+export interface SecuritySuiteOptions {
+    helmet?: boolean | object;
+    security?: boolean | object;
+    ddosProtection?: boolean | object;
+    inputValidation?: boolean | object;
+    contentSecurityPolicy?: boolean | object;
+    order?: string[];
+}
+/**
+ * Comprehensive security middleware suite that combines multiple security layers
+ */
+export default class SecuritySuite {
+    private middlewares;
+    constructor(options?: SecuritySuiteOptions);
+    handle(req: EnhancedRequest, next: NextFunction): Promise<Response | null>;
+}
+/**
+ * Factory function to create a security suite middleware
+ */
+export declare function securitySuite(options?: SecuritySuiteOptions): MiddlewareHandler;
+/**
+ * Preset configurations for different security levels
+ */
+export declare const securityPresets: {
+    /**
+     * Basic security - minimal performance impact
+     */
+    basic: () => MiddlewareHandler;
+    /**
+     * Standard security - balanced security and performance
+     */
+    standard: () => MiddlewareHandler;
+    /**
+     * High security - maximum protection
+     */
+    high: () => MiddlewareHandler;
+    /**
+     * API security - optimized for API endpoints
+     */
+    api: () => MiddlewareHandler;
+    /**
+     * Development security - minimal restrictions for development
+     */
+    development: () => MiddlewareHandler;
+};

package/dist/middleware/session.d.ts

@@ -0,0 +1,23 @@
+import type { EnhancedRequest, NextFunction } from '../types';
+import type { SessionStore, SessionData } from '../types/core';
+/**
+ * Session middleware with pluggable store support.
+ *
+ * By default uses an in-memory store. Configure with a different store
+ * for persistent sessions (file, redis, database).
+ *
+ * @example
+ * // Use default memory store
+ * const session = new Session()
+ *
+ * // Use a custom store
+ * import { RedisSessionStore } from 'bun-router/session'
+ * const session = new Session({ store: new RedisSessionStore(redisClient) })
+ */
+export default class Session {
+    private store;
+    constructor(options?: {
+        store?: SessionStore<SessionData>;
+    });
+    handle(req: EnhancedRequest, next: NextFunction): Promise<Response>;
+}

package/dist/model-binding/index.d.ts

@@ -0,0 +1,2 @@
+export { bindModel, createModelBindingMiddleware, ModelBindingFactory, type ModelBindingMiddlewareOptions, ModelBindingUtils, TypedModelBinding, withModelBinding, } from './model-middleware';
+export { type ModelBindingConfig, ModelFactory, ModelRegistry, modelRegistry, type ModelResolutionResult, ModelUtils, } from './model-registry';

package/dist/model-binding/model-middleware.d.ts

@@ -0,0 +1,118 @@
+import type { EnhancedRequest, ExtractRouteParams } from '../types';
+/**
+ * Model binding middleware options
+ */
+export interface ModelBindingMiddlewareOptions {
+    failOnError?: boolean;
+    attachToRequest?: boolean;
+    paramMapping?: Record<string, string>;
+}
+/**
+ * Simplified model binding configuration for middleware
+ */
+export interface ModelBindingRef {
+    model: string;
+    parameter: string;
+    required?: boolean;
+    as?: string;
+}
+/**
+ * Create model binding middleware
+ */
+export declare function createModelBindingMiddleware(bindings: ModelBindingRef[], options?: ModelBindingMiddlewareOptions): (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>;
+/**
+ * Single model binding middleware
+ */
+export declare function bindModel(modelName: string, parameterName: string, options?: {
+    required?: boolean;
+    as?: string;
+    failOnError?: boolean;
+}): (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>;
+/**
+ * Route parameter model binding decorator
+ */
+export declare function withModelBinding<TPath extends string>(bindings: ModelBindingRef[]): (_target: any, _propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Model binding utilities for middleware
+ */
+export declare const ModelBindingUtils: {
+    /**
+     * Create middleware for a specific model type
+     */
+    forModel<T>(modelName: string, paramName: string, options?: {
+        validator?: (model: T) => boolean | Promise<boolean>;
+        transformer?: (model: T) => T | Promise<T>;
+        cache?: boolean;
+    }): (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>;
+    /**
+     * Create middleware that binds multiple models
+     */
+    multiple(bindings: Array<{
+        model: string;
+        param: string;
+        required?: boolean;
+    }>): (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>;
+    /**
+     * Create middleware that validates model ownership
+     */
+    requireOwnership<T extends {
+        userId?: string | number;
+    }>(modelName: string, userIdField?: string): (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>;
+    /**
+     * Create middleware that caches resolved models
+     */
+    withCache(modelName: string, paramName: string, _options?: {
+        ttl?: number;
+        keyGenerator?: (params: Record<string, string>) => string;
+    }): (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>;
+    /**
+     * Create middleware that handles optional model binding
+     */
+    optional(modelName: string, paramName: string): (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>;
+};
+/**
+ * Model binding middleware factory
+ */
+export declare class ModelBindingFactory {
+    /**
+     * Create binding for user model
+     */
+    static user(paramName?: string, as?: string): (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>;
+    /**
+     * Create binding for post model
+     */
+    static post(paramName?: string, as?: string): (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>;
+    /**
+     * Create binding for category model
+     */
+    static category(paramName?: string, as?: string): (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>;
+    /**
+     * Create binding for any resource with ownership validation
+     */
+    static ownedResource(modelName: string, paramName: string, userIdField?: string): Array<(req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>>;
+    /**
+     * Create nested resource bindings (e.g., user -> posts)
+     */
+    static nested(parentModel: string, parentParam: string, childModel: string, childParam: string): (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>;
+}
+/**
+ * Type-safe model binding helpers
+ */
+export declare const TypedModelBinding: {
+    /**
+     * Create a typed model binding that preserves route parameter types
+     */
+    create<TPath extends string>(bindings: Array<{
+        model: string;
+        param: keyof ExtractRouteParams<TPath>;
+        required?: boolean;
+        as?: string;
+    }>): (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>;
+    /**
+     * Create a single typed model binding
+     */
+    single<TPath extends string>(modelName: string, param: keyof ExtractRouteParams<TPath>, options?: {
+        required?: boolean;
+        as?: string;
+    }): (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>;
+};

package/dist/model-binding/model-registry.d.ts

@@ -0,0 +1,164 @@
+import type { EnhancedRequest, ModelResolver, ModelTransformerFn, ModelValidatorFn } from '../types';
+/**
+ * Model resolution result
+ */
+export interface ModelResolutionResult<T = any> {
+    model: T | null;
+    error?: string;
+    status?: number;
+}
+/**
+ * Model binding configuration for a specific model
+ */
+export interface ModelBindingConfig<T = any> {
+    resolver: ModelResolver<T>;
+    validator?: ModelValidatorFn<T>;
+    transformer?: ModelTransformerFn<T>;
+    cache?: {
+        enabled: boolean;
+        ttl: number;
+        key?: (params: Record<string, string>) => string;
+    };
+    errorHandling?: {
+        notFound?: (params: Record<string, string>) => Response;
+        validation?: (model: T, error: string) => Response;
+        transform?: (error: string) => Response;
+    };
+}
+/**
+ * Model registry for managing model bindings
+ */
+export declare class ModelRegistry {
+    private models;
+    private cache;
+    /**
+     * Register a model binding
+     */
+    register<T>(name: string, config: ModelBindingConfig<T>): void;
+    /**
+     * Get model binding configuration
+     */
+    get(name: string): ModelBindingConfig | undefined;
+    /**
+     * Check if model is registered
+     */
+    has(name: string): boolean;
+    /**
+     * Resolve a model using its binding
+     */
+    resolve<T>(modelName: string, params: Record<string, string>, req?: EnhancedRequest): Promise<ModelResolutionResult<T>>;
+    /**
+     * Create error response for model binding failure
+     */
+    createErrorResponse(modelName: string, result: ModelResolutionResult, params: Record<string, string>): Response;
+    /**
+     * Clear cache for a specific model
+     */
+    clearCache(modelName: string, params?: Record<string, string>): void;
+    /**
+     * Clear all cache
+     */
+    clearAllCache(): void;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        totalEntries: number;
+        validEntries: number;
+        expiredEntries: number;
+        models: number;
+    };
+    /**
+     * Cleanup expired cache entries
+     */
+    cleanupCache(): number;
+    /**
+     * Get cached model if available and valid
+     */
+    private getCachedModel;
+    /**
+     * Cache a model
+     */
+    private cacheModel;
+    /**
+     * Generate cache key for model
+     */
+    private generateCacheKey;
+}
+/**
+ * Global model registry instance
+ */
+export declare const modelRegistry: ModelRegistry;
+/**
+ * Model binding utilities
+ */
+export declare const ModelUtils: {
+    /**
+     * Create a simple resolver for database models
+     */
+    dbResolver<T>(tableName: string, idField?: string, db?: any): ModelResolver<T>;
+    /**
+     * Create a validator that checks required fields
+     */
+    requiredFieldsValidator<T extends Record<string, any>>(fields: (keyof T)[]): ModelValidatorFn<T>;
+    /**
+     * Create a transformer that picks specific fields
+     */
+    pickFieldsTransformer<T, K extends keyof T>(fields: K[]): ModelTransformerFn<T>;
+    /**
+     * Create a transformer that excludes specific fields
+     */
+    omitFieldsTransformer<T, K extends keyof T>(fields: K[]): ModelTransformerFn<T>;
+    /**
+     * Create a UUID validator
+     */
+    uuidValidator<T extends {
+        id: string;
+    }>(): ModelValidatorFn<T>;
+    /**
+     * Create ownership validator (checks if user owns the model)
+     */
+    ownershipValidator<T extends {
+        userId?: string | number;
+    }>(userIdField?: string): ModelValidatorFn<T>;
+};
+/**
+ * Common model binding factories
+ */
+export declare const ModelFactory: {
+    /**
+     * Create a simple model binding for database entities
+     */
+    entity<T>(tableName: string, options?: {
+        idField?: string;
+        cache?: boolean;
+        cacheTtl?: number;
+        validator?: ModelValidatorFn<T>;
+        transformer?: ModelTransformerFn<T>;
+        db?: any;
+    }): ModelBindingConfig<T>;
+    /**
+     * Create a user model binding with ownership validation
+     */
+    user<T extends {
+        id: string;
+        userId?: string;
+    }>(tableName?: string, options?: {
+        cache?: boolean;
+        cacheTtl?: number;
+        db?: any;
+    }): ModelBindingConfig<T>;
+    /**
+     * Create a resource model binding with ownership check
+     */
+    ownedResource<T extends {
+        id: string;
+        userId: string;
+    }>(tableName: string, options?: {
+        idField?: string;
+        userIdField?: string;
+        cache?: boolean;
+        cacheTtl?: number;
+        db?: any;
+    }): ModelBindingConfig<T>;
+};

package/dist/model-binding.d.ts

@@ -0,0 +1,185 @@
+import type { EnhancedRequest } from './types';
+/**
+ * Laravel-style model binding that integrates with bun-query-builder models
+ */
+/**
+ * Base model interface compatible with bun-query-builder
+ */
+export interface Model {
+    id: string | number;
+    [key: string]: any;
+    /**
+     * Get the route key for the model (Laravel-style)
+     */
+    getRouteKeyName?: () => string;
+    /**
+     * Resolve route binding for this model instance (Laravel-style)
+     */
+    resolveRouteBinding?: (value: string | number, field?: string) => Promise<this | null>;
+}
+/**
+ * Query builder model resolver interface for integration layer
+ */
+export interface QueryBuilderModelResolver<TModel extends Model = Model> {
+    table: string;
+    queryBuilder?: any;
+    /**
+     * Find a model by ID or custom key
+     */
+    find: (id: string | number, keyName?: string) => Promise<TModel | null>;
+    /**
+     * Find a model by ID or throw if not found
+     */
+    findOrFail: (id: string | number, keyName?: string) => Promise<TModel>;
+    /**
+     * Get the route key name for this model
+     */
+    getRouteKeyName?: () => string;
+    /**
+     * Apply constraints to a query (for scoped binding)
+     */
+    applyConstraints?: (query: any, context: Record<string, Model>) => any;
+}
+/**
+ * Wrapper for bun-query-builder models to add Laravel-style route binding
+ */
+export declare class BunQueryBuilderModel<T extends Model = Model> {
+    definition: any;
+    queryBuilder: any;
+    constructor(definition: any, // bun-query-builder model definition
+    queryBuilder: any);
+    /**
+     * Get table name from bun-query-builder definition
+     */
+    getTableName(): string;
+    /**
+     * Find a model by ID using bun-query-builder's find method
+     */
+    find(id: string | number): Promise<T | null>;
+    /**
+     * Find a model by ID or throw using bun-query-builder's findOrFail method
+     */
+    findOrFail(id: string | number): Promise<T>;
+    /**
+     * Find by custom field using bun-query-builder's where method
+     */
+    where(field: string, value: any): Promise<T | null>;
+    /**
+     * Get the default route key name for this model
+     */
+    getRouteKeyName(): string;
+    /**
+     * Custom route binding resolution (can be overridden)
+     */
+    resolveRouteBinding(value: string | number, field?: string): Promise<T | null>;
+}
+/**
+ * Parse route parameter to extract model name and custom key
+ * Examples: {user} -> {name: 'user', key: undefined}
+ *          {post:slug} -> {name: 'post', key: 'slug'}
+ */
+/**
+ * Parse multiple route parameters from path
+ */
+export declare function parseRouteParameters(path: string): {
+    name: string;
+    key?: string;
+}[];
+export declare function parseRouteParameter(param: string): {
+    name: string;
+    key?: string;
+};
+/**
+ * Extract model parameters from route path
+ */
+export declare function extractModelParameters(path: string): {
+    name: string;
+    key?: string;
+}[];
+/**
+ * Model not found error
+ */
+export declare class ModelNotFoundError extends Error {
+    modelName: string;
+    value: string | number;
+    field: string;
+    constructor(modelName: string, value: string | number, field?: string);
+}
+/**
+ * Model binding registry for explicit bindings (Laravel Route::model and Route::bind)
+ */
+export declare class ModelBindingRegistry {
+    private bindings;
+    /**
+     * Register explicit model binding (Laravel Route::model style)
+     */
+    model<T extends Model>(parameter: string, modelWrapper: BunQueryBuilderModel<T>): void;
+    /**
+     * Register custom binding resolver (Laravel Route::bind style)
+     */
+    bind(parameter: string, resolver: (value: string) => Promise<Model | null>): void;
+    /**
+     * Get binding for parameter
+     */
+    getBinding(parameter: string): BunQueryBuilderModel | ((_value: string) => Promise<Model | null>) | undefined;
+    /**
+     * Check if parameter has explicit binding
+     */
+    hasBinding(parameter: string): boolean;
+}
+/**
+ * Global model binding registry instance
+ */
+export declare const modelRegistry: ModelBindingRegistry;
+/**
+ * Model binding configuration interface
+ */
+export interface ModelBindingConfig {
+    model: string;
+    key?: string;
+    constraints?: Record<string, any>;
+}
+/**
+ * Model class interface
+ */
+export interface ModelClass<T extends Model = Model> {
+    new (...args: any[]): T;
+    find: (id: string | number) => Promise<T | null>;
+    findOrFail: (id: string | number) => Promise<T>;
+}
+/**
+ * Model resolver interface
+ */
+export interface ModelResolver<T extends Model = Model> {
+    find: (id: string | number, keyName?: string) => Promise<T | null>;
+    findOrFail: (id: string | number, keyName?: string) => Promise<T>;
+    getRouteKeyName?: () => string;
+}
+/**
+ * Route binding options interface
+ */
+export interface RouteBindingOptions {
+    model?: string;
+    key?: string;
+    constraints?: Record<string, any>;
+    middleware?: string[];
+}
+/**
+ * Resolve model from route parameter using bun-query-builder
+ */
+export declare function resolveModel<T extends Model>(_paramName: string, value: string | number, modelWrapper: BunQueryBuilderModel<T>, customKey?: string, _context?: Record<string, Model>): Promise<T | null>;
+/**
+ * Route model binding middleware factory for bun-query-builder models
+ */
+export declare function createModelBindingMiddleware(modelParameters: {
+    name: string;
+    key?: string;
+}[], modelWrappers: Record<string, BunQueryBuilderModel>): (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>;
+/**
+ * Create a model wrapper from bun-query-builder model definition
+ */
+export declare function createModelWrapper<T extends Model>(modelDefinition: any, queryBuilder: any): BunQueryBuilderModel<T>;
+/**
+ * Apply model bindings to a route
+ */
+export declare function applyModelBindings(path: string, modelWrappers: Record<string, BunQueryBuilderModel>, _options?: RouteBindingOptions): (req: EnhancedRequest, next: () => Promise<Response>) => Promise<Response>;

package/dist/model-resolver-factory.d.ts

@@ -0,0 +1,31 @@
+import type { Model, QueryBuilderModelResolver } from './model-binding';
+/**
+ * Factory function to create model resolvers with bun-query-builder integration
+ */
+export declare function createModelResolver<TModel extends Model = Model>(tableName: string, options?: {
+    keyName?: string;
+    applyConstraints?: (query: any, context: Record<string, Model>) => any;
+}): QueryBuilderModelResolver<TModel>;
+/**
+ * Create a scoped model resolver that applies constraints based on parent models
+ */
+export declare function createScopedModelResolver<TModel extends Model = Model>(tableName: string, constraintFn: (query: any, context: Record<string, Model>) => any, options?: {
+    keyName?: string;
+}): QueryBuilderModelResolver<TModel>;
+/**
+ * Common constraint functions for scoped bindings
+ */
+export declare const constraints: {
+    /**
+     * Ensure a model belongs to a specific parent model
+     */
+    belongsTo: (parentKey: string, foreignKey: string) => ((_query: any, _context: Record<string, Model>) => any);
+    /**
+     * Ensure a model belongs to the authenticated user
+     */
+    belongsToUser: (userKey?: string, foreignKey?: string) => ((_query: any, _context: Record<string, Model>) => any);
+    /**
+     * Apply multiple constraints
+     */
+    combine: (...constraintFns: Array<(query: any, context: Record<string, Model>) => any>) => ((query: any, context: Record<string, Model>) => any);
+};