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

package/lib/cjs/types/authorization/guard-decorators.d.ts

@@ -0,0 +1,128 @@
+import "reflect-metadata";
+import type { IGuard, GuardClass } from "./guard.interface.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
+ */
+export declare function Guard(options?: {
+    priority?: number;
+    cacheable?: boolean;
+}): ClassDecorator;
+/**
+ * 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
+ */
+export declare function UseGuards(...guards: Array<IGuard | GuardClass>): ClassDecorator & MethodDecorator;

package/lib/cjs/types/authorization/guard-executor.d.ts

@@ -0,0 +1,26 @@
+import { Logger } from "../provider/logger/logger.provider.js";
+import type { IGuard, GuardClass, GuardContext } from "./guard.interface.js";
+import { GuardResult } from "./guard.interface.js";
+import { GuardRegistry } from "./guard-registry.js";
+import type { IGuardCache } from "./services/guard-cache.interface.js";
+/**
+ * Executor for running guards in priority order with caching support
+ */
+export declare class GuardExecutor {
+    private registry;
+    private cache;
+    private logger;
+    constructor(registry: GuardRegistry, cache: IGuardCache, 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
+     */
+    execute(guards: Array<GuardClass | IGuard>, context: GuardContext): Promise<GuardResult>;
+    /**
+     * Generate default cache key for guard
+     * @private
+     */
+    private defaultCacheKey;
+}

package/lib/cjs/types/authorization/guard-registry.d.ts

@@ -0,0 +1,35 @@
+import "reflect-metadata";
+import { interfaces } from "../di/inversify.js";
+import { Logger } from "../provider/logger/logger.provider.js";
+import type { IGuard, GuardClass } from "./guard.interface.js";
+/**
+ * Registry for managing guards with automatic discovery
+ * Similar to ExceptionFilterRegistry
+ */
+export declare class GuardRegistry {
+    private container;
+    private logger;
+    private guards;
+    private initialized;
+    constructor(container: interfaces.Container, logger: Logger);
+    /**
+     * Initialize the registry by auto-discovering all guards decorated with @Guard
+     * This should be called after the container is fully configured
+     */
+    initialize(): void;
+    /**
+     * Get guard instance (from registry or create new)
+     * @param guard - Guard class or instance
+     * @returns Guard instance
+     */
+    get(guard: GuardClass | IGuard): IGuard;
+    /**
+     * Check if registry is initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Inject common dependencies into guard instance
+     * @private
+     */
+    private injectDependencies;
+}

package/lib/cjs/types/authorization/guard.interface.d.ts

@@ -0,0 +1,335 @@
+import { Request, Response } from "express";
+import type { Container, interfaces } from "../di/inversify.js";
+import { AppError } from "../error/app-error.js";
+/**
+ * Principal interface for authentication
+ * This is adapter-agnostic and matches the adapter's Principal interface
+ */
+export interface Principal<T = unknown> {
+    details: T;
+    isAuthenticated(): Promise<boolean>;
+    isInRole(role: string): Promise<boolean>;
+    isResourceOwner(resourceId: unknown): Promise<boolean>;
+}
+/**
+ * Scope information extracted from request
+ */
+export interface GuardScope {
+    /**
+     * Tenant ID if multi-tenant application
+     */
+    tenant?: string;
+    /**
+     * Unique request ID
+     */
+    request: string;
+    /**
+     * Session ID if available
+     */
+    session?: string;
+    /**
+     * Transaction ID if available
+     */
+    transaction?: string;
+    /**
+     * Workflow ID if available
+     */
+    workflow?: string;
+}
+/**
+ * Route metadata for guard context
+ */
+export interface RouteMetadata {
+    /**
+     * Controller name
+     */
+    controller: string;
+    /**
+     * Method name
+     */
+    method: string;
+    /**
+     * Route path
+     */
+    path: string;
+    /**
+     * Route parameters
+     */
+    params: Record<string, unknown>;
+    /**
+     * Query parameters
+     */
+    query: Record<string, unknown>;
+}
+/**
+ * Guard context providing comprehensive information for authorization decisions
+ */
+export interface GuardContext {
+    /**
+     * Express request object
+     */
+    request: Request;
+    /**
+     * Express response object
+     */
+    response: Response;
+    /**
+     * Principal (user) from AuthProvider
+     */
+    principal: Principal;
+    /**
+     * DI container (request-scoped child container)
+     */
+    container: Container;
+    /**
+     * Scope information (extracted from request)
+     */
+    scope: GuardScope;
+    /**
+     * Route metadata
+     */
+    route: RouteMetadata;
+    /**
+     * Get scoped service from container
+     * @param identifier - Service identifier
+     * @param scopeName - Optional scope name (e.g., "tenant")
+     */
+    getScoped<T>(identifier: interfaces.ServiceIdentifier<T>, scopeName?: string): T;
+    /**
+     * Get tenant ID from scope
+     */
+    getTenantId(): string | undefined;
+    /**
+     * Get request ID from scope
+     */
+    getRequestId(): string;
+}
+/**
+ * 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
+ */
+export declare class GuardResult {
+    readonly allowed: boolean;
+    readonly error?: AppError;
+    private constructor();
+    /**
+     * Create an allow result.
+     *
+     * @layer public
+     * @audience application-developers
+     *
+     * @returns GuardResult with allowed = true
+     *
+     * @example
+     * ```typescript
+     * return GuardResult.allow();
+     * ```
+     *
+     * @public API
+     */
+    static allow(): GuardResult;
+    /**
+     * 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?: AppError): GuardResult;
+}
+/**
+ * Guard interface for authorization checks.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept guard-interface
+ * @difficulty intermediate
+ *
+ * @summary Quick Start
+ * Implement this interface to create custom guards for authorization.
+ *
+ * @example
+ * ```typescript
+ * @Guard({ priority: 1 })
+ * export class AuthenticatedGuard implements IGuard {
+ *   async canActivate(context: GuardContext): Promise<GuardResult> {
+ *     const isAuthenticated = await context.principal.isAuthenticated();
+ *     return isAuthenticated ? GuardResult.allow() : GuardResult.deny();
+ *   }
+ * }
+ * ```
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Architecture**
+ *
+ * Guards are executed by GuardExecutor in priority order:
+ * 1. Resolved from registry or container
+ * 2. Sorted by priority (lower = earlier)
+ * 3. Executed sequentially
+ * 4. Early exit on deny
+ * 5. Results cached if cacheable
+ *
+ * **Return Types**
+ * - `GuardResult`: Explicit allow/deny with optional error
+ * - `boolean`: `true` = allow, `false` = deny with default error
+ *
+ * @see {@link GuardContext} for available context information
+ * @see {@link GuardResult} for result types
+ * @see {@link GuardExecutor} for execution logic
+ *
+ * @layer advanced
+ * @audience power-users
+ *
+ * **Advanced Patterns**
+ *
+ * Caching guard results:
+ * ```typescript
+ * @Guard({ cacheable: true })
+ * export class CachedGuard implements IGuard {
+ *   cacheKey = (context) => `guard:${context.principal.details.id}`;
+ *   // ...
+ * }
+ * ```
+ *
+ * Priority ordering:
+ * ```typescript
+ * @Guard({ priority: 1 })  // Runs first (authentication)
+ * export class AuthGuard implements IGuard { }
+ *
+ * @Guard({ priority: 50 })  // Runs after auth (authorization)
+ * export class RoleGuard implements IGuard { }
+ * ```
+ *
+ * @public API
+ */
+export interface IGuard {
+    /**
+     * Determines if the request should be allowed to proceed.
+     *
+     * @layer public
+     * @audience application-developers
+     *
+     * @param context - Full guard context with request, principal, container, and scope info
+     * @returns GuardResult or boolean (true = allow, false = deny with default error)
+     *
+     * @example
+     * ```typescript
+     * async canActivate(context: GuardContext): Promise<GuardResult> {
+     *   const isAuthenticated = await context.principal.isAuthenticated();
+     *   if (!isAuthenticated) {
+     *     return GuardResult.deny(AppError.unauthorized("Please login"));
+     *   }
+     *   return GuardResult.allow();
+     * }
+     * ```
+     *
+     * @public API
+     */
+    canActivate(context: GuardContext): Promise<GuardResult | boolean>;
+    /**
+     * Optional: Execution priority (lower = earlier). Default: 100
+     *
+     * @default 100
+     *
+     * Useful for guards that must run before others (e.g., authentication before authorization).
+     *
+     * **Common Priorities:**
+     * - 1-10: Authentication guards
+     * - 50-100: Authorization guards (roles, permissions)
+     * - 100+: Resource guards (ownership, attributes)
+     *
+     * @example
+     * ```typescript
+     * @Guard({ priority: 1 })  // Runs first
+     * export class AuthenticatedGuard implements IGuard { }
+     * ```
+     */
+    priority?: number;
+    /**
+     * Optional: Whether guard result can be cached within request scope.
+     *
+     * @default false
+     *
+     * When `true`, guard result is cached for the request scope.
+     * Subsequent calls with same cache key return cached result.
+     *
+     * @example
+     * ```typescript
+     * @Guard({ cacheable: true })
+     * export class CachedGuard implements IGuard {
+     *   cacheKey = (context) => `user:${context.principal.details.id}`;
+     * }
+     * ```
+     */
+    cacheable?: boolean;
+    /**
+     * Optional: Custom cache key generator.
+     *
+     * @default `${guard.name}:${method}:${path}`
+     *
+     * Generates cache key for this guard. Only used if `cacheable: true`.
+     *
+     * @example
+     * ```typescript
+     * cacheKey = (context) => {
+     *   return `guard:${context.principal.details.id}:${context.route.path}`;
+     * }
+     * ```
+     */
+    cacheKey?: (context: GuardContext) => string;
+}
+/**
+ * Type for guard class constructor
+ */
+export type GuardClass = new (...args: Array<any>) => IGuard;
+/**
+ * Metadata for guard registration
+ */
+export interface GuardMetadata {
+    /**
+     * Execution priority
+     */
+    priority: number;
+    /**
+     * Whether result is cacheable
+     */
+    cacheable: boolean;
+    /**
+     * The guard class
+     */
+    guard: NewableFunction;
+}

package/lib/cjs/types/authorization/guards/attribute-based.guard.d.ts

@@ -0,0 +1,60 @@
+import type { IGuard, GuardContext } from "../guard.interface.js";
+import { GuardResult } from "../guard.interface.js";
+/**
+ * Attribute set for ABAC (Attribute-Based Access Control)
+ */
+export interface AttributeSet {
+    user: {
+        id: string;
+        roles: Array<string>;
+        department?: string;
+        [key: string]: unknown;
+    };
+    resource: {
+        id: string;
+        type: string;
+        owner?: string;
+        [key: string]: unknown;
+    };
+    environment: {
+        time: Date;
+        ip: string;
+        tenant?: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Guard that uses ABAC (Attribute-Based Access Control)
+ * Evaluates policy based on user, resource, and environment attributes
+ *
+ * @example
+ * ```typescript
+ * @controller("/api/resources")
+ * export class ResourceController {
+ *   @Get("/:id")
+ *   @UseGuards(
+ *     RequireAuth(),
+ *     RequirePolicy((attrs) => {
+ *       return attrs.user.roles.includes("admin") ||
+ *              attrs.resource.owner === attrs.user.id;
+ *     })
+ *   )
+ *   getResource(@param("id") id: string) {}
+ * }
+ * ```
+ */
+/**
+ * Note: Guards are instantiated dynamically by GuardRegistry, not via DI
+ */
+export declare class AttributeBasedGuard implements IGuard {
+    private policy;
+    constructor(policy: (attributes: AttributeSet) => boolean | Promise<boolean>);
+    canActivate(context: GuardContext): Promise<GuardResult>;
+    private getUserRoles;
+    private getResourceOwner;
+}
+/**
+ * Factory function for convenience
+ * @param policy - Policy function that evaluates attributes
+ */
+export declare const RequirePolicy: (policy: (attributes: AttributeSet) => boolean | Promise<boolean>) => AttributeBasedGuard;

package/lib/cjs/types/authorization/guards/authenticated.guard.d.ts

@@ -0,0 +1,26 @@
+import type { IGuard, GuardContext } from "../guard.interface.js";
+import { GuardResult } from "../guard.interface.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
+ */
+export declare class AuthenticatedGuard implements IGuard {
+    canActivate(context: GuardContext): Promise<GuardResult>;
+}
+/**
+ * Factory function for convenience
+ */
+export declare const RequireAuth: () => AuthenticatedGuard;

package/lib/cjs/types/authorization/guards/composition.guard.d.ts

@@ -0,0 +1,42 @@
+import type { IGuard, GuardClass } 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 declare function combineGuards(...guards: Array<IGuard | GuardClass>): IGuard;
+/**
+ * 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 declare function sequenceGuards(...guards: Array<IGuard | GuardClass>): IGuard;

package/lib/cjs/types/authorization/guards/conditional.guard.d.ts

@@ -0,0 +1,21 @@
+import type { IGuard, GuardContext, GuardClass } 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 declare function whenGuard(condition: (context: GuardContext) => boolean | Promise<boolean>, guard: IGuard | GuardClass): IGuard;

package/lib/cjs/types/authorization/guards/index.d.ts

@@ -0,0 +1,7 @@
+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";