trueppm-api 0.4.0__py3-none-any.whl

trueppm_api/apps/projects/key_views.py

@@ -0,0 +1,468 @@
+"""Key resolution and key availability endpoints (ADR-1237 §5, §6).
+
+``GET /api/v1/resolve/`` turns whatever a person pasted — a project or program
+key, a retired key, a UUID, or a ``PLAT-T-10`` reference — into the UUIDs every
+other endpoint takes. ``GET /api/v1/keys/`` backs the create form's live key
+suggestion and availability check.
+
+The security property of the resolver is that it cannot tell a caller anything
+about an object they cannot read. That is structural, not a check: every lookup
+runs against ONE queryset that is already restricted to what the caller can
+read, intersected with the token's scope, so there is no "found it, now check
+permission" branch whose timing or body could differ. Missing, hidden,
+out-of-token-scope and retired-key-of-a-hidden-project all fall out of the same
+empty queryset and return the same bytes. A future "fast path" that looks an
+``ObjectKey`` up first and checks access second reintroduces the distinction;
+``test_resolve_404_is_indistinguishable`` is the tripwire.
+"""
+
+from __future__ import annotations
+
+import re
+import uuid
+from typing import Any
+
+from django.db.models import Exists, OuterRef, Q, QuerySet
+from drf_spectacular.utils import (
+    OpenApiParameter,
+    OpenApiResponse,
+    extend_schema,
+    inline_serializer,
+)
+from rest_framework import serializers, status
+from rest_framework.authentication import BaseAuthentication
+from rest_framework.permissions import IsAuthenticated
+from rest_framework.request import Request
+from rest_framework.response import Response
+from rest_framework.throttling import ScopedRateThrottle
+from rest_framework.views import APIView
+
+from trueppm_api.apps.access.models import ProgramMembership, ProjectMembership
+from trueppm_api.apps.projects.keys import (
+    KIND_PROGRAM,
+    KIND_PROJECT,
+    KINDS,
+    base_key_for,
+    is_reserved,
+    key_format_error,
+    normalize_key,
+)
+from trueppm_api.apps.projects.models import (
+    ApiToken,
+    ObjectKey,
+    Program,
+    Project,
+    Risk,
+    Sprint,
+    Task,
+)
+
+#: ``<KEY>-<T|SP|R>-<n>``. The greedy ``.+`` makes the match take the RIGHTMOST
+#: marker, so a grandfathered hyphenated key parses: ``GA-SEC-T-10`` is key
+#: ``GA-SEC``, task 10 (ADR-1237 §2).
+_REF_RE = re.compile(r"(?P<key>.+)-(?P<marker>T|SP|R)-(?P<n>[0-9]{1,9})", re.IGNORECASE)
+
+#: The one 404 body. Built here, once, and returned verbatim from every
+#: not-found branch so the four cases cannot drift apart byte-wise.
+_NOT_FOUND_BODY = {"detail": "Not found."}
+
+_MAX_REF_LENGTH = 128
+
+RESOLVE_RESPONSE = inline_serializer(
+    "ResolveResponse",
+    {
+        "type": serializers.ChoiceField(choices=["project", "program", "task", "sprint", "risk"]),
+        "id": serializers.UUIDField(),
+        "project_id": serializers.UUIDField(allow_null=True),
+        "program_id": serializers.UUIDField(allow_null=True),
+        "key": serializers.CharField(
+            allow_null=True,
+            help_text=(
+                "The CURRENT key of the project (or program) the ref belongs to — a "
+                "retired key resolves, and this is what it was renamed to. Null for a "
+                "project that has no key yet (addressable by UUID only)."
+            ),
+        ),
+        "canonical_ref": serializers.CharField(
+            help_text=(
+                "The current reference form: `PLAT`, `atlas-platform-launch`, "
+                "`PLAT-T-10`, `PLAT-SP-3`, `PLAT-R-7`. The UUID when the owning "
+                "project has no key."
+            )
+        ),
+    },
+)
+
+KEY_SUGGESTION_RESPONSE = inline_serializer(
+    "KeySuggestionResponse",
+    {
+        "available": serializers.BooleanField(
+            required=False,
+            help_text="Present only when `key` was sent. Whether that key can be used.",
+        ),
+        "reason": serializers.ChoiceField(
+            choices=["taken", "reserved", "invalid"],
+            allow_null=True,
+            required=False,
+            help_text=(
+                "Present only when `key` was sent. Why it is unavailable: `taken` "
+                "(held now or before by some project/program — never says which), "
+                "`reserved` (`new`, `settings`, `trash`, or UUID-shaped), or `invalid` "
+                "(does not match the format). Null when available."
+            ),
+        ),
+        "suggestion": serializers.CharField(
+            help_text=(
+                "A free key: derived from `name`, or the next free suffix of `key` "
+                "(`PLAT` → `PLAT2`). Free at the time of the call only."
+            )
+        ),
+    },
+)
+
+_ERROR_RESPONSE = inline_serializer("KeyRequestError", {"detail": serializers.CharField()})
+
+
+def _bad_request(detail: str) -> Response:
+    return Response({"detail": detail}, status=status.HTTP_400_BAD_REQUEST)
+
+
+def _kind(request: Request) -> str | None:
+    kind = (request.query_params.get("kind") or "").strip().lower()
+    return kind if kind in KINDS else None
+
+
+def _user(request: Request) -> Any:
+    # IsAuthenticated has already run; the Any keeps AnonymousUser out of the lookup type.
+    return request.user
+
+
+def readable_projects(request: Request) -> QuerySet[Project]:
+    """Projects the caller can read, intersected with the token's scope (ADR-1237 §5).
+
+    Readable is the same rule ``ProjectScopedViewSet`` applies: a live
+    ``ProjectMembership`` on a live project. A project- or program-scoped
+    ``ApiToken`` authenticates *as its minter*, so without the intersection it
+    would resolve every project the minter can see — the #1712 blast-radius
+    problem on a new surface.
+    """
+    qs = Project.objects.filter(
+        is_deleted=False,
+        pk__in=ProjectMembership.objects.filter(user=_user(request), is_deleted=False).values(
+            "project_id"
+        ),
+    )
+    token = getattr(request, "auth", None)
+    if isinstance(token, ApiToken):
+        if token.project_id is not None:
+            qs = qs.filter(pk=token.project_id)
+        elif token.program_id is not None:
+            qs = qs.filter(program_id=token.program_id)
+    return qs
+
+
+def readable_programs(request: Request) -> QuerySet[Program]:
+    """Programs the caller can read, intersected with the token's scope.
+
+    A project-scoped token resolves no program at all: it was minted for one
+    project, and the program around it is not part of that grant.
+    """
+    qs = Program.objects.filter(is_deleted=False).filter(
+        Exists(
+            ProgramMembership.objects.filter(
+                program=OuterRef("pk"), user=_user(request), is_deleted=False
+            )
+        )
+    )
+    token = getattr(request, "auth", None)
+    if isinstance(token, ApiToken):
+        if token.project_id is not None:
+            return qs.none()
+        if token.program_id is not None:
+            qs = qs.filter(pk=token.program_id)
+    return qs
+
+
+def _match_key(qs: QuerySet[Any], kind: str, key: str) -> Any:
+    """The object in ``qs`` whose current or retired key is ``key``, or ``None``.
+
+    ``code`` is matched as well as ``ObjectKey`` so a key written by a pre-0.4 pod
+    during the rolling upgrade, which has no row yet, still resolves.
+    """
+    fk = "program_id" if kind == KIND_PROGRAM else "project_id"
+    held = ObjectKey.objects.filter(kind=kind, key__iexact=key).values(fk)
+    return qs.filter(Q(code__iexact=key) | Q(pk__in=held)).first()
+
+
+def _owner_ref(project: Project) -> str | None:
+    return project.code or None
+
+
+def _project_body(project: Project) -> dict[str, Any]:
+    return {
+        "type": KIND_PROJECT,
+        "id": str(project.pk),
+        "project_id": str(project.pk),
+        "program_id": str(project.program_id) if project.program_id else None,
+        "key": _owner_ref(project),
+        "canonical_ref": project.code or str(project.pk),
+    }
+
+
+def _program_body(program: Program) -> dict[str, Any]:
+    return {
+        "type": KIND_PROGRAM,
+        "id": str(program.pk),
+        "project_id": None,
+        "program_id": str(program.pk),
+        "key": program.code or None,
+        "canonical_ref": program.code or str(program.pk),
+    }
+
+
+def _child_body(project: Project, kind: str, obj: Any, marker: str, number: int) -> dict[str, Any]:
+    return {
+        "type": kind,
+        "id": str(obj.pk),
+        "project_id": str(project.pk),
+        "program_id": str(project.program_id) if project.program_id else None,
+        "key": _owner_ref(project),
+        "canonical_ref": f"{project.code}-{marker}-{number}" if project.code else str(obj.pk),
+    }
+
+
+def _resolve_child(project: Project, marker: str, number: int) -> dict[str, Any] | None:
+    """Decode a ``T``/``SP``/``R`` number against ``project``.
+
+    Tasks and sprints share the hex ``object_sequence`` short id, so ``T-10`` is
+    ``short_id == "0000000A"`` (see ``format_short_id_display``); risks keep their
+    own decimal counter, so ``R-7`` is ``short_id == "7"`` (#929).
+    """
+    if marker == "R":
+        risk = Risk.objects.filter(project=project, short_id=str(number), is_deleted=False).first()
+        return _child_body(project, "risk", risk, "R", number) if risk else None
+    hex_id = f"{number:08X}"
+    if marker == "T":
+        task = Task.objects.filter(project=project, short_id=hex_id, is_deleted=False).first()
+        return _child_body(project, "task", task, "T", number) if task else None
+    sprint = Sprint.objects.filter(project=project, short_id=hex_id, is_deleted=False).first()
+    return _child_body(project, "sprint", sprint, "SP", number) if sprint else None
+
+
+class _TokenReachableView(APIView):
+    """Accept a project/program-scoped API token ahead of the default auth stack.
+
+    ``readable_projects``/``readable_programs`` (above) already intersect a
+    project- or program-scoped ``ApiToken`` against its own ``project_id``/
+    ``program_id`` — that IS the #1712 confused-deputy defense for this surface.
+    Without this override, such a token never reaches that code at all: the
+    default auth stack's ``OwnerScopedApiTokenAuthentication`` accepts only
+    owner-scoped (personal) tokens and 401s every project/program token before
+    the view runs, so ``readable_projects``'/``readable_programs``' token
+    branches were dead in production (rbac-check finding, security-review Low).
+
+    This mirrors ``McpReadableViewMixin.get_authenticators`` — prepend
+    ``ProjectApiTokenAuthentication`` so a ``tppm_`` bearer authenticates before
+    JWT/the owner-scoped class get a turn — but deliberately WITHOUT that
+    mixin's ``TokenIsOwnerScoped`` guard, which *rejects* project/program
+    tokens outright for the unscoped MCP collection reads (#1712). Rejecting
+    them here would be the opposite bug: ADR-1237 §5 is written for exactly a
+    project/program token narrowing the resolver to its own scope, so the
+    guard that protects the MCP surface would 401 the very callers this
+    endpoint exists to admit.
+    """
+
+    def get_authenticators(self) -> list[BaseAuthentication]:
+        from trueppm_api.apps.projects.authentication import ProjectApiTokenAuthentication
+
+        return [ProjectApiTokenAuthentication(), *super().get_authenticators()]
+
+
+class ResolveView(_TokenReachableView):
+    """Resolve a key, retired key, UUID, or ``PLAT-T-10`` reference to UUIDs (ADR-1237 §5).
+
+    Read-only, no side effects, no audit event. Anything the caller cannot read
+    — or that does not exist — is the same ``404 {"detail": "Not found."}``.
+    """
+
+    permission_classes = [IsAuthenticated]  # noqa: RUF012
+    throttle_classes = [ScopedRateThrottle]  # noqa: RUF012
+    throttle_scope = "resolve"
+
+    @extend_schema(
+        summary="Resolve a project/program key or reference to its ids",
+        description=(
+            "`ref` is a current key, a retired key, a UUID, or `<KEY>-<T|SP|R>-<n>` "
+            "(project kind only). A hyphenated legacy key parses on the rightmost "
+            "marker: `GA-SEC-T-10` is task 10 of `GA-SEC`. `key` and `canonical_ref` "
+            "are always the CURRENT form, so a client holding a retired key learns "
+            "the new one.\n\n"
+            "Visibility is the lookup: only projects/programs the caller is a live "
+            "member of, intersected with a project/program token's scope, can match. "
+            'Everything else — missing, hidden, out of token scope — is `404 {"detail": '
+            '"Not found."}`, byte-identical. Throttle scope `resolve`.'
+        ),
+        parameters=[
+            OpenApiParameter("kind", str, OpenApiParameter.QUERY, required=True, enum=list(KINDS)),
+            OpenApiParameter("ref", str, OpenApiParameter.QUERY, required=True),
+        ],
+        responses={
+            200: RESOLVE_RESPONSE,
+            400: OpenApiResponse(
+                response=_ERROR_RESPONSE, description="Missing or invalid kind/ref."
+            ),
+            404: OpenApiResponse(
+                response=_ERROR_RESPONSE,
+                description="Nothing the caller can read matches `ref`.",
+            ),
+        },
+    )
+    def get(self, request: Request) -> Response:
+        kind = _kind(request)
+        if kind is None:
+            return _bad_request("kind must be 'project' or 'program'.")
+        ref = (request.query_params.get("ref") or "").strip()
+        if not ref or len(ref) > _MAX_REF_LENGTH:
+            return _bad_request("ref is required.")
+        body = self._resolve(request, kind, ref)
+        if body is None:
+            return Response(dict(_NOT_FOUND_BODY), status=status.HTTP_404_NOT_FOUND)
+        return Response(body)
+
+    def _resolve(self, request: Request, kind: str, ref: str) -> dict[str, Any] | None:
+        if kind == KIND_PROGRAM:
+            programs = readable_programs(request)
+            try:
+                program = programs.filter(pk=uuid.UUID(ref)).first()
+            except ValueError:
+                program = _match_key(programs, KIND_PROGRAM, ref)
+            return _program_body(program) if program is not None else None
+
+        projects = readable_projects(request)
+        try:
+            project = projects.filter(pk=uuid.UUID(ref)).first()
+        except ValueError:
+            project = None
+        else:
+            return _project_body(project) if project is not None else None
+
+        # The whole ref as a key first: a grandfathered code can itself end in
+        # something marker-shaped, and addressing the project must win.
+        project = _match_key(projects, KIND_PROJECT, ref)
+        if project is not None:
+            return _project_body(project)
+        match = _REF_RE.fullmatch(ref)
+        if match is None:
+            return None
+        project = _match_key(projects, KIND_PROJECT, match["key"])
+        if project is None:
+            return None
+        return _resolve_child(project, match["marker"].upper(), int(match["n"]))
+
+
+class KeySuggestionView(_TokenReachableView):
+    """Suggest a key from a name, or check one key's availability (ADR-1237 §6).
+
+    **This is an existence oracle, and that is accepted.** A workspace-unique
+    namespace cannot refuse a taken key without saying it is taken, so a caller
+    learns that *some* project holds ``ACME`` — never which one, its name, or its
+    UUID. Scoping this to the caller's membership would silently allow duplicate
+    keys; do not "fix" it. Throttled in the same ``resolve`` bucket.
+    """
+
+    permission_classes = [IsAuthenticated]  # noqa: RUF012
+    throttle_classes = [ScopedRateThrottle]  # noqa: RUF012
+    throttle_scope = "resolve"
+
+    @extend_schema(
+        summary="Suggest a project/program key, or check one for availability",
+        description=(
+            "Send `name` to get `{suggestion}` derived from it (`Platform` → `PLAT`, "
+            "then `PLAT2` when taken). Send `key` to get `{available, reason, "
+            "suggestion}`. A key is taken if any project (or program) holds or ever "
+            "held it — keys are never reissued. The response never names the holder. "
+            "`object_id` (optional, with `key`) is the project/program being renamed: "
+            "its own current and retired keys are reported available, because "
+            "renaming back is allowed. Throttle scope `resolve`."
+        ),
+        parameters=[
+            OpenApiParameter("kind", str, OpenApiParameter.QUERY, required=True, enum=list(KINDS)),
+            OpenApiParameter("name", str, OpenApiParameter.QUERY, required=False),
+            OpenApiParameter("key", str, OpenApiParameter.QUERY, required=False),
+            OpenApiParameter("object_id", str, OpenApiParameter.QUERY, required=False),
+        ],
+        responses={
+            200: KEY_SUGGESTION_RESPONSE,
+            400: OpenApiResponse(
+                response=_ERROR_RESPONSE, description="Missing kind, or neither name nor key."
+            ),
+        },
+    )
+    def get(self, request: Request) -> Response:
+        from trueppm_api.apps.projects.services import (
+            KeyAssignmentError,
+            derive_key,
+            is_key_taken,
+            suggest_free_key,
+        )
+
+        kind = _kind(request)
+        if kind is None:
+            return _bad_request("kind must be 'project' or 'program'.")
+        raw_key = (request.query_params.get("key") or "").strip()
+        name = (request.query_params.get("name") or "").strip()
+        try:
+            if raw_key:
+                if len(raw_key) > _MAX_REF_LENGTH:
+                    return _bad_request("key is too long.")
+                key = normalize_key(raw_key, kind)
+                problem = key_format_error(key, kind)
+                if problem is not None:
+                    reserved = is_reserved(key)
+                    base = key if reserved else base_key_for(raw_key, kind)
+                    return Response(
+                        {
+                            "available": False,
+                            "reason": "reserved" if reserved else "invalid",
+                            "suggestion": suggest_free_key(base, kind),
+                        }
+                    )
+                exclude = self._renamed_object(request, kind)
+                if is_key_taken(kind, key, exclude=exclude):
+                    return Response(
+                        {
+                            "available": False,
+                            "reason": "taken",
+                            "suggestion": suggest_free_key(key, kind),
+                        }
+                    )
+                return Response({"available": True, "reason": None, "suggestion": key})
+            if name:
+                if len(name) > 255:
+                    return _bad_request("name is too long.")
+                return Response({"suggestion": derive_key(name, kind)})
+        except KeyAssignmentError as exc:
+            # Namespace-squatting cap (security-review Low, perf-check Low):
+            # next_free_key() gives up after MAX_SUFFIX_ATTEMPTS rather than
+            # looping forever. A 400 the caller can act on (pick their own key),
+            # never a 500.
+            return _bad_request(str(exc))
+        return _bad_request("Send name or key.")
+
+    def _renamed_object(self, request: Request, kind: str) -> Any:
+        """The object being renamed, when the caller can read it; else ``None``.
+
+        Resolved through the same readable querysets as the resolver, so naming
+        an object you cannot see simply has no effect.
+        """
+        raw = (request.query_params.get("object_id") or "").strip()
+        if not raw:
+            return None
+        try:
+            pk = uuid.UUID(raw)
+        except ValueError:
+            return None
+        qs: QuerySet[Any] = (
+            readable_programs(request) if kind == KIND_PROGRAM else readable_projects(request)
+        )
+        return qs.filter(pk=pk).first()

trueppm_api/apps/projects/keys.py

@@ -0,0 +1,205 @@
+"""Pure key rules for project and program keys (ADR-1237).
+
+A key is the human address of a project (``PLAT``) or program
+(``atlas-platform-launch``), stored denormalized as ``code`` and, with its whole
+history, as ``ObjectKey`` rows. This module holds only the rules that need no
+database: format, reserved words, normalization, the derivation of a base key
+from a name, and the suffixing that makes a base key free. It is deliberately
+ORM-free so the migration repair (``projects.backfill``) can reuse exactly the
+rules the live service applies — two copies of a derivation rule drift, and a
+backfill that derives ``PLAT`` differently from the create path would leave the
+upgrade and the next create disagreeing about what a name's key is.
+
+The database-aware halves (``derive_key``, ``assign_key``) live in
+``apps.projects.services``.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from collections.abc import Callable
+
+KIND_PROJECT = "project"
+KIND_PROGRAM = "program"
+KINDS = (KIND_PROJECT, KIND_PROGRAM)
+
+#: New project keys: a letter, then 1-9 letters or digits. No hyphen, so a
+#: reference is ``-``-separated like Jira and the shipped ``PLAT-R-7``.
+PROJECT_KEY_RE = re.compile(r"[A-Z][A-Z0-9]{1,9}")
+PROJECT_KEY_MAX = 10
+#: Pre-ADR-1237 project codes (hyphens allowed, <=12). Grandfathered: a stored
+#: value in this shape is never rewritten and still resolves, but no *new* value
+#: may take it.
+LEGACY_PROJECT_CODE_RE = re.compile(r"[A-Z0-9](?:[A-Z0-9-]*[A-Z0-9])?")
+LEGACY_PROJECT_CODE_MAX = 12
+#: Program keys stay slugs, because seed replace keys on ``program.slug``.
+PROGRAM_KEY_RE = re.compile(r"[a-z0-9](?:[a-z0-9-]*[a-z0-9])?")
+PROGRAM_KEY_MAX = 40
+
+#: Route segments a key must never shadow (``/projects/new``, ``/projects/trash``).
+RESERVED_KEYS = frozenset({"new", "settings", "trash"})
+_UUID_SHAPED = re.compile(
+    r"[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}", re.IGNORECASE
+)
+
+#: The DoS bound on renames (ADR-1237 threat model, D): a rename loop would
+#: otherwise reserve keys forever.
+MAX_RETIRED_KEYS = 10
+
+#: Cap on how many candidates :func:`next_free_key` will probe (security-review
+#: Low, perf-check Low). Without a bound, namespace squatting — deliberately
+#: registering every key in a popular name's suffix run (``PLAT``, ``PLAT2``,
+#: ``PLAT3``, …) — turns another user's create or rename into an unbounded
+#: loop of 1-2 queries per candidate. 1000 is far past any real collision run
+#: (the suffix cap already trims the base to fit ``PROJECT_KEY_MAX``/
+#: ``PROGRAM_KEY_MAX``, so exhausting it needs 1000 deliberately-squatted keys
+#: for one base) and still resolves in well under the ``resolve`` throttle's
+#: per-request budget.
+MAX_SUFFIX_ATTEMPTS = 1000
+
+# The en dash matches the UX copy (ADR-1237 UX spec §1) the web renders verbatim.
+PROJECT_FORMAT_MESSAGE = "Letters and digits only, starting with a letter, 2–10 characters."  # noqa: RUF001
+PROGRAM_FORMAT_MESSAGE = "Lowercase letters, digits and hyphens, up to 40 characters."
+RESERVED_MESSAGE = "That word is reserved."
+IN_USE_MESSAGE = "This key is already in use."
+CAP_MESSAGE = (
+    f"This key has been changed {MAX_RETIRED_KEYS} times, the most allowed. "
+    "Contact your workspace admin."
+)
+
+_PROJECT_FALLBACK = "PROJ"
+_PROGRAM_FALLBACK = "program"
+
+SUFFIX_EXHAUSTED_MESSAGE = "Couldn't find a free key from this name — please choose one."
+
+
+class KeyAssignmentError(ValueError):
+    """A key write refused for a caller-correctable reason; always a ``400`` on ``code``.
+
+    Defined here rather than in ``services.py`` (its main call site and the
+    module every existing ``except KeyAssignmentError`` imports it from)
+    because :func:`next_free_key` below must be able to raise it, and this
+    module is deliberately import-light (see the module docstring) — nothing
+    here may depend on ``services.py``. ``services.py`` re-exports this name,
+    so every existing ``from trueppm_api.apps.projects.services import
+    KeyAssignmentError`` keeps working unchanged.
+
+    The message never names the object holding a taken key — the existence
+    oracle ADR-1237 §6 accepts leaks *that* a key is taken, never *by what*.
+    """
+
+
+def is_uuid_shaped(value: str) -> bool:
+    """True when ``value`` would read as a UUID (hyphenated or bare hex)."""
+    return bool(_UUID_SHAPED.fullmatch(value))
+
+
+def normalize_key(key: str, kind: str) -> str:
+    """Canonical case for ``kind``: project keys upper, program keys lower.
+
+    Comparison is case-insensitive either way; normalizing on write means the
+    stored form is what a user would have typed into the UI, which uppercases
+    (project) or lowercases (program) as they type.
+    """
+    stripped = (key or "").strip()
+    return stripped.upper() if kind == KIND_PROJECT else stripped.lower()
+
+
+def key_format_error(key: str, kind: str) -> str | None:
+    """Why ``key`` cannot be a *new* key of ``kind``, or ``None`` when it can.
+
+    Expects an already-normalized key. Reserved words and UUID-shaped values are
+    checked for both kinds: a key must never shadow a route segment or be
+    mistaken for the UUID it stands in for.
+    """
+    if kind == KIND_PROJECT:
+        if not PROJECT_KEY_RE.fullmatch(key):
+            return PROJECT_FORMAT_MESSAGE
+    elif len(key) > PROGRAM_KEY_MAX or not PROGRAM_KEY_RE.fullmatch(key):
+        return PROGRAM_FORMAT_MESSAGE
+    if key.lower() in RESERVED_KEYS or is_uuid_shaped(key):
+        return RESERVED_MESSAGE
+    return None
+
+
+def is_reserved(key: str) -> bool:
+    """True for a reserved word or a UUID-shaped value (either kind)."""
+    return key.lower() in RESERVED_KEYS or is_uuid_shaped(key)
+
+
+def _ascii(value: str) -> str:
+    return unicodedata.normalize("NFKD", value or "").encode("ascii", "ignore").decode("ascii")
+
+
+def base_key_for(name: str, kind: str) -> str:
+    """The un-suffixed key a ``name`` suggests. Always a valid new key of ``kind``.
+
+    Project: the initials of a multi-word name (``Platform Migration`` → ``PM``),
+    or the first four characters of a single word (``Platform`` → ``PLAT``). A
+    result that would start with a digit gets a ``P`` prefix. Program: the name
+    slugified to ``[a-z0-9-]``, capped at 40.
+
+    Reserved and UUID-shaped results are *not* rejected here — they are valid
+    shapes that :func:`next_free_key` steps past with a suffix, the same way it
+    steps past a taken key.
+    """
+    if kind == KIND_PROJECT:
+        words = re.findall(r"[A-Za-z0-9]+", _ascii(name))
+        if len(words) >= 2:
+            base = "".join(word[0] for word in words)
+        elif words:
+            base = words[0][:4]
+        else:
+            base = ""
+        base = base.upper()
+        if base and base[0].isdigit():
+            base = f"P{base}"
+        base = base[:PROJECT_KEY_MAX]
+        if len(base) < 2:
+            # One-letter initials ("X") or nothing usable at all.
+            base = (base + words[0][1:4].upper()) if words and len(words[0]) > 1 else ""
+            base = base[:PROJECT_KEY_MAX]
+        if not PROJECT_KEY_RE.fullmatch(base):
+            base = _PROJECT_FALLBACK
+        return base
+    slug = re.sub(r"[^a-z0-9]+", "-", _ascii(name).lower()).strip("-")
+    slug = slug[:PROGRAM_KEY_MAX].rstrip("-")
+    return slug or _PROGRAM_FALLBACK
+
+
+def _suffixed(base: str, n: int, kind: str) -> str:
+    if kind == KIND_PROJECT:
+        tail = str(n)
+        return base[: PROJECT_KEY_MAX - len(tail)] + tail
+    tail = f"-{n}"
+    return base[: PROGRAM_KEY_MAX - len(tail)].rstrip("-") + tail
+
+
+def next_free_key(base: str, kind: str, is_taken: Callable[[str], bool]) -> str:
+    """``base`` if free, else the first free ``base2``/``base3``… (``base-2`` for programs).
+
+    ``is_taken`` is asked about each candidate; reserved and UUID-shaped
+    candidates are skipped without asking. The suffix trims the base rather than
+    exceeding the length cap, so ``ABCDEFGHIJ`` steps to ``ABCDEFGHI2``.
+
+    Raises:
+        KeyAssignmentError: after :data:`MAX_SUFFIX_ATTEMPTS` candidates are all
+            reserved or taken (security-review Low, perf-check Low). Without a
+            bound, namespace squatting — pre-registering every suffix of a
+            popular base — turns another caller's create or rename into an
+            unbounded loop of 1-2 queries per candidate. Every caller of this
+            function already sits behind (or is wrapped to sit behind) a
+            ``KeyAssignmentError`` handler that turns it into a ``400`` on
+            ``code``, so this is a caller-correctable refusal, not a crash.
+    """
+    candidate = base
+    n = 1
+    attempts = 1
+    while is_reserved(candidate) or is_taken(candidate):
+        if attempts >= MAX_SUFFIX_ATTEMPTS:
+            raise KeyAssignmentError(SUFFIX_EXHAUSTED_MESSAGE)
+        n += 1
+        candidate = _suffixed(base, n, kind)
+        attempts += 1
+    return candidate