@oondemand/oon-core-back 0.7.16 → 0.7.19

package/src/core/runtime/tenantDataPurge.js

@@ -0,0 +1,166 @@
+"use strict";
+
+/**
+ * Exclusão dos dados de uma organização cuja licença do App terminou há mais
+ * de 30 dias (F1.5). A Central decide o que é devido; o runtime só executa o
+ * que ela entrega, autenticado pela credencial do deployment.
+ *
+ * Escopos:
+ * - `tenant` (App multi-tenant, runtime compartilhado): apaga os documentos
+ *   com o tenantId da organização nos models com escopo `tenant` ou `user`, e
+ *   os e-mails transacionais desse tenant. Models `system`/`legacy`, que não
+ *   identificam a organização, ficam intactos e saem no relatório.
+ * - `full` (App single-tenant, runtime dedicado): apaga os documentos de todos
+ *   os models do App, exceto os de escopo `system` (configuração do App), além
+ *   dos e-mails transacionais e dos segredos do runtime. O runtime continua no
+ *   ar para o próximo licenciamento.
+ *
+ * Só uma réplica executa por vez (trava no MongoDB).
+ */
+const crypto = require("node:crypto");
+const axios = require("axios");
+const mongoose = require("../database/mongoose");
+const registry = require("../registry");
+const ctx = require("../context");
+const { dataScope, tenantField } = require("../tenancy");
+const { getBaseUrl, getTimeout } = require("../utils/activationProvider");
+const { operationalRequestHeaders } = require("../utils/instanceActivation");
+const { isLocalRuntime } = require("./localDevelopment");
+
+const PURGES_PATH = "/integracao/runtime/data-purges";
+const LOCKS = "oon_runtime_locks";
+const LOCK_ID = "tenant-data-purge";
+const LOCK_MS = 30 * 60 * 1000;
+const DEFAULT_INTERVAL_MS = 6 * 60 * 60 * 1000;
+const EMAIL_DISPATCHES = "oon_email_dispatches";
+const SECRETS = "oon_secrets";
+
+const state = { owner: `${process.pid}:${crypto.randomUUID()}`, timer: null, running: false, inFlight: null };
+
+function hasField(entry, field) {
+  return Boolean(entry?.mongooseModel?.schema?.path?.(field));
+}
+
+async function executePurge({ scope, tenantId }, { entries = registry.listModels(), connection = mongoose.connection } = {}) {
+  if (!["tenant", "full"].includes(scope)) throw new Error(`Escopo de exclusão inválido: ${scope}`);
+  if (scope === "tenant" && !tenantId) throw new Error("Exclusão por organização exige tenantId.");
+  const deleted = {};
+  const skipped = [];
+  for (const entry of entries) {
+    const model = entry?.mongooseModel;
+    if (!model) continue;
+    const kind = dataScope(entry);
+    let filter = null;
+    if (scope === "full") {
+      if (kind !== "system") filter = {};
+    } else if (["tenant", "user"].includes(kind) && hasField(entry, tenantField(entry))) {
+      filter = { [tenantField(entry)]: tenantId };
+    }
+    if (!filter) { skipped.push(entry.name); continue; }
+    // eslint-disable-next-line no-await-in-loop
+    const result = await model.deleteMany(filter);
+    deleted[entry.name] = Number(result?.deletedCount || 0);
+  }
+  const emails = connection.collection(EMAIL_DISPATCHES);
+  const emailFilter = scope === "full" ? {} : { scopeKey: { $regex: `:tenant:${String(tenantId).replace(/[^A-Za-z0-9_-]/g, "")}$` } };
+  deleted.emailDispatches = Number((await emails.deleteMany(emailFilter))?.deletedCount || 0);
+  if (scope === "full") {
+    deleted.secrets = Number((await connection.collection(SECRETS).deleteMany({}))?.deletedCount || 0);
+  }
+  return { deleted, skipped };
+}
+
+async function acquireLock(connection) {
+  const locks = connection.collection(LOCKS);
+  const expiresAt = new Date(Date.now() + LOCK_MS);
+  try {
+    await locks.insertOne({ _id: LOCK_ID, owner: state.owner, expiresAt });
+    return true;
+  } catch (error) {
+    if (error?.code !== 11000) throw error;
+  }
+  const result = await locks.updateOne({ _id: LOCK_ID, expiresAt: { $lte: new Date() } }, { $set: { owner: state.owner, expiresAt } });
+  return Number(result?.modifiedCount || 0) > 0;
+}
+
+async function releaseLock(connection) {
+  await connection.collection(LOCKS).deleteOne({ _id: LOCK_ID, owner: state.owner });
+}
+
+async function runOnce({
+  http = axios,
+  connection = mongoose.connection,
+  headers = () => operationalRequestHeaders({}),
+  baseUrl = () => getBaseUrl(),
+  execute = executePurge,
+  log = console,
+} = {}) {
+  if (connection?.readyState !== 1) return { skipped: "database_unavailable" };
+  if (!await acquireLock(connection)) return { skipped: "locked" };
+  try {
+    const requestHeaders = await headers();
+    const base = baseUrl();
+    const response = await http.get(`${base}${PURGES_PATH}`, { headers: requestHeaders, timeout: getTimeout(), maxRedirects: 0 });
+    const purges = Array.isArray(response?.data?.purges) ? response.data.purges : [];
+    const results = [];
+    for (const purge of purges) {
+      let body;
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        const report = await execute({ scope: purge.scope, tenantId: purge.tenantId }, { connection });
+        body = { ok: true, report };
+        log.log(`[OonCore] Dados da organização ${purge.tenantId} excluídos (${purge.scope}).`);
+      } catch (error) {
+        body = { ok: false, error: String(error?.message || error).slice(0, 500) };
+        log.error(`[OonCore] Falha ao excluir dados da organização ${purge.tenantId}: ${body.error}`);
+      }
+      // eslint-disable-next-line no-await-in-loop
+      await http.post(`${base}${PURGES_PATH}/${encodeURIComponent(purge.id)}/complete`, body, { headers: requestHeaders, timeout: getTimeout(), maxRedirects: 0 });
+      results.push({ id: purge.id, ok: body.ok });
+    }
+    return { processed: results };
+  } finally {
+    await releaseLock(connection);
+  }
+}
+
+function intervalMs() {
+  const value = Number(process.env.OON_DATA_PURGE_INTERVAL_MS);
+  return Number.isSafeInteger(value) && value >= 60000 ? value : DEFAULT_INTERVAL_MS;
+}
+
+function enabled() {
+  if (isLocalRuntime()) return false;
+  if (String(process.env.OON_DATA_PURGE || "true").toLowerCase() === "false") return false;
+  // A própria Central (root) e Apps globais não recebem licenças de organizações.
+  if (ctx.config.ecosystem?.role === "root") return false;
+  const tenancy = ctx.config.tenancyModel || ctx.config.ecosystem?.tenancyModel;
+  return tenancy !== "none";
+}
+
+function schedule(delay) {
+  if (!state.running) return;
+  state.timer = setTimeout(() => {
+    state.inFlight = runOnce()
+      .catch((error) => console.warn(`[OonCore] Verificação de exclusões de dados falhou: ${error?.message || error}`))
+      .finally(() => { state.inFlight = null; schedule(intervalMs()); });
+  }, delay);
+  state.timer.unref?.();
+}
+
+function startTenantDataPurges() {
+  if (state.running || !enabled()) return false;
+  state.running = true;
+  // Primeira verificação alguns minutos após o boot, com variação entre réplicas.
+  schedule(120000 + Math.floor(Math.random() * 60000));
+  return true;
+}
+
+async function stopTenantDataPurges() {
+  state.running = false;
+  clearTimeout(state.timer);
+  state.timer = null;
+  if (state.inFlight) await state.inFlight;
+}
+
+module.exports = { executePurge, runOnce, startTenantDataPurges, stopTenantDataPurges, PURGES_PATH, LOCKS };

package/src/core/storage/files.js

@@ -0,0 +1,131 @@
+"use strict";
+
+/*
+ * F4.8 — Armazenamento compartilhado de arquivos.
+ *
+ * Substitui a pasta local `uploads` (que é de cada pod e some no reinício) por
+ * GridFS no MongoDB do próprio App: um arquivo gravado por uma réplica é lido
+ * por qualquer outra e sobrevive a reinícios e novas publicações. Cada arquivo
+ * pertence a um tenant; leitura, listagem e exclusão exigem o mesmo tenant,
+ * salvo quando o chamador declara `global: true` (Apps sem tenancy).
+ */
+
+const { Readable } = require("node:stream");
+const mongoose = require("../database/mongoose");
+
+const BUCKET = "oon_files";
+const DEFAULT_MAX_BYTES = 25 * 1024 * 1024;
+
+function storageError(message, code, statusCode) {
+  return Object.assign(new Error(message), { code, statusCode });
+}
+
+function bucket(connection = mongoose.connection) {
+  if (!connection?.db) throw storageError("Banco de dados indisponível para arquivos.", "FILE_STORAGE_UNAVAILABLE", 503);
+  return new mongoose.mongo.GridFSBucket(connection.db, { bucketName: BUCKET });
+}
+
+function scope({ tenantId, global = false } = {}) {
+  if (global === true) return { global: true, tenantId: null };
+  const value = tenantId === undefined || tenantId === null ? "" : String(tenantId);
+  if (!value) throw storageError("Tenant obrigatório para arquivos.", "FILE_TENANT_REQUIRED", 400);
+  return { global: false, tenantId: value };
+}
+
+function objectId(id) {
+  try { return new mongoose.Types.ObjectId(String(id)); } catch { throw storageError("Arquivo não encontrado.", "FILE_NOT_FOUND", 404); }
+}
+
+function info(doc) {
+  return { id: String(doc._id), filename: doc.filename, length: doc.length, contentType: doc.metadata?.contentType || "application/octet-stream",
+    tenantId: doc.metadata?.tenantId || null, metadata: doc.metadata?.custom || {}, uploadDate: doc.uploadDate };
+}
+
+/** Grava um arquivo (Buffer, string ou Readable) e devolve os metadados. */
+async function saveFile({ data, filename, contentType = "application/octet-stream", metadata = {}, maxBytes = DEFAULT_MAX_BYTES, ...owner } = {}, options = {}) {
+  const target = scope(owner);
+  const name = String(filename || "").trim();
+  if (!name || name.length > 255 || /[\\/\0]/.test(name)) throw storageError("Nome de arquivo inválido.", "FILE_NAME_INVALID", 422);
+  const source = data instanceof Readable ? data : Readable.from(Buffer.isBuffer(data) ? [data] : [Buffer.from(String(data ?? ""))]);
+  const upload = bucket(options.connection).openUploadStream(name, { metadata: { tenantId: target.tenantId, contentType: String(contentType), custom: metadata } });
+  let size = 0;
+  await new Promise((resolve, reject) => {
+    const fail = (error) => { source.destroy(); upload.abort().catch(() => {}).finally(() => reject(error)); };
+    source.on("data", (chunk) => {
+      size += chunk.length;
+      if (size > maxBytes) return fail(storageError(`Arquivo maior que o limite de ${maxBytes} bytes.`, "FILE_TOO_LARGE", 413));
+      if (!upload.write(chunk)) source.pause();
+    });
+    upload.on("drain", () => source.resume());
+    source.on("error", fail);
+    upload.on("error", reject);
+    upload.on("finish", resolve);
+    source.on("end", () => { if (size <= maxBytes) upload.end(); });
+  });
+  return getFileInfo(upload.id, target, options);
+}
+
+async function findScoped(id, owner, options) {
+  const target = scope(owner);
+  const [doc] = await bucket(options.connection).find({ _id: objectId(id), ...(target.global ? {} : { "metadata.tenantId": target.tenantId }) }).limit(1).toArray();
+  if (!doc) throw storageError("Arquivo não encontrado.", "FILE_NOT_FOUND", 404);
+  return doc;
+}
+
+async function getFileInfo(id, owner = {}, options = {}) {
+  return info(await findScoped(id, owner, options));
+}
+
+/** Abre o conteúdo para leitura em stream, no escopo do tenant. */
+async function openFile(id, owner = {}, options = {}) {
+  const doc = await findScoped(id, owner, options);
+  return { file: info(doc), stream: bucket(options.connection).openDownloadStream(doc._id) };
+}
+
+async function readFile(id, owner = {}, options = {}) {
+  const { file, stream } = await openFile(id, owner, options);
+  const chunks = [];
+  for await (const chunk of stream) chunks.push(chunk);
+  return { file, data: Buffer.concat(chunks) };
+}
+
+async function listFiles(owner = {}, { limit = 100, filename } = {}, options = {}) {
+  const target = scope(owner);
+  const filter = { ...(target.global ? {} : { "metadata.tenantId": target.tenantId }), ...(filename ? { filename: String(filename) } : {}) };
+  const docs = await bucket(options.connection).find(filter).sort({ uploadDate: -1 }).limit(Math.min(Math.max(1, Number(limit) || 100), 500)).toArray();
+  return docs.map(info);
+}
+
+async function deleteFile(id, owner = {}, options = {}) {
+  const doc = await findScoped(id, owner, options);
+  await bucket(options.connection).delete(doc._id);
+  return { deleted: true, id: String(doc._id) };
+}
+
+/** Responde a requisição com o arquivo (download ou exibição). */
+async function sendFile(res, id, owner = {}, { download = false } = {}, options = {}) {
+  const { file, stream } = await openFile(id, owner, options);
+  res.setHeader("Content-Type", file.contentType);
+  res.setHeader("Content-Length", String(file.length));
+  res.setHeader("X-Content-Type-Options", "nosniff");
+  res.setHeader("Content-Disposition", `${download ? "attachment" : "inline"}; filename*=UTF-8''${encodeURIComponent(file.filename)}`);
+  await new Promise((resolve, reject) => { stream.on("error", reject); res.on("finish", resolve); stream.pipe(res); });
+  return file;
+}
+
+/** Atalho com o tenant do request autenticado (req.accessContext). */
+function forRequest(req) {
+  const tenantId = req?.accessContext?.tenantId;
+  const owner = tenantId ? { tenantId } : { global: true };
+  return {
+    save: (input) => saveFile({ ...input, ...owner }),
+    info: (id) => getFileInfo(id, owner),
+    open: (id) => openFile(id, owner),
+    read: (id) => readFile(id, owner),
+    list: (query) => listFiles(owner, query),
+    remove: (id) => deleteFile(id, owner),
+    send: (res, id, opts) => sendFile(res, id, owner, opts),
+  };
+}
+
+module.exports = { BUCKET, DEFAULT_MAX_BYTES, saveFile, getFileInfo, openFile, readFile, listFiles, deleteFile, sendFile, forRequest };

package/src/core/usage/reporter.js

@@ -0,0 +1,193 @@
+"use strict";
+
+/*
+ * F5.3/F5.5 — consumo do App para os limites de uso do plano.
+ *
+ * `usage.record(metric, quantidade, { tenantId })` acumula em memória e, a
+ * cada `OON_USAGE_FLUSH_MS` (padrão 15 s), fecha um lote com id único. O lote
+ * é gravado na outbox `oon_usage_outbox` do MongoDB do App antes do envio,
+ * então sobrevive a reinício e qualquer réplica pode reenviá-lo. A Central
+ * conta cada id uma vez só, mesmo se o lote for reenviado.
+ *
+ * `usage.assertAvailable(metric, { tenantId })` recusa a operação (423
+ * USAGE_LIMIT_REACHED) quando o plano bloqueia ao atingir o limite. O estado
+ * vem da Central (resposta do lote ou consulta, cache de 60 s) somado ao que
+ * ainda não foi enviado. Se a Central não responde, a operação segue: o
+ * consumo continua registrado e o limite é aplicado quando ela voltar.
+ */
+
+const crypto = require("node:crypto");
+const axios = require("axios");
+const mongoose = require("../database/mongoose");
+const { operationalRequestHeaders } = require("../utils/instanceActivation");
+const { getBaseUrl, getTimeout } = require("../utils/activationProvider");
+const { isLocalRuntime } = require("../runtime/localDevelopment");
+
+const METRIC = /^[a-z][a-z0-9_.-]{1,62}$/;
+const COLLECTION = "oon_usage_outbox";
+const STATE_TTL_MS = 60 * 1000;
+const LEASE_MS = 30 * 1000;
+const MAX_ATTEMPTS = 20;
+const owner = `${process.pid}:${crypto.randomUUID()}`;
+
+const buffers = new Map(); // tenantId -> Map(metric -> quantity)
+const memoryOutbox = []; // sem banco conectado
+const states = new Map(); // tenantId -> { at, metrics: Map }
+let timer = null;
+let flushing = null;
+
+function flushInterval() {
+  const value = Number(process.env.OON_USAGE_FLUSH_MS);
+  return Number.isSafeInteger(value) && value >= 1000 ? value : 15000;
+}
+function usageError(message, code, statusCode, details) {
+  return Object.assign(new Error(message), { code, statusCode, ...(details ? { details } : {}) });
+}
+function collection() {
+  return mongoose.connection?.readyState === 1 && mongoose.connection.db ? mongoose.connection.db.collection(COLLECTION) : null;
+}
+function key(tenantId) {
+  const value = tenantId === undefined || tenantId === null ? "" : String(tenantId);
+  if (!value) throw usageError("Tenant obrigatório para registrar consumo.", "USAGE_TENANT_REQUIRED", 400);
+  return value;
+}
+function ensureTimer() {
+  if (timer) return;
+  timer = setInterval(() => { flush().catch(() => {}); }, flushInterval());
+  timer.unref?.();
+}
+
+/** Registra consumo (acumulado e enviado em lote). */
+function record(metric, quantity = 1, { tenantId } = {}) {
+  if (!METRIC.test(String(metric || ""))) throw usageError("Métrica de uso inválida.", "USAGE_METRIC_INVALID", 422, { metric });
+  if (!Number.isSafeInteger(quantity) || quantity < 1) throw usageError("Quantidade de uso inválida.", "USAGE_QUANTITY_INVALID", 422);
+  if (isLocalRuntime()) return { recorded: false, reason: "local" };
+  const tenant = key(tenantId);
+  const bucket = buffers.get(tenant) || new Map();
+  bucket.set(metric, (bucket.get(metric) || 0) + quantity);
+  buffers.set(tenant, bucket);
+  ensureTimer();
+  return { recorded: true };
+}
+
+function pendingFor(tenantId, metric) {
+  return buffers.get(String(tenantId))?.get(metric) || 0;
+}
+
+/** Fecha os lotes em memória, grava na outbox e envia os pendentes. */
+async function flush() {
+  if (flushing) return flushing;
+  flushing = (async () => {
+    const at = new Date();
+    for (const [tenantId, bucket] of [...buffers.entries()]) {
+      buffers.delete(tenantId);
+      const items = [...bucket.entries()].map(([metric, quantity]) => ({ metric, quantity }));
+      if (!items.length) continue;
+      const batch = { _id: crypto.randomUUID(), tenantId, items, status: "pending", attempts: 0, nextAttemptAt: at, createdAt: at };
+      const outbox = collection();
+      if (outbox) await outbox.insertOne(batch); else memoryOutbox.push(batch);
+    }
+    return deliverPending();
+  })().finally(() => { flushing = null; });
+  return flushing;
+}
+
+async function send(batch) {
+  const response = await axios.post(`${getBaseUrl()}/integracao/app-usage/batches`,
+    { tenantId: batch.tenantId, batchId: batch._id, items: batch.items },
+    { headers: await operationalRequestHeaders({ tenantId: batch.tenantId, correlationId: `usage:${batch._id}` }), timeout: getTimeout(), maxRedirects: 0 });
+  remember(batch.tenantId, response.data);
+  return response.data;
+}
+
+function retryable(error) {
+  const status = error?.response?.status;
+  return !status || status >= 500 || status === 429 || status === 408;
+}
+
+async function deliverPending({ limit = 20 } = {}) {
+  const outbox = collection();
+  let sent = 0, failed = 0;
+  if (!outbox) {
+    for (const batch of memoryOutbox.splice(0, limit)) {
+      try { await send(batch); sent++; } catch (error) { failed++; if (retryable(error)) memoryOutbox.push(batch); }
+    }
+    return { sent, failed };
+  }
+  for (let i = 0; i < limit; i++) {
+    const now = new Date();
+    const batch = await outbox.findOneAndUpdate(
+      { status: "pending", nextAttemptAt: { $lte: now }, $or: [{ leaseUntil: { $exists: false } }, { leaseUntil: { $lt: now } }] },
+      { $set: { leaseUntil: new Date(+now + LEASE_MS), leaseOwner: owner } }, { sort: { nextAttemptAt: 1 }, returnDocument: "after" });
+    const doc = batch?.value === undefined ? batch : batch.value;
+    if (!doc) break;
+    try {
+      await send(doc);
+      await outbox.deleteOne({ _id: doc._id, leaseOwner: owner });
+      sent++;
+    } catch (error) {
+      failed++;
+      const attempts = (doc.attempts || 0) + 1;
+      const terminal = !retryable(error) || attempts >= MAX_ATTEMPTS;
+      await outbox.updateOne({ _id: doc._id, leaseOwner: owner }, {
+        $set: { attempts, status: terminal ? "rejected" : "pending", nextAttemptAt: new Date(Date.now() + Math.min(3600000, 2 ** attempts * 1000)),
+          lastError: { status: error?.response?.status || null, code: error?.response?.data?.code || error?.code || null, at: new Date() } },
+        $unset: { leaseUntil: 1, leaseOwner: 1 } });
+    }
+  }
+  return { sent, failed };
+}
+
+function remember(tenantId, data) {
+  if (!data || !Array.isArray(data.metrics)) return;
+  states.set(String(tenantId), { at: Date.now(), metrics: new Map(data.metrics.map((m) => [m.metric, m])) });
+}
+
+async function state(tenantId, { refresh = false } = {}) {
+  const tenant = key(tenantId);
+  const cached = states.get(tenant);
+  if (!refresh && cached && Date.now() - cached.at < STATE_TTL_MS) return cached;
+  const response = await axios.get(`${getBaseUrl()}/integracao/app-usage/state`, {
+    params: { tenantId: tenant }, headers: await operationalRequestHeaders({ tenantId: tenant, correlationId: `usage-state:${crypto.randomUUID()}` }),
+    timeout: getTimeout(), maxRedirects: 0 });
+  remember(tenant, response.data);
+  return states.get(tenant) || { at: Date.now(), metrics: new Map() };
+}
+
+/** Recusa a operação quando a métrica bloqueia ao atingir o limite do ciclo. */
+async function assertAvailable(metric, { tenantId, quantity = 1 } = {}) {
+  if (isLocalRuntime()) return { available: true, reason: "local" };
+  let current;
+  try { current = await state(tenantId); } catch { return { available: true, reason: "central_unavailable" }; }
+  const limit = current.metrics.get(metric);
+  if (!limit || limit.onLimit !== "block") return { available: true };
+  const used = (limit.used || 0) + pendingFor(tenantId, metric);
+  if (used + quantity > limit.included) {
+    throw usageError(`O limite de ${limit.label || metric} do plano foi atingido neste ciclo (${limit.included}). O uso volta no próximo ciclo ou com a troca de plano.`,
+      "USAGE_LIMIT_REACHED", 423, { metric, used, included: limit.included, periodEndAt: limit.periodEndAt || null });
+  }
+  return { available: true, remaining: limit.included - used };
+}
+
+/** Middleware: confere o limite antes e registra 1 uso quando a resposta for 2xx. */
+function limit(metric, { quantity = 1 } = {}) {
+  return async (req, res, next) => {
+    const tenantId = req.accessContext?.tenantId;
+    try {
+      await assertAvailable(metric, { tenantId, quantity });
+      res.on("finish", () => { if (res.statusCode >= 200 && res.statusCode < 300) { try { record(metric, quantity, { tenantId }); } catch { /* sem tenant */ } } });
+      return next();
+    } catch (error) {
+      return res.status(error.statusCode || 500).json({ code: error.code, message: error.message, details: error.details });
+    }
+  };
+}
+
+async function stop() {
+  if (timer) { clearInterval(timer); timer = null; }
+  if (buffers.size) await flush().catch(() => {});
+}
+
+function reset() { buffers.clear(); memoryOutbox.length = 0; states.clear(); if (timer) { clearInterval(timer); timer = null; } }
+
+module.exports = { COLLECTION, record, flush, deliverPending, state, assertAvailable, limit, stop, reset };

package/src/core/utils/instanceActivation.js

@@ -284,16 +284,26 @@ async function ensureInstance() {
   );
 
   if (!instance) {
-    instance = await Instancia.create({
-      ecosystemRole: role(),
-      status: "nao_ativada",
-      appCode: getAppCode(),
-      ambiente: ambiente(),
-      ecosystemUrl: process.env.CENTRAL_ATIVACAO_URL,
-      publicUrl: process.env.PUBLIC_APP_URL,
-      coreVersion: version(),
-      appVersion: version(),
-    });
+    try {
+      instance = await Instancia.create({
+        ecosystemRole: role(),
+        status: "nao_ativada",
+        appCode: getAppCode(),
+        ambiente: ambiente(),
+        ecosystemUrl: process.env.CENTRAL_ATIVACAO_URL,
+        publicUrl: process.env.PUBLIC_APP_URL,
+        coreVersion: version(),
+        appVersion: version(),
+      });
+    } catch (error) {
+      // Outra réplica criou a instância entre o findOne e o create; o índice
+      // único de singletonKey impede a duplicidade, então basta reler.
+      if (error?.code !== 11000) throw error;
+      instance = await Instancia.findOne().select(
+        "+credentialEncrypted +credentialIv +credentialAuthTag +activationRequest",
+      );
+      if (!instance) throw error;
+    }
   }
 
   if (instance.ecosystemRole !== role()) {

package/src/delivery/buildImage.js

@@ -32,6 +32,7 @@ COPY --from=frontend /src/frontend/dist /usr/share/nginx/html
 COPY .oon-delivery/nginx.conf /etc/nginx/oon.conf
 COPY .oon-delivery/supervisor.js /supervisor.js
 COPY .oon-delivery/launchRuntime.js .oon-delivery/validateImage.js /oon-delivery/
+COPY .oon-delivery/errors.js /deploy/contracts/errors.js
 COPY .oon-delivery/entrypoint.sh /entrypoint.sh
 RUN chmod +x /entrypoint.sh && mkdir -p /app/backend/uploads /run/nginx && chown -R node:node /app/backend/uploads
 EXPOSE 8080
@@ -111,6 +112,8 @@ function prepareDeliveryFiles(workspace) {
   fs.mkdirSync(target, { recursive: true });
   prepareAppManifest(workspace, target);
   for (const file of ["supervisor.js", "launchRuntime.js", "validateImage.js"]) fs.copyFileSync(path.join(__dirname, file), path.join(target, file));
+  // launchRuntime.js requires ../deploy/contracts/errors (sanitizeMessage).
+  fs.copyFileSync(path.join(__dirname, "../deploy/contracts/errors.js"), path.join(target, "errors.js"));
   fs.writeFileSync(path.join(target, "Dockerfile"), DOCKERFILE);
   fs.writeFileSync(path.join(target, "nginx.conf"), NGINX);
   fs.writeFileSync(path.join(target, "entrypoint.sh"), ENTRYPOINT, {

package/src/delivery/launchRuntime.js

@@ -1,13 +1,31 @@
 "use strict";
 const { createRequire } = require("node:module");
 const { classify } = require("./validateImage");
-const runtimeRequire = createRequire("/app/backend/package.json");
-// Invoke the public API of the SDK INSIDE the image; do not replace the app's
-// dependency version. Include the error class so SyntaxError is not lost by an
-// older CLI that prints only error.message. Never print the raw error/stack.
-Promise.resolve().then(() => runtimeRequire("@oondemand/oon-core-back").start({ cwd: "/app/backend" }))
-  .catch((error) => {
-    const diagnostic = classify(`${error?.name || "Error"}: ${error?.message || ""}`);
-    console.error(`OON_STARTUP_FAILURE ${JSON.stringify(diagnostic)}`);
-    process.exit(1);
-  });
+// Copied next to this file in the image (/deploy/contracts/errors.js) so the
+// same relative path resolves in the repository and inside the image.
+const { sanitizeMessage } = require("../deploy/contracts/errors");
+
+// Manifest errors (e.g. AppManifestError) carry the actionable detail in
+// issues. Print only path and sanitized message; never the stack or raw error.
+function startupIssueLines(error) {
+  if (!Array.isArray(error?.issues)) return [];
+  return error.issues.map((issue) => ` - ${sanitizeMessage(issue?.path || "$")}: ${sanitizeMessage(issue?.message)}`);
+}
+
+function launch() {
+  const runtimeRequire = createRequire("/app/backend/package.json");
+  // Invoke the public API of the SDK INSIDE the image; do not replace the app's
+  // dependency version. Include the error class so SyntaxError is not lost by an
+  // older CLI that prints only error.message. Never print the raw error/stack.
+  Promise.resolve().then(() => runtimeRequire("@oondemand/oon-core-back").start({ cwd: "/app/backend" }))
+    .catch((error) => {
+      for (const line of startupIssueLines(error)) console.error(line);
+      const diagnostic = classify(`${error?.name || "Error"}: ${error?.message || ""}`);
+      console.error(`OON_STARTUP_FAILURE ${JSON.stringify(diagnostic)}`);
+      process.exit(1);
+    });
+}
+
+if (require.main === module) launch();
+
+module.exports = { startupIssueLines };