Make testing easier

docs/configuration.md

@@ -501,20 +501,20 @@ See the [Django project documentation on the settings](https://docs.djangoprojec
 
 #### [`PAPERLESS_ALLOWED_HOSTS=<comma-separated-list>`](#PAPERLESS_ALLOWED_HOSTS) {#PAPERLESS_ALLOWED_HOSTS}
 
-: If you're planning on putting Paperless on the open internet, then
-you really should set this value to the domain name you're using.
-Failing to do so leaves you open to HTTP host header attacks.
+: If you expose Paperless to the internet, set `PAPERLESS_URL` to its public URL
+or list its public hostname in `PAPERLESS_ALLOWED_HOSTS` to help protect against
+HTTP Host header attacks.
 You can read more about this in [the Django project's documentation](https://docs.djangoproject.com/en/4.1/topics/security/#host-header-validation)
 
-    Just remember that this is a comma-separated list, so
-    "example.com" is fine, as is "example.com,www.example.com", but
-    NOT " example.com" or "example.com,"
+    Separate multiple hostnames with commas, as in `example.com,www.example.com`.
 
-    Can also be set using PAPERLESS_URL (see above).
-
-    "localhost" is always allowed for docker healthcheck
-
-    Defaults to "\*", which is all hosts.
+    - With neither setting configured, Paperless accepts any host.
+    - With only `PAPERLESS_URL` set, Paperless accepts the hostname from that URL
+      and `localhost` (used by the Docker health check).
+    - `PAPERLESS_ALLOWED_HOSTS` adds hosts to `localhost` and the hostname from
+      `PAPERLESS_URL`, if set. A blank list adds no hosts.
+    - With `PAPERLESS_ALLOWED_HOSTS=*`, Paperless accepts any host, even when
+      `PAPERLESS_URL` is set.
 
 #### [`PAPERLESS_CORS_ALLOWED_HOSTS=<comma-separated-list>`](#PAPERLESS_CORS_ALLOWED_HOSTS) {#PAPERLESS_CORS_ALLOWED_HOSTS}
 
@@ -873,14 +873,6 @@ If both the [PAPERLESS_ACCOUNT_DEFAULT_GROUPS](#PAPERLESS_ACCOUNT_DEFAULT_GROUPS
 
     Defaults to 1209600 (2 weeks)
 
-#### [`PAPERLESS_SESSION_CLEANUP_TASK_CRON=<cron expression>`](#PAPERLESS_SESSION_CLEANUP_TASK_CRON) {#PAPERLESS_SESSION_CLEANUP_TASK_CRON}
-
-: Configures the schedule to remove expired sessions from the session store.
-Django does not prune these automatically, so without this they would
-accumulate indefinitely.
-
-    Defaults to `0 3 * * *`, once per day at 03:00.
-
 #### [`PAPERLESS_TOKEN_THROTTLE_RATE=<rate>`](#PAPERLESS_TOKEN_THROTTLE_RATE) {#PAPERLESS_TOKEN_THROTTLE_RATE}
 
 : Rate limit for the API token authentication endpoint (`/api/token/`), used to mitigate brute-force login attempts.
@@ -1157,9 +1149,6 @@ they use underscores instead of dashes.
         be changed by trusted users. This applies to the `AppConfig` permission as well,
         which allows setting these arguments from the UI.
 
-        Arguments paperless manages itself (`input_file_or_options`, `output_file`
-        and `sidecar`) are rejected by the API and ignored if set here.
-
     Specify arguments as a JSON dictionary. Keep note of lower case
     booleans and double quoted parameter names and strings. Examples:
 

src/documents/tasks.py

@@ -12,7 +12,6 @@ from celery import Task
 from celery import shared_task
 from django.conf import settings
 from django.contrib.contenttypes.models import ContentType
-from django.contrib.sessions.models import Session
 from django.db import models
 from django.db import transaction
 from django.db.models.signals import post_save
@@ -926,17 +925,3 @@ def cleanup_expired_share_link_bundles() -> None:
             )
     if count:
         logger.info("Deleted %s expired share link bundle(s)", count)
-
-
-@shared_task
-def clear_expired_sessions() -> None:
-    """
-    Remove expired database sessions in batches to limit the size of each delete.
-    """
-    expired = Session.objects.filter(expire_date__lt=timezone.now())
-    while session_keys := list(
-        expired.order_by("expire_date").values_list("pk", flat=True)[:500],
-    ):
-        expired.filter(pk__in=session_keys).delete()
-
-    logger.info("Cleared expired sessions")

src/documents/tests/test_api_app_config.py

@@ -287,28 +287,6 @@ class TestApiAppConfig(DirectoriesMixin, APITestCase):
         self.assertEqual(config.user_args, user_args)
         self.assertEqual(config.barcode_tag_mapping, barcode_tag_mapping)
 
-    def test_api_update_config_rejects_reserved_user_args(self) -> None:
-        """
-        GIVEN:
-            - API request to update app config with user_args which set an
-              argument the parser manages itself
-        WHEN:
-            - API is called
-        THEN:
-            - Request is rejected with a 400 naming the argument
-            - Config is not updated
-        """
-        response = self.client.patch(
-            f"{self.ENDPOINT}1/",
-            json.dumps({"user_args": json.dumps({"sidecar": "/tmp/x.py"})}),
-            content_type="application/json",
-        )
-        self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)
-        self.assertIn("sidecar", str(response.data["user_args"]))
-        config = ApplicationConfiguration.objects.first()
-        assert config is not None
-        self.assertIsNone(config.user_args)
-
     def test_api_update_config_rejects_invalid_json_objects(self) -> None:
         """
         GIVEN:

src/documents/tests/test_tasks.py

@@ -5,11 +5,8 @@ from unittest import mock
 
 import pytest
 from django.conf import settings
-from django.contrib.sessions.models import Session
-from django.db import connection
 from django.test import TestCase
 from django.test import override_settings
-from django.test.utils import CaptureQueriesContext
 from django.utils import timezone
 
 from documents import tasks
@@ -615,36 +612,3 @@ class TestApplyAISuggestionsTask(DirectoriesMixin, TestCase):
 
         apply_suggestions.assert_not_called()
         self.assertIn("no longer exists", "".join(cm.output))
-
-
-@pytest.mark.django_db
-class TestClearExpiredSessions:
-    def test_clears_only_expired_sessions_in_batches(self) -> None:
-        """
-        GIVEN:
-            - More than one batch of expired sessions and one still-valid session
-        WHEN:
-            - The clear_expired_sessions task runs
-        THEN:
-            - Only expired sessions are removed, using multiple deletes
-        """
-        now = timezone.now()
-        Session.objects.bulk_create(
-            Session(
-                session_key=f"expired-{i}",
-                session_data="",
-                expire_date=now - timedelta(days=1),
-            )
-            for i in range(501)
-        )
-        Session.objects.create(
-            session_key="valid",
-            session_data="",
-            expire_date=now + timedelta(days=1),
-        )
-
-        with CaptureQueriesContext(connection) as queries:
-            tasks.clear_expired_sessions()
-
-        assert set(Session.objects.values_list("session_key", flat=True)) == {"valid"}
-        assert sum(query["sql"].startswith("DELETE FROM") for query in queries) == 2

src/paperless/config.py

@@ -12,17 +12,6 @@ from paperless.models import ModeChoices
 from paperless.models import OutputTypeChoices
 from paperless.models import RemoteOCRMode
 
-# OCRmyPDF arguments the parser sets itself, pointing into its own temporary
-# directory. The parser reads these files back after OCR, so user supplied
-# values can only break consumption (or write to arbitrary paths), never help.
-OCR_RESERVED_USER_ARGS: frozenset[str] = frozenset(
-    {
-        "input_file_or_options",
-        "output_file",
-        "sidecar",
-    },
-)
-
 
 @dataclasses.dataclass
 class BaseConfig:

src/paperless/parsers/tesseract.py

@@ -21,7 +21,6 @@ from documents.parsers import make_thumbnail_from_pdf
 from documents.utils import copy_file_with_basic_stats
 from documents.utils import maybe_override_pixel_limit
 from documents.utils import remove_alpha_channel
-from paperless.config import OCR_RESERVED_USER_ARGS
 from paperless.config import OcrConfig
 from paperless.models import CleanChoices
 from paperless.models import ModeChoices
@@ -352,22 +351,7 @@ class RasterisedDocumentParser:
 
         if self.settings.user_args is not None:
             try:
-                reserved = sorted(
-                    OCR_RESERVED_USER_ARGS & self.settings.user_args.keys(),
-                )
-                if reserved:
-                    self.log.warning(
-                        f"Ignoring OCR user arguments managed by paperless: "
-                        f"{', '.join(reserved)}",
-                    )
-                ocrmypdf_args = {
-                    **ocrmypdf_args,
-                    **{
-                        k: v
-                        for k, v in self.settings.user_args.items()
-                        if k not in OCR_RESERVED_USER_ARGS
-                    },
-                }
+                ocrmypdf_args = {**ocrmypdf_args, **self.settings.user_args}
             except Exception as e:
                 self.log.warning(
                     f"There is an issue with PAPERLESS_OCR_USER_ARGS, so "

src/paperless/serialisers.py

@@ -19,7 +19,6 @@ from PIL import Image
 from rest_framework import serializers
 from rest_framework.authtoken.serializers import AuthTokenSerializer
 
-from paperless.config import OCR_RESERVED_USER_ARGS
 from paperless.models import ApplicationConfiguration
 from paperless.network import validate_outbound_http_url
 from paperless.validators import reject_dangerous_svg
@@ -252,13 +251,6 @@ class ApplicationConfigurationSerializer(
 
     def validate_user_args(self, value):
         self._require_json_object("user_args", value)
-        if value is not None:
-            reserved = sorted(OCR_RESERVED_USER_ARGS & value.keys())
-            if reserved:
-                raise serializers.ValidationError(
-                    f"user_args may not set arguments managed by paperless: "
-                    f"{', '.join(reserved)}.",
-                )
         return value
 
     def validate_barcode_tag_mapping(self, value):

src/paperless/settings/__init__.py

@@ -450,23 +450,34 @@ CORS_EXPOSE_HEADERS = [
     "Content-Disposition",
 ]
 
-ALLOWED_HOSTS = get_list_from_env("PAPERLESS_ALLOWED_HOSTS", default=["*"])
-if ALLOWED_HOSTS != ["*"]:
-    # always allow localhost. Necessary e.g. for healthcheck in docker.
-    ALLOWED_HOSTS.append("localhost")
+
+def _get_allowed_hosts() -> list[str]:
+    if "PAPERLESS_ALLOWED_HOSTS" in os.environ or os.getenv("PAPERLESS_URL"):
+        allowed_hosts = get_list_from_env("PAPERLESS_ALLOWED_HOSTS")
+    else:
+        allowed_hosts = ["*"]
+    if allowed_hosts != ["*"]:
+        # Always allow localhost for the Docker health check.
+        allowed_hosts.append("localhost")
+    return allowed_hosts
+
+
+ALLOWED_HOSTS = _get_allowed_hosts()
 
 
 def _parse_paperless_url():
     global CSRF_TRUSTED_ORIGINS, CORS_ALLOWED_ORIGINS, ALLOWED_HOSTS
     url = os.getenv("PAPERLESS_URL")
     if url:
-        hostname = urlparse(url).hostname
-        if not hostname:
+        hostname = (urlparse(url).hostname or "").removesuffix(".")
+        if not hostname or hostname == "*" or hostname.startswith("."):
             raise ImproperlyConfigured(
-                f"PAPERLESS_URL {url!r} has no hostname, expected a URL like https://example.com",
+                f"PAPERLESS_URL {url!r} has no valid hostname, expected a URL like https://example.com",
             )
         CSRF_TRUSTED_ORIGINS.append(url)
         CORS_ALLOWED_ORIGINS.append(url)
+        if ":" in hostname and not hostname.startswith("["):
+            hostname = f"[{hostname}]"  # Add brackets around IPv6 addresses
         ALLOWED_HOSTS.append(hostname)
 
     return url

src/paperless/settings/custom.py

@@ -165,17 +165,6 @@ def parse_beat_schedule() -> dict:
                 "expires": 23.0 * 60.0 * 60.0,
             },
         },
-        {
-            "name": "Clear expired sessions",
-            "env_key": "PAPERLESS_SESSION_CLEANUP_TASK_CRON",
-            # Default daily at 03:00
-            "env_default": "0 3 * * *",
-            "task": "documents.tasks.clear_expired_sessions",
-            "options": {
-                # 1 hour before default schedule sends again
-                "expires": 23.0 * 60.0 * 60.0,
-            },
-        },
     ]
     for task in tasks:
         # Either get the environment setting or use the default

src/paperless/tests/parsers/test_tesseract_custom_settings.py

@@ -243,34 +243,6 @@ class TestParserSettingsFromDb(DirectoriesMixin, FileSystemAssertsMixin, TestCas
             "UseDeviceIndependentColor",
         )
 
-    def test_ocr_user_args_cannot_override_reserved(self) -> None:
-        """
-        GIVEN:
-            - User arguments which attempt to override arguments the parser
-              manages itself, alongside a legitimate argument
-        WHEN:
-            - OCR parameters are constructed
-        THEN:
-            - Reserved arguments keep the parser supplied values
-            - The legitimate argument is still applied
-        """
-        instance = ApplicationConfiguration.objects.all().first()
-        assert instance is not None
-        instance.user_args = {
-            "sidecar": "/tmp/evil.py",
-            "output_file": "/tmp/out.pdf",
-            "input_file_or_options": "/etc/passwd",
-            "unpaper_args": "--pre-rotate 90",
-        }
-        instance.save()
-
-        params = self.get_params()
-
-        self.assertEqual(params["sidecar"], "sidecar.txt")
-        self.assertEqual(params["output_file"], "output.pdf")
-        self.assertEqual(params["input_file_or_options"], "input.pdf")
-        self.assertEqual(params["unpaper_args"], "--pre-rotate 90")
-
     def test_ocr_user_args(self) -> None:
         """
         GIVEN:

src/paperless/tests/settings/test_custom_parsers.py

@@ -182,7 +182,6 @@ def make_expected_schedule(
     workflow_expire = 59.0 * 60.0
     llm_index_expire = 23.0 * 60.0 * 60.0
     share_link_cleanup_expire = 23.0 * 60.0 * 60.0
-    session_cleanup_expire = 23.0 * 60.0 * 60.0
 
     schedule: dict[str, Any] = {
         "Check all e-mail accounts": {
@@ -249,14 +248,6 @@ def make_expected_schedule(
                 "headers": {"trigger_source": "scheduled"},
             },
         },
-        "Clear expired sessions": {
-            "task": "documents.tasks.clear_expired_sessions",
-            "schedule": crontab(minute=0, hour="3"),
-            "options": {
-                "expires": session_cleanup_expire,
-                "headers": {"trigger_source": "scheduled"},
-            },
-        },
     }
 
     overrides = overrides or {}
@@ -307,7 +298,6 @@ class TestParseBeatSchedule:
                     "PAPERLESS_WORKFLOW_SCHEDULED_TASK_CRON": "disable",
                     "PAPERLESS_LLM_INDEX_TASK_CRON": "disable",
                     "PAPERLESS_SHARE_LINK_BUNDLE_CLEANUP_CRON": "disable",
-                    "PAPERLESS_SESSION_CLEANUP_TASK_CRON": "disable",
                 },
                 {},
                 id="all-disabled",

src/paperless/tests/settings/test_settings.py

@@ -3,9 +3,14 @@ from unittest import TestCase
 from unittest import mock
 
 import pytest
+from django.core.exceptions import DisallowedHost
 from django.core.exceptions import ImproperlyConfigured
+from django.http import HttpRequest
+from django.test import override_settings
 
+import paperless.settings as paperless_settings
 from paperless.settings import _get_allauth_trusted_proxy_count
+from paperless.settings import _get_allowed_hosts
 from paperless.settings import _get_classifier_language_setting
 from paperless.settings import _get_search_language_setting
 from paperless.settings import _parse_paperless_url
@@ -168,8 +173,88 @@ class TestPaperlessURLSettings(TestCase):
             self.assertIn(url, settings.CORS_ALLOWED_ORIGINS)
 
 
-@pytest.mark.parametrize("url", ["example.com", "https://", "/just/a/path"])
-def test_paperless_url_without_hostname_is_rejected(
+@pytest.mark.parametrize(
+    ("url", "allowed_hosts", "expected", "accepted_host", "rejected_host"),
+    [
+        (None, None, ["*"], "other.example.com", None),
+        (None, "", ["localhost"], "localhost:8000", "other.example.com"),
+        (
+            None,
+            "lan.example.com",
+            ["lan.example.com", "localhost"],
+            "lan.example.com",
+            "other.example.com",
+        ),
+        (None, "*", ["*"], "other.example.com", None),
+        (
+            "https://example.com:8443",
+            None,
+            ["localhost", "example.com"],
+            "example.com:8443",
+            "other.example.com",
+        ),
+        (
+            "https://example.com.",
+            "",
+            ["localhost", "example.com"],
+            "example.com.",
+            "other.example.com",
+        ),
+        (
+            "http://[::1]:8000",
+            None,
+            ["localhost", "[::1]"],
+            "[::1]:8000",
+            "other.example.com",
+        ),
+        ("https://example.com", "*", ["*", "example.com"], "other.example.com", None),
+        (
+            "https://example.com",
+            "lan.example.com",
+            ["lan.example.com", "localhost", "example.com"],
+            "lan.example.com",
+            "other.example.com",
+        ),
+    ],
+)
+def test_allowed_hosts_at_startup(
+    monkeypatch: pytest.MonkeyPatch,
+    url: str | None,
+    allowed_hosts: str | None,
+    expected: list[str],
+    accepted_host: str,
+    rejected_host: str | None,
+) -> None:
+    for name, value in (
+        ("PAPERLESS_URL", url),
+        ("PAPERLESS_ALLOWED_HOSTS", allowed_hosts),
+    ):
+        if value is None:
+            monkeypatch.delenv(name, raising=False)
+        else:
+            monkeypatch.setenv(name, value)
+
+    monkeypatch.setattr(paperless_settings, "ALLOWED_HOSTS", _get_allowed_hosts())
+    monkeypatch.setattr(paperless_settings, "CSRF_TRUSTED_ORIGINS", [])
+    monkeypatch.setattr(paperless_settings, "CORS_ALLOWED_ORIGINS", [])
+    assert _parse_paperless_url() == url
+    assert expected == paperless_settings.ALLOWED_HOSTS
+
+    request = HttpRequest()
+    with override_settings(ALLOWED_HOSTS=expected):
+        request.META["HTTP_HOST"] = accepted_host
+        assert request.get_host() == accepted_host
+        if rejected_host:
+            request.META["HTTP_HOST"] = rejected_host
+            with pytest.raises(DisallowedHost):
+                request.get_host()
+
+
+@pytest.mark.parametrize(
+    "url",
+    ["example.com", "https://", "/just/a/path", "https://*", "https://.example.com"],
+)
+def test_paperless_url_without_valid_hostname_is_rejected(
     monkeypatch: pytest.MonkeyPatch,
     url: str,
 ) -> None:
@@ -179,9 +264,9 @@ def test_paperless_url_without_hostname_is_rejected(
     WHEN:
         - The URL is parsed
     THEN:
-        - A configuration error is raised instead of adding None to ALLOWED_HOSTS
+        - A configuration error is raised for missing or wildcard hostnames
     """
     monkeypatch.setenv("PAPERLESS_URL", url)
 
-    with pytest.raises(ImproperlyConfigured, match="no hostname"):
+    with pytest.raises(ImproperlyConfigured, match="no valid hostname"):
         _parse_paperless_url()