API routes

EMA Vault expone 44 módulos API bajo el worker Hono, organizados por dominio operativo (negocio, finanzas, producto, sistema) y con verificación de permisos a nivel módulo vía canRead y canWrite. La autorización se aplica en cada handler en lugar de a través de una decorator global, lo que permite que cada endpoint declare su propio set de roles permitidos sin acoplar el resto del módulo. Cuatro layers de autenticación cubren los contextos posibles —staff con JWT Supabase, llamadas worker-a-worker con header de plataforma, webhooks de GitHub con HMAC, y rutas explícitamente públicas— y los cinco roles RBAC distribuyen los permisos sobre el resto.

Nota

La fuente de verdad es src/index.ts + cada src/api/{resource}.ts. Este resumen se mantiene sincronizado.

Auth layers

Layer	Cómo funciona	Mounting
public	Sin credenciales	rutas explícitas antes de authMiddleware
supabase	JWT Supabase + vault_users.is_active=true	app.use("/api/*", authMiddleware)
platform-key	Header X-Platform-Key	mount antes de authMiddleware
webhook-sig	HMAC verification (/api/github/webhook)	mount antes de authMiddleware

Roles RBAC

Rol	Bypass	Módulos default
admin	Sí — bypass todos los checks	Todo
technical	No	producto, infra, audit, wiki, equipo
commercial	No	pipeline, contratos, directorio, catálogo, pricing
finance	No	finanzas, facturación electrónica, MRR, obligaciones
viewer	No	lectura limitada

Tabla vault_permissions(role, module, can_read, can_write) — admin configura granular.

Endpoints públicos (sin auth)

Método	Path	Notas
GET	/api/health	Liveness probe
GET	/api/config	Bootstrap: Supabase URL + anon key
GET	/auth/me	(con JWT — retorna user + permissions)
GET	/auth/callback	OAuth Google redirect
POST	/api/github/webhook	HMAC verified — sync issues
POST	/api/internal/tenants	X-Platform-Key — endpoint interno reservado

Módulos por dominio

Negocio · Pipeline + leads

Módulo	Path	Rol mínimo
Pipeline / Leads	/api/leads/* · /api/pipeline/*	commercial, admin
Assessments	/api/assessments/*	commercial, admin
Lead-EMI conversations	/api/lead-emi-conversations/*	commercial, admin

Negocio · Clientes y directorio

Módulo	Path	Rol mínimo
Tenants (clientes)	/api/tenants/*	commercial, finance, admin
Provisioning	POST /api/tenants/:id/provision	admin
Clientes (DEPRECATED)	/api/clients/*	redirige a tenants
Organizations	/api/organizations/*	commercial, admin
Directorio (people)	/api/directory/*	commercial, admin
Equipo Vault	/api/vault-team/*	admin

Negocio · Contratos y pricing

Módulo	Path	Rol mínimo
Contratos	/api/contracts/*	commercial, finance, admin
Catálogo	/api/catalog/*	commercial, admin
Catálogo costos	/api/catalog/costs/*	finance, admin
Catálogo pricing	/api/catalog/pricing/*	finance, admin
Productos catalog	/api/products-catalog/*	commercial, admin
Pricing tool	/api/pricing-tool/*	commercial, finance, admin

Finanzas

Módulo	Path	Rol mínimo
Finance entries	/api/finance/*	finance, admin
Invoices (interna)	/api/invoices/*	finance, admin
Fiscal config (facturación electrónica)	/api/fiscal/*	finance, admin
MRR	/api/mrr/*	finance, admin
Exchange rates	/api/exchange/*	finance, admin
Obligaciones	/api/obligations/*	finance, admin

Producto

Módulo	Path	Rol mínimo
Productos (catálogo)	/api/products/*	technical, admin
Cross-product	GET /api/products/cross/issues GET /api/products/cross/recent	technical, admin
Producto sub-pages	/api/products/:slug/*	technical, admin
GitHub sync	/api/products/:slug/github-sync	technical, admin
Releases	/api/products/:slug/releases/*	technical, admin
Roadmap	/api/products/:slug/layers/*	technical, admin
Tech stack	/api/products/:slug/tech-stack/*	technical, admin
Quality	/api/quality/*	technical, admin

Editorial y conocimiento

Módulo	Path	Rol mínimo
Editorial posts	/api/editorial/*	commercial, admin
Wiki	/api/wiki/*	technical, admin
Documentos	/api/documents/*	technical, admin
Brand	/api/brand/*	commercial, admin

Operaciones

Módulo	Path	Rol mínimo
Checklist	/api/checklist/*	admin, technical
Time tracking	/api/time/*	technical, admin
Notifications	/api/notifications/*	(todos)
Infra	/api/infra/*	technical, admin
Dashboard	/api/dashboard/*	(todos — read-only)
KPIs	/api/kpis/*	(todos — read-only)
Análisis	/api/analysis/*	admin, technical
Changelog	/api/changelog/*	technical, admin

Sistema

Módulo	Path	Rol mínimo
Audit log	/api/audit/*	admin
Vault permissions	/api/vault-permissions/*	admin
Vault roles	/api/vault-roles/*	admin

EMI

Módulo	Path	Rol mínimo
EMI proxy chat	POST /api/emi/chat	(todos) — auditado
EMI access check	GET /api/emi/access	(todos)
EMI access admin	/api/emi-access/*	admin
EMI analytics	/api/emi-analytics/*	admin

AI (Anthropic)

Módulo	Path	Rol mínimo
AI proposal	POST /api/ai/proposal	commercial, admin
AI contract summary	POST /api/ai/contract	commercial, finance, admin
AI summary	POST /api/ai/summary	(todos con write en módulo origen)

Ema Well

Módulo	Path	Rol mínimo
Well metrics overview	GET /api/well/metrics/overview	(todos read)
Well metrics retention	GET /api/well/metrics/retention	(todos read)
Well metrics streaks	GET /api/well/metrics/streaks	(todos read)
Well metrics pillars	GET /api/well/metrics/pillars	(todos read)
Well metrics daily	GET /api/well/metrics/daily	(todos read)

Patrón helpers

apiFetch<T>(path, opts)

Helper en src/client/lib/api.ts que retorna JSON parseado directamente:

const tenants = await apiFetch<Tenant[]>('/api/tenants');
// tenants es Tenant[] directamente, no Response

canRead(module: string): boolean

Helper en src/client/lib/auth.ts:

import { canRead, canWrite } from '../lib/auth';

if (canRead('finance')) {
  // mostrar módulo
}

Filtra navItems del sidebar dinámicamente.

Reglas de oro al agregar endpoint

1. Mount order matters: rutas públicas ANTES de authMiddleware en index.ts. Cross-product /cross/* ANTES de /:slug/*.
2. Permisos en handler: usar canRead(c, 'module') / canWrite(c, 'module') desde el contexto.
3. Audit log para mutations críticas — el audit_trigger() SQL cubre 12 tablas, pero para acciones cross-product (provisioning) loggear manual en /api/audit/*.
4. CSP whitelist — si llamás a un dominio externo nuevo, actualizar connect-src en security-headers.ts.
5. Rate limiting — Vault es internal, no implementa rate-limit per-user (asume staff trusted). Aplicar solo a endpoints públicos (/api/github/webhook).

Cómo verificar

# Listar todos los routes mounted
grep -n "app.route" src/index.ts

# Verificar canRead/canWrite usage
grep -rn "canRead\|canWrite" src/api/

# Ver módulos en vault_permissions
SELECT DISTINCT module FROM emavault.vault_permissions ORDER BY module;