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.

Marketplace: hash-bound review stamps and trust levels for registry extensions

Juan Denis02bb7666e2b3
diff --git a/backend/app/api/marketplace.py b/backend/app/api/marketplace.py
index 9c33e8fa..d17a7946 100644
--- a/backend/app/api/marketplace.py
+++ b/backend/app/api/marketplace.py
@@ -46,20 +46,43 @@ def install_registry(slug):
if not user or not user.is_admin:
return jsonify({'error': 'Admin access required'}), 403
+ # Trust gate: an unreviewed community extension (or one with no pinned
+ # checksum) installs only after an explicit risk acknowledgment — the
+ # Marketplace shows a confirmation dialog and resends with
+ # acknowledge_risk: true. first_party / reviewed entries install as-is.
+ from app.services import registry_service
+ entry = registry_service.get_entry(slug)
+ body = request.get_json(silent=True) or {}
+ trust = (entry or {}).get('trust', 'unreviewed')
+ acknowledged = body.get('acknowledge_risk') is True
+ if entry is not None and not acknowledged and (
+ trust == 'unreviewed' or not entry.get('sha256')):
+ return jsonify({
+ 'error': 'This community extension has not been reviewed by the '
+ 'ServerKit maintainers; installing it runs unreviewed code '
+ 'with full panel privileges. Resend with '
+ 'acknowledge_risk: true to proceed.',
+ 'trust': trust,
+ 'requires_acknowledgment': True,
+ }), 409
+
from app.services.plugin_service import install_registry_extension
try:
plugin = install_registry_extension(slug, user_id=user.id)
+ details = {'name': plugin.name, 'version': plugin.version, 'source': 'registry'}
+ if acknowledged:
+ details['trust'] = trust
+ details['acknowledged_risk'] = True
AuditService.log(
action=AuditLog.ACTION_RESOURCE_CREATE,
user_id=user.id,
target_type='plugin',
target_id=plugin.id,
- details={'name': plugin.name, 'version': plugin.version, 'source': 'registry'},
+ details=details,
)
# Opt-in anonymous install ping (default OFF; #17). Best-effort — never
# affects the install result.
try:
- from app.services import registry_service
registry_service.record_install(plugin.slug, plugin.version)
except Exception:
pass
diff --git a/backend/app/services/registry_service.py b/backend/app/services/registry_service.py
index a62de3ac..ea52d788 100644
--- a/backend/app/services/registry_service.py
+++ b/backend/app/services/registry_service.py
@@ -16,6 +16,7 @@ Design rules:
import json
import logging
import os
+import re
import time
from urllib.parse import urljoin
@@ -74,6 +75,7 @@ _FIELDS = {
'max_panel_version': None,
'source': '',
'sha256': None,
+ 'review': None,
'repo': '',
'logo': None,
'homepage': '',
@@ -98,6 +100,34 @@ def _resolve_logo(logo, base_url):
return logo
+# A review stamp counts only when it pins a full lowercase sha256 digest —
+# anything else is treated as absent (never trusted by shape alone).
+_REVIEW_SHA_RE = re.compile(r'^[0-9a-f]{64}$')
+
+
+def _validate_review(review):
+ """Keep a `review` stamp only if it is a dict whose `sha256` is a 64-char
+ lowercase hex digest of the exact artifact the reviewer inspected."""
+ if not isinstance(review, dict):
+ return None
+ sha = review.get('sha256')
+ if not isinstance(sha, str) or not _REVIEW_SHA_RE.match(sha):
+ return None
+ return review
+
+
+def _derive_trust(entry):
+ """first_party > reviewed (review stamp hash-bound to the entry's sha256)
+ > unreviewed. A stale stamp (artifact changed → sha256 moved on) never
+ counts: the reviewer vouched for exact bytes, not a slug."""
+ if entry['first_party']:
+ return 'first_party'
+ review = entry['review']
+ if review and entry['sha256'] and review['sha256'] == entry['sha256']:
+ return 'reviewed'
+ return 'unreviewed'
+
+
def _normalize(raw, base_url=None):
if not isinstance(raw, dict) or not raw.get('slug'):
return None
@@ -110,6 +140,8 @@ def _normalize(raw, base_url=None):
out['screenshots'] = []
out['bundled'] = bool(out['bundled'])
out['logo'] = _resolve_logo(out['logo'], base_url)
+ out['review'] = _validate_review(out['review'])
+ out['trust'] = _derive_trust(out)
return out
diff --git a/backend/tests/test_registry.py b/backend/tests/test_registry.py
index e98f0ed5..c2326f0b 100644
--- a/backend/tests/test_registry.py
+++ b/backend/tests/test_registry.py
@@ -349,3 +349,121 @@ def test_registry_endpoint_include_bundled_flag(app, client, auth_headers, monke
resp2 = client.get('/api/v1/marketplace/registry?include_bundled=true', headers=auth_headers)
assert any(e['slug'] == 'serverkit-wordpress' for e in resp2.get_json()['extensions'])
+
+
+# --------------------------------------------------------------------------- #
+# Review stamps → trust derivation + the install acknowledgment gate
+# --------------------------------------------------------------------------- #
+
+_SHA_A = 'a' * 64
+_SHA_B = 'b' * 64
+
+
+def _entry(**overrides):
+ base = {
+ 'slug': 'community-ext', 'display_name': 'Community', 'version': '1.0.0',
+ 'source': 'https://x/c.zip', 'sha256': _SHA_A,
+ }
+ base.update(overrides)
+ return registry_service._normalize(base)
+
+
+def test_trust_first_party_wins():
+ e = _entry(first_party=True, review={'reviewer': 'jhd3197', 'sha256': _SHA_B})
+ assert e['trust'] == 'first_party'
+
+
+def test_trust_reviewed_when_hashes_match():
+ e = _entry(review={'reviewer': 'jhd3197', 'date': '2026-07-23', 'sha256': _SHA_A})
+ assert e['trust'] == 'reviewed'
+ assert e['review']['reviewer'] == 'jhd3197'
+
+
+def test_trust_unreviewed_without_review():
+ assert _entry()['trust'] == 'unreviewed'
+ assert _entry()['review'] is None
+
+
+def test_trust_unreviewed_when_review_hash_is_stale():
+ # The artifact changed → entry sha256 moved on → the stamp no longer counts.
+ e = _entry(review={'reviewer': 'jhd3197', 'sha256': _SHA_B})
+ assert e['trust'] == 'unreviewed'
+
+
[email protected]('review', [
+ 'not-a-dict',
+ {'reviewer': 'jhd3197'}, # no sha256
+ {'sha256': 'ABCDEF' + '0' * 58}, # uppercase
+ {'sha256': 'a' * 63}, # too short
+ {'sha256': 'g' * 64}, # non-hex
+])
+def test_trust_unreviewed_when_review_malformed(review):
+ e = _entry(review=review)
+ assert e['review'] is None
+ assert e['trust'] == 'unreviewed'
+
+
+class _FakePlugin:
+ id = 1
+ name = 'community-ext'
+ slug = 'community-ext'
+ version = '1.0.0'
+
+ def to_dict(self):
+ return {'name': self.name, 'version': self.version}
+
+
+def fake_install(monkeypatch):
+ """Stub the heavy install; the gate tests only exercise the route logic."""
+ monkeypatch.setattr(
+ plugin_service, 'install_registry_extension', lambda slug, user_id=None: _FakePlugin())
+
+
+def _seed_cache(monkeypatch, entry):
+ monkeypatch.setattr(registry_service, '_cache', {
+ 'ts': 9e18, 'source': 'test', 'entries': [entry],
+ })
+
+
+def test_install_gate_blocks_unreviewed_without_ack(app, client, auth_headers, fake_install, monkeypatch):
+ _seed_cache(monkeypatch, _entry())
+ resp = client.post('/api/v1/marketplace/registry/community-ext/install',
+ headers=auth_headers)
+ assert resp.status_code == 409
+ data = resp.get_json()
+ assert data['requires_acknowledgment'] is True
+ assert data['trust'] == 'unreviewed'
+ assert 'unreviewed' in data['error']
+
+
+def test_install_gate_blocks_first_party_without_sha256(app, client, auth_headers, fake_install, monkeypatch):
+ # trusted publisher, but no pinned checksum to verify the artifact against.
+ e = _entry(first_party=True, sha256=None)
+ assert e['trust'] == 'first_party'
+ _seed_cache(monkeypatch, e)
+ resp = client.post('/api/v1/marketplace/registry/community-ext/install',
+ headers=auth_headers)
+ assert resp.status_code == 409
+ assert resp.get_json()['requires_acknowledgment'] is True
+
+
+def test_install_gate_passes_with_acknowledge_risk(app, client, auth_headers, fake_install, monkeypatch):
+ _seed_cache(monkeypatch, _entry())
+ resp = client.post('/api/v1/marketplace/registry/community-ext/install',
+ headers=auth_headers, json={'acknowledge_risk': True})
+ assert resp.status_code == 201
+
+
+def test_install_gate_unaffected_for_first_party(app, client, auth_headers, fake_install, monkeypatch):
+ _seed_cache(monkeypatch, _entry(first_party=True))
+ resp = client.post('/api/v1/marketplace/registry/community-ext/install',
+ headers=auth_headers)
+ assert resp.status_code == 201
+
+
+def test_install_gate_unaffected_for_reviewed(app, client, auth_headers, fake_install, monkeypatch):
+ _seed_cache(monkeypatch, _entry(review={'reviewer': 'jhd3197', 'sha256': _SHA_A}))
+ resp = client.post('/api/v1/marketplace/registry/community-ext/install',
+ headers=auth_headers)
+ assert resp.status_code == 201
diff --git a/docs/EXTENSIONS_REGISTRY.md b/docs/EXTENSIONS_REGISTRY.md
index 29c91b1d..1f481877 100644
--- a/docs/EXTENSIONS_REGISTRY.md
+++ b/docs/EXTENSIONS_REGISTRY.md
@@ -70,6 +70,13 @@ stay valid unchanged; the new fields (`logo`, `repo`, `bundled`) are optional.
"sdk_version": "^1.0.0", // optional (additive) — frontend SDK range the bundle targets
"source": "https://github.com/owner/repo", // repo URL (latest release), release URL, or direct .zip
"sha256": "…", // sha256 of the release zip — STRONGLY recommended
+ "review": { // optional — hash-bound review stamp (see below)
+ "reviewer": "jhd3197",
+ "date": "2026-07-23",
+ "sha256": "…", // sha256 of the exact zip the reviewer inspected
+ "commit": "…", // optional git sha
+ "notes": "…" // optional
+ },
"repo": "https://github.com/owner/repo", // v2 — https URL of the source repo (shown as "Source repo")
"logo": "assets/serverkit-gui/logo.svg", // v2 — https URL OR repo-relative assets/<slug>/<file>
"release_notes": "…", // optional (additive) — shown in the update-diff modal
@@ -117,6 +124,51 @@ Notes:
node scripts/export-registry-entries.mjs # emits index-v2 bundled entries
```
+### Review stamps (`review`) & trust levels
+
+An entry may carry an optional **`review`** stamp recording that a reviewer
+inspected the published artifact:
+
+```jsonc
+"review": {
+ "reviewer": "jhd3197", // who reviewed it
+ "date": "2026-07-23", // when
+ "sha256": "…", // sha256 of the EXACT zip that was reviewed
+ "commit": "…", // optional git sha of the reviewed source
+ "notes": "…" // optional free text
+}
+```
+
+The stamp is **hash-bound**: the reviewer vouched for the bytes whose digest is
+`review.sha256`, not for the slug. If the artifact ever changes (new release,
+replaced asset), the entry's `sha256` moves on and no longer matches
+`review.sha256` — the review is **stale** and stops counting. A stamp only
+survives normalization when it is an object whose `sha256` is a 64-character
+lowercase hex digest; anything malformed is dropped.
+
+From this the panel derives a per-entry **`trust`** level, surfaced on the
+catalog API and in the Marketplace:
+
+| `trust` | Meaning |
+|---|---|
+| `first_party` | `first_party: true` — authored by ServerKit (always wins). |
+| `reviewed` | A valid `review` stamp exists and `review.sha256` equals the entry's `sha256`. |
+| `unreviewed` | Everything else — no stamp, a stale stamp (hash mismatch), a malformed stamp, or no `sha256` to bind to. |
+
+The Marketplace renders **Reviewed** (with a *Reviewed by \<reviewer\> on
+\<date\>* tooltip) and **Unreviewed** badges accordingly.
+
+**Install-time acknowledgment.** Installing an `unreviewed` entry — or any
+entry with no `sha256` to verify against — requires explicit consent:
+`POST /api/v1/marketplace/registry/<slug>/install` without
+`{"acknowledge_risk": true}` in the JSON body returns **409** with
+`{"error": …, "trust": …, "requires_acknowledgment": true}`. The Marketplace
+catches this, shows a confirmation dialog explaining that the extension is
+unreviewed community code running with full panel privileges, and resends with
+`acknowledge_risk: true` only if the operator confirms (the acknowledgment is
+recorded in the audit log). `first_party` and `reviewed` entries install
+unchanged, with no extra prompt.
+
---
## Publishing an extension
diff --git a/frontend/src/pages/Marketplace.jsx b/frontend/src/pages/Marketplace.jsx
index c708419b..a34fbc45 100644
--- a/frontend/src/pages/Marketplace.jsx
+++ b/frontend/src/pages/Marketplace.jsx
@@ -85,6 +85,8 @@ const getRegistryCatalogEntry = (entry) => ({
version: entry.version || '0.0.0',
author: entry.author,
firstParty: isFirstParty(entry.author, entry),
+ trust: entry.trust || 'unreviewed',
+ review: entry.review || null,
icon: entry.icon || null,
logo: entry.logo || null,
repo: entry.repo || entry.homepage || null,
@@ -105,6 +107,27 @@ const sourceBadgeVariant = (source) => {
return 'outline';
};
+// Trust badge derived from the registry's hash-bound review stamp. 'reviewed'
+// shows who/when in the tooltip; 'unreviewed' warns on registry cards only
+// (built-in entries never carry a trust field).
+const TrustBadge = ({ entry }) => {
+ if (entry.trust === 'reviewed') {
+ const review = entry.review || {};
+ const title = review.reviewer && review.date
+ ? `Reviewed by ${review.reviewer} on ${review.date}`
+ : 'Reviewed by the ServerKit maintainers';
+ return (
+ <Badge variant="success" title={title}>
+ <ShieldCheck aria-hidden="true" /> Reviewed
+ </Badge>
+ );
+ }
+ if (entry.trust === 'unreviewed' && entry.source === 'registry') {
+ return <Badge variant="warning">Unreviewed</Badge>;
+ }
+ return null;
+};
+
const getLocalCatalogEntry = (builtin) => {
const manifest = builtin.manifest || {};
@@ -173,6 +196,9 @@ const Marketplace = () => {
const [manualInstallSource, setManualInstallSource] = useState(null);
const [installing, setInstalling] = useState(false);
const [detailEntry, setDetailEntry] = useState(null);
+ // Registry slug awaiting unreviewed-risk confirmation — drives the
+ // acknowledge-risk dialog (confirm retries with acknowledge_risk: true).
+ const [riskTarget, setRiskTarget] = useState(null);
// Plugin pending uninstall — drives the keep-vs-purge data-policy dialog.
const [uninstallTarget, setUninstallTarget] = useState(null);
// Id of the installed plugin whose row action (uninstall/toggle/update) is
@@ -216,14 +242,20 @@ const Marketplace = () => {
}
};
- const handleRegistryInstall = async (slug) => {
+ const handleRegistryInstall = async (slug, acknowledgeRisk = false) => {
setInstalling(true);
try {
- const result = await api.installRegistryExtension(slug);
+ const result = await api.installRegistryExtension(
+ slug, acknowledgeRisk ? { acknowledge_risk: true } : undefined);
toast.success(`Installed "${result.display_name}". Restart backend if blueprint routes do not appear.`);
loadExtensions();
} catch (err) {
- toast.error(err.message || 'Registry install failed');
+ // 409 trust gate — ask for explicit confirmation, then retry.
+ if (err.status === 409 && err.data?.requires_acknowledgment) {
+ setRiskTarget(slug);
+ } else {
+ toast.error(err.message || 'Registry install failed');
+ }
} finally {
setInstalling(false);
}
@@ -232,11 +264,21 @@ const Marketplace = () => {
const installEntry = (entry) => {
if (entry.source === 'local') {
handleBuiltinInstall(entry.installKey);
+ } else if (entry.trust === 'unreviewed') {
+ // Proactive gate: unreviewed registry entries confirm first
+ // (the backend 409 path above covers the race/stale cases).
+ setRiskTarget(entry.installKey);
} else {
handleRegistryInstall(entry.installKey);
}
};
+ const confirmRiskyInstall = () => {
+ const slug = riskTarget;
+ setRiskTarget(null);
+ if (slug) handleRegistryInstall(slug, true);
+ };
+
// Land on Installed after a manual install so the new row (and its
// actions) is immediately visible.
const handleManualInstalled = () => {
@@ -414,11 +456,7 @@ const Marketplace = () => {
key={entry.key}
entry={entry}
installing={installing}
- onInstall={
- entry.source === 'local'
- ? handleBuiltinInstall
- : handleRegistryInstall
- }
+ onInstall={() => installEntry(entry)}
onOpenDetail={setDetailEntry}
statusVariant={pluginStatusVariant}
/>
@@ -504,6 +542,34 @@ const Marketplace = () => {
/>
)}
+ {riskTarget && (
+ <Modal
+ open
+ onClose={() => setRiskTarget(null)}
+ title="Install unreviewed extension?"
+ size="sm"
+ footer={
+ <>
+ <Button variant="ghost" onClick={() => setRiskTarget(null)}>Cancel</Button>
+ <Button variant="destructive" onClick={confirmRiskyInstall}>
+ Install anyway
+ </Button>
+ </>
+ }
+ >
+ <div className="extension-risk-dialog">
+ <p>
+ This is a community extension whose exact code has not been
+ reviewed by the ServerKit maintainers.
+ </p>
+ <p className="text-muted">
+ It runs with full panel privileges. Only install it if you trust
+ the author.
+ </p>
+ </div>
+ </Modal>
+ )}
+
{configTarget && (
<PluginConfigDialog
plugin={configTarget}
@@ -641,6 +707,7 @@ const CatalogExtensionCard = ({ entry, installing, onInstall, onOpenDetail, stat
) : (
entry.author && <span>by {entry.author}</span>
)}
+ <TrustBadge entry={entry} />
</div>
<div className="extension-card__actions">
{entry.installed ? (
@@ -691,6 +758,7 @@ const ExtensionDetailModal = ({ entry, installing, statusVariant, onClose, onIns
{entry.firstParty && (
<Badge variant="secondary" className="extension-firstparty">by ServerKit</Badge>
)}
+ <TrustBadge entry={entry} />
<Badge variant={sourceBadgeVariant(entry.source)}>{entry.sourceLabel}</Badge>
<Badge variant="outline">{titleCase(category)}</Badge>
</div>
diff --git a/frontend/src/services/api/system.js b/frontend/src/services/api/system.js
index a5441b4d..b5afd322 100644
--- a/frontend/src/services/api/system.js
+++ b/frontend/src/services/api/system.js
@@ -908,10 +908,13 @@ export async function getRegistryExtensions() {
return this.request('/marketplace/registry');
}
-// One-click install for a registry extension by slug (admin-only).
-export async function installRegistryExtension(slug) {
+// One-click install for a registry extension by slug (admin-only). Pass
+// `{ acknowledge_risk: true }` to confirm an unreviewed community extension
+// after the 409 `requires_acknowledgment` gate.
+export async function installRegistryExtension(slug, body) {
return this.request(`/marketplace/registry/${encodeURIComponent(slug)}/install`, {
method: 'POST',
+ ...(body ? { body } : {}),
});
}
diff --git a/frontend/src/styles/pages/_marketplace.scss b/frontend/src/styles/pages/_marketplace.scss
index 0ebb5723..1623a30b 100644
--- a/frontend/src/styles/pages/_marketplace.scss
+++ b/frontend/src/styles/pages/_marketplace.scss
@@ -832,6 +832,19 @@
}
}
+// Risk-acknowledgment dialog shown before installing an unreviewed
+// community extension from the registry.
+.extension-risk-dialog {
+ display: flex;
+ flex-direction: column;
+ gap: $space-3;
+
+ p {
+ margin: 0;
+ line-height: $line-height-normal;
+ }
+}
+
// Per-plugin config editor (#49) — fields generated from config_schema.
.plugin-config-form {
display: flex;