@thotischner/observability-mcp 1.4.0 → 1.5.1

package/dist/cli/lib.js

@@ -0,0 +1,185 @@
+// Pure, IO-free helpers for the omcp CLI so they can be unit-tested
+// without spawning docker or touching the filesystem.
+/** Minimal argv parser: `omcp <command> [sub] [positionals] [--flag[=val]] [-f val]`. */
+export function parseArgs(argv) {
+    const flags = {};
+    const rest = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith("--")) {
+            const eq = a.indexOf("=");
+            if (eq !== -1)
+                flags[a.slice(2, eq)] = a.slice(eq + 1);
+            else if (i + 1 < argv.length && !argv[i + 1].startsWith("-"))
+                flags[a.slice(2)] = argv[++i];
+            else
+                flags[a.slice(2)] = true;
+        }
+        else if (a.startsWith("-") && a.length > 1) {
+            if (i + 1 < argv.length && !argv[i + 1].startsWith("-"))
+                flags[a.slice(1)] = argv[++i];
+            else
+                flags[a.slice(1)] = true;
+        }
+        else {
+            rest.push(a);
+        }
+    }
+    return { command: rest[0] ?? "", sub: rest[1], flags, positionals: rest.slice(2) };
+}
+/**
+ * Given a desired port and a predicate that says whether a port is in
+ * use, return the first free port at or after `desired` (bounded scan).
+ */
+export function pickFreePort(desired, inUse, span = 50) {
+    for (let p = desired; p < desired + span; p++) {
+        if (!inUse(p))
+            return p;
+    }
+    throw new Error(`no free port in [${desired}, ${desired + span})`);
+}
+/**
+ * Build a docker-compose override that remaps the host side of the
+ * given service ports. Uses the `!override` tag so it replaces (not
+ * appends to) the base `ports:` list.
+ */
+export function composeOverride(remaps) {
+    const services = remaps
+        .map((r) => `  ${r.service}:\n    ports: !override\n      - "${r.host}:${r.container}"`)
+        .join("\n");
+    return `services:\n${services}\n`;
+}
+export const DEFAULT_CATALOG_URL = "https://thotischner.github.io/observability-mcp/hub/index.json";
+/**
+ * Decide where to read the catalog from, in priority order:
+ *   1. explicit `from` (a URL or a filesystem path)
+ *   2. a local checkout's hub/catalog/index.json (when localPath exists)
+ *   3. the public Pages catalog
+ */
+export function resolveCatalogSource(from, localPath) {
+    if (from) {
+        return /^https?:\/\//.test(from)
+            ? { kind: "url", location: from }
+            : { kind: "file", location: from };
+    }
+    if (localPath)
+        return { kind: "file", location: localPath };
+    return { kind: "url", location: DEFAULT_CATALOG_URL };
+}
+export function formatPluginList(cat) {
+    const rows = cat.connectors
+        .slice()
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((c) => {
+        const latest = c.latest ?? c.versions[0]?.version ?? "—";
+        const flags = [c.builtin ? "builtin" : "", c.tier].filter(Boolean).join(",");
+        return [c.name, latest, c.signalTypes.join("+"), flags];
+    });
+    const head = ["NAME", "LATEST", "SIGNALS", "TIER"];
+    const widths = head.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
+    const line = (cols) => cols.map((c, i) => c.padEnd(widths[i])).join("  ").trimEnd();
+    return [line(head), ...rows.map(line)].join("\n");
+}
+export function formatPluginInfo(c) {
+    const out = [];
+    out.push(`${c.displayName}  (${c.name})`);
+    out.push(`  tier:      ${c.tier}${c.builtin ? " · builtin (ships in the server image)" : ""}`);
+    out.push(`  signals:   ${c.signalTypes.join(", ")}`);
+    out.push(`  ${c.description}`);
+    out.push(`  versions:`);
+    for (const v of c.versions) {
+        out.push(`    - ${v.version}${v.releasedAt ? ` (${v.releasedAt})` : ""}${v.serverCompat ? ` · server ${v.serverCompat}` : ""}`);
+        if (v.integrity)
+            out.push(`      integrity: ${v.integrity}`);
+        if (v.signatureUrl)
+            out.push(`      signature: ${v.signatureUrl}`);
+        if (v.tarballUrl)
+            out.push(`      tarball:   ${v.tarballUrl}`);
+        if (v.changelog)
+            out.push(`      changelog: ${v.changelog}`);
+    }
+    return out.join("\n");
+}
+/** Split "name" or "name@1.2.3" into parts. Throws on a malformed ref. */
+export function parsePluginRef(ref) {
+    const m = ref.match(/^([a-z][a-z0-9-]*)(?:@(\d+\.\d+\.\d+(?:-[a-z0-9.-]+)?))?$/);
+    if (!m)
+        throw new Error(`invalid plugin ref '${ref}' (expected name or name@x.y.z)`);
+    return { name: m[1], version: m[2] };
+}
+/**
+ * Resolve a catalog + ref into the concrete artifact to install.
+ * Returns {builtin:true} for image-bundled connectors (caller should
+ * no-op). Throws if the connector/version is unknown.
+ */
+export function resolveInstall(cat, ref) {
+    const { name, version } = parsePluginRef(ref);
+    const c = cat.connectors.find((x) => x.name === name);
+    if (!c)
+        throw new Error(`no connector '${name}' in catalog (try: omcp plugin list)`);
+    if (c.builtin)
+        return { name, version: version ?? c.latest ?? "", builtin: true };
+    const v = version
+        ? c.versions.find((x) => x.version === version)
+        : c.versions.find((x) => x.version === (c.latest ?? c.versions[0]?.version)) ?? c.versions[0];
+    if (!v)
+        throw new Error(`version '${version}' not found for '${name}'`);
+    return {
+        name,
+        version: v.version,
+        builtin: false,
+        tarballUrl: v.tarballUrl,
+        signatureUrl: v.signatureUrl,
+        manifestUrl: v.manifestUrl,
+        integrity: v.integrity,
+    };
+}
+export const HELM_REPO_NAME = "observability-mcp";
+export const HELM_REPO_URL = "https://thotischner.github.io/observability-mcp/";
+export const HELM_CHART = "observability-mcp/observability-mcp";
+/**
+ * Split argv at the first standalone "--": everything after it is
+ * passed verbatim to the wrapped tool (helm). Keeps omcp from having to
+ * re-implement helm's flag grammar (repeatable --set, -n, -f, ...).
+ */
+export function splitPassthrough(argv) {
+    const i = argv.indexOf("--");
+    if (i === -1)
+        return { argv, passthrough: [] };
+    return { argv: argv.slice(0, i), passthrough: argv.slice(i + 1) };
+}
+/** The helm argv for the install/upgrade step (repo add/update are fixed). */
+export function helmReleaseArgs(action, release, passthrough) {
+    const head = action === "upgrade"
+        ? ["upgrade", "--install", release, HELM_CHART]
+        : ["install", release, HELM_CHART];
+    return [...head, ...passthrough];
+}
+export const HELP = `omcp — observability-mcp control CLI
+
+Usage:
+  omcp version                 Print CLI + server package version
+  omcp doctor                  Check the local toolchain (docker, compose, helm, node)
+  omcp demo up                 Start the full demo stack (auto-picks free host ports)
+  omcp demo down               Stop and remove the demo stack
+  omcp demo status             Show demo container status
+  omcp plugin list             List connectors from the hub catalog
+  omcp plugin info <name>      Show one connector's versions + verification info
+  omcp plugin install <ref>    Install name[@version]: download, verify, extract
+  omcp plugin verify <dir>     Verify an installed plugin dir against a trust root
+  omcp helm install [release]  helm repo add+update, then install the signed chart
+  omcp helm upgrade [release]  Same, as 'helm upgrade --install'
+  omcp help                    Show this help
+
+Pass extra helm flags after a literal --, e.g.:
+  omcp helm upgrade obs -- -n monitoring --set sources.prometheusUrl=http://prom:9090
+
+Flags:
+  --json                       Machine-readable output (doctor, status, plugin)
+  --from <url|path>            Catalog source (default: local checkout or the public hub)
+  --offline-dir <dir>          Airgapped: read <name>-<ver>.tgz[.sig] + manifest from <dir>
+  --trust-root <pem>           Verify signature+integrity against this PEM (fail-closed)
+  --insecure                   Skip verification (NOT recommended; explicit opt-out)
+  --dest <dir>                 Install target (default: $PLUGINS_DIR or ./plugins)
+  --force                      Overwrite an existing install dir
+`;

package/dist/cli/lib.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/lib.test.js

@@ -0,0 +1,134 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { parseArgs, pickFreePort, composeOverride, resolveCatalogSource, formatPluginList, formatPluginInfo, DEFAULT_CATALOG_URL, } from "./lib.js";
+const CAT = {
+    catalogVersion: 1,
+    connectors: [
+        {
+            name: "prometheus",
+            displayName: "Prometheus",
+            description: "PromQL metrics.",
+            tier: "official",
+            builtin: true,
+            signalTypes: ["metrics"],
+            latest: "1.4.0",
+            versions: [{ version: "1.4.0", releasedAt: "2026-05-15", serverCompat: ">=1.4.0" }],
+        },
+        {
+            name: "tempo",
+            displayName: "Grafana Tempo",
+            description: "TraceQL.",
+            tier: "third-party",
+            signalTypes: ["traces"],
+            versions: [
+                { version: "1.0.0", releasedAt: "2026-05-15", integrity: "sha256-AAAA=", signatureUrl: "https://x/s.sig" },
+            ],
+        },
+    ],
+};
+test("parseArgs: command, sub, positionals", () => {
+    const p = parseArgs(["demo", "up", "extra"]);
+    assert.equal(p.command, "demo");
+    assert.equal(p.sub, "up");
+    assert.deepEqual(p.positionals, ["extra"]);
+});
+test("parseArgs: --flag=val, --flag val, boolean, -f val", () => {
+    const p = parseArgs(["plugin", "install", "loki", "--from=/m", "--ver", "1.2.0", "--json", "-f", "x"]);
+    assert.equal(p.command, "plugin");
+    assert.equal(p.sub, "install");
+    assert.deepEqual(p.positionals, ["loki"]);
+    assert.equal(p.flags.from, "/m");
+    assert.equal(p.flags.ver, "1.2.0");
+    assert.equal(p.flags.json, true);
+    assert.equal(p.flags.f, "x");
+});
+test("parseArgs: empty argv", () => {
+    const p = parseArgs([]);
+    assert.equal(p.command, "");
+    assert.equal(p.sub, undefined);
+});
+test("pickFreePort returns desired when free", () => {
+    assert.equal(pickFreePort(3000, () => false), 3000);
+});
+test("pickFreePort skips used ports", () => {
+    const used = new Set([3000, 3001, 3002]);
+    assert.equal(pickFreePort(3000, (p) => used.has(p)), 3003);
+});
+test("pickFreePort throws when span exhausted", () => {
+    assert.throws(() => pickFreePort(3000, () => true, 5), /no free port/);
+});
+test("composeOverride emits !override port mappings", () => {
+    const y = composeOverride([
+        { service: "mcp-server", host: 3001, container: 3000 },
+        { service: "loki", host: 3101, container: 3100 },
+    ]);
+    assert.match(y, /^services:\n/);
+    assert.match(y, /  mcp-server:\n    ports: !override\n      - "3001:3000"/);
+    assert.match(y, /  loki:\n    ports: !override\n      - "3101:3100"/);
+});
+test("resolveCatalogSource: explicit url, explicit path, local, default", () => {
+    assert.deepEqual(resolveCatalogSource("https://h/x.json", null), { kind: "url", location: "https://h/x.json" });
+    assert.deepEqual(resolveCatalogSource("/tmp/c.json", null), { kind: "file", location: "/tmp/c.json" });
+    assert.deepEqual(resolveCatalogSource(undefined, "/repo/hub/catalog/index.json"), { kind: "file", location: "/repo/hub/catalog/index.json" });
+    assert.deepEqual(resolveCatalogSource(undefined, null), { kind: "url", location: DEFAULT_CATALOG_URL });
+});
+test("formatPluginList: header, sorted rows, builtin+tier flags", () => {
+    const out = formatPluginList(CAT);
+    const lines = out.split("\n");
+    assert.match(lines[0], /^NAME\s+LATEST\s+SIGNALS\s+TIER$/);
+    // sorted: prometheus before tempo
+    assert.ok(lines[1].startsWith("prometheus"));
+    assert.match(lines[1], /builtin,official/);
+    assert.ok(lines[2].startsWith("tempo"));
+    assert.match(lines[2], /third-party/);
+});
+test("formatPluginInfo: versions + integrity/signature surfaced", () => {
+    const info = formatPluginInfo(CAT.connectors[1]);
+    assert.match(info, /Grafana Tempo {2}\(tempo\)/);
+    assert.match(info, /tier: {6}third-party/);
+    assert.match(info, /1\.0\.0 \(2026-05-15\)/);
+    assert.match(info, /integrity: sha256-AAAA=/);
+    assert.match(info, /signature: https:\/\/x\/s\.sig/);
+});
+import { parsePluginRef, resolveInstall } from "./lib.js";
+test("parsePluginRef: name and name@version, rejects junk", () => {
+    assert.deepEqual(parsePluginRef("tempo"), { name: "tempo", version: undefined });
+    assert.deepEqual(parsePluginRef("tempo@1.2.3"), { name: "tempo", version: "1.2.3" });
+    assert.deepEqual(parsePluginRef("x@1.0.0-rc.1"), { name: "x", version: "1.0.0-rc.1" });
+    assert.throws(() => parsePluginRef("Bad Name"), /invalid plugin ref/);
+    assert.throws(() => parsePluginRef("tempo@v1"), /invalid plugin ref/);
+});
+test("resolveInstall: builtin short-circuits", () => {
+    const r = resolveInstall(CAT, "prometheus");
+    assert.equal(r.builtin, true);
+    assert.equal(r.name, "prometheus");
+});
+test("resolveInstall: picks latest then specific version", () => {
+    const def = resolveInstall(CAT, "tempo");
+    assert.equal(def.version, "1.0.0");
+    assert.equal(def.builtin, false);
+    assert.equal(def.integrity, "sha256-AAAA=");
+    const pinned = resolveInstall(CAT, "tempo@1.0.0");
+    assert.equal(pinned.version, "1.0.0");
+    assert.throws(() => resolveInstall(CAT, "tempo@9.9.9"), /not found/);
+    assert.throws(() => resolveInstall(CAT, "ghost"), /no connector/);
+});
+import { splitPassthrough, helmReleaseArgs, HELM_CHART } from "./lib.js";
+test("splitPassthrough: splits at first -- ", () => {
+    assert.deepEqual(splitPassthrough(["helm", "install", "obs"]), {
+        argv: ["helm", "install", "obs"],
+        passthrough: [],
+    });
+    assert.deepEqual(splitPassthrough(["helm", "upgrade", "obs", "--", "-n", "mon", "--set", "a=b"]), { argv: ["helm", "upgrade", "obs"], passthrough: ["-n", "mon", "--set", "a=b"] });
+});
+test("helmReleaseArgs: install vs upgrade --install, passthrough appended", () => {
+    assert.deepEqual(helmReleaseArgs("install", "obs", []), ["install", "obs", HELM_CHART]);
+    assert.deepEqual(helmReleaseArgs("upgrade", "obs", ["-n", "mon"]), [
+        "upgrade",
+        "--install",
+        "obs",
+        HELM_CHART,
+        "-n",
+        "mon",
+    ]);
+});

package/dist/connectors/hub.d.ts

@@ -0,0 +1,48 @@
+import type { LoadedConnector } from "./loader.js";
+export declare const DEFAULT_HUB_CATALOG_URL = "https://thotischner.github.io/observability-mcp/hub/index.json";
+/** Catalog source: env override wins (airgapped mirror / private hub). */
+export declare function resolveHubCatalogUrl(env?: NodeJS.ProcessEnv): string;
+export interface InstalledConnector {
+    name: string;
+    source: "builtin" | "filesystem" | "config";
+    displayName: string;
+    description: string;
+    version: string | null;
+    signalTypes: string[];
+    capabilities: Record<string, boolean>;
+}
+/** Shape the loader's entries into the UI's installed list. */
+export declare function describeInstalled(loaded: LoadedConnector[]): InstalledConnector[];
+export interface CatalogConnector {
+    name: string;
+    displayName: string;
+    description: string;
+    tier: string;
+    builtin?: boolean;
+    signalTypes: string[];
+    latest?: string;
+    versions: Array<{
+        version: string;
+        tarballUrl?: string;
+        integrity?: string;
+        serverCompat?: string;
+        changelog?: string;
+        releasedAt?: string;
+    }>;
+}
+export interface HubCatalogEntry extends CatalogConnector {
+    installed: boolean;
+    installedVersion: string | null;
+}
+/**
+ * Merge the hub catalog with what's installed so the UI can show
+ * status + offer not-yet-installed connectors.
+ */
+export declare function mergeCatalog(catalog: {
+    connectors?: CatalogConnector[];
+} | null, installed: InstalledConnector[]): HubCatalogEntry[];
+/** Fetch + parse the catalog. fetchImpl injected for tests. */
+export declare function fetchHubCatalog(url: string, fetchImpl?: typeof fetch): Promise<{
+    connectors: CatalogConnector[];
+    catalogVersion?: number;
+}>;

package/dist/connectors/hub.js

@@ -0,0 +1,51 @@
+// Connector-hub integration helpers (pure, IO-injectable so they unit
+// test without network). Powers the Web UI "Connectors" page:
+//   - what's installed/loaded right now
+//   - what the hub catalog offers, with an "installed" marker
+export const DEFAULT_HUB_CATALOG_URL = "https://thotischner.github.io/observability-mcp/hub/index.json";
+/** Catalog source: env override wins (airgapped mirror / private hub). */
+export function resolveHubCatalogUrl(env = process.env) {
+    return env.HUB_CATALOG_URL || DEFAULT_HUB_CATALOG_URL;
+}
+/** Shape the loader's entries into the UI's installed list. */
+export function describeInstalled(loaded) {
+    return loaded
+        .map((p) => ({
+        name: p.name,
+        source: p.source,
+        displayName: p.manifest?.displayName ?? p.name,
+        description: p.manifest?.description ?? "",
+        version: p.manifest?.version ?? null,
+        signalTypes: p.manifest?.signalTypes ?? [],
+        capabilities: p.manifest?.capabilities ?? {},
+    }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Merge the hub catalog with what's installed so the UI can show
+ * status + offer not-yet-installed connectors.
+ */
+export function mergeCatalog(catalog, installed) {
+    const byName = new Map(installed.map((i) => [i.name, i]));
+    return (catalog?.connectors ?? [])
+        .map((c) => {
+        const have = byName.get(c.name);
+        return {
+            ...c,
+            installed: !!have,
+            installedVersion: have?.version ?? null,
+        };
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Fetch + parse the catalog. fetchImpl injected for tests. */
+export async function fetchHubCatalog(url, fetchImpl = fetch) {
+    const res = await fetchImpl(url);
+    if (!res.ok)
+        throw new Error(`hub catalog HTTP ${res.status} from ${url}`);
+    const body = (await res.json());
+    if (!body || !Array.isArray(body.connectors)) {
+        throw new Error("hub catalog malformed (no connectors[])");
+    }
+    return { connectors: body.connectors, catalogVersion: body.catalogVersion };
+}

package/dist/connectors/hub.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/connectors/hub.test.js

@@ -0,0 +1,52 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { resolveHubCatalogUrl, describeInstalled, mergeCatalog, fetchHubCatalog, DEFAULT_HUB_CATALOG_URL, } from "./hub.js";
+test("resolveHubCatalogUrl: default + env override", () => {
+    assert.equal(resolveHubCatalogUrl({}), DEFAULT_HUB_CATALOG_URL);
+    assert.equal(resolveHubCatalogUrl({ HUB_CATALOG_URL: "http://mirror/idx.json" }), "http://mirror/idx.json");
+});
+test("describeInstalled maps loader entries, sorts, defaults", () => {
+    const loaded = [
+        { name: "loki", source: "builtin", factory: () => ({}) },
+        {
+            name: "datadog",
+            source: "filesystem",
+            factory: () => ({}),
+            manifest: {
+                displayName: "Datadog",
+                description: "DD",
+                version: "1.0.0",
+                signalTypes: ["metrics", "logs"],
+                capabilities: { queryMetrics: true },
+            },
+        },
+    ];
+    const d = describeInstalled(loaded);
+    assert.deepEqual(d.map((x) => x.name), ["datadog", "loki"]); // sorted
+    assert.equal(d[0].displayName, "Datadog");
+    assert.deepEqual(d[0].signalTypes, ["metrics", "logs"]);
+    assert.equal(d[1].displayName, "loki"); // falls back to name
+    assert.equal(d[1].version, null);
+    assert.deepEqual(d[1].capabilities, {});
+});
+test("mergeCatalog marks installed + version, sorts, tolerates null", () => {
+    const installed = describeInstalled([
+        { name: "datadog", source: "filesystem", factory: () => ({}), manifest: { version: "1.0.0" } },
+    ]);
+    const merged = mergeCatalog({ connectors: [
+            { name: "grafana", displayName: "Grafana", description: "", tier: "official", signalTypes: ["metrics"], versions: [{ version: "1.0.0" }] },
+            { name: "datadog", displayName: "Datadog", description: "", tier: "official", signalTypes: ["metrics"], versions: [{ version: "1.0.0" }] },
+        ] }, installed);
+    assert.deepEqual(merged.map((m) => m.name), ["datadog", "grafana"]);
+    assert.equal(merged[0].installed, true);
+    assert.equal(merged[0].installedVersion, "1.0.0");
+    assert.equal(merged[1].installed, false);
+    assert.deepEqual(mergeCatalog(null, installed), []);
+});
+test("fetchHubCatalog: ok, http error, malformed", async () => {
+    const ok = async () => ({ ok: true, status: 200, json: async () => ({ connectors: [{ name: "x" }], catalogVersion: 1 }) });
+    const r = await fetchHubCatalog("u", ok);
+    assert.equal(r.connectors.length, 1);
+    await assert.rejects(() => fetchHubCatalog("u", (async () => ({ ok: false, status: 503, json: async () => ({}) }))), /HTTP 503/);
+    await assert.rejects(() => fetchHubCatalog("u", (async () => ({ ok: true, status: 200, json: async () => ({}) }))), /malformed/);
+});

package/dist/connectors/install.d.ts

@@ -0,0 +1,24 @@
+/** A connector name is safe iff kebab-case ASCII (also blocks traversal). */
+export declare function isValidConnectorName(name: unknown): name is string;
+/**
+ * Resolve the install target and guarantee it stays directly inside
+ * pluginsDir (defence-in-depth against `..`/absolute names even though
+ * isValidConnectorName already rejects them).
+ */
+export declare function safeTarget(pluginsDir: string, name: string): string;
+export interface InstallResult {
+    name: string;
+    version: string | null;
+}
+/**
+ * Install a connector tarball into pluginsDir, fail-closed. Always
+ * verifies the manifest signature + entry integrity against trustRoot
+ * — there is intentionally NO insecure bypass on this path (it's
+ * reachable over HTTP). Throws PluginVerificationError on any failure.
+ */
+export declare function installTarball(opts: {
+    tgzPath: string;
+    pluginsDir: string;
+    trustRootPath: string;
+    expectedName?: string;
+}): InstallResult;

package/dist/connectors/install.js

@@ -0,0 +1,100 @@
+// Shared connector-install core: extract a tarball, verify it
+// fail-closed against a trust root (the SAME crypto as the server
+// loader / omcp CLI — verify.ts), then atomically place it under
+// PLUGINS_DIR. Used by the Web UI install API (and reusable by the
+// CLI). Pure guards are split out for unit testing.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync, statSync, mkdtempSync, mkdirSync, rmSync, cpSync, } from "node:fs";
+import { join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+import { loadTrustRoot, verifyIntegrity, verifyManifestSignature, PluginVerificationError, } from "./verify.js";
+const NAME_RE = /^[a-z][a-z0-9-]*$/;
+/** A connector name is safe iff kebab-case ASCII (also blocks traversal). */
+export function isValidConnectorName(name) {
+    return typeof name === "string" && NAME_RE.test(name);
+}
+/**
+ * Resolve the install target and guarantee it stays directly inside
+ * pluginsDir (defence-in-depth against `..`/absolute names even though
+ * isValidConnectorName already rejects them).
+ */
+export function safeTarget(pluginsDir, name) {
+    if (!isValidConnectorName(name))
+        throw new Error(`invalid connector name: ${String(name)}`);
+    const base = resolve(pluginsDir);
+    const target = resolve(base, name);
+    if (target !== join(base, name) || !target.startsWith(base + "/")) {
+        throw new Error("refusing path outside PLUGINS_DIR");
+    }
+    return target;
+}
+function tarExtract(tgz, dest) {
+    const r = spawnSync("tar", ["-xzf", tgz, "-C", dest], { stdio: "pipe" });
+    if (r.status !== 0)
+        throw new Error(`tar extraction failed: ${r.stderr?.toString() || r.status}`);
+}
+function findPluginRoot(base) {
+    for (const dir of [base, ...readdirSync(base).map((e) => join(base, e))]) {
+        try {
+            if (!statSync(dir).isDirectory())
+                continue;
+            const pkgPath = join(dir, "package.json");
+            if (!existsSync(pkgPath))
+                continue;
+            if (JSON.parse(readFileSync(pkgPath, "utf8")).observabilityMcp?.kind === "connector")
+                return dir;
+        }
+        catch {
+            /* skip */
+        }
+    }
+    return null;
+}
+/**
+ * Install a connector tarball into pluginsDir, fail-closed. Always
+ * verifies the manifest signature + entry integrity against trustRoot
+ * — there is intentionally NO insecure bypass on this path (it's
+ * reachable over HTTP). Throws PluginVerificationError on any failure.
+ */
+export function installTarball(opts) {
+    const trustRoot = loadTrustRoot(opts.trustRootPath); // throws if unreadable/bad
+    const work = mkdtempSync(join(tmpdir(), "obsmcp-install-"));
+    try {
+        const stage = join(work, "stage");
+        mkdirSync(stage);
+        tarExtract(opts.tgzPath, stage);
+        const root = findPluginRoot(stage);
+        if (!root)
+            throw new PluginVerificationError("tarball has no connector package.json marker");
+        const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+        const marker = pkg.observabilityMcp;
+        const name = marker?.name;
+        if (!isValidConnectorName(name))
+            throw new PluginVerificationError(`invalid connector name in package: ${String(name)}`);
+        if (opts.expectedName && opts.expectedName !== name) {
+            throw new PluginVerificationError(`tarball is '${name}', expected '${opts.expectedName}'`);
+        }
+        const manifestRel = marker.manifest || "./manifest.json";
+        const manifestPath = resolve(root, manifestRel);
+        if (!existsSync(manifestPath))
+            throw new PluginVerificationError(`manifest not found: ${manifestRel}`);
+        const sigPath = manifestPath + ".sig";
+        if (!existsSync(sigPath))
+            throw new PluginVerificationError(`missing manifest signature: ${manifestRel}.sig`);
+        const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+        const entryPath = resolve(root, pkg.main || "index.js");
+        // Fail-closed: signature over the manifest + manifest pins the
+        // entry hash. Throws PluginVerificationError on mismatch.
+        verifyManifestSignature(readFileSync(manifestPath), readFileSync(sigPath), trustRoot);
+        verifyIntegrity(entryPath, manifest.integrity);
+        const target = safeTarget(opts.pluginsDir, name);
+        mkdirSync(opts.pluginsDir, { recursive: true });
+        if (existsSync(target))
+            rmSync(target, { recursive: true, force: true });
+        cpSync(root, target, { recursive: true });
+        return { name, version: manifest.version ?? null };
+    }
+    finally {
+        rmSync(work, { recursive: true, force: true });
+    }
+}

package/dist/connectors/install.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/connectors/install.test.js

@@ -0,0 +1,58 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { generateKeyPairSync, sign as edSign, createHash } from "node:crypto";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { isValidConnectorName, safeTarget, installTarball } from "./install.js";
+import { PluginVerificationError } from "./verify.js";
+test("isValidConnectorName: kebab only, blocks traversal", () => {
+    assert.ok(isValidConnectorName("datadog"));
+    assert.ok(isValidConnectorName("my-connector9"));
+    for (const bad of ["../evil", "Foo", "a/b", "", "1abc", "a_b", null, 42]) {
+        assert.equal(isValidConnectorName(bad), false);
+    }
+});
+test("safeTarget keeps the path inside pluginsDir", () => {
+    const t = safeTarget("/plugins", "datadog");
+    assert.equal(t, "/plugins/datadog");
+    assert.throws(() => safeTarget("/plugins", "../etc"), /invalid connector name|outside/);
+});
+function mkSignedTarball(dir, name, priv, opts = {}) {
+    const src = join(dir, "src");
+    mkdirSync(src, { recursive: true });
+    writeFileSync(join(src, "index.js"), "export default () => ({});\n");
+    const integ = "sha256-" + createHash("sha256").update(readFileSync(join(src, "index.js"))).digest("base64");
+    const manifest = { schemaVersion: 1, name, displayName: name, version: "1.0.0", description: "x", signalTypes: ["metrics"], integrity: integ };
+    const mb = Buffer.from(JSON.stringify(manifest));
+    writeFileSync(join(src, "manifest.json"), mb);
+    if (!opts.noSig)
+        writeFileSync(join(src, "manifest.json.sig"), edSign(null, mb, priv));
+    writeFileSync(join(src, "package.json"), JSON.stringify({ name, main: "index.js", observabilityMcp: { kind: "connector", name, manifest: "./manifest.json" } }));
+    if (opts.tamper)
+        writeFileSync(join(src, "index.js"), "export default () => ({}); /* tampered */\n");
+    const tgz = join(dir, `${name}-1.0.0.tgz`);
+    const r = spawnSync("tar", ["-czf", tgz, "-C", src, "."]);
+    assert.equal(r.status, 0, "tar failed in test setup");
+    return tgz;
+}
+test("installTarball: verifies + installs; rejects tamper / missing sig / wrong name", () => {
+    const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+    const work = mkdtempSync(join(tmpdir(), "it-"));
+    const pub = join(work, "pub.pem");
+    writeFileSync(pub, publicKey.export({ type: "spki", format: "pem" }));
+    const pluginsDir = join(work, "plugins");
+    const good = mkSignedTarball(join(work, "good"), "datadog", privateKey);
+    const r = installTarball({ tgzPath: good, pluginsDir, trustRootPath: pub });
+    assert.equal(r.name, "datadog");
+    assert.equal(r.version, "1.0.0");
+    assert.ok(existsSync(join(pluginsDir, "datadog", "manifest.json")));
+    const tampered = mkSignedTarball(join(work, "bad"), "datadog", privateKey, { tamper: true });
+    assert.throws(() => installTarball({ tgzPath: tampered, pluginsDir, trustRootPath: pub }), PluginVerificationError);
+    const noSig = mkSignedTarball(join(work, "nosig"), "datadog", privateKey, { noSig: true });
+    assert.throws(() => installTarball({ tgzPath: noSig, pluginsDir, trustRootPath: pub }), /missing manifest signature/);
+    const other = mkSignedTarball(join(work, "other"), "grafana", privateKey);
+    assert.throws(() => installTarball({ tgzPath: other, pluginsDir, trustRootPath: pub, expectedName: "datadog" }), /expected 'datadog'/);
+});