Skip to content

Open-source personal finance manager. Self-hosted, privacy-first.

19.9 KB
Raw Blame
"""Named validators and normalisers for fiscal document values.

A jurisdiction pack never carries code. It names a validator, and the name
resolves here. That keeps a pack reviewable as data, keeps it safe to load
from outside the repo one day, and keeps validation on the server where it
belongs: the mask in the browser is a convenience, never the check.

Two rules hold for everything in this file:

  - **Nothing here touches the network.** Confirming a VAT number against
    VIES would tell a third party who this workspace bills. A format check
    that runs locally is worth less and costs nothing.
  - **A validator only rejects what is certainly wrong.** These documents
    end up on invoices, so catching a typo is worth it; guessing at a
    format that varies by state or by year is not. Where the rule is not
    globally defined, the validator is `none` and says so.
"""
from collections.abc import Callable

# ---------------------------------------------------------------------------
# normalisation — what gets stored
# ---------------------------------------------------------------------------
def normalise_digits(value: str) -> str:
    """Keep digits only. For documents that are numbers wearing punctuation."""
    return "".join(c for c in value if c.isdigit())


def normalise_upper_alnum(value: str) -> str:
    """Upper-case, drop separators. For VAT-shaped ids with a country prefix."""
    return "".join(c for c in value.upper() if c.isalnum())


def normalise_upper_compact(value: str) -> str:
    """Upper-case, drop separators, keep every other character.

    For documents where a symbol is part of the value: a Mexican RFC may
    contain `&` and `Ñ`, and `upper_alnum` would silently delete the `&`,
    turning a valid document into a different one.
    """
    return "".join(c for c in value.upper() if not c.isspace() and c not in "-./")


def normalise_trim(value: str) -> str:
    """Collapse surrounding whitespace and nothing else."""
    return value.strip()


NORMALISERS: dict[str, Callable[[str], str]] = {
    "digits": normalise_digits,
    "upper_alnum": normalise_upper_alnum,
    "upper_compact": normalise_upper_compact,
    "trim": normalise_trim,
}


# ---------------------------------------------------------------------------
# helpers
# ---------------------------------------------------------------------------
def _mod11_check(digits: str, weights: list[int]) -> int:
    """Weighted mod-11 check digit, the shape most BR/PT documents use."""
    total = sum(int(d) * w for d, w in zip(digits, weights))
    remainder = total % 11
    return 0 if remainder < 2 else 11 - remainder


def _weighted_sum(digits: str, weights: list[int]) -> int:
    return sum(int(d) * w for d, w in zip(digits, weights))


def _digits_len(value: str, *lengths: int) -> str | None:
    """The check shared by every document whose only certain rule is its size."""
    if not value.isdigit():
        return "invalid"
    return None if len(value) in lengths else "length"


def _luhn_ok(digits: str) -> bool:
    total = 0
    for index, char in enumerate(reversed(digits)):
        digit = int(char)
        if index % 2 == 1:
            digit *= 2
            if digit > 9:
                digit -= 9
        total += digit
    return total % 10 == 0


# ---------------------------------------------------------------------------
# validators — return None when valid, else a machine-readable reason
# ---------------------------------------------------------------------------
def validate_none(value: str) -> None:
    """Accept anything non-empty.

    Used by `other` and by every document whose format is not globally
    defined. This is what lets a jurisdiction Securo has never shipped
    store a real document today.
    """
    return None


def validate_br_cpf(value: str) -> str | None:
    if len(value) != 11:
        return "length"
    # Repdigits pass the check-digit maths but are never issued.
    if value == value[0] * 11:
        return "invalid"
    first = _mod11_check(value[:9], list(range(10, 1, -1)))
    second = _mod11_check(value[:10], list(range(11, 1, -1)))
    if value[9] != str(first) or value[10] != str(second):
        return "check_digit"
    return None


def validate_br_cnpj(value: str) -> str | None:
    if len(value) != 14:
        return "length"
    if value == value[0] * 14:
        return "invalid"
    first = _mod11_check(value[:12], [5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2])
    second = _mod11_check(value[:13], [6, 5, 4, 3, 2, 9, 8, 7, 6, 5, 4, 3, 2])
    if value[12] != str(first) or value[13] != str(second):
        return "check_digit"
    return None


def validate_pt_nif(value: str) -> str | None:
    if len(value) != 9:
        return "length"
    check = _mod11_check(value[:8], list(range(9, 1, -1)))
    # PT collapses both mod-11 remainders to 0 rather than to 0 and 1.
    expected = 0 if check > 9 else check
    if value[8] != str(expected):
        return "check_digit"
    return None


def validate_es_nif(value: str) -> str | None:
    """DNI/NIE shape: eight digits plus a check letter."""
    if len(value) != 9:
        return "length"
    body, letter = value[:8], value[8]
    # NIE starts with X/Y/Z, which stands in for a leading 0/1/2.
    if body[0] in "XYZ":
        body = str("XYZ".index(body[0])) + body[1:]
    if not body.isdigit():
        return "invalid"
    if letter != "TRWAGMYFPDXBNJZSQVHLCKE"[int(body) % 23]:
        return "check_digit"
    return None


def validate_it_partita_iva(value: str) -> str | None:
    if len(value) != 11:
        return "length"
    if not value.isdigit():
        return "invalid"
    return None if _luhn_ok(value) else "check_digit"


def validate_it_codice_fiscale(value: str) -> str | None:
    """Sixteen alphanumerics. The full check character needs a birth
    registry, so only the shape is enforced."""
    if len(value) != 16:
        return "length"
    return None if value.isalnum() else "invalid"


def validate_fr_siret(value: str) -> str | None:
    if len(value) != 14:
        return "length"
    if not value.isdigit():
        return "invalid"
    return None if _luhn_ok(value) else "check_digit"


def validate_de_steuernummer(value: str) -> str | None:
    """Ten or eleven digits. The state-specific layouts differ and the
    federal scheme is being rolled out, so length is all that is certain."""
    if not value.isdigit():
        return "invalid"
    return None if len(value) in (10, 11) else "length"


def validate_eu_vat_format(value: str) -> str | None:
    """Two-letter country prefix plus 2 to 13 alphanumerics.

    Format only. Each member state has its own check rule, and confirming
    the number really exists means calling VIES, which would disclose the
    workspace's client list to a third party.

    Also covers UK numbers, which kept the same shape after Brexit.
    """
    if len(value) < 4 or len(value) > 15:
        return "length"
    if not value[:2].isalpha():
        return "prefix"
    if not value[2:].isalnum():
        return "invalid"
    return None


def validate_us_ein(value: str) -> str | None:
    if not value.isdigit():
        return "invalid"
    return None if len(value) == 9 else "length"


# ---------------------------------------------------------------------------
# Latin America
# ---------------------------------------------------------------------------
def validate_ar_cuit(value: str) -> str | None:
    if len(value) != 11:
        return "length"
    check = 11 - (_weighted_sum(value[:10], [5, 4, 3, 2, 7, 6, 5, 4, 3, 2]) % 11)
    # AR folds the two overflow remainders instead of rejecting them.
    expected = {11: 0, 10: 9}.get(check, check)
    return None if value[10] == str(expected) else "check_digit"


def validate_cl_rut(value: str) -> str | None:
    """Seven or eight digits plus a check character, which may be K."""
    if len(value) not in (8, 9):
        return "length"
    body, check = value[:-1], value[-1]
    if not body.isdigit():
        return "invalid"
    # Weights cycle 2..7 from the rightmost digit of the body.
    total = sum(int(d) * (2 + i % 6) for i, d in enumerate(reversed(body)))
    remainder = 11 - (total % 11)
    expected = {11: "0", 10: "K"}.get(remainder, str(remainder))
    return None if check == expected else "check_digit"


def validate_co_nit(value: str) -> str | None:
    """Nine digits, optionally followed by the verification digit.

    The DV is checked only when it is present: writing a NIT without it is
    common and is not an error.
    """
    if len(value) not in (9, 10):
        return "length"
    if not value.isdigit():
        return "invalid"
    if len(value) == 9:
        return None
    weights = [41, 37, 29, 23, 19, 17, 13, 7, 3]
    remainder = _weighted_sum(value[:9], weights) % 11
    expected = remainder if remainder < 2 else 11 - remainder
    return None if value[9] == str(expected) else "check_digit"


def validate_pe_ruc(value: str) -> str | None:
    if len(value) != 11:
        return "length"
    total = _weighted_sum(value[:10], [5, 4, 3, 2, 7, 6, 5, 4, 3, 2])
    expected = (11 - (total % 11)) % 10
    return None if value[10] == str(expected) else "check_digit"


def validate_uy_rut(value: str) -> str | None:
    """Twelve digits. The check rule is not published, so size is the check."""
    return _digits_len(value, 12)


def validate_cr_cedula(value: str) -> str | None:
    """Nine digits for a person, ten for a company. No published check digit."""
    return _digits_len(value, 9, 10)


def validate_do_rnc(value: str) -> str | None:
    """Nine digits for a company, eleven for a person's cédula."""
    return _digits_len(value, 9, 11)


# ---------------------------------------------------------------------------
# Europe outside the VAT-only packs
# ---------------------------------------------------------------------------
def validate_pl_nip(value: str) -> str | None:
    if len(value) != 10:
        return "length"
    if not value.isdigit():
        return "invalid"
    remainder = _weighted_sum(value[:9], [6, 5, 7, 2, 3, 4, 5, 6, 7]) % 11
    # A remainder of 10 cannot be expressed in one digit, so no such NIP exists.
    if remainder == 10:
        return "check_digit"
    return None if value[9] == str(remainder) else "check_digit"


def validate_se_orgnr(value: str) -> str | None:
    if len(value) != 10:
        return "length"
    if not value.isdigit():
        return "invalid"
    return None if _luhn_ok(value) else "check_digit"


def validate_dk_cvr(value: str) -> str | None:
    if len(value) != 8:
        return "length"
    if not value.isdigit():
        return "invalid"
    total = _weighted_sum(value, [2, 7, 6, 5, 4, 3, 2, 1])
    return None if total % 11 == 0 else "check_digit"


def validate_no_orgnr(value: str) -> str | None:
    if len(value) != 9:
        return "length"
    if not value.isdigit():
        return "invalid"
    remainder = _weighted_sum(value[:8], [3, 2, 7, 6, 5, 4, 3, 2]) % 11
    if remainder == 1:
        return "check_digit"
    expected = 0 if remainder == 0 else 11 - remainder
    return None if value[8] == str(expected) else "check_digit"


def validate_cz_ico(value: str) -> str | None:
    if len(value) != 8:
        return "length"
    if not value.isdigit():
        return "invalid"
    remainder = _weighted_sum(value[:7], [8, 7, 6, 5, 4, 3, 2]) % 11
    expected = {0: 1, 1: 0}.get(remainder, 11 - remainder)
    return None if value[7] == str(expected) else "check_digit"


def validate_hu_adoszam(value: str) -> str | None:
    """Eight digits for the core number, eleven with the VAT and county
    suffixes. The published check rule covers only some issuing years."""
    return _digits_len(value, 8, 11)


def validate_ro_cui(value: str) -> str | None:
    if not value.isdigit():
        return "invalid"
    if not 2 <= len(value) <= 10:
        return "length"
    body, check = value[:-1], value[-1]
    key = "753217532"[-len(body):]
    expected = (_weighted_sum(body, [int(k) for k in key]) * 10) % 11 % 10
    return None if check == str(expected) else "check_digit"


def validate_ch_uid(value: str) -> str | None:
    """CHE plus nine digits. The prefix is optional on input."""
    body = value[3:] if value.startswith("CHE") else value
    if len(body) != 9:
        return "length"
    if not body.isdigit():
        return "invalid"
    check = 11 - (_weighted_sum(body[:8], [5, 4, 3, 2, 7, 6, 5, 4]) % 11)
    if check == 10:
        return "check_digit"
    expected = 0 if check == 11 else check
    return None if body[8] == str(expected) else "check_digit"


def validate_ru_inn(value: str) -> str | None:
    """Ten digits for an organisation, twelve for a person."""
    if not value.isdigit():
        return "invalid"
    if len(value) == 10:
        expected = _weighted_sum(value[:9], [2, 4, 10, 3, 5, 9, 4, 6, 8]) % 11 % 10
        return None if value[9] == str(expected) else "check_digit"
    if len(value) == 12:
        first = _weighted_sum(value[:10], [7, 2, 4, 10, 3, 5, 9, 4, 6, 8]) % 11 % 10
        second = _weighted_sum(value[:11], [3, 7, 2, 4, 10, 3, 5, 9, 4, 6, 8]) % 11 % 10
        if value[10] != str(first) or value[11] != str(second):
            return "check_digit"
        return None
    return "length"

def validate_kz_biniin(value: str) -> str | None:
    """Validate a Kazakhstani BIN or IIN.

    BIN (legal entities) and IIN (individuals) share the same 12-digit length
    and the same published checksum scheme, so one validator serves both. The
    scheme is two-pass: each pass uses a different weight vector, and the
    weighted sum modulo 11 is the check digit. A result of 10 from either
    pass means the number was never issued and the code is rejected.
    """
    if not value.isdigit():
        return "invalid"
    if len(value) != 12:
        return "length"
    weights = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]
    check = _weighted_sum(value[:11], weights) % 11
    if check == 10:
        weights2 = [3, 4, 5, 6, 7, 8, 9, 10, 11, 1, 2]
        check = _weighted_sum(value[:11], weights2) % 11
        if check == 10:
            return "check_digit"
    return None if value[11] == str(check) else "check_digit"


def validate_ua_edrpou(value: str) -> str | None:
    """Eight digits. The check rule differs by registration range, so size
    is all that is certain."""
    return _digits_len(value, 8)


# ---------------------------------------------------------------------------
# Rest of the world
# ---------------------------------------------------------------------------
def validate_ca_bn(value: str) -> str | None:
    """Nine digits. The CRA does not publish its check rule, so rejecting on
    one would risk refusing a real Business Number."""
    return _digits_len(value, 9)


def validate_au_abn(value: str) -> str | None:
    if len(value) != 11:
        return "length"
    if not value.isdigit():
        return "invalid"
    weights = [10, 1, 3, 5, 7, 9, 11, 13, 15, 17, 19]
    # The published algorithm subtracts one from the leading digit first.
    total = (int(value[0]) - 1) * weights[0] + _weighted_sum(value[1:], weights[1:])
    return None if total % 89 == 0 else "check_digit"


def validate_nz_nzbn(value: str) -> str | None:
    """Thirteen digits, GS1-issued. The check rule is not public."""
    return _digits_len(value, 13)


def validate_jp_corporate(value: str) -> str | None:
    """Thirteen digits. The leading check digit's rule varies by issuing
    batch, so only the size is enforced."""
    return _digits_len(value, 13)


def validate_ph_tin(value: str) -> str | None:
    """Nine digits, or twelve to fifteen with the branch code."""
    if not value.isdigit():
        return "invalid"
    return None if 9 <= len(value) <= 15 else "length"


def validate_id_npwp(value: str) -> str | None:
    """Fifteen digits, or sixteen since the NIK-based migration."""
    return _digits_len(value, 15, 16)


def validate_vn_mst(value: str) -> str | None:
    """Ten digits, or thirteen with the three-digit branch suffix.

    The tenth digit is a check digit, but reissued and legacy codes are in
    circulation that do not satisfy the published weighting, so refusing on
    it would reject real tax codes.
    """
    return _digits_len(value, 10, 13)


def validate_mx_rfc(value: str) -> str | None:
    """Twelve characters for a company, thirteen for a person.

    The trailing homoclave is assigned by the SAT and cannot be recomputed,
    so the shape is the only available check.
    """
    if len(value) not in (12, 13):
        return "length"
    letters = 3 if len(value) == 12 else 4
    if not all(c.isalpha() or c in "&Ñ" for c in value[:letters]):
        return "invalid"
    if not value[letters : letters + 6].isdigit():
        return "invalid"
    return None if value[letters + 6 :].isalnum() else "invalid"


def validate_in_gstin(value: str) -> str | None:
    """Two state digits, a PAN, an entity digit and two trailing characters."""
    if len(value) != 15:
        return "length"
    if not value[:2].isdigit():
        return "invalid"
    return "invalid" if validate_in_pan(value[2:12]) else None


def validate_in_pan(value: str) -> str | None:
    if len(value) != 10:
        return "length"
    if not (value[:5].isalpha() and value[5:9].isdigit() and value[9].isalpha()):
        return "invalid"
    return None


def validate_sg_uen(value: str) -> str | None:
    """A UEN in one of the three shapes ACRA issues, each ending in a check
    letter:

      - business:      eight digits plus the letter (53012345A)
      - local company: year, five digits, the letter (201012345A)
      - other entity:  T/S/R, two year digits, two letters, four digits, letter

    The check letter's algorithm is not published, so only the shape is
    enforced: refusing on a reverse-engineered rule would reject real numbers.
    """
    if len(value) not in (9, 10):
        return "length"
    if not value[-1].isalpha():
        return "invalid"
    body = value[:-1]
    if len(value) == 9:
        return None if body.isdigit() else "invalid"
    if body.isdigit():
        return None
    if value[0] in "TSR" and body[1:3].isdigit() and body[3:5].isalpha() and body[5:].isdigit():
        return None
    return "invalid"

def validate_az_voen(value: str) -> str | None:
    """Ten digits. Check for a valid 10-digit format without checksum validation."""
    return _digits_len(value, 10)


def validate_cn_uscc(value: str) -> str | None:
    """Eighteen characters from a restricted alphabet: I, O, S, V and Z are
    excluded to keep the code unambiguous when read aloud."""
    if len(value) != 18:
        return "length"
    allowed = set("0123456789ABCDEFGHJKLMNPQRTUWXY")
    return None if set(value) <= allowed else "invalid"


VALIDATORS: dict[str, Callable[[str], str | None]] = {
    "none": validate_none,
    "br_cpf": validate_br_cpf,
    "br_cnpj": validate_br_cnpj,
    "pt_nif": validate_pt_nif,
    "es_nif": validate_es_nif,
    "it_partita_iva": validate_it_partita_iva,
    "it_codice_fiscale": validate_it_codice_fiscale,
    "fr_siret": validate_fr_siret,
    "de_steuernummer": validate_de_steuernummer,
    "eu_vat_format": validate_eu_vat_format,
    "us_ein": validate_us_ein,
    "ar_cuit": validate_ar_cuit,
    "cl_rut": validate_cl_rut,
    "co_nit": validate_co_nit,
    "pe_ruc": validate_pe_ruc,
    "uy_rut": validate_uy_rut,
    "cr_cedula": validate_cr_cedula,
    "do_rnc": validate_do_rnc,
    "mx_rfc": validate_mx_rfc,
    "pl_nip": validate_pl_nip,
    "se_orgnr": validate_se_orgnr,
    "dk_cvr": validate_dk_cvr,
    "no_orgnr": validate_no_orgnr,
    "cz_ico": validate_cz_ico,
    "hu_adoszam": validate_hu_adoszam,
    "ro_cui": validate_ro_cui,
    "ch_uid": validate_ch_uid,
    "ru_inn": validate_ru_inn,
    "kz_biniin": validate_kz_biniin,
    "ua_edrpou": validate_ua_edrpou,
    "ca_bn": validate_ca_bn,
    "au_abn": validate_au_abn,
    "nz_nzbn": validate_nz_nzbn,
    "jp_corporate": validate_jp_corporate,
    "ph_tin": validate_ph_tin,
    "id_npwp": validate_id_npwp,
    "vn_mst": validate_vn_mst,
    "in_gstin": validate_in_gstin,
    "in_pan": validate_in_pan,
    "cn_uscc": validate_cn_uscc,
    "sg_uen": validate_sg_uen,
    "az_voen": validate_az_voen,
}