asap-protocol 0.3.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

asap/models/parts.py

@@ -14,6 +14,10 @@ from pydantic import Discriminator, Field, TypeAdapter, field_validator
 from asap.models.base import ASAPBaseModel
 from asap.models.types import MIMEType
 
+# Security: reject URIs that could lead to path traversal or local file access
+PATH_TRAVERSAL_PATTERN = re.compile(r"\.\.")
+FILE_URI_PREFIX = "file://"
+
 
 class TextPart(ASAPBaseModel):
     """Plain text content part.
@@ -70,7 +74,7 @@ class FilePart(ASAPBaseModel):
 
     Attributes:
         type: Discriminator field, always "file"
-        uri: File URI (can be asap://, file://, https://, or data: URI)
+        uri: File URI (asap://, https://, or data:; file:// and path traversal rejected)
         mime_type: MIME type of the file (e.g., "application/pdf")
         inline_data: Optional base64-encoded inline file data
 
@@ -91,12 +95,38 @@ class FilePart(ASAPBaseModel):
     """
 
     type: Literal["file"] = Field(..., description="Part type discriminator")
-    uri: str = Field(..., description="File URI (asap://, file://, https://, data:)")
+    uri: str = Field(
+        ...,
+        description="File URI (asap://, https://, data:; file:// and .. rejected)",
+    )
     mime_type: MIMEType = Field(..., description="MIME type (e.g., application/pdf)")
     inline_data: str | None = Field(
         default=None, description="Optional base64-encoded inline file data"
     )
 
+    @field_validator("uri")
+    @classmethod
+    def validate_uri(cls, v: str) -> str:
+        """Validate URI: reject path traversal and suspicious file:// URIs.
+
+        Rejects URIs containing '..' (path traversal) and file:// URIs
+        to prevent reading arbitrary server paths from user-supplied input.
+
+        Args:
+            v: URI string to validate
+
+        Returns:
+            The same URI if valid
+
+        Raises:
+            ValueError: If URI contains path traversal or is a file:// URI
+        """
+        if PATH_TRAVERSAL_PATTERN.search(v):
+            raise ValueError(f"URI must not contain path traversal (..): {v!r}")
+        if v.strip().lower().startswith(FILE_URI_PREFIX):
+            raise ValueError("file:// URIs are not allowed for security (path traversal risk)")
+        return v
+
     @field_validator("mime_type")
     @classmethod
     def validate_mime_type(cls, v: str) -> str:
@@ -201,7 +231,7 @@ Example:
     >>> # Deserializes to FilePart
     >>> file_part = Part.validate_python({
     ...     "type": "file",
-    ...     "uri": "file://test.pdf",
+    ...     "uri": "https://example.com/doc.pdf",
     ...     "mime_type": "application/pdf"
     ... })
 """

asap/models/validators.py

@@ -0,0 +1,16 @@
+"""Shared validators for ASAP protocol models."""
+
+import re
+
+from asap.models.constants import AGENT_URN_PATTERN, MAX_URN_LENGTH
+
+_AGENT_URN_RE = re.compile(AGENT_URN_PATTERN)
+
+
+def validate_agent_urn(v: str) -> str:
+    """Validate agent URN format and length (pattern + max length)."""
+    if len(v) > MAX_URN_LENGTH:
+        raise ValueError(f"Agent URN must be at most {MAX_URN_LENGTH} characters, got {len(v)}")
+    if not _AGENT_URN_RE.match(v):
+        raise ValueError(f"Agent ID must follow URN format 'urn:asap:agent:{{name}}', got: {v}")
+    return v

asap/observability/__init__.py

@@ -25,6 +25,9 @@ from asap.observability.logging import (
     clear_context,
     configure_logging,
     get_logger,
+    is_debug_log_mode,
+    is_debug_mode,
+    sanitize_for_logging,
 )
 from asap.observability.metrics import (
     MetricsCollector,
@@ -38,6 +41,9 @@ __all__ = [
     "configure_logging",
     "get_logger",
     "get_metrics",
+    "is_debug_log_mode",
+    "is_debug_mode",
     "reset_metrics",
     "MetricsCollector",
+    "sanitize_for_logging",
 ]

asap/observability/dashboards/README.md

@@ -0,0 +1,24 @@
+# ASAP Grafana Dashboards
+
+Pre-built dashboards for ASAP Protocol observability. Use with Prometheus scraping the `/asap/metrics` endpoint.
+
+## Dashboards
+
+- **asap-red.json** – RED metrics (Request rate, Error rate, Duration/latency) for ASAP requests.
+- **asap-detailed.json** – Topology, state machine transitions, and circuit breaker status.
+
+## Setup
+
+1. Configure a Prometheus datasource in Grafana (scrape ASAP server at `http://<asap-host>:<port>/asap/metrics`).
+2. **Provisioning**: Copy the JSON files to Grafana's provisioning path, e.g.:
+   - Copy to `<grafana provisioning dir>/dashboards/asap/` and set the provisioning config to load from that directory.
+   - Or import manually: Grafana UI → Dashboards → Import → Upload JSON file.
+3. Select the Prometheus datasource when prompted.
+
+## Metrics used
+
+- `asap_requests_total` – Total requests (labels: `payload_type`, `status`).
+- `asap_requests_error_total` – Failed requests.
+- `asap_request_duration_seconds` – Request latency histogram.
+- `asap_state_transitions_total` – State machine transitions (labels: `from_status`, `to_status`).
+- `asap_circuit_breaker_open` – Circuit open state (if exposed by client metrics).

asap/observability/dashboards/asap-detailed.json

@@ -0,0 +1,131 @@
+{
+  "annotations": { "list": [] },
+  "editable": true,
+  "fiscalYearStartMonth": 0,
+  "graphTooltip": 1,
+  "id": null,
+  "links": [],
+  "liveNow": false,
+  "panels": [
+    {
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "description": "Handler executions per second by payload type (activity view)",
+      "fieldConfig": {
+        "defaults": {
+          "color": { "mode": "palette-classic" },
+          "custom": { "axisCenteredZero": false, "axisColorMode": "text", "axisLabel": "", "axisPlacement": "auto", "barAlignment": 0, "drawStyle": "line", "fillOpacity": 10, "gradientMode": "none", "hideFrom": { "legend": false, "tooltip": false, "viz": false }, "lineInterpolation": "linear", "lineWidth": 1, "pointSize": 5, "scaleDistribution": { "type": "linear" }, "showPoints": "auto", "spanNulls": false, "stacking": { "group": "A", "mode": "normal" }, "thresholdsStyle": { "mode": "off" } },
+          "unit": "reqps"
+        },
+        "overrides": []
+      },
+      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 0 },
+      "id": 10,
+      "options": { "legend": { "displayMode": "list", "placement": "bottom", "showLegend": true } },
+      "targets": [
+        {
+          "expr": "sum(rate(asap_handler_executions_total[1m])) by (payload_type)",
+          "legendFormat": "{{payload_type}}",
+          "refId": "A"
+        }
+      ],
+      "title": "Handler executions (by payload type)",
+      "type": "timeseries"
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "description": "Task state machine transition rate by from_state and to_state",
+      "fieldConfig": {
+        "defaults": {
+          "color": { "mode": "palette-classic" },
+          "custom": { "axisCenteredZero": false, "axisColorMode": "text", "axisLabel": "", "axisPlacement": "auto", "barAlignment": 0, "drawStyle": "line", "fillOpacity": 10, "gradientMode": "none", "hideFrom": { "legend": false, "tooltip": false, "viz": false }, "lineInterpolation": "linear", "lineWidth": 1, "pointSize": 5, "scaleDistribution": { "type": "linear" }, "showPoints": "auto", "spanNulls": false, "stacking": { "group": "A", "mode": "none" }, "thresholdsStyle": { "mode": "off" } },
+          "unit": "reqps"
+        },
+        "overrides": []
+      },
+      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 0 },
+      "id": 11,
+      "options": { "legend": { "displayMode": "list", "placement": "bottom", "showLegend": true } },
+      "targets": [
+        {
+          "expr": "sum(rate(asap_state_transitions_total[1m])) by (from_status, to_status)",
+          "legendFormat": "{{from_status}} → {{to_status}}",
+          "refId": "A"
+        }
+      ],
+      "title": "State transitions",
+      "type": "timeseries"
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "description": "Circuit breaker open state (1 = open). Requires asap_circuit_breaker_open metric from client.",
+      "fieldConfig": {
+        "defaults": {
+          "color": { "mode": "thresholds" },
+          "mappings": [
+            { "options": { "0": { "color": "green", "index": 0, "text": "closed" } }, "type": "value" },
+            { "options": { "1": { "color": "red", "index": 0, "text": "open" } }, "type": "value" }
+          ],
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              { "color": "green", "value": null },
+              { "color": "red", "value": 1 }
+            ]
+          },
+          "unit": "short"
+        },
+        "overrides": []
+      },
+      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 8 },
+      "id": 12,
+      "options": { "colorMode": "value", "graphMode": "none", "justifyMode": "auto", "orientation": "auto", "reduceOptions": { "calcs": ["lastNotNull"], "fields": "", "values": false }, "textMode": "auto" },
+      "targets": [
+        {
+          "expr": "asap_circuit_breaker_open",
+          "legendFormat": "{{instance}}",
+          "refId": "A"
+        }
+      ],
+      "title": "Circuit breaker status",
+      "type": "stat"
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "description": "State transition rate as table (from_state, to_state, rate)",
+      "fieldConfig": {
+        "defaults": {
+          "color": { "mode": "palette-classic" },
+          "custom": { "align": "auto", "cellOptions": { "type": "auto" }, "inspect": false },
+          "mappings": [],
+          "unit": "reqps"
+        },
+        "overrides": []
+      },
+      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 8 },
+      "id": 13,
+      "options": { "cellHeight": "sm", "footer": { "countRows": false, "fields": "", "reducer": ["sum"], "show": false }, "showHeader": true, "sortBy": [] },
+      "targets": [
+        {
+          "expr": "sum(rate(asap_state_transitions_total[1m])) by (from_status, to_status)",
+          "format": "table",
+          "instant": true,
+          "refId": "A"
+        }
+      ],
+      "title": "State transitions (table)",
+      "type": "table"
+    }
+  ],
+  "refresh": "10s",
+  "schemaVersion": 38,
+  "style": "dark",
+  "tags": ["asap", "detailed", "state-machine"],
+  "templating": { "list": [] },
+  "time": { "from": "now-1h", "to": "now" },
+  "timepicker": {},
+  "timezone": "utc",
+  "title": "ASAP Detailed (topology & state)",
+  "uid": "asap-detailed",
+  "version": 1,
+  "weekStart": ""
+}

asap/observability/dashboards/asap-red.json

@@ -0,0 +1,129 @@
+{
+  "annotations": { "list": [] },
+  "editable": true,
+  "fiscalYearStartMonth": 0,
+  "graphTooltip": 1,
+  "id": null,
+  "links": [],
+  "liveNow": false,
+  "panels": [
+    {
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "description": "Requests per second by payload type",
+      "fieldConfig": {
+        "defaults": {
+          "color": { "mode": "palette-classic" },
+          "custom": { "axisCenteredZero": false, "axisColorMode": "text", "axisLabel": "", "axisPlacement": "auto", "barAlignment": 0, "drawStyle": "line", "fillOpacity": 10, "gradientMode": "none", "hideFrom": { "legend": false, "tooltip": false, "viz": false }, "lineInterpolation": "linear", "lineWidth": 1, "pointSize": 5, "scaleDistribution": { "type": "linear" }, "showPoints": "auto", "spanNulls": false, "stacking": { "group": "A", "mode": "none" }, "thresholdsStyle": { "mode": "off" } },
+          "unit": "reqps"
+        },
+        "overrides": []
+      },
+      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 0 },
+      "id": 1,
+      "options": { "legend": { "displayMode": "list", "placement": "bottom", "showLegend": true } },
+      "targets": [
+        {
+          "expr": "sum(rate(asap_requests_total[1m])) by (payload_type)",
+          "legendFormat": "{{payload_type}}",
+          "refId": "A"
+        }
+      ],
+      "title": "Request Rate",
+      "type": "timeseries"
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "description": "Error rate: errors / total requests",
+      "fieldConfig": {
+        "defaults": {
+          "color": { "mode": "thresholds" },
+          "mappings": [],
+          "max": 1,
+          "min": 0,
+          "thresholds": {
+            "mode": "absolute",
+            "steps": [
+              { "color": "green", "value": null },
+              { "color": "yellow", "value": 0.01 },
+              { "color": "red", "value": 0.05 }
+            ]
+          },
+          "unit": "percentunit"
+        },
+        "overrides": []
+      },
+      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 0 },
+      "id": 2,
+      "options": { "legend": { "displayMode": "list", "placement": "bottom", "showLegend": true } },
+      "targets": [
+        {
+          "expr": "sum(rate(asap_requests_error_total[1m])) / (sum(rate(asap_requests_total[1m])) + 1e-9)",
+          "legendFormat": "Error rate",
+          "refId": "A"
+        }
+      ],
+      "title": "Error Rate",
+      "type": "timeseries"
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "description": "95th percentile request duration",
+      "fieldConfig": {
+        "defaults": {
+          "color": { "mode": "palette-classic" },
+          "custom": { "axisCenteredZero": false, "axisColorMode": "text", "axisLabel": "", "axisPlacement": "auto", "barAlignment": 0, "drawStyle": "line", "fillOpacity": 10, "gradientMode": "none", "hideFrom": { "legend": false, "tooltip": false, "viz": false }, "lineInterpolation": "linear", "lineWidth": 1, "pointSize": 5, "scaleDistribution": { "type": "linear" }, "showPoints": "auto", "spanNulls": false, "stacking": { "group": "A", "mode": "none" }, "thresholdsStyle": { "mode": "off" } },
+          "unit": "s"
+        },
+        "overrides": []
+      },
+      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 8 },
+      "id": 3,
+      "options": { "legend": { "displayMode": "list", "placement": "bottom", "showLegend": true } },
+      "targets": [
+        {
+          "expr": "histogram_quantile(0.95, sum(rate(asap_request_duration_seconds_bucket[1m])) by (le))",
+          "legendFormat": "p95",
+          "refId": "A"
+        }
+      ],
+      "title": "Latency (p95)",
+      "type": "timeseries"
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "prometheus" },
+      "description": "99th percentile request duration",
+      "fieldConfig": {
+        "defaults": {
+          "color": { "mode": "palette-classic" },
+          "custom": { "axisCenteredZero": false, "axisColorMode": "text", "axisLabel": "", "axisPlacement": "auto", "barAlignment": 0, "drawStyle": "line", "fillOpacity": 10, "gradientMode": "none", "hideFrom": { "legend": false, "tooltip": false, "viz": false }, "lineInterpolation": "linear", "lineWidth": 1, "pointSize": 5, "scaleDistribution": { "type": "linear" }, "showPoints": "auto", "spanNulls": false, "stacking": { "group": "A", "mode": "none" }, "thresholdsStyle": { "mode": "off" } },
+          "unit": "s"
+        },
+        "overrides": []
+      },
+      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 8 },
+      "id": 4,
+      "options": { "legend": { "displayMode": "list", "placement": "bottom", "showLegend": true } },
+      "targets": [
+        {
+          "expr": "histogram_quantile(0.99, sum(rate(asap_request_duration_seconds_bucket[1m])) by (le))",
+          "legendFormat": "p99",
+          "refId": "A"
+        }
+      ],
+      "title": "Latency (p99)",
+      "type": "timeseries"
+    }
+  ],
+  "refresh": "10s",
+  "schemaVersion": 38,
+  "style": "dark",
+  "tags": ["asap", "red"],
+  "templating": { "list": [] },
+  "time": { "from": "now-1h", "to": "now" },
+  "timepicker": {},
+  "timezone": "utc",
+  "title": "ASAP RED",
+  "uid": "asap-red",
+  "version": 1,
+  "weekStart": ""
+}

asap/observability/logging.py

@@ -13,6 +13,8 @@ Environment Variables:
     ASAP_LOG_FORMAT: Set to "json" for JSON output, "console" for colored output
     ASAP_LOG_LEVEL: Set log level (DEBUG, INFO, WARNING, ERROR)
     ASAP_SERVICE_NAME: Service name to include in logs
+    ASAP_DEBUG: Set to "true" or "1" to log full data and stack traces; otherwise sensitive fields are redacted
+    ASAP_DEBUG_LOG: Set to "true" or "1" to log full request/response bodies (structured JSON); for development
 
 Example:
     >>> from asap.observability.logging import get_logger, configure_logging
@@ -42,11 +44,90 @@ DEFAULT_SERVICE_NAME = "asap-protocol"
 ENV_LOG_FORMAT = "ASAP_LOG_FORMAT"
 ENV_LOG_LEVEL = "ASAP_LOG_LEVEL"
 ENV_SERVICE_NAME = "ASAP_SERVICE_NAME"
+ENV_DEBUG = "ASAP_DEBUG"
+ENV_DEBUG_LOG = "ASAP_DEBUG_LOG"
+
+# Placeholder for redacted sensitive values in logs
+REDACTED_PLACEHOLDER = "***REDACTED***"
+
+# Key substrings (case-insensitive) that indicate sensitive data to redact
+_SENSITIVE_KEY_PATTERNS = frozenset(
+    {
+        "password",
+        "token",
+        "secret",
+        "key",
+        "authorization",
+        "auth",
+        "credential",
+        "api_key",
+        "apikey",
+        "access_token",
+        "refresh_token",
+    }
+)
 
 # Module-level flag to track if logging has been configured
 _logging_configured = False
 
 
+def _is_sensitive_key(key: str) -> bool:
+    """Return True if the key name indicates sensitive data that should be redacted."""
+    lower = key.lower()
+    return any(pattern in lower for pattern in _SENSITIVE_KEY_PATTERNS)
+
+
+def sanitize_for_logging(data: dict[str, Any]) -> dict[str, Any]:
+    """Sanitize a dict for safe logging by redacting sensitive field values.
+
+    Keys matching (case-insensitive) password, token, secret, key, authorization,
+    auth, credential, api_key, apikey, access_token, refresh_token have their
+    values replaced with REDACTED_PLACEHOLDER. Handles nested
+    dicts and lists of dicts recursively. Non-sensitive keys and correlation_id
+    are preserved for debugging.
+
+    Args:
+        data: The dict to sanitize (e.g. envelope payload or request params).
+
+    Returns:
+        A new dict with sensitive values replaced; nested structures are deep-copied
+        and sanitized. Non-dict/non-list values for sensitive keys are redacted.
+
+    Example:
+        >>> sanitize_for_logging({"user": "alice", "password": "secret123"})
+        {'user': 'alice', 'password': '***REDACTED***'}
+        >>> sanitize_for_logging({"nested": {"token": "sk_live_abc"}})
+        {'nested': {'token': '***REDACTED***'}}
+    """
+    if not data:
+        return {}
+    result: dict[str, Any] = {}
+    for k, v in data.items():
+        if _is_sensitive_key(k):
+            result[k] = REDACTED_PLACEHOLDER
+        elif isinstance(v, dict):
+            result[k] = sanitize_for_logging(v)
+        elif isinstance(v, list):
+            result[k] = [
+                sanitize_for_logging(item) if isinstance(item, dict) else item for item in v
+            ]
+        else:
+            result[k] = v
+    return result
+
+
+def is_debug_mode() -> bool:
+    """Return True if ASAP_DEBUG is set to a truthy value (e.g. true, 1)."""
+    value = os.environ.get(ENV_DEBUG, "").strip().lower()
+    return value in ("true", "1", "yes", "on")
+
+
+def is_debug_log_mode() -> bool:
+    """Return True if ASAP_DEBUG_LOG is set to a truthy value (log full request/response)."""
+    value = os.environ.get(ENV_DEBUG_LOG, "").strip().lower()
+    return value in ("true", "1", "yes", "on")
+
+
 def _get_log_level() -> str:
     """Get log level from environment or use default."""
     return os.environ.get(ENV_LOG_LEVEL, DEFAULT_LOG_LEVEL).upper()
@@ -185,7 +266,6 @@ def get_logger(name: str) -> structlog.stdlib.BoundLogger:
         >>> logger = logger.bind(trace_id="trace_123")
         >>> logger.info("request.processed")  # trace_id automatically included
     """
-    # Ensure logging is configured
     if not _logging_configured:
         configure_logging()
 

asap/observability/metrics.py

@@ -150,16 +150,30 @@ class MetricsCollector:
         >>> print(collector.export_prometheus())
     """
 
-    # Default metric definitions
+    # Default metric definitions (20+ for observability)
     DEFAULT_COUNTERS: ClassVar[dict[str, str]] = {
         "asap_requests_total": "Total number of ASAP requests received",
         "asap_requests_success_total": "Total number of successful ASAP requests",
         "asap_requests_error_total": "Total number of failed ASAP requests",
         "asap_thread_pool_exhausted_total": "Total number of thread pool exhaustion events",
+        "asap_handler_executions_total": "Total number of handler executions",
+        "asap_handler_errors_total": "Total number of handler execution failures",
+        "asap_state_transitions_total": "Total number of state machine transitions",
+        "asap_transport_send_total": "Total number of transport send attempts",
+        "asap_transport_send_errors_total": "Total number of transport send errors",
+        "asap_transport_retries_total": "Total number of transport retries",
+        "asap_parse_errors_total": "Total number of JSON-RPC parse errors",
+        "asap_auth_failures_total": "Total number of authentication failures",
+        "asap_validation_errors_total": "Total number of envelope validation errors",
+        "asap_invalid_timestamp_total": "Total number of invalid timestamp rejections",
+        "asap_invalid_nonce_total": "Total number of invalid nonce rejections",
+        "asap_sender_mismatch_total": "Total number of sender identity mismatches",
     }
 
     DEFAULT_HISTOGRAMS: ClassVar[dict[str, str]] = {
         "asap_request_duration_seconds": "Request processing duration in seconds",
+        "asap_handler_duration_seconds": "Handler execution duration in seconds",
+        "asap_transport_send_duration_seconds": "Transport send duration in seconds",
     }
 
     def __init__(self) -> None: