@termix-ssh/plugin-sdk 1.0.12 → 1.0.13

package/dist/backend.d.ts

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

package/dist/capabilities.js

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

package/dist/db.js

@@ -160,6 +160,7 @@ export const LEGACY_TABLE_OWNERS = {
     homepage_items: "homepage",
     homepage_layouts: "homepage",
     dashboard_service_links: "homepage",
+    recent_activity: "homepage",
     secret_sources: "secret-sources",
     opkssh_tokens: "opkssh",
     vault_profiles: "vault",