permissions-contractx 1.0.2 → 1.1.0

package/README.md

@@ -1,1397 +1,104 @@
-# 🔐 Permissions ContractX
+# permissions-contractx
 
-A comprehensive **NestJS authentication and authorization package** designed for microservices in the ContractX ecosystem. This package provides JWT-based authentication, role-based access control (RBAC), and granular permission management.
+Librería compartida de autorización para la plataforma **ContractX**. Provee los guards, decoradores, interfaces y constantes que los microservicios usan para verificar los JWT que emite el servicio de Auth y aplicar el modelo de permisos de dominio (ADR-004).
 
-[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
-[![NestJS](https://img.shields.io/badge/NestJS-E0234E?style=flat&logo=nestjs&logoColor=white)](https://nestjs.com/)
-[![JWT](https://img.shields.io/badge/JWT-000000?style=flat&logo=JSON%20web%20tokens)](https://jwt.io/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+Auth **emite y firma** los tokens; cada microservicio **verifica** los suyos usando este paquete. Ningún servicio mantiene su propio catálogo de permisos: todos referencian el vocabulario central definido en Auth.
 
-## ✨ Features
-
-- 🔑 **JWT Authentication** - Secure token-based authentication
-- 👥 **Role-Based Access Control** - Hierarchical role system
-- 🔐 **Permission-Based Authorization** - Granular permission control
-- 🏢 **Multi-Tenant Support** - Client/Provider organizational structure
-- 🚀 **Easy Integration** - Simple decorator-based API
-- 🛡️ **Security First** - Built-in security best practices
-- 📊 **Request Context** - User context service for easy access
-- 🔧 **TypeScript** - Full TypeScript support with strict typing
-- 📖 **Comprehensive Documentation** - Detailed examples and guides
-
-## 📦 Installation
+## Instalación
 
 ```bash
 npm install permissions-contractx
 ```
 
-### Peer Dependencies
+### Peer dependencies
 
-Make sure you have the required peer dependencies installed:
+El paquete espera que el servicio consumidor ya tenga instaladas:
 
-```bash
-npm install @nestjs/common @nestjs/core @nestjs/jwt @nestjs/config jsonwebtoken rxjs reflect-metadata
-```
+- `@nestjs/common`, `@nestjs/core`
+- `reflect-metadata`, `rxjs`
+- `jsonwebtoken`
+- `express`
 
-## 🚀 Quick Start
+## Qué incluye
 
-### 1. Basic Setup
+### Guards
 
-```typescript
-// app.module.ts
-import { Module } from '@nestjs/common';
-import { PermissionsContractXModule } from 'permissions-contractx';
+- **`AuthorizationGuard`** — guard de autorización con cuatro estados de migración por endpoint (legacy / observación / estricto / solo-permisos), eje lectura/escritura derivado del método HTTP, y soporte de modo-ver (un permiso de solo lectura bloquea escrituras). Resuelve conflictos con la regla *deny-overrides* (deny siempre gana).
+- `JwtAuthGuard` — verificación y decodificación del JWT.
 
-@Module({
-  imports: [
-    PermissionsContractXModule.register({
-      jwt: {
-        secret: 'your-secret-key',
-        issuer: 'your-api',
-        audience: 'your-users',
-        expiresIn: '15m',
-      },
-      guards: {
-        enableGlobalAuth: true, // Apply authentication globally
-      },
-    }),
-  ],
-})
-export class AppModule {}
-```
+### Decoradores
 
-### 2. Using Decorators in Controllers
+- `@RequirePermissions(...)` — declara los permisos que un endpoint exige.
+- `@PermissionWrites(...)` — override explícito del eje lectura/escritura (por ejemplo, un `GET` con efectos o un `POST` de solo lectura).
+- `@CurrentUser()` — inyecta el usuario resuelto del token.
+- `@Public()` — marca un endpoint como abierto.
 
-```typescript
-import { Controller, Get, Post, UseGuards } from '@nestjs/common';
-import {
-  CurrentUser,
-  Roles,
-  RequirePermissions,
-  Public,
-  JwtAuthGuard,
-  RolesGuard,
-  PermissionsGuard,
-  JwtPayload,
-} from 'permissions-contractx';
+### Interfaces
 
-@Controller('users')
-@UseGuards(JwtAuthGuard, RolesGuard, PermissionsGuard)
-export class UsersController {
-  
-  // Public endpoint (no authentication)
-  @Public()
-  @Get('public')
-  getPublicInfo() {
-    return { message: 'This is public' };
-  }
+- **`JwtPayload`** — contrato del token que emite Auth: `sub`, `role[]`, `permissions[]`, `permissionsView[]`, `clientId[]`, `providerId`, `tenantContext` (`'client' | 'provider' | 'system'`), `key_client`, entre otros.
+- `PermissionMode` — enum `WRITE` / `READ`, espejo del modo del par rol↔permiso en Auth.
 
-  // Authenticated endpoint
-  @Get('profile')
-  getProfile(@CurrentUser() user: JwtPayload) {
-    return {
-      id: user.sub,
-      name: user.fullName,
-      roles: user.role,
-      permissions: user.permissions,
-    };
-  }
+### Constantes
 
-  // Role-based access
-  @Roles('superadmin', 'client_contract_admin')
-  @Get('admin-data')
-  getAdminData() {
-    return { message: 'Admin only data' };
-  }
+- **`permission-names.constants`** — los 130 códigos de permiso de dominio, agrupados por microservicio, más `PERMISSIONS_BY_DOMAIN`, `ALL_PERMISSION_CODES` y el tipo `PermissionCode`.
+- `security.constants` — constantes de roles del sistema.
 
-  // Permission-based access
-  @RequirePermissions('users.create')
-  @Post()
-  createUser(@CurrentUser() user: JwtPayload) {
-    return { message: 'User created', createdBy: user.fullName };
-  }
-
-  // Combined role and permission
-  @Roles('client_contract_admin')
-  @RequirePermissions('users.delete')
-  @Delete(':id')
-  deleteUser(@Param('id') id: string) {
-    return { message: `User ${id} deleted` };
-  }
-}
-```
-
-### 3. Environment Variables Setup
-
-Create a `.env` file:
-
-```env
-JWT_SECRET=your-super-secret-jwt-key-change-in-production
-JWT_ISSUER=contractx-api
-JWT_AUDIENCE=contractx-users
-JWT_EXPIRES_IN=15m
-
-# Optional: Enable global guards
-ENABLE_GLOBAL_AUTH=true
-ENABLE_AUTH_LOGGING=true
-
-# Development only
-DISABLE_AUTH=false  # Set to true to disable auth in development
-```
+## Uso básico
 
-### 4. Auto-Configuration with Environment Variables
+Registrar el guard de forma global en un microservicio (NestJS):
 
 ```typescript
-// app.module.ts - Easiest setup
-@Module({
-  imports: [
-    PermissionsContractXModule.forRoot(), // Auto-configures from environment variables
-  ],
-})
-export class AppModule {}
-```
-
-## 🏗️ Advanced Configuration
-
-### Async Configuration
-
-```typescript
-import { ConfigModule, ConfigService } from '@nestjs/config';
+import { AuthorizationGuard } from 'permissions-contractx';
+import { APP_GUARD } from '@nestjs/core';
 
 @Module({
-  imports: [
-    PermissionsContractXModule.registerAsync({
-      imports: [ConfigModule],
-      useFactory: async (configService: ConfigService) => ({
-        jwt: {
-          secret: configService.get('JWT_SECRET'),
-          issuer: configService.get('JWT_ISSUER'),
-          audience: configService.get('JWT_AUDIENCE'),
-          expiresIn: configService.get('JWT_EXPIRES_IN', '15m'),
-          clockTolerance: 30, // seconds
-        },
-        guards: {
-          enableGlobalAuth: true,
-          enableGlobalRoles: false,
-          enableGlobalPermissions: false,
-        },
-        security: {
-          enableLogging: process.env.NODE_ENV === 'production',
-        },
-        development: {
-          disableAuth: process.env.NODE_ENV === 'development',
-          mockUser: {
-            sub: 'dev-user-123',
-            role: ['superadmin'],
-            permissions: ['*'],
-            fullName: 'Development User',
-            email: 'dev@example.com',
-          },
-        },
-      }),
-      inject: [ConfigService],
-    }),
+  providers: [
+    { provide: APP_GUARD, useClass: AuthorizationGuard },
   ],
 })
 export class AppModule {}
 ```
 
-## 📋 JWT Token Structure
-
-The JWT token must include the following payload structure:
-
-```json
-{
-  "sub": "user_123456789",      // User ID (required)
-  "fullName": "John Doe",       // User's full name (required)
-  "email": "john@example.com",  // User's email
-  "clientId": "client_001",     // Organization/Client ID
-  "sessionId": "session_abc",   // Session tracking
-  
-  "role": [                     // User roles array (required)
-    "admin",
-    "manager",
-    "user"
-  ],
-  
-  "permissions": [              // User permissions array (required)
-    "users:read",
-    "users:create",
-    "users:update",
-    "users:delete",
-    "settings:manage"
-  ],
-  
-  // Standard JWT fields
-  "iat": 1609459200,           // Issued at
-  "exp": 1609545600,           // Expires at
-  "iss": "contractx-api",      // Issuer
-  "aud": "contractx-users"     // Audience
-}
-```
-
-## 🛡️ Guards
-
-### 1. JwtAuthGuard
-
-Validates JWT tokens and extracts user information.
-
-```typescript
-import { Controller, UseGuards } from '@nestjs/common';
-import { JwtAuthGuard } from 'permissions-contractx';
-
-@Controller('protected')
-@UseGuards(JwtAuthGuard)
-export class ProtectedController {
-  // All routes require valid JWT token
-}
-```
-
-### 2. RolesGuard
-
-Checks if user has required roles.
+Proteger un endpoint exigiendo un permiso:
 
 ```typescript
-import { Controller, UseGuards } from '@nestjs/common';
-import { JwtAuthGuard, RolesGuard, RequireRoles } from 'permissions-contractx';
-
-@Controller('admin')
-@UseGuards(JwtAuthGuard, RolesGuard)
-export class AdminController {
-  
-  @Get('dashboard')
-  @RequireRoles('admin', 'manager') // User must have admin OR manager role
-  getDashboard() {
-    return { message: 'Admin dashboard' };
-  }
-}
-```
-
-### 3. PermissionsGuard
-
-Checks if user has required permissions.
-
-```typescript
-import { Controller, UseGuards } from '@nestjs/common';
-import { JwtAuthGuard, PermissionsGuard, RequirePermissions } from 'permissions-contractx';
-
-@Controller('users')
-@UseGuards(JwtAuthGuard, PermissionsGuard)
-export class UsersController {
-  
-  @Post()
-  @RequirePermissions('users:create') // User must have this exact permission
-  createUser() {
-    return { message: 'User created' };
-  }
-
-  @Delete(':id')
-  @RequirePermissions('users:delete', 'admin:all') // User must have one of these
-  deleteUser() {
-    return { message: 'User deleted' };
-  }
-}
-```
-
-## 🎯 Decorators
-
-The permissions-contractx package provides a comprehensive set of decorators for authentication and authorization in your NestJS applications.
-
-### 🔐 Authentication Decorators
-
-#### `@Public()`
-Marks routes as public (no authentication required). Essential for login endpoints, health checks, and public APIs.
-
-```typescript
-@Controller('auth')
-export class AuthController {
-  @Public()
-  @Post('login')
-  login(@Body() credentials: LoginDto) {
-    return this.authService.login(credentials);
-  }
-  
-  @Public()
-  @Get('health')
-  getHealth() {
-    return { status: 'OK', timestamp: new Date() };
-  }
-}
-```
-
-#### `@CurrentUser(property?)`
-Injects the current authenticated user or specific user properties into route handlers.
-
-```typescript
-@Controller('users')
-export class UsersController {
-  // Inject full user object
-  @Get('profile')
-  getProfile(@CurrentUser() user: JwtPayload) {
-    return {
-      id: user.sub,
-      name: user.fullName,
-      email: user.email,
-      roles: user.role,
-      permissions: user.permissions
-    };
-  }
-  
-  // Inject specific user property
-  @Post('actions')
-  performAction(
-    @CurrentUser('sub') userId: string,
-    @CurrentUser('fullName') userName: string,
-    @Body() actionData: any
-  ) {
-    return {
-      action: 'completed',
-      performedBy: userName,
-      userId: userId,
-      data: actionData
-    };
-  }
-}
-```
-
-#### `@UserId()`
-Convenience decorator to get the current user's ID directly.
-
-```typescript
-@Controller('resources')
-export class ResourcesController {
-  @Post()
-  createResource(
-    @UserId() userId: string,
-    @Body() resourceData: CreateResourceDto
-  ) {
-    return this.resourcesService.create({
-      ...resourceData,
-      createdBy: userId,
-      createdAt: new Date()
-    });
-  }
-  
-  @Get('my-resources')
-  getMyResources(@UserId() userId: string) {
-    return this.resourcesService.findByUser(userId);
-  }
-}
-```
-
-#### `@UserRoles()`
-Injects the current user's roles array into the route handler.
-
-```typescript
-@Controller('dashboard')
-export class DashboardController {
-  @Get('capabilities')
-  getUserCapabilities(@UserRoles() roles: string[]) {
-    const capabilities = {
-      canManageUsers: roles.includes('superadmin') || roles.includes('client_contract_admin'),
-      canViewReports: roles.some(role => role.includes('reports')),
-      canManageContracts: roles.some(role => role.includes('contract_admin')),
-      isClientSide: roles.some(role => role.startsWith('client_')),
-      isProviderSide: roles.some(role => role.startsWith('provider_'))
-    };
-    
-    return { roles, capabilities };
-  }
-}
-```
+import { RequirePermissions } from 'permissions-contractx';
 
-#### `@UserPermissions()`
-Injects the current user's permissions array into the route handler.
-
-```typescript
-@Controller('admin')
-export class AdminController {
-  @Get('available-actions')
-  getAvailableActions(@UserPermissions() permissions: string[]) {
-    const modulePermissions = permissions.reduce((acc, permission) => {
-      const [module, action] = permission.split(':');
-      if (!acc[module]) acc[module] = [];
-      acc[module].push(action);
-      return acc;
-    }, {});
-    
-    return {
-      totalPermissions: permissions.length,
-      moduleBreakdown: modulePermissions,
-      rawPermissions: permissions
-    };
-  }
-}
-```
-
-#### `@UserClientId()`
-Injects the current user's client ID for multi-tenant applications.
-
-```typescript
-@Controller('tenant')
-export class TenantController {
-  @Get('data')
-  getTenantData(@UserClientId() clientId: string) {
-    return this.dataService.findByClient(clientId);
-  }
-  
-  @Post('settings')
-  updateTenantSettings(
-    @UserClientId() clientId: string,
-    @Body() settings: TenantSettingsDto
-  ) {
-    return this.settingsService.update(clientId, settings);
-  }
-}
-```
-
-### 👥 Role-Based Authorization Decorators
-
-#### `@Roles(...roles)`
-Requires user to have **at least one** of the specified roles (OR logic).
-
-```typescript
-@Controller('admin')
-export class AdminController {
-  // User needs superadmin OR any contract admin role
-  @Roles('superadmin', 'client_contract_admin', 'provider_contract_admin')
-  @Get('dashboard')
-  getAdminDashboard() {
-    return { message: 'Admin dashboard data' };
-  }
-  
-  // Multiple specific roles
-  @Roles('client_finance_manager', 'provider_finance_manager')
-  @Get('financial-reports')
-  getFinancialReports() {
-    return this.reportsService.getFinancialData();
-  }
-}
-```
-
-#### `@AdminOnly()`
-Shortcut for admin-level access (superadmin, client_contract_admin, provider_contract_admin).
-
-```typescript
-@Controller('system')
-export class SystemController {
-  @AdminOnly()
-  @Delete('cache')
-  clearCache() {
-    return this.cacheService.clear();
-  }
-  
-  @AdminOnly()
-  @Post('maintenance-mode')
-  enableMaintenanceMode(@Body() config: MaintenanceConfigDto) {
-    return this.systemService.enableMaintenance(config);
-  }
-}
-```
-
-#### `@ClientOnly()`
-Restricts access to client-side roles only.
-
-```typescript
-@Controller('client')
-export class ClientController {
-  @ClientOnly()
-  @Get('performance-metrics')
-  getClientPerformanceMetrics(@UserClientId() clientId: string) {
-    return this.metricsService.getClientMetrics(clientId);
-  }
-  
-  @ClientOnly()
-  @Post('escalation')
-  createEscalation(@Body() escalationData: CreateEscalationDto) {
-    return this.escalationService.create(escalationData);
-  }
-}
-```
-
-#### `@ProviderOnly()`
-Restricts access to provider-side roles only.
-
-```typescript
-@Controller('provider')
-export class ProviderController {
-  @ProviderOnly()
-  @Get('delivery-schedule')
-  getDeliverySchedule() {
-    return this.deliveryService.getSchedule();
-  }
-  
-  @ProviderOnly()
-  @Put('deliverable/:id/status')
-  updateDeliverableStatus(
-    @Param('id') id: string,
-    @Body() statusUpdate: DeliverableStatusDto
-  ) {
-    return this.deliverableService.updateStatus(id, statusUpdate);
-  }
-}
-```
-
-#### `@SuperAdminOnly()`
-Restricts access to superadmin role only.
-
-```typescript
-@Controller('system-admin')
-export class SystemAdminController {
-  @SuperAdminOnly()
-  @Post('create-tenant')
-  createTenant(@Body() tenantData: CreateTenantDto) {
-    return this.tenantService.create(tenantData);
-  }
-  
-  @SuperAdminOnly()
-  @Delete('user/:id')
-  deleteUser(@Param('id') userId: string) {
-    return this.userService.delete(userId);
-  }
-}
-```
-
-### 🔐 Permission-Based Authorization Decorators
-
-#### `@RequirePermissions(...permissions)`
-Requires user to have **all** specified permissions (AND logic).
-
-```typescript
 @Controller('contracts')
 export class ContractsController {
-  // User must have ALL specified permissions
-  @RequirePermissions('contracts.create', 'contracts.validate')
   @Post()
-  createContract(@Body() contractData: CreateContractDto) {
-    return this.contractService.create(contractData);
-  }
-  
-  // Single permission requirement
-  @RequirePermissions('contracts.delete')
-  @Delete(':id')
-  deleteContract(@Param('id') id: string) {
-    return this.contractService.delete(id);
-  }
-}
-```
-
-#### `@RequireAnyPermission(...permissions)`
-Requires user to have **at least one** of the specified permissions (OR logic).
-
-```typescript
-@Controller('documents')
-export class DocumentsController {
-  // User needs ANY of these permissions
-  @RequireAnyPermission('documents.read', 'documents.show', 'documents.filter')
-  @Get()
-  getDocuments(@Query() filters: DocumentFiltersDto) {
-    return this.documentService.findAll(filters);
-  }
-  
-  // Administrative permissions
-  @RequireAnyPermission('documents.admin', 'superadmin.all')
-  @Post('batch-process')
-  batchProcessDocuments(@Body() batchData: BatchProcessDto) {
-    return this.documentService.batchProcess(batchData);
-  }
-}
-```
-
-### 🎯 Module-Level Permission Decorators
-
-These decorators provide convenient access patterns based on common CRUD operations:
-
-#### `@ReadAccess(module)`
-Grants read access to a module (read, show, or filter permissions).
-
-```typescript
-@Controller('reports')
-export class ReportsController {
-  @ReadAccess('reports')
-  @Get('financial')
-  getFinancialReports() {
-    // User needs reports.read, reports.show, OR reports.filter
-    return this.reportsService.getFinancialReports();
-  }
-  
-  @ReadAccess('contracts')
-  @Get('contract-summary')
-  getContractSummary() {
-    // User needs contracts.read, contracts.show, OR contracts.filter
-    return this.contractService.getSummary();
-  }
-}
-```
-
-#### `@WriteAccess(module)`
-Grants write access to a module (create or update permissions).
-
-```typescript
-@Controller('users')
-export class UsersController {
-  @WriteAccess('users')
-  @Post()
-  createUser(@Body() userData: CreateUserDto) {
-    // User needs users.create OR users.update
-    return this.userService.create(userData);
-  }
-  
-  @WriteAccess('users')
-  @Put(':id')
-  updateUser(
-    @Param('id') id: string,
-    @Body() userData: UpdateUserDto
-  ) {
-    // User needs users.create OR users.update
-    return this.userService.update(id, userData);
-  }
-}
-```
-
-#### `@DeleteAccess(module)`
-Grants delete access to a module.
-
-```typescript
-@Controller('deliverables')
-export class DeliverablesController {
-  @DeleteAccess('deliverables')
-  @Delete(':id')
-  deleteDeliverable(@Param('id') id: string) {
-    // User needs deliverables.delete
-    return this.deliverableService.delete(id);
-  }
-}
-```
-
-#### `@FullAccess(module)`
-Grants full CRUD access to a module (any module permission).
-
-```typescript
-@Controller('admin/modules')
-export class ModuleAdminController {
-  @FullAccess('users')
-  @Post('users/bulk-operation')
-  bulkUserOperation(@Body() operation: BulkOperationDto) {
-    // User needs ANY users module permission
-    return this.userService.bulkOperation(operation);
-  }
-}
-```
-
-### 🔄 Combining Decorators
-
-Decorators can be combined for complex authorization logic:
-
-```typescript
-@Controller('advanced')
-export class AdvancedController {
-  // Combine role and permission requirements
-  @Roles('client_contract_admin', 'provider_contract_admin')
-  @RequirePermissions('contracts.approve')
-  @Put('contracts/:id/approve')
-  approveContract(
-    @Param('id') contractId: string,
-    @CurrentUser() user: JwtPayload
-  ) {
-    return this.contractService.approve(contractId, user.sub);
-  }
-  
-  // Complex permission logic
-  @ClientOnly()
-  @RequireAnyPermission('reports.generate', 'reports.admin')
-  @Post('custom-report')
-  generateCustomReport(
-    @Body() reportSpec: CustomReportDto,
-    @UserClientId() clientId: string
-  ) {
-    return this.reportsService.generateCustom(reportSpec, clientId);
-  }
-  
-  // Multiple permission sets
-  @RequirePermissions('documents.create')
-  @RequireAnyPermission('contracts.update', 'deliverables.update')
-  @Post('document-with-linking')
-  createLinkedDocument(
-    @Body() documentData: LinkedDocumentDto,
-    @UserId() userId: string
-  ) {
-    // User must have documents.create AND (contracts.update OR deliverables.update)
-    return this.documentService.createWithLinking(documentData, userId);
-  }
-}
-```
-
-### 🏷️ Method vs Class Level Decorators
-
-Decorators can be applied at both class and method levels:
-
-```typescript
-// Class-level decorators apply to all methods
-@Controller('secure')
-@UseGuards(JwtAuthGuard, RolesGuard, PermissionsGuard)
-@ClientOnly() // All methods require client roles
-export class SecureController {
-  @Get('data')
-  getData() {
-    // Inherits @ClientOnly from class
-    return this.dataService.getClientData();
-  }
-  
-  @RequirePermissions('admin.override')
-  @Get('admin-data')
-  getAdminData() {
-    // Combines @ClientOnly + @RequirePermissions
-    return this.dataService.getAdminData();
-  }
-  
-  @Public() // Overrides class-level @ClientOnly
-  @Get('public-info')
-  getPublicInfo() {
-    return { message: 'Public information' };
-  }
-}
-```
-
-## 🛠️ Services
-
-### UserContextService
-
-Access user information and check permissions programmatically:
-
-```typescript
-import { Injectable } from '@nestjs/common';
-import { UserContextService } from 'permissions-contractx';
-
-@Injectable()
-export class MyService {
-  constructor(private userContext: UserContextService) {}
-
-  async doSomething() {
-    // Get user information
-    const user = this.userContext.getUser();
-    const userId = this.userContext.getUserId();
-    const roles = this.userContext.getUserRoles();
-
-    // Check permissions
-    if (this.userContext.hasRole('admin')) {
-      // Do admin stuff
-    }
-
-    if (this.userContext.hasPermission('users.create')) {
-      // Can create users
-    }
-
-    if (this.userContext.isClientUser()) {
-      // Client-side user logic
-    }
-
-    // Get user summary for logging
-    const summary = this.userContext.getUserSummary();
-    console.log('User accessing service:', summary);
-  }
-}
-```
-
-## 🚫 Error Handling
-
-The package provides specific error messages for different authentication and authorization failures:
-
-### Common Error Responses
-
-```json
-// 401 - Missing token
-{
-  "statusCode": 401,
-  "message": "Access token is required",
-  "error": "Unauthorized"
-}
-
-// 401 - Invalid token
-{
-  "statusCode": 401,
-  "message": "Invalid access token",
-  "error": "Unauthorized"
-}
-
-// 401 - Expired token
-{
-  "statusCode": 401,
-  "message": "Access token has expired",
-  "error": "Unauthorized"
-}
-
-// 403 - Insufficient permissions
-{
-  "statusCode": 403,
-  "message": "Insufficient permissions. Required: users:create",
-  "error": "Forbidden"
-}
-
-// 403 - Missing roles
-{
-  "statusCode": 403,
-  "message": "Insufficient roles. Required: admin",
-  "error": "Forbidden"
-}
-```
-
-### Custom Error Handling
-
-```typescript
-import { ExceptionFilter, Catch, ArgumentsHost } from '@nestjs/common';
-import { UnauthorizedException, ForbiddenException } from '@nestjs/common';
-
-@Catch(UnauthorizedException, ForbiddenException)
-export class AuthExceptionFilter implements ExceptionFilter {
-  catch(exception: UnauthorizedException | ForbiddenException, host: ArgumentsHost) {
-    const ctx = host.switchToHttp();
-    const response = ctx.getResponse();
-    
-    // Custom error handling logic
-    response.status(exception.getStatus()).json({
-      statusCode: exception.getStatus(),
-      message: exception.message,
-      timestamp: new Date().toISOString(),
-    });
-  }
-}
-```
-
-## 💾 Database Integration & ODS Seeder
-
-### ODS Roles and Permissions Seeder
-
-The package includes a complete seeder for the ODS (Operational Data Store) roles and permissions matrix with **16 predefined roles** and **23 modules**:
-
-```typescript
-import { ContractXRolePermissionSeeder } from '@your-org/permissions-contractx';
-
-@Injectable()
-export class DatabaseSeederService {
-  constructor(
-    private readonly seeder: ContractXRolePermissionSeeder,
-    // Your repository dependencies
-    @InjectRepository(Role) private roleRepo: Repository<Role>,
-    @InjectRepository(Permission) private permissionRepo: Repository<Permission>,
-    @InjectRepository(RolePermission) private rolePermissionRepo: Repository<RolePermission>
-  ) {}
-
-  async seedRolesAndPermissions() {
-    const { roles, permissions, rolePermissions } = await this.seeder.seed();
-    
-    // Save to database
-    const savedRoles = await this.roleRepo.save(roles);
-    const savedPermissions = await this.permissionRepo.save(permissions);
-    
-    // Update IDs for role-permission mappings
-    const mappingsWithIds = rolePermissions.map(rp => ({
-      ...rp,
-      roleId: savedRoles.find(r => r.name === roles.find(role => role.id === rp.roleId)?.name)?.id,
-      permissionId: savedPermissions.find(p => p.name === permissions.find(perm => perm.id === rp.permissionId)?.name)?.id
-    }));
-    
-    await this.rolePermissionRepo.save(mappingsWithIds);
-    
-    // Validate seeded data
-    const isValid = await this.seeder.validateSeed(savedRoles, savedPermissions, mappingsWithIds);
-    if (!isValid) {
-      throw new Error('Seeder validation failed');
-    }
-    
-    // Get statistics
-    const stats = this.seeder.getSeederStats();
-    console.log('Seeding completed:', stats);
-    /*
-    Output:
-    {
-      totalRoles: 16,
-      totalPermissions: 161, // 23 modules × 7 actions each
-      totalModules: 23,
-      rolesByType: {
-        system: 4,
-        client: 6,
-        provider: 6
-      },
-      permissionsByCategory: {
-        contract_management: 98,
-        financial: 21,
-        system_admin: 21,
-        user_management: 7,
-        client_management: 7,
-        provider_management: 7
-      }
-    }
-    */
-  }
-}
-```
-
-### ODS Roles Matrix (16 Roles)
-
-The seeder creates the following roles based on the complete ODS specification:
-
-#### 🔧 System Roles
-- **superadmin**: Full system access to all modules
-- **support**: Broad access excluding client management
-- **auditor**: Read-only audit and compliance access
-- **guest**: Limited read-only access
-
-#### 👥 Client-Side Roles
-- **client_contract_admin**: Full contract management for client
-- **client_performance_manager**: SLA and performance management
-- **client_finance_manager**: Financial operations and invoicing
-- **client_reports_manager**: Reporting and analytics
-- **client_relationship_manager**: Relationship and meeting management
-- **client_risk_manager**: Risk and security management
-
-#### 🏢 Provider-Side Roles
-- **provider_contract_admin**: Provider contract administration
-- **provider_performance_manager**: Provider performance management
-- **provider_finance_manager**: Provider financial operations
-- **provider_relationship_manager**: Provider relationship management
-- **provider_risk_manager**: Provider risk management
-- **provider_operator**: Operational support and deliverable management
-
-### 📊 ODS Modules (23 Modules)
-
-The seeder covers all ContractX modules with comprehensive CRUD permissions:
-
-- **Core Management**: clients, contracts, users, providers, documents, clauses
-- **Deliverables**: deliverables, subdeliverables, deliverable_history
-- **SLA Management**: sla_services, measurement_windows, credit_service_levels
-- **Collaboration**: meetings, meeting_participants, action_items
-- **Notifications**: notification_escalations
-- **Financial**: invoice_services, invoice_lines
-- **System**: security_control, configuration, workflows
-
-### Database Entity Examples
-
-For database integration with TypeORM, implement the seeder interfaces:
-
-```typescript
-// Role Entity
-@Entity('roles')
-export class Role implements RoleEntity {
-  @PrimaryGeneratedColumn('uuid')
-  id: string;
-
-  @Column({ unique: true })
-  name: string;
-
-  @Column()
-  displayName: string;
-
-  @Column()
-  description: string;
-
-  @Column()
-  type: string;
-
-  @Column()
-  scope: string;
-
-  @Column()
-  level: number;
-
-  @Column({ default: true })
-  isActive: boolean;
-
-  @Column()
-  tenantAssociation: string;
-
-  @Column('jsonb')
-  metadata: Record<string, any>;
-
-  @CreateDateColumn()
-  createdAt: Date;
-
-  @UpdateDateColumn()
-  updatedAt: Date;
-}
-
-// Permission Entity
-@Entity('permissions')
-export class Permission implements PermissionEntity {
-  @PrimaryGeneratedColumn('uuid')
-  id: string;
-
-  @Column({ unique: true })
-  name: string;
-
-  @Column()
-  displayName: string;
-
-  @Column()
-  description: string;
-
-  @Column()
-  module: string;
-
-  @Column()
-  action: string;
-
-  @Column()
-  category: string;
-
-  @Column()
-  scope: string;
-
-  @Column({ default: true })
-  isActive: boolean;
-
-  @Column('jsonb')
-  metadata: Record<string, any>;
-
-  @CreateDateColumn()
-  createdAt: Date;
-
-  @UpdateDateColumn()
-  updatedAt: Date;
-}
-
-// Role-Permission Junction
-@Entity('role_permissions')
-export class RolePermission implements RolePermissionEntity {
-  @PrimaryGeneratedColumn('uuid')
-  id: string;
-
-  @Column()
-  roleId: string;
-
-  @Column()
-  permissionId: string;
-
-  @Column({ default: true })
-  isActive: boolean;
-
-  @Column('jsonb', { nullable: true })
-  metadata: Record<string, any>;
-
-  @CreateDateColumn()
-  createdAt: Date;
-
-  @UpdateDateColumn()
-  updatedAt: Date;
-}
-
-// User entity example with JWT payload
-@Entity('users')
-export class User implements JwtPayload {
-  @PrimaryGeneratedColumn('uuid')
-  id: string;
-
-  @Column()
-  email: string;
-
-  @Column('simple-array')
-  roles: string[];
-
-  @Column('simple-array')
-  permissions: string[];
-
-  @Column({ nullable: true })
-  clientId?: string;
-
-  @Column({ nullable: true })
-  providerId?: string;
-
-  @Column()
-  firstName: string;
-
-  @Column()
-  lastName: string;
-
-  @Column({ default: true })
-  isActive: boolean;
-
-  @CreateDateColumn()
-  createdAt: Date;
-
-  @UpdateDateColumn()
-  updatedAt: Date;
-}
-```
-
-### Integration with Auth Service
-
-```typescript
-// In your auth-service-contract
-@Injectable()
-export class AuthService {
-  constructor(
-    private readonly seeder: ContractXRolePermissionSeeder,
-    private readonly authorizationService: ContractXAuthorizationService,
-    private readonly validationService: ContractXValidationService,
-  ) {}
-
-  async initializeSystem() {
-    // Seed ODS roles and permissions
-    await this.seeder.seed();
-  }
-
-  async validateUserAccess(user: JwtPayload, requiredPermission: string) {
-    return this.authorizationService.checkPermission(user, requiredPermission);
-  }
-
-  async getUserAccessMatrix(user: JwtPayload) {
-    return this.authorizationService.generateAccessMatrix(user);
-  }
+  @RequirePermissions('contracts.create')
+  create() { /* ... */ }
 }
 ```
 
-## 🌍 Environment Variables
-
-| Variable | Description | Default | Required |
-|----------|-------------|---------|----------|
-| `JWT_SECRET` | JWT signing secret | - | ✅ Yes |
-| `JWT_ISSUER` | Token issuer | `contractx-api` | No |
-| `JWT_AUDIENCE` | Token audience | `contractx-users` | No |
-| `JWT_EXPIRES_IN` | Token expiration | `15m` | No |
-| `JWT_CLOCK_TOLERANCE` | Clock tolerance (seconds) | `0` | No |
-| `ENABLE_GLOBAL_AUTH` | Apply auth guard globally | `false` | No |
-| `ENABLE_GLOBAL_ROLES` | Apply roles guard globally | `false` | No |
-| `ENABLE_GLOBAL_PERMISSIONS` | Apply permissions guard globally | `false` | No |
-| `ENABLE_AUTH_LOGGING` | Enable security logging | `false` | No |
-| `DISABLE_AUTH` | Disable authentication | `false` | No |
-
-## 🔒 Security Best Practices
-
-### 1. JWT Token Structure
-
-The package expects JWT tokens with this payload structure:
+Override del eje lectura/escritura cuando la convención HTTP no aplica:
 
 ```typescript
-interface JwtPayload {
-  sub: string;                // User ID
-  role: string[];            // User roles
-  permissions: string[];     // User permissions
-  fullName: string;          // User's full name
-  email?: string;            // User's email
-  clientId?: string;         // Organization/client ID
-  sessionId?: string;        // Session tracking
-  iat?: number;             // Issued at
-  exp?: number;             // Expires at
-}
-```
-
-### 2. Environment Variables
-
-```env
-# Required
-JWT_SECRET=your-256-bit-secret-key-here
-JWT_ISSUER=your-api-name
-JWT_AUDIENCE=your-api-users
-
-# Optional but recommended
-JWT_EXPIRES_IN=15m
-JWT_CLOCK_TOLERANCE=30
-
-# Security
-ENABLE_AUTH_LOGGING=true
-```
-
-### 3. Global Guards
+import { PermissionWrites } from 'permissions-contractx';
 
-```typescript
-// For maximum security, enable global authentication
-PermissionsContractXModule.register({
-  guards: {
-    enableGlobalAuth: true,    // All routes require auth by default
-    enableGlobalRoles: false,  // Only specific routes check roles
-    enableGlobalPermissions: false, // Only specific routes check permissions
-  },
-})
+// Un POST que en realidad solo consulta:
+@Post('search')
+@RequirePermissions('contracts.view_list')
+@PermissionWrites(false)
+search() { /* ... */ }
 ```
 
-## 🧪 Testing
-
-### Unit Testing
-
-```typescript
-import { Test } from '@nestjs/testing';
-import { JwtService } from '@nestjs/jwt';
-import { JwtAuthGuard } from 'permissions-contractx';
-
-describe('Authentication', () => {
-  let guard: JwtAuthGuard;
-
-  beforeEach(async () => {
-    const module = await Test.createTestingModule({
-      providers: [
-        JwtAuthGuard,
-        {
-          provide: JwtService,
-          useValue: { verifyAsync: jest.fn() },
-        },
-        // ... other providers
-      ],
-    }).compile();
-
-    guard = module.get(JwtAuthGuard);
-  });
-
-  it('should authenticate valid token', async () => {
-    // Test implementation
-  });
-});
-```
-
-### Integration Testing
-
-```typescript
-import * as request from 'supertest';
-
-describe('Protected Routes', () => {
-  it('should reject unauthenticated requests', () => {
-    return request(app.getHttpServer())
-      .get('/protected-route')
-      .expect(401);
-  });
-
-  it('should allow authenticated requests', () => {
-    return request(app.getHttpServer())
-      .get('/protected-route')
-      .set('Authorization', `Bearer ${validToken}`)
-      .expect(200);
-  });
-});
-```
-
-## 🚀 Production Deployment
-
-### Docker Support
-
-```dockerfile
-FROM node:18-alpine
-WORKDIR /app
-COPY package*.json ./
-RUN npm ci --only=production
-COPY . .
-RUN npm run build
-
-ENV NODE_ENV=production
-ENV JWT_SECRET=${JWT_SECRET}
-ENV JWT_ISSUER=contractx-production
-
-EXPOSE 3000
-CMD ["npm", "run", "start:prod"]
-```
-
-### Environment Configuration
-
-```yaml
-# docker-compose.yml
-version: '3.8'
-services:
-  app:
-    build: .
-    environment:
-      - NODE_ENV=production
-      - JWT_SECRET=${JWT_SECRET}
-      - JWT_ISSUER=contractx-api
-      - JWT_AUDIENCE=contractx-users
-      - ENABLE_AUTH_LOGGING=true
-```
-
-## 📖 Examples
-
-### Complete Controller Example
-
-```typescript
-import {
-  Controller,
-  Get,
-  Post,
-  Put,
-  Delete,
-  Body,
-  Param,
-  UseGuards,
-} from '@nestjs/common';
-import {
-  JwtAuthGuard,
-  RolesGuard,
-  PermissionsGuard,
-  CurrentUser,
-  Roles,
-  RequirePermissions,
-  Public,
-  ClientOnly,
-  AdminOnly,
-  JwtPayload,
-} from 'permissions-contractx';
-
-@Controller('contracts')
-@UseGuards(JwtAuthGuard, RolesGuard, PermissionsGuard)
-export class ContractsController {
-  
-  @Public()
-  @Get('health')
-  getHealth() {
-    return { status: 'OK' };
-  }
-
-  @Get()
-  @RequirePermissions('contracts.read', 'contracts.filter')
-  async getContracts(@CurrentUser() user: JwtPayload) {
-    // User must have both read AND filter permissions
-    return { contracts: [], requestedBy: user.fullName };
-  }
-
-  @Post()
-  @ClientOnly()
-  @RequirePermissions('contracts.create')
-  async createContract(
-    @Body() contractData: any,
-    @CurrentUser() user: JwtPayload,
-  ) {
-    // Only client-side users with create permission
-    return { id: '123', createdBy: user.sub };
-  }
-
-  @Put(':id/approve')
-  @AdminOnly()
-  @RequirePermissions('contracts.approve')
-  async approveContract(
-    @Param('id') id: string,
-    @CurrentUser() user: JwtPayload,
-  ) {
-    // Only admins with approval permission
-    return { id, approvedBy: user.fullName, approvedAt: new Date() };
-  }
-
-  @Delete(':id')
-  @Roles('superadmin')
-  async deleteContract(@Param('id') id: string) {
-    // Only superadmin can delete
-    return { message: `Contract ${id} deleted` };
-  }
-}
-```
-
-## 🤝 Contributing
-
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
-
-## 📄 License
+## Modelo de cuatro estados (migración)
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+El `AuthorizationGuard` permite migrar cada endpoint de forma gradual mediante la variable de entorno de enforcement:
 
-## 🆘 Support
+1. **legacy / solo-roles** — sin gateo por permisos (estado de partida).
+2. **observación** — el gateo por permisos evalúa y registra discrepancias, pero solo el rol-gate bloquea.
+3. **estricto** — ambos gates bloquean.
+4. **solo-permisos** — endpoint graduado, gateado únicamente por permisos.
 
-- 📧 Email: support@contractx.dev
-- 🐛 Issues: [GitHub Issues](https://github.com/your-org/permissions-contractx/issues)
-- 📚 Documentation: [Full Documentation](https://permissions-contractx.dev)
+Esto permite introducir el enforcement servicio por servicio sin romper el acceso existente. El principio rector es *fallar-seguro*: ante cualquier conflicto, gana lo más restrictivo.
 
-## 📊 Package Stats
+## Versionado
 
-- ✅ **Zero Dependencies** (only peer dependencies)
-- 🚀 **TypeScript First** - Built with TypeScript for TypeScript
-- 📦 **Tree Shakeable** - Only import what you need
-- 🔒 **Security Focused** - Built with security best practices
-- 🧪 **Well Tested** - Comprehensive test coverage
+Sigue [SemVer](https://semver.org/). La serie `1.x` es aditiva sobre el modelo ADR-004; los cambios que retiren la API antigua de autorización se reservan para una mayor (`2.0.0`).
 
----
+## Licencia
 
-Made with ❤️ by the ContractX Team
+MIT