trueppm-api 0.4.0b2__py3-none-any.whl

trueppm_api/apps/access/management/commands/create_admin.py

@@ -0,0 +1,164 @@
+"""Management command to bootstrap a TruePPM admin (superuser) account.
+
+Runs automatically on container startup (both Docker Compose and Kubernetes).
+Idempotent: if a superuser already exists the command exits immediately — it
+will NOT reset a production password on re-deploy.
+
+"A superuser already exists" is the *only* thing that stops it. When none does,
+the command resolves ``DJANGO_SUPERUSER_EMAIL`` with ``get_or_create`` and then
+sets ``is_staff``/``is_superuser`` and a fresh password unconditionally — so an
+existing **non-superuser** holding that address is promoted and has its password
+reset. That is intended (it is how an operator recovers an install whose only
+superuser was demoted), but it is a privilege grant, so it is announced on stdout
+rather than reported as an ordinary create (#3175).
+
+Credential delivery
+-------------------
+The password is written to a file (default ``/tmp/trueppm_admin_password``)
+with atomic 0o600 permissions so it never appears in container log aggregators
+(CloudWatch, Datadog, etc.).  Override the path via the
+``TRUEPPM_ADMIN_PASSWORD_FILE`` environment variable.  If the file write fails
+the password falls back to management-command stdout *only* — it is never
+passed to ``logger.*`` which would forward it to log aggregators.
+
+Environment variables
+---------------------
+``DJANGO_SUPERUSER_EMAIL``
+    Admin email address (default: ``admin@example.com``).
+
+    The default is an RFC 2606 reserved domain, chosen so it can never be
+    delivered to. It used to be ``admin@trueppm.com`` — a domain the *vendor*
+    owns and the operator does not, which put every un-overridden install's
+    root account at an address its owner could not receive password-reset mail
+    at, and someone else could (#3175). Always set this explicitly.
+``DJANGO_SUPERUSER_USERNAME``
+    Admin username; defaults to the local part of the email.
+``DJANGO_SUPERUSER_PASSWORD``
+    Explicit password.  When omitted a secure random password is generated
+    via :func:`secrets.token_urlsafe`.
+``TRUEPPM_ADMIN_PASSWORD_FILE``
+    Path where the one-time password is written (default:
+    ``/tmp/trueppm_admin_password``).  Override in production to a
+    non-world-writable location (e.g. an emptyDir volume mount).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import secrets
+
+from django.contrib.auth import get_user_model
+from django.core.management.base import BaseCommand
+
+logger = logging.getLogger(__name__)
+
+# Default intentionally uses /tmp for dev convenience; production deployments
+# must set TRUEPPM_ADMIN_PASSWORD_FILE to a non-world-writable path.
+_PASSWORD_FILE = os.environ.get(  # nosec B108
+    "TRUEPPM_ADMIN_PASSWORD_FILE", "/tmp/trueppm_admin_password"
+)
+
+
+class Command(BaseCommand):
+    """Bootstrap a TruePPM superuser on first run; no-op if one already exists."""
+
+    help = (
+        "Bootstrap a superuser on first run. "
+        "Writes the one-time password to a file rather than stdout "
+        "so it is not visible in container log aggregators."
+    )
+
+    def handle(self, *args: object, **options: object) -> None:
+        """Execute the command.
+
+        Exits immediately when a superuser already exists so that re-deploying
+        a Kubernetes pod or restarting the compose stack does not overwrite a
+        production password.
+        """
+        User = get_user_model()
+
+        if User.objects.filter(is_superuser=True).exists():
+            self.stdout.write("Admin user already exists — skipping bootstrap.")
+            return
+
+        email = os.environ.get("DJANGO_SUPERUSER_EMAIL", "admin@example.com").strip()
+        username = os.environ.get("DJANGO_SUPERUSER_USERNAME", "").strip() or email.split("@")[0]
+        password = os.environ.get("DJANGO_SUPERUSER_PASSWORD", "").strip() or secrets.token_urlsafe(
+            16
+        )
+
+        # get-or-create-ok: bootstrap command, single CLI/env admin email — no duplicate reachable
+        user, created = User.objects.get_or_create(
+            email=email,
+            defaults={"username": username},
+        )
+        # Bootstrap-only: password is an operator-supplied env var or a
+        # cryptographically random token (above), not interactive signup input —
+        # AUTH_PASSWORD_VALIDATORS govern the registration path, not superuser
+        # provisioning.
+        # nosemgrep: unvalidated-password
+        user.set_password(password)
+        user.username = username
+        user.is_staff = True
+        user.is_superuser = True
+        user.save()
+
+        # An existing row being promoted is a privilege grant on an account the
+        # operator did not necessarily know was there — say so plainly rather than
+        # letting it read like a routine bootstrap line.
+        if created:
+            action = "Created"
+        else:
+            action = "Promoted existing user to"
+            self.stdout.write(
+                self.style.WARNING(
+                    f"WARNING: {email} already existed as a non-superuser. It has been "
+                    "granted superuser + staff and its password has been RESET. If this "
+                    "was not intended, set DJANGO_SUPERUSER_EMAIL to an unused address."
+                )
+            )
+
+        # Write to file rather than stdout — credentials in stdout end up in
+        # every log aggregator that ships container output.
+        pw_to_stdout = False
+        try:
+            flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC
+            # O_NOFOLLOW prevents a symlink attack on the world-writable /tmp
+            # directory (Linux and macOS only; ignored on platforms that lack it).
+            if hasattr(os, "O_NOFOLLOW"):
+                flags |= os.O_NOFOLLOW
+            # Mode 0o600 is applied atomically at file creation — avoids the
+            # TOCTOU window that a two-step open()+chmod() would leave.
+            fd = os.open(_PASSWORD_FILE, flags, 0o600)
+            with os.fdopen(fd, "w") as fh:
+                fh.write(password + "\n")
+            password_info = f"[REDACTED — written to {_PASSWORD_FILE}]"
+        except OSError as exc:
+            # File write failed.  Fall back to management-command stdout only;
+            # do NOT use logger.* (log aggregators capture WARNING+ lines).
+            # No secret logged: the only arg is the OSError; the password is
+            # surfaced solely on command stdout below, never via the logger.
+            # nosemgrep: python-logger-credential-disclosure
+            logger.warning(
+                "create_admin: could not write password file (%s). "
+                "Credential printed to command stdout only.",
+                exc,
+            )
+            pw_to_stdout = True
+            password_info = password
+
+        self.stdout.write("")
+        self.stdout.write(self.style.WARNING("=" * 60))
+        self.stdout.write(self.style.WARNING("  TRUEPPM INITIAL ADMIN CREDENTIALS"))
+        self.stdout.write(self.style.WARNING("=" * 60))
+        self.stdout.write(f"  {action} admin: {email} (username={username})")
+        self.stdout.write(f"  Password: {password_info}")
+        if not pw_to_stdout:
+            self.stdout.write(
+                self.style.WARNING(
+                    f"  Retrieve the password from {_PASSWORD_FILE}, then delete the file."
+                )
+            )
+        self.stdout.write(self.style.WARNING("=" * 60))
+        self.stdout.write("")

trueppm_api/apps/access/management/commands/migrate_locked.py

@@ -0,0 +1,96 @@
+"""``migrate`` serialized behind a PostgreSQL advisory lock (#3188).
+
+The chart runs ``migrate`` as a **per-pod init container**, not as a
+``pre-upgrade`` hook Job. At ``replicaCount: 1`` that is harmless; at 2 or more
+every pod runs it concurrently against one database, and Django has no
+concurrency control of its own — each process reads ``django_migrations``,
+decides the same migration is unapplied, and both run it. The outcomes are a
+duplicate-key error on the ``django_migrations`` insert, a lock timeout between
+two concurrent ``ALTER TABLE``s, or a partially-applied DDL sequence, depending
+on timing. All three surface as a crash-looping init container during a rollout,
+which is the worst moment to be debugging schema state.
+
+A session-level advisory lock is the cheap fix and needs no new infrastructure:
+PostgreSQL already arbitrates it, the losers block rather than fail, and by the
+time they acquire the lock the winner has finished so their own ``migrate`` is a
+no-op. Advisory locks are also released automatically if the holder's connection
+dies, so a killed init container cannot wedge the next rollout.
+
+Deliberately a separate command rather than an override of ``migrate``: an
+operator running ``manage.py migrate`` by hand should get Django's command with
+Django's semantics, and a wrapper that silently changed it would be a surprise
+in exactly the situation where surprises are expensive.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from django.core.management import call_command
+from django.core.management.base import BaseCommand, CommandError
+from django.db import connection
+
+#: Arbitrary but FIXED 64-bit key. Every TruePPM process must use the same one or
+#: the lock arbitrates nothing; it is namespaced by the database, so two
+#: TruePPM installs on separate databases never contend. Derived by hand rather
+#: than hashed from a string so it is stable across Python versions —
+#: ``hash()`` is salted per process and would silently give each pod its own lock.
+MIGRATION_ADVISORY_LOCK_KEY = 4_113_188_001
+
+
+class Command(BaseCommand):
+    help = "Run `migrate` while holding a PostgreSQL advisory lock (#3188)."
+
+    def add_arguments(self, parser: Any) -> None:
+        parser.add_argument(
+            "--lock-timeout",
+            type=int,
+            default=600,
+            help=(
+                "Seconds to wait for the lock before giving up. Must exceed the "
+                "longest migration run, since every other pod waits out the "
+                "winner. 0 waits forever."
+            ),
+        )
+
+    def handle(self, *args: Any, **options: Any) -> None:
+        if connection.vendor != "postgresql":
+            # SQLite has no advisory locks, and a non-PostgreSQL backend is
+            # necessarily a single-process dev setup where the race cannot occur.
+            self.stdout.write("Not PostgreSQL — running migrate without a lock.")
+            call_command("migrate", "--noinput")
+            return
+
+        timeout = int(options["lock_timeout"])
+        deadline = time.monotonic() + timeout if timeout else None
+
+        with connection.cursor() as cursor:
+            acquired = False
+            while not acquired:
+                # try_advisory_lock, not advisory_lock: blocking inside the
+                # database would hold the connection with no way to report
+                # progress or honor --lock-timeout. Polling costs one cheap
+                # round trip a second and keeps the timeout ours to enforce.
+                cursor.execute("SELECT pg_try_advisory_lock(%s)", [MIGRATION_ADVISORY_LOCK_KEY])
+                row = cursor.fetchone()
+                acquired = bool(row and row[0])
+                if acquired:
+                    break
+                if deadline is not None and time.monotonic() >= deadline:
+                    raise CommandError(
+                        f"Timed out after {timeout}s waiting for the migration "
+                        "advisory lock. Another pod is still migrating, or a "
+                        "previous run's connection is still open."
+                    )
+                self.stdout.write("Waiting for the migration advisory lock…")
+                time.sleep(1)
+
+            self.stdout.write(self.style.SUCCESS("Acquired the migration advisory lock."))
+            try:
+                call_command("migrate", "--noinput")
+            finally:
+                # Explicit unlock so a long-lived connection (the init container
+                # exits right after, but tests and manual runs do not) does not
+                # hold it until disconnect.
+                cursor.execute("SELECT pg_advisory_unlock(%s)", [MIGRATION_ADVISORY_LOCK_KEY])

trueppm_api/apps/access/management/commands/revoke_api_tokens.py

@@ -0,0 +1,209 @@
+"""``manage.py revoke_api_tokens`` — the operator's API-token breach-recovery lever (#2878).
+
+**Why this exists.** ``administration/security.md`` told operators that rotating the JWT
+signing key after a suspected token leak or an admin off-boarding signs everyone out. It
+does — for sessions and JWTs. An API token is resolved by a SHA-256 hash lookup
+(``apps/projects/authentication.py``), carries no signature, and is completely untouched
+by key rotation: after following the documented procedure to the letter, every leaked
+token on the instance is still live, and nothing in the runbook said so. This command is
+the missing half of that procedure.
+
+**Scope is a required choice, not a default.** Exactly one of:
+
+  * ``--user <username-or-email>`` — every *personal* token owned by one account. The
+    off-boarding / "this person's laptop was stolen" case.
+  * ``--all-personal`` — every personal token on the instance. The "our secret store
+    leaked" case. Leaves project- and program-scoped integration tokens alone, so team
+    CI keeps working.
+  * ``--all`` — every token of every kind, including integration tokens, **plus**
+    every active share link and configured git-automation webhook secret instance-
+    wide (#2939) — the other two durable grants a leaked token or compromised
+    session can mint that no other lever reaches. This *will* break every inbound
+    sync and public share link until an admin re-mints; it is the full-compromise
+    lever.
+
+**Dry-run by default.** The command reports what it would revoke and exits; ``--commit``
+performs the revocation, prompting for confirmation unless ``--yes`` is given. Revocation
+is one-way — nothing in the codebase clears ``revoked_at`` — so a mistyped scope cannot
+be undone, which is exactly why it does not act without being told twice.
+
+Every revoked token gets an ``ApiTokenAuditEntry`` row with
+``detail["reason"] = "operator_bulk_revoke"``, so the incident timeline can distinguish
+an operator's containment sweep from a user's routine rotation. ``actor`` is null: a
+command run from a shell has no Django user, and inventing one would be worse than
+recording the absence.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from django.contrib.auth import get_user_model
+from django.core.management.base import BaseCommand, CommandError
+from django.db import transaction
+from django.db.models import Q
+from django.utils import timezone
+
+REASON = "operator_bulk_revoke"
+
+
+class Command(BaseCommand):
+    help = "Revoke API tokens instance-wide or for one account (breach recovery, #2878)."
+
+    def add_arguments(self, parser: Any) -> None:
+        scope = parser.add_mutually_exclusive_group(required=True)
+        scope.add_argument(
+            "--user",
+            type=str,
+            help="Revoke every personal access token owned by this username or email.",
+        )
+        scope.add_argument(
+            "--all-personal",
+            action="store_true",
+            help="Revoke every personal access token on the instance. Leaves project- "
+            "and program-scoped integration tokens alone.",
+        )
+        scope.add_argument(
+            "--all",
+            action="store_true",
+            help="Revoke EVERY API token, including project- and program-scoped "
+            "integration tokens. Breaks all inbound sync until re-minted.",
+        )
+        parser.add_argument(
+            "--commit",
+            action="store_true",
+            help="Actually revoke. Without this the command only reports.",
+        )
+        parser.add_argument(
+            "--yes",
+            action="store_true",
+            help="Skip the interactive confirmation (for use in a runbook script).",
+        )
+
+    def handle(self, *args: Any, **options: Any) -> None:
+        from trueppm_api.apps.projects.models import (
+            ApiToken,
+            ApiTokenAuditAction,
+            ApiTokenAuditEntry,
+        )
+
+        target_user = None
+        if options["user"]:
+            User = get_user_model()
+            identifier = str(options["user"]).strip()
+            # Accept either handle so a runbook does not have to know which the operator
+            # has to hand during an incident.
+            #
+            # FAIL CLOSED on ambiguity. Django's stock ``auth.User`` puts **no**
+            # uniqueness constraint on ``email`` at all, and ``username`` uniqueness is
+            # case-*sensitive*, so ``__iexact`` can match several rows two ways. A
+            # ``.first()`` here would silently pick the lowest pk — during an incident,
+            # while reporting success — so the leaked token stays live and an uninvolved
+            # account's automations break instead. ``apps/sso/services.py`` and
+            # ``core/password_reset.py`` already treat this lookup as hazardous; this is
+            # the third caller and it must not be the one that guesses.
+            candidates = list(
+                User.objects.filter(
+                    Q(username__iexact=identifier) | Q(email__iexact=identifier)
+                ).order_by("pk")[:3]
+            )
+            if not candidates:
+                raise CommandError(f"No account matches {identifier!r} by username or email.")
+            if len(candidates) > 1:
+                listed = ", ".join(f"pk={u.pk} username={u.username!r}" for u in candidates)
+                raise CommandError(
+                    f"{identifier!r} matches more than one account ({listed}). Re-run with "
+                    "an unambiguous username so the sweep cannot contain the wrong "
+                    "account."
+                )
+            target_user = candidates[0]
+
+        active = ApiToken.objects.filter(is_deleted=False, revoked_at__isnull=True)
+        if target_user is not None:
+            queryset = active.filter(owner=target_user)
+            scope_label = f"personal tokens owned by {target_user.username}"
+        elif options["all_personal"]:
+            queryset = active.filter(owner__isnull=False)
+            scope_label = "all personal access tokens on this instance"
+        else:
+            queryset = active
+            scope_label = "ALL API tokens on this instance (including integration tokens)"
+
+        doomed = list(queryset.only("pk", "token_prefix", "name", "owner", "project", "program"))
+        self.stdout.write(f"Scope: {scope_label}")
+        self.stdout.write(f"Active tokens matched: {len(doomed)}")
+        for token in doomed:
+            kind = "personal" if token.owner_id else ("project" if token.project_id else "program")
+            self.stdout.write(f"  {token.token_prefix}… ({kind}) {token.name}")
+
+        # --all is the full-compromise lever: also sweep the two non-token durable
+        # grants a leaked token (or a compromised session) can mint (#2939). Counted
+        # ahead of --commit so a dry run reports the whole blast radius, not just
+        # the token count.
+        from trueppm_api.apps.integrations.models import BoardAutomation
+        from trueppm_api.apps.projects.models import ShareLink
+
+        links_matched = secrets_matched = 0
+        if options["all"]:
+            links_matched = ShareLink.objects.filter(revoked_at__isnull=True).count()
+            secrets_matched = BoardAutomation.objects.exclude(secret_ciphertext=b"").count()
+            self.stdout.write(f"Active share links matched: {links_matched}")
+            self.stdout.write(f"Configured git-automation secrets matched: {secrets_matched}")
+
+        if not doomed and not links_matched and not secrets_matched:
+            self.stdout.write(self.style.SUCCESS("Nothing to revoke."))
+            return
+
+        if not options["commit"]:
+            self.stdout.write(
+                self.style.WARNING("Dry run — nothing revoked. Re-run with --commit to apply.")
+            )
+            return
+
+        if not options["yes"]:
+            total = len(doomed) + links_matched + secrets_matched
+            answer = input(f"Revoke {total} grant(s)? This cannot be undone. [y/N] ")
+            if answer.strip().lower() not in ("y", "yes"):
+                raise CommandError("Aborted.")
+
+        now = timezone.now()
+        with transaction.atomic():
+            revoked = ApiToken.objects.filter(pk__in=[token.pk for token in doomed]).update(
+                revoked_at=now
+            )
+            # One audit row per token, in the same transaction as the revocation, so the
+            # sweep and its record commit together. The scope XOR on ApiTokenAuditEntry
+            # requires exactly one of owner/project/program, mirroring the token's own.
+            ApiTokenAuditEntry.objects.bulk_create(
+                [
+                    ApiTokenAuditEntry(
+                        owner_id=token.owner_id,
+                        project_id=token.project_id,
+                        program_id=token.program_id,
+                        token=token,
+                        token_prefix=token.token_prefix,
+                        actor=None,
+                        action=ApiTokenAuditAction.REVOKED.value,
+                        detail={"name": token.name, "reason": REASON},
+                    )
+                    for token in doomed
+                ]
+            )
+            links_revoked = secrets_cleared = 0
+            if options["all"]:
+                from trueppm_api.apps.access.services import revoke_personal_durable_grants
+
+                links_revoked, secrets_cleared = revoke_personal_durable_grants(actor=None)
+
+        self.stdout.write(self.style.SUCCESS(f"Revoked {revoked} token(s)."))
+        if options["all"]:
+            self.stdout.write(
+                self.style.SUCCESS(
+                    f"Revoked {links_revoked} share link(s), cleared "
+                    f"{secrets_cleared} git-automation secret(s)."
+                )
+            )
+        self.stdout.write(
+            "Sessions and JWTs are a separate credential class — rotate JWT_SIGNING_KEY "
+            "as well if you have not already (administration/security.md)."
+        )

trueppm_api/apps/access/migrations/0001_initial.py

@@ -0,0 +1,61 @@
+"""Initial migration for the access app — creates ProjectMembership."""
+
+from __future__ import annotations
+
+import uuid
+
+import django.db.models.deletion
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies: list[tuple[str, str]] = [  # type: ignore[misc]
+        ("projects", "0001_initial"),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="ProjectMembership",
+            fields=[
+                ("id", models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True)),
+                ("server_version", models.BigIntegerField(default=0, editable=False)),
+                (
+                    "project",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.PROTECT,
+                        related_name="memberships",
+                        to="projects.project",
+                    ),
+                ),
+                (
+                    "user",
+                    models.ForeignKey(
+                        on_delete=django.db.models.deletion.CASCADE,
+                        related_name="memberships",
+                        to=settings.AUTH_USER_MODEL,
+                    ),
+                ),
+                (
+                    "role",
+                    models.IntegerField(
+                        choices=[
+                            (0, "Viewer"),
+                            (1, "Member"),
+                            (2, "Scheduler"),
+                            (3, "Admin"),
+                            (4, "Owner"),
+                        ]
+                    ),
+                ),
+            ],
+            options={"db_table": "access_project_membership"},
+        ),
+        migrations.AlterUniqueTogether(
+            name="projectmembership",
+            unique_together={("project", "user")},
+        ),
+    ]