Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python
14.1 KB
Raw Blame
"""Manage FCC's own saved Claude Desktop gateway configuration."""

import getpass
import json
import os
import re
import sys
from dataclasses import dataclass
from pathlib import Path
from typing import cast
from urllib.parse import urlsplit
from uuid import NAMESPACE_URL, uuid5

from free_claude_code.config.server_urls import same_proxy_url
from free_claude_code.core.json_types import JsonObject
from free_claude_code.harnesses.config_file import atomic_write_text, decode_json

_IDENTITY = (
    "https://github.com/Alishahryar1/free-claude-code/integrations/claude-desktop"
)
FCC_ID = str(uuid5(NAMESPACE_URL, _IDENTITY))
DEFAULT_ID = str(uuid5(NAMESPACE_URL, _IDENTITY + "/default"))
_VIEW_HEADER = "X-FCC-Model-View"


class ManagedDesktopError(ValueError):
    """Local configuration cannot override an organization policy."""


class PendingDisconnectError(ValueError):
    """A new connection must wait for the requested removal to finish."""


class PendingMigrationError(ValueError):
    """Desktop must move its legacy Windows data before FCC creates the new root."""


def config_root() -> Path:
    home = Path.home()
    if sys.platform == "win32":
        parent = Path(os.environ.get("LOCALAPPDATA") or home / "AppData/Local")
    elif sys.platform == "darwin":
        parent = home / "Library/Application Support"
    else:
        parent = Path(os.environ.get("XDG_CONFIG_HOME") or home / ".config")
        if not parent.is_absolute():
            parent = home / ".config"
    return parent / "Claude-3p"


def legacy_windows_root() -> Path | None:
    appdata = os.environ.get("APPDATA")
    return Path(appdata) / "Claude-3p" if appdata else None


def _check_pending_migration(root: Path) -> None:
    if sys.platform != "win32":
        return
    try:
        root.stat()
    except FileNotFoundError:
        pass
    else:
        return
    legacy = legacy_windows_root()
    if legacy is not None:
        try:
            legacy.stat()
        except FileNotFoundError:
            return
        raise PendingMigrationError


def check_unmanaged() -> None:
    """Conservatively leave managed installations to their administrator."""
    try:
        if sys.platform == "win32":
            import winreg

            for hive in (winreg.HKEY_LOCAL_MACHINE, winreg.HKEY_CURRENT_USER):
                try:
                    with winreg.OpenKey(hive, r"SOFTWARE\Policies\Claude") as key:
                        if winreg.QueryInfoKey(key)[1]:
                            raise ManagedDesktopError
                except FileNotFoundError:
                    pass
        else:
            candidates = (
                [
                    Path(
                        "/Library/Managed Preferences/com.anthropic.claudefordesktop.plist"
                    ),
                    Path("/Library/Managed Preferences")
                    / getpass.getuser()
                    / "com.anthropic.claudefordesktop.plist",
                ]
                if sys.platform == "darwin"
                else [Path("/etc/claude-desktop/managed-settings.json")]
            )
            for path in candidates:
                try:
                    path.stat()
                except FileNotFoundError:
                    continue
                raise ManagedDesktopError
    except OSError:
        raise ManagedDesktopError from None


def _read(path: Path) -> JsonObject | None:
    try:
        value = decode_json(path.read_text(encoding="utf-8-sig"))
    except FileNotFoundError:
        return None
    if not isinstance(value, dict):
        raise ValueError("Desktop settings must be objects")
    return cast(JsonObject, value)


def _write(path: Path, value: JsonObject) -> bool:
    if _read(path) == value:
        return False
    atomic_write_text(path, json.dumps(value, indent=2, allow_nan=False) + "\n")
    return True


def _headers(profile: JsonObject) -> dict[str, str]:
    value = profile.get("inferenceCustomHeaders", {})
    if not isinstance(value, dict) or any(
        not isinstance(k, str) or not isinstance(v, str) for k, v in value.items()
    ):
        raise ValueError("Invalid Desktop custom headers")
    return cast(dict[str, str], value)


def _owned(profile: JsonObject) -> bool:
    return profile.get("inferenceProvider") == "gateway" and any(
        key.lower() == _VIEW_HEADER.lower() and value == "claude-desktop"
        for key, value in _headers(profile).items()
    )


@dataclass
class _Library:
    root: Path
    metadata: JsonObject | None
    entries: list[JsonObject]
    profile: JsonObject | None
    mode: JsonObject

    def file(self, name: str) -> Path:
        return (self.root / name).resolve()

    @property
    def profile_path(self) -> Path:
        return self.file(f"configLibrary/{FCC_ID}.json")

    @property
    def metadata_path(self) -> Path:
        return self.file("configLibrary/_meta.json")

    @property
    def mode_path(self) -> Path:
        return self.file("claude_desktop_config.json")

    @property
    def default_path(self) -> Path:
        return self.file(f"configLibrary/{DEFAULT_ID}.json")

    @property
    def selected(self) -> bool:
        return self.metadata is not None and self.metadata.get("appliedId") == FCC_ID

    @property
    def active(self) -> bool:
        return (
            self.selected
            and self.mode.get("deploymentMode") == "3p"
            and self.metadata is not None
            and not self.metadata.get("hybridPointer")
        )

    def paths(self) -> JsonObject:
        result: JsonObject = {
            "desktop_profile": str(self.profile_path),
            "desktop_library": str(self.metadata_path),
            "desktop_settings": str(self.mode_path),
        }
        if not self.entries or self.selected:
            result["default_profile"] = str(self.default_path)
        return result

    def validate_default(self) -> None:
        if _read(self.default_path) not in (None, {}):
            raise ValueError("Reserved Default configuration is already used")

    def ensure_default(self) -> JsonObject:
        self.validate_default()
        _write(self.default_path, {})
        return {"id": DEFAULT_ID, "name": "Default"}


def _load(root: Path) -> _Library:
    check_unmanaged()
    library = _Library(root.resolve(), None, [], None, {})
    library.metadata = _read(library.metadata_path)
    library.profile = _read(library.profile_path)
    library.mode = _read(library.mode_path) or {}
    if library.metadata is not None:
        entries = library.metadata.get("entries")
        if not isinstance(entries, list) or not entries:
            raise ValueError("Invalid Desktop configuration library")
        ids: set[str] = set()
        for entry in entries:
            if (
                not isinstance(entry, dict)
                or not isinstance(entry.get("id"), str)
                or not isinstance(entry.get("name"), str)
            ):
                raise ValueError("Invalid Desktop entry")
            entry_id = cast(str, entry["id"])
            if not re.fullmatch(r"[a-f0-9-]{36}", entry_id) or entry_id in ids:
                raise ValueError("Invalid or duplicate Desktop entry ID")
            if entry_id == FCC_ID and entry["name"] != "FCC":
                raise ValueError("FCC profile ID is already used")
            ids.add(entry_id)
        applied_id = library.metadata.get("appliedId")
        if not isinstance(applied_id, str) or applied_id not in ids:
            raise ValueError("Invalid Desktop active entry")
        library.entries = cast(list[JsonObject], entries)
    if library.profile is not None:
        _headers(library.profile)
        registered = any(entry["id"] == FCC_ID for entry in library.entries)
        if library.profile.get("inferenceProvider") != "gateway" or (
            not registered and not _owned(library.profile)
        ):
            raise ValueError("FCC profile ID is already used")
    return library


def _values(url: str, token: str) -> JsonObject:
    parsed = urlsplit(url)
    if (
        not token
        or not parsed.hostname
        or parsed.username
        or parsed.password
        or parsed.query
        or parsed.fragment
        or parsed.path not in ("", "/")
    ):
        raise ValueError("Invalid Desktop gateway")
    if parsed.scheme != "https" and not (
        parsed.scheme == "http" and parsed.hostname in {"localhost", "127.0.0.1", "::1"}
    ):
        raise ValueError("Desktop requires a loopback HTTP or HTTPS gateway")
    return {
        "inferenceProvider": "gateway",
        "inferenceGatewayBaseUrl": url.rstrip("/"),
        "inferenceCredentialKind": "static",
        "inferenceGatewayApiKey": token,
        "inferenceGatewayAuthScheme": "bearer",
        "modelDiscoveryEnabled": True,
    }


def _current(library: _Library, values: JsonObject) -> bool:
    profile = library.profile
    return bool(
        library.active
        and profile is not None
        and _owned(profile)
        and all(
            profile.get(key) == value
            for key, value in values.items()
            if key != "inferenceGatewayBaseUrl"
        )
        and same_proxy_url(
            profile.get("inferenceGatewayBaseUrl"),
            str(values["inferenceGatewayBaseUrl"]),
        )
    )


def _update_profile(library: _Library, values: JsonObject) -> bool:
    profile = dict(library.profile or {})
    headers = {
        k: v for k, v in _headers(profile).items() if k.lower() != _VIEW_HEADER.lower()
    }
    headers[_VIEW_HEADER] = "claude-desktop"
    profile.update(values)
    # Desktop otherwise restricts tool network access to the inference gateway.
    profile.setdefault("coworkEgressAllowedHosts", ["*"])
    profile["inferenceCustomHeaders"] = headers
    return _write(library.profile_path, profile)


def _disconnect_intent(path: Path, root: Path) -> bool | None:
    record = _read(path)
    if record is None:
        return None
    if (
        set(record) != {"root", "return_to_sign_in"}
        or record["root"] != str(root.resolve())
        or not isinstance(record["return_to_sign_in"], bool)
    ):
        raise ValueError("Invalid Desktop disconnect record")
    return record["return_to_sign_in"]


def _empty_profile(path: Path) -> bool:
    try:
        return _read(path) == {}
    except ValueError, UnicodeError:
        # A user may change the neutral profile between a failure and retry.
        return False


def _disconnect(library: _Library, path: Path, intent: bool | None) -> None:
    has_entry = any(entry["id"] == FCC_ID for entry in library.entries)
    if not has_entry and library.profile is None and intent is None:
        return
    if library.selected:
        library.validate_default()
    return_to_sign_in = intent is True or library.selected
    _write(path, {"root": str(library.root), "return_to_sign_in": return_to_sign_in})
    if library.selected:
        default = library.ensure_default()
        entries = list(library.entries)
        if not any(entry["id"] == DEFAULT_ID for entry in entries):
            entries.append(default)
        metadata = dict(library.metadata or {})
        metadata.update({"entries": entries, "appliedId": DEFAULT_ID})
        metadata.pop("hybridPointer", None)
        _write(library.metadata_path, metadata)
        library = _load(library.root)
    if (
        return_to_sign_in
        and library.metadata is not None
        and library.metadata.get("appliedId") == DEFAULT_ID
        and not library.metadata.get("hybridPointer")
        and _empty_profile(library.default_path)
    ):
        _write(library.mode_path, library.mode | {"deploymentMode": "1p"})
    # Keep the registered ownership until unlink succeeds, even if its header
    # was changed. A retry after unlink safely accepts the missing profile.
    library.profile_path.unlink(missing_ok=True)
    library = _load(library.root)
    entries = [entry for entry in library.entries if entry["id"] != FCC_ID]
    if len(entries) != len(library.entries):
        metadata = dict(library.metadata or {})
        metadata["entries"] = entries
        _write(library.metadata_path, metadata)
    remaining = _load(library.root)
    if remaining.profile is not None or any(
        entry["id"] == FCC_ID for entry in remaining.entries
    ):
        raise ValueError("Desktop disconnect cleanup is incomplete")
    path.unlink(missing_ok=True)


def refresh_connected(
    root: Path, proxy_root_url: str, auth_token: str, *, disconnect_path: Path
) -> bool:
    library = _load(root)
    if _disconnect_intent(disconnect_path, root) is not None:
        return False
    if not library.active or library.profile is None:
        return False
    return _update_profile(library, _values(proxy_root_url, auth_token))


def configure(
    root: Path,
    proxy_root_url: str,
    auth_token: str,
    connected: bool | None = None,
    *,
    disconnect_path: Path,
) -> JsonObject:
    library = _load(root)
    disconnect_path = disconnect_path.resolve()
    intent = _disconnect_intent(disconnect_path, root)
    if connected is True:
        if intent is not None:
            raise PendingDisconnectError
        _check_pending_migration(library.root)
        values = _values(proxy_root_url, auth_token)
        if not library.entries:
            library.validate_default()
            library.entries = [library.ensure_default()]
        _update_profile(library, values)
        entries = [entry for entry in library.entries if entry["id"] != FCC_ID]
        entries.append({"id": FCC_ID, "name": "FCC"})
        metadata = dict(library.metadata or {})
        metadata.update({"entries": entries, "appliedId": FCC_ID})
        metadata.pop("hybridPointer", None)
        _write(library.metadata_path, metadata)
        _write(library.mode_path, library.mode | {"deploymentMode": "3p"})
    elif connected is False:
        _disconnect(library, disconnect_path, intent)
    if connected is not None:
        library = _load(root)
    is_connected = (
        library.active and library.profile is not None and connected is not False
    )
    if is_connected:
        is_connected = _current(library, _values(proxy_root_url, auth_token))
    return {
        "connected": is_connected,
        "disconnect_pending": _disconnect_intent(disconnect_path, root) is not None,
        "paths": library.paths() | {"disconnect_record": str(disconnect_path)},
    }