text.mask

def mask(value: str, visible: int, mask_char: str, keep_separators: bool) -> str

from fune.text.mask import mask  # text.mask@^1

from typing import Any, List


def _whole(value: Any) -> bool:
    # bool is an int in Python; True is not a count of one here.
    return isinstance(value, int) and not isinstance(value, bool)


def _is_separator(ch: str) -> bool:
    # Only these two are separators: they are how card and sort-code numbers
    # are printed.
    return ch == " " or ch == "-"


def mask(value: str, visible: int, mask_char: str, keep_separators: bool) -> str:
    """Mask all but the last ``visible`` characters of ``value``.

    Characters are Unicode code points (a Python str is already indexed by
    code point), so an emoji counts once and the length never changes.
    """
    if not isinstance(value, str):
        raise TypeError("mask needs a string, received %r" % (value,))
    if not _whole(visible):
        raise TypeError("visible must be a whole number, received %r" % (visible,))
    if visible < 0:
        raise ValueError("visible must be 0 or greater, received %d" % (visible,))
    if not isinstance(mask_char, str) or len(mask_char) != 1:
        raise ValueError('maskChar must be exactly one character, received "%s"' % (mask_char,))

    out: List[str] = [""] * len(value)
    shown = 0
    # Walk from the end so "the last n" is counted without a second pass.
    for i in range(len(value) - 1, -1, -1):
        ch = value[i]
        if keep_separators and _is_separator(ch):
            out[i] = ch
        elif shown < visible:
            out[i] = ch
            shown += 1
        else:
            out[i] = mask_char
    return "".join(out)

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the Python package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add text.mask

The manifest, vectors and README with only the Python implementation. Install it without the registry with fune add ./text.mask-1.0.0-python.fune, or fetch it from a terminal with fune pull text.mask@1.0.0:python.

The whole function, every language, is one file too: text.mask-1.0.0.fune, 10,511 bytes, sha256 e1bbb7d0741d771c6ccf2ae30859e642453a9ee706208c1183714ba54a1668fa. It installs into a project of any language.

# fune: before text.mask

# fune: after text.mask

# fune: step text.mask after <n|label>

More from the author

With `keepSeparators` on, ASCII spaces and hyphens stay where they are and are not counted, so a card printed in groups keeps its shape and still shows its last four digits: "4242 4242 4242 4242" becomes "**** **** **** 4242", and the sort code "12-34-56" with 2 visible becomes "**-**-56". Only those two characters are separators; dots, slashes and brackets are masked like anything else, because they are just as often part of the secret.

With it off, separators are ordinary characters: they are masked and they count towards `visible`, so the output never reveals how a value was grouped.

## Counting

Characters are Unicode code points in all three languages, so an accented letter or an emoji counts once, and the result always has the same number of code points as the input. A letter written as a base letter plus a combining accent is two code points and is masked as two.

## Edge cases

- `visible` of 0 masks everything; `visible` at or above the length returns the value unchanged. Nothing is padded: a short value stays short. - A negative `visible`, or a `maskChar` that is not exactly one code point, is an error.

## What masking is not

Masking is for display. The digits you show must be ones you are allowed to show - PCI DSS permits at most the first six and last four of a card number - and the full value must not be sent to the page at all if it is not needed there. This function does not know what the value is.

Files