====== 12 - La Forja: acceso identificado al gremio ======

La API es pública: cualquiera puede borrar héroes y nadie sabe quién consulta. El último paso aplica el tema: **autenticación y autorización, tokens opacos, renovación y rotación, ''Principal'' y filtro Servlet**. Lo externo es el formato del intercambio; el mecanismo que lo cumple lo diseña cada uno.

===== 1. Qué se pide =====

  * **Login con credenciales**: el que valida usuario y contraseña entrega un **par de tokens opacos** — y ese intercambio es un contrato fijo:

<sxh json>
{
  "accessToken": "kR9x..._A2t",
  "refreshToken": "bV3q...8fTw"
}
</sxh>

  * El **token de acceso** viaja en cada petición protegida en la cabecera ''Authorization: Bearer ...''. El de **renovación** solo sirve para pedir un par nuevo, que **rota**: tras la renovación, el par antiguo deja de valer.
  * Cada autenticación (el login y el chequeo del token en cada petición) deja una **identidad** disponible para el resto del procesamiento: el controlador sabe **quién** llama, con su nombre y su rol.
  * **Autorización por rol**: el **maestro** administra la plantilla y la forja (altas y borrados); el resto de usuarios autenticados solo consulta. Cada endpoint decide si basta con estar autenticado o si exige un rol.
  * Los dos estados finales se distinguen: quien llega sin identidad recibe ''401 Unauthorized''; quien llega sin permiso, ''403 Forbidden''. Ambos por el canal del manejador global del paso 10.
  * Los tokens se generan con un generador criptográficamente seguro (''SecureRandom'' con formato **URL de Base64**) y el almacén de sesiones activas guarda su **hash**, nunca el valor en claro: robar el almacén no da por qué vale el token.
  * Las contraseñas se guardan con **hash**, nunca en claro.
  * El estado de las sesiones activas obedece a lo ya aprendido en el paso 11: tiene caducidad, no crece sin límite, y el contexto por petición se limpia al terminar — el hilo de Tomcat se reutiliza.

===== 2. Con qué =====

  * Todo lo del tema: autenticación frente a autorización, **tokens opacos**, **renovación** y **rotación**, roles, ''Principal'', estado por petición (''ThreadLocal'' y su limpieza) y el **filtro Servlet** que se ejecuta antes del controlador.
  * El generador seguro del tema y el principio del hash guardado: lo mismo que se hace con la contraseña se hace con los tokens — el valor en claro jamás se almacena.
  * Lo que ya quedó en pie de pasos anteriores: el manejador global del 10 traduce los fallos, y el estado compartido del 11 delimita lo que pertenece a cada hilo.

===== 3. Decisiones tuyas =====

  * ¿Dónde vive cada pieza y con qué nombre? El rol como **enum**, el ''Principal'' propio y el servicio que lo construyen son tuyos: decide el nombre y lo mínimo que llevan.
  * ¿Quién valida el token y **dónde**? La decisión esperada es el filtro, que se ejecuta antes de que el controlador exista; si eliges otra, se defiende.
  * ¿Qué pasa cuando el token no vale o no llega? ¿Y qué pasa con el token de renovación **consumido** que reaparece (la rotación marcó la reutilización como alarma: decide cuál es la consecuencia)?
  * ¿Cómo marca cada endpoint lo que exige: sin identidad, con rol? ¿El controlador consulta el contexto por petición, o el filtro le entrega la identidad ya resuelta?
  * ¿Cuánto vive cada token y cuántas veces se puede renovar? La caducidad es decisión del diseño, no del azar.

===== 4. Comprobación =====

  * El login con credenciales correctas entrega el par de tokens con el formato del contrato; con credenciales malas, falla con ''401'' y sin revelar cuál de las dos falló.
  * Con el token de acceso llega la identidad a cada endpoint: una petición "¿quién soy?" muestra al usuario autenticado, y en ningún log ni token ni contraseña.
  * La protección coincide con la tabla: el maestro administra, el resto consulta; un usuario autenticado sin permiso recibe un ''403'', no un error más.
  * El token de acceso caducado o desconocido es un ''401'' de siempre: el mensaje dice qué ocurre, no cómo se comprobó.
  * La renovación con el token válido entrega par nuevo y deja inutilizado el antiguo: reutilizarlo despierta la alarma de la reutilización que se haya decidido.
  * Tras cada petición, el contexto de identidad queda limpio: repetir la misma petición en el mismo hilo no arrastra el ''Principal'' del usuario anterior.
  * Las pruebas del paso 10 pasan enteras — ahora, para el que ya está autenticado.

===== 5. Cierre del arco =====

El paso 12 completa el recorrido: la app del paso 01 (pseudocódigo del gremio) acaba siendo una **API REST autenticada por tokens opacos**, con roles, filtro y estado por petición — los mismos héroes y la misma forja, construidos paso a paso por quien los había diseñado al principio del curso.

<note warning>Nada del final se improvisa: **nunca** se escriben tokens ni contraseñas en los logs (la regla ya estaba en el paso 10); las contraseñas y los tokens se guardan siempre con **hash**; y el almacén de sesiones activas es, de nuevo, **estado compartido entre hilos** (paso 11) — la caducidad y la limpieza de sesiones vencidas también lo son.</note>