@trismegisto/spine 2.1.1 → 3.0.0

package/README.md

@@ -51,12 +51,12 @@ export const appConfig: ApplicationConfig = {
   o tema no `<body>` e usa `clientId` como prefixo de **todas** as chaves salvas (tema, menu lateral, abas):
   apps diferentes na mesma origem não misturam preferências. Opções: `clientId`, `appName` (nome ao lado do
   logo no cabeçalho), `logo`, `showAppName` e `favicon` (ver "Logo e favicon" abaixo), `technicalDocs` (mostra a
-  especificação técnica das telas e o botão "Copiar token de acesso" do painel de configurações; padrão
+  especificação técnica das telas e o botão "Copiar token de acesso" da seção Sessões das configurações; padrão
   `isDevMode()`).
 - **Recentes, buscas recentes e favoritos** ficam no `localStorage` por usuário (`SpineUserStorage`: chave
   `<clientId>_<lista>_<sub>`, com o `sub` do token). No logout (pelo spine ou vindo de outra aba, via `isAuth$`) os
-  históricos são apagados; os favoritos ficam. Logout próprio do app: chame `SpineUserStorage.clearHistory()` antes
-  de `AuthorizationService.logout()`.
+  históricos são apagados; os favoritos ficam. Logout próprio do app: use `SpineLogoutService.logout()` (veja
+  "Sair (logout)" abaixo).
 - **`APP_ROUTES`** traz login, callback, saída e as rotas privadas sob o `spine-layout`
   (`LayoutComponent`). O `/callback` usa o `handleCallback()` do `@orfeu/angular`: confere state/verifier, volta
   para a URL pedida antes do login e, no `login_required` da reautorização silenciosa, segue sozinho para o login
@@ -84,6 +84,35 @@ export const components: ComponentRoute[] = [
 ];
 ```
 
+### Sair (logout)
+
+Todas as saídas do spine (item "Sair" do menu do perfil, botão "Sair" do painel de configurações, atalho
+`Mod+Shift+L` e a ação da tela `/blocked`) passam pelo **`SpineLogoutService`** (`@trismegisto/spine/layout`). O app não
+precisa de código próprio:
+
+- **Falha no Argos** (`@orfeu/angular` 1.3.x: o `logout()` repete uma vez e, falhando de novo, mantém a sessão e emite
+  `logoutFailed$`): o serviço assina `logoutFailed$` uma vez e mostra um aviso de erro (`hm-alert` de erro,
+  `role="alert"`, pelo `NotificationService`) com `SpineMessages.session.logoutFailed` — "Não foi possível sair agora.
+  Verifique a conexão e tente de novo." A pessoa fica na tela, a sessão continua e os botões voltam ao normal para
+  tentar de novo. Vale também para um `AuthorizationService.logout()` chamado direto pelo app.
+- **Sucesso**: só então os históricos (recentes e buscas recentes) são apagados; o `@orfeu/angular` navega para o
+  `/logoff`. Com falha, nada é apagado.
+- `logout()` devolve `Promise<boolean>` (`true` = saiu; nunca rejeita) e `pending` (signal) fica `true` durante a
+  saída: o painel de configurações mostra o botão carregando, o item do menu fica desabilitado e o painel só fecha
+  quando a saída deu certo. Cliques repetidos reaproveitam a mesma tentativa.
+- **`@orfeu/angular` 1.0.x** (sem `logoutFailed$`, `logout()` sem retorno): funciona como antes — a saída conta como
+  concluída e os históricos saem.
+
+Logout num botão do próprio app:
+
+```ts
+const saiu = await inject(SpineLogoutService).logout(); // false: o aviso já apareceu; a pessoa continua aqui
+```
+
+O `spine-layout` também monta os avisos: o `spine-notification` (`NotificationService`) e um `hm-toast-stack`
+(`HermesToastService`, usado nas configurações, inclusive em MFA e Sessões, e no auto-serviço). O app não monta outro; se
+montar, os avisos não aparecem em dobro (só uma pilha desenha).
+
 ## Logo e favicon
 
 O spine não traz marca nenhuma: o logo do cabeçalho e o favicon são arquivos do app.
@@ -117,14 +146,71 @@ provideUi({
 - **Marca em componente:** `{ provide: SPINE_BRAND, useValue: MarcaComponent }` (`@trismegisto/spine/layout`) tem
   prioridade sobre a imagem (ex.: SVG inline com `currentColor`). Ele fica dentro do link — sem link/botão dentro.
 
-## Conta e segurança (painel de configurações)
+## Painel de configurações: seções
+
+Aberto pelo menu do perfil, por `Ctrl+,`, por `SpineSettingsService.open(chave)` ou por link com `?settings=<chave>`
+(chaves em `SPINE_SETTINGS_KEYS`, de `@trismegisto/spine/layout`). As seções do app (`provideSettingsSection`) entram
+antes de "Sobre".
+
+| Seção | Chave (`?settings=`) | Conteúdo | Quando aparece |
+| --- | --- | --- | --- |
+| Conta | `conta` | Perfil, nível de acesso, Sair | Sempre |
+| MFA | `mfa` | Conta no Argos, verificação em duas etapas, códigos de recuperação | Com `authority` e `realmId` do `AUTH_CONFIG` preenchidos |
+| Sessões | `sessoes` | Token de acesso, Tokens de aplicação, Conectar um agente de IA, Sessões e dispositivos | Sempre (cada linha com a própria condição, abaixo) |
+| Notificações | `notificacoes` | Tipos de aviso do app, aviso do navegador | Com `SpineConfig.features.notices` |
+| Aparência | `aparencia` | Tema, cor, densidade, fonte, menu lateral | Sempre |
+| Região | `regiao` | Idioma, fuso horário | Sempre |
+| Atalhos | `atalhos` | Lista de atalhos, tour guiado | Sempre |
+| Sobre | `sobre` | Aplicação, versão, build, ambiente, links, dependências, informações de suporte | Sempre |
+
+Linhas da seção **Sessões**: "Sessão" sempre; "Token de acesso" só com `SpineConfig.technicalDocs` (sem configuração,
+só em `isDevMode()`); "Tokens de aplicação" sempre (sem `SPINE_ADMIN_API` a linha explica que não está disponível);
+"Sessões e dispositivos" só com a API da conta (a mesma condição da seção MFA). Sem nenhuma linha visível, a seção
+não aparece.
+
+**Chave antiga**: até a versão 2.1.2 a seção "Conta e segurança" (`seguranca`) reunia MFA e sessões, e "Sessão" e os
+tokens ficavam em "Conta". `?settings=seguranca` (e `SPINE_SETTINGS_KEYS.security`, agora `@deprecated`) abre a seção
+**MFA** (`SPINE_SETTINGS_ALIASES`, `resolveSettingsSection`); sem a API da conta, como qualquer chave sem seção, abre
+a primeira. `?settings=conta` continua abrindo Conta.
+
+## Recursos opcionais do painel (`SpineConfig.features`)
+
+Desligados sem configuração; o app liga cada um em `provideUi({ ..., features })`:
+
+```ts
+features: {
+  aiAgent: { servers: [{ name: 'hefesto', url: '/hefesto/mcp', label: 'Hefesto', readScopes: 'deploy.*.read', writeScopes: 'deploy.*' }] },
+  accountActivity: true,
+  idleTimeout: { max: 60 },          // ou true; { min, max } em minutos
+  startPage: true,
+  defaultBadge: true,
+  notices: { types: [{ id: 'deploy-concluido', label: 'Deploy concluído' }] },
+  accountPreferences: true,
+}
+```
 
-A seção **Conta e segurança** do painel (`?settings=seguranca`) gerencia a conta da pessoa no Argos sem sair do app:
-**Verificação em duas etapas** (adicionar o aplicativo autenticador com QR Code, adicionar o e-mail, trocar o aparelho,
-remover), **Códigos de recuperação** (gerar um lote novo, mostrado uma vez, com copiar e baixar) e **Sessões e
-dispositivos** (encerrar uma sessão ou todas as outras; a deste login vem marcada). Antes de qualquer alteração a
-pessoa confirma a identidade (senha, código do autenticador, código no e-mail cadastrado ou código de recuperação); o
-Argos guarda essa prova por 5 minutos.
+| Recurso | Onde | O que faz | Depende de |
+| --- | --- | --- | --- |
+| `aiAgent` | Sessões › Conectar um agente de IA | Cria um token de aplicação pessoal (`x-app-token`) e mostra, uma única vez, o `.mcp.json` pronto para o Claude Code com os servidores do app; "Leitura e escrita" põe `writeScopes` em `x-mcp-scopes` (sem isso, `readScopes` ou nenhum header: o MCP já é só leitura). URL relativa vira absoluta pela origem da página. O token nunca vai para o console nem para o storage | `SPINE_ADMIN_API` |
+| `accountActivity` | MFA › Atividade da conta | Entradas e tentativas que falharam desta conta, 90 dias, com IP, navegador, aplicativo, método e motivo; filtro "Só falhas" e "Carregar mais" | API da conta (`GET /activity`) |
+| `idleTimeout` | Conta › Encerrar por inatividade | Nunca/5/15/30/60 min; aviso com contagem 60 s antes e saída pelo `SpineLogoutService`. Conta a atividade de todas as abas. `{ min, max }` limitam a escolha (com `max`, "Nunca" some) | — |
+| `startPage` | Conta › Tela inicial | Início, última tela visitada ou um favorito, aplicada no `/callback` quando o login não pediu outra URL | — |
+| `defaultBadge` | Conta › Crachá padrão | Crachá com que o login entra nesta aplicação, guardado no Argos (vale em qualquer navegador); aparece com mais de um crachá | API da conta (`GET/PUT /badges`) |
+| `notices` | Notificações (`?settings=notificacoes`) | Liga/desliga cada tipo de aviso que o app declara e o aviso do navegador (Notification API, pede a permissão) quando a aba está em segundo plano. O app emite com `SpineNoticesService.notify(tipo, { title, body?, url?, intent? })` | — |
+| `accountPreferences` | Dados do navegador › Preferências na conta | Espelha no Argos (`GET/PUT /preferences`, por usuário e aplicação, até 16 KB) tema, cor, densidade, fonte, menu lateral, idioma, fuso, relógio, semana, texto, animações, atalhos, inatividade, tela inicial, avisos e favoritos: lê e aplica no login, soma os favoritos, grava agrupado. As telas Aparência, Região etc. continuam iguais; sem a API (ou com Argos sem o endpoint) fica só no navegador | API da conta |
+
+Serviços (todos de `@trismegisto/spine/layout`): `SpineIdleService`, `SpineStartPageService`, `SpineNoticesService`,
+`SpineAccountPreferencesService`; preferências novas no `SpinePreferencesService` (`idleMinutes`, `startPage`,
+`noticeTypes`, `browserNotices`).
+
+## MFA e Sessões (API da conta do Argos)
+
+A seção **MFA** (`?settings=mfa`) gerencia a conta da pessoa no Argos sem sair do app: **Verificação em duas etapas**
+(adicionar o aplicativo autenticador com QR Code, adicionar o e-mail, trocar o aparelho, remover) e **Códigos de
+recuperação** (gerar um lote novo, mostrado uma vez, com copiar e baixar). Na seção **Sessões** (`?settings=sessoes`),
+a linha **Sessões e dispositivos** encerra uma sessão ou todas as outras (a deste login vem marcada). Antes de
+qualquer alteração de MFA a pessoa confirma a identidade (senha, código do autenticador, código no e-mail cadastrado
+ou código de recuperação); o Argos guarda essa prova por 5 minutos.
 
 - **API**: a área da conta do Argos com Bearer, `{authority}/api/realms/{realmId}/account/*` (`security`, `reauth`,
   `mfa/*`, `recovery-codes`, `sessions`), com o access token da sessão do `@orfeu/angular` no `Authorization` — o
@@ -132,9 +218,9 @@ Argos guarda essa prova por 5 minutos.
   a sessão pelo `sid` do token. Token vencido renova uma vez e repete.
 - **Configuração**: nenhuma além do `provideAuth`. A origem do app precisa estar nas `redirect_uris` do client no
   Argos (é o que o CORS do Argos libera — o login já exige isso). Sem `authority`/`realmId` (ou com `CHANGE_ME`) a
-  seção não aparece.
+  seção MFA e a linha "Sessões e dispositivos" não aparecem.
 - **Versão do Argos**: precisa da área da conta por Bearer (`/realms/{realm}/account`). Num Argos anterior a seção
-  mostra o erro de carregamento.
+  MFA e a linha de sessões mostram o erro de carregamento.
 - A mesma API sai de `SpineAccountSecurityService` / `argosAccountApi(authority, realm)` (`@trismegisto/spine/layout`),
   para outra tela do app.
 
@@ -145,12 +231,12 @@ Argos guarda essa prova por 5 minutos.
 | `@trismegisto/spine` | `provideUi`, `SpineConfig`, `ThemeService`, `DensityService`, `SpinePreferencesService`, `provideSpineNews`, textos (`SPINE_MESSAGES`, `provideSpineMessages`) |
 | `@trismegisto/spine/shell` | `APP_ROUTES`, `PUBLIC_ROUTES`, `PRIVATE_ROUTES`, `provideShell`, telas de login e de estado |
 | `@trismegisto/spine/routing` | `ComponentRoute`, `COMPONENT_ROUTES`, `ViewGuard`, `RouteIdInterceptor`, resolução de rota |
-| `@trismegisto/spine/layout` | `LayoutComponent` (`spine-layout`), cabeçalho, menu lateral, onboarding, atalhos, configurações, novidades, documentação |
+| `@trismegisto/spine/layout` | `LayoutComponent` (`spine-layout`), cabeçalho, menu lateral, onboarding, atalhos, configurações, novidades, documentação, `SpineLogoutService` |
 | `@trismegisto/spine/modal` | `ModalService` (`open(config)` devolve um `Observable` com o resultado), `ModalContent` |
 | `@trismegisto/spine/side-panel` | `SidePanelService`, `SidePanelContent` |
 | `@trismegisto/spine/notification` | `NotificationService` (`addNotification`) |
-| `@trismegisto/spine/auto-service` | `provideAutoService({ adminApi })`: telas prontas de autosserviço (início, grupos, aplicações, cliente, auditoria), sempre carregadas sob demanda (`AUTO_SERVICE_SCREENS`); as classes das telas não são exportadas. Cada tela já vem com a documentação (manual de uso e especificação técnica, em `AUTO_SERVICE_DOCUMENTS`, também sob demanda) no botão de documentação da página. `AutoServiceService` e o tipo `AutoServiceClient` são exportados |
-| `@trismegisto/spine/audit` | A tela de Auditoria (`SpineAuditComponent`, `spine-audit`), a mesma para o painel central (`scope="admin"`) e o auto-serviço (`scope="client"`), + `SpineAuditService` e os tipos/funções puras (`AuditEvent`, `AuditQuery`, `buildAuditQuery`, `auditApiBase`…). **Exporta o componente: importe só de código lazy** |
+| `@trismegisto/spine/auto-service` | `provideAutoService({ adminApi })`: telas prontas de autosserviço (início, grupos, aplicações, cliente e, no menu Auditoria, ações e tentativas de login), sempre carregadas sob demanda (`AUTO_SERVICE_SCREENS`); as classes das telas não são exportadas. Cada tela já vem com a documentação (manual de uso e especificação técnica, em `AUTO_SERVICE_DOCUMENTS`, também sob demanda) no botão de documentação da página. `AutoServiceService` (com os tipos de grupo `AutoServiceGroup`, `AutoServiceGroupType`, `AutoServiceGroupCreate`, `AutoServiceGroupUpdate`) e o tipo `AutoServiceClient` são exportados |
+| `@trismegisto/spine/audit` | As telas de auditoria — Ações (`SpineAuditComponent`, `spine-audit`) e Tentativas de login (`SpineLoginAttemptsComponent`, `spine-login-attempts`) —, as mesmas para o painel central (`scope="admin"`) e o auto-serviço (`scope="client"`), + `SpineAuditService` e os tipos/funções puras (`AuditEvent`, `AuditQuery`, `buildAuditQuery`, `auditApiBase`…). **Exporta o componente: importe só de código lazy** |
 | `@trismegisto/spine/graphql` | `provideGraphql({ endpoints })`: um cliente Apollo nomeado por backend |
 
 ## Auditoria (`@trismegisto/spine/audit`)
@@ -171,10 +257,10 @@ component: async () => (await import('./admin-audit-page.component')).AdminAudit
 // …e no template da página: <spine-audit scope="admin" [adminApi]="environment.adminApi" />
 ```
 
-- **No auto-serviço:** aba **Auditoria** na página de Aplicações (`import('@trismegisto/spine/audit')` só ao abrir
-  a aba) e página própria ligada a `AUTO_SERVICE_AUDIT_TEMPLATE_ROUTER_ID` (`ad100004-…`), que aparece no menu
-  "Administração" quando o template `auto-service` do banco tiver esse router. O app não configura nada além do
-  `provideAutoService`.
+- **No auto-serviço:** menu **Auditoria** (dentro de "Administração", no template `auto-service` do argos) com duas
+  páginas: **Ações** (`AUTO_SERVICE_AUDIT_TEMPLATE_ROUTER_ID`, `ad100004-…`, esta tela) e **Tentativas de login**
+  (`AUTO_SERVICE_LOGIN_ATTEMPTS_TEMPLATE_ROUTER_ID`, `ad100005-…`, `SpineLoginAttemptsComponent` com
+  `scope="client"`, `GET /auto-service/:clientId/attempts`). O app não configura nada além do `provideAutoService`.
 - **Conteúdo:** período rápido (1h/6h/24h/7d/30d; as datas da faixa de filtros vencem), "Atualizar" + atualização
   automática opcional (30 s), filtros (datas, aplicação — multisseleção —, usuário, operação, método, resultado, só
   ações do usuário, nível, permissão, tipo de ator, status HTTP, trace, ID do usuário; filtros salvos por escopo),