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

package/src/handler.ts

@@ -0,0 +1,111 @@
+import type { APIGatewayProxyEvent, APIGatewayProxyResult } from "aws-lambda";
+import { SSMClient } from "@aws-sdk/client-ssm";
+import {
+  createPluginLogger,
+  pluginAuthorizerContextOf,
+  pluginRoutePath,
+  PluginAuthorizerContextV1,
+} from "@fntio/infra-client-plugin-sdk/backend";
+import { ssmParameterStore } from "./parameters";
+import { assertInScope, configuredPrefixes, ParameterScopeError, ParameterStore } from "./scope";
+
+// The plugin's three routes. Authentication and authorization already happened: the shared authorizer
+// verified the caller, matched this request to a registered route, and attached the context below. What
+// is left is the plugin's own business — which is why nothing here re-reads a permission or an account
+// from the request body.
+
+const ssm = new SSMClient({});
+
+/** The account this function may touch. A route authorized for account A must never act on account B,
+ *  so a mismatch is refused rather than quietly served from wherever the function happens to run. */
+const HOME_ACCOUNT = process.env.PLUGIN_ACCOUNT_NUMBER ?? "";
+
+const json = (statusCode: number, body: unknown): APIGatewayProxyResult => ({
+  statusCode,
+  headers: { "content-type": "application/json", "cache-control": "no-store" },
+  body: JSON.stringify(body),
+});
+
+export interface HandlerDeps {
+  readonly store: ParameterStore;
+  readonly prefixes: string[];
+  readonly homeAccount: string;
+}
+
+function deps(): HandlerDeps {
+  return { store: ssmParameterStore(ssm), prefixes: configuredPrefixes(), homeAccount: HOME_ACCOUNT };
+}
+
+export async function handler(event: APIGatewayProxyEvent): Promise<APIGatewayProxyResult> {
+  return route(event, deps());
+}
+
+/** Exported for tests: the same path the Lambda takes, with its dependencies handed in. */
+export async function route(event: APIGatewayProxyEvent, d: HandlerDeps): Promise<APIGatewayProxyResult> {
+  let ctx: PluginAuthorizerContextV1;
+  try {
+    ctx = pluginAuthorizerContextOf(event);
+  } catch {
+    // Only reachable if this function is invoked outside its gateway route; fail closed rather than
+    // guess who the caller is.
+    return json(500, { message: "This request did not come through the portal." });
+  }
+  const log = createPluginLogger(ctx);
+
+  if (!d.prefixes.length) {
+    log.error("no parameter prefixes configured");
+    return json(500, { message: "This plugin has no parameter prefixes configured." });
+  }
+  if (ctx.accountNumber !== d.homeAccount) {
+    // The portal authorized an account this deployment of the plugin cannot serve. Reading the home
+    // account's parameters anyway would hand the caller another account's data.
+    log.error("authorized for an account this plugin does not serve", { requested: ctx.accountNumber });
+    return json(409, { message: `This plugin instance only serves account ${d.homeAccount}.` });
+  }
+
+  const path = pluginRoutePath(event.path, ctx);
+  if (path === null) return json(400, { message: "That path is outside this plugin." });
+  const method = event.httpMethod.toUpperCase();
+  const name = event.pathParameters?.["name"];
+
+  try {
+    if (method === "GET" && path === "/parameters") {
+      const parameters = await d.store.list(d.prefixes);
+      log.info("listed parameters", { count: parameters.length });
+      return json(200, { parameters, prefixes: d.prefixes });
+    }
+
+    if (method === "GET" && name) {
+      const decoded = decodeURIComponent(name);
+      assertInScope(decoded, d.prefixes);
+      const parameter = await d.store.get(decoded);
+      log.info("read parameter", { name: decoded, secret: parameter.secret });
+      return json(200, { parameter });
+    }
+
+    if (method === "PUT" && name) {
+      const decoded = decodeURIComponent(name);
+      assertInScope(decoded, d.prefixes);
+      const value = (JSON.parse(event.body ?? "{}") as { value?: unknown }).value;
+      if (typeof value !== "string" || !value.length) {
+        return json(400, { message: "Send a non-empty string value." });
+      }
+      const version = await d.store.put(decoded, value);
+      // The value itself is never logged — only that it changed, and to which version.
+      log.info("updated parameter", { name: decoded, version });
+      return json(200, { name: decoded, version });
+    }
+  } catch (err) {
+    if (err instanceof ParameterScopeError) {
+      log.warn("refused an out-of-scope parameter", { error: err.message });
+      return json(400, { message: err.message });
+    }
+    if ((err as { name?: string }).name === "ParameterNotFound") {
+      return json(404, { message: "No such parameter." });
+    }
+    log.error("parameter operation failed", { error: (err as Error).message });
+    return json(502, { message: "The parameter store did not answer." });
+  }
+
+  return json(404, { message: `No such route: ${method} ${path}` });
+}

package/src/index.ts

@@ -0,0 +1,96 @@
+import * as path from "node:path";
+import { Duration } from "aws-cdk-lib";
+import * as iam from "aws-cdk-lib/aws-iam";
+import * as lambda from "aws-cdk-lib/aws-lambda";
+import type { Construct } from "constructs";
+import { definePlugin, PluginDefinition } from "@fntio/infra-client-plugin-cdk";
+
+export interface ParametersPluginProps {
+  /** The account whose parameters this instance serves. The handler refuses any other, even if the
+   *  portal authorizes one, so a second account means a second registration with its own function. */
+  readonly accountNumber: string;
+  /** SSM name prefixes the plugin may read and write. Nothing outside them is reachable — not by a
+   *  crafted name, not by a `..` segment. Least privilege is enforced twice: here and in the IAM policy. */
+  readonly prefixes: readonly string[];
+  /** Defaults to the stack's region. */
+  readonly region?: string;
+  readonly version?: string;
+  /** Off by default would hide it from everyone; registrations are usually enabled. */
+  readonly enabled?: boolean;
+}
+
+/** The reference plugin: a scoped Parameter Store viewer and editor.
+ *
+ *  Everything a customer writes for their own plugin is here — a manifest, a handler factory, and the
+ *  IAM the handler needs. `addAccessPortal({ plugins: [parametersPlugin(...)] })` is the only wiring. */
+export function parametersPlugin(props: ParametersPluginProps): PluginDefinition {
+  const prefixes = props.prefixes.map((p) => (p.endsWith("/") ? p : `${p}/`));
+  if (!prefixes.length) throw new Error("parametersPlugin needs at least one parameter prefix");
+
+  return definePlugin({
+    schemaVersion: 1,
+    id: "parameters",
+    displayName: "Application parameters",
+    description: "Read and edit SSM parameters under the configured prefixes.",
+    version: props.version ?? "1.0.0",
+    hostApiVersion: 1,
+    enabled: props.enabled ?? true,
+    accounts: [{ accountNumber: props.accountNumber, ...(props.region ? { regions: [props.region] } : {}) }],
+    permissions: [
+      { id: "user", label: "View application parameters" },
+      { id: "admin", label: "Edit application parameters", description: "Includes viewing." },
+    ],
+    ui: {
+      assets: path.join(__dirname, "..", "web-dist"),
+      user: { label: "Parameters", icon: "sliders", order: 10, entry: "index.html#/user" },
+      admin: { label: "Parameters", icon: "sliders", order: 10, entry: "index.html#/admin" },
+    },
+    backend: {
+      handlers: { api: (scope) => apiFunction(scope, props.accountNumber, prefixes) },
+      routes: [
+        { id: "list", method: "GET", path: "/parameters", permission: "user", handlerKey: "api" },
+        { id: "get", method: "GET", path: "/parameters/{name}", permission: "user", handlerKey: "api" },
+        { id: "update", method: "PUT", path: "/parameters/{name}", permission: "admin", handlerKey: "api" },
+      ],
+    },
+  });
+}
+
+function apiFunction(scope: Construct, accountNumber: string, prefixes: string[]): lambda.IFunction {
+  // The bundle is built when this package is built (scripts/build-lambda.mjs), so a deployment
+  // that installs the package needs no bundler of its own.
+  const fn = new lambda.Function(scope, "ParametersApi", {
+    code: lambda.Code.fromAsset(path.join(__dirname, "..", "lambda-dist")),
+    description: "Example plugin API: reads the allowed SSM parameters in this account.",
+    handler: "index.handler",
+    runtime: lambda.Runtime.NODEJS_22_X,
+    timeout: Duration.seconds(10),
+    environment: {
+      PLUGIN_ACCOUNT_NUMBER: accountNumber,
+      PARAMETER_PREFIXES: prefixes.join(","),
+    },
+  });
+
+  // The policy mirrors the handler's own rule, so neither alone is the only thing standing between a
+  // caller and the rest of the account's parameters.
+  const arns = prefixes.map((prefix) => `arn:aws:ssm:*:${accountNumber}:parameter${prefix}*`);
+  fn.addToRolePolicy(
+    new iam.PolicyStatement({
+      actions: ["ssm:GetParameter", "ssm:GetParameters", "ssm:PutParameter"],
+      resources: arns,
+    })
+  );
+  // GetParametersByPath authorizes on the path itself, not the parameters under it.
+  fn.addToRolePolicy(
+    new iam.PolicyStatement({
+      actions: ["ssm:GetParametersByPath"],
+      resources: prefixes.map((prefix) => `arn:aws:ssm:*:${accountNumber}:parameter${prefix.replace(/\/$/, "")}`),
+    })
+  );
+  return fn;
+}
+
+// From scope.ts, never from parameters.ts: a re-export here decides what a consumer has to have
+// installed to synthesize, and parameters.ts imports the AWS SDK client the Lambda uses.
+export { assertInScope, configuredPrefixes, ParameterScopeError } from "./scope";
+export type { ParameterDetail, ParameterSummary, ParameterStore } from "./scope";

package/src/parameters.ts

@@ -0,0 +1,54 @@
+import { SSMClient, GetParameterCommand, GetParametersByPathCommand, PutParameterCommand } from "@aws-sdk/client-ssm";
+import type { ParameterStore, ParameterSummary } from "./scope";
+
+// The SSM-backed half of the plugin's rules, loaded only inside the Lambda. Everything the
+// registration needs lives in scope.ts, which imports nothing from the AWS SDK.
+
+const isSecret = (type?: string) => type === "SecureString";
+
+export function ssmParameterStore(client: SSMClient): ParameterStore {
+  return {
+    async list(prefixes) {
+      const out: ParameterSummary[] = [];
+      for (const prefix of prefixes) {
+        let NextToken: string | undefined;
+        do {
+          const page = await client.send(
+            new GetParametersByPathCommand({ Path: prefix.replace(/\/$/, ""), Recursive: true, WithDecryption: false, NextToken })
+          );
+          for (const p of page.Parameters ?? []) {
+            if (!p.Name) continue;
+            out.push({
+              name: p.Name,
+              type: p.Type ?? "String",
+              ...(p.LastModifiedDate ? { lastModified: p.LastModifiedDate.toISOString() } : {}),
+              ...(p.Version === undefined ? {} : { version: p.Version }),
+            });
+          }
+          NextToken = page.NextToken;
+        } while (NextToken);
+      }
+      return out.sort((a, b) => a.name.localeCompare(b.name));
+    },
+
+    async get(name) {
+      // WithDecryption stays false on purpose: a SecureString comes back as metadata only.
+      const res = await client.send(new GetParameterCommand({ Name: name, WithDecryption: false }));
+      const p = res.Parameter ?? {};
+      const secret = isSecret(p.Type);
+      return {
+        name,
+        type: p.Type ?? "String",
+        secret,
+        ...(secret ? {} : { value: p.Value ?? "" }),
+        ...(p.LastModifiedDate ? { lastModified: p.LastModifiedDate.toISOString() } : {}),
+        ...(p.Version === undefined ? {} : { version: p.Version }),
+      };
+    },
+
+    async put(name, value) {
+      const res = await client.send(new PutParameterCommand({ Name: name, Value: value, Overwrite: true }));
+      return res.Version ?? 0;
+    },
+  };
+}

package/src/scope.ts

@@ -0,0 +1,46 @@
+// What this plugin is willing to touch, and nothing that talks to AWS. The registration
+// (index.ts) re-exports from here, so loading it on a developer's machine never pulls the
+// Lambda's runtime dependencies in with it — a consumer installs the package without them.
+
+export interface ParameterSummary {
+  readonly name: string;
+  /** SecureString values are never fetched decrypted, so the type is how the UI knows to say so. */
+  readonly type: string;
+  readonly lastModified?: string;
+  readonly version?: number;
+}
+
+export interface ParameterDetail extends ParameterSummary {
+  /** Absent for a SecureString: this sample never displays a decrypted secret. */
+  readonly value?: string;
+  readonly secret: boolean;
+}
+
+export class ParameterScopeError extends Error {}
+
+/** Prefixes this deployment allows, from the registration. Empty = the plugin can touch nothing. */
+export function configuredPrefixes(raw = process.env.PARAMETER_PREFIXES): string[] {
+  return (raw ?? "")
+    .split(",")
+    .map((p) => p.trim())
+    .filter(Boolean)
+    .map((p) => (p.endsWith("/") ? p : `${p}/`));
+}
+
+/** A name is in scope only if it sits under a configured prefix and cannot climb out of it. A `..`
+ *  segment, a missing leading slash, or a name that merely starts with the prefix as a string
+ *  (`/app-secrets` against `/app`) are all refused. */
+export function assertInScope(name: string, prefixes: string[]): void {
+  if (!name.startsWith("/")) throw new ParameterScopeError("A parameter name starts with /");
+  if (name.split("/").includes("..")) throw new ParameterScopeError("A parameter name cannot contain ..");
+  if (!/^[a-zA-Z0-9_.\-/]+$/.test(name)) throw new ParameterScopeError("That parameter name has characters SSM does not allow");
+  if (!prefixes.some((prefix) => name.startsWith(prefix))) {
+    throw new ParameterScopeError(`This plugin is limited to ${prefixes.join(", ") || "no prefixes"}`);
+  }
+}
+
+export interface ParameterStore {
+  list(prefixes: string[]): Promise<ParameterSummary[]>;
+  get(name: string): Promise<ParameterDetail>;
+  put(name: string, value: string): Promise<number>;
+}

package/web/app.css

@@ -0,0 +1,16 @@
+/* The component styles come from @fntio/infra-client-plugin-ui and the values from the portal's theme;
+   this file is only what is specific to this plugin's own page. */
+:root { color-scheme: light dark; }
+
+body {
+  margin: 0;
+  /* The frame is the whole page, so the page gutter is the plugin's: the portal's own is 2rem. */
+  padding: 2rem;
+  /* Transparent: the portal paints the surface behind the frame. */
+  background: transparent;
+}
+
+/* The value column carries the widest, least predictable content. */
+.value { max-width: 22rem; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.editing { display: flex; align-items: center; gap: 0.4rem; }
+.editing .ic-input { min-width: 12rem; }

package/web/app.ts

@@ -0,0 +1,296 @@
+import { connectToInfraClient, PluginAccountContext, PluginApiError, PluginContext } from "@fntio/infra-client-plugin-sdk/browser";
+import { applyPluginUi } from "@fntio/infra-client-plugin-ui";
+
+// A plugin frontend in plain TypeScript — no framework, to show the SDK does not ask for one. The portal
+// has already signed the user in; this page never sees a password, a refresh token, or a login screen.
+// Its look comes from the shared UI classes, so it reads as part of the app without copying anything.
+
+interface ParameterSummary {
+  name: string;
+  type: string;
+  lastModified?: string;
+  version?: number;
+}
+
+const app = () => document.getElementById("app") as HTMLElement;
+
+function el<K extends keyof HTMLElementTagNameMap>(
+  tag: K,
+  className?: string,
+  text?: string
+): HTMLElementTagNameMap[K] {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text !== undefined) node.textContent = text;
+  return node;
+}
+
+const button = (label: string, variant = "outline"): HTMLButtonElement =>
+  el("button", `ic-btn ic-btn-sm ic-btn-${variant}`, label);
+
+function show(...nodes: (Node | null)[]): void {
+  app().replaceChildren(...nodes.filter((n): n is Node => n !== null));
+}
+
+/** The three states every plugin page needs, drawn the way the portal draws them. */
+function loading(): HTMLElement {
+  const card = el("div", "ic-card");
+  for (let i = 0; i < 3; i += 1) card.appendChild(el("div", "ic-skeleton"));
+  return card;
+}
+
+function empty(message: string, hint?: string): HTMLElement {
+  const box = el("div", "ic-empty");
+  box.appendChild(el("p", undefined, message));
+  if (hint) box.appendChild(el("p", "ic-caption", hint));
+  return box;
+}
+
+function failure(message: string, retry?: () => void): HTMLElement {
+  const box = el("div", "ic-error");
+  box.appendChild(el("p", "ic-error-title", "That did not work"));
+  box.appendChild(el("p", "ic-caption", message));
+  if (retry) {
+    const again = button("Try again", "outline");
+    again.addEventListener("click", retry);
+    box.appendChild(again);
+  }
+  return box;
+}
+
+async function start(): Promise<void> {
+  applyPluginUi(document);
+  let context: PluginContext;
+  try {
+    context = await connectToInfraClient();
+  } catch (err) {
+    // The portal is the only way in; outside its frame there is nothing this page can do.
+    show(failure((err as Error).message));
+    return;
+  }
+
+  context.on("accessChanged", () => void draw(context));
+  context.on("sessionEnded", () => show(empty("Your session ended.", "Sign in again in the portal.")));
+  await draw(context);
+}
+
+// Which account the page works in is this plugin's own state: the portal only says which accounts are open.
+let chosen: string | null = null;
+/** An account the user was working in and no longer holds. Said out loud, never swapped for another:
+ *  quietly moving someone to a different account is how an edit lands in the wrong one. */
+let lost: string | null = null;
+
+/** The chosen account while it is still permitted. Only the first visit defaults to the first account. */
+function currentAccount(context: PluginContext): PluginAccountContext | null {
+  const accounts = context.accounts();
+  if (chosen && !accounts.some((a) => a.accountNumber === chosen)) {
+    lost = chosen;
+    chosen = null;
+  }
+  // Granted back (or a refresh that briefly dropped it): pick up where the user was.
+  if (lost && accounts.some((a) => a.accountNumber === lost)) {
+    chosen = lost;
+    lost = null;
+  }
+  if (!chosen && !lost) chosen = accounts[0]?.accountNumber ?? null;
+  return accounts.find((a) => a.accountNumber === chosen) ?? null;
+}
+
+/** The plugin draws its own header: the portal hands the frame the whole page. Title on the left; the
+ *  account picker on the right only when there is a choice. */
+function pageHeader(context: PluginContext): HTMLElement {
+  const header = el("div", "ic-header");
+  const titles = el("div");
+  titles.appendChild(el("h1", "ic-title", "Parameters"));
+  titles.appendChild(el("p", "ic-caption", `${context.plugin.displayName} · ${context.plugin.version}`));
+  header.appendChild(titles);
+
+  const accounts = context.accounts();
+  const selected = currentAccount(context);
+  if (accounts.length > 1 || (accounts.length === 1 && !selected)) {
+    const select = el("select", "ic-select");
+    select.setAttribute("aria-label", "Account");
+    if (!selected) {
+      const placeholder = el("option", undefined, "Choose an account");
+      placeholder.value = "";
+      placeholder.selected = true;
+      placeholder.disabled = true;
+      select.appendChild(placeholder);
+    }
+    for (const account of accounts) {
+      const option = el("option", undefined, `${account.accountNumber} · ${account.displayName}`);
+      option.value = account.accountNumber;
+      option.selected = account.accountNumber === selected?.accountNumber;
+      select.appendChild(option);
+    }
+    select.addEventListener("change", () => {
+      chosen = select.value;
+      lost = null;
+      void draw(context);
+    });
+    header.appendChild(select);
+  } else if (selected) {
+    header.appendChild(el("span", "ic-caption ic-mono", `${selected.accountNumber} · ${selected.displayName}`));
+  }
+  return header;
+}
+
+/** Only the newest draw may paint: a slow load for one account must not land under another's header. */
+let drawing = 0;
+
+async function draw(context: PluginContext): Promise<void> {
+  const run = ++drawing;
+  const page = (...nodes: (Node | null)[]) => show(pageHeader(context), ...nodes);
+  const account = currentAccount(context);
+  if (!account) {
+    page(
+      lost
+        ? empty(`Your access to account ${lost} ended.`, context.accounts().length ? "Choose another account to continue." : undefined)
+        : empty("No account available.", "You have no account with access to this plugin.")
+    );
+    return;
+  }
+  // `entry` is which page the portal opened, and it decides what this frame offers. The API enforces the
+  // same thing independently — this only keeps the UI honest.
+  const canEdit = context.entry === "admin" && context.hasPermission("admin", account.accountNumber);
+  page(loading());
+
+  let parameters: ParameterSummary[];
+  let prefixes: string[];
+  try {
+    const res = await context.api.get<{ parameters: ParameterSummary[]; prefixes: string[] }>(
+      `accounts/${account.accountNumber}/parameters`
+    );
+    parameters = res.parameters;
+    prefixes = res.prefixes;
+  } catch (err) {
+    if (run === drawing) page(failure(explain(err), () => void draw(context)));
+    return;
+  }
+  if (run !== drawing) return;
+
+  if (!parameters.length) {
+    page(empty("No parameters yet.", `Nothing exists under ${prefixes.join(", ")}.`));
+    return;
+  }
+
+  const card = el("div", "ic-card");
+  const head = el("div", "ic-card-head");
+  head.appendChild(el("h2", "ic-card-title", `${parameters.length} parameter${parameters.length === 1 ? "" : "s"}`));
+  head.appendChild(el("span", "ic-caption", prefixes.join(", ")));
+  card.appendChild(head);
+
+  const wrap = el("div", "ic-table-wrap");
+  const table = el("table", "ic-table");
+  const thead = el("thead");
+  const headRow = el("tr");
+  for (const [label, width] of [["Name", ""], ["Value", ""], ["Type", ""], ["", ""]] as const) {
+    const th = el("th", undefined, label);
+    if (width) th.style.width = width;
+    headRow.appendChild(th);
+  }
+  thead.appendChild(headRow);
+  table.appendChild(thead);
+  const body = el("tbody");
+  for (const parameter of parameters) body.appendChild(row(context, account.accountNumber, parameter, canEdit));
+  table.appendChild(body);
+  wrap.appendChild(table);
+  card.appendChild(wrap);
+  page(card);
+}
+
+function row(context: PluginContext, accountNumber: string, parameter: ParameterSummary, canEdit: boolean): HTMLElement {
+  const secret = parameter.type === "SecureString";
+  const tr = el("tr");
+  tr.appendChild(el("td", "ic-mono", parameter.name));
+
+  const valueCell = el("td", "value ic-mono ic-muted", "—");
+  tr.appendChild(valueCell);
+
+  const typeCell = el("td");
+  typeCell.appendChild(el("span", `ic-badge${secret ? " ic-badge-amber" : ""}`, secret ? "secret" : parameter.type));
+  tr.appendChild(typeCell);
+
+  const actions = el("td");
+  const reveal = button(secret ? "Details" : "Show");
+  reveal.addEventListener("click", async () => {
+    reveal.disabled = true;
+    try {
+      const res = await context.api.get<{ parameter: { value?: string; secret: boolean } }>(
+        `accounts/${accountNumber}/parameters/${encodeURIComponent(parameter.name)}`
+      );
+      if (res.parameter.secret) {
+        // An encrypted value is never fetched decrypted; say so rather than showing an empty cell.
+        valueCell.textContent = "hidden — encrypted";
+        reveal.remove();
+        return;
+      }
+      valueCell.textContent = res.parameter.value ?? "";
+      valueCell.className = "value ic-mono";
+      reveal.remove();
+      if (canEdit) actions.appendChild(editButton(context, accountNumber, parameter.name, valueCell, actions));
+    } catch (err) {
+      valueCell.replaceChildren(el("span", "ic-caption", explain(err)));
+      reveal.disabled = false;
+    }
+  });
+  actions.appendChild(reveal);
+  tr.appendChild(actions);
+  return tr;
+}
+
+function editButton(
+  context: PluginContext,
+  accountNumber: string,
+  name: string,
+  valueCell: HTMLElement,
+  actions: HTMLElement
+): HTMLButtonElement {
+  const edit = button("Edit");
+  edit.addEventListener("click", () => {
+    const original = valueCell.textContent ?? "";
+    const input = el("input", "ic-input");
+    input.value = original;
+    input.setAttribute("aria-label", `New value for ${name}`);
+    const save = button("Save", "primary");
+    const cancel = button("Cancel", "ghost");
+    const editing = el("div", "editing");
+    editing.append(input, save, cancel);
+    valueCell.replaceChildren(editing);
+    edit.remove();
+    input.focus();
+
+    const done = (text: string) => {
+      valueCell.replaceChildren();
+      valueCell.textContent = text;
+      actions.appendChild(editButton(context, accountNumber, name, valueCell, actions));
+    };
+    cancel.addEventListener("click", () => done(original));
+    save.addEventListener("click", async () => {
+      // An explicit confirmation before a write: this edits live configuration.
+      if (!window.confirm(`Set ${name} to "${input.value}"?`)) return;
+      save.disabled = true;
+      try {
+        await context.api.put(`accounts/${accountNumber}/parameters/${encodeURIComponent(name)}`, { value: input.value });
+        done(input.value);
+      } catch (err) {
+        save.disabled = false;
+        const message = el("span", "ic-caption", explain(err));
+        editing.appendChild(message);
+      }
+    });
+  });
+  return edit;
+}
+
+/** Turn an SDK error into something a person can act on. */
+function explain(err: unknown): string {
+  if (err instanceof PluginApiError) {
+    const body = err.body as { message?: string } | undefined;
+    if (err.status === 403) return "You no longer have access to this plugin in this account.";
+    return body?.message ?? `The request failed (${err.status}).`;
+  }
+  return (err as Error).message || "Something went wrong.";
+}
+
+void start();

package/web/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Application parameters</title>
+    <link rel="stylesheet" href="app.css" />
+  </head>
+  <body>
+    <!-- The portal paints this document's theme tokens; nothing here hardcodes a colour or a product name. -->
+    <main id="app" class="ic-page" aria-live="polite">
+      <p class="muted">Connecting to the portal…</p>
+    </main>
+    <script src="app.js"></script>
+  </body>
+</html>

package/web-dist/app.css

@@ -0,0 +1,16 @@
+/* The component styles come from @fntio/infra-client-plugin-ui and the values from the portal's theme;
+   this file is only what is specific to this plugin's own page. */
+:root { color-scheme: light dark; }
+
+body {
+  margin: 0;
+  /* The frame is the whole page, so the page gutter is the plugin's: the portal's own is 2rem. */
+  padding: 2rem;
+  /* Transparent: the portal paints the surface behind the frame. */
+  background: transparent;
+}
+
+/* The value column carries the widest, least predictable content. */
+.value { max-width: 22rem; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.editing { display: flex; align-items: center; gap: 0.4rem; }
+.editing .ic-input { min-width: 12rem; }