upscaler-cli 0.1.0__tar.gz

upscaler_cli-0.1.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: upscaler-cli
+Version: 0.1.0
+Summary: Upscaler CLI - search, retrieve, and manage documents, records, and workflows
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: httpx>=0.25
+Requires-Dist: cryptography>=41.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.14; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Requires-Dist: black>=24.0; extra == "dev"
+Requires-Dist: flake8>=7.0; extra == "dev"
+Requires-Dist: isort>=5.13; extra == "dev"

upscaler_cli-0.1.0/README.md

@@ -0,0 +1,110 @@
+# Upscaler CLI
+
+Command-line tool for searching, retrieving, and managing Upscaler documents, records, and workflows.
+
+## Install
+
+```bash
+pip install up-sdk
+```
+
+## Setup
+
+```bash
+upscaler config set server_url https://your-upscaler-api.com
+upscaler login
+```
+
+For dev/staging with self-signed certificates:
+
+```bash
+upscaler config set verify_ssl false
+```
+
+## Quick Start
+
+```bash
+# Check connection
+upscaler health
+
+# Search documents
+upscaler search "safety procedures"
+
+# Get an asset
+upscaler get rg_abc123
+upscaler get rg_abc123 --format schema
+upscaler get rg_abc123 --format markdown
+
+# List data
+upscaler list definitions
+upscaler list entries --definition-id rg_abc123
+upscaler list todos
+
+# View hierarchy
+upscaler hierarchy d_abc123
+
+# Manage todos
+upscaler todo create --title "Review document"
+upscaler todo close to_abc123
+
+# Manage entries
+upscaler entry create --definition-id rg_abc123 --data '{"title": "New item"}'
+upscaler entry create --definition-id rg_abc123 --data @payload.json
+
+# Get members and groups
+upscaler get <firebase_uid> --type member
+upscaler get g_abc123
+```
+
+## Global Flags
+
+Global flags go **before** the command:
+
+```bash
+upscaler --json list todos          # JSON output
+upscaler --verbose search "audit"   # show HTTP details
+upscaler --server https://... health  # override server URL
+upscaler --version                  # print version
+```
+
+## Write Safety
+
+Preview changes before committing:
+
+```bash
+upscaler entry create --definition-id rg_123 --data @payload.json --dry-run
+upscaler asset delete --asset-id rg_123 --dry-run
+```
+
+## Data Input
+
+Write commands accept `--data` in three forms:
+
+```bash
+--data '{"key": "value"}'          # inline JSON
+--data @payload.json               # from file (recommended)
+--data -                           # from stdin
+```
+
+## Configuration
+
+```bash
+upscaler config set server_url https://api.example.com
+upscaler config set verify_ssl false
+upscaler config get server_url
+```
+
+Settings stored at `~/.upscaler/config.json`. Overridden by environment variables (`UPSCALER_SERVER`, `UPSCALER_VERIFY_SSL`) and flags (`--server`).
+
+## Auth Commands
+
+```bash
+upscaler login       # browser-based OAuth2 login
+upscaler status      # check auth state + token expiry
+upscaler refresh     # refresh expired token
+upscaler logout      # revoke and clear tokens
+```
+
+## All Commands
+
+Run `upscaler --help` for the full command list, or `upscaler <command> --help` for details on any command.

upscaler_cli-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "upscaler-cli"
+version = "0.1.0"
+description = "Upscaler CLI - search, retrieve, and manage documents, records, and workflows"
+requires-python = ">=3.10"
+dependencies = [
+    "click>=8.0",
+    "httpx>=0.25",
+    "cryptography>=41.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-mock>=3.14",
+    "respx>=0.21",
+    "black>=24.0",
+    "flake8>=7.0",
+    "isort>=5.13",
+]
+
+[project.scripts]
+upscaler = "src.cli.main:cli"
+
+[tool.setuptools.packages.find]
+include = ["src*"]
+
+[tool.setuptools.package-data]
+src = ["SKILL.md"]
+
+[tool.black]
+line-length = 100
+
+[tool.isort]
+profile = "black"
+line_length = 100
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

upscaler_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

upscaler_cli-0.1.0/src/SKILL.md

@@ -0,0 +1,85 @@
+# Upscaler CLI
+
+Search, retrieve, and manage Upscaler documents, records, and workflows.
+
+## Setup
+
+```bash
+pip install up-sdk
+upscaler config set server_url https://your-api-url.com
+upscaler config set verify_ssl false  # for dev/staging with self-signed certs
+upscaler login
+```
+
+## Important: Global flags go BEFORE the command
+
+```bash
+upscaler --json list todos        # correct
+upscaler list todos --json        # WRONG — --json is a global flag
+upscaler --verbose --json search "query"  # correct
+```
+
+## Commands
+
+### Read
+
+```bash
+upscaler search "safety procedures"                          # table output
+upscaler --json search "compliance" --limit 5 --type policy  # JSON output
+upscaler get <asset_id>                                      # asset overview
+upscaler get <asset_id> --format markdown                    # document content
+upscaler get <asset_id> --format schema                      # field schema
+upscaler get <uid> --type member                             # member by ID
+upscaler get <group_id> --type group                         # group by ID (also auto-detected for g_ prefix)
+upscaler hierarchy <asset_id>                                # asset tree
+upscaler hierarchy <asset_id> --depth 5                      # deep tree
+upscaler list definitions                                    # all definitions
+upscaler list entries --definition-id <id>                   # entries for a definition
+upscaler list todos                                          # your todos
+upscaler list field-options --definition-id <id> --field-key <key>
+```
+
+### Write (use --dry-run to preview changes)
+
+```bash
+upscaler todo create --title "Review doc"
+upscaler todo close <id>
+upscaler entry create --definition-id <id> --data @payload.json
+upscaler entry update --entry-id <id> --data '{"values": {...}}'
+upscaler asset create --type register_definition --data '{"title": "..."}'
+upscaler asset delete --asset-id <id> --dry-run              # preview only
+```
+
+### Data Input
+
+Write commands accept `--data` in three forms:
+
+- Flag value: `--data '{"key": "value"}'`
+- File reference: `--data @payload.json` (safest — avoids shell escaping)
+- Stdin pipe: `echo '{}' | upscaler entry create --data -`
+
+### Utility
+
+```bash
+upscaler health                   # check server connectivity
+upscaler status                   # check auth state
+upscaler config set <key> <value> # persist settings
+upscaler config get <key>         # read settings
+```
+
+## Agent Usage
+
+Always use `--json` (global flag, before the command) for structured output:
+
+```bash
+upscaler --json search "audit"
+upscaler --json get <asset_id>
+upscaler --json list todos
+upscaler --json todo create --title "x"
+```
+
+## Error Handling
+
+- Exit code 0 = success
+- Exit code 1 = error → check stderr for details
+- Exit code 2 = auth required → tell user to run `upscaler login`

upscaler_cli-0.1.0/src/__init__.py

@@ -0,0 +1,3 @@
+"""Upscaler CLI — search, retrieve, and manage Upscaler content."""
+
+__version__ = "0.1.0"

upscaler_cli-0.1.0/src/auth/encryption.py

@@ -0,0 +1,83 @@
+"""Token encryption using Fernet with machine-bound PBKDF2 key derivation.
+
+Security model:
+- Key derived from machine identity (hostname:username) + random salt
+- PBKDF2-HMAC-SHA256 with 480,000 iterations
+- Fernet symmetric encryption (AES-128-CBC + HMAC-SHA256)
+- Tokens encrypted at rest, decrypted in-memory only
+- Different machine = different key = decryption fails
+"""
+
+import base64
+import getpass
+import json
+import platform
+
+from cryptography.fernet import Fernet, InvalidToken
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
+
+
+def _get_machine_identity() -> str:
+    """Return machine-bound identity string: '{hostname}:{username}'."""
+    hostname = platform.node()
+    username = getpass.getuser()
+    return f"{hostname}:{username}"
+
+
+def derive_key(salt: bytes) -> bytes:
+    """Derive a Fernet-compatible key from machine identity and salt.
+
+    Args:
+        salt: Random bytes (16 bytes recommended) from ~/.upscaler/.salt
+
+    Returns:
+        32-byte key suitable for Fernet encryption.
+    """
+    identity = _get_machine_identity().encode("utf-8")
+    kdf = PBKDF2HMAC(
+        algorithm=hashes.SHA256(),
+        length=32,
+        salt=salt,
+        iterations=480_000,
+    )
+    raw_key = kdf.derive(identity)
+    return base64.urlsafe_b64encode(raw_key)
+
+
+def encrypt(plaintext: str, key: bytes) -> bytes:
+    """Encrypt a plaintext string using Fernet.
+
+    Args:
+        plaintext: String to encrypt (typically JSON-serialized token data).
+        key: Fernet-compatible key from derive_key().
+
+    Returns:
+        Encrypted bytes (Fernet token).
+    """
+    fernet = Fernet(key)
+    return fernet.encrypt(plaintext.encode("utf-8"))
+
+
+def decrypt(ciphertext: bytes, key: bytes) -> str:
+    """Decrypt Fernet-encrypted bytes back to plaintext string.
+
+    Args:
+        ciphertext: Encrypted bytes from encrypt().
+        key: Same Fernet key used for encryption.
+
+    Returns:
+        Decrypted plaintext string.
+
+    Raises:
+        RuntimeError: If decryption fails (wrong key, corrupted data, or
+            token copied from another machine).
+    """
+    fernet = Fernet(key)
+    try:
+        return fernet.decrypt(ciphertext).decode("utf-8")
+    except InvalidToken:
+        raise RuntimeError(
+            "Token store corrupted or copied from another machine. "
+            "Run: upscaler login"
+        )

upscaler_cli-0.1.0/src/auth/oauth.py

@@ -0,0 +1,324 @@
+"""OAuth2 Authorization Code + PKCE flow for CLI login.
+
+Flow:
+1. Register client via Dynamic Client Registration (DCR)
+2. Generate PKCE code verifier + challenge
+3. Start localhost HTTP server for callback
+4. Open browser to authorize URL
+5. Wait for callback with auth code
+6. Exchange code for tokens
+7. Return TokenData
+
+Also supports:
+- Token refresh (refresh_token grant)
+- Token revocation (best-effort)
+"""
+
+import asyncio
+import base64
+import hashlib
+import http.server
+import logging
+import os
+import secrets
+import socket
+import sys
+import threading
+import time
+import webbrowser
+from dataclasses import dataclass
+from typing import Optional, Tuple
+from urllib.parse import parse_qs, urlencode, urlparse
+
+import httpx
+
+from src.auth.token_store import TokenData
+
+logger = logging.getLogger(__name__)
+
+# Default callback port for localhost server
+DEFAULT_PORT = 19876
+LOGIN_TIMEOUT = 120  # seconds
+
+
+def generate_pkce() -> Tuple[str, str]:
+    """Generate PKCE code verifier and challenge.
+
+    Returns:
+        Tuple of (verifier, challenge) where:
+        - verifier: 43-128 character random string
+        - challenge: base64url(sha256(verifier))
+    """
+    # Generate 32 random bytes → 43 character base64url string
+    verifier = base64.urlsafe_b64encode(os.urandom(32)).rstrip(b"=").decode("ascii")
+
+    # S256 challenge
+    digest = hashlib.sha256(verifier.encode("ascii")).digest()
+    challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
+
+    return verifier, challenge
+
+
+def generate_state() -> str:
+    """Generate random state parameter for CSRF prevention."""
+    return secrets.token_urlsafe(32)
+
+
+class OAuthFlow:
+    """Manages OAuth2 flows: login, refresh, revoke."""
+
+    def __init__(self, server_url: str, verify_ssl: bool = True):
+        """Initialize OAuth flow.
+
+        Args:
+            server_url: Base URL of the Upscaler API (e.g., https://api.upscaler.com)
+            verify_ssl: If False, skip SSL certificate verification.
+        """
+        self.server_url = server_url.rstrip("/")
+        self.oauth_base = f"{self.server_url}/mcp"
+        self.verify_ssl = verify_ssl
+
+    async def register_client(self) -> Tuple[str, str]:
+        """Register a new OAuth client via Dynamic Client Registration.
+
+        Returns:
+            Tuple of (client_id, client_secret).
+        """
+        url = f"{self.oauth_base}/register"
+        payload = {
+            "client_name": f"upscaler-cli-{secrets.token_hex(4)}",
+            "grant_types": ["authorization_code", "refresh_token"],
+            "response_types": ["code"],
+            "redirect_uris": [f"http://127.0.0.1:{DEFAULT_PORT}/callback"],
+            "token_endpoint_auth_method": "client_secret_post",
+        }
+
+        async with httpx.AsyncClient(verify=self.verify_ssl) as client:
+            response = await client.post(url, json=payload)
+            response.raise_for_status()
+            data = response.json()
+
+        return data["client_id"], data["client_secret"]
+
+    async def login(self, port: int = DEFAULT_PORT) -> TokenData:
+        """Run full OAuth2 PKCE login flow.
+
+        Args:
+            port: Localhost port for callback server.
+
+        Returns:
+            TokenData with access + refresh tokens.
+
+        Raises:
+            RuntimeError: On timeout, port conflict, or auth failure.
+        """
+        # Check port availability
+        if not self._is_port_available(port):
+            raise RuntimeError(
+                f"Login callback port {port} in use. Use --port to specify another."
+            )
+
+        # Register client
+        client_id, client_secret = await self.register_client()
+
+        # Generate PKCE
+        verifier, challenge = generate_pkce()
+        state = generate_state()
+
+        # Start callback server
+        auth_code_holder = {"code": None, "error": None}
+        server = self._start_callback_server(port, state, auth_code_holder)
+
+        try:
+            # Build authorize URL
+            redirect_uri = f"http://127.0.0.1:{port}/callback"
+            params = {
+                "response_type": "code",
+                "client_id": client_id,
+                "redirect_uri": redirect_uri,
+                "state": state,
+                "code_challenge": challenge,
+                "code_challenge_method": "S256",
+                "scope": "mcp:read mcp:write",
+            }
+            authorize_url = f"{self.oauth_base}/authorize?{urlencode(params)}"
+
+            # Open browser
+            if not webbrowser.open(authorize_url):
+                print(
+                    f"Open this URL in your browser: {authorize_url}", file=sys.stderr
+                )
+
+            # Wait for callback
+            deadline = time.time() + LOGIN_TIMEOUT
+            while time.time() < deadline:
+                if auth_code_holder["code"] or auth_code_holder["error"]:
+                    break
+                await asyncio.sleep(0.5)
+
+            if auth_code_holder["error"]:
+                raise RuntimeError(f"Login failed: {auth_code_holder['error']}")
+
+            if not auth_code_holder["code"]:
+                raise RuntimeError("Login timed out. Run upscaler login to try again.")
+
+            # Exchange code for tokens
+            token_data = await self._exchange_code(
+                code=auth_code_holder["code"],
+                verifier=verifier,
+                redirect_uri=redirect_uri,
+                client_id=client_id,
+                client_secret=client_secret,
+            )
+
+            return token_data
+
+        finally:
+            server.shutdown()
+
+    async def refresh(self, token_data: TokenData) -> TokenData:
+        """Exchange refresh token for new access + refresh tokens.
+
+        Args:
+            token_data: Current token data with refresh_token.
+
+        Returns:
+            Updated TokenData with new tokens.
+
+        Raises:
+            RuntimeError: If refresh fails (session expired).
+        """
+        payload = {
+            "grant_type": "refresh_token",
+            "refresh_token": token_data.refresh_token,
+            "client_id": token_data.client_id,
+            "client_secret": token_data.client_secret,
+        }
+
+        async with httpx.AsyncClient(verify=self.verify_ssl) as client:
+            response = await client.post(token_data.token_endpoint, data=payload)
+
+        if response.status_code != 200:
+            raise RuntimeError("Session expired. Run: upscaler login")
+
+        data = response.json()
+        return TokenData(
+            access_token=data["access_token"],
+            refresh_token=data.get("refresh_token", token_data.refresh_token),
+            expires_at=time.time() + data.get("expires_in", 86400),
+            client_id=token_data.client_id,
+            client_secret=token_data.client_secret,
+            organization_id=token_data.organization_id,
+            token_endpoint=token_data.token_endpoint,
+        )
+
+    async def revoke(self, token_data: TokenData) -> None:
+        """Revoke tokens (best-effort — does not raise on failure)."""
+        url = f"{self.oauth_base}/revoke"
+        payload = {
+            "token": token_data.access_token,
+            "client_id": token_data.client_id,
+            "client_secret": token_data.client_secret,
+        }
+
+        try:
+            async with httpx.AsyncClient(timeout=5.0, verify=self.verify_ssl) as client:
+                await client.post(url, data=payload)
+        except Exception as e:
+            logger.debug(f"Token revocation failed (best-effort): {e}")
+
+    async def _exchange_code(
+        self,
+        code: str,
+        verifier: str,
+        redirect_uri: str,
+        client_id: str,
+        client_secret: str,
+    ) -> TokenData:
+        """Exchange authorization code for tokens."""
+        token_url = f"{self.oauth_base}/token"
+        payload = {
+            "grant_type": "authorization_code",
+            "code": code,
+            "redirect_uri": redirect_uri,
+            "code_verifier": verifier,
+            "client_id": client_id,
+            "client_secret": client_secret,
+        }
+
+        async with httpx.AsyncClient(verify=self.verify_ssl) as client:
+            response = await client.post(token_url, data=payload)
+
+        if response.status_code != 200:
+            raise RuntimeError(
+                f"Token exchange failed ({response.status_code}). Run: upscaler login"
+            )
+
+        data = response.json()
+        return TokenData(
+            access_token=data["access_token"],
+            refresh_token=data["refresh_token"],
+            expires_at=time.time() + data.get("expires_in", 86400),
+            client_id=client_id,
+            client_secret=client_secret,
+            organization_id=data.get("organization_id"),
+            token_endpoint=token_url,
+        )
+
+    def _is_port_available(self, port: int) -> bool:
+        """Check if a port is available for binding."""
+        try:
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                s.bind(("127.0.0.1", port))
+                return True
+        except OSError:
+            return False
+
+    def _start_callback_server(
+        self, port: int, expected_state: str, result_holder: dict
+    ) -> http.server.HTTPServer:
+        """Start a localhost HTTP server to receive the OAuth callback."""
+
+        class CallbackHandler(http.server.BaseHTTPRequestHandler):
+            def do_GET(self):
+                parsed = urlparse(self.path)
+
+                # Ignore non-callback requests (favicon, prefetch, etc.)
+                if not parsed.path.rstrip("/").endswith("/callback"):
+                    self.send_response(204)
+                    self.end_headers()
+                    return
+
+                params = parse_qs(parsed.query)
+
+                state = params.get("state", [None])[0]
+                code = params.get("code", [None])[0]
+                error = params.get("error", [None])[0]
+
+                if error:
+                    result_holder["error"] = error
+                    self.send_response(200)
+                    self.end_headers()
+                    self.wfile.write(b"Login failed. You can close this tab.")
+                    return
+
+                if state != expected_state:
+                    result_holder["error"] = "State mismatch — possible CSRF attack"
+                    self.send_response(400)
+                    self.end_headers()
+                    self.wfile.write(b"State mismatch. Login cancelled.")
+                    return
+
+                if code:
+                    result_holder["code"] = code
+                    self.send_response(200)
+                    self.end_headers()
+                    self.wfile.write(b"Login successful! You can close this tab.")
+
+            def log_message(self, format, *args):
+                pass  # Suppress server logs
+
+        server = http.server.HTTPServer(("127.0.0.1", port), CallbackHandler)
+        thread = threading.Thread(target=server.serve_forever, daemon=True)
+        thread.start()
+        return server