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

connectonion/network/connect.py

@@ -6,14 +6,24 @@ Lifecycle (Client Side):
   2. agent.input(prompt) opens WebSocket to relay /ws/input endpoint
   3. Sends INPUT message: {type: "INPUT", input_id, to, prompt, session?}
   4. Receives streaming events: tool_call, tool_result, thinking, assistant
-  5. Receives final OUTPUT: {type: "OUTPUT", result, session} or ask_user
-  6. Returns Response(text, done) - done=False means agent asked a question
+  5. If stranger: ONBOARD_REQUIRED → callback provides credentials → ONBOARD_SUBMIT → ONBOARD_SUCCESS → retry
+  6. Receives final OUTPUT: {type: "OUTPUT", result, session} or ask_user
+  7. Returns Response(text, done) - done=False means agent asked a question
 
 Message Flow:
   Client → /ws/input → Relay → forwards to Agent's /ws/announce connection
   Agent processes → sends OUTPUT → Relay resolves pending_outputs future
   Relay → forwards OUTPUT → Client receives response
 
+Onboard Flow (for strangers connecting to careful/strict agents):
+  Client: INPUT
+  Server: ONBOARD_REQUIRED {methods: ["invite_code", "payment"], payment_amount: N}
+  Client: calls on_onboard callback to get credentials
+  Client: ONBOARD_SUBMIT {invite_code: "...", payment: N}
+  Server: ONBOARD_SUCCESS {level: "contact", message: "..."}
+  Client: INPUT (retry original prompt)
+  Server: OUTPUT
+
 Related Files:
   - oo-api/relay/routes.py: Relay server WebSocket endpoints
   - connectonion/network/relay.py: Agent-side relay connection (serve_loop)
@@ -31,7 +41,7 @@ import json
 import time
 import uuid
 from dataclasses import dataclass
-from typing import Any, Dict, List, Optional
+from typing import Any, Callable, Dict, List, Optional
 
 from .. import address as addr
 
@@ -96,7 +106,12 @@ class RemoteAgent:
         """
         return self._ui_events
 
-    def input(self, prompt: str, timeout: float = 60.0) -> Response:
+    def input(
+        self,
+        prompt: str,
+        timeout: float = 60.0,
+        on_onboard: Optional[Callable[[List[str], Optional[float]], Dict[str, Any]]] = None
+    ) -> Response:
         """
         Send prompt to remote agent and get response.
 
@@ -107,6 +122,10 @@ class RemoteAgent:
         Args:
             prompt: Task/prompt to send
             timeout: Seconds to wait for response (default 60)
+            on_onboard: Callback when agent requires onboarding (invite code or payment).
+                        Called with (methods: list[str], payment_amount: float | None).
+                        Should return {"invite_code": "..."} or {"payment": amount}.
+                        If None, prompts interactively in terminal.
 
         Returns:
             Response with text and done flag
@@ -115,6 +134,12 @@ class RemoteAgent:
             >>> response = agent.input("Book a flight to Tokyo")
             >>> if not response.done:
             ...     response = agent.input("March 15")  # Answer the question
+
+        Onboard example:
+            >>> def handle_onboard(methods, payment_amount):
+            ...     if "invite_code" in methods:
+            ...         return {"invite_code": input("Enter invite code: ")}
+            >>> response = agent.input("Hello", on_onboard=handle_onboard)
         """
         try:
             asyncio.get_running_loop()
@@ -125,11 +150,16 @@ class RemoteAgent:
         except RuntimeError as e:
             if "input() cannot be used" in str(e):
                 raise
-        return asyncio.run(self._stream_input(prompt, timeout))
+        return asyncio.run(self._stream_input(prompt, timeout, on_onboard))
 
-    async def input_async(self, prompt: str, timeout: float = 60.0) -> Response:
+    async def input_async(
+        self,
+        prompt: str,
+        timeout: float = 60.0,
+        on_onboard: Optional[Callable[[List[str], Optional[float]], Dict[str, Any]]] = None
+    ) -> Response:
         """Async version of input()."""
-        return await self._stream_input(prompt, timeout)
+        return await self._stream_input(prompt, timeout, on_onboard)
 
     def reset(self) -> None:
         """Clear conversation and start fresh."""
@@ -137,7 +167,12 @@ class RemoteAgent:
         self._ui_events = []
         self._status = "idle"
 
-    async def _stream_input(self, prompt: str, timeout: float) -> Response:
+    async def _stream_input(
+        self,
+        prompt: str,
+        timeout: float,
+        on_onboard: Optional[Callable[[List[str], Optional[float]], Dict[str, Any]]] = None
+    ) -> Response:
         """Send prompt via WebSocket and stream events."""
         import websockets
 
@@ -153,30 +188,10 @@ class RemoteAgent:
         ws_url = f"{self._relay_url}/ws/input"
 
         # Generate input_id for routing/response matching
-        import uuid
         input_id = str(uuid.uuid4())
 
         # Build the INPUT message
-        input_msg = {
-            "type": "INPUT",
-            "input_id": input_id,
-            "prompt": prompt,
-            "to": self.address,
-            "timestamp": int(time.time())
-        }
-
-        # Add session for conversation continuation
-        if self._current_session:
-            input_msg["session"] = self._current_session
-
-        # Sign if keys provided
-        if self._keys:
-            payload = {"prompt": prompt, "to": self.address, "timestamp": input_msg["timestamp"]}
-            canonical = json.dumps(payload, sort_keys=True, separators=(',', ':'))
-            signature = addr.sign(self._keys, canonical.encode())
-            input_msg["payload"] = payload
-            input_msg["from"] = self._keys["address"]
-            input_msg["signature"] = signature.hex()
+        input_msg = self._build_input_message(prompt, input_id)
 
         try:
             async with websockets.connect(ws_url) as ws:
@@ -209,6 +224,43 @@ class RemoteAgent:
                         self._status = "idle"
                         raise ConnectionError(f"Agent error: {event.get('message', event.get('error'))}")
 
+                    elif event_type == "ONBOARD_REQUIRED":
+                        # Agent requires onboarding (invite code or payment)
+                        methods = event.get("methods", [])
+                        payment_amount = event.get("payment_amount")
+
+                        # Add onboard_required event to UI
+                        self._add_ui_event({
+                            "type": "onboard_required",
+                            "methods": methods,
+                            "payment_amount": payment_amount
+                        })
+
+                        # Get credentials from callback or prompt interactively
+                        if on_onboard:
+                            credentials = on_onboard(methods, payment_amount)
+                        else:
+                            credentials = self._prompt_onboard(methods, payment_amount)
+
+                        # Send ONBOARD_SUBMIT
+                        submit_msg = self._build_onboard_submit(credentials)
+                        await ws.send(json.dumps(submit_msg))
+                        # Continue loop to wait for ONBOARD_SUCCESS
+
+                    elif event_type == "ONBOARD_SUCCESS":
+                        # Onboard successful - add to UI
+                        self._add_ui_event({
+                            "type": "onboard_success",
+                            "level": event.get("level", "contact"),
+                            "message": event.get("message", "Onboard successful")
+                        })
+
+                        # Retry the original prompt
+                        retry_input_id = str(uuid.uuid4())
+                        retry_msg = self._build_input_message(prompt, retry_input_id)
+                        await ws.send(json.dumps(retry_msg))
+                        # Continue loop to wait for OUTPUT
+
                     elif event_type == "ask_user":
                         # Agent is asking a question - return done=False so caller sends another input()
                         self._status = "waiting"
@@ -233,6 +285,70 @@ class RemoteAgent:
             self._status = "idle"
             raise TimeoutError(f"Request timed out after {timeout}s")
 
+    def _build_input_message(self, prompt: str, input_id: str) -> Dict[str, Any]:
+        """Build INPUT message with optional signing."""
+        input_msg = {
+            "type": "INPUT",
+            "input_id": input_id,
+            "prompt": prompt,
+            "to": self.address,
+            "timestamp": int(time.time())
+        }
+
+        # Add session for conversation continuation
+        if self._current_session:
+            input_msg["session"] = self._current_session
+
+        # Sign if keys provided
+        if self._keys:
+            payload = {"prompt": prompt, "to": self.address, "timestamp": input_msg["timestamp"]}
+            canonical = json.dumps(payload, sort_keys=True, separators=(',', ':'))
+            signature = addr.sign(self._keys, canonical.encode())
+            input_msg["payload"] = payload
+            input_msg["from"] = self._keys["address"]
+            input_msg["signature"] = signature.hex()
+
+        return input_msg
+
+    def _build_onboard_submit(self, credentials: Dict[str, Any]) -> Dict[str, Any]:
+        """Build ONBOARD_SUBMIT message with optional signing."""
+        payload = {
+            "timestamp": int(time.time()),
+            **credentials
+        }
+
+        submit_msg: Dict[str, Any] = {
+            "type": "ONBOARD_SUBMIT",
+            "payload": payload
+        }
+
+        # Sign if keys provided
+        if self._keys:
+            canonical = json.dumps(payload, sort_keys=True, separators=(',', ':'))
+            signature = addr.sign(self._keys, canonical.encode())
+            submit_msg["from"] = self._keys["address"]
+            submit_msg["signature"] = signature.hex()
+
+        return submit_msg
+
+    def _prompt_onboard(self, methods: List[str], payment_amount: Optional[float]) -> Dict[str, Any]:
+        """Prompt user interactively for onboard credentials."""
+        print(f"\n🔐 Access verification required")
+        print(f"   Available methods: {', '.join(methods)}")
+
+        if "invite_code" in methods:
+            code = input("   Enter invite code: ").strip()
+            if code:
+                return {"invite_code": code}
+
+        if "payment" in methods and payment_amount:
+            print(f"   Payment required: ${payment_amount}")
+            confirm = input("   Pay now? [y/N]: ").strip().lower()
+            if confirm == 'y':
+                return {"payment": payment_amount}
+
+        raise ValueError("No valid onboard credentials provided")
+
     def _handle_stream_event(self, event: Dict[str, Any]) -> None:
         """Handle streaming event and update UI."""
         event_type = event.get("type")

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}