@thotischner/observability-mcp 1.4.0 → 1.5.1

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(), []);
+        });
+    });
 });

package/dist/connectors/verify.d.ts

@@ -0,0 +1,19 @@
+import { type KeyObject } from "node:crypto";
+export declare class PluginVerificationError extends Error {
+}
+/** Parse a PEM public key into a KeyObject. Throws PluginVerificationError. */
+export declare function loadTrustRoot(pemPath: string): KeyObject;
+/** "sha256-<base64>" digest of a buffer, matching the manifest `integrity` form. */
+export declare function sha256Integrity(data: Buffer): string;
+/**
+ * Constant-time-ish compare of the entry file against the manifest's
+ * declared integrity digest. Throws on mismatch.
+ */
+export declare function verifyIntegrity(entryPath: string, integrity: string | undefined): void;
+/**
+ * Verify a detached signature over the raw manifest bytes against the
+ * trust root. Signature is read as base64 (whitespace tolerated, e.g. a
+ * `manifest.json.sig` produced by `openssl dgst -sign ... | base64`).
+ * Throws PluginVerificationError if the signature does not verify.
+ */
+export declare function verifyManifestSignature(manifestBytes: Buffer, signatureBytes: Buffer, trustRoot: KeyObject): void;

package/dist/connectors/verify.js

@@ -0,0 +1,87 @@
+import { createHash, createPublicKey, verify as cryptoVerify } from "node:crypto";
+import { readFileSync } from "node:fs";
+// Airgapped-friendly plugin verification.
+//
+// No network, no external binary (no cosign): a plugin is trusted when
+//   1. its entry file hashes to the manifest's `integrity` digest, and
+//   2. the manifest bytes carry a detached signature that verifies
+//      against a locally-configured trust-root public key.
+//
+// Ed25519 and RSA/EC (PKCS#8 / SPKI PEM) trust roots are supported.
+export class PluginVerificationError extends Error {
+}
+/** Parse a PEM public key into a KeyObject. Throws PluginVerificationError. */
+export function loadTrustRoot(pemPath) {
+    let pem;
+    try {
+        pem = readFileSync(pemPath, "utf8");
+    }
+    catch (err) {
+        throw new PluginVerificationError(`trust root unreadable at ${pemPath}: ${String(err)}`);
+    }
+    try {
+        return createPublicKey(pem);
+    }
+    catch (err) {
+        throw new PluginVerificationError(`trust root is not a valid PEM public key: ${String(err)}`);
+    }
+}
+/** "sha256-<base64>" digest of a buffer, matching the manifest `integrity` form. */
+export function sha256Integrity(data) {
+    return "sha256-" + createHash("sha256").update(data).digest("base64");
+}
+/**
+ * Constant-time-ish compare of the entry file against the manifest's
+ * declared integrity digest. Throws on mismatch.
+ */
+export function verifyIntegrity(entryPath, integrity) {
+    if (!integrity) {
+        throw new PluginVerificationError("manifest has no integrity digest");
+    }
+    let bytes;
+    try {
+        bytes = readFileSync(entryPath);
+    }
+    catch (err) {
+        throw new PluginVerificationError(`entry file unreadable: ${String(err)}`);
+    }
+    const actual = sha256Integrity(bytes);
+    if (actual.length !== integrity.length || actual !== integrity) {
+        throw new PluginVerificationError(`entry file integrity mismatch (manifest=${integrity} actual=${actual})`);
+    }
+}
+/**
+ * Verify a detached signature over the raw manifest bytes against the
+ * trust root. Signature is read as base64 (whitespace tolerated, e.g. a
+ * `manifest.json.sig` produced by `openssl dgst -sign ... | base64`).
+ * Throws PluginVerificationError if the signature does not verify.
+ */
+export function verifyManifestSignature(manifestBytes, signatureBytes, trustRoot) {
+    const sig = decodeSignature(signatureBytes);
+    // Ed25519/Ed448 take algorithm=null; RSA/EC sign over a SHA-256 digest.
+    const keyType = trustRoot.asymmetricKeyType;
+    const algorithm = keyType === "ed25519" || keyType === "ed448" ? null : "sha256";
+    let ok = false;
+    try {
+        ok = cryptoVerify(algorithm, manifestBytes, trustRoot, sig);
+    }
+    catch (err) {
+        throw new PluginVerificationError(`signature verification errored: ${String(err)}`);
+    }
+    if (!ok) {
+        throw new PluginVerificationError("manifest signature does not match trust root");
+    }
+}
+// Accept either raw DER bytes or a base64/armored .sig file.
+function decodeSignature(raw) {
+    const text = raw.toString("utf8").trim();
+    if (/^[A-Za-z0-9+/\s=]+$/.test(text) && text.length > 0) {
+        const compact = text.replace(/\s+/g, "");
+        const b = Buffer.from(compact, "base64");
+        // Round-trip check: if it re-encodes cleanly it was really base64.
+        if (b.length > 0 && b.toString("base64").replace(/=+$/, "") === compact.replace(/=+$/, "")) {
+            return b;
+        }
+    }
+    return raw;
+}

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

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

package/dist/connectors/verify.test.js

@@ -0,0 +1,63 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { generateKeyPairSync, sign as cryptoSign, createPublicKey } from "node:crypto";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { sha256Integrity, verifyIntegrity, verifyManifestSignature, loadTrustRoot, PluginVerificationError, } from "./verify.js";
+function tmp() {
+    return mkdtempSync(join(tmpdir(), "verify-"));
+}
+test("sha256Integrity produces sha256-<base64> and round-trips", () => {
+    const digest = sha256Integrity(Buffer.from("hello"));
+    assert.match(digest, /^sha256-[A-Za-z0-9+/]+=*$/);
+    assert.equal(sha256Integrity(Buffer.from("hello")), digest);
+    assert.notEqual(sha256Integrity(Buffer.from("hellp")), digest);
+});
+test("verifyIntegrity passes on match, throws on mismatch and missing", () => {
+    const dir = tmp();
+    const entry = join(dir, "index.js");
+    writeFileSync(entry, "export default () => ({});\n");
+    const good = sha256Integrity(Buffer.from("export default () => ({});\n"));
+    assert.doesNotThrow(() => verifyIntegrity(entry, good));
+    assert.throws(() => verifyIntegrity(entry, "sha256-AAAA"), PluginVerificationError);
+    assert.throws(() => verifyIntegrity(entry, undefined), PluginVerificationError);
+    assert.throws(() => verifyIntegrity(join(dir, "nope.js"), good), PluginVerificationError);
+});
+test("Ed25519: valid signature verifies, tampered manifest is rejected", () => {
+    const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+    const manifest = Buffer.from('{"name":"prometheus","schemaVersion":1}');
+    const sig = cryptoSign(null, manifest, privateKey);
+    assert.doesNotThrow(() => verifyManifestSignature(manifest, sig, publicKey));
+    // base64-armored signature (the form `openssl ... | base64` emits)
+    const armored = Buffer.from(sig.toString("base64"));
+    assert.doesNotThrow(() => verifyManifestSignature(manifest, armored, publicKey));
+    // tampered bytes
+    assert.throws(() => verifyManifestSignature(Buffer.from('{"name":"evil"}'), sig, publicKey), PluginVerificationError);
+});
+test("RSA trust root path (algorithm=sha256) verifies", () => {
+    const { publicKey, privateKey } = generateKeyPairSync("rsa", { modulusLength: 2048 });
+    const manifest = Buffer.from('{"name":"loki"}');
+    const sig = cryptoSign("sha256", manifest, privateKey);
+    assert.doesNotThrow(() => verifyManifestSignature(manifest, sig, publicKey));
+});
+test("signature from a different key is rejected", () => {
+    const a = generateKeyPairSync("ed25519");
+    const b = generateKeyPairSync("ed25519");
+    const manifest = Buffer.from("payload");
+    const sig = cryptoSign(null, manifest, a.privateKey);
+    assert.throws(() => verifyManifestSignature(manifest, sig, b.publicKey), PluginVerificationError);
+});
+test("loadTrustRoot parses PEM and rejects garbage", () => {
+    const dir = tmp();
+    const { publicKey } = generateKeyPairSync("ed25519");
+    const pem = publicKey.export({ type: "spki", format: "pem" });
+    const p = join(dir, "trust.pem");
+    writeFileSync(p, pem);
+    const loaded = loadTrustRoot(p);
+    assert.equal(loaded.export({ type: "spki", format: "pem" }), createPublicKey(pem).export({ type: "spki", format: "pem" }));
+    const bad = join(dir, "bad.pem");
+    writeFileSync(bad, "not a key");
+    assert.throws(() => loadTrustRoot(bad), PluginVerificationError);
+    assert.throws(() => loadTrustRoot(join(dir, "missing.pem")), PluginVerificationError);
+});

package/dist/context.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Request-scoped context threaded from the transport boundary (HTTP `/mcp`,
+ * stdio, and the internal REST/dashboard call sites) into every tool handler.
+ *
+ * Today it carries only an anonymous principal and a correlation id — it is a
+ * deliberate pass-through that does not change behaviour. It is the single
+ * seam that later access-control / scoping / audit work attaches to, so those
+ * features become additive rather than a cross-cutting rewrite.
+ */
+export interface RequestContext {
+    /** Stable id for the calling principal. "anonymous" when no auth configured. */
+    principalId: string;
+    /** How the principal was authenticated. */
+    auth: "anonymous" | "apikey";
+    /**
+     * Coarse per-credential source allow-list (single-tenant primitive). When
+     * set, the principal may only target these source names. Rich role-based
+     * scoping (tools/services/lookback/read-only) is a separate concern.
+     */
+    allowedSources?: string[];
+    /** Correlates all tool calls within one transport request/session. */
+    correlationId: string;
+}
+/** Default all-access anonymous context — preserves current behaviour. */
+export declare function defaultContext(): RequestContext;
+/** Context for an authenticated API-key principal. */
+export declare function principalContext(principalId: string, allowedSources?: string[]): RequestContext;

package/dist/context.js

@@ -0,0 +1,18 @@
+import { randomUUID } from "node:crypto";
+/** Default all-access anonymous context — preserves current behaviour. */
+export function defaultContext() {
+    return {
+        principalId: "anonymous",
+        auth: "anonymous",
+        correlationId: randomUUID(),
+    };
+}
+/** Context for an authenticated API-key principal. */
+export function principalContext(principalId, allowedSources) {
+    return {
+        principalId,
+        auth: "apikey",
+        allowedSources: allowedSources && allowedSources.length > 0 ? allowedSources : undefined,
+        correlationId: randomUUID(),
+    };
+}