@angular-helpers/security 21.0.3 → 21.1.0

package/README.es.md

@@ -15,6 +15,13 @@ Paquete de seguridad para aplicaciones Angular que previene ataques comunes como
 - **Análisis de Complejidad**: Detecta patrones peligrosos antes de la ejecución.
 - **Modo Seguro**: Solo permite patrones verificados como seguros.
 
+### **Web Crypto API**
+
+- **Cifrado/Descifrado**: Soporte AES-GCM para manejo seguro de datos
+- **Hashing**: SHA-256 y otros algoritmos
+- **Gestión de Claves**: Generar, importar y exportar claves criptográficas
+- **Aleatorio Seguro**: Valores aleatorios criptográficamente seguros
+
 ### **Patrón Builder**
 
 - **API Fluida**: Construye expresiones regulares de forma intuitiva.
@@ -93,6 +100,51 @@ const result = await RegexSecurityService.builder()
   .execute('12345', this.securityService);
 ```
 
+### **WebCryptoService**
+
+```typescript
+import { WebCryptoService } from '@angular-helpers/security';
+
+export class SecureStorageComponent {
+  private cryptoService = inject(WebCryptoService);
+
+  async hashPassword(password: string): Promise<string> {
+    return await this.cryptoService.hash(password, 'SHA-256');
+  }
+
+  async encryptData(
+    data: string,
+  ): Promise<{ ciphertext: ArrayBuffer; iv: Uint8Array; key: CryptoKey }> {
+    const key = await this.cryptoService.generateAesKey(256);
+    const { ciphertext, iv } = await this.cryptoService.encryptAes(key, data);
+    return { ciphertext, iv, key };
+  }
+
+  async decryptData(ciphertext: ArrayBuffer, iv: Uint8Array, key: CryptoKey): Promise<string> {
+    return await this.cryptoService.decryptAes(key, ciphertext, iv);
+  }
+
+  async exportKeyForStorage(key: CryptoKey): Promise<JsonWebKey> {
+    return await this.cryptoService.exportKey(key);
+  }
+
+  async importKeyFromStorage(jwk: JsonWebKey): Promise<CryptoKey> {
+    return await this.cryptoService.importAesKey(jwk);
+  }
+
+  generateSecureToken(length: number = 32): string {
+    const bytes = this.cryptoService.generateRandomBytes(length);
+    return Array.from(bytes)
+      .map((b) => b.toString(16).padStart(2, '0'))
+      .join('');
+  }
+
+  generateUUID(): string {
+    return this.cryptoService.randomUUID();
+  }
+}
+```
+
 ## 📊 Niveles de Riesgo
 
 | Nivel          | Descripción          | Acción                                   |

package/README.md

@@ -15,6 +15,36 @@ Security package for Angular applications that prevents common attacks like ReDo
 - **Complexity Analysis**: Detects dangerous patterns before execution.
 - **Safe Mode**: Only allows patterns verified as safe.
 
+### **Web Crypto API**
+
+- **Encryption/Decryption**: AES-GCM support for secure data handling
+- **Hashing**: SHA-256 and other algorithms
+- **HMAC Signing**: HMAC-SHA-256/384/512 for message authentication
+- **Key Management**: Generate, import, and export cryptographic keys
+- **Secure Random**: Cryptographically secure random values
+- **UUID Generation**: RFC4122 v4 UUIDs
+
+### **Secure Storage**
+
+- **Transparent Encryption**: AES-GCM encrypted localStorage/sessionStorage
+- **Ephemeral Mode**: In-memory keys for single-session security
+- **Passphrase Mode**: PBKDF2-derived keys for cross-session persistence
+- **Namespace Isolation**: Organize stored data with prefixes
+
+### **Input Sanitization**
+
+- **XSS Prevention**: Strip dangerous tags and attributes from HTML
+- **URL Validation**: Allow only http/https schemes
+- **HTML Escaping**: Safe interpolation of user content
+- **JSON Safety**: Safe parsing without eval
+
+### **Password Strength**
+
+- **Entropy-Based Scoring**: 0-4 score with labeled strength levels
+- **Pattern Detection**: Detects sequences, repetitions, keyboard walks
+- **Common Password Check**: Blocks frequently used passwords
+- **Feedback Messages**: Actionable improvement suggestions
+
 ### **Builder Pattern**
 
 - **Fluent API**: Intuitively build regular expressions.
@@ -37,7 +67,16 @@ import { provideSecurity } from '@angular-helpers/security';
 bootstrapApplication(AppComponent, {
   providers: [
     provideSecurity({
+      // Core services (enabled by default)
       enableRegexSecurity: true,
+      enableWebCrypto: true,
+
+      // New services (opt-in, disabled by default)
+      enableSecureStorage: true,
+      enableInputSanitizer: true,
+      enablePasswordStrength: true,
+
+      // Global settings
       defaultTimeout: 5000,
       safeMode: false,
     }),
@@ -45,6 +84,27 @@ bootstrapApplication(AppComponent, {
 });
 ```
 
+### **Individual Providers**
+
+```typescript
+import {
+  provideRegexSecurity,
+  provideWebCrypto,
+  provideSecureStorage,
+  provideInputSanitizer,
+  providePasswordStrength,
+} from '@angular-helpers/security';
+
+// Use only the services you need
+bootstrapApplication(AppComponent, {
+  providers: [
+    provideSecureStorage({ storage: 'session', pbkdf2Iterations: 600_000 }),
+    provideInputSanitizer({ allowedTags: ['b', 'i', 'em', 'strong'] }),
+    providePasswordStrength(),
+  ],
+});
+```
+
 ### **Service Injection**
 
 ```typescript
@@ -163,6 +223,154 @@ export class FormValidationComponent {
 }
 ```
 
+### **WebCryptoService**
+
+```typescript
+import { WebCryptoService } from '@angular-helpers/security';
+
+export class SecureStorageComponent {
+  private cryptoService = inject(WebCryptoService);
+
+  async hashPassword(password: string): Promise<string> {
+    return await this.cryptoService.hash(password, 'SHA-256');
+  }
+
+  async encryptData(
+    data: string,
+  ): Promise<{ ciphertext: ArrayBuffer; iv: Uint8Array; key: CryptoKey }> {
+    const key = await this.cryptoService.generateAesKey(256);
+    const { ciphertext, iv } = await this.cryptoService.encryptAes(key, data);
+    return { ciphertext, iv, key };
+  }
+
+  async decryptData(ciphertext: ArrayBuffer, iv: Uint8Array, key: CryptoKey): Promise<string> {
+    return await this.cryptoService.decryptAes(key, ciphertext, iv);
+  }
+
+  async exportKeyForStorage(key: CryptoKey): Promise<JsonWebKey> {
+    return await this.cryptoService.exportKey(key);
+  }
+
+  async importKeyFromStorage(jwk: JsonWebKey): Promise<CryptoKey> {
+    return await this.cryptoService.importAesKey(jwk);
+  }
+
+  generateSecureToken(length: number = 32): string {
+    const bytes = this.cryptoService.generateRandomBytes(length);
+    return Array.from(bytes)
+      .map((b) => b.toString(16).padStart(2, '0'))
+      .join('');
+  }
+
+  generateUUID(): string {
+    return this.cryptoService.randomUUID();
+  }
+
+  async signAndVerify(data: string): Promise<boolean> {
+    // Generate HMAC key for SHA-256
+    const key = await this.cryptoService.generateHmacKey('HMAC-SHA-256');
+
+    // Sign the data
+    const signature = await this.cryptoService.sign(key, data);
+
+    // Verify the signature
+    return await this.cryptoService.verify(key, data, signature);
+  }
+}
+```
+
+### **SecureStorageService**
+
+```typescript
+import { SecureStorageService } from '@angular-helpers/security';
+
+export class UserSettingsComponent {
+  private storage = inject(SecureStorageService);
+
+  async saveUserToken(token: string): Promise<void> {
+    // Ephemeral mode (default): data survives only this session
+    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> {
+    // Passphrase mode: data survives page reloads
+    await this.storage.initWithPassphrase(passphrase);
+  }
+
+  async saveWithNamespace(userId: string, data: unknown): Promise<void> {
+    // Namespace isolation
+    await this.storage.set('profile', data, `user:${userId}`);
+  }
+
+  clearUserData(userId: string): void {
+    // Clear only this user's data
+    this.storage.clear(`user:${userId}`);
+  }
+}
+```
+
+### **InputSanitizerService**
+
+```typescript
+import { InputSanitizerService } from '@angular-helpers/security';
+
+export class CommentComponent {
+  private sanitizer = inject(InputSanitizerService);
+
+  sanitizeUserComment(html: string): string {
+    // Strip dangerous tags, keep safe ones (b, i, em, a, etc.)
+    return this.sanitizer.sanitizeHtml(html);
+    // Example: '<b>Hello</b><script>alert(1)</script>' → '<b>Hello</b>'
+  }
+
+  validateUserLink(url: string): string | null {
+    // Only allow http/https URLs
+    return this.sanitizer.sanitizeUrl(url);
+    // Example: 'javascript:alert(1)' → null
+    // Example: 'https://example.com' → 'https://example.com/'
+  }
+
+  escapeForDisplay(text: string): string {
+    // Safe for HTML text nodes
+    return this.sanitizer.escapeHtml(text);
+    // Example: '<b>hello</b>' → '&lt;b&gt;hello&lt;/b&gt;'
+  }
+
+  parseUserJson(json: string): unknown | null {
+    // Safe JSON parsing without eval
+    return this.sanitizer.sanitizeJson(json);
+  }
+}
+```
+
+### **PasswordStrengthService**
+
+```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' to 'very-strong'
+    console.log(`Entropy: ${result.entropy} bits`); // calculated entropy
+    console.log('Feedback:', result.feedback); // improvement suggestions
+
+    // Example results:
+    // 'password' → score: 0, label: 'very-weak', feedback: ['This is a commonly used password']
+    // 'P@ssw0rd!' → score: 2, label: 'fair', feedback: ['Avoid keyboard patterns']
+    // 'xK#9mZ$vLq2@rBnT7' → score: 4, label: 'very-strong', feedback: []
+  }
+}
+```
+
 ## 🔧 Advanced Configuration
 
 ### **Security Options**

package/fesm2022/angular-helpers-security.mjs

@@ -1,5 +1,6 @@
 import * as i0 from '@angular/core';
-import { inject, DestroyRef, Injectable, makeEnvironmentProviders } from '@angular/core';
+import { inject, DestroyRef, Injectable, PLATFORM_ID, InjectionToken, makeEnvironmentProviders } from '@angular/core';
+import { isPlatformBrowser } from '@angular/common';
 
 /**
  * Security service for regular expressions that prevents ReDoS
@@ -411,8 +412,614 @@ class RegexSecurityBuilder {
     }
 }
 
+class WebCryptoService {
+    platformId = inject(PLATFORM_ID);
+    isSupported() {
+        return isPlatformBrowser(this.platformId) && 'crypto' in window && 'subtle' in crypto;
+    }
+    get subtle() {
+        if (!this.isSupported()) {
+            throw new Error('Web Crypto API not supported in this environment');
+        }
+        return crypto.subtle;
+    }
+    ensureSecureContext() {
+        if (!window.isSecureContext) {
+            throw new Error('Web Crypto API requires a secure context (HTTPS)');
+        }
+    }
+    async hash(data, algorithm = 'SHA-256') {
+        this.ensureSecureContext();
+        const buffer = typeof data === 'string' ? new TextEncoder().encode(data) : data;
+        const hashBuffer = await this.subtle.digest(algorithm, buffer);
+        return this.bufferToHex(hashBuffer);
+    }
+    async generateAesKey(length = 256) {
+        this.ensureSecureContext();
+        return this.subtle.generateKey({ name: 'AES-GCM', length }, true, ['encrypt', 'decrypt']);
+    }
+    async encryptAes(key, data) {
+        this.ensureSecureContext();
+        const buffer = typeof data === 'string' ? new TextEncoder().encode(data) : data;
+        const iv = crypto.getRandomValues(new Uint8Array(12));
+        const ciphertext = await this.subtle.encrypt({ name: 'AES-GCM', iv }, key, buffer);
+        return { ciphertext, iv };
+    }
+    async decryptAes(key, ciphertext, iv) {
+        this.ensureSecureContext();
+        const decrypted = await this.subtle.decrypt({ name: 'AES-GCM', iv }, key, ciphertext);
+        return new TextDecoder().decode(decrypted);
+    }
+    async exportKey(key) {
+        this.ensureSecureContext();
+        return this.subtle.exportKey('jwk', key);
+    }
+    async importAesKey(jwk) {
+        this.ensureSecureContext();
+        return this.subtle.importKey('jwk', jwk, { name: 'AES-GCM' }, true, ['encrypt', 'decrypt']);
+    }
+    generateRandomBytes(length) {
+        if (!this.isSupported()) {
+            throw new Error('Web Crypto API not supported');
+        }
+        return crypto.getRandomValues(new Uint8Array(length));
+    }
+    randomUUID() {
+        if (!this.isSupported()) {
+            throw new Error('Web Crypto API not supported');
+        }
+        return crypto.randomUUID();
+    }
+    async generateHmacKey(algorithm = 'HMAC-SHA-256') {
+        this.ensureSecureContext();
+        return this.subtle.generateKey({ name: 'HMAC', hash: { name: this.hmacHashName(algorithm) } }, true, ['sign', 'verify']);
+    }
+    /**
+     * Signs data with an HMAC key. Returns a hex-encoded signature.
+     */
+    async sign(key, data) {
+        this.ensureSecureContext();
+        const buffer = typeof data === 'string' ? new TextEncoder().encode(data) : data;
+        const signature = await this.subtle.sign('HMAC', key, buffer);
+        return this.bufferToHex(signature);
+    }
+    /**
+     * Verifies an HMAC signature (hex-encoded). Returns false for malformed input — never throws.
+     */
+    async verify(key, data, signature) {
+        this.ensureSecureContext();
+        let sigBytes;
+        try {
+            sigBytes = this.hexToBytes(signature);
+        }
+        catch {
+            return false;
+        }
+        try {
+            const buffer = typeof data === 'string' ? new TextEncoder().encode(data) : data;
+            return await this.subtle.verify('HMAC', key, sigBytes, buffer);
+        }
+        catch {
+            return false;
+        }
+    }
+    async importHmacKey(jwk, algorithm = 'HMAC-SHA-256') {
+        this.ensureSecureContext();
+        return this.subtle.importKey('jwk', jwk, { name: 'HMAC', hash: { name: this.hmacHashName(algorithm) } }, true, ['sign', 'verify']);
+    }
+    bufferToHex(buffer) {
+        return Array.from(new Uint8Array(buffer))
+            .map((b) => b.toString(16).padStart(2, '0'))
+            .join('');
+    }
+    hexToBytes(hex) {
+        if (hex.length % 2 !== 0)
+            throw new Error('Invalid hex string');
+        const bytes = new Uint8Array(new ArrayBuffer(hex.length / 2));
+        for (let i = 0; i < hex.length; i += 2) {
+            const byte = parseInt(hex.substring(i, i + 2), 16);
+            if (isNaN(byte))
+                throw new Error('Invalid hex string');
+            bytes[i / 2] = byte;
+        }
+        return bytes;
+    }
+    hmacHashName(algorithm) {
+        return algorithm.replace('HMAC-', '');
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: WebCryptoService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: WebCryptoService });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: WebCryptoService, decorators: [{
+            type: Injectable
+        }] });
+
+const SECURE_STORAGE_CONFIG = new InjectionToken('SECURE_STORAGE_CONFIG');
+const SALT_STORAGE_KEY = '__ss_salt__';
+const DEFAULT_ITERATIONS = 600_000;
+/**
+ * Service for transparent AES-GCM encrypted storage on top of localStorage/sessionStorage.
+ *
+ * Two key modes are supported:
+ * - **Ephemeral** (default): a CryptoKey is generated in memory per service instance.
+ *   Data is unrecoverable after page reload or service re-creation.
+ * - **Passphrase-derived**: call `initWithPassphrase(passphrase)` to derive a stable key
+ *   via PBKDF2. Data survives page reloads as long as the same passphrase is used.
+ *
+ * @example
+ * // Ephemeral mode
+ * await storage.set('token', { value: 'abc' });
+ * const token = await storage.get<{ value: string }>('token');
+ *
+ * @example
+ * // Passphrase mode
+ * await storage.initWithPassphrase('my-secret');
+ * await storage.set('user', { id: 1 }, 'auth');
+ * const user = await storage.get<{ id: number }>('user', 'auth');
+ */
+class SecureStorageService {
+    platformId = inject(PLATFORM_ID);
+    storageConfig;
+    activeKey = null;
+    constructor() {
+        const config = inject(SECURE_STORAGE_CONFIG, { optional: true }) ?? {};
+        this.storageConfig = {
+            storage: config.storage ?? 'local',
+            pbkdf2Iterations: config.pbkdf2Iterations ?? DEFAULT_ITERATIONS,
+        };
+    }
+    isSupported() {
+        return (isPlatformBrowser(this.platformId) &&
+            'crypto' in window &&
+            'subtle' in crypto &&
+            'localStorage' in window);
+    }
+    /**
+     * Initializes the service with a passphrase-derived key (PBKDF2 + AES-GCM).
+     * The salt is automatically persisted in storage on first call and reused on subsequent calls.
+     * Calling this again replaces the active key.
+     *
+     * @param passphrase Secret passphrase for key derivation.
+     * @param explicitSalt Optional base64 salt. When provided, the stored salt is ignored.
+     */
+    async initWithPassphrase(passphrase, explicitSalt) {
+        this.assertSupported();
+        let salt;
+        if (explicitSalt) {
+            salt = this.base64ToBytes(explicitSalt);
+        }
+        else {
+            const stored = this.nativeStorage.getItem(SALT_STORAGE_KEY);
+            if (stored) {
+                salt = this.base64ToBytes(stored);
+            }
+            else {
+                salt = crypto.getRandomValues(new Uint8Array(new ArrayBuffer(16)));
+                this.nativeStorage.setItem(SALT_STORAGE_KEY, this.bytesToBase64(salt));
+            }
+        }
+        const keyMaterial = await crypto.subtle.importKey('raw', new TextEncoder().encode(passphrase), 'PBKDF2', false, ['deriveKey']);
+        this.activeKey = await crypto.subtle.deriveKey({
+            name: 'PBKDF2',
+            salt,
+            iterations: this.storageConfig.pbkdf2Iterations,
+            hash: 'SHA-256',
+        }, keyMaterial, { name: 'AES-GCM', length: 256 }, true, ['encrypt', 'decrypt']);
+    }
+    /**
+     * Encrypts and stores a value.
+     * A fresh random IV is generated for every write.
+     *
+     * @throws {TypeError} When `value` is `undefined`.
+     * @throws {DOMException} When storage quota is exceeded.
+     */
+    async set(key, value, namespace) {
+        this.assertSupported();
+        if (value === undefined) {
+            throw new TypeError('Cannot store undefined value in SecureStorageService');
+        }
+        const cryptoKey = await this.ensureKey();
+        const iv = crypto.getRandomValues(new Uint8Array(new ArrayBuffer(12)));
+        const plaintext = new TextEncoder().encode(JSON.stringify(value));
+        const ciphertext = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, cryptoKey, plaintext);
+        const entry = {
+            iv: this.bytesToBase64(iv),
+            ct: this.bytesToBase64(ciphertext),
+        };
+        this.nativeStorage.setItem(this.buildStorageKey(key, namespace), JSON.stringify(entry));
+    }
+    /**
+     * Decrypts and returns a stored value.
+     * Returns `null` if the key does not exist, was written without encryption,
+     * or the ciphertext is corrupted.
+     */
+    async get(key, namespace) {
+        this.assertSupported();
+        const raw = this.nativeStorage.getItem(this.buildStorageKey(key, namespace));
+        if (!raw)
+            return null;
+        let entry;
+        try {
+            const parsed = JSON.parse(raw);
+            if (!parsed || typeof parsed !== 'object' || !('iv' in parsed) || !('ct' in parsed)) {
+                return null;
+            }
+            entry = parsed;
+        }
+        catch {
+            return null;
+        }
+        try {
+            const cryptoKey = await this.ensureKey();
+            const iv = this.base64ToBytes(entry.iv);
+            const ciphertext = this.base64ToBytes(entry.ct);
+            const decrypted = await crypto.subtle.decrypt({ name: 'AES-GCM', iv }, cryptoKey, ciphertext);
+            return JSON.parse(new TextDecoder().decode(decrypted));
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Removes a single entry from storage.
+     */
+    remove(key, namespace) {
+        this.assertSupported();
+        this.nativeStorage.removeItem(this.buildStorageKey(key, namespace));
+    }
+    /**
+     * Clears all entries belonging to a namespace.
+     * When called without arguments, clears the entire storage target.
+     */
+    clear(namespace) {
+        this.assertSupported();
+        if (!namespace) {
+            this.nativeStorage.clear();
+            return;
+        }
+        const prefix = `${namespace}:`;
+        const keysToRemove = [];
+        for (let i = 0; i < this.nativeStorage.length; i++) {
+            const k = this.nativeStorage.key(i);
+            if (k?.startsWith(prefix)) {
+                keysToRemove.push(k);
+            }
+        }
+        keysToRemove.forEach((k) => this.nativeStorage.removeItem(k));
+    }
+    get nativeStorage() {
+        return this.storageConfig.storage === 'session' ? sessionStorage : localStorage;
+    }
+    buildStorageKey(key, namespace) {
+        return namespace ? `${namespace}:${key}` : key;
+    }
+    async ensureKey() {
+        if (this.activeKey)
+            return this.activeKey;
+        this.activeKey = await crypto.subtle.generateKey({ name: 'AES-GCM', length: 256 }, true, [
+            'encrypt',
+            'decrypt',
+        ]);
+        return this.activeKey;
+    }
+    assertSupported() {
+        if (!this.isSupported()) {
+            throw new Error('SecureStorageService is not supported in this environment (requires browser + Web Crypto API)');
+        }
+    }
+    bytesToBase64(buffer) {
+        const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
+        let binary = '';
+        for (let i = 0; i < bytes.length; i++) {
+            binary += String.fromCharCode(bytes[i]);
+        }
+        return btoa(binary);
+    }
+    base64ToBytes(base64) {
+        return Uint8Array.from(atob(base64), (c) => c.charCodeAt(0));
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: SecureStorageService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: SecureStorageService });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: SecureStorageService, decorators: [{
+            type: Injectable
+        }], ctorParameters: () => [] });
+
+const SANITIZER_CONFIG = new InjectionToken('SANITIZER_CONFIG');
+const DEFAULT_ALLOWED_TAGS = [
+    'b',
+    'i',
+    'em',
+    'strong',
+    'a',
+    'p',
+    'br',
+    'ul',
+    'ol',
+    'li',
+    'span',
+];
+const DEFAULT_ALLOWED_ATTRIBUTES = {
+    a: ['href'],
+};
+const SAFE_URL_SCHEMES = ['http:', 'https:'];
+/**
+ * Service for structured input sanitization to defend against XSS, URL injection, and unsafe HTML.
+ *
+ * This service is defense-in-depth and DOES NOT replace a Content Security Policy (CSP).
+ * Always configure a proper CSP alongside using this service.
+ *
+ * @example
+ * const clean = sanitizer.sanitizeHtml('<b>Hello</b><script>alert(1)</script>');
+ * // → '<b>Hello</b>'
+ *
+ * @example
+ * const url = sanitizer.sanitizeUrl('javascript:alert(1)');
+ * // → null
+ */
+class InputSanitizerService {
+    platformId = inject(PLATFORM_ID);
+    allowedTags;
+    allowedAttributes;
+    constructor() {
+        const config = inject(SANITIZER_CONFIG, { optional: true }) ?? {};
+        this.allowedTags = new Set(config.allowedTags ?? DEFAULT_ALLOWED_TAGS);
+        this.allowedAttributes = config.allowedAttributes ?? DEFAULT_ALLOWED_ATTRIBUTES;
+    }
+    isSupported() {
+        return isPlatformBrowser(this.platformId) && typeof DOMParser !== 'undefined';
+    }
+    /**
+     * Parses and sanitizes an HTML string, keeping only allowed tags and attributes.
+     * Script execution is prevented — parsing is done via DOMParser, not innerHTML assignment.
+     *
+     * @throws {Error} When called in a non-browser environment.
+     */
+    sanitizeHtml(input) {
+        if (!this.isSupported()) {
+            throw new Error('sanitizeHtml requires a browser environment (DOMParser unavailable)');
+        }
+        if (!input)
+            return '';
+        const parser = new DOMParser();
+        const doc = parser.parseFromString(input, 'text/html');
+        this.processNode(doc.body);
+        return doc.body.innerHTML;
+    }
+    /**
+     * Validates and normalizes a URL string.
+     * Returns the normalized URL only for `http:` and `https:` schemes.
+     * Returns `null` for `javascript:`, `data:`, `vbscript:`, relative URLs, or malformed input.
+     */
+    sanitizeUrl(input) {
+        if (!input)
+            return null;
+        try {
+            const url = new URL(input);
+            return SAFE_URL_SCHEMES.includes(url.protocol) ? url.toString() : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Escapes HTML special characters for safe text interpolation.
+     * Use this when inserting user content into HTML text nodes or attributes.
+     */
+    escapeHtml(input) {
+        if (!input)
+            return '';
+        return input
+            .replace(/&/g, '&amp;')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;')
+            .replace(/"/g, '&quot;')
+            .replace(/'/g, '&#x27;');
+    }
+    /**
+     * Safely parses a JSON string. Returns the parsed value on success, `null` on any error.
+     * Does NOT use `eval` or `Function` — uses JSON.parse only.
+     */
+    sanitizeJson(input) {
+        if (!input)
+            return null;
+        try {
+            return JSON.parse(input);
+        }
+        catch {
+            return null;
+        }
+    }
+    processNode(node) {
+        const children = Array.from(node.childNodes);
+        for (const child of children) {
+            if (child.nodeType !== Node.ELEMENT_NODE)
+                continue;
+            const element = child;
+            const tagName = element.tagName.toLowerCase();
+            if (!this.allowedTags.has(tagName)) {
+                const text = element.textContent ?? '';
+                node.replaceChild(document.createTextNode(text), element);
+                continue;
+            }
+            this.sanitizeAttributes(element, tagName);
+            this.processNode(element);
+        }
+    }
+    sanitizeAttributes(element, tagName) {
+        const attrsToRemove = [];
+        const allowed = this.allowedAttributes[tagName] ?? [];
+        for (let i = 0; i < element.attributes.length; i++) {
+            const attr = element.attributes[i];
+            if (attr.name.startsWith('on')) {
+                attrsToRemove.push(attr.name);
+                continue;
+            }
+            if (!allowed.includes(attr.name)) {
+                attrsToRemove.push(attr.name);
+                continue;
+            }
+            if (attr.name === 'href' && this.sanitizeUrl(attr.value) === null) {
+                attrsToRemove.push(attr.name);
+            }
+        }
+        attrsToRemove.forEach((name) => element.removeAttribute(name));
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: InputSanitizerService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: InputSanitizerService });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: InputSanitizerService, decorators: [{
+            type: Injectable
+        }], ctorParameters: () => [] });
+
+const COMMON_PASSWORDS = new Set([
+    'password',
+    '123456',
+    'qwerty',
+    'letmein',
+    'admin',
+    'welcome',
+    '111111',
+    'abc123',
+    'monkey',
+    'master',
+    'login',
+    'pass',
+]);
+const ALPHA_SEQUENCES = 'abcdefghijklmnopqrstuvwxyz';
+const DIGIT_SEQUENCES = '0123456789';
+const KEYBOARD_ROWS = ['qwertyuiop', 'asdfghjkl', 'zxcvbnm'];
+const SCORE_LABELS = {
+    0: 'very-weak',
+    1: 'weak',
+    2: 'fair',
+    3: 'strong',
+    4: 'very-strong',
+};
+/**
+ * Service for entropy-based password strength evaluation.
+ * All methods are synchronous and side-effect free — safely wrappable in Angular `computed()`.
+ *
+ * Score thresholds (bits of entropy):
+ * - 0 (very-weak):  < 28 bits
+ * - 1 (weak):       28–35 bits
+ * - 2 (fair):       36–49 bits
+ * - 3 (strong):     50–69 bits
+ * - 4 (very-strong): ≥ 70 bits
+ *
+ * @example
+ * const result = passwordStrength.assess('P@ssw0rd!');
+ * console.log(result.score);   // 2
+ * console.log(result.label);   // 'fair'
+ * console.log(result.entropy); // ~42.5
+ */
+class PasswordStrengthService {
+    /**
+     * Evaluates the strength of a password.
+     * Never throws — returns score 0 for empty or null-like input.
+     */
+    assess(password) {
+        if (!password) {
+            return {
+                score: 0,
+                label: 'very-weak',
+                entropy: 0,
+                feedback: ['Password cannot be empty'],
+            };
+        }
+        const feedback = [];
+        const chars = [...password];
+        const length = chars.length;
+        const hasLower = /[a-z]/.test(password);
+        const hasUpper = /[A-Z]/.test(password);
+        const hasDigit = /[0-9]/.test(password);
+        const hasSymbol = /[!@#$%^&*()\-_=+[\]{}|;:'",.<>/?\\`~]/.test(password);
+        const hasExtended = chars.some((c) => c.codePointAt(0) > 127);
+        let poolSize = 0;
+        if (hasLower)
+            poolSize += 26;
+        if (hasUpper)
+            poolSize += 26;
+        if (hasDigit)
+            poolSize += 10;
+        if (hasSymbol)
+            poolSize += 32;
+        if (hasExtended)
+            poolSize += 64;
+        if (poolSize === 0)
+            poolSize = 26;
+        let entropy = length * Math.log2(poolSize);
+        const hasAlphaSeq = this.containsSequence(password.toLowerCase(), ALPHA_SEQUENCES, 3);
+        const hasDigitSeq = this.containsSequence(password, DIGIT_SEQUENCES, 3);
+        const hasRepeat = /(.)\1{2,}/.test(password);
+        const hasKeyboard = KEYBOARD_ROWS.some((row) => this.containsSequence(password.toLowerCase(), row, 4));
+        if (hasAlphaSeq || hasDigitSeq) {
+            entropy *= 0.8;
+            feedback.push('Avoid predictable sequences (abc, 123)');
+        }
+        if (hasRepeat) {
+            entropy *= 0.9;
+            feedback.push('Avoid repeated characters');
+        }
+        if (hasKeyboard) {
+            entropy *= 0.85;
+            feedback.push('Avoid keyboard patterns (qwerty, asdf)');
+        }
+        if (length < 8) {
+            feedback.push('Use at least 8 characters');
+        }
+        if (!hasUpper)
+            feedback.push('Add uppercase letters');
+        if (!hasDigit)
+            feedback.push('Add numbers');
+        if (!hasSymbol)
+            feedback.push('Add special characters');
+        const isCommon = COMMON_PASSWORDS.has(password.toLowerCase());
+        let score = this.entropyToScore(entropy);
+        if (isCommon) {
+            score = Math.min(score, 1);
+            if (!feedback.includes('Use at least 8 characters')) {
+                feedback.push('This is a commonly used password');
+            }
+        }
+        return {
+            score,
+            label: SCORE_LABELS[score],
+            entropy: Math.round(entropy * 100) / 100,
+            feedback,
+        };
+    }
+    entropyToScore(entropy) {
+        if (entropy < 28)
+            return 0;
+        if (entropy < 36)
+            return 1;
+        if (entropy < 50)
+            return 2;
+        if (entropy < 70)
+            return 3;
+        return 4;
+    }
+    containsSequence(input, sequence, minLength) {
+        for (let i = 0; i <= sequence.length - minLength; i++) {
+            if (input.includes(sequence.substring(i, i + minLength)))
+                return true;
+        }
+        return false;
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: PasswordStrengthService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: PasswordStrengthService });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: PasswordStrengthService, decorators: [{
+            type: Injectable
+        }] });
+
 const defaultSecurityConfig = {
     enableRegexSecurity: true,
+    enableWebCrypto: true,
+    enableSecureStorage: false,
+    enableInputSanitizer: false,
+    enablePasswordStrength: false,
     defaultTimeout: 5000,
     safeMode: false,
 };
@@ -422,14 +1029,44 @@ function provideSecurity(config = {}) {
     if (mergedConfig.enableRegexSecurity) {
         providers.push(RegexSecurityService);
     }
+    if (mergedConfig.enableWebCrypto) {
+        providers.push(WebCryptoService);
+    }
+    if (mergedConfig.enableSecureStorage) {
+        providers.push(SecureStorageService);
+    }
+    if (mergedConfig.enableInputSanitizer) {
+        providers.push(InputSanitizerService);
+    }
+    if (mergedConfig.enablePasswordStrength) {
+        providers.push(PasswordStrengthService);
+    }
     return makeEnvironmentProviders(providers);
 }
 function provideRegexSecurity() {
     return makeEnvironmentProviders([RegexSecurityService]);
 }
+function provideWebCrypto() {
+    return makeEnvironmentProviders([WebCryptoService]);
+}
+function provideSecureStorage(config) {
+    return makeEnvironmentProviders([
+        SecureStorageService,
+        ...(config ? [{ provide: SECURE_STORAGE_CONFIG, useValue: config }] : []),
+    ]);
+}
+function provideInputSanitizer(config) {
+    return makeEnvironmentProviders([
+        InputSanitizerService,
+        ...(config ? [{ provide: SANITIZER_CONFIG, useValue: config }] : []),
+    ]);
+}
+function providePasswordStrength() {
+    return makeEnvironmentProviders([PasswordStrengthService]);
+}
 
 /**
  * Generated bundle index. Do not edit.
  */
 
-export { RegexSecurityBuilder, RegexSecurityService, defaultSecurityConfig, provideRegexSecurity, provideSecurity };
+export { InputSanitizerService, PasswordStrengthService, RegexSecurityBuilder, RegexSecurityService, SANITIZER_CONFIG, SECURE_STORAGE_CONFIG, SecureStorageService, WebCryptoService, defaultSecurityConfig, provideInputSanitizer, providePasswordStrength, provideRegexSecurity, provideSecureStorage, provideSecurity, provideWebCrypto };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@angular-helpers/security",
-  "version": "21.0.3",
+  "version": "21.1.0",
   "description": "Angular security helpers for preventing ReDoS and other security vulnerabilities",
   "keywords": [
     "angular",
@@ -9,18 +9,25 @@
     "redos",
     "prevention",
     "web-worker",
-    "builder-pattern"
+    "builder-pattern",
+    "encryption",
+    "web-crypto",
+    "hmac",
+    "xss",
+    "sanitization",
+    "password-strength",
+    "secure-storage"
   ],
   "author": "Angular Helpers Team",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/angular-helpers/security"
+    "url": "https://github.com/Gaspar1992/angular-helpers"
   },
   "bugs": {
-    "url": "https://github.com/angular-helpers/security/issues"
+    "url": "https://github.com/Gaspar1992/angular-helpers/issues"
   },
-  "homepage": "https://github.com/angular-helpers/security#readme",
+  "homepage": "https://gaspar1992.github.io/angular-helpers/docs/security",
   "publishConfig": {
     "access": "public"
   },

package/types/angular-helpers-security.d.ts

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { EnvironmentProviders } from '@angular/core';
+import { InjectionToken, EnvironmentProviders } from '@angular/core';
 
 interface RegexSecurityConfig {
     timeout?: number;
@@ -151,14 +151,222 @@ declare class RegexSecurityBuilder {
     execute(text: string, service: RegexSecurityService): Promise<RegexTestResult>;
 }
 
+type HashAlgorithm = 'SHA-1' | 'SHA-256' | 'SHA-384' | 'SHA-512';
+type HmacAlgorithm = 'HMAC-SHA-256' | 'HMAC-SHA-384' | 'HMAC-SHA-512';
+type AesKeyLength = 128 | 192 | 256;
+interface AesEncryptResult {
+    ciphertext: ArrayBuffer;
+    iv: Uint8Array;
+}
+declare class WebCryptoService {
+    private readonly platformId;
+    isSupported(): boolean;
+    private get subtle();
+    private ensureSecureContext;
+    hash(data: string | ArrayBuffer, algorithm?: HashAlgorithm): Promise<string>;
+    generateAesKey(length?: AesKeyLength): Promise<CryptoKey>;
+    encryptAes(key: CryptoKey, data: string | ArrayBuffer): Promise<AesEncryptResult>;
+    decryptAes(key: CryptoKey, ciphertext: ArrayBuffer, iv: Uint8Array<ArrayBuffer>): Promise<string>;
+    exportKey(key: CryptoKey): Promise<JsonWebKey>;
+    importAesKey(jwk: JsonWebKey): Promise<CryptoKey>;
+    generateRandomBytes(length: number): Uint8Array;
+    randomUUID(): string;
+    generateHmacKey(algorithm?: HmacAlgorithm): Promise<CryptoKey>;
+    /**
+     * Signs data with an HMAC key. Returns a hex-encoded signature.
+     */
+    sign(key: CryptoKey, data: string | ArrayBuffer): Promise<string>;
+    /**
+     * Verifies an HMAC signature (hex-encoded). Returns false for malformed input — never throws.
+     */
+    verify(key: CryptoKey, data: string | ArrayBuffer, signature: string): Promise<boolean>;
+    importHmacKey(jwk: JsonWebKey, algorithm?: HmacAlgorithm): Promise<CryptoKey>;
+    private bufferToHex;
+    private hexToBytes;
+    private hmacHashName;
+    static ɵfac: i0.ɵɵFactoryDeclaration<WebCryptoService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<WebCryptoService>;
+}
+
+type StorageTarget = 'local' | 'session';
+interface SecureStorageConfig {
+    storage?: StorageTarget;
+    pbkdf2Iterations?: number;
+}
+declare const SECURE_STORAGE_CONFIG: InjectionToken<SecureStorageConfig>;
+/**
+ * Service for transparent AES-GCM encrypted storage on top of localStorage/sessionStorage.
+ *
+ * Two key modes are supported:
+ * - **Ephemeral** (default): a CryptoKey is generated in memory per service instance.
+ *   Data is unrecoverable after page reload or service re-creation.
+ * - **Passphrase-derived**: call `initWithPassphrase(passphrase)` to derive a stable key
+ *   via PBKDF2. Data survives page reloads as long as the same passphrase is used.
+ *
+ * @example
+ * // Ephemeral mode
+ * await storage.set('token', { value: 'abc' });
+ * const token = await storage.get<{ value: string }>('token');
+ *
+ * @example
+ * // Passphrase mode
+ * await storage.initWithPassphrase('my-secret');
+ * await storage.set('user', { id: 1 }, 'auth');
+ * const user = await storage.get<{ id: number }>('user', 'auth');
+ */
+declare class SecureStorageService {
+    private readonly platformId;
+    private readonly storageConfig;
+    private activeKey;
+    constructor();
+    isSupported(): boolean;
+    /**
+     * Initializes the service with a passphrase-derived key (PBKDF2 + AES-GCM).
+     * The salt is automatically persisted in storage on first call and reused on subsequent calls.
+     * Calling this again replaces the active key.
+     *
+     * @param passphrase Secret passphrase for key derivation.
+     * @param explicitSalt Optional base64 salt. When provided, the stored salt is ignored.
+     */
+    initWithPassphrase(passphrase: string, explicitSalt?: string): Promise<void>;
+    /**
+     * Encrypts and stores a value.
+     * A fresh random IV is generated for every write.
+     *
+     * @throws {TypeError} When `value` is `undefined`.
+     * @throws {DOMException} When storage quota is exceeded.
+     */
+    set<T>(key: string, value: T, namespace?: string): Promise<void>;
+    /**
+     * Decrypts and returns a stored value.
+     * Returns `null` if the key does not exist, was written without encryption,
+     * or the ciphertext is corrupted.
+     */
+    get<T>(key: string, namespace?: string): Promise<T | null>;
+    /**
+     * Removes a single entry from storage.
+     */
+    remove(key: string, namespace?: string): void;
+    /**
+     * Clears all entries belonging to a namespace.
+     * When called without arguments, clears the entire storage target.
+     */
+    clear(namespace?: string): void;
+    private get nativeStorage();
+    private buildStorageKey;
+    private ensureKey;
+    private assertSupported;
+    private bytesToBase64;
+    private base64ToBytes;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SecureStorageService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SecureStorageService>;
+}
+
+interface SanitizerConfig {
+    allowedTags?: string[];
+    allowedAttributes?: Record<string, string[]>;
+}
+declare const SANITIZER_CONFIG: InjectionToken<SanitizerConfig>;
+/**
+ * Service for structured input sanitization to defend against XSS, URL injection, and unsafe HTML.
+ *
+ * This service is defense-in-depth and DOES NOT replace a Content Security Policy (CSP).
+ * Always configure a proper CSP alongside using this service.
+ *
+ * @example
+ * const clean = sanitizer.sanitizeHtml('<b>Hello</b><script>alert(1)</script>');
+ * // → '<b>Hello</b>'
+ *
+ * @example
+ * const url = sanitizer.sanitizeUrl('javascript:alert(1)');
+ * // → null
+ */
+declare class InputSanitizerService {
+    private readonly platformId;
+    private readonly allowedTags;
+    private readonly allowedAttributes;
+    constructor();
+    isSupported(): boolean;
+    /**
+     * Parses and sanitizes an HTML string, keeping only allowed tags and attributes.
+     * Script execution is prevented — parsing is done via DOMParser, not innerHTML assignment.
+     *
+     * @throws {Error} When called in a non-browser environment.
+     */
+    sanitizeHtml(input: string): string;
+    /**
+     * Validates and normalizes a URL string.
+     * Returns the normalized URL only for `http:` and `https:` schemes.
+     * Returns `null` for `javascript:`, `data:`, `vbscript:`, relative URLs, or malformed input.
+     */
+    sanitizeUrl(input: string): string | null;
+    /**
+     * Escapes HTML special characters for safe text interpolation.
+     * Use this when inserting user content into HTML text nodes or attributes.
+     */
+    escapeHtml(input: string): string;
+    /**
+     * Safely parses a JSON string. Returns the parsed value on success, `null` on any error.
+     * Does NOT use `eval` or `Function` — uses JSON.parse only.
+     */
+    sanitizeJson(input: string): unknown | null;
+    private processNode;
+    private sanitizeAttributes;
+    static ɵfac: i0.ɵɵFactoryDeclaration<InputSanitizerService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<InputSanitizerService>;
+}
+
+interface PasswordStrengthResult {
+    score: 0 | 1 | 2 | 3 | 4;
+    label: 'very-weak' | 'weak' | 'fair' | 'strong' | 'very-strong';
+    entropy: number;
+    feedback: string[];
+}
+/**
+ * Service for entropy-based password strength evaluation.
+ * All methods are synchronous and side-effect free — safely wrappable in Angular `computed()`.
+ *
+ * Score thresholds (bits of entropy):
+ * - 0 (very-weak):  < 28 bits
+ * - 1 (weak):       28–35 bits
+ * - 2 (fair):       36–49 bits
+ * - 3 (strong):     50–69 bits
+ * - 4 (very-strong): ≥ 70 bits
+ *
+ * @example
+ * const result = passwordStrength.assess('P@ssw0rd!');
+ * console.log(result.score);   // 2
+ * console.log(result.label);   // 'fair'
+ * console.log(result.entropy); // ~42.5
+ */
+declare class PasswordStrengthService {
+    /**
+     * Evaluates the strength of a password.
+     * Never throws — returns score 0 for empty or null-like input.
+     */
+    assess(password: string): PasswordStrengthResult;
+    private entropyToScore;
+    private containsSequence;
+    static ɵfac: i0.ɵɵFactoryDeclaration<PasswordStrengthService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<PasswordStrengthService>;
+}
+
 interface SecurityConfig {
     enableRegexSecurity?: boolean;
+    enableWebCrypto?: boolean;
+    enableSecureStorage?: boolean;
+    enableInputSanitizer?: boolean;
+    enablePasswordStrength?: boolean;
     defaultTimeout?: number;
     safeMode?: boolean;
 }
 declare const defaultSecurityConfig: SecurityConfig;
 declare function provideSecurity(config?: SecurityConfig): EnvironmentProviders;
 declare function provideRegexSecurity(): EnvironmentProviders;
+declare function provideWebCrypto(): EnvironmentProviders;
+declare function provideSecureStorage(config?: SecureStorageConfig): EnvironmentProviders;
+declare function provideInputSanitizer(config?: SanitizerConfig): EnvironmentProviders;
+declare function providePasswordStrength(): EnvironmentProviders;
 
-export { RegexSecurityBuilder, RegexSecurityService, defaultSecurityConfig, provideRegexSecurity, provideSecurity };
-export type { RegexBuilderOptions, RegexSecurityConfig, RegexSecurityResult, RegexTestResult, SecurityConfig };
+export { InputSanitizerService, PasswordStrengthService, RegexSecurityBuilder, RegexSecurityService, SANITIZER_CONFIG, SECURE_STORAGE_CONFIG, SecureStorageService, WebCryptoService, defaultSecurityConfig, provideInputSanitizer, providePasswordStrength, provideRegexSecurity, provideSecureStorage, provideSecurity, provideWebCrypto };
+export type { AesEncryptResult, AesKeyLength, HashAlgorithm, HmacAlgorithm, PasswordStrengthResult, RegexBuilderOptions, RegexSecurityConfig, RegexSecurityResult, RegexTestResult, SanitizerConfig, SecureStorageConfig, SecurityConfig, StorageTarget };