@oondemand/oon-core-back 0.4.29 → 0.5.0

package/README.md

@@ -1,5 +1,11 @@
 # OonCore Back - ativação de instâncias
 
+## Runtime local desconectado
+
+Com `NODE_ENV=development` e `OON_RUNTIME_MODE=local`, o Core escuta apenas em `127.0.0.1`, cria uma sessão técnica local de até 30 dias e não consulta a Central de Ativações. Códigos independentes e de uso único atendem navegador e automação/seed. Apps com tenant usam o contexto virtual fixo `local:tenant`, sem criar um recurso. O estado é `ativa_local`; nenhuma instância, licença, Deployment ou credencial operacional é criada. Produção, Kubernetes, bind externo e identidade operacional falham no startup.
+
+O scaffold configura esse fluxo. Não use `DEV_TOKEN` em uma Central nova.
+
 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.
 
 ## Variáveis de ambiente

package/package.json

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

package/src/api/auth.routes.js

@@ -7,6 +7,7 @@ const { asyncHandler, sendResponse } = require("../core/utils/helpers");
 const { ensureInstance, operationalRequestHeaders } = require("../core/utils/instanceActivation");
 const { findAccessForUser, audit } = require("../core/rbac/storage");
 const { changeFirstAccessPassword } = require("../core/rbac/identityProvider");
+const { isLocalRuntime } = require("../core/runtime/localDevelopment");
 const {
   LOGIN_PATH,
   getBaseUrl,
@@ -20,6 +21,14 @@ const SESSION_SCOPE_HEADER = "x-oon-session-scope";
 const LAUNCH_EXCHANGE_PATH = "/integracao/app-access/launch/exchange";
 const router = express.Router();
 
+router.use((req, _res, next) => {
+  if (!isLocalRuntime() || (req.method === "GET" && req.path === "/validar-token")) return next();
+  return next(new GenericError("Operação da plataforma indisponível no runtime local.", {
+    statusCode: 403,
+    code: "LOCAL_OPERATION_NOT_SUPPORTED",
+  }));
+});
+
 function readBasicAuthorization(req) {
   const authorization = String(req.headers.authorization || "");
   if (!authorization.startsWith("Basic ")) {

package/src/api/localDevelopment.routes.js

@@ -0,0 +1,68 @@
+"use strict";
+
+const express = require("express");
+const auth = require("../core/middlewares/auth");
+const GenericError = require("../core/errors/GenericError");
+const { asyncHandler } = require("../core/utils/helpers");
+const {
+  SESSION_COOKIE,
+  CSRF_COOKIE,
+  exchangeBootstrapCode,
+  validateLocalSession,
+  validateCsrf,
+  invalidateLocalSession,
+  localRoles,
+  setLocalRole,
+  parseCookies,
+  cookie,
+  clearCookie,
+  localRuntimeSummary,
+} = require("../core/runtime/localDevelopment");
+
+const router = express.Router();
+
+router.post("/bootstrap", asyncHandler(async (req, res) => {
+  const code = String(req.body?.code || "").trim();
+  const result = await exchangeBootstrapCode(code);
+  const maxAge = Math.max(1, Math.floor((result.expiresAt.getTime() - Date.now()) / 1000));
+  res.setHeader("Set-Cookie", [
+    cookie(SESSION_COOKIE, result.sessionToken, { httpOnly: true, maxAge }),
+    cookie(CSRF_COOKIE, result.csrfToken, { maxAge }),
+  ]);
+  res.set("Cache-Control", "no-store");
+  res.status(200).json({ ...localRuntimeSummary(result), roleCode: result.roleCode });
+}));
+
+router.use(auth);
+
+router.get("/context", asyncHandler(async (req, res) => {
+  const cookies = parseCookies(req.headers.cookie);
+  const session = await validateLocalSession(cookies[SESSION_COOKIE]);
+  res.set("Cache-Control", "no-store");
+  res.json({ ...localRuntimeSummary(session), roleCode: session.roleCode, roles: localRoles() });
+}));
+
+router.post("/role", asyncHandler(async (req, res) => {
+  const cookies = parseCookies(req.headers.cookie);
+  await validateCsrf(req.headers["x-oon-local-csrf"] || cookies[CSRF_COOKIE]);
+  const role = await setLocalRole(req.body?.roleCode);
+  res.set("Cache-Control", "no-store");
+  res.json({ role });
+}));
+
+router.post("/logout", asyncHandler(async (_req, res) => {
+  await invalidateLocalSession();
+  res.setHeader("Set-Cookie", [
+    clearCookie(SESSION_COOKIE, { httpOnly: true }),
+    clearCookie(CSRF_COOKIE),
+  ]);
+  res.set("Cache-Control", "no-store");
+  res.status(204).end();
+}));
+
+router.use((_req, _res, next) => next(new GenericError("Operação local desconhecida.", {
+  statusCode: 404,
+  code: "LOCAL_OPERATION_NOT_FOUND",
+})));
+
+module.exports = router;

package/src/api/status.routes.js

@@ -4,6 +4,7 @@ const express = require("express");
 const mongoose = require("mongoose");
 const ctx = require("../core/context");
 const { runtimeSummary } = require("./core.routes");
+const { isLocalRuntime, localRuntimeSummary } = require("../core/runtime/localDevelopment");
 
 const router = express.Router();
 
@@ -31,6 +32,7 @@ function readinessSummary(readyState = mongoose.connection.readyState) {
       ready,
       state: database.code,
     },
+    ...(isLocalRuntime() ? localRuntimeSummary() : { runtimeMode: "platform" }),
   };
 }
 
@@ -39,6 +41,7 @@ function versionSummary() {
     status: "ok",
     service: ctx.config.serviceName,
     ...runtimeSummary(),
+    ...(isLocalRuntime() ? localRuntimeSummary() : { runtimeMode: "platform" }),
   };
 }
 
@@ -59,6 +62,19 @@ router.get("/health/version", (_req, res) => {
   res.status(200).json(versionSummary());
 });
 
+router.get("/ativacao/status", (_req, res, next) => {
+  if (!isLocalRuntime()) return next();
+  res.set("Cache-Control", "no-store");
+  res.status(200).json({
+    role: "member",
+    appCode: ctx.config.appCode || ctx.config.slug || process.env.APP_CODE,
+    ambiente: "desenvolvimento",
+    podeAtivar: false,
+    podeTentarNovamente: false,
+    ...localRuntimeSummary(),
+  });
+});
+
 module.exports = router;
 module.exports.databaseState = databaseState;
 module.exports.readinessSummary = readinessSummary;

package/src/boot/createApp.js

@@ -18,11 +18,32 @@ const authRoutes = require("../api/auth.routes");
 const activationRoutes = require("../api/activation.routes");
 const activationGuard = require("../core/middlewares/activationGuard");
 const transactionalEmail = require("../capabilities/transactionalEmail");
+const localDevelopmentRoutes = require("../api/localDevelopment.routes");
+const {
+  isLocalRuntime,
+  isLoopbackHost,
+  localRequestBoundary,
+} = require("../core/runtime/localDevelopment");
+
+function localCorsOptions() {
+  return {
+    credentials: true,
+    origin(origin, callback) {
+      if (!origin || isLoopbackHost(origin)) return callback(null, true);
+      const error = new Error("Origin não permitida no runtime local.");
+      error.statusCode = 403;
+      error.code = "LOCAL_ORIGIN_FORBIDDEN";
+      return callback(error);
+    },
+  };
+}
 
 function createApp() {
   const app = express();
 
-  app.use(cors(ctx.config.cors));
+  app.disable("trust proxy");
+  app.use(localRequestBoundary);
+  app.use(cors(isLocalRuntime() ? localCorsOptions() : ctx.config.cors));
   app.use(helmet());
   app.use(express.json({ limit: "10mb" }));
   app.use(express.urlencoded({ extended: true, limit: "10mb" }));
@@ -30,7 +51,8 @@ function createApp() {
   if (process.env.NODE_ENV === "development") app.use(morgan("dev"));
 
   app.use("/", statusRoutes);
-  app.use("/ativacao", activationRoutes);
+  if (isLocalRuntime()) app.use("/auth/local", localDevelopmentRoutes);
+  else app.use("/ativacao", activationRoutes);
   app.use(activationGuard);
   app.use("/auth", authRoutes);
   app.use("/core", accessRoutes);

package/src/boot/startServer.js

@@ -3,6 +3,11 @@ const { connectDB } = require("./database");
 const { createApp } = require("./createApp");
 const { loadCentral } = require("./loadCentral");
 const transactionalEmail = require("../capabilities/transactionalEmail");
+const {
+  isLocalRuntime,
+  validateLocalRuntime,
+  prepareLocalDevelopmentSession,
+} = require("../core/runtime/localDevelopment");
 
 /**
  * Sobe a aplicação completa: carrega a Central do consumidor, conecta no
@@ -15,14 +20,23 @@ async function start({ cwd = process.cwd(), listen = true } = {}) {
   loadCentral(cwd);
   await connectDB();
   await transactionalEmail.initialize();
+  const host = isLocalRuntime() ? "127.0.0.1" : undefined;
+  validateLocalRuntime({ host: host || process.env.HOST || "127.0.0.1" });
+  const localSession = isLocalRuntime() ? await prepareLocalDevelopmentSession() : null;
   const app = createApp();
 
   if (!listen) return { app };
 
   const port = ctx.config.port;
   return new Promise((resolve) => {
-    const server = app.listen(port, () => {
+    const server = app.listen(port, host, () => {
       console.log("****************************************************************");
+      if (localSession) {
+        console.log("Runtime: desenvolvimento local desconectado");
+        console.log(`URL: http://127.0.0.1:5173/?oon_local_bootstrap=${localSession.bootstrapCode}`);
+        console.log(`Código para automação/seed: ${localSession.automationBootstrapCode}`);
+        console.log(`Expira em: ${localSession.expiresAt.toISOString()}`);
+      }
       console.log(`${ctx.config.serviceName} rodando na porta ${port} e conectado ao MongoDB`);
       console.log("****************************************************************");
       const stop = () => transactionalEmail.stopWorker();

package/src/core/middlewares/activationGuard.js

@@ -1,5 +1,6 @@
 const { ensureInstance } = require("../utils/instanceActivation");
 const Helpers = require("../utils/helpers");
+const { isLocalRuntime } = require("../runtime/localDevelopment");
 
 const allowed = [
   /^\/ativacao(\/|$)/,
@@ -10,6 +11,7 @@ const allowed = [
 
 module.exports = async function activationGuard(req, res, next) {
   try {
+    if (isLocalRuntime()) return next();
     if (allowed.some((pattern) => pattern.test(req.path))) return next();
 
     const instance = await ensureInstance();

package/src/core/middlewares/auth.js

@@ -13,6 +13,13 @@ const {
   readRequestedTenantId,
   createAccessContext,
 } = require("../tenancy");
+const {
+  SESSION_COOKIE,
+  isLocalRuntime,
+  parseCookies,
+  validateLocalSession,
+  localPrincipal,
+} = require("../runtime/localDevelopment");
 
 async function defaultVerifyToken(token, { req } = {}) {
   const baseUrl = getBaseUrl(req);
@@ -89,6 +96,7 @@ function localDevelopmentVerifyToken(token, { req } = {}) {
 }
 
 function resolveVerifyToken() {
+  if (isLocalRuntime()) return async (token) => localPrincipal(await validateLocalSession(token));
   if (typeof ctx.config.auth?.verifyToken === "function") return ctx.config.auth.verifyToken;
   if (process.env.NODE_ENV === "development" && process.env.DEV_TOKEN) {
     return localDevelopmentVerifyToken;
@@ -102,6 +110,15 @@ function isFirstAccessRoute(req) {
 }
 
 async function applyEffectiveAccess(usuario) {
+  if (usuario?.localDevelopment && usuario?.runtimeMode === "local") {
+    return {
+      ...usuario,
+      accessStatus: "active",
+      mustChangePassword: false,
+      firstAccessPending: false,
+      rbacMode: "local-development",
+    };
+  }
   const access = await resolveUserAccess(usuario);
   return {
     ...usuario,
@@ -115,7 +132,9 @@ async function applyEffectiveAccess(usuario) {
 }
 
 const authMiddleware = async (req, res, next) => {
-  const token = req.headers.authorization?.split(" ")[1];
+  const token = isLocalRuntime()
+    ? parseCookies(req.headers.cookie)[SESSION_COOKIE]
+    : req.headers.authorization?.split(" ")[1];
   if (!token) {
     return Helpers.sendErrorResponse({
       res,

package/src/core/runtime/localDevelopment.js

@@ -0,0 +1,340 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const mongoose = require("mongoose");
+const ctx = require("../context");
+const GenericError = require("../errors/GenericError");
+const { policy, roleByCode, rolePermissions } = require("../rbac/policy");
+const { resolveLocalExecutionPolicy } = require("./localExecutionPolicy");
+
+const RUNTIME_MODE_ENV = "OON_RUNTIME_MODE";
+const LOCAL_RUNTIME_MODE = "local";
+const DEFAULT_TTL_DAYS = 30;
+const BOOTSTRAP_TTL_MINUTES = 10;
+const SESSION_COOKIE = "oon_local_session";
+const CSRF_COOKIE = "oon_local_csrf";
+const CSRF_HEADER = "x-oon-local-csrf";
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1"]);
+
+let memorySession = null;
+let preparedSecrets = null;
+
+function isLocalRuntime(env = process.env) {
+  return String(env[RUNTIME_MODE_ENV] || "").trim().toLowerCase() === LOCAL_RUNTIME_MODE;
+}
+
+function runtimeMode(env = process.env) {
+  return isLocalRuntime(env) ? LOCAL_RUNTIME_MODE : "platform";
+}
+
+function hash(value) {
+  return crypto.createHash("sha256").update(String(value || "")).digest("hex");
+}
+
+function randomSecret() {
+  return crypto.randomBytes(32).toString("base64url");
+}
+
+function safeEqualHash(left, right) {
+  const a = Buffer.from(String(left || ""), "hex");
+  const b = Buffer.from(String(right || ""), "hex");
+  return a.length > 0 && a.length === b.length && crypto.timingSafeEqual(a, b);
+}
+
+function hostnameOf(value) {
+  const raw = String(value || "").trim();
+  if (!raw) return "";
+  try {
+    return new URL(raw.includes("://") ? raw : `http://${raw}`).hostname.replace(/^\[|\]$/g, "").toLowerCase();
+  } catch {
+    return "";
+  }
+}
+
+function isLoopbackHost(value) {
+  return LOOPBACK_HOSTS.has(hostnameOf(value));
+}
+
+function localError(message, code, statusCode = 400) {
+  return new GenericError(message, { code, statusCode });
+}
+
+function validateLocalRuntime({ env = process.env, host = "127.0.0.1" } = {}) {
+  if (!isLocalRuntime(env)) return { runtimeMode: "platform", host };
+  if (env.NODE_ENV !== "development") {
+    throw localError("O runtime local exige NODE_ENV=development.", "LOCAL_RUNTIME_ENV_INVALID", 500);
+  }
+  if (env.KUBERNETES_SERVICE_HOST || env.OON_DEPLOYMENT_ID || env.OON_DEPLOYMENT_TOKEN || env.OON_INSTANCE_ID || env.OON_INSTANCE_TOKEN) {
+    throw localError("O runtime local não pode iniciar com identidade de Deployment, instância ou Kubernetes.", "LOCAL_RUNTIME_PLATFORM_IDENTITY", 500);
+  }
+  if (!isLoopbackHost(host)) {
+    throw localError("O runtime local deve escutar exclusivamente em 127.0.0.1, localhost ou ::1.", "LOCAL_RUNTIME_BIND_FORBIDDEN", 500);
+  }
+  if (env.PUBLIC_APP_URL && !isLoopbackHost(env.PUBLIC_APP_URL)) {
+    throw localError("PUBLIC_APP_URL deve apontar para loopback no runtime local.", "LOCAL_RUNTIME_PUBLIC_URL_FORBIDDEN", 500);
+  }
+  return { runtimeMode: LOCAL_RUNTIME_MODE, host: hostnameOf(host) };
+}
+
+function ttlDays(env = process.env, policyTtlDays = DEFAULT_TTL_DAYS) {
+  const parsed = Number(env.OON_LOCAL_TTL_DAYS || policyTtlDays);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.min(parsed, policyTtlDays, 30) : policyTtlDays;
+}
+
+function localSessionModel() {
+  const schema = new mongoose.Schema({
+    singletonKey: { type: String, default: "default", unique: true, immutable: true },
+    tokenHash: { type: String, required: true, select: false },
+    csrfHash: { type: String, required: true, select: false },
+    bootstrapHash: { type: String, required: true, select: false },
+    automationBootstrapHash: { type: String, required: true, select: false },
+    bootstrapExpiresAt: { type: Date, required: true },
+    expiresAt: { type: Date, required: true, index: true },
+    roleCode: { type: String, required: true },
+  }, { timestamps: true, collection: "oon_core_local_development_session" });
+  return mongoose.models.OonCoreLocalDevelopmentSession
+    || mongoose.model("OonCoreLocalDevelopmentSession", schema);
+}
+
+function defaultRoleCode() {
+  const current = policy();
+  if (!current.enabled) return "admin";
+  return roleByCode("developer")?.code
+    || current.roles.find((role) => role.admin)?.code
+    || current.roles[0]?.code
+    || "admin";
+}
+
+async function loadSession() {
+  if (mongoose.connection.readyState !== 1) return memorySession;
+  return localSessionModel().findOne({ singletonKey: "default" })
+    .select("+tokenHash +csrfHash +bootstrapHash +automationBootstrapHash");
+}
+
+async function persistSession(values, existing) {
+  if (mongoose.connection.readyState !== 1) {
+    memorySession = { ...(existing || {}), ...values, singletonKey: "default" };
+    return memorySession;
+  }
+  if (existing) {
+    Object.assign(existing, values);
+    await existing.save();
+    return existing;
+  }
+  return localSessionModel().create({ singletonKey: "default", ...values });
+}
+
+async function prepareLocalDevelopmentSession({ now = new Date() } = {}) {
+  if (!isLocalRuntime()) return null;
+  validateLocalRuntime({ host: process.env.HOST || "127.0.0.1" });
+  const executionPolicy = await resolveLocalExecutionPolicy({ appCode: ctx.config.appCode || ctx.config.slug });
+  const current = await loadSession();
+  const currentExpiry = current?.expiresAt ? new Date(current.expiresAt) : null;
+  if (currentExpiry && currentExpiry <= now) {
+    throw localError(
+      "O período de desenvolvimento local expirou. Exclua os dados locais para iniciar um novo período.",
+      "LOCAL_SESSION_EXPIRED",
+      403,
+    );
+  }
+  const expiresAt = currentExpiry
+    || new Date(now.getTime() + ttlDays(process.env, executionPolicy.ttlDays) * 24 * 60 * 60 * 1000);
+  const sessionToken = randomSecret();
+  const csrfToken = randomSecret();
+  const configuredBootstrap = String(process.env.OON_LOCAL_BOOTSTRAP_CODE || "").trim();
+  const bootstrapCode = configuredBootstrap.length >= 43 ? configuredBootstrap : randomSecret();
+  const configuredAutomationBootstrap = String(process.env.OON_LOCAL_AUTOMATION_BOOTSTRAP_CODE || "").trim();
+  const automationBootstrapCode = configuredAutomationBootstrap.length >= 43
+    ? configuredAutomationBootstrap
+    : randomSecret();
+  const values = {
+    tokenHash: hash(sessionToken),
+    csrfHash: hash(csrfToken),
+    bootstrapHash: hash(bootstrapCode),
+    automationBootstrapHash: hash(automationBootstrapCode),
+    bootstrapExpiresAt: new Date(now.getTime() + BOOTSTRAP_TTL_MINUTES * 60 * 1000),
+    expiresAt,
+    roleCode: current?.roleCode || defaultRoleCode(),
+  };
+  await persistSession(values, current);
+  preparedSecrets = { sessionToken, csrfToken, bootstrapCode, automationBootstrapCode, expiresAt };
+  return { bootstrapCode, automationBootstrapCode, expiresAt, roleCode: values.roleCode, policy: executionPolicy };
+}
+
+async function exchangeBootstrapCode(code, { now = new Date() } = {}) {
+  const session = await loadSession();
+  const providedHash = hash(code);
+  const secretName = session && safeEqualHash(session.bootstrapHash, providedHash)
+    ? "bootstrapCode"
+    : session && safeEqualHash(session.automationBootstrapHash, providedHash)
+      ? "automationBootstrapCode"
+      : null;
+  if (!session || !preparedSecrets || session.bootstrapExpiresAt <= now || !secretName) {
+    throw localError("Código de inicialização local inválido ou expirado.", "LOCAL_BOOTSTRAP_INVALID", 401);
+  }
+  const consumedField = secretName === "bootstrapCode" ? "bootstrapHash" : "automationBootstrapHash";
+  const replacementHash = hash(randomSecret());
+  await persistSession({ [consumedField]: replacementHash }, session);
+  const result = {
+    sessionToken: preparedSecrets.sessionToken,
+    csrfToken: preparedSecrets.csrfToken,
+    expiresAt: preparedSecrets.expiresAt,
+    roleCode: session.roleCode,
+  };
+  preparedSecrets = { ...preparedSecrets, [secretName]: null };
+  return result;
+}
+
+async function validateLocalSession(token, { now = new Date() } = {}) {
+  const session = await loadSession();
+  if (!session || !token || session.expiresAt <= now || !safeEqualHash(session.tokenHash, hash(token))) {
+    throw localError("Sessão local ausente, inválida ou expirada.", "LOCAL_SESSION_INVALID", 401);
+  }
+  return session;
+}
+
+async function validateCsrf(token) {
+  const session = await loadSession();
+  if (!session || !token || !safeEqualHash(session.csrfHash, hash(token))) {
+    throw localError("Proteção CSRF local inválida.", "LOCAL_CSRF_INVALID", 403);
+  }
+  return true;
+}
+
+async function invalidateLocalSession({ now = new Date() } = {}) {
+  const session = await loadSession();
+  if (!session) return;
+  await persistSession({
+    tokenHash: hash(randomSecret()),
+    csrfHash: hash(randomSecret()),
+    bootstrapHash: hash(randomSecret()),
+    automationBootstrapHash: hash(randomSecret()),
+    bootstrapExpiresAt: now,
+  }, session);
+  preparedSecrets = null;
+}
+
+function localRoles() {
+  const current = policy();
+  if (!current.enabled) return [{ code: "admin", name: "Administrador local", permissions: ["*"] }];
+  return current.roles.map((role) => ({
+    code: role.code,
+    name: role.name || role.code,
+    permissions: rolePermissions(role),
+    admin: Boolean(role.admin),
+  }));
+}
+
+async function setLocalRole(roleCode) {
+  const role = localRoles().find((candidate) => candidate.code === String(roleCode || ""));
+  if (!role) throw localError("Perfil local não está declarado no central.app.json.", "LOCAL_ROLE_NOT_DECLARED", 422);
+  const session = await loadSession();
+  if (!session) throw localError("Sessão local não inicializada.", "LOCAL_SESSION_INVALID", 401);
+  await persistSession({ roleCode: role.code }, session);
+  return role;
+}
+
+async function localPrincipal(session) {
+  const role = localRoles().find((candidate) => candidate.code === session.roleCode) || localRoles()[0];
+  const tenancyModel = ctx.config.tenancyModel || ctx.config.ecosystem?.tenancyModel || "single_tenant";
+  const tenantId = tenancyModel === "none" ? undefined : "local:tenant";
+  return {
+    id: "local:developer",
+    usuarioId: "local:developer",
+    tipo: role.code,
+    perfil: role.code,
+    roleCode: role.code,
+    nome: "Desenvolvedor local",
+    email: "developer@localhost",
+    permissions: role.permissions,
+    capabilities: ctx.config.capabilities || [],
+    appCode: ctx.config.appCode || ctx.config.slug || process.env.APP_CODE,
+    tenancyModel,
+    tenantId,
+    tenant: tenantId ? { id: tenantId, name: "Tenant local" } : undefined,
+    runtimeMode: LOCAL_RUNTIME_MODE,
+    localDevelopment: true,
+  };
+}
+
+function parseCookies(header) {
+  return String(header || "").split(";").reduce((cookies, part) => {
+    const index = part.indexOf("=");
+    if (index < 0) return cookies;
+    const key = part.slice(0, index).trim();
+    const value = part.slice(index + 1).trim();
+    if (key) {
+      try { cookies[key] = decodeURIComponent(value); }
+      catch { cookies[key] = ""; }
+    }
+    return cookies;
+  }, {});
+}
+
+function cookie(name, value, { httpOnly = false, maxAge = 0 } = {}) {
+  const parts = [`${name}=${encodeURIComponent(value)}`, "Path=/", "SameSite=Strict"];
+  if (httpOnly) parts.push("HttpOnly");
+  if (process.env.OON_LOCAL_HTTPS === "true") parts.push("Secure");
+  if (maxAge) parts.push(`Max-Age=${Math.max(0, Math.floor(maxAge))}`);
+  return parts.join("; ");
+}
+
+function clearCookie(name, { httpOnly = false } = {}) {
+  return cookie(name, "", { httpOnly, maxAge: -1 }) + "; Expires=Thu, 01 Jan 1970 00:00:00 GMT";
+}
+
+function assertLocalRequest(req) {
+  if (!isLoopbackHost(req.headers.host)) {
+    throw localError("Host não permitido no runtime local.", "LOCAL_HOST_FORBIDDEN", 403);
+  }
+  if (req.headers["x-forwarded-host"] || req.headers["x-forwarded-proto"] || req.headers.forwarded) {
+    throw localError("Cabeçalhos de proxy não são aceitos no runtime local.", "LOCAL_PROXY_FORBIDDEN", 403);
+  }
+  const origin = req.headers.origin;
+  if (origin && !isLoopbackHost(origin)) {
+    throw localError("Origin não permitida no runtime local.", "LOCAL_ORIGIN_FORBIDDEN", 403);
+  }
+}
+
+async function localRequestBoundary(req, _res, next) {
+  if (!isLocalRuntime()) return next();
+  try {
+    assertLocalRequest(req);
+    const safeMethod = ["GET", "HEAD", "OPTIONS"].includes(req.method);
+    const bootstrap = String(req.path || "").split("?")[0] === "/auth/local/bootstrap";
+    if (!safeMethod && !bootstrap) {
+      const cookies = parseCookies(req.headers.cookie);
+      const csrfHeader = req.headers[CSRF_HEADER];
+      if (!csrfHeader || csrfHeader !== cookies[CSRF_COOKIE]) {
+        throw localError("Proteção CSRF local ausente ou divergente.", "LOCAL_CSRF_INVALID", 403);
+      }
+      await validateCsrf(csrfHeader);
+    }
+    return next();
+  } catch (error) {
+    return next(error);
+  }
+}
+
+function localRuntimeSummary(session) {
+  return {
+    runtimeMode: LOCAL_RUNTIME_MODE,
+    status: "ativa_local",
+    disconnected: true,
+    expiresAt: session?.expiresAt || preparedSecrets?.expiresAt,
+  };
+}
+
+function resetLocalDevelopmentForTests() {
+  memorySession = null;
+  preparedSecrets = null;
+}
+
+module.exports = {
+  RUNTIME_MODE_ENV, LOCAL_RUNTIME_MODE, SESSION_COOKIE, CSRF_COOKIE, CSRF_HEADER,
+  isLocalRuntime, runtimeMode, isLoopbackHost, validateLocalRuntime, ttlDays,
+  prepareLocalDevelopmentSession, exchangeBootstrapCode, validateLocalSession,
+  validateCsrf, invalidateLocalSession, localRoles, setLocalRole, localPrincipal, parseCookies, cookie,
+  clearCookie, assertLocalRequest, localRequestBoundary, localRuntimeSummary,
+  resetLocalDevelopmentForTests,
+};

package/src/core/runtime/localExecutionPolicy.js

@@ -0,0 +1,66 @@
+"use strict";
+
+const GenericError = require("../errors/GenericError");
+
+const EMBEDDED_POLICY = Object.freeze({
+  schemaVersion: 1,
+  source: "embedded",
+  allowed: true,
+  ttlDays: 30,
+  offlineBehavior: "allow-until-expiration",
+});
+
+class EmbeddedLocalExecutionPolicyProvider {
+  async resolve() {
+    return { ...EMBEDDED_POLICY };
+  }
+}
+
+let provider = new EmbeddedLocalExecutionPolicyProvider();
+
+function validatePolicy(value) {
+  if (!value || value.schemaVersion !== 1 || typeof value.allowed !== "boolean") {
+    throw new GenericError("Política de execução local inválida.", {
+      statusCode: 500,
+      code: "LOCAL_POLICY_INVALID",
+    });
+  }
+  const ttlDays = Number(value.ttlDays);
+  if (!Number.isFinite(ttlDays) || ttlDays <= 0 || ttlDays > 30) {
+    throw new GenericError("TTL da política local deve estar entre 1 e 30 dias.", {
+      statusCode: 500,
+      code: "LOCAL_POLICY_TTL_INVALID",
+    });
+  }
+  return { ...value, ttlDays };
+}
+
+async function resolveLocalExecutionPolicy(context = {}) {
+  const resolved = validatePolicy(await provider.resolve({ offline: true, ...context }));
+  if (!resolved.allowed) {
+    throw new GenericError("A política atual não permite iniciar uma nova sessão local.", {
+      statusCode: 403,
+      code: "LOCAL_EXECUTION_NOT_ALLOWED",
+    });
+  }
+  return resolved;
+}
+
+function setLocalExecutionPolicyProvider(nextProvider) {
+  if (!nextProvider || typeof nextProvider.resolve !== "function") {
+    throw new TypeError("LocalExecutionPolicyProvider deve implementar resolve(context).");
+  }
+  provider = nextProvider;
+}
+
+function resetLocalExecutionPolicyProvider() {
+  provider = new EmbeddedLocalExecutionPolicyProvider();
+}
+
+module.exports = {
+  EMBEDDED_POLICY,
+  EmbeddedLocalExecutionPolicyProvider,
+  resolveLocalExecutionPolicy,
+  setLocalExecutionPolicyProvider,
+  resetLocalExecutionPolicyProvider,
+};

package/src/core/utils/instanceActivation.js

@@ -10,6 +10,7 @@ const {
   getAppCode,
   getTimeout,
 } = require("./activationProvider");
+const { isLocalRuntime } = require("../runtime/localDevelopment");
 
 const PATHS = {
   validar: "/integracao/ativacao-instancias/validar-codigo",
@@ -251,6 +252,16 @@ function clearInstanceIdentity(instance) {
 }
 
 async function ensureInstance() {
+  if (isLocalRuntime()) {
+    return {
+      ecosystemRole: role(),
+      status: "ativa_local",
+      runtimeMode: "local",
+      appCode: getAppCode(),
+      ambiente: "desenvolvimento",
+      save: async () => {},
+    };
+  }
   if (mongoose.connection.readyState !== 1) {
     return {
       ecosystemRole: role(),
@@ -472,6 +483,12 @@ function operationalIdentity(instance) {
 }
 
 async function operationalRequestHeaders(options = {}, dependencies = {}) {
+  if (isLocalRuntime()) {
+    throw new GenericError("Operações da plataforma não estão disponíveis no runtime local.", {
+      statusCode: 403,
+      code: "LOCAL_OPERATION_NOT_SUPPORTED",
+    });
+  }
   const loadInstance = dependencies.ensureInstance || ensureInstance;
   const buildHeaders = dependencies.instanceHeaders || instanceHeaders;
   const instance = await loadInstance();

package/src/index.js

@@ -20,6 +20,8 @@ const domainRules = require("./manifest/domainRules");
 const processManifest = require("./manifest/processManifest");
 const processRuntime = require("./manifest/processRuntime");
 const referencePolicies = require("./manifest/referencePolicies");
+const localDevelopment = require("./core/runtime/localDevelopment");
+const localExecutionPolicy = require("./core/runtime/localExecutionPolicy");
 
 module.exports = {
   start, createApp, activate,
@@ -88,6 +90,8 @@ module.exports = {
   receiveIntegrationWebhook: integrations.receiveWebhook,
   capabilities,
   operationalRequestHeaders,
+  localDevelopment,
+  localExecutionPolicy,
   PdfRenderingError: capabilities.PdfRenderingError,
   TransactionalEmailError: capabilities.TransactionalEmailError,
   GenericError, registry,