@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/esm/authorization/guards/authenticated.guard.js

@@ -0,0 +1,45 @@
+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;
+};
+import { Guard } from "../guard-decorators.js";
+import { injectable } from "../../di/inversify.js";
+import { GuardResult } from "../guard.interface.js";
+import { AppError } from "../../error/app-error.js";
+/**
+ * Guard that requires authentication
+ * Checks if principal is authenticated
+ *
+ * @example
+ * ```typescript
+ * @controller("/api/users")
+ * export class UserController {
+ *   @Get("/profile")
+ *   @UseGuards(AuthenticatedGuard)
+ *   getProfile(@principal() principal: Principal) {
+ *     return principal.details;
+ *   }
+ * }
+ * ```
+ * Note: Guards are instantiated dynamically by GuardRegistry, not via DI
+ */
+let AuthenticatedGuard = class AuthenticatedGuard {
+    async canActivate(context) {
+        const isAuthenticated = await context.principal.isAuthenticated();
+        if (!isAuthenticated) {
+            return GuardResult.deny(AppError.unauthorized("Authentication required"));
+        }
+        return GuardResult.allow();
+    }
+};
+AuthenticatedGuard = __decorate([
+    Guard({ priority: 1, cacheable: true }),
+    injectable()
+], AuthenticatedGuard);
+export { AuthenticatedGuard };
+/**
+ * Factory function for convenience
+ */
+export const RequireAuth = () => new AuthenticatedGuard();

package/lib/esm/authorization/guards/composition.guard.js

@@ -0,0 +1,63 @@
+import { GuardResult } from "../guard.interface.js";
+/**
+ * Combine multiple guards (all must pass)
+ *
+ * @example
+ * ```typescript
+ * @controller("/api/sensitive")
+ * export class SensitiveController {
+ *   @Get("/")
+ *   @UseGuards(
+ *     combineGuards(
+ *       RequireAuth(),
+ *       RequireRoles("admin"),
+ *       RequirePermission("sensitive:read")
+ *     )
+ *   )
+ *   getSensitive() {}
+ * }
+ * ```
+ */
+export function combineGuards(...guards) {
+    return {
+        async canActivate(context) {
+            for (const guard of guards) {
+                const guardInstance = typeof guard === "function" ? new guard() : guard;
+                const result = await guardInstance.canActivate(context);
+                const guardResult = result instanceof GuardResult
+                    ? result
+                    : result
+                        ? GuardResult.allow()
+                        : GuardResult.deny();
+                if (!guardResult.allowed) {
+                    return guardResult;
+                }
+            }
+            return GuardResult.allow();
+        },
+        priority: 100,
+    };
+}
+/**
+ * Sequence guards (sequential dependencies)
+ * Same implementation as combineGuards but different semantic meaning
+ *
+ * @example
+ * ```typescript
+ * @controller("/api/data")
+ * export class DataController {
+ *   @Get("/")
+ *   @UseGuards(
+ *     sequenceGuards(
+ *       LoggingGuard,
+ *       AuditGuard,
+ *       RequireAuth()
+ *     )
+ *   )
+ *   getData() {}
+ * }
+ * ```
+ */
+export function sequenceGuards(...guards) {
+    return combineGuards(...guards);
+}

package/lib/esm/authorization/guards/conditional.guard.js

@@ -0,0 +1,38 @@
+import { GuardResult } from "../guard.interface.js";
+/**
+ * Guard that executes conditionally (integrates with existing when/unless pattern)
+ *
+ * @example
+ * ```typescript
+ * @controller("/api/admin")
+ * export class AdminController {
+ *   @Get("/")
+ *   @UseGuards(
+ *     whenGuard(
+ *       (ctx) => ctx.request.method === "POST",
+ *       RequireRoles("super-admin")
+ *     ),
+ *     RequireRoles("admin")
+ *   )
+ *   adminAction() {}
+ * }
+ * ```
+ */
+export function whenGuard(condition, guard) {
+    return {
+        async canActivate(context) {
+            const shouldExecute = await condition(context);
+            if (!shouldExecute) {
+                return GuardResult.allow(); // Skip guard
+            }
+            const guardInstance = typeof guard === "function" ? new guard() : guard;
+            const result = await guardInstance.canActivate(context);
+            return result instanceof GuardResult
+                ? result
+                : result
+                    ? GuardResult.allow()
+                    : GuardResult.deny();
+        },
+        priority: 50,
+    };
+}

package/lib/esm/authorization/guards/index.js

@@ -0,0 +1,8 @@
+// Built-in guards
+export * from "./authenticated.guard.js";
+export * from "./role.guard.js";
+export * from "./permission.guard.js";
+export * from "./resource-owner.guard.js";
+export * from "./attribute-based.guard.js";
+export * from "./conditional.guard.js";
+export * from "./composition.guard.js";

package/lib/esm/authorization/guards/permission.guard.js

@@ -0,0 +1,80 @@
+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);
+};
+import { Guard } from "../guard-decorators.js";
+import { injectable } from "../../di/inversify.js";
+import { inject } from "../../di/annotation/inject.js";
+import { GuardResult } from "../guard.interface.js";
+import { AppError } from "../../error/app-error.js";
+/**
+ * Guard that requires specific permission
+ * Uses SecurityContext for permission checking (request-scoped caching)
+ *
+ * @example
+ * ```typescript
+ * @controller("/api/documents")
+ * export class DocumentController {
+ *   @Get("/")
+ *   @UseGuards(PermissionGuard("documents:read"))
+ *   listDocuments() {}
+ * }
+ * ```
+ * Note: Guards are instantiated dynamically by GuardRegistry, not via DI
+ */
+let PermissionGuard = class PermissionGuard {
+    permission;
+    constructor(permission) {
+        this.permission = permission;
+        if (!permission) {
+            throw new Error("PermissionGuard requires a permission string");
+        }
+    }
+    securityContext;
+    async canActivate(context) {
+        // Try to use SecurityContext if available (request-scoped caching)
+        if (this.securityContext) {
+            const hasPermission = await this.securityContext.hasPermission(this.permission);
+            if (!hasPermission) {
+                return GuardResult.deny(AppError.forbidden(`Missing permission: ${this.permission}`));
+            }
+            return GuardResult.allow();
+        }
+        // Fallback: Check if principal has permission method
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const principal = context.principal;
+        if (typeof principal.hasPermission === "function") {
+            const hasPermission = await principal.hasPermission(this.permission);
+            if (!hasPermission) {
+                return GuardResult.deny(AppError.forbidden(`Missing permission: ${this.permission}`));
+            }
+            return GuardResult.allow();
+        }
+        // No permission checking available
+        return GuardResult.deny(AppError.forbidden(`Permission check not available: ${this.permission}`));
+    }
+    cacheKey(context) {
+        const details = context.principal.details;
+        return `permission:${this.permission}:${details?.id || "anonymous"}`;
+    }
+};
+__decorate([
+    inject("ISecurityContext"),
+    __metadata("design:type", Object)
+], PermissionGuard.prototype, "securityContext", void 0);
+PermissionGuard = __decorate([
+    Guard({ priority: 20, cacheable: true }),
+    injectable(),
+    __metadata("design:paramtypes", [String])
+], PermissionGuard);
+export { PermissionGuard };
+/**
+ * Factory function for convenience
+ * @param permission - Permission to require
+ */
+export const RequirePermission = (permission) => new PermissionGuard(permission);

package/lib/esm/authorization/guards/resource-owner.guard.js

@@ -0,0 +1,58 @@
+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);
+};
+import { Guard } from "../guard-decorators.js";
+import { injectable } from "../../di/inversify.js";
+import { GuardResult } from "../guard.interface.js";
+import { AppError } from "../../error/app-error.js";
+/**
+ * Guard that requires resource ownership
+ * Checks if principal owns the resource specified by route parameter
+ *
+ * @example
+ * ```typescript
+ * @controller("/api/documents")
+ * export class DocumentController {
+ *   @Delete("/:id")
+ *   @UseGuards(ResourceOwnerGuard("id"))
+ *   deleteDocument(@param("id") id: string) {
+ *     // Only resource owner can delete
+ *   }
+ * }
+ * ```
+ * Note: Guards are instantiated dynamically by GuardRegistry, not via DI
+ */
+let ResourceOwnerGuard = class ResourceOwnerGuard {
+    resourceIdParam;
+    constructor(resourceIdParam = "id") {
+        this.resourceIdParam = resourceIdParam;
+    }
+    async canActivate(context) {
+        const resourceId = context.route.params[this.resourceIdParam];
+        if (!resourceId) {
+            return GuardResult.deny(AppError.badRequest(`Resource ID parameter '${this.resourceIdParam}' is required`));
+        }
+        const isOwner = await context.principal.isResourceOwner(resourceId);
+        if (!isOwner) {
+            return GuardResult.deny(AppError.forbidden("Not resource owner"));
+        }
+        return GuardResult.allow();
+    }
+};
+ResourceOwnerGuard = __decorate([
+    Guard({ priority: 30 }),
+    injectable(),
+    __metadata("design:paramtypes", [String])
+], ResourceOwnerGuard);
+export { ResourceOwnerGuard };
+/**
+ * Factory function for convenience
+ * @param paramName - Route parameter name containing resource ID (default: "id")
+ */
+export const RequireResourceOwner = (paramName = "id") => new ResourceOwnerGuard(paramName);

package/lib/esm/authorization/guards/role.guard.js

@@ -0,0 +1,61 @@
+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);
+};
+import { Guard } from "../guard-decorators.js";
+import { injectable } from "../../di/inversify.js";
+import { GuardResult } from "../guard.interface.js";
+import { AppError } from "../../error/app-error.js";
+/**
+ * Guard that requires specific roles
+ * Checks if principal has any of the required roles
+ *
+ * @example
+ * ```typescript
+ * @controller("/api/admin")
+ * export class AdminController {
+ *   @Get("/users")
+ *   @UseGuards(RoleGuard(["admin"]))
+ *   getUsers() {}
+ * }
+ * ```
+ * Note: Guards are instantiated dynamically by GuardRegistry, not via DI
+ */
+let RoleGuard = class RoleGuard {
+    roles;
+    constructor(roles) {
+        this.roles = roles;
+        if (!roles || roles.length === 0) {
+            throw new Error("RoleGuard requires at least one role");
+        }
+    }
+    async canActivate(context) {
+        // Check if user has any of the required roles
+        const roleChecks = await Promise.all(this.roles.map((role) => context.principal.isInRole(role)));
+        const hasRole = roleChecks.some(Boolean);
+        if (!hasRole) {
+            return GuardResult.deny(AppError.forbidden(`Requires one of: ${this.roles.join(", ")}`));
+        }
+        return GuardResult.allow();
+    }
+    cacheKey(context) {
+        const details = context.principal.details;
+        return `role:${this.roles.join(",")}:${details?.id || "anonymous"}`;
+    }
+};
+RoleGuard = __decorate([
+    Guard({ priority: 10, cacheable: true }),
+    injectable(),
+    __metadata("design:paramtypes", [Array])
+], RoleGuard);
+export { RoleGuard };
+/**
+ * Factory function for convenience
+ * @param roles - Roles to require
+ */
+export const RequireRole = (...roles) => new RoleGuard(roles);

package/lib/esm/authorization/index.js

@@ -0,0 +1,24 @@
+// Core interfaces and types
+export * from "./guard.interface.js";
+export * from "./guard-constants.js";
+// Decorators
+export * from "./guard-decorators.js";
+// Registry and executor
+export * from "./guard-registry.js";
+export * from "./guard-executor.js";
+// Services
+export * from "./services/guard-cache.interface.js";
+export * from "./services/guard-cache.js";
+export * from "./services/security-context.interface.js";
+export * from "./services/security-context.js";
+export * from "./services/permission-service.interface.js";
+export * from "./services/permission-service.js";
+export * from "./services/permission-hierarchy.interface.js";
+export * from "./services/permission-hierarchy.js";
+// Built-in guards
+export * from "./guards/index.js";
+// Convenience decorators
+export * from "./decorators/convenience.js";
+// Configuration
+export * from "./authorization-config.interface.js";
+export * from "./setup.js";

package/lib/esm/authorization/services/guard-cache.interface.js

@@ -0,0 +1 @@
+export {};

package/lib/esm/authorization/services/guard-cache.js

@@ -0,0 +1,51 @@
+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;
+};
+import { injectable } from "../../di/inversify.js";
+/**
+ * Implementation of guard result caching
+ * Caches results per scope (request, tenant, etc.)
+ * Note: This is bound manually in setupAuthorization() to allow user overrides
+ */
+let GuardCache = class GuardCache {
+    // Scope -> Cache Key -> Result
+    cache = new Map();
+    /**
+     * Get cached guard result
+     */
+    get(scope, key) {
+        const scopeCache = this.cache.get(scope);
+        if (!scopeCache) {
+            return null;
+        }
+        return scopeCache.get(key) || null;
+    }
+    /**
+     * Set cached guard result
+     */
+    set(scope, key, result) {
+        if (!this.cache.has(scope)) {
+            this.cache.set(scope, new Map());
+        }
+        this.cache.get(scope).set(key, result);
+    }
+    /**
+     * Clear all cached results for a scope
+     */
+    clearScope(scope) {
+        this.cache.delete(scope);
+    }
+    /**
+     * Clear all cached results
+     */
+    clear() {
+        this.cache.clear();
+    }
+};
+GuardCache = __decorate([
+    injectable()
+], GuardCache);
+export { GuardCache };

package/lib/esm/authorization/services/permission-hierarchy.interface.js

@@ -0,0 +1 @@
+export {};

package/lib/esm/authorization/services/permission-hierarchy.js

@@ -0,0 +1,49 @@
+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;
+};
+import { injectable } from "../../di/inversify.js";
+/**
+ * Permission hierarchy service for role/permission inheritance
+ * Handles hierarchical permissions (e.g., admin inherits user permissions)
+ * Note: This is bound manually in setupAuthorization() to allow user overrides
+ */
+let PermissionHierarchy = class PermissionHierarchy {
+    hierarchy = {
+        "super-admin": ["admin", "moderator", "user"],
+        admin: ["moderator", "user"],
+        moderator: ["user"],
+    };
+    /**
+     * Resolve all roles including inherited ones
+     */
+    async resolveRoles(roles) {
+        const allRoles = new Set();
+        for (const role of roles) {
+            allRoles.add(role);
+            const inherited = this.hierarchy[role] || [];
+            inherited.forEach((r) => allRoles.add(r));
+        }
+        return Array.from(allRoles);
+    }
+    /**
+     * Check if role inherits from another role
+     */
+    inheritsFrom(role, parentRole) {
+        const inherited = this.hierarchy[role] || [];
+        return (inherited.includes(parentRole) ||
+            inherited.some((r) => this.inheritsFrom(r, parentRole)));
+    }
+    /**
+     * Configure hierarchy
+     */
+    configure(hierarchy) {
+        this.hierarchy = { ...this.hierarchy, ...hierarchy };
+    }
+};
+PermissionHierarchy = __decorate([
+    injectable()
+], PermissionHierarchy);
+export { PermissionHierarchy };

package/lib/esm/authorization/services/permission-service.interface.js

@@ -0,0 +1 @@
+export {};

package/lib/esm/authorization/services/permission-service.js

@@ -0,0 +1,56 @@
+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); }
+};
+import { injectable } from "../../di/inversify.js";
+import { inject } from "../../di/annotation/inject.js";
+import { Logger } from "../../provider/logger/logger.provider.js";
+/**
+ * Tenant-scoped permission service
+ * Each tenant gets isolated permission cache
+ * Note: This is bound manually in setupAuthorization() with tenant scope to allow user overrides
+ */
+let PermissionService = class PermissionService {
+    logger;
+    cache = new Map(); // User ID -> Permissions
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Get all permissions for a user
+     * Results are cached per tenant scope
+     */
+    async getPermissions(userId, tenantId) {
+        const cacheKey = `${tenantId || "default"}:${userId}`;
+        if (this.cache.has(cacheKey)) {
+            return this.cache.get(cacheKey);
+        }
+        // In a real implementation, load from database/repository
+        // For now, return empty array (to be implemented by user)
+        this.logger?.warn(`PermissionService.getPermissions() not implemented. Override with your own implementation.`, "permission-service");
+        const permissions = [];
+        this.cache.set(cacheKey, permissions);
+        return permissions;
+    }
+    /**
+     * Check if user has specific permission
+     */
+    async hasPermission(userId, permission, tenantId) {
+        const permissions = await this.getPermissions(userId, tenantId);
+        return permissions.includes(permission);
+    }
+};
+PermissionService = __decorate([
+    injectable(),
+    __param(0, inject(Logger)),
+    __metadata("design:paramtypes", [Logger])
+], PermissionService);
+export { PermissionService };

package/lib/esm/authorization/services/security-context.interface.js

@@ -0,0 +1 @@
+export {};

package/lib/esm/authorization/services/security-context.js

@@ -0,0 +1,74 @@
+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); }
+};
+import { injectable } from "../../di/inversify.js";
+import { inject } from "../../di/annotation/inject.js";
+import { Logger } from "../../provider/logger/logger.provider.js";
+/**
+ * Request-scoped security context for caching permissions
+ * Provides permission checking with request-scoped caching
+ * Note: This is bound manually in setupAuthorization() to allow user overrides
+ */
+let SecurityContext = class SecurityContext {
+    permissionService;
+    logger;
+    permissions = new Set();
+    roles = new Set();
+    loaded = false;
+    constructor(permissionService, logger) {
+        this.permissionService = permissionService;
+        this.logger = logger;
+    }
+    /**
+     * Preload all permissions for user (called once per request)
+     */
+    async preload(userId) {
+        if (this.loaded) {
+            return;
+        }
+        try {
+            if (this.permissionService) {
+                const permissions = await this.permissionService.getPermissions(userId);
+                permissions.forEach((p) => this.permissions.add(p));
+            }
+            this.loaded = true;
+        }
+        catch (error) {
+            this.logger?.error(`Failed to preload permissions for user ${userId}: ${error}`, "security-context");
+        }
+    }
+    /**
+     * Check if user has specific permission
+     */
+    async hasPermission(permission) {
+        return this.permissions.has(permission);
+    }
+    /**
+     * Add permission to context
+     */
+    addPermission(permission) {
+        this.permissions.add(permission);
+    }
+    /**
+     * Get all permissions
+     */
+    async getPermissions() {
+        return Array.from(this.permissions);
+    }
+};
+SecurityContext = __decorate([
+    injectable(),
+    __param(0, inject("IPermissionService")),
+    __param(1, inject(Logger)),
+    __metadata("design:paramtypes", [Object, Logger])
+], SecurityContext);
+export { SecurityContext };