@thotischner/observability-mcp 1.4.0 → 1.4.1

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'/);
+});

package/dist/connectors/loader.d.ts

@@ -23,9 +23,14 @@ export declare class PluginLoader {
     private connectors;
     private pluginsDir;
     private disabled;
+    private verify;
+    private trustRootPath?;
+    private trustRoot?;
     constructor(opts?: {
         pluginsDir?: string;
         disabled?: string[];
+        verify?: boolean;
+        trustRoot?: string;
     });
     load(): Promise<void>;
     list(): LoadedConnector[];

package/dist/connectors/loader.js

@@ -6,6 +6,7 @@ import { PrometheusConnector } from "./prometheus.js";
 import { LokiConnector } from "./loki.js";
 import { sanitizeForLog } from "../util/sanitize.js";
 import { instrumentConnector } from "../metrics/instrument-connector.js";
+import { loadTrustRoot, verifyIntegrity, verifyManifestSignature, PluginVerificationError, } from "./verify.js";
 /**
  * Resolves which connector implementations the server should know about,
  * applying three sources in order (later overrides earlier):
@@ -20,6 +21,13 @@ export class PluginLoader {
     connectors = new Map();
     pluginsDir;
     disabled;
+    // Fail-closed verification for filesystem plugins. Builtins are part
+    // of the trusted image and are never gated. Default off so existing
+    // deployments are unchanged; recommended on in prod/airgapped (the
+    // Helm chart sets it).
+    verify;
+    trustRootPath;
+    trustRoot;
     constructor(opts = {}) {
         this.pluginsDir = opts.pluginsDir
             ?? process.env.PLUGINS_DIR
@@ -30,9 +38,25 @@ export class PluginLoader {
             .map((s) => s.trim())
             .filter(Boolean);
         this.disabled = new Set([...(opts.disabled ?? []), ...envDisabled]);
+        this.verify = opts.verify ?? /^(1|true|yes)$/i.test(process.env.VERIFY_PLUGINS ?? "");
+        this.trustRootPath = opts.trustRoot ?? process.env.PLUGIN_TRUST_ROOT;
     }
     async load() {
         this.loadBuiltins();
+        if (this.verify) {
+            if (!this.trustRootPath) {
+                console.warn("VERIFY_PLUGINS is on but PLUGIN_TRUST_ROOT is unset — refusing to load any filesystem plugins (fail-closed). Builtins remain available.");
+                return;
+            }
+            try {
+                this.trustRoot = loadTrustRoot(this.trustRootPath);
+                console.log("Plugin verification enabled; trust root loaded from %s", sanitizeForLog(this.trustRootPath));
+            }
+            catch (err) {
+                console.warn("VERIFY_PLUGINS is on but trust root failed to load (%s) — refusing to load any filesystem plugins (fail-closed). Builtins remain available.", sanitizeForLog(String(err)));
+                return;
+            }
+        }
         await this.loadFilesystem();
     }
     list() {
@@ -105,10 +129,13 @@ export class PluginLoader {
         if (!marker || marker.kind !== "connector" || !marker.name)
             return;
         let manifest;
+        let manifestPath;
+        let manifestBytes;
         if (marker.manifest) {
-            const manifestPath = resolve(pluginRoot, marker.manifest);
+            manifestPath = resolve(pluginRoot, marker.manifest);
             if (existsSync(manifestPath)) {
-                const raw = JSON.parse(readFileSync(manifestPath, "utf8"));
+                manifestBytes = readFileSync(manifestPath);
+                const raw = JSON.parse(manifestBytes.toString("utf8"));
                 const parsed = manifestSchema.safeParse(raw);
                 if (!parsed.success) {
                     const issues = parsed.error.issues
@@ -130,6 +157,31 @@ export class PluginLoader {
             console.warn("Plugin %s missing entry file %s", sanitizeForLog(marker.name), sanitizeForLog(entryFile));
             return;
         }
+        // Fail-closed verification gate. A plugin only loads under
+        // VERIFY_PLUGINS if it ships a manifest whose `integrity` matches
+        // the entry file AND a detached `<manifest>.sig` that verifies
+        // against the trust root. Everything is local — airgapped-safe.
+        if (this.verify) {
+            if (!manifest || !manifestPath || !manifestBytes) {
+                console.warn("VERIFY_PLUGINS: plugin %s has no manifest.json — skipping (fail-closed)", sanitizeForLog(marker.name));
+                return;
+            }
+            const sigPath = manifestPath + ".sig";
+            if (!existsSync(sigPath)) {
+                console.warn("VERIFY_PLUGINS: plugin %s missing manifest signature %s — skipping (fail-closed)", sanitizeForLog(marker.name), sanitizeForLog(marker.manifest + ".sig"));
+                return;
+            }
+            try {
+                verifyManifestSignature(manifestBytes, readFileSync(sigPath), this.trustRoot);
+                verifyIntegrity(entryPath, manifest.integrity);
+            }
+            catch (err) {
+                const detail = err instanceof PluginVerificationError ? err.message : String(err);
+                console.warn("VERIFY_PLUGINS: plugin %s failed verification (%s) — skipping (fail-closed)", sanitizeForLog(marker.name), sanitizeForLog(detail));
+                return;
+            }
+            console.log("VERIFY_PLUGINS: plugin %s signature + integrity OK", sanitizeForLog(marker.name));
+        }
         const mod = await import(pathToFileURL(entryPath).href);
         const factory = mod.default ?? mod.createConnector;
         if (typeof factory !== "function") {

package/dist/connectors/loki.js

@@ -54,13 +54,19 @@ export class LokiConnector {
     }
     async disconnect() { }
     async listServices() {
-        // Probe each candidate label and merge values. Loki streams may identify
-        // services via service_name, service, job, app, or container depending on
-        // the shipper configuration. Walking all candidates ensures historical
-        // streams remain reachable when label conventions change over time.
+        // Candidate labels are ordered by preference (service_name, service,
+        // job, app, container). The FIRST label that yields any values wins —
+        // we do not union across labels. Unioning duplicated every service:
+        // one real container is simultaneously `service="api-gateway"` and
+        // `container="myproj-api-gateway-1"`, and a co-located shipper can add
+        // unrelated `container` values (e.g. other compose/k8s containers on
+        // the same Docker host). The ordered fallback still keeps streams
+        // reachable on backends that only carry a low-priority label.
         const seen = new Map();
         for (const label of this.serviceLabels) {
             const values = await this.getLabelValues(label);
+            if (values.length === 0)
+                continue;
             for (const raw of values) {
                 // Docker's loki.source.docker writes container names with a leading '/'
                 // (Docker API Names[0] convention). Strip it for display so the name
@@ -75,6 +81,7 @@ export class LokiConnector {
                     });
                 }
             }
+            break; // first non-empty label is authoritative
         }
         return Array.from(seen.values());
     }

package/dist/connectors/loki.test.js

@@ -108,4 +108,31 @@ describe("LokiConnector", () => {
             assert.equal(proto.escapeLogQLRegex("error`test`"), "error\\`test\\`");
         });
     });
+    describe("listServices", () => {
+        function withLabelValues(map) {
+            const c = new LokiConnector();
+            c.serviceLabels = ["service_name", "service", "job", "app", "container"];
+            c.getLabelValues = async (label) => map[label] ?? [];
+            return c;
+        }
+        it("first non-empty label wins — does NOT union container aliases", async () => {
+            const c = withLabelValues({
+                service: ["api-gateway", "payment-service"],
+                // co-located shipper noise that must NOT leak in:
+                container: ["myproj-api-gateway-1", "k8s_POD_api-gateway_demo_x"],
+            });
+            const names = (await c.listServices()).map((s) => s.name).sort();
+            assert.deepEqual(names, ["api-gateway", "payment-service"]);
+        });
+        it("falls back to a lower-priority label only when higher ones are empty", async () => {
+            const c = withLabelValues({ container: ["/svc-a", "/svc-b"] });
+            const svcs = await c.listServices();
+            assert.deepEqual(svcs.map((s) => s.name).sort(), ["svc-a", "svc-b"]);
+            assert.equal(svcs[0].labels.discoveredVia, "container");
+        });
+        it("returns empty when no candidate label has values", async () => {
+            const c = withLabelValues({});
+            assert.deepEqual(await c.listServices(), []);
+        });
+    });
 });