trustarc-cli 1.0.0__py3-none-any.whl

trustarc_sdk/openapi/__init__.py

@@ -0,0 +1,39 @@
+from trustarc_sdk.openapi.call import Entrypoint, acall, call
+from trustarc_sdk.openapi.feature_manager import (
+    ASK_ARC_CUD_LICENSE_ID,
+    ais_feature_enabled,
+    is_feature_enabled,
+)
+from trustarc_sdk.openapi.parse import (
+    ACTION_VERBS,
+    METHOD_ACTION,
+    base_url_from_spec,
+    detect_namespace_prefix,
+    extract_resource_action,
+    fetch_spec,
+    group_operations_by_resource,
+    iter_operations,
+    resolve_base_url,
+)
+from trustarc_sdk.openapi.schema import build_responses, build_schema_snapshot, resolve_ref
+
+__all__ = [
+    "ACTION_VERBS",
+    "ASK_ARC_CUD_LICENSE_ID",
+    "METHOD_ACTION",
+    "Entrypoint",
+    "acall",
+    "ais_feature_enabled",
+    "base_url_from_spec",
+    "build_responses",
+    "build_schema_snapshot",
+    "call",
+    "is_feature_enabled",
+    "detect_namespace_prefix",
+    "extract_resource_action",
+    "fetch_spec",
+    "group_operations_by_resource",
+    "iter_operations",
+    "resolve_base_url",
+    "resolve_ref",
+]

trustarc_sdk/openapi/call.py

@@ -0,0 +1,204 @@
+import re
+from datetime import datetime, timezone
+from enum import StrEnum
+from urllib.parse import quote
+
+import httpx
+from trustarc_sdk.openapi.feature_manager import (
+    ASK_ARC_CUD_LICENSE_ID,
+    ais_feature_enabled,
+    is_feature_enabled,
+)
+
+
+class Entrypoint(StrEnum):
+    MCP = "mcp"
+    CLI = "cli"
+    ASK_ARC = "ask-arc"
+
+
+_PLACEHOLDER = re.compile(r"\{([^/{}]+)\}")
+_DOT_SEGMENTS = frozenset({".", ".."})
+
+
+def _encode_header_value(value: str) -> str:
+    return quote(value)
+
+
+def _cud_blocked_response(method: str, url: str) -> httpx.Response:
+    return httpx.Response(
+        403,
+        json={"error": "Create or Update or Delete action is not enabled for this account."},
+        request=httpx.Request(method, url),
+    )
+
+
+def _prepare(
+    operation: dict,
+    base_url: str,
+    access_token: str,
+    args: dict | None,
+    user_agent: str | None = None,
+    title: str | None = None,
+    explanation: str | None = None,
+    human_approved: bool = False,
+    thread_id: str | None = None,
+    entrypoint: Entrypoint | None = None,
+    source: str | None = None,
+    path_params: dict | None = None,
+    query_params: dict | None = None,
+    body: dict | list | None = None,
+) -> tuple[str, str, dict, dict | list | None, dict]:
+    method = operation["method"]
+    if path_params is not None or query_params is not None or body is not None:
+        if args:
+            raise TypeError("pass either args or path_params/query_params/body, not both")
+        path_values = dict(path_params or {})
+        query_values = dict(query_params or {})
+        body_fields: dict | list | None = body
+    else:
+        path_values, query_values, body_fields = _classify_by_name(operation, args or {})
+        if not body_fields:
+            body_fields = None
+    if method.upper() == "GET":
+        body_fields = None
+
+    path = _bind_path(operation["path"], path_values)
+    url = f"{base_url.rstrip('/')}{path}"
+    headers: dict = {}
+    if access_token:
+        headers["Authorization"] = f"Bearer {access_token}"
+    if user_agent:
+        headers["User-Agent"] = user_agent
+    if entrypoint:
+        headers["X-TrustArc-Entrypoint"] = entrypoint
+    if source:
+        headers["X-TrustArc-Source"] = source
+    if title:
+        headers["X-TrustArc-Title"] = _encode_header_value(title)
+    if explanation:
+        headers["X-TrustArc-Explanation"] = _encode_header_value(explanation)
+    if human_approved:
+        headers["X-TrustArc-Human-Approved"] = "true"
+    if thread_id:
+        headers["X-TrustArc-Thread-Id"] = thread_id
+    headers["X-TrustArc-Request-Time"] = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+    return method, url, query_values, body_fields, headers
+
+
+def _classify_by_name(operation: dict, args: dict) -> tuple[dict, dict, dict]:
+    path_values: dict = {}
+    query_values: dict = {}
+    body_fields: dict = {}
+    declared = {p["name"]: p for p in operation.get("parameters", [])}
+    for key, value in args.items():
+        param = declared.get(key)
+        if param and param.get("in") == "path":
+            path_values[key] = value
+        elif param and param.get("in") == "query":
+            query_values[key] = value
+        else:
+            body_fields[key] = value
+    return path_values, query_values, body_fields
+
+
+def _bind_path(template: str, path_values: dict) -> str:
+    path = template
+    for name, value in path_values.items():
+        segment = str(value)
+        if segment in _DOT_SEGMENTS:
+            raise ValueError(f"path parameter {name} cannot be {segment!r}")
+        path = path.replace(f"{{{name}}}", quote(segment, safe=""))
+    missing = _PLACEHOLDER.findall(path)
+    if missing:
+        raise ValueError(f"missing path parameter(s): {', '.join(missing)}")
+    return path
+
+
+def call(
+    operation: dict,
+    base_url: str,
+    access_token: str,
+    args: dict | None = None,
+    timeout: float = 60.0,
+    user_agent: str | None = None,
+    title: str | None = None,
+    explanation: str | None = None,
+    human_approved: bool = False,
+    thread_id: str | None = None,
+    entrypoint: Entrypoint | None = None,
+    source: str | None = None,
+    feature_manager_url: str | None = None,
+    feature_id: str = ASK_ARC_CUD_LICENSE_ID,
+    path_params: dict | None = None,
+    query_params: dict | None = None,
+    body: dict | list | None = None,
+) -> httpx.Response:
+    method, url, query_params, body_fields, headers = _prepare(
+        operation,
+        base_url,
+        access_token,
+        args,
+        user_agent,
+        title,
+        explanation,
+        human_approved,
+        thread_id,
+        entrypoint,
+        source,
+        path_params=path_params,
+        query_params=query_params,
+        body=body,
+    )
+    if (
+        method.upper() != "GET"
+        and feature_manager_url
+        and not is_feature_enabled(feature_manager_url, feature_id, access_token)
+    ):
+        return _cud_blocked_response(method, url)
+    return httpx.request(method, url, params=query_params or None, json=body_fields, headers=headers, timeout=timeout)
+
+
+async def acall(
+    operation: dict,
+    base_url: str,
+    access_token: str,
+    args: dict | None = None,
+    timeout: float = 60.0,
+    user_agent: str | None = None,
+    title: str | None = None,
+    explanation: str | None = None,
+    human_approved: bool = False,
+    thread_id: str | None = None,
+    entrypoint: Entrypoint | None = None,
+    source: str | None = None,
+    feature_manager_url: str | None = None,
+    feature_id: str = ASK_ARC_CUD_LICENSE_ID,
+    path_params: dict | None = None,
+    query_params: dict | None = None,
+    body: dict | list | None = None,
+) -> httpx.Response:
+    method, url, query_params, body_fields, headers = _prepare(
+        operation,
+        base_url,
+        access_token,
+        args,
+        user_agent,
+        title,
+        explanation,
+        human_approved,
+        thread_id,
+        entrypoint,
+        source,
+        path_params=path_params,
+        query_params=query_params,
+        body=body,
+    )
+    if (
+        method.upper() != "GET"
+        and feature_manager_url
+        and not await ais_feature_enabled(feature_manager_url, feature_id, access_token)
+    ):
+        return _cud_blocked_response(method, url)
+    async with httpx.AsyncClient(timeout=timeout, follow_redirects=True) as client:
+        return await client.request(method, url, params=query_params or None, json=body_fields, headers=headers)

trustarc_sdk/openapi/feature_manager.py

@@ -0,0 +1,106 @@
+import base64
+import json
+import logging
+import time
+
+import httpx
+
+ASK_ARC_CUD_LICENSE_ID = "ARC_ASK_ARC_CUD"
+
+_DEFAULT_TTL_S = 5 * 60
+_cache: dict[tuple[str, str, str], tuple[float, bool]] = {}
+
+
+def _account_key(access_token: str) -> str:
+    try:
+        payload = access_token.split(".")[1]
+        payload += "=" * (-len(payload) % 4)
+        claims = json.loads(base64.urlsafe_b64decode(payload))
+        return str(claims.get("accountId") or claims.get("account_id") or access_token)
+    except Exception:
+        return access_token
+
+
+def _cache_key(feature_manager_url: str, feature_id: str, access_token: str) -> tuple[str, str, str]:
+    return (feature_manager_url, feature_id, _account_key(access_token))
+
+
+def _cache_get(key: tuple[str, str, str]) -> bool | None:
+    hit = _cache.get(key)
+    if hit is None:
+        return None
+    if hit[0] > time.monotonic():
+        return hit[1]
+    del _cache[key]
+    return None
+
+
+def _cache_set(key: tuple[str, str, str], value: bool, ttl_s: float) -> None:
+    _cache[key] = (time.monotonic() + ttl_s, value)
+
+
+def _url(feature_manager_url: str, feature_id: str) -> str:
+    return f"{feature_manager_url.rstrip('/')}/api/features/{feature_id}"
+
+
+def _parse(data: object, feature_id: str) -> bool:
+    if not isinstance(data, dict):
+        return False
+    return str(data.get(feature_id, "")).lower() == "true"
+
+
+def is_feature_enabled(
+    feature_manager_url: str,
+    feature_id: str,
+    access_token: str,
+    ttl_s: float = _DEFAULT_TTL_S,
+    timeout: float = 10.0,
+) -> bool:
+    if not feature_manager_url or not access_token:
+        return False
+    key = _cache_key(feature_manager_url, feature_id, access_token)
+    cached = _cache_get(key)
+    if cached is not None:
+        return cached
+    try:
+        resp = httpx.get(
+            _url(feature_manager_url, feature_id), headers={"Authorization": f"Bearer {access_token}"}, timeout=timeout
+        )
+        if resp.status_code != 200:
+            logging.warning("feature_manager %s -> %s", feature_id, resp.status_code)
+            return False
+        enabled = _parse(resp.json(), feature_id)
+    except Exception as e:
+        logging.warning("feature_manager lookup failed for %s: %s", feature_id, e)
+        return False
+    _cache_set(key, enabled, ttl_s)
+    return enabled
+
+
+async def ais_feature_enabled(
+    feature_manager_url: str,
+    feature_id: str,
+    access_token: str,
+    ttl_s: float = _DEFAULT_TTL_S,
+    timeout: float = 10.0,
+) -> bool:
+    if not feature_manager_url or not access_token:
+        return False
+    key = _cache_key(feature_manager_url, feature_id, access_token)
+    cached = _cache_get(key)
+    if cached is not None:
+        return cached
+    try:
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            resp = await client.get(
+                _url(feature_manager_url, feature_id), headers={"Authorization": f"Bearer {access_token}"}
+            )
+        if resp.status_code != 200:
+            logging.warning("feature_manager %s -> %s", feature_id, resp.status_code)
+            return False
+        enabled = _parse(resp.json(), feature_id)
+    except Exception as e:
+        logging.warning("feature_manager lookup failed for %s: %s", feature_id, e)
+        return False
+    _cache_set(key, enabled, ttl_s)
+    return enabled

trustarc_sdk/openapi/parse.py

@@ -0,0 +1,207 @@
+from urllib.parse import urlparse
+
+import httpx
+import inflection
+from trustarc_sdk.openapi.feature_manager import ASK_ARC_CUD_LICENSE_ID, is_feature_enabled
+
+ACTION_VERBS = {
+    "new",
+    "create",
+    "update",
+    "patch",
+    "upsert",
+    "merge",
+    "delete",
+    "approve",
+    "reject",
+    "submit",
+    "cancel",
+    "complete",
+    "activate",
+    "deactivate",
+    "enable",
+    "disable",
+    "start",
+    "stop",
+    "pause",
+    "resume",
+    "publish",
+    "unpublish",
+    "lock",
+    "unlock",
+    "send",
+    "trigger",
+    "validate",
+    "verify",
+    "clone",
+    "duplicate",
+    "import",
+    "export",
+    "reset",
+    "refresh",
+}
+
+METHOD_ACTION = {
+    "POST": "create",
+    "PUT": "update",
+    "PATCH": "patch",
+    "DELETE": "delete",
+}
+
+
+def base_url_from_spec(spec_url: str) -> str:
+    parsed = urlparse(spec_url)
+    return f"{parsed.scheme}://{parsed.netloc}"
+
+
+def resolve_base_url(spec: dict, spec_url: str) -> str:
+    servers = spec.get("servers") or []
+    if servers and servers[0].get("url"):
+        url = servers[0]["url"]
+        if url.startswith("http"):
+            return url.rstrip("/")
+        return base_url_from_spec(spec_url).rstrip("/") + "/" + url.lstrip("/")
+    return base_url_from_spec(spec_url)
+
+
+def fetch_spec(spec_url: str) -> dict:
+    response = httpx.get(spec_url, follow_redirects=True, timeout=30)
+    response.raise_for_status()
+    return response.json()
+
+
+def iter_operations(spec: dict):
+    for path, methods in spec.get("paths", {}).items():
+        for method, op in methods.items():
+            if method.lower() not in {"get", "post", "put", "patch", "delete"}:
+                continue
+            wire_method = method.upper()
+            semantic = (op.get("x-semantic-method") or wire_method).upper()
+            yield {
+                "method": wire_method,
+                "semantic_method": semantic,
+                "path": path,
+                "summary": op.get("summary", ""),
+                "description": op.get("description", ""),
+                "parameters": op.get("parameters", []),
+                "request_body": op.get("requestBody"),
+                "responses": op.get("responses") or {},
+                "tags": op.get("tags") or [],
+            }
+
+
+def group_operations_by_resource(
+    spec: dict,
+    namespace_prefix: list[str] | None = None,
+    include_tags: list[str] | None = None,
+    *,
+    feature_manager_url: str | None = None,
+    access_token: str | None = None,
+) -> dict[str, list[tuple[str, dict]]]:
+    prefix = namespace_prefix if namespace_prefix is not None else detect_namespace_prefix(spec)
+    tag_filter = set(include_tags) if include_tags else None
+    cud_enabled = not feature_manager_url or is_feature_enabled(
+        feature_manager_url, ASK_ARC_CUD_LICENSE_ID, access_token or ""
+    )
+    grouped: dict[str, list[tuple[str, dict]]] = {}
+    seen: dict[tuple[str, str], int] = {}
+    for op in iter_operations(spec):
+        if tag_filter and not tag_filter.intersection(op.get("tags") or []):
+            continue
+        if not cud_enabled and op["method"].upper() != "GET":
+            continue
+        resource, action = extract_resource_action(op, namespace_prefix=prefix)
+        key = (resource, action)
+        seen[key] = seen.get(key, 0) + 1
+        if seen[key] > 1:
+            action = f"{action}-{seen[key]}"
+        grouped.setdefault(resource, []).append((action, op))
+    return grouped
+
+
+def detect_namespace_prefix(spec: dict) -> list[str]:
+    paths = list(spec.get("paths", {}).keys())
+    if len(paths) < 2:
+        return []
+    firsts = set()
+    for p in paths:
+        segs = [s for s in p.split("/") if s]
+        if not segs or segs[0].startswith("{"):
+            return []
+        firsts.add(segs[0])
+    return [firsts.pop()] if len(firsts) == 1 else []
+
+
+def extract_resource_action(op: dict, namespace_prefix: list[str] | None = None) -> tuple[str, str]:
+    method = op.get("semantic_method", op["method"]).upper()
+    raw = [s for s in op["path"].split("/") if s]
+
+    segs = list(raw)
+    for p in namespace_prefix or []:
+        if segs and segs[0].lower() == p.lower():
+            segs.pop(0)
+        else:
+            break
+
+    resource_parts: list[str] = []
+    explicit_action: str | None = None
+    trailing_param = False
+
+    i = 0
+    while i < len(segs):
+        seg = segs[i]
+        lower = seg.lower()
+
+        if seg.startswith("{"):
+            trailing_param = True
+            i += 1
+            continue
+
+        trailing_param = False
+
+        if lower in ACTION_VERBS and all(segs[j].startswith("{") for j in range(i + 1, len(segs))):
+            explicit_action = lower
+            trailing_param = any(segs[j].startswith("{") for j in range(i + 1, len(segs)))
+            i = len(segs)
+            break
+
+        resource_parts.append(lower)
+        i += 1
+
+    resource_words: list[str] = []
+    for part in resource_parts:
+        words = _split_words(part)
+        if words:
+            words[-1] = inflection.singularize(words[-1])
+        resource_words.extend(words)
+    resource = "-".join(resource_words) or "root"
+
+    if explicit_action and not trailing_param:
+        action = explicit_action
+    elif method == "GET":
+        action = "get" if trailing_param else "list"
+    else:
+        action = METHOD_ACTION.get(method, method.lower())
+
+    return resource, action
+
+
+def _split_words(name: str) -> list[str]:
+    tokens = name.replace("_", " ").replace("-", " ")
+    words: list[str] = []
+    buf: list[str] = []
+    for ch in tokens:
+        if ch == " ":
+            if buf:
+                words.append("".join(buf))
+                buf = []
+        elif ch.isupper():
+            if buf:
+                words.append("".join(buf))
+                buf = []
+            buf.append(ch.lower())
+        else:
+            buf.append(ch)
+    if buf:
+        words.append("".join(buf))
+    return [w for w in words if w]

trustarc_sdk/openapi/schema.py

@@ -0,0 +1,92 @@
+def resolve_ref(node, spec: dict, seen: set[str] | None = None):
+    seen = seen if seen is not None else set()
+    if isinstance(node, dict):
+        if "$ref" in node and isinstance(node["$ref"], str):
+            ref = node["$ref"]
+            if ref in seen:
+                return {"$ref": ref}
+            if ref.startswith("#/"):
+                parts = ref[2:].split("/")
+                target = spec
+                for p in parts:
+                    target = target.get(p, {}) if isinstance(target, dict) else {}
+                return resolve_ref(target, spec, seen | {ref})
+            return {"$ref": ref}
+        return {k: resolve_ref(v, spec, seen) for k, v in node.items()}
+    if isinstance(node, list):
+        return [resolve_ref(v, spec, seen) for v in node]
+    return node
+
+
+JSON_MIME = "application/json"
+
+
+def _preferred_mime(content: dict) -> str | None:
+    offered = [mime for mime, media in content.items() if "schema" in media]
+    for mime in offered:
+        if mime.split(";")[0].strip() == JSON_MIME:
+            return mime
+    return offered[0] if offered else None
+
+
+def _success_codes(responses: dict) -> list[str]:
+    exact = sorted(c for c in responses if c.isdigit() and c.startswith("2"))
+    return exact + [c for c in ("2XX", "default") if c in responses]
+
+
+def _is_success(code: str) -> bool:
+    return code.startswith("2")
+
+
+def build_responses(op: dict, spec: dict) -> dict:
+    """Every documented status with its description; 2xx entries also carry the resolved schema."""
+    responses: dict = {}
+    for code, response in (op.get("responses") or {}).items():
+        code = str(code)
+        if code.startswith("x-"):
+            continue
+        response = resolve_ref(response or {}, spec)
+        entry: dict = {"description": response.get("description") or ""}
+        if _is_success(code):
+            content = response.get("content") or {}
+            mime = _preferred_mime(content)
+            if mime:
+                entry["content_type"] = mime
+                entry["schema"] = resolve_ref(content[mime]["schema"], spec)
+        responses[code] = entry
+    return responses
+
+
+def build_schema_snapshot(op: dict, spec: dict) -> dict:
+    snapshot: dict = {
+        "method": op["method"],
+        "path": op["path"],
+        "summary": op.get("summary") or "",
+        "description": op.get("description") or "",
+        "parameters": [resolve_ref(p, spec) for p in op.get("parameters") or []],
+    }
+    body = op.get("request_body")
+    if body:
+        content = body.get("content") or {}
+        mime = _preferred_mime(content)
+        if mime:
+            snapshot["request_body"] = {
+                "content_type": mime,
+                "required": body.get("required", False),
+                "schema": resolve_ref(content[mime]["schema"], spec),
+            }
+    responses = {str(c): r for c, r in (op.get("responses") or {}).items()}
+    for code in _success_codes(responses):
+        content = responses[code].get("content") or {}
+        for mime, media in content.items():
+            if "schema" in media:
+                snapshot["response"] = {
+                    "status": code,
+                    "content_type": mime,
+                    "schema": resolve_ref(media["schema"], spec),
+                }
+                break
+        if "response" in snapshot:
+            break
+    snapshot["responses"] = build_responses(op, spec)
+    return snapshot