code-puppy-core-plugins 0.0.26__tar.gz → 0.0.27__tar.gz

{code_puppy_core_plugins-0.0.26 → code_puppy_core_plugins-0.0.27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: code-puppy-core-plugins
-Version: 0.0.26
+Version: 0.0.27
 Summary: Official plugin bundle for Code Puppy
 Project-URL: Repository, https://github.com/mpfaffenberger/code_puppy_core_plugins
 Project-URL: Homepage, https://github.com/mpfaffenberger/code_puppy_core_plugins

code_puppy_core_plugins-0.0.27/code_puppy_core_plugins/openrouter_oauth/__init__.py

@@ -0,0 +1,6 @@
+"""OpenRouter OAuth PKCE plugin.
+
+One-click browser sign-in that exchanges an authorization code for a
+user-controlled OpenRouter API key, wired into the ``/add_model`` flow via
+the ``provider_credential_flow`` hook.
+"""

code_puppy_core_plugins-0.0.27/code_puppy_core_plugins/openrouter_oauth/config.py

@@ -0,0 +1,21 @@
+"""Configuration for the OpenRouter OAuth PKCE flow.
+
+OpenRouter's flow is deliberately simple: no client id, no scopes, no
+refresh tokens. The authorization code is exchanged at ``keys_url`` for a
+user-controlled API key. Localhost callbacks are supported on any port, so
+we bind an ephemeral one. See https://openrouter.ai/docs/use-cases/oauth-pkce
+"""
+
+from __future__ import annotations
+
+OPENROUTER_OAUTH_CONFIG = {
+    "auth_url": "https://openrouter.ai/auth",
+    "keys_url": "https://openrouter.ai/api/v1/auth/keys",
+    "env_var": "OPENROUTER_API_KEY",
+    "provider_id": "openrouter",
+    "redirect_host": "localhost",
+    "redirect_path": "/callback",
+    # OpenRouter authorization codes are single-use and expire after 10
+    # minutes; give the user most of that window.
+    "callback_timeout": 540,
+}

code_puppy_core_plugins-0.0.27/code_puppy_core_plugins/openrouter_oauth/oauth_flow.py

@@ -0,0 +1,242 @@
+"""OpenRouter OAuth PKCE flow.
+
+Follows https://openrouter.ai/docs/use-cases/oauth-pkce: send the user to
+``/auth`` with an S256 code challenge, receive the authorization code on a
+localhost callback (any port is allowed), then exchange code + verifier at
+``/api/v1/auth/keys`` for a user-controlled API key. There is no state
+parameter in OpenRouter's flow -- PKCE is the integrity mechanism, and the
+code is single-use with a 10 minute expiry.
+
+The key is persisted via :func:`code_puppy.provider_credentials.save_credential`
+so it is immediately usable by the model factory (puppy.cfg + os.environ).
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import secrets
+import threading
+import time
+import urllib.parse
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Any, Tuple
+
+import requests
+
+from code_puppy.messaging import emit_error, emit_info, emit_success, emit_warning
+from code_puppy.provider_credentials import save_credential
+
+from ..oauth_pasteback import parse_oauth_callback_input, read_available_stdin_line
+from ..oauth_puppy_html import oauth_failure_html, oauth_success_html
+from .config import OPENROUTER_OAUTH_CONFIG
+
+
+def generate_pkce_pair() -> Tuple[str, str]:
+    """Return an S256 ``(code_verifier, code_challenge)`` pair."""
+    verifier = secrets.token_urlsafe(64)
+    digest = hashlib.sha256(verifier.encode("ascii")).digest()
+    challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
+    return verifier, challenge
+
+
+def exchange_code_for_key(code: str, code_verifier: str) -> str:
+    """Exchange an authorization code for a user-controlled API key.
+
+    Raises on HTTP errors or a malformed response so callers can surface
+    the failure; returns the API key on success.
+    """
+    response = requests.post(
+        OPENROUTER_OAUTH_CONFIG["keys_url"],
+        json={
+            "code": code,
+            "code_verifier": code_verifier,
+            "code_challenge_method": "S256",
+        },
+        timeout=30,
+    )
+    response.raise_for_status()
+    key = response.json().get("key")
+    if not key:
+        raise RuntimeError("OpenRouter response did not include an API key")
+    return key
+
+
+def _save_key(key: str) -> None:
+    save_credential(OPENROUTER_OAUTH_CONFIG["env_var"], key)
+
+
+class _OAuthServer(HTTPServer):
+    """Localhost callback server holding the state for one OAuth attempt."""
+
+    def __init__(self) -> None:
+        host = OPENROUTER_OAUTH_CONFIG["redirect_host"]
+        # OpenRouter explicitly supports localhost callbacks on any port.
+        super().__init__((host, 0), _CallbackHandler)
+
+        self.exit_code = 1
+        self.code_verifier, self.code_challenge = generate_pkce_pair()
+        port = self.server_address[1]
+        path = OPENROUTER_OAUTH_CONFIG["redirect_path"]
+        self.callback_url = f"http://{host}:{port}{path}"
+
+    def auth_url(self) -> str:
+        params = {
+            "callback_url": self.callback_url,
+            "code_challenge": self.code_challenge,
+            "code_challenge_method": "S256",
+        }
+        return f"{OPENROUTER_OAUTH_CONFIG['auth_url']}?{urllib.parse.urlencode(params)}"
+
+    def exchange_code(self, code: str) -> None:
+        _save_key(exchange_code_for_key(code, self.code_verifier))
+
+
+class _CallbackHandler(BaseHTTPRequestHandler):
+    server: "_OAuthServer"
+
+    def do_GET(self) -> None:  # noqa: N802
+        parsed = urllib.parse.urlparse(self.path)
+        if parsed.path != OPENROUTER_OAUTH_CONFIG["redirect_path"]:
+            self._send_failure(404, "Callback endpoint not found for the puppy parade.")
+            return
+
+        params = urllib.parse.parse_qs(parsed.query)
+        error = params.get("error", [None])[0]
+        if error:
+            description = params.get("error_description", [error])[0]
+            self._send_failure(400, f"OpenRouter authorization failed: {description}")
+            self._shutdown_after_delay()
+            return
+
+        code = params.get("code", [None])[0]
+        if not code:
+            self._send_failure(400, "Missing auth code — the token treat rolled away.")
+            self._shutdown_after_delay()
+            return
+
+        try:
+            self.server.exchange_code(code)
+        except Exception as exc:  # noqa: BLE001
+            self._send_failure(500, f"Key exchange failed: {exc}")
+            self._shutdown_after_delay()
+            return
+
+        self.server.exit_code = 0
+        self._send_html(
+            oauth_success_html(
+                "OpenRouter",
+                "You can now close this window and return to Code Puppy.",
+            )
+        )
+        self._shutdown_after_delay()
+
+    def log_message(self, fmt: str, *args: Any) -> None:  # noqa: A003
+        pass
+
+    def _send_html(self, body: str, status: int = 200) -> None:
+        encoded = body.encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.send_header("Content-Length", str(len(encoded)))
+        self.end_headers()
+        self.wfile.write(encoded)
+
+    def _send_failure(self, status: int, reason: str) -> None:
+        self._send_html(oauth_failure_html("OpenRouter", reason), status)
+
+    def _shutdown_after_delay(self, seconds: float = 2.0) -> None:
+        def _later() -> None:
+            time.sleep(seconds)
+            self.server.shutdown()
+
+        threading.Thread(target=_later, daemon=True).start()
+
+
+def _complete_pasted_input(raw_input: str, code_verifier: str) -> bool:
+    """Exchange a pasted callback URL / bare code for an API key."""
+    try:
+        parsed = parse_oauth_callback_input(raw_input)
+    except ValueError as exc:
+        emit_error(f"Could not parse pasted OAuth input: {exc}")
+        return False
+
+    if parsed.error:
+        emit_error(f"OpenRouter returned an error: {parsed.error_message}")
+        return False
+    if not parsed.code:
+        emit_error("Pasted OAuth input did not contain an authorization code.")
+        return False
+
+    try:
+        _save_key(exchange_code_for_key(parsed.code, code_verifier))
+    except Exception as exc:  # noqa: BLE001
+        emit_error(f"Key exchange failed: {exc}")
+        return False
+    return True
+
+
+def _wait_for_completion(server: _OAuthServer) -> bool:
+    """Poll for the localhost callback, accepting pasted input meanwhile."""
+    emit_info(
+        "Waiting for the OpenRouter callback. If localhost cannot be reached "
+        "(SSH, container), paste the full callback URL or authorization code "
+        "here and press Enter."
+    )
+
+    elapsed = 0.0
+    timeout = OPENROUTER_OAUTH_CONFIG["callback_timeout"]
+    interval = 0.25
+    while elapsed < timeout:
+        if server.exit_code == 0:
+            return True
+
+        pasted = read_available_stdin_line()
+        if pasted is not None and pasted.strip():
+            if _complete_pasted_input(pasted, server.code_verifier):
+                return True
+
+        time.sleep(interval)
+        elapsed += interval
+    return False
+
+
+def run_oauth_flow() -> bool:
+    """Run the browser PKCE flow. Returns True when a key was saved."""
+    try:
+        server = _OAuthServer()
+    except Exception as exc:  # noqa: BLE001
+        emit_error(f"Could not start OpenRouter OAuth flow: {exc}")
+        return False
+
+    auth_url = server.auth_url()
+    emit_info(f"Open this URL in your browser: {auth_url}")
+
+    server_thread = threading.Thread(target=server.serve_forever, daemon=True)
+    server_thread.start()
+
+    from code_puppy.tools.common import should_suppress_browser
+
+    if should_suppress_browser():
+        emit_info(f"[HEADLESS MODE] Would normally open: {auth_url}")
+    else:
+        try:
+            import webbrowser
+
+            if not webbrowser.open(auth_url):
+                emit_warning("Please open the URL manually — the browser stayed home.")
+        except Exception as exc:  # noqa: BLE001
+            emit_warning(f"Could not open browser automatically: {exc}")
+
+    completed = _wait_for_completion(server)
+
+    server.shutdown()
+    server_thread.join(timeout=5)
+
+    if not completed:
+        emit_error("OpenRouter authentication failed or timed out.")
+        return False
+
+    env_var = OPENROUTER_OAUTH_CONFIG["env_var"]
+    emit_success(f"OpenRouter OAuth complete — API key saved as {env_var}.")
+    return True

code_puppy_core_plugins-0.0.27/code_puppy_core_plugins/openrouter_oauth/register_callbacks.py

@@ -0,0 +1,93 @@
+"""OpenRouter OAuth plugin callbacks.
+
+Hooks into the ``/add_model`` credential step: when the user adds an
+OpenRouter model and ``OPENROUTER_API_KEY`` is not set, offer the one-click
+browser PKCE sign-in before falling back to manual key entry.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+from code_puppy.callbacks import register_callback
+
+from .config import OPENROUTER_OAUTH_CONFIG
+
+logger = logging.getLogger(__name__)
+
+_OAUTH = "oauth"
+_MANUAL = "manual"
+
+
+def _themed(builder):
+    """Apply the app menu theme when the host exposes it."""
+    try:
+        from code_puppy.command_line.tui_style import themed
+    except Exception:  # noqa: BLE001 - older cores; unthemed menus still work
+        return builder
+    return themed(builder)
+
+
+def build_choice_menu(**overrides):
+    """Menu offering browser sign-in vs manual key entry."""
+    from termflow.tui import MenuBuilder, MenuItem
+
+    env_var = OPENROUTER_OAUTH_CONFIG["env_var"]
+    builder = _themed(
+        MenuBuilder(f"OpenRouter needs {env_var}")
+        .items(
+            [
+                MenuItem(
+                    "Sign in with OpenRouter (browser)",
+                    value=_OAUTH,
+                    description="OAuth PKCE — mints a key for you",
+                ),
+                MenuItem(
+                    "Paste an API key manually",
+                    value=_MANUAL,
+                    description="Get one at https://openrouter.ai/keys",
+                ),
+            ]
+        )
+        .alt_screen(False)
+        .footer_hint("Enter select - Esc enter key manually")
+    )
+    for name, value in overrides.items():
+        getattr(builder, name)(value)
+    return builder.build()
+
+
+def choose_flow(**overrides) -> str:
+    """Ask how to acquire the key. Esc/cancel defers to manual entry."""
+    result = build_choice_menu(**overrides).run()
+    if result.cancelled or result.item is None:
+        return _MANUAL
+    return result.item.value
+
+
+def _credential_flow(*, provider_id: str, env_var: str) -> Optional[bool]:
+    """``provider_credential_flow`` hook: OpenRouter browser sign-in.
+
+    Returns True when a key was obtained and saved; None to defer to the
+    core manual-entry prompt (wrong provider, user preference, or a failed
+    OAuth attempt).
+    """
+    if (
+        provider_id != OPENROUTER_OAUTH_CONFIG["provider_id"]
+        or env_var != OPENROUTER_OAUTH_CONFIG["env_var"]
+    ):
+        return None
+    if choose_flow() != _OAUTH:
+        return None
+
+    from .oauth_flow import run_oauth_flow
+
+    return True if run_oauth_flow() else None
+
+
+try:
+    register_callback("provider_credential_flow", _credential_flow)
+except ValueError:
+    # Older core without the hook: stay quiet, /add_model still works manually.
+    logger.debug("Core lacks provider_credential_flow; openrouter_oauth inactive")

code_puppy_core_plugins-0.0.27/code_puppy_core_plugins/openrouter_oauth/test_plugin.py

@@ -0,0 +1,263 @@
+"""Tests for the OpenRouter OAuth PKCE plugin."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import threading
+import urllib.error
+import urllib.parse
+import urllib.request
+from io import StringIO
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from code_puppy_core_plugins.openrouter_oauth import oauth_flow, register_callbacks
+from code_puppy_core_plugins.openrouter_oauth.config import OPENROUTER_OAUTH_CONFIG
+
+
+# -- PKCE --------------------------------------------------------------------
+
+
+class TestPkce:
+    def test_challenge_is_s256_of_verifier(self):
+        verifier, challenge = oauth_flow.generate_pkce_pair()
+        expected = (
+            base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest())
+            .rstrip(b"=")
+            .decode()
+        )
+        assert challenge == expected
+        assert "=" not in challenge
+
+    def test_pairs_are_unique(self):
+        assert oauth_flow.generate_pkce_pair() != oauth_flow.generate_pkce_pair()
+
+
+# -- code -> key exchange ----------------------------------------------------
+
+
+class TestExchange:
+    def _response(self, payload, status=200):
+        response = MagicMock()
+        response.json.return_value = payload
+        if status >= 400:
+            response.raise_for_status.side_effect = Exception(f"HTTP {status}")
+        return response
+
+    def test_success_returns_key(self):
+        with patch.object(oauth_flow.requests, "post") as mock_post:
+            mock_post.return_value = self._response({"key": "sk-or-v1-abc"})
+            key = oauth_flow.exchange_code_for_key("code123", "verifier456")
+        assert key == "sk-or-v1-abc"
+        _, kwargs = mock_post.call_args
+        assert kwargs["json"] == {
+            "code": "code123",
+            "code_verifier": "verifier456",
+            "code_challenge_method": "S256",
+        }
+        assert mock_post.call_args[0][0] == OPENROUTER_OAUTH_CONFIG["keys_url"]
+
+    def test_missing_key_raises(self):
+        with patch.object(oauth_flow.requests, "post") as mock_post:
+            mock_post.return_value = self._response({"nope": True})
+            with pytest.raises(RuntimeError, match="did not include an API key"):
+                oauth_flow.exchange_code_for_key("code", "verifier")
+
+    def test_http_error_propagates(self):
+        with patch.object(oauth_flow.requests, "post") as mock_post:
+            mock_post.return_value = self._response({}, status=403)
+            with pytest.raises(Exception, match="HTTP 403"):
+                oauth_flow.exchange_code_for_key("code", "verifier")
+
+
+# -- localhost callback server -----------------------------------------------
+
+
+class TestCallbackServer:
+    def _serve(self):
+        server = oauth_flow._OAuthServer()
+        thread = threading.Thread(target=server.serve_forever, daemon=True)
+        thread.start()
+        return server, thread
+
+    def _get(self, url):
+        try:
+            with urllib.request.urlopen(url, timeout=5) as response:
+                return response.status
+        except urllib.error.HTTPError as exc:
+            return exc.code
+
+    def test_auth_url_contains_callback_and_challenge(self):
+        server = oauth_flow._OAuthServer()
+        try:
+            url = server.auth_url()
+            assert url.startswith(OPENROUTER_OAUTH_CONFIG["auth_url"])
+            assert urllib.parse.quote(server.callback_url, safe="") in url
+            assert "code_challenge_method=S256" in url
+        finally:
+            server.server_close()
+
+    def test_callback_with_code_saves_key(self):
+        server, thread = self._serve()
+        try:
+            with (
+                patch.object(oauth_flow, "exchange_code_for_key") as mock_exchange,
+                patch.object(oauth_flow, "save_credential") as mock_save,
+            ):
+                mock_exchange.return_value = "sk-or-v1-abc"
+                status = self._get(f"{server.callback_url}?code=authcode")
+            assert status == 200
+            assert server.exit_code == 0
+            mock_exchange.assert_called_once_with("authcode", server.code_verifier)
+            mock_save.assert_called_once_with(
+                OPENROUTER_OAUTH_CONFIG["env_var"], "sk-or-v1-abc"
+            )
+        finally:
+            server.shutdown()
+            thread.join(timeout=5)
+
+    def test_callback_missing_code_fails(self):
+        server, thread = self._serve()
+        try:
+            assert self._get(server.callback_url) == 400
+            assert server.exit_code == 1
+        finally:
+            server.shutdown()
+            thread.join(timeout=5)
+
+    def test_callback_wrong_path_404s(self):
+        server, thread = self._serve()
+        try:
+            host, port = server.server_address[:2]
+            assert self._get(f"http://{host}:{port}/nope?code=x") == 404
+        finally:
+            server.shutdown()
+            thread.join(timeout=5)
+
+    def test_callback_provider_error_fails(self):
+        server, thread = self._serve()
+        try:
+            status = self._get(
+                f"{server.callback_url}?error=access_denied"
+                "&error_description=user+said+no"
+            )
+            assert status == 400
+            assert server.exit_code == 1
+        finally:
+            server.shutdown()
+            thread.join(timeout=5)
+
+
+# -- pasted input ------------------------------------------------------------
+
+
+class TestPastedInput:
+    def test_full_url_paste_exchanges_code(self):
+        with (
+            patch.object(oauth_flow, "exchange_code_for_key") as mock_exchange,
+            patch.object(oauth_flow, "save_credential") as mock_save,
+        ):
+            mock_exchange.return_value = "sk-or-v1-abc"
+            ok = oauth_flow._complete_pasted_input(
+                "http://localhost:5555/callback?code=pasted", "verifier"
+            )
+        assert ok is True
+        mock_exchange.assert_called_once_with("pasted", "verifier")
+        mock_save.assert_called_once()
+
+    def test_error_paste_fails(self):
+        ok = oauth_flow._complete_pasted_input(
+            "?error=access_denied&error_description=nope", "verifier"
+        )
+        assert ok is False
+
+    def test_exchange_failure_reported(self):
+        with patch.object(oauth_flow, "exchange_code_for_key") as mock_exchange:
+            mock_exchange.side_effect = RuntimeError("boom")
+            assert oauth_flow._complete_pasted_input("barecode", "verifier") is False
+
+
+# -- credential-flow hook ----------------------------------------------------
+
+
+class TestCredentialFlowHook:
+    def test_ignores_other_providers(self):
+        with patch.object(register_callbacks, "choose_flow") as mock_choose:
+            assert (
+                register_callbacks._credential_flow(
+                    provider_id="acme", env_var="ACME_API_KEY"
+                )
+                is None
+            )
+        mock_choose.assert_not_called()
+
+    def test_ignores_other_env_vars(self):
+        with patch.object(register_callbacks, "choose_flow") as mock_choose:
+            assert (
+                register_callbacks._credential_flow(
+                    provider_id="openrouter", env_var="SOMETHING_ELSE"
+                )
+                is None
+            )
+        mock_choose.assert_not_called()
+
+    def test_manual_choice_defers(self):
+        with (
+            patch.object(register_callbacks, "choose_flow", return_value="manual"),
+            patch.object(oauth_flow, "run_oauth_flow") as mock_run,
+        ):
+            assert (
+                register_callbacks._credential_flow(
+                    provider_id="openrouter", env_var="OPENROUTER_API_KEY"
+                )
+                is None
+            )
+        mock_run.assert_not_called()
+
+    def test_oauth_success_returns_true(self):
+        with (
+            patch.object(register_callbacks, "choose_flow", return_value="oauth"),
+            patch.object(oauth_flow, "run_oauth_flow", return_value=True),
+        ):
+            assert (
+                register_callbacks._credential_flow(
+                    provider_id="openrouter", env_var="OPENROUTER_API_KEY"
+                )
+                is True
+            )
+
+    def test_oauth_failure_defers_to_manual(self):
+        with (
+            patch.object(register_callbacks, "choose_flow", return_value="oauth"),
+            patch.object(oauth_flow, "run_oauth_flow", return_value=False),
+        ):
+            assert (
+                register_callbacks._credential_flow(
+                    provider_id="openrouter", env_var="OPENROUTER_API_KEY"
+                )
+                is None
+            )
+
+
+# -- choice menu (headless) --------------------------------------------------
+
+
+class TestChoiceMenu:
+    def _keys(self, *keys):
+        script = iter(keys)
+        return {
+            "key_source": lambda: next(script),
+            "output": StringIO(),
+            "size": lambda: (90, 20),
+        }
+
+    def test_enter_selects_oauth(self):
+        assert register_callbacks.choose_flow(**self._keys("enter")) == "oauth"
+
+    def test_down_enter_selects_manual(self):
+        assert register_callbacks.choose_flow(**self._keys("down", "enter")) == "manual"
+
+    def test_escape_defers_to_manual(self):
+        assert register_callbacks.choose_flow(**self._keys("escape")) == "manual"

{code_puppy_core_plugins-0.0.26 → code_puppy_core_plugins-0.0.27}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "code-puppy-core-plugins"
-version = "0.0.26"
+version = "0.0.27"
 description = "Official plugin bundle for Code Puppy"
 readme = "README.md"
 requires-python = ">=3.11,<3.15"
@@ -64,6 +64,7 @@ no_tools = "code_puppy_core_plugins.no_tools.register_callbacks"
 obsidian_agent = "code_puppy_core_plugins.obsidian_agent.register_callbacks"
 ollama = "code_puppy_core_plugins.ollama.register_callbacks"
 ollama_setup = "code_puppy_core_plugins.ollama_setup.register_callbacks"
+openrouter_oauth = "code_puppy_core_plugins.openrouter_oauth.register_callbacks"
 plugin_list = "code_puppy_core_plugins.plugin_list.register_callbacks"
 pop_command = "code_puppy_core_plugins.pop_command.register_callbacks"
 prompt_newline = "code_puppy_core_plugins.prompt_newline.register_callbacks"