PWR Umbral

Motor de autenticacion segura en PHP puro. Hash Argon2id, TOTP nativo (RFC 6238), bloqueo por intentos fallidos, recuperacion de password y autenticacion en dos factores. Almacenamiento en JSON, sin base de datos ni dependencias externas.

Instalacion

Umbral es un unico archivo PHP. Incluirlo en tu proyecto para disponer de todas las funciones de autenticacion.

PHP 
require_once __DIR__ . '/core/umbral.php';

Requisitos minimos

  • PHP 7.4 o superior
  • Extension sodium (para Argon2id, incluida en PHP 7.2+)
  • Permisos de escritura en datos/ para almacenamiento de usuarios

Inicio rapido

Registro, login y verificacion de sesion en pocas lineas.

PHP 
require_once 'core/umbral.php';

// Registrar un usuario
$reg = pwr_umbral_registrar('usuario@ejemplo.com', 'MiPassword_Seguro123');

// Iniciar sesion
$login = pwr_umbral_login('usuario@ejemplo.com', 'MiPassword_Seguro123');

// Verificar sesion activa
$sesion = pwr_umbral_verificar();

Funciones

pwr_umbral_registrar()

Registra un nuevo usuario con hash Argon2id. Valida formato de email y fortaleza del password.

Firma 
pwr_umbral_registrar(string $email, string $password): array
ParametroTipoDescripcion
$emailstringEmail del usuario (se usa como identificador unico)
$passwordstringPassword en texto plano (se almacena como hash Argon2id)

Retorna: array con ok (bool), id (string) y mensaje (string).

pwr_umbral_login()

Inicia sesion verificando credenciales. Comprueba bloqueo por intentos fallidos antes de validar.

Firma 
pwr_umbral_login(string $email, string $password): array
ParametroTipoDescripcion
$emailstringEmail del usuario
$passwordstringPassword en texto plano

Retorna: array con ok (bool), usuario (datos seguros sin hash) y mensaje. Si tiene 2FA activo, incluye requiere_2fa.

pwr_umbral_logout()

Cierra la sesion activa y destruye los datos de sesion.

Firma 
pwr_umbral_logout(): array

Retorna: array con ok (bool) y mensaje.

pwr_umbral_verificar()

Verifica si hay una sesion activa y valida. Comprueba que el usuario exista y la sesion no haya expirado.

Firma 
pwr_umbral_verificar(): array

Retorna: array con ok (bool), usuario (datos seguros) y mensaje.

pwr_umbral_bloqueo_intentos()

Comprueba si un email tiene bloqueados los intentos de login por exceso de fallos.

Firma 
pwr_umbral_bloqueo_intentos(string $email): array
ParametroTipoDescripcion
$emailstringEmail del usuario a comprobar

Retorna: array con bloqueado (bool), intentos (int), max_intentos (int) y minutos_restantes (int).

pwr_umbral_recuperar_password()

Genera un token de recuperacion de password con expiracion configurable.

Firma 
pwr_umbral_recuperar_password(string $email): array
ParametroTipoDescripcion
$emailstringEmail del usuario que solicita recuperacion

Retorna: array con ok (bool), token (string) y expira (datetime). El token debe enviarse por email al usuario.

pwr_umbral_cambiar_password()

Cambia el password de un usuario usando un token de recuperacion valido.

Firma 
pwr_umbral_cambiar_password(string $token, string $nueva): array
ParametroTipoDescripcion
$tokenstringToken de recuperacion generado por pwr_umbral_recuperar_password()
$nuevastringNueva password en texto plano

Retorna: array con ok (bool) y mensaje.

pwr_umbral_2fa_generar()

Genera un secreto TOTP para activar la autenticacion en dos factores. Devuelve el secreto y la URI para generar QR.

Firma 
pwr_umbral_2fa_generar(string $usuario_id): array
ParametroTipoDescripcion
$usuario_idstringID del usuario al que activar 2FA

Retorna: array con ok (bool), secreto (string base32), uri (string otpauth://) y mensaje.

pwr_umbral_2fa_verificar()

Verifica un codigo TOTP de 6 digitos contra el secreto almacenado del usuario.

Firma 
pwr_umbral_2fa_verificar(string $usuario_id, string $codigo): array
ParametroTipoDescripcion
$usuario_idstringID del usuario
$codigostringCodigo TOTP de 6 digitos desde la app autenticadora

Retorna: array con ok (bool) y mensaje.

pwr_umbral_info()

Devuelve informacion del modulo: version, algoritmo de hash, estado de extensiones y configuracion activa.

Firma 
pwr_umbral_info(): array

Retorna: array con version, hash_algoritmo, 2fa_disponible, usuarios_total.

Configuracion

La configuracion se almacena en datos/umbral_config.json. Si no existe, Umbral usa valores por defecto seguros.

datos/umbral_config.json 
{
    "max_intentos": 5,                  // Intentos fallidos antes de bloquear
    "ventana_bloqueo_minutos": 15,       // Duracion del bloqueo en minutos
    "token_expiracion_horas": 1,          // Expiracion del token de recuperacion
    "totp_digitos": 6,                   // Digitos del codigo TOTP
    "totp_periodo": 30,                  // Periodo de rotacion TOTP en segundos
    "totp_ventana": 1,                   // Ventanas adyacentes aceptadas (+/- 1)
    "sesion_duracion_horas": 24,          // Duracion de la sesion en horas
    "log_activado": true,                // Registrar eventos en log
    "log_ruta": "logs/umbral.log"        // Ruta del archivo de log
}

Ejemplos

Flujo completo de registro y login

PHP 
require_once 'core/umbral.php';

// 1. Registrar usuario
$reg = pwr_umbral_registrar('admin@miapp.com', 'Segura_2024!');
if (!$reg['ok']) {
    die('Error: ' . $reg['mensaje']);
}

// 2. Login
$login = pwr_umbral_login('admin@miapp.com', 'Segura_2024!');
if ($login['ok']) {
    echo 'Bienvenido, ' . $login['usuario']['email'];
}

Proteger una pagina con sesion

pagina-protegida.php 
require_once 'core/umbral.php';

$sesion = pwr_umbral_verificar();
if (!$sesion['ok']) {
    header('Location: /login.php');
    exit;
}

// El usuario esta autenticado
echo 'Hola, ' . $sesion['usuario']['email'];

Activar autenticacion en dos factores

PHP 
require_once 'core/umbral.php';

// Generar secreto TOTP para el usuario
$totp = pwr_umbral_2fa_generar($usuario_id);
if ($totp['ok']) {
    // Mostrar URI para generar QR en la app
    echo 'Configura tu app con esta URI: ' . $totp['uri'];
}

// Verificar codigo TOTP del usuario
$verificacion = pwr_umbral_2fa_verificar($usuario_id, $_POST['codigo_totp']);
if ($verificacion['ok']) {
    echo 'Codigo 2FA valido';
}

Recuperacion de password

PHP 
require_once 'core/umbral.php';

// Generar token de recuperacion
$recuperar = pwr_umbral_recuperar_password('usuario@ejemplo.com');
if ($recuperar['ok']) {
    // Enviar token por email al usuario
    $token = $recuperar['token'];
    // mail($email, 'Recuperar password', "Token: $token");
}

// Cuando el usuario envie el token + nueva password
$cambio = pwr_umbral_cambiar_password($_POST['token'], $_POST['nueva_password']);
echo $cambio['mensaje'];