@termix-ssh/plugin-sdk 1.0.0

package/dist/testing.js

@@ -0,0 +1,1451 @@
+/**
+ * Test helpers for plugin authors.
+ *
+ * createMockCtx is the one to reach for: it enforces capabilities the way the
+ * real runtime does. createFakeContext stays for tests that only need a
+ * context-shaped object and do not care about the gates.
+ *
+ * The vitest config these run under comes from @termix-ssh/plugin-sdk/vitest-preset.
+ */
+import { LoginMethodError, PLUGIN_HOST_INPUT_KEYS, PluginCapabilityError, } from "./backend.js";
+export function createFakeProcess(pid = 4242) {
+    const stdout = [];
+    const stderr = [];
+    const killed = [];
+    let resolveExit = () => { };
+    const exited = new Promise((resolve) => {
+        resolveExit = resolve;
+    });
+    return {
+        pid,
+        onStdout: (listener) => void stdout.push(listener),
+        onStderr: (listener) => void stderr.push(listener),
+        exited,
+        kill: (signal = "SIGTERM") => {
+            killed.push(signal);
+            resolveExit({ code: null, signal });
+        },
+        emitStdout: (chunk) => stdout.forEach((listener) => listener(chunk)),
+        emitStderr: (chunk) => stderr.forEach((listener) => listener(chunk)),
+        exit: (code, signal = null) => resolveExit({ code, signal }),
+        killed,
+    };
+}
+const CORE_PERMISSION_GROUPS = new Set([
+    "hosts",
+    "snippets",
+    "credentials",
+    "admin",
+]);
+/**
+ * A short name takes the plugin's prefix. An id already under this plugin or
+ * a core group is used as given, like src/backend/plugins/rbac.ts does.
+ */
+function qualifyPermission(pluginId, permission) {
+    const head = permission.split(".")[0];
+    if (head === pluginId || CORE_PERMISSION_GROUPS.has(head))
+        return permission;
+    return `${pluginId}.${permission}`;
+}
+/** How a settings row is keyed in the doubles. Mirrors the real unique index. */
+function settingsKey(scope, scopeId, key) {
+    return `${scope}:${scopeId ?? ""}:${key}`;
+}
+function noopLogger() {
+    return {
+        debug: () => { },
+        info: () => { },
+        warn: () => { },
+        error: () => { },
+    };
+}
+const HOST_INPUT_KEYS = new Set(PLUGIN_HOST_INPUT_KEYS);
+/** Refuses a key ctx.hosts does not take, the way core does. */
+function checkHostInput(input) {
+    const unknown = Object.keys(input ?? {}).filter((key) => !HOST_INPUT_KEYS.has(key));
+    if (unknown.length > 0) {
+        throw new Error(`ctx.hosts does not take ${unknown.join(", ")}`);
+    }
+}
+function emptyHostRecord(id, userId) {
+    return {
+        id,
+        userId,
+        syncId: null,
+        name: null,
+        ip: "",
+        port: 22,
+        username: "",
+        authType: "password",
+        credentialId: null,
+        overrideCredentialUsername: false,
+        connectionType: "ssh",
+        tags: null,
+        folder: null,
+        parentHostId: null,
+        pin: false,
+        notes: null,
+        jumpHosts: [],
+        enableSsh: true,
+        sshPort: null,
+        statusCheckEnabled: true,
+        statusCheckInterval: null,
+        connectionOrigin: null,
+        sshOptions: {},
+        pluginSettings: {},
+        status: null,
+        localOnly: false,
+        createdAt: null,
+        updatedAt: null,
+    };
+}
+function applyHostInput(record, input) {
+    const { tags, pluginSettings: _settings, forceKeyboardInteractive: _fki, ...rest } = input;
+    const next = { ...record };
+    for (const [key, value] of Object.entries(rest)) {
+        if (value !== undefined)
+            next[key] = value;
+    }
+    if (tags !== undefined) {
+        next.tags = Array.isArray(tags) ? tags.join(",") : tags;
+    }
+    if (next.jumpHosts === null)
+        next.jumpHosts = [];
+    if (next.sshOptions === null)
+        next.sshOptions = {};
+    return next;
+}
+/**
+ * A context double good enough to call activate() against in a unit test.
+ * Nothing here is capability-checked: a test asserting a capability gate
+ * should use the real runtime, not this.
+ */
+export function createFakeContext(options = {}) {
+    const pluginId = options.pluginId ?? "test-plugin";
+    const disposals = [];
+    const emitted = [];
+    const kv = new Map();
+    const tables = [];
+    const syncEntities = [];
+    const wsRoutes = [];
+    const httpRouters = [];
+    const listeners = new Map();
+    const settings = new Map();
+    const coreSettings = new Map(Object.entries(options.coreSettings ?? {}));
+    const settingsListeners = new Map();
+    const settingsValidators = new Set();
+    const sshConnections = [];
+    const hostShares = [];
+    const desktopWindows = [];
+    const externalClientLaunches = [];
+    const credentialReads = [];
+    const createdSshKeys = [];
+    const notifications = [];
+    const notifyHub = { current: null };
+    const fetches = [];
+    const processRuns = [];
+    const binaries = [];
+    const tls = {
+        writes: [],
+        reloads: 0,
+        calls: [],
+        challenges: new Map(),
+        renewers: 0,
+    };
+    let tlsState = options.tlsStatus ?? {
+        enabled: true,
+        certificate: null,
+    };
+    const secretStore = new Map();
+    const audits = [];
+    const activities = [];
+    const trackedSessions = [];
+    const interactions = [];
+    const statusReports = [];
+    const statusPorts = new Map();
+    const hostStatuses = new Map(Object.entries(options.hostStatuses ?? {}).map(([id, entry]) => [
+        Number(id),
+        entry,
+    ]));
+    const droppedPools = [];
+    const scheduled = [];
+    const schedule = (kind, ms, fn) => {
+        const job = { kind, ms, fn, stopped: false };
+        scheduled.push(job);
+        const stop = () => {
+            job.stopped = true;
+        };
+        disposals.push(stop);
+        return stop;
+    };
+    const hostsById = new Map((options.hosts ?? []).map((h) => [h.id, h]));
+    const hostRecordsById = new Map();
+    let nextHostId = Math.max(0, ...(options.hosts ?? []).map((h) => h.id)) + 1;
+    const services = new Map(Object.entries(options.services ?? {}));
+    const serviceKey = (service, name) => name ? `${service}#${name}` : service;
+    const registryProviders = new Map();
+    const auth = {
+        sshAuthProviders: [],
+        keyboardInteractiveHandlers: [],
+        loginMethods: [],
+        secondFactors: [],
+        enrollments: new Set(),
+        secretResolvers: new Map(),
+        completedLogins: [],
+        revokedSessions: [],
+        loginFailures: new Map(),
+    };
+    const sshClient = options.sshClient ?? {};
+    let actor = options.actor;
+    const held = options.permissions
+        ? new Set(options.permissions.map((permission) => qualifyPermission(pluginId, permission)))
+        : null;
+    const holds = (permission) => held === null || held.has(qualifyPermission(pluginId, permission));
+    // Like the runtime, a route can only require a permission the manifest
+    // declares. Checked when the test hands in a manifest.
+    const declaredPermissions = options.manifest?.contributes?.permissions
+        ? new Set(options.manifest.contributes.permissions.map((entry) => qualifyPermission(pluginId, entry.name)))
+        : null;
+    for (const [key, value] of Object.entries(options.settings ?? {})) {
+        settings.set(settingsKey("admin", undefined, key), value);
+    }
+    const writeSetting = (scope, scopeId, key, value) => {
+        settings.set(settingsKey(scope, scopeId, key), value);
+        for (const listener of settingsListeners.get(key) ?? [])
+            listener(value);
+    };
+    const manifest = {
+        id: pluginId,
+        name: pluginId,
+        version: "1.0.0",
+        description: "",
+        author: { name: "test" },
+        license: "MIT",
+        category: "Productivity",
+        engine: { termix: ">=2.9.0", api: "1" },
+        capabilities: [],
+        ...options.manifest,
+    };
+    const disposables = {
+        add: (dispose) => disposals.push(dispose),
+    };
+    const ctx = {
+        pluginId,
+        manifest,
+        log: noopLogger(),
+        events: {
+            emit: (topic, payload) => {
+                emitted.push({ topic, payload });
+                for (const listener of listeners.get(topic) ?? [])
+                    listener(payload);
+            },
+            on: (topic, listener) => {
+                let set = listeners.get(topic);
+                if (!set) {
+                    set = new Set();
+                    listeners.set(topic, set);
+                }
+                set.add(listener);
+                return () => set.delete(listener);
+            },
+        },
+        kv: {
+            get: async (key) => (kv.has(key) ? kv.get(key) : null),
+            set: async (key, value) => {
+                kv.set(key, value);
+            },
+            delete: async (key) => kv.delete(key),
+            list: async () => [...kv.keys()],
+        },
+        files: {
+            // A fake path; a test that needs a real folder uses the OS temp dir
+            // itself, not this double.
+            dataDir: async () => `/tmp/${pluginId}`,
+        },
+        db: options.db
+            ? {
+                ...options.db,
+                define: async (definition) => {
+                    tables.push(definition);
+                    return options.db.define(definition);
+                },
+                client: () => options.db.client(),
+                refs: () => options.db.refs(),
+                persist: () => options.db.persist(),
+                dialect: options.db.dialect,
+            }
+            : {
+                // No engine behind this one. Pass createTestDb().database as `db`
+                // for a test that needs real SQL.
+                define: async (definition) => {
+                    tables.push(definition);
+                    return undefined;
+                },
+                client: async () => {
+                    throw new Error("createFakeContext has no database: pass createTestDb().database as db");
+                },
+                refs: async () => {
+                    throw new Error("createFakeContext has no database: pass createTestDb().database as db");
+                },
+                persist: async () => { },
+                dialect: "sqlite",
+            },
+        sync: {
+            registerEntity: (entity) => {
+                syncEntities.push(entity);
+            },
+        },
+        registry: {
+            provide: (key, value) => {
+                assertOwnRegistryKey(pluginId, key);
+                registryProviders.set(key, value);
+            },
+            consume: (key) => registryProviders.get(key),
+            revoke: (key, value) => {
+                assertOwnRegistryKey(pluginId, key);
+                if (!registryProviders.has(key))
+                    return false;
+                if (value !== undefined && registryProviders.get(key) !== value) {
+                    return false;
+                }
+                return registryProviders.delete(key);
+            },
+        },
+        services: {
+            provide: (service, implementation, provideOptions) => {
+                services.set(serviceKey(service, provideOptions?.name), implementation);
+            },
+            // What this context provided or the test seeded through `services`.
+            // Like the real handle, a missing provider is an empty object, which a
+            // consumer's `"method" in handle` probe reads as absent.
+            get: (service, getOptions) => (services.get(serviceKey(service, getOptions?.provider)) ??
+                {}),
+            providers: (service) => [...services.keys()].flatMap((key) => key === service
+                ? [""]
+                : key.startsWith(`${service}#`)
+                    ? [key.slice(service.length + 1)]
+                    : []),
+        },
+        secrets: {
+            get: async (key) => secretStore.get(`${actor ?? ""}:${key}`) ?? null,
+            set: async (key, value) => {
+                if (value === null)
+                    secretStore.delete(`${actor ?? ""}:${key}`);
+                else
+                    secretStore.set(`${actor ?? ""}:${key}`, value);
+            },
+            delete: async (key) => {
+                secretStore.delete(`${actor ?? ""}:${key}`);
+            },
+            seal: async (value) => `sealed:${Buffer.from(value, "utf8").toString("base64")}`,
+            unseal: async (sealed) => sealed?.startsWith("sealed:")
+                ? Buffer.from(sealed.slice(7), "base64").toString("utf8")
+                : null,
+            offer: () => { },
+            withdraw: () => false,
+            getShared: async () => null,
+        },
+        http: {
+            // No express here: a test that needs a real router should mount the
+            // plugin's own route module against its own express app.
+            router: (routerOptions) => {
+                httpRouters.push(routerOptions);
+                return (options.router ? options.router() : undefined);
+            },
+            baseUrl: () => options.baseUrl ?? "https://termix.test",
+        },
+        ws: {
+            route: (path, handler, wsOptions) => {
+                wsRoutes.push({ path, raw: false, handler, options: wsOptions });
+            },
+            upgrade: (path, handler, wsOptions) => {
+                wsRoutes.push({
+                    path,
+                    raw: true,
+                    upgrade: handler,
+                    options: wsOptions,
+                });
+            },
+        },
+        rbac: {
+            // Enforces options.permissions for the acting user, or passes
+            // everything when none were given. The runtime's own resolution against
+            // other plugins' namespaces is covered by core's tests, not here.
+            has: async (permission) => holds(permission),
+            hasFor: async (_userId, permission) => holds(permission),
+            require: (permission) => {
+                if (declaredPermissions &&
+                    !declaredPermissions.has(qualifyPermission(pluginId, permission))) {
+                    throw new Error(`Plugin ${pluginId} cannot require permission "${permission}": it is not declared in contributes.permissions`);
+                }
+                return ((_req, res, next) => {
+                    if (holds(permission)) {
+                        next();
+                        return;
+                    }
+                    res.status(403).json({
+                        error: "Insufficient permissions",
+                        required: qualifyPermission(pluginId, permission),
+                    });
+                });
+            },
+        },
+        // Nothing here is capability-checked, per the module doc; createMockCtx
+        // gates this against options.capabilities.
+        capabilities: {
+            has: async () => true,
+            require: async () => { },
+        },
+        settings: {
+            get: async (key) => settings.get(settingsKey("admin", undefined, key)),
+            set: async (key, value) => writeSetting("admin", undefined, key, value),
+            getUser: async (userId, key) => settings.get(settingsKey("user", userId, key)),
+            setUser: async (userId, key, value) => writeSetting("user", userId, key, value),
+            getHost: async (hostId, key) => settings.get(settingsKey("host", String(hostId), key)),
+            getHostFor: async (hostId, _userId, key) => settings.get(settingsKey("host", String(hostId), key)),
+            // Host defaults live in core; the mock stands in the user's own
+            // setting of the same key, so a test can set one with setUser.
+            getHostDefault: async (userId, key) => settings.get(settingsKey("user", userId, key)),
+            setHost: async (hostId, key, value, options) => options?.inherit
+                ? void settings.delete(settingsKey("host", String(hostId), key))
+                : writeSetting("host", String(hostId), key, value),
+            listHostValues: async (key) => {
+                const found = [];
+                for (const [storedKey, value] of settings) {
+                    const [scope, scopeId, name] = storedKey.split(":");
+                    if (scope !== "host" || name !== key || value === undefined)
+                        continue;
+                    const hostId = Number(scopeId);
+                    found.push({
+                        hostId,
+                        userId: hostRecordsById.get(hostId)?.userId ?? actor ?? "",
+                        value: value,
+                    });
+                }
+                return found;
+            },
+            getAll: async (scope, scopeId) => {
+                const prefix = `${scope}:${scopeId ?? ""}:`;
+                const all = {};
+                for (const [storedKey, value] of settings) {
+                    if (storedKey.startsWith(prefix)) {
+                        all[storedKey.slice(prefix.length)] = value;
+                    }
+                }
+                return all;
+            },
+            onChange: (key, listener) => {
+                let set = settingsListeners.get(key);
+                if (!set) {
+                    set = new Set();
+                    settingsListeners.set(key, set);
+                }
+                set.add(listener);
+                const unsubscribe = () => {
+                    set.delete(listener);
+                };
+                disposals.push(unsubscribe);
+                return unsubscribe;
+            },
+            onValidate: (scope, validator) => {
+                const entry = { scope, validator };
+                settingsValidators.add(entry);
+                const unsubscribe = () => {
+                    settingsValidators.delete(entry);
+                };
+                disposals.push(unsubscribe);
+                return unsubscribe;
+            },
+            readCore: async (key) => coreSettings.get(key) ?? null,
+        },
+        disposables,
+        hosts: {
+            list: async () => [...hostsById.values()],
+            get: async (hostId) => hostsById.get(hostId) ?? null,
+            checkAccess: async (hostId) => {
+                const found = hostsById.get(hostId);
+                if (!found)
+                    return { hasAccess: false, isOwner: false, isShared: false };
+                const isOwner = found.userId === actor;
+                return {
+                    hasAccess: true,
+                    isOwner,
+                    isShared: !isOwner,
+                    permissionLevel: "manage",
+                };
+            },
+            create: async (host) => {
+                checkHostInput(host);
+                const id = nextHostId++;
+                const record = applyHostInput(emptyHostRecord(id, actor ?? "unknown"), host);
+                hostRecordsById.set(id, record);
+                return record;
+            },
+            update: async (hostId, patch) => {
+                checkHostInput(patch);
+                const existing = hostRecordsById.get(hostId);
+                if (!existing)
+                    return null;
+                const updated = applyHostInput(existing, patch);
+                hostRecordsById.set(hostId, updated);
+                return updated;
+            },
+            delete: async (hostId) => {
+                const existed = hostRecordsById.delete(hostId) || hostsById.delete(hostId);
+                return existed;
+            },
+            listOwned: async () => [
+                ...hostRecordsById.values(),
+            ],
+            share: async (hostId, targets, permissionLevel, durationHours) => {
+                hostShares.push({ hostId, targets, permissionLevel, durationHours });
+                return { hostId, shared: true };
+            },
+            listUsers: async () => options.shareableUsers ?? [],
+            listRoles: async () => options.shareableRoles ?? [],
+            trackSession: (hostId) => {
+                trackedSessions.push(hostId);
+                let active = true;
+                return () => {
+                    if (!active)
+                        return;
+                    active = false;
+                    const index = trackedSessions.indexOf(hostId);
+                    if (index >= 0)
+                        trackedSessions.splice(index, 1);
+                };
+            },
+            recordActivity: async (hostId, type, hostName) => {
+                activities.push({ hostId, type, hostName });
+            },
+            status: {
+                get: async (hostId) => hostStatuses.get(hostId) ?? null,
+                check: async (hostId) => hostStatuses.get(hostId) ?? null,
+                reportLogin: (hostId, outcome) => {
+                    statusReports.push({ hostId, ...outcome });
+                },
+                registerPort: (connectionType, resolve) => {
+                    statusPorts.set(connectionType, resolve);
+                    return () => {
+                        statusPorts.delete(connectionType);
+                    };
+                },
+            },
+        },
+        schedule: {
+            every: (intervalMs, fn, scheduleOptions) => {
+                const stop = schedule("every", intervalMs, fn);
+                if (scheduleOptions?.runNow)
+                    void fn();
+                return stop;
+            },
+            after: (delayMs, fn) => schedule("after", delayMs, fn),
+        },
+        audit: {
+            record: async (entry) => {
+                audits.push({ ...entry });
+            },
+        },
+        ssh: {
+            connect: async (host, connectOptions) => {
+                sshConnections.push({ host, options: connectOptions });
+                return {
+                    client: sshClient,
+                    jumpClient: null,
+                    host: (typeof host === "number"
+                        ? { id: host, ip: "", port: 22, username: "" }
+                        : host),
+                    dispose: () => { },
+                };
+            },
+            withConnection: async (host, connectOptions, fn) => {
+                sshConnections.push({ host, pool: connectOptions.pool });
+                return fn(sshClient);
+            },
+            jumpChain: async () => ({
+                client: sshClient,
+                jumpClient: null,
+                host: { id: 0, ip: "", port: 22, username: "" },
+                dispose: () => { },
+            }),
+            dropPooled: (pool, hostId) => {
+                droppedPools.push({ pool, hostId });
+            },
+            poolKey: (pool, host) => `${pool}:${host.userId}:${host.ip}:${host.port}:${host.username}`,
+            resolveHost: async (hostId, resolveOptions) => (options.sshHosts ?? []).find((host) => resolveOptions?.syncId
+                ? host.syncId === resolveOptions.syncId
+                : host.id === hostId) ?? null,
+            prepare: async () => ({
+                config: {},
+                outcome: { status: "ready" },
+                authType: null,
+            }),
+            openTransport: async () => ({ jumpClient: null, via: "direct" }),
+            startInteraction: async (interaction, request) => {
+                interactions.push({ action: "start", interaction, request });
+            },
+            cancelInteraction: async (interaction, request) => {
+                interactions.push({ action: "cancel", interaction, request });
+            },
+            classifyKeyboardInteractive: ({ prompts }, host) => ({
+                kind: "auto",
+                responses: prompts.map((p) => /password/i.test(p.prompt) && typeof host.password === "string"
+                    ? host.password
+                    : ""),
+            }),
+            autoResponses: (prompts, password) => prompts.map((p) => /password/i.test(p.prompt) && password ? password : ""),
+            requiresSecret: (authType) => ["password", "key", "credential", "agent"].includes(authType),
+            // Matches core: the built-in types, plus any registered provider that
+            // does not opt out. An unknown type cannot connect unattended.
+            supportsBackground: (authType) => {
+                if (["password", "key", "credential", "agent"].includes(authType)) {
+                    return true;
+                }
+                const provider = auth.sshAuthProviders.find((candidate) => candidate.type === authType);
+                return !!provider && provider.supportsBackground !== false;
+            },
+        },
+        auth: {
+            registerSshAuthProvider: (provider) => {
+                auth.sshAuthProviders.push(provider);
+            },
+            registerKeyboardInteractiveHandler: (handler) => {
+                auth.keyboardInteractiveHandlers.push(handler);
+            },
+            registerLoginMethod: (method) => {
+                auth.loginMethods.push(method);
+            },
+            registerSecondFactor: (factor) => {
+                auth.secondFactors.push(factor);
+            },
+            recordEnrollment: async (userId, factorId) => {
+                if (options.refuseEnrollment) {
+                    throw new LoginMethodError(options.refuseEnrollment, 409);
+                }
+                auth.enrollments.add(`${userId}:${factorId}`);
+            },
+            removeEnrollment: async (userId, factorId) => {
+                auth.enrollments.delete(`${userId}:${factorId}`);
+            },
+            // Stands in for core's pipeline: answers with the identity as JSON, or
+            // redirects back with the error the way core does.
+            completeRedirectLogin: async (methodId, req, res) => {
+                const response = res;
+                const method = auth.loginMethods.find((candidate) => candidate.id === methodId);
+                if (!method?.callback) {
+                    throw new Error(`No registered redirect method "${methodId}"`);
+                }
+                try {
+                    const identity = await method.callback(req);
+                    auth.completedLogins.push({ methodId, identity });
+                    response.status(200).json({ completed: methodId, identity });
+                }
+                catch (error) {
+                    const returnTo = error.returnTo;
+                    const message = error.message;
+                    if (returnTo) {
+                        const url = new URL(returnTo);
+                        url.searchParams.set("error", error.code ?? message);
+                        response.redirect(url.toString());
+                        return;
+                    }
+                    response
+                        .status(error.status ?? 500)
+                        .json({ error: message });
+                }
+            },
+            revokeSessions: async (match) => {
+                if (!match.sub && !match.sid)
+                    return 0;
+                auth.revokedSessions.push(match);
+                return 1;
+            },
+            loginRateLimit: {
+                isLocked: async (ip, key) => {
+                    const failures = auth.loginFailures.get(`${ip}|${key}`) ?? 0;
+                    return failures >= (options.loginAttemptLimit ?? 5)
+                        ? { locked: true, remainingTime: 60 }
+                        : { locked: false };
+                },
+                recordFailure: async (ip, key) => {
+                    const id = `${ip}|${key}`;
+                    auth.loginFailures.set(id, (auth.loginFailures.get(id) ?? 0) + 1);
+                },
+            },
+            countLinkedUsers: async (provider) => options.linkedUsers?.[provider] ?? 0,
+        },
+        desktop: {
+            openIsolatedWindow: async (request) => {
+                desktopWindows.push(request);
+                return { success: true };
+            },
+            launchExternalClient: async (request) => {
+                externalClientLaunches.push(request);
+                return { success: true };
+            },
+            available: () => options.desktopAvailable ?? false,
+        },
+        credentials: {
+            listSshKeys: async () => [
+                ...(options.sshKeyCredentials ?? []),
+                ...createdSshKeys.map((key) => ({
+                    id: key.id,
+                    name: key.name,
+                    username: key.username ?? null,
+                    publicKey: key.publicKey,
+                })),
+            ],
+            createSshKey: async (input) => {
+                const id = Math.max(0, ...(options.sshKeyCredentials ?? []).map((key) => key.id), ...createdSshKeys.map((key) => key.id)) + 1;
+                createdSshKeys.push({ ...input, id });
+                return { id };
+            },
+            resolveHostProtocol: async (hostId, protocol) => {
+                credentialReads.push({ hostId, protocol });
+                return options.protocolTargets?.[`${hostId}:${protocol}`] ?? null;
+            },
+            registerSecretResolver: (scheme, resolve) => {
+                auth.secretResolvers.set(scheme, resolve);
+                disposals.push(() => {
+                    auth.secretResolvers.delete(scheme);
+                });
+            },
+        },
+        notify: {
+            channels: async () => {
+                if (!actor)
+                    throw new Error("ctx.notify needs an acting user");
+                return options.notificationChannels ?? [];
+            },
+            send: async (notification) => {
+                if (!notification.audience && !actor) {
+                    throw new Error("ctx.notify needs an acting user or an audience");
+                }
+                notifications.push({ actor, notification });
+                const channelIds = notification.channelIds ?? [];
+                const selected = (options.notificationChannels ?? []).filter((channel) => channelIds.includes(channel.id) && channel.enabled);
+                return { recipients: 1, delivered: selected.length, failures: [] };
+            },
+            serve: (hub) => {
+                if (notifyHub.current)
+                    throw new Error("A hub is already running");
+                notifyHub.current = hub;
+                const revoke = () => {
+                    if (notifyHub.current === hub)
+                        notifyHub.current = null;
+                };
+                disposals.push(revoke);
+                return revoke;
+            },
+        },
+        fetch: async (url, init) => {
+            fetches.push({ url, init });
+            if (!options.fetch)
+                throw new Error("ctx.fetch is not stubbed");
+            return options.fetch(url, init);
+        },
+        process: {
+            run: async (file, args, runOptions) => {
+                processRuns.push({ file, args, options: runOptions });
+                if (!options.process?.run) {
+                    throw new Error("ctx.process.run is not stubbed");
+                }
+                return options.process.run(file, args, runOptions);
+            },
+            ensureBinary: async (spec) => {
+                binaries.push(spec);
+                if (options.process?.ensureBinary) {
+                    return options.process.ensureBinary(spec);
+                }
+                return `/tmp/${pluginId}/bin/${spec.name}`;
+            },
+        },
+        plugins: {
+            list: async () => options.installedPlugins ?? [
+                {
+                    id: pluginId,
+                    version: "1.0.0",
+                    source: "bundled",
+                    state: "active",
+                },
+            ],
+        },
+        system: {
+            tlsStatus: async () => {
+                tls.calls.push("tlsStatus");
+                return {
+                    ...tlsState,
+                    renewal: tls.renewers > 0 ? { pluginId, pluginName: pluginId } : null,
+                };
+            },
+            writeTlsCertificate: async (certificatePem, privateKeyPem) => {
+                tls.calls.push("writeTlsCertificate");
+                const info = options.validateTls
+                    ? options.validateTls(certificatePem, privateKeyPem)
+                    : {
+                        subject: "CN=fake",
+                        issuer: "CN=fake-ca",
+                        names: [],
+                        notBefore: new Date().toISOString(),
+                        notAfter: new Date(Date.now() + 90 * 86_400_000).toISOString(),
+                        selfSigned: false,
+                        fingerprint: "00",
+                    };
+                tls.writes.push({ certificatePem, privateKeyPem });
+                tlsState = { ...tlsState, certificate: info };
+                return info;
+            },
+            reloadTls: async () => {
+                tls.calls.push("reloadTls");
+                tls.reloads++;
+                return { applied: true, message: "reloaded" };
+            },
+            publishHttpChallenge: async (token, content) => {
+                tls.calls.push("publishHttpChallenge");
+                tls.challenges.set(token, content);
+                let live = true;
+                const remove = () => {
+                    if (!live)
+                        return;
+                    live = false;
+                    tls.challenges.delete(token);
+                };
+                disposals.push(remove);
+                return remove;
+            },
+            registerTlsRenewer: async () => {
+                tls.calls.push("registerTlsRenewer");
+                tls.renewers++;
+                let live = true;
+                const remove = () => {
+                    if (!live)
+                        return;
+                    live = false;
+                    tls.renewers--;
+                };
+                disposals.push(remove);
+                return remove;
+            },
+        },
+        asUser: async (userId, fn) => {
+            const previous = actor;
+            actor = userId;
+            try {
+                return await fn();
+            }
+            finally {
+                actor = previous;
+            }
+        },
+        currentActor: () => actor,
+    };
+    return {
+        ctx,
+        validateSettings: async (scope, values, context = {}) => {
+            const errors = {};
+            for (const entry of settingsValidators) {
+                if (entry.scope !== scope)
+                    continue;
+                Object.assign(errors, (await entry.validator(values, context)) ?? {});
+            }
+            return errors;
+        },
+        disposals,
+        emitted,
+        kv,
+        tables,
+        syncEntities,
+        wsRoutes,
+        httpRouters,
+        settings,
+        coreSettings,
+        sshConnections,
+        hostShares,
+        auth,
+        desktopWindows,
+        externalClientLaunches,
+        credentialReads,
+        createdSshKeys,
+        notifications,
+        notifyHub,
+        fetches,
+        processRuns,
+        binaries,
+        tls,
+        secretStore,
+        audits,
+        activities,
+        trackedSessions,
+        interactions,
+        statusReports,
+        statusPorts,
+        hostStatuses,
+        droppedPools,
+        scheduled,
+        runScheduled: async () => {
+            for (const job of scheduled.filter((candidate) => !candidate.stopped)) {
+                if (job.kind === "after")
+                    job.stopped = true;
+                await job.fn();
+            }
+        },
+        setActor: (userId) => {
+            actor = userId;
+        },
+        actAs: async (userId, fn) => {
+            const previous = actor;
+            actor = userId;
+            try {
+                return await fn();
+            }
+            finally {
+                actor = previous;
+            }
+        },
+        services,
+    };
+}
+/**
+ * A context double that gates on capabilities the way src/backend/plugins/ctx.ts
+ * does, so a test can prove a plugin fails closed without a running server.
+ *
+ * The gates on today's ctx surface: kv:own on every ctx.kv call, db:own on
+ * ctx.db, network:serve on ctx.http and ctx.ws, events:core on emitting a
+ * topic outside the plugin's own namespace, settings:read-core on
+ * ctx.settings.readCore, ssh:connect plus credentials:use on ctx.ssh,
+ * notify:send on ctx.notify (notify:hub on serve), network:outbound on ctx.fetch, process:spawn on
+ * ctx.process, system:tls on ctx.system, plugins:read on ctx.plugins, and auth:provide on ctx.auth. Reading a plugin's own settings is deliberately
+ * ungated. As the SDK grows a member, add its gate here in the same shape.
+ */
+export function createMockCtx(options = {}) {
+    const granted = new Set(options.capabilities ?? []);
+    const checked = [];
+    const base = createFakeContext({
+        pluginId: options.pluginId,
+        actor: options.actor,
+        settings: options.settings,
+        coreSettings: options.coreSettings,
+        sshClient: options.sshClient,
+        db: options.db,
+        router: options.router,
+        permissions: options.permissions,
+        hosts: options.hosts,
+        shareableUsers: options.shareableUsers,
+        shareableRoles: options.shareableRoles,
+        sshHosts: options.sshHosts,
+        services: options.services,
+        protocolTargets: options.protocolTargets,
+        sshKeyCredentials: options.sshKeyCredentials,
+        desktopAvailable: options.desktopAvailable,
+        hostStatuses: options.hostStatuses,
+        notificationChannels: options.notificationChannels,
+        fetch: options.fetch,
+        process: options.process,
+        tlsStatus: options.tlsStatus,
+        installedPlugins: options.installedPlugins,
+        validateTls: options.validateTls,
+        refuseEnrollment: options.refuseEnrollment,
+        baseUrl: options.baseUrl,
+        linkedUsers: options.linkedUsers,
+        loginAttemptLimit: options.loginAttemptLimit,
+        manifest: {
+            capabilities: options.capabilities ?? [],
+            ...options.manifest,
+        },
+    });
+    const { ctx, kv } = base;
+    const pluginId = ctx.pluginId;
+    for (const [key, value] of Object.entries(options.kv ?? {})) {
+        kv.set(key, value);
+    }
+    const require = (capability) => {
+        checked.push(capability);
+        if (!granted.has(capability)) {
+            throw new PluginCapabilityError(pluginId, capability);
+        }
+    };
+    const guardedKv = ctx.kv;
+    const guardedDb = ctx.db;
+    const gatedCtx = {
+        ...ctx,
+        asUser: async (userId, fn) => {
+            require("users:impersonate");
+            return ctx.asUser(userId, fn);
+        },
+        db: {
+            define: async (definition) => {
+                require("db:own");
+                return guardedDb.define(definition);
+            },
+            client: async () => {
+                require("db:own");
+                return guardedDb.client();
+            },
+            refs: async () => {
+                require("db:core-refs");
+                return guardedDb.refs();
+            },
+            persist: async (persistOptions) => {
+                require("db:own");
+                return guardedDb.persist(persistOptions);
+            },
+            dialect: guardedDb.dialect,
+        },
+        kv: {
+            get: async (key) => {
+                require("kv:own");
+                return guardedKv.get(key);
+            },
+            set: async (key, value) => {
+                require("kv:own");
+                return guardedKv.set(key, value);
+            },
+            delete: async (key) => {
+                require("kv:own");
+                return guardedKv.delete(key);
+            },
+            list: async () => {
+                require("kv:own");
+                return guardedKv.list();
+            },
+        },
+        files: {
+            dataDir: async () => {
+                require("files:own");
+                return ctx.files.dataDir();
+            },
+        },
+        events: {
+            emit: (topic, payload) => {
+                if (!topic.startsWith(`plugin.${pluginId}.`) &&
+                    !granted.has("events:core")) {
+                    throw new Error(`Plugin ${pluginId} may only emit topics under "plugin.${pluginId}.". ` +
+                        `Declare the events:core capability to emit core topics.`);
+                }
+                ctx.events.emit(topic, payload);
+            },
+            on: (topic, listener) => {
+                if (!topic.startsWith("plugin.") && !granted.has("events:core")) {
+                    throw new Error(`Plugin ${pluginId} may only listen to "plugin.*" topics. ` +
+                        `Declare the events:core capability to listen to core topics.`);
+                }
+                return ctx.events.on(topic, listener);
+            },
+        },
+        http: {
+            router: (routerOptions) => {
+                require("network:serve");
+                return ctx.http.router(routerOptions);
+            },
+            baseUrl: (req) => ctx.http.baseUrl(req),
+        },
+        ws: {
+            route: (path, handler, wsOptions) => {
+                require("network:serve");
+                ctx.ws.route(path, handler, wsOptions);
+            },
+            upgrade: (path, handler, wsOptions) => {
+                require("network:serve");
+                ctx.ws.upgrade(path, handler, wsOptions);
+            },
+        },
+        settings: {
+            // Reading and writing a plugin's OWN settings is ungated, exactly as in
+            // the real runtime. Only readCore reaches outside the plugin.
+            ...ctx.settings,
+            listHostValues: async (key) => {
+                require("hosts:read");
+                return ctx.settings.listHostValues(key);
+            },
+            readCore: async (key) => {
+                require("settings:read-core");
+                return ctx.settings.readCore(key);
+            },
+        },
+        hosts: {
+            list: async () => {
+                require("hosts:read");
+                return ctx.hosts.list();
+            },
+            get: async (hostId) => {
+                require("hosts:read");
+                return ctx.hosts.get(hostId);
+            },
+            checkAccess: async (hostId, level) => {
+                require("hosts:read");
+                return ctx.hosts.checkAccess(hostId, level);
+            },
+            create: async (host) => {
+                require("hosts:write");
+                return ctx.hosts.create(host);
+            },
+            update: async (hostId, patch) => {
+                require("hosts:write");
+                return ctx.hosts.update(hostId, patch);
+            },
+            delete: async (hostId) => {
+                require("hosts:write");
+                return ctx.hosts.delete(hostId);
+            },
+            listOwned: async () => {
+                require("hosts:write");
+                return ctx.hosts.listOwned();
+            },
+            share: async (hostId, targets, permissionLevel, durationHours) => {
+                require("hosts:write");
+                return ctx.hosts.share(hostId, targets, permissionLevel, durationHours);
+            },
+            listUsers: async () => {
+                require("hosts:write");
+                return ctx.hosts.listUsers();
+            },
+            listRoles: async () => {
+                require("hosts:write");
+                return ctx.hosts.listRoles();
+            },
+            trackSession: (hostId) => {
+                require("hosts:read");
+                return ctx.hosts.trackSession(hostId);
+            },
+            recordActivity: async (hostId, type, hostName) => {
+                require("hosts:read");
+                return ctx.hosts.recordActivity(hostId, type, hostName);
+            },
+            status: {
+                get: async (hostId) => {
+                    require("hosts:read");
+                    return ctx.hosts.status.get(hostId);
+                },
+                check: async (hostId) => {
+                    require("hosts:read");
+                    return ctx.hosts.status.check(hostId);
+                },
+                reportLogin: (hostId, outcome) => {
+                    require("hosts:read");
+                    ctx.hosts.status.reportLogin(hostId, outcome);
+                },
+                registerPort: (connectionType, resolve) => {
+                    require("hosts:read");
+                    return ctx.hosts.status.registerPort(connectionType, resolve);
+                },
+            },
+        },
+        ssh: {
+            ...ctx.ssh,
+            connect: async (host, connectOptions) => {
+                require("ssh:connect");
+                require("credentials:use");
+                return ctx.ssh.connect(host, connectOptions);
+            },
+            withConnection: async (host, connectOptions, fn) => {
+                require("ssh:connect");
+                require("credentials:use");
+                return ctx.ssh.withConnection(host, connectOptions, fn);
+            },
+            prepare: async (host, prepareOptions) => {
+                require("ssh:connect");
+                require("credentials:use");
+                return ctx.ssh.prepare(host, prepareOptions);
+            },
+            openTransport: async (host, config, transportOptions) => {
+                require("ssh:connect");
+                return ctx.ssh.openTransport(host, config, transportOptions);
+            },
+            resolveHost: async (hostId, resolveOptions) => {
+                require("ssh:connect");
+                require("credentials:use");
+                return ctx.ssh.resolveHost(hostId, resolveOptions);
+            },
+            startInteraction: async (interaction, request) => {
+                require("ssh:connect");
+                require("credentials:use");
+                return ctx.ssh.startInteraction(interaction, request);
+            },
+            cancelInteraction: async (interaction, request) => {
+                require("ssh:connect");
+                return ctx.ssh.cancelInteraction(interaction, request);
+            },
+            jumpChain: async (jumpHosts, chainOptions) => {
+                require("ssh:connect");
+                require("credentials:use");
+                return ctx.ssh.jumpChain(jumpHosts, chainOptions);
+            },
+        },
+        auth: {
+            registerSshAuthProvider: (provider) => {
+                require("auth:provide");
+                ctx.auth.registerSshAuthProvider(provider);
+            },
+            registerKeyboardInteractiveHandler: (handler) => {
+                require("auth:provide");
+                ctx.auth.registerKeyboardInteractiveHandler(handler);
+            },
+            registerLoginMethod: (method) => {
+                require("auth:provide");
+                ctx.auth.registerLoginMethod(method);
+            },
+            registerSecondFactor: (factor) => {
+                require("auth:provide");
+                ctx.auth.registerSecondFactor(factor);
+            },
+            recordEnrollment: async (userId, factorId) => {
+                require("auth:provide");
+                return ctx.auth.recordEnrollment(userId, factorId);
+            },
+            removeEnrollment: async (userId, factorId) => {
+                require("auth:provide");
+                return ctx.auth.removeEnrollment(userId, factorId);
+            },
+            completeRedirectLogin: async (methodId, req, res) => {
+                require("auth:provide");
+                return ctx.auth.completeRedirectLogin(methodId, req, res);
+            },
+            revokeSessions: async (match) => {
+                require("auth:provide");
+                return ctx.auth.revokeSessions(match);
+            },
+            loginRateLimit: {
+                isLocked: async (ip, key) => {
+                    require("auth:provide");
+                    return ctx.auth.loginRateLimit.isLocked(ip, key);
+                },
+                recordFailure: async (ip, key) => {
+                    require("auth:provide");
+                    return ctx.auth.loginRateLimit.recordFailure(ip, key);
+                },
+            },
+            countLinkedUsers: async (provider) => {
+                require("auth:provide");
+                return ctx.auth.countLinkedUsers(provider);
+            },
+        },
+        desktop: {
+            openIsolatedWindow: async (request) => {
+                require("desktop:window");
+                return ctx.desktop.openIsolatedWindow(request);
+            },
+            launchExternalClient: async (request) => {
+                require("desktop:window");
+                return ctx.desktop.launchExternalClient(request);
+            },
+            available: () => ctx.desktop.available(),
+        },
+        credentials: {
+            listSshKeys: async () => {
+                require("credentials:use");
+                return ctx.credentials.listSshKeys();
+            },
+            createSshKey: async (input) => {
+                require("credentials:write");
+                return ctx.credentials.createSshKey(input);
+            },
+            resolveHostProtocol: async (hostId, protocol) => {
+                require("credentials:read");
+                const declared = ctx.manifest.contributes?.protocols;
+                if (declared && !declared.some((entry) => entry.id === protocol)) {
+                    throw new Error(`Plugin ${pluginId} did not declare protocol "${protocol}" in contributes.protocols`);
+                }
+                return ctx.credentials.resolveHostProtocol(hostId, protocol);
+            },
+            registerSecretResolver: (scheme, resolve) => {
+                require("auth:provide");
+                ctx.credentials.registerSecretResolver(scheme, resolve);
+            },
+        },
+        notify: {
+            channels: async () => {
+                require("notify:send");
+                return ctx.notify.channels();
+            },
+            send: async (notification) => {
+                require("notify:send");
+                return ctx.notify.send(notification);
+            },
+            serve: (hub) => {
+                require("notify:hub");
+                return ctx.notify.serve(hub);
+            },
+        },
+        fetch: async (url, init) => {
+            require("network:outbound");
+            return ctx.fetch(url, init);
+        },
+        process: {
+            run: async (file, args, runOptions) => {
+                require("process:spawn");
+                return ctx.process.run(file, args, runOptions);
+            },
+            ensureBinary: async (spec) => {
+                require("process:spawn");
+                return ctx.process.ensureBinary(spec);
+            },
+        },
+        plugins: {
+            list: async () => {
+                require("plugins:read");
+                return ctx.plugins.list();
+            },
+        },
+        system: {
+            tlsStatus: async () => {
+                require("system:tls");
+                return ctx.system.tlsStatus();
+            },
+            writeTlsCertificate: async (certificatePem, privateKeyPem) => {
+                require("system:tls");
+                return ctx.system.writeTlsCertificate(certificatePem, privateKeyPem);
+            },
+            reloadTls: async () => {
+                require("system:tls");
+                return ctx.system.reloadTls();
+            },
+            publishHttpChallenge: async (token, content) => {
+                require("system:tls");
+                return ctx.system.publishHttpChallenge(token, content);
+            },
+            registerTlsRenewer: async () => {
+                require("system:tls");
+                return ctx.system.registerTlsRenewer();
+            },
+        },
+        secrets: {
+            ...ctx.secrets,
+            get: async (key) => {
+                require("secrets:own");
+                return ctx.secrets.get(key);
+            },
+            set: async (key, value) => {
+                require("secrets:own");
+                return ctx.secrets.set(key, value);
+            },
+            delete: async (key) => {
+                require("secrets:own");
+                return ctx.secrets.delete(key);
+            },
+            seal: async (value) => {
+                require("secrets:own");
+                return ctx.secrets.seal(value);
+            },
+            unseal: async (sealed) => {
+                require("secrets:own");
+                return ctx.secrets.unseal(sealed);
+            },
+        },
+        capabilities: {
+            has: async (capability) => granted.has(capability),
+            require: async (capability) => {
+                require(capability);
+            },
+        },
+    };
+    return { ...base, ctx: gatedCtx, checked };
+}
+/**
+ * An in-memory SQLite database with a plugin's own migrations applied.
+ *
+ * Core's users, ssh_data, roles and user_roles exist as minimal stubs with
+ * foreign keys on, so a refUser or refHost column cascades exactly as it
+ * does on the server, and ctx.db.refs() has something real to join against.
+ * The migrations are read from <pluginDir>/migrations/sqlite and split with
+ * the same splitter the server's runner uses.
+ */
+export async function createTestDb(pluginDir, options = {}) {
+    const [{ default: Database }, { drizzle }, fs, path, ddl, builder] = await Promise.all([
+        import("better-sqlite3"),
+        import("drizzle-orm/better-sqlite3"),
+        import("node:fs"),
+        import("node:path"),
+        import("./ddl.js"),
+        import("./table-builder.js"),
+    ]);
+    const sqlite = new Database(":memory:");
+    sqlite.exec("PRAGMA foreign_keys = ON");
+    sqlite.exec("CREATE TABLE users (id TEXT PRIMARY KEY, username TEXT NOT NULL DEFAULT '', is_admin INTEGER NOT NULL DEFAULT 0)");
+    sqlite.exec("CREATE TABLE ssh_data (id INTEGER PRIMARY KEY AUTOINCREMENT)");
+    sqlite.exec("CREATE TABLE roles (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, display_name TEXT NOT NULL DEFAULT '')");
+    sqlite.exec("CREATE TABLE user_roles (id INTEGER PRIMARY KEY AUTOINCREMENT, user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE, role_id INTEGER NOT NULL REFERENCES roles(id) ON DELETE CASCADE)");
+    const handle = drizzle(sqlite);
+    // The manifest id, not the folder name: a plugin's own repo is rarely
+    // named after its id.
+    const manifestPath = path.join(pluginDir, "manifest.json");
+    const pluginId = (fs.existsSync(manifestPath) &&
+        JSON.parse(fs.readFileSync(manifestPath, "utf8")).id) ||
+        path.basename(pluginDir);
+    const applied = [];
+    let persisted = 0;
+    await options.before?.(sqlite);
+    const migrate = async () => {
+        const dir = path.join(pluginDir, "migrations", "sqlite");
+        if (!fs.existsSync(dir))
+            return [];
+        const files = fs
+            .readdirSync(dir)
+            .filter((file) => /^\d{4}_[a-z0-9_]+\.sql$/.test(file))
+            .sort();
+        const now = [];
+        for (const file of files) {
+            const id = file.replace(/\.sql$/, "");
+            if (applied.includes(id))
+                continue;
+            const source = fs.readFileSync(path.join(dir, file), "utf8");
+            for (const statement of ddl.splitStatements(source)) {
+                sqlite.exec(statement);
+            }
+            applied.push(id);
+            now.push(id);
+        }
+        return now;
+    };
+    if (!options.skipMigrations)
+        await migrate();
+    const refs = {
+        users: builder.buildRefTable("users", {
+            id: "text",
+            username: "text",
+            isAdmin: "boolean",
+        }),
+        hosts: builder.buildRefTable("ssh_data", { id: "integer" }),
+        roles: builder.buildRefTable("roles", {
+            id: "integer",
+            name: "text",
+            displayName: "text",
+        }),
+        userRoles: builder.buildRefTable("user_roles", {
+            id: "integer",
+            userId: "text",
+            roleId: "integer",
+        }),
+    };
+    const database = {
+        define: async (definition) => builder.buildTable(pluginId, definition),
+        client: async () => handle,
+        refs: async () => refs,
+        persist: async () => {
+            persisted += 1;
+        },
+        dialect: "sqlite",
+    };
+    return {
+        sqlite,
+        drizzle: handle,
+        database,
+        get persisted() {
+            return persisted;
+        },
+        applied,
+        migrate,
+        close: () => sqlite.close(),
+    };
+}
+const TEST_HOST = "@termix-ssh/plugin-host/testing";
+export async function renderWithApp(plugin, options = {}) {
+    // A variable specifier keeps bundlers from resolving it at build time; the
+    // test runner resolves it through its alias.
+    const host = (await import(/* @vite-ignore */ TEST_HOST));
+    return host.renderPlugin(plugin, options);
+}
+function assertOwnRegistryKey(pluginId, key) {
+    if (typeof key !== "string" || !key.startsWith(`${pluginId}.`)) {
+        throw new Error(`Plugin ${pluginId} may only use registry keys under "${pluginId}.", not "${key}"`);
+    }
+}