usuario.php library

Path in the Gestor bibliotecas/usuario.php

Everything that happens after the password is accepted: issuing the login cookie, listing and ending sessions, asking for the password again before sensitive actions, issuing personal tokens for the API and keeping the 2FA recovery codes. It is used by perfil-usuario and the API.

The login cookie

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

1. draws a pubID (64 hex) and stores it in usuarios_tokens with the USUARIO_HASH_PASSWORD HMAC, the expiration, the IP and the User-Agent;

2. builds the token in the Gestor RSA format (usuario_gerar_jwt(), see autenticacao.php) and puts it in the COOKIE_AUTHNAME cookie: HttpOnly, SameSite=Lax, Secure except in the development environment over HTTP;

3. writes the COOKIE_AUTHPROFILE cookie with the SHA-256 of the profile id (used only for presentation; it is not signed).

With sessao, the cookie dies when the browser closes; without it, it lasts COOKIE_LIFETIME (15 days). Validation on every request is the router's job (gestor_permissao_token(), request lifecycle).

usuario_app_gerar_token_autorizacao() (returns the token instead of writing the cookie) and usuario_openssl_gerar_chaves() have no callers.

Active sessions

Provisional authorization

Before sensitive actions (changing e-mail, password, 2FA), perfil-usuario asks for the password again. usuario_autorizacao_provisoria() controls that window, kept in the session for USUARIO_AUTORIZACAO_LIFETIME (300 s):

• ['validar' => true] opens the window; ['invalidar' => true] closes it; ['verificar' => true] tells whether it is open;

• ['verificarModal' => ['cancelarUrl', 'confirmarUrl', 'autorizadoUrl', 'autorizadoUrlQuerystring']] shows the confirmation modal when it is not open.

Personal API tokens

c2f_pat_<64 hex> tokens (constant USUARIO_API_TOKEN_PREFIXO), accepted in the same Authorization: Bearer as the OAuth2 tokens:

• usuario_api_token_gerar($id_usuario, $name, $scopes = [], $expiration_days = null) returns the plain token only once; the database (usuarios_api_tokens) keeps only its SHA-256 (usuario_api_token_hash()) and a displayable prefix (usuario_api_token_prefixo());

• usuario_api_token_validar($token) checks hash, status and expiration (usuario_api_token_situacao() tells revoked from expired), records the use and returns the same format as oauth2_validar_token();

• usuario_api_token_formato() only tells whether the string has the format, so the API picks the right validator;

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

• usuario_api_tokens_disponivel(): the table exists (migrated installation).

2FA recovery codes

usuario_recovery_codes_gerar($amount = 10) draws the codes (without 0, O, 1, I and L, to be copied by hand); the database keeps only the hashes (usuario_recovery_code_hash() over the form normalized by usuario_recovery_code_normalizar(), which ignores hyphens, spaces and case). usuario_recovery_code_consumir($code, $hashes) returns whether the code is valid and the list without it (single use). usuario_recovery_codes_disponivel() tells whether the column exists.

Legacy

usuario_host_dados() returns data of the host user (multi-host mode, see host.php) or of an anonymous one. It has no callers.

Functions

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