cloud-dog-api-kit 0.13.0__py3-none-any.whl

cloud_dog_api_kit/a2a/gateway.py

@@ -0,0 +1,105 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — A2A gateway helpers
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Helpers for mapping REST endpoints to A2A handlers.
+#   A2A endpoints MUST be thin wrappers over REST calls.
+# Related requirements: FR15.1
+# Related architecture: CC1.18
+
+"""A2A gateway helpers for cloud_dog_api_kit."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class A2AHandler:
+    """A2A handler definition mapped from a REST endpoint.
+
+    Attributes:
+        name: The handler name.
+        description: Human-readable description.
+        endpoint_path: The REST endpoint path this handler wraps.
+        method: HTTP method. Defaults to ``POST``.
+        input_schema: JSON Schema for the handler's input.
+        output_schema: JSON Schema for the handler's output.
+
+    Related tests: UT1.33_A2AGateway
+    """
+
+    name: str
+    description: str
+    endpoint_path: str
+    method: str = "POST"
+    input_schema: dict[str, Any] = field(default_factory=dict)
+    output_schema: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to a dictionary suitable for A2A registration.
+
+        Returns:
+            A dictionary with the handler definition.
+        """
+        return {
+            "name": self.name,
+            "description": self.description,
+            "endpoint_path": self.endpoint_path,
+            "method": self.method,
+            "inputSchema": self.input_schema,
+            "outputSchema": self.output_schema,
+        }
+
+
+def create_a2a_handler_from_endpoint(
+    endpoint_path: str,
+    method: str = "POST",
+    description: str = "",
+    name: str | None = None,
+    input_schema: dict[str, Any] | None = None,
+    output_schema: dict[str, Any] | None = None,
+) -> A2AHandler:
+    """Create an A2A handler from a REST endpoint.
+
+    Args:
+        endpoint_path: The REST endpoint path.
+        method: HTTP method. Defaults to ``POST``.
+        description: Handler description.
+        name: Override handler name. Derived from path if None.
+        input_schema: JSON Schema for inputs.
+        output_schema: JSON Schema for outputs.
+
+    Returns:
+        An A2AHandler instance.
+
+    Related tests: UT1.33_A2AGateway
+    """
+    if name is None:
+        parts = endpoint_path.strip("/").split("/")
+        filtered = [p for p in parts if not p.startswith("{") and p not in ("api", "v1", "v2")]
+        name = "_".join(filtered).replace(":", "_")
+
+    return A2AHandler(
+        name=name,
+        description=description,
+        endpoint_path=endpoint_path,
+        method=method,
+        input_schema=input_schema or {},
+        output_schema=output_schema or {},
+    )

cloud_dog_api_kit/a2a/skill_audit.py

@@ -0,0 +1,107 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""A2A skill audit middleware for PS-50 compliance.
+
+License: Apache 2.0
+Ownership: Cloud-Dog, Viewdeck Engineering Limited
+Description: Wraps A2A skill handlers with structured audit logging.
+Requirements: PS-50.AUD2
+Tasks: W28A-737
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Callable, Optional
+
+
+def a2a_skill_audit_middleware(
+    skill_name: str,
+    handler: Callable,
+    *,
+    service: str,
+    logger: Optional[logging.Logger] = None,
+) -> Callable:
+    """Wrap an A2A skill handler to emit audit log entries for every invocation.
+
+    Args:
+        skill_name: The name of the A2A skill being wrapped.
+        handler: The original skill handler callable.
+        service: The emitting service name (e.g. ``"file-mcp-server"``).
+        logger: Optional logger instance. Falls back to stdlib logging.
+
+    Returns:
+        A wrapped handler that logs audit entries for each skill invocation.
+
+    Audit record fields:
+        - correlation_id
+        - service
+        - skill_name (which skill was invoked)
+        - actor (requesting agent or user)
+        - task_id (A2A task ID)
+        - outcome ("success" | "error")
+        - duration_ms
+        - timestamp
+        - error_detail (if outcome is "error")
+    """
+    log = logger or logging.getLogger(f"cloud_dog_api_kit.a2a.audit.{service}")
+
+    def _wrapped(text: str, *, task_id: str = "", actor: str = "a2a-caller", **kwargs: Any) -> Any:
+        correlation_id = task_id or str(uuid.uuid4().hex[:16])
+        ts = datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+        t0 = time.monotonic()
+        try:
+            result = handler(text, **kwargs)
+            duration_ms = round((time.monotonic() - t0) * 1000, 2)
+            log.info(
+                "a2a_skill_invocation",
+                extra={
+                    "event_type": "a2a_skill_invocation",
+                    "correlation_id": correlation_id,
+                    "service": service,
+                    "skill_name": skill_name,
+                    "actor": actor,
+                    "task_id": task_id,
+                    "outcome": "success",
+                    "duration_ms": duration_ms,
+                    "timestamp": ts,
+                },
+            )
+            return result
+        except Exception as exc:
+            duration_ms = round((time.monotonic() - t0) * 1000, 2)
+            log.warning(
+                "a2a_skill_invocation",
+                extra={
+                    "event_type": "a2a_skill_invocation",
+                    "correlation_id": correlation_id,
+                    "service": service,
+                    "skill_name": skill_name,
+                    "actor": actor,
+                    "task_id": task_id,
+                    "outcome": "error",
+                    "duration_ms": duration_ms,
+                    "timestamp": ts,
+                    "error_detail": str(exc),
+                },
+            )
+            raise
+
+    _wrapped.__name__ = handler.__name__ if hasattr(handler, "__name__") else skill_name
+    _wrapped.__doc__ = handler.__doc__
+    return _wrapped

cloud_dog_api_kit/auth/__init__.py

@@ -0,0 +1,35 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — Authentication and authorisation
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Auth dependency, RBAC helpers, and tenant isolation.
+# Related requirements: FR3.1, FR3.2, FR3.3, FR3.4, FR3.5
+# Related architecture: CC1.5, CC1.6
+
+"""Authentication and authorisation for cloud_dog_api_kit."""
+
+from cloud_dog_api_kit.auth.dependency import create_auth_dependency
+from cloud_dog_api_kit.auth.rbac import require_admin, require_permission, require_tenant
+from cloud_dog_api_kit.auth.service_auth import create_service_auth_dependency
+
+__all__ = [
+    "create_auth_dependency",
+    "create_service_auth_dependency",
+    "require_admin",
+    "require_permission",
+    "require_tenant",
+]

cloud_dog_api_kit/auth/dependency.py

@@ -0,0 +1,121 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — Authentication dependency for FastAPI
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: FastAPI dependency factory for API key / Bearer authentication.
+#   Supports both API key and Bearer token with configurable verify functions.
+# Related requirements: FR3.4, FR3.5
+# Related architecture: CC1.5
+
+"""Authentication dependency factory for FastAPI."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from fastapi import Request
+
+from cloud_dog_api_kit.errors.exceptions import UnauthenticatedError
+
+
+def create_auth_dependency(
+    api_key_header: str = "X-API-Key",
+    bearer_verify_fn: Callable | None = None,
+    api_key_verify_fn: Callable | None = None,
+    config_api_key: str | None = None,
+) -> Callable:
+    """Create a FastAPI dependency for API key / Bearer authentication.
+
+    The dependency tries Bearer token first, then falls back to API key.
+    On success, sets ``request.state.user``, ``request.state.api_key``,
+    and ``request.state.tenant_id``.
+
+    Args:
+        api_key_header: Header name for API key. Defaults to ``X-API-Key``.
+        bearer_verify_fn: Async/sync callable to verify Bearer tokens.
+            Should return a dict with ``user_id``, ``roles``, ``tenant_id``.
+        api_key_verify_fn: Async/sync callable to verify API keys.
+            Should return a dict with ``user_id``, ``roles``, ``tenant_id``.
+        config_api_key: Static API key from config for simple verification.
+
+    Returns:
+        A FastAPI dependency callable.
+
+    Related tests: UT1.6_AuthDependency, UT1.7_BearerAuth, UT1.10_ServiceAuth
+    """
+
+    async def _auth_dependency(request: Request) -> dict[str, Any]:
+        # Try Bearer token first
+        auth_header = request.headers.get("authorization", "")
+        if auth_header.startswith("Bearer "):
+            token = auth_header[7:].strip()
+            if not token:
+                raise UnauthenticatedError(message="Empty Bearer token")
+            if bearer_verify_fn is not None:
+                import asyncio
+
+                if asyncio.iscoroutinefunction(bearer_verify_fn):
+                    result = await bearer_verify_fn(token)
+                else:
+                    result = bearer_verify_fn(token)
+                if result is None:
+                    raise UnauthenticatedError(message="Invalid Bearer token")
+                _set_request_state(request, result)
+                return result
+            raise UnauthenticatedError(message="Bearer token verification not configured")
+
+        # Try API key
+        api_key = request.headers.get(api_key_header.lower(), "") or request.headers.get(api_key_header, "")
+        if not api_key:
+            raise UnauthenticatedError(message="Missing credentials")
+
+        if api_key_verify_fn is not None:
+            import asyncio
+
+            if asyncio.iscoroutinefunction(api_key_verify_fn):
+                result = await api_key_verify_fn(api_key)
+            else:
+                result = api_key_verify_fn(api_key)
+            if result is None:
+                raise UnauthenticatedError(message="Invalid API key")
+            _set_request_state(request, result)
+            return result
+
+        # Fall back to config-based verification
+        if config_api_key is not None:
+            if api_key == config_api_key:
+                result = {"user_id": "api_key_user", "roles": [], "tenant_id": None}
+                _set_request_state(request, result)
+                return result
+            raise UnauthenticatedError(message="Invalid API key")
+
+        raise UnauthenticatedError(message="No authentication method configured")
+
+    return _auth_dependency
+
+
+def _set_request_state(request: Request, auth_result: dict[str, Any]) -> None:
+    """Set authentication result on request state.
+
+    Args:
+        request: The FastAPI request.
+        auth_result: Dict with user_id, roles, tenant_id.
+    """
+    request.state.user = auth_result.get("user_id")
+    request.state.api_key = True
+    request.state.tenant_id = auth_result.get("tenant_id")
+    request.state.roles = auth_result.get("roles", [])

cloud_dog_api_kit/auth/rbac.py

@@ -0,0 +1,107 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — RBAC helpers
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Role-based access control helpers for endpoint-level authorisation.
+#   Default-deny: all endpoints require auth unless explicitly marked public.
+# Related requirements: FR3.3
+# Related architecture: CC1.6
+
+"""RBAC helpers for cloud_dog_api_kit."""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from fastapi import Request
+
+from cloud_dog_api_kit.errors.exceptions import UnauthorisedError
+
+
+def require_permission(permission: str) -> Callable:
+    """Create a FastAPI dependency that checks for a specific permission.
+
+    Args:
+        permission: The required permission string.
+
+    Returns:
+        A FastAPI dependency callable that raises UnauthorisedError if
+        the user does not have the required permission.
+
+    Related tests: UT1.8_RBACHelpers, SEC1.2_RBACEnforcement
+    """
+
+    async def _check(request: Request) -> None:
+        roles = getattr(request.state, "roles", []) or []
+        permissions = getattr(request.state, "permissions", []) or []
+        all_perms = set(roles) | set(permissions)
+        if permission not in all_perms:
+            raise UnauthorisedError(message=f"Missing required permission: {permission}")
+
+    return _check
+
+
+def require_admin() -> Callable:
+    """Create a FastAPI dependency that checks for admin role.
+
+    Returns:
+        A FastAPI dependency callable that raises UnauthorisedError if
+        the user does not have the admin role.
+
+    Related tests: UT1.8_RBACHelpers, SEC1.2_RBACEnforcement
+    """
+
+    async def _check(request: Request) -> None:
+        roles = getattr(request.state, "roles", []) or []
+        if "admin" not in roles:
+            raise UnauthorisedError(message="Admin access required")
+
+    return _check
+
+
+def require_tenant(tenant_id_param: str = "tenant_id") -> Callable:
+    """Create a FastAPI dependency that enforces tenant isolation.
+
+    Checks that the authenticated user's tenant_id matches the requested
+    tenant_id from the path or query parameters.
+
+    Args:
+        tenant_id_param: The name of the path/query parameter containing
+            the tenant ID. Defaults to ``tenant_id``.
+
+    Returns:
+        A FastAPI dependency callable that raises UnauthorisedError on
+        tenant mismatch.
+
+    Related tests: UT1.9_TenantIsolation, SEC1.3_TenantIsolation
+    """
+
+    async def _check(request: Request) -> None:
+        user_tenant = getattr(request.state, "tenant_id", None)
+        if user_tenant is None:
+            return  # No tenant context — skip check
+
+        # Check path params
+        requested_tenant = request.path_params.get(tenant_id_param)
+        if requested_tenant is None:
+            # Check query params
+            requested_tenant = request.query_params.get(tenant_id_param)
+
+        if requested_tenant is not None and requested_tenant != user_tenant:
+            raise UnauthorisedError(message="Access denied: tenant mismatch")
+
+    return _check

cloud_dog_api_kit/auth/service_auth.py

@@ -0,0 +1,54 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — Service-to-service authentication
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Service-to-service auth using X-App-Id + service key.
+# Related requirements: FR3.5
+# Related architecture: SA1
+
+"""Service-to-service authentication helpers."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from fastapi import Header
+
+from cloud_dog_api_kit.errors.exceptions import UnauthenticatedError
+
+
+def create_service_auth_dependency(
+    service_key_verify_fn: Callable[[str, str], dict[str, Any] | None],
+    app_id_header: str = "X-App-Id",
+    key_header: str = "X-Service-Key",
+) -> Callable:
+    """Create a dependency enforcing service-to-service authentication."""
+
+    async def _dep(
+        app_id: str | None = Header(default=None, alias=app_id_header),
+        service_key: str | None = Header(default=None, alias=key_header),
+    ) -> dict[str, Any]:
+        if not app_id or not service_key:
+            raise UnauthenticatedError(message="Missing service credentials")
+
+        result = service_key_verify_fn(app_id, service_key)
+        if result is None:
+            raise UnauthenticatedError(message="Invalid service credentials")
+
+        return result
+
+    return _dep

cloud_dog_api_kit/clients/__init__.py

@@ -0,0 +1,29 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — HTTP client helpers
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Service-to-service HTTP client creation and retry utilities.
+# Related requirements: FR9.1, FR9.2
+# Related architecture: SA1
+
+"""HTTP client helpers for cloud_dog_api_kit."""
+
+from __future__ import annotations
+
+from cloud_dog_api_kit.clients.http_client import ClientTimeout, RetryPolicy, create_http_client
+
+__all__ = ["ClientTimeout", "RetryPolicy", "create_http_client"]

cloud_dog_api_kit/clients/circuit_breaker.py

@@ -0,0 +1,39 @@
+# Copyright 2026 Cloud-Dog, Viewdeck Engineering Limited
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# cloud_dog_api_kit — Circuit breaker hook (optional)
+#
+# Licence: Proprietary — Cloud-Dog AI Platform
+# Owner: Cloud-Dog AI
+# Description: Optional circuit breaker hooks for HTTP client integrations.
+# Related requirements: FR9.1
+# Related architecture: SA1
+
+"""Circuit breaker hooks for cloud_dog_api_kit."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class CircuitBreaker(Protocol):
+    """Optional circuit breaker protocol."""
+
+    def on_success(self) -> None:
+        """Record a successful protected call."""
+        ...
+
+    def on_failure(self) -> None:
+        """Record a failed protected call."""
+        ...