orquestrador/docs/architecture/admin-credential-strategy.md

Estrategia De Credenciais Para StaffAccount

Este documento define a estrategia inicial de credenciais para contas administrativas internas (StaffAccount).

Objetivo

Permitir autenticacao web no orquestrador-admin sem misturar a identidade do painel com o User do atendimento.

O que e o StaffAccount

StaffAccount e a conta administrativa interna do sistema.

Ela representa um funcionario ou administrador da empresa e existe apenas no dominio administrativo. Nao deve ser usada para identificar cliente do atendimento.

Responsabilidades principais do StaffAccount:

• autenticar acesso ao painel administrativo
• carregar papel de autorizacao (colaborador, diretor)
• auditar quem executou uma acao interna
• governar drafts, configuracoes, relatorios e publicacao de tools

O que e a StaffSession

StaffSession representa uma sessao administrativa ativa derivada de um login do StaffAccount.

Cada sessao possui:

• session_id
• refresh_token_hash
• data de expiracao
• marcador de revogacao
• metadados simples de IP e user-agent

Isso permite tratar login, refresh e logout sem depender apenas de um access token solto.

Identificador de login

O identificador principal de login sera:

• email

Regras:

• deve ser unico no banco administrativo
• deve ser normalizado em lowercase na camada de servico e repositorio
• nao sera compartilhado com a identidade do atendimento

Segredo primario

O segredo primario inicial sera:

• senha gerenciada internamente

A senha nunca deve ser armazenada em texto puro.

Estrategia de hash

A estrategia inicial definida para password_hash e:

• esquema: pbkdf2_sha256
• iteracoes padrao: 390000
• salt aleatorio por conta
• pepper opcional via ambiente: ADMIN_AUTH_PASSWORD_PEPPER

Formato de persistencia adotado:

• pbkdf2_sha256$<iterations>$<salt>$<digest>

Politica inicial de senha

Politica minima definida:

• tamanho minimo: 12
• exigir letra maiuscula
• exigir letra minuscula
• exigir digito
• exigir simbolo

A validacao dessa politica ja esta refletida no runtime administrativo.

Tokens e sessao

Estrategia inicial para a autenticacao web:

• access token curto: 30 minutos
• refresh token: 7 dias
• secret de assinatura dedicado: ADMIN_AUTH_TOKEN_SECRET
• issuer do admin runtime: ADMIN_AUTH_TOKEN_ISSUER
• tamanho configuravel do refresh token: ADMIN_AUTH_REFRESH_TOKEN_BYTES

Nesta etapa, o runtime administrativo ja faz:

• emissao de access token assinado por HMAC-SHA256
• emissao de refresh token opaco
• armazenamento hash do refresh token em StaffSession
• rotacao do refresh token no endpoint de refresh
• revogacao da sessao no logout

Bootstrap do primeiro diretor

A primeira conta de diretor deve nascer por fluxo controlado, nunca por startup automatico.

Variaveis previstas:

• ADMIN_BOOTSTRAP_ENABLED
• ADMIN_BOOTSTRAP_EMAIL
• ADMIN_BOOTSTRAP_DISPLAY_NAME
• ADMIN_BOOTSTRAP_PASSWORD
• ADMIN_BOOTSTRAP_ROLE

Regras:

• o bootstrap deve ser executado por comando explicito no futuro
• nao deve criar conta automaticamente ao subir o servico
• o papel padrao do bootstrap e diretor

Relacao com papeis e permissoes

A conta StaffAccount continua acoplada a hierarquia compartilhada:

• colaborador
• diretor

A senha autentica a identidade; o role governa autorizacao.

Configuracoes adicionadas ao admin runtime

As configuracoes de credenciais passam a existir em admin_app/core/settings.py:

• admin_auth_password_hash_scheme
• admin_auth_password_hash_iterations
• admin_auth_password_min_length
• admin_auth_password_require_uppercase
• admin_auth_password_require_lowercase
• admin_auth_password_require_digit
• admin_auth_password_require_symbol
• admin_auth_password_pepper
• admin_auth_token_secret
• admin_auth_token_issuer
• admin_auth_access_token_ttl_minutes
• admin_auth_refresh_token_ttl_days
• admin_auth_refresh_token_bytes
• admin_bootstrap_enabled
• admin_bootstrap_email
• admin_bootstrap_display_name
• admin_bootstrap_password
• admin_bootstrap_role

Endpoints iniciais de autenticacao

Nesta etapa, o orquestrador-admin passa a expor:

• POST /auth/login
• POST /auth/refresh
• POST /auth/logout
• GET /auth/me

Proximos passos naturais

• implementar autorizacao por papel nas demais rotas administrativas
• implementar fluxo explicito de bootstrap do primeiro diretor
• implementar gestao de sessoes revogaveis por tela administrativa