@termix-ssh/plugin-sdk 1.0.0

package/dist/manifest.d.ts

@@ -0,0 +1,461 @@
+/**
+ * Manifest v2: the inert JSON description of a plugin.
+ *
+ * Core reads this without running any plugin code, so everything that decides
+ * whether a plugin may load, what it may do and where its UI appears has to be
+ * expressible here.
+ *
+ * Unknown fields are rejected at every level. A typo'd "contribute" or
+ * "permissionGroups" used to validate clean and be silently dropped, which
+ * made a manifest look like it declared something it did not.
+ */
+/**
+ * The plugin API this build implements. A minor bump adds to the API and
+ * never removes; a major bump may break plugins.
+ *
+ * engine.api is a semver range checked against this ("1" means any 1.x,
+ * "^1.2" needs 1.2 or later). engine.termix is checked against the core
+ * version by the server.
+ */
+export declare const PLUGIN_API_VERSION = "1.0.0";
+/** The API major, the default engine.api for a new plugin. */
+export declare const SUPPORTED_PLUGIN_API_VERSION: string;
+/** Whether this build's plugin API satisfies a manifest's engine.api. */
+export declare function isApiCompatible(range: string): boolean;
+/**
+ * Whether a core version satisfies a manifest's engine.termix. A prerelease
+ * core (2.9.0-beta.1) counts as that release.
+ */
+export declare function isTermixCompatible(range: string, coreVersion: string | null): boolean;
+export declare const PLUGIN_CATEGORIES: readonly ["Terminal", "Files & Transfer", "Infrastructure", "Monitoring", "Networking", "Access & Security", "Productivity"];
+export declare const PLUGIN_PLATFORMS: readonly ["linux", "win32", "darwin"];
+export declare const ACTION_CONTRIBUTION_KINDS: readonly ["button", "component"];
+export type ActionContributionKind = (typeof ACTION_CONTRIBUTION_KINDS)[number];
+/**
+ * Ids no plugin may take. A permission is registered as <id>.<name>, so a
+ * plugin called "admin" would mint admin.* permissions and could default them
+ * onto the user role; the rest are names core or the runtime already uses.
+ */
+export declare const RESERVED_PLUGIN_IDS: readonly string[];
+/** The roles core seeds. A plugin may only set defaults for these. */
+export declare const SYSTEM_ROLE_NAMES: readonly ["admin", "user"];
+export type SystemRoleName = (typeof SYSTEM_ROLE_NAMES)[number];
+/**
+ * Core permission groups. A plugin permission may not start with one of these,
+ * or a manifest could declare admin.users.manage and gate a route on it.
+ */
+export declare const RESERVED_PERMISSION_PREFIXES: readonly ["hosts", "credentials", "admin"];
+/** The id a plugin-relative permission name is registered under. */
+export declare function qualifyPermission(pluginId: string, name: string): string;
+export interface PluginAuthor {
+    name: string;
+    url?: string;
+}
+export interface PluginEngine {
+    /** Semver range of Termix releases the plugin runs on, e.g. ">=2.9.0". */
+    termix: string;
+    /**
+     * Semver range of the plugin API it needs, e.g. "1" or "^1.2". Use the
+     * lowest minor whose API you call, so older cores refuse it cleanly.
+     */
+    api: string;
+}
+export interface HostCapabilityContribution {
+    key: string;
+    labelKey: string;
+    editorTab: string;
+}
+export interface PluginTabContribution {
+    id: string;
+    titleKey: string;
+    icon: string;
+    openFrom: string[];
+}
+/**
+ * A sidebar panel or dashboard card the plugin's frontend registers. Declared
+ * here so core knows who owns a saved view even while the plugin is off and
+ * its code never loaded.
+ */
+export interface PluginViewContribution {
+    id: string;
+    titleKey: string;
+    icon?: string;
+}
+/**
+ * One role permission a plugin contributes.
+ *
+ * `name` is short and plugin-relative; core registers it as
+ * `<pluginId>.<name>`, so a plugin can never name a core group or another
+ * plugin's namespace. The i18n keys are plugin-relative too.
+ */
+export interface PluginPermissionContribution {
+    name: string;
+    titleKey: string;
+    descriptionKey: string;
+    /** System roles that should hold this the first time it is seen. */
+    defaultRoles?: SystemRoleName[];
+}
+export interface PluginActionContribution {
+    id: string;
+    titleKey: string;
+    /** Name of the frontend export implementing this action. */
+    handler: string;
+    icon?: string;
+    permission?: string;
+    slot?: string;
+    kind?: ActionContributionKind;
+}
+export interface PluginActionSlot {
+    id: string;
+    accepts: ActionContributionKind[];
+    descriptionKey?: string;
+}
+export interface PluginServiceProvide {
+    service: string;
+    version: string;
+    /** The role permission a calling user needs. */
+    permission: string;
+    /**
+     * Named providers this plugin registers, for a service several plugins
+     * provide side by side (sessions.live, keyed by session type). Omitted, the
+     * plugin provides it once, unnamed.
+     */
+    names?: string[];
+}
+export interface PluginServiceRequire {
+    service: string;
+    versionRange: string;
+    optional?: boolean;
+}
+export interface PluginSecretProvide {
+    key: string;
+    permission: string;
+    descriptionKey?: string;
+}
+export interface PluginSecretRequire {
+    plugin: string;
+    key: string;
+    optional?: boolean;
+}
+export declare const SETTINGS_FIELD_TYPES: readonly ["boolean", "string", "number", "select", "multiselect", "secret", "textarea", "json", "custom"];
+export type PluginSettingsFieldType = (typeof SETTINGS_FIELD_TYPES)[number];
+export declare const SETTINGS_SCOPES: readonly ["admin", "user", "host"];
+export type PluginSettingsScope = (typeof SETTINGS_SCOPES)[number];
+export interface PluginSettingsOption {
+    value: string;
+    labelKey: string;
+}
+/**
+ * One field on a plugin's settings page.
+ *
+ * Core renders these; a plugin supplies data only, so it cannot ship its own
+ * form styling and drift from the rest of the app. `type: "custom"` is the
+ * escape hatch for UI a schema cannot express, and names a component the
+ * frontend registered rather than carrying markup.
+ */
+export interface PluginSettingsField {
+    key: string;
+    type: PluginSettingsFieldType;
+    /** Required except for "custom", which draws its own label. */
+    labelKey?: string;
+    descriptionKey?: string;
+    placeholderKey?: string;
+    default?: unknown;
+    /** select and multiselect only. */
+    options?: PluginSettingsOption[];
+    /** number only. */
+    min?: number;
+    max?: number;
+    /** Key of a boolean field in the same scope that must be on. */
+    requires?: string;
+    /**
+     * Who may write it. Admin fields default to admin.plugins.manage; a short
+     * name resolves against this plugin's own permissions.
+     */
+    permission?: string;
+    /** Section heading this field sits under. */
+    group?: string;
+    /** Registered component id. Required when type is "custom". */
+    component?: string;
+    /**
+     * Host scope only: whether the field can have a host default (server,
+     * user or folder) that hosts follow until they set their own. On by
+     * default for every field except secrets and json fields with
+     * `secretKeys`. Turn it off for a value that only makes sense per host,
+     * such as a MAC address or an API endpoint.
+     */
+    defaultable?: boolean;
+    /**
+     * Host scope only: the levels that may set a default for it. Defaults to
+     * all three. Leave "admin" out for a value that points at one user's own
+     * rows (a snippet id, a profile id).
+     */
+    defaultLevels?: Array<"admin" | "user" | "folder">;
+    /**
+     * Host scope only: a look-and-feel value. When the host follows its
+     * defaults, a user it is shared with gets their own defaults for it
+     * rather than the owner's.
+     */
+    personal?: boolean;
+    /**
+     * Host scope only: the lowest share level whose recipients see this value
+     * in the host payload. Defaults to "connect", everyone who sees the host.
+     */
+    shareRead?: "connect" | "view" | "edit" | "manage";
+    /** Host scope only: only the host's owner may change it. */
+    ownerOnly?: boolean;
+    /**
+     * JSON fields only: keys inside the stored object that hold secrets, such
+     * as a gateway password. Core clears them from exports like any secret.
+     */
+    secretKeys?: string[];
+    /**
+     * Stored and validated like any field, but not drawn by the generic
+     * settings form, because the plugin edits it in its own UI (a host editor
+     * section).
+     */
+    hidden?: boolean;
+}
+export interface PluginHostSettingsContribution {
+    /** Boolean field rendered first, gating the rest of the section. */
+    enableKey?: string;
+    enableLabelKey?: string;
+    enableDescriptionKey?: string;
+    /** What the enable switch reads before a host saves it. Off by default. */
+    enableDefault?: boolean;
+    /** Host editor strip the generated tab sits in. Defaults to "top". */
+    editorGroup?: "top" | "ssh";
+    /** Position among that strip's tabs, core ones included. */
+    editorOrder?: number;
+    fields: PluginSettingsField[];
+}
+export interface PluginSettingsContribution {
+    admin?: PluginSettingsField[];
+    user?: PluginSettingsField[];
+    host?: PluginHostSettingsContribution;
+}
+/**
+ * What a plugin adds to sign-in and SSH auth. Declared so core can tell who
+ * owns an auth type or factor even while the plugin is disabled, and so the
+ * login screen knows which bundles it needs before anyone has signed in.
+ */
+export interface PluginAuthContribution {
+    /** Values of ssh_data.auth_type this plugin provides. */
+    sshAuthTypes?: string[];
+    /** Login method ids. */
+    loginMethods?: string[];
+    /** Second factor ids. */
+    secondFactors?: string[];
+    /** Schemes this plugin resolves for "<scheme>://..." secret references, e.g. "op". */
+    secretSchemes?: string[];
+    /** Keyboard-interactive handler ids, e.g. "warpgate". */
+    keyboardInteractive?: string[];
+}
+export interface PluginContributions {
+    tabs?: PluginTabContribution[];
+    panels?: PluginViewContribution[];
+    dashboardCards?: PluginViewContribution[];
+    /**
+     * The frontend also runs on anonymous guest pages (shared-session and
+     * collab links), where it is activated with app.guest set.
+     */
+    guest?: boolean;
+    /**
+     * `?view=` names an anonymous guest page may open. Each must be served by a
+     * tab's `standalone` component. Needs `guest: true`.
+     */
+    guestViews?: string[];
+    actions?: PluginActionContribution[];
+    actionSlots?: PluginActionSlot[];
+    permissions?: PluginPermissionContribution[];
+    settings?: PluginSettingsContribution;
+    /**
+     * A host-editor checkbox backed by a boolean column on the host record.
+     * A5/A6/A7 reshape this; it stays in v2 because remote-desktop, docker,
+     * proxmox and web-endpoint ship it today.
+     */
+    hostCapability?: HostCapabilityContribution | HostCapabilityContribution[];
+    auth?: PluginAuthContribution;
+    http?: PluginHttpContribution;
+    /**
+     * This plugin's Appearance defaults for each interface preset, read in the
+     * frontend with usePluginUiPreferences. Every preset names the same keys;
+     * values are booleans, numbers, strings or string arrays.
+     */
+    uiPresets?: Record<"simple" | "balanced" | "advanced", Record<string, unknown>>;
+    /**
+     * Wire names of the sync entities this plugin registers with
+     * ctx.sync.registerEntity, so a server can name them while the plugin is
+     * off and a desktop can list them in its sync settings.
+     */
+    syncEntities?: string[];
+    /**
+     * Other plugins' action, slot and extension point ids this plugin calls,
+     * fills or extends. Declaration only: nothing breaks when the owner is
+     * missing, but the coupling is written down where tools and people can
+     * see it.
+     */
+    uses?: string[];
+    /**
+     * Keybinding actions this plugin adds to Appearance > Keybindings, with
+     * the parameters a saved binding carries. Core validates saved bindings
+     * against these without running plugin code, and translates a parameter
+     * naming a sync entity over sync.
+     */
+    keybindingActions?: PluginKeybindingActionContribution[];
+    /**
+     * Connection protocols whose per-host login core stores, encrypts,
+     * shares, exports and syncs for this plugin, read back with
+     * ctx.credentials.resolveHostProtocol.
+     */
+    protocols?: PluginProtocolContribution[];
+}
+/** A field a protocol login carries besides username and password. */
+export interface PluginProtocolCredentialField {
+    key: string;
+    /** Encrypted with the owner's data key and never sent to a browser. */
+    secret?: boolean;
+}
+export interface PluginProtocolContribution {
+    /** Stored with each login. Never change it once hosts use it. */
+    id: string;
+    credentialFields?: PluginProtocolCredentialField[];
+    /**
+     * The port an import row without one gets, for a host whose main
+     * protocol this is.
+     */
+    defaultPort?: number;
+    /**
+     * What the owner's login falls back to from the host's own SSH login
+     * when the protocol login leaves it empty.
+     */
+    hostLoginFallback?: Array<"username" | "password">;
+}
+/** Protocol ids core keeps for itself. */
+export declare const RESERVED_PROTOCOL_IDS: readonly string[];
+/** Login keys a declared credential field may not reuse. */
+export declare const RESERVED_PROTOCOL_FIELD_KEYS: readonly string[];
+/** One parameter a saved keybinding action carries next to its type. */
+export interface PluginKeybindingParam {
+    type: "string" | "boolean";
+    required?: boolean;
+    /** A regular expression a string value must match. */
+    pattern?: string;
+    maxLength?: number;
+    /**
+     * The value is a local row id of this sync entity, stored as a string.
+     * Sync sends the row's syncId instead.
+     */
+    syncEntity?: string;
+}
+export interface PluginKeybindingActionContribution {
+    /**
+     * Stored as the binding's action.type. New actions use
+     * "<plugin id>.<name>"; the bundled ones keep their 2.8 names.
+     */
+    id: string;
+    params?: Record<string, PluginKeybindingParam>;
+}
+/** Keybinding action types the shell runs itself; no plugin may declare them. */
+export declare const CORE_KEYBINDING_ACTIONS: readonly string[];
+/**
+ * How a desktop linked to a server treats this plugin.
+ * - "mirror": follows the server, installed and switched on or off with it.
+ * - "local": each desktop decides for itself (a serial port is local).
+ * - "server": only makes sense on a server, never runs on a linked desktop.
+ */
+export type PluginDesktopMode = "mirror" | "local" | "server";
+export declare const PLUGIN_DESKTOP_MODES: readonly PluginDesktopMode[];
+export interface PluginHttpContribution {
+    /**
+     * Old URLs something outside Termix still calls (a webhook a third party
+     * posts to). Each must start with "/<plugin id>/"; a request under it is
+     * served by this plugin's router with that prefix removed, so
+     * "/automations/webhook/x" reaches the route "/webhook/x". Core routes win
+     * a clash.
+     */
+    legacyPaths?: string[];
+    /**
+     * Old URLs outside the plugin's namespace that something outside Termix
+     * still sends people to (an identity provider's callback, a published
+     * resolver URL). A request at `from`, or under it, is redirected to `to`
+     * under /plugin-api/<id>/ with the rest of the path and the query kept.
+     * Core routes win a clash.
+     */
+    legacyRedirects?: PluginLegacyRedirect[];
+    /**
+     * An admin may call this plugin's routes on behalf of another user with
+     * the X-Admin-Target-User header (the admin "manage user" panel). Without
+     * it core refuses the header on every route under /plugin-api/<id>/.
+     */
+    adminImpersonation?: boolean;
+}
+export interface PluginLegacyRedirect {
+    /** An absolute path, e.g. "/users/oidc/callback". */
+    from: string;
+    /** A path in this plugin's router, e.g. "/callback". */
+    to: string;
+    /** 307 (the default) or 308 for a permanent move. */
+    status?: 307 | 308;
+}
+export interface PluginManifest {
+    id: string;
+    name: string;
+    version: string;
+    description: string;
+    author: PluginAuthor;
+    license: string;
+    repository?: string;
+    category: string;
+    icon?: string;
+    engine: PluginEngine;
+    /** Catalog capability ids. */
+    capabilities: string[];
+    /** pluginId -> semver range. A missing one blocks activation. */
+    dependencies?: Record<string, string>;
+    /** pluginId -> semver range. A missing one is normal. */
+    optionalDependencies?: Record<string, string>;
+    provides?: PluginServiceProvide[];
+    requires?: PluginServiceRequire[];
+    providesSecret?: PluginSecretProvide[];
+    requiresSecret?: PluginSecretRequire[];
+    contributes?: PluginContributions;
+    /** Built backend entry, relative to the plugin root. */
+    backend?: string;
+    /** Built frontend entry, relative to the plugin root. */
+    frontend?: string;
+    /** Locales directory, relative to the plugin root. */
+    locales?: string;
+    platforms?: string[];
+    /**
+     * Bare npm package names carrying a native (.node) binding. The CLI build
+     * never bundles them: they stay a real dependency in the plugin's own
+     * package.json and are resolved from node_modules at runtime instead,
+     * because esbuild bundling a native addon breaks the relative path it uses
+     * to locate its compiled binary.
+     */
+    nativeDependencies?: string[];
+    /** How a linked desktop treats this plugin. Defaults to "mirror". */
+    desktop?: PluginDesktopMode;
+}
+export declare const DEFAULT_BACKEND_ENTRY = "dist/backend.js";
+export declare const DEFAULT_FRONTEND_ENTRY = "dist/frontend.js";
+export declare const DEFAULT_LOCALES_DIR = "locales";
+export declare function validateManifest(manifest: unknown): string[];
+export declare const PROTOCOL_ID_PATTERN: RegExp;
+export declare const PROTOCOL_FIELD_KEY_PATTERN: RegExp;
+/**
+ * Checks one saved keybinding action against the parameters its declaration
+ * lists. A parameter the declaration does not list is refused, so a binding
+ * cannot carry arbitrary data under a declared type.
+ */
+export declare function validateKeybindingActionParams(action: Record<string, unknown>, declaration: PluginKeybindingActionContribution): boolean;
+export interface ParsedManifest {
+    manifest?: PluginManifest;
+    errors: string[];
+}
+/**
+ * Validates, then applies the cross-field rules a JSON schema cannot express
+ * and fills in the entry-point defaults.
+ */
+export declare function parseManifest(raw: unknown): ParsedManifest;