@angular-helpers/security 21.2.0 → 21.4.1

package/README.es.md

@@ -49,6 +49,37 @@ Paquete de seguridad para aplicaciones Angular que previene ataques comunes como
 - **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**
 
 - **API Fluida**: Construye expresiones regulares de forma intuitiva.
@@ -305,6 +336,170 @@ 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:'] })]),
+  });
+}
+```
+
+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,50 @@ 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.
+
+### **Session Inactivity Monitor**
+
+- **NgZone-optimized**: DOM events tracked outside Angular change detection.
+- **Security interop**: Can automatically clear SecureStorage and SensitiveClipboard upon timeout.
+- **Warning states**: Configurable thresholds to warn users before expiration.
+
+### **Secure Cross-Window Messaging**
+
+- **HMAC-SHA-256 signatures**: Every message is signed; tampered payloads are discarded.
+- **Origin whitelist**: Messages from non-allowed origins are rejected before any crypto work.
+- **Anti-replay protection**: Envelope includes `timestamp + nonce`; messages older than 30s are discarded.
+- **SSR-safe**: No-op on the server — no `window` access.
+
 ### **Builder Pattern**
 
 - **Fluent API**: Intuitively build regular expressions.
@@ -371,6 +415,253 @@ 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.
+
+### **SessionIdleService**
+
+```typescript
+import { SessionIdleService } from '@angular-helpers/security';
+
+export class AppComponent {
+  private sessionIdle = inject(SessionIdleService);
+
+  ngOnInit() {
+    this.sessionIdle.start({
+      timeoutMs: 15 * 60 * 1000, // 15 minutes
+      warningThresholdMs: 60 * 1000, // 1 minute warning
+      autoClearStorage: true,
+      autoClearClipboard: true,
+    });
+
+    // React to states
+    effect(() => {
+      if (this.sessionIdle.isWarning()) {
+        console.warn(`Session will expire in ${this.sessionIdle.timeRemaining()}ms`);
+      }
+    });
+
+    // React to timeout
+    this.sessionIdle.onTimeout.subscribe(() => {
+      this.authService.logout();
+    });
+  }
+}
+```
+
+The service tracks DOM events (`mousemove`, `keydown`, etc.) outside the Angular Zone to prevent change detection spam. It can automatically clear `SecureStorageService` and `SensitiveClipboardService` when the session times out.
+
+### **SecureMessageService**
+
+```typescript
+import { SecureMessageService, provideSecureMessage } from '@angular-helpers/security';
+
+// app.config.ts
+bootstrapApplication(AppComponent, {
+  providers: [provideSecureMessage()],
+});
+
+// parent-app.component.ts
+export class ParentComponent {
+  private channel = inject(SecureMessageService);
+
+  async ngOnInit() {
+    // 1. Generate a shared key (transport it to the iframe via a secure channel)
+    const key = await this.channel.generateChannelKey();
+
+    // 2. Configure: only accept messages from the iframe origin
+    this.channel.configure({
+      allowedOrigins: ['https://child-app.example.com'],
+      signingKey: key,
+    });
+
+    // 3. React to incoming messages
+    this.channel.messages$<{ type: string; payload: unknown }>().subscribe(({ data, origin }) => {
+      console.log('Verified message from', origin, data);
+    });
+
+    // 4. Or use the Signal for reactive UI
+    effect(() => {
+      const msg = this.channel.lastMessage()();
+      if (msg) console.log('Last message:', msg.data);
+    });
+  }
+
+  async sendToChild(iframe: HTMLIFrameElement) {
+    await this.channel.send(
+      iframe.contentWindow!,
+      { type: 'INIT', payload: { userId: 42 } },
+      'https://child-app.example.com', // targetOrigin — never '*'
+    );
+  }
+}
+```
+
+> **Key exchange**: `SecureMessageService` does not perform automatic key negotiation — transport the `CryptoKey` to the other context via a secure out-of-band channel (e.g., derive it from a shared secret using `WebCryptoService.generateHmacKey()` seeded by a passphrase). Once both sides share the key, all message integrity is handled automatically.
+
 ## 🔧 Advanced Configuration
 
 ### **Security Options**

package/fesm2022/angular-helpers-security-forms.mjs

@@ -0,0 +1,110 @@
+import { assessPasswordStrength, isHtmlSafe, isUrlSafe, containsScriptInjection, containsSqlInjectionHints } from '@angular-helpers/security';
+
+/**
+ * Collection of Reactive Forms validators that bridge the shared security helpers into
+ * the Angular `ValidatorFn` contract. All validators are static factory functions and do not
+ * require provider registration.
+ *
+ * For the Signal Forms equivalents see `@angular-helpers/security/signal-forms`.
+ *
+ * @example
+ * const form = new FormGroup({
+ *   password: new FormControl('', [
+ *     Validators.required,
+ *     SecurityValidators.strongPassword({ minScore: 3 }),
+ *   ]),
+ *   bio: new FormControl('', [SecurityValidators.safeHtml()]),
+ *   homepage: new FormControl('', [SecurityValidators.safeUrl({ schemes: ['https:'] })]),
+ * });
+ */
+class SecurityValidators {
+    /**
+     * Validates password strength using the shared entropy-based scoring logic.
+     * Returns `{ weakPassword: { score, required } }` when the score is below `minScore`.
+     *
+     * @param options.minScore Minimum acceptable score (0..4). Default: `2` (fair).
+     */
+    static strongPassword(options = {}) {
+        const required = options.minScore ?? 2;
+        return (control) => {
+            const value = control.value;
+            if (value === null || value === undefined || value === '')
+                return null;
+            if (typeof value !== 'string')
+                return null;
+            const { score } = assessPasswordStrength(value);
+            return score < required ? { weakPassword: { score, required } } : null;
+        };
+    }
+    /**
+     * Validates that the given HTML string contains no tags or attributes outside the allowlist.
+     * Returns `{ unsafeHtml: true }` when sanitization would alter the value.
+     *
+     * Requires a browser environment (DOMParser). In SSR contexts the validator returns `null`
+     * (no error) to avoid blocking forms server-side; re-validation happens automatically on
+     * hydration.
+     */
+    static safeHtml(options = {}) {
+        return (control) => {
+            const value = control.value;
+            if (value === null || value === undefined || value === '')
+                return null;
+            if (typeof value !== 'string')
+                return null;
+            if (typeof DOMParser === 'undefined')
+                return null;
+            return isHtmlSafe(value, options) ? null : { unsafeHtml: true };
+        };
+    }
+    /**
+     * Validates that the given URL is well-formed and uses an allowed scheme.
+     * Returns `{ unsafeUrl: true }` for `javascript:`, `data:`, relative URLs, and other
+     * non-allowlisted protocols.
+     */
+    static safeUrl(options = {}) {
+        const schemes = options.schemes ?? ['http:', 'https:'];
+        return (control) => {
+            const value = control.value;
+            if (value === null || value === undefined || value === '')
+                return null;
+            if (typeof value !== 'string')
+                return null;
+            return isUrlSafe(value, schemes) ? null : { unsafeUrl: true };
+        };
+    }
+    /**
+     * Rejects values that look like script injection attempts (`<script>`, `javascript:`,
+     * or inline event handlers). Lightweight pattern check — NOT a substitute for a full
+     * HTML sanitizer.
+     */
+    static noScriptInjection() {
+        return (control) => {
+            const value = control.value;
+            if (value === null || value === undefined || value === '')
+                return null;
+            if (typeof value !== 'string')
+                return null;
+            return containsScriptInjection(value) ? { scriptInjection: true } : null;
+        };
+    }
+    /**
+     * Heuristic check for common SQL-injection sentinel strings. Intended as defense-in-depth
+     * for user-facing inputs. Use parameterized queries on the server as the primary defense.
+     */
+    static noSqlInjectionHints() {
+        return (control) => {
+            const value = control.value;
+            if (value === null || value === undefined || value === '')
+                return null;
+            if (typeof value !== 'string')
+                return null;
+            return containsSqlInjectionHints(value) ? { sqlInjectionHint: true } : null;
+        };
+    }
+}
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { SecurityValidators };