feat: move desktop, status, import, audit and branding features into plugins

packages/plugin-sdk/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 1.0.13
+
+Plugin API 1.5.0.
+
+### Added
+
+- `runtime: "desktop"` in the manifest for a plugin that only loads on the desktop app
+- `desktop:local` and `ctx.desktop.local`: file system, local shell and machine info on the desktop app's own backend
+- `ctx.audit.subscribe`, `ctx.audit.list` and `ctx.audit.exportBatches` under `audit:read`
+- `ctx.hosts.importMany`, `importSshConfig`, `exportMany` and `registerImportNormalizer`, with the `hosts:export` capability
+- `ctx.credentials.publicKey` and `resolveKeyRefs`, `ctx.ssh.exec`, and `@termix-ssh/plugin-sdk/ssh-keys`
+- `ctx.hosts.status.provide` and `ctx.hosts.activity.provide` so a plugin can own host status and recent activity, with `ctx.network.tcpProbe`, `ctx.ssh.probe`, `ctx.hosts.probeTargets` and `ctx.hosts.sessionActive`
+- `registerHostStatusIndicator` and `registerHostEditorToolbarItem`, and `order` for host badges
+- Onboarding steps can sit in a `start` section, take a `position` and `replaces` a core step
+- A plugin can provide the app name, tagline and logo through the `<id>.brandingProvider` registry key
+
 ## 1.0.12
 
 Plugin API 1.4.0.

packages/plugin-sdk/PLUGIN-GUIDE.md

@@ -1,6 +1,6 @@
 # Termix plugin guide
 
-SDK 1.0.12 | Plugin API 1.4.0
+SDK 1.0.13 | Plugin API 1.5.0
 
 This guide is for anyone, person or AI coding tool, building a Termix plugin. It ships inside
 `@termix-ssh/plugin-sdk`, so the copy in your `node_modules` always matches the SDK you have installed.
@@ -325,6 +325,24 @@ try {
 commands. `@termix-ssh/plugin-sdk/host-commands` has helpers to detect the OS and run package manager and
 sudo commands. Hosts from `ctx.hosts` never carry secrets. Pass the host or its id to `ctx.ssh`.
 
+### The desktop app
+
+Set `"runtime": "desktop"` in the manifest for a plugin that only makes sense on a desktop app. It never
+loads on a server, ignores server sync and may declare `desktop:local`. Any plugin can declare
+`desktop:local` and check `ctx.desktop.local.available()` at runtime.
+
+`ctx.desktop.local` works on the desktop app's own backend only:
+
+- `info()`: home folder, platform, user data folder, backend port and the linked server (url and token) or null
+- `fs`: `list`, `mkdir`, `createFile`, `rename`, `ensureDir`, `exists`, `walk`, `trash`, `reveal`, `open`,
+  `openRead` and `openDownload`. Downloads stay inside the folder the user picked, links in it are refused and
+  an existing file is never replaced by accident
+- `pty.spawn()`: a local shell, stopped when the plugin stops
+- `pluginFetch(origin, subPath, init)`: calls this plugin's own routes on the desktop's backend ("local") or the linked server ("remote") as the acting user. Bodies can be streams, so a plugin can move big files without the renderer
+
+Use `ctx.audit.subscribe`, `list` and `exportBatches` (`audit:read`) to read the audit trail. Subscribers
+are called after a line is accepted and never delay the action that wrote it.
+
 ### Events, timers, alerts, services
 
 ```ts
@@ -470,13 +488,15 @@ your plugin's error boundary and Suspense.
 | `registerHostEditorSection`                                                        | Your own host editor section (host settings get one for free)     |
 | `registerHostProtocol`                                                             | A connection protocol next to SSH                                 |
 | `registerHostBadge`, `registerHostContextMenuItem`                                 | Badges and menu items on host rows                                |
+| `registerHostStatusIndicator`                                                      | The status dot or stripe on a host row (a layout draws it)        |
+| `registerHostEditorToolbarItem`                                                    | A control in the host editor toolbar (a layout draws it)          |
 | `registerPaletteEntry`, `registerPaletteGroup`                                     | Command palette entries                                           |
 | `registerKeybindingAction`, `registerKeybindingDefault`                            | Bindable actions                                                  |
 | `registerSettingsComponent`                                                        | A component for a `custom` settings field                         |
 | `registerAction`, `invokeAction`                                                   | Actions across plugins                                            |
 | `registerSlotContribution`, `declareActionSlot`                                    | Fill or own a UI slot                                             |
 | `registerComponent`, `registerExtension`                                           | Offer a component by id, add to an extension point                |
-| `registerOnboardingStep`                                                           | A first run setup step                                            |
+| `registerOnboardingStep`                                                           | A first run setup step (`section`, `position`, `replaces`)        |
 | `registerLoginMethod`, `registerSecondFactorUI`, `registerSshAuthEditor`           | Sign in UI                                                        |
 | `registerLayout`                                                                   | A whole-app layout (`contributes.layouts`, API 1.4)               |
 | `api`                                                                              | Axios client for your `/plugin-api/<id>/` routes, auth included   |
@@ -484,6 +504,16 @@ your plugin's error boundary and Suspense.
 | `docs`, `tabs`, `confirm`, `listHosts`, `getHost`, `t`, `hasPermission`, `desktop` | Helpers                                                           |
 | `onSettingsChanged`, `onDispose`                                                   | Hooks                                                             |
 
+Badges, status indicators and toolbar items take `{ id, when(host), component, order? }`; lower `order`
+comes first. An onboarding step sits in a section (`start`, `setup`, `explore`, `security`) or at an exact
+`position` from 1 to 99. `replaces: ["preset"]` lists older step keys the step took over, so people who saw
+those are not shown it again.
+
+Branding: a plugin that owns the app name, tagline and logo provides
+`ctx.registry.provide("<id>.brandingProvider", async () => ({ appName, tagline, logo }))` in its backend.
+Core reads it for `GET /users/branding` (the login page, the browser tab and the sync server name) and falls
+back to "Termix" with no logo when no plugin provides one. `logo` is a PNG data URL or null.
+
 Hooks from `@termix-ssh/plugin-sdk/frontend`: `useTranslation`, `usePermission`, `useSettings`, `useHost`,
 `useHosts`, `usePluginApi`, `useCurrentUser`, `useTheme`, `useToast`, `useDocsUrl`, `useTabs`,
 `useSlotContributions`, `useSshAuthTypes`, `useExtensions`, `useShell`.
@@ -828,60 +858,66 @@ To run your own registry instead, see https://docs.termix.site/develop/registrie
 
 ## SDK entry points
 
-| Import                                                               | What it is                                                            |
-| -------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| `@termix-ssh/plugin-sdk/backend`                                     | `PluginContext` and the backend types                                 |
-| `@termix-ssh/plugin-sdk/frontend`                                    | `TermixApp`, `TabProps` and the hooks                                 |
-| `@termix-ssh/plugin-sdk/ui`                                          | The UI kit, served by Termix at runtime                               |
-| `@termix-ssh/plugin-sdk/db`                                          | `defineTable` and column builders                                     |
-| `@termix-ssh/plugin-sdk/manifest`                                    | `PluginManifest` type and manifest checks                             |
-| `@termix-ssh/plugin-sdk/capabilities`                                | The capability catalog                                                |
-| `@termix-ssh/plugin-sdk/settings`                                    | Settings field validation                                             |
-| `@termix-ssh/plugin-sdk/testing`                                     | `createMockCtx`, `createTestDb`, `renderWithApp`, `createFakeContext` |
-| `@termix-ssh/plugin-sdk/vitest-preset`                               | `pluginVitestConfig`                                                  |
-| `@termix-ssh/plugin-sdk/host-commands`                               | OS detection, package manager and sudo helpers over ssh2              |
-| `@termix-ssh/plugin-sdk/ssh-certs`                                   | `applyCertificateAuth()` for certificate based SSH auth               |
-| `@termix-ssh/plugin-sdk/desktop`                                     | The desktop app bridge, typed. Check it exists before use             |
-| `@termix-ssh/plugin-sdk/openapi`                                     | `buildOpenApi()`                                                      |
-| `@termix-ssh/plugin-sdk/changelog`                                   | Changelog parsing and checks                                          |
-| `@termix-ssh/plugin-sdk/docs`                                        | Docs link and env var helpers                                         |
-| `@termix-ssh/plugin-sdk/ddl`, `@termix-ssh/plugin-sdk/table-builder` | Table to SQL and Drizzle mapping. You rarely need these               |
+| Import                                                               | What it is                                                                                     |
+| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `@termix-ssh/plugin-sdk/backend`                                     | `PluginContext` and the backend types                                                          |
+| `@termix-ssh/plugin-sdk/frontend`                                    | `TermixApp`, `TabProps` and the hooks                                                          |
+| `@termix-ssh/plugin-sdk/ui`                                          | The UI kit, served by Termix at runtime                                                        |
+| `@termix-ssh/plugin-sdk/db`                                          | `defineTable` and column builders                                                              |
+| `@termix-ssh/plugin-sdk/manifest`                                    | `PluginManifest` type and manifest checks                                                      |
+| `@termix-ssh/plugin-sdk/capabilities`                                | The capability catalog                                                                         |
+| `@termix-ssh/plugin-sdk/settings`                                    | Settings field validation                                                                      |
+| `@termix-ssh/plugin-sdk/testing`                                     | `createMockCtx`, `createTestDb`, `renderWithApp`, `createFakeContext`                          |
+| `@termix-ssh/plugin-sdk/vitest-preset`                               | `pluginVitestConfig`                                                                           |
+| `@termix-ssh/plugin-sdk/host-commands`                               | OS detection, package manager and sudo helpers over ssh2                                       |
+| `@termix-ssh/plugin-sdk/ssh-certs`                                   | `applyCertificateAuth()` for certificate based SSH auth                                        |
+| `@termix-ssh/plugin-sdk/ssh-keys`                                    | `generateSshKeyPair()`, `detectSshKeyType()`, `publicKeyFromPrivate()`, `validateSshKeyPair()` |
+| `@termix-ssh/plugin-sdk/desktop`                                     | The desktop app bridge, typed. Check it exists before use                                      |
+| `@termix-ssh/plugin-sdk/openapi`                                     | `buildOpenApi()`                                                                               |
+| `@termix-ssh/plugin-sdk/changelog`                                   | Changelog parsing and checks                                                                   |
+| `@termix-ssh/plugin-sdk/docs`                                        | Docs link and env var helpers                                                                  |
+| `@termix-ssh/plugin-sdk/ddl`, `@termix-ssh/plugin-sdk/table-builder` | Table to SQL and Drizzle mapping. You rarely need these                                        |
 
 ## Capabilities
 
-| Capability           | Risk     | What it allows                                          |
-| -------------------- | -------- | ------------------------------------------------------- |
-| `credentials:read`   | critical | Read stored secrets for hosts the user can reach        |
-| `system:tls`         | critical | Replace the HTTPS certificate, answer CA domain checks  |
-| `ssh:connect`        | high     | Run any command on hosts, with the user's access        |
-| `process:spawn`      | high     | Run programs on the Termix server                       |
-| `users:write`        | high     | Add users and change their roles                        |
-| `users:impersonate`  | high     | Act as another user, or get a session for them, audited |
-| `db:core-refs`       | high     | Query core users, roles and hosts tables (read only)    |
-| `auth:provide`       | high     | Add login methods, second factors, SSH auth types       |
-| `device:serial`      | high     | Open serial and USB ports on the server                 |
-| `notify:hub`         | high     | Receive every alert (the alerts hub only)               |
-| `ui:layout`          | high     | Replace the whole app layout                            |
-| `hosts:write`        | medium   | Add and edit hosts                                      |
-| `credentials:use`    | medium   | Connect with saved credentials without seeing them      |
-| `credentials:write`  | medium   | Save new credentials                                    |
-| `network:outbound`   | medium   | Outbound HTTP through `ctx.fetch`                       |
-| `network:serve`      | medium   | HTTP routes and sockets                                 |
-| `network:broadcast`  | medium   | Local network broadcasts, like Wake-on-LAN              |
-| `users:read`         | medium   | Usernames, roles and UI language                        |
-| `events:core`        | medium   | Listen to core events                                   |
-| `notify:send`        | medium   | Send alerts                                             |
-| `audit:read`         | medium   | Read the audit log                                      |
-| `desktop:window`     | medium   | Open windows in the desktop app                         |
-| `hosts:read`         | low      | Read hosts the user can see                             |
-| `db:own`             | low      | Your own tables                                         |
-| `kv:own`             | low      | Small key value state                                   |
-| `files:own`          | low      | Your own folder on disk                                 |
-| `secrets:own`        | low      | Your own encrypted secrets                              |
-| `settings:read-core` | low      | Read Termix server settings                             |
-| `plugins:read`       | low      | See installed plugins                                   |
-| `ui:surface`         | low      | Add tabs, panels and settings                           |
-| `ui:theme`           | low      | Add color themes, CSS only                              |
+| Capability               | Risk     | What it allows                                          |
+| ------------------------ | -------- | ------------------------------------------------------- |
+| `credentials:read`       | critical | Read stored secrets for hosts the user can reach        |
+| `system:tls`             | critical | Replace the HTTPS certificate, answer CA domain checks  |
+| `ssh:connect`            | high     | Run any command on hosts, with the user's access        |
+| `process:spawn`          | high     | Run programs on the Termix server                       |
+| `users:write`            | high     | Add users and change their roles                        |
+| `users:impersonate`      | high     | Act as another user, or get a session for them, audited |
+| `db:core-refs`           | high     | Query core users, roles and hosts tables (read only)    |
+| `auth:provide`           | high     | Add login methods, second factors, SSH auth types       |
+| `device:serial`          | high     | Open serial and USB ports on the server                 |
+| `desktop:local`          | high     | Use the user's own computer, desktop app only           |
+| `hosts:export`           | high     | Export hosts with their saved logins                    |
+| `notify:hub`             | high     | Receive every alert (the alerts hub only)               |
+| `ui:layout`              | high     | Replace the whole app layout                            |
+| `hosts:write`            | medium   | Add and edit hosts                                      |
+| `hosts:status-provide`   | medium   | Be the source of host status dots                       |
+| `hosts:activity-provide` | medium   | Be the source of the recent activity list               |
+| `network:probe`          | medium   | Check that a host answers on a TCP port                 |
+| `credentials:use`        | medium   | Connect with saved credentials without seeing them      |
+| `credentials:write`      | medium   | Save new credentials                                    |
+| `network:outbound`       | medium   | Outbound HTTP through `ctx.fetch`                       |
+| `network:serve`          | medium   | HTTP routes and sockets                                 |
+| `network:broadcast`      | medium   | Local network broadcasts, like Wake-on-LAN              |
+| `users:read`             | medium   | Usernames, roles and UI language                        |
+| `events:core`            | medium   | Listen to core events                                   |
+| `notify:send`            | medium   | Send alerts                                             |
+| `audit:read`             | medium   | Read the audit log                                      |
+| `desktop:window`         | medium   | Open windows in the desktop app                         |
+| `hosts:read`             | low      | Read hosts the user can see                             |
+| `db:own`                 | low      | Your own tables                                         |
+| `kv:own`                 | low      | Small key value state                                   |
+| `files:own`              | low      | Your own folder on disk                                 |
+| `secrets:own`            | low      | Your own encrypted secrets                              |
+| `settings:read-core`     | low      | Read Termix server settings                             |
+| `plugins:read`           | low      | See installed plugins                                   |
+| `ui:surface`             | low      | Add tabs, panels and settings                           |
+| `ui:theme`               | low      | Add color themes, CSS only                              |
 
 An update that adds a capability waits for an admin to approve it.
 

packages/plugin-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@termix-ssh/plugin-sdk",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "description": "The contract between Termix core and a plugin: types, the capability catalog and the manifest schema.",
   "license": "Apache-2.0",
   "repository": {
@@ -85,6 +85,10 @@
       "types": "./dist/ssh-certs.d.ts",
       "default": "./dist/ssh-certs.js"
     },
+    "./ssh-keys": {
+      "types": "./dist/ssh-keys.d.ts",
+      "default": "./dist/ssh-keys.js"
+    },
     "./tsconfig.plugin.json": "./tsconfig.plugin.json",
     "./schema/manifest.schema.json": "./schema/manifest.schema.json",
     "./ui": {

packages/plugin-sdk/schema/manifest.schema.json

@@ -154,6 +154,7 @@
           "system:tls",
           "device:serial",
           "hosts:write",
+          "hosts:export",
           "credentials:use",
           "credentials:write",
           "network:outbound",
@@ -163,7 +164,11 @@
           "events:core",
           "notify:send",
           "audit:read",
+          "network:probe",
+          "hosts:status-provide",
+          "hosts:activity-provide",
           "desktop:window",
+          "desktop:local",
           "users:impersonate",
           "db:core-refs",
           "hosts:read",
@@ -1261,6 +1266,11 @@
       "enum": ["mirror", "local", "server"],
       "description": "How a desktop linked to a server treats this plugin: mirror follows the server, local is decided on each desktop, server never runs on a linked desktop. Defaults to mirror."
     },
+    "runtime": {
+      "type": "string",
+      "enum": ["desktop"],
+      "description": "desktop: the plugin only loads on a desktop app's own embedded backend, never on a server. It implies desktop local and may declare desktop:local."
+    },
     "nativeDependencies": {
       "type": "array",
       "minItems": 1,

packages/plugin-sdk/src/backend.ts

@@ -848,6 +848,168 @@ export interface PluginHosts {
    * Needs hosts:read.
    */
   status: PluginHostStatusApi;
+  /**
+   * The hosts the acting user may connect to (their own and shared ones) as a
+   * status provider needs them: address, port and jump hosts, no secrets.
+   * Pass hostIds to narrow it. Needs hosts:read.
+   */
+  probeTargets: (filter?: {
+    hostIds?: number[];
+  }) => Promise<PluginHostProbeTarget[]>;
+  /** Whether a session is open to the host right now. Needs hosts:read. */
+  sessionActive: (hostId: number) => boolean;
+  /**
+   * Imports Termix JSON host rows for the acting user, the same way POST
+   * /host/bulk-import does: up to 100 rows, jump hosts remapped by exportId,
+   * defaults, protocol logins and plugin settings applied, one save at the end.
+   * Needs hosts:write, plus credentials:write when credentials are passed, and
+   * the acting user needs the core hosts.create and hosts.edit permissions.
+   */
+  importMany: (
+    hosts: Record<string, unknown>[],
+    options?: PluginHostImportOptions,
+  ) => Promise<PluginHostImportResult>;
+  /** Imports the Host entries of an OpenSSH config file. Same rules as importMany. */
+  importSshConfig: (
+    content: string,
+    options?: Pick<PluginHostImportOptions, "overwrite" | "atomic">,
+  ) => Promise<PluginHostImportResult>;
+  /**
+   * The acting user's own hosts as Termix JSON. Without share the secrets are
+   * included, decrypted. With share every secret is left out and credential
+   * logins point at a scrubbed credentials list by alias. Needs hosts:export
+   * and is always audited.
+   */
+  exportMany: (options?: {
+    share?: boolean;
+    /** Only these of the user's hosts. */
+    hostIds?: number[];
+  }) => Promise<PluginHostExport>;
+  /**
+   * Validates and writes this plugin's own host settings from an imported
+   * row. Called for every imported row once the host exists. Return the
+   * values to write, or null to write nothing. Removed when the plugin
+   * deactivates. Needs hosts:write.
+   */
+  registerImportNormalizer: (
+    normalizer: PluginHostImportNormalizer,
+  ) => () => void;
+  /** The recent activity list on the dashboard. */
+  activity: PluginHostActivityApi;
+}
+
+export interface PluginHostImportOptions {
+  /** Update a host that matches on ip, port and username instead of skipping it. */
+  overwrite?: boolean;
+  /**
+   * All or nothing: if any row fails, the hosts this call created are deleted
+   * and the result says rolledBack. Cannot be combined with overwrite.
+   */
+  atomic?: boolean;
+  /** Credential placeholders rows can refer to by credentialAlias. */
+  credentials?: Array<Record<string, unknown>>;
+}
+
+export interface PluginHostImportResult {
+  success: number;
+  updated: number;
+  skipped: number;
+  failed: number;
+  errors: string[];
+  createdHostIds: number[];
+  rolledBack?: boolean;
+}
+
+export interface PluginHostExport {
+  hosts: Array<Record<string, unknown>>;
+  /** Share exports only. */
+  version?: string;
+  exportedAt?: string;
+  credentials?: Array<Record<string, unknown>>;
+}
+
+export type PluginHostImportNormalizer = (
+  raw: Record<string, unknown>,
+) => Record<string, unknown> | null;
+
+export interface PluginHostProbeTarget {
+  id: number;
+  /** The user who owns the host; its jump hosts are theirs. */
+  ownerUserId: string;
+  ip: string;
+  port: number;
+  connectionType: string;
+  jumpHosts: Array<{ hostId: number }>;
+  statusCheckEnabled: boolean;
+  /** Seconds, or null to use the global interval. */
+  statusCheckInterval: number | null;
+}
+
+/**
+ * The plugin that owns host status. Core keeps the routes, the sync feed and
+ * ctx.hosts.status; this fills them. One provider at a time.
+ */
+export interface PluginHostStatusProvider {
+  start: () => void;
+  stop: () => void;
+  get: (hostId: number) => PluginHostStatusEntry | null;
+  /**
+   * Every status known, after polling is brought in line with the request:
+   * with hostIds, exactly those of the user's hosts; without, all of them.
+   */
+  statusesFor: (
+    userId: string,
+    hostIds: number[] | null,
+  ) => Promise<Map<number, PluginHostStatusEntry>>;
+  /** Restarts the user's checks. */
+  refresh: (userId: string) => Promise<void>;
+  check: (hostId: number) => Promise<PluginHostStatusEntry | null>;
+  reportLogin: (hostId: number, outcome: { ok: boolean }) => void;
+  registerPort: (
+    connectionType: string,
+    resolve: (
+      hostId: number,
+    ) => number | undefined | Promise<number | undefined>,
+  ) => () => void;
+  /** The global check interval in seconds. */
+  getIntervalSeconds: () => Promise<number>;
+  setIntervalSeconds: (seconds: number) => Promise<void>;
+}
+
+export interface PluginActivityEntry {
+  id: number;
+  userId: string;
+  type: string;
+  hostId: number;
+  hostName: string | null;
+  timestamp: string;
+}
+
+export type PluginRecordActivityResult =
+  | { status: "logged"; id: number }
+  | { status: "rate_limited" }
+  | { status: "invalid_type" }
+  | { status: "denied" }
+  | { status: "unavailable" };
+
+/** The plugin that stores recent activity. One provider at a time. */
+export interface PluginActivityProvider {
+  record: (
+    userId: string,
+    entry: { type: string; hostId: number; hostName: string },
+  ) => Promise<PluginRecordActivityResult>;
+  list: (userId: string, limit: number) => Promise<PluginActivityEntry[]>;
+  deleteByUserId: (userId: string) => Promise<void>;
+  deleteByHostIds: (hostIds: number[]) => Promise<void>;
+}
+
+export interface PluginHostActivityApi {
+  /**
+   * Becomes the store behind the dashboard's recent activity and
+   * ctx.hosts.recordActivity. Needs hosts:activity-provide. Removed on
+   * deactivate.
+   */
+  provide: (provider: PluginActivityProvider) => () => void;
 }
 
 /**
@@ -896,6 +1058,11 @@ export interface PluginHostStatusApi {
       hostId: number,
     ) => number | undefined | Promise<number | undefined>,
   ) => () => void;
+  /**
+   * Becomes core's host status. Needs hosts:status-provide. Removed on
+   * deactivate, which hands status back to core's built-in checks.
+   */
+  provide: (provider: PluginHostStatusProvider) => () => void;
 }
 
 /**
@@ -1060,6 +1227,25 @@ export interface PluginSshConnectOptions {
   sock?: unknown;
 }
 
+export interface PluginSshExecOptions extends PluginSshConnectOptions {
+  /** Time to wait for the command to finish. Default 30s, at most 10 minutes. */
+  timeoutMs?: number;
+  /** Most bytes kept of each of stdout and stderr. Default 256 KB, at most 4 MB. */
+  maxOutputBytes?: number;
+  /** Written to the command's standard input, then closed. */
+  stdin?: string;
+}
+
+export interface PluginSshExecResult {
+  stdout: string;
+  stderr: string;
+  /** The exit code. Null when the command was killed or ran out of time. */
+  code: number | null;
+  /** Output went past maxOutputBytes and the rest was dropped. */
+  truncated: boolean;
+  timedOut: boolean;
+}
+
 export interface PluginSshConnection<Client = unknown> {
   /** An ssh2 Client, already "ready". */
   client: Client;
@@ -1079,12 +1265,47 @@ export interface PluginSshConnection<Client = unknown> {
  * audit line per new connection. Connections still open on deactivate are
  * closed.
  */
+export interface PluginNetwork {
+  /**
+   * Whether a TCP port answers. An SSH banner is read and answered politely;
+   * nothing is ever sent that logs in. Loopback, private and link-local
+   * addresses are allowed, since status checks target the user's own hosts.
+   */
+  tcpProbe: (
+    host: string,
+    port: number,
+    options?: { timeoutMs?: number },
+  ) => Promise<boolean>;
+}
+
 export interface PluginSsh {
+  /**
+   * Whether a TCP port answers through the host's jump host chain. Chains are
+   * shared and closed when idle. The acting user must be able to connect to
+   * the host. Needs ssh:connect.
+   */
+  probe: (
+    hostId: number,
+    options?: { port?: number; timeoutMs?: number },
+  ) => Promise<boolean>;
+
   connect: <Client = unknown>(
     host: number | PluginSshHost,
     options?: PluginSshConnectOptions,
   ) => Promise<PluginSshConnection<Client>>;
 
+  /**
+   * Runs one command on a host with its stored login and closes the
+   * connection. The acting user needs connect access to the host, the same as
+   * connect. Output is capped and the command is stopped at the time limit.
+   * Needs ssh:connect and credentials:use.
+   */
+  exec: (
+    host: number | PluginSshHost,
+    command: string,
+    options?: PluginSshExecOptions,
+  ) => Promise<PluginSshExecResult>;
+
   /** Borrows a pooled connection. The pool key is `<pool>:<owner>:<address>`. */
   withConnection: <T, Client = unknown>(
     host: number | PluginSshHost,
@@ -1603,6 +1824,148 @@ export interface PluginDesktop {
   ) => Promise<{ success: boolean; error?: string }>;
   /** Whether the server runs embedded in the desktop app, so the calls above can work. */
   available: () => boolean;
+  /**
+   * The user's own machine. Only works on the desktop app's embedded backend
+   * and needs desktop:local; every call is audited once per plugin start.
+   */
+  readonly local: PluginDesktopLocal;
+}
+
+export interface PluginLocalDirEntry {
+  name: string;
+  path: string;
+  type: "file" | "directory" | "link";
+  size: number;
+  modifiedTimestamp?: number;
+  linkTarget?: string;
+  hidden: boolean;
+}
+
+export interface PluginLocalWalkResult {
+  files: Array<{ localPath: string; relativePath: string; size: number }>;
+  emptyDirs: string[];
+  totalBytes: number;
+}
+
+export interface PluginLocalPty {
+  readonly pid: number;
+  /** The shell program that was started. */
+  readonly shell: string;
+  write: (data: string) => void;
+  resize: (cols: number, rows: number) => void;
+  kill: () => void;
+  onData: (handler: (data: string) => void) => () => void;
+  onExit: (handler: (exitCode: number) => void) => () => void;
+}
+
+/** A download being written next to its final name, published when done. */
+export interface PluginLocalDownload {
+  /** Final path inside the chosen folder, links inside it already refused. */
+  readonly path: string;
+  readonly stream: NodeJS.WritableStream;
+  /** Moves the finished partial onto its final name. */
+  publish: (options?: { overwrite?: boolean }) => Promise<string>;
+  /** Removes the partial file. Safe to call after publish. */
+  abort: () => Promise<void>;
+}
+
+export interface PluginLocalResponse {
+  readonly status: number;
+  readonly ok: boolean;
+  readonly headers: { get: (name: string) => string | null };
+  /** A web stream of the body, or null when there is none. */
+  readonly body: AsyncIterable<Uint8Array> | null;
+  text: () => Promise<string>;
+}
+
+export interface PluginDesktopLocal {
+  /** Whether local access is possible: embedded backend and capability granted. */
+  available: () => boolean;
+  /**
+   * Calls this plugin's own HTTP routes on the embedded backend ("local") or
+   * on the server the desktop is linked to ("remote"), as the acting user.
+   * The path is under /plugin-api/<this plugin id>; nothing else is
+   * reachable. The link's proxy headers and certificate rules apply. A body
+   * may be a string, a buffer or a Node stream.
+   */
+  pluginFetch: (
+    origin: "local" | "remote",
+    subPath: string,
+    init?: {
+      method?: string;
+      headers?: Record<string, string>;
+      body?: string | Buffer | NodeJS.ReadableStream;
+      signal?: AbortSignal;
+    },
+  ) => Promise<PluginLocalResponse>;
+  info: () => Promise<{
+    home: string;
+    separator: string;
+    platform: NodeJS.Platform;
+    /** The desktop app's user data folder. */
+    userDataDir: string;
+    /** The port the embedded backend listens on. */
+    backendPort: number;
+    /** The server this desktop is linked to, or null. */
+    link: {
+      serverUrl: string;
+      token: string | null;
+      /**
+       * Headers for a request to the linked server: the session, plus the
+       * proxy headers and basic auth the link was set up with.
+       */
+      headers: Record<string, string>;
+      /** The link accepts a self-signed certificate. */
+      allowInvalidCertificate: boolean;
+    } | null;
+  }>;
+  /**
+   * GET a JSON route on the linked server with the link's session, proxy
+   * headers and certificate rules. Rejects with an error whose `kind` is
+   * "signed_out" when the server refused the session.
+   */
+  linkJson: (pathname: string) => Promise<unknown>;
+  readonly fs: {
+    list: (dirPath: string) => Promise<{
+      path: string;
+      parent: string | null;
+      entries: PluginLocalDirEntry[];
+    }>;
+    mkdir: (parentPath: string, name: string) => Promise<string>;
+    createFile: (parentPath: string, name: string) => Promise<string>;
+    /** Renames inside the same folder; never replaces an existing name. */
+    rename: (path: string, newName: string) => Promise<string>;
+    /** Creates a folder; with rootPath it must stay inside that folder. */
+    ensureDir: (dirPath: string, rootPath?: string) => Promise<string>;
+    /** Which of the given paths exist. */
+    exists: (paths: string[]) => Promise<string[]>;
+    walk: (rootPaths: string[]) => Promise<PluginLocalWalkResult>;
+    /** Sends entries to the operating system's trash. */
+    trash: (paths: string[]) => Promise<{
+      trashed: number;
+      failed: Array<{ path: string; error: string }>;
+    }>;
+    reveal: (path: string) => Promise<void>;
+    open: (path: string) => Promise<void>;
+    openRead: (path: string) => Promise<{
+      stream: NodeJS.ReadableStream;
+      size: number;
+    }>;
+    openDownload: (options: {
+      rootPath: string;
+      destPath: string;
+      transferId: string;
+      overwrite?: boolean;
+    }) => Promise<PluginLocalDownload>;
+  };
+  readonly pty: {
+    spawn: (options?: {
+      cols?: number;
+      rows?: number;
+      /** "wsl" on Windows starts WSL instead of PowerShell. */
+      shell?: string;
+    }) => Promise<PluginLocalPty>;
+  };
 }
 
 /**
@@ -1699,6 +2062,23 @@ export interface PluginCredentials {
     scheme: string,
     resolve: (userId: string, reference: string) => Promise<string>,
   ) => void;
+  /**
+   * The public key line of an SSH key credential the acting user can see
+   * (their own, with the core credentials.view permission). Derived from the
+   * private key when none is stored, including a key kept behind a secret
+   * reference. Null when the credential is missing, is not a key, or cannot
+   * be read. Needs credentials:use. Audited.
+   */
+  publicKey: (credentialId: number) => Promise<string | null>;
+  /**
+   * Replaces secret references ("op://...") in a key and its passphrase with
+   * the real values, for the acting user. Plain values pass through. Hands
+   * private key material to the plugin. Needs credentials:read. Audited.
+   */
+  resolveKeyRefs: (
+    key: string,
+    passphrase?: string | null,
+  ) => Promise<{ key: string; passphrase?: string }>;
 }
 
 /**
@@ -1721,6 +2101,57 @@ export interface PluginAudit {
      */
     request?: unknown;
   }) => Promise<void>;
+  /**
+   * Called for every audit line core or any plugin writes, after it is
+   * accepted. Fire and forget: a slow or throwing handler never delays or
+   * fails the audited action. Lines written before the plugin started are not
+   * replayed; read them with list or export. Returns an unsubscribe function;
+   * it is also removed when the plugin deactivates. Needs audit:read.
+   */
+  subscribe: (handler: (entry: PluginAuditEntry) => void) => () => void;
+  /** A page of stored lines, newest first. Needs audit:read. */
+  list: (options?: {
+    filters?: PluginAuditFilters;
+    limit?: number;
+    offset?: number;
+  }) => Promise<{ entries: PluginAuditEntry[]; total: number }>;
+  /**
+   * Stored lines in time order, in batches, so an export never holds the
+   * whole trail in memory. Needs audit:read.
+   */
+  exportBatches: (
+    filters?: PluginAuditFilters,
+    batchSize?: number,
+  ) => AsyncGenerator<PluginAuditEntry[]>;
+}
+
+export interface PluginAuditFilters {
+  userId?: string;
+  action?: string;
+  resourceType?: string;
+  success?: boolean;
+  /** ISO date-time. */
+  startDate?: string;
+  /** ISO date-time. */
+  endDate?: string;
+}
+
+export interface PluginAuditEntry {
+  /** Only on stored lines (list and export). */
+  id?: number;
+  /** ISO date-time. */
+  timestamp: string;
+  userId: string | null;
+  username: string;
+  action: string;
+  resourceType: string;
+  resourceId: string | null;
+  resourceName: string | null;
+  details: string | null;
+  ipAddress: string | null;
+  userAgent: string | null;
+  success: boolean;
+  errorMessage: string | null;
 }
 
 /** A notification channel a user set up. Its config never leaves the hub. */
@@ -2066,6 +2497,8 @@ export interface PluginContext {
   readonly notify: PluginNotify;
   /** Outbound HTTP through core's SSRF guard. Needs network:outbound. */
   readonly fetch: PluginFetch;
+  /** Plain reachability checks. Needs network:probe. */
+  readonly network: PluginNetwork;
   /** Programs on the Termix server. Needs process:spawn. */
   readonly process: PluginProcess;
   /** The server certificate. Needs system:tls. */

packages/plugin-sdk/src/capabilities.ts

@@ -52,16 +52,21 @@ export const CAPABILITY_CATALOG: readonly CapabilityInfo[] = [
   entry("ui:layout", "high"),
 
   entry("hosts:write", "medium"),
+  entry("hosts:export", "high"),
   entry("credentials:use", "medium"),
   entry("credentials:write", "medium"),
   entry("network:outbound", "medium"),
   entry("network:serve", "medium"),
   entry("network:broadcast", "medium"),
+  entry("network:probe", "medium"),
+  entry("hosts:status-provide", "medium"),
+  entry("hosts:activity-provide", "medium"),
   entry("users:read", "medium"),
   entry("events:core", "medium"),
   entry("notify:send", "medium"),
   entry("audit:read", "medium"),
   entry("desktop:window", "medium"),
+  entry("desktop:local", "high"),
 
   entry("hosts:read", "low"),
   entry("db:own", "low"),

packages/plugin-sdk/src/db.ts

@@ -256,6 +256,7 @@ export const LEGACY_TABLE_OWNERS: Readonly<Record<string, string>> = {
   homepage_items: "homepage",
   homepage_layouts: "homepage",
   dashboard_service_links: "homepage",
+  recent_activity: "homepage",
   secret_sources: "secret-sources",
   opkssh_tokens: "opkssh",
   vault_profiles: "vault",

packages/plugin-sdk/src/desktop.ts

@@ -3,8 +3,6 @@
  * only inside the Termix desktop app; check isElectron before calling it.
  */
 
-import type { PluginSshPromptRequest } from "./backend.js";
-
 export interface ServerConfig {
   serverUrl?: string;
   allowInvalidCertificate?: boolean;
@@ -33,27 +31,6 @@ export interface DialogResult {
   [key: string]: unknown;
 }
 
-export interface LocalDirectoryResult {
-  success: boolean;
-  path: string;
-  parent?: string;
-  entries: LocalFileEntry[];
-  error?: string;
-}
-
-export interface LocalCollectedFile {
-  path: string;
-  name: string;
-  relativePath: string;
-  size: number;
-  created?: string;
-  modified: string;
-}
-
-export type LocalPathMutationResult =
-  | ({ success: true } & Partial<LocalFileEntry>)
-  | { success: false; error?: string };
-
 export interface ElectronAPI {
   getAppVersion: () => Promise<string>;
   setZoomFactor?: (factor: number) => void;
@@ -67,60 +44,6 @@ export interface ElectronAPI {
     serverUrl: string,
     allowInvalidCertificate?: boolean,
   ) => Promise<ConnectionTestResult>;
-  answerC2SAuth: (id: string, answer: string | null) => Promise<boolean>;
-  onC2SAuthPrompt: (
-    callback: (prompt: {
-      id: string;
-      closed?: boolean;
-      tunnelName?: string;
-      request?: PluginSshPromptRequest;
-    }) => void,
-  ) => () => void;
-  getC2STunnelConfig: () => Promise<unknown[]>;
-  saveC2STunnelConfig: (
-    config: unknown[],
-  ) => Promise<{ success: boolean; error?: string }>;
-  checkLocalPortAvailable: (
-    host: string,
-    port: number,
-  ) => Promise<{ available: boolean; error?: string }>;
-  getC2STunnelPresetDefaultName: () => Promise<string>;
-  startC2STunnel: (
-    tunnel: unknown,
-    index: number,
-    authToken?: string,
-  ) => Promise<{
-    success: boolean;
-    tunnelName?: string;
-    error?: string;
-    code?: string;
-  }>;
-  testC2STunnel: (
-    tunnel: unknown,
-    index: number,
-    authToken?: string,
-  ) => Promise<{
-    success: boolean;
-    message?: string;
-    error?: string;
-    code?: string;
-  }>;
-  stopC2STunnel: (
-    tunnelName: string,
-  ) => Promise<{ success: boolean; error?: string }>;
-  getC2STunnelStatuses: () => Promise<Record<string, unknown>>;
-  onC2STunnelStatuses?: (
-    callback: (statuses: Record<string, unknown>) => void,
-  ) => () => void;
-  startC2SAutoStartTunnels: () => Promise<{
-    success: boolean;
-    started: number;
-    errors: string[];
-  }>;
-  /** Where the linked server relays client tunnel streams, a /plugin-ws/ path. */
-  setC2SRelayPath?: (
-    relayPath: string,
-  ) => Promise<{ success: boolean; error?: string }>;
   onCloseActiveTab?: (callback: () => void) => () => void;
   clearSessionCookies: () => Promise<void>;
   getSessionCookie: (
@@ -136,62 +59,6 @@ export interface ElectronAPI {
 
   showSaveDialog: (options: DialogOptions) => Promise<DialogResult>;
   showOpenDialog: (options: DialogOptions) => Promise<DialogResult>;
-  getLocalHomeDirectory?: () => Promise<string>;
-  listLocalDirectory?: (path?: string) => Promise<LocalDirectoryResult>;
-  statLocalPaths?: (
-    paths: string[],
-  ) => Promise<
-    Array<
-      | (LocalFileEntry & { success: true })
-      | { success: false; path: string; error?: string }
-    >
-  >;
-  collectLocalFiles?: (paths: string[]) => Promise<{
-    success: boolean;
-    files: LocalCollectedFile[];
-    truncated?: boolean;
-    error?: string;
-  }>;
-  createLocalFolder?: (
-    parentPath: string,
-    folderName: string,
-  ) => Promise<LocalPathMutationResult>;
-  renameLocalPath?: (
-    path: string,
-    newName: string,
-  ) => Promise<LocalPathMutationResult>;
-  trashLocalPath?: (path: string) => Promise<LocalPathMutationResult>;
-  chmodLocalPath?: (
-    path: string,
-    permissions: string,
-  ) => Promise<LocalPathMutationResult>;
-
-  openExternalEditor: (fileData: {
-    fileName: string;
-    content: string;
-    encoding?: "utf8" | "base64";
-    editorPath?: string | null;
-  }) => Promise<{
-    success: boolean;
-    editId?: string;
-    path?: string;
-    error?: string;
-  }>;
-
-  closeExternalEditor: (editId: string) => Promise<{
-    success: boolean;
-    error?: string;
-  }>;
-
-  onExternalEditorSaved?: (
-    callback: (payload: {
-      editId: string;
-      content: string;
-      encoding: "utf8";
-      path: string;
-    }) => void,
-  ) => () => void;
-
   onUpdateAvailable: (callback: () => void) => void;
   onUpdateDownloaded: (callback: () => void) => void;
 
@@ -238,159 +105,6 @@ export interface ElectronAPI {
     success: boolean;
     error?: string;
   }>;
-
-  startLocalTerminal(dimensions: {
-    cols: number;
-    rows: number;
-    shell?: "default" | "wsl";
-  }): Promise<{ sessionId: string; shell: string }>;
-  readyLocalTerminal(sessionId: string): Promise<boolean>;
-  writeLocalTerminal(sessionId: string, data: string): Promise<boolean>;
-  resizeLocalTerminal(
-    sessionId: string,
-    cols: number,
-    rows: number,
-  ): Promise<boolean>;
-  closeLocalTerminal(sessionId: string): Promise<boolean>;
-  onLocalTerminalData(
-    sessionId: string,
-    callback: (data: string) => void,
-  ): () => void;
-  onLocalTerminalExit(
-    sessionId: string,
-    callback: (exitCode: number) => void,
-  ): () => void;
-
-  /** Local disk browsing for the dual-pane file manager (desktop only). */
-  localFs?: {
-    home: () => Promise<LocalFsResult<LocalFsHomeInfo>>;
-    list: (dirPath: string) => Promise<LocalFsResult<LocalDirectoryListing>>;
-    mkdir: (
-      parentPath: string,
-      name: string,
-    ) => Promise<LocalFsResult<{ path: string }>>;
-    createFile: (
-      parentPath: string,
-      name: string,
-    ) => Promise<LocalFsResult<{ path: string }>>;
-    rename: (
-      oldPath: string,
-      newName: string,
-    ) => Promise<LocalFsResult<{ path: string }>>;
-    trash: (paths: string[]) => Promise<LocalFsResult<LocalTrashResult>>;
-    ensureDir: (
-      dirPath: string,
-      rootPath?: string,
-    ) => Promise<LocalFsResult<{ path: string }>>;
-    exists: (paths: string[]) => Promise<LocalFsResult<{ existing: string[] }>>;
-    walk: (paths: string[]) => Promise<LocalFsResult<LocalWalkResult>>;
-    reveal: (targetPath: string) => Promise<LocalFsResult<unknown>>;
-    open: (targetPath: string) => Promise<LocalFsResult<unknown>>;
-  };
-
-  /** Streamed local<->remote transfers driven by the main process. */
-  localTransfer?: {
-    /** The /plugin-api/<id> path that serves the streaming routes. */
-    setApiPath?: (apiPath: string) => Promise<LocalFsResult<object>>;
-    upload: (
-      options: LocalUploadRequest,
-    ) => Promise<LocalFsResult<{ bytes: number }>>;
-    download: (
-      options: LocalDownloadRequest,
-    ) => Promise<LocalFsResult<{ path: string }>>;
-    cancel: (
-      transferId: string,
-    ) => Promise<LocalFsResult<{ cancelled: boolean }>>;
-    onProgress: (
-      callback: (payload: LocalTransferProgress) => void,
-    ) => () => void;
-  };
-}
-
-export type LocalFsResult<T> =
-  ({ success: true } & T) | { success: false; error: string; code?: string };
-
-export interface LocalFsHomeInfo {
-  home: string;
-  separator: string;
-  platform: string;
-}
-
-export interface LocalFileEntry {
-  name: string;
-  path: string;
-  type: "file" | "directory" | "link" | "other";
-  created?: string;
-  modified?: string;
-  permissions?: string;
-  owner?: string;
-  group?: string;
-  size: number;
-  modifiedTimestamp?: number;
-  linkTarget?: string;
-  hidden: boolean;
-}
-
-export interface LocalDirectoryListing {
-  path: string;
-  parent: string | null;
-  entries: LocalFileEntry[];
-}
-
-export interface LocalTrashResult {
-  trashed: number;
-  failed: Array<{ path: string; error: string }>;
-}
-
-export interface LocalWalkFile {
-  localPath: string;
-  /** Path relative to the drop root; "/"-separated and includes the root's own name. */
-  relativePath: string;
-  size: number;
-}
-
-export interface LocalWalkResult {
-  files: LocalWalkFile[];
-  emptyDirs: string[];
-  totalBytes: number;
-}
-
-/**
- * Which Termix backend a transfer talks to. The main process resolves the
- * actual URL and credentials for the origin; the renderer never supplies them.
- */
-export type LocalTransferOrigin = "local" | "remote";
-
-export interface LocalUploadRequest {
-  transferId: string;
-  origin: LocalTransferOrigin;
-  fields: Record<string, string>;
-  localPath: string;
-  fileName: string;
-  deviceId?: string;
-  /** The renderer's token for the embedded backend (origin "local"); sent as a Bearer header. */
-  authToken?: string;
-}
-
-export interface LocalDownloadRequest {
-  transferId: string;
-  origin: LocalTransferOrigin;
-  body: Record<string, unknown>;
-  destPath: string;
-  /** Selected download folder; destPath must resolve strictly inside it (code EINVAL otherwise). */
-  rootPath: string;
-  expectedSize?: number;
-  /** Replace an existing file at destPath; otherwise the transfer is refused with code EEXIST. */
-  overwrite?: boolean;
-  deviceId?: string;
-  /** The renderer's token for the embedded backend (origin "local"); sent as a Bearer header. */
-  authToken?: string;
-}
-
-export interface LocalTransferProgress {
-  transferId: string;
-  transferred: number;
-  total?: number;
 }
 
 declare global {

packages/plugin-sdk/src/frontend.ts

@@ -653,8 +653,16 @@ export interface HostBadgeContribution {
   id: string;
   when: (host: PluginHostRecord) => boolean;
   component: ComponentType<{ host: PluginHostRecord }>;
+  /** Lower comes first. Ties sort by id. */
+  order?: number;
 }
 
+/** The dot or stripe that shows a host's status on its row. */
+export type HostStatusIndicatorContribution = HostBadgeContribution;
+
+/** A control in the host editor's toolbar. */
+export type HostEditorToolbarItemContribution = HostBadgeContribution;
+
 export interface HostContextMenuItemContribution {
   id: string;
   titleKey: string;
@@ -838,10 +846,11 @@ export type OnboardingMode = "full" | "partial" | "rerun";
  * Where a plugin step sits in onboarding. "setup" comes right after the
  * appearance steps, for things that need doing before the feature works
  * (like pointing at a guacd server). "explore" (the default) comes after
- * that, "security" after the account security step. Onboarding is for
+ * that, "security" after the account security step. "start" comes before
+ * the appearance steps, for choices that shape how the rest looks. Onboarding is for
  * choices, not for explaining features.
  */
-export type OnboardingSection = "setup" | "explore" | "security";
+export type OnboardingSection = "start" | "setup" | "explore" | "security";
 
 export interface OnboardingStepProps {
   /**
@@ -884,6 +893,16 @@ export interface OnboardingStepContribution {
   permission?: string;
   section?: OnboardingSection;
   order?: number;
+  /**
+   * Exact place in the flow, 1 to 99, instead of a section. Core steps sit at
+   * 10 (plugins), 20, 25, 30 (preset), 40 (appearance) and 90 (security).
+   */
+  position?: number;
+  /**
+   * Older step keys this step took over, like "preset". People who already
+   * saw one of them are not shown this step again.
+   */
+  replaces?: string[];
   when?: (context: {
     isAdmin: boolean;
     isDesktop: boolean;
@@ -1055,6 +1074,14 @@ export interface TermixApp extends TermixAppInfo {
   registerHostAction: (action: HostActionContribution) => Disposer;
   registerHostProtocol: (protocol: HostProtocolContribution) => Disposer;
   registerHostBadge: (badge: HostBadgeContribution) => Disposer;
+  /** Draws a host row's status. A layout renders every registered one. */
+  registerHostStatusIndicator: (
+    indicator: HostStatusIndicatorContribution,
+  ) => Disposer;
+  /** Adds a control to the host editor's toolbar. */
+  registerHostEditorToolbarItem: (
+    item: HostEditorToolbarItemContribution,
+  ) => Disposer;
   registerHostContextMenuItem: (
     item: HostContextMenuItemContribution,
   ) => Disposer;

packages/plugin-sdk/src/manifest.ts

@@ -37,7 +37,7 @@ export {
  * "^1.2" needs 1.2 or later). engine.termix is checked against the core
  * version by the server.
  */
-export const PLUGIN_API_VERSION = "1.4.0";
+export const PLUGIN_API_VERSION = "1.5.0";
 
 /** The API major, the default engine.api for a new plugin. */
 export const SUPPORTED_PLUGIN_API_VERSION = String(
@@ -688,6 +688,21 @@ export interface PluginManifest {
   nativeDependencies?: string[];
   /** How a linked desktop treats this plugin. Defaults to "mirror". */
   desktop?: PluginDesktopMode;
+  /**
+   * "desktop": the plugin only loads on a desktop app's own embedded backend,
+   * never on a server. It implies desktop "local" and may declare desktop:local.
+   */
+  runtime?: PluginRuntime;
+}
+
+export type PluginRuntime = "desktop";
+export const PLUGIN_RUNTIMES: readonly PluginRuntime[] = ["desktop"];
+
+/** The desktop mode a manifest resolves to. */
+export function resolvePluginDesktopMode(
+  m: Pick<PluginManifest, "desktop" | "runtime">,
+): PluginDesktopMode {
+  return m.desktop ?? (m.runtime === "desktop" ? "local" : "mirror");
 }
 
 export const DEFAULT_BACKEND_ENTRY = "dist/backend.js";
@@ -727,6 +742,7 @@ const ALLOWED_TOP_LEVEL = new Set([
   "platforms",
   "nativeDependencies",
   "desktop",
+  "runtime",
 ]);
 
 const ALLOWED_CONTRIBUTES = new Set([
@@ -904,6 +920,21 @@ export function validateManifest(manifest: unknown): string[] {
       `Field "desktop" must be one of: ${PLUGIN_DESKTOP_MODES.join(", ")}`,
     );
   }
+  if (
+    m.runtime !== undefined &&
+    !PLUGIN_RUNTIMES.includes(m.runtime as PluginRuntime)
+  ) {
+    errors.push(
+      `Field "runtime" must be one of: ${PLUGIN_RUNTIMES.join(", ")}`,
+    );
+  }
+  if (
+    m.runtime === "desktop" &&
+    m.desktop !== undefined &&
+    m.desktop !== "local"
+  ) {
+    errors.push(`A "desktop" runtime plugin must use desktop "local"`);
+  }
   validateDependencyMap(m.dependencies, "dependencies", errors);
   validateDependencyMap(m.optionalDependencies, "optionalDependencies", errors);
   validateProvides(m.provides, errors);

packages/plugin-sdk/src/ssh-keys.ts

@@ -0,0 +1,122 @@
+/**
+ * SSH key helpers for plugins that make, check or deploy keys: generate a key
+ * pair, tell what a key is, derive a public key and check a pair belongs
+ * together. Pure functions over ssh2, which the host supplies. Core keeps its
+ * own copy for the connect pipeline.
+ */
+
+import ssh2 from "ssh2";
+
+export type SshKeyKind = "ssh-ed25519" | "ssh-rsa" | "ecdsa-sha2-nistp256";
+
+export interface GeneratedSshKeyPair {
+  privateKey: string;
+  publicKey: string;
+  keyType: SshKeyKind;
+}
+
+export interface GenerateSshKeyPairOptions {
+  /** RSA only. 2048 to 8192, default 4096. */
+  bits?: number;
+  passphrase?: string;
+  comment?: string;
+}
+
+/** Makes a new key pair; the public half is one authorized_keys line. */
+export function generateSshKeyPair(
+  type: SshKeyKind,
+  options: GenerateSshKeyPairOptions = {},
+): GeneratedSshKeyPair {
+  const algorithm =
+    type === "ssh-rsa" ? "rsa" : type === "ssh-ed25519" ? "ed25519" : "ecdsa";
+  if (
+    type !== "ssh-rsa" &&
+    type !== "ssh-ed25519" &&
+    type !== "ecdsa-sha2-nistp256"
+  ) {
+    throw new Error(`Unsupported key type: ${String(type)}`);
+  }
+  const generateOptions: Record<string, unknown> = {
+    comment: options.comment ?? "",
+  };
+  if (options.passphrase) {
+    generateOptions.passphrase = options.passphrase;
+    generateOptions.cipher = "aes256-ctr";
+  }
+  if (type === "ssh-rsa") {
+    const bits = options.bits ?? 4096;
+    if (!Number.isInteger(bits) || bits < 2048 || bits > 8192) {
+      throw new Error("RSA keys need 2048 to 8192 bits");
+    }
+    generateOptions.bits = bits;
+  }
+  if (type === "ecdsa-sha2-nistp256") generateOptions.bits = 256;
+
+  const pair = ssh2.utils.generateKeyPairSync(
+    algorithm as "rsa",
+    generateOptions as never,
+  );
+  return {
+    privateKey: pair.private,
+    publicKey: pair.public.trim(),
+    keyType: type,
+  };
+}
+
+function parse(key: string, passphrase?: string) {
+  const parsed = ssh2.utils.parseKey(key.trim(), passphrase || undefined);
+  const first = Array.isArray(parsed) ? parsed[0] : parsed;
+  if (!first || first instanceof Error) {
+    throw first instanceof Error ? first : new Error("Not a readable SSH key");
+  }
+  return first;
+}
+
+/** The key's algorithm, like "ssh-ed25519", or null when it cannot be read. */
+export function detectSshKeyType(
+  key: string,
+  passphrase?: string,
+): string | null {
+  try {
+    return parse(key, passphrase).type;
+  } catch {
+    return null;
+  }
+}
+
+/** The authorized_keys line for a private key, or null. */
+export function publicKeyFromPrivate(
+  privateKey: string,
+  passphrase?: string,
+): string | null {
+  try {
+    const parsed = parse(privateKey, passphrase);
+    return `${parsed.type} ${parsed.getPublicSSH().toString("base64")}`;
+  } catch {
+    return null;
+  }
+}
+
+/** Whether a public key line belongs to the private key. */
+export function validateSshKeyPair(
+  privateKey: string,
+  publicKey: string,
+  passphrase?: string,
+): { isValid: boolean; error?: string } {
+  try {
+    const priv = parse(privateKey, passphrase);
+    const pub = parse(publicKey);
+    const same = priv.getPublicSSH().equals(pub.getPublicSSH());
+    return same
+      ? { isValid: true }
+      : {
+          isValid: false,
+          error: "The public key does not match the private key",
+        };
+  } catch (error) {
+    return {
+      isValid: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}

packages/plugin-sdk/src/testing.ts

@@ -14,7 +14,10 @@ import {
   PluginCapabilityError,
 } from "./backend.js";
 import type {
+  PluginAuditEntry,
+  PluginAuditFilters,
   PluginContext,
+  PluginDesktopLocal,
   PluginDisposables,
   PluginLogger,
 } from "./backend.js";
@@ -70,7 +73,10 @@ import type { PluginDatabase } from "./backend.js";
 import type {
   PluginExternalClientRequest,
   PluginProtocolTarget,
+  PluginHostProbeTarget,
   PluginHostStatusEntry,
+  PluginActivityProvider,
+  PluginHostStatusProvider,
   PluginNotification,
   PluginNotificationChannel,
   PluginNotifyHub,
@@ -101,6 +107,8 @@ export interface FakeContextOptions {
   settings?: Record<string, unknown>;
   /** Seed for the core settings ctx.settings.readCore can reach. */
   coreSettings?: Record<string, string>;
+  /** What ctx.files.dataDir() answers. Defaults to /tmp/<pluginId>. */
+  dataDir?: string;
   /** What ctx.ssh.connect and withConnection hand back as the client. */
   sshClient?: unknown;
   /** A real database behind ctx.db, usually createTestDb().database. */
@@ -134,8 +142,18 @@ export interface FakeContextOptions {
   sshKeyCredentials?: PluginSshKeyCredential[];
   /** What ctx.desktop.available() answers. Defaults to false. */
   desktopAvailable?: boolean;
+  /** What ctx.desktop.local is. Calls throw when this is not given. */
+  desktopLocal?: PluginDesktopLocal;
+  /** The stored audit lines ctx.audit.list and exportBatches serve. */
+  auditEntries?: PluginAuditEntry[];
   /** What ctx.hosts.status.get and check answer, by host id. */
   hostStatuses?: Record<number, PluginHostStatusEntry>;
+  /** What ctx.hosts.probeTargets answers. */
+  probeTargets?: PluginHostProbeTarget[];
+  /** Host ids ctx.hosts.sessionActive answers true for. */
+  activeSessions?: number[];
+  /** What ctx.network.tcpProbe and ctx.ssh.probe answer. Defaults to false. */
+  reachable?: (target: string | number, port?: number) => boolean;
   /** The acting user's channels, what ctx.notify.channels answers. */
   notificationChannels?: PluginNotificationChannel[];
   /**
@@ -263,6 +281,10 @@ export interface FakePluginContext {
   ) => Promise<Record<string, string>>;
   /** Everything the plugin registered through ctx.disposables. */
   disposals: Array<() => void | Promise<void>>;
+  /** Providers registered through ctx.hosts.status.provide. */
+  hostStatusProviders: PluginHostStatusProvider[];
+  /** Every provider passed to ctx.hosts.activity.provide that is still registered. */
+  activityProviders: PluginActivityProvider[];
   /** Topics emitted through ctx.events.emit, in order. */
   emitted: Array<{ topic: string; payload: unknown }>;
   /** Backing store behind ctx.kv. */
@@ -338,6 +360,8 @@ export interface FakePluginContext {
     challenges: Map<string, string>;
     renewers: number;
   };
+  /** Calls every ctx.audit.subscribe handler, like a line core just accepted. */
+  emitAudit: (entry: PluginAuditEntry) => void;
   /** Every ctx.audit.record entry, in order. */
   audits: Array<{ action: string; success: boolean; [key: string]: unknown }>;
   /** Every ctx.hosts.recordActivity call, in order. */
@@ -491,6 +515,8 @@ export function createFakeContext(
   const pluginId = options.pluginId ?? "test-plugin";
   const disposals: Array<() => void | Promise<void>> = [];
   const emitted: Array<{ topic: string; payload: unknown }> = [];
+  const hostStatusProviders: PluginHostStatusProvider[] = [];
+  const activityProviders: PluginActivityProvider[] = [];
   const kv = new Map<string, unknown>();
   const tables: PluginTableDefinition[] = [];
   const syncEntities: SyncEntityRegistration[] = [];
@@ -531,6 +557,7 @@ export function createFakeContext(
   };
   const secretStore = new Map<string, string>();
   const audits: FakePluginContext["audits"] = [];
+  const auditSubscribers = new Set<(entry: PluginAuditEntry) => void>();
   const activities: FakePluginContext["activities"] = [];
   const trackedSessions: number[] = [];
   const interactions: FakePluginContext["interactions"] = [];
@@ -665,7 +692,7 @@ export function createFakeContext(
     files: {
       // A fake path; a test that needs a real folder uses the OS temp dir
       // itself, not this double.
-      dataDir: async () => `/tmp/${pluginId}`,
+      dataDir: async () => options.dataDir ?? `/tmp/${pluginId}`,
     },
 
     db: options.db
@@ -902,6 +929,27 @@ export function createFakeContext(
     disposables,
 
     hosts: {
+      importMany: async (rows) => {
+        const created = rows.map(() => nextHostId++);
+        return {
+          success: created.length,
+          updated: 0,
+          skipped: 0,
+          failed: 0,
+          errors: [],
+          createdHostIds: created,
+        };
+      },
+      importSshConfig: async () => ({
+        success: 0,
+        updated: 0,
+        skipped: 0,
+        failed: 0,
+        errors: [],
+        createdHostIds: [],
+      }),
+      exportMany: async () => ({ hosts: [] }),
+      registerImportNormalizer: () => () => {},
       list: async () => [...hostsById.values()],
       get: async (hostId) => hostsById.get(hostId) ?? null,
       checkAccess: async (hostId): Promise<PluginHostAccess> => {
@@ -971,7 +1019,29 @@ export function createFakeContext(
       recordActivity: async (hostId, type, hostName) => {
         activities.push({ hostId, type, hostName });
       },
+      probeTargets: async (filter) =>
+        (options.probeTargets ?? []).filter(
+          (target) => !filter?.hostIds || filter.hostIds.includes(target.id),
+        ),
+      sessionActive: (hostId) =>
+        options.activeSessions?.includes(hostId) ?? false,
+      activity: {
+        provide: (provider) => {
+          activityProviders.push(provider);
+          return () => {
+            const at = activityProviders.indexOf(provider);
+            if (at >= 0) activityProviders.splice(at, 1);
+          };
+        },
+      },
       status: {
+        provide: (provider) => {
+          hostStatusProviders.push(provider);
+          return () => {
+            const at = hostStatusProviders.indexOf(provider);
+            if (at >= 0) hostStatusProviders.splice(at, 1);
+          };
+        },
         get: async (hostId) => hostStatuses.get(hostId) ?? null,
         check: async (hostId) => hostStatuses.get(hostId) ?? null,
         reportLogin: (hostId, outcome) => {
@@ -996,12 +1066,45 @@ export function createFakeContext(
     },
 
     audit: {
+      subscribe: (handler) => {
+        auditSubscribers.add(handler);
+        return () => {
+          auditSubscribers.delete(handler);
+        };
+      },
+      list: async (listOptions) => {
+        const matching = filterAuditEntries(
+          options.auditEntries ?? [],
+          listOptions?.filters,
+        ).reverse();
+        const offset = listOptions?.offset ?? 0;
+        return {
+          entries: matching.slice(offset, offset + (listOptions?.limit ?? 50)),
+          total: matching.length,
+        };
+      },
+      exportBatches: async function* (filters, batchSize) {
+        const matching = filterAuditEntries(
+          options.auditEntries ?? [],
+          filters,
+        );
+        const size = batchSize ?? 500;
+        for (let at = 0; at < matching.length; at += size) {
+          yield matching.slice(at, at + size);
+        }
+      },
       record: async (entry) => {
         audits.push({ ...entry });
       },
     },
 
+    network: {
+      tcpProbe: async (host, port) => options.reachable?.(host, port) ?? false,
+    },
+
     ssh: {
+      probe: async (hostId, probeOptions) =>
+        options.reachable?.(hostId, probeOptions?.port) ?? false,
       connect: async (host, connectOptions) => {
         sshConnections.push({ host, options: connectOptions });
         return {
@@ -1013,6 +1116,16 @@ export function createFakeContext(
           dispose: () => {},
         };
       },
+      exec: async (host) => {
+        sshConnections.push({ host });
+        return {
+          stdout: "",
+          stderr: "",
+          code: 0,
+          truncated: false,
+          timedOut: false,
+        };
+      },
       withConnection: async (host, connectOptions, fn) => {
         sshConnections.push({ host, pool: connectOptions.pool });
         return fn(sshClient as never);
@@ -1169,6 +1282,7 @@ export function createFakeContext(
         return { success: true };
       },
       available: () => options.desktopAvailable ?? false,
+      local: options.desktopLocal ?? unavailableDesktopLocal(),
     },
 
     credentials: {
@@ -1195,6 +1309,13 @@ export function createFakeContext(
         credentialReads.push({ hostId, protocol });
         return options.protocolTargets?.[`${hostId}:${protocol}`] ?? null;
       },
+      publicKey: async (credentialId) =>
+        (options.sshKeyCredentials ?? []).find((k) => k.id === credentialId)
+          ?.publicKey ?? null,
+      resolveKeyRefs: async (key, passphrase) => ({
+        key,
+        passphrase: passphrase ?? undefined,
+      }),
       registerSecretResolver: (scheme, resolve) => {
         auth.secretResolvers.set(scheme, resolve);
         disposals.push(() => {
@@ -1345,6 +1466,8 @@ export function createFakeContext(
       return errors;
     },
     disposals,
+    hostStatusProviders,
+    activityProviders,
     emitted,
     kv,
     tables,
@@ -1368,6 +1491,9 @@ export function createFakeContext(
     tls,
     secretStore,
     audits,
+    emitAudit: (entry) => {
+      for (const handler of auditSubscribers) handler(entry);
+    },
     activities,
     trackedSessions,
     interactions,
@@ -1409,6 +1535,8 @@ export interface MockContextOptions {
   settings?: Record<string, unknown>;
   /** Seed for the core settings readCore can reach. */
   coreSettings?: Record<string, string>;
+  /** What ctx.files.dataDir() answers. */
+  dataDir?: string;
   /** Acting user returned by currentActor and used by asUser. */
   actor?: string;
   /** What ctx.ssh.connect and withConnection hand back as the client. */
@@ -1434,8 +1562,18 @@ export interface MockContextOptions {
   sshKeyCredentials?: PluginSshKeyCredential[];
   /** What ctx.desktop.available() answers. */
   desktopAvailable?: boolean;
+  /** What ctx.desktop.local is. See FakeContextOptions. */
+  desktopLocal?: PluginDesktopLocal;
+  /** See FakeContextOptions. */
+  auditEntries?: PluginAuditEntry[];
   /** What ctx.hosts.status answers. See FakeContextOptions. */
   hostStatuses?: Record<number, PluginHostStatusEntry>;
+  /** What ctx.hosts.probeTargets answers. */
+  probeTargets?: PluginHostProbeTarget[];
+  /** Host ids ctx.hosts.sessionActive answers true for. */
+  activeSessions?: number[];
+  /** What ctx.network.tcpProbe and ctx.ssh.probe answer. */
+  reachable?: (target: string | number, port?: number) => boolean;
   /** The acting user's channels, what ctx.notify.channels answers. */
   notificationChannels?: PluginNotificationChannel[];
   /**
@@ -1481,6 +1619,63 @@ export interface MockPluginContext extends FakePluginContext {
  * (users:impersonate on issueUserToken), and users:read on ctx.users. Reading a plugin's own settings is deliberately
  * ungated. As the SDK grows a member, add its gate here in the same shape.
  */
+function filterAuditEntries(
+  entries: PluginAuditEntry[],
+  filters: PluginAuditFilters | undefined,
+): PluginAuditEntry[] {
+  return entries.filter(
+    (entry) =>
+      (filters?.userId === undefined || entry.userId === filters.userId) &&
+      (filters?.action === undefined || entry.action === filters.action) &&
+      (filters?.resourceType === undefined ||
+        entry.resourceType === filters.resourceType) &&
+      (filters?.success === undefined || entry.success === filters.success) &&
+      (filters?.startDate === undefined ||
+        entry.timestamp >= filters.startDate) &&
+      (filters?.endDate === undefined || entry.timestamp <= filters.endDate),
+  );
+}
+
+function gateDesktopLocal(
+  target: PluginDesktopLocal,
+  check: () => void,
+): PluginDesktopLocal {
+  const wrap = (value: unknown): unknown => {
+    if (typeof value === "function") {
+      return (...args: unknown[]) => {
+        check();
+        return (value as (...a: unknown[]) => unknown)(...args);
+      };
+    }
+    if (value && typeof value === "object") {
+      return new Proxy(value as object, {
+        get: (obj, key) => wrap((obj as Record<string | symbol, unknown>)[key]),
+      });
+    }
+    return value;
+  };
+  return new Proxy(target, {
+    get: (obj, key) =>
+      key === "available"
+        ? obj.available
+        : wrap((obj as unknown as Record<string | symbol, unknown>)[key]),
+  });
+}
+
+function unavailableDesktopLocal(): PluginDesktopLocal {
+  const fail = (): never => {
+    throw new Error("ctx.desktop.local needs the desktopLocal test option");
+  };
+  const deep = (): unknown =>
+    new Proxy(() => fail(), { get: () => deep(), apply: () => fail() });
+  return {
+    available: () => false,
+    info: fail,
+    fs: deep(),
+    pty: deep(),
+  } as unknown as PluginDesktopLocal;
+}
+
 export function createMockCtx(
   options: MockContextOptions = {},
 ): MockPluginContext {
@@ -1492,6 +1687,7 @@ export function createMockCtx(
     actor: options.actor,
     settings: options.settings,
     coreSettings: options.coreSettings,
+    dataDir: options.dataDir,
     sshClient: options.sshClient,
     db: options.db,
     router: options.router,
@@ -1504,7 +1700,12 @@ export function createMockCtx(
     protocolTargets: options.protocolTargets,
     sshKeyCredentials: options.sshKeyCredentials,
     desktopAvailable: options.desktopAvailable,
+    desktopLocal: options.desktopLocal,
+    auditEntries: options.auditEntries,
     hostStatuses: options.hostStatuses,
+    probeTargets: options.probeTargets,
+    activeSessions: options.activeSessions,
+    reachable: options.reachable,
     notificationChannels: options.notificationChannels,
     fetch: options.fetch,
     process: options.process,
@@ -1650,6 +1851,23 @@ export function createMockCtx(
     },
 
     hosts: {
+      importMany: async (rows, importOptions) => {
+        require("hosts:write");
+        if (importOptions?.credentials?.length) require("credentials:write");
+        return ctx.hosts.importMany(rows, importOptions);
+      },
+      importSshConfig: async (content, importOptions) => {
+        require("hosts:write");
+        return ctx.hosts.importSshConfig(content, importOptions);
+      },
+      exportMany: async (exportOptions) => {
+        require("hosts:export");
+        return ctx.hosts.exportMany(exportOptions);
+      },
+      registerImportNormalizer: (normalizer) => {
+        require("hosts:write");
+        return ctx.hosts.registerImportNormalizer(normalizer);
+      },
       list: async () => {
         require("hosts:read");
         return ctx.hosts.list();
@@ -1698,7 +1916,26 @@ export function createMockCtx(
         require("hosts:read");
         return ctx.hosts.recordActivity(hostId, type, hostName);
       },
+      probeTargets: async (filter) => {
+        require("hosts:read");
+        return ctx.hosts.probeTargets(filter);
+      },
+      sessionActive: (hostId) => {
+        require("hosts:read");
+        return ctx.hosts.sessionActive(hostId);
+      },
+      activity: {
+        provide: (provider) => {
+          require("hosts:activity-provide");
+          return ctx.hosts.activity.provide(provider);
+        },
+      },
       status: {
+        provide: (provider) => {
+          require("hosts:read");
+          require("hosts:status-provide");
+          return ctx.hosts.status.provide(provider);
+        },
         get: async (hostId) => {
           require("hosts:read");
           return ctx.hosts.status.get(hostId);
@@ -1720,11 +1957,20 @@ export function createMockCtx(
 
     ssh: {
       ...ctx.ssh,
+      probe: async (hostId, probeOptions) => {
+        require("ssh:connect");
+        return ctx.ssh.probe(hostId, probeOptions);
+      },
       connect: async (host, connectOptions) => {
         require("ssh:connect");
         require("credentials:use");
         return ctx.ssh.connect(host, connectOptions);
       },
+      exec: async (host, command, execOptions) => {
+        require("ssh:connect");
+        require("credentials:use");
+        return ctx.ssh.exec(host, command, execOptions);
+      },
       withConnection: async (host, connectOptions, fn) => {
         require("ssh:connect");
         require("credentials:use");
@@ -1820,6 +2066,22 @@ export function createMockCtx(
       },
     },
 
+    audit: {
+      record: (entry) => ctx.audit.record(entry),
+      subscribe: (handler) => {
+        require("audit:read");
+        return ctx.audit.subscribe(handler);
+      },
+      list: async (listOptions) => {
+        require("audit:read");
+        return ctx.audit.list(listOptions);
+      },
+      exportBatches: (filters, batchSize) => {
+        require("audit:read");
+        return ctx.audit.exportBatches(filters, batchSize);
+      },
+    },
+
     desktop: {
       openIsolatedWindow: async (request) => {
         require("desktop:window");
@@ -1830,6 +2092,9 @@ export function createMockCtx(
         return ctx.desktop.launchExternalClient(request);
       },
       available: () => ctx.desktop.available(),
+      local: gateDesktopLocal(ctx.desktop.local, () =>
+        require("desktop:local"),
+      ),
     },
 
     credentials: {
@@ -1851,6 +2116,14 @@ export function createMockCtx(
         }
         return ctx.credentials.resolveHostProtocol(hostId, protocol);
       },
+      publicKey: async (credentialId) => {
+        require("credentials:use");
+        return ctx.credentials.publicKey(credentialId);
+      },
+      resolveKeyRefs: async (key, passphrase) => {
+        require("credentials:read");
+        return ctx.credentials.resolveKeyRefs(key, passphrase);
+      },
       registerSecretResolver: (scheme, resolve) => {
         require("auth:provide");
         ctx.credentials.registerSecretResolver(scheme, resolve);
@@ -1877,6 +2150,13 @@ export function createMockCtx(
       return ctx.fetch(url, init);
     },
 
+    network: {
+      tcpProbe: async (host, port, probeOptions) => {
+        require("network:probe");
+        return ctx.network.tcpProbe(host, port, probeOptions);
+      },
+    },
+
     process: {
       run: async (file, args, runOptions) => {
         require("process:spawn");

packages/plugin-sdk/ui.api.txt

@@ -115,13 +115,11 @@ DropdownMenuSubTrigger (value): ({ className, inset, children, ...props }: Dropd
 DropdownMenuTrigger (value): ({ ...props }: DropdownMenuTriggerProps & RefAttributes<HTMLButtonElement>) => Element
 EditingWidth (type): EditingWidth
 EmptyState (value): ({ icon: Icon, title, hint, action, className, }: { icon?: LucideIcon; title: string; hint?: string; action?: ReactNode; className?: string; }) => Element
-ExportPayload (type): ExportPayload
 FOLDER_COLORS (value): string[]
 FONT_SIZES (value): { id: FontSizeId; label: string; }[]
 Facts (value): ({ className, children, }: { className?: string; children: ReactNode; }) => Element
 FakeSwitch (value): ({ defaultChecked, disabled, checked, onChange, }: { defaultChecked?: boolean; disabled?: boolean; checked?: boolean; onChange?: (v: boolean) => void; }) => Element
 Field (value): ({ label, hint, error, aside, htmlFor, className, children, }: { label: string; hint?: ReactNode; error?: string; aside?: ReactNode; htmlFor?: string; className?: string; children: ReactNode; }) => Element
-FieldGroup (type): FieldGroup
 FieldPair (value): ({ children }: { children: ReactNode; }) => Element
 FolderAccessRule (type): FolderAccessRule
 FolderIconEl (value): ({ icon, className, style, }: { icon?: string; className?: string; style?: CSSProperties; }) => Element
@@ -200,6 +198,7 @@ NumberField (value): ({ label, value, onChange, placeholder, hint, error, min, m
 OPEN_PLUGINS_EVENT (value): "termix:open-plugins"
 OpenTabRecord (type): OpenTabRecord
 PANEL (value): { readonly body: "p-2.5"; readonly gap: "gap-2"; readonly band: "px-3 py-2"; readonly cardHead: "px-3 py-2.5"; readonly header: "h-12.5"; }
+PRESETS (value): Record<"simple" | "balanced" | "advanced", UiAreaPreferences>
 PROMPT_BUTTON (value): "inline-flex h-7 items-center justify-center gap-1.5 border border-border px-3 text-xs text-muted-foreground transition-colors hover:bg-muted hover:text-foreground focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50"
 PROMPT_DESTRUCTIVE_BUTTON (value): "inline-flex h-7 items-center justify-center gap-1.5 bg-destructive px-3 text-xs font-medium text-white transition-colors hover:bg-destructive/90 focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50"
 PROMPT_PRIMARY_BUTTON (value): "inline-flex h-7 items-center justify-center gap-1.5 border border-accent-brand/40 px-3 text-xs font-medium text-accent-brand transition-colors hover:bg-accent-brand/10 focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50"
@@ -344,13 +343,11 @@ adminUpdateUserCredential (value): (targetUserId: string, credentialId: number,
 adminUpdateUserHost (value): (targetUserId: string, hostId: number, hostData: HostData) => Promise<Host>
 applyAccentColor (value): (colorValue: string) => void
 applyFontSize (value): (id: FontSizeId) => void
-applyPresetSideEffects (value): (preset: "advanced" | "simple" | "balanced") => Promise<void>
+applyPresetSideEffects (value): (preset: "simple" | "balanced" | "advanced") => Promise<void>
 applyUiFont (value): (id: UiFontId) => void
 assignRoleToUser (value): (userId: string, roleId: number) => Promise<{ success: boolean; }>
 beginSplitDrag (value): (source: SplitDragSource, x: number, y: number) => void
-buildExportPayload (value): (raw: ExportPayload, selected: Set<string>, groups: Set<FieldGroup>, withCredentials: boolean, pluginSecrets?: PluginSecretKeys) => ExportPayload
 buildOriginWsUrl (value): ({ origin, localPort, localPath, remotePath, includeJwt, }: { origin: ConnectionOrigin; localPort: number; localPath: string; remotePath: string; includeJwt?: boolean; }) => Promise<WebSocketConnectionTarget>
-bulkImportSSHHosts (value): (hosts: HostData[], overwrite?: boolean, credentials?: Record<string, unknown>[]) => Promise<{ message: string; success: number; updated: number; skipped: number; failed: number; errors: string[]; }>
 bulkUpdateSSHHosts (value): (hostIds: number[], updates: Record<string, unknown>) => Promise<{ updated: number; failed: number; errors: string[]; }>
 canConfigureUpdates (value): (state: DesktopUpdateState) => state is DesktopUpdateState
 canJoinSplit (value): (tab: Tab) => boolean
@@ -379,22 +376,17 @@ deleteOpenTab (value): (instanceId: string) => Promise<void>
 deleteRole (value): (roleId: number) => Promise<{ success: boolean; }>
 deleteSSHHost (value): (hostId: number) => Promise<Record<string, unknown>>
 deleteUser (value): (username: string, successorUserId?: string) => Promise<Record<string, unknown>>
-deployCredentialToHost (value): (credentialId: number, targetHostId: number) => Promise<Record<string, unknown>>
 desktopUpdates (value): () => DesktopUpdatesBridge
 docsUrl (value): (page?: "dashboard" | "users" | "sessions" | "roles" | "branding" | "database" | "manage" | "settings" | "plugins" | "install" | "cli" | "develop" | "home" | "updating" | "betas" | "envVars" | "https" | "reverseProxy" | "desktopSync" | "interface" | "hosts" | "portKnocking" | "hostDefaults" | "credentials" | "sharing" | "account" | "accountSecurity" | "accountData" | "apiKeys" | "commandPalette" | "interfaceSettings" | "appearance" | "keybindings" | "adminGeneral" | "adminDatabase" | "adminSsl" | "auditLog" | "importExport" | "pluginCatalog" | "communityRegistry" | "pluginRegistries" | "hostRegistry") => string
 duplicateCredential (value): (credentialId: number, data: Record<string, unknown>) => Promise<Record<string, unknown>>
 enabledHostProtocols (value): (host: { pluginSettings?: Record<string, Record<string, unknown>>; }, list?: HostProtocolDef[]) => HostProtocolDef[]
 endSplitDrag (value): (commit: boolean) => void
-exportAllSSHHosts (value): { (): Promise<{ hosts: Host[]; }>; (options: { share: true; }): Promise<{ version: string; exportedAt: string; credentials: Record<string, unknown>[]; hosts: Host[]; }>; }
 filterPaletteItems (value): (items: PaletteItemDef[], query: string, showWhenEmpty?: boolean) => PaletteItemDef[]
 findCoreHostDefault (value): (key: string) => CoreHostDefault
 findMatchingKeybinding (value): (e: KeyboardEvent, bindings: CustomKeybinding[]) => CustomKeybinding
-generateKeyPair (value): (keyType: "ssh-ed25519" | "ssh-rsa" | "ecdsa-sha2-nistp256", keySize?: number, passphrase?: string) => Promise<GeneratedKeyPair>
-generatePublicKeyFromPrivate (value): (privateKey: string, keyPassword?: string) => Promise<GeneratedPublicKey>
 getActiveSessions (value): () => Promise<ActiveSessionInfo[]>
 getAdaptiveResourceBudget (value): (kind: AdaptiveTaskKind) => AdaptiveResourceBudget
 getApiKeys (value): () => Promise<{ apiKeys: ApiKey[]; }>
-getAuditForwarding (value): () => Promise<AuditForwardingSettings>
 getAuditLogActions (value): () => Promise<{ actions: string[]; }>
 getAuditLogs (value): (filters?: AuditLogFilters) => Promise<AuditLogResponse>
 getBasePath (value): () => string
@@ -463,11 +455,11 @@ groupRailItems (value): (items: RailItemDef[]) => { group: RailGroup; items: Rai
 hasVisibleFields (value): (fields: PluginSettingsField[]) => boolean
 hostActionsFor (value): (all: HostActionDef[], host: Host, kind?: "open" | "connect") => HostActionDef[]
 hostBadgesFor (value): (all: HostBadgeDef[], host: Host) => HostBadgeDef[]
-hostKey (value): (host: Record<string, unknown>) => string
+hostEditorToolbarItemsFor (value): (all: HostBadgeDef[], host: Host) => HostBadgeDef[]
 hostMenuItemsFor (value): (all: HostContextMenuItemDef[], host: Host) => HostContextMenuItemDef[]
 hostProtocolFlags (value): (host: { enableSsh?: boolean; pluginSettings?: Record<string, Record<string, unknown>>; }, list?: HostProtocolDef[]) => HostProtocols
+hostStatusIndicatorsFor (value): (all: HostBadgeDef[], host: Host) => HostBadgeDef[]
 hydrateLocalSharedHostAuth (value): <T>(host: T) => Promise<T>
-importSSHConfigHosts (value): (content: string, overwrite?: boolean) => Promise<{ message: string; success: number; updated: number; skipped: number; failed: number; errors: string[]; }>
 invalidateHostsAndStatusCaches (value): () => void
 invalidateServerStatusCache (value): () => void
 isCoreRailView (value): (id: string) => boolean
@@ -492,7 +484,6 @@ makeUserAdmin (value): (userId: string) => Promise<Record<string, unknown>>
 mapCredentials (value): (res: unknown) => Credential[]
 markAdaptiveResourceUsed (value): (kind: AdaptiveTaskKind, action: string, now?: number) => void
 markTabSurfaceUsed (value): (type: TabType) => void
-maskSecrets (value): (payload: ExportPayload, pluginSecrets?: PluginSecretKeys) => ExportPayload
 moveRailItem (value): (items: RailItemDef[], id: string, beforeId: string) => string[]
 moveSplitDrag (value): (x: number, y: number) => void
 normalizeLanguageCode (value): (language?: string) => string
@@ -503,7 +494,6 @@ parseCustomKeybindings (value): (raw?: string) => CustomKeybinding[]
 parseServerTime (value): (ts: string) => Date
 pluginKey (value): { (pluginId: string, key: string): string; (pluginId: string, key: string): string; }
 pluginName (value): (t: Translator, plugin: { id: string; name: string; }) => string
-pluginSecretKeys (value): (summaries: { id: string; contributes?: { settings?: { host?: { fields?: { key: string; secretKeys?: string[]; }[]; }; }; }; }[]) => PluginSecretKeys
 pluginWsUrl (value): (pluginId: string, path: string, options?: { origin?: ConnectionOrigin; }) => Promise<WebSocketConnectionTarget>
 preloadTabSurface (value): (type: TabType) => void
 previewHostDefaultsLevel (value): (target: HostDefaultsTarget, change: HostDefaultsChange) => Promise<{ changedHosts: number; }>
@@ -576,8 +566,6 @@ tabJumpHotkeyKeys (value): () => string[]
 takePendingManageRequest (value): () => ManageRequest
 unlinkExternalFromPasswordAccount (value): (userId: string) => Promise<{ success: boolean; message: string; }>
 unlinkServer (value): (keepData: boolean) => Promise<SyncStatus>
-updateAuditForwarding (value): (url: string, token?: string) => Promise<{ url: string; hasToken: boolean; }>
-updateBranding (value): (update: BrandingSettingsUpdate) => Promise<BrandingSettings>
 updateCredential (value): (credentialId: number, credentialData: Record<string, unknown>) => Promise<Record<string, unknown>>
 updateExternalAutoProvision (value): (enabled: boolean) => Promise<Record<string, unknown>>
 updateFolderMetadata (value): (name: string, color?: string, icon?: string, credentialId?: number, localOnly?: boolean) => Promise<void>
@@ -613,8 +601,10 @@ useHostActions (value): () => HostActionDef[]
 useHostBadges (value): () => HostBadgeDef[]
 useHostContextMenuItems (value): () => HostContextMenuItemDef[]
 useHostEditorSections (value): () => HostEditorSectionDef[]
+useHostEditorToolbarItems (value): () => HostBadgeDef[]
 useHostProtocols (value): () => HostProtocolDef[]
 useHostStatus (value): (hostId: number, statusCheckEnabled?: boolean) => StatusValue
+useHostStatusIndicators (value): () => HostBadgeDef[]
 useInstalledPlugins (value): () => PluginSummary[]
 useIsDefaultsEditor (value): () => boolean
 useIsMobile (value): () => boolean