Uecko_ERP/modules/identity/README.md

modules/identity

identity es el runtime nuevo de autenticación, sesión y acceso por memberships del ERP.

Responsabilidades

Gestiona:

• Account
• login
• refresh
• logout
• session
• RefreshToken
• CompanyMembership
• acceso account-company
• roles/permisos futuros

No gestiona:

• la ficha operativa completa de empresa
• companySlug en auth
• el tenant dentro del access token

Endpoints activos

POST /identity/auth/login
POST /identity/auth/refresh
POST /identity/auth/logout
GET  /identity/auth/session

El endpoint para companies accesibles es:

GET /companies/available

Ese endpoint pertenece al flujo actual, pero no implica que identity deba exponer GET /identity/companies.

Access token

El access token contiene solo:

{
  accountId: string;
  email: string;
}

No debe contener:

• companyId
• companySlug
• roles
• permisos

Middlewares públicos

Para rutas autenticadas sin tenant:

router.use(...requireIdentityAuthenticated(params));

Para rutas tenant-scoped:

router.use(...requireIdentityTenant(params));

Código backend nuevo no debe usar:

• @erp/auth/api
• mockUser
• requireAuthenticated legacy
• requireCompanyContext legacy

Servicios públicos

identity expone el servicio:

identity:general

Con acceso a companyAccess para casos como:

canAccessCompany(...)
findAccessibleCompanyIds(...)

Responsabilidad:

• identity decide qué companyId puede usar una cuenta según memberships activas.
• no devuelve la ficha completa de empresa.

Tenant context

requireIdentityTenant(params) compone:

• identity:general.companyAccess
• companies:general.finder

Validación esperada:

1. access token válido
2. cuenta autenticable
3. X-Company-Id presente
4. X-Company-Id UUID válido
5. membership activa
6. company activa
7. req.user.companyId poblado

Reglas de mantenimiento

• Backend nuevo: usar @erp/identity/api.
• No documentar ni crear GET /identity/companies.
• No borrar modules/auth mientras existan consumidores legacy reales.
• modules/supplier sigue pendiente de migración si continúa usando el runtime legacy.