Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

chore(checks): move core system checks to posthog/checks.py with namespaced ids (#129832)

Rafael Audibert4256554640d2
diff --git a/docs/published/handbook/engineering/oauth-development-guide.md b/docs/published/handbook/engineering/oauth-development-guide.md
index b45df483b5a3..b8cb86226df7 100644
--- a/docs/published/handbook/engineering/oauth-development-guide.md
+++ b/docs/published/handbook/engineering/oauth-development-guide.md
@@ -30,7 +30,7 @@ openssl genrsa 2048 | openssl pkcs8 -topk8 -nocrypt -outform PEM | \
```
Without this key, PostHog cannot create OAuth applications.
-Django's system checks print warning `posthog.W001` at startup.
+Django's system checks print warning `posthog.oauth.W001` at startup.
Client ID metadata document clients, dynamic client registration and toolbar sign-in get an OAuth `server_error` that names the missing setting.
### 2. Set Up Your Environment
diff --git a/posthog/api/oauth/cimd.py b/posthog/api/oauth/cimd.py
index 22bf3ae5038f..d9914649fe9d 100644
--- a/posthog/api/oauth/cimd.py
+++ b/posthog/api/oauth/cimd.py
@@ -30,14 +30,15 @@ from rest_framework.throttling import SimpleRateThrottle
from posthog.exceptions_capture import capture_exception
from posthog.models.oauth import (
+ OIDC_SIGNING_KEY_MISSING_MESSAGE,
CIMDVerificationToken,
OAuthApplication,
TokenEndpointAuthMethod,
find_cimd_verification_token,
normalize_cimd_url,
+ oidc_signing_key_configured,
revoke_application_sessions,
)
-from posthog.oauth_signing_key import OIDC_SIGNING_KEY_MISSING_MESSAGE, oidc_signing_key_configured
from posthog.ph_client import ph_scoped_capture
from posthog.rate_limit import IPThrottle
from posthog.scopes import OIDC_SCOPES, filter_self_registered_ceiling, filter_to_unprivileged_scopes
diff --git a/posthog/api/oauth/dcr.py b/posthog/api/oauth/dcr.py
index 1bec2d04e82e..31048fb5dfd1 100644
--- a/posthog/api/oauth/dcr.py
+++ b/posthog/api/oauth/dcr.py
@@ -26,8 +26,12 @@ from rest_framework.response import Response
from rest_framework.views import APIView
from posthog.exceptions_capture import capture_exception
-from posthog.models.oauth import OAuthApplication, TokenEndpointAuthMethod
-from posthog.oauth_signing_key import OIDC_SIGNING_KEY_MISSING_MESSAGE, oidc_signing_key_configured
+from posthog.models.oauth import (
+ OIDC_SIGNING_KEY_MISSING_MESSAGE,
+ OAuthApplication,
+ TokenEndpointAuthMethod,
+ oidc_signing_key_configured,
+)
from posthog.rate_limit import IPThrottle
from posthog.scopes import OIDC_SCOPES, filter_self_registered_ceiling
diff --git a/posthog/api/oauth/toolbar_service.py b/posthog/api/oauth/toolbar_service.py
index 0b9097131359..4ed224f68944 100644
--- a/posthog/api/oauth/toolbar_service.py
+++ b/posthog/api/oauth/toolbar_service.py
@@ -24,9 +24,13 @@ import structlog
from posthog.api.utils import canonicalize_encoded_url, strip_url_userinfo, unparsed_hostname_in_allowed_url_list
from posthog.models import Team, User
-from posthog.models.oauth import OAuthApplication, is_loopback_host
+from posthog.models.oauth import (
+ OIDC_SIGNING_KEY_MISSING_MESSAGE,
+ OAuthApplication,
+ is_loopback_host,
+ oidc_signing_key_configured,
+)
from posthog.models.organization import Organization
-from posthog.oauth_signing_key import OIDC_SIGNING_KEY_MISSING_MESSAGE, oidc_signing_key_configured
logger = structlog.get_logger(__name__)
diff --git a/posthog/apps.py b/posthog/apps.py
index 3f13298322a3..785313547627 100644
--- a/posthog/apps.py
+++ b/posthog/apps.py
@@ -52,8 +52,7 @@ class PostHogConfig(AppConfig):
# django.setup(), so a process that never builds the router (celery, temporal, migrate,
# shell) would lose them. They live in dedicated import-light modules — never wire
# ready() through an API module, even one that looks light today.
- import posthog.storage.checks # noqa: F401, PLC0415
- import posthog.oauth_signing_key # noqa: F401, PLC0415
+ import posthog.checks # noqa: F401, PLC0415
import posthog.models.file_system.signal_handlers # noqa: F401, PLC0415
import posthog.caching.organization_serializer_cache # noqa: F401, PLC0415
import posthog.models.activity_logging.signal_handlers # noqa: F401, PLC0415
diff --git a/posthog/checks.py b/posthog/checks.py
new file mode 100644
index 000000000000..dd76a7e6eb40
--- /dev/null
+++ b/posthog/checks.py
@@ -0,0 +1,139 @@
+"""Core Django system checks, and the ID scheme every PostHog system check follows.
+
+A system check catches a deployment misconfiguration when the process starts (`migrate`, `check`,
+`runserver`) instead of in user traffic. Each check ID has the form `posthog.<area>.<level><nnn>`:
+
+- `<area>` names what the check guards, such as `oauth` or `storage`. A product check uses the
+ product name, such as `posthog.canvas.E001`.
+- `<level>` is `E` for an error, which stops `migrate` and `runserver`, or `W` for a warning,
+ which only prints.
+- `<nnn>` counts up from 001 inside each area and level. Never reuse a retired number.
+
+Core checks live in this module, grouped by area. A product check lives in its product's
+`backend/checks.py` and registers through `register_check` from this module. Declare every ID a
+check can emit in `register_check`, so `test_system_check_ids.py` can verify them from Django's
+check registry without running the check.
+"""
+
+import re
+from collections.abc import Callable, Sequence
+from typing import Any
+
+from django.conf import settings
+from django.core.checks import CheckMessage, Error, Warning, register
+
+from posthog.models.oauth import oidc_signing_key_configured
+from posthog.product_db_router import get_product_db_routes
+from posthog.storage.object_storage import is_usable_endpoint
+
+CHECK_ID_PATTERN = re.compile(r"^posthog\.[a-z][a-z0-9_]*\.[EW]\d{3}$")
+
+CheckFunction = Callable[..., list[CheckMessage]]
+
+
+def register_check(*check_ids: str, tags: Sequence[str] = ()) -> Callable[[CheckFunction], CheckFunction]:
+ def decorator(check: CheckFunction) -> CheckFunction:
+ setattr(check, "check_ids", check_ids) # noqa: B010
+ return register(*tags)(check)
+
+ return decorator
+
+
+# OAuth
+
+OAUTH_SIGNING_KEY_MISSING = "posthog.oauth.W001"
+
+
+@register_check(OAUTH_SIGNING_KEY_MISSING)
+def check_oidc_signing_key(app_configs: Any, **kwargs: Any) -> list[CheckMessage]:
+ if oidc_signing_key_configured():
+ return []
+ return [
+ Warning(
+ "OIDC_RSA_PRIVATE_KEY is not set, so OAuth clients cannot be created. "
+ "MCP clients, dynamic client registration and toolbar sign-in fail with an OAuth server_error.",
+ hint="Set OIDC_RSA_PRIVATE_KEY to an RSA private key in PEM format, for example the output of "
+ "`openssl genrsa 2048`.",
+ id=OAUTH_SIGNING_KEY_MISSING,
+ )
+ ]
+
+
+# Object storage
+
+STORAGE_PUBLIC_ENDPOINT_UNUSABLE = "posthog.storage.E001"
+
+
+@register_check(STORAGE_PUBLIC_ENDPOINT_UNUSABLE)
+def check_object_storage_public_endpoint(app_configs: Any, **kwargs: Any) -> list[CheckMessage]:
+ """Catch a misconfigured OBJECT_STORAGE_PUBLIC_ENDPOINT at startup rather than in user traffic.
+
+ An unsubstituted deployment template literal (e.g. `https://${POSTHOG_DOMAIN}`) makes boto3
+ raise `ValueError` on client construction, which previously surfaced as 500s on every
+ hypercache-backed read. Failing the system check makes the bad rollout obvious immediately.
+ """
+ errors: list[CheckMessage] = []
+
+ endpoint = settings.OBJECT_STORAGE_PUBLIC_ENDPOINT
+ if settings.OBJECT_STORAGE_ENABLED and endpoint and not is_usable_endpoint(endpoint):
+ errors.append(
+ Error(
+ f"OBJECT_STORAGE_PUBLIC_ENDPOINT is not a usable URL: {endpoint!r}",
+ hint="Check the deployment env — it likely contains an unsubstituted ${...} template placeholder.",
+ id=STORAGE_PUBLIC_ENDPOINT_UNUSABLE,
+ )
+ )
+
+ return errors
+
+
+# Field encryption
+
+ENCRYPTION_SALT_KEY_WRONG_LENGTH = "posthog.encryption.E001"
+
+
+@register_check(ENCRYPTION_SALT_KEY_WRONG_LENGTH)
+def check_encryption_salt_keys(app_configs: Any, **kwargs: Any) -> list[CheckMessage]:
+ # Each ENCRYPTION_SALT_KEYS entry is used directly as a Fernet key, which must be exactly 32 bytes.
+ # A wrong-length key otherwise fails lazily with an opaque error on the first encrypt/decrypt — and
+ # during a SECRET_KEY / ENCRYPTION_SALT_KEYS rotation that surfaces as a confusing runtime crash
+ # instead of a clear config error. SECRET_KEY / SALT_KEY are exempt: they run through PBKDF2, which
+ # normalizes any input length to 32 bytes.
+ errors: list[CheckMessage] = []
+ for index, key in enumerate(settings.ENCRYPTION_SALT_KEYS):
+ byte_length = len(key.encode("utf-8"))
+ if byte_length != 32:
+ errors.append(
+ Error(
+ f"ENCRYPTION_SALT_KEYS[{index}] must be exactly 32 bytes, got {byte_length}.",
+ hint="Generate one with `openssl rand -hex 16` (produces 32 characters).",
+ id=ENCRYPTION_SALT_KEY_WRONG_LENGTH,
+ )
+ )
+ return errors
+
+
+# Product database routing
+
+DB_ROUTER_APP_ON_SEVERAL_DATABASES = "posthog.db_router.E001"
+
+
+@register_check(DB_ROUTER_APP_ON_SEVERAL_DATABASES)
+def check_product_db_routes(app_configs: Any, **kwargs: Any) -> list[CheckMessage]:
+ errors: list[CheckMessage] = []
+
+ app_label_to_database: dict[str, str] = {}
+
+ for route in get_product_db_routes():
+ existing = app_label_to_database.get(route.app_label)
+ if existing is not None and existing != route.database:
+ errors.append(
+ Error(
+ f"product db route for '{route.app_label}' points to multiple databases",
+ hint="Ensure each product app has exactly one database in db_routing.yaml",
+ id=DB_ROUTER_APP_ON_SEVERAL_DATABASES,
+ )
+ )
+ app_label_to_database[route.app_label] = route.database
+
+ return errors
diff --git a/posthog/helpers/encrypted_fields.py b/posthog/helpers/encrypted_fields.py
index d3dadca84d47..82b9cd0fc85b 100644
--- a/posthog/helpers/encrypted_fields.py
+++ b/posthog/helpers/encrypted_fields.py
@@ -5,7 +5,6 @@ import json
import base64
from django.conf import settings
-from django.core.checks import Error, register
from django.db import models
from django.utils.functional import cached_property
@@ -237,24 +236,3 @@ class EncryptedJSONStringField(EncryptedFieldMixin, models.JSONField):
pass
return value
-
-
-@register()
-def check_encryption_salt_keys(app_configs, **kwargs):
- # Each ENCRYPTION_SALT_KEYS entry is used directly as a Fernet key, which must be exactly 32 bytes.
- # A wrong-length key otherwise fails lazily with an opaque error on the first encrypt/decrypt — and
- # during a SECRET_KEY / ENCRYPTION_SALT_KEYS rotation that surfaces as a confusing runtime crash
- # instead of a clear config error. SECRET_KEY / SALT_KEY are exempt: they run through PBKDF2, which
- # normalizes any input length to 32 bytes.
- errors = []
- for index, key in enumerate(settings.ENCRYPTION_SALT_KEYS):
- byte_length = len(key.encode("utf-8"))
- if byte_length != 32:
- errors.append(
- Error(
- f"ENCRYPTION_SALT_KEYS[{index}] must be exactly 32 bytes, got {byte_length}.",
- hint="Generate one with `openssl rand -hex 16` (produces 32 characters).",
- id="posthog.E004",
- )
- )
- return errors
diff --git a/posthog/helpers/tests/test_encrypted_fields.py b/posthog/helpers/tests/test_encrypted_fields.py
index 891ab617f348..5f8c005b5577 100644
--- a/posthog/helpers/tests/test_encrypted_fields.py
+++ b/posthog/helpers/tests/test_encrypted_fields.py
@@ -11,8 +11,7 @@ from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
from parameterized import parameterized
-from posthog.helpers.encrypted_fields import EncryptedFieldMixin, check_encryption_salt_keys
-from posthog.settings.utils import get_list
+from posthog.helpers.encrypted_fields import EncryptedFieldMixin
KEY_A = "a" * 32
KEY_B = "b" * 32
@@ -206,47 +205,3 @@ class TestSecretKeyRotation(SimpleTestCase):
assert _fernet(KEY_A).decrypt(token.encode("utf-8")).decode("utf-8") == PLAINTEXT
with self.assertRaises(InvalidToken):
_legacy_fernet(NEW).decrypt(token.encode("utf-8"))
-
-
-class TestEncryptionSaltKeysCheck(SimpleTestCase):
- # System check that ENCRYPTION_SALT_KEYS entries are valid Fernet keys (exactly 32 bytes). Each is
- # used directly as a Fernet key, so a wrong-length one would otherwise crash opaquely on first use.
-
- @override_settings(ENCRYPTION_SALT_KEYS=["00beef0000beef0000beef0000beef00"])
- def test_single_valid_key_passes(self):
- assert check_encryption_salt_keys(None) == []
-
- @override_settings(ENCRYPTION_SALT_KEYS=get_list("00beef0000beef0000beef0000beef00," + "a" * 32))
- def test_two_valid_keys_pass(self):
- assert check_encryption_salt_keys(None) == []
-
- @override_settings(ENCRYPTION_SALT_KEYS=get_list(",".join(["a" * 32, "b" * 32, "c" * 32])))
- def test_three_valid_keys_pass(self):
- assert check_encryption_salt_keys(None) == []
-
- @override_settings(ENCRYPTION_SALT_KEYS=["tooshort"])
- def test_short_key_is_flagged(self):
- errors = check_encryption_salt_keys(None)
- assert len(errors) == 1
- assert errors[0].id == "posthog.E004"
- assert "ENCRYPTION_SALT_KEYS[0]" in errors[0].msg
- assert "got 8" in errors[0].msg
-
- @override_settings(ENCRYPTION_SALT_KEYS=["a" * 33])
- def test_long_key_is_flagged(self):
- errors = check_encryption_salt_keys(None)
- assert len(errors) == 1
- assert "got 33" in errors[0].msg
-
- @override_settings(ENCRYPTION_SALT_KEYS=["a" * 32, "b" * 31])
- def test_reports_index_of_offending_key(self):
- errors = check_encryption_salt_keys(None)
- assert len(errors) == 1
- assert "ENCRYPTION_SALT_KEYS[1]" in errors[0].msg
-
- @override_settings(ENCRYPTION_SALT_KEYS=["é" * 32])
- def test_counts_bytes_not_characters(self):
- # 32 'é' is 64 bytes in UTF-8 — must be flagged, since Fernet keys are byte-sized
- errors = check_encryption_salt_keys(None)
- assert len(errors) == 1
- assert "got 64" in errors[0].msg
diff --git a/posthog/models/oauth.py b/posthog/models/oauth.py
index b4e28eb3e0ed..196b039888f3 100644
--- a/posthog/models/oauth.py
+++ b/posthog/models/oauth.py
@@ -99,6 +99,18 @@ def is_loopback_host(hostname: str | None) -> bool:
return False
+OIDC_SIGNING_KEY_MISSING_MESSAGE = (
+ "OAuth is not set up on this PostHog instance. "
+ "Ask the instance admin to set the OIDC_RSA_PRIVATE_KEY environment variable to an RSA private key in PEM format."
+)
+
+
+def oidc_signing_key_configured() -> bool:
+ # Every OAuth client PostHog creates (CIMD, DCR, toolbar) uses RS256, and OAuthApplication.clean()
+ # rejects RS256 without this key, so no client can be created or updated while it is unset.
+ return bool(oauth2_settings.OIDC_RSA_PRIVATE_KEY)
+
+
class OAuthApplication(ModelActivityMixin, AbstractApplication): # type: ignore[django-manager-missing]
id: models.UUIDField = models.UUIDField(primary_key=True, default=UUIDT, editable=False)
@@ -519,7 +531,7 @@ class OAuthApplication(ModelActivityMixin, AbstractApplication): # type: ignore
for origin in allowed_origins:
origin_validator(origin)
- if self.algorithm == AbstractApplication.RS256_ALGORITHM and not oauth2_settings.OIDC_RSA_PRIVATE_KEY:
+ if self.algorithm == AbstractApplication.RS256_ALGORITHM and not oidc_signing_key_configured():
raise ValidationError("You must set OIDC_RSA_PRIVATE_KEY to use RSA algorithm")
if self.algorithm == AbstractApplication.HS256_ALGORITHM and (
diff --git a/posthog/oauth_signing_key.py b/posthog/oauth_signing_key.py
deleted file mode 100644
index 2ed16895159d..000000000000
--- a/posthog/oauth_signing_key.py
+++ /dev/null
@@ -1,31 +0,0 @@
-from typing import Any
-
-from django.core.checks import CheckMessage, Warning, register
-
-from oauth2_provider.settings import oauth2_settings
-
-OIDC_SIGNING_KEY_MISSING_MESSAGE = (
- "OAuth is not set up on this PostHog instance. "
- "Ask the instance admin to set the OIDC_RSA_PRIVATE_KEY environment variable to an RSA private key in PEM format."
-)
-
-
-def oidc_signing_key_configured() -> bool:
- # Every OAuth client PostHog creates (CIMD, DCR, toolbar) uses RS256, and OAuthApplication.clean()
- # rejects RS256 without this key, so no client can be created or updated while it is unset.
- return bool(oauth2_settings.OIDC_RSA_PRIVATE_KEY)
-
-
-@register()
-def check_oidc_signing_key(app_configs: Any, **kwargs: Any) -> list[CheckMessage]:
- if oidc_signing_key_configured():
- return []
- return [
- Warning(
- "OIDC_RSA_PRIVATE_KEY is not set, so OAuth clients cannot be created. "
- "MCP clients, dynamic client registration and toolbar sign-in fail with an OAuth server_error.",
- hint="Set OIDC_RSA_PRIVATE_KEY to an RSA private key in PEM format, for example the output of "
- "`openssl genrsa 2048`.",
- id="posthog.W001",
- )
- ]
diff --git a/posthog/product_db_router.py b/posthog/product_db_router.py
index 04053fba2fc4..397032e4962a 100644
--- a/posthog/product_db_router.py
+++ b/posthog/product_db_router.py
@@ -3,7 +3,6 @@ from __future__ import annotations
from functools import lru_cache
from django.conf import settings
-from django.core.checks import Error, register
from posthog.product_db_config import ProductDBRoute, load_product_db_routes
from posthog.settings.base_variables import TEST
@@ -63,25 +62,3 @@ class ProductDBRouter:
return False
return None
-
-
-@register()
-def check_product_db_routes(app_configs, **kwargs):
- errors: list[Error] = []
-
- routes = get_product_db_routes()
- app_label_to_database: dict[str, str] = {}
-
- for route in routes:
- existing = app_label_to_database.get(route.app_label)
- if existing is not None and existing != route.database:
- errors.append(
- Error(
- f"product db route for '{route.app_label}' points to multiple databases",
- hint="Ensure each product app has exactly one database in db_routing.yaml",
- id="posthog.E003",
- )
- )
- app_label_to_database[route.app_label] = route.database
-
- return errors
diff --git a/posthog/settings/access.py b/posthog/settings/access.py
index 8e32e12da505..8d0ca9d3b781 100644
--- a/posthog/settings/access.py
+++ b/posthog/settings/access.py
@@ -153,7 +153,7 @@ AGENT_PROXY_CALLBACK_SECRET: str | None = os.getenv("AGENT_PROXY_CALLBACK_SECRET
# These are legacy values only kept around for backwards compatibility with self hosted versions
SALT_KEY = get_list(os.getenv("SALT_KEY", "0123456789abcdefghijklmnopqrstuvwxyz"))
# We provide a default as it is needed for hobby deployments. Each entry must be exactly 32 bytes
-# (used directly as a Fernet key) — enforced by check_encryption_salt_keys in encrypted_fields.py.
+# (used directly as a Fernet key) — enforced by check_encryption_salt_keys in posthog/checks.py.
ENCRYPTION_SALT_KEYS = get_list(os.getenv("ENCRYPTION_SALT_KEYS", "00beef0000beef0000beef0000beef00"))
INTERNAL_IPS = ["127.0.0.1", "172.18.0.1"] # Docker IP
diff --git a/posthog/storage/checks.py b/posthog/storage/checks.py
deleted file mode 100644
index e59056e93ba1..000000000000
--- a/posthog/storage/checks.py
+++ /dev/null
@@ -1,27 +0,0 @@
-from django.conf import settings
-from django.core.checks import Error, register
-
-from posthog.storage.object_storage import is_usable_endpoint
-
-
-@register()
-def check_object_storage_public_endpoint(app_configs, **kwargs):
- """Catch a misconfigured OBJECT_STORAGE_PUBLIC_ENDPOINT at startup rather than in user traffic.
-
- An unsubstituted deployment template literal (e.g. `https://${POSTHOG_DOMAIN}`) makes boto3
- raise `ValueError` on client construction, which previously surfaced as 500s on every
- hypercache-backed read. Failing the system check makes the bad rollout obvious immediately.
- """
- errors: list[Error] = []
-
- endpoint = settings.OBJECT_STORAGE_PUBLIC_ENDPOINT
- if settings.OBJECT_STORAGE_ENABLED and endpoint and not is_usable_endpoint(endpoint):
- errors.append(
- Error(
- f"OBJECT_STORAGE_PUBLIC_ENDPOINT is not a usable URL: {endpoint!r}",
- hint="Check the deployment env — it likely contains an unsubstituted ${...} template placeholder.",
- id="posthog.E004",
- )
- )
-
- return errors
diff --git a/posthog/storage/test/test_checks.py b/posthog/storage/test/test_checks.py
deleted file mode 100644
index 2d8f5b654381..000000000000
--- a/posthog/storage/test/test_checks.py
+++ /dev/null
@@ -1,29 +0,0 @@
-from django.test import SimpleTestCase
-
-from posthog.storage.checks import check_object_storage_public_endpoint
-
-
-class TestObjectStoragePublicEndpointCheck(SimpleTestCase):
- def test_no_error_for_valid_endpoint(self) -> None:
- with self.settings(
- OBJECT_STORAGE_ENABLED=True,
- OBJECT_STORAGE_PUBLIC_ENDPOINT="https://public.example.com",
- ):
- assert check_object_storage_public_endpoint(None) == []
-
- def test_error_for_unsubstituted_placeholder(self) -> None:
- with self.settings(
- OBJECT_STORAGE_ENABLED=True,
- OBJECT_STORAGE_PUBLIC_ENDPOINT="https://${POSTHOG_DOMAIN}",
- ):
- errors = check_object_storage_public_endpoint(None)
-
- assert len(errors) == 1
- assert errors[0].id == "posthog.E004"
-
- def test_no_error_when_storage_disabled(self) -> None:
- with self.settings(
- OBJECT_STORAGE_ENABLED=False,
- OBJECT_STORAGE_PUBLIC_ENDPOINT="https://${POSTHOG_DOMAIN}",
- ):
- assert check_object_storage_public_endpoint(None) == []
diff --git a/posthog/test/repo_invariants/test_system_check_ids.py b/posthog/test/repo_invariants/test_system_check_ids.py
new file mode 100644
index 000000000000..367316121acc
--- /dev/null
+++ b/posthog/test/repo_invariants/test_system_check_ids.py
@@ -0,0 +1,48 @@
+from collections import Counter
+from collections.abc import Callable
+from typing import Any
+
+from django.core.checks.registry import registry
+
+from posthog.checks import CHECK_ID_PATTERN
+
+OWNED_PACKAGES = ("posthog", "ee", "products", "common")
+
+
+def _owned_checks() -> list[Callable[..., Any]]:
+ checks = registry.get_checks(include_deployment_checks=True)
+ return [check for check in checks if check.__module__.split(".")[0] in OWNED_PACKAGES]
+
+
+def _label(check: Callable[..., Any]) -> str:
+ return f"{check.__module__}.{check.__qualname__}"
+
+
+def test_every_system_check_declares_ids_in_the_posthog_scheme() -> None:
+ checks = _owned_checks()
+ assert checks, "No PostHog system check is registered, so this test checks nothing."
+
+ problems: list[str] = []
+ for check in checks:
+ check_ids: tuple[str, ...] = getattr(check, "check_ids", ())
+ if not check_ids:
+ problems.append(f"{_label(check)} declares no IDs. Register it with posthog.checks.register_check.")
+ for check_id in check_ids:
+ if not CHECK_ID_PATTERN.match(check_id):
+ problems.append(f"{_label(check)} emits {check_id!r}, which is not posthog.<area>.<E|W><nnn>.")
+ module_parts = check.__module__.split(".")
+ if module_parts[0] == "products":
+ prefix = f"posthog.{module_parts[1]}."
+ problems.extend(
+ f"{_label(check)} emits {check_id!r}, but a product check must start with {prefix!r}."
+ for check_id in check_ids
+ if not check_id.startswith(prefix)
+ )
+
+ assert not problems, "\n".join(problems)
+
+
+def test_system_check_ids_are_unique() -> None:
+ counts = Counter(check_id for check in _owned_checks() for check_id in getattr(check, "check_ids", ()))
+ duplicates = sorted(check_id for check_id, count in counts.items() if count > 1)
+ assert not duplicates, f"These system check IDs are declared by more than one check: {duplicates}"
diff --git a/posthog/test/test_checks.py b/posthog/test/test_checks.py
new file mode 100644
index 000000000000..d3ffdbb8962f
--- /dev/null
+++ b/posthog/test/test_checks.py
@@ -0,0 +1,86 @@
+from pathlib import Path
+
+from django.test import SimpleTestCase, override_settings
+
+from posthog.checks import check_encryption_salt_keys, check_object_storage_public_endpoint, check_product_db_routes
+from posthog.product_db_router import get_product_db_routes
+from posthog.settings.utils import get_list
+
+
+class TestObjectStoragePublicEndpointCheck(SimpleTestCase):
+ def test_no_error_for_valid_endpoint(self) -> None:
+ with self.settings(
+ OBJECT_STORAGE_ENABLED=True,
+ OBJECT_STORAGE_PUBLIC_ENDPOINT="https://public.example.com",
+ ):
+ assert check_object_storage_public_endpoint(None) == []
+
+ def test_error_for_unsubstituted_placeholder(self) -> None:
+ with self.settings(
+ OBJECT_STORAGE_ENABLED=True,
+ OBJECT_STORAGE_PUBLIC_ENDPOINT="https://${POSTHOG_DOMAIN}",
+ ):
+ errors = check_object_storage_public_endpoint(None)
+
+ assert len(errors) == 1
+ assert errors[0].id == "posthog.storage.E001"
+
+ def test_no_error_when_storage_disabled(self) -> None:
+ with self.settings(
+ OBJECT_STORAGE_ENABLED=False,
+ OBJECT_STORAGE_PUBLIC_ENDPOINT="https://${POSTHOG_DOMAIN}",
+ ):
+ assert check_object_storage_public_endpoint(None) == []
+
+
+class TestEncryptionSaltKeysCheck(SimpleTestCase):
+ # System check that ENCRYPTION_SALT_KEYS entries are valid Fernet keys (exactly 32 bytes). Each is
+ # used directly as a Fernet key, so a wrong-length one would otherwise crash opaquely on first use.
+
+ @override_settings(ENCRYPTION_SALT_KEYS=["00beef0000beef0000beef0000beef00"])
+ def test_single_valid_key_passes(self):
+ assert check_encryption_salt_keys(None) == []
+
+ @override_settings(ENCRYPTION_SALT_KEYS=get_list("00beef0000beef0000beef0000beef00," + "a" * 32))
+ def test_two_valid_keys_pass(self):
+ assert check_encryption_salt_keys(None) == []
+
+ @override_settings(ENCRYPTION_SALT_KEYS=get_list(",".join(["a" * 32, "b" * 32, "c" * 32])))
+ def test_three_valid_keys_pass(self):
+ assert check_encryption_salt_keys(None) == []
+
+ @override_settings(ENCRYPTION_SALT_KEYS=["tooshort"])
+ def test_short_key_is_flagged(self):
+ errors = check_encryption_salt_keys(None)
+ assert len(errors) == 1
+ assert errors[0].id == "posthog.encryption.E001"
+ assert "ENCRYPTION_SALT_KEYS[0]" in errors[0].msg
+ assert "got 8" in errors[0].msg
+
+ @override_settings(ENCRYPTION_SALT_KEYS=["a" * 33])
+ def test_long_key_is_flagged(self):
+ errors = check_encryption_salt_keys(None)
+ assert len(errors) == 1
+ assert "got 33" in errors[0].msg
+
+ @override_settings(ENCRYPTION_SALT_KEYS=["a" * 32, "b" * 31])
+ def test_reports_index_of_offending_key(self):
+ errors = check_encryption_salt_keys(None)
+ assert len(errors) == 1
+ assert "ENCRYPTION_SALT_KEYS[1]" in errors[0].msg
+
+ @override_settings(ENCRYPTION_SALT_KEYS=["é" * 32])
+ def test_counts_bytes_not_characters(self):
+ # 32 'é' is 64 bytes in UTF-8 — must be flagged, since Fernet keys are byte-sized
+ errors = check_encryption_salt_keys(None)
+ assert len(errors) == 1
+ assert "got 64" in errors[0].msg
+
+
+class TestProductDBRouteChecks(SimpleTestCase):
+ @override_settings(BASE_DIR=Path(__file__).resolve().parents[2])
+ def test_check_passes_for_valid_route_config(self) -> None:
+ get_product_db_routes.cache_clear()
+ self.addCleanup(get_product_db_routes.cache_clear)
+
+ self.assertEqual(check_product_db_routes(None), [])
diff --git a/posthog/test/test_product_db_router.py b/posthog/test/test_product_db_router.py
index 9dd445af4242..25f743d9b0ad 100644
--- a/posthog/test/test_product_db_router.py
+++ b/posthog/test/test_product_db_router.py
@@ -4,7 +4,7 @@ from types import SimpleNamespace
from django.test import SimpleTestCase, override_settings
from posthog.product_db_config import ProductDBRoute, load_product_db_routes
-from posthog.product_db_router import ProductDBRouter, check_product_db_routes, get_product_db_routes
+from posthog.product_db_router import ProductDBRouter
FAKE_PRODUCT_DATABASES: dict[str, dict] = {
"default": {},
@@ -66,12 +66,3 @@ class TestProductDBRouteLoading(SimpleTestCase):
self.assertEqual(len(visual_review_routes), 1)
self.assertEqual(visual_review_routes[0].database, "visual_review")
self.assertTrue(visual_review_routes[0].source.endswith("products/db_routing.yaml"))
-
-
-class TestProductDBRouteChecks(SimpleTestCase):
- @override_settings(BASE_DIR=Path(__file__).resolve().parents[2])
- def test_check_passes_for_valid_route_config(self) -> None:
- get_product_db_routes.cache_clear()
- self.addCleanup(get_product_db_routes.cache_clear)
-
- self.assertEqual(check_product_db_routes(None), [])
diff --git a/products/canvas/backend/checks.py b/products/canvas/backend/checks.py
index 18a7c721f335..ea298221525c 100644
--- a/products/canvas/backend/checks.py
+++ b/products/canvas/backend/checks.py
@@ -4,16 +4,29 @@ A half-configured artifact origin used to fail silently: every build would
succeed and then serve ``artifact_url: null``. These system checks make a
misconfiguration fail the deploy instead. An entirely unset origin is legal —
it means artifact delivery is off (DEBUG/TEST fall back to SITE_URL).
+
+Check IDs follow the scheme documented at the top of posthog/checks.py.
"""
from typing import Any
from django.conf import settings
-from django.core.checks import Error, register
+from django.core.checks import CheckMessage, Error
+
+from posthog.checks import register_check
+
+CANVAS_ARTIFACT_DELIVERY_INCOMPLETE = "posthog.canvas.E001"
+CANVAS_ARTIFACT_ORIGIN_INVALID = "posthog.canvas.E002"
+CANVAS_ARTIFACT_SIGNING_KEY_TOO_SHORT = "posthog.canvas.E003"
-@register("canvas")
-def check_artifact_delivery_settings(app_configs: Any, **kwargs: Any) -> list[Error]:
+@register_check(
+ CANVAS_ARTIFACT_DELIVERY_INCOMPLETE,
+ CANVAS_ARTIFACT_ORIGIN_INVALID,
+ CANVAS_ARTIFACT_SIGNING_KEY_TOO_SHORT,
+ tags=["canvas"],
+)
+def check_artifact_delivery_settings(app_configs: Any, **kwargs: Any) -> list[CheckMessage]:
if settings.DEBUG or settings.TEST:
return []
origin = settings.CANVAS_ARTIFACT_ORIGIN
@@ -26,14 +39,14 @@ def check_artifact_delivery_settings(app_configs: Any, **kwargs: Any) -> list[Er
_configured_artifact_host,
)
- errors: list[Error] = []
+ errors: list[CheckMessage] = []
keys = _artifact_signing_keys()
if not origin or not keys:
errors.append(
Error(
"Canvas artifact delivery needs CANVAS_ARTIFACT_ORIGIN and a signing key from "
"CANVAS_ARTIFACT_SIGNING_KEYS or SECRET_KEY.",
- id="canvas.E001",
+ id=CANVAS_ARTIFACT_DELIVERY_INCOMPLETE,
)
)
if origin and _configured_artifact_host() is None:
@@ -41,7 +54,7 @@ def check_artifact_delivery_settings(app_configs: Any, **kwargs: Any) -> list[Er
Error(
f"CANVAS_ARTIFACT_ORIGIN ({origin!r}) must be a bare https origin with no path, "
"query, fragment, or credentials.",
- id="canvas.E002",
+ id=CANVAS_ARTIFACT_ORIGIN_INVALID,
)
)
invalid_key_positions = [str(index + 1) for index, key in enumerate(keys) if len(key) < 32]
@@ -50,7 +63,7 @@ def check_artifact_delivery_settings(app_configs: Any, **kwargs: Any) -> list[Er
Error(
"Every Canvas artifact signing key must be at least 32 characters; invalid position(s): "
+ ", ".join(invalid_key_positions),
- id="canvas.E003",
+ id=CANVAS_ARTIFACT_SIGNING_KEY_TOO_SHORT,
)
)
return errors
diff --git a/products/canvas/backend/tests/test_artifact_tokens.py b/products/canvas/backend/tests/test_artifact_tokens.py
index 646ca73cabc0..6b03f543ea65 100644
--- a/products/canvas/backend/tests/test_artifact_tokens.py
+++ b/products/canvas/backend/tests/test_artifact_tokens.py
@@ -169,7 +169,7 @@ class TestCanvasArtifactTokens(SimpleTestCase):
CANVAS_ARTIFACT_SIGNING_KEYS=["dedicated-signing-key-at-least-32-bytes-long"],
)
def test_production_check_rejects_a_signing_key_without_an_origin(self) -> None:
- self.assertIn("canvas.E001", [error.id for error in check_artifact_delivery_settings(None)])
+ self.assertIn("posthog.canvas.E001", [error.id for error in check_artifact_delivery_settings(None)])
@override_settings(
DEBUG=False,