# 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