@termix-ssh/plugin-sdk 1.0.15 → 1.0.17

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 1.0.17
+
+Plugin API 1.9.0.
+
+### Added
+
+- `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
+- `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
+
+## 1.0.16
+
+Plugin API 1.8.0.
+
+### Added
+
+- `ctx.sync.provide` and the `sync:provide` capability, so a plugin can answer every /sync request
+- `ctx.ssh.transports.provide` and the `ssh:transport` capability, so a plugin can carry SSH connections over its own stream
+- `ctx.hosts.folders.ensure` and `removeEmpty`
+
+### Removed
+
+- 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
+
 ## 1.0.15
 
 Plugin API 1.7.0.

package/PLUGIN-GUIDE.md

@@ -1,6 +1,6 @@
 # Termix plugin guide
 
-SDK 1.0.15 | Plugin API 1.7.0
+SDK 1.0.17 | Plugin API 1.9.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.
@@ -202,37 +202,40 @@ Bundled as ESM for Node 22+ into `dist/backend.js`. Backend imports of your own
 
 ### What ctx has
 
-| Member                 | Capability                       | What it does                                                   |
-| ---------------------- | -------------------------------- | -------------------------------------------------------------- |
-| `pluginId`, `manifest` | none                             | Your id and manifest                                           |
-| `log`                  | none                             | Log lines tagged with your plugin                              |
-| `db`                   | `db:own`                         | Your own tables                                                |
-| `kv`                   | `kv:own`                         | Small key value state                                          |
-| `files.dataDir()`      | `files:own`                      | A folder of your own                                           |
-| `settings`             | none                             | Your settings                                                  |
-| `secrets`              | `secrets:own`                    | Encrypted values per user, `seal`/`unseal` for your own tables |
-| `http`, `ws`           | `network:serve`                  | Routes and sockets                                             |
-| `rbac`                 | none                             | Check the actor's permissions                                  |
-| `hosts`                | `hosts:read`, `hosts:write`      | List, read, create, update and share hosts as the actor        |
-| `ssh`                  | `ssh:connect`, `credentials:use` | Connect to hosts through Termix's SSH pipeline                 |
-| `credentials`          | varies                           | The actor's saved keys, and protocol logins                    |
-| `services`             | per service                      | Call other plugins and offer your own                          |
-| `events`               | `events:core` for core topics    | Emit and listen for events                                     |
-| `notify`               | `notify:send`                    | Send alerts to the Alerts inbox                                |
-| `fetch`                | `network:outbound`               | Outbound HTTP with SSRF protection                             |
-| `process`              | `process:spawn`                  | Run programs on the server                                     |
-| `schedule`             | none                             | Timers that stop on disable and never overlap                  |
-| `audit.record`         | none                             | Write your own audit line                                      |
-| `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                                    |
-| `asUser(userId, fn)`   | always audited                   | Run background work as a user                                  |
-| `currentActor()`       | none                             | The user the current call runs for                             |
-| `disposables.add(fn)`  | none                             | Extra cleanup on disable                                       |
+| Member                 | Capability                       | What it does                                                    |
+| ---------------------- | -------------------------------- | --------------------------------------------------------------- |
+| `pluginId`, `manifest` | none                             | Your id and manifest                                            |
+| `log`                  | none                             | Log lines tagged with your plugin                               |
+| `db`                   | `db:own`                         | Your own tables                                                 |
+| `kv`                   | `kv:own`                         | Small key value state                                           |
+| `files.dataDir()`      | `files:own`                      | A folder of your own                                            |
+| `settings`             | none                             | Your settings                                                   |
+| `secrets`              | `secrets:own`                    | Encrypted values per user, `seal`/`unseal` for your own tables  |
+| `http`, `ws`           | `network:serve`                  | Routes and sockets                                              |
+| `rbac`                 | none                             | Check the actor's permissions                                   |
+| `hosts`                | `hosts:read`, `hosts:write`      | List, read, create, update and share hosts as the actor         |
+| `ssh`                  | `ssh:connect`, `credentials:use` | Connect to hosts through Termix's SSH pipeline                  |
+| `credentials`          | varies                           | The actor's saved keys, and protocol logins                     |
+| `services`             | per service                      | Call other plugins and offer your own                           |
+| `events`               | `events:core` for core topics    | Emit and listen for events                                      |
+| `notify`               | `notify:send`                    | Send alerts to the Alerts inbox                                 |
+| `fetch`                | `network:outbound`               | Outbound HTTP with SSRF protection                              |
+| `process`              | `process:spawn`                  | Run programs on the server                                      |
+| `schedule`             | none                             | Timers that stop on disable and never overlap                   |
+| `audit.record`         | none                             | Write your own audit line                                       |
+| `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       |
+| `sync.provide`         | `sync:provide`                   | Answers all /sync requests: server sync, linked desktops        |
+| `ssh.transports`       | `ssh:transport`                  | Carries a host's SSH connection over your own stream            |
+| `hosts.folders`        | `hosts:write`                    | Create a folder row with a color and icon, remove it when empty |
+| `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                                     |
+| `asUser(userId, fn)`   | always audited                   | Run background work as a user                                   |
+| `currentActor()`       | none                             | The user the current call runs for                              |
+| `disposables.add(fn)`  | none                             | Extra cleanup on disable                                        |
 
 ### The actor
 
@@ -301,6 +304,9 @@ 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")`.
+- Transports: with `ssh:transport`, `ctx.ssh.transports.provide({ claims(hostId), open({ id, ip, port }) })`
+  returns a stream the SSH client uses instead of a direct, proxy or jump host connection. Core also serves
+  `/plugin-ws/core/ssh-relay?hostId=` for callers with connect access, so one Termix can relay to another.
 - 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
@@ -489,6 +495,7 @@ your plugin's error boundary and Suspense.
 | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
 | `registerRailItem`                                                                 | A sidebar rail button                                             |
 | `registerTab`, `registerPanel`                                                     | A tab type or sidebar panel (id in `contributes.tabs` / `panels`) |
+| `registerCompanion`, `toggleCompanion`                                             | A panel beside any host tab, bound to its host and handle         |
 | `registerDashboardCard`                                                            | A dashboard card (`contributes.dashboardCards`)                   |
 | `registerHostAction`                                                               | A host button, palette entry or default connect                   |
 | `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
 exports with props is `ui.api.txt` in the Termix repo
 (https://github.com/Termix-SSH/Termix/blob/main/packages/plugin-sdk/ui.api.txt).
 
+- Web pages that break in an iframe: `NativeView` (props `url`, `ignoreCert`, `hidden`, `fallback`) shows the
+  page in a native view in the desktop app. It fills its element, hides while a dialog or menu is open and renders
+  `fallback` in a browser.
 - Square: panels, cards and containers have no rounded corners. Small controls may stay rounded.
 - Flat: borders, not shadows. Use theme tokens like `border-border`, `bg-background`,
   `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`,
 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"`.
 
+Sync is answered by one plugin. `sync:provide` is high risk: `ctx.sync.provide({ handle })` takes over every
+request under `/sync` (an Express style handler, 404 when nothing provides it), and `ctx.sync.host` hands
+over the neutral parts core keeps: the replica store (`replica`), the change feed and push applier
+(`feed`), the linked server list (`links`, one per local user), desktop accounts (`accounts`), sessions
+(`sessions`), host lookups, plugin mirroring and the proxy settings the desktop app needs. A test passes its
+own `syncHost` to `createMockCtx`. An API key can ask `POST /users/ws-ticket/api-key` for a one minute
+ticket that opens plugin sockets as its user, which is how one server opens sessions through another.
+
 ## Testing
 
 ```ts
@@ -893,46 +911,48 @@ To run your own registry instead, see https://docs.termix.site/develop/registrie
 
 ## 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       |
-| `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                              |
+| 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            |
+| `sync:provide`           | high     | Run sync: answer every /sync request                          |
+| `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                     |
+| `ssh:transport`          | high     | Carry SSH connections for hosts it claims over its own stream |
+| `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.
 

package/dist/backend.d.ts

@@ -201,6 +201,346 @@ export interface SyncEntityRegistration {
  */
 export interface PluginSync {
     registerEntity: (entity: SyncEntityRegistration) => void;
+    /** Needs sync:provide. Takes over /sync/v2 and /sync/link. Removed on deactivate. */
+    provide: (provider: PluginSyncProvider) => () => void;
+    /** Needs sync:provide. The replica store, change feed and link registry. */
+    readonly host: PluginSyncHost;
+}
+/**
+ * The plugin that owns server and desktop sync. Core forwards every request
+ * under /sync to `handle` (an Express style handler) and answers 404 when no
+ * plugin provides it. Call `next()` to let core answer instead.
+ */
+export interface PluginSyncProvider {
+    handle: (req: unknown, res: unknown, next: (error?: unknown) => void) => void | Promise<void>;
+}
+/** A kind of data that syncs, as the sync provider sees it. */
+export interface SyncEntityInfo {
+    type: string;
+    owner: string;
+    order: number;
+    readOnly: boolean;
+    /** Whether the row would show in a load even if it exists. */
+    covers?: (syncId: string) => boolean;
+}
+/** A row ready for the wire, with its content hash. */
+export interface SyncWireRow {
+    syncId: string;
+    wire: SyncRow;
+    hash: string;
+}
+export interface SyncRecordInfo {
+    entityType: string;
+    syncId: string;
+    revision: number;
+    hash: string | null;
+    deleted: boolean;
+    error: string | null;
+    errorHash: string | null;
+    seq: number;
+}
+export interface SyncConflictInfo {
+    id: number;
+    entityType: string;
+    syncId: string;
+    localRow: string;
+    createdAt: string;
+}
+export interface SyncAccountInfo {
+    id: string;
+    username: string;
+    isAdmin: boolean;
+    active: boolean;
+}
+export interface SyncProxyHeader {
+    name: string;
+    value: string;
+}
+export interface SyncBasicAuth {
+    username: string;
+    password: string;
+}
+/** Extra per server connection options. Kept open so new ones need no migration. */
+export type SyncLinkOptions = Record<string, unknown>;
+/** One server a desktop is linked to, with a replica of its data. */
+export interface SyncLinkInfo {
+    id: number;
+    /** The local user the replica belongs to. */
+    userId: string;
+    serverUrl: string;
+    serverName: string | null;
+    serverVersion: string | null;
+    sessionToken: string | null;
+    customHeaders: SyncProxyHeader[];
+    basicAuth: SyncBasicAuth | null;
+    allowInvalidCertificate: boolean;
+    remoteUserId: string | null;
+    remoteUsername: string | null;
+    account: {
+        remoteUserId?: string;
+        username?: string;
+        isAdmin?: boolean;
+        roles?: string[];
+        permissions?: string[];
+    } | null;
+    disabledTypes: string[];
+    /** Extra connection options for this server, kept open for new ones. */
+    options: SyncLinkOptions;
+    knownTypes: string[];
+    cursor: number;
+    status: "idle" | "syncing" | "offline" | "error" | "signed_out";
+    lastError: string | null;
+    linkedAt: string;
+    lastSyncAt: string | null;
+}
+export interface SyncLinkCreate {
+    userId: string;
+    serverUrl: string;
+    serverName?: string | null;
+    serverVersion?: string | null;
+    sessionToken: string;
+    customHeaders?: SyncProxyHeader[];
+    basicAuth?: SyncBasicAuth | null;
+    allowInvalidCertificate?: boolean;
+    remoteUserId?: string | null;
+    remoteUsername?: string | null;
+}
+export type SyncLinkPatch = Partial<Pick<SyncLinkInfo, "serverName" | "serverVersion" | "sessionToken" | "customHeaders" | "basicAuth" | "allowInvalidCertificate" | "remoteUserId" | "remoteUsername" | "account" | "disabledTypes" | "options" | "knownTypes" | "cursor" | "status" | "lastError" | "lastSyncAt">>;
+export type SyncRemoteErrorKind = "offline" | "tls" | "proxy" | "basic_auth" | "signed_out" | "server";
+export interface SyncRemoteError extends Error {
+    readonly kind: SyncRemoteErrorKind;
+    readonly status?: number;
+}
+export interface SyncRemoteTarget {
+    serverUrl: string;
+    sessionToken?: string | null;
+    customHeaders?: SyncProxyHeader[];
+    basicAuth?: SyncBasicAuth | null;
+    allowInvalidCertificate?: boolean;
+}
+export interface SyncRemoteRequest {
+    method?: string;
+    body?: unknown;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export interface SyncPushOp {
+    entityType: string;
+    syncId: string;
+    baseRevision: number;
+    op: "upsert" | "delete";
+    row?: SyncRow;
+}
+export type SyncPushResult = {
+    syncId: string;
+    entityType: string;
+    status: "ok";
+    revision: number;
+} | {
+    syncId: string;
+    entityType: string;
+    status: "conflict";
+    revision: number;
+    deleted: boolean;
+    row: SyncRow | null;
+} | {
+    syncId: string;
+    entityType: string;
+    status: "rejected";
+    reason: string;
+};
+export interface SyncRemotePlugin {
+    id: string;
+    name: string;
+    version: string;
+    source: string;
+    artifact: boolean;
+    enabled: boolean;
+    active: boolean;
+    desktop: string;
+    syncEntities: string[];
+    granted: string[];
+}
+/**
+ * What the sync provider gets from core: the replica store, the change feed,
+ * the linked server registry, sessions and a few helpers. Core keeps all of
+ * it neutral; the provider decides when and how to use it. Needs sync:provide.
+ */
+export interface PluginSyncHost {
+    /** True on the desktop app's own backend. */
+    readonly embedded: boolean;
+    info: {
+        appName: () => Promise<string>;
+        version: () => string;
+    };
+    entities: {
+        list: () => SyncEntityInfo[];
+        get: (type: string) => SyncEntityInfo | undefined;
+        /** Registers core's own entities once. */
+        ensureCore: () => Promise<void>;
+        onChanged: (listener: () => void) => () => void;
+        onLocalWrite: (listener: () => void) => () => void;
+    };
+    /** Rows and bookkeeping of one local user's replica. */
+    replica: {
+        resolvers: (userId: string, onMissing?: () => void) => unknown;
+        loadRows: (type: string, userId: string, resolvers: unknown) => Promise<{
+            rows: Map<string, SyncWireRow>;
+            failed: Set<string>;
+        }>;
+        loadRow: (type: string, userId: string, syncId: string, resolvers: unknown) => Promise<SyncWireRow | null>;
+        writeRow: (type: string, userId: string, wire: SyncRow, resolvers: unknown) => Promise<void>;
+        deleteRow: (type: string, userId: string, syncId: string) => Promise<void>;
+        orderSelfReferences: (type: string, rows: SyncRow[]) => SyncRow[];
+        counts: (userId: string) => Promise<Record<string, number>>;
+        wipe: (userId: string) => Promise<void>;
+        regenerateSyncIds: (userId: string) => Promise<void>;
+        removeSharedCopies: (userId: string) => Promise<void>;
+        records: {
+            list: (userId: string) => Promise<Map<string, SyncRecordInfo>>;
+            put: (userId: string, type: string, syncId: string, values: {
+                revision: number;
+                hash: string | null;
+                deleted: boolean;
+            }) => Promise<void>;
+            setError: (userId: string, type: string, syncId: string, reason: string, hash: string) => Promise<void>;
+            clearErrors: (userId: string) => Promise<void>;
+            listErrors: (userId: string) => Promise<SyncRecordInfo[]>;
+            deleteForUser: (userId: string) => Promise<void>;
+            key: (type: string, syncId: string) => string;
+        };
+        conflicts: {
+            save: (userId: string, type: string, syncId: string, row: SyncRow, revision: number) => Promise<void>;
+            list: (userId: string) => Promise<SyncConflictInfo[]>;
+            get: (userId: string, id: number) => Promise<SyncConflictInfo | null>;
+            delete: (userId: string, id: number) => Promise<void>;
+        };
+    };
+    /** The server side: what changed for an account and what a desktop pushed. */
+    feed: {
+        withUserLock: <T>(userId: string, run: () => Promise<T>) => Promise<T>;
+        changes: (userId: string, cursor: number, limit: number, types?: string[]) => Promise<{
+            records: Array<{
+                seq: number;
+                entityType: string;
+                syncId: string;
+                revision: number;
+                deleted: boolean;
+                row: SyncRow | null;
+            }>;
+            hasMore: boolean;
+            nextCursor: number;
+            entityTypes: Array<{
+                type: string;
+                owner: string;
+                order: number;
+                readOnly: boolean;
+            }>;
+        }>;
+        parsePushOps: (body: unknown) => Promise<SyncPushOp[] | null>;
+        applyPush: (userId: string, ops: SyncPushOp[]) => Promise<SyncPushResult[]>;
+        /** Streams a change notice to the account's open event streams. */
+        listen: (userId: string, res: unknown) => Promise<() => void>;
+    };
+    /**
+     * The linked server registry, kept in core so it is there before plugins.
+     * One link per local user. Without a user, the active account is meant.
+     */
+    links: {
+        list: () => Promise<SyncLinkInfo[]>;
+        get: (userId?: string) => Promise<SyncLinkInfo | null>;
+        create: (link: SyncLinkCreate) => Promise<SyncLinkInfo>;
+        update: (patch: SyncLinkPatch, userId?: string) => Promise<SyncLinkInfo | null>;
+        remove: (userId?: string) => Promise<void>;
+    };
+    /** Desktop accounts: the local user and the replica user of each server. */
+    accounts: {
+        list: () => Promise<SyncAccountInfo[]>;
+        /** A new empty account, ready to be linked to a server. */
+        create: () => Promise<string>;
+        /** Which account the app signs in as from now on. */
+        setActive: (userId: string) => Promise<void>;
+        activeId: () => Promise<string | null>;
+        /** Deletes an account and all its data. The last one cannot go. */
+        remove: (userId: string) => Promise<void>;
+    };
+    http: {
+        json: <T>(target: SyncRemoteTarget, pathname: string, request?: SyncRemoteRequest) => Promise<T>;
+        fetch: (target: SyncRemoteTarget, pathname: string, request?: SyncRemoteRequest) => Promise<{
+            ok: boolean;
+            status: number;
+            body: AsyncIterable<Uint8Array> | null;
+        }>;
+        normalizeServerUrl: (input: string) => string | null;
+        isRemoteError: (error: unknown) => error is SyncRemoteError;
+    };
+    sessions: {
+        /** A long lived session for a linked desktop. Shows in the account's sessions. */
+        issueDesktop: (userId: string, options: {
+            days: number;
+            deviceInfo: string;
+        }) => Promise<string>;
+        revoke: (sessionId: string) => Promise<void>;
+        find: (sessionId: string) => Promise<{
+            expiresAt: string;
+            deviceInfo: string | null;
+        } | null>;
+        findUser: (userId: string) => Promise<{
+            id: string;
+            username: string;
+        } | null>;
+        /** The user and session behind a token, or null when it is not valid. */
+        verify: (token: string) => Promise<{
+            userId: string;
+            sessionId?: string;
+        } | null>;
+        /** Sets the sign in cookie on a response, like a login does. A name sets another cookie. */
+        setCookie: (req: unknown, res: unknown, value: string, options?: {
+            name?: string;
+            days?: number;
+        }) => void;
+        /** Removes the sign in cookie, without ending the session behind it. */
+        clearCookie: (req: unknown, res: unknown, name?: string) => void;
+        /** Express middleware that signs the request in and sets userId and sessionId. */
+        middleware: () => unknown;
+        /** Express middleware that lets a request through only on a desktop. */
+        desktopOnly: () => unknown;
+    };
+    hosts: {
+        findForSync: (userId: string, syncId: string) => Promise<{
+            id: number;
+            name: string | null;
+        } | null>;
+        statusBySyncId: (userId: string) => Promise<Record<string, unknown>>;
+    };
+    plugins: {
+        listForDesktop: () => Promise<{
+            plugins: SyncRemotePlugin[];
+            registryKeys: unknown;
+        }>;
+        /** Sends a plugin archive; false when there is no such plugin to share. */
+        sendPackage: (pluginId: string, res: unknown) => Promise<boolean>;
+        mirror: (link: SyncLinkInfo) => Promise<void>;
+        lastRemote: () => SyncRemotePlugin[];
+        localNames: () => Map<string, string>;
+    };
+    desktop: {
+        /** Tells the app's main process how to reach the linked origin. */
+        applyProxy: (link: SyncLinkInfo | null) => Promise<void>;
+        deviceName: () => string;
+    };
+    alerts: {
+        send: (alert: {
+            title: string;
+            body: string;
+            severity: "info" | "warning" | "error";
+            category: string;
+            dedupeKey: string;
+            link?: {
+                tab: string;
+            };
+        }) => Promise<void>;
+    };
 }
 /**
  * A plain key/value hand-off between plugins. `provide` and `revoke` only take
@@ -798,6 +1138,17 @@ export interface PluginHosts {
     activity: PluginHostActivityApi;
     /** Read only hosts this plugin manages. */
     locks: PluginHostLocksApi;
+    /** Folder rows for the acting user. Needs hosts:write. */
+    folders: PluginHostFoldersApi;
+}
+export interface PluginHostFoldersApi {
+    /** Creates the folder row if missing and sets its color and icon. */
+    ensure: (name: string, style?: {
+        color?: string | null;
+        icon?: string | null;
+    }) => Promise<void>;
+    /** Removes the folder row and subfolders once no host is left in them. */
+    removeEmpty: (name: string) => Promise<boolean>;
 }
 export interface PluginHostImportOptions {
     /** Update a host that matches on ip, port and username instead of skipping it. */
@@ -1136,7 +1487,26 @@ export interface PluginNetwork {
         timeoutMs?: number;
     }) => Promise<boolean>;
 }
+/**
+ * A way to reach some hosts other than a plain TCP connection. `claims` is
+ * asked for every connection, so it must be quick. `open` returns a stream
+ * the SSH client runs over, like a relayed socket.
+ */
+export interface PluginSshTransportProvider {
+    claims: (hostId: number) => boolean;
+    open: (host: {
+        id: number;
+        ip: string;
+        port: number;
+    }) => Promise<import("node:stream").Duplex>;
+}
+export interface PluginSshTransports {
+    /** Needs ssh:transport. Removed on deactivate. */
+    provide: (provider: PluginSshTransportProvider) => () => void;
+}
 export interface PluginSsh {
+    /** Other ways to reach hosts, used by every connection to them. */
+    transports: PluginSshTransports;
     /**
      * 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

package/dist/capabilities.js

@@ -34,6 +34,8 @@ export const CAPABILITY_CATALOG = [
     entry("db:core-refs", "high"),
     entry("auth:provide", "high"),
     entry("auth:policy", "high"),
+    entry("sync:provide", "high"),
+    entry("ssh:transport", "high"),
     entry("device:serial", "high"),
     entry("notify:hub", "high"),
     entry("ui:layout", "high"),