@termix-ssh/plugin-sdk 1.0.12 → 1.0.15

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 1.0.15
+
+Plugin API 1.7.0.
+
+### Added
+
+- `ctx.auth.policy.provide` and the `auth:policy` capability, so a plugin can set an idle timeout, cap session length, turn off remember me and require a second factor
+- `ctx.auth.listSecondFactors` lists the second factors from every running plugin
+- `AuthEnrollmentSections` takes `factorsOnly`
+- `getHttpsSettings` and `updateHttpsSettings` in `@termix-ssh/plugin-sdk/ui`
+
+### Fixed
+
+- Plugin frontend tests against a locally linked SDK failed with a second copy of React
+
+## 1.0.14
+
+Plugin API 1.6.0.
+
+### Added
+
+- `ctx.hosts.locks.provide` and the `hosts:lock` capability, so a plugin can manage hosts that stay read only for everyone else and block adding hosts by hand
+- `ctx.hosts.setShares` to replace every grant on a host in one call
+- `ctx.credentials.list` returns the acting user's credentials by name, without secrets
+- `ctx.hosts.create` and `update` take `password`, `key`, `keyPassword`, `keyType`, `sudoPassword`, `protocolAuth` and `pluginEnable`
+
+## 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.

package/PLUGIN-GUIDE.md

@@ -1,6 +1,6 @@
 # Termix plugin guide
 
-SDK 1.0.12 | Plugin API 1.4.0
+SDK 1.0.15 | Plugin API 1.7.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.
@@ -164,7 +164,7 @@ Unknown fields are refused at every level, so a typo fails validation. The schem
 | `icon`                                 | A [Lucide](https://lucide.dev/icons/) icon name, like `Hand`.                                                       |
 | `features`                             | Up to 20 short lines shown on the plugin's page.                                                                    |
 | `docs`                                 | An https link to your docs.                                                                                         |
-| `engine.termix`                        | Termix versions you work with, like `>=26.10.0`.                                                                    |
+| `engine.termix`                        | Termix versions you work with, like `>=26.10.0`. Older Termix builds don't list a release they can't run.           |
 | `engine.api`                           | Plugin API range, like `^1.2`. A major bump of the API is breaking.                                                 |
 | `capabilities`                         | What your code may do. See the reference at the end.                                                                |
 | `dependencies`, `optionalDependencies` | Other plugins, `{ "snippets": "^1.0.0" }`. You must keep working without optional ones.                             |
@@ -226,6 +226,7 @@ Bundled as ESM for Node 22+ into `dist/backend.js`. Backend imports of your own
 | `sync`                 | none                             | Sync your tables to a linked desktop                           |
 | `auth`                 | `auth:provide`                   | Login methods, second factors, SSH auth types                  |
 | `auth.issueUserToken`  | `users:impersonate`              | A short-lived session for calling Termix's API as a user       |
+| `auth.policy`          | `auth:policy`                    | Login rules: idle timeout, session length, second factors      |
 | `users.getLocale`      | `users:read`                     | A user's UI language                                           |
 | `system`               | `system:tls`                     | The server's HTTPS certificate                                 |
 | `plugins.list()`       | `plugins:read`                   | Which plugins are installed                                    |
@@ -300,6 +301,11 @@ router.post("/notes", async (req, res) => {
 - `ctx.rbac.require("manage")` on a single route, `await ctx.rbac.has("manage")` in code. A full id like
   `hosts.edit` checks a core permission.
 - Host access: `ctx.hosts.checkAccess(hostId, "connect" | "view" | "edit" | "manage")`.
+- Managed hosts: with `hosts:lock`, `ctx.hosts.locks.provide({ isLocked, note, allowManualCreate })` makes
+  the hosts you manage read only for the UI, the API and other plugins (pins and order still work), and
+  `allowManualCreate: () => false` blocks adding hosts by hand. Your own `ctx.hosts` writes still go
+  through. `ctx.hosts.setShares(hostId, grants)` replaces a host's whole grant list, and
+  `ctx.credentials.list()` finds the acting user's credentials by name.
 
 ### Errors
 
@@ -325,6 +331,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 +494,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 +510,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`.
@@ -563,8 +599,6 @@ export function activate(app: TermixApp) {
   `classic-layout.hostTree` and `classic-layout.dashboard` for other plugins to place with `PluginComponent`.
   It reads the shell with `useShellController()` from `@termix-ssh/plugin-sdk/ui`, which exposes more than
   `useShell()` and may change with Termix. A third party layout should start from `useShell()`.
-- Example Top Bar Layout (https://github.com/Termix-SSH/Plugin-Example-Topbar-Layout) is a small third party
-  style layout built only on `useShell()`, `TabStage` and `@termix-ssh/plugin-sdk/ui`, with a phone version.
 
 A theme is CSS only. Declare it in `contributes.themes` (`id`, `label`, `mode` light or dark, `css` path,
 optional `swatch` colors for the picker) with the `ui:theme` capability. The id becomes a class on `<html>`,
@@ -582,9 +616,7 @@ A plugin that only holds themes needs no code. Leave out `src/`: `termix-plugin
 - Themes show in the picker in the order core lists its own, then the plugin's order.
 - A theme someone saved that no longer exists shows as System. It comes back when the plugin does.
 - Accent color, UI font, font size and density are not part of a theme. Core applies them on top.
-- Bundled Classic Themes (https://github.com/Termix-SSH/Plugin-Classic-Themes) is a full example, and
-  Example Theme (https://github.com/Termix-SSH/Plugin-Example-Theme) a small one with one light and one dark
-  theme.
+- Bundled Classic Themes (https://github.com/Termix-SSH/Plugin-Classic-Themes) is a full example.
 
 ## Looking native
 
@@ -668,6 +700,13 @@ closely. Declare ids in `contributes.auth` and register them with `ctx.auth.regi
 `registerSecondFactor` or `registerSshAuthProvider`. Connection protocols go in `contributes.protocols`
 and `app.registerHostProtocol`. Read https://docs.termix.site/develop/auth before starting one.
 
+Login rules need `auth:policy`. `ctx.auth.policy.provide({ evaluate, allowRememberDevice })` is asked at
+every login with the user, the method, the device and every second factor (`ctx.auth.listSecondFactors()`
+lists them too). `evaluate` returns `allowRememberDevice`, `maxSessionSeconds`, `idleTimeoutSeconds` and
+`secondFactor` (`"always"` or `"new-device"`). The strictest answer from all plugins wins, and a throw
+refuses the login. A user who must have a second factor but has none gets a session that can only set one
+up, and `/users/me` reports `restriction: "second-factor-setup"`.
+
 ## Testing
 
 ```ts
@@ -832,60 +871,68 @@ 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       |
+| `auth:policy`            | high     | Set login rules: idle timeout, session length, 2FA      |
+| `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               |
+| `hosts:lock`             | medium   | Make hosts it manages read only for everyone else       |
+| `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.