@hemia/auth-sdk 0.0.1

package/README.md

@@ -0,0 +1,86 @@
+# Hemia Auth SDK
+
+SDK para gestionar autenticación SSO con PKCE flow, manejo de sesiones y refresh tokens automático.
+
+---
+
+## 📦 Instalación
+
+```bash
+npm install @hemia/auth-sdk
+bun add @hemia/auth-sdk
+```
+
+```bash
+bun add @hemia/auth-sdk
+```
+
+---
+
+## 🚀 Uso Básico
+
+### Configuración
+
+```typescript
+import { AuthService, AuthCacheService } from '@hemia/auth-sdk';
+
+const config = {
+  clientId: 'your-client-id',
+  clientSecret: 'your-client-secret',
+  redirectUri: 'http://localhost:3000/callback',
+  ssoBaseUrl: 'https://sso.hemia.com',
+  ssoAuthUrl: '/oauth/authorize',
+  ssoTokenEndpoint: '/oauth/token',
+  ssoLogoutEndpoint: '/oauth/logout',
+  uiBaseUrl: 'http://localhost:3000'
+};
+
+const storage = new AuthCacheService(redisClient);
+const jwtManager = new JwtManager();
+const authService = new AuthService(config, storage, jwtManager);
+```
+
+---
+
+## 🎯 Controller Abstracto
+
+El SDK incluye un `AbstractAuthController` con endpoints listos:
+
+- `GET /login` - Inicia el flujo de autenticación
+- `GET /callback` - Procesa el callback del SSO
+- `GET /me` - Obtiene datos del usuario autenticado
+- `POST /logout` - Cierra la sesión
+
+```typescript
+import { AbstractAuthController } from '@hemia/auth-sdk';
+
+export class AuthController extends AbstractAuthController {
+  constructor(authService: AuthService) {
+    super(authService);
+  }
+}
+```
+
+---
+
+## 🔒 Manejo de Errores
+
+Todos los errores de sesión extienden `SessionError` e incluyen:
+- `code`: Código del error
+- `message`: Mensaje descriptivo
+- `redirectTo`: URL de redirección sugerida
+
+---
+
+## 🛠️ Scripts Disponibles
+
+| Script       | Descripción                      |
+|--------------|----------------------------------|
+| `npm run build`   | Compila el paquete con Rollup     |
+| `npm run test`    | Ejecuta pruebas con Jest         |
+| `npm run clean`   | Limpia la carpeta `dist/`       |
+
+---
+
+## ✨ Generado con Hemia CLI
+    

package/dist/hemia-auth-sdk.esm.js

@@ -0,0 +1,496 @@
+import 'reflect-metadata';
+import { Get, Req, Res, Post, HttpError, BadRequestError, CustomHttpError, InternalServerError } from '@hemia/common';
+import { HMNetworkServices } from '@hemia/network-services';
+import { randomBytes, createHash } from 'crypto';
+import { injectable } from 'inversify';
+import { CacheService } from '@hemia/cache-manager';
+
+/******************************************************************************
+Copyright (c) Microsoft Corporation.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+***************************************************************************** */
+/* global Reflect, Promise, SuppressedError, Symbol, Iterator */
+
+
+function __decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+
+function __param(paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+}
+
+function __metadata(metadataKey, metadataValue) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(metadataKey, metadataValue);
+}
+
+typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+};
+
+class SessionError extends Error {
+    constructor(message, code, redirectTo) {
+        super(message);
+        this.code = code;
+        this.redirectTo = redirectTo;
+        this.name = this.constructor.name;
+        Error.captureStackTrace(this, this.constructor);
+    }
+}
+class SessionNotFoundError extends SessionError {
+    constructor(message = 'Sesión no encontrada') {
+        super(message, 'SESSION_NOT_FOUND', '/?session=required');
+    }
+}
+class SessionExpiredError extends SessionError {
+    constructor(message = 'Sesión expirada') {
+        super(message, 'SESSION_EXPIRED', '/session-expired?session=expired');
+    }
+}
+class SessionInvalidError extends SessionError {
+    constructor(message = 'Sesión inválida') {
+        super(message, 'SESSION_INVALID', '/?session=invalid');
+    }
+}
+class TokenRefreshFailedError extends SessionError {
+    constructor(message = 'Error al renovar tokens') {
+        super(message, 'TOKEN_REFRESH_FAILED', '/session-expired?session=expired');
+    }
+}
+class InvalidTokenFormatError extends SessionError {
+    constructor(message = 'Formato de token inválido') {
+        super(message, 'INVALID_TOKEN_FORMAT', '/?session=invalid');
+    }
+}
+
+/**
+ * Controller Abstracto Reutilizable
+ * Gestiona automáticamente Login, Callback, Me y Logout.
+ */
+class AbstractAuthController {
+    constructor(authService) {
+        this.authService = authService;
+    }
+    async login(req, res) {
+        try {
+            const autoParam = typeof req.query.auto === 'string' ? req.query.auto : 'false';
+            const { loginUrl, tempState } = this.authService.generateLoginParams(autoParam);
+            res.cookie('auth_flow', JSON.stringify(tempState), {
+                httpOnly: true,
+                secure: process.env.NODE_ENV === 'production',
+                maxAge: 300000 // 5 min
+            });
+            res.redirect(loginUrl);
+        }
+        catch (error) {
+            console.error('Login Error:', error);
+            res.status(500).send('Login initialization failed');
+        }
+    }
+    async callback(req, res) {
+        try {
+            const { code, state } = req.query;
+            const authFlowCookie = req.cookies['auth_flow'];
+            if (!authFlowCookie) {
+                res.status(400).send('Missing auth flow cookie');
+                return;
+            }
+            const storedState = JSON.parse(authFlowCookie);
+            const result = await this.authService.handleCallback(code, state, storedState);
+            res.cookie('x-session', result.sessionId, {
+                httpOnly: true,
+                secure: process.env.NODE_ENV === 'production',
+                sameSite: 'lax',
+                maxAge: result.expiresIn * 1000,
+                path: '/'
+            });
+            res.clearCookie('auth_flow');
+            res.redirect(result.redirectUrl);
+        }
+        catch (error) {
+            console.error('Callback Error:', error);
+            if (error instanceof HttpError) {
+                res.status(error.statusCode).json({
+                    success: false,
+                    message: error.message,
+                    error: error.error
+                });
+                return;
+            }
+            res.status(500).json({
+                success: false,
+                message: 'Failed to complete authentication',
+                error: error.message
+            });
+        }
+    }
+    async me(req, res) {
+        const sessionId = req.cookies['x-session'];
+        if (!sessionId) {
+            return res.status(401).json({
+                success: false,
+                message: 'No session found',
+                data: {
+                    redirect_to: '/?session=required'
+                },
+                error: {
+                    message: 'Session is missing',
+                    code: 'SESSION_MISSING'
+                }
+            });
+        }
+        try {
+            const result = await this.authService.getSessionUser(sessionId);
+            return res.status(200).json({
+                success: true,
+                data: result
+            });
+        }
+        catch (error) {
+            res.clearCookie('x-session', {
+                httpOnly: true,
+                secure: process.env.NODE_ENV === 'production',
+                sameSite: 'lax',
+            });
+            if (error instanceof SessionError) {
+                return res.status(401).json({
+                    success: false,
+                    message: error.message,
+                    data: {
+                        redirect_to: error.redirectTo || '/login'
+                    },
+                    error: {
+                        message: error.message,
+                        code: error.code
+                    }
+                });
+            }
+            else {
+                return res.status(500).json({
+                    success: false,
+                    message: 'Failed to retrieve session user',
+                    error: error.message
+                });
+            }
+        }
+    }
+    async logout(req, res) {
+        const sessionId = req.cookies['x-session'];
+        if (sessionId) {
+            await this.authService.logout(sessionId);
+        }
+        res.clearCookie('x-session', {
+            httpOnly: true,
+            secure: process.env.NODE_ENV === 'production',
+            sameSite: 'lax',
+        });
+        return res.status(200).json({ success: true });
+    }
+}
+__decorate([
+    Get('/login'),
+    __param(0, Req()),
+    __param(1, Res()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], AbstractAuthController.prototype, "login", null);
+__decorate([
+    Get('/callback'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], AbstractAuthController.prototype, "callback", null);
+__decorate([
+    Get('/me'),
+    __param(0, Req()),
+    __param(1, Res()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], AbstractAuthController.prototype, "me", null);
+__decorate([
+    Post('/logout'),
+    __param(0, Req()),
+    __param(1, Res()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], AbstractAuthController.prototype, "logout", null);
+
+/**
+ * Utilidades para manejo de PKCE y codificación Base64URL
+ */
+class Generators {
+    /**
+     * Base64URL Encoding
+     * Reemplaza la implementación manual con Buffer de Node.js
+     */
+    static base64urlEncode(strOrBuffer) {
+        const buffer = Buffer.isBuffer(strOrBuffer)
+            ? strOrBuffer
+            : Buffer.from(strOrBuffer);
+        return buffer
+            .toString('base64')
+            .replace(/\+/g, '-')
+            .replace(/\//g, '_')
+            .replace(/=+$/, '');
+    }
+    /**
+     * Genera un Code Verifier para el flujo PKCE (OAuth 2.0).
+     * Crea una cadena aleatoria de 43 a 128 caracteres, codificada en Base64URL.
+     */
+    static generateCodeVerifier() {
+        const buffer = randomBytes(32);
+        return this.base64urlEncode(buffer);
+    }
+    /**
+     * Generate Code Challenge (SHA-256)
+     */
+    static generateCodeChallenge(verifier) {
+        const hash = createHash('sha256')
+            .update(verifier)
+            .digest();
+        return this.base64urlEncode(hash);
+    }
+    /**
+     * Genera un estado aleatorio para la protección CSRF.
+     */
+    static state() {
+        const buffer = randomBytes(16);
+        return this.base64urlEncode(buffer);
+    }
+}
+
+let AuthCacheService = class AuthCacheService {
+    constructor(cacheClient) {
+        this.cacheClient = cacheClient;
+    }
+    async set(key, value, ttlSeconds) {
+        await this.cacheClient.setObject(key, value, ttlSeconds);
+    }
+    async get(key) {
+        return await this.cacheClient.getObject(key);
+    }
+    async delete(key) {
+        await this.cacheClient.deleteKey(key);
+    }
+};
+AuthCacheService = __decorate([
+    injectable(),
+    __metadata("design:paramtypes", [CacheService])
+], AuthCacheService);
+
+let AuthService = class AuthService {
+    constructor(config, storage, jwtManager) {
+        this.config = config;
+        this.storage = storage;
+        this.jwtManager = jwtManager;
+        this.networkServices = new HMNetworkServices(this.config.ssoBaseUrl);
+    }
+    /**
+     * Genera los parámetros necesarios para iniciar el login SSO
+     * @param auto
+     * @returns
+     */
+    generateLoginParams(auto = 'false') {
+        const codeVerifier = Generators.generateCodeVerifier();
+        const codeChallenge = Generators.generateCodeChallenge(codeVerifier);
+        const state = Generators.state();
+        const params = new URLSearchParams({
+            response_type: 'code',
+            client_id: this.config.clientId,
+            redirect_uri: this.config.redirectUri,
+            state: state,
+            code_challenge: codeChallenge,
+            code_challenge_method: 'S256',
+            auto: auto
+        });
+        const loginUrl = `${this.config.ssoBaseUrl}${this.config.ssoAuthUrl}?${params.toString()}`;
+        const tempState = {
+            state,
+            codeVerifier
+        };
+        return {
+            loginUrl,
+            tempState
+        };
+    }
+    /**
+     * Maneja el callback del SSO, intercambiando el código por tokens y creando la sesión.
+     * @param code Código de autorización recibido del SSO
+     * @param incomingState Estado recibido del SSO
+     * @param storedState Estado temporal almacenado antes de redirigir al SSO
+     * @returns Información de la sesión creada
+     */
+    async handleCallback(code, incomingState, storedState) {
+        if (incomingState !== storedState.state) {
+            throw new BadRequestError('Invalid state parameter', 'invalid_state');
+        }
+        try {
+            const response = await this.networkServices.post(this.config.ssoTokenEndpoint, {
+                grantType: 'authorization_code',
+                clientId: this.config.clientId,
+                clientSecret: this.config.clientSecret,
+                code,
+                redirectUri: this.config.redirectUri,
+                codeVerifier: storedState.codeVerifier
+            });
+            if (response.status !== 200) {
+                throw new CustomHttpError('Token exchange failed', response.status, 'token_exchange_failed');
+            }
+            if (!response.data.access_token) {
+                throw new InternalServerError('No access token received from SSO', 'invalid_token_response');
+            }
+            const { access_token, refresh_token, id_token, expires_in, session_id } = response.data;
+            const sessionId = randomBytes(16).toString('hex');
+            const sessionData = {
+                accessToken: access_token,
+                refreshToken: refresh_token,
+                idToken: id_token,
+                expiresAt: Date.now() + (expires_in * 1000),
+                createdAt: new Date().toISOString(),
+                ssoSessionId: session_id
+            };
+            await this.storage.set(`x-session:${sessionId}`, sessionData, expires_in);
+            return {
+                sessionId,
+                expiresIn: expires_in,
+                redirectUrl: `${this.config.uiBaseUrl}`
+            };
+        }
+        catch (error) {
+            console.error('Token Exchange Error:', error);
+            throw error;
+        }
+    }
+    /**
+     * Obtiene y valida la sesión del usuario a partir del sessionId.
+     * Si la sesión está cerca de expirar, intenta refrescar los tokens.
+     * @param sessionId Identificador de la sesión
+     * @returns Información del usuario o error si la sesión no es válida
+     */
+    async getSessionUser(sessionId) {
+        const key = `x-session:${sessionId}`;
+        let session = await this.storage.get(key);
+        if (!session) {
+            throw new SessionNotFoundError();
+        }
+        if (session.expiresAt < Date.now()) {
+            throw new SessionExpiredError();
+        }
+        const timeUntilExpiry = session.expiresAt - Date.now();
+        if (timeUntilExpiry < 2 * 60 * 1000) {
+            try {
+                session = await this.refreshTokens(session, sessionId);
+            }
+            catch (error) {
+                throw new TokenRefreshFailedError();
+            }
+        }
+        try {
+            const userData = await this.decodeIdToken(session.idToken);
+            if (!userData) {
+                throw new SessionInvalidError();
+            }
+            return userData;
+        }
+        catch (e) {
+            throw new InvalidTokenFormatError();
+        }
+    }
+    /**
+     * Cierra la sesión del usuario tanto en el SSO como localmente.
+     * @param sessionId Identificador de la sesión
+     */
+    async logout(sessionId) {
+        const key = `x-session:${sessionId}`;
+        const session = await this.storage.get(key);
+        if (session) {
+            try {
+                await this.networkServices.post(this.config.ssoLogoutEndpoint, {
+                    ssoSessionId: session.sessionId
+                });
+            }
+            catch (e) { /* Silent error */ }
+            await this.storage.delete(key);
+        }
+    }
+    /**
+     * Decodifica el ID token para extraer la información del usuario.
+     * @param idToken Token de identificación JWT
+     * @returns Información del usuario o null si no se puede decodificar
+     */
+    async decodeIdToken(idToken) {
+        try {
+            const decode = this.jwtManager.decode(idToken);
+            if (!decode) {
+                return null;
+            }
+            const data = {
+                email: decode.email || '',
+                name: decode.name || '',
+                given_name: decode.given_name,
+                family_name: decode.family_name,
+                picture: decode.picture,
+                ...decode
+            };
+            return data;
+        }
+        catch (error) {
+            throw new Error('Failed to decode ID token');
+        }
+    }
+    /**
+     * Refresca los tokens de la sesión utilizando el refresh token.
+     * @param session Datos actuales de la sesión
+     * @param sessionId Identificador de la sesión
+     * @returns Datos actualizados de la sesión
+     */
+    async refreshTokens(session, sessionId) {
+        const response = await this.networkServices.post(this.config.ssoTokenEndpoint, {
+            grantType: 'refresh_token',
+            clientId: this.config.clientId,
+            clientSecret: this.config.clientSecret,
+            refreshToken: session.refreshToken,
+            sessionId: session.ssoSessionId
+        });
+        const { access_token, refresh_token, id_token, expires_in } = response.data;
+        const updatedSession = {
+            accessToken: access_token,
+            refreshToken: refresh_token || session.refreshToken,
+            idToken: id_token || session.idToken,
+            expiresAt: Date.now() + (expires_in * 1000),
+            sessionId: response.data.session_id || '',
+            createdAt: Date.now().toString()
+        };
+        await this.storage.set(`x-session:${sessionId}`, updatedSession, expires_in);
+        return updatedSession;
+    }
+};
+AuthService = __decorate([
+    injectable(),
+    __metadata("design:paramtypes", [Object, AuthCacheService, Object])
+], AuthService);
+
+const registerAuthSdk = (container, config, cacheService, jwtManager) => {
+    container.bind(AuthService).toDynamicValue(() => {
+        return new AuthService(config, cacheService, jwtManager);
+    }).inSingletonScope();
+};
+
+export { AbstractAuthController, AuthCacheService, AuthService, InvalidTokenFormatError, SessionError, SessionExpiredError, SessionInvalidError, SessionNotFoundError, TokenRefreshFailedError, registerAuthSdk };