@expressots/core 3.0.0-beta.4 → 4.0.0-preview.1

package/lib/cjs/application/index.js

@@ -1,9 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ServerEnvironment = exports.AppFactory = exports.AppContainer = void 0;
-var application_container_1 = require("./application-container");
-Object.defineProperty(exports, "AppContainer", { enumerable: true, get: function () { return application_container_1.AppContainer; } });
-var application_factory_1 = require("./application-factory");
-Object.defineProperty(exports, "AppFactory", { enumerable: true, get: function () { return application_factory_1.AppFactory; } });
-var application_types_1 = require("./application.types");
-Object.defineProperty(exports, "ServerEnvironment", { enumerable: true, get: function () { return application_types_1.ServerEnvironment; } });
+exports.loadEnvSync = exports.bootstrap = exports.ServerEnvironment = exports.AppFactory = exports.AppContainer = void 0;
+var application_container_js_1 = require("./application-container.js");
+Object.defineProperty(exports, "AppContainer", { enumerable: true, get: function () { return application_container_js_1.AppContainer; } });
+var application_factory_js_1 = require("./application-factory.js");
+Object.defineProperty(exports, "AppFactory", { enumerable: true, get: function () { return application_factory_js_1.AppFactory; } });
+var application_types_js_1 = require("./application.types.js");
+Object.defineProperty(exports, "ServerEnvironment", { enumerable: true, get: function () { return application_types_js_1.ServerEnvironment; } });
+var bootstrap_js_1 = require("./bootstrap.js");
+Object.defineProperty(exports, "bootstrap", { enumerable: true, get: function () { return bootstrap_js_1.bootstrap; } });
+Object.defineProperty(exports, "loadEnvSync", { enumerable: true, get: function () { return bootstrap_js_1.loadEnvSync; } });

package/lib/cjs/authorization/authorization-config.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/cjs/authorization/decorators/convenience.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequireAuthentication = RequireAuthentication;
+exports.RequireRoles = RequireRoles;
+exports.RequirePermissions = RequirePermissions;
+exports.RequireOwnership = RequireOwnership;
+const guard_decorators_js_1 = require("../guard-decorators.js");
+const index_js_1 = require("../guards/index.js");
+/**
+ * Shorthand decorator for requiring authentication
+ * Equivalent to @UseGuards(RequireAuth())
+ *
+ * @example
+ * ```typescript
+ * @controller("/api/users")
+ * export class UserController {
+ *   @Get("/profile")
+ *   @RequireAuthentication()
+ *   getProfile(@principal() principal: Principal) {
+ *     return principal.details;
+ *   }
+ * }
+ * ```
+ */
+function RequireAuthentication() {
+    return (0, guard_decorators_js_1.UseGuards)((0, index_js_1.RequireAuth)());
+}
+/**
+ * Shorthand decorator for requiring specific roles
+ * Equivalent to @UseGuards(RequireRole(...roles))
+ *
+ * @example
+ * ```typescript
+ * @controller("/api/admin")
+ * export class AdminController {
+ *   @Get("/users")
+ *   @RequireRoles("admin")
+ *   getUsers() {}
+ * }
+ * ```
+ */
+function RequireRoles(...roles) {
+    return (0, guard_decorators_js_1.UseGuards)((0, index_js_1.RequireRole)(...roles));
+}
+/**
+ * Shorthand decorator for requiring specific permissions
+ * Equivalent to @UseGuards(RequirePermission(...permissions))
+ *
+ * @example
+ * ```typescript
+ * @controller("/api/documents")
+ * export class DocumentController {
+ *   @Get("/")
+ *   @RequirePermissions("documents:read")
+ *   listDocuments() {}
+ * }
+ * ```
+ */
+function RequirePermissions(...permissions) {
+    return (0, guard_decorators_js_1.UseGuards)(...permissions.map((p) => (0, index_js_1.RequirePermission)(p)));
+}
+/**
+ * Shorthand decorator for requiring resource ownership
+ * Equivalent to @UseGuards(RequireResourceOwner(paramName))
+ *
+ * @example
+ * ```typescript
+ * @controller("/api/documents")
+ * export class DocumentController {
+ *   @Delete("/:id")
+ *   @RequireOwnership("id")
+ *   deleteDocument(@param("id") id: string) {
+ *     // Only resource owner can delete
+ *   }
+ * }
+ * ```
+ */
+function RequireOwnership(paramName = "id") {
+    return (0, guard_decorators_js_1.UseGuards)((0, index_js_1.RequireResourceOwner)(paramName));
+}

package/lib/cjs/authorization/guard-constants.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GUARD_METADATA_KEY = void 0;
+/**
+ * Metadata keys for guard system
+ * These are used by the guard decorators and registry
+ */
+exports.GUARD_METADATA_KEY = {
+    guard: "expressots:guard",
+    controllerGuards: "expressots:controller-guards",
+    methodGuards: "expressots:method-guards",
+};

package/lib/cjs/authorization/guard-decorators.js

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Guard = Guard;
+exports.UseGuards = UseGuards;
+require("reflect-metadata");
+const guard_constants_js_1 = require("./guard-constants.js");
+/**
+ * Decorator to mark a class as a guard (for auto-discovery).
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept guard-decorator
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Mark your guard class with `@Guard()` to enable auto-discovery.
+ *
+ * @example
+ * ```typescript
+ * @Guard({ priority: 1, cacheable: true })
+ * @provide(AuthenticatedGuard)
+ * export class AuthenticatedGuard implements IGuard {
+ *   async canActivate(context: GuardContext): Promise<GuardResult> {
+ *     const isAuthenticated = await context.principal.isAuthenticated();
+ *     return isAuthenticated ? GuardResult.allow() : GuardResult.deny();
+ *   }
+ * }
+ * ```
+ *
+ * @param options - Guard options
+ * @param options.priority - Execution priority (lower = earlier). Default: 100
+ * @param options.cacheable - Whether result can be cached. Default: false
+ * @returns ClassDecorator
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Behavior**
+ * - Registers guard metadata for auto-discovery
+ * - Stores metadata in global registry via Reflect
+ * - GuardRegistry discovers guards during initialization
+ *
+ * **Priority System**
+ * - Lower priority = earlier execution
+ * - Authentication guards typically use priority 1-10
+ * - Authorization guards typically use priority 50-100
+ * - Resource guards typically use priority 100+
+ *
+ * @see {@link GuardRegistry} for auto-discovery mechanism
+ * @see {@link UseGuards} for applying guards to routes
+ *
+ * @public API
+ */
+function Guard(options) {
+    return (target) => {
+        const metadata = {
+            priority: options?.priority ?? 100,
+            cacheable: options?.cacheable ?? false,
+            guard: target,
+        };
+        Reflect.defineMetadata(guard_constants_js_1.GUARD_METADATA_KEY.guard, metadata, target);
+        // Register in global registry for auto-discovery
+        const existingGuards = Reflect.getMetadata(guard_constants_js_1.GUARD_METADATA_KEY.guard, Reflect) || [];
+        const newGuards = [...existingGuards, metadata];
+        Reflect.defineMetadata(guard_constants_js_1.GUARD_METADATA_KEY.guard, newGuards, Reflect);
+    };
+}
+/**
+ * Apply guards at controller or method level.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept guard-application
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Apply guards to protect routes. Can be used at controller or method level.
+ *
+ * @example
+ * ```typescript
+ * // Controller-level guards
+ * @UseGuards(AuthenticatedGuard, RoleGuard)
+ * @controller("/users")
+ * export class UserController {
+ *   @Get("/")
+ *   getUsers() {
+ *     // Both guards apply to all methods
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Method-level guards (overrides controller-level)
+ * @controller("/users")
+ * export class UserController {
+ *   @Get("/:id")
+ *   @UseGuards(ResourceOwnerGuard) // Only this guard applies
+ *   getUser(@param("id") id: string) {
+ *     // Only ResourceOwnerGuard applies
+ *   }
+ * }
+ * ```
+ *
+ * @param guards - Guard classes or instances to apply
+ * @returns ClassDecorator & MethodDecorator
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Behavior**
+ * - Stores guard metadata on controller/method
+ * - Method-level guards override controller-level guards
+ * - Guards are resolved and executed by GuardExecutor
+ * - Execution order follows guard priority
+ *
+ * **Guard Resolution**
+ * - GuardRegistry resolves guard instances
+ * - Supports both guard classes and instances
+ * - Factory functions (RequireAuth, RequireRole) create instances dynamically
+ *
+ * @see {@link Guard} for creating guards
+ * @see {@link GuardExecutor} for execution logic
+ *
+ * @layer advanced
+ * @audience power-users
+ *
+ * **Advanced Usage**
+ *
+ * Combining multiple guards:
+ * ```typescript
+ * @UseGuards(AuthenticatedGuard, RequireRole("admin"), RequirePermission("users:read"))
+ * ```
+ *
+ * Conditional guards:
+ * ```typescript
+ * @UseGuards(ConditionalGuard(() => process.env.NODE_ENV === "production"))
+ * ```
+ *
+ * @public API
+ */
+function UseGuards(...guards) {
+    return (
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    target, propertyKey) => {
+        if (propertyKey) {
+            // Method-level guards
+            const existingGuards = Reflect.getMetadata(guard_constants_js_1.GUARD_METADATA_KEY.methodGuards, target.constructor, propertyKey) || [];
+            const newGuards = [...existingGuards, ...guards];
+            Reflect.defineMetadata(guard_constants_js_1.GUARD_METADATA_KEY.methodGuards, newGuards, target.constructor, propertyKey);
+        }
+        else {
+            // Controller-level guards
+            const existingGuards = Reflect.getMetadata(guard_constants_js_1.GUARD_METADATA_KEY.controllerGuards, target) || [];
+            const newGuards = [...existingGuards, ...guards];
+            Reflect.defineMetadata(guard_constants_js_1.GUARD_METADATA_KEY.controllerGuards, newGuards, target);
+        }
+    };
+}

package/lib/cjs/authorization/guard-executor.js

@@ -0,0 +1,101 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GuardExecutor = void 0;
+const inversify_js_1 = require("../di/inversify.js");
+const logger_provider_js_1 = require("../provider/logger/logger.provider.js");
+const guard_interface_js_1 = require("./guard.interface.js");
+const guard_registry_js_1 = require("./guard-registry.js");
+/**
+ * Executor for running guards in priority order with caching support
+ */
+let GuardExecutor = class GuardExecutor {
+    constructor(registry, cache, logger) {
+        this.registry = registry;
+        this.cache = cache;
+        this.logger = logger;
+    }
+    /**
+     * Execute guards in priority order with caching support
+     * @param guards - Array of guard classes or instances
+     * @param context - Guard context with request, principal, container, and scope
+     * @returns GuardResult indicating if access is allowed
+     */
+    async execute(guards, context) {
+        if (guards.length === 0) {
+            return guard_interface_js_1.GuardResult.allow();
+        }
+        // 1. Resolve guards and sort by priority
+        const resolvedGuards = guards
+            .map((g) => this.registry.get(g))
+            .sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100));
+        // 2. Execute guards sequentially
+        for (const guard of resolvedGuards) {
+            try {
+                // Check cache if cacheable
+                if (guard.cacheable) {
+                    const cacheKey = guard.cacheKey
+                        ? guard.cacheKey(context)
+                        : this.defaultCacheKey(guard, context);
+                    const cached = this.cache.get(context.scope.request, cacheKey);
+                    if (cached !== null) {
+                        if (!cached.allowed) {
+                            return cached;
+                        }
+                        continue; // Allow, check next guard
+                    }
+                }
+                // Execute guard
+                const result = await guard.canActivate(context);
+                const guardResult = result instanceof guard_interface_js_1.GuardResult
+                    ? result
+                    : result
+                        ? guard_interface_js_1.GuardResult.allow()
+                        : guard_interface_js_1.GuardResult.deny();
+                // Cache result if cacheable and allowed
+                if (guard.cacheable && guardResult.allowed) {
+                    const cacheKey = guard.cacheKey
+                        ? guard.cacheKey(context)
+                        : this.defaultCacheKey(guard, context);
+                    this.cache.set(context.scope.request, cacheKey, guardResult);
+                }
+                // Early exit on deny
+                if (!guardResult.allowed) {
+                    return guardResult;
+                }
+            }
+            catch (error) {
+                this.logger.error(`Guard ${guard.constructor.name} threw an error: ${error}`, "guard-executor");
+                // On error, deny access for security
+                return guard_interface_js_1.GuardResult.deny();
+            }
+        }
+        return guard_interface_js_1.GuardResult.allow();
+    }
+    /**
+     * Generate default cache key for guard
+     * @private
+     */
+    defaultCacheKey(guard, context) {
+        return `${guard.constructor.name}:${context.route.method}:${context.route.path}`;
+    }
+};
+exports.GuardExecutor = GuardExecutor;
+exports.GuardExecutor = GuardExecutor = __decorate([
+    (0, inversify_js_1.injectable)(),
+    __param(0, (0, inversify_js_1.inject)(guard_registry_js_1.GuardRegistry)),
+    __param(1, (0, inversify_js_1.inject)("IGuardCache")),
+    __param(2, (0, inversify_js_1.inject)(logger_provider_js_1.Logger)),
+    __metadata("design:paramtypes", [guard_registry_js_1.GuardRegistry, Object, logger_provider_js_1.Logger])
+], GuardExecutor);

package/lib/cjs/authorization/guard-registry.js

@@ -0,0 +1,133 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GuardRegistry = void 0;
+require("reflect-metadata");
+const inversify_js_1 = require("../di/inversify.js");
+const logger_provider_js_1 = require("../provider/logger/logger.provider.js");
+const guard_constants_js_1 = require("./guard-constants.js");
+/**
+ * Registry for managing guards with automatic discovery
+ * Similar to ExceptionFilterRegistry
+ */
+let GuardRegistry = class GuardRegistry {
+    constructor(container, logger) {
+        this.container = container;
+        this.logger = logger;
+        this.guards = new Map();
+        this.initialized = false;
+    }
+    /**
+     * Initialize the registry by auto-discovering all guards decorated with @Guard
+     * This should be called after the container is fully configured
+     */
+    initialize() {
+        if (this.initialized) {
+            return;
+        }
+        try {
+            // Get all guards registered via @Guard decorator
+            const guardMetadata = Reflect.getMetadata(guard_constants_js_1.GUARD_METADATA_KEY.guard, Reflect) || [];
+            guardMetadata.forEach(({ guard, priority, cacheable }) => {
+                try {
+                    // Try to get guard from container (if @provide() decorated)
+                    let guardInstance;
+                    if (this.container.isBound(guard)) {
+                        guardInstance = this.container.get(guard);
+                    }
+                    else {
+                        // Try to create instance manually if not in container
+                        // Some guards require constructor arguments (RoleGuard, PermissionGuard, etc.)
+                        // Only register guards that can be instantiated without arguments
+                        try {
+                            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                            guardInstance = new guard();
+                            // Try to inject common dependencies
+                            this.injectDependencies(guardInstance);
+                        }
+                        catch (constructorError) {
+                            // Guard requires constructor arguments - skip auto-registration
+                            // These guards will be instantiated dynamically via factory functions
+                            // (RequireAuth(), RequireRole(), etc.) when used in @UseGuards()
+                            // Silently skip - this is expected behavior for guards with constructor args
+                            return; // Skip this guard
+                        }
+                    }
+                    // Set metadata
+                    guardInstance.priority = priority;
+                    guardInstance.cacheable = cacheable;
+                    this.guards.set(guard, guardInstance);
+                }
+                catch (error) {
+                    this.logger.warn(`Failed to register guard ${guard.name}: ${error}`, "guard-registry");
+                }
+            });
+            this.initialized = true;
+        }
+        catch (error) {
+            this.logger.error(`Failed to initialize guard registry: ${error}`, "guard-registry");
+        }
+    }
+    /**
+     * Get guard instance (from registry or create new)
+     * @param guard - Guard class or instance
+     * @returns Guard instance
+     */
+    get(guard) {
+        if (typeof guard === "function") {
+            // Try registry first
+            const registered = this.guards.get(guard);
+            if (registered) {
+                return registered;
+            }
+            // Try container
+            if (this.container.isBound(guard)) {
+                return this.container.get(guard);
+            }
+            // Create new instance
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const instance = new guard();
+            this.injectDependencies(instance);
+            return instance;
+        }
+        // Already an instance
+        return guard;
+    }
+    /**
+     * Check if registry is initialized
+     */
+    isInitialized() {
+        return this.initialized;
+    }
+    /**
+     * Inject common dependencies into guard instance
+     * @private
+     */
+    injectDependencies(instance) {
+        // Inject common dependencies if available
+        if (this.container.isBound(logger_provider_js_1.Logger)) {
+            instance.logger = this.container.get(logger_provider_js_1.Logger);
+        }
+        if (this.container.isBound("Report")) {
+            instance.report = this.container.get("Report");
+        }
+    }
+};
+exports.GuardRegistry = GuardRegistry;
+exports.GuardRegistry = GuardRegistry = __decorate([
+    (0, inversify_js_1.injectable)(),
+    __param(0, (0, inversify_js_1.inject)(inversify_js_1.Container)),
+    __param(1, (0, inversify_js_1.inject)(logger_provider_js_1.Logger)),
+    __metadata("design:paramtypes", [Object, logger_provider_js_1.Logger])
+], GuardRegistry);

package/lib/cjs/authorization/guard.interface.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GuardResult = void 0;
+const app_error_js_1 = require("../error/app-error.js");
+/**
+ * Guard result indicating whether access is allowed.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept guard-result
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Use `GuardResult.allow()` or `GuardResult.deny()` to return guard decisions.
+ *
+ * @example
+ * ```typescript
+ * async canActivate(context: GuardContext): Promise<GuardResult> {
+ *   if (await context.principal.isAuthenticated()) {
+ *     return GuardResult.allow();
+ *   }
+ *   return GuardResult.deny(AppError.unauthorized("Please login"));
+ * }
+ * ```
+ *
+ * @public API
+ */
+class GuardResult {
+    constructor(allowed, error) {
+        this.allowed = allowed;
+        this.error = error;
+    }
+    /**
+     * Create an allow result.
+     *
+     * @layer public
+     * @audience application-developers
+     *
+     * @returns GuardResult with allowed = true
+     *
+     * @example
+     * ```typescript
+     * return GuardResult.allow();
+     * ```
+     *
+     * @public API
+     */
+    static allow() {
+        return new GuardResult(true);
+    }
+    /**
+     * Create a deny result.
+     *
+     * @layer public
+     * @audience application-developers
+     *
+     * @param error - Optional error to throw (defaults to forbidden)
+     * @returns GuardResult with allowed = false
+     *
+     * @example
+     * ```typescript
+     * // Default error (403 Forbidden)
+     * return GuardResult.deny();
+     *
+     * // Custom error
+     * return GuardResult.deny(AppError.unauthorized("Please login"));
+     * ```
+     *
+     * @public API
+     */
+    static deny(error) {
+        return new GuardResult(false, error || app_error_js_1.AppError.forbidden("Access denied"));
+    }
+}
+exports.GuardResult = GuardResult;