# SPDX-FileCopyrightText: 2026 Dennis Fink # # SPDX-License-Identifier: BSD-3-Clause """Webmention forms and URL validation.""" import ipaddress import httpx from flask import current_app from flask_wtf import FlaskForm from wtforms import ( DateField, Field, HiddenField, IntegerField, PasswordField, SearchField, SelectField, StringField, SubmitField, ValidationError, ) from wtforms.form import BaseForm from wtforms.validators import ( AnyOf, InputRequired, NumberRange, Optional, StopValidation, ) from .hostname import normalize_hostname from .net import is_public_address from .validation import is_control_character RECEIVED_STATUS_CHOICES = { "": "All statuses", "pending": "Pending", "verifying": "Verifying", "verified": "Verified", "declined": "Declined", } class MaxURLBytes: """Check the UTF-8 byte length of a submitted URL using the current config.""" def __init__( self, config_key: str = "MAX_WEBMENTION_URL_BYTES", message: str | None = None ) -> None: self.config_key = config_key self.message = message def __call__(self, form: BaseForm, field: Field) -> None: if field.data is None: return max_bytes = current_app.config[self.config_key] try: length = len(field.data.encode("utf-8")) except UnicodeEncodeError as exc: raise ValidationError(field.gettext("URL must be valid UTF-8.")) from exc if length > max_bytes: raise ValidationError( self.message or field.gettext(f"URL must not exceed {max_bytes} bytes.") ) class StrictHTTPURL: """Require an HTTP(S) URL that httpx can parse without rewriting whitespace. httpx automatically percent-encodes some whitespace. Reject it instead of silently changing the submitted URL (which may be used in exact URL matches). """ def __call__(self, form: BaseForm, field: Field) -> None: value = field.data if not isinstance(value, str): raise StopValidation(field.gettext("Invalid URL.")) if any( character.isspace() or is_control_character(character) for character in value ): raise StopValidation(field.gettext("Invalid URL.")) try: parsed = httpx.URL(value) except (httpx.InvalidURL, ValueError, UnicodeError) as exc: raise StopValidation(field.gettext("Invalid URL.")) from exc if not parsed.host: raise StopValidation(field.gettext("Invalid URL.")) if parsed.scheme not in ("http", "https"): raise StopValidation( field.gettext(f"{field.name} must begin with http or https") ) class AllowedTargetHostname: """Validate that a URL uses an allowed hostname. :param message: Optional validation error message. """ def __init__(self, message: str | None = None) -> None: """Initialize the validator. :param message: Optional validation error message. """ self.message = message def __call__(self, form: BaseForm, field: Field) -> None: """Validate that a URL uses an allowed hostname. :param form: Form containing the field. :param field: Field containing the URL to validate. :raises ValidationError: If the URL hostname is not configured as allowed. """ try: hostname = normalize_hostname(field.data, from_url=True) except ValueError: hostname = None if hostname in current_app.config["ALLOWED_TARGET_HOSTNAMES"]: return raise ValidationError(self.message or field.gettext("Invalid input.")) class RejectNonPublicIPLiteral: """Reject non-public IP literals without performing DNS in the web worker.""" def __call__(self, form: BaseForm, field: Field) -> None: try: hostname = normalize_hostname(field.data, from_url=True) except ValueError as exc: raise ValidationError(field.gettext("Invalid input.")) from exc try: address = ipaddress.ip_address(hostname) except ValueError: return # Named hosts are resolved only during the background fetch. if not is_public_address(address): raise ValidationError(field.gettext("URL must use a public address.")) class LoginForm(FlaskForm): """Form for authenticating a user.""" username = StringField("Username", validators=[InputRequired()]) password = PasswordField("Password", validators=[InputRequired()]) submit = SubmitField("Sign In") class WebmentionSubmissionForm(FlaskForm): """Form for receiving a Webmention. The source must be a public HTTP or HTTPS URL distinct from the target. The target must be an HTTP or HTTPS URL using an allowed hostname. """ source = StringField( "source", validators=[ InputRequired(), MaxURLBytes(), StrictHTTPURL(), RejectNonPublicIPLiteral(), ], ) target = StringField( "target", validators=[ InputRequired(), MaxURLBytes(), StrictHTTPURL(), AllowedTargetHostname(), ], ) def validate_source(self, field: Field) -> None: """Reject a source URL that equals the target URL. :param field: Source URL field being validated. :raises ValidationError: If the source URL equals the target URL. """ if field.data == self.target.data: raise ValidationError(field.gettext("Field must not be equal to target.")) class CanonicalDate: """Require HTML date inputs to use the canonical YYYY-MM-DD format.""" def __call__(self, form: BaseForm, field: DateField) -> None: if ( field.data is not None and field.raw_data and field.raw_data[0] != field.data.isoformat() ): raise ValidationError(field.gettext("Invalid date.")) def default_received_page_size() -> int: """Use 25 rows unless the configured maximum is lower.""" return min(25, current_app.config["RECEIVED_MAX_PAGE_SIZE"]) class ReceivedWebmentionFilterForm(FlaskForm): """GET filters for the received Webmention list.""" status = SelectField("Status", choices=RECEIVED_STATUS_CHOICES, default="") q = SearchField("Source or target") date_from = DateField( "Updated from (UTC)", validators=[Optional(), CanonicalDate()] ) date_to = DateField("Updated to (UTC)", validators=[Optional(), CanonicalDate()]) sort = HiddenField( default="received", validators=[AnyOf(("received", "updated", "status", "source", "target"))], ) order = HiddenField(default="desc", validators=[AnyOf(("asc", "desc"))]) per_page = IntegerField( "Rows per page", default=default_received_page_size, validators=[NumberRange(min=1)], ) def validate_per_page(self, field: IntegerField) -> None: """Enforce the deployment's maximum received-list page size.""" if ( field.data is not None and field.data > current_app.config["RECEIVED_MAX_PAGE_SIZE"] ): raise ValidationError("Rows per page exceeds the configured maximum.") def validate_date_to(self, field: DateField) -> None: """Require the end date to be on or after the start date.""" if ( self.date_from.data is not None and field.data is not None and field.data < self.date_from.data ): raise ValidationError("End date must be on or after start date.") class ConfirmActionForm(FlaskForm): """Form for confirming an administrative action.""" submit = SubmitField("Confirm") class SourceDomainForm(FlaskForm): """Add a domain to the source blocklist or allowlist.""" domain = StringField("Source domain", validators=[InputRequired()]) submit = SubmitField("Add domain") def validate_domain(self, field: Field) -> None: """Require a bare hostname and persist its canonical form.""" try: field.data = normalize_hostname(field.data) except ValueError as exc: raise ValidationError(str(exc)) from exc