jwt.php library

Path in the Gestor bibliotecas/jwt.php

Generates and validates HS256 JWTs with a set of symmetric keys stored in the database, with rotation and a grace period.

Keys

The set is stored as JSON in the variaveis table (modulo='sistema', id='jwt_keys'), each key with key_id, key_secret (256 bits), created_at, status (active/expired) and expired_at. The first call to jwt_generate_token() creates the active key if there is none.

jwt_rotate_keys() expires the active key, creates a new one and deletes the expired ones whose grace period is over. The grace period is AUTH_JWT_GRACE_HOURS (default 24) hours counted from expired_at.

Usage

gestor_incluir_biblioteca('jwt');
$token = jwt_generate_token(['sub' => $userId, 'exp' => time() + 3600]);
try {
    $r = jwt_validate_token($token);          // ['status' => 'Active'|'Grace', 'payload' => [...]]
    if (($r['payload']['exp'] ?? 0) < time()) throw new Exception('Expired token.');
    if ($r['status'] === 'Grace') { /* issue a new token */ }
} catch (Exception $e) {
    // malformed, unknown kid, invalid signature or key outside the grace period
}

Other details:

• iat is added when missing; the header carries kid with the key_id.

• The header's alg is ignored (verification is always HMAC-SHA256), which prevents algorithm-confusion attacks.

• The secret keys are stored in plain text in the variaveis table: anyone who can read the database (or a backup) can issue tokens.

Internal helpers (used by the functions above; rarely called directly): jwt_base64url_encode(), jwt_base64url_decode(), jwt_rotation_days(), jwt_grace_hours(), jwt_keys_load(), jwt_keys_save(), jwt_nova_chave(), jwt_get_active_key().

Functions

jwt_base64url_encode($data)

jwt_base64url_decode($data)

jwt_rotation_days()

jwt_grace_hours()

jwt_keys_load(): array

jwt_keys_save(array $keys): void

jwt_nova_chave(string $status = 'active'): array

jwt_get_active_key(): array

jwt_generate_token(array $payload): string

jwt_validate_token(string $token): array

jwt_rotate_keys(): array