valtech-components 2.0.794 → 2.0.795

package/src/lib/services/auth/config.ts

@@ -0,0 +1,87 @@
+import {
+  EnvironmentProviders,
+  InjectionToken,
+  makeEnvironmentProviders,
+  APP_INITIALIZER,
+  inject,
+} from '@angular/core';
+import { provideHttpClient, withInterceptors } from '@angular/common/http';
+import { ValtechAuthConfig } from './types';
+import { authInterceptor } from './interceptor';
+import { AuthService } from './auth.service';
+
+/**
+ * Token de inyección para la configuración de Auth.
+ */
+export const VALTECH_AUTH_CONFIG = new InjectionToken<ValtechAuthConfig>('ValtechAuthConfig');
+
+/**
+ * Configuración por defecto.
+ */
+export const DEFAULT_AUTH_CONFIG: Partial<ValtechAuthConfig> = {
+  authPrefix: '/v2/auth',
+  storagePrefix: 'valtech_auth_',
+  refreshBeforeExpiry: 60,
+  enableTabSync: true,
+  loginRoute: '/login',
+  homeRoute: '/',
+  unauthorizedRoute: '/unauthorized',
+  enableFirebaseIntegration: false,
+  enableDeviceRegistration: false,
+};
+
+/**
+ * Factory para inicializar el AuthService.
+ */
+function initializeAuth(authService: AuthService): () => Promise<void> {
+  return () => authService.initialize();
+}
+
+/**
+ * Provee el servicio de autenticación a la aplicación Angular.
+ *
+ * @param config - Configuración de autenticación
+ * @returns EnvironmentProviders para usar en bootstrapApplication
+ *
+ * @example
+ * ```typescript
+ * // main.ts
+ * import { bootstrapApplication } from '@angular/platform-browser';
+ * import { provideValtechAuth } from 'valtech-components';
+ * import { environment } from './environments/environment';
+ *
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideValtechAuth({
+ *       apiUrl: environment.apiUrl,
+ *       enableFirebaseIntegration: true,
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+export function provideValtechAuth(config: ValtechAuthConfig): EnvironmentProviders {
+  const mergedConfig: ValtechAuthConfig = {
+    ...DEFAULT_AUTH_CONFIG,
+    ...config,
+  };
+
+  return makeEnvironmentProviders([
+    { provide: VALTECH_AUTH_CONFIG, useValue: mergedConfig },
+    provideHttpClient(withInterceptors([authInterceptor])),
+    // Inicializar AuthService al arrancar la app
+    {
+      provide: APP_INITIALIZER,
+      useFactory: initializeAuth,
+      deps: [AuthService],
+      multi: true,
+    },
+  ]);
+}
+
+/**
+ * Provee solo el interceptor (para apps que ya tienen AuthService configurado manualmente).
+ */
+export function provideValtechAuthInterceptor(): EnvironmentProviders {
+  return makeEnvironmentProviders([provideHttpClient(withInterceptors([authInterceptor]))]);
+}

package/src/lib/services/auth/device.service.ts

@@ -0,0 +1,163 @@
+import { Injectable, Inject } from '@angular/core';
+import { HttpClient } from '@angular/common/http';
+import { Observable } from 'rxjs';
+import { map, catchError } from 'rxjs/operators';
+
+import { VALTECH_AUTH_CONFIG } from './config';
+import {
+  ValtechAuthConfig,
+  DeviceInfo,
+  ListDevicesResponse,
+  DeviceActionResult,
+  DeviceActionRequest,
+  DeviceActionResponse,
+  ValidateActionResponse,
+} from './types';
+
+/**
+ * Servicio para gestión de dispositivos del usuario.
+ * Permite listar, aprobar, bloquear y eliminar dispositivos registrados.
+ *
+ * @example
+ * ```typescript
+ * import { DeviceService } from 'valtech-components';
+ *
+ * @Component({...})
+ * export class DevicesPage {
+ *   private deviceService = inject(DeviceService);
+ *
+ *   devices = signal<DeviceInfo[]>([]);
+ *
+ *   async ngOnInit() {
+ *     const devices = await firstValueFrom(this.deviceService.listDevices());
+ *     this.devices.set(devices);
+ *   }
+ *
+ *   async blockDevice(deviceId: string) {
+ *     await firstValueFrom(this.deviceService.blockDevice(deviceId));
+ *     // Recargar lista
+ *   }
+ * }
+ * ```
+ */
+@Injectable({ providedIn: 'root' })
+export class DeviceService {
+  constructor(
+    @Inject(VALTECH_AUTH_CONFIG) private config: ValtechAuthConfig,
+    private http: HttpClient
+  ) {}
+
+  private get baseUrl(): string {
+    return `${this.config.apiUrl}/v2/users/me/devices`;
+  }
+
+  /**
+   * Lista todos los dispositivos registrados del usuario.
+   */
+  listDevices(): Observable<DeviceInfo[]> {
+    return this.http.get<ListDevicesResponse>(this.baseUrl).pipe(
+      map(response => response.devices)
+    );
+  }
+
+  /**
+   * Obtiene información de un dispositivo específico.
+   */
+  getDevice(deviceId: string): Observable<DeviceInfo> {
+    return this.http.get<{ operationId: string; device: DeviceInfo }>(
+      `${this.baseUrl}/${deviceId}`
+    ).pipe(map(response => response.device));
+  }
+
+  /**
+   * Bloquea un dispositivo.
+   * Revoca todas las sesiones activas de ese dispositivo.
+   */
+  blockDevice(deviceId: string): Observable<DeviceActionResult> {
+    return this.http.post<DeviceActionResult>(
+      `${this.baseUrl}/${deviceId}/block`,
+      {}
+    );
+  }
+
+  /**
+   * Aprueba un dispositivo pendiente.
+   * Cambia el estado de pending_approval a active.
+   */
+  approveDevice(deviceId: string): Observable<DeviceActionResult> {
+    return this.http.post<DeviceActionResult>(
+      `${this.baseUrl}/${deviceId}/approve`,
+      {}
+    );
+  }
+
+  /**
+   * Elimina un dispositivo registrado.
+   */
+  deleteDevice(deviceId: string): Observable<DeviceActionResult> {
+    return this.http.delete<DeviceActionResult>(`${this.baseUrl}/${deviceId}`);
+  }
+
+  /**
+   * Valida un token de acción SIN ejecutarlo.
+   * Útil para mostrar confirmación al usuario antes de ejecutar.
+   * Este endpoint NO requiere autenticación.
+   *
+   * @param token Token JWT de acción
+   * @returns Información del token si es válido
+   *
+   * @example
+   * ```typescript
+   * const token = this.route.snapshot.queryParams['token'];
+   * if (token) {
+   *   const validation = await firstValueFrom(this.deviceService.validateAction(token));
+   *   if (validation.valid) {
+   *     // Mostrar confirmación al usuario
+   *     console.log(`Acción: ${validation.actionType}`);
+   *   }
+   * }
+   * ```
+   */
+  validateAction(token: string): Observable<ValidateActionResponse> {
+    return this.http.post<ValidateActionResponse>(
+      `${this.config.apiUrl}/v2/actions/validate`,
+      { token }
+    );
+  }
+
+  /**
+   * Ejecuta una acción de dispositivo desde un token de email.
+   * Este endpoint NO requiere autenticación.
+   * El token viene en la URL del email de alerta de nuevo inicio de sesión.
+   *
+   * @param token Token JWT de acción (24h, un solo uso)
+   *
+   * @example
+   * ```typescript
+   * // En la página de dispositivos, al detectar ?token=xxx en la URL:
+   * const token = this.route.snapshot.queryParams['token'];
+   * if (token) {
+   *   const result = await firstValueFrom(this.deviceService.executeAction(token));
+   *   if (result.success) {
+   *     console.log(`Dispositivo bloqueado, ${result.sessionsRevoked} sesiones cerradas`);
+   *   }
+   * }
+   * ```
+   */
+  executeAction(token: string): Observable<DeviceActionResponse> {
+    // Usa el endpoint unificado de acciones
+    return this.http.post<{ operationId: string; success: boolean; message: string; data?: Record<string, unknown> }>(
+      `${this.config.apiUrl}/v2/actions/execute`,
+      { token }
+    ).pipe(
+      map(response => ({
+        operationId: response.operationId,
+        success: response.success,
+        message: response.message,
+        action: (response.data?.['action'] as string) || 'refuse',
+        deviceId: (response.data?.['deviceId'] as string) || '',
+        sessionsRevoked: response.data?.['sessionsRevoked'] as number | undefined,
+      }))
+    );
+  }
+}

package/src/lib/services/auth/guards.ts

@@ -0,0 +1,234 @@
+import { inject } from '@angular/core';
+import {
+  Router,
+  CanActivateFn,
+  UrlTree,
+  ActivatedRouteSnapshot,
+} from '@angular/router';
+import { AuthService } from './auth.service';
+import { VALTECH_AUTH_CONFIG } from './config';
+
+/**
+ * Guard que verifica si el usuario está autenticado.
+ * Redirige a loginRoute si no está autenticado.
+ *
+ * @example
+ * ```typescript
+ * import { authGuard } from 'valtech-components';
+ *
+ * const routes: Routes = [
+ *   {
+ *     path: 'dashboard',
+ *     canActivate: [authGuard],
+ *     loadComponent: () => import('./dashboard.page'),
+ *   },
+ * ];
+ * ```
+ */
+export const authGuard: CanActivateFn = (): boolean | UrlTree => {
+  const authService = inject(AuthService);
+  const router = inject(Router);
+  const config = inject(VALTECH_AUTH_CONFIG);
+
+  if (authService.isAuthenticated()) {
+    return true;
+  }
+
+  return router.createUrlTree([config.loginRoute]);
+};
+
+/**
+ * Guard que verifica si el usuario NO está autenticado.
+ * Redirige a homeRoute si ya está autenticado.
+ * Útil para páginas de login/registro.
+ *
+ * @example
+ * ```typescript
+ * import { guestGuard } from 'valtech-components';
+ *
+ * const routes: Routes = [
+ *   {
+ *     path: 'login',
+ *     canActivate: [guestGuard],
+ *     loadComponent: () => import('./login.page'),
+ *   },
+ * ];
+ * ```
+ */
+export const guestGuard: CanActivateFn = (): boolean | UrlTree => {
+  const authService = inject(AuthService);
+  const router = inject(Router);
+  const config = inject(VALTECH_AUTH_CONFIG);
+
+  if (!authService.isAuthenticated()) {
+    return true;
+  }
+
+  return router.createUrlTree([config.homeRoute]);
+};
+
+/**
+ * Factory para crear guard de permisos.
+ * Verifica si el usuario tiene el permiso especificado.
+ *
+ * @param permissions - Permiso o lista de permisos requeridos (OR)
+ * @returns Guard function
+ *
+ * @example
+ * ```typescript
+ * import { authGuard, permissionGuard } from 'valtech-components';
+ *
+ * const routes: Routes = [
+ *   {
+ *     path: 'templates',
+ *     canActivate: [authGuard, permissionGuard('templates:read')],
+ *     loadComponent: () => import('./templates.page'),
+ *   },
+ *   {
+ *     path: 'admin',
+ *     canActivate: [authGuard, permissionGuard(['admin:*', 'super_admin'])],
+ *     loadComponent: () => import('./admin.page'),
+ *   },
+ * ];
+ * ```
+ */
+export function permissionGuard(
+  permissions: string | string[]
+): CanActivateFn {
+  return (): boolean | UrlTree => {
+    const authService = inject(AuthService);
+    const router = inject(Router);
+    const config = inject(VALTECH_AUTH_CONFIG);
+
+    const permArray = Array.isArray(permissions) ? permissions : [permissions];
+
+    if (authService.hasAnyPermission(permArray)) {
+      return true;
+    }
+
+    console.warn(
+      `[ValtechAuth] Permiso denegado. Requerido: ${permArray.join(' o ')}`
+    );
+    return router.createUrlTree([config.unauthorizedRoute]);
+  };
+}
+
+/**
+ * Guard que lee permisos desde route.data.
+ * Permite configurar permisos directamente en la definición de rutas.
+ *
+ * @example
+ * ```typescript
+ * import { authGuard, permissionGuardFromRoute } from 'valtech-components';
+ *
+ * const routes: Routes = [
+ *   {
+ *     path: 'admin/users',
+ *     canActivate: [authGuard, permissionGuardFromRoute],
+ *     data: {
+ *       permissions: ['users:read', 'users:manage'],
+ *       requireAll: false  // true = AND, false = OR (default)
+ *     },
+ *     loadComponent: () => import('./users.page'),
+ *   },
+ * ];
+ * ```
+ */
+export const permissionGuardFromRoute: CanActivateFn = (
+  route: ActivatedRouteSnapshot
+): boolean | UrlTree => {
+  const authService = inject(AuthService);
+  const router = inject(Router);
+  const config = inject(VALTECH_AUTH_CONFIG);
+
+  const permissions = route.data['permissions'] as string[] | undefined;
+  const requireAll = route.data['requireAll'] as boolean | undefined;
+
+  if (!permissions || permissions.length === 0) {
+    return true;
+  }
+
+  const hasAccess = requireAll
+    ? authService.hasAllPermissions(permissions)
+    : authService.hasAnyPermission(permissions);
+
+  if (hasAccess) {
+    return true;
+  }
+
+  console.warn(
+    `[ValtechAuth] Permiso denegado. Requerido: ${permissions.join(
+      requireAll ? ' y ' : ' o '
+    )}`
+  );
+  return router.createUrlTree([config.unauthorizedRoute]);
+};
+
+/**
+ * Guard que verifica si el usuario es super admin.
+ *
+ * @example
+ * ```typescript
+ * import { authGuard, superAdminGuard } from 'valtech-components';
+ *
+ * const routes: Routes = [
+ *   {
+ *     path: 'super-admin',
+ *     canActivate: [authGuard, superAdminGuard],
+ *     loadComponent: () => import('./super-admin.page'),
+ *   },
+ * ];
+ * ```
+ */
+export const superAdminGuard: CanActivateFn = (): boolean | UrlTree => {
+  const authService = inject(AuthService);
+  const router = inject(Router);
+  const config = inject(VALTECH_AUTH_CONFIG);
+
+  if (authService.isSuperAdmin()) {
+    return true;
+  }
+
+  console.warn('[ValtechAuth] Acceso de super admin requerido');
+  return router.createUrlTree([config.unauthorizedRoute]);
+};
+
+/**
+ * Guard que verifica si el usuario tiene un rol específico.
+ *
+ * @param roles - Rol o lista de roles requeridos (OR)
+ * @returns Guard function
+ *
+ * @example
+ * ```typescript
+ * import { authGuard, roleGuard } from 'valtech-components';
+ *
+ * const routes: Routes = [
+ *   {
+ *     path: 'editor',
+ *     canActivate: [authGuard, roleGuard(['editor', 'admin'])],
+ *     loadComponent: () => import('./editor.page'),
+ *   },
+ * ];
+ * ```
+ */
+export function roleGuard(roles: string | string[]): CanActivateFn {
+  return (): boolean | UrlTree => {
+    const authService = inject(AuthService);
+    const router = inject(Router);
+    const config = inject(VALTECH_AUTH_CONFIG);
+
+    const roleArray = Array.isArray(roles) ? roles : [roles];
+
+    const hasRole = roleArray.some((role) => authService.hasRole(role));
+
+    if (hasRole) {
+      return true;
+    }
+
+    console.warn(
+      `[ValtechAuth] Rol requerido: ${roleArray.join(' o ')}`
+    );
+    return router.createUrlTree([config.unauthorizedRoute]);
+  };
+}

package/src/lib/services/auth/handoff.service.ts

@@ -0,0 +1,225 @@
+import { HttpClient } from '@angular/common/http';
+import { Inject, Injectable } from '@angular/core';
+import { Router } from '@angular/router';
+import { firstValueFrom, Observable } from 'rxjs';
+import { catchError, tap } from 'rxjs/operators';
+
+import { AuthService } from './auth.service';
+import { VALTECH_AUTH_CONFIG } from './config';
+import { ValtechAuthConfig } from './types';
+
+/**
+ * Name of the query param that carries the handoff token. Apps may override
+ * via `detectAndExchangeHandoff({ tokenParam })` but the default keeps the
+ * convention consistent across the factory.
+ */
+export const HANDOFF_TOKEN_PARAM = 'handoff';
+
+/**
+ * Name of the query param that carries the post-exchange route.
+ */
+export const HANDOFF_ROUTE_PARAM = 'route';
+
+/**
+ * Options for `HandoffService.detectAndExchangeHandoff`.
+ */
+export interface DetectAndExchangeOptions {
+  /** Override the query param name. Default: `'handoff'`. */
+  tokenParam?: string;
+  /** Override the route param name. Default: `'route'`. */
+  routeParam?: string;
+  /** Where to navigate if no route param is present. Default: `'/'`. */
+  defaultRoute?: string;
+  /** Where to navigate on exchange error. Default: app's configured `loginRoute`. */
+  errorRoute?: string;
+}
+
+/**
+ * Request body for `POST /v2/auth/handoff`.
+ *
+ * Both fields are optional and stored for audit only — the exchange step
+ * does not enforce that the redeeming app matches `targetAppId`.
+ */
+export interface HandoffCreateRequest {
+  /** Target app the handoff is intended for (e.g. `"myvaltech"`). Audit-only. */
+  targetAppId?: string;
+  /** Route the target app should navigate to after exchange. Echoed back. */
+  route?: string;
+}
+
+/**
+ * Response body from `POST /v2/auth/handoff`.
+ */
+export interface HandoffCreateResponse {
+  operationId: string;
+  /** Raw token to embed in the redirect URL as `?handoff=<token>`. 30s TTL, single-use. */
+  token: string;
+  /** RFC3339 expiration timestamp. */
+  expiresAt: string;
+  /** Echoed `route` from the request, when provided. */
+  route?: string;
+  /**
+   * Absolute base URL of the target app (e.g. `"https://sigify.com"`).
+   *
+   * When present, callers should use this as the destination for the redirect.
+   * Backend resolves it from the `app-config` table (single source of truth).
+   *
+   * Optional for backward compatibility — when missing, callers may fall back
+   * to a client-side `appUrls` mapping.
+   */
+  targetBaseUrl?: string;
+}
+
+/**
+ * Response body from `POST /v2/auth/handoff/exchange`.
+ *
+ * Same shape as `SigninResponse` — installable via `AuthService.setExternalAuth`.
+ */
+export interface HandoffExchangeResponse {
+  operationId: string;
+  accessToken: string;
+  refreshToken: string;
+  firebaseToken?: string;
+  expiresIn: number;
+  tokenType: string;
+  userId: string;
+}
+
+/**
+ * HandoffService — cross-app session transfer.
+ *
+ * Implements the OAuth Authorization Code pattern, applied internally between
+ * apps that share the same backend.
+ *
+ * **Origin app (user is authenticated):**
+ *
+ * ```typescript
+ * const { token, route } = await firstValueFrom(
+ *   handoff.createHandoff({ targetAppId: 'myvaltech', route: '/app/dashboard' })
+ * );
+ * window.location.href = `https://myvaltech.app/?handoff=${token}&route=${encodeURIComponent(route ?? '/')}`;
+ * ```
+ *
+ * **Target app (boot):** call `exchangeHandoff(token)`. On success, the session
+ * is installed (`AuthService.setExternalAuth`) and the user is authenticated.
+ * See `detectAndExchangeHandoff` helper for the typical bootstrap pattern.
+ *
+ * Security notes:
+ * - Token is single-use and short-lived (30s) — enforced server-side.
+ * - Token in URL must be removed from history after exchange to avoid log leakage.
+ * - The exchange endpoint is public; do NOT add auth header. The
+ *   `HttpClient` request below avoids triggering the auth interceptor since the
+ *   user isn't logged in yet on the target app.
+ */
+@Injectable({ providedIn: 'root' })
+export class HandoffService {
+  private detected = false;
+
+  constructor(
+    @Inject(VALTECH_AUTH_CONFIG) private config: ValtechAuthConfig,
+    private http: HttpClient,
+    private auth: AuthService,
+    private router: Router
+  ) {}
+
+  /**
+   * Create a handoff token. Caller must be authenticated.
+   *
+   * @param request Optional metadata: target app id and intended route.
+   * @returns Observable emitting `{ token, expiresAt, route? }`.
+   */
+  createHandoff(request: HandoffCreateRequest = {}): Observable<HandoffCreateResponse> {
+    return this.http.post<HandoffCreateResponse>(`${this.baseUrl}/handoff`, request);
+  }
+
+  /**
+   * Exchange a handoff token for a session and install it.
+   *
+   * On success, the response is piped through `AuthService.setExternalAuth`
+   * so the user becomes authenticated. Subsequent navigation can proceed.
+   *
+   * On failure, the observable errors. The caller is responsible for
+   * showing an error and routing to `/login`.
+   *
+   * @param token Raw handoff token read from the URL.
+   */
+  exchangeHandoff(token: string): Observable<HandoffExchangeResponse> {
+    return this.http
+      .post<HandoffExchangeResponse>(`${this.baseUrl}/handoff/exchange`, { token })
+      .pipe(
+        tap(response => this.installSession(response)),
+        catchError(err => {
+          // Surface the error untouched — the caller decides how to react
+          // (typically: redirect to /login + toast). Don't install a bad session.
+          throw err;
+        })
+      );
+  }
+
+  /**
+   * Bootstrap helper — reads the handoff token from the current URL, exchanges
+   * it for a session, and navigates to the intended route with the token
+   * stripped from history.
+   *
+   * Idempotent: subsequent calls are no-ops. Wire from an
+   * `APP_INITIALIZER`/`provideAppInitializer` factory in `main.ts`.
+   *
+   * ```typescript
+   * // main.ts
+   * provideAppInitializer(() => inject(HandoffService).detectAndExchangeHandoff())
+   * ```
+   *
+   * On error (expired/used/invalid token), redirects to `errorRoute` (default:
+   * the app's configured `loginRoute`). The URL is always cleaned, even on
+   * error, so the token cannot be retried by refreshing the page.
+   *
+   * @returns `true` if a handoff was detected and processed (success or fail).
+   *          `false` if no token was present (cold boot, normal flow).
+   */
+  async detectAndExchangeHandoff(options: DetectAndExchangeOptions = {}): Promise<boolean> {
+    if (this.detected || typeof window === 'undefined') {
+      return false;
+    }
+    this.detected = true;
+
+    const tokenParam = options.tokenParam ?? HANDOFF_TOKEN_PARAM;
+    const routeParam = options.routeParam ?? HANDOFF_ROUTE_PARAM;
+    const defaultRoute = options.defaultRoute ?? '/';
+    const errorRoute = options.errorRoute ?? this.config.loginRoute ?? '/login';
+
+    const params = new URLSearchParams(window.location.search);
+    const token = params.get(tokenParam);
+    if (!token) {
+      return false;
+    }
+
+    const targetRoute = params.get(routeParam) || defaultRoute;
+
+    try {
+      await firstValueFrom(this.exchangeHandoff(token));
+      await this.router.navigateByUrl(targetRoute, { replaceUrl: true });
+    } catch (err) {
+      console.warn('[Handoff] Exchange failed, redirecting to login', err);
+      await this.router.navigateByUrl(errorRoute, { replaceUrl: true });
+    }
+
+    return true;
+  }
+
+  /**
+   * Persist the session in `AuthService`. Mirrors the install flow used by
+   * the normal signin path so timers, Firebase, and tab-sync all kick in.
+   */
+  private installSession(response: HandoffExchangeResponse): void {
+    this.auth.setExternalAuth({
+      accessToken: response.accessToken,
+      refreshToken: response.refreshToken,
+      firebaseToken: response.firebaseToken,
+      expiresIn: response.expiresIn,
+    });
+  }
+
+  private get baseUrl(): string {
+    return `${this.config.apiUrl}${this.config.authPrefix}`;
+  }
+}