clue-python-sdk-core 0.0.1__py3-none-any.whl

clue_python_sdk_core/otel_bridge.py

@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping, Sequence
+
+
+def build_otel_request_span_id(trace_id: str, span_id: str) -> str:
+	return f"otel:{trace_id}:{span_id}"
+
+
+def resolve_current_otel_span_context(
+	expected_kind: str | None = None,
+) -> dict[str, str] | None:
+	try:
+		from opentelemetry import trace
+	except ImportError:
+		return None
+
+	try:
+		span = trace.get_current_span()
+	except Exception:
+		return None
+
+	if span is None:
+		return None
+
+	span_context_getter = getattr(span, "get_span_context", None)
+	if not callable(span_context_getter):
+		return None
+
+	try:
+		span_context = span_context_getter()
+	except Exception:
+		return None
+
+	if not getattr(span_context, "is_valid", False):
+		return None
+
+	kind_name = _span_kind_name(getattr(span, "kind", None))
+	if expected_kind is not None and kind_name != expected_kind:
+		return None
+
+	trace_id_raw = getattr(span_context, "trace_id", 0)
+	span_id_raw = getattr(span_context, "span_id", 0)
+	if not isinstance(trace_id_raw, int) or trace_id_raw <= 0:
+		return None
+	if not isinstance(span_id_raw, int) or span_id_raw <= 0:
+		return None
+
+	parent_context = getattr(span, "parent", None)
+	parent_span_id = None
+	if getattr(parent_context, "is_valid", False):
+		parent_span_id_raw = getattr(parent_context, "span_id", 0)
+		if isinstance(parent_span_id_raw, int) and parent_span_id_raw > 0:
+			parent_span_id = f"{parent_span_id_raw:016x}"
+
+	return {
+		"trace_id": f"{trace_id_raw:032x}",
+		"span_id": f"{span_id_raw:016x}",
+		"parent_span_id": parent_span_id or "",
+		"kind": kind_name or "",
+	}
+
+
+def merge_current_otel_span_context(
+	context: Mapping[str, object],
+	*,
+	expected_kind: str | None = None,
+	use_otel_request_span_id: bool = False,
+) -> dict[str, object]:
+	otel_context = resolve_current_otel_span_context(expected_kind)
+	if otel_context is None:
+		return dict(context)
+
+	merged = dict(context)
+	trace_id = otel_context["trace_id"]
+	span_id = otel_context["span_id"]
+	parent_span_id = otel_context.get("parent_span_id") or None
+	merged["trace_id"] = trace_id
+	merged["span_id"] = span_id
+	merged["parent_span_id"] = parent_span_id
+	if use_otel_request_span_id and not _non_empty_string(merged.get("request_span_id")):
+		merged["request_span_id"] = build_otel_request_span_id(trace_id, span_id)
+	return merged
+
+
+def annotate_current_otel_span(
+	attributes: Mapping[str, object],
+	*,
+	expected_kind: str | None = None,
+) -> bool:
+	try:
+		from opentelemetry import trace
+	except ImportError:
+		return False
+
+	otel_context = resolve_current_otel_span_context(expected_kind)
+	if otel_context is None:
+		return False
+
+	try:
+		span = trace.get_current_span()
+	except Exception:
+		return False
+
+	if span is None:
+		return False
+
+	set_attribute = getattr(span, "set_attribute", None)
+	if not callable(set_attribute):
+		return False
+
+	wrote = False
+	for key, value in attributes.items():
+		if not isinstance(key, str) or not key.strip() or value is None:
+			continue
+		normalized = _normalize_attribute_value(value)
+		if normalized is None:
+			continue
+		try:
+			set_attribute(key, normalized)
+			wrote = True
+		except Exception:
+			continue
+
+	return wrote
+
+
+def _span_kind_name(kind: object) -> str | None:
+	name = getattr(kind, "name", None)
+	if isinstance(name, str) and name.strip():
+		return name.strip().upper()
+	if isinstance(kind, str) and kind.strip():
+		return kind.strip().upper()
+	return None
+
+
+def _non_empty_string(value: object) -> str | None:
+	return value if isinstance(value, str) and value else None
+
+
+def _normalize_attribute_value(value: object) -> str | bool | int | float | Sequence[str | bool | int | float] | None:
+	if isinstance(value, bool):
+		return value
+	if isinstance(value, int):
+		return value
+	if isinstance(value, float):
+		return value if value == value else None
+	if isinstance(value, str):
+		return value
+	if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+		items: list[str | bool | int | float] = []
+		for entry in value:
+			normalized = _normalize_attribute_value(entry)
+			if normalized is None or isinstance(normalized, Sequence) and not isinstance(normalized, str):
+				return json.dumps(value, separators=(",", ":"), ensure_ascii=True)
+			items.append(normalized)
+		return tuple(items)
+	if isinstance(value, Mapping):
+		return json.dumps(value, separators=(",", ":"), ensure_ascii=True)
+	try:
+		return json.dumps(value, separators=(",", ":"), ensure_ascii=True)
+	except Exception:
+		return None

clue_python_sdk_core/parameter_snapshot.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping, Sequence
+
+from .contracts import (
+	CAPTURE_MODE_ALLOWED_PLAINTEXT,
+	CAPTURE_MODE_FORBIDDEN,
+	CAPTURE_MODE_MASKED_FINGERPRINT,
+)
+from .http_extraction import _to_json_value
+from .privacy import JsonValue, fingerprint_value, infer_value_type, is_denied_key
+
+FORBIDDEN_PARAMETER_VALUE = "__forbidden__"
+PARAMETER_FINGERPRINT_SECRET = "clue-backend-sdk"
+
+
+def _normalize_parameter_lookup_path(path: str) -> str:
+	return re.sub(r"\[\d+\]", "[]", path)
+
+
+def _parameter_leaf(value: object, *, capture_mode: str) -> dict[str, JsonValue]:
+	normalized = _to_json_value(value)
+	if capture_mode == CAPTURE_MODE_ALLOWED_PLAINTEXT:
+		leaf_value: JsonValue = normalized
+	elif capture_mode == CAPTURE_MODE_MASKED_FINGERPRINT:
+		leaf_value = fingerprint_value(normalized, PARAMETER_FINGERPRINT_SECRET)
+	else:
+		leaf_value = FORBIDDEN_PARAMETER_VALUE
+
+	return {
+		"type": infer_value_type(normalized),
+		"value": leaf_value,
+		"capture_mode": capture_mode,
+	}
+
+
+def _build_parameter_snapshot(
+	value: object,
+	*,
+	allowed_paths: Sequence[str],
+	denied_keys: Sequence[str],
+	path: str = "",
+) -> tuple[JsonValue, list[str]]:
+	normalized_allowed_paths = {
+		_normalize_parameter_lookup_path(str(entry))
+		for entry in allowed_paths
+		if str(entry).strip()
+	}
+
+	if isinstance(value, Mapping):
+		snapshot: dict[str, JsonValue] = {}
+		allowed_value_keys: list[str] = []
+		for key, child in value.items():
+			key_text = str(key)
+			child_path = f"{path}.{key_text}" if path else key_text
+			if is_denied_key(key_text, denied_keys):
+				snapshot[key_text] = _parameter_leaf(
+					child,
+					capture_mode=CAPTURE_MODE_FORBIDDEN,
+				)
+				continue
+
+			child_snapshot, child_allowed_value_keys = _build_parameter_snapshot(
+				child,
+				allowed_paths=allowed_paths,
+				denied_keys=denied_keys,
+				path=child_path,
+			)
+			snapshot[key_text] = child_snapshot
+			allowed_value_keys.extend(child_allowed_value_keys)
+
+		return snapshot, allowed_value_keys
+
+	if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+		items = list(value)
+		if not items:
+			return [], []
+
+		representative_snapshot, allowed_value_keys = _build_parameter_snapshot(
+			items[0],
+			allowed_paths=allowed_paths,
+			denied_keys=denied_keys,
+			path=f"{path}[]",
+		)
+		return [representative_snapshot], allowed_value_keys
+
+	normalized_path = _normalize_parameter_lookup_path(path)
+	capture_mode = (
+		CAPTURE_MODE_ALLOWED_PLAINTEXT
+		if normalized_path in normalized_allowed_paths
+		else CAPTURE_MODE_MASKED_FINGERPRINT
+	)
+	allowed_value_keys = [path] if capture_mode == CAPTURE_MODE_ALLOWED_PLAINTEXT and path else []
+	return _parameter_leaf(value, capture_mode=capture_mode), allowed_value_keys
+
+
+def _build_request_parameter_snapshot(
+	*,
+	query: Mapping[str, JsonValue],
+	body: JsonValue | None,
+	allowed_value_paths: Sequence[str],
+	denied_keys: Sequence[str],
+) -> tuple[dict[str, JsonValue], list[str], str, str]:
+	snapshot: dict[str, JsonValue] = {}
+	allowed_value_keys: list[str] = []
+
+	if body is not None:
+		body_snapshot, body_allowed_value_keys = _build_parameter_snapshot(
+			body,
+			allowed_paths=allowed_value_paths,
+			denied_keys=denied_keys,
+			path="body",
+		)
+		snapshot["body"] = body_snapshot
+		allowed_value_keys.extend(body_allowed_value_keys)
+
+	if query:
+		query_snapshot, query_allowed_value_keys = _build_parameter_snapshot(
+			query,
+			allowed_paths=allowed_value_paths,
+			denied_keys=denied_keys,
+			path="query",
+		)
+		snapshot["query"] = query_snapshot
+		allowed_value_keys.extend(query_allowed_value_keys)
+
+	privacy_level = "allowlisted" if allowed_value_keys else "default_masked"
+	masking_state = "partially_unmasked" if allowed_value_keys else "masked"
+	return snapshot, sorted(dict.fromkeys(allowed_value_keys)), privacy_level, masking_state
+
+
+def _build_response_parameter_snapshot(
+	*,
+	body: JsonValue | None,
+	allowed_value_paths: Sequence[str],
+	denied_keys: Sequence[str],
+) -> tuple[dict[str, JsonValue], list[str], str, str]:
+	if body is None:
+		return {}, [], "default_masked", "masked"
+
+	response_snapshot, allowed_value_keys = _build_parameter_snapshot(
+		body,
+		allowed_paths=allowed_value_paths,
+		denied_keys=denied_keys,
+		path="response",
+	)
+	privacy_level = "allowlisted" if allowed_value_keys else "default_masked"
+	masking_state = "partially_unmasked" if allowed_value_keys else "masked"
+	return {
+		"response": response_snapshot,
+	}, sorted(dict.fromkeys(allowed_value_keys)), privacy_level, masking_state

clue_python_sdk_core/privacy.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import re
+from collections.abc import Mapping, Sequence
+from typing import Dict, List, Union
+
+JsonScalar = Union[str, int, float, bool, None]
+JsonValue = Union[JsonScalar, List["JsonValue"], Dict[str, "JsonValue"]]
+
+MASK_TOKEN_KEY = "__clue_masked__"
+
+DEFAULT_DENIED_KEYS = frozenset(
+	{
+		"authorization",
+		"cookie",
+		"set-cookie",
+		"password",
+		"passwd",
+		"secret",
+		"token",
+		"session",
+		"session_token",
+		"refresh_token",
+		"api_key",
+		"apikey",
+		"private_key",
+	}
+)
+
+
+def _normalize_lookup_key(key: str) -> str:
+	with_underscores = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", key.strip())
+	return re.sub(r"[^a-z0-9]+", "_", with_underscores.lower()).strip("_")
+
+
+def is_denied_key(key: str, denied_keys: Sequence[str] = ()) -> bool:
+	normalized = _normalize_lookup_key(key)
+	if not normalized:
+		return False
+
+	denied = {
+		_normalize_lookup_key(entry)
+		for entry in [*DEFAULT_DENIED_KEYS, *denied_keys]
+		if _normalize_lookup_key(entry)
+	}
+	if normalized in denied:
+		return True
+
+	padded = f"_{normalized}_"
+	return any(f"_{entry}_" in padded for entry in denied)
+
+
+def _to_json_value(value: object) -> JsonValue:
+	if value is None:
+		return None
+	if isinstance(value, bool):
+		return value
+	if isinstance(value, (int, float)):
+		return value
+	if isinstance(value, str):
+		return value
+	if isinstance(value, bytes):
+		return value.decode("utf-8", errors="replace")
+	if isinstance(value, Mapping):
+		return {str(key): _to_json_value(child) for key, child in value.items()}
+	if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+		return [_to_json_value(child) for child in value]
+	return str(value)
+
+
+def safe_sanitize_object(value: object, denied_keys: Sequence[str] = ()) -> JsonValue:
+	if isinstance(value, Mapping):
+		sanitized: dict[str, JsonValue] = {}
+		for key, child in value.items():
+			key_text = str(key)
+			if is_denied_key(key_text, denied_keys):
+				continue
+			sanitized[key_text] = safe_sanitize_object(child, denied_keys)
+		return sanitized
+
+	if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+		return [safe_sanitize_object(child, denied_keys) for child in value]
+
+	return _to_json_value(value)
+
+
+def infer_value_type(value: object) -> str:
+	if value is None:
+		return "null"
+	if isinstance(value, bool):
+		return "boolean"
+	if isinstance(value, (int, float)):
+		return "number"
+	if isinstance(value, str):
+		return "string"
+	if isinstance(value, bytes):
+		return "bytes"
+	if isinstance(value, Mapping):
+		return "object"
+	if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+		return "array"
+	return type(value).__name__
+
+
+def build_mask_token(mode: str, value: object) -> dict[str, JsonValue]:
+	return {
+		MASK_TOKEN_KEY: True,
+		"mode": mode,
+		"valueType": infer_value_type(value),
+	}
+
+
+def fingerprint_value(value: object, secret: str) -> str:
+	normalized = json.dumps(_to_json_value(value), sort_keys=True, separators=(",", ":"))
+	digest = hmac.new(
+		secret.encode("utf-8"),
+		normalized.encode("utf-8"),
+		hashlib.sha256,
+	).hexdigest()
+	return f"hmac:{digest}"
+