@asaidimu/utils-sanitize 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Saidimu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,238 @@
+# `@asaidimu/utils-sanitize`
+
+Field-level sanitization for documents, with support for configurable masking policies, recursive deep sanitization, multi-scope configuration merging, and HMAC-based hashing. Works in browsers and Node.js 18+ (Web Crypto API).
+
+## Installation
+
+```bash
+npm install @asaidimu/utils-sanitize
+```
+
+## Quick Start
+
+```typescript
+import { Sanitizer, DocumentSanitizer, newSecureDefaultConfig } from "@asaidimu/utils-sanitize";
+
+// Create a sanitizer with common security patterns
+const config = newSecureDefaultConfig();
+const sanitizer = new DocumentSanitizer(config, "my-scope");
+
+const doc = {
+  username: "alice",
+  password: "supersecret",
+  email: "alice@example.com",
+  ssn: "123-45-6789",
+  notes: "hello world",
+};
+
+const result = await sanitizer.sanitizeDocumentDeep(doc);
+// {
+//   username: "alice",
+//   password: "***",
+//   email:    "al*********om",
+//   ssn:      "***",
+//   notes:    "hello world",
+// }
+```
+
+## Policies
+
+| Policy | Constant | Effect |
+|--------|----------|--------|
+| `"redact"` | `MaskRedact` | Replaces value with `"***"` |
+| `"hash"` | `MaskHash` | Replaces value with `[HASH:XXXXXXXX]` (first 8 hex chars of HMAC-SHA256) |
+| `"obscure"` | `MaskObscure` | Shows prefix/suffix characters, replaces middle with a character (default: `*`) |
+| `"preserve"` | `MaskPreserve` | Leaves the value unchanged (default) |
+
+### Policy Resolution Order
+
+When resolving which policy applies to a field:
+
+1. **Explicit field mapping** (`config.fields`) — highest priority
+2. **Pattern rules** (`config.patterns`) — evaluated in declaration order, first match wins
+3. **Default policy** (`config.defaultPolicy`) — fallback when no rule matches
+
+### Restrictiveness Ordering
+
+redact > hash > obscure > preserve
+
+Use `mostRestrictivePolicy(a, b)` to get the more restrictive of two policies.
+
+## API
+
+### Core Types
+
+```typescript
+type MaskedFieldPolicy = "redact" | "hash" | "preserve" | "obscure";
+```
+
+### `Sanitizer`
+
+Flat-document sanitizer. Applies policies to top-level fields only.
+
+```typescript
+const s = new Sanitizer(config, logger?);
+
+// Sanitize a single value
+await s.sanitizeValue("fieldName", value);
+
+// Sanitize a flat document
+await s.sanitizeDocument({ field: value, ... });
+```
+
+### `DocumentSanitizer`
+
+Extends `Sanitizer` with recursive deep sanitization and metadata handling.
+
+```typescript
+const ds = new DocumentSanitizer(config, scopeID, logger?);
+
+// Deep sanitization (nested objects, arrays)
+await ds.sanitizeDocumentDeep(doc);
+
+// Sanitize only metadata (preserves reserved system fields)
+await ds.sanitizeMetadata(metadata);
+```
+
+**Deep sanitization behaviour:**
+
+- **Plain objects** — recursed, each key sanitized independently (policies are not inherited from parent field names)
+- **Arrays** — recursed element-by-element
+  - Objects inside arrays have each key sanitized independently
+  - Scalars inside arrays inherit the parent field's policy via `<fieldName>[]` lookup
+- **Dates** and **Uint8Arrays** — treated as scalars (not recursed)
+- **`_metadata_`** — special handling: system fields (`_version_`, `_created_`, `_updated_`, `_checksum_`, `_signature_`) are preserved; user-defined fields are sanitized
+
+### `FieldMaskConfig`
+
+```typescript
+interface FieldMaskConfig {
+  version?: string;
+  scope?: string;
+  defaultPolicy?: MaskedFieldPolicy;       // default: "preserve"
+  fields?: Record<string, MaskedFieldPolicy>;
+  patterns?: PatternRule[];
+  obscureConfig?: ObscureConfig;
+  hashSecret?: string;                      // hex-encoded, ≥ 32 hex chars
+  description?: string;
+}
+```
+
+### `ObscureConfig`
+
+```typescript
+interface ObscureConfig {
+  prefixLength: number;    // chars to show at start (default: 2)
+  suffixLength: number;    // chars to show at end (default: 2)
+  replacement: string;     // middle replacement char (default: "*")
+  maxLength: number;       // normalize output length (0 = no limit, default: 0)
+}
+```
+
+When `maxLength` is set, the output is normalised to exactly `maxLength`, hiding the original value's length:
+
+| Original | `maxLength=12` | Notes |
+|----------|----------------|-------|
+| `"abc123"` | `"ab******23"` | Padded to 12 |
+| `"1ea82440-9c3e"` | `"1ea8****9c3e"` | Exact fit |
+| `"1ea82440-…-2651"` | `"1ea8****2651"` | Truncated to 12 |
+
+Values shorter than `prefixLength + suffixLength + 1` are rendered as `"[OBSCURED]"`.
+
+### `PatternRule`
+
+```typescript
+interface PatternRule {
+  pattern: string;           // regex source string
+  policy: MaskedFieldPolicy;
+  comment?: string;          // human-readable description
+  readonly _regex?: RegExp;  // compiled regex (non-enumerable, internal)
+}
+```
+
+### Config Validation
+
+`validateConfig(config)` validates a `FieldMaskConfig`, mutating it to apply defaults. Throws `SystemError` aggregating all validation errors when any are found (severity: `"error"`). Warnings (e.g., `maxLength` too small) are collected but do not throw.
+
+### Configuration Merging
+
+```typescript
+mergeConfigs(globalConfig, scopedConfig): FieldMaskConfig
+```
+
+Merges a global config with a scoped config for multi-scope setups:
+
+- **Fields** — global baseline, scoped overrides (scoped wins on collision)
+- **Patterns** — scoped patterns evaluated first (higher priority); scoped patterns shadow global patterns with the same regex source
+- **Default policy** — scoped wins, then global, then `"preserve"`
+- **Obscure config** — scoped wins when it has a `replacement` char
+- **Hash secret** — scoped wins
+
+Does not mutate either input.
+
+### Helpers
+
+```typescript
+// Field policy parsing
+parseMaskedFieldPolicy(s: string): MaskedFieldPolicy;  // throws SystemError on invalid
+
+// Policy comparison
+mostRestrictivePolicy(a, b): MaskedFieldPolicy;
+
+// Pattern compilation
+compilePattern(pattern, policy, comment?): PatternRule;     // throws SystemError on invalid regex
+mustCompilePattern(pattern, policy, comment?): PatternRule;  // alias (for static init)
+
+// Pre-built patterns
+commonSecurityPatterns(): PatternRule[];     // 11 common patterns (password, email, SSN, etc.)
+newSecureDefaultConfig(): FieldMaskConfig;    // config with common patterns + defaults
+
+// Batch sanitization
+sanitizeDocumentArray(sanitizer, docs[]): Promise<Record<string, unknown>[]>;
+sanitizeAnyValue(sanitizer, value): Promise<unknown>;  // auto-detect object/array/scalar
+```
+
+### `commonSecurityPatterns()` — included patterns
+
+| Pattern | Policy | Field examples |
+|---------|--------|----------------|
+| `password` | redact | `password`, `userPassword` |
+| `secret` | redact | `secret`, `my_secret` |
+| `token` | redact | `token`, `auth_token` |
+| `api[_-]?key` | redact | `api_key`, `apikey`, `api-key` |
+| `private[_-]?key` | redact | `private_key` |
+| `credential` | redact | `credential`, `credentials` |
+| `ssn\|social[_-]?security` | redact | `ssn`, `social_security` |
+| `credit[_-]?card\|cvv` | redact | `credit_card`, `cvv` |
+| `email` | obscure | `email`, `userEmail` |
+| `phone\|mobile` | obscure | `phone`, `mobile` |
+| `auth` | hash | `auth`, `authToken` |
+
+## Hash Details
+
+- Uses **HMAC-SHA256** via the Web Crypto API (`crypto.subtle.sign`)
+- Output format: `[HASH:XXXXXXXX]` (first 8 hex chars)
+- Each `Sanitizer` instance uses a per-instance random 32-byte secret when `hashSecret` is not provided, preventing rainbow-table attacks
+- Consistent secret across instances = consistent hashes for the same input values
+
+## Obscure Details
+
+- Uses `TextDecoder` for `Uint8Array` values
+- Falls back to `String()` for all other types
+- With `maxLength > 0`, the output is normalised to exactly `maxLength` characters, hiding the original length
+
+## Error Handling
+
+The module throws `SystemError` (from `@core/error`) with structured error codes:
+
+| Code | Scenario |
+|------|----------|
+| `ERR_SANITIZATION_CONFIG_INVALID` | Config validation failed |
+| `ERR_INVALID_POLICY` | Unknown policy string |
+| `ERR_EMPTY_PATTERN` | Pattern string is empty |
+| `ERR_INVALID_REGEX` | Pattern regex failed to compile |
+| `ERR_INVALID_CONFIG` | Invalid obscure config or hash secret |
+| `ERR_SANITIZATION_PATTERN_INVALID` | `compilePattern` received invalid regex |
+| `ERR_SANITIZATION_FAILED` | Document sanitization failed (batch operations) |
+
+On invalid config, `Sanitizer` and `DocumentSanitizer` constructors fall back to a **preserve-all** default and log the error — they never throw from the constructor.

package/index.d.cts

@@ -0,0 +1,246 @@
+//#region src/logger/logger.d.ts
+/**
+ * Represents the severity level of a system log entry.
+ * Levels are ordered by increasing severity: trace, debug, info, warn, error.
+ */
+type LogLevel = "trace" | "debug" | "info" | "warn" | "error";
+/**
+ * Structure representing a fully contextualized system log entry ready for sinking.
+ */
+interface SystemLog {
+  /** The severity level of the log. */
+  level: LogLevel;
+  /** A clear, human-readable string identifying the distinct event (e.g., "user_login_failed"). */
+  event: string;
+  /** Additional structured data specific to this log instantiation. */
+  data?: object;
+  /** Contextual data shared across the logger instance (e.g., traceIds, environment). */
+  context?: object;
+  /** Epoch timestamp in milliseconds denoting when the log event occurred. */
+  timestamp: number;
+}
+/**
+ * Primary logger interface providing level-specific log dispatching and context-chaining.
+ */
+interface SystemLogger {
+  /** Logs high-volume, extremely fine-grained diagnostic details. */
+  trace(event: string, data?: object): void;
+  /** Logs diagnostic information useful during local development or debugging. */
+  debug(event: string, data?: object): void;
+  /** Logs standard operational events that track the healthy flow of the system. */
+  info(event: string, data?: object): void;
+  /** Alias for the `info` logging method. */
+  log(event: string, data?: object): void;
+  /** Logs non-fatal operational anomalies or conditions that deserve attention. */
+  warn(event: string, data?: object): void;
+  /** Logs critical errors, failures, or exceptions preventing a transaction/process. */
+  error(event: string, data?: unknown): void;
+  /**
+   * Directly forwards a pre-constructed `SystemLog` record through the logger's pipeline.
+   * Combines instance context before outputting.
+   */
+  write(record: SystemLog): void;
+  /**
+   * Generates a new `SystemLogger` instance that shares the existing sinks and parent
+   * context, deeply merging the newly provided context on top.
+   *
+   * @param context - The metadata to append to all subsequent logs emitted by the child logger.
+   */
+  child(context: object): SystemLogger;
+}
+//#endregion
+//#region src/sanitize/index.d.ts
+/** Defines how a field should be treated during sanitization. */
+type MaskedFieldPolicy = "redact" | "hash" | "preserve" | "obscure";
+declare const MaskRedact: MaskedFieldPolicy;
+declare const MaskHash: MaskedFieldPolicy;
+declare const MaskPreserve: MaskedFieldPolicy;
+declare const MaskObscure: MaskedFieldPolicy;
+/**
+ * Parses a string into a MaskedFieldPolicy.
+ * Throws a SystemError if the string is not a valid policy.
+ */
+declare function parseMaskedFieldPolicy(s: string): MaskedFieldPolicy;
+/** Returns the more restrictive of two policies. */
+declare function mostRestrictivePolicy(a: MaskedFieldPolicy, b: MaskedFieldPolicy): MaskedFieldPolicy;
+/** Allows regex-based matching on field names. */
+interface PatternRule {
+  /** Regex source string. */
+  pattern: string;
+  /** Masking policy applied when pattern matches. */
+  policy: MaskedFieldPolicy;
+  /** Human-readable description. */
+  comment?: string;
+  /**
+   * Compiled regex — populated during validateConfig(). Internal use only.
+   * Non-enumerable so it does not appear in JSON.stringify output.
+   */
+  readonly _regex?: RegExp;
+}
+/** Controls how MaskObscure renders its output. */
+interface ObscureConfig {
+  /** Number of characters to reveal at the start. */
+  prefixLength: number;
+  /** Number of characters to reveal at the end. */
+  suffixLength: number;
+  /** Replacement character for the obscured portion (default: `"*"`). */
+  replacement: string;
+  /**
+   * Maximum total length of the obscured output (0 = no limit).
+   * When set, the output is normalised to exactly this length,
+   * hiding the original value's length.
+   *
+   * Example with maxLength=12:
+   *   Short:   "abc123"           → "ab******23"   (padded to 12)
+   *   Medium:  "1ea82440-9c3e"    → "1ea8****9c3e" (exact fit)
+   *   Long:    "1ea82440-…-2651"  → "1ea8****2651" (truncated to 12)
+   *
+   * Values shorter than prefixLength + suffixLength + 1 are shown as "[OBSCURED]".
+   */
+  maxLength: number;
+}
+declare function defaultObscureConfig(): ObscureConfig;
+/** Configuration for a field-masking sanitizer. */
+interface FieldMaskConfig {
+  /** Semantic version for forward compatibility. */
+  version?: string;
+  /** Scope identifier — must be non-empty when used in multi-scope setups. */
+  scope?: string;
+  /** Policy applied when no explicit rule matches a field. Defaults to `"preserve"`. */
+  defaultPolicy?: MaskedFieldPolicy;
+  /** Explicit field-name → policy mapping (highest priority). */
+  fields?: Record<string, MaskedFieldPolicy>;
+  /** Regex-based rules evaluated after `fields`. */
+  patterns?: PatternRule[];
+  /** Controls MaskObscure rendering. */
+  obscureConfig?: ObscureConfig;
+  /**
+   * Hex-encoded HMAC secret (≥ 32 hex chars / 16 bytes).
+   * If omitted, a cryptographically random secret is generated per instance.
+   */
+  hashSecret?: string;
+  /** Human-readable context. */
+  description?: string;
+}
+interface ValidationIssue {
+  code: string;
+  message: string;
+  path?: string;
+  index?: number;
+  severity: "error" | "warning";
+}
+/**
+ * Validates a FieldMaskConfig, mutating it to set defaults where appropriate.
+ * Throws a SystemError aggregating all validation errors if any are found.
+ *
+ * Safe to call in any environment — no Node.js APIs used.
+ */
+declare function validateConfig(config: FieldMaskConfig): void;
+/** Handles field masking based on a FieldMaskConfig. */
+declare class Sanitizer {
+  protected readonly config: FieldMaskConfig;
+  protected readonly logger: SystemLogger;
+  /** Raw secret bytes — kept for reference; actual signing uses cryptoKeyPromise. */
+  protected readonly hashSecretBytes: Uint8Array;
+  /**
+   * Lazily-imported CryptoKey for HMAC-SHA256.
+   * Imported once and reused across all hashValue() calls on this instance.
+   */
+  protected readonly cryptoKeyPromise: Promise<CryptoKey>;
+  /**
+   * Creates a new Sanitizer.
+   *
+   * Validates the config and applies defaults. If the config is invalid, falls
+   * back to a preserve-all default and logs the error.
+   *
+   * If `config.hashSecret` is not provided, a cryptographically random 32-byte
+   * secret is generated per instance via `crypto.getRandomValues`, preventing
+   * rainbow-table attacks on hashed values.
+   */
+  constructor(config: FieldMaskConfig, logger?: SystemLogger);
+  /**
+   * Applies masking rules to a flat document.
+   * Returns a new object — the original is never mutated.
+   */
+  sanitizeDocument(doc: Record<string, unknown>): Promise<Record<string, unknown>>;
+  /** Applies masking to a single named value. */
+  sanitizeValue(fieldName: string, value: unknown): Promise<unknown>;
+  /** Resolves which policy applies to a given field name. */
+  protected getPolicyForField(fieldName: string): MaskedFieldPolicy;
+  /** Applies the given masking policy to a value. */
+  protected applyPolicy(fieldName: string, value: unknown, policy: MaskedFieldPolicy): Promise<unknown>;
+  /**
+   * Creates a short HMAC-SHA256 hash of the value using the Web Crypto API.
+   * Uses a per-sanitizer secret to prevent rainbow-table attacks.
+   * Returns `[HASH:<8 hex chars>]`.
+   */
+  protected hashValue(value: unknown): Promise<string>;
+  /**
+   * Shows first/last characters with the middle replaced by `obscureConfig.replacement`.
+   * When `maxLength` is set, the output is normalised to exactly that length.
+   * Synchronous — no crypto involved.
+   */
+  protected obscureValue(value: unknown): string;
+}
+/** Extends Sanitizer with recursive document and metadata handling. */
+declare class DocumentSanitizer extends Sanitizer {
+  private readonly scopeID;
+  constructor(config: FieldMaskConfig, scopeID: string, logger?: SystemLogger);
+  /**
+   * Performs deep sanitization of a document, recursing into nested objects and arrays.
+   * Returns a new object — the original is never mutated.
+   */
+  sanitizeDocumentDeep(doc: Record<string, unknown>): Promise<Record<string, unknown>>;
+  /** Sanitizes a metadata map: system fields are preserved, user-defined fields are sanitized. */
+  sanitizeMetadata(metadata: Record<string, unknown>): Promise<Record<string, unknown>>;
+  /** Recursively sanitizes a value, descending into nested maps and arrays. */
+  private sanitizeValueDeep;
+  protected applyPolicy(fieldName: string, value: unknown, policy: MaskedFieldPolicy): Promise<unknown>;
+}
+/**
+ * Merges a global config with a scoped config.
+ *
+ * Priority rules:
+ * - Scoped field mappings override global field mappings.
+ * - Scoped patterns shadow global patterns with the same regex source string,
+ *   and are evaluated first (higher priority) in the merged result.
+ * - Scoped default policy, obscure config, and hash secret each override
+ *   global when present.
+ *
+ * Does not mutate either input — returns a fresh FieldMaskConfig.
+ */
+declare function mergeConfigs(globalConfig: FieldMaskConfig | null, scopedConfig: FieldMaskConfig): FieldMaskConfig;
+/**
+ * Compiles a regex pattern and returns a PatternRule with the compiled regex attached.
+ * Throws a SystemError if the regex is invalid.
+ */
+declare function compilePattern(pattern: string, policy: MaskedFieldPolicy, comment?: string): PatternRule;
+/**
+ * Compiles a pattern and throws on error.
+ * Use only for static initialization at module load time.
+ */
+declare function mustCompilePattern(pattern: string, policy: MaskedFieldPolicy, comment?: string): PatternRule;
+/**
+ * Returns a set of commonly used security-oriented masking patterns.
+ *
+ * Note: Go's inline `(?i)` flag is replaced with the JS `i` regex flag,
+ * which is semantically equivalent for ASCII field names.
+ */
+declare function commonSecurityPatterns(): PatternRule[];
+/** Creates a FieldMaskConfig pre-loaded with common security patterns. */
+declare function newSecureDefaultConfig(): FieldMaskConfig;
+/**
+ * Sanitizes an array of documents using the same DocumentSanitizer instance.
+ * Returns a new array — originals are not mutated.
+ * Throws a SystemError if any document fails sanitization.
+ */
+declare function sanitizeDocumentArray(sanitizer: DocumentSanitizer, docs: Record<string, unknown>[]): Promise<Record<string, unknown>[]>;
+/**
+ * Sanitizes any value that might be or contain documents.
+ * - Plain objects are treated as documents and sanitized deeply.
+ * - Arrays are recursed element-by-element.
+ * - Scalars are returned as-is (no field-name context at the top level).
+ */
+declare function sanitizeValue(sanitizer: DocumentSanitizer, value: unknown): Promise<unknown>;
+//#endregion
+export { DocumentSanitizer, FieldMaskConfig, MaskHash, MaskObscure, MaskPreserve, MaskRedact, MaskedFieldPolicy, ObscureConfig, PatternRule, Sanitizer, ValidationIssue, commonSecurityPatterns, compilePattern, defaultObscureConfig, mergeConfigs, mostRestrictivePolicy, mustCompilePattern, newSecureDefaultConfig, parseMaskedFieldPolicy, sanitizeDocumentArray, sanitizeValue, validateConfig };

package/index.d.ts

@@ -0,0 +1,197 @@
+import { SystemLogger } from "@asaidimu/utils-logger";
+
+//#region src/sanitize/index.d.ts
+/** Defines how a field should be treated during sanitization. */
+type MaskedFieldPolicy = "redact" | "hash" | "preserve" | "obscure";
+declare const MaskRedact: MaskedFieldPolicy;
+declare const MaskHash: MaskedFieldPolicy;
+declare const MaskPreserve: MaskedFieldPolicy;
+declare const MaskObscure: MaskedFieldPolicy;
+/**
+ * Parses a string into a MaskedFieldPolicy.
+ * Throws a SystemError if the string is not a valid policy.
+ */
+declare function parseMaskedFieldPolicy(s: string): MaskedFieldPolicy;
+/** Returns the more restrictive of two policies. */
+declare function mostRestrictivePolicy(a: MaskedFieldPolicy, b: MaskedFieldPolicy): MaskedFieldPolicy;
+/** Allows regex-based matching on field names. */
+interface PatternRule {
+  /** Regex source string. */
+  pattern: string;
+  /** Masking policy applied when pattern matches. */
+  policy: MaskedFieldPolicy;
+  /** Human-readable description. */
+  comment?: string;
+  /**
+   * Compiled regex — populated during validateConfig(). Internal use only.
+   * Non-enumerable so it does not appear in JSON.stringify output.
+   */
+  readonly _regex?: RegExp;
+}
+/** Controls how MaskObscure renders its output. */
+interface ObscureConfig {
+  /** Number of characters to reveal at the start. */
+  prefixLength: number;
+  /** Number of characters to reveal at the end. */
+  suffixLength: number;
+  /** Replacement character for the obscured portion (default: `"*"`). */
+  replacement: string;
+  /**
+   * Maximum total length of the obscured output (0 = no limit).
+   * When set, the output is normalised to exactly this length,
+   * hiding the original value's length.
+   *
+   * Example with maxLength=12:
+   *   Short:   "abc123"           → "ab******23"   (padded to 12)
+   *   Medium:  "1ea82440-9c3e"    → "1ea8****9c3e" (exact fit)
+   *   Long:    "1ea82440-…-2651"  → "1ea8****2651" (truncated to 12)
+   *
+   * Values shorter than prefixLength + suffixLength + 1 are shown as "[OBSCURED]".
+   */
+  maxLength: number;
+}
+declare function defaultObscureConfig(): ObscureConfig;
+/** Configuration for a field-masking sanitizer. */
+interface FieldMaskConfig {
+  /** Semantic version for forward compatibility. */
+  version?: string;
+  /** Scope identifier — must be non-empty when used in multi-scope setups. */
+  scope?: string;
+  /** Policy applied when no explicit rule matches a field. Defaults to `"preserve"`. */
+  defaultPolicy?: MaskedFieldPolicy;
+  /** Explicit field-name → policy mapping (highest priority). */
+  fields?: Record<string, MaskedFieldPolicy>;
+  /** Regex-based rules evaluated after `fields`. */
+  patterns?: PatternRule[];
+  /** Controls MaskObscure rendering. */
+  obscureConfig?: ObscureConfig;
+  /**
+   * Hex-encoded HMAC secret (≥ 32 hex chars / 16 bytes).
+   * If omitted, a cryptographically random secret is generated per instance.
+   */
+  hashSecret?: string;
+  /** Human-readable context. */
+  description?: string;
+}
+interface ValidationIssue {
+  code: string;
+  message: string;
+  path?: string;
+  index?: number;
+  severity: "error" | "warning";
+}
+/**
+ * Validates a FieldMaskConfig, mutating it to set defaults where appropriate.
+ * Throws a SystemError aggregating all validation errors if any are found.
+ *
+ * Safe to call in any environment — no Node.js APIs used.
+ */
+declare function validateConfig(config: FieldMaskConfig): void;
+/** Handles field masking based on a FieldMaskConfig. */
+declare class Sanitizer {
+  protected readonly config: FieldMaskConfig;
+  protected readonly logger: SystemLogger;
+  /** Raw secret bytes — kept for reference; actual signing uses cryptoKeyPromise. */
+  protected readonly hashSecretBytes: Uint8Array;
+  /**
+   * Lazily-imported CryptoKey for HMAC-SHA256.
+   * Imported once and reused across all hashValue() calls on this instance.
+   */
+  protected readonly cryptoKeyPromise: Promise<CryptoKey>;
+  /**
+   * Creates a new Sanitizer.
+   *
+   * Validates the config and applies defaults. If the config is invalid, falls
+   * back to a preserve-all default and logs the error.
+   *
+   * If `config.hashSecret` is not provided, a cryptographically random 32-byte
+   * secret is generated per instance via `crypto.getRandomValues`, preventing
+   * rainbow-table attacks on hashed values.
+   */
+  constructor(config: FieldMaskConfig, logger?: SystemLogger);
+  /**
+   * Applies masking rules to a flat document.
+   * Returns a new object — the original is never mutated.
+   */
+  sanitizeDocument(doc: Record<string, unknown>): Promise<Record<string, unknown>>;
+  /** Applies masking to a single named value. */
+  sanitizeValue(fieldName: string, value: unknown): Promise<unknown>;
+  /** Resolves which policy applies to a given field name. */
+  protected getPolicyForField(fieldName: string): MaskedFieldPolicy;
+  /** Applies the given masking policy to a value. */
+  protected applyPolicy(fieldName: string, value: unknown, policy: MaskedFieldPolicy): Promise<unknown>;
+  /**
+   * Creates a short HMAC-SHA256 hash of the value using the Web Crypto API.
+   * Uses a per-sanitizer secret to prevent rainbow-table attacks.
+   * Returns `[HASH:<8 hex chars>]`.
+   */
+  protected hashValue(value: unknown): Promise<string>;
+  /**
+   * Shows first/last characters with the middle replaced by `obscureConfig.replacement`.
+   * When `maxLength` is set, the output is normalised to exactly that length.
+   * Synchronous — no crypto involved.
+   */
+  protected obscureValue(value: unknown): string;
+}
+/** Extends Sanitizer with recursive document and metadata handling. */
+declare class DocumentSanitizer extends Sanitizer {
+  private readonly scopeID;
+  constructor(config: FieldMaskConfig, scopeID: string, logger?: SystemLogger);
+  /**
+   * Performs deep sanitization of a document, recursing into nested objects and arrays.
+   * Returns a new object — the original is never mutated.
+   */
+  sanitizeDocumentDeep(doc: Record<string, unknown>): Promise<Record<string, unknown>>;
+  /** Sanitizes a metadata map: system fields are preserved, user-defined fields are sanitized. */
+  sanitizeMetadata(metadata: Record<string, unknown>): Promise<Record<string, unknown>>;
+  /** Recursively sanitizes a value, descending into nested maps and arrays. */
+  private sanitizeValueDeep;
+  protected applyPolicy(fieldName: string, value: unknown, policy: MaskedFieldPolicy): Promise<unknown>;
+}
+/**
+ * Merges a global config with a scoped config.
+ *
+ * Priority rules:
+ * - Scoped field mappings override global field mappings.
+ * - Scoped patterns shadow global patterns with the same regex source string,
+ *   and are evaluated first (higher priority) in the merged result.
+ * - Scoped default policy, obscure config, and hash secret each override
+ *   global when present.
+ *
+ * Does not mutate either input — returns a fresh FieldMaskConfig.
+ */
+declare function mergeConfigs(globalConfig: FieldMaskConfig | null, scopedConfig: FieldMaskConfig): FieldMaskConfig;
+/**
+ * Compiles a regex pattern and returns a PatternRule with the compiled regex attached.
+ * Throws a SystemError if the regex is invalid.
+ */
+declare function compilePattern(pattern: string, policy: MaskedFieldPolicy, comment?: string): PatternRule;
+/**
+ * Compiles a pattern and throws on error.
+ * Use only for static initialization at module load time.
+ */
+declare function mustCompilePattern(pattern: string, policy: MaskedFieldPolicy, comment?: string): PatternRule;
+/**
+ * Returns a set of commonly used security-oriented masking patterns.
+ *
+ * Note: Go's inline `(?i)` flag is replaced with the JS `i` regex flag,
+ * which is semantically equivalent for ASCII field names.
+ */
+declare function commonSecurityPatterns(): PatternRule[];
+/** Creates a FieldMaskConfig pre-loaded with common security patterns. */
+declare function newSecureDefaultConfig(): FieldMaskConfig;
+/**
+ * Sanitizes an array of documents using the same DocumentSanitizer instance.
+ * Returns a new array — originals are not mutated.
+ * Throws a SystemError if any document fails sanitization.
+ */
+declare function sanitizeDocumentArray(sanitizer: DocumentSanitizer, docs: Record<string, unknown>[]): Promise<Record<string, unknown>[]>;
+/**
+ * Sanitizes any value that might be or contain documents.
+ * - Plain objects are treated as documents and sanitized deeply.
+ * - Arrays are recursed element-by-element.
+ * - Scalars are returned as-is (no field-name context at the top level).
+ */
+declare function sanitizeValue(sanitizer: DocumentSanitizer, value: unknown): Promise<unknown>;
+//#endregion
+export { DocumentSanitizer, FieldMaskConfig, MaskHash, MaskObscure, MaskPreserve, MaskRedact, MaskedFieldPolicy, ObscureConfig, PatternRule, Sanitizer, ValidationIssue, commonSecurityPatterns, compilePattern, defaultObscureConfig, mergeConfigs, mostRestrictivePolicy, mustCompilePattern, newSecureDefaultConfig, parseMaskedFieldPolicy, sanitizeDocumentArray, sanitizeValue, validateConfig };

package/index.js

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("@asaidimu/utils-error"),t=require("@asaidimu/utils-logger");const n=`redact`,r=`hash`,i=`preserve`,a=`obscure`;function o(t){switch(t.toLowerCase()){case`redact`:return n;case`hash`:return r;case`obscure`:return a;case`preserve`:return i;default:throw new e.SystemError({code:`ERR_SANITIZATION_CONFIG_INVALID`,message:`unknown policy: ${t} (valid: redact, hash, obscure, preserve)`})}}const s={redact:4,hash:3,obscure:2,preserve:1};function c(e,t){return s[e]>=s[t]?e:t}function l(){return{prefixLength:2,suffixLength:2,replacement:`*`,maxLength:0}}function u(t){let n=[];for(let[e,r]of Object.entries(t.fields??{}))try{o(r)}catch{n.push({code:`ERR_INVALID_POLICY`,message:`invalid policy "${r}" for field "${e}"`,path:`fields.${e}`,severity:`error`})}let r=[];for(let e=0;e<(t.patterns??[]).length;e++){let i=t.patterns[e];if(!i.pattern){n.push({code:`ERR_EMPTY_PATTERN`,message:`pattern string is empty`,path:`patterns`,index:e,severity:`error`}),r.push(i);continue}let a;try{a=new RegExp(i.pattern)}catch(t){n.push({code:`ERR_INVALID_REGEX`,message:`invalid regex: ${String(t)}`,path:`patterns`,index:e,severity:`error`}),r.push(i);continue}try{o(i.policy)}catch{n.push({code:`ERR_INVALID_POLICY`,message:`invalid policy "${i.policy}"`,path:`patterns`,index:e,severity:`error`})}let s={...i};Object.defineProperty(s,"_regex",{value:a,enumerable:!1,writable:!1,configurable:!1}),r.push(s)}if(t.patterns=r,t.defaultPolicy!==void 0)try{o(t.defaultPolicy)}catch{n.push({code:`ERR_INVALID_POLICY`,message:`invalid default policy "${t.defaultPolicy}"`,path:`default_policy`,severity:`error`})}else t.defaultPolicy=i;if(!t.obscureConfig||!t.obscureConfig.replacement)t.obscureConfig=l();else{let e=t.obscureConfig;if(e.prefixLength<0&&n.push({code:`ERR_INVALID_CONFIG`,message:`prefixLength must be >= 0`,path:`obscure.prefixLength`,severity:`error`}),e.suffixLength<0&&n.push({code:`ERR_INVALID_CONFIG`,message:`suffixLength must be >= 0`,path:`obscure.suffixLength`,severity:`error`}),e.maxLength<0&&n.push({code:`ERR_INVALID_CONFIG`,message:`maxLength must be >= 0`,path:`obscure.maxLength`,severity:`error`}),e.maxLength>0){let t=e.prefixLength+e.suffixLength+1;e.maxLength<t&&n.push({code:`ERR_INVALID_CONFIG`,message:`maxLength (${e.maxLength}) is too small for prefix (${e.prefixLength}) + suffix (${e.suffixLength}) + 1`,path:`obscure.maxLength`,severity:`warning`})}}if(t.hashSecret!==void 0&&t.hashSecret!==``){let e=t.hashSecret;e.length%2==0&&/^[0-9a-fA-F]+$/.test(e)?e.length<32&&n.push({code:`ERR_INVALID_CONFIG`,message:`hashSecret too short: must be at least 16 bytes (32 hex chars)`,path:`hash_secret`,severity:`error`}):n.push({code:`ERR_INVALID_CONFIG`,message:`hashSecret must be a valid hex-encoded string`,path:`hash_secret`,severity:`error`})}let a=n.filter(e=>e.severity===`error`);if(a.length>0)throw new e.SystemError({code:`ERR_SANITIZATION_CONFIG_INVALID`,message:`sanitization config validation failed`,issues:a.map(e=>({code:e.code,message:e.message,path:e.path,index:e.index,severity:`error`}))})}function d(e){let t=new Uint8Array(e.length/2);for(let n=0;n<t.length;n++)t[n]=parseInt(e.slice(n*2,n*2+2),16);return t}function f(e){return Array.from(new Uint8Array(e)).map(e=>e.toString(16).padStart(2,`0`)).join(``)}function p(){let e=new Uint8Array(32);return crypto.getRandomValues(e),e}function m(e){return crypto.subtle.importKey(`raw`,e,{name:`HMAC`,hash:`SHA-256`},!1,[`sign`])}var h=class{config;logger;hashSecretBytes;cryptoKeyPromise;constructor(e,n){this.logger=n??new t.Logger([]);let r={...e};try{u(r)}catch(e){this.logger.error(`sanitizer_config_invalid`,{error:String(e),fallback:`preserve-all`}),r={defaultPolicy:i,obscureConfig:l()},u(r)}this.config=r;let a;if(r.hashSecret){let e=d(r.hashSecret);e.length>=16?(a=e,this.logger.debug(`sanitizer_hash_secret_loaded`)):(this.logger.warn(`sanitizer_hash_secret_invalid`,{reason:`too short, generating random secret`}),a=p())}else a=p();this.hashSecretBytes=a,this.cryptoKeyPromise=m(a)}async sanitizeDocument(e){let t=await Promise.all(Object.entries(e).map(async([e,t])=>{let n=this.getPolicyForField(e);return[e,await this.applyPolicy(e,t,n)]}));return Object.fromEntries(t)}async sanitizeValue(e,t){let n=this.getPolicyForField(e);return this.applyPolicy(e,t,n)}getPolicyForField(e){let t=this.config.fields?.[e];if(t!==void 0)return t;for(let t of this.config.patterns??[])if(t._regex?.test(e))return t.policy;return this.config.defaultPolicy??`preserve`}async applyPolicy(e,t,n){if(t==null)return t;switch(n){case`redact`:return`***`;case`hash`:return this.hashValue(t);case`obscure`:return this.obscureValue(t);case`preserve`:return t;default:return this.logger.warn(`sanitizer_unknown_policy`,{field:e,policy:n}),t}}async hashValue(e){let t=E(e),n=await this.cryptoKeyPromise,r=new TextEncoder().encode(t);return`[HASH:${f(await crypto.subtle.sign(`HMAC`,n,r)).slice(0,8)}]`}obscureValue(e){let t=E(e),{prefixLength:n,suffixLength:r,replacement:i,maxLength:a}=this.config.obscureConfig??l(),o=t.length;if(o<=n+r+1)return`[OBSCURED]`;let s=t.slice(0,n),c=t.slice(o-r),u;if(a>0){let e=a-n-r;if(e<1)return`[OBSCURED]`;u=e}else u=o-n-r;return`${s}${i.repeat(u)}${c}`}};const g=new Set([`_version_`,`_created_`,`_updated_`,`_checksum_`,`_signature_`]);function _(e){return g.has(e)}var v=class extends h{scopeID;constructor(e,t,n){super(e,n),this.scopeID=t}async sanitizeDocumentDeep(e){let t=await Promise.all(Object.entries(e).map(async([e,t])=>e===`_metadata_`&&D(t)?[e,await this.sanitizeMetadata(t)]:[e,await this.sanitizeValueDeep(e,t)]));return Object.fromEntries(t)}async sanitizeMetadata(e){let t=await Promise.all(Object.entries(e).map(async([e,t])=>_(e)?[e,t]:[e,await this.sanitizeValueDeep(e,t)]));return Object.fromEntries(t)}async sanitizeValueDeep(e,t){if(t==null)return t;if(D(t)){let e=await Promise.all(Object.entries(t).map(async([e,t])=>[e,await this.sanitizeValueDeep(e,t)]));return Object.fromEntries(e)}if(Array.isArray(t))return Promise.all(t.map(async t=>{if(D(t)){let e=await Promise.all(Object.entries(t).map(async([e,t])=>[e,await this.sanitizeValueDeep(e,t)]));return Object.fromEntries(e)}return this.sanitizeValueDeep(`${e}[]`,t)}));let n=this.getPolicyForField(e);return this.applyPolicy(e,t,n)}async applyPolicy(e,t,n){if(t==null)return t;switch(n){case`redact`:case`hash`:case`obscure`:case`preserve`:return super.applyPolicy(e,t,n);default:return this.logger.warn(`sanitizer_unknown_policy`,{scope:this.scopeID,field:e,policy:n}),t}}};function y(e,t){let n={fields:{},patterns:[]};Object.assign(n.fields,e?.fields??{}),Object.assign(n.fields,t.fields??{});let r=new Map;for(let t of e?.patterns??[])r.set(t.pattern,t);for(let e of t.patterns??[])r.set(e.pattern,e);let i=new Set((t.patterns??[]).map(e=>e.pattern)),a=(t.patterns??[]).map(e=>r.get(e.pattern)),o=(e?.patterns??[]).filter(e=>!i.has(e.pattern)).map(e=>r.get(e.pattern));return n.patterns=[...a,...o],n.defaultPolicy=t.defaultPolicy??e?.defaultPolicy??`preserve`,t.obscureConfig?.replacement?n.obscureConfig=t.obscureConfig:e?.obscureConfig&&(n.obscureConfig=e.obscureConfig),n.hashSecret=t.hashSecret??e?.hashSecret,n}function b(t,n,r){let i;try{i=new RegExp(t)}catch(n){throw new e.SystemError({code:`ERR_SANITIZATION_PATTERN_INVALID`,message:`failed to compile pattern "${t}"`,cause:n})}let a={pattern:t,policy:n,comment:r};return Object.defineProperty(a,"_regex",{value:i,enumerable:!1,writable:!1,configurable:!1}),a}function x(e,t,n){return b(e,t,n)}function S(){return[b(`password`,n,`Passwords`),b(`secret`,n,`Secrets`),b(`token`,n,`Tokens`),b(`api[_-]?key`,n,`API keys`),b(`private[_-]?key`,n,`Private keys`),b(`credential`,n,`Credentials`),b(`auth`,r,`Auth fields`),b(`ssn|social[_-]?security`,n,`SSN`),b(`credit[_-]?card|cvv`,n,`Payment card data`),b(`email`,a,`Email addresses`),b(`phone|mobile`,a,`Phone numbers`)].map(({pattern:e,policy:t,comment:n})=>b(`(?i)${e}`.replace(/^\(\?i\)/,``),t,n))}function C(){return{version:`v1`,fields:{},patterns:S(),defaultPolicy:i,obscureConfig:l()}}async function w(t,n){return Promise.all(n.map(async(n,r)=>{try{return await t.sanitizeDocumentDeep(n)}catch(t){throw new e.SystemError({code:`ERR_SANITIZATION_FAILED`,message:`failed to sanitize document at index ${r}`,cause:t,issues:[{code:`ERR_SANITIZATION_FAILED`,message:String(t),index:r,severity:`error`}]})}}))}async function T(e,t){return t==null?t:D(t)?e.sanitizeDocumentDeep(t):Array.isArray(t)?Promise.all(t.map(t=>T(e,t))):t}function E(e){return typeof e==`string`?e:e instanceof Uint8Array?new TextDecoder().decode(e):String(e)}function D(e){return typeof e==`object`&&!!e&&!Array.isArray(e)&&!(e instanceof Uint8Array)&&!(e instanceof Date)}exports.DocumentSanitizer=v,exports.MaskHash=r,exports.MaskObscure=a,exports.MaskPreserve=i,exports.MaskRedact=n,exports.Sanitizer=h,exports.commonSecurityPatterns=S,exports.compilePattern=b,exports.defaultObscureConfig=l,exports.mergeConfigs=y,exports.mostRestrictivePolicy=c,exports.mustCompilePattern=x,exports.newSecureDefaultConfig=C,exports.parseMaskedFieldPolicy=o,exports.sanitizeDocumentArray=w,exports.sanitizeValue=T,exports.validateConfig=u;

package/index.mjs

@@ -0,0 +1 @@
+import{SystemError as e}from"@asaidimu/utils-error";import{Logger as t}from"@asaidimu/utils-logger";const n=`redact`,r=`hash`,i=`preserve`,a=`obscure`;function o(t){switch(t.toLowerCase()){case`redact`:return n;case`hash`:return r;case`obscure`:return a;case`preserve`:return i;default:throw new e({code:`ERR_SANITIZATION_CONFIG_INVALID`,message:`unknown policy: ${t} (valid: redact, hash, obscure, preserve)`})}}const s={redact:4,hash:3,obscure:2,preserve:1};function c(e,t){return s[e]>=s[t]?e:t}function l(){return{prefixLength:2,suffixLength:2,replacement:`*`,maxLength:0}}function u(t){let n=[];for(let[e,r]of Object.entries(t.fields??{}))try{o(r)}catch{n.push({code:`ERR_INVALID_POLICY`,message:`invalid policy "${r}" for field "${e}"`,path:`fields.${e}`,severity:`error`})}let r=[];for(let e=0;e<(t.patterns??[]).length;e++){let i=t.patterns[e];if(!i.pattern){n.push({code:`ERR_EMPTY_PATTERN`,message:`pattern string is empty`,path:`patterns`,index:e,severity:`error`}),r.push(i);continue}let a;try{a=new RegExp(i.pattern)}catch(t){n.push({code:`ERR_INVALID_REGEX`,message:`invalid regex: ${String(t)}`,path:`patterns`,index:e,severity:`error`}),r.push(i);continue}try{o(i.policy)}catch{n.push({code:`ERR_INVALID_POLICY`,message:`invalid policy "${i.policy}"`,path:`patterns`,index:e,severity:`error`})}let s={...i};Object.defineProperty(s,"_regex",{value:a,enumerable:!1,writable:!1,configurable:!1}),r.push(s)}if(t.patterns=r,t.defaultPolicy!==void 0)try{o(t.defaultPolicy)}catch{n.push({code:`ERR_INVALID_POLICY`,message:`invalid default policy "${t.defaultPolicy}"`,path:`default_policy`,severity:`error`})}else t.defaultPolicy=i;if(!t.obscureConfig||!t.obscureConfig.replacement)t.obscureConfig=l();else{let e=t.obscureConfig;if(e.prefixLength<0&&n.push({code:`ERR_INVALID_CONFIG`,message:`prefixLength must be >= 0`,path:`obscure.prefixLength`,severity:`error`}),e.suffixLength<0&&n.push({code:`ERR_INVALID_CONFIG`,message:`suffixLength must be >= 0`,path:`obscure.suffixLength`,severity:`error`}),e.maxLength<0&&n.push({code:`ERR_INVALID_CONFIG`,message:`maxLength must be >= 0`,path:`obscure.maxLength`,severity:`error`}),e.maxLength>0){let t=e.prefixLength+e.suffixLength+1;e.maxLength<t&&n.push({code:`ERR_INVALID_CONFIG`,message:`maxLength (${e.maxLength}) is too small for prefix (${e.prefixLength}) + suffix (${e.suffixLength}) + 1`,path:`obscure.maxLength`,severity:`warning`})}}if(t.hashSecret!==void 0&&t.hashSecret!==``){let e=t.hashSecret;e.length%2==0&&/^[0-9a-fA-F]+$/.test(e)?e.length<32&&n.push({code:`ERR_INVALID_CONFIG`,message:`hashSecret too short: must be at least 16 bytes (32 hex chars)`,path:`hash_secret`,severity:`error`}):n.push({code:`ERR_INVALID_CONFIG`,message:`hashSecret must be a valid hex-encoded string`,path:`hash_secret`,severity:`error`})}let a=n.filter(e=>e.severity===`error`);if(a.length>0)throw new e({code:`ERR_SANITIZATION_CONFIG_INVALID`,message:`sanitization config validation failed`,issues:a.map(e=>({code:e.code,message:e.message,path:e.path,index:e.index,severity:`error`}))})}function d(e){let t=new Uint8Array(e.length/2);for(let n=0;n<t.length;n++)t[n]=parseInt(e.slice(n*2,n*2+2),16);return t}function f(e){return Array.from(new Uint8Array(e)).map(e=>e.toString(16).padStart(2,`0`)).join(``)}function p(){let e=new Uint8Array(32);return crypto.getRandomValues(e),e}function m(e){return crypto.subtle.importKey(`raw`,e,{name:`HMAC`,hash:`SHA-256`},!1,[`sign`])}var h=class{config;logger;hashSecretBytes;cryptoKeyPromise;constructor(e,n){this.logger=n??new t([]);let r={...e};try{u(r)}catch(e){this.logger.error(`sanitizer_config_invalid`,{error:String(e),fallback:`preserve-all`}),r={defaultPolicy:i,obscureConfig:l()},u(r)}this.config=r;let a;if(r.hashSecret){let e=d(r.hashSecret);e.length>=16?(a=e,this.logger.debug(`sanitizer_hash_secret_loaded`)):(this.logger.warn(`sanitizer_hash_secret_invalid`,{reason:`too short, generating random secret`}),a=p())}else a=p();this.hashSecretBytes=a,this.cryptoKeyPromise=m(a)}async sanitizeDocument(e){let t=await Promise.all(Object.entries(e).map(async([e,t])=>{let n=this.getPolicyForField(e);return[e,await this.applyPolicy(e,t,n)]}));return Object.fromEntries(t)}async sanitizeValue(e,t){let n=this.getPolicyForField(e);return this.applyPolicy(e,t,n)}getPolicyForField(e){let t=this.config.fields?.[e];if(t!==void 0)return t;for(let t of this.config.patterns??[])if(t._regex?.test(e))return t.policy;return this.config.defaultPolicy??`preserve`}async applyPolicy(e,t,n){if(t==null)return t;switch(n){case`redact`:return`***`;case`hash`:return this.hashValue(t);case`obscure`:return this.obscureValue(t);case`preserve`:return t;default:return this.logger.warn(`sanitizer_unknown_policy`,{field:e,policy:n}),t}}async hashValue(e){let t=E(e),n=await this.cryptoKeyPromise,r=new TextEncoder().encode(t);return`[HASH:${f(await crypto.subtle.sign(`HMAC`,n,r)).slice(0,8)}]`}obscureValue(e){let t=E(e),{prefixLength:n,suffixLength:r,replacement:i,maxLength:a}=this.config.obscureConfig??l(),o=t.length;if(o<=n+r+1)return`[OBSCURED]`;let s=t.slice(0,n),c=t.slice(o-r),u;if(a>0){let e=a-n-r;if(e<1)return`[OBSCURED]`;u=e}else u=o-n-r;return`${s}${i.repeat(u)}${c}`}};const g=new Set([`_version_`,`_created_`,`_updated_`,`_checksum_`,`_signature_`]);function _(e){return g.has(e)}var v=class extends h{scopeID;constructor(e,t,n){super(e,n),this.scopeID=t}async sanitizeDocumentDeep(e){let t=await Promise.all(Object.entries(e).map(async([e,t])=>e===`_metadata_`&&D(t)?[e,await this.sanitizeMetadata(t)]:[e,await this.sanitizeValueDeep(e,t)]));return Object.fromEntries(t)}async sanitizeMetadata(e){let t=await Promise.all(Object.entries(e).map(async([e,t])=>_(e)?[e,t]:[e,await this.sanitizeValueDeep(e,t)]));return Object.fromEntries(t)}async sanitizeValueDeep(e,t){if(t==null)return t;if(D(t)){let e=await Promise.all(Object.entries(t).map(async([e,t])=>[e,await this.sanitizeValueDeep(e,t)]));return Object.fromEntries(e)}if(Array.isArray(t))return Promise.all(t.map(async t=>{if(D(t)){let e=await Promise.all(Object.entries(t).map(async([e,t])=>[e,await this.sanitizeValueDeep(e,t)]));return Object.fromEntries(e)}return this.sanitizeValueDeep(`${e}[]`,t)}));let n=this.getPolicyForField(e);return this.applyPolicy(e,t,n)}async applyPolicy(e,t,n){if(t==null)return t;switch(n){case`redact`:case`hash`:case`obscure`:case`preserve`:return super.applyPolicy(e,t,n);default:return this.logger.warn(`sanitizer_unknown_policy`,{scope:this.scopeID,field:e,policy:n}),t}}};function y(e,t){let n={fields:{},patterns:[]};Object.assign(n.fields,e?.fields??{}),Object.assign(n.fields,t.fields??{});let r=new Map;for(let t of e?.patterns??[])r.set(t.pattern,t);for(let e of t.patterns??[])r.set(e.pattern,e);let i=new Set((t.patterns??[]).map(e=>e.pattern)),a=(t.patterns??[]).map(e=>r.get(e.pattern)),o=(e?.patterns??[]).filter(e=>!i.has(e.pattern)).map(e=>r.get(e.pattern));return n.patterns=[...a,...o],n.defaultPolicy=t.defaultPolicy??e?.defaultPolicy??`preserve`,t.obscureConfig?.replacement?n.obscureConfig=t.obscureConfig:e?.obscureConfig&&(n.obscureConfig=e.obscureConfig),n.hashSecret=t.hashSecret??e?.hashSecret,n}function b(t,n,r){let i;try{i=new RegExp(t)}catch(n){throw new e({code:`ERR_SANITIZATION_PATTERN_INVALID`,message:`failed to compile pattern "${t}"`,cause:n})}let a={pattern:t,policy:n,comment:r};return Object.defineProperty(a,"_regex",{value:i,enumerable:!1,writable:!1,configurable:!1}),a}function x(e,t,n){return b(e,t,n)}function S(){return[b(`password`,n,`Passwords`),b(`secret`,n,`Secrets`),b(`token`,n,`Tokens`),b(`api[_-]?key`,n,`API keys`),b(`private[_-]?key`,n,`Private keys`),b(`credential`,n,`Credentials`),b(`auth`,r,`Auth fields`),b(`ssn|social[_-]?security`,n,`SSN`),b(`credit[_-]?card|cvv`,n,`Payment card data`),b(`email`,a,`Email addresses`),b(`phone|mobile`,a,`Phone numbers`)].map(({pattern:e,policy:t,comment:n})=>b(`(?i)${e}`.replace(/^\(\?i\)/,``),t,n))}function C(){return{version:`v1`,fields:{},patterns:S(),defaultPolicy:i,obscureConfig:l()}}async function w(t,n){return Promise.all(n.map(async(n,r)=>{try{return await t.sanitizeDocumentDeep(n)}catch(t){throw new e({code:`ERR_SANITIZATION_FAILED`,message:`failed to sanitize document at index ${r}`,cause:t,issues:[{code:`ERR_SANITIZATION_FAILED`,message:String(t),index:r,severity:`error`}]})}}))}async function T(e,t){return t==null?t:D(t)?e.sanitizeDocumentDeep(t):Array.isArray(t)?Promise.all(t.map(t=>T(e,t))):t}function E(e){return typeof e==`string`?e:e instanceof Uint8Array?new TextDecoder().decode(e):String(e)}function D(e){return typeof e==`object`&&!!e&&!Array.isArray(e)&&!(e instanceof Uint8Array)&&!(e instanceof Date)}export{v as DocumentSanitizer,r as MaskHash,a as MaskObscure,i as MaskPreserve,n as MaskRedact,h as Sanitizer,S as commonSecurityPatterns,b as compilePattern,l as defaultObscureConfig,y as mergeConfigs,c as mostRestrictivePolicy,x as mustCompilePattern,C as newSecureDefaultConfig,o as parseMaskedFieldPolicy,w as sanitizeDocumentArray,T as sanitizeValue,u as validateConfig};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@asaidimu/utils-sanitize",
+  "version": "1.0.0",
+  "description": "A collection of sanitize utilities.",
+  "main": "index.js",
+  "module": "index.mjs",
+  "types": "index.d.ts",
+  "keywords": [
+    "typescript",
+    "utility"
+  ],
+  "author": "Saidimu <47994458+asaidimu@users.noreply.github.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asaidimu/erp-utils.git"
+  },
+  "bugs": {
+    "url": "https://github.com/asaidimu/erp-utils/issues"
+  },
+  "homepage": "https://github.com/asaidimu/erp-utils/tree/main/src/sanitize#readme",
+  "files": [
+    "./*"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./index.d.ts",
+        "default": "./index.mjs"
+      },
+      "require": {
+        "types": "./index.d.ts",
+        "default": "./index.js"
+      }
+    }
+  },
+  "dependencies": {},
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "tag": "latest",
+    "access": "public"
+  },
+  "release": {
+    "plugins": [
+      [
+        "@semantic-release/npm",
+        {
+          "pkgRoot": "./dist"
+        }
+      ],
+      [
+        "@semantic-release/git",
+        {
+          "assets": [
+            "CHANGELOG.md",
+            "package.json"
+          ],
+          "message": "chore(release): Release @asaidimu/utils-sanitize v${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+        }
+      ]
+    ]
+  }
+}