Termix/packages/plugin-sdk/FINISH-LIST.md

Finish list

Everything a Phase B/C step left for D0 is done. What is left needs a person with a real install, a real device or a repo outside this one.

Manual checks after 2.9.0

• SSH terminal: password auth, key auth (and an encrypted key's passphrase prompt), TOTP keyboard-interactive, a jump host, Warpgate, split view, snippets sent to a terminal, reconnect after a network drop and after a page reload (session reattach), and the local terminal in the desktop app.

• Serial: the Electron backend path against a real device path/COM port, and the Web Serial browser picker in Chrome or Edge.

• Session sharing: a link share (read-only and read-write) opened in a private window, a user share joined from Active Connections, revoke and "end for everyone", and a collab room with two members, control hand-off, a guest link, rotate and end.

• Session recording: an SSH session recorded end to end (playback matches what happened, including a resize mid-session), a host with recording switched off records nothing, retention prunes an old recording on schedule, a guacd RDP/VNC/Telnet recording still gets a row and plays back, and deleting a user anonymizes their recordings instead of removing them.

• Host status and metrics: on a 2.8 database, hosts whose status checks were off stay off and a custom interval survives; the host list dot goes reachable, then online once the Host Metrics tab or a terminal logs in; an RDP-only host on a custom port shows online; the metrics tab, the dashboard host bars, the homepage host status widget, the metrics chart widget, the terminal toolbar bars and the file manager's disk bar; a manager card (services, packages) and a health check; TOTP on the metrics connect; the admin metrics interval, history retention and new-host default; the temperature unit; disabling host metrics leaves every other plugin's SSH working, then enabling it again.

• Remote desktop: an RDP, a VNC and a Telnet host; a host behind one jump host (tunnels plugin on and off) and behind a chain of two; macOS Screen Sharing over VNC with no username; RDP recording (and none with session-recording off or the host's switch off); file transfer through the RDP drive, drag and drop included; clipboard both ways; sharing an RDP session by link (read-only and read-write) and presenting it in a collab room; opening Windows Remote Desktop from the desktop app on Windows; changing the guacd URL in admin settings without a restart; turning Remote Desktop off in admin (actions disappear, connects answer 403); a 2.8 host that only had connection_type = rdp comes up as RDP with SSH off; RDP user defaults apply to a saved host; Quick Connect over RDP and VNC; the desktop app with a host on the remote server and one on This device.

• Docker: a 2.8 host with Docker on (and one on Podman) keeps its switch and runtime; list, start, stop, logs, stats and the console on a Linux host; TOTP (including a wrong code first) and Warpgate on the connect; a host with no stored password asks for credentials; the homepage Docker widget; an automation Docker step and a docker_event trigger; disable Docker with a console open, then enable it and open another.

• Automations: on a 2.8 database the automations, their run history and their channel links are there; a schedule fires; a webhook fires on both /plugin-api/automations/webhook/<token> and the old /automations/webhook/<token>; a metric threshold on a host nobody has open still fires (headless viewers); a docker_event trigger and a Docker step; a notify step to webhook, ntfy and Discord channels, and to a LAN ntfy with the private opt-in plus the admin allowlist; disable Docker and the automation shows "Needs docker", its scheduled runs are recorded as skipped and the others keep running, then enable it again; the AI assistant lists and creates automations, and says they are unavailable with automations off.

• Homepage: on a 2.8 database every widget, its layout and every service link are there; add, move, resize, edit and delete a widget of each type; the favicon, RSS, ping and custom API widgets against a real remote URL, and each refuses a private/loopback target; the dashboard's Service Links and Homepage Preview cards; the Dashboard/Homepage toggle and its copy-link and open-full-view buttons; ?view=homepage; docker's, tunnels' and file-manager's own homepage widgets still work with the homepage plugin disabled; the AI assistant lists homepage items and says unavailable with homepage off; disable homepage in admin (the tab, its dashboard cards and the toggle disappear) then enable it again.

• TOTP and passkeys: on a 2.8 database a TOTP user is still asked for a code (and a backup code works once); set up TOTP from Settings > Security, add a second device, regenerate backup codes, disable it; enabling signs out other sessions; "remember me" skips it next time; disable the totp plugin and a TOTP user's login is refused until an admin resets their factors; register a passkey, sign in with it with and without a PIN (no PIN still asks for TOTP), delete it; existing 2.8 passkeys still sign in.

• SSO and LDAP: on a 2.8 database every SSO provider and LDAP directory is there, in Settings > Plugins > Single sign-on and > LDAP; an existing provider still signs in through its identity provider without changing anything there (its redirect URI shows /users/oidc/callback); add the new redirect URI at the provider, switch it over and sign in again; a new provider, GitHub and Google; an existing SSO user and an existing LDAP user land in their old accounts; the env-configured provider; admin group and role map; back-channel logout from Keycloak ends the session; the desktop app's system browser login and Termix-Mobile's login; silent sign-in; a second factor after an external login with the admin setting on and off; disable each plugin and its buttons go away and its URLs stop signing anyone in, then enable it again.

• OPKSSH and Warpgate: on a 2.8 Docker install with OPKSSH set up, the config shows up under the plugin, the admin page shows the old redirect URI and a terminal sign-in to an OPKSSH host works through the provider chooser without touching the identity provider; switch to the new URI, register it and sign in again; a second connect within 24 hours skips the browser; an offline Docker install uses the baked binary; disable the opkssh plugin and the host says it needs it. A Warpgate host's toggle is on in the host editor's Plugins group after the upgrade, and the terminal, file manager and docker each show the sign-in dialog and connect after it.

• Vault: on a 2.8 database every Vault profile is there and each Vault host still has its profile selected in the host editor; the admin page shows the old redirect URI; a terminal connect opens Vault's sign-in, signs a certificate and connects, and a second connect skips the browser until the certificate expires; create, edit, share and delete a profile from the host editor (sharing only offered with "Share Vault profiles"); switch to the new redirect URI after allowing it in the Vault role; disable the vault plugin and a Vault host says it needs it, then enable it again.

• Termix-Mobile: the 2.8 termix-id management routes (/termix-id/me, /termix-id/keys, /termix-id/ca and the rest) now 404, only the /termix-id/u/ resolver redirects. Confirm the mobile app does not call them, and that it still reads a host's metrics settings (statsConfig is put back on the host payload by host-metrics) and the renamed Warpgate fields. Once it reads pluginSettings and GET /host/status, drop host-metrics's hostPayloadLegacy hook.

• Docs site: point these at the plugins: the OPKSSH config path and redirect URI, the step-ca settings, the Vault redirect URI, the Termix ID resolver URL (/plugin-api/termix-identity/u/<handle>, the old one still 308s) and the HTTPS certificate page (docs.termix.site/features/networking/ssl, which still describes certbot and the webroot challenge).

• Run bash scripts/upgrade-check.sh once with Docker running. It upgrades the D4 fixture on real Postgres 16 and MySQL 8. The Postgres half passed against an in-process PGlite server during D4; MySQL has not run yet.

• Host settings round trip: filter the Hosts panel by a plugin feature, bulk enable and disable a plugin on a few hosts, export hosts to JSON and import them on another install (plugin settings come across, secrets do not), the raw SQLite export and import, and remote sync of a host with a Vault profile selected (the profile follows it).

• Desktop app with a remote server: tunnels on a remote host show their status next to local ones, and the terminal toolbar's metrics bars work for a host on the remote server.

• Shared hosts: a remote desktop host shared at "connect" does not show its gateway settings; a shared editor cannot change a Vault host's profile; the host list status dot works for a host someone shared with you.

• The PDF preview in the file manager, in the browser and in the desktop app.

• The tab right-click menu's share entry on a terminal whose toolbar is hidden, and the terminal toolbar's quick links (tmux monitor, docker, tunnels, host metrics) for a host with those plugins on.

• Appearance: switching the interface preset changes the Docker layout and the host metrics column count, a change made in either shows under Appearance with the plugin's name and reverts from there, and a 2.8 user's Docker and host metrics overrides are still applied.

• A new host takes the admin "command history for new hosts" setting (a 2.8 install that had it off in host defaults keeps it off), and the file manager and terminal are on for a new host.

• Settings saves with a bad value are refused with a message: a relative terminal background image path, a step-ca URL that is not https.

• Custom SSL_CERT_PATH and SSL_KEY_PATH in the environment survive a restart and no self-signed certificate is generated over them.

• A LAN ntfy or webhook target in the admin allowlist is reached through the configured outbound proxy.

• An admin enables a plugin that was off since the upgrade: its 2.8 data is copied in without a restart.

• A password user who signs in for the first time after the upgrade keeps their TOTP (the copy runs once their keys unlock).

• D1 changes to check by hand: Quick Connect lists Tailscale next to the core auth types and connects with it, and its "Connect to Files" button comes from the file manager; the admin "manage user" panel's Snippets tab (add, edit, delete a snippet for another user); the dashboard's active tunnel counter and its click; the tab bar's file manager button; the secret reference hint and manager in the host and credential editors; Proxmox guest discovery and import (now its own /plugin-api/proxmox/import route); the Tailscale device list behind an outbound proxy and against a LAN Headscale; dragging a local file into a host in the desktop app (its transfer URL moved off the dead port 30004); a per-user database export and import that carries file manager bookmarks; the Simple preset hiding plugin rail items except Snippets.

• Termix-Mobile: after a redirect login (SSO) with the admin setting "second factor after external login" on, the server answers with the second-factor step (pending cookie and temp_token) instead of a session. The mobile app has to handle that step; that change is in the mobile repo.

• D2 changes to check by hand: a remote desktop session still opens, and a touch mode switch within five minutes reuses its token (after that the app mints a new one); the terminal, file manager and host metrics still connect and sudo still works (they now declare credentials:read); Docker and automations connect with a redacted host handed back to core; Admin > Plugins > Permissions lists a plugin's public routes; a disabled plugin's /plugin-api URL answers 503; a share-link guest who leaves cannot type.

After D3 (needs the repos and keys)

• Run termix-plugin keygen, then pin the public key in TRUSTED_PLUGIN_KEYS (src/backend/plugins/trust.ts) and save it as keys/official.pub in Termix-Registry. Until then the list is empty and TERMIX_REQUIRE_SIGNED_PLUGINS=true blocks every user plugin. Steps are in the Termix-Registry README.
• Create the Termix-Registry and Termix-Plugin-Template repos from the local folders next to this repo, and set TERMIX_PLUGIN_SIGNING_KEY and REGISTRY_TOKEN secrets.
• Publish the SDK (npm run build:sdk && npm publish --workspace @termix/plugin-sdk), then run npm install in Termix-Plugin-Template and commit its package-lock.json; its release workflow uses npm ci.
• Plugins outside this repo cannot use renderWithApp or @termix/plugin-sdk/ui (types and the test host come from core's source). Ship them in the SDK package before community plugins need UI components.
• npm run test:plugins on Windows sometimes fails with "Worker exited unexpectedly" in a random plugin (file-manager once, workspaces once); the same suite passes alone and a rerun of the full run passed. Find out why the vitest fork dies (D0).
• Check by hand: drop a signed .tmxplug into <DATA_DIR>/plugins/ on a real install, with and without TERMIX_REQUIRE_SIGNED_PLUGINS=true.

Left for later

• 3.0.0: drop the migrated 2.8 settings rows (guac_url, step_ca_url, global_metrics_interval and the rest). The upgrade moves leave them in place so a downgrade to 2.8 still works; nothing reads them in 2.9.
• Plugin repo split: knip still reports about 150 unused exports inside plugins (constants exported for readability, tables.ts exports the CLI reads, test-only helpers). Prune them per plugin when it moves to its own repo; core and the SDK are clean.
• Plugin OpenAPI docs: plugins carry @openapi comments but src/backend/utils/swagger.ts only scans core routes, so npm run generate:openapi leaves every /plugin-api/ route out.
• Three backend tests sit next to their source, against the test layout rule: src/backend/hosts/host-session-status.test.ts, jump-host-proxy.test.ts and ssh-keepalive.test.ts. Move them under src/backend/tests/hosts/.
• D2 low findings, not fixed: plugin sockets have no Origin check (a SameSite=lax cookie is not sent on a cross-site WebSocket, so only a sibling subdomain could try); a public :param path matches every HTTP method and would also match a sibling literal route; /plugins/public-manifest shows plugin versions before login; ctx.process.ensureBinary hashes any prebuilt path on disk; credentials.resolveHostProtocol falls back to the SSH password for an RDP login (2.8 behaviour, behind credentials:read); a remote desktop display token can be replayed within its five minute TTL (strict single use would break the touch mode switch and reconnect, which reuse it). Revisit with signing and the install UI in 3.0.0.