connectonion 0.6.2__py3-none-any.whl → 0.6.4__py3-none-any.whl

connectonion/network/host/auth.py

@@ -0,0 +1,191 @@
+"""
+Purpose: Ed25519 signature verification and trust-based authentication for hosted agents
+LLM-Note:
+  Dependencies: imports from [network/trust/, llm_do.py, nacl.signing] | imported by [network/host/routes.py, network/host/server.py] | tested by [tests/network/test_host_auth.py]
+  Data flow: receives request dict with {payload, from, signature} → extract_and_authenticate() verifies Ed25519 signature via verify_signature() using nacl → checks timestamp expiry (5 min window) → applies trust policy (open/careful/strict/custom) → optionally evaluates via trust agent → returns (prompt, identity, sig_valid, error)
+  State/Effects: reads trust settings from agent | calls trust agent for evaluation if custom policy | no persistent state
+  Integration: exposes verify_signature(payload, signature, public_key) → bool, extract_and_authenticate(data, trust, blacklist, whitelist, agent_address) → (prompt, identity, sig_valid, error), get_agent_address(agent) → str, is_custom_trust(trust) → bool | used by host() to enforce authentication on all requests
+  Performance: signature verification uses nacl (fast Ed25519) | 5 minute timestamp window prevents replay | whitelist bypass for trusted callers
+  Errors: returns error strings: "unauthorized: ...", "forbidden: ...", "rejected: ..." | does NOT raise exceptions (caller checks error)
+Authentication and signature verification for hosted agents.
+"""
+
+import hashlib
+import json
+import time
+
+from ..trust import create_trust_agent, TRUST_LEVELS
+
+
+# Signature expiry window (5 minutes)
+SIGNATURE_EXPIRY_SECONDS = 300
+
+
+def verify_signature(payload: dict, signature: str, public_key: str) -> bool:
+    """Verify Ed25519 signature.
+
+    Args:
+        payload: The payload that was signed
+        signature: Hex-encoded signature (with or without 0x prefix)
+        public_key: Hex-encoded public key (with or without 0x prefix)
+
+    Returns:
+        True if signature is valid, False otherwise
+    """
+    from nacl.signing import VerifyKey
+    from nacl.exceptions import BadSignatureError
+
+    # Remove 0x prefix if present
+    sig_hex = signature[2:] if signature.startswith("0x") else signature
+    key_hex = public_key[2:] if public_key.startswith("0x") else public_key
+
+    # Canonicalize payload (deterministic JSON)
+    canonical = json.dumps(payload, sort_keys=True, separators=(",", ":"))
+
+    try:
+        verify_key = VerifyKey(bytes.fromhex(key_hex))
+        verify_key.verify(canonical.encode(), bytes.fromhex(sig_hex))
+        return True
+    except (BadSignatureError, ValueError):
+        # BadSignatureError: invalid signature
+        # ValueError: invalid hex encoding
+        return False
+
+
+def extract_and_authenticate(data: dict, trust, *, blacklist=None, whitelist=None, agent_address=None):
+    """Extract prompt and authenticate request.
+
+    ALL requests must be signed - this is a protocol requirement.
+
+    Required format (Ed25519 signed):
+        {
+            "payload": {"prompt": "...", "to": "0xAgentAddress", "timestamp": 123},
+            "from": "0xCallerPublicKey",
+            "signature": "0xEd25519Signature..."
+        }
+
+    Trust levels control additional policies AFTER signature verification:
+        - "open": Any valid signer allowed
+        - "careful": Warnings for unknown signers (default)
+        - "strict": Whitelist only
+        - Custom policy/Agent: LLM evaluation
+
+    Returns: (prompt, identity, sig_valid, error)
+    """
+    # Protocol requirement: ALL requests must be signed
+    if "payload" not in data or "signature" not in data:
+        return None, None, False, "unauthorized: signed request required"
+
+    # Verify signature (protocol level - always required)
+    prompt, identity, error = _authenticate_signed(
+        data, blacklist=blacklist, whitelist=whitelist, agent_address=agent_address
+    )
+    if error:
+        return prompt, identity, False, error
+
+    # Trust level: additional policies AFTER signature verification
+    if trust == "strict" and whitelist and identity not in whitelist:
+        return None, identity, True, "forbidden: not in whitelist"
+
+    # Custom trust policy/agent evaluation
+    if is_custom_trust(trust):
+        trust_agent = create_trust_agent(trust)
+        accepted, reason = evaluate_with_trust_agent(trust_agent, prompt, identity, True)
+        if not accepted:
+            return None, identity, True, f"rejected: {reason}"
+
+    return prompt, identity, True, None
+
+
+def _authenticate_signed(data: dict, *, blacklist=None, whitelist=None, agent_address=None):
+    """Authenticate signed request with Ed25519 - ALWAYS REQUIRED.
+
+    Protocol-level signature verification. All requests must be signed.
+
+    Returns: (prompt, identity, error) - error is None on success
+    """
+    payload = data.get("payload", {})
+    identity = data.get("from")
+    signature = data.get("signature")
+
+    prompt = payload.get("prompt", "")
+    timestamp = payload.get("timestamp")
+    to_address = payload.get("to")
+
+    # Check blacklist first
+    if blacklist and identity in blacklist:
+        return None, identity, "forbidden: blacklisted"
+
+    # Check whitelist (bypass signature check - trusted caller)
+    if whitelist and identity in whitelist:
+        return prompt, identity, None
+
+    # Validate required fields
+    if not identity:
+        return None, None, "unauthorized: 'from' field required"
+    if not signature:
+        return None, identity, "unauthorized: signature required"
+    if not timestamp:
+        return None, identity, "unauthorized: timestamp required in payload"
+
+    # Check timestamp expiry (5 minute window)
+    now = time.time()
+    if abs(now - timestamp) > SIGNATURE_EXPIRY_SECONDS:
+        return None, identity, "unauthorized: signature expired"
+
+    # Optionally verify 'to' matches agent address
+    if agent_address and to_address and to_address != agent_address:
+        return None, identity, "unauthorized: wrong recipient"
+
+    # Verify signature
+    if not verify_signature(payload, signature, identity):
+        return None, identity, "unauthorized: invalid signature"
+
+    return prompt, identity, None
+
+
+def get_agent_address(agent) -> str:
+    """Generate deterministic address from agent name."""
+    h = hashlib.sha256(agent.name.encode()).hexdigest()
+    return f"0x{h[:40]}"
+
+
+def evaluate_with_trust_agent(trust_agent, prompt: str, identity: str, sig_valid: bool) -> tuple[bool, str]:
+    """Evaluate request using a custom trust agent (policy or Agent).
+
+    Only called when trust is a policy string or custom Agent - NOT for simple levels.
+
+    Args:
+        trust_agent: The trust agent created from policy or custom Agent
+        prompt: The request prompt
+        identity: The requester's identity/address
+        sig_valid: Whether the signature is valid
+
+    Returns:
+        (accepted, reason) tuple
+    """
+    from pydantic import BaseModel
+    from ...llm_do import llm_do
+
+    class TrustDecision(BaseModel):
+        accept: bool
+        reason: str
+
+    request_info = f"""Evaluate this request:
+- prompt: {prompt[:200]}{'...' if len(prompt) > 200 else ''}
+- identity: {identity or 'anonymous'}
+- signature_valid: {sig_valid}"""
+
+    decision = llm_do(
+        request_info,
+        output=TrustDecision,
+        system_prompt=trust_agent.system_prompt,
+    )
+    return decision.accept, decision.reason
+
+
+def is_custom_trust(trust) -> bool:
+    """Check if trust needs a custom agent (policy or Agent, not a level)."""
+    if not isinstance(trust, str):
+        return True  # It's an Agent
+    return trust not in TRUST_LEVELS  # It's a policy string

connectonion/network/host/routes.py

@@ -0,0 +1,135 @@
+"""
+Purpose: HTTP/WebSocket route handlers for agent hosting endpoints
+LLM-Note:
+  Dependencies: imports from [network/host/session.py, connectonion/__init__.py] | imported by [network/host/server.py, network/asgi/http.py, network/asgi/websocket.py] | tested by [tests/network/test_host_routes.py]
+  Data flow: receives HTTP request → input_handler() calls create_agent() for fresh instance → server generates session_id (new) or uses existing (continuation) → calls agent.input(prompt, session) → stores result in SessionStorage → returns {session_id, status, result, duration_ms, session}
+  State/Effects: reads/writes SessionStorage via storage.save()/get()/list() | factory creates fresh agent per request (prevents state bleeding) | writes session records with TTL expiry | session_id always server-generated
+  Integration: exposes input_handler(create_agent, storage, prompt, result_ttl, session, connection), session_handler(storage, session_id), sessions_handler(storage), health_handler(agent_name, start_time), info_handler(agent_metadata, trust), admin_logs_handler(agent_name), admin_sessions_handler() | used by server.py and ASGI adapters
+  Performance: factory creates fresh agent per request (thread-safe, no deep copy issues) | SessionStorage TTL auto-cleanup | session continuation via session dict (multi-turn conversations)
+  Errors: session_handler returns None if session_id not found | admin_logs_handler returns {"error": "..."} if log file missing
+Route handlers for hosted agents.
+"""
+
+import time
+import uuid
+from pathlib import Path
+from typing import Callable
+
+from .session import Session, SessionStorage
+
+
+def input_handler(create_agent: Callable, storage: SessionStorage, prompt: str, result_ttl: int,
+                  session: dict | None = None, connection=None) -> dict:
+    """POST /input (and WebSocket /ws)
+
+    Args:
+        create_agent: Factory function that returns a fresh Agent instance
+        storage: SessionStorage for persisting results
+        prompt: The user's prompt
+        result_ttl: How long to keep the result on server
+        session: Optional conversation session for continuation
+        connection: WebSocket connection for bidirectional I/O (None for HTTP)
+    """
+    agent = create_agent()  # Fresh instance per request
+    agent.io = connection  # WebSocket connection or None for HTTP
+    now = time.time()
+
+    # Server generates session_id (new session) or uses existing (continuation)
+    # NOTE: We mutate `session` dict here, but it's safe - the dict is created
+    # fresh from json.loads() per request, not shared anywhere.
+    session = session or {}
+    session_id = session.get('session_id') or str(uuid.uuid4())
+    session['session_id'] = session_id
+
+    # Create storage record
+    record = Session(
+        session_id=session_id,
+        status="running",
+        prompt=prompt,
+        created=now,
+        expires=now + result_ttl,
+    )
+    storage.save(record)
+
+    # TODO: If agent.input() throws, record stays "running" until TTL expires.
+    # This is acceptable: client gets 500 error, record expires naturally.
+    start = time.time()
+    result = agent.input(prompt, session=session)
+    duration_ms = int((time.time() - start) * 1000)
+
+    record.status = "done"
+    record.result = result
+    record.duration_ms = duration_ms
+    storage.save(record)
+
+    # Return result with updated session for client to continue conversation
+    return {
+        "session_id": session_id,
+        "status": "done",
+        "result": result,
+        "duration_ms": duration_ms,
+        "session": agent.current_session
+    }
+
+
+def session_handler(storage: SessionStorage, session_id: str) -> dict | None:
+    """GET /sessions/{id}"""
+    session = storage.get(session_id)
+    return session.model_dump() if session else None
+
+
+def sessions_handler(storage: SessionStorage) -> dict:
+    """GET /sessions"""
+    return {"sessions": [s.model_dump() for s in storage.list()]}
+
+
+def health_handler(agent_name: str, start_time: float) -> dict:
+    """GET /health"""
+    return {"status": "healthy", "agent": agent_name, "uptime": int(time.time() - start_time)}
+
+
+def info_handler(agent_metadata: dict, trust: str) -> dict:
+    """GET /info
+
+    Returns pre-extracted metadata - no agent creation needed.
+    """
+    from ... import __version__
+    return {
+        "name": agent_metadata["name"],
+        "address": agent_metadata["address"],
+        "tools": agent_metadata["tools"],
+        "trust": trust,
+        "version": __version__,
+    }
+
+
+def admin_logs_handler(agent_name: str) -> dict:
+    """GET /admin/logs - return plain text activity log file."""
+    log_path = Path(f".co/logs/{agent_name}.log")
+    if log_path.exists():
+        return {"content": log_path.read_text()}
+    return {"error": "No logs found"}
+
+
+def admin_sessions_handler() -> dict:
+    """GET /admin/sessions - return raw session YAML files as JSON.
+
+    Returns session files as-is (converted from YAML to JSON). Each session
+    contains: name, created, updated, total_cost, total_tokens, turns array.
+    Frontend handles the display logic.
+    """
+    import yaml
+    sessions_dir = Path(".co/evals")
+    if not sessions_dir.exists():
+        return {"sessions": []}
+
+    sessions = []
+    for session_file in sessions_dir.glob("*.yaml"):
+        with open(session_file) as f:
+            session_data = yaml.safe_load(f)
+            if session_data:
+                sessions.append(session_data)
+
+    # Sort by updated date descending (newest first)
+    sessions.sort(key=lambda s: s.get("updated", s.get("created", "")), reverse=True)
+    return {"sessions": sessions}

connectonion/network/host/server.py

@@ -0,0 +1,289 @@
+"""
+Purpose: Host agent as HTTP/WebSocket server with trust-based access control
+LLM-Note:
+  Dependencies: imports from [network/asgi/, network/trust/, network/host/session.py, network/host/auth.py, network/host/routes.py] | imported by [network/__init__.py as host()] | tested by [tests/network/test_host.py]
+  Data flow: host(create_agent, port, trust) → _create_route_handlers() wraps all routes → asgi_create_app() creates FastAPI/Starlette app → uvicorn.run() starts server → each request calls create_agent() for fresh instance → executes via input_handler()/ws_input() → returns result + session | trust enforcement via extract_and_authenticate() at request boundary
+  State/Effects: starts HTTP server on specified port | creates .co/logs/ directory | stores sessions in SessionStorage (in-memory with TTL) | optionally announces to relay server | each request gets fresh agent instance (no state bleeding)
+  Integration: exposes host(create_agent, port=8000, trust=None, result_ttl=3600, relay_url=None) | creates ASGI app with routes: POST /input, GET /sessions, GET /sessions/{id}, GET /health, GET /info, WebSocket /ws, admin endpoints | trust accepts: "open"/"careful"/"strict" (level), markdown string (policy), or Agent (custom verifier)
+  Performance: factory pattern creates fresh agent per request (thread-safe) | SessionStorage auto-expires old results via TTL | WebSocket supports real-time bidirectional I/O | relay connection runs in background thread
+  Errors: trust errors return 401/403 via extract_and_authenticate() | missing sessions return None (404) | raises if port already in use
+Host an agent over HTTP/WebSocket.
+
+Trust enforcement happens at the host level, not in the Agent.
+This provides clean separation: Agent does work, host controls access.
+
+Trust parameter accepts three forms:
+1. Level (string): "open", "careful", "strict"
+2. Policy (string): Natural language or file path
+3. Agent: Custom Agent instance for verification
+
+All forms create a trust agent behind the scenes.
+
+Worker Isolation:
+Each request calls the create_agent factory to get a fresh agent instance.
+This ensures complete isolation - tools with state (like BrowserTool)
+don't interfere between concurrent requests.
+"""
+
+import os
+from pathlib import Path
+from typing import Callable, Union
+
+from rich.console import Console
+from rich.panel import Panel
+
+from ..asgi import create_app as asgi_create_app
+from ..trust import get_default_trust_level
+from .session import SessionStorage
+from .auth import extract_and_authenticate
+from .routes import (
+    input_handler,
+    session_handler,
+    sessions_handler,
+    health_handler,
+    info_handler,
+    admin_logs_handler,
+    admin_sessions_handler,
+)
+
+
+def get_default_trust() -> str:
+    """Get default trust based on environment.
+
+    Returns:
+        Trust level based on CONNECTONION_ENV, defaults to 'careful'
+    """
+    return get_default_trust_level() or "careful"
+
+
+def _extract_agent_metadata(create_agent: Callable) -> tuple[dict, object]:
+    """Extract metadata from a sample agent instance.
+
+    Returns:
+        (metadata dict, sample_agent) - sample_agent for additional extraction
+    """
+    sample = create_agent()
+    metadata = {
+        "name": sample.name,
+        "tools": sample.tools.names(),
+    }
+    return metadata, sample
+
+
+def _create_route_handlers(create_agent: Callable, agent_metadata: dict, result_ttl: int):
+    """Create route handler dict for ASGI app.
+
+    Args:
+        create_agent: Factory function that returns a fresh Agent instance.
+                      Called once per request for isolation.
+        agent_metadata: Pre-extracted metadata (name, tools, address) - avoids
+                        creating agents for health/info endpoints.
+        result_ttl: How long to keep results on server in seconds
+    """
+    agent_name = agent_metadata["name"]
+
+    def handle_input(storage, prompt, session=None, connection=None):
+        return input_handler(create_agent, storage, prompt, result_ttl, session, connection)
+
+    def handle_ws_input(storage, prompt, connection, session=None):
+        return input_handler(create_agent, storage, prompt, result_ttl, session, connection)
+
+    def handle_health(start_time):
+        return health_handler(agent_name, start_time)
+
+    def handle_info(trust):
+        return info_handler(agent_metadata, trust)
+
+    def handle_admin_logs():
+        return admin_logs_handler(agent_name)
+
+    return {
+        "input": handle_input,
+        "session": session_handler,
+        "sessions": sessions_handler,
+        "health": handle_health,
+        "info": handle_info,
+        "auth": extract_and_authenticate,
+        "ws_input": handle_ws_input,
+        "admin_logs": handle_admin_logs,
+        "admin_sessions": admin_sessions_handler,
+    }
+
+
+def _start_relay_background(create_agent: Callable, relay_url: str, addr_data: dict, agent_summary: str):
+    """Start relay connection in background thread.
+
+    The relay connection runs alongside the HTTP server, allowing the agent
+    to be discovered via P2P network while also serving HTTP requests.
+
+    Args:
+        create_agent: Factory function that returns a fresh Agent instance
+        relay_url: WebSocket URL for P2P relay
+        addr_data: Agent address data (public key, address)
+        agent_summary: Summary text for relay announcement
+    """
+    import asyncio
+    import threading
+    from .. import announce, relay
+
+    # Create ANNOUNCE message
+    announce_msg = announce.create_announce_message(addr_data, agent_summary, endpoints=[])
+
+    # Task handler - fresh instance for each request
+    # NOTE: agent.input() is synchronous inside async function, but this runs in
+    # a separate thread with its own event loop (not uvicorn's). Only blocks the
+    # relay thread, not the HTTP server. Could use asyncio.to_thread() if relay
+    # needs concurrent task handling or heartbeat during execution.
+    async def task_handler(prompt: str) -> str:
+        agent = create_agent()
+        return agent.input(prompt)
+
+    async def relay_loop():
+        ws = await relay.connect(relay_url)
+        await relay.serve_loop(ws, announce_msg, task_handler)
+
+    def run():
+        asyncio.run(relay_loop())
+
+    thread = threading.Thread(target=run, daemon=True, name="relay-connection")
+    thread.start()
+    return thread
+
+
+def host(
+    create_agent: Callable,
+    port: int = None,
+    trust: Union[str, "Agent"] = "careful",
+    result_ttl: int = 86400,
+    workers: int = 1,
+    reload: bool = False,
+    *,
+    relay_url: str = "wss://oo.openonion.ai",
+    blacklist: list | None = None,
+    whitelist: list | None = None,
+):
+    """
+    Host an agent over HTTP/WebSocket with optional P2P relay discovery.
+
+    Each request calls create_agent() to get a fresh Agent instance.
+    This ensures complete isolation between concurrent requests.
+
+    State Control via Closure:
+        # Isolated state (default, safest) - create inside:
+        def create_agent():
+            browser = BrowserTool()  # Fresh per request
+            return Agent("assistant", tools=[browser])
+
+        # Shared state (advanced) - create outside, capture via closure:
+        browser = BrowserTool()  # Shared across all requests
+        def create_agent():
+            return Agent("assistant", tools=[browser])
+
+    Args:
+        create_agent: Function that returns a fresh Agent instance.
+                      Called once per request. Define tools inside for isolation,
+                      or outside for shared state.
+        port: HTTP port (default: PORT env var or 8000)
+        trust: Trust level, policy, or Agent:
+            - Level: "open", "careful", "strict"
+            - Policy: Natural language or file path
+            - Agent: Custom trust agent
+        result_ttl: How long to keep results on server in seconds (default 24h)
+        workers: Number of worker processes
+        reload: Auto-reload on code changes
+        relay_url: P2P relay URL (default: production relay)
+            - Set to None to disable relay
+        blacklist: Blocked identities
+        whitelist: Allowed identities
+
+    Endpoints:
+        POST /input         - Submit prompt, get result
+        GET  /sessions/{id} - Get session by ID
+        GET  /sessions      - List all sessions
+        GET  /health        - Health check
+        GET  /info          - Agent info
+        WS   /ws            - WebSocket
+        GET  /logs          - Activity log (requires OPENONION_API_KEY)
+        GET  /logs/sessions - Activity sessions (requires OPENONION_API_KEY)
+    """
+    import uvicorn
+    from ... import address
+
+    # Use PORT env var if port not specified (for container deployments)
+    if port is None:
+        port = int(os.environ.get("PORT", 8000))
+
+    # Extract metadata once at startup
+    agent_metadata, sample = _extract_agent_metadata(create_agent)
+    agent_summary = sample.system_prompt[:1000] if sample.system_prompt else f"{agent_metadata['name']} agent"
+
+    # Load or generate agent identity
+    co_dir = Path.cwd() / '.co'
+    addr_data = address.load(co_dir)
+
+    if addr_data is None:
+        addr_data = address.generate()
+        address.save(addr_data, co_dir)
+
+    agent_metadata["address"] = addr_data['address']
+
+    storage = SessionStorage()
+    route_handlers = _create_route_handlers(create_agent, agent_metadata, result_ttl)
+    app = asgi_create_app(
+        route_handlers=route_handlers,
+        storage=storage,
+        trust=trust,
+        blacklist=blacklist,
+        whitelist=whitelist,
+    )
+
+    # Start relay connection in background (if enabled)
+    if relay_url:
+        _start_relay_background(create_agent, relay_url, addr_data, agent_summary)
+
+    # Display startup info
+    relay_status = f"[green]✓[/] {relay_url}" if relay_url else "[dim]disabled[/]"
+    Console().print(Panel(
+        f"[bold]POST[/] http://localhost:{port}/input\n"
+        f"[dim]GET  /sessions/{{id}} · /sessions · /health · /info[/]\n"
+        f"[dim]WS   ws://localhost:{port}/ws\n"
+        f"[dim]UI   http://localhost:{port}/docs[/]\n\n"
+        f"[bold]Address:[/] {agent_metadata['address']}\n"
+        f"[bold]Relay:[/]   {relay_status}",
+        title=f"[green]Agent '{agent_metadata['name']}'[/]"
+    ))
+
+    uvicorn.run(app, host="0.0.0.0", port=port, workers=workers, reload=reload, log_level="warning")
+
+
+def create_app(create_agent: Callable, storage=None, trust="careful", result_ttl=86400, *, blacklist=None, whitelist=None):
+    """Create ASGI app for external uvicorn/gunicorn usage.
+
+    Each request calls create_agent() to get a fresh Agent instance.
+
+    Usage:
+        from connectonion.network import create_app
+
+        def create_agent():
+            return Agent("assistant", tools=[search])
+
+        app = create_app(create_agent)
+        # uvicorn myagent:app --workers 4
+    """
+    from .auth import get_agent_address
+
+    if storage is None:
+        storage = SessionStorage()
+
+    # Extract metadata once at startup
+    agent_metadata, sample = _extract_agent_metadata(create_agent)
+    agent_metadata["address"] = get_agent_address(sample)
+
+    route_handlers = _create_route_handlers(create_agent, agent_metadata, result_ttl)
+    return asgi_create_app(
+        route_handlers=route_handlers,
+        storage=storage,
+        trust=trust,
+        blacklist=blacklist,
+        whitelist=whitelist,
+    )