Preparar el receptor firmado

Vamos a preparar el receptor provisto en app/api/github/route.ts sobre la branch development. Usá el editor del host en lab y Hermes CLI dentro de lab-agent, en /workspace. Antes de empezar necesitás la sesión de GitHub del agente y el bind mount escribible.

Acá aparece otra credencial, con una tarea distinta del PAT. El PAT autoriza a gh a usar la API de GitHub. El secret es un valor privado que comparten GitHub y este receptor para comprobar la firma de las entregas entrantes. HMAC-SHA256 calcula esa firma usando el secret y el body. Verificarla permite detectar cambios en el body y comprobar que lo firmó alguien que conoce el secret. No cifra el contenido ni decide qué repositorios o eventos vas a atender.

El receptor corre en el runtime Node y compara las firmas con timingSafeEqual, para evitar que el tiempo de comparación revele en qué posición difieren. Para calcular la firma necesita los bytes originales, antes de interpretar el JSON. Si leyeras los datos y volvieras a serializarlos, podrían cambiar los espacios o el orden de las claves. Aunque los datos significaran lo mismo, esos bytes distintos invalidarían la firma.

GitHub y el receptor calculan HMAC-SHA256 sobre los mismos bytes con el mismo secret

El diagrama del taller es conceptual. Para que las firmas coincidan, ambos extremos deben usar el mismo secret.

al recibir POST:
  leer bytes con límite de tamaño
  verificar HMAC con el secret
  interpretar JSON y validar el repo
  filtrar los eventos permitidos
  detectar una entrega repetida
  registrar metadata y responder

El código provisto limita el body a 128 KiB, exige application/json, valida el repo y el delivery ID, permite ping y pull_request y registra sólo metadata acotada. También recuerda entregas para no procesarlas dos veces. Guarda como máximo 1000 IDs durante una hora en la memoria de una instancia, y pierde ese estado al reiniciar. No es una cola durable ni protección completa contra replay.

Fijate que la firma y los filtros responden preguntas distintas. Que el body diga contener tu repo no prueba su origen, por eso primero verificamos HMAC. Después, los filtros de repo y evento deciden si ese aviso válido corresponde al trabajo permitido. No reemplaces una comprobación por la otra.

Para preparar la configuración, elegí una de las dos formas siguientes. No ejecutes ambas pisando variables existentes.

Delegar a Hermes

Si elegís delegarlo, abrí Hermes dentro de la shell del agente, en /workspace:

hermes chat

El siguiente bloque es un prompt para Hermes, no un comando Bash. Reemplazá sólo el repo con el tuyo:

Revisá app/api/github/route.ts de este proyecto.
Adaptalo sólo si hace falta para este backend.
Usá TU_USUARIO/REPO como repositorio permitido.
Prepará .env.local sin pisar variables existentes, sin imprimir ni versionar secretos.
Generá un secret aleatorio de al menos 32 bytes con crypto u openssl y guardalo allí.
Configurá WEBHOOK_SECRET y GITHUB_WEBHOOK_REPO.
Conservá las validaciones y no actives ninguna llamada a IA.
No imprimas secretos ni hagas push.
Mostrame un resumen sin credenciales, qué cambió y cómo comprobarlo.

El bind mount permite escribir .env.local en el proyecto que usa lab-app. Hermes no tiene el socket Docker y no puede reiniciar otros containers. No se lo concedas para evitar un paso humano.

Alternativa manual: mismo resultado, sin delegar

Si preferís hacerlo a mano y .env.local no existe, copiá .env.example a .env.local. Si ya existe, editá sólo las dos claves necesarias y conservá las demás variables. Generá el valor en una terminal privada, no proyectada, porque el siguiente comando lo imprime:

openssl rand -hex 32

El resultado es un secret nuevo. Pegalo sólo en WEBHOOK_SECRET dentro del archivo privado y completá GITHUB_WEBHOOK_REPO con tu owner/repo. Nunca copies el valor a esta guía, un chat o un commit.

Con cualquiera de las dos opciones terminada, volvé al host, en la carpeta lab. Vamos a comprobar la exclusión y los cambios sin mostrar el contenido del archivo:

git check-ignore .env.local
git status --short
git diff -- app/api/github/route.ts

Buscá que git check-ignore identifique .env.local y que el resumen confirme las dos claves sin revelar valores. Revisá el diff para comprobar que conserva firma, límites y filtros, y que ningún paso añade IA. No sigas si el secret aparece en archivos versionados, .env.local no está ignorado o se eliminaron validaciones. Si hubo exposición, revocá o rotá la credencial antes de continuar.

Referencia: validar entregas de GitHub.