Invitaciones por correo¶

kubelatch puede enviar por correo, a través de Resend, los enlaces de un solo uso de una invitación o de un restablecimiento de acceso, en lugar de enseñártelos para que los copies. Esta página explica cómo preparar Resend, qué configurar en kubelatch, qué debes saber de seguridad y qué hacer cuando un correo no llega.

Qué hace¶

• Es una función Pro, también durante la prueba y el periodo de gracia. En Free la opción sale deshabilitada y marcada Pro; copiar el enlace sigue funcionando en todas las ediciones.
• Cubre los dos tipos de enlace que un administrador emite para una persona: la invitación de una cuenta nueva (72 horas) y el restablecimiento o enlace de vinculación de una existente (24 horas). Ver Usuarios y bots.
• Eliges cada vez entre enviar por correo y copiar el enlace. No las dos: con correo, kubelatch no te enseña nunca el enlace, así que solo existe una copia viva, en el buzón de la persona.
• El correo va solo a la dirección de la cuenta, nunca a una libre. El formulario nombra esa dirección antes de enviar, y la auditoría la registra.
• Si el correo no llega, lo reenvías o copias un enlace nuevo desde la fila o la ficha de la persona. Cualquiera de los dos anula el anterior.

Preparar Resend¶

1. Crea una cuenta de Resend y verifica el dominio de envío (los registros DNS que pide Resend). Envía desde un dominio que controles, como mail.example.com.
2. Crea una API key con el permiso Sending access, limitada a ese dominio. No uses una clave de acceso completo: si la clave se filtra, el daño se limita a correos desde ese dominio.
3. Mantén apagados el seguimiento de clics y el de aperturas en el dominio. Vienen apagados por defecto; déjalos así. El seguimiento reescribe los enlaces del mensaje para que pasen por el redireccionador de Resend, y el token de la invitación viajaría por los servidores de Resend.

kubelatch solo habla con https://api.resend.com: la dirección está fija y no se puede cambiar, y no hay SMTP.

Configurar kubelatch¶

Dos variables de entorno, listadas en Configuración:

Con el chart de Helm (Instalar):

• Pon mail.from en tus values; el chart lo convierte en KUBELATCH_MAIL_FROM.
• Pon la clave en el Secret: secrets.env.KUBELATCH_RESEND_API_KEY, o el campo KUBELATCH_RESEND_API_KEY de tu secrets.existingSecret.

mail:
  from: "kubelatch <noreply@example.com>"

Sin mail.from el chart no define nada y todo funciona como antes. Las variables solo se leen al arrancar: tras cambiarlas, reinicia los pods.

kubelatch las valida al arrancar. Una clave sin remitente, o un KUBELATCH_MAIL_FROM que no sea una dirección válida, impide arrancar el servidor, y el log dice qué valor está mal, como con cualquier otra variable errónea. La clave nunca aparece en logs, errores, base de datos ni API.

Con ambas puestas, el formulario de alta ofrece Enviar por correo, que es la opción por defecto. Con Pro pero sin Resend, la opción dice que falta configurar Resend en el servidor y enlaza aquí.

Notas de seguridad¶

• Resend guarda el contenido de lo que envía unos 30 días, y su panel lo muestra. Quien tenga acceso al panel de Resend de esa cuenta puede leer las invitaciones y los restablecimientos que aún no se han usado, y usarlos. Trata el acceso al panel como el poder de canjear invitaciones pendientes: dáselo a la menor gente posible, con el mismo cuidado que a una cuenta de administrador.
• Los enlaces mueren pronto. Valen una sola vez; una invitación dura 72 horas y un restablecimiento 24. Usarlo, emitir otro para la misma persona o dejarlo caducar lo termina, así que lo que queda en el historial de Resend deja de servir. Emitir un enlace nuevo, por correo o por copia, anula los pendientes.
• El token viaja en el fragmento de la URL (tras la #), que los navegadores nunca envían por HTTP. Los escáneres de correo que abren el enlace no lo consumen: solo lo hace la persona al pulsar el botón de la página.
• Límites por hora, para que una cuenta de administrador robada no use kubelatch como relé de spam: 3 correos por cuenta y 20 por administrador. Cuenta cada intento, también uno fallido. Pasados, la respuesta es 429 mail.rate_limited.
• El mensaje nombra a quien invita, el host real de tu kubelatch y la caducidad, pide comprobar que el enlace empieza por tu URL base y nunca solicita una contraseña. No lleva imágenes remotas ni seguimiento.
• Auditoría. Cada envío escribe link.email_sent (el propósito del enlace, la dirección y el id del mensaje en Resend) y cada fallo link.email_failed (con el estado HTTP que respondió Resend), junto al user.create o link.reset habitual, que también dice que la entrega fue por correo. Están en Auditoría y retención. Ninguno contiene el enlace ni el token.

Solución de problemas¶

Con 502 mail.failed y mail.failed_reset, el estado indica dónde mirar: 401 o 403 es una clave equivocada o demasiado limitada, o un remitente fuera del dominio verificado; 422 es una dirección que Resend rechaza; 429 es el límite de Resend; 5xx es Resend caído. El motivo está en link.email_failed, en «Auditoría».

El correo no llegó. kubelatch solo sabe que Resend lo aceptó. Busca el mensaje en el registro «Emails» de Resend: si dice entregado, el problema está en el lado de la persona (la carpeta de spam, una pasarela de filtrado); si dice rebotado, la dirección es errónea. Después reenvíalo («Reenviar invitación por correo» en la fila, o «Restablecer acceso» en la ficha de la cuenta) o «Copiar un enlace nuevo»; ambos anulan el anterior.