cloud-dog-api-kit 0.13.0__tar.gz → 0.13.2__tar.gz

cloud_dog_api_kit-0.13.2/.docs-manifest.yml

@@ -0,0 +1,6 @@
+schema-version: 1.0
+project: platform-api-kit
+canon-set: PACKAGE
+canon-template-baseline: 1.0
+conditional-docs: []
+additional-docs: []

{cloud_dog_api_kit-0.13.0 → cloud_dog_api_kit-0.13.2}/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.13.2 - 2026-06-05
+- MCP `sync-with-progress` dispatch now allows the full PS-95 five-minute Mode 2
+  sync budget instead of clamping fallback execution to the short 55-second
+  budget. This lets progress-aware clients receive the final tool result for
+  migrated long-call services after the old Traefik timeout window.
+
+## 0.13.1 - 2026-06-05
+- MCP streamable HTTP transport now emits `notifications/progress` SSE frames for
+  `sync-with-progress` tools when the client advertises `text/event-stream`, then
+  returns the final JSON-RPC tool result on the same stream. This fixes W28D-323
+  Mode 2 progress-aware client compatibility for migrated services while keeping
+  stock JSON clients on the existing final-result response path.
+
 ## 0.12.4 - 2026-05-04
 - `WebApiProxy._build_headers` now performs a case-insensitive merge of caller-supplied headers with caller-wins semantics. Previously, Python dict case-sensitivity allowed BOTH `X-API-Key` (the proxy's service key) and `x-api-key` (the caller's forwarded header from FastAPI request iteration) to coexist; httpx emitted both as separate header lines and Starlette's first-match selection caused the service key to override the caller's authenticated identity downstream — breaking RBAC such that any developer making a proxied request impersonated admin. The fix removes any existing case-insensitive duplicate of an incoming header before adding the caller's value, preserving the caller's identity for downstream authorisation. Version skips 0.12.3 because that internal-PyPI release was reverted (untested + bundled an unrelated shared-client change). Resolves the D-RBAC root cause documented in W28A-#A51-REPORT-2026-05-04.md Section D.
 

cloud_dog_api_kit-0.13.2/DATA-MODEL.md

@@ -0,0 +1,33 @@
+---
+template-id: T-PKG-DMT
+template-version: 1.0
+applies-to: DATA-MODEL.md
+registry: package
+required: must-have
+when-applicable: ""
+template-last-updated: 2026-06-12
+template-owner: platform-standards
+
+project: platform-api-kit
+public: true
+doc-last-updated: 2026-06-12
+doc-git-commit: no-git
+doc-git-branch: main
+doc-source-shas: []
+doc-age-policy: indefinite
+doc-conformance-stamp: 2026-06-12T12:00:00Z
+---
+
+# platform-api-kit — DATA-MODEL
+
+> **Template version:** T-PKG-DMT v1.0
+
+## 1. Exported types
+| Type | Shape | Purpose |
+|---|---|---|
+
+## 2. Persisted state
+If the package owns persisted state, describe schema.
+
+## 3. Cross-references
+- [ARCHITECTURE.md](ARCHITECTURE.md)

{cloud_dog_api_kit-0.13.0 → cloud_dog_api_kit-0.13.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cloud-dog-api-kit
-Version: 0.13.0
+Version: 0.13.2
 Summary: PS-20 API toolkit for Cloud-Dog services
 Project-URL: Source, https://github.com/cloud-dog-ai/platform-api-kit
 Author: Cloud-Dog, Viewdeck Engineering Limited

{cloud_dog_api_kit-0.13.0 → cloud_dog_api_kit-0.13.2}/README.md

@@ -133,7 +133,7 @@ pip install cloud-dog-api-kit
   - `ruff check cloud_dog_api_kit tests` -> `All checks passed!`
   - `ruff format --check cloud_dog_api_kit tests examples` -> `143 files already formatted`
   - `python -m build` -> fails in network-restricted environment (isolated `hatchling` install unavailable)
-  - `/opt/iac/Development/cloud-dog-ai/cloud-dog-ai-platform-standards/packages/backend/platform-config/.venv/bin/python -m build --no-isolation` -> built `.tar.gz` and `.whl`
+  - `<platform-config>/.venv/bin/python -m build --no-isolation` -> built `.tar.gz` and `.whl`
 
 ---
 

{cloud_dog_api_kit-0.13.0 → cloud_dog_api_kit-0.13.2}/cloud_dog_api_kit/__init__.py

@@ -33,7 +33,7 @@ Public API:
 
 from __future__ import annotations
 
-__version__ = "0.12.1"
+__version__ = "0.13.2"
 
 
 def create_app(*args, **kwargs):  # type: ignore[no-untyped-def]
@@ -109,6 +109,7 @@ from cloud_dog_api_kit.openapi import configure_openapi
 from cloud_dog_api_kit.versioning import VersionHeaderMiddleware
 from cloud_dog_api_kit.webhook import WebhookSignatureMiddleware, compute_webhook_signature
 from cloud_dog_api_kit.web.proxy import WebApiProxy
+from cloud_dog_api_kit.agent import AgentSession, AgentStrategy, SessionState, parse_prefer_strategy
 
 __all__ = [
     "create_app",

cloud_dog_api_kit-0.13.2/cloud_dog_api_kit/agent/__init__.py

@@ -0,0 +1,11 @@
+"""Agent session lifecycle and strategy parsing (W28B-309, PS-96)."""
+
+from cloud_dog_api_kit.agent.session import AgentSession, SessionState
+from cloud_dog_api_kit.agent.strategy import AgentStrategy, parse_prefer_strategy
+
+__all__ = [
+    "AgentSession",
+    "AgentStrategy",
+    "SessionState",
+    "parse_prefer_strategy",
+]

cloud_dog_api_kit-0.13.2/cloud_dog_api_kit/agent/session.py

@@ -0,0 +1,113 @@
+"""Agent session lifecycle (W28B-309, PS-96 §5).
+
+An AgentSession tracks a multi-turn agent interaction across
+create → (suspend ↔ resume)* → close transitions. Memory
+persistence is delegated to cloud_dog_cache interfaces.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Callable, Optional
+import uuid
+
+
+class SessionState(str, Enum):
+    """Agent session lifecycle states."""
+    CREATED = "created"
+    ACTIVE = "active"
+    SUSPENDED = "suspended"
+    CLOSED = "closed"
+
+
+_TRANSITIONS: dict[SessionState, set[SessionState]] = {
+    SessionState.CREATED: {SessionState.ACTIVE, SessionState.CLOSED},
+    SessionState.ACTIVE: {SessionState.SUSPENDED, SessionState.CLOSED},
+    SessionState.SUSPENDED: {SessionState.ACTIVE, SessionState.CLOSED},
+    SessionState.CLOSED: set(),
+}
+
+
+@dataclass
+class AgentSession:
+    """Lifecycle-managed agent session with memory persistence hooks."""
+
+    session_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    state: SessionState = SessionState.CREATED
+    strategy: Optional[str] = None
+    memory: dict[str, Any] = field(default_factory=dict)
+    created_at: datetime = field(default_factory=lambda: datetime.now(tz=timezone.utc))
+    updated_at: datetime = field(default_factory=lambda: datetime.now(tz=timezone.utc))
+    _on_persist: Optional[Callable[["AgentSession"], None]] = field(default=None, repr=False)
+
+    def _transition(self, target: SessionState) -> None:
+        allowed = _TRANSITIONS.get(self.state, set())
+        if target not in allowed:
+            raise ValueError(f"Invalid transition: {self.state.value} → {target.value}")
+        self.state = target
+        self.updated_at = datetime.now(tz=timezone.utc)
+
+    # ── Lifecycle hooks ──
+
+    def create(self, *, strategy: Optional[str] = None) -> "AgentSession":
+        """Activate a newly created session."""
+        self._transition(SessionState.ACTIVE)
+        if strategy:
+            self.strategy = strategy
+        self._persist()
+        return self
+
+    def suspend(self, *, checkpoint: dict[str, Any] | None = None) -> "AgentSession":
+        """Suspend the session, persisting current memory."""
+        self._transition(SessionState.SUSPENDED)
+        if checkpoint:
+            self.memory["_checkpoint"] = checkpoint
+        self._persist()
+        return self
+
+    def resume(self) -> "AgentSession":
+        """Resume a suspended session."""
+        self._transition(SessionState.ACTIVE)
+        self.memory.pop("_checkpoint", None)
+        self._persist()
+        return self
+
+    def close(self) -> "AgentSession":
+        """Close the session permanently."""
+        self._transition(SessionState.CLOSED)
+        self._persist()
+        return self
+
+    # ── Memory ──
+
+    def set_memory(self, key: str, value: Any) -> None:
+        """Store a value in session memory."""
+        self.memory[key] = value
+        self._persist()
+
+    def get_memory(self, key: str, default: Any = None) -> Any:
+        """Retrieve a value from session memory."""
+        return self.memory.get(key, default)
+
+    # ── Persistence ──
+
+    def set_persist_hook(self, hook: Callable[["AgentSession"], None]) -> None:
+        """Register a persistence callback (e.g., cloud_dog_cache write)."""
+        self._on_persist = hook
+
+    def _persist(self) -> None:
+        if self._on_persist is not None:
+            self._on_persist(self)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise for cache/storage."""
+        return {
+            "session_id": self.session_id,
+            "state": self.state.value,
+            "strategy": self.strategy,
+            "memory": self.memory,
+            "created_at": self.created_at.isoformat(),
+            "updated_at": self.updated_at.isoformat(),
+        }

cloud_dog_api_kit-0.13.2/cloud_dog_api_kit/agent/strategy.py

@@ -0,0 +1,36 @@
+"""Agent strategy selection via Prefer header (W28B-309, PS-96 §3)."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Optional
+
+
+class AgentStrategy(str, Enum):
+    """PS-96 agent execution strategies."""
+    SIMPLE = "simple"
+    REACT = "react"
+    CODEACT = "codeact"
+    SUBAGENT_ROUTER = "subagent_router"
+    RLM = "rlm"
+    REFLEXION = "reflexion"
+
+
+def parse_prefer_strategy(prefer_header: Optional[str]) -> Optional[AgentStrategy]:
+    """Parse agent-strategy from RFC 7240 Prefer header.
+
+    Example: ``Prefer: agent-strategy=react``
+
+    Returns None if no agent-strategy preference found or value unknown.
+    """
+    if not prefer_header:
+        return None
+    for token in prefer_header.split(","):
+        token = token.strip()
+        if token.lower().startswith("agent-strategy="):
+            value = token.split("=", 1)[1].strip().strip('"').lower()
+            try:
+                return AgentStrategy(value)
+            except ValueError:
+                return None
+    return None

{cloud_dog_api_kit-0.13.0 → cloud_dog_api_kit-0.13.2}/cloud_dog_api_kit/mcp/client_sdk.py

@@ -64,9 +64,18 @@ class AsyncJobClient:
             )
         return job_id
 
-    async def wait(self, job_id: str, *, timeout: float | None = None) -> dict[str, Any]:
+    async def wait(
+        self,
+        job_id: str,
+        *,
+        timeout: float | None = None,
+        on_progress: Callable[[float, float | None, str | None], Awaitable[None]] | None = None,
+    ) -> dict[str, Any]:
         """Poll a job until completion or timeout.
 
+        If on_progress is provided, invokes it with (progress_pct, total, message)
+        each time a poll returns progress data (Mode 2 client-side).
+
         Returns the final job status dict with 'result' on success.
         Raises TimeoutError with the job_id if timeout expires.
         """
@@ -74,6 +83,17 @@ class AsyncJobClient:
         while True:
             status = await self._poll_job(job_id)
             state = str(status.get("status", "")).lower()
+
+            # Emit progress if callback provided and status has progress data
+            if on_progress and "progress" in status:
+                prog = status["progress"]
+                if isinstance(prog, dict):
+                    await on_progress(
+                        float(prog.get("percentage", 0)),
+                        prog.get("total"),
+                        prog.get("message"),
+                    )
+
             if state in ("completed", "succeeded"):
                 return status
             if state in ("failed", "cancelled", "timeout", "dead_lettered"):
@@ -109,13 +129,13 @@ class AsyncJobClient:
         if _is_budget_exceeded(response):
             job_id = _extract_job_id_from_error(response)
             if job_id:
-                return await self.wait(job_id, timeout=timeout)
+                return await self.wait(job_id, timeout=timeout, on_progress=on_progress)
             raise ValueError("Budget exceeded but no job_id in error response")
 
         # Async/job_id response (Mode 3)
         job_id = _extract_job_id(response)
         if job_id:
-            return await self.wait(job_id, timeout=timeout)
+            return await self.wait(job_id, timeout=timeout, on_progress=on_progress)
 
         # Fallback: treat entire response as sync result
         return {"status": "completed", "result": response}

{cloud_dog_api_kit-0.13.0 → cloud_dog_api_kit-0.13.2}/cloud_dog_api_kit/mcp/tool_router.py

@@ -45,7 +45,7 @@ SYNC_CLASS_ASYNC = "async-only"
 SYNC_CLASSES = frozenset({SYNC_CLASS_DEFAULT, SYNC_CLASS_PROGRESS, SYNC_CLASS_ASYNC})
 
 DEFAULT_SYNC_BUDGET_SECONDS = 50
-MAX_SYNC_BUDGET_SECONDS = 55
+MAX_SYNC_BUDGET_SECONDS = 300
 
 
 @dataclass(slots=True)

{cloud_dog_api_kit-0.13.0 → cloud_dog_api_kit-0.13.2}/cloud_dog_api_kit/mcp/transport.py

@@ -25,6 +25,7 @@
 
 from __future__ import annotations
 
+import asyncio
 import inspect
 import json
 import sys
@@ -44,7 +45,7 @@ from cloud_dog_api_kit.mcp.async_jobs import AsyncJobStore
 from cloud_dog_api_kit.mcp.error_mapper import map_legacy_mcp_payload
 from cloud_dog_api_kit.mcp.legacy_sse import LegacySSEBroker, LegacySSEConfig
 from cloud_dog_api_kit.mcp.session import SESSION_HEADER, McpSessionManager
-from cloud_dog_api_kit.mcp.tool_router import ToolContract, normalise_tool_registry
+from cloud_dog_api_kit.mcp.tool_router import SYNC_CLASS_PROGRESS, ToolContract, normalise_tool_registry
 
 TransportModes = set[str]
 ToolCallable = Callable[[dict[str, Any], Request], Awaitable[Any] | Any]
@@ -198,6 +199,41 @@ def _mcp_tool_call_payload(result: Any) -> dict[str, Any]:
     return payload
 
 
+def _accepts_event_stream(request: Request) -> bool:
+    return "text/event-stream" in request.headers.get("accept", "").lower()
+
+
+def _sse_frame(data: dict[str, Any], *, event: str | None = None) -> str:
+    lines: list[str] = []
+    if event:
+        lines.append(f"event: {event}")
+    encoded = json.dumps(data, default=str, ensure_ascii=True)
+    for line in encoded.splitlines() or [""]:
+        lines.append(f"data: {line}")
+    return "\n".join(lines) + "\n\n"
+
+
+def _mcp_progress_notification(
+    *,
+    progress_token: str,
+    progress: float,
+    total: float | None,
+    message: str,
+) -> dict[str, Any]:
+    params: dict[str, Any] = {
+        "progressToken": progress_token,
+        "progress": progress,
+        "message": message,
+    }
+    if total is not None:
+        params["total"] = total
+    return {
+        "jsonrpc": "2.0",
+        "method": "notifications/progress",
+        "params": params,
+    }
+
+
 async def _maybe_await(value: Any) -> Any:
     if inspect.isawaitable(value):
         return await value
@@ -289,6 +325,18 @@ async def _resolve_tool_context(
     return context
 
 
+def _progress_token_from_params(params: dict[str, Any], session_id: str, request_id: Any) -> str:
+    meta = params.get("_meta")
+    if isinstance(meta, dict):
+        token = meta.get("progressToken")
+        if token is not None and str(token).strip():
+            return str(token)
+    token = params.get("progressToken")
+    if token is not None and str(token).strip():
+        return str(token)
+    return f"{session_id}:{request_id if request_id is not None else uuid4().hex}"
+
+
 async def _dispatch_payload(
     tools: dict[str, ToolContract],
     payload: dict[str, Any],
@@ -665,6 +713,101 @@ async def _dispatch_payload(
         response.headers["X-Mcp-Session-Created"] = "true" if created else "false"
         return response
 
+    if (
+        payload.get("jsonrpc") == "2.0"
+        and modern_jsonrpc
+        and tool.sync_class == SYNC_CLASS_PROGRESS
+        and wait_value is not False
+        and _accepts_event_stream(request)
+    ):
+        rpc_id = payload.get("id")
+        progress_token = _progress_token_from_params(params, session.session_id, rpc_id)
+        budget_total = max(float(tool.sync_budget_seconds or 0.0), 1.0)
+
+        async def _event_stream() -> Any:
+            started = asyncio.get_running_loop().time()
+            yield _sse_frame(
+                _mcp_progress_notification(
+                    progress_token=progress_token,
+                    progress=0.0,
+                    total=budget_total,
+                    message=f"Started {tool.name}",
+                ),
+                event="message",
+            )
+
+            task = asyncio.create_task(_call_tool(tool, arguments, request, tool_context))
+            last_reported_second = 0
+            try:
+                while not task.done():
+                    await asyncio.sleep(1.0)
+                    elapsed = asyncio.get_running_loop().time() - started
+                    reported_second = int(elapsed)
+                    if reported_second <= last_reported_second:
+                        continue
+                    last_reported_second = reported_second
+                    yield _sse_frame(
+                        _mcp_progress_notification(
+                            progress_token=progress_token,
+                            progress=min(float(elapsed), budget_total),
+                            total=budget_total,
+                            message=f"Running {tool.name}",
+                        ),
+                        event="message",
+                    )
+
+                result = await task
+                yield _sse_frame(
+                    _mcp_progress_notification(
+                        progress_token=progress_token,
+                        progress=budget_total,
+                        total=budget_total,
+                        message=f"Completed {tool.name}",
+                    ),
+                    event="message",
+                )
+                tool_payload = _mcp_tool_call_payload(result)
+                response_payload = _jsonrpc_response(rpc_id, result=tool_payload)
+                if is_messages_path:
+                    response_payload = _messages_compat_payload(
+                        jsonrpc_payload=response_payload,
+                        legacy_result=result,
+                        request_id=request_id,
+                        correlation_id=correlation_id,
+                    )
+                yield _sse_frame(response_payload, event="message")
+            except Exception as exc:
+                if not task.done():
+                    task.cancel()
+                yield _sse_frame(
+                    _mcp_progress_notification(
+                        progress_token=progress_token,
+                        progress=budget_total,
+                        total=budget_total,
+                        message=f"Failed {tool.name}",
+                    ),
+                    event="message",
+                )
+                yield _sse_frame(
+                    _jsonrpc_response(
+                        rpc_id,
+                        error={
+                            "code": -32000,
+                            "message": str(exc) or f"Tool failed: {tool.name}",
+                        },
+                    ),
+                    event="message",
+                )
+
+        response = StreamingResponse(
+            _event_stream(),
+            media_type="text/event-stream",
+            headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
+        )
+        response.headers[SESSION_HEADER] = session.session_id
+        response.headers["X-Mcp-Session-Created"] = "true" if created else "false"
+        return response
+
     result = await _call_tool(tool, arguments, request, tool_context)
     if payload.get("jsonrpc") == "2.0" and modern_jsonrpc:
         tool_payload = _mcp_tool_call_payload(result)

cloud_dog_api_kit-0.13.2/cloud_dog_api_kit/web/__init__.py

@@ -0,0 +1,23 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+# Licensed under the Apache License, Version 2.0
+"""Web server utilities for cloud_dog_api_kit."""
+
+from .proxy import (
+    PRINCIPAL_ROLE_HEADER,
+    PRINCIPAL_SOURCE_HEADER,
+    PRINCIPAL_SOURCE_WEBUI,
+    PRINCIPAL_USER_HEADER,
+    ProxyResponse,
+    SessionPrincipal,
+    WebApiProxy,
+)
+
+__all__ = [
+    "PRINCIPAL_ROLE_HEADER",
+    "PRINCIPAL_SOURCE_HEADER",
+    "PRINCIPAL_SOURCE_WEBUI",
+    "PRINCIPAL_USER_HEADER",
+    "ProxyResponse",
+    "SessionPrincipal",
+    "WebApiProxy",
+]

{cloud_dog_api_kit-0.13.0 → cloud_dog_api_kit-0.13.2}/cloud_dog_api_kit/web/proxy.py

@@ -25,6 +25,11 @@ Related Tests: UT1.XX_WebApiProxy
 
 Recent Changes (max 10):
 - 2026-04-08: W28A-849 — Initial implementation.
+- 2026-06-10: PS-82 §8.3 — canonical session-principal forwarding. Adds the
+    SessionPrincipal carrier + per-call ``principal=`` forwarding so a web-proxy
+    NEVER substitutes its service/service-admin key for a user-originated request
+    (the W28A-890 / notification 3-of-76 identity-collapse defect class). The
+    backend enforces RBAC on the forwarded principal.
 """
 
 from __future__ import annotations
@@ -37,6 +42,44 @@ import httpx
 
 logger = logging.getLogger(__name__)
 
+# --- PS-82 §8.3 canonical session-principal forwarding headers -------------------
+# The ONE canonical set of headers a web-proxy uses to forward the authenticated
+# session principal (identity + role) to the backend. Services MUST NOT invent
+# their own header names — the backend trusts exactly these on the internal hop.
+PRINCIPAL_USER_HEADER = "X-Request-User"
+PRINCIPAL_ROLE_HEADER = "X-Request-Role"
+PRINCIPAL_SOURCE_HEADER = "X-Request-Source"
+#: Marks a request as originating from an authenticated WebUI session (vs a raw
+#: service-to-service call). The backend uses this to require the forwarded
+#: principal instead of materialising the service-key identity.
+PRINCIPAL_SOURCE_WEBUI = "webui"
+
+
+@dataclass(frozen=True, slots=True)
+class SessionPrincipal:
+    """The authenticated WebUI session principal forwarded to the backend (PS-82 §8.3).
+
+    Carries the *user's* identity + role so the backend enforces RBAC on the real
+    caller. A web-proxy MUST construct one of these from the session for EVERY
+    user-originated call site and pass it to the proxy, so the service/service-admin
+    key is never substituted for a user request (the identity-collapse defect).
+    """
+
+    user: str
+    role: str = "user"
+
+    def headers(self) -> dict[str, str]:
+        """Return the canonical forwarding headers for this principal."""
+        user = str(self.user or "").strip()
+        if not user:
+            return {}
+        role = str(self.role or "user").strip().lower() or "user"
+        return {
+            PRINCIPAL_SOURCE_HEADER: PRINCIPAL_SOURCE_WEBUI,
+            PRINCIPAL_USER_HEADER: user,
+            PRINCIPAL_ROLE_HEADER: role,
+        }
+
 
 @dataclass
 class ProxyResponse:
@@ -118,17 +161,28 @@ class WebApiProxy:
         )
 
     def _build_headers(
-        self, extra_headers: Mapping[str, str] | None = None
+        self,
+        extra_headers: Mapping[str, str] | None = None,
+        principal: SessionPrincipal | None = None,
     ) -> dict[str, str]:
-        """Build request headers with API key and optional extras.
+        """Build request headers with API key, optional extras, and session principal.
 
         Caller-supplied headers take precedence on case-insensitive name match,
         so a forwarded X-API-Key from an authenticated user overrides the proxy's
         service key (preserves caller identity for downstream RBAC).
+
+        When ``principal`` is supplied (PS-82 §8.3), the canonical
+        ``X-Request-Source``/``X-Request-User``/``X-Request-Role`` forwarding headers
+        are added so the backend authorises the REAL caller. The proxy's
+        service/service-admin key still travels as the transport credential for the
+        internal hop, but the backend MUST enforce RBAC on the forwarded principal —
+        never collapse the user to the service-admin identity.
         """
         headers: dict[str, str] = {}
         if self._api_key:
             headers[self._api_key_header] = self._api_key
+        if principal is not None:
+            headers.update(principal.headers())
         if extra_headers:
             for incoming_key, incoming_value in extra_headers.items():
                 normalised = incoming_key.lower()
@@ -146,6 +200,7 @@ class WebApiProxy:
         params: dict[str, Any] | None = None,
         headers: Mapping[str, str] | None = None,
         cookies: dict[str, str] | None = None,
+        principal: SessionPrincipal | None = None,
     ) -> ProxyResponse:
         """Send a proxied request to the API server.
 
@@ -156,12 +211,15 @@ class WebApiProxy:
             params: Query parameters.
             headers: Additional headers to forward.
             cookies: Cookies to forward (for session-based auth proxying).
+            principal: The authenticated WebUI session principal (PS-82 §8.3).
+                MUST be supplied for every user-originated call site so the backend
+                enforces RBAC on the real caller instead of the service-admin key.
 
         Returns:
             ProxyResponse with status_code, data, and optional error.
         """
         url = f"{self._base_url}{path}"
-        merged_headers = self._build_headers(headers)
+        merged_headers = self._build_headers(headers, principal=principal)
         try:
             async with httpx.AsyncClient(
                 verify=self._verify_tls,

{cloud_dog_api_kit-0.13.0 → cloud_dog_api_kit-0.13.2}/pyproject.toml

@@ -4,7 +4,7 @@ authors = [
   { name = "Cloud-Dog, Viewdeck Engineering Limited" }
 ]
 name = "cloud-dog-api-kit"
-version = "0.13.0"
+version = "0.13.2"
 description = "PS-20 API toolkit for Cloud-Dog services"
 requires-python = ">=3.10"
 dependencies = [