Seguridad

Los errores de seguridad en plugins afectan a comerciantes reales y sus clientes. Sigue estas prácticas antes de enviar tu plugin a revisión.

1. Siempre verifica las firmas de webhook

Nunca proceses un webhook entrante sin verificar primero su firma HMAC. Un webhook no verificado puede ser reproducido o falsificado.

import { verifyWebhook } from "@whatalo/plugin-sdk/webhooks";

export async function POST(request: Request) {
  const payload = await request.text();
  const signature = request.headers.get("x-whatalo-hmac-sha256") ?? "";

  const isValid = verifyWebhook({ payload, signature, secret: process.env.WHATALO_CLIENT_SECRET! });
  if (!isValid) {
    return new Response("Invalid signature", { status: 401 });
  }

  // Safe to process payload here
}

Usa el verificador mejorado del template para protección contra repetición — rechaza solicitudes con una marca de tiempo fuera de una ventana de 300 segundos.

2. Protege tu client secret

Tu client secret autentica tu plugin ante la plataforma. Exponerlo es equivalente a entregar la identidad de tu plugin.

• Nunca guardes secretos en control de versiones
• Siempre usa variables de entorno: process.env.WHATALO_CLIENT_SECRET
• El template generado añade .env y .whatalo/ al .gitignore automáticamente
• Ejecuta whatalo validate regularmente — escanea tu proyecto en busca de secretos hardcodeados

3. Solicita los scopes mínimos necesarios

Solo declara los scopes de permisos que tu plugin realmente necesita en whatalo.app.ts. Solicitar permisos amplios cuando solo se necesita acceso limitado:

• Aumenta la superficie de riesgo si tu plugin es comprometido
• Es señalado durante el proceso de revisión

4. Valida toda la entrada

• Valida la estructura de los payloads de webhook antes de procesarlos
• Sanitiza cualquier dato externo antes de renderizarlo en tu UI
• No confíes en context.storeId para autorización del lado del servidor — siempre verifica el acceso mediante la API

5. Asegura tu endpoint de webhook

• Usa HTTPS en producción — nunca HTTP
• Implementa protección contra repetición (verifica marcas de tiempo de las solicitudes)
• Retorna códigos de estado HTTP apropiados: 200 para éxito, 4xx para errores del cliente, 500 para fallos inesperados

6. Maneja la expiración de tokens

El CLI maneja la renovación de tokens automáticamente durante el desarrollo. Para llamadas a la API del lado del servidor en producción:

• Maneja AuthenticationError (HTTP 401) de forma elegante
• Implementa lógica de reintento para fallos transitorios antes de mostrar un error al comerciante

7. No almacenes datos innecesarios del comerciante

• Obtén los datos del comerciante desde la API cuando sea necesario en lugar de almacenarlos en caché a largo plazo
• Si debes persistir datos, encríptalo en reposo
• Escucha el webhook app.uninstalled y elimina todos los datos del comerciante cuando un plugin sea removido