@oondemand/oon-core-back 0.3.75 → 0.3.76

package/package.json

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

package/src/core/errors/GenericError.js

@@ -1,12 +1,13 @@
 /**
  * Erro de domínio reconhecido pelo error middleware do Core.
- * Permite que services/triggers sinalizem statusCode e detalhes.
+ * Permite que services/triggers sinalizem statusCode, code e detalhes.
  */
 class GenericError extends Error {
-  constructor(message, { statusCode = 400, details = null } = {}) {
+  constructor(message, { statusCode = 400, code = undefined, details = null } = {}) {
     super(message);
     this.name = "GenericError";
     this.statusCode = statusCode;
+    this.code = code;
     this.details = details;
   }
 }

package/src/core/factories/crudController.js

@@ -1,5 +1,6 @@
 const Helpers = require("../utils/helpers");
 const registry = require("../registry");
+const { scopeMutation } = require("../tenancy");
 const {
   prepareProcessMutation,
   assertAtomicInvariants,
@@ -38,13 +39,27 @@ function createCrudController(entry, service) {
     if (validate) await validate(data, context);
   };
 
-  const prepareCreate = async (data, method = "post", session = null) => {
-    const prepared = await prepareProcessMutation(entry, {}, data, {
+  const prepareCreate = async (
+    data,
+    method = "post",
+    session = null,
+    accessContext = undefined,
+  ) => {
+    const scopedData = scopeMutation(entry, data, accessContext);
+    const prepared = await prepareProcessMutation(entry, {}, scopedData, {
       op: "create",
       session,
+      accessContext,
     });
 
-    await assertReferencePolicies(entry, prepared.consolidated, { session });
+    // Reaplica o escopo depois das regras para impedir que fórmula/hook de
+    // domínio substitua tenantId/usuarioId confiável. O controller usa o
+    // contrato público de tenancy e não exige helpers extras em services
+    // customizados/legados.
+    prepared.changes = scopeMutation(entry, prepared.changes, accessContext);
+    prepared.consolidated = scopeMutation(entry, prepared.consolidated, accessContext);
+
+    await assertReferencePolicies(entry, prepared.consolidated, { session, accessContext });
     await runCustomValidation(prepared.consolidated, {
       op: "create",
       method,
@@ -54,14 +69,24 @@ function createCrudController(entry, service) {
       consolidated: prepared.consolidated,
       changedFields: prepared.changedFields,
       session,
+      accessContext,
     });
     return prepared;
   };
 
-  const prepareUpdate = async (id, changes, method, session = null) => {
+  const prepareUpdate = async (
+    id,
+    changes,
+    method,
+    session = null,
+    accessContext = undefined,
+  ) => {
+    const scopedChanges = scopeMutation(entry, changes, accessContext);
     const validate = registry.getValidation(entry.name);
     if (!validate && !hasDomainRules(entry) && !hasProcessRules(entry)) {
-      const normalizedChanges = changes && typeof changes === "object" ? { ...changes } : {};
+      const normalizedChanges = scopedChanges && typeof scopedChanges === "object"
+        ? { ...scopedChanges }
+        : {};
       return {
         current: null,
         requestedChanges: normalizedChanges,
@@ -71,14 +96,17 @@ function createCrudController(entry, service) {
       };
     }
 
-    const currentRecord = await service.getById(id, { session });
+    const currentRecord = await service.getById(id, { session, accessContext });
     const current = toPlainRecord(currentRecord);
-    const prepared = await prepareProcessMutation(entry, current, changes, {
+    const prepared = await prepareProcessMutation(entry, current, scopedChanges, {
       op: "update",
       session,
+      accessContext,
     });
+    prepared.changes = scopeMutation(entry, prepared.changes, accessContext);
+    prepared.consolidated = scopeMutation(entry, prepared.consolidated, accessContext);
 
-    await assertReferencePolicies(entry, prepared.consolidated, { session });
+    await assertReferencePolicies(entry, prepared.consolidated, { session, accessContext });
     if (validate) {
       await validate(prepared.consolidated, {
         op: "update",
@@ -90,30 +118,33 @@ function createCrudController(entry, service) {
         consolidated: prepared.consolidated,
         changedFields: prepared.changedFields,
         session,
+        accessContext,
       });
     }
 
     return { current, ...prepared };
   };
 
-  async function createOne(data, method, session) {
-    const prepared = await prepareCreate(data, method, session);
+  async function createOne(data, method, session, accessContext) {
+    const prepared = await prepareCreate(data, method, session, accessContext);
     await assertAtomicInvariants(entry, prepared.consolidated, null, session);
-    const record = await service.create(prepared.changes, { session });
+    const record = await service.create(prepared.changes, { session, accessContext });
     await recalculateDependents(entry, null, toPlainRecord(record), {
       session,
       changedFields: prepared.changedFields,
+      accessContext,
     });
     return record;
   }
 
-  async function updateOne(id, changes, method, session) {
-    const prepared = await prepareUpdate(id, changes, method, session);
+  async function updateOne(id, changes, method, session, accessContext) {
+    const prepared = await prepareUpdate(id, changes, method, session, accessContext);
     await assertAtomicInvariants(entry, prepared.consolidated, prepared.current, session);
-    const record = await service.update(id, prepared.changes, { session });
+    const record = await service.update(id, prepared.changes, { session, accessContext });
     await recalculateDependents(entry, prepared.current, toPlainRecord(record), {
       session,
       changedFields: prepared.changedFields,
+      accessContext,
     });
     return record;
   }
@@ -127,19 +158,27 @@ function createCrudController(entry, service) {
         searchTerm,
         sort,
         filtros,
+        accessContext: req.accessContext,
       });
       Helpers.sendPaginatedResponse({ res, statusCode: 200, results, pagination });
     },
 
     async getById(req, res) {
-      const registro = await service.getById(req.params.id);
+      const registro = await service.getById(req.params.id, {
+        accessContext: req.accessContext,
+      });
       Helpers.sendResponse({ res, statusCode: 200, [entry.singular]: registro });
     },
 
     async create(req, res) {
       const registro = await withProcessTransaction(
         entry,
-        (session) => createOne(req.body ?? {}, "post", session),
+        (session) => createOne(
+          req.body ?? {},
+          "post",
+          session,
+          req.accessContext,
+        ),
       );
       Helpers.sendResponse({ res, statusCode: 201, [entry.singular]: registro });
     },
@@ -147,7 +186,13 @@ function createCrudController(entry, service) {
     async update(req, res) {
       const registro = await withProcessTransaction(
         entry,
-        (session) => updateOne(req.params.id, req.body ?? {}, "put", session),
+        (session) => updateOne(
+          req.params.id,
+          req.body ?? {},
+          "put",
+          session,
+          req.accessContext,
+        ),
       );
       Helpers.sendResponse({ res, statusCode: 200, [entry.singular]: registro });
     },
@@ -155,20 +200,36 @@ function createCrudController(entry, service) {
     async patch(req, res) {
       const registro = await withProcessTransaction(
         entry,
-        (session) => updateOne(req.params.id, req.body ?? {}, "patch", session),
+        (session) => updateOne(
+          req.params.id,
+          req.body ?? {},
+          "patch",
+          session,
+          req.accessContext,
+        ),
       );
       Helpers.sendResponse({ res, statusCode: 200, [entry.singular]: registro });
     },
 
     async remove(req, res) {
       const registro = await withProcessTransaction(entry, async (session) => {
-        const currentRecord = await service.getById(req.params.id, { session });
+        const currentRecord = await service.getById(req.params.id, {
+          session,
+          accessContext: req.accessContext,
+        });
         const current = toPlainRecord(currentRecord);
-        await assertDeleteAllowed(entry, req.params.id, { session });
-        const removed = await service.remove(req.params.id, { session });
+        await assertDeleteAllowed(entry, req.params.id, {
+          session,
+          accessContext: req.accessContext,
+        });
+        const removed = await service.remove(req.params.id, {
+          session,
+          accessContext: req.accessContext,
+        });
         await recalculateDependents(entry, current, null, {
           session,
           changedFields: Object.keys(current),
+          accessContext: req.accessContext,
         });
         return removed;
       });
@@ -178,16 +239,22 @@ function createCrudController(entry, service) {
     async importMany(req, res) {
       const rows = req.body?.rows || req.body;
       if (!Array.isArray(rows)) {
-        const result = await service.importMany(rows);
+        const result = await service.importMany(rows, {
+          accessContext: req.accessContext,
+        });
         Helpers.sendResponse({ res, statusCode: 201, ...result });
         return;
       }
 
       if (!hasProcessRules(entry)) {
         const preparedRows = await Promise.all(
-          rows.map(async (row) => (await prepareCreate(row, "import")).changes),
+          rows.map(async (row) => (
+            await prepareCreate(row, "import", null, req.accessContext)
+          ).changes),
         );
-        const result = await service.importMany(preparedRows);
+        const result = await service.importMany(preparedRows, {
+          accessContext: req.accessContext,
+        });
         Helpers.sendResponse({ res, statusCode: 201, ...result });
         return;
       }
@@ -195,7 +262,7 @@ function createCrudController(entry, service) {
       let inserted = 0;
       for (const row of rows) {
         await withProcessTransaction(entry, async (session) => {
-          await createOne(row, "import", session);
+          await createOne(row, "import", session, req.accessContext);
           inserted += 1;
         });
       }
@@ -203,7 +270,9 @@ function createCrudController(entry, service) {
     },
 
     async exportAll(req, res) {
-      const results = await service.exportAll(req.query);
+      const results = await service.exportAll(req.query, {
+        accessContext: req.accessContext,
+      });
       Helpers.sendResponse({ res, statusCode: 200, results });
     },
   };
@@ -214,4 +283,4 @@ module.exports = {
   toPlainRecord,
   hasDomainRules,
   hasProcessRules,
-};
+};

package/src/core/factories/crudService.js

@@ -1,5 +1,12 @@
 const GenericError = require("../errors/GenericError");
 const registry = require("../registry");
+const {
+  dataScope,
+  scopeFilter,
+  mergeScopedFilter,
+  scopeMutation,
+  scopedIdFilter,
+} = require("../tenancy");
 
 const COMMON_REFERENCE_LABEL_FIELDS = [
   "nome",
@@ -15,7 +22,7 @@ const COMMON_REFERENCE_LABEL_FIELDS = [
   "sigla",
 ];
 
-function referencePopulateSpecs(entry) {
+function referencePopulateSpecs(entry, accessContext) {
   const setting = entry.definition?.crud?.populateRefs;
   if (!setting) return [];
 
@@ -35,10 +42,15 @@ function referencePopulateSpecs(entry) {
         ...COMMON_REFERENCE_LABEL_FIELDS,
         ...(referencedEntry?.searchableFields || []),
       ];
+      let match;
+      if (referencedEntry && dataScope(referencedEntry) !== "legacy") {
+        match = scopeFilter(referencedEntry, accessContext);
+      }
 
       return {
         path: field.name,
         select: [...new Set(select)].join(" "),
+        ...(match && Object.keys(match).length ? { match } : {}),
       };
     });
 }
@@ -62,21 +74,47 @@ function withSession(query, session) {
   return session && query && typeof query.session === "function" ? query.session(session) : query;
 }
 
+function scopeDenied() {
+  return new GenericError("Registro fora do contexto de acesso atual.", {
+    statusCode: 403,
+    code: "TENANT_SCOPE_DENIED",
+  });
+}
+
+function notFound() {
+  return new GenericError("Registro não encontrado.", { statusCode: 404 });
+}
+
 function createCrudService(entry) {
   const { mongooseModel: Model, searchableFields } = entry;
-  const populateSpecs = referencePopulateSpecs(entry);
 
-  async function listPaginated({ pageIndex = 0, pageSize = 20, searchTerm, sort, filtros = {} } = {}) {
+  async function assertScopedMiss(id, accessContext, session) {
+    const scope = dataScope(entry);
+    if (scope === "legacy" || scope === "system") throw notFound();
+    const exists = await withSession(Model.exists({ _id: id }), session);
+    if (exists) throw scopeDenied();
+    throw notFound();
+  }
+
+  async function listPaginated({
+    pageIndex = 0,
+    pageSize = 20,
+    searchTerm,
+    sort,
+    filtros = {},
+    accessContext,
+  } = {}) {
     const page = Math.max(0, Number(pageIndex) || 0);
     const limit = Math.min(200, Math.max(1, Number(pageSize) || 20));
 
-    const query = { ...cleanFilters(filtros) };
+    const query = mergeScopedFilter(entry, cleanFilters(filtros), accessContext);
     if (searchTerm && searchableFields.length) {
       const rx = new RegExp(escapeRegex(searchTerm), "i");
       query.$or = searchableFields.map((f) => ({ [f]: rx }));
     }
 
     const sortSpec = parseSort(sort);
+    const populateSpecs = referencePopulateSpecs(entry, accessContext);
     const listQuery = populateQuery(
       Model.find(query).sort(sortSpec).skip(page * limit).limit(limit),
       populateSpecs
@@ -98,32 +136,48 @@ function createCrudService(entry) {
   }
 
   async function getById(id, options = {}) {
-    const query = withSession(Model.findById(id), options.session);
+    const populateSpecs = referencePopulateSpecs(entry, options.accessContext);
+    const query = withSession(
+      Model.findOne(scopedIdFilter(entry, id, options.accessContext)),
+      options.session,
+    );
     const doc = await resolvePopulated(query, populateSpecs);
-    if (!doc) throw new GenericError("Registro não encontrado.", { statusCode: 404 });
+    if (!doc) await assertScopedMiss(id, options.accessContext, options.session);
     return doc;
   }
 
   async function create(data, options = {}) {
-    const doc = new Model(data);
+    const scopedData = scopeMutation(entry, data, options.accessContext);
+    const doc = new Model(scopedData);
     await doc.save({ session: options.session || undefined });
-    return resolvePopulated(doc, populateSpecs);
+    return resolvePopulated(doc, referencePopulateSpecs(entry, options.accessContext));
   }
 
   async function update(id, data, options = {}) {
-    const query = Model.findByIdAndUpdate(id, data, {
-      new: true,
-      runValidators: true,
-      session: options.session || undefined,
-    });
-    const doc = await resolvePopulated(query, populateSpecs);
-    if (!doc) throw new GenericError("Registro não encontrado.", { statusCode: 404 });
+    const scopedData = scopeMutation(entry, data, options.accessContext);
+    const query = Model.findOneAndUpdate(
+      scopedIdFilter(entry, id, options.accessContext),
+      scopedData,
+      {
+        new: true,
+        runValidators: true,
+        session: options.session || undefined,
+      },
+    );
+    const doc = await resolvePopulated(
+      query,
+      referencePopulateSpecs(entry, options.accessContext),
+    );
+    if (!doc) await assertScopedMiss(id, options.accessContext, options.session);
     return doc;
   }
 
   async function remove(id, options = {}) {
-    const doc = await withSession(Model.findByIdAndDelete(id), options.session);
-    if (!doc) throw new GenericError("Registro não encontrado.", { statusCode: 404 });
+    const doc = await withSession(
+      Model.findOneAndDelete(scopedIdFilter(entry, id, options.accessContext)),
+      options.session,
+    );
+    if (!doc) await assertScopedMiss(id, options.accessContext, options.session);
     return doc;
   }
 
@@ -131,18 +185,38 @@ function createCrudService(entry) {
     if (!Array.isArray(rows)) {
       throw new GenericError("Esperado um array de registros.", { statusCode: 400 });
     }
-    const docs = await Model.insertMany(rows, {
+    const scopedRows = rows.map((row) => scopeMutation(entry, row, options.accessContext));
+    const docs = await Model.insertMany(scopedRows, {
       ordered: false,
       session: options.session || undefined,
     });
     return { inserted: docs.length };
   }
 
-  async function exportAll(filtros = {}) {
-    return Model.find(cleanFilters(filtros)).lean();
+  async function exportAll(filtros = {}, options = {}) {
+    const query = mergeScopedFilter(entry, cleanFilters(filtros), options.accessContext);
+    return Model.find(query).lean();
+  }
+
+  function scopeQuery(filter = {}, accessContext) {
+    return mergeScopedFilter(entry, filter, accessContext);
+  }
+
+  function scopedData(data = {}, accessContext) {
+    return scopeMutation(entry, data, accessContext);
   }
 
-  return { listPaginated, getById, create, update, remove, importMany, exportAll };
+  return {
+    listPaginated,
+    getById,
+    create,
+    update,
+    remove,
+    importMany,
+    exportAll,
+    scopeQuery,
+    scopedData,
+  };
 }
 
 function cleanFilters(filtros) {
@@ -163,4 +237,9 @@ function escapeRegex(str) {
   return String(str).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
-module.exports = { createCrudService, referencePopulateSpecs, resolvePopulated };
+module.exports = {
+  createCrudService,
+  referencePopulateSpecs,
+  resolvePopulated,
+  cleanFilters,
+};

package/src/core/middlewares/auth.js

@@ -8,10 +8,16 @@ const {
   getTimeout,
 } = require("../utils/activationProvider");
 const { resolveUserAccess } = require("../rbac/storage");
+const {
+  TENANT_HEADER,
+  readRequestedTenantId,
+  createAccessContext,
+} = require("../tenancy");
 
 async function defaultVerifyToken(token, { req } = {}) {
   const baseUrl = getBaseUrl(req);
   const appCode = getAppCode();
+  const requestedTenantId = readRequestedTenantId(req);
 
   let response;
   try {
@@ -21,6 +27,7 @@ async function defaultVerifyToken(token, { req } = {}) {
       headers: {
         Authorization: `Bearer ${token}`,
         "x-app-code": appCode,
+        ...(requestedTenantId ? { [TENANT_HEADER]: requestedTenantId } : {}),
       },
     });
   } catch (error) {
@@ -28,6 +35,7 @@ async function defaultVerifyToken(token, { req } = {}) {
       error.response?.data?.message || error.message || "Token inválido ou erro na autenticação.",
     );
     err.statusCode = error.response?.status || error.statusCode || 401;
+    err.code = error.response?.data?.code || error.code;
     throw err;
   }
 
@@ -41,6 +49,12 @@ async function defaultVerifyToken(token, { req } = {}) {
   const tipoAcesso = data.aplicativo?.tipoAcesso || data.tipoAcesso || data.tipo || data.perfil;
   return {
     ...data,
+    acesso: response.data.acesso || data.acesso,
+    tenant: response.data.tenant || data.tenant,
+    tenancyModel:
+      response.data.acesso?.app?.tenancyModel ||
+      data.aplicativo?.tenancyModel ||
+      data.tenancyModel,
     tipo: tipoAcesso === "master" ? "admin" : tipoAcesso,
     perfil: data.perfil || tipoAcesso,
     nome: data.nome,
@@ -48,18 +62,25 @@ async function defaultVerifyToken(token, { req } = {}) {
   };
 }
 
-function localDevelopmentVerifyToken(token) {
+function localDevelopmentVerifyToken(token, { req } = {}) {
   const expected = String(process.env.DEV_TOKEN || "");
   if (process.env.NODE_ENV !== "development" || !expected || token !== expected) {
     const error = new Error("Token local de desenvolvimento inválido.");
     error.statusCode = 401;
     throw error;
   }
+  const requestedTenantId = readRequestedTenantId(req);
   return {
+    id: process.env.DEV_USER_ID || "dev-local",
+    usuarioId: process.env.DEV_USER_ID || "dev-local",
     tipo: process.env.DEV_USER_ROLE || "admin",
     perfil: process.env.DEV_USER_ROLE || "admin",
+    roleCode: process.env.DEV_USER_ROLE || "admin",
     nome: process.env.DEV_USER_NAME || "Dev Local",
     email: process.env.DEV_USER_EMAIL || "dev@local",
+    tenantId: requestedTenantId || process.env.DEV_TENANT_ID,
+    appCode: process.env.APP_CODE,
+    tenancyModel: process.env.DEV_TENANCY_MODEL || ctx.config.tenancyModel || "single_tenant",
     capabilities: ctx.config.capabilities || [],
   };
 }
@@ -101,14 +122,28 @@ const authMiddleware = async (req, res, next) => {
   }
 
   try {
-    const providerUser = await resolveVerifyToken()(token, { req });
+    const requestedTenantId = readRequestedTenantId(req);
+    const providerUser = await resolveVerifyToken()(token, { req, requestedTenantId });
     if (!providerUser) {
       const error = new Error("Usuário não resolvido.");
       error.statusCode = 401;
       throw error;
     }
     const usuario = await applyEffectiveAccess(providerUser);
-    req.usuario = usuario;
+    const accessContext = createAccessContext(usuario, {
+      requestedTenantId,
+      tenancyModel: ctx.config.tenancyModel || ctx.config.app?.tenancyModel,
+      appCode: getAppCode(),
+    });
+
+    req.usuario = {
+      ...usuario,
+      tenantId: accessContext.tenantId,
+      appCode: accessContext.appCode || usuario.appCode,
+    };
+    // Contexto imutável e validado. Controllers e rotas customizadas devem
+    // consumir req.accessContext em vez de tenantId vindo de query/body.
+    req.accessContext = accessContext;
 
     if (usuario.mustChangePassword && !isFirstAccessRoute(req)) {
       return Helpers.sendErrorResponse({

package/src/core/tenancy.js

@@ -0,0 +1,200 @@
+const GenericError = require("./errors/GenericError");
+
+const TENANT_HEADER = "x-oon-tenant-id";
+const TENANCY_MODELS = Object.freeze(["none", "single_tenant", "multi_tenant"]);
+const DATA_SCOPES = Object.freeze(["legacy", "system", "tenant", "user"]);
+
+function stringId(value) {
+  if (value === undefined || value === null || value === "") return undefined;
+  if (typeof value === "object") {
+    if (value.id !== undefined) return stringId(value.id);
+    if (value._id !== undefined) return stringId(value._id);
+  }
+  return String(value);
+}
+
+function forbidden(code, message) {
+  return new GenericError(message, { statusCode: 403, code });
+}
+
+function readRequestedTenantId(req) {
+  return stringId(req?.headers?.[TENANT_HEADER]);
+}
+
+function inferVerifiedTenantId(usuario) {
+  return stringId(
+    usuario?.tenantId ||
+      usuario?.tenant?.id ||
+      usuario?.tenant?._id ||
+      usuario?.acesso?.tenant?.id ||
+      usuario?.acesso?.tenant?._id ||
+      usuario?.licenca?.tenantId ||
+      usuario?.aplicativo?.tenantId,
+  );
+}
+
+function inferTenancyModel(usuario, fallback = "single_tenant") {
+  const value =
+    usuario?.tenancyModel ||
+    usuario?.app?.tenancyModel ||
+    usuario?.aplicativo?.tenancyModel ||
+    usuario?.acesso?.app?.tenancyModel ||
+    fallback;
+  return TENANCY_MODELS.includes(value) ? value : fallback;
+}
+
+function inferPermissions(usuario) {
+  const raw = usuario?.permissions || usuario?.permissoes || [];
+  if (Array.isArray(raw)) return [...new Set(raw.map(String))];
+  return [];
+}
+
+function createAccessContext(usuario, options = {}) {
+  const requestedTenantId = stringId(options.requestedTenantId);
+  const verifiedTenantId = inferVerifiedTenantId(usuario);
+  const tenancyModel = inferTenancyModel(usuario, options.tenancyModel || "single_tenant");
+
+  // O header seleciona um tenant, mas nunca é autoridade. A autoridade é o
+  // tenant devolvido pelo provedor de identidade/Control Plane após validar o
+  // vínculo do usuário com o app e o tenant solicitado.
+  if (requestedTenantId && verifiedTenantId && requestedTenantId !== verifiedTenantId) {
+    throw forbidden(
+      "TENANT_CONTEXT_MISMATCH",
+      "O tenant solicitado não corresponde ao contexto autorizado.",
+    );
+  }
+
+  if (tenancyModel === "multi_tenant" && !verifiedTenantId) {
+    throw forbidden(
+      "TENANT_CONTEXT_REQUIRED",
+      "Selecione um tenant autorizado para acessar este aplicativo.",
+    );
+  }
+
+  if (tenancyModel === "none" && requestedTenantId) {
+    throw forbidden(
+      "TENANT_CONTEXT_NOT_ALLOWED",
+      "Este aplicativo não aceita contexto de tenant.",
+    );
+  }
+
+  const roleCode = String(
+    usuario?.roleCode || usuario?.perfil || usuario?.tipo || "",
+  ).trim() || undefined;
+
+  return Object.freeze({
+    userId: stringId(usuario?.usuarioId || usuario?.id || usuario?._id || usuario?.sub),
+    tenantId: tenancyModel === "none" ? undefined : verifiedTenantId,
+    appCode: String(
+      usuario?.appCode ||
+        usuario?.app?.codigo ||
+        usuario?.aplicativo?.codigo ||
+        usuario?.acesso?.app?.codigo ||
+        options.appCode ||
+        "",
+    ).trim().toLowerCase() || undefined,
+    roleCode,
+    permissions: Object.freeze(inferPermissions(usuario)),
+    tenancyModel,
+  });
+}
+
+function dataScope(entryOrDefinition) {
+  const definition = entryOrDefinition?.definition || entryOrDefinition || {};
+  const value = definition.scope || definition.tenancy?.scope || "legacy";
+  return DATA_SCOPES.includes(value) ? value : "legacy";
+}
+
+function tenantField(entryOrDefinition) {
+  const definition = entryOrDefinition?.definition || entryOrDefinition || {};
+  return definition.tenancy?.tenantField || "tenantId";
+}
+
+function userField(entryOrDefinition) {
+  const definition = entryOrDefinition?.definition || entryOrDefinition || {};
+  return definition.tenancy?.userField || "usuarioId";
+}
+
+function requireContextValue(value, code, message) {
+  if (!value) throw forbidden(code, message);
+  return value;
+}
+
+function scopeFilter(entryOrDefinition, accessContext) {
+  const scope = dataScope(entryOrDefinition);
+  if (scope === "legacy" || scope === "system") return {};
+
+  const tenantId = requireContextValue(
+    accessContext?.tenantId,
+    "TENANT_CONTEXT_REQUIRED",
+    "Contexto de tenant obrigatório para este recurso.",
+  );
+  const filter = { [tenantField(entryOrDefinition)]: tenantId };
+
+  if (scope === "user") {
+    filter[userField(entryOrDefinition)] = requireContextValue(
+      accessContext?.userId,
+      "USER_CONTEXT_REQUIRED",
+      "Contexto de usuário obrigatório para este recurso.",
+    );
+  }
+
+  return filter;
+}
+
+function mergeScopedFilter(entryOrDefinition, filter = {}, accessContext) {
+  const clean = { ...(filter || {}) };
+  const enforced = scopeFilter(entryOrDefinition, accessContext);
+
+  // Remove tentativas de substituir escopo via query/body. O valor confiável
+  // sempre vence e é derivado de req.accessContext.
+  for (const [key, value] of Object.entries(enforced)) {
+    clean[key] = value;
+  }
+  return clean;
+}
+
+function scopeMutation(entryOrDefinition, data = {}, accessContext) {
+  const result = data && typeof data === "object" && !Array.isArray(data)
+    ? { ...data }
+    : data;
+  if (!result || typeof result !== "object" || Array.isArray(result)) return result;
+
+  const scope = dataScope(entryOrDefinition);
+  if (scope === "legacy" || scope === "system") return result;
+
+  const enforced = scopeFilter(entryOrDefinition, accessContext);
+  Object.assign(result, enforced);
+  return result;
+}
+
+function scopedIdFilter(entryOrDefinition, id, accessContext) {
+  return mergeScopedFilter(entryOrDefinition, { _id: id }, accessContext);
+}
+
+function assertScopedEntry(entryOrDefinition) {
+  const scope = dataScope(entryOrDefinition);
+  if (scope === "legacy") return;
+  if (!DATA_SCOPES.includes(scope)) {
+    throw new Error(`Escopo de dados inválido: ${scope}`);
+  }
+}
+
+module.exports = {
+  TENANT_HEADER,
+  TENANCY_MODELS,
+  DATA_SCOPES,
+  stringId,
+  readRequestedTenantId,
+  inferVerifiedTenantId,
+  inferTenancyModel,
+  createAccessContext,
+  dataScope,
+  tenantField,
+  userField,
+  scopeFilter,
+  mergeScopedFilter,
+  scopeMutation,
+  scopedIdFilter,
+  assertScopedEntry,
+};

package/src/index.js

@@ -6,6 +6,7 @@ const { activate } = require("./boot/activation");
 const define = require("./core/define");
 const fields = require("./core/fields");
 const registry = require("./core/registry");
+const tenancy = require("./core/tenancy");
 const GenericError = require("./core/errors/GenericError");
 const { requirePermission } = require("./core/middlewares/permissions");
 const rbacPolicy = require("./core/rbac/policy");
@@ -38,6 +39,16 @@ module.exports = {
   roleByCode: rbacPolicy.roleByCode,
   permissionGranted: rbacPolicy.granted,
 
+  TENANT_HEADER: tenancy.TENANT_HEADER,
+  TENANCY_MODELS: tenancy.TENANCY_MODELS,
+  DATA_SCOPES: tenancy.DATA_SCOPES,
+  createAccessContext: tenancy.createAccessContext,
+  readRequestedTenantId: tenancy.readRequestedTenantId,
+  scopeFilter: tenancy.scopeFilter,
+  mergeScopedFilter: tenancy.mergeScopedFilter,
+  scopeMutation: tenancy.scopeMutation,
+  scopedIdFilter: tenancy.scopedIdFilter,
+
   APP_MANIFEST_FILENAME: appManifest.APP_MANIFEST_FILENAME,
   APP_MANIFEST_SCHEMA_VERSION: appManifest.APP_MANIFEST_SCHEMA_VERSION,
   SUPPORTED_APP_KINDS: appManifest.SUPPORTED_APP_KINDS,