ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
feat(connect): pair the panel with ServerKit Cloud from the CLI
Juan Denis0a654e0f5fbe
diff --git a/backend/app/api/connect.py b/backend/app/api/connect.pynew file mode 100644index 00000000..95de0602--- /dev/null+++ b/backend/app/api/connect.py@@ -0,0 +1,19 @@+"""Connect API — expose this panel's ServerKit Cloud connection state.++Pairing itself happens via `serverkit connect` on the host (see+app/services/connect_client.py); this read-only endpoint lets the Settings+UI render the connection state.+"""+from flask import Blueprint, jsonify+from flask_jwt_extended import jwt_required++from app.services import connect_client++connect_bp = Blueprint('connect', __name__)+++@connect_bp.route('/status', methods=['GET'])+@jwt_required()+def get_status():+ """Current ServerKit Cloud connection state (unpaired/paired_offline/...)."""+ return jsonify(connect_client.status())diff --git a/backend/app/core_blueprints.py b/backend/app/core_blueprints.pyindex 0dbf9b6a..73cdef21 100644--- a/backend/app/core_blueprints.py+++ b/backend/app/core_blueprints.py@@ -263,6 +263,7 @@ CORE_BLUEPRINTS: tuple[BlueprintSpec, ...] = (name='obs_fleet',),BlueprintSpec('app.api.pairing', 'pairing_bp', '/api/v1/pairing'),+ BlueprintSpec('app.api.connect', 'connect_bp', '/api/v1/connect'),BlueprintSpec('app.api.ai', 'ai_bp', '/api/v1/ai'),BlueprintSpec('app.api.speed_test', 'speedtest_bp', '/api/v1/speedtest'),BlueprintSpec('app.api.site_imports', 'site_imports_bp', '/api/v1/imports'),diff --git a/backend/app/services/connect_client.py b/backend/app/services/connect_client.pynew file mode 100644index 00000000..22d16e06--- /dev/null+++ b/backend/app/services/connect_client.py@@ -0,0 +1,350 @@+"""ServerKit Cloud connect pairing — panel side.++M1 scope is pairing ONLY: enroll with ServerKit Cloud, print the pairing code ++fingerprint, poll with an Ed25519 proof-of-possession until the user approves+in the browser, then write ``connect.json`` next to the panel config. No+WebSocket transport, no reconnect loop — those are later milestones.++ServerKit Cloud endpoints (no session auth on the panel side):+ POST /api/pair/enroll -> enrollment_id, enrollment_secret (shown once), code+ POST /api/pair/poll -> 202 pending / 200 claimed (signed proof-of-possession)+ POST /api/pair/rotate -> new code + expires_at++The enrollment_secret is kept in memory for the pairing session only — it is+never written to disk or logged.+"""+import json+import logging+import os+import socket+import time+from datetime import datetime, timezone++import requests++from app import paths+from app.services import connect_keys++logger = logging.getLogger(__name__)++DEFAULT_CLOUD_URL = 'https://app.serverkit.ai'+CONNECT_FILENAME = 'connect.json'+KEY_PATH_FIELD = 'key_path'++# Connection state enum — the same names ServerKit Cloud uses on the Device row.+STATES = ('unpaired', 'pairing', 'paired_offline', 'online', 'degraded', 'revoked')++HTTP_TIMEOUT_S = 20+DEFAULT_PAIR_TIMEOUT_S = 15 * 60 # generous: the user may walk away to log in+POLL_INTERVAL_S = 3.0+++class ConnectError(Exception):+ """Pairing failed in a way worth showing the operator verbatim."""+++# ==================== Paths / config ====================+++def resolve_cloud_url(cli_url: str = None) -> str:+ """--cloud flag > SERVERKIT_CLOUD_URL env var > DEFAULT_CLOUD_URL."""+ url = (cli_url or os.environ.get('SERVERKIT_CLOUD_URL') or DEFAULT_CLOUD_URL)+ url = url.strip().rstrip('/')+ if not url.startswith(('http://', 'https://')):+ raise ConnectError(f'ServerKit Cloud URL must start with http:// or https:// (got {url!r})')+ return url+++def connect_file_path() -> str:+ return os.path.join(paths.SERVERKIT_CONFIG_DIR, CONNECT_FILENAME)+++def _read_connect_file() -> dict:+ path = connect_file_path()+ if not os.path.exists(path):+ return {}+ try:+ with open(path, 'r', encoding='utf-8') as f:+ data = json.load(f)+ return data if isinstance(data, dict) else {}+ except (OSError, ValueError) as exc:+ logger.warning('Could not read %s: %s', path, exc)+ return {}+++def _write_connect_file(payload: dict):+ path = connect_file_path()+ os.makedirs(os.path.dirname(path), exist_ok=True)+ with open(path, 'w', encoding='utf-8') as f:+ json.dump(payload, f, indent=2)+ f.write('\n')+ if os.name != 'nt':+ os.chmod(path, 0o600)+++# ==================== Facts ====================+++def _panel_machine_id(fallback: str) -> str:+ """Stable id for this panel host: /etc/machine-id, else the device fingerprint."""+ for candidate in ('/etc/machine-id', '/var/lib/dbus/machine-id'):+ try:+ with open(candidate, 'r', encoding='utf-8') as f:+ value = f.read().strip()+ if value:+ return value+ except OSError:+ continue+ return fallback+++def _gather_hosts() -> list:+ """One host entry (kind 'agent') per agent-backed Server this panel manages.++ Server rows carry no machine_id/fingerprint for their agents, so only+ agent_id and hostname are reported. Without a Flask app context (or with+ the DB down) the honest answer is an empty list.+ """+ try:+ from flask import has_app_context+ if not has_app_context():+ return []+ from app.models.server import Server+ servers = (+ Server.query+ .filter(Server.agent_id.isnot(None))+ .with_entities(Server.agent_id, Server.hostname, Server.name)+ .all()+ )+ return [+ {+ 'agent_id': s.agent_id,+ 'machine_id': None,+ 'fingerprint': None,+ 'hostname': s.hostname or s.name,+ 'kind': 'agent',+ }+ for s in servers+ ]+ except Exception as exc: # never block pairing on host enumeration+ logger.warning('Could not enumerate managed agents: %s', exc)+ return []+++# ==================== Pairing ====================+++def _post(cloud_url: str, endpoint: str, body: dict) -> requests.Response:+ return requests.post(+ f'{cloud_url}/api/pair/{endpoint}',+ json=body,+ timeout=HTTP_TIMEOUT_S,+ )+++def _error_detail(resp: requests.Response) -> str:+ try:+ detail = resp.json().get('detail')+ except ValueError:+ detail = None+ if isinstance(detail, dict):+ detail = detail.get('error')+ return detail or resp.text[:200] or f'HTTP {resp.status_code}'+++def _print_code(echo, code: str, fingerprint: str, cloud_url: str, expires_at: str):+ echo('')+ echo(f' Pairing code: {code}')+ echo(f' Fingerprint: {connect_keys.format_fingerprint(fingerprint)}')+ echo('')+ echo(f' Approve this server at {cloud_url}/pair — enter the code and')+ echo(' confirm the fingerprint matches exactly.')+ echo(f' Code expires at {expires_at}; a new one is printed automatically.')+ echo('')+++def connect(cloud_url: str = None, echo=print, timeout_s: int = DEFAULT_PAIR_TIMEOUT_S,+ poll_interval: float = POLL_INTERVAL_S) -> dict:+ """Pair this panel with ServerKit Cloud. Returns the written connect.json payload.++ Blocks (polling every ~3 s) until the enrollment is claimed, the overall+ timeout elapses, or ServerKit Cloud rejects the enrollment. Ctrl+C is handled by the+ caller (KeyboardInterrupt).+ """+ cloud_url = resolve_cloud_url(cloud_url)++ existing = _read_connect_file()+ if existing.get('device_id'):+ raise ConnectError(+ f'This panel is already connected to {existing.get("org_slug") or "an organization"} '+ f'as "{existing.get("name")}". Run `serverkit connect status` for details or '+ '`serverkit connect disconnect` first.'+ )++ private_key, pubkey_hex, fingerprint = connect_keys.load_or_create_keypair()++ from app.utils.version import get_panel_version+ body = {+ 'pubkey': pubkey_hex,+ 'fingerprint': fingerprint,+ 'hostname': socket.gethostname(),+ 'panel_version': get_panel_version(),+ 'proto': 1,+ 'machine_id': _panel_machine_id(fingerprint),+ 'hosts': _gather_hosts(),+ }++ try:+ resp = _post(cloud_url, 'enroll', body)+ except requests.RequestException as exc:+ raise ConnectError(f'Cannot reach ServerKit Cloud at {cloud_url}: {exc}')+ if resp.status_code == 409:+ raise ConnectError(f'ServerKit Cloud refused enrollment: {_error_detail(resp)}')+ if resp.status_code != 201:+ raise ConnectError(f'Enroll failed ({resp.status_code}): {_error_detail(resp)}')++ enrolled = resp.json()+ enrollment_id = enrolled['enrollment_id']+ enrollment_secret = enrolled['enrollment_secret'] # session-only; never stored+ code = enrolled['code']+ expires_at = enrolled.get('expires_at')++ echo(f'Connecting this panel to ServerKit Cloud ({cloud_url}) ...')+ _print_code(echo, code, fingerprint, cloud_url, expires_at)++ deadline = time.monotonic() + timeout_s+ last_warning = 0.0+ while time.monotonic() < deadline:+ if expires_at and _past(expires_at):+ try:+ rot = _post(cloud_url, 'rotate', {+ 'enrollment_id': enrollment_id,+ 'enrollment_secret': enrollment_secret,+ })+ if rot.status_code == 200:+ data = rot.json()+ code, expires_at = data['code'], data.get('expires_at')+ echo('The previous code expired; here is a new one.')+ _print_code(echo, code, fingerprint, cloud_url, expires_at)+ elif rot.status_code != 423: # 423 = frozen: someone is typing it — keep it+ logger.warning('Code rotation failed (%s): %s',+ rot.status_code, _error_detail(rot))+ expires_at = None # avoid hammering; poll until claimed/timeout+ except requests.RequestException:+ pass++ ts = int(time.time())+ sig = private_key.sign(f'{enrollment_id}|{ts}'.encode()).hex()+ try:+ poll = _post(cloud_url, 'poll', {+ 'enrollment_id': enrollment_id,+ 'enrollment_secret': enrollment_secret,+ 'ts': ts,+ 'sig': sig,+ })+ except requests.RequestException as exc:+ now = time.monotonic()+ if now - last_warning > 15:+ last_warning = now+ echo(f' ... waiting (ServerKit Cloud unreachable: {exc}); will retry')+ time.sleep(poll_interval)+ continue++ if poll.status_code == 200:+ claimed = poll.json()+ payload = {+ 'device_id': claimed.get('device_id'),+ 'org_slug': claimed.get('org_slug'),+ 'name': claimed.get('name'),+ 'relay_url': claimed.get('relay_url'),+ 'scopes': claimed.get('scopes') or [],+ 'fingerprint': fingerprint,+ KEY_PATH_FIELD: connect_keys.default_key_path(),+ 'cloud_url': cloud_url,+ 'paired_at': datetime.now(timezone.utc).isoformat(),+ }+ _write_connect_file(payload)+ echo('')+ echo(f'Connected to organization "{payload["org_slug"]}" '+ f'as "{payload["name"]}".')+ echo(f'State saved to {connect_file_path()}')+ return payload++ if poll.status_code == 202:+ time.sleep(poll_interval)+ continue+ if poll.status_code == 423:+ raise ConnectError(f'Enrollment locked by ServerKit Cloud: {_error_detail(poll)}')+ if poll.status_code in (400, 401):+ raise ConnectError(f'ServerKit Cloud rejected this enrollment: {_error_detail(poll)}')+ logger.warning('Unexpected poll response %s: %s',+ poll.status_code, _error_detail(poll))+ time.sleep(poll_interval)++ raise ConnectError(+ f'Pairing timed out after {timeout_s // 60} minutes. '+ 'Run `serverkit connect` again to start a new enrollment.'+ )+++def _past(iso_ts: str) -> bool:+ try:+ dt = datetime.fromisoformat(str(iso_ts))+ except ValueError:+ return False+ if dt.tzinfo is None:+ dt = dt.replace(tzinfo=timezone.utc)+ return datetime.now(timezone.utc) >= dt+++# ==================== Status / disconnect ====================+++def status() -> dict:+ """Connection state as the UI/CLI should show it (reads connect.json + key)."""+ data = _read_connect_file()+ key_path = data.get(KEY_PATH_FIELD) or connect_keys.default_key_path()+ key_present = os.path.exists(key_path)+ if not data.get('device_id'):+ return {+ 'state': 'unpaired',+ 'state_reason': None,+ 'paired': False,+ 'cloud_url': resolve_cloud_url(),+ 'key_present': key_present,+ 'key_path': key_path,+ }+ state = 'paired_offline' if key_present else 'degraded'+ return {+ 'state': state,+ # No transport yet in M1 — a paired panel has never been online.+ 'state_reason': 'never_connected' if key_present else 'device_key_missing',+ 'paired': True,+ 'cloud_url': data.get('cloud_url') or resolve_cloud_url(),+ 'device_id': data.get('device_id'),+ 'org_slug': data.get('org_slug'),+ 'name': data.get('name'),+ 'relay_url': data.get('relay_url'),+ 'scopes': data.get('scopes') or [],+ 'fingerprint': data.get('fingerprint'),+ 'fingerprint_grouped': connect_keys.format_fingerprint(data['fingerprint'])+ if data.get('fingerprint') else None,+ 'paired_at': data.get('paired_at'),+ 'key_present': key_present,+ 'key_path': key_path,+ }+++def disconnect(remove_key: bool = False) -> dict:+ """Forget the pairing locally. Does NOT revoke anything on ServerKit Cloud."""+ removed = []+ path = connect_file_path()+ if os.path.exists(path):+ os.unlink(path)+ removed.append(path)+ if remove_key:+ key_path = connect_keys.default_key_path()+ if os.path.exists(key_path):+ os.unlink(key_path)+ removed.append(key_path)+ return {'success': True, 'removed': removed, 'state': 'unpaired'}diff --git a/backend/app/services/connect_keys.py b/backend/app/services/connect_keys.pynew file mode 100644index 00000000..9b7b3388--- /dev/null+++ b/backend/app/services/connect_keys.py@@ -0,0 +1,84 @@+"""Device keypair for ServerKit Cloud connect pairing.++The panel holds one Ed25519 keypair that identifies it as a device to the+ServerKit Cloud control plane. The private key lives next to the panel config+(``paths.SERVERKIT_CONFIG_DIR``) with mode 0600, mirroring how the agent+stores its pairing key (``/etc/serverkit-agent/pairing.key``).++Fingerprint contract (verified server-side by ServerKit Cloud): the first 16 hex chars+of sha256 over the RAW 32-byte public key, displayed in groups of four+(``a1b2 c3d4 e5f6 7890``).+"""+import hashlib+import logging+import os++from cryptography.hazmat.primitives import serialization+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey++from app import paths++logger = logging.getLogger(__name__)++KEY_FILENAME = 'connect_device_key.pem'+++def default_key_path() -> str:+ return os.path.join(paths.SERVERKIT_CONFIG_DIR, KEY_FILENAME)+++def fingerprint_of(pubkey_bytes: bytes) -> str:+ """First 16 hex chars of sha256(raw pubkey bytes) — ServerKit Cloud's contract."""+ return hashlib.sha256(pubkey_bytes).hexdigest()[:16]+++def format_fingerprint(fingerprint: str) -> str:+ """``a1b2c3d4e5f67890`` -> ``a1b2 c3d4 e5f6 7890`` (the agent's format)."""+ return ' '.join(fingerprint[i:i + 4] for i in range(0, len(fingerprint), 4))+++def _public_bytes(private_key: Ed25519PrivateKey) -> bytes:+ return private_key.public_key().public_bytes(+ serialization.Encoding.Raw, serialization.PublicFormat.Raw,+ )+++def load_or_create_keypair(path: str = None):+ """Load the device keypair from ``path``, generating + persisting one if absent.++ Returns (private_key, pubkey_hex, fingerprint). The file is written with+ mode 0600; on POSIX an existing file with looser permissions is tightened.+ """+ path = path or default_key_path()+ if os.path.exists(path):+ with open(path, 'rb') as f:+ private_key = serialization.load_pem_private_key(f.read(), password=None)+ if not isinstance(private_key, Ed25519PrivateKey):+ raise ValueError(f'{path} is not an Ed25519 private key')+ if os.name != 'nt':+ os.chmod(path, 0o600)+ else:+ private_key = Ed25519PrivateKey.generate()+ os.makedirs(os.path.dirname(path), exist_ok=True)+ pem = private_key.private_bytes(+ serialization.Encoding.PEM,+ serialization.PrivateFormat.PKCS8,+ serialization.NoEncryption(),+ )+ # O_EXCL so a lost race regenerates instead of clobbering a live key.+ fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)+ try:+ with os.fdopen(fd, 'wb') as f:+ f.write(pem)+ except Exception:+ try:+ os.unlink(path)+ except OSError:+ pass+ raise+ if os.name != 'nt':+ os.chmod(path, 0o600)+ logger.info('Generated ServerKit Cloud device key at %s', path)++ pubkey_bytes = _public_bytes(private_key)+ return private_key, pubkey_bytes.hex(), fingerprint_of(pubkey_bytes)diff --git a/backend/cli.py b/backend/cli.pyindex eae2db9d..b4561b1e 100644--- a/backend/cli.py+++ b/backend/cli.py@@ -6,6 +6,7 @@ import clickimport jsonimport secretsimport sys+import contextlibfrom pathlib import Path# Load .env file before importing app@@ -1531,5 +1532,132 @@ def _prompt_disk_selection(usable):click.echo(click.style('Nothing selected — pick at least one number.', fg='yellow'))+# ── connect (ServerKit Cloud pairing) ─────────────────────────────────────────+[email protected](invoke_without_command=True)[email protected]('--cloud', 'cloud_url', default=None,+ help='ServerKit Cloud control-plane URL (default: SERVERKIT_CLOUD_URL env var '+ 'or https://app.serverkit.ai)')[email protected]('--json', 'as_json', is_flag=True, help='Output machine-readable JSON')[email protected]_context+def connect(ctx, cloud_url, as_json):+ """Pair this panel with ServerKit Cloud.++ Prints a pairing code and this panel's fingerprint, then waits for the+ enrollment to be approved in the browser.+ """+ if ctx.invoked_subcommand is not None:+ return++ from app.services import connect_client+ from app.services.connect_client import ConnectError++ already = connect_client.status()+ if already.get('paired'):+ if as_json:+ _echo_json(already)+ return+ click.echo(f'This panel is already connected to organization '+ f'"{already.get("org_slug")}" as "{already.get("name")}" '+ f'({already.get("cloud_url")}).')+ click.echo(f'Fingerprint: {already.get("fingerprint_grouped")}')+ click.echo('Run `serverkit connect status` for details, or '+ '`serverkit connect disconnect` before re-pairing.')+ return++ # The app context is only needed to enumerate managed agents from the DB.+ # Pairing itself is DB-independent, so a broken local DB must not block it.+ try:+ app = create_app()+ app_context = app.app_context()+ except Exception as exc:+ click.echo(click.style(+ f'Warning: panel database unavailable ({exc}); '+ 'reporting no managed agents to ServerKit Cloud.', fg='yellow'), err=True)+ app_context = contextlib.nullcontext()++ try:+ with app_context:+ result = connect_client.connect(cloud_url=cloud_url, echo=click.echo)+ except ConnectError as exc:+ _fail(str(exc))+ except KeyboardInterrupt:+ click.echo()+ _fail('Pairing aborted — nothing was saved. '+ 'Run `serverkit connect` to start over.')++ if as_json:+ _echo_json(result)++[email protected]('status')[email protected]('--json', 'as_json', is_flag=True, help='Output machine-readable JSON')+def connect_status(as_json):+ """Show this panel's ServerKit Cloud connection state."""+ from app.services import connect_client++ state = connect_client.status()+ if as_json:+ _echo_json(state)+ return++ if not state.get('paired'):+ click.echo('Not connected to ServerKit Cloud. '+ 'Run `serverkit connect` to pair this panel.')+ return++ rows = [+ ('State', state.get('state')),+ ('Reason', state.get('state_reason') or '-'),+ ('ServerKit Cloud', state.get('cloud_url')),+ ('Organization', state.get('org_slug') or '-'),+ ('Name', state.get('name') or '-'),+ ('Fingerprint', state.get('fingerprint_grouped') or '-'),+ ('Relay', state.get('relay_url') or '-'),+ ('Scopes', ', '.join(state.get('scopes') or []) or '-'),+ ('Paired at', state.get('paired_at') or '-'),+ ('Device key', state.get('key_path')+ + ('' if state.get('key_present') else ' (MISSING)')),+ ]+ _echo_table(['Field', 'Value'], rows)++[email protected]('disconnect')[email protected]('--remove-key', is_flag=True,+ help='Also delete the device keypair (a new identity on next pair)')[email protected]('--yes', is_flag=True, help='Skip the confirmation prompt')[email protected]('--json', 'as_json', is_flag=True, help='Output machine-readable JSON')+def connect_disconnect(remove_key, yes, as_json):+ """Forget the ServerKit Cloud pairing on this panel.++ Local only — to revoke the device for everyone, remove it in the ServerKit Cloud UI.+ """+ from app.services import connect_client++ state = connect_client.status()+ if not state.get('paired'):+ if as_json:+ _echo_json({'success': True, 'state': 'unpaired', 'removed': []})+ return+ click.echo('This panel is not connected to ServerKit Cloud.')+ return++ if not yes and not as_json:+ click.echo(f'This will forget the pairing with organization '+ f'"{state.get("org_slug")}" on this panel. '+ 'The device stays registered on ServerKit Cloud until revoked there.')+ if not click.confirm('Disconnect?', default=False):+ click.echo('Aborted.')+ return++ result = connect_client.disconnect(remove_key=remove_key)+ if as_json:+ _echo_json(result)+ return+ for path in result['removed']:+ click.echo(f'Removed {path}')+ click.echo(click.style('Disconnected from ServerKit Cloud.', fg='green'))++if __name__ == '__main__':cli()diff --git a/backend/tests/test_core_blueprint_registry.py b/backend/tests/test_core_blueprint_registry.pyindex 56180eae..bd854123 100644--- a/backend/tests/test_core_blueprint_registry.py+++ b/backend/tests/test_core_blueprint_registry.py@@ -7,9 +7,9 @@ from pathlib import Pathfrom app.core_blueprints import CORE_BLUEPRINTS-EXPECTED_CORE_BLUEPRINT_COUNT = 112+EXPECTED_CORE_BLUEPRINT_COUNT = 113EXPECTED_MANIFEST_SHA256 = (- 'e0eb77cea08ddc21c49d00c25381371dc11b941c4a483ee1532739b4e6ad5013'+ '55cd5d9a732e1ed2301774ef4462e1424dea408ae4e192a1e177688570bf95d4')