connectonion 0.6.3__py3-none-any.whl → 0.6.5__py3-none-any.whl

connectonion/network/host/auth.py

@@ -1,20 +1,25 @@
 """
 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)
+  Dependencies: imports from [network/trust/TrustAgent, nacl.signing] | imported by [network/host/routes.py, network/host/server.py] | tested by [tests/unit/test_host_auth.py]
+  Data flow: receives request dict with {payload, from, signature} → extract_and_authenticate() verifies Ed25519 signature → uses TrustAgent.should_allow() for trust decisions (fast rules + LLM fallback) → returns (prompt, identity, sig_valid, error)
+  State/Effects: TrustAgent handles all trust state (whitelist, contacts, blocklist in ~/.co/)
+  Integration: exposes verify_signature(), extract_and_authenticate(), get_agent_address(), is_custom_trust() | used by host() to enforce authentication
+  Performance: TrustAgent.should_allow() runs fast rules first (zero tokens), only uses LLM for 'ask' cases
+  Errors: returns error strings: "unauthorized: ...", "forbidden: ..." | does NOT raise exceptions
 Authentication and signature verification for hosted agents.
+
+Trust evaluation (via TrustAgent.should_allow()):
+1. Parameter whitelist (highest priority, instant allow)
+2. Signature verification (protocol level)
+3. TrustAgent handles fast rules + LLM fallback
 """
 
 import hashlib
 import json
 import time
 
-from ..trust import create_trust_agent, TRUST_LEVELS
+from ..trust import TrustAgent, TRUST_LEVELS
 
 
 # Signature expiry window (5 minutes)
@@ -64,10 +69,29 @@ def extract_and_authenticate(data: dict, trust, *, blacklist=None, whitelist=Non
             "signature": "0xEd25519Signature..."
         }
 
-    Trust levels control additional policies AFTER signature verification:
-        - "open": Any valid signer allowed
-        - "careful": Warnings for unknown signers (default)
-        - "strict": Whitelist only
+    Onboarding (in payload):
+        {
+            "payload": {"prompt": "...", "invite_code": "BETA2024", ...}
+        }
+        or:
+        {
+            "payload": {"prompt": "...", "payment": 10, ...}
+        }
+
+    Authentication flow:
+        1. Signature verification (protocol level, always required)
+        2. Parameter whitelist check (instant allow if match)
+        3. Fast rules from YAML config:
+           - allow: [whitelisted, contact]  → instant allow
+           - deny: [blocked]                → instant deny
+           - onboard: {invite_code, payment} → promote stranger to contact
+           - default: allow | deny | ask    → final decision
+        4. Trust agent (only if fast rules return None for 'ask' cases)
+
+    Trust levels (predefined YAML configs):
+        - "open": default=allow (development)
+        - "careful": default=ask (staging)
+        - "strict": allow=[whitelisted], default=deny (production)
         - Custom policy/Agent: LLM evaluation
 
     Returns: (prompt, identity, sig_valid, error)
@@ -76,31 +100,48 @@ def extract_and_authenticate(data: dict, trust, *, blacklist=None, whitelist=Non
     if "payload" not in data or "signature" not in data:
         return None, None, False, "unauthorized: signed request required"
 
-    # Verify signature (protocol level - always required)
+    # Verify signature (protocol level - always required, even for whitelisted)
     prompt, identity, error = _authenticate_signed(
-        data, blacklist=blacklist, whitelist=whitelist, agent_address=agent_address
+        data, blacklist=blacklist, 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
-
+    # Parameter whitelist bypasses trust POLICY (not signature verification)
+    if whitelist and identity in whitelist:
+        return prompt, identity, True, None
 
-def _authenticate_signed(data: dict, *, blacklist=None, whitelist=None, agent_address=None):
+    # Use TrustAgent for all trust decisions (fast rules + LLM fallback)
+    payload = data.get("payload", {})
+    request_data = {
+        "prompt": prompt,
+        "invite_code": payload.get("invite_code"),
+        "payment": payload.get("payment", 0),
+    }
+
+    # Trust should be TrustAgent (resolved by host/create_app)
+    # But handle string for backwards compatibility with direct calls
+    if isinstance(trust, TrustAgent):
+        trust_agent = trust
+    elif isinstance(trust, str):
+        trust_agent = TrustAgent(trust)
+    else:
+        # Unknown type (e.g., Agent) - use default "careful"
+        trust_agent = TrustAgent("careful")
+
+    decision = trust_agent.should_allow(identity, request_data)
+
+    if decision.allow:
+        return prompt, identity, True, None
+    else:
+        return None, identity, True, f"forbidden: {decision.reason}"
+
+
+def _authenticate_signed(data: dict, *, blacklist=None, agent_address=None):
     """Authenticate signed request with Ed25519 - ALWAYS REQUIRED.
 
     Protocol-level signature verification. All requests must be signed.
+    Whitelist is NOT checked here - it bypasses trust policy, not signature.
 
     Returns: (prompt, identity, error) - error is None on success
     """
@@ -112,14 +153,10 @@ def _authenticate_signed(data: dict, *, blacklist=None, whitelist=None, agent_ad
     timestamp = payload.get("timestamp")
     to_address = payload.get("to")
 
-    # Check blacklist first
+    # Check blacklist first (security: even before signature check)
     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"
@@ -137,7 +174,7 @@ def _authenticate_signed(data: dict, *, blacklist=None, whitelist=None, agent_ad
     if agent_address and to_address and to_address != agent_address:
         return None, identity, "unauthorized: wrong recipient"
 
-    # Verify signature
+    # Verify signature ALWAYS (no whitelist bypass - that's at policy level)
     if not verify_signature(payload, signature, identity):
         return None, identity, "unauthorized: invalid signature"
 
@@ -150,40 +187,6 @@ def get_agent_address(agent) -> str:
     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):

connectonion/network/host/routes.py

@@ -88,13 +88,19 @@ def health_handler(agent_name: str, start_time: float) -> dict:
     return {"status": "healthy", "agent": agent_name, "uptime": int(time.time() - start_time)}
 
 
-def info_handler(agent_metadata: dict, trust: str) -> dict:
+def info_handler(agent_metadata: dict, trust: str, trust_config: dict | None = None) -> dict:
     """GET /info
 
-    Returns pre-extracted metadata - no agent creation needed.
+    Returns pre-extracted metadata including onboard requirements.
+
+    Args:
+        agent_metadata: Agent name, address, tools
+        trust: Trust level string ("open", "careful", "strict", or custom)
+        trust_config: Parsed YAML config from trust policy (optional)
     """
     from ... import __version__
-    return {
+
+    result = {
         "name": agent_metadata["name"],
         "address": agent_metadata["address"],
         "tools": agent_metadata["tools"],
@@ -102,6 +108,17 @@ def info_handler(agent_metadata: dict, trust: str) -> dict:
         "version": __version__,
     }
 
+    # Add onboard info if available
+    if trust_config:
+        onboard = trust_config.get("onboard", {})
+        if onboard:
+            result["onboard"] = {
+                "invite_code": "invite_code" in onboard,
+                "payment": onboard.get("payment"),
+            }
+
+    return result
+
 
 def admin_logs_handler(agent_name: str) -> dict:
     """GET /admin/logs - return plain text activity log file."""
@@ -133,3 +150,71 @@ def admin_sessions_handler() -> dict:
     # Sort by updated date descending (newest first)
     sessions.sort(key=lambda s: s.get("updated", s.get("created", "")), reverse=True)
     return {"sessions": sessions}
+
+
+# === Admin Trust Routes ===
+# These receive TrustAgent instance from route_handlers
+
+def admin_trust_promote_handler(trust_agent, client_id: str) -> dict:
+    """POST /admin/trust/promote - Promote client to next level."""
+    level = trust_agent.get_level(client_id)
+    if level == "stranger":
+        result = trust_agent.promote_to_contact(client_id)
+    elif level == "contact":
+        result = trust_agent.promote_to_whitelist(client_id)
+    elif level == "whitelist":
+        return {"error": "Already at highest level", "level": level}
+    elif level == "blocked":
+        return {"error": "Client is blocked. Unblock first.", "level": level}
+    else:
+        return {"error": f"Unknown level: {level}"}
+
+    return {"success": True, "message": result, "level": trust_agent.get_level(client_id)}
+
+
+def admin_trust_demote_handler(trust_agent, client_id: str) -> dict:
+    """POST /admin/trust/demote - Demote client to previous level."""
+    level = trust_agent.get_level(client_id)
+    if level == "whitelist":
+        result = trust_agent.demote_to_contact(client_id)
+    elif level == "contact":
+        result = trust_agent.demote_to_stranger(client_id)
+    elif level == "stranger":
+        return {"error": "Already at lowest level", "level": level}
+    elif level == "blocked":
+        return {"error": "Client is blocked. Unblock first.", "level": level}
+    else:
+        return {"error": f"Unknown level: {level}"}
+
+    return {"success": True, "message": result, "level": trust_agent.get_level(client_id)}
+
+
+def admin_trust_block_handler(trust_agent, client_id: str, reason: str = "") -> dict:
+    """POST /admin/trust/block - Block a client."""
+    result = trust_agent.block(client_id, reason)
+    return {"success": True, "message": result, "level": trust_agent.get_level(client_id)}
+
+
+def admin_trust_unblock_handler(trust_agent, client_id: str) -> dict:
+    """POST /admin/trust/unblock - Unblock a client."""
+    result = trust_agent.unblock(client_id)
+    return {"success": True, "message": result, "level": trust_agent.get_level(client_id)}
+
+
+def admin_trust_level_handler(trust_agent, client_id: str) -> dict:
+    """GET /admin/trust/level/{client_id} - Get client's trust level."""
+    return {"client_id": client_id, "level": trust_agent.get_level(client_id)}
+
+
+# === Super Admin Routes (admin management) ===
+
+def admin_admins_add_handler(trust_agent, admin_id: str) -> dict:
+    """POST /superadmin/add - Add an admin. Super admin only."""
+    result = trust_agent.add_admin(admin_id)
+    return {"success": True, "message": result}
+
+
+def admin_admins_remove_handler(trust_agent, admin_id: str) -> dict:
+    """POST /superadmin/remove - Remove an admin. Super admin only."""
+    result = trust_agent.remove_admin(admin_id)
+    return {"success": True, "message": result}

connectonion/network/host/server.py

@@ -26,6 +26,7 @@ don't interfere between concurrent requests.
 """
 
 import os
+from functools import partial
 from pathlib import Path
 from typing import Callable, Union
 
@@ -33,7 +34,8 @@ 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 ..trust import TrustAgent, get_default_trust_level, parse_policy, TRUST_LEVELS
+from ..trust.factory import PROMPTS_DIR
 from .session import SessionStorage
 from .auth import extract_and_authenticate
 from .routes import (
@@ -44,9 +46,49 @@ from .routes import (
     info_handler,
     admin_logs_handler,
     admin_sessions_handler,
+    # Admin trust routes
+    admin_trust_promote_handler,
+    admin_trust_demote_handler,
+    admin_trust_block_handler,
+    admin_trust_unblock_handler,
+    admin_trust_level_handler,
+    # Super admin routes
+    admin_admins_add_handler,
+    admin_admins_remove_handler,
 )
 
 
+def _parse_trust_config(trust: Union[str, "Agent"]) -> dict | None:
+    """Parse trust config from trust parameter.
+
+    Returns YAML config dict if trust is a level or file path, None otherwise.
+    Used to extract onboard info for /info endpoint.
+    """
+    if not isinstance(trust, str):
+        return None
+
+    # Check if it's a trust level
+    if trust.lower() in TRUST_LEVELS:
+        policy_path = PROMPTS_DIR / f"{trust.lower()}.md"
+        if policy_path.exists():
+            config, _ = parse_policy(policy_path.read_text(encoding='utf-8'))
+            return config
+        return None
+
+    # Check if it's a file path
+    path = Path(trust)
+    if path.exists() and path.is_file():
+        config, _ = parse_policy(path.read_text(encoding='utf-8'))
+        return config
+
+    # Inline policy text
+    if trust.startswith('---'):
+        config, _ = parse_policy(trust)
+        return config
+
+    return None
+
+
 def get_default_trust() -> str:
     """Get default trust based on environment.
 
@@ -70,7 +112,7 @@ def _extract_agent_metadata(create_agent: Callable) -> tuple[dict, object]:
     return metadata, sample
 
 
-def _create_route_handlers(create_agent: Callable, agent_metadata: dict, result_ttl: int):
+def _create_route_handlers(create_agent: Callable, agent_metadata: dict, result_ttl: int, trust_agent):
     """Create route handler dict for ASGI app.
 
     Args:
@@ -79,6 +121,7 @@ def _create_route_handlers(create_agent: Callable, agent_metadata: dict, result_
         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
+        trust_agent: TrustAgent instance for trust operations
     """
     agent_name = agent_metadata["name"]
 
@@ -91,8 +134,8 @@ def _create_route_handlers(create_agent: Callable, agent_metadata: dict, result_
     def handle_health(start_time):
         return health_handler(agent_name, start_time)
 
-    def handle_info(trust):
-        return info_handler(agent_metadata, trust)
+    def handle_info(trust, trust_config=None):
+        return info_handler(agent_metadata, trust, trust_config)
 
     def handle_admin_logs():
         return admin_logs_handler(agent_name)
@@ -107,6 +150,17 @@ def _create_route_handlers(create_agent: Callable, agent_metadata: dict, result_
         "ws_input": handle_ws_input,
         "admin_logs": handle_admin_logs,
         "admin_sessions": admin_sessions_handler,
+        # TrustAgent instance for direct access in http.py/websocket.py
+        "trust_agent": trust_agent,
+        # Admin trust routes (partial injects trust_agent as first arg)
+        "admin_trust_promote": partial(admin_trust_promote_handler, trust_agent),
+        "admin_trust_demote": partial(admin_trust_demote_handler, trust_agent),
+        "admin_trust_block": partial(admin_trust_block_handler, trust_agent),
+        "admin_trust_unblock": partial(admin_trust_unblock_handler, trust_agent),
+        "admin_trust_level": partial(admin_trust_level_handler, trust_agent),
+        # Super admin routes
+        "admin_admins_add": partial(admin_admins_add_handler, trust_agent),
+        "admin_admins_remove": partial(admin_admins_remove_handler, trust_agent),
     }
 
 
@@ -197,14 +251,14 @@ def host(
         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)
+        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  /admin/logs     - Activity log (requires OPENONION_API_KEY)
+        GET  /admin/sessions - Activity sessions (requires OPENONION_API_KEY)
     """
     import uvicorn
     from ... import address
@@ -228,11 +282,24 @@ def host(
     agent_metadata["address"] = addr_data['address']
 
     storage = SessionStorage()
-    route_handlers = _create_route_handlers(create_agent, agent_metadata, result_ttl)
+
+    # Create TrustAgent instance - the single interface for all trust operations
+    # Users can subclass TrustAgent to customize (e.g., database-backed admin storage)
+    if isinstance(trust, TrustAgent):
+        trust_agent = trust
+    else:
+        trust_agent = TrustAgent(trust if isinstance(trust, str) else "careful")
+
+    route_handlers = _create_route_handlers(create_agent, agent_metadata, result_ttl, trust_agent)
+
+    # Parse trust config for /info onboard info
+    trust_config = _parse_trust_config(trust)
+
     app = asgi_create_app(
         route_handlers=route_handlers,
         storage=storage,
-        trust=trust,
+        trust=trust_agent,  # Pass resolved TrustAgent, not raw trust
+        trust_config=trust_config,
         blacklist=blacklist,
         whitelist=whitelist,
     )
@@ -243,13 +310,23 @@ def host(
 
     # Display startup info
     relay_status = f"[green]✓[/] {relay_url}" if relay_url else "[dim]disabled[/]"
+
+    # Build trust info for display
+    trust_info = ""
+    if trust_config and isinstance(trust, str) and trust.lower() in TRUST_LEVELS:
+        onboard = trust_config.get("onboard", {})
+        invite_codes = onboard.get("invite_code", [])
+        if invite_codes:
+            codes_str = ", ".join(invite_codes) if isinstance(invite_codes, list) else invite_codes
+            trust_info = f"\n[bold]Invite:[/]  {codes_str}\n[dim]         Run 'co copy trust/{trust}' to customize[/]"
+
     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}",
+        f"[bold]Relay:[/]   {relay_status}{trust_info}",
         title=f"[green]Agent '{agent_metadata['name']}'[/]"
     ))
 
@@ -279,11 +356,17 @@ def create_app(create_agent: Callable, storage=None, trust="careful", result_ttl
     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)
+    # Create TrustAgent instance
+    if isinstance(trust, TrustAgent):
+        trust_agent = trust
+    else:
+        trust_agent = TrustAgent(trust if isinstance(trust, str) else "careful")
+
+    route_handlers = _create_route_handlers(create_agent, agent_metadata, result_ttl, trust_agent)
     return asgi_create_app(
         route_handlers=route_handlers,
         storage=storage,
-        trust=trust,
+        trust=trust_agent,  # Pass resolved TrustAgent, not raw trust
         blacklist=blacklist,
         whitelist=whitelist,
     )

connectonion/network/trust/__init__.py

@@ -1,30 +1,38 @@
 """
-Purpose: Trust verification system module re-exporting factory, prompts, and verification tools
-LLM-Note:
-  Dependencies: imports from [factory.py, prompts.py, tools.py] | imported by [network/__init__.py, network/host/auth.py, network/host/server.py] | tested by [tests/network/test_trust.py]
-  Data flow: re-exports trust agent creation utilities and trust level prompts
-  State/Effects: no state
-  Integration: exposes create_trust_agent(trust_spec) → Agent, get_default_trust_level() → str, validate_trust_level(level), TRUST_LEVELS dict, TRUST_PROMPTS dict, get_trust_prompt(level) → str, get_trust_verification_tools() → list | used by host() for access control policies
-  Performance: trivial
-  Errors: none
 Trust verification system for agent networking.
 
-This module contains:
-- factory: Trust agent creation and configuration
-- prompts: Pre-configured trust prompts for different levels
-- tools: Verification tools for trust agents
+Usage:
+    from connectonion.network.trust import TrustAgent
+
+    trust = TrustAgent("careful")  # or "open", "strict", or path to policy
+
+    # Access control
+    decision = trust.should_allow("client-123", {"prompt": "hello"})
+
+    # Trust level operations
+    trust.promote_to_contact("client-123")
+    trust.block("bad-actor", reason="spam")
+    level = trust.get_level("client-123")  # "stranger", "contact", "whitelist", "blocked"
+
+    # Admin operations
+    trust.is_admin("client-123")
+    trust.add_admin("new-admin")
+
+TrustAgent is the single interface for all trust operations.
+Subclass to customize behavior (e.g., database-backed admin storage).
 """
 
-from .factory import create_trust_agent, get_default_trust_level, validate_trust_level, TRUST_LEVELS
-from .prompts import TRUST_PROMPTS, get_trust_prompt
-from .tools import get_trust_verification_tools
+from .trust_agent import TrustAgent, Decision
+from .factory import get_default_trust_level, validate_trust_level, TRUST_LEVELS
+from .fast_rules import parse_policy
 
 __all__ = [
-    "create_trust_agent",
+    # TrustAgent - the single interface
+    "TrustAgent",
+    "Decision",
+    # Helpers
     "get_default_trust_level",
     "validate_trust_level",
     "TRUST_LEVELS",
-    "TRUST_PROMPTS",
-    "get_trust_prompt",
-    "get_trust_verification_tools",
+    "parse_policy",
 ]