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
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.pyindex 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_extensiontry: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'] = TrueAuditService.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_serviceregistry_service.record_install(plugin.slug, plugin.version)except Exception:passdiff --git a/backend/app/services/registry_service.py b/backend/app/services/registry_service.pyindex a62de3ac..ea52d788 100644--- a/backend/app/services/registry_service.py+++ b/backend/app/services/registry_service.py@@ -16,6 +16,7 @@ Design rules:import jsonimport loggingimport os+import reimport timefrom 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 outdiff --git a/backend/tests/test_registry.py b/backend/tests/test_registry.pyindex 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, monkeresp2 = 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 == 201diff --git a/docs/EXTENSIONS_REGISTRY.md b/docs/EXTENSIONS_REGISTRY.mdindex 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 extensiondiff --git a/frontend/src/pages/Marketplace.jsx b/frontend/src/pages/Marketplace.jsxindex 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 && (<PluginConfigDialogplugin={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.jsindex 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.scssindex 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;