Skip to content

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.

feat(extensions): deliver runtime ESM frontends to production panels (#39)

Juan Denisffc1fd772813
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 a
build now takes you to one full-page live console at `/deployments/<id>`: a
diff --git a/ROADMAP.md b/ROADMAP.md
index 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 panel
diff --git a/backend/app/api/plugins.py b/backend/app/api/plugins.py
index 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_KEYS
plugin = 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.py
index 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 a
contributions 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 out
def _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.py
index 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=False
plugin.entry_point = entry_point
plugin.url_prefix = url_prefix
plugin.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_ACTIVE
db.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.py
index 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.py
index 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 InstalledPlugin
from app.services import contribution_service, plugin_service, registry_service
from 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.py
index 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 == 200
diff --git a/docs/EXTENSIONS.md b/docs/EXTENSIONS.md
index 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 frontend
halves are checked into `frontend/src/plugins/<slug>/` and compiled into every
shipped 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)