[Column Masking] MEDIUM: Design document and implementation signature mismatch
- Dominant language
- Go
- Stars
- 40.5k
- Forks
- 6.2k
- PR merge metrics
- PR metrics pending
Description
## Severity
MEDIUM
## Description
The design document describes `MASK_PARTIAL`/`MASK_DATE` (and optional parameters for `MASK_FULL`) inconsistently with the actual implementation.
This directly causes users to write policy expressions that are "parseable but not executable", and amplifies the risk of Issue-2 (point-get fail-open).
## Signature Mismatch Details
### MASK_PARTIAL
**Design Document** (`docs/design/2026-02-27-column-level-masking.md:166`):
```
MASK_PARTIAL(expr[, replace[, start[, length]]])
```
**Actual Implementation** (`pkg/expression/builtin_masking.go:333`):
```go
// Actual signature: MASK_PARTIAL(str, pad, start, length)
// arg count registered in: pkg/expression/builtin.go:655
```
### MASK_DATE
**Design Document**:
```
MASK_DATE(expr, format)
```
**Actual Implementation** (`pkg/expression/builtin_masking.go:503`):
```go
// MASK_DATE(col, 'YYYY-MM-DD') - format is a fixed literal
// Actual behavior may differ from document description
```
### MASK_FULL
The design document describes optional parameters, but actual implementation behavior may not match the documentation.
## Impact
1. **Document Misleading**: Policies written by users following the documentation may not execute
2. **Runtime Errors**: When users use the signature from the document, parsing errors may be triggered
3. **Amplifies fail-open Risk**: If expression parsing fails, per Issue-2, original data may be leaked directly
## Example Risk
```sql
-- User creates policy following documentation (signature may be wrong)
CREATE MASKING POLICY p AS MASK_PARTIAL(col, '****', 2, 4) ENABLE;
-- If signature doesn't match, parsing error may be triggered
-- Based on current fail-open behavior, query returns original value!
SELECT col FROM t WHERE pk = 1; -- leaks original value
```
## Related Code Locations
- `docs/design/2026-02-27-column-level-masking.md:166` - design document signatures (incorrect)
- `pkg/expression/builtin_masking.go:333` - MASK_PARTIAL implementation
- `pkg/expression/builtin_masking.go:503` - MASK_DATE implementation
- `pkg/expression/builtin.go:655` - arg count registration
- `.agents/skills/column-masking-auto-validation/references/column-masking-test-plan.md:17` - test plan claims "AT RESULT semantics"
## Proposed Fix
**Option A (Recommended)**: Update documentation to match implementation
1. Update function signatures in `docs/design/2026-02-27-column-level-masking.md`
2. Update test plan document if needed
3. Add actual function signature documentation
4. Ensure documentation and implementation are completely consistent
**Option B**: Reverse-adjust implementation to match documentation (Not recommended - involves large parser/test changes, may affect existing users)
## Parent Issue
Relates to #65744
Contributor guide
Assessment
This issue has not been assessed yet.