req-119: Personal Access Tokens (Chaves de API Pessoais) e Códigos de Recuperação (Recovery Codes) no Perfil de Usuário

• Status do intake: ready-for-intake

• Data: 2026-08-17

• Origem: continuidade do programa de modernização do módulo perfil-usuario e individualização de segurança por usuário

• Classificação: segurança de API, autenticação multi-fator, chaves pessoais

• Batch candidato: BATCH-120

1. Contexto e Objetivos

Com as políticas de API e 2FA centralizadas no admin-environment, cada usuário autorizado (conforme AUTH_API_ALLOWED_PROFILES) precisa ter a capacidade de emitir e gerenciar suas próprias Chaves de API (Personal Access Tokens - PAT) de forma granular, além de contar com Códigos de Recuperação (Recovery Codes) para evitar perda irreversível de acesso caso perca seu aplicativo autenticador.

Esta requisição implementa:

1. Aba de Chaves de API Pessoais (PAT) no Perfil: Geração segura de tokens com identificador único, nome amigável, prefixo visível, escopos de permissão e data de expiração;

2. Revogação e Auditoria de Tokens: Exibição de data de criação, último uso e botão de revogação instantânea;

3. Códigos de Backup / Recuperação para 2FA: Geração de 10 códigos descartáveis (armazenados com hash seguro) no momento da ativação do 2FA e suporte ao resgate na tela de login.

2. Escopo Técnico Requerido

Módulo 1: Estrutura de Banco de Dados e Biblioteca de Tokens de API

• Tabela usuarios_api_tokens:

  • id_usuarios_api_tokens (PK auto-increment);

  • id_usuarios (FK para usuarios);

  • nome (identificador amigável do token, ex.: "Integração Zapier", "CLI Local");

  • token_prefix (primeiros 8 caracteres visíveis, ex.: c2f_pat_a1b2...);

  • token_hash (hash SHA-256 do token completo);

  • escopos (JSON com permissões autorizadas para o token);

  • expiracao (data/hora de expiração opcional ou nulo para sem expiração);

  • ultimo_uso (datetime atualizado a cada requisição autenticada);

  • status (A = Ativo, R = Revogado, E = Expirado);

  • data_criacao, data_modificacao.

• Biblioteca Core (gestor/bibliotecas/usuario.php):

  • usuario_api_token_gerar(int $id_usuario, string $nome, array $escopos = [], ?int $dias_expiracao = null): array: Gera o token aleatório com prefixo c2f_pat_, grava o hash no banco e retorna o token em texto puro uma única vez;

  • usuario_api_token_validar(string $token_puro): array|false: Valida se o token é válido, não está revogado, não expirou e atualiza ultimo_uso;

  • usuario_api_token_revogar(int $id_token, int $id_usuario): bool: Marca o status do token como revogado (R).

Módulo 2: Aba de Chaves de API no perfil-usuario

• Interface em Tailwind CSS:

  • Nova Tab 4: Chaves de API (PAT) no painel do perfil;

  • Botão "Gerar Nova Chave de API", abrindo modal moderno em Tailwind com formulário (Nome do Token, Duração/Expiração, Escopos selecionáveis);

  • Modal de exibição do token recém-gerado com botão de cópia rápida ("Copie este token agora. Você não poderá visualizá-lo novamente");

  • Tabela responsiva com a lista de tokens ativos do usuário, exibindo Nome, Prefixo, Data de Criação, Último Uso e Botão de Revogação.

Módulo 3: Códigos de Recuperação (Recovery Codes) para 2FA

• Armazenamento e Geração:

  • Adicionar coluna two_factor_recovery_codes (JSON de hashes) na tabela usuarios;

  • Na ativação do 2FA em perfil_usuario_ajax_seguranca_2fa_ativar, gerar 10 códigos alfanuméricos de 8 caracteres (ex: ABCD-1234), gravar os hashes e exibir os códigos formatados para o usuário salvar/imprimir;

  • Ao usar um código de recuperação na tela de login (signin-2fa), invalidar aquele código específico (código de uso único).

3. Critérios de Aceite e Validação

1. Usuários de perfis autorizados conseguem criar Personal Access Tokens com prefixo legível e copiar a chave no momento da criação.

2. A listagem de tokens no perfil atualiza o "Último uso" quando o token é utilizado em chamadas de API.

3. A revogação do token invalida imediatamente o acesso em qualquer endpoint REST/API do sistema.

4. Ao ativar o 2FA, os 10 recovery codes são gerados e exibidos claramente. O login com recovery code funciona e consome o código utilizado.

5. Testes unitários PHP e Vitest cobrindo geração, autenticação via PAT e consumo de recovery codes 100% verdes.