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): enforce signature policy in install flow

Juan Denis31697cda9e09
diff --git a/backend/app/api/marketplace.py b/backend/app/api/marketplace.py
index bbc6e525..f5e0cbae 100644
--- a/backend/app/api/marketplace.py
+++ b/backend/app/api/marketplace.py
@@ -68,6 +68,11 @@ def install_registry(slug):
reason = 'unreviewed'
elif not entry.get('sha256'):
reason = 'unverified'
+ elif entry.get('signature') and not entry.get('publisher_trusted'):
+ # Signed, but by a publisher key this panel doesn't pin (plan 55).
+ # Consent-overridable like unsigned; a BAD signature is never
+ # overridable — install_registry_extension hard-fails on it below.
+ reason = 'untrusted_key'
if reason:
message = (
'This community extension has not been reviewed by the ServerKit '
@@ -76,6 +81,11 @@ def install_registry(slug):
if reason == 'unreviewed' else
'This extension has no pinned checksum, so the panel cannot '
'verify the artifact it would install.'
+ if reason == 'unverified' else
+ f"This extension is signed, but its publisher key "
+ f"'{entry.get('publisher_key_id')}' is not pinned by this panel, "
+ f"so the signature cannot be verified. Install only if you trust "
+ f"the source."
)
return jsonify({
'error': f'{message} Resend with acknowledge_risk: true to proceed.',
diff --git a/backend/app/api/plugins.py b/backend/app/api/plugins.py
index 7c6d6171..c1bb8ec4 100644
--- a/backend/app/api/plugins.py
+++ b/backend/app/api/plugins.py
@@ -69,10 +69,19 @@ def install_plugin():
# Optional checksum continuity: the preview step returns the resolved URL +
# sha256; passing them here pins the install to the exact previewed bytes.
expected_sha256 = (data.get('sha256') or None)
+ # Optional signature continuity (plan 55): when the preview verified a
+ # detached signature, pass it through so the install re-verifies the exact
+ # pinned bytes. A bad signature is a hard failure; no signature = the
+ # consent card's "unsigned" path.
+ expected_signature = (data.get('signature') or None)
+ expected_key_id = (data.get('publisher_key_id') or None)
from app.services.plugin_service import install_from_url
try:
- plugin = install_from_url(url, user_id=user.id, expected_sha256=expected_sha256)
+ plugin = install_from_url(
+ url, user_id=user.id, expected_sha256=expected_sha256,
+ expected_signature=expected_signature, expected_key_id=expected_key_id,
+ )
AuditService.log(
action=AuditLog.ACTION_RESOURCE_CREATE,
user_id=user.id,
diff --git a/backend/app/data/registry_index.json b/backend/app/data/registry_index.json
index edd65ab9..b66da469 100644
--- a/backend/app/data/registry_index.json
+++ b/backend/app/data/registry_index.json
@@ -1,7 +1,7 @@
{
- "schema_version": 2,
- "updated": "2026-07-20",
- "note": "Bundled fallback copy of the ServerKit extension registry index. The live index is fetched from SERVERKIT_REGISTRY_URL when configured; this file is used offline and in tests. Curated via PR in the serverkit-extensions repo.",
+ "schema_version": 3,
+ "updated": "2026-08-05",
+ "note": "Bundled fallback copy of the ServerKit extension registry index. The live index is fetched from SERVERKIT_REGISTRY_URL when configured; this file is used offline and in tests. Curated via PR in the serverkit-extensions repo. Schema v3 adds optional per-entry `signature` + `publisher_key_id` (ed25519 minisign-style detached signature over the release zip, verified against the panel's pinned publisher keys at install — plan 55 D3). v1/v2 indexes without those fields remain valid; their entries are treated as unsigned.",
"extensions": [
{
"slug": "serverkit-gui",
diff --git a/backend/app/models/plugin.py b/backend/app/models/plugin.py
index 95d576eb..c1178dbe 100644
--- a/backend/app/models/plugin.py
+++ b/backend/app/models/plugin.py
@@ -109,6 +109,10 @@ class InstalledPlugin(db.Model):
# Schema only — saved VALUES may hold secrets and are served
# exclusively by the admin-gated /config endpoint.
'config_schema': manifest.get('config_schema') or {},
+ # Install-time signature verdict (plan 55): None for sources that
+ # predate stamping, else {status: verified|untrusted_key|unsigned,
+ # key_id?, publisher?}. Panel-managed (reserved config key).
+ 'signature': (self.config or {}).get('_signature'),
'installed_at': self.installed_at.isoformat() if self.installed_at else None,
'updated_at': self.updated_at.isoformat() if self.updated_at else None,
}
diff --git a/backend/app/services/plugin_service.py b/backend/app/services/plugin_service.py
index 23492468..783c89a6 100644
--- a/backend/app/services/plugin_service.py
+++ b/backend/app/services/plugin_service.py
@@ -503,8 +503,28 @@ def _update_plugin_metadata(plugin, manifest):
plugin.category = manifest.get('category', 'utility')
+def _record_signature_status(plugin, sig_result):
+ """Stamp the install-time signature verdict on the plugin's config under
+ the panel-managed ``_signature`` reserved key (same trust-machinery
+ namespace as ``_frontend_hashes`` — config PUTs can't forge it). The
+ extension detail surfaces this so an installed extension's origin
+ verification stays visible after install."""
+ cfg = dict(plugin.config or {})
+ if sig_result and sig_result.get('status') != 'unsigned':
+ cfg['_signature'] = {
+ k: sig_result.get(k)
+ for k in ('status', 'key_id', 'publisher')
+ if sig_result.get(k)
+ }
+ else:
+ cfg['_signature'] = {'status': 'unsigned'}
+ plugin.config = cfg
+ db.session.commit()
+
+
def install_from_url(url, user_id=None, expected_sha256=None, force=False,
- hot_load=True, source_type=None):
+ hot_load=True, source_type=None,
+ expected_signature=None, expected_key_id=None):
"""Download and install a plugin from a URL.
Args:
@@ -512,6 +532,11 @@ def install_from_url(url, user_id=None, expected_sha256=None, force=False,
user_id: ID of the user performing the install
expected_sha256: if given, the downloaded zip must match this digest
before extraction — a mismatch is a hard failure (no partial install)
+ expected_signature / expected_key_id: if given, the downloaded zip is
+ verified against this base64 ed25519 signature envelope (plan 55
+ D3) under the pinned publisher key named by expected_key_id. A bad
+ signature is a hard failure; an unpinned key installs but is
+ recorded as 'untrusted_key'.
force: allow reinstalling over an already-active plugin (used by updates)
hot_load: register the blueprint into the running app immediately.
The boot-time repair pass (#48) passes False — load_all_plugins
@@ -539,11 +564,20 @@ def install_from_url(url, user_id=None, expected_sha256=None, force=False,
)
buf.seek(0)
- return _install_from_buffer(
+ sig_result = None
+ if expected_signature:
+ from app.services import signing_service
+ sig_result = signing_service.verify_for_install(
+ buf.getvalue(), expected_signature, expected_key_id)
+ buf.seek(0)
+
+ plugin = _install_from_buffer(
buf, source_url=url, source_type=source_type or 'url',
user_id=user_id, force=force,
hot_load=hot_load,
)
+ _record_signature_status(plugin, sig_result)
+ return plugin
def _read_manifest_from_buffer(buf):
@@ -567,17 +601,45 @@ def _read_manifest_from_buffer(buf):
raise ValueError(f'plugin.json could not be parsed: {e}')
+def _fetch_detached_signature(resolved_url):
+ """Best-effort fetch of the minisign-style detached signature published
+ beside a release zip (``<zip URL>.minisig`` — the convention
+ scripts/sign-extension.mjs writes). Returns the base64 envelope string,
+ or None when the release carries no signature (or the fetch fails —
+ preview must never hard-fail on a missing optional asset)."""
+ if not (resolved_url or '').startswith(('http://', 'https://')):
+ return None
+ try:
+ headers = {
+ 'Accept': 'text/plain, application/octet-stream',
+ 'User-Agent': 'ServerKit-Plugin-Installer/1.0',
+ }
+ token = _github_token()
+ if token and _is_github_host(resolved_url):
+ headers['Authorization'] = f'Bearer {token}'
+ resp = requests.get(resolved_url + '.minisig', timeout=15, headers=headers)
+ if resp.status_code != 200:
+ return None
+ text = (resp.text or '').strip()
+ return text or None
+ except Exception as e:
+ logger.debug(f'No detached signature at {resolved_url}.minisig: {e}')
+ return None
+
+
def preview_from_url(url):
"""Resolve + download a GitHub/zip source and read its manifest WITHOUT
installing. Returns the metadata a user needs to consent to the install:
slug, display_name, version, description, permissions, panel-version gate,
- the resolved download URL, its sha256, and any warnings.
+ the resolved download URL, its sha256, the signature verdict (signed by a
+ pinned publisher / unsigned / untrusted key / invalid), and any warnings.
Stateless by design — the subsequent install re-downloads (extension zips
are small) and pins the previewed sha256 so the installed bytes are
byte-identical to the previewed bytes.
"""
from app.utils.version import version_satisfies, get_panel_version
+ from app.services import signing_service
import hashlib
normalized = _normalize_source_url(url)
@@ -595,6 +657,22 @@ def preview_from_url(url):
buf.seek(0)
manifest = _read_manifest_from_buffer(buf)
+ # Signature verdict for the consent card (plan 55): the detached .minisig
+ # beside the release asset, verified against the panel's pinned publisher
+ # keys. Unsigned is a verdict, not an error — the card says so honestly.
+ sig_b64 = _fetch_detached_signature(resolved)
+ sig_result = signing_service.verify_detached(buf.getvalue(), sig_b64)
+ signature = {
+ 'status': sig_result['status'],
+ 'key_id': sig_result.get('key_id'),
+ 'publisher': sig_result.get('publisher'),
+ # The raw envelope is echoed back so the install step can re-verify
+ # the exact previewed signature against the pinned sha256 bytes.
+ 'signature': sig_b64 if sig_result['status'] != 'unsigned' else None,
+ }
+ if sig_result['status'] == 'invalid':
+ signature['error'] = sig_result.get('error')
+
# Validate shape early so preview surfaces manifest problems too.
_validate_manifest(manifest)
@@ -632,6 +710,7 @@ def preview_from_url(url):
'max_panel_version': maxv,
'resolved_url': resolved,
'sha256': digest,
+ 'signature': signature,
'warnings': warnings,
}
@@ -1551,8 +1630,9 @@ def get_plugin_by_slug(slug):
# 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',)
+# config PUT. The runtime-frontend loader's per-bundle sha256 hashes live here,
+# and so does the install-time signature verdict (plan 55).
+RESERVED_PLUGIN_CONFIG_KEYS = ('_frontend_hashes', '_signature')
def _record_frontend_hashes(plugin, manifest, frontend_dest):
@@ -1942,7 +2022,12 @@ def _assert_panel_compatible(entry):
def install_registry_extension(slug, user_id=None):
- """Install an extension listed in the remote registry (checksum-verified)."""
+ """Install an extension listed in the remote registry (checksum-verified).
+
+ When the index entry carries a ``signature``/``publisher_key_id`` pair
+ (index schema v3, plan 55 D3) the downloaded zip is also verified against
+ the panel's pinned publisher keys — a bad signature is a hard failure
+ even when the sha256 matches."""
from app.services import registry_service
entry = registry_service.get_entry(slug)
if not entry:
@@ -1954,6 +2039,8 @@ def install_registry_extension(slug, user_id=None):
return install_from_url(
source, user_id=user_id, expected_sha256=entry.get('sha256'),
source_type='registry',
+ expected_signature=entry.get('signature'),
+ expected_key_id=entry.get('publisher_key_id'),
)
@@ -2011,4 +2098,6 @@ def update_plugin(plugin_id, user_id=None):
return install_from_url(
source, user_id=user_id, expected_sha256=entry.get('sha256'), force=True,
source_type=stamped,
+ expected_signature=entry.get('signature'),
+ expected_key_id=entry.get('publisher_key_id'),
)
diff --git a/backend/app/services/registry_service.py b/backend/app/services/registry_service.py
index a1a5d607..af48683c 100644
--- a/backend/app/services/registry_service.py
+++ b/backend/app/services/registry_service.py
@@ -75,6 +75,11 @@ _FIELDS = {
'max_panel_version': None,
'source': '',
'sha256': None,
+ # Index schema v3 (plan 55 D3): optional ed25519 detached signature over
+ # the release zip + the publisher key id that must verify it. Absent in
+ # v1/v2 indexes → the entry is treated as unsigned (consent, not a block).
+ 'signature': None,
+ 'publisher_key_id': None,
'review': None,
'repo': '',
'logo': None,
@@ -141,6 +146,20 @@ def _normalize(raw, base_url=None):
out['bundled'] = bool(out['bundled'])
out['logo'] = _resolve_logo(out['logo'], base_url)
out['review'] = _validate_review(out['review'])
+ # Signature fields only count as well-formed strings; a signature without
+ # a key id (or vice versa) is meaningless and collapses to unsigned.
+ if not isinstance(out['signature'], str) or not out['signature'].strip():
+ out['signature'] = None
+ if not isinstance(out['publisher_key_id'], str) or not out['publisher_key_id'].strip():
+ out['publisher_key_id'] = None
+ if not out['signature'] or not out['publisher_key_id']:
+ out['signature'] = None
+ out['publisher_key_id'] = None
+ # Whether the named publisher key is pinned by this panel — drives the
+ # catalog badge / 409 consent distinction between "signed" and "signed by
+ # someone we don't know". The crypto check itself happens at install.
+ from app.services import signing_service
+ out['publisher_trusted'] = signing_service.is_trusted_key(out['publisher_key_id'])
out['trust'] = _derive_trust(out)
return out