suaveplan/openspec/archive/2026-04-19-enterprise-data-masking/proposal.md

OpenSpec Change: enterprise-data-masking

• Change ID: enterprise-data-masking
• Package: @suaveplan/data-masking
• Category: universal
• Target path: universal/data/data-masking
• Status: PROPOSED
• Date: 2026-04-19
• Reference spec: /mnt/s/web/suaveplan/enterprise/data-masking.md

Summary

Greenfield rebuild of @suaveplan/data-masking — structured PII masking with type detection, pattern-based redaction, conditional role/field-permission masking, strategy library (hash, partial, redact, maskEmail, maskPhone, maskIp, maskCreditCard), pluggable MaskingRegistry, and an AuditEntry trail.

Current-state audit (genesis)

Package does not exist yet — fresh build.

Dependencies

• Workspace: @suaveplan/error, @suaveplan/events, @suaveplan/types
• External (via catalog): zod, tslib, @opentelemetry/api
• Dev (via catalog): vitest, @vitest/coverage-istanbul, fast-check, mitata

Preserved public surface

Masker / registry

• DataMasker, MaskingRegistry, RegistryErrorCode
• Strategies: hash, maskCreditCard, maskEmail, maskIp, maskPhone, partial, redact

Patterns

• PatternMasker, PatternMaskerOptions, PatternMatch, PatternRule

Detection

• TypeDetector, DetectionOptions, DetectionResult, SensitiveDataType

Rules

• ConditionalMasker, ConditionalMaskResult, FieldPermission, MaskingContext, MaskingPolicy, MaskingRole

Audit

• MaskingAudit, AuditEntry, AuditFilter, AuditOptions, AuditSink

Error codes

• DataMaskingErrorCode, DATA_MASKING_ERROR_METADATA, registerDataMaskingErrorCodes

Hooks / types

• DataMaskingHandler, MaskingHookData, MaskingHookMap
• MaskingConfig, MaskingOptions, MaskingRule, MaskingStrategy, MaskResult

New genesis additions

• Additional codes: DATA_MASKING.INVALID_POLICY, DATA_MASKING.UNKNOWN_STRATEGY, DATA_MASKING.AUDIT_SINK_FAILED.
• Zod schemas for every config type.
• OTel counter data_masking.masked.total{type}, histogram data_masking.mask.duration_ms.
• Property tests: idempotency (mask twice = mask once), never-leak property on PII patterns.

Impact

• Adds one new package: universal/data/data-masking
• Adds one new spec capability: data-masking