@oondemand/oon-core-back 0.2.0 → 0.3.0

package/README.md

@@ -1,132 +1,19 @@
-# @oondemand/oon-core-back
+# OonCore Back - ativação de instâncias
 
-📖 **[Documentação completa → ooncoredoc.vercel.app](https://ooncoredoc.vercel.app)**
+O Core suporta `ecosystem.role` em `central.config.js`: `root` para a Central de Ativações e `member` (padrão) para demais Centrais. Aplicações `member` iniciam como `nao_ativada`, expõem apenas `/ativacao/*`, `/health` e `/version`, e só liberam autenticação/CRUD após ativação.
 
-Core runtime para **Centrais Oon**. O backend de uma Central passa a ser
-apenas domínio: você escreve `central.config.js` + `src/models` (e, quando
-preciso, `validations / triggers / pipelines / documents / integrations /
-routes`) e sobe tudo com `oonCore-back start`.
+## Variáveis de ambiente
 
-Toda a infraestrutura — boot, banco, auth, RBAC, logs, auditoria, paginação,
-metadata, CRUD, módulos opinativos (Omie, Assistentes, Multi-moedas, Esteiras,
-Documentos) e deploy (Docker + k8s) — vive aqui dentro.
+- `CENTRAL_ATIVACAO_URL`: backend real da Central de Ativações; nunca aponte para o próprio Core.
+- `APP_CODE`: código do aplicativo no Ecossistema.
+- `APP_ENVIRONMENT`: `desenvolvimento`, `homologacao` ou `producao`.
+- `PUBLIC_APP_URL`: URL pública confirmada da Central.
+- `INSTANCE_CREDENTIAL_ENCRYPTION_KEY`: chave para AES-256-GCM; obrigatória em produção.
+- `AUTH_PROVIDER_TIMEOUT_MS`: timeout das chamadas à Central de Ativações.
+- `INSTANCE_HEARTBEAT_INTERVAL_MS`: intervalo planejado para sincronização/heartbeat.
 
-## Instalação
+## Fluxo
 
-```bash
-npm install @oondemand/oon-core-back
-```
+`GET /ativacao/status` informa estado sem segredos. `POST /ativacao/validar-codigo` valida sem consumir. `POST /ativacao/concluir` revalida, chama `/ativar`, criptografa imediatamente o token da instância, executa hooks declarativos, chama `/concluir` e marca a instância como `ativa`. `POST /ativacao/tentar-novamente` retoma uma ativação já registrada sem exigir novo código.
 
-## Uso mínimo
-
-`central.config.js`:
-
-```js
-module.exports = {
-  serviceName: "minha-central",
-  // opcional: provedor de auth (default = Meus Apps)
-  // auth: { verifyToken: async (token) => ({ tipo, nome, email }) },
-};
-```
-
-`src/models/Produto.js`:
-
-```js
-const { defineModel, fields } = require("@oondemand/oon-core-back");
-
-defineModel({
-  name: "Produto",
-  schema: {
-    nome: fields.string({ required: true }),
-    preco: fields.currency(),
-    moeda: fields.currencyCode(),
-  },
-  crud: { enabled: true, roles: { write: ["admin"] } },
-});
-```
-
-Subir:
-
-```bash
-npx oonCore-back start   # produção
-npx oonCore-back dev     # watch/reload
-```
-
-Isso já expõe, para `Produto`:
-
-```
-GET    /produtos            (list + paginação/filtros/busca/ordenação)
-GET    /produtos/:id
-POST   /produtos
-PUT    /produtos/:id
-PATCH  /produtos/:id
-DELETE /produtos/:id
-POST   /produtos/import
-GET    /produtos/export
-```
-
-Todas privadas (auth obrigatório), com RBAC e auditoria nas mutações.
-
-## API pública
-
-```js
-const {
-  start, createApp, activate,
-  defineCentral, defineModel, fields,
-  defineCollection, defineDocument, definePipeline,
-  defineOmieMapping, defineRoutes, defineValidation, defineTrigger,
-  omie, GenericError, registry,
-} = require("@oondemand/oon-core-back");
-```
-
-### `defineRoutes` — rotas customizadas com o contrato de segurança
-
-Nunca se usa `express.Router()` cru. `router.private.*` aplica auth + RBAC
-(+ auditoria opcional); `router.public.*` é aberto.
-
-```js
-const { defineRoutes } = require("@oondemand/oon-core-back");
-
-defineRoutes("/relatorios", (router) => {
-  router.private.get("/resumo", { roles: ["admin"] }, async (req, res) => {
-    res.json({ ok: true, usuario: req.usuario });
-  });
-  router.public.get("/health", async (_req, res) => res.json({ up: true }));
-});
-```
-
-## Rotas `/core/*` (contrato com o oonCore-front)
-
-```
-GET /core/metadata     GET /core/models      GET /core/models/:name
-GET /core/collections  GET /core/documents   GET /core/pipelines
-GET /core/integrations GET /core/permissions GET /core/actions
-GET /core/menus        GET /core/features
-```
-
-## CLI
-
-```bash
-oonCore-back start        # produção
-oonCore-back dev          # watch/reload
-oonCore-back activate     # seed/ativação (singleton Sistema + hook)
-oonCore-back build:image  # renderiza Dockerfile + docker build
-oonCore-back k8s:render   # renderiza manifests a partir de central.manifest.json
-oonCore-back deploy       # kubectl apply dos manifests
-```
-
-O consumidor não escreve YAML: ajusta `central.manifest.json` e o Core
-renderiza Dockerfile + ConfigMap/Secret/Deployment/Service/Ingress/HPA/Certificate.
-
-## Testes
-
-```bash
-npm test                 # invariantes de segurança (offline)
-MONGO_URI=... npm test   # inclui CRUD + auditoria (requer Mongo)
-```
-
-## Variáveis de ambiente principais
-
-`SERVICE_NAME`, `SERVICE_VERSION`, `PORT`, `NODE_ENV`,
-`DB_SERVER`/`DB_NAME`/`DB_USER`/`DB_PASSWORD`/`DB_AUTH_SOURCE`/`DB_REPLICA_SET`/`DB_TSL`
-(ou `MONGO_URI`), `MEUS_APPS_BACKEND_URL`, `OMIE_APP_KEY`/`OMIE_APP_SECRET`.
+Campos adicionais podem ser declarados em `activation.fields`; `password` e `secret` são sanitizados na configuração retornada ao frontend. Hooks opcionais: `validate`, `beforeComplete`, `afterComplete`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oondemand/oon-core-back",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/oondemand/oon-platform.git",

package/src/api/activation.routes.js

@@ -0,0 +1,522 @@
+const express = require("express");
+const ctx = require("../core/context");
+const GenericError = require("../core/errors/GenericError");
+const { asyncHandler, sendResponse } = require("../core/utils/helpers");
+const {
+  PATHS,
+  globalDefaults,
+  globalFields,
+  rootFields,
+  role,
+  ambiente,
+  publicUrl,
+  sanitizeFields,
+  activationConfig,
+  ensureInstance,
+  hasActiveRootInstance,
+  claimRootBootstrap,
+  validateRootCredentials,
+  encrypt,
+  instanceHeaders,
+  validateParams,
+  providerPost,
+  providerPayload,
+  event,
+} = require("../core/utils/instanceActivation");
+const { getAppCode, getBaseUrl } = require("../core/utils/activationProvider");
+
+const router = express.Router();
+const attempts = new Map();
+
+function rateLimit(req, res, next) {
+  const key = req.ip || "local";
+  const now = Date.now();
+  const list = (attempts.get(key) || []).filter((time) => now - time < 60000);
+
+  if (list.length >= 30) {
+    return res.status(429).json({
+      error: {
+        code: "RATE_LIMIT",
+        message: "Muitas tentativas de ativação.",
+      },
+    });
+  }
+
+  list.push(now);
+  attempts.set(key, list);
+  next();
+}
+
+function assertMember() {
+  if (role() === "root") {
+    throw new GenericError(
+      "Aplicações root usam o bootstrap inicial do ecossistema.",
+      { statusCode: 400 },
+    );
+  }
+}
+
+function assertRoot() {
+  if (role() !== "root") {
+    throw new GenericError(
+      "Somente a aplicação root pode executar esta ativação.",
+      { statusCode: 400 },
+    );
+  }
+}
+
+function assertApp(data) {
+  const returned = data?.app?.codigo || data?.appCode;
+  if (returned && String(returned).toLowerCase() !== getAppCode()) {
+    throw new GenericError(
+      "Código do aplicativo retornado pela Central é incompatível.",
+      { statusCode: 502 },
+    );
+  }
+}
+
+function safeContext(data) {
+  const { credencial, ...safe } = data || {};
+  return safe;
+}
+
+function requireRootBootstrapResult(result) {
+  const usuarioId = result?.usuario?.id || result?.usuario?._id;
+  const tenantId = result?.tenant?.id || result?.tenant?._id;
+  const appId = result?.app?.id || result?.app?._id;
+  const licencaId = result?.licenca?.id || result?.licenca?._id;
+
+  if (!usuarioId || !tenantId || !appId || !licencaId) {
+    throw new GenericError(
+      "O bootstrap root não retornou a estrutura mínima do ecossistema.",
+      { statusCode: 500 },
+    );
+  }
+
+  if (
+    result?.app?.ecosystemRole &&
+    result.app.ecosystemRole !== "root"
+  ) {
+    throw new GenericError(
+      "O aplicativo criado pelo bootstrap não foi identificado como root.",
+      { statusCode: 500 },
+    );
+  }
+
+  return {
+    usuarioId: String(usuarioId),
+    tenantId: String(tenantId),
+    appId: String(appId),
+    licencaId: String(licencaId),
+  };
+}
+
+router.use(rateLimit);
+
+router.get(
+  "/status",
+  asyncHandler(async (_req, res) => {
+    const instance = await ensureInstance();
+    const rootActive =
+      instance.ecosystemRole === "root"
+        ? await hasActiveRootInstance()
+        : false;
+
+    const canActivateRoot =
+      instance.ecosystemRole === "root" &&
+      !rootActive &&
+      ["nao_ativada", "erro"].includes(instance.status);
+
+    const canActivateMember =
+      instance.ecosystemRole === "member" &&
+      ["nao_ativada", "erro"].includes(instance.status) &&
+      !instance.instanceId;
+
+    sendResponse({
+      res,
+      role: instance.ecosystemRole,
+      status: instance.status,
+      appCode: getAppCode(),
+      ambiente: instance.ambiente || ambiente(),
+      podeAtivar: canActivateRoot || canActivateMember,
+      podeTentarNovamente:
+        instance.ecosystemRole === "member" &&
+        Boolean(instance.instanceId) &&
+        ["configurando", "erro"].includes(instance.status),
+      motivoSuspensao: instance.motivoSuspensao,
+      motivoRevogacao: instance.motivoRevogacao,
+    });
+  }),
+);
+
+router.get(
+  "/configuracao",
+  asyncHandler(async (req, res) => {
+    const instance = await ensureInstance();
+    const config = activationConfig();
+
+    if (instance.ecosystemRole === "root") {
+      return sendResponse({
+        res,
+        mode: "root-bootstrap",
+        configurationVersion: config.configurationVersion,
+        rootFields: sanitizeFields(rootFields),
+        globalFields: [],
+        appFields: [],
+        defaults: {},
+        technical: {
+          appCode: getAppCode(),
+          ambiente: ambiente(),
+          ecosystemRole: "root",
+        },
+      });
+    }
+
+    const host = new URL(getBaseUrl(req)).hostname;
+    return sendResponse({
+      res,
+      mode: "member-activation",
+      configurationVersion: config.configurationVersion,
+      rootFields: [],
+      globalFields,
+      appFields: sanitizeFields(config.fields),
+      defaults: {
+        ...globalDefaults,
+        ambiente: ambiente(),
+        urlPublica: publicUrl(req),
+      },
+      technical: {
+        appCode: getAppCode(),
+        ambiente: ambiente(),
+        ecosystemRole: "member",
+        centralAtivacaoHost: host,
+      },
+    });
+  }),
+);
+
+router.post(
+  "/ativar-root",
+  asyncHandler(async (req, res) => {
+    assertRoot();
+
+    const config = activationConfig();
+    if (typeof config.rootBootstrap !== "function") {
+      throw new GenericError(
+        "A aplicação root não configurou o bootstrap inicial.",
+        { statusCode: 500 },
+      );
+    }
+
+    const { email, password } = validateRootCredentials(
+      req.body?.email,
+      req.body?.senha,
+    );
+    const instance = await claimRootBootstrap();
+
+    event("ROOT_BOOTSTRAP_STARTED", {
+      correlationId: req.correlationId,
+      appCode: getAppCode(),
+    });
+
+    try {
+      const result = await config.rootBootstrap({
+        email,
+        password,
+        appCode: getAppCode(),
+        appName: ctx.config.name,
+        appSlug: ctx.config.slug,
+        environment: ambiente(),
+        context: { req },
+      });
+
+      const ids = requireRootBootstrapResult(result);
+      const now = new Date();
+
+      Object.assign(instance, {
+        ecosystemRole: "root",
+        status: "ativa",
+        instanceId: result.instanceId || `root:${ids.appId}`,
+        instanceCode: result.instanceCode || "root",
+        appCode: getAppCode(),
+        appId: ids.appId,
+        tenantId: ids.tenantId,
+        licencaId: ids.licencaId,
+        ambiente: ambiente(),
+        nomeInstancia: ctx.config.name || ctx.config.slug || getAppCode(),
+        publicUrl: publicUrl(req),
+        tenant: result.tenant,
+        app: result.app,
+        licenca: result.licenca,
+        parametrosGlobais: {},
+        parametrosAplicacao: {},
+        configurationVersion: config.configurationVersion,
+        ativadaEm: now,
+        concluidaEm: now,
+        ultimoErro: undefined,
+      });
+
+      await instance.save();
+
+      event("ROOT_BOOTSTRAP_COMPLETED", {
+        correlationId: req.correlationId,
+        appCode: getAppCode(),
+        usuarioId: ids.usuarioId,
+      });
+
+      return sendResponse({
+        res,
+        sucesso: true,
+        status: "ativa",
+        usuario: {
+          id: ids.usuarioId,
+          email: result.usuario.email,
+        },
+      });
+    } catch (error) {
+      instance.status = "erro";
+      instance.ultimoErro = error.message;
+      await instance.save();
+
+      event("ROOT_BOOTSTRAP_FAILED", {
+        correlationId: req.correlationId,
+        appCode: getAppCode(),
+      });
+
+      throw error;
+    }
+  }),
+);
+
+router.post(
+  "/validar-codigo",
+  asyncHandler(async (req, res) => {
+    assertMember();
+    const codigoAtivacao = String(req.body?.codigoAtivacao || "").trim();
+    if (!codigoAtivacao) {
+      throw new GenericError("Código de ativação obrigatório.", {
+        statusCode: 400,
+      });
+    }
+
+    const instance = await ensureInstance();
+    if (instance.status === "ativa") {
+      throw new GenericError("Instância já ativada.", { statusCode: 409 });
+    }
+
+    event("INSTANCE_ACTIVATION_VALIDATION_STARTED", {
+      correlationId: req.correlationId,
+    });
+
+    try {
+      const response = await providerPost(
+        req,
+        PATHS.validar,
+        providerPayload(req, codigoAtivacao),
+      );
+      assertApp(response.data);
+      instance.status = "validando";
+      instance.ultimaValidacaoEm = new Date();
+      await instance.save();
+      event("INSTANCE_ACTIVATION_VALIDATION_SUCCEEDED", {
+        correlationId: req.correlationId,
+      });
+      sendResponse({ res, ...safeContext(response.data) });
+    } catch (error) {
+      event("INSTANCE_ACTIVATION_VALIDATION_FAILED", {
+        correlationId: req.correlationId,
+        status: error.response?.status,
+      });
+      throw error.response
+        ? new GenericError(
+            error.response.data?.message || "Código de ativação inválido.",
+            { statusCode: error.response.status },
+          )
+        : error;
+    }
+  }),
+);
+
+router.post(
+  "/concluir",
+  asyncHandler(async (req, res) => {
+    assertMember();
+    const {
+      codigoAtivacao,
+      nomeInstancia,
+      parametrosGlobais = {},
+      parametrosAplicacao = {},
+    } = req.body || {};
+
+    if (!codigoAtivacao) {
+      throw new GenericError("Código de ativação obrigatório.", {
+        statusCode: 400,
+      });
+    }
+
+    validateParams(
+      { ...parametrosGlobais, nomeInstancia },
+      parametrosAplicacao,
+    );
+
+    const config = activationConfig();
+    const instance = await ensureInstance();
+
+    if (
+      instance.instanceId &&
+      ["configurando", "erro"].includes(instance.status)
+    ) {
+      return res.redirect(307, "/ativacao/tentar-novamente");
+    }
+
+    if (!["nao_ativada", "validando", "erro"].includes(instance.status)) {
+      throw new GenericError(
+        "Instância não pode ser ativada neste estado.",
+        { statusCode: 409 },
+      );
+    }
+
+    event("INSTANCE_ACTIVATION_STARTED", {
+      correlationId: req.correlationId,
+    });
+
+    if (typeof config.hooks.validate === "function") {
+      await config.hooks.validate({
+        globalParameters: parametrosGlobais,
+        appParameters: parametrosAplicacao,
+        context: { req },
+      });
+    }
+
+    const preview = await providerPost(
+      req,
+      PATHS.validar,
+      providerPayload(req, codigoAtivacao),
+    );
+    assertApp(preview.data);
+
+    const activated = await providerPost(
+      req,
+      PATHS.ativar,
+      providerPayload(req, codigoAtivacao, { nomeInstancia, metadata: {} }),
+    );
+    assertApp(activated.data);
+
+    const token = activated.data?.credencial?.token;
+    if (!activated.data?.instancia?.id || !token) {
+      throw new GenericError("Resposta de ativação inválida.", {
+        statusCode: 502,
+      });
+    }
+
+    Object.assign(instance, encrypt(token), {
+      status: "configurando",
+      instanceId: activated.data.instancia.id,
+      instanceCode: activated.data.instancia.codigo,
+      credentialVersion: activated.data.credencial.versao,
+      appCode: getAppCode(),
+      appId: activated.data.app?.id || preview.data?.app?.id,
+      tenantId: activated.data.tenant?.id || preview.data?.tenant?.id,
+      licencaId: activated.data.licenca?.id || preview.data?.licenca?.id,
+      ambiente: ambiente(),
+      nomeInstancia,
+      publicUrl: publicUrl(req),
+      tenant: activated.data.tenant || preview.data?.tenant,
+      app: activated.data.app || preview.data?.app,
+      licenca: activated.data.licenca || preview.data?.licenca,
+      parametrosGlobais,
+      parametrosAplicacao,
+      configurationVersion: config.configurationVersion,
+      ativadaEm: new Date(),
+      ultimoErro: undefined,
+    });
+
+    await instance.save();
+    event("INSTANCE_ACTIVATION_REGISTERED", {
+      correlationId: req.correlationId,
+    });
+
+    await complete(req, instance, config);
+    sendResponse({
+      res,
+      sucesso: true,
+      status: "ativa",
+      instanceId: instance.instanceId,
+    });
+  }),
+);
+
+async function complete(req, instance, config) {
+  try {
+    if (typeof config.hooks.beforeComplete === "function") {
+      await config.hooks.beforeComplete({
+        globalParameters: instance.parametrosGlobais,
+        appParameters: instance.parametrosAplicacao,
+        context: { req },
+      });
+    }
+
+    await providerPost(
+      req,
+      PATHS.concluir,
+      {
+        configurationVersion: config.configurationVersion,
+        parametros: instance.parametrosGlobais,
+      },
+      instanceHeaders(instance),
+    );
+
+    instance.status = "ativa";
+    instance.concluidaEm = new Date();
+    instance.ultimoErro = undefined;
+    await instance.save();
+
+    event("INSTANCE_ACTIVATION_COMPLETED", {
+      correlationId: req.correlationId,
+    });
+
+    if (typeof config.hooks.afterComplete === "function") {
+      await config.hooks.afterComplete({
+        instance: instance.toJSON(),
+        context: { req },
+      });
+    }
+  } catch (error) {
+    instance.status = "erro";
+    instance.ultimoErro = error.message;
+    await instance.save();
+    event("INSTANCE_ACTIVATION_FAILED", {
+      correlationId: req.correlationId,
+    });
+    throw error;
+  }
+}
+
+router.post(
+  "/tentar-novamente",
+  asyncHandler(async (req, res) => {
+    assertMember();
+    const instance = await ensureInstance();
+    const config = activationConfig();
+
+    if (
+      !instance.instanceId ||
+      !["configurando", "erro"].includes(instance.status)
+    ) {
+      throw new GenericError(
+        "Não há ativação pendente para retomar.",
+        { statusCode: 409 },
+      );
+    }
+
+    await complete(req, instance, config);
+    sendResponse({
+      res,
+      sucesso: true,
+      status: instance.status,
+      instanceId: instance.instanceId,
+    });
+  }),
+);
+
+module.exports = router;