@fntio/infra-client-plugin-sdk 0.0.0-stage → 0.2.0

package/dist/contracts/paths.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLUGIN_ASSET_ROOT = exports.PLUGIN_API_ROOT = void 0;
+exports.pluginApiBaseUrl = pluginApiBaseUrl;
+exports.pluginAccountRoot = pluginAccountRoot;
+exports.pluginRouteResourcePath = pluginRouteResourcePath;
+exports.pluginAccountPath = pluginAccountPath;
+exports.parsePluginResourcePath = parsePluginResourcePath;
+exports.pluginAssetPrefix = pluginAssetPrefix;
+exports.pluginUiUrl = pluginUiUrl;
+const manifest_1 = require("./manifest");
+exports.PLUGIN_API_ROOT = "/api/plugins";
+exports.PLUGIN_ASSET_ROOT = "/plugin-assets";
+function pluginApiBaseUrl(pluginId) {
+    return `${exports.PLUGIN_API_ROOT}/${pluginId}`;
+}
+/** The gateway resource every route of a plugin hangs off: `/api/plugins/<id>/accounts/{accountNumber}`. */
+function pluginAccountRoot(pluginId) {
+    return `${pluginApiBaseUrl(pluginId)}/accounts/{${manifest_1.PLUGIN_ACCOUNT_PARAM}}`;
+}
+/** The gateway resource path template for one registered route. */
+function pluginRouteResourcePath(pluginId, routePath) {
+    return pluginAccountRoot(pluginId) + (routePath === "/" ? "" : routePath);
+}
+/** The concrete account root a request lands on: the template with the account filled in. */
+function pluginAccountPath(pluginId, accountNumber) {
+    return pluginAccountRoot(pluginId).replace(`{${manifest_1.PLUGIN_ACCOUNT_PARAM}}`, accountNumber);
+}
+/** The inverse of `pluginRouteResourcePath`: the authorizer resolves a gateway resource template
+ *  back to the plugin and route it belongs to. `null` for anything that is not one. */
+function parsePluginResourcePath(resource) {
+    const prefix = `${exports.PLUGIN_API_ROOT}/`;
+    if (!resource.startsWith(prefix))
+        return null;
+    const pluginId = resource.slice(prefix.length).split("/")[0];
+    if (!manifest_1.PLUGIN_ID_PATTERN.test(pluginId))
+        return null;
+    const root = pluginAccountRoot(pluginId);
+    if (resource === root)
+        return { pluginId, routePath: "/" };
+    return resource.startsWith(`${root}/`) ? { pluginId, routePath: resource.slice(root.length) } : null;
+}
+/** Immutable asset prefix: a new hash for changed bytes, even under the same version. */
+function pluginAssetPrefix(pluginId, version, assetHash) {
+    return `${exports.PLUGIN_ASSET_ROOT}/${pluginId}/${version}-${assetHash}`;
+}
+function pluginUiUrl(assetPrefix, entry) {
+    return `${assetPrefix}/${entry}`;
+}

package/dist/contracts/theme.d.ts

@@ -0,0 +1,21 @@
+/** The documented subset of the portal's semantic CSS custom properties handed to plugin frames. */
+export declare const PLUGIN_THEME_TOKENS: readonly ["--background", "--surface", "--surface-foreground", "--muted", "--muted-foreground", "--text-secondary", "--placeholder", "--border", "--border-strong", "--ring", "--card-bg", "--popover-bg", "--state-hover", "--state-selected", "--gray-1", "--gray-2", "--gray-3", "--gray-4", "--gray-5", "--gray-6", "--gray-7", "--gray-8", "--gray-9", "--gray-10", "--gray-11", "--gray-12", "--accent-1", "--accent-2", "--accent-3", "--accent-4", "--accent-5", "--accent-6", "--accent-7", "--accent-8", "--accent-9", "--accent-10", "--accent-11", "--accent-12", "--brand-primary", "--brand-primary-hover", "--brand-foreground", "--brand-text", "--brand-muted-foreground", "--success", "--success-muted", "--warning", "--warning-muted", "--danger", "--danger-hover", "--danger-muted", "--radius", "--radius-md", "--radius-lg", "--radius-xl", "--font-sans", "--font-mono", "--ease-standard", "--ease-emphasized"];
+export type PluginThemeToken = (typeof PLUGIN_THEME_TOKENS)[number];
+export type PluginThemeTokens = Partial<Record<PluginThemeToken, string>>;
+export type PluginAppearance = "light" | "dark";
+export interface PluginBranding {
+    readonly projectName: string;
+    readonly logoUrl?: string;
+}
+export interface PluginTheme {
+    readonly appearance: PluginAppearance;
+    readonly tokens: PluginThemeTokens;
+    readonly branding: PluginBranding;
+}
+export declare function isPluginThemeToken(name: string): name is PluginThemeToken;
+export declare function isPluginTheme(value: unknown): value is PluginTheme;
+/** A token value is a color, length, font stack or easing; anything that could close the rule or
+ *  pull a resource is dropped rather than written into the plugin document. */
+export declare function isSafeCssValue(value: string): boolean;
+/** A stylesheet that applies the host theme to a plugin document. Unknown tokens are ignored. */
+export declare function pluginThemeCss(theme: PluginTheme, selector?: string): string;

package/dist/contracts/theme.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLUGIN_THEME_TOKENS = void 0;
+exports.isPluginThemeToken = isPluginThemeToken;
+exports.isPluginTheme = isPluginTheme;
+exports.isSafeCssValue = isSafeCssValue;
+exports.pluginThemeCss = pluginThemeCss;
+/** The documented subset of the portal's semantic CSS custom properties handed to plugin frames. */
+exports.PLUGIN_THEME_TOKENS = [
+    "--background", "--surface", "--surface-foreground", "--muted", "--muted-foreground",
+    "--text-secondary", "--placeholder", "--border", "--border-strong", "--ring",
+    "--card-bg", "--popover-bg", "--state-hover", "--state-selected",
+    "--gray-1", "--gray-2", "--gray-3", "--gray-4", "--gray-5", "--gray-6",
+    "--gray-7", "--gray-8", "--gray-9", "--gray-10", "--gray-11", "--gray-12",
+    "--accent-1", "--accent-2", "--accent-3", "--accent-4", "--accent-5", "--accent-6",
+    "--accent-7", "--accent-8", "--accent-9", "--accent-10", "--accent-11", "--accent-12",
+    "--brand-primary", "--brand-primary-hover", "--brand-foreground", "--brand-text", "--brand-muted-foreground",
+    "--success", "--success-muted", "--warning", "--warning-muted",
+    "--danger", "--danger-hover", "--danger-muted",
+    "--radius", "--radius-md", "--radius-lg", "--radius-xl",
+    "--font-sans", "--font-mono", "--ease-standard", "--ease-emphasized",
+];
+const TOKEN_SET = new Set(exports.PLUGIN_THEME_TOKENS);
+function isPluginThemeToken(name) {
+    return TOKEN_SET.has(name);
+}
+function isPluginTheme(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const t = value;
+    if (t.appearance !== "light" && t.appearance !== "dark")
+        return false;
+    if (!t.tokens || typeof t.tokens !== "object" || Array.isArray(t.tokens))
+        return false;
+    for (const [k, v] of Object.entries(t.tokens)) {
+        if (!isPluginThemeToken(k) || typeof v !== "string")
+            return false;
+    }
+    const b = t.branding;
+    if (!b || typeof b !== "object" || typeof b.projectName !== "string")
+        return false;
+    if (b.logoUrl !== undefined && typeof b.logoUrl !== "string")
+        return false;
+    return true;
+}
+/** A token value is a color, length, font stack or easing; anything that could close the rule or
+ *  pull a resource is dropped rather than written into the plugin document. */
+function isSafeCssValue(value) {
+    return value.length > 0 && value.length <= 200 && !/[;{}<>]/.test(value) && !/url\s*\(|expression\s*\(|@import/i.test(value);
+}
+/** A stylesheet that applies the host theme to a plugin document. Unknown tokens are ignored. */
+function pluginThemeCss(theme, selector = ":root") {
+    const lines = [`color-scheme: ${theme.appearance};`];
+    for (const name of exports.PLUGIN_THEME_TOKENS) {
+        const value = theme.tokens[name];
+        if (value !== undefined && isSafeCssValue(value))
+            lines.push(`${name}: ${value};`);
+    }
+    return `${selector} {\n  ${lines.join("\n  ")}\n}\n`;
+}

package/dist/contracts/transport.d.ts

@@ -0,0 +1,14 @@
+export interface PluginMessagePort {
+    postMessage(message: unknown, targetOrigin: string): void;
+}
+export interface PluginMessageEventLike {
+    readonly data: unknown;
+    readonly origin: string;
+    readonly source: unknown;
+}
+export type PluginMessageListener = (event: PluginMessageEventLike) => void;
+export interface PluginMessageListenerTarget {
+    addEventListener(type: "message", listener: PluginMessageListener): void;
+    removeEventListener(type: "message", listener: PluginMessageListener): void;
+}
+export declare function newPluginProtocolId(prefix: string): string;

package/dist/contracts/transport.js

@@ -0,0 +1,10 @@
+"use strict";
+// The slice of `Window` the iframe protocol touches, typed structurally so tests and the local
+// development host can supply fakes. A real `Window` satisfies all three.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.newPluginProtocolId = newPluginProtocolId;
+function newPluginProtocolId(prefix) {
+    const c = globalThis.crypto;
+    const id = typeof c?.randomUUID === "function" ? c.randomUUID() : `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`;
+    return `${prefix}-${id}`;
+}

package/dist/contracts/validate.d.ts

@@ -0,0 +1,27 @@
+import { PluginManifestV1 } from "./manifest";
+export type PluginValidationCode = "not-an-object" | "unknown-field" | "schema-version" | "host-api-version" | "plugin-id" | "display-name" | "description" | "version" | "enabled" | "accounts-empty" | "account-number" | "account-duplicate" | "region" | "region-duplicate" | "permissions-empty" | "permission-id" | "permission-duplicate" | "permission-label" | "ui-empty" | "ui-unknown-entry" | "ui-undeclared-permission" | "ui-entry-path" | "ui-label" | "ui-icon" | "ui-order" | "ui-assets-directory" | "ui-entry-missing" | "route-id" | "route-duplicate-id" | "route-method" | "route-path" | "route-greedy" | "route-reserved-param" | "route-param-duplicate" | "route-param-conflict" | "route-duplicate-shape" | "route-undeclared-permission" | "route-handler-key" | "no-surface" | "manifest-too-large";
+export interface PluginValidationIssue {
+    readonly code: PluginValidationCode;
+    /** Dotted location in the manifest, "" for the whole document. */
+    readonly path: string;
+    readonly message: string;
+}
+export type PluginValidationResult = {
+    readonly ok: true;
+    readonly manifest: PluginManifestV1;
+} | {
+    readonly ok: false;
+    readonly issues: readonly PluginValidationIssue[];
+};
+export interface ValidatePluginManifestOptions {
+    /** When given, every route's handlerKey must be one of these. */
+    readonly handlerKeys?: readonly string[];
+}
+export declare class PluginValidationError extends Error {
+    readonly issues: readonly PluginValidationIssue[];
+    constructor(issues: readonly PluginValidationIssue[], subject?: string);
+}
+export declare function assertPluginManifest(input: unknown, options?: ValidatePluginManifestOptions): PluginManifestV1;
+export declare function validatePluginManifest(input: unknown, options?: ValidatePluginManifestOptions): PluginValidationResult;
+/** The file part of an entry ("index.html#/user" → "index.html"). */
+export declare function pluginEntryFile(entry: string): string;

package/dist/contracts/validate.js

@@ -0,0 +1,321 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PluginValidationError = void 0;
+exports.assertPluginManifest = assertPluginManifest;
+exports.validatePluginManifest = validatePluginManifest;
+exports.pluginEntryFile = pluginEntryFile;
+const manifest_1 = require("./manifest");
+class PluginValidationError extends Error {
+    issues;
+    constructor(issues, subject = "Plugin manifest") {
+        super(`${subject} is invalid:\n` +
+            issues.map((i) => `  - ${i.path || "(manifest)"}: ${i.message} [${i.code}]`).join("\n"));
+        this.issues = issues;
+        this.name = "PluginValidationError";
+    }
+}
+exports.PluginValidationError = PluginValidationError;
+function assertPluginManifest(input, options) {
+    const result = validatePluginManifest(input, options);
+    if (!result.ok)
+        throw new PluginValidationError(result.issues);
+    return result.manifest;
+}
+const TOP_LEVEL_KEYS = ["schemaVersion", "id", "displayName", "description", "version", "hostApiVersion", "enabled", "accounts", "permissions", "ui", "routes"];
+const ACCOUNT_KEYS = ["accountNumber", "regions"];
+const PERMISSION_KEYS = ["id", "label", "description"];
+const UI_KEYS = ["user", "admin"];
+const UI_ENTRY_KEYS = ["label", "icon", "order", "entry"];
+const ROUTE_KEYS = ["id", "method", "path", "permission", "handlerKey"];
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const isText = (v, max) => typeof v === "string" && v.trim().length > 0 && v.length <= max;
+function unknownKeys(obj, known, at, code, issue) {
+    for (const key of Object.keys(obj)) {
+        if (!known.includes(key))
+            issue(code, at ? `${at}.${key}` : key, `unknown field "${key}"`);
+    }
+}
+function validatePluginManifest(input, options = {}) {
+    const issues = [];
+    const issue = (code, path, message) => { issues.push({ code, path, message }); };
+    if (!isRecord(input)) {
+        return { ok: false, issues: [{ code: "not-an-object", path: "", message: "manifest must be an object" }] };
+    }
+    const m = input;
+    unknownKeys(m, TOP_LEVEL_KEYS, "", "unknown-field", issue);
+    if (m.schemaVersion !== manifest_1.PLUGIN_MANIFEST_SCHEMA_VERSION)
+        issue("schema-version", "schemaVersion", `must be ${manifest_1.PLUGIN_MANIFEST_SCHEMA_VERSION}`);
+    if (m.hostApiVersion !== manifest_1.PLUGIN_HOST_API_VERSION)
+        issue("host-api-version", "hostApiVersion", `must be ${manifest_1.PLUGIN_HOST_API_VERSION}`);
+    if (typeof m.id !== "string" || !manifest_1.PLUGIN_ID_PATTERN.test(m.id))
+        issue("plugin-id", "id", "lowercase letters, digits and hyphens, starting with a letter, 1-64 characters");
+    if (!isText(m.displayName, manifest_1.PLUGIN_DISPLAY_NAME_MAX))
+        issue("display-name", "displayName", `1-${manifest_1.PLUGIN_DISPLAY_NAME_MAX} characters`);
+    if (m.description !== undefined && (typeof m.description !== "string" || m.description.length > manifest_1.PLUGIN_DESCRIPTION_MAX))
+        issue("description", "description", `a string of at most ${manifest_1.PLUGIN_DESCRIPTION_MAX} characters`);
+    if (typeof m.version !== "string" || !manifest_1.PLUGIN_VERSION_PATTERN.test(m.version))
+        issue("version", "version", "letters, digits, dots, plus and hyphens, 1-64 characters (it becomes part of the asset URL)");
+    if (typeof m.enabled !== "boolean")
+        issue("enabled", "enabled", "must be true or false");
+    validateAccounts(m.accounts, issue);
+    const declared = validatePermissions(m.permissions, issue);
+    const uiEntries = m.ui === undefined ? 0 : validateUi(m.ui, declared, issue);
+    const routeCount = validateRoutes(m.routes, declared, options.handlerKeys, issue);
+    if (uiEntries === 0 && routeCount === 0)
+        issue("no-surface", "", "declare at least one UI entry or one route");
+    if (issues.length === 0) {
+        const bytes = new TextEncoder().encode(JSON.stringify(m)).length;
+        if (bytes > manifest_1.PLUGIN_MANIFEST_MAX_BYTES)
+            issue("manifest-too-large", "", `${bytes} bytes; the limit is ${manifest_1.PLUGIN_MANIFEST_MAX_BYTES}`);
+    }
+    if (issues.length > 0)
+        return { ok: false, issues };
+    return { ok: true, manifest: JSON.parse(JSON.stringify(m)) };
+}
+function validateAccounts(accounts, issue) {
+    if (!Array.isArray(accounts) || accounts.length === 0) {
+        issue("accounts-empty", "accounts", "bind the plugin to at least one AWS account");
+        return;
+    }
+    const seen = new Set();
+    accounts.forEach((a, i) => {
+        const at = `accounts[${i}]`;
+        if (!isRecord(a)) {
+            issue("account-number", at, "must be an object with accountNumber");
+            return;
+        }
+        unknownKeys(a, ACCOUNT_KEYS, at, "unknown-field", issue);
+        if (typeof a.accountNumber !== "string" || !manifest_1.AWS_ACCOUNT_PATTERN.test(a.accountNumber)) {
+            issue("account-number", `${at}.accountNumber`, "must be a 12-digit AWS account id");
+        }
+        else if (seen.has(a.accountNumber)) {
+            issue("account-duplicate", `${at}.accountNumber`, `account ${a.accountNumber} is bound twice`);
+        }
+        else {
+            seen.add(a.accountNumber);
+        }
+        if (a.regions !== undefined) {
+            if (!Array.isArray(a.regions) || a.regions.length === 0) {
+                issue("region", `${at}.regions`, "omit regions or list at least one");
+            }
+            else {
+                const regs = new Set();
+                a.regions.forEach((r, j) => {
+                    if (typeof r !== "string" || !manifest_1.AWS_REGION_PATTERN.test(r))
+                        issue("region", `${at}.regions[${j}]`, `"${String(r)}" is not an AWS region name`);
+                    else if (regs.has(r))
+                        issue("region-duplicate", `${at}.regions[${j}]`, `${r} is listed twice`);
+                    else
+                        regs.add(r);
+                });
+            }
+        }
+    });
+}
+function validatePermissions(permissions, issue) {
+    const declared = [];
+    if (!Array.isArray(permissions) || permissions.length === 0) {
+        issue("permissions-empty", "permissions", `declare "user", "admin", or both`);
+        return declared;
+    }
+    permissions.forEach((p, i) => {
+        const at = `permissions[${i}]`;
+        if (!isRecord(p)) {
+            issue("permission-id", at, "must be an object with id and label");
+            return;
+        }
+        unknownKeys(p, PERMISSION_KEYS, at, "unknown-field", issue);
+        if (typeof p.id !== "string" || !manifest_1.PLUGIN_PERMISSIONS.includes(p.id)) {
+            issue("permission-id", `${at}.id`, `must be "user" or "admin"`);
+        }
+        else if (declared.includes(p.id)) {
+            issue("permission-duplicate", `${at}.id`, `"${p.id}" is declared twice`);
+        }
+        else {
+            declared.push(p.id);
+        }
+        if (!isText(p.label, manifest_1.PLUGIN_DISPLAY_NAME_MAX))
+            issue("permission-label", `${at}.label`, `1-${manifest_1.PLUGIN_DISPLAY_NAME_MAX} characters`);
+        if (p.description !== undefined && (typeof p.description !== "string" || p.description.length > manifest_1.PLUGIN_DESCRIPTION_MAX))
+            issue("description", `${at}.description`, `a string of at most ${manifest_1.PLUGIN_DESCRIPTION_MAX} characters`);
+    });
+    return declared;
+}
+function validateUi(ui, declared, issue) {
+    if (!isRecord(ui)) {
+        issue("ui-unknown-entry", "ui", "must be an object with user and/or admin entries");
+        return 0;
+    }
+    unknownKeys(ui, UI_KEYS, "ui", "ui-unknown-entry", issue);
+    let count = 0;
+    for (const kind of UI_KEYS) {
+        const entry = ui[kind];
+        if (entry === undefined)
+            continue;
+        count++;
+        const at = `ui.${kind}`;
+        if (!isRecord(entry)) {
+            issue("ui-entry-path", at, "must be an object with label and entry");
+            continue;
+        }
+        unknownKeys(entry, UI_ENTRY_KEYS, at, "unknown-field", issue);
+        if (!declared.includes(kind))
+            issue("ui-undeclared-permission", at, `a ${kind} entry needs the "${kind}" permission declared`);
+        if (!isText(entry.label, manifest_1.PLUGIN_DISPLAY_NAME_MAX))
+            issue("ui-label", `${at}.label`, `1-${manifest_1.PLUGIN_DISPLAY_NAME_MAX} characters`);
+        if (entry.icon !== undefined && (typeof entry.icon !== "string" || !manifest_1.PLUGIN_ICON_PATTERN.test(entry.icon)))
+            issue("ui-icon", `${at}.icon`, "a host icon identifier: lowercase letters, digits, hyphens");
+        if (entry.order !== undefined && !Number.isInteger(entry.order))
+            issue("ui-order", `${at}.order`, "must be an integer");
+        validateEntryPath(entry.entry, `${at}.entry`, issue);
+    }
+    if (count === 0)
+        issue("ui-empty", "ui", "omit ui or give it a user and/or admin entry");
+    return count;
+}
+/** The file part of an entry ("index.html#/user" → "index.html"). */
+function pluginEntryFile(entry) {
+    const hash = entry.indexOf("#");
+    return hash === -1 ? entry : entry.slice(0, hash);
+}
+function validateEntryPath(entry, at, issue) {
+    if (typeof entry !== "string" || entry.length === 0) {
+        issue("ui-entry-path", at, `required: a file inside the asset directory, e.g. "index.html#/user"`);
+        return;
+    }
+    const file = pluginEntryFile(entry);
+    if (file === "")
+        issue("ui-entry-path", at, `must name a file before the "#"`);
+    else if (/^[a-z][a-z0-9+.-]*:/i.test(file) || file.startsWith("//"))
+        issue("ui-entry-path", at, "must be relative to the asset directory, not a URL");
+    else if (file.startsWith("/"))
+        issue("ui-entry-path", at, `must not start with "/"`);
+    else if (file.includes("\\") || file.includes("?"))
+        issue("ui-entry-path", at, `must not contain "\\" or "?"`);
+    else if (file.split("/").some((s) => s === "" || s === "." || s === ".."))
+        issue("ui-entry-path", at, `must not contain empty, "." or ".." segments`);
+    else if (!/^[A-Za-z0-9._~/-]+$/.test(file))
+        issue("ui-entry-path", at, "letters, digits, ., _, ~, - and / only");
+}
+function parseRoutePath(path, at, issue) {
+    if (typeof path !== "string" || !path.startsWith("/")) {
+        issue("route-path", at, `must start with "/"`);
+        return;
+    }
+    if (path === "/")
+        return { segments: [], shape: "/" };
+    if (path.endsWith("/")) {
+        issue("route-path", at, `must not end with "/"`);
+        return;
+    }
+    const segments = [];
+    const names = new Set();
+    let bad = false;
+    for (const part of path.slice(1).split("/")) {
+        if (part === "") {
+            issue("route-path", at, "empty segment");
+            bad = true;
+            continue;
+        }
+        const param = /^\{([A-Za-z][A-Za-z0-9]*)\}$/.exec(part);
+        if (param) {
+            const name = param[1];
+            if (name === manifest_1.PLUGIN_ACCOUNT_PARAM) {
+                issue("route-reserved-param", at, `{${manifest_1.PLUGIN_ACCOUNT_PARAM}} is the platform's account segment`);
+                bad = true;
+            }
+            if (names.has(name)) {
+                issue("route-param-duplicate", at, `{${name}} appears twice`);
+                bad = true;
+            }
+            names.add(name);
+            segments.push({ kind: "param", name });
+            continue;
+        }
+        if (part.includes("+") || part === "*") {
+            issue("route-greedy", at, `greedy segments like "{proxy+}" are not supported`);
+            bad = true;
+            continue;
+        }
+        if (part.startsWith("{")) {
+            issue("route-path", at, `malformed parameter "${part}": use {name} with letters and digits`);
+            bad = true;
+            continue;
+        }
+        if (!/^[A-Za-z0-9._~-]+$/.test(part)) {
+            issue("route-path", at, `segment "${part}" has characters outside letters, digits, ., _, ~, -`);
+            bad = true;
+            continue;
+        }
+        segments.push({ kind: "literal", value: part });
+    }
+    if (bad)
+        return;
+    return { segments, shape: "/" + segments.map((s) => (s.kind === "param" ? "{}" : s.value)).join("/") };
+}
+function validateRoutes(routes, declared, handlerKeys, issue) {
+    if (routes === undefined) {
+        issue("route-path", "routes", "required: an array (empty for a UI-only plugin)");
+        return 0;
+    }
+    if (!Array.isArray(routes)) {
+        issue("route-path", "routes", "must be an array");
+        return 0;
+    }
+    const ids = new Set();
+    const shapes = new Map();
+    const paramAt = new Map();
+    routes.forEach((r, i) => {
+        const at = `routes[${i}]`;
+        if (!isRecord(r)) {
+            issue("route-id", at, "must be an object with id, method, path, permission, handlerKey");
+            return;
+        }
+        unknownKeys(r, ROUTE_KEYS, at, "unknown-field", issue);
+        const routeId = typeof r.id === "string" ? r.id : `#${i}`;
+        if (typeof r.id !== "string" || !manifest_1.PLUGIN_ID_PATTERN.test(r.id))
+            issue("route-id", `${at}.id`, "lowercase letters, digits and hyphens, starting with a letter, 1-64 characters");
+        else if (ids.has(r.id))
+            issue("route-duplicate-id", `${at}.id`, `route id "${r.id}" is used twice`);
+        else
+            ids.add(r.id);
+        const method = typeof r.method === "string" && manifest_1.PLUGIN_ROUTE_METHODS.includes(r.method) ? r.method : undefined;
+        if (!method)
+            issue("route-method", `${at}.method`, `one of ${manifest_1.PLUGIN_ROUTE_METHODS.join(", ")} (no ANY)`);
+        if (typeof r.permission !== "string" || !manifest_1.PLUGIN_PERMISSIONS.includes(r.permission))
+            issue("route-undeclared-permission", `${at}.permission`, `must be "user" or "admin"`);
+        else if (!declared.includes(r.permission))
+            issue("route-undeclared-permission", `${at}.permission`, `"${r.permission}" is not declared in permissions`);
+        if (typeof r.handlerKey !== "string" || r.handlerKey.length === 0)
+            issue("route-handler-key", `${at}.handlerKey`, "required: the key of a backend handler");
+        else if (handlerKeys && !handlerKeys.includes(r.handlerKey))
+            issue("route-handler-key", `${at}.handlerKey`, `no handler named "${r.handlerKey}" (have: ${handlerKeys.join(", ") || "none"})`);
+        const parsed = parseRoutePath(r.path, `${at}.path`, issue);
+        if (!parsed || !method)
+            return;
+        const shapeKey = `${method} ${parsed.shape}`;
+        const dup = shapes.get(shapeKey);
+        if (dup)
+            issue("route-duplicate-shape", `${at}.path`, `${method} ${parsed.shape} is already registered by route "${dup}" (parameter names do not distinguish routes)`);
+        else
+            shapes.set(shapeKey, routeId);
+        let prefix = "";
+        for (const seg of parsed.segments) {
+            if (seg.kind === "param") {
+                const key = `${prefix}/{}`;
+                const prev = paramAt.get(key);
+                if (prev && prev.name !== seg.name) {
+                    issue("route-param-conflict", `${at}.path`, `{${seg.name}} conflicts with {${prev.name}} in route "${prev.routeId}": API Gateway allows one parameter name per position`);
+                }
+                else if (!prev) {
+                    paramAt.set(key, { name: seg.name, routeId });
+                }
+                prefix = key;
+            }
+            else {
+                prefix = `${prefix}/${seg.value}`;
+            }
+        }
+    });
+    return routes.length;
+}

package/dist/fixtures/devHost.d.ts

@@ -0,0 +1,57 @@
+import { PluginAccountContext, PluginInfoContext, PluginSession, PluginUserContext } from "../contracts/messages";
+import { PluginAppearance, PluginTheme } from "../contracts/theme";
+import { PluginMessageListenerTarget } from "../contracts/transport";
+import { PluginHost, PluginHostFrame, PluginSessionEndReason } from "../host/host";
+export type DevHostEvent = {
+    readonly type: "ready";
+    readonly instanceId: string;
+    readonly sdkVersion: string;
+    readonly reconnect: boolean;
+} | {
+    readonly type: "handshakeTimeout";
+} | {
+    readonly type: "refresh";
+    readonly outcome: "renewed" | "failed";
+} | {
+    readonly type: "accessRefresh";
+    readonly reason: "forbidden" | "manual";
+} | {
+    readonly type: "incompatible";
+    readonly version: unknown;
+} | {
+    readonly type: "ended";
+    readonly reason: PluginSessionEndReason;
+};
+export interface DevHostOptions {
+    readonly frame: PluginHostFrame;
+    readonly listenOn: PluginMessageListenerTarget;
+    readonly origin: string;
+    readonly plugin?: Partial<PluginInfoContext>;
+    readonly entry?: "user" | "admin";
+    readonly user?: Partial<PluginUserContext>;
+    readonly accounts?: readonly PluginAccountContext[];
+    readonly appearance?: PluginAppearance;
+    readonly theme?: PluginTheme;
+    /** How long a fixture token lives; default five minutes. */
+    readonly tokenLifetimeMs?: number;
+    readonly handshakeTimeoutMs?: number;
+    readonly onEvent?: (event: DevHostEvent) => void;
+}
+export interface DevHost extends PluginHost {
+    session(): PluginSession;
+    accounts(): readonly PluginAccountContext[];
+    /** Mint a new fixture token and push it, as the portal's renew timer would. */
+    renewSession(): PluginSession;
+    /** Push the current token with an expiry in the past: the plugin's next request asks to renew. */
+    expireSession(): void;
+    /** The next renewal request ends the session instead (the portal's 12 h wall). */
+    failNextRefresh(): void;
+    grant(account: PluginAccountContext): void;
+    revoke(accountNumber: string): void;
+    setEntryAvailable(available: boolean): void;
+    setAppearance(appearance: PluginAppearance): void;
+    setTheme(theme: PluginTheme): void;
+    signOut(): void;
+}
+export declare function devHostTheme(appearance: PluginAppearance): PluginTheme;
+export declare function createDevHost(options: DevHostOptions): DevHost;

package/dist/fixtures/devHost.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.devHostTheme = devHostTheme;
+exports.createDevHost = createDevHost;
+const paths_1 = require("../contracts/paths");
+const host_1 = require("../host/host");
+const samples_1 = require("./samples");
+function devHostTheme(appearance) {
+    return appearance === "dark" ? samples_1.sampleDarkTheme : samples_1.sampleTheme;
+}
+function createDevHost(options) {
+    const lifetime = options.tokenLifetimeMs ?? 5 * 60_000;
+    let sequence = 0;
+    const mint = () => ({ token: `fixture-token-${++sequence}`, expiresAt: Date.now() + lifetime });
+    let session = mint();
+    let accounts = options.accounts ?? samples_1.sampleAccounts;
+    let entryAvailable = true;
+    let theme = options.theme ?? devHostTheme(options.appearance ?? "light");
+    let failNext = false;
+    const emit = (event) => options.onEvent?.(event);
+    const base = {
+        id: "parameters", displayName: "Application parameters", version: "0.0.0-dev", revision: "dev",
+        ...options.plugin,
+    };
+    // Derived AFTER the overrides: a developer who renames the plugin gets their own API root.
+    const plugin = { ...base, apiBaseUrl: options.plugin?.apiBaseUrl ?? (0, paths_1.pluginApiBaseUrl)(base.id) };
+    const user = { subject: "dev-user", principalType: "user", email: "dev@example.com", displayName: "Dev User", ...options.user };
+    const renew = () => {
+        session = mint();
+        return session;
+    };
+    const host = (0, host_1.createPluginHost)({
+        frame: options.frame,
+        origin: options.origin,
+        listenOn: options.listenOn,
+        handshakeTimeoutMs: options.handshakeTimeoutMs,
+        initialState: () => ({ session, user, plugin, entry: options.entry ?? "user", accounts, theme }),
+        refreshSession: async () => {
+            if (failNext) {
+                failNext = false;
+                emit({ type: "refresh", outcome: "failed" });
+                return null;
+            }
+            emit({ type: "refresh", outcome: "renewed" });
+            return renew();
+        },
+        onReady: (info) => emit({ type: "ready", ...info }),
+        onHandshakeTimeout: () => emit({ type: "handshakeTimeout" }),
+        onRequestAccessRefresh: (reason) => emit({ type: "accessRefresh", reason }),
+        onIncompatible: (info) => emit({ type: "incompatible", version: info.version }),
+        onEnded: (reason) => emit({ type: "ended", reason }),
+    });
+    const pushAccess = () => host.sendAccess({ accounts, entryAvailable });
+    return {
+        ...host,
+        session: () => session,
+        accounts: () => accounts,
+        renewSession: () => {
+            host.sendSession(renew());
+            return session;
+        },
+        expireSession: () => {
+            session = { token: session.token, expiresAt: Date.now() - 1 };
+            host.sendSession(session);
+        },
+        failNextRefresh: () => {
+            failNext = true;
+        },
+        grant: (account) => {
+            accounts = [...accounts.filter((a) => a.accountNumber !== account.accountNumber), account];
+            pushAccess();
+        },
+        revoke: (accountNumber) => {
+            accounts = accounts.filter((a) => a.accountNumber !== accountNumber);
+            pushAccess();
+        },
+        setEntryAvailable: (available) => {
+            entryAvailable = available;
+            pushAccess();
+        },
+        setAppearance: (appearance) => {
+            theme = devHostTheme(appearance);
+            host.sendTheme(theme);
+        },
+        setTheme: (next) => {
+            theme = next;
+            host.sendTheme(next);
+        },
+        signOut: () => host.end("signedOut"),
+    };
+}