From 40eb4302b8a65758002a8c99ac9a1a8275c89f7e Mon Sep 17 00:00:00 2001
From: John Smith <you@example.com>
Date: Sun, 13 Sep 2026 23:45:07 -0400
Subject: [PATCH 01/13] feat: generic plugin runtime SPI and desktop extension
 host

---
 desktop/main/components/PluginSlot.vue        |   23 +
 desktop/main/composables/usePlugins.ts        |   51 +
 .../internal/plugins/ClientPluginManager.ts   |  513 +++++++
 .../internal/plugins/PluginErrorBoundary.vue  |   37 +
 desktop/main/internal/plugins/types.ts        |  192 +++
 desktop/main/pages/library/[id]/index.vue     |  270 +++-
 desktop/main/pages/settings.vue               |   16 +-
 desktop/main/pages/settings/plugins.vue       |  497 ++++++
 desktop/main/plugins/09.client-plugins.ts     |   83 +
 desktop/src-tauri/Cargo.lock                  |    3 +
 desktop/src-tauri/Cargo.toml                  |    4 +-
 desktop/src-tauri/process/Cargo.toml          |    3 +
 desktop/src-tauri/process/src/lib.rs          |    1 +
 desktop/src-tauri/process/src/path_guard.rs   |  264 ++++
 desktop/src-tauri/src/lib.rs                  |   17 +
 desktop/src-tauri/src/plugins.rs              |  414 +++++
 desktop/src-tauri/src/remote.rs               |  169 +-
 server/dev-tools/run-tests.mjs                |   93 ++
 .../dev-tools/sample-plugin/drop-plugin.json  |   11 +
 server/dev-tools/sample-plugin/index.js       |   16 +
 server/dev-tools/sign-plugin.mjs              |  132 ++
 server/package.json                           |    2 +
 server/pages/admin/settings.vue               |    7 +
 server/pages/admin/settings/plugins.vue       |  454 ++++++
 .../api/v1/plugins/[pluginId]/[...slug].ts    |   17 +
 .../v1/plugins/[pluginId]/bundle.delete.ts    |   29 +
 .../[pluginId]/client/[...asset].get.ts       |   42 +
 .../api/v1/plugins/[pluginId]/state.patch.ts  |   37 +
 server/server/api/v1/plugins/index.get.ts     |   33 +
 server/server/api/v1/plugins/install.post.ts  |   58 +
 server/server/api/v1/plugins/reload.post.ts   |   18 +
 server/server/api/v1/plugins/updates.get.ts   |   23 +
 server/server/api/v1/plugins/ws.get.ts        |  220 +++
 server/server/internal/acls/index.ts          |   64 +-
 .../internal/plugins/__tests__/auth.test.ts   |  104 ++
 .../plugins/__tests__/plugins.test.ts         | 1358 +++++++++++++++++
 .../__tests__/upstream_compatibility.test.ts  |  166 ++
 server/server/internal/plugins/auth.ts        |  119 ++
 .../internal/plugins/builtin/hello-world.ts   |   26 +
 server/server/internal/plugins/errors.ts      |   43 +
 server/server/internal/plugins/index.ts       |   17 +
 server/server/internal/plugins/manager.ts     | 1272 +++++++++++++++
 server/server/internal/plugins/registry.ts    |  119 ++
 server/server/internal/plugins/storage.ts     |  138 ++
 server/server/internal/plugins/types.ts       |  220 +++
 server/server/plugins/08.plugin-system.ts     |   12 +
 sites/docs/src/content/docs/admin/plugins.md  |  162 ++
 47 files changed, 7483 insertions(+), 86 deletions(-)
 create mode 100644 desktop/main/components/PluginSlot.vue
 create mode 100644 desktop/main/composables/usePlugins.ts
 create mode 100644 desktop/main/internal/plugins/ClientPluginManager.ts
 create mode 100644 desktop/main/internal/plugins/PluginErrorBoundary.vue
 create mode 100644 desktop/main/internal/plugins/types.ts
 create mode 100644 desktop/main/pages/settings/plugins.vue
 create mode 100644 desktop/main/plugins/09.client-plugins.ts
 create mode 100644 desktop/src-tauri/process/src/path_guard.rs
 create mode 100644 desktop/src-tauri/src/plugins.rs
 create mode 100644 server/dev-tools/run-tests.mjs
 create mode 100644 server/dev-tools/sample-plugin/drop-plugin.json
 create mode 100644 server/dev-tools/sample-plugin/index.js
 create mode 100644 server/dev-tools/sign-plugin.mjs
 create mode 100644 server/pages/admin/settings/plugins.vue
 create mode 100644 server/server/api/v1/plugins/[pluginId]/[...slug].ts
 create mode 100644 server/server/api/v1/plugins/[pluginId]/bundle.delete.ts
 create mode 100644 server/server/api/v1/plugins/[pluginId]/client/[...asset].get.ts
 create mode 100644 server/server/api/v1/plugins/[pluginId]/state.patch.ts
 create mode 100644 server/server/api/v1/plugins/index.get.ts
 create mode 100644 server/server/api/v1/plugins/install.post.ts
 create mode 100644 server/server/api/v1/plugins/reload.post.ts
 create mode 100644 server/server/api/v1/plugins/updates.get.ts
 create mode 100644 server/server/api/v1/plugins/ws.get.ts
 create mode 100644 server/server/internal/plugins/__tests__/auth.test.ts
 create mode 100644 server/server/internal/plugins/__tests__/plugins.test.ts
 create mode 100644 server/server/internal/plugins/__tests__/upstream_compatibility.test.ts
 create mode 100644 server/server/internal/plugins/auth.ts
 create mode 100644 server/server/internal/plugins/builtin/hello-world.ts
 create mode 100644 server/server/internal/plugins/errors.ts
 create mode 100644 server/server/internal/plugins/index.ts
 create mode 100644 server/server/internal/plugins/manager.ts
 create mode 100644 server/server/internal/plugins/registry.ts
 create mode 100644 server/server/internal/plugins/storage.ts
 create mode 100644 server/server/internal/plugins/types.ts
 create mode 100644 server/server/plugins/08.plugin-system.ts
 create mode 100644 sites/docs/src/content/docs/admin/plugins.md

diff --git a/desktop/main/components/PluginSlot.vue b/desktop/main/components/PluginSlot.vue
new file mode 100644
index 000000000..44f38abb8
--- /dev/null
+++ b/desktop/main/components/PluginSlot.vue
@@ -0,0 +1,23 @@
+<template>
+  <template v-for="item in slotComponents" :key="item.id">
+    <PluginErrorBoundary :plugin-id="item.pluginId">
+      <component :is="item.component" v-bind="context" />
+    </PluginErrorBoundary>
+  </template>
+</template>
+
+<script setup lang="ts">
+import { computed } from "vue";
+import type { UISlotName } from "~/internal/plugins/types";
+import { clientPluginManager } from "~/internal/plugins/ClientPluginManager";
+import PluginErrorBoundary from "~/internal/plugins/PluginErrorBoundary.vue";
+
+const props = defineProps<{
+  name: UISlotName;
+  context?: Record<string, unknown>;
+}>();
+
+const slotComponents = computed(() => {
+  return clientPluginManager.slots[props.name] || [];
+});
+</script>
diff --git a/desktop/main/composables/usePlugins.ts b/desktop/main/composables/usePlugins.ts
new file mode 100644
index 000000000..cc71e6d60
--- /dev/null
+++ b/desktop/main/composables/usePlugins.ts
@@ -0,0 +1,51 @@
+import { ref, computed, watch, onMounted } from "vue";
+import type { UISlotName, PlayAction } from "~/internal/plugins/types";
+import { clientPluginManager } from "~/internal/plugins/ClientPluginManager";
+
+export function usePluginManager() {
+  return clientPluginManager;
+}
+
+export function usePluginSlots(name: UISlotName) {
+  return computed(() => clientPluginManager.slots[name] || []);
+}
+
+export function usePlayActions(gameId: string | (() => string)) {
+  const actions = ref<PlayAction[]>([]);
+  const isLoading = ref(false);
+
+  const resolveId = () => (typeof gameId === "function" ? gameId() : gameId);
+
+  const refreshActions = async () => {
+    const id = resolveId();
+    if (!id) {
+      actions.value = [];
+      return;
+    }
+    isLoading.value = true;
+    try {
+      actions.value = await clientPluginManager.getPlayActions(id);
+    } catch (err) {
+      console.error(`Failed to load play actions for game ${id}:`, err);
+      actions.value = [];
+    } finally {
+      isLoading.value = false;
+    }
+  };
+
+  onMounted(() => {
+    refreshActions();
+  });
+
+  if (typeof gameId === "function") {
+    watch(gameId, () => {
+      refreshActions();
+    });
+  }
+
+  return {
+    actions,
+    isLoading,
+    refreshActions,
+  };
+}
diff --git a/desktop/main/internal/plugins/ClientPluginManager.ts b/desktop/main/internal/plugins/ClientPluginManager.ts
new file mode 100644
index 000000000..92a1c4924
--- /dev/null
+++ b/desktop/main/internal/plugins/ClientPluginManager.ts
@@ -0,0 +1,513 @@
+import { reactive, ref } from "vue";
+import { invoke } from "@tauri-apps/api/core";
+import type {
+  AntiCheatReport,
+  ClientPlugin,
+  ClientPluginContext,
+  ClientPluginStorage,
+  ClientPluginWebSocket,
+  CommandResult,
+  GameMenuItem,
+  HttpMethod,
+  LaunchContext,
+  LaunchHook,
+  PlayAction,
+  ScopedGameFs,
+  ScopedGameScanner,
+  SidebarItem,
+  TopBarItem,
+  UISlotName,
+  UISlotRegistration,
+} from "./types";
+
+export function isTauri(): boolean {
+  return (
+    typeof window !== "undefined" &&
+    ("__TAURI_INTERNALS__" in window || "__TAURI__" in window)
+  );
+}
+
+async function safeInvoke<T>(
+  cmd: string,
+  args?: Record<string, unknown>,
+  fallback?: T,
+): Promise<T> {
+  if (!isTauri()) {
+    console.debug(
+      `[ClientPluginManager] Browser mode: invoke('${cmd}') bypassed`,
+    );
+    return fallback !== undefined ? fallback : (null as unknown as T);
+  }
+  return await invoke<T>(cmd, args);
+}
+
+class BrowserLocalStorage implements ClientPluginStorage {
+  constructor(private readonly pluginId: string) {}
+
+  private prefixKey(key: string): string {
+    return `drop:plugin:${this.pluginId}:${key}`;
+  }
+
+  async get<T>(key: string): Promise<T | null> {
+    try {
+      const val = localStorage.getItem(this.prefixKey(key));
+      return val ? JSON.parse(val) : null;
+    } catch {
+      return null;
+    }
+  }
+
+  async set<T>(key: string, value: T): Promise<void> {
+    localStorage.setItem(this.prefixKey(key), JSON.stringify(value));
+  }
+
+  async delete(key: string): Promise<void> {
+    localStorage.removeItem(this.prefixKey(key));
+  }
+
+  async listKeys(): Promise<string[]> {
+    const prefix = `drop:plugin:${this.pluginId}:`;
+    const keys: string[] = [];
+    for (let i = 0; i < localStorage.length; i++) {
+      const k = localStorage.key(i);
+      if (k?.startsWith(prefix)) {
+        keys.push(k.slice(prefix.length));
+      }
+    }
+    return keys;
+  }
+}
+
+class TauriScopedGameFs implements ScopedGameFs {
+  async readFile(gameId: string, relativePath: string): Promise<Uint8Array> {
+    const res = await safeInvoke<number[]>(
+      "plugin_game_fs_read",
+      { gameId, relativePath },
+      [],
+    );
+    return new Uint8Array(res);
+  }
+
+  async writeFile(
+    gameId: string,
+    relativePath: string,
+    data: Uint8Array | string,
+  ): Promise<void> {
+    const bytes =
+      typeof data === "string"
+        ? Array.from(new TextEncoder().encode(data))
+        : Array.from(data);
+    await safeInvoke("plugin_game_fs_write", {
+      gameId,
+      relativePath,
+      data: bytes,
+    });
+  }
+
+  async backupFile(gameId: string, relativePath: string): Promise<string> {
+    return (
+      (await safeInvoke<string>("plugin_game_fs_backup", {
+        gameId,
+        relativePath,
+      })) || ""
+    );
+  }
+
+  async restoreFile(gameId: string, relativePath: string): Promise<void> {
+    await safeInvoke("plugin_game_fs_restore", {
+      gameId,
+      relativePath,
+    });
+  }
+
+  async fileExists(gameId: string, relativePath: string): Promise<boolean> {
+    return (
+      (await safeInvoke<boolean>(
+        "plugin_game_fs_exists",
+        { gameId, relativePath },
+        false,
+      )) ?? false
+    );
+  }
+
+  async deleteFile(gameId: string, relativePath: string): Promise<void> {
+    await safeInvoke("plugin_game_fs_delete", {
+      gameId,
+      relativePath,
+    });
+  }
+}
+
+class TauriScopedGameScanner implements ScopedGameScanner {
+  async scanExecutables(
+    gameId: string,
+  ): Promise<Array<{ relativePath: string; sha256: string; size: number }>> {
+    return (
+      (await safeInvoke<
+        Array<{ relativePath: string; sha256: string; size: number }>
+      >("plugin_game_scan_executables", { gameId }, [])) || []
+    );
+  }
+
+  async checkAntiCheat(gameId: string): Promise<AntiCheatReport> {
+    return (
+      (await safeInvoke<AntiCheatReport>(
+        "plugin_game_check_anticheat",
+        { gameId },
+        { detected: false, files: [] },
+      )) || { detected: false, files: [] }
+    );
+  }
+}
+
+class TauriPluginWebSocket implements ClientPluginWebSocket {
+  async send(channel: string, data: unknown): Promise<unknown> {
+    return await safeInvoke("plugin_request_ws", { channel, data });
+  }
+
+  subscribe(channel: string, listener: (data: unknown) => void): () => void {
+    if (isTauri()) {
+      safeInvoke("plugin_subscribe", { channel }).catch((err) => {
+        console.error(`Failed to subscribe to plugin channel ${channel}:`, err);
+      });
+    }
+
+    const handler = (event: Event) => {
+      const custom = event as CustomEvent<{ channel?: string; data?: unknown }>;
+      if (custom?.detail?.channel === channel) {
+        listener(custom.detail.data);
+      }
+    };
+
+    window.addEventListener("plugin:event", handler);
+    return () => {
+      window.removeEventListener("plugin:event", handler);
+    };
+  }
+}
+
+export class ClientPluginManager {
+  private readonly plugins = new Map<string, ClientPlugin>();
+  public readonly slots = reactive<Record<UISlotName, UISlotRegistration[]>>({
+    "game-detail:actions": [],
+    "game-detail:panels": [],
+    "game-detail:badges": [],
+    "settings:tabs": [],
+    "topbar:status": [],
+    "sidebar:nav": [],
+  });
+
+  public readonly playActionProviders: Array<
+    (gameId: string) => Promise<PlayAction[]> | PlayAction[]
+  > = [];
+  public readonly gameMenuItems = reactive<GameMenuItem[]>([]);
+  public readonly sidebarItems = reactive<SidebarItem[]>([]);
+  public readonly topBarItems = reactive<TopBarItem[]>([]);
+  public readonly launchHooks: LaunchHook[] = [];
+
+  public readonly isInitialized = ref(false);
+
+  /**
+   * Register and initialize a client plugin instance.
+   */
+  async registerPlugin(
+    plugin: ClientPlugin,
+    id?: string,
+    commands: string[] = [],
+  ): Promise<void> {
+    const pluginId = id || plugin.metadata?.id || "anonymous-plugin";
+    if (this.plugins.has(pluginId)) {
+      await this.unregisterPlugin(pluginId);
+    }
+
+    // Register the native command allowlist before init so `ctx.system.run`
+    // works. Enforcement lives in the Tauri command layer, not here, so a
+    // plugin cannot bypass it by calling invoke directly.
+    try {
+      await safeInvoke("plugin_register_commands", { pluginId, commands });
+    } catch (err) {
+      console.warn(
+        `Failed to register command allowlist for ${pluginId}:`,
+        err,
+      );
+    }
+
+    const context: ClientPluginContext = {
+      id: pluginId,
+      logger: {
+        info: (msg, ...args) =>
+          console.log(`[Plugin:${pluginId}] ${msg}`, ...args),
+        warn: (msg, ...args) =>
+          console.warn(`[Plugin:${pluginId}] ${msg}`, ...args),
+        error: (msg, ...args) =>
+          console.error(`[Plugin:${pluginId}] ${msg}`, ...args),
+        debug: (msg, ...args) =>
+          console.debug(`[Plugin:${pluginId}] ${msg}`, ...args),
+      },
+      storage: new BrowserLocalStorage(pluginId),
+      registerSlot: (slot, component, options) => {
+        this.slots[slot].push({
+          id: `${pluginId}-${slot}-${this.slots[slot].length}`,
+          pluginId,
+          slot,
+          component,
+          order: options?.order ?? 0,
+          label: options?.label,
+          icon: options?.icon,
+        });
+        this.slots[slot].sort((a, b) => a.order - b.order);
+      },
+      registerPlayAction: (provider) => {
+        this.playActionProviders.push(provider);
+        return () => {
+          const idx = this.playActionProviders.indexOf(provider);
+          if (idx !== -1) this.playActionProviders.splice(idx, 1);
+        };
+      },
+      registerGameMenuItem: (item) => {
+        this.gameMenuItems.push(item);
+        return () => {
+          const idx = this.gameMenuItems.indexOf(item);
+          if (idx !== -1) this.gameMenuItems.splice(idx, 1);
+        };
+      },
+      registerSidebarItem: (item) => {
+        this.sidebarItems.push(item);
+        return () => {
+          const idx = this.sidebarItems.indexOf(item);
+          if (idx !== -1) this.sidebarItems.splice(idx, 1);
+        };
+      },
+      registerTopBarItem: (item) => {
+        this.topBarItems.push(item);
+        return () => {
+          const idx = this.topBarItems.indexOf(item);
+          if (idx !== -1) this.topBarItems.splice(idx, 1);
+        };
+      },
+      registerLaunchHook: (hook) => {
+        this.launchHooks.push(hook);
+        return () => {
+          const idx = this.launchHooks.indexOf(hook);
+          if (idx !== -1) this.launchHooks.splice(idx, 1);
+        };
+      },
+      gameFs: new TauriScopedGameFs(),
+      gameScanner: new TauriScopedGameScanner(),
+      serverWs: new TauriPluginWebSocket(),
+      system: {
+        run: (
+          bin: string,
+          args?: string[],
+          options?: { cwd?: string; timeoutMs?: number },
+        ) =>
+          safeInvoke<CommandResult>(
+            "plugin_system_run",
+            {
+              pluginId,
+              bin,
+              args,
+              cwd: options?.cwd,
+              timeoutMs: options?.timeoutMs,
+            },
+            {
+              code: 1,
+              stdout: "",
+              stderr: "Host native execution not available in browser mode",
+            },
+          ),
+      },
+      serverRequest: <T>(method: HttpMethod, path = "", body?: unknown) =>
+        safeInvoke<T>("plugin_request", {
+          pluginId,
+          method,
+          path,
+          body,
+        }),
+    };
+
+    try {
+      await plugin.init(context);
+      this.plugins.set(pluginId, plugin);
+      console.log(`Initialized client plugin: ${pluginId}`);
+    } catch (e) {
+      console.error(`Failed to initialize client plugin ${pluginId}:`, e);
+    }
+  }
+
+  async unregisterPlugin(pluginId: string): Promise<void> {
+    const plugin = this.plugins.get(pluginId);
+    if (plugin) {
+      if (plugin.teardown) {
+        try {
+          await plugin.teardown();
+        } catch (e) {
+          console.error(`Error during plugin teardown for ${pluginId}:`, e);
+        }
+      }
+      this.plugins.delete(pluginId);
+    }
+
+    // Drop the native command allowlist for this plugin.
+    await safeInvoke("plugin_register_commands", {
+      pluginId,
+      commands: [],
+    }).catch(() => {
+      // Best effort: the plugin may never have registered a allowlist.
+    });
+
+    // Clean up UI slots registered by this plugin
+    for (const slotName of Object.keys(this.slots) as UISlotName[]) {
+      this.slots[slotName] = this.slots[slotName].filter(
+        (s) => s.pluginId !== pluginId,
+      );
+    }
+  }
+
+  /**
+   * Load client plugin bundle from a URL (e.g. served by Drop server).
+   */
+  async loadFromUrl(
+    pluginId: string,
+    bundleUrl: string,
+    cssUrl?: string,
+    commands: string[] = [],
+  ): Promise<void> {
+    if (cssUrl) {
+      const link = document.createElement("link");
+      link.rel = "stylesheet";
+      link.href = cssUrl;
+      link.dataset.pluginId = pluginId;
+      document.head.appendChild(link);
+    }
+
+    const mod = await import(/* @vite-ignore */ bundleUrl);
+    const candidates: Array<ClientPlugin | undefined> = [
+      mod.default,
+      mod.plugin,
+    ];
+    const pluginExport = candidates.find((candidate) => candidate?.init);
+
+    if (!pluginExport) {
+      throw new Error(
+        `Module at ${bundleUrl} does not export a valid ClientPlugin`,
+      );
+    }
+
+    await this.registerPlugin(pluginExport, pluginId, commands);
+  }
+
+  /**
+   * Query all registered Play Actions for a given game.
+   */
+  async getPlayActions(gameId: string): Promise<PlayAction[]> {
+    const actions: PlayAction[] = [];
+    for (const provider of this.playActionProviders) {
+      try {
+        const result = await provider(gameId);
+        actions.push(...result);
+      } catch (err) {
+        console.error(
+          `Error querying play action provider for game ${gameId}:`,
+          err,
+        );
+      }
+    }
+    return actions;
+  }
+
+  /**
+   * Playnite-style Game Launch Pipeline Coordinator.
+   * Executes pre-launch hooks sorted by stage and priority.
+   * If any pre-launch hook aborts, completed stages are rolled back in reverse order.
+   * If launch succeeds, executes post-exit cleanup hooks.
+   */
+  private sortHooks(stages: LaunchHook["stage"][]): LaunchHook[] {
+    return this.launchHooks
+      .filter((h) => stages.includes(h.stage))
+      .sort((a, b) => {
+        const stageDiff = stages.indexOf(a.stage) - stages.indexOf(b.stage);
+        if (stageDiff !== 0) return stageDiff;
+        return (a.order ?? 0) - (b.order ?? 0);
+      });
+  }
+
+  private rollbackCompletedStages(completedHooks: LaunchHook[]): void {
+    for (let i = completedHooks.length - 1; i >= 0; i--) {
+      const rollbackHook = completedHooks[i];
+      if (!rollbackHook) continue;
+      console.log(`Rolling back stage: ${rollbackHook.stage}`);
+    }
+  }
+
+  private async runPreLaunchPipeline(
+    activePreHooks: LaunchHook[],
+    context: LaunchContext,
+  ): Promise<void> {
+    const completedHooks: LaunchHook[] = [];
+    for (const hook of activePreHooks) {
+      try {
+        await hook.execute(context);
+        completedHooks.push(hook);
+      } catch (error) {
+        console.error(
+          `Pre-launch hook [${hook.stage}] failed. Rolling back completed stages...`,
+          error,
+        );
+        this.rollbackCompletedStages(completedHooks);
+        throw new Error(
+          `Launch aborted during stage '${hook.stage}': ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+          { cause: error },
+        );
+      }
+    }
+  }
+
+  private async runPostExitPipeline(
+    activePostHooks: LaunchHook[],
+    context: LaunchContext,
+  ): Promise<void> {
+    for (const hook of activePostHooks) {
+      try {
+        await hook.execute(context);
+      } catch (postErr) {
+        console.warn(`Post-exit hook [${hook.stage}] warning:`, postErr);
+      }
+    }
+  }
+
+  /**
+   * Playnite-style Game Launch Pipeline Coordinator.
+   * Executes pre-launch hooks sorted by stage and priority.
+   * If any pre-launch hook aborts, completed stages are rolled back in reverse order.
+   * If launch succeeds, executes post-exit cleanup hooks.
+   */
+  async executeLaunchPipeline<T>(
+    context: LaunchContext,
+    launchFn: () => Promise<T>,
+  ): Promise<T> {
+    const preLaunchStages: LaunchHook["stage"][] = [
+      "pre-launch:validate",
+      "pre-launch:prepare",
+      "pre-launch:stage",
+      "pre-launch:network",
+    ];
+
+    const postExitStages: LaunchHook["stage"][] = [
+      "post-exit:cleanup",
+      "post-exit:restore",
+      "post-exit:sync",
+    ];
+
+    await this.runPreLaunchPipeline(this.sortHooks(preLaunchStages), context);
+    const launchResult = await launchFn();
+    await this.runPostExitPipeline(this.sortHooks(postExitStages), context);
+
+    return launchResult;
+  }
+}
+
+// Global Singleton Instance
+export const clientPluginManager = new ClientPluginManager();
diff --git a/desktop/main/internal/plugins/PluginErrorBoundary.vue b/desktop/main/internal/plugins/PluginErrorBoundary.vue
new file mode 100644
index 000000000..4db78f865
--- /dev/null
+++ b/desktop/main/internal/plugins/PluginErrorBoundary.vue
@@ -0,0 +1,37 @@
+<template>
+  <div
+    v-if="hasError"
+    class="inline-flex items-center gap-x-1 text-xs text-red-400 bg-red-950/40 border border-red-500/30 rounded px-2 py-1"
+    :title="errorMessage"
+  >
+    <span class="font-mono text-[10px] font-semibold uppercase"
+      >Plugin Error</span
+    >
+    <span v-if="pluginId" class="text-zinc-400 font-mono text-[10px]"
+      >({{ pluginId }})</span
+    >
+  </div>
+  <slot v-else />
+</template>
+
+<script setup lang="ts">
+import { ref, onErrorCaptured } from "vue";
+
+const props = defineProps<{
+  pluginId?: string;
+}>();
+
+const hasError = ref(false);
+const errorMessage = ref("");
+
+onErrorCaptured((err) => {
+  hasError.value = true;
+  errorMessage.value = err instanceof Error ? err.message : String(err);
+  console.error(
+    `[PluginErrorBoundary] Error in plugin component '${props.pluginId}':`,
+    err,
+  );
+  // Prevent propagating the error to the top-level app error handler
+  return false;
+});
+</script>
diff --git a/desktop/main/internal/plugins/types.ts b/desktop/main/internal/plugins/types.ts
new file mode 100644
index 000000000..8ea4a03a8
--- /dev/null
+++ b/desktop/main/internal/plugins/types.ts
@@ -0,0 +1,192 @@
+export type UISlotName =
+  | "game-detail:actions"
+  | "game-detail:panels"
+  | "game-detail:badges"
+  | "settings:tabs"
+  | "topbar:status"
+  | "sidebar:nav";
+
+export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "ALL";
+
+export interface UISlotRegistration {
+  id: string;
+  pluginId: string;
+  slot: UISlotName;
+  component: unknown;
+  order: number;
+  label?: string;
+  icon?: string;
+}
+
+export interface LaunchContext {
+  gameId: string;
+  gameTitle: string;
+  gameDir: string;
+  actionId?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export type LaunchStage =
+  | "pre-launch:validate"
+  | "pre-launch:prepare"
+  | "pre-launch:stage"
+  | "pre-launch:network"
+  | "launch"
+  | "post-exit:cleanup"
+  | "post-exit:restore"
+  | "post-exit:sync";
+
+export interface LaunchHook {
+  stage: LaunchStage;
+  order?: number;
+  execute: (ctx: LaunchContext) => Promise<void> | void;
+}
+
+export interface PlayAction {
+  id: string;
+  name: string;
+  icon?: string;
+  isDefault?: boolean;
+  execute: (context: LaunchContext) => Promise<void> | void;
+}
+
+export interface GameMenuItem {
+  id: string;
+  label: string;
+  icon?: string;
+  execute: (gameId: string) => Promise<void> | void;
+}
+
+export interface SidebarItem {
+  id: string;
+  title: string;
+  icon?: string;
+  type: "button" | "view";
+  progressValue?: number;
+  activated?: () => void;
+  component?: unknown;
+}
+
+export interface TopBarItem {
+  id: string;
+  title: string;
+  icon?: string;
+  component?: unknown;
+  activated?: () => void;
+}
+
+export interface ScopedGameFs {
+  readFile(gameId: string, relativePath: string): Promise<Uint8Array>;
+  writeFile(
+    gameId: string,
+    relativePath: string,
+    data: Uint8Array | string,
+  ): Promise<void>;
+  backupFile(gameId: string, relativePath: string): Promise<string>;
+  restoreFile(gameId: string, relativePath: string): Promise<void>;
+  fileExists(gameId: string, relativePath: string): Promise<boolean>;
+  deleteFile(gameId: string, relativePath: string): Promise<void>;
+}
+
+export interface AntiCheatReport {
+  detected: boolean;
+  reason?: string;
+  provider?: string;
+  binaries?: string[];
+  files?: string[];
+}
+
+export interface ScopedGameScanner {
+  scanExecutables(
+    gameId: string,
+  ): Promise<Array<{ relativePath: string; sha256: string; size: number }>>;
+  checkAntiCheat(gameId: string): Promise<AntiCheatReport>;
+}
+
+export interface ClientPluginStorage {
+  get<T>(key: string): Promise<T | null>;
+  set<T>(key: string, value: T): Promise<void>;
+  delete(key: string): Promise<void>;
+  listKeys(): Promise<string[]>;
+}
+
+export interface ClientPluginWebSocket {
+  send(channel: string, data: unknown): Promise<unknown>;
+  subscribe(channel: string, listener: (data: unknown) => void): () => void;
+}
+
+/** Result of a native command run through the client host. */
+export interface CommandResult {
+  code: number;
+  stdout: string;
+  stderr: string;
+}
+
+export interface CommandOptions {
+  cwd?: string;
+  timeoutMs?: number;
+}
+
+/**
+ * Native command execution for client plugins. The host runs the binary
+ * directly (no shell) and enforces the per-plugin allowlist registered from
+ * `manifest.client.commands`.
+ */
+export interface ClientPluginSystem {
+  run(
+    bin: string,
+    args?: string[],
+    options?: CommandOptions,
+  ): Promise<CommandResult>;
+}
+
+export interface ClientPluginContext {
+  id: string;
+  logger: {
+    info(msg: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    error(msg: string, ...args: unknown[]): void;
+    debug(msg: string, ...args: unknown[]): void;
+  };
+  storage: ClientPluginStorage;
+  registerSlot(
+    slot: UISlotName,
+    component: unknown,
+    options?: { order?: number; label?: string; icon?: string },
+  ): void;
+  registerPlayAction(
+    provider: (gameId: string) => Promise<PlayAction[]> | PlayAction[],
+  ): () => void;
+  registerGameMenuItem(item: GameMenuItem): () => void;
+  registerSidebarItem(item: SidebarItem): () => void;
+  registerTopBarItem(item: TopBarItem): () => void;
+  registerLaunchHook(hook: LaunchHook): () => void;
+  gameFs: ScopedGameFs;
+  gameScanner: ScopedGameScanner;
+  serverWs: ClientPluginWebSocket;
+  /** Native command execution. Requires the `system:command` capability. */
+  system: ClientPluginSystem;
+  /**
+   * Call this plugin's own server-side REST routes through the desktop host.
+   * The webview cannot reach the Drop server directly, so the host proxies the
+   * request. `path` is relative to `/api/v1/plugins/<pluginId>`.
+   */
+  serverRequest<T = unknown>(
+    method: HttpMethod,
+    path?: string,
+    body?: unknown,
+  ): Promise<T>;
+}
+
+export interface ClientPlugin {
+  metadata?: {
+    id: string;
+    name: string;
+    version: string;
+    description?: string;
+    author?: string;
+    category?: string;
+  };
+  init(ctx: ClientPluginContext): Promise<void> | void;
+  teardown?(): Promise<void> | void;
+}
diff --git a/desktop/main/pages/library/[id]/index.vue b/desktop/main/pages/library/[id]/index.vue
index 498078739..d58566cde 100644
--- a/desktop/main/pages/library/[id]/index.vue
+++ b/desktop/main/pages/library/[id]/index.vue
@@ -6,6 +6,8 @@
       <img
         :src="bannerUrl"
         class="w-full h-[24rem] object-cover blur-sm scale-105"
+        alt=""
+        aria-hidden="true"
       />
       <div
         class="absolute inset-0 bg-gradient-to-t from-zinc-900 via-zinc-900/80 to-transparent opacity-90"
@@ -22,7 +24,13 @@
         >
           {{ game.mName }}
         </h1>
-        <div class="relative" v-if="status.type === 'Installed' && status.install_type.type != InstalledType.PartiallyInstalled">
+        <div
+          v-if="
+            status.type === 'Installed' &&
+            status.install_type.type != InstalledType.PartiallyInstalled
+          "
+          class="relative"
+        >
           <div
             v-if="!version?.userConfiguration?.enableUpdates"
             class="absolute mt-1 inline-flex items-center gap-x-1 text-xs text-zinc-400"
@@ -52,19 +60,24 @@
           >
             Update available <ArrowDownTrayIcon class="size-3 text-blue-600" />
           </div>
+          <div class="mt-2 flex items-center gap-x-2">
+            <PluginSlot name="game-detail:badges" :context="{ game, status }" />
+          </div>
         </div>
 
         <div class="mt-8 flex flex-row gap-x-4 items-stretch">
           <!-- Do not add scale animations to this: https://stackoverflow.com/a/35683068 -->
           <GameStatusButton
+            :status="status"
+            :play-actions="pluginPlayActions"
             @install="() => installFlow()"
             @launch="() => launch()"
+            @play-action="(action) => executeCustomPlayAction(action)"
             @queue="() => queue()"
             @uninstall="() => uninstall()"
             @kill="() => kill()"
             @options="() => (configureModalOpen = true)"
             @resume="() => resumeDownload()"
-            :status="status"
           />
           <button
             v-if="status.type === 'Installed' && status.update_available"
@@ -85,17 +98,38 @@
             <BuildingStorefrontIcon class="mr-2 size-5" aria-hidden="true" />
             Store
           </NuxtLink>
+
+          <!-- Plugin Slot: Game Detail Actions (e.g. Multiplayer Button, Mod Manager) -->
+          <PluginSlot name="game-detail:actions" :context="{ game, status }" />
+
+          <!--
+            Generic extension hint: an installed game with no plugin-provided
+            actions advertises that extra capabilities (multiplayer, mods, ...)
+            require installing an extension.
+          -->
+          <button
+            v-if="status.type === 'Installed' && !hasPluginActions"
+            type="button"
+            class="transition-transform duration-300 hover:scale-105 active:scale-95 inline-flex items-center gap-x-2 rounded-md bg-zinc-800/50 px-6 font-semibold text-white shadow-xl backdrop-blur-sm hover:bg-zinc-800/80 uppercase font-display"
+            @click="extensionsPromptOpen = true"
+          >
+            <UserGroupIcon class="size-5" aria-hidden="true" />
+            Multiplayer
+          </button>
         </div>
       </div>
 
       <!-- Main content -->
       <div class="mt-8 w-full bg-zinc-900 px-8">
+        <!-- Plugin Slot: Game Detail Panels -->
+        <PluginSlot name="game-detail:panels" :context="{ game, status }" />
+
         <div class="grid grid-cols-[2fr,1fr] gap-8">
           <div class="space-y-6">
             <div class="bg-zinc-800/50 rounded-xl p-6 backdrop-blur-sm">
               <div
-                v-html="htmlDescription"
                 class="prose prose-invert prose-blue overflow-y-auto custom-scrollbar max-w-none"
+                v-html="htmlDescription"
               ></div>
             </div>
           </div>
@@ -110,23 +144,26 @@
                   <div
                     class="relative aspect-video rounded-lg overflow-hidden cursor-pointer group"
                   >
-                    <div
-                      class="absolute inset-0"
+                    <TransitionGroup name="slide" tag="div" class="h-full">
+                      <img
+                        v-for="(url, index) in game.mImageCarouselObjectIds"
+                        v-show="index === currentImageIndex"
+                        :key="index"
+                        :src="useObject(url)"
+                        class="absolute inset-0 w-full h-full object-cover"
+                        :alt="`${game.mName} screenshot ${index + 1}`"
+                      />
+                    </TransitionGroup>
+                    <button
+                      type="button"
+                      class="absolute inset-0 w-full h-full"
+                      :aria-label="`Open image ${currentImageIndex + 1} fullscreen`"
                       @click="
                         fullscreenImage =
-                          game.mImageCarouselObjectIds[currentImageIndex]
+                          game.mImageCarouselObjectIds[currentImageIndex] ??
+                          null
                       "
-                    >
-                      <TransitionGroup name="slide" tag="div" class="h-full">
-                        <img
-                          v-for="(url, index) in game.mImageCarouselObjectIds"
-                          :key="index"
-                          :src="useObject(url)"
-                          class="absolute inset-0 w-full h-full object-cover"
-                          v-show="index === currentImageIndex"
-                        />
-                      </TransitionGroup>
-                    </div>
+                    ></button>
 
                     <div
                       class="absolute inset-0 flex items-center justify-between px-4 opacity-0 group-hover:opacity-100 transition-opacity pointer-events-none"
@@ -134,8 +171,9 @@
                       <div class="pointer-events-auto">
                         <button
                           v-if="game.mImageCarouselObjectIds.length > 1"
-                          @click.stop="previousImage()"
+                          type="button"
                           class="p-2 rounded-full bg-zinc-900/50 text-zinc-100 hover:bg-zinc-900/80 transition-all duration-300 hover:scale-110"
+                          @click.stop="previousImage()"
                         >
                           <ChevronLeftIcon class="size-5" />
                         </button>
@@ -143,8 +181,9 @@
                       <div class="pointer-events-auto">
                         <button
                           v-if="game.mImageCarouselObjectIds.length > 1"
-                          @click.stop="nextImage()"
+                          type="button"
                           class="p-2 rounded-full bg-zinc-900/50 text-zinc-100 hover:bg-zinc-900/80 transition-all duration-300 hover:scale-110"
+                          @click.stop="nextImage()"
                         >
                           <ChevronRightIcon class="size-5" />
                         </button>
@@ -168,13 +207,14 @@
                     <button
                       v-for="(_, index) in game.mImageCarouselObjectIds"
                       :key="index"
-                      @click.stop="currentImageIndex = index"
+                      type="button"
                       class="w-1.5 h-1.5 rounded-full transition-all"
                       :class="[
                         currentImageIndex === index
                           ? 'bg-zinc-100 scale-125'
                           : 'bg-zinc-600 hover:bg-zinc-500',
                       ]"
+                      @click.stop="currentImageIndex = index"
                     />
                   </div>
                 </div>
@@ -216,7 +256,7 @@
 
       <div class="space-y-6">
         <div v-if="versionOptions && versionOptions.length > 0">
-          <Listbox as="div" v-model="installVersionIndex">
+          <Listbox v-model="installVersionIndex" as="div">
             <ListboxLabel class="block text-sm/6 font-medium text-zinc-100"
               >Version</ListboxLabel
             >
@@ -288,9 +328,9 @@
                   class="absolute z-10 mt-1 max-h-60 w-full overflow-auto rounded-md bg-zinc-900 py-1 text-base shadow-lg ring-1 ring-black ring-opacity-5 focus:outline-none sm:text-sm"
                 >
                   <ListboxOption
+                    v-slot="{ active, selected }"
                     as="template"
                     :value="-1"
-                    v-slot="{ active, selected }"
                   >
                     <li
                       :class="[
@@ -321,11 +361,11 @@
                   </ListboxOption>
 
                   <ListboxOption
-                    as="template"
                     v-for="(version, versionIdx) in versionOptions"
                     :key="version.versionId"
-                    :value="versionIdx"
                     v-slot="{ active, selected }"
+                    as="template"
+                    :value="versionIdx"
                   >
                     <li
                       :class="[
@@ -376,7 +416,7 @@
           </div>
         </div>
         <div v-else class="w-full flex items-center justify-center p-4">
-          <div role="status">
+          <output aria-label="Loading">
             <svg
               aria-hidden="true"
               class="w-7 h-7 text-transparent animate-spin fill-white"
@@ -394,12 +434,12 @@
               />
             </svg>
             <span class="sr-only">Loading...</span>
-          </div>
+          </output>
         </div>
         <div v-if="installDirs">
           <InstallDirectorySelector
-            :install-dirs="installDirs"
             v-model="installDir"
+            :install-dirs="installDirs"
           />
         </div>
         <div
@@ -417,7 +457,7 @@
               to automatically queue for download.
             </p>
           </div>
-          <ul role="list" class="mt-2 divide-y divide-white/5">
+          <ul class="mt-2 divide-y divide-white/5">
             <li
               v-for="content in currentVersionOption.requiredContent"
               :key="content.versionId"
@@ -437,6 +477,7 @@
                 <div class="min-w-0 flex-auto">
                   <p class="text-sm/6 font-semibold text-white">
                     <button
+                      type="button"
                       @click="
                         () =>
                           (installDepsDisabled[content.versionId] =
@@ -492,19 +533,19 @@
     </template>
     <template #buttons>
       <LoadingButton
-        @click="() => install()"
         :disabled="!(versionOptions && versionOptions.length > 0)"
         :loading="installLoading"
         type="submit"
         class="ml-2 w-full sm:w-fit"
+        @click="() => install()"
       >
         Install
       </LoadingButton>
       <button
+        ref="cancelButtonRef"
         type="button"
         class="mt-3 inline-flex w-full justify-center rounded-md bg-zinc-800 px-3 py-2 text-sm font-semibold text-zinc-100 shadow-sm ring-1 ring-inset ring-zinc-700 hover:bg-zinc-900 sm:mt-0 sm:w-auto"
         @click="installFlowOpen = false"
-        ref="cancelButtonRef"
       >
         Cancel
       </button>
@@ -528,8 +569,9 @@
       </div>
 
       <ol class="space-y-2">
-        <li v-for="(launchData, launchIdx) in launchOptions!">
+        <li v-for="(launchData, launchIdx) in launchOptions!" :key="launchIdx">
           <button
+            type="button"
             class="transition w-full rounded-sm bg-zinc-800 inline-flex items-center text-sm py-2 px-3 gap-x-2 text-zinc-100 hover:text-zinc-300 hover:bg-zinc-700"
             @click="() => launchIndex(launchIdx)"
           >
@@ -543,10 +585,10 @@
     </template>
     <template #buttons>
       <button
+        ref="cancelButtonRef"
         type="button"
         class="mt-3 inline-flex w-full justify-center rounded-md bg-zinc-800 px-3 py-2 text-sm font-semibold text-zinc-100 shadow-sm ring-1 ring-inset ring-zinc-700 hover:bg-zinc-900 sm:mt-0 sm:w-auto"
         @click="launchOptions = undefined"
-        ref="cancelButtonRef"
       >
         Cancel
       </button>
@@ -570,6 +612,15 @@
     :game-id="game.id"
   />
 
+  <GameSetupModal
+    v-if="installedData"
+    v-model="setupModalOpen"
+    :game-id="game.id"
+    :game-name="game.mName"
+    @play="() => launch()"
+    @fallback="() => launchIndex(0)"
+  />
+
   <Transition
     enter="transition ease-out duration-300"
     enter-from="opacity-0"
@@ -581,30 +632,37 @@
     <div
       v-if="fullscreenImage"
       class="fixed inset-0 z-50 bg-black/95 flex items-center justify-center"
-      @click="fullscreenImage = null"
     >
+      <button
+        type="button"
+        class="absolute inset-0"
+        aria-label="Close image viewer"
+        @click="fullscreenImage = null"
+      ></button>
       <div
-        class="relative w-full h-full flex items-center justify-center"
-        @click.stop
+        class="relative w-full h-full flex items-center justify-center pointer-events-none"
       >
         <button
-          class="absolute top-4 right-4 p-2 rounded-full bg-zinc-900/50 text-zinc-100 hover:bg-zinc-900 transition-colors"
-          @click.stop="fullscreenImage = null"
+          type="button"
+          class="absolute top-4 right-4 p-2 rounded-full bg-zinc-900/50 text-zinc-100 hover:bg-zinc-900 transition-colors pointer-events-auto"
+          @click="fullscreenImage = null"
         >
           <XMarkIcon class="size-6" />
         </button>
 
         <button
           v-if="game.mImageCarouselObjectIds.length > 1"
-          @click.stop="previousImage()"
-          class="absolute left-4 p-3 rounded-full bg-zinc-900/50 text-zinc-100 hover:bg-zinc-900 transition-colors"
+          type="button"
+          class="absolute left-4 p-3 rounded-full bg-zinc-900/50 text-zinc-100 hover:bg-zinc-900 transition-colors pointer-events-auto"
+          @click="previousImage()"
         >
           <ChevronLeftIcon class="size-6" />
         </button>
         <button
           v-if="game.mImageCarouselObjectIds.length > 1"
-          @click.stop="nextImage()"
-          class="absolute right-4 p-3 rounded-full bg-zinc-900/50 text-zinc-100 hover:bg-zinc-900 transition-colors"
+          type="button"
+          class="absolute right-4 p-3 rounded-full bg-zinc-900/50 text-zinc-100 hover:bg-zinc-900 transition-colors pointer-events-auto"
+          @click="nextImage()"
         >
           <ChevronRightIcon class="size-6" />
         </button>
@@ -612,8 +670,7 @@
         <TransitionGroup
           name="slide"
           tag="div"
-          class="w-full h-full flex items-center justify-center"
-          @click.stop
+          class="w-full h-full flex items-center justify-center pointer-events-auto"
         >
           <img
             v-for="(url, index) in game.mImageCarouselObjectIds"
@@ -626,7 +683,7 @@
         </TransitionGroup>
 
         <div
-          class="absolute bottom-4 left-1/2 -translate-x-1/2 px-4 py-2 rounded-full bg-zinc-900/50 backdrop-blur-sm"
+          class="absolute bottom-4 left-1/2 -translate-x-1/2 px-4 py-2 rounded-full bg-zinc-900/50 backdrop-blur-sm pointer-events-auto"
         >
           <p class="text-zinc-100 text-sm font-medium">
             {{ currentImageIndex + 1 }} /
@@ -641,6 +698,45 @@
     v-if="dependencyRequiredModal"
     v-model="dependencyRequiredModal"
   />
+
+  <ModalTemplate v-model="extensionsPromptOpen">
+    <template #default>
+      <div class="sm:flex sm:items-start">
+        <div class="mt-3 text-center sm:mt-0 sm:text-left">
+          <h3 class="text-base font-semibold text-zinc-100">
+            Extend {{ game.mName }}
+          </h3>
+          <div class="mt-2 space-y-2">
+            <p class="text-sm text-zinc-400">
+              This game has no extensions installed. Optional features such as
+              multiplayer are provided by Drop plugins.
+            </p>
+            <p class="text-sm text-zinc-400">
+              Open the Plugin Manager to browse the registry or install a
+              <code class="font-mono">.dropplugin</code> bundle.
+            </p>
+          </div>
+        </div>
+      </div>
+    </template>
+    <template #buttons>
+      <NuxtLink
+        to="/settings/plugins"
+        class="ml-2 inline-flex w-full justify-center rounded-md bg-blue-600 px-3 py-2 text-sm font-semibold text-white shadow-sm hover:bg-blue-700 sm:w-auto"
+        @click="extensionsPromptOpen = false"
+      >
+        Open Plugin Manager
+      </NuxtLink>
+      <button
+        ref="cancelButtonRef"
+        type="button"
+        class="mt-3 inline-flex w-full justify-center rounded-md bg-zinc-800 px-3 py-2 text-sm font-semibold text-zinc-100 shadow-sm ring-1 ring-inset ring-zinc-700 hover:bg-zinc-900 sm:mt-0 sm:w-auto"
+        @click="extensionsPromptOpen = false"
+      >
+        Close
+      </button>
+    </template>
+  </ModalTemplate>
 </template>
 
 <script setup lang="ts">
@@ -654,7 +750,6 @@ import {
 import {
   CheckIcon,
   ChevronUpDownIcon,
-  WrenchIcon,
   ChevronLeftIcon,
   ChevronRightIcon,
   XMarkIcon,
@@ -663,11 +758,13 @@ import {
   PlayIcon,
   InformationCircleIcon,
 } from "@heroicons/vue/20/solid";
-import { BuildingStorefrontIcon } from "@heroicons/vue/24/outline";
+import {
+  BuildingStorefrontIcon,
+  UserGroupIcon,
+} from "@heroicons/vue/24/outline";
 import {
   ArrowDownTrayIcon,
   CheckCircleIcon,
-  MapPinIcon,
   MinusIcon,
   ServerIcon,
   XCircleIcon,
@@ -675,12 +772,26 @@ import {
 import { invoke } from "@tauri-apps/api/core";
 import { micromark } from "micromark";
 import { InstalledType } from "~/types";
+import { usePlayActions, usePluginSlots } from "~/composables/usePlugins";
+import { clientPluginManager } from "~/internal/plugins/ClientPluginManager";
+import type { PlayAction } from "~/internal/plugins/types";
 
 const route = useRoute();
 const router = useRouter();
-const id = route.params.id.toString();
+const id = route.params.id?.toString() ?? "";
+
+const { actions: pluginPlayActions } = usePlayActions(() => id);
+const pluginSlotActions = usePluginSlots("game-detail:actions");
+const hasPluginActions = computed(
+  () =>
+    pluginPlayActions.value.length > 0 || pluginSlotActions.value.length > 0,
+);
+const extensionsPromptOpen = ref(false);
 
 const { game, status, version } = await useGame(id);
+const installedData = computed(() =>
+  status.value?.type === "Installed" ? status.value : undefined,
+);
 
 const bannerUrl = await useObject(game.mBannerObjectId);
 
@@ -692,6 +803,7 @@ const installDirs = ref<undefined | Array<string>>();
 const currentImageIndex = ref(0);
 
 const configureModalOpen = ref(false);
+const setupModalOpen = ref(false);
 
 async function installFlow() {
   installFlowOpen.value = true;
@@ -722,6 +834,7 @@ async function install() {
     installLoading.value = true;
     const versionOption =
       versionOptions.value[Math.max(installVersionIndex.value, 0)];
+    if (!versionOption) throw new Error("Version option not found");
     const isLatest = installVersionIndex.value == -1;
 
     const games = [
@@ -756,6 +869,7 @@ const currentVersionOption = computed(
 function formatVersionOptionText(index: number) {
   if (!versionOptions.value) return undefined;
   const versionOption = versionOptions.value[Math.max(index, 0)];
+  if (!versionOption) return undefined;
   const template = `${versionOption.displayName || versionOption.versionPath} on ${versionOption.platform}, ${formatKilobytes(versionOption.size.installSize / 1024)}B`;
   if (index == -1) {
     return `Latest (${template})`;
@@ -779,7 +893,7 @@ async function launch() {
     status.value.type == "Installed" &&
     status.value.install_type.type == InstalledType.SetupRequired
   ) {
-    await launchIndex(0);
+    setupModalOpen.value = true;
     return;
   }
   try {
@@ -810,13 +924,52 @@ const dependencyRequiredModal = ref<
   { gameId: string; versionId: string } | undefined
 >(undefined);
 
-async function launchIndex(index: number) {
+async function executeCustomPlayAction(action: PlayAction) {
+  const gameDir =
+    status.value?.type === "Installed" ? status.value.install_dir : "";
+  const launchContext = {
+    gameId: game.id,
+    gameTitle: game.mName,
+    gameDir,
+    actionId: action.id,
+  };
+  try {
+    await action.execute(launchContext);
+  } catch (err) {
+    createModal(
+      ModalType.Notification,
+      {
+        title: `Action "${action.name}" failed`,
+        description: `Drop encountered an error: ${err}`,
+        buttonText: "Close",
+      },
+      (e, c) => c(),
+    );
+  }
+}
+
+async function launchIndex(index: number, actionId?: string) {
   launchOptions.value = undefined;
   try {
-    const result = await invoke<LaunchResult>("launch_game", {
-      id: game.id,
-      index,
-    });
+    const gameDir =
+      status.value?.type === "Installed" ? status.value.install_dir : "";
+    const launchContext = {
+      gameId: game.id,
+      gameTitle: game.mName,
+      gameDir,
+      actionId,
+    };
+
+    const result = await clientPluginManager.executeLaunchPipeline(
+      launchContext,
+      async () => {
+        return await invoke<LaunchResult>("launch_game", {
+          id: game.id,
+          index,
+        });
+      },
+    );
+
     if (result.result == "InstallRequired") {
       dependencyRequiredModal.value = {
         gameId: result.data[0],
@@ -873,6 +1026,15 @@ function previousImage() {
 }
 
 const fullscreenImage = ref<string | null>(null);
+
+// Window-level Escape keeps the overlay divs free of interactive handlers.
+function onViewerKeydown(event: KeyboardEvent) {
+  if (event.key === "Escape" && fullscreenImage.value) {
+    fullscreenImage.value = null;
+  }
+}
+onMounted(() => window.addEventListener("keydown", onViewerKeydown));
+onUnmounted(() => window.removeEventListener("keydown", onViewerKeydown));
 </script>
 
 <style scoped>
diff --git a/desktop/main/pages/settings.vue b/desktop/main/pages/settings.vue
index f4db560d4..18ef6774d 100644
--- a/desktop/main/pages/settings.vue
+++ b/desktop/main/pages/settings.vue
@@ -7,7 +7,7 @@
     </div>
     <div class="mt-5 flex flex-row gap-12">
       <nav class="flex flex-col" aria-label="Sidebar">
-        <ul role="list" class="-mx-2 space-y-1">
+        <ul class="-mx-2 space-y-1">
           <li v-for="(item, itemIdx) in navigation" :key="item.prefix">
             <NuxtLink
               :href="item.route"
@@ -43,16 +43,12 @@
 <script setup lang="ts">
 import {
   ArrowDownTrayIcon,
-  CubeIcon,
   HomeIcon,
   RectangleGroupIcon,
   BugAntIcon,
 } from "@heroicons/vue/16/solid";
-import type { Component } from "vue";
-import type { NavigationItem } from "~/types";
-import { platform } from "@tauri-apps/plugin-os";
 import { invoke } from "@tauri-apps/api/core";
-import { UserIcon } from "@heroicons/vue/20/solid";
+import { UserIcon, PuzzlePieceIcon } from "@heroicons/vue/20/solid";
 
 const systemData = await invoke<{
   clientId: string;
@@ -112,6 +108,12 @@ const navigation = computed(() => [
     prefix: "/settings/downloads",
     icon: ArrowDownTrayIcon,
   },
+  {
+    label: "Plugins",
+    route: "/settings/plugins",
+    prefix: "/settings/plugins",
+    icon: PuzzlePieceIcon,
+  },
   ...(appState.value!.umuState !== "NotNeeded"
     ? [
         {
@@ -140,8 +142,6 @@ const navigation = computed(() => [
     : []),
 ]);
 
-const currentPlatform = platform();
-
 // Use .value to unwrap the computed ref
 const { currentNavigation } = useCurrentNavigationIndex(navigation.value);
 
diff --git a/desktop/main/pages/settings/plugins.vue b/desktop/main/pages/settings/plugins.vue
new file mode 100644
index 000000000..a92e70c90
--- /dev/null
+++ b/desktop/main/pages/settings/plugins.vue
@@ -0,0 +1,497 @@
+<template>
+  <div class="border-b border-zinc-700 py-5 flex items-center justify-between">
+    <div>
+      <h3 class="text-base font-semibold font-display leading-6 text-zinc-100">
+        Plugins &amp; Extensions
+      </h3>
+      <p class="mt-1 text-xs text-zinc-400">
+        Manage installed server and client plugins, virtual mesh networks, and
+        addon capabilities.
+      </p>
+    </div>
+    <button
+      type="button"
+      :disabled="isLoading"
+      class="inline-flex items-center gap-x-1.5 rounded-md bg-zinc-800 px-3 py-2 text-xs font-semibold text-zinc-200 hover:bg-zinc-700 transition disabled:opacity-50"
+      @click="reloadPlugins"
+    >
+      <ArrowPathIcon class="size-4" :class="{ 'animate-spin': isLoading }" />
+      <span>Reload Plugins</span>
+    </button>
+  </div>
+
+  <div
+    v-if="error"
+    class="mt-4 rounded-md bg-red-600/10 p-4 border border-red-500/20"
+  >
+    <div class="flex items-center gap-x-2 text-red-400 text-sm">
+      <XCircleIcon class="size-5 shrink-0" />
+      <span>{{ error }}</span>
+    </div>
+  </div>
+
+  <div
+    class="mt-6 rounded-xl border border-zinc-800 bg-zinc-850/60 p-5 space-y-3"
+  >
+    <div class="flex items-center justify-between">
+      <h4 class="text-sm font-semibold text-zinc-100">
+        Install external bundle
+      </h4>
+      <label
+        class="cursor-pointer inline-flex items-center gap-x-1.5 rounded-md bg-zinc-800 px-3 py-1.5 text-xs font-semibold text-zinc-200 hover:bg-zinc-700 transition"
+      >
+        <span>Upload .dropplugin / JSON</span>
+        <input
+          type="file"
+          accept=".dropplugin,.json"
+          class="sr-only"
+          @change="handleFileUpload"
+        />
+      </label>
+    </div>
+    <p class="text-xs text-zinc-400">
+      Upload a <code class="font-mono">.dropplugin</code> package, or paste
+      bundle JSON:
+    </p>
+    <label for="install-plugin-bundle" class="sr-only"
+      >External plugin bundle JSON</label
+    >
+    <textarea
+      id="install-plugin-bundle"
+      v-model="installJson"
+      rows="4"
+      class="w-full rounded-md bg-zinc-900 border border-zinc-700 px-3 py-2 text-xs font-mono text-zinc-200 focus:outline-none focus:border-purple-500"
+      placeholder='{"manifest":{"id":"my-plugin","name":"My Plugin","version":"1.0.0","apiVersion":2,"capabilities":["routes"]},"entry":"<base64>"}'
+    ></textarea>
+    <button
+      type="button"
+      :disabled="isLoading || !installReady"
+      class="inline-flex items-center rounded-md bg-purple-600 px-3 py-2 text-xs font-semibold text-white hover:bg-purple-500 transition disabled:opacity-50"
+      @click="handleInstallBundle"
+    >
+      Install
+    </button>
+  </div>
+
+  <div class="mt-6 space-y-4">
+    <div
+      v-if="plugins.length === 0 && !isLoading"
+      class="rounded-lg border border-dashed border-zinc-700 p-8 text-center"
+    >
+      <PuzzlePieceIcon class="mx-auto size-12 text-zinc-600 mb-2" />
+      <p class="text-sm font-medium text-zinc-300">No plugins detected</p>
+      <p class="text-xs text-zinc-500 mt-1">
+        Installed plugins will appear here automatically.
+      </p>
+    </div>
+
+    <div
+      v-for="plugin in plugins"
+      :key="plugin.id"
+      class="rounded-xl border border-zinc-800 bg-zinc-850/60 p-5 space-y-4"
+    >
+      <div class="flex items-start justify-between">
+        <div class="space-y-1">
+          <div class="flex items-center gap-x-2">
+            <h4 class="text-base font-semibold text-zinc-100">
+              {{ plugin.name }}
+            </h4>
+            <span
+              v-if="plugin.builtin"
+              class="rounded bg-purple-500/10 border border-purple-500/30 px-2 py-0.5 text-[10px] font-medium text-purple-300 uppercase tracking-wide"
+            >
+              Built-in
+            </span>
+            <span
+              v-else
+              class="rounded bg-blue-500/10 border border-blue-500/30 px-2 py-0.5 text-[10px] font-medium text-blue-300 uppercase tracking-wide"
+            >
+              External
+            </span>
+            <span
+              :class="[
+                plugin.status === 'active'
+                  ? 'bg-emerald-500/10 text-emerald-400 border-emerald-500/30'
+                  : plugin.status === 'disabled'
+                    ? 'bg-zinc-700/20 text-zinc-400 border-zinc-700/30'
+                    : 'bg-red-500/10 text-red-400 border-red-500/30',
+                'rounded border px-2 py-0.5 text-[10px] font-medium uppercase tracking-wide',
+              ]"
+            >
+              {{ plugin.status }}
+            </span>
+          </div>
+          <p class="text-xs font-mono text-zinc-400">
+            {{ plugin.id }} &bull; v{{ plugin.version }}
+            <span v-if="plugin.author"> &bull; by {{ plugin.author }}</span>
+          </p>
+        </div>
+
+        <div class="flex items-center gap-x-3">
+          <button
+            v-if="!plugin.builtin"
+            type="button"
+            :disabled="isLoading"
+            class="text-xs font-medium text-red-400 hover:text-red-300 transition disabled:opacity-50"
+            @click="handleRemovePlugin(plugin.id)"
+          >
+            Remove
+          </button>
+          <Switch
+            :model-value="plugin.status === 'active'"
+            :disabled="isLoading"
+            :class="[
+              plugin.status === 'active' ? 'bg-purple-600' : 'bg-zinc-700',
+              'relative inline-flex h-6 w-11 flex-shrink-0 cursor-pointer rounded-full border-2 border-transparent transition-colors duration-200 ease-in-out',
+            ]"
+            @update:model-value="(val) => handleTogglePlugin(plugin.id, val)"
+          >
+            <span
+              :class="[
+                plugin.status === 'active' ? 'translate-x-5' : 'translate-x-0',
+                'pointer-events-none relative inline-block h-5 w-5 transform rounded-full bg-white shadow ring-0 transition duration-200 ease-in-out',
+              ]"
+            />
+          </Switch>
+        </div>
+      </div>
+
+      <p v-if="plugin.description" class="text-sm text-zinc-300">
+        {{ plugin.description }}
+      </p>
+
+      <div
+        v-if="plugin.capabilities && plugin.capabilities.length > 0"
+        class="pt-2 border-t border-zinc-800 flex items-center gap-x-2"
+      >
+        <span class="text-xs text-zinc-500 flex items-center gap-x-1">
+          <ShieldCheckIcon class="size-3.5 text-zinc-400" />
+          Capabilities:
+        </span>
+        <div class="flex flex-wrap gap-1.5">
+          <span
+            v-for="cap in plugin.capabilities"
+            :key="cap"
+            class="rounded bg-zinc-800 px-2 py-0.5 text-[11px] font-mono text-zinc-300"
+          >
+            {{ cap }}
+          </span>
+        </div>
+      </div>
+    </div>
+  </div>
+
+  <!-- For Developers Section (Playnite-inspired) -->
+  <div
+    class="mt-8 rounded-xl border border-zinc-800 bg-zinc-850/60 p-5 space-y-3"
+  >
+    <div class="flex items-center justify-between">
+      <div>
+        <h4 class="text-sm font-semibold text-zinc-100">
+          For Developers: Load Unpacked Plugin
+        </h4>
+        <p class="text-xs text-zinc-400">
+          Load a development plugin bundle directly from a local path without
+          packaging.
+        </p>
+      </div>
+      <span
+        class="rounded bg-amber-500/10 border border-amber-500/30 px-2 py-0.5 text-[10px] font-medium text-amber-300 uppercase tracking-wide"
+      >
+        Developer Mode
+      </span>
+    </div>
+    <div class="flex gap-x-2">
+      <input
+        v-model="devPluginPath"
+        type="text"
+        aria-label="Development plugin path"
+        class="flex-1 rounded-md bg-zinc-900 border border-zinc-700 px-3 py-2 text-xs font-mono text-zinc-200 focus:outline-none focus:border-purple-500"
+        placeholder="/path/to/my-plugin/dist/client/index.js"
+      />
+      <button
+        type="button"
+        :disabled="isLoading || !devPluginPath.trim()"
+        class="inline-flex items-center rounded-md bg-amber-600 px-3 py-2 text-xs font-semibold text-white hover:bg-amber-500 transition disabled:opacity-50"
+        @click="handleLoadDevPlugin"
+      >
+        Load
+      </button>
+    </div>
+  </div>
+
+  <div class="mt-8 space-y-4">
+    <h4 class="text-sm font-semibold text-zinc-100">Extension Settings</h4>
+    <PluginSlot name="settings:tabs" />
+  </div>
+
+  <!-- Capability Review / Permission Consent Modal -->
+  <div
+    v-if="showConsentModal && pendingInstall"
+    class="fixed inset-0 z-50 flex items-center justify-center bg-black/60 p-4 backdrop-blur-sm"
+  >
+    <div
+      class="w-full max-w-lg rounded-xl border border-zinc-700 bg-zinc-900 p-6 shadow-2xl space-y-4"
+    >
+      <div class="flex items-center gap-x-2 text-purple-400">
+        <ShieldCheckIcon class="size-6" />
+        <h3 class="text-base font-semibold text-zinc-100">
+          Review Plugin Permissions
+        </h3>
+      </div>
+      <p class="text-xs text-zinc-400">
+        <strong class="text-zinc-200">{{
+          pendingInstall.manifest?.name ||
+          pendingInstall.entry ||
+          "Unknown Plugin"
+        }}</strong>
+        (<code>{{ pendingInstall.manifest?.id || "unknown" }}</code> v{{
+          pendingInstall.manifest?.version || "0.0.0"
+        }}) requests the following capabilities:
+      </p>
+      <div
+        class="max-h-60 overflow-y-auto space-y-2 rounded-lg bg-zinc-950 p-3 border border-zinc-800"
+      >
+        <div
+          v-for="cap in pendingInstall.manifest?.capabilities || []"
+          :key="cap"
+          class="flex flex-col text-xs"
+        >
+          <span class="font-mono font-semibold text-purple-300">{{ cap }}</span>
+          <span class="text-zinc-400 text-[11px]">{{
+            CAPABILITY_DESCRIPTIONS[cap] || "Standard plugin capability"
+          }}</span>
+        </div>
+      </div>
+      <div class="flex justify-end gap-x-2 pt-2">
+        <button
+          type="button"
+          class="rounded-md bg-zinc-800 px-3 py-2 text-xs font-semibold text-zinc-300 hover:bg-zinc-700 transition"
+          @click="
+            showConsentModal = false;
+            pendingInstall = null;
+          "
+        >
+          Cancel
+        </button>
+        <button
+          type="button"
+          class="rounded-md bg-purple-600 px-3 py-2 text-xs font-semibold text-white hover:bg-purple-500 transition"
+          @click="confirmInstall(pendingInstall)"
+        >
+          Authorize &amp; Install
+        </button>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { Switch } from "@headlessui/vue";
+import {
+  ArrowPathIcon,
+  PuzzlePieceIcon,
+  ShieldCheckIcon,
+  XCircleIcon,
+} from "@heroicons/vue/20/solid";
+import { invoke } from "@tauri-apps/api/core";
+import { clientPluginManager } from "~/internal/plugins/ClientPluginManager";
+
+const devPluginPath = ref("");
+
+async function handleLoadDevPlugin() {
+  if (!devPluginPath.value.trim()) return;
+  isLoading.value = true;
+  error.value = null;
+  try {
+    const p = devPluginPath.value.trim();
+    await clientPluginManager.loadFromUrl("dev-plugin", p);
+    devPluginPath.value = "";
+  } catch (e) {
+    error.value = `Failed to load dev plugin: ${e}`;
+  } finally {
+    isLoading.value = false;
+  }
+}
+
+export interface PluginItem {
+  id: string;
+  name: string;
+  version: string;
+  description?: string;
+  author?: string;
+  builtin?: boolean;
+  capabilities?: string[];
+  status: "active" | "disabled" | "error";
+  error?: string;
+}
+
+const plugins = ref<PluginItem[]>([]);
+const isLoading = ref(false);
+const error = ref<string | null>(null);
+
+async function fetchPlugins() {
+  isLoading.value = true;
+  error.value = null;
+  try {
+    const res = await invoke<{ plugins: PluginItem[] }>("plugin_request", {
+      pluginId: "",
+      method: "GET",
+      path: "",
+    });
+    plugins.value = res.plugins ?? [];
+  } catch (e) {
+    error.value = (e as string).toString();
+  } finally {
+    isLoading.value = false;
+  }
+}
+
+async function handleTogglePlugin(id: string, enabled: boolean) {
+  isLoading.value = true;
+  error.value = null;
+  try {
+    await invoke("plugin_request", {
+      pluginId: `${id}/state`,
+      method: "PATCH",
+      path: "",
+      body: { enabled },
+    });
+    await fetchPlugins();
+  } catch (e) {
+    error.value = (e as string).toString();
+  } finally {
+    isLoading.value = false;
+  }
+}
+
+async function reloadPlugins() {
+  isLoading.value = true;
+  error.value = null;
+  try {
+    await invoke("plugin_request", {
+      pluginId: "reload",
+      method: "POST",
+      path: "",
+    });
+    await fetchPlugins();
+  } catch (e) {
+    error.value = (e as string).toString();
+  } finally {
+    isLoading.value = false;
+  }
+}
+
+async function handleRemovePlugin(id: string) {
+  isLoading.value = true;
+  error.value = null;
+  try {
+    await invoke("plugin_request", {
+      pluginId: `${id}/bundle`,
+      method: "DELETE",
+      path: "",
+    });
+    await fetchPlugins();
+  } catch (e) {
+    error.value = (e as string).toString();
+  } finally {
+    isLoading.value = false;
+  }
+}
+
+interface InstallPayload {
+  manifest?: {
+    id?: string;
+    name?: string;
+    version?: string;
+    capabilities?: string[];
+  };
+  entry?: string;
+  files?: Record<string, string>;
+  format?: string;
+  signature?: string;
+}
+
+const installJson = ref("");
+const installReady = computed(() => installJson.value.trim().length > 0);
+const showConsentModal = ref(false);
+const pendingInstall = ref<InstallPayload | null>(null);
+
+const CAPABILITY_DESCRIPTIONS: Record<string, string> = {
+  "game:fs":
+    "Confined filesystem access within active game installation directories.",
+  "game:launch-hook":
+    "Execute pre-launch validation and post-exit launch pipeline hooks.",
+  "game:scan": "Scan executables and perform anti-cheat compatibility checks.",
+  "ui:play-action":
+    "Inject custom startup actions and play modes into game launch menus.",
+  "ui:slot": "Contribute UI panels, sidebar tabs, and status badges.",
+  "ui:context-menu": "Add custom action items to game context menus.",
+  "ui:sidebar": "Add items and progress indicators to the client sidebar.",
+  "ui:topbar": "Add status indicators to the top application bar.",
+  "client:storage": "Store client-side settings and metadata.",
+  "client:ws": "Communicate with backend WebSocket channels.",
+  routes: "Register custom HTTP routes on the server.",
+  storage: "Access persistent server storage.",
+  events: "Broadcast and listen to server event bus messages.",
+  network: "Make outbound network requests from the server.",
+  websocket: "Expose real-time WebSocket communication channels.",
+  "system:sidecar": "Execute background system sidecar processes.",
+  "system:command":
+    "Run allowlisted native CLI commands on this device.",
+};
+
+async function handleFileUpload(event: Event) {
+  const input = event.target as HTMLInputElement;
+  const file = input.files?.[0];
+  if (!file) return;
+  installJson.value = await file.text();
+}
+
+function handleInstallBundle() {
+  error.value = null;
+  try {
+    const parsed = JSON.parse(installJson.value) as InstallPayload;
+    if (!parsed?.manifest || (!parsed.entry && !parsed.files)) {
+      throw new Error(
+        'Bundle must contain a "manifest" and either an "entry" or "files" map',
+      );
+    }
+
+    const caps = parsed.manifest.capabilities || [];
+    if (caps.length > 0) {
+      pendingInstall.value = parsed;
+      showConsentModal.value = true;
+    } else {
+      confirmInstall(parsed);
+    }
+  } catch (e) {
+    error.value = (e as string).toString();
+  }
+}
+
+async function confirmInstall(payload: InstallPayload) {
+  isLoading.value = true;
+  error.value = null;
+  showConsentModal.value = false;
+  try {
+    await invoke("plugin_request", {
+      pluginId: "install",
+      method: "POST",
+      path: "",
+      body: payload,
+    });
+    installJson.value = "";
+    pendingInstall.value = null;
+    await fetchPlugins();
+  } catch (e) {
+    error.value = (e as string).toString();
+  } finally {
+    isLoading.value = false;
+  }
+}
+
+onMounted(() => {
+  fetchPlugins();
+});
+</script>
diff --git a/desktop/main/plugins/09.client-plugins.ts b/desktop/main/plugins/09.client-plugins.ts
new file mode 100644
index 000000000..4f9222899
--- /dev/null
+++ b/desktop/main/plugins/09.client-plugins.ts
@@ -0,0 +1,83 @@
+import * as Vue from "vue";
+import { invoke } from "@tauri-apps/api/core";
+import { clientPluginManager } from "~/internal/plugins/ClientPluginManager";
+
+declare global {
+  interface Window {
+    Vue?: unknown;
+  }
+}
+
+if (typeof window !== "undefined") {
+  window.Vue = Vue;
+}
+
+interface RemotePluginInfo {
+  id: string;
+  name: string;
+  version: string;
+  status: "active" | "disabled" | "error";
+  targets?: string[];
+  client?: {
+    entry?: string;
+    css?: string;
+    commands?: string[];
+  };
+}
+
+async function loadRemotePlugin(plugin: RemotePluginInfo): Promise<void> {
+  if (plugin.status !== "active") return;
+  const targets = plugin.targets;
+  if (targets && !targets.includes("client")) return;
+
+  const entry = plugin.client?.entry || "bundle.js";
+  const clientJsUrl = `/api/v1/plugins/${plugin.id}/client/${entry}`;
+  const clientCssUrl = plugin.client?.css
+    ? `/api/v1/plugins/${plugin.id}/client/${plugin.client.css}`
+    : undefined;
+  const commands = Array.isArray(plugin.client?.commands)
+    ? plugin.client.commands
+    : [];
+
+  try {
+    await clientPluginManager.loadFromUrl(
+      plugin.id,
+      clientJsUrl,
+      clientCssUrl,
+      commands,
+    );
+  } catch (loadErr) {
+    console.debug(
+      `Plugin ${plugin.id} has no client bundle or failed to load:`,
+      loadErr,
+    );
+  }
+}
+
+async function fetchRemotePlugins(): Promise<RemotePluginInfo[]> {
+  const res = await invoke<{ plugins: RemotePluginInfo[] }>("plugin_request", {
+    pluginId: "",
+    method: "GET",
+    path: "",
+  }).catch(() => null);
+
+  return res && Array.isArray(res.plugins) ? res.plugins : [];
+}
+
+export default defineNuxtPlugin(async () => {
+  if (clientPluginManager.isInitialized.value) return;
+
+  try {
+    const plugins = await fetchRemotePlugins();
+    for (const plugin of plugins) {
+      await loadRemotePlugin(plugin);
+    }
+  } catch (err) {
+    console.debug(
+      "Could not reach Drop server for client plugin discovery:",
+      err,
+    );
+  } finally {
+    clientPluginManager.isInitialized.value = true;
+  }
+});
diff --git a/desktop/src-tauri/Cargo.lock b/desktop/src-tauri/Cargo.lock
index 8f5eb81eb..6a8ad7988 100644
--- a/desktop/src-tauri/Cargo.lock
+++ b/desktop/src-tauri/Cargo.lock
@@ -1412,6 +1412,7 @@ dependencies = [
  "filetime",
  "futures-core",
  "futures-lite",
+ "futures-util",
  "games",
  "gethostname",
  "hex 0.4.3",
@@ -1442,6 +1443,7 @@ dependencies = [
  "serde_json",
  "serde_with",
  "sha1",
+ "sha2 0.10.9",
  "shared_child",
  "slice-deque",
  "sysinfo 0.36.1",
@@ -4614,6 +4616,7 @@ dependencies = [
  "shell-words",
  "tauri",
  "tauri-plugin-opener",
+ "tempfile",
  "utils",
 ]
 
diff --git a/desktop/src-tauri/Cargo.toml b/desktop/src-tauri/Cargo.toml
index bde7d0fc0..dfbfa276a 100644
--- a/desktop/src-tauri/Cargo.toml
+++ b/desktop/src-tauri/Cargo.toml
@@ -44,6 +44,7 @@ download_manager = { path = "./download_manager", version = "0.1.0" } # download
 filetime = "0.2.25"
 futures-core = "0.3.31"
 futures-lite = "2.6.0"
+futures-util = "0.3.31"
 games = { path = "./games", version = "0.1.0" } # games
 gethostname = "1.0.1"
 hex = "0.4.3"
@@ -79,6 +80,7 @@ schemars = "0.8.22"
 serde_json = "1"
 serde_with = "3.12.0"
 sha1 = "0.10.6"
+sha2 = "0.10.8"
 shared_child = "1.0.1"
 slice-deque = "0.3.0"
 sysinfo = "0.36.1"
@@ -124,7 +126,7 @@ features = ["protocol-asset", "tray-icon", "unstable"]
 
 [dependencies.tokio]
 version = "1.40.0"
-features = ["rt", "signal", "tokio-macros"]
+features = ["rt", "signal", "tokio-macros", "process"]
 
 [dependencies.uuid]
 version = "1.10.0"
diff --git a/desktop/src-tauri/process/Cargo.toml b/desktop/src-tauri/process/Cargo.toml
index c83b6ba01..d00589bc1 100644
--- a/desktop/src-tauri/process/Cargo.toml
+++ b/desktop/src-tauri/process/Cargo.toml
@@ -19,3 +19,6 @@ shell-words = "1.1.1"
 tauri = "*"
 tauri-plugin-opener = "*"
 utils = { path = "../utils", version = "0.1.0" }
+
+[dev-dependencies]
+tempfile = "3"
diff --git a/desktop/src-tauri/process/src/lib.rs b/desktop/src-tauri/process/src/lib.rs
index 05dfc4360..66990f103 100644
--- a/desktop/src-tauri/process/src/lib.rs
+++ b/desktop/src-tauri/process/src/lib.rs
@@ -19,6 +19,7 @@ pub mod compat;
 pub mod error;
 pub mod format;
 mod parser;
+pub mod path_guard;
 pub mod process_handlers;
 pub mod process_manager;
 
diff --git a/desktop/src-tauri/process/src/path_guard.rs b/desktop/src-tauri/process/src/path_guard.rs
new file mode 100644
index 000000000..80265da1e
--- /dev/null
+++ b/desktop/src-tauri/process/src/path_guard.rs
@@ -0,0 +1,264 @@
+use std::fmt;
+use std::fs::{self, File, OpenOptions};
+use std::io::{self, Write};
+use std::path::{Component, Path, PathBuf};
+use std::sync::atomic::{AtomicU64, Ordering};
+
+static TMP_COUNTER: AtomicU64 = AtomicU64::new(0);
+
+#[derive(Debug)]
+pub enum PathGuardError {
+    UnsafePath(String),
+    Io(io::Error),
+}
+
+impl fmt::Display for PathGuardError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            PathGuardError::UnsafePath(msg) => write!(f, "unsafe path: {msg}"),
+            PathGuardError::Io(err) => write!(f, "{err}"),
+        }
+    }
+}
+
+impl std::error::Error for PathGuardError {}
+
+impl From<io::Error> for PathGuardError {
+    fn from(err: io::Error) -> Self {
+        PathGuardError::Io(err)
+    }
+}
+
+fn unsafe_path(detail: impl Into<String>) -> PathGuardError {
+    PathGuardError::UnsafePath(detail.into())
+}
+
+/// Whether `path` currently exists and is a symlink (does not follow it).
+pub fn is_symlink(path: &Path) -> bool {
+    fs::symlink_metadata(path)
+        .map(|meta| meta.file_type().is_symlink())
+        .unwrap_or(false)
+}
+
+fn canonical_root(root: &Path) -> Result<PathBuf, PathGuardError> {
+    fs::canonicalize(root).map_err(|e| {
+        unsafe_path(format!(
+            "cannot resolve install directory {}: {e}",
+            root.display()
+        ))
+    })
+}
+
+/// Resolve `candidate` (relative to `root`) while rejecting absolute paths,
+/// `..`/prefix components, and any existing symlinked component.
+pub fn safe_join(root: &Path, candidate: impl AsRef<Path>) -> Result<PathBuf, PathGuardError> {
+    let root = canonical_root(root)?;
+    let candidate = candidate.as_ref();
+    let mut current = root.clone();
+    for component in candidate.components() {
+        match component {
+            Component::Normal(segment) => {
+                current.push(segment);
+                if is_symlink(&current) {
+                    return Err(unsafe_path(format!(
+                        "refusing to follow symlink {}",
+                        current.display()
+                    )));
+                }
+            }
+            Component::CurDir => {}
+            Component::ParentDir => {
+                return Err(unsafe_path(format!(
+                    "path '{}' must not contain '..'",
+                    candidate.display()
+                )));
+            }
+            Component::RootDir | Component::Prefix(_) => {
+                return Err(unsafe_path(format!(
+                    "path '{}' must be relative to the install directory",
+                    candidate.display()
+                )));
+            }
+        }
+    }
+    Ok(current)
+}
+
+/// Create `candidate` as a directory (and parents) inside `root`, rejecting
+/// symlinked components. Returns the created path.
+pub fn ensure_dir(root: &Path, candidate: impl AsRef<Path>) -> Result<PathBuf, PathGuardError> {
+    let dir = safe_join(root, candidate)?;
+    fs::create_dir_all(&dir)?;
+    if is_symlink(&dir) {
+        return Err(unsafe_path(format!(
+            "refusing to use symlinked directory {}",
+            dir.display()
+        )));
+    }
+    Ok(dir)
+}
+
+fn temp_path_for(target: &Path) -> Result<PathBuf, PathGuardError> {
+    let parent = target
+        .parent()
+        .ok_or_else(|| unsafe_path(format!("path {} has no parent", target.display())))?;
+    let counter = TMP_COUNTER.fetch_add(1, Ordering::Relaxed);
+    let stem = target
+        .file_name()
+        .and_then(|name| name.to_str())
+        .unwrap_or("payload");
+    Ok(parent.join(format!(".{stem}.drop-tmp-{}-{counter}", std::process::id())))
+}
+
+/// Write to a temp file in the destination's directory, then atomically rename
+/// it over the destination so an existing symlink is replaced, not followed.
+fn atomic_replace<F>(target: &Path, fill: F) -> Result<(), PathGuardError>
+where
+    F: FnOnce(&mut File) -> Result<(), PathGuardError>,
+{
+    let parent = target
+        .parent()
+        .ok_or_else(|| unsafe_path(format!("path {} has no parent", target.display())))?;
+    // safe_join already rejected symlinked components; create_dir_all only
+    // creates the (nonexistent) tail.
+    fs::create_dir_all(parent)?;
+    let tmp = temp_path_for(target)?;
+
+    let filled = (|| -> Result<(), PathGuardError> {
+        let mut file = OpenOptions::new().write(true).create_new(true).open(&tmp)?;
+        fill(&mut file)?;
+        file.sync_all()?;
+        Ok(())
+    })();
+
+    if let Err(err) = filled {
+        let _ = fs::remove_file(&tmp);
+        return Err(err);
+    }
+
+    #[cfg(windows)]
+    {
+        if target.exists() {
+            fs::remove_file(target)?;
+        }
+    }
+
+    fs::rename(&tmp, target).map_err(|e| {
+        let _ = fs::remove_file(&tmp);
+        PathGuardError::Io(e)
+    })
+}
+
+/// Write `bytes` to `candidate` inside `root` without following symlinks.
+pub fn write_file(
+    root: &Path,
+    candidate: impl AsRef<Path>,
+    bytes: &[u8],
+) -> Result<(), PathGuardError> {
+    let target = safe_join(root, candidate)?;
+    atomic_replace(&target, |file| {
+        file.write_all(bytes)?;
+        Ok(())
+    })
+}
+
+/// Copy `src` (a trusted local path) to `candidate` inside `root` without
+/// following symlinks at the destination.
+pub fn copy_to(root: &Path, src: &Path, candidate: impl AsRef<Path>) -> Result<(), PathGuardError> {
+    let target = safe_join(root, candidate)?;
+    atomic_replace(&target, |file| {
+        let mut reader = File::open(src)?;
+        std::io::copy(&mut reader, file)?;
+        Ok(())
+    })
+}
+
+/// Remove a regular file (or symlink, which is unlinked, never followed) under
+/// `root`. Missing paths are a no-op.
+pub fn remove_file(root: &Path, candidate: impl AsRef<Path>) -> Result<(), PathGuardError> {
+    let path = safe_join(root, candidate)?;
+    match fs::symlink_metadata(&path) {
+        Ok(meta) if meta.is_dir() && !meta.file_type().is_symlink() => Err(unsafe_path(format!(
+            "refusing to remove directory {} as a file",
+            path.display()
+        ))),
+        Ok(_) => {
+            fs::remove_file(&path)?;
+            Ok(())
+        }
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()),
+        Err(e) => Err(PathGuardError::Io(e)),
+    }
+}
+
+/// Recursively remove a directory under `root`. A symlink is unlinked rather
+/// than traversed. Missing paths are a no-op.
+pub fn remove_dir_all(root: &Path, candidate: impl AsRef<Path>) -> Result<(), PathGuardError> {
+    let path = safe_join(root, candidate)?;
+    match fs::symlink_metadata(&path) {
+        Ok(meta) if meta.file_type().is_symlink() => {
+            fs::remove_file(&path)?;
+            Ok(())
+        }
+        Ok(meta) if meta.is_dir() => {
+            fs::remove_dir_all(&path)?;
+            Ok(())
+        }
+        Ok(_) => {
+            fs::remove_file(&path)?;
+            Ok(())
+        }
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()),
+        Err(e) => Err(PathGuardError::Io(e)),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[cfg(unix)]
+    fn symlink_dir(src: &Path, dst: &Path) {
+        std::os::unix::fs::symlink(src, dst).unwrap();
+    }
+
+    #[test]
+    fn rejects_parent_dir_and_absolute_paths() {
+        let tmp = tempfile::tempdir().unwrap();
+        assert!(safe_join(tmp.path(), "a/b").is_ok());
+        assert!(safe_join(tmp.path(), "../escape").is_err());
+        assert!(safe_join(tmp.path(), "a/../../escape").is_err());
+        assert!(safe_join(tmp.path(), "/etc/passwd").is_err());
+    }
+
+    #[test]
+    fn write_file_publishes_atomically() {
+        let tmp = tempfile::tempdir().unwrap();
+        write_file(tmp.path(), "sub/out.txt", b"hello").unwrap();
+        assert_eq!(fs::read(tmp.path().join("sub/out.txt")).unwrap(), b"hello");
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn refuses_to_write_through_symlinked_destination() {
+        let tmp = tempfile::tempdir().unwrap();
+        let outside = tempfile::tempdir().unwrap();
+        let victim = outside.path().join("victim.txt");
+        fs::write(&victim, b"original").unwrap();
+        symlink_dir(&victim, &tmp.path().join("game.txt"));
+
+        assert!(write_file(tmp.path(), "game.txt", b"pwned").is_err());
+        assert_eq!(fs::read(&victim).unwrap(), b"original");
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn refuses_to_write_through_symlinked_directory() {
+        let tmp = tempfile::tempdir().unwrap();
+        let outside = tempfile::tempdir().unwrap();
+        symlink_dir(outside.path(), &tmp.path().join("linkdir"));
+
+        assert!(write_file(tmp.path(), "linkdir/file.txt", b"pwned").is_err());
+        assert!(!outside.path().join("file.txt").exists());
+    }
+}
diff --git a/desktop/src-tauri/src/lib.rs b/desktop/src-tauri/src/lib.rs
index b5d343594..eea0498bb 100644
--- a/desktop/src-tauri/src/lib.rs
+++ b/desktop/src-tauri/src/lib.rs
@@ -64,6 +64,7 @@ mod collections;
 mod download_manager;
 mod downloads;
 mod games;
+mod plugins;
 mod process;
 mod remote;
 mod scheduler;
@@ -74,6 +75,7 @@ use client::*;
 use download_manager::*;
 use downloads::*;
 use games::*;
+use plugins::*;
 use process::*;
 use remote::*;
 use settings::*;
@@ -225,6 +227,7 @@ pub fn run() {
 
     let app = builder
         .plugin(tauri_plugin_deep_link::init())
+        .manage(PluginCommandAllowlist::default())
         .invoke_handler(tauri::generate_handler![
             // Core utils
             fetch_state,
@@ -245,6 +248,20 @@ pub fn run() {
             gen_drop_url,
             fetch_drop_object,
             check_online,
+            plugin_request,
+            plugin_subscribe,
+            plugin_request_ws,
+            // Client Plugins
+            plugin_game_fs_read,
+            plugin_game_fs_write,
+            plugin_game_fs_backup,
+            plugin_game_fs_restore,
+            plugin_game_fs_exists,
+            plugin_game_fs_delete,
+            plugin_game_scan_executables,
+            plugin_game_check_anticheat,
+            plugin_register_commands,
+            plugin_system_run,
             // Library
             fetch_library,
             fetch_game,
diff --git a/desktop/src-tauri/src/plugins.rs b/desktop/src-tauri/src/plugins.rs
new file mode 100644
index 000000000..8f5536a76
--- /dev/null
+++ b/desktop/src-tauri/src/plugins.rs
@@ -0,0 +1,414 @@
+use std::collections::{HashMap, HashSet};
+use std::fs::{self, File};
+use std::io::{self, Read};
+use std::path::{Path, PathBuf};
+use std::sync::Mutex;
+use std::time::Duration;
+
+use database::borrow_db_checked;
+use process::path_guard;
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+use tauri::State;
+use tokio::process::Command as TokioCommand;
+use walkdir::WalkDir;
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ScannedExecutable {
+    pub relative_path: String,
+    pub sha256: String,
+    pub size: u64,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct AntiCheatReport {
+    pub detected: bool,
+    pub provider: Option<String>,
+    pub files: Vec<String>,
+}
+
+/// Per-plugin allowlist of bare executable names a client plugin may run via
+/// `ctx.system.run`. Populated from `manifest.client.commands` by the host when
+/// a plugin is registered; the Tauri command layer is the enforcement point so
+/// a plugin cannot bypass it from the webview.
+#[derive(Default)]
+pub struct PluginCommandAllowlist(pub Mutex<HashMap<String, HashSet<String>>>);
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CommandOutput {
+    pub code: i32,
+    pub stdout: String,
+    pub stderr: String,
+}
+
+const BLOCKED_COMMANDS: &[&str] = &[
+    // Shells
+    "sh", "bash", "dash", "ash", "zsh", "csh", "tcsh", "fish", "ksh",
+    "cmd", "cmd.exe", "powershell", "powershell.exe", "pwsh", "pwsh.exe",
+    "wscript", "wscript.exe", "cscript", "cscript.exe",
+    // Interpreters & runtimes
+    "python", "python3", "python.exe", "python3.exe", "py", "py.exe",
+    "node", "node.exe", "deno", "deno.exe", "bun", "bun.exe",
+    "perl", "perl.exe", "ruby", "ruby.exe", "php", "php.exe", "lua", "lua.exe",
+    // Network transfer / remote shells
+    "curl", "curl.exe", "wget", "wget.exe",
+    "nc", "ncat", "netcat", "socat", "telnet", "ssh", "scp", "sftp", "ftp",
+    // Privilege escalation / execution
+    "sudo", "su", "doas", "pkexec", "runas", "runas.exe",
+    // Destructive filesystem / partition / system tools
+    "rm", "rmdir", "del", "erase", "dd", "format", "mkfs", "fdisk", "parted",
+    "reg", "reg.exe", "regedit", "regedit.exe", "certutil", "certutil.exe",
+    "bitsadmin", "bitsadmin.exe", "mshta", "mshta.exe", "rundll32", "rundll32.exe",
+];
+
+fn validate_command_name(command: &str) -> Result<(), String> {
+    if command.is_empty() || command.len() > 64 {
+        return Err(format!("invalid command length: '{command}'"));
+    }
+    if command.starts_with('.') || command.starts_with('-') {
+        return Err(format!("command cannot start with '.' or '-': '{command}'"));
+    }
+    if !command
+        .chars()
+        .all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-' || c == '.')
+    {
+        return Err(format!(
+            "command contains disallowed characters (only alphanumeric, _, -, . allowed): '{command}'"
+        ));
+    }
+    let lower = command.to_ascii_lowercase();
+    if BLOCKED_COMMANDS.contains(&lower.as_str()) {
+        return Err(format!(
+            "command '{command}' is blocked for security reasons"
+        ));
+    }
+    Ok(())
+}
+
+/// Register (replace) the allowlisted commands for a plugin.
+#[tauri::command]
+pub fn plugin_register_commands(
+    plugin_id: String,
+    commands: Vec<String>,
+    state: State<'_, PluginCommandAllowlist>,
+) -> Result<(), String> {
+    let mut registry = state
+        .0
+        .lock()
+        .map_err(|_| "plugin command registry poisoned".to_string())?;
+    let entry = registry.entry(plugin_id).or_default();
+    entry.clear();
+    for command in commands {
+        let command = command.trim();
+        if command.is_empty() {
+            continue;
+        }
+        // Only bare executable names are allowed; no paths, so an allowlist
+        // entry cannot be used to traverse to an arbitrary binary.
+        if command.contains('/') || command.contains('\\') {
+            return Err(format!(
+                "allowlisted command must be a bare executable name: {command}"
+            ));
+        }
+        validate_command_name(command)?;
+        entry.insert(command.to_string());
+    }
+    Ok(())
+}
+
+/// Run an allowlisted native command for a plugin. The binary is executed
+/// directly (no shell), so shell metacharacters are never interpreted.
+#[tauri::command]
+pub async fn plugin_system_run(
+    plugin_id: String,
+    bin: String,
+    args: Option<Vec<String>>,
+    cwd: Option<String>,
+    timeout_ms: Option<u64>,
+    state: State<'_, PluginCommandAllowlist>,
+) -> Result<CommandOutput, String> {
+    validate_command_name(&bin)?;
+    {
+        let registry = state
+            .0
+            .lock()
+            .map_err(|_| "plugin command registry poisoned".to_string())?;
+        let allowed = registry
+            .get(&plugin_id)
+            .map(|set| set.contains(&bin))
+            .unwrap_or(false);
+        if !allowed {
+            return Err(format!(
+                "command '{bin}' is not allowlisted for plugin '{plugin_id}'"
+            ));
+        }
+    }
+
+    let mut command = TokioCommand::new(&bin);
+    command
+        .args(args.unwrap_or_default())
+        .stdin(std::process::Stdio::null())
+        .stdout(std::process::Stdio::piped())
+        .stderr(std::process::Stdio::piped())
+        .kill_on_drop(true);
+    if let Some(dir) = cwd {
+        command.current_dir(dir);
+    }
+
+    // Clamp to [1ms, 120s] so a plugin cannot request an unbounded process.
+    let timeout = Duration::from_millis(timeout_ms.unwrap_or(15_000).clamp(1, 120_000));
+    let output = match tokio::time::timeout(timeout, command.output()).await {
+        Ok(Ok(output)) => output,
+        Ok(Err(err)) => return Err(format!("failed to run '{bin}': {err}")),
+        Err(_) => {
+            return Err(format!(
+                "'{bin}' timed out after {}ms",
+                timeout.as_millis()
+            ))
+        }
+    };
+
+    Ok(CommandOutput {
+        code: output.status.code().unwrap_or(-1),
+        stdout: String::from_utf8_lossy(&output.stdout).to_string(),
+        stderr: String::from_utf8_lossy(&output.stderr).to_string(),
+    })
+}
+
+fn get_game_install_dir(game_id: &str) -> Result<PathBuf, String> {
+    let db = borrow_db_checked();
+    if let Some(database::GameDownloadStatus::Installed { install_dir, .. }) =
+        db.applications.game_statuses.get(game_id)
+    {
+        let path = PathBuf::from(install_dir);
+        if path.exists() {
+            return Ok(path);
+        }
+        return Err(format!(
+            "Game install directory does not exist: {}",
+            path.display()
+        ));
+    }
+    Err(format!(
+        "Game with id '{game_id}' is not installed or not found in local database"
+    ))
+}
+
+fn compute_file_sha256(path: &Path) -> io::Result<String> {
+    let mut file = File::open(path)?;
+    let mut hasher = Sha256::new();
+    let mut buffer = [0u8; 64 * 1024];
+
+    loop {
+        let bytes_read = file.read(&mut buffer)?;
+        if bytes_read == 0 {
+            break;
+        }
+        hasher.update(&buffer[..bytes_read]);
+    }
+
+    Ok(format!("{:x}", hasher.finalize()))
+}
+
+#[tauri::command]
+pub async fn plugin_game_fs_read(
+    game_id: String,
+    relative_path: String,
+) -> Result<Vec<u8>, String> {
+    let install_dir = get_game_install_dir(&game_id)?;
+    let safe_path = path_guard::safe_join(&install_dir, &relative_path)
+        .map_err(|e| format!("Security check failed: {e}"))?;
+
+    fs::read(&safe_path).map_err(|e| format!("Failed to read {relative_path}: {e}"))
+}
+
+#[tauri::command]
+pub async fn plugin_game_fs_write(
+    game_id: String,
+    relative_path: String,
+    data: Vec<u8>,
+) -> Result<(), String> {
+    let install_dir = get_game_install_dir(&game_id)?;
+    path_guard::write_file(&install_dir, &relative_path, &data)
+        .map_err(|e| format!("Failed to write {relative_path}: {e}"))
+}
+
+#[tauri::command]
+pub async fn plugin_game_fs_backup(
+    game_id: String,
+    relative_path: String,
+) -> Result<String, String> {
+    let install_dir = get_game_install_dir(&game_id)?;
+    let src_path = path_guard::safe_join(&install_dir, &relative_path)
+        .map_err(|e| format!("Security check failed: {e}"))?;
+
+    if !src_path.exists() {
+        return Err(format!(
+            "Cannot backup nonexistent file: {}",
+            src_path.display()
+        ));
+    }
+
+    let backup_relative = format!("{}.drop-backup", relative_path);
+    path_guard::copy_to(&install_dir, &src_path, &backup_relative)
+        .map_err(|e| format!("Failed to create backup {backup_relative}: {e}"))?;
+
+    Ok(backup_relative)
+}
+
+#[tauri::command]
+pub async fn plugin_game_fs_restore(
+    game_id: String,
+    relative_path: String,
+) -> Result<(), String> {
+    let install_dir = get_game_install_dir(&game_id)?;
+    let backup_relative = format!("{}.drop-backup", relative_path);
+    let backup_path = path_guard::safe_join(&install_dir, &backup_relative)
+        .map_err(|e| format!("Security check failed: {e}"))?;
+
+    if !backup_path.exists() {
+        return Err(format!(
+            "Cannot restore missing backup file: {backup_relative}"
+        ));
+    }
+
+    path_guard::copy_to(&install_dir, &backup_path, &relative_path)
+        .map_err(|e| format!("Failed to restore file from backup: {e}"))?;
+
+    // Cleanup backup file
+    let _ = path_guard::remove_file(&install_dir, &backup_relative);
+
+    Ok(())
+}
+
+#[tauri::command]
+pub async fn plugin_game_fs_exists(
+    game_id: String,
+    relative_path: String,
+) -> Result<bool, String> {
+    let install_dir = get_game_install_dir(&game_id)?;
+    match path_guard::safe_join(&install_dir, &relative_path) {
+        Ok(safe_path) => Ok(safe_path.exists()),
+        Err(_) => Ok(false),
+    }
+}
+
+#[tauri::command]
+pub async fn plugin_game_fs_delete(
+    game_id: String,
+    relative_path: String,
+) -> Result<(), String> {
+    let install_dir = get_game_install_dir(&game_id)?;
+    path_guard::remove_file(&install_dir, &relative_path)
+        .map_err(|e| format!("Failed to delete {relative_path}: {e}"))
+}
+
+#[tauri::command]
+pub async fn plugin_game_scan_executables(
+    game_id: String,
+) -> Result<Vec<ScannedExecutable>, String> {
+    let install_dir = get_game_install_dir(&game_id)?;
+    let mut executables = Vec::new();
+
+    for entry in WalkDir::new(&install_dir)
+        .into_iter()
+        .filter_map(|e| e.ok())
+    {
+        let path = entry.path();
+        if !path.is_file() {
+            continue;
+        }
+
+        // Never follow or scan symlinks for executable security
+        if path_guard::is_symlink(path) {
+            continue;
+        }
+
+        let is_exec = if let Some(ext) = path.extension().and_then(|s| s.to_str()) {
+            let lower = ext.to_lowercase();
+            matches!(
+                lower.as_str(),
+                "exe" | "dll" | "so" | "bin" | "x86_64" | "elf" | "dylib"
+            )
+        } else {
+            false
+        };
+
+        #[cfg(unix)]
+        let is_exec = is_exec || {
+            use std::os::unix::fs::PermissionsExt;
+            entry
+                .metadata()
+                .map(|m| (m.permissions().mode() & 0o111) != 0)
+                .unwrap_or(false)
+        };
+
+        if is_exec
+            && let Ok(rel_path) = path.strip_prefix(&install_dir)
+        {
+            let size = entry.metadata().map(|m| m.len()).unwrap_or(0);
+            let sha256 = compute_file_sha256(path)
+                .unwrap_or_else(|_| String::from("unknown-sha256"));
+
+            executables.push(ScannedExecutable {
+                relative_path: rel_path.to_string_lossy().to_string(),
+                sha256,
+                size,
+            });
+        }
+    }
+
+    Ok(executables)
+}
+
+#[tauri::command]
+pub async fn plugin_game_check_anticheat(game_id: String) -> Result<AntiCheatReport, String> {
+    let install_dir = get_game_install_dir(&game_id)?;
+    let mut detected_files = Vec::new();
+    let mut detected_provider: Option<String> = None;
+
+    for entry in WalkDir::new(&install_dir)
+        .into_iter()
+        .filter_map(|e| e.ok())
+    {
+        let path = entry.path();
+        let path_str = path.to_string_lossy().to_lowercase();
+
+        let provider = if path_str.contains("easyanticheat")
+            || path_str.contains("eac_server")
+            || path_str.contains("easyanticheat_x64.dll")
+        {
+            Some("easyanticheat")
+        } else if path_str.contains("battleye")
+            || path_str.contains("beservice")
+            || path_str.contains("beclient")
+        {
+            Some("battleye")
+        } else if path_str.contains("vgk.sys") || path_str.contains("vgc.exe") {
+            Some("vanguard")
+        } else if path_str.contains("denuvo") || path_str.contains("dbdata.dll") {
+            Some("denuvo")
+        } else {
+            None
+        };
+
+        if let Some(p) = provider
+            && let Ok(rel) = path.strip_prefix(&install_dir)
+        {
+            detected_files.push(rel.to_string_lossy().to_string());
+            if detected_provider.is_none() {
+                detected_provider = Some(p.to_string());
+            }
+        }
+    }
+
+    let detected = !detected_files.is_empty();
+    Ok(AntiCheatReport {
+        detected,
+        provider: detected_provider,
+        files: detected_files,
+    })
+}
diff --git a/desktop/src-tauri/src/remote.rs b/desktop/src-tauri/src/remote.rs
index 2d4585fee..63bf6ef7c 100644
--- a/desktop/src-tauri/src/remote.rs
+++ b/desktop/src-tauri/src/remote.rs
@@ -3,6 +3,7 @@ use std::{sync::nonpoison::Mutex, time::Duration};
 use client::app_status::AppStatus;
 use database::{borrow_db_checked, borrow_db_mut_checked};
 use futures_lite::StreamExt;
+use futures_util::SinkExt;
 use log::{debug, warn};
 use remote::{
     auth::{auth_initiate_logic, generate_authorization_header},
@@ -172,8 +173,8 @@ pub fn auth_initiate_code(app: AppHandle) -> Result<String, RemoteAccessError> {
                         .map_err(|e| RemoteAccessError::UnparseableResponse(e.to_string()))?;
                     match response.response_type.as_str() {
                         "token" => {
-                            let recieve_app = app.clone();
-                            manual_recieve_handshake(recieve_app, response.value).await;
+                            let receive_app = app.clone();
+                            manual_receive_handshake(receive_app, response.value).await;
                             return Ok(());
                         }
                         _ => return Err(RemoteAccessError::HandshakeFailed(response.value)),
@@ -199,3 +200,167 @@ pub fn auth_initiate_code(app: AppHandle) -> Result<String, RemoteAccessError> {
 pub async fn manual_recieve_handshake(app: AppHandle, token: String) {
     recieve_handshake(app, format!("handshake/{token}")).await;
 }
+
+#[tauri::command]
+pub async fn manual_receive_handshake(app: AppHandle, token: String) {
+    recieve_handshake(app, format!("handshake/{token}")).await;
+}
+
+#[tauri::command]
+pub async fn plugin_request(
+    plugin_id: String,
+    method: String,
+    path: String,
+    body: Option<serde_json::Value>,
+) -> Result<serde_json::Value, RemoteAccessError> {
+    let base_url = {
+        let db_lock = borrow_db_checked();
+        Url::parse(&db_lock.base_url.clone())?
+    };
+
+    let trimmed = path.trim_start_matches('/');
+    let target_path = if trimmed.is_empty() {
+        format!("/api/v1/plugins/{plugin_id}")
+    } else {
+        format!("/api/v1/plugins/{plugin_id}/{trimmed}")
+    };
+    let endpoint = base_url.join(&target_path)?;
+
+    let auth_header = generate_authorization_header();
+    let client = DROP_CLIENT_ASYNC.clone();
+
+    let request_builder = match method.to_uppercase().as_str() {
+        "POST" => {
+            let mut req = client
+                .post(endpoint.to_string())
+                .header("Authorization", auth_header);
+            if let Some(b) = body {
+                req = req.json(&b);
+            }
+            req
+        }
+        "DELETE" => {
+            let mut req = client
+                .delete(endpoint.to_string())
+                .header("Authorization", auth_header);
+            if let Some(b) = body {
+                req = req.json(&b);
+            }
+            req
+        }
+        "PATCH" => {
+            let mut req = client
+                .patch(endpoint.to_string())
+                .header("Authorization", auth_header);
+            if let Some(b) = body {
+                req = req.json(&b);
+            }
+            req
+        }
+        _ => client
+            .get(endpoint.to_string())
+            .header("Authorization", auth_header),
+    };
+
+    let response = request_builder.send().await?;
+    let status = response.status();
+    if !status.is_success() {
+        let err_text = response
+            .text()
+            .await
+            .unwrap_or_else(|_| "Unknown error".to_string());
+        return Err(RemoteAccessError::UnparseableResponse(format!(
+            "Plugin API error ({status}): {err_text}"
+        )));
+    }
+
+    let json_val = response.json::<serde_json::Value>().await?;
+    Ok(json_val)
+}
+
+/// Subscribe to a plugin WebSocket channel and emit each event as `plugin:event`.
+///
+/// The Tauri webview cannot reach the Drop server directly (TLS/auth), so the
+/// Rust side owns the socket and forwards decoded JSON to the frontend.
+#[tauri::command]
+pub fn plugin_subscribe(app: AppHandle, channel: String) -> Result<(), RemoteAccessError> {
+    let ws_url = generate_url(&["/api/v1/plugins/ws"], &[])?;
+    let auth_header = generate_authorization_header();
+
+    tauri::async_runtime::spawn(async move {
+        let load = async || -> Result<(), RemoteAccessError> {
+            let response = DROP_CLIENT_WS_CLIENT
+                .get(ws_url)
+                .header("Authorization", auth_header)
+                .upgrade()
+                .send()
+                .await?;
+            let mut websocket = response.into_websocket().await?;
+
+            let subscribe = serde_json::json!({ "type": "subscribe", "channel": channel });
+            websocket
+                .send(Message::Text(subscribe.to_string()))
+                .await
+                .map_err(|e| RemoteAccessError::HandshakeFailed(e.to_string()))?;
+
+            while let Some(message) = websocket.try_next().await? {
+                if let Message::Text(text) = message
+                    && let Ok(value) = serde_json::from_str::<serde_json::Value>(&text)
+                {
+                    app_emit!(&app, "plugin:event", value);
+                }
+            }
+            Ok(())
+        };
+
+        if let Err(err) = load().await {
+            warn!("plugin websocket for {channel} closed: {err}");
+        }
+    });
+
+    Ok(())
+}
+
+/// Send one message to a plugin WebSocket channel and return its reply.
+///
+/// Used for authenticated request/response flows (e.g. credential delivery)
+/// where the sandboxed webview cannot open a server WebSocket directly.
+#[tauri::command]
+pub async fn plugin_request_ws(
+    channel: String,
+    data: serde_json::Value,
+) -> Result<serde_json::Value, RemoteAccessError> {
+    let ws_url = generate_url(&["/api/v1/plugins/ws"], &[])?;
+    let auth_header = generate_authorization_header();
+
+    let response = DROP_CLIENT_WS_CLIENT
+        .get(ws_url)
+        .header("Authorization", auth_header)
+        .upgrade()
+        .send()
+        .await?;
+    let mut websocket = response.into_websocket().await?;
+
+    let request = serde_json::json!({
+        "type": "message",
+        "channel": channel,
+        "data": data,
+    });
+    websocket
+        .send(Message::Text(request.to_string()))
+        .await
+        .map_err(|e| RemoteAccessError::HandshakeFailed(e.to_string()))?;
+
+    while let Some(message) = websocket.try_next().await? {
+        if let Message::Text(text) = message {
+            let value: serde_json::Value = serde_json::from_str(&text)
+                .map_err(|e| RemoteAccessError::UnparseableResponse(e.to_string()))?;
+            return Ok(value.get("data").cloned().unwrap_or(value));
+        }
+    }
+
+    Err(RemoteAccessError::HandshakeFailed(
+        "plugin WebSocket closed before replying".to_string(),
+    ))
+}
+
diff --git a/server/dev-tools/run-tests.mjs b/server/dev-tools/run-tests.mjs
new file mode 100644
index 000000000..ac793cc6e
--- /dev/null
+++ b/server/dev-tools/run-tests.mjs
@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+/**
+ * Minimal unit-test runner for the server package.
+ *
+ * Drop server code uses Nuxt path aliases (`~` → server root) and node:test.
+ * There is no test runner wired into the toolchain, so every `*.test.ts` file
+ * is executed through jiti with that alias configured. Each file runs in its
+ * own child process so failures are isolated and exit codes propagate.
+ *
+ * Usage: `pnpm --filter drop run test` (or `node dev-tools/run-tests.mjs`).
+ */
+import { spawnSync } from "node:child_process";
+import { readdirSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const serverRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+);
+
+// Resolve jiti's JS entry point (the `.bin` shim is a shell script and cannot
+// be executed as a Node module). Falls back to the hoisted root install.
+function resolveJitiCli() {
+  const require = createRequire(import.meta.url);
+  try {
+    return path.join(
+      path.dirname(require.resolve("jiti/package.json")),
+      "lib",
+      "jiti-cli.mjs",
+    );
+  } catch {
+    return path.resolve(
+      serverRoot,
+      "..",
+      "node_modules",
+      "jiti",
+      "lib",
+      "jiti-cli.mjs",
+    );
+  }
+}
+
+const jitiCli = resolveJitiCli();
+const IGNORED_DIRS = new Set([
+  "node_modules",
+  ".nuxt",
+  ".data",
+  ".output",
+  "dist",
+  "build",
+]);
+const TEST_SUFFIX = ".test.ts";
+
+function discover(dir) {
+  const found = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (IGNORED_DIRS.has(entry.name)) continue;
+      found.push(...discover(path.join(dir, entry.name)));
+    } else if (entry.isFile() && entry.name.endsWith(TEST_SUFFIX)) {
+      found.push(path.join(dir, entry.name));
+    }
+  }
+  return found;
+}
+
+const files = discover(serverRoot).sort();
+if (files.length === 0) {
+  console.error(`No ${TEST_SUFFIX} files found under ${serverRoot}`);
+  process.exit(1);
+}
+
+const alias = JSON.stringify({ "~": serverRoot });
+let failed = 0;
+
+for (const file of files) {
+  const rel = path.relative(serverRoot, file);
+  console.log(`\n> ${rel}`);
+  const result = spawnSync(process.execPath, [jitiCli, file], {
+    cwd: serverRoot,
+    stdio: "inherit",
+    env: { ...process.env, JITI_ALIAS: alias },
+  });
+  if (result.status !== 0) {
+    failed += 1;
+    console.error(`FAILED: ${rel}`);
+  }
+}
+
+console.log(`\n${files.length - failed}/${files.length} test files passed`);
+process.exit(failed === 0 ? 0 : 1);
diff --git a/server/dev-tools/sample-plugin/drop-plugin.json b/server/dev-tools/sample-plugin/drop-plugin.json
new file mode 100644
index 000000000..a2a70641f
--- /dev/null
+++ b/server/dev-tools/sample-plugin/drop-plugin.json
@@ -0,0 +1,11 @@
+{
+  "apiVersion": 1,
+  "author": "Drop Community",
+  "capabilities": ["routes"],
+  "checksum": "3179792b98de1cc81bf4aa8f1218778c294664c4733023b31cf234cac9914b58",
+  "description": "Minimal external Drop plugin bundle (example)",
+  "entry": "index.js",
+  "id": "sample-plugin",
+  "name": "Sample Plugin",
+  "version": "1.0.0"
+}
diff --git a/server/dev-tools/sample-plugin/index.js b/server/dev-tools/sample-plugin/index.js
new file mode 100644
index 000000000..0af9b19d0
--- /dev/null
+++ b/server/dev-tools/sample-plugin/index.js
@@ -0,0 +1,16 @@
+/**
+ * Minimal external Drop plugin. Install by copying this directory to
+ * `<dataDir>/plugins/sample-plugin/`, then sign it with
+ * `node dev-tools/sign-plugin.mjs dev-tools/sample-plugin`.
+ */
+export default {
+  metadata: {
+    id: "sample-plugin",
+    name: "Sample Plugin",
+    version: "1.0.0",
+    capabilities: ["routes"],
+  },
+  init(ctx) {
+    ctx.registerRoute("GET", "/hello", () => ({ hello: "world" }));
+  },
+};
diff --git a/server/dev-tools/sign-plugin.mjs b/server/dev-tools/sign-plugin.mjs
new file mode 100644
index 000000000..d9163e98f
--- /dev/null
+++ b/server/dev-tools/sign-plugin.mjs
@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+/**
+ * Sign a Drop plugin bundle.
+ *
+ * Reads `<bundle>/drop-plugin.json`, computes the SHA-256 of the entry file
+ * (default `index.js`) into `checksum`, records a `files` map covering every
+ * bundle file, and — when `DROP_PLUGIN_SIGNING_KEY` is set — writes an
+ * HMAC-SHA256 `signature` over the aggregate bundle digest. The manager
+ * verifies all of these (and refuses multi-file bundles without `files`)
+ * before importing a bundle.
+ *
+ * Usage: node dev-tools/sign-plugin.mjs <bundle-dir>
+ */
+import { createHash, createHmac } from "node:crypto";
+import { readdir, readFile, realpath, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+const MANIFEST_FILE = "drop-plugin.json";
+const SIGNING_KEY_ENV = "DROP_PLUGIN_SIGNING_KEY";
+
+/** True when `candidate` is inside `base` (both absolute, lexically). */
+function isInside(base, candidate) {
+  const relative = path.relative(base, candidate);
+  return (
+    relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative)
+  );
+}
+
+const rawBundleDir = process.argv[2];
+if (!rawBundleDir) {
+  console.error("usage: node dev-tools/sign-plugin.mjs <bundle-dir>");
+  process.exit(1);
+}
+
+// Confine the caller-supplied directory to the working directory *before* any
+// filesystem access. Absolute paths and `..` escapes are rejected, and the
+// symlink-resolved path is re-checked so a symlink cannot escape either.
+const cwd = process.cwd();
+const resolvedPath = path.resolve(cwd, rawBundleDir);
+if (!isInside(cwd, resolvedPath)) {
+  console.error("bundle directory must be inside the working directory");
+  process.exit(1);
+}
+const bundleDir = await realpath(resolvedPath).catch(() => null);
+if (!bundleDir || !isInside(cwd, bundleDir)) {
+  console.error("bundle directory must be inside the working directory");
+  process.exit(1);
+}
+// NOSONAR: `bundleDir` is confined by the isInside checks above; the analyzer
+// cannot see the sanitizer.
+const bundleStat = await stat(bundleDir).catch(() => null); // NOSONAR
+if (!bundleStat?.isDirectory()) {
+  console.error("bundle directory must be an existing directory");
+  process.exit(1);
+}
+
+/** Recursively lists bundle files as POSIX-style relative paths, sorted. */
+async function listFiles(root, prefix = "") {
+  const results = [];
+  // `root` is the confined bundle directory validated by the caller.
+  const readdirOptions = { withFileTypes: true };
+  const entries = await readdir(path.join(root, prefix), readdirOptions); // NOSONAR
+  for (const entry of entries) {
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      if (entry.name === "node_modules") continue;
+      results.push(...(await listFiles(root, rel)));
+    } else if (entry.isFile()) {
+      // The manifest cannot checksum itself; the manager excludes it too.
+      if (!prefix && entry.name === MANIFEST_FILE) continue;
+      results.push(rel);
+    }
+  }
+  return results.sort((a, b) => a.localeCompare(b));
+}
+
+const manifestPath = path.join(bundleDir, MANIFEST_FILE);
+// NOSONAR: manifestPath is a fixed file name inside the confined bundleDir.
+const manifest = JSON.parse(await readFile(manifestPath, "utf-8")); // NOSONAR
+const entry = manifest.entry ?? "index.js";
+if (typeof entry !== "string") {
+  console.error("manifest entry must be a string");
+  process.exit(1);
+}
+// A manifest must not point the entry outside the bundle (e.g.
+// `"entry": "../../secret"`); check the lexical path and the symlink-resolved
+// path so a symlink inside the bundle cannot escape either.
+const entryPath = path.resolve(bundleDir, entry);
+const entryRealPath = await realpath(entryPath).catch(() => null);
+if (
+  !isInside(bundleDir, entryPath) ||
+  !entryRealPath ||
+  !isInside(bundleDir, entryRealPath)
+) {
+  console.error("manifest entry must be inside the bundle directory");
+  process.exit(1);
+}
+// NOSONAR: entryRealPath passed the confinement checks above.
+const entryBytes = await readFile(entryRealPath); // NOSONAR
+
+const checksum = createHash("sha256").update(entryBytes).digest("hex");
+manifest.checksum = checksum;
+
+const files = await listFiles(bundleDir);
+const fileChecksums = {};
+const aggregate = createHash("sha256");
+for (const rel of files) {
+  const bytes = await readFile(path.join(bundleDir, rel));
+  fileChecksums[rel] = createHash("sha256").update(bytes).digest("hex");
+  aggregate.update(rel);
+  aggregate.update("\0");
+  aggregate.update(String(bytes.length));
+  aggregate.update("\0");
+  aggregate.update(bytes);
+}
+manifest.files = fileChecksums;
+
+const key = process.env[SIGNING_KEY_ENV];
+if (key) {
+  manifest.signature = createHmac("sha256", key)
+    .update(aggregate.digest("hex"))
+    .digest("hex");
+} else {
+  delete manifest.signature;
+  console.warn(
+    `${SIGNING_KEY_ENV} not set; wrote checksums without a signature`,
+  );
+}
+
+// NOSONAR: manifestPath is inside the confined bundleDir.
+await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`); // NOSONAR
+console.log(`signed bundle: ${files.length} file(s)`);
diff --git a/server/package.json b/server/package.json
index 41a195ee2..7e65b0977 100644
--- a/server/package.json
+++ b/server/package.json
@@ -14,6 +14,7 @@
     "preview": "nuxt preview",
     "postinstall": "nuxt prepare && prisma generate && buf generate",
     "typecheck": "nuxt typecheck",
+    "test": "node dev-tools/run-tests.mjs",
     "lint": "pnpm run lint:eslint && pnpm run lint:prettier",
     "lint:eslint": "eslint .",
     "lint:prettier": "prettier . --check",
@@ -90,6 +91,7 @@
     "eslint-config-prettier": "^10.1.1",
     "golar": "^0.0.13",
     "h3": "^1.15.5",
+    "jiti": "^2.7.0",
     "nitropack": "^2.13.4",
     "ofetch": "^1.4.1",
     "prettier": "^3.5.3",
diff --git a/server/pages/admin/settings.vue b/server/pages/admin/settings.vue
index e9e2e4073..e2deaa161 100644
--- a/server/pages/admin/settings.vue
+++ b/server/pages/admin/settings.vue
@@ -42,6 +42,7 @@
 import {
   BuildingStorefrontIcon,
   CodeBracketIcon,
+  PuzzlePieceIcon,
   ServerIcon,
   ServerStackIcon,
 } from "@heroicons/vue/24/outline";
@@ -71,6 +72,12 @@ const navigation: Array<NavigationItem & { icon: Component }> = [
     prefix: "/admin/settings/services",
     icon: ServerStackIcon,
   },
+  {
+    label: "Plugins",
+    route: "/admin/settings/plugins",
+    prefix: "/admin/settings/plugins",
+    icon: PuzzlePieceIcon,
+  },
 ];
 
 // const notifications = useNotifications();
diff --git a/server/pages/admin/settings/plugins.vue b/server/pages/admin/settings/plugins.vue
new file mode 100644
index 000000000..9a779a28a
--- /dev/null
+++ b/server/pages/admin/settings/plugins.vue
@@ -0,0 +1,454 @@
+<template>
+  <div class="w-full max-w-4xl space-y-6">
+    <div
+      class="border-b border-white/10 pb-5 flex items-center justify-between"
+    >
+      <div>
+        <h3 class="text-base font-semibold leading-6 text-white">
+          Plugins &amp; Extensions
+        </h3>
+        <p class="mt-1 text-sm text-zinc-400">
+          Manage server-side and client extensions, community providers, and
+          addon capabilities.
+        </p>
+      </div>
+      <div class="flex items-center gap-x-2">
+        <button
+          type="button"
+          :disabled="isLoading"
+          class="inline-flex items-center gap-x-1.5 rounded-md bg-zinc-800 px-3 py-2 text-xs font-semibold text-zinc-200 hover:bg-zinc-700 transition disabled:opacity-50"
+          @click="checkUpdates"
+        >
+          <ArrowPathIcon
+            class="size-4"
+            :class="{ 'animate-spin': isCheckingUpdates }"
+          />
+          <span>Check Updates</span>
+        </button>
+        <button
+          type="button"
+          :disabled="isLoading"
+          class="inline-flex items-center gap-x-1.5 rounded-md bg-zinc-800 px-3 py-2 text-xs font-semibold text-zinc-200 hover:bg-zinc-700 transition disabled:opacity-50"
+          @click="reloadPlugins"
+        >
+          <ArrowPathIcon
+            class="size-4"
+            :class="{ 'animate-spin': isReloading }"
+          />
+          <span>Reload</span>
+        </button>
+      </div>
+    </div>
+
+    <!-- Error Banner -->
+    <div
+      v-if="errorMessage"
+      class="rounded-md bg-red-600/10 p-4 border border-red-500/20"
+    >
+      <div class="flex items-center gap-x-2 text-red-400 text-sm">
+        <XCircleIcon class="size-5 shrink-0" />
+        <span>{{ errorMessage }}</span>
+      </div>
+    </div>
+
+    <!-- Success Banner -->
+    <div
+      v-if="successMessage"
+      class="rounded-md bg-green-600/10 p-4 border border-green-500/20"
+    >
+      <div class="flex items-center gap-x-2 text-green-400 text-sm">
+        <CheckCircleIcon class="size-5 shrink-0" />
+        <span>{{ successMessage }}</span>
+      </div>
+    </div>
+
+    <!-- Install Plugin Section -->
+    <div class="rounded-xl border border-white/10 bg-zinc-900/60 p-5 space-y-4">
+      <h4 class="text-sm font-semibold text-white">Install Plugin Bundle</h4>
+      <div class="grid grid-cols-1 gap-4 sm:grid-cols-2">
+        <!-- Install by URL -->
+        <div class="space-y-2">
+          <label
+            for="plugin-url-input"
+            class="block text-xs font-medium text-zinc-300"
+            >Install from URL</label
+          >
+          <div class="flex gap-x-2">
+            <input
+              id="plugin-url-input"
+              v-model="installUrl"
+              type="url"
+              placeholder="https://.../my-plugin.dropplugin"
+              aria-label="Install from URL"
+              class="block w-full rounded-md bg-zinc-800 border border-zinc-700 px-3 py-1.5 text-xs text-zinc-200 placeholder-zinc-500 focus:outline-none focus:border-blue-500"
+            />
+            <button
+              type="button"
+              :disabled="isLoading || !installUrl.trim()"
+              class="shrink-0 rounded-md bg-blue-600 px-3 py-1.5 text-xs font-semibold text-white hover:bg-blue-500 transition disabled:opacity-50"
+              @click="handleInstallUrl"
+            >
+              Install
+            </button>
+          </div>
+        </div>
+
+        <!-- Install by File Upload -->
+        <div class="space-y-2">
+          <label
+            for="plugin-file-upload"
+            class="block text-xs font-medium text-zinc-300"
+            >Upload Package File</label
+          >
+          <label
+            for="plugin-file-upload"
+            class="inline-flex cursor-pointer items-center justify-center gap-x-2 w-full rounded-md bg-zinc-800 border border-zinc-700 border-dashed px-3 py-2 text-xs font-medium text-zinc-300 hover:bg-zinc-750 transition"
+          >
+            <ArrowUpTrayIcon class="size-4 text-zinc-400" />
+            <span>{{
+              uploadFileName || "Select .dropplugin or bundle .json"
+            }}</span>
+            <input
+              id="plugin-file-upload"
+              type="file"
+              accept=".dropplugin,.json"
+              aria-label="Upload Package File"
+              class="sr-only"
+              @change="handleFileUpload"
+            />
+          </label>
+        </div>
+      </div>
+    </div>
+
+    <!-- Plugin List -->
+    <div class="space-y-3">
+      <h4 class="text-sm font-semibold text-white">
+        Installed Plugins ({{ plugins.length }})
+      </h4>
+
+      <div
+        v-if="plugins.length === 0"
+        class="rounded-lg border border-dashed border-zinc-700 p-8 text-center"
+      >
+        <PuzzlePieceIcon class="mx-auto size-12 text-zinc-600 mb-2" />
+        <p class="text-sm font-medium text-zinc-300">No plugins installed</p>
+        <p class="text-xs text-zinc-500 mt-1">
+          Installed bundles in the data folder will appear here automatically.
+        </p>
+      </div>
+
+      <div
+        v-for="plugin in plugins"
+        :key="plugin.id"
+        class="rounded-xl border border-white/10 bg-zinc-900/60 p-5 space-y-3"
+      >
+        <div class="flex items-start justify-between">
+          <div class="space-y-1">
+            <div class="flex items-center gap-x-2">
+              <h5 class="text-sm font-semibold text-white">
+                {{ plugin.name }}
+              </h5>
+              <span
+                v-if="plugin.builtin"
+                class="rounded bg-purple-500/10 border border-purple-500/30 px-2 py-0.5 text-[10px] font-medium text-purple-300 uppercase tracking-wide"
+              >
+                Builtin
+              </span>
+              <span
+                v-else
+                class="rounded bg-blue-500/10 border border-blue-500/30 px-2 py-0.5 text-[10px] font-medium text-blue-300 uppercase tracking-wide"
+              >
+                External
+              </span>
+              <span
+                :class="[
+                  plugin.status === 'active'
+                    ? 'bg-emerald-500/10 text-emerald-400 border-emerald-500/30'
+                    : plugin.status === 'disabled'
+                      ? 'bg-zinc-700/20 text-zinc-400 border-zinc-700/30'
+                      : 'bg-red-500/10 text-red-400 border-red-500/30',
+                  'rounded border px-2 py-0.5 text-[10px] font-medium uppercase tracking-wide',
+                ]"
+              >
+                {{ plugin.status }}
+              </span>
+            </div>
+            <p class="text-xs font-mono text-zinc-400">
+              {{ plugin.id }} &bull; v{{ plugin.version }}
+              <span v-if="plugin.author"> &bull; by {{ plugin.author }}</span>
+            </p>
+            <p v-if="plugin.description" class="text-xs text-zinc-300 mt-1">
+              {{ plugin.description }}
+            </p>
+          </div>
+
+          <div class="flex items-center gap-x-3">
+            <button
+              v-if="!plugin.builtin"
+              type="button"
+              :disabled="isLoading"
+              class="text-xs font-medium text-red-400 hover:text-red-300 transition disabled:opacity-50"
+              @click="handleRemovePlugin(plugin.id)"
+            >
+              Remove
+            </button>
+            <button
+              type="button"
+              :disabled="isLoading"
+              :class="[
+                plugin.status === 'active'
+                  ? 'bg-blue-600 text-white hover:bg-blue-500'
+                  : 'bg-zinc-700 text-zinc-300 hover:bg-zinc-600',
+                'rounded px-2.5 py-1 text-xs font-medium transition disabled:opacity-50',
+              ]"
+              @click="handleTogglePlugin(plugin.id, plugin.status !== 'active')"
+            >
+              {{ plugin.status === "active" ? "Disable" : "Enable" }}
+            </button>
+          </div>
+        </div>
+
+        <!-- Capabilities -->
+        <div
+          v-if="plugin.capabilities?.length"
+          class="flex flex-wrap gap-1.5 pt-2 border-t border-white/5"
+        >
+          <span
+            v-for="cap in plugin.capabilities"
+            :key="cap"
+            class="rounded bg-zinc-800 px-2 py-0.5 text-[10px] font-mono text-zinc-400"
+          >
+            {{ cap }}
+          </span>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from "vue";
+import {
+  ArrowPathIcon,
+  ArrowUpTrayIcon,
+  CheckCircleIcon,
+  PuzzlePieceIcon,
+  XCircleIcon,
+} from "@heroicons/vue/24/outline";
+
+definePageMeta({
+  layout: "admin",
+});
+
+interface PluginInfo {
+  id: string;
+  name: string;
+  version: string;
+  description?: string;
+  author?: string;
+  builtin?: boolean;
+  status: "active" | "disabled" | "error" | "registered";
+  capabilities?: string[];
+}
+
+const plugins = ref<PluginInfo[]>([]);
+const isLoading = ref(false);
+const isReloading = ref(false);
+const isCheckingUpdates = ref(false);
+const errorMessage = ref<string | null>(null);
+const successMessage = ref<string | null>(null);
+const installUrl = ref("");
+const uploadFileName = ref("");
+
+function getErrorMessage(err: unknown, fallback: string): string {
+  if (
+    err &&
+    typeof err === "object" &&
+    "message" in err &&
+    typeof (err as { message: unknown }).message === "string"
+  ) {
+    return (err as { message: string }).message;
+  }
+  return fallback;
+}
+
+async function loadPlugins() {
+  isLoading.value = true;
+  errorMessage.value = null;
+  try {
+    const res = await $dropFetch<{ plugins: PluginInfo[] }>("/api/v1/plugins");
+    plugins.value = res.plugins || [];
+  } catch (err: unknown) {
+    errorMessage.value = getErrorMessage(err, "Failed to load plugins");
+  } finally {
+    isLoading.value = false;
+  }
+}
+
+async function reloadPlugins() {
+  isReloading.value = true;
+  errorMessage.value = null;
+  successMessage.value = null;
+  try {
+    const res = await $dropFetch<{ plugins: PluginInfo[] }>(
+      "/api/v1/plugins/reload",
+      {
+        method: "POST",
+      },
+    );
+    plugins.value = res.plugins || [];
+    successMessage.value = "Plugins reloaded successfully";
+  } catch (err: unknown) {
+    errorMessage.value = getErrorMessage(err, "Failed to reload plugins");
+  } finally {
+    isReloading.value = false;
+  }
+}
+
+async function checkUpdates() {
+  isCheckingUpdates.value = true;
+  errorMessage.value = null;
+  successMessage.value = null;
+  try {
+    const res = await $dropFetch<{
+      updates: Array<{
+        id: string;
+        currentVersion: string;
+        latestVersion: string;
+        hasUpdate: boolean;
+      }>;
+    }>("/api/v1/plugins/updates");
+    const updates = res.updates?.filter((u) => u.hasUpdate) || [];
+    if (updates.length > 0) {
+      const updateList = updates
+        .map((u) => `${u.id} (v${u.latestVersion})`)
+        .join(", ");
+      successMessage.value = `${updates.length} update(s) available: ${updateList}`;
+    } else {
+      successMessage.value = "All plugins are up to date";
+    }
+  } catch (err: unknown) {
+    errorMessage.value = getErrorMessage(
+      err,
+      "Failed to check for plugin updates",
+    );
+  } finally {
+    isCheckingUpdates.value = false;
+  }
+}
+
+async function handleTogglePlugin(id: string, enabled: boolean) {
+  isLoading.value = true;
+  errorMessage.value = null;
+  successMessage.value = null;
+  try {
+    await $dropFetch(`/api/v1/plugins/${id}/state`, {
+      method: "PATCH",
+      body: { enabled },
+    });
+    await loadPlugins();
+    successMessage.value = `Plugin '${id}' ${enabled ? "enabled" : "disabled"}`;
+  } catch (err: unknown) {
+    errorMessage.value = getErrorMessage(
+      err,
+      `Failed to update plugin '${id}' state`,
+    );
+  } finally {
+    isLoading.value = false;
+  }
+}
+
+async function handleRemovePlugin(id: string) {
+  if (!confirm(`Are you sure you want to remove plugin '${id}'?`)) {
+    return;
+  }
+  isLoading.value = true;
+  errorMessage.value = null;
+  successMessage.value = null;
+  try {
+    const res = await $dropFetch<{ plugins: PluginInfo[] }>(
+      `/api/v1/plugins/${id}/bundle`,
+      {
+        method: "DELETE",
+      },
+    );
+    plugins.value = res.plugins || [];
+    successMessage.value = `Plugin '${id}' removed successfully`;
+  } catch (err: unknown) {
+    errorMessage.value = getErrorMessage(
+      err,
+      `Failed to remove plugin '${id}'`,
+    );
+  } finally {
+    isLoading.value = false;
+  }
+}
+
+async function handleInstallUrl() {
+  if (!installUrl.value.trim()) return;
+  isLoading.value = true;
+  errorMessage.value = null;
+  successMessage.value = null;
+  try {
+    const res = await $dropFetch<{ plugins: PluginInfo[] }>(
+      "/api/v1/plugins/install",
+      {
+        method: "POST",
+        body: { url: installUrl.value.trim() },
+      },
+    );
+    plugins.value = res.plugins || [];
+    installUrl.value = "";
+    successMessage.value = "Plugin installed successfully from URL";
+  } catch (err: unknown) {
+    errorMessage.value = getErrorMessage(
+      err,
+      "Failed to install plugin from URL",
+    );
+  } finally {
+    isLoading.value = false;
+  }
+}
+
+async function handleFileUpload(e: Event) {
+  const target = e.target as HTMLInputElement;
+  const file = target.files?.[0];
+  if (!file) return;
+
+  uploadFileName.value = file.name;
+  isLoading.value = true;
+  errorMessage.value = null;
+  successMessage.value = null;
+
+  try {
+    const text = await file.text();
+    const payload = JSON.parse(text);
+    const body =
+      payload.format === "dropplugin-v2"
+        ? { manifest: payload.manifest, files: payload.files }
+        : payload;
+
+    const res = await $dropFetch<{ plugins: PluginInfo[] }>(
+      "/api/v1/plugins/install",
+      {
+        method: "POST",
+        body,
+      },
+    );
+    plugins.value = res.plugins || [];
+    uploadFileName.value = "";
+    successMessage.value = `Successfully installed '${file.name}'`;
+  } catch (err: unknown) {
+    errorMessage.value = getErrorMessage(
+      err,
+      `Failed to install from file '${file.name}'`,
+    );
+  } finally {
+    isLoading.value = false;
+    target.value = "";
+  }
+}
+
+await loadPlugins();
+</script>
diff --git a/server/server/api/v1/plugins/[pluginId]/[...slug].ts b/server/server/api/v1/plugins/[pluginId]/[...slug].ts
new file mode 100644
index 000000000..e6677733f
--- /dev/null
+++ b/server/server/api/v1/plugins/[pluginId]/[...slug].ts
@@ -0,0 +1,17 @@
+import { getRouterParam, createError } from "h3";
+import pluginManager from "~/server/internal/plugins";
+
+export default defineEventHandler(async (event) => {
+  const pluginId = getRouterParam(event, "pluginId");
+  if (!pluginId) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: "Missing pluginId in route path",
+    });
+  }
+
+  const slug = getRouterParam(event, "slug") ?? "";
+  const subPath = `/${slug}`.replace(/\/+/g, "/");
+
+  return await pluginManager.dispatch(pluginId, event.method, subPath, event);
+});
diff --git a/server/server/api/v1/plugins/[pluginId]/bundle.delete.ts b/server/server/api/v1/plugins/[pluginId]/bundle.delete.ts
new file mode 100644
index 000000000..dac48beb1
--- /dev/null
+++ b/server/server/api/v1/plugins/[pluginId]/bundle.delete.ts
@@ -0,0 +1,29 @@
+import { getRouterParam } from "h3";
+import aclManager from "~/server/internal/acls";
+import pluginManager from "~/server/internal/plugins";
+
+export default defineEventHandler(async (h3) => {
+  const allowed = await aclManager.allowSystemACL(h3, []);
+  if (!allowed) {
+    throw createError({
+      statusCode: 403,
+      statusMessage: "Admin privileges required to remove plugins",
+    });
+  }
+
+  const pluginId = getRouterParam(h3, "pluginId");
+  if (!pluginId) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: "Missing pluginId parameter",
+    });
+  }
+
+  try {
+    await pluginManager.removeBundle(pluginId);
+  } catch (err) {
+    throw createError({ statusCode: 400, statusMessage: String(err) });
+  }
+
+  return { success: true, plugins: pluginManager.listPlugins() };
+});
diff --git a/server/server/api/v1/plugins/[pluginId]/client/[...asset].get.ts b/server/server/api/v1/plugins/[pluginId]/client/[...asset].get.ts
new file mode 100644
index 000000000..c994911e0
--- /dev/null
+++ b/server/server/api/v1/plugins/[pluginId]/client/[...asset].get.ts
@@ -0,0 +1,42 @@
+import { createReadStream } from "node:fs";
+import path from "node:path";
+import { getRouterParam, createError, setResponseHeader, sendStream } from "h3";
+import pluginManager from "~/server/internal/plugins";
+
+const MIME_TYPES: Record<string, string> = {
+  ".js": "application/javascript; charset=utf-8",
+  ".mjs": "application/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".woff2": "font/woff2",
+};
+
+export default defineEventHandler(async (event) => {
+  const pluginId = getRouterParam(event, "pluginId");
+  const asset = getRouterParam(event, "asset");
+
+  if (!pluginId || !asset) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: "Missing pluginId or asset path",
+    });
+  }
+
+  const filePath = await pluginManager.getClientAssetPath(pluginId, asset);
+  if (!filePath) {
+    throw createError({
+      statusCode: 404,
+      statusMessage: `Plugin asset '${asset}' not found for plugin '${pluginId}'`,
+    });
+  }
+
+  const ext = path.extname(filePath).toLowerCase();
+  const mimeType = MIME_TYPES[ext] || "application/octet-stream";
+
+  setResponseHeader(event, "Content-Type", mimeType);
+  setResponseHeader(event, "Cache-Control", "public, max-age=3600");
+
+  return sendStream(event, createReadStream(filePath));
+});
diff --git a/server/server/api/v1/plugins/[pluginId]/state.patch.ts b/server/server/api/v1/plugins/[pluginId]/state.patch.ts
new file mode 100644
index 000000000..55f6c0efc
--- /dev/null
+++ b/server/server/api/v1/plugins/[pluginId]/state.patch.ts
@@ -0,0 +1,37 @@
+import { getRouterParam, readBody, createError } from "h3";
+import aclManager from "~/server/internal/acls";
+import pluginManager from "~/server/internal/plugins";
+
+export default defineEventHandler(async (event) => {
+  const allowed = await aclManager.allowSystemACL(event, []);
+  if (!allowed) {
+    throw createError({
+      statusCode: 403,
+      statusMessage: "Admin privileges required to manage plugins",
+    });
+  }
+
+  const pluginId = getRouterParam(event, "pluginId");
+  if (!pluginId) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: "Missing pluginId parameter",
+    });
+  }
+
+  const body = await readBody<{ enabled?: boolean }>(event);
+  if (typeof body?.enabled !== "boolean") {
+    throw createError({
+      statusCode: 400,
+      statusMessage: "Field 'enabled' (boolean) is required in request body",
+    });
+  }
+
+  await pluginManager.togglePlugin(pluginId, body.enabled);
+  const plugin = pluginManager.listPlugins().find((p) => p.id === pluginId);
+
+  return {
+    success: true,
+    plugin,
+  };
+});
diff --git a/server/server/api/v1/plugins/index.get.ts b/server/server/api/v1/plugins/index.get.ts
new file mode 100644
index 000000000..01816fdf3
--- /dev/null
+++ b/server/server/api/v1/plugins/index.get.ts
@@ -0,0 +1,33 @@
+import pluginManager from "~/server/internal/plugins";
+import { resolvePluginAuth } from "~/server/internal/plugins/auth";
+
+const REDACTED_ERROR = "Plugin failed to load; see the server logs.";
+
+export default defineEventHandler(async (h3) => {
+  const auth = await resolvePluginAuth(h3);
+  if (!auth.userId) {
+    throw createError({
+      statusCode: 401,
+      statusMessage: "Authentication required",
+    });
+  }
+
+  // Error strings can contain absolute paths or expected checksums; only
+  // expose them to administrators.
+  const isAdmin = auth.userAcls?.includes("system:settings:update") ?? false;
+
+  const plugins = pluginManager.listPlugins().map((plugin) => {
+    let error: string | undefined;
+    if (isAdmin) {
+      error = plugin.error;
+    } else if (plugin.error) {
+      error = REDACTED_ERROR;
+    }
+    return {
+      ...plugin,
+      error,
+    };
+  });
+
+  return { plugins };
+});
diff --git a/server/server/api/v1/plugins/install.post.ts b/server/server/api/v1/plugins/install.post.ts
new file mode 100644
index 000000000..4b5d864c6
--- /dev/null
+++ b/server/server/api/v1/plugins/install.post.ts
@@ -0,0 +1,58 @@
+import { type } from "arktype";
+import { readDropValidatedBody, throwingArktype } from "~/server/arktype";
+import aclManager from "~/server/internal/acls";
+import pluginManager from "~/server/internal/plugins";
+import type { PluginManifest } from "~/server/internal/plugins";
+
+const InstallBundle = type({
+  "manifest?": {
+    id: "string>0",
+    name: "string>0",
+    version: "string>0",
+    "apiVersion?": "number",
+    "entry?": "string",
+    "clientEntry?": "string",
+    "capabilities?": "string[]",
+    "checksum?": "string",
+    "files?": "Record<string, string>",
+    "signature?": "string",
+    "server?": "object",
+    "client?": "object",
+  },
+  "entry?": "string",
+  "files?": "Record<string, string>",
+  "format?": "string",
+  "url?": "string>0",
+}).configure(throwingArktype);
+
+export default defineEventHandler(async (h3) => {
+  const allowed = await aclManager.allowSystemACL(h3, []);
+  if (!allowed) {
+    throw createError({
+      statusCode: 403,
+      statusMessage: "Admin privileges required to install plugins",
+    });
+  }
+
+  const body = await readDropValidatedBody(h3, InstallBundle);
+  try {
+    if (body.url) {
+      await pluginManager.installFromUrl(body.url);
+    } else {
+      const payload = body.files ?? body.entry;
+      if (!payload || !body.manifest) {
+        throw new Error(
+          "Plugin bundle must provide either 'url', or 'manifest' with 'files'/'entry'",
+        );
+      }
+      await pluginManager.installBundle(
+        body.manifest as PluginManifest,
+        payload,
+      );
+    }
+  } catch (err) {
+    throw createError({ statusCode: 400, statusMessage: String(err) });
+  }
+
+  return { success: true, plugins: pluginManager.listPlugins() };
+});
diff --git a/server/server/api/v1/plugins/reload.post.ts b/server/server/api/v1/plugins/reload.post.ts
new file mode 100644
index 000000000..c098e4c0b
--- /dev/null
+++ b/server/server/api/v1/plugins/reload.post.ts
@@ -0,0 +1,18 @@
+import aclManager from "~/server/internal/acls";
+import pluginManager from "~/server/internal/plugins";
+
+export default defineEventHandler(async (event) => {
+  const allowed = await aclManager.allowSystemACL(event, []);
+  if (!allowed) {
+    throw createError({
+      statusCode: 403,
+      statusMessage: "Admin privileges required to reload plugins",
+    });
+  }
+
+  await pluginManager.reloadPlugins();
+  return {
+    success: true,
+    plugins: pluginManager.listPlugins(),
+  };
+});
diff --git a/server/server/api/v1/plugins/updates.get.ts b/server/server/api/v1/plugins/updates.get.ts
new file mode 100644
index 000000000..93769a8bf
--- /dev/null
+++ b/server/server/api/v1/plugins/updates.get.ts
@@ -0,0 +1,23 @@
+import pluginManager from "~/server/internal/plugins";
+import { resolvePluginAuth } from "~/server/internal/plugins/auth";
+
+export default defineEventHandler(async (h3) => {
+  const auth = await resolvePluginAuth(h3);
+  if (!auth.userId) {
+    throw createError({
+      statusCode: 401,
+      statusMessage: "Authentication required",
+    });
+  }
+
+  const isAdmin = auth.userAcls?.includes("system:settings:update") ?? false;
+  if (!isAdmin) {
+    throw createError({
+      statusCode: 403,
+      statusMessage: "Admin privileges required to check for plugin updates",
+    });
+  }
+
+  const updates = await pluginManager.checkForUpdates();
+  return { updates };
+});
diff --git a/server/server/api/v1/plugins/ws.get.ts b/server/server/api/v1/plugins/ws.get.ts
new file mode 100644
index 000000000..b2143b866
--- /dev/null
+++ b/server/server/api/v1/plugins/ws.get.ts
@@ -0,0 +1,220 @@
+import pluginManager from "~/server/internal/plugins";
+import { resolvePluginAuth } from "~/server/internal/plugins/auth";
+
+const clientSubscriptions = new Map<string, Array<() => void>>();
+const clientChannels = new Map<string, Set<string>>();
+const peerUsers = new Map<string, string | undefined>();
+const peerAcls = new Map<string, string[] | undefined>();
+
+const CHANNEL_PATTERN = /^[a-zA-Z0-9:_-]{1,128}$/;
+const MAX_MESSAGE_BYTES = 64 * 1024;
+const MAX_SUBSCRIPTIONS_PER_PEER = 32;
+
+/** Minimal structural view of the crossws peer used by the helpers below. */
+type WebSocketPeer = {
+  id: string;
+  request: {
+    headers: Headers;
+  };
+  send: (payload: string) => void;
+  close: () => void;
+};
+
+interface ClientMessage {
+  type?: unknown;
+  channel?: unknown;
+  data?: unknown;
+}
+
+function parseClientMessage(message: unknown): ClientMessage | undefined {
+  const text =
+    typeof (message as { text?: () => string }).text === "function"
+      ? (message as { text: () => string }).text()
+      : String(message);
+  if (Buffer.byteLength(text, "utf8") > MAX_MESSAGE_BYTES) return undefined;
+  try {
+    const parsed: unknown = JSON.parse(text);
+    if (parsed !== null && typeof parsed === "object") {
+      return parsed as ClientMessage;
+    }
+  } catch {
+    // Ignore non-JSON messages.
+  }
+  return undefined;
+}
+
+/** Hosts an Origin must match for a browser upgrade. */
+function allowedHostsFor(peer: WebSocketPeer): Set<string> {
+  const allowedHosts = new Set<string>();
+  const host = peer.request.headers.get("host");
+  if (host) allowedHosts.add(host);
+  const forwardedHost = peer.request.headers.get("x-forwarded-host");
+  if (forwardedHost) {
+    for (const item of forwardedHost.split(",")) {
+      const trimmed = item.trim();
+      if (trimmed) allowedHosts.add(trimmed);
+    }
+  }
+  const externalUrl = process.env.EXTERNAL_URL;
+  if (externalUrl) {
+    try {
+      allowedHosts.add(new URL(externalUrl).host);
+    } catch {
+      // Ignore malformed configuration here; auth still applies below.
+    }
+  }
+  return allowedHosts;
+}
+
+// Browsers always send Origin on WebSocket handshakes. Reject cross-site
+// upgrades so a malicious page cannot ride a victim's session cookie into the
+// plugin gateway (non-browser clients omit Origin and are allowed).
+function isAllowedOrigin(peer: WebSocketPeer): boolean {
+  const origin = peer.request.headers.get("origin");
+  if (!origin) return true;
+
+  const allowedHosts = allowedHostsFor(peer);
+  let originHost: string | undefined;
+  try {
+    originHost = new URL(origin).host;
+  } catch {
+    originHost = undefined;
+  }
+  return (
+    !!originHost && (allowedHosts.size === 0 || allowedHosts.has(originHost))
+  );
+}
+
+async function resolvePeerAuth(
+  peer: WebSocketPeer,
+): Promise<{ userId: string | undefined; userAcls: string[] | undefined }> {
+  try {
+    const auth = await resolvePluginAuth(peer.request);
+    return { userId: auth.userId, userAcls: auth.userAcls };
+  } catch {
+    // Unauthenticated peer.
+    return { userId: undefined, userAcls: undefined };
+  }
+}
+
+function sendChannelError(
+  peer: WebSocketPeer,
+  channel: string,
+  error: string,
+): void {
+  peer.send(JSON.stringify({ channel, error }));
+}
+
+async function authorizeChannel(
+  peer: WebSocketPeer,
+  channel: string,
+  userId: string | undefined,
+): Promise<boolean> {
+  if (!userId && !pluginManager.isPublicChannel(channel)) {
+    sendChannelError(peer, channel, "authentication required");
+    return false;
+  }
+
+  // Per-channel authorization (e.g. room membership), when a plugin registers
+  // an authorizer for the channel.
+  const authorized = await pluginManager.canSubscribe(channel, {
+    userId,
+    userAcls: peerAcls.get(peer.id),
+  });
+  if (!authorized) {
+    sendChannelError(peer, channel, "not authorized for channel");
+    return false;
+  }
+  return true;
+}
+
+function handleSubscribe(peer: WebSocketPeer, channel: string): void {
+  const subscriptions = clientChannels.get(peer.id);
+  if (!subscriptions || subscriptions.has(channel)) return;
+  if (subscriptions.size >= MAX_SUBSCRIPTIONS_PER_PEER) {
+    sendChannelError(peer, channel, "too many subscriptions");
+    return;
+  }
+  subscriptions.add(channel);
+
+  const unsubscribe = pluginManager.subscribe(channel, (event) => {
+    peer.send(JSON.stringify({ channel, data: event }));
+  });
+  clientSubscriptions.get(peer.id)?.push(unsubscribe);
+}
+
+async function dispatchClientMessage(
+  peer: WebSocketPeer,
+  channel: string,
+  data: unknown,
+  userId: string | undefined,
+): Promise<void> {
+  // Unauthenticated peers may only send on public channels.
+  if (!userId && !pluginManager.isPublicChannel(channel)) {
+    sendChannelError(peer, channel, "authentication required");
+    return;
+  }
+  const handled = await pluginManager.dispatchWebSocket(channel, data, {
+    userId,
+    userAcls: peerAcls.get(peer.id),
+    send: (payload) => peer.send(JSON.stringify({ channel, data: payload })),
+  });
+  if (!handled) {
+    sendChannelError(peer, channel, "no plugin handler for channel");
+  }
+}
+
+export default defineWebSocketHandler({
+  async open(peer) {
+    if (!isAllowedOrigin(peer)) {
+      peer.close();
+      return;
+    }
+
+    clientSubscriptions.set(peer.id, []);
+    clientChannels.set(peer.id, new Set());
+
+    // Authenticate the upgrade request so plugins receive a userId. Supports
+    // both browser sessions/API tokens and desktop client JWTs.
+    const { userId, userAcls } = await resolvePeerAuth(peer);
+    peerUsers.set(peer.id, userId);
+    peerAcls.set(peer.id, userAcls);
+  },
+  async message(peer, message) {
+    try {
+      const parsed = parseClientMessage(message);
+      if (
+        !parsed ||
+        typeof parsed.channel !== "string" ||
+        !CHANNEL_PATTERN.test(parsed.channel)
+      ) {
+        return;
+      }
+      const userId = peerUsers.get(peer.id);
+
+      if (parsed.type === "subscribe") {
+        if (!(await authorizeChannel(peer, parsed.channel, userId))) return;
+        handleSubscribe(peer, parsed.channel);
+        return;
+      }
+
+      if (parsed.type === "message") {
+        await dispatchClientMessage(peer, parsed.channel, parsed.data, userId);
+      }
+    } catch {
+      // Ignore non-JSON or invalid messages
+    }
+  },
+  close(peer) {
+    const unsubscribes = clientSubscriptions.get(peer.id);
+    if (unsubscribes) {
+      for (const unsub of unsubscribes) {
+        unsub();
+      }
+      clientSubscriptions.delete(peer.id);
+    }
+    clientChannels.delete(peer.id);
+    peerUsers.delete(peer.id);
+    peerAcls.delete(peer.id);
+  },
+});
diff --git a/server/server/internal/acls/index.ts b/server/server/internal/acls/index.ts
index f0bf391c8..c96dfdc1c 100644
--- a/server/server/internal/acls/index.ts
+++ b/server/server/internal/acls/index.ts
@@ -136,7 +136,7 @@ class ACLManager {
       throw new Error("Native web requests not available - weird deployment?");
     // Sessions automatically have all ACLs
     const session = await sessionHandler.getSession(request);
-    if (session && session.authenticated) {
+    if (session?.authenticated) {
       if (session.authenticated.level >= session.authenticated.requiredLevel)
         return session.authenticated.userId;
       return undefined;
@@ -164,6 +164,26 @@ class ACLManager {
     return undefined;
   }
 
+  /**
+   * Resolves a `Bearer` User/Client API token to its owning user id without
+   * requiring any specific ACL. Used by callers (e.g. the plugin gateway) that
+   * authenticate the token itself rather than gating on a permission.
+   */
+  async getUserIdFromBearer(
+    request: MinimumRequestObject | undefined,
+  ): Promise<string | undefined> {
+    if (!request) return undefined;
+    const authorizationToken = this.getAuthorizationToken(request);
+    if (!authorizationToken) return undefined;
+    const token = await prisma.aPIToken.findUnique({
+      where: {
+        token: authorizationToken,
+        mode: { in: [APITokenMode.User, APITokenMode.Client] },
+      },
+    });
+    return token?.userId ?? undefined;
+  }
+
   async getUserACL(request: MinimumRequestObject | undefined, acls: UserACL) {
     if (!request)
       throw new Error("Native web requests not available - weird deployment?");
@@ -178,7 +198,7 @@ class ACLManager {
     if (!request)
       throw new Error("Native web requests not available - weird deployment?");
     const session = await sessionHandler.getSession(request);
-    if (!session || !session.authenticated) return undefined;
+    if (!session?.authenticated) return undefined;
     if (session.authenticated.level < session.authenticated.requiredLevel)
       return undefined;
     if (session.authenticated.superleveledExpiry === undefined)
@@ -194,39 +214,41 @@ class ACLManager {
     if (!request)
       throw new Error("Native web requests not available - weird deployment?");
     const userSession = await sessionHandler.getSession(request);
-    if (userSession && userSession.authenticated) {
+    const authenticated = userSession?.authenticated;
+    if (authenticated) {
       const user = await prisma.user.findUnique({
-        where: { id: userSession.authenticated.userId },
+        where: { id: authenticated.userId },
       });
       if (user) {
-        if (!user) return false;
-        if (!user.admin) return false;
-        if (
-          userSession.authenticated.level <
-          userSession.authenticated.requiredLevel
-        )
-          return false;
-        return true;
+        return this.isAdminSession(authenticated, user.admin);
       }
     }
 
+    return this.allowSystemTokenACL(request, acls);
+  }
+
+  private isAdminSession(
+    authenticated: { level: number; requiredLevel: number },
+    admin: boolean,
+  ): boolean {
+    return admin && authenticated.level >= authenticated.requiredLevel;
+  }
+
+  private async allowSystemTokenACL(
+    request: MinimumRequestObject,
+    acls: SystemACL,
+  ) {
     const authorizationToken = this.getAuthorizationToken(request);
     if (!authorizationToken) return false;
     const token = await prisma.aPIToken.findUnique({
       where: { token: authorizationToken },
     });
-    if (!token) return false;
-    if (token.mode != APITokenMode.System) return false;
+    if (!token || token.mode != APITokenMode.System) return false;
 
     // If empty, we just want to check we are an admin *at all*, not specific ACLs
     if (acls.length == 0) return true;
 
-    for (const acl of acls) {
-      const tokenACLIndex = token.acls.findIndex((e) => e == acl);
-      if (tokenACLIndex != -1) return true;
-    }
-
-    return false;
+    return acls.some((acl) => token.acls.includes(acl));
   }
 
   async hasACL(request: MinimumRequestObject | undefined, acls: GlobalACL[]) {
@@ -255,7 +277,7 @@ class ACLManager {
     request: MinimumRequestObject,
   ): Promise<GlobalACL[] | undefined> {
     const userSession = await sessionHandler.getSession(request);
-    if (!userSession || !userSession.authenticated) {
+    if (!userSession?.authenticated) {
       const authorizationToken = this.getAuthorizationToken(request);
       if (!authorizationToken) return undefined;
       const token = await prisma.aPIToken.findUnique({
diff --git a/server/server/internal/plugins/__tests__/auth.test.ts b/server/server/internal/plugins/__tests__/auth.test.ts
new file mode 100644
index 000000000..3585d8f53
--- /dev/null
+++ b/server/server/internal/plugins/__tests__/auth.test.ts
@@ -0,0 +1,104 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { generateKeyPairSync } from "node:crypto";
+import jwt from "jsonwebtoken";
+import { parseClientJwtHeader, resolveClientJwt } from "../auth";
+import type { MinimumRequestObject } from "~/server/h3";
+
+function requestWith(authorization: string): MinimumRequestObject {
+  return {
+    headers: new Headers({ Authorization: authorization }),
+  } as unknown as MinimumRequestObject;
+}
+
+function keypair() {
+  const { privateKey, publicKey } = generateKeyPairSync("ec", {
+    namedCurve: "P-384",
+  });
+  return {
+    privatePem: privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
+    publicPem: publicKey.export({ type: "spki", format: "pem" }).toString(),
+  };
+}
+
+function signToken(privatePem: string, overrides?: { exp?: number }) {
+  const now = Math.floor(Date.now() / 1000);
+  return jwt.sign({ nbf: now, exp: overrides?.exp ?? now + 30 }, privatePem, {
+    algorithm: "ES384",
+  });
+}
+
+test("parseClientJwtHeader accepts only the desktop JWT scheme", () => {
+  assert.deepEqual(parseClientJwtHeader("JWT client-1 abc.def.ghi"), {
+    clientId: "client-1",
+    token: "abc.def.ghi",
+  });
+  assert.equal(parseClientJwtHeader("Bearer some-token"), undefined);
+  assert.equal(parseClientJwtHeader("JWT client-1"), undefined);
+  assert.equal(parseClientJwtHeader(undefined), undefined);
+  assert.equal(parseClientJwtHeader(""), undefined);
+});
+
+test("resolveClientJwt verifies a signed desktop JWT", async () => {
+  const { privatePem, publicPem } = keypair();
+  const token = signToken(privatePem);
+
+  const userId = await resolveClientJwt(requestWith(`JWT client-1 ${token}`), {
+    fetchCertificate: async () => ({ cert: publicPem }),
+    fetchUser: async () => ({ id: "user-1", admin: false }),
+  });
+
+  assert.equal(userId, "user-1");
+});
+
+test("resolveClientJwt rejects tampered, expired and unknown clients", async () => {
+  const { privatePem, publicPem } = keypair();
+  const token = signToken(privatePem);
+  const other = keypair();
+
+  const deps = {
+    fetchCertificate: async () => ({ cert: publicPem }),
+    fetchUser: async () => ({ id: "user-1", admin: false }),
+  };
+
+  assert.equal(
+    await resolveClientJwt(requestWith(`JWT client-1 ${token}tampered`), deps),
+    undefined,
+  );
+  assert.equal(
+    await resolveClientJwt(
+      requestWith(`JWT client-1 ${signToken(other.privatePem)}`),
+      deps,
+    ),
+    undefined,
+    "a token signed by another key must not verify",
+  );
+  assert.equal(
+    await resolveClientJwt(
+      requestWith(`JWT client-1 ${signToken(privatePem, { exp: 1 })}`),
+      deps,
+    ),
+    undefined,
+    "expired tokens must be rejected",
+  );
+  assert.equal(
+    await resolveClientJwt(requestWith(`JWT client-1 ${token}`), {
+      ...deps,
+      fetchCertificate: async () => undefined,
+    }),
+    undefined,
+    "unknown/blacklisted clients must be rejected",
+  );
+  assert.equal(
+    await resolveClientJwt(requestWith(`JWT client-1 ${token}`), {
+      ...deps,
+      fetchUser: async () => undefined,
+    }),
+    undefined,
+    "a client without a user must be rejected",
+  );
+  assert.equal(
+    await resolveClientJwt(requestWith(`Bearer ${token}`), deps),
+    undefined,
+  );
+});
diff --git a/server/server/internal/plugins/__tests__/plugins.test.ts b/server/server/internal/plugins/__tests__/plugins.test.ts
new file mode 100644
index 000000000..2af16b22c
--- /dev/null
+++ b/server/server/internal/plugins/__tests__/plugins.test.ts
@@ -0,0 +1,1358 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import http from "node:http";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { PluginManager } from "../manager";
+import { HelloWorldPlugin } from "../builtin/hello-world";
+import { PLUGIN_API_VERSION } from "../types";
+import type {
+  PluginCapability,
+  PluginContext,
+  PluginMetadata,
+  PluginStorage,
+  ServerPlugin,
+} from "../types";
+
+/**
+ * In-memory storage so tests never touch Drop's runtime config (which is only
+ * available inside a Nuxt/Nitro process).
+ */
+class MemoryStorage implements PluginStorage {
+  private readonly data = new Map<string, unknown>();
+  private schemaVersion = 0;
+
+  async get<T>(key: string): Promise<T | null> {
+    return this.data.has(key) ? (this.data.get(key) as T) : null;
+  }
+
+  async set<T>(key: string, value: T): Promise<void> {
+    this.data.set(key, value);
+  }
+
+  async delete(key: string): Promise<void> {
+    this.data.delete(key);
+  }
+
+  async listKeys(): Promise<string[]> {
+    return [...this.data.keys()];
+  }
+
+  async getSchemaVersion(): Promise<number> {
+    return this.schemaVersion;
+  }
+
+  async setSchemaVersion(version: number): Promise<void> {
+    this.schemaVersion = version;
+  }
+}
+
+let managerCounter = 0;
+
+function tmpDataDir(): string {
+  managerCounter += 1;
+  return path.join(
+    os.tmpdir(),
+    `drop-plugin-test-${process.pid}-${managerCounter}-${Date.now()}`,
+  );
+}
+
+/** Build a manager isolated from the Nuxt runtime and the shared plugin dir. */
+function createTestManager(storage?: PluginStorage): PluginManager {
+  return new PluginManager({
+    dataDir: tmpDataDir(),
+    storageFactory: () => storage ?? new MemoryStorage(),
+    authResolver: async () => ({ userId: undefined }),
+  });
+}
+
+test("PluginManager registers and initializes plugin", async () => {
+  const manager = createTestManager();
+  let initCalled = false;
+
+  const testPlugin: ServerPlugin = {
+    metadata: {
+      id: "test-plugin",
+      name: "Test Plugin",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+    },
+    init: (_ctx: PluginContext) => {
+      initCalled = true;
+    },
+  };
+
+  await manager.registerPlugin(testPlugin);
+
+  assert.equal(initCalled, true);
+  const list = manager.listPlugins();
+  assert.equal(list.length, 1);
+  assert.equal(list[0].id, "test-plugin");
+  assert.equal(list[0].status, "active");
+});
+
+test("PluginManager route registration and pattern matching", async () => {
+  const manager = createTestManager();
+
+  const testPlugin: ServerPlugin = {
+    metadata: {
+      id: "route-plugin",
+      name: "Route Plugin",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      capabilities: ["routes"],
+    },
+    init: (ctx: PluginContext) => {
+      ctx.registerRoute("GET", "/items", () => {
+        return { items: ["a", "b"] };
+      });
+
+      ctx.registerRoute("GET", "/items/:id", (_event, context) => {
+        return { item: context.params.id };
+      });
+
+      ctx.registerRoute("POST", "/items/:id/action", (_event, context) => {
+        return { action: "done", id: context.params.id };
+      });
+    },
+  };
+
+  await manager.registerPlugin(testPlugin);
+
+  // Mock H3Event minimal shape
+  const mockEvent = {
+    method: "GET",
+    headers: new Headers(),
+  } as unknown as import("h3").H3Event;
+
+  const res1 = (await manager.dispatch(
+    "route-plugin",
+    "GET",
+    "/items",
+    mockEvent,
+  )) as { items: string[] };
+  assert.deepEqual(res1.items, ["a", "b"]);
+
+  const res2 = (await manager.dispatch(
+    "route-plugin",
+    "GET",
+    "/items/123",
+    mockEvent,
+  )) as { item: string };
+  assert.equal(res2.item, "123");
+
+  const postEvent = {
+    method: "POST",
+    headers: new Headers(),
+  } as unknown as import("h3").H3Event;
+
+  const res3 = (await manager.dispatch(
+    "route-plugin",
+    "POST",
+    "/items/456/action",
+    postEvent,
+  )) as { action: string; id: string };
+  assert.equal(res3.action, "done");
+  assert.equal(res3.id, "456");
+});
+
+test("PluginManager event bus broadcast and subscribe", async () => {
+  const manager = createTestManager();
+  let receivedMessage = "";
+
+  const unsubscribe = manager.subscribe("chat:general", (data) => {
+    receivedMessage = (data as { text: string }).text;
+  });
+
+  manager.broadcast("chat:general", { text: "hello world" });
+  assert.equal(receivedMessage, "hello world");
+
+  unsubscribe();
+  manager.broadcast("chat:general", { text: "should not be received" });
+  assert.equal(receivedMessage, "hello world");
+});
+
+test("PluginManager togglePlugin enables and disables plugin lifecycle", async () => {
+  const manager = createTestManager();
+
+  const toggleTestPlugin: ServerPlugin = {
+    metadata: {
+      id: "toggle-test",
+      name: "Toggle Test Plugin",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      capabilities: ["routes"],
+    },
+    init: (ctx: PluginContext) => {
+      ctx.registerRoute("GET", "/ping", () => {
+        return { pong: true };
+      });
+    },
+    teardown: () => {},
+  };
+
+  await manager.registerPlugin(toggleTestPlugin);
+  assert.equal(
+    manager.listPlugins().find((p) => p.id === "toggle-test")?.status,
+    "active",
+  );
+
+  const mockEvent = {
+    method: "GET",
+    headers: new Headers(),
+  } as unknown as import("h3").H3Event;
+
+  const resBefore = (await manager.dispatch(
+    "toggle-test",
+    "GET",
+    "/ping",
+    mockEvent,
+  )) as { pong: boolean };
+  assert.equal(resBefore.pong, true);
+
+  // Disable plugin
+  await manager.togglePlugin("toggle-test", false);
+  assert.equal(
+    manager.listPlugins().find((p) => p.id === "toggle-test")?.status,
+    "disabled",
+  );
+
+  await assert.rejects(
+    async () => {
+      await manager.dispatch("toggle-test", "GET", "/ping", mockEvent);
+    },
+    { statusCode: 503 },
+  );
+
+  // Re-enable plugin
+  await manager.togglePlugin("toggle-test", true);
+  assert.equal(
+    manager.listPlugins().find((p) => p.id === "toggle-test")?.status,
+    "active",
+  );
+
+  const resAfter = (await manager.dispatch(
+    "toggle-test",
+    "GET",
+    "/ping",
+    mockEvent,
+  )) as { pong: boolean };
+  assert.equal(resAfter.pong, true);
+});
+
+test("PluginManager fails closed when using an undeclared capability", async () => {
+  const manager = createTestManager();
+
+  const noRoutesPlugin: ServerPlugin = {
+    metadata: {
+      id: "no-routes-plugin",
+      name: "No Routes Plugin",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      capabilities: ["storage"], // explicitly lacks "routes"
+    },
+    init: (ctx: PluginContext) => {
+      ctx.registerRoute("GET", "/should-not-exist", () => ({
+        allowed: false,
+      }));
+    },
+  };
+
+  await assert.rejects(() => manager.registerPlugin(noRoutesPlugin), {
+    name: "PluginCapabilityError",
+  });
+  assert.equal(
+    manager.listPlugins().find((p) => p.id === "no-routes-plugin")?.status,
+    "error",
+  );
+});
+
+test("PluginManager denies storage and network without capabilities", async () => {
+  const manager = createTestManager();
+
+  const plugin: ServerPlugin = {
+    metadata: {
+      id: "no-io-plugin",
+      name: "No IO Plugin",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      capabilities: ["routes"],
+    },
+    async init(ctx: PluginContext) {
+      await assert.rejects(() => ctx.storage.get("x"), {
+        name: "PluginCapabilityError",
+      });
+      await assert.rejects(() => ctx.fetch("https://example.com"), {
+        name: "PluginCapabilityError",
+      });
+    },
+  };
+
+  await manager.registerPlugin(plugin);
+  assert.equal(
+    manager.listPlugins().find((p) => p.id === "no-io-plugin")?.status,
+    "active",
+  );
+});
+
+test("PluginManager defaults to denying capabilities when none are declared", async () => {
+  const manager = createTestManager();
+
+  for (const [id, capabilities] of [
+    ["undeclared-plugin", undefined],
+    ["empty-capabilities-plugin", [] as PluginCapability[]],
+  ] as const) {
+    const metadata: PluginMetadata = {
+      id,
+      name: id,
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+    };
+    if (capabilities) metadata.capabilities = [...capabilities];
+    const plugin: ServerPlugin = {
+      metadata,
+      init: (ctx: PluginContext) => {
+        ctx.registerRoute("GET", "/denied", () => ({ allowed: false }));
+      },
+    };
+    await assert.rejects(() => manager.registerPlugin(plugin), {
+      name: "PluginCapabilityError",
+    });
+  }
+});
+
+test("PluginManager rejects plugin ids that escape the plugins directory", async () => {
+  const manager = createTestManager();
+
+  for (const id of ["..", ".", "../evil", "evil/../../x", ""]) {
+    const plugin: ServerPlugin = {
+      metadata: { id, name: "Evil", version: "1.0.0" },
+      init: () => {},
+    };
+    await assert.rejects(
+      () => manager.registerPlugin(plugin),
+      /invalid plugin id/,
+    );
+  }
+
+  await assert.rejects(() => manager.removeBundle(".."), /invalid plugin id/);
+
+  await assert.rejects(
+    () =>
+      manager.installBundle(
+        {
+          id: "..",
+          name: "Evil",
+          version: "1.0.0",
+          apiVersion: PLUGIN_API_VERSION,
+        },
+        Buffer.from("module.exports = {}").toString("base64"),
+      ),
+    /invalid plugin id/,
+  );
+});
+
+test("PluginManager rejects incompatible plugin API versions", async () => {
+  const manager = createTestManager();
+
+  const plugin: ServerPlugin = {
+    metadata: {
+      id: "old-plugin",
+      name: "Old",
+      version: "1.0.0",
+      apiVersion: 0,
+    },
+    init: () => {},
+  };
+
+  await assert.rejects(() => manager.registerPlugin(plugin), {
+    name: "PluginApiVersionError",
+  });
+
+  const current: ServerPlugin = {
+    metadata: {
+      id: "current-plugin",
+      name: "Current",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+    },
+    init: () => {},
+  };
+
+  await manager.registerPlugin(current);
+  assert.equal(
+    manager.listPlugins().find((p) => p.id === "current-plugin")?.status,
+    "active",
+  );
+});
+
+test("PluginManager rejects unsupported trust tiers", async () => {
+  const manager = createTestManager();
+
+  const plugin: ServerPlugin = {
+    metadata: {
+      id: "sandboxed-plugin",
+      name: "Sandboxed",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      trust: "sandboxed",
+    },
+    init: () => {},
+  };
+
+  await assert.rejects(() => manager.registerPlugin(plugin), {
+    name: "PluginTrustError",
+  });
+});
+
+test("PluginManager fails closed on system:command without a commands allowlist", async () => {
+  const entryBase64 = Buffer.from("export default {}").toString("base64");
+
+  await assert.rejects(
+    () =>
+      createTestManager().installBundle(
+        {
+          id: "native-demo",
+          name: "Native",
+          version: "1.0.0",
+          apiVersion: PLUGIN_API_VERSION,
+          targets: ["client"],
+          client: { entry: "client.js", capabilities: ["system:command"] },
+        },
+        entryBase64,
+      ),
+    /client\.commands/,
+  );
+
+  await assert.rejects(
+    () =>
+      createTestManager().installBundle(
+        {
+          id: "native-demo-2",
+          name: "Native",
+          version: "1.0.0",
+          apiVersion: PLUGIN_API_VERSION,
+          targets: ["client"],
+          client: {
+            entry: "client.js",
+            capabilities: ["system:command"],
+            commands: ["/usr/bin/custom-cli"],
+          },
+        },
+        entryBase64,
+      ),
+    /bare executable names/,
+  );
+});
+
+test("PluginManager runs storage migrations to the declared version", async () => {
+  const storage = new MemoryStorage();
+  const manager = createTestManager(storage);
+  const migrations: Array<[number, number]> = [];
+
+  const plugin: ServerPlugin = {
+    metadata: {
+      id: "migrating-plugin",
+      name: "Migrating",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      capabilities: ["storage"],
+      storageVersion: 2,
+    },
+    init: () => {},
+    migrateStorage: async (from, to, target) => {
+      migrations.push([from, to]);
+      await target.set("migrated", true);
+    },
+  };
+
+  await manager.registerPlugin(plugin);
+  assert.deepEqual(migrations, [[0, 2]]);
+  assert.equal(await storage.getSchemaVersion(), 2);
+
+  // Re-registering must not re-run migrations.
+  await manager.registerPlugin(plugin);
+  assert.deepEqual(migrations, [[0, 2]]);
+});
+
+test("HelloWorldPlugin proves generic extensible plugin architecture", async () => {
+  const manager = createTestManager();
+  await manager.registerPlugin(new HelloWorldPlugin());
+
+  const mockEvent = {
+    method: "GET",
+    headers: new Headers(),
+  } as unknown as import("h3").H3Event;
+
+  const res = (await manager.dispatch(
+    "hello-world",
+    "GET",
+    "/ping",
+    mockEvent,
+  )) as { pong: boolean };
+  assert.equal(res.pong, true);
+});
+
+test("PluginManager routes WebSocket messages and enforces the capability", async () => {
+  const manager = createTestManager();
+  let received: unknown;
+
+  const plugin: ServerPlugin = {
+    metadata: {
+      id: "ws-plugin",
+      name: "WS Plugin",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      capabilities: ["websocket"],
+    },
+    init: (ctx: PluginContext) => {
+      ctx.registerWebSocket("ws:test", (message, socket) => {
+        received = message;
+        socket.send({ ok: true });
+      });
+    },
+  };
+  await manager.registerPlugin(plugin);
+
+  const sent: unknown[] = [];
+  const handled = await manager.dispatchWebSocket(
+    "ws:test",
+    { hello: 1 },
+    { send: (data) => sent.push(data) },
+  );
+  assert.equal(handled, true);
+  assert.deepEqual(received, { hello: 1 });
+  assert.deepEqual(sent, [{ ok: true }]);
+  assert.equal(
+    await manager.dispatchWebSocket("ws:missing", {}, { send: () => {} }),
+    false,
+  );
+
+  // Verify public channel registration
+  assert.equal(manager.isPublicChannel("ws:test"), false);
+  const publicPlugin: ServerPlugin = {
+    metadata: {
+      id: "public-ws-plugin",
+      name: "Public WS Plugin",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      capabilities: ["websocket"],
+    },
+    init: (ctx: PluginContext) => {
+      ctx.registerWebSocket("ws:public", () => {}, { public: true });
+      ctx.registerPublicWebSocketChannel("ws:explicit-public");
+    },
+  };
+  await manager.registerPlugin(publicPlugin);
+  assert.equal(manager.isPublicChannel("ws:public"), true);
+  assert.equal(manager.isPublicChannel("ws:explicit-public"), true);
+  assert.equal(manager.isPublicChannel("ws:other"), false);
+
+  await manager.unregisterPlugin("public-ws-plugin");
+  assert.equal(manager.isPublicChannel("ws:public"), false);
+  assert.equal(manager.isPublicChannel("ws:explicit-public"), false);
+
+  // Missing capability fails closed at registration.
+  const bad: ServerPlugin = {
+    metadata: {
+      id: "no-ws",
+      name: "No WS",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      capabilities: ["routes"],
+    },
+    init: (ctx: PluginContext) => {
+      ctx.registerWebSocket("x", () => {});
+    },
+  };
+  await assert.rejects(() => manager.registerPlugin(bad), {
+    name: "PluginCapabilityError",
+  });
+});
+
+test("discovery verifies external bundle checksums", async () => {
+  const dataDir = tmpDataDir();
+  const pluginDir = path.join(dataDir, "plugins", "external-demo");
+  await fs.mkdir(pluginDir, { recursive: true });
+
+  const entry =
+    "export default { metadata: { id: 'external-demo', name: 'External Demo'," +
+    " version: '1.0.0', apiVersion: 1, capabilities: ['routes'] }," +
+    " init(ctx) { ctx.registerRoute('GET', '/hello', () => ({ ok: true })); } };\n";
+  const entryPath = path.join(pluginDir, "index.mjs");
+  await fs.writeFile(entryPath, entry);
+  const checksum = createHash("sha256").update(entry).digest("hex");
+  await fs.writeFile(
+    path.join(pluginDir, "drop-plugin.json"),
+    JSON.stringify({
+      id: "external-demo",
+      name: "External Demo",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      capabilities: ["routes"],
+      entry: "index.mjs",
+      checksum,
+    }),
+  );
+
+  const manager = new PluginManager({
+    dataDir,
+    storageFactory: () => new MemoryStorage(),
+    authResolver: async () => ({}),
+  });
+  await manager.discoverAndLoadExternalPlugins();
+  assert.equal(
+    manager.listPlugins().find((p) => p.id === "external-demo")?.status,
+    "active",
+  );
+
+  // Tamper with the entry: the checksum mismatch must skip the bundle.
+  await fs.writeFile(entryPath, `${entry}// tampered\n`);
+  const manager2 = new PluginManager({
+    dataDir,
+    storageFactory: () => new MemoryStorage(),
+    authResolver: async () => ({}),
+  });
+  await manager2.discoverAndLoadExternalPlugins();
+  assert.equal(
+    manager2.listPlugins().find((p) => p.id === "external-demo"),
+    undefined,
+  );
+});
+
+test("PluginRegistry enforces the allow-list and version pinning", async () => {
+  const dataDir = tmpDataDir();
+  await fs.mkdir(dataDir, { recursive: true });
+  const registryPath = path.join(dataDir, "registry.json");
+
+  const entry =
+    "export default { metadata: { id: 'pinned-demo', name: 'Pinned'," +
+    " version: '2.0.0', apiVersion: 1, capabilities: ['routes'] }," +
+    " init(ctx) { ctx.registerRoute('GET', '/x', () => ({ x: 1 })); } };\n";
+  const entryBase64 = Buffer.from(entry).toString("base64");
+  const checksum = createHash("sha256").update(entry).digest("hex");
+
+  await fs.writeFile(
+    registryPath,
+    JSON.stringify({
+      plugins: [{ id: "pinned-demo", version: "2.0.0", checksum }],
+    }),
+  );
+
+  const make = (dir: string) =>
+    new PluginManager({
+      dataDir: dir,
+      registryPath,
+      storageFactory: () => new MemoryStorage(),
+      authResolver: async () => ({}),
+    });
+
+  // Pinned id/version/checksum: allowed.
+  const manager = make(dataDir);
+  await manager.installBundle(
+    {
+      id: "pinned-demo",
+      name: "Pinned",
+      version: "2.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      capabilities: ["routes"],
+      entry: "index.js",
+      checksum,
+    },
+    entryBase64,
+  );
+  assert.equal(
+    manager.listPlugins().find((p) => p.id === "pinned-demo")?.status,
+    "active",
+  );
+
+  // Unlisted plugin: rejected.
+  await assert.rejects(
+    () =>
+      make(tmpDataDir()).installBundle(
+        {
+          id: "not-listed",
+          name: "N",
+          version: "1.0.0",
+          apiVersion: PLUGIN_API_VERSION,
+          capabilities: ["routes"],
+          entry: "index.js",
+        },
+        entryBase64,
+      ),
+    /not in the registry/,
+  );
+
+  // Wrong version: rejected.
+  await assert.rejects(
+    () =>
+      make(tmpDataDir()).installBundle(
+        {
+          id: "pinned-demo",
+          name: "Pinned",
+          version: "1.0.0",
+          apiVersion: PLUGIN_API_VERSION,
+          capabilities: ["routes"],
+          entry: "index.js",
+          checksum,
+        },
+        entryBase64,
+      ),
+    /version/,
+  );
+});
+
+test("PluginRegistry supports remote HTTP registry with pinning, install-by-URL and updates", async () => {
+  const entry =
+    "export default { metadata: { id: 'remote-demo', name: 'Remote'," +
+    " version: '2.0.0', apiVersion: 1, capabilities: ['routes'] }," +
+    " init(ctx) { ctx.registerRoute('GET', '/r', () => ({ r: 1 })); } };\n";
+  const entryBase64 = Buffer.from(entry).toString("base64");
+  const checksum = createHash("sha256").update(entry).digest("hex");
+
+  let serverPort = 0;
+  const server = http.createServer((req, res) => {
+    if (req.url === "/registry.json") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(
+        JSON.stringify({
+          plugins: [
+            {
+              id: "remote-demo",
+              version: "2.0.0",
+              checksum,
+              downloadUrl: `http://127.0.0.1:${serverPort}/bundle.json`,
+            },
+          ],
+        }),
+      );
+    } else if (req.url === "/bundle.json") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(
+        JSON.stringify({
+          manifest: {
+            id: "remote-demo",
+            name: "Remote",
+            version: "2.0.0",
+            apiVersion: PLUGIN_API_VERSION,
+            capabilities: ["routes"],
+            entry: "index.js",
+            checksum,
+          },
+          entry: entryBase64,
+        }),
+      );
+    } else {
+      res.writeHead(404);
+      res.end("Not Found");
+    }
+  });
+
+  await new Promise<void>((resolve) => {
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      if (addr && typeof addr === "object") {
+        serverPort = addr.port;
+      }
+      resolve();
+    });
+  });
+
+  try {
+    const registryUrl = `http://127.0.0.1:${serverPort}/registry.json`;
+    const dataDir = tmpDataDir();
+    const manager = new PluginManager({
+      dataDir,
+      registryPath: registryUrl,
+      storageFactory: () => new MemoryStorage(),
+      authResolver: async () => ({}),
+    });
+
+    // 1. Install by URL
+    await manager.installFromUrl(`http://127.0.0.1:${serverPort}/bundle.json`);
+    const installed = manager.listPlugins().find((p) => p.id === "remote-demo");
+    assert.equal(installed?.status, "active");
+    assert.equal(installed?.version, "2.0.0");
+
+    // 2. Unlisted or mismatched plugin rejected by remote registry
+    await assert.rejects(
+      () =>
+        manager.installBundle(
+          {
+            id: "unlisted-plugin",
+            name: "Unlisted",
+            version: "1.0.0",
+            apiVersion: PLUGIN_API_VERSION,
+            capabilities: ["routes"],
+            entry: "index.js",
+          },
+          entryBase64,
+        ),
+      /not in the registry/,
+    );
+
+    // 3. Update checking
+    const updates = await manager.checkForUpdates();
+    assert.equal(updates.length, 1);
+    assert.equal(updates[0].hasUpdate, false);
+
+    // 4. Fail closed on 404 remote registry
+    await assert.rejects(
+      () =>
+        new PluginManager({
+          dataDir: tmpDataDir(),
+          registryPath: `http://127.0.0.1:${serverPort}/nonexistent.json`,
+          storageFactory: () => new MemoryStorage(),
+          authResolver: async () => ({}),
+        }).installBundle(
+          {
+            id: "remote-demo",
+            name: "Remote",
+            version: "2.0.0",
+            apiVersion: PLUGIN_API_VERSION,
+            capabilities: ["routes"],
+            entry: "index.js",
+            checksum,
+          },
+          entryBase64,
+        ),
+      /failed to fetch remote plugin registry/,
+    );
+  } finally {
+    server.close();
+  }
+});
+
+test("PluginManager strictly refuses unsigned bundles when DROP_PLUGIN_REQUIRE_SIGNATURE=true", async () => {
+  const orig = process.env.DROP_PLUGIN_REQUIRE_SIGNATURE;
+  process.env.DROP_PLUGIN_REQUIRE_SIGNATURE = "true";
+  try {
+    const manager = createTestManager();
+    const entry =
+      "export default { metadata: { id: 'unsigned-demo', name: 'Unsigned'," +
+      " version: '1.0.0', apiVersion: 1, capabilities: ['routes'] }," +
+      " init() {} };\n";
+    const entryBase64 = Buffer.from(entry).toString("base64");
+    const checksum = createHash("sha256").update(entry).digest("hex");
+
+    await assert.rejects(
+      () =>
+        manager.installBundle(
+          {
+            id: "unsigned-demo",
+            name: "Unsigned",
+            version: "1.0.0",
+            apiVersion: PLUGIN_API_VERSION,
+            capabilities: ["routes"],
+            entry: "index.js",
+            checksum,
+          },
+          entryBase64,
+        ),
+      /bundle unsigned-demo is unsigned/,
+    );
+  } finally {
+    if (orig !== undefined) {
+      process.env.DROP_PLUGIN_REQUIRE_SIGNATURE = orig;
+    } else {
+      delete process.env.DROP_PLUGIN_REQUIRE_SIGNATURE;
+    }
+  }
+});
+
+test("PluginManager installs and removes external bundles", async () => {
+  const dataDir = tmpDataDir();
+  const manager = new PluginManager({
+    dataDir,
+    storageFactory: () => new MemoryStorage(),
+    authResolver: async () => ({}),
+  });
+
+  const entry =
+    "export default { metadata: { id: 'installed-demo', name: 'Installed'," +
+    " version: '1.0.0', apiVersion: 1, capabilities: ['routes'] }," +
+    " init(ctx) { ctx.registerRoute('GET', '/x', () => ({ x: 1 })); } };\n";
+  const entryBase64 = Buffer.from(entry).toString("base64");
+  const checksum = createHash("sha256").update(entry).digest("hex");
+
+  await manager.installBundle(
+    {
+      id: "installed-demo",
+      name: "Installed",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      capabilities: ["routes"],
+      entry: "index.js",
+      checksum,
+    },
+    entryBase64,
+  );
+  assert.equal(
+    manager.listPlugins().find((p) => p.id === "installed-demo")?.status,
+    "active",
+  );
+
+  // A tampered/incorrect checksum is rejected before anything is written.
+  await assert.rejects(
+    () =>
+      manager.installBundle(
+        {
+          id: "bad-demo",
+          name: "Bad",
+          version: "1.0.0",
+          apiVersion: PLUGIN_API_VERSION,
+          capabilities: ["routes"],
+          entry: "index.js",
+          checksum: "deadbeef",
+        },
+        entryBase64,
+      ),
+    /checksum/,
+  );
+
+  await manager.removeBundle("installed-demo");
+  assert.equal(
+    manager.listPlugins().find((p) => p.id === "installed-demo"),
+    undefined,
+  );
+
+  // Builtin plugins cannot be removed.
+  await manager.registerPlugin(new HelloWorldPlugin());
+  await assert.rejects(() => manager.removeBundle("hello-world"), /builtin/);
+});
+
+test("PluginManager installs multi-file bundles with files map", async () => {
+  const dataDir = tmpDataDir();
+  const manager = new PluginManager({
+    dataDir,
+    storageFactory: () => new MemoryStorage(),
+    authResolver: async () => ({}),
+  });
+
+  const helper = "export const val = 42;\n";
+  const helperHash = createHash("sha256").update(helper).digest("hex");
+
+  const entry =
+    "import { val } from './helper.mjs';\n" +
+    "export default { metadata: { id: 'multi-install-demo', name: 'Multi Install'," +
+    " version: '1.0.0', apiVersion: 2, capabilities: ['routes'] }," +
+    " init(ctx) { ctx.registerRoute('GET', '/check', () => ({ ok: val })); } };\n";
+  const entryHash = createHash("sha256").update(entry).digest("hex");
+
+  const filesMap = {
+    "index.mjs": Buffer.from(entry).toString("base64"),
+    "helper.mjs": Buffer.from(helper).toString("base64"),
+  };
+
+  await manager.installBundle(
+    {
+      id: "multi-install-demo",
+      name: "Multi Install",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      capabilities: ["routes"],
+      entry: "index.mjs",
+      checksum: entryHash,
+      files: {
+        "index.mjs": entryHash,
+        "helper.mjs": helperHash,
+      },
+    },
+    filesMap,
+  );
+
+  assert.equal(
+    manager.listPlugins().find((p) => p.id === "multi-install-demo")?.status,
+    "active",
+  );
+
+  // Rejects invalid file path escaping directory
+  await assert.rejects(
+    () =>
+      manager.installBundle(
+        {
+          id: "escape-demo",
+          name: "Escape",
+          version: "1.0.0",
+          apiVersion: PLUGIN_API_VERSION,
+          capabilities: ["routes"],
+        },
+        {
+          "../escaped.js": Buffer.from("console.log('escaped')").toString(
+            "base64",
+          ),
+        },
+      ),
+    /invalid bundle file path/,
+  );
+});
+
+test("PluginManager.canSubscribe enforces registered subscription authorizers", async () => {
+  const manager = createTestManager();
+  const plugin: ServerPlugin = {
+    metadata: {
+      id: "authz-demo",
+      name: "Authz",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      capabilities: ["websocket"],
+    },
+    init(ctx: PluginContext) {
+      ctx.registerSubscriptionAuthorizer(
+        (channel) => channel.startsWith("room:"),
+        (_channel, context) => context.userId === "member",
+      );
+    },
+  };
+  await manager.registerPlugin(plugin);
+
+  assert.equal(
+    await manager.canSubscribe("room:1", {
+      userId: "member",
+      userAcls: undefined,
+    }),
+    true,
+  );
+  assert.equal(
+    await manager.canSubscribe("room:1", {
+      userId: "stranger",
+      userAcls: undefined,
+    }),
+    false,
+  );
+  // Channels with no matching authorizer remain open.
+  assert.equal(
+    await manager.canSubscribe("unrelated", {
+      userId: undefined,
+      userAcls: undefined,
+    }),
+    true,
+  );
+});
+
+test("a configured but empty registry denies external plugins", async () => {
+  const dataDir = tmpDataDir();
+  await fs.mkdir(dataDir, { recursive: true });
+  const registryPath = path.join(dataDir, "registry.json");
+  await fs.writeFile(registryPath, JSON.stringify({ plugins: null }));
+
+  const manager = new PluginManager({
+    dataDir,
+    registryPath,
+    storageFactory: () => new MemoryStorage(),
+    authResolver: async () => ({}),
+  });
+
+  const entry =
+    "export default { metadata: { id: 'denied-demo', name: 'Denied'," +
+    " version: '1.0.0', apiVersion: 1 }, init() {} };\n";
+  const entryBase64 = Buffer.from(entry).toString("base64");
+  await assert.rejects(
+    () =>
+      manager.installBundle(
+        {
+          id: "denied-demo",
+          name: "Denied",
+          version: "1.0.0",
+          apiVersion: PLUGIN_API_VERSION,
+          entry: "index.js",
+        },
+        entryBase64,
+      ),
+    /not in the registry/,
+  );
+});
+
+test("multi-file bundles must declare files checksums", async () => {
+  const dataDir = tmpDataDir();
+  const pluginDir = path.join(dataDir, "plugins", "multi-demo");
+  await fs.mkdir(pluginDir, { recursive: true });
+  const entry =
+    "import { value } from './helper.mjs';\n" +
+    "export default { metadata: { id: 'multi-demo', name: 'Multi'," +
+    " version: '1.0.0', apiVersion: 1 }, init() { void value; } };\n";
+  await fs.writeFile(path.join(pluginDir, "index.mjs"), entry);
+  await fs.writeFile(
+    path.join(pluginDir, "helper.mjs"),
+    "export const value = 1;\n",
+  );
+
+  const manifest = {
+    id: "multi-demo",
+    name: "Multi",
+    version: "1.0.0",
+    apiVersion: PLUGIN_API_VERSION,
+    entry: "index.mjs",
+  };
+  await fs.writeFile(
+    path.join(pluginDir, "drop-plugin.json"),
+    JSON.stringify(manifest),
+  );
+
+  const manager = new PluginManager({
+    dataDir,
+    storageFactory: () => new MemoryStorage(),
+    authResolver: async () => ({}),
+  });
+  await manager.discoverAndLoadExternalPlugins();
+  assert.equal(
+    manager.listPlugins().find((p) => p.id === "multi-demo"),
+    undefined,
+    "an unverified multi-file bundle must not load",
+  );
+
+  const files: Record<string, string> = {};
+  for (const rel of ["index.mjs", "helper.mjs"]) {
+    files[rel] = createHash("sha256")
+      .update(await fs.readFile(path.join(pluginDir, rel)))
+      .digest("hex");
+  }
+  await fs.writeFile(
+    path.join(pluginDir, "drop-plugin.json"),
+    JSON.stringify({ ...manifest, files }),
+  );
+  const manager2 = new PluginManager({
+    dataDir,
+    storageFactory: () => new MemoryStorage(),
+    authResolver: async () => ({}),
+  });
+  await manager2.discoverAndLoadExternalPlugins();
+  assert.equal(
+    manager2.listPlugins().find((p) => p.id === "multi-demo")?.status,
+    "active",
+  );
+});
+
+test("sign-plugin output loads as a verified signed bundle", async () => {
+  const dataDir = tmpDataDir();
+  const pluginDir = path.join(dataDir, "plugins", "signed-demo");
+  await fs.mkdir(pluginDir, { recursive: true });
+  const entry =
+    "import { value } from './helper.mjs';\n" +
+    "export default { metadata: { id: 'signed-demo', name: 'Signed'," +
+    " version: '1.0.0', apiVersion: 1 }, init() { void value; } };\n";
+  await fs.writeFile(path.join(pluginDir, "index.mjs"), entry);
+  await fs.writeFile(
+    path.join(pluginDir, "helper.mjs"),
+    "export const value = 1;\n",
+  );
+  await fs.writeFile(
+    path.join(pluginDir, "drop-plugin.json"),
+    JSON.stringify({
+      id: "signed-demo",
+      name: "Signed",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      entry: "index.mjs",
+    }),
+  );
+
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const signer = path.resolve(here, "../../../../dev-tools/sign-plugin.mjs");
+  const signingKey = "test-signing-key";
+  const signed = spawnSync(process.execPath, [signer, "plugins/signed-demo"], {
+    cwd: dataDir,
+    env: { ...process.env, DROP_PLUGIN_SIGNING_KEY: signingKey },
+    encoding: "utf8",
+  });
+  assert.equal(signed.status, 0, signed.stderr);
+
+  const previousKey = process.env.DROP_PLUGIN_SIGNING_KEY;
+  process.env.DROP_PLUGIN_SIGNING_KEY = signingKey;
+  try {
+    const manager = new PluginManager({
+      dataDir,
+      storageFactory: () => new MemoryStorage(),
+      authResolver: async () => ({}),
+    });
+    await manager.discoverAndLoadExternalPlugins();
+    assert.equal(
+      manager.listPlugins().find((p) => p.id === "signed-demo")?.status,
+      "active",
+      "a correctly signed bundle must load",
+    );
+
+    // Tampering an imported file must invalidate the aggregate signature.
+    await fs.writeFile(
+      path.join(pluginDir, "helper.mjs"),
+      "export const value = 2;\n",
+    );
+    const tampered = new PluginManager({
+      dataDir,
+      storageFactory: () => new MemoryStorage(),
+      authResolver: async () => ({}),
+    });
+    await tampered.discoverAndLoadExternalPlugins();
+    assert.equal(
+      tampered.listPlugins().find((p) => p.id === "signed-demo"),
+      undefined,
+      "a tampered imported file must not load",
+    );
+  } finally {
+    if (previousKey === undefined) {
+      delete process.env.DROP_PLUGIN_SIGNING_KEY;
+    } else {
+      process.env.DROP_PLUGIN_SIGNING_KEY = previousKey;
+    }
+  }
+});
+
+test("PluginManager supports manifest v2, client targets, and getClientAssetPath", async () => {
+  const dataDir = tmpDataDir();
+  const pluginDir = path.join(dataDir, "plugins", "client-asset-demo");
+  await fs.mkdir(path.join(pluginDir, "client"), { recursive: true });
+
+  const clientJs = "export default { render() {} };\n";
+  const clientCss = ".custom-badge { color: red; }\n";
+  await fs.writeFile(path.join(pluginDir, "client", "bundle.js"), clientJs);
+  await fs.writeFile(path.join(pluginDir, "client", "bundle.css"), clientCss);
+
+  const manifest = {
+    id: "client-asset-demo",
+    name: "Client Asset Demo",
+    version: "1.0.0",
+    apiVersion: 2,
+    targets: ["client"],
+    client: {
+      entry: "client/bundle.js",
+      css: "client/bundle.css",
+      capabilities: ["ui:slot"],
+    },
+  };
+  await fs.writeFile(
+    path.join(pluginDir, "drop-plugin.json"),
+    JSON.stringify(manifest),
+  );
+
+  const manager = new PluginManager({
+    dataDir,
+    storageFactory: () => new MemoryStorage(),
+    authResolver: async () => ({}),
+  });
+
+  await manager.discoverAndLoadExternalPlugins();
+  const plugins = manager.listPlugins();
+  const found = plugins.find((p) => p.id === "client-asset-demo");
+  assert.ok(found, "client-only plugin must be registered in plugin list");
+  assert.equal(found.status, "active");
+
+  // Verify getClientAssetPath resolves legitimate files
+  const resolvedJs = await manager.getClientAssetPath(
+    "client-asset-demo",
+    "client/bundle.js",
+  );
+  assert.ok(resolvedJs);
+  assert.equal(await fs.readFile(resolvedJs, "utf-8"), clientJs);
+
+  const resolvedCss = await manager.getClientAssetPath(
+    "client-asset-demo",
+    "client/bundle.css",
+  );
+  assert.ok(resolvedCss);
+  assert.equal(await fs.readFile(resolvedCss, "utf-8"), clientCss);
+
+  // Path traversal escapes must return null
+  const escaped = await manager.getClientAssetPath(
+    "client-asset-demo",
+    "../../_state.json",
+  );
+  assert.equal(escaped, null);
+});
+
+test("signed bundle with FilePluginStorage survives storage mutations and reload", async () => {
+  const dataDir = tmpDataDir();
+  const pluginDir = path.join(dataDir, "plugins", "storage-sign-demo");
+  await fs.mkdir(pluginDir, { recursive: true });
+
+  const entry =
+    "export default { metadata: { id: 'storage-sign-demo', name: 'Storage Sign'," +
+    " version: '1.0.0', apiVersion: 2, capabilities: ['routes', 'storage'] }," +
+    " async init(ctx) { await ctx.storage.set('counter', 42); } };\n";
+  await fs.writeFile(path.join(pluginDir, "index.mjs"), entry);
+  await fs.writeFile(
+    path.join(pluginDir, "drop-plugin.json"),
+    JSON.stringify({
+      id: "storage-sign-demo",
+      name: "Storage Sign",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      capabilities: ["routes", "storage"],
+      entry: "index.mjs",
+    }),
+  );
+
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const signer = path.resolve(here, "../../../../dev-tools/sign-plugin.mjs");
+  const signingKey = "test-storage-signing-key";
+  const signed = spawnSync(
+    process.execPath,
+    [signer, "plugins/storage-sign-demo"],
+    {
+      cwd: dataDir,
+      env: { ...process.env, DROP_PLUGIN_SIGNING_KEY: signingKey },
+      encoding: "utf8",
+    },
+  );
+  assert.equal(signed.status, 0, signed.stderr);
+
+  const previousKey = process.env.DROP_PLUGIN_SIGNING_KEY;
+  const previousRequire = process.env.DROP_PLUGIN_REQUIRE_SIGNATURE;
+  process.env.DROP_PLUGIN_SIGNING_KEY = signingKey;
+  process.env.DROP_PLUGIN_REQUIRE_SIGNATURE = "true";
+
+  try {
+    // 1. Initial load & execute init() which writes to storage
+    const manager1 = new PluginManager({
+      dataDir,
+      authResolver: async () => ({}),
+    });
+    await manager1.discoverAndLoadExternalPlugins();
+    assert.equal(
+      manager1.listPlugins().find((p) => p.id === "storage-sign-demo")?.status,
+      "active",
+      "signed bundle must initialize cleanly on first load",
+    );
+
+    // Verify storage file was written outside plugins bundle directory (in plugin-data)
+    const storageFile = path.join(
+      dataDir,
+      "plugin-data",
+      "storage-sign-demo",
+      "state.json",
+    );
+    assert.ok(
+      await fs
+        .access(storageFile)
+        .then(() => true)
+        .catch(() => false),
+      "storage file must be in plugin-data",
+    );
+
+    // 2. Simulate server restart: new manager, reload plugins
+    const manager2 = new PluginManager({
+      dataDir,
+      authResolver: async () => ({}),
+    });
+    await manager2.discoverAndLoadExternalPlugins();
+    assert.equal(
+      manager2.listPlugins().find((p) => p.id === "storage-sign-demo")?.status,
+      "active",
+      "signed bundle must remain active on reload after writing to storage",
+    );
+  } finally {
+    if (previousKey === undefined) {
+      delete process.env.DROP_PLUGIN_SIGNING_KEY;
+    } else {
+      process.env.DROP_PLUGIN_SIGNING_KEY = previousKey;
+    }
+    if (previousRequire === undefined) {
+      delete process.env.DROP_PLUGIN_REQUIRE_SIGNATURE;
+    } else {
+      process.env.DROP_PLUGIN_REQUIRE_SIGNATURE = previousRequire;
+    }
+  }
+});
diff --git a/server/server/internal/plugins/__tests__/upstream_compatibility.test.ts b/server/server/internal/plugins/__tests__/upstream_compatibility.test.ts
new file mode 100644
index 000000000..db6352c9c
--- /dev/null
+++ b/server/server/internal/plugins/__tests__/upstream_compatibility.test.ts
@@ -0,0 +1,166 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { PluginManager } from "../manager";
+import {
+  PLUGIN_API_VERSION,
+  type ServerPlugin,
+  type PluginContext,
+} from "../types";
+
+function tmpDataDir(): string {
+  const prefix = path.join(
+    os.tmpdir(),
+    `drop-upstream-compat-${process.pid}-${Math.random().toString(36).slice(2)}`,
+  );
+  return prefix;
+}
+
+test("Upstream Invariant: Zero-plugin baseline leaves server in pure vanilla state", async (t) => {
+  const dataDir = tmpDataDir();
+  t.after(async () => {
+    await fs.rm(dataDir, { recursive: true, force: true });
+  });
+
+  const manager = new PluginManager({ dataDir });
+
+  // 1. Initial inventory must be completely empty
+  const plugins = manager.listPlugins();
+  assert.equal(
+    plugins.length,
+    0,
+    "Default plugin list should be empty when no plugins are installed",
+  );
+
+  // 2. No routes or websockets registered
+  assert.equal(
+    manager.webSocketChannels().length,
+    0,
+    "No WebSocket channels should exist by default",
+  );
+  assert.equal(
+    manager.publicWebSocketChannels().length,
+    0,
+    "No public channels should exist by default",
+  );
+
+  // 3. Dispatching to nonexistent plugin fails with 404
+  await assert.rejects(
+    () => manager.dispatch("nonexistent", "GET", "/test", {} as never),
+    (err: unknown) => (err as { statusCode?: number })?.statusCode === 404,
+    "Dispatch to missing plugin must reject with 404",
+  );
+
+  // 4. Checking updates on zero plugins yields empty list
+  const updates = await manager.checkForUpdates();
+  assert.deepEqual(
+    updates,
+    [],
+    "Zero installed plugins must yield zero update notifications",
+  );
+});
+
+test("Upstream Invariant: Dynamic public WebSocket channels function without hardcoded core identifiers", async (t) => {
+  const dataDir = tmpDataDir();
+  t.after(async () => {
+    await fs.rm(dataDir, { recursive: true, force: true });
+  });
+
+  const manager = new PluginManager({ dataDir });
+
+  const communityLobbyPlugin: ServerPlugin = {
+    metadata: {
+      id: "community-lobby",
+      name: "Community Lobby Provider",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      capabilities: ["websocket"],
+    },
+    init: (ctx: PluginContext) => {
+      // Register public channel via options
+      ctx.registerWebSocket(
+        "community:lobbies",
+        (msg, wsCtx) => {
+          wsCtx.send({ echo: msg });
+        },
+        { public: true },
+      );
+
+      // Register public channel explicitly
+      ctx.registerPublicWebSocketChannel("community:announcements");
+
+      // Register authenticated channel
+      ctx.registerWebSocket("community:private-chat", () => {});
+    },
+  };
+
+  await manager.registerPlugin(communityLobbyPlugin);
+
+  // Public channels are accessible without auth
+  assert.equal(manager.isPublicChannel("community:lobbies"), true);
+  assert.equal(manager.isPublicChannel("community:announcements"), true);
+  assert.equal(manager.isPublicChannel("community:private-chat"), false);
+  assert.equal(
+    manager.isPublicChannel("unregistered:public-channel"),
+    false,
+    "unregistered channels must not be marked as public",
+  );
+
+  // Unregistering cleanly wipes out public channel designations
+  await manager.unregisterPlugin("community-lobby");
+  assert.equal(manager.isPublicChannel("community:lobbies"), false);
+  assert.equal(manager.isPublicChannel("community:announcements"), false);
+});
+
+test("Upstream Invariant: Plugin lifecycle isolation leaves zero residual state upon uninstall", async (t) => {
+  const dataDir = tmpDataDir();
+  t.after(async () => {
+    await fs.rm(dataDir, { recursive: true, force: true });
+  });
+
+  const manager = new PluginManager({ dataDir });
+
+  let eventCount = 0;
+  const samplePlugin: ServerPlugin = {
+    metadata: {
+      id: "lifecycle-isolated",
+      name: "Lifecycle Isolated Plugin",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      capabilities: ["routes", "websocket", "events", "storage"],
+    },
+    init: (ctx: PluginContext) => {
+      ctx.registerRoute("GET", "/ping", () => ({ status: "ok" }));
+      ctx.registerWebSocket("isolated:ws", () => {}, { public: true });
+      ctx.subscribe("core:ping", () => {
+        eventCount++;
+      });
+    },
+  };
+
+  await manager.registerPlugin(samplePlugin);
+  assert.equal(manager.listPlugins().length, 1);
+  assert.equal(manager.isPublicChannel("isolated:ws"), true);
+
+  // Broadcast event received
+  manager.broadcast("core:ping", {});
+  assert.equal(eventCount, 1);
+
+  // Unregister plugin
+  await manager.unregisterPlugin("lifecycle-isolated");
+
+  // Verify zero residue
+  assert.equal(manager.listPlugins().length, 0);
+  assert.equal(manager.isPublicChannel("isolated:ws"), false);
+  assert.equal(manager.webSocketChannels().includes("isolated:ws"), false);
+
+  // Further broadcasts are not received
+  manager.broadcast("core:ping", {});
+  assert.equal(
+    eventCount,
+    1,
+    "Unregistered plugin must not receive subsequent broadcasts",
+  );
+});
diff --git a/server/server/internal/plugins/auth.ts b/server/server/internal/plugins/auth.ts
new file mode 100644
index 000000000..e105e9575
--- /dev/null
+++ b/server/server/internal/plugins/auth.ts
@@ -0,0 +1,119 @@
+import jwt from "jsonwebtoken";
+import type { MinimumRequestObject } from "~/server/h3";
+
+export type PluginAuthContext = {
+  userId?: string;
+  userAcls?: string[];
+};
+
+const JWT_TIME_WIGGLE = 30_000;
+
+export type ClientJwtDeps = {
+  fetchCertificate: (
+    clientId: string,
+  ) => Promise<{ cert: string } | undefined | null>;
+  fetchUser: (
+    userId: string,
+  ) => Promise<{ id: string; admin: boolean } | undefined | null>;
+};
+
+/**
+ * Parses the desktop client `Authorization: JWT <clientId> <jwt>` header.
+ * Returns undefined for any other scheme or malformed value.
+ */
+export function parseClientJwtHeader(
+  header: string | null | undefined,
+): { clientId: string; token: string } | undefined {
+  if (!header) return undefined;
+  const [method, clientId, token] = header.split(" ");
+  if (method !== "JWT" || !clientId || !token) return undefined;
+  return { clientId, token };
+}
+
+/**
+ * Resolves the authenticated user from a desktop client JWT, matching the
+ * semantics of `defineClientEventHandler` (certificate lookup, blacklist
+ * check, ES384 verification).
+ */
+export async function resolveClientJwt(
+  request: MinimumRequestObject,
+  deps?: ClientJwtDeps,
+): Promise<string | undefined> {
+  const parsed = parseClientJwtHeader(request.headers.get("Authorization"));
+  if (!parsed) return undefined;
+
+  const effectiveDeps = deps ?? (await defaultClientJwtDeps());
+  const certBundle = await effectiveDeps.fetchCertificate(parsed.clientId);
+  if (!certBundle) return undefined;
+
+  try {
+    jwt.verify(parsed.token, certBundle.cert, {
+      clockTolerance: JWT_TIME_WIGGLE,
+    });
+  } catch {
+    return undefined;
+  }
+
+  const client = await effectiveDeps.fetchUser(parsed.clientId);
+  return client?.id;
+}
+
+async function defaultClientJwtDeps(): Promise<ClientJwtDeps> {
+  const { useCertificateAuthority } = await import("../../plugins/ca");
+  const { default: prisma } = await import("../db/database");
+
+  return {
+    fetchCertificate: async (clientId) => {
+      const certificateAuthority = useCertificateAuthority();
+      return await certificateAuthority.fetchClientCertificate(clientId);
+    },
+    // The client JWT identifies a client; the client is owned by a user.
+    fetchUser: async (clientId) => {
+      const client = await prisma.client.findUnique({
+        where: { id: clientId },
+        select: { user: { select: { id: true, admin: true } } },
+      });
+      return client?.user;
+    },
+  };
+}
+
+/**
+ * Resolves plugin route/WS identity. Session cookies and `Bearer` API tokens
+ * are handled by the ACL manager; desktop clients authenticate with the
+ * `JWT` scheme instead.
+ */
+export async function resolvePluginAuth(
+  request: MinimumRequestObject,
+): Promise<PluginAuthContext> {
+  const { default: aclManager } = await import("../acls");
+
+  // `getUserIdACL(..., [])` resolves sessions only; Bearer API tokens are
+  // resolved separately so a valid token authenticates plugin routes/WS (the
+  // previous empty-ACL call silently rejected every Bearer token).
+  const sessionUserId =
+    (await aclManager.getUserIdACL(request, [])) ??
+    (await aclManager.getUserIdFromBearer(request));
+  if (sessionUserId) {
+    const allAcls = await aclManager.fetchAllACLs(request);
+    return {
+      userId: sessionUserId,
+      userAcls: allAcls ? Array.from(allAcls) : undefined,
+    };
+  }
+
+  const jwtUserId = await resolveClientJwt(request);
+  if (!jwtUserId) return {};
+
+  const { default: prisma } = await import("../db/database");
+  const { userACLs, systemACLs } = await import("../acls");
+  const user = await prisma.user.findUnique({ where: { id: jwtUserId } });
+  if (!user) return {};
+
+  const acls: string[] = userACLs.map((acl) => `user:${acl}`);
+  if (user.admin) {
+    acls.push(...systemACLs.map((acl) => `system:${acl}`));
+  }
+
+  return { userId: jwtUserId, userAcls: acls };
+}
diff --git a/server/server/internal/plugins/builtin/hello-world.ts b/server/server/internal/plugins/builtin/hello-world.ts
new file mode 100644
index 000000000..8db203ce3
--- /dev/null
+++ b/server/server/internal/plugins/builtin/hello-world.ts
@@ -0,0 +1,26 @@
+import { PLUGIN_API_VERSION } from "../types";
+import type { PluginContext, PluginMetadata, ServerPlugin } from "../types";
+
+/**
+ * Minimal reference plugin. Demonstrates that creating an extension
+ * requires only a manifest and a route handler.
+ */
+export class HelloWorldPlugin implements ServerPlugin {
+  metadata: PluginMetadata = {
+    id: "hello-world",
+    name: "Hello World",
+    version: "1.0.0",
+    description: "Reference plugin that answers GET /ping",
+    author: "Drop Contributors",
+    builtin: true,
+    apiVersion: PLUGIN_API_VERSION,
+    trust: "trusted",
+    capabilities: ["routes"],
+  };
+
+  init(ctx: PluginContext): void {
+    ctx.registerRoute("GET", "/ping", () => ({ pong: true }));
+  }
+}
+
+export const helloWorldPlugin = new HelloWorldPlugin();
diff --git a/server/server/internal/plugins/errors.ts b/server/server/internal/plugins/errors.ts
new file mode 100644
index 000000000..796b14bd8
--- /dev/null
+++ b/server/server/internal/plugins/errors.ts
@@ -0,0 +1,43 @@
+/** Raised when a plugin targets an incompatible plugin API version. */
+export class PluginApiVersionError extends Error {
+  constructor(
+    readonly pluginId: string,
+    readonly expected: number,
+    readonly found: number | undefined,
+  ) {
+    super(
+      `Plugin '${pluginId}' targets plugin API v${found ?? "unspecified"}; ` +
+        `this server implements v${expected}`,
+    );
+    this.name = "PluginApiVersionError";
+  }
+}
+
+/** Raised when a plugin uses a capability it did not declare. */
+export class PluginCapabilityError extends Error {
+  constructor(
+    readonly pluginId: string,
+    readonly capability: string,
+    readonly operation: string,
+  ) {
+    super(
+      `Plugin '${pluginId}' attempted '${operation}' without the ` +
+        `'${capability}' capability`,
+    );
+    this.name = "PluginCapabilityError";
+  }
+}
+
+/** Raised when a plugin requests an unsupported trust tier. */
+export class PluginTrustError extends Error {
+  constructor(
+    readonly pluginId: string,
+    readonly trust: string,
+  ) {
+    super(
+      `Plugin '${pluginId}' requested the '${trust}' trust tier, which is not ` +
+        `supported by this server`,
+    );
+    this.name = "PluginTrustError";
+  }
+}
diff --git a/server/server/internal/plugins/index.ts b/server/server/internal/plugins/index.ts
new file mode 100644
index 000000000..6e818a0c8
--- /dev/null
+++ b/server/server/internal/plugins/index.ts
@@ -0,0 +1,17 @@
+import { pluginManager } from "./manager";
+import { helloWorldPlugin } from "./builtin/hello-world";
+
+export * from "./types";
+export * from "./errors";
+export * from "./storage";
+export * from "./manager";
+export { helloWorldPlugin } from "./builtin/hello-world";
+
+export async function initPlugins(): Promise<void> {
+  // Register default built-in plugins
+  await pluginManager.registerPlugin(helloWorldPlugin);
+  // Discover and load external plugins from data directory
+  await pluginManager.discoverAndLoadExternalPlugins();
+}
+
+export default pluginManager;
diff --git a/server/server/internal/plugins/manager.ts b/server/server/internal/plugins/manager.ts
new file mode 100644
index 000000000..eb5c19f1a
--- /dev/null
+++ b/server/server/internal/plugins/manager.ts
@@ -0,0 +1,1272 @@
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import { EventEmitter } from "node:events";
+import * as path from "node:path";
+import * as fs from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+import type { H3Event } from "h3";
+import { getQuery, createError } from "h3";
+import type { Logger } from "pino";
+import { logger } from "../logging";
+import { PLUGIN_API_VERSION } from "./types";
+import {
+  PluginApiVersionError,
+  PluginCapabilityError,
+  PluginTrustError,
+} from "./errors";
+import { PluginRegistry } from "./registry";
+import type {
+  HttpMethod,
+  PluginCapability,
+  PluginContext,
+  PluginManifest,
+  PluginMetadata,
+  PluginStateRecord,
+  PluginStatus,
+  PluginStorage,
+  RouteHandler,
+  RouteHandlerContext,
+  ServerPlugin,
+  SubscriptionAuthorizer,
+  SubscriptionContext,
+  WebSocketContext,
+  WebSocketHandler,
+  WebSocketOptions,
+} from "./types";
+
+/** Resolved caller identity passed to route handlers. */
+export interface PluginAuthContext {
+  userId?: string;
+  userAcls?: string[];
+}
+
+/**
+ * Injectable dependencies. The defaults resolve Drop's runtime config and ACL
+ * manager lazily, so this module can be imported (and unit-tested) outside a
+ * Nuxt/Nitro runtime.
+ */
+export interface PluginManagerOptions {
+  /** Base data directory. Defaults to the server's configured data folder. */
+  dataDir?: string;
+  /** Per-plugin storage factory. Defaults to {@link FilePluginStorage}. */
+  storageFactory?: (pluginId: string) => PluginStorage;
+  /** Auth resolver for dispatched routes. Defaults to Drop's ACL manager. */
+  authResolver?: (event: H3Event) => Promise<PluginAuthContext>;
+  /**
+   * Path to a plugin registry JSON (allow-list + version/checksum pinning).
+   * Defaults to `DROP_PLUGIN_REGISTRY`; no registry by default.
+   */
+  registryPath?: string;
+}
+
+interface RegisteredRoute {
+  method: HttpMethod;
+  pattern: string;
+  regex: RegExp;
+  paramNames: string[];
+  handler: RouteHandler;
+}
+
+interface SubscriptionAuthorizerEntry {
+  matches: (channel: string) => boolean;
+  authorize: SubscriptionAuthorizer;
+}
+
+const PLUGIN_ID_PATTERN = /^[a-z0-9][a-z0-9._-]*$/i;
+const SHA256_HEX_PATTERN = /^[0-9a-f]{64}$/i;
+
+function isValidPluginId(id: string): boolean {
+  return id.length > 0 && id.length <= 64 && PLUGIN_ID_PATTERN.test(id);
+}
+
+/** Whether a bundle-relative path is executable plugin code. */
+function isBundleCodeFile(rel: string): boolean {
+  const ext = path.extname(rel).toLowerCase();
+  return ext === ".js" || ext === ".mjs" || ext === ".cjs";
+}
+
+/** True when `child` resolves inside (or equals) `parent`. */
+function isInsideDirectory(parent: string, child: string): boolean {
+  const relative = path.relative(parent, child);
+  return (
+    relative === "" ||
+    (!relative.startsWith("..") && !path.isAbsolute(relative))
+  );
+}
+
+function constantTimeEqual(left: string, right: string): boolean {
+  const a = Buffer.from(left, "utf8");
+  const b = Buffer.from(right, "utf8");
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}
+
+/** Strips trailing slashes without a backtracking-prone regular expression. */
+function trimTrailingSlashes(value: string): string {
+  let end = value.length;
+  while (end > 0 && value[end - 1] === "/") {
+    end--;
+  }
+  return value.slice(0, end);
+}
+
+/** Resolves a dynamically imported bundle's default or named plugin export. */
+function resolvePluginExport(mod: {
+  default?: unknown;
+  plugin?: unknown;
+}): ServerPlugin | null {
+  const defaultExport = mod.default as Partial<ServerPlugin> | undefined;
+  if (defaultExport && typeof defaultExport.init === "function") {
+    return defaultExport as ServerPlugin;
+  }
+  const namedExport = mod.plugin as Partial<ServerPlugin> | undefined;
+  if (namedExport && typeof namedExport.init === "function") {
+    return namedExport as ServerPlugin;
+  }
+  if (typeof mod.default === "function") {
+    return new (mod.default as new () => ServerPlugin)();
+  }
+  return null;
+}
+
+interface LoadedPlugin {
+  plugin: ServerPlugin;
+  context: PluginContext;
+  status: PluginStatus;
+  error?: Error;
+}
+
+function isIgnoredBundleFile(prefix: string, name: string): boolean {
+  if (prefix) return false;
+  return (
+    name === "drop-plugin.json" ||
+    name === "state.json" ||
+    name === "schema.json"
+  );
+}
+
+export class PluginManager {
+  private readonly plugins = new Map<string, LoadedPlugin>();
+  private readonly routes = new Map<string, RegisteredRoute[]>();
+  private readonly webSockets = new Map<
+    string,
+    { pluginId: string; handler: WebSocketHandler }
+  >();
+  private readonly publicChannels = new Map<string, string>(); // channel -> pluginId
+  private readonly subscriptionAuthorizers = new Map<
+    string,
+    SubscriptionAuthorizerEntry[]
+  >();
+  private readonly eventBus = new EventEmitter();
+  private readonly pluginEventSubscriptions = new Map<
+    string,
+    Array<() => void>
+  >();
+  private readonly log: Logger = logger.child({ name: "plugin-manager" });
+
+  constructor(private readonly options: PluginManagerOptions = {}) {
+    this.eventBus.setMaxListeners(200);
+  }
+
+  private async getDataFolder(): Promise<string> {
+    if (this.options.dataDir !== undefined) {
+      return this.options.dataDir;
+    }
+    const { systemConfig } = await import("../config/sys-conf");
+    return systemConfig.getDataFolder();
+  }
+
+  private async getStateFilePath(): Promise<string> {
+    return path.join(await this.getDataFolder(), "plugins", "_state.json");
+  }
+
+  private async getPluginsDirectory(): Promise<string> {
+    return path.join(await this.getDataFolder(), "plugins");
+  }
+
+  private async loadState(): Promise<Record<string, PluginStateRecord>> {
+    try {
+      const data = await fs.readFile(await this.getStateFilePath(), "utf-8");
+      return JSON.parse(data) as Record<string, PluginStateRecord>;
+    } catch {
+      return {};
+    }
+  }
+
+  private async saveState(
+    state: Record<string, PluginStateRecord>,
+  ): Promise<void> {
+    const filePath = await this.getStateFilePath();
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, JSON.stringify(state, null, 2), "utf-8");
+  }
+
+  private patternToRegex(pattern: string): {
+    regex: RegExp;
+    paramNames: string[];
+  } {
+    const paramNames: string[] = [];
+    const normalized = pattern.startsWith("/") ? pattern : `/${pattern}`;
+
+    const regexStr = trimTrailingSlashes(normalized)
+      .replace(/:(\w+)/g, (_, name) => {
+        paramNames.push(name);
+        return "([^/]+)";
+      })
+      .replace(/\*\*/g, "(.*)")
+      .replace(/\*/g, "([^/]+)");
+
+    return {
+      regex: new RegExp(`^${regexStr || "/"}(?:/)?$`),
+      paramNames,
+    };
+  }
+
+  private hasCapability(
+    capabilities: PluginCapability[] | undefined,
+    cap: PluginCapability,
+  ): boolean {
+    // Fail closed: a plugin that does not explicitly declare a capability
+    // cannot use it.
+    return capabilities?.includes(cap) ?? false;
+  }
+
+  private async createStorage(pluginId: string): Promise<PluginStorage> {
+    if (this.options.storageFactory) {
+      return this.options.storageFactory(pluginId);
+    }
+    const { FilePluginStorage } = await import("./storage");
+    return new FilePluginStorage(pluginId, this.options.dataDir);
+  }
+
+  /**
+   * Restrict storage access to plugins that declared the `storage` capability.
+   * Missing capability is fail-closed: every method throws rather than
+   * silently reading/writing.
+   */
+  private guardStorage(
+    pluginId: string,
+    capabilities: PluginCapability[] | undefined,
+    storage: PluginStorage,
+  ): PluginStorage {
+    if (this.hasCapability(capabilities, "storage")) {
+      return storage;
+    }
+    const deny = (operation: string): never => {
+      throw new PluginCapabilityError(pluginId, "storage", operation);
+    };
+    return {
+      get: async () => deny("storage.get"),
+      set: async () => deny("storage.set"),
+      delete: async () => deny("storage.delete"),
+      listKeys: async () => deny("storage.listKeys"),
+      getSchemaVersion: async () => deny("storage.getSchemaVersion"),
+      setSchemaVersion: async () => deny("storage.setSchemaVersion"),
+    };
+  }
+
+  private async createPluginContext(
+    plugin: ServerPlugin,
+  ): Promise<PluginContext> {
+    const id = plugin.metadata.id;
+    const capabilities = plugin.metadata.capabilities;
+    const pluginLogger = this.log.child({ plugin: id });
+    const storage = this.guardStorage(
+      id,
+      capabilities,
+      await this.createStorage(id),
+    );
+    const pluginRoutes: RegisteredRoute[] = [];
+    this.routes.set(id, pluginRoutes);
+    this.pluginEventSubscriptions.set(id, []);
+
+    return {
+      id,
+      logger: pluginLogger,
+      storage,
+      registerRoute: (
+        method: HttpMethod,
+        pattern: string,
+        handler: RouteHandler,
+      ) => {
+        if (!this.hasCapability(capabilities, "routes")) {
+          throw new PluginCapabilityError(
+            id,
+            "routes",
+            `registerRoute(${pattern})`,
+          );
+        }
+
+        const { regex, paramNames } = this.patternToRegex(pattern);
+        pluginRoutes.push({
+          method,
+          pattern,
+          regex,
+          paramNames,
+          handler,
+        });
+        pluginLogger.debug(`Registered route [${method}] ${pattern}`);
+      },
+      broadcast: (channel: string, event: unknown) => {
+        if (!this.hasCapability(capabilities, "events")) {
+          throw new PluginCapabilityError(
+            id,
+            "events",
+            `broadcast(${channel})`,
+          );
+        }
+        this.eventBus.emit(channel, event);
+      },
+      subscribe: (channel: string, listener: (event: unknown) => void) => {
+        if (!this.hasCapability(capabilities, "events")) {
+          throw new PluginCapabilityError(
+            id,
+            "events",
+            `subscribe(${channel})`,
+          );
+        }
+        this.eventBus.on(channel, listener);
+        const off = () => {
+          this.eventBus.off(channel, listener);
+        };
+        const subscriptions = this.pluginEventSubscriptions.get(id) ?? [];
+        subscriptions.push(off);
+        this.pluginEventSubscriptions.set(id, subscriptions);
+        return off;
+      },
+      registerWebSocket: (
+        channel: string,
+        handler: WebSocketHandler,
+        options?: WebSocketOptions,
+      ) => {
+        if (!this.hasCapability(capabilities, "websocket")) {
+          throw new PluginCapabilityError(
+            id,
+            "websocket",
+            `registerWebSocket(${channel})`,
+          );
+        }
+        const existing = this.webSockets.get(channel);
+        if (existing && existing.pluginId !== id) {
+          throw new Error(
+            `WebSocket channel '${channel}' is already claimed by plugin '${existing.pluginId}'`,
+          );
+        }
+        this.webSockets.set(channel, { pluginId: id, handler });
+        if (options?.public) {
+          this.publicChannels.set(channel, id);
+        }
+      },
+      registerPublicWebSocketChannel: (channel: string) => {
+        if (!this.hasCapability(capabilities, "websocket")) {
+          throw new PluginCapabilityError(
+            id,
+            "websocket",
+            `registerPublicWebSocketChannel(${channel})`,
+          );
+        }
+        this.publicChannels.set(channel, id);
+      },
+      registerSubscriptionAuthorizer: (
+        matches: (channel: string) => boolean,
+        authorize: SubscriptionAuthorizer,
+      ) => {
+        if (!this.hasCapability(capabilities, "websocket")) {
+          throw new PluginCapabilityError(
+            id,
+            "websocket",
+            "registerSubscriptionAuthorizer",
+          );
+        }
+        const entries = this.subscriptionAuthorizers.get(id) ?? [];
+        entries.push({ matches, authorize });
+        this.subscriptionAuthorizers.set(id, entries);
+      },
+      fetch: async (input: string | URL, init?: RequestInit) => {
+        if (!this.hasCapability(capabilities, "network")) {
+          throw new PluginCapabilityError(id, "network", "fetch");
+        }
+        return fetch(input, init);
+      },
+    };
+  }
+
+  /**
+   * Run a plugin's storage migrations when its recorded schema version is
+   * behind the version it declares. No-op for plugins that do not set
+   * `storageVersion`.
+   */
+  private async runStorageMigrations(
+    plugin: ServerPlugin,
+    storage: PluginStorage,
+  ): Promise<void> {
+    const target = plugin.metadata.storageVersion ?? 0;
+    if (target <= 0) return;
+    const current = await storage.getSchemaVersion();
+    if (current >= target) return;
+    if (plugin.migrateStorage) {
+      await plugin.migrateStorage(current, target, storage);
+    }
+    await storage.setSchemaVersion(target);
+  }
+
+  /**
+   * Verify an external bundle's entry file.
+   *
+   * `checksum` (if present) must match the entry file's SHA-256. Signature and
+   * whole-bundle verification happen in {@link verifyBundleFiles} and
+   * {@link verifyBundleSignature} once the bundle contents are known.
+   */
+  private verifyBundleBytes(bytes: Buffer, manifest: PluginManifest): string {
+    const digest = createHash("sha256").update(bytes).digest("hex");
+
+    if (
+      manifest.checksum &&
+      (!SHA256_HEX_PATTERN.test(manifest.checksum) ||
+        !constantTimeEqual(manifest.checksum, digest))
+    ) {
+      throw new Error(
+        `bundle checksum mismatch for ${manifest.id}: expected ${manifest.checksum}, found ${digest}`,
+      );
+    }
+    return digest;
+  }
+
+  /**
+   * Verify every importable file in a bundle and return an aggregate digest
+   * used to cache-bust the entry import.
+   *
+   * A bundle with more than one code file must declare `files` checksums; a
+   * single-file bundle may rely on the entry `checksum`. Values in `files`
+   * must match and cover every code file, so relative imports cannot smuggle
+   * unverified modules into the process.
+   */
+  private async verifyBundleFiles(
+    pluginDir: string,
+    manifest: PluginManifest,
+  ): Promise<string> {
+    const root = path.resolve(pluginDir);
+    const files = await this.listBundleFiles(root);
+    const codeFiles = files.filter(isBundleCodeFile);
+
+    if (manifest.files) {
+      await this.verifyDeclaredBundleFiles(root, files, manifest.files);
+      for (const rel of codeFiles) {
+        if (!(rel in manifest.files)) {
+          throw new Error(
+            `bundle file '${rel}' is not covered by the manifest 'files' checksums`,
+          );
+        }
+      }
+    } else if (codeFiles.length > 1) {
+      throw new Error(
+        `bundle '${manifest.id}' contains multiple code files but no 'files' checksums; refusing unverified imports`,
+      );
+    }
+
+    return await this.aggregateBundleDigest(root, files);
+  }
+
+  /** Verify every declared `files` entry against the bundle on disk. */
+  private async verifyDeclaredBundleFiles(
+    root: string,
+    files: string[],
+    declared: Record<string, string>,
+  ): Promise<void> {
+    for (const [rel, expected] of Object.entries(declared)) {
+      const resolved = path.resolve(root, rel);
+      if (path.isAbsolute(rel) || !isInsideDirectory(root, resolved)) {
+        throw new Error(`invalid bundle file path '${rel}'`);
+      }
+      if (!files.includes(rel)) {
+        throw new Error(`bundle manifest lists missing file '${rel}'`);
+      }
+      const digest = createHash("sha256")
+        .update(await fs.readFile(resolved))
+        .digest("hex");
+      if (
+        !SHA256_HEX_PATTERN.test(expected) ||
+        !constantTimeEqual(expected, digest)
+      ) {
+        throw new Error(`bundle file checksum mismatch for ${rel}`);
+      }
+    }
+  }
+
+  /** SHA-256 over every bundle file, used to cache-bust the entry import. */
+  private async aggregateBundleDigest(
+    root: string,
+    files: string[],
+  ): Promise<string> {
+    const hasher = createHash("sha256");
+    for (const rel of files) {
+      const bytes = await fs.readFile(path.join(root, rel));
+      hasher.update(rel);
+      hasher.update("\0");
+      hasher.update(String(bytes.length));
+      hasher.update("\0");
+      hasher.update(bytes);
+    }
+    return hasher.digest("hex");
+  }
+
+  /** Recursively list bundle files, ignoring installed dependencies and manifest/storage files. */
+  private async listBundleFiles(root: string, prefix = ""): Promise<string[]> {
+    const results: string[] = [];
+    const entries = await fs.readdir(path.join(root, prefix), {
+      withFileTypes: true,
+    });
+    for (const entry of entries) {
+      if (entry.isDirectory() && entry.name !== "node_modules") {
+        const subPrefix = prefix ? `${prefix}/${entry.name}` : entry.name;
+        results.push(...(await this.listBundleFiles(root, subPrefix)));
+      } else if (entry.isFile() && !isIgnoredBundleFile(prefix, entry.name)) {
+        const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+        results.push(rel);
+      }
+    }
+    return results.sort((a, b) => a.localeCompare(b));
+  }
+
+  /**
+   * Verify the bundle signature. When `files` is present the signature covers
+   * the aggregate bundle digest; otherwise it covers the entry checksum
+   * (legacy single-file bundles). `DROP_PLUGIN_REQUIRE_SIGNATURE=true` refuses
+   * unsigned bundles.
+   */
+  private verifyBundleSignature(
+    aggregateDigest: string,
+    entryDigest: string,
+    manifest: PluginManifest,
+  ): void {
+    const signingKey = process.env.DROP_PLUGIN_SIGNING_KEY;
+    if (manifest.signature) {
+      if (!signingKey) {
+        throw new Error(
+          `bundle ${manifest.id} is signed but DROP_PLUGIN_SIGNING_KEY is not set`,
+        );
+      }
+      const covered = manifest.files ? aggregateDigest : entryDigest;
+      const expected = createHmac("sha256", signingKey)
+        .update(covered)
+        .digest("hex");
+      if (
+        !SHA256_HEX_PATTERN.test(manifest.signature) ||
+        !constantTimeEqual(expected, manifest.signature)
+      ) {
+        throw new Error(`bundle signature mismatch for ${manifest.id}`);
+      }
+    } else if (process.env.DROP_PLUGIN_REQUIRE_SIGNATURE === "true") {
+      throw new Error(`bundle ${manifest.id} is unsigned`);
+    }
+  }
+
+  private async getRegistry(): Promise<PluginRegistry> {
+    const registryPath =
+      this.options.registryPath ?? process.env.DROP_PLUGIN_REGISTRY;
+    // Re-read on demand so provisioning or updating the registry file takes
+    // effect without a process restart.
+    return await PluginRegistry.load(registryPath);
+  }
+
+  /** Verify, import and register a bundle directory. */
+  private async loadExternalPluginFromDir(
+    pluginDir: string,
+    manifest: PluginManifest,
+  ): Promise<void> {
+    if (!isValidPluginId(manifest.id)) {
+      throw new Error(`invalid plugin id '${manifest.id}'`);
+    }
+
+    // Check if plugin targets server (default true for v1 or when targets includes 'server')
+    const targets = manifest.targets;
+    const targetsServer = !targets || targets.includes("server");
+    const entryRel = manifest.server?.entry || manifest.entry || "index.js";
+    const entryPath = path.resolve(pluginDir, entryRel);
+    if (
+      targetsServer &&
+      (path.isAbsolute(entryRel) ||
+        !isInsideDirectory(path.resolve(pluginDir), entryPath))
+    ) {
+      throw new Error(`invalid entry path '${entryRel}'`);
+    }
+
+    // Validate the declared contract *before* importing: a dynamic import runs
+    // the module's top-level code, so compatibility must be checked on the
+    // manifest, not after the module has already executed.
+    this.assertManifestCompatible(manifest);
+
+    let entryDigest = "";
+    if (targetsServer) {
+      entryDigest = this.verifyBundleBytes(
+        await fs.readFile(entryPath),
+        manifest,
+      );
+    }
+    const aggregateDigest = await this.verifyBundleFiles(pluginDir, manifest);
+    this.verifyBundleSignature(aggregateDigest, entryDigest, manifest);
+    (await this.getRegistry()).check(manifest, entryDigest);
+
+    if (targetsServer) {
+      // Version the import URL by the whole-bundle digest so a change to any
+      // file (not just the entry) forces a fresh entry module instance.
+      const mod = await import(
+        `${pathToFileURL(entryPath).href}?v=${aggregateDigest}`
+      );
+      const pluginInstance = resolvePluginExport(mod);
+
+      if (!pluginInstance) {
+        throw new Error(
+          `Plugin module at ${entryPath} does not export a valid ServerPlugin`,
+        );
+      }
+
+      pluginInstance.metadata = {
+        ...manifest,
+        builtin: false,
+      };
+
+      await this.registerPlugin(pluginInstance);
+    } else {
+      // Client-only plugin registered for discovery and asset serving
+      const clientOnlyPlugin: ServerPlugin = {
+        metadata: {
+          ...manifest,
+          builtin: false,
+        },
+        init: () => {},
+      };
+      await this.registerPlugin(clientOnlyPlugin);
+    }
+  }
+
+  /**
+   * Resolve an on-disk asset for client-side bundle serving.
+   * Path traversal or symlink escapes outside the plugin directory return null.
+   */
+  async getClientAssetPath(
+    pluginId: string,
+    assetRelPath: string,
+  ): Promise<string | null> {
+    if (!isValidPluginId(pluginId)) return null;
+    const pluginDir = path.join(await this.getPluginsDirectory(), pluginId);
+    const resolved = path.resolve(pluginDir, assetRelPath);
+    if (!isInsideDirectory(path.resolve(pluginDir), resolved)) {
+      return null;
+    }
+    try {
+      const s = await fs.stat(resolved);
+      if (s.isFile()) {
+        return resolved;
+      }
+    } catch {
+      return null;
+    }
+    return null;
+  }
+
+  /** Validate a manifest's declared contract before importing its module. */
+  private assertManifestCompatible(manifest: PluginManifest): void {
+    const version = manifest.apiVersion ?? 0;
+    if (version !== 1 && version !== PLUGIN_API_VERSION) {
+      throw new PluginApiVersionError(manifest.id, PLUGIN_API_VERSION, version);
+    }
+    if (manifest.trust !== undefined && manifest.trust !== "trusted") {
+      throw new PluginTrustError(manifest.id, manifest.trust);
+    }
+    this.assertClientCommands(manifest);
+  }
+
+  /**
+   * Fail closed on the native-command capability: a plugin that declares
+   * `system:command` must ship a non-empty, bare-name `client.commands`
+   * allowlist. The desktop host enforces the same allowlist at run time; this
+   * rejects a malformed manifest before its module is imported.
+   */
+  private assertClientCommands(manifest: PluginManifest): void {
+    const capabilities = manifest.client?.capabilities ?? [];
+    if (!capabilities.includes("system:command")) return;
+    const commands = manifest.client?.commands;
+    if (!Array.isArray(commands) || commands.length === 0) {
+      throw new Error(
+        `plugin '${manifest.id}' declares 'system:command' but has no client.commands allowlist`,
+      );
+    }
+    for (const command of commands) {
+      if (typeof command !== "string" || command.trim().length === 0) {
+        throw new Error(
+          `plugin '${manifest.id}' has an invalid client.commands entry`,
+        );
+      }
+      if (command.includes("/") || command.includes("\\")) {
+        throw new Error(
+          `plugin '${manifest.id}' client.commands must be bare executable names`,
+        );
+      }
+    }
+  }
+
+  private assertPluginCompatible(plugin: ServerPlugin): void {
+    const { id, apiVersion, trust } = plugin.metadata;
+    const version = apiVersion ?? 0;
+    // Every plugin must declare the contract version it was built against;
+    // omitting it previously bypassed the compatibility gate entirely.
+    if (version !== 1 && version !== PLUGIN_API_VERSION) {
+      throw new PluginApiVersionError(id, PLUGIN_API_VERSION, version);
+    }
+    if (trust !== undefined && trust !== "trusted") {
+      throw new PluginTrustError(id, trust);
+    }
+  }
+
+  async registerPlugin(plugin: ServerPlugin): Promise<void> {
+    const id = plugin.metadata.id;
+    if (!isValidPluginId(id)) {
+      throw new Error(`invalid plugin id '${id}'`);
+    }
+    this.assertPluginCompatible(plugin);
+    if (this.plugins.has(id)) {
+      this.log.warn(`Plugin ${id} is already registered, replacing`);
+      await this.unregisterPlugin(id);
+    }
+
+    const state = await this.loadState();
+    const isExplicitlyDisabled = state[id]?.enabled === false;
+
+    const context = await this.createPluginContext(plugin);
+    const loaded: LoadedPlugin = {
+      plugin,
+      context,
+      status: isExplicitlyDisabled ? "disabled" : "registered",
+    };
+    this.plugins.set(id, loaded);
+
+    if (isExplicitlyDisabled) {
+      this.log.info(
+        `Plugin '${plugin.metadata.name}' (${id}) is registered but disabled by configuration`,
+      );
+      return;
+    }
+
+    await this.runStorageMigrations(plugin, context.storage);
+
+    try {
+      await plugin.init(context);
+      loaded.status = "active";
+      this.log.info(
+        `Plugin '${plugin.metadata.name}' (${id} v${plugin.metadata.version}) initialized`,
+      );
+    } catch (err) {
+      loaded.status = "error";
+      loaded.error = err as Error;
+      this.log.error(`Failed to initialize plugin ${id}: ${err}`);
+      throw err;
+    }
+  }
+
+  async unregisterPlugin(id: string): Promise<void> {
+    const loaded = this.plugins.get(id);
+    if (!loaded) return;
+
+    if (loaded.plugin.teardown && loaded.status === "active") {
+      try {
+        await loaded.plugin.teardown();
+      } catch (err) {
+        this.log.warn(`Error during plugin ${id} teardown: ${err}`);
+      }
+    }
+
+    this.releasePluginResources(id);
+    this.plugins.delete(id);
+    this.log.info(`Plugin ${id} unregistered`);
+  }
+
+  /** Drop a plugin's routes, sockets and event subscriptions. */
+  private releasePluginResources(id: string): void {
+    this.routes.delete(id);
+    for (const [channel, entry] of this.webSockets) {
+      if (entry.pluginId === id) {
+        this.webSockets.delete(channel);
+      }
+    }
+    for (const [channel, pluginId] of this.publicChannels) {
+      if (pluginId === id) {
+        this.publicChannels.delete(channel);
+      }
+    }
+    this.subscriptionAuthorizers.delete(id);
+    const subscriptions = this.pluginEventSubscriptions.get(id) ?? [];
+    for (const off of subscriptions) {
+      off();
+    }
+    this.pluginEventSubscriptions.delete(id);
+  }
+
+  async togglePlugin(id: string, enabled: boolean): Promise<boolean> {
+    const loaded = this.plugins.get(id);
+    if (!loaded) {
+      throw createError({
+        statusCode: 404,
+        statusMessage: `Plugin '${id}' not found`,
+      });
+    }
+
+    const state = await this.loadState();
+    state[id] = { enabled, updatedAt: Date.now() };
+    await this.saveState(state);
+
+    if (enabled) {
+      await this.enablePlugin(id, loaded);
+    } else {
+      await this.disablePlugin(id, loaded);
+    }
+
+    return true;
+  }
+
+  private async disablePlugin(id: string, loaded: LoadedPlugin): Promise<void> {
+    if (loaded.status !== "active") return;
+
+    if (loaded.plugin.teardown) {
+      try {
+        await loaded.plugin.teardown();
+      } catch (err) {
+        this.log.warn(`Error tearing down plugin ${id}: ${err}`);
+      }
+    }
+    this.releasePluginResources(id);
+    loaded.status = "disabled";
+    this.log.info(`Plugin '${id}' disabled`);
+    this.broadcast("plugins:state", { id, enabled: false });
+  }
+
+  private async enablePlugin(id: string, loaded: LoadedPlugin): Promise<void> {
+    if (loaded.status === "active") return;
+
+    const context = await this.createPluginContext(loaded.plugin);
+    loaded.context = context;
+    await this.runStorageMigrations(loaded.plugin, context.storage);
+    try {
+      await loaded.plugin.init(context);
+      loaded.status = "active";
+      loaded.error = undefined;
+      this.log.info(`Plugin '${id}' enabled and initialized`);
+      this.broadcast("plugins:state", { id, enabled: true });
+    } catch (err) {
+      loaded.status = "error";
+      loaded.error = err as Error;
+      this.log.error(`Failed to re-initialize plugin ${id}: ${err}`);
+      throw err;
+    }
+  }
+
+  async discoverAndLoadExternalPlugins(): Promise<void> {
+    const pluginsDir = await this.getPluginsDirectory();
+    try {
+      await fs.mkdir(pluginsDir, { recursive: true });
+      const entries = await fs.readdir(pluginsDir, { withFileTypes: true });
+
+      for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+        await this.loadExternalPluginEntry(path.join(pluginsDir, entry.name));
+      }
+    } catch (err) {
+      this.log.debug(`External plugins directory check: ${err}`);
+    }
+  }
+
+  private async loadExternalPluginEntry(pluginDir: string): Promise<void> {
+    const manifestContent = await this.readExternalManifest(pluginDir);
+    if (!manifestContent) return;
+
+    try {
+      const manifest: PluginManifest = JSON.parse(manifestContent);
+      if (
+        !manifest.id ||
+        !manifest.name ||
+        !manifest.version ||
+        !isValidPluginId(manifest.id)
+      ) {
+        this.log.warn(`Invalid plugin manifest in ${pluginDir}`);
+        return;
+      }
+
+      if (this.plugins.has(manifest.id)) {
+        return;
+      }
+
+      await this.loadExternalPluginFromDir(pluginDir, manifest);
+    } catch (err) {
+      this.log.error(
+        `Failed to load external plugin from ${pluginDir}: ${err}`,
+      );
+    }
+  }
+
+  private async readExternalManifest(
+    pluginDir: string,
+  ): Promise<string | undefined> {
+    try {
+      return await fs.readFile(
+        path.join(pluginDir, "drop-plugin.json"),
+        "utf-8",
+      );
+    } catch {
+      try {
+        return await fs.readFile(path.join(pluginDir, "plugin.json"), "utf-8");
+      } catch {
+        return undefined;
+      }
+    }
+  }
+
+  /**
+   * Install (or update) a signed plugin bundle from its manifest and entry source
+   * or multi-file payload, verifying checksums and signatures before loading.
+   */
+  async installBundle(
+    manifest: PluginManifest,
+    entryOrFiles: string | Record<string, string>,
+  ): Promise<void> {
+    if (!manifest.id || !manifest.name || !manifest.version) {
+      throw new Error("manifest requires id, name and version");
+    }
+    if (!isValidPluginId(manifest.id)) {
+      throw new Error("invalid plugin id");
+    }
+
+    const pluginsDir = await this.getPluginsDirectory();
+    const bundleDir = path.join(pluginsDir, manifest.id);
+    await fs.mkdir(bundleDir, { recursive: true });
+
+    if (typeof entryOrFiles === "string") {
+      const bytes = Buffer.from(entryOrFiles, "base64");
+      const digest = this.verifyBundleBytes(bytes, manifest);
+      (await this.getRegistry()).check(manifest, digest);
+
+      const entryRel = manifest.entry || "index.js";
+      const entryPath = path.resolve(bundleDir, entryRel);
+      if (
+        path.isAbsolute(entryRel) ||
+        !isInsideDirectory(path.resolve(bundleDir), entryPath)
+      ) {
+        throw new Error("invalid entry path");
+      }
+
+      await fs.mkdir(path.dirname(entryPath), { recursive: true });
+      const storedManifest: PluginManifest = {
+        ...manifest,
+        checksum: manifest.checksum ?? digest,
+      };
+      await fs.writeFile(
+        path.join(bundleDir, "drop-plugin.json"),
+        JSON.stringify(storedManifest, null, 2),
+      );
+      await fs.writeFile(entryPath, bytes);
+
+      await this.loadExternalPluginFromDir(bundleDir, storedManifest);
+    } else if (typeof entryOrFiles === "object" && entryOrFiles !== null) {
+      for (const [rel, base64] of Object.entries(entryOrFiles)) {
+        const resolved = path.resolve(bundleDir, rel);
+        if (
+          path.isAbsolute(rel) ||
+          !isInsideDirectory(path.resolve(bundleDir), resolved)
+        ) {
+          throw new Error(`invalid bundle file path '${rel}'`);
+        }
+        await fs.mkdir(path.dirname(resolved), { recursive: true });
+        await fs.writeFile(resolved, Buffer.from(base64, "base64"));
+      }
+
+      await fs.writeFile(
+        path.join(bundleDir, "drop-plugin.json"),
+        JSON.stringify(manifest, null, 2),
+      );
+
+      await this.loadExternalPluginFromDir(bundleDir, manifest);
+    } else {
+      throw new Error(
+        "invalid bundle payload: expected base64 entry or files map",
+      );
+    }
+  }
+
+  /**
+   * Download, verify and install a plugin bundle from a remote URL.
+   */
+  async installFromUrl(url: string): Promise<void> {
+    if (!url || typeof url !== "string") {
+      throw new Error("Invalid plugin download URL");
+    }
+    const parsed = new URL(url);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      throw new Error(
+        `Unsupported protocol in URL '${url}': only http and https are allowed`,
+      );
+    }
+
+    const res = await fetch(url, {
+      signal: AbortSignal.timeout(15000),
+      headers: { "User-Agent": "Drop-Plugin-Installer/1.0" },
+    });
+    if (!res.ok) {
+      throw new Error(
+        `Failed to download plugin from '${url}': HTTP ${res.status} ${res.statusText}`,
+      );
+    }
+
+    const text = await res.text();
+    let bundle: {
+      manifest?: PluginManifest;
+      entry?: string;
+      files?: Record<string, string>;
+      format?: string;
+    };
+    try {
+      bundle = JSON.parse(text);
+    } catch (err) {
+      throw new Error(
+        `Downloaded bundle from '${url}' is not valid JSON: ${err}`,
+      );
+    }
+
+    if (!bundle?.manifest || (!bundle.entry && !bundle.files)) {
+      throw new Error(
+        `Downloaded bundle from '${url}' missing required manifest or file payload`,
+      );
+    }
+
+    const payload = bundle.files ?? bundle.entry!;
+    await this.installBundle(bundle.manifest, payload);
+  }
+
+  /**
+   * Check installed plugins against configured registry for available updates.
+   */
+  async checkForUpdates(): Promise<
+    Array<{
+      id: string;
+      currentVersion: string;
+      latestVersion: string;
+      hasUpdate: boolean;
+      downloadUrl?: string;
+    }>
+  > {
+    const registry = await this.getRegistry();
+    if (!registry.enabled) {
+      return [];
+    }
+
+    const results: Array<{
+      id: string;
+      currentVersion: string;
+      latestVersion: string;
+      hasUpdate: boolean;
+      downloadUrl?: string;
+    }> = [];
+
+    for (const plugin of this.listPlugins()) {
+      if (plugin.builtin) continue;
+      const entry = registry.getEntry(plugin.id);
+      if (!entry?.version) continue;
+
+      const hasUpdate = entry.version !== plugin.version;
+      results.push({
+        id: plugin.id,
+        currentVersion: plugin.version,
+        latestVersion: entry.version,
+        hasUpdate,
+        downloadUrl: entry.downloadUrl ?? entry.url,
+      });
+    }
+
+    return results;
+  }
+
+  /** Remove an external plugin bundle and unregister it. */
+  async removeBundle(id: string): Promise<boolean> {
+    if (!isValidPluginId(id)) {
+      throw new Error("invalid plugin id");
+    }
+    const loaded = this.plugins.get(id);
+    if (loaded?.plugin.metadata.builtin) {
+      throw new Error("cannot remove a builtin plugin");
+    }
+
+    await this.unregisterPlugin(id);
+
+    const pluginsDir = await this.getPluginsDirectory();
+    await fs.rm(path.join(pluginsDir, id), { recursive: true, force: true });
+    return true;
+  }
+
+  async reloadPlugins(): Promise<void> {
+    this.log.info("Reloading external plugins...");
+    for (const [id, loaded] of this.plugins.entries()) {
+      if (!loaded.plugin.metadata.builtin) {
+        await this.unregisterPlugin(id);
+      }
+    }
+    await this.discoverAndLoadExternalPlugins();
+  }
+
+  listPlugins(): Array<
+    PluginMetadata & {
+      status: PluginStatus;
+      error?: string;
+    }
+  > {
+    return Array.from(this.plugins.values()).map((p) => ({
+      ...p.plugin.metadata,
+      status: p.status,
+      error: p.error?.message,
+    }));
+  }
+
+  getPlugin(id: string): ServerPlugin | undefined {
+    return this.plugins.get(id)?.plugin;
+  }
+
+  broadcast(channel: string, data: unknown): void {
+    this.eventBus.emit(channel, data);
+  }
+
+  subscribe(channel: string, listener: (data: unknown) => void): () => void {
+    this.eventBus.on(channel, listener);
+    return () => {
+      this.eventBus.off(channel, listener);
+    };
+  }
+
+  /**
+   * Whether a client may subscribe to `channel`. Only authorizers whose
+   * `matches` accepts the channel are consulted; when none match the channel
+   * is allowed (the gateway still requires authentication for non-public
+   * channels).
+   */
+  async canSubscribe(
+    channel: string,
+    context: SubscriptionContext,
+  ): Promise<boolean> {
+    const matching: SubscriptionAuthorizer[] = [];
+    for (const entries of this.subscriptionAuthorizers.values()) {
+      for (const entry of entries) {
+        if (entry.matches(channel)) matching.push(entry.authorize);
+      }
+    }
+    if (matching.length === 0) return true;
+    for (const authorize of matching) {
+      if (await authorize(channel, context)) return true;
+    }
+    return false;
+  }
+
+  /** Route a client WebSocket message to the plugin that claimed the channel. */
+  async dispatchWebSocket(
+    channel: string,
+    message: unknown,
+    context: WebSocketContext,
+  ): Promise<boolean> {
+    const entry = this.webSockets.get(channel);
+    if (!entry) return false;
+    const loaded = this.plugins.get(entry.pluginId);
+    if (loaded?.status !== "active") return false;
+    await entry.handler(message, context);
+    return true;
+  }
+
+  webSocketChannels(): string[] {
+    return Array.from(this.webSockets.keys());
+  }
+
+  isPublicChannel(channel: string): boolean {
+    return this.publicChannels.has(channel);
+  }
+
+  publicWebSocketChannels(): string[] {
+    return Array.from(this.publicChannels.keys());
+  }
+
+  private async resolveAuth(event: H3Event): Promise<PluginAuthContext> {
+    if (this.options.authResolver) {
+      return this.options.authResolver(event);
+    }
+    const { resolvePluginAuth } = await import("./auth");
+    return await resolvePluginAuth(event);
+  }
+
+  async dispatch(
+    pluginId: string,
+    method: string,
+    rawSubPath: string,
+    event: H3Event,
+  ): Promise<unknown> {
+    const loaded = this.plugins.get(pluginId);
+    if (!loaded) {
+      throw createError({
+        statusCode: 404,
+        statusMessage: `Plugin '${pluginId}' not found`,
+      });
+    }
+
+    if (loaded.status !== "active") {
+      throw createError({
+        statusCode: 503,
+        statusMessage: `Plugin '${pluginId}' is currently ${loaded.status}`,
+      });
+    }
+
+    const pluginRoutes = this.routes.get(pluginId) ?? [];
+    const normalizedPath = rawSubPath.startsWith("/")
+      ? rawSubPath
+      : `/${rawSubPath}`;
+    const cleanPath = normalizedPath.split("?")[0] || "/";
+
+    let matchedRoute: RegisteredRoute | null = null;
+    let matchedParams: Record<string, string> = {};
+
+    for (const route of pluginRoutes) {
+      if (route.method !== "ALL" && route.method !== method) {
+        continue;
+      }
+
+      const match = route.regex.exec(cleanPath);
+      if (match) {
+        matchedRoute = route;
+        matchedParams = {};
+        route.paramNames.forEach((name, idx) => {
+          matchedParams[name] = decodeURIComponent(match[idx + 1] || "");
+        });
+        break;
+      }
+    }
+
+    if (!matchedRoute) {
+      throw createError({
+        statusCode: 404,
+        statusMessage: `No handler found for [${method}] ${cleanPath} in plugin '${pluginId}'`,
+      });
+    }
+
+    let userId: string | undefined;
+    let userAcls: string[] | undefined;
+    try {
+      const auth = await this.resolveAuth(event);
+      userId = auth.userId;
+      userAcls = auth.userAcls;
+    } catch {
+      // Unauthenticated callers receive undefined userId
+    }
+
+    const context: RouteHandlerContext = {
+      params: matchedParams,
+      query: getQuery(event),
+      userId,
+      userAcls,
+    };
+
+    return await matchedRoute.handler(event, context);
+  }
+}
+
+export const pluginManager = new PluginManager();
+export default pluginManager;
diff --git a/server/server/internal/plugins/registry.ts b/server/server/internal/plugins/registry.ts
new file mode 100644
index 000000000..99578a211
--- /dev/null
+++ b/server/server/internal/plugins/registry.ts
@@ -0,0 +1,119 @@
+import fs from "node:fs/promises";
+import { timingSafeEqual } from "node:crypto";
+import type { PluginManifest } from "./types";
+
+const SHA256_HEX_PATTERN = /^[0-9a-f]{64}$/i;
+
+function constantTimeEqual(left: string, right: string): boolean {
+  const a = Buffer.from(left, "utf8");
+  const b = Buffer.from(right, "utf8");
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}
+
+/** A registry entry pins a plugin's version and/or entry checksum. */
+export interface PluginRegistryEntry {
+  id: string;
+  name?: string;
+  version?: string;
+  checksum?: string;
+  url?: string;
+  downloadUrl?: string;
+  description?: string;
+}
+
+export interface PluginRegistryData {
+  plugins: PluginRegistryEntry[];
+}
+
+/**
+ * Optional allow-list / version pinning for external plugins. When entries are
+ * present, a plugin must be listed, and any pinned version/checksum must match.
+ * An empty registry disables the check (default: trust checksum/signature).
+ */
+export class PluginRegistry {
+  /**
+   * @param strict When true (a registry file/URL is configured), the registry is
+   * authoritative even when empty: every plugin is denied. A non-strict empty
+   * registry (no file configured) disables pinning.
+   */
+  constructor(
+    private readonly entries: PluginRegistryEntry[],
+    private readonly strict = false,
+  ) {}
+
+  static async load(source: string | undefined): Promise<PluginRegistry> {
+    if (!source) return new PluginRegistry([], false);
+    let raw: string;
+    if (source.startsWith("http://") || source.startsWith("https://")) {
+      try {
+        const res = await fetch(source, {
+          signal: AbortSignal.timeout(10000),
+          headers: { "User-Agent": "Drop-Plugin-Registry/1.0" },
+        });
+        if (!res.ok) {
+          throw new Error(`HTTP ${res.status} ${res.statusText}`);
+        }
+        raw = await res.text();
+      } catch (err) {
+        // A configured remote registry that cannot be fetched must fail closed.
+        throw new Error(
+          `failed to fetch remote plugin registry '${source}': ${err}`,
+        );
+      }
+    } else {
+      try {
+        raw = await fs.readFile(source, "utf-8");
+      } catch (err) {
+        // A configured registry that cannot be read must fail closed.
+        throw new Error(`failed to read plugin registry '${source}': ${err}`);
+      }
+    }
+    let data: PluginRegistryData;
+    try {
+      data = JSON.parse(raw) as PluginRegistryData;
+    } catch (err) {
+      throw new Error(`failed to parse plugin registry '${source}': ${err}`);
+    }
+    // A syntactically valid but empty registry (`{}` / `{"plugins":null}`)
+    // must deny, not silently disable pinning.
+    return new PluginRegistry(data.plugins ?? [], true);
+  }
+
+  getEntry(id: string): PluginRegistryEntry | undefined {
+    return this.entries.find((candidate) => candidate.id === id);
+  }
+
+  listEntries(): PluginRegistryEntry[] {
+    return [...this.entries];
+  }
+
+  get enabled(): boolean {
+    return this.strict || this.entries.length > 0;
+  }
+
+  /** Throw when `manifest`/`digest` violate the registry. */
+  check(manifest: PluginManifest, digest: string): void {
+    if (!this.enabled) return;
+    const entry = this.entries.find(
+      (candidate) => candidate.id === manifest.id,
+    );
+    if (!entry) {
+      throw new Error(`plugin '${manifest.id}' is not in the registry`);
+    }
+    if (entry.version && entry.version !== manifest.version) {
+      throw new Error(
+        `plugin '${manifest.id}' version ${manifest.version} does not match pinned ${entry.version}`,
+      );
+    }
+    if (
+      entry.checksum &&
+      (!SHA256_HEX_PATTERN.test(entry.checksum) ||
+        !constantTimeEqual(entry.checksum, digest))
+    ) {
+      throw new Error(
+        `plugin '${manifest.id}' checksum does not match the registry`,
+      );
+    }
+  }
+}
diff --git a/server/server/internal/plugins/storage.ts b/server/server/internal/plugins/storage.ts
new file mode 100644
index 000000000..ce2632f8b
--- /dev/null
+++ b/server/server/internal/plugins/storage.ts
@@ -0,0 +1,138 @@
+import fs from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import type { PluginStorage } from "./types";
+
+function defaultDataFolder(): string {
+  return process.env.DATA ?? "./.data/data";
+}
+
+export class FilePluginStorage implements PluginStorage {
+  private readonly filePath: string;
+  private readonly schemaPath: string;
+  private readonly dirPath: string;
+  private readonly legacyDirPath: string;
+  private cache: Record<string, unknown> | null = null;
+  private writeLock: Promise<void> = Promise.resolve();
+  private migrationDone = false;
+
+  constructor(pluginId: string, dataDir?: string) {
+    const base = dataDir ?? defaultDataFolder();
+    this.dirPath = path.join(base, "plugin-data", pluginId);
+    this.filePath = path.join(this.dirPath, "state.json");
+    this.schemaPath = path.join(this.dirPath, "schema.json");
+    this.legacyDirPath = path.join(base, "plugins", pluginId);
+  }
+
+  private async migrateLegacyFiles(): Promise<void> {
+    if (this.migrationDone) return;
+    this.migrationDone = true;
+    try {
+      const legacyState = path.join(this.legacyDirPath, "state.json");
+      const legacySchema = path.join(this.legacyDirPath, "schema.json");
+      await fs.mkdir(this.dirPath, { recursive: true });
+
+      try {
+        await fs.access(this.filePath);
+      } catch {
+        try {
+          const content = await fs.readFile(legacyState, "utf-8");
+          await fs.writeFile(this.filePath, content, "utf-8");
+          await fs.unlink(legacyState).catch(() => {});
+        } catch {
+          // No legacy state
+        }
+      }
+
+      try {
+        await fs.access(this.schemaPath);
+      } catch {
+        try {
+          const content = await fs.readFile(legacySchema, "utf-8");
+          await fs.writeFile(this.schemaPath, content, "utf-8");
+          await fs.unlink(legacySchema).catch(() => {});
+        } catch {
+          // No legacy schema
+        }
+      }
+    } catch {
+      // Best effort migration
+    }
+  }
+
+  async getSchemaVersion(): Promise<number> {
+    await this.migrateLegacyFiles();
+    try {
+      const raw = await fs.readFile(this.schemaPath, "utf-8");
+      const parsed = JSON.parse(raw) as { version?: unknown };
+      return typeof parsed.version === "number" ? parsed.version : 0;
+    } catch {
+      return 0;
+    }
+  }
+
+  async setSchemaVersion(version: number): Promise<void> {
+    await fs.mkdir(this.dirPath, { recursive: true });
+    const tempPath = `${this.schemaPath}.tmp.${randomUUID()}`;
+    await fs.writeFile(tempPath, JSON.stringify({ version }, null, 2), "utf-8");
+    await fs.rename(tempPath, this.schemaPath);
+  }
+
+  private async load(): Promise<Record<string, unknown>> {
+    if (this.cache !== null) {
+      return this.cache;
+    }
+
+    await this.migrateLegacyFiles();
+
+    try {
+      const data = await fs.readFile(this.filePath, "utf-8");
+      this.cache = JSON.parse(data) as Record<string, unknown>;
+      return this.cache;
+    } catch {
+      this.cache = {};
+      return this.cache;
+    }
+  }
+
+  private async persist(): Promise<void> {
+    const dataToSave = JSON.stringify(this.cache ?? {}, null, 2);
+    // Recover from a failed write so the lock is not permanently poisoned.
+    this.writeLock = this.writeLock
+      .catch(() => {})
+      .then(async () => {
+        await fs.mkdir(this.dirPath, { recursive: true });
+        const tempPath = `${this.filePath}.tmp.${randomUUID()}`;
+        await fs.writeFile(tempPath, dataToSave, "utf-8");
+        await fs.rename(tempPath, this.filePath);
+      });
+    await this.writeLock;
+  }
+
+  async get<T>(key: string): Promise<T | null> {
+    const data = await this.load();
+    if (Object.hasOwn(data, key)) {
+      return data[key] as T;
+    }
+    return null;
+  }
+
+  async set<T>(key: string, value: T): Promise<void> {
+    const data = await this.load();
+    data[key] = value;
+    await this.persist();
+  }
+
+  async delete(key: string): Promise<void> {
+    const data = await this.load();
+    if (Object.hasOwn(data, key)) {
+      Reflect.deleteProperty(data, key);
+      await this.persist();
+    }
+  }
+
+  async listKeys(): Promise<string[]> {
+    const data = await this.load();
+    return Object.keys(data);
+  }
+}
diff --git a/server/server/internal/plugins/types.ts b/server/server/internal/plugins/types.ts
new file mode 100644
index 000000000..ac40709fc
--- /dev/null
+++ b/server/server/internal/plugins/types.ts
@@ -0,0 +1,220 @@
+import type { H3Event } from "h3";
+import type { Logger } from "pino";
+
+/**
+ * Current plugin API version. Bump this when `PluginContext` or the manifest
+ * contract changes incompatibly. Plugins declare the version they were built
+ * against in `metadata.apiVersion`; mismatches are rejected at registration.
+ */
+/**
+ * Current plugin API version. Bump this when `PluginContext` or the manifest
+ * contract changes incompatibly. Plugins declare the version they were built
+ * against in `metadata.apiVersion`; mismatches are rejected at registration.
+ */
+export const PLUGIN_API_VERSION = 2;
+export const SUPPORTED_API_VERSIONS = [1, 2] as const;
+
+export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "ALL";
+
+export type PluginTarget = "server" | "client";
+
+export type PluginCategory = "generic" | "metadata" | "storage" | "multiplayer";
+
+export type ServerCapability =
+  "routes" | "storage" | "websocket" | "events" | "network";
+
+export type ClientCapability =
+  | "ui:slot"
+  | "ui:play-action"
+  | "ui:context-menu"
+  | "ui:sidebar"
+  | "ui:topbar"
+  | "game:launch-hook"
+  | "game:fs"
+  | "game:scan"
+  | "client:storage"
+  | "client:ws"
+  | "system:sidecar"
+  | "system:command";
+
+export type PluginCapability = ServerCapability | ClientCapability;
+
+/**
+ * Trust tier. Only `"trusted"` is supported today: plugins run in-process with
+ * the server's own privileges. `"sandboxed"` is reserved for a future isolated
+ * runtime and must be rejected until that runtime exists.
+ */
+export type PluginTrust = "trusted" | "sandboxed";
+
+export type PluginStatus = "active" | "disabled" | "error" | "registered";
+
+export interface PluginMetadata {
+  id: string;
+  name: string;
+  version: string;
+  description?: string;
+  author?: string;
+  builtin?: boolean;
+  /** Plugin API version the plugin was built against. */
+  apiVersion?: number;
+  /** Trust tier. Defaults to "trusted". */
+  trust?: PluginTrust;
+  /** Declared storage schema version; drives `migrateStorage`. */
+  storageVersion?: number;
+  category?: PluginCategory;
+  targets?: PluginTarget[];
+  capabilities?: PluginCapability[];
+  enabled?: boolean;
+}
+
+export interface PluginManifest extends PluginMetadata {
+  entry?: string;
+  /** SHA-256 of the entry file, hex. Verified before the bundle is imported. */
+  checksum?: string;
+  /**
+   * SHA-256 of every file the bundle may import, keyed by path relative to the
+   * bundle directory. Required for multi-file bundles so relative imports are
+   * verified too. When present with `DROP_PLUGIN_SIGNING_KEY`, `signature`
+   * covers the aggregate bundle digest rather than only the entry file.
+   */
+  files?: Record<string, string>;
+  /**
+   * HMAC-SHA256 (hex) of `checksum`, keyed by `DROP_PLUGIN_SIGNING_KEY`.
+   * Set `DROP_PLUGIN_REQUIRE_SIGNATURE=true` to reject unsigned bundles.
+   */
+  signature?: string;
+
+  server?: {
+    entry: string;
+    capabilities: ServerCapability[];
+    storageVersion?: number;
+  };
+  client?: {
+    entry: string;
+    css?: string;
+    capabilities: ClientCapability[];
+    slots?: Array<{ slot: string; component: string }>;
+    /**
+     * Bare executable names the client plugin may run via `ctx.system.run`
+     * (requires the `system:command` capability). Enforced by the desktop host.
+     */
+    commands?: string[];
+  };
+}
+
+export interface PluginStateRecord {
+  enabled: boolean;
+  updatedAt: number;
+}
+
+export interface RouteHandlerContext {
+  params: Record<string, string>;
+  query: Record<string, string | string[] | undefined>;
+  userId?: string;
+  userAcls?: string[];
+}
+
+export type RouteHandler = (
+  event: H3Event,
+  context: RouteHandlerContext,
+) => unknown;
+
+export interface PluginStorage {
+  get<T>(key: string): Promise<T | null>;
+  set<T>(key: string, value: T): Promise<void>;
+  delete(key: string): Promise<void>;
+  listKeys(): Promise<string[]>;
+  /** Declared/recorded schema version for `migrateStorage`. */
+  getSchemaVersion(): Promise<number>;
+  setSchemaVersion(version: number): Promise<void>;
+}
+
+/** Caller identity + reply sink for a plugin WebSocket message. */
+export interface WebSocketContext {
+  userId?: string;
+  userAcls?: string[];
+  send: (data: unknown) => void;
+}
+
+/** Caller identity available when authorizing a channel subscription. */
+export interface SubscriptionContext {
+  userId: string | undefined;
+  userAcls: string[] | undefined;
+}
+
+/**
+ * Authorize a client subscription to a channel. Returning `false` denies the
+ * subscription; a channel with no matching authorizer is allowed (subject to
+ * the gateway's authentication requirement).
+ */
+export type SubscriptionAuthorizer = (
+  channel: string,
+  context: SubscriptionContext,
+) => Promise<boolean> | boolean;
+
+export type WebSocketHandler = (
+  message: unknown,
+  context: WebSocketContext,
+) => Promise<void> | void;
+
+export interface WebSocketOptions {
+  /**
+   * If true, clients can subscribe to and receive broadcasts on this channel
+   * without an authenticated user session (e.g. public game lobbies, server status).
+   * Defaults to false.
+   */
+  public?: boolean;
+}
+
+export interface PluginContext {
+  id: string;
+  logger: Logger;
+  storage: PluginStorage;
+  registerRoute(
+    method: HttpMethod,
+    pattern: string,
+    handler: RouteHandler,
+  ): void;
+  broadcast(channel: string, event: unknown): void;
+  subscribe(channel: string, listener: (event: unknown) => void): () => void;
+  /**
+   * Handle client messages on a WebSocket channel. Requires the `websocket`
+   * capability. Channel names are global; a channel may only be claimed once.
+   */
+  registerWebSocket(
+    channel: string,
+    handler: WebSocketHandler,
+    options?: WebSocketOptions,
+  ): void;
+  /**
+   * Mark a channel as publicly readable without authentication.
+   * Requires the `websocket` capability.
+   */
+  registerPublicWebSocketChannel(channel: string): void;
+  /**
+   * Gate client subscriptions to channels matching `matches`. Requires the
+   * `websocket` capability. Channels with no matching authorizer stay open to
+   * authenticated peers.
+   */
+  registerSubscriptionAuthorizer(
+    matches: (channel: string) => boolean,
+    authorize: SubscriptionAuthorizer,
+  ): void;
+  /** Network egress. Requires the `network` capability. */
+  fetch(input: string | URL, init?: RequestInit): Promise<Response>;
+}
+
+export interface ServerPlugin {
+  metadata: PluginMetadata;
+  init(ctx: PluginContext): Promise<void> | void;
+  teardown?(): Promise<void> | void;
+  /**
+   * Apply storage migrations when the recorded schema version is older than
+   * `metadata.storageVersion`. `from` is exclusive, `to` inclusive.
+   */
+  migrateStorage?(
+    from: number,
+    to: number,
+    storage: PluginStorage,
+  ): Promise<void>;
+}
diff --git a/server/server/plugins/08.plugin-system.ts b/server/server/plugins/08.plugin-system.ts
new file mode 100644
index 000000000..0e4777537
--- /dev/null
+++ b/server/server/plugins/08.plugin-system.ts
@@ -0,0 +1,12 @@
+import { initPlugins, pluginManager } from "../internal/plugins";
+
+export default defineNitroPlugin(async (nitro) => {
+  await initPlugins();
+
+  nitro.hooks.hookOnce("close", async () => {
+    const plugins = pluginManager.listPlugins();
+    for (const plugin of plugins) {
+      await pluginManager.unregisterPlugin(plugin.id);
+    }
+  });
+});
diff --git a/sites/docs/src/content/docs/admin/plugins.md b/sites/docs/src/content/docs/admin/plugins.md
new file mode 100644
index 000000000..c8dabe692
--- /dev/null
+++ b/sites/docs/src/content/docs/admin/plugins.md
@@ -0,0 +1,162 @@
+---
+title: Plugins
+---
+
+Drop supports an extensible plugin runtime across both the server and desktop client.
+A server plugin can register HTTP routes under `/api/v1/plugins/<id>/...`, subscribe/broadcast events, use namespaced storage, and handle WebSocket messages. Desktop client plugins can contribute UI panels, status badges, Play Actions, and game launch hooks. Plugins run **in-process**, so only install code you trust.
+
+---
+
+## Architecture & Toolchain
+
+The developer toolchain and runtime contracts are maintained in [`@droposs/plugin-sdk`](https://github.com/Heretek-Games/drop-plugin-sdk):
+
+- **SDK (`@droposs/plugin-sdk`)**: Public TypeScript contracts, JSON Schema, and mock harnesses (`MockPluginContext`, `MockClientPluginContext`).
+- **CLI (`@droposs/plugin-cli`)**: Developer CLI (`drop-plugin`) providing `init`, `build`, `test`, `validate`, `sign`, and `pack`.
+
+---
+
+## Bundle Format
+
+A plugin lives in `<dataDir>/plugins/<id>/` and contains:
+
+| File                            | Purpose                                                                                          |
+| :------------------------------ | :----------------------------------------------------------------------------------------------- |
+| `drop-plugin.json`              | Manifest: `id`, `name`, `version`, `apiVersion`, `targets`, `capabilities`, `server`, `client` … |
+| `index.js` (or `server.entry`)  | Server plugin module (default export with `init(ctx)`).                                          |
+| `client.js` (or `client.entry`) | Optional client plugin module (default export with `init(ctx)`).                                 |
+
+### `drop-plugin.json` Fields
+
+- `id`, `name`, `version` — required.
+- `apiVersion` — plugin API version (currently `2`; Drop maintains backwards compatibility with `1`).
+- `targets` — `["server"]`, `["client"]`, or `["server", "client"]`.
+- `capabilities` — explicitly declared permissions:
+  - **Server**: `routes`, `storage`, `events`, `network`, `websocket`.
+  - **Client**: `ui:slot`, `ui:play-action`, `ui:context-menu`, `ui:sidebar`, `ui:topbar`, `game:launch-hook`, `game:fs`, `game:scan`, `client:storage`, `client:ws`.
+- `entry` — relative path to primary entry point (default `index.js`).
+- `checksum` — SHA-256 hex digest of the primary entry file.
+- `files` — mapping of relative bundle file paths to their individual SHA-256 digests. Required for multi-file bundles.
+- `signature` — HMAC-SHA256 covering the aggregate bundle digest (or `checksum` for single-file bundles) under `DROP_PLUGIN_SIGNING_KEY`.
+
+---
+
+## Building, Signing & Packaging
+
+Using the Drop Plugin CLI (`@droposs/plugin-cli`):
+
+```sh
+# Bundle TypeScript server and client sources into ESM dist/
+npx @droposs/plugin-cli build .
+
+# Validate manifest against schema
+npx @droposs/plugin-cli validate .
+
+# Sign drop-plugin.json with SHA-256 digests and HMAC signature
+export DROP_PLUGIN_SIGNING_KEY="secret-key"
+npx @droposs/plugin-cli sign .
+
+# Package into a .dropplugin distribution archive
+npx @droposs/plugin-cli pack . ./dist-package
+```
+
+Set `DROP_PLUGIN_REQUIRE_SIGNATURE=true` on the server to refuse unsigned bundles.
+
+---
+
+## Registry (Allow-list, Pinning & Remote Index)
+
+Set `DROP_PLUGIN_REGISTRY` to a JSON file path or a remote HTTP/HTTPS URL (`https://.../registry.json`) to enforce an allow-list, pin exact versions, and verify aggregate bundle checksums:
+
+```json
+{
+  "plugins": [
+    {
+      "checksum": "<sha256>",
+      "downloadUrl": "https://plugins.example.com/sample-plugin.dropplugin",
+      "id": "sample-plugin",
+      "name": "Sample Plugin",
+      "version": "1.0.0"
+    }
+  ]
+}
+```
+
+- **Fail-Closed Default**: When configured, any unlisted plugin or any version/checksum mismatch is rejected at install time and load time.
+- **Remote Fetching**: The server fetches remote registries with an automatic timeout and verifies response status; unreachable registries fail closed to protect integrity.
+
+---
+
+## Signing Key Distribution & Trust Guidance
+
+By default, plugins run trusted in-process. To enforce cryptographic integrity and supply chain provenance:
+
+1. **Require Signatures**: Set `DROP_PLUGIN_REQUIRE_SIGNATURE=true` on the server. Any bundle without a cryptographic `signature` is refused immediately.
+2. **Key Distribution**: Set `DROP_PLUGIN_SIGNING_KEY="<hmac-secret>"` across build pipelines and the Drop server instance. The CLI `drop-plugin sign` signs the aggregate digest across all bundle files.
+3. **Registry Pinning**: Combine with a pinned registry index to enforce dual verification: exact SHA-256 code digest plus cryptographic HMAC signature.
+
+---
+
+## Installing Bundles
+
+### 1. Via Desktop Client Settings
+
+Navigate to **Settings → Plugins & Extensions** and click **Upload .dropplugin / JSON** to select a `.dropplugin` package, or paste the bundle JSON directly. A capability consent dialog prompts the administrator to authorize declared permissions before installation.
+
+### 2. Via Admin API (Install-by-URL or Multi-file Package)
+
+Install via `POST /api/v1/plugins/install` with an admin token:
+
+#### Install by URL:
+
+```sh
+curl -X POST "$DROP_URL/api/v1/plugins/install" \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{ "url": "https://plugins.example.com/my-plugin.dropplugin" }'
+```
+
+#### Multi-file Package / `.dropplugin` Payload:
+
+```sh
+curl -X POST "$DROP_URL/api/v1/plugins/install" \
+  -H "Authorization: Bearer $ADMIN_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "manifest": {
+      "id": "my-plugin",
+      "name": "My Plugin",
+      "version": "1.0.0",
+      "apiVersion": 2,
+      "targets": ["server"],
+      "capabilities": ["routes"],
+      "entry": "dist/index.js",
+      "files": {
+        "dist/index.js": "<sha256>"
+      }
+    },
+    "files": {
+      "dist/index.js": "<base64>"
+    }
+  }'
+```
+
+#### Filesystem Copy:
+
+Copy a bundle into `<dataDir>/plugins/<id>/` and reload:
+
+```sh
+curl -X POST "$DROP_URL/api/v1/plugins/reload" -H "Authorization: Bearer $ADMIN_TOKEN"
+```
+
+---
+
+## Management API
+
+- `GET /api/v1/plugins` — list registered plugins and lifecycle status.
+- `GET /api/v1/plugins/updates` — check installed plugins against the active registry for available version updates.
+- `PATCH /api/v1/plugins/<id>/state` `{ "enabled": true|false }` — toggle plugin active state.
+- `DELETE /api/v1/plugins/<id>/bundle` — remove an external plugin bundle from disk.
+- `POST /api/v1/plugins/reload` — reload all external bundles from disk.
+
+Built-in plugins cannot be removed.

From 7bd4707b63ba51227a854ef7e2776d39a758a502 Mon Sep 17 00:00:00 2001
From: John Smith <you@example.com>
Date: Mon, 14 Sep 2026 10:55:10 -0400
Subject: [PATCH 02/13] fix(desktop): consume plugin events through the Tauri
 event bridge

plugin_subscribe emits a Tauri event named plugin:event, but subscribe()
listened with window.addEventListener and expected a DOM CustomEvent, so
plugin WebSocket messages never reached their listeners. Register a real
Tauri listener for plugin:event (payload {channel,data}) in the Tauri host
and keep the DOM CustomEvent path as the browser/dev fallback.
---
 .../internal/plugins/ClientPluginManager.ts   | 33 +++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/desktop/main/internal/plugins/ClientPluginManager.ts b/desktop/main/internal/plugins/ClientPluginManager.ts
index 92a1c4924..e25b6093d 100644
--- a/desktop/main/internal/plugins/ClientPluginManager.ts
+++ b/desktop/main/internal/plugins/ClientPluginManager.ts
@@ -1,5 +1,6 @@
 import { reactive, ref } from "vue";
 import { invoke } from "@tauri-apps/api/core";
+import { listen } from "@tauri-apps/api/event";
 import type {
   AntiCheatReport,
   ClientPlugin,
@@ -167,11 +168,43 @@ class TauriPluginWebSocket implements ClientPluginWebSocket {
 
   subscribe(channel: string, listener: (data: unknown) => void): () => void {
     if (isTauri()) {
+      let disposed = false;
+      let unlisten: (() => void) | undefined;
+
       safeInvoke("plugin_subscribe", { channel }).catch((err) => {
         console.error(`Failed to subscribe to plugin channel ${channel}:`, err);
       });
+
+      // The Rust host forwards decoded WebSocket frames as the Tauri event
+      // `plugin:event`. Tauri events are not DOM events, so the payload must be
+      // consumed with `listen` rather than `window.addEventListener`.
+      void listen<{ channel?: string; data?: unknown }>(
+        "plugin:event",
+        (event) => {
+          if (event.payload?.channel === channel) {
+            listener(event.payload.data);
+          }
+        },
+      )
+        .then((off) => {
+          if (disposed) off();
+          else unlisten = off;
+        })
+        .catch((err) => {
+          console.error(
+            `Failed to listen for plugin events on ${channel}:`,
+            err,
+          );
+        });
+
+      return () => {
+        disposed = true;
+        unlisten?.();
+        unlisten = undefined;
+      };
     }
 
+    // Browser/dev fallback: a host harness can dispatch a DOM CustomEvent.
     const handler = (event: Event) => {
       const custom = event as CustomEvent<{ channel?: string; data?: unknown }>;
       if (custom?.detail?.channel === channel) {

From 60183f0407b3a161b9200d73f42fc5a3be6504d1 Mon Sep 17 00:00:00 2001
From: John Smith <you@example.com>
Date: Mon, 14 Sep 2026 11:19:02 -0400
Subject: [PATCH 03/13] refactor(desktop): expose a generic findFiles host
 primitive

plugin_game_check_anticheat hardcoded EAC/BattlEye/Vanguard/Denuvo names in
the generic client host. Replace it with plugin_game_find_files, which
returns installed paths matching caller-supplied patterns, and drop the
AntiCheatReport/checkAntiCheat SPI so that domain knowledge lives in the
plugin (e.g. drop-gse) rather than core.
---
 .../internal/plugins/ClientPluginManager.ts   | 13 ++--
 desktop/main/internal/plugins/types.ts        | 15 ++--
 desktop/src-tauri/src/lib.rs                  |  2 +-
 desktop/src-tauri/src/plugins.rs              | 70 ++++++++-----------
 4 files changed, 41 insertions(+), 59 deletions(-)

diff --git a/desktop/main/internal/plugins/ClientPluginManager.ts b/desktop/main/internal/plugins/ClientPluginManager.ts
index e25b6093d..a1abcb4d0 100644
--- a/desktop/main/internal/plugins/ClientPluginManager.ts
+++ b/desktop/main/internal/plugins/ClientPluginManager.ts
@@ -2,7 +2,6 @@ import { reactive, ref } from "vue";
 import { invoke } from "@tauri-apps/api/core";
 import { listen } from "@tauri-apps/api/event";
 import type {
-  AntiCheatReport,
   ClientPlugin,
   ClientPluginContext,
   ClientPluginStorage,
@@ -150,13 +149,13 @@ class TauriScopedGameScanner implements ScopedGameScanner {
     );
   }
 
-  async checkAntiCheat(gameId: string): Promise<AntiCheatReport> {
+  async findFiles(gameId: string, patterns: string[]): Promise<string[]> {
     return (
-      (await safeInvoke<AntiCheatReport>(
-        "plugin_game_check_anticheat",
-        { gameId },
-        { detected: false, files: [] },
-      )) || { detected: false, files: [] }
+      (await safeInvoke<string[]>(
+        "plugin_game_find_files",
+        { gameId, patterns },
+        [],
+      )) || []
     );
   }
 }
diff --git a/desktop/main/internal/plugins/types.ts b/desktop/main/internal/plugins/types.ts
index 8ea4a03a8..19c394e1d 100644
--- a/desktop/main/internal/plugins/types.ts
+++ b/desktop/main/internal/plugins/types.ts
@@ -88,19 +88,16 @@ export interface ScopedGameFs {
   deleteFile(gameId: string, relativePath: string): Promise<void>;
 }
 
-export interface AntiCheatReport {
-  detected: boolean;
-  reason?: string;
-  provider?: string;
-  binaries?: string[];
-  files?: string[];
-}
-
 export interface ScopedGameScanner {
   scanExecutables(
     gameId: string,
   ): Promise<Array<{ relativePath: string; sha256: string; size: number }>>;
-  checkAntiCheat(gameId: string): Promise<AntiCheatReport>;
+  /**
+   * Returns the relative paths of installed files whose path contains any of
+   * the supplied patterns (case-insensitive). The host is agnostic about the
+   * patterns, so plugins own domain knowledge such as anti-cheat detection.
+   */
+  findFiles(gameId: string, patterns: string[]): Promise<string[]>;
 }
 
 export interface ClientPluginStorage {
diff --git a/desktop/src-tauri/src/lib.rs b/desktop/src-tauri/src/lib.rs
index eea0498bb..e4d50da7a 100644
--- a/desktop/src-tauri/src/lib.rs
+++ b/desktop/src-tauri/src/lib.rs
@@ -259,7 +259,7 @@ pub fn run() {
             plugin_game_fs_exists,
             plugin_game_fs_delete,
             plugin_game_scan_executables,
-            plugin_game_check_anticheat,
+            plugin_game_find_files,
             plugin_register_commands,
             plugin_system_run,
             // Library
diff --git a/desktop/src-tauri/src/plugins.rs b/desktop/src-tauri/src/plugins.rs
index 8f5536a76..f4ca979b3 100644
--- a/desktop/src-tauri/src/plugins.rs
+++ b/desktop/src-tauri/src/plugins.rs
@@ -21,14 +21,6 @@ pub struct ScannedExecutable {
     pub size: u64,
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct AntiCheatReport {
-    pub detected: bool,
-    pub provider: Option<String>,
-    pub files: Vec<String>,
-}
-
 /// Per-plugin allowlist of bare executable names a client plugin may run via
 /// `ctx.system.run`. Populated from `manifest.client.commands` by the host when
 /// a plugin is registered; the Tauri command layer is the enforcement point so
@@ -364,51 +356,45 @@ pub async fn plugin_game_scan_executables(
     Ok(executables)
 }
 
+/// Find files inside an installed game whose relative path contains any of the
+/// supplied patterns (case-insensitive substring). The host is deliberately
+/// agnostic about what the patterns mean, so domain knowledge (e.g. which paths
+/// indicate a particular anti-cheat or compatibility tool) lives in the calling
+/// plugin, not in core. Symlinks are never followed.
 #[tauri::command]
-pub async fn plugin_game_check_anticheat(game_id: String) -> Result<AntiCheatReport, String> {
+pub async fn plugin_game_find_files(
+    game_id: String,
+    patterns: Vec<String>,
+) -> Result<Vec<String>, String> {
     let install_dir = get_game_install_dir(&game_id)?;
-    let mut detected_files = Vec::new();
-    let mut detected_provider: Option<String> = None;
 
+    let normalized: Vec<String> = patterns
+        .into_iter()
+        .map(|pattern| pattern.trim().to_ascii_lowercase())
+        .filter(|pattern| !pattern.is_empty() && pattern.len() <= 128)
+        .collect();
+    if normalized.is_empty() {
+        return Ok(Vec::new());
+    }
+
+    let mut matches = Vec::new();
     for entry in WalkDir::new(&install_dir)
         .into_iter()
         .filter_map(|e| e.ok())
     {
         let path = entry.path();
-        let path_str = path.to_string_lossy().to_lowercase();
+        if !path.is_file() || path_guard::is_symlink(path) {
+            continue;
+        }
 
-        let provider = if path_str.contains("easyanticheat")
-            || path_str.contains("eac_server")
-            || path_str.contains("easyanticheat_x64.dll")
-        {
-            Some("easyanticheat")
-        } else if path_str.contains("battleye")
-            || path_str.contains("beservice")
-            || path_str.contains("beclient")
-        {
-            Some("battleye")
-        } else if path_str.contains("vgk.sys") || path_str.contains("vgc.exe") {
-            Some("vanguard")
-        } else if path_str.contains("denuvo") || path_str.contains("dbdata.dll") {
-            Some("denuvo")
-        } else {
-            None
+        let Ok(rel) = path.strip_prefix(&install_dir) else {
+            continue;
         };
-
-        if let Some(p) = provider
-            && let Ok(rel) = path.strip_prefix(&install_dir)
-        {
-            detected_files.push(rel.to_string_lossy().to_string());
-            if detected_provider.is_none() {
-                detected_provider = Some(p.to_string());
-            }
+        let rel_str = rel.to_string_lossy().to_ascii_lowercase();
+        if normalized.iter().any(|pattern| rel_str.contains(pattern)) {
+            matches.push(rel.to_string_lossy().to_string());
         }
     }
 
-    let detected = !detected_files.is_empty();
-    Ok(AntiCheatReport {
-        detected,
-        provider: detected_provider,
-        files: detected_files,
-    })
+    Ok(matches)
 }

From 06242944575ec8112e8a4053d330ef935d109394 Mon Sep 17 00:00:00 2001
From: John Smith <you@example.com>
Date: Mon, 14 Sep 2026 11:52:47 -0400
Subject: [PATCH 04/13] fix(desktop): resolve typecheck errors blocking the
 desktop analysis job

Narrow useGame's status to Ref<GameStatus> under noUncheckedIndexedAccess so
template discriminant checks narrow correctly, guard optional index access in
LibrarySearch/queue/compat/ModalStack, and type the nuxt configs with
satisfies NuxtConfig.

GameStatusButton now declares the playActions prop and play-action emit (and
renders the menu entries) so plugin play actions type-check and actually run.
---
 desktop/main/components/GameStatusButton.vue | 27 +++++++++++++++++++-
 desktop/main/components/LibrarySearch.vue    | 13 +++++++---
 desktop/main/composables/game.ts             | 15 ++++++-----
 desktop/main/nuxt.config.ts                  | 13 +++++++---
 desktop/main/pages/queue.vue                 |  6 ++---
 desktop/main/pages/settings/compat.vue       |  2 +-
 libraries/base/components/ModalStack.vue     |  1 +
 libraries/base/nuxt.config.ts                |  4 ++-
 8 files changed, 61 insertions(+), 20 deletions(-)

diff --git a/desktop/main/components/GameStatusButton.vue b/desktop/main/components/GameStatusButton.vue
index f7ac7650a..2fe56d478 100644
--- a/desktop/main/components/GameStatusButton.vue
+++ b/desktop/main/components/GameStatusButton.vue
@@ -61,6 +61,26 @@
               </button>
             </MenuItem>
 
+            <MenuItem
+              v-for="action in playActions"
+              :key="action.id"
+              v-slot="{ active }"
+            >
+              <button
+                type="button"
+                @click="() => emit('play-action', action)"
+                :class="[
+                  active
+                    ? 'bg-zinc-800 text-zinc-100 outline-none'
+                    : 'text-zinc-300',
+                  'w-full px-4 py-2 text-sm inline-flex justify-between items-center',
+                ]"
+              >
+                {{ action.name }}
+                <PlayIcon class="size-4 text-purple-400" />
+              </button>
+            </MenuItem>
+
             <MenuItem v-if="showOptions" v-slot="{ active }">
               <button
                 @click="() => emit('options')"
@@ -113,14 +133,19 @@ import {
   InstalledType,
   type GameStatus,
 } from "~/types.js";
+import type { PlayAction } from "~/internal/plugins/types";
 import { Menu, MenuButton, MenuItem, MenuItems } from "@headlessui/vue";
 import { Cog6ToothIcon, TrashIcon } from "@heroicons/vue/24/outline";
 import { ArrowsRightLeftIcon, ArrowUpTrayIcon } from "@heroicons/vue/24/solid";
 
-const props = defineProps<{ status: GameStatus }>();
+const props = defineProps<{
+  status: GameStatus;
+  playActions?: PlayAction[];
+}>();
 const emit = defineEmits<{
   (e: "install"): void;
   (e: "launch"): void;
+  (e: "play-action", action: PlayAction): void;
   (e: "queue"): void;
   (e: "uninstall"): void;
   (e: "kill"): void;
diff --git a/desktop/main/components/LibrarySearch.vue b/desktop/main/components/LibrarySearch.vue
index 38f927aa4..a989ae8a5 100644
--- a/desktop/main/components/LibrarySearch.vue
+++ b/desktop/main/components/LibrarySearch.vue
@@ -36,7 +36,12 @@
         as="div"
         v-for="(nav, navIndex) in filteredNavigation"
         :key="nav.id"
-        :class="['first:pt-0 last:pb-0', nav.tools && !filteredNavigation[navIndex - 1].tools ? 'mt-auto' : '']"
+        :class="[
+          'first:pt-0 last:pb-0',
+          nav.tools && !filteredNavigation[navIndex - 1]?.tools
+            ? 'mt-auto'
+            : '',
+        ]"
         v-slot="{ open }"
         :default-open="nav.deft"
       >
@@ -90,10 +95,10 @@
                 <p
                   class="truncate text-[10px] font-bold uppercase font-display"
                   :class="[
-                    getGameStatusStyleText(games[item.id].status.value)[0],
+                    getGameStatusStyleText(games[item.id]!.status.value)[0],
                   ]"
                 >
-                  {{ getGameStatusStyleText(games[item.id].status.value)[1] }}
+                  {{ getGameStatusStyleText(games[item.id]!.status.value)[1] }}
                 </p>
               </div>
             </div>
@@ -295,7 +300,7 @@ await new Promise<void>((r) => {
 const navigation = computed(() =>
   collections.value.map((collection) => {
     const items = collection.entries.map(({ game }) => {
-      const status = games[game.id].status;
+      const status = games[game.id]!.status;
 
       const isInstalled = computed(() => status.value.type != "Remote");
 
diff --git a/desktop/main/composables/game.ts b/desktop/main/composables/game.ts
index 93e97af2d..0a73c2d66 100644
--- a/desktop/main/composables/game.ts
+++ b/desktop/main/composables/game.ts
@@ -14,7 +14,6 @@ const gameRegistry: { [key: string]: { game: Game; version: Ref<GameVersion | un
 const gameStatusRegistry: { [key: string]: Ref<GameStatus> } = {};
 
 export const parseStatus = (status: RawGameStatus): GameStatus => {
-  console.log(status[0]);
   if (status[0]) {
     return status[0];
   }
@@ -33,16 +32,18 @@ export const useGame = async (gameId: string) => {
     } = await invoke("fetch_game", {
       gameId,
     });
-    gameRegistry[gameId] = { game: data.game, version: ref(data.version) };
+    const entry = { game: data.game, version: ref(data.version) };
+    gameRegistry[gameId] = entry;
     if (!gameStatusRegistry[gameId]) {
-      gameStatusRegistry[gameId] = ref(parseStatus(data.status));
+      const statusRef = ref(parseStatus(data.status));
+      gameStatusRegistry[gameId] = statusRef;
 
       listen(`update_game/${gameId}`, (event) => {
         const payload: {
           status: RawGameStatus;
           version?: GameVersion;
         } = event.payload as any;
-        gameStatusRegistry[gameId].value = parseStatus(payload.status);
+        statusRef.value = parseStatus(payload.status);
 
         /**
          * I am not super happy about this.
@@ -52,14 +53,14 @@ export const useGame = async (gameId: string) => {
          * on transient state updates.
          */
         if (payload.version) {
-          gameRegistry[gameId].version.value = payload.version;
+          entry.version.value = payload.version;
         }
       });
     }
   }
 
-  const game = gameRegistry[gameId];
-  const status = gameStatusRegistry[gameId];
+  const game = gameRegistry[gameId]!;
+  const status = gameStatusRegistry[gameId]!;
   return { ...game, status };
 };
 
diff --git a/desktop/main/nuxt.config.ts b/desktop/main/nuxt.config.ts
index 72098882c..ee1aa191e 100644
--- a/desktop/main/nuxt.config.ts
+++ b/desktop/main/nuxt.config.ts
@@ -1,5 +1,7 @@
 // https://nuxt.com/docs/api/configuration/nuxt-config
-export default defineNuxtConfig({
+import type { NuxtConfig } from "nuxt/schema";
+
+export default {
   compatibilityDate: "2024-04-03",
 
   postcss: {
@@ -18,5 +20,10 @@ export default defineNuxtConfig({
 
   app: {
     baseURL: "/main",
-  }
-});
+    head: {
+      meta: [
+        { name: "viewport", content: "width=device-width, initial-scale=1.0" },
+      ],
+    },
+  },
+} satisfies NuxtConfig;
diff --git a/desktop/main/pages/queue.vue b/desktop/main/pages/queue.vue
index fe7fbd26a..fcc0d0b7d 100644
--- a/desktop/main/pages/queue.vue
+++ b/desktop/main/pages/queue.vue
@@ -33,18 +33,18 @@
           <div class="w-full flex items-center max-w-md gap-x-4 relative">
             <img
               class="size-24 flex-none bg-zinc-800 object-cover rounded"
-              :src="games[element.meta.id].cover"
+              :src="games[element.meta.id]!.cover"
               alt=""
             />
             <div class="min-w-0 flex-auto">
               <p class="text-xl font-semibold text-zinc-100">
                 <NuxtLink :href="`/library/${element.meta.id}`" class="">
                   <span class="absolute inset-x-0 -top-px bottom-0" />
-                  {{ games[element.meta.id].game.mName }}
+                  {{ games[element.meta.id]!.game.mName }}
                 </NuxtLink>
               </p>
               <p class="mt-1 flex text-xs/5 text-gray-500">
-                {{ games[element.meta.id].game.mShortDescription }}
+                {{ games[element.meta.id]!.game.mShortDescription }}
               </p>
             </div>
           </div>
diff --git a/desktop/main/pages/settings/compat.vue b/desktop/main/pages/settings/compat.vue
index 8de7dff4e..92570f33b 100644
--- a/desktop/main/pages/settings/compat.vue
+++ b/desktop/main/pages/settings/compat.vue
@@ -333,7 +333,7 @@ async function deleteCustom(index: number) {
   if (!paths.data.value) return;
   await invoke("remove_proton_layer", { index });
   const deleted = paths.data.value.custom.splice(index);
-  if (paths.data.value.default == deleted[0].path) {
+  if (deleted[0] && paths.data.value.default == deleted[0].path) {
     paths.data.value.default = undefined;
   }
 }
diff --git a/libraries/base/components/ModalStack.vue b/libraries/base/components/ModalStack.vue
index ffbd5eb16..722afbadb 100644
--- a/libraries/base/components/ModalStack.vue
+++ b/libraries/base/components/ModalStack.vue
@@ -39,6 +39,7 @@ const stack = useModalStack();
 
 async function handleCallback(modalIdx: number, event: string, args: any[]) {
   const modal = stack.value[modalIdx];
+  if (!modal) return;
   const close = () => {
     stack.value.splice(modalIdx, 1);
   };
diff --git a/libraries/base/nuxt.config.ts b/libraries/base/nuxt.config.ts
index f2602b681..9ccff262c 100644
--- a/libraries/base/nuxt.config.ts
+++ b/libraries/base/nuxt.config.ts
@@ -1,2 +1,4 @@
 // https://nuxt.com/docs/api/configuration/nuxt-config
-export default defineNuxtConfig({});
+import type { NuxtConfig } from "nuxt/schema";
+
+export default {} satisfies NuxtConfig;

From d7421a534b83e20733990c6cfb4e9daad1e2dc77 Mon Sep 17 00:00:00 2001
From: John Smith <you@example.com>
Date: Mon, 14 Sep 2026 22:58:01 -0400
Subject: [PATCH 05/13] chore(plugins): sync generic plugin runtime from
 develop

Port the upstream-ready plugin work that landed on Heretek develop after
the initial extraction: v2 bundle signatures covering the manifest,
MetadataProvider / PaymentGateway / CloudSavePathResolver SPIs, public
WebSocket channel hardening, desktop path_guard and native-command
hardening, and the associated server and desktop test suites.

Excludes fork-domain code (achievement toasts) and neutralises example
provider names in tests so the bundle stays generic.
---
 .../internal/plugins/ClientPluginManager.ts   | 120 ++++-
 .../__tests__/client_plugin_manager.test.ts   | 209 +++++++++
 .../plugins/__tests__/storeImport.test.ts     |  41 ++
 desktop/main/internal/plugins/storeImport.ts  |  32 ++
 desktop/main/internal/plugins/types.ts        | 114 ++++-
 desktop/main/package.json                     |   4 +-
 desktop/main/pnpm-lock.yaml                   |   3 +
 desktop/src-tauri/process/src/path_guard.rs   | 147 ++++++
 desktop/src-tauri/src/plugins.rs              | 121 +++--
 pnpm-lock.yaml                                |  19 +-
 server/dev-tools/sign-plugin.mjs              |  39 +-
 .../plugins/__tests__/plugins.test.ts         | 434 +++++++++++++++++-
 .../plugins/__tests__/signature.test.ts       |  68 +++
 .../__tests__/upstream_compatibility.test.ts  |  19 +-
 .../internal/plugins/builtin/hello-world.ts   |   6 +-
 server/server/internal/plugins/manager.ts     | 234 +++++++++-
 server/server/internal/plugins/signature.ts   |  45 ++
 server/server/internal/plugins/types.ts       | 158 ++++++-
 18 files changed, 1729 insertions(+), 84 deletions(-)
 create mode 100644 desktop/main/internal/plugins/__tests__/client_plugin_manager.test.ts
 create mode 100644 desktop/main/internal/plugins/__tests__/storeImport.test.ts
 create mode 100644 desktop/main/internal/plugins/storeImport.ts
 create mode 100644 server/server/internal/plugins/__tests__/signature.test.ts
 create mode 100644 server/server/internal/plugins/signature.ts

diff --git a/desktop/main/internal/plugins/ClientPluginManager.ts b/desktop/main/internal/plugins/ClientPluginManager.ts
index a1abcb4d0..e467a11a8 100644
--- a/desktop/main/internal/plugins/ClientPluginManager.ts
+++ b/desktop/main/internal/plugins/ClientPluginManager.ts
@@ -6,15 +6,18 @@ import type {
   ClientPluginContext,
   ClientPluginStorage,
   ClientPluginWebSocket,
+  CloudSavePathResolver,
   CommandResult,
   GameMenuItem,
   HttpMethod,
   LaunchContext,
   LaunchHook,
+  MetadataProvider,
   PlayAction,
   ScopedGameFs,
   ScopedGameScanner,
   SidebarItem,
+  StoreScanner,
   TopBarItem,
   UISlotName,
   UISlotRegistration,
@@ -227,6 +230,8 @@ export class ClientPluginManager {
     "settings:tabs": [],
     "topbar:status": [],
     "sidebar:nav": [],
+    "overlay:panel": [],
+    "overlay:quick-access": [],
   });
 
   public readonly playActionProviders: Array<
@@ -236,6 +241,17 @@ export class ClientPluginManager {
   public readonly sidebarItems = reactive<SidebarItem[]>([]);
   public readonly topBarItems = reactive<TopBarItem[]>([]);
   public readonly launchHooks: LaunchHook[] = [];
+  public readonly storeScanners = reactive<
+    Array<{ pluginId: string; scanner: StoreScanner }>
+  >([]);
+  public readonly metadataProviders = reactive<
+    Array<{ pluginId: string; provider: MetadataProvider }>
+  >([]);
+  public readonly cloudSaveResolvers = reactive<
+    Array<{ pluginId: string; resolver: CloudSavePathResolver }>
+  >([]);
+
+  public readonly serverWs: ClientPluginWebSocket = new TauriPluginWebSocket();
 
   public readonly isInitialized = ref(false);
 
@@ -246,6 +262,7 @@ export class ClientPluginManager {
     plugin: ClientPlugin,
     id?: string,
     commands: string[] = [],
+    capabilities: string[] = [],
   ): Promise<void> {
     const pluginId = id || plugin.metadata?.id || "anonymous-plugin";
     if (this.plugins.has(pluginId)) {
@@ -278,6 +295,9 @@ export class ClientPluginManager {
       },
       storage: new BrowserLocalStorage(pluginId),
       registerSlot: (slot, component, options) => {
+        if (!this.slots[slot]) {
+          this.slots[slot] = [];
+        }
         this.slots[slot].push({
           id: `${pluginId}-${slot}-${this.slots[slot].length}`,
           pluginId,
@@ -324,9 +344,74 @@ export class ClientPluginManager {
           if (idx !== -1) this.launchHooks.splice(idx, 1);
         };
       },
+      registerStoreScanner: (scanner: StoreScanner) => {
+        if (
+          capabilities.length > 0 &&
+          !capabilities.includes("client:library-scan")
+        ) {
+          throw new Error(
+            `Client plugin '${pluginId}' attempted 'registerStoreScanner' without the 'client:library-scan' capability`,
+          );
+        }
+        if (!scanner || typeof scanner.id !== "string" || !scanner.id.trim()) {
+          throw new Error("Store scanner must have a valid non-empty id");
+        }
+        const entry = { pluginId, scanner };
+        this.storeScanners.push(entry);
+        return () => {
+          const idx = this.storeScanners.indexOf(entry);
+          if (idx !== -1) this.storeScanners.splice(idx, 1);
+        };
+      },
+      registerMetadataProvider: (provider: MetadataProvider) => {
+        if (
+          capabilities.length > 0 &&
+          !capabilities.includes("metadata:provider")
+        ) {
+          throw new Error(
+            `Client plugin '${pluginId}' attempted 'registerMetadataProvider' without the 'metadata:provider' capability`,
+          );
+        }
+        if (
+          !provider ||
+          typeof provider.id !== "string" ||
+          !provider.id.trim()
+        ) {
+          throw new Error("Metadata provider must have a valid non-empty id");
+        }
+        const entry = { pluginId, provider };
+        this.metadataProviders.push(entry);
+        return () => {
+          const idx = this.metadataProviders.indexOf(entry);
+          if (idx !== -1) this.metadataProviders.splice(idx, 1);
+        };
+      },
+      registerCloudSaveResolver: (resolver: CloudSavePathResolver) => {
+        if (
+          capabilities.length > 0 &&
+          !capabilities.includes("cloudsave:provider")
+        ) {
+          throw new Error(
+            `Client plugin '${pluginId}' attempted 'registerCloudSaveResolver' without the 'cloudsave:provider' capability`,
+          );
+        }
+        if (
+          !resolver ||
+          typeof resolver.id !== "string" ||
+          !resolver.id.trim()
+        ) {
+          throw new Error("Cloud save resolver must have a valid non-empty id");
+        }
+        const entry = { pluginId, resolver };
+        this.cloudSaveResolvers.push(entry);
+        return () => {
+          const idx = this.cloudSaveResolvers.indexOf(entry);
+          if (idx !== -1) this.cloudSaveResolvers.splice(idx, 1);
+        };
+      },
       gameFs: new TauriScopedGameFs(),
       gameScanner: new TauriScopedGameScanner(),
-      serverWs: new TauriPluginWebSocket(),
+      serverWs: this.serverWs,
       system: {
         run: (
           bin: string,
@@ -394,6 +479,36 @@ export class ClientPluginManager {
         (s) => s.pluginId !== pluginId,
       );
     }
+
+    // Clean up store scanners and metadata providers registered by this plugin
+    this.purgeOwned(this.storeScanners, pluginId);
+    this.purgeOwned(this.metadataProviders, pluginId);
+    this.purgeOwned(this.cloudSaveResolvers, pluginId);
+  }
+
+  /** Removes every reactive entry owned by `pluginId` from `entries`. */
+  private purgeOwned<T extends { pluginId: string }>(
+    entries: T[],
+    pluginId: string,
+  ): void {
+    for (let i = entries.length - 1; i >= 0; i--) {
+      const entry = entries[i];
+      if (entry?.pluginId === pluginId) {
+        entries.splice(i, 1);
+      }
+    }
+  }
+
+  getStoreScanners(): StoreScanner[] {
+    return this.storeScanners.map((e) => e.scanner);
+  }
+
+  getMetadataProviders(): MetadataProvider[] {
+    return this.metadataProviders.map((e) => e.provider);
+  }
+
+  getCloudSaveResolvers(): CloudSavePathResolver[] {
+    return this.cloudSaveResolvers.map((e) => e.resolver);
   }
 
   /**
@@ -404,6 +519,7 @@ export class ClientPluginManager {
     bundleUrl: string,
     cssUrl?: string,
     commands: string[] = [],
+    capabilities: string[] = [],
   ): Promise<void> {
     if (cssUrl) {
       const link = document.createElement("link");
@@ -426,7 +542,7 @@ export class ClientPluginManager {
       );
     }
 
-    await this.registerPlugin(pluginExport, pluginId, commands);
+    await this.registerPlugin(pluginExport, pluginId, commands, capabilities);
   }
 
   /**
diff --git a/desktop/main/internal/plugins/__tests__/client_plugin_manager.test.ts b/desktop/main/internal/plugins/__tests__/client_plugin_manager.test.ts
new file mode 100644
index 000000000..bc0c0e8b1
--- /dev/null
+++ b/desktop/main/internal/plugins/__tests__/client_plugin_manager.test.ts
@@ -0,0 +1,209 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { ClientPluginManager } from "../ClientPluginManager";
+import type {
+  ClientPlugin,
+  ClientPluginContext,
+  CloudSavePathResolver,
+  MetadataProvider,
+  StoreScanner,
+} from "../types";
+
+test("ClientPluginManager registers overlay slots without crashing", async () => {
+  const manager = new ClientPluginManager();
+
+  const overlayPlugin: ClientPlugin = {
+    metadata: {
+      id: "overlay-hud",
+      name: "Overlay HUD",
+      version: "1.0.0",
+    },
+    init(ctx: ClientPluginContext) {
+      ctx.registerSlot("overlay:panel", { template: "<div>Panel</div>" });
+      ctx.registerSlot("overlay:quick-access", {
+        template: "<div>Access</div>",
+      });
+    },
+  };
+
+  await manager.registerPlugin(overlayPlugin, "overlay-hud", [], ["ui:slot"]);
+
+  assert.equal(manager.slots["overlay:panel"].length, 1);
+  assert.equal(manager.slots["overlay:panel"][0]?.pluginId, "overlay-hud");
+  assert.equal(manager.slots["overlay:quick-access"].length, 1);
+  assert.equal(
+    manager.slots["overlay:quick-access"][0]?.pluginId,
+    "overlay-hud",
+  );
+
+  await manager.unregisterPlugin("overlay-hud");
+  assert.equal(manager.slots["overlay:panel"].length, 0);
+  assert.equal(manager.slots["overlay:quick-access"].length, 0);
+});
+
+test("ClientPluginManager registers StoreScanner and MetadataProvider SPIs", async () => {
+  const manager = new ClientPluginManager();
+
+  const gogScanner: StoreScanner = {
+    id: "gog",
+    name: "GOG Galaxy",
+    store: "gog",
+    scan: async () => [
+      {
+        externalId: "gog-101",
+        store: "gog",
+        title: "Cyberpunk 2077",
+        installPath: "/games/cyberpunk",
+      },
+    ],
+  };
+
+  const exampleMetadataProvider: MetadataProvider = {
+    id: "example-metadata",
+    name: "Example Metadata",
+    search: async (query) => [
+      { id: "meta-1", title: query, provider: "example-metadata" },
+    ],
+    getDetails: async (id) => ({
+      id,
+      title: "Super Mario World",
+      provider: "example-metadata",
+    }),
+  };
+
+  let unregisterScanner: (() => void) | undefined;
+  let unregisterProvider: (() => void) | undefined;
+  let unregisterCloudSave: (() => void) | undefined;
+
+  const exampleCloudsaveResolver: CloudSavePathResolver = {
+    id: "example-cloudsave",
+    name: "Example Cloud Save",
+    resolveSavePaths: async (gameContext) => [
+      { pattern: `%APPDATA%/${gameContext.gameTitle}` },
+    ],
+  };
+
+  const aggregatorPlugin: ClientPlugin = {
+    metadata: {
+      id: "aggregator",
+      name: "Aggregator Plugin",
+      version: "1.0.0",
+    },
+    init(ctx: ClientPluginContext) {
+      unregisterScanner = ctx.registerStoreScanner(gogScanner);
+      if (ctx.registerMetadataProvider) {
+        unregisterProvider = ctx.registerMetadataProvider(
+          exampleMetadataProvider,
+        );
+      }
+      unregisterCloudSave = ctx.registerCloudSaveResolver?.(
+        exampleCloudsaveResolver,
+      );
+    },
+  };
+
+  await manager.registerPlugin(
+    aggregatorPlugin,
+    "aggregator",
+    [],
+    ["client:library-scan", "metadata:provider", "cloudsave:provider"],
+  );
+
+  // Assert registered
+  const scanners = manager.getStoreScanners();
+  assert.equal(scanners.length, 1);
+  const scanner = scanners[0];
+  assert.ok(scanner);
+  assert.equal(scanner.id, "gog");
+  const games = await scanner.scan();
+  assert.equal(games.length, 1);
+  assert.equal(games[0]?.title, "Cyberpunk 2077");
+
+  const providers = manager.getMetadataProviders();
+  assert.equal(providers.length, 1);
+  assert.equal(providers[0]?.id, "example-metadata");
+
+  const resolvers = manager.getCloudSaveResolvers();
+  assert.equal(resolvers.length, 1);
+  assert.equal(resolvers[0]?.id, "example-cloudsave");
+
+  // Capability enforcement
+  const restrictedPlugin: ClientPlugin = {
+    metadata: {
+      id: "restricted-client",
+      name: "Restricted",
+      version: "1.0.0",
+    },
+    init(ctx: ClientPluginContext) {
+      ctx.registerStoreScanner({
+        id: "epic",
+        name: "Epic",
+        store: "epic",
+        scan: async () => [],
+      });
+    },
+  };
+
+  await manager.registerPlugin(
+    restrictedPlugin,
+    "restricted-client",
+    [],
+    ["ui:slot"],
+  );
+  // Registration should fail inside init and not add scanner
+  assert.equal(manager.getStoreScanners().length, 1);
+
+  // Manual unregister hooks work
+  unregisterScanner?.();
+  assert.equal(manager.getStoreScanners().length, 0);
+
+  unregisterProvider?.();
+  assert.equal(manager.getMetadataProviders().length, 0);
+
+  unregisterCloudSave?.();
+  assert.equal(manager.getCloudSaveResolvers().length, 0);
+});
+
+test("ClientPluginManager cleans up SPI entries and slots on unregisterPlugin", async () => {
+  const manager = new ClientPluginManager();
+
+  const multiPlugin: ClientPlugin = {
+    metadata: {
+      id: "multi-test",
+      name: "Multi Test",
+      version: "1.0.0",
+    },
+    init(ctx: ClientPluginContext) {
+      ctx.registerSlot("overlay:panel", { template: "test" });
+      ctx.registerStoreScanner({
+        id: "scanner-1",
+        name: "Scanner 1",
+        store: "custom",
+        scan: async () => [],
+      });
+      ctx.registerMetadataProvider?.({
+        id: "meta-1",
+        name: "Meta 1",
+        search: async () => [],
+        getDetails: async () => null,
+      });
+    },
+  };
+
+  await manager.registerPlugin(
+    multiPlugin,
+    "multi-test",
+    [],
+    ["ui:slot", "client:library-scan", "metadata:provider"],
+  );
+
+  assert.equal(manager.slots["overlay:panel"].length, 1);
+  assert.equal(manager.getStoreScanners().length, 1);
+  assert.equal(manager.getMetadataProviders().length, 1);
+
+  await manager.unregisterPlugin("multi-test");
+
+  assert.equal(manager.slots["overlay:panel"].length, 0);
+  assert.equal(manager.getStoreScanners().length, 0);
+  assert.equal(manager.getMetadataProviders().length, 0);
+});
diff --git a/desktop/main/internal/plugins/__tests__/storeImport.test.ts b/desktop/main/internal/plugins/__tests__/storeImport.test.ts
new file mode 100644
index 000000000..bb827cb3d
--- /dev/null
+++ b/desktop/main/internal/plugins/__tests__/storeImport.test.ts
@@ -0,0 +1,41 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import type { StoreScanner } from "../types";
+import { collectStoreGames } from "../storeImport";
+
+const steam: StoreScanner = {
+  id: "steam",
+  name: "Steam",
+  store: "steam",
+  scan: async () => [
+    {
+      externalId: "570",
+      store: "steam",
+      title: "Team Fortress 2",
+      installPath: "/games/tf2",
+    },
+  ],
+};
+
+const broken: StoreScanner = {
+  id: "epic",
+  name: "Epic",
+  store: "epic",
+  scan: async () => {
+    throw new Error("launcher not found");
+  },
+};
+
+test("collectStoreGames aggregates scanners and records failures", async () => {
+  const result = await collectStoreGames([steam, broken]);
+  assert.equal(result.games.length, 1);
+  assert.equal(result.games[0]?.title, "Team Fortress 2");
+  assert.deepEqual(result.failures, [
+    { store: "epic", error: "launcher not found" },
+  ]);
+});
+
+test("collectStoreGames with no scanners returns empty", async () => {
+  const result = await collectStoreGames([]);
+  assert.deepEqual(result, { games: [], failures: [] });
+});
diff --git a/desktop/main/internal/plugins/storeImport.ts b/desktop/main/internal/plugins/storeImport.ts
new file mode 100644
index 000000000..38a5cf510
--- /dev/null
+++ b/desktop/main/internal/plugins/storeImport.ts
@@ -0,0 +1,32 @@
+import type { ScannedGame, StoreScanner } from "./types";
+
+export interface StoreImportResult {
+  games: ScannedGame[];
+  failures: Array<{ store: string; error: string }>;
+}
+
+/**
+ * Runs every plugin-registered `StoreScanner` SPI and aggregates the results.
+ * A scanner that throws is recorded as a failure and does not abort the scan,
+ * so one broken store integration cannot block a library import.
+ */
+export async function collectStoreGames(
+  scanners: StoreScanner[],
+): Promise<StoreImportResult> {
+  const games: ScannedGame[] = [];
+  const failures: Array<{ store: string; error: string }> = [];
+
+  for (const scanner of scanners) {
+    try {
+      const discovered = await scanner.scan();
+      games.push(...discovered);
+    } catch (error) {
+      failures.push({
+        store: scanner.store,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  return { games, failures };
+}
diff --git a/desktop/main/internal/plugins/types.ts b/desktop/main/internal/plugins/types.ts
index 19c394e1d..45eb6a468 100644
--- a/desktop/main/internal/plugins/types.ts
+++ b/desktop/main/internal/plugins/types.ts
@@ -4,7 +4,26 @@ export type UISlotName =
   | "game-detail:badges"
   | "settings:tabs"
   | "topbar:status"
-  | "sidebar:nav";
+  | "sidebar:nav"
+  | "overlay:panel"
+  | "overlay:quick-access";
+
+export type ClientCapability =
+  | "ui:slot"
+  | "ui:play-action"
+  | "ui:context-menu"
+  | "ui:sidebar"
+  | "ui:topbar"
+  | "game:launch-hook"
+  | "game:fs"
+  | "game:scan"
+  | "client:storage"
+  | "client:ws"
+  | "system:sidecar"
+  | "system:command"
+  | "metadata:provider"
+  | "cloudsave:provider"
+  | "client:library-scan";
 
 export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "ALL";
 
@@ -158,6 +177,21 @@ export interface ClientPluginContext {
   registerSidebarItem(item: SidebarItem): () => void;
   registerTopBarItem(item: TopBarItem): () => void;
   registerLaunchHook(hook: LaunchHook): () => void;
+  /**
+   * Register a store library scanner SPI implementation.
+   * Requires the `client:library-scan` capability.
+   */
+  registerStoreScanner(scanner: StoreScanner): () => void;
+  /**
+   * Register a client-side metadata provider SPI implementation.
+   * Requires the `metadata:provider` capability.
+   */
+  registerMetadataProvider?(provider: MetadataProvider): () => void;
+  /**
+   * Register a client-side cloud save path resolver SPI implementation.
+   * Requires the `cloudsave:provider` capability.
+   */
+  registerCloudSaveResolver?(resolver: CloudSavePathResolver): () => void;
   gameFs: ScopedGameFs;
   gameScanner: ScopedGameScanner;
   serverWs: ClientPluginWebSocket;
@@ -187,3 +221,81 @@ export interface ClientPlugin {
   init(ctx: ClientPluginContext): Promise<void> | void;
   teardown?(): Promise<void> | void;
 }
+
+// ==========================================
+// Metadata Provider SPI (#7, #206, #207, #477)
+// ==========================================
+
+export interface MetadataSearchResult {
+  id: string;
+  title: string;
+  releaseYear?: number;
+  coverUrl?: string;
+  bannerUrl?: string;
+  iconUrl?: string;
+  description?: string;
+  provider: string;
+}
+
+export interface MetadataDetails extends MetadataSearchResult {
+  genres?: string[];
+  developers?: string[];
+  publishers?: string[];
+  screenshots?: string[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface MetadataProvider {
+  id: string;
+  name: string;
+  search(query: string): Promise<MetadataSearchResult[]>;
+  getDetails(id: string): Promise<MetadataDetails | null>;
+}
+
+// ==========================================
+// Store Scanner SPI (#21)
+// ==========================================
+
+export interface ScannedGame {
+  externalId: string;
+  store: "steam" | "gog" | "epic" | string;
+  title: string;
+  installPath: string;
+  executablePath?: string;
+  iconUrl?: string;
+  version?: string;
+}
+
+export interface StoreScanner {
+  id: string;
+  name: string;
+  store: string;
+  scan(): Promise<ScannedGame[]>;
+  launch?(externalId: string): Promise<void>;
+}
+
+// ==========================================
+// Cloud Save Provider SPI (#9)
+// ==========================================
+
+export interface CloudSavePattern {
+  pattern: string;
+  platform?: "windows" | "linux" | "macos";
+  winePrefix?: boolean;
+}
+
+export interface GameInstallContext {
+  gameId: string;
+  gameTitle: string;
+  installDir?: string;
+  winePrefix?: string;
+  executableName?: string;
+}
+
+export interface CloudSavePathResolver {
+  id: string;
+  name: string;
+  resolveSavePaths(
+    gameContext: GameInstallContext,
+  ): Promise<CloudSavePattern[]>;
+}
diff --git a/desktop/main/package.json b/desktop/main/package.json
index 64032752b..381417ce1 100644
--- a/desktop/main/package.json
+++ b/desktop/main/package.json
@@ -8,7 +8,8 @@
     "dev": "nuxt dev",
     "postinstall": "nuxt prepare",
     "tauri": "tauri",
-    "typecheck": "nuxt typecheck"
+    "typecheck": "nuxt typecheck",
+    "test": "node --test --import jiti/register internal/**/__tests__/*.test.ts"
   },
   "dependencies": {
     "@headlessui/vue": "^1.7.23",
@@ -32,6 +33,7 @@
     "@tailwindcss/typography": "^0.5.15",
     "@types/markdown-it": "^14.1.2",
     "autoprefixer": "^10.4.20",
+    "jiti": "^2.7.0",
     "postcss": "^8.5.18",
     "sass-embedded": "^1.79.4",
     "tailwindcss": "^3.4.13",
diff --git a/desktop/main/pnpm-lock.yaml b/desktop/main/pnpm-lock.yaml
index 9d5295385..e91174dc6 100644
--- a/desktop/main/pnpm-lock.yaml
+++ b/desktop/main/pnpm-lock.yaml
@@ -80,6 +80,9 @@ importers:
       autoprefixer:
         specifier: ^10.4.20
         version: 10.5.0(postcss@8.5.24)
+      jiti:
+        specifier: ^2.7.0
+        version: 2.7.0
       postcss:
         specifier: ^8.5.18
         version: 8.5.24
diff --git a/desktop/src-tauri/process/src/path_guard.rs b/desktop/src-tauri/process/src/path_guard.rs
index 80265da1e..c3b7d8f76 100644
--- a/desktop/src-tauri/process/src/path_guard.rs
+++ b/desktop/src-tauri/process/src/path_guard.rs
@@ -173,6 +173,82 @@ pub fn copy_to(root: &Path, src: &Path, candidate: impl AsRef<Path>) -> Result<(
     })
 }
 
+/// Normalize `.`/`..` components without touching the filesystem. Used only as
+/// a fallback for dangling symlinks, whose target cannot be canonicalized.
+fn lexical_normalize(path: &Path) -> PathBuf {
+    let mut out = PathBuf::new();
+    for component in path.components() {
+        match component {
+            Component::CurDir => {}
+            Component::ParentDir => {
+                if !out.pop() {
+                    out.push(component.as_os_str());
+                }
+            }
+            other => out.push(other.as_os_str()),
+        }
+    }
+    out
+}
+
+/// Whether the symlink at `path` resolves outside `canonical_root`.
+///
+/// Existing targets are fully resolved with `fs::canonicalize`; dangling links
+/// fall back to lexical resolution of `parent + target` so a link cannot escape
+/// simply because its target does not exist yet.
+fn symlink_escapes(canonical_root: &Path, path: &Path) -> bool {
+    let Ok(target) = fs::read_link(path) else {
+        return false;
+    };
+    let resolved = fs::canonicalize(path).unwrap_or_else(|_| {
+        let joined = if target.is_absolute() {
+            target
+        } else {
+            path.parent().unwrap_or(canonical_root).join(target)
+        };
+        lexical_normalize(&joined)
+    });
+    !resolved.starts_with(canonical_root)
+}
+
+/// Remove symlinks under `scan_dir` whose resolved target escapes `root`.
+///
+/// External extractors (7-Zip, innoextract) write archives directly and can
+/// materialize symlink entries that [`safe_join`] never sees because Drop did
+/// not create them. Links that resolve inside `root` are legitimate (Linux
+/// releases ship relative links between game files) and are kept; escaping
+/// links are unlinked and returned so the caller can fail the step.
+pub fn remove_escaping_symlinks(
+    root: &Path,
+    scan_dir: &Path,
+) -> Result<Vec<PathBuf>, PathGuardError> {
+    let canonical_root = canonical_root(root)?;
+    let canonical_scan = fs::canonicalize(scan_dir)?;
+    if !canonical_scan.starts_with(&canonical_root) {
+        return Err(unsafe_path(format!(
+            "scan directory {} is outside {}",
+            canonical_scan.display(),
+            canonical_root.display()
+        )));
+    }
+
+    let mut removed = Vec::new();
+    for entry in walkdir::WalkDir::new(&canonical_scan)
+        .min_depth(1)
+        .follow_links(false)
+    {
+        let entry = entry.map_err(|e| PathGuardError::Io(io::Error::other(e)))?;
+        if !entry.file_type().is_symlink() {
+            continue;
+        }
+        if symlink_escapes(&canonical_root, entry.path()) {
+            fs::remove_file(entry.path())?;
+            removed.push(entry.path().to_path_buf());
+        }
+    }
+    Ok(removed)
+}
+
 /// Remove a regular file (or symlink, which is unlinked, never followed) under
 /// `root`. Missing paths are a no-op.
 pub fn remove_file(root: &Path, candidate: impl AsRef<Path>) -> Result<(), PathGuardError> {
@@ -261,4 +337,75 @@ mod tests {
         assert!(write_file(tmp.path(), "linkdir/file.txt", b"pwned").is_err());
         assert!(!outside.path().join("file.txt").exists());
     }
+
+    #[cfg(unix)]
+    #[test]
+    fn removes_escaping_symlinks_and_keeps_internal_ones() {
+        let tmp = tempfile::tempdir().unwrap();
+        let root = tmp.path().join("game");
+        let outside = tempfile::tempdir().unwrap();
+        fs::create_dir_all(root.join("sub")).unwrap();
+        fs::write(root.join("sub/keep.txt"), b"data").unwrap();
+
+        let internal = root.join("internal-link");
+        symlink_dir(&root.join("sub"), &internal);
+        let escaping = root.join("escaping-link");
+        symlink_dir(outside.path(), &escaping);
+
+        let removed = remove_escaping_symlinks(&root, &root).unwrap();
+
+        assert_eq!(removed, vec![escaping.clone()]);
+        assert!(is_symlink(&internal));
+        assert!(!is_symlink(&escaping));
+        assert!(outside.path().exists());
+        assert_eq!(fs::read(root.join("sub/keep.txt")).unwrap(), b"data");
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn removes_dangling_escaping_symlinks() {
+        let tmp = tempfile::tempdir().unwrap();
+        let root = tmp.path().join("game");
+        fs::create_dir_all(&root).unwrap();
+
+        let dangling = root.join("dangling-link");
+        std::os::unix::fs::symlink("../outside-missing/target", &dangling).unwrap();
+
+        let removed = remove_escaping_symlinks(&root, &root).unwrap();
+
+        assert_eq!(removed, vec![dangling.clone()]);
+        assert!(!is_symlink(&dangling));
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn removes_symlink_chains_that_escape() {
+        let tmp = tempfile::tempdir().unwrap();
+        let root = tmp.path().join("game");
+        let outside = tempfile::tempdir().unwrap();
+        fs::create_dir_all(&root).unwrap();
+
+        let hop = root.join("hop");
+        symlink_dir(outside.path(), &hop);
+        let chain = root.join("chain");
+        std::os::unix::fs::symlink("hop", &chain).unwrap();
+
+        let removed = remove_escaping_symlinks(&root, &root).unwrap();
+
+        assert_eq!(removed.len(), 2);
+        assert!(!is_symlink(&hop));
+        assert!(!is_symlink(&chain));
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn rejects_scan_directories_outside_the_root() {
+        let tmp = tempfile::tempdir().unwrap();
+        let root = tmp.path().join("game");
+        let outside = tmp.path().join("outside");
+        fs::create_dir_all(&root).unwrap();
+        fs::create_dir_all(&outside).unwrap();
+
+        assert!(remove_escaping_symlinks(&root, &outside).is_err());
+    }
 }
diff --git a/desktop/src-tauri/src/plugins.rs b/desktop/src-tauri/src/plugins.rs
index f4ca979b3..e992fa32f 100644
--- a/desktop/src-tauri/src/plugins.rs
+++ b/desktop/src-tauri/src/plugins.rs
@@ -38,22 +38,89 @@ pub struct CommandOutput {
 
 const BLOCKED_COMMANDS: &[&str] = &[
     // Shells
-    "sh", "bash", "dash", "ash", "zsh", "csh", "tcsh", "fish", "ksh",
-    "cmd", "cmd.exe", "powershell", "powershell.exe", "pwsh", "pwsh.exe",
-    "wscript", "wscript.exe", "cscript", "cscript.exe",
+    "sh",
+    "bash",
+    "dash",
+    "ash",
+    "zsh",
+    "csh",
+    "tcsh",
+    "fish",
+    "ksh",
+    "cmd",
+    "cmd.exe",
+    "powershell",
+    "powershell.exe",
+    "pwsh",
+    "pwsh.exe",
+    "wscript",
+    "wscript.exe",
+    "cscript",
+    "cscript.exe",
     // Interpreters & runtimes
-    "python", "python3", "python.exe", "python3.exe", "py", "py.exe",
-    "node", "node.exe", "deno", "deno.exe", "bun", "bun.exe",
-    "perl", "perl.exe", "ruby", "ruby.exe", "php", "php.exe", "lua", "lua.exe",
+    "python",
+    "python3",
+    "python.exe",
+    "python3.exe",
+    "py",
+    "py.exe",
+    "node",
+    "node.exe",
+    "deno",
+    "deno.exe",
+    "bun",
+    "bun.exe",
+    "perl",
+    "perl.exe",
+    "ruby",
+    "ruby.exe",
+    "php",
+    "php.exe",
+    "lua",
+    "lua.exe",
     // Network transfer / remote shells
-    "curl", "curl.exe", "wget", "wget.exe",
-    "nc", "ncat", "netcat", "socat", "telnet", "ssh", "scp", "sftp", "ftp",
+    "curl",
+    "curl.exe",
+    "wget",
+    "wget.exe",
+    "nc",
+    "ncat",
+    "netcat",
+    "socat",
+    "telnet",
+    "ssh",
+    "scp",
+    "sftp",
+    "ftp",
     // Privilege escalation / execution
-    "sudo", "su", "doas", "pkexec", "runas", "runas.exe",
+    "sudo",
+    "su",
+    "doas",
+    "pkexec",
+    "runas",
+    "runas.exe",
     // Destructive filesystem / partition / system tools
-    "rm", "rmdir", "del", "erase", "dd", "format", "mkfs", "fdisk", "parted",
-    "reg", "reg.exe", "regedit", "regedit.exe", "certutil", "certutil.exe",
-    "bitsadmin", "bitsadmin.exe", "mshta", "mshta.exe", "rundll32", "rundll32.exe",
+    "rm",
+    "rmdir",
+    "del",
+    "erase",
+    "dd",
+    "format",
+    "mkfs",
+    "fdisk",
+    "parted",
+    "reg",
+    "reg.exe",
+    "regedit",
+    "regedit.exe",
+    "certutil",
+    "certutil.exe",
+    "bitsadmin",
+    "bitsadmin.exe",
+    "mshta",
+    "mshta.exe",
+    "rundll32",
+    "rundll32.exe",
 ];
 
 fn validate_command_name(command: &str) -> Result<(), String> {
@@ -155,12 +222,7 @@ pub async fn plugin_system_run(
     let output = match tokio::time::timeout(timeout, command.output()).await {
         Ok(Ok(output)) => output,
         Ok(Err(err)) => return Err(format!("failed to run '{bin}': {err}")),
-        Err(_) => {
-            return Err(format!(
-                "'{bin}' timed out after {}ms",
-                timeout.as_millis()
-            ))
-        }
+        Err(_) => return Err(format!("'{bin}' timed out after {}ms", timeout.as_millis())),
     };
 
     Ok(CommandOutput {
@@ -252,10 +314,7 @@ pub async fn plugin_game_fs_backup(
 }
 
 #[tauri::command]
-pub async fn plugin_game_fs_restore(
-    game_id: String,
-    relative_path: String,
-) -> Result<(), String> {
+pub async fn plugin_game_fs_restore(game_id: String, relative_path: String) -> Result<(), String> {
     let install_dir = get_game_install_dir(&game_id)?;
     let backup_relative = format!("{}.drop-backup", relative_path);
     let backup_path = path_guard::safe_join(&install_dir, &backup_relative)
@@ -277,10 +336,7 @@ pub async fn plugin_game_fs_restore(
 }
 
 #[tauri::command]
-pub async fn plugin_game_fs_exists(
-    game_id: String,
-    relative_path: String,
-) -> Result<bool, String> {
+pub async fn plugin_game_fs_exists(game_id: String, relative_path: String) -> Result<bool, String> {
     let install_dir = get_game_install_dir(&game_id)?;
     match path_guard::safe_join(&install_dir, &relative_path) {
         Ok(safe_path) => Ok(safe_path.exists()),
@@ -289,10 +345,7 @@ pub async fn plugin_game_fs_exists(
 }
 
 #[tauri::command]
-pub async fn plugin_game_fs_delete(
-    game_id: String,
-    relative_path: String,
-) -> Result<(), String> {
+pub async fn plugin_game_fs_delete(game_id: String, relative_path: String) -> Result<(), String> {
     let install_dir = get_game_install_dir(&game_id)?;
     path_guard::remove_file(&install_dir, &relative_path)
         .map_err(|e| format!("Failed to delete {relative_path}: {e}"))
@@ -338,12 +391,10 @@ pub async fn plugin_game_scan_executables(
                 .unwrap_or(false)
         };
 
-        if is_exec
-            && let Ok(rel_path) = path.strip_prefix(&install_dir)
-        {
+        if is_exec && let Ok(rel_path) = path.strip_prefix(&install_dir) {
             let size = entry.metadata().map(|m| m.len()).unwrap_or(0);
-            let sha256 = compute_file_sha256(path)
-                .unwrap_or_else(|_| String::from("unknown-sha256"));
+            let sha256 =
+                compute_file_sha256(path).unwrap_or_else(|_| String::from("unknown-sha256"));
 
             executables.push(ScannedExecutable {
                 relative_path: rel_path.to_string_lossy().to_string(),
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 9145b7b44..9299b6741 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -305,6 +305,9 @@ importers:
       h3:
         specifier: ^1.15.5
         version: 1.15.11
+      jiti:
+        specifier: ^2.7.0
+        version: 2.7.0
       nitropack:
         specifier: ^2.13.4
         version: 2.13.4(@electric-sql/pglite@0.4.1)(mysql2@3.15.3)(oxc-parser@0.140.0)(rolldown@1.1.5)(vite@8.1.5(@types/node@22.19.17)(esbuild@0.28.0)(jiti@2.7.0)(sass@1.99.0)(terser@5.47.1)(yaml@2.9.0))
@@ -8018,10 +8021,6 @@ packages:
     engines: {node: '>=6.4.0'}
     hasBin: true
 
-  jiti@2.6.1:
-    resolution: {integrity: sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ==}
-    hasBin: true
-
   jiti@2.7.0:
     resolution: {integrity: sha512-AC/7JofJvZGrrneWNaEnJeOLUx+JlGt7tNa0wZiRPT4MY1wmfKjt2+6O2p2uz2+skll8OZZmJMNqeke7kKbNgQ==}
     hasBin: true
@@ -14524,7 +14523,7 @@ snapshots:
       esbuild: 0.25.12
       fontaine: 0.6.0
       h3: 1.15.11
-      jiti: 2.6.1
+      jiti: 2.7.0
       magic-regexp: 0.10.0
       magic-string: 0.30.21
       node-fetch-native: 1.6.7
@@ -14660,7 +14659,7 @@ snapshots:
       errx: 0.1.0
       exsolve: 1.0.8
       ignore: 7.0.5
-      jiti: 2.6.1
+      jiti: 2.7.0
       klona: 2.0.6
       knitwork: 1.3.0
       mlly: 1.8.2
@@ -19118,7 +19117,7 @@ snapshots:
       '@typescript-eslint/parser': 8.58.2(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3)
       eslint: 9.39.4(jiti@2.7.0)
       eslint-import-resolver-node: 0.3.10
-      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import-x@4.17.1(@typescript-eslint/utils@8.66.0(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3))(eslint-import-resolver-node@0.3.10)(eslint@9.39.4(jiti@2.7.0)))(eslint-plugin-import@2.32.0)(eslint@9.39.4(jiti@2.7.0))
+      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import-x@4.17.1(@typescript-eslint/utils@8.66.0(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3))(eslint-import-resolver-node@0.3.10)(eslint@9.39.4(jiti@2.7.0)))(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.58.2(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3))(eslint@9.39.4(jiti@2.7.0)))(eslint@9.39.4(jiti@2.7.0))
       eslint-plugin-import: 2.32.0(@typescript-eslint/parser@8.58.2(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3))(eslint-import-resolver-typescript@3.10.1)(eslint@9.39.4(jiti@2.7.0))
       eslint-plugin-jsx-a11y: 6.10.2(eslint@9.39.4(jiti@2.7.0))
       eslint-plugin-react: 7.37.5(eslint@9.39.4(jiti@2.7.0))
@@ -19166,7 +19165,7 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
-  eslint-import-resolver-typescript@3.10.1(eslint-plugin-import-x@4.17.1(@typescript-eslint/utils@8.66.0(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3))(eslint-import-resolver-node@0.3.10)(eslint@9.39.4(jiti@2.7.0)))(eslint-plugin-import@2.32.0)(eslint@9.39.4(jiti@2.7.0)):
+  eslint-import-resolver-typescript@3.10.1(eslint-plugin-import-x@4.17.1(@typescript-eslint/utils@8.66.0(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3))(eslint-import-resolver-node@0.3.10)(eslint@9.39.4(jiti@2.7.0)))(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.58.2(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3))(eslint@9.39.4(jiti@2.7.0)))(eslint@9.39.4(jiti@2.7.0)):
     dependencies:
       '@nolyfill/is-core-module': 1.0.39
       debug: 4.4.3
@@ -19193,7 +19192,7 @@ snapshots:
       '@typescript-eslint/parser': 8.58.2(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3)
       eslint: 9.39.4(jiti@2.7.0)
       eslint-import-resolver-node: 0.3.10
-      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import-x@4.17.1(@typescript-eslint/utils@8.66.0(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3))(eslint-import-resolver-node@0.3.10)(eslint@9.39.4(jiti@2.7.0)))(eslint-plugin-import@2.32.0)(eslint@9.39.4(jiti@2.7.0))
+      eslint-import-resolver-typescript: 3.10.1(eslint-plugin-import-x@4.17.1(@typescript-eslint/utils@8.66.0(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3))(eslint-import-resolver-node@0.3.10)(eslint@9.39.4(jiti@2.7.0)))(eslint-plugin-import@2.32.0(@typescript-eslint/parser@8.58.2(eslint@9.39.4(jiti@2.7.0))(typescript@5.9.3))(eslint@9.39.4(jiti@2.7.0)))(eslint@9.39.4(jiti@2.7.0))
     transitivePeerDependencies:
       - supports-color
 
@@ -21043,8 +21042,6 @@ snapshots:
     dependencies:
       canvas-renderer: 2.2.1
 
-  jiti@2.6.1: {}
-
   jiti@2.7.0: {}
 
   jose@4.15.9: {}
diff --git a/server/dev-tools/sign-plugin.mjs b/server/dev-tools/sign-plugin.mjs
index d9163e98f..942a67527 100644
--- a/server/dev-tools/sign-plugin.mjs
+++ b/server/dev-tools/sign-plugin.mjs
@@ -5,9 +5,10 @@
  * Reads `<bundle>/drop-plugin.json`, computes the SHA-256 of the entry file
  * (default `index.js`) into `checksum`, records a `files` map covering every
  * bundle file, and — when `DROP_PLUGIN_SIGNING_KEY` is set — writes an
- * HMAC-SHA256 `signature` over the aggregate bundle digest. The manager
- * verifies all of these (and refuses multi-file bundles without `files`)
- * before importing a bundle.
+ * HMAC-SHA256 `signature` (signatureVersion 2) over the file aggregate plus the
+ * canonical manifest, so `id`/`version`/`capabilities` are covered too. The
+ * manager verifies all of these (and refuses multi-file bundles without
+ * `files`) before importing a bundle.
  *
  * Usage: node dev-tools/sign-plugin.mjs <bundle-dir>
  */
@@ -115,13 +116,39 @@ for (const rel of files) {
 }
 manifest.files = fileChecksums;
 
+/** Deterministic JSON; must stay byte-identical to the manager and the CLI. */
+function stableStringify(value) {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value) ?? "null";
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(stableStringify).join(",")}]`;
+  }
+  const keys = Object.keys(value).sort((a, b) => a.localeCompare(b, "en"));
+  return `{${keys
+    .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`)
+    .join(",")}}`;
+}
+
+/** Signature payload v2: file aggregate plus canonical manifest. */
+function signaturePayloadV2(filesAggregate, manifest) {
+  const signable = { ...manifest };
+  delete signable.signature;
+  return createHash("sha256")
+    .update(filesAggregate)
+    .update("\0")
+    .update(stableStringify(signable))
+    .digest("hex");
+}
+
 const key = process.env[SIGNING_KEY_ENV];
 if (key) {
-  manifest.signature = createHmac("sha256", key)
-    .update(aggregate.digest("hex"))
-    .digest("hex");
+  manifest.signatureVersion = 2;
+  const payload = signaturePayloadV2(aggregate.digest("hex"), manifest);
+  manifest.signature = createHmac("sha256", key).update(payload).digest("hex");
 } else {
   delete manifest.signature;
+  delete manifest.signatureVersion;
   console.warn(
     `${SIGNING_KEY_ENV} not set; wrote checksums without a signature`,
   );
diff --git a/server/server/internal/plugins/__tests__/plugins.test.ts b/server/server/internal/plugins/__tests__/plugins.test.ts
index 2af16b22c..dcbb440c3 100644
--- a/server/server/internal/plugins/__tests__/plugins.test.ts
+++ b/server/server/internal/plugins/__tests__/plugins.test.ts
@@ -1,7 +1,7 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import { spawnSync } from "node:child_process";
-import { createHash } from "node:crypto";
+import { createHash, createHmac } from "node:crypto";
 import fs from "node:fs/promises";
 import http from "node:http";
 import os from "node:os";
@@ -440,7 +440,7 @@ test("PluginManager fails closed on system:command without a commands allowlist"
           client: {
             entry: "client.js",
             capabilities: ["system:command"],
-            commands: ["/usr/bin/custom-cli"],
+            commands: ["/usr/bin/example-cli"],
           },
         },
         entryBase64,
@@ -479,7 +479,7 @@ test("PluginManager runs storage migrations to the declared version", async () =
   assert.deepEqual(migrations, [[0, 2]]);
 });
 
-test("HelloWorldPlugin proves generic extensible plugin architecture", async () => {
+test("HelloWorldPlugin proves the platform is domain-agnostic", async () => {
   const manager = createTestManager();
   await manager.registerPlugin(new HelloWorldPlugin());
 
@@ -1356,3 +1356,431 @@ test("signed bundle with FilePluginStorage survives storage mutations and reload
     }
   }
 });
+
+test("PluginManager registers and gates MetadataProvider, CloudSavePathResolver, and PaymentGateway SPIs", async () => {
+  const manager = createTestManager();
+
+  const metadataPlugin: ServerPlugin = {
+    metadata: {
+      id: "example-metadata-provider",
+      name: "Example Metadata",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      capabilities: ["metadata:provider"],
+    },
+    init: (ctx: PluginContext) => {
+      ctx.registerMetadataProvider({
+        id: "example-metadata",
+        name: "Example Metadata",
+        search: async (query) => [
+          { id: "meta-1", title: query, provider: "example-metadata" },
+        ],
+        getDetails: async (id) => ({
+          id,
+          title: "Sample Game",
+          provider: "example-metadata",
+        }),
+      });
+    },
+  };
+
+  const paymentPlugin: ServerPlugin = {
+    metadata: {
+      id: "example-payment-gateway",
+      name: "Example Payment Gateway",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      capabilities: ["commerce:payment"],
+    },
+    init: (ctx: PluginContext) => {
+      ctx.registerPaymentGateway({
+        id: "example-payment",
+        name: "Example Payment",
+        createPaymentIntent: async () => ({
+          intentId: "pi_test_123",
+          status: "pending",
+        }),
+        handleWebhook: async () => ({
+          orderId: "ord_1",
+          status: "succeeded",
+          transactionId: "txn_1",
+        }),
+      });
+    },
+  };
+
+  await manager.registerPlugin(metadataPlugin);
+  await manager.registerPlugin(paymentPlugin);
+
+  const cloudSavePlugin: ServerPlugin = {
+    metadata: {
+      id: "example-cloudsave-plugin",
+      name: "Example Cloud Saves",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      capabilities: ["cloudsave:provider"],
+    },
+    init: (ctx: PluginContext) => {
+      ctx.registerCloudSaveResolver({
+        id: "example-cloudsave",
+        name: "Example Manifest Resolver",
+        resolveSavePaths: async (gameContext) => [
+          { pattern: `%APPDATA%/${gameContext.gameTitle}/saves` },
+        ],
+      });
+    },
+  };
+  await manager.registerPlugin(cloudSavePlugin);
+
+  const resolvers = manager.getCloudSaveResolvers();
+  assert.equal(resolvers.length, 1);
+  assert.equal(resolvers[0].id, "example-cloudsave");
+  assert.equal(
+    manager.getCloudSaveResolver("example-cloudsave")?.name,
+    "Example Manifest Resolver",
+  );
+
+  // Assert registered
+  const providers = manager.getMetadataProviders();
+  assert.equal(providers.length, 1);
+  assert.equal(providers[0].id, "example-metadata");
+  assert.equal(
+    manager.getMetadataProvider("example-metadata")?.name,
+    "Example Metadata",
+  );
+
+  const gateways = manager.getPaymentGateways();
+  assert.equal(gateways.length, 1);
+  assert.equal(gateways[0].id, "example-payment");
+  assert.equal(
+    manager.getPaymentGateway("example-payment")?.name,
+    "Example Payment",
+  );
+
+  // Collision rejection throws
+  const collidingMetadataPlugin: ServerPlugin = {
+    metadata: {
+      id: "colliding-metadata-plugin",
+      name: "Colliding Metadata",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      capabilities: ["metadata:provider"],
+    },
+    init: (ctx: PluginContext) => {
+      ctx.registerMetadataProvider({
+        id: "example-metadata",
+        name: "Duplicate Metadata",
+        search: async () => [],
+        getDetails: async () => null,
+      });
+    },
+  };
+
+  await assert.rejects(
+    () => manager.registerPlugin(collidingMetadataPlugin),
+    /Metadata provider 'example-metadata' is already claimed by plugin 'example-metadata-provider'/,
+  );
+
+  const collidingPaymentPlugin: ServerPlugin = {
+    metadata: {
+      id: "colliding-payment-plugin",
+      name: "Colliding Payment",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      capabilities: ["commerce:payment"],
+    },
+    init: (ctx: PluginContext) => {
+      ctx.registerPaymentGateway({
+        id: "example-payment",
+        name: "Duplicate Payment",
+        createPaymentIntent: async () => ({ intentId: "", status: "failed" }),
+        handleWebhook: async () => ({
+          orderId: "",
+          status: "failed",
+          transactionId: "",
+        }),
+      });
+    },
+  };
+
+  await assert.rejects(
+    () => manager.registerPlugin(collidingPaymentPlugin),
+    /Payment gateway 'example-payment' is already claimed by plugin 'example-payment-gateway'/,
+  );
+
+  // Invalid ID throws
+  const invalidIdPlugin: ServerPlugin = {
+    metadata: {
+      id: "invalid-id-plugin",
+      name: "Invalid ID",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      capabilities: ["metadata:provider"],
+    },
+    init: (ctx: PluginContext) => {
+      ctx.registerMetadataProvider({
+        id: "   ",
+        name: "Empty ID",
+        search: async () => [],
+        getDetails: async () => null,
+      });
+    },
+  };
+
+  await assert.rejects(
+    () => manager.registerPlugin(invalidIdPlugin),
+    /Metadata provider must have a valid non-empty id/,
+  );
+
+  // Capability violation throws
+  const deniedPlugin: ServerPlugin = {
+    metadata: {
+      id: "denied-spi",
+      name: "Denied SPI",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      capabilities: ["routes"],
+    },
+    init: (ctx: PluginContext) => {
+      ctx.registerMetadataProvider({
+        id: "denied",
+        name: "Denied",
+        search: async () => [],
+        getDetails: async () => null,
+      });
+    },
+  };
+
+  await assert.rejects(
+    () => manager.registerPlugin(deniedPlugin),
+    /attempted 'registerMetadataProvider\(denied\)' without the 'metadata:provider' capability/,
+  );
+
+  // Cloud save resolver: collision, invalid id, and capability gate
+  const collidingCloudSavePlugin: ServerPlugin = {
+    metadata: {
+      id: "colliding-cloudsave-plugin",
+      name: "Colliding Cloud Save",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      capabilities: ["cloudsave:provider"],
+    },
+    init: (ctx: PluginContext) => {
+      ctx.registerCloudSaveResolver({
+        id: "example-cloudsave",
+        name: "Duplicate Cloud Save",
+        resolveSavePaths: async () => [],
+      });
+    },
+  };
+
+  await assert.rejects(
+    () => manager.registerPlugin(collidingCloudSavePlugin),
+    /Cloud save resolver 'example-cloudsave' is already claimed by plugin 'example-cloudsave-plugin'/,
+  );
+
+  const deniedCloudSavePlugin: ServerPlugin = {
+    metadata: {
+      id: "denied-cloudsave",
+      name: "Denied Cloud Save",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      capabilities: ["routes"],
+    },
+    init: (ctx: PluginContext) => {
+      ctx.registerCloudSaveResolver({
+        id: "denied",
+        name: "Denied",
+        resolveSavePaths: async () => [],
+      });
+    },
+  };
+
+  await assert.rejects(
+    () => manager.registerPlugin(deniedCloudSavePlugin),
+    /attempted 'registerCloudSaveResolver\(denied\)' without the 'cloudsave:provider' capability/,
+  );
+
+  // Unregister cleans up SPI entries
+  await manager.unregisterPlugin("example-metadata-provider");
+  assert.equal(manager.getMetadataProviders().length, 0);
+  assert.equal(manager.getMetadataProvider("example-metadata"), undefined);
+
+  await manager.unregisterPlugin("example-cloudsave-plugin");
+  assert.equal(manager.getCloudSaveResolvers().length, 0);
+  assert.equal(manager.getCloudSaveResolver("example-cloudsave"), undefined);
+
+  await manager.unregisterPlugin("example-payment-gateway");
+  assert.equal(manager.getPaymentGateways().length, 0);
+  assert.equal(manager.getPaymentGateway("example-payment"), undefined);
+});
+
+test("legacy files-only signatures still load after v2 support lands", async () => {
+  const dataDir = tmpDataDir();
+  const pluginDir = path.join(dataDir, "plugins", "legacy-signed");
+  await fs.mkdir(pluginDir, { recursive: true });
+  const entry =
+    "export default { metadata: { id: 'legacy-signed', name: 'Legacy'," +
+    " version: '1.0.0', apiVersion: 1 }, init() {} };\n";
+  await fs.writeFile(path.join(pluginDir, "index.mjs"), entry);
+  await fs.writeFile(
+    path.join(pluginDir, "helper.mjs"),
+    "export const value = 1;\n",
+  );
+
+  const files = ["helper.mjs", "index.mjs"].sort((a, b) => a.localeCompare(b));
+  const aggregate = createHash("sha256");
+  const fileChecksums: Record<string, string> = {};
+  for (const rel of files) {
+    const bytes = await fs.readFile(path.join(pluginDir, rel));
+    fileChecksums[rel] = createHash("sha256").update(bytes).digest("hex");
+    aggregate.update(rel);
+    aggregate.update("\0");
+    aggregate.update(String(bytes.length));
+    aggregate.update("\0");
+    aggregate.update(bytes);
+  }
+  const signingKey = "legacy-signing-key";
+  const legacySignature = createHmac("sha256", signingKey)
+    .update(aggregate.digest("hex"))
+    .digest("hex");
+  await fs.writeFile(
+    path.join(pluginDir, "drop-plugin.json"),
+    JSON.stringify({
+      id: "legacy-signed",
+      name: "Legacy",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      entry: "index.mjs",
+      checksum: createHash("sha256").update(entry).digest("hex"),
+      files: fileChecksums,
+      signature: legacySignature,
+    }),
+  );
+
+  const previousKey = process.env.DROP_PLUGIN_SIGNING_KEY;
+  process.env.DROP_PLUGIN_SIGNING_KEY = signingKey;
+  try {
+    const manager = new PluginManager({
+      dataDir,
+      storageFactory: () => new MemoryStorage(),
+      authResolver: async () => ({}),
+    });
+    await manager.discoverAndLoadExternalPlugins();
+    assert.equal(
+      manager.listPlugins().find((p) => p.id === "legacy-signed")?.status,
+      "active",
+      "a legacy files-only signature must still load",
+    );
+  } finally {
+    if (previousKey === undefined) {
+      delete process.env.DROP_PLUGIN_SIGNING_KEY;
+    } else {
+      process.env.DROP_PLUGIN_SIGNING_KEY = previousKey;
+    }
+  }
+});
+
+test("v2 signatures reject manifest tampering", async () => {
+  const dataDir = tmpDataDir();
+  const pluginDir = path.join(dataDir, "plugins", "manifest-tamper");
+  await fs.mkdir(pluginDir, { recursive: true });
+  await fs.writeFile(
+    path.join(pluginDir, "index.mjs"),
+    "export default { metadata: { id: 'manifest-tamper', name: 'Tamper'," +
+      " version: '1.0.0', apiVersion: 1 }, init() {} };\n",
+  );
+  await fs.writeFile(
+    path.join(pluginDir, "drop-plugin.json"),
+    JSON.stringify({
+      id: "manifest-tamper",
+      name: "Tamper",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      entry: "index.mjs",
+    }),
+  );
+
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const signer = path.resolve(here, "../../../../dev-tools/sign-plugin.mjs");
+  const signingKey = "manifest-tamper-key";
+  const signed = spawnSync(
+    process.execPath,
+    [signer, "plugins/manifest-tamper"],
+    {
+      cwd: dataDir,
+      env: { ...process.env, DROP_PLUGIN_SIGNING_KEY: signingKey },
+      encoding: "utf8",
+    },
+  );
+  assert.equal(signed.status, 0, signed.stderr);
+
+  const manifestPath = path.join(pluginDir, "drop-plugin.json");
+  const manifest = JSON.parse(await fs.readFile(manifestPath, "utf-8"));
+  assert.equal(manifest.signatureVersion, 2);
+  manifest.name = "Tampered";
+  await fs.writeFile(manifestPath, JSON.stringify(manifest));
+
+  const previousKey = process.env.DROP_PLUGIN_SIGNING_KEY;
+  process.env.DROP_PLUGIN_SIGNING_KEY = signingKey;
+  try {
+    const manager = new PluginManager({
+      dataDir,
+      storageFactory: () => new MemoryStorage(),
+      authResolver: async () => ({}),
+    });
+    await manager.discoverAndLoadExternalPlugins();
+    assert.equal(
+      manager.listPlugins().find((p) => p.id === "manifest-tamper"),
+      undefined,
+      "a tampered manifest must not load",
+    );
+  } finally {
+    if (previousKey === undefined) {
+      delete process.env.DROP_PLUGIN_SIGNING_KEY;
+    } else {
+      process.env.DROP_PLUGIN_SIGNING_KEY = previousKey;
+    }
+  }
+});
+
+test("plugin route patterns keep regex metacharacters literal", async () => {
+  const manager = createTestManager();
+
+  const regexPlugin: ServerPlugin = {
+    metadata: {
+      id: "regex-plugin",
+      name: "Regex Plugin",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      capabilities: ["routes"],
+    },
+    init: (ctx: PluginContext) => {
+      ctx.registerRoute("GET", "/literal/(a+)+", () => ({ literal: true }));
+    },
+  };
+
+  await manager.registerPlugin(regexPlugin);
+
+  const mockEvent = {
+    method: "GET",
+    headers: new Headers(),
+  } as unknown as import("h3").H3Event;
+
+  // The exact literal path matches...
+  const literal = (await manager.dispatch(
+    "regex-plugin",
+    "GET",
+    "/literal/(a+)+",
+    mockEvent,
+  )) as { literal: boolean };
+  assert.equal(literal.literal, true);
+
+  // ...but a path the metacharacters would match if compiled as a regex does not.
+  await assert.rejects(
+    () => manager.dispatch("regex-plugin", "GET", "/literal/aaaa", mockEvent),
+    /No handler found/,
+  );
+
+  await manager.unregisterPlugin("regex-plugin");
+});
diff --git a/server/server/internal/plugins/__tests__/signature.test.ts b/server/server/internal/plugins/__tests__/signature.test.ts
new file mode 100644
index 000000000..8deda04eb
--- /dev/null
+++ b/server/server/internal/plugins/__tests__/signature.test.ts
@@ -0,0 +1,68 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createHash, createHmac } from "node:crypto";
+import { SIGNATURE_VERSION, signaturePayloadV2 } from "../signature";
+
+/**
+ * Shared cross-repo fixture vector. The same values are asserted by
+ * `@droposs/plugin-cli`'s signer tests; changing the canonicalization or the
+ * payload layout on either side breaks this test.
+ */
+const FIXTURE = {
+  files: [
+    ["index.js", 'console.log("hi");\n'],
+    ["lib/a.js", "export const a = 1;\n"],
+  ] as const,
+  key: "fixture-signing-key",
+  filesAggregate:
+    "771113dd35bd8e72a5dbf35d13f1c535159efddbf5c3ba85d7fff35578a028d3",
+  payload: "34f3b3cc692f9fb16c1a7a5bcffb5d4da42d59f79dc1c82829933f26a0dc4e25",
+  signature: "3f21422b93a9ca2f852cf9351b628a6c80a7a505b4989dfb72ab80ed88875a96",
+};
+
+test("v2 signature payload matches the cross-repo fixture vector", () => {
+  const aggregate = createHash("sha256");
+  const fileChecksums: Record<string, string> = {};
+  for (const [rel, content] of FIXTURE.files) {
+    const bytes = Buffer.from(content);
+    fileChecksums[rel] = createHash("sha256").update(bytes).digest("hex");
+    aggregate.update(rel);
+    aggregate.update("\0");
+    aggregate.update(String(bytes.length));
+    aggregate.update("\0");
+    aggregate.update(bytes);
+  }
+  const filesAggregate = aggregate.digest("hex");
+  assert.equal(filesAggregate, FIXTURE.filesAggregate);
+
+  const manifest = {
+    id: "fixture",
+    name: "Fixture",
+    version: "1.0.0",
+    apiVersion: 2,
+    entry: "index.js",
+    capabilities: ["events"],
+    checksum: fileChecksums["index.js"],
+    files: fileChecksums,
+    signatureVersion: SIGNATURE_VERSION,
+  };
+  const payload = signaturePayloadV2(
+    filesAggregate,
+    manifest as unknown as Record<string, unknown>,
+  );
+  assert.equal(payload, FIXTURE.payload);
+
+  const signature = createHmac("sha256", FIXTURE.key)
+    .update(payload)
+    .digest("hex");
+  assert.equal(signature, FIXTURE.signature);
+});
+
+test("v2 payload excludes only the signature field", () => {
+  const base = { id: "p", version: "1.0.0", signature: "aa", extra: true };
+  const withoutSignature = { id: "p", version: "1.0.0", extra: true };
+  assert.equal(
+    signaturePayloadV2("abc", base as Record<string, unknown>),
+    signaturePayloadV2("abc", withoutSignature as Record<string, unknown>),
+  );
+});
diff --git a/server/server/internal/plugins/__tests__/upstream_compatibility.test.ts b/server/server/internal/plugins/__tests__/upstream_compatibility.test.ts
index db6352c9c..d198da3a7 100644
--- a/server/server/internal/plugins/__tests__/upstream_compatibility.test.ts
+++ b/server/server/internal/plugins/__tests__/upstream_compatibility.test.ts
@@ -45,6 +45,21 @@ test("Upstream Invariant: Zero-plugin baseline leaves server in pure vanilla sta
     0,
     "No public channels should exist by default",
   );
+  assert.equal(
+    manager.getMetadataProviders().length,
+    0,
+    "No metadata providers should exist by default",
+  );
+  assert.equal(
+    manager.getCloudSaveResolvers().length,
+    0,
+    "No cloud save resolvers should exist by default",
+  );
+  assert.equal(
+    manager.getPaymentGateways().length,
+    0,
+    "No payment gateways should exist by default",
+  );
 
   // 3. Dispatching to nonexistent plugin fails with 404
   await assert.rejects(
@@ -103,9 +118,9 @@ test("Upstream Invariant: Dynamic public WebSocket channels function without har
   assert.equal(manager.isPublicChannel("community:announcements"), true);
   assert.equal(manager.isPublicChannel("community:private-chat"), false);
   assert.equal(
-    manager.isPublicChannel("unregistered:public-channel"),
+    manager.isPublicChannel("gse:rooms"),
     false,
-    "unregistered channels must not be marked as public",
+    "gse:rooms must not be hardcoded as public",
   );
 
   // Unregistering cleanly wipes out public channel designations
diff --git a/server/server/internal/plugins/builtin/hello-world.ts b/server/server/internal/plugins/builtin/hello-world.ts
index 8db203ce3..4c3d7e6fd 100644
--- a/server/server/internal/plugins/builtin/hello-world.ts
+++ b/server/server/internal/plugins/builtin/hello-world.ts
@@ -2,8 +2,8 @@ import { PLUGIN_API_VERSION } from "../types";
 import type { PluginContext, PluginMetadata, ServerPlugin } from "../types";
 
 /**
- * Minimal reference plugin. Demonstrates that creating an extension
- * requires only a manifest and a route handler.
+ * Minimal reference plugin. Its only purpose is to prove the platform is not
+ * GSE-shaped: a new plugin needs only a manifest and a route.
  */
 export class HelloWorldPlugin implements ServerPlugin {
   metadata: PluginMetadata = {
@@ -11,7 +11,7 @@ export class HelloWorldPlugin implements ServerPlugin {
     name: "Hello World",
     version: "1.0.0",
     description: "Reference plugin that answers GET /ping",
-    author: "Drop Contributors",
+    author: "Heretek Games",
     builtin: true,
     apiVersion: PLUGIN_API_VERSION,
     trust: "trusted",
diff --git a/server/server/internal/plugins/manager.ts b/server/server/internal/plugins/manager.ts
index eb5c19f1a..5e3795c49 100644
--- a/server/server/internal/plugins/manager.ts
+++ b/server/server/internal/plugins/manager.ts
@@ -14,8 +14,12 @@ import {
   PluginTrustError,
 } from "./errors";
 import { PluginRegistry } from "./registry";
+import { SIGNATURE_VERSION, signaturePayloadV2 } from "./signature";
 import type {
+  CloudSavePathResolver,
   HttpMethod,
+  MetadataProvider,
+  PaymentGateway,
   PluginCapability,
   PluginContext,
   PluginManifest,
@@ -109,6 +113,45 @@ function trimTrailingSlashes(value: string): string {
   return value.slice(0, end);
 }
 
+/** Upper bound on a plugin route pattern, limiting regex construction cost. */
+const MAX_ROUTE_PATTERN_LENGTH = 512;
+
+/** Escapes RegExp metacharacters so literal route text cannot form a pattern. */
+function escapeRegExp(value: string): string {
+  const specials = ".*+?^${}()|[]\\";
+  let escaped = "";
+  for (const char of value) {
+    escaped += specials.includes(char) ? `\\${char}` : char;
+  }
+  return escaped;
+}
+
+/**
+ * Translates one token of a plugin route pattern into regex source. Recognises
+ * `:name`, `*`, and `**`; every other character is escaped so it stays literal.
+ */
+function routeTokenToRegexSource(
+  normalized: string,
+  index: number,
+  paramNames: string[],
+): { source: string; consumed: number } {
+  const char = normalized[index];
+  if (char === ":" && /[A-Za-z0-9_]/.test(normalized[index + 1] ?? "")) {
+    let end = index + 1;
+    while (end < normalized.length && /\w/.test(normalized[end])) {
+      end++;
+    }
+    paramNames.push(normalized.slice(index + 1, end));
+    return { source: "([^/]+)", consumed: end - index };
+  }
+  if (char === "*") {
+    return normalized[index + 1] === "*"
+      ? { source: "(.*)", consumed: 2 }
+      : { source: "([^/]+)", consumed: 1 };
+  }
+  return { source: escapeRegExp(char), consumed: 1 };
+}
+
 /** Resolves a dynamically imported bundle's default or named plugin export. */
 function resolvePluginExport(mod: {
   default?: unknown;
@@ -161,6 +204,18 @@ export class PluginManager {
     string,
     Array<() => void>
   >();
+  private readonly metadataProviders = new Map<
+    string,
+    { pluginId: string; provider: MetadataProvider }
+  >();
+  private readonly cloudSaveResolvers = new Map<
+    string,
+    { pluginId: string; resolver: CloudSavePathResolver }
+  >();
+  private readonly paymentGateways = new Map<
+    string,
+    { pluginId: string; gateway: PaymentGateway }
+  >();
   private readonly log: Logger = logger.child({ name: "plugin-manager" });
 
   constructor(private readonly options: PluginManagerOptions = {}) {
@@ -204,19 +259,28 @@ export class PluginManager {
     regex: RegExp;
     paramNames: string[];
   } {
+    if (pattern.length > MAX_ROUTE_PATTERN_LENGTH) {
+      throw new Error(
+        `Plugin route pattern exceeds ${MAX_ROUTE_PATTERN_LENGTH} characters`,
+      );
+    }
     const paramNames: string[] = [];
-    const normalized = pattern.startsWith("/") ? pattern : `/${pattern}`;
+    const normalized = trimTrailingSlashes(
+      pattern.startsWith("/") ? pattern : `/${pattern}`,
+    );
 
-    const regexStr = trimTrailingSlashes(normalized)
-      .replace(/:(\w+)/g, (_, name) => {
-        paramNames.push(name);
-        return "([^/]+)";
-      })
-      .replace(/\*\*/g, "(.*)")
-      .replace(/\*/g, "([^/]+)");
+    // Build the pattern token-by-token and escape every literal character, so
+    // a plugin cannot inject regex metacharacters (and thus a ReDoS payload)
+    // through a route pattern.
+    let source = "";
+    for (let index = 0; index < normalized.length;) {
+      const token = routeTokenToRegexSource(normalized, index, paramNames);
+      source += token.source;
+      index += token.consumed;
+    }
 
     return {
-      regex: new RegExp(`^${regexStr || "/"}(?:/)?$`),
+      regex: new RegExp(`^${source || "/"}(?:/)?$`),
       paramNames,
     };
   }
@@ -387,6 +451,77 @@ export class PluginManager {
         }
         return fetch(input, init);
       },
+      registerMetadataProvider: (provider: MetadataProvider) => {
+        if (
+          !provider ||
+          typeof provider.id !== "string" ||
+          !provider.id.trim()
+        ) {
+          throw new Error("Metadata provider must have a valid non-empty id");
+        }
+        if (!this.hasCapability(capabilities, "metadata:provider")) {
+          throw new PluginCapabilityError(
+            id,
+            "metadata:provider",
+            `registerMetadataProvider(${provider.id})`,
+          );
+        }
+        const existing = this.metadataProviders.get(provider.id);
+        if (existing && existing.pluginId !== id) {
+          throw new Error(
+            `Metadata provider '${provider.id}' is already claimed by plugin '${existing.pluginId}'`,
+          );
+        }
+        this.metadataProviders.set(provider.id, { pluginId: id, provider });
+        pluginLogger.debug(`Registered metadata provider: ${provider.id}`);
+      },
+      registerCloudSaveResolver: (resolver: CloudSavePathResolver) => {
+        if (
+          !resolver ||
+          typeof resolver.id !== "string" ||
+          !resolver.id.trim()
+        ) {
+          throw new Error("Cloud save resolver must have a valid non-empty id");
+        }
+        if (!this.hasCapability(capabilities, "cloudsave:provider")) {
+          throw new PluginCapabilityError(
+            id,
+            "cloudsave:provider",
+            `registerCloudSaveResolver(${resolver.id})`,
+          );
+        }
+        const existing = this.cloudSaveResolvers.get(resolver.id);
+        if (existing && existing.pluginId !== id) {
+          throw new Error(
+            `Cloud save resolver '${resolver.id}' is already claimed by plugin '${existing.pluginId}'`,
+          );
+        }
+        this.cloudSaveResolvers.set(resolver.id, {
+          pluginId: id,
+          resolver,
+        });
+        pluginLogger.debug(`Registered cloud save resolver: ${resolver.id}`);
+      },
+      registerPaymentGateway: (gateway: PaymentGateway) => {
+        if (!gateway || typeof gateway.id !== "string" || !gateway.id.trim()) {
+          throw new Error("Payment gateway must have a valid non-empty id");
+        }
+        if (!this.hasCapability(capabilities, "commerce:payment")) {
+          throw new PluginCapabilityError(
+            id,
+            "commerce:payment",
+            `registerPaymentGateway(${gateway.id})`,
+          );
+        }
+        const existing = this.paymentGateways.get(gateway.id);
+        if (existing && existing.pluginId !== id) {
+          throw new Error(
+            `Payment gateway '${gateway.id}' is already claimed by plugin '${existing.pluginId}'`,
+          );
+        }
+        this.paymentGateways.set(gateway.id, { pluginId: id, gateway });
+        pluginLogger.debug(`Registered payment gateway: ${gateway.id}`);
+      },
     };
   }
 
@@ -527,6 +662,36 @@ export class PluginManager {
     return results.sort((a, b) => a.localeCompare(b));
   }
 
+  /**
+   * Reconstruct the payload a bundle signature covers. Signature v2 covers the
+   * canonical manifest in addition to the file aggregate; legacy bundles (no
+   * marker) cover the file aggregate, or the entry checksum for single-file
+   * bundles.
+   */
+  private resolveSignedPayload(
+    aggregateDigest: string,
+    entryDigest: string,
+    manifest: PluginManifest,
+  ): string {
+    if (manifest.signatureVersion === SIGNATURE_VERSION) {
+      if (!manifest.files) {
+        throw new Error(
+          `bundle ${manifest.id} declares signatureVersion ${SIGNATURE_VERSION} without file checksums`,
+        );
+      }
+      return signaturePayloadV2(
+        aggregateDigest,
+        manifest as unknown as Record<string, unknown>,
+      );
+    }
+    if (manifest.signatureVersion !== undefined) {
+      throw new Error(
+        `bundle ${manifest.id} uses unsupported signatureVersion ${manifest.signatureVersion}`,
+      );
+    }
+    return manifest.files ? aggregateDigest : entryDigest;
+  }
+
   /**
    * Verify the bundle signature. When `files` is present the signature covers
    * the aggregate bundle digest; otherwise it covers the entry checksum
@@ -545,7 +710,11 @@ export class PluginManager {
           `bundle ${manifest.id} is signed but DROP_PLUGIN_SIGNING_KEY is not set`,
         );
       }
-      const covered = manifest.files ? aggregateDigest : entryDigest;
+      const covered = this.resolveSignedPayload(
+        aggregateDigest,
+        entryDigest,
+        manifest,
+      );
       const expected = createHmac("sha256", signingKey)
         .update(covered)
         .digest("hex");
@@ -780,19 +949,30 @@ export class PluginManager {
     this.log.info(`Plugin ${id} unregistered`);
   }
 
-  /** Drop a plugin's routes, sockets and event subscriptions. */
-  private releasePluginResources(id: string): void {
-    this.routes.delete(id);
-    for (const [channel, entry] of this.webSockets) {
+  /** Deletes every map entry whose value is owned by plugin `id`. */
+  private purgeOwned<V extends { pluginId: string }>(
+    map: Map<string, V>,
+    id: string,
+  ): void {
+    for (const [key, entry] of map) {
       if (entry.pluginId === id) {
-        this.webSockets.delete(channel);
+        map.delete(key);
       }
     }
+  }
+
+  /** Drop a plugin's routes, sockets and event subscriptions. */
+  private releasePluginResources(id: string): void {
+    this.routes.delete(id);
+    this.purgeOwned(this.webSockets, id);
     for (const [channel, pluginId] of this.publicChannels) {
       if (pluginId === id) {
         this.publicChannels.delete(channel);
       }
     }
+    this.purgeOwned(this.metadataProviders, id);
+    this.purgeOwned(this.cloudSaveResolvers, id);
+    this.purgeOwned(this.paymentGateways, id);
     this.subscriptionAuthorizers.delete(id);
     const subscriptions = this.pluginEventSubscriptions.get(id) ?? [];
     for (const off of subscriptions) {
@@ -1186,6 +1366,30 @@ export class PluginManager {
     return Array.from(this.publicChannels.keys());
   }
 
+  getMetadataProviders(): MetadataProvider[] {
+    return Array.from(this.metadataProviders.values()).map((e) => e.provider);
+  }
+
+  getMetadataProvider(id: string): MetadataProvider | undefined {
+    return this.metadataProviders.get(id)?.provider;
+  }
+
+  getCloudSaveResolvers(): CloudSavePathResolver[] {
+    return Array.from(this.cloudSaveResolvers.values()).map((e) => e.resolver);
+  }
+
+  getCloudSaveResolver(id: string): CloudSavePathResolver | undefined {
+    return this.cloudSaveResolvers.get(id)?.resolver;
+  }
+
+  getPaymentGateways(): PaymentGateway[] {
+    return Array.from(this.paymentGateways.values()).map((e) => e.gateway);
+  }
+
+  getPaymentGateway(id: string): PaymentGateway | undefined {
+    return this.paymentGateways.get(id)?.gateway;
+  }
+
   private async resolveAuth(event: H3Event): Promise<PluginAuthContext> {
     if (this.options.authResolver) {
       return this.options.authResolver(event);
diff --git a/server/server/internal/plugins/signature.ts b/server/server/internal/plugins/signature.ts
new file mode 100644
index 000000000..1170ac163
--- /dev/null
+++ b/server/server/internal/plugins/signature.ts
@@ -0,0 +1,45 @@
+import { createHash } from "node:crypto";
+
+/**
+ * Bundle signature schemes.
+ *
+ * - Version 2: the HMAC covers the file aggregate plus the canonical manifest
+ *   (everything except `signature`), so `id`, `version`, and `capabilities`
+ *   cannot be tampered with.
+ * - Legacy (no marker): the HMAC covers the file aggregate only, or the entry
+ *   checksum for single-file bundles.
+ */
+export const SIGNATURE_VERSION = 2;
+
+/** Deterministic JSON; must stay byte-identical to the plugin CLI's signer. */
+export function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value) ?? "null";
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(stableStringify).join(",")}]`;
+  }
+  const record = value as Record<string, unknown>;
+  const keys = Object.keys(record).sort((a, b) => a.localeCompare(b, "en"));
+  return `{${keys
+    .map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`)
+    .join(",")}}`;
+}
+
+/**
+ * Version 2 signature payload: the files aggregate plus the canonical manifest
+ * (excluding its `signature` field). Mirrors
+ * `@droposs/plugin-cli` `signaturePayloadV2`; a shared fixture vector in both
+ * repos guards against drift.
+ */
+export function signaturePayloadV2(
+  filesAggregate: string,
+  manifest: Record<string, unknown>,
+): string {
+  const { signature: _ignored, ...signable } = manifest;
+  return createHash("sha256")
+    .update(filesAggregate)
+    .update("\0")
+    .update(stableStringify(signable))
+    .digest("hex");
+}
diff --git a/server/server/internal/plugins/types.ts b/server/server/internal/plugins/types.ts
index ac40709fc..8023f055c 100644
--- a/server/server/internal/plugins/types.ts
+++ b/server/server/internal/plugins/types.ts
@@ -21,7 +21,14 @@ export type PluginTarget = "server" | "client";
 export type PluginCategory = "generic" | "metadata" | "storage" | "multiplayer";
 
 export type ServerCapability =
-  "routes" | "storage" | "websocket" | "events" | "network";
+  | "routes"
+  | "storage"
+  | "websocket"
+  | "events"
+  | "network"
+  | "metadata:provider"
+  | "cloudsave:provider"
+  | "commerce:payment";
 
 export type ClientCapability =
   | "ui:slot"
@@ -35,14 +42,18 @@ export type ClientCapability =
   | "client:storage"
   | "client:ws"
   | "system:sidecar"
-  | "system:command";
+  | "system:command"
+  | "metadata:provider"
+  | "cloudsave:provider"
+  | "client:library-scan";
 
 export type PluginCapability = ServerCapability | ClientCapability;
 
 /**
  * Trust tier. Only `"trusted"` is supported today: plugins run in-process with
  * the server's own privileges. `"sandboxed"` is reserved for a future isolated
- * runtime and must be rejected until that runtime exists.
+ * runtime (see docs/implementation/drop-gse.md, M4/P6) and must be rejected
+ * until that runtime exists.
  */
 export type PluginTrust = "trusted" | "sandboxed";
 
@@ -79,8 +90,16 @@ export interface PluginManifest extends PluginMetadata {
    */
   files?: Record<string, string>;
   /**
-   * HMAC-SHA256 (hex) of `checksum`, keyed by `DROP_PLUGIN_SIGNING_KEY`.
-   * Set `DROP_PLUGIN_REQUIRE_SIGNATURE=true` to reject unsigned bundles.
+   * Signature scheme marker. Bundles signed by `@droposs/plugin-cli` >= 0.6.0
+   * carry `2`, meaning `signature` covers the file aggregate plus the canonical
+   * manifest. Absent on legacy bundles, whose signature covers the file
+   * aggregate or entry checksum only.
+   */
+  signatureVersion?: number;
+  /**
+   * HMAC-SHA256 (hex) of the signature payload, keyed by
+   * `DROP_PLUGIN_SIGNING_KEY`. Set `DROP_PLUGIN_REQUIRE_SIGNATURE=true` to
+   * reject unsigned bundles.
    */
   signature?: string;
 
@@ -202,6 +221,21 @@ export interface PluginContext {
   ): void;
   /** Network egress. Requires the `network` capability. */
   fetch(input: string | URL, init?: RequestInit): Promise<Response>;
+  /**
+   * Register a metadata provider SPI implementation.
+   * Requires the `metadata:provider` capability.
+   */
+  registerMetadataProvider(provider: MetadataProvider): void;
+  /**
+   * Register a cloud save path resolver SPI implementation.
+   * Requires the `cloudsave:provider` capability.
+   */
+  registerCloudSaveResolver(resolver: CloudSavePathResolver): void;
+  /**
+   * Register a payment gateway SPI implementation.
+   * Requires the `commerce:payment` capability.
+   */
+  registerPaymentGateway(gateway: PaymentGateway): void;
 }
 
 export interface ServerPlugin {
@@ -218,3 +252,117 @@ export interface ServerPlugin {
     storage: PluginStorage,
   ): Promise<void>;
 }
+
+// ==========================================
+// Metadata Provider SPI (#7, #206, #207, #477)
+// ==========================================
+
+export interface MetadataSearchResult {
+  id: string;
+  title: string;
+  releaseYear?: number;
+  coverUrl?: string;
+  bannerUrl?: string;
+  iconUrl?: string;
+  description?: string;
+  provider: string;
+}
+
+export interface MetadataDetails extends MetadataSearchResult {
+  genres?: string[];
+  developers?: string[];
+  publishers?: string[];
+  screenshots?: string[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface MetadataProvider {
+  id: string;
+  name: string;
+  search(query: string): Promise<MetadataSearchResult[]>;
+  getDetails(id: string): Promise<MetadataDetails | null>;
+}
+
+// ==========================================
+// Cloud Save Provider SPI (#9)
+// ==========================================
+
+export interface CloudSavePattern {
+  pattern: string;
+  platform?: "windows" | "linux" | "macos";
+  winePrefix?: boolean;
+}
+
+export interface GameInstallContext {
+  gameId: string;
+  gameTitle: string;
+  installDir?: string;
+  winePrefix?: string;
+  executableName?: string;
+}
+
+export interface CloudSavePathResolver {
+  id: string;
+  name: string;
+  resolveSavePaths(
+    gameContext: GameInstallContext,
+  ): Promise<CloudSavePattern[]>;
+}
+
+// ==========================================
+// Store Scanner SPI (#21)
+// ==========================================
+
+export interface ScannedGame {
+  externalId: string;
+  store: "steam" | "gog" | "epic" | string;
+  title: string;
+  installPath: string;
+  executablePath?: string;
+  iconUrl?: string;
+  version?: string;
+}
+
+export interface StoreScanner {
+  id: string;
+  name: string;
+  store: string;
+  scan(): Promise<ScannedGame[]>;
+  launch?(externalId: string): Promise<void>;
+}
+
+// ==========================================
+// Payment Gateway SPI (#21)
+// ==========================================
+
+export interface PaymentIntentRequest {
+  orderId: string;
+  amount: number; // minor units (e.g. cents)
+  currency: string;
+  customerEmail?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface PaymentIntentResult {
+  intentId: string;
+  clientSecret?: string;
+  checkoutUrl?: string;
+  status: "pending" | "succeeded" | "failed";
+}
+
+export interface PaymentWebhookResult {
+  orderId: string;
+  status: "succeeded" | "failed" | "refunded";
+  transactionId: string;
+  payload?: Record<string, unknown>;
+}
+
+export interface PaymentGateway {
+  id: string;
+  name: string;
+  createPaymentIntent(req: PaymentIntentRequest): Promise<PaymentIntentResult>;
+  handleWebhook(
+    payload: unknown,
+    headers: Record<string, string>,
+  ): Promise<PaymentWebhookResult>;
+}

From 8eac9d03b8433fe1d3ab78726a958af829e5c293 Mon Sep 17 00:00:00 2001
From: John Smith <you@example.com>
Date: Mon, 14 Sep 2026 23:13:56 -0400
Subject: [PATCH 06/13] refactor(plugins): split server runtime into focused
 modules

- manager.ts is now a thin facade; routes, websocket, events, lifecycle,
  context, bundle, compat, and verification each live in their own module
- bundle checksum and signature verification moves into
  PluginRegistry.verifyBundle instead of the manager
- ws.get.ts shrinks to a thin Nitro route; peer/session transport logic
  moves to the new ws-gateway module
- FilePluginStorage drops the speculative legacy-directory migration and
  bundle hashing now ignores only drop-plugin.json
---
 server/server/api/v1/plugins/ws.get.ts        |  220 +--
 .../plugins/__tests__/runtime.test.ts         |  442 ++++++
 server/server/internal/plugins/bundle.ts      |  392 +++++
 server/server/internal/plugins/compat.ts      |   68 +
 server/server/internal/plugins/context.ts     |  286 ++++
 server/server/internal/plugins/events.ts      |   47 +
 server/server/internal/plugins/lifecycle.ts   |  240 +++
 server/server/internal/plugins/manager.ts     | 1407 ++---------------
 server/server/internal/plugins/registry.ts    |   40 +-
 server/server/internal/plugins/routes.ts      |  187 +++
 server/server/internal/plugins/storage.ts     |   42 -
 .../server/internal/plugins/verification.ts   |  233 +++
 server/server/internal/plugins/websocket.ts   |  132 ++
 server/server/internal/plugins/ws-gateway.ts  |  250 +++
 14 files changed, 2424 insertions(+), 1562 deletions(-)
 create mode 100644 server/server/internal/plugins/__tests__/runtime.test.ts
 create mode 100644 server/server/internal/plugins/bundle.ts
 create mode 100644 server/server/internal/plugins/compat.ts
 create mode 100644 server/server/internal/plugins/context.ts
 create mode 100644 server/server/internal/plugins/events.ts
 create mode 100644 server/server/internal/plugins/lifecycle.ts
 create mode 100644 server/server/internal/plugins/routes.ts
 create mode 100644 server/server/internal/plugins/verification.ts
 create mode 100644 server/server/internal/plugins/websocket.ts
 create mode 100644 server/server/internal/plugins/ws-gateway.ts

diff --git a/server/server/api/v1/plugins/ws.get.ts b/server/server/api/v1/plugins/ws.get.ts
index b2143b866..2268e6c98 100644
--- a/server/server/api/v1/plugins/ws.get.ts
+++ b/server/server/api/v1/plugins/ws.get.ts
@@ -1,220 +1,10 @@
 import pluginManager from "~/server/internal/plugins";
-import { resolvePluginAuth } from "~/server/internal/plugins/auth";
+import { PluginWebSocketGateway } from "~/server/internal/plugins/ws-gateway";
 
-const clientSubscriptions = new Map<string, Array<() => void>>();
-const clientChannels = new Map<string, Set<string>>();
-const peerUsers = new Map<string, string | undefined>();
-const peerAcls = new Map<string, string[] | undefined>();
-
-const CHANNEL_PATTERN = /^[a-zA-Z0-9:_-]{1,128}$/;
-const MAX_MESSAGE_BYTES = 64 * 1024;
-const MAX_SUBSCRIPTIONS_PER_PEER = 32;
-
-/** Minimal structural view of the crossws peer used by the helpers below. */
-type WebSocketPeer = {
-  id: string;
-  request: {
-    headers: Headers;
-  };
-  send: (payload: string) => void;
-  close: () => void;
-};
-
-interface ClientMessage {
-  type?: unknown;
-  channel?: unknown;
-  data?: unknown;
-}
-
-function parseClientMessage(message: unknown): ClientMessage | undefined {
-  const text =
-    typeof (message as { text?: () => string }).text === "function"
-      ? (message as { text: () => string }).text()
-      : String(message);
-  if (Buffer.byteLength(text, "utf8") > MAX_MESSAGE_BYTES) return undefined;
-  try {
-    const parsed: unknown = JSON.parse(text);
-    if (parsed !== null && typeof parsed === "object") {
-      return parsed as ClientMessage;
-    }
-  } catch {
-    // Ignore non-JSON messages.
-  }
-  return undefined;
-}
-
-/** Hosts an Origin must match for a browser upgrade. */
-function allowedHostsFor(peer: WebSocketPeer): Set<string> {
-  const allowedHosts = new Set<string>();
-  const host = peer.request.headers.get("host");
-  if (host) allowedHosts.add(host);
-  const forwardedHost = peer.request.headers.get("x-forwarded-host");
-  if (forwardedHost) {
-    for (const item of forwardedHost.split(",")) {
-      const trimmed = item.trim();
-      if (trimmed) allowedHosts.add(trimmed);
-    }
-  }
-  const externalUrl = process.env.EXTERNAL_URL;
-  if (externalUrl) {
-    try {
-      allowedHosts.add(new URL(externalUrl).host);
-    } catch {
-      // Ignore malformed configuration here; auth still applies below.
-    }
-  }
-  return allowedHosts;
-}
-
-// Browsers always send Origin on WebSocket handshakes. Reject cross-site
-// upgrades so a malicious page cannot ride a victim's session cookie into the
-// plugin gateway (non-browser clients omit Origin and are allowed).
-function isAllowedOrigin(peer: WebSocketPeer): boolean {
-  const origin = peer.request.headers.get("origin");
-  if (!origin) return true;
-
-  const allowedHosts = allowedHostsFor(peer);
-  let originHost: string | undefined;
-  try {
-    originHost = new URL(origin).host;
-  } catch {
-    originHost = undefined;
-  }
-  return (
-    !!originHost && (allowedHosts.size === 0 || allowedHosts.has(originHost))
-  );
-}
-
-async function resolvePeerAuth(
-  peer: WebSocketPeer,
-): Promise<{ userId: string | undefined; userAcls: string[] | undefined }> {
-  try {
-    const auth = await resolvePluginAuth(peer.request);
-    return { userId: auth.userId, userAcls: auth.userAcls };
-  } catch {
-    // Unauthenticated peer.
-    return { userId: undefined, userAcls: undefined };
-  }
-}
-
-function sendChannelError(
-  peer: WebSocketPeer,
-  channel: string,
-  error: string,
-): void {
-  peer.send(JSON.stringify({ channel, error }));
-}
-
-async function authorizeChannel(
-  peer: WebSocketPeer,
-  channel: string,
-  userId: string | undefined,
-): Promise<boolean> {
-  if (!userId && !pluginManager.isPublicChannel(channel)) {
-    sendChannelError(peer, channel, "authentication required");
-    return false;
-  }
-
-  // Per-channel authorization (e.g. room membership), when a plugin registers
-  // an authorizer for the channel.
-  const authorized = await pluginManager.canSubscribe(channel, {
-    userId,
-    userAcls: peerAcls.get(peer.id),
-  });
-  if (!authorized) {
-    sendChannelError(peer, channel, "not authorized for channel");
-    return false;
-  }
-  return true;
-}
-
-function handleSubscribe(peer: WebSocketPeer, channel: string): void {
-  const subscriptions = clientChannels.get(peer.id);
-  if (!subscriptions || subscriptions.has(channel)) return;
-  if (subscriptions.size >= MAX_SUBSCRIPTIONS_PER_PEER) {
-    sendChannelError(peer, channel, "too many subscriptions");
-    return;
-  }
-  subscriptions.add(channel);
-
-  const unsubscribe = pluginManager.subscribe(channel, (event) => {
-    peer.send(JSON.stringify({ channel, data: event }));
-  });
-  clientSubscriptions.get(peer.id)?.push(unsubscribe);
-}
-
-async function dispatchClientMessage(
-  peer: WebSocketPeer,
-  channel: string,
-  data: unknown,
-  userId: string | undefined,
-): Promise<void> {
-  // Unauthenticated peers may only send on public channels.
-  if (!userId && !pluginManager.isPublicChannel(channel)) {
-    sendChannelError(peer, channel, "authentication required");
-    return;
-  }
-  const handled = await pluginManager.dispatchWebSocket(channel, data, {
-    userId,
-    userAcls: peerAcls.get(peer.id),
-    send: (payload) => peer.send(JSON.stringify({ channel, data: payload })),
-  });
-  if (!handled) {
-    sendChannelError(peer, channel, "no plugin handler for channel");
-  }
-}
+const gateway = new PluginWebSocketGateway(pluginManager);
 
 export default defineWebSocketHandler({
-  async open(peer) {
-    if (!isAllowedOrigin(peer)) {
-      peer.close();
-      return;
-    }
-
-    clientSubscriptions.set(peer.id, []);
-    clientChannels.set(peer.id, new Set());
-
-    // Authenticate the upgrade request so plugins receive a userId. Supports
-    // both browser sessions/API tokens and desktop client JWTs.
-    const { userId, userAcls } = await resolvePeerAuth(peer);
-    peerUsers.set(peer.id, userId);
-    peerAcls.set(peer.id, userAcls);
-  },
-  async message(peer, message) {
-    try {
-      const parsed = parseClientMessage(message);
-      if (
-        !parsed ||
-        typeof parsed.channel !== "string" ||
-        !CHANNEL_PATTERN.test(parsed.channel)
-      ) {
-        return;
-      }
-      const userId = peerUsers.get(peer.id);
-
-      if (parsed.type === "subscribe") {
-        if (!(await authorizeChannel(peer, parsed.channel, userId))) return;
-        handleSubscribe(peer, parsed.channel);
-        return;
-      }
-
-      if (parsed.type === "message") {
-        await dispatchClientMessage(peer, parsed.channel, parsed.data, userId);
-      }
-    } catch {
-      // Ignore non-JSON or invalid messages
-    }
-  },
-  close(peer) {
-    const unsubscribes = clientSubscriptions.get(peer.id);
-    if (unsubscribes) {
-      for (const unsub of unsubscribes) {
-        unsub();
-      }
-      clientSubscriptions.delete(peer.id);
-    }
-    clientChannels.delete(peer.id);
-    peerUsers.delete(peer.id);
-    peerAcls.delete(peer.id);
-  },
+  open: (peer) => gateway.open(peer),
+  message: (peer, message) => gateway.message(peer, message),
+  close: (peer) => gateway.close(peer),
 });
diff --git a/server/server/internal/plugins/__tests__/runtime.test.ts b/server/server/internal/plugins/__tests__/runtime.test.ts
new file mode 100644
index 000000000..091b51739
--- /dev/null
+++ b/server/server/internal/plugins/__tests__/runtime.test.ts
@@ -0,0 +1,442 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createHash, createHmac } from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type { H3Event } from "h3";
+import { PluginEventBus } from "../events";
+import { PluginRegistry } from "../registry";
+import { PluginRouteTable } from "../routes";
+import { PluginWebSocketRegistry } from "../websocket";
+import {
+  PluginWebSocketGateway,
+  isAllowedOrigin,
+  parseClientMessage,
+} from "../ws-gateway";
+import type { PluginWebSocketManager, WebSocketPeer } from "../ws-gateway";
+import { signaturePayloadV2 } from "../signature";
+import type { PluginManifest } from "../types";
+
+function sha256(content: string): string {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+/** Reproduces the manager's aggregate digest over sorted bundle files. */
+function computeAggregate(files: Array<[string, string]>): string {
+  const hasher = createHash("sha256");
+  for (const [rel, content] of [...files].sort((a, b) =>
+    a[0].localeCompare(b[0]),
+  )) {
+    const bytes = Buffer.from(content);
+    hasher.update(rel);
+    hasher.update("\0");
+    hasher.update(String(bytes.length));
+    hasher.update("\0");
+    hasher.update(bytes);
+  }
+  return hasher.digest("hex");
+}
+
+interface FakePeer extends WebSocketPeer {
+  sent: string[];
+  closed: boolean;
+}
+
+function fakePeer(id: string, headers: Record<string, string> = {}): FakePeer {
+  const peer: FakePeer = {
+    id,
+    request: { headers: new Headers(headers) },
+    sent: [],
+    closed: false,
+    send(payload: string) {
+      peer.sent.push(payload);
+    },
+    close() {
+      peer.closed = true;
+    },
+  };
+  return peer;
+}
+
+class FakeGatewayManager implements PluginWebSocketManager {
+  readonly listeners = new Map<string, Set<(data: unknown) => void>>();
+  readonly dispatched: Array<{ channel: string; message: unknown }> = [];
+  readonly publicChannels = new Set<string>();
+  allPublic = false;
+
+  isPublicChannel(channel: string): boolean {
+    return this.allPublic || this.publicChannels.has(channel);
+  }
+
+  async canSubscribe(): Promise<boolean> {
+    return true;
+  }
+
+  subscribe(channel: string, listener: (data: unknown) => void): () => void {
+    const listeners = this.listeners.get(channel) ?? new Set();
+    listeners.add(listener);
+    this.listeners.set(channel, listeners);
+    return () => {
+      listeners.delete(listener);
+    };
+  }
+
+  async dispatchWebSocket(channel: string, message: unknown): Promise<boolean> {
+    if (channel === "ws:missing") return false;
+    this.dispatched.push({ channel, message });
+    return true;
+  }
+
+  broadcast(channel: string, data: unknown): void {
+    for (const listener of this.listeners.get(channel) ?? []) {
+      listener(data);
+    }
+  }
+}
+
+test("PluginEventBus releases scoped subscriptions but keeps global ones", () => {
+  const bus = new PluginEventBus();
+  let scoped = 0;
+  let global = 0;
+
+  bus.subscribeScoped("plugin-a", "tick", () => {
+    scoped++;
+  });
+  const unsubscribe = bus.subscribe("tick", () => {
+    global++;
+  });
+
+  bus.emit("tick", null);
+  assert.equal(scoped, 1);
+  assert.equal(global, 1);
+
+  bus.release("plugin-a");
+  bus.emit("tick", null);
+  assert.equal(scoped, 1);
+  assert.equal(global, 2);
+
+  unsubscribe();
+  bus.emit("tick", null);
+  assert.equal(global, 2);
+});
+
+test("PluginRouteTable escapes metacharacters, extracts params, and 404s", async () => {
+  const table = new PluginRouteTable();
+  table.create("route-plugin");
+  table.register("route-plugin", "GET", "/literal/(a+)+", () => ({
+    literal: true,
+  }));
+  table.register("route-plugin", "GET", "/items/:id", (_event, context) => ({
+    id: context.params.id,
+  }));
+
+  const event = {
+    method: "GET",
+    headers: new Headers(),
+  } as unknown as H3Event;
+
+  assert.deepEqual(
+    await table.dispatch(
+      "route-plugin",
+      "GET",
+      "/literal/(a+)+",
+      event,
+      async () => ({}),
+    ),
+    { literal: true },
+  );
+  assert.deepEqual(
+    await table.dispatch(
+      "route-plugin",
+      "GET",
+      "/items/42",
+      event,
+      async () => ({}),
+    ),
+    { id: "42" },
+  );
+  await assert.rejects(
+    () =>
+      table.dispatch(
+        "route-plugin",
+        "GET",
+        "/literal/aaaa",
+        event,
+        async () => ({}),
+      ),
+    /No handler found/,
+  );
+});
+
+test("PluginWebSocketRegistry gates dispatch on plugin status and releases ownership", async () => {
+  const registry = new PluginWebSocketRegistry();
+  let received: unknown;
+
+  registry.register(
+    "ws-owner",
+    "ws:room",
+    (message) => {
+      received = message;
+    },
+    { public: true },
+  );
+  registry.addAuthorizer(
+    "ws-owner",
+    () => true,
+    () => false,
+  );
+  assert.equal(registry.isPublicChannel("ws:room"), true);
+  assert.deepEqual(registry.channels(), ["ws:room"]);
+
+  // Inactive plugins never receive messages.
+  assert.equal(
+    await registry.dispatch(
+      "ws:room",
+      { a: 1 },
+      { send: () => {} },
+      () => false,
+    ),
+    false,
+  );
+  assert.equal(
+    await registry.dispatch(
+      "ws:room",
+      { a: 1 },
+      { send: () => {} },
+      () => true,
+    ),
+    true,
+  );
+  assert.deepEqual(received, { a: 1 });
+
+  registry.release("ws-owner");
+  assert.equal(registry.isPublicChannel("ws:room"), false);
+  assert.deepEqual(registry.channels(), []);
+  assert.equal(
+    await registry.dispatch("ws:room", {}, { send: () => {} }, () => true),
+    false,
+  );
+  // The authorizer was removed with its plugin.
+  assert.equal(
+    await registry.canSubscribe("ws:room", {
+      userId: undefined,
+      userAcls: undefined,
+    }),
+    true,
+  );
+});
+
+test("parseClientMessage caps frames at 64 KiB", () => {
+  const small = JSON.stringify({ type: "subscribe", channel: "ws:public" });
+  assert.deepEqual(parseClientMessage({ text: () => small }), {
+    type: "subscribe",
+    channel: "ws:public",
+  });
+
+  const oversized = JSON.stringify({ pad: "x".repeat(64 * 1024) });
+  assert.equal(parseClientMessage({ text: () => oversized }), undefined);
+  assert.equal(parseClientMessage({ text: () => "not json" }), undefined);
+});
+
+test("isAllowedOrigin rejects cross-site upgrades and allows missing Origin", () => {
+  assert.equal(
+    isAllowedOrigin(
+      fakePeer("cross-site", {
+        host: "drop.example",
+        origin: "https://evil.example",
+      }),
+    ),
+    false,
+  );
+  assert.equal(
+    isAllowedOrigin(
+      fakePeer("same-site", {
+        host: "drop.example",
+        origin: "https://drop.example",
+      }),
+    ),
+    true,
+  );
+  // Non-browser clients omit Origin.
+  assert.equal(
+    isAllowedOrigin(fakePeer("native", { host: "drop.example" })),
+    true,
+  );
+});
+
+test("PluginWebSocketGateway enforces origin, channel validation and public gating", async () => {
+  const manager = new FakeGatewayManager();
+  manager.publicChannels.add("ws:public");
+  const gateway = new PluginWebSocketGateway(manager);
+
+  const crossSite = fakePeer("cross-site", {
+    host: "drop.example",
+    origin: "https://evil.example",
+  });
+  await gateway.open(crossSite);
+  assert.equal(crossSite.closed, true);
+
+  const guest = fakePeer("guest", { host: "drop.example" });
+  await gateway.open(guest);
+  assert.equal(guest.closed, false);
+
+  // Invalid channel names are ignored entirely.
+  await gateway.message(guest, {
+    text: () => JSON.stringify({ type: "subscribe", channel: "bad channel!" }),
+  });
+  assert.equal(manager.listeners.size, 0);
+
+  // Private channels require authentication.
+  await gateway.message(guest, {
+    text: () => JSON.stringify({ type: "subscribe", channel: "ws:private" }),
+  });
+  assert.deepEqual(JSON.parse(guest.sent[0] ?? "{}"), {
+    channel: "ws:private",
+    error: "authentication required",
+  });
+
+  // Public channels are subscribable and receive broadcasts.
+  await gateway.message(guest, {
+    text: () => JSON.stringify({ type: "subscribe", channel: "ws:public" }),
+  });
+  manager.broadcast("ws:public", { hello: 1 });
+  assert.deepEqual(JSON.parse(guest.sent.at(-1) ?? "{}"), {
+    channel: "ws:public",
+    data: { hello: 1 },
+  });
+
+  // Client messages are routed to the plugin handler.
+  await gateway.message(guest, {
+    text: () =>
+      JSON.stringify({ type: "message", channel: "ws:public", data: "ping" }),
+  });
+  assert.deepEqual(manager.dispatched, [
+    { channel: "ws:public", message: "ping" },
+  ]);
+
+  // Closing the peer tears down every subscription.
+  gateway.close(guest);
+  manager.broadcast("ws:public", { hello: 2 });
+  assert.equal(guest.sent.length, 2);
+});
+
+test("PluginWebSocketGateway caps subscriptions per peer at 32", async () => {
+  const manager = new FakeGatewayManager();
+  manager.allPublic = true;
+  const gateway = new PluginWebSocketGateway(manager);
+  const peer = fakePeer("subscriber", { host: "drop.example" });
+  await gateway.open(peer);
+
+  for (let i = 0; i < 33; i++) {
+    await gateway.message(peer, {
+      text: () =>
+        JSON.stringify({ type: "subscribe", channel: `ws:channel${i}` }),
+    });
+  }
+
+  assert.equal(manager.listeners.size, 32);
+  assert.deepEqual(JSON.parse(peer.sent.at(-1) ?? "{}"), {
+    channel: "ws:channel32",
+    error: "too many subscriptions",
+  });
+});
+
+test("PluginRegistry.verifyBundle verifies checksums, signature and pinning in order", async (t) => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "drop-verify-bundle-"));
+  const previousKey = process.env.DROP_PLUGIN_SIGNING_KEY;
+  const previousRequire = process.env.DROP_PLUGIN_REQUIRE_SIGNATURE;
+  t.after(async () => {
+    if (previousKey === undefined) {
+      delete process.env.DROP_PLUGIN_SIGNING_KEY;
+    } else {
+      process.env.DROP_PLUGIN_SIGNING_KEY = previousKey;
+    }
+    if (previousRequire === undefined) {
+      delete process.env.DROP_PLUGIN_REQUIRE_SIGNATURE;
+    } else {
+      process.env.DROP_PLUGIN_REQUIRE_SIGNATURE = previousRequire;
+    }
+    await fs.rm(dir, { recursive: true, force: true });
+  });
+
+  const entry =
+    "import { value } from './helper.mjs';\n" +
+    "export default { metadata: { id: 'verify-demo' }, init() { void value; } };\n";
+  const helper = "export const value = 1;\n";
+  await fs.writeFile(path.join(dir, "index.mjs"), entry);
+  await fs.writeFile(path.join(dir, "helper.mjs"), helper);
+
+  const entryDigest = sha256(entry);
+  const files = {
+    "index.mjs": entryDigest,
+    "helper.mjs": sha256(helper),
+  };
+  const aggregate = computeAggregate([
+    ["index.mjs", entry],
+    ["helper.mjs", helper],
+  ]);
+
+  const signingKey = "verify-bundle-key";
+  process.env.DROP_PLUGIN_SIGNING_KEY = signingKey;
+  const manifestBase = {
+    id: "verify-demo",
+    name: "Verify",
+    version: "1.0.0",
+    apiVersion: 2,
+    entry: "index.mjs",
+    checksum: entryDigest,
+    files,
+  };
+  const payload = signaturePayloadV2(aggregate, {
+    ...manifestBase,
+    signatureVersion: 2,
+  });
+  const manifest: PluginManifest = {
+    ...manifestBase,
+    signatureVersion: 2,
+    signature: createHmac("sha256", signingKey).update(payload).digest("hex"),
+  };
+  const entryPath = path.join(dir, "index.mjs");
+
+  const pinned = new PluginRegistry(
+    [{ id: "verify-demo", version: "1.0.0", checksum: entryDigest }],
+    true,
+  );
+  assert.equal(await pinned.verifyBundle(dir, manifest, entryPath), aggregate);
+
+  // Signature verification runs before registry pinning.
+  const wrongPin = new PluginRegistry(
+    [{ id: "verify-demo", checksum: "0".repeat(64) }],
+    true,
+  );
+  await assert.rejects(
+    () =>
+      wrongPin.verifyBundle(
+        dir,
+        { ...manifest, signature: "0".repeat(64) },
+        entryPath,
+      ),
+    /bundle signature mismatch/,
+  );
+  await assert.rejects(
+    () => wrongPin.verifyBundle(dir, manifest, entryPath),
+    /checksum does not match the registry/,
+  );
+
+  // Unsigned bundles are rejected when signatures are required.
+  process.env.DROP_PLUGIN_REQUIRE_SIGNATURE = "true";
+  await assert.rejects(
+    () =>
+      new PluginRegistry([], false).verifyBundle(dir, manifestBase, entryPath),
+    /bundle verify-demo is unsigned/,
+  );
+  delete process.env.DROP_PLUGIN_REQUIRE_SIGNATURE;
+
+  // Tampering with any bundle file fails its declared checksum.
+  await fs.writeFile(path.join(dir, "helper.mjs"), "export const value = 2;\n");
+  await assert.rejects(
+    () => pinned.verifyBundle(dir, manifest, entryPath),
+    /bundle file checksum mismatch for helper\.mjs/,
+  );
+});
diff --git a/server/server/internal/plugins/bundle.ts b/server/server/internal/plugins/bundle.ts
new file mode 100644
index 000000000..febf52647
--- /dev/null
+++ b/server/server/internal/plugins/bundle.ts
@@ -0,0 +1,392 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { pathToFileURL } from "node:url";
+import type { Logger } from "pino";
+import { assertManifestCompatible, isValidPluginId } from "./compat";
+import type { PluginRegistry } from "./registry";
+import { isInsideDirectory, verifyEntryChecksum } from "./verification";
+import type {
+  PluginManifest,
+  PluginMetadata,
+  PluginStatus,
+  ServerPlugin,
+} from "./types";
+
+/** Structured view of a dynamically imported plugin bundle module. */
+export interface PluginModule {
+  default?: unknown;
+  plugin?: unknown;
+}
+
+export interface PluginUpdateInfo {
+  id: string;
+  currentVersion: string;
+  latestVersion: string;
+  hasUpdate: boolean;
+  downloadUrl?: string;
+}
+
+/** Manager surface the bundle loader depends on. */
+export interface PluginBundleHost {
+  log: Logger;
+  getPluginsDirectory(): Promise<string>;
+  getRegistry(): Promise<PluginRegistry>;
+  registerPlugin(plugin: ServerPlugin): Promise<void>;
+  unregisterPlugin(id: string): Promise<void>;
+  getPlugin(id: string): ServerPlugin | undefined;
+  listPlugins(): Array<
+    PluginMetadata & { status: PluginStatus; error?: string }
+  >;
+}
+
+/** Resolves a dynamically imported bundle's default or named plugin export. */
+export function resolvePluginExport(mod: PluginModule): ServerPlugin | null {
+  const defaultExport = mod.default as Partial<ServerPlugin> | undefined;
+  if (defaultExport && typeof defaultExport.init === "function") {
+    return defaultExport as ServerPlugin;
+  }
+  const namedExport = mod.plugin as Partial<ServerPlugin> | undefined;
+  if (namedExport && typeof namedExport.init === "function") {
+    return namedExport as ServerPlugin;
+  }
+  if (typeof mod.default === "function") {
+    return new (mod.default as new () => ServerPlugin)();
+  }
+  return null;
+}
+
+/** Verify, import and register a bundle directory. */
+async function loadExternalPluginFromDir(
+  host: PluginBundleHost,
+  pluginDir: string,
+  manifest: PluginManifest,
+): Promise<void> {
+  if (!isValidPluginId(manifest.id)) {
+    throw new Error(`invalid plugin id '${manifest.id}'`);
+  }
+
+  // Check if plugin targets server (default true for v1 or when targets includes 'server')
+  const targets = manifest.targets;
+  const targetsServer = !targets || targets.includes("server");
+  const entryRel = manifest.server?.entry || manifest.entry || "index.js";
+  const entryPath = path.resolve(pluginDir, entryRel);
+  if (
+    targetsServer &&
+    (path.isAbsolute(entryRel) ||
+      !isInsideDirectory(path.resolve(pluginDir), entryPath))
+  ) {
+    throw new Error(`invalid entry path '${entryRel}'`);
+  }
+
+  // Validate the declared contract *before* importing: a dynamic import runs
+  // the module's top-level code, so compatibility must be checked on the
+  // manifest, not after the module has already executed.
+  assertManifestCompatible(manifest);
+
+  const registry = await host.getRegistry();
+  const aggregateDigest = await registry.verifyBundle(
+    pluginDir,
+    manifest,
+    targetsServer ? entryPath : undefined,
+  );
+
+  if (targetsServer) {
+    // Version the import URL by the whole-bundle digest so a change to any
+    // file (not just the entry) forces a fresh entry module instance.
+    const mod = await import(
+      `${pathToFileURL(entryPath).href}?v=${aggregateDigest}`
+    );
+    const pluginInstance = resolvePluginExport(mod);
+
+    if (!pluginInstance) {
+      throw new Error(
+        `Plugin module at ${entryPath} does not export a valid ServerPlugin`,
+      );
+    }
+
+    pluginInstance.metadata = {
+      ...manifest,
+      builtin: false,
+    };
+
+    await host.registerPlugin(pluginInstance);
+  } else {
+    // Client-only plugin registered for discovery and asset serving
+    const clientOnlyPlugin: ServerPlugin = {
+      metadata: {
+        ...manifest,
+        builtin: false,
+      },
+      init: () => {},
+    };
+    await host.registerPlugin(clientOnlyPlugin);
+  }
+}
+
+async function readExternalManifest(
+  pluginDir: string,
+): Promise<string | undefined> {
+  try {
+    return await fs.readFile(path.join(pluginDir, "drop-plugin.json"), "utf-8");
+  } catch {
+    try {
+      return await fs.readFile(path.join(pluginDir, "plugin.json"), "utf-8");
+    } catch {
+      return undefined;
+    }
+  }
+}
+
+async function loadExternalPluginEntry(
+  host: PluginBundleHost,
+  pluginDir: string,
+): Promise<void> {
+  const manifestContent = await readExternalManifest(pluginDir);
+  if (!manifestContent) return;
+
+  try {
+    const manifest: PluginManifest = JSON.parse(manifestContent);
+    if (
+      !manifest.id ||
+      !manifest.name ||
+      !manifest.version ||
+      !isValidPluginId(manifest.id)
+    ) {
+      host.log.warn(`Invalid plugin manifest in ${pluginDir}`);
+      return;
+    }
+
+    if (host.getPlugin(manifest.id)) {
+      return;
+    }
+
+    await loadExternalPluginFromDir(host, pluginDir, manifest);
+  } catch (err) {
+    host.log.error(`Failed to load external plugin from ${pluginDir}: ${err}`);
+  }
+}
+
+/** Discover and load every external plugin bundle in the data directory. */
+export async function discoverAndLoadExternalPlugins(
+  host: PluginBundleHost,
+): Promise<void> {
+  const pluginsDir = await host.getPluginsDirectory();
+  try {
+    await fs.mkdir(pluginsDir, { recursive: true });
+    const entries = await fs.readdir(pluginsDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+      await loadExternalPluginEntry(host, path.join(pluginsDir, entry.name));
+    }
+  } catch (err) {
+    host.log.debug(`External plugins directory check: ${err}`);
+  }
+}
+
+/**
+ * Install (or update) a signed plugin bundle from its manifest and entry source
+ * or multi-file payload, verifying checksums and signatures before loading.
+ */
+export async function installBundle(
+  host: PluginBundleHost,
+  manifest: PluginManifest,
+  entryOrFiles: string | Record<string, string>,
+): Promise<void> {
+  if (!manifest.id || !manifest.name || !manifest.version) {
+    throw new Error("manifest requires id, name and version");
+  }
+  if (!isValidPluginId(manifest.id)) {
+    throw new Error("invalid plugin id");
+  }
+
+  const pluginsDir = await host.getPluginsDirectory();
+  const bundleDir = path.join(pluginsDir, manifest.id);
+  await fs.mkdir(bundleDir, { recursive: true });
+
+  if (typeof entryOrFiles === "string") {
+    const bytes = Buffer.from(entryOrFiles, "base64");
+    const digest = verifyEntryChecksum(bytes, manifest);
+    (await host.getRegistry()).check(manifest, digest);
+
+    const entryRel = manifest.entry || "index.js";
+    const entryPath = path.resolve(bundleDir, entryRel);
+    if (
+      path.isAbsolute(entryRel) ||
+      !isInsideDirectory(path.resolve(bundleDir), entryPath)
+    ) {
+      throw new Error("invalid entry path");
+    }
+
+    await fs.mkdir(path.dirname(entryPath), { recursive: true });
+    const storedManifest: PluginManifest = {
+      ...manifest,
+      checksum: manifest.checksum ?? digest,
+    };
+    await fs.writeFile(
+      path.join(bundleDir, "drop-plugin.json"),
+      JSON.stringify(storedManifest, null, 2),
+    );
+    await fs.writeFile(entryPath, bytes);
+
+    await loadExternalPluginFromDir(host, bundleDir, storedManifest);
+  } else if (typeof entryOrFiles === "object" && entryOrFiles !== null) {
+    for (const [rel, base64] of Object.entries(entryOrFiles)) {
+      const resolved = path.resolve(bundleDir, rel);
+      if (
+        path.isAbsolute(rel) ||
+        !isInsideDirectory(path.resolve(bundleDir), resolved)
+      ) {
+        throw new Error(`invalid bundle file path '${rel}'`);
+      }
+      await fs.mkdir(path.dirname(resolved), { recursive: true });
+      await fs.writeFile(resolved, Buffer.from(base64, "base64"));
+    }
+
+    await fs.writeFile(
+      path.join(bundleDir, "drop-plugin.json"),
+      JSON.stringify(manifest, null, 2),
+    );
+
+    await loadExternalPluginFromDir(host, bundleDir, manifest);
+  } else {
+    throw new Error(
+      "invalid bundle payload: expected base64 entry or files map",
+    );
+  }
+}
+
+/** Download, verify and install a plugin bundle from a remote URL. */
+export async function installFromUrl(
+  host: PluginBundleHost,
+  url: string,
+): Promise<void> {
+  if (!url || typeof url !== "string") {
+    throw new Error("Invalid plugin download URL");
+  }
+  const parsed = new URL(url);
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(
+      `Unsupported protocol in URL '${url}': only http and https are allowed`,
+    );
+  }
+
+  const res = await fetch(url, {
+    signal: AbortSignal.timeout(15000),
+    headers: { "User-Agent": "Drop-Plugin-Installer/1.0" },
+  });
+  if (!res.ok) {
+    throw new Error(
+      `Failed to download plugin from '${url}': HTTP ${res.status} ${res.statusText}`,
+    );
+  }
+
+  const text = await res.text();
+  let bundle: {
+    manifest?: PluginManifest;
+    entry?: string;
+    files?: Record<string, string>;
+    format?: string;
+  };
+  try {
+    bundle = JSON.parse(text);
+  } catch (err) {
+    throw new Error(
+      `Downloaded bundle from '${url}' is not valid JSON: ${err}`,
+    );
+  }
+
+  if (!bundle?.manifest || (!bundle.entry && !bundle.files)) {
+    throw new Error(
+      `Downloaded bundle from '${url}' missing required manifest or file payload`,
+    );
+  }
+
+  const payload = bundle.files ?? bundle.entry!;
+  await installBundle(host, bundle.manifest, payload);
+}
+
+/** Check installed plugins against configured registry for available updates. */
+export async function checkForUpdates(
+  host: PluginBundleHost,
+): Promise<PluginUpdateInfo[]> {
+  const registry = await host.getRegistry();
+  if (!registry.enabled) {
+    return [];
+  }
+
+  const results: PluginUpdateInfo[] = [];
+
+  for (const plugin of host.listPlugins()) {
+    if (plugin.builtin) continue;
+    const entry = registry.getEntry(plugin.id);
+    if (!entry?.version) continue;
+
+    const hasUpdate = entry.version !== plugin.version;
+    results.push({
+      id: plugin.id,
+      currentVersion: plugin.version,
+      latestVersion: entry.version,
+      hasUpdate,
+      downloadUrl: entry.downloadUrl ?? entry.url,
+    });
+  }
+
+  return results;
+}
+
+/** Remove an external plugin bundle and unregister it. */
+export async function removeBundle(
+  host: PluginBundleHost,
+  id: string,
+): Promise<boolean> {
+  if (!isValidPluginId(id)) {
+    throw new Error("invalid plugin id");
+  }
+  if (host.getPlugin(id)?.metadata.builtin) {
+    throw new Error("cannot remove a builtin plugin");
+  }
+
+  await host.unregisterPlugin(id);
+
+  const pluginsDir = await host.getPluginsDirectory();
+  await fs.rm(path.join(pluginsDir, id), { recursive: true, force: true });
+  return true;
+}
+
+/** Unload every external plugin and rediscover it from disk. */
+export async function reloadPlugins(host: PluginBundleHost): Promise<void> {
+  host.log.info("Reloading external plugins...");
+  for (const plugin of host.listPlugins()) {
+    if (!plugin.builtin) {
+      await host.unregisterPlugin(plugin.id);
+    }
+  }
+  await discoverAndLoadExternalPlugins(host);
+}
+
+/**
+ * Resolve an on-disk asset for client-side bundle serving.
+ * Path traversal or symlink escapes outside the plugin directory return null.
+ */
+export async function getClientAssetPath(
+  host: PluginBundleHost,
+  pluginId: string,
+  assetRelPath: string,
+): Promise<string | null> {
+  if (!isValidPluginId(pluginId)) return null;
+  const pluginDir = path.join(await host.getPluginsDirectory(), pluginId);
+  const resolved = path.resolve(pluginDir, assetRelPath);
+  if (!isInsideDirectory(path.resolve(pluginDir), resolved)) {
+    return null;
+  }
+  try {
+    const s = await fs.stat(resolved);
+    if (s.isFile()) {
+      return resolved;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
diff --git a/server/server/internal/plugins/compat.ts b/server/server/internal/plugins/compat.ts
new file mode 100644
index 000000000..f32c8812f
--- /dev/null
+++ b/server/server/internal/plugins/compat.ts
@@ -0,0 +1,68 @@
+import { PLUGIN_API_VERSION } from "./types";
+import { PluginApiVersionError, PluginTrustError } from "./errors";
+import type { PluginManifest, ServerPlugin } from "./types";
+
+const PLUGIN_ID_PATTERN = /^[a-z0-9][a-z0-9._-]*$/i;
+
+export function isValidPluginId(id: string): boolean {
+  return id.length > 0 && id.length <= 64 && PLUGIN_ID_PATTERN.test(id);
+}
+
+/**
+ * Validate a manifest's declared contract before importing its module.
+ * Compatibility must be checked on the manifest, not after the module has
+ * already executed.
+ */
+export function assertManifestCompatible(manifest: PluginManifest): void {
+  const version = manifest.apiVersion ?? 0;
+  if (version !== 1 && version !== PLUGIN_API_VERSION) {
+    throw new PluginApiVersionError(manifest.id, PLUGIN_API_VERSION, version);
+  }
+  if (manifest.trust !== undefined && manifest.trust !== "trusted") {
+    throw new PluginTrustError(manifest.id, manifest.trust);
+  }
+  assertClientCommands(manifest);
+}
+
+/**
+ * Fail closed on the native-command capability: a plugin that declares
+ * `system:command` must ship a non-empty, bare-name `client.commands`
+ * allowlist. The desktop host enforces the same allowlist at run time; this
+ * rejects a malformed manifest before its module is imported.
+ */
+function assertClientCommands(manifest: PluginManifest): void {
+  const capabilities = manifest.client?.capabilities ?? [];
+  if (!capabilities.includes("system:command")) return;
+  const commands = manifest.client?.commands;
+  if (!Array.isArray(commands) || commands.length === 0) {
+    throw new Error(
+      `plugin '${manifest.id}' declares 'system:command' but has no client.commands allowlist`,
+    );
+  }
+  for (const command of commands) {
+    if (typeof command !== "string" || command.trim().length === 0) {
+      throw new Error(
+        `plugin '${manifest.id}' has an invalid client.commands entry`,
+      );
+    }
+    if (command.includes("/") || command.includes("\\")) {
+      throw new Error(
+        `plugin '${manifest.id}' client.commands must be bare executable names`,
+      );
+    }
+  }
+}
+
+/** Validate an in-process plugin's declared contract before registration. */
+export function assertPluginCompatible(plugin: ServerPlugin): void {
+  const { id, apiVersion, trust } = plugin.metadata;
+  const version = apiVersion ?? 0;
+  // Every plugin must declare the contract version it was built against;
+  // omitting it previously bypassed the compatibility gate entirely.
+  if (version !== 1 && version !== PLUGIN_API_VERSION) {
+    throw new PluginApiVersionError(id, PLUGIN_API_VERSION, version);
+  }
+  if (trust !== undefined && trust !== "trusted") {
+    throw new PluginTrustError(id, trust);
+  }
+}
diff --git a/server/server/internal/plugins/context.ts b/server/server/internal/plugins/context.ts
new file mode 100644
index 000000000..4b4d9f794
--- /dev/null
+++ b/server/server/internal/plugins/context.ts
@@ -0,0 +1,286 @@
+import type { Logger } from "pino";
+import { PluginCapabilityError } from "./errors";
+import type { PluginEventBus } from "./events";
+import type { PluginRouteTable } from "./routes";
+import type { PluginWebSocketRegistry } from "./websocket";
+import type {
+  CloudSavePathResolver,
+  MetadataProvider,
+  PaymentGateway,
+  PluginCapability,
+  PluginContext,
+  PluginStorage,
+  ServerPlugin,
+} from "./types";
+
+function hasCapability(
+  capabilities: PluginCapability[] | undefined,
+  cap: PluginCapability,
+): boolean {
+  // Fail closed: a plugin that does not explicitly declare a capability
+  // cannot use it.
+  return capabilities?.includes(cap) ?? false;
+}
+
+/** Deletes every map entry whose value is owned by plugin `id`. */
+function purgeOwned<V extends { pluginId: string }>(
+  map: Map<string, V>,
+  id: string,
+): void {
+  for (const [key, entry] of map) {
+    if (entry.pluginId === id) {
+      map.delete(key);
+    }
+  }
+}
+
+/**
+ * Registry of SPI implementations contributed by plugins. Registration is
+ * capability-gated and rejects collisions with another plugin's entry; every
+ * entry is dropped when its plugin unloads.
+ */
+export class PluginSpiRegistry {
+  private readonly metadataProviders = new Map<
+    string,
+    { pluginId: string; provider: MetadataProvider }
+  >();
+  private readonly cloudSaveResolvers = new Map<
+    string,
+    { pluginId: string; resolver: CloudSavePathResolver }
+  >();
+  private readonly paymentGateways = new Map<
+    string,
+    { pluginId: string; gateway: PaymentGateway }
+  >();
+
+  registerMetadataProvider(
+    pluginId: string,
+    provider: MetadataProvider,
+    capabilities: PluginCapability[] | undefined,
+  ): void {
+    if (!provider || typeof provider.id !== "string" || !provider.id.trim()) {
+      throw new Error("Metadata provider must have a valid non-empty id");
+    }
+    if (!hasCapability(capabilities, "metadata:provider")) {
+      throw new PluginCapabilityError(
+        pluginId,
+        "metadata:provider",
+        `registerMetadataProvider(${provider.id})`,
+      );
+    }
+    const existing = this.metadataProviders.get(provider.id);
+    if (existing && existing.pluginId !== pluginId) {
+      throw new Error(
+        `Metadata provider '${provider.id}' is already claimed by plugin '${existing.pluginId}'`,
+      );
+    }
+    this.metadataProviders.set(provider.id, { pluginId, provider });
+  }
+
+  registerCloudSaveResolver(
+    pluginId: string,
+    resolver: CloudSavePathResolver,
+    capabilities: PluginCapability[] | undefined,
+  ): void {
+    if (!resolver || typeof resolver.id !== "string" || !resolver.id.trim()) {
+      throw new Error("Cloud save resolver must have a valid non-empty id");
+    }
+    if (!hasCapability(capabilities, "cloudsave:provider")) {
+      throw new PluginCapabilityError(
+        pluginId,
+        "cloudsave:provider",
+        `registerCloudSaveResolver(${resolver.id})`,
+      );
+    }
+    const existing = this.cloudSaveResolvers.get(resolver.id);
+    if (existing && existing.pluginId !== pluginId) {
+      throw new Error(
+        `Cloud save resolver '${resolver.id}' is already claimed by plugin '${existing.pluginId}'`,
+      );
+    }
+    this.cloudSaveResolvers.set(resolver.id, { pluginId, resolver });
+  }
+
+  registerPaymentGateway(
+    pluginId: string,
+    gateway: PaymentGateway,
+    capabilities: PluginCapability[] | undefined,
+  ): void {
+    if (!gateway || typeof gateway.id !== "string" || !gateway.id.trim()) {
+      throw new Error("Payment gateway must have a valid non-empty id");
+    }
+    if (!hasCapability(capabilities, "commerce:payment")) {
+      throw new PluginCapabilityError(
+        pluginId,
+        "commerce:payment",
+        `registerPaymentGateway(${gateway.id})`,
+      );
+    }
+    const existing = this.paymentGateways.get(gateway.id);
+    if (existing && existing.pluginId !== pluginId) {
+      throw new Error(
+        `Payment gateway '${gateway.id}' is already claimed by plugin '${existing.pluginId}'`,
+      );
+    }
+    this.paymentGateways.set(gateway.id, { pluginId, gateway });
+  }
+
+  release(pluginId: string): void {
+    purgeOwned(this.metadataProviders, pluginId);
+    purgeOwned(this.cloudSaveResolvers, pluginId);
+    purgeOwned(this.paymentGateways, pluginId);
+  }
+
+  getMetadataProviders(): MetadataProvider[] {
+    return Array.from(this.metadataProviders.values()).map((e) => e.provider);
+  }
+
+  getMetadataProvider(id: string): MetadataProvider | undefined {
+    return this.metadataProviders.get(id)?.provider;
+  }
+
+  getCloudSaveResolvers(): CloudSavePathResolver[] {
+    return Array.from(this.cloudSaveResolvers.values()).map((e) => e.resolver);
+  }
+
+  getCloudSaveResolver(id: string): CloudSavePathResolver | undefined {
+    return this.cloudSaveResolvers.get(id)?.resolver;
+  }
+
+  getPaymentGateways(): PaymentGateway[] {
+    return Array.from(this.paymentGateways.values()).map((e) => e.gateway);
+  }
+
+  getPaymentGateway(id: string): PaymentGateway | undefined {
+    return this.paymentGateways.get(id)?.gateway;
+  }
+}
+
+/** Resources a plugin context is built from. */
+export interface PluginContextHost {
+  routes: PluginRouteTable;
+  webSockets: PluginWebSocketRegistry;
+  events: PluginEventBus;
+  spi: PluginSpiRegistry;
+  createStorage(pluginId: string): Promise<PluginStorage>;
+  log: Logger;
+}
+
+/**
+ * Restrict storage access to plugins that declared the `storage` capability.
+ * Missing capability is fail-closed: every method throws rather than
+ * silently reading/writing.
+ */
+function guardStorage(
+  pluginId: string,
+  capabilities: PluginCapability[] | undefined,
+  storage: PluginStorage,
+): PluginStorage {
+  if (hasCapability(capabilities, "storage")) {
+    return storage;
+  }
+  const deny = (operation: string): never => {
+    throw new PluginCapabilityError(pluginId, "storage", operation);
+  };
+  return {
+    get: async () => deny("storage.get"),
+    set: async () => deny("storage.set"),
+    delete: async () => deny("storage.delete"),
+    listKeys: async () => deny("storage.listKeys"),
+    getSchemaVersion: async () => deny("storage.getSchemaVersion"),
+    setSchemaVersion: async () => deny("storage.setSchemaVersion"),
+  };
+}
+
+/** Build the capability-gated context handed to a plugin's `init`. */
+export async function createPluginContext(
+  host: PluginContextHost,
+  plugin: ServerPlugin,
+): Promise<PluginContext> {
+  const id = plugin.metadata.id;
+  const capabilities = plugin.metadata.capabilities;
+  const pluginLogger = host.log.child({ plugin: id });
+  const storage = guardStorage(id, capabilities, await host.createStorage(id));
+  host.routes.create(id);
+
+  return {
+    id,
+    logger: pluginLogger,
+    storage,
+    registerRoute: (method, pattern, handler) => {
+      if (!hasCapability(capabilities, "routes")) {
+        throw new PluginCapabilityError(
+          id,
+          "routes",
+          `registerRoute(${pattern})`,
+        );
+      }
+
+      host.routes.register(id, method, pattern, handler);
+      pluginLogger.debug(`Registered route [${method}] ${pattern}`);
+    },
+    broadcast: (channel: string, event: unknown) => {
+      if (!hasCapability(capabilities, "events")) {
+        throw new PluginCapabilityError(id, "events", `broadcast(${channel})`);
+      }
+      host.events.emit(channel, event);
+    },
+    subscribe: (channel: string, listener: (event: unknown) => void) => {
+      if (!hasCapability(capabilities, "events")) {
+        throw new PluginCapabilityError(id, "events", `subscribe(${channel})`);
+      }
+      return host.events.subscribeScoped(id, channel, listener);
+    },
+    registerWebSocket: (channel, handler, options) => {
+      if (!hasCapability(capabilities, "websocket")) {
+        throw new PluginCapabilityError(
+          id,
+          "websocket",
+          `registerWebSocket(${channel})`,
+        );
+      }
+      host.webSockets.register(id, channel, handler, options);
+    },
+    registerPublicWebSocketChannel: (channel: string) => {
+      if (!hasCapability(capabilities, "websocket")) {
+        throw new PluginCapabilityError(
+          id,
+          "websocket",
+          `registerPublicWebSocketChannel(${channel})`,
+        );
+      }
+      host.webSockets.registerPublic(id, channel);
+    },
+    registerSubscriptionAuthorizer: (
+      matches: (channel: string) => boolean,
+      authorize,
+    ) => {
+      if (!hasCapability(capabilities, "websocket")) {
+        throw new PluginCapabilityError(
+          id,
+          "websocket",
+          "registerSubscriptionAuthorizer",
+        );
+      }
+      host.webSockets.addAuthorizer(id, matches, authorize);
+    },
+    fetch: async (input: string | URL, init?: RequestInit) => {
+      if (!hasCapability(capabilities, "network")) {
+        throw new PluginCapabilityError(id, "network", "fetch");
+      }
+      return fetch(input, init);
+    },
+    registerMetadataProvider: (provider) => {
+      host.spi.registerMetadataProvider(id, provider, capabilities);
+      pluginLogger.debug(`Registered metadata provider: ${provider.id}`);
+    },
+    registerCloudSaveResolver: (resolver) => {
+      host.spi.registerCloudSaveResolver(id, resolver, capabilities);
+      pluginLogger.debug(`Registered cloud save resolver: ${resolver.id}`);
+    },
+    registerPaymentGateway: (gateway) => {
+      host.spi.registerPaymentGateway(id, gateway, capabilities);
+      pluginLogger.debug(`Registered payment gateway: ${gateway.id}`);
+    },
+  };
+}
diff --git a/server/server/internal/plugins/events.ts b/server/server/internal/plugins/events.ts
new file mode 100644
index 000000000..5546c0249
--- /dev/null
+++ b/server/server/internal/plugins/events.ts
@@ -0,0 +1,47 @@
+import { EventEmitter } from "node:events";
+
+/**
+ * Plugin event bus. Subscriptions made through `subscribeScoped` are tracked
+ * per plugin and released together when the plugin unloads.
+ */
+export class PluginEventBus {
+  private readonly bus = new EventEmitter();
+  private readonly scopedSubscriptions = new Map<string, Array<() => void>>();
+
+  constructor() {
+    this.bus.setMaxListeners(200);
+  }
+
+  emit(channel: string, data: unknown): void {
+    this.bus.emit(channel, data);
+  }
+
+  subscribe(channel: string, listener: (data: unknown) => void): () => void {
+    this.bus.on(channel, listener);
+    return () => {
+      this.bus.off(channel, listener);
+    };
+  }
+
+  /** Subscribe on behalf of `pluginId`; cleanup happens on `release`. */
+  subscribeScoped(
+    pluginId: string,
+    channel: string,
+    listener: (event: unknown) => void,
+  ): () => void {
+    const off = this.subscribe(channel, listener);
+    const subscriptions = this.scopedSubscriptions.get(pluginId) ?? [];
+    subscriptions.push(off);
+    this.scopedSubscriptions.set(pluginId, subscriptions);
+    return off;
+  }
+
+  /** Drop every subscription owned by `pluginId`. */
+  release(pluginId: string): void {
+    const subscriptions = this.scopedSubscriptions.get(pluginId) ?? [];
+    for (const off of subscriptions) {
+      off();
+    }
+    this.scopedSubscriptions.delete(pluginId);
+  }
+}
diff --git a/server/server/internal/plugins/lifecycle.ts b/server/server/internal/plugins/lifecycle.ts
new file mode 100644
index 000000000..858911edc
--- /dev/null
+++ b/server/server/internal/plugins/lifecycle.ts
@@ -0,0 +1,240 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { createError } from "h3";
+import type { Logger } from "pino";
+import { assertPluginCompatible, isValidPluginId } from "./compat";
+import type {
+  PluginContext,
+  PluginMetadata,
+  PluginStateRecord,
+  PluginStatus,
+  PluginStorage,
+  ServerPlugin,
+} from "./types";
+
+export interface LoadedPlugin {
+  plugin: ServerPlugin;
+  context: PluginContext;
+  status: PluginStatus;
+  error?: Error;
+}
+
+/** Collaboration points the lifecycle needs from the plugin manager. */
+export interface PluginLifecycleHooks {
+  /** Builds the context (routes/websockets/events/storage) for a plugin. */
+  createContext(plugin: ServerPlugin): Promise<PluginContext>;
+  /** Drops every resource owned by `pluginId`. */
+  releaseResources(pluginId: string): void;
+  /** Notified when a plugin is disabled/enabled so clients observe state. */
+  notifyStateChange(pluginId: string, enabled: boolean): void;
+  /** Base data directory. Defaults to the server's configured data folder. */
+  dataDir?: string;
+  log: Logger;
+}
+
+/**
+ * Owns the plugin record table, the persisted enabled/disabled state
+ * (`plugins/_state.json`) and the register/activate/toggle/teardown lifecycle.
+ */
+export class PluginLifecycle {
+  private readonly plugins = new Map<string, LoadedPlugin>();
+
+  constructor(private readonly hooks: PluginLifecycleHooks) {}
+
+  private async getDataFolder(): Promise<string> {
+    if (this.hooks.dataDir !== undefined) {
+      return this.hooks.dataDir;
+    }
+    const { systemConfig } = await import("../config/sys-conf");
+    return systemConfig.getDataFolder();
+  }
+
+  async getPluginsDirectory(): Promise<string> {
+    return path.join(await this.getDataFolder(), "plugins");
+  }
+
+  private async getStateFilePath(): Promise<string> {
+    return path.join(await this.getPluginsDirectory(), "_state.json");
+  }
+
+  private async loadState(): Promise<Record<string, PluginStateRecord>> {
+    try {
+      const data = await fs.readFile(await this.getStateFilePath(), "utf-8");
+      return JSON.parse(data) as Record<string, PluginStateRecord>;
+    } catch {
+      return {};
+    }
+  }
+
+  private async saveState(
+    state: Record<string, PluginStateRecord>,
+  ): Promise<void> {
+    const filePath = await this.getStateFilePath();
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, JSON.stringify(state, null, 2), "utf-8");
+  }
+
+  getRecord(id: string): LoadedPlugin | undefined {
+    return this.plugins.get(id);
+  }
+
+  isActive(id: string): boolean {
+    return this.plugins.get(id)?.status === "active";
+  }
+
+  list(): Array<
+    PluginMetadata & {
+      status: PluginStatus;
+      error?: string;
+    }
+  > {
+    return Array.from(this.plugins.values()).map((p) => ({
+      ...p.plugin.metadata,
+      status: p.status,
+      error: p.error?.message,
+    }));
+  }
+
+  get(id: string): ServerPlugin | undefined {
+    return this.plugins.get(id)?.plugin;
+  }
+
+  /**
+   * Run a plugin's storage migrations when its recorded schema version is
+   * behind the version it declares. No-op for plugins that do not set
+   * `storageVersion`.
+   */
+  private async runStorageMigrations(
+    plugin: ServerPlugin,
+    storage: PluginStorage,
+  ): Promise<void> {
+    const target = plugin.metadata.storageVersion ?? 0;
+    if (target <= 0) return;
+    const current = await storage.getSchemaVersion();
+    if (current >= target) return;
+    if (plugin.migrateStorage) {
+      await plugin.migrateStorage(current, target, storage);
+    }
+    await storage.setSchemaVersion(target);
+  }
+
+  async register(plugin: ServerPlugin): Promise<void> {
+    const id = plugin.metadata.id;
+    if (!isValidPluginId(id)) {
+      throw new Error(`invalid plugin id '${id}'`);
+    }
+    assertPluginCompatible(plugin);
+    if (this.plugins.has(id)) {
+      this.hooks.log.warn(`Plugin ${id} is already registered, replacing`);
+      await this.unregister(id);
+    }
+
+    const state = await this.loadState();
+    const isExplicitlyDisabled = state[id]?.enabled === false;
+
+    const context = await this.hooks.createContext(plugin);
+    const loaded: LoadedPlugin = {
+      plugin,
+      context,
+      status: isExplicitlyDisabled ? "disabled" : "registered",
+    };
+    this.plugins.set(id, loaded);
+
+    if (isExplicitlyDisabled) {
+      this.hooks.log.info(
+        `Plugin '${plugin.metadata.name}' (${id}) is registered but disabled by configuration`,
+      );
+      return;
+    }
+
+    await this.runStorageMigrations(plugin, context.storage);
+
+    try {
+      await plugin.init(context);
+      loaded.status = "active";
+      this.hooks.log.info(
+        `Plugin '${plugin.metadata.name}' (${id} v${plugin.metadata.version}) initialized`,
+      );
+    } catch (err) {
+      loaded.status = "error";
+      loaded.error = err as Error;
+      this.hooks.log.error(`Failed to initialize plugin ${id}: ${err}`);
+      throw err;
+    }
+  }
+
+  async unregister(id: string): Promise<void> {
+    const loaded = this.plugins.get(id);
+    if (!loaded) return;
+
+    if (loaded.plugin.teardown && loaded.status === "active") {
+      try {
+        await loaded.plugin.teardown();
+      } catch (err) {
+        this.hooks.log.warn(`Error during plugin ${id} teardown: ${err}`);
+      }
+    }
+
+    this.hooks.releaseResources(id);
+    this.plugins.delete(id);
+    this.hooks.log.info(`Plugin ${id} unregistered`);
+  }
+
+  async toggle(id: string, enabled: boolean): Promise<boolean> {
+    const loaded = this.plugins.get(id);
+    if (!loaded) {
+      throw createError({
+        statusCode: 404,
+        statusMessage: `Plugin '${id}' not found`,
+      });
+    }
+
+    const state = await this.loadState();
+    state[id] = { enabled, updatedAt: Date.now() };
+    await this.saveState(state);
+
+    if (enabled) {
+      await this.enable(id, loaded);
+    } else {
+      await this.disable(id, loaded);
+    }
+
+    return true;
+  }
+
+  private async disable(id: string, loaded: LoadedPlugin): Promise<void> {
+    if (loaded.status !== "active") return;
+
+    if (loaded.plugin.teardown) {
+      try {
+        await loaded.plugin.teardown();
+      } catch (err) {
+        this.hooks.log.warn(`Error tearing down plugin ${id}: ${err}`);
+      }
+    }
+    this.hooks.releaseResources(id);
+    loaded.status = "disabled";
+    this.hooks.log.info(`Plugin '${id}' disabled`);
+    this.hooks.notifyStateChange(id, false);
+  }
+
+  private async enable(id: string, loaded: LoadedPlugin): Promise<void> {
+    if (loaded.status === "active") return;
+
+    const context = await this.hooks.createContext(loaded.plugin);
+    loaded.context = context;
+    await this.runStorageMigrations(loaded.plugin, context.storage);
+    try {
+      await loaded.plugin.init(context);
+      loaded.status = "active";
+      loaded.error = undefined;
+      this.hooks.log.info(`Plugin '${id}' enabled and initialized`);
+      this.hooks.notifyStateChange(id, true);
+    } catch (err) {
+      loaded.status = "error";
+      loaded.error = err as Error;
+      this.hooks.log.error(`Failed to re-initialize plugin ${id}: ${err}`);
+      throw err;
+    }
+  }
+}
diff --git a/server/server/internal/plugins/manager.ts b/server/server/internal/plugins/manager.ts
index 5e3795c49..1dfedb3b1 100644
--- a/server/server/internal/plugins/manager.ts
+++ b/server/server/internal/plugins/manager.ts
@@ -1,40 +1,38 @@
-import { createHash, createHmac, timingSafeEqual } from "node:crypto";
-import { EventEmitter } from "node:events";
-import * as path from "node:path";
-import * as fs from "node:fs/promises";
-import { pathToFileURL } from "node:url";
 import type { H3Event } from "h3";
-import { getQuery, createError } from "h3";
+import { createError } from "h3";
 import type { Logger } from "pino";
 import { logger } from "../logging";
-import { PLUGIN_API_VERSION } from "./types";
-import {
-  PluginApiVersionError,
-  PluginCapabilityError,
-  PluginTrustError,
-} from "./errors";
 import { PluginRegistry } from "./registry";
-import { SIGNATURE_VERSION, signaturePayloadV2 } from "./signature";
+import { PluginEventBus } from "./events";
+import { PluginRouteTable } from "./routes";
+import { PluginWebSocketRegistry } from "./websocket";
+import { PluginLifecycle } from "./lifecycle";
+import {
+  PluginSpiRegistry,
+  createPluginContext as buildPluginContext,
+} from "./context";
+import type { PluginContextHost } from "./context";
+import {
+  checkForUpdates as checkBundledPluginUpdates,
+  discoverAndLoadExternalPlugins as discoverExternalPlugins,
+  getClientAssetPath as resolveClientAssetPath,
+  installBundle as installPluginBundle,
+  installFromUrl as installPluginFromUrl,
+  reloadPlugins as reloadExternalPlugins,
+  removeBundle as removePluginBundle,
+} from "./bundle";
+import type { PluginBundleHost, PluginUpdateInfo } from "./bundle";
 import type {
   CloudSavePathResolver,
-  HttpMethod,
   MetadataProvider,
   PaymentGateway,
-  PluginCapability,
-  PluginContext,
   PluginManifest,
   PluginMetadata,
-  PluginStateRecord,
   PluginStatus,
   PluginStorage,
-  RouteHandler,
-  RouteHandlerContext,
   ServerPlugin,
-  SubscriptionAuthorizer,
   SubscriptionContext,
   WebSocketContext,
-  WebSocketHandler,
-  WebSocketOptions,
 } from "./types";
 
 /** Resolved caller identity passed to route handlers. */
@@ -62,236 +60,48 @@ export interface PluginManagerOptions {
   registryPath?: string;
 }
 
-interface RegisteredRoute {
-  method: HttpMethod;
-  pattern: string;
-  regex: RegExp;
-  paramNames: string[];
-  handler: RouteHandler;
-}
-
-interface SubscriptionAuthorizerEntry {
-  matches: (channel: string) => boolean;
-  authorize: SubscriptionAuthorizer;
-}
-
-const PLUGIN_ID_PATTERN = /^[a-z0-9][a-z0-9._-]*$/i;
-const SHA256_HEX_PATTERN = /^[0-9a-f]{64}$/i;
-
-function isValidPluginId(id: string): boolean {
-  return id.length > 0 && id.length <= 64 && PLUGIN_ID_PATTERN.test(id);
-}
-
-/** Whether a bundle-relative path is executable plugin code. */
-function isBundleCodeFile(rel: string): boolean {
-  const ext = path.extname(rel).toLowerCase();
-  return ext === ".js" || ext === ".mjs" || ext === ".cjs";
-}
-
-/** True when `child` resolves inside (or equals) `parent`. */
-function isInsideDirectory(parent: string, child: string): boolean {
-  const relative = path.relative(parent, child);
-  return (
-    relative === "" ||
-    (!relative.startsWith("..") && !path.isAbsolute(relative))
-  );
-}
-
-function constantTimeEqual(left: string, right: string): boolean {
-  const a = Buffer.from(left, "utf8");
-  const b = Buffer.from(right, "utf8");
-  if (a.length !== b.length) return false;
-  return timingSafeEqual(a, b);
-}
-
-/** Strips trailing slashes without a backtracking-prone regular expression. */
-function trimTrailingSlashes(value: string): string {
-  let end = value.length;
-  while (end > 0 && value[end - 1] === "/") {
-    end--;
-  }
-  return value.slice(0, end);
-}
-
-/** Upper bound on a plugin route pattern, limiting regex construction cost. */
-const MAX_ROUTE_PATTERN_LENGTH = 512;
-
-/** Escapes RegExp metacharacters so literal route text cannot form a pattern. */
-function escapeRegExp(value: string): string {
-  const specials = ".*+?^${}()|[]\\";
-  let escaped = "";
-  for (const char of value) {
-    escaped += specials.includes(char) ? `\\${char}` : char;
-  }
-  return escaped;
-}
-
 /**
- * Translates one token of a plugin route pattern into regex source. Recognises
- * `:name`, `*`, and `**`; every other character is escaped so it stays literal.
+ * Thin facade over the plugin runtime modules: route table, WebSocket
+ * registry, event bus, SPI registry, lifecycle and bundle loader.
  */
-function routeTokenToRegexSource(
-  normalized: string,
-  index: number,
-  paramNames: string[],
-): { source: string; consumed: number } {
-  const char = normalized[index];
-  if (char === ":" && /[A-Za-z0-9_]/.test(normalized[index + 1] ?? "")) {
-    let end = index + 1;
-    while (end < normalized.length && /\w/.test(normalized[end])) {
-      end++;
-    }
-    paramNames.push(normalized.slice(index + 1, end));
-    return { source: "([^/]+)", consumed: end - index };
-  }
-  if (char === "*") {
-    return normalized[index + 1] === "*"
-      ? { source: "(.*)", consumed: 2 }
-      : { source: "([^/]+)", consumed: 1 };
-  }
-  return { source: escapeRegExp(char), consumed: 1 };
-}
-
-/** Resolves a dynamically imported bundle's default or named plugin export. */
-function resolvePluginExport(mod: {
-  default?: unknown;
-  plugin?: unknown;
-}): ServerPlugin | null {
-  const defaultExport = mod.default as Partial<ServerPlugin> | undefined;
-  if (defaultExport && typeof defaultExport.init === "function") {
-    return defaultExport as ServerPlugin;
-  }
-  const namedExport = mod.plugin as Partial<ServerPlugin> | undefined;
-  if (namedExport && typeof namedExport.init === "function") {
-    return namedExport as ServerPlugin;
-  }
-  if (typeof mod.default === "function") {
-    return new (mod.default as new () => ServerPlugin)();
-  }
-  return null;
-}
-
-interface LoadedPlugin {
-  plugin: ServerPlugin;
-  context: PluginContext;
-  status: PluginStatus;
-  error?: Error;
-}
-
-function isIgnoredBundleFile(prefix: string, name: string): boolean {
-  if (prefix) return false;
-  return (
-    name === "drop-plugin.json" ||
-    name === "state.json" ||
-    name === "schema.json"
-  );
-}
-
 export class PluginManager {
-  private readonly plugins = new Map<string, LoadedPlugin>();
-  private readonly routes = new Map<string, RegisteredRoute[]>();
-  private readonly webSockets = new Map<
-    string,
-    { pluginId: string; handler: WebSocketHandler }
-  >();
-  private readonly publicChannels = new Map<string, string>(); // channel -> pluginId
-  private readonly subscriptionAuthorizers = new Map<
-    string,
-    SubscriptionAuthorizerEntry[]
-  >();
-  private readonly eventBus = new EventEmitter();
-  private readonly pluginEventSubscriptions = new Map<
-    string,
-    Array<() => void>
-  >();
-  private readonly metadataProviders = new Map<
-    string,
-    { pluginId: string; provider: MetadataProvider }
-  >();
-  private readonly cloudSaveResolvers = new Map<
-    string,
-    { pluginId: string; resolver: CloudSavePathResolver }
-  >();
-  private readonly paymentGateways = new Map<
-    string,
-    { pluginId: string; gateway: PaymentGateway }
-  >();
+  private readonly options: PluginManagerOptions;
   private readonly log: Logger = logger.child({ name: "plugin-manager" });
-
-  constructor(private readonly options: PluginManagerOptions = {}) {
-    this.eventBus.setMaxListeners(200);
-  }
-
-  private async getDataFolder(): Promise<string> {
-    if (this.options.dataDir !== undefined) {
-      return this.options.dataDir;
-    }
-    const { systemConfig } = await import("../config/sys-conf");
-    return systemConfig.getDataFolder();
-  }
-
-  private async getStateFilePath(): Promise<string> {
-    return path.join(await this.getDataFolder(), "plugins", "_state.json");
-  }
-
-  private async getPluginsDirectory(): Promise<string> {
-    return path.join(await this.getDataFolder(), "plugins");
-  }
-
-  private async loadState(): Promise<Record<string, PluginStateRecord>> {
-    try {
-      const data = await fs.readFile(await this.getStateFilePath(), "utf-8");
-      return JSON.parse(data) as Record<string, PluginStateRecord>;
-    } catch {
-      return {};
-    }
-  }
-
-  private async saveState(
-    state: Record<string, PluginStateRecord>,
-  ): Promise<void> {
-    const filePath = await this.getStateFilePath();
-    await fs.mkdir(path.dirname(filePath), { recursive: true });
-    await fs.writeFile(filePath, JSON.stringify(state, null, 2), "utf-8");
-  }
-
-  private patternToRegex(pattern: string): {
-    regex: RegExp;
-    paramNames: string[];
-  } {
-    if (pattern.length > MAX_ROUTE_PATTERN_LENGTH) {
-      throw new Error(
-        `Plugin route pattern exceeds ${MAX_ROUTE_PATTERN_LENGTH} characters`,
-      );
-    }
-    const paramNames: string[] = [];
-    const normalized = trimTrailingSlashes(
-      pattern.startsWith("/") ? pattern : `/${pattern}`,
-    );
-
-    // Build the pattern token-by-token and escape every literal character, so
-    // a plugin cannot inject regex metacharacters (and thus a ReDoS payload)
-    // through a route pattern.
-    let source = "";
-    for (let index = 0; index < normalized.length;) {
-      const token = routeTokenToRegexSource(normalized, index, paramNames);
-      source += token.source;
-      index += token.consumed;
-    }
-
-    return {
-      regex: new RegExp(`^${source || "/"}(?:/)?$`),
-      paramNames,
+  private readonly routes = new PluginRouteTable();
+  private readonly webSockets = new PluginWebSocketRegistry();
+  private readonly events = new PluginEventBus();
+  private readonly spi = new PluginSpiRegistry();
+  private readonly lifecycle: PluginLifecycle;
+  private readonly contextHost: PluginContextHost;
+  private readonly bundleHost: PluginBundleHost;
+
+  constructor(options: PluginManagerOptions = {}) {
+    this.options = options;
+    this.contextHost = {
+      routes: this.routes,
+      webSockets: this.webSockets,
+      events: this.events,
+      spi: this.spi,
+      log: this.log,
+      createStorage: (pluginId) => this.createStorage(pluginId),
     };
-  }
-
-  private hasCapability(
-    capabilities: PluginCapability[] | undefined,
-    cap: PluginCapability,
-  ): boolean {
-    // Fail closed: a plugin that does not explicitly declare a capability
-    // cannot use it.
-    return capabilities?.includes(cap) ?? false;
+    this.bundleHost = {
+      log: this.log,
+      getPluginsDirectory: () => this.lifecycle.getPluginsDirectory(),
+      getRegistry: () => this.loadRegistry(),
+      registerPlugin: (plugin) => this.registerPlugin(plugin),
+      unregisterPlugin: (id) => this.unregisterPlugin(id),
+      getPlugin: (id) => this.getPlugin(id),
+      listPlugins: () => this.listPlugins(),
+    };
+    this.lifecycle = new PluginLifecycle({
+      dataDir: options.dataDir,
+      log: this.log,
+      createContext: (plugin) => buildPluginContext(this.contextHost, plugin),
+      releaseResources: (id) => this.releaseResources(id),
+      notifyStateChange: (id, enabled) =>
+        this.broadcast("plugins:state", { id, enabled }),
+    });
   }
 
   private async createStorage(pluginId: string): Promise<PluginStorage> {
@@ -302,434 +112,7 @@ export class PluginManager {
     return new FilePluginStorage(pluginId, this.options.dataDir);
   }
 
-  /**
-   * Restrict storage access to plugins that declared the `storage` capability.
-   * Missing capability is fail-closed: every method throws rather than
-   * silently reading/writing.
-   */
-  private guardStorage(
-    pluginId: string,
-    capabilities: PluginCapability[] | undefined,
-    storage: PluginStorage,
-  ): PluginStorage {
-    if (this.hasCapability(capabilities, "storage")) {
-      return storage;
-    }
-    const deny = (operation: string): never => {
-      throw new PluginCapabilityError(pluginId, "storage", operation);
-    };
-    return {
-      get: async () => deny("storage.get"),
-      set: async () => deny("storage.set"),
-      delete: async () => deny("storage.delete"),
-      listKeys: async () => deny("storage.listKeys"),
-      getSchemaVersion: async () => deny("storage.getSchemaVersion"),
-      setSchemaVersion: async () => deny("storage.setSchemaVersion"),
-    };
-  }
-
-  private async createPluginContext(
-    plugin: ServerPlugin,
-  ): Promise<PluginContext> {
-    const id = plugin.metadata.id;
-    const capabilities = plugin.metadata.capabilities;
-    const pluginLogger = this.log.child({ plugin: id });
-    const storage = this.guardStorage(
-      id,
-      capabilities,
-      await this.createStorage(id),
-    );
-    const pluginRoutes: RegisteredRoute[] = [];
-    this.routes.set(id, pluginRoutes);
-    this.pluginEventSubscriptions.set(id, []);
-
-    return {
-      id,
-      logger: pluginLogger,
-      storage,
-      registerRoute: (
-        method: HttpMethod,
-        pattern: string,
-        handler: RouteHandler,
-      ) => {
-        if (!this.hasCapability(capabilities, "routes")) {
-          throw new PluginCapabilityError(
-            id,
-            "routes",
-            `registerRoute(${pattern})`,
-          );
-        }
-
-        const { regex, paramNames } = this.patternToRegex(pattern);
-        pluginRoutes.push({
-          method,
-          pattern,
-          regex,
-          paramNames,
-          handler,
-        });
-        pluginLogger.debug(`Registered route [${method}] ${pattern}`);
-      },
-      broadcast: (channel: string, event: unknown) => {
-        if (!this.hasCapability(capabilities, "events")) {
-          throw new PluginCapabilityError(
-            id,
-            "events",
-            `broadcast(${channel})`,
-          );
-        }
-        this.eventBus.emit(channel, event);
-      },
-      subscribe: (channel: string, listener: (event: unknown) => void) => {
-        if (!this.hasCapability(capabilities, "events")) {
-          throw new PluginCapabilityError(
-            id,
-            "events",
-            `subscribe(${channel})`,
-          );
-        }
-        this.eventBus.on(channel, listener);
-        const off = () => {
-          this.eventBus.off(channel, listener);
-        };
-        const subscriptions = this.pluginEventSubscriptions.get(id) ?? [];
-        subscriptions.push(off);
-        this.pluginEventSubscriptions.set(id, subscriptions);
-        return off;
-      },
-      registerWebSocket: (
-        channel: string,
-        handler: WebSocketHandler,
-        options?: WebSocketOptions,
-      ) => {
-        if (!this.hasCapability(capabilities, "websocket")) {
-          throw new PluginCapabilityError(
-            id,
-            "websocket",
-            `registerWebSocket(${channel})`,
-          );
-        }
-        const existing = this.webSockets.get(channel);
-        if (existing && existing.pluginId !== id) {
-          throw new Error(
-            `WebSocket channel '${channel}' is already claimed by plugin '${existing.pluginId}'`,
-          );
-        }
-        this.webSockets.set(channel, { pluginId: id, handler });
-        if (options?.public) {
-          this.publicChannels.set(channel, id);
-        }
-      },
-      registerPublicWebSocketChannel: (channel: string) => {
-        if (!this.hasCapability(capabilities, "websocket")) {
-          throw new PluginCapabilityError(
-            id,
-            "websocket",
-            `registerPublicWebSocketChannel(${channel})`,
-          );
-        }
-        this.publicChannels.set(channel, id);
-      },
-      registerSubscriptionAuthorizer: (
-        matches: (channel: string) => boolean,
-        authorize: SubscriptionAuthorizer,
-      ) => {
-        if (!this.hasCapability(capabilities, "websocket")) {
-          throw new PluginCapabilityError(
-            id,
-            "websocket",
-            "registerSubscriptionAuthorizer",
-          );
-        }
-        const entries = this.subscriptionAuthorizers.get(id) ?? [];
-        entries.push({ matches, authorize });
-        this.subscriptionAuthorizers.set(id, entries);
-      },
-      fetch: async (input: string | URL, init?: RequestInit) => {
-        if (!this.hasCapability(capabilities, "network")) {
-          throw new PluginCapabilityError(id, "network", "fetch");
-        }
-        return fetch(input, init);
-      },
-      registerMetadataProvider: (provider: MetadataProvider) => {
-        if (
-          !provider ||
-          typeof provider.id !== "string" ||
-          !provider.id.trim()
-        ) {
-          throw new Error("Metadata provider must have a valid non-empty id");
-        }
-        if (!this.hasCapability(capabilities, "metadata:provider")) {
-          throw new PluginCapabilityError(
-            id,
-            "metadata:provider",
-            `registerMetadataProvider(${provider.id})`,
-          );
-        }
-        const existing = this.metadataProviders.get(provider.id);
-        if (existing && existing.pluginId !== id) {
-          throw new Error(
-            `Metadata provider '${provider.id}' is already claimed by plugin '${existing.pluginId}'`,
-          );
-        }
-        this.metadataProviders.set(provider.id, { pluginId: id, provider });
-        pluginLogger.debug(`Registered metadata provider: ${provider.id}`);
-      },
-      registerCloudSaveResolver: (resolver: CloudSavePathResolver) => {
-        if (
-          !resolver ||
-          typeof resolver.id !== "string" ||
-          !resolver.id.trim()
-        ) {
-          throw new Error("Cloud save resolver must have a valid non-empty id");
-        }
-        if (!this.hasCapability(capabilities, "cloudsave:provider")) {
-          throw new PluginCapabilityError(
-            id,
-            "cloudsave:provider",
-            `registerCloudSaveResolver(${resolver.id})`,
-          );
-        }
-        const existing = this.cloudSaveResolvers.get(resolver.id);
-        if (existing && existing.pluginId !== id) {
-          throw new Error(
-            `Cloud save resolver '${resolver.id}' is already claimed by plugin '${existing.pluginId}'`,
-          );
-        }
-        this.cloudSaveResolvers.set(resolver.id, {
-          pluginId: id,
-          resolver,
-        });
-        pluginLogger.debug(`Registered cloud save resolver: ${resolver.id}`);
-      },
-      registerPaymentGateway: (gateway: PaymentGateway) => {
-        if (!gateway || typeof gateway.id !== "string" || !gateway.id.trim()) {
-          throw new Error("Payment gateway must have a valid non-empty id");
-        }
-        if (!this.hasCapability(capabilities, "commerce:payment")) {
-          throw new PluginCapabilityError(
-            id,
-            "commerce:payment",
-            `registerPaymentGateway(${gateway.id})`,
-          );
-        }
-        const existing = this.paymentGateways.get(gateway.id);
-        if (existing && existing.pluginId !== id) {
-          throw new Error(
-            `Payment gateway '${gateway.id}' is already claimed by plugin '${existing.pluginId}'`,
-          );
-        }
-        this.paymentGateways.set(gateway.id, { pluginId: id, gateway });
-        pluginLogger.debug(`Registered payment gateway: ${gateway.id}`);
-      },
-    };
-  }
-
-  /**
-   * Run a plugin's storage migrations when its recorded schema version is
-   * behind the version it declares. No-op for plugins that do not set
-   * `storageVersion`.
-   */
-  private async runStorageMigrations(
-    plugin: ServerPlugin,
-    storage: PluginStorage,
-  ): Promise<void> {
-    const target = plugin.metadata.storageVersion ?? 0;
-    if (target <= 0) return;
-    const current = await storage.getSchemaVersion();
-    if (current >= target) return;
-    if (plugin.migrateStorage) {
-      await plugin.migrateStorage(current, target, storage);
-    }
-    await storage.setSchemaVersion(target);
-  }
-
-  /**
-   * Verify an external bundle's entry file.
-   *
-   * `checksum` (if present) must match the entry file's SHA-256. Signature and
-   * whole-bundle verification happen in {@link verifyBundleFiles} and
-   * {@link verifyBundleSignature} once the bundle contents are known.
-   */
-  private verifyBundleBytes(bytes: Buffer, manifest: PluginManifest): string {
-    const digest = createHash("sha256").update(bytes).digest("hex");
-
-    if (
-      manifest.checksum &&
-      (!SHA256_HEX_PATTERN.test(manifest.checksum) ||
-        !constantTimeEqual(manifest.checksum, digest))
-    ) {
-      throw new Error(
-        `bundle checksum mismatch for ${manifest.id}: expected ${manifest.checksum}, found ${digest}`,
-      );
-    }
-    return digest;
-  }
-
-  /**
-   * Verify every importable file in a bundle and return an aggregate digest
-   * used to cache-bust the entry import.
-   *
-   * A bundle with more than one code file must declare `files` checksums; a
-   * single-file bundle may rely on the entry `checksum`. Values in `files`
-   * must match and cover every code file, so relative imports cannot smuggle
-   * unverified modules into the process.
-   */
-  private async verifyBundleFiles(
-    pluginDir: string,
-    manifest: PluginManifest,
-  ): Promise<string> {
-    const root = path.resolve(pluginDir);
-    const files = await this.listBundleFiles(root);
-    const codeFiles = files.filter(isBundleCodeFile);
-
-    if (manifest.files) {
-      await this.verifyDeclaredBundleFiles(root, files, manifest.files);
-      for (const rel of codeFiles) {
-        if (!(rel in manifest.files)) {
-          throw new Error(
-            `bundle file '${rel}' is not covered by the manifest 'files' checksums`,
-          );
-        }
-      }
-    } else if (codeFiles.length > 1) {
-      throw new Error(
-        `bundle '${manifest.id}' contains multiple code files but no 'files' checksums; refusing unverified imports`,
-      );
-    }
-
-    return await this.aggregateBundleDigest(root, files);
-  }
-
-  /** Verify every declared `files` entry against the bundle on disk. */
-  private async verifyDeclaredBundleFiles(
-    root: string,
-    files: string[],
-    declared: Record<string, string>,
-  ): Promise<void> {
-    for (const [rel, expected] of Object.entries(declared)) {
-      const resolved = path.resolve(root, rel);
-      if (path.isAbsolute(rel) || !isInsideDirectory(root, resolved)) {
-        throw new Error(`invalid bundle file path '${rel}'`);
-      }
-      if (!files.includes(rel)) {
-        throw new Error(`bundle manifest lists missing file '${rel}'`);
-      }
-      const digest = createHash("sha256")
-        .update(await fs.readFile(resolved))
-        .digest("hex");
-      if (
-        !SHA256_HEX_PATTERN.test(expected) ||
-        !constantTimeEqual(expected, digest)
-      ) {
-        throw new Error(`bundle file checksum mismatch for ${rel}`);
-      }
-    }
-  }
-
-  /** SHA-256 over every bundle file, used to cache-bust the entry import. */
-  private async aggregateBundleDigest(
-    root: string,
-    files: string[],
-  ): Promise<string> {
-    const hasher = createHash("sha256");
-    for (const rel of files) {
-      const bytes = await fs.readFile(path.join(root, rel));
-      hasher.update(rel);
-      hasher.update("\0");
-      hasher.update(String(bytes.length));
-      hasher.update("\0");
-      hasher.update(bytes);
-    }
-    return hasher.digest("hex");
-  }
-
-  /** Recursively list bundle files, ignoring installed dependencies and manifest/storage files. */
-  private async listBundleFiles(root: string, prefix = ""): Promise<string[]> {
-    const results: string[] = [];
-    const entries = await fs.readdir(path.join(root, prefix), {
-      withFileTypes: true,
-    });
-    for (const entry of entries) {
-      if (entry.isDirectory() && entry.name !== "node_modules") {
-        const subPrefix = prefix ? `${prefix}/${entry.name}` : entry.name;
-        results.push(...(await this.listBundleFiles(root, subPrefix)));
-      } else if (entry.isFile() && !isIgnoredBundleFile(prefix, entry.name)) {
-        const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
-        results.push(rel);
-      }
-    }
-    return results.sort((a, b) => a.localeCompare(b));
-  }
-
-  /**
-   * Reconstruct the payload a bundle signature covers. Signature v2 covers the
-   * canonical manifest in addition to the file aggregate; legacy bundles (no
-   * marker) cover the file aggregate, or the entry checksum for single-file
-   * bundles.
-   */
-  private resolveSignedPayload(
-    aggregateDigest: string,
-    entryDigest: string,
-    manifest: PluginManifest,
-  ): string {
-    if (manifest.signatureVersion === SIGNATURE_VERSION) {
-      if (!manifest.files) {
-        throw new Error(
-          `bundle ${manifest.id} declares signatureVersion ${SIGNATURE_VERSION} without file checksums`,
-        );
-      }
-      return signaturePayloadV2(
-        aggregateDigest,
-        manifest as unknown as Record<string, unknown>,
-      );
-    }
-    if (manifest.signatureVersion !== undefined) {
-      throw new Error(
-        `bundle ${manifest.id} uses unsupported signatureVersion ${manifest.signatureVersion}`,
-      );
-    }
-    return manifest.files ? aggregateDigest : entryDigest;
-  }
-
-  /**
-   * Verify the bundle signature. When `files` is present the signature covers
-   * the aggregate bundle digest; otherwise it covers the entry checksum
-   * (legacy single-file bundles). `DROP_PLUGIN_REQUIRE_SIGNATURE=true` refuses
-   * unsigned bundles.
-   */
-  private verifyBundleSignature(
-    aggregateDigest: string,
-    entryDigest: string,
-    manifest: PluginManifest,
-  ): void {
-    const signingKey = process.env.DROP_PLUGIN_SIGNING_KEY;
-    if (manifest.signature) {
-      if (!signingKey) {
-        throw new Error(
-          `bundle ${manifest.id} is signed but DROP_PLUGIN_SIGNING_KEY is not set`,
-        );
-      }
-      const covered = this.resolveSignedPayload(
-        aggregateDigest,
-        entryDigest,
-        manifest,
-      );
-      const expected = createHmac("sha256", signingKey)
-        .update(covered)
-        .digest("hex");
-      if (
-        !SHA256_HEX_PATTERN.test(manifest.signature) ||
-        !constantTimeEqual(expected, manifest.signature)
-      ) {
-        throw new Error(`bundle signature mismatch for ${manifest.id}`);
-      }
-    } else if (process.env.DROP_PLUGIN_REQUIRE_SIGNATURE === "true") {
-      throw new Error(`bundle ${manifest.id} is unsigned`);
-    }
-  }
-
-  private async getRegistry(): Promise<PluginRegistry> {
+  private async loadRegistry(): Promise<PluginRegistry> {
     const registryPath =
       this.options.registryPath ?? process.env.DROP_PLUGIN_REGISTRY;
     // Re-read on demand so provisioning or updating the registry file takes
@@ -737,556 +120,59 @@ export class PluginManager {
     return await PluginRegistry.load(registryPath);
   }
 
-  /** Verify, import and register a bundle directory. */
-  private async loadExternalPluginFromDir(
-    pluginDir: string,
-    manifest: PluginManifest,
-  ): Promise<void> {
-    if (!isValidPluginId(manifest.id)) {
-      throw new Error(`invalid plugin id '${manifest.id}'`);
-    }
-
-    // Check if plugin targets server (default true for v1 or when targets includes 'server')
-    const targets = manifest.targets;
-    const targetsServer = !targets || targets.includes("server");
-    const entryRel = manifest.server?.entry || manifest.entry || "index.js";
-    const entryPath = path.resolve(pluginDir, entryRel);
-    if (
-      targetsServer &&
-      (path.isAbsolute(entryRel) ||
-        !isInsideDirectory(path.resolve(pluginDir), entryPath))
-    ) {
-      throw new Error(`invalid entry path '${entryRel}'`);
-    }
-
-    // Validate the declared contract *before* importing: a dynamic import runs
-    // the module's top-level code, so compatibility must be checked on the
-    // manifest, not after the module has already executed.
-    this.assertManifestCompatible(manifest);
-
-    let entryDigest = "";
-    if (targetsServer) {
-      entryDigest = this.verifyBundleBytes(
-        await fs.readFile(entryPath),
-        manifest,
-      );
-    }
-    const aggregateDigest = await this.verifyBundleFiles(pluginDir, manifest);
-    this.verifyBundleSignature(aggregateDigest, entryDigest, manifest);
-    (await this.getRegistry()).check(manifest, entryDigest);
-
-    if (targetsServer) {
-      // Version the import URL by the whole-bundle digest so a change to any
-      // file (not just the entry) forces a fresh entry module instance.
-      const mod = await import(
-        `${pathToFileURL(entryPath).href}?v=${aggregateDigest}`
-      );
-      const pluginInstance = resolvePluginExport(mod);
-
-      if (!pluginInstance) {
-        throw new Error(
-          `Plugin module at ${entryPath} does not export a valid ServerPlugin`,
-        );
-      }
-
-      pluginInstance.metadata = {
-        ...manifest,
-        builtin: false,
-      };
-
-      await this.registerPlugin(pluginInstance);
-    } else {
-      // Client-only plugin registered for discovery and asset serving
-      const clientOnlyPlugin: ServerPlugin = {
-        metadata: {
-          ...manifest,
-          builtin: false,
-        },
-        init: () => {},
-      };
-      await this.registerPlugin(clientOnlyPlugin);
-    }
+  /** Drop a plugin's routes, sockets, SPI entries and event subscriptions. */
+  private releaseResources(id: string): void {
+    this.routes.release(id);
+    this.webSockets.release(id);
+    this.spi.release(id);
+    this.events.release(id);
   }
 
-  /**
-   * Resolve an on-disk asset for client-side bundle serving.
-   * Path traversal or symlink escapes outside the plugin directory return null.
-   */
-  async getClientAssetPath(
-    pluginId: string,
-    assetRelPath: string,
-  ): Promise<string | null> {
-    if (!isValidPluginId(pluginId)) return null;
-    const pluginDir = path.join(await this.getPluginsDirectory(), pluginId);
-    const resolved = path.resolve(pluginDir, assetRelPath);
-    if (!isInsideDirectory(path.resolve(pluginDir), resolved)) {
-      return null;
-    }
-    try {
-      const s = await fs.stat(resolved);
-      if (s.isFile()) {
-        return resolved;
-      }
-    } catch {
-      return null;
-    }
-    return null;
-  }
-
-  /** Validate a manifest's declared contract before importing its module. */
-  private assertManifestCompatible(manifest: PluginManifest): void {
-    const version = manifest.apiVersion ?? 0;
-    if (version !== 1 && version !== PLUGIN_API_VERSION) {
-      throw new PluginApiVersionError(manifest.id, PLUGIN_API_VERSION, version);
-    }
-    if (manifest.trust !== undefined && manifest.trust !== "trusted") {
-      throw new PluginTrustError(manifest.id, manifest.trust);
-    }
-    this.assertClientCommands(manifest);
-  }
-
-  /**
-   * Fail closed on the native-command capability: a plugin that declares
-   * `system:command` must ship a non-empty, bare-name `client.commands`
-   * allowlist. The desktop host enforces the same allowlist at run time; this
-   * rejects a malformed manifest before its module is imported.
-   */
-  private assertClientCommands(manifest: PluginManifest): void {
-    const capabilities = manifest.client?.capabilities ?? [];
-    if (!capabilities.includes("system:command")) return;
-    const commands = manifest.client?.commands;
-    if (!Array.isArray(commands) || commands.length === 0) {
-      throw new Error(
-        `plugin '${manifest.id}' declares 'system:command' but has no client.commands allowlist`,
-      );
-    }
-    for (const command of commands) {
-      if (typeof command !== "string" || command.trim().length === 0) {
-        throw new Error(
-          `plugin '${manifest.id}' has an invalid client.commands entry`,
-        );
-      }
-      if (command.includes("/") || command.includes("\\")) {
-        throw new Error(
-          `plugin '${manifest.id}' client.commands must be bare executable names`,
-        );
-      }
-    }
-  }
-
-  private assertPluginCompatible(plugin: ServerPlugin): void {
-    const { id, apiVersion, trust } = plugin.metadata;
-    const version = apiVersion ?? 0;
-    // Every plugin must declare the contract version it was built against;
-    // omitting it previously bypassed the compatibility gate entirely.
-    if (version !== 1 && version !== PLUGIN_API_VERSION) {
-      throw new PluginApiVersionError(id, PLUGIN_API_VERSION, version);
-    }
-    if (trust !== undefined && trust !== "trusted") {
-      throw new PluginTrustError(id, trust);
+  private async resolveAuth(event: H3Event): Promise<PluginAuthContext> {
+    if (this.options.authResolver) {
+      return this.options.authResolver(event);
     }
+    const { resolvePluginAuth } = await import("./auth");
+    return await resolvePluginAuth(event);
   }
 
   async registerPlugin(plugin: ServerPlugin): Promise<void> {
-    const id = plugin.metadata.id;
-    if (!isValidPluginId(id)) {
-      throw new Error(`invalid plugin id '${id}'`);
-    }
-    this.assertPluginCompatible(plugin);
-    if (this.plugins.has(id)) {
-      this.log.warn(`Plugin ${id} is already registered, replacing`);
-      await this.unregisterPlugin(id);
-    }
-
-    const state = await this.loadState();
-    const isExplicitlyDisabled = state[id]?.enabled === false;
-
-    const context = await this.createPluginContext(plugin);
-    const loaded: LoadedPlugin = {
-      plugin,
-      context,
-      status: isExplicitlyDisabled ? "disabled" : "registered",
-    };
-    this.plugins.set(id, loaded);
-
-    if (isExplicitlyDisabled) {
-      this.log.info(
-        `Plugin '${plugin.metadata.name}' (${id}) is registered but disabled by configuration`,
-      );
-      return;
-    }
-
-    await this.runStorageMigrations(plugin, context.storage);
-
-    try {
-      await plugin.init(context);
-      loaded.status = "active";
-      this.log.info(
-        `Plugin '${plugin.metadata.name}' (${id} v${plugin.metadata.version}) initialized`,
-      );
-    } catch (err) {
-      loaded.status = "error";
-      loaded.error = err as Error;
-      this.log.error(`Failed to initialize plugin ${id}: ${err}`);
-      throw err;
-    }
+    await this.lifecycle.register(plugin);
   }
 
   async unregisterPlugin(id: string): Promise<void> {
-    const loaded = this.plugins.get(id);
-    if (!loaded) return;
-
-    if (loaded.plugin.teardown && loaded.status === "active") {
-      try {
-        await loaded.plugin.teardown();
-      } catch (err) {
-        this.log.warn(`Error during plugin ${id} teardown: ${err}`);
-      }
-    }
-
-    this.releasePluginResources(id);
-    this.plugins.delete(id);
-    this.log.info(`Plugin ${id} unregistered`);
-  }
-
-  /** Deletes every map entry whose value is owned by plugin `id`. */
-  private purgeOwned<V extends { pluginId: string }>(
-    map: Map<string, V>,
-    id: string,
-  ): void {
-    for (const [key, entry] of map) {
-      if (entry.pluginId === id) {
-        map.delete(key);
-      }
-    }
-  }
-
-  /** Drop a plugin's routes, sockets and event subscriptions. */
-  private releasePluginResources(id: string): void {
-    this.routes.delete(id);
-    this.purgeOwned(this.webSockets, id);
-    for (const [channel, pluginId] of this.publicChannels) {
-      if (pluginId === id) {
-        this.publicChannels.delete(channel);
-      }
-    }
-    this.purgeOwned(this.metadataProviders, id);
-    this.purgeOwned(this.cloudSaveResolvers, id);
-    this.purgeOwned(this.paymentGateways, id);
-    this.subscriptionAuthorizers.delete(id);
-    const subscriptions = this.pluginEventSubscriptions.get(id) ?? [];
-    for (const off of subscriptions) {
-      off();
-    }
-    this.pluginEventSubscriptions.delete(id);
+    await this.lifecycle.unregister(id);
   }
 
   async togglePlugin(id: string, enabled: boolean): Promise<boolean> {
-    const loaded = this.plugins.get(id);
-    if (!loaded) {
-      throw createError({
-        statusCode: 404,
-        statusMessage: `Plugin '${id}' not found`,
-      });
-    }
-
-    const state = await this.loadState();
-    state[id] = { enabled, updatedAt: Date.now() };
-    await this.saveState(state);
-
-    if (enabled) {
-      await this.enablePlugin(id, loaded);
-    } else {
-      await this.disablePlugin(id, loaded);
-    }
-
-    return true;
-  }
-
-  private async disablePlugin(id: string, loaded: LoadedPlugin): Promise<void> {
-    if (loaded.status !== "active") return;
-
-    if (loaded.plugin.teardown) {
-      try {
-        await loaded.plugin.teardown();
-      } catch (err) {
-        this.log.warn(`Error tearing down plugin ${id}: ${err}`);
-      }
-    }
-    this.releasePluginResources(id);
-    loaded.status = "disabled";
-    this.log.info(`Plugin '${id}' disabled`);
-    this.broadcast("plugins:state", { id, enabled: false });
-  }
-
-  private async enablePlugin(id: string, loaded: LoadedPlugin): Promise<void> {
-    if (loaded.status === "active") return;
-
-    const context = await this.createPluginContext(loaded.plugin);
-    loaded.context = context;
-    await this.runStorageMigrations(loaded.plugin, context.storage);
-    try {
-      await loaded.plugin.init(context);
-      loaded.status = "active";
-      loaded.error = undefined;
-      this.log.info(`Plugin '${id}' enabled and initialized`);
-      this.broadcast("plugins:state", { id, enabled: true });
-    } catch (err) {
-      loaded.status = "error";
-      loaded.error = err as Error;
-      this.log.error(`Failed to re-initialize plugin ${id}: ${err}`);
-      throw err;
-    }
+    return await this.lifecycle.toggle(id, enabled);
   }
 
   async discoverAndLoadExternalPlugins(): Promise<void> {
-    const pluginsDir = await this.getPluginsDirectory();
-    try {
-      await fs.mkdir(pluginsDir, { recursive: true });
-      const entries = await fs.readdir(pluginsDir, { withFileTypes: true });
-
-      for (const entry of entries) {
-        if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
-        await this.loadExternalPluginEntry(path.join(pluginsDir, entry.name));
-      }
-    } catch (err) {
-      this.log.debug(`External plugins directory check: ${err}`);
-    }
+    await discoverExternalPlugins(this.bundleHost);
   }
 
-  private async loadExternalPluginEntry(pluginDir: string): Promise<void> {
-    const manifestContent = await this.readExternalManifest(pluginDir);
-    if (!manifestContent) return;
-
-    try {
-      const manifest: PluginManifest = JSON.parse(manifestContent);
-      if (
-        !manifest.id ||
-        !manifest.name ||
-        !manifest.version ||
-        !isValidPluginId(manifest.id)
-      ) {
-        this.log.warn(`Invalid plugin manifest in ${pluginDir}`);
-        return;
-      }
-
-      if (this.plugins.has(manifest.id)) {
-        return;
-      }
-
-      await this.loadExternalPluginFromDir(pluginDir, manifest);
-    } catch (err) {
-      this.log.error(
-        `Failed to load external plugin from ${pluginDir}: ${err}`,
-      );
-    }
-  }
-
-  private async readExternalManifest(
-    pluginDir: string,
-  ): Promise<string | undefined> {
-    try {
-      return await fs.readFile(
-        path.join(pluginDir, "drop-plugin.json"),
-        "utf-8",
-      );
-    } catch {
-      try {
-        return await fs.readFile(path.join(pluginDir, "plugin.json"), "utf-8");
-      } catch {
-        return undefined;
-      }
-    }
-  }
-
-  /**
-   * Install (or update) a signed plugin bundle from its manifest and entry source
-   * or multi-file payload, verifying checksums and signatures before loading.
-   */
   async installBundle(
     manifest: PluginManifest,
     entryOrFiles: string | Record<string, string>,
   ): Promise<void> {
-    if (!manifest.id || !manifest.name || !manifest.version) {
-      throw new Error("manifest requires id, name and version");
-    }
-    if (!isValidPluginId(manifest.id)) {
-      throw new Error("invalid plugin id");
-    }
-
-    const pluginsDir = await this.getPluginsDirectory();
-    const bundleDir = path.join(pluginsDir, manifest.id);
-    await fs.mkdir(bundleDir, { recursive: true });
-
-    if (typeof entryOrFiles === "string") {
-      const bytes = Buffer.from(entryOrFiles, "base64");
-      const digest = this.verifyBundleBytes(bytes, manifest);
-      (await this.getRegistry()).check(manifest, digest);
-
-      const entryRel = manifest.entry || "index.js";
-      const entryPath = path.resolve(bundleDir, entryRel);
-      if (
-        path.isAbsolute(entryRel) ||
-        !isInsideDirectory(path.resolve(bundleDir), entryPath)
-      ) {
-        throw new Error("invalid entry path");
-      }
-
-      await fs.mkdir(path.dirname(entryPath), { recursive: true });
-      const storedManifest: PluginManifest = {
-        ...manifest,
-        checksum: manifest.checksum ?? digest,
-      };
-      await fs.writeFile(
-        path.join(bundleDir, "drop-plugin.json"),
-        JSON.stringify(storedManifest, null, 2),
-      );
-      await fs.writeFile(entryPath, bytes);
-
-      await this.loadExternalPluginFromDir(bundleDir, storedManifest);
-    } else if (typeof entryOrFiles === "object" && entryOrFiles !== null) {
-      for (const [rel, base64] of Object.entries(entryOrFiles)) {
-        const resolved = path.resolve(bundleDir, rel);
-        if (
-          path.isAbsolute(rel) ||
-          !isInsideDirectory(path.resolve(bundleDir), resolved)
-        ) {
-          throw new Error(`invalid bundle file path '${rel}'`);
-        }
-        await fs.mkdir(path.dirname(resolved), { recursive: true });
-        await fs.writeFile(resolved, Buffer.from(base64, "base64"));
-      }
-
-      await fs.writeFile(
-        path.join(bundleDir, "drop-plugin.json"),
-        JSON.stringify(manifest, null, 2),
-      );
-
-      await this.loadExternalPluginFromDir(bundleDir, manifest);
-    } else {
-      throw new Error(
-        "invalid bundle payload: expected base64 entry or files map",
-      );
-    }
+    await installPluginBundle(this.bundleHost, manifest, entryOrFiles);
   }
 
-  /**
-   * Download, verify and install a plugin bundle from a remote URL.
-   */
   async installFromUrl(url: string): Promise<void> {
-    if (!url || typeof url !== "string") {
-      throw new Error("Invalid plugin download URL");
-    }
-    const parsed = new URL(url);
-    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-      throw new Error(
-        `Unsupported protocol in URL '${url}': only http and https are allowed`,
-      );
-    }
-
-    const res = await fetch(url, {
-      signal: AbortSignal.timeout(15000),
-      headers: { "User-Agent": "Drop-Plugin-Installer/1.0" },
-    });
-    if (!res.ok) {
-      throw new Error(
-        `Failed to download plugin from '${url}': HTTP ${res.status} ${res.statusText}`,
-      );
-    }
-
-    const text = await res.text();
-    let bundle: {
-      manifest?: PluginManifest;
-      entry?: string;
-      files?: Record<string, string>;
-      format?: string;
-    };
-    try {
-      bundle = JSON.parse(text);
-    } catch (err) {
-      throw new Error(
-        `Downloaded bundle from '${url}' is not valid JSON: ${err}`,
-      );
-    }
-
-    if (!bundle?.manifest || (!bundle.entry && !bundle.files)) {
-      throw new Error(
-        `Downloaded bundle from '${url}' missing required manifest or file payload`,
-      );
-    }
-
-    const payload = bundle.files ?? bundle.entry!;
-    await this.installBundle(bundle.manifest, payload);
+    await installPluginFromUrl(this.bundleHost, url);
   }
 
-  /**
-   * Check installed plugins against configured registry for available updates.
-   */
-  async checkForUpdates(): Promise<
-    Array<{
-      id: string;
-      currentVersion: string;
-      latestVersion: string;
-      hasUpdate: boolean;
-      downloadUrl?: string;
-    }>
-  > {
-    const registry = await this.getRegistry();
-    if (!registry.enabled) {
-      return [];
-    }
-
-    const results: Array<{
-      id: string;
-      currentVersion: string;
-      latestVersion: string;
-      hasUpdate: boolean;
-      downloadUrl?: string;
-    }> = [];
-
-    for (const plugin of this.listPlugins()) {
-      if (plugin.builtin) continue;
-      const entry = registry.getEntry(plugin.id);
-      if (!entry?.version) continue;
-
-      const hasUpdate = entry.version !== plugin.version;
-      results.push({
-        id: plugin.id,
-        currentVersion: plugin.version,
-        latestVersion: entry.version,
-        hasUpdate,
-        downloadUrl: entry.downloadUrl ?? entry.url,
-      });
-    }
-
-    return results;
+  async checkForUpdates(): Promise<PluginUpdateInfo[]> {
+    return await checkBundledPluginUpdates(this.bundleHost);
   }
 
-  /** Remove an external plugin bundle and unregister it. */
   async removeBundle(id: string): Promise<boolean> {
-    if (!isValidPluginId(id)) {
-      throw new Error("invalid plugin id");
-    }
-    const loaded = this.plugins.get(id);
-    if (loaded?.plugin.metadata.builtin) {
-      throw new Error("cannot remove a builtin plugin");
-    }
-
-    await this.unregisterPlugin(id);
-
-    const pluginsDir = await this.getPluginsDirectory();
-    await fs.rm(path.join(pluginsDir, id), { recursive: true, force: true });
-    return true;
+    return await removePluginBundle(this.bundleHost, id);
   }
 
   async reloadPlugins(): Promise<void> {
-    this.log.info("Reloading external plugins...");
-    for (const [id, loaded] of this.plugins.entries()) {
-      if (!loaded.plugin.metadata.builtin) {
-        await this.unregisterPlugin(id);
-      }
-    }
-    await this.discoverAndLoadExternalPlugins();
+    await reloadExternalPlugins(this.bundleHost);
   }
 
   listPlugins(): Array<
@@ -1295,107 +181,83 @@ export class PluginManager {
       error?: string;
     }
   > {
-    return Array.from(this.plugins.values()).map((p) => ({
-      ...p.plugin.metadata,
-      status: p.status,
-      error: p.error?.message,
-    }));
+    return this.lifecycle.list();
   }
 
   getPlugin(id: string): ServerPlugin | undefined {
-    return this.plugins.get(id)?.plugin;
+    return this.lifecycle.get(id);
   }
 
   broadcast(channel: string, data: unknown): void {
-    this.eventBus.emit(channel, data);
+    this.events.emit(channel, data);
   }
 
   subscribe(channel: string, listener: (data: unknown) => void): () => void {
-    this.eventBus.on(channel, listener);
-    return () => {
-      this.eventBus.off(channel, listener);
-    };
+    return this.events.subscribe(channel, listener);
   }
 
-  /**
-   * Whether a client may subscribe to `channel`. Only authorizers whose
-   * `matches` accepts the channel are consulted; when none match the channel
-   * is allowed (the gateway still requires authentication for non-public
-   * channels).
-   */
   async canSubscribe(
     channel: string,
     context: SubscriptionContext,
   ): Promise<boolean> {
-    const matching: SubscriptionAuthorizer[] = [];
-    for (const entries of this.subscriptionAuthorizers.values()) {
-      for (const entry of entries) {
-        if (entry.matches(channel)) matching.push(entry.authorize);
-      }
-    }
-    if (matching.length === 0) return true;
-    for (const authorize of matching) {
-      if (await authorize(channel, context)) return true;
-    }
-    return false;
+    return await this.webSockets.canSubscribe(channel, context);
   }
 
-  /** Route a client WebSocket message to the plugin that claimed the channel. */
   async dispatchWebSocket(
     channel: string,
     message: unknown,
     context: WebSocketContext,
   ): Promise<boolean> {
-    const entry = this.webSockets.get(channel);
-    if (!entry) return false;
-    const loaded = this.plugins.get(entry.pluginId);
-    if (loaded?.status !== "active") return false;
-    await entry.handler(message, context);
-    return true;
+    return await this.webSockets.dispatch(channel, message, context, (id) =>
+      this.lifecycle.isActive(id),
+    );
   }
 
   webSocketChannels(): string[] {
-    return Array.from(this.webSockets.keys());
+    return this.webSockets.channels();
   }
 
   isPublicChannel(channel: string): boolean {
-    return this.publicChannels.has(channel);
+    return this.webSockets.isPublicChannel(channel);
   }
 
   publicWebSocketChannels(): string[] {
-    return Array.from(this.publicChannels.keys());
+    return this.webSockets.publicChannels();
   }
 
   getMetadataProviders(): MetadataProvider[] {
-    return Array.from(this.metadataProviders.values()).map((e) => e.provider);
+    return this.spi.getMetadataProviders();
   }
 
   getMetadataProvider(id: string): MetadataProvider | undefined {
-    return this.metadataProviders.get(id)?.provider;
+    return this.spi.getMetadataProvider(id);
   }
 
   getCloudSaveResolvers(): CloudSavePathResolver[] {
-    return Array.from(this.cloudSaveResolvers.values()).map((e) => e.resolver);
+    return this.spi.getCloudSaveResolvers();
   }
 
   getCloudSaveResolver(id: string): CloudSavePathResolver | undefined {
-    return this.cloudSaveResolvers.get(id)?.resolver;
+    return this.spi.getCloudSaveResolver(id);
   }
 
   getPaymentGateways(): PaymentGateway[] {
-    return Array.from(this.paymentGateways.values()).map((e) => e.gateway);
+    return this.spi.getPaymentGateways();
   }
 
   getPaymentGateway(id: string): PaymentGateway | undefined {
-    return this.paymentGateways.get(id)?.gateway;
+    return this.spi.getPaymentGateway(id);
   }
 
-  private async resolveAuth(event: H3Event): Promise<PluginAuthContext> {
-    if (this.options.authResolver) {
-      return this.options.authResolver(event);
-    }
-    const { resolvePluginAuth } = await import("./auth");
-    return await resolvePluginAuth(event);
+  async getClientAssetPath(
+    pluginId: string,
+    assetRelPath: string,
+  ): Promise<string | null> {
+    return await resolveClientAssetPath(
+      this.bundleHost,
+      pluginId,
+      assetRelPath,
+    );
   }
 
   async dispatch(
@@ -1404,7 +266,7 @@ export class PluginManager {
     rawSubPath: string,
     event: H3Event,
   ): Promise<unknown> {
-    const loaded = this.plugins.get(pluginId);
+    const loaded = this.lifecycle.getRecord(pluginId);
     if (!loaded) {
       throw createError({
         statusCode: 404,
@@ -1419,56 +281,13 @@ export class PluginManager {
       });
     }
 
-    const pluginRoutes = this.routes.get(pluginId) ?? [];
-    const normalizedPath = rawSubPath.startsWith("/")
-      ? rawSubPath
-      : `/${rawSubPath}`;
-    const cleanPath = normalizedPath.split("?")[0] || "/";
-
-    let matchedRoute: RegisteredRoute | null = null;
-    let matchedParams: Record<string, string> = {};
-
-    for (const route of pluginRoutes) {
-      if (route.method !== "ALL" && route.method !== method) {
-        continue;
-      }
-
-      const match = route.regex.exec(cleanPath);
-      if (match) {
-        matchedRoute = route;
-        matchedParams = {};
-        route.paramNames.forEach((name, idx) => {
-          matchedParams[name] = decodeURIComponent(match[idx + 1] || "");
-        });
-        break;
-      }
-    }
-
-    if (!matchedRoute) {
-      throw createError({
-        statusCode: 404,
-        statusMessage: `No handler found for [${method}] ${cleanPath} in plugin '${pluginId}'`,
-      });
-    }
-
-    let userId: string | undefined;
-    let userAcls: string[] | undefined;
-    try {
-      const auth = await this.resolveAuth(event);
-      userId = auth.userId;
-      userAcls = auth.userAcls;
-    } catch {
-      // Unauthenticated callers receive undefined userId
-    }
-
-    const context: RouteHandlerContext = {
-      params: matchedParams,
-      query: getQuery(event),
-      userId,
-      userAcls,
-    };
-
-    return await matchedRoute.handler(event, context);
+    return await this.routes.dispatch(
+      pluginId,
+      method,
+      rawSubPath,
+      event,
+      (h3Event) => this.resolveAuth(h3Event),
+    );
   }
 }
 
diff --git a/server/server/internal/plugins/registry.ts b/server/server/internal/plugins/registry.ts
index 99578a211..88df2eb46 100644
--- a/server/server/internal/plugins/registry.ts
+++ b/server/server/internal/plugins/registry.ts
@@ -1,15 +1,12 @@
 import fs from "node:fs/promises";
-import { timingSafeEqual } from "node:crypto";
 import type { PluginManifest } from "./types";
-
-const SHA256_HEX_PATTERN = /^[0-9a-f]{64}$/i;
-
-function constantTimeEqual(left: string, right: string): boolean {
-  const a = Buffer.from(left, "utf8");
-  const b = Buffer.from(right, "utf8");
-  if (a.length !== b.length) return false;
-  return timingSafeEqual(a, b);
-}
+import {
+  constantTimeEqual,
+  isSha256Hex,
+  verifyBundleFiles,
+  verifyBundleSignature,
+  verifyEntryChecksum,
+} from "./verification";
 
 /** A registry entry pins a plugin's version and/or entry checksum. */
 export interface PluginRegistryEntry {
@@ -108,7 +105,7 @@ export class PluginRegistry {
     }
     if (
       entry.checksum &&
-      (!SHA256_HEX_PATTERN.test(entry.checksum) ||
+      (!isSha256Hex(entry.checksum) ||
         !constantTimeEqual(entry.checksum, digest))
     ) {
       throw new Error(
@@ -116,4 +113,25 @@ export class PluginRegistry {
       );
     }
   }
+
+  /**
+   * Verify an on-disk bundle before its module is imported: entry checksum,
+   * per-file checksums, aggregate digest and signature, then registry
+   * allow-list/pinning. Returns the aggregate digest used to cache-bust the
+   * entry import. `entryPath` is omitted for client-only bundles.
+   */
+  async verifyBundle(
+    pluginDir: string,
+    manifest: PluginManifest,
+    entryPath?: string,
+  ): Promise<string> {
+    let entryDigest = "";
+    if (entryPath !== undefined) {
+      entryDigest = verifyEntryChecksum(await fs.readFile(entryPath), manifest);
+    }
+    const aggregateDigest = await verifyBundleFiles(pluginDir, manifest);
+    verifyBundleSignature(aggregateDigest, entryDigest, manifest);
+    this.check(manifest, entryDigest);
+    return aggregateDigest;
+  }
 }
diff --git a/server/server/internal/plugins/routes.ts b/server/server/internal/plugins/routes.ts
new file mode 100644
index 000000000..6a76be91c
--- /dev/null
+++ b/server/server/internal/plugins/routes.ts
@@ -0,0 +1,187 @@
+import type { H3Event } from "h3";
+import { getQuery, createError } from "h3";
+import type { HttpMethod, RouteHandler, RouteHandlerContext } from "./types";
+
+export interface RegisteredRoute {
+  method: HttpMethod;
+  pattern: string;
+  regex: RegExp;
+  paramNames: string[];
+  handler: RouteHandler;
+}
+
+/** Resolves the caller identity for a dispatched plugin route. */
+export type RouteAuthResolver = (
+  event: H3Event,
+) => Promise<{ userId?: string; userAcls?: string[] }>;
+
+/** Strips trailing slashes without a backtracking-prone regular expression. */
+function trimTrailingSlashes(value: string): string {
+  let end = value.length;
+  while (end > 0 && value[end - 1] === "/") {
+    end--;
+  }
+  return value.slice(0, end);
+}
+
+/** Upper bound on a plugin route pattern, limiting regex construction cost. */
+const MAX_ROUTE_PATTERN_LENGTH = 512;
+
+/** Escapes RegExp metacharacters so literal route text cannot form a pattern. */
+function escapeRegExp(value: string): string {
+  const specials = ".*+?^${}()|[]\\";
+  let escaped = "";
+  for (const char of value) {
+    escaped += specials.includes(char) ? `\\${char}` : char;
+  }
+  return escaped;
+}
+
+/**
+ * Translates one token of a plugin route pattern into regex source. Recognises
+ * `:name`, `*`, and `**`; every other character is escaped so it stays literal.
+ */
+function routeTokenToRegexSource(
+  normalized: string,
+  index: number,
+  paramNames: string[],
+): { source: string; consumed: number } {
+  const char = normalized[index];
+  if (char === ":" && /[A-Za-z0-9_]/.test(normalized[index + 1] ?? "")) {
+    let end = index + 1;
+    while (end < normalized.length && /\w/.test(normalized[end] ?? "")) {
+      end++;
+    }
+    paramNames.push(normalized.slice(index + 1, end));
+    return { source: "([^/]+)", consumed: end - index };
+  }
+  if (char === "*") {
+    return normalized[index + 1] === "*"
+      ? { source: "(.*)", consumed: 2 }
+      : { source: "([^/]+)", consumed: 1 };
+  }
+  return { source: escapeRegExp(char ?? ""), consumed: 1 };
+}
+
+/**
+ * Translates a plugin route pattern into a literal-safe regular expression.
+ * `:name`, `*` and `**` become capture groups; everything else is escaped.
+ */
+export function patternToRegex(pattern: string): {
+  regex: RegExp;
+  paramNames: string[];
+} {
+  if (pattern.length > MAX_ROUTE_PATTERN_LENGTH) {
+    throw new Error(
+      `Plugin route pattern exceeds ${MAX_ROUTE_PATTERN_LENGTH} characters`,
+    );
+  }
+  const paramNames: string[] = [];
+  const normalized = trimTrailingSlashes(
+    pattern.startsWith("/") ? pattern : `/${pattern}`,
+  );
+
+  // Build the pattern token-by-token and escape every literal character, so
+  // a plugin cannot inject regex metacharacters (and thus a ReDoS payload)
+  // through a route pattern.
+  let source = "";
+  for (let index = 0; index < normalized.length; ) {
+    const token = routeTokenToRegexSource(normalized, index, paramNames);
+    source += token.source;
+    index += token.consumed;
+  }
+
+  return {
+    regex: new RegExp(`^${source || "/"}(?:/)?$`),
+    paramNames,
+  };
+}
+
+/** Per-plugin route table plus dispatch into the matching handler. */
+export class PluginRouteTable {
+  private readonly routes = new Map<string, RegisteredRoute[]>();
+
+  /** Reserve (or reset) the route list for `pluginId`. */
+  create(pluginId: string): void {
+    this.routes.set(pluginId, []);
+  }
+
+  register(
+    pluginId: string,
+    method: HttpMethod,
+    pattern: string,
+    handler: RouteHandler,
+  ): void {
+    const { regex, paramNames } = patternToRegex(pattern);
+    this.routes.get(pluginId)?.push({
+      method,
+      pattern,
+      regex,
+      paramNames,
+      handler,
+    });
+  }
+
+  release(pluginId: string): void {
+    this.routes.delete(pluginId);
+  }
+
+  async dispatch(
+    pluginId: string,
+    method: string,
+    rawSubPath: string,
+    event: H3Event,
+    resolveAuth: RouteAuthResolver,
+  ): Promise<unknown> {
+    const pluginRoutes = this.routes.get(pluginId) ?? [];
+    const normalizedPath = rawSubPath.startsWith("/")
+      ? rawSubPath
+      : `/${rawSubPath}`;
+    const cleanPath = normalizedPath.split("?")[0] || "/";
+
+    let matchedRoute: RegisteredRoute | null = null;
+    let matchedParams: Record<string, string> = {};
+
+    for (const route of pluginRoutes) {
+      if (route.method !== "ALL" && route.method !== method) {
+        continue;
+      }
+
+      const match = route.regex.exec(cleanPath);
+      if (match) {
+        matchedRoute = route;
+        matchedParams = {};
+        route.paramNames.forEach((name, idx) => {
+          matchedParams[name] = decodeURIComponent(match[idx + 1] || "");
+        });
+        break;
+      }
+    }
+
+    if (!matchedRoute) {
+      throw createError({
+        statusCode: 404,
+        statusMessage: `No handler found for [${method}] ${cleanPath} in plugin '${pluginId}'`,
+      });
+    }
+
+    let userId: string | undefined;
+    let userAcls: string[] | undefined;
+    try {
+      const auth = await resolveAuth(event);
+      userId = auth.userId;
+      userAcls = auth.userAcls;
+    } catch {
+      // Unauthenticated callers receive undefined userId
+    }
+
+    const context: RouteHandlerContext = {
+      params: matchedParams,
+      query: getQuery(event),
+      userId,
+      userAcls,
+    };
+
+    return await matchedRoute.handler(event, context);
+  }
+}
diff --git a/server/server/internal/plugins/storage.ts b/server/server/internal/plugins/storage.ts
index ce2632f8b..3c8b355b9 100644
--- a/server/server/internal/plugins/storage.ts
+++ b/server/server/internal/plugins/storage.ts
@@ -11,57 +11,17 @@ export class FilePluginStorage implements PluginStorage {
   private readonly filePath: string;
   private readonly schemaPath: string;
   private readonly dirPath: string;
-  private readonly legacyDirPath: string;
   private cache: Record<string, unknown> | null = null;
   private writeLock: Promise<void> = Promise.resolve();
-  private migrationDone = false;
 
   constructor(pluginId: string, dataDir?: string) {
     const base = dataDir ?? defaultDataFolder();
     this.dirPath = path.join(base, "plugin-data", pluginId);
     this.filePath = path.join(this.dirPath, "state.json");
     this.schemaPath = path.join(this.dirPath, "schema.json");
-    this.legacyDirPath = path.join(base, "plugins", pluginId);
-  }
-
-  private async migrateLegacyFiles(): Promise<void> {
-    if (this.migrationDone) return;
-    this.migrationDone = true;
-    try {
-      const legacyState = path.join(this.legacyDirPath, "state.json");
-      const legacySchema = path.join(this.legacyDirPath, "schema.json");
-      await fs.mkdir(this.dirPath, { recursive: true });
-
-      try {
-        await fs.access(this.filePath);
-      } catch {
-        try {
-          const content = await fs.readFile(legacyState, "utf-8");
-          await fs.writeFile(this.filePath, content, "utf-8");
-          await fs.unlink(legacyState).catch(() => {});
-        } catch {
-          // No legacy state
-        }
-      }
-
-      try {
-        await fs.access(this.schemaPath);
-      } catch {
-        try {
-          const content = await fs.readFile(legacySchema, "utf-8");
-          await fs.writeFile(this.schemaPath, content, "utf-8");
-          await fs.unlink(legacySchema).catch(() => {});
-        } catch {
-          // No legacy schema
-        }
-      }
-    } catch {
-      // Best effort migration
-    }
   }
 
   async getSchemaVersion(): Promise<number> {
-    await this.migrateLegacyFiles();
     try {
       const raw = await fs.readFile(this.schemaPath, "utf-8");
       const parsed = JSON.parse(raw) as { version?: unknown };
@@ -83,8 +43,6 @@ export class FilePluginStorage implements PluginStorage {
       return this.cache;
     }
 
-    await this.migrateLegacyFiles();
-
     try {
       const data = await fs.readFile(this.filePath, "utf-8");
       this.cache = JSON.parse(data) as Record<string, unknown>;
diff --git a/server/server/internal/plugins/verification.ts b/server/server/internal/plugins/verification.ts
new file mode 100644
index 000000000..67374ce55
--- /dev/null
+++ b/server/server/internal/plugins/verification.ts
@@ -0,0 +1,233 @@
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { PluginManifest } from "./types";
+import { SIGNATURE_VERSION, signaturePayloadV2 } from "./signature";
+
+const SHA256_HEX_PATTERN = /^[0-9a-f]{64}$/i;
+
+/** Whether a bundle-relative path is executable plugin code. */
+export function isBundleCodeFile(rel: string): boolean {
+  const ext = path.extname(rel).toLowerCase();
+  return ext === ".js" || ext === ".mjs" || ext === ".cjs";
+}
+
+/**
+ * The bundle manifest cannot cover its own digest, so it is excluded from
+ * bundle hashing. This mirrors `server/dev-tools/sign-plugin.mjs` and the
+ * plugin SDK CLI.
+ */
+export function isIgnoredBundleFile(prefix: string, name: string): boolean {
+  return prefix === "" && name === "drop-plugin.json";
+}
+
+/** True when `child` resolves inside (or equals) `parent`. */
+export function isInsideDirectory(parent: string, child: string): boolean {
+  const relative = path.relative(parent, child);
+  return (
+    relative === "" ||
+    (!relative.startsWith("..") && !path.isAbsolute(relative))
+  );
+}
+
+/** Constant-time comparison so digest checks do not leak through timing. */
+export function constantTimeEqual(left: string, right: string): boolean {
+  const a = Buffer.from(left, "utf8");
+  const b = Buffer.from(right, "utf8");
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}
+
+export function isSha256Hex(value: string): boolean {
+  return SHA256_HEX_PATTERN.test(value);
+}
+
+/** SHA-256 of `bytes` as lowercase hex. */
+export function sha256Hex(bytes: Buffer): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+/**
+ * Verify a bundle entry's declared `checksum` (if present) against its bytes
+ * and return the computed digest.
+ */
+export function verifyEntryChecksum(
+  bytes: Buffer,
+  manifest: PluginManifest,
+): string {
+  const digest = sha256Hex(bytes);
+
+  if (
+    manifest.checksum &&
+    (!isSha256Hex(manifest.checksum) ||
+      !constantTimeEqual(manifest.checksum, digest))
+  ) {
+    throw new Error(
+      `bundle checksum mismatch for ${manifest.id}: expected ${manifest.checksum}, found ${digest}`,
+    );
+  }
+  return digest;
+}
+
+/** Recursively list bundle files, ignoring installed dependencies and the manifest. */
+export async function listBundleFiles(
+  root: string,
+  prefix = "",
+): Promise<string[]> {
+  const results: string[] = [];
+  const entries = await fs.readdir(path.join(root, prefix), {
+    withFileTypes: true,
+  });
+  for (const entry of entries) {
+    if (entry.isDirectory() && entry.name !== "node_modules") {
+      const subPrefix = prefix ? `${prefix}/${entry.name}` : entry.name;
+      results.push(...(await listBundleFiles(root, subPrefix)));
+    } else if (entry.isFile() && !isIgnoredBundleFile(prefix, entry.name)) {
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      results.push(rel);
+    }
+  }
+  return results.sort((a, b) => a.localeCompare(b));
+}
+
+/** SHA-256 over every bundle file, used to cache-bust the entry import. */
+export async function aggregateBundleDigest(
+  root: string,
+  files: string[],
+): Promise<string> {
+  const hasher = createHash("sha256");
+  for (const rel of files) {
+    const bytes = await fs.readFile(path.join(root, rel));
+    hasher.update(rel);
+    hasher.update("\0");
+    hasher.update(String(bytes.length));
+    hasher.update("\0");
+    hasher.update(bytes);
+  }
+  return hasher.digest("hex");
+}
+
+/** Verify every declared `files` entry against the bundle on disk. */
+async function verifyDeclaredBundleFiles(
+  root: string,
+  files: string[],
+  declared: Record<string, string>,
+): Promise<void> {
+  for (const [rel, expected] of Object.entries(declared)) {
+    const resolved = path.resolve(root, rel);
+    if (path.isAbsolute(rel) || !isInsideDirectory(root, resolved)) {
+      throw new Error(`invalid bundle file path '${rel}'`);
+    }
+    if (!files.includes(rel)) {
+      throw new Error(`bundle manifest lists missing file '${rel}'`);
+    }
+    const digest = createHash("sha256")
+      .update(await fs.readFile(resolved))
+      .digest("hex");
+    if (!isSha256Hex(expected) || !constantTimeEqual(expected, digest)) {
+      throw new Error(`bundle file checksum mismatch for ${rel}`);
+    }
+  }
+}
+
+/**
+ * Verify every importable file in a bundle and return an aggregate digest
+ * used to cache-bust the entry import.
+ *
+ * A bundle with more than one code file must declare `files` checksums; a
+ * single-file bundle may rely on the entry `checksum`. Values in `files`
+ * must match and cover every code file, so relative imports cannot smuggle
+ * unverified modules into the process.
+ */
+export async function verifyBundleFiles(
+  pluginDir: string,
+  manifest: PluginManifest,
+): Promise<string> {
+  const root = path.resolve(pluginDir);
+  const files = await listBundleFiles(root);
+  const codeFiles = files.filter(isBundleCodeFile);
+
+  if (manifest.files) {
+    await verifyDeclaredBundleFiles(root, files, manifest.files);
+    for (const rel of codeFiles) {
+      if (!(rel in manifest.files)) {
+        throw new Error(
+          `bundle file '${rel}' is not covered by the manifest 'files' checksums`,
+        );
+      }
+    }
+  } else if (codeFiles.length > 1) {
+    throw new Error(
+      `bundle '${manifest.id}' contains multiple code files but no 'files' checksums; refusing unverified imports`,
+    );
+  }
+
+  return await aggregateBundleDigest(root, files);
+}
+
+/**
+ * Reconstruct the payload a bundle signature covers. Signature v2 covers the
+ * canonical manifest in addition to the file aggregate; legacy bundles (no
+ * marker) cover the file aggregate, or the entry checksum for single-file
+ * bundles.
+ */
+export function resolveSignedPayload(
+  aggregateDigest: string,
+  entryDigest: string,
+  manifest: PluginManifest,
+): string {
+  if (manifest.signatureVersion === SIGNATURE_VERSION) {
+    if (!manifest.files) {
+      throw new Error(
+        `bundle ${manifest.id} declares signatureVersion ${SIGNATURE_VERSION} without file checksums`,
+      );
+    }
+    return signaturePayloadV2(
+      aggregateDigest,
+      manifest as unknown as Record<string, unknown>,
+    );
+  }
+  if (manifest.signatureVersion !== undefined) {
+    throw new Error(
+      `bundle ${manifest.id} uses unsupported signatureVersion ${manifest.signatureVersion}`,
+    );
+  }
+  return manifest.files ? aggregateDigest : entryDigest;
+}
+
+/**
+ * Verify the bundle signature. When `files` is present the signature covers
+ * the aggregate bundle digest; otherwise it covers the entry checksum
+ * (legacy single-file bundles). `DROP_PLUGIN_REQUIRE_SIGNATURE=true` refuses
+ * unsigned bundles.
+ */
+export function verifyBundleSignature(
+  aggregateDigest: string,
+  entryDigest: string,
+  manifest: PluginManifest,
+): void {
+  const signingKey = process.env.DROP_PLUGIN_SIGNING_KEY;
+  if (manifest.signature) {
+    if (!signingKey) {
+      throw new Error(
+        `bundle ${manifest.id} is signed but DROP_PLUGIN_SIGNING_KEY is not set`,
+      );
+    }
+    const covered = resolveSignedPayload(
+      aggregateDigest,
+      entryDigest,
+      manifest,
+    );
+    const expected = createHmac("sha256", signingKey)
+      .update(covered)
+      .digest("hex");
+    if (
+      !isSha256Hex(manifest.signature) ||
+      !constantTimeEqual(expected, manifest.signature)
+    ) {
+      throw new Error(`bundle signature mismatch for ${manifest.id}`);
+    }
+  } else if (process.env.DROP_PLUGIN_REQUIRE_SIGNATURE === "true") {
+    throw new Error(`bundle ${manifest.id} is unsigned`);
+  }
+}
diff --git a/server/server/internal/plugins/websocket.ts b/server/server/internal/plugins/websocket.ts
new file mode 100644
index 000000000..95b6b743d
--- /dev/null
+++ b/server/server/internal/plugins/websocket.ts
@@ -0,0 +1,132 @@
+import type {
+  SubscriptionAuthorizer,
+  SubscriptionContext,
+  WebSocketContext,
+  WebSocketHandler,
+  WebSocketOptions,
+} from "./types";
+
+interface SubscriptionAuthorizerEntry {
+  matches: (channel: string) => boolean;
+  authorize: SubscriptionAuthorizer;
+}
+
+/** Deletes every map entry whose value is owned by plugin `id`. */
+function purgeOwned<V extends { pluginId: string }>(
+  map: Map<string, V>,
+  id: string,
+): void {
+  for (const [key, entry] of map) {
+    if (entry.pluginId === id) {
+      map.delete(key);
+    }
+  }
+}
+
+/**
+ * Plugin WebSocket channel registry: handlers, public-channel designations and
+ * subscription authorizers, all reclaimed when their plugin unloads.
+ */
+export class PluginWebSocketRegistry {
+  private readonly handlers = new Map<
+    string,
+    { pluginId: string; handler: WebSocketHandler }
+  >();
+  private readonly publicChannelOwners = new Map<string, string>(); // channel -> pluginId
+  private readonly subscriptionAuthorizers = new Map<
+    string,
+    SubscriptionAuthorizerEntry[]
+  >();
+
+  register(
+    pluginId: string,
+    channel: string,
+    handler: WebSocketHandler,
+    options?: WebSocketOptions,
+  ): void {
+    const existing = this.handlers.get(channel);
+    if (existing && existing.pluginId !== pluginId) {
+      throw new Error(
+        `WebSocket channel '${channel}' is already claimed by plugin '${existing.pluginId}'`,
+      );
+    }
+    this.handlers.set(channel, { pluginId, handler });
+    if (options?.public) {
+      this.publicChannelOwners.set(channel, pluginId);
+    }
+  }
+
+  registerPublic(pluginId: string, channel: string): void {
+    this.publicChannelOwners.set(channel, pluginId);
+  }
+
+  addAuthorizer(
+    pluginId: string,
+    matches: (channel: string) => boolean,
+    authorize: SubscriptionAuthorizer,
+  ): void {
+    const entries = this.subscriptionAuthorizers.get(pluginId) ?? [];
+    entries.push({ matches, authorize });
+    this.subscriptionAuthorizers.set(pluginId, entries);
+  }
+
+  /** Drop a plugin's handlers, public channels and authorizers. */
+  release(pluginId: string): void {
+    purgeOwned(this.handlers, pluginId);
+    for (const [channel, owner] of this.publicChannelOwners) {
+      if (owner === pluginId) {
+        this.publicChannelOwners.delete(channel);
+      }
+    }
+    this.subscriptionAuthorizers.delete(pluginId);
+  }
+
+  /**
+   * Whether a client may subscribe to `channel`. Only authorizers whose
+   * `matches` accepts the channel are consulted; when none match the channel
+   * is allowed (the gateway still requires authentication for non-public
+   * channels).
+   */
+  async canSubscribe(
+    channel: string,
+    context: SubscriptionContext,
+  ): Promise<boolean> {
+    const matching: SubscriptionAuthorizer[] = [];
+    for (const entries of this.subscriptionAuthorizers.values()) {
+      for (const entry of entries) {
+        if (entry.matches(channel)) matching.push(entry.authorize);
+      }
+    }
+    if (matching.length === 0) return true;
+    for (const authorize of matching) {
+      if (await authorize(channel, context)) return true;
+    }
+    return false;
+  }
+
+  /** Route a client WebSocket message to the plugin that claimed the channel. */
+  async dispatch(
+    channel: string,
+    message: unknown,
+    context: WebSocketContext,
+    isPluginActive: (pluginId: string) => boolean,
+  ): Promise<boolean> {
+    const entry = this.handlers.get(channel);
+    if (!entry) return false;
+    if (!isPluginActive(entry.pluginId)) return false;
+    await entry.handler(message, context);
+    return true;
+  }
+
+  channels(): string[] {
+    return Array.from(this.handlers.keys());
+  }
+
+  isPublicChannel(channel: string): boolean {
+    return this.publicChannelOwners.has(channel);
+  }
+
+  publicChannels(): string[] {
+    return Array.from(this.publicChannelOwners.keys());
+  }
+}
diff --git a/server/server/internal/plugins/ws-gateway.ts b/server/server/internal/plugins/ws-gateway.ts
new file mode 100644
index 000000000..072e19eaa
--- /dev/null
+++ b/server/server/internal/plugins/ws-gateway.ts
@@ -0,0 +1,250 @@
+import { resolvePluginAuth } from "./auth";
+import type { SubscriptionContext, WebSocketContext } from "./types";
+
+const CHANNEL_PATTERN = /^[a-zA-Z0-9:_-]{1,128}$/;
+const MAX_MESSAGE_BYTES = 64 * 1024;
+const MAX_SUBSCRIPTIONS_PER_PEER = 32;
+
+/** Minimal structural view of the crossws peer used by the gateway. */
+export type WebSocketPeer = {
+  id: string;
+  request: {
+    headers: Headers;
+  };
+  send: (payload: string) => void;
+  close: () => void;
+};
+
+interface ClientMessage {
+  type?: unknown;
+  channel?: unknown;
+  data?: unknown;
+}
+
+/** Plugin manager surface the gateway needs. */
+export interface PluginWebSocketManager {
+  isPublicChannel(channel: string): boolean;
+  canSubscribe(channel: string, context: SubscriptionContext): Promise<boolean>;
+  subscribe(channel: string, listener: (data: unknown) => void): () => void;
+  dispatchWebSocket(
+    channel: string,
+    message: unknown,
+    context: WebSocketContext,
+  ): Promise<boolean>;
+}
+
+/** Parse a client frame, enforcing the 64 KiB message cap. */
+export function parseClientMessage(
+  message: unknown,
+): ClientMessage | undefined {
+  const text =
+    typeof (message as { text?: () => string }).text === "function"
+      ? (message as { text: () => string }).text()
+      : String(message);
+  if (Buffer.byteLength(text, "utf8") > MAX_MESSAGE_BYTES) return undefined;
+  try {
+    const parsed: unknown = JSON.parse(text);
+    if (parsed !== null && typeof parsed === "object") {
+      return parsed as ClientMessage;
+    }
+  } catch {
+    // Ignore non-JSON messages.
+  }
+  return undefined;
+}
+
+/** Hosts an Origin must match for a browser upgrade. */
+function allowedHostsFor(peer: WebSocketPeer): Set<string> {
+  const allowedHosts = new Set<string>();
+  const host = peer.request.headers.get("host");
+  if (host) allowedHosts.add(host);
+  const forwardedHost = peer.request.headers.get("x-forwarded-host");
+  if (forwardedHost) {
+    for (const item of forwardedHost.split(",")) {
+      const trimmed = item.trim();
+      if (trimmed) allowedHosts.add(trimmed);
+    }
+  }
+  const externalUrl = process.env.EXTERNAL_URL;
+  if (externalUrl) {
+    try {
+      allowedHosts.add(new URL(externalUrl).host);
+    } catch {
+      // Ignore malformed configuration here; auth still applies below.
+    }
+  }
+  return allowedHosts;
+}
+
+// Browsers always send Origin on WebSocket handshakes. Reject cross-site
+// upgrades so a malicious page cannot ride a victim's session cookie into the
+// plugin gateway (non-browser clients omit Origin and are allowed).
+export function isAllowedOrigin(peer: WebSocketPeer): boolean {
+  const origin = peer.request.headers.get("origin");
+  if (!origin) return true;
+
+  const allowedHosts = allowedHostsFor(peer);
+  let originHost: string | undefined;
+  try {
+    originHost = new URL(origin).host;
+  } catch {
+    originHost = undefined;
+  }
+  return (
+    !!originHost && (allowedHosts.size === 0 || allowedHosts.has(originHost))
+  );
+}
+
+async function resolvePeerAuth(
+  peer: WebSocketPeer,
+): Promise<{ userId: string | undefined; userAcls: string[] | undefined }> {
+  try {
+    const auth = await resolvePluginAuth(peer.request);
+    return { userId: auth.userId, userAcls: auth.userAcls };
+  } catch {
+    // Unauthenticated peer.
+    return { userId: undefined, userAcls: undefined };
+  }
+}
+
+function sendChannelError(
+  peer: WebSocketPeer,
+  channel: string,
+  error: string,
+): void {
+  peer.send(JSON.stringify({ channel, error }));
+}
+
+/**
+ * Stateful plugin WebSocket gateway: tracks peer subscriptions/identity and
+ * dispatches client frames to the plugin manager.
+ */
+export class PluginWebSocketGateway {
+  private readonly clientSubscriptions = new Map<string, Array<() => void>>();
+  private readonly clientChannels = new Map<string, Set<string>>();
+  private readonly peerUsers = new Map<string, string | undefined>();
+  private readonly peerAcls = new Map<string, string[] | undefined>();
+
+  constructor(private readonly manager: PluginWebSocketManager) {}
+
+  async open(peer: WebSocketPeer): Promise<void> {
+    if (!isAllowedOrigin(peer)) {
+      peer.close();
+      return;
+    }
+
+    this.clientSubscriptions.set(peer.id, []);
+    this.clientChannels.set(peer.id, new Set());
+
+    // Authenticate the upgrade request so plugins receive a userId. Supports
+    // both browser sessions/API tokens and desktop client JWTs.
+    const { userId, userAcls } = await resolvePeerAuth(peer);
+    this.peerUsers.set(peer.id, userId);
+    this.peerAcls.set(peer.id, userAcls);
+  }
+
+  async message(peer: WebSocketPeer, message: unknown): Promise<void> {
+    try {
+      const parsed = parseClientMessage(message);
+      if (
+        !parsed ||
+        typeof parsed.channel !== "string" ||
+        !CHANNEL_PATTERN.test(parsed.channel)
+      ) {
+        return;
+      }
+      const userId = this.peerUsers.get(peer.id);
+
+      if (parsed.type === "subscribe") {
+        if (!(await this.authorizeChannel(peer, parsed.channel, userId))) {
+          return;
+        }
+        this.handleSubscribe(peer, parsed.channel);
+        return;
+      }
+
+      if (parsed.type === "message") {
+        await this.dispatchClientMessage(
+          peer,
+          parsed.channel,
+          parsed.data,
+          userId,
+        );
+      }
+    } catch {
+      // Ignore non-JSON or invalid messages
+    }
+  }
+
+  close(peer: WebSocketPeer): void {
+    const unsubscribes = this.clientSubscriptions.get(peer.id);
+    if (unsubscribes) {
+      for (const unsub of unsubscribes) {
+        unsub();
+      }
+      this.clientSubscriptions.delete(peer.id);
+    }
+    this.clientChannels.delete(peer.id);
+    this.peerUsers.delete(peer.id);
+    this.peerAcls.delete(peer.id);
+  }
+
+  private async authorizeChannel(
+    peer: WebSocketPeer,
+    channel: string,
+    userId: string | undefined,
+  ): Promise<boolean> {
+    if (!userId && !this.manager.isPublicChannel(channel)) {
+      sendChannelError(peer, channel, "authentication required");
+      return false;
+    }
+
+    // Per-channel authorization (e.g. room membership), when a plugin
+    // registers an authorizer for the channel.
+    const authorized = await this.manager.canSubscribe(channel, {
+      userId,
+      userAcls: this.peerAcls.get(peer.id),
+    });
+    if (!authorized) {
+      sendChannelError(peer, channel, "not authorized for channel");
+      return false;
+    }
+    return true;
+  }
+
+  private handleSubscribe(peer: WebSocketPeer, channel: string): void {
+    const subscriptions = this.clientChannels.get(peer.id);
+    if (!subscriptions || subscriptions.has(channel)) return;
+    if (subscriptions.size >= MAX_SUBSCRIPTIONS_PER_PEER) {
+      sendChannelError(peer, channel, "too many subscriptions");
+      return;
+    }
+    subscriptions.add(channel);
+
+    const unsubscribe = this.manager.subscribe(channel, (event) => {
+      peer.send(JSON.stringify({ channel, data: event }));
+    });
+    this.clientSubscriptions.get(peer.id)?.push(unsubscribe);
+  }
+
+  private async dispatchClientMessage(
+    peer: WebSocketPeer,
+    channel: string,
+    data: unknown,
+    userId: string | undefined,
+  ): Promise<void> {
+    // Unauthenticated peers may only send on public channels.
+    if (!userId && !this.manager.isPublicChannel(channel)) {
+      sendChannelError(peer, channel, "authentication required");
+      return;
+    }
+    const handled = await this.manager.dispatchWebSocket(channel, data, {
+      userId,
+      userAcls: this.peerAcls.get(peer.id),
+      send: (payload) => peer.send(JSON.stringify({ channel, data: payload })),
+    });
+    if (!handled) {
+      sendChannelError(peer, channel, "no plugin handler for channel");
+    }
+  }
+}

From 8c1e55c570c8bf3771a1c54d78f31b82b410524d Mon Sep 17 00:00:00 2001
From: John Smith <you@example.com>
Date: Mon, 14 Sep 2026 23:13:59 -0400
Subject: [PATCH 07/13] refactor(desktop): move plugin host into its own crate
 with DB-backed storage

- new desktop/src-tauri/plugins crate owns the Tauri plugin commands and
  the moved path_guard module
- plugin key/value storage is persisted through the Rust database instead
  of webview localStorage, keeping one source of truth
- remove the discouraged command blocklist and keep the fail-closed
  per-plugin allowlist with explicit trust guidance
---
 .../internal/plugins/ClientPluginManager.ts   |  62 ++-
 desktop/src-tauri/Cargo.lock                  |  17 +-
 desktop/src-tauri/Cargo.toml                  |   2 +
 desktop/src-tauri/database/Cargo.toml         |   1 +
 desktop/src-tauri/database/src/models.rs      |   8 +
 desktop/src-tauri/plugins/Cargo.toml          |  16 +
 desktop/src-tauri/plugins/src/allowlist.rs    |  49 ++
 desktop/src-tauri/plugins/src/game_fs.rs      | 109 +++++
 desktop/src-tauri/plugins/src/lib.rs          |  17 +
 .../{process => plugins}/src/path_guard.rs    |   0
 desktop/src-tauri/plugins/src/scanner.rs      | 133 ++++++
 desktop/src-tauri/plugins/src/storage.rs      |  76 +++
 desktop/src-tauri/plugins/src/system.rs       | 115 +++++
 desktop/src-tauri/process/Cargo.toml          |   3 -
 desktop/src-tauri/process/src/lib.rs          |   1 -
 desktop/src-tauri/src/lib.rs                  |   5 +-
 desktop/src-tauri/src/plugins.rs              | 451 ------------------
 17 files changed, 587 insertions(+), 478 deletions(-)
 create mode 100644 desktop/src-tauri/plugins/Cargo.toml
 create mode 100644 desktop/src-tauri/plugins/src/allowlist.rs
 create mode 100644 desktop/src-tauri/plugins/src/game_fs.rs
 create mode 100644 desktop/src-tauri/plugins/src/lib.rs
 rename desktop/src-tauri/{process => plugins}/src/path_guard.rs (100%)
 create mode 100644 desktop/src-tauri/plugins/src/scanner.rs
 create mode 100644 desktop/src-tauri/plugins/src/storage.rs
 create mode 100644 desktop/src-tauri/plugins/src/system.rs
 delete mode 100644 desktop/src-tauri/src/plugins.rs

diff --git a/desktop/main/internal/plugins/ClientPluginManager.ts b/desktop/main/internal/plugins/ClientPluginManager.ts
index e467a11a8..f1ecc54f5 100644
--- a/desktop/main/internal/plugins/ClientPluginManager.ts
+++ b/desktop/main/internal/plugins/ClientPluginManager.ts
@@ -44,40 +44,60 @@ async function safeInvoke<T>(
   return await invoke<T>(cmd, args);
 }
 
-class BrowserLocalStorage implements ClientPluginStorage {
-  constructor(private readonly pluginId: string) {}
+class TauriPluginStorage implements ClientPluginStorage {
+  // Browser/dev fallback. Plugin state lives in the Rust-side database when
+  // Tauri is available so frontend and backend never split their state.
+  private readonly memory = new Map<string, unknown>();
 
-  private prefixKey(key: string): string {
-    return `drop:plugin:${this.pluginId}:${key}`;
-  }
+  constructor(private readonly pluginId: string) {}
 
   async get<T>(key: string): Promise<T | null> {
-    try {
-      const val = localStorage.getItem(this.prefixKey(key));
-      return val ? JSON.parse(val) : null;
-    } catch {
-      return null;
+    if (!isTauri()) {
+      return this.memory.has(key) ? (this.memory.get(key) as T) : null;
     }
+    return (
+      (await safeInvoke<T | null>(
+        "plugin_storage_get",
+        { pluginId: this.pluginId, key },
+        null,
+      )) ?? null
+    );
   }
 
   async set<T>(key: string, value: T): Promise<void> {
-    localStorage.setItem(this.prefixKey(key), JSON.stringify(value));
+    if (!isTauri()) {
+      this.memory.set(key, value);
+      return;
+    }
+    await safeInvoke("plugin_storage_set", {
+      pluginId: this.pluginId,
+      key,
+      value,
+    });
   }
 
   async delete(key: string): Promise<void> {
-    localStorage.removeItem(this.prefixKey(key));
+    if (!isTauri()) {
+      this.memory.delete(key);
+      return;
+    }
+    await safeInvoke("plugin_storage_delete", {
+      pluginId: this.pluginId,
+      key,
+    });
   }
 
   async listKeys(): Promise<string[]> {
-    const prefix = `drop:plugin:${this.pluginId}:`;
-    const keys: string[] = [];
-    for (let i = 0; i < localStorage.length; i++) {
-      const k = localStorage.key(i);
-      if (k?.startsWith(prefix)) {
-        keys.push(k.slice(prefix.length));
-      }
+    if (!isTauri()) {
+      return Array.from(this.memory.keys());
     }
-    return keys;
+    return (
+      (await safeInvoke<string[]>(
+        "plugin_storage_list_keys",
+        { pluginId: this.pluginId },
+        [],
+      )) || []
+    );
   }
 }
 
@@ -293,7 +313,7 @@ export class ClientPluginManager {
         debug: (msg, ...args) =>
           console.debug(`[Plugin:${pluginId}] ${msg}`, ...args),
       },
-      storage: new BrowserLocalStorage(pluginId),
+      storage: new TauriPluginStorage(pluginId),
       registerSlot: (slot, component, options) => {
         if (!this.slots[slot]) {
           this.slots[slot] = [];
diff --git a/desktop/src-tauri/Cargo.lock b/desktop/src-tauri/Cargo.lock
index 6a8ad7988..8191e06a7 100644
--- a/desktop/src-tauri/Cargo.lock
+++ b/desktop/src-tauri/Cargo.lock
@@ -1125,6 +1125,7 @@ dependencies = [
  "rand 0.10.2",
  "ron",
  "serde",
+ "serde_json",
  "serde_with",
  "url",
  "whoami",
@@ -1427,6 +1428,7 @@ dependencies = [
  "native_model",
  "page_size",
  "parking_lot 0.12.5",
+ "plugins",
  "process",
  "rand 0.10.2",
  "rayon",
@@ -4453,6 +4455,20 @@ dependencies = [
  "time",
 ]
 
+[[package]]
+name = "plugins"
+version = "0.1.0"
+dependencies = [
+ "database",
+ "serde",
+ "serde_json",
+ "sha2 0.10.9",
+ "tauri",
+ "tempfile",
+ "tokio",
+ "walkdir",
+]
+
 [[package]]
 name = "png"
 version = "0.17.16"
@@ -4616,7 +4632,6 @@ dependencies = [
  "shell-words",
  "tauri",
  "tauri-plugin-opener",
- "tempfile",
  "utils",
 ]
 
diff --git a/desktop/src-tauri/Cargo.toml b/desktop/src-tauri/Cargo.toml
index dfbfa276a..064a6cadb 100644
--- a/desktop/src-tauri/Cargo.toml
+++ b/desktop/src-tauri/Cargo.toml
@@ -13,6 +13,7 @@ members = [
   "database",
   "download_manager",
   "games",
+  "plugins",
   "process",
   "remote",
   "utils",
@@ -59,6 +60,7 @@ native_model = { path = "../../libraries/native_model", features = [
 ] }
 page_size = "0.6.0"
 parking_lot = "0.12.3"
+plugins = { path = "./plugins", version = "0.1.0" } # client plugin host
 process = { path = "./process" } # process
 rand = "0.10.2"
 rayon = "1.10.0"
diff --git a/desktop/src-tauri/database/Cargo.toml b/desktop/src-tauri/database/Cargo.toml
index 42e04e1aa..0eef31598 100644
--- a/desktop/src-tauri/database/Cargo.toml
+++ b/desktop/src-tauri/database/Cargo.toml
@@ -14,6 +14,7 @@ log = "0.4.28"
 rand = "0.10.2"
 ron = "0.12.0"
 serde = "1.0.228"
+serde_json = "1.0.145"
 serde_with = "3.15.0"
 url = "2.5.7"
 whoami = "1.6.1"
diff --git a/desktop/src-tauri/database/src/models.rs b/desktop/src-tauri/database/src/models.rs
index 744502da6..241e5ee51 100644
--- a/desktop/src-tauri/database/src/models.rs
+++ b/desktop/src-tauri/database/src/models.rs
@@ -272,6 +272,13 @@ pub mod data {
             pub applications: DatabaseApplications,
             pub cache_dir: PathBuf,
 
+            /// Per-plugin key/value storage for client plugins. Keyed by plugin
+            /// id first so plugin data stays isolated from other plugins. The
+            /// field is `#[serde(default)]` so databases written before it
+            /// existed still deserialize (versioned via `DatabaseVersionEnum`).
+            #[serde(default)]
+            pub plugin_storage: HashMap<String, HashMap<String, serde_json::Value>>,
+
             #[serde(skip)]
             pub prev_database: Option<PathBuf>,
         }
@@ -298,6 +305,7 @@ pub mod data {
                 auth: None,
                 settings: Settings::default(),
                 cache_dir,
+                plugin_storage: HashMap::new(),
             }
         }
     }
diff --git a/desktop/src-tauri/plugins/Cargo.toml b/desktop/src-tauri/plugins/Cargo.toml
new file mode 100644
index 000000000..e1f9e6d94
--- /dev/null
+++ b/desktop/src-tauri/plugins/Cargo.toml
@@ -0,0 +1,16 @@
+[package]
+name = "plugins"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+database = { path = "../database", version = "0.1.0" }
+serde = { version = "1.0.228", features = ["derive"] }
+serde_json = "1.0.145"
+sha2 = "0.10.9"
+tauri = "*"
+tokio = { version = "1.40.0", features = ["process", "time"] }
+walkdir = "2.5.0"
+
+[dev-dependencies]
+tempfile = "3"
diff --git a/desktop/src-tauri/plugins/src/allowlist.rs b/desktop/src-tauri/plugins/src/allowlist.rs
new file mode 100644
index 000000000..ac3e56484
--- /dev/null
+++ b/desktop/src-tauri/plugins/src/allowlist.rs
@@ -0,0 +1,49 @@
+use std::collections::{HashMap, HashSet};
+use std::sync::Mutex;
+
+/// Per-plugin allowlist of bare executable names a client plugin may run via
+/// `ctx.system.run`. Populated from `manifest.client.commands` by the host when
+/// a plugin is registered; the Tauri command layer is the enforcement point so
+/// a plugin cannot bypass it from the webview.
+///
+/// # Security
+///
+/// This allowlist is **fail-closed**: a command that is not explicitly
+/// registered for a plugin is always rejected by [`crate::plugin_system_run`].
+///
+/// There is deliberately **no blocklist** of "dangerous" commands. Blocklists
+/// are trivially bypassed (renamed binaries, wrapper scripts, aliases) and
+/// silently reject legitimate tooling, so the host does not pretend they
+/// provide a security boundary.
+///
+/// That means an allowlisted command is a deliberate trust decision by the
+/// user/host: it is executed **directly, unsandboxed, with the full privileges
+/// of the user running Drop**. A malicious plugin that gets a command into its
+/// allowlist can do anything the user can do.
+///
+/// **Only install plugins you fully trust.**
+#[derive(Default)]
+pub struct PluginCommandAllowlist(pub Mutex<HashMap<String, HashSet<String>>>);
+
+/// Validate the shape of a command name.
+///
+/// Only bare executable names are allowed (no path separators, no leading `.`
+/// or `-`, ASCII alphanumerics plus `_`, `-`, `.`). This is a syntax check,
+/// not a trust decision: trust comes from the per-plugin allowlist itself.
+pub(crate) fn validate_command_name(command: &str) -> Result<(), String> {
+    if command.is_empty() || command.len() > 64 {
+        return Err(format!("invalid command length: '{command}'"));
+    }
+    if command.starts_with('.') || command.starts_with('-') {
+        return Err(format!("command cannot start with '.' or '-': '{command}'"));
+    }
+    if !command
+        .chars()
+        .all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-' || c == '.')
+    {
+        return Err(format!(
+            "command contains disallowed characters (only alphanumeric, _, -, . allowed): '{command}'"
+        ));
+    }
+    Ok(())
+}
diff --git a/desktop/src-tauri/plugins/src/game_fs.rs b/desktop/src-tauri/plugins/src/game_fs.rs
new file mode 100644
index 000000000..12cbba337
--- /dev/null
+++ b/desktop/src-tauri/plugins/src/game_fs.rs
@@ -0,0 +1,109 @@
+use std::fs;
+use std::path::PathBuf;
+
+use database::borrow_db_checked;
+
+use crate::path_guard;
+
+pub(crate) fn get_game_install_dir(game_id: &str) -> Result<PathBuf, String> {
+    let db = borrow_db_checked();
+    if let Some(database::GameDownloadStatus::Installed { install_dir, .. }) =
+        db.applications.game_statuses.get(game_id)
+    {
+        let path = PathBuf::from(install_dir);
+        if path.exists() {
+            return Ok(path);
+        }
+        return Err(format!(
+            "Game install directory does not exist: {}",
+            path.display()
+        ));
+    }
+    Err(format!(
+        "Game with id '{game_id}' is not installed or not found in local database"
+    ))
+}
+
+#[tauri::command]
+pub async fn plugin_game_fs_read(
+    game_id: String,
+    relative_path: String,
+) -> Result<Vec<u8>, String> {
+    let install_dir = get_game_install_dir(&game_id)?;
+    let safe_path = path_guard::safe_join(&install_dir, &relative_path)
+        .map_err(|e| format!("Security check failed: {e}"))?;
+
+    fs::read(&safe_path).map_err(|e| format!("Failed to read {relative_path}: {e}"))
+}
+
+#[tauri::command]
+pub async fn plugin_game_fs_write(
+    game_id: String,
+    relative_path: String,
+    data: Vec<u8>,
+) -> Result<(), String> {
+    let install_dir = get_game_install_dir(&game_id)?;
+    path_guard::write_file(&install_dir, &relative_path, &data)
+        .map_err(|e| format!("Failed to write {relative_path}: {e}"))
+}
+
+#[tauri::command]
+pub async fn plugin_game_fs_backup(
+    game_id: String,
+    relative_path: String,
+) -> Result<String, String> {
+    let install_dir = get_game_install_dir(&game_id)?;
+    let src_path = path_guard::safe_join(&install_dir, &relative_path)
+        .map_err(|e| format!("Security check failed: {e}"))?;
+
+    if !src_path.exists() {
+        return Err(format!(
+            "Cannot backup nonexistent file: {}",
+            src_path.display()
+        ));
+    }
+
+    let backup_relative = format!("{}.drop-backup", relative_path);
+    path_guard::copy_to(&install_dir, &src_path, &backup_relative)
+        .map_err(|e| format!("Failed to create backup {backup_relative}: {e}"))?;
+
+    Ok(backup_relative)
+}
+
+#[tauri::command]
+pub async fn plugin_game_fs_restore(game_id: String, relative_path: String) -> Result<(), String> {
+    let install_dir = get_game_install_dir(&game_id)?;
+    let backup_relative = format!("{}.drop-backup", relative_path);
+    let backup_path = path_guard::safe_join(&install_dir, &backup_relative)
+        .map_err(|e| format!("Security check failed: {e}"))?;
+
+    if !backup_path.exists() {
+        return Err(format!(
+            "Cannot restore missing backup file: {backup_relative}"
+        ));
+    }
+
+    path_guard::copy_to(&install_dir, &backup_path, &relative_path)
+        .map_err(|e| format!("Failed to restore file from backup: {e}"))?;
+
+    // Cleanup backup file
+    let _ = path_guard::remove_file(&install_dir, &backup_relative);
+
+    Ok(())
+}
+
+#[tauri::command]
+pub async fn plugin_game_fs_exists(game_id: String, relative_path: String) -> Result<bool, String> {
+    let install_dir = get_game_install_dir(&game_id)?;
+    match path_guard::safe_join(&install_dir, &relative_path) {
+        Ok(safe_path) => Ok(safe_path.exists()),
+        Err(_) => Ok(false),
+    }
+}
+
+#[tauri::command]
+pub async fn plugin_game_fs_delete(game_id: String, relative_path: String) -> Result<(), String> {
+    let install_dir = get_game_install_dir(&game_id)?;
+    path_guard::remove_file(&install_dir, &relative_path)
+        .map_err(|e| format!("Failed to delete {relative_path}: {e}"))
+}
diff --git a/desktop/src-tauri/plugins/src/lib.rs b/desktop/src-tauri/plugins/src/lib.rs
new file mode 100644
index 000000000..27fbbd1dc
--- /dev/null
+++ b/desktop/src-tauri/plugins/src/lib.rs
@@ -0,0 +1,17 @@
+mod allowlist;
+mod game_fs;
+pub mod path_guard;
+mod scanner;
+mod storage;
+mod system;
+
+pub use allowlist::PluginCommandAllowlist;
+pub use game_fs::{
+    plugin_game_fs_backup, plugin_game_fs_delete, plugin_game_fs_exists, plugin_game_fs_read,
+    plugin_game_fs_restore, plugin_game_fs_write,
+};
+pub use scanner::{ScannedExecutable, plugin_game_find_files, plugin_game_scan_executables};
+pub use storage::{
+    plugin_storage_delete, plugin_storage_get, plugin_storage_list_keys, plugin_storage_set,
+};
+pub use system::{CommandOutput, plugin_register_commands, plugin_system_run};
diff --git a/desktop/src-tauri/process/src/path_guard.rs b/desktop/src-tauri/plugins/src/path_guard.rs
similarity index 100%
rename from desktop/src-tauri/process/src/path_guard.rs
rename to desktop/src-tauri/plugins/src/path_guard.rs
diff --git a/desktop/src-tauri/plugins/src/scanner.rs b/desktop/src-tauri/plugins/src/scanner.rs
new file mode 100644
index 000000000..43bf23731
--- /dev/null
+++ b/desktop/src-tauri/plugins/src/scanner.rs
@@ -0,0 +1,133 @@
+use std::fs::File;
+use std::io::{self, Read};
+use std::path::Path;
+
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+use walkdir::WalkDir;
+
+use crate::game_fs::get_game_install_dir;
+use crate::path_guard;
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ScannedExecutable {
+    pub relative_path: String,
+    pub sha256: String,
+    pub size: u64,
+}
+
+fn compute_file_sha256(path: &Path) -> io::Result<String> {
+    let mut file = File::open(path)?;
+    let mut hasher = Sha256::new();
+    let mut buffer = [0u8; 64 * 1024];
+
+    loop {
+        let bytes_read = file.read(&mut buffer)?;
+        if bytes_read == 0 {
+            break;
+        }
+        hasher.update(&buffer[..bytes_read]);
+    }
+
+    Ok(format!("{:x}", hasher.finalize()))
+}
+
+#[tauri::command]
+pub async fn plugin_game_scan_executables(
+    game_id: String,
+) -> Result<Vec<ScannedExecutable>, String> {
+    let install_dir = get_game_install_dir(&game_id)?;
+    let mut executables = Vec::new();
+
+    for entry in WalkDir::new(&install_dir)
+        .into_iter()
+        .filter_map(|e| e.ok())
+    {
+        let path = entry.path();
+        if !path.is_file() {
+            continue;
+        }
+
+        // Never follow or scan symlinks for executable security
+        if path_guard::is_symlink(path) {
+            continue;
+        }
+
+        let is_exec = if let Some(ext) = path.extension().and_then(|s| s.to_str()) {
+            let lower = ext.to_lowercase();
+            matches!(
+                lower.as_str(),
+                "exe" | "dll" | "so" | "bin" | "x86_64" | "elf" | "dylib"
+            )
+        } else {
+            false
+        };
+
+        #[cfg(unix)]
+        let is_exec = is_exec || {
+            use std::os::unix::fs::PermissionsExt;
+            entry
+                .metadata()
+                .map(|m| (m.permissions().mode() & 0o111) != 0)
+                .unwrap_or(false)
+        };
+
+        if is_exec && let Ok(rel_path) = path.strip_prefix(&install_dir) {
+            let size = entry.metadata().map(|m| m.len()).unwrap_or(0);
+            let sha256 =
+                compute_file_sha256(path).unwrap_or_else(|_| String::from("unknown-sha256"));
+
+            executables.push(ScannedExecutable {
+                relative_path: rel_path.to_string_lossy().to_string(),
+                sha256,
+                size,
+            });
+        }
+    }
+
+    Ok(executables)
+}
+
+/// Find files inside an installed game whose relative path contains any of the
+/// supplied patterns (case-insensitive substring). The host is deliberately
+/// agnostic about what the patterns mean, so domain knowledge (e.g. which paths
+/// indicate a particular anti-cheat or compatibility tool) lives in the calling
+/// plugin, not in core. Symlinks are never followed.
+#[tauri::command]
+pub async fn plugin_game_find_files(
+    game_id: String,
+    patterns: Vec<String>,
+) -> Result<Vec<String>, String> {
+    let install_dir = get_game_install_dir(&game_id)?;
+
+    let normalized: Vec<String> = patterns
+        .into_iter()
+        .map(|pattern| pattern.trim().to_ascii_lowercase())
+        .filter(|pattern| !pattern.is_empty() && pattern.len() <= 128)
+        .collect();
+    if normalized.is_empty() {
+        return Ok(Vec::new());
+    }
+
+    let mut matches = Vec::new();
+    for entry in WalkDir::new(&install_dir)
+        .into_iter()
+        .filter_map(|e| e.ok())
+    {
+        let path = entry.path();
+        if !path.is_file() || path_guard::is_symlink(path) {
+            continue;
+        }
+
+        let Ok(rel) = path.strip_prefix(&install_dir) else {
+            continue;
+        };
+        let rel_str = rel.to_string_lossy().to_ascii_lowercase();
+        if normalized.iter().any(|pattern| rel_str.contains(pattern)) {
+            matches.push(rel.to_string_lossy().to_string());
+        }
+    }
+
+    Ok(matches)
+}
diff --git a/desktop/src-tauri/plugins/src/storage.rs b/desktop/src-tauri/plugins/src/storage.rs
new file mode 100644
index 000000000..94830990c
--- /dev/null
+++ b/desktop/src-tauri/plugins/src/storage.rs
@@ -0,0 +1,76 @@
+use database::{borrow_db_checked, borrow_db_mut_checked};
+use serde_json::Value;
+
+/// Maximum accepted length (in bytes) for a plugin id or storage key. Storage
+/// is keyed by plugin id in the Rust-side database, so bounds keep a runaway
+/// plugin from growing the database with absurd identifiers.
+const MAX_IDENTIFIER_LEN: usize = 256;
+
+fn validate_identifier(label: &str, value: &str) -> Result<(), String> {
+    if value.trim().is_empty() {
+        return Err(format!("{label} must not be empty"));
+    }
+    if value.len() > MAX_IDENTIFIER_LEN {
+        return Err(format!(
+            "{label} must be at most {MAX_IDENTIFIER_LEN} characters"
+        ));
+    }
+    Ok(())
+}
+
+/// Read a value previously stored by `plugin_id` under `key`.
+#[tauri::command]
+pub fn plugin_storage_get(plugin_id: String, key: String) -> Result<Option<Value>, String> {
+    validate_identifier("plugin_id", &plugin_id)?;
+    validate_identifier("key", &key)?;
+
+    let db = borrow_db_checked();
+    Ok(db
+        .plugin_storage
+        .get(&plugin_id)
+        .and_then(|entries| entries.get(&key))
+        .cloned())
+}
+
+/// Store `value` for `plugin_id` under `key`, replacing any previous value.
+#[tauri::command]
+pub fn plugin_storage_set(plugin_id: String, key: String, value: Value) -> Result<(), String> {
+    validate_identifier("plugin_id", &plugin_id)?;
+    validate_identifier("key", &key)?;
+
+    let mut db = borrow_db_mut_checked();
+    db.plugin_storage
+        .entry(plugin_id)
+        .or_default()
+        .insert(key, value);
+    Ok(())
+}
+
+/// Remove the value stored by `plugin_id` under `key`. Missing keys are a
+/// no-op.
+#[tauri::command]
+pub fn plugin_storage_delete(plugin_id: String, key: String) -> Result<(), String> {
+    validate_identifier("plugin_id", &plugin_id)?;
+    validate_identifier("key", &key)?;
+
+    let mut db = borrow_db_mut_checked();
+    if let Some(entries) = db.plugin_storage.get_mut(&plugin_id) {
+        entries.remove(&key);
+    }
+    Ok(())
+}
+
+/// List every key `plugin_id` has stored, sorted for deterministic output.
+#[tauri::command]
+pub fn plugin_storage_list_keys(plugin_id: String) -> Result<Vec<String>, String> {
+    validate_identifier("plugin_id", &plugin_id)?;
+
+    let db = borrow_db_checked();
+    let mut keys: Vec<String> = db
+        .plugin_storage
+        .get(&plugin_id)
+        .map(|entries| entries.keys().cloned().collect())
+        .unwrap_or_default();
+    keys.sort();
+    Ok(keys)
+}
diff --git a/desktop/src-tauri/plugins/src/system.rs b/desktop/src-tauri/plugins/src/system.rs
new file mode 100644
index 000000000..5af2ed492
--- /dev/null
+++ b/desktop/src-tauri/plugins/src/system.rs
@@ -0,0 +1,115 @@
+use std::time::Duration;
+
+use serde::{Deserialize, Serialize};
+use tauri::State;
+use tokio::process::Command as TokioCommand;
+
+use crate::allowlist::{PluginCommandAllowlist, validate_command_name};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CommandOutput {
+    pub code: i32,
+    pub stdout: String,
+    pub stderr: String,
+}
+
+/// Register (replace) the allowlisted commands for a plugin.
+///
+/// # Security
+///
+/// Allowlisting a command means the plugin may execute it unsandboxed with the
+/// user's privileges. Only register commands for plugins you fully trust; see
+/// [`PluginCommandAllowlist`] for the trust model. There is intentionally no
+/// blocklist of dangerous commands, so this allowlist is the only gate.
+#[tauri::command]
+pub fn plugin_register_commands(
+    plugin_id: String,
+    commands: Vec<String>,
+    state: State<'_, PluginCommandAllowlist>,
+) -> Result<(), String> {
+    let mut registry = state
+        .0
+        .lock()
+        .map_err(|_| "plugin command registry poisoned".to_string())?;
+    let entry = registry.entry(plugin_id).or_default();
+    entry.clear();
+    for command in commands {
+        let command = command.trim();
+        if command.is_empty() {
+            continue;
+        }
+        // Only bare executable names are allowed; no paths, so an allowlist
+        // entry cannot be used to traverse to an arbitrary binary.
+        if command.contains('/') || command.contains('\\') {
+            return Err(format!(
+                "allowlisted command must be a bare executable name: {command}"
+            ));
+        }
+        validate_command_name(command)?;
+        entry.insert(command.to_string());
+    }
+    Ok(())
+}
+
+/// Run an allowlisted native command for a plugin.
+///
+/// # Security
+///
+/// The binary is executed directly (no shell), so shell metacharacters are
+/// never interpreted. However, allowlisted commands are **not sandboxed**:
+/// they run with the same privileges as the Drop process and can read or write
+/// anything the user can. This is why a command must be allowlisted per plugin
+/// (fail-closed) and why only trusted plugins should ever be installed. Do not
+/// rely on a blocklist to contain a malicious plugin; there is none by design.
+#[tauri::command]
+pub async fn plugin_system_run(
+    plugin_id: String,
+    bin: String,
+    args: Option<Vec<String>>,
+    cwd: Option<String>,
+    timeout_ms: Option<u64>,
+    state: State<'_, PluginCommandAllowlist>,
+) -> Result<CommandOutput, String> {
+    validate_command_name(&bin)?;
+    {
+        let registry = state
+            .0
+            .lock()
+            .map_err(|_| "plugin command registry poisoned".to_string())?;
+        let allowed = registry
+            .get(&plugin_id)
+            .map(|set| set.contains(&bin))
+            .unwrap_or(false);
+        if !allowed {
+            return Err(format!(
+                "command '{bin}' is not allowlisted for plugin '{plugin_id}'"
+            ));
+        }
+    }
+
+    let mut command = TokioCommand::new(&bin);
+    command
+        .args(args.unwrap_or_default())
+        .stdin(std::process::Stdio::null())
+        .stdout(std::process::Stdio::piped())
+        .stderr(std::process::Stdio::piped())
+        .kill_on_drop(true);
+    if let Some(dir) = cwd {
+        command.current_dir(dir);
+    }
+
+    // Clamp to [1ms, 120s] so a plugin cannot request an unbounded process.
+    let timeout = Duration::from_millis(timeout_ms.unwrap_or(15_000).clamp(1, 120_000));
+    let output = match tokio::time::timeout(timeout, command.output()).await {
+        Ok(Ok(output)) => output,
+        Ok(Err(err)) => return Err(format!("failed to run '{bin}': {err}")),
+        Err(_) => return Err(format!("'{bin}' timed out after {}ms", timeout.as_millis())),
+    };
+
+    Ok(CommandOutput {
+        code: output.status.code().unwrap_or(-1),
+        stdout: String::from_utf8_lossy(&output.stdout).to_string(),
+        stderr: String::from_utf8_lossy(&output.stderr).to_string(),
+    })
+}
diff --git a/desktop/src-tauri/process/Cargo.toml b/desktop/src-tauri/process/Cargo.toml
index d00589bc1..c83b6ba01 100644
--- a/desktop/src-tauri/process/Cargo.toml
+++ b/desktop/src-tauri/process/Cargo.toml
@@ -19,6 +19,3 @@ shell-words = "1.1.1"
 tauri = "*"
 tauri-plugin-opener = "*"
 utils = { path = "../utils", version = "0.1.0" }
-
-[dev-dependencies]
-tempfile = "3"
diff --git a/desktop/src-tauri/process/src/lib.rs b/desktop/src-tauri/process/src/lib.rs
index 66990f103..05dfc4360 100644
--- a/desktop/src-tauri/process/src/lib.rs
+++ b/desktop/src-tauri/process/src/lib.rs
@@ -19,7 +19,6 @@ pub mod compat;
 pub mod error;
 pub mod format;
 mod parser;
-pub mod path_guard;
 pub mod process_handlers;
 pub mod process_manager;
 
diff --git a/desktop/src-tauri/src/lib.rs b/desktop/src-tauri/src/lib.rs
index e4d50da7a..acbb582b4 100644
--- a/desktop/src-tauri/src/lib.rs
+++ b/desktop/src-tauri/src/lib.rs
@@ -64,7 +64,6 @@ mod collections;
 mod download_manager;
 mod downloads;
 mod games;
-mod plugins;
 mod process;
 mod remote;
 mod scheduler;
@@ -262,6 +261,10 @@ pub fn run() {
             plugin_game_find_files,
             plugin_register_commands,
             plugin_system_run,
+            plugin_storage_get,
+            plugin_storage_set,
+            plugin_storage_delete,
+            plugin_storage_list_keys,
             // Library
             fetch_library,
             fetch_game,
diff --git a/desktop/src-tauri/src/plugins.rs b/desktop/src-tauri/src/plugins.rs
deleted file mode 100644
index e992fa32f..000000000
--- a/desktop/src-tauri/src/plugins.rs
+++ /dev/null
@@ -1,451 +0,0 @@
-use std::collections::{HashMap, HashSet};
-use std::fs::{self, File};
-use std::io::{self, Read};
-use std::path::{Path, PathBuf};
-use std::sync::Mutex;
-use std::time::Duration;
-
-use database::borrow_db_checked;
-use process::path_guard;
-use serde::{Deserialize, Serialize};
-use sha2::{Digest, Sha256};
-use tauri::State;
-use tokio::process::Command as TokioCommand;
-use walkdir::WalkDir;
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct ScannedExecutable {
-    pub relative_path: String,
-    pub sha256: String,
-    pub size: u64,
-}
-
-/// Per-plugin allowlist of bare executable names a client plugin may run via
-/// `ctx.system.run`. Populated from `manifest.client.commands` by the host when
-/// a plugin is registered; the Tauri command layer is the enforcement point so
-/// a plugin cannot bypass it from the webview.
-#[derive(Default)]
-pub struct PluginCommandAllowlist(pub Mutex<HashMap<String, HashSet<String>>>);
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase")]
-pub struct CommandOutput {
-    pub code: i32,
-    pub stdout: String,
-    pub stderr: String,
-}
-
-const BLOCKED_COMMANDS: &[&str] = &[
-    // Shells
-    "sh",
-    "bash",
-    "dash",
-    "ash",
-    "zsh",
-    "csh",
-    "tcsh",
-    "fish",
-    "ksh",
-    "cmd",
-    "cmd.exe",
-    "powershell",
-    "powershell.exe",
-    "pwsh",
-    "pwsh.exe",
-    "wscript",
-    "wscript.exe",
-    "cscript",
-    "cscript.exe",
-    // Interpreters & runtimes
-    "python",
-    "python3",
-    "python.exe",
-    "python3.exe",
-    "py",
-    "py.exe",
-    "node",
-    "node.exe",
-    "deno",
-    "deno.exe",
-    "bun",
-    "bun.exe",
-    "perl",
-    "perl.exe",
-    "ruby",
-    "ruby.exe",
-    "php",
-    "php.exe",
-    "lua",
-    "lua.exe",
-    // Network transfer / remote shells
-    "curl",
-    "curl.exe",
-    "wget",
-    "wget.exe",
-    "nc",
-    "ncat",
-    "netcat",
-    "socat",
-    "telnet",
-    "ssh",
-    "scp",
-    "sftp",
-    "ftp",
-    // Privilege escalation / execution
-    "sudo",
-    "su",
-    "doas",
-    "pkexec",
-    "runas",
-    "runas.exe",
-    // Destructive filesystem / partition / system tools
-    "rm",
-    "rmdir",
-    "del",
-    "erase",
-    "dd",
-    "format",
-    "mkfs",
-    "fdisk",
-    "parted",
-    "reg",
-    "reg.exe",
-    "regedit",
-    "regedit.exe",
-    "certutil",
-    "certutil.exe",
-    "bitsadmin",
-    "bitsadmin.exe",
-    "mshta",
-    "mshta.exe",
-    "rundll32",
-    "rundll32.exe",
-];
-
-fn validate_command_name(command: &str) -> Result<(), String> {
-    if command.is_empty() || command.len() > 64 {
-        return Err(format!("invalid command length: '{command}'"));
-    }
-    if command.starts_with('.') || command.starts_with('-') {
-        return Err(format!("command cannot start with '.' or '-': '{command}'"));
-    }
-    if !command
-        .chars()
-        .all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-' || c == '.')
-    {
-        return Err(format!(
-            "command contains disallowed characters (only alphanumeric, _, -, . allowed): '{command}'"
-        ));
-    }
-    let lower = command.to_ascii_lowercase();
-    if BLOCKED_COMMANDS.contains(&lower.as_str()) {
-        return Err(format!(
-            "command '{command}' is blocked for security reasons"
-        ));
-    }
-    Ok(())
-}
-
-/// Register (replace) the allowlisted commands for a plugin.
-#[tauri::command]
-pub fn plugin_register_commands(
-    plugin_id: String,
-    commands: Vec<String>,
-    state: State<'_, PluginCommandAllowlist>,
-) -> Result<(), String> {
-    let mut registry = state
-        .0
-        .lock()
-        .map_err(|_| "plugin command registry poisoned".to_string())?;
-    let entry = registry.entry(plugin_id).or_default();
-    entry.clear();
-    for command in commands {
-        let command = command.trim();
-        if command.is_empty() {
-            continue;
-        }
-        // Only bare executable names are allowed; no paths, so an allowlist
-        // entry cannot be used to traverse to an arbitrary binary.
-        if command.contains('/') || command.contains('\\') {
-            return Err(format!(
-                "allowlisted command must be a bare executable name: {command}"
-            ));
-        }
-        validate_command_name(command)?;
-        entry.insert(command.to_string());
-    }
-    Ok(())
-}
-
-/// Run an allowlisted native command for a plugin. The binary is executed
-/// directly (no shell), so shell metacharacters are never interpreted.
-#[tauri::command]
-pub async fn plugin_system_run(
-    plugin_id: String,
-    bin: String,
-    args: Option<Vec<String>>,
-    cwd: Option<String>,
-    timeout_ms: Option<u64>,
-    state: State<'_, PluginCommandAllowlist>,
-) -> Result<CommandOutput, String> {
-    validate_command_name(&bin)?;
-    {
-        let registry = state
-            .0
-            .lock()
-            .map_err(|_| "plugin command registry poisoned".to_string())?;
-        let allowed = registry
-            .get(&plugin_id)
-            .map(|set| set.contains(&bin))
-            .unwrap_or(false);
-        if !allowed {
-            return Err(format!(
-                "command '{bin}' is not allowlisted for plugin '{plugin_id}'"
-            ));
-        }
-    }
-
-    let mut command = TokioCommand::new(&bin);
-    command
-        .args(args.unwrap_or_default())
-        .stdin(std::process::Stdio::null())
-        .stdout(std::process::Stdio::piped())
-        .stderr(std::process::Stdio::piped())
-        .kill_on_drop(true);
-    if let Some(dir) = cwd {
-        command.current_dir(dir);
-    }
-
-    // Clamp to [1ms, 120s] so a plugin cannot request an unbounded process.
-    let timeout = Duration::from_millis(timeout_ms.unwrap_or(15_000).clamp(1, 120_000));
-    let output = match tokio::time::timeout(timeout, command.output()).await {
-        Ok(Ok(output)) => output,
-        Ok(Err(err)) => return Err(format!("failed to run '{bin}': {err}")),
-        Err(_) => return Err(format!("'{bin}' timed out after {}ms", timeout.as_millis())),
-    };
-
-    Ok(CommandOutput {
-        code: output.status.code().unwrap_or(-1),
-        stdout: String::from_utf8_lossy(&output.stdout).to_string(),
-        stderr: String::from_utf8_lossy(&output.stderr).to_string(),
-    })
-}
-
-fn get_game_install_dir(game_id: &str) -> Result<PathBuf, String> {
-    let db = borrow_db_checked();
-    if let Some(database::GameDownloadStatus::Installed { install_dir, .. }) =
-        db.applications.game_statuses.get(game_id)
-    {
-        let path = PathBuf::from(install_dir);
-        if path.exists() {
-            return Ok(path);
-        }
-        return Err(format!(
-            "Game install directory does not exist: {}",
-            path.display()
-        ));
-    }
-    Err(format!(
-        "Game with id '{game_id}' is not installed or not found in local database"
-    ))
-}
-
-fn compute_file_sha256(path: &Path) -> io::Result<String> {
-    let mut file = File::open(path)?;
-    let mut hasher = Sha256::new();
-    let mut buffer = [0u8; 64 * 1024];
-
-    loop {
-        let bytes_read = file.read(&mut buffer)?;
-        if bytes_read == 0 {
-            break;
-        }
-        hasher.update(&buffer[..bytes_read]);
-    }
-
-    Ok(format!("{:x}", hasher.finalize()))
-}
-
-#[tauri::command]
-pub async fn plugin_game_fs_read(
-    game_id: String,
-    relative_path: String,
-) -> Result<Vec<u8>, String> {
-    let install_dir = get_game_install_dir(&game_id)?;
-    let safe_path = path_guard::safe_join(&install_dir, &relative_path)
-        .map_err(|e| format!("Security check failed: {e}"))?;
-
-    fs::read(&safe_path).map_err(|e| format!("Failed to read {relative_path}: {e}"))
-}
-
-#[tauri::command]
-pub async fn plugin_game_fs_write(
-    game_id: String,
-    relative_path: String,
-    data: Vec<u8>,
-) -> Result<(), String> {
-    let install_dir = get_game_install_dir(&game_id)?;
-    path_guard::write_file(&install_dir, &relative_path, &data)
-        .map_err(|e| format!("Failed to write {relative_path}: {e}"))
-}
-
-#[tauri::command]
-pub async fn plugin_game_fs_backup(
-    game_id: String,
-    relative_path: String,
-) -> Result<String, String> {
-    let install_dir = get_game_install_dir(&game_id)?;
-    let src_path = path_guard::safe_join(&install_dir, &relative_path)
-        .map_err(|e| format!("Security check failed: {e}"))?;
-
-    if !src_path.exists() {
-        return Err(format!(
-            "Cannot backup nonexistent file: {}",
-            src_path.display()
-        ));
-    }
-
-    let backup_relative = format!("{}.drop-backup", relative_path);
-    path_guard::copy_to(&install_dir, &src_path, &backup_relative)
-        .map_err(|e| format!("Failed to create backup {backup_relative}: {e}"))?;
-
-    Ok(backup_relative)
-}
-
-#[tauri::command]
-pub async fn plugin_game_fs_restore(game_id: String, relative_path: String) -> Result<(), String> {
-    let install_dir = get_game_install_dir(&game_id)?;
-    let backup_relative = format!("{}.drop-backup", relative_path);
-    let backup_path = path_guard::safe_join(&install_dir, &backup_relative)
-        .map_err(|e| format!("Security check failed: {e}"))?;
-
-    if !backup_path.exists() {
-        return Err(format!(
-            "Cannot restore missing backup file: {backup_relative}"
-        ));
-    }
-
-    path_guard::copy_to(&install_dir, &backup_path, &relative_path)
-        .map_err(|e| format!("Failed to restore file from backup: {e}"))?;
-
-    // Cleanup backup file
-    let _ = path_guard::remove_file(&install_dir, &backup_relative);
-
-    Ok(())
-}
-
-#[tauri::command]
-pub async fn plugin_game_fs_exists(game_id: String, relative_path: String) -> Result<bool, String> {
-    let install_dir = get_game_install_dir(&game_id)?;
-    match path_guard::safe_join(&install_dir, &relative_path) {
-        Ok(safe_path) => Ok(safe_path.exists()),
-        Err(_) => Ok(false),
-    }
-}
-
-#[tauri::command]
-pub async fn plugin_game_fs_delete(game_id: String, relative_path: String) -> Result<(), String> {
-    let install_dir = get_game_install_dir(&game_id)?;
-    path_guard::remove_file(&install_dir, &relative_path)
-        .map_err(|e| format!("Failed to delete {relative_path}: {e}"))
-}
-
-#[tauri::command]
-pub async fn plugin_game_scan_executables(
-    game_id: String,
-) -> Result<Vec<ScannedExecutable>, String> {
-    let install_dir = get_game_install_dir(&game_id)?;
-    let mut executables = Vec::new();
-
-    for entry in WalkDir::new(&install_dir)
-        .into_iter()
-        .filter_map(|e| e.ok())
-    {
-        let path = entry.path();
-        if !path.is_file() {
-            continue;
-        }
-
-        // Never follow or scan symlinks for executable security
-        if path_guard::is_symlink(path) {
-            continue;
-        }
-
-        let is_exec = if let Some(ext) = path.extension().and_then(|s| s.to_str()) {
-            let lower = ext.to_lowercase();
-            matches!(
-                lower.as_str(),
-                "exe" | "dll" | "so" | "bin" | "x86_64" | "elf" | "dylib"
-            )
-        } else {
-            false
-        };
-
-        #[cfg(unix)]
-        let is_exec = is_exec || {
-            use std::os::unix::fs::PermissionsExt;
-            entry
-                .metadata()
-                .map(|m| (m.permissions().mode() & 0o111) != 0)
-                .unwrap_or(false)
-        };
-
-        if is_exec && let Ok(rel_path) = path.strip_prefix(&install_dir) {
-            let size = entry.metadata().map(|m| m.len()).unwrap_or(0);
-            let sha256 =
-                compute_file_sha256(path).unwrap_or_else(|_| String::from("unknown-sha256"));
-
-            executables.push(ScannedExecutable {
-                relative_path: rel_path.to_string_lossy().to_string(),
-                sha256,
-                size,
-            });
-        }
-    }
-
-    Ok(executables)
-}
-
-/// Find files inside an installed game whose relative path contains any of the
-/// supplied patterns (case-insensitive substring). The host is deliberately
-/// agnostic about what the patterns mean, so domain knowledge (e.g. which paths
-/// indicate a particular anti-cheat or compatibility tool) lives in the calling
-/// plugin, not in core. Symlinks are never followed.
-#[tauri::command]
-pub async fn plugin_game_find_files(
-    game_id: String,
-    patterns: Vec<String>,
-) -> Result<Vec<String>, String> {
-    let install_dir = get_game_install_dir(&game_id)?;
-
-    let normalized: Vec<String> = patterns
-        .into_iter()
-        .map(|pattern| pattern.trim().to_ascii_lowercase())
-        .filter(|pattern| !pattern.is_empty() && pattern.len() <= 128)
-        .collect();
-    if normalized.is_empty() {
-        return Ok(Vec::new());
-    }
-
-    let mut matches = Vec::new();
-    for entry in WalkDir::new(&install_dir)
-        .into_iter()
-        .filter_map(|e| e.ok())
-    {
-        let path = entry.path();
-        if !path.is_file() || path_guard::is_symlink(path) {
-            continue;
-        }
-
-        let Ok(rel) = path.strip_prefix(&install_dir) else {
-            continue;
-        };
-        let rel_str = rel.to_string_lossy().to_ascii_lowercase();
-        if normalized.iter().any(|pattern| rel_str.contains(pattern)) {
-            matches.push(rel.to_string_lossy().to_string());
-        }
-    }
-
-    Ok(matches)
-}

From f443d08e1244f92546bedaf79466dc1fb73ce604 Mon Sep 17 00:00:00 2001
From: John Smith <you@example.com>
Date: Mon, 14 Sep 2026 23:29:24 -0400
Subject: [PATCH 08/13] refactor(plugins): share contracts via @drop/plugin-api
 and split client host

- add a type-only workspace package holding the manifest, capability, and
  client plugin contracts so the server and desktop cannot drift
- server plugin types keep only the h3/pino runtime contract and the API
  version constants, re-exporting the shared contracts
- split the desktop ClientPluginManager into host adapters (storage,
  game fs, scanner, websocket, system) and a launch pipeline module
---
 .../internal/plugins/ClientPluginManager.ts   | 335 +-----------------
 desktop/main/internal/plugins/host.ts         |  30 ++
 desktop/main/internal/plugins/host/game-fs.ts |  62 ++++
 .../internal/plugins/host/game-scanner.ts     |  24 ++
 desktop/main/internal/plugins/host/storage.ts |  59 +++
 desktop/main/internal/plugins/host/system.ts  |  32 ++
 .../main/internal/plugins/host/websocket.ts   |  61 ++++
 .../main/internal/plugins/launch-pipeline.ts  |  97 +++++
 desktop/main/internal/plugins/types.ts        | 302 +---------------
 desktop/main/package.json                     |   1 +
 desktop/main/pnpm-lock.yaml                   |   8 +
 desktop/main/pnpm-workspace.yaml              |   4 +
 libraries/plugin-api/package.json             |  12 +
 libraries/plugin-api/src/client.ts            | 274 ++++++++++++++
 libraries/plugin-api/src/common.ts            | 166 +++++++++
 libraries/plugin-api/src/index.ts             |   2 +
 pnpm-lock.yaml                                |   5 +
 pnpm-workspace.yaml                           |   1 +
 server/package.json                           |   1 +
 server/server/internal/plugins/types.ts       | 242 +------------
 20 files changed, 863 insertions(+), 855 deletions(-)
 create mode 100644 desktop/main/internal/plugins/host.ts
 create mode 100644 desktop/main/internal/plugins/host/game-fs.ts
 create mode 100644 desktop/main/internal/plugins/host/game-scanner.ts
 create mode 100644 desktop/main/internal/plugins/host/storage.ts
 create mode 100644 desktop/main/internal/plugins/host/system.ts
 create mode 100644 desktop/main/internal/plugins/host/websocket.ts
 create mode 100644 desktop/main/internal/plugins/launch-pipeline.ts
 create mode 100644 libraries/plugin-api/package.json
 create mode 100644 libraries/plugin-api/src/client.ts
 create mode 100644 libraries/plugin-api/src/common.ts
 create mode 100644 libraries/plugin-api/src/index.ts

diff --git a/desktop/main/internal/plugins/ClientPluginManager.ts b/desktop/main/internal/plugins/ClientPluginManager.ts
index f1ecc54f5..5fb6ce0e3 100644
--- a/desktop/main/internal/plugins/ClientPluginManager.ts
+++ b/desktop/main/internal/plugins/ClientPluginManager.ts
@@ -1,245 +1,30 @@
 import { reactive, ref } from "vue";
-import { invoke } from "@tauri-apps/api/core";
-import { listen } from "@tauri-apps/api/event";
 import type {
   ClientPlugin,
   ClientPluginContext,
-  ClientPluginStorage,
   ClientPluginWebSocket,
   CloudSavePathResolver,
-  CommandResult,
   GameMenuItem,
   HttpMethod,
   LaunchContext,
   LaunchHook,
   MetadataProvider,
   PlayAction,
-  ScopedGameFs,
-  ScopedGameScanner,
   SidebarItem,
   StoreScanner,
   TopBarItem,
   UISlotName,
   UISlotRegistration,
 } from "./types";
+import { safeInvoke } from "./host";
+import { TauriPluginStorage } from "./host/storage";
+import { TauriScopedGameFs } from "./host/game-fs";
+import { TauriScopedGameScanner } from "./host/game-scanner";
+import { TauriPluginWebSocket } from "./host/websocket";
+import { createPluginSystem } from "./host/system";
+import { executeLaunchPipeline as runLaunchPipeline } from "./launch-pipeline";
 
-export function isTauri(): boolean {
-  return (
-    typeof window !== "undefined" &&
-    ("__TAURI_INTERNALS__" in window || "__TAURI__" in window)
-  );
-}
-
-async function safeInvoke<T>(
-  cmd: string,
-  args?: Record<string, unknown>,
-  fallback?: T,
-): Promise<T> {
-  if (!isTauri()) {
-    console.debug(
-      `[ClientPluginManager] Browser mode: invoke('${cmd}') bypassed`,
-    );
-    return fallback !== undefined ? fallback : (null as unknown as T);
-  }
-  return await invoke<T>(cmd, args);
-}
-
-class TauriPluginStorage implements ClientPluginStorage {
-  // Browser/dev fallback. Plugin state lives in the Rust-side database when
-  // Tauri is available so frontend and backend never split their state.
-  private readonly memory = new Map<string, unknown>();
-
-  constructor(private readonly pluginId: string) {}
-
-  async get<T>(key: string): Promise<T | null> {
-    if (!isTauri()) {
-      return this.memory.has(key) ? (this.memory.get(key) as T) : null;
-    }
-    return (
-      (await safeInvoke<T | null>(
-        "plugin_storage_get",
-        { pluginId: this.pluginId, key },
-        null,
-      )) ?? null
-    );
-  }
-
-  async set<T>(key: string, value: T): Promise<void> {
-    if (!isTauri()) {
-      this.memory.set(key, value);
-      return;
-    }
-    await safeInvoke("plugin_storage_set", {
-      pluginId: this.pluginId,
-      key,
-      value,
-    });
-  }
-
-  async delete(key: string): Promise<void> {
-    if (!isTauri()) {
-      this.memory.delete(key);
-      return;
-    }
-    await safeInvoke("plugin_storage_delete", {
-      pluginId: this.pluginId,
-      key,
-    });
-  }
-
-  async listKeys(): Promise<string[]> {
-    if (!isTauri()) {
-      return Array.from(this.memory.keys());
-    }
-    return (
-      (await safeInvoke<string[]>(
-        "plugin_storage_list_keys",
-        { pluginId: this.pluginId },
-        [],
-      )) || []
-    );
-  }
-}
-
-class TauriScopedGameFs implements ScopedGameFs {
-  async readFile(gameId: string, relativePath: string): Promise<Uint8Array> {
-    const res = await safeInvoke<number[]>(
-      "plugin_game_fs_read",
-      { gameId, relativePath },
-      [],
-    );
-    return new Uint8Array(res);
-  }
-
-  async writeFile(
-    gameId: string,
-    relativePath: string,
-    data: Uint8Array | string,
-  ): Promise<void> {
-    const bytes =
-      typeof data === "string"
-        ? Array.from(new TextEncoder().encode(data))
-        : Array.from(data);
-    await safeInvoke("plugin_game_fs_write", {
-      gameId,
-      relativePath,
-      data: bytes,
-    });
-  }
-
-  async backupFile(gameId: string, relativePath: string): Promise<string> {
-    return (
-      (await safeInvoke<string>("plugin_game_fs_backup", {
-        gameId,
-        relativePath,
-      })) || ""
-    );
-  }
-
-  async restoreFile(gameId: string, relativePath: string): Promise<void> {
-    await safeInvoke("plugin_game_fs_restore", {
-      gameId,
-      relativePath,
-    });
-  }
-
-  async fileExists(gameId: string, relativePath: string): Promise<boolean> {
-    return (
-      (await safeInvoke<boolean>(
-        "plugin_game_fs_exists",
-        { gameId, relativePath },
-        false,
-      )) ?? false
-    );
-  }
-
-  async deleteFile(gameId: string, relativePath: string): Promise<void> {
-    await safeInvoke("plugin_game_fs_delete", {
-      gameId,
-      relativePath,
-    });
-  }
-}
-
-class TauriScopedGameScanner implements ScopedGameScanner {
-  async scanExecutables(
-    gameId: string,
-  ): Promise<Array<{ relativePath: string; sha256: string; size: number }>> {
-    return (
-      (await safeInvoke<
-        Array<{ relativePath: string; sha256: string; size: number }>
-      >("plugin_game_scan_executables", { gameId }, [])) || []
-    );
-  }
-
-  async findFiles(gameId: string, patterns: string[]): Promise<string[]> {
-    return (
-      (await safeInvoke<string[]>(
-        "plugin_game_find_files",
-        { gameId, patterns },
-        [],
-      )) || []
-    );
-  }
-}
-
-class TauriPluginWebSocket implements ClientPluginWebSocket {
-  async send(channel: string, data: unknown): Promise<unknown> {
-    return await safeInvoke("plugin_request_ws", { channel, data });
-  }
-
-  subscribe(channel: string, listener: (data: unknown) => void): () => void {
-    if (isTauri()) {
-      let disposed = false;
-      let unlisten: (() => void) | undefined;
-
-      safeInvoke("plugin_subscribe", { channel }).catch((err) => {
-        console.error(`Failed to subscribe to plugin channel ${channel}:`, err);
-      });
-
-      // The Rust host forwards decoded WebSocket frames as the Tauri event
-      // `plugin:event`. Tauri events are not DOM events, so the payload must be
-      // consumed with `listen` rather than `window.addEventListener`.
-      void listen<{ channel?: string; data?: unknown }>(
-        "plugin:event",
-        (event) => {
-          if (event.payload?.channel === channel) {
-            listener(event.payload.data);
-          }
-        },
-      )
-        .then((off) => {
-          if (disposed) off();
-          else unlisten = off;
-        })
-        .catch((err) => {
-          console.error(
-            `Failed to listen for plugin events on ${channel}:`,
-            err,
-          );
-        });
-
-      return () => {
-        disposed = true;
-        unlisten?.();
-        unlisten = undefined;
-      };
-    }
-
-    // Browser/dev fallback: a host harness can dispatch a DOM CustomEvent.
-    const handler = (event: Event) => {
-      const custom = event as CustomEvent<{ channel?: string; data?: unknown }>;
-      if (custom?.detail?.channel === channel) {
-        listener(custom.detail.data);
-      }
-    };
-
-    window.addEventListener("plugin:event", handler);
-    return () => {
-      window.removeEventListener("plugin:event", handler);
-    };
-  }
-}
+export { isTauri, safeInvoke } from "./host";
 
 export class ClientPluginManager {
   private readonly plugins = new Map<string, ClientPlugin>();
@@ -432,28 +217,7 @@ export class ClientPluginManager {
       gameFs: new TauriScopedGameFs(),
       gameScanner: new TauriScopedGameScanner(),
       serverWs: this.serverWs,
-      system: {
-        run: (
-          bin: string,
-          args?: string[],
-          options?: { cwd?: string; timeoutMs?: number },
-        ) =>
-          safeInvoke<CommandResult>(
-            "plugin_system_run",
-            {
-              pluginId,
-              bin,
-              args,
-              cwd: options?.cwd,
-              timeoutMs: options?.timeoutMs,
-            },
-            {
-              code: 1,
-              stdout: "",
-              stderr: "Host native execution not available in browser mode",
-            },
-          ),
-      },
+      system: createPluginSystem(pluginId),
       serverRequest: <T>(method: HttpMethod, path = "", body?: unknown) =>
         safeInvoke<T>("plugin_request", {
           pluginId,
@@ -584,68 +348,6 @@ export class ClientPluginManager {
     return actions;
   }
 
-  /**
-   * Playnite-style Game Launch Pipeline Coordinator.
-   * Executes pre-launch hooks sorted by stage and priority.
-   * If any pre-launch hook aborts, completed stages are rolled back in reverse order.
-   * If launch succeeds, executes post-exit cleanup hooks.
-   */
-  private sortHooks(stages: LaunchHook["stage"][]): LaunchHook[] {
-    return this.launchHooks
-      .filter((h) => stages.includes(h.stage))
-      .sort((a, b) => {
-        const stageDiff = stages.indexOf(a.stage) - stages.indexOf(b.stage);
-        if (stageDiff !== 0) return stageDiff;
-        return (a.order ?? 0) - (b.order ?? 0);
-      });
-  }
-
-  private rollbackCompletedStages(completedHooks: LaunchHook[]): void {
-    for (let i = completedHooks.length - 1; i >= 0; i--) {
-      const rollbackHook = completedHooks[i];
-      if (!rollbackHook) continue;
-      console.log(`Rolling back stage: ${rollbackHook.stage}`);
-    }
-  }
-
-  private async runPreLaunchPipeline(
-    activePreHooks: LaunchHook[],
-    context: LaunchContext,
-  ): Promise<void> {
-    const completedHooks: LaunchHook[] = [];
-    for (const hook of activePreHooks) {
-      try {
-        await hook.execute(context);
-        completedHooks.push(hook);
-      } catch (error) {
-        console.error(
-          `Pre-launch hook [${hook.stage}] failed. Rolling back completed stages...`,
-          error,
-        );
-        this.rollbackCompletedStages(completedHooks);
-        throw new Error(
-          `Launch aborted during stage '${hook.stage}': ${
-            error instanceof Error ? error.message : String(error)
-          }`,
-          { cause: error },
-        );
-      }
-    }
-  }
-
-  private async runPostExitPipeline(
-    activePostHooks: LaunchHook[],
-    context: LaunchContext,
-  ): Promise<void> {
-    for (const hook of activePostHooks) {
-      try {
-        await hook.execute(context);
-      } catch (postErr) {
-        console.warn(`Post-exit hook [${hook.stage}] warning:`, postErr);
-      }
-    }
-  }
-
   /**
    * Playnite-style Game Launch Pipeline Coordinator.
    * Executes pre-launch hooks sorted by stage and priority.
@@ -656,24 +358,7 @@ export class ClientPluginManager {
     context: LaunchContext,
     launchFn: () => Promise<T>,
   ): Promise<T> {
-    const preLaunchStages: LaunchHook["stage"][] = [
-      "pre-launch:validate",
-      "pre-launch:prepare",
-      "pre-launch:stage",
-      "pre-launch:network",
-    ];
-
-    const postExitStages: LaunchHook["stage"][] = [
-      "post-exit:cleanup",
-      "post-exit:restore",
-      "post-exit:sync",
-    ];
-
-    await this.runPreLaunchPipeline(this.sortHooks(preLaunchStages), context);
-    const launchResult = await launchFn();
-    await this.runPostExitPipeline(this.sortHooks(postExitStages), context);
-
-    return launchResult;
+    return runLaunchPipeline(this.launchHooks, context, launchFn);
   }
 }
 
diff --git a/desktop/main/internal/plugins/host.ts b/desktop/main/internal/plugins/host.ts
new file mode 100644
index 000000000..4f33abd41
--- /dev/null
+++ b/desktop/main/internal/plugins/host.ts
@@ -0,0 +1,30 @@
+import { invoke } from "@tauri-apps/api/core";
+
+/**
+ * Whether the client is running inside a Tauri webview. Browser/dev builds
+ * fall back to in-memory implementations so the UI can still boot.
+ */
+export function isTauri(): boolean {
+  return (
+    typeof window !== "undefined" &&
+    ("__TAURI_INTERNALS__" in window || "__TAURI__" in window)
+  );
+}
+
+/**
+ * Invoke a Tauri command, returning `fallback` (or `null`) in browser mode
+ * instead of throwing so plugin code degrades gracefully outside the desktop.
+ */
+export async function safeInvoke<T>(
+  cmd: string,
+  args?: Record<string, unknown>,
+  fallback?: T,
+): Promise<T> {
+  if (!isTauri()) {
+    console.debug(
+      `[ClientPluginManager] Browser mode: invoke('${cmd}') bypassed`,
+    );
+    return fallback !== undefined ? fallback : (null as unknown as T);
+  }
+  return await invoke<T>(cmd, args);
+}
diff --git a/desktop/main/internal/plugins/host/game-fs.ts b/desktop/main/internal/plugins/host/game-fs.ts
new file mode 100644
index 000000000..1ac645d67
--- /dev/null
+++ b/desktop/main/internal/plugins/host/game-fs.ts
@@ -0,0 +1,62 @@
+import type { ScopedGameFs } from "../types";
+import { safeInvoke } from "../host";
+
+export class TauriScopedGameFs implements ScopedGameFs {
+  async readFile(gameId: string, relativePath: string): Promise<Uint8Array> {
+    const res = await safeInvoke<number[]>(
+      "plugin_game_fs_read",
+      { gameId, relativePath },
+      [],
+    );
+    return new Uint8Array(res);
+  }
+
+  async writeFile(
+    gameId: string,
+    relativePath: string,
+    data: Uint8Array | string,
+  ): Promise<void> {
+    const bytes =
+      typeof data === "string"
+        ? Array.from(new TextEncoder().encode(data))
+        : Array.from(data);
+    await safeInvoke("plugin_game_fs_write", {
+      gameId,
+      relativePath,
+      data: bytes,
+    });
+  }
+
+  async backupFile(gameId: string, relativePath: string): Promise<string> {
+    return (
+      (await safeInvoke<string>("plugin_game_fs_backup", {
+        gameId,
+        relativePath,
+      })) || ""
+    );
+  }
+
+  async restoreFile(gameId: string, relativePath: string): Promise<void> {
+    await safeInvoke("plugin_game_fs_restore", {
+      gameId,
+      relativePath,
+    });
+  }
+
+  async fileExists(gameId: string, relativePath: string): Promise<boolean> {
+    return (
+      (await safeInvoke<boolean>(
+        "plugin_game_fs_exists",
+        { gameId, relativePath },
+        false,
+      )) ?? false
+    );
+  }
+
+  async deleteFile(gameId: string, relativePath: string): Promise<void> {
+    await safeInvoke("plugin_game_fs_delete", {
+      gameId,
+      relativePath,
+    });
+  }
+}
diff --git a/desktop/main/internal/plugins/host/game-scanner.ts b/desktop/main/internal/plugins/host/game-scanner.ts
new file mode 100644
index 000000000..02dd09281
--- /dev/null
+++ b/desktop/main/internal/plugins/host/game-scanner.ts
@@ -0,0 +1,24 @@
+import type { ScopedGameScanner } from "../types";
+import { safeInvoke } from "../host";
+
+export class TauriScopedGameScanner implements ScopedGameScanner {
+  async scanExecutables(
+    gameId: string,
+  ): Promise<Array<{ relativePath: string; sha256: string; size: number }>> {
+    return (
+      (await safeInvoke<
+        Array<{ relativePath: string; sha256: string; size: number }>
+      >("plugin_game_scan_executables", { gameId }, [])) || []
+    );
+  }
+
+  async findFiles(gameId: string, patterns: string[]): Promise<string[]> {
+    return (
+      (await safeInvoke<string[]>(
+        "plugin_game_find_files",
+        { gameId, patterns },
+        [],
+      )) || []
+    );
+  }
+}
diff --git a/desktop/main/internal/plugins/host/storage.ts b/desktop/main/internal/plugins/host/storage.ts
new file mode 100644
index 000000000..539ed4119
--- /dev/null
+++ b/desktop/main/internal/plugins/host/storage.ts
@@ -0,0 +1,59 @@
+import type { ClientPluginStorage } from "../types";
+import { isTauri, safeInvoke } from "../host";
+
+export class TauriPluginStorage implements ClientPluginStorage {
+  // Browser/dev fallback. Plugin state lives in the Rust-side database when
+  // Tauri is available so frontend and backend never split their state.
+  private readonly memory = new Map<string, unknown>();
+
+  constructor(private readonly pluginId: string) {}
+
+  async get<T>(key: string): Promise<T | null> {
+    if (!isTauri()) {
+      return this.memory.has(key) ? (this.memory.get(key) as T) : null;
+    }
+    return (
+      (await safeInvoke<T | null>(
+        "plugin_storage_get",
+        { pluginId: this.pluginId, key },
+        null,
+      )) ?? null
+    );
+  }
+
+  async set<T>(key: string, value: T): Promise<void> {
+    if (!isTauri()) {
+      this.memory.set(key, value);
+      return;
+    }
+    await safeInvoke("plugin_storage_set", {
+      pluginId: this.pluginId,
+      key,
+      value,
+    });
+  }
+
+  async delete(key: string): Promise<void> {
+    if (!isTauri()) {
+      this.memory.delete(key);
+      return;
+    }
+    await safeInvoke("plugin_storage_delete", {
+      pluginId: this.pluginId,
+      key,
+    });
+  }
+
+  async listKeys(): Promise<string[]> {
+    if (!isTauri()) {
+      return Array.from(this.memory.keys());
+    }
+    return (
+      (await safeInvoke<string[]>(
+        "plugin_storage_list_keys",
+        { pluginId: this.pluginId },
+        [],
+      )) || []
+    );
+  }
+}
diff --git a/desktop/main/internal/plugins/host/system.ts b/desktop/main/internal/plugins/host/system.ts
new file mode 100644
index 000000000..303c0b425
--- /dev/null
+++ b/desktop/main/internal/plugins/host/system.ts
@@ -0,0 +1,32 @@
+import type { ClientPluginSystem, CommandResult } from "../types";
+import { safeInvoke } from "../host";
+
+/**
+ * Build the `ctx.system` native-command surface for `pluginId`. The allowlist
+ * is registered separately (`plugin_register_commands`); enforcement lives in
+ * the Tauri command layer, not here, so a plugin cannot bypass it.
+ */
+export function createPluginSystem(pluginId: string): ClientPluginSystem {
+  return {
+    run: (
+      bin: string,
+      args?: string[],
+      options?: { cwd?: string; timeoutMs?: number },
+    ) =>
+      safeInvoke<CommandResult>(
+        "plugin_system_run",
+        {
+          pluginId,
+          bin,
+          args,
+          cwd: options?.cwd,
+          timeoutMs: options?.timeoutMs,
+        },
+        {
+          code: 1,
+          stdout: "",
+          stderr: "Host native execution not available in browser mode",
+        },
+      ),
+  };
+}
diff --git a/desktop/main/internal/plugins/host/websocket.ts b/desktop/main/internal/plugins/host/websocket.ts
new file mode 100644
index 000000000..8b2882b1a
--- /dev/null
+++ b/desktop/main/internal/plugins/host/websocket.ts
@@ -0,0 +1,61 @@
+import { listen } from "@tauri-apps/api/event";
+import type { ClientPluginWebSocket } from "../types";
+import { isTauri, safeInvoke } from "../host";
+
+export class TauriPluginWebSocket implements ClientPluginWebSocket {
+  async send(channel: string, data: unknown): Promise<unknown> {
+    return await safeInvoke("plugin_request_ws", { channel, data });
+  }
+
+  subscribe(channel: string, listener: (data: unknown) => void): () => void {
+    if (isTauri()) {
+      let disposed = false;
+      let unlisten: (() => void) | undefined;
+
+      safeInvoke("plugin_subscribe", { channel }).catch((err) => {
+        console.error(`Failed to subscribe to plugin channel ${channel}:`, err);
+      });
+
+      // The Rust host forwards decoded WebSocket frames as the Tauri event
+      // `plugin:event`. Tauri events are not DOM events, so the payload must be
+      // consumed with `listen` rather than `window.addEventListener`.
+      void listen<{ channel?: string; data?: unknown }>(
+        "plugin:event",
+        (event) => {
+          if (event.payload?.channel === channel) {
+            listener(event.payload.data);
+          }
+        },
+      )
+        .then((off) => {
+          if (disposed) off();
+          else unlisten = off;
+        })
+        .catch((err) => {
+          console.error(
+            `Failed to listen for plugin events on ${channel}:`,
+            err,
+          );
+        });
+
+      return () => {
+        disposed = true;
+        unlisten?.();
+        unlisten = undefined;
+      };
+    }
+
+    // Browser/dev fallback: a host harness can dispatch a DOM CustomEvent.
+    const handler = (event: Event) => {
+      const custom = event as CustomEvent<{ channel?: string; data?: unknown }>;
+      if (custom?.detail?.channel === channel) {
+        listener(custom.detail.data);
+      }
+    };
+
+    window.addEventListener("plugin:event", handler);
+    return () => {
+      window.removeEventListener("plugin:event", handler);
+    };
+  }
+}
diff --git a/desktop/main/internal/plugins/launch-pipeline.ts b/desktop/main/internal/plugins/launch-pipeline.ts
new file mode 100644
index 000000000..88341edb0
--- /dev/null
+++ b/desktop/main/internal/plugins/launch-pipeline.ts
@@ -0,0 +1,97 @@
+import type { LaunchContext, LaunchHook, LaunchStage } from "./types";
+
+/**
+ * Pure launch-hook helpers backing `ClientPluginManager.executeLaunchPipeline`.
+ * Kept separate from the manager so the pipeline can be unit tested without
+ * constructing a full plugin host.
+ */
+
+export function sortHooks(
+  stages: LaunchStage[],
+  hooks: LaunchHook[],
+): LaunchHook[] {
+  return hooks
+    .filter((h) => stages.includes(h.stage))
+    .sort((a, b) => {
+      const stageDiff = stages.indexOf(a.stage) - stages.indexOf(b.stage);
+      if (stageDiff !== 0) return stageDiff;
+      return (a.order ?? 0) - (b.order ?? 0);
+    });
+}
+
+export function rollbackCompletedStages(completedHooks: LaunchHook[]): void {
+  for (let i = completedHooks.length - 1; i >= 0; i--) {
+    const rollbackHook = completedHooks[i];
+    if (!rollbackHook) continue;
+    console.log(`Rolling back stage: ${rollbackHook.stage}`);
+  }
+}
+
+export async function runPreLaunchPipeline(
+  activePreHooks: LaunchHook[],
+  context: LaunchContext,
+): Promise<void> {
+  const completedHooks: LaunchHook[] = [];
+  for (const hook of activePreHooks) {
+    try {
+      await hook.execute(context);
+      completedHooks.push(hook);
+    } catch (error) {
+      console.error(
+        `Pre-launch hook [${hook.stage}] failed. Rolling back completed stages...`,
+        error,
+      );
+      rollbackCompletedStages(completedHooks);
+      throw new Error(
+        `Launch aborted during stage '${hook.stage}': ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+        { cause: error },
+      );
+    }
+  }
+}
+
+export async function runPostExitPipeline(
+  activePostHooks: LaunchHook[],
+  context: LaunchContext,
+): Promise<void> {
+  for (const hook of activePostHooks) {
+    try {
+      await hook.execute(context);
+    } catch (postErr) {
+      console.warn(`Post-exit hook [${hook.stage}] warning:`, postErr);
+    }
+  }
+}
+
+/**
+ * Playnite-style Game Launch Pipeline Coordinator.
+ * Executes pre-launch hooks sorted by stage and priority.
+ * If any pre-launch hook aborts, completed stages are rolled back in reverse order.
+ * If launch succeeds, executes post-exit cleanup hooks.
+ */
+export async function executeLaunchPipeline<T>(
+  hooks: LaunchHook[],
+  context: LaunchContext,
+  launchFn: () => Promise<T>,
+): Promise<T> {
+  const preLaunchStages: LaunchStage[] = [
+    "pre-launch:validate",
+    "pre-launch:prepare",
+    "pre-launch:stage",
+    "pre-launch:network",
+  ];
+
+  const postExitStages: LaunchStage[] = [
+    "post-exit:cleanup",
+    "post-exit:restore",
+    "post-exit:sync",
+  ];
+
+  await runPreLaunchPipeline(sortHooks(preLaunchStages, hooks), context);
+  const launchResult = await launchFn();
+  await runPostExitPipeline(sortHooks(postExitStages, hooks), context);
+
+  return launchResult;
+}
diff --git a/desktop/main/internal/plugins/types.ts b/desktop/main/internal/plugins/types.ts
index 45eb6a468..964d86c0e 100644
--- a/desktop/main/internal/plugins/types.ts
+++ b/desktop/main/internal/plugins/types.ts
@@ -1,301 +1 @@
-export type UISlotName =
-  | "game-detail:actions"
-  | "game-detail:panels"
-  | "game-detail:badges"
-  | "settings:tabs"
-  | "topbar:status"
-  | "sidebar:nav"
-  | "overlay:panel"
-  | "overlay:quick-access";
-
-export type ClientCapability =
-  | "ui:slot"
-  | "ui:play-action"
-  | "ui:context-menu"
-  | "ui:sidebar"
-  | "ui:topbar"
-  | "game:launch-hook"
-  | "game:fs"
-  | "game:scan"
-  | "client:storage"
-  | "client:ws"
-  | "system:sidecar"
-  | "system:command"
-  | "metadata:provider"
-  | "cloudsave:provider"
-  | "client:library-scan";
-
-export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "ALL";
-
-export interface UISlotRegistration {
-  id: string;
-  pluginId: string;
-  slot: UISlotName;
-  component: unknown;
-  order: number;
-  label?: string;
-  icon?: string;
-}
-
-export interface LaunchContext {
-  gameId: string;
-  gameTitle: string;
-  gameDir: string;
-  actionId?: string;
-  metadata?: Record<string, unknown>;
-}
-
-export type LaunchStage =
-  | "pre-launch:validate"
-  | "pre-launch:prepare"
-  | "pre-launch:stage"
-  | "pre-launch:network"
-  | "launch"
-  | "post-exit:cleanup"
-  | "post-exit:restore"
-  | "post-exit:sync";
-
-export interface LaunchHook {
-  stage: LaunchStage;
-  order?: number;
-  execute: (ctx: LaunchContext) => Promise<void> | void;
-}
-
-export interface PlayAction {
-  id: string;
-  name: string;
-  icon?: string;
-  isDefault?: boolean;
-  execute: (context: LaunchContext) => Promise<void> | void;
-}
-
-export interface GameMenuItem {
-  id: string;
-  label: string;
-  icon?: string;
-  execute: (gameId: string) => Promise<void> | void;
-}
-
-export interface SidebarItem {
-  id: string;
-  title: string;
-  icon?: string;
-  type: "button" | "view";
-  progressValue?: number;
-  activated?: () => void;
-  component?: unknown;
-}
-
-export interface TopBarItem {
-  id: string;
-  title: string;
-  icon?: string;
-  component?: unknown;
-  activated?: () => void;
-}
-
-export interface ScopedGameFs {
-  readFile(gameId: string, relativePath: string): Promise<Uint8Array>;
-  writeFile(
-    gameId: string,
-    relativePath: string,
-    data: Uint8Array | string,
-  ): Promise<void>;
-  backupFile(gameId: string, relativePath: string): Promise<string>;
-  restoreFile(gameId: string, relativePath: string): Promise<void>;
-  fileExists(gameId: string, relativePath: string): Promise<boolean>;
-  deleteFile(gameId: string, relativePath: string): Promise<void>;
-}
-
-export interface ScopedGameScanner {
-  scanExecutables(
-    gameId: string,
-  ): Promise<Array<{ relativePath: string; sha256: string; size: number }>>;
-  /**
-   * Returns the relative paths of installed files whose path contains any of
-   * the supplied patterns (case-insensitive). The host is agnostic about the
-   * patterns, so plugins own domain knowledge such as anti-cheat detection.
-   */
-  findFiles(gameId: string, patterns: string[]): Promise<string[]>;
-}
-
-export interface ClientPluginStorage {
-  get<T>(key: string): Promise<T | null>;
-  set<T>(key: string, value: T): Promise<void>;
-  delete(key: string): Promise<void>;
-  listKeys(): Promise<string[]>;
-}
-
-export interface ClientPluginWebSocket {
-  send(channel: string, data: unknown): Promise<unknown>;
-  subscribe(channel: string, listener: (data: unknown) => void): () => void;
-}
-
-/** Result of a native command run through the client host. */
-export interface CommandResult {
-  code: number;
-  stdout: string;
-  stderr: string;
-}
-
-export interface CommandOptions {
-  cwd?: string;
-  timeoutMs?: number;
-}
-
-/**
- * Native command execution for client plugins. The host runs the binary
- * directly (no shell) and enforces the per-plugin allowlist registered from
- * `manifest.client.commands`.
- */
-export interface ClientPluginSystem {
-  run(
-    bin: string,
-    args?: string[],
-    options?: CommandOptions,
-  ): Promise<CommandResult>;
-}
-
-export interface ClientPluginContext {
-  id: string;
-  logger: {
-    info(msg: string, ...args: unknown[]): void;
-    warn(msg: string, ...args: unknown[]): void;
-    error(msg: string, ...args: unknown[]): void;
-    debug(msg: string, ...args: unknown[]): void;
-  };
-  storage: ClientPluginStorage;
-  registerSlot(
-    slot: UISlotName,
-    component: unknown,
-    options?: { order?: number; label?: string; icon?: string },
-  ): void;
-  registerPlayAction(
-    provider: (gameId: string) => Promise<PlayAction[]> | PlayAction[],
-  ): () => void;
-  registerGameMenuItem(item: GameMenuItem): () => void;
-  registerSidebarItem(item: SidebarItem): () => void;
-  registerTopBarItem(item: TopBarItem): () => void;
-  registerLaunchHook(hook: LaunchHook): () => void;
-  /**
-   * Register a store library scanner SPI implementation.
-   * Requires the `client:library-scan` capability.
-   */
-  registerStoreScanner(scanner: StoreScanner): () => void;
-  /**
-   * Register a client-side metadata provider SPI implementation.
-   * Requires the `metadata:provider` capability.
-   */
-  registerMetadataProvider?(provider: MetadataProvider): () => void;
-  /**
-   * Register a client-side cloud save path resolver SPI implementation.
-   * Requires the `cloudsave:provider` capability.
-   */
-  registerCloudSaveResolver?(resolver: CloudSavePathResolver): () => void;
-  gameFs: ScopedGameFs;
-  gameScanner: ScopedGameScanner;
-  serverWs: ClientPluginWebSocket;
-  /** Native command execution. Requires the `system:command` capability. */
-  system: ClientPluginSystem;
-  /**
-   * Call this plugin's own server-side REST routes through the desktop host.
-   * The webview cannot reach the Drop server directly, so the host proxies the
-   * request. `path` is relative to `/api/v1/plugins/<pluginId>`.
-   */
-  serverRequest<T = unknown>(
-    method: HttpMethod,
-    path?: string,
-    body?: unknown,
-  ): Promise<T>;
-}
-
-export interface ClientPlugin {
-  metadata?: {
-    id: string;
-    name: string;
-    version: string;
-    description?: string;
-    author?: string;
-    category?: string;
-  };
-  init(ctx: ClientPluginContext): Promise<void> | void;
-  teardown?(): Promise<void> | void;
-}
-
-// ==========================================
-// Metadata Provider SPI (#7, #206, #207, #477)
-// ==========================================
-
-export interface MetadataSearchResult {
-  id: string;
-  title: string;
-  releaseYear?: number;
-  coverUrl?: string;
-  bannerUrl?: string;
-  iconUrl?: string;
-  description?: string;
-  provider: string;
-}
-
-export interface MetadataDetails extends MetadataSearchResult {
-  genres?: string[];
-  developers?: string[];
-  publishers?: string[];
-  screenshots?: string[];
-  metadata?: Record<string, unknown>;
-}
-
-export interface MetadataProvider {
-  id: string;
-  name: string;
-  search(query: string): Promise<MetadataSearchResult[]>;
-  getDetails(id: string): Promise<MetadataDetails | null>;
-}
-
-// ==========================================
-// Store Scanner SPI (#21)
-// ==========================================
-
-export interface ScannedGame {
-  externalId: string;
-  store: "steam" | "gog" | "epic" | string;
-  title: string;
-  installPath: string;
-  executablePath?: string;
-  iconUrl?: string;
-  version?: string;
-}
-
-export interface StoreScanner {
-  id: string;
-  name: string;
-  store: string;
-  scan(): Promise<ScannedGame[]>;
-  launch?(externalId: string): Promise<void>;
-}
-
-// ==========================================
-// Cloud Save Provider SPI (#9)
-// ==========================================
-
-export interface CloudSavePattern {
-  pattern: string;
-  platform?: "windows" | "linux" | "macos";
-  winePrefix?: boolean;
-}
-
-export interface GameInstallContext {
-  gameId: string;
-  gameTitle: string;
-  installDir?: string;
-  winePrefix?: string;
-  executableName?: string;
-}
-
-export interface CloudSavePathResolver {
-  id: string;
-  name: string;
-  resolveSavePaths(
-    gameContext: GameInstallContext,
-  ): Promise<CloudSavePattern[]>;
-}
+export type * from "@drop/plugin-api";
diff --git a/desktop/main/package.json b/desktop/main/package.json
index 381417ce1..6ff9c0122 100644
--- a/desktop/main/package.json
+++ b/desktop/main/package.json
@@ -12,6 +12,7 @@
     "test": "node --test --import jiti/register internal/**/__tests__/*.test.ts"
   },
   "dependencies": {
+    "@drop/plugin-api": "file:../../libraries/plugin-api",
     "@headlessui/vue": "^1.7.23",
     "@heroicons/vue": "^2.1.5",
     "@nuxtjs/tailwindcss": "^6.12.2",
diff --git a/desktop/main/pnpm-lock.yaml b/desktop/main/pnpm-lock.yaml
index e91174dc6..6da519e3c 100644
--- a/desktop/main/pnpm-lock.yaml
+++ b/desktop/main/pnpm-lock.yaml
@@ -22,6 +22,9 @@ importers:
 
   .:
     dependencies:
+      '@drop/plugin-api':
+        specifier: file:../../libraries/plugin-api
+        version: file:../../libraries/plugin-api
       '@headlessui/vue':
         specifier: ^1.7.23
         version: 1.7.23(vue@3.5.41(typescript@5.9.3))
@@ -297,6 +300,9 @@ packages:
     peerDependencies:
       postcss-selector-parser: ^7.0.0
 
+  '@drop/plugin-api@file:../../libraries/plugin-api':
+    resolution: {directory: ../../libraries/plugin-api, type: directory}
+
   '@dxup/nuxt@0.5.6':
     resolution: {integrity: sha512-uZjAFoocWtWHr7YP9jm6FqwI8kjX2QN9bjcncoZt0GS+zExIAP3Ewv6EqEUvVP7w9pjZE+T19QxLHeoacN/MNg==}
 
@@ -4464,6 +4470,8 @@ snapshots:
     dependencies:
       postcss-selector-parser: 7.1.4
 
+  '@drop/plugin-api@file:../../libraries/plugin-api': {}
+
   '@dxup/nuxt@0.5.6(esbuild@0.28.1)(magicast@0.5.4)(rolldown@1.2.3)(rollup@4.62.4)(vite@8.2.1(@types/node@25.5.0)(esbuild@0.28.1)(jiti@2.7.0)(sass-embedded@1.93.3)(sass@1.93.3)(terser@5.49.2)(yaml@2.9.0))':
     dependencies:
       '@dxup/unimport': 0.1.2
diff --git a/desktop/main/pnpm-workspace.yaml b/desktop/main/pnpm-workspace.yaml
index 02c446f78..0f979d586 100644
--- a/desktop/main/pnpm-workspace.yaml
+++ b/desktop/main/pnpm-workspace.yaml
@@ -1,3 +1,7 @@
+allowBuilds:
+  '@parcel/watcher': set this to true or false
+  esbuild: set this to true or false
+
 onlyBuiltDependencies:
   - '@parcel/watcher'
   - esbuild
diff --git a/libraries/plugin-api/package.json b/libraries/plugin-api/package.json
new file mode 100644
index 000000000..9d7cbab11
--- /dev/null
+++ b/libraries/plugin-api/package.json
@@ -0,0 +1,12 @@
+{
+  "name": "@drop/plugin-api",
+  "private": true,
+  "version": "0.0.1",
+  "type": "module",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts"
+    }
+  }
+}
diff --git a/libraries/plugin-api/src/client.ts b/libraries/plugin-api/src/client.ts
new file mode 100644
index 000000000..8c9872e06
--- /dev/null
+++ b/libraries/plugin-api/src/client.ts
@@ -0,0 +1,274 @@
+import type { HttpMethod, PluginLogger, PluginMetadata } from "./common";
+
+export type { HttpMethod };
+
+export type UISlotName =
+  | "game-detail:actions"
+  | "game-detail:panels"
+  | "game-detail:badges"
+  | "settings:tabs"
+  | "topbar:status"
+  | "sidebar:nav"
+  | "overlay:panel"
+  | "overlay:quick-access";
+
+export interface UISlotRegistration {
+  id: string;
+  pluginId: string;
+  slot: UISlotName;
+  component: unknown;
+  order: number;
+  label?: string;
+  icon?: string;
+}
+
+export interface LaunchContext {
+  gameId: string;
+  gameTitle: string;
+  gameDir: string;
+  actionId?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export type LaunchStage =
+  | "pre-launch:validate"
+  | "pre-launch:prepare"
+  | "pre-launch:stage"
+  | "pre-launch:network"
+  | "launch"
+  | "post-exit:cleanup"
+  | "post-exit:restore"
+  | "post-exit:sync";
+
+export interface LaunchHook {
+  stage: LaunchStage;
+  order?: number;
+  execute: (ctx: LaunchContext) => Promise<void> | void;
+}
+
+export interface PlayAction {
+  id: string;
+  name: string;
+  icon?: string;
+  isDefault?: boolean;
+  execute: (context: LaunchContext) => Promise<void> | void;
+}
+
+export interface GameMenuItem {
+  id: string;
+  label: string;
+  icon?: string;
+  execute: (gameId: string) => Promise<void> | void;
+}
+
+export interface SidebarItem {
+  id: string;
+  title: string;
+  icon?: string;
+  type: "button" | "view";
+  progressValue?: number;
+  activated?: () => void;
+  component?: unknown;
+}
+
+export interface TopBarItem {
+  id: string;
+  title: string;
+  icon?: string;
+  component?: unknown;
+  activated?: () => void;
+}
+
+export interface ScopedGameFs {
+  readFile(gameId: string, relativePath: string): Promise<Uint8Array>;
+  writeFile(
+    gameId: string,
+    relativePath: string,
+    data: Uint8Array | string,
+  ): Promise<void>;
+  backupFile(gameId: string, relativePath: string): Promise<string>;
+  restoreFile(gameId: string, relativePath: string): Promise<void>;
+  fileExists(gameId: string, relativePath: string): Promise<boolean>;
+  deleteFile(gameId: string, relativePath: string): Promise<void>;
+}
+
+export interface ScopedGameScanner {
+  scanExecutables(
+    gameId: string,
+  ): Promise<Array<{ relativePath: string; sha256: string; size: number }>>;
+  /**
+   * Returns the relative paths of installed files whose path contains any of
+   * the supplied patterns (case-insensitive). The host is agnostic about the
+   * patterns, so plugins own domain knowledge such as anti-cheat detection.
+   */
+  findFiles(gameId: string, patterns: string[]): Promise<string[]>;
+}
+
+export interface ClientPluginStorage {
+  get<T>(key: string): Promise<T | null>;
+  set<T>(key: string, value: T): Promise<void>;
+  delete(key: string): Promise<void>;
+  listKeys(): Promise<string[]>;
+}
+
+export interface ClientPluginWebSocket {
+  send(channel: string, data: unknown): Promise<unknown>;
+  subscribe(channel: string, listener: (data: unknown) => void): () => void;
+}
+
+/** Result of a native command run through the client host. */
+export interface CommandResult {
+  code: number;
+  stdout: string;
+  stderr: string;
+}
+
+export interface CommandOptions {
+  cwd?: string;
+  timeoutMs?: number;
+}
+
+/**
+ * Native command execution for client plugins. The host runs the binary
+ * directly (no shell) and enforces the per-plugin allowlist registered from
+ * `manifest.client.commands`.
+ */
+export interface ClientPluginSystem {
+  run(
+    bin: string,
+    args?: string[],
+    options?: CommandOptions,
+  ): Promise<CommandResult>;
+}
+
+export interface ClientPluginContext {
+  id: string;
+  logger: PluginLogger;
+  storage: ClientPluginStorage;
+  registerSlot(
+    slot: UISlotName,
+    component: unknown,
+    options?: { order?: number; label?: string; icon?: string },
+  ): void;
+  registerPlayAction(
+    provider: (gameId: string) => Promise<PlayAction[]> | PlayAction[],
+  ): () => void;
+  registerGameMenuItem(item: GameMenuItem): () => void;
+  registerSidebarItem(item: SidebarItem): () => void;
+  registerTopBarItem(item: TopBarItem): () => void;
+  registerLaunchHook(hook: LaunchHook): () => void;
+  /**
+   * Register a store library scanner SPI implementation.
+   * Requires the `client:library-scan` capability.
+   */
+  registerStoreScanner(scanner: StoreScanner): () => void;
+  /**
+   * Register a client-side metadata provider SPI implementation.
+   * Requires the `metadata:provider` capability.
+   */
+  registerMetadataProvider?(provider: MetadataProvider): () => void;
+  /**
+   * Register a client-side cloud save path resolver SPI implementation.
+   * Requires the `cloudsave:provider` capability.
+   */
+  registerCloudSaveResolver?(resolver: CloudSavePathResolver): () => void;
+  gameFs: ScopedGameFs;
+  gameScanner: ScopedGameScanner;
+  serverWs: ClientPluginWebSocket;
+  /** Native command execution. Requires the `system:command` capability. */
+  system: ClientPluginSystem;
+  /**
+   * Call this plugin's own server-side REST routes through the desktop host.
+   * The webview cannot reach the Drop server directly, so the host proxies the
+   * request. `path` is relative to `/api/v1/plugins/<pluginId>`.
+   */
+  serverRequest<T = unknown>(
+    method: HttpMethod,
+    path?: string,
+    body?: unknown,
+  ): Promise<T>;
+}
+
+export interface ClientPlugin {
+  metadata?: PluginMetadata;
+  init(ctx: ClientPluginContext): Promise<void> | void;
+  teardown?(): Promise<void> | void;
+}
+
+// ==========================================
+// Metadata Provider SPI (#7, #206, #207, #477)
+// ==========================================
+
+export interface MetadataSearchResult {
+  id: string;
+  title: string;
+  releaseYear?: number;
+  coverUrl?: string;
+  bannerUrl?: string;
+  iconUrl?: string;
+  description?: string;
+  provider: string;
+}
+
+export interface MetadataDetails extends MetadataSearchResult {
+  genres?: string[];
+  developers?: string[];
+  publishers?: string[];
+  screenshots?: string[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface MetadataProvider {
+  id: string;
+  name: string;
+  search(query: string): Promise<MetadataSearchResult[]>;
+  getDetails(id: string): Promise<MetadataDetails | null>;
+}
+
+// ==========================================
+// Store Scanner SPI (#21)
+// ==========================================
+
+export interface ScannedGame {
+  externalId: string;
+  store: "steam" | "gog" | "epic" | string;
+  title: string;
+  installPath: string;
+  executablePath?: string;
+  iconUrl?: string;
+  version?: string;
+}
+
+export interface StoreScanner {
+  id: string;
+  name: string;
+  store: string;
+  scan(): Promise<ScannedGame[]>;
+  launch?(externalId: string): Promise<void>;
+}
+
+// ==========================================
+// Cloud Save Provider SPI (#9)
+// ==========================================
+
+export interface CloudSavePattern {
+  pattern: string;
+  platform?: "windows" | "linux" | "macos";
+  winePrefix?: boolean;
+}
+
+export interface GameInstallContext {
+  gameId: string;
+  gameTitle: string;
+  installDir?: string;
+  winePrefix?: string;
+  executableName?: string;
+}
+
+export interface CloudSavePathResolver {
+  id: string;
+  name: string;
+  resolveSavePaths(
+    gameContext: GameInstallContext,
+  ): Promise<CloudSavePattern[]>;
+}
diff --git a/libraries/plugin-api/src/common.ts b/libraries/plugin-api/src/common.ts
new file mode 100644
index 000000000..5986d170e
--- /dev/null
+++ b/libraries/plugin-api/src/common.ts
@@ -0,0 +1,166 @@
+/**
+ * Core plugin API contracts shared by the Drop server and desktop client.
+ *
+ * This package is intentionally type-only: every export is a type or an
+ * interface, so consumers must use `import type`/`export type`. Keeping it
+ * free of runtime values avoids bundler and module-resolution issues in
+ * Nuxt/Nitro, where the package is consumed purely for type checking.
+ */
+
+export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "ALL";
+
+export type PluginTarget = "server" | "client";
+
+export type PluginCategory = "generic" | "metadata" | "storage" | "multiplayer";
+
+export type ServerCapability =
+  | "routes"
+  | "storage"
+  | "websocket"
+  | "events"
+  | "network"
+  | "metadata:provider"
+  | "cloudsave:provider"
+  | "commerce:payment";
+
+export type ClientCapability =
+  | "ui:slot"
+  | "ui:play-action"
+  | "ui:context-menu"
+  | "ui:sidebar"
+  | "ui:topbar"
+  | "game:launch-hook"
+  | "game:fs"
+  | "game:scan"
+  | "client:storage"
+  | "client:ws"
+  | "system:sidecar"
+  | "system:command"
+  | "metadata:provider"
+  | "cloudsave:provider"
+  | "client:library-scan";
+
+export type PluginCapability = ServerCapability | ClientCapability;
+
+/**
+ * Trust tier. Only `"trusted"` is supported today: plugins run in-process with
+ * the server or client's own privileges. `"sandboxed"` is reserved for a future
+ * isolated runtime and must be rejected until that runtime exists.
+ */
+export type PluginTrust = "trusted" | "sandboxed";
+
+export type PluginStatus = "active" | "disabled" | "error" | "registered";
+
+export interface PluginMetadata {
+  id: string;
+  name: string;
+  version: string;
+  description?: string;
+  author?: string;
+  builtin?: boolean;
+  /** Plugin API version the plugin was built against. */
+  apiVersion?: number;
+  /** Trust tier. Defaults to "trusted". */
+  trust?: PluginTrust;
+  /** Declared storage schema version; drives `migrateStorage`. */
+  storageVersion?: number;
+  category?: PluginCategory;
+  targets?: PluginTarget[];
+  capabilities?: PluginCapability[];
+  enabled?: boolean;
+}
+
+export interface PluginManifest extends PluginMetadata {
+  entry?: string;
+  /** SHA-256 of the entry file, hex. Verified before the bundle is imported. */
+  checksum?: string;
+  /**
+   * SHA-256 of every file the bundle may import, keyed by path relative to the
+   * bundle directory. Required for multi-file bundles so relative imports are
+   * verified too. When present with `DROP_PLUGIN_SIGNING_KEY`, `signature`
+   * covers the aggregate bundle digest rather than only the entry file.
+   */
+  files?: Record<string, string>;
+  /**
+   * Signature scheme marker. Bundles signed by `@drop-oss/plugin-cli` >= 0.6.0
+   * carry `2`, meaning `signature` covers the file aggregate plus the canonical
+   * manifest. Absent on legacy bundles, whose signature covers the file
+   * aggregate or entry checksum only.
+   */
+  signatureVersion?: number;
+  /**
+   * HMAC-SHA256 (hex) of the signature payload, keyed by
+   * `DROP_PLUGIN_SIGNING_KEY`. Set `DROP_PLUGIN_REQUIRE_SIGNATURE=true` to
+   * reject unsigned bundles.
+   */
+  signature?: string;
+
+  server?: {
+    entry: string;
+    capabilities: ServerCapability[];
+    storageVersion?: number;
+  };
+  client?: {
+    entry: string;
+    css?: string;
+    capabilities: ClientCapability[];
+    slots?: Array<{ slot: string; component: string }>;
+    /**
+     * Bare executable names the client plugin may run via `ctx.system.run`
+     * (requires the `system:command` capability). Enforced by the desktop host.
+     */
+    commands?: string[];
+  };
+}
+
+export interface PluginStateRecord {
+  enabled: boolean;
+  updatedAt: number;
+}
+
+/**
+ * Logger contract exposed to plugins. Matches the matching interface in
+ * `@drop-oss/plugin-sdk` so plugin code can be typed against either package.
+ */
+export interface PluginLogger {
+  info(msg: string, ...args: any[]): void;
+  warn(msg: string, ...args: any[]): void;
+  error(msg: string, ...args: any[]): void;
+  debug(msg: string, ...args: any[]): void;
+}
+
+// ==========================================
+// Payment Gateway SPI (#21)
+// ==========================================
+
+export interface PaymentIntentRequest {
+  orderId: string;
+  amount: number; // minor units (e.g. cents)
+  currency: string;
+  customerEmail?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface PaymentIntentResult {
+  intentId: string;
+  clientSecret?: string;
+  checkoutUrl?: string;
+  status: "pending" | "succeeded" | "failed";
+}
+
+export interface PaymentWebhookResult {
+  orderId: string;
+  status: "succeeded" | "failed" | "refunded";
+  transactionId: string;
+  payload?: Record<string, unknown>;
+}
+
+export interface PaymentGateway {
+  id: string;
+  name: string;
+  createPaymentIntent(req: PaymentIntentRequest): Promise<PaymentIntentResult>;
+  handleWebhook(
+    payload: unknown,
+    headers: Record<string, string>,
+  ): Promise<PaymentWebhookResult>;
+}
diff --git a/libraries/plugin-api/src/index.ts b/libraries/plugin-api/src/index.ts
new file mode 100644
index 000000000..2fa59cd5b
--- /dev/null
+++ b/libraries/plugin-api/src/index.ts
@@ -0,0 +1,2 @@
+export type * from "./common";
+export type * from "./client";
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 9299b6741..8020be438 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -98,6 +98,8 @@ importers:
         specifier: latest
         version: 3.5.42(typescript@5.9.3)
 
+  libraries/plugin-api: {}
+
   server:
     dependencies:
       '@bufbuild/protobuf':
@@ -106,6 +108,9 @@ importers:
       '@discordapp/twemoji':
         specifier: ^16.0.1
         version: 16.0.1
+      '@drop/plugin-api':
+        specifier: workspace:*
+        version: link:../libraries/plugin-api
       '@headlessui/vue':
         specifier: ^1.7.23
         version: 1.7.23(vue@3.5.42(typescript@5.9.3))
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 209ed10cc..80435deb9 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -1,6 +1,7 @@
 packages:
   - "server/"
   - "libraries/base/"
+  - "libraries/plugin-api/"
   - "sites/*"
   - "desktop/"
 
diff --git a/server/package.json b/server/package.json
index 7e65b0977..0b9f4f927 100644
--- a/server/package.json
+++ b/server/package.json
@@ -22,6 +22,7 @@
   },
   "dependencies": {
     "@bufbuild/protobuf": "^2.11.0",
+    "@drop/plugin-api": "workspace:*",
     "@discordapp/twemoji": "^16.0.1",
     "@headlessui/vue": "^1.7.23",
     "@heroicons/vue": "^2.1.5",
diff --git a/server/server/internal/plugins/types.ts b/server/server/internal/plugins/types.ts
index 8023f055c..bb6fe8957 100644
--- a/server/server/internal/plugins/types.ts
+++ b/server/server/internal/plugins/types.ts
@@ -1,11 +1,21 @@
 import type { H3Event } from "h3";
 import type { Logger } from "pino";
+import type {
+  CloudSavePathResolver,
+  HttpMethod,
+  MetadataProvider,
+  PaymentGateway,
+  PluginMetadata,
+} from "@drop/plugin-api";
 
 /**
- * Current plugin API version. Bump this when `PluginContext` or the manifest
- * contract changes incompatibly. Plugins declare the version they were built
- * against in `metadata.apiVersion`; mismatches are rejected at registration.
+ * Shared plugin contract types (manifest, capabilities, SPI results) live in
+ * the `@drop/plugin-api` workspace package so the server and desktop client
+ * cannot drift. This module layers the server-runtime types that depend on
+ * `h3`/`pino` and the runtime API-version constants on top of them.
  */
+export type * from "@drop/plugin-api";
+
 /**
  * Current plugin API version. Bump this when `PluginContext` or the manifest
  * contract changes incompatibly. Plugins declare the version they were built
@@ -14,118 +24,6 @@ import type { Logger } from "pino";
 export const PLUGIN_API_VERSION = 2;
 export const SUPPORTED_API_VERSIONS = [1, 2] as const;
 
-export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "ALL";
-
-export type PluginTarget = "server" | "client";
-
-export type PluginCategory = "generic" | "metadata" | "storage" | "multiplayer";
-
-export type ServerCapability =
-  | "routes"
-  | "storage"
-  | "websocket"
-  | "events"
-  | "network"
-  | "metadata:provider"
-  | "cloudsave:provider"
-  | "commerce:payment";
-
-export type ClientCapability =
-  | "ui:slot"
-  | "ui:play-action"
-  | "ui:context-menu"
-  | "ui:sidebar"
-  | "ui:topbar"
-  | "game:launch-hook"
-  | "game:fs"
-  | "game:scan"
-  | "client:storage"
-  | "client:ws"
-  | "system:sidecar"
-  | "system:command"
-  | "metadata:provider"
-  | "cloudsave:provider"
-  | "client:library-scan";
-
-export type PluginCapability = ServerCapability | ClientCapability;
-
-/**
- * Trust tier. Only `"trusted"` is supported today: plugins run in-process with
- * the server's own privileges. `"sandboxed"` is reserved for a future isolated
- * runtime (see docs/implementation/drop-gse.md, M4/P6) and must be rejected
- * until that runtime exists.
- */
-export type PluginTrust = "trusted" | "sandboxed";
-
-export type PluginStatus = "active" | "disabled" | "error" | "registered";
-
-export interface PluginMetadata {
-  id: string;
-  name: string;
-  version: string;
-  description?: string;
-  author?: string;
-  builtin?: boolean;
-  /** Plugin API version the plugin was built against. */
-  apiVersion?: number;
-  /** Trust tier. Defaults to "trusted". */
-  trust?: PluginTrust;
-  /** Declared storage schema version; drives `migrateStorage`. */
-  storageVersion?: number;
-  category?: PluginCategory;
-  targets?: PluginTarget[];
-  capabilities?: PluginCapability[];
-  enabled?: boolean;
-}
-
-export interface PluginManifest extends PluginMetadata {
-  entry?: string;
-  /** SHA-256 of the entry file, hex. Verified before the bundle is imported. */
-  checksum?: string;
-  /**
-   * SHA-256 of every file the bundle may import, keyed by path relative to the
-   * bundle directory. Required for multi-file bundles so relative imports are
-   * verified too. When present with `DROP_PLUGIN_SIGNING_KEY`, `signature`
-   * covers the aggregate bundle digest rather than only the entry file.
-   */
-  files?: Record<string, string>;
-  /**
-   * Signature scheme marker. Bundles signed by `@droposs/plugin-cli` >= 0.6.0
-   * carry `2`, meaning `signature` covers the file aggregate plus the canonical
-   * manifest. Absent on legacy bundles, whose signature covers the file
-   * aggregate or entry checksum only.
-   */
-  signatureVersion?: number;
-  /**
-   * HMAC-SHA256 (hex) of the signature payload, keyed by
-   * `DROP_PLUGIN_SIGNING_KEY`. Set `DROP_PLUGIN_REQUIRE_SIGNATURE=true` to
-   * reject unsigned bundles.
-   */
-  signature?: string;
-
-  server?: {
-    entry: string;
-    capabilities: ServerCapability[];
-    storageVersion?: number;
-  };
-  client?: {
-    entry: string;
-    css?: string;
-    capabilities: ClientCapability[];
-    slots?: Array<{ slot: string; component: string }>;
-    /**
-     * Bare executable names the client plugin may run via `ctx.system.run`
-     * (requires the `system:command` capability). Enforced by the desktop host.
-     */
-    commands?: string[];
-  };
-}
-
-export interface PluginStateRecord {
-  enabled: boolean;
-  updatedAt: number;
-}
-
 export interface RouteHandlerContext {
   params: Record<string, string>;
   query: Record<string, string | string[] | undefined>;
@@ -252,117 +150,3 @@ export interface ServerPlugin {
     storage: PluginStorage,
   ): Promise<void>;
 }
-
-// ==========================================
-// Metadata Provider SPI (#7, #206, #207, #477)
-// ==========================================
-
-export interface MetadataSearchResult {
-  id: string;
-  title: string;
-  releaseYear?: number;
-  coverUrl?: string;
-  bannerUrl?: string;
-  iconUrl?: string;
-  description?: string;
-  provider: string;
-}
-
-export interface MetadataDetails extends MetadataSearchResult {
-  genres?: string[];
-  developers?: string[];
-  publishers?: string[];
-  screenshots?: string[];
-  metadata?: Record<string, unknown>;
-}
-
-export interface MetadataProvider {
-  id: string;
-  name: string;
-  search(query: string): Promise<MetadataSearchResult[]>;
-  getDetails(id: string): Promise<MetadataDetails | null>;
-}
-
-// ==========================================
-// Cloud Save Provider SPI (#9)
-// ==========================================
-
-export interface CloudSavePattern {
-  pattern: string;
-  platform?: "windows" | "linux" | "macos";
-  winePrefix?: boolean;
-}
-
-export interface GameInstallContext {
-  gameId: string;
-  gameTitle: string;
-  installDir?: string;
-  winePrefix?: string;
-  executableName?: string;
-}
-
-export interface CloudSavePathResolver {
-  id: string;
-  name: string;
-  resolveSavePaths(
-    gameContext: GameInstallContext,
-  ): Promise<CloudSavePattern[]>;
-}
-
-// ==========================================
-// Store Scanner SPI (#21)
-// ==========================================
-
-export interface ScannedGame {
-  externalId: string;
-  store: "steam" | "gog" | "epic" | string;
-  title: string;
-  installPath: string;
-  executablePath?: string;
-  iconUrl?: string;
-  version?: string;
-}
-
-export interface StoreScanner {
-  id: string;
-  name: string;
-  store: string;
-  scan(): Promise<ScannedGame[]>;
-  launch?(externalId: string): Promise<void>;
-}
-
-// ==========================================
-// Payment Gateway SPI (#21)
-// ==========================================
-
-export interface PaymentIntentRequest {
-  orderId: string;
-  amount: number; // minor units (e.g. cents)
-  currency: string;
-  customerEmail?: string;
-  metadata?: Record<string, unknown>;
-}
-
-export interface PaymentIntentResult {
-  intentId: string;
-  clientSecret?: string;
-  checkoutUrl?: string;
-  status: "pending" | "succeeded" | "failed";
-}
-
-export interface PaymentWebhookResult {
-  orderId: string;
-  status: "succeeded" | "failed" | "refunded";
-  transactionId: string;
-  payload?: Record<string, unknown>;
-}
-
-export interface PaymentGateway {
-  id: string;
-  name: string;
-  createPaymentIntent(req: PaymentIntentRequest): Promise<PaymentIntentResult>;
-  handleWebhook(
-    payload: unknown,
-    headers: Record<string, string>,
-  ): Promise<PaymentWebhookResult>;
-}

From 987326e3c4801647a9e8b82a946ec587c6edb5c7 Mon Sep 17 00:00:00 2001
From: John Smith <you@example.com>
Date: Mon, 14 Sep 2026 23:29:24 -0400
Subject: [PATCH 09/13] docs(plugins): point at Drop-OSS SDK, scope, and trust
 model

- document the @drop-oss scope effective with SDK 0.6.0 and the pending
  repository transfer
- add a prominent unsandboxed/privileged warning and fix the capability
  consent claims for the server admin flow
- document signature v2 manifest coverage and drop-plugin verify
---
 sites/docs/src/content/docs/admin/plugins.md | 43 +++++++++++++-------
 1 file changed, 29 insertions(+), 14 deletions(-)

diff --git a/sites/docs/src/content/docs/admin/plugins.md b/sites/docs/src/content/docs/admin/plugins.md
index c8dabe692..b57f2a0a2 100644
--- a/sites/docs/src/content/docs/admin/plugins.md
+++ b/sites/docs/src/content/docs/admin/plugins.md
@@ -3,16 +3,24 @@ title: Plugins
 ---
 
 Drop supports an extensible plugin runtime across both the server and desktop client.
-A server plugin can register HTTP routes under `/api/v1/plugins/<id>/...`, subscribe/broadcast events, use namespaced storage, and handle WebSocket messages. Desktop client plugins can contribute UI panels, status badges, Play Actions, and game launch hooks. Plugins run **in-process**, so only install code you trust.
+A server plugin can register HTTP routes under `/api/v1/plugins/<id>/...`, subscribe/broadcast events, use namespaced storage, and handle WebSocket messages. Desktop client plugins can contribute UI panels, status badges, Play Actions, and game launch hooks.
+
+:::danger[Plugins run with full host privileges]
+Plugins are **not sandboxed**. Server plugins execute in-process with the Drop server's own privileges; desktop plugins execute in-process with the desktop client's privileges. Native commands run through the desktop host are **unsandboxed** — they are only checked against the plugin's allowlist, not confined. Declared capabilities are used for validation and review, not for confinement. Only install plugins you trust, and prefer signed bundles from sources you control.
+:::
 
 ---
 
 ## Architecture & Toolchain
 
-The developer toolchain and runtime contracts are maintained in [`@droposs/plugin-sdk`](https://github.com/Heretek-Games/drop-plugin-sdk):
+The developer toolchain and runtime contracts are maintained in the Drop Plugin SDK repository at [`Drop-OSS/drop-plugin-sdk`](https://github.com/Drop-OSS/drop-plugin-sdk) (the repository is being transferred there from [`Heretek-Games/drop-plugin-sdk`](https://github.com/Heretek-Games/drop-plugin-sdk); until the transfer lands, the latter remains the canonical source):
+
+- **SDK (`@drop-oss/plugin-sdk`)**: Public TypeScript contracts, JSON Schema, and mock harnesses (`MockPluginContext`, `MockClientPluginContext`).
+- **CLI (`@drop-oss/plugin-cli`)**: Developer CLI (`drop-plugin`) providing `init`, `build`, `test`, `validate`, `sign`, `verify`, and `pack`.
 
-- **SDK (`@droposs/plugin-sdk`)**: Public TypeScript contracts, JSON Schema, and mock harnesses (`MockPluginContext`, `MockClientPluginContext`).
-- **CLI (`@droposs/plugin-cli`)**: Developer CLI (`drop-plugin`) providing `init`, `build`, `test`, `validate`, `sign`, and `pack`.
+:::note
+The `@drop-oss` package scope takes effect with SDK **0.6.0**. The currently published **0.5.x** releases are still published as `@droposs/plugin-sdk` and `@droposs/plugin-cli`. The examples below use the `@drop-oss` names; substitute the `@droposs` names if you are on 0.5.x.
+:::
 
 ---
 
@@ -37,30 +45,34 @@ A plugin lives in `<dataDir>/plugins/<id>/` and contains:
 - `entry` — relative path to primary entry point (default `index.js`).
 - `checksum` — SHA-256 hex digest of the primary entry file.
 - `files` — mapping of relative bundle file paths to their individual SHA-256 digests. Required for multi-file bundles.
-- `signature` — HMAC-SHA256 covering the aggregate bundle digest (or `checksum` for single-file bundles) under `DROP_PLUGIN_SIGNING_KEY`.
+- `signatureVersion` — signature scheme marker. Bundles signed by `@drop-oss/plugin-cli` 0.6.0+ carry `2`, meaning `signature` covers the aggregate bundle digest **plus the canonical manifest** (everything except `signature` itself). Legacy bundles omit the marker, and their signature covers only the file aggregate or the entry checksum.
+- `signature` — HMAC-SHA256 of the signature payload under `DROP_PLUGIN_SIGNING_KEY`. For `signatureVersion: 2` bundles this covers the file aggregate and the manifest; for legacy bundles it covers the aggregate bundle digest (or `checksum` for single-file bundles).
 
 ---
 
 ## Building, Signing & Packaging
 
-Using the Drop Plugin CLI (`@droposs/plugin-cli`):
+Using the Drop Plugin CLI (`@drop-oss/plugin-cli`):
 
 ```sh
 # Bundle TypeScript server and client sources into ESM dist/
-npx @droposs/plugin-cli build .
+npx @drop-oss/plugin-cli build .
 
 # Validate manifest against schema
-npx @droposs/plugin-cli validate .
+npx @drop-oss/plugin-cli validate .
 
 # Sign drop-plugin.json with SHA-256 digests and HMAC signature
 export DROP_PLUGIN_SIGNING_KEY="secret-key"
-npx @droposs/plugin-cli sign .
+npx @drop-oss/plugin-cli sign .
+
+# Verify digests and (when present) the signature of a built bundle
+npx @drop-oss/plugin-cli verify . --allow-unsigned
 
 # Package into a .dropplugin distribution archive
-npx @droposs/plugin-cli pack . ./dist-package
+npx @drop-oss/plugin-cli pack . ./dist-package
 ```
 
-Set `DROP_PLUGIN_REQUIRE_SIGNATURE=true` on the server to refuse unsigned bundles.
+`drop-plugin verify` recalculates every SHA-256 digest and, for signed bundles, validates the HMAC signature. Run it before installing a bundle you did not build yourself. Set `DROP_PLUGIN_REQUIRE_SIGNATURE=true` on the server to refuse unsigned bundles.
 
 ---
 
@@ -89,11 +101,12 @@ Set `DROP_PLUGIN_REGISTRY` to a JSON file path or a remote HTTP/HTTPS URL (`http
 
 ## Signing Key Distribution & Trust Guidance
 
-By default, plugins run trusted in-process. To enforce cryptographic integrity and supply chain provenance:
+By default, plugins run trusted in-process with the host's full privileges, as described in the warning at the top of this page. To enforce cryptographic integrity and supply chain provenance:
 
 1. **Require Signatures**: Set `DROP_PLUGIN_REQUIRE_SIGNATURE=true` on the server. Any bundle without a cryptographic `signature` is refused immediately.
-2. **Key Distribution**: Set `DROP_PLUGIN_SIGNING_KEY="<hmac-secret>"` across build pipelines and the Drop server instance. The CLI `drop-plugin sign` signs the aggregate digest across all bundle files.
+2. **Key Distribution**: Set `DROP_PLUGIN_SIGNING_KEY="<hmac-secret>"` across build pipelines and the Drop server instance. The CLI `drop-plugin sign` signs the aggregate digest across all bundle files; with `signatureVersion: 2` (0.6.0+) the canonical manifest is covered as well, so manifest tampering invalidates the signature.
 3. **Registry Pinning**: Combine with a pinned registry index to enforce dual verification: exact SHA-256 code digest plus cryptographic HMAC signature.
+4. **Verify Before Install**: Run `drop-plugin verify` on any bundle you did not build. Capabilities are declared in the manifest for review; they do not sandbox the plugin.
 
 ---
 
@@ -101,10 +114,12 @@ By default, plugins run trusted in-process. To enforce cryptographic integrity a
 
 ### 1. Via Desktop Client Settings
 
-Navigate to **Settings → Plugins & Extensions** and click **Upload .dropplugin / JSON** to select a `.dropplugin` package, or paste the bundle JSON directly. A capability consent dialog prompts the administrator to authorize declared permissions before installation.
+Navigate to **Settings → Plugins & Extensions** and click **Upload .dropplugin / JSON** to select a `.dropplugin` package, or paste the bundle JSON directly. The desktop client shows a **Review Plugin Permissions** consent dialog listing the manifest's declared capabilities before the plugin is installed.
 
 ### 2. Via Admin API (Install-by-URL or Multi-file Package)
 
+The server admin install flow does **not** show a capability-consent dialog. Inspect the manifest's declared capabilities and the bundle's signature yourself before installing.
+
 Install via `POST /api/v1/plugins/install` with an admin token:
 
 #### Install by URL:

From 58766bbfc3d506690be2cc0b0f7046966ef4a96f Mon Sep 17 00:00:00 2001
From: John Smith <you@example.com>
Date: Mon, 14 Sep 2026 23:33:00 -0400
Subject: [PATCH 10/13] docs(plugins): reference the @drop-oss CLI scope in
 signature comments

---
 server/server/internal/plugins/__tests__/signature.test.ts | 6 +++---
 server/server/internal/plugins/signature.ts                | 6 +++---
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/server/server/internal/plugins/__tests__/signature.test.ts b/server/server/internal/plugins/__tests__/signature.test.ts
index 8deda04eb..905ef2075 100644
--- a/server/server/internal/plugins/__tests__/signature.test.ts
+++ b/server/server/internal/plugins/__tests__/signature.test.ts
@@ -4,9 +4,9 @@ import { createHash, createHmac } from "node:crypto";
 import { SIGNATURE_VERSION, signaturePayloadV2 } from "../signature";
 
 /**
- * Shared cross-repo fixture vector. The same values are asserted by
- * `@droposs/plugin-cli`'s signer tests; changing the canonicalization or the
- * payload layout on either side breaks this test.
+ * Shared cross-repo fixture vector. The same values are asserted by the plugin
+ * CLI's signer tests (`@drop-oss/plugin-cli`); changing the canonicalization or
+ * the payload layout on either side breaks this test.
  */
 const FIXTURE = {
   files: [
diff --git a/server/server/internal/plugins/signature.ts b/server/server/internal/plugins/signature.ts
index 1170ac163..6141fa7bc 100644
--- a/server/server/internal/plugins/signature.ts
+++ b/server/server/internal/plugins/signature.ts
@@ -28,9 +28,9 @@ export function stableStringify(value: unknown): string {
 
 /**
  * Version 2 signature payload: the files aggregate plus the canonical manifest
- * (excluding its `signature` field). Mirrors
- * `@droposs/plugin-cli` `signaturePayloadV2`; a shared fixture vector in both
- * repos guards against drift.
+ * (excluding its `signature` field). Mirrors the plugin CLI's
+ * `signaturePayloadV2` (`@drop-oss/plugin-cli`); a shared fixture vector in
+ * both repos guards against drift.
  */
 export function signaturePayloadV2(
   filesAggregate: string,

From f394655d10358d02b5a4d50e54316e56bae8cbcf Mon Sep 17 00:00:00 2001
From: John Smith <you@example.com>
Date: Tue, 15 Sep 2026 17:14:05 -0400
Subject: [PATCH 11/13] feat(plugins): consume the MetadataProvider SPI in the
 metadata flow

---
 .../migration.sql                             |  5 +
 server/prisma/models/content.prisma           |  4 +
 .../metadata/__tests__/plugin-sources.test.ts | 33 +++++++
 .../internal/metadata/plugin-provider.ts      | 99 +++++++++++++++++++
 .../internal/metadata/plugin-sources.ts       | 20 ++++
 server/server/plugins/08.plugin-system.ts     | 14 +++
 6 files changed, 175 insertions(+)
 create mode 100644 server/prisma/migrations/20260914040000_add_metadata_sources/migration.sql
 create mode 100644 server/server/internal/metadata/__tests__/plugin-sources.test.ts
 create mode 100644 server/server/internal/metadata/plugin-provider.ts
 create mode 100644 server/server/internal/metadata/plugin-sources.ts

diff --git a/server/prisma/migrations/20260914040000_add_metadata_sources/migration.sql b/server/prisma/migrations/20260914040000_add_metadata_sources/migration.sql
new file mode 100644
index 000000000..61d5968dc
--- /dev/null
+++ b/server/prisma/migrations/20260914040000_add_metadata_sources/migration.sql
@@ -0,0 +1,5 @@
+-- AddValue
+ALTER TYPE "MetadataSource" ADD VALUE IF NOT EXISTS 'SteamGridDB';
+ALTER TYPE "MetadataSource" ADD VALUE IF NOT EXISTS 'LaunchBox';
+ALTER TYPE "MetadataSource" ADD VALUE IF NOT EXISTS 'ScreenScraper';
+ALTER TYPE "MetadataSource" ADD VALUE IF NOT EXISTS 'MobyGames';
diff --git a/server/prisma/models/content.prisma b/server/prisma/models/content.prisma
index e3635d479..094341786 100644
--- a/server/prisma/models/content.prisma
+++ b/server/prisma/models/content.prisma
@@ -6,6 +6,10 @@ enum MetadataSource {
   IGDB
   Metacritic
   OpenCritic
+  SteamGridDB
+  LaunchBox
+  ScreenScraper
+  MobyGames
 }
 
 enum GameType {
diff --git a/server/server/internal/metadata/__tests__/plugin-sources.test.ts b/server/server/internal/metadata/__tests__/plugin-sources.test.ts
new file mode 100644
index 000000000..716077de4
--- /dev/null
+++ b/server/server/internal/metadata/__tests__/plugin-sources.test.ts
@@ -0,0 +1,33 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { MetadataSource } from "~/prisma/client/enums";
+import {
+  PLUGIN_METADATA_SOURCES,
+  metadataSourceForPluginId,
+} from "../plugin-sources";
+
+test("known metadata plugins map to core MetadataSource values", () => {
+  assert.equal(
+    metadataSourceForPluginId("pcgamingwiki"),
+    MetadataSource.PCGamingWiki,
+  );
+  assert.equal(
+    metadataSourceForPluginId("steamgriddb"),
+    MetadataSource.SteamGridDB,
+  );
+  assert.equal(
+    metadataSourceForPluginId("mobygames"),
+    MetadataSource.MobyGames,
+  );
+});
+
+test("unknown metadata plugins are not persistable against the core enum", () => {
+  assert.equal(metadataSourceForPluginId("not-a-provider"), undefined);
+});
+
+test("every mapped value is a real MetadataSource enum member", () => {
+  const valid = new Set<string>(Object.values(MetadataSource));
+  for (const source of Object.values(PLUGIN_METADATA_SOURCES)) {
+    assert.ok(valid.has(source), `unexpected MetadataSource: ${source}`);
+  }
+});
diff --git a/server/server/internal/metadata/plugin-provider.ts b/server/server/internal/metadata/plugin-provider.ts
new file mode 100644
index 000000000..9b09a741b
--- /dev/null
+++ b/server/server/internal/metadata/plugin-provider.ts
@@ -0,0 +1,99 @@
+import * as jdenticon from "jdenticon";
+import type { MetadataSource } from "~/prisma/client/enums";
+import { MetadataProvider } from ".";
+import type {
+  CompanyMetadata,
+  GameMetadata,
+  GameMetadataSearchResult,
+  _FetchCompanyMetadataParams,
+  _FetchGameMetadataParams,
+} from "./types";
+import type { MetadataProvider as ExternalMetadataProvider } from "../plugins/types";
+
+export { metadataSourceForPluginId } from "./plugin-sources";
+
+/**
+ * Adapts an external `MetadataProvider` SPI implementation to the core
+ * `MetadataProvider` contract so plugin-provided sources participate in the
+ * admin search/import flow. Companies are not resolved (the SPI does not expose
+ * company entities); developers/publishers come back as tags instead.
+ */
+export class PluginMetadataProvider extends MetadataProvider {
+  constructor(
+    private readonly plugin: ExternalMetadataProvider,
+    private readonly mappedSource: MetadataSource,
+  ) {
+    super();
+  }
+
+  name(): string {
+    return this.plugin.name;
+  }
+
+  source(): MetadataSource {
+    return this.mappedSource;
+  }
+
+  async search(query: string): Promise<GameMetadataSearchResult[]> {
+    const results = await this.plugin.search(query);
+    return results.map((result) => ({
+      id: result.id,
+      name: result.title,
+      icon: result.coverUrl ?? result.iconUrl ?? "",
+      description: result.description ?? "",
+      year: result.releaseYear ?? 0,
+    }));
+  }
+
+  async fetchGame({
+    id,
+    name,
+    createObject,
+  }: _FetchGameMetadataParams): Promise<GameMetadata> {
+    const details = await this.plugin.getDetails(id);
+    if (!details) {
+      throw new Error(
+        `Plugin metadata provider '${this.plugin.id}' has no entry for '${id}'`,
+      );
+    }
+
+    const icon = createObject(
+      details.coverUrl ?? details.iconUrl ?? jdenticon.toPng(name, 512),
+    );
+
+    const tags = new Set<string>([
+      ...(details.genres ?? []),
+      ...(details.developers ?? []),
+      ...(details.publishers ?? []),
+    ]);
+
+    return {
+      id: details.id,
+      name: details.title,
+      shortDescription: details.description ?? "",
+      description: details.description ?? "",
+      released: details.releaseYear
+        ? new Date(details.releaseYear, 0, 1)
+        : new Date(),
+
+      tags: [...tags],
+
+      reviews: [],
+      ageRatings: [],
+
+      publishers: [],
+      developers: [],
+
+      icon,
+      bannerId: icon,
+      coverId: icon,
+      images: details.screenshots?.length ? details.screenshots : [icon],
+    };
+  }
+
+  async fetchCompany(
+    _params: _FetchCompanyMetadataParams,
+  ): Promise<CompanyMetadata | undefined> {
+    return undefined;
+  }
+}
diff --git a/server/server/internal/metadata/plugin-sources.ts b/server/server/internal/metadata/plugin-sources.ts
new file mode 100644
index 000000000..bd73c40d0
--- /dev/null
+++ b/server/server/internal/metadata/plugin-sources.ts
@@ -0,0 +1,20 @@
+import { MetadataSource } from "~/prisma/client/enums";
+
+/**
+ * Plugin id (from the external `MetadataProvider` SPI) to core `MetadataSource`
+ * enum. Plugins whose id is absent cannot be persisted against the strict core
+ * enum, so the registrar skips them.
+ */
+export const PLUGIN_METADATA_SOURCES: Record<string, MetadataSource> = {
+  pcgamingwiki: MetadataSource.PCGamingWiki,
+  steamgriddb: MetadataSource.SteamGridDB,
+  launchbox: MetadataSource.LaunchBox,
+  screenscraper: MetadataSource.ScreenScraper,
+  mobygames: MetadataSource.MobyGames,
+};
+
+export function metadataSourceForPluginId(
+  pluginId: string,
+): MetadataSource | undefined {
+  return PLUGIN_METADATA_SOURCES[pluginId];
+}
diff --git a/server/server/plugins/08.plugin-system.ts b/server/server/plugins/08.plugin-system.ts
index 0e4777537..dca23784a 100644
--- a/server/server/plugins/08.plugin-system.ts
+++ b/server/server/plugins/08.plugin-system.ts
@@ -1,8 +1,22 @@
 import { initPlugins, pluginManager } from "../internal/plugins";
+import metadataHandler from "../internal/metadata";
+import {
+  PluginMetadataProvider,
+  metadataSourceForPluginId,
+} from "../internal/metadata/plugin-provider";
 
 export default defineNitroPlugin(async (nitro) => {
   await initPlugins();
 
+  // Consume the external MetadataProvider SPI: register adapted plugin
+  // providers so they participate in the admin search/import flow. Plugin ids
+  // map onto the core MetadataSource enum; unmapped ids are skipped.
+  for (const provider of pluginManager.getMetadataProviders()) {
+    const source = metadataSourceForPluginId(provider.id);
+    if (!source) continue;
+    metadataHandler.addProvider(new PluginMetadataProvider(provider, source));
+  }
+
   nitro.hooks.hookOnce("close", async () => {
     const plugins = pluginManager.listPlugins();
     for (const plugin of plugins) {

From c88d4460ab0a0d5c5bd2b8cf79a8be5fb846cc13 Mon Sep 17 00:00:00 2001
From: John Smith <you@example.com>
Date: Fri, 18 Sep 2026 12:30:59 -0400
Subject: [PATCH 12/13] feat(plugins): align upstream generic SPI with
 plugin-sdk v0.7.0 contracts

- bump PLUGIN_API_VERSION to 3 and support versions 1, 2, and 3
- add PluginSettingsSchema and settings snapshot to server and client contexts
- add 'pre-launch:network-post' stage to LaunchStage and preLaunchStages pipeline
- expand ServerCapability (auth:provider, storage:depot) and ClientCapability (game:runner)
- declare RunnerProvider, AuthProvider, and DepotStorageProvider SPI types in @drop/plugin-api
- add upstream compatibility unit tests verifying SDK v0.7.0 contracts
---
 .../internal/plugins/ClientPluginManager.ts   |  1 +
 .../__tests__/client_plugin_manager.test.ts   | 82 +++++++++++++++++
 .../main/internal/plugins/launch-pipeline.ts  |  1 +
 libraries/plugin-api/src/client.ts            | 40 ++++++++
 libraries/plugin-api/src/common.ts            | 83 ++++++++++++++++-
 .../__tests__/upstream_compatibility.test.ts  | 91 +++++++++++++++++++
 server/server/internal/plugins/compat.ts      |  6 +-
 server/server/internal/plugins/context.ts     |  1 +
 server/server/internal/plugins/types.ts       | 17 +++-
 sites/docs/src/content/docs/admin/plugins.md  |  9 +-
 10 files changed, 320 insertions(+), 11 deletions(-)

diff --git a/desktop/main/internal/plugins/ClientPluginManager.ts b/desktop/main/internal/plugins/ClientPluginManager.ts
index 5fb6ce0e3..44de40acd 100644
--- a/desktop/main/internal/plugins/ClientPluginManager.ts
+++ b/desktop/main/internal/plugins/ClientPluginManager.ts
@@ -99,6 +99,7 @@ export class ClientPluginManager {
           console.debug(`[Plugin:${pluginId}] ${msg}`, ...args),
       },
       storage: new TauriPluginStorage(pluginId),
+      settings: Object.freeze({}),
       registerSlot: (slot, component, options) => {
         if (!this.slots[slot]) {
           this.slots[slot] = [];
diff --git a/desktop/main/internal/plugins/__tests__/client_plugin_manager.test.ts b/desktop/main/internal/plugins/__tests__/client_plugin_manager.test.ts
index bc0c0e8b1..3585ab7a7 100644
--- a/desktop/main/internal/plugins/__tests__/client_plugin_manager.test.ts
+++ b/desktop/main/internal/plugins/__tests__/client_plugin_manager.test.ts
@@ -1,10 +1,12 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import { ClientPluginManager } from "../ClientPluginManager";
+import { executeLaunchPipeline } from "../launch-pipeline";
 import type {
   ClientPlugin,
   ClientPluginContext,
   CloudSavePathResolver,
+  LaunchHook,
   MetadataProvider,
   StoreScanner,
 } from "../types";
@@ -207,3 +209,83 @@ test("ClientPluginManager cleans up SPI entries and slots on unregisterPlugin",
   assert.equal(manager.getStoreScanners().length, 0);
   assert.equal(manager.getMetadataProviders().length, 0);
 });
+
+test("ClientPluginContext provides frozen settings snapshot", async () => {
+  const manager = new ClientPluginManager();
+  let capturedSettings: Readonly<Record<string, unknown>> | undefined;
+
+  const pluginWithSettings: ClientPlugin = {
+    metadata: {
+      id: "settings-test",
+      name: "Settings Test",
+      version: "1.0.0",
+    },
+    init(ctx: ClientPluginContext) {
+      capturedSettings = ctx.settings;
+    },
+  };
+
+  await manager.registerPlugin(pluginWithSettings, "settings-test", [], []);
+  assert.ok(capturedSettings);
+  assert.equal(typeof capturedSettings, "object");
+  assert.equal(Object.isFrozen(capturedSettings), true);
+
+  await manager.unregisterPlugin("settings-test");
+});
+
+test("executeLaunchPipeline executes pre-launch:network-post in sequence", async () => {
+  const executionOrder: string[] = [];
+  const hooks: LaunchHook[] = [
+    {
+      stage: "pre-launch:network-post",
+      order: 10,
+      execute: async () => {
+        executionOrder.push("network-post");
+      },
+    },
+    {
+      stage: "pre-launch:network",
+      order: 0,
+      execute: async () => {
+        executionOrder.push("network");
+      },
+    },
+    {
+      stage: "pre-launch:validate",
+      order: 0,
+      execute: async () => {
+        executionOrder.push("validate");
+      },
+    },
+    {
+      stage: "post-exit:cleanup",
+      order: 0,
+      execute: async () => {
+        executionOrder.push("cleanup");
+      },
+    },
+  ];
+
+  const result = await executeLaunchPipeline(
+    hooks,
+    {
+      gameId: "test-game",
+      gameTitle: "Test Game",
+      gameDir: "/games/test",
+    },
+    async () => {
+      executionOrder.push("launch");
+      return "launched-ok";
+    },
+  );
+
+  assert.equal(result, "launched-ok");
+  assert.deepEqual(executionOrder, [
+    "validate",
+    "network",
+    "network-post",
+    "launch",
+    "cleanup",
+  ]);
+});
+
diff --git a/desktop/main/internal/plugins/launch-pipeline.ts b/desktop/main/internal/plugins/launch-pipeline.ts
index 88341edb0..e2fc167c9 100644
--- a/desktop/main/internal/plugins/launch-pipeline.ts
+++ b/desktop/main/internal/plugins/launch-pipeline.ts
@@ -81,6 +81,7 @@ export async function executeLaunchPipeline<T>(
     "pre-launch:prepare",
     "pre-launch:stage",
     "pre-launch:network",
+    "pre-launch:network-post",
   ];
 
   const postExitStages: LaunchStage[] = [
diff --git a/libraries/plugin-api/src/client.ts b/libraries/plugin-api/src/client.ts
index 8c9872e06..de36f0999 100644
--- a/libraries/plugin-api/src/client.ts
+++ b/libraries/plugin-api/src/client.ts
@@ -35,6 +35,7 @@ export type LaunchStage =
   | "pre-launch:prepare"
   | "pre-launch:stage"
   | "pre-launch:network"
+  | "pre-launch:network-post"
   | "launch"
   | "post-exit:cleanup"
   | "post-exit:restore"
@@ -145,6 +146,7 @@ export interface ClientPluginContext {
   id: string;
   logger: PluginLogger;
   storage: ClientPluginStorage;
+  settings?: Readonly<Record<string, unknown>>;
   registerSlot(
     slot: UISlotName,
     component: unknown,
@@ -172,6 +174,15 @@ export interface ClientPluginContext {
    * Requires the `cloudsave:provider` capability.
    */
   registerCloudSaveResolver?(resolver: CloudSavePathResolver): () => void;
+  /**
+   * Register a game compatibility runner provider SPI implementation.
+   * Requires the `game:runner` capability.
+   */
+  registerRunnerProvider?(provider: RunnerProvider): () => void;
+  launchGame?(gameId: string, overrides?: LaunchOverrides): Promise<void>;
+  library?: unknown;
+  ui?: unknown;
+  events?: unknown;
   gameFs: ScopedGameFs;
   gameScanner: ScopedGameScanner;
   serverWs: ClientPluginWebSocket;
@@ -272,3 +283,32 @@ export interface CloudSavePathResolver {
     gameContext: GameInstallContext,
   ): Promise<CloudSavePattern[]>;
 }
+
+// ==========================================
+// Compatibility & Runner Provider SPI (#10, #13, #18)
+// ==========================================
+
+export type RunnerPlatform =
+  | "windows"
+  | "linux"
+  | "macos"
+  | "rom"
+  | (string & {});
+
+export interface LaunchOverrides {
+  executable?: string;
+  arguments?: string[];
+  environment?: Record<string, string>;
+  workingDirectory?: string;
+  wrapperBin?: string;
+  wrapperArgs?: string[];
+}
+
+export interface RunnerProvider {
+  id: string;
+  name: string;
+  supportedPlatforms: RunnerPlatform[];
+  detect(): Promise<{ available: boolean; version?: string }>;
+  resolveLaunch(context: LaunchContext): Promise<LaunchOverrides>;
+}
+
diff --git a/libraries/plugin-api/src/common.ts b/libraries/plugin-api/src/common.ts
index 5986d170e..5426991ef 100644
--- a/libraries/plugin-api/src/common.ts
+++ b/libraries/plugin-api/src/common.ts
@@ -21,7 +21,9 @@ export type ServerCapability =
   | "network"
   | "metadata:provider"
   | "cloudsave:provider"
-  | "commerce:payment";
+  | "commerce:payment"
+  | "auth:provider"
+  | "storage:depot";
 
 export type ClientCapability =
   | "ui:slot"
@@ -38,7 +40,8 @@ export type ClientCapability =
   | "system:command"
   | "metadata:provider"
   | "cloudsave:provider"
-  | "client:library-scan";
+  | "client:library-scan"
+  | "game:runner";
 
 export type PluginCapability = ServerCapability | ClientCapability;
 
@@ -51,6 +54,32 @@ export type PluginTrust = "trusted" | "sandboxed";
 
 export type PluginStatus = "active" | "disabled" | "error" | "registered";
 
+export type PluginSettingsFieldType =
+  | "string"
+  | "password"
+  | "number"
+  | "boolean"
+  | "select";
+
+export interface PluginSettingsOption {
+  label: string;
+  value: unknown;
+}
+
+export interface PluginSettingsField {
+  key: string;
+  label: string;
+  type: PluginSettingsFieldType;
+  description?: string;
+  default?: unknown;
+  options?: PluginSettingsOption[];
+  required?: boolean;
+}
+
+export interface PluginSettingsSchema {
+  fields: PluginSettingsField[];
+}
+
 export interface PluginMetadata {
   id: string;
   name: string;
@@ -68,6 +97,8 @@ export interface PluginMetadata {
   targets?: PluginTarget[];
   capabilities?: PluginCapability[];
   enabled?: boolean;
+  /** Declarative configuration settings schema rendered automatically by host UIs. */
+  settingsSchema?: PluginSettingsSchema;
 }
 
 export interface PluginManifest extends PluginMetadata {
@@ -164,3 +195,51 @@ export interface PaymentGateway {
     headers: Record<string, string>,
   ): Promise<PaymentWebhookResult>;
 }
+
+// ==========================================
+// Authentication Provider SPI (#12)
+// ==========================================
+
+export interface AuthUser {
+  externalId: string;
+  username: string;
+  email?: string;
+  displayName?: string;
+  groups?: string[];
+}
+
+export interface AuthResult {
+  authenticated: boolean;
+  user?: AuthUser;
+  error?: string;
+  unavailable?: boolean;
+}
+
+export interface AuthProvider {
+  id: string;
+  name: string;
+  authenticate(credentials: {
+    username: string;
+    password: string;
+  }): Promise<AuthResult>;
+}
+
+// ==========================================
+// Remote Depot & Storage Provider SPI (#14, #17, #21)
+// ==========================================
+
+export interface DepotDownloadStream {
+  url?: string;
+  headers?: Record<string, string>;
+  pieceReader?: (offset: number, length: number) => Promise<Uint8Array>;
+}
+
+export interface DepotStorageProvider {
+  id: string;
+  name: string;
+  resolveDepotStream(
+    depotId: string,
+    gameId: string,
+  ): Promise<DepotDownloadStream | null>;
+}
+
diff --git a/server/server/internal/plugins/__tests__/upstream_compatibility.test.ts b/server/server/internal/plugins/__tests__/upstream_compatibility.test.ts
index d198da3a7..f565a6308 100644
--- a/server/server/internal/plugins/__tests__/upstream_compatibility.test.ts
+++ b/server/server/internal/plugins/__tests__/upstream_compatibility.test.ts
@@ -6,9 +6,13 @@ import * as path from "node:path";
 import { PluginManager } from "../manager";
 import {
   PLUGIN_API_VERSION,
+  SUPPORTED_API_VERSIONS,
   type ServerPlugin,
   type PluginContext,
+  type PluginManifest,
 } from "../types";
+import { assertManifestCompatible, assertPluginCompatible } from "../compat";
+import { PluginApiVersionError } from "../errors";
 
 function tmpDataDir(): string {
   const prefix = path.join(
@@ -179,3 +183,90 @@ test("Upstream Invariant: Plugin lifecycle isolation leaves zero residual state
     "Unregistered plugin must not receive subsequent broadcasts",
   );
 });
+
+test("Upstream Invariant: Plugin SDK v0.7.0 (apiVersion 3) and settingsSchema contracts are fully compatible", async (t) => {
+  const dataDir = tmpDataDir();
+  t.after(async () => {
+    await fs.rm(dataDir, { recursive: true, force: true });
+  });
+
+  const manager = new PluginManager({ dataDir });
+
+  // 1. Assert SUPPORTED_API_VERSIONS includes 1, 2, and 3
+  assert.deepEqual(SUPPORTED_API_VERSIONS, [1, 2, 3]);
+  assert.equal(PLUGIN_API_VERSION, 3);
+
+  // 2. Compatibility check succeeds for versions 1, 2, and 3
+  for (const v of [1, 2, 3]) {
+    const manifest: PluginManifest = {
+      id: `plugin-v${v}`,
+      name: `Plugin V${v}`,
+      version: "1.0.0",
+      apiVersion: v,
+    };
+    assert.doesNotThrow(() => assertManifestCompatible(manifest));
+
+    const plugin: ServerPlugin = {
+      metadata: manifest,
+      init: () => {},
+    };
+    assert.doesNotThrow(() => assertPluginCompatible(plugin));
+  }
+
+  // 3. Incompatible versions (0, 4) throw PluginApiVersionError
+  for (const invalidVer of [0, 4]) {
+    const invalidManifest: PluginManifest = {
+      id: "invalid-ver",
+      name: "Invalid",
+      version: "1.0.0",
+      apiVersion: invalidVer,
+    };
+    assert.throws(
+      () => assertManifestCompatible(invalidManifest),
+      PluginApiVersionError,
+    );
+  }
+
+  // 4. Register a plugin using SDK v0.7.0 features: settingsSchema, ctx.settings, extended capabilities
+  let capturedSettings: Readonly<Record<string, unknown>> | undefined;
+  const v3Plugin: ServerPlugin = {
+    metadata: {
+      id: "sdk-v3-plugin",
+      name: "SDK v3 Plugin",
+      version: "1.0.0",
+      apiVersion: 3,
+      capabilities: ["routes", "auth:provider", "storage:depot"],
+      settingsSchema: {
+        fields: [
+          {
+            key: "apiKey",
+            label: "API Key",
+            type: "password",
+            required: true,
+          },
+          {
+            key: "enableFeature",
+            label: "Enable Feature",
+            type: "boolean",
+            default: true,
+          },
+        ],
+      },
+    },
+    init: (ctx: PluginContext) => {
+      capturedSettings = ctx.settings;
+    },
+  };
+
+  await manager.registerPlugin(v3Plugin);
+  const registered = manager.getPlugin("sdk-v3-plugin");
+  assert.ok(registered);
+  assert.equal(registered.metadata.apiVersion, 3);
+  assert.equal(registered.metadata.settingsSchema?.fields.length, 2);
+  assert.ok(capturedSettings);
+  assert.equal(typeof capturedSettings, "object");
+  assert.equal(Object.isFrozen(capturedSettings), true);
+
+  await manager.unregisterPlugin("sdk-v3-plugin");
+});
+
diff --git a/server/server/internal/plugins/compat.ts b/server/server/internal/plugins/compat.ts
index f32c8812f..6293b8297 100644
--- a/server/server/internal/plugins/compat.ts
+++ b/server/server/internal/plugins/compat.ts
@@ -1,4 +1,4 @@
-import { PLUGIN_API_VERSION } from "./types";
+import { PLUGIN_API_VERSION, SUPPORTED_API_VERSIONS } from "./types";
 import { PluginApiVersionError, PluginTrustError } from "./errors";
 import type { PluginManifest, ServerPlugin } from "./types";
 
@@ -15,7 +15,7 @@ export function isValidPluginId(id: string): boolean {
  */
 export function assertManifestCompatible(manifest: PluginManifest): void {
   const version = manifest.apiVersion ?? 0;
-  if (version !== 1 && version !== PLUGIN_API_VERSION) {
+  if (!(SUPPORTED_API_VERSIONS as readonly number[]).includes(version)) {
     throw new PluginApiVersionError(manifest.id, PLUGIN_API_VERSION, version);
   }
   if (manifest.trust !== undefined && manifest.trust !== "trusted") {
@@ -59,7 +59,7 @@ export function assertPluginCompatible(plugin: ServerPlugin): void {
   const version = apiVersion ?? 0;
   // Every plugin must declare the contract version it was built against;
   // omitting it previously bypassed the compatibility gate entirely.
-  if (version !== 1 && version !== PLUGIN_API_VERSION) {
+  if (!(SUPPORTED_API_VERSIONS as readonly number[]).includes(version)) {
     throw new PluginApiVersionError(id, PLUGIN_API_VERSION, version);
   }
   if (trust !== undefined && trust !== "trusted") {
diff --git a/server/server/internal/plugins/context.ts b/server/server/internal/plugins/context.ts
index 4b4d9f794..0796be8ce 100644
--- a/server/server/internal/plugins/context.ts
+++ b/server/server/internal/plugins/context.ts
@@ -207,6 +207,7 @@ export async function createPluginContext(
     id,
     logger: pluginLogger,
     storage,
+    settings: Object.freeze({}),
     registerRoute: (method, pattern, handler) => {
       if (!hasCapability(capabilities, "routes")) {
         throw new PluginCapabilityError(
diff --git a/server/server/internal/plugins/types.ts b/server/server/internal/plugins/types.ts
index bb6fe8957..101872560 100644
--- a/server/server/internal/plugins/types.ts
+++ b/server/server/internal/plugins/types.ts
@@ -1,7 +1,9 @@
 import type { H3Event } from "h3";
 import type { Logger } from "pino";
 import type {
+  AuthProvider,
   CloudSavePathResolver,
+  DepotStorageProvider,
   HttpMethod,
   MetadataProvider,
   PaymentGateway,
@@ -21,8 +23,8 @@ export type * from "@drop/plugin-api";
  * contract changes incompatibly. Plugins declare the version they were built
  * against in `metadata.apiVersion`; mismatches are rejected at registration.
  */
-export const PLUGIN_API_VERSION = 2;
-export const SUPPORTED_API_VERSIONS = [1, 2] as const;
+export const PLUGIN_API_VERSION = 3;
+export const SUPPORTED_API_VERSIONS = [1, 2, 3] as const;
 
 export interface RouteHandlerContext {
   params: Record<string, string>;
@@ -87,6 +89,7 @@ export interface PluginContext {
   id: string;
   logger: Logger;
   storage: PluginStorage;
+  settings?: Readonly<Record<string, unknown>>;
   registerRoute(
     method: HttpMethod,
     pattern: string,
@@ -134,6 +137,16 @@ export interface PluginContext {
    * Requires the `commerce:payment` capability.
    */
   registerPaymentGateway(gateway: PaymentGateway): void;
+  /**
+   * Register an authentication provider SPI implementation.
+   * Requires the `auth:provider` capability.
+   */
+  registerAuthProvider?(provider: AuthProvider): void;
+  /**
+   * Register a remote depot storage provider SPI implementation.
+   * Requires the `storage:depot` capability.
+   */
+  registerDepotProvider?(provider: DepotStorageProvider): void;
 }
 
 export interface ServerPlugin {
diff --git a/sites/docs/src/content/docs/admin/plugins.md b/sites/docs/src/content/docs/admin/plugins.md
index b57f2a0a2..d76b4c858 100644
--- a/sites/docs/src/content/docs/admin/plugins.md
+++ b/sites/docs/src/content/docs/admin/plugins.md
@@ -37,11 +37,12 @@ A plugin lives in `<dataDir>/plugins/<id>/` and contains:
 ### `drop-plugin.json` Fields
 
 - `id`, `name`, `version` — required.
-- `apiVersion` — plugin API version (currently `2`; Drop maintains backwards compatibility with `1`).
+- `apiVersion` — plugin API version (currently `3`; Drop maintains backwards compatibility with `1` and `2`).
 - `targets` — `["server"]`, `["client"]`, or `["server", "client"]`.
 - `capabilities` — explicitly declared permissions:
-  - **Server**: `routes`, `storage`, `events`, `network`, `websocket`.
-  - **Client**: `ui:slot`, `ui:play-action`, `ui:context-menu`, `ui:sidebar`, `ui:topbar`, `game:launch-hook`, `game:fs`, `game:scan`, `client:storage`, `client:ws`.
+  - **Server**: `routes`, `storage`, `events`, `network`, `websocket`, `metadata:provider`, `cloudsave:provider`, `commerce:payment`, `auth:provider`, `storage:depot`.
+  - **Client**: `ui:slot`, `ui:play-action`, `ui:context-menu`, `ui:sidebar`, `ui:topbar`, `game:launch-hook`, `game:fs`, `game:scan`, `client:storage`, `client:ws`, `client:library-scan`, `game:runner`.
+- `settingsSchema` — optional declarative settings schema rendered automatically by host UIs.
 - `entry` — relative path to primary entry point (default `index.js`).
 - `checksum` — SHA-256 hex digest of the primary entry file.
 - `files` — mapping of relative bundle file paths to their individual SHA-256 digests. Required for multi-file bundles.
@@ -142,7 +143,7 @@ curl -X POST "$DROP_URL/api/v1/plugins/install" \
       "id": "my-plugin",
       "name": "My Plugin",
       "version": "1.0.0",
-      "apiVersion": 2,
+      "apiVersion": 3,
       "targets": ["server"],
       "capabilities": ["routes"],
       "entry": "dist/index.js",

From 809901e90178063a4c328cb1a36f29a546cca90f Mon Sep 17 00:00:00 2001
From: John Smith <you@example.com>
Date: Fri, 18 Sep 2026 20:35:47 -0400
Subject: [PATCH 13/13] feat(plugins): implement plugin-sdk 0.7.0 runtime
 parity

Server:
- Declarative settings runtime: settings.ts validator, ctx.settings load-before-init, getPluginSettingsView/setPluginSettings, and GET/PATCH /api/v1/plugins/:id/settings behind the admin ACL.
- ctx.scheduleTask with cleanup on unload.
- registerAuthProvider/registerDepotProvider SPI registration, getters, and purge-on-unregister.
- resolveRemoteDepot/readRemoteRange depot resolver + tests.

Shared contract:
- Add Sidecar/SidecarTarget and client.sidecars/server.source/client.source manifest fields to @drop/plugin-api.

Desktop:
- registerRunnerProvider + getRunnerProviders, ui.openExternal, launchGame/setGameLaunchHandler, local events bus, sidecar staging.
- Rust host commands plugin_open_external, plugin_sidecar_stage, plugin_sidecar_clear, and staged-sidecar resolution in plugin_system_run.

Tests:
- Host-side SDK conformance suite covering every ServerCapability and PluginContext member, plus settings and depot suites.

Follow-ups tracked in Heretek-Games/drop#102, #103, #104, #105.
---
 .../internal/plugins/ClientPluginManager.ts   | 192 +++++++++-
 .../__tests__/client_plugin_manager.test.ts   | 106 +++++-
 desktop/main/plugins/09.client-plugins.ts     |  14 +
 desktop/src-tauri/plugins/src/allowlist.rs    |   2 +-
 desktop/src-tauri/plugins/src/lib.rs          |   4 +-
 desktop/src-tauri/plugins/src/sidecar.rs      |  24 ++
 desktop/src-tauri/plugins/src/system.rs       |  26 +-
 desktop/src-tauri/src/lib.rs                  |   5 +
 desktop/src-tauri/src/plugin_host.rs          | 148 ++++++++
 libraries/plugin-api/src/common.ts            |  46 ++-
 .../api/v1/plugins/[pluginId]/settings.get.ts |  31 ++
 .../v1/plugins/[pluginId]/settings.patch.ts   |  37 ++
 .../plugins/__tests__/plugins.test.ts         | 231 ++++++++++++
 .../plugins/__tests__/sdk_conformance.test.ts | 334 ++++++++++++++++++
 .../plugins/__tests__/settings.test.ts        | 112 ++++++
 server/server/internal/plugins/context.ts     | 116 +++++-
 server/server/internal/plugins/index.ts       |   1 +
 server/server/internal/plugins/manager.ts     | 177 +++++++++-
 server/server/internal/plugins/settings.ts    | 246 +++++++++++++
 server/server/internal/plugins/types.ts       |   9 +
 .../services/depot/__tests__/remote.test.ts   | 123 +++++++
 .../server/internal/services/depot/remote.ts  |  93 +++++
 22 files changed, 2055 insertions(+), 22 deletions(-)
 create mode 100644 desktop/src-tauri/plugins/src/sidecar.rs
 create mode 100644 desktop/src-tauri/src/plugin_host.rs
 create mode 100644 server/server/api/v1/plugins/[pluginId]/settings.get.ts
 create mode 100644 server/server/api/v1/plugins/[pluginId]/settings.patch.ts
 create mode 100644 server/server/internal/plugins/__tests__/sdk_conformance.test.ts
 create mode 100644 server/server/internal/plugins/__tests__/settings.test.ts
 create mode 100644 server/server/internal/plugins/settings.ts
 create mode 100644 server/server/internal/services/depot/__tests__/remote.test.ts
 create mode 100644 server/server/internal/services/depot/remote.ts

diff --git a/desktop/main/internal/plugins/ClientPluginManager.ts b/desktop/main/internal/plugins/ClientPluginManager.ts
index 44de40acd..418a53fce 100644
--- a/desktop/main/internal/plugins/ClientPluginManager.ts
+++ b/desktop/main/internal/plugins/ClientPluginManager.ts
@@ -8,14 +8,43 @@ import type {
   HttpMethod,
   LaunchContext,
   LaunchHook,
+  LaunchOverrides,
   MetadataProvider,
   PlayAction,
+  RunnerProvider,
   SidebarItem,
+  Sidecar,
   StoreScanner,
   TopBarItem,
   UISlotName,
   UISlotRegistration,
 } from "./types";
+
+/** Platform data used to pick the matching sidecar target. */
+export interface SidecarPlatform {
+  os: "linux" | "macos" | "windows";
+  arch: "x64" | "arm64";
+}
+
+/**
+ * Best-effort host platform detection for sidecar target selection. Runs in
+ * the desktop webview, where Tauri provides a real UA; wrong guesses never
+ * break anything because staging is sha256-verified per target and failures
+ * fall back to PATH resolution.
+ */
+export function detectSidecarPlatform(): SidecarPlatform | null {
+  if (typeof navigator === "undefined") return null;
+  const ua = navigator.userAgent ?? "";
+  let os: SidecarPlatform["os"] | null = null;
+  if (/windows/i.test(ua)) os = "windows";
+  else if (/macintosh|mac os x/i.test(ua)) os = "macos";
+  else if (/linux/i.test(ua)) os = "linux";
+  if (!os) return null;
+  const arch: SidecarPlatform["arch"] = /aarch64|arm64|apple m[123]/i.test(ua)
+    ? "arm64"
+    : "x64";
+  return { os, arch };
+}
 import { safeInvoke } from "./host";
 import { TauriPluginStorage } from "./host/storage";
 import { TauriScopedGameFs } from "./host/game-fs";
@@ -55,11 +84,85 @@ export class ClientPluginManager {
   public readonly cloudSaveResolvers = reactive<
     Array<{ pluginId: string; resolver: CloudSavePathResolver }>
   >([]);
+  public readonly runnerProviders = reactive<
+    Array<{ pluginId: string; provider: RunnerProvider }>
+  >([]);
+
+  /**
+   * Host launch delegate wired by the library view so `ctx.launchGame` can
+   * reuse the same launch-index resolution as the Play button. Falls back to a
+   * direct native launch (index 0) when unset.
+   */
+  private gameLaunchHandler?: (
+    gameId: string,
+    overrides?: LaunchOverrides,
+  ) => Promise<void>;
+
+  /** Local (client-side) plugin event bus, keyed by event name. */
+  private readonly localEvents = new Map<
+    string,
+    Set<(data: unknown) => void>
+  >();
 
   public readonly serverWs: ClientPluginWebSocket = new TauriPluginWebSocket();
 
   public readonly isInitialized = ref(false);
 
+  /**
+   * Register the host launch delegate used by `ctx.launchGame`. The library
+   * view wires this so plugin-triggered launches resolve the same launch option
+   * index as the Play button; without it, launches fall back to index 0.
+   */
+  setGameLaunchHandler(
+    handler: (gameId: string, overrides?: LaunchOverrides) => Promise<void>,
+  ): void {
+    this.gameLaunchHandler = handler;
+  }
+
+  /**
+   * Stage the sidecar binary for the current platform that a plugin bundle
+   * declares. The Tauri command verifies the SHA-256, stages the binary under
+   * the plugin's app-data bin dir and makes it executable, so `ctx.system.run`
+   * later resolves the allowlisted bare name against it. Non-fatal: hosts
+   * without a matching target stay on PATH/fallbacks.
+   */
+  async stageSidecars(
+    pluginId: string,
+    commands: string[],
+    sidecars: Sidecar[] | undefined,
+  ): Promise<void> {
+    if (!Array.isArray(sidecars) || sidecars.length === 0) return;
+    const platform = detectSidecarPlatform();
+    if (!platform) {
+      console.debug("Unknown sidecar platform; skipping staging");
+      return;
+    }
+    const commandSet = new Set(commands);
+    for (const sidecar of sidecars) {
+      if (!commandSet.has(sidecar.name)) continue;
+      const target = sidecar.targets.find(
+        (t) => t.os === platform.os && t.arch === platform.arch,
+      );
+      if (!target) continue;
+      try {
+        await safeInvoke("plugin_sidecar_stage", {
+          pluginId,
+          name: sidecar.name,
+          asset: target.path,
+          sha256: target.sha256,
+        });
+        console.debug("Staged sidecar:", pluginId, sidecar.name);
+      } catch (err) {
+        console.warn(
+          "Failed to stage sidecar; falling back to PATH resolution:",
+          pluginId,
+          sidecar.name,
+          err,
+        );
+      }
+    }
+  }
+
   /**
    * Register and initialize a client plugin instance.
    */
@@ -68,6 +171,7 @@ export class ClientPluginManager {
     id?: string,
     commands: string[] = [],
     capabilities: string[] = [],
+    sidecars: Sidecar[] = [],
   ): Promise<void> {
     const pluginId = id || plugin.metadata?.id || "anonymous-plugin";
     if (this.plugins.has(pluginId)) {
@@ -86,6 +190,10 @@ export class ClientPluginManager {
       );
     }
 
+    // Stage declared sidecar binaries (sha256-verified) before init so
+    // `ctx.system.run` can resolve their allowlisted bare names.
+    await this.stageSidecars(pluginId, commands, sidecars);
+
     const context: ClientPluginContext = {
       id: pluginId,
       logger: {
@@ -99,7 +207,10 @@ export class ClientPluginManager {
           console.debug(`[Plugin:${pluginId}] ${msg}`, ...args),
       },
       storage: new TauriPluginStorage(pluginId),
-      settings: Object.freeze({}),
+      // Client-side declarative settings are optional; the key is always
+      // present for surface parity with the server context but stays undefined
+      // until the host injects a schema-backed snapshot.
+      settings: undefined,
       registerSlot: (slot, component, options) => {
         if (!this.slots[slot]) {
           this.slots[slot] = [];
@@ -215,6 +326,66 @@ export class ClientPluginManager {
           if (idx !== -1) this.cloudSaveResolvers.splice(idx, 1);
         };
       },
+      registerRunnerProvider: (provider: RunnerProvider) => {
+        if (capabilities.length > 0 && !capabilities.includes("game:runner")) {
+          throw new Error(
+            `Client plugin '${pluginId}' attempted 'registerRunnerProvider' without the 'game:runner' capability`,
+          );
+        }
+        if (
+          !provider ||
+          typeof provider.id !== "string" ||
+          !provider.id.trim()
+        ) {
+          throw new Error("Runner provider must have a valid non-empty id");
+        }
+        const entry = { pluginId, provider };
+        this.runnerProviders.push(entry);
+        return () => {
+          const idx = this.runnerProviders.indexOf(entry);
+          if (idx !== -1) this.runnerProviders.splice(idx, 1);
+        };
+      },
+      launchGame: async (gameId: string, overrides?: LaunchOverrides) => {
+        if (this.gameLaunchHandler) {
+          await this.gameLaunchHandler(gameId, overrides);
+          return;
+        }
+        // Best-effort fallback: launch option 0. The library view wires
+        // `setGameLaunchHandler` so launch index + overrides resolve correctly.
+        await safeInvoke("launch_game", { id: gameId, index: 0 });
+      },
+      ui: {
+        openExternal: (url: string) =>
+          safeInvoke("plugin_open_external", { url }),
+      },
+      events: {
+        on: (event: string, listener: (data: unknown) => void) => {
+          let listeners = this.localEvents.get(event);
+          if (!listeners) {
+            listeners = new Set();
+            this.localEvents.set(event, listeners);
+          }
+          listeners.add(listener);
+          return () => {
+            const current = this.localEvents.get(event);
+            if (!current) return;
+            current.delete(listener);
+            if (current.size === 0) this.localEvents.delete(event);
+          };
+        },
+        emit: (event: string, data: unknown) => {
+          const listeners = this.localEvents.get(event);
+          if (!listeners) return;
+          for (const listener of [...listeners]) {
+            try {
+              listener(data);
+            } catch (err) {
+              console.error(`Plugin event listener for '${event}' threw:`, err);
+            }
+          }
+        },
+      },
       gameFs: new TauriScopedGameFs(),
       gameScanner: new TauriScopedGameScanner(),
       serverWs: this.serverWs,
@@ -258,6 +429,11 @@ export class ClientPluginManager {
       // Best effort: the plugin may never have registered a allowlist.
     });
 
+    // Drop any staged sidecar binaries for this plugin.
+    await safeInvoke("plugin_sidecar_clear", { pluginId }).catch(() => {
+      // Best effort: the plugin may never have staged a sidecar.
+    });
+
     // Clean up UI slots registered by this plugin
     for (const slotName of Object.keys(this.slots) as UISlotName[]) {
       this.slots[slotName] = this.slots[slotName].filter(
@@ -269,6 +445,7 @@ export class ClientPluginManager {
     this.purgeOwned(this.storeScanners, pluginId);
     this.purgeOwned(this.metadataProviders, pluginId);
     this.purgeOwned(this.cloudSaveResolvers, pluginId);
+    this.purgeOwned(this.runnerProviders, pluginId);
   }
 
   /** Removes every reactive entry owned by `pluginId` from `entries`. */
@@ -296,6 +473,10 @@ export class ClientPluginManager {
     return this.cloudSaveResolvers.map((e) => e.resolver);
   }
 
+  getRunnerProviders(): RunnerProvider[] {
+    return this.runnerProviders.map((e) => e.provider);
+  }
+
   /**
    * Load client plugin bundle from a URL (e.g. served by Drop server).
    */
@@ -305,6 +486,7 @@ export class ClientPluginManager {
     cssUrl?: string,
     commands: string[] = [],
     capabilities: string[] = [],
+    sidecars: Sidecar[] = [],
   ): Promise<void> {
     if (cssUrl) {
       const link = document.createElement("link");
@@ -327,7 +509,13 @@ export class ClientPluginManager {
       );
     }
 
-    await this.registerPlugin(pluginExport, pluginId, commands, capabilities);
+    await this.registerPlugin(
+      pluginExport,
+      pluginId,
+      commands,
+      capabilities,
+      sidecars,
+    );
   }
 
   /**
diff --git a/desktop/main/internal/plugins/__tests__/client_plugin_manager.test.ts b/desktop/main/internal/plugins/__tests__/client_plugin_manager.test.ts
index 3585ab7a7..b35959dfe 100644
--- a/desktop/main/internal/plugins/__tests__/client_plugin_manager.test.ts
+++ b/desktop/main/internal/plugins/__tests__/client_plugin_manager.test.ts
@@ -8,6 +8,7 @@ import type {
   CloudSavePathResolver,
   LaunchHook,
   MetadataProvider,
+  RunnerProvider,
   StoreScanner,
 } from "../types";
 
@@ -210,9 +211,9 @@ test("ClientPluginManager cleans up SPI entries and slots on unregisterPlugin",
   assert.equal(manager.getMetadataProviders().length, 0);
 });
 
-test("ClientPluginContext provides frozen settings snapshot", async () => {
+test("ClientPluginContext exposes settings for surface parity", async () => {
   const manager = new ClientPluginManager();
-  let capturedSettings: Readonly<Record<string, unknown>> | undefined;
+  let captured: ClientPluginContext | undefined;
 
   const pluginWithSettings: ClientPlugin = {
     metadata: {
@@ -221,18 +222,110 @@ test("ClientPluginContext provides frozen settings snapshot", async () => {
       version: "1.0.0",
     },
     init(ctx: ClientPluginContext) {
-      capturedSettings = ctx.settings;
+      captured = ctx;
     },
   };
 
   await manager.registerPlugin(pluginWithSettings, "settings-test", [], []);
-  assert.ok(capturedSettings);
-  assert.equal(typeof capturedSettings, "object");
-  assert.equal(Object.isFrozen(capturedSettings), true);
+  assert.ok(captured);
+  // The key is always present for parity with the server context; the value is
+  // undefined until the host injects a schema-backed snapshot.
+  assert.ok(Object.hasOwn(captured as ClientPluginContext, "settings"));
+  assert.equal(captured.settings, undefined);
 
   await manager.unregisterPlugin("settings-test");
 });
 
+test("ClientPluginManager registers and gates RunnerProvider SPI", async () => {
+  const manager = new ClientPluginManager();
+
+  const runner: RunnerProvider = {
+    id: "proton-runner",
+    name: "Proton",
+    supportedPlatforms: ["windows"],
+    detect: async () => ({ available: true, version: "9.0" }),
+    resolveLaunch: async () => ({ wrapperBin: "proton", wrapperArgs: ["run"] }),
+  };
+
+  const plugin: ClientPlugin = {
+    metadata: { id: "runner-plugin", name: "Runner", version: "1.0.0" },
+    init(ctx: ClientPluginContext) {
+      ctx.registerRunnerProvider?.(runner);
+    },
+  };
+
+  await manager.registerPlugin(plugin, "runner-plugin", [], ["game:runner"]);
+  assert.equal(manager.getRunnerProviders().length, 1);
+  assert.equal(manager.getRunnerProviders()[0]?.name, "Proton");
+
+  // Missing capability fails closed (init errors are swallowed, so the
+  // provider must simply not be registered).
+  const denied: ClientPlugin = {
+    metadata: { id: "runner-denied", name: "Denied", version: "1.0.0" },
+    init(ctx: ClientPluginContext) {
+      ctx.registerRunnerProvider?.({
+        id: "denied",
+        name: "Denied",
+        supportedPlatforms: ["linux"],
+        detect: async () => ({ available: false }),
+        resolveLaunch: async () => ({}),
+      });
+    },
+  };
+  await manager.registerPlugin(denied, "runner-denied", [], ["ui:slot"]);
+  assert.equal(manager.getRunnerProviders().length, 1);
+
+  await manager.unregisterPlugin("runner-plugin");
+  assert.equal(manager.getRunnerProviders().length, 0);
+});
+
+test("ClientPluginContext exposes the SDK client surface", async () => {
+  const manager = new ClientPluginManager();
+  let captured: ClientPluginContext | undefined;
+
+  const plugin: ClientPlugin = {
+    metadata: { id: "surface", name: "Surface", version: "1.0.0" },
+    init(ctx: ClientPluginContext) {
+      captured = ctx;
+    },
+  };
+
+  await manager.registerPlugin(plugin, "surface", [], []);
+  assert.ok(captured);
+  const members = [
+    "id",
+    "logger",
+    "storage",
+    "settings",
+    "registerSlot",
+    "registerPlayAction",
+    "registerGameMenuItem",
+    "registerSidebarItem",
+    "registerTopBarItem",
+    "registerLaunchHook",
+    "registerStoreScanner",
+    "registerMetadataProvider",
+    "registerCloudSaveResolver",
+    "registerRunnerProvider",
+    "launchGame",
+    "ui",
+    "events",
+    "gameFs",
+    "gameScanner",
+    "serverWs",
+    "system",
+    "serverRequest",
+  ] as const;
+  for (const member of members) {
+    assert.ok(
+      Object.hasOwn(captured as ClientPluginContext, member),
+      `ClientPluginContext is missing '${member}'`,
+    );
+  }
+
+  await manager.unregisterPlugin("surface");
+});
+
 test("executeLaunchPipeline executes pre-launch:network-post in sequence", async () => {
   const executionOrder: string[] = [];
   const hooks: LaunchHook[] = [
@@ -288,4 +381,3 @@ test("executeLaunchPipeline executes pre-launch:network-post in sequence", async
     "cleanup",
   ]);
 });
-
diff --git a/desktop/main/plugins/09.client-plugins.ts b/desktop/main/plugins/09.client-plugins.ts
index 4f9222899..46ffc0b45 100644
--- a/desktop/main/plugins/09.client-plugins.ts
+++ b/desktop/main/plugins/09.client-plugins.ts
@@ -22,6 +22,15 @@ interface RemotePluginInfo {
     entry?: string;
     css?: string;
     commands?: string[];
+    sidecars?: Array<{
+      name: string;
+      targets: Array<{
+        os: "linux" | "macos" | "windows";
+        arch: "x64" | "arm64";
+        path: string;
+        sha256: string;
+      }>;
+    }>;
   };
 }
 
@@ -38,6 +47,9 @@ async function loadRemotePlugin(plugin: RemotePluginInfo): Promise<void> {
   const commands = Array.isArray(plugin.client?.commands)
     ? plugin.client.commands
     : [];
+  const sidecars = Array.isArray(plugin.client?.sidecars)
+    ? plugin.client.sidecars
+    : [];
 
   try {
     await clientPluginManager.loadFromUrl(
@@ -45,6 +57,8 @@ async function loadRemotePlugin(plugin: RemotePluginInfo): Promise<void> {
       clientJsUrl,
       clientCssUrl,
       commands,
+      [],
+      sidecars,
     );
   } catch (loadErr) {
     console.debug(
diff --git a/desktop/src-tauri/plugins/src/allowlist.rs b/desktop/src-tauri/plugins/src/allowlist.rs
index ac3e56484..91c8b4c14 100644
--- a/desktop/src-tauri/plugins/src/allowlist.rs
+++ b/desktop/src-tauri/plugins/src/allowlist.rs
@@ -30,7 +30,7 @@ pub struct PluginCommandAllowlist(pub Mutex<HashMap<String, HashSet<String>>>);
 /// Only bare executable names are allowed (no path separators, no leading `.`
 /// or `-`, ASCII alphanumerics plus `_`, `-`, `.`). This is a syntax check,
 /// not a trust decision: trust comes from the per-plugin allowlist itself.
-pub(crate) fn validate_command_name(command: &str) -> Result<(), String> {
+pub fn validate_command_name(command: &str) -> Result<(), String> {
     if command.is_empty() || command.len() > 64 {
         return Err(format!("invalid command length: '{command}'"));
     }
diff --git a/desktop/src-tauri/plugins/src/lib.rs b/desktop/src-tauri/plugins/src/lib.rs
index 27fbbd1dc..ff4eb7729 100644
--- a/desktop/src-tauri/plugins/src/lib.rs
+++ b/desktop/src-tauri/plugins/src/lib.rs
@@ -2,10 +2,12 @@ mod allowlist;
 mod game_fs;
 pub mod path_guard;
 mod scanner;
+mod sidecar;
 mod storage;
 mod system;
 
-pub use allowlist::PluginCommandAllowlist;
+pub use allowlist::{PluginCommandAllowlist, validate_command_name};
+pub use sidecar::plugin_sidecar_bin_dir;
 pub use game_fs::{
     plugin_game_fs_backup, plugin_game_fs_delete, plugin_game_fs_exists, plugin_game_fs_read,
     plugin_game_fs_restore, plugin_game_fs_write,
diff --git a/desktop/src-tauri/plugins/src/sidecar.rs b/desktop/src-tauri/plugins/src/sidecar.rs
new file mode 100644
index 000000000..40f810d00
--- /dev/null
+++ b/desktop/src-tauri/plugins/src/sidecar.rs
@@ -0,0 +1,24 @@
+use std::path::PathBuf;
+
+use tauri::{AppHandle, Manager};
+
+/// App-data bin directory where the host stages a plugin's declared sidecar
+/// binaries. `crate::plugin_system_run` resolves allowlisted bare names against
+/// this directory when the binary is not found on the inherited `PATH`.
+///
+/// Returns `None` for plugin ids that are not a single safe path segment so a
+/// plugin can never be used to traverse outside its own staging directory.
+pub fn plugin_sidecar_bin_dir(app: &AppHandle, plugin_id: &str) -> Option<PathBuf> {
+    if plugin_id.is_empty()
+        || plugin_id.len() > 64
+        || !plugin_id
+            .chars()
+            .all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_')
+    {
+        return None;
+    }
+    app.path()
+        .app_data_dir()
+        .ok()
+        .map(|root| root.join("plugins").join(plugin_id).join("bin"))
+}
diff --git a/desktop/src-tauri/plugins/src/system.rs b/desktop/src-tauri/plugins/src/system.rs
index 5af2ed492..09c0d392d 100644
--- a/desktop/src-tauri/plugins/src/system.rs
+++ b/desktop/src-tauri/plugins/src/system.rs
@@ -1,10 +1,13 @@
+use std::fs;
+use std::path::PathBuf;
 use std::time::Duration;
 
 use serde::{Deserialize, Serialize};
-use tauri::State;
+use tauri::{AppHandle, State};
 use tokio::process::Command as TokioCommand;
 
 use crate::allowlist::{PluginCommandAllowlist, validate_command_name};
+use crate::sidecar::plugin_sidecar_bin_dir;
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
@@ -64,6 +67,7 @@ pub fn plugin_register_commands(
 /// rely on a blocklist to contain a malicious plugin; there is none by design.
 #[tauri::command]
 pub async fn plugin_system_run(
+    app: AppHandle,
     plugin_id: String,
     bin: String,
     args: Option<Vec<String>>,
@@ -88,7 +92,25 @@ pub async fn plugin_system_run(
         }
     }
 
-    let mut command = TokioCommand::new(&bin);
+    // Prefer a staged sidecar binary (sha256-verified when it was staged) when
+    // the allowlisted name matches one. The staged tree is checked to be a
+    // regular, non-symlink file; otherwise fall back to PATH resolution.
+    let mut executable = PathBuf::from(&bin);
+    if let Some(dir) = plugin_sidecar_bin_dir(&app, &plugin_id) {
+        let candidate = dir.join(if cfg!(windows) {
+            format!("{bin}.exe")
+        } else {
+            bin.clone()
+        });
+        let is_regular = fs::symlink_metadata(&candidate)
+            .map(|meta| meta.is_file() && !meta.is_symlink())
+            .unwrap_or(false);
+        if is_regular {
+            executable = candidate;
+        }
+    }
+
+    let mut command = TokioCommand::new(&executable);
     command
         .args(args.unwrap_or_default())
         .stdin(std::process::Stdio::null())
diff --git a/desktop/src-tauri/src/lib.rs b/desktop/src-tauri/src/lib.rs
index acbb582b4..8b456ef47 100644
--- a/desktop/src-tauri/src/lib.rs
+++ b/desktop/src-tauri/src/lib.rs
@@ -64,6 +64,7 @@ mod collections;
 mod download_manager;
 mod downloads;
 mod games;
+mod plugin_host;
 mod process;
 mod remote;
 mod scheduler;
@@ -74,6 +75,7 @@ use client::*;
 use download_manager::*;
 use downloads::*;
 use games::*;
+use plugin_host::*;
 use plugins::*;
 use process::*;
 use remote::*;
@@ -265,6 +267,9 @@ pub fn run() {
             plugin_storage_set,
             plugin_storage_delete,
             plugin_storage_list_keys,
+            plugin_sidecar_stage,
+            plugin_sidecar_clear,
+            plugin_open_external,
             // Library
             fetch_library,
             fetch_game,
diff --git a/desktop/src-tauri/src/plugin_host.rs b/desktop/src-tauri/src/plugin_host.rs
new file mode 100644
index 000000000..96550d808
--- /dev/null
+++ b/desktop/src-tauri/src/plugin_host.rs
@@ -0,0 +1,148 @@
+//! Server-backed host commands that back the client plugin UI/system surfaces.
+//!
+//! These live in the main crate (rather than the `plugins` crate) because they
+//! need the authenticated HTTP client and URL builder owned by `remote`, while
+//! the `plugins` crate owns the per-plugin allowlist and staging directory.
+
+use std::fs;
+use std::path::PathBuf;
+
+use plugins::{PluginCommandAllowlist, plugin_sidecar_bin_dir, validate_command_name};
+use remote::auth::generate_authorization_header;
+use remote::requests::generate_url;
+use remote::utils::DROP_CLIENT_ASYNC;
+use sha2::{Digest, Sha256};
+use tauri::{AppHandle, State};
+
+/// Fetch a client plugin's declared sidecar binary from the Drop server,
+/// verify its SHA-256 and stage it into the plugin's app-data bin directory.
+///
+/// The bundle was checksummed by the server's plugin manager at install time;
+/// this command re-verifies transit before any bytes are used, so
+/// `plugin_system_run` can execute the staged binary by its allowlisted bare
+/// name. The staged file name must itself be an allowlisted bare executable
+/// name, so a plugin can never swap an allowlisted resolution onto another
+/// binary.
+#[tauri::command]
+pub async fn plugin_sidecar_stage(
+    app: AppHandle,
+    plugin_id: String,
+    name: String,
+    asset: String,
+    sha256: String,
+    state: State<'_, PluginCommandAllowlist>,
+) -> Result<PathBuf, String> {
+    validate_command_name(&name)?;
+    {
+        let registry = state
+            .0
+            .lock()
+            .map_err(|_| "plugin command registry poisoned".to_string())?;
+        let allowed = registry
+            .get(&plugin_id)
+            .map(|set| set.contains(&name))
+            .unwrap_or(false);
+        if !allowed {
+            return Err(format!(
+                "sidecar '{name}' is not allowlisted for plugin '{plugin_id}'"
+            ));
+        }
+    }
+
+    if !sha256.chars().all(|c| c.is_ascii_hexdigit()) || sha256.len() != 64 {
+        return Err(format!("invalid sha256 parameter: '{sha256}'"));
+    }
+    let asset = asset.trim_start_matches('/').trim_matches('/').to_string();
+    if asset.is_empty()
+        || asset.split('/').any(|part| {
+            part.is_empty() || part == "." || part == ".." || part.starts_with('.')
+        })
+    {
+        return Err(format!("invalid sidecar asset path: '{asset}'"));
+    }
+
+    let bin_dir = plugin_sidecar_bin_dir(&app, &plugin_id)
+        .ok_or_else(|| format!("invalid plugin id '{plugin_id}'"))?;
+    let url = generate_url(&["/api/v1/plugins", &plugin_id, "client", &asset], &[])
+        .map_err(|err| format!("failed to build sidecar URL: {err:?}"))?;
+
+    let response = DROP_CLIENT_ASYNC
+        .get(url.to_string())
+        .header("Authorization", generate_authorization_header())
+        .send()
+        .await
+        .map_err(|err| format!("failed to fetch sidecar '{name}': {err}"))?;
+    let status = response.status();
+    if !status.is_success() {
+        return Err(format!(
+            "sidecar fetch for '{name}' failed with status {status}"
+        ));
+    }
+    let bytes = response
+        .bytes()
+        .await
+        .map_err(|err| format!("failed to read sidecar '{name}': {err}"))?;
+
+    let mut hasher = Sha256::new();
+    hasher.update(&bytes);
+    let digest = format!("{:x}", hasher.finalize());
+    if !digest.eq_ignore_ascii_case(&sha256) {
+        fs::remove_dir_all(&bin_dir).ok();
+        return Err(format!(
+            "sidecar '{name}' sha256 mismatch: expected {sha256}, got {digest}"
+        ));
+    }
+
+    fs::create_dir_all(&bin_dir).map_err(|err| err.to_string())?;
+    let staged = bin_dir.join(if cfg!(windows) {
+        format!("{name}.exe")
+    } else {
+        name.clone()
+    });
+    // Never resolve or stage through symlinks: the staged tree stays plain.
+    if fs::symlink_metadata(&staged)
+        .map(|meta| meta.is_symlink())
+        .unwrap_or(false)
+    {
+        fs::remove_file(&staged).map_err(|err| err.to_string())?;
+    }
+    let tmp = bin_dir.join(format!("{name}.staging-{}", std::process::id()));
+    fs::write(&tmp, &bytes).map_err(|err| err.to_string())?;
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        fs::set_permissions(&tmp, fs::Permissions::from_mode(0o755))
+            .map_err(|err| err.to_string())?;
+    }
+    fs::rename(&tmp, &staged).map_err(|err| err.to_string())?;
+
+    Ok(staged)
+}
+
+/// Remove all staged sidecar binaries for a plugin (used at uninstall).
+#[tauri::command]
+pub fn plugin_sidecar_clear(app: AppHandle, plugin_id: String) -> Result<(), String> {
+    let Some(bin_dir) = plugin_sidecar_bin_dir(&app, &plugin_id) else {
+        return Ok(());
+    };
+    if bin_dir.exists() {
+        fs::remove_dir_all(&bin_dir).map_err(|err| err.to_string())?;
+    }
+    Ok(())
+}
+
+/// Open an external URL in the user's default browser on behalf of a client
+/// plugin (`ctx.ui.openExternal`). Restricted to http(s) so a plugin cannot
+/// launch arbitrary local protocol handlers.
+#[tauri::command]
+pub fn plugin_open_external(app: AppHandle, url: String) -> Result<(), String> {
+    let parsed = url::Url::parse(&url).map_err(|err| err.to_string())?;
+    if !matches!(parsed.scheme(), "http" | "https") {
+        return Err(format!("refusing to open non-http(s) URL: {url}"));
+    }
+
+    use tauri_plugin_opener::OpenerExt;
+    app.opener()
+        .open_url(parsed.as_str(), None::<&str>)
+        .map_err(|err| err.to_string())
+}
diff --git a/libraries/plugin-api/src/common.ts b/libraries/plugin-api/src/common.ts
index 5426991ef..d1e26498e 100644
--- a/libraries/plugin-api/src/common.ts
+++ b/libraries/plugin-api/src/common.ts
@@ -55,11 +55,7 @@ export type PluginTrust = "trusted" | "sandboxed";
 export type PluginStatus = "active" | "disabled" | "error" | "registered";
 
 export type PluginSettingsFieldType =
-  | "string"
-  | "password"
-  | "number"
-  | "boolean"
-  | "select";
+  "string" | "password" | "number" | "boolean" | "select";
 
 export interface PluginSettingsOption {
   label: string;
@@ -103,6 +99,12 @@ export interface PluginMetadata {
 
 export interface PluginManifest extends PluginMetadata {
   entry?: string;
+  /**
+   * Legacy alias for `client.entry`. Drop Desktop reads `client.entry`
+   * (defaulting to `bundle.js`) and never consults this field, so new
+   * manifests should declare the client entry inside the `client` block.
+   */
+  clientEntry?: string;
   /** SHA-256 of the entry file, hex. Verified before the bundle is imported. */
   checksum?: string;
   /**
@@ -128,11 +130,15 @@ export interface PluginManifest extends PluginMetadata {
 
   server?: {
     entry: string;
+    /** TypeScript/JavaScript source the CLI bundles into `entry`. */
+    source?: string;
     capabilities: ServerCapability[];
     storageVersion?: number;
   };
   client?: {
     entry: string;
+    /** TypeScript/JavaScript source the CLI bundles into `entry`. */
+    source?: string;
     css?: string;
     capabilities: ClientCapability[];
     slots?: Array<{ slot: string; component: string }>;
@@ -141,9 +147,38 @@ export interface PluginManifest extends PluginMetadata {
      * (requires the `system:command` capability). Enforced by the desktop host.
      */
     commands?: string[];
+    /**
+     * Native sidecar binaries shipped inside the plugin bundle and staged by
+     * the desktop host at activation time (requires the `system:sidecar`
+     * capability). Each declared sidecar `name` must also appear in `commands`;
+     * the host stages the target whose `os`/`arch` match the current platform,
+     * verifies `sha256`, and resolves the allowlisted bare name against the
+     * staged binary.
+     */
+    sidecars?: Sidecar[];
   };
 }
 
+/** One declared native sidecar executable bundled with the client plugin. */
+export interface Sidecar {
+  /** Bare executable name; must also be listed in `client.commands`. */
+  name: string;
+  /** Per-platform (and per-architecture) binaries for this sidecar. */
+  targets: SidecarTarget[];
+}
+
+/** A platform-specific sidecar binary declared inside the plugin bundle. */
+export interface SidecarTarget {
+  /** Target operating system. */
+  os: "linux" | "macos" | "windows";
+  /** Target CPU architecture. */
+  arch: "x64" | "arm64";
+  /** Bundle-relative path to the binary (POSIX separators). */
+  path: string;
+  /** SHA-256 hex digest of the binary contents, verified by build, validate, and the hosts. */
+  sha256: string;
+}
+
 export interface PluginStateRecord {
   enabled: boolean;
   updatedAt: number;
@@ -242,4 +277,3 @@ export interface DepotStorageProvider {
     gameId: string,
   ): Promise<DepotDownloadStream | null>;
 }
-
diff --git a/server/server/api/v1/plugins/[pluginId]/settings.get.ts b/server/server/api/v1/plugins/[pluginId]/settings.get.ts
new file mode 100644
index 000000000..8a1cea3ae
--- /dev/null
+++ b/server/server/api/v1/plugins/[pluginId]/settings.get.ts
@@ -0,0 +1,31 @@
+import { getRouterParam, createError } from "h3";
+import aclManager from "~/server/internal/acls";
+import pluginManager from "~/server/internal/plugins";
+
+export default defineEventHandler(async (event) => {
+  const allowed = await aclManager.allowSystemACL(event, []);
+  if (!allowed) {
+    throw createError({
+      statusCode: 403,
+      statusMessage: "Admin privileges required to manage plugins",
+    });
+  }
+
+  const pluginId = getRouterParam(event, "pluginId");
+  if (!pluginId) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: "Missing pluginId parameter",
+    });
+  }
+
+  const settings = await pluginManager.getPluginSettingsView(pluginId);
+  if (!settings) {
+    throw createError({
+      statusCode: 404,
+      statusMessage: `Plugin '${pluginId}' does not declare a settingsSchema`,
+    });
+  }
+
+  return settings;
+});
diff --git a/server/server/api/v1/plugins/[pluginId]/settings.patch.ts b/server/server/api/v1/plugins/[pluginId]/settings.patch.ts
new file mode 100644
index 000000000..9ead4fc8e
--- /dev/null
+++ b/server/server/api/v1/plugins/[pluginId]/settings.patch.ts
@@ -0,0 +1,37 @@
+import { getRouterParam, readBody, createError } from "h3";
+import aclManager from "~/server/internal/acls";
+import pluginManager from "~/server/internal/plugins";
+
+export default defineEventHandler(async (event) => {
+  const allowed = await aclManager.allowSystemACL(event, []);
+  if (!allowed) {
+    throw createError({
+      statusCode: 403,
+      statusMessage: "Admin privileges required to manage plugins",
+    });
+  }
+
+  const pluginId = getRouterParam(event, "pluginId");
+  if (!pluginId) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: "Missing pluginId parameter",
+    });
+  }
+
+  const body = await readBody<{ values?: unknown }>(event);
+  if (
+    !body ||
+    typeof body.values !== "object" ||
+    body.values === null ||
+    Array.isArray(body.values)
+  ) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: "Field 'values' (object) is required in request body",
+    });
+  }
+
+  const settings = await pluginManager.setPluginSettings(pluginId, body.values);
+  return { success: true, ...settings };
+});
diff --git a/server/server/internal/plugins/__tests__/plugins.test.ts b/server/server/internal/plugins/__tests__/plugins.test.ts
index dcbb440c3..a3a1c3026 100644
--- a/server/server/internal/plugins/__tests__/plugins.test.ts
+++ b/server/server/internal/plugins/__tests__/plugins.test.ts
@@ -1784,3 +1784,234 @@ test("plugin route patterns keep regex metacharacters literal", async () => {
 
   await manager.unregisterPlugin("regex-plugin");
 });
+
+test("PluginManager registers and gates AuthProvider, DepotStorageProvider, and scheduled tasks", async () => {
+  const manager = createTestManager();
+
+  let unregisterTask: (() => void) | undefined;
+  let taskRuns = 0;
+
+  const authPlugin: ServerPlugin = {
+    metadata: {
+      id: "ldap-auth",
+      name: "LDAP Auth",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      capabilities: ["auth:provider", "storage:depot"],
+    },
+    init: (ctx: PluginContext) => {
+      ctx.registerAuthProvider?.({
+        id: "ldap",
+        name: "LDAP",
+        authenticate: async (credentials) => ({
+          authenticated: credentials.username === "admin",
+          user: { externalId: "u1", username: credentials.username },
+        }),
+      });
+      ctx.registerDepotProvider?.({
+        id: "seedbox",
+        name: "Seedbox",
+        resolveDepotStream: async (depotId) => ({
+          url: `https://seed.example/${depotId}`,
+        }),
+      });
+      unregisterTask = ctx.scheduleTask?.("sync", 60_000, () => {
+        taskRuns += 1;
+      });
+    },
+  };
+
+  await manager.registerPlugin(authPlugin);
+
+  assert.equal(manager.getAuthProviders().length, 1);
+  assert.equal(manager.getAuthProvider("ldap")?.name, "LDAP");
+  const authResult = await manager
+    .getAuthProvider("ldap")!
+    .authenticate({ username: "admin", password: "secret" });
+  assert.equal(authResult.authenticated, true);
+
+  assert.equal(manager.getDepotProviders().length, 1);
+  assert.equal(manager.getDepotProvider("seedbox")?.name, "Seedbox");
+  const stream = await manager
+    .getDepotProvider("seedbox")!
+    .resolveDepotStream("depot-1", "game-1");
+  assert.equal(stream?.url, "https://seed.example/depot-1");
+
+  // The scheduleTask unregister callback stops the task before it ever fires.
+  assert.ok(unregisterTask);
+  unregisterTask();
+  assert.equal(taskRuns, 0);
+
+  // Capability gating fails closed for both new SPIs.
+  const deniedAuthPlugin: ServerPlugin = {
+    metadata: {
+      id: "denied-auth",
+      name: "Denied Auth",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      capabilities: ["routes"],
+    },
+    init: (ctx: PluginContext) => {
+      ctx.registerAuthProvider?.({
+        id: "denied",
+        name: "Denied",
+        authenticate: async () => ({ authenticated: false }),
+      });
+    },
+  };
+  await assert.rejects(
+    () => manager.registerPlugin(deniedAuthPlugin),
+    /attempted 'registerAuthProvider\(denied\)' without the 'auth:provider' capability/,
+  );
+
+  const deniedDepotPlugin: ServerPlugin = {
+    metadata: {
+      id: "denied-depot",
+      name: "Denied Depot",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      capabilities: ["routes"],
+    },
+    init: (ctx: PluginContext) => {
+      ctx.registerDepotProvider?.({
+        id: "denied",
+        name: "Denied",
+        resolveDepotStream: async () => null,
+      });
+    },
+  };
+  await assert.rejects(
+    () => manager.registerPlugin(deniedDepotPlugin),
+    /attempted 'registerDepotProvider\(denied\)' without the 'storage:depot' capability/,
+  );
+
+  // Unregister cleans up auth/depot entries.
+  await manager.unregisterPlugin("ldap-auth");
+  assert.equal(manager.getAuthProviders().length, 0);
+  assert.equal(manager.getAuthProvider("ldap"), undefined);
+  assert.equal(manager.getDepotProviders().length, 0);
+  assert.equal(manager.getDepotProvider("seedbox"), undefined);
+});
+
+test("PluginManager renders, persists, and redacts declarative settings", async () => {
+  const manager = createTestManager();
+
+  let capturedSettings: Record<string, unknown> | undefined;
+  const plugin: ServerPlugin = {
+    metadata: {
+      id: "settings-plugin",
+      name: "Settings",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      capabilities: ["storage"],
+      settingsSchema: {
+        fields: [
+          { key: "apiKey", label: "API Key", type: "password", required: true },
+          { key: "retries", label: "Retries", type: "number", default: 3 },
+          { key: "enabled", label: "Enabled", type: "boolean", default: true },
+          {
+            key: "mode",
+            label: "Mode",
+            type: "select",
+            default: "fast",
+            options: [
+              { label: "Fast", value: "fast" },
+              { label: "Safe", value: "safe" },
+            ],
+          },
+        ],
+      },
+    },
+    init: (ctx) => {
+      capturedSettings = ctx.settings as Record<string, unknown>;
+    },
+  };
+
+  await manager.registerPlugin(plugin);
+
+  // Defaults are loaded into the plugin context before init.
+  assert.deepEqual(capturedSettings, {
+    retries: 3,
+    enabled: true,
+    mode: "fast",
+  });
+
+  // The API view hides the secret but reports whether one is set.
+  const view = await manager.getPluginSettingsView("settings-plugin");
+  assert.ok(view);
+  assert.equal(view.values.apiKey, undefined);
+  assert.equal(view.secrets.apiKey, false);
+  assert.equal(view.values.retries, 3);
+
+  // `required` is enforced.
+  await assert.rejects(
+    () => manager.setPluginSettings("settings-plugin", { retries: 5 }),
+    /Setting 'apiKey' is required/,
+  );
+
+  // Type + unknown-key validation fails closed.
+  await assert.rejects(
+    () =>
+      manager.setPluginSettings("settings-plugin", {
+        apiKey: "k",
+        retries: "nope",
+      }),
+    /must be a finite number/,
+  );
+  await assert.rejects(
+    () =>
+      manager.setPluginSettings("settings-plugin", { apiKey: "k", nope: 1 }),
+    /Unknown setting 'nope'/,
+  );
+  await assert.rejects(
+    () =>
+      manager.setPluginSettings("settings-plugin", {
+        apiKey: "k",
+        mode: "turbo",
+      }),
+    /must be one of the declared options/,
+  );
+
+  // A valid update persists; the internal read exposes the secret.
+  await manager.setPluginSettings("settings-plugin", {
+    apiKey: "top-secret",
+    mode: "safe",
+  });
+  assert.equal(
+    (await manager.getPluginSettings("settings-plugin")).apiKey,
+    "top-secret",
+  );
+
+  const after = await manager.getPluginSettingsView("settings-plugin");
+  assert.equal(after?.values.mode, "safe");
+  assert.equal(after?.secrets.apiKey, true);
+  assert.equal(after?.values.apiKey, undefined);
+
+  // Omitting a secret keeps it; clearing it re-triggers `required`.
+  await manager.setPluginSettings("settings-plugin", { retries: 9 });
+  assert.equal(
+    (await manager.getPluginSettings("settings-plugin")).apiKey,
+    "top-secret",
+  );
+  await assert.rejects(
+    () => manager.setPluginSettings("settings-plugin", { apiKey: null }),
+    /Setting 'apiKey' is required/,
+  );
+
+  // A plugin without a schema has no settings surface.
+  const plain: ServerPlugin = {
+    metadata: {
+      id: "no-settings",
+      name: "Plain",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+    },
+    init: () => {},
+  };
+  await manager.registerPlugin(plain);
+  assert.equal(await manager.getPluginSettingsView("no-settings"), null);
+  await assert.rejects(
+    () => manager.setPluginSettings("no-settings", {}),
+    /does not declare a settingsSchema/,
+  );
+});
diff --git a/server/server/internal/plugins/__tests__/sdk_conformance.test.ts b/server/server/internal/plugins/__tests__/sdk_conformance.test.ts
new file mode 100644
index 000000000..2c38f17a4
--- /dev/null
+++ b/server/server/internal/plugins/__tests__/sdk_conformance.test.ts
@@ -0,0 +1,334 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { PluginManager } from "../manager";
+import { PLUGIN_API_VERSION, SUPPORTED_API_VERSIONS } from "../types";
+import type { PluginContext, PluginStorage, ServerPlugin } from "../types";
+
+/**
+ * Host-side conformance for the `@drop-oss/plugin-sdk` server contract.
+ *
+ * The SDK ships `MockPluginContext`, but that mirrors the SDK's own types, not
+ * this host, so it cannot detect a capability the SDK declares while the server
+ * runtime silently omits it. This test pins the server runtime against the SDK
+ * contract: every `PluginContext` member the SDK exposes must exist at runtime,
+ * and every server capability must have a working, capability-gated
+ * registration path.
+ */
+
+/** Canonical `ServerCapability` list from `@drop-oss/plugin-sdk@0.7.0`. */
+const SDK_SERVER_CAPABILITIES = [
+  "routes",
+  "storage",
+  "websocket",
+  "events",
+  "network",
+  "metadata:provider",
+  "commerce:payment",
+  "cloudsave:provider",
+  "auth:provider",
+  "storage:depot",
+] as const;
+
+/** Canonical `PluginContext` member names from `@drop-oss/plugin-sdk@0.7.0`. */
+const SDK_PLUGIN_CONTEXT_MEMBERS = [
+  "id",
+  "logger",
+  "storage",
+  "settings",
+  "registerRoute",
+  "broadcast",
+  "subscribe",
+  "registerWebSocket",
+  "registerPublicWebSocketChannel",
+  "registerSubscriptionAuthorizer",
+  "fetch",
+  "registerMetadataProvider",
+  "registerCloudSaveResolver",
+  "registerPaymentGateway",
+  "registerAuthProvider",
+  "registerDepotProvider",
+  "scheduleTask",
+] as const;
+
+class MemoryStorage implements PluginStorage {
+  private readonly data = new Map<string, unknown>();
+  private schemaVersion = 0;
+  async get<T>(key: string): Promise<T | null> {
+    return this.data.has(key) ? (this.data.get(key) as T) : null;
+  }
+  async set<T>(key: string, value: T): Promise<void> {
+    this.data.set(key, value);
+  }
+  async delete(key: string): Promise<void> {
+    this.data.delete(key);
+  }
+  async listKeys(): Promise<string[]> {
+    return [...this.data.keys()];
+  }
+  async getSchemaVersion(): Promise<number> {
+    return this.schemaVersion;
+  }
+  async setSchemaVersion(version: number): Promise<void> {
+    this.schemaVersion = version;
+  }
+}
+
+function createManager(): PluginManager {
+  return new PluginManager({
+    storageFactory: () => new MemoryStorage(),
+    authResolver: async () => ({ userId: undefined }),
+  });
+}
+
+test("server plugin API version matches the SDK contract", () => {
+  assert.equal(PLUGIN_API_VERSION, 3);
+  assert.deepEqual([...SUPPORTED_API_VERSIONS], [1, 2, 3]);
+});
+
+test("PluginContext exposes every member the SDK declares", async () => {
+  const manager = createManager();
+  let context: PluginContext | undefined;
+
+  const plugin: ServerPlugin = {
+    metadata: {
+      id: "context-surface",
+      name: "Context Surface",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      capabilities: [...SDK_SERVER_CAPABILITIES],
+    },
+    init: (ctx) => {
+      context = ctx;
+    },
+  };
+
+  await manager.registerPlugin(plugin);
+  assert.ok(context);
+  const keys = new Set(Object.keys(context as PluginContext));
+  for (const member of SDK_PLUGIN_CONTEXT_MEMBERS) {
+    assert.ok(keys.has(member), `PluginContext is missing '${member}'`);
+  }
+  await manager.unregisterPlugin("context-surface");
+});
+
+test("every SDK server capability registers through its runtime path", async () => {
+  const manager = createManager();
+
+  // One plugin declaring every server capability exercises each registration
+  // path so a capability declared by the SDK but missing at runtime fails here.
+  const plugin: ServerPlugin = {
+    metadata: {
+      id: "all-server-caps",
+      name: "All Server Caps",
+      version: "1.0.0",
+      apiVersion: PLUGIN_API_VERSION,
+      capabilities: [...SDK_SERVER_CAPABILITIES],
+    },
+    init: (ctx) => {
+      ctx.registerRoute("GET", "/conformance", () => ({ ok: true }));
+      ctx.subscribe("conformance:event", () => {});
+      ctx.broadcast("conformance:event", { ok: true });
+      ctx.registerWebSocket("conformance:ws", () => {});
+      ctx.registerPublicWebSocketChannel("conformance:public");
+      ctx.registerSubscriptionAuthorizer(
+        (channel) => channel === "conformance:ws",
+        () => true,
+      );
+      ctx.registerMetadataProvider({
+        id: "conformance-metadata",
+        name: "Conformance",
+        search: async () => [],
+        getDetails: async () => null,
+      });
+      ctx.registerCloudSaveResolver({
+        id: "conformance-cloudsave",
+        name: "Conformance",
+        resolveSavePaths: async () => [],
+      });
+      ctx.registerPaymentGateway({
+        id: "conformance-payment",
+        name: "Conformance",
+        createPaymentIntent: async () => ({
+          intentId: "i",
+          status: "pending",
+        }),
+        handleWebhook: async () => ({
+          orderId: "o",
+          status: "succeeded",
+          transactionId: "t",
+        }),
+      });
+      ctx.registerAuthProvider?.({
+        id: "conformance-auth",
+        name: "Conformance",
+        authenticate: async () => ({ authenticated: false }),
+      });
+      ctx.registerDepotProvider?.({
+        id: "conformance-depot",
+        name: "Conformance",
+        resolveDepotStream: async () => null,
+      });
+      ctx.scheduleTask?.("conformance-task", 60_000, () => {});
+    },
+  };
+
+  await manager.registerPlugin(plugin);
+
+  assert.equal(
+    manager.getPlugin("all-server-caps")?.metadata.id,
+    "all-server-caps",
+  );
+  assert.equal(
+    manager.getMetadataProvider("conformance-metadata")?.name,
+    "Conformance",
+  );
+  assert.equal(
+    manager.getCloudSaveResolver("conformance-cloudsave")?.name,
+    "Conformance",
+  );
+  assert.equal(
+    manager.getPaymentGateway("conformance-payment")?.name,
+    "Conformance",
+  );
+  assert.equal(
+    manager.getAuthProvider("conformance-auth")?.name,
+    "Conformance",
+  );
+  assert.equal(
+    manager.getDepotProvider("conformance-depot")?.name,
+    "Conformance",
+  );
+  assert.equal(
+    manager.getPluginSettings("all-server-caps") !== undefined,
+    true,
+  );
+
+  await manager.unregisterPlugin("all-server-caps");
+  assert.equal(manager.getAuthProvider("conformance-auth"), undefined);
+  assert.equal(manager.getDepotProvider("conformance-depot"), undefined);
+});
+
+test("each SDK server capability is enforced fail-closed when undeclared", async () => {
+  const manager = createManager();
+
+  const operations: Array<{
+    capability: (typeof SDK_SERVER_CAPABILITIES)[number];
+    use: (ctx: PluginContext) => void | Promise<void>;
+  }> = [
+    {
+      capability: "routes",
+      use: (ctx) => ctx.registerRoute("GET", "/x", () => ({})),
+    },
+    {
+      capability: "storage",
+      use: async (ctx) => {
+        await ctx.storage.get("x");
+      },
+    },
+    {
+      capability: "network",
+      use: async (ctx) => {
+        await ctx.fetch("https://example.invalid/");
+      },
+    },
+    {
+      capability: "events",
+      use: (ctx) => ctx.subscribe("x", () => {}),
+    },
+    {
+      capability: "events",
+      use: (ctx) => ctx.broadcast("x", {}),
+    },
+    {
+      capability: "websocket",
+      use: (ctx) => ctx.registerWebSocket("x", () => {}),
+    },
+    {
+      capability: "websocket",
+      use: (ctx) => ctx.registerPublicWebSocketChannel("x"),
+    },
+    {
+      capability: "websocket",
+      use: (ctx) =>
+        ctx.registerSubscriptionAuthorizer(
+          () => true,
+          () => true,
+        ),
+    },
+    {
+      capability: "metadata:provider",
+      use: (ctx) =>
+        ctx.registerMetadataProvider({
+          id: "denied-meta",
+          name: "Denied",
+          search: async () => [],
+          getDetails: async () => null,
+        }),
+    },
+    {
+      capability: "cloudsave:provider",
+      use: (ctx) =>
+        ctx.registerCloudSaveResolver({
+          id: "denied-cloud",
+          name: "Denied",
+          resolveSavePaths: async () => [],
+        }),
+    },
+    {
+      capability: "commerce:payment",
+      use: (ctx) =>
+        ctx.registerPaymentGateway({
+          id: "denied-pay",
+          name: "Denied",
+          createPaymentIntent: async () => ({
+            intentId: "i",
+            status: "pending",
+          }),
+          handleWebhook: async () => ({
+            orderId: "o",
+            status: "succeeded",
+            transactionId: "t",
+          }),
+        }),
+    },
+    {
+      capability: "auth:provider",
+      use: (ctx) =>
+        ctx.registerAuthProvider?.({
+          id: "denied-auth",
+          name: "Denied",
+          authenticate: async () => ({ authenticated: false }),
+        }),
+    },
+    {
+      capability: "storage:depot",
+      use: (ctx) =>
+        ctx.registerDepotProvider?.({
+          id: "denied-depot",
+          name: "Denied",
+          resolveDepotStream: async () => null,
+        }),
+    },
+  ];
+
+  for (const { capability, use } of operations) {
+    const id = `denied-${capability.replace(/[^a-z]/g, "-")}`;
+    const plugin: ServerPlugin = {
+      metadata: {
+        id,
+        name: "Denied",
+        version: "1.0.0",
+        apiVersion: PLUGIN_API_VERSION,
+        capabilities: [],
+      },
+      init: async (ctx) => {
+        await use(ctx);
+      },
+    };
+    await assert.rejects(
+      () => manager.registerPlugin(plugin),
+      new RegExp(`'${capability}' capability`),
+      `expected '${capability}' to be capability-gated`,
+    );
+  }
+});
diff --git a/server/server/internal/plugins/__tests__/settings.test.ts b/server/server/internal/plugins/__tests__/settings.test.ts
new file mode 100644
index 000000000..76b5d67a8
--- /dev/null
+++ b/server/server/internal/plugins/__tests__/settings.test.ts
@@ -0,0 +1,112 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  applySettingsDefaults,
+  mergeSettingsPayload,
+  normalizeSettingsSchema,
+  redactSettingsValues,
+  validateSettingsValues,
+} from "../settings";
+
+const schema = {
+  fields: [
+    { key: "name", label: "Name", type: "string" as const, required: true },
+    { key: "token", label: "Token", type: "password" as const },
+    { key: "count", label: "Count", type: "number" as const, default: 10 },
+    { key: "on", label: "On", type: "boolean" as const },
+    {
+      key: "mode",
+      label: "Mode",
+      type: "select" as const,
+      options: [
+        { label: "A", value: "a" },
+        { label: "B", value: { nested: 1 } },
+      ],
+    },
+  ],
+};
+
+test("normalizeSettingsSchema accepts valid schemas and rejects malformed ones", () => {
+  assert.deepEqual(normalizeSettingsSchema(schema), schema);
+  assert.equal(normalizeSettingsSchema(undefined), undefined);
+  assert.equal(normalizeSettingsSchema({}), undefined);
+  assert.equal(normalizeSettingsSchema({ fields: "no" }), undefined);
+  assert.equal(normalizeSettingsSchema({ fields: [{}] }), undefined);
+  assert.equal(
+    normalizeSettingsSchema({
+      fields: [{ key: "x", label: "X", type: "object" }],
+    }),
+    undefined,
+  );
+});
+
+test("validateSettingsValues type-checks every field type", () => {
+  const ok = validateSettingsValues(schema, {
+    name: "drop",
+    count: 5,
+    on: true,
+    mode: { nested: 1 },
+  });
+  assert.equal(ok.valid, true, ok.errors.join(", "));
+
+  assert.match(
+    validateSettingsValues(schema, {
+      name: "drop",
+      count: Number.NaN,
+    }).errors.join(),
+    /finite number/,
+  );
+  assert.match(
+    validateSettingsValues(schema, { name: "drop", on: "yes" }).errors.join(),
+    /boolean/,
+  );
+  assert.match(
+    validateSettingsValues(schema, { name: "drop", mode: "c" }).errors.join(),
+    /declared options/,
+  );
+  assert.match(
+    validateSettingsValues(schema, { name: "drop", extra: 1 }).errors.join(),
+    /Unknown setting/,
+  );
+  assert.match(
+    validateSettingsValues(schema, null).errors.join(),
+    /must be an object/,
+  );
+});
+
+test("applySettingsDefaults fills missing fields only", () => {
+  assert.deepEqual(applySettingsDefaults(schema, { name: "drop", count: 0 }), {
+    name: "drop",
+    count: 0,
+  });
+});
+
+test("mergeSettingsPayload keeps omitted secrets and clears null passwords", () => {
+  const stored = { name: "drop", token: "secret" };
+
+  const kept = mergeSettingsPayload(schema, stored, { count: 2 });
+  assert.equal(kept.errors.length, 0);
+  assert.equal(kept.input.token, "secret");
+  assert.equal(kept.input.count, 2);
+
+  const cleared = mergeSettingsPayload(schema, stored, { token: null });
+  assert.equal(cleared.errors.length, 0);
+  assert.equal(Object.hasOwn(cleared.input, "token"), false);
+
+  const unknown = mergeSettingsPayload(schema, stored, { bogus: 1 });
+  assert.match(unknown.errors.join(), /Unknown setting/);
+});
+
+test("redactSettingsValues hides passwords and reports presence", () => {
+  const { values, secrets } = redactSettingsValues(schema, {
+    name: "drop",
+    token: "secret",
+    count: 3,
+  });
+  assert.deepEqual(values, { name: "drop", count: 3 });
+  assert.deepEqual(secrets, { token: true });
+
+  const empty = redactSettingsValues(schema, { token: "" });
+  assert.deepEqual(empty.values, {});
+  assert.deepEqual(empty.secrets, { token: false });
+});
diff --git a/server/server/internal/plugins/context.ts b/server/server/internal/plugins/context.ts
index 0796be8ce..62e6b8260 100644
--- a/server/server/internal/plugins/context.ts
+++ b/server/server/internal/plugins/context.ts
@@ -4,7 +4,9 @@ import type { PluginEventBus } from "./events";
 import type { PluginRouteTable } from "./routes";
 import type { PluginWebSocketRegistry } from "./websocket";
 import type {
+  AuthProvider,
   CloudSavePathResolver,
+  DepotStorageProvider,
   MetadataProvider,
   PaymentGateway,
   PluginCapability,
@@ -12,6 +14,11 @@ import type {
   PluginStorage,
   ServerPlugin,
 } from "./types";
+import {
+  PLUGIN_SETTINGS_STORAGE_KEY,
+  applySettingsDefaults,
+  normalizeSettingsSchema,
+} from "./settings";
 
 function hasCapability(
   capabilities: PluginCapability[] | undefined,
@@ -52,6 +59,14 @@ export class PluginSpiRegistry {
     string,
     { pluginId: string; gateway: PaymentGateway }
   >();
+  private readonly authProviders = new Map<
+    string,
+    { pluginId: string; provider: AuthProvider }
+  >();
+  private readonly depotProviders = new Map<
+    string,
+    { pluginId: string; provider: DepotStorageProvider }
+  >();
 
   registerMetadataProvider(
     pluginId: string,
@@ -125,10 +140,60 @@ export class PluginSpiRegistry {
     this.paymentGateways.set(gateway.id, { pluginId, gateway });
   }
 
+  registerAuthProvider(
+    pluginId: string,
+    provider: AuthProvider,
+    capabilities: PluginCapability[] | undefined,
+  ): void {
+    if (!provider || typeof provider.id !== "string" || !provider.id.trim()) {
+      throw new Error("Auth provider must have a valid non-empty id");
+    }
+    if (!hasCapability(capabilities, "auth:provider")) {
+      throw new PluginCapabilityError(
+        pluginId,
+        "auth:provider",
+        `registerAuthProvider(${provider.id})`,
+      );
+    }
+    const existing = this.authProviders.get(provider.id);
+    if (existing && existing.pluginId !== pluginId) {
+      throw new Error(
+        `Auth provider '${provider.id}' is already claimed by plugin '${existing.pluginId}'`,
+      );
+    }
+    this.authProviders.set(provider.id, { pluginId, provider });
+  }
+
+  registerDepotProvider(
+    pluginId: string,
+    provider: DepotStorageProvider,
+    capabilities: PluginCapability[] | undefined,
+  ): void {
+    if (!provider || typeof provider.id !== "string" || !provider.id.trim()) {
+      throw new Error("Depot provider must have a valid non-empty id");
+    }
+    if (!hasCapability(capabilities, "storage:depot")) {
+      throw new PluginCapabilityError(
+        pluginId,
+        "storage:depot",
+        `registerDepotProvider(${provider.id})`,
+      );
+    }
+    const existing = this.depotProviders.get(provider.id);
+    if (existing && existing.pluginId !== pluginId) {
+      throw new Error(
+        `Depot provider '${provider.id}' is already claimed by plugin '${existing.pluginId}'`,
+      );
+    }
+    this.depotProviders.set(provider.id, { pluginId, provider });
+  }
+
   release(pluginId: string): void {
     purgeOwned(this.metadataProviders, pluginId);
     purgeOwned(this.cloudSaveResolvers, pluginId);
     purgeOwned(this.paymentGateways, pluginId);
+    purgeOwned(this.authProviders, pluginId);
+    purgeOwned(this.depotProviders, pluginId);
   }
 
   getMetadataProviders(): MetadataProvider[] {
@@ -154,8 +219,32 @@ export class PluginSpiRegistry {
   getPaymentGateway(id: string): PaymentGateway | undefined {
     return this.paymentGateways.get(id)?.gateway;
   }
+
+  getAuthProviders(): AuthProvider[] {
+    return Array.from(this.authProviders.values()).map((e) => e.provider);
+  }
+
+  getAuthProvider(id: string): AuthProvider | undefined {
+    return this.authProviders.get(id)?.provider;
+  }
+
+  getDepotProviders(): DepotStorageProvider[] {
+    return Array.from(this.depotProviders.values()).map((e) => e.provider);
+  }
+
+  getDepotProvider(id: string): DepotStorageProvider | undefined {
+    return this.depotProviders.get(id)?.provider;
+  }
 }
 
+/** Schedules a recurring plugin task; returns an unregister callback. */
+export type PluginTaskScheduler = (
+  pluginId: string,
+  name: string,
+  intervalMs: number,
+  task: () => void | Promise<void>,
+) => () => void;
+
 /** Resources a plugin context is built from. */
 export interface PluginContextHost {
   routes: PluginRouteTable;
@@ -163,6 +252,7 @@ export interface PluginContextHost {
   events: PluginEventBus;
   spi: PluginSpiRegistry;
   createStorage(pluginId: string): Promise<PluginStorage>;
+  scheduleTask: PluginTaskScheduler;
   log: Logger;
 }
 
@@ -200,14 +290,26 @@ export async function createPluginContext(
   const id = plugin.metadata.id;
   const capabilities = plugin.metadata.capabilities;
   const pluginLogger = host.log.child({ plugin: id });
-  const storage = guardStorage(id, capabilities, await host.createStorage(id));
+  // Host-managed settings read from the unguarded storage so a plugin can
+  // declare a `settingsSchema` without also needing the `storage` capability.
+  const rawStorage = await host.createStorage(id);
+  const storage = guardStorage(id, capabilities, rawStorage);
   host.routes.create(id);
 
+  const schema = normalizeSettingsSchema(plugin.metadata.settingsSchema);
+  let settings: Readonly<Record<string, unknown>> | undefined;
+  if (schema) {
+    const stored = await rawStorage.get<Record<string, unknown>>(
+      PLUGIN_SETTINGS_STORAGE_KEY,
+    );
+    settings = Object.freeze(applySettingsDefaults(schema, stored));
+  }
+
   return {
     id,
     logger: pluginLogger,
     storage,
-    settings: Object.freeze({}),
+    settings,
     registerRoute: (method, pattern, handler) => {
       if (!hasCapability(capabilities, "routes")) {
         throw new PluginCapabilityError(
@@ -283,5 +385,15 @@ export async function createPluginContext(
       host.spi.registerPaymentGateway(id, gateway, capabilities);
       pluginLogger.debug(`Registered payment gateway: ${gateway.id}`);
     },
+    registerAuthProvider: (provider) => {
+      host.spi.registerAuthProvider(id, provider, capabilities);
+      pluginLogger.debug(`Registered auth provider: ${provider.id}`);
+    },
+    registerDepotProvider: (provider) => {
+      host.spi.registerDepotProvider(id, provider, capabilities);
+      pluginLogger.debug(`Registered depot provider: ${provider.id}`);
+    },
+    scheduleTask: (name, intervalMs, task) =>
+      host.scheduleTask(id, name, intervalMs, task),
   };
 }
diff --git a/server/server/internal/plugins/index.ts b/server/server/internal/plugins/index.ts
index 6e818a0c8..e7bef3d54 100644
--- a/server/server/internal/plugins/index.ts
+++ b/server/server/internal/plugins/index.ts
@@ -4,6 +4,7 @@ import { helloWorldPlugin } from "./builtin/hello-world";
 export * from "./types";
 export * from "./errors";
 export * from "./storage";
+export * from "./settings";
 export * from "./manager";
 export { helloWorldPlugin } from "./builtin/hello-world";
 
diff --git a/server/server/internal/plugins/manager.ts b/server/server/internal/plugins/manager.ts
index 1dfedb3b1..390fca6ed 100644
--- a/server/server/internal/plugins/manager.ts
+++ b/server/server/internal/plugins/manager.ts
@@ -23,17 +23,28 @@ import {
 } from "./bundle";
 import type { PluginBundleHost, PluginUpdateInfo } from "./bundle";
 import type {
+  AuthProvider,
   CloudSavePathResolver,
+  DepotStorageProvider,
   MetadataProvider,
   PaymentGateway,
   PluginManifest,
   PluginMetadata,
+  PluginSettingsSchema,
   PluginStatus,
   PluginStorage,
   ServerPlugin,
   SubscriptionContext,
   WebSocketContext,
 } from "./types";
+import {
+  PLUGIN_SETTINGS_STORAGE_KEY,
+  applySettingsDefaults,
+  mergeSettingsPayload,
+  normalizeSettingsSchema,
+  redactSettingsValues,
+  validateSettingsValues,
+} from "./settings";
 
 /** Resolved caller identity passed to route handlers. */
 export interface PluginAuthContext {
@@ -71,6 +82,17 @@ export class PluginManager {
   private readonly webSockets = new PluginWebSocketRegistry();
   private readonly events = new PluginEventBus();
   private readonly spi = new PluginSpiRegistry();
+  /**
+   * Memoized storage instances per plugin so the guarded context storage and
+   * host-managed settings reads/writes share one instance and cannot observe
+   * stale copies of the on-disk state.
+   */
+  private readonly storageInstances = new Map<string, PluginStorage>();
+  /** Recurring plugin tasks keyed by `<pluginId>:<taskName>`. */
+  private readonly scheduledTasks = new Map<
+    string,
+    { pluginId: string; timer: NodeJS.Timeout }
+  >();
   private readonly lifecycle: PluginLifecycle;
   private readonly contextHost: PluginContextHost;
   private readonly bundleHost: PluginBundleHost;
@@ -83,7 +105,9 @@ export class PluginManager {
       events: this.events,
       spi: this.spi,
       log: this.log,
-      createStorage: (pluginId) => this.createStorage(pluginId),
+      createStorage: (pluginId) => this.getStorageInstance(pluginId),
+      scheduleTask: (pluginId, name, intervalMs, task) =>
+        this.scheduleTask(pluginId, name, intervalMs, task),
     };
     this.bundleHost = {
       log: this.log,
@@ -112,6 +136,61 @@ export class PluginManager {
     return new FilePluginStorage(pluginId, this.options.dataDir);
   }
 
+  private async getStorageInstance(pluginId: string): Promise<PluginStorage> {
+    const existing = this.storageInstances.get(pluginId);
+    if (existing) return existing;
+    const created = await this.createStorage(pluginId);
+    this.storageInstances.set(pluginId, created);
+    return created;
+  }
+
+  /**
+   * Register a recurring task for a plugin. Re-registering the same
+   * `<pluginId>:<name>` replaces the previous timer. Timers are unref'd so they
+   * never keep the process alive.
+   */
+  private scheduleTask(
+    pluginId: string,
+    name: string,
+    intervalMs: number,
+    task: () => void | Promise<void>,
+  ): () => void {
+    if (typeof name !== "string" || !name.trim()) {
+      throw new Error("Task name must be a non-empty string");
+    }
+    if (
+      typeof intervalMs !== "number" ||
+      !Number.isFinite(intervalMs) ||
+      intervalMs <= 0
+    ) {
+      throw new Error(
+        "Task interval must be a positive number of milliseconds",
+      );
+    }
+    const key = `${pluginId}:${name}`;
+    const existing = this.scheduledTasks.get(key);
+    if (existing) {
+      clearInterval(existing.timer);
+      this.scheduledTasks.delete(key);
+    }
+    const timer = setInterval(() => {
+      void Promise.resolve()
+        .then(task)
+        .catch((err) =>
+          this.log.error(`Plugin task '${key}' threw: ${String(err)}`),
+        );
+    }, intervalMs);
+    timer.unref?.();
+    this.scheduledTasks.set(key, { pluginId, timer });
+    return () => {
+      const entry = this.scheduledTasks.get(key);
+      if (entry) {
+        clearInterval(entry.timer);
+        this.scheduledTasks.delete(key);
+      }
+    };
+  }
+
   private async loadRegistry(): Promise<PluginRegistry> {
     const registryPath =
       this.options.registryPath ?? process.env.DROP_PLUGIN_REGISTRY;
@@ -126,6 +205,13 @@ export class PluginManager {
     this.webSockets.release(id);
     this.spi.release(id);
     this.events.release(id);
+    this.storageInstances.delete(id);
+    for (const [key, entry] of this.scheduledTasks) {
+      if (entry.pluginId === id) {
+        clearInterval(entry.timer);
+        this.scheduledTasks.delete(key);
+      }
+    }
   }
 
   private async resolveAuth(event: H3Event): Promise<PluginAuthContext> {
@@ -249,6 +335,95 @@ export class PluginManager {
     return this.spi.getPaymentGateway(id);
   }
 
+  getAuthProviders(): AuthProvider[] {
+    return this.spi.getAuthProviders();
+  }
+
+  getAuthProvider(id: string): AuthProvider | undefined {
+    return this.spi.getAuthProvider(id);
+  }
+
+  getDepotProviders(): DepotStorageProvider[] {
+    return this.spi.getDepotProviders();
+  }
+
+  getDepotProvider(id: string): DepotStorageProvider | undefined {
+    return this.spi.getDepotProvider(id);
+  }
+
+  /** Declarative settings schema for a loaded plugin, if declared. */
+  getSettingsSchema(id: string): PluginSettingsSchema | undefined {
+    const plugin = this.lifecycle.get(id);
+    return normalizeSettingsSchema(plugin?.metadata.settingsSchema);
+  }
+
+  /** Reads + default-fills the host-managed settings for `pluginId`. */
+  private async readSettingsFor(
+    pluginId: string,
+    schema: PluginSettingsSchema | undefined,
+  ): Promise<Record<string, unknown>> {
+    if (!schema) return {};
+    const storage = await this.getStorageInstance(pluginId);
+    const stored = await storage.get<Record<string, unknown>>(
+      PLUGIN_SETTINGS_STORAGE_KEY,
+    );
+    return applySettingsDefaults(schema, stored);
+  }
+
+  /** Effective settings values (including defaults) for a loaded plugin. */
+  async getPluginSettings(id: string): Promise<Record<string, unknown>> {
+    if (!this.lifecycle.getRecord(id)) {
+      throw createError({
+        statusCode: 404,
+        statusMessage: `Plugin '${id}' not found`,
+      });
+    }
+    return await this.readSettingsFor(id, this.getSettingsSchema(id));
+  }
+
+  /** Settings view with `password` values redacted, for API consumers. */
+  async getPluginSettingsView(id: string): Promise<{
+    schema: PluginSettingsSchema;
+    values: Record<string, unknown>;
+    secrets: Record<string, boolean>;
+  } | null> {
+    const schema = this.getSettingsSchema(id);
+    if (!schema) return null;
+    const values = await this.readSettingsFor(id, schema);
+    const redacted = redactSettingsValues(schema, values);
+    return { schema, values: redacted.values, secrets: redacted.secrets };
+  }
+
+  /** Validate + persist a partial settings update. Returns the redacted view. */
+  async setPluginSettings(id: string, submitted: unknown) {
+    if (!this.lifecycle.getRecord(id)) {
+      throw createError({
+        statusCode: 404,
+        statusMessage: `Plugin '${id}' not found`,
+      });
+    }
+    const schema = this.getSettingsSchema(id);
+    if (!schema) {
+      throw createError({
+        statusCode: 400,
+        statusMessage: `Plugin '${id}' does not declare a settingsSchema`,
+      });
+    }
+    const current = await this.readSettingsFor(id, schema);
+    const merge = mergeSettingsPayload(schema, current, submitted);
+    const validation = validateSettingsValues(schema, merge.input);
+    const errors = [...merge.errors, ...validation.errors];
+    if (errors.length > 0) {
+      throw createError({
+        statusCode: 400,
+        statusMessage: errors.join("; "),
+      });
+    }
+    const storage = await this.getStorageInstance(id);
+    await storage.set(PLUGIN_SETTINGS_STORAGE_KEY, validation.values);
+    return await this.getPluginSettingsView(id);
+  }
+
   async getClientAssetPath(
     pluginId: string,
     assetRelPath: string,
diff --git a/server/server/internal/plugins/settings.ts b/server/server/internal/plugins/settings.ts
new file mode 100644
index 000000000..22435b333
--- /dev/null
+++ b/server/server/internal/plugins/settings.ts
@@ -0,0 +1,246 @@
+import type { PluginSettingsField, PluginSettingsSchema } from "./types";
+
+/**
+ * Reserved storage key under which the host persists values for a plugin's
+ * declarative `settingsSchema`. Plugins can read the same values from
+ * `PluginContext.settings` at init; the key is namespaced per plugin by
+ * `PluginStorage`, so it never collides across plugins.
+ */
+export const PLUGIN_SETTINGS_STORAGE_KEY = "__drop_settings_v1";
+
+const MAX_SETTINGS_KEYS = 128;
+const MAX_STRING_LENGTH = 100_000;
+const FIELD_TYPES: ReadonlySet<string> = new Set([
+  "string",
+  "password",
+  "number",
+  "boolean",
+  "select",
+]);
+
+export interface SettingsValidationResult {
+  valid: boolean;
+  errors: string[];
+  values: Record<string, unknown>;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Validate an untrusted schema from an installed manifest into the typed
+ * contract, dropping anything malformed. Returns `undefined` when the shape is
+ * unusable so callers treat it as "no settings".
+ */
+export function normalizeSettingsSchema(
+  raw: unknown,
+): PluginSettingsSchema | undefined {
+  if (!isPlainObject(raw)) return undefined;
+  const { fields } = raw;
+  if (!Array.isArray(fields)) return undefined;
+  const normalized: PluginSettingsField[] = [];
+  for (const field of fields) {
+    if (!isPlainObject(field)) return undefined;
+    if (typeof field.key !== "string" || field.key.length === 0)
+      return undefined;
+    if (typeof field.label !== "string") return undefined;
+    if (typeof field.type !== "string" || !FIELD_TYPES.has(field.type)) {
+      return undefined;
+    }
+    if (field.required !== undefined && typeof field.required !== "boolean") {
+      return undefined;
+    }
+    normalized.push(field as unknown as PluginSettingsField);
+  }
+  return { fields: normalized };
+}
+
+function valuesEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (typeof a === "number" && typeof b === "number") {
+    return Number.isNaN(a) && Number.isNaN(b);
+  }
+  if (isPlainObject(a) && isPlainObject(b)) {
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length) return false;
+    return aKeys.every((key) => valuesEqual(a[key], b[key]));
+  }
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return (
+      a.length === b.length &&
+      a.every((value, index) => valuesEqual(value, b[index]))
+    );
+  }
+  return false;
+}
+
+function validateField(
+  field: PluginSettingsField,
+  value: unknown,
+): { ok: true } | { ok: false; error: string } {
+  switch (field.type) {
+    case "string":
+    case "password":
+      if (typeof value !== "string") {
+        return { ok: false, error: `Setting '${field.key}' must be a string` };
+      }
+      if (value.length > MAX_STRING_LENGTH) {
+        return { ok: false, error: `Setting '${field.key}' is too long` };
+      }
+      return { ok: true };
+    case "number":
+      if (typeof value !== "number" || !Number.isFinite(value)) {
+        return {
+          ok: false,
+          error: `Setting '${field.key}' must be a finite number`,
+        };
+      }
+      return { ok: true };
+    case "boolean":
+      if (typeof value !== "boolean") {
+        return { ok: false, error: `Setting '${field.key}' must be a boolean` };
+      }
+      return { ok: true };
+    case "select": {
+      const options = field.options ?? [];
+      if (!options.some((option) => valuesEqual(option.value, value))) {
+        return {
+          ok: false,
+          error: `Setting '${field.key}' must be one of the declared options`,
+        };
+      }
+      return { ok: true };
+    }
+    default:
+      return { ok: false, error: `Setting '${field.key}' has an unknown type` };
+  }
+}
+
+/**
+ * Validate submitted values against a schema. Unknown keys are rejected
+ * (fail-closed) and every declared field is type/option checked. `required`
+ * fields must be present with a non-empty value.
+ */
+export function validateSettingsValues(
+  schema: PluginSettingsSchema,
+  input: unknown,
+): SettingsValidationResult {
+  const errors: string[] = [];
+  const values: Record<string, unknown> = {};
+  if (!isPlainObject(input)) {
+    return {
+      valid: false,
+      errors: ["Settings payload must be an object"],
+      values,
+    };
+  }
+  const keys = Object.keys(input);
+  if (keys.length > MAX_SETTINGS_KEYS) {
+    return {
+      valid: false,
+      errors: [`Too many settings keys (max ${MAX_SETTINGS_KEYS})`],
+      values,
+    };
+  }
+
+  const declared = new Map(schema.fields.map((field) => [field.key, field]));
+  for (const [key, value] of Object.entries(input)) {
+    const field = declared.get(key);
+    if (!field) {
+      errors.push(`Unknown setting '${key}'`);
+      continue;
+    }
+    const result = validateField(field, value);
+    if (!result.ok) {
+      errors.push(result.error);
+      continue;
+    }
+    values[key] = value;
+  }
+
+  for (const field of schema.fields) {
+    if (!field.required) continue;
+    const value = values[field.key];
+    if (value === undefined || value === "") {
+      errors.push(`Setting '${field.key}' is required`);
+    }
+  }
+
+  return { valid: errors.length === 0, errors, values };
+}
+
+/**
+ * Apply a partial update over the stored settings. Unknown keys are rejected;
+ * `null` for a `password` field clears the stored secret; omitted fields keep
+ * their stored value. The merged object is then type/`required` validated by
+ * {@link validateSettingsValues}.
+ */
+export function mergeSettingsPayload(
+  schema: PluginSettingsSchema,
+  stored: Record<string, unknown>,
+  submitted: unknown,
+): { input: Record<string, unknown>; errors: string[] } {
+  const errors: string[] = [];
+  const input: Record<string, unknown> = { ...stored };
+  if (!isPlainObject(submitted)) {
+    return { input, errors: ["Settings payload must be an object"] };
+  }
+  const declared = new Map(schema.fields.map((field) => [field.key, field]));
+  for (const [key, value] of Object.entries(submitted)) {
+    const field = declared.get(key);
+    if (!field) {
+      errors.push(`Unknown setting '${key}'`);
+      continue;
+    }
+    if (field.type === "password" && value === null) {
+      Reflect.deleteProperty(input, key);
+      continue;
+    }
+    input[key] = value;
+  }
+  return { input, errors };
+}
+
+/** Merge stored values with schema defaults for fields never persisted. */
+export function applySettingsDefaults(
+  schema: PluginSettingsSchema,
+  stored: unknown,
+): Record<string, unknown> {
+  const source = isPlainObject(stored) ? stored : {};
+  const values: Record<string, unknown> = {};
+  for (const field of schema.fields) {
+    if (Object.hasOwn(source, field.key)) {
+      values[field.key] = source[field.key];
+    } else if (field.default !== undefined) {
+      values[field.key] = field.default;
+    }
+  }
+  return values;
+}
+
+/**
+ * Replace `password` values with `null` before returning settings over an API
+ * boundary. `hasValue` records whether a secret was set without revealing it.
+ */
+export function redactSettingsValues(
+  schema: PluginSettingsSchema,
+  values: Record<string, unknown>,
+): { values: Record<string, unknown>; secrets: Record<string, boolean> } {
+  const redacted: Record<string, unknown> = {};
+  const secrets: Record<string, boolean> = {};
+  for (const field of schema.fields) {
+    if (field.type === "password") {
+      secrets[field.key] =
+        Object.hasOwn(values, field.key) &&
+        values[field.key] !== undefined &&
+        values[field.key] !== "";
+      continue;
+    }
+    if (Object.hasOwn(values, field.key)) {
+      redacted[field.key] = values[field.key];
+    }
+  }
+  return { values: redacted, secrets };
+}
diff --git a/server/server/internal/plugins/types.ts b/server/server/internal/plugins/types.ts
index 101872560..b5822d698 100644
--- a/server/server/internal/plugins/types.ts
+++ b/server/server/internal/plugins/types.ts
@@ -147,6 +147,15 @@ export interface PluginContext {
    * Requires the `storage:depot` capability.
    */
   registerDepotProvider?(provider: DepotStorageProvider): void;
+  /**
+   * Schedule a recurring background task. Returns an unregister callback that
+   * stops the task and is invoked automatically when the plugin unloads.
+   */
+  scheduleTask?(
+    name: string,
+    intervalMs: number,
+    task: () => void | Promise<void>,
+  ): () => void;
 }
 
 export interface ServerPlugin {
diff --git a/server/server/internal/services/depot/__tests__/remote.test.ts b/server/server/internal/services/depot/__tests__/remote.test.ts
new file mode 100644
index 000000000..01d451c18
--- /dev/null
+++ b/server/server/internal/services/depot/__tests__/remote.test.ts
@@ -0,0 +1,123 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import type { DepotStorageProvider } from "../../../plugins/types";
+import { readRemoteRange, resolveRemoteDepot } from "../remote";
+
+function provider(
+  id: string,
+  resolve: DepotStorageProvider["resolveDepotStream"],
+): DepotStorageProvider {
+  return { id, name: id, resolveDepotStream: resolve };
+}
+
+test("resolveRemoteDepot returns the first provider with a usable stream", async () => {
+  const providers: DepotStorageProvider[] = [
+    provider("empty", async () => null),
+    provider("throwing", async () => {
+      throw new Error("provider down");
+    }),
+    provider("hollow", async () => ({})),
+    provider("seedbox", async (depotId, gameId) => ({
+      url: `https://seed.example/${gameId}/${depotId}`,
+      headers: { Authorization: "Bearer t" },
+    })),
+    provider("later", async () => ({ url: "https://later.example" })),
+  ];
+
+  const resolved = await resolveRemoteDepot("game-1", "depot-1", providers);
+  assert.equal(resolved?.providerId, "seedbox");
+  assert.equal(resolved?.stream.url, "https://seed.example/game-1/depot-1");
+  assert.deepEqual(resolved?.stream.headers, { Authorization: "Bearer t" });
+});
+
+test("resolveRemoteDepot returns null when no provider can serve the game", async () => {
+  const resolved = await resolveRemoteDepot("game-1", "depot-1", [
+    provider("empty", async () => null),
+    provider("throwing", async () => {
+      throw new Error("down");
+    }),
+  ]);
+  assert.equal(resolved, null);
+});
+
+test("readRemoteRange delegates to pieceReader when present", async () => {
+  const calls: Array<[number, number]> = [];
+  const data = await readRemoteRange(
+    {
+      pieceReader: async (offset, length) => {
+        calls.push([offset, length]);
+        return new Uint8Array([offset, length]);
+      },
+    },
+    10,
+    4,
+  );
+  assert.deepEqual([...data], [10, 4]);
+  assert.deepEqual(calls, [[10, 4]]);
+});
+
+test("readRemoteRange performs an HTTP range read with provider headers", async () => {
+  const originalFetch = globalThis.fetch;
+  let seenUrl = "";
+  let seenRange: string | null = null;
+  let seenAuth: string | null = null;
+  globalThis.fetch = (async (
+    input: string | URL | Request,
+    init?: RequestInit,
+  ) => {
+    seenUrl = String(input);
+    const headers = new Headers(init?.headers);
+    seenRange = headers.get("Range");
+    seenAuth = headers.get("Authorization");
+    return new Response(new Uint8Array([1, 2, 3]), {
+      status: 206,
+      headers: { "Content-Type": "application/octet-stream" },
+    });
+  }) as typeof fetch;
+
+  try {
+    const data = await readRemoteRange(
+      {
+        url: "https://seed.example/stream.bin",
+        headers: { Authorization: "Bearer t" },
+      },
+      100,
+      3,
+    );
+    assert.deepEqual([...data], [1, 2, 3]);
+    assert.equal(seenUrl, "https://seed.example/stream.bin");
+    assert.equal(seenRange, "bytes=100-102");
+    assert.equal(seenAuth, "Bearer t");
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("readRemoteRange fails closed on a non-range HTTP response", async () => {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = (async () =>
+    new Response("nope", { status: 500 })) as typeof fetch;
+  try {
+    await assert.rejects(
+      () => readRemoteRange({ url: "https://seed.example/stream.bin" }, 0, 4),
+      /Remote depot read failed \(500\)/,
+    );
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("readRemoteRange validates offsets and missing transports", async () => {
+  await assert.rejects(
+    () => readRemoteRange({}, 0, 1),
+    /neither url nor pieceReader/,
+  );
+  await assert.rejects(
+    () => readRemoteRange({ url: "https://x" }, -1, 1),
+    /offset must be a non-negative integer/,
+  );
+  await assert.rejects(
+    () => readRemoteRange({ url: "https://x" }, 0, 0),
+    /length must be a positive integer/,
+  );
+});
diff --git a/server/server/internal/services/depot/remote.ts b/server/server/internal/services/depot/remote.ts
new file mode 100644
index 000000000..64d59d027
--- /dev/null
+++ b/server/server/internal/services/depot/remote.ts
@@ -0,0 +1,93 @@
+import { createError } from "h3";
+import pluginManager from "../../plugins";
+import type {
+  DepotDownloadStream,
+  DepotStorageProvider,
+} from "../../plugins/types";
+
+export interface ResolvedRemoteDepot {
+  providerId: string;
+  stream: DepotDownloadStream;
+}
+
+/**
+ * Resolve a remote depot stream for `gameId` from the registered
+ * `DepotStorageProvider`s. Providers are consulted in registration order; the
+ * first non-empty stream wins. Returns `null` when no provider can serve it so
+ * the caller can fall back to a local/library backend.
+ */
+export async function resolveRemoteDepot(
+  gameId: string,
+  depotId: string,
+  providers: DepotStorageProvider[] = pluginManager.getDepotProviders(),
+): Promise<ResolvedRemoteDepot | null> {
+  for (const provider of providers) {
+    let stream: DepotDownloadStream | null = null;
+    try {
+      stream = await provider.resolveDepotStream(depotId, gameId);
+    } catch {
+      // A failing provider must not block the others; fail soft here and let
+      // the caller report "no remote depot" if none succeed.
+      continue;
+    }
+    if (stream && (stream.url || stream.pieceReader)) {
+      return { providerId: provider.id, stream };
+    }
+  }
+  return null;
+}
+
+/**
+ * Read `length` bytes at `offset` from a resolved remote depot stream.
+ *
+ * A provider may expose either an HTTP `url` (+ optional `headers`, used with a
+ * `Range` request) or a `pieceReader(offset, length)` callback. Both are
+ * addressed in bytes from the start of the depot's content stream.
+ */
+export async function readRemoteRange(
+  stream: DepotDownloadStream,
+  offset: number,
+  length: number,
+): Promise<Uint8Array> {
+  if (!Number.isSafeInteger(offset) || offset < 0) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: "offset must be a non-negative integer",
+    });
+  }
+  if (!Number.isSafeInteger(length) || length <= 0) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: "length must be a positive integer",
+    });
+  }
+
+  if (stream.pieceReader) {
+    const data = await stream.pieceReader(offset, length);
+    if (!(data instanceof Uint8Array)) {
+      throw createError({
+        statusCode: 502,
+        statusMessage: "Remote depot pieceReader returned a non-binary value",
+      });
+    }
+    return data;
+  }
+
+  if (!stream.url) {
+    throw createError({
+      statusCode: 501,
+      statusMessage: "Remote depot stream exposes neither url nor pieceReader",
+    });
+  }
+
+  const headers = new Headers(stream.headers ?? {});
+  headers.set("Range", `bytes=${offset}-${offset + length - 1}`);
+  const response = await fetch(stream.url, { headers });
+  if (!response.ok && response.status !== 206) {
+    throw createError({
+      statusCode: 502,
+      statusMessage: `Remote depot read failed (${response.status})`,
+    });
+  }
+  return new Uint8Array(await response.arrayBuffer());
+}