@oondemand/oon-core-back 0.7.1 → 0.7.3

package/README.md

@@ -73,3 +73,21 @@ defineModel({
 ```
 
 Use `populateRefs: true` para todas as referências da model ou informe uma lista explícita. O CRUD devolve somente `_id` e campos usuais de identificação, como nome, razão social, descrição, código, e-mail e campos pesquisáveis da model referenciada. Exportações mantêm os identificadores originais.
+
+## Requisições com corpo sensível
+
+Rotas privadas declaradas com `defineRoutes` que recebem credenciais ou outros segredos devem marcar a operação mutante com `sensitiveBody: true`:
+
+```js
+defineRoutes("/integracao", (router) => {
+  router.private.put("/credencial", {
+    permission: "integracao.config.write",
+    sensitiveBody: true,
+  }, async (req, res) => {
+    // Validar e persistir com segurança; devolver somente metadados sanitizados.
+    res.json({ configured: true });
+  });
+});
+```
+
+O Core omite todo o corpo de entrada e resposta no `requestLog` para esse método e caminho, inclusive se a rota responder erro. Método, URL, status, usuário e correlationId continuam registrados. A opção não cifra o banco nem substitui autorização, validação e respostas sanitizadas. Nunca retorne o segredo pela rota, pelo erro ou pela auditoria da mutação. A opção não se aplica automaticamente a endpoints de CRUD gerados.

package/bin/build-delivery-image.js

@@ -8,4 +8,6 @@ const workspace = path.resolve(flag("--workspace") || process.cwd());
 const tag = flag("--tag");
 const output = flag("--output");
 if (!tag || !output) { console.error("--tag e --output são obrigatórios"); process.exit(2); }
-buildImage({ workspace, tag, output: path.resolve(output) });
+buildImage({ workspace, tag, output: path.resolve(output), diagnosticOutput: flag("--diagnostic-output") })
+  .catch((error) => { console.error(error.code || "IMAGE_BUILD_FAILED"); process.exitCode = 1; });
+

package/bin/check-delivery-source.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+"use strict";
+const path = require("node:path");
+const { testSource } = require("../src/delivery/testSource");
+function flag(name) { const i = process.argv.indexOf(name); return i < 0 ? undefined : process.argv[i + 1]; }
+const output = flag("--diagnostic-output");
+if (!output) throw new Error("--diagnostic-output é obrigatório");
+const result = testSource({ workspace: path.resolve(flag("--workspace") || process.cwd()), output });
+console.log(JSON.stringify({ status: result.status, suites: result.suites }));
+if (result.status === "failed") process.exitCode = 1;

package/package.json

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

package/src/core/define.js

@@ -161,6 +161,9 @@ function defineRoutes(basePath, builder) {
     const required = opts.permission || opts.permissions;
     if (required) chain.push(requirePermission(required));
     else chain.push(rbac(opts.roles || []));
+    if (["post", "put", "patch", "delete"].includes(method) && opts.sensitiveBody === true) {
+      registry.registerSensitiveRequest(method, basePath, path);
+    }
     if (["post", "put", "patch", "delete"].includes(method) && opts.audit) {
       chain.push(mutationAudit(opts.audit));
     }

package/src/core/middlewares/requestLog.js

@@ -1,4 +1,5 @@
 const Log = require("../models/Log");
+const registry = require("../registry");
 
 /**
  * Registra requisições mutantes (não-GET) na model interna Log.
@@ -7,18 +8,19 @@ const Log = require("../models/Log");
 const requestLog = async (req, res, next) => {
   if (req.method === "GET") return next();
 
+  const sensitiveBody = await registry.isSensitiveRequest(req.method, req.url || req.originalUrl);
   const log = new Log({
     usuario: req.usuario || null,
     endpoint: req.originalUrl,
     metodo: req.method,
     ip: req.ip || req.headers["x-forwarded-for"] || req.connection?.remoteAddress,
     correlationId: req.correlationId,
-    dadosRequisicao: req.body,
+    dadosRequisicao: sensitiveBody ? { omitted: true } : req.body,
   });
 
   res.on("finish", () => {
     log.statusResposta = res.statusCode;
-    log.dadosResposta = res.locals.body || null;
+    log.dadosResposta = sensitiveBody ? null : (res.locals.body || null);
     log.save().catch(() => {});
   });
 

package/src/core/registry.js

@@ -1,3 +1,5 @@
+const express = require("express");
+
 /**
  * Model Registry — coração técnico do Core (Seção 17).
  *
@@ -17,6 +19,7 @@ const store = {
   pipelines: new Map(),
   menus: [],
   features: new Map(),
+  sensitiveRequests: [], // Express routers used only to classify sensitive paths
 };
 
 function registerModel(entry) {
@@ -68,6 +71,37 @@ const simpleRegister = (mapName) => (key, value) => {
 };
 const simpleList = (mapName) => () => [...store[mapName].values()];
 
+function registerSensitiveRequest(method, basePath, path) {
+  // Use the same mount and route semantics as defineRoutes/createApp.
+  const route = express.Router();
+  route[method.toLowerCase()](path, (req) => req.sensitiveMatch());
+  const mounted = express.Router();
+  mounted.use(basePath, route);
+  store.sensitiveRequests.push(mounted);
+}
+
+async function isSensitiveRequest(method, url) {
+  for (const router of store.sensitiveRequests) {
+    const matched = await new Promise((resolve) => {
+      // A separate request prevents classification from modifying the real request.
+      const request = {
+        method: String(method).toUpperCase(),
+        url: String(url || '/'),
+        headers: {},
+        sensitiveMatch: () => resolve(true),
+      };
+      // Routing errors fail closed: omit bodies instead of risking disclosure.
+      try {
+        router.handle(request, {}, (error) => resolve(Boolean(error)));
+      } catch {
+        resolve(true);
+      }
+    });
+    if (matched) return true;
+  }
+  return false;
+}
+
 function registerMenu(item) {
   store.menus.push(item);
 }
@@ -82,6 +116,7 @@ function reset() {
   store.pipelines.clear();
   store.menus.length = 0;
   store.features.clear();
+  store.sensitiveRequests.length = 0;
 }
 
 module.exports = {
@@ -104,6 +139,8 @@ module.exports = {
   registerFeature: simpleRegister("features"),
   listFeatures: simpleList("features"),
   registerMenu,
+  registerSensitiveRequest,
+  isSensitiveRequest,
   listMenus: () => store.menus,
   reset,
 };

package/src/delivery/buildImage.js

@@ -3,6 +3,7 @@
 const fs = require("node:fs");
 const path = require("node:path");
 const { run } = require("./command");
+const { validateImage } = require("./validateImage");
 
 const DOCKERFILE = `# syntax=docker/dockerfile:1.7
 FROM node:20-alpine AS frontend
@@ -28,19 +29,32 @@ ENV NODE_ENV=production
 COPY --from=backend /app/backend /app/backend
 COPY .oon-delivery/app-manifest/ /app/
 COPY --from=frontend /src/frontend/dist /usr/share/nginx/html
-COPY .oon-delivery/nginx.conf /etc/nginx/http.d/default.conf
+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/entrypoint.sh /entrypoint.sh
-RUN chmod +x /entrypoint.sh && mkdir -p /app/backend/uploads /run/nginx
+RUN chmod +x /entrypoint.sh && mkdir -p /app/backend/uploads /run/nginx && chown -R node:node /app/backend/uploads
 EXPOSE 8080
 HEALTHCHECK --interval=30s --timeout=5s --start-period=30s --retries=3 CMD curl -fsS http://127.0.0.1:8080/health/live || exit 1
 ENTRYPOINT ["/entrypoint.sh"]
 `;
 
-const NGINX = `server {
+const NGINX = `pid /tmp/nginx.pid;
+error_log /dev/stderr;
+events {}
+http {
+  include /etc/nginx/mime.types;
+  access_log /dev/stdout;
+  client_body_temp_path /tmp/client_temp;
+  proxy_temp_path /tmp/proxy_temp;
+  fastcgi_temp_path /tmp/fastcgi_temp;
+  uwsgi_temp_path /tmp/uwsgi_temp;
+  scgi_temp_path /tmp/scgi_temp;
+server {
   listen 8080;
   server_name _;
   root /usr/share/nginx/html;
-  location = /health/live { access_log off; return 200 'ok'; add_header Content-Type text/plain; }
+  location = /health/live { access_log off; proxy_pass http://127.0.0.1:4000/; }
   location /api/ {
     proxy_pass http://127.0.0.1:4000/;
     proxy_http_version 1.1;
@@ -50,16 +64,12 @@ const NGINX = `server {
   }
   location / { try_files $uri $uri/ /index.html; }
 }
+}
 `;
 
 const ENTRYPOINT = `#!/bin/sh
 set -eu
-cd /app/backend
-export PORT=4000
-./node_modules/.bin/oonCore-back start &
-backend_pid=$!
-trap 'kill $backend_pid 2>/dev/null || true' TERM INT EXIT
-exec nginx -g 'daemon off;'
+exec node /supervisor.js
 `;
 
 function prepareAppManifest(workspace, deliveryDirectory) {
@@ -96,19 +106,36 @@ function prepareAppManifest(workspace, deliveryDirectory) {
 
 function prepareDeliveryFiles(workspace) {
   const target = path.join(workspace, ".oon-delivery");
+  if (fs.existsSync(target) && fs.lstatSync(target).isSymbolicLink()) throw new Error("Diretório de delivery não pode ser symlink.");
+  fs.rmSync(target, { recursive: true, force: true });
   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));
   fs.writeFileSync(path.join(target, "Dockerfile"), DOCKERFILE);
   fs.writeFileSync(path.join(target, "nginx.conf"), NGINX);
   fs.writeFileSync(path.join(target, "entrypoint.sh"), ENTRYPOINT, {
     mode: 0o755,
   });
+  // Dockerfile-specific ignore rules win over the root ignore file. Preserve
+  // user rules, then append mandatory exclusions so local installs and secrets
+  // cannot overwrite production dependencies or leak into the final image.
+  const userIgnore = path.join(workspace, ".dockerignore");
+  const ignore = fs.existsSync(userIgnore) ? fs.readFileSync(userIgnore, "utf8") : "";
+  fs.writeFileSync(path.join(target, "Dockerfile.dockerignore"), ignore + "\n**/node_modules\n**/.git\n**/.env\n**/.env.*\n**/*.pem\n**/*.key\n**/.npmrc\n!frontend/.env.production\n");
   return path.join(target, "Dockerfile");
 }
 
-function buildImage({ workspace, tag, output }) {
+async function buildImage({ workspace, tag, output, diagnosticOutput }) {
+  fs.rmSync(output, { force: true });
   const dockerfile = prepareDeliveryFiles(workspace);
   run("docker", ["build", "-f", dockerfile, "-t", tag, workspace]);
+  const validation = await validateImage({ tag });
+  if (diagnosticOutput) fs.writeFileSync(diagnosticOutput, JSON.stringify(validation, null, 2));
+  if (validation.status !== "passed") {
+    const error = new Error(validation.cause);
+    error.code = validation.code;
+    throw error;
+  }
   run("docker", ["save", "-o", output, tag]);
   return { dockerfile, output, tag };
 }
@@ -121,3 +148,4 @@ module.exports = {
   prepareDeliveryFiles,
   buildImage,
 };
+

package/src/delivery/launchRuntime.js

@@ -0,0 +1,13 @@
+"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);
+  });

package/src/delivery/supervisor.js

@@ -0,0 +1,52 @@
+"use strict";
+
+// PID 1 owns both process groups. An unexpected exit (including status 0)
+// terminates the container; a live proxy cannot hide a dead backend.
+const { spawn } = require("node:child_process");
+
+function supervise({ backend, proxy, graceMs = 5000 } = {}) {
+  const children = [];
+  let stopping = false;
+  let exitCode = 1;
+  let timer;
+  const signalGroup = (child, signal) => {
+    if (!child.pid) return;
+    try { process.kill(-child.pid, signal); } catch (error) {
+      if (error.code !== "ESRCH") throw error;
+    }
+  };
+  const finish = () => {
+    if (stopping && children.every((child) => child.failed || child.exitCode !== null || child.signalCode !== null)) {
+      clearTimeout(timer);
+      process.exitCode = exitCode;
+    }
+  };
+  const stop = (code) => {
+    if (stopping) return;
+    stopping = true;
+    exitCode = code;
+    for (const child of children) signalGroup(child, "SIGTERM");
+    timer = setTimeout(() => {
+      for (const child of children) signalGroup(child, "SIGKILL");
+    }, graceMs);
+    finish();
+  };
+  for (const spec of [backend, proxy]) {
+    const child = spawn(spec.command, spec.args || [], {
+      cwd: spec.cwd, env: { ...process.env, PORT: "4000" },
+      stdio: "inherit", detached: true,
+    });
+    children.push(child);
+    child.once("error", () => { child.failed = true; stop(1); finish(); });
+    child.once("exit", () => { stop(1); finish(); });
+  }
+  process.once("SIGTERM", () => stop(0));
+  process.once("SIGINT", () => stop(0));
+}
+
+if (require.main === module) supervise({
+  backend: { command: process.execPath, args: ["/oon-delivery/launchRuntime.js"], cwd: "/app/backend" },
+  proxy: { command: "nginx", args: ["-c", "/etc/nginx/oon.conf", "-g", "daemon off;"] },
+});
+
+module.exports = { supervise };

package/src/delivery/testSource.js

@@ -0,0 +1,64 @@
+"use strict";
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+const { randomUUID } = require("node:crypto");
+const { prepareDeliveryFiles } = require("./buildImage");
+
+function testPlan(workspace) {
+  const scopes = [".", "backend", "frontend"].map((scope) => {
+    const file = path.join(workspace, scope, "package.json");
+    const declared = fs.existsSync(file) && typeof JSON.parse(fs.readFileSync(file, "utf8")).scripts?.test === "string";
+    return { scope, status: declared ? "declared" : "not_declared" };
+  });
+  // A root suite is the orchestration entrypoint. Components are run separately
+  // only when no root test is declared. This avoids executing a suite twice.
+  if (scopes[0].status === "declared") {
+    for (const item of scopes.slice(1)) if (item.status === "declared") item.status = "root_orchestrated";
+  }
+  return scopes;
+}
+function testSource({ workspace, output }) {
+  const suites = testPlan(workspace);
+  const result = { schemaVersion: 1, stage: "source_tests", deployStarted: false, suites };
+  const selected = suites.filter((s) => s.status === "declared");
+  if (!selected.length) {
+    result.status = "not_declared";
+    fs.writeFileSync(output, JSON.stringify(result));
+    return result;
+  }
+  prepareDeliveryFiles(workspace);
+  const target = path.join(workspace, ".oon-delivery");
+  const dockerfile = path.join(target, "Dockerfile.test");
+  fs.copyFileSync(path.join(target, "Dockerfile.dockerignore"), `${dockerfile}.dockerignore`);
+  fs.writeFileSync(dockerfile, `FROM node:20-alpine\nWORKDIR /work\nCOPY . .\nRUN for scope in . backend frontend; do if [ -f "$scope/package.json" ]; then (cd "$scope" && if [ -f package-lock.json ]; then npm ci --ignore-scripts; else npm install --ignore-scripts; fi); fi; done\nRUN chown -R node:node /work\nUSER node\n`);
+  const name = `oon-tests-${randomUUID()}`;
+  const invoke = (args) => spawnSync("docker", args, { encoding: "utf8", timeout: 600000, maxBuffer: 1024 * 1024 });
+  try {
+    const build = invoke(["build", "-f", dockerfile, "-t", name, workspace]);
+    if (build.error || build.status !== 0) {
+      result.status = "failed"; result.category = "unknown"; result.code = "SOURCE_TEST_SETUP_FAILED";
+      result.cause = "Não foi possível preparar as dependências dos testes.";
+      result.guidance = "Confira lockfiles, dependências e disponibilidade do registry. Scripts de instalação não são executados nesta etapa.";
+    } else {
+      for (const suite of selected) {
+        const run = invoke(["run", "--rm", "--name", name, "--network", "none", "--cap-drop=ALL", "--security-opt=no-new-privileges", "--memory=1g", "--cpus=2", "--pids-limit=256", "--workdir", path.posix.join("/work", suite.scope), name, "npm", "test"]);
+        suite.status = run.status === 0 && !run.error ? "passed" : "failed";
+        if (suite.status === "failed") break;
+      }
+      for (const suite of selected) if (suite.status === "declared") suite.status = "not_run";
+      result.status = suites.some((s) => s.status === "failed") ? "failed" : "passed";
+      if (result.status === "failed") {
+        result.category = "unknown"; result.code = "SOURCE_TEST_FAILED";
+        result.cause = "A suíte declarada não passou no ambiente isolado.";
+        result.guidance = "Execute os testes declarados e confira dependências; serviços externos não são acessíveis durante os testes.";
+      }
+    }
+  } finally {
+    invoke(["rm", "-f", "-v", name]);
+    invoke(["image", "rm", "-f", name]);
+    fs.writeFileSync(output, JSON.stringify(result, null, 2));
+  }
+  return result;
+}
+module.exports = { testSource, testPlan };

package/src/delivery/validateImage.js

@@ -0,0 +1,124 @@
+"use strict";
+
+const { spawnSync } = require("node:child_process");
+const { randomUUID } = require("node:crypto");
+
+// No arbitrary logs cross the build/privileged-job boundary. Only a bounded
+// allowlist of paths and stable codes is returned; messages are platform-owned.
+function safePath(value) {
+  const text = String(value || "").replace(/^\/app\//, "");
+  return text.length <= 240 && /^(?:[.@a-zA-Z0-9_-]+\/)*[.@a-zA-Z0-9_-]+$/.test(text)
+    && !/(?:secret|token|password|credential|\.env)/i.test(text) ? text : undefined;
+}
+function classify(log = "") {
+  const recorded = log.match(/OON_STARTUP_FAILURE (\{[^\r\n]+\})/);
+  if (recorded) {
+    try {
+      const input = JSON.parse(recorded[1]);
+      const known = ["IMAGE_MODULE_NOT_FOUND", "IMAGE_SYNTAX_ERROR", "IMAGE_DEPENDENCY_UNAVAILABLE", "IMAGE_STARTUP_FAILED"];
+      if (known.includes(input.code)) {
+        // Reconstruct through the same bounded classifier; no arbitrary fields.
+        const representative = input.code === "IMAGE_MODULE_NOT_FOUND"
+          ? `Cannot find module '${safePath(input.path) || "unavailable"}'\nRequire stack:\n- ${safePath(input.importer) || "unavailable"}`
+          : input.code === "IMAGE_SYNTAX_ERROR" ? "SyntaxError:" : input.code === "IMAGE_DEPENDENCY_UNAVAILABLE" ? "ECONNREFUSED" : "";
+        return classify(representative);
+      }
+    } catch { /* Treat malformed logs as indeterminate. */ }
+  }
+  const missing = log.match(/Cannot find module ['"]([^'"\r\n]+)['"]/);
+  if (missing) return {
+    category: "application", code: "IMAGE_MODULE_NOT_FOUND",
+    cause: "Módulo ou asset necessário não está disponível na imagem de produção.",
+    path: safePath(missing[1]),
+    importer: safePath(log.match(/Require stack:\s*\n- ([^\r\n]+)/)?.[1]),
+    guidance: "Inclua assets de runtime em backend e declare dependências em dependencies. Confira o importador e o contrato de empacotamento.",
+  };
+  if (/SyntaxError:/.test(log)) return {
+    category: "application", code: "IMAGE_SYNTAX_ERROR",
+    cause: "Um módulo da imagem contém sintaxe inválida.",
+    guidance: "Revise a sintaxe dos módulos e a compatibilidade com Node 20.",
+  };
+  if (/Mongo(?:ose)?ServerSelectionError|ECONNREFUSED|ENOTFOUND|ETIMEDOUT/.test(log)) return {
+    category: "configuration", code: "IMAGE_DEPENDENCY_UNAVAILABLE",
+    cause: "A aplicação tentou acessar uma dependência indisponível na validação isolada.",
+    guidance: "Confira a configuração de inicialização. Serviços reais não são acessíveis durante esta validação.",
+  };
+  return {
+    category: "unknown", code: "IMAGE_STARTUP_FAILED",
+    cause: "A imagem não concluiu a inicialização; a causa não foi determinada.",
+    guidance: "Reproduza a inicialização em ambiente isolado e confira a configuração e os módulos carregados.",
+  };
+}
+function docker(args, { timeout = 30000, allowFailure = false } = {}) {
+  const r = spawnSync("docker", args, { encoding: "utf8", timeout, maxBuffer: 1024 * 1024 });
+  if (!allowFailure && (r.error || r.status !== 0)) {
+    const error = new Error("O executor de validação não concluiu uma operação Docker.");
+    error.code = "IMAGE_VALIDATION_INFRASTRUCTURE";
+    throw error;
+  }
+  return r;
+}
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function validateImage({ tag, timeoutMs = 90000, execute = docker, sleep = delay }) {
+  const id = `oon-validation-${randomUUID()}`;
+  const database = `${id}-db`, app = `${id}-app`;
+  const base = { schemaVersion: 1, stage: "image_validation", deployStarted: false };
+  let imageId;
+  let infrastructureStep = "image_inspect";
+  try {
+    imageId = execute(["image", "inspect", "--format", "{{.Id}}", tag]).stdout.trim();
+    if (!/^sha256:[a-f0-9]{64}$/.test(imageId)) throw new Error("Invalid image identity");
+    // Pull BEFORE attaching services to an internal-only network. No host mounts,
+    // published ports, host networking, Docker socket, or real credentials.
+    infrastructureStep = "database_image";
+    execute(["pull", "mongo:7"], { timeout: 180000 });
+    infrastructureStep = "database_startup";
+    execute(["run", "-d", "--name", database, "--network", "none", "--user", "999:999", "--cap-drop=ALL",
+      "--security-opt=no-new-privileges", "--memory=1g", "--cpus=1", "--pids-limit=128",
+      "--read-only", "--tmpfs", "/data/db:rw,uid=999,gid=999,size=536870912",
+      "--tmpfs", "/data/configdb:rw,uid=999,gid=999,size=16777216",
+      "--tmpfs", "/tmp:rw,size=67108864", "mongo:7", "mongod", "--bind_ip_all", "--wiredTigerCacheSizeGB", "0.25"]);
+    let databaseReady = false;
+    for (let attempt = 0; attempt < 30; attempt++) {
+      const ping = execute(["exec", database, "mongosh", "--quiet", "--eval", "quit(db.adminCommand({ping:1}).ok ? 0 : 1)"], { allowFailure: true, timeout: 3000 });
+      if (ping.status === 0) { databaseReady = true; break; }
+      await sleep(1000);
+    }
+    if (!databaseReady) throw new Error("Validation database unavailable");
+    infrastructureStep = "application_startup";
+    execute(["run", "-d", "--name", app, "--network", `container:${database}`, "--user", "1000:1000",
+      "--cap-drop=ALL", "--security-opt=no-new-privileges", "--read-only",
+      "--memory=512m", "--cpus=1", "--pids-limit=128",
+      "--tmpfs", "/tmp:rw,uid=1000,gid=1000,size=67108864",
+      "--tmpfs", "/app/backend/uploads:rw,uid=1000,gid=1000,size=16777216",
+      "--env", "MONGO_URI=mongodb://127.0.0.1:27017/validation",
+      "--env", "NODE_ENV=production", "--env", "APP_ENVIRONMENT=desenvolvimento",
+      "--env", "INSTANCE_CREDENTIAL_ENCRYPTION_KEY=validation-only-not-a-real-credential",
+      "--env", "CENTRAL_ATIVACAO_URL=http://unavailable.invalid",
+      "--env", "CENTRAL_ATIVACAO_API_URL=http://unavailable.invalid", imageId]);
+    const deadline = Date.now() + timeoutMs;
+    let consecutive = 0;
+    while (Date.now() < deadline) {
+      const running = execute(["inspect", "--format", "{{.State.Running}}", app]).stdout.trim();
+      if (running !== "true") {
+        const logs = execute(["logs", "--tail", "80", app], { allowFailure: true });
+        return { ...base, imageId, status: "failed", ...classify(`${logs.stdout || ""}\n${logs.stderr || ""}`) };
+      }
+      const health = execute(["exec", app, "curl", "-fsS", "--max-time", "2", "http://127.0.0.1:8080/api/health/ready"], { allowFailure: true, timeout: 4000 });
+      if (health.status === 0) consecutive++; else consecutive = 0;
+      if (consecutive >= 3) return { ...base, imageId, status: "passed" };
+      await sleep(1000);
+    }
+    return { ...base, imageId, status: "failed", category: "unknown", code: "IMAGE_VALIDATION_TIMEOUT",
+      cause: "A inicialização não terminou no prazo de validação.",
+      guidance: "Investigue inicialização e dependências. Timeout isolado não comprova erro de código." };
+  } catch {
+    return { ...base, imageId, status: "failed", category: "infrastructure", code: "IMAGE_VALIDATION_INFRASTRUCTURE", infrastructureStep,
+      cause: "O ambiente de validação não conseguiu executar a prova da imagem.",
+      guidance: "Verifique Docker, recursos e disponibilidade da imagem do serviço temporário; tente novamente." };
+  } finally {
+    execute(["rm", "-f", "-v", app, database], { allowFailure: true });
+  }
+}
+module.exports = { validateImage, classify, safePath };