"""Small path-safety contract for externally supplied opaque identifiers."""

from __future__ import annotations

import re

_OPAQUE_ID = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,127}\Z")


def validate_opaque_id(value: str, *, label: str) -> str:
    if value in {".", ".."} or _OPAQUE_ID.fullmatch(value) is None:
        raise ValueError(
            f"{label} must be 1-128 ASCII letters, digits, dots, underscores, or hyphens"
        )
    return value


__all__ = ["validate_opaque_id"]
