praisonai-code 0.0.1__py3-none-any.whl

praisonai_code/cli/configuration/oauth.py

@@ -0,0 +1,389 @@
+"""
+Browser-based (OAuth / device-code) provider sign-in for the PraisonAI CLI.
+
+This module implements the operator-onboarding OAuth flow for the ``auth login``
+command. It intentionally lives in the wrapper layer (``praisonai``) because it
+is heavy, provider-specific onboarding UX; it *reuses* the protocol-first OAuth
+primitives shipped in the core SDK (``praisonaiagents.mcp``) rather than
+reimplementing PKCE / a local-callback server.
+
+Two flow styles are supported per provider:
+- ``device``: RFC 8628 device-authorization grant (print a code + URL, poll).
+- ``authcode``: RFC 7636 authorization-code + PKCE via a local callback.
+
+Provider OAuth endpoints are not hardcoded for unknown providers; a provider is
+"OAuth-capable" only if it appears in :data:`OAUTH_PROVIDERS` or the caller
+supplies explicit endpoints. Providers without a config fall back to API-key
+login automatically (handled by the CLI command).
+"""
+
+import time
+import webbrowser
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional, Tuple
+
+
+@dataclass
+class OAuthProviderConfig:
+    """OAuth endpoint configuration for a single provider."""
+    flow: str  # "device" or "authcode"
+    client_id: str
+    token_url: str
+    device_authorization_url: Optional[str] = None
+    authorization_url: Optional[str] = None
+    scope: Optional[str] = None
+    audience: Optional[str] = None
+    extra_auth_params: Dict[str, str] = field(default_factory=dict)
+
+
+# Built-in OAuth-capable providers. This registry is intentionally small and
+# additive: providers absent here transparently fall back to API-key login.
+# Endpoints can also be supplied at call-time (e.g. for self-hosted gateways).
+OAUTH_PROVIDERS: Dict[str, OAuthProviderConfig] = {}
+
+
+def get_provider_config(
+    provider: str,
+    overrides: Optional[Dict[str, Any]] = None,
+) -> Optional[OAuthProviderConfig]:
+    """
+    Resolve an :class:`OAuthProviderConfig` for ``provider``.
+
+    Args:
+        provider: Provider name (case-insensitive).
+        overrides: Optional dict of endpoint overrides. If it contains the
+            minimum required fields it is used to construct an ad-hoc config,
+            allowing OAuth for providers not in the built-in registry.
+
+    Returns:
+        Config if the provider supports OAuth, else None.
+    """
+    overrides = overrides or {}
+    base = OAUTH_PROVIDERS.get(provider.lower())
+
+    merged: Dict[str, Any] = {}
+    if base is not None:
+        merged.update(base.__dict__)
+    merged.update({k: v for k, v in overrides.items() if v is not None})
+
+    if not merged.get("client_id") or not merged.get("token_url"):
+        return None
+    if not merged.get("flow"):
+        merged["flow"] = "device" if merged.get("device_authorization_url") else "authcode"
+
+    return OAuthProviderConfig(
+        flow=merged["flow"],
+        client_id=merged["client_id"],
+        token_url=merged["token_url"],
+        device_authorization_url=merged.get("device_authorization_url"),
+        authorization_url=merged.get("authorization_url"),
+        scope=merged.get("scope"),
+        audience=merged.get("audience"),
+        extra_auth_params=merged.get("extra_auth_params") or {},
+    )
+
+
+def provider_supports_oauth(
+    provider: str,
+    overrides: Optional[Dict[str, Any]] = None,
+) -> bool:
+    """Return True if ``provider`` has a usable OAuth configuration."""
+    return get_provider_config(provider, overrides) is not None
+
+
+def _tokens_to_credential_kwargs(payload: Dict[str, Any]) -> Dict[str, Any]:
+    """Normalise a token endpoint response into store kwargs."""
+    access_token = payload.get("access_token")
+    expires_in = payload.get("expires_in")
+    expires_at = (time.time() + float(expires_in)) if expires_in else None
+    return {
+        "access_token": access_token,
+        "refresh_token": payload.get("refresh_token"),
+        "expires_at": expires_at,
+        "scope": payload.get("scope"),
+    }
+
+
+def run_device_code_flow(
+    config: OAuthProviderConfig,
+    *,
+    open_browser: bool = True,
+    on_prompt=None,
+    poll_timeout: float = 300.0,
+) -> Dict[str, Any]:
+    """
+    Run the RFC 8628 device-authorization flow.
+
+    Args:
+        config: Provider OAuth config (must have ``device_authorization_url``).
+        open_browser: Whether to attempt opening the verification URL.
+        on_prompt: Optional callback ``(verification_uri, user_code)`` used to
+            display instructions to the user.
+        poll_timeout: Max seconds to poll for authorization.
+
+    Returns:
+        Dict of credential kwargs (access_token, refresh_token, expires_at,
+        scope) plus ``token_url`` and ``client_id`` for later refresh.
+
+    Raises:
+        RuntimeError: On request failure or timeout.
+    """
+    try:
+        import requests
+    except ImportError as exc:
+        raise RuntimeError(
+            "OAuth login requires the optional 'requests' package. "
+            "Install it with: pip install requests"
+        ) from exc
+
+    if not config.device_authorization_url:
+        raise RuntimeError("Provider does not define a device authorization endpoint")
+
+    data = {"client_id": config.client_id}
+    if config.scope:
+        data["scope"] = config.scope
+    if config.audience:
+        data["audience"] = config.audience
+
+    resp = requests.post(config.device_authorization_url, data=data, timeout=30)
+    resp.raise_for_status()
+    dev = resp.json()
+
+    device_code = dev.get("device_code")
+    user_code = dev.get("user_code")
+    verification_uri = dev.get("verification_uri") or dev.get("verification_url")
+    verification_uri_complete = dev.get("verification_uri_complete")
+    interval = float(dev.get("interval", 5))
+
+    if on_prompt:
+        on_prompt(verification_uri, user_code)
+
+    if open_browser and (verification_uri_complete or verification_uri):
+        try:
+            webbrowser.open(verification_uri_complete or verification_uri)
+        except Exception:
+            pass
+
+    deadline = time.time() + poll_timeout
+    token_data = {
+        "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+        "device_code": device_code,
+        "client_id": config.client_id,
+    }
+
+    while time.time() < deadline:
+        time.sleep(interval)
+        tok = requests.post(config.token_url, data=token_data, timeout=30)
+        payload = tok.json()
+        if tok.status_code == 200 and payload.get("access_token"):
+            return _tokens_to_credential_kwargs(payload)
+
+        error = payload.get("error")
+        if error == "authorization_pending":
+            continue
+        if error == "slow_down":
+            interval += 5
+            continue
+        raise RuntimeError(f"Device authorization failed: {error or tok.status_code}")
+
+    raise RuntimeError("Timed out waiting for device authorization")
+
+
+def run_authcode_flow(
+    config: OAuthProviderConfig,
+    *,
+    open_browser: bool = True,
+    on_prompt=None,
+    callback_timeout: float = 300.0,
+) -> Dict[str, Any]:
+    """
+    Run the RFC 7636 authorization-code + PKCE flow via a local callback.
+
+    Reuses the core SDK's :class:`OAuthCallbackHandler` and PKCE helpers so the
+    wrapper does not reimplement OAuth client primitives.
+
+    Returns:
+        Dict of credential kwargs (access_token, refresh_token, expires_at,
+        scope).
+
+    Raises:
+        RuntimeError: On request failure or timeout.
+    """
+    try:
+        import requests
+    except ImportError as exc:
+        raise RuntimeError(
+            "OAuth login requires the optional 'requests' package. "
+            "Install it with: pip install requests"
+        ) from exc
+
+    from praisonaiagents.mcp.mcp_oauth_callback import (
+        OAuthCallbackHandler,
+        OAUTH_CALLBACK_PORT,
+        OAUTH_CALLBACK_PATH,
+        generate_state,
+        generate_code_verifier,
+        generate_code_challenge,
+        get_redirect_url,
+    )
+
+    if not config.authorization_url:
+        raise RuntimeError("Provider does not define an authorization endpoint")
+
+    handler = OAuthCallbackHandler()
+    state = generate_state()
+    verifier = generate_code_verifier()
+    challenge = generate_code_challenge(verifier)
+    redirect_uri = get_redirect_url()
+
+    # ``OAuthCallbackHandler`` only holds in-memory state; it does not listen on
+    # the redirect URI. Start a short-lived local HTTP server that receives the
+    # provider redirect and forwards (state, code) into the handler so that
+    # ``wait_for_callback`` can unblock.
+    server = _start_callback_server(handler, OAUTH_CALLBACK_PORT, OAUTH_CALLBACK_PATH)
+
+    params = {
+        "response_type": "code",
+        "client_id": config.client_id,
+        "redirect_uri": redirect_uri,
+        "state": state,
+        "code_challenge": challenge,
+        "code_challenge_method": "S256",
+    }
+    if config.scope:
+        params["scope"] = config.scope
+    if config.audience:
+        params["audience"] = config.audience
+    params.update(config.extra_auth_params)
+
+    from urllib.parse import urlencode
+
+    auth_url = f"{config.authorization_url}?{urlencode(params)}"
+
+    if on_prompt:
+        on_prompt(auth_url, None)
+    if open_browser:
+        try:
+            webbrowser.open(auth_url)
+        except Exception:
+            pass
+
+    try:
+        code = handler.wait_for_callback(state, timeout=callback_timeout)
+    finally:
+        handler.clear_state(state)
+        server.shutdown()
+        server.server_close()
+
+    token_data = {
+        "grant_type": "authorization_code",
+        "code": code,
+        "redirect_uri": redirect_uri,
+        "client_id": config.client_id,
+        "code_verifier": verifier,
+    }
+    tok = requests.post(config.token_url, data=token_data, timeout=30)
+    tok.raise_for_status()
+    payload = tok.json()
+    if not payload.get("access_token"):
+        raise RuntimeError("Token endpoint did not return an access token")
+    return _tokens_to_credential_kwargs(payload)
+
+
+def _start_callback_server(handler, port: int, path: str):
+    """
+    Start a short-lived local HTTP server to receive the OAuth redirect.
+
+    The provider redirects the browser to ``http://127.0.0.1:<port><path>?...``;
+    this server parses the ``state``/``code`` (or ``error``) query parameters,
+    forwards them into ``handler.receive_callback`` so a blocked
+    ``wait_for_callback`` can unblock, and shows a minimal browser confirmation.
+
+    Args:
+        handler: An ``OAuthCallbackHandler`` to receive (state, code) pairs.
+        port: Localhost port to listen on (matches the registered redirect URI).
+        path: Expected callback path.
+
+    Returns:
+        A running ``http.server.HTTPServer`` whose ``serve_forever`` loop runs on
+        a daemon thread. Callers must ``shutdown()`` + ``server_close()`` it.
+    """
+    import threading
+    from http.server import BaseHTTPRequestHandler, HTTPServer
+    from urllib.parse import urlparse, parse_qs
+
+    class _CallbackRequestHandler(BaseHTTPRequestHandler):
+        def do_GET(self):  # noqa: N802 (stdlib-mandated name)
+            parsed = urlparse(self.path)
+            if parsed.path != path:
+                self.send_response(404)
+                self.end_headers()
+                return
+
+            params = parse_qs(parsed.query)
+            state = (params.get("state") or [None])[0]
+            code = (params.get("code") or [None])[0]
+            error = (params.get("error") or [None])[0]
+
+            if state and code:
+                handler.receive_callback(state, code)
+                body = b"Sign-in complete. You can close this tab."
+            else:
+                body = (
+                    f"Sign-in failed: {error or 'missing code'}. "
+                    "You can close this tab."
+                ).encode()
+
+            self.send_response(200)
+            self.send_header("Content-Type", "text/plain; charset=utf-8")
+            self.end_headers()
+            self.wfile.write(body)
+
+        def log_message(self, *args):  # silence default stderr logging
+            return
+
+    server = HTTPServer(("127.0.0.1", port), _CallbackRequestHandler)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    return server
+
+
+def run_oauth_login(
+    provider: str,
+    *,
+    overrides: Optional[Dict[str, Any]] = None,
+    open_browser: bool = True,
+    on_prompt=None,
+    timeout: float = 300.0,
+) -> Tuple[OAuthProviderConfig, Dict[str, Any]]:
+    """
+    Run the appropriate OAuth flow for ``provider`` and return tokens.
+
+    Args:
+        provider: Provider name.
+        overrides: Optional endpoint overrides (enables ad-hoc/self-hosted).
+        open_browser: Whether to auto-open the browser.
+        on_prompt: Optional callback for displaying instructions to the user.
+        timeout: Max seconds to wait for authorization.
+
+    Returns:
+        Tuple of (resolved config, credential kwargs ready for the store).
+
+    Raises:
+        ValueError: If the provider does not support OAuth.
+        RuntimeError: On flow failure/timeout.
+    """
+    config = get_provider_config(provider, overrides)
+    if config is None:
+        raise ValueError(f"Provider '{provider}' does not support OAuth login")
+
+    if config.flow == "device":
+        tokens = run_device_code_flow(
+            config, open_browser=open_browser, on_prompt=on_prompt, poll_timeout=timeout
+        )
+    else:
+        tokens = run_authcode_flow(
+            config, open_browser=open_browser, on_prompt=on_prompt, callback_timeout=timeout
+        )
+
+    return config, tokens

praisonai_code/cli/configuration/paths.py

@@ -0,0 +1,224 @@
+"""
+Configuration paths for PraisonAI CLI.
+
+Defines standard locations for configuration files.
+"""
+
+import os
+from pathlib import Path
+from typing import List, Optional
+
+
+# Directory markers that identify a PraisonAI project root.
+# Order matters: the first existing marker is used as the config directory
+# so that detection and config read/write stay aligned.
+_PROJECT_MARKERS = (".praison", ".praisonai")
+# Default config directory name used when no marker exists yet.
+_DEFAULT_CONFIG_DIRNAME = ".praison"
+# VCS markers used as a fallback when no project config dir is present.
+_VCS_MARKERS = (".git",)
+
+
+def _config_dirname_for(root: Path) -> str:
+    """Return the config directory name to use under ``root``.
+
+    Prefers an existing project marker directory so that a repo created with
+    ``.praisonai`` reads and writes config from the same directory it was
+    detected by, rather than silently switching to ``.praison``.
+    """
+    for marker in _PROJECT_MARKERS:
+        if (root / marker).is_dir():
+            return marker
+    return _DEFAULT_CONFIG_DIRNAME
+
+
+def find_project_root(start: Optional[Path] = None) -> Optional[Path]:
+    """Walk upward from ``start`` (or cwd) to locate the project root.
+
+    The project root is the nearest ancestor (including ``start`` itself)
+    that contains a project marker directory (``.praison``/``.praisonai``)
+    or a VCS root (``.git``). This lets the CLI behave identically from any
+    sub-directory of a project tree.
+
+    An explicit override may be supplied via the ``PRAISONAI_PROJECT``
+    environment variable, in which case that path is returned directly.
+
+    Returns:
+        The resolved project root, or ``None`` if no marker is found.
+    """
+    override = os.environ.get("PRAISONAI_PROJECT")
+    if override:
+        try:
+            override_path = Path(override).expanduser().resolve()
+        except (OSError, ValueError):
+            override_path = None
+        # Only honour an override that points to an existing directory;
+        # an invalid value falls through to normal discovery rather than
+        # aborting or anchoring config writes to a bogus path.
+        if override_path is not None and override_path.is_dir():
+            return override_path
+
+    try:
+        cur = (start or Path.cwd()).resolve()
+    except (OSError, ValueError):
+        return None
+
+    for d in (cur, *cur.parents):
+        if any((d / m).is_dir() for m in _PROJECT_MARKERS):
+            return d
+        if any((d / m).exists() for m in _VCS_MARKERS):
+            return d
+    return None
+
+
+def get_user_config_dir() -> Path:
+    """Get user configuration directory (~/.praison/)."""
+    return Path.home() / ".praison"
+
+
+def get_user_config_path() -> Path:
+    """Get user configuration file path (~/.praison/config.toml)."""
+    return get_user_config_dir() / "config.toml"
+
+
+def get_project_config_dir(project_root: Optional[Path] = None) -> Path:
+    """Get project configuration directory (.praison/).
+
+    When no ``project_root`` is given, the root is discovered by walking up
+    from the current working directory via :func:`find_project_root`, so the
+    project config is found from any sub-directory. Falls back to cwd when no
+    project marker is present.
+    """
+    root = project_root or find_project_root() or Path.cwd()
+    return root / _config_dirname_for(root)
+
+
+def get_project_config_path(project_root: Optional[Path] = None) -> Path:
+    """Get project configuration file path (.praison/config.toml)."""
+    return get_project_config_dir(project_root) / "config.toml"
+
+
+def get_sessions_dir() -> Path:
+    """Get sessions directory (~/.praison/sessions/)."""
+    return get_user_config_dir() / "sessions"
+
+
+def get_traces_dir() -> Path:
+    """Get traces directory (~/.praison/traces/)."""
+    return get_user_config_dir() / "traces"
+
+
+def get_logs_dir() -> Path:
+    """Get logs directory (~/.praison/logs/)."""
+    return get_user_config_dir() / "logs"
+
+
+def get_cache_dir() -> Path:
+    """Get cache directory (~/.praison/cache/)."""
+    return get_user_config_dir() / "cache"
+
+
+def get_config_paths(project_root: Optional[Path] = None) -> List[Path]:
+    """
+    Get all configuration file paths in precedence order (highest first).
+    
+    Precedence (highest first):
+    1. Project configs along the ancestor chain (nearest cwd wins, then
+       farther ancestors up to the project root): .praison/config.toml
+    2. User config: ~/.praison/config.toml
+
+    When no ``project_root`` is supplied, the chain is collected by walking
+    up from cwd to the detected project root so the CLI behaves identically
+    from any sub-directory.
+
+    Returns:
+        List of paths in precedence order
+    """
+    paths: List[Path] = []
+    seen: set = set()
+
+    if project_root is not None:
+        roots = [project_root]
+    else:
+        roots = _project_config_search_roots()
+
+    # Project configs (highest precedence), nearest-to-cwd first.
+    for root in roots:
+        project_config = (root / _config_dirname_for(root) / "config.toml")
+        if not project_config.exists():
+            continue
+        resolved = project_config.resolve()
+        if resolved not in seen:
+            seen.add(resolved)
+            paths.append(project_config)
+
+    # User config
+    user_config = get_user_config_path()
+    if user_config.exists() and user_config.resolve() not in seen:
+        paths.append(user_config)
+
+    return paths
+
+
+def _project_config_search_roots() -> List[Path]:
+    """Return candidate roots from cwd up to the project root (nearest first)."""
+    try:
+        cur = Path.cwd().resolve()
+    except (OSError, ValueError):
+        return []
+
+    project_root = find_project_root(cur)
+    # No project marker anywhere above cwd: don't walk to the filesystem
+    # root, otherwise an unrelated ancestor's .praison/config.toml would be
+    # picked up with higher precedence than the user config.
+    if project_root is None:
+        return [cur]
+
+    roots: List[Path] = []
+    for d in (cur, *cur.parents):
+        roots.append(d)
+        if d == project_root:
+            break
+    else:
+        # project_root is outside the cwd ancestry (e.g. PRAISONAI_PROJECT
+        # override pointing elsewhere): honour it explicitly.
+        roots.append(project_root)
+    return roots
+
+
+def ensure_config_dirs() -> None:
+    """Ensure all configuration directories exist."""
+    dirs = [
+        get_user_config_dir(),
+        get_sessions_dir(),
+        get_traces_dir(),
+        get_logs_dir(),
+        get_cache_dir(),
+    ]
+    for d in dirs:
+        d.mkdir(parents=True, exist_ok=True)
+
+
+def get_env_prefix() -> str:
+    """Get environment variable prefix."""
+    return "PRAISONAI_"
+
+
+def env_to_config_key(env_var: str) -> Optional[str]:
+    """
+    Convert environment variable name to config key.
+    
+    Example: PRAISONAI_OUTPUT_FORMAT -> output.format
+    """
+    prefix = get_env_prefix()
+    if not env_var.startswith(prefix):
+        return None
+    
+    key = env_var[len(prefix):].lower()
+    # Convert underscores to dots for nested keys
+    # Single underscore = dot, double underscore = single underscore
+    parts = key.split("__")
+    result_parts = []
+    for part in parts:
+        result_parts.append(part.replace("_", "."))
+    return "_".join(result_parts)