Validación de Entradas en GraphQL: Estrategias Robustas para Proteger tus APIs

La validación de entradas es una capa fundamental de seguridad y calidad en cualquier API, y GraphQL no es la excepción. Una API GraphQL bien diseñada no solo debe ser flexible y eficiente, sino también resistente a datos malformados o maliciosos.

En este tutorial, cubriremos por qué la validación es crucial, las diferentes capas donde se puede aplicar, y cómo implementarla de manera efectiva utilizando herramientas y patrones comunes en el ecosistema GraphQL.

🎯 ¿Por Qué la Validación de Entradas es Crucial en GraphQL?

Aunque GraphQL ofrece tipado fuerte en su esquema, esto solo garantiza que los datos coincidan con el tipo esperado (por ejemplo, un String será una cadena). No garantiza que la cadena tenga una longitud mínima, que un número esté dentro de un rango específico, que un email sea válido o que una URL sea funcional. Aquí es donde entra en juego la validación de entradas.

Beneficios Clave de una Buena Validación:

• Seguridad: Previene ataques como inyección SQL, XSS, o el envío de datos maliciosos que puedan explotar vulnerabilidades.
• Integridad de Datos: Asegura que solo datos válidos y coherentes entren en tu base de datos o sistemas de backend.
• Estabilidad del Sistema: Evita errores inesperados en la lógica de negocio o en las operaciones de la base de datos causados por entradas inválidas.
• Experiencia del Desarrollador: Facilita el desarrollo frontend al tener una API predecible y que devuelve errores útiles.
• Experiencia del Usuario: Proporciona mensajes de error claros y específicos que permiten a los usuarios corregir sus entradas rápidamente.

📖 Capas de Validación en GraphQL

Podemos aplicar la validación en varias capas de nuestra arquitectura GraphQL, cada una con su propósito y ventajas.

1. Validación a Nivel de Esquema (Schema-Level Validation)

Esta es la primera línea de defensa y se realiza antes de que la ejecución llegue a tus resolvers. El propio motor de GraphQL ya realiza una validación básica de tipos. Por ejemplo, si tu esquema espera un Int y recibes un String, GraphQL lo detectará automáticamente.

type User {
  id: ID!
  name: String!
  email: String!
  age: Int
}

type Mutation {
  createUser(name: String!, email: String!, age: Int): User
}

En este ejemplo, si createUser recibe age: "veinte", GraphQL generará un error de tipo antes de invocar el resolver.

Limitaciones:

Esta validación es limitada a los tipos escalares estándar. No puede validar la semántica de los datos, como la longitud de una cadena, el formato de un email o el rango de un número.

2. Validación a Nivel de Resolver (Resolver-Level Validation)

Aquí es donde la mayoría de la lógica de validación semántica reside. Antes de que un resolver interactúe con la lógica de negocio o la base de datos, se pueden aplicar reglas personalizadas a los argumentos de entrada.

// Ejemplo de un resolver con validación básica
const resolvers = {
  Mutation: {
    createUser: (parent, { name, email, age }) => {
      if (!name || name.length < 3) {
        throw new Error('El nombre debe tener al menos 3 caracteres.');
      }
      if (!/\[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/.test(email)) {
        throw new Error('Formato de email inválido.');
      }
      if (age !== undefined && (age < 0 || age > 120)) {
        throw new Error('La edad debe estar entre 0 y 120.');
      }
      // Lógica para crear el usuario...
      return { id: '1', name, email, age };
    },
  },
};

3. Validación con Middleware o Directivas Personalizadas

Para evitar la repetición de código de validación en múltiples resolvers, podemos centralizarla usando middleware (si tu servidor GraphQL lo permite, como express-graphql o Apollo Server) o, más idiomáticamente en GraphQL, a través de directivas personalizadas.

Las directivas personalizadas permiten agregar lógica reutilizable a tu esquema de forma declarativa, aplicando validaciones a campos o argumentos directamente en la definición del esquema.

🛠️ Implementando Validación Robusta con Directivas

Las directivas son una herramienta poderosa para añadir funcionalidades transversales a tu esquema GraphQL. Podemos definir directivas como @validateEmail o @minStringLength(value: 5) y aplicarlas a los argumentos de nuestros campos.

Paso 1: Definir la Directiva en el Esquema

Primero, necesitas definir la directiva y sus argumentos en tu schema.graphql (o donde definas tu esquema).

directive @constraint(minLength: Int, maxLength: Int, format: String, pattern: String, min: Int, max: Int) on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION

type Mutation {
  createUser(
    name: String! @constraint(minLength: 3, maxLength: 50),
    email: String! @constraint(format: "email"),
    age: Int @constraint(min: 0, max: 120)
  ): User
}

Aquí, @constraint es una directiva genérica que puede recibir varios argumentos para diferentes tipos de validación. La declaración on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION especifica dónde se puede usar esta directiva.

Paso 2: Implementar la Lógica de la Directiva

Para que la directiva funcione, necesitamos implementarla en nuestro servidor GraphQL. Esto generalmente implica transformar el esquema (schema transformation) o usar un wrapper de resolver.

Usaremos un enfoque de transformación de esquema, lo que significa que interceptaremos la ejecución de los resolvers en los campos donde se aplica la directiva.

// Este es un ejemplo conceptual. La implementación real varía según la librería.
import { mapSchema, get}; from '@graphql-tools/utils';
import { ApolloServer, gql } from 'apollo-server';

const typeDefs = gql`
  directive @constraint(minLength: Int, maxLength: Int, format: String, pattern: String, min: Int, max: Int) on ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION

  type User {
    id: ID!
    name: String!
    email: String!
    age: Int
  }

  type Query {
    users: [User]
  }

  type Mutation {
    createUser(
      name: String! @constraint(minLength: 3, maxLength: 50),
      email: String! @constraint(format: "email"),
      age: Int @constraint(min: 0, max: 120)
    ): User
  }
`;

function applyConstraintDirective(schema) {
  return mapSchema(schema, {
    // Esto intercepta cada campo del esquema
    [MapperKind.FIELD]: (fieldConfig) => {
      // Obtener las directivas aplicadas al campo o a sus argumentos
      const constraintDirectives = getDirective(schema, fieldConfig, 'constraint');

      if (constraintDirectives) {
        const { resolve = defaultFieldResolver } = fieldConfig;

        // Crear un nuevo resolver que envuelve el original
        fieldConfig.resolve = async function (source, args, context, info) {
          // Aquí se itera sobre los argumentos y se aplica la lógica de validación
          for (const argName in args) {
            const argValue = args[argName];
            const argType = fieldConfig.args.find(a => a.name === argName);
            const argDirectives = getDirective(schema, argType, 'constraint');

            if (argDirectives && argDirectives.length > 0) {
              const constraints = argDirectives[0]; // Asumiendo una única directiva @constraint por argumento

              // Lógica de validación basada en los argumentos de la directiva
              if (constraints.minLength && String(argValue).length < constraints.minLength) {
                throw new Error(`El campo ${argName} debe tener al menos ${constraints.minLength} caracteres.`);
              }
              if (constraints.maxLength && String(argValue).length > constraints.maxLength) {
                throw new Error(`El campo ${argName} debe tener como máximo ${constraints.maxLength} caracteres.`);
              }
              if (constraints.format === 'email' && !/^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/.test(argValue)) {
                throw new Error(`El campo ${argName} tiene un formato de email inválido.`);
              }
              if (constraints.min && argValue < constraints.min) {
                throw new Error(`El campo ${argName} debe ser mayor o igual a ${constraints.min}.`);
              }
              if (constraints.max && argValue > constraints.max) {
                throw new Error(`El campo ${argName} debe ser menor o igual a ${constraints.max}.`);
              }
              // ... otras validaciones
            }
          }
          return resolve(source, args, context, info);
        };
      }
      return fieldConfig;
    },
  });
}

// Para usarlo con Apollo Server
const schema = makeExecutableSchema({ typeDefs, resolvers });
const schemaWithDirectives = applyConstraintDirective(schema);

const server = new ApolloServer({ schema: schemaWithDirectives });
// ... iniciar el servidor

Este patrón permite centralizar la lógica de validación, haciéndola reutilizable y más fácil de mantener.

📦 Librerías de Validación en GraphQL

Existen librerías que simplifican enormemente la implementación de validaciones más complejas, especialmente aquellas que requieren expresiones regulares o reglas de negocio sofisticadas.

1. yup o joi para Validación de Esquemas

Aunque no son específicas de GraphQL, librerías como yup (o joi en Node.js) son excelentes para definir esquemas de validación de objetos de entrada. Puedes integrarlas en tus resolvers o incluso en la lógica de tus directivas.

import * as yup from 'yup';

const userSchema = yup.object().shape({
  name: yup.string().min(3).max(50).required('El nombre es obligatorio y debe tener entre 3 y 50 caracteres.'),
  email: yup.string().email('Formato de email inválido.').required('El email es obligatorio.'),
  age: yup.number().integer('La edad debe ser un número entero.').min(0).max(120).nullable(true),
});

const resolvers = {
  Mutation: {
    createUser: async (parent, args) => {
      try {
        // Validar los argumentos con el esquema de yup
        const validatedArgs = await userSchema.validate(args, { abortEarly: false });
        // abortEarly: false para obtener todos los errores de validación a la vez

        // Lógica para crear el usuario con validatedArgs
        return { id: '2', ...validatedArgs };
      } catch (validationError) {
        // Manejar los errores de validación
        throw new Error(validationError.errors.join(', '));
      }
    },
  },
};

2. graphql-middleware (para express-graphql y apollo-server anteriores)

Si utilizas un middleware como express-graphql o versiones anteriores de Apollo Server que no soportan directivas de manera tan nativa, graphql-middleware puede ser una opción para aplicar lógica de validación de forma global o por campo.

// Ejemplo conceptual con graphql-middleware
import { applyMiddleware } from 'graphql-middleware';

const validationMiddleware = async (resolve, root, args, context, info) => {
  if (info.fieldName === 'createUser') {
    // Lógica de validación específica para createUser
    if (args.name.length < 3) {
      throw new Error('Name too short!');
    }
  }
  return resolve(root, args, context, info);
};

const schema = buildSchema(`...
`); // Tu esquema
const resolvers = { /* ... */ };

const schemaWithMiddleware = applyMiddleware(schema, validationMiddleware);

// Usar schemaWithMiddleware en tu servidor GraphQL

📝 Manejo de Errores de Validación

Una parte crucial de la validación es cómo se comunican los errores al cliente. GraphQL tiene un formato de respuesta de error estándar (errors array), pero podemos mejorarlo.

Errores Estándar de GraphQL

Cuando se lanza un Error en un resolver o una directiva, GraphQL lo captura y lo incluye en el array errors de la respuesta.

{
  "errors": [
    {
      "message": "El nombre debe tener al menos 3 caracteres.",
      "locations": [ { "line": 3, "column": 5 } ],
      "path": [ "createUser" ]
    }
  ],
  "data": null
}

Errores Personalizados con extensions

Para proporcionar más contexto o estructurar los errores de validación de forma que el frontend pueda procesarlos programáticamente, puedes usar la propiedad extensions del objeto GraphQLError.

import { GraphQLError } from 'graphql';

const resolvers = {
  Mutation: {
    createUser: (parent, { name, email }) => {
      const errors = [];

      if (!name || name.length < 3) {
        errors.push({ field: 'name', message: 'El nombre debe tener al menos 3 caracteres.' });
      }
      if (!/^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/.test(email)) {
        errors.push({ field: 'email', message: 'Formato de email inválido.' });
      }

      if (errors.length > 0) {
        throw new GraphQLError('Errores de validación', {
          extensions: {
            code: 'BAD_USER_INPUT',
            errors: errors,
          },
        });
      }
      // ...
      return { id: '3', name, email };
    },
  },
};

La respuesta ahora podría verse así:

{
  "errors": [
    {
      "message": "Errores de validación",
      "locations": [ { "line": 3, "column": 5 } ],
      "path": [ "createUser" ],
      "extensions": {
        "code": "BAD_USER_INPUT",
        "errors": [
          { "field": "name", "message": "El nombre debe tener al menos 3 caracteres." },
          { "field": "email", "message": "Formato de email inválido." }
        ]
      }
    }
  ],
  "data": null
}

Este enfoque permite al cliente identificar rápidamente qué campos tienen errores y mostrar mensajes apropiados.

Tipos de Errores en el Esquema (Uniones o Interfaces)

Para un manejo de errores aún más explícito, puedes definir tipos de error en tu esquema GraphQL. Por ejemplo, un tipo CreateUserPayload que puede ser User o InvalidInputError.

type InvalidInputError {
  field: String!
  message: String!
}

union CreateUserResult = User | InvalidInputError

type Mutation {
  createUser(input: CreateUserInput!): CreateUserResult
}

Esto requiere una lógica más compleja en el resolver para devolver el tipo correcto, pero ofrece una experiencia de tipado robusta para el cliente GraphQL.

✅ Buenas Prácticas y Consideraciones Adicionales

1. Fallo Temprano, Fallo Rápido (Fail Fast)

Aplica las validaciones tan pronto como sea posible en el ciclo de vida de la solicitud. Esto evita que recursos computacionales se gasten en procesar datos inválidos.

2. Agrupa los Errores de Validación

Siempre que sea posible, recopila y devuelve todos los errores de validación de una entrada, en lugar de detenerte en el primer error. Esto mejora la experiencia del usuario, ya que puede corregir múltiples problemas a la vez.

3. Evita la Lógica de Negocio en la Validación

La validación de entrada debe centrarse en la forma y la estructura de los datos. Las reglas de negocio que dependen del estado actual de tu sistema (ej. "el usuario no puede comprar más de 5 artículos si ya tiene una suscripción premium") pertenecen a la lógica de negocio después de la validación de entrada.

4. Reutiliza la Lógica de Validación

Si tienes validaciones complejas que se aplican en varios lugares (por ejemplo, validar un email en createUser y updateUser), asegúrate de que la lógica esté centralizada y sea reutilizable, ya sea a través de directivas, funciones de utilidad o librerías de validación.

5. Documenta tus Validaciones

Usa comentarios en tu esquema GraphQL y en la documentación de tu API para describir las reglas de validación de cada campo. Esto ayuda a los desarrolladores frontend a construir formularios correctos desde el principio.

"Representa la edad de un usuario, debe estar entre 0 y 120 años." 
age: Int @constraint(min: 0, max: 120)

💡 Conclusión

La validación de entradas es un componente innegociable para construir APIs GraphQL robustas, seguras y amigables para el usuario y el desarrollador. Al integrar la validación en múltiples capas (esquema, resolvers, directivas) y al manejar los errores de forma efectiva, puedes garantizar la integridad de tus datos y la estabilidad de tu aplicación.

Recuerda que la clave está en el equilibrio: validar lo suficiente para proteger tu API, pero sin sobrecomplicar la lógica o penalizar el rendimiento.