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(extensions): deliver runtime ESM frontends to production panels (#39)
Juan Denisffc1fd772813
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 3d8d1e40..d6df82e3 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -20,6 +20,13 @@ awaiting a stable release:### Added+- **Extensions render on a production panel without a rebuild.** An extension that+ ships a prebuilt ESM bundle (`frontend_entry: "dist/index.mjs"`) now lights up its+ UI the moment it's installed — the panel fetches the bundle through the authed+ assets route, verifies its integrity against the hash pinned at install, and loads+ it live. Previously an installed extension's backend worked but its pages stayed+ invisible until the whole panel was rebuilt. A panel-wide kill switch+ (`extensions.runtime_frontend`, on by default) can turn the mechanism off.- **The Deploy Console — publish anything, watch it live, debug it from the UI.**Installing a template, deploying a repo, redeploying a service, or uploading abuild now takes you to one full-page live console at `/deployments/<id>`: adiff --git a/ROADMAP.md b/ROADMAP.mdindex 5e22526b..25720e9c 100644--- a/ROADMAP.md+++ b/ROADMAP.md@@ -12,7 +12,7 @@ This document outlines the development roadmap for ServerKit. Features are organ- **Deploy Console & Live Run Logs** - Every install and deploy lands on one full-page live console: streaming build output, a step timeline with per-step durations and a live elapsed timer, and failure cards showing the real error tail with plain-language hints and one-click retry. Backed by a unified batched run-log layer (database persistence + WebSocket push with a polling fallback).- **New Service Wizard & Template Catalog** - Three-step service creation (Source / Connect / Review) backed by a server-side template catalog with one-click compose templates and Git-repo templates.-- **Extensions Platform Maturation** - Marketplace registry backed by standalone extension repos (Kubernetes, Automations, Analytics, Mail, GPU, CrowdSec, DNS server, and more), with built-in features progressively extracted to keep the default panel lean.+- **Extensions Platform Maturation** - Marketplace registry backed by standalone extension repos (Kubernetes, Automations, Analytics, Mail, GPU, CrowdSec, DNS server, and more), with built-in features progressively extracted to keep the default panel lean. Installed extensions that ship a prebuilt bundle now render their UI on a production panel with no rebuild.- **Privacy-First Web Analytics** - Cookieless, self-hosted analytics extension with WordPress and nginx integration and optional geo lookup.- **Agent Fleet & Peering** - ServerKit-to-ServerKit peering (embedded agent mode), fleet doctor tooling, and agent capability upgrades.- **Auth & Proxy Hardening** - Trusted reverse-proxy client-IP handling and per-IP login brute-force throttling.@@ -605,7 +605,7 @@ happen live, and debug failures entirely from the UI.## Extension Platform-- [ ] Runtime frontend loading — installed extensions render without rebuilding the panel+- [x] Runtime frontend loading — installed extensions render without rebuilding the panel- [ ] Signed extension releases, with explicit install consent for unsigned or third-party code- [ ] Remaining built-ins extracted to standalone repos (including the WordPress flagship)- [ ] Security suite (Fail2ban, ClamAV, Lynis, auto-updates, image scanning) as installable extensions for a leaner default paneldiff --git a/backend/app/api/plugins.py b/backend/app/api/plugins.pyindex 6587b6d6..229246ba 100644--- a/backend/app/api/plugins.py+++ b/backend/app/api/plugins.py@@ -531,12 +531,18 @@ def get_plugin_config(plugin_id):if not user or not user.is_admin:return jsonify({'error': 'Admin access required'}), 403- from app.services.plugin_service import get_plugin+ from app.services.plugin_service import get_plugin, RESERVED_PLUGIN_CONFIG_KEYSplugin = get_plugin(plugin_id)if not plugin:return jsonify({'error': 'Plugin not found'}), 404+ # Hide panel-managed reserved keys (e.g. _frontend_hashes) — they're not+ # user config and must not be echoed back for editing.+ user_config = {+ k: v for k, v in (plugin.config or {}).items()+ if k not in RESERVED_PLUGIN_CONFIG_KEYS+ }return jsonify({- 'config': plugin.config,+ 'config': user_config,'config_schema': (plugin.manifest or {}).get('config_schema') or {},})@@ -554,8 +560,10 @@ def update_plugin_config(plugin_id):if not user or not user.is_admin:return jsonify({'error': 'Admin access required'}), 403- from app import db- from app.services.plugin_service import get_plugin+ from app.services.plugin_service import (+ get_plugin, update_plugin_config as svc_update_plugin_config,+ RESERVED_PLUGIN_CONFIG_KEYS,+ )plugin = get_plugin(plugin_id)if not plugin:return jsonify({'error': 'Plugin not found'}), 404@@ -565,8 +573,9 @@ def update_plugin_config(plugin_id):if not isinstance(config, dict):return jsonify({'error': 'config must be an object'}), 400- plugin.config = config- db.session.commit()+ # The service strips/re-applies panel-managed reserved keys (e.g. the+ # runtime-frontend integrity pins), so a config PUT can't drop or forge them.+ plugin = svc_update_plugin_config(plugin.slug, config)AuditService.log(action=AuditLog.ACTION_RESOURCE_UPDATE,user_id=user.id,@@ -574,7 +583,11 @@ def update_plugin_config(plugin_id):target_id=str(plugin.id),details={'event': 'config_update', 'keys': sorted(config.keys())},)- return jsonify({'config': plugin.config})+ user_config = {+ k: v for k, v in (plugin.config or {}).items()+ if k not in RESERVED_PLUGIN_CONFIG_KEYS+ }+ return jsonify({'config': user_config})@plugins_bp.route('/updates', methods=['GET'])diff --git a/backend/app/services/contribution_service.py b/backend/app/services/contribution_service.pyindex 8591ae61..a10a241d 100644--- a/backend/app/services/contribution_service.py+++ b/backend/app/services/contribution_service.py@@ -37,6 +37,45 @@ Only plugins with status == 'active' contribute. A plugin without acontributions block is silently skipped."""from app.models.plugin import InstalledPlugin+from app.utils.sdk import SDK_VERSION+++# Panel-managed plugin-config key holding the per-bundle sha256 hashes recorded+# for a runtime-frontend extension at install time (see plugin_service).+RUNTIME_FRONTEND_HASH_KEY = '_frontend_hashes'+++def _runtime_frontends(plugins):+ """Descriptor map for extensions delivered as a prebuilt ESM bundle.++ Shape: ``{ slug: { entry, hashes: {entry: sha256}, sdk_version } }``. The+ client runtime loader (frontend/src/plugins/runtime/loader.js) fetches each+ bundle through the JWT-authed assets route, verifies its sha256 against the+ hash recorded here at install time, then blob-imports it — resolving the+ externalized react/router/sdk specifiers through the host import map.++ Only extensions whose manifest ``frontend_entry`` is an ESM bundle (``.mjs``)+ appear here; baked ``.jsx`` builtins render via the build-time glob, not the+ runtime loader. Gated by the ``extensions.runtime_frontend`` kill switch+ (Decision 4) — off means an empty map and the loader is inert.+ """+ from app.services.settings_service import SettingsService+ if not SettingsService.get('extensions.runtime_frontend', True):+ return {}++ out = {}+ for p in plugins:+ manifest = p.manifest or {}+ entry = (manifest.get('frontend_entry') or '').strip()+ if not entry.endswith('.mjs'):+ continue+ hashes = (p.config or {}).get(RUNTIME_FRONTEND_HASH_KEY) or {}+ out[p.slug] = {+ 'entry': entry,+ 'hashes': hashes,+ 'sdk_version': manifest.get('sdk_version') or '',+ }+ return outdef _tag(items, slug):@@ -98,4 +137,8 @@ def get_active_contributions():'layouts': layouts,'tabs': tabs,'ai': ai,+ # Panel SDK version the client uses to gate runtime bundles (plan 25 #1).+ 'sdk_version': SDK_VERSION,+ # Runtime-loadable ESM frontends (plan 25 Phase 2, core-slim #39).+ 'frontends': _runtime_frontends(plugins),}diff --git a/backend/app/services/plugin_service.py b/backend/app/services/plugin_service.pyindex f08b1224..76d8f0f3 100644--- a/backend/app/services/plugin_service.py+++ b/backend/app/services/plugin_service.py@@ -889,6 +889,11 @@ def _install_from_buffer(buf, source_url, source_type, user_id=None, force=Falseplugin.entry_point = entry_pointplugin.url_prefix = url_prefixplugin.frontend_entry = manifest.get('frontend_entry', '')+ # Runtime-frontend integrity (plan 25 #6, core-slim #39): pin the sha256+ # of the prebuilt ESM bundle so the client loader can verify the bytes it+ # blob-imports match what was installed. No-op for baked .jsx builtins.+ if has_frontend:+ _record_frontend_hashes(plugin, manifest, frontend_dest)plugin.status = InstalledPlugin.STATUS_ACTIVEdb.session.commit()@@ -1527,6 +1532,62 @@ def get_plugin_by_slug(slug):return InstalledPlugin.query.filter_by(slug=slug).first()+# Plugin-config keys the panel owns — never user-editable, preserved across a+# config PUT. The runtime-frontend loader's per-bundle sha256 hashes live here.+RESERVED_PLUGIN_CONFIG_KEYS = ('_frontend_hashes',)+++def _record_frontend_hashes(plugin, manifest, frontend_dest):+ """Pin the sha256 of a runtime-frontend ESM bundle at install time.++ Stored on the plugin's config under the panel-managed ``_frontend_hashes``+ key (a reserved namespace preserved across config edits). Only ESM bundles+ (manifest ``frontend_entry`` ending ``.mjs``) are hashed — baked ``.jsx``+ builtins load via the build-time glob and need no integrity pin. Best+ effort: a missing bundle file just records nothing (the loader then refuses+ to import an extension with no recorded hash).+ """+ entry = (manifest.get('frontend_entry') or '').strip()+ if not entry.endswith('.mjs'):+ return+ bundle_path = os.path.join(frontend_dest, entry)+ if not os.path.isfile(bundle_path):+ return+ import hashlib+ with open(bundle_path, 'rb') as f:+ digest = hashlib.sha256(f.read()).hexdigest()+ cfg = dict(plugin.config or {})+ hashes = dict(cfg.get('_frontend_hashes') or {})+ hashes[entry] = digest+ cfg['_frontend_hashes'] = hashes+ plugin.config = cfg+++def update_plugin_config(slug, config):+ """Save a plugin's user config, preserving panel-managed reserved keys.++ A config PUT from the Marketplace replaces the user-visible values but must+ never drop (or let the caller forge) the panel-managed ``_frontend_hashes``+ integrity pins. Reserved keys are stripped from the incoming payload and the+ existing values are re-applied on top.+ """+ plugin = get_plugin_by_slug(slug)+ if not plugin:+ raise ValueError('Plugin not found')++ existing = plugin.config or {}+ new_cfg = {+ k: v for k, v in (config or {}).items()+ if k not in RESERVED_PLUGIN_CONFIG_KEYS+ }+ for key in RESERVED_PLUGIN_CONFIG_KEYS:+ if key in existing:+ new_cfg[key] = existing[key]+ plugin.config = new_cfg+ db.session.commit()+ return plugin++def list_builtin_extensions():"""Enumerate folders in BUILTIN_EXTENSIONS_DIR that look like plugins.diff --git a/backend/app/services/settings_service.py b/backend/app/services/settings_service.pyindex c02d4e4d..38e6665d 100644--- a/backend/app/services/settings_service.py+++ b/backend/app/services/settings_service.py@@ -153,6 +153,12 @@ class SettingsService:# 503s the module's API (same mechanism as the plugin status guard). The# toggle state later becomes the extraction auto-install signal (#34).'module_wordpress_enabled': {'value': True, 'type': 'boolean', 'description': 'Show the WordPress module (nav, routes, and /api/v1/wordpress).'},+ # Runtime-frontend delivery kill switch (core-slim #39). When on, the+ # /plugins/contributions envelope advertises a `frontends` descriptor map+ # so a production panel can blob-import an installed extension's prebuilt+ # ESM bundle without a rebuild. Off removes the map and the client loader+ # is inert (baked builtins still render via the build-time glob).+ 'extensions.runtime_frontend': {'value': True, 'type': 'boolean', 'description': 'Deliver installed extensions\' prebuilt ESM frontends to production panels at runtime (no rebuild).'},}# Settings that must never be returned through the API (only "is it set?").diff --git a/backend/tests/test_runtime_frontend.py b/backend/tests/test_runtime_frontend.pyindex 3643374c..085c0fa9 100644--- a/backend/tests/test_runtime_frontend.py+++ b/backend/tests/test_runtime_frontend.py@@ -35,19 +35,18 @@ from app.models.plugin import InstalledPluginfrom app.services import contribution_service, plugin_service, registry_servicefrom app.services.settings_service import SettingsService-pytestmark = pytest.mark.skip(- reason="plan 42: hollow feature - the runtime-frontend backend contract "- "(frontends descriptor map, _frontend_hashes install-time ESM sha256, "- "extensions.runtime_frontend kill switch) was lost in the data loss")-_BUNDLE = 'export function Page(){return null;}'_ICON = '<circle cx="12" cy="12" r="8"/>'@pytest.fixture-def plugin_dirs(tmp_path, monkeypatch):+def plugin_dirs(app, tmp_path, monkeypatch):"""Redirect plugin install roots at throwaway tmp dirs so installs never- touch the real backend/frontend/builtin plugin trees."""+ touch the real backend/frontend/builtin plugin trees.++ Depends on ``app`` so the test body runs inside an application context (the+ ``app`` fixture yields while its context is active) — the assertions query+ the DB and call services directly."""backend = tmp_path / 'backend_plugins'frontend = tmp_path / 'frontend_plugins'builtin = tmp_path / 'builtin_extensions'@@ -72,8 +71,8 @@ def _runtime_zip(slug='serverkit-runtime', bundle=_BUNDLE, **kw):'sdk_version': '^1.0.0','frontend_entry': 'dist/index.mjs','contributions': {- 'nav': [{'label': 'Runtime Demo', 'route': 'runtime-demo',- 'category': 'system', 'icon': _ICON}],+ 'nav': [{'id': 'runtime-demo', 'label': 'Runtime Demo',+ 'route': 'runtime-demo', 'category': 'system', 'icon': _ICON}],'routes': [{'path': 'runtime-demo', 'component': 'Page'}],},}@@ -137,6 +136,7 @@ def test_baked_and_runtime_coexist(plugin_dirs):# A baked builtin contributes via a .jsx component, not a runtime bundle, so# it must NOT appear in the runtime `frontends` map.baked = InstalledPlugin(slug='serverkit-baked', name='Baked',+ display_name='Baked', version='1.0.0',status=InstalledPlugin.STATUS_ACTIVE,manifest={'frontend_entry': 'components/Baked.jsx'})db.session.add(baked)diff --git a/backend/tests/test_sdk_contract.py b/backend/tests/test_sdk_contract.pyindex 64be49e2..06edfd57 100644--- a/backend/tests/test_sdk_contract.py+++ b/backend/tests/test_sdk_contract.py@@ -28,9 +28,6 @@ def test_backend_mirror_matches_frontend_sdk_version():)[email protected](reason="plan 42: hollow feature - runtime-frontend contribution "- "surface (sdk_version/frontends in get_active_contributions) "- "was lost in the data loss; restored by plan 42 recovery")def test_contributions_reports_sdk_version(client, auth_headers):resp = client.get('/api/v1/plugins/contributions', headers=auth_headers)assert resp.status_code == 200diff --git a/docs/EXTENSIONS.md b/docs/EXTENSIONS.mdindex c4348beb..84d8876a 100644--- a/docs/EXTENSIONS.md+++ b/docs/EXTENSIONS.md@@ -177,11 +177,58 @@ must design around:1. **Builtin (in-repo) extensions work in production** because their frontendhalves are checked into `frontend/src/plugins/<slug>/` and compiled into everyshipped bundle. "Install" just flips the runtime contribution envelope on.-2. **A third-party extension that ships a frontend does *not* render on a- production panel** (the panel serves a pre-built bundle; `plugin_service` copies- files but nothing rebuilds Vite). Its **backend half loads fine.** Until the- Phase 3 frontend-delivery mechanism lands, third-party extensions should be- backend-only, or use a `bare`/custom layout escape hatch.+2. **A third-party extension can now render on a production panel without a+ rebuild** — if it ships a prebuilt **ESM bundle** (see below). The panel serves+ a pre-built bundle and nothing rebuilds Vite, so a checked-in `.jsx` frontend+ still won't appear; but a `dist/index.mjs` bundle is fetched, integrity-checked,+ and blob-imported at runtime by the client loader. Its **backend half loads+ fine** either way.++### Runtime frontend delivery (prebuilt ESM bundle)++An installed extension whose manifest declares a `.mjs` `frontend_entry` is+delivered to the running panel **without a rebuild** (core-slim #39):++```jsonc+// plugin.json+{+ "frontend_entry": "dist/index.mjs", // an ESM bundle (NOT a .jsx source file)+ "sdk_version": "^1.0.0" // semver range the panel SDK must satisfy+}+```++How it works: at install time `plugin_service` records the bundle's sha256 (stored+under the panel-managed `_frontend_hashes` config key). The+`/api/v1/plugins/contributions` envelope then advertises a `frontends` descriptor+map — `{ slug: { entry, hashes, sdk_version } }` — plus the panel's `sdk_version`.+The client loader (`frontend/src/plugins/runtime/loader.js`) fetches the bundle+through the JWT-authed assets route, verifies the sha256, refuses it if its+`sdk_version` range doesn't cover the panel, then blob-imports it — resolving the+externalized bare specifiers through the host import map. Failures render a fail-soft+card on the extension's routes, never a white screen.++**Build convention** — externalize exactly the specifiers the host import map+resolves (`react`, `react-dom`, `react/jsx-runtime`, `react-router-dom`,+`serverkit-sdk`) so the extension shares the panel's singleton instances:++```js+// vite.config.js (extension repo)+import { defineConfig } from 'vite';+export default defineConfig({+ build: {+ lib: { entry: 'src/index.jsx', formats: ['es'], fileName: () => 'index.mjs' },+ outDir: 'dist',+ rollupOptions: {+ external: ['react', 'react-dom', 'react/jsx-runtime',+ 'react-router-dom', 'serverkit-sdk'],+ },+ },+});+```++Operators can disable runtime delivery panel-wide with the+`extensions.runtime_frontend` system setting (kill switch, default on); baked+builtins keep rendering via the build-time glob regardless.### D5 — builtin frontends are pre-bundled (single source of truth)