Self-hosted, plugin-based server management.
TypeScript dockerhomelabpluginsrdpremote-desktopself-hostedserver-managementsftpsshterminaltermixvnc
/**
* The pluginSettings map attached to a host on its way out.
*
* Without this the host editor would need one request per plugin per host,
* which is the shape that makes a list of a few hundred hosts slow. One query
* covers the whole list instead.
*
* Kept out of transformHostResponse because that function is synchronous and
* shared by every host read path. Secrets are always redacted here, so nothing
* on this path has to decrypt and the async work stays in one place.
*/
import type { PluginManifest } from "@termix-ssh/plugin-sdk/manifest";
import { createCurrentPluginSettingsRepository } from "../repositories/factory.js";
import type { PluginSettingsRecord } from "../repositories/plugin-settings-repository.js";
import {
declaredFields,
findField,
resolveFieldValue,
setSetting,
} from "../../plugins/settings.js";
import {
coerceSettingValue,
validateSettingValue,
} from "@termix-ssh/plugin-sdk/settings";
import { getPluginRuntime } from "../../plugins/index.js";
import { consume } from "../../plugins/registry.js";
import { sshLogger } from "../../utils/logger.js";
export type HostPluginSettings = Record<string, Record<string, unknown>>;
/**
* Marks a host changed after one of its plugin settings did, so remote sync,
* which pulls by updated_at, carries the new value across.
*/
export async function touchHost(hostId: number): Promise<void> {
try {
const { sql } = await import("drizzle-orm");
const { runStatement } =
await import("../../utils/crypto-migration/raw-rows.js");
await runStatement(
sql`UPDATE ssh_data SET updated_at = ${new Date().toISOString()} WHERE id = ${hostId}`,
);
} catch {
// Only a sync hint; the setting itself is already saved.
}
}
/** Enabled plugins that declare host-scope settings, with their manifests. */
export function hostSettingsPlugins(): PluginManifest[] {
try {
const { loader } = getPluginRuntime();
return loader
.list()
.filter((plugin) => plugin.state === "active")
.map((plugin) => plugin.manifest)
.filter(
(manifest): manifest is PluginManifest =>
!!manifest && !!manifest.contributes?.settings?.host,
);
} catch {
// The runtime is not up in every context that renders a host.
return [];
}
}
/**
* Builds the map for a set of hosts in one query.
*
* Returns an empty map when no enabled plugin declares host settings, so the
* common case costs nothing.
*/
export async function loadHostPluginSettings(
hostIds: number[],
): Promise<Map<number, HostPluginSettings>> {
const result = new Map<number, HostPluginSettings>();
const manifests = hostSettingsPlugins();
if (manifests.length === 0 || hostIds.length === 0) return result;
let rows: PluginSettingsRecord[] = [];
try {
rows = await createCurrentPluginSettingsRepository().getAllForScopeIds(
"host",
hostIds.map(String),
);
} catch (error) {
// A host list must not fail because a settings read did.
sshLogger.warn("Failed to load host plugin settings", {
operation: "host_plugin_settings",
error: error instanceof Error ? error.message : String(error),
});
return result;
}
const byHostAndPlugin = new Map<string, PluginSettingsRecord[]>();
for (const row of rows) {
const key = `${row.scopeId}:${row.pluginId}`;
const list = byHostAndPlugin.get(key);
if (list) list.push(row);
else byHostAndPlugin.set(key, [row]);
}
for (const hostId of hostIds) {
const perPlugin: HostPluginSettings = {};
for (const manifest of manifests) {
const fields = declaredFields(manifest, "host");
if (fields.length === 0) continue;
const stored = new Map(
(byHostAndPlugin.get(`${hostId}:${manifest.id}`) ?? []).map((row) => [
row.key,
row,
]),
);
const values: Record<string, unknown> = {};
for (const field of fields) {
values[field.key] = await resolveFieldValue(
field,
stored.get(field.key),
{ redactSecrets: true },
);
}
perPlugin[manifest.id] = values;
}
if (Object.keys(perPlugin).length > 0) result.set(hostId, perPlugin);
}
return result;
}
const SHARE_LEVELS = ["connect", "view", "edit", "manage"];
/**
* Drops the fields a shared host's recipient may not read: a field declares
* the lowest share level that sees it with shareRead. The owner sees all.
*/
function visibleHostPluginSettings(
values: HostPluginSettings,
host: Record<string, unknown>,
): HostPluginSettings {
if (!host.isShared) return values;
const level = SHARE_LEVELS.indexOf(
typeof host.permissionLevel === "string" ? host.permissionLevel : "connect",
);
const result: HostPluginSettings = {};
for (const manifest of hostSettingsPlugins()) {
const own = values[manifest.id];
if (!own) continue;
const copy = { ...own };
for (const field of declaredFields(manifest, "host")) {
if (
field.shareRead &&
SHARE_LEVELS.indexOf(field.shareRead) > Math.max(level, 0)
) {
delete copy[field.key];
}
}
result[manifest.id] = copy;
}
return result;
}
/**
* Fields a plugin still puts on the host payload in their pre-2.9 shape, for
* clients outside Termix (Termix-Mobile) that have not moved to
* pluginSettings yet. Registered as ctx.registry.provide(
* "<id>.hostPayloadLegacy", fn); the function gets the plugin's own host
* values and the host, and never overwrites a field core already set. When
* both are objects the plugin's keys are added to core's, under the same
* rule.
*/
export type PluginHostPayloadLegacy = (
values: Record<string, unknown>,
host: Record<string, unknown>,
) => Record<string, unknown> | null;
function isPlainObject(value: unknown): value is Record<string, unknown> {
return !!value && typeof value === "object" && !Array.isArray(value);
}
function applyLegacyFields(
host: Record<string, unknown>,
values: HostPluginSettings,
): void {
for (const manifest of hostSettingsPlugins()) {
const own = values[manifest.id];
if (!own) continue;
const legacy = consume<PluginHostPayloadLegacy>(
`${manifest.id}.hostPayloadLegacy`,
);
if (!legacy) continue;
try {
for (const [key, value] of Object.entries(legacy(own, host) ?? {})) {
const current = host[key];
if (current === undefined || current === null) {
host[key] = value;
} else if (isPlainObject(current) && isPlainObject(value)) {
// An object core already sends (terminalConfig) gains the plugin's
// keys, still never over one core set.
host[key] = { ...value, ...current };
}
}
} catch {
// A plugin's compat shape must never break a host read.
}
}
}
/** Attaches the map to already-transformed host objects, in place. */
export function attachHostPluginSettings(
hosts: Record<string, unknown>[],
settings: Map<number, HostPluginSettings>,
): void {
if (settings.size === 0) return;
for (const host of hosts) {
const hostId = Number(host.id);
const values = settings.get(hostId);
if (!values) continue;
host.pluginSettings = visibleHostPluginSettings(values, host);
applyLegacyFields(host, host.pluginSettings as HostPluginSettings);
}
}
/**
* The single-host convenience wrapper. With a viewer, a shared host's
* personal fields come from that viewer's own defaults.
*/
export async function withHostPluginSettings(
host: Record<string, unknown>,
viewerId?: string,
): Promise<Record<string, unknown>> {
const hostId = Number(host.id);
if (!Number.isInteger(hostId)) return host;
const settings = await loadHostPluginSettings([hostId]);
if (viewerId) {
const { applyPersonalHostValues } =
await import("../../hosts/defaults/personal.js");
await applyPersonalHostValues(settings, viewerId).catch(() => {});
}
const values = settings.get(hostId);
if (!values) return host;
const result: Record<string, unknown> = {
...host,
pluginSettings: visibleHostPluginSettings(values, host),
};
applyLegacyFields(result, result.pluginSettings as HostPluginSettings);
return result;
}
/**
* Writes a set of host-scope plugin settings in one call, through the same
* path as every other settings write: an undeclared key is refused, a value
* is validated, and a secret field is encrypted.
*/
export async function writeHostPluginSettings(
manifest: PluginManifest,
hostId: number,
values: Record<string, unknown>,
): Promise<void> {
for (const [key, value] of Object.entries(values)) {
if (value === undefined) continue;
const error = await setSetting(manifest, "host", hostId, key, value);
if (error) {
sshLogger.warn("Refused a plugin host setting on import", {
operation: "host_import_plugin_settings",
pluginId: manifest.id,
hostId,
key,
error,
});
}
}
}
/**
* Checks the host settings a ctx.hosts write carries, keyed by plugin id,
* before anything is written. A key the plugin does not declare, or a value
* its field refuses, is an error. A plugin that is not running has nowhere to
* keep them, so its entry is skipped and named in `skipped`.
*/
export function checkHostPluginSettingsInput(
input: Record<string, Record<string, unknown>>,
): {
writes: Array<{ manifest: PluginManifest; values: Record<string, unknown> }>;
skipped: string[];
errors: string[];
} {
const running = new Map(hostSettingsPlugins().map((m) => [m.id, m]));
const writes: Array<{
manifest: PluginManifest;
values: Record<string, unknown>;
}> = [];
const skipped: string[] = [];
const errors: string[] = [];
for (const [pluginId, values] of Object.entries(input)) {
const manifest = running.get(pluginId);
if (!manifest) {
skipped.push(pluginId);
continue;
}
for (const [key, value] of Object.entries(values)) {
const field = findField(manifest, "host", key);
if (!field) {
errors.push(`${pluginId}.${key} is not a host setting it declares`);
continue;
}
const error = validateSettingValue(
field,
coerceSettingValue(field, value),
);
if (error) errors.push(`${pluginId}.${key}: ${error}`);
}
writes.push({ manifest, values });
}
return { writes, skipped, errors };
}
/**
* A plugin's own validator for the fields it accepts inline on a bulk host
* import row (host-bulk-routes.ts's Termix-JSON import path). Registered
* through ctx.registry.provide("<pluginId>.hostImportNormalizer", fn) - not
* part of the SDK's typed ctx surface, because only this one bulk-import
* path calls it and a full contract is speculative until a second caller
* needs it. Returns the fields to write (JSON-serializable, matching
* writeHostPluginSettings's input), or null to write nothing for this row.
*/
export type PluginHostImportNormalizer = (
raw: Record<string, unknown>,
) => Record<string, unknown> | null;
/**
* Runs every enabled plugin's registered import normalizer over one imported
* host row and writes whatever each one returns, so a plugin's host-scope
* settings are validated the same way on bulk import as they are anywhere
* else - instead of host-bulk-routes.ts hardcoding one plugin's shape.
*
* Best-effort per plugin: one plugin's normalizer throwing must not fail the
* whole import, so it is logged and skipped rather than propagated.
*/
export async function applyPluginHostImportSettings(
hostId: number,
raw: Record<string, unknown>,
): Promise<void> {
const exported =
raw.pluginSettings && typeof raw.pluginSettings === "object"
? (raw.pluginSettings as HostPluginSettings)
: {};
for (const manifest of hostSettingsPlugins()) {
try {
// What an export carried for this plugin, validated like any other
// write. Secrets never leave the server, so there are none to restore.
const carried = exported[manifest.id];
if (carried && typeof carried === "object") {
for (const field of declaredFields(manifest, "host")) {
if (field.type === "secret" || !(field.key in carried)) continue;
await setSetting(
manifest,
"host",
hostId,
field.key,
carried[field.key],
);
}
}
const normalizer = consume<PluginHostImportNormalizer>(
`${manifest.id}.hostImportNormalizer`,
);
const values = normalizer?.(raw);
if (values) await writeHostPluginSettings(manifest, hostId, values);
} catch (error) {
sshLogger.warn("Plugin host import normalizer failed", {
operation: "host_import_plugin_settings",
pluginId: manifest.id,
hostId,
error: error instanceof Error ? error.message : String(error),
});
}
}
}
/**
* Turns one plugin's host switch on or off for a set of hosts. Returns false
* when the plugin is not running or declares no enableKey.
*/
export async function setHostPluginEnabled(
pluginId: string,
hostIds: number[],
enabled: boolean,
): Promise<boolean> {
const manifest = hostSettingsPlugins().find((m) => m.id === pluginId);
const enableKey = manifest?.contributes?.settings?.host?.enableKey;
if (!manifest || !enableKey) return false;
for (const hostId of hostIds) {
await setSetting(manifest, "host", hostId, enableKey, enabled);
await touchHost(hostId);
}
const { changeHostOverrides } =
await import("../../hosts/defaults/overrides.js");
await changeHostOverrides(hostIds, { own: [[pluginId, enableKey]] });
return true;
}