Probar on-prem localmente

Cómo correr y verificar el flujo on-prem (licencia → bootstrap → onboarding con tier → invitar usuarios) en tu máquina.

Qué necesita on-prem

Pieza	Dónde	Para qué
EDITION=onprem	env del deployment de Convex	tier desde la licencia, isBootstrapAvailable, single-tenant
VITE_EDITION=onprem	env del frontend	engancha el LicenseGate, rama on-prem
LICENSE_PUBLIC_KEY	env del deployment + embebida en lib/licensing/public-key.ts	verificar la firma del token
LICENSE_PRIVATE_KEY	solo para emitir tokens	firmar la licencia. NUNCA en el build on-prem
Token de licencia	lo pega el usuario en el LicenseGate	autoriza la instancia, define mods/seats

Precaución

El bootstrap (/setup) requiere base sin usuarios, y emitir desde /super/licenses requiere super_admin — ambas cosas chocan. Para el test local emitimos el token con un script (scripts/issue-test-license.ts).

Pasos

# 1. par de llaves (una vez)
npx tsx scripts/gen-license-keys.ts

# 2. backend del deployment de prueba
npx convex env set EDITION onprem
npx convex env set LICENSE_PUBLIC_KEY '<publica>'

# 3. embeber la pública en lib/licensing/public-key.ts (no commitear)

# 4. emitir un token de prueba
LICENSE_PRIVATE_KEY='<priv>' npx tsx scripts/issue-test-license.ts \
  --mods clients,sales --seats 2 --cust "Demo SA"

# 5. correr en modo on-prem
VITE_EDITION=onprem bun run dev

Activar + omitir el heartbeat (solo dev)

Pegá el token en el LicenseGate. En dev, fetch("/license/heartbeat") es relativo a localhost:3000 y no llega a Convex, así que hay que omitir el heartbeat desde la consola del browser:

localStorage.setItem(
  "heskala.license.lastHeartbeatOkAt",
  String(Math.floor(Date.now() / 1000)),
);
location.reload();

Verificar

• Bootstrap: base vacía → /setup (crear primer admin).
• Onboarding: crea la empresa con el tier de la licencia (enabledModules = mods, maxUsers = seats, lifetime).
• Tier en la UI: el sidebar muestra solo los módulos del tier; URL a un módulo fuera → “módulo no incluido”.
• Seats: crear usuarios hasta el límite; el siguiente queda bloqueado.
• Invitar sin SMTP: el dialog muestra un link /activate?token=....

Limpieza

git checkout lib/licensing/public-key.ts
npx convex env remove EDITION   # si usaste el deployment dev compartido

Caveats

• El heartbeat no funciona en dev (URL relativa) → de ahí el bypass.
• El token del script no crea registro en licenses → un heartbeat real lo rechazaría. Para validar heartbeat end-to-end, emitir desde /super/licenses.