Central de Ativações

Central Oon responsável pelo cadastro de usuários, tenants, apps e licenças, além do controle das ativações e publicações dos aplicativos.

A solução foi gerada com create-central-oon e contém dois projetos declarativos que consomem o OonCore:

• backend/ — domínio em src/models; boot, banco, autenticação, RBAC, metadata, CRUD e deploy são fornecidos por @oondemand/oon-core-back.
• frontend/ — declaração em central.ui.json; shell, providers, roteamento, autenticação, coleções e esteiras são fornecidos por @oondemand/oon-core-front.

Autenticação local

A própria Central de Ativações possui uma tela em /login.

• POST /auth/autenticar — autentica o operador da Central de Ativações.
• GET /auth/validar-token — valida a sessão local pelo middleware do OonCore.

Essas rotas são internas à Central de Ativações e não devem ser utilizadas pelos backends das demais Centrais.

Integração de autenticação dos aplicativos

Os aplicativos consumidores utilizam um namespace exclusivo, evitando colisão e recursão com as rotas /auth do próprio OonCore:

• POST /integracao/autenticacao-aplicativos/autenticar
• GET /integracao/autenticacao-aplicativos/verificar-permissao

A autenticação recebe as credenciais no header Basic e exige o código do aplicativo em x-app-code. O usuário somente recebe o token quando também possui acesso ativo ao aplicativo.

A verificação de permissão recebe:

• Authorization: Bearer <token>;
• x-app-code: <codigo-do-app>.

A autorização somente é concedida quando:

• o usuário permanece ativo;
• o app está ativo;
• a permissão do usuário para o app está ativa;
• a licença está ativa;
• os vínculos do app e do usuário com a licença estão ativos.

A resposta inclui o perfil no app, as permissões funcionais e os dados mínimos do aplicativo e da licença. O objeto usuario.aplicativo.tipoAcesso permanece disponível para compatibilidade.

O token possui validade configurável, é armazenado pelo frontend na chave isolada da Central e acompanha as chamadas privadas no header Authorization: Bearer.

Variáveis obrigatórias/recomendadas:

• AUTH_TOKEN_SECRET — chave longa e exclusiva de assinatura;
• AUTH_TOKEN_TTL_SECONDS — duração do token, com padrão de 8 horas;
• VITE_API_URL — endereço do backend utilizado pela tela de login.

Modelo de licenciamento

O domínio de licenciamento segue uma estrutura relacional:

1. cada Licença pertence a um Tenant;
2. os Apps por licença definem quais aplicações estão disponíveis naquela licença;
3. os Usuários por licença definem quais usuários participam daquela licença;
4. as Permissões por app definem o perfil e as ações de cada usuário em cada app licenciado.

Aplicativos

Cada app possui um campo codigo obrigatório, único e normalizado em minúsculas. Esse código identifica o aplicativo nas verificações de permissão realizadas pelos backends consumidores.

Permissões por app

Cada permissão relaciona uma licença, um usuário e um app, com:

• perfil no app: administrador, gestor, operador, desenvolvedor ou leitura;
• autorização para ativar;
• autorização para publicar;
• autorização para gerenciar usuários;
• status da permissão: ativa, suspensa ou revogada.

Segurança dos usuários

O cadastro de usuários exige senha para novos registros. A senha:

• possui no mínimo 8 caracteres;
• é transformada em hash scrypt com salt aleatório antes da persistência;
• não é pesquisável nem retornada nas consultas da coleção;
• é apresentada como campo protegido no formulário;
• não é exibida no datagrid.

Usuários antigos que ainda possuam credencial legada são atualizados para o hash seguro após a primeira autenticação válida.

Coleções

• Usuários — pessoas autorizadas a administrar ou operar a Central.
• Tenants — organizações/clientes isolados dentro do ecossistema.
• Apps — catálogo de aplicações disponíveis para licenciamento e publicação.
• Licenças — contrato comercial e operacional pertencente a um tenant.
• Apps por licença — apps disponibilizados em cada licença.
• Usuários por licença — usuários vinculados a cada licença.
• Permissões por app — RBAC do usuário dentro de cada app licenciado.
• Publicações — histórico auditável de cada publicação por ambiente.

Esteiras

Ativação

nova → validacao_cadastral → validacao_licenca → configuracao → provisionamento → ativada

Saídas excepcionais: suspensa e cancelada.

Publicação

nova → preparacao → validacao → publicando → publicada

Saídas excepcionais: falha e cancelada.

Rodando localmente

# backend
cd backend
cp .env.example .env
npm install
npm run dev

# frontend, em outro terminal
cd frontend
cp .env.example .env
npm install
npm run dev

Depois, acesse http://localhost:5173/login e entre com um usuário de status ativo.

Próximas integrações

A base declarativa deixa preparados os pontos de evolução para:

• aplicar as permissões por app no RBAC das APIs e telas;
• recuperação e redefinição segura de senha;
• autorização GitHub do usuário;
• criação/fork de repositório na organização OonDemand;
• geração de manifestos e arquivos de deploy;
• publicação dos ambientes de desenvolvimento, homologação e produção;
• provisionamento de URLs, banco de dados e secrets;
• bloqueio automático conforme vigência e limites da licença.

Central root do Ecossistema Oon

Esta aplicação é explicitamente a raiz de confiança do Ecossistema Oon (ecosystem.role = "root"). Somente a Central de Ativações deve usar esse papel: as demais Centrais são membros, não mantêm senhas locais de operadores para integração e devem se ativar por códigos emitidos aqui. Por isso, esta aplicação não exibe fluxo /ativacao, não depende de CENTRAL_ATIVACAO_URL e mantém login local apenas para seus próprios operadores.

A separação de autenticação é obrigatória:

• /auth/autenticar e /auth/validar-token são rotas locais exclusivas da Central de Ativações.
• Aplicações externas usam somente namespaces /integracao/*.
• x-app-code sozinho nunca identifica uma Central membro; integrações exigem credencial de instância.

Ativação de instâncias de aplicativos

A Central gerencia dois novos modelos declarativos:

• Códigos de Ativação (CodigoAtivacao) — guarda apenas codigoHash, codigoPrefixo, tenant, licença, app, ambiente, validade, uso, revogação e metadados. O código completo é retornado somente na criação administrativa.
• Instâncias de Aplicativos (InstanciaAplicativo) — guarda app, licença, tenant, ambiente, URL, status, versões, fingerprint, credentialHash, credentialPrefix, credentialVersion, timestamps operacionais e metadados. A credencial completa é retornada somente na ativação.
• Auditoria do Ecossistema (AuditoriaEcossistema) — registra eventos como criação/validação/consumo de código, criação/conclusão/suspensão/revogação de instância, heartbeat e autenticações negadas.

Estados

CodigoAtivacao transita de novo para utilizado, expirado ou revogado. Estados finais não devem ser reativados.

InstanciaAplicativo usa configurando, ativa, suspensa, revogada e erro. Instâncias revogadas não voltam para ativa; suspensão preserva a credencial, revogação invalida a credencial atual.

Limites por ambiente

Licenças e vínculos LicencaApp aceitam limites declarativos no formato:

{
  "instancias": {
    "desenvolvimento": 3,
    "homologacao": 1,
    "producao": 1
  }
}

A ativação valida licença ativa e vigente, app ativo, vínculo LicencaApp ativo, tenant ativo, ambiente permitido e quantidade máxima por ambiente. Instâncias revogadas não contam para o limite, permitindo substituição controlada.

Rotas de ativação

Namespace exclusivo: /integracao/ativacao-instancias.

Validar código sem consumo

POST /integracao/ativacao-instancias/validar-codigo
Content-Type: application/json

{
  "codigoAtivacao": "OON-XXXX-XXXX-XXXX",
  "appCode": "central-minexco",
  "ambiente": "producao",
  "urlPublica": "https://minexco.exemplo.com",
  "coreVersion": "x.y.z",
  "appVersion": "x.y.z"
}

A resposta indica valido: true e retorna somente dados mínimos de ativação, tenant, app e licença. Não retorna credenciais, hashes, usuários ou dados de outros apps/licenças.

Ativar instância

POST /integracao/ativacao-instancias/ativar
Idempotency-Key: deploy-123
Content-Type: application/json

{
  "codigoAtivacao": "OON-XXXX-XXXX-XXXX",
  "appCode": "central-minexco",
  "nomeInstancia": "Central Minexco - Produção",
  "ambiente": "producao",
  "urlPublica": "https://minexco.exemplo.com",
  "coreVersion": "x.y.z",
  "appVersion": "x.y.z",
  "fingerprint": "fingerprint-local",
  "metadata": {}
}

A rota repete as validações, consome o código com operação condicional atômica, cria a instância como configurando, gera token aleatório de alta entropia, persiste apenas o hash e retorna o token apenas nesta resposta. Repetições com a mesma chave de idempotência retornam a instância já criada sem reenviar a credencial.

Concluir configuração

POST /integracao/ativacao-instancias/concluir
x-oon-instance-id: <id>
x-oon-instance-token: <token>
x-app-code: central-minexco
Content-Type: application/json

{
  "configurationVersion": 1,
  "parametros": {
    "idioma": "pt-BR",
    "timezone": "America/Sao_Paulo",
    "moeda": "BRL",
    "pais": "BR",
    "formatoData": "DD/MM/YYYY"
  }
}

A conclusão é idempotente, sanitiza parâmetros, descarta chaves com nomes sensíveis e marca a instância como ativa.

Contexto e heartbeat

GET /integracao/ativacao-instancias/contexto
x-oon-instance-id: <id>
x-oon-instance-token: <token>
x-app-code: central-minexco

POST /integracao/ativacao-instancias/heartbeat
x-oon-instance-id: <id>
x-oon-instance-token: <token>
x-app-code: central-minexco

O contexto atualiza ultimaValidacaoEm e ultimoAcessoEm. O heartbeat atualiza ultimoHeartbeatEm, versões e URL pública permitida, sem reativar automaticamente instâncias suspensas ou revogadas.

Autenticação de usuários por aplicativo

As rotas de integração de autenticação exigem simultaneamente credenciais humanas e identidade da instância:

POST /integracao/autenticacao-aplicativos/autenticar
Authorization: Basic <email:senha>
x-oon-instance-id: <id>
x-oon-instance-token: <token>
x-app-code: central-minexco

A validação ocorre nesta ordem: instância, licença/app/tenant, credenciais humanas, vínculo LicencaUsuario, permissão PermissaoUsuarioApp e emissão do token humano. O token inclui usuarioId, tenantId, licencaId, appId, appCode, instanceId, perfil, iat, exp e jti.

GET /integracao/autenticacao-aplicativos/verificar-permissao
Authorization: Bearer <token-humano>
x-oon-instance-id: <id>
x-oon-instance-token: <token>
x-app-code: central-minexco

A verificação rejeita token humano emitido para outra instância ou outro app.

Erros padronizados

As integrações usam códigos operacionais como ACTIVATION_CODE_REQUIRED, ACTIVATION_CODE_INVALID, ACTIVATION_CODE_EXPIRED, ACTIVATION_CODE_REVOKED, ACTIVATION_CODE_ALREADY_USED, APP_NOT_FOUND, APP_INACTIVE, APP_CODE_MISMATCH, LICENSE_NOT_FOUND, LICENSE_INACTIVE, LICENSE_EXPIRED, LICENSE_APP_INACTIVE, INSTANCE_LIMIT_REACHED, INSTANCE_CREDENTIAL_INVALID, INSTANCE_CONFIGURING, INSTANCE_SUSPENDED, INSTANCE_REVOKED, TENANT_INACTIVE, USER_CREDENTIALS_INVALID, USER_INACTIVE, USER_NOT_LICENSED e USER_APP_PERMISSION_DENIED.

Segurança e auditoria

• Códigos completos e tokens de instância nunca são persistidos nem retornados em consultas posteriores.
• Hashes usam SHA-256 para comparação segura de segredos aleatórios de alta entropia; senhas humanas continuam usando scrypt.
• Headers de instância são obrigatórios nas rotas de integração de autenticação.
• URLs públicas são normalizadas e limitadas a http/https.
• metadata é limitado e sanitizado para evitar mass assignment.
• Eventos de ativação e operação são registrados em AuditoriaEcossistema com requestId, IP, user-agent e metadados sanitizados.

Migração e ordem de implantação

1. Publicar a Central de Ativações com os novos modelos e rotas.
2. Garantir que apps existentes tenham codigo único preenchido.
3. Configurar limites nas licenças ou vínculos LicencaApp.
4. Gerar o primeiro código de ativação para cada Central membro.
5. Publicar a versão correspondente do OonCore com tela/fluxo de ativação de membro.
6. Ativar cada Central membro usando /integracao/ativacao-instancias/ativar e concluir em seguida.
7. Somente depois tornar os headers de instância obrigatórios nos consumidores em produção, preservando uma janela de transição planejada.

Não há criação automática de instâncias nem credenciais implícitas para apps existentes; usuários, licenças e permissões são preservados.