Initial Commit

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

@@ -0,0 +1,67 @@
+# 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`