@oondemand/oon-core-back 0.3.43 → 0.3.45

package/package.json

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

package/src/api/core.routes.js

@@ -2,18 +2,12 @@ const express = require("express");
 const registry = require("../core/registry");
 const ctx = require("../core/context");
 
-/**
- * Rotas /core/* — contrato de metadata com o oonCore-front (Seção 2.5/21).
- * Expõem o que o registry conhece, sem domínio hardcoded.
- */
 const router = express.Router();
 
 function modelSummary(entry) {
   return {
     name: entry.name,
     singular: entry.singular,
-    // basePath em que o CRUD está montado — consumido pelo oonCore-front para
-    // resolver a URL do recurso no modo "dynamic" (default = /<singular>s).
     basePath: entry.definition.basePath || `/${entry.singular}s`,
     crud: entry.definition.crud?.enabled !== false,
     roles: entry.definition.crud?.roles || {},
@@ -22,9 +16,25 @@ function modelSummary(entry) {
   };
 }
 
+function appSummary() {
+  const manifest = ctx.config.appManifest;
+  if (!manifest) return undefined;
+  return {
+    schemaVersion: manifest.schemaVersion,
+    id: manifest.id,
+    name: manifest.name,
+    slug: manifest.slug,
+    appKind: manifest.appKind,
+    modules: manifest.modules,
+    capabilities: manifest.capabilities,
+    compatibility: manifest.compatibility,
+  };
+}
+
 router.get("/metadata", (_req, res) => {
   res.json({
     service: { name: ctx.config.serviceName, version: ctx.config.serviceVersion },
+    app: appSummary(),
     models: registry.listModels().map(modelSummary),
     collections: registry.listCollections(),
     documents: registry.listDocuments(),
@@ -35,21 +45,16 @@ router.get("/metadata", (_req, res) => {
   });
 });
 
-router.get("/models", (_req, res) => {
-  res.json({ results: registry.listModels().map(modelSummary) });
-});
-
+router.get("/models", (_req, res) => res.json({ results: registry.listModels().map(modelSummary) }));
 router.get("/models/:name", (req, res) => {
   const entry = registry.getModel(req.params.name);
   if (!entry) return res.status(404).json({ message: "Model não registrada." });
   res.json(modelSummary(entry));
 });
-
 router.get("/collections", (_req, res) => res.json({ results: registry.listCollections() }));
 router.get("/documents", (_req, res) => res.json({ results: registry.listDocuments() }));
 router.get("/pipelines", (_req, res) => res.json({ results: registry.listPipelines() }));
 router.get("/integrations", (_req, res) => res.json({ results: registry.listIntegrations() }));
-
 router.get("/permissions", (_req, res) => {
   const permissions = registry.listModels().flatMap((entry) => {
     const roles = entry.definition.crud?.roles || {};
@@ -60,7 +65,6 @@ router.get("/permissions", (_req, res) => {
   });
   res.json({ results: permissions });
 });
-
 router.get("/actions", (_req, res) => {
   const actions = registry.listModels().map((entry) => ({
     model: entry.name,
@@ -68,7 +72,6 @@ router.get("/actions", (_req, res) => {
   }));
   res.json({ results: actions });
 });
-
 router.get("/menus", (_req, res) => res.json({ results: registry.listMenus() }));
 router.get("/features", (_req, res) => res.json({ results: registry.listFeatures() }));
 

package/src/boot/loadCentral.js

@@ -1,23 +1,17 @@
 const fs = require("node:fs");
 const path = require("node:path");
 const ctx = require("../core/context");
+const {
+  APP_MANIFEST_FILENAME,
+  resolveAppManifestPath,
+  loadAppManifest,
+  AppManifestError,
+} = require("../manifest/appManifest");
 const {
   DOMAIN_MANIFEST_FILENAME,
   loadDomainManifest,
 } = require("../manifest/domainManifest");
 
-/**
- * Descobre e carrega a Central do consumidor:
- *   1. `central.config.js` na raiz do projeto (mescla na config do Core);
- *   2. `central.domain.json` na raiz (registra models declarativas);
- *   3. arquivos de domínio em `src/{models,validations,triggers,routes,
- *      pipelines,documents,integrations,mappings}` (apenas `require`,
- *      o efeito colateral é registrar via `define*`).
- *
- * O carregamento dos diretórios JavaScript permanece ativo durante a migração.
- * Declarar a mesma model no manifesto e em `src/models` falha explicitamente no
- * registry, impedindo duas fontes de verdade silenciosas.
- */
 const DOMAIN_DIRS = [
   "models",
   "validations",
@@ -30,11 +24,51 @@ const DOMAIN_DIRS = [
   "hooks",
 ];
 
+const APP_CONFIG_KEYS = new Set([
+  "name",
+  "slug",
+  "appCode",
+  "appCodigo",
+  "appKind",
+  "ecosystem",
+  "activation",
+  "modules",
+  "capabilities",
+]);
+
+function assertConfigBoundary(config, appManifest) {
+  if (!appManifest || !config || typeof config !== "object") return;
+  const issues = [];
+  for (const key of APP_CONFIG_KEYS) {
+    if (Object.prototype.hasOwnProperty.call(config, key)) {
+      issues.push({
+        path: `central.config.js.${key}`,
+        message: `deve ser declarado em ${APP_MANIFEST_FILENAME}.`,
+      });
+    }
+  }
+  if (appManifest.appKind !== "root-central" && Object.prototype.hasOwnProperty.call(config, "auth")) {
+    issues.push({
+      path: "central.config.js.auth",
+      message: "autenticação de Centrais member/portal é fornecida pelo OonCore.",
+    });
+  }
+  if (issues.length) throw new AppManifestError("central.config.js viola a fronteira declarativa.", issues);
+}
+
 function loadCentral(cwd = process.cwd()) {
+  let appManifest;
+  const appManifestPath = resolveAppManifestPath(cwd);
+  if (fs.existsSync(appManifestPath)) {
+    appManifest = loadAppManifest(appManifestPath);
+  }
+
   const configPath = path.join(cwd, "central.config.js");
   if (fs.existsSync(configPath)) {
-    const config = require(configPath);
-    ctx.setConfig(typeof config === "function" ? config() : config);
+    const exported = require(configPath);
+    const config = typeof exported === "function" ? exported() : exported;
+    assertConfigBoundary(config, appManifest);
+    ctx.setConfig(config);
   }
 
   const domainManifestPath = path.join(cwd, DOMAIN_MANIFEST_FILENAME);
@@ -54,12 +88,9 @@ function loadCentral(cwd = process.cwd()) {
 function requireDir(dir) {
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
     const full = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      requireDir(full);
-    } else if (/\.(js|cjs)$/.test(entry.name)) {
-      require(full);
-    }
+    if (entry.isDirectory()) requireDir(full);
+    else if (/\.(js|cjs)$/.test(entry.name)) require(full);
   }
 }
 
-module.exports = { loadCentral, DOMAIN_DIRS };
+module.exports = { loadCentral, DOMAIN_DIRS, APP_CONFIG_KEYS, assertConfigBoundary };

package/src/core/middlewares/auth.js

@@ -8,11 +8,6 @@ const {
   getTimeout,
 } = require("../utils/activationProvider");
 
-/**
- * Verificador padrão: delega para a Central de Ativações e valida o token no
- * contexto do app configurado no backend por APP_CODE/APP_CODIGO.
- * Pode ser sobrescrito via `central.config.js -> auth.verifyToken`.
- */
 async function defaultVerifyToken(token, { req } = {}) {
   const baseUrl = getBaseUrl(req);
   const appCode = getAppCode();
@@ -29,9 +24,7 @@ async function defaultVerifyToken(token, { req } = {}) {
     });
   } catch (error) {
     const err = new Error(
-      error.response?.data?.message ||
-        error.message ||
-        "Token inválido ou erro na autenticação.",
+      error.response?.data?.message || error.message || "Token inválido ou erro na autenticação.",
     );
     err.statusCode = error.response?.status || error.statusCode || 401;
     throw err;
@@ -44,9 +37,7 @@ async function defaultVerifyToken(token, { req } = {}) {
     throw err;
   }
 
-  const tipoAcesso =
-    data.aplicativo?.tipoAcesso || data.tipoAcesso || data.tipo || data.perfil;
-
+  const tipoAcesso = data.aplicativo?.tipoAcesso || data.tipoAcesso || data.tipo || data.perfil;
   return {
     ...data,
     tipo: tipoAcesso === "master" ? "admin" : tipoAcesso,
@@ -56,9 +47,32 @@ async function defaultVerifyToken(token, { req } = {}) {
   };
 }
 
+function localDevelopmentVerifyToken(token) {
+  const expected = String(process.env.DEV_TOKEN || "");
+  if (process.env.NODE_ENV !== "development" || !expected || token !== expected) {
+    const error = new Error("Token local de desenvolvimento inválido.");
+    error.statusCode = 401;
+    throw error;
+  }
+  return {
+    tipo: process.env.DEV_USER_ROLE || "admin",
+    perfil: process.env.DEV_USER_ROLE || "admin",
+    nome: process.env.DEV_USER_NAME || "Dev Local",
+    email: process.env.DEV_USER_EMAIL || "dev@local",
+    capabilities: ctx.config.capabilities || [],
+  };
+}
+
+function resolveVerifyToken() {
+  if (typeof ctx.config.auth?.verifyToken === "function") return ctx.config.auth.verifyToken;
+  if (process.env.NODE_ENV === "development" && process.env.DEV_TOKEN) {
+    return localDevelopmentVerifyToken;
+  }
+  return defaultVerifyToken;
+}
+
 const authMiddleware = async (req, res, next) => {
   const token = req.headers.authorization?.split(" ")[1];
-
   if (!token) {
     return Helpers.sendErrorResponse({
       res,
@@ -67,10 +81,8 @@ const authMiddleware = async (req, res, next) => {
     });
   }
 
-  const verify = ctx.config.auth?.verifyToken || defaultVerifyToken;
-
   try {
-    const usuario = await verify(token, { req });
+    const usuario = await resolveVerifyToken()(token, { req });
     if (!usuario) {
       const error = new Error("Usuário não resolvido.");
       error.statusCode = 401;
@@ -89,3 +101,5 @@ const authMiddleware = async (req, res, next) => {
 
 module.exports = authMiddleware;
 module.exports.defaultVerifyToken = defaultVerifyToken;
+module.exports.localDevelopmentVerifyToken = localDevelopmentVerifyToken;
+module.exports.resolveVerifyToken = resolveVerifyToken;

package/src/index.js

@@ -1,12 +1,5 @@
 require("dotenv").config();
 
-/**
- * API pública do @oondemand/oon-core-back (Seção 2.4).
- *
- * O consumidor escreve apenas models/validations/triggers/hooks/mappings/
- * pipelines/documents/integrations/routes e sobe com `start()` ou
- * `oonCore-back start`.
- */
 const { start } = require("./boot/startServer");
 const { createApp } = require("./boot/createApp");
 const { activate } = require("./boot/activation");
@@ -15,16 +8,14 @@ const fields = require("./core/fields");
 const registry = require("./core/registry");
 const GenericError = require("./core/errors/GenericError");
 const { omie } = require("./modules/omie");
+const appManifest = require("./manifest/appManifest");
 const domainManifest = require("./manifest/domainManifest");
 const domainRules = require("./manifest/domainRules");
 
 module.exports = {
-  // boot
   start,
   createApp,
   activate,
-
-  // declaração de domínio
   defineCentral: define.defineCentral,
   defineModel: define.defineModel,
   defineCollection: define.defineCollection,
@@ -35,7 +26,17 @@ module.exports = {
   defineValidation: define.defineValidation,
   defineTrigger: define.defineTrigger,
 
-  // manifesto declarativo de domínio
+  APP_MANIFEST_FILENAME: appManifest.APP_MANIFEST_FILENAME,
+  APP_MANIFEST_SCHEMA_VERSION: appManifest.APP_MANIFEST_SCHEMA_VERSION,
+  SUPPORTED_APP_KINDS: appManifest.SUPPORTED_APP_KINDS,
+  SUPPORTED_APP_MODULES: appManifest.SUPPORTED_MODULES,
+  AppManifestError: appManifest.AppManifestError,
+  validateAppManifest: appManifest.validateAppManifest,
+  resolveAppManifestPath: appManifest.resolveAppManifestPath,
+  appManifestToConfig: appManifest.appManifestToConfig,
+  registerAppManifest: appManifest.registerAppManifest,
+  loadAppManifest: appManifest.loadAppManifest,
+
   DOMAIN_MANIFEST_FILENAME: domainManifest.DOMAIN_MANIFEST_FILENAME,
   DOMAIN_MANIFEST_SCHEMA_VERSION: domainManifest.DOMAIN_MANIFEST_SCHEMA_VERSION,
   SUPPORTED_DOMAIN_FIELD_KINDS: domainManifest.SUPPORTED_FIELD_KINDS,
@@ -49,11 +50,8 @@ module.exports = {
   evaluateDomainExpression: domainRules.evaluateDomainExpression,
   applyDomainMutation: domainRules.applyDomainMutation,
 
-  // helpers
   fields,
   omie,
   GenericError,
-
-  // avançado / introspecção
   registry,
 };

package/src/manifest/appManifest.js

@@ -0,0 +1,297 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const ctx = require("../core/context");
+const corePackage = require("../../package.json");
+
+const APP_MANIFEST_FILENAME = "central.app.json";
+const APP_MANIFEST_SCHEMA_VERSION = 1;
+const SUPPORTED_APP_KINDS = Object.freeze([
+  "root-central",
+  "member-central",
+  "portal-cockpit",
+]);
+const SUPPORTED_MODULES = Object.freeze([
+  "collections",
+  "documents",
+  "pipelines",
+  "integrations",
+  "omie",
+  "assistants",
+  "currencies",
+]);
+const APP_KIND_ROLE = Object.freeze({
+  "root-central": "root",
+  "member-central": "member",
+  "portal-cockpit": "portal",
+});
+
+class AppManifestError extends Error {
+  constructor(message, issues = [], options = {}) {
+    super(message, options);
+    this.name = "AppManifestError";
+    this.code = "OON_APP_MANIFEST_INVALID";
+    this.statusCode = 422;
+    this.issues = issues;
+    this.details = { issues };
+  }
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function hasOwn(object, key) {
+  return Object.prototype.hasOwnProperty.call(object, key);
+}
+
+function addIssue(issues, fieldPath, message) {
+  issues.push({ path: fieldPath, message });
+}
+
+function parseVersion(value) {
+  if (typeof value !== "string") return null;
+  const match = value.trim().match(/^(\d+)\.(\d+)\.(\d+)(?:[-+][0-9A-Za-z.-]+)?$/);
+  if (!match) return null;
+  return match.slice(1, 4).map(Number);
+}
+
+function compareVersions(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] < right[index] ? -1 : 1;
+  }
+  return 0;
+}
+
+function validateCompatibility(compatibility, issues, coreVersion) {
+  if (!isPlainObject(compatibility)) {
+    addIssue(issues, "compatibility", "deve ser um objeto.");
+    return;
+  }
+  if (!isPlainObject(compatibility.core)) {
+    addIssue(issues, "compatibility.core", "deve ser um objeto.");
+    return;
+  }
+
+  const allowedKeys = new Set(["minVersion", "maxVersionExclusive"]);
+  for (const key of Object.keys(compatibility.core)) {
+    if (!allowedKeys.has(key)) addIssue(issues, `compatibility.core.${key}`, "propriedade não suportada.");
+  }
+
+  const minVersion = parseVersion(compatibility.core.minVersion);
+  const maxVersion = hasOwn(compatibility.core, "maxVersionExclusive")
+    ? parseVersion(compatibility.core.maxVersionExclusive)
+    : null;
+
+  if (!minVersion) {
+    addIssue(issues, "compatibility.core.minVersion", "deve usar versão semântica, por exemplo 0.3.45.");
+  }
+  if (hasOwn(compatibility.core, "maxVersionExclusive") && !maxVersion) {
+    addIssue(
+      issues,
+      "compatibility.core.maxVersionExclusive",
+      "deve usar versão semântica, por exemplo 0.4.0.",
+    );
+  }
+  if (minVersion && maxVersion && compareVersions(minVersion, maxVersion) >= 0) {
+    addIssue(
+      issues,
+      "compatibility.core",
+      "minVersion deve ser menor que maxVersionExclusive.",
+    );
+  }
+
+  const installedVersion = parseVersion(coreVersion);
+  if (!installedVersion || !minVersion) return;
+  if (compareVersions(installedVersion, minVersion) < 0) {
+    addIssue(
+      issues,
+      "compatibility.core.minVersion",
+      `requer OonCore ${compatibility.core.minVersion} ou superior; instalado ${coreVersion}.`,
+    );
+  }
+  if (maxVersion && compareVersions(installedVersion, maxVersion) >= 0) {
+    addIssue(
+      issues,
+      "compatibility.core.maxVersionExclusive",
+      `requer OonCore anterior a ${compatibility.core.maxVersionExclusive}; instalado ${coreVersion}.`,
+    );
+  }
+}
+
+function validateActivation(activation, issues) {
+  if (!hasOwn(activation || {}, "enabled") && activation === undefined) return;
+  if (!isPlainObject(activation)) {
+    addIssue(issues, "activation", "deve ser um objeto.");
+    return;
+  }
+  const allowedKeys = new Set(["enabled", "configurationVersion", "fields"]);
+  for (const key of Object.keys(activation)) {
+    if (!allowedKeys.has(key)) addIssue(issues, `activation.${key}`, "propriedade não suportada.");
+  }
+  if (hasOwn(activation, "enabled") && typeof activation.enabled !== "boolean") {
+    addIssue(issues, "activation.enabled", "deve ser booleano.");
+  }
+  if (
+    hasOwn(activation, "configurationVersion")
+    && (!Number.isInteger(activation.configurationVersion) || activation.configurationVersion < 1)
+  ) {
+    addIssue(issues, "activation.configurationVersion", "deve ser inteiro maior ou igual a 1.");
+  }
+  if (hasOwn(activation, "fields") && !Array.isArray(activation.fields)) {
+    addIssue(issues, "activation.fields", "deve ser uma lista.");
+  }
+}
+
+function validateAppManifest(input, { coreVersion = corePackage.version } = {}) {
+  const issues = [];
+  if (!isPlainObject(input)) {
+    throw new AppManifestError("central.app.json inválido.", [
+      { path: "$", message: "deve conter um objeto JSON." },
+    ]);
+  }
+
+  const allowedTopLevel = new Set([
+    "$schema",
+    "schemaVersion",
+    "id",
+    "name",
+    "slug",
+    "appKind",
+    "modules",
+    "capabilities",
+    "compatibility",
+    "activation",
+  ]);
+  for (const key of Object.keys(input)) {
+    if (!allowedTopLevel.has(key)) addIssue(issues, key, "propriedade não suportada.");
+  }
+
+  if (input.schemaVersion !== APP_MANIFEST_SCHEMA_VERSION) {
+    addIssue(
+      issues,
+      "schemaVersion",
+      `versão não suportada. Use ${APP_MANIFEST_SCHEMA_VERSION}.`,
+    );
+  }
+  if (typeof input.id !== "string" || !/^[a-z0-9][a-z0-9._-]*$/.test(input.id)) {
+    addIssue(issues, "id", "deve usar letras minúsculas, números, ponto, hífen ou sublinhado.");
+  }
+  if (typeof input.name !== "string" || !input.name.trim()) {
+    addIssue(issues, "name", "é obrigatório e deve ser texto não vazio.");
+  }
+  if (typeof input.slug !== "string" || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(input.slug)) {
+    addIssue(issues, "slug", "deve usar slug em letras minúsculas separado por hífen.");
+  }
+  if (!SUPPORTED_APP_KINDS.includes(input.appKind)) {
+    addIssue(issues, "appKind", `deve ser um de: ${SUPPORTED_APP_KINDS.join(", ")}.`);
+  }
+
+  if (!isPlainObject(input.modules)) {
+    addIssue(issues, "modules", "deve ser um objeto.");
+  } else {
+    for (const key of Object.keys(input.modules)) {
+      if (!SUPPORTED_MODULES.includes(key)) {
+        addIssue(issues, `modules.${key}`, `módulo não suportado. Use: ${SUPPORTED_MODULES.join(", ")}.`);
+      } else if (typeof input.modules[key] !== "boolean") {
+        addIssue(issues, `modules.${key}`, "deve ser booleano.");
+      }
+    }
+  }
+
+  if (!Array.isArray(input.capabilities)) {
+    addIssue(issues, "capabilities", "deve ser uma lista.");
+  } else {
+    const seen = new Set();
+    input.capabilities.forEach((capability, index) => {
+      if (
+        typeof capability !== "string"
+        || !/^[a-z][a-z0-9]*(?:[._:-][a-z0-9][a-z0-9-]*)+$/.test(capability)
+      ) {
+        addIssue(
+          issues,
+          `capabilities[${index}]`,
+          "deve ser um identificador namespaced, por exemplo core.collections.",
+        );
+      } else if (seen.has(capability)) {
+        addIssue(issues, `capabilities[${index}]`, `capability duplicada: ${capability}.`);
+      } else {
+        seen.add(capability);
+      }
+    });
+  }
+
+  validateCompatibility(input.compatibility, issues, coreVersion);
+  validateActivation(input.activation, issues);
+
+  if (issues.length) throw new AppManifestError("central.app.json inválido.", issues);
+  return JSON.parse(JSON.stringify(input));
+}
+
+function resolveAppManifestPath(cwd = process.cwd()) {
+  const absolute = path.resolve(cwd);
+  const candidates = [path.join(absolute, APP_MANIFEST_FILENAME)];
+  const parent = path.dirname(absolute);
+  if (["backend", "frontend"].includes(path.basename(absolute))) {
+    candidates.push(path.join(parent, APP_MANIFEST_FILENAME));
+  }
+  return candidates.find((candidate) => fs.existsSync(candidate)) || candidates[0];
+}
+
+function appManifestToConfig(manifest, manifestPath) {
+  return {
+    serviceName: manifest.slug,
+    name: manifest.name,
+    slug: manifest.slug,
+    appCode: manifest.id,
+    appKind: manifest.appKind,
+    ecosystem: { role: APP_KIND_ROLE[manifest.appKind] },
+    activation: manifest.activation || {
+      enabled: manifest.appKind !== "portal-cockpit",
+      configurationVersion: 1,
+      fields: [],
+    },
+    modules: { ...manifest.modules },
+    capabilities: [...manifest.capabilities],
+    appManifest: manifest,
+    appManifestPath: manifestPath,
+  };
+}
+
+function registerAppManifest(input, options = {}) {
+  const manifest = validateAppManifest(input, options);
+  ctx.setConfig(appManifestToConfig(manifest, options.manifestPath));
+  return manifest;
+}
+
+function loadAppManifest(cwdOrFile = process.cwd(), options = {}) {
+  const manifestPath = cwdOrFile.endsWith?.(".json")
+    ? path.resolve(cwdOrFile)
+    : resolveAppManifestPath(cwdOrFile);
+  let input;
+  try {
+    input = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") throw error;
+    throw new AppManifestError("Não foi possível ler central.app.json.", [
+      { path: "$", message: error.message },
+    ], { cause: error });
+  }
+  return registerAppManifest(input, { ...options, manifestPath });
+}
+
+module.exports = {
+  APP_MANIFEST_FILENAME,
+  APP_MANIFEST_SCHEMA_VERSION,
+  SUPPORTED_APP_KINDS,
+  SUPPORTED_MODULES,
+  AppManifestError,
+  parseVersion,
+  compareVersions,
+  validateAppManifest,
+  resolveAppManifestPath,
+  appManifestToConfig,
+  registerAppManifest,
+  loadAppManifest,
+};