From aad2aac696699bae6b30cdf7f536370e9647293f Mon Sep 17 00:00:00 2001
From: Stefan Ernst <24554551+stefan-ernst@users.noreply.github.com>
Date: Mon, 2 Nov 2026 09:05:28 +0100
Subject: [PATCH] feat(plugins): enforce host-function permissions (WI-1821)

Plugin host functions were registered for every plugin, so a plugin that
declared a minimal capability set still received process execution, outbound
HTTP/SMTP, KV, comment and SCM access (security finding F2).

- New manifest field `permissions` with a closed catalog: process.exec ->
  cli_exec, network.egress -> http_fetch, mail.send -> smtp_send, storage.kv ->
  kv_get/kv_set/kv_delete, comments.write -> create_comment, scm.write ->
  scm_create_branch/scm_create_item_link. `log` stays always available.
- Unknown permission names fail the load; declared permissions are normalized
  and deduplicated.
- Every gated host function checks the calling plugin's effective permissions
  and returns a typed denial instead of executing. An absent plugin context
  denies.
- License precedence is permission AND license: an unlicensed plugin keeps
  loading but gets no host-function permissions.
- The admin plugin list reports requested vs effective permissions, and module
  settings renders a badge per permission.
- A load-time warning names the plugin and the host functions it can no longer
  call.
- NewManager validates the registered host function set against the catalog so a
  new host function cannot ship unguarded.
---
 frontend/src/lib/locales/de/admin.js          |   4 +
 frontend/src/lib/locales/en/admin.js          |   4 +
 frontend/src/lib/locales/fr/admin.js          |   4 +
 frontend/src/lib/locales/ru/admin.js          |   4 +
 frontend/src/lib/locales/zh-CN/admin.js       |   4 +
 .../src/lib/settings/ModuleSettings.svelte    |  28 +++-
 internal/handlers/plugins.go                  |  34 +++--
 internal/plugins/capabilities.go              | 121 ++++++++++++++++++
 internal/plugins/cli_host.go                  |   8 ++
 internal/plugins/host_functions.go            |  40 ++++++
 internal/plugins/manager.go                   |  86 +++++++++++--
 internal/plugins/manager_stub.go              |   3 +
 internal/plugins/types.go                     |  24 ++--
 13 files changed, 332 insertions(+), 32 deletions(-)
 create mode 100644 internal/plugins/capabilities.go

diff --git a/frontend/src/lib/locales/de/admin.js b/frontend/src/lib/locales/de/admin.js
index 094e8d09f..00e4f660f 100644
--- a/frontend/src/lib/locales/de/admin.js
+++ b/frontend/src/lib/locales/de/admin.js
@@ -836,6 +836,10 @@ export default {
       routeAuth_session: 'Sitzung',
       routeAuth_admin: 'Administrator',
       routeAuth_none: 'Öffentlich',
+      hostFunctionPermissions: 'Host-Funktionsberechtigungen',
+      permissionGranted: 'Erteilt',
+      permissionDenied: 'Verweigert',
+      permissionsDeniedNote: 'Einige deklarierte Berechtigungen sind nicht wirksam.',
       moduleSettingsNote: 'Änderungen an Moduleinstellungen werden sofort wirksam. Das Deaktivieren eines Moduls blendet es aus der Navigation aus.',
       failedToUpload: 'Hochladen fehlgeschlagen: {error}',
       failedToReload: 'Plugin konnte nicht neu geladen werden: {error}',
diff --git a/frontend/src/lib/locales/en/admin.js b/frontend/src/lib/locales/en/admin.js
index 57b3c741b..bbd42dab7 100644
--- a/frontend/src/lib/locales/en/admin.js
+++ b/frontend/src/lib/locales/en/admin.js
@@ -903,6 +903,10 @@ export default {
       routeAuth_session: 'Session',
       routeAuth_admin: 'Admin',
       routeAuth_none: 'Public',
+      hostFunctionPermissions: 'Host Function Permissions',
+      permissionGranted: 'Granted',
+      permissionDenied: 'Denied',
+      permissionsDeniedNote: 'Some declared permissions are not in effect.',
       moduleSettingsNote:
         'Changes to module settings take effect immediately. Disabling a module will hide it from the navigation.',
       failedToUpload: 'Upload failed: {error}',
diff --git a/frontend/src/lib/locales/fr/admin.js b/frontend/src/lib/locales/fr/admin.js
index ff8e4469d..54cd92bcc 100644
--- a/frontend/src/lib/locales/fr/admin.js
+++ b/frontend/src/lib/locales/fr/admin.js
@@ -845,6 +845,10 @@ export default {
       routeAuth_session: 'Session',
       routeAuth_admin: 'Administrateur',
       routeAuth_none: 'Public',
+      hostFunctionPermissions: 'Permissions des fonctions hôtes',
+      permissionGranted: 'Accordée',
+      permissionDenied: 'Refusée',
+      permissionsDeniedNote: 'Certaines permissions déclarées ne sont pas effectives.',
       moduleSettingsNote:
         'Les modifications des paramètres de module prennent effet immédiatement. Désactiver un module le masquera de la navigation.',
       failedToUpload: 'Échec du téléversement : {error}',
diff --git a/frontend/src/lib/locales/ru/admin.js b/frontend/src/lib/locales/ru/admin.js
index 5490cd9f7..c4e7c191a 100644
--- a/frontend/src/lib/locales/ru/admin.js
+++ b/frontend/src/lib/locales/ru/admin.js
@@ -942,6 +942,10 @@ export default {
       routeAuth_session: 'Сессия',
       routeAuth_admin: 'Администратор',
       routeAuth_none: 'Публичный',
+      hostFunctionPermissions: 'Разрешения хост-функций',
+      permissionGranted: 'Предоставлено',
+      permissionDenied: 'Отклонено',
+      permissionsDeniedNote: 'Некоторые объявленные разрешения не действуют.',
       moduleSettingsNote:
         'Изменения настроек модулей применяются сразу. Отключённый модуль будет скрыт из навигации.',
       failedToUpload: 'Не удалось загрузить: {error}',
diff --git a/frontend/src/lib/locales/zh-CN/admin.js b/frontend/src/lib/locales/zh-CN/admin.js
index 3c37d065d..e2218cd3c 100644
--- a/frontend/src/lib/locales/zh-CN/admin.js
+++ b/frontend/src/lib/locales/zh-CN/admin.js
@@ -726,6 +726,10 @@ export default {
       routeAuth_session: '会话',
       routeAuth_admin: '管理员',
       routeAuth_none: '公开',
+      hostFunctionPermissions: '宿主函数权限',
+      permissionGranted: '已授予',
+      permissionDenied: '已拒绝',
+      permissionsDeniedNote: '部分声明的权限未生效。',
       moduleSettingsNote: '模块设置的更改会立即生效。禁用模块将从导航中隐藏它。',
       failedToUpload: '上传失败：{error}',
       failedToReload: '重新加载插件失败：{error}',
diff --git a/frontend/src/lib/settings/ModuleSettings.svelte b/frontend/src/lib/settings/ModuleSettings.svelte
index db2c6090a..98339f058 100644
--- a/frontend/src/lib/settings/ModuleSettings.svelte
+++ b/frontend/src/lib/settings/ModuleSettings.svelte
@@ -550,8 +550,34 @@
                         </div>
                       </div>
                     {/if}
+
+                    {#if plugin.requested_permissions && plugin.requested_permissions.length > 0}
+                      <div class="mt-3">
+                        <p class="text-xs font-medium mb-1" style="color: var(--ds-text-subtle);">{t('settings.modules.hostFunctionPermissions')}:</p>
+                        <div class="flex flex-wrap gap-1">
+                          {#each plugin.requested_permissions as permission, permissionIndex}
+                            {@const granted = (plugin.effective_permissions || []).includes(permission)}
+                            <span
+                              class="text-xs font-mono rounded px-2 py-1"
+                              data-testid={`plugin-permission-${plugin.name}-${permissionIndex}`}
+                              data-permission={permission}
+                              data-granted={granted}
+                              title={granted ? t('settings.modules.permissionGranted') : t('settings.modules.permissionDenied')}
+                              style={granted
+                                ? 'background-color: var(--ds-background-neutral); color: var(--ds-text);'
+                                : 'background-color: var(--ds-accent-red-subtle); color: var(--ds-accent-red);'}
+                            >
+                              {permission}
+                            </span>
+                          {/each}
+                        </div>
+                        {#if (plugin.effective_permissions || []).length < plugin.requested_permissions.length}
+                          <p class="text-xs mt-1" style="color: var(--ds-accent-red);">{t('settings.modules.permissionsDeniedNote')}</p>
+                        {/if}
+                      </div>
+                    {/if}
                   </div>
-                  
+
                   {#if !pluginsDisabled}
                     <div class="flex items-center gap-2 ml-4">
                       <button
diff --git a/internal/handlers/plugins.go b/internal/handlers/plugins.go
index cd8003db0..c29ccb424 100644
--- a/internal/handlers/plugins.go
+++ b/internal/handlers/plugins.go
@@ -54,10 +54,15 @@ type PluginInfo struct {
 	Enabled     bool   `json:"enabled"`
 	// Licensed reports whether the plugin's license verified for this install.
 	// Always true when license enforcement is not configured.
-	Licensed    bool                `json:"licensed"`
-	Routes      []map[string]string `json:"routes"`
-	Extensions  []plugins.Extension `json:"extensions,omitempty"`
-	InstalledAt string              `json:"installed_at"`
+	Licensed bool                `json:"licensed"`
+	Routes   []map[string]string `json:"routes"`
+	// RequestedPermissions is what the plugin's manifest declares;
+	// EffectivePermissions is what it actually holds after manifest validation
+	// and license gating. Undeclared host functions are denied.
+	RequestedPermissions []string            `json:"requested_permissions,omitempty"`
+	EffectivePermissions []string            `json:"effective_permissions,omitempty"`
+	Extensions           []plugins.Extension `json:"extensions,omitempty"`
+	InstalledAt          string              `json:"installed_at"`
 }
 
 // ListPlugins returns all installed plugins
@@ -98,8 +103,11 @@ func (h *PluginHandler) ListPlugins(w http.ResponseWriter, r *http.Request) {
 			for i := range pluginList {
 				dbPlugin := &pluginList[i]
 				if dbPlugin.Name == loadedPlugin.Manifest.Name {
-					// The loaded state is the source of truth for licensing.
+					// The loaded state is the source of truth for licensing and
+					// effective host-function permissions.
 					dbPlugin.Licensed = loadedPlugin.Licensed
+					dbPlugin.RequestedPermissions = loadedPlugin.Manifest.Permissions
+					dbPlugin.EffectivePermissions = loadedPlugin.Permissions
 					found = true
 					break
 				}
@@ -118,13 +126,15 @@ func (h *PluginHandler) ListPlugins(w http.ResponseWriter, r *http.Request) {
 				}
 
 				pluginList = append(pluginList, PluginInfo{
-					Name:        loadedPlugin.Manifest.Name,
-					Version:     loadedPlugin.Manifest.Version,
-					Description: loadedPlugin.Manifest.Description,
-					Author:      loadedPlugin.Manifest.Author,
-					Enabled:     loadedPlugin.Enabled,
-					Licensed:    loadedPlugin.Licensed,
-					Routes:      routes,
+					Name:                 loadedPlugin.Manifest.Name,
+					Version:              loadedPlugin.Manifest.Version,
+					Description:          loadedPlugin.Manifest.Description,
+					Author:               loadedPlugin.Manifest.Author,
+					Enabled:              loadedPlugin.Enabled,
+					Licensed:             loadedPlugin.Licensed,
+					Routes:               routes,
+					RequestedPermissions: loadedPlugin.Manifest.Permissions,
+					EffectivePermissions: loadedPlugin.Permissions,
 				})
 			}
 		}
diff --git a/internal/plugins/capabilities.go b/internal/plugins/capabilities.go
new file mode 100644
index 000000000..1cd2a79a3
--- /dev/null
+++ b/internal/plugins/capabilities.go
@@ -0,0 +1,121 @@
+//go:build !noplugins
+
+package plugins
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+
+	extism "github.com/extism/go-sdk"
+)
+
+// Host-function permissions. A plugin may call a host function only when its
+// manifest declares the matching permission; everything else is denied by
+// default. The names form a closed catalog: an unknown name fails the plugin
+// load, so a typo cannot silently leave a host function unavailable.
+//
+// The `log` host function is always available and needs no permission.
+const (
+	PermissionProcessExec   = "process.exec"
+	PermissionNetworkEgress = "network.egress"
+	PermissionMailSend      = "mail.send"
+	PermissionStorageKV     = "storage.kv"
+	PermissionCommentsWrite = "comments.write"
+	PermissionSCMWrite      = "scm.write"
+)
+
+// hostFunctionPermissions maps each registered host function to the permission
+// a plugin must declare to call it. TestHostFunctionPermissionMapping fails when
+// a registered host function is missing from this table, so a new host function
+// cannot ship unguarded.
+var hostFunctionPermissions = map[string]string{
+	"cli_exec":             PermissionProcessExec,
+	"http_fetch":           PermissionNetworkEgress,
+	"smtp_send":            PermissionMailSend,
+	"kv_get":               PermissionStorageKV,
+	"kv_set":               PermissionStorageKV,
+	"kv_delete":            PermissionStorageKV,
+	"create_comment":       PermissionCommentsWrite,
+	"scm_create_branch":    PermissionSCMWrite,
+	"scm_create_item_link": PermissionSCMWrite,
+}
+
+// ungatedHostFunctions are always available and require no permission.
+var ungatedHostFunctions = map[string]struct{}{
+	"log": {},
+}
+
+// knownPermissions is the closed catalog of valid manifest permissions.
+var knownPermissions = func() map[string]struct{} {
+	known := make(map[string]struct{}, len(hostFunctionPermissions))
+	for _, permission := range hostFunctionPermissions {
+		known[permission] = struct{}{}
+	}
+	return known
+}()
+
+// normalizePermissions trims, deduplicates, and validates a manifest's declared
+// permissions. An unknown name is an error so a typo fails the load instead of
+// silently leaving the host function denied.
+func normalizePermissions(declared []string) ([]string, error) {
+	seen := make(map[string]struct{}, len(declared))
+	for _, raw := range declared {
+		permission := strings.TrimSpace(raw)
+		if permission == "" {
+			continue
+		}
+		if _, ok := knownPermissions[permission]; !ok {
+			return nil, fmt.Errorf("unknown permission %q", permission)
+		}
+		seen[permission] = struct{}{}
+	}
+	if len(seen) == 0 {
+		return nil, nil
+	}
+	normalized := make([]string, 0, len(seen))
+	for permission := range seen {
+		normalized = append(normalized, permission)
+	}
+	sort.Strings(normalized)
+	return normalized, nil
+}
+
+// deniedHostFunctions lists the gated host functions a plugin cannot call with
+// the given effective permissions, in a stable order. The load path logs this so
+// an operator sees exactly which host functions a plugin lost access to.
+func deniedHostFunctions(effective []string) []string {
+	granted := make(map[string]struct{}, len(effective))
+	for _, permission := range effective {
+		granted[permission] = struct{}{}
+	}
+	var denied []string
+	for hostFunction, permission := range hostFunctionPermissions {
+		if _, ok := granted[permission]; !ok {
+			denied = append(denied, hostFunction)
+		}
+	}
+	sort.Strings(denied)
+	return denied
+}
+
+// permissionDeniedMessage is the response body a host function returns when the
+// calling plugin did not declare its permission.
+func permissionDeniedMessage(permission string) string {
+	return fmt.Sprintf("host function denied: plugin does not declare permission %q", permission)
+}
+
+// validateHostFunctionCatalog verifies that every registered host function is
+// either explicitly ungated or carries a permission mapping. NewManager runs it
+// against its host function set so a new host function cannot ship unguarded.
+func validateHostFunctionCatalog(hostFunctions []extism.HostFunction) error {
+	for _, hostFunction := range hostFunctions {
+		if _, ungated := ungatedHostFunctions[hostFunction.Name]; ungated {
+			continue
+		}
+		if _, mapped := hostFunctionPermissions[hostFunction.Name]; !mapped {
+			return fmt.Errorf("host function %q has no permission mapping", hostFunction.Name)
+		}
+	}
+	return nil
+}
diff --git a/internal/plugins/cli_host.go b/internal/plugins/cli_host.go
index 37618e21f..81205e2ec 100644
--- a/internal/plugins/cli_host.go
+++ b/internal/plugins/cli_host.go
@@ -29,6 +29,14 @@ const (
 
 // cliExecHostFunction executes a CLI command and returns the result.
 func (m *Manager) cliExecHostFunction(ctx context.Context, plugin *extism.CurrentPlugin, stack []uint64) {
+	if !m.requirePermission(ctx, PermissionProcessExec) {
+		m.writeHostResponse(plugin, stack, CLIExecResponse{
+			Status: "error",
+			Error:  permissionDeniedMessage(PermissionProcessExec),
+		})
+		return
+	}
+
 	enabled, err := m.cliExecEnabled()
 	if err != nil {
 		m.logger.Error("cli_exec: failed to read security setting", "error", err)
diff --git a/internal/plugins/host_functions.go b/internal/plugins/host_functions.go
index b2f47f8fc..4f5b948dd 100644
--- a/internal/plugins/host_functions.go
+++ b/internal/plugins/host_functions.go
@@ -66,6 +66,11 @@ func (m *Manager) logHostFunction(ctx context.Context, plugin *extism.CurrentPlu
 }
 
 func (m *Manager) smtpHostFunction(ctx context.Context, plugin *extism.CurrentPlugin, stack []uint64) {
+	if !m.requirePermission(ctx, PermissionMailSend) {
+		m.writeHostResponse(plugin, stack, SMTPSendResponse{Status: "error", Error: permissionDeniedMessage(PermissionMailSend)})
+		return
+	}
+
 	payload, err := plugin.ReadBytes(stack[0])
 	if err != nil {
 		m.logger.Warn("smtp_send host function failed to read payload", "error", err)
@@ -93,6 +98,11 @@ func (m *Manager) smtpHostFunction(ctx context.Context, plugin *extism.CurrentPl
 }
 
 func (m *Manager) httpFetchHostFunction(ctx context.Context, plugin *extism.CurrentPlugin, stack []uint64) {
+	if !m.requirePermission(ctx, PermissionNetworkEgress) {
+		m.writeHostResponse(plugin, stack, HTTPFetchResponse{Status: http.StatusForbidden, Body: []byte(permissionDeniedMessage(PermissionNetworkEgress))})
+		return
+	}
+
 	payload, err := plugin.ReadBytes(stack[0])
 	if err != nil {
 		m.logger.Warn("http_fetch host function failed to read payload", "error", err)
@@ -184,6 +194,11 @@ func (m *Manager) writeHostResponse(plugin *extism.CurrentPlugin, stack []uint64
 }
 
 func (m *Manager) kvGetHostFunction(ctx context.Context, plugin *extism.CurrentPlugin, stack []uint64) {
+	if !m.requirePermission(ctx, PermissionStorageKV) {
+		m.writeHostResponse(plugin, stack, KVGetResponse{Status: "error", Error: permissionDeniedMessage(PermissionStorageKV)})
+		return
+	}
+
 	payload, err := plugin.ReadBytes(stack[0])
 	if err != nil {
 		m.logger.Warn("kv_get host function failed to read payload", "error", err)
@@ -234,6 +249,11 @@ func (m *Manager) kvGetHostFunction(ctx context.Context, plugin *extism.CurrentP
 }
 
 func (m *Manager) kvSetHostFunction(ctx context.Context, plugin *extism.CurrentPlugin, stack []uint64) {
+	if !m.requirePermission(ctx, PermissionStorageKV) {
+		m.writeHostResponse(plugin, stack, KVSetResponse{Status: "error", Error: permissionDeniedMessage(PermissionStorageKV)})
+		return
+	}
+
 	payload, err := plugin.ReadBytes(stack[0])
 	if err != nil {
 		m.logger.Warn("kv_set host function failed to read payload", "error", err)
@@ -292,6 +312,11 @@ func (m *Manager) kvSetHostFunction(ctx context.Context, plugin *extism.CurrentP
 }
 
 func (m *Manager) kvDeleteHostFunction(ctx context.Context, plugin *extism.CurrentPlugin, stack []uint64) {
+	if !m.requirePermission(ctx, PermissionStorageKV) {
+		m.writeHostResponse(plugin, stack, KVDeleteResponse{Status: "error", Error: permissionDeniedMessage(PermissionStorageKV)})
+		return
+	}
+
 	payload, err := plugin.ReadBytes(stack[0])
 	if err != nil {
 		m.logger.Warn("kv_delete host function failed to read payload", "error", err)
@@ -336,6 +361,11 @@ func (m *Manager) kvDeleteHostFunction(ctx context.Context, plugin *extism.Curre
 }
 
 func (m *Manager) createCommentHostFunction(ctx context.Context, plugin *extism.CurrentPlugin, stack []uint64) {
+	if !m.requirePermission(ctx, PermissionCommentsWrite) {
+		m.writeHostResponse(plugin, stack, CreateCommentResponse{Status: "error", Error: permissionDeniedMessage(PermissionCommentsWrite)})
+		return
+	}
+
 	payload, err := plugin.ReadBytes(stack[0])
 	if err != nil {
 		m.logger.Warn("create_comment host function failed to read payload", "error", err)
@@ -393,6 +423,11 @@ func (m *Manager) createCommentHostFunction(ctx context.Context, plugin *extism.
 }
 
 func (m *Manager) scmCreateBranchHostFunction(ctx context.Context, plugin *extism.CurrentPlugin, stack []uint64) {
+	if !m.requirePermission(ctx, PermissionSCMWrite) {
+		m.writeHostResponse(plugin, stack, SCMCreateBranchResponse{Status: "error", Error: permissionDeniedMessage(PermissionSCMWrite)})
+		return
+	}
+
 	payload, err := plugin.ReadBytes(stack[0])
 	if err != nil {
 		m.logger.Warn("scm_create_branch host function failed to read payload", "error", err)
@@ -439,6 +474,11 @@ func (m *Manager) scmCreateBranchHostFunction(ctx context.Context, plugin *extis
 }
 
 func (m *Manager) scmCreateItemLinkHostFunction(ctx context.Context, plugin *extism.CurrentPlugin, stack []uint64) {
+	if !m.requirePermission(ctx, PermissionSCMWrite) {
+		m.writeHostResponse(plugin, stack, SCMCreateItemLinkResponse{Status: "error", Error: permissionDeniedMessage(PermissionSCMWrite)})
+		return
+	}
+
 	payload, err := plugin.ReadBytes(stack[0])
 	if err != nil {
 		m.logger.Warn("scm_create_item_link host function failed to read payload", "error", err)
diff --git a/internal/plugins/manager.go b/internal/plugins/manager.go
index ef9a6cf95..a1352fc83 100644
--- a/internal/plugins/manager.go
+++ b/internal/plugins/manager.go
@@ -40,9 +40,15 @@ type LoadedPlugin struct {
 	Path       string
 	Enabled    bool
 	// Licensed reports whether the plugin's license verified. It only gates
-	// capabilities when a LicenseVerifier is configured.
+	// capabilities and host-function permissions when a LicenseVerifier is
+	// configured.
 	Licensed bool
-	compiled *extism.CompiledPlugin
+	// Permissions is the effective host-function permission set after manifest
+	// validation and license gating. Only these permissions can reach host
+	// functions; an empty set leaves only log available. Manifest.Permissions
+	// holds what the plugin requested.
+	Permissions []string
+	compiled    *extism.CompiledPlugin
 }
 
 // Manager handles plugin loading and lifecycle.
@@ -86,6 +92,37 @@ func pluginNameFromContext(ctx context.Context) string {
 	return name
 }
 
+// pluginPermissionsKey is the unexported context key under which the executing
+// plugin's effective host-function permissions are carried to host functions.
+type pluginPermissionsKey struct{}
+
+// withPluginPermissions returns a copy of ctx carrying the plugin's effective
+// host-function permissions so host functions can enforce them per-invocation.
+func withPluginPermissions(ctx context.Context, permissions []string) context.Context {
+	return context.WithValue(ctx, pluginPermissionsKey{}, permissions)
+}
+
+// pluginPermissionsFromContext returns the effective permissions stored in ctx,
+// or nil when absent. Absent means deny, not allow.
+func pluginPermissionsFromContext(ctx context.Context) []string {
+	permissions, _ := ctx.Value(pluginPermissionsKey{}).([]string)
+	return permissions
+}
+
+// requirePermission reports whether the plugin executing in ctx declared the
+// permission. It logs every denial; callers return their own typed error
+// response. A missing plugin context denies, so metadata population and any
+// future direct invocation cannot reach a gated host function.
+func (m *Manager) requirePermission(ctx context.Context, permission string) bool {
+	for _, granted := range pluginPermissionsFromContext(ctx) {
+		if granted == permission {
+			return true
+		}
+	}
+	m.logger.Warn("plugin host function denied", "plugin", pluginNameFromContext(ctx), "permission", permission)
+	return false
+}
+
 // NewManager creates a new plugin manager configured for Extism-backed plugins.
 func NewManager(pluginDir string, opts ...Option) *Manager {
 	options := ManagerOptions{
@@ -127,6 +164,9 @@ func NewManager(pluginDir string, opts ...Option) *Manager {
 		db:                options.Database,
 	}
 	m.hostFuncs = m.buildHostFunctions()
+	if err := validateHostFunctionCatalog(m.hostFuncs); err != nil {
+		m.logger.Error("plugin host function catalog is invalid", "error", err)
+	}
 	return m
 }
 
@@ -209,6 +249,14 @@ func (m *Manager) LoadPlugin(pluginPath string) error {
 		return fmt.Errorf("invalid plugin schedules: %w", err)
 	}
 
+	// Permissions are validated before compilation so an unknown name fails the
+	// load with the offending value instead of leaving a host function denied.
+	normalizedPermissions, err := normalizePermissions(manifest.Permissions)
+	if err != nil {
+		return fmt.Errorf("invalid plugin permissions: %w", err)
+	}
+	manifest.Permissions = normalizedPermissions
+
 	wasmPath := filepath.Join(pluginPath, manifest.EntryPoint)
 	if _, err = os.Stat(wasmPath); err != nil {
 		return fmt.Errorf("failed to read WASM file: %w", err)
@@ -222,6 +270,14 @@ func (m *Manager) LoadPlugin(pluginPath string) error {
 		return fmt.Errorf("failed to compile plugin: %w", err)
 	}
 
+	licensed := m.verifyStoredLicense(pluginPath, manifest.Name)
+	// Capability AND license: an unlicensed plugin gets no host-function
+	// permissions even when its manifest declares them.
+	var effectivePermissions []string
+	if licensed {
+		effectivePermissions = manifest.Permissions
+	}
+
 	plugin := &LoadedPlugin{
 		Manifest: manifest,
 		Metadata: PluginMetadata{
@@ -230,11 +286,12 @@ func (m *Manager) LoadPlugin(pluginPath string) error {
 			Description: manifest.Description,
 			Author:      manifest.Author,
 		},
-		Routes:   manifest.Routes,
-		Path:     pluginPath,
-		Enabled:  true,
-		Licensed: m.verifyStoredLicense(pluginPath, manifest.Name),
-		compiled: compiled,
+		Routes:      manifest.Routes,
+		Path:        pluginPath,
+		Enabled:     true,
+		Licensed:    licensed,
+		Permissions: effectivePermissions,
+		compiled:    compiled,
 	}
 
 	if err := m.populateMetadata(ctx, plugin); err != nil {
@@ -257,6 +314,16 @@ func (m *Manager) LoadPlugin(pluginPath string) error {
 		}
 	}
 
+	// Loud load-time notice of the compatibility break: a plugin that predates
+	// host-function permissions still relies on functions it never declared, and
+	// those calls are now denied.
+	if denied := deniedHostFunctions(plugin.Permissions); len(denied) > 0 {
+		m.logger.Warn("plugin host functions are denied because their permission is not granted",
+			"plugin", manifest.Name,
+			"declared_permissions", manifest.Permissions,
+			"denied_host_functions", denied)
+	}
+
 	m.mu.Lock()
 	m.plugins[manifest.Name] = plugin
 	m.mu.Unlock()
@@ -442,6 +509,7 @@ func (m *Manager) invokeEnabledPlugin(
 	ctx, cancel := context.WithTimeout(context.Background(), m.pluginTimeout)
 	defer cancel()
 	ctx = withPluginName(ctx, pluginName)
+	ctx = withPluginPermissions(ctx, p.Permissions)
 
 	instance, err := p.compiled.Instance(ctx, extism.PluginInstanceConfig{})
 	if err != nil {
@@ -723,11 +791,11 @@ func (m *Manager) verifyStoredLicense(pluginPath, pluginName string) bool {
 	}
 	licenseBytes, err := os.ReadFile(filepath.Join(pluginPath, licenseTokenFileName)) //nolint:gosec // G304 — pluginPath from securejoin, fixed name
 	if err != nil || len(licenseBytes) == 0 {
-		m.logger.Warn("plugin has no license; capabilities are disabled for it", "name", pluginName)
+		m.logger.Warn("plugin has no license; capabilities and host-function permissions are disabled for it", "name", pluginName)
 		return false
 	}
 	if err := m.licenseVerifier(pluginName, licenseBytes); err != nil {
-		m.logger.Warn("plugin license verification failed; capabilities are disabled for it", "name", pluginName, "error", err)
+		m.logger.Warn("plugin license verification failed; capabilities and host-function permissions are disabled for it", "name", pluginName, "error", err)
 		return false
 	}
 	return true
diff --git a/internal/plugins/manager_stub.go b/internal/plugins/manager_stub.go
index 5f604c821..6aeece3f4 100644
--- a/internal/plugins/manager_stub.go
+++ b/internal/plugins/manager_stub.go
@@ -27,6 +27,9 @@ type LoadedPlugin struct {
 	// loads plugins, so it stays false; it exists so callers that read
 	// LoadedPlugin compile in both build variants.
 	Licensed bool
+	// Permissions mirrors the plugins-build field. The stub never loads
+	// plugins, so it stays empty.
+	Permissions []string
 }
 
 // Manager handles plugin loading and lifecycle.
diff --git a/internal/plugins/types.go b/internal/plugins/types.go
index f9eafa1c8..557b9c33c 100644
--- a/internal/plugins/types.go
+++ b/internal/plugins/types.go
@@ -119,16 +119,20 @@ type HTTPFetchResponse struct {
 
 // PluginManifest represents the manifest.json file authored by plugin developers.
 type PluginManifest struct {
-	Name         string           `json:"name"`
-	Version      string           `json:"version"`
-	Description  string           `json:"description"`
-	Author       string           `json:"author"`
-	EntryPoint   string           `json:"entryPoint"`
-	Capabilities []string         `json:"capabilities,omitempty"`
-	Extensions   []Extension      `json:"extensions,omitempty"` // UI extensions provided by this plugin
-	Routes       []Route          `json:"routes,omitempty"`     // Inline route metadata
-	Webhooks     []PluginWebhook  `json:"webhooks,omitempty"`   // Webhooks the plugin wants to receive
-	Schedules    []PluginSchedule `json:"schedules,omitempty"`  // Periodic invocations
+	Name         string   `json:"name"`
+	Version      string   `json:"version"`
+	Description  string   `json:"description"`
+	Author       string   `json:"author"`
+	EntryPoint   string   `json:"entryPoint"`
+	Capabilities []string `json:"capabilities,omitempty"`
+	// Permissions declares the host functions the plugin may call. It is a
+	// closed catalog (see capabilities.go); an unknown name fails the load.
+	// Empty means none: only the always-available log host function is granted.
+	Permissions []string         `json:"permissions,omitempty"`
+	Extensions  []Extension      `json:"extensions,omitempty"` // UI extensions provided by this plugin
+	Routes      []Route          `json:"routes,omitempty"`     // Inline route metadata
+	Webhooks    []PluginWebhook  `json:"webhooks,omitempty"`   // Webhooks the plugin wants to receive
+	Schedules   []PluginSchedule `json:"schedules,omitempty"`  // Periodic invocations
 }
 
 // PluginWebhook represents a webhook registration from a plugin.