@angular-helpers/security 21.1.0 → 21.3.0

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