kotindia-core/io.github.kotindia/PAN/mask

mask

fun mask(value: String, visibleStart: Int = 0, visibleEnd: Int = 4, maskChar: Char = 'X'): String(source)

Masks a PAN for PII-safe display.

PAN is financial PII — always mask before displaying in UI or logging.

Masking operates on the raw input string (not normalised). This is intentional — the masker is a display utility that works character-by-character on whatever string it receives. Callers who want to mask a normalised PAN should call format first: PAN.mask(PAN.format(value)).

Default (visibleStart=0, visibleEnd=4, maskChar='X'): Shows last 4 characters, masks the rest. "ABCPE1234F" → "XXXXXX234F" (last 4: "234F")

Middle-digit-exposure pattern (visibleStart=5, visibleEnd=1): Shows first 5 characters and last 1, masks the 4-digit section (positions 5–8). "ABCPE1234F" → "ABCPEXXXXF" (masks "1234")

Note: The pattern "XXXXX1234X" (all letters masked, digits exposed) from the KotIndia design notes is not achievable with the standard (visibleStart, visibleEnd) signature. Use (5, 1) for the closest practical alternative. This is a known limitation of the standard masking signature documented here for clarity.

Edge cases (all safe — never throws):

Empty input → returns "".
visibleStart + visibleEnd >= value.length → entire string returned unmasked (overlap rule).
Non-normalised input (lowercase, spaces) → masking applied character-by-character on the raw string. No normalisation is performed.

Return

Masked string. Never throws — display-safe by contract.

Parameters

value

Raw PAN string to mask. No normalisation is applied.

visibleStart

Number of leading characters to show unmasked. Default: 0.

visibleEnd

Number of trailing characters to show unmasked. Default: 4.

maskChar

Character to replace masked positions. Default: 'X'.

Samples

check(PAN.mask("ABCPE1234F") == "XXXXXX234F")