@termix-ssh/plugin-sdk 1.0.15 → 1.0.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/CHANGELOG.md +31 -0
  2. package/PLUGIN-GUIDE.md +92 -72
  3. package/dist/backend.d.ts +381 -0
  4. package/dist/capabilities.js +2 -0
  5. package/dist/frontend.d.ts +45 -0
  6. package/dist/host/{PluginsTab-S33WIIGC.js → PluginsTab-YAGYRBIE.js} +3 -3
  7. package/dist/host/{chunk-57DJU2ZA.js → chunk-2MU6WNSX.js} +1 -1
  8. package/dist/host/{chunk-VFTB2RDP.js → chunk-446UEDSK.js} +4 -2
  9. package/dist/host/{chunk-3L45NNT5.js → chunk-7LEJ3HYF.js} +20 -3
  10. package/dist/host/{chunk-V44FCJBQ.js → chunk-J2AILBXM.js} +540 -400
  11. package/dist/host/{chunk-2IV3VX7F.js → chunk-LQKK2JJA.js} +5 -1
  12. package/dist/host/core-classes.json +1 -1
  13. package/dist/host/{linked-server-SCJH7DSL.js → linked-server-OUF3POT7.js} +5 -3
  14. package/dist/host/{rbac-api-KA5IPQQL.js → rbac-api-LZVENREG.js} +1 -1
  15. package/dist/host/testing-host.js +4 -4
  16. package/dist/host/types/src/types/onboarding.d.ts +0 -1
  17. package/dist/host/types/src/ui/auth/Auth.d.ts +1 -0
  18. package/dist/host/types/src/ui/lib/linked-server.d.ts +2 -0
  19. package/dist/host/types/src/ui/plugin-host/NativeView.d.ts +19 -0
  20. package/dist/host/types/src/ui/plugin-host/sdk-ui.d.ts +2 -6
  21. package/dist/host/types/src/ui/shell/CompanionFrame.d.ts +11 -0
  22. package/dist/host/types/src/ui/shell/companions.d.ts +63 -0
  23. package/dist/host/ui.js +149 -815
  24. package/dist/host/{use-permissions-LLN6TLAL.js → use-permissions-BYCDS5PD.js} +1 -1
  25. package/dist/manifest.d.ts +1 -1
  26. package/dist/manifest.js +1 -1
  27. package/dist/testing.d.ts +5 -1
  28. package/dist/testing.js +28 -0
  29. package/package.json +1 -1
  30. package/schema/manifest.schema.json +2 -0
  31. package/dist/host/types/src/ui/api/sync-api.d.ts +0 -93
  32. package/dist/host/types/src/ui/auth/ElectronLoginForm.d.ts +0 -9
  33. package/dist/host/types/src/ui/hooks/use-sync-status.d.ts +0 -4
  34. package/dist/host/types/src/ui/lib/sync-status.d.ts +0 -6
  35. package/dist/host/types/src/ui/settings/sync/LinkServerDialog.d.ts +0 -12
  36. package/dist/host/types/src/ui/settings/sync/ProxySettingsFields.d.ts +0 -15
  37. package/dist/host/types/src/ui/settings/sync/saved-servers.d.ts +0 -3
package/CHANGELOG.md CHANGED
@@ -1,5 +1,36 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.0.18
4
+
5
+ Plugin API 1.10.0.
6
+
7
+ ### Added
8
+
9
+ - `clientCert` on the sync link, link patch and remote target, and the `client_cert` remote error kind, so a sync plugin can link to a server that needs mutual TLS
10
+
11
+ ## 1.0.17
12
+
13
+ Plugin API 1.9.0.
14
+
15
+ ### Added
16
+
17
+ - `app.registerCompanion` and `app.toggleCompanion`, so a plugin can add a panel beside any host tab. The user opens, resizes and moves it, and the tab keeps running
18
+ - `NativeView` in `@termix-ssh/plugin-sdk/ui`, which shows a web page in a native view in the desktop app, for sites that do not work in an iframe
19
+
20
+ ## 1.0.16
21
+
22
+ Plugin API 1.8.0.
23
+
24
+ ### Added
25
+
26
+ - `ctx.sync.provide` and the `sync:provide` capability, so a plugin can answer every /sync request
27
+ - `ctx.ssh.transports.provide` and the `ssh:transport` capability, so a plugin can carry SSH connections over its own stream
28
+ - `ctx.hosts.folders.ensure` and `removeEmpty`
29
+
30
+ ### Removed
31
+
32
+ - The sync screens and calls in `@termix-ssh/plugin-sdk/ui`: `LinkServerDialog`, `ProxySettingsFields`, `useSyncStatus`, `refreshSyncStatus`, `setSyncStatus`, `getSyncConflicts`, `getSyncErrors`, `retrySyncErrors`, `settleSyncConflict`, `syncNow`, `unlinkServer`, `updateSyncSettings` and their types. They moved into the sync plugin
33
+
3
34
  ## 1.0.15
4
35
 
5
36
  Plugin API 1.7.0.
package/PLUGIN-GUIDE.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Termix plugin guide
2
2
 
3
- SDK 1.0.15 | Plugin API 1.7.0
3
+ SDK 1.0.18 | Plugin API 1.10.0
4
4
 
5
5
  This guide is for anyone, person or AI coding tool, building a Termix plugin. It ships inside
6
6
  `@termix-ssh/plugin-sdk`, so the copy in your `node_modules` always matches the SDK you have installed.
@@ -202,37 +202,40 @@ Bundled as ESM for Node 22+ into `dist/backend.js`. Backend imports of your own
202
202
 
203
203
  ### What ctx has
204
204
 
205
- | Member | Capability | What it does |
206
- | ---------------------- | -------------------------------- | -------------------------------------------------------------- |
207
- | `pluginId`, `manifest` | none | Your id and manifest |
208
- | `log` | none | Log lines tagged with your plugin |
209
- | `db` | `db:own` | Your own tables |
210
- | `kv` | `kv:own` | Small key value state |
211
- | `files.dataDir()` | `files:own` | A folder of your own |
212
- | `settings` | none | Your settings |
213
- | `secrets` | `secrets:own` | Encrypted values per user, `seal`/`unseal` for your own tables |
214
- | `http`, `ws` | `network:serve` | Routes and sockets |
215
- | `rbac` | none | Check the actor's permissions |
216
- | `hosts` | `hosts:read`, `hosts:write` | List, read, create, update and share hosts as the actor |
217
- | `ssh` | `ssh:connect`, `credentials:use` | Connect to hosts through Termix's SSH pipeline |
218
- | `credentials` | varies | The actor's saved keys, and protocol logins |
219
- | `services` | per service | Call other plugins and offer your own |
220
- | `events` | `events:core` for core topics | Emit and listen for events |
221
- | `notify` | `notify:send` | Send alerts to the Alerts inbox |
222
- | `fetch` | `network:outbound` | Outbound HTTP with SSRF protection |
223
- | `process` | `process:spawn` | Run programs on the server |
224
- | `schedule` | none | Timers that stop on disable and never overlap |
225
- | `audit.record` | none | Write your own audit line |
226
- | `sync` | none | Sync your tables to a linked desktop |
227
- | `auth` | `auth:provide` | Login methods, second factors, SSH auth types |
228
- | `auth.issueUserToken` | `users:impersonate` | A short-lived session for calling Termix's API as a user |
229
- | `auth.policy` | `auth:policy` | Login rules: idle timeout, session length, second factors |
230
- | `users.getLocale` | `users:read` | A user's UI language |
231
- | `system` | `system:tls` | The server's HTTPS certificate |
232
- | `plugins.list()` | `plugins:read` | Which plugins are installed |
233
- | `asUser(userId, fn)` | always audited | Run background work as a user |
234
- | `currentActor()` | none | The user the current call runs for |
235
- | `disposables.add(fn)` | none | Extra cleanup on disable |
205
+ | Member | Capability | What it does |
206
+ | ---------------------- | -------------------------------- | --------------------------------------------------------------- |
207
+ | `pluginId`, `manifest` | none | Your id and manifest |
208
+ | `log` | none | Log lines tagged with your plugin |
209
+ | `db` | `db:own` | Your own tables |
210
+ | `kv` | `kv:own` | Small key value state |
211
+ | `files.dataDir()` | `files:own` | A folder of your own |
212
+ | `settings` | none | Your settings |
213
+ | `secrets` | `secrets:own` | Encrypted values per user, `seal`/`unseal` for your own tables |
214
+ | `http`, `ws` | `network:serve` | Routes and sockets |
215
+ | `rbac` | none | Check the actor's permissions |
216
+ | `hosts` | `hosts:read`, `hosts:write` | List, read, create, update and share hosts as the actor |
217
+ | `ssh` | `ssh:connect`, `credentials:use` | Connect to hosts through Termix's SSH pipeline |
218
+ | `credentials` | varies | The actor's saved keys, and protocol logins |
219
+ | `services` | per service | Call other plugins and offer your own |
220
+ | `events` | `events:core` for core topics | Emit and listen for events |
221
+ | `notify` | `notify:send` | Send alerts to the Alerts inbox |
222
+ | `fetch` | `network:outbound` | Outbound HTTP with SSRF protection |
223
+ | `process` | `process:spawn` | Run programs on the server |
224
+ | `schedule` | none | Timers that stop on disable and never overlap |
225
+ | `audit.record` | none | Write your own audit line |
226
+ | `sync` | none | Sync your tables to a linked desktop |
227
+ | `auth` | `auth:provide` | Login methods, second factors, SSH auth types |
228
+ | `auth.issueUserToken` | `users:impersonate` | A short-lived session for calling Termix's API as a user |
229
+ | `auth.policy` | `auth:policy` | Login rules: idle timeout, session length, second factors |
230
+ | `sync.provide` | `sync:provide` | Answers all /sync requests: server sync, linked desktops |
231
+ | `ssh.transports` | `ssh:transport` | Carries a host's SSH connection over your own stream |
232
+ | `hosts.folders` | `hosts:write` | Create a folder row with a color and icon, remove it when empty |
233
+ | `users.getLocale` | `users:read` | A user's UI language |
234
+ | `system` | `system:tls` | The server's HTTPS certificate |
235
+ | `plugins.list()` | `plugins:read` | Which plugins are installed |
236
+ | `asUser(userId, fn)` | always audited | Run background work as a user |
237
+ | `currentActor()` | none | The user the current call runs for |
238
+ | `disposables.add(fn)` | none | Extra cleanup on disable |
236
239
 
237
240
  ### The actor
238
241
 
@@ -301,6 +304,9 @@ router.post("/notes", async (req, res) => {
301
304
  - `ctx.rbac.require("manage")` on a single route, `await ctx.rbac.has("manage")` in code. A full id like
302
305
  `hosts.edit` checks a core permission.
303
306
  - Host access: `ctx.hosts.checkAccess(hostId, "connect" | "view" | "edit" | "manage")`.
307
+ - Transports: with `ssh:transport`, `ctx.ssh.transports.provide({ claims(hostId), open({ id, ip, port }) })`
308
+ returns a stream the SSH client uses instead of a direct, proxy or jump host connection. Core also serves
309
+ `/plugin-ws/core/ssh-relay?hostId=` for callers with connect access, so one Termix can relay to another.
304
310
  - Managed hosts: with `hosts:lock`, `ctx.hosts.locks.provide({ isLocked, note, allowManualCreate })` makes
305
311
  the hosts you manage read only for the UI, the API and other plugins (pins and order still work), and
306
312
  `allowManualCreate: () => false` blocks adding hosts by hand. Your own `ctx.hosts` writes still go
@@ -489,6 +495,7 @@ your plugin's error boundary and Suspense.
489
495
  | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
490
496
  | `registerRailItem` | A sidebar rail button |
491
497
  | `registerTab`, `registerPanel` | A tab type or sidebar panel (id in `contributes.tabs` / `panels`) |
498
+ | `registerCompanion`, `toggleCompanion` | A panel beside any host tab, bound to its host and handle |
492
499
  | `registerDashboardCard` | A dashboard card (`contributes.dashboardCards`) |
493
500
  | `registerHostAction` | A host button, palette entry or default connect |
494
501
  | `registerHostEditorSection` | Your own host editor section (host settings get one for free) |
@@ -624,6 +631,9 @@ Build UI from `@termix-ssh/plugin-sdk/ui` so it matches Termix and follows the t
624
631
  exports with props is `ui.api.txt` in the Termix repo
625
632
  (https://github.com/Termix-SSH/Termix/blob/main/packages/plugin-sdk/ui.api.txt).
626
633
 
634
+ - Web pages that break in an iframe: `NativeView` (props `url`, `ignoreCert`, `hidden`, `fallback`) shows the
635
+ page in a native view in the desktop app. It fills its element, hides while a dialog or menu is open and renders
636
+ `fallback` in a browser.
627
637
  - Square: panels, cards and containers have no rounded corners. Small controls may stay rounded.
628
638
  - Flat: borders, not shadows. Use theme tokens like `border-border`, `bg-background`,
629
639
  `text-muted-foreground`, `text-destructive`. One accent, `text-accent-brand`. Don't add colors.
@@ -707,6 +717,14 @@ lists them too). `evaluate` returns `allowRememberDevice`, `maxSessionSeconds`,
707
717
  refuses the login. A user who must have a second factor but has none gets a session that can only set one
708
718
  up, and `/users/me` reports `restriction: "second-factor-setup"`.
709
719
 
720
+ Sync is answered by one plugin. `sync:provide` is high risk: `ctx.sync.provide({ handle })` takes over every
721
+ request under `/sync` (an Express style handler, 404 when nothing provides it), and `ctx.sync.host` hands
722
+ over the neutral parts core keeps: the replica store (`replica`), the change feed and push applier
723
+ (`feed`), the linked server list (`links`, one per local user), desktop accounts (`accounts`), sessions
724
+ (`sessions`), host lookups, plugin mirroring and the proxy settings the desktop app needs. A test passes its
725
+ own `syncHost` to `createMockCtx`. An API key can ask `POST /users/ws-ticket/api-key` for a one minute
726
+ ticket that opens plugin sockets as its user, which is how one server opens sessions through another.
727
+
710
728
  ## Testing
711
729
 
712
730
  ```ts
@@ -893,46 +911,48 @@ To run your own registry instead, see https://docs.termix.site/develop/registrie
893
911
 
894
912
  ## Capabilities
895
913
 
896
- | Capability | Risk | What it allows |
897
- | ------------------------ | -------- | ------------------------------------------------------- |
898
- | `credentials:read` | critical | Read stored secrets for hosts the user can reach |
899
- | `system:tls` | critical | Replace the HTTPS certificate, answer CA domain checks |
900
- | `ssh:connect` | high | Run any command on hosts, with the user's access |
901
- | `process:spawn` | high | Run programs on the Termix server |
902
- | `users:write` | high | Add users and change their roles |
903
- | `users:impersonate` | high | Act as another user, or get a session for them, audited |
904
- | `db:core-refs` | high | Query core users, roles and hosts tables (read only) |
905
- | `auth:provide` | high | Add login methods, second factors, SSH auth types |
906
- | `auth:policy` | high | Set login rules: idle timeout, session length, 2FA |
907
- | `device:serial` | high | Open serial and USB ports on the server |
908
- | `desktop:local` | high | Use the user's own computer, desktop app only |
909
- | `hosts:export` | high | Export hosts with their saved logins |
910
- | `notify:hub` | high | Receive every alert (the alerts hub only) |
911
- | `ui:layout` | high | Replace the whole app layout |
912
- | `hosts:write` | medium | Add and edit hosts |
913
- | `hosts:status-provide` | medium | Be the source of host status dots |
914
- | `hosts:activity-provide` | medium | Be the source of the recent activity list |
915
- | `hosts:lock` | medium | Make hosts it manages read only for everyone else |
916
- | `network:probe` | medium | Check that a host answers on a TCP port |
917
- | `credentials:use` | medium | Connect with saved credentials without seeing them |
918
- | `credentials:write` | medium | Save new credentials |
919
- | `network:outbound` | medium | Outbound HTTP through `ctx.fetch` |
920
- | `network:serve` | medium | HTTP routes and sockets |
921
- | `network:broadcast` | medium | Local network broadcasts, like Wake-on-LAN |
922
- | `users:read` | medium | Usernames, roles and UI language |
923
- | `events:core` | medium | Listen to core events |
924
- | `notify:send` | medium | Send alerts |
925
- | `audit:read` | medium | Read the audit log |
926
- | `desktop:window` | medium | Open windows in the desktop app |
927
- | `hosts:read` | low | Read hosts the user can see |
928
- | `db:own` | low | Your own tables |
929
- | `kv:own` | low | Small key value state |
930
- | `files:own` | low | Your own folder on disk |
931
- | `secrets:own` | low | Your own encrypted secrets |
932
- | `settings:read-core` | low | Read Termix server settings |
933
- | `plugins:read` | low | See installed plugins |
934
- | `ui:surface` | low | Add tabs, panels and settings |
935
- | `ui:theme` | low | Add color themes, CSS only |
914
+ | Capability | Risk | What it allows |
915
+ | ------------------------ | -------- | ------------------------------------------------------------- |
916
+ | `credentials:read` | critical | Read stored secrets for hosts the user can reach |
917
+ | `system:tls` | critical | Replace the HTTPS certificate, answer CA domain checks |
918
+ | `ssh:connect` | high | Run any command on hosts, with the user's access |
919
+ | `process:spawn` | high | Run programs on the Termix server |
920
+ | `users:write` | high | Add users and change their roles |
921
+ | `users:impersonate` | high | Act as another user, or get a session for them, audited |
922
+ | `db:core-refs` | high | Query core users, roles and hosts tables (read only) |
923
+ | `auth:provide` | high | Add login methods, second factors, SSH auth types |
924
+ | `auth:policy` | high | Set login rules: idle timeout, session length, 2FA |
925
+ | `sync:provide` | high | Run sync: answer every /sync request |
926
+ | `device:serial` | high | Open serial and USB ports on the server |
927
+ | `desktop:local` | high | Use the user's own computer, desktop app only |
928
+ | `hosts:export` | high | Export hosts with their saved logins |
929
+ | `notify:hub` | high | Receive every alert (the alerts hub only) |
930
+ | `ui:layout` | high | Replace the whole app layout |
931
+ | `hosts:write` | medium | Add and edit hosts |
932
+ | `hosts:status-provide` | medium | Be the source of host status dots |
933
+ | `hosts:activity-provide` | medium | Be the source of the recent activity list |
934
+ | `ssh:transport` | high | Carry SSH connections for hosts it claims over its own stream |
935
+ | `hosts:lock` | medium | Make hosts it manages read only for everyone else |
936
+ | `network:probe` | medium | Check that a host answers on a TCP port |
937
+ | `credentials:use` | medium | Connect with saved credentials without seeing them |
938
+ | `credentials:write` | medium | Save new credentials |
939
+ | `network:outbound` | medium | Outbound HTTP through `ctx.fetch` |
940
+ | `network:serve` | medium | HTTP routes and sockets |
941
+ | `network:broadcast` | medium | Local network broadcasts, like Wake-on-LAN |
942
+ | `users:read` | medium | Usernames, roles and UI language |
943
+ | `events:core` | medium | Listen to core events |
944
+ | `notify:send` | medium | Send alerts |
945
+ | `audit:read` | medium | Read the audit log |
946
+ | `desktop:window` | medium | Open windows in the desktop app |
947
+ | `hosts:read` | low | Read hosts the user can see |
948
+ | `db:own` | low | Your own tables |
949
+ | `kv:own` | low | Small key value state |
950
+ | `files:own` | low | Your own folder on disk |
951
+ | `secrets:own` | low | Your own encrypted secrets |
952
+ | `settings:read-core` | low | Read Termix server settings |
953
+ | `plugins:read` | low | See installed plugins |
954
+ | `ui:surface` | low | Add tabs, panels and settings |
955
+ | `ui:theme` | low | Add color themes, CSS only |
936
956
 
937
957
  An update that adds a capability waits for an admin to approve it.
938
958