Épica A — Autenticación, usuarios y roles

Estado: Borrador · Última actualización: 2026-08-24 · Índice: README

Cubre la autenticación de usuarios contra el JWT de Flagare y la gestión de miembros y roles por proyecto. El rol no es un atributo del usuario, sino de la relación usuario + proyecto. Reglas de negocio del bloque: RN-001 a RN-008.

HU-001 — Autenticarse con el JWT de Flagare

Épica: A · Autenticación, usuarios y roles · Deriva de: Transversal · Cubre: RF-001, RF-002, RF-003 · Reglas: RN-008, RN-085 · Estado: Borrador

Historia

Como usuario de Flagare, quiero acceder a Argos QA con el mismo token que ya me identifica en el ecosistema, para no gestionar una credencial más y que mi identidad sea la única fuente de verdad.

Objetivo / valor. Argos QA no administra identidades propias: delega el quién es en identity.flagare y se reserva solo el qué puede hacer en cada proyecto. Un token válido basta para entrar; nada de contraseñas locales.

Alcance

• Dentro: validación del JWT en cada petición, la consulta al servicio /me de

identity.flagare al iniciar sesión para obtener los permisos del usuario, el alta implícita en el primer acceso, y el rechazo de tokens inválidos.

• Fuera: la autorización por rol de proyecto (la resuelve HU-002 y la matriz) y el

diseño del contrato del token y de /me (documentado, no diseñado).

Actores y permisos

Precondiciones

• El emisor identity.flagare está disponible para que su token pueda validarse.
• La petición transporta un token en la forma esperada por el contrato (pendiente PA-007).

Comportamiento funcional

• Principal. La petición llega con un JWT que solo valida la identidad; el sistema lo

valida (firma, vigencia, emisor). Al iniciar sesión en Argos QA, el sistema llama al servicio /me de identity.flagare, que devuelve los permisos del usuario —incluido su rol de plataforma (Admin, Product Manager o ninguno)—. Si el usuario no existe localmente, se crea su registro a partir de la identidad, sin aprovisionamiento previo; la sesión continúa con la identidad y los permisos establecidos.

• Alternativo A1 — usuario ya conocido. El registro local ya existe; el sistema no lo

recrea, solo lo asocia a la sesión (sus permisos igual se refrescan desde /me).

• Error E1 — token ausente o malformado. El sistema rechaza la petición sin revelar

información del recurso solicitado.

• Error E2 — token expirado o de emisor no reconocido. Mismo rechazo, sin filtrar

detalle del recurso.

• Error E3 — /me no responde. Sin la respuesta de /me, el sistema no puede resolver los

permisos de plataforma; lo informa y no autoriza acciones de plataforma hasta poder consultarlo.

Datos y campos (funcional, no esquema)

• Del token (JWT): solo validación de identidad —firma, vigencia, emisor e identificador

del usuario—. El token no transporta roles ni permisos.

• De /me de identity.flagare: los permisos del usuario, incluido su **rol de

plataforma** (Admin / Product Manager / ninguno, RN-085). Su forma exacta depende de PA-007.

• Deriva el sistema: registro local del usuario en su primer acceso.

Reglas de negocio aplicables

• RN-008 / RN-085 — el JWT valida la identidad; los permisos de plataforma los

entrega el servicio /me de identity.flagare, que Argos QA consulta y no administra. Los roles de proyecto los administra Argos QA. El contrato de /me queda pendiente en PA-007.

Integraciones (documentado, el dev implementa)

• identity.flagare — Argos QA valida el JWT (llave de identidad) y consulta /me

para obtener los permisos del usuario (rol de plataforma). El contrato fino (forma del token y respuesta de /me) se cierra con PA-007; ninguna credencial propia se almacena.

Criterios de aceptación

• CA-001

> Dado un JWT válido emitido por identity.flagare de un usuario desconocido para Argos QA > Cuando el usuario hace su primera petición autenticada > Entonces el sistema crea su registro local a partir de los claims del token y la petición procede con esa identidad.

• CA-002

> Dado un usuario que ya tiene registro local en Argos QA > Cuando vuelve a autenticarse con un token válido > Entonces el sistema reutiliza su registro y no crea un duplicado.

• CA-003

> Dado una petición sin token o con un token malformado > Cuando llega al sistema > Entonces se rechaza sin revelar información del recurso solicitado.

• CA-004

> Dado una petición con un token expirado o de un emisor no reconocido > Cuando llega al sistema > Entonces se rechaza igual que un token ausente, sin filtrar detalle del recurso.

• CA-012

> Dado un usuario con JWT válido que inicia sesión en Argos QA > Cuando el sistema consulta /me de identity.flagare > Entonces obtiene los permisos del usuario —incluido su rol de plataforma— y los usa para autorizar; el JWT por sí solo no otorga permisos.

Dependencias y bloqueos

• PA-007 — condiciona el contrato del JWT (validación) y del servicio /me de

identity.flagare (forma de los permisos, nombres de rol de plataforma). La HU se especifica asumiendo: token = identidad; /me = permisos.

• HU-002 (miembros y roles) consume la identidad establecida aquí para resolver los

permisos por proyecto.

Casos borde / notas. El alta implícita no requiere que un administrador provisione al usuario de antemano: existir en identity.flagare y acceder por primera vez basta para tener registro local. Ese registro no otorga ningún rol de proyecto por sí solo (RN-004, HU-002).

HU-002 — Gestionar miembros y roles del proyecto

Épica: A · Autenticación, usuarios y roles · Deriva de: CU-002 · Cubre: RF-004, RF-005, RF-006, RF-007, RF-008, RF-018 · Reglas: RN-001, RN-002, RN-003, RN-004, RN-005, RN-006, RN-007 · Estado: Borrador

Historia

Como Product Manager, quiero definir quién participa en el proyecto y con qué roles, para que cada persona vea y haga exactamente lo que le corresponde, y nada más.

Objetivo / valor. El acceso a un proyecto se gobierna por la dupla usuario + proyecto. Sin rol asignado no hay visibilidad; con varios roles, los permisos se suman. El PM es quien reparte esas responsabilidades y cada cambio queda auditado.

Alcance

• Dentro: listar miembros y sus roles, agregar un miembro con uno o más roles, revocar

roles, y la validación de las restricciones de asignación (Client excluyente, último PM).

• Fuera: la autenticación en sí (HU-001), la definición de qué permite cada rol (la fija

la matriz de roles y permisos), las asignaciones de trabajo a personas —escenarios o ejecuciones—, que no existen en el MVP, y la administración de roles de plataforma (Admin, Product Manager de plataforma), que provienen del servicio /me de identity.flagare y no se gestionan aquí (RN-085).

Actores y permisos

Precondiciones

• El usuario que gestiona tiene rol Product Manager en el proyecto, o es Admin de

plataforma (RN-085).

• El proyecto existe y está Activo.

Comportamiento funcional

• Principal. El PM abre la administración de miembros; el sistema muestra los miembros

actuales con sus roles; el PM agrega una persona y le asigna uno o más roles entre Product Manager, QA, Developer y Client; el sistema valida las restricciones, guarda la asignación, la registra en auditoría y notifica al usuario agregado.

• Alternativo A1 — varios roles a la misma persona. El PM asigna, por ejemplo, Developer

y QA a una misma persona; el sistema lo acepta y los permisos efectivos son la unión de ambos (RN-002).

• Alternativo A2 — revocar un rol. El PM retira un rol; el sistema lo aplica de inmediato;

las sesiones activas del afectado pierden el permiso en su siguiente petición.

• Error E1 — Client junto a otro rol. El sistema rechaza asignar Client a quien ya tiene

otro rol en el proyecto, y rechaza asignar otro rol a quien es Client, explicando la exclusividad (RN-006).

• Error E2 — último Product Manager. El sistema impide revocar el rol Product Manager si

es el único del proyecto (RN-005).

Datos y campos (funcional)

• Captura el usuario: miembro a agregar (identidad del usuario), rol o roles a asignar.
• Deriva el sistema: permisos efectivos como unión de roles, marca de auditoría con autor

y timestamp de cada cambio.

Reglas de negocio aplicables

• RN-001 / RN-003 — el rol se asigna por usuario + proyecto; no hay rol global y una

misma persona puede tener roles distintos en proyectos distintos.

• RN-002 — con varios roles, los permisos son la unión, nunca la intersección.
• RN-004 — un usuario sin rol en el proyecto no puede verlo ni saber que existe.
• RN-005 — todo proyecto conserva al menos un Product Manager; no se revoca el último.
• RN-006 — el rol Client es excluyente respecto de cualquier otro rol en el proyecto.
• RN-007 — asignar y revocar roles es facultad del Product Manager y queda auditado.

Estados y transiciones. No cambia el estado de ninguna entidad de producto; sí exige que el proyecto esté Activo (un proyecto Archivado es de solo lectura, HU-005).

Eventos que emite. Ninguno del catálogo de dominio; la notificación al usuario agregado se cursa por el canal de notificaciones (HU-025). El cambio de rol se refleja en auditoría (HU-027).

Criterios de aceptación

• CA-005

> Dado un Product Manager en la administración de miembros de su proyecto > Cuando agrega a una persona y le asigna el rol QA > Entonces el miembro queda con rol QA, el cambio se registra en auditoría y se le notifica.

• CA-006

> Dado una persona ya miembro del proyecto > Cuando el PM le asigna además el rol Developer teniendo ya QA > Entonces el sistema lo acepta y sus permisos efectivos son la unión de QA y Developer.

• CA-007

> Dado un usuario que ya tiene rol Developer en el proyecto > Cuando el PM intenta asignarle además el rol Client > Entonces el sistema lo impide y explica que Client es excluyente.

• CA-008

> Dado un usuario con rol Client en el proyecto > Cuando el PM intenta asignarle cualquier otro rol > Entonces el sistema lo impide por la misma exclusividad.

• CA-009

> Dado un proyecto con un único Product Manager > Cuando el PM intenta revocarle ese rol > Entonces el sistema lo impide e indica que debe existir al menos un Product Manager.

• CA-010

> Dado un miembro con un rol asignado y una sesión activa > Cuando el PM le revoca ese rol > Entonces el permiso se pierde en la siguiente petición del afectado.

• CA-011

> Dado un usuario sin ningún rol en un proyecto > Cuando intenta listarlo o acceder a él por su identificador > Entonces el sistema no se lo muestra ni le revela que existe.

• CA-013

> Dado un usuario con rol de plataforma Admin y un proyecto donde no tiene rol de proyecto asignado > Cuando accede a ese proyecto > Entonces el sistema se lo permite —excepción a RN-004 por su permiso de plataforma (RN-085)—, a diferencia de un usuario sin rol, al que se le niega.

Dependencias y bloqueos

• HU-001 (autenticación) provee la identidad sobre la que se asignan los roles.
• HU-005 (archivar y reactivar) — sobre un proyecto Archivado no se gestionan roles.
• HU-025 (eventos y notificaciones) cursa el aviso al usuario agregado.

Casos borde / notas. La revocación no cierra sesiones activas de forma inmediata: el permiso se pierde en la siguiente petición, no a mitad de una en curso. Un usuario puede ser QA en un proyecto y Developer en otro sin conflicto (RN-003).