first commit

docs/foundation/data/data-masking/src/strategies/full.md

@@ -0,0 +1,67 @@
+# full strategy
+
+## Purpose
+
+The `full` masking strategy completely replaces an input string with a
+configurable replacement sentinel.  It is the most aggressive masking mode
+available in `@suaveplan/data-masking`: no characters from the original value
+are preserved, so the output reveals nothing about length, structure, or
+content.  This strategy is appropriate for highly sensitive fields such as
+passwords, SSNs, or security codes where even partial exposure is unacceptable.
+
+## Features
+
+- Zero information leakage — original value is discarded entirely.
+- Customisable replacement via `MaskRule.replacement`; defaults to `"***"`.
+- Constant-time execution (no iteration over the input string).
+
+## Usage: Basic Example
+
+```ts
+import { maskFull } from '@suaveplan/data-masking/strategies/full';
+
+const masked = maskFull('super-secret-password', { fields: ['password'], strategy: 'full' });
+// masked → '***'
+```
+
+## Usage: Advanced Example
+
+```ts
+import { maskFull } from '@suaveplan/data-masking/strategies/full';
+
+// Custom replacement sentinel
+const masked = maskFull('123-45-6789', {
+  fields: ['ssn'],
+  strategy: 'full',
+  replacement: '[REDACTED]',
+});
+// masked → '[REDACTED]'
+```
+
+## API Reference
+
+### `maskFull(value, rule)`
+
+```ts
+function maskFull(value: string, rule: MaskRule): string;
+```
+
+| Parameter | Type       | Description                                             |
+|-----------|------------|---------------------------------------------------------|
+| `value`   | `string`   | The original value to mask (immediately discarded).     |
+| `rule`    | `MaskRule` | Driving rule; `rule.replacement` used when provided.    |
+
+**Returns** `rule.replacement` if set, otherwise `"***"`.
+
+**Does not throw.**
+
+## Implementation Notes
+
+- The `value` parameter is accepted but immediately voided to satisfy the
+  uniform `mask(value, rule): string` strategy interface.
+- `rule.replacement` may be any string, including the empty string `""`.
+  Callers that want a custom sentinel (e.g. `"[REDACTED]"`, `"N/A"`) set this
+  field on their `MaskRule`.
+- Unlike `partial`, `email`, or `preserve-format` strategies, the `full`
+  strategy cannot be reversed or detected — it is appropriate for
+  security-critical fields that must not leak data to downstream systems.