clm-kernel 0.0.0__py3-none-any.whl

clm/layer4/eoa_sponsor.py

@@ -0,0 +1,232 @@
+"""EOA Sponsor Signing Surface — Sprint 138.4.
+
+Provides the human-facing cryptographic boundary where EOA (Externally Owned
+Agent) volition enters the CLM OS. A PCard cannot fire until the human EOA
+signs the VCard pre-gate with their Ed25519 ``did:key:*`` keypair.
+
+CLI usage:
+    clm-sponsor --generate-keypair
+    clm-sponsor --pcard <handle> --intent <text>
+
+The keypair is stored at ``~/.clm/eoa_keypair.ed25519`` (or
+``$CLM_EOA_KEYPAIR_PATH``). Only the private key PEM is stored on disk;
+the public DID is derived on demand.
+"""
+
+import argparse
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from clm.cross_cutting.clm_logger import get_logger
+from clm.layer0.utils import clm_hash_string
+
+_logger = get_logger("clm.layer4.eoa_sponsor")
+
+
+def _keypair_path() -> Path:
+    """Return the path to the EOA keypair file."""
+    env = os.environ.get("CLM_EOA_KEYPAIR_PATH")
+    if env:
+        return Path(env)
+    return Path.home() / ".clm" / "eoa_keypair.ed25519"
+
+
+def generate_keypair() -> dict:
+    """Generate an Ed25519 keypair and store it on disk.
+
+    Returns a dict with ``private_pem``, ``public_pem``, and ``did``.
+    """
+    from clm.layer1.verifier import clm_derive_session_key
+
+    keypair = clm_derive_session_key()
+    path = _keypair_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(keypair["private_key"])
+    path.chmod(0o600)
+    return keypair
+
+
+def load_private_key() -> Ed25519PrivateKey:
+    """Load the EOA Ed25519 private key from disk."""
+    path = _keypair_path()
+    if not path.exists():
+        raise FileNotFoundError(
+            f"EOA keypair not found at {path}. Run 'clm-sponsor --generate-keypair' first."
+        )
+    pem = path.read_bytes()
+    return serialization.load_pem_private_key(pem, password=None)
+
+
+def derive_did() -> str:
+    """Derive the ``did:key:*`` DID from the stored EOA keypair."""
+    from clm.layer1.verifier import pem_to_did
+
+    private_key = load_private_key()
+    public_pem = private_key.public_key().public_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+    return pem_to_did(public_pem)
+
+
+def derive_did_from_pubkey(public_key) -> str:
+    """Derive did:key:z* from an Ed25519PublicKey object."""
+    from clm.layer1.verifier import pem_to_did
+    public_pem = public_key.public_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+    return pem_to_did(public_pem)
+
+
+def generate_in_memory_keypair():
+    """Generate in-memory Ed25519PrivateKey and its did:key:z* string."""
+    from cryptography.hazmat.primitives.asymmetric import ed25519
+    private_key = ed25519.Ed25519PrivateKey.generate()
+    did = derive_did_from_pubkey(private_key.public_key())
+    return private_key, did
+
+
+def sign_intent_with_key(
+    private_key,
+    pcard_handle: str,
+    intent: str,
+    timestamp: str | None = None,
+    use_blake3: bool = True,
+) -> dict:
+    """Sign intent using an in-memory Ed25519 private key."""
+    if use_blake3:
+        from clm.layer0.hash import compute_blake3
+        intent_hash = compute_blake3(intent)
+    else:
+        intent_hash = clm_hash_string(intent)
+
+    if timestamp is None:
+        timestamp = time.strftime("%Y-%m-%dT%H:%M:%S%z")
+
+    sponsor_did = derive_did_from_pubkey(private_key.public_key())
+    payload = f"{pcard_handle}:{intent_hash}:{timestamp}".encode()
+    signature = private_key.sign(payload)
+    sig_hex = signature.hex()
+
+    return {
+        "sponsor_did": sponsor_did,
+        "pcard_handle": pcard_handle,
+        "intent": intent,
+        "intent_hash": intent_hash,
+        "signature": sig_hex,
+        "timestamp": timestamp,
+    }
+
+
+def sign_intent(pcard_handle: str, intent: str, timestamp: str | None = None, use_blake3: bool = True) -> dict:
+    """Sign the VCard pre-gate hash for a PCard intent using the on-disk key."""
+    private_key = load_private_key()
+    return sign_intent_with_key(private_key, pcard_handle, intent, timestamp, use_blake3=use_blake3)
+
+
+def verify_signature(sponsor_did: str, pcard_handle: str, intent_hash: str, timestamp: str, signature_hex: str) -> bool:
+    """Verify a VCard pre-gate signature against a sponsor DID."""
+    from clm.layer1.verifier import did_to_pubkey
+
+    pubkey = did_to_pubkey(sponsor_did)
+    payload = f"{pcard_handle}:{intent_hash}:{timestamp}".encode()
+    signature = bytes.fromhex(signature_hex)
+    try:
+        pubkey.verify(signature, payload)
+        return True
+    except Exception:
+        return False
+
+
+def commit_sponsor_did(run_id: str, sponsor_did: str, signature_hex: str) -> str:
+    """Commit the sponsor_did to the run:<run_id>:sponsor handle.
+
+    This follows the Sprint 44 pattern of committing sponsor identity
+    to a handle in the execution_log pillar.
+    """
+    import sqlite3
+
+    db_path = os.environ.get("CLM_DB_PATH", os.path.join(os.getcwd(), "db", "execution_log.db"))
+    handle_name = f"run:{run_id}:sponsor"
+    content = json.dumps({"sponsor_did": sponsor_did, "signature": signature_hex})
+    content_hash = clm_hash_string(content)
+    ts = time.strftime("%Y-%m-%dT%H:%M:%S%z")
+
+    conn = sqlite3.connect(db_path)
+    cursor = conn.cursor()
+    cursor.execute(
+        "INSERT OR REPLACE INTO card (hash, content, g_time) VALUES (?, ?, ?)",
+        (content_hash, content, ts),
+    )
+    cursor.execute(
+        "INSERT OR REPLACE INTO handle_registry (handle, current_hash, created_at, updated_at) VALUES (?, ?, ?, ?)",
+        (handle_name, content_hash, ts, ts),
+    )
+    conn.commit()
+    conn.close()
+    return content_hash
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="clm-sponsor",
+        description="EOA Sponsor Signing Surface — sign VCard pre-gates with Ed25519 did:key",
+    )
+    parser.add_argument(
+        "--generate-keypair",
+        action="store_true",
+        help="Generate a new Ed25519 keypair at ~/.clm/eoa_keypair.ed25519",
+    )
+    parser.add_argument("--pcard", metavar="HANDLE", help="PCard handle to sponsor")
+    parser.add_argument("--intent", metavar="TEXT", help="Intent text to sign")
+    parser.add_argument("--run-id", metavar="ID", default="default", help="Run ID for sponsor handle")
+    parser.add_argument("--yes", action="store_true", help="Skip confirmation prompt")
+    args = parser.parse_args()
+
+    if args.generate_keypair:
+        kp = generate_keypair()
+        print(f"[sponsor] Keypair generated at {_keypair_path()}")
+        print(f"[sponsor] Sponsor DID: {kp['did']}")
+        sys.exit(0)
+
+    if not args.pcard or not args.intent:
+        parser.error("--pcard and --intent are required (unless --generate-keypair)")
+
+    try:
+        sponsor_did = derive_did()
+    except FileNotFoundError as e:
+        _logger.error(f"[sponsor] Error: {e}")
+        sys.exit(1)
+
+    print(f"[sponsor] Pending PCard: {args.pcard}")
+    print(f"[sponsor] Intent: \"{args.intent}\"")
+    print(f"[sponsor] Sponsor DID: {sponsor_did}")
+
+    if not args.yes:
+        response = input("[sponsor] Sign VCard pre-gate? [y/N]: ")
+        if response.lower() != "y":
+            print("[sponsor] Aborted.")
+            sys.exit(1)
+
+    result = sign_intent(args.pcard, args.intent)
+    print("[sponsor] VCard pre-gate signed.")
+    print(f"[sponsor] Intent hash: {result['intent_hash']}")
+    print(f"[sponsor] Signature: {result['signature'][:32]}...")
+
+    content_hash = commit_sponsor_did(args.run_id, result["sponsor_did"], result["signature"])
+    print(f"[sponsor] sponsor_did committed to run:{args.run_id}:sponsor (hash: {content_hash[:16]}...)")
+    print("[sponsor] Dispatching to Flux...")
+
+    # Output JSON for programmatic consumption
+    print(f"SPONSOR_RESULT:{json.dumps(result)}")
+
+
+if __name__ == "__main__":
+    main()

clm/layer4/events.py

@@ -0,0 +1,69 @@
+"""Structured Event Log & Execution Receipts — Sprint 364.
+
+Canonical Path: kernel/scripts/clm/layer4/events.py
+Parity: Rust `src/layer4/events.rs`, TypeScript `src/layer4/events.ts`
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from enum import Enum
+from typing import Any
+
+from clm.layer0.hash import compute_blake3
+
+
+@dataclass
+class ExecutionEvent:
+    transition_id: str
+    transition_name: str
+    source_places: list[str]
+    target_places: list[str]
+    token_deltas: dict[str, Any]
+    timestamp: str
+
+
+@dataclass
+class EventLog:
+    run_id: str
+    sponsor_did: str
+    events: list[ExecutionEvent] = field(default_factory=list)
+
+    def append_event(self, event: ExecutionEvent) -> None:
+        self.events.append(event)
+
+    def to_canonical_json(self) -> str:
+        data = {
+            "run_id": self.run_id,
+            "sponsor_did": self.sponsor_did,
+            "events": [asdict(e) for e in self.events],
+        }
+        return json.dumps(data, separators=(",", ":"))
+
+    def compute_receipt_hash(self) -> str:
+        canonical = self.to_canonical_json()
+        return compute_blake3(canonical)
+
+
+class EventType(str, Enum):
+    MARKING_CHANGED = "marking_changed"
+    TRANSITION_FIRED = "transition_fired"
+    ERROR = "error"
+    GATEWAY_CONNECT = "gateway_connect"
+    GATEWAY_DISCONNECT = "gateway_disconnect"
+
+
+@dataclass
+class GatewayEvent:
+    event_type: EventType | str
+    payload: dict[str, Any]
+    timestamp: str
+
+
+__all__ = [
+    "ExecutionEvent",
+    "EventLog",
+    "EventType",
+    "GatewayEvent",
+]

clm/layer4/flux_gateway.py

@@ -0,0 +1,133 @@
+"""Layer 4 Flux-as-Petri-Net Gateway & Grafana Faro / Loki Telemetry (DEL-391-02, INV-391-02).
+
+Bridges frontend user action intents into typed CPN ingress tokens:
+- Homomorphic mapping from MembraneAction to CPN transition firing.
+- Injects W3C `traceparent` headers into distributed action payloads (faroFluxMiddleware).
+- Projects updated Petri net markings back into MembraneEvent streams and ActionResult responses.
+"""
+from __future__ import annotations
+
+import re
+import time
+import uuid
+from typing import Any, Dict, Optional
+
+from clm.layer0.hash import compute_blake3
+from clm.layer4.membrane import ActionResult, MembraneAction, MembraneSession
+
+# W3C Trace Context regex: version-trace_id-parent_id-trace_flags
+W3C_TRACEPARENT_REGEX = re.compile(r"^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$")
+
+
+def generate_w3c_traceparent(
+    trace_id: Optional[str] = None,
+    parent_id: Optional[str] = None,
+    flags: str = "01",
+) -> str:
+    """Generates a valid W3C traceparent header string (version 00).
+    Format: 00-{trace_id_32hex}-{parent_id_16hex}-{flags_2hex}
+    """
+    t_id = trace_id or uuid.uuid4().hex
+    p_id = parent_id or uuid.uuid4().hex[:16]
+    return f"00-{t_id}-{p_id}-{flags}"
+
+
+def parse_w3c_traceparent(traceparent: str) -> Dict[str, str]:
+    """Parses a W3C traceparent header string into its components."""
+    match = W3C_TRACEPARENT_REGEX.match(traceparent)
+    if not match:
+        raise ValueError(f"Invalid W3C traceparent format: '{traceparent}'")
+    return {
+        "version": match.group(1),
+        "trace_id": match.group(2),
+        "parent_id": match.group(3),
+        "flags": match.group(4),
+    }
+
+
+def faro_flux_middleware(action: MembraneAction) -> MembraneAction:
+    """Faro telemetry middleware ensuring W3C traceparent injection into MembraneAction payload."""
+    payload = dict(action.payload)
+    if "traceparent" not in payload or not payload["traceparent"]:
+        payload["traceparent"] = generate_w3c_traceparent()
+    return MembraneAction(action_type=action.action_type, payload=payload)
+
+
+class FluxPetriGateway:
+    """Pluggable Flux-as-Petri-Net Gateway connecting MembraneActions to CPN transitions."""
+
+    def __init__(self, scheduler: Any = None) -> None:
+        self.scheduler = scheduler
+
+    def dispatch_action(
+        self,
+        action: MembraneAction,
+        session: Optional[MembraneSession] = None,
+        timestamp: Optional[str] = None,
+    ) -> ActionResult:
+        """Dispatches a user action intent into the CPN VM substrate with W3C telemetry."""
+        ts = timestamp or time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+        sess = session or MembraneSession(session_id="flux-default", user_did="did:clm:operator")
+
+        # Step 1: Inject W3C telemetry via faroFluxMiddleware
+        instrumented_action = faro_flux_middleware(action)
+        traceparent = instrumented_action.payload["traceparent"]
+
+        # Step 2: Compute intent hash
+        raw_repr = f"{instrumented_action.action_type}:{instrumented_action.payload}"
+        intent_hash = compute_blake3(raw_repr)
+
+        # Step 3: Emit ingress token event into CPN marking
+        sess.push_event(
+            event_type="flux_ingress_token",
+            payload={
+                "action_type": instrumented_action.action_type,
+                "intent_hash": intent_hash,
+                "traceparent": traceparent,
+            },
+            timestamp=ts,
+        )
+
+        # Step 4: Execute transition through scheduler if available
+        result_message = f"Flux action '{instrumented_action.action_type}' dispatched"
+        if self.scheduler is not None and hasattr(self.scheduler, "execute_step"):
+            try:
+                step_res = self.scheduler.execute_step(instrumented_action.payload)
+                result_message = f"CPN VM executed: {step_res}"
+            except Exception as e:
+                sess.push_event(
+                    event_type="flux_execution_error",
+                    payload={"error": str(e), "traceparent": traceparent},
+                    timestamp=ts,
+                )
+                return ActionResult(
+                    success=False,
+                    message=f"CPN VM transition failed: {e}",
+                    emitted_cards=[],
+                )
+
+        # Step 5: Project updated Petri net marking
+        sess.push_event(
+            event_type="flux_marking_projected",
+            payload={
+                "intent_hash": intent_hash,
+                "emitted_card": intent_hash,
+                "traceparent": traceparent,
+            },
+            timestamp=ts,
+        )
+
+        return ActionResult(
+            success=True,
+            message=result_message,
+            emitted_cards=[intent_hash],
+        )
+
+
+__all__ = [
+    "W3C_TRACEPARENT_REGEX",
+    "generate_w3c_traceparent",
+    "parse_w3c_traceparent",
+    "faro_flux_middleware",
+    "FluxPetriGateway",
+]

clm/layer4/gateway.py

@@ -0,0 +1,91 @@
+"""Headless Gateway Router — Sprint 364.
+
+Canonical Path: kernel/scripts/clm/layer4/gateway.py
+Parity: Rust `src/layer4/gateway.rs`, TypeScript `src/layer4/gateway/`
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from clm.layer0.hash import compute_blake3
+
+
+class GatewayRouter:
+    def __init__(self) -> None:
+        self.card_registry: dict[str, Any] = {}
+
+    def register_card(self, card_hash: str, content: Any) -> None:
+        self.card_registry[card_hash] = content
+
+    def dispatch(self, request: dict[str, Any]) -> dict[str, Any]:
+        req_id = request.get("id")
+        if request.get("jsonrpc") != "2.0":
+            return {
+                "jsonrpc": "2.0",
+                "id": req_id,
+                "error": {
+                    "code": -32600,
+                    "message": "Invalid Request: jsonrpc must be '2.0'",
+                },
+            }
+
+        method = request.get("method")
+        params = request.get("params") or {}
+
+        if method == "clm.status":
+            return {
+                "jsonrpc": "2.0",
+                "id": req_id,
+                "result": {
+                    "status": "ready",
+                    "layers": [0, 1, 2, 3, 4],
+                    "registered_cards": len(self.card_registry),
+                },
+            }
+        elif method == "clm.eval":
+            expr = params.get("expression", "")
+            content_hash = compute_blake3(expr)
+            return {
+                "jsonrpc": "2.0",
+                "id": req_id,
+                "result": {
+                    "evaluated": expr,
+                    "content_hash": content_hash,
+                    "success": True,
+                },
+            }
+        elif method == "clm.card_get":
+            card_hash = params.get("hash", "")
+            if card_hash in self.card_registry:
+                return {
+                    "jsonrpc": "2.0",
+                    "id": req_id,
+                    "result": self.card_registry[card_hash],
+                }
+            return {
+                "jsonrpc": "2.0",
+                "id": req_id,
+                "error": {
+                    "code": -32004,
+                    "message": f"Card not found: {card_hash}",
+                },
+            }
+        else:
+            return {
+                "jsonrpc": "2.0",
+                "id": req_id,
+                "error": {
+                    "code": -32601,
+                    "message": f"Method not found: {method}",
+                },
+            }
+
+
+# Alias for coordinating frameworks and canary verification
+CLMGateway = GatewayRouter
+
+__all__ = [
+    "GatewayRouter",
+    "CLMGateway",
+]