# Autenticación institucional de notificaciones

## Configuración

Configurar en el servidor de la API:

- `NOTIFICATIONS_PERMISSION_MODULE_ID`: identificador de `tblc_modulo` reservado para Notificaciones.
- `NOTIFICATIONS_INSTITUTIONAL_TOKEN_TTL`: vigencia del token Sanctum en minutos.
- `NOTIFICATIONS_INSTITUTIONAL_REQUIRE_HTTPS=true`.
- `NOTIFICATIONS_INSTITUTIONAL_HMAC_KEY_ID` y `NOTIFICATIONS_INSTITUTIONAL_HMAC_SECRET`.
- `NOTIFICATIONS_INSTITUTIONAL_HMAC_PREVIOUS_KEY_ID` y `NOTIFICATIONS_INSTITUTIONAL_HMAC_PREVIOUS_SECRET` durante una rotación.

El secreto debe ser aleatorio, tener al menos 32 bytes y existir solamente en la configuración de ambos servidores.

## Firma HMAC

Cada solicitud a `/api/institutional/notificaciones` incluye:

- `X-Iudy-Key-Id`
- `X-Iudy-Timestamp` (Unix)
- `X-Iudy-Nonce` (16 a 128 caracteres alfanuméricos, guion o guion bajo)
- `X-Iudy-Operator` (`tblc_usuario.IdUsua` de la sesión PHP)
- `X-Iudy-Signature` (HMAC-SHA256 hexadecimal)

La cadena canónica es:

```text
MÉTODO_HTTP
RUTA_Y_QUERY_EXACTAS
SHA256_DEL_CUERPO
TIMESTAMP
NONCE
ID_OPERADOR
```

Para JSON, el hash corresponde a los bytes exactos enviados. Para multipart, se calcula sobre JSON sin escapar Unicode ni `/`, con `fields` ordenados recursivamente y `files` ordenados por campo; cada archivo contiene `name`, `size` y `sha256` de su contenido.

La autenticación devuelve un token con la única ability `notifications:admin`. El proxy PHP debe conservarlo exclusivamente en `$_SESSION`, firmar también cada operación y revocarlo mediante `POST /api/institutional/notificaciones/logout` al cerrar la autorización.

## Endpoints

- `POST /api/institutional/notificaciones/auth`
- `POST /api/institutional/notificaciones/logout`
- `GET /api/institutional/notificaciones?student_id={IdUsua}`
- `POST /api/institutional/notificaciones`
- `GET /api/institutional/notificaciones/{id}?student_id={IdUsua}`
- `GET /api/institutional/notificaciones/{id}/adjunto?student_id={IdUsua}`

La creación requiere `X-Iudy-Idempotency-Key` y `context_student_id`. El historial, detalle y adjunto se filtran por destinatario desde Laravel.