FactuGES_ERP/modules/identity/README.md

# `modules/identity`

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

## Documentación canónica relacionada

- API de autenticación: [`../../docs/architecture/identity-auth-api.md`](../../docs/architecture/identity-auth-api.md)
- Contexto tenant y middlewares públicos: [`../../docs/architecture/tenant-context.md`](../../docs/architecture/tenant-context.md)
- Estado de migración: [`../../docs/architecture/identity-migration-status.md`](../../docs/architecture/identity-migration-status.md)

## 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

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

El endpoint para companies accesibles es:

```http
GET /companies/available
```

Ese endpoint pertenece al flujo actual. Las reglas detalladas del flujo y los endpoints no válidos se mantienen en la documentación de arquitectura.

## Access token

El access token contiene solo identidad de cuenta.

Shape actual:

```ts
{
  accountId: string;
  email: string;
}
```

Las restricciones detalladas sobre claims y contexto tenant se documentan en `tenant-context.md`.

## Middlewares públicos

Los contratos públicos de `requireIdentityAuthenticated(params)` y `requireIdentityTenant(params)` se documentan en `tenant-context.md`.

Código backend nuevo no debe usar:

- `@erp/auth/api`
- `mockUser`
- `requireAuthenticated` legacy
- `requireCompanyContext` legacy

## Servicios públicos

`identity` expone el servicio:

```txt
identity:general
```

Con acceso a `companyAccess` para casos como:

```ts
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`

La validación esperada, la semántica de errores y el shape mínimo de `req.user` se mantienen en `tenant-context.md`.

## Reglas de mantenimiento

- Backend nuevo: usar `@erp/identity/api`.
- No duplicar aquí contratos que ya viven en documentación de arquitectura.
- No borrar `modules/auth` mientras existan consumidores legacy reales.
- `modules/supplier` sigue pendiente de migración si continúa usando el runtime legacy.