permissions-contractx 1.0.2 → 1.2.0

package/dist/decorators/permission-writes.decorator.d.ts

@@ -0,0 +1,14 @@
+/**
+ * [ADR-004 Fase 2 / Bloque 1] Override del eje lectura/escritura (D3) que usa el
+ * AuthorizationGuard para clasificar la petición, cuando el método HTTP no basta:
+ *  - @PermissionWrites(true)  → tratar como ESCRITURA (p.ej. un GET que muta).
+ *  - @PermissionWrites(false) → tratar como LECTURA (p.ej. búsqueda por POST).
+ * Sin el decorador, la clasificación cae por método HTTP (GET/HEAD/OPTIONS = lectura).
+ *
+ * Nota: `RequirePermissions` NO se define aquí — ya existe en
+ * permissions.decorator.ts (mismo metadata key 'permissions' que lee el guard).
+ * Este archivo solo añade lo que faltaba en el paquete.
+ */
+export declare const PERMISSION_WRITES_KEY = "permission_writes";
+export declare const PermissionWrites: (writes: boolean) => import("@nestjs/common").CustomDecorator<string>;
+//# sourceMappingURL=permission-writes.decorator.d.ts.map

package/dist/decorators/permission-writes.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-writes.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/permission-writes.decorator.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,sBAAsB,CAAC;AAEzD,eAAO,MAAM,gBAAgB,GAAI,QAAQ,OAAO,qDAA+C,CAAC"}

package/dist/decorators/permission-writes.decorator.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PermissionWrites = exports.PERMISSION_WRITES_KEY = void 0;
+const common_1 = require("@nestjs/common");
+/**
+ * [ADR-004 Fase 2 / Bloque 1] Override del eje lectura/escritura (D3) que usa el
+ * AuthorizationGuard para clasificar la petición, cuando el método HTTP no basta:
+ *  - @PermissionWrites(true)  → tratar como ESCRITURA (p.ej. un GET que muta).
+ *  - @PermissionWrites(false) → tratar como LECTURA (p.ej. búsqueda por POST).
+ * Sin el decorador, la clasificación cae por método HTTP (GET/HEAD/OPTIONS = lectura).
+ *
+ * Nota: `RequirePermissions` NO se define aquí — ya existe en
+ * permissions.decorator.ts (mismo metadata key 'permissions' que lee el guard).
+ * Este archivo solo añade lo que faltaba en el paquete.
+ */
+exports.PERMISSION_WRITES_KEY = 'permission_writes';
+const PermissionWrites = (writes) => (0, common_1.SetMetadata)(exports.PERMISSION_WRITES_KEY, writes);
+exports.PermissionWrites = PermissionWrites;

package/dist/decorators/permissions.decorator.d.ts

@@ -8,90 +8,32 @@ export declare const PERMISSIONS_KEY = "permissions";
  * User must have all specified permissions (AND logic).
  *
  * @param permissions - Array of permission codes required to access the route
- *
- * @example
- * ```typescript
- * @RequirePermissions('users.create', 'users.update')
- * @Post('users')
- * createUser() {
- *   // User must have both users.create AND users.update permissions
- * }
- * ```
  */
 export declare const RequirePermissions: (...permissions: string[]) => import("@nestjs/common").CustomDecorator<string>;
 /**
  * Decorator requiring any of the specified permissions (OR logic)
  *
  * @param permissions - Array of permission codes, user needs at least one
- *
- * @example
- * ```typescript
- * @RequireAnyPermission('users.read', 'users.show')
- * @Get('users/:id')
- * getUser() {
- *   // User needs either users.read OR users.show permission
- * }
- * ```
  */
 export declare const RequireAnyPermission: (...permissions: string[]) => import("@nestjs/common").CustomDecorator<string>;
 /**
  * Decorator for read access (show, read, filter)
- *
  * @param module - Module name (e.g., 'users', 'contracts')
- *
- * @example
- * ```typescript
- * @ReadAccess('users')
- * @Get('users')
- * getUsers() {
- *   // User needs users.read, users.show, or users.filter permission
- * }
- * ```
  */
 export declare const ReadAccess: (module: string) => import("@nestjs/common").CustomDecorator<string>;
 /**
  * Decorator for write access (create, update)
- *
  * @param module - Module name (e.g., 'users', 'contracts')
- *
- * @example
- * ```typescript
- * @WriteAccess('users')
- * @Put('users/:id')
- * updateUser() {
- *   // User needs users.create or users.update permission
- * }
- * ```
  */
 export declare const WriteAccess: (module: string) => import("@nestjs/common").CustomDecorator<string>;
 /**
  * Decorator for delete access
- *
  * @param module - Module name (e.g., 'users', 'contracts')
- *
- * @example
- * ```typescript
- * @DeleteAccess('users')
- * @Delete('users/:id')
- * deleteUser() {
- *   // User needs users.delete permission
- * }
- * ```
  */
 export declare const DeleteAccess: (module: string) => import("@nestjs/common").CustomDecorator<string>;
 /**
  * Decorator for full CRUD access to a module
- *
  * @param module - Module name (e.g., 'users', 'contracts')
- *
- * @example
- * ```typescript
- * @FullAccess('users')
- * @Controller('users')
- * export class UsersController {
- *   // All methods require full user module access
- * }
- * ```
  */
 export declare const FullAccess: (module: string) => import("@nestjs/common").CustomDecorator<string>;
 //# sourceMappingURL=permissions.decorator.d.ts.map

package/dist/decorators/permissions.decorator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"permissions.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/permissions.decorator.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,eAAO,MAAM,eAAe,gBAAgB,CAAC;AAE7C;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,kBAAkB,GAAI,GAAG,aAAa,MAAM,EAAE,qDAChB,CAAC;AAE5C;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB,GAAI,GAAG,aAAa,MAAM,EAAE,qDACjB,CAAC;AAE7C;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,MAAM,qDAKtC,CAAC;AAEJ;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,MAAM,qDAIvC,CAAC;AAEJ;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,MAAM,qDACH,CAAC;AAEzC;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,MAAM,qDAQtC,CAAC"}
+{"version":3,"file":"permissions.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/permissions.decorator.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,eAAO,MAAM,eAAe,gBAAgB,CAAC;AAE7C;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,GAAI,GAAG,aAAa,MAAM,EAAE,qDAA8C,CAAC;AAE1G;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAAI,GAAG,aAAa,MAAM,EAAE,qDAA+C,CAAC;AAE7G;;;GAGG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,MAAM,qDACqC,CAAC;AAE/E;;;GAGG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,MAAM,qDAAiE,CAAC;AAE5G;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,MAAM,qDAA2C,CAAC;AAEvF;;;GAGG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,MAAM,qDAQtC,CAAC"}

package/dist/decorators/permissions.decorator.js

@@ -12,15 +12,6 @@ exports.PERMISSIONS_KEY = 'permissions';
  * User must have all specified permissions (AND logic).
  *
  * @param permissions - Array of permission codes required to access the route
- *
- * @example
- * ```typescript
- * @RequirePermissions('users.create', 'users.update')
- * @Post('users')
- * createUser() {
- *   // User must have both users.create AND users.update permissions
- * }
- * ```
  */
 const RequirePermissions = (...permissions) => (0, common_1.SetMetadata)(exports.PERMISSIONS_KEY, permissions);
 exports.RequirePermissions = RequirePermissions;
@@ -28,79 +19,30 @@ exports.RequirePermissions = RequirePermissions;
  * Decorator requiring any of the specified permissions (OR logic)
  *
  * @param permissions - Array of permission codes, user needs at least one
- *
- * @example
- * ```typescript
- * @RequireAnyPermission('users.read', 'users.show')
- * @Get('users/:id')
- * getUser() {
- *   // User needs either users.read OR users.show permission
- * }
- * ```
  */
 const RequireAnyPermission = (...permissions) => (0, common_1.SetMetadata)('anyPermissions', permissions);
 exports.RequireAnyPermission = RequireAnyPermission;
 /**
  * Decorator for read access (show, read, filter)
- *
  * @param module - Module name (e.g., 'users', 'contracts')
- *
- * @example
- * ```typescript
- * @ReadAccess('users')
- * @Get('users')
- * getUsers() {
- *   // User needs users.read, users.show, or users.filter permission
- * }
- * ```
  */
 const ReadAccess = (module) => (0, exports.RequireAnyPermission)(`${module}.read`, `${module}.show`, `${module}.filter`);
 exports.ReadAccess = ReadAccess;
 /**
  * Decorator for write access (create, update)
- *
  * @param module - Module name (e.g., 'users', 'contracts')
- *
- * @example
- * ```typescript
- * @WriteAccess('users')
- * @Put('users/:id')
- * updateUser() {
- *   // User needs users.create or users.update permission
- * }
- * ```
  */
 const WriteAccess = (module) => (0, exports.RequireAnyPermission)(`${module}.create`, `${module}.update`);
 exports.WriteAccess = WriteAccess;
 /**
  * Decorator for delete access
- *
  * @param module - Module name (e.g., 'users', 'contracts')
- *
- * @example
- * ```typescript
- * @DeleteAccess('users')
- * @Delete('users/:id')
- * deleteUser() {
- *   // User needs users.delete permission
- * }
- * ```
  */
 const DeleteAccess = (module) => (0, exports.RequirePermissions)(`${module}.delete`);
 exports.DeleteAccess = DeleteAccess;
 /**
  * Decorator for full CRUD access to a module
- *
  * @param module - Module name (e.g., 'users', 'contracts')
- *
- * @example
- * ```typescript
- * @FullAccess('users')
- * @Controller('users')
- * export class UsersController {
- *   // All methods require full user module access
- * }
- * ```
  */
 const FullAccess = (module) => (0, exports.RequireAnyPermission)(`${module}.create`, `${module}.read`, `${module}.update`, `${module}.delete`, `${module}.show`, `${module}.filter`);
 exports.FullAccess = FullAccess;

package/dist/decorators/roles.decorator.d.ts

@@ -8,68 +8,15 @@ export declare const ROLES_KEY = "roles";
  * User must have at least one of the specified roles (OR logic).
  *
  * @param roles - Array of role names required to access the route
- *
- * @example
- * ```typescript
- * @Roles('superadmin', 'client_contract_admin')
- * @Get('admin-data')
- * getAdminData() {
- *   // Only users with superadmin OR client_contract_admin role
- * }
- * ```
  */
 export declare const Roles: (...roles: string[]) => import("@nestjs/common").CustomDecorator<string>;
-/**
- * Decorator for ContractX specific admin roles
- *
- * @example
- * ```typescript
- * @AdminOnly()
- * @Delete(':id')
- * deleteResource() {
- *   // Only admin roles can access
- * }
- * ```
- */
+/** Decorator for ContractX specific admin roles */
 export declare const AdminOnly: () => import("@nestjs/common").CustomDecorator<string>;
-/**
- * Decorator for client-side roles only
- *
- * @example
- * ```typescript
- * @ClientOnly()
- * @Get('client-data')
- * getClientData() {
- *   // Only client-side roles can access
- * }
- * ```
- */
+/** Decorator for client-side roles only */
 export declare const ClientOnly: () => import("@nestjs/common").CustomDecorator<string>;
-/**
- * Decorator for provider-side roles only
- *
- * @example
- * ```typescript
- * @ProviderOnly()
- * @Get('provider-data')
- * getProviderData() {
- *   // Only provider-side roles can access
- * }
- * ```
- */
+/** Decorator for provider-side roles only */
 export declare const ProviderOnly: () => import("@nestjs/common").CustomDecorator<string>;
-/**
- * Decorator for superadmin access only
- *
- * @example
- * ```typescript
- * @SuperAdminOnly()
- * @Post('system/configure')
- * configureSystem() {
- *   // Only superadmin can access
- * }
- * ```
- */
+/** Decorator for superadmin access only */
 export declare const SuperAdminOnly: () => import("@nestjs/common").CustomDecorator<string>;
 /**
  * Alias for Roles decorator for backward compatibility

package/dist/decorators/roles.decorator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"roles.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/roles.decorator.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,eAAO,MAAM,SAAS,UAAU,CAAC;AAEjC;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,KAAK,GAAI,GAAG,OAAO,MAAM,EAAE,qDAAkC,CAAC;AAE3E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,SAAS,wDAIrB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,UAAU,wDAOtB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,wDAOxB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,wDAA4B,CAAC;AAExD;;;GAGG;AACH,eAAO,MAAM,YAAY,aAhFO,MAAM,EAAE,qDAgFP,CAAC"}
+{"version":3,"file":"roles.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/roles.decorator.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,eAAO,MAAM,SAAS,UAAU,CAAC;AAEjC;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,GAAI,GAAG,OAAO,MAAM,EAAE,qDAAkC,CAAC;AAK3E,mDAAmD;AACnD,eAAO,MAAM,SAAS,wDAAgF,CAAC;AAEvG,2CAA2C;AAC3C,eAAO,MAAM,UAAU,wDAQpB,CAAC;AAEJ,6CAA6C;AAC7C,eAAO,MAAM,YAAY,wDAQtB,CAAC;AAEJ,2CAA2C;AAC3C,eAAO,MAAM,cAAc,wDAA4B,CAAC;AAExD;;;GAGG;AACH,eAAO,MAAM,YAAY,aArCO,MAAM,EAAE,qDAqCP,CAAC"}

package/dist/decorators/roles.decorator.js

@@ -12,72 +12,21 @@ exports.ROLES_KEY = 'roles';
  * User must have at least one of the specified roles (OR logic).
  *
  * @param roles - Array of role names required to access the route
- *
- * @example
- * ```typescript
- * @Roles('superadmin', 'client_contract_admin')
- * @Get('admin-data')
- * getAdminData() {
- *   // Only users with superadmin OR client_contract_admin role
- * }
- * ```
  */
 const Roles = (...roles) => (0, common_1.SetMetadata)(exports.ROLES_KEY, roles);
 exports.Roles = Roles;
-/**
- * Decorator for ContractX specific admin roles
- *
- * @example
- * ```typescript
- * @AdminOnly()
- * @Delete(':id')
- * deleteResource() {
- *   // Only admin roles can access
- * }
- * ```
- */
+// NOTA[reconstrucción]: los helpers de abajo hardcodean nombres de rol del vocabulario VIEJO
+// (superadmin, client_performance_manager, ...) → "se reemplaza" al portar al modelo nuevo.
+/** Decorator for ContractX specific admin roles */
 const AdminOnly = () => (0, exports.Roles)('superadmin', 'client_contract_admin', 'provider_contract_admin');
 exports.AdminOnly = AdminOnly;
-/**
- * Decorator for client-side roles only
- *
- * @example
- * ```typescript
- * @ClientOnly()
- * @Get('client-data')
- * getClientData() {
- *   // Only client-side roles can access
- * }
- * ```
- */
+/** Decorator for client-side roles only */
 const ClientOnly = () => (0, exports.Roles)('client_contract_admin', 'client_performance_manager', 'client_finance_manager', 'client_reports_manager', 'client_relationship_manager', 'client_risk_manager');
 exports.ClientOnly = ClientOnly;
-/**
- * Decorator for provider-side roles only
- *
- * @example
- * ```typescript
- * @ProviderOnly()
- * @Get('provider-data')
- * getProviderData() {
- *   // Only provider-side roles can access
- * }
- * ```
- */
+/** Decorator for provider-side roles only */
 const ProviderOnly = () => (0, exports.Roles)('provider_contract_admin', 'provider_performance_manager', 'provider_finance_manager', 'provider_reports_manager', 'provider_relationship_manager', 'provider_risk_manager');
 exports.ProviderOnly = ProviderOnly;
-/**
- * Decorator for superadmin access only
- *
- * @example
- * ```typescript
- * @SuperAdminOnly()
- * @Post('system/configure')
- * configureSystem() {
- *   // Only superadmin can access
- * }
- * ```
- */
+/** Decorator for superadmin access only */
 const SuperAdminOnly = () => (0, exports.Roles)('superadmin');
 exports.SuperAdminOnly = SuperAdminOnly;
 /**

package/dist/guards/authorization.guard.d.ts

@@ -0,0 +1,37 @@
+import { CanActivate, ExecutionContext } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+/**
+ * [ADR-004] AuthorizationGuard — guard de 4 estados portado desde Auth.
+ *
+ * Lee dos conjuntos ya resueltos del JWT (la resolución deny-wins ocurre en Auth,
+ * vía resolvePermissionEntitlements, NO aquí):
+ *   - user.permissions      = acceso pleno (write/full)
+ *   - user.permissionsView  = modo-ver (👁, solo lectura)
+ *
+ * Eje lectura/escritura (D3): por método HTTP (GET/HEAD/OPTIONS = lectura), salvo
+ * override @PermissionWrites. En lectura vale acceso pleno O modo-ver; en escritura
+ * SOLO acceso pleno (modo-ver bloquea).
+ *
+ * Doble gateo rol+permiso (D4) vía env AUTHZ_ENFORCEMENT:
+ *   - legacy (default): rol O permiso (comportamiento previo, sin cambio).
+ *   - observe: el rol decide; se loguea la discrepancia con el permiso (recolección).
+ *   - strict:  el permiso decide.
+ */
+export declare class AuthorizationGuard implements CanActivate {
+    private reflector;
+    private readonly logger;
+    constructor(reflector: Reflector);
+    canActivate(context: ExecutionContext): boolean;
+    /**
+     * [D4] Modo de enforcement del doble gateo, vía env `AUTHZ_ENFORCEMENT`.
+     * Default 'legacy' ⇒ comportamiento previo (rol O permiso) sin cambio hasta optar in.
+     */
+    private resolveEnforcementMode;
+    /**
+     * Clasifica la petición como escritura o lectura para el eje modo-ver (D3).
+     * Override explícito @PermissionWrites(boolean) gana; si no, cae por método HTTP
+     * (GET/HEAD/OPTIONS = lectura; el resto = escritura).
+     */
+    private isWriteRequest;
+}
+//# sourceMappingURL=authorization.guard.d.ts.map

package/dist/guards/authorization.guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorization.guard.d.ts","sourceRoot":"","sources":["../../src/guards/authorization.guard.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,WAAW,EACX,gBAAgB,EAGjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAWzC;;;;;;;;;;;;;;;;GAgBG;AACH,qBACa,kBAAmB,YAAW,WAAW;IAGxC,OAAO,CAAC,SAAS;IAF7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuC;gBAE1C,SAAS,EAAE,SAAS;IAExC,WAAW,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO;IA+G/C;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAK9B;;;;OAIG;IACH,OAAO,CAAC,cAAc;CAUvB"}

package/dist/guards/authorization.guard.js

@@ -0,0 +1,150 @@
+"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 AuthorizationGuard_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthorizationGuard = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const permission_writes_decorator_1 = require("../decorators/permission-writes.decorator");
+const READ_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+/**
+ * [ADR-004] AuthorizationGuard — guard de 4 estados portado desde Auth.
+ *
+ * Lee dos conjuntos ya resueltos del JWT (la resolución deny-wins ocurre en Auth,
+ * vía resolvePermissionEntitlements, NO aquí):
+ *   - user.permissions      = acceso pleno (write/full)
+ *   - user.permissionsView  = modo-ver (👁, solo lectura)
+ *
+ * Eje lectura/escritura (D3): por método HTTP (GET/HEAD/OPTIONS = lectura), salvo
+ * override @PermissionWrites. En lectura vale acceso pleno O modo-ver; en escritura
+ * SOLO acceso pleno (modo-ver bloquea).
+ *
+ * Doble gateo rol+permiso (D4) vía env AUTHZ_ENFORCEMENT:
+ *   - legacy (default): rol O permiso (comportamiento previo, sin cambio).
+ *   - observe: el rol decide; se loguea la discrepancia con el permiso (recolección).
+ *   - strict:  el permiso decide.
+ */
+let AuthorizationGuard = AuthorizationGuard_1 = class AuthorizationGuard {
+    constructor(reflector) {
+        this.reflector = reflector;
+        this.logger = new common_1.Logger(AuthorizationGuard_1.name);
+    }
+    canActivate(context) {
+        const requiredRoles = this.reflector.getAllAndOverride('roles', [
+            context.getHandler(),
+            context.getClass(),
+        ]);
+        const requiredPermissions = this.reflector.getAllAndOverride('permissions', [
+            context.getHandler(),
+            context.getClass(),
+        ]);
+        if ((!requiredRoles || requiredRoles.length === 0) &&
+            (!requiredPermissions || requiredPermissions.length === 0)) {
+            return true;
+        }
+        const request = context.switchToHttp().getRequest();
+        const user = request.user;
+        if (!user) {
+            this.logger.warn('No user found in request context for authorization');
+            throw new common_1.ForbiddenException('Authentication required for access');
+        }
+        const userId = user.sub;
+        const userRoles = user.role || [];
+        // Dos conjuntos resueltos en la carga del JWT: permissions = acceso pleno;
+        // permissionsView = modo-ver (solo lectura). Las filas `deny` ya fueron retiradas
+        // en origen (resolvePermissionEntitlements), así que el guard no necesita conocer
+        // grant_type — la decisión es pertenencia a estos arrays.
+        const userPermissions = user.permissions || [];
+        const userPermissionsView = user.permissionsView || [];
+        let hasRole = true;
+        if (requiredRoles && requiredRoles.length > 0) {
+            hasRole = requiredRoles.some((role) => userRoles.includes(role));
+            if (!hasRole) {
+                this.logger.warn(`Role access denied: User ${userId} with roles [${userRoles.join(', ')}] attempted to access resource requiring [${requiredRoles.join(', ')}]`);
+            }
+        }
+        let hasPermissions = true;
+        if (requiredPermissions && requiredPermissions.length > 0) {
+            // Eje lectura/escritura (D3): por método HTTP, salvo override @PermissionWrites.
+            const isWrite = this.isWriteRequest(context, request.method);
+            // Lectura: vale acceso pleno O modo-ver. Escritura: SOLO acceso pleno (modo-ver bloquea).
+            const allowsCode = (permission) => isWrite
+                ? userPermissions.includes(permission)
+                : userPermissions.includes(permission) || userPermissionsView.includes(permission);
+            hasPermissions = requiredPermissions.every(allowsCode);
+            if (!hasPermissions) {
+                const missingPermissions = requiredPermissions.filter((permission) => !allowsCode(permission));
+                const viewOnlyBlocked = requiredPermissions.filter((permission) => isWrite && userPermissionsView.includes(permission) && !userPermissions.includes(permission));
+                this.logger.warn(`Permission access denied: User ${userId} (${isWrite ? 'write' : 'read'}) missing [${missingPermissions.join(', ')}]` +
+                    (viewOnlyBlocked.length ? ` — view-only on [${viewOnlyBlocked.join(', ')}] cannot write` : ''));
+            }
+        }
+        const bothPresent = requiredRoles && requiredRoles.length > 0 && requiredPermissions && requiredPermissions.length > 0;
+        let hasAccess;
+        if (bothPresent) {
+            const mode = this.resolveEnforcementMode();
+            if (mode === 'observe') {
+                if (hasRole !== hasPermissions) {
+                    this.logger.warn(`AUTHZ_DISCREPANCY user=${userId} ${request.method ?? '?'} ${request.url ?? '?'} ` +
+                        `role_decides=${hasRole} permission_would=${hasPermissions} ` +
+                        `roles=[${(requiredRoles ?? []).join(', ')}] perms=[${(requiredPermissions ?? []).join(', ')}]`);
+                }
+                hasAccess = hasRole;
+            }
+            else if (mode === 'strict') {
+                hasAccess = hasPermissions;
+            }
+            else {
+                hasAccess = hasRole || hasPermissions;
+            }
+        }
+        else {
+            // Solo uno presente → ése decide (el ausente quedó en true por defecto).
+            hasAccess = hasRole && hasPermissions;
+        }
+        if (!hasAccess) {
+            const roleMsg = requiredRoles?.length > 0 ? `roles: [${requiredRoles.join(', ')}]` : '';
+            const permMsg = requiredPermissions?.length > 0 ? `permissions: [${requiredPermissions.join(', ')}]` : '';
+            const requirements = [roleMsg, permMsg].filter(Boolean).join(' or ');
+            throw new common_1.ForbiddenException(`Access denied. Required ${requirements}`);
+        }
+        this.logger.debug(`Authorization granted: User ${userId} accessing resource with roles [${userRoles.join(', ')}] and permissions [${userPermissions.join(', ')}]`);
+        return true;
+    }
+    /**
+     * [D4] Modo de enforcement del doble gateo, vía env `AUTHZ_ENFORCEMENT`.
+     * Default 'legacy' ⇒ comportamiento previo (rol O permiso) sin cambio hasta optar in.
+     */
+    resolveEnforcementMode() {
+        const v = (process.env.AUTHZ_ENFORCEMENT ?? 'legacy').toLowerCase();
+        return v === 'observe' || v === 'strict' ? v : 'legacy';
+    }
+    /**
+     * Clasifica la petición como escritura o lectura para el eje modo-ver (D3).
+     * Override explícito @PermissionWrites(boolean) gana; si no, cae por método HTTP
+     * (GET/HEAD/OPTIONS = lectura; el resto = escritura).
+     */
+    isWriteRequest(context, method) {
+        const override = this.reflector.getAllAndOverride(permission_writes_decorator_1.PERMISSION_WRITES_KEY, [
+            context.getHandler(),
+            context.getClass(),
+        ]);
+        if (typeof override === 'boolean') {
+            return override;
+        }
+        return !READ_METHODS.has((method ?? '').toUpperCase());
+    }
+};
+exports.AuthorizationGuard = AuthorizationGuard;
+exports.AuthorizationGuard = AuthorizationGuard = AuthorizationGuard_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [core_1.Reflector])
+], AuthorizationGuard);

package/dist/guards/index.d.ts

@@ -1,4 +1,5 @@
 export * from './jwt-auth.guard';
 export * from './roles.guard';
 export * from './permissions.guard';
+export * from './authorization.guard';
 //# sourceMappingURL=index.d.ts.map

package/dist/guards/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/guards/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/guards/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC"}

package/dist/guards/index.js

@@ -17,3 +17,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./jwt-auth.guard"), exports);
 __exportStar(require("./roles.guard"), exports);
 __exportStar(require("./permissions.guard"), exports);
+__exportStar(require("./authorization.guard"), exports);

package/dist/guards/jwt-auth.guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jwt-auth.guard.d.ts","sourceRoot":"","sources":["../../src/guards/jwt-auth.guard.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,WAAW,EACX,gBAAgB,EAIjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAc,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAIrE;;;GAGG;AACH,qBACa,YAAa,YAAW,WAAW;IAI5C,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAE1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAN1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;gBAGrC,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,SAAS,EAEpB,OAAO,EAAE,wBAAwB;IAG9C,WAAW,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;IA2E9D;;OAEG;IACH,OAAO,CAAC,sBAAsB;CAe/B"}
+{"version":3,"file":"jwt-auth.guard.d.ts","sourceRoot":"","sources":["../../src/guards/jwt-auth.guard.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAqD,MAAM,gBAAgB,CAAC;AAClH,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAEzD;;;GAGG;AACH,qBACa,YAAa,YAAW,WAAW;IAI5C,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAE1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAN1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;gBAGrC,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,SAAS,EAEpB,OAAO,EAAE,wBAAwB;IAG9C,WAAW,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;IA2D9D;;OAEG;IACH,OAAO,CAAC,sBAAsB;CAY/B"}

package/dist/guards/permissions.guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"permissions.guard.d.ts","sourceRoot":"","sources":["../../src/guards/permissions.guard.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,WAAW,EACX,gBAAgB,EAGjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAIzC;;;;GAIG;AACH,qBACa,gBAAiB,YAAW,WAAW;IAGtC,OAAO,CAAC,QAAQ,CAAC,SAAS;IAFtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqC;gBAE/B,SAAS,EAAE,SAAS;IAEjD,WAAW,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO;CAwFhD"}
+{"version":3,"file":"permissions.guard.d.ts","sourceRoot":"","sources":["../../src/guards/permissions.guard.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAA0C,MAAM,gBAAgB,CAAC;AACvG,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAGzC;;;;GAIG;AACH,qBACa,gBAAiB,YAAW,WAAW;IAGtC,OAAO,CAAC,QAAQ,CAAC,SAAS;IAFtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqC;gBAE/B,SAAS,EAAE,SAAS;IAEjD,WAAW,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO;CA6DhD"}

package/dist/guards/permissions.guard.js

@@ -26,9 +26,15 @@ let PermissionsGuard = PermissionsGuard_1 = class PermissionsGuard {
     }
     canActivate(context) {
         // Check for required permissions (AND logic)
-        const requiredPermissions = this.reflector.getAllAndOverride(decorators_1.PERMISSIONS_KEY, [context.getHandler(), context.getClass()]);
+        const requiredPermissions = this.reflector.getAllAndOverride(decorators_1.PERMISSIONS_KEY, [
+            context.getHandler(),
+            context.getClass(),
+        ]);
         // Check for any permissions (OR logic)
-        const anyPermissions = this.reflector.getAllAndOverride('anyPermissions', [context.getHandler(), context.getClass()]);
+        const anyPermissions = this.reflector.getAllAndOverride('anyPermissions', [
+            context.getHandler(),
+            context.getClass(),
+        ]);
         // If no permissions are specified, allow access
         if ((!requiredPermissions || requiredPermissions.length === 0) &&
             (!anyPermissions || anyPermissions.length === 0)) {

package/dist/guards/roles.guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"roles.guard.d.ts","sourceRoot":"","sources":["../../src/guards/roles.guard.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,WAAW,EACX,gBAAgB,EAGjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAIzC;;;GAGG;AACH,qBACa,UAAW,YAAW,WAAW;IAGhC,OAAO,CAAC,QAAQ,CAAC,SAAS;IAFtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;gBAEzB,SAAS,EAAE,SAAS;IAEjD,WAAW,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO;CA2ChD"}
+{"version":3,"file":"roles.guard.d.ts","sourceRoot":"","sources":["../../src/guards/roles.guard.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAA0C,MAAM,gBAAgB,CAAC;AACvG,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAGzC;;;GAGG;AACH,qBACa,UAAW,YAAW,WAAW;IAGhC,OAAO,CAAC,QAAQ,CAAC,SAAS;IAFtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;gBAEzB,SAAS,EAAE,SAAS;IAEjD,WAAW,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO;CA8BhD"}