Proyectos, entornos y releases
Esta API interna permite preparar aplicaciones desplegables sin alterar el catálogo DSL ni publicar infraestructura. Sus rutas operativas requieren sesión de usuario de plataforma y membresía OWNER/ADMIN vigente en la empresa activa. La promoción directa requiere el principal OAuth confidencial de Nimo y el scope nimo:application-projects:promote; un JWT USER recibe 403. La SPA promociona mediante el BFF cookie-only. La asignación permanece shareable=false y publicSafe=false; no se expone a claves API, clientes app, SDK público, MCP externo ni chat embebible.
| Método | Ruta | Entrada | Resultado |
|---|---|---|---|
| GET | /app-projects?page=1&limit=20 | page ≥ 1; limit 1–100 (defecto 20) | 200: { data, total, page, limit }, proyectos de la empresa activa |
| POST | /app-projects | { name, sourceType: "dsl", applicationRef } o { name, sourceType: "git-static" } | 201: proyecto; crea preview y production con configuración revisión 1 y namespaces diferentes |
| POST | /app-projects/:id/releases | DSL: { sourceVersion: 1 }; Git: { commitSha: "<SHA completo de 40/64 hex>" } | 201: release con snapshot, hash y versión del formato |
| POST | /app-projects/:projectId/releases/:releaseId/artifact | Sin body | Compila bundle DSL inmutable; exige OWNER/ADMIN vigente. sourceHash permanece separado de artifactHash |
| GET | /app-projects/:projectId/releases/:releaseId/artifact | UUIDs de proyecto y release | Manifiesto y URL de artefacto; exige OWNER/ADMIN vigente |
| GET | /app-projects/:id/environments | UUID de proyecto | 200: entornos con configRevision, releaseGeneration, dataNamespace, currentRelease |
| GET | /app-projects/:projectId/environments/:environmentId/connections | UUIDs de proyecto y entorno | Cuatro políticas y diagnóstico; nunca devuelve credenciales |
| PUT | /app-projects/:projectId/environments/:environmentId/connections | expectedRevision y política para payment/email/push/webhook | Nueva revisión con referencias a providers tenant activos. Preview rechaza conexiones productivas; sandbox sin adapter y push/webhook fallan 422 sin escribir; revisión obsoleta: 409 |
| GET | /app-projects/:projectId/environments/:environmentId/runtime-origins | UUIDs de proyecto y entorno | Lista de orígenes exactos activos y retirados |
| POST | /app-projects/:projectId/environments/:environmentId/runtime-origins | { origin } | Registra HTTPS exacto (localhost/loopback HTTP solo en desarrollo); sin wildcard, credenciales, ruta, query o fragmento |
| DELETE | /app-projects/:projectId/environments/:environmentId/runtime-origins/:originId | UUIDs de proyecto, entorno y origen | Retira el origen y deniega inmediatamente sesiones enlazadas |
| POST | /app-projects/:projectId/environments/:environmentId/runtime-sessions | { originId, expiresInSeconds?: 60..3600 } | Emite una sola vez una credencial opaca nrs_… con 15 min por defecto, ligada a usuario/app/empresa/proyecto/entorno/release/origen |
| DELETE | /app-projects/runtime-sessions/:id | UUID de sesión del usuario actual | Revocación inmediata; el siguiente request devuelve 401 |
| POST | /app-operations | Idempotency-Key + { projectId, environmentId, releaseId, operationType: deployment|hosting-migration|hosting-rollback, expectedGeneration } | 201: operationId persistido antes de dispatch; migración/rollback solo sobre el release vigente; clave repetida con misma entrada devuelve la operación, entrada diferente: 409 |
| POST | /app-environments/:id/promotions | OAuth interno Nimo con scope nimo:application-projects:promote; payload de promoción | 201: activa el release probado en Preview; JWT USER normal: 403; revisión obsoleta u operación activa: 409 |
| GET | /app-operations/:id | UUID de operación | 200: estado y evidencia saneada de la empresa activa; otra empresa/inexistente: 404 |
| POST | /app-operations/:id/cancel | UUID de operación | 200: cancelada; operación terminada: 409 |
Las operaciones requieren usuario de plataforma con membresía OWNER/ADMIN vigente y no están expuestas a SDK público, MCP externo ni chat embebido. La tabla durable conserva la operación si el proceso se reinicia; una clave de idempotencia no puede reutilizarse con otra entrada. Migración y rollback guardan una instantánea de release, ruta, revisión de configuración y namespace de datos. Si alguno cambia antes del corte, la operación falla sin cambiar la ruta activa. WfP nunca ejecuta código de cliente y los JWT temporales de assets no se guardan en la operación.
BFF cookie-only para promoción de Nimo
Estas rutas no forman parte del OpenAPI ni de los SDK públicos. Requieren el Origin exacto de NIMO_INTERNAL_BFF_ORIGIN y cookie host-only __Secure-nimo_bff_session con Secure, HttpOnly, SameSite=Lax, Path=/ai/internal/bff y TTL de 15 minutos. El login valida contraseña y membresía OWNER/ADMIN activa. No emite JWT ni OAuth bearer. Cada mutación usa X-Nimo-CSRF-Token; la membresía se revalida en cada request y logout o rotación revoca la sesión anterior.
| Método | Ruta | Entrada / headers | Resultado |
|---|---|---|---|
| POST | /ai/internal/bff/session | Origin; { username, password, companyId } | Cookie BFF y { csrfToken, expiresAt, user }; error credenciales: 401 |
| POST | /ai/internal/bff/session/bootstrap | Cookie + Origin | Renueva CSRF para la sesión; sesión inválida/expirada/replay: 401 |
| POST | /ai/internal/bff/session/rotate | Cookie + Origin + X-Nimo-CSRF-Token | Rota la sesión opaca; la anterior se revoca |
| POST | /ai/internal/bff/session/logout | Cookie + Origin + X-Nimo-CSRF-Token | Revoca sesión y limpia cookie; 204 |
| POST | /ai/internal/bff/promotions/environments/:environmentId | Cookie + Origin + X-Nimo-CSRF-Token; payload de promoción | 201: mismo servicio de promoción con revalidación OWNER/ADMIN live |
El BFF es una frontera first-party de navegador. Un cliente que ya posea las credenciales de un OWNER/ADMIN aún puede autenticarse a las rutas API ordinarias; el endpoint de promoción con JWT USER directo continúa denegado.
Los proyectos DSL requieren una definición propia o una definición de plataforma seguida por la empresa. Para plataforma solo puede fijarse la versión exacta actualmente seguida. Sin sesión: 401; permiso revocado o token externo: 403; proyecto/definición/versión ajena, inexistente o no autorizada: 404; entrada inválida: 400. Las operaciones denegadas no dejan escrituras parciales.
Las operaciones anteriores requieren JWT de plataforma y rol OWNER/ADMIN vigente. Las sesiones runtime se limitan a una allowlist explícita de rutas y métodos de ejecución DSL; el guard las deniega en endpoints administrativos, incluidas rutas @Public(). Cada request vuelve a validar membresía, rol de aplicación, release, expiración/revocación y origen registrado exacto. El contexto se deriva de la sesión y los selectors de headers no pueden cambiarlo. CORS refleja orígenes activos para transporte de navegador, pero no concede autoridad. Esta capacidad permanece interna y no se añade a SDK público, MCP externo ni chat embebible.
Publicar otra versión DSL no cambia los releases ni despliega nada. Un release no se edita; crear otro conserva el anterior. currentRelease comienza en null. Las conexiones se guardan como referencias opacas a providers existentes en revisiones inmutables; las credenciales permanecen en el vault. Solo payment/Stripe y email/SMTP de producción pueden referenciar providers tenant activos. Preview no usa credenciales productivas ni recurre a un provider built-in de plataforma; si no hay adapter sandbox, devuelve un diagnóstico 422 y no ejecuta el efecto. Push y webhook siguen bloqueados hasta que existan adapters aprobados. El runtime DSL usa el entorno autorizado como namespace de instancias y relaciones: preview y production no comparten datos. Los IDs recibidos se aceptan solo tras verificar membresía, propiedad del proyecto y release asignado. El namespace de archivos permanece pendiente.
En Git, el SHA es una referencia declarativa: aún no se consulta ni se verifica el repositorio, no se construye y no se despliega. repositoryBindingId se rechaza hasta integrar y autorizar repositorios. toolchain.snapshotSchemaVersion describe el formato de captura, no una compilación ejecutada.
La promoción requiere una sesión OWNER/ADMIN vigente y el release activo de Preview con deployment exitoso confirmado. Verifica la revisión de configuración y las referencias a providers tenant, crea una asignación inmutable en Production y cambia el release activo en una transacción con control de generación. Conserva las asignaciones anteriores. La confirmación indica activación del runtime del backend; no despliega a Pages ni comprueba salud remota de Production. sourceHash, artifactHash y configurationHash describen el snapshot fuente, los bytes compilados y la revisión privada de configuración, respectivamente.