@angular-helpers/security 21.2.0 → 21.3.0

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,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**

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 };

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

@@ -0,0 +1,159 @@
+import { inject, resource } from '@angular/core';
+import { validate, validateAsync } from '@angular/forms/signals';
+import { assessPasswordStrength, isHtmlSafe, isUrlSafe, containsScriptInjection, containsSqlInjectionHints, HibpService } from '@angular-helpers/security';
+
+/**
+ * Registers a sync validation rule on a string field that fails when the password strength
+ * is below the required score. Uses the shared `assessPasswordStrength` helper for behavioural
+ * parity with the Reactive Forms `SecurityValidators.strongPassword`.
+ *
+ * @example
+ * form(model, (p) => {
+ *   required(p.password);
+ *   strongPassword(p.password, { minScore: 3 });
+ * });
+ */
+function strongPassword(path, options) {
+    const required = options?.minScore ?? 2;
+    const message = options?.message ?? 'Password is too weak';
+    validate(path, ({ value }) => {
+        const raw = value();
+        if (!raw)
+            return null;
+        const { score } = assessPasswordStrength(raw);
+        return score < required ? { kind: 'weakPassword', message } : null;
+    });
+}
+/**
+ * Registers a sync validation rule that fails when the input contains tags or attributes
+ * outside the allowed HTML sanitizer allowlist.
+ *
+ * Requires a browser environment. In SSR contexts the rule is a no-op (returns `null`) so
+ * server-rendered forms remain submittable; re-validation happens on hydration.
+ */
+function safeHtml(path, options) {
+    const message = options?.message ?? 'Value contains unsafe HTML';
+    const sanitizerOptions = {
+        allowedTags: options?.allowedTags,
+        allowedAttributes: options?.allowedAttributes,
+    };
+    validate(path, ({ value }) => {
+        const raw = value();
+        if (!raw)
+            return null;
+        if (typeof DOMParser === 'undefined')
+            return null;
+        return isHtmlSafe(raw, sanitizerOptions) ? null : { kind: 'unsafeHtml', message };
+    });
+}
+/**
+ * Registers a sync validation rule that fails for malformed URLs or URLs using schemes
+ * outside the allowlist (default: `http:` and `https:`).
+ */
+function safeUrl(path, options) {
+    const schemes = options?.schemes ?? ['http:', 'https:'];
+    const message = options?.message ?? 'URL scheme is not allowed';
+    validate(path, ({ value }) => {
+        const raw = value();
+        if (!raw)
+            return null;
+        return isUrlSafe(raw, schemes) ? null : { kind: 'unsafeUrl', message };
+    });
+}
+/**
+ * Registers a sync validation rule that rejects values matching common script-injection
+ * sentinels (`<script>`, `javascript:`, inline event handlers).
+ */
+function noScriptInjection(path, options) {
+    const message = options?.message ?? 'Value contains script injection patterns';
+    validate(path, ({ value }) => {
+        const raw = value();
+        if (!raw)
+            return null;
+        return containsScriptInjection(raw) ? { kind: 'scriptInjection', message } : null;
+    });
+}
+/**
+ * Registers a sync validation rule that rejects common SQL-injection sentinel strings.
+ * Intended as defense-in-depth alongside server-side parameterized queries.
+ */
+function noSqlInjectionHints(path, options) {
+    const message = options?.message ?? 'Value contains SQL injection hints';
+    validate(path, ({ value }) => {
+        const raw = value();
+        if (!raw)
+            return null;
+        return containsSqlInjectionHints(raw) ? { kind: 'sqlInjectionHint', message } : null;
+    });
+}
+/**
+ * Registers an async validation rule that checks the password against the Have I Been Pwned
+ * breach corpus via the k-anonymity API. Requires `provideHibp()` to be set up in the
+ * injector hierarchy.
+ *
+ * Fail-open semantics: network errors and unsupported environments do NOT produce a
+ * validation error — the form remains submittable. This is intentional to prevent HIBP
+ * outages from blocking user sign-ups.
+ *
+ * @example
+ * form(model, (p) => {
+ *   required(p.password);
+ *   strongPassword(p.password, { minScore: 3 });
+ *   hibpPassword(p.password);
+ * });
+ */
+function hibpPassword(path, options) {
+    const message = options?.message ?? 'This password has appeared in a data breach';
+    const debounceMs = options?.debounceMs ?? 300;
+    validateAsync(path, {
+        params: ({ value }) => {
+            const raw = value();
+            return raw && raw.length >= 8 ? raw : undefined;
+        },
+        factory: (passwordSignal) => {
+            const hibp = inject(HibpService);
+            return resource({
+                params: () => passwordSignal(),
+                loader: async ({ params: password, abortSignal }) => {
+                    if (!password)
+                        return undefined;
+                    if (debounceMs > 0) {
+                        await debounce(debounceMs, abortSignal);
+                    }
+                    return hibp.isPasswordLeaked(password);
+                },
+            });
+        },
+        onSuccess: (result) => {
+            if (!result)
+                return null;
+            if (result.error)
+                return null;
+            return result.leaked ? { kind: 'leakedPassword', message, count: result.count } : null;
+        },
+        onError: () => null,
+    });
+}
+function debounce(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { hibpPassword, noScriptInjection, noSqlInjectionHints, safeHtml, safeUrl, strongPassword };