Plugin and configuration¶

def require_password_length(
    password: str,
    minimum_length: int = DEFAULT_MINIMUM_PASSWORD_LENGTH,
    *,
    maximum_length: int = MAX_PASSWORD_LENGTH,
) -> None:
    """Raise when a password falls outside the configured length bounds.

    The default ``minimum_length`` matches the password-length metadata exposed
    for app-owned user schemas via ``litestar_auth.schemas.UserPasswordField``.

    Raises:
        ValueError: If ``password`` exceeds ``maximum_length`` or is shorter
            than ``minimum_length``.
    """
    if len(password) > maximum_length:
        msg = f"Password must be at most {maximum_length} characters long."
        raise ValueError(msg)

    if len(password) < minimum_length:
        msg = f"Password must be at least {minimum_length} characters long."
        raise ValueError(msg)

def resolve_trusted_proxy_setting(*, trusted_proxy: object) -> bool:
    """Validate and normalize trusted-proxy configuration flags.

    Args:
        trusted_proxy: Candidate trusted-proxy value from configuration.

    Returns:
        Normalized trusted-proxy boolean.

    Raises:
        ConfigurationError: If ``trusted_proxy`` is not a boolean value.
    """
    if isinstance(trusted_proxy, bool):
        return trusted_proxy

    msg = "trusted_proxy must be a boolean."
    raise ConfigurationError(msg)

def validate_oauth_provider_name(name: str, *, label: str = "OAuth provider name") -> str:
    """Validate and return a route/cookie/callback-safe OAuth provider name.

    Returns:
        The validated provider name.

    Raises:
        ConfigurationError: If ``name`` is empty or contains path, cookie, or
            callback-URL unsafe characters.
    """
    if fullmatch(OAUTH_PROVIDER_NAME_PATTERN, name):
        return name

    msg = (
        f"{label} must match {OAUTH_PROVIDER_NAME_PATTERN!r}: use 1-64 ASCII letters, "
        "digits, underscores, or hyphens, and start/end with an alphanumeric character."
    )
    raise ConfigurationError(msg)

def validate_production_secret(
    secret: str,
    *,
    label: str,
    unsafe_testing: bool = False,
    minimum_length: int = MINIMUM_SECRET_LENGTH,
    minimum_entropy_bits: float = MINIMUM_SECRET_ENTROPY_BITS,
) -> None:
    """Validate production secret material, preserving explicit test shortcuts.

    Production token, HMAC, and encryption secrets need both a length floor and
    a basic entropy floor. Repeated-character strings such as ``"a" * 32`` pass
    length-only validation but are not safe signing or encryption material.
    ``unsafe_testing=True`` keeps fixture-only shortcuts possible while making
    the weaker posture explicit at the call site.
    """
    if unsafe_testing:
        return
    validate_secret_strength(
        secret,
        label=label,
        minimum_length=minimum_length,
        minimum_entropy_bits=minimum_entropy_bits,
    )

def validate_secret_length(secret: str, *, label: str, minimum_length: int = MINIMUM_SECRET_LENGTH) -> None:
    """Validate the configured secret length.

    Args:
        secret: Secret value to validate.
        label: Human-readable label used in error messages.
        minimum_length: Minimum length in characters.

    Raises:
        ConfigurationError: When ``secret`` is shorter than ``minimum_length``.
    """
    if len(secret) >= minimum_length:
        return

    msg = f"{label} must be at least {minimum_length} characters."
    raise ConfigurationError(msg)

def validate_secret_roles_are_distinct(role_values: SecretRoleValues) -> None:
    """Raise when one configured secret value is reused across distinct auth roles.

    Distinct JWT audiences already keep verification, reset-password, and TOTP
    tokens scoped to their own flows. Production deployments must still keep
    those secrets separate so one compromise does not widen the blast radius
    across multiple roles.

    Raises:
        ConfigurationError: If one configured secret value is reused across
            multiple roles.
    """
    roles_by_secret: dict[str, list[_SecretRole]] = {}
    for role, secret in role_values.as_role_pairs():
        if not secret:
            continue
        roles_by_secret.setdefault(secret, []).append(role)

    reused_roles = [
        tuple(sorted(roles, key=lambda current_role: current_role.setting_name))
        for roles in roles_by_secret.values()
        if len(roles) > 1
    ]
    if not reused_roles:
        return

    reused_roles.sort(key=lambda roles: tuple(role.setting_name for role in roles))
    role_descriptions = "; ".join(", ".join(role.render_usage() for role in roles) for roles in reused_roles)
    msg = (
        "Distinct secrets/keys are the supported production posture for "
        "verification, reset-password, login telemetry, TOTP, OAuth flow-cookie, and API-key roles. "
        "Distinct JWT audiences "
        "and encrypted-cookie envelopes still prevent token cross-use, but reusing one configured value across "
        "roles increases blast radius if that secret leaks. "
        f"Detected shared secret material across: {role_descriptions}. "
        "Configure one distinct high-entropy value for each secret role, or use "
        "unsafe_testing=True only for test-owned single-process setups."
    )
    raise ConfigurationError(msg)

def validate_secret_strength(
    secret: str,
    *,
    label: str,
    minimum_length: int = MINIMUM_SECRET_LENGTH,
    minimum_entropy_bits: float = MINIMUM_SECRET_ENTROPY_BITS,
) -> None:
    """Validate that a configured secret clears length and Shannon-entropy floors.

    The base library checks length only at constructor seams to keep test
    fixtures interchangeable with production config. ``validate_secret_strength``
    is the recommended operator-side gate for production deployments: wire it
    into the application's startup hook (or a custom `LitestarAuthConfig`
    bootstrap path) to fail closed on degenerate inputs like ``"a" * 32``,
    keyboard-mashed strings, or other low-entropy material that the chars-count
    check alone cannot reject.

    Args:
        secret: Secret value to validate.
        label: Human-readable label used in error messages.
        minimum_length: Minimum length in characters (defaults to
            :data:`MINIMUM_SECRET_LENGTH`).
        minimum_entropy_bits: Minimum approximate Shannon entropy in bits
            (defaults to :data:`MINIMUM_SECRET_ENTROPY_BITS`). Pass ``0`` to
            skip the entropy check while keeping length validation.

    Raises:
        ConfigurationError: When ``secret`` fails either the length floor or
            the entropy floor. The same exception type is used as
            :func:`validate_secret_length` so existing operator handlers stay
            compatible.
    """
    validate_secret_length(secret, label=label, minimum_length=minimum_length)
    if minimum_entropy_bits <= 0:
        return
    bits = _shannon_entropy_bits(secret)
    if bits < minimum_entropy_bits:
        msg = (
            f"{label} has insufficient entropy (~{bits:.0f} bits; required "
            f"{minimum_entropy_bits:.0f}). Generate via "
            'python -c "import secrets; print(secrets.token_hex(32))".'
        )
        raise ConfigurationError(msg)