@termix-ssh/plugin-sdk 1.0.0

package/dist/host/types/src/types/host-defaults.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Host defaults: the keys a host can inherit and how their values compare.
+ *
+ * Shared by the backend (resolution, materializing, the upgrade) and the host
+ * editor (which fields show an inherited badge). A key is namespaced:
+ * "core.<key>" for core's own fields, "<pluginId>.<field>" for a plugin's host
+ * setting. Values are in the host API's shape, never in column form.
+ */
+export type HostDefaultsLevel = "admin" | "user" | "folder";
+export declare const HOST_DEFAULTS_LEVELS: readonly HostDefaultsLevel[];
+export declare const CORE_NAMESPACE = "core";
+/** Namespace -> keys the host sets itself. */
+export type DefaultOverrides = Record<string, string[]>;
+export interface HostDefaultSource {
+    level: HostDefaultsLevel | "builtin";
+    folderId?: number;
+    folderName?: string;
+}
+export interface ResolvedHostDefault {
+    value: unknown;
+    source: HostDefaultSource;
+}
+export interface HostAuthDefault {
+    authType: string;
+    credentialId: number | null;
+    overrideCredentialUsername: boolean;
+    agentSocketPath: string | null;
+    agentIdentity: string | null;
+}
+export interface HostSocks5Default {
+    useSocks5: boolean;
+    socks5Host: string | null;
+    socks5Port: number | null;
+    socks5Username: string | null;
+    socks5ProxyChain: unknown[] | null;
+}
+export interface CoreHostDefault {
+    key: string;
+    /** Levels allowed to set it. A value that points at a user's row is never admin. */
+    levels: readonly HostDefaultsLevel[];
+    /** What a host gets when no level sets it. Undefined means nothing to inherit. */
+    builtin: unknown;
+    /** One canonical form, so two spellings of the same value compare equal. */
+    normalize: (value: unknown) => unknown;
+}
+/** Auth types whose login lives on the host itself, so it cannot be a default. */
+export declare const SECRET_AUTH_TYPES: string[];
+export declare function normalizeAuthDefault(value: unknown): HostAuthDefault | null;
+export declare function normalizeSocks5Default(value: unknown): HostSocks5Default;
+export declare const CORE_HOST_DEFAULTS: readonly CoreHostDefault[];
+export declare function findCoreHostDefault(key: string): CoreHostDefault | undefined;
+/** "core.sshPort" -> ["core", "sshPort"]. The plugin id never has a dot. */
+export declare function splitDefaultKey(fullKey: string): [string, string];
+export declare function joinDefaultKey(namespace: string, key: string): string;
+/** JSON with sorted object keys, so equal values stringify the same. */
+export declare function stableStringify(value: unknown): string;
+export declare function defaultValuesEqual(a: unknown, b: unknown): boolean;
+/** A stored or sent overrides value, or null when it is not one. */
+export declare function parseDefaultOverrides(raw: unknown): DefaultOverrides | null;
+export declare function isDefaultOverridden(overrides: DefaultOverrides | null | undefined, namespace: string, key: string): boolean;

package/dist/host/types/src/types/host-sidebar-preferences.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Host sidebar preferences model. Shared by the frontend sidebar and the
+ * backend preferences endpoint (no framework imports, mirrors
+ * ./host-metrics.ts's dependency-free convention). Replaces the ~10
+ * independent localStorage keys/custom events the sidebar used to manage
+ * individually.
+ *
+ * SortKey and StatusColorScheme are duplicated here (rather than imported
+ * from src/ui/sidebar/host-sort.ts / src/ui/hooks/use-status-color-scheme.ts)
+ * because those files use the "../ui" frontend path alias, which the backend's
+ * NodeNext build cannot resolve. Keep the values below in sync with those
+ * two files.
+ */
+export declare const HOST_SIDEBAR_PREFS_VERSION = 1;
+export type SortKey = "default" | "name-asc" | "name-desc" | "ip-asc" | "ip-desc" | "status-online" | "status-offline" | "manual";
+export type StatusColorScheme = "accent" | "status";
+export type HostGroupKey = "folder" | "tag" | "status" | "protocol" | "auth";
+export type HostDensity = "comfortable" | "compact";
+export type HostTrayTrigger = "always" | "hover" | "click" | "actionsOnly";
+/** What clicking a host does when it already has an open tab. */
+export type HostClickBehavior = "newTab" | "focusExisting" | "focusExistingDoubleClickNew";
+export interface HostSidebarFilterState {
+    status: ("online" | "offline" | "pinned")[];
+    /** SSH auth type ids; plugins add their own. */
+    authType: string[];
+    /** "ssh" or a plugin protocol id. */
+    protocol: string[];
+    /** Plugin ids whose host switch must be on. */
+    features: string[];
+    tags: string[];
+}
+export interface HostSidebarDisplayPreferences {
+    density: HostDensity;
+    showTags: boolean;
+    trayTrigger: HostTrayTrigger;
+    statusColorScheme: StatusColorScheme;
+    /** When true, a host row needs a double click to launch its session. */
+    openOnDoubleClick: boolean;
+    /** When false, nested folders hide the parent-path breadcrumb before their name. */
+    showFolderPaths: boolean;
+    hostClickBehavior: HostClickBehavior;
+}
+export interface HostSidebarPreferences {
+    version: number;
+    sort: {
+        key: SortKey;
+        pinnedFirst: boolean;
+    };
+    groupKey: HostGroupKey;
+    filters: HostSidebarFilterState;
+    openFolders: string[];
+    display: HostSidebarDisplayPreferences;
+}
+export declare function defaultHostSidebarPreferences(): HostSidebarPreferences;
+export declare function sanitizeHostSidebarPreferences(input: unknown): HostSidebarPreferences;

package/dist/host/types/src/types/index.d.ts

@@ -0,0 +1,298 @@
+import type { HostProtocolAuthSummary, HostProtocolAuthType, HostSshOptions } from "@termix-ssh/plugin-sdk/frontend";
+import type { Request } from "express";
+import type { RefObject } from "react";
+import type { HostAuthOverrides } from "./auth-protocols.js";
+import type { DefaultOverrides } from "./host-defaults.js";
+export type { AuthOverrideProtocol, HostAuthOverrideState, HostAuthOverrides, } from "./auth-protocols.js";
+/**
+ * Core's own SSH auth types, plus whatever a plugin registers through
+ * ctx.auth (the owning plugin decides the name).
+ */
+export type SSHAuthType = "password" | "key" | "credential" | "none" | "agent" | (string & {});
+export type { HostProtocolAuthSummary, HostProtocolAuthType };
+/** One plugin protocol's login in a host write. */
+export interface HostProtocolAuthInput {
+    authType?: HostProtocolAuthType;
+    credentialId?: number | null;
+    username?: string | null;
+    /** Left out to keep the saved password. */
+    password?: string | null;
+    /** Declared credential fields; one left out keeps its value. */
+    fields?: Record<string, string | null>;
+}
+export interface JumpHost {
+    hostId: number;
+}
+export type Host = {
+    id: number;
+    name: string;
+    ip: string;
+    port: number;
+    username: string;
+    folder: string;
+    tags: string[];
+    pin: boolean;
+    authType: SSHAuthType;
+    shareSshAuth?: boolean;
+    password?: string;
+    key?: string;
+    keyPassword?: string;
+    keyType?: string;
+    sudoPassword?: string;
+    forceKeyboardInteractive?: boolean;
+    credentialId?: number;
+    overrideCredentialUsername?: boolean;
+    userId?: string;
+    jumpHosts?: JumpHost[];
+    statusCheckEnabled?: boolean;
+    /** Seconds between status checks; null follows the global setting. */
+    statusCheckInterval?: number | null;
+    terminalConfig?: HostTerminalConfig;
+    sshOptions?: HostSshOptions;
+    notes?: string;
+    useSocks5?: boolean;
+    socks5Host?: string;
+    socks5Port?: number;
+    socks5Username?: string;
+    socks5Password?: string;
+    socks5ProxyChain?: ProxyNode[];
+    portKnockSequence?: Array<{
+        port: number;
+        protocol?: "tcp" | "udp";
+        delay?: number;
+    }>;
+    /** "ssh", or the id of the plugin protocol a host without SSH uses. */
+    connectionType?: string;
+    enableSsh?: boolean;
+    sshPort?: number;
+    /** Each plugin protocol's login, secrets left out. */
+    protocolAuth?: Record<string, HostProtocolAuthSummary>;
+    /**
+     * Stable identity across a desktop/server sync pair. `id` is an
+     * autoincrement local to whichever database produced the row, so it cannot
+     * name the same host on both sides; this can. Absent on hosts that have
+     * never been part of a sync.
+     */
+    syncId?: string | null;
+    createdAt: string;
+    updatedAt: string;
+    sortOrder?: number | null;
+    connectionOrigin?: "local" | "remote" | null;
+    /** Assigned when a host is opened in a tab; distinguishes duplicate tabs. */
+    instanceId?: string;
+    hasKey?: boolean;
+    hasKeyPassword?: boolean;
+    hasPassword?: boolean;
+    hasSudoPassword?: boolean;
+    isShared?: boolean;
+    authOverrides?: HostAuthOverrides;
+    permissionLevel?: "connect" | "view" | "edit" | "manage";
+    sharedExpiresAt?: string;
+    ownerUsername?: string;
+    /** A read-only copy of a host shared with the linked account. */
+    sharedCopy?: boolean;
+    /** Desktop only: kept on this device, never synced to the server. */
+    localOnly?: boolean;
+    /** Enabled plugins' host-scope settings, keyed by plugin id. Secrets redacted. */
+    pluginSettings?: Record<string, Record<string, unknown>>;
+    /** Host default keys this host sets itself, per namespace. */
+    defaultOverrides?: DefaultOverrides | null;
+};
+export interface JumpHostData {
+    hostId: number;
+}
+export interface ProxyNode {
+    host: string;
+    port: number;
+    /**
+     * The host editor writes "socks4"/"socks5"/"http", while proxy-helper.ts
+     * tests for "http" and casts everything else to 4|5 before handing it to the
+     * socks client. The two spellings have never agreed; typed as the union of
+     * what is actually stored rather than pretending one side is right.
+     */
+    type: 4 | 5 | "http" | "socks4" | "socks5";
+    username?: string;
+    password?: string;
+}
+export interface HostData {
+    /** Host default keys the host sets itself, per namespace. Every other key follows its defaults. */
+    defaultOverrides?: DefaultOverrides | null;
+    name?: string;
+    ip: string;
+    port: number;
+    username: string;
+    folder?: string;
+    /** Sub-host nesting: mutually exclusive with folder. */
+    parentHostId?: number | string | null;
+    tags?: string[];
+    pin?: boolean;
+    authType: SSHAuthType;
+    shareSshAuth?: boolean;
+    password?: string;
+    key?: File | string | null;
+    keyPassword?: string;
+    keyType?: string;
+    sudoPassword?: string;
+    credentialId?: number | null;
+    connectionOrigin?: "local" | "remote" | null;
+    overrideCredentialUsername?: boolean;
+    forceKeyboardInteractive?: boolean;
+    jumpHosts?: JumpHostData[];
+    statusCheckEnabled?: boolean;
+    /** Seconds between status checks; null follows the global setting. */
+    statusCheckInterval?: number | null;
+    terminalConfig?: HostTerminalConfig;
+    sshOptions?: HostSshOptions;
+    notes?: string;
+    useSocks5?: boolean;
+    socks5Host?: string;
+    socks5Port?: number;
+    socks5Username?: string;
+    socks5Password?: string;
+    socks5ProxyChain?: ProxyNode[];
+    portKnockSequence?: Array<{
+        port: number;
+        protocol?: "tcp" | "udp";
+        delay?: number;
+    }>;
+    /** "ssh", or the id of the plugin protocol a host without SSH uses. */
+    connectionType?: string;
+    enableSsh?: boolean;
+    sshPort?: number;
+    /**
+     * Plugin protocol logins to write, keyed by protocol id. A key left out
+     * keeps its login, null removes it, and a field left out keeps its value.
+     */
+    protocolAuth?: Record<string, HostProtocolAuthInput | null>;
+    /** Desktop only: kept on this device, never synced to the server. */
+    localOnly?: boolean;
+}
+export type SSHHost = Host;
+export type SSHHostData = HostData;
+export interface SSHFolder {
+    id: number;
+    userId: string;
+    name: string;
+    color?: string;
+    icon?: string;
+    credentialId?: number | null;
+    sortOrder?: number | null;
+    /** Desktop only: the folder and its hosts stay on this device. */
+    localOnly?: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface Credential {
+    id: number;
+    name: string;
+    description?: string;
+    folder?: string;
+    tags: string[];
+    authType: "password" | "key";
+    username?: string;
+    password?: string;
+    key?: string;
+    publicKey?: string;
+    /** CA-signed certificate file content (e.g. id_ed25519-cert.pub) */
+    certPublicKey?: string;
+    /** True when a cert is stored but certPublicKey content is redacted in list responses */
+    hasCertPublicKey?: boolean;
+    keyPassword?: string;
+    keyType?: string;
+    usageCount: number;
+    lastUsed?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CredentialBackend {
+    id: number;
+    userId: string;
+    name: string;
+    description: string | null;
+    folder: string | null;
+    tags: string;
+    authType: "password" | "key";
+    username: string | null;
+    password: string | null;
+    key: string;
+    privateKey?: string;
+    publicKey?: string;
+    /** CA-signed certificate file content (e.g. id_ed25519-cert.pub) */
+    certPublicKey?: string;
+    keyPassword: string | null;
+    keyType?: string;
+    detectedKeyType: string;
+    usageCount: number;
+    lastUsed: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * What 2.8 kept in ssh_data.terminal_config. Core reads none of it any more:
+ * the terminal's look and behavior and the startup command are plugins' host
+ * settings, and the connection options have their own column (sshOptions).
+ */
+export type HostTerminalConfig = Record<string, unknown>;
+export type { HostSshOptions } from "@termix-ssh/plugin-sdk/frontend";
+export interface TabContextTab {
+    id: number;
+    instanceId?: string;
+    /** A core tab type or one a plugin registered. */
+    type: string;
+    title: string;
+    hostConfig?: SSHHost;
+    terminalRef?: RefObject<TerminalRefHandle | null>;
+    initialTab?: string;
+    _updateTimestamp?: number;
+    connectionConfig?: Record<string, unknown>;
+}
+export interface TerminalRefHandle {
+    disconnect?: () => void;
+    reconnect?: () => void;
+    isConnected?: () => boolean;
+    fit?: () => void;
+    sendInput?: (data: string) => void;
+    subscribeOutput?: (listener: (data: string) => void) => () => void;
+    notifyResize?: () => void;
+    refresh?: () => void;
+}
+export interface AuthenticatedRequest extends Request {
+    userId: string;
+    sessionId?: string;
+    apiKeyId?: string;
+    actingAdminUserId?: string;
+    user?: {
+        id: string;
+        username: string;
+        isAdmin: boolean;
+    };
+}
+export interface GitHubAsset {
+    id: number;
+    name: string;
+    size: number;
+    download_count: number;
+    browser_download_url: string;
+}
+export interface GitHubRelease {
+    id: number;
+    tag_name: string;
+    name: string;
+    body: string;
+    published_at: string;
+    html_url: string;
+    assets: GitHubAsset[];
+    prerelease: boolean;
+    draft: boolean;
+}
+export interface GitHubAPIResponse<T> {
+    data: T;
+    cached: boolean;
+    cache_age?: number;
+    timestamp?: number;
+}
+export interface CacheEntry<T = unknown> {
+    data: T;
+    timestamp: number;
+    expiresAt: number;
+}

package/dist/host/types/src/types/keybindings.d.ts

@@ -0,0 +1,27 @@
+export interface KeyCombo {
+    key: string;
+    isCode: boolean;
+    ctrl: boolean;
+    alt: boolean;
+    shift: boolean;
+    meta: boolean;
+}
+/**
+ * The shell's own actions (nextTab, previousTab, openCommandPalette,
+ * reconnectSession) or one a plugin declared in contributes.keybindingActions.
+ */
+export type KeybindingActionType = string;
+/** A bound action: its type plus the parameters its declaration lists. */
+export interface KeybindingAction {
+    type: KeybindingActionType;
+    [param: string]: unknown;
+}
+export interface CustomKeybinding {
+    id: string;
+    combo: KeyCombo;
+    action: KeybindingAction;
+    enabled: boolean;
+    overridesDefaultId?: string;
+    createdAt: string;
+    updatedAt: string;
+}

package/dist/host/types/src/types/ui-preferences.d.ts

@@ -0,0 +1,102 @@
+/**
+ * App-wide UI complexity preferences. Shared by the frontend UI preferences
+ * context and the backend preferences endpoint (no framework imports, mirrors
+ * ./host-sidebar-preferences.ts's dependency-free convention -- the backend's
+ * NodeNext build cannot resolve the "../ui" frontend path alias).
+ *
+ * The model stores the user's *intent* -- a preset plus the individual knobs
+ * they have deliberately changed -- not a second copy of values other stores
+ * already own. Areas whose knobs already live somewhere else (host sidebar
+ * blob, user_preferences.hiddenRailTabs, a handful of localStorage keys) are
+ * seeded from the preset when it changes; reads keep going to the existing
+ * store. See applyPresetSideEffects on the frontend.
+ *
+ * "balanced" is exactly today's behavior. Every value in PRESETS.balanced is
+ * transcribed from the defaults that were already in the code, so existing
+ * users who land on it see no change at all.
+ */
+/** 2: the docker and host metrics areas moved to their plugins. */
+export declare const UI_PREFERENCES_VERSION = 3;
+/** Bump when onboarding gains steps existing users should be shown again. */
+export declare const UI_ONBOARDING_VERSION = 2;
+export type UiPreset = "simple" | "balanced" | "advanced" | "custom";
+export type UiAreaKey = "chrome" | "hostList" | "credentialList" | "rail" | "dashboard" | "hostEditor";
+export type UiDensity = "comfortable" | "compact";
+export type UiTrayTrigger = "always" | "hover" | "click" | "actionsOnly";
+export type UiRowActions = "essential" | "full";
+export type UiEmptyStateVerbosity = "minimal" | "guided";
+export type UiHostEditorMode = "simple" | "full";
+export interface UiChromePreferences {
+    showBreadcrumbs: boolean;
+    showStatusBar: boolean;
+    emptyStateVerbosity: UiEmptyStateVerbosity;
+}
+export interface UiHostListPreferences {
+    density: UiDensity;
+    showTags: boolean;
+    showResourceBars: boolean;
+    showStatusStripes: boolean;
+    trayTrigger: UiTrayTrigger;
+    rowActions: UiRowActions;
+}
+export interface UiCredentialListPreferences {
+    density: UiDensity;
+    showTags: boolean;
+}
+export interface UiRailPreferences {
+    hiddenTabs: string[];
+    /**
+     * Also hide every plugin rail item that does not set simplePreset. Plugin
+     * items are only known at runtime, so the preset cannot list them.
+     */
+    hidePluginItems?: boolean;
+}
+export interface UiDashboardPreferences {
+    enabledCards: string[];
+}
+export interface UiHostEditorPreferences {
+    mode: UiHostEditorMode;
+}
+export interface UiAreaPreferences {
+    chrome: UiChromePreferences;
+    hostList: UiHostListPreferences;
+    credentialList: UiCredentialListPreferences;
+    rail: UiRailPreferences;
+    dashboard: UiDashboardPreferences;
+    hostEditor: UiHostEditorPreferences;
+}
+/** A plugin's own area, keyed "plugin:<id>", holding what it declared in contributes.uiPresets. */
+export type UiPluginAreaKey = `plugin:${string}`;
+export type UiOverrides = {
+    [A in UiAreaKey]?: Partial<UiAreaPreferences[A]>;
+} & {
+    [key: UiPluginAreaKey]: Record<string, unknown>;
+};
+export interface UiOnboardingState {
+    /** 0 means "never completed". Compared against UI_ONBOARDING_VERSION. */
+    completedVersion: number;
+    completedAt: string | null;
+    skipped: boolean;
+}
+export interface UiPreferences {
+    version: number;
+    preset: UiPreset;
+    overrides: UiOverrides;
+    onboarding: UiOnboardingState;
+}
+export declare const PRESETS: Record<Exclude<UiPreset, "custom">, UiAreaPreferences>;
+export declare const UI_AREA_KEYS: UiAreaKey[];
+export declare function sanitizeUiOverrides(input: unknown): UiOverrides;
+export declare function defaultUiPreferences(): UiPreferences;
+export declare function sanitizeUiPreferences(input: unknown): UiPreferences;
+/**
+ * Effective values for one area: preset defaults with the user's overrides
+ * layered on top. "custom" only labels a diverged state, so it re-bases on
+ * balanced rather than carrying a fourth value table.
+ */
+export declare function resolveArea<A extends UiAreaKey>(preferences: UiPreferences, area: A): UiAreaPreferences[A];
+/** The presets a plugin declares in contributes.uiPresets. */
+export type UiPluginPresets = Record<Exclude<UiPreset, "custom">, Record<string, unknown>>;
+/** A plugin area's values: its preset for the user's level, then overrides. */
+export declare function resolvePluginArea(preferences: UiPreferences, pluginId: string, presets: UiPluginPresets | undefined): Record<string, unknown>;
+export declare function hasUiOverrides(preferences: UiPreferences): boolean;