flowgraphapp 0.1.1__py3-none-any.whl

flowgraph/keys.py

@@ -0,0 +1,133 @@
+"""Provider API keys — stored in the OS keychain, never in the wheel or the browser.
+
+Resolution precedence (mirrors Simon Willison's `llm` CLI, the de-facto standard):
+explicit value > OS keychain (`keyring`) > environment variable > 0600 config file.
+The 0600 file is a fallback used ONLY when no OS keychain backend is available
+(e.g. headless Linux where keyring degrades to the Null backend). The key source is
+always reported so the UI/trace can be honest about where a secret came from.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Optional, Tuple
+
+from .config import config_dir
+
+SERVICE = "flowgraph"
+
+# provider -> accepted environment-variable names (first hit wins)
+ENV_VARS = {
+    "anthropic": ("ANTHROPIC_API_KEY",),
+    "openrouter": ("OPENROUTER_API_KEY",),
+    "openai": ("OPENAI_API_KEY",),
+    "google": ("GEMINI_API_KEY", "GOOGLE_API_KEY"),
+    "deepseek": ("DEEPSEEK_API_KEY",),
+}
+
+
+def _keys_file() -> Path:
+    return config_dir() / "keys.json"
+
+
+def _keyring():
+    """Return the keyring module iff a real OS backend is available, else None."""
+    try:
+        import keyring
+        kr = keyring.get_keyring()
+        backend = type(kr).__module__.lower()
+        if "fail" in backend or "null" in backend:
+            return None
+        return keyring
+    except Exception:
+        return None
+
+
+def keyring_available() -> bool:
+    return _keyring() is not None
+
+
+def get_key(provider: str, explicit: Optional[str] = None) -> Tuple[Optional[str], str]:
+    """Return (key, source). source in {explicit, keychain, env, file, none}."""
+    if explicit:
+        return explicit, "explicit"
+
+    kr = _keyring()
+    if kr is not None:
+        try:
+            v = kr.get_password(SERVICE, provider)
+            if v:
+                return v, "keychain"
+        except Exception:
+            pass
+
+    for env in ENV_VARS.get(provider, ()):
+        v = os.environ.get(env)
+        if v:
+            return v, "env"
+
+    v = _read_file().get(provider)
+    if v:
+        return v, "file"
+
+    return None, "none"
+
+
+def set_key(provider: str, value: str) -> str:
+    """Persist a key. Returns the storage backend used ('keychain' or 'file')."""
+    kr = _keyring()
+    if kr is not None:
+        try:
+            kr.set_password(SERVICE, provider, value)
+            return "keychain"
+        except Exception:
+            pass
+    data = _read_file()
+    data[provider] = value
+    _write_file(data)
+    return "file"
+
+
+def delete_key(provider: str) -> None:
+    kr = _keyring()
+    if kr is not None:
+        try:
+            kr.delete_password(SERVICE, provider)
+        except Exception:
+            pass
+    data = _read_file()
+    if provider in data:
+        del data[provider]
+        _write_file(data)
+
+
+def _read_file() -> dict:
+    p = _keys_file()
+    if not p.is_file():
+        return {}
+    try:
+        return json.loads(p.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+
+
+def _write_file(data: dict) -> None:
+    """Atomic 0600 write — the fallback store must never be world-readable."""
+    p = _keys_file()
+    tmp = p.with_name(p.name + ".tmp")
+    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(data, f)
+    finally:
+        try:
+            os.chmod(tmp, 0o600)
+        except OSError:
+            pass
+    os.replace(tmp, p)
+    try:
+        os.chmod(p, 0o600)
+    except OSError:
+        pass

flowgraph/providers.py

@@ -0,0 +1,89 @@
+"""LLM provider resolution behind a typed boundary (charter §1 — swappable mechanism).
+
+Two pluggable kinds, modelled identically: a local OpenAI-compatible runtime
+(Ollama / LM Studio / llama.cpp — zero key, air-gapped) and BYOK cloud providers
+(key held server-side, never sent to the browser). Default is local-model-first:
+use a reachable local runtime, else fall back to the first BYOK provider with a key.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, Sequence
+
+import httpx
+
+from . import keys as keymod
+from .config import LOCAL_RUNTIME_PROBES
+
+BYOK_BASES = {
+    "anthropic": "https://api.anthropic.com",
+    "openrouter": "https://openrouter.ai/api",
+    "openai": "https://api.openai.com",
+    "deepseek": "https://api.deepseek.com",
+}
+
+DEFAULT_MODELS = {
+    "anthropic": "claude-haiku-4-5-20251001",
+    "openrouter": "anthropic/claude-haiku-4.5",
+    "openai": "gpt-4o-mini",
+    "deepseek": "deepseek-chat",
+    "local": "",  # let the runtime use its loaded model when unspecified
+}
+
+
+@dataclass
+class ProviderChoice:
+    kind: str          # 'local' | 'anthropic' | 'openrouter' | 'openai' | 'deepseek'
+    label: str         # human-readable, for honest surfacing (e.g. "Ollama (local, no key)")
+    base_url: str
+    api_key: Optional[str]
+    key_source: str    # 'none' | 'keychain' | 'env' | 'file' | 'explicit'
+
+    @property
+    def is_anthropic(self) -> bool:
+        return self.kind == "anthropic"
+
+
+async def detect_local_runtime(
+    client: httpx.AsyncClient, timeout: float = 0.8
+) -> Optional[ProviderChoice]:
+    """Probe well-known OpenAI-compatible local endpoints; return the first reachable."""
+    for name, base in LOCAL_RUNTIME_PROBES:
+        try:
+            r = await client.get(base + "/v1/models", timeout=timeout)
+            if r.status_code < 500:
+                return ProviderChoice(
+                    kind="local",
+                    label=f"{name} (local, no key)",
+                    base_url=base,
+                    api_key=None,
+                    key_source="none",
+                )
+        except Exception:
+            continue
+    return None
+
+
+async def resolve_provider(
+    client: httpx.AsyncClient,
+    *,
+    prefer_local: bool = True,
+    byok_order: Sequence[str] = ("anthropic", "openrouter", "openai", "deepseek"),
+) -> Optional[ProviderChoice]:
+    if prefer_local:
+        local = await detect_local_runtime(client)
+        if local is not None:
+            return local
+
+    for kind in byok_order:
+        key, source = keymod.get_key(kind)
+        if key:
+            return ProviderChoice(
+                kind=kind,
+                label=f"{kind} (key from {source})",
+                base_url=BYOK_BASES[kind],
+                api_key=key,
+                key_source=source,
+            )
+    return None

flowgraph/runtime_config.py

@@ -0,0 +1,27 @@
+"""Non-secret runtime config served at GET /config.
+
+This is the seam the SPA reads (build-once / runtime-config pattern) to learn that it
+is running under the local server and should route AI through the same-origin proxy
+(so the key stays server-side). It NEVER contains a provider key — only the active
+provider's kind/label and key SOURCE, for honest surfacing. The SPA consumes this at
+boot (L1, docs/18 §7.1): `store.init()` → `applyRuntimeConfig` → `resolveAiTransport`
+selects the same-origin proxy; in proxy mode the CSP connect-src is tightened to 'self'.
+"""
+
+from __future__ import annotations
+
+from . import __version__
+from .config import ServerConfig
+
+
+def runtime_config(config: ServerConfig) -> dict:
+    return {
+        "mode": "local",
+        "version": __version__,
+        # Same-origin: the SPA can use relative /api/... paths, so no base URL needed.
+        "apiBase": "",
+        "proxyEnabled": True,
+        "transport": "proxy",  # hint: prefer the server-side key proxy over browser BYOK
+        "auth": "cookie" if config.auth_enabled else "none",
+        "localModelFirst": True,
+    }

flowgraph/security.py

@@ -0,0 +1,291 @@
+"""The hardening layer. Assumes ``localhost`` is hostile-reachable.
+
+Defenses (all ON by default, fail-closed, enforced as ONE ASGI middleware so they
+cover every route — static assets, API, health, and any future SSE/WebSocket):
+
+1. Host-header allow-list   -> the load-bearing DNS-rebinding defense. A rebound
+   request arrives with ``Host: attacker.com`` and is rejected. Exact host:port
+   match only; substrings/suffixes/missing-Host/0.0.0.0/trailing-dot are rejected.
+2. Origin validation        -> on every WebSocket handshake and every state-changing
+   (non-GET) HTTP request, and on any HTTP request that carries a foreign Origin.
+   Defeats Cross-Site WebSocket Hijacking (WS is not covered by CORS).
+3. Session token            -> >=256-bit CSPRNG, required on every route except the
+   index handshake and /healthz. Constant-time compare. Defends against other local
+   users/processes (who can forge Host/Origin but cannot obtain the token).
+4. Security headers          -> strict CSP, nosniff, frame-ancestors 'none', etc. on
+   ALL responses (treat rendered/streamed content as untrusted).
+
+References: Jupyter (allow_remote_access=False), MCP-SDK CVE-2025-66416 (the trap of
+shipping this OFF by default), CWE-1385 (WS origin), the 0.0.0.0-day class.
+"""
+
+from __future__ import annotations
+
+import hmac
+import secrets
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional, Tuple
+
+from .config import PROVIDER_ORIGINS, ServerConfig
+
+LOOPBACK_HOSTNAMES = frozenset({"127.0.0.1", "localhost", "::1"})
+
+# Paths reachable WITHOUT a token. The index handshake and health only; everything
+# else (assets, /config, /api/*) requires auth.
+_AUTH_EXEMPT_PATHS = frozenset({"/", "/index.html", "/healthz"})
+
+
+# --------------------------------------------------------------------------- tokens
+
+def new_session_token() -> str:
+    """256-bit URL-safe token."""
+    return secrets.token_urlsafe(32)
+
+
+def tokens_match(a: str, b: str) -> bool:
+    """Constant-time comparison (never use ==)."""
+    if not a or not b:
+        return False
+    return hmac.compare_digest(a.encode("utf-8"), b.encode("utf-8"))
+
+
+@dataclass
+class _Ticket:
+    value: str
+    expires_at: float
+
+
+class TicketStore:
+    """Single-use, short-TTL tickets that bootstrap a session cookie from the launch URL.
+
+    The long-lived session token is NEVER placed in a URL (it would leak to logs /
+    history). Instead the launch URL carries a one-time ticket; the index route
+    exchanges it for an HttpOnly SameSite=Strict cookie and strips it via redirect.
+    """
+
+    def __init__(self, ttl_seconds: int = 600) -> None:
+        self._ttl = ttl_seconds
+        self._tickets: dict[str, _Ticket] = {}
+
+    def mint(self) -> str:
+        value = secrets.token_urlsafe(24)
+        self._tickets[value] = _Ticket(value, time.monotonic() + self._ttl)
+        return value
+
+    def consume(self, value: Optional[str]) -> bool:
+        if not value:
+            return False
+        t = self._tickets.pop(value, None)
+        if t is None:
+            return False
+        return t.expires_at >= time.monotonic()
+
+
+# ----------------------------------------------------------------------- host/origin
+
+def split_host_port(value: Optional[str]) -> Tuple[Optional[str], Optional[str]]:
+    """Parse a Host/authority header into (host, port). Rejects malformed input."""
+    if not value:
+        return None, None
+    value = value.strip()
+    if value.startswith("["):  # IPv6 literal: [::1]:port or [::1]
+        end = value.find("]")
+        if end == -1:
+            return None, None
+        host = value[1:end]
+        rest = value[end + 1:]
+        if rest == "":
+            return host, ""
+        if rest.startswith(":"):
+            return host, rest[1:]
+        return None, None
+    if value.count(":") == 0:
+        return value, ""
+    if value.count(":") == 1:
+        host, port = value.rsplit(":", 1)
+        return host, port
+    # bare IPv6 without brackets, or otherwise malformed -> reject
+    return None, None
+
+
+def host_allowed(host_header: Optional[str], bound_port: int) -> bool:
+    host, port = split_host_port(host_header)
+    if host is None:
+        return False
+    if host.lower() not in LOOPBACK_HOSTNAMES:
+        return False
+    # We always bind an explicit port; the Host must carry the matching port.
+    return port == str(bound_port)
+
+
+def allowed_origins(config: ServerConfig) -> frozenset:
+    scheme = config.scheme
+    port = config.port
+    origins = set()
+    for h in ("127.0.0.1", "localhost"):
+        origins.add(f"{scheme}://{h}:{port}")
+    origins.add(f"{scheme}://[::1]:{port}")
+    return frozenset(origins)
+
+
+def origin_allowed(origin: Optional[str], config: ServerConfig) -> bool:
+    if not origin:
+        return False
+    return origin in allowed_origins(config)
+
+
+# ------------------------------------------------------------------- security headers
+
+def safe_static_path(static_dir: Path, rel: str) -> Optional[Path]:
+    """Resolve ``rel`` under ``static_dir``, or None if it would escape (path traversal)."""
+    base = static_dir.resolve()
+    candidate = (base / rel).resolve()
+    try:
+        candidate.relative_to(base)
+    except ValueError:
+        return None
+    return candidate
+
+
+def content_security_policy(config: ServerConfig) -> str:
+    # connect-src: in PROXY mode (the default — see config.proxy_mode / GET /config) the SPA
+    # routes ALL AI through the same-origin proxy, so it never needs a provider or local-runtime
+    # origin — tighten to 'self' (docs/18 §4.8/§7.4). In BYOK-direct mode (proxy_mode=False) the
+    # browser calls providers/local runtimes itself, so those origins must be permitted.
+    if config.proxy_mode:
+        connect = ["'self'", *config.extra_connect_src]
+    else:
+        connect = ["'self'", *PROVIDER_ORIGINS]
+        for h in ("127.0.0.1", "localhost"):
+            connect += [f"http://{h}:11434", f"http://{h}:1234", f"http://{h}:8080"]
+        connect += list(config.extra_connect_src)
+    return "; ".join([
+        "default-src 'self'",
+        "script-src 'self'",
+        "style-src 'self' 'unsafe-inline'",  # React/Tailwind inline styles
+        "img-src 'self' data: blob:",
+        "font-src 'self' data:",
+        "worker-src 'self' blob:",  # pdf.worker
+        "connect-src " + " ".join(connect),
+        "base-uri 'self'",
+        "form-action 'self'",
+        "object-src 'none'",
+        "frame-ancestors 'none'",
+    ])
+
+
+def security_headers(config: ServerConfig) -> list[tuple[bytes, bytes]]:
+    headers = {
+        "content-security-policy": content_security_policy(config),
+        "x-content-type-options": "nosniff",
+        "x-frame-options": "DENY",
+        "referrer-policy": "same-origin",
+        "permissions-policy": "geolocation=(), microphone=(), camera=()",
+        "cross-origin-opener-policy": "same-origin",
+        "cross-origin-resource-policy": "same-origin",
+    }
+    if config.scheme == "https":
+        headers["strict-transport-security"] = "max-age=63072000"
+    return [(k.encode(), v.encode()) for k, v in headers.items()]
+
+
+# --------------------------------------------------------------------- ASGI middleware
+
+def _header(scope_headers, name: bytes) -> Optional[str]:
+    for k, v in scope_headers:
+        if k == name:
+            try:
+                return v.decode("latin-1")
+            except Exception:
+                return None
+    return None
+
+
+def _cookie_token(scope_headers) -> Optional[str]:
+    raw = _header(scope_headers, b"cookie")
+    if not raw:
+        return None
+    for part in raw.split(";"):
+        part = part.strip()
+        if part.startswith("fg_session="):
+            return part[len("fg_session="):]
+    return None
+
+
+class LocalSecurityMiddleware:
+    """One ASGI middleware enforcing Host/Origin/token + security headers on every route."""
+
+    def __init__(self, app, config: ServerConfig) -> None:
+        self.app = app
+        self.config = config
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] not in ("http", "websocket"):
+            return await self.app(scope, receive, send)
+
+        headers = scope.get("headers", [])
+        host = _header(headers, b"host")
+        origin = _header(headers, b"origin")
+        is_ws = scope["type"] == "websocket"
+        method = "GET" if is_ws else scope.get("method", "GET")
+        path = scope.get("path", "/")
+
+        # 1. Host allow-list — the primary DNS-rebinding defense. Every request.
+        if not host_allowed(host, self.config.port):
+            return await self._deny(scope, send, 403, "Forbidden host")
+
+        # 2. Origin validation — WS always; HTTP on non-safe methods or any foreign Origin.
+        if is_ws:
+            if not origin_allowed(origin, self.config):
+                return await self._deny(scope, send, 403, "Forbidden origin")
+        else:
+            if method not in ("GET", "HEAD", "OPTIONS"):
+                if not origin_allowed(origin, self.config):
+                    return await self._deny(scope, send, 403, "Forbidden origin")
+            elif origin is not None and not origin_allowed(origin, self.config):
+                return await self._deny(scope, send, 403, "Forbidden origin")
+
+        # 3. Token auth — unless disabled. The index handshake (ticket->cookie) and
+        #    /healthz are exempt; the index route itself enforces ticket-or-401.
+        if self.config.auth_enabled and not self._is_authed(headers):
+            if not (method in ("GET", "HEAD") and path in _AUTH_EXEMPT_PATHS):
+                return await self._deny(scope, send, 401, "Authentication required")
+
+        # Passed the gate — inject security headers on the way out.
+        await self.app(scope, receive, self._wrap_send(send))
+
+    def _is_authed(self, headers) -> bool:
+        bearer = _header(headers, b"authorization")
+        if bearer and bearer.lower().startswith("bearer "):
+            if tokens_match(bearer[7:].strip(), self.config.session_token):
+                return True
+        cookie = _cookie_token(headers)
+        if cookie and tokens_match(cookie, self.config.session_token):
+            return True
+        return False
+
+    def _wrap_send(self, send):
+        extra = security_headers(self.config)
+
+        async def wrapped(message):
+            if message["type"] == "http.response.start":
+                message = dict(message)
+                message["headers"] = list(message.get("headers", [])) + extra
+            await send(message)
+
+        return wrapped
+
+    async def _deny(self, scope, send, status: int, detail: str):
+        if scope["type"] == "websocket":
+            # Reject the handshake before accept.
+            await send({"type": "websocket.close", "code": 1008})
+            return
+        body = detail.encode("utf-8")
+        start_headers = [
+            (b"content-type", b"text/plain; charset=utf-8"),
+            (b"content-length", str(len(body)).encode()),
+        ] + security_headers(self.config)
+        await send({"type": "http.response.start", "status": status, "headers": start_headers})
+        await send({"type": "http.response.body", "body": body})

flowgraph/server.py

@@ -0,0 +1,96 @@
+"""The FastAPI app: hardened static SPA host + the /api/ai/chat proxy.
+
+Routes (all behind LocalSecurityMiddleware — Host/Origin/token + security headers):
+  GET  /healthz        liveness + version (Host-checked, no token)
+  GET  /config         non-secret runtime config for the SPA (auth required)
+  POST /api/ai/chat    LLM proxy, key stays server-side (auth + Origin required)
+  GET  /{path}         SPA: ticket->cookie handshake at root, then static + SPA fallback
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastapi import FastAPI, Request
+from fastapi.responses import FileResponse, JSONResponse, PlainTextResponse, RedirectResponse
+
+from . import __version__
+from .ai_proxy import proxy_chat
+from .config import ServerConfig, resolve_static_dir
+from .runtime_config import runtime_config
+from .security import LocalSecurityMiddleware, TicketStore, safe_static_path, tokens_match
+
+
+def _request_authed(request: Request, config: ServerConfig) -> bool:
+    auth = request.headers.get("authorization")
+    if auth and auth.lower().startswith("bearer ") and tokens_match(auth[7:].strip(), config.session_token):
+        return True
+    ck = request.cookies.get("fg_session")
+    return bool(ck and tokens_match(ck, config.session_token))
+
+
+def create_app(config: ServerConfig, tickets: TicketStore) -> FastAPI:
+    static_dir = Path(config.static_dir or resolve_static_dir()).resolve()
+    config.static_dir = static_dir
+    index_html = static_dir / "index.html"
+
+    app = FastAPI(title="FlowGraph (local)", version=__version__, docs_url=None, redoc_url=None, openapi_url=None)
+    app.add_middleware(LocalSecurityMiddleware, config=config)
+
+    @app.get("/healthz")
+    async def healthz():
+        return {"status": "ok", "version": __version__}
+
+    @app.get("/config")
+    async def config_route():
+        return runtime_config(config)
+
+    @app.post("/api/ai/chat")
+    async def ai_chat(request: Request):
+        try:
+            body = await request.json()
+        except Exception:
+            return JSONResponse({"text": None, "error": "invalid-json"}, status_code=400)
+        if not isinstance(body, dict) or not isinstance(body.get("messages"), list):
+            return JSONResponse({"text": None, "error": "messages-required"}, status_code=400)
+        result = await proxy_chat(body, prefer_local=config.local_model_first)
+        status = 200 if not result.get("error") else 502
+        return JSONResponse(result, status_code=status)
+
+    @app.get("/{full_path:path}")
+    async def spa(full_path: str, request: Request):
+        is_root = full_path in ("", "index.html")
+
+        # Ticket -> cookie handshake (bootstraps the session from the launch URL).
+        if is_root and config.auth_enabled and not _request_authed(request, config):
+            ticket = request.query_params.get("ticket")
+            if ticket and tickets.consume(ticket):
+                resp = RedirectResponse(url="/", status_code=302)
+                resp.set_cookie(
+                    "fg_session",
+                    config.session_token,
+                    httponly=True,
+                    samesite="strict",
+                    secure=(config.scheme == "https"),
+                    path="/",
+                )
+                return resp
+            return PlainTextResponse(
+                "FlowGraph is running. Open it using the URL printed in the terminal "
+                "where you launched `flowgraph` (it carries a one-time access ticket).",
+                status_code=401,
+            )
+
+        # Serve a static file (path-safe) or fall back to index.html for client-side routes.
+        candidate = safe_static_path(static_dir, full_path)
+        if candidate is None:
+            return PlainTextResponse("Not found", status_code=404)  # path traversal blocked
+        if candidate.is_file():
+            return FileResponse(candidate)
+        # Missing asset (has an extension) -> 404; missing route -> SPA fallback.
+        last = full_path.rsplit("/", 1)[-1]
+        if "." in last:
+            return PlainTextResponse("Not found", status_code=404)
+        return FileResponse(index_html)
+
+    return app