provide-uterm-client 0.5.0__tar.gz

provide_uterm_client-0.5.0/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: provide-uterm-client
+Version: 0.5.0
+Summary: Client libraries, transports, and AI/MCP integration for provide-uterm
+License-Expression: AGPL-3.0-or-later
+Requires-Python: >=3.11
+Requires-Dist: provide-uterm>=0.5.0
+Requires-Dist: mcp>=2.0.0
+Provides-Extra: http
+Requires-Dist: httpx2>=2.10; extra == "http"
+Provides-Extra: websocket
+Requires-Dist: websockets>=16.0; extra == "websocket"
+Provides-Extra: ssh
+Requires-Dist: asyncssh>=2.22.0; extra == "ssh"
+Provides-Extra: all
+Requires-Dist: httpx2>=2.10; extra == "all"
+Requires-Dist: websockets>=16.0; extra == "all"
+Requires-Dist: asyncssh>=2.22.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.3; extra == "dev"
+Requires-Dist: pytest-cov>=7.0; extra == "dev"
+Requires-Dist: pytest-timeout>=2.4.0; extra == "dev"
+Requires-Dist: mypy>=1.19; extra == "dev"
+Requires-Dist: ruff>=0.15; extra == "dev"
+Requires-Dist: httpx2>=2.10; extra == "dev"
+Requires-Dist: websockets>=16.0; extra == "dev"
+Requires-Dist: asyncssh>=2.22.0; extra == "dev"

provide_uterm_client-0.5.0/README.md

@@ -0,0 +1,60 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+# provide-uterm-client
+
+Async HTTP and WebSocket client library for the provide-uterm control plane.
+Provides `HijackClient` for REST-based session and hijack management, plus
+inline WebSocket clients (`AsyncInlineWebSocketClient`,
+`SyncInlineWebSocketClient`) for real-time terminal data streams. Every method
+returns `tuple[bool, dict]` for straightforward success/error handling.
+
+## Installation
+
+```bash
+pip install provide-uterm-client[http]        # HijackClient (httpx)
+pip install provide-uterm-client[websocket]   # WS clients (websockets)
+```
+
+Requires Python 3.11+.
+
+## HijackClient API
+
+| Method | Description |
+|---|---|
+| `acquire(worker_id, owner, lease_s)` | Acquire a lease-based hijack session |
+| `heartbeat(worker_id, hijack_id, lease_s)` | Extend a hijack lease |
+| `send(worker_id, hijack_id, keys, ...)` | Send input with optional prompt guard |
+| `snapshot(worker_id, hijack_id, wait_ms)` | Read terminal snapshot |
+| `events(worker_id, hijack_id, after_seq)` | Read event log |
+| `step(worker_id, hijack_id)` | Single-step the worker loop |
+| `release(worker_id, hijack_id)` | Release hijack, resume automation |
+| `list_sessions()` | List all sessions |
+| `get_session(session_id)` | Get session details |
+| `session_snapshot(session_id)` | Get session terminal snapshot |
+| `watch_session_events(session_id, ...)` | Long-poll session event stream |
+| `quick_connect(connector_type, ...)` | Create an ephemeral session |
+| `health()` | Server health check |
+
+## Usage
+
+```python
+from provide.uterm.client import HijackClient
+
+async with HijackClient("http://localhost:8780") as c:
+    ok, data = await c.acquire("worker-1", owner="agent")
+    if ok:
+        ok, snap = await c.snapshot("worker-1", data["hijack_id"])
+        print(snap["snapshot"]["screen"])
+        await c.release("worker-1", data["hijack_id"])
+```
+
+## Key modules
+
+- `provide.uterm.client.hijack` -- `HijackClient` async REST client
+- `provide.uterm.client.control_ws` -- `AsyncInlineWebSocketClient`, `SyncInlineWebSocketClient`, `LogicalFrameDecoder`
+- `provide.uterm.client.mcp_tools` -- shared helpers used by the AI package
+
+## Links
+
+- [Main repository README](../../README.md)

provide_uterm_client-0.5.0/VERSION

@@ -0,0 +1 @@
+0.5.0

provide_uterm_client-0.5.0/pyproject.toml

@@ -0,0 +1,102 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "provide-uterm-client"
+dynamic = ["version"]
+description = "Client libraries, transports, and AI/MCP integration for provide-uterm"
+requires-python = ">=3.11"
+license = "AGPL-3.0-or-later"
+dependencies = [
+    "provide-uterm>=0.5.0",
+    # Base dependency, not an extra: `uterm-mcp` (below, [project.scripts]) is
+    # an unconditional console script pointing at provide.uterm.ai, which
+    # imports mcp at module scope. Gating mcp behind an extra would let
+    # `pip install provide-uterm-client` install a console script whose own
+    # import fails until the caller separately opts into an extra it has no
+    # way to discover from the entry point alone -- a latent packaging bug
+    # that predates this port (the old fastmcp-extra arrangement had the same
+    # shape). Declaring mcp unconditionally is the fix, not an oversight.
+    "mcp>=2.0.0",
+]
+
+[project.optional-dependencies]
+http = ["httpx2>=2.10"]
+websocket = ["websockets>=16.0"]
+ssh = ["asyncssh>=2.22.0"]
+all = ["httpx2>=2.10", "websockets>=16.0", "asyncssh>=2.22.0"]
+dev = [
+    "pytest>=9.0",
+    "pytest-asyncio>=1.3",
+    "pytest-cov>=7.0",
+    "pytest-timeout>=2.4.0",
+    "mypy>=1.19",
+    "ruff>=0.15",
+    "httpx2>=2.10",
+    "websockets>=16.0",
+    "asyncssh>=2.22.0",
+]
+
+[project.scripts]
+uterm-mcp = "provide.uterm.ai.cli:main"
+
+[tool.setuptools.dynamic]
+version = {file = "VERSION"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"provide.uterm" = ["py.typed"]
+
+[tool.pytest.ini_options]
+consider_namespace_packages = true
+asyncio_mode = "auto"
+testpaths = ["tests"]
+markers = [
+    "go_interop: tests requiring a built Go uterm binary",
+]
+addopts = [
+    "--import-mode=importlib",
+    "-v",
+    "--strict-markers",
+    "--tb=short",
+    "-ra",
+    "--cov=provide.uterm.client",
+    "--cov=provide.uterm.transports",
+    "--cov=provide.uterm.ai",
+    "--cov-branch",
+    "--cov-report=term-missing",
+    "--cov-fail-under=100",
+]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+
+[tool.ruff.lint]
+select = [
+    "E", "W", "F", "I", "N", "UP", "B", "C4", "SIM", "TCH", "PTH",
+    "DTZ", "ICN", "ISC", "PERF", "PIE", "RET", "RSE", "TID", "S", "ARG", "RUF",
+]
+# Aligned with the workspace-root ruff config in ../../pyproject.toml.
+ignore = [
+    "E501", "S101", "S104", "S108", "S110", "S112", "S311", "S603", "S607",
+    "S604", "F811", "N806", "N814", "B017", "SIM105", "SIM117", "ARG001",
+    "ARG002", "PTH108", "SIM108", "PERF401",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401", "RUF022"]
+"tests/**/*.py" = ["E402", "B905", "S101", "S105", "S106", "S110", "ARG", "TCH", "RUF003", "RUF012", "RUF015", "RUF043", "RUF059"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+namespace_packages = true
+explicit_package_bases = true
+mypy_path = ["src"]

provide_uterm_client-0.5.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

provide_uterm_client-0.5.0/src/provide/uterm/ai/__init__.py

@@ -0,0 +1,7 @@
+#
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+from provide.uterm.ai.server import create_mcp_app
+
+__all__ = ["create_mcp_app"]

provide_uterm_client-0.5.0/src/provide/uterm/ai/auth.py

@@ -0,0 +1,252 @@
+#
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+"""Authorization chokepoint for MCP tool dispatch.
+
+All MCP tool handlers go through :func:`authorize` (applied via
+:func:`authorized` decorator) before their bodies execute.  The chokepoint:
+
+1. Resolves the calling :class:`McpPrincipal` via the transport's
+   authenticated identity (when available, from :func:`mcp.server.mcpserver.authenticated_principal`),
+   or falls back to the server's configured default principal.
+2. Looks up the tool's required role in
+   :mod:`provide.uterm.ai.policy`.
+3. Rejects with a typed :class:`AuthorizationDenied` (returned as a
+   structured error dict — never raised across the wire) before the tool
+   body runs.
+
+Adding a new tool therefore requires an explicit
+:data:`~provide.uterm.ai.policy.TOOL_REQUIRED_ROLES` entry; otherwise
+the chokepoint refuses the call.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from functools import wraps
+from typing import Any, Protocol, TypeVar, cast
+
+from mcp.server.mcpserver import authenticated_principal
+
+from provide.uterm.ai.policy import Role, required_role, role_at_least
+
+F = TypeVar("F", bound=Callable[..., Awaitable[Any]])
+
+
+@dataclass(slots=True, frozen=True)
+class McpPrincipal:
+    """Principal calling an MCP tool.
+
+    Mirrors the fields used by ``provide.uterm.server.auth.Principal``
+    that matter at the MCP boundary.  Kept lightweight: the MCP layer does
+    not need OIDC claims, just identity + role(s).
+    """
+
+    subject_id: str = "anonymous"
+    roles: frozenset[str] = field(default_factory=lambda: frozenset({"viewer"}))
+
+    @property
+    def primary_role(self) -> str:
+        """Return the highest-privilege role the principal holds."""
+        from provide.uterm.ai.policy import role_rank
+
+        if not self.roles:
+            return "viewer"
+        return max(self.roles, key=role_rank)
+
+    def has_at_least(self, minimum: Role) -> bool:
+        """Return True if the principal has a role at least *minimum*."""
+        return any(role_at_least(r, minimum) for r in self.roles)
+
+
+class _ContextLike(Protocol):
+    """Subset of the MCP ``Context`` the chokepoint uses (kept narrow for typing)."""
+
+    @property
+    def request_context(self) -> Any: ...
+
+
+class AuthorizationDenied(Exception):  # noqa: N818 — domain-modeling name; not all exceptions end in Error.
+    """Raised when a principal is not permitted to invoke a tool.
+
+    The chokepoint catches this and converts it into a structured error
+    dict so MCP clients receive a deterministic shape rather than an MCP
+    transport-level exception.
+    """
+
+    def __init__(self, *, tool: str, principal: McpPrincipal, required: Role) -> None:
+        self.tool = tool
+        self.principal = principal
+        self.required = required
+        super().__init__(
+            f"principal {principal.subject_id!r} (roles={sorted(principal.roles)}) "
+            f"is not authorized to call tool {tool!r} (requires {required!r})"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Principal resolution.
+# ---------------------------------------------------------------------------
+
+# MCP 2.0 removed fastmcp's per-request state bag (``ctx.get_state``), so the
+# principal is no longer looked up by key. The SDK's own binding —
+# ``authenticated_principal`` — supplies the authenticated (client, issuer,
+# subject) identity directly, and returns None on unauthenticated transports
+# such as stdio.
+
+
+def principal_from_headers(headers: dict[str, str] | None) -> McpPrincipal | None:
+    """Build a principal from ``X-Uterm-Principal`` / ``X-Uterm-Role`` headers.
+
+    Returns ``None`` when neither header is present.  Header lookup is
+    case-insensitive.
+
+    Security boundary: these headers are trusted only because they are
+    supplied locally by the operator launching the stdio server, via
+    ``client_kwargs["headers"]``. They are NOT a remote caller's assertion.
+    If an HTTP transport is ever enabled for this server, this path must be
+    removed or gated behind a verified token first — MCP 2.0's
+    ``Context.headers`` is explicit that client-supplied headers are never an
+    identity assertion.
+    """
+    if not headers:
+        return None
+    lowered = {k.lower(): v for k, v in headers.items()}
+    subject = lowered.get("x-uterm-principal")
+    role = lowered.get("x-uterm-role")
+    if subject is None and role is None:
+        return None
+    return McpPrincipal(
+        subject_id=subject or "anonymous",
+        roles=frozenset({role}) if role else frozenset({"viewer"}),
+    )
+
+
+def _authenticated_identity(ctx: _ContextLike) -> str | None:
+    """Return the transport-authenticated identity, or None.
+
+    Not a bare subject id: :func:`mcp.server.mcpserver.authenticated_principal`
+    returns a JSON-serialized ``(client_id, issuer, subject)`` triple (see
+    ``mcp/server/request_state.py``), which becomes ``McpPrincipal.subject_id``
+    verbatim. That value is operator-visible — it surfaces in
+    :func:`deny_payload`'s ``"principal"`` field and in
+    :class:`AuthorizationDenied`'s exception message — so it must read as an
+    identity string, not be mistaken for a plain username.
+
+    ``Context.request_context`` raises when no request is bound rather than
+    returning None, so the access is guarded: an unbound context is a
+    "no authenticated identity" answer, not an error worth propagating out of
+    an authorization check.
+
+    The subsequent call to ``authenticated_principal(request_context)`` is
+    deliberately left unguarded: it only reads a contextvar via
+    ``get_access_token()`` (default ``None``) and never touches its ``ctx``
+    argument, so it cannot raise on a garbage or mock ``request_context`` —
+    unlike the property access above, there is nothing here for a bare
+    ``except`` to usefully catch.
+    """
+    try:
+        request_context = ctx.request_context
+    except Exception:
+        return None
+    return authenticated_principal(request_context)
+
+
+async def resolve_principal(
+    ctx: _ContextLike | None,
+    *,
+    default: McpPrincipal,
+) -> McpPrincipal:
+    """Resolve the principal for the current MCP request.
+
+    Lookup order:
+
+    1. The transport-authenticated identity, when the transport binds one
+       (:func:`mcp.server.mcpserver.authenticated_principal`). Roles come from
+       the configured *default*, because that binding carries identity, not
+       authorisation.
+    2. Configured server *default* (passed in by ``create_mcp_app``).
+
+    Kept ``async`` despite no longer awaiting anything, so that
+    :func:`authorized` and its tests need no change.
+    """
+    if ctx is not None:
+        identity = _authenticated_identity(ctx)
+        if identity is not None:
+            return McpPrincipal(subject_id=identity, roles=default.roles)
+    return default
+
+
+# ---------------------------------------------------------------------------
+# Chokepoint dispatch.
+# ---------------------------------------------------------------------------
+
+
+def deny_payload(err: AuthorizationDenied) -> dict[str, Any]:
+    """Render an :class:`AuthorizationDenied` as a tool-result dict.
+
+    Shape matches the rest of the MCP tool surface (``success`` is False
+    and an ``error`` discriminator is included) so that callers can branch
+    on it without having to special-case authorization failures.
+    """
+    return {
+        "success": False,
+        "error": "authorization_denied",
+        "tool": err.tool,
+        "required_role": err.required,
+        "principal": err.principal.subject_id,
+        "principal_roles": sorted(err.principal.roles),
+    }
+
+
+@dataclass(slots=True)
+class AuthorizationContext:
+    """Bundle of state the chokepoint needs at every call.
+
+    A single instance is created by :func:`create_mcp_app` and closed over
+    by the per-tool wrappers.  Holding it in one place lets tests inject a
+    different default principal without monkey-patching.
+    """
+
+    default_principal: McpPrincipal
+
+
+def authorized(tool_name: str, auth_ctx: AuthorizationContext) -> Callable[[F], F]:
+    """Return a decorator that gates *tool_name* on its required role.
+
+    Principal resolution uses the transport-authenticated identity when
+    available (via :func:`mcp.server.mcpserver.authenticated_principal`), and
+    falls back to ``auth_ctx.default_principal``. The decorator preserves the
+    wrapped function's signature via :func:`functools.wraps` so that the MCP
+    server can introspect parameter types as if no decoration were applied.
+    """
+    minimum = required_role(tool_name)
+
+    def _decorator(fn: F) -> F:
+        @wraps(fn)
+        async def _wrapper(*args: Any, **kwargs: Any) -> Any:
+            ctx = kwargs.get("ctx")
+            principal = await resolve_principal(
+                cast("_ContextLike | None", ctx),
+                default=auth_ctx.default_principal,
+            )
+            if not principal.has_at_least(minimum):
+                err = AuthorizationDenied(tool=tool_name, principal=principal, required=minimum)
+                return deny_payload(err)
+            return await fn(*args, **kwargs)
+
+        # Stash metadata for tests / introspection. Using ``setattr`` makes
+        # the dynamic attribute attachment explicit to both mypy and ty
+        # (both type checkers treat direct ``obj.attr = …`` on a typed
+        # callable as an unresolved-attribute error; ``setattr`` is the
+        # canonical opt-out).
+        setattr(_wrapper, "__uterm_tool_name__", tool_name)  # noqa: B010
+        setattr(_wrapper, "__uterm_required_role__", minimum)  # noqa: B010
+        # ``functools.wraps`` returns ``_Wrapped[…]`` rather than the
+        # original ``F``; the cast tells both type checkers the wrapper
+        # honours the same callable shape as the wrapped function.
+        return cast("F", _wrapper)
+
+    return _decorator

provide_uterm_client-0.5.0/src/provide/uterm/ai/cli.py

@@ -0,0 +1,69 @@
+#
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+"""CLI entry point for the uterm-mcp server.
+
+Usage::
+
+    uterm-mcp --url http://localhost:8780
+    uterm-mcp --url http://localhost:8780 --entity-prefix /agent
+    uterm-mcp --url http://localhost:8780 --header Authorization:"Bearer tok"
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="uterm-mcp",
+        description="MCP server for provide-uterm session and hijack control.",
+    )
+    parser.add_argument("--url", required=True, help="Base URL of the provide-uterm server.")
+    parser.add_argument(
+        "--entity-prefix",
+        default="/worker",
+        help="Path prefix for worker endpoints (default: /worker).",
+    )
+    parser.add_argument(
+        "--header",
+        dest="headers",
+        action="append",
+        default=[],
+        help="Extra header as key:value (repeatable).",
+    )
+    # Default role granted to the stdio caller (the LLM) when no explicit
+    # identity headers are supplied.  Operators must opt in to ``admin`` —
+    # see Finding #2 in the security review notes.
+    parser.add_argument(
+        "--role",
+        dest="role",
+        choices=("admin", "operator", "viewer"),
+        default="operator",
+        help="Default role for the stdio caller (default: operator).",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Parse args and run the MCP server on stdio."""
+    parser = _build_parser()
+    args = parser.parse_args(argv if argv is not None else sys.argv[1:])
+
+    headers: dict[str, str] = {}
+    for h in args.headers:
+        key, _, value = h.partition(":")
+        headers[key.strip()] = value.strip()
+
+    from provide.uterm.ai.server import create_mcp_app
+
+    app = create_mcp_app(
+        args.url,
+        entity_prefix=args.entity_prefix,
+        headers=headers if headers else None,
+        default_role=args.role,
+    )
+    app.run(transport="stdio")

provide_uterm_client-0.5.0/src/provide/uterm/ai/constants.py

@@ -0,0 +1,29 @@
+#
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+"""Input-hardening limits and policy toggles for the MCP tool surface.
+
+Centralises the security tunables so no policy is hardcoded inline at the call
+sites.
+"""
+
+from __future__ import annotations
+
+# Keystroke byte cap for hijack_send (matches the sanitizer default so the two
+# code paths cannot drift).
+MAX_KEYSTROKE_BYTES: int = 4096
+
+# Maximum length of a user/LLM-supplied regex pattern. The length cap removes
+# the cheap amplification path; it is paired with a structural denylist (see
+# ``provide.uterm.ai.patterns.has_catastrophic_construct``) that rejects nested
+# quantifiers and quantified backreferences — the classic catastrophic-
+# backtracking shapes a short, under-the-cap pattern can still trigger. True
+# backtracking-time bounds would still require a ``regex``/``re2`` engine, so a
+# residual risk for exotic shapes (e.g. overlapping alternations) remains.
+MAX_USER_PATTERN_LEN: int = 512
+
+# Whether MCP-driven session_create may target private/internal hosts. Defaults
+# to deny: an LLM should not be able to pivot to 169.254.169.254, RFC1918, or
+# loopback. Operators that genuinely need internal targets must opt in.
+ALLOW_PRIVATE_HOSTS: bool = False

provide_uterm_client-0.5.0/src/provide/uterm/ai/patterns.py

@@ -0,0 +1,113 @@
+#
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+"""Structural ReDoS guard for untrusted (LLM/user-supplied) regex patterns.
+
+The MCP tool surface lets a caller — including a low-privilege ``viewer`` role
+via ``session_watch`` / ``session_subscribe`` — hand us a regex that we compile
+with stdlib :mod:`re`.  A pure length cap does not bound catastrophic
+backtracking for *short* pathological patterns such as ``(a+)+$``, so before any
+``re.compile`` we reject the cheap, well-known catastrophic constructs:
+
+* **nested quantifiers** — a quantified group whose body is itself quantified
+  (``(a+)+``, ``(a*)*``, ``(a+)*``, ``(a*)+``, ``(\\w+)+`` …), the classic
+  exponential-backtracking shape; and
+* **quantified backreferences** — ``\\1+``, ``(\\1)+`` …, which also drive
+  pathological backtracking.
+
+Neither stdlib :mod:`re` (no time bound) nor a new third-party engine
+(``re2``/``regex`` are not project dependencies) is used: this is a structural
+denylist applied *in addition to* the length cap.
+
+Residual risk (documented honestly): this does NOT catch every ReDoS shape —
+notably overlapping alternations like ``(a|a)*`` or quantifier interactions
+across adjacent tokens — because detecting those structurally without large
+false-positive collateral is hard.  It removes the cheap, classic amplification
+paths an LLM is most likely to emit; egress/time bounds at the server remain the
+defence-in-depth backstop.
+"""
+
+from __future__ import annotations
+
+import re
+
+# A backreference token: ``\1`` .. ``\99`` (stdlib ``re`` allows up to 99 groups).
+_BACKREF = re.compile(r"\\[1-9][0-9]?$")
+
+# A quantified backreference *anywhere* in the pattern: ``\1+``, ``\2*``,
+# ``\3{2,5}`` — the ``\`` is not itself escaped because the scan below skips
+# escaped pairs when collecting groups, but a top-level backref+quantifier needs
+# its own check (it is not wrapped in a group).
+_QUANTIFIED_BACKREF = re.compile(r"\\[1-9][0-9]?[+*{]")
+
+# Quantifier characters that, when they immediately follow a group close paren,
+# make that group "repeated".
+_QUANTIFIER_OPENERS = frozenset("+*{")
+
+
+def _group_bodies_with_following_char(pattern: str) -> list[tuple[str, str]]:
+    """Return ``(body, char_after_close)`` for every balanced ``(...)`` group.
+
+    Escaped parens (``\\(`` / ``\\)``) are treated as literals, not group
+    delimiters.  Unbalanced closes are ignored (the downstream stdlib compiler
+    rejects the pattern as invalid), so this never raises on malformed input.
+    """
+    stack: list[int] = []
+    results: list[tuple[str, str]] = []
+    i = 0
+    n = len(pattern)
+    while i < n:
+        char = pattern[i]
+        if char == "\\":
+            # Skip the escaped character so ``\(`` / ``\)`` are literals.
+            i += 2
+            continue
+        if char == "(":
+            stack.append(i)
+        elif char == ")" and stack:
+            start = stack.pop()
+            body = pattern[start + 1 : i]
+            after = pattern[i + 1] if i + 1 < n else ""
+            results.append((body, after))
+        i += 1
+    return results
+
+
+def _body_is_repeated_unit(body: str) -> bool:
+    """Return ``True`` when a group *body* is itself a repeated/backref unit.
+
+    Such a body, when the enclosing group is also quantified, forms the classic
+    nested-quantifier (``(a+)+``) or quantified-backref-in-group (``(\\1)+``)
+    catastrophic shape.
+    """
+    if not body:
+        return False
+    # The whole body is a backreference, e.g. ``(\1)+``.
+    if _BACKREF.fullmatch(body):
+        return True
+    last = body[-1]
+    # A lazy quantifier (``a+?``) ends in ``?``; the real quantifier is the
+    # char before it.
+    if last == "?":
+        return len(body) >= 2 and body[-2] in "+*}"
+    if last not in "+*}":
+        return False
+    # Guard against an escaped quantifier (``a\*``) being read as a quantifier.
+    return not (len(body) >= 2 and body[-2] == "\\")
+
+
+def has_catastrophic_construct(pattern: str) -> bool:
+    """Return ``True`` when *pattern* contains a known catastrophic construct.
+
+    Detects nested quantifiers (a quantified group whose body is itself
+    quantified) and quantified backreferences.  See the module docstring for the
+    residual-risk caveats — this is a structural denylist, not a proof of
+    linear-time matching.
+    """
+    if _QUANTIFIED_BACKREF.search(pattern):
+        return True
+    for body, after in _group_bodies_with_following_char(pattern):
+        if after in _QUANTIFIER_OPENERS and _body_is_repeated_unit(body):
+            return True
+    return False