@bigso/auth-sdk 0.4.7 → 0.5.1

package/README.md

@@ -1,188 +1,233 @@
 # @bigso/auth-sdk
 
-SDK oficial de autenticación para Bigso SSO, compatible con el estándar SSO v2.3. Este paquete permite integrar aplicaciones web con el flujo de autenticación basado en iframe seguro, utilizando PKCE, JWS firmados y comunicación mediante postMessage.
+SDK oficial de autenticación para Bigso SSO v2. Flujo basado en JWT Bearer tokens con PKCE, comunicación por iframe seguro, y validación JWKS.
 
-## 🚀 Características
+## Características
 
-✅ **Flujo seguro** con PKCE obligatorio y JWS firmado.
+- **Flujo PKCE completo** — codeVerifier se expone al consuming app para enviar al backend
+- **JWT Bearer tokens** — accessToken + refreshToken con revoke y rotación automática
+- **Comunicación por iframe** con postMessage v2.3 y validación de origen
+- **JWS verification** en frontend con JWKS remoto
+- **3 entry points**: Browser, Node.js, Express middleware
+- **Server-to-server** login, exchange, refresh, logout via API v2
 
-✅ **Compatible con SSO v2.3** (whitelist de origins, kid en JWS, validación de nonce, timeout reactivo).
+## Instalación
 
-✅ **Manejo automático de estados** (state, nonce, verifier, requestId).
-
-✅ **Verificación de firma JWS** en el frontend usando `jose` y JWKS remoto.
+```bash
+npm install @bigso/auth-sdk
+```
 
-✅ **Timeout reactivo configurable**, activado tras `sso-ready`.
+## Arquitectura v2
 
-✅ **Soporte para redirect_uri y tenant_hint**.
+```
+┌──────────────┐     postMessage (v2.3)     ┌──────────────┐
+│   App Web     │◄──────────────────────────►│  SSO Portal   │
+│  (consuming)  │  sso-init / sso-success    │  (iframe)     │
+└──────┬───────┘                             └──────┬───────┘
+       │                                            │
+       │ 1. auth.login() → codeVerifier             │
+       │ 2. POST /exchange-v2-pkce                  │
+       │    { code, codeVerifier }                  │
+       ▼                                            ▼
+┌──────────────┐     POST /api/v2/auth/exchange    ┌──────────────┐
+│  App Backend  │──────────────────────────────────►│  SSO Core     │
+│  (Express)   │◄─────────────────────────────────│  (API v2)     │
+│              │     { accessToken, refreshToken }  │              │
+└──────────────┘                                   └──────────────┘
+```
 
-✅ **Manejo de errores** incluyendo `version_mismatch` con fallback automático.
+## Uso
 
-✅ **API asíncrona** basada en promesas.
+### Browser (iframe login)
 
-✅ **Sistema de eventos** (ready, success, error, fallback, debug).
+```typescript
+import { BigsoAuth } from '@bigso/auth-sdk';
 
-✅ **Ligero** (~6 kB) y con tipos TypeScript.
+const auth = new BigsoAuth({
+  clientId: 'crm',
+  ssoOrigin: 'https://sso.bigso.co',
+  jwksUrl: 'https://sso.bigso.co/.well-known/jwks.json',
+});
 
-## 📦 Instalación
+auth.on('success', async (result) => {
+  // result.code         → authorization code
+  // result.codeVerifier → PKCE verifier (send to your backend!)
+  // result.signed_payload → JWS signed payload
+  // result.state        → matches your original state
+  // result.nonce        → matches your original nonce
+
+  // Send to your backend:
+  const response = await fetch('/api/auth/exchange-v2-pkce', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      payload: result.signed_payload,
+    }),
+  });
+});
 
-```bash
-npm install @bigso/auth-sdk
-# o
-yarn add @bigso/auth-sdk
-# o
-pnpm add @bigso/auth-sdk
+auth.login();
 ```
 
-## 🧪 Uso básico
+### Express backend
 
 ```typescript
-import { BigsoAuth } from '@bigso/auth-sdk';
+import { BigsoSsoClient } from '@bigso/auth-sdk/node';
+import { createSsoAuthRouter, ssoAuthMiddleware } from '@bigso/auth-sdk/express';
 
-const auth = new BigsoAuth({
-  clientId: 'tu-client-id',
-  ssoOrigin: 'https://sso.tudominio.com',
-  jwksUrl: 'https://sso.tudominio.com/.well-known/jwks.json',
-  timeout: 5000,            // opcional, por defecto 5000ms
-  debug: true,              // opcional, logs de depuración
-  redirectUri: 'https://miapp.com/callback',   // opcional
-  tenantHint: 'mi-tenant'   // opcional
+const ssoClient = new BigsoSsoClient({
+  ssoBackendUrl: 'https://sso.bigso.co',
+  ssoJwksUrl: 'https://sso.bigso.co/.well-known/jwks.json',
+  appId: 'crm',
 });
 
-auth.on('ready', () => console.log('✅ Iframe listo'));
-auth.on('success', (payload) => {
-  console.log('✅ Autenticación exitosa', payload);
-  // Envía el signed_payload al backend para canjear el código
-  enviarAlBackend(payload.signed_payload);
-});
-auth.on('error', (error) => console.error('❌ Error:', error));
-auth.on('fallback', () => console.log('⚠️ Fallback por redirección activado'));
+// Auth routes: /exchange, /exchange-v2, /session, /refresh, /logout
+app.use('/api/auth', createSsoAuthRouter({
+  ssoClient,
+  frontendUrl: 'https://myapp.com',
+}));
 
-auth.login().catch(err => console.error('Login falló', err));
+// Protected routes: validates Bearer JWT token
+app.get('/api/protected', ssoAuthMiddleware({ ssoClient }), (req, res) => {
+  res.json({ user: req.user, tenant: req.tenant });
+});
 ```
 
-## 📚 API Reference
+### Node.js (server-to-server)
 
-### `new BigsoAuth(options)`
-Crea una nueva instancia del cliente de autenticación.
+```typescript
+import { BigsoSsoClient } from '@bigso/auth-sdk/node';
 
-#### Opciones de configuración
-| Parámetro | Tipo | Obligatorio | Por defecto | Descripción |
-| :--- | :--- | :---: | :---: | :--- |
-| `clientId` | `string` | ✅ | — | Client ID registrado en el SSO. |
-| `ssoOrigin` | `string` | ✅ | — | Origen del SSO (ej. `https://sso.bigso.co`). |
-| `jwksUrl` | `string` | ✅ | — | URL del JWKS para verificar firmas (ej. `/.well-known/jwks.json`). |
-| `timeout` | `number` | ❌ | `5000` | Tiempo máximo de espera tras `sso-ready` (milisegundos). |
-| `debug` | `boolean` | ❌ | `false` | Activa logs de depuración en consola. |
-| `redirectUri` | `string` | ❌ | `''` | URI de redirección registrada (se valida exactamente en el SSO). |
-| `tenantHint` | `string` | ❌ | `''` | Sugerencia de tenant para flujos multi-tenant. |
+const client = new BigsoSsoClient({
+  ssoBackendUrl: 'https://sso.bigso.co',
+  ssoJwksUrl: 'https://sso.bigso.co/.well-known/jwks.json',
+  appId: 'crm',
+});
 
-### `auth.login()`
-Inicia el flujo de autenticación. Devuelve una promesa que se resuelve con el payload decodificado del JWS (solo para información; la validación final debe realizarse en el backend).
+// Exchange authorization code with PKCE
+const session = await client.exchangeCode('ac_abc123...', 'dBjftJeZ4CVP...');
 
-**Retorna**: `Promise<any>` – Payload del JWS (contiene `code`, `state`, `nonce`, `iss`, etc.).
+// Validate an access token locally (no network call)
+const payload = await client.validateAccessToken('eyJhbG...');
 
-**Rechaza**: `Error` o payload de error del iframe.
+// Refresh tokens (uses httpOnly cookie)
+const refreshed = await client.refreshTokens();
 
-### `auth.abort()`
-Cancela el flujo de autenticación en curso, eliminando el iframe y rechazando la promesa.
+// Logout
+await client.logout('eyJhbG...', true);  // revokeAll = true
+```
 
-### `auth.on(event, handler)`
-Registra un manejador para los eventos del SDK.
+## API Reference
 
-#### Eventos disponibles:
-| Evento | Descripción | Parámetros |
-| :--- | :--- | :--- |
-| `ready` | Se emite cuando el iframe está listo y se ha enviado `sso-init`. | — |
-| `success` | Se emite tras verificar exitosamente la firma JWS y validar `state`/`nonce` en el frontend. | `payload: any` (payload del JWS) |
-| `error` | Se emite cuando ocurre un error (incluyendo `version_mismatch` antes del fallback automático). | `error: Error | SsoErrorPayload` |
-| `fallback` | Se emite justo antes de redirigir a la URL de fallback (por timeout o `version_mismatch`). | — |
-| `debug` | Se emite cuando `debug: true` para logs internos. | `args: any[]` |
+### Browser: `BigsoAuth`
 
-## ⚙️ Ejemplos avanzados
+#### Constructor
 
-### Personalizar el timeout
-```typescript
-const auth = new BigsoAuth({
-  clientId: 'abc123',
-  ssoOrigin: 'https://sso.bigso.co',
-  jwksUrl: 'https://sso.bigso.co/.well-known/jwks.json',
-  timeout: 10000 // 10 segundos
-});
-```
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `clientId` | `string` | Yes | — | App ID registered in SSO |
+| `ssoOrigin` | `string` | Yes | — | SSO origin (e.g. `https://sso.bigso.co`) |
+| `jwksUrl` | `string` | Yes | — | JWKS URL for JWS verification |
+| `timeout` | `number` | No | `5000` | Timeout after `sso-ready` (ms) |
+| `debug` | `boolean` | No | `false` | Debug logging |
+| `redirectUri` | `string` | No | `''` | Redirect URI |
+| `tenantHint` | `string` | No | `''` | Tenant hint for multi-tenant |
 
-### Usar `redirect_uri` y `tenant_hint`
-```typescript
-const auth = new BigsoAuth({
-  clientId: 'abc123',
-  ssoOrigin: 'https://sso.bigso.co',
-  jwksUrl: 'https://sso.bigso.co/.well-known/jwks.json',
-  redirectUri: 'https://admin.miapp.com/callback',
-  tenantHint: 'enterprise'
-});
-```
+#### `auth.login()`
 
-### Manejo de fallback personalizado
-Puedes escuchar el evento `fallback` para ejecutar tu propia lógica antes de la redirección automática:
+Returns `Promise<BigsoAuthResult>`:
 
-```typescript
-auth.on('fallback', () => {
-  console.log('Mostrando spinner o mensaje...');
-  // Por defecto, el SDK redirige a /authorize.
-  // Si quieres evitar la redirección automática, puedes sobrescribir el comportamiento
-  // pero no es recomendable ya que es el mecanismo de último recurso.
-});
-```
+| Field | Type | Description |
+|---|---|---|
+| `code` | `string` | Authorization code from SSO |
+| `codeVerifier` | `string` | PKCE code verifier — send to backend |
+| `state` | `string` | Matches your original state |
+| `nonce` | `string` | Matches your original nonce |
+| `signed_payload` | `string` | JWS signed payload |
+| `tenant` | `SsoTenant` | Tenant data (if included) |
 
-## 🔒 Consideraciones de seguridad
+### Node: `BigsoSsoClient`
 
-- **Whitelist de origins**: El SDK asume que el SSO Core está configurado correctamente con la whitelist de origins para cada `client_id` y que responde con `Content-Security-Policy: frame-ancestors`. El SDK no puede controlar esto; es responsabilidad del administrador del SSO.
-- **Validación en backend**: La verificación del JWS en el frontend es solo una capa adicional de integridad. El backend debe validar la firma, el nonce, el state y canjear el código usando PKCE antes de emitir tokens.
-- **nonce y state**: El SDK genera valores aleatorios seguros (`crypto.randomUUID`) y los valida en el frontend. El backend debe realizar la misma validación para prevenir ataques de replay.
-- **Prevención de replay**: El SDK no incluye lógica de deduplicación de JWS en el frontend; esto debe implementarse en el backend usando `jti` si es necesario.
-- **Timeout**: El timeout se inicia solo después de `sso-ready`, evitando falsos positivos. Si se alcanza, el SDK ejecuta un fallback a redirección (endpoint `/authorize`).
-- **Versiones**: El SDK usa `v: '2.3'`. Si el iframe responde con `version_mismatch`, se activa el fallback automático.
+| Method | Description |
+|---|---|
+| `exchangeCode(code, codeVerifier)` | Exchange auth code for tokens via `/api/v2/auth/exchange` |
+| `refreshTokens()` | Refresh tokens via `/api/v2/auth/refresh` (uses cookie) |
+| `logout(accessToken, revokeAll?)` | Revoke session via `/api/v2/auth/logout` |
+| `validateAccessToken(token)` | Verify JWT locally against JWKS |
+| `verifySignedPayload(token, audience)` | Verify JWS signed payload |
 
-## 🛠️ Desarrollo
+### Express: `createSsoAuthRouter(options)`
 
-### Construcción
-```bash
-npm run build   # genera dist/ con formatos ESM, CJS y types
-```
+| Route | Method | Description |
+|---|---|---|
+| `/exchange` | POST | `{code, codeVerifier}` → v2 exchange |
+| `/exchange-v2` | POST | `{payload}` → verify JWS, then v2 exchange |
+| `/session` | GET | Validate Bearer token, return user data |
+| `/refresh` | POST | Proxy to `/api/v2/auth/refresh` |
+| `/logout` | POST | Bearer token → `/api/v2/auth/logout` |
+
+### Express: `ssoAuthMiddleware({ ssoClient })`
+
+Reads `Authorization: Bearer <token>`, validates JWT against JWKS, populates `req.user`, `req.tenant`, `req.tokenPayload`.
+
+## Flujo PKCE completo
 
-### Pruebas
-```bash
-npm test        # ejecuta vitest
 ```
+1. Browser SDK genera: state, nonce, codeVerifier
+2. Browser SDK computa: codeChallenge = SHA256(codeVerifier)
+3. Browser SDK → iframe: {codeChallenge, state, nonce}
+4. Iframe → SSO Core: POST /api/v2/auth/authorize (con codeChallenge)
+5. Iframe → Browser SDK: {code, state} (firmado como JWS)
+6. Browser SDK verifica JWS, valida state y nonce
+7. Browser SDK retorna {code, codeVerifier} al consuming app
+8. Consuming app → su backend: POST /exchange-v2-pkce {payload, codeVerifier}
+9. Backend verifica JWS, extrae code, llama /api/v2/auth/exchange {code, appId, codeVerifier}
+10. SSO Core verifica: SHA256(codeVerifier) === codeChallenge → emite tokens
+```
+
+## Seguridad
+
+- **PKCE**: codeVerifier nunca sale del browser hasta el paso 7, pero jamás se envía al SSO iframe
+- **JWS**: El signed_payload se verifica contra JWKS en frontend y backend
+- **state + nonce**: Validados en ambos lados para prevenir CSRF y replay
+- **JWT Bearer**: Access tokens validados localmente contra JWKS, revocables en Redis/PG
+- **httpOnly cookies**: Refresh tokens via cookie, nunca accesibles via JS
+
+## Desarrollo
 
-### Linting
 ```bash
-npm run lint
+npm run build   # ESM + CJS + types → dist/
+npm run dev     # watch mode
+npm run lint    # eslint
+npm test        # vitest
 ```
 
-## 📝 Changelog
+## Changelog
 
-### v0.4.0 (2026-03-23)
-Protocolo actualizado a SSO v2.3
-- Mensaje `sso-init` con `v: '2.3'`.
-- Timeout reactivo (se inicia tras `sso-ready`).
-- Validación de `requestId` en respuestas.
-- Soporte para `redirect_uri`, `tenant_hint`, `timeout_ms`.
-- Manejo de error `version_mismatch` con fallback automático.
-- Validación de `nonce` en el frontend tras verificar JWS.
+### v0.5.0 (2026-04-07) — Full v2
 
-**Mejoras internas:**
-- Método `abort()` para cancelar operación.
-- Evento `debug` opcional.
-- Documentación completa.
+**Breaking changes:**
+- All v1 API endpoints removed (`/api/v1/auth/token`, `/api/v1/auth/verify-session`, etc.)
+- `SsoSessionData`, `SsoRefreshData`, `SsoExchangeResponse` types removed
+- `ssoAuthMiddleware` now validates Bearer JWT (no cookies)
+- Express routes use v2 endpoints exclusively
+- `BigsoSsoClient` methods renamed/changed
 
-**Breaking changes:** Ninguno, pero se recomienda actualizar el backend para validar `nonce` si no lo hacía antes.
+**New features:**
+- `BigsoAuthResult.codeVerifier` — PKCE verifier exposed for backend exchange
+- `BigsoSsoClient.exchangeCode(code, codeVerifier)` — PKCE exchange via `/api/v2/auth/exchange`
+- `BigsoSsoClient.refreshTokens()` — via `/api/v2/auth/refresh`
+- `BigsoSsoClient.logout(accessToken)` — via `/api/v2/auth/logout`
+- `BigsoSsoClient.validateAccessToken(token)` — Local JWT verification against JWKS
+- Express `/exchange-v2-pkce` route with full PKCE support
+- Express `/refresh` and `/logout` routes for v2 API
+- `ssoAuthMiddleware` validates Bearer JWT tokens locally
 
-### v0.2.0 (anterior)
-- Implementación inicial con v2.2.
+### v0.4.0 (2026-03-23)
+- SSO v2.3 protocol support (iframe postMessage)
+- PKCE, JWS verification, nonce validation
+- Timeout reactive (starts after `sso-ready`)
 
-## 📄 Licencia
-MIT © Bigso
+## Licencia
 
-## 🤝 Contribuciones
-Por favor, abre un issue o pull request en el repositorio oficial.
+MIT © Bigso

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@bigso/auth-sdk",
-    "version": "0.4.7",
-    "description": "SDK de autenticación para SSO v2.3 con iframe seguro",
+    "version": "0.5.1",
+    "description": "SDK de autenticación para SSO v2 - JWT Bearer + PKCE",
     "publishConfig": {
         "registry": "https://registry.npmjs.org/",
         "access": "public"