trueppm-api 0.4.0b2__py3-none-any.whl

trueppm_api/settings/dev.py

@@ -0,0 +1,273 @@
+"""Development settings — DEBUG on, relaxed auth, local service URLs.
+
+This module is fenced by ``_assert_dev_environment_safe`` because it sets
+``AllowAny`` and ``ALLOWED_HOSTS=['*']`` — loading it in staging or production
+would silently disable authentication on every endpoint. The guard fails loudly
+at import time unless the process is a test runner or the operator has
+explicitly opted in via ``TRUEPPM_ALLOW_DEV_SETTINGS=1``.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+import environ
+
+
+def _assert_dev_environment_safe(
+    env: Mapping[str, str] | None = None,
+    modules: Mapping[str, Any] | None = None,
+) -> None:
+    """Refuse to load dev settings outside a test runner or developer workstation.
+
+    Four signals permit the load, in order of precedence:
+      1. ``PYTEST_CURRENT_TEST`` is set in the environment (pytest is active)
+      2. ``pytest`` is already imported in the running process (test collection)
+      3. ``mypy`` is already imported (django-stubs imports settings under mypy)
+      4. ``TRUEPPM_ALLOW_DEV_SETTINGS=1`` is set (explicit developer opt-in)
+
+    Any other environment — staging, production, an unconfigured Docker image —
+    raises ``RuntimeError`` to prevent the module from completing its import and
+    overriding ``DEFAULT_PERMISSION_CLASSES`` with ``AllowAny``.
+
+    Args are injectable so the assertion can be unit-tested without mutating the
+    real environment or the global module table.
+    """
+    env = env if env is not None else os.environ
+    modules = modules if modules is not None else sys.modules
+
+    if env.get("PYTEST_CURRENT_TEST"):
+        return
+    if "pytest" in modules or "mypy" in modules:
+        return
+    if env.get("TRUEPPM_ALLOW_DEV_SETTINGS") == "1":
+        return
+
+    raise RuntimeError(
+        "trueppm_api.settings.dev was loaded outside local dev or a test runner. "
+        "This module sets AllowAny and ALLOWED_HOSTS=['*'] — refusing to import. "
+        "Set TRUEPPM_ALLOW_DEV_SETTINGS=1 to override on a developer workstation."
+    )
+
+
+_assert_dev_environment_safe()
+
+
+from .base import *  # noqa: F403, E402
+from .base import BASE_DIR, DATABASES, REST_FRAMEWORK  # noqa: E402
+
+env = environ.Env()
+
+# Read .env file if present (optional in dev)
+environ.Env.read_env(env_file=".env", overwrite=False)
+
+DEBUG = True
+
+ALLOWED_HOSTS = ["*"]
+
+# Deterministic Fernet key for dev / pytest only — never use this value in
+# staging or production. The dev settings module is fenced by
+# _assert_dev_environment_safe above; production reads its key from a
+# Kubernetes Secret via the Helm chart and never falls through to this default.
+INTEGRATION_ENCRYPTION_KEY = "cNHot7PnbAHGIuY4zUht8FwB5wYGv06O7ppzGyhzR84="
+
+# In dev, allow unauthenticated access to the API for ease of local testing.
+# Throttle classes/rates are inherited from base settings via the spread below;
+# this dev-only module merely relaxes the permission classes. Fenced by
+# _assert_dev_environment_safe — never loaded in staging or production.
+REST_FRAMEWORK = {  # nosemgrep: missing-throttle-config
+    **REST_FRAMEWORK,  # nosemgrep: missing-throttle-config
+    "DEFAULT_PERMISSION_CLASSES": ["rest_framework.permissions.AllowAny"],
+    # Re-add SessionAuthentication on top of base's posture (#2248) so the test
+    # suite's `client.force_login()` populates request.user without minting a JWT.
+    # Never loaded in staging/prod (fenced by _assert_dev_environment_safe). Keeps
+    # base's OwnerScopedApiTokenAuthentication entry (#2547) so PAT-authenticated
+    # requests in the test suite exercise the real production auth wiring.
+    "DEFAULT_AUTHENTICATION_CLASSES": [
+        "trueppm_api.apps.projects.authentication.OwnerScopedApiTokenAuthentication",
+        "rest_framework_simplejwt.authentication.JWTAuthentication",
+        "rest_framework.authentication.SessionAuthentication",
+    ],
+}
+
+# The refresh cookie must work over plain HTTP on localhost — a Secure cookie is
+# dropped by the browser on http://. Production keeps the base default (True).
+AUTH_REFRESH_COOKIE_SECURE = False
+
+# Django admin is ON in dev and OFF everywhere else (#3557). base.py defaults it
+# to False so that a production deploy that sets nothing does not expose a second
+# password door; a developer workstation is the one place where reaching /admin/
+# with no ceremony is the point. Still env-overridable, so `pytest` can assert the
+# disabled behavior through the same variable an operator would set. This module
+# is fenced by _assert_dev_environment_safe above, so the relaxation cannot load
+# in staging or production.
+DJANGO_ADMIN_ENABLED = env.bool("TRUEPPM_DJANGO_ADMIN_ENABLED", default=True)
+
+# base.py defaults MEDIA_ROOT to /var/lib/trueppm/media — the path the chart and
+# compose mount a writable volume at (#3184). Nothing creates that path on a
+# developer workstation, and pytest runs under this module, so keep uploads
+# inside the checkout. BASE_DIR is packages/api/src, so `.parent` lands on
+# packages/api/media/, which .gitignore has already carried since #817.
+MEDIA_ROOT = Path(env("TRUEPPM_MEDIA_ROOT", default=str(BASE_DIR.parent / "media")))
+
+# WhiteNoise (base.py MIDDLEWARE) serves static from STATIC_ROOT, which requires a
+# `collectstatic` run. In dev and under pytest we want /static/ to work without
+# that step, so serve straight from the staticfiles *finders* (each app's static/
+# dir, including drf-spectacular-sidecar's bundles) and re-scan on every request so
+# newly added files appear without a restart. Production keeps the base behavior:
+# collectstatic into STATIC_ROOT, which WhiteNoise serves with far-future caching.
+WHITENOISE_USE_FINDERS = True
+WHITENOISE_AUTOREFRESH = True
+
+# Local dev / pytest run in a single process, so per-process memory is a
+# sufficient (and dependency-free) cache for the OIDC login state and the DRF
+# throttles. Production uses the Redis-backed cache from base.py. Overriding here
+# keeps `pytest` from requiring a separate Valkey cache db (the testcontainers
+# fixture provisions PostgreSQL only).
+CACHES = {
+    "default": {"BACKEND": "django.core.cache.backends.locmem.LocMemCache"},
+}
+
+
+# Detailed SQL logging in dev.
+#
+# This override replaces base.py's build_logging_config() output entirely, so the
+# UTC-timestamp fix in that function (#1952) does not reach dev. That is fine and
+# intentional: these handlers declare no "formatter", so they use logging's
+# default (message-only) formatter, which emits no %(asctime)s at all — there is
+# no log timestamp here to render in the wrong timezone. If a formatter with
+# %(asctime)s is ever added to this dev config, mirror the base fix
+# (logging.Formatter.converter = time.gmtime) so dev timestamps stay UTC too.
+LOGGING = {
+    "version": 1,
+    "disable_existing_loggers": False,
+    "handlers": {
+        "console": {"class": "logging.StreamHandler"},
+    },
+    "root": {
+        "handlers": ["console"],
+        "level": "WARNING",
+    },
+    "loggers": {
+        "django.db.backends": {
+            "handlers": ["console"],
+            "level": env("SQL_LOG_LEVEL", default="WARNING"),
+            "propagate": False,
+        },
+    },
+}
+
+# ---------------------------------------------------------------------------
+# CI test-DB prewarm (#688)
+# ---------------------------------------------------------------------------
+# When the api:test CI shards have loaded a `migrated` template database from
+# the schema dump produced by api:testdb-dump, clone each pytest-xdist worker
+# DB from it (CREATE DATABASE ... TEMPLATE, a fast file copy) and skip the
+# per-worker migration replay. The template already carries the ltree
+# extension, the wbs_path GiST index, and the data backfills, so this is
+# equivalent to a full migrate — unlike --no-migrations, which skips the
+# RunSQL that creates the ltree extension and breaks test-DB creation.
+#
+# Gated on the CI-set env var: a local `pytest` run (no `migrated` template
+# present) leaves DATABASES untouched and builds its test DB by replaying
+# migrations exactly as before. This is test-only — the TEST sub-dict is read
+# solely by Django's test-database creation, never by a running server.
+_test_db_template = os.environ.get("TRUEPPM_TEST_DB_TEMPLATE")
+if _test_db_template:
+    DATABASES["default"].setdefault("TEST", {})
+    DATABASES["default"]["TEST"]["TEMPLATE"] = _test_db_template
+    DATABASES["default"]["TEST"]["MIGRATE"] = False
+
+# ---------------------------------------------------------------------------
+# Per-worktree test DB (scripts/wt)
+# ---------------------------------------------------------------------------
+# `scripts/wt new` writes TRUEPPM_TEST_DB=test_trueppm_wt_<slug> into each
+# worktree's .envrc so N parallel worktrees each create and drop their OWN test
+# database instead of racing on one shared `test_trueppm`. This removes the need
+# for the out-of-band flock mutex that serialized parallel pytest runs (and that
+# flock(1) can't provide on macOS). Test-only: like TEST["TEMPLATE"] above, the
+# TEST["NAME"] key is read solely by Django's test-database creation, never by a
+# running server.
+
+
+def _apply_test_db_name(databases: dict[str, Any], env: Mapping[str, str]) -> None:
+    """Point Django's test-DB creation at a per-worktree database, if requested.
+
+    Reads ``TRUEPPM_TEST_DB`` from ``env`` and, when set, writes it to
+    ``databases["default"]["TEST"]["NAME"]`` so a worktree's ``pytest`` run builds
+    an isolated test database instead of racing on the shared one. A no-op when the
+    variable is unset or empty. ``databases``/``env`` are injectable so the logic
+    is unit-testable without reloading the settings module or mutating the process
+    environment (mirrors ``_assert_dev_environment_safe``).
+    """
+    name = env.get("TRUEPPM_TEST_DB")
+    if not name:
+        return
+    databases["default"].setdefault("TEST", {})
+    databases["default"]["TEST"]["NAME"] = name
+
+
+_apply_test_db_name(DATABASES, os.environ)
+
+
+# ---------------------------------------------------------------------------
+# Fast password hashing under pytest (#3391)
+# ---------------------------------------------------------------------------
+# Django 5.2 defaults to PBKDF2-SHA256 at 1,000,000 iterations. That cost is the
+# whole point in production and pure waste in the test suite, which makes 1,054
+# `create_user(..., password=...)` calls and asserts nothing about hash strength.
+# Measured: 76.3ms per PBKDF2 hash vs 0.026ms for MD5 — 2,899x, several minutes
+# of every api:test run spent proving nothing.
+#
+# Gated on pytest actually being loaded rather than applied to all of dev: a
+# local `runserver` keeps the production hasher, so a developer never logs in
+# against a weaker algorithm than the one they ship. `"pytest" in sys.modules`
+# is ONE of the four signals `_assert_dev_environment_safe` trusts above, not
+# the same test — that guard also accepts PYTEST_CURRENT_TEST from the env,
+# which this deliberately does not, because it is set per test rather than at
+# settings-import time. The gap is worth naming: a subprocess spawned from a
+# test inherits PYTEST_CURRENT_TEST but not the parent's module table, so it
+# would load PBKDF2 while its parent used MD5, and a cross-process
+# check_password against an md5 hash would raise "Unknown password hashing
+# algorithm". Latent, not live — the suite's only subprocess use is a mocked
+# Popen — but a future test that really shells out has to know this.
+#
+# Where settings.dev actually loads, so the next reader does not have to guess:
+# the local compose stack (docker-compose.yml, three services, which set
+# TRUEPPM_ALLOW_DEV_SETTINGS=1), every api:* CI job, the Makefile, and
+# scripts/export-openapi.sh — plus pytest. It is routine infrastructure, not a
+# rare manual opt-in. The branch is unreachable in all of those but pytest for
+# one reason: packages/api/Dockerfile installs `api[c]`/`api[binary]` and never
+# `api[dev]`, and uninstalls pip, so the runtime image has no pytest to import.
+# Every deployed path (helm values, docker-compose.prod, docker-compose.demo)
+# loads settings.prod and never reaches this file at all.
+#
+# The list is deliberately a SINGLE entry. Adding PBKDF2 back as a fallback
+# looks safer and is not: `hasher_changed` would then be True on every login, so
+# check_password's setter fires and ModelBackend REWRITES stored PBKDF2 hashes
+# as MD5. One entry fails those rows closed instead of silently downgrading them.
+#
+# DX note: with --reuse-db, a test database created before this change still
+# holds PBKDF2 hashes, which no longer verify (Django catches the unknown-hasher
+# ValueError and returns False rather than raising). That reads as an auth
+# regression; it is a stale test DB. Use --create-db once.
+#
+# Asserted by tests/test_password_hashers.py, including the invariant this
+# gate rests on: nothing under src/ may import pytest.
+
+
+def _use_fast_password_hashers(modules: Mapping[str, Any]) -> bool:
+    """Report whether the test-only fast password hasher should be installed.
+
+    Injectable so the predicate is unit-testable without mutating the global
+    module table (mirrors ``_assert_dev_environment_safe``).
+    """
+    return "pytest" in modules
+
+
+if _use_fast_password_hashers(sys.modules):
+    PASSWORD_HASHERS = ["django.contrib.auth.hashers.MD5PasswordHasher"]

trueppm_api/settings/prod.py

@@ -0,0 +1,228 @@
+"""Production settings — security hardened, secrets from environment."""
+
+from __future__ import annotations
+
+import logging
+import urllib.parse
+
+import environ
+
+from trueppm_api.apps.observability.logging import build_logging_config
+from trueppm_api.core.security_checks import (
+    validate_allowed_hosts,
+    validate_attachment_storage,
+    validate_integration_encryption_key,
+    validate_project_soft_delete_retention,
+    validate_secret_key,
+    validate_service_credentials,
+    validate_signing_key,
+)
+
+from .base import *  # noqa: F403
+from .base import (
+    ALLOW_LOCAL_ATTACHMENT_STORAGE,
+    ALLOW_UNENCRYPTED_DB,
+    ALLOW_WILDCARD_ALLOWED_HOSTS,
+    DATABASES,
+    DJANGO_LOG_LEVEL,
+    INTEGRATION_ENCRYPTION_KEY,
+    MEDIA_ROOT,
+    REDIS_URL,
+    SIMPLE_JWT,
+    STORAGES,
+    TRUEPPM_PROJECT_SOFT_DELETE_RETENTION_DAYS,
+)
+
+env = environ.Env()
+
+DEBUG = False
+
+# Prefix for every import-time boot-guard failure below.
+_REFUSING_TO_START = "Refusing to start: "
+
+# Force single-line JSON logs in production so a collector (Loki/ELK/CloudWatch)
+# can index each record's fields — including the OTel trace_id/span_id/request_id
+# the filter injects (ADR-0223, #1899) — for log-to-trace correlation. The base
+# config defaults to human-readable console output for dev; here we always emit
+# JSON regardless of TRUEPPM_LOG_JSON, while still honouring DJANGO_LOG_LEVEL.
+LOGGING = build_logging_config(level=DJANGO_LOG_LEVEL, json_output=True)
+
+ALLOWED_HOSTS = env.list("ALLOWED_HOSTS")
+
+# Refuse to boot on a bare-wildcard ALLOWED_HOSTS (#3515). Host validation is the
+# only bound on the host the API reports, and therefore on every absolute URL it
+# builds; "*" removes it. Same import-time enforcement as the guards below, since
+# gunicorn/asgi workers never run `manage.py check`. Operators whose host set is
+# genuinely unknowable opt in via TRUEPPM_ALLOW_WILDCARD_HOSTS=true and keep the
+# warning instead — the TRUEPPM_ALLOW_UNENCRYPTED_DB shape, chosen so an existing
+# install running "*" has a one-variable remedy rather than a crash-loop.
+_wildcard_host_errors = validate_allowed_hosts(
+    ALLOWED_HOSTS, debug=DEBUG, allow_wildcard=ALLOW_WILDCARD_ALLOWED_HOSTS
+)
+if _wildcard_host_errors:
+    raise RuntimeError(_REFUSING_TO_START + "; ".join(str(e.msg) for e in _wildcard_host_errors))
+if ALLOW_WILDCARD_ALLOWED_HOSTS and "*" in ALLOWED_HOSTS:
+    logging.getLogger("trueppm.settings").warning(
+        "ALLOWED_HOSTS contains the wildcard '*', so Django performs no host "
+        "validation. Absolute URLs the API builds (the OIDC redirect_uri and the "
+        "inbound Git-webhook URL) will follow whatever host the caller sends. "
+        "Proceeding because TRUEPPM_ALLOW_WILDCARD_HOSTS=true is set."
+    )
+
+SECRET_KEY = env("SECRET_KEY")  # required; no default in prod
+
+# Refuse to boot with a weak SECRET_KEY (#566, PYSEC-2025-183).
+# Django's system-check registry only fires under `manage.py check`; gunicorn
+# and asgi workers do not run checks at startup, so the failure must be
+# raised at settings import time to actually stop a broken deploy.
+_secret_key_errors = validate_secret_key(SECRET_KEY, debug=DEBUG)
+if _secret_key_errors:
+    raise RuntimeError(_REFUSING_TO_START + "; ".join(str(e.msg) for e in _secret_key_errors))
+
+# Dedicated JWT signing key (#2247). base.py already derived JWT_SIGNING_KEY from
+# the SECRET_KEY env var; re-derive it here against the prod-required SECRET_KEY so
+# the binding is explicit and cannot drift, and mirror the value into SIMPLE_JWT.
+# Then refuse to boot on a weak *explicit* key — an unset key inherits the
+# already-validated SECRET_KEY, so validate_signing_key returns clean for it.
+JWT_SIGNING_KEY = env("JWT_SIGNING_KEY", default=SECRET_KEY)
+SIMPLE_JWT["SIGNING_KEY"] = JWT_SIGNING_KEY
+_signing_key_errors = validate_signing_key(JWT_SIGNING_KEY, SECRET_KEY, debug=DEBUG)
+if _signing_key_errors:
+    raise RuntimeError(_REFUSING_TO_START + "; ".join(str(e.msg) for e in _signing_key_errors))
+
+# Persistent connections for production load.
+DATABASES["default"]["CONN_MAX_AGE"] = 600
+
+# Security headers.
+SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
+
+# The host is NOT taken from the proxy, and that asymmetry with the line above is
+# deliberate (#3515). Django defaults both of these to False; stating them keeps
+# the file from inheriting a position it never took.
+#
+# Why the scheme is trusted and the host is not:
+#
+#   * X-Forwarded-Proto carries information the app cannot obtain any other way —
+#     the container always speaks plain HTTP on :8000, so without the header
+#     every request looks insecure. Its failure mode here is contained: the
+#     Secure flags on the session, CSRF and refresh cookies are hardcoded True
+#     above and in base.py rather than derived from is_secure(), so a spoofed
+#     value does not downgrade a cookie.
+#
+#   * X-Forwarded-Host carries nothing new. Every proxy this project ships
+#     preserves the original Host (`proxy_set_header Host $host` in
+#     nginx/app.conf.template, app-http.conf.template, demo.conf.template,
+#     packages/web/nginx.conf and the chart's web ConfigMap), and none of them
+#     sets or strips X-Forwarded-Host. Turning this on would therefore trust a
+#     header whose only author in every supported topology is the client: Host is
+#     the edge's routing key, so a value that does not route never arrives, while
+#     X-Forwarded-Host routes fine and would be believed anyway. That is a strict
+#     widening of who can steer request.build_absolute_uri(), and it buys nothing.
+#
+# The premise True would need — "the proxy is the sole ingress path" — is also not
+# something the chart enforces: templates/networkpolicy.yaml restricts the bundled
+# datastore pods only, and the admin docs hand API-pod ingress restriction to the
+# operator. Do not flip this without also closing that gap and stripping the
+# header at every edge.
+#
+# An operator whose proxy genuinely rewrites Host does not need this switch:
+# TRUEPPM_PUBLIC_API_BASE_URL pins the origin for both request-derived absolute
+# URLs (the OIDC redirect_uri and the inbound Git-webhook URL), which is a value
+# they control rather than a belief about a header they cannot verify.
+USE_X_FORWARDED_HOST = False
+USE_X_FORWARDED_PORT = False
+SECURE_HSTS_SECONDS = 31536000
+SECURE_HSTS_INCLUDE_SUBDOMAINS = True
+SESSION_COOKIE_SECURE = True
+CSRF_COOKIE_SECURE = True
+SECURE_CONTENT_TYPE_NOSNIFF = True
+SECURE_REFERRER_POLICY = "same-origin"
+# HTTP→HTTPS redirect is opt-in: many deploys terminate TLS at the ingress and
+# speak plain HTTP to the app (incl. the k8s liveness/readiness probes that hit
+# /health/ and /edition/), where an unconditional redirect would break them.
+# Operators that expose the app directly over TLS opt in via env; the probe
+# paths stay exempt so they keep working over plain HTTP either way.
+SECURE_SSL_REDIRECT = env.bool("TRUEPPM_SECURE_SSL_REDIRECT", default=False)
+SECURE_REDIRECT_EXEMPT = [r"^api/v1/health/$", r"^api/v1/readyz$", r"^api/v1/edition/$"]
+
+# Refuse to boot when task attachments would land on ephemeral local disk in a
+# containerized deploy (#775) — same import-time enforcement as the SECRET_KEY
+# guard, since gunicorn/asgi workers never run `manage.py check`. Passing
+# MEDIA_ROOT extends the guard to the opted-in case (#3184): before this the
+# opt-in was an unverified claim, and the deployment it described — no MEDIA_ROOT
+# at all, on a read-only root filesystem — booted clean and then EROFS'd on the
+# first upload.
+_storage_errors = validate_attachment_storage(
+    STORAGES["default"]["BACKEND"],
+    debug=DEBUG,
+    allow_local=ALLOW_LOCAL_ATTACHMENT_STORAGE,
+    media_root=MEDIA_ROOT,
+)
+if _storage_errors:
+    raise RuntimeError(_REFUSING_TO_START + "; ".join(str(e.msg) for e in _storage_errors))
+
+# Refuse to boot without a valid integration encryption key (#1002). The key
+# encrypts integration PATs at rest; without this guard a missing/malformed key
+# only surfaces as a 500 on the first PAT connect, long after deploy. Same
+# import-time enforcement as the SECRET_KEY and storage guards above.
+_integration_key_errors = validate_integration_encryption_key(
+    INTEGRATION_ENCRYPTION_KEY, debug=DEBUG
+)
+if _integration_key_errors:
+    raise RuntimeError(_REFUSING_TO_START + "; ".join(str(e.msg) for e in _integration_key_errors))
+
+# Refuse to boot when the soft-delete retention window is 0 (#3186). 0 sets the
+# purge cutoff to the present moment, so the next tick HARD-deletes every
+# trashed project and all of its children via CASCADE — irreversibly, with no
+# tombstone. The API has always refused this value
+# (RetentionPolicyWriteSerializer.value is min_value=1); the env var had no
+# floor, and the chart's own comment told operators to set exactly this "to keep
+# the default". Same import-time posture as the guards above, since asgi workers
+# never run `manage.py check`.
+_retention_errors = validate_project_soft_delete_retention(
+    TRUEPPM_PROJECT_SOFT_DELETE_RETENTION_DAYS
+)
+if _retention_errors:
+    raise RuntimeError(_REFUSING_TO_START + "; ".join(str(e.msg) for e in _retention_errors))
+
+# Refuse to boot when DATABASE_URL has no sslmode parameter in a non-DEBUG
+# deployment (#1550). Without sslmode=require the connection falls back to
+# whatever the server negotiates, which may be plaintext — the same fail-closed
+# posture as the SECRET_KEY (#566), attachment-storage (#775), and integration-
+# key (#1002) guards above, since gunicorn/asgi workers never run
+# `manage.py check`. Operators terminating TLS at the proxy/sidecar layer (where
+# the app-to-DB link is already encrypted) opt in via
+# TRUEPPM_ALLOW_UNENCRYPTED_DB=true and keep the warning instead.
+_db_url_raw: str = env("DATABASE_URL", default="")
+if _db_url_raw:
+    _db_url_qs = urllib.parse.parse_qs(urllib.parse.urlparse(_db_url_raw).query)
+    if "sslmode" not in _db_url_qs:
+        if ALLOW_UNENCRYPTED_DB:
+            logging.getLogger("trueppm.settings").warning(
+                "DATABASE_URL does not include sslmode=require. "
+                "Database connections may use unencrypted transport. "
+                "Proceeding because TRUEPPM_ALLOW_UNENCRYPTED_DB=true is set; "
+                "ensure TLS is enforced at the network layer."
+            )
+        else:
+            raise RuntimeError(
+                "Refusing to start: DATABASE_URL does not include sslmode=require "
+                "in a non-DEBUG environment; database connections may use "
+                "unencrypted transport. Set sslmode=require in DATABASE_URL, or set "
+                "TRUEPPM_ALLOW_UNENCRYPTED_DB=true if TLS is enforced at the network "
+                "layer."
+            )
+
+# Refuse to boot on a placeholder datastore credential (#3176). Compose's
+# ``${DB_PASSWORD:?...}`` only asserts the variable is non-empty, and .env.example
+# shipped ``change-me`` — so the documented copy-paste path produced a deploy in which
+# SECRET_KEY, the attachment backend, the integration key and sslmode were all validated
+# and the database/cache passwords were not. Same import-time enforcement as the guards
+# above, for the same reason: gunicorn/asgi workers never run ``manage.py check``.
+_service_cred_errors = validate_service_credentials(
+    DATABASES["default"].get("PASSWORD"),
+    urllib.parse.urlparse(REDIS_URL or "").password,
+    debug=DEBUG,
+)
+if _service_cred_errors:
+    raise RuntimeError(_REFUSING_TO_START + "; ".join(str(e.msg) for e in _service_cred_errors))

trueppm_api/urls.py

@@ -0,0 +1,153 @@
+"""Root URL configuration."""
+
+from __future__ import annotations
+
+from django.conf import settings
+from django.contrib import admin
+from django.urls import include, path
+from drf_spectacular.utils import extend_schema, inline_serializer
+from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerSplitView
+from rest_framework import serializers
+from rest_framework.decorators import api_view, permission_classes
+from rest_framework.permissions import AllowAny
+from rest_framework.request import Request
+from rest_framework.response import Response
+
+from trueppm_api.apps.observability.views import readyz
+from trueppm_api.core.auth_views import (
+    CookieTokenLogoutView,
+    CookieTokenObtainPairView,
+    CookieTokenRefreshView,
+)
+from trueppm_api.core.password_reset import (
+    PasswordResetConfirmView,
+    PasswordResetRequestView,
+)
+
+
+@extend_schema(
+    summary="Liveness probe",
+    description=(
+        'Returns HTTP 200 with `{"status": "ok"}` when the API process is running. '
+        "No authentication required. Use for Kubernetes liveness/readiness probes."
+    ),
+    responses={200: inline_serializer("HealthResponse", {"status": serializers.CharField()})},
+    auth=[],
+    tags=["meta"],
+)
+@api_view(["GET"])
+@permission_classes([AllowAny])
+def health(_request: Request) -> Response:
+    return Response({"status": "ok"})
+
+
+@extend_schema(
+    summary="Running edition",
+    description=(
+        'Returns `{"edition": "community" | "enterprise"}` from the TRUEPPM_EDITION '
+        "Django setting. No authentication required. The React shell calls this once "
+        "at startup to decide the post-login redirect target (ADR-0029, ADR-0030)."
+    ),
+    responses={
+        200: inline_serializer(
+            "EditionResponse",
+            {
+                "edition": serializers.CharField(),
+                "version": serializers.CharField(),
+                "build_sha": serializers.CharField(allow_blank=True),
+            },
+        )
+    },
+    auth=[],
+    tags=["meta"],
+)
+@api_view(["GET"])
+@permission_classes([AllowAny])
+def edition(request: Request) -> Response:
+    """Return the running edition — community or enterprise.
+
+    Public endpoint (no auth required). The React shell calls this once at
+    startup to decide the post-login redirect target (ADR-0029, ADR-0030).
+    The value is controlled by the TRUEPPM_EDITION Django setting, which the
+    enterprise Helm chart sets to "enterprise".
+    """
+    return Response(
+        {
+            "edition": settings.TRUEPPM_EDITION,
+            # Build identity (#2392): a bug report has to name the exact build it
+            # came from, and this is the one endpoint the shell already calls at
+            # startup without auth. `build_sha` is empty on a source checkout.
+            "version": settings.TRUEPPM_VERSION,
+            "build_sha": settings.TRUEPPM_BUILD_SHA,
+        }
+    )
+
+
+# Versioned prefix every app router mounts under.
+_API_V1_PREFIX = "api/v1/"
+
+urlpatterns = [
+    path("api/v1/health/", health, name="health"),
+    # Dependency-aware readiness probe (#1894). Unauthenticated like /health/ so
+    # kubelet can call it, but returns 503 when the DB or cache is unreachable —
+    # unlike /health/, which is a shallow process-liveness check.
+    path("api/v1/readyz", readyz, name="readyz"),
+    path("api/v1/edition/", edition, name="edition"),
+    path("admin/", admin.site.urls),
+    # OpenAPI schema and interactive docs. The *split* Swagger view (not the
+    # default inline one) is required by our strict CSP: it delivers the UI
+    # bootstrap as a separate same-origin JS request instead of an inline
+    # <script>, which script-src 'self' would otherwise block (the page rendered
+    # blank — #1603). Asset bundles are served from drf-spectacular-sidecar
+    # ('self') via SWAGGER_UI_DIST=SIDECAR in settings.
+    path("api/schema/", SpectacularAPIView.as_view(), name="schema"),
+    path("api/docs/", SpectacularSwaggerSplitView.as_view(url_name="schema"), name="swagger-ui"),
+    path(
+        "api/schema/swagger-ui/",
+        SpectacularSwaggerSplitView.as_view(url_name="schema"),
+        name="swagger-ui-compat",
+    ),
+    # JWT auth endpoints (#897). Login returns the access token in the body and
+    # sets the refresh token in an httpOnly cookie; refresh reads that cookie;
+    # logout clears it (and blacklists the token if the blacklist app is present).
+    path("api/v1/auth/token/", CookieTokenObtainPairView.as_view(), name="token_obtain_pair"),
+    path("api/v1/auth/token/refresh/", CookieTokenRefreshView.as_view(), name="token_refresh"),
+    path("api/v1/auth/logout/", CookieTokenLogoutView.as_view(), name="token_logout"),
+    # Self-service password reset (#765, ADR-0209). Both AllowAny + throttled with a
+    # dedicated "password_reset" scope. Request always returns 200 (no user
+    # enumeration); confirm validates a stateless token, sets the password, and
+    # revokes all of the account's other sessions.
+    path(
+        "api/v1/auth/password/reset/",
+        PasswordResetRequestView.as_view(),
+        name="password_reset",
+    ),
+    path(
+        "api/v1/auth/password/reset/confirm/",
+        PasswordResetConfirmView.as_view(),
+        name="password_reset_confirm",
+    ),
+    # Versioned API
+    path(_API_V1_PREFIX, include("trueppm_api.apps.access.urls")),
+    path(_API_V1_PREFIX, include("trueppm_api.apps.projects.urls")),
+    path(_API_V1_PREFIX, include("trueppm_api.apps.resources.urls")),
+    path(_API_V1_PREFIX, include("trueppm_api.apps.scheduling.urls")),
+    path(_API_V1_PREFIX, include("trueppm_api.apps.sync.urls")),
+    path(_API_V1_PREFIX, include("trueppm_api.apps.history.urls")),
+    path(_API_V1_PREFIX, include("trueppm_api.apps.msproject.urls")),
+    path(_API_V1_PREFIX, include("trueppm_api.apps.jiraimport.urls")),
+    path(_API_V1_PREFIX, include("trueppm_api.apps.csvimport.urls")),
+    path(_API_V1_PREFIX, include("trueppm_api.apps.webhooks.urls")),
+    path(_API_V1_PREFIX, include("trueppm_api.apps.taskruns.urls")),
+    path(_API_V1_PREFIX, include("trueppm_api.apps.notifications.urls")),
+    path(_API_V1_PREFIX, include("trueppm_api.apps.integrations.urls")),
+    path(_API_V1_PREFIX, include("trueppm_api.apps.observability.urls")),
+    path(_API_V1_PREFIX, include("trueppm_api.apps.workspace.urls")),
+    path(_API_V1_PREFIX, include("trueppm_api.apps.teams.urls")),
+    path(_API_V1_PREFIX, include("trueppm_api.apps.timetracking.urls")),
+    # Basic SSO — OIDC relying party (ADR-0187). Flow endpoints under
+    # auth/oidc/*, admin config under workspace/sso/*.
+    path(_API_V1_PREFIX, include("trueppm_api.apps.sso.urls")),
+    # Team-readable agent-action audit log (ADR-0112 RC1, #1805).
+    path(_API_V1_PREFIX, include("trueppm_api.apps.agents.urls")),
+]