# 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`