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): show declared vs observed permissions, and pending deps

Juan Denisd3f32bf4c234
diff --git a/frontend/src/components/marketplace/ExtensionPermissionsDialog.jsx b/frontend/src/components/marketplace/ExtensionPermissionsDialog.jsx
new file mode 100644
index 00000000..3a58a26f
--- /dev/null
+++ b/frontend/src/components/marketplace/ExtensionPermissionsDialog.jsx
@@ -0,0 +1,309 @@
+import { useCallback, useEffect, useState } from 'react';
+import { Ban, Eye, EyeOff, PackageX } from 'lucide-react';
+import api from '../../services/api';
+import Modal from '@/components/Modal';
+import { Button } from '@/components/ui/button';
+import { Pill } from '@/components/ds';
+import { formatRelativeTime } from '../../utils/time';
+
+// The backend stamps observations with datetime.utcnow().isoformat(), which
+// carries no timezone suffix — JS would read that as local time and skew every
+// label by the browser's offset. Pin it to UTC before formatting.
+const asUtcDate = (iso) => {
+ if (!iso) return null;
+ const hasZone = /(Z|[+-]\d{2}:?\d{2})$/.test(String(iso));
+ const parsed = new Date(hasZone ? iso : `${iso}Z`);
+ return Number.isNaN(parsed.getTime()) ? null : parsed;
+};
+
+// "4m ago", with the absolute local timestamp in the tooltip.
+const ObservedAt = ({ iso }) => {
+ const date = asUtcDate(iso);
+ if (!date) return null;
+ return (
+ <time dateTime={date.toISOString()} title={date.toLocaleString()}>
+ {formatRelativeTime(date.toISOString())}
+ </time>
+ );
+};
+
+const plural = (count, word) => `${count} ${word}${count === 1 ? '' : 's'}`;
+
+// One declared permission. The three shapes below are the whole point of this
+// surface, so each renders its own sentence rather than sharing a vague one:
+//
+// observable + used → the gate saw it happen
+// observable + not used → the gate saw nothing, and that means something
+// not observable → there is no gate, so nothing can be concluded.
+// No count, no "unused", no zero.
+const PermissionRow = ({ row }) => {
+ if (!row.observable) {
+ return (
+ <li className="extension-permissions__row extension-permissions__row--opaque">
+ <div className="extension-permissions__row-head">
+ <code>{row.permission}</code>
+ <Pill kind="gray" dot={false}>
+ <EyeOff aria-hidden="true" />
+ Use cannot be observed
+ </Pill>
+ </div>
+ <p className="extension-permissions__note">
+ The panel exposes no gated helper for this capability — an extension that
+ wants it imports the host module directly, and nothing in the panel sees
+ the call. Whether this extension has used it cannot be answered here.
+ </p>
+ {row.uses > 0 && (
+ <p className="extension-permissions__note">
+ {plural(row.uses, 'call')} did pass through the SDK gate and
+ {row.uses === 1 ? ' was' : ' were'} recorded
+ {row.last_used_at && <> (most recent <ObservedAt iso={row.last_used_at} />)</>}
+ . Calls that did not go through the gate leave no trace, so treat that
+ as a floor, not a total.
+ </p>
+ )}
+ </li>
+ );
+ }
+
+ if (row.used) {
+ return (
+ <li className="extension-permissions__row extension-permissions__row--used">
+ <div className="extension-permissions__row-head">
+ <code>{row.permission}</code>
+ <Pill kind="green" dot={false}>
+ <Eye aria-hidden="true" />
+ Used
+ </Pill>
+ </div>
+ <p className="extension-permissions__note">
+ Every use of this capability passes through the panel&apos;s SDK gate.
+ Recorded {plural(row.uses, 'time')} since the panel process started
+ {row.last_used_at && <>, most recently <ObservedAt iso={row.last_used_at} /></>}
+ .
+ </p>
+ </li>
+ );
+ }
+
+ return (
+ <li className="extension-permissions__row extension-permissions__row--unused">
+ <div className="extension-permissions__row-head">
+ <code>{row.permission}</code>
+ <Pill kind="amber" dot={false}>
+ <Eye aria-hidden="true" />
+ No use recorded
+ </Pill>
+ </div>
+ <p className="extension-permissions__note">
+ Every use of this capability has to pass through the panel&apos;s SDK gate, and
+ the gate has recorded none since the panel process started. Either the
+ extension has not needed it yet, or it declares more than it uses.
+ </p>
+ </li>
+ );
+};
+
+// Calls the gate refused. These did not happen — the wording never says "used".
+const BlockedRow = ({ row }) => {
+ const refused = row.denied ?? row.uses;
+ return (
+ <li className="extension-permissions__row extension-permissions__row--blocked">
+ <div className="extension-permissions__row-head">
+ <code>{row.permission}</code>
+ <Pill kind="red" dot={false}>
+ <Ban aria-hidden="true" />
+ Blocked
+ </Pill>
+ </div>
+ <p className="extension-permissions__note">
+ This extension asked for a capability its manifest does not declare, so the
+ panel refused the call — it did not run. Refused {plural(refused, 'time')}
+ {row.last_used_at && <>, most recently <ObservedAt iso={row.last_used_at} /></>}
+ .
+ </p>
+ </li>
+ );
+};
+
+const PermissionsSection = ({ report }) => {
+ const rows = Array.isArray(report?.permissions) ? report.permissions : [];
+ const declared = rows.filter((row) => row.declared);
+ const blocked = rows.filter((row) => !row.declared);
+ const observable = declared.filter((row) => row.observable).length;
+
+ return (
+ <section className="extension-permissions__section">
+ <div className="extension-permissions__section-head">
+ <h4>Declared permissions</h4>
+ {declared.length > 0 && (
+ <span className="extension-permissions__count">
+ {declared.length} declared · {observable} the panel can observe
+ </span>
+ )}
+ </div>
+ <p className="extension-permissions__scope">
+ Use is recorded in memory, in this backend process only. It covers the time
+ since the panel last started and is cleared on restart.
+ </p>
+
+ {declared.length > 0 ? (
+ <ul className="extension-permissions__list">
+ {declared.map((row) => <PermissionRow key={row.permission} row={row} />)}
+ </ul>
+ ) : (
+ <p className="extension-permissions__note">
+ This extension&apos;s manifest declares no host permissions.
+ </p>
+ )}
+
+ {blocked.length > 0 && (
+ <div className="extension-permissions__blocked">
+ <div className="extension-permissions__section-head">
+ <h4>Blocked attempts</h4>
+ </div>
+ <p className="extension-permissions__scope">
+ Capabilities this extension reached for without declaring them. The
+ panel refused each one; nothing on this list ran.
+ </p>
+ <ul className="extension-permissions__list">
+ {blocked.map((row) => <BlockedRow key={row.permission} row={row} />)}
+ </ul>
+ </div>
+ )}
+
+ <p className="extension-permissions__footnote">
+ Declared permissions are a consent signal, not a sandbox. Extension code runs
+ inside the panel process with the panel&apos;s privileges; the panel can record
+ what passes through its own SDK and cannot confine what does not.
+ </p>
+ </section>
+ );
+};
+
+// Task 6: the "saved for manual review" requirements file, with its contents and
+// the exact opt-in env var. Read-only on purpose — there is deliberately no
+// install action here, and the copy says so rather than implying one is missing.
+const RequirementsSection = ({ requirements }) => {
+ const envVar = requirements?.env_var || 'SERVERKIT_ALLOW_PLUGIN_PIP';
+ const pipEnabled = Boolean(requirements?.pip_enabled);
+ const packages = Array.isArray(requirements?.packages) ? requirements.packages : [];
+
+ if (!requirements?.pending) {
+ return (
+ <section className="extension-permissions__section">
+ <div className="extension-permissions__section-head">
+ <h4>Python dependencies</h4>
+ </div>
+ <p className="extension-permissions__note">
+ No pending Python dependencies. Either this extension ships
+ no <code>requirements.txt</code>, or its packages were installed when it
+ was installed.
+ </p>
+ <p className="extension-permissions__note">
+ {pipEnabled
+ ? <>Dependency installation is currently enabled on this panel (<code>{envVar}</code>).</>
+ : <>Dependency installation is off on this panel. When an extension ships Python packages, the panel writes the file next to the extension instead of installing it, and lists it here.</>}
+ </p>
+ </section>
+ );
+ }
+
+ return (
+ <section className="extension-permissions__section">
+ <div className="extension-permissions__section-head">
+ <h4>Python dependencies</h4>
+ <Pill kind="amber" dot={false}>
+ <PackageX aria-hidden="true" />
+ Not installed
+ </Pill>
+ </div>
+ <p className="extension-permissions__note">
+ This extension ships a <code>requirements.txt</code> that the panel did not
+ install ({plural(packages.length, 'requirement')} listed). Anything on this
+ list that is not already present in the backend&apos;s Python environment will
+ fail to import at runtime.
+ </p>
+ <p className="extension-permissions__note">
+ {pipEnabled
+ ? <>Dependency installation is enabled on this panel now (<code>{envVar}</code>), but this file predates that: the panel only installs requirements while installing or updating an extension. Reinstall or update this extension to apply it.</>
+ : <>Installing these runs pip with the backend&apos;s privileges — a setup.py hook is arbitrary code — so it is opt-in and off by default. Set <code>{envVar}=1</code> on the backend, then reinstall or update this extension.</>}
+ </p>
+ {requirements.path && (
+ <p className="extension-permissions__note">
+ File on the backend host: <code>{requirements.path}</code>
+ </p>
+ )}
+ {requirements.content && (
+ <pre className="extension-permissions__file">{requirements.content}</pre>
+ )}
+ {requirements.truncated && (
+ <p className="extension-permissions__note">
+ This file is larger than the panel will send to the browser; the end has
+ been cut off. Read it on the backend host for the full list.
+ </p>
+ )}
+ <p className="extension-permissions__footnote">
+ This page is read-only. Nothing here installs anything.
+ </p>
+ </section>
+ );
+};
+
+// Per-extension honesty surface (plan 55 tasks 6 + 7): what the extension
+// declared, what the panel actually saw it do, what it was refused, and which
+// Python packages the panel declined to install.
+const ExtensionPermissionsDialog = ({ plugin, onClose }) => {
+ const [report, setReport] = useState(null);
+ const [requirements, setRequirements] = useState(null);
+ const [loading, setLoading] = useState(true);
+ const [error, setError] = useState(null);
+
+ const load = useCallback(async () => {
+ setLoading(true);
+ setError(null);
+ try {
+ const [perms, reqs] = await Promise.all([
+ api.getPluginPermissions(plugin.id),
+ api.getPluginRequirements(plugin.id),
+ ]);
+ setReport(perms);
+ setRequirements(reqs);
+ } catch (err) {
+ setError(err.message || 'Could not read this extension.');
+ } finally {
+ setLoading(false);
+ }
+ }, [plugin.id]);
+
+ useEffect(() => { load(); }, [load]);
+
+ return (
+ <Modal
+ open
+ onClose={onClose}
+ title={`${plugin.display_name} — permissions & dependencies`}
+ size="md"
+ footer={<Button variant="ghost" onClick={onClose}>Close</Button>}
+ >
+ <div className="extension-permissions">
+ {loading && <p className="text-muted">Loading…</p>}
+
+ {!loading && error && (
+ <div className="extension-permissions__error">
+ <p>{error}</p>
+ <Button variant="outline" size="sm" onClick={load}>Try again</Button>
+ </div>
+ )}
+
+ {!loading && !error && (
+ <>
+ <PermissionsSection report={report} />
+ <RequirementsSection requirements={requirements} />
+ </>
+ )}
+ </div>
+ </Modal>
+ );
+};
+
+export default ExtensionPermissionsDialog;
diff --git a/frontend/src/pages/Marketplace.jsx b/frontend/src/pages/Marketplace.jsx
index aad7b413..0f001130 100644
--- a/frontend/src/pages/Marketplace.jsx
+++ b/frontend/src/pages/Marketplace.jsx
@@ -14,6 +14,7 @@ import {
ServerCog,
ShieldAlert,
ShieldCheck,
+ ShieldQuestion,
Sparkles,
Star,
UploadCloud,
@@ -31,6 +32,7 @@ import {
} from '@/components/ds';
import { useTopbarActions } from '@/hooks/useTopbarActions';
import ManualInstallModal from '../components/marketplace/ManualInstallModal';
+import ExtensionPermissionsDialog from '../components/marketplace/ExtensionPermissionsDialog';
import {
ExtensionBrandMark, hasBrandMark, extensionCoverStyle,
} from '../components/icons/ExtensionBrands';
@@ -246,6 +248,10 @@ const Marketplace = () => {
const [busyPlugin, setBusyPlugin] = useState(null); // { id, action }
// Plugin whose config is being edited (#49) — drives the config dialog.
const [configTarget, setConfigTarget] = useState(null);
+ // Plugin whose declared-vs-observed permissions and pending Python
+ // dependencies are being read (plan 55 tasks 6+7) — drives the read-only
+ // permissions dialog.
+ const [permissionsTarget, setPermissionsTarget] = useState(null);
const loadExtensions = useCallback(async () => {
try {
@@ -581,6 +587,7 @@ const Marketplace = () => {
onUpdate={handlePluginUpdate}
onUninstall={requestPluginUninstall}
onConfigure={setConfigTarget}
+ onInspectPermissions={setPermissionsTarget}
statusVariant={pluginStatusVariant}
/>
))}
@@ -689,6 +696,13 @@ const Marketplace = () => {
onClose={() => setConfigTarget(null)}
/>
)}
+
+ {permissionsTarget && (
+ <ExtensionPermissionsDialog
+ plugin={permissionsTarget}
+ onClose={() => setPermissionsTarget(null)}
+ />
+ )}
</div>
);
};
@@ -958,7 +972,10 @@ const PLUGIN_SOURCE_BADGES = {
registry: { label: 'Registry', variant: 'info' },
};
-const PluginRow = ({ plugin, update, busy, onToggle, onUpdate, onUninstall, onConfigure, statusVariant }) => {
+const PluginRow = ({
+ plugin, update, busy, onToggle, onUpdate, onUninstall, onConfigure,
+ onInspectPermissions, statusVariant,
+}) => {
const updateAvailable = Boolean(update?.update_available);
const compatible = update?.compatible !== false;
// A row action is in flight — disable every action on this row so it can't
@@ -1011,6 +1028,16 @@ const PluginRow = ({ plugin, update, busy, onToggle, onUpdate, onUninstall, onCo
Configure
</Button>
)}
+ <Button
+ size="sm"
+ variant="outline"
+ disabled={isBusy}
+ title="Declared permissions, what the panel has observed, and pending Python dependencies"
+ onClick={() => onInspectPermissions(plugin)}
+ >
+ <ShieldQuestion aria-hidden="true" />
+ Permissions
+ </Button>
<Button
size="sm"
variant={plugin.status === 'active' ? 'outline' : 'default'}
diff --git a/frontend/src/services/api/plugins.js b/frontend/src/services/api/plugins.js
index 6a9320bb..f13e9620 100644
--- a/frontend/src/services/api/plugins.js
+++ b/frontend/src/services/api/plugins.js
@@ -142,6 +142,33 @@ export async function updatePluginConfig(pluginId, config) {
});
}
+// Declared vs actually-observed permission use for one installed extension
+// (plan 55, admin-only):
+// { slug, permissions: [ { permission, declared, observable, used, uses,
+// first_used_at, last_used_at, denied? } ],
+// unused_observable, undeclared_attempts, observable_count,
+// declaration_only_count }
+//
+// `observable` is the load-bearing field. It is true only for capabilities whose
+// every use has to pass through the SDK gate (today just `agent.command:<action>`);
+// for the declaration-only ones (docker, shell, filesystem, network, db) the panel
+// owns no gate, so `used: false` there means "no evidence either way" and must
+// never be rendered as "unused". Rows with `declared: false` were refused at the
+// gate — attempts, not uses.
+export async function getPluginPermissions(pluginId) {
+ return this.request(`/plugins/${pluginId}/permissions`);
+}
+
+// Python dependencies an install declined to pip-install for one extension
+// (plan 55, admin-only):
+// { slug, pending, pip_enabled, env_var, path, content, packages, truncated }
+// `pending: true` means the packages were NOT installed and the requirements
+// file is sitting next to the extension. Read-only — there is no install route
+// behind this by design.
+export async function getPluginRequirements(pluginId) {
+ return this.request(`/plugins/${pluginId}/requirements`);
+}
+
// Returns available updates for installed plugins:
// { updates: [ { slug, plugin_id, installed_version, available_version,
// update_available, compatible, source } ] }
diff --git a/frontend/src/styles/pages/_marketplace.scss b/frontend/src/styles/pages/_marketplace.scss
index b8e23c5a..f5acb0f7 100644
--- a/frontend/src/styles/pages/_marketplace.scss
+++ b/frontend/src/styles/pages/_marketplace.scss
@@ -860,3 +860,159 @@
line-height: $line-height-normal;
}
}
+
+// Read-only permissions + pending-dependencies dialog for an installed
+// extension (plan 55 tasks 6+7). Rows are prose-first on purpose: the
+// distinction between "the gate saw nothing" and "there is no gate" only
+// survives if each row can say it in a sentence, so nothing here compresses
+// a permission down to a bare chip.
+.extension-permissions {
+ display: flex;
+ flex-direction: column;
+ gap: $space-6;
+
+ &__section {
+ display: flex;
+ flex-direction: column;
+ gap: $space-3;
+ }
+
+ &__section-head {
+ display: flex;
+ flex-wrap: wrap;
+ align-items: center;
+ justify-content: space-between;
+ gap: $space-2;
+
+ h4 {
+ margin: 0;
+ font-size: $font-size-base;
+ font-weight: $font-weight-semibold;
+ }
+ }
+
+ &__count {
+ color: $text-tertiary;
+ font-size: $font-size-sm;
+ }
+
+ // The observation-window caveat under a section heading.
+ &__scope {
+ margin: 0;
+ color: $text-tertiary;
+ font-size: $font-size-sm;
+ line-height: $line-height-normal;
+ }
+
+ &__list {
+ margin: 0;
+ padding: 0;
+ list-style: none;
+ display: flex;
+ flex-direction: column;
+ gap: $space-3;
+ }
+
+ &__row {
+ display: flex;
+ flex-direction: column;
+ gap: $space-2;
+ padding: $space-3;
+ border: 1px solid $border-subtle;
+ border-left: 2px solid $border-active;
+ border-radius: $radius-md;
+ background: $bg-elevated;
+
+ // Left edge carries the verdict so a scan down the list reads the
+ // three states apart before any text is read.
+ &--used { border-left-color: $success; }
+ &--unused { border-left-color: $warning; }
+ &--opaque { border-left-color: $border-active; }
+ &--blocked { border-left-color: $danger; }
+ }
+
+ &__row-head {
+ display: flex;
+ flex-wrap: wrap;
+ align-items: center;
+ justify-content: space-between;
+ gap: $space-2;
+
+ code {
+ font-family: $font-mono;
+ font-size: $font-size-sm;
+ color: $text-primary;
+ overflow-wrap: anywhere;
+ }
+ }
+
+ &__note {
+ margin: 0;
+ color: $text-secondary;
+ font-size: $font-size-sm;
+ line-height: $line-height-normal;
+
+ code {
+ font-family: $font-mono;
+ font-size: $font-size-sm;
+ padding: 1px 4px;
+ border-radius: $radius-sm;
+ background: $bg-code;
+ color: $text-primary;
+ overflow-wrap: anywhere;
+ }
+ }
+
+ &__blocked {
+ display: flex;
+ flex-direction: column;
+ gap: $space-3;
+ margin-top: $space-2;
+ }
+
+ &__footnote {
+ margin: 0;
+ padding-top: $space-2;
+ border-top: 1px solid $border-subtle;
+ color: $text-tertiary;
+ font-size: $font-size-xs;
+ line-height: $line-height-normal;
+ }
+
+ // Verbatim requirements.txt — scrolls on its own rather than widening
+ // the dialog.
+ &__file {
+ margin: 0;
+ max-height: 220px;
+ overflow: auto;
+ padding: $space-3;
+ border: 1px solid $border-subtle;
+ border-radius: $radius-md;
+ background: $bg-code;
+ color: $text-secondary;
+ font-family: $font-mono;
+ font-size: $font-size-sm;
+ line-height: $line-height-normal;
+ white-space: pre;
+ }
+
+ &__error {
+ display: flex;
+ flex-direction: column;
+ align-items: flex-start;
+ gap: $space-3;
+
+ p {
+ margin: 0;
+ color: $danger;
+ font-size: $font-size-sm;
+ line-height: $line-height-normal;
+ }
+ }
+
+ .sk-pill svg {
+ width: 12px;
+ height: 12px;
+ flex-shrink: 0;
+ }
+}