Biblioteca usuario.php

Caminho no Gestor bibliotecas/usuario.php

Tudo o que acontece depois de a senha ser aceita: emitir o cookie de login, listar e encerrar sessões, pedir a senha de novo antes de ações sensíveis, emitir tokens pessoais para a API e guardar os códigos de recuperação do 2FA. Quem a usa é o perfil-usuario e a API.

O cookie de login

usuario_gerar_token_autorizacao(['id_usuarios' => …, 'sessao' => true]):

1. sorteia um pubID (64 hex) e grava em usuarios_tokens com o HMAC USUARIO_HASH_PASSWORD, a validade, o IP e o User-Agent;

2. monta o token no formato RSA do Gestor (usuario_gerar_jwt(), veja autenticacao.php) e o põe no cookie COOKIE_AUTHNAME: HttpOnly, SameSite=Lax, Secure fora do ambiente de desenvolvimento em HTTP;

3. grava o cookie COOKIE_AUTHPROFILE com o SHA-256 do id do perfil (usado só para apresentação; não é assinado).

Com sessao, o cookie morre ao fechar o navegador; sem, dura COOKIE_LIFETIME (15 dias). A validação a cada requisição é do roteador (gestor_permissao_token(), ciclo de uma requisição).

usuario_app_gerar_token_autorizacao() (devolve o token em vez de gravar o cookie) e usuario_openssl_gerar_chaves() não têm chamadores.

Sessões ativas

Autorização provisória

Antes de ações sensíveis (trocar e-mail, senha, 2FA), o perfil-usuario pede a senha de novo. usuario_autorizacao_provisoria() controla essa janela, guardada na sessão com validade de USUARIO_AUTORIZACAO_LIFETIME (300 s):

• ['validar' => true] abre a janela; ['invalidar' => true] fecha; ['verificar' => true] diz se está aberta;

• ['verificarModal' => ['cancelarUrl', 'confirmarUrl', 'autorizadoUrl', 'autorizadoUrlQuerystring']] mostra o modal de confirmação quando ela não está aberta.

Tokens pessoais de API

Tokens c2f_pat_<64 hex> (constante USUARIO_API_TOKEN_PREFIXO), aceitos no mesmo Authorization: Bearer dos tokens OAuth2:

• usuario_api_token_gerar($id_usuario, $nome, $escopos = [], $dias_expiracao = null) devolve o token em texto uma única vez; o banco (usuarios_api_tokens) guarda só o SHA-256 (usuario_api_token_hash()) e um prefixo exibível (usuario_api_token_prefixo());

• usuario_api_token_validar($token) confere hash, status e validade (usuario_api_token_situacao() distingue revogado de expirado), registra o uso e devolve o mesmo formato de oauth2_validar_token();

• usuario_api_token_formato() só diz se a string tem o formato, para a API escolher o validador;

• usuario_api_token_revogar($id_token, $id_usuario), usuario_api_tokens_listar($id_usuario);

• usuario_api_tokens_disponivel(): a tabela existe (instalação migrada).

Códigos de recuperação do 2FA

usuario_recovery_codes_gerar($quantidade = 10) sorteia os códigos (sem 0, O, 1, I e L, para serem copiados à mão); o banco guarda só os hashes (usuario_recovery_code_hash() sobre a forma normalizada por usuario_recovery_code_normalizar(), que ignora hífen, espaço e caixa). usuario_recovery_code_consumir($codigo, $hashes) devolve se o código vale e a lista sem ele (uso único). usuario_recovery_codes_disponivel() informa se a coluna existe.

Legado

usuario_host_dados() devolve dados do usuário de host (modo multi-host, veja host.php) ou de um anônimo. Não tem chamadores.

Funções

usuario_openssl_gerar_chaves(array|false $params = false): array|false

usuario_gerar_jwt(array|false $params = false): string|false

usuario_gerar_token_autorizacao(array|false $params = false): bool

usuario_app_gerar_token_autorizacao(array|false $params = false): array|false

usuario_autorizacao_provisoria(array|false $params = false): bool|void

usuario_user_agent_analisar(string $userAgent): array{navegador:string,sistema:string,dispositivo:string}

usuario_sessao_formatar(array $registro, string|null $tokenAtual = null): array

usuario_sessoes_listar(int $id_usuario, string|null $token_atual_pubID = null): array

usuario_sessao_revogar(string $pubID, int $id_usuario): bool

usuario_sessoes_revogar_outras(string $token_atual_pubID, int $id_usuario): bool

usuario_api_tokens_disponivel(): bool

usuario_recovery_codes_disponivel(): bool

usuario_api_token_formato(string $token): bool

usuario_api_token_hash(string $token): string

usuario_api_token_prefixo(string $token): string

usuario_api_token_situacao(array $registro, int|null $agora = null): string

usuario_api_token_gerar(int $id_usuario, string $nome, array $escopos = Array(), int|null $dias_expiracao = null): array|false

usuario_api_token_validar(string $token_puro): array|false

usuario_api_token_revogar(int $id_token, int $id_usuario): bool

usuario_api_tokens_listar(int $id_usuario): array

usuario_recovery_codes_gerar(int $quantidade = 10): array

usuario_recovery_code_normalizar(string $codigo): string

usuario_recovery_code_hash(string $codigo): string

usuario_recovery_code_consumir(string $codigo, array $hashes): array{valido:bool,restantes:array}

usuario_host_dados(array|false $params = false): mixed|array