# @oondemand/oon-core-back > Core runtime para Centrais Oon: Model Registry, CRUD/RBAC automáticos, módulos opinativos e capabilities nativas. Latest version **0.7.2** (published 2026-09-24) · SEE LICENSE IN LICENSE license · 0 weekly downloads ## Install ```sh npm install @oondemand/oon-core-back pnpm add @oondemand/oon-core-back yarn add @oondemand/oon-core-back bun add @oondemand/oon-core-back ``` Provides the command `oonCore-back`. ## Health **Score 60/100 (C)** — status: active. Positive: esm support; no vulnerabilities; recently updated; high maintenance score. Warnings: low downloads; no types; pre 1.0. ## Facts | | | |---|---| | Version | 0.7.2 | | Published | 2026-09-24 | | First published | 2026-06-11 | | Weekly downloads | 0 | | License | SEE LICENSE IN LICENSE | | TypeScript types | none | | Module format | ESM + CommonJS | | Node | >=18 | | Dependencies | 9 | | Unpacked size | 428.9 KB | | Known vulnerabilities | 0 | | Install scripts | no | | Maintainers | robertolima-dev, fanaia | | Keywords | oondemand, ooncore, central, model-registry, express, mongoose, capabilities | ## Links - npm: https://www.npmjs.com/package/@oondemand/oon-core-back - Repository: https://github.com/oondemand/oon-platform - Homepage: https://github.com/oondemand/oon-platform#readme - Issues: https://github.com/oondemand/oon-platform/issues - npm.io page: https://npm.io/package/@oondemand/oon-core-back ## Dependencies (9) - [ajv](https://npm.io/package/ajv.md) ^8.17.1 - [cors](https://npm.io/package/cors.md) ^2.8.5 - [axios](https://npm.io/package/axios.md) ^1.7.7 - [dotenv](https://npm.io/package/dotenv.md) ^16.4.5 - [helmet](https://npm.io/package/helmet.md) ^8.0.0 - [morgan](https://npm.io/package/morgan.md) ^1.10.0 - [express](https://npm.io/package/express.md) ^4.21.2 - [mongoose](https://npm.io/package/mongoose.md) ^8.5.4 - [handlebars](https://npm.io/package/handlebars.md) ^4.7.8 ## Alternatives - [angular-pipes](https://npm.io/package/angular-pipes.md) — 5.6K weekly downloads - [@ng-web-apis/midi](https://npm.io/package/@ng-web-apis/midi.md) — 2.6K weekly downloads - [happn-3](https://npm.io/package/happn-3.md) — 1.6K weekly downloads - [@opensip-cli/lang-go](https://npm.io/package/@opensip-cli/lang-go.md) — 1.2K weekly downloads - [mongoose-typescript](https://npm.io/package/mongoose-typescript.md) — 85 weekly downloads ## Recent versions - 0.7.2 (latest) — 2026-09-24 - 0.7.1 — 2026-09-23 - 0.7.0 — 2026-09-22 - 0.6.13 — 2026-09-16 - 0.6.12 — 2026-09-15 - 0.6.11 — 2026-09-12 - 0.6.10 — 2026-09-10 - 0.6.9 — 2026-09-10 - 0.6.8 — 2026-09-10 - 0.6.7 — 2026-09-07 - 0.6.6 — 2026-09-03 - 0.6.5 — 2026-09-03 - 0.6.4 — 2026-09-02 - 0.6.3 — 2026-09-02 - 0.6.2 — 2026-09-02 - … 119 more at https://npm.io/package/@oondemand/oon-core-back/versions ## README # 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 - `CENTRAL_ATIVACAO_URL`: URL pública/frontend da Central de Ativações. - `CENTRAL_ATIVACAO_API_URL`: URL canônica do backend da Central de Ativações. Padrão: `https://central-ativacao.central.oondemand.online/api/`. - `APP_CODE`: código do aplicativo no Ecossistema. - `APP_ENVIRONMENT`: `desenvolvimento`, `homologacao` ou `producao`. - `PUBLIC_APP_URL`: URL pública confirmada da Central. - `INSTANCE_CREDENTIAL_ENCRYPTION_KEY`: chave para AES-256-GCM; obrigatória em produção. - `AUTH_PROVIDER_TIMEOUT_MS`: timeout das chamadas à Central de Ativações. - `INSTANCE_HEARTBEAT_INTERVAL_MS`: intervalo planejado para sincronização/heartbeat. Compatibilidade temporária: `CENTRAL_ATIVACAO_BACKEND_URL` e `MEUS_APPS_BACKEND_URL` continuam aceitas como aliases da URL da API. Nunca aponte a URL da API para o próprio Core. ## Catálogo público de perfis Todo App com RBAC declarado expõe `GET /core/role-catalog`. O contrato `schemaVersion: 1` contém `appCode`, `enabled` e `roles[]` com `code`, `name`, `description` e `admin`. Desde o SDK 0.7.1, a extensão aditiva opcional `roles[].commercialPermissions` publica nomes explícitos de permissões funcionais permitidas pelo papel. Wildcards são expandidos somente pelas permissões declaradas em `rbac.permissions`; wildcard literal e namespaces `tenant`, `publications`, `homologation`, `production`, `apps`, `users` e `roles` são excluídos. Políticas internas e permissões técnicas não são publicadas. O campo permanece opcional no schemaVersion 1: catálogos anteriores são conformes para descoberta e fluxos existentes. O novo aceite comercial inicial requer essa capacidade e deve falhar fechado com `APP_ROLE_CATALOG_UNAVAILABLE` quando ausente; não se infere autoridade do nome admin. Consumidores antigos devem tolerar campos adicionais. O runtime continua intersectando cada grant explícito com a política local atual. O endpoint é somente leitura, usa cache público de cinco minutos e não concede autorização. ## Saúde operacional - `GET /health/ready`: retorna HTTP 200 somente quando o MongoDB está conectado; retorna 503 enquanto o runtime não estiver pronto. - `GET /health/version`: expõe as versões do OonCore e da Central, commit, release, build e ambiente da publicação. O campo `deployment.environment` usa exclusivamente `APP_ENVIRONMENT`. A variável `NODE_ENV=production` configura a execução técnica do Node dentro da imagem e não representa o ambiente lógico da publicação. Na imagem de entrega, essas rotas são publicadas pelo Nginx sob `/api/health/ready` e `/api/health/version`. ## Fluxo `GET /ativacao/status` informa estado sem segredos. `POST /ativacao/validar-codigo` valida sem consumir. `POST /ativacao/concluir` revalida, chama `/ativar`, criptografa imediatamente o token da instância, executa hooks declarativos, chama `/concluir` e marca a instância como `ativa`. `POST /ativacao/tentar-novamente` retoma uma ativação já registrada sem exigir novo código. Campos adicionais podem ser declarados em `activation.fields`; `password` e `secret` são sanitizados na configuração retornada ao frontend. Hooks opcionais: `validate`, `beforeComplete`, `afterComplete`. ## Imagem de entrega O comando de delivery preserva `central.app.json` em dois pontos da imagem: - `/src/central.app.json` durante o build do frontend declarativo; - `/app/central.app.json` para descoberta pelo backend em runtime. Centrais legadas sem o manifesto continuam suportadas. O empacotador cria uma pasta intermediária vazia, evitando tornar `central.app.json` obrigatório para aplicações que ainda usam somente `central.config.js`. ## Rótulos de campos relacionados Por padrão, campos declarados com `fields.ref(...)` continuam sendo devolvidos pelo CRUD como `ObjectId`. Uma model pode optar pela população segura das referências usadas em grids e cards: ```js defineModel({ name: "Pedido", schema: { clienteId: fields.ref("Cliente", { required: true, label: "Cliente" }), }, crud: { enabled: true, populateRefs: ["clienteId"], }, }); ``` Use `populateRefs: true` para todas as referências da model ou informe uma lista explícita. O CRUD devolve somente `_id` e campos usuais de identificação, como nome, razão social, descrição, código, e-mail e campos pesquisáveis da model referenciada. Exportações mantêm os identificadores originais. --- _Source: https://npm.io/package/@oondemand/oon-core-back · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._