backend-mcp/modules/auth/manifest.yaml

Generador automático de backends con Node.js, Express, Prisma y módulos configurables. Servidor MCP compatible con npx para agentes IA. Soporta PostgreSQL, MySQL, MongoDB y SQLite.

# modules/auth/manifest.yaml
module:
  name: "auth"
  version: "1.0.0"
  description: "Sistema completo de autenticación JWT con roles y permisos"
  category: "security"
  author: "MCP Backend Generator"
  license: "MIT"
  
triggers:
  - condition: "user_wants_auth"
    value: true
  - condition: "needs_login"
    value: true
  - condition: "requires_jwt"
    value: true
  - condition: "has_user_roles"
    value: true
  - condition: "mentions_authentication"
    keywords: ["login", "autenticación", "usuarios", "JWT", "auth", "sesión", "contraseña"]
    value: true

entry_points:
  main: "templates/auth.service.ts.hbs"
  middleware: "templates/auth.middleware.ts.hbs"
  strategy: "templates/jwt.strategy.ts.hbs"
  guards: "templates/roles.guard.ts.hbs"
  controller: "templates/auth.controller.ts.hbs"
  routes: "templates/auth.routes.ts.hbs"

dependencies:
  required:
    - "database"
    - "email"
  optional:
    - "logging"
    - "websockets"

environment_variables:
  required:
    - name: "JWT_SECRET"
      description: "Clave secreta para firmar tokens JWT"
      validation: "min:32"
    - name: "JWT_EXPIRES_IN"
      description: "Tiempo de expiración del token de acceso"
      default: "15m"
    - name: "JWT_REFRESH_EXPIRES_IN"
      description: "Tiempo de expiración del token de actualización"
      default: "30d"
  optional:
    - name: "JWT_ISSUER"
      description: "Emisor del token JWT"
    - name: "JWT_AUDIENCE"
      description: "Audiencia del token JWT"
    - name: "BCRYPT_ROUNDS"
      description: "Rondas de hash para bcrypt"
      default: "12"

features:
  - "login"
  - "register"
  - "refresh-tokens"
  - "email-verification"
  - "password-reset"
  - "role-based-access"
  - "permission-guards"
  - "audit-logging"
  - "rate-limiting"
  - "password-policies"

api:
  endpoints:
    - method: "POST"
      path: "/auth/login"
      summary: "Iniciar sesión"
      description: |
        Autentica un usuario con email y contraseña, retornando tokens JWT.
        
        Este endpoint valida las credenciales del usuario y genera tokens de acceso
        y actualización si la autenticación es exitosa.
      operationId: "loginUser"
      auth_required: false
      supportsPagination: false
      supportsSearch: false
      rateLimit:
        requests: 5
        window: "15 minutes"
      requestBody:
        required: true
        description: "Credenciales de usuario"
        schema:
          type: "object"
          required: ["email", "password"]
          properties:
            email:
              type: "string"
              format: "email"
              description: "Email del usuario"
              example: "usuario@ejemplo.com"
            password:
              type: "string"
              minLength: 8
              description: "Contraseña del usuario"
              example: "MiContraseña123!"
            rememberMe:
              type: "boolean"
              description: "Mantener sesión activa por más tiempo"
              default: false
        examples:
          loginRequest:
            summary: "Solicitud de login típica"
            value:
              email: "juan.perez@ejemplo.com"
              password: "MiContraseña123!"
              rememberMe: true
      responses:
        success:
          description: "Login exitoso"
          schema:
            type: "object"
            properties:
              success:
                type: "boolean"
                example: true
              message:
                type: "string"
                example: "Login exitoso"
              data:
                type: "object"
                properties:
                  user:
                    $ref: "#/components/schemas/User"
                  tokens:
                    type: "object"
                    properties:
                      accessToken:
                        type: "string"
                        description: "Token JWT de acceso"
                      refreshToken:
                        type: "string"
                        description: "Token para renovar el acceso"
                      expiresIn:
                        type: "integer"
                        description: "Tiempo de expiración en segundos"
          examples:
            loginSuccess:
              summary: "Respuesta exitosa de login"
              value:
                success: true
                message: "Login exitoso"
                data:
                  user:
                    id: "123e4567-e89b-12d3-a456-426614174000"
                    email: "juan.perez@ejemplo.com"
                    name: "Juan Pérez"
                    role: "employee"
                  tokens:
                    accessToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
                    refreshToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
                    expiresIn: 900
      useCases:
        - "Autenticación de usuarios en aplicaciones web"
        - "Login en aplicaciones móviles"
        - "Integración con sistemas de terceros"
      notes: |
        - Las contraseñas deben cumplir con la política de seguridad
        - Se aplica rate limiting para prevenir ataques de fuerza bruta
        - Los tokens tienen tiempo de expiración configurable
    
    - method: "POST"
      path: "/auth/register"
      summary: "Registrar nuevo usuario"
      description: |
        Registra un nuevo usuario en el sistema.
        
        Crea una nueva cuenta de usuario con validación de datos y envío
        de email de verificación si está habilitado.
      operationId: "registerUser"
      auth_required: false
      rateLimit:
        requests: 3
        window: "10 minutes"
      requestBody:
        required: true
        description: "Datos del nuevo usuario"
        schema:
          type: "object"
          required: ["email", "password", "name"]
          properties:
            email:
              type: "string"
              format: "email"
              description: "Email único del usuario"
            password:
              type: "string"
              minLength: 8
              description: "Contraseña que cumple políticas de seguridad"
            name:
              type: "string"
              minLength: 2
              maxLength: 100
              description: "Nombre completo del usuario"
            role:
              type: "string"
              enum: ["employee", "manager"]
              default: "employee"
              description: "Rol inicial del usuario"
      responses:
        success:
          description: "Usuario registrado exitosamente"
          schema:
            type: "object"
            properties:
              success:
                type: "boolean"
              message:
                type: "string"
              data:
                type: "object"
                properties:
                  user:
                    $ref: "#/components/schemas/User"
                  emailVerificationSent:
                    type: "boolean"
    
    - method: "POST"
      path: "/auth/refresh"
      summary: "Renovar tokens de acceso"
      description: |
        Renueva el token de acceso usando el refresh token.
        
        Permite mantener la sesión activa sin requerir login nuevamente.
      operationId: "refreshTokens"
      auth_required: true
      requestBody:
        required: true
        schema:
          type: "object"
          required: ["refreshToken"]
          properties:
            refreshToken:
              type: "string"
              description: "Token de actualización válido"
      responses:
        success:
          description: "Tokens renovados exitosamente"
          schema:
            type: "object"
            properties:
              success:
                type: "boolean"
              data:
                type: "object"
                properties:
                  accessToken:
                    type: "string"
                  refreshToken:
                    type: "string"
                  expiresIn:
                    type: "integer"
    
    - method: "POST"
      path: "/auth/logout"
      summary: "Cerrar sesión"
      description: "Invalida los tokens del usuario y cierra la sesión"
      operationId: "logoutUser"
      auth_required: true
      responses:
        success:
          description: "Sesión cerrada exitosamente"
          schema:
            $ref: "#/components/schemas/SuccessResponse"
    
    - method: "GET"
      path: "/auth/profile"
      summary: "Obtener perfil del usuario"
      description: "Retorna la información del perfil del usuario autenticado"
      operationId: "getUserProfile"
      auth_required: true
      responses:
        success:
          description: "Perfil del usuario"
          schema:
            type: "object"
            properties:
              success:
                type: "boolean"
              data:
                $ref: "#/components/schemas/User"
    
    - method: "PUT"
      path: "/auth/profile"
      summary: "Actualizar perfil del usuario"
      description: "Actualiza la información del perfil del usuario autenticado"
      operationId: "updateUserProfile"
      auth_required: true
      requestBody:
        required: true
        schema:
          type: "object"
          properties:
            name:
              type: "string"
              minLength: 2
              maxLength: 100
            email:
              type: "string"
              format: "email"
      responses:
        success:
          description: "Perfil actualizado exitosamente"
          schema:
            type: "object"
            properties:
              success:
                type: "boolean"
              data:
                $ref: "#/components/schemas/User"
  
  schemas:
    User:
      type: "object"
      properties:
        id:
          type: "string"
          format: "uuid"
          description: "ID único del usuario"
        email:
          type: "string"
          format: "email"
          description: "Email del usuario"
        name:
          type: "string"
          description: "Nombre completo del usuario"
        role:
          type: "string"
          enum: ["admin", "manager", "employee"]
          description: "Rol del usuario"
        emailVerified:
          type: "boolean"
          description: "Indica si el email está verificado"
        lastLoginAt:
          type: "string"
          format: "date-time"
          description: "Fecha del último login"
        createdAt:
          type: "string"
          format: "date-time"
          description: "Fecha de creación"
        updatedAt:
          type: "string"
          format: "date-time"
          description: "Fecha de última actualización"
      required: ["id", "email", "name", "role"]
      example:
        id: "123e4567-e89b-12d3-a456-426614174000"
        email: "juan.perez@ejemplo.com"
        name: "Juan Pérez"
        role: "employee"
        emailVerified: true
        lastLoginAt: "2024-01-15T10:30:00Z"
        createdAt: "2024-01-10T08:00:00Z"
        updatedAt: "2024-01-15T10:30:00Z"

generated_files:
  - "src/auth/auth.service.ts"
  - "src/auth/jwt.strategy.ts"
  - "src/auth/auth.middleware.ts"
  - "src/auth/roles.guard.ts"
  - "src/auth/auth.controller.ts"
  - "src/auth/auth.routes.ts"
  - "src/dtos/auth.dto.ts"
  - "src/types/auth.types.ts"

integration:
  database_tables:
    - name: "users"
      description: "Tabla principal de usuarios"
      required: true
    - name: "refresh_tokens"
      description: "Tokens de actualización"
      required: true
    - name: "password_resets"
      description: "Solicitudes de restablecimiento"
      required: true
    - name: "email_verifications"
      description: "Verificaciones de email"
      required: true
  email_templates:
    - "verify-email"
    - "reset-password"
    - "welcome"
    - "password-changed"

roles:
  default: "employee"
  available:
    - name: "admin"
      description: "Administrador del sistema"
      permissions: ["*"]
    - name: "manager"
      description: "Gerente con permisos limitados"
      permissions: ["read:*", "write:own", "manage:team"]
    - name: "employee"
      description: "Empleado básico"
      permissions: ["read:own", "write:own"]

security:
  password_policy:
    min_length: 8
    require_uppercase: true
    require_lowercase: true
    require_numbers: true
    require_symbols: true
    max_age_days: 90
  rate_limiting:
    login_attempts: 5
    window_minutes: 15
    lockout_minutes: 30
  session_management:
    max_concurrent_sessions: 3
    idle_timeout_minutes: 30

usage_examples:
  - title: "Simple JWT auth for API"
    description: "Autenticación básica con JWT para API REST"
    config:
      features: ["login", "register", "refresh-tokens"]
  - title: "Role-based access control"
    description: "Control de acceso basado en roles"
    config:
      features: ["login", "register", "role-based-access", "permission-guards"]
  - title: "Multi-tenant authentication"
    description: "Autenticación para aplicaciones multi-tenant"
    config:
      features: ["login", "register", "email-verification", "role-based-access"]
  - title: "Social login integration"
    description: "Integración con proveedores sociales"
    config:
      features: ["login", "register", "social-providers"]

ai_instructions: |
  Use este módulo cuando:
  - El usuario mencione "login", "autenticación", "JWT", "usuarios", "roles", "permisos"
  - El proyecto requiera gestión de usuarios
  - La API necesite endpoints protegidos
  - Se mencione seguridad o control de acceso
  
  Siempre combinar con:
  - Módulo database (para almacenamiento de usuarios)
  - Módulo email (para verificación y recuperación)
  
  Pasos de configuración:
  1. Verificar que JWT_SECRET esté configurado (mínimo 32 caracteres)
  2. Asegurar que el módulo database cree las tablas de usuarios
  3. Configurar templates de email para verificación
  4. Aplicar middleware de autenticación a rutas protegidas
  5. Configurar guards de roles según los permisos requeridos
  
  Consideraciones de seguridad:
  - Siempre usar HTTPS en producción
  - Configurar CORS apropiadamente
  - Implementar rate limiting para endpoints de autenticación
  - Usar contraseñas seguras y hash con bcrypt
  - Rotar secrets regularmente

automation:
  init_script: "init.js"
  actions:
    - "setup_jwt_configuration"
    - "create_auth_tables"
    - "generate_auth_endpoints"
    - "configure_middleware"
    - "setup_role_guards"
    - "return_auth_metadata"

testing:
  unit_tests:
    - "auth.service.test.ts"
    - "jwt.strategy.test.ts"
    - "roles.guard.test.ts"
  integration_tests:
    - "auth.integration.test.ts"
  e2e_tests:
    - "auth.e2e.test.ts"

metrics:
  performance:
    token_generation_time: "< 10ms"
    login_response_time: "< 200ms"
    password_hash_time: "< 100ms"
  security:
    password_strength_score: "> 80"
    token_entropy: "> 256 bits"
    session_security_level: "high"

compatibility:
  node_versions: [">= 18.0.0"]
  frameworks: ["express", "fastify", "koa"]
  databases: ["postgresql", "mysql", "mongodb"]
  email_providers: ["resend", "sendgrid", "nodemailer"]

documentation:
  readme: "README.md"
  api_docs: "api-documentation.md"
  security_guide: "security-guide.md"
  examples: "examples/"