crprotocol 2.2.0__tar.gz → 2.3.0__tar.gz

{crprotocol-2.2.0 → crprotocol-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crprotocol
-Version: 2.2.0
+Version: 2.3.0
 Summary: Context Relay Protocol — unbounded context, unbounded generation, amplified reasoning for LLMs
 Project-URL: Homepage, https://crprotocol.io
 Project-URL: Documentation, https://crprotocol.io
@@ -73,7 +73,7 @@ Description-Content-Type: text/markdown
 <p align="center">
   <a href="LICENSE.md"><img src="https://img.shields.io/badge/Spec-CC_BY--SA_4.0-blue.svg" alt="Spec: CC BY-SA 4.0"></a>
   <a href="LICENSE.md"><img src="https://img.shields.io/badge/Code-ELv2-orange.svg" alt="Code: Elastic License 2.0"></a>
-  <img src="https://img.shields.io/badge/Spec_Version-2.1.0-brightgreen.svg" alt="Spec Version: 2.1.0">
+  <img src="https://img.shields.io/badge/Spec_Version-2.2.0-brightgreen.svg" alt="Spec Version: 2.2.0">
   <img src="https://img.shields.io/badge/RFC_2119-Conformant-orange.svg" alt="RFC 2119">
   <img src="https://img.shields.io/badge/Language_Neutral-JSON_Schema-yellow.svg" alt="Language Neutral">
   <img src="https://img.shields.io/badge/Status-Specification_Complete-green.svg" alt="Status: Specification Complete">

{crprotocol-2.2.0 → crprotocol-2.3.0}/README.md

@@ -16,7 +16,7 @@
 <p align="center">
   <a href="LICENSE.md"><img src="https://img.shields.io/badge/Spec-CC_BY--SA_4.0-blue.svg" alt="Spec: CC BY-SA 4.0"></a>
   <a href="LICENSE.md"><img src="https://img.shields.io/badge/Code-ELv2-orange.svg" alt="Code: Elastic License 2.0"></a>
-  <img src="https://img.shields.io/badge/Spec_Version-2.1.0-brightgreen.svg" alt="Spec Version: 2.1.0">
+  <img src="https://img.shields.io/badge/Spec_Version-2.2.0-brightgreen.svg" alt="Spec Version: 2.2.0">
   <img src="https://img.shields.io/badge/RFC_2119-Conformant-orange.svg" alt="RFC 2119">
   <img src="https://img.shields.io/badge/Language_Neutral-JSON_Schema-yellow.svg" alt="Language Neutral">
   <img src="https://img.shields.io/badge/Status-Specification_Complete-green.svg" alt="Status: Specification Complete">

{crprotocol-2.2.0 → crprotocol-2.3.0}/crp/__init__.py

@@ -50,10 +50,23 @@ from crp.core.context_enforcer import (
 from crp.core.manifest_ledger import (
     EnvVarKeyProvider,
     KeyProvider,
+    LedgerChainError,
     ManifestLedger,
     ManifestLedgerEntry,
     RotatingKeyProvider,
 )
+from crp.core.ledger_backends import (
+    AsyncBufferedSink,
+    HTTPForwardingSink,
+    JSONLinesFileSink,
+    NullSink,
+)
+from crp.core.manifest_derive import (
+    content_hash,
+    derive_manifest_from_messages,
+    derive_source_from_message,
+    derive_sources_from_messages,
+)
 from crp.core.errors import (
     CRPError,
     BudgetExhaustedError,
@@ -140,9 +153,20 @@ __all__ = [
     "set_default_enforcer",
     "ManifestLedger",
     "ManifestLedgerEntry",
+    "LedgerChainError",
     "KeyProvider",
     "EnvVarKeyProvider",
     "RotatingKeyProvider",
+    # Ledger forwarding sinks (CRP 2.3, §7.14.5)
+    "JSONLinesFileSink",
+    "HTTPForwardingSink",
+    "AsyncBufferedSink",
+    "NullSink",
+    # Derived manifests (CRP 2.3, §7.14.6)
+    "content_hash",
+    "derive_source_from_message",
+    "derive_sources_from_messages",
+    "derive_manifest_from_messages",
     # Error types (§audit L2)
     "CRPError",
     "ErrorCode",

{crprotocol-2.2.0 → crprotocol-2.3.0}/crp/_version.py

@@ -2,4 +2,4 @@
 # Licensed under Elastic License 2.0 — see LICENSE.md for details.
 """CRP — Context Relay Protocol SDK."""
 
-__version__ = "2.2.0"
+__version__ = "2.3.0"

{crprotocol-2.2.0 → crprotocol-2.3.0}/crp/core/context_enforcer.py

@@ -47,6 +47,7 @@ from .context_source import (
     ContextSource,
     ManifestValidationError,
     SourceKind,
+    SourceOrigin,
     TrustLevel,
     check_attestation,
 )
@@ -572,6 +573,87 @@ class ContextEnforcer:
             except (ValueError, ManifestValidationError) as exc:
                 logger.warning("CRP ledger record failed: %s", exc)
 
+    # ------------------------------------------------------------ per-turn
+
+    def check_messages(
+        self,
+        messages: Sequence[dict[str, Any]],
+        manifest: ContextManifest | None = None,
+        *,
+        session_id: str | None = None,
+        derive_manifest: bool = False,
+        emit: bool = True,
+    ) -> EnforcementResult:
+        """Re-run the enforcement pipeline against a full chat history (CRP 2.3).
+
+        For every message the enforcer derives a :class:`ContextSource`
+        (system/user/assistant/tool → kind+trust) and an observed-content
+        bundle, so both *attestation* and *injection* scans run over the
+        actual bytes that will be sent to the model. Tool-call loops
+        benefit most: ``tool_result`` payloads are re-validated every
+        turn instead of only at first assembly.
+
+        When ``derive_manifest=True`` and *manifest* is ``None``, a fresh
+        manifest is derived from the messages themselves (unsigned, one
+        source per message). This is the "belt-and-braces" path for
+        integrators who want a per-turn audit record even if they never
+        authored a manifest.
+        """
+        from .manifest_derive import derive_sources_from_messages, derive_manifest_from_messages
+
+        sid = session_id or self._session_id
+        effective_manifest = manifest
+        if effective_manifest is None and derive_manifest:
+            effective_manifest = derive_manifest_from_messages(
+                messages, session_id=sid
+            )
+        bundles: list[_ObservedContent] = []
+        for source, text in derive_sources_from_messages(
+            messages, session_id=sid
+        ):
+            bundles.append(_ObservedContent(source=source, content=text))
+        return self.check(effective_manifest, bundles, emit=emit)
+
+    def check_tool_result(
+        self,
+        content: str | dict[str, Any] | list[Any],
+        *,
+        source: ContextSource | None = None,
+        manifest: ContextManifest | None = None,
+        tool_call_id: str | None = None,
+        tool_name: str | None = None,
+        emit: bool = True,
+    ) -> EnforcementResult:
+        """Validate a single tool-call / function-call result (CRP 2.3).
+
+        Runs the same pipeline as :meth:`check` but bounded to one
+        payload, so agent loops can re-validate each tool response
+        individually.  If *source* is not supplied, a derived
+        ``FUNCTION_CALL`` source is constructed with an ``UNKNOWN`` trust
+        level (tool outputs are never implicitly trusted).
+        """
+        from .manifest_derive import _flatten_content, content_hash
+
+        text = _flatten_content(content)
+        if source is None:
+            metadata: dict[str, Any] = {
+                "content_sha256": content_hash(text) if text else "sha256:",
+                "content_len": len(text),
+            }
+            if tool_call_id:
+                metadata["tool_call_id"] = str(tool_call_id)[:128]
+            if tool_name:
+                metadata["tool_name"] = str(tool_name)[:128]
+            source = ContextSource(
+                kind=SourceKind.FUNCTION_CALL,
+                source_id=f"tool_result:{tool_call_id or tool_name or 'anon'}",
+                origin=SourceOrigin.OBSERVED,
+                trust_level=TrustLevel.UNKNOWN,
+                retrieved_at=time.time(),
+                metadata=metadata,
+            )
+        return self.check(manifest, [_ObservedContent(source=source, content=text)], emit=emit)
+
 
 # ---------------------------------------------------------------------------
 # Convenience: observed-content bundle factory
@@ -591,29 +673,97 @@ __all__.append("observed_content")
 
 
 # ---------------------------------------------------------------------------
-# Process-wide default (opt-in)
+# Process-wide default (opt-in + env-var safety net, CRP 2.3)
 # ---------------------------------------------------------------------------
 
 
 _DEFAULT: ContextEnforcer | None = None
 _DEFAULT_LOCK = threading.Lock()
+_ENV_AUTO_INSTALL_DONE = False
+_ENV_VAR = "CRP_DEFAULT_ENFORCEMENT"
+
+
+def _maybe_install_from_env() -> None:
+    """Auto-install a default enforcer if ``CRP_DEFAULT_ENFORCEMENT`` is set.
+
+    Runs at most once per process. Accepted values (case-insensitive):
+    ``observe``, ``warn``, ``reject``, ``off``. Any other value is logged
+    and ignored. When ``CRP_MANIFEST_SECRET`` is present, an
+    :class:`~crp.core.manifest_ledger.EnvVarKeyProvider` is attached
+    automatically so signature verification works without further wiring.
+
+    This closes the footgun where an integrator forgets to call
+    :func:`set_default_enforcer` — operations teams can flip the env var
+    to ``observe`` in production and get an audit trail immediately.
+    """
+    global _ENV_AUTO_INSTALL_DONE, _DEFAULT
+    with _DEFAULT_LOCK:
+        if _ENV_AUTO_INSTALL_DONE:
+            return
+        _ENV_AUTO_INSTALL_DONE = True
+        if _DEFAULT is not None:
+            return  # Explicit opt-in wins — don't clobber.
+        import os as _os
+        raw = _os.environ.get(_ENV_VAR, "").strip().lower()
+        if raw in ("", "off", "none", "disabled", "0", "false"):
+            return
+        try:
+            policy = EnforcementPolicy(raw)
+        except ValueError:
+            logger.warning(
+                "CRP: %s=%r is invalid; expected observe/warn/reject/off",
+                _ENV_VAR,
+                raw,
+            )
+            return
+        key_provider: Any = None
+        if _os.environ.get("CRP_MANIFEST_SECRET"):
+            try:
+                from crp.core.manifest_ledger import EnvVarKeyProvider
+                key_provider = EnvVarKeyProvider()
+            except Exception as exc:  # pragma: no cover - defensive
+                logger.warning(
+                    "CRP: failed to build EnvVarKeyProvider from env: %s", exc
+                )
+        _DEFAULT = ContextEnforcer(policy=policy, key_provider=key_provider)
+        logger.info(
+            "CRP: installed default enforcer policy=%s from %s",
+            policy.value,
+            _ENV_VAR,
+        )
 
 
 def default_enforcer() -> ContextEnforcer | None:
     """Return the installed process-wide enforcer, or ``None``.
 
-    Returning None is intentional: CRP does not force enforcement on
-    applications that do not opt in. Consumers that want "off by default"
-    behaviour check for None and skip.
+    On first call, honours the ``CRP_DEFAULT_ENFORCEMENT`` environment
+    variable (``observe|warn|reject|off``) as a safety net when
+    :func:`set_default_enforcer` was never called. Explicit calls to
+    :func:`set_default_enforcer` always take precedence — env auto-install
+    only fires when no enforcer has been installed yet.
     """
+    _maybe_install_from_env()
     with _DEFAULT_LOCK:
         return _DEFAULT
 
 
 def set_default_enforcer(enforcer: ContextEnforcer | None) -> ContextEnforcer | None:
-    """Install *enforcer* as the process-wide default. Returns the previous one."""
-    global _DEFAULT
+    """Install *enforcer* as the process-wide default. Returns the previous one.
+
+    Marks env auto-install as "done" so a later ``default_enforcer()`` call
+    does not clobber an explicit ``None``.
+    """
+    global _DEFAULT, _ENV_AUTO_INSTALL_DONE
     with _DEFAULT_LOCK:
         old = _DEFAULT
         _DEFAULT = enforcer
+        _ENV_AUTO_INSTALL_DONE = True
         return old
+
+
+def _reset_default_enforcer_for_tests() -> None:
+    """Testing hook: clear the default + re-arm env auto-install."""
+    global _DEFAULT, _ENV_AUTO_INSTALL_DONE
+    with _DEFAULT_LOCK:
+        _DEFAULT = None
+        _ENV_AUTO_INSTALL_DONE = False

crprotocol-2.3.0/crp/core/ledger_backends.py

@@ -0,0 +1,186 @@
+# Copyright © 2025-2026 Constantinos Vidiniotis. All rights reserved.
+# Licensed under Elastic License 2.0 — see LICENSE.md for details.
+"""Ledger forwarding sinks (§7.14.5, CRP 2.3).
+
+CRP 2.2's :class:`~crp.core.manifest_ledger.ManifestLedger` wrote JSONL
+files to the local filesystem.  That is sufficient for a single node but
+fails in two real operational settings:
+
+* **Distributed workers** — multiple replicas need their ledger entries
+  aggregated in a central store (SIEM, SQL, data-lake) so auditors see a
+  single timeline.
+* **Tamper-evidence in depth** — the CRP 2.3 hash-chain catches edits on
+  the local JSONL file, but a root-level attacker could still delete the
+  file.  Forwarding every record to an append-only external system closes
+  that hole.
+
+These sinks implement the existing
+:class:`~crp.core.context_enforcer.AuditSink` protocol (``emit(event)``)
+so the same wiring serves enforcement events *and* ledger writes. Pass
+the sinks in via ``ManifestLedger(forward_to=[...])``.
+
+All sinks here are pure-stdlib. Production deployments should use HTTPS
+with rotating tokens and rely on the SIEM's native replay/retention.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import queue
+import threading
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any, Iterable
+
+__all__ = [
+    "JSONLinesFileSink",
+    "HTTPForwardingSink",
+    "AsyncBufferedSink",
+    "NullSink",
+]
+
+
+_log = logging.getLogger("crp.ledger_backends")
+
+
+class NullSink:
+    """No-op sink. Useful when a configuration requires a sink object but
+    nothing should be forwarded (e.g. in tests)."""
+
+    def emit(self, event: dict[str, Any]) -> None:  # noqa: D401
+        return
+
+
+class JSONLinesFileSink:
+    """Append every event as one JSON object per line to a local file.
+
+    Thread-safe: all writes are serialised on an internal lock. Intended
+    for replicating ledger records to a location monitored by Splunk
+    Universal Forwarder, Vector, Fluentd, etc.
+    """
+
+    def __init__(self, path: str | os.PathLike[str]) -> None:
+        self._path = Path(path)
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.Lock()
+
+    def emit(self, event: dict[str, Any]) -> None:
+        line = json.dumps(event, separators=(",", ":"), sort_keys=True, default=str)
+        with self._lock:
+            with self._path.open("a", encoding="utf-8") as fp:
+                fp.write(line)
+                fp.write("\n")
+
+
+class HTTPForwardingSink:
+    """POST every event as JSON to an HTTPS endpoint.
+
+    Intended for Splunk HEC, Elastic Common Schema ingest, Datadog Logs
+    HTTP intake, Azure Monitor, AWS CloudWatch Logs (via signed gateway),
+    or a bespoke SIEM collector.
+
+    Failures are logged at WARNING; the sink never raises out to the
+    caller. Callers that need guaranteed delivery should wrap this in
+    :class:`AsyncBufferedSink` and pair it with a retry layer.
+    """
+
+    def __init__(
+        self,
+        url: str,
+        *,
+        headers: dict[str, str] | None = None,
+        timeout: float = 3.0,
+    ) -> None:
+        if not url or not url.startswith(("http://", "https://")):
+            raise ValueError("HTTPForwardingSink: url must be http:// or https://")
+        self._url = url
+        self._headers = {
+            "Content-Type": "application/json",
+            "User-Agent": "crp-ledger-forwarder/1.0",
+        }
+        if headers:
+            self._headers.update(headers)
+        self._timeout = float(timeout)
+
+    def emit(self, event: dict[str, Any]) -> None:
+        body = json.dumps(event, separators=(",", ":"), default=str).encode("utf-8")
+        req = urllib.request.Request(
+            self._url, data=body, headers=self._headers, method="POST"
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                if resp.status >= 400:
+                    _log.warning(
+                        "CRP ledger HTTP forward non-2xx: %d %s",
+                        resp.status,
+                        self._url,
+                    )
+        except (urllib.error.URLError, TimeoutError, OSError) as exc:
+            _log.warning("CRP ledger HTTP forward failed: %s (%s)", self._url, exc)
+
+
+class AsyncBufferedSink:
+    """Background-thread buffer wrapping a downstream sink.
+
+    Enqueues events in memory (bounded; default 10k) and drains them on a
+    single worker thread. Keeps ledger writes off the hot path when the
+    downstream sink is slow or flaky.
+
+    Call :meth:`close` on shutdown to flush. Events that cannot be
+    enqueued (queue full) are dropped and logged — operators should size
+    the queue for their write rate.
+    """
+
+    def __init__(
+        self,
+        target: Any,
+        *,
+        max_queue: int = 10_000,
+        drain_on_close: bool = True,
+    ) -> None:
+        if not hasattr(target, "emit"):
+            raise TypeError("AsyncBufferedSink target must implement .emit()")
+        self._target = target
+        self._q: queue.Queue[dict[str, Any] | None] = queue.Queue(maxsize=max_queue)
+        self._drain_on_close = drain_on_close
+        self._stopped = threading.Event()
+        self._worker = threading.Thread(
+            target=self._run, name="crp-ledger-sink", daemon=True
+        )
+        self._worker.start()
+
+    def emit(self, event: dict[str, Any]) -> None:
+        if self._stopped.is_set():
+            return
+        try:
+            self._q.put_nowait(dict(event))
+        except queue.Full:
+            _log.warning("CRP ledger async sink full; dropping event")
+
+    def _run(self) -> None:
+        while True:
+            item = self._q.get()
+            if item is None:
+                return
+            try:
+                self._target.emit(item)
+            except Exception as exc:  # pragma: no cover - defensive
+                _log.warning("CRP ledger async target raised: %s", exc)
+            finally:
+                self._q.task_done()
+
+    def close(self, timeout: float = 5.0) -> None:
+        """Signal shutdown and (optionally) wait for the queue to drain."""
+        if self._stopped.is_set():
+            return
+        self._stopped.set()
+        if self._drain_on_close:
+            deadline = time.monotonic() + timeout
+            while not self._q.empty() and time.monotonic() < deadline:
+                time.sleep(0.01)
+        self._q.put(None)
+        self._worker.join(timeout=timeout)