@angular-helpers/security 21.2.0 → 21.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@angular-helpers/security",
-  "version": "21.2.0",
+  "version": "21.4.1",
   "description": "Angular security helpers for preventing ReDoS and other security vulnerabilities",
   "keywords": [
     "angular",
@@ -16,7 +16,12 @@
     "xss",
     "sanitization",
     "password-strength",
-    "secure-storage"
+    "secure-storage",
+    "session-idle",
+    "inactivity",
+    "postmessage",
+    "iframe",
+    "secure-channel"
   ],
   "author": "Angular Helpers Team",
   "license": "MIT",
@@ -34,8 +39,14 @@
   "peerDependencies": {
     "@angular/common": "^21.0.0",
     "@angular/core": "^21.0.0",
+    "@angular/forms": "^21.0.0",
     "rxjs": "^7.0.0 || ^8.0.0"
   },
+  "peerDependenciesMeta": {
+    "@angular/forms": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "tslib": "^2.0.0"
   },
@@ -48,7 +59,16 @@
     ".": {
       "types": "./types/angular-helpers-security.d.ts",
       "default": "./fesm2022/angular-helpers-security.mjs"
+    },
+    "./forms": {
+      "types": "./types/angular-helpers-security-forms.d.ts",
+      "default": "./fesm2022/angular-helpers-security-forms.mjs"
+    },
+    "./signal-forms": {
+      "types": "./types/angular-helpers-security-signal-forms.d.ts",
+      "default": "./fesm2022/angular-helpers-security-signal-forms.mjs"
     }
   },
-  "sideEffects": false
+  "sideEffects": false,
+  "type": "module"
 }

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

@@ -0,0 +1,65 @@
+import { ValidatorFn } from '@angular/forms';
+import { HtmlSanitizerOptions, PasswordScore } from '@angular-helpers/security';
+
+interface StrongPasswordOptions {
+    minScore?: PasswordScore;
+}
+interface SafeUrlOptions {
+    schemes?: readonly string[];
+}
+type SafeHtmlOptions = HtmlSanitizerOptions;
+/**
+ * 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:'] })]),
+ * });
+ */
+declare 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?: StrongPasswordOptions): ValidatorFn;
+    /**
+     * 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?: SafeHtmlOptions): ValidatorFn;
+    /**
+     * 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?: SafeUrlOptions): ValidatorFn;
+    /**
+     * 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(): ValidatorFn;
+    /**
+     * 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(): ValidatorFn;
+}
+
+export { SecurityValidators };
+export type { SafeHtmlOptions, SafeUrlOptions, StrongPasswordOptions };

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

@@ -0,0 +1,99 @@
+import { PathKind, SchemaPath, SchemaPathRules } from '@angular/forms/signals';
+import { HtmlSanitizerOptions, PasswordScore } from '@angular-helpers/security';
+
+/**
+ * Options for {@link strongPassword}.
+ */
+interface StrongPasswordRuleOptions {
+    /** Minimum acceptable score (0..4). Default: `2` (fair). */
+    minScore?: PasswordScore;
+    /** Custom message shown to the user. Default: `'Password is too weak'`. */
+    message?: string;
+}
+/**
+ * Options for {@link safeUrl}.
+ */
+interface SafeUrlRuleOptions {
+    /** Allowed URL schemes including the trailing colon. Default: `['http:', 'https:']`. */
+    schemes?: readonly string[];
+    /** Custom message. Default: `'URL scheme is not allowed'`. */
+    message?: string;
+}
+/**
+ * Options for {@link safeHtml}.
+ */
+interface SafeHtmlRuleOptions extends HtmlSanitizerOptions {
+    /** Custom message. Default: `'Value contains unsafe HTML'`. */
+    message?: string;
+}
+/**
+ * Options for {@link noScriptInjection} and {@link noSqlInjectionHints}.
+ */
+interface PatternRuleOptions {
+    /** Custom message. Default varies per rule. */
+    message?: string;
+}
+/**
+ * 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 });
+ * });
+ */
+declare function strongPassword<TPathKind extends PathKind = PathKind.Root>(path: SchemaPath<string, SchemaPathRules.Supported, TPathKind>, options?: StrongPasswordRuleOptions): void;
+/**
+ * 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.
+ */
+declare function safeHtml<TPathKind extends PathKind = PathKind.Root>(path: SchemaPath<string, SchemaPathRules.Supported, TPathKind>, options?: SafeHtmlRuleOptions): void;
+/**
+ * Registers a sync validation rule that fails for malformed URLs or URLs using schemes
+ * outside the allowlist (default: `http:` and `https:`).
+ */
+declare function safeUrl<TPathKind extends PathKind = PathKind.Root>(path: SchemaPath<string, SchemaPathRules.Supported, TPathKind>, options?: SafeUrlRuleOptions): void;
+/**
+ * Registers a sync validation rule that rejects values matching common script-injection
+ * sentinels (`<script>`, `javascript:`, inline event handlers).
+ */
+declare function noScriptInjection<TPathKind extends PathKind = PathKind.Root>(path: SchemaPath<string, SchemaPathRules.Supported, TPathKind>, options?: PatternRuleOptions): void;
+/**
+ * Registers a sync validation rule that rejects common SQL-injection sentinel strings.
+ * Intended as defense-in-depth alongside server-side parameterized queries.
+ */
+declare function noSqlInjectionHints<TPathKind extends PathKind = PathKind.Root>(path: SchemaPath<string, SchemaPathRules.Supported, TPathKind>, options?: PatternRuleOptions): void;
+/**
+ * Options for {@link hibpPassword}.
+ */
+interface HibpPasswordRuleOptions {
+    /** Custom message. Default: `'This password has appeared in a data breach'`. */
+    message?: string;
+    /** Debounce value changes before contacting HIBP. Default: `300` ms. */
+    debounceMs?: number;
+}
+/**
+ * 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);
+ * });
+ */
+declare function hibpPassword<TPathKind extends PathKind = PathKind.Root>(path: SchemaPath<string, SchemaPathRules.Supported, TPathKind>, options?: HibpPasswordRuleOptions): void;
+
+export { hibpPassword, noScriptInjection, noSqlInjectionHints, safeHtml, safeUrl, strongPassword };
+export type { HibpPasswordRuleOptions, PatternRuleOptions, SafeHtmlRuleOptions, SafeUrlRuleOptions, StrongPasswordRuleOptions };