openwright-core 0.6.0__py3-none-any.whl

openwright/__init__.py

@@ -0,0 +1,20 @@
+"""OpenWright — the Agent Evidence Layer.
+
+OpenWright turns the runtime behavior of AI agents into signed, tamper-evident,
+control-mapped audit evidence: telemetry/SDK signals → a canonical
+``ComplianceEvent`` → declarative regulatory crosswalks → an append-only Merkle
+log → signed reports → independent verification.
+
+Boundary (non-negotiable, see FR-RPT-07 / NFR-COMP-01): OpenWright produces
+*evidence that controls were exercised*. It does NOT assert or imply legal
+compliance, certification, or fitness. Those are judgments reserved for
+qualified auditors and counsel.
+"""
+
+__version__ = "0.6.0"
+
+# Schema version for the canonical event model. Bumped independently of the
+# package version; readers MUST tolerate unknown future fields (DR-04).
+COMPLIANCE_EVENT_SCHEMA_VERSION = "1.0.0"
+
+__all__ = ["__version__", "COMPLIANCE_EVENT_SCHEMA_VERSION"]

openwright/_ed25519_pure.py

@@ -0,0 +1,98 @@
+"""Pure-Python Ed25519 signature *verification* (RFC 8032).
+
+Used as a fallback by the verifier when the ``cryptography`` package is not
+available — e.g. when running the verifier inside a stock WASM Python (Pyodide)
+in the browser (FR-VER-04 [P2]). With this fallback the verifier needs **zero
+third-party dependencies**, only the standard library.
+
+This implements verification only (never signing); it follows the cofactorless
+group-equation check ``[S]B == R + [k]A`` from RFC 8032 §5.1.7, which accepts all
+signatures produced by a compliant signer (e.g. ``cryptography``). It is not
+constant-time, which is fine — verification uses only public data.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+_P = 2**255 - 19
+_L = 2**252 + 27742317777372353535851937790883648493
+
+
+def _inv(x: int) -> int:
+    return pow(x, _P - 2, _P)
+
+
+_D = (-121665 * _inv(121666)) % _P
+_I = pow(2, (_P - 1) // 4, _P)
+
+
+def _xrecover(y: int) -> int:
+    xx = (y * y - 1) * _inv(_D * y * y + 1)
+    x = pow(xx, (_P + 3) // 8, _P)
+    if (x * x - xx) % _P != 0:
+        x = (x * _I) % _P
+    if x % 2 != 0:
+        x = _P - x
+    return x
+
+
+_BY = (4 * _inv(5)) % _P
+_BX = _xrecover(_BY) % _P
+_B = (_BX, _BY)
+
+
+def _edwards_add(p1, p2):
+    x1, y1 = p1
+    x2, y2 = p2
+    denom = _inv(1 + _D * x1 * x2 * y1 * y2)
+    x3 = (x1 * y2 + x2 * y1) * denom % _P
+    denom2 = _inv(1 - _D * x1 * x2 * y1 * y2)
+    y3 = (y1 * y2 + x1 * x2) * denom2 % _P
+    return (x3, y3)
+
+
+def _scalarmult(point, e: int):
+    result = (0, 1)  # neutral element
+    addend = point
+    while e > 0:
+        if e & 1:
+            result = _edwards_add(result, addend)
+        addend = _edwards_add(addend, addend)
+        e >>= 1
+    return result
+
+
+def _is_on_curve(point) -> bool:
+    x, y = point
+    return (-x * x + y * y - 1 - _D * x * x * y * y) % _P == 0
+
+
+def _decodepoint(s: bytes):
+    val = int.from_bytes(s, "little")
+    y = val & ((1 << 255) - 1)
+    x = _xrecover(y)
+    if (x & 1) != ((val >> 255) & 1):
+        x = _P - x
+    point = (x, y)
+    if not _is_on_curve(point):
+        raise ValueError("point not on curve")
+    return point
+
+
+def verify(public_key: bytes, signature: bytes, message: bytes) -> bool:
+    """Return True iff ``signature`` is a valid Ed25519 signature of ``message``."""
+    if len(signature) != 64 or len(public_key) != 32:
+        return False
+    try:
+        r_point = _decodepoint(signature[:32])
+        a_point = _decodepoint(public_key)
+    except (ValueError, Exception):  # noqa: BLE001
+        return False
+    s = int.from_bytes(signature[32:], "little")
+    if s >= _L:
+        return False
+    h = int.from_bytes(hashlib.sha512(signature[:32] + public_key + message).digest(), "little") % _L
+    sb = _scalarmult(_B, s)
+    ha = _scalarmult(a_point, h)
+    return sb == _edwards_add(r_point, ha)

openwright/adapters/__init__.py

@@ -0,0 +1,37 @@
+"""Source-format adapters (FR-NRM-03).
+
+Each adapter isolates one upstream convention so that a change there (e.g. the
+OTel GenAI conventions leaving experimental status — C-01) requires editing only
+that adapter, never the core or the canonical event schema. Adapters are
+deliberately proto-agnostic: they consume plain Python dicts, so the ingest
+layer owns OTLP/protobuf decoding.
+"""
+
+from .base import SpanData
+from .otel_genai import span_to_event
+from .a2a import reconstruct_provenance
+from .langfuse import apply_langfuse_precedence, has_langfuse_attributes
+from .sarif_in import sarif_to_events
+from .policy import policy_decisions_to_events
+from .receipt import (
+    SignedActionReceiptSource,
+    ReceiptSource,
+    ReceiptVerificationError,
+    receipt_to_event,
+    sign_receipt,
+)
+
+__all__ = [
+    "SpanData",
+    "span_to_event",
+    "reconstruct_provenance",
+    "apply_langfuse_precedence",
+    "has_langfuse_attributes",
+    "sarif_to_events",
+    "policy_decisions_to_events",
+    "SignedActionReceiptSource",
+    "ReceiptSource",
+    "ReceiptVerificationError",
+    "receipt_to_event",
+    "sign_receipt",
+]

openwright/adapters/a2a.py

@@ -0,0 +1,71 @@
+"""A2A task-provenance reconstruction (FR-ING-05).
+
+Verified against the A2A spec (v0.3.0): a ``Task`` has ``id`` and ``contextId``
+but NO parent-task field; cross-task lineage is expressed softly via
+``Message.referenceTaskIds`` and grouping via ``contextId``. OpenWright therefore
+*reconstructs* a parent/root chain from those signals — the ``parent_task_id``
+and ``root_task_id`` on a :class:`Provenance` are OpenWright-derived, not native
+A2A fields. Absent A2A, provenance degrades to single-event records (A-02).
+
+All A2A-origin data is treated as untrusted input (FR-ING-10): IDs are used only
+as opaque correlation keys, never interpreted or executed.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+
+from ..events import Provenance
+
+
+def reconstruct_provenance(
+    task_id: Optional[str],
+    context_id: Optional[str] = None,
+    reference_task_ids: Optional[List[str]] = None,
+    known: Optional[Dict[str, Provenance]] = None,
+) -> Provenance:
+    """Reconstruct parent/root for ``task_id`` from A2A signals.
+
+    ``known`` maps already-seen task IDs to their reconstructed provenance, used
+    to walk the root chain. ``reference_task_ids`` (from the triggering Message)
+    yields the parent; the root is the parent's root, or this task if it has none.
+    """
+    known = known or {}
+    parent_task_id = reference_task_ids[0] if reference_task_ids else None
+
+    if parent_task_id and parent_task_id in known and known[parent_task_id].root_task_id:
+        root_task_id = known[parent_task_id].root_task_id
+    elif parent_task_id:
+        root_task_id = parent_task_id  # parent unseen; best-effort root = parent
+    else:
+        root_task_id = task_id  # no parent → this task is its own root
+
+    return Provenance(
+        task_id=task_id,
+        context_id=context_id,
+        parent_task_id=parent_task_id,
+        root_task_id=root_task_id,
+    )
+
+
+# Attribute keys some instrumentations use to carry A2A identifiers on spans.
+A2A_TASK_ID = "a2a.task.id"
+A2A_CONTEXT_ID = "a2a.context.id"
+A2A_REFERENCE_TASK_IDS = "a2a.reference_task_ids"
+
+
+def provenance_from_attributes(
+    attrs: Dict[str, object], known: Optional[Dict[str, Provenance]] = None
+) -> Optional[Provenance]:
+    """Reconstruct provenance from A2A identifiers carried as span attributes."""
+    task_id = attrs.get(A2A_TASK_ID)
+    if not task_id:
+        return None
+    refs = attrs.get(A2A_REFERENCE_TASK_IDS)
+    ref_list = list(refs) if isinstance(refs, (list, tuple)) else ([refs] if refs else None)
+    return reconstruct_provenance(
+        str(task_id),
+        context_id=str(attrs[A2A_CONTEXT_ID]) if attrs.get(A2A_CONTEXT_ID) else None,
+        reference_task_ids=[str(r) for r in ref_list] if ref_list else None,
+        known=known,
+    )

openwright/adapters/base.py

@@ -0,0 +1,24 @@
+"""Shared adapter input types."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+
+@dataclass
+class SpanData:
+    """A telemetry span reduced to plain Python (no protobuf types).
+
+    The ingest layer fills this from OTLP; adapters consume it. Keeping adapters
+    free of protobuf imports is what makes them swappable (FR-NRM-03).
+    """
+
+    name: str
+    attributes: Dict[str, Any] = field(default_factory=dict)
+    resource: Dict[str, Any] = field(default_factory=dict)
+    trace_id: Optional[str] = None
+    span_id: Optional[str] = None
+    parent_span_id: Optional[str] = None
+    start_time_unix_nano: Optional[int] = None
+    status: Optional[str] = None

openwright/adapters/langfuse.py

@@ -0,0 +1,56 @@
+"""Langfuse ``langfuse.*`` attribute precedence (FR-ING-06).
+
+Langfuse documents that its ``langfuse.*`` namespace "always take[s] precedence
+over the generic OpenTelemetry conventions" (langfuse.com/integrations/native/
+opentelemetry, verified 2026-05). This adapter overlays those values onto an
+event already normalized from generic ``gen_ai.*`` attributes.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from ..canonical import hash_payload
+from ..events import ComplianceEvent, IORef, ModelInfo
+
+LF_SESSION_ID = "langfuse.session.id"
+LF_USER_ID = "langfuse.user.id"
+LF_ENVIRONMENT = "langfuse.environment"
+LF_OBS_MODEL = "langfuse.observation.model.name"
+LF_OBS_INPUT = "langfuse.observation.input"
+LF_OBS_OUTPUT = "langfuse.observation.output"
+LF_OBS_LEVEL = "langfuse.observation.level"
+LF_OBS_TYPE = "langfuse.observation.type"
+LF_TRACE_NAME = "langfuse.trace.name"
+
+
+def has_langfuse_attributes(attrs: Dict[str, Any]) -> bool:
+    return any(k.startswith("langfuse.") for k in attrs)
+
+
+def apply_langfuse_precedence(event: ComplianceEvent, attrs: Dict[str, Any]) -> ComplianceEvent:
+    """Mutate ``event`` so langfuse.* values win over generic OTel values."""
+    if not has_langfuse_attributes(attrs):
+        return event
+
+    # Session id groups related observations → use as context if present.
+    if attrs.get(LF_SESSION_ID):
+        event.provenance.context_id = str(attrs[LF_SESSION_ID])
+
+    if attrs.get(LF_OBS_MODEL):
+        event.model = event.model or ModelInfo()
+        event.model.request_model = str(attrs[LF_OBS_MODEL])
+
+    if attrs.get(LF_OBS_INPUT) is not None or attrs.get(LF_OBS_OUTPUT) is not None:
+        event.io = event.io or IORef()
+        if attrs.get(LF_OBS_INPUT) is not None:
+            event.io.input_ref = hash_payload(attrs[LF_OBS_INPUT])
+        if attrs.get(LF_OBS_OUTPUT) is not None:
+            event.io.output_ref = hash_payload(attrs[LF_OBS_OUTPUT])
+
+    for key, label in ((LF_USER_ID, "user_id"), (LF_ENVIRONMENT, "environment"), (LF_OBS_LEVEL, "level"), (LF_OBS_TYPE, "observation_type"), (LF_TRACE_NAME, "trace_name")):
+        if attrs.get(key) is not None:
+            event.attributes[f"langfuse.{label}"] = str(attrs[key])
+
+    event.attributes["langfuse_precedence_applied"] = True
+    return event

openwright/adapters/otel_genai.py

@@ -0,0 +1,180 @@
+"""OpenTelemetry GenAI semantic-convention adapter (FR-ING-03, FR-NRM-01).
+
+All attribute names live in this module so a future rename is a one-line change
+(FR-NRM-03; the conventions are still Experimental/"Development" — C-01). Both
+the current names and their deprecated predecessors are accepted, since
+instrumentations that have not opted into ``gen_ai_latest_experimental`` still
+emit the old names (verified against opentelemetry.io, 2026-05). When both are
+present the current name wins.
+
+There is NO ``gen_ai.usage.cost`` attribute in the conventions; cost is derived
+downstream from token counts and an operator-supplied pricing table, or omitted.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from ..canonical import hash_payload
+from ..events import ComplianceEvent, EventKind, IORef, ModelInfo, ToolInfo
+from .base import SpanData
+
+# -- attribute names (single source of truth) ---------------------------------
+A_OPERATION = "gen_ai.operation.name"
+A_PROVIDER = "gen_ai.provider.name"
+A_PROVIDER_LEGACY = "gen_ai.system"
+A_REQUEST_MODEL = "gen_ai.request.model"
+A_RESPONSE_MODEL = "gen_ai.response.model"
+A_INPUT_TOKENS = "gen_ai.usage.input_tokens"
+A_INPUT_TOKENS_LEGACY = "gen_ai.usage.prompt_tokens"
+A_OUTPUT_TOKENS = "gen_ai.usage.output_tokens"
+A_OUTPUT_TOKENS_LEGACY = "gen_ai.usage.completion_tokens"
+A_FINISH_REASONS = "gen_ai.response.finish_reasons"
+A_TOOL_NAME = "gen_ai.tool.name"
+A_TOOL_CALL_ID = "gen_ai.tool.call.id"
+A_TOOL_TYPE = "gen_ai.tool.type"
+A_CONVERSATION_ID = "gen_ai.conversation.id"
+A_AGENT_NAME = "gen_ai.agent.name"
+# Deprecated/removed content attributes — hashed if present, never stored raw.
+A_PROMPT_LEGACY = "gen_ai.prompt"
+A_COMPLETION_LEGACY = "gen_ai.completion"
+
+_OPERATION_TO_KIND = {
+    "chat": EventKind.LLM_CALL,
+    "generate_content": EventKind.LLM_CALL,
+    "text_completion": EventKind.LLM_CALL,
+    "embeddings": EventKind.LLM_CALL,
+    "execute_tool": EventKind.TOOL_CALL,
+    "invoke_agent": EventKind.AGENT_DECISION,
+    "create_agent": EventKind.AGENT_DECISION,
+    "invoke_workflow": EventKind.AGENT_DECISION,
+}
+
+
+def _first(attrs: Dict[str, Any], *keys: str) -> Optional[Any]:
+    for k in keys:
+        if k in attrs and attrs[k] is not None:
+            return attrs[k]
+    return None
+
+
+def _coerce_int(value: Any) -> Optional[int]:
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _coerce_str_list(value: Any) -> Optional[List[str]]:
+    if value is None:
+        return None
+    if isinstance(value, (list, tuple)):
+        return [str(v) for v in value]
+    return [str(value)]  # tolerate a scalar emitted instead of a 1-element array
+
+
+def detected_semconv(attrs: Dict[str, Any]) -> str:
+    """Best-effort tag of which convention generation a span follows."""
+    if A_PROVIDER in attrs or A_INPUT_TOKENS in attrs:
+        return "gen_ai/latest"
+    if A_PROVIDER_LEGACY in attrs or A_INPUT_TOKENS_LEGACY in attrs:
+        return "gen_ai/legacy"
+    return "gen_ai/unknown"
+
+
+def span_to_event(
+    span: SpanData,
+    *,
+    timestamp: str,
+    agent_id: Optional[str] = None,
+    pricing: Optional[Dict[str, Any]] = None,
+) -> ComplianceEvent:
+    """Normalize one GenAI span into a canonical :class:`ComplianceEvent`."""
+    attrs = span.attributes or {}
+    operation = attrs.get(A_OPERATION)
+    kind = _OPERATION_TO_KIND.get(operation, EventKind.GENERIC)
+
+    resolved_agent = (
+        agent_id
+        or attrs.get(A_AGENT_NAME)
+        or span.resource.get("service.name")
+        or "unknown-agent"
+    )
+
+    input_tokens = _coerce_int(_first(attrs, A_INPUT_TOKENS, A_INPUT_TOKENS_LEGACY))
+    output_tokens = _coerce_int(_first(attrs, A_OUTPUT_TOKENS, A_OUTPUT_TOKENS_LEGACY))
+    total_tokens = (input_tokens or 0) + (output_tokens or 0) if (input_tokens or output_tokens) else None
+
+    # Legacy raw content, if present, is hashed — never stored inline (FR-LED-06).
+    prompt = attrs.get(A_PROMPT_LEGACY)
+    completion = attrs.get(A_COMPLETION_LEGACY)
+
+    cost = None
+    if pricing and (input_tokens is not None or output_tokens is not None):
+        cost = _compute_cost(pricing, _first(attrs, A_REQUEST_MODEL, A_RESPONSE_MODEL), input_tokens, output_tokens)
+
+    io = IORef(
+        input_ref=hash_payload(prompt) if prompt is not None else None,
+        output_ref=hash_payload(completion) if completion is not None else None,
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        total_tokens=total_tokens,
+        cost=cost,
+        cost_currency="USD" if cost else None,
+    )
+    model = ModelInfo(
+        provider=_first(attrs, A_PROVIDER, A_PROVIDER_LEGACY),
+        request_model=attrs.get(A_REQUEST_MODEL),
+        response_model=attrs.get(A_RESPONSE_MODEL),
+    )
+    tool = None
+    if attrs.get(A_TOOL_NAME) or attrs.get(A_TOOL_CALL_ID):
+        tool = ToolInfo(name=attrs.get(A_TOOL_NAME), call_id=attrs.get(A_TOOL_CALL_ID))
+
+    extra: Dict[str, Any] = {}
+    if operation:
+        extra["operation"] = operation
+    finish = _coerce_str_list(attrs.get(A_FINISH_REASONS))
+    if finish:
+        extra["finish_reasons"] = finish
+    if attrs.get(A_TOOL_TYPE):
+        extra["tool_type"] = attrs[A_TOOL_TYPE]
+    extra["semconv"] = detected_semconv(attrs)
+
+    conversation_id = attrs.get(A_CONVERSATION_ID)
+
+    return ComplianceEvent(
+        timestamp=timestamp,
+        kind=kind,
+        actor={"agent_id": resolved_agent},
+        provenance={"context_id": conversation_id} if conversation_id else {},
+        io=io if any(v is not None for v in io.model_dump().values()) else None,
+        model=model if any(model.model_dump().values()) else None,
+        tool=tool,
+        attributes=extra,
+        source={
+            "format": "otel-genai",
+            "span_id": span.span_id,
+            "trace_id": span.trace_id,
+        },
+    )
+
+
+def _compute_cost(
+    pricing: Dict[str, Any], model: Optional[str], in_tok: Optional[int], out_tok: Optional[int]
+) -> Optional[str]:
+    """Derive a cost as a decimal string (no floats in the event — FR-NRM-04)."""
+    from decimal import Decimal
+
+    rates = pricing.get(model) if model else None
+    rates = rates or pricing.get("default")
+    if not rates:
+        return None
+    cost = Decimal(0)
+    if in_tok:
+        cost += Decimal(str(rates.get("input_per_1k", 0))) * Decimal(in_tok) / Decimal(1000)
+    if out_tok:
+        cost += Decimal(str(rates.get("output_per_1k", 0))) * Decimal(out_tok) / Decimal(1000)
+    return f"{cost:.6f}"

openwright/adapters/policy.py

@@ -0,0 +1,63 @@
+"""Policy-engine decision ingest (FR-ING-09): OPA and Cedar → policy.decision events.
+
+Consumes decision logs from Open Policy Agent (OPA) and Amazon Cedar and records
+them as ``policy_decision`` events. We consume the engines' output; we do not
+re-implement policy evaluation. All input is treated as untrusted (FR-ING-10):
+parsing is defensive and malformed entries are skipped, not fatal.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from ..events import ComplianceEvent, EventKind
+
+
+def _opa_entry(entry: Dict[str, Any]) -> Dict[str, Any]:
+    result = entry.get("result")
+    allowed = result.get("allow") if isinstance(result, dict) else result
+    return {
+        "engine": "opa",
+        "decision_id": entry.get("decision_id"),
+        "policy": entry.get("path"),
+        "decision": "allow" if allowed else "deny",
+        "result": result if not isinstance(result, dict) else None,
+    }
+
+
+def _cedar_entry(entry: Dict[str, Any]) -> Dict[str, Any]:
+    decision = entry.get("decision")
+    diagnostics = entry.get("diagnostics", {}) if isinstance(entry.get("diagnostics"), dict) else {}
+    return {
+        "engine": "cedar",
+        "decision": str(decision).lower() if decision else None,
+        "determining_policies": diagnostics.get("reason"),
+        "errors": diagnostics.get("errors"),
+    }
+
+
+def policy_decisions_to_events(
+    entries: List[Dict[str, Any]],
+    *,
+    agent_id: str,
+    timestamp: str,
+    engine: str = "opa",
+    task_id: Optional[str] = None,
+) -> List[ComplianceEvent]:
+    parse = _opa_entry if engine == "opa" else _cedar_entry
+    events: List[ComplianceEvent] = []
+    for entry in entries:
+        if not isinstance(entry, dict):
+            continue
+        attrs = {k: v for k, v in parse(entry).items() if v is not None}
+        events.append(
+            ComplianceEvent(
+                timestamp=entry.get("timestamp") or timestamp,
+                kind=EventKind.POLICY_DECISION,
+                actor={"agent_id": agent_id},
+                provenance={"task_id": task_id} if task_id else {},
+                attributes=attrs,
+                source={"format": f"policy-{engine}"},
+            )
+        )
+    return events