Download the PHP package dlunire/dlauth without Composer

Tutorial: DLAuth

Guía práctica de extremo a extremo para usar DLAuth en un proyecto real, desde el login hasta la revocación de sesiones en todos los dispositivos.

1. Instalación

2. Filosofía en una frase

DLAuth nunca consulta una base de datos ni lee la petición HTTP por su cuenta. Solo gestiona $_SESSION, decide cuándo toca revalidar contra una fuente externa (mediante un TTL), y delega el cómo por completo al programador.

Esto la hace agnóstica de cualquier motor de persistencia (MySQL, PostgreSQL, SQLite, archivo, lo que sea).

3. Crear tu propia clase concreta

DLAuth es abstract — no se instancia directamente. Extiéndela con tu propia clase:

4. Login — crear la sesión (siempre en POST)

Regla de oro: la creación de sesión debe ocurrir exclusivamente en peticiones POST, nunca en GET/HEAD. Mezclarlas abre la puerta a session fixation. La separación la garantiza tu enrutador, puede ser el enrutador del ecosistema DLUnire u otro que estés escogiendo:

Dentro del controlador de login:

Qué ocurre internamente al llamar create_session_data():

1. Verifica que haya una sesión de PHP activa (session_start() ya ejecutado); si no, lanza RuntimeException.
2. Verifica que no exista ya una sesión válida en este campo (write-once).
3. Solo si va a proceder de verdad, ejecuta session_regenerate_id(true) — mitigación de session fixation: cualquier ID de sesión que el cliente tuviera antes de autenticarse queda invalidado en este preciso momento.
4. Escribe el registro completo en $_SESSION (datos, timestamp, un token aleatorio de 512 bits, contexto capturado con los set_*()).

5. Leer la sesión — en cada petición (GET/HEAD)

authenticated()/unauthenticated() evitan que tengas que comprobar is_valid_session por tu cuenta en cada controlador — el callback correspondiente solo se ejecuta si aplica.

6. Verificar un token recibido del cliente

DLAuth nunca lee la petición HTTP directamente. Si necesitas comparar un hash que el cliente envió (por ejemplo, en un header Authorization o una cookie separada del PHPSESSID) contra el token guardado en la sesión, extráelo con DLRoute primero y pásaselo a DLAuth:

Internamente usa hash_equals(), no === — comparación en tiempo constante, indispensable porque $received_hash proviene de un cliente no confiable.

7. Logout — cerrar sesión en este dispositivo

Puede utilizar HTTP POST o HTTP DELETE.

8. Cerrar sesión en todos los dispositivos

Este es el flujo más importante para entender la filosofía de DLAuth. Tú decides de dónde sale el dato de revocación — DLAuth solo decide cuándo preguntarte, a través del mismo TTL.

El contrato es estricto: el callback debe devolver siempre una instancia de SessionsRemovalRequest. Si devuelves cualquier otra cosa, DLAuth lanza TypeError de inmediato, en vez de fallar en silencio más adelante.

Para pruebas, sin tocar ninguna base de datos:

Flujo completo de decisión dentro de delete_all_sessions():

9. Cookies — Cookie y SameSite

Si necesitas transportar el token de sesión (o cualquier otro valor) en una cookie separada de PHPSESSID, usa Cookie:

Defaults ya orientados a seguridad: http_only = true siempre, y same_site = SameSite::LAX si no se configura explícitamente. secure queda en false por defecto de forma deliberada — Cookie no tiene visibilidad propia del esquema HTTP/HTTPS de la petición actual; esa determinación le corresponde a DLRoute.

Consultar o eliminar una cookie existente, sin instanciar nada:

10. Resumen de responsabilidades

DLAuth nunca cruza estas fronteras: no consulta bases de datos, no lee la petición HTTP directamente, no decide el esquema de cifrado del transporte. Cada pieza hace una sola cosa.

11. Consideraciones de seguridad ya cubiertas

• Entropía del token: hash('sha384', random_bytes(64)) — 512 bits de una CSPRNG.
• Comparación en tiempo constante: verify_token() usa hash_equals().
• Mitigación de session fixation: session_regenerate_id(true) en cada creación de sesión exitosa.
• Write-once: una sesión ya creada no puede sobrescribirse por accidente.
• Defaults seguros en cookies: http_only = true por defecto.
• Separación POST/GET: responsabilidad de DLRoute, refuerza la mitigación de session fixation a nivel de arquitectura.

12. Fuera del alcance de DLAuth (necesario en otras capas)

• CSRF en el formulario que dispara el POST de login/logout.
• Rate limiting sobre el endpoint de login, para mitigar fuerza bruta.
• Comparación activa de ip/user_agent contra la petición actual para detectar reuso de token desde un contexto distinto — SessionData guarda estos valores, pero no los compara por sí sola.

Estas piezas deben resolverse en DLRoute o en middlewares de la aplicación consumidora, no dentro de DLAuth.