@hemia/auth-sso/README.md

Autenticación SSO centralizada para entornos multiaplicación desarrollados con Node.js

# @hemia/auth-sso

Cliente de autenticación Single Sign-On (SSO) para entornos web multiaplicación. Este paquete permite validar sesiones, iniciar login usando PKCE, manejar el callback de autenticación, refrescar sesiones y cerrar sesión de forma centralizada.

## Instalación

```bash
npm install @hemia/auth-sso
```

## Uso básico

```ts
import { SSOClient } from '@hemia/auth-sso';

const sso = new SSOClient({
  clientId: 'sistema1',
  redirectUri: 'https://sistema1.com/callback',
  ssoAuthUrl: 'https://sso.miempresa.com/authorize',
  tokenEndpoint: 'https://sistema1.com/api/sso/token',
  sessionEndpoint: 'https://sistema1.com/api/sso/check-session',
  refreshEndpoint: 'https://sistema1.com/api/sso/refresh',
  logoutEndpoint: 'https://sistema1.com/api/sso/logout',
  logoutRedirectUrl: 'https://sistema1.com/',
  scopes: ['openid', 'profile'],
  apiKey: 'mi-api-key'
});
```

## Métodos disponibles

### `validateSession(): Promise<SSOSession>`

Valida si la sesión actual sigue activa, usando una caché de TTL de 1 minuto para evitar llamadas excesivas.

```ts
const session = await sso.validateSession();
if (!session.isAuthenticated) {
  sso.startLogin();
}
```

### `startLogin(auto?: boolean, skip?: boolean): Promise<void>`

Redirige al usuario al flujo de autenticación del SSO usando PKCE.

```ts
sso.startLogin(); // auto y skip son opcionales
```

### `handleCallback(): Promise<{ success: boolean; message?: string, brokenSession?: boolean }>`

Procesa el callback del servidor SSO después de la redirección e intercambia el código de autorización por un token de sesión.

```ts
const result = await sso.handleCallback();
if (!result.success) {
  console.error(result.message);
}
```

### `refreshToken(): Promise<boolean>`

Renueva la sesión actual usando el token de sesión. Ideal para mantener sesiones activas sin necesidad de login constante.

```ts
const ok = await sso.refreshToken();
```

### `logout(): Promise<void>`

Cierra la sesión actual tanto en el cliente como en el backend del sistema, y redirige al usuario.

```ts
await sso.logout();
```

## Requisitos

* Backend del sistema debe implementar los endpoints para: token, sesión, refresh y logout.
* El flujo de autenticación usa PKCE (`code_challenge` y `code_verifier`).
* El cliente guarda datos temporales en `localStorage`.

## Estructura esperada del objeto `SSOConfig`

```ts
interface SSOConfig {
  clientId: string;
  redirectUri: string;
  ssoAuthUrl: string;
  tokenEndpoint: string;
  sessionEndpoint: string;
  refreshEndpoint?: string;
  logoutEndpoint?: string;
  logoutRedirectUrl?: string;
  scopes: string[];
  apiKey?: string;
}
```

## Licencia

MIT