@angular-helpers/security 21.1.0 → 21.3.0

package/README.es.md

@@ -4,7 +4,11 @@
 
 # Angular Security Helpers
 
-Paquete de seguridad para aplicaciones Angular que previene ataques comunes como ReDoS (Regular Expression Denial of Service) usando Web Workers para ejecución segura.
+Paquete de seguridad para aplicaciones Angular que previene ataques comunes como ReDoS (Regular Expression Denial of Service), XSS, y proporciona utilidades criptográficas usando Web Workers y Web Crypto API para ejecución segura.
+
+> **Versión**: 21.2.0 — [CHANGELOG](./CHANGELOG.md)
+
+---
 
 ## 🛡️ Características
 
@@ -18,9 +22,63 @@ Paquete de seguridad para aplicaciones Angular que previene ataques comunes como
 ### **Web Crypto API**
 
 - **Cifrado/Descifrado**: Soporte AES-GCM para manejo seguro de datos
+- **Firmas HMAC**: Firmar y verificar datos con HMAC-SHA256/384/512
 - **Hashing**: SHA-256 y otros algoritmos
 - **Gestión de Claves**: Generar, importar y exportar claves criptográficas
 - **Aleatorio Seguro**: Valores aleatorios criptográficamente seguros
+- **Generación UUID**: UUIDs RFC4122 v4
+
+### **Almacenamiento Seguro**
+
+- **Cifrado Transparente**: Almacenamiento cifrado AES-GCM sobre localStorage/sessionStorage
+- **Modo Efímero**: Claves en memoria para seguridad de sesión única
+- **Modo Passphrase**: Claves derivadas PBKDF2 para persistencia entre sesiones
+- **Aislamiento por Namespace**: Organiza datos almacenados con prefijos
+
+### **Sanitización de Input**
+
+- **Prevención XSS**: Limpieza de HTML con lista de permitidos
+- **Validación de URLs**: Esquemas de URL seguros
+- **Escape de HTML**: Caracteres especiales para interpolación segura
+- **JSON Seguro**: Parseo seguro sin eval
+
+### **Fuerza de Contraseña**
+
+- **Puntuación basada en Entropía**: Calcular fuerza en bits de entropía
+- **Detección de Contraseñas Comunes**: Bloquear contraseñas débiles conocidas
+- **Detección de Patrones**: Detectar patrones de teclado y secuencias
+- **Feedback Accionable**: Sugerencias específicas para mejorar
+
+### **Validators de Formularios (sub-entries)**
+
+- **`@angular-helpers/security/forms`**: puente para Reactive Forms — `SecurityValidators.strongPassword`, `safeHtml`, `safeUrl`, `noScriptInjection`, `noSqlInjectionHints`.
+- **`@angular-helpers/security/signal-forms`**: puente para Signal Forms de Angular v21 — `strongPassword`, `safeHtml`, `safeUrl`, `noScriptInjection`, `noSqlInjectionHints`, y el async `hibpPassword`.
+- **Core compartido**: ambos paradigmas delegan en los mismos helpers puros para garantizar paridad de comportamiento.
+
+### **Inspección de JWT**
+
+- **Decodificación client-side**: `decode`, `claim`, `isExpired`, `expiresIn`.
+- **Explícitamente NO verifica firma**: la validación criptográfica se hace server-side.
+
+### **Protección CSRF**
+
+- **`CsrfService`**: double-submit con tokens generados por `WebCryptoService.generateRandomBytes`.
+- **`withCsrfHeader()`**: interceptor funcional que inyecta el header en POST/PUT/PATCH/DELETE.
+
+### **Rate Limiter**
+
+- **Token-bucket** y **sliding-window**, configurables por clave.
+- **Estado basado en signals**: `canExecute(key)` y `remaining(key)` devuelven `Signal<T>`.
+
+### **HIBP Leaked Password Check**
+
+- **k-anonymity**: sólo los primeros 5 caracteres hex del SHA-1 salen del navegador.
+- **Fail-open**: los errores de red nunca bloquean el envío del formulario.
+
+### **Clipboard Sensible**
+
+- **Auto-clear verificado**: lee el clipboard antes de limpiar para no pisar contenido ajeno.
+- **Estilo password-manager**: default 15 segundos, configurable.
 
 ### **Patrón Builder**
 
@@ -44,7 +102,16 @@ import { provideSecurity } from '@angular-helpers/security';
 bootstrapApplication(AppComponent, {
   providers: [
     provideSecurity({
+      // Servicios core (habilitados por defecto)
       enableRegexSecurity: true,
+      enableWebCrypto: true,
+
+      // Nuevos servicios (opt-in, deshabilitados por defecto)
+      enableSecureStorage: true,
+      enableInputSanitizer: true,
+      enablePasswordStrength: true,
+
+      // Configuración global
       defaultTimeout: 5000,
       safeMode: false,
     }),
@@ -52,6 +119,27 @@ bootstrapApplication(AppComponent, {
 });
 ```
 
+### **Providers Individuales**
+
+```typescript
+import {
+  provideRegexSecurity,
+  provideWebCrypto,
+  provideSecureStorage,
+  provideInputSanitizer,
+  providePasswordStrength,
+} from '@angular-helpers/security';
+
+// Usar solo los servicios que necesites
+bootstrapApplication(AppComponent, {
+  providers: [
+    provideSecureStorage({ storage: 'session', pbkdf2Iterations: 600_000 }),
+    provideInputSanitizer({ allowedTags: ['b', 'i', 'em', 'strong'] }),
+    providePasswordStrength(),
+  ],
+});
+```
+
 ### **Inyección de Servicios**
 
 ```typescript
@@ -142,9 +230,276 @@ export class SecureStorageComponent {
   generateUUID(): string {
     return this.cryptoService.randomUUID();
   }
+
+  async signAndVerify(data: string): Promise<boolean> {
+    // Generar clave HMAC para SHA-256
+    const key = await this.cryptoService.generateHmacKey('HMAC-SHA-256');
+
+    // Firmar los datos
+    const signature = await this.cryptoService.sign(key, data);
+
+    // Verificar la firma
+    return await this.cryptoService.verify(key, data, signature);
+  }
 }
 ```
 
+### **SecureStorageService — Almacenamiento Cifrado**
+
+```typescript
+import { SecureStorageService } from '@angular-helpers/security';
+
+export class UserSettingsComponent {
+  private storage = inject(SecureStorageService);
+
+  async saveUserToken(token: string): Promise<void> {
+    // Modo efímero (por defecto): datos sobreviven solo esta sesión
+    await this.storage.set('authToken', { token, createdAt: Date.now() });
+  }
+
+  async getUserToken(): Promise<{ token: string; createdAt: number } | null> {
+    return await this.storage.get<{ token: string; createdAt: number }>('authToken');
+  }
+
+  async initWithPassphrase(passphrase: string): Promise<void> {
+    // Modo passphrase: datos sobreviven recargas de página
+    await this.storage.initWithPassphrase(passphrase);
+  }
+
+  async saveWithNamespace(userId: string, data: unknown): Promise<void> {
+    // Aislamiento por namespace
+    await this.storage.set('profile', data, `user:${userId}`);
+  }
+
+  clearUserData(userId: string): void {
+    // Limpiar solo los datos de este usuario
+    this.storage.clear(`user:${userId}`);
+  }
+}
+```
+
+### **InputSanitizerService — Prevención XSS**
+
+```typescript
+import { InputSanitizerService } from '@angular-helpers/security';
+
+export class CommentComponent {
+  private sanitizer = inject(InputSanitizerService);
+
+  sanitizeUserComment(html: string): string {
+    // Limpiar tags peligrosos, mantener seguros (b, i, em, a, etc.)
+    return this.sanitizer.sanitizeHtml(html);
+    // Ejemplo: '<b>Hola</b><script>alert(1)</script>' → '<b>Hola</b>'
+  }
+
+  validateUserLink(url: string): string | null {
+    // Solo permitir URLs http/https
+    return this.sanitizer.sanitizeUrl(url);
+    // Ejemplo: 'javascript:alert(1)' → null
+    // Ejemplo: 'https://example.com' → 'https://example.com/'
+  }
+
+  escapeForDisplay(text: string): string {
+    // Seguro para nodos de texto HTML
+    return this.sanitizer.escapeHtml(text);
+    // Ejemplo: '<b>hola</b>' → '&lt;b&gt;hola&lt;/b&gt;'
+  }
+
+  parseUserJson(json: string): unknown | null {
+    // Parseo seguro de JSON sin eval
+    return this.sanitizer.sanitizeJson(json);
+  }
+}
+```
+
+### **PasswordStrengthService — Evaluación de Contraseñas**
+
+```typescript
+import { PasswordStrengthService } from '@angular-helpers/security';
+
+export class RegistrationComponent {
+  private passwordStrength = inject(PasswordStrengthService);
+
+  checkPasswordStrength(password: string): void {
+    const result = this.passwordStrength.assess(password);
+
+    console.log(`Score: ${result.score}/4`); // 0-4
+    console.log(`Label: ${result.label}`); // 'very-weak' a 'very-strong'
+    console.log(`Entropía: ${result.entropy} bits`); // entropía calculada
+    console.log('Feedback:', result.feedback); // sugerencias de mejora
+
+    // Ejemplos de resultados:
+    // 'password' → score: 0, label: 'very-weak', feedback: ['Contraseña común']
+    // 'P@ssw0rd!' → score: 2, label: 'fair', feedback: ['Evita patrones de teclado']
+    // 'xK#9mZ$vLq2@rBnT7' → score: 4, label: 'very-strong', feedback: []
+  }
+}
+```
+
+### **SecurityValidators — Reactive Forms**
+
+```typescript
+import { FormControl, FormGroup, Validators } from '@angular/forms';
+import { SecurityValidators } from '@angular-helpers/security/forms';
+
+export class SignupFormComponent {
+  form = new FormGroup({
+    password: new FormControl('', [
+      Validators.required,
+      SecurityValidators.strongPassword({ minScore: 3 }),
+    ]),
+    bio: new FormControl('', [SecurityValidators.safeHtml()]),
+    homepage: new FormControl('', [SecurityValidators.safeUrl({ schemes: ['https:'] })]),
+  });
+}
+```
+
+Los validators son factory functions estáticas — no hace falta registrar providers. Delegan en los
+mismos helpers puros que usa la versión Signal Forms, así que ambos paradigmas devuelven resultados
+equivalentes para el mismo input.
+
+### **Validators para Signal Forms**
+
+```typescript
+import { signal } from '@angular/core';
+import { form, required } from '@angular/forms/signals';
+import {
+  strongPassword,
+  hibpPassword,
+  safeHtml,
+  safeUrl,
+} from '@angular-helpers/security/signal-forms';
+
+export class SignupSignalFormsComponent {
+  model = signal({ email: '', password: '', bio: '', homepage: '' });
+
+  f = form(this.model, (p) => {
+    required(p.email);
+    required(p.password);
+    strongPassword(p.password, { minScore: 3 });
+    hibpPassword(p.password); // async — valida contra HIBP
+    safeHtml(p.bio);
+    safeUrl(p.homepage, { schemes: ['https:'] });
+  });
+}
+```
+
+**Requisito del sub-entry**: instalar `@angular/forms`. El entry principal
+`@angular-helpers/security` no depende de `@angular/forms`.
+
+**Regla HIBP async**: `hibpPassword` requiere `provideHibp()` en la jerarquía del inyector. Falla
+en modo open — errores de red nunca bloquean el submit del formulario.
+
+### **JwtService — Inspección Client-Side**
+
+```typescript
+import { JwtService } from '@angular-helpers/security';
+
+export class SessionGuard {
+  private jwt = inject(JwtService);
+
+  isAuthenticated(): boolean {
+    const token = localStorage.getItem('access_token');
+    if (!token) return false;
+    return !this.jwt.isExpired(token, 30); // 30 segundos de leeway
+  }
+
+  currentUserId(): string | null {
+    const token = localStorage.getItem('access_token');
+    return token ? this.jwt.claim<string>(token, 'sub') : null;
+  }
+}
+```
+
+> **Nota de seguridad**: `JwtService` sólo decodifica payloads para inspección. **Nunca** confíes
+> en el contenido para decisiones de autorización — la verificación de la firma va siempre
+> server-side.
+
+### **CsrfService + `withCsrfHeader()`**
+
+```typescript
+import { bootstrapApplication } from '@angular/platform-browser';
+import { provideHttpClient, withInterceptors } from '@angular/common/http';
+import { provideSecurity, CsrfService, withCsrfHeader } from '@angular-helpers/security';
+
+bootstrapApplication(App, {
+  providers: [
+    provideSecurity({ enableCsrf: true }),
+    provideHttpClient(withInterceptors([withCsrfHeader()])),
+  ],
+});
+
+// Tras el login:
+const csrf = inject(CsrfService);
+csrf.storeToken(response.csrfToken);
+// A partir de ahora, todas las requests POST/PUT/PATCH/DELETE llevan X-CSRF-Token.
+```
+
+### **RateLimiterService**
+
+```typescript
+import { RateLimiterService, RateLimitExceededError } from '@angular-helpers/security';
+
+export class SearchComponent {
+  private rateLimiter = inject(RateLimiterService);
+
+  constructor() {
+    this.rateLimiter.configure('search', {
+      type: 'token-bucket',
+      capacity: 5,
+      refillPerSecond: 1,
+    });
+  }
+
+  canSearch = this.rateLimiter.canExecute('search'); // Signal<boolean>
+  remaining = this.rateLimiter.remaining('search'); // Signal<number>
+
+  async search(query: string) {
+    try {
+      await this.rateLimiter.consume('search');
+      return this.api.search(query);
+    } catch (err) {
+      if (err instanceof RateLimitExceededError) {
+        // Mostrar countdown usando err.retryAfterMs
+      }
+    }
+  }
+}
+```
+
+### **HibpService**
+
+```typescript
+import { HibpService } from '@angular-helpers/security';
+
+export class RegistrationComponent {
+  private hibp = inject(HibpService);
+
+  async checkPassword(password: string) {
+    const { leaked, count, error } = await this.hibp.isPasswordLeaked(password);
+    if (error) return; // fail-open en errores de red
+    if (leaked) alert(`Esta contraseña apareció en ${count} brechas.`);
+  }
+}
+```
+
+### **SensitiveClipboardService**
+
+```typescript
+import { SensitiveClipboardService } from '@angular-helpers/security';
+
+export class ApiKeyPanel {
+  private sensitiveClipboard = inject(SensitiveClipboardService);
+
+  async copy(value: string) {
+    await this.sensitiveClipboard.copy(value, { clearAfterMs: 15_000 });
+  }
+}
+```
+
+El servicio lee el clipboard antes de limpiarlo y omite el clear si el contenido ya no coincide con
+lo que escribió — así evita pisar copias que el usuario haya hecho en otra parte.
+
 ## 📊 Niveles de Riesgo
 
 | Nivel          | Descripción          | Acción                                   |

package/README.md

@@ -45,6 +45,37 @@ Security package for Angular applications that prevents common attacks like ReDo
 - **Common Password Check**: Blocks frequently used passwords
 - **Feedback Messages**: Actionable improvement suggestions
 
+### **Forms Validators (sub-entries)**
+
+- **`@angular-helpers/security/forms`**: Reactive Forms bridge — `SecurityValidators.strongPassword`, `safeHtml`, `safeUrl`, `noScriptInjection`, `noSqlInjectionHints`.
+- **`@angular-helpers/security/signal-forms`**: Angular v21 Signal Forms bridge — `strongPassword`, `safeHtml`, `safeUrl`, `noScriptInjection`, `noSqlInjectionHints`, and async `hibpPassword`.
+- **Shared core**: both paradigms delegate to the same pure helpers for guaranteed behavioural parity.
+
+### **JWT Inspection**
+
+- **Client-side decode**: `decode`, `claim`, `isExpired`, `expiresIn`.
+- **Explicit non-verifying**: signature validation must happen server-side.
+
+### **CSRF Protection**
+
+- **`CsrfService`**: double-submit token helper backed by `WebCryptoService.generateRandomBytes`.
+- **`withCsrfHeader()`**: functional HTTP interceptor that injects the token on POST/PUT/PATCH/DELETE.
+
+### **Rate Limiter**
+
+- **Token-bucket** and **sliding-window** policies.
+- **Signal-based state**: `canExecute(key)`, `remaining(key)` return `Signal<T>`.
+
+### **HIBP Leaked-Password Check**
+
+- **k-anonymity**: only the first 5 hex chars of SHA-1 leave the browser.
+- **Fail-open**: network errors never block form submissions.
+
+### **Sensitive Clipboard**
+
+- **Verified auto-clear**: reads back the clipboard before clearing to avoid clobbering unrelated content.
+- **Password-manager semantics**: default 15-second clear, configurable.
+
 ### **Builder Pattern**
 
 - **Fluent API**: Intuitively build regular expressions.
@@ -371,6 +402,172 @@ export class RegistrationComponent {
 }
 ```
 
+### **SecurityValidators (Reactive Forms)**
+
+```typescript
+import { FormControl, FormGroup, Validators } from '@angular/forms';
+import { SecurityValidators } from '@angular-helpers/security/forms';
+
+export class SignupFormComponent {
+  form = new FormGroup({
+    password: new FormControl('', [
+      Validators.required,
+      SecurityValidators.strongPassword({ minScore: 3 }),
+    ]),
+    bio: new FormControl('', [SecurityValidators.safeHtml()]),
+    homepage: new FormControl('', [SecurityValidators.safeUrl({ schemes: ['https:'] })]),
+    query: new FormControl('', [
+      SecurityValidators.noScriptInjection(),
+      SecurityValidators.noSqlInjectionHints(),
+    ]),
+  });
+}
+```
+
+The validators are static factory functions — no provider registration required. They delegate to
+shared pure helpers, so the Signal Forms variant below produces equivalent results for the same input.
+
+### **Signal Forms validators**
+
+```typescript
+import { signal } from '@angular/core';
+import { form, required } from '@angular/forms/signals';
+import {
+  strongPassword,
+  hibpPassword,
+  safeHtml,
+  safeUrl,
+} from '@angular-helpers/security/signal-forms';
+
+export class SignupSignalFormsComponent {
+  model = signal({ email: '', password: '', bio: '', homepage: '' });
+
+  f = form(this.model, (p) => {
+    required(p.email);
+    required(p.password);
+    strongPassword(p.password, { minScore: 3 });
+    hibpPassword(p.password); // async — calls HIBP via validateAsync
+    safeHtml(p.bio);
+    safeUrl(p.homepage, { schemes: ['https:'] });
+  });
+}
+```
+
+**Sub-entry requirement**: ensure `@angular/forms` is installed. The main entry has zero runtime
+dependency on `@angular/forms`; only the sub-entries need it.
+
+**Async HIBP rule**: `hibpPassword` requires `provideHibp()` in the injector hierarchy. The rule
+fails open — network errors never block form submission.
+
+### **JwtService**
+
+```typescript
+import { JwtService } from '@angular-helpers/security';
+
+export class SessionGuard {
+  private jwt = inject(JwtService);
+
+  isAuthenticated(): boolean {
+    const token = localStorage.getItem('access_token');
+    if (!token) return false;
+    return !this.jwt.isExpired(token, /* leewaySeconds */ 30);
+  }
+
+  currentUserId(): string | null {
+    const token = localStorage.getItem('access_token');
+    return token ? this.jwt.claim<string>(token, 'sub') : null;
+  }
+}
+```
+
+> **Security note**: `JwtService` decodes payloads for client-side inspection only. **Never** trust
+> the decoded contents for authorization decisions — signature verification must happen server-side.
+
+### **CsrfService + `withCsrfHeader()`**
+
+```typescript
+import { bootstrapApplication } from '@angular/platform-browser';
+import { provideHttpClient, withInterceptors } from '@angular/common/http';
+import { provideSecurity, CsrfService, withCsrfHeader } from '@angular-helpers/security';
+
+bootstrapApplication(App, {
+  providers: [
+    provideSecurity({ enableCsrf: true }),
+    provideHttpClient(withInterceptors([withCsrfHeader()])),
+  ],
+});
+
+// After login:
+const csrf = inject(CsrfService);
+csrf.storeToken(response.csrfToken);
+// Subsequent POST/PUT/PATCH/DELETE requests automatically carry X-CSRF-Token.
+```
+
+### **RateLimiterService**
+
+```typescript
+import { RateLimiterService, RateLimitExceededError } from '@angular-helpers/security';
+
+export class SearchComponent {
+  private rateLimiter = inject(RateLimiterService);
+
+  constructor() {
+    this.rateLimiter.configure('search', {
+      type: 'token-bucket',
+      capacity: 5,
+      refillPerSecond: 1,
+    });
+  }
+
+  canSearch = this.rateLimiter.canExecute('search'); // Signal<boolean>
+  remaining = this.rateLimiter.remaining('search'); // Signal<number>
+
+  async search(query: string) {
+    try {
+      await this.rateLimiter.consume('search');
+      return this.api.search(query);
+    } catch (err) {
+      if (err instanceof RateLimitExceededError) {
+        // Show countdown using err.retryAfterMs
+      }
+    }
+  }
+}
+```
+
+### **HibpService**
+
+```typescript
+import { HibpService } from '@angular-helpers/security';
+
+export class RegistrationComponent {
+  private hibp = inject(HibpService);
+
+  async checkPassword(password: string) {
+    const { leaked, count, error } = await this.hibp.isPasswordLeaked(password);
+    if (error) return; // fail-open on network failures
+    if (leaked) alert(`This password has appeared in ${count} data breaches.`);
+  }
+}
+```
+
+### **SensitiveClipboardService**
+
+```typescript
+import { SensitiveClipboardService } from '@angular-helpers/security';
+
+export class ApiKeyPanel {
+  private sensitiveClipboard = inject(SensitiveClipboardService);
+
+  async copy(value: string) {
+    await this.sensitiveClipboard.copy(value, { clearAfterMs: 15_000 });
+  }
+}
+```
+
+The service reads the clipboard before clearing and skips the clear if the content no longer
+matches what was copied — so third-party copies by the user are never overwritten.
+
 ## 🔧 Advanced Configuration
 
 ### **Security Options**