@termix-ssh/plugin-sdk 1.0.12 → 1.0.15

package/dist/manifest.js

@@ -22,7 +22,7 @@ export { ENV_NAME_PATTERN, MAX_ENV_DESCRIPTION_LENGTH, pluginDocsPage, pluginDoc
  * "^1.2" needs 1.2 or later). engine.termix is checked against the core
  * version by the server.
  */
-export const PLUGIN_API_VERSION = "1.4.0";
+export const PLUGIN_API_VERSION = "1.7.0";
 /** The API major, the default engine.api for a new plugin. */
 export const SUPPORTED_PLUGIN_API_VERSION = String(semver.major(PLUGIN_API_VERSION));
 /** Whether this build's plugin API satisfies a manifest's engine.api. */
@@ -192,6 +192,11 @@ export const PLUGIN_DESKTOP_MODES = [
     "local",
     "server",
 ];
+export const PLUGIN_RUNTIMES = ["desktop"];
+/** The desktop mode a manifest resolves to. */
+export function resolvePluginDesktopMode(m) {
+    return m.desktop ?? (m.runtime === "desktop" ? "local" : "mirror");
+}
 export const DEFAULT_BACKEND_ENTRY = "dist/backend.js";
 export const DEFAULT_FRONTEND_ENTRY = "dist/frontend.js";
 export const DEFAULT_LOCALES_DIR = "locales";
@@ -227,6 +232,7 @@ const ALLOWED_TOP_LEVEL = new Set([
     "platforms",
     "nativeDependencies",
     "desktop",
+    "runtime",
 ]);
 const ALLOWED_CONTRIBUTES = new Set([
     "tabs",
@@ -365,6 +371,15 @@ export function validateManifest(manifest) {
         !PLUGIN_DESKTOP_MODES.includes(m.desktop)) {
         errors.push(`Field "desktop" must be one of: ${PLUGIN_DESKTOP_MODES.join(", ")}`);
     }
+    if (m.runtime !== undefined &&
+        !PLUGIN_RUNTIMES.includes(m.runtime)) {
+        errors.push(`Field "runtime" must be one of: ${PLUGIN_RUNTIMES.join(", ")}`);
+    }
+    if (m.runtime === "desktop" &&
+        m.desktop !== undefined &&
+        m.desktop !== "local") {
+        errors.push(`A "desktop" runtime plugin must use desktop "local"`);
+    }
     validateDependencyMap(m.dependencies, "dependencies", errors);
     validateDependencyMap(m.optionalDependencies, "optionalDependencies", errors);
     validateProvides(m.provides, errors);

package/dist/ssh-keys.d.ts

@@ -0,0 +1,29 @@
+/**
+ * SSH key helpers for plugins that make, check or deploy keys: generate a key
+ * pair, tell what a key is, derive a public key and check a pair belongs
+ * together. Pure functions over ssh2, which the host supplies. Core keeps its
+ * own copy for the connect pipeline.
+ */
+export type SshKeyKind = "ssh-ed25519" | "ssh-rsa" | "ecdsa-sha2-nistp256";
+export interface GeneratedSshKeyPair {
+    privateKey: string;
+    publicKey: string;
+    keyType: SshKeyKind;
+}
+export interface GenerateSshKeyPairOptions {
+    /** RSA only. 2048 to 8192, default 4096. */
+    bits?: number;
+    passphrase?: string;
+    comment?: string;
+}
+/** Makes a new key pair; the public half is one authorized_keys line. */
+export declare function generateSshKeyPair(type: SshKeyKind, options?: GenerateSshKeyPairOptions): GeneratedSshKeyPair;
+/** The key's algorithm, like "ssh-ed25519", or null when it cannot be read. */
+export declare function detectSshKeyType(key: string, passphrase?: string): string | null;
+/** The authorized_keys line for a private key, or null. */
+export declare function publicKeyFromPrivate(privateKey: string, passphrase?: string): string | null;
+/** Whether a public key line belongs to the private key. */
+export declare function validateSshKeyPair(privateKey: string, publicKey: string, passphrase?: string): {
+    isValid: boolean;
+    error?: string;
+};

package/dist/ssh-keys.js

@@ -0,0 +1,85 @@
+/**
+ * SSH key helpers for plugins that make, check or deploy keys: generate a key
+ * pair, tell what a key is, derive a public key and check a pair belongs
+ * together. Pure functions over ssh2, which the host supplies. Core keeps its
+ * own copy for the connect pipeline.
+ */
+import ssh2 from "ssh2";
+/** Makes a new key pair; the public half is one authorized_keys line. */
+export function generateSshKeyPair(type, options = {}) {
+    const algorithm = type === "ssh-rsa" ? "rsa" : type === "ssh-ed25519" ? "ed25519" : "ecdsa";
+    if (type !== "ssh-rsa" &&
+        type !== "ssh-ed25519" &&
+        type !== "ecdsa-sha2-nistp256") {
+        throw new Error(`Unsupported key type: ${String(type)}`);
+    }
+    const generateOptions = {
+        comment: options.comment ?? "",
+    };
+    if (options.passphrase) {
+        generateOptions.passphrase = options.passphrase;
+        generateOptions.cipher = "aes256-ctr";
+    }
+    if (type === "ssh-rsa") {
+        const bits = options.bits ?? 4096;
+        if (!Number.isInteger(bits) || bits < 2048 || bits > 8192) {
+            throw new Error("RSA keys need 2048 to 8192 bits");
+        }
+        generateOptions.bits = bits;
+    }
+    if (type === "ecdsa-sha2-nistp256")
+        generateOptions.bits = 256;
+    const pair = ssh2.utils.generateKeyPairSync(algorithm, generateOptions);
+    return {
+        privateKey: pair.private,
+        publicKey: pair.public.trim(),
+        keyType: type,
+    };
+}
+function parse(key, passphrase) {
+    const parsed = ssh2.utils.parseKey(key.trim(), passphrase || undefined);
+    const first = Array.isArray(parsed) ? parsed[0] : parsed;
+    if (!first || first instanceof Error) {
+        throw first instanceof Error ? first : new Error("Not a readable SSH key");
+    }
+    return first;
+}
+/** The key's algorithm, like "ssh-ed25519", or null when it cannot be read. */
+export function detectSshKeyType(key, passphrase) {
+    try {
+        return parse(key, passphrase).type;
+    }
+    catch {
+        return null;
+    }
+}
+/** The authorized_keys line for a private key, or null. */
+export function publicKeyFromPrivate(privateKey, passphrase) {
+    try {
+        const parsed = parse(privateKey, passphrase);
+        return `${parsed.type} ${parsed.getPublicSSH().toString("base64")}`;
+    }
+    catch {
+        return null;
+    }
+}
+/** Whether a public key line belongs to the private key. */
+export function validateSshKeyPair(privateKey, publicKey, passphrase) {
+    try {
+        const priv = parse(privateKey, passphrase);
+        const pub = parse(publicKey);
+        const same = priv.getPublicSSH().equals(pub.getPublicSSH());
+        return same
+            ? { isValid: true }
+            : {
+                isValid: false,
+                error: "The public key does not match the private key",
+            };
+    }
+    catch (error) {
+        return {
+            isValid: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}

package/dist/testing.d.ts

@@ -7,7 +7,7 @@
  *
  * The vitest config these run under comes from @termix-ssh/plugin-sdk/vitest-preset.
  */
-import type { PluginContext } from "./backend.js";
+import type { PluginAuditEntry, PluginContext, PluginDesktopLocal } from "./backend.js";
 import type { HostActionContribution, TermixApp } from "./frontend.js";
 import type { PluginManifest } from "./manifest.js";
 import type { PluginTableDefinition } from "./db.js";
@@ -25,7 +25,7 @@ export interface FakeWsRoute {
 import type { PluginLoginMethod, PluginVerifiedIdentity, PluginSecondFactor, PluginSshAuthProvider, PluginSshConnectOptions, PluginSshHost, PluginHostSummary, PluginShareableUser, PluginShareableRole, PluginSshKeyCredential, PluginSshKeyCredentialInput } from "./backend.js";
 import type { SyncEntityRegistration } from "./backend.js";
 import type { PluginDatabase } from "./backend.js";
-import type { PluginExternalClientRequest, PluginProtocolTarget, PluginHostStatusEntry, PluginNotification, PluginNotificationChannel, PluginNotifyHub, PluginFetchInit, PluginBinarySpec, PluginTlsCertificateInfo, PluginTlsStatus, PluginSummary, PluginKeyboardInteractiveHandler, PluginProcessHandle, PluginProcessOptions } from "./backend.js";
+import type { PluginExternalClientRequest, PluginProtocolTarget, PluginHostProbeTarget, PluginHostStatusEntry, PluginActivityProvider, PluginHostLockProvider, PluginAuthPolicyProvider, PluginCredentialSummary, PluginHostShareGrant, PluginHostStatusProvider, PluginNotification, PluginNotificationChannel, PluginNotifyHub, PluginFetchInit, PluginBinarySpec, PluginTlsCertificateInfo, PluginTlsStatus, PluginSummary, PluginKeyboardInteractiveHandler, PluginProcessHandle, PluginProcessOptions } from "./backend.js";
 /** A timer registered through ctx.schedule, run by hand with runScheduled. */
 export interface FakeScheduledJob {
     kind: "every" | "after";
@@ -42,6 +42,8 @@ export interface FakeContextOptions {
     settings?: Record<string, unknown>;
     /** Seed for the core settings ctx.settings.readCore can reach. */
     coreSettings?: Record<string, string>;
+    /** What ctx.files.dataDir() answers. Defaults to /tmp/<pluginId>. */
+    dataDir?: string;
     /** What ctx.ssh.connect and withConnection hand back as the client. */
     sshClient?: unknown;
     /** A real database behind ctx.db, usually createTestDb().database. */
@@ -73,10 +75,22 @@ export interface FakeContextOptions {
     protocolTargets?: Record<string, PluginProtocolTarget>;
     /** What ctx.credentials.listSshKeys answers. */
     sshKeyCredentials?: PluginSshKeyCredential[];
+    /** What ctx.credentials.list answers. */
+    credentialSummaries?: PluginCredentialSummary[];
     /** What ctx.desktop.available() answers. Defaults to false. */
     desktopAvailable?: boolean;
+    /** What ctx.desktop.local is. Calls throw when this is not given. */
+    desktopLocal?: PluginDesktopLocal;
+    /** The stored audit lines ctx.audit.list and exportBatches serve. */
+    auditEntries?: PluginAuditEntry[];
     /** What ctx.hosts.status.get and check answer, by host id. */
     hostStatuses?: Record<number, PluginHostStatusEntry>;
+    /** What ctx.hosts.probeTargets answers. */
+    probeTargets?: PluginHostProbeTarget[];
+    /** Host ids ctx.hosts.sessionActive answers true for. */
+    activeSessions?: number[];
+    /** What ctx.network.tcpProbe and ctx.ssh.probe answer. Defaults to false. */
+    reachable?: (target: string | number, port?: number) => boolean;
     /** The acting user's channels, what ctx.notify.channels answers. */
     notificationChannels?: PluginNotificationChannel[];
     /**
@@ -110,6 +124,11 @@ export interface FakeContextOptions {
     baseUrl?: string;
     /** What ctx.auth.countLinkedUsers answers, by provider. Defaults to 0. */
     linkedUsers?: Record<string, number>;
+    /** Second factors from other plugins that ctx.auth.listSecondFactors adds. */
+    secondFactors?: {
+        id: string;
+        pluginId: string;
+    }[];
     /** Failures before ctx.auth.loginRateLimit locks a key. Defaults to 5. */
     loginAttemptLimit?: number;
     /** What ctx.users.getLocale answers, by user id. A missing user answers null. */
@@ -155,6 +174,8 @@ export interface FakeAuthRegistrations {
         purpose: string;
         ttlSeconds?: number;
     }>;
+    /** Providers passed to ctx.auth.policy.provide that are still registered. */
+    policies: PluginAuthPolicyProvider[];
 }
 export interface FakePluginContext {
     ctx: PluginContext;
@@ -164,6 +185,12 @@ export interface FakePluginContext {
     }) => Promise<Record<string, string>>;
     /** Everything the plugin registered through ctx.disposables. */
     disposals: Array<() => void | Promise<void>>;
+    /** Providers registered through ctx.hosts.status.provide. */
+    hostStatusProviders: PluginHostStatusProvider[];
+    /** Every provider passed to ctx.hosts.activity.provide that is still registered. */
+    activityProviders: PluginActivityProvider[];
+    /** Every provider passed to ctx.hosts.locks.provide that is still registered. */
+    hostLockProviders: PluginHostLockProvider[];
     /** Topics emitted through ctx.events.emit, in order. */
     emitted: Array<{
         topic: string;
@@ -199,6 +226,11 @@ export interface FakePluginContext {
         permissionLevel: string;
         durationHours?: number;
     }>;
+    /** Every ctx.hosts.setShares call, in order. */
+    hostShareSets: Array<{
+        hostId: number;
+        grants: PluginHostShareGrant[];
+    }>;
     /** Everything registered through ctx.auth. */
     auth: FakeAuthRegistrations;
     /** Every ctx.desktop.openIsolatedWindow call, in order. */
@@ -255,6 +287,8 @@ export interface FakePluginContext {
         challenges: Map<string, string>;
         renewers: number;
     };
+    /** Calls every ctx.audit.subscribe handler, like a line core just accepted. */
+    emitAudit: (entry: PluginAuditEntry) => void;
     /** Every ctx.audit.record entry, in order. */
     audits: Array<{
         action: string;
@@ -321,6 +355,8 @@ export interface MockContextOptions {
     settings?: Record<string, unknown>;
     /** Seed for the core settings readCore can reach. */
     coreSettings?: Record<string, string>;
+    /** What ctx.files.dataDir() answers. */
+    dataDir?: string;
     /** Acting user returned by currentActor and used by asUser. */
     actor?: string;
     /** What ctx.ssh.connect and withConnection hand back as the client. */
@@ -344,10 +380,22 @@ export interface MockContextOptions {
     protocolTargets?: Record<string, PluginProtocolTarget>;
     /** What ctx.credentials.listSshKeys serves. */
     sshKeyCredentials?: PluginSshKeyCredential[];
+    /** What ctx.credentials.list serves. */
+    credentialSummaries?: PluginCredentialSummary[];
     /** What ctx.desktop.available() answers. */
     desktopAvailable?: boolean;
+    /** What ctx.desktop.local is. See FakeContextOptions. */
+    desktopLocal?: PluginDesktopLocal;
+    /** See FakeContextOptions. */
+    auditEntries?: PluginAuditEntry[];
     /** What ctx.hosts.status answers. See FakeContextOptions. */
     hostStatuses?: Record<number, PluginHostStatusEntry>;
+    /** What ctx.hosts.probeTargets answers. */
+    probeTargets?: PluginHostProbeTarget[];
+    /** Host ids ctx.hosts.sessionActive answers true for. */
+    activeSessions?: number[];
+    /** What ctx.network.tcpProbe and ctx.ssh.probe answer. */
+    reachable?: (target: string | number, port?: number) => boolean;
     /** The acting user's channels, what ctx.notify.channels answers. */
     notificationChannels?: PluginNotificationChannel[];
     /**
@@ -372,25 +420,14 @@ export interface MockContextOptions {
     /** See FakeContextOptions. */
     loginAttemptLimit?: number;
     /** See FakeContextOptions. */
+    secondFactors?: FakeContextOptions["secondFactors"];
+    /** See FakeContextOptions. */
     locales?: Record<string, string>;
 }
 export interface MockPluginContext extends FakePluginContext {
     /** Capability ids checked during the test, in order, denied ones included. */
     checked: string[];
 }
-/**
- * A context double that gates on capabilities the way src/backend/plugins/ctx.ts
- * does, so a test can prove a plugin fails closed without a running server.
- *
- * The gates on today's ctx surface: kv:own on every ctx.kv call, db:own on
- * ctx.db, network:serve on ctx.http and ctx.ws, events:core on emitting a
- * topic outside the plugin's own namespace, settings:read-core on
- * ctx.settings.readCore, ssh:connect plus credentials:use on ctx.ssh,
- * notify:send on ctx.notify (notify:hub on serve), network:outbound on ctx.fetch, process:spawn on
- * ctx.process, system:tls on ctx.system, plugins:read on ctx.plugins, auth:provide on ctx.auth
- * (users:impersonate on issueUserToken), and users:read on ctx.users. Reading a plugin's own settings is deliberately
- * ungated. As the SDK grows a member, add its gate here in the same shape.
- */
 export declare function createMockCtx(options?: MockContextOptions): MockPluginContext;
 /** A sqlite handle as createTestDb exposes it. Structural, like better-sqlite3's. */
 export interface TestSqlite {