Make testing easier

.github/DISCUSSION_TEMPLATE/feature-requests.yml

@@ -1,23 +1,5 @@
 title: "[Feature Request] "
 body:
-  - type: markdown
-    attributes:
-      value: |
-        #### Use of AI tools
-
-        If this request was generated, in whole or in part, by an AI tool or agent you **must** say so using the field below. Failing to clearly disclose this is a violation of our [Code of Conduct](https://github.com/paperless-ngx/paperless-ngx/blob/main/CODE_OF_CONDUCT.md).
-
-        The project prefers thoughtful, well-described ideas to AI-generated content. Please describe the problem, your use case, the desired behavior, and who would benefit.
-  - type: dropdown
-    id: ai-usage
-    attributes:
-      label: AI usage
-      description: Was any part of this request written by an AI tool or agent?
-      options:
-        - No AI tools were used
-        - Yes, AI tools helped write this request
-    validations:
-      required: true
   - type: textarea
     id: description
     attributes:

.github/DISCUSSION_TEMPLATE/support.yml

@@ -1,21 +1,5 @@
 title: "[Support] "
 body:
-  - type: markdown
-    attributes:
-      value: |
-        #### Use of AI tools
-
-        If this post was generated, in whole or in part, by an AI tool or agent you **must** say so using the field below. Failing to clearly disclose this is a violation of our [Code of Conduct](https://github.com/paperless-ngx/paperless-ngx/blob/main/CODE_OF_CONDUCT.md).
-  - type: dropdown
-    id: ai-usage
-    attributes:
-      label: AI usage
-      description: Was any part of this post written by an AI tool or agent?
-      options:
-        - No AI tools were used
-        - Yes, AI tools helped write this post
-    validations:
-      required: true
   - type: textarea
     id: description
     attributes:

.pre-commit-config.yaml

@@ -38,7 +38,7 @@ repos:
           - json
   # See https://github.com/prettier/prettier/issues/15742 for the fork reason
   - repo: https://github.com/rbubley/mirrors-prettier
-    rev: 'v3.9.10'
+    rev: 'v3.9.9'
     hooks:
       - id: prettier
         types_or:
@@ -46,16 +46,16 @@ repos:
           - ts
           - markdown
         additional_dependencies:
-          - prettier@3.9.10
+          - prettier@3.9.9
           - 'prettier-plugin-organize-imports@4.3.0'
   # Python hooks
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.17.2
+    rev: v0.16.9
     hooks:
       - id: ruff-check
       - id: ruff-format
   - repo: https://github.com/tox-dev/pyproject-fmt
-    rev: "v2.30.3"
+    rev: "v2.29.4"
     hooks:
       - id: pyproject-fmt
         additional_dependencies: [tomli]

AGENTS.md

@@ -1,44 +0,0 @@
-# Guidance for AI agents
-
-Read [CONTRIBUTING.md](CONTRIBUTING.md) before working on this repository, especially [Use of AI Tools](CONTRIBUTING.md#use-of-ai-tools). These contribution rules apply to all agent-assisted work.
-
-## Contribution boundaries
-
-- Do not open or submit pull requests, including "on behalf of" a human. The project does not accept PRs from AI agents. Prepare local changes for a human to review, verify, and submit personally.
-- The project does not accept PRs that are entirely or mostly AI-derived. Human submission and disclosure do not override this rule.
-- AI-generated content must be clearly disclosed as described in the contributing guidelines. When handing work back to a human, identify what was generated or changed with AI assistance so they can disclose it accurately.
-- Trust matters. Encourage first-time contributors to discuss their proposed change before preparing a PR, especially for large changes or changes involving AI-generated code. New features and enhancements should almost always target an existing feature request with community interest and discussion.
-- The project prefers thoughtful, well-described ideas to AI-generated pull requests. Help contributors describe their problem, use case, desired behavior, and who would benefit. An implementation is not required for a valuable contribution, and a flawed implementation can obscure a useful idea before it receives proper discussion.
-- AI tools have lowered the effort needed to produce a PR, but reviewing and maintaining it still requires substantial work. Encourage discussion of the idea before investing in implementation and review.
-- Issue reports must describe observed behavior, reproduction steps, and relevant logs. Do not add speculative root causes, code analysis, or proposed fixes to agent-generated reports.
-
-## Security reports
-
-- AI-assisted security reports must meet the legitimacy and verification requirements in [SECURITY.md](SECURITY.md#ai-assisted-submissions). A human must verify a real Paperless-ngx code path, concrete reproduction steps, affected versions, and realistic security impact before submission.
-- Account for existing permission checks, configuration requirements, and trust boundaries. Speculation, scanner output, or concerns about third-party software or deployment choices without a demonstrated Paperless-ngx vulnerability do not meet this threshold and may be closed without extended discussion.
-- Disclose AI assistance and use the private vulnerability reporting channel specified in [SECURITY.md](SECURITY.md#reporting-a-vulnerability).
-
-## Working on changes
-
-- Read the relevant code, tests, and documentation before editing. Paperless-ngx is complex: trace interactions between affected components rather than assuming a change is isolated.
-- Keep changes focused on the requested work and follow existing patterns. Avoid unrelated refactoring, formatting, dependency updates, or generated-file changes.
-- Consider effects on permissions, document processing, background tasks, storage, and the API when those areas are involved.
-- Add or update meaningful tests for behavior changes and regressions. Do not weaken tests or checks to make a change pass.
-- Update user or developer documentation when behavior or setup changes.
-- Keep credentials and private documents out of commits, fixtures, logs, and examples.
-
-## Repository and validation
-
-- `src/`: Django back end.
-- `src-ui/`: Angular front end, managed with `pnpm`.
-- `docs/`: Documentation.
-- `docker/` and `scripts/`: Deployment and development tooling.
-- Base functional changes on `dev`; documentation-only changes may target `main`.
-
-Follow [the development documentation](docs/development.md) for environment setup and testing. Common checks after setup are:
-
-- Back end: run `uv run pytest` from `src/` (use a test path to focus on the affected area).
-- Front end: run `pnpm test` and `pnpm lint` from `src-ui/`.
-- Formatting and other pre-commit checks: run `uv run prek run --files <changed-files>` from the repository root.
-
-When handing work back, summarize the changes, the checks actually run and their results, and any remaining uncertainty. Clearly state when a check could not be run; do not claim verification that did not happen. The human contributor must understand and independently verify the contribution before submitting it.

CONTRIBUTING.md

@@ -4,18 +4,6 @@ If you feel like contributing to the project, please do! Bug fixes and improveme
 
 ⚠️ Please note: Pull requests that implement a new feature or enhancement _should almost always target an existing feature request_ with evidence of community interest and discussion. This is in order to balance the work of implementing and maintaining new features / enhancements. Pull requests that are opened without meeting this requirement may not be merged.
 
-## Trust and collaboration
-
-Paperless-ngx places a high value on trust between contributors and maintainers. If you have not contributed before, consider starting with a discussion before preparing a pull request, especially for a large contribution or one involving AI-generated code.
-
-Paperless-ngx is complex, and understanding how its components interact takes time. A change that appears correct in isolation can have consequences elsewhere in the application. Contributors should understand the code they submit, explain how it fits into the project, and work with maintainers through review. Starting with smaller, focused contributions can help build that understanding and trust.
-
-We prefer thoughtful, well-described ideas to AI-generated pull requests. You do not need to supply an implementation for your contribution to be valuable. Explain the problem you have encountered, your use case, the behavior you would like to see, and who would benefit. Concrete examples, alternatives you have considered, and relevant constraints help the community discuss and refine the idea.
-
-AI tools have lowered the effort needed to produce a pull request, but evaluating one still requires substantial maintainer time. Maintainers still need to establish whether the implementation is correct, fits the project, and can be maintained over time.
-
-A flawed implementation can also obscure a good idea: discussion becomes focused on problems with the generated code before the community has considered whether the underlying proposal is useful. Starting with the idea gives it a fair discussion on its own merits and lets contributors and maintainers agree on an approach before investing in implementation and review.
-
 If you want to implement something big:
 
 - As above, please start with a discussion! Maybe something similar is already in development and we can make it happen together.
@@ -73,10 +61,9 @@ This project does not specifically prohibit the use of AI tools or agents _durin
 
 1. Any content — code, pull request descriptions, issue reports or comments — that was generated in whole or in part by an AI tool or agent **must be clearly disclosed as such**. Failing to clearly disclose this is considered a violation of our [Code of Conduct](CODE_OF_CONDUCT.md) and may result in your contributions being closed and further action being taken.
 2. AI-generated code must not violate copyright protections.
-3. We will not accept PRs opened or submitted by AI agents, including agents acting "on behalf of" a human. A human contributor must personally review, verify, and submit the contribution and take responsibility for it throughout review.
-4. We will not accept PRs that are entirely or mostly AI-derived.
-5. Issue reports must describe _observed behavior only_: what happened, how to reproduce it and the relevant logs. Reports generated by an AI agent should not include code analysis, speculation about the root cause or suggest fixes.
-6. Contributors are responsible for everything they submit, regardless of how it was produced. Please do not open issues or PRs you have not verified yourself.
+3. We will not accept PRs that are entirely or mostly AI-derived.
+4. Issue reports must describe _observed behavior only_: what happened, how to reproduce it and the relevant logs. Reports generated by an AI agent should not include code analysis, speculation about the root cause or suggest fixes.
+5. Contributors are responsible for everything they submit, regardless of how it was produced. Please do not open issues or PRs you have not verified yourself.
 
 # Translating Paperless-ngx
 

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.

pyproject.toml

@@ -212,7 +212,12 @@ extend-select = [
   "UP",   # https://docs.astral.sh/ruff/rules/#pyupgrade-up
   "W",    # https://docs.astral.sh/ruff/rules/#pycodestyle-e-w
 ]
-ignore = [ "DJ001", "ICN001", "PLC0415", "RUF012", "SIM105" ]
+ignore = [
+  "DJ001",
+  "PLC0415",
+  "RUF012",
+  "SIM105",
+]
 # Migrations
 per-file-ignores."*/migrations/*.py" = [
   "E501",

src/documents/consumer.py

@@ -631,7 +631,9 @@ class ConsumerPlugin(
                                     pk=self.metadata.actor_id,
                                 ).first()
                                 if actor is not None:
-                                    from auditlog.context import set_actor  # type: ignore[import-untyped]
+                                    from auditlog.context import (  # type: ignore[import-untyped]
+                                        set_actor,
+                                    )
 
                                     with set_actor(actor):
                                         original_document.save()
@@ -649,7 +651,9 @@ class ConsumerPlugin(
 
                             # Create a log entry for the version addition, if enabled
                             if settings.AUDIT_LOG_ENABLED:
-                                from auditlog.models import LogEntry  # type: ignore[import-untyped]
+                                from auditlog.models import (  # type: ignore[import-untyped]
+                                    LogEntry,
+                                )
 
                                 LogEntry.objects.log_create(
                                     instance=root_doc,

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_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/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/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()