@oondemand/oon-core-back 0.7.4 → 0.7.8

package/README.md

@@ -1,5 +1,7 @@
 # OonCore Back - ativação de instâncias
 
+Para criar ou alterar um App, comece pela entrada curta distribuída pelo gerador em `.ooncore/AGENTS.md` e pelo índice `.ooncore/docs/TASK_INDEX.md`. Bootstrap, rotas privadas, permissões, prefixos, erros e `sensitiveBody` estão consolidados em `.ooncore/docs/PUBLIC_CONTRACTS.md`. Esta referência detalhada é para consulta sob demanda.
+
 ## 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.
@@ -91,3 +93,38 @@ defineRoutes("/integracao", (router) => {
 ```
 
 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.
+
+## Segredos V1 (0.7.6)
+
+`capabilities.secrets.put/status/use/remove` armazena objetos cifrados para Apps single_tenant dedicados. Declare `core.secrets` e `capabilitySettings["core.secrets"]={enabled:true}`. Rotas exigem permissão e sensitiveBody; use `req.accessContext`. Chave provisionada fora do banco, preservada em republicações. Veja o guia distribuído `SECRETS.md` para assinaturas, limites e recadastro explícito.
+
+
+### Aceite de convite (C2, SDK 0.7.7)
+
+`PUBLIC_APP_URL` deve conter a origem pública HTTPS do aplicativo, sem credenciais,
+query, fragmento ou subcaminho. HTTP é permitido apenas em loopback fora de produção.
+A configuração é validada antes de emitir/rotacionar o convite; o header Host não
+é usado como destino. Novos links usam `/accept-invite#token=...`.
+
+O frontend consulta `POST /core/invitations/inspect` com `{ token }`. Somente um
+convite pendente válido permite consultar a existência da identidade. O aceite
+usa `POST /core/invitations/accept` com `{ token, intent, password? }`:
+`authenticate` verifica a senha atual; `register` cria uma identidade com senha
+nova; `session` exige uma sessão válida do destinatário. Nenhum desses caminhos
+redefine a senha de uma identidade existente. Recuperação de senha continua no
+login da plataforma. O retorno após aceite é local e fixo, sem aceitar redirect
+arbitrário. Os endpoints antigos continuam disponíveis até o cutover coordenado.
+
+Provedores locais devem fornecer `auth.inspectInvitation({ req, invitation })`,
+retornando `{ accountExists: boolean, sessionUser?: { id, email } | null }`, além de
+`auth.provisionInvitation`. A sessão opcional deve ser validada como identidade
+(assinatura, expiração, versão de credencial e escopo), sem exigir o acesso que
+o convite ainda concederá. Uma sessão inválida retorna `sessionUser: null`.
+O provisionamento recebe também `intent` e deve verificar a prova correspondente,
+retornando `usuario` com `id` e `email` do destinatário. Sem hook de inspeção,
+um provedor local falha fechado e nunca delega identidades administrativas ao
+provedor de aplicativos.
+
+Publicar primeiro o suporte da Central (consulta e prova de identidade), depois
+lançar front/back do SDK juntos e atualizar consumidores. O bloqueio de integração
+comercial permanece até C3a/C3b; C2 não executa cutover nem reenvia convites.

package/package.json

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

package/src/api/access.routes.js

@@ -22,9 +22,10 @@ const {
   recoverPendingInvitation,
   assertNotLastAdmin,
 } = require("../core/rbac/storage");
-const { provisionInvitation } = require("../core/rbac/identityProvider");
+const { provisionInvitation, inspectInvitation } = require("../core/rbac/identityProvider");
 
 const router = express.Router();
+router.use(require("../core/rbac/centralInvitations").createRouter({ inviteUrl }));
 
 function requiredRbac() {
   if (!policy().enabled) {
@@ -36,10 +37,16 @@ function requiredRbac() {
 }
 
 function inviteUrl(req, token) {
-  const base = String(
-    process.env.PUBLIC_APP_URL || `${req.protocol || "http"}://${req.get("host") || req.headers.host}`,
-  ).replace(/\/$/, "");
-  return `${base}/accept-invite?token=${encodeURIComponent(token)}`;
+  let base;
+  try {
+    base = new URL(String(process.env.PUBLIC_APP_URL || ""));
+    const local = ["localhost", "127.0.0.1", "[::1]"].includes(base.hostname);
+    if ((base.protocol !== "https:" && !(base.protocol === "http:" && local && process.env.NODE_ENV !== "production"))
+      || base.username || base.password || base.search || base.hash || base.pathname !== "/") throw new Error();
+  } catch {
+    throw new GenericError("Configure PUBLIC_APP_URL com a origem HTTPS pública deste aplicativo.", { statusCode: 503, code: "INVITATION_PUBLIC_URL_INVALID" });
+  }
+  return `${base.origin}/accept-invite#token=${encodeURIComponent(token)}`;
 }
 
 function invitationView(invitation) {
@@ -139,6 +146,7 @@ router.post(
   asyncHandler(async (req, res) => {
     requiredRbac();
     const role = assertAssignable(req.usuario, req.body?.roleCode);
+    inviteUrl(req, ""); // Validate configuration before creating or rotating a token.
     const result = await createInvitation({
       email: req.body?.email,
       name: req.body?.name,
@@ -192,6 +200,7 @@ router.post(
     const previous = await Invitation.findOne({ _id: req.params.id, appCode: appCode() });
     if (!previous) throw new GenericError("Convite não encontrado.", { statusCode: 404 });
     assertAssignable(req.usuario, previous.roleCode);
+    inviteUrl(req, ""); // Validate configuration before creating or rotating a token.
     const result = await createInvitation({
       email: previous.email,
       name: previous.name,
@@ -277,11 +286,9 @@ router.patch(
   }),
 );
 
-router.get(
-  "/invitations/:token",
-  asyncHandler(async (req, res) => {
+const inspectHandler = asyncHandler(async (req, res) => {
     requiredRbac();
-    const invitation = await findInvitationByToken(req.params.token);
+    const invitation = await findInvitationByToken(req.params.token || req.body?.token);
     if (!invitation || invitation.status !== "pending") {
       throw new GenericError("Convite inválido, expirado ou já utilizado.", {
         statusCode: 410,
@@ -289,8 +296,12 @@ router.get(
       });
     }
     res.set("Cache-Control", "no-store");
+    const identity = await inspectInvitation({ req, invitation });
+    if (typeof identity?.accountExists !== "boolean") throw new GenericError("Resposta inválida do provedor de identidade.", { statusCode: 502 });
     res.json({
       invitation: {
+        accountExists: identity.accountExists,
+        sessionUser: identity.sessionUser || null,
         email: invitation.email,
         name: invitation.name,
         roleCode: invitation.roleCode,
@@ -298,19 +309,23 @@ router.get(
         expiresAt: invitation.expiresAt,
       },
     });
-  }),
-);
+  });
+router.get("/invitations/:token", inspectHandler);
+router.post("/invitations/inspect", inspectHandler);
 
-router.post(
-  "/invitations/:token/accept",
-  asyncHandler(async (req, res) => {
+const acceptHandler = asyncHandler(async (req, res) => {
     requiredRbac();
     const password = String(req.body?.password || "");
-    if (password.length < 8) {
-      throw new GenericError("A nova senha deve possuir pelo menos 8 caracteres.", { statusCode: 422 });
+    const intent = req.body?.intent;
+    if (intent !== undefined && !["register", "authenticate", "session"].includes(intent)) {
+      throw new GenericError("Forma de autenticação inválida.", { statusCode: 422 });
+    }
+    if ((intent === "register" || intent === undefined) && password.length < 8) {
+      throw new GenericError("A senha de cadastro deve possuir pelo menos 8 caracteres.", { statusCode: 422 });
     }
+    if (intent !== "session" && !password) throw new GenericError("Informe a senha.", { statusCode: 422 });
 
-    const invitation = await findInvitationByToken(req.params.token);
+    const invitation = await findInvitationByToken(req.params.token || req.body?.token);
     if (!invitation || invitation.status !== "pending") {
       throw new GenericError("Convite inválido, expirado ou já utilizado.", {
         statusCode: 410,
@@ -324,8 +339,12 @@ router.post(
       throw new GenericError("O acesso associado ao convite não está mais disponível.", { statusCode: 410 });
     }
 
-    const identity = await provisionInvitation({ req, invitation, password });
+    const identity = await provisionInvitation({ req, invitation, password, intent });
     const providerUser = identity?.usuario || identity?.user || identity;
+    if (!providerUser?.email || String(providerUser.email).trim().toLowerCase() !== invitation.email.toLowerCase()
+      || !(providerUser.id || providerUser._id)) {
+      throw new GenericError("Identidade retornada não corresponde ao convite.", { statusCode: 502, code: "INVITATION_IDENTITY_MISMATCH" });
+    }
     access.identityId = String(providerUser?.id || providerUser?._id || access.identityId || "") || undefined;
     access.name = providerUser?.nome || providerUser?.name || access.name;
     access.status = "active";
@@ -347,11 +366,12 @@ router.post(
 
     res.set("Cache-Control", "no-store");
     res.json({
-      message: "Convite aceito. A nova senha foi definida e o acesso está ativo.",
+      message: "Convite aceito. O acesso está ativo.",
       email: access.email,
     });
-  }),
-);
+  });
+router.post("/invitations/:token/accept", acceptHandler);
+router.post("/invitations/accept", acceptHandler);
 
 module.exports = router;
 module.exports.inviteUrl = inviteUrl;

package/src/api/core.routes.js

@@ -5,6 +5,11 @@ const fs = require("node:fs");
 const path = require("node:path");
 const registry = require("../core/registry");
 const ctx = require("../core/context");
+const { mergeScopedFilter } = require("../core/tenancy");
+const { granted } = require("../core/rbac/policy");
+const auth = require("../core/middlewares/auth");
+const GenericError = require("../core/errors/GenericError");
+const { effectiveRoles } = require("../core/middlewares/rbac");
 const corePackage = require("../../package.json");
 
 const router = express.Router();
@@ -115,9 +120,7 @@ const DASHBOARD_FILTER_OPERATORS = Object.freeze({
 });
 
 function dashboardError(message, statusCode = 422) {
-  const error = new Error(message);
-  error.statusCode = statusCode;
-  return error;
+  return new GenericError(message, { statusCode, code: "OON_DASHBOARD_REQUEST_REJECTED" });
 }
 
 function dashboardField(entry, field, usage) {
@@ -170,7 +173,7 @@ function normalizeDashboardFilter(entry, raw = {}) {
   ]));
 }
 
-async function executeDashboardMetric(entry, query = {}) {
+async function executeDashboardMetric(entry, query = {}, accessContext) {
   if (!entry?.mongooseModel) throw dashboardError("Model sem persistência para o Dashboard.");
   const id = String(query.id || "").trim();
   if (!id) throw dashboardError("Todo indicador do Dashboard deve possuir id.");
@@ -178,7 +181,7 @@ async function executeDashboardMetric(entry, query = {}) {
   if (!["count", "sum", "groupCount", "groupSum"].includes(kind)) {
     throw dashboardError(`Agregação de Dashboard não permitida: ${kind}.`);
   }
-  const filter = normalizeDashboardFilter(entry, query.filters || {});
+  const filter = mergeScopedFilter(entry, normalizeDashboardFilter(entry, query.filters || {}), accessContext);
 
   if (kind === "count") {
     return { id, kind, value: Number(await entry.mongooseModel.countDocuments(filter)) };
@@ -222,13 +225,18 @@ async function executeDashboardMetric(entry, query = {}) {
 }
 
 function canReadDashboardModel(req, entry) {
-  const roles = entry.definition?.crud?.roles?.read || [];
+  if (!req.usuario) return false;
+  const crud = entry.definition?.crud || {};
+  if (crud.permissions?.read) return granted(req.usuario.permissions, crud.permissions.read);
+  const roles = crud.roles?.read || [];
   if (!roles.length) return true;
-  const role = req.user?.tipo || req.user?.role;
-  return roles.includes(role);
+  if (req.usuario.commercialAccess && !req.usuario.commercialAccess.roleComplete) return false;
+  if (req.usuario.permissions?.includes("*")) return true;
+  const allowed = roles.map(role => String(role).trim().toLowerCase());
+  return effectiveRoles(req.usuario).some(role => allowed.includes(role));
 }
 
-router.post("/dashboard/query", async (req, res, next) => {
+router.post("/dashboard/query", auth, async (req, res, next) => {
   try {
     const queries = req.body?.queries;
     if (!Array.isArray(queries) || !queries.length) {
@@ -244,7 +252,7 @@ router.post("/dashboard/query", async (req, res, next) => {
       if (!canReadDashboardModel(req, entry)) {
         throw dashboardError(`Sem permissão de leitura para ${entry.name}.`, 403);
       }
-      return executeDashboardMetric(entry, query);
+      return executeDashboardMetric(entry, query, req.accessContext);
     }));
     res.json({ results });
   } catch (error) {

package/src/boot/loadCentral.js

@@ -70,6 +70,17 @@ function assertConfigBoundary(config, appManifest) {
 }
 
 function loadCentral(cwd = process.cwd()) {
+  cwd = path.resolve(cwd);
+  // start({ cwd }) always points to the backend, not the App root.
+  // Fail locally instead of starting a healthy server with no domain routes.
+  if (fs.existsSync(path.join(cwd, APP_MANIFEST_FILENAME))
+    && fs.existsSync(path.join(cwd, "backend", "src"))
+    && !fs.existsSync(path.join(cwd, "src"))
+    && !fs.existsSync(path.join(cwd, "central.config.js"))) {
+    const error = new Error(`OON_BACKEND_CWD_INVALID: ${cwd} é a raiz do App. Use start({ cwd: path.join(appRoot, "backend") }) ou execute o CLI em backend/.`);
+    error.code = "OON_BACKEND_CWD_INVALID";
+    throw error;
+  }
   let appManifest;
   const appManifestPath = resolveAppManifestPath(cwd);
   if (fs.existsSync(appManifestPath)) {

package/src/capabilities/index.js

@@ -6,6 +6,7 @@ const transactionalEmail = require("./transactionalEmail");
 const pdf = Object.freeze({ render: pdfRendering.render });
 
 module.exports = Object.freeze({
+  secrets: require("./secrets"),
   pdf,
   pdfRendering: pdf,
   configurePdfRendering: pdfRendering.configurePdfRendering,

package/src/capabilities/secrets/index.js

@@ -0,0 +1,113 @@
+"use strict";
+const crypto = require("node:crypto");
+const mongoose = require("mongoose");
+const ctx = require("../../core/context");
+const GenericError = require("../../core/errors/GenericError");
+const MAX_BYTES = 16384;
+function fail(code, statusCode = 409) {
+  return new GenericError({ SECRETS_UNAVAILABLE: "Restabeleça o provisionamento da chave antes de recadastrar.", SECRETS_REENTRY_REQUIRED: "Recadastre explicitamente a credencial.", SECRETS_NOT_FOUND: "Credencial não cadastrada.", SECRETS_USE_FAILED: "A operação com a credencial falhou." }[code] || "Operação de segredos recusada; confira declaração, contexto e parâmetros.", { code, statusCode });
+}
+function enabled() { return ctx.config.capabilities?.includes("core.secrets"); }
+function resolveScope(context, name) {
+  if (!enabled()) throw fail("SECRETS_NOT_DECLARED");
+  if (ctx.config.tenancyModel !== "single_tenant" || ctx.config.deploymentMode !== "dedicated") throw fail("SECRETS_UNSUPPORTED_RUNTIME");
+  if (typeof name !== "string" || !/^[a-z][a-z0-9._-]{0,63}$/.test(name)) throw fail("SECRETS_INVALID_NAME", 422);
+  const { OON_SECRETS_INSTANCE: instance, APP_ENVIRONMENT: environment, OON_SECRETS_TENANT: tenantId } = process.env;
+  const appCode = ctx.config.appCode;
+  if (!instance || !environment || !tenantId || !appCode) throw fail("SECRETS_UNAVAILABLE");
+  if (!context?.userId || context.tenancyModel !== "single_tenant" || context.tenantId !== tenantId || context.appCode !== appCode) throw fail("SECRETS_SCOPE_DENIED", 403);
+  return { scope: JSON.stringify([appCode, instance, environment, tenantId]), name };
+}
+function key() {
+  const value = process.env.OON_SECRETS_KEY;
+  if (!value || !/^[A-Za-z0-9+/]{43}=$/.test(value)) throw fail("SECRETS_UNAVAILABLE");
+  const result = Buffer.from(value, "base64");
+  if (result.length !== 32 || result.toString("base64") !== value) throw fail("SECRETS_UNAVAILABLE");
+  return result;
+}
+function models() {
+  if (!mongoose.models.OonSecret) {
+    const schema = new mongoose.Schema({ _id: String, scope: String, name: String, envelope: mongoose.Schema.Types.Mixed }, { versionKey: false, timestamps: true });
+    mongoose.model("OonSecret", schema, "oon_secrets");
+    mongoose.model("OonSecretAudit", new mongoose.Schema({ operation: String, actorId: String, scope: String, name: String, correlationId: String, at: Date }, { versionKey: false }), "oon_secret_audit");
+  }
+  return { Secret: mongoose.model("OonSecret"), Audit: mongoose.model("OonSecretAudit") };
+}
+function id(s) { return crypto.createHash("sha256").update(JSON.stringify([s.scope, s.name])).digest("hex"); }
+function aad(s) { return Buffer.from(JSON.stringify([1, "AES-256-GCM", s.scope, s.name])); }
+function decode(envelope, s) {
+  const k = key();
+  let plain;
+  try {
+    if (envelope?.version !== 1 || envelope.algorithm !== "AES-256-GCM" || !/^[a-f0-9]{24}$/.test(envelope.iv) || !/^[a-f0-9]{32}$/.test(envelope.tag) || typeof envelope.ciphertext !== "string" || envelope.ciphertext.length > MAX_BYTES * 2 || !/^[A-Za-z0-9+/]+={0,2}$/.test(envelope.ciphertext) || Buffer.from(envelope.ciphertext, "base64").toString("base64") !== envelope.ciphertext) throw Error();
+    const cipher = crypto.createDecipheriv("aes-256-gcm", k, Buffer.from(envelope.iv, "hex"));
+    cipher.setAAD(aad(s)); cipher.setAuthTag(Buffer.from(envelope.tag, "hex"));
+    plain = Buffer.concat([cipher.update(Buffer.from(envelope.ciphertext, "base64")), cipher.final()]);
+    return JSON.parse(plain.toString("utf8"));
+  } catch { throw fail("SECRETS_REENTRY_REQUIRED"); }
+  finally { k.fill(0); plain?.fill(0); }
+}
+async function audit(operation, s, context, correlationId) {
+  if (correlationId !== undefined && (typeof correlationId !== "string" || !/^[a-zA-Z0-9:_-]{1,128}$/.test(correlationId))) throw fail("SECRETS_INVALID_CORRELATION", 422);
+  await models().Audit.create({ operation, actorId: String(context.userId), ...s, correlationId, at: new Date() });
+}
+async function safe(operation) {
+  try { return await operation(); }
+  catch (error) { if (error instanceof GenericError && error.code?.startsWith("SECRETS_")) throw error; throw fail("SECRETS_STORAGE_UNAVAILABLE", 503); }
+}
+async function status({ name, context, correlationId } = {}) {
+  return safe(async () => {
+    const s = resolveScope(context, name);
+    await audit("status", s, context, correlationId);
+    const row = await models().Secret.findById(id(s)).lean();
+    try { const k = key(); k.fill(0); } catch { return { state: "reentry_required", reason: "key_unavailable", action: "restore_provisioning" }; }
+    if (!row) return { state: "absent" };
+    try { decode(row.envelope, s); return { state: "available" }; }
+    catch { return { state: "reentry_required", reason: "incompatible_or_unreadable", action: "replace" }; }
+  });
+}
+async function put({ name, value, context, correlationId, replace = false } = {}) {
+  return safe(async () => {
+    const s = resolveScope(context, name);
+    let plain;
+    try {
+      if (!value || Object.getPrototypeOf(value) !== Object.prototype) throw Error();
+      plain = Buffer.from(JSON.stringify(value));
+      const parsed = JSON.parse(plain.toString("utf8"));
+      if (plain.length > MAX_BYTES || !parsed || Array.isArray(parsed) || typeof parsed !== "object" || !Object.keys(parsed).length) throw Error();
+    } catch { plain?.fill(0); throw fail("SECRETS_INVALID_VALUE", 422); }
+    let k;
+    try {
+      k = key();
+      const existing = await models().Secret.findById(id(s)).lean();
+      if (existing && replace !== true) { try { decode(existing.envelope, s); } catch { throw fail("SECRETS_REENTRY_REQUIRED"); } }
+      const iv = crypto.randomBytes(12);
+      const cipher = crypto.createCipheriv("aes-256-gcm", k, iv); cipher.setAAD(aad(s));
+      const ciphertext = Buffer.concat([cipher.update(plain), cipher.final()]).toString("base64");
+      const envelope = { version: 1, algorithm: "AES-256-GCM", iv: iv.toString("hex"), tag: cipher.getAuthTag().toString("hex"), ciphertext };
+      await audit("put", s, context, correlationId);
+      // Deterministic _id makes concurrent first writes use Mongo's unique primary key.
+      try { await models().Secret.updateOne({ _id: id(s) }, { $set: { ...s, envelope } }, { upsert: true }); }
+      catch (error) { if (error.code !== 11000) throw error; await models().Secret.updateOne({ _id: id(s) }, { $set: { ...s, envelope } }, { upsert: true }); }
+      return { state: "available" };
+    } finally { k?.fill(0); plain.fill(0); }
+  });
+}
+async function use({ name, context, correlationId } = {}, callback) {
+  const value = await safe(async () => {
+    const s = resolveScope(context, name);
+    const row = await models().Secret.findById(id(s)).lean();
+    if (!row) throw fail("SECRETS_NOT_FOUND");
+    const value = decode(row.envelope, s);
+    await audit("use", s, context, correlationId);
+    return value;
+  });
+  try { if (typeof callback !== "function") throw Error(); await callback(value); }
+  catch { throw fail("SECRETS_USE_FAILED", 502); }
+  finally { for (const name of Object.keys(value)) { try { delete value[name]; } catch { /* consumer may freeze retained copies */ } } }
+  // No callback return value crosses this API boundary.
+}
+async function remove({ name, context, correlationId } = {}) {
+  return safe(async () => { const s = resolveScope(context, name); await audit("remove", s, context, correlationId); await models().Secret.deleteOne({ _id: id(s) }); return { state: "absent" }; });
+}
+module.exports = Object.freeze({ put, status, use, remove });

package/src/core/define.js

@@ -150,13 +150,26 @@ function definePipeline(name, config) {
 }
 
 function defineRoutes(basePath, builder) {
+  const invalid = (method, route, reason) => {
+    const error = new TypeError(`defineRoutes(${String(basePath)}) ${method} ${String(route)}: ${reason} Use router.private.post("/rota", { permission: "recurso.write" }, handler) ou ("/rota", handler).`);
+    error.code = "OON_ROUTE_REGISTRATION_INVALID";
+    throw error;
+  };
+  if (typeof builder !== "function") invalid("builder", "", "builder deve ser uma função.");
   const expressRouter = express.Router();
 
-  const wrapPrivate = (method) => (path, opts = {}, handler) => {
+  const wrapPrivate = (method) => (...args) => {
+    let [path, opts = {}, handler] = args;
+    if (args.length < 2 || args.length > 3) invalid(method, path, "São aceitos dois ou três argumentos.");
+    if (typeof opts === "function" && args.length === 3) {
+      invalid(method, path, "Middleware na posição de opções descartaria o handler final.");
+    }
     if (typeof opts === "function") {
       handler = opts;
       opts = {};
     }
+    if (!opts || typeof opts !== "object" || Array.isArray(opts)) invalid(method, path, "Opções devem ser um objeto.");
+    if (typeof handler !== "function") invalid(method, path, "Handler ausente ou inválido.");
     const chain = [auth];
     const required = opts.permission || opts.permissions;
     if (required) chain.push(requirePermission(required));
@@ -170,7 +183,9 @@ function defineRoutes(basePath, builder) {
     expressRouter[method](path, ...chain, asyncHandler(handler));
   };
 
-  const wrapPublic = (method) => (path, handler) => {
+  const wrapPublic = (method) => (...args) => {
+    const [path, handler] = args;
+    if (args.length !== 2 || typeof handler !== "function") invalid(method, path, "Rota pública exige (path, handler).");
     expressRouter[method](path, asyncHandler(handler));
   };
 

package/src/core/middlewares/auth.js

@@ -137,6 +137,14 @@ async function applyEffectiveAccess(usuario) {
       rbacMode: "app-commercial", commercialAccess: { ...authority,
         roleComplete: !local.includes("*") && local.every(p => permissions.includes(p)) } };
   }
+  if (usuario?.canonicalAccess && typeof ctx.config.auth?.verifyToken !== "function") {
+    const source = usuario.canonicalAccess;
+    const role = roleByCode(source.roleCode);
+    if (!source.grantId || source.tenantId !== usuario.tenantId || !role) {
+      throw Object.assign(Error("Concessão central inválida."), { statusCode: 403, code: "CENTRAL_ACCESS_INVALID" });
+    }
+    return { ...usuario, roleCode: role.code, permissions: rolePermissions(role), accessStatus: "active", mustChangePassword: false, rbacMode: "central-invitation" };
+  }
   const access = await resolveUserAccess(usuario);
   return {
     ...usuario,

package/src/core/middlewares/requestLog.js

@@ -8,10 +8,11 @@ const registry = require("../registry");
 const requestLog = async (req, res, next) => {
   if (req.method === "GET") return next();
 
-  const sensitiveBody = await registry.isSensitiveRequest(req.method, req.url || req.originalUrl);
+  const invitationRequest = /\/(?:core\/invitations|convites)\//.test(String(req.originalUrl || req.url));
+  const sensitiveBody = invitationRequest || await registry.isSensitiveRequest(req.method, req.url || req.originalUrl);
   const log = new Log({
     usuario: req.usuario || null,
-    endpoint: req.originalUrl,
+    endpoint: invitationRequest ? String(req.originalUrl).replace(/(\/core\/invitations\/)[^/?]+/, "$1[redacted]").split("?")[0] : req.originalUrl,
     metodo: req.method,
     ip: req.ip || req.headers["x-forwarded-for"] || req.connection?.remoteAddress,
     correlationId: req.correlationId,

package/src/core/rbac/centralInvitations.js

@@ -0,0 +1,70 @@
+"use strict";
+const express = require("express");
+const ctx = require("../context");
+const auth = require("../middlewares/auth");
+const { asyncHandler } = require("../utils/helpers");
+const GenericError = require("../errors/GenericError");
+const { defaultProviderCall } = require("./identityProvider");
+const { models, appCode, audit } = require("./storage");
+const base = "/integracao/autenticacao-aplicativos/convites/v1";
+function enabled() { return process.env.OON_CENTRAL_INVITATIONS_ENABLED === "true" && typeof ctx.config.auth?.provisionInvitation !== "function" && typeof ctx.config.auth?.verifyToken !== "function" && process.env.OON_RUNTIME_MODE !== "local"; }
+async function cutover() {
+  // No import or token recovery. Idempotent state transition touches only old pending invitations.
+  const { Invitation } = models();
+  const session = await Invitation.db.startSession();
+  try { await session.withTransaction(async () => {
+    const rows = await Invitation.find({ appCode: appCode(), status: "pending" }).session(session);
+    for (const row of rows) {
+      const changed = await Invitation.updateOne({ _id: row._id, status: "pending" }, { $set: { status: "revoked", revokedAt: new Date() } }, { session });
+      if (changed.modifiedCount) await audit("invitation.cutover.v1", { actor: "system:cutover", target: row.email, context: { invitationId: String(row._id), cutoverId: "central-invitations-v1" }, session });
+    }
+  }); } finally { await session.endSession(); }
+}
+function createRouter({ inviteUrl }) {
+  const router = express.Router();
+  router.use((req, _res, next) => enabled() ? next() : next("router"));
+  const call = (req, payload) => defaultProviderCall(req, `${base}/command`, payload);
+  const management = handler => [auth, asyncHandler(async (req, res) => { await call(req, { command: "list" }); await cutover(); res.set("Cache-Control", "no-store"); await handler(req, res); })];
+  function identifier(value) {
+    const match = /^central:([a-f\d]{24})$/i.exec(String(value));
+    if (!match) throw new GenericError("Convite anterior ao corte. Solicite um novo convite.", { statusCode: 410, code: "INVITATION_LEGACY_DISABLED" });
+    return match[1];
+  }
+  function invitation(row) { return { ...row, id: `central:${row.id}` }; }
+  const access = row => ({ id: `central:${row.id}`, email: row.email, name: row.name, roleCode: row.roleCode, status: row.status === "accepted" ? "active" : row.status === "pending" ? "invited" : "revoked", origin: "central", invitation: invitation(row) });
+  async function withLink(req, result) {
+    if (result.invitation.status && result.invitation.status !== "pending") return { invitation: invitation(result.invitation), access: access(result.invitation) };
+    const copied = await call(req, { command: "copy", id: result.invitation.id });
+    return { invitation: invitation(copied.invitation), access: access(copied.invitation), inviteUrl: inviteUrl(req, copied.token) };
+  }
+  router.get("/users", ...management(async (req, res) => {
+    const result = await call(req, { command: "list" });
+    const canonical = result.invitations.map(access);
+    const identities = new Set(canonical.map(row => row.email));
+    const local = req.usuario?.commercialAccess ? [] : await models().UserAccess.find({ appCode: appCode(), status: { $ne: "invited" } }).lean();
+    res.json({ results: [...canonical, ...local.filter(row => !identities.has(row.email)).map(row => ({ id: String(row._id), email: row.email, name: row.name, roleCode: row.roleCode, status: row.status, origin: "local" }))] });
+  }));
+  router.post("/users/invitations", ...management(async (req, res) => {
+    inviteUrl(req, "");
+    const result = await call(req, { command: "create", email: req.body?.email, roleCode: req.body?.roleCode, version: 0 });
+    res.status(201).json(await withLink(req, result));
+  }));
+  router.get("/users/invitations/:id/link", ...management(async (req, res) => res.json(await withLink(req, { invitation: { id: identifier(req.params.id) } }))));
+  router.post("/users/invitations/:id/regenerate", ...management(async (req, res) => {
+    inviteUrl(req, "");
+    res.json(await withLink(req, await call(req, { command: "reissue", id: identifier(req.params.id), version: req.body?.version })));
+  }));
+  router.delete("/users/invitations/:id", ...management(async (req, res) => res.json(await call(req, { command: "revoke", id: identifier(req.params.id), version: req.body?.version }))));
+  router.patch("/users/:id", auth, asyncHandler(async (req, _res, next) => { if (!String(req.params.id).startsWith("central:")) return next("router"); throw new GenericError("Gerencie a concessão na Central; esta lista é uma projeção de leitura.", { statusCode: 409, code: "CENTRAL_ACCESS_COMMAND_REQUIRED" }); }));
+  for (const action of ["inspect", "accept", "decline"]) router.post(`/invitations/${action}`, asyncHandler(async (req, res) => {
+    if (!String(req.body?.token || "").startsWith("c3.")) throw new GenericError("Convite anterior ao corte. Solicite um novo convite.", { statusCode: 410, code: "INVITATION_LEGACY_DISABLED" });
+    res.set("Cache-Control", "no-store");
+    if (action === "inspect") return res.json(await defaultProviderCall(req, `${base}/inspect`, { token: req.body.token }));
+    const result = await call(req, { command: action, token: req.body.token, version: req.body.version, intent: req.body.intent, password: req.body.password, registration: req.body.registration });
+    res.json({ ...result, message: "Convite processado pela Central." });
+  }));
+  router.all("/invitations/:token/accept", (_req, res) => res.status(410).json({ code: "INVITATION_LEGACY_DISABLED", message: "Solicite um novo convite." }));
+  router.get("/invitations/:token", (_req, res) => res.status(410).json({ code: "INVITATION_LEGACY_DISABLED", message: "Solicite um novo convite." }));
+  return router;
+}
+module.exports = { enabled, cutover, createRouter };

package/src/core/rbac/identityProvider.js

@@ -10,6 +10,7 @@ const {
 } = require("../utils/instanceActivation");
 
 const IDENTITY_PATHS = Object.freeze({
+  inspectInvitation: "/integracao/autenticacao-aplicativos/convites/inspecionar",
   provisionInvitation: "/integracao/autenticacao-aplicativos/convites/provisionar",
   changeFirstAccessPassword: "/integracao/autenticacao-aplicativos/primeiro-acesso/senha",
 });
@@ -25,6 +26,9 @@ async function defaultProviderCall(req, path, payload) {
 
   try {
     const headers = instanceHeaders(instance);
+    for (const key of ["idempotency-key", "x-correlation-id", "x-oon-tenant-id"]) {
+      if (req?.headers?.[key]) headers[key] = req.headers[key];
+    }
     if (req?.headers?.authorization) headers.Authorization = req.headers.authorization;
     const response = await providerPost(req, path, payload, headers);
     return response.data;
@@ -38,14 +42,24 @@ async function defaultProviderCall(req, path, payload) {
   }
 }
 
-async function provisionInvitation({ req, invitation, password }) {
+async function inspectInvitation({ req, invitation }) {
+  const hook = ctx.config.auth?.inspectInvitation;
+  if (typeof hook === "function") return hook({ req, invitation });
+  if (typeof ctx.config.auth?.provisionInvitation === "function") {
+    throw new GenericError("O provedor local precisa disponibilizar a consulta de convite.", { statusCode: 503, code: "INVITATION_INSPECTION_REQUIRED" });
+  }
+  return defaultProviderCall(req, IDENTITY_PATHS.inspectInvitation, { email: invitation.email });
+}
+
+async function provisionInvitation({ req, invitation, password, intent }) {
   const hook = ctx.config.auth?.provisionInvitation;
-  if (typeof hook === "function") return hook({ req, invitation, password });
+  if (typeof hook === "function") return hook({ req, invitation, password, intent });
   return defaultProviderCall(req, IDENTITY_PATHS.provisionInvitation, {
     email: invitation.email,
     nome: invitation.name,
     roleCode: invitation.roleCode,
     password,
+    intent,
     invitationFingerprint: invitation.tokenFingerprint,
   });
 }
@@ -63,6 +77,7 @@ async function changeFirstAccessPassword({ req, user, password }) {
 module.exports = {
   IDENTITY_PATHS,
   defaultProviderCall,
+  inspectInvitation,
   provisionInvitation,
   changeFirstAccessPassword,
 };

package/src/core/rbac/storage.js

@@ -105,10 +105,10 @@ function sanitizeSnapshot(value) {
   return plain;
 }
 
-async function audit(event, { actor, target, before, after, context } = {}) {
+async function audit(event, { actor, target, before, after, context, session } = {}) {
   if (mongoose.connection.readyState !== 1) return null;
   const { Audit } = models();
-  return Audit.create({
+  const data = {
     appCode: appCode(),
     event,
     actor: typeof actor === "string" ? actor : actorKey(actor),
@@ -117,7 +117,8 @@ async function audit(event, { actor, target, before, after, context } = {}) {
     after: sanitizeSnapshot(after),
     context,
     at: new Date(),
-  });
+  };
+  return session ? (await Audit.create([data], { session }))[0] : Audit.create(data);
 }
 
 function accessError(message, code = "RBAC_ACCESS_DENIED", statusCode = 403) {

package/src/delivery/runtime.js

@@ -6,6 +6,8 @@ const { kubectl } = require("./command");
 const { validateInfraFromCluster } = require("../deploy/contracts/infra-contract");
 const { provisionMongo, validateMongoUri } = require("./mongoProvisioning");
 
+const { provisionSecrets } = require("./secretsProvisioning");
+
 const RESOURCE_PROFILES = {
   nano: { cpuRequest: "50m", cpuLimit: "250m", memoryRequest: "96Mi", memoryLimit: "256Mi" },
   small: { cpuRequest: "100m", cpuLimit: "500m", memoryRequest: "128Mi", memoryLimit: "512Mi" },
@@ -111,6 +113,11 @@ spec:
           imagePullPolicy: IfNotPresent
           ports: [{ name: http, containerPort: 8080 }]
           envFrom: [{ secretRef: { name: oon-runtime } }]
+${context.functionalCapabilities?.["core.secrets"]?.enabled ? `          env:
+            - name: OON_SECRETS_KEY
+              valueFrom:
+                secretKeyRef: { name: oon-core-secrets, key: OON_SECRETS_KEY, optional: true }
+` : ""}
           resources:
             requests: { cpu: ${resources.cpuRequest}, memory: ${resources.memoryRequest} }
             limits: { cpu: ${resources.cpuLimit}, memory: ${resources.memoryLimit} }
@@ -171,6 +178,10 @@ function applyRuntimeSecret({ context, mongoUri, encryptionKey, extraSecrets = {
     CENTRAL_ATIVACAO_API_URL: context.activationApiUrl,
     INSTANCE_CREDENTIAL_ENCRYPTION_KEY: encryptionKey,
     ...extraSecrets,
+    ...(context.functionalCapabilities?.["core.secrets"]?.enabled ? {
+      OON_SECRETS_INSTANCE: context.secretsScope.instance,
+      OON_SECRETS_TENANT: context.secretsScope.tenantId,
+    } : {}),
   };
   const args = ["-n", context.namespace, "create", "secret", "generic", "oon-runtime"];
   for (const [key, value] of Object.entries(literals)) args.push(`--from-literal=${key}=${value}`);
@@ -244,6 +255,7 @@ async function provisionRuntime({ context, extraSecrets = {} }) {
       "oon-runtime",
       "INSTANCE_CREDENTIAL_ENCRYPTION_KEY",
     ) || randomSecret(48);
+  provisionSecrets(context);
   applyRuntimeSecret({ context, mongoUri, encryptionKey, extraSecrets });
   return { infra, databaseName, credentialRotated };
 }
@@ -294,4 +306,4 @@ async function activateMember(context) {
   return data;
 }
 
-module.exports = { RESOURCE_PROFILES, randomSecret, dnsLabel, kubernetesLabelValue, provisionMongo, validateMongoUri, baselineManifest, runtimeManifest, provisionRuntime, deployRuntime, waitHttp, activateMember };
+module.exports = { supportsSecretsV1: true, RESOURCE_PROFILES, randomSecret, dnsLabel, kubernetesLabelValue, provisionMongo, validateMongoUri, baselineManifest, runtimeManifest, provisionRuntime, deployRuntime, waitHttp, activateMember };

package/src/delivery/secretsProvisioning.js

@@ -0,0 +1,41 @@
+"use strict";
+const crypto = require("node:crypto");
+const { spawnSync } = require("node:child_process");
+const SECRET = "oon-core-secrets";
+const MARKER = "oon-core-secrets-initialized";
+function command(args, input) {
+  const result = spawnSync("kubectl", args, { input, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
+  // Never surface kubectl output: admission errors may reflect the submitted object.
+  if (result.error || result.status !== 0) throw Error("SECRETS_PROVISIONING_FAILED: acesso ao cluster recusado ou indisponível.");
+  return result.stdout;
+}
+function provisionSecrets(context, run = command) {
+  if (!context.functionalCapabilities?.["core.secrets"]?.enabled) return;
+  if (!context.secretsScope?.instance || !context.secretsScope?.tenantId || !context.environment) throw Error("SECRETS_SCOPE_REQUIRED");
+  const read = (kind, name) => {
+    const output = run(["-n", context.namespace, "get", kind, name, "--ignore-not-found", "-o", "json"]);
+    try { return output?.trim() ? JSON.parse(output) : null; } catch { throw Error("SECRETS_CLUSTER_RESPONSE_INVALID"); }
+  };
+  const binding = JSON.stringify([context.appCode, context.secretsScope.instance, context.environment, context.secretsScope.tenantId]);
+  let secret = read("secret", SECRET);
+  const marker = read("secret", MARKER);
+  if (marker && Buffer.from(marker.data?.binding || "", "base64").toString("utf8") !== binding) throw Error("SECRETS_SCOPE_MISMATCH");
+  if (!secret) {
+    if (marker) throw Error("SECRETS_KEY_MISSING: restabeleça a chave por procedimento controlado.");
+    const document = { apiVersion: "v1", kind: "Secret", immutable: true, metadata: { name: SECRET, namespace: context.namespace }, type: "Opaque", stringData: { OON_SECRETS_KEY: crypto.randomBytes(32).toString("base64"), OON_SECRETS_BINDING: binding } };
+    // Create, never apply/upsert. A concurrent creator's value wins atomically.
+    try { run(["create", "-f", "-"], JSON.stringify(document)); }
+    catch { /* A failed create is only recoverable if a valid winner can be read. */ }
+    secret = read("secret", SECRET);
+  }
+  const decode = key => Buffer.from(secret?.data?.[key] || "", "base64").toString("utf8");
+  const keyValue = decode("OON_SECRETS_KEY");
+  if (!secret || secret.immutable !== true || decode("OON_SECRETS_BINDING") !== binding || !/^[A-Za-z0-9+/]{43}=$/.test(keyValue) || Buffer.from(keyValue, "base64").toString("base64") !== keyValue) throw Error("SECRETS_KEY_INVALID: provisionamento requer intervenção.");
+  if (!marker) {
+    const doc = { apiVersion: "v1", kind: "Secret", immutable: true, metadata: { name: MARKER, namespace: context.namespace }, type: "Opaque", stringData: { binding } };
+    try { run(["create", "-f", "-"], JSON.stringify(doc)); }
+    catch { const winner = read("secret", MARKER); if (Buffer.from(winner?.data?.binding || "", "base64").toString("utf8") !== binding) throw Error("SECRETS_MARKER_UNAVAILABLE"); }
+  }
+  // Never return key material to the executor/context/evidence serializer.
+}
+module.exports = { provisionSecrets };

package/src/manifest/appManifest.js

@@ -147,6 +147,10 @@ function validateCapabilitySettings(settings, capabilities, issues) {
       addIssue(issues, base, "exige a mesma capability declarada em capabilities.");
       continue;
     }
+    if (capability === "core.secrets") {
+      if (!isPlainObject(config) || config.enabled !== true || Object.keys(config).some(key => key !== "enabled")) addIssue(issues, base, "use apenas { enabled: true }.");
+      continue;
+    }
     if (capability !== TRANSACTIONAL_EMAIL_CAPABILITY) {
       addIssue(issues, base, "capability configurável desconhecida.");
       continue;
@@ -286,6 +290,10 @@ function validateAppManifest(input, { coreVersion = corePackage.version } = {})
     });
   }
   validateCapabilitySettings(input.capabilitySettings, input.capabilities, issues);
+  if (input.capabilities?.includes("core.secrets")) {
+    if (dimensions.tenancyModel !== "single_tenant" || dimensions.deploymentMode !== "dedicated") addIssue(issues, "capabilities", "core.secrets V1 exige single_tenant dedicado.");
+    if (input.capabilitySettings?.["core.secrets"]?.enabled !== true) addIssue(issues, "capabilitySettings.core.secrets", "declare { enabled: true } para provisionamento.");
+  }
   validateCompatibility(input.compatibility, issues, coreVersion);
   validateActivation(input.activation, issues);
   if (input.auth !== undefined) {

package/src/manifest/processRuntime.js

@@ -366,7 +366,8 @@ async function assertAtomicInvariants(entry, candidate, current, session) {
     }
 
     const match = {
-      [rule.parentLocalField]: parentId,
+      // Aggregation does not apply Mongoose query casting to HTTP string IDs.
+      [rule.parentLocalField]: entry.mongooseModel.schema?.path(rule.parentLocalField)?.cast(parentId) ?? parentId,
       ...compileMongoMatch(rule.match),
     };
     if (current?._id) match._id = { $ne: current._id };
@@ -514,6 +515,9 @@ async function recalculateTarget(entry, selectors, options = {}) {
         updateOne: {
           filter: { _id: documents[index]._id },
           update: { $set: changed },
+          // Only server-derived, validated changes reach this recalculation path.
+          // readonly still rejects client writes in applyDomainMutation.
+          overwriteImmutable: true,
         },
       });
     }