@termix-ssh/plugin-sdk 1.0.10 → 1.0.12

package/dist/host/{use-permissions-2P2TP6GY.js → use-permissions-6VSHHUMB.js}

@@ -7,8 +7,8 @@ import {
   resetPermissionsCache,
   setPermissionsForTesting,
   usePermissions
-} from "./chunk-DIOJ3KW2.js";
-import "./chunk-YC2MAKSP.js";
+} from "./chunk-VEWOYAMZ.js";
+import "./chunk-YGYBM7SQ.js";
 export {
   hasPermission,
   loadPermissionChecker,

package/dist/manifest.d.ts

@@ -10,6 +10,7 @@
  * made a manifest look like it declared something it did not.
  */
 import { type PluginEnvVar } from "./docs.js";
+export { validateThemeCss } from "./theme-css.js";
 export { ENV_NAME_PATTERN, MAX_ENV_DESCRIPTION_LENGTH, pluginDocsPage, pluginDocsUrl, pluginEnvVars, type PluginEnvVar, } from "./docs.js";
 /**
  * The plugin API this build implements. A minor bump adds to the API and
@@ -19,7 +20,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 declare const PLUGIN_API_VERSION = "1.2.0";
+export declare const PLUGIN_API_VERSION = "1.4.0";
 /** The API major, the default engine.api for a new plugin. */
 export declare const SUPPORTED_PLUGIN_API_VERSION: string;
 /** Whether this build's plugin API satisfies a manifest's engine.api. */
@@ -265,6 +266,41 @@ export interface PluginAuthContribution {
     /** Keyboard-interactive handler ids, e.g. "warpgate". */
     keyboardInteractive?: string[];
 }
+/** A layout id or theme id: short, lowercase, used as a CSS class for themes. */
+export declare const LOOK_ID_PATTERN: RegExp;
+/**
+ * A whole-app layout the frontend registers with app.registerLayout. Needs
+ * the ui:layout capability. Declared here so core can list and choose it
+ * before any plugin code runs.
+ */
+export interface PluginLayoutContribution {
+    id: string;
+    /** i18n key in the plugin's namespace, or plain text. */
+    label: string;
+    description?: string;
+    /** Theme picked with this layout when nobody chose one. */
+    defaultTheme?: string;
+    /** The layout a default-look plugin starts with. */
+    default?: boolean;
+}
+/**
+ * A theme: one CSS file of token rules scoped under `.<id>`, applied as a
+ * class on <html>. Needs the ui:theme capability. No code runs for a theme.
+ */
+export interface PluginThemeContribution {
+    id: string;
+    /** i18n key in the plugin's namespace, or plain text. */
+    label: string;
+    mode: "light" | "dark";
+    /** Path of the CSS file inside the plugin. */
+    css: string;
+    /** Colors the theme picker previews it with. */
+    swatch?: {
+        background: string;
+        panel: string;
+        text: string;
+    };
+}
 export interface PluginContributions {
     tabs?: PluginTabContribution[];
     panels?: PluginViewContribution[];
@@ -323,6 +359,10 @@ export interface PluginContributions {
      * ctx.credentials.resolveHostProtocol.
      */
     protocols?: PluginProtocolContribution[];
+    /** Whole-app layouts. Needs the ui:layout capability. */
+    layouts?: PluginLayoutContribution[];
+    /** Themes. Needs the ui:theme capability. */
+    themes?: PluginThemeContribution[];
 }
 /** A field a protocol login carries besides username and password. */
 export interface PluginProtocolCredentialField {

package/dist/manifest.js

@@ -12,6 +12,7 @@
 import semver from "semver";
 import { isKnownCapability } from "./capabilities.js";
 import { ENV_NAME_PATTERN, MAX_ENV_DESCRIPTION_LENGTH, pluginDocsUrl, } from "./docs.js";
+export { validateThemeCss } from "./theme-css.js";
 export { ENV_NAME_PATTERN, MAX_ENV_DESCRIPTION_LENGTH, pluginDocsPage, pluginDocsUrl, pluginEnvVars, } from "./docs.js";
 /**
  * The plugin API this build implements. A minor bump adds to the API and
@@ -21,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.2.0";
+export const PLUGIN_API_VERSION = "1.4.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. */
@@ -168,6 +169,8 @@ export const SETTINGS_FIELD_TYPES = [
     "custom",
 ];
 export const SETTINGS_SCOPES = ["admin", "user", "host"];
+/** A layout id or theme id: short, lowercase, used as a CSS class for themes. */
+export const LOOK_ID_PATTERN = /^[a-z][a-z0-9-]{1,39}$/;
 /** Protocol ids core keeps for itself. */
 export const RESERVED_PROTOCOL_IDS = ["ssh"];
 /** Login keys a declared credential field may not reuse. */
@@ -243,6 +246,8 @@ const ALLOWED_CONTRIBUTES = new Set([
     "uses",
     "keybindingActions",
     "protocols",
+    "layouts",
+    "themes",
 ]);
 const ALLOWED_SETTINGS_FIELD = [
     "key",
@@ -734,6 +739,81 @@ function validateContributes(contributes, pluginId, errors) {
     validateUiPresets(contributes.uiPresets, errors);
     validateKeybindingActions(contributes.keybindingActions, errors);
     validateProtocols(contributes.protocols, errors);
+    validateLayouts(contributes.layouts, errors);
+    validateThemes(contributes.themes, errors);
+}
+/** An array of objects with unique look ids; calls `each` for every valid entry. */
+function validateLookList(value, field, allowed, errors, each) {
+    if (value === undefined)
+        return;
+    if (!Array.isArray(value)) {
+        errors.push(`Field "contributes.${field}" must be an array`);
+        return;
+    }
+    const seen = new Set();
+    value.forEach((raw, index) => {
+        const where = `contributes.${field}[${index}]`;
+        if (!isPlainObject(raw)) {
+            errors.push(`${where} must be an object`);
+            return;
+        }
+        rejectUnknown(raw, allowed, where, errors);
+        if (typeof raw.id !== "string" || !LOOK_ID_PATTERN.test(raw.id)) {
+            errors.push(`${where}.id must match ${LOOK_ID_PATTERN} (lowercase letters, digits, dashes)`);
+        }
+        else {
+            if (seen.has(raw.id))
+                errors.push(`${where}.id duplicates "${raw.id}"`);
+            seen.add(raw.id);
+        }
+        requireString(raw.label, `${where}.label`, errors);
+        each(raw, where);
+    });
+}
+function validateLayouts(value, errors) {
+    validateLookList(value, "layouts", ["id", "label", "description", "defaultTheme", "default"], errors, (raw, where) => {
+        if (raw.description !== undefined)
+            requireString(raw.description, `${where}.description`, errors);
+        if (raw.defaultTheme !== undefined &&
+            (typeof raw.defaultTheme !== "string" ||
+                !LOOK_ID_PATTERN.test(raw.defaultTheme))) {
+            errors.push(`${where}.defaultTheme must be a theme id`);
+        }
+        if (raw.default !== undefined && typeof raw.default !== "boolean") {
+            errors.push(`${where}.default must be a boolean`);
+        }
+    });
+    if (Array.isArray(value) &&
+        value.filter((raw) => isPlainObject(raw) && raw.default === true).length > 1) {
+        errors.push('Only one entry in "contributes.layouts" may set default');
+    }
+}
+const HEX_COLOR = /^#[0-9a-fA-F]{3,8}$/;
+function validateThemes(value, errors) {
+    validateLookList(value, "themes", ["id", "label", "mode", "css", "swatch"], errors, (raw, where) => {
+        if (raw.mode !== "light" && raw.mode !== "dark") {
+            errors.push(`${where}.mode must be "light" or "dark"`);
+        }
+        if (requireString(raw.css, `${where}.css`, errors)) {
+            requireRelativePath(raw.css, `${where}.css`, errors);
+            if (!raw.css.endsWith(".css")) {
+                errors.push(`${where}.css must be a .css file`);
+            }
+        }
+        if (raw.swatch !== undefined) {
+            if (!isPlainObject(raw.swatch)) {
+                errors.push(`${where}.swatch must be an object`);
+                return;
+            }
+            rejectUnknown(raw.swatch, ["background", "panel", "text"], `${where}.swatch`, errors);
+            for (const key of ["background", "panel", "text"]) {
+                const color = raw.swatch[key];
+                if (typeof color !== "string" || !HEX_COLOR.test(color)) {
+                    errors.push(`${where}.swatch.${key} must be a hex color`);
+                }
+            }
+        }
+    });
 }
 export const PROTOCOL_ID_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;
 export const PROTOCOL_FIELD_KEY_PATTERN = /^[a-zA-Z][a-zA-Z0-9]{0,31}$/;
@@ -1595,6 +1675,14 @@ export function parseManifest(raw) {
     if (contributesAuth && !manifest.capabilities.includes("auth:provide")) {
         errors.push('contributes.auth needs the "auth:provide" capability in the capabilities array');
     }
+    if ((manifest.contributes?.layouts?.length ?? 0) > 0 &&
+        !manifest.capabilities.includes("ui:layout")) {
+        errors.push('contributes.layouts needs the "ui:layout" capability in the capabilities array');
+    }
+    if ((manifest.contributes?.themes?.length ?? 0) > 0 &&
+        !manifest.capabilities.includes("ui:theme")) {
+        errors.push('contributes.themes needs the "ui:theme" capability in the capabilities array');
+    }
     for (const secret of manifest.requiresSecret ?? []) {
         if (secret.plugin === manifest.id) {
             errors.push(`requiresSecret["${secret.key}"] points at this plugin; use ctx.secrets.get instead`);

package/dist/testing/setup.js

@@ -89,6 +89,7 @@ globalThis.__termixTestPluginHost = {
     useHostStatus: () => null,
     useCurrentUser: () => null,
     useTheme: () => ({ theme: "dark" }),
+    useShell: () => null,
     toast: { success: noop, error: noop, info: noop, warning: noop },
     getApi: () => ({
         get: offline,

package/dist/testing.d.ts

@@ -112,6 +112,8 @@ export interface FakeContextOptions {
     linkedUsers?: Record<string, number>;
     /** 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. */
+    locales?: Record<string, string>;
 }
 export interface FakeProcessOptions {
     run?: (file: string, args: readonly string[], options?: PluginProcessOptions) => PluginProcessHandle | Promise<PluginProcessHandle>;
@@ -147,6 +149,12 @@ export interface FakeAuthRegistrations {
     }>;
     /** Failures recorded through ctx.auth.loginRateLimit, by "<ip>|<key>". */
     loginFailures: Map<string, number>;
+    /** Every ctx.auth.issueUserToken call, in order. */
+    userTokens: Array<{
+        userId: string;
+        purpose: string;
+        ttlSeconds?: number;
+    }>;
 }
 export interface FakePluginContext {
     ctx: PluginContext;
@@ -363,6 +371,8 @@ export interface MockContextOptions {
     linkedUsers?: Record<string, number>;
     /** See FakeContextOptions. */
     loginAttemptLimit?: number;
+    /** See FakeContextOptions. */
+    locales?: Record<string, string>;
 }
 export interface MockPluginContext extends FakePluginContext {
     /** Capability ids checked during the test, in order, denied ones included. */
@@ -377,7 +387,8 @@ export interface MockPluginContext extends FakePluginContext {
  * 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, and auth:provide on ctx.auth. Reading a plugin's own settings is deliberately
+ * 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;

package/dist/testing.js

@@ -194,6 +194,7 @@ export function createFakeContext(options = {}) {
         completedLogins: [],
         revokedSessions: [],
         loginFailures: new Map(),
+        userTokens: [],
     };
     const sshClient = options.sshClient ?? {};
     let actor = options.actor;
@@ -673,6 +674,17 @@ export function createFakeContext(options = {}) {
                 },
             },
             countLinkedUsers: async (provider) => options.linkedUsers?.[provider] ?? 0,
+            issueUserToken: async (userId, tokenOptions) => {
+                auth.userTokens.push({ userId, ...tokenOptions });
+                const ttl = Math.min(tokenOptions.ttlSeconds ?? 300, 900);
+                return {
+                    token: `fake-token-${auth.userTokens.length}`,
+                    expiresAt: new Date(Date.now() + ttl * 1000).toISOString(),
+                };
+            },
+        },
+        users: {
+            getLocale: async (userId) => options.locales?.[userId] ?? null,
         },
         desktop: {
             openIsolatedWindow: async (request) => {
@@ -914,7 +926,8 @@ export function createFakeContext(options = {}) {
  * 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, and auth:provide on ctx.auth. Reading a plugin's own settings is deliberately
+ * 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 function createMockCtx(options = {}) {
@@ -948,6 +961,7 @@ export function createMockCtx(options = {}) {
         baseUrl: options.baseUrl,
         linkedUsers: options.linkedUsers,
         loginAttemptLimit: options.loginAttemptLimit,
+        locales: options.locales,
         manifest: {
             capabilities: options.capabilities ?? [],
             ...options.manifest,
@@ -1218,6 +1232,16 @@ export function createMockCtx(options = {}) {
                 require("auth:provide");
                 return ctx.auth.countLinkedUsers(provider);
             },
+            issueUserToken: async (userId, tokenOptions) => {
+                require("users:impersonate");
+                return ctx.auth.issueUserToken(userId, tokenOptions);
+            },
+        },
+        users: {
+            getLocale: async (userId) => {
+                require("users:read");
+                return ctx.users.getLocale(userId);
+            },
         },
         desktop: {
             openIsolatedWindow: async (request) => {

package/dist/theme-css.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Checks a theme's CSS before core serves it.
+ *
+ * A theme is colors and styles only, so its file may hold nothing but rules
+ * whose every selector starts with the theme's own class (`.nord`,
+ * `:root.nord`, `html.nord ...`), optionally inside @media or @supports.
+ * Anything that could load from elsewhere or run code is refused: @import,
+ * url() to another host, other at-rules, expression() and javascript:.
+ */
+/** Every problem with a theme's CSS, empty when it is safe to serve. */
+export declare function validateThemeCss(css: string, themeId: string): string[];

package/dist/theme-css.js

@@ -0,0 +1,142 @@
+/**
+ * Checks a theme's CSS before core serves it.
+ *
+ * A theme is colors and styles only, so its file may hold nothing but rules
+ * whose every selector starts with the theme's own class (`.nord`,
+ * `:root.nord`, `html.nord ...`), optionally inside @media or @supports.
+ * Anything that could load from elsewhere or run code is refused: @import,
+ * url() to another host, other at-rules, expression() and javascript:.
+ */
+const ALLOWED_BLOCK_AT_RULES = new Set(["media", "supports"]);
+function stripComments(css) {
+    return css.replace(/\/\*[\s\S]*?\*\//g, " ");
+}
+/** Splits on commas that are not inside parentheses or brackets. */
+function splitSelectors(prelude) {
+    const parts = [];
+    let depth = 0;
+    let current = "";
+    for (const ch of prelude) {
+        if (ch === "(" || ch === "[")
+            depth += 1;
+        if (ch === ")" || ch === "]")
+            depth -= 1;
+        if (ch === "," && depth === 0) {
+            parts.push(current);
+            current = "";
+            continue;
+        }
+        current += ch;
+    }
+    parts.push(current);
+    return parts.map((part) => part.trim());
+}
+function withoutStrings(css) {
+    return css.replace(/"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'/g, '""');
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** Index of the brace closing the one at `open`, skipping strings. */
+function matchingBrace(css, open) {
+    let depth = 0;
+    let quote = null;
+    for (let i = open; i < css.length; i += 1) {
+        const ch = css[i];
+        if (quote) {
+            if (ch === "\\")
+                i += 1;
+            else if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'")
+            quote = ch;
+        else if (ch === "{")
+            depth += 1;
+        else if (ch === "}") {
+            depth -= 1;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return -1;
+}
+function checkUrls(css, errors) {
+    const urls = css.matchAll(/url\(\s*(['"]?)([^'")]*)\1\s*\)/gi);
+    for (const match of urls) {
+        const target = match[2].trim();
+        if (target.startsWith("data:"))
+            continue;
+        if (/^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith("//")) {
+            errors.push(`url(${target}) points outside the plugin`);
+        }
+    }
+}
+function checkRules(css, scope, themeId, errors) {
+    let index = 0;
+    while (index < css.length) {
+        const rest = css.slice(index);
+        if (rest.trim() === "")
+            return;
+        const open = css.indexOf("{", index);
+        const semicolon = css.indexOf(";", index);
+        if (semicolon !== -1 && (open === -1 || semicolon < open)) {
+            const statement = css.slice(index, semicolon).trim();
+            errors.push(statement.startsWith("@")
+                ? `${statement.split(/\s/)[0]} is not allowed in a theme`
+                : `Unexpected "${statement}" outside a rule`);
+            index = semicolon + 1;
+            continue;
+        }
+        if (open === -1) {
+            errors.push(`Unexpected "${rest.trim()}" at the end`);
+            return;
+        }
+        const close = matchingBrace(css, open);
+        if (close === -1) {
+            errors.push("A rule is missing its closing brace");
+            return;
+        }
+        const prelude = css.slice(index, open).trim();
+        const body = css.slice(open + 1, close);
+        if (prelude.startsWith("@")) {
+            const name = prelude.slice(1).split(/[\s(]/)[0].toLowerCase();
+            if (ALLOWED_BLOCK_AT_RULES.has(name)) {
+                checkRules(body, scope, themeId, errors);
+            }
+            else {
+                errors.push(`@${name} is not allowed in a theme`);
+            }
+        }
+        else {
+            for (const selector of splitSelectors(prelude)) {
+                if (!scope.test(selector)) {
+                    errors.push(`Selector "${selector}" must start with .${themeId}, :root.${themeId} or html.${themeId}`);
+                }
+            }
+            if (withoutStrings(body).includes("{")) {
+                errors.push(`Nested rules are not allowed in "${prelude}"`);
+            }
+        }
+        index = close + 1;
+    }
+}
+/** Every problem with a theme's CSS, empty when it is safe to serve. */
+export function validateThemeCss(css, themeId) {
+    const errors = [];
+    const clean = stripComments(css);
+    if (/@import\b/i.test(clean))
+        errors.push("@import is not allowed in a theme");
+    if (/expression\s*\(/i.test(clean))
+        errors.push("expression() is not allowed in a theme");
+    if (/javascript:/i.test(clean))
+        errors.push("javascript: is not allowed in a theme");
+    if (/-moz-binding|behavior\s*:/i.test(clean))
+        errors.push("Script bindings are not allowed in a theme");
+    checkUrls(clean, errors);
+    const id = escapeRegExp(themeId);
+    const scope = new RegExp(`^(?::root|html)?\\.${id}(?![\\w-])`);
+    checkRules(clean, scope, themeId, errors);
+    return [...new Set(errors)];
+}

package/dist/vitest-preset.d.ts

@@ -27,8 +27,14 @@ export declare function pluginVitestConfig(configUrl: string, options?: PluginVi
         enforce: "pre";
         load(id: string): string;
     }[];
+    server: {
+        fs: {
+            allow: string[];
+        };
+    };
     resolve: {
         alias: Record<string, string>;
+        dedupe: string[];
     };
     test: {
         globals: boolean;
@@ -40,8 +46,14 @@ export declare function pluginVitestConfig(configUrl: string, options?: PluginVi
                 enforce: "pre";
                 load(id: string): string;
             }[];
+            server: {
+                fs: {
+                    allow: string[];
+                };
+            };
             resolve: {
                 alias: Record<string, string>;
+                dedupe: string[];
             };
             test: {
                 name: string;
@@ -59,8 +71,14 @@ export declare function pluginVitestConfig(configUrl: string, options?: PluginVi
                 enforce: "pre";
                 load(id: string): string;
             }[];
+            server: {
+                fs: {
+                    allow: string[];
+                };
+            };
             resolve: {
                 alias: Record<string, string>;
+                dedupe: string[];
             };
             test: {
                 name: string;

package/dist/vitest-preset.js

@@ -80,9 +80,18 @@ export function pluginVitestConfig(configUrl, options = {}) {
     // unexpectedly". Threads don't.
     const pool = "threads";
     const plugins = [wasmBinaryPlugin()];
+    // A local SDK linked into node_modules sits outside the plugin folder, so
+    // Vite must be allowed to read it, and React must come from the plugin.
+    const sdkDir = fs.realpathSync(fileURLToPath(new URL("..", import.meta.url)));
+    const server = { fs: { allow: [pluginDir, sdkDir] } };
+    const resolve = {
+        alias,
+        dedupe: ["react", "react-dom", "react-i18next", "i18next"],
+    };
     return {
         plugins,
-        resolve: { alias },
+        server,
+        resolve,
         test: {
             globals: true,
             setupFiles: [setupFile],
@@ -90,7 +99,8 @@ export function pluginVitestConfig(configUrl, options = {}) {
             projects: [
                 {
                     plugins,
-                    resolve: { alias },
+                    server,
+                    resolve,
                     test: {
                         name: `${pluginId}:backend`,
                         root: pluginDir,
@@ -103,7 +113,8 @@ export function pluginVitestConfig(configUrl, options = {}) {
                 },
                 {
                     plugins,
-                    resolve: { alias },
+                    server,
+                    resolve,
                     test: {
                         name: `${pluginId}:frontend`,
                         root: pluginDir,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@termix-ssh/plugin-sdk",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "description": "The contract between Termix core and a plugin: types, the capability catalog and the manifest schema.",
   "license": "Apache-2.0",
   "repository": {