@thotischner/observability-mcp 1.5.1 → 1.7.0

package/dist/connectors/kubernetes.js

@@ -0,0 +1,185 @@
+import { TopologyStore, podResource, podEdges, nodeResource, deploymentResource, deploymentEdges, replicaSetResource, replicaSetEdges, namespaceResource, namespacedId, clusterScopedId, } from "./kubernetes-graph.js";
+// Default provider is loaded lazily so tests don't pay the
+// @kubernetes/client-node import cost (and so the module is usable in
+// environments where the SDK isn't installed yet — e.g. unit tests in CI
+// before the dep lands).
+let defaultProvider;
+export function setDefaultInformerFactoryProvider(p) {
+    defaultProvider = p;
+}
+async function loadDefaultProvider() {
+    if (defaultProvider)
+        return defaultProvider;
+    const mod = await import("./kubernetes-client.js");
+    defaultProvider = mod.createInformerFactory;
+    return defaultProvider;
+}
+export class KubernetesConnector {
+    type = "kubernetes";
+    signalType = "topology";
+    name = "";
+    store;
+    factory;
+    informers = [];
+    providerOverride;
+    /** Constructor injection used by tests. */
+    constructor(provider) {
+        this.providerOverride = provider;
+    }
+    async connect(config) {
+        this.name = config.name;
+        this.store = new TopologyStore(config.name);
+        const provider = this.providerOverride ?? (await loadDefaultProvider());
+        this.factory = await provider(config);
+        // Wire each informer to the store. Pure builders translate Kube
+        // objects → Resource/Edge; the store dedupes and emits diffs.
+        const pods = this.factory.pods();
+        pods.on("add", (p) => this.applyPod(p));
+        pods.on("update", (p) => this.applyPod(p));
+        pods.on("delete", (p) => {
+            const id = idOfPod(p);
+            if (id)
+                this.store.removeResource(id);
+        });
+        pods.on("error", (err) => logWatchError(this.name, "pods", err));
+        const nodes = this.factory.nodes();
+        nodes.on("add", (n) => this.applyNode(n));
+        nodes.on("update", (n) => this.applyNode(n));
+        nodes.on("delete", (n) => {
+            const id = idOfNode(n);
+            if (id)
+                this.store.removeResource(id);
+        });
+        nodes.on("error", (err) => logWatchError(this.name, "nodes", err));
+        const deps = this.factory.deployments();
+        deps.on("add", (d) => this.applyDeployment(d));
+        deps.on("update", (d) => this.applyDeployment(d));
+        deps.on("delete", (d) => {
+            const id = idOfNamespaced("deployment", d);
+            if (id)
+                this.store.removeResource(id);
+        });
+        deps.on("error", (err) => logWatchError(this.name, "deployments", err));
+        const rs = this.factory.replicaSets();
+        rs.on("add", (r) => this.applyReplicaSet(r));
+        rs.on("update", (r) => this.applyReplicaSet(r));
+        rs.on("delete", (r) => {
+            const id = idOfNamespaced("replicaset", r);
+            if (id)
+                this.store.removeResource(id);
+        });
+        rs.on("error", (err) => logWatchError(this.name, "replicasets", err));
+        const ns = this.factory.namespaces();
+        ns.on("add", (n) => this.applyNamespace(n));
+        ns.on("update", (n) => this.applyNamespace(n));
+        ns.on("delete", (n) => {
+            const name = n.metadata?.name;
+            if (name)
+                this.store.removeResource(clusterScopedId("namespace", name));
+        });
+        ns.on("error", (err) => logWatchError(this.name, "namespaces", err));
+        this.informers = [pods, nodes, deps, rs, ns];
+        await Promise.all(this.informers.map((i) => i.start()));
+    }
+    applyPod(p) {
+        const r = podResource(this.name, p);
+        if (!r)
+            return;
+        this.store.upsertResource(r, podEdges(this.name, p));
+    }
+    applyNode(n) {
+        const r = nodeResource(this.name, n);
+        if (!r)
+            return;
+        this.store.upsertResource(r, []);
+    }
+    applyDeployment(d) {
+        const r = deploymentResource(this.name, d);
+        if (!r)
+            return;
+        this.store.upsertResource(r, deploymentEdges(this.name, d));
+    }
+    applyReplicaSet(rs) {
+        const r = replicaSetResource(this.name, rs);
+        if (!r)
+            return;
+        this.store.upsertResource(r, replicaSetEdges(this.name, rs));
+    }
+    applyNamespace(n) {
+        const r = namespaceResource(this.name, n);
+        if (!r)
+            return;
+        this.store.upsertResource(r, []);
+    }
+    async healthCheck() {
+        if (!this.factory)
+            return { status: "down", latencyMs: 0, message: "not connected" };
+        const r = await this.factory.healthCheck();
+        return { status: r.ok ? "up" : "down", latencyMs: r.latencyMs, message: r.message };
+    }
+    async disconnect() {
+        await Promise.all(this.informers.map((i) => i.stop().catch(() => { })));
+        this.informers = [];
+        await this.factory?.close().catch(() => { });
+        this.factory = undefined;
+    }
+    // Topology has no metric/service surface — these stay empty/inert.
+    getDefaultMetrics() {
+        return [];
+    }
+    getMetrics() {
+        return [];
+    }
+    async listServices() {
+        return [];
+    }
+    // --- Topology capability ---
+    async listResources() {
+        return this.store?.listResources() ?? [];
+    }
+    async listEdges() {
+        return this.store?.listEdges() ?? [];
+    }
+    async getTopologySnapshot() {
+        return (this.store?.snapshot() ?? {
+            source: this.name,
+            resources: [],
+            edges: [],
+            revision: 0,
+        });
+    }
+    watchTopology(listener) {
+        if (!this.store)
+            return () => { };
+        // Initial resync so subscribers see the current state without
+        // racing the next watch event.
+        queueMicrotask(() => listener({ type: "resync", snapshot: this.store.snapshot() }));
+        return this.store.subscribe(listener);
+    }
+}
+// --- helpers ---
+function idOfPod(p) {
+    const n = p.metadata?.name;
+    const ns = p.metadata?.namespace;
+    if (!n || !ns)
+        return undefined;
+    return namespacedId("pod", ns, n);
+}
+function idOfNode(n) {
+    return n.metadata?.name ? clusterScopedId("node", n.metadata.name) : undefined;
+}
+function idOfNamespaced(kind, obj) {
+    const n = obj.metadata?.name;
+    const ns = obj.metadata?.namespace;
+    if (!n || !ns)
+        return undefined;
+    return namespacedId(kind, ns, n);
+}
+function logWatchError(source, kind, err) {
+    // AbortError is what makeInformer emits when we cleanly stop the watch
+    // (disconnect, process shutdown) — not actually an error to surface.
+    const msg = String(err);
+    if (msg.includes("AbortError") || /aborted a request/i.test(msg))
+        return;
+    console.warn("k8s watch error: source=%s kind=%s err=%s", source, kind, msg);
+}

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

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

package/dist/connectors/kubernetes.test.js

@@ -0,0 +1,136 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { KubernetesConnector } from "./kubernetes.js";
+import { isTopologyProvider } from "./interface.js";
+class FakeInformer {
+    handlers = {};
+    started = false;
+    stopped = false;
+    on(event, handler) {
+        (this.handlers[event] ??= []).push(handler);
+    }
+    async start() {
+        this.started = true;
+    }
+    async stop() {
+        this.stopped = true;
+    }
+    emit(event, obj) {
+        for (const h of this.handlers[event] ?? [])
+            h(obj);
+    }
+}
+function makeFakeFactory() {
+    const pods = new FakeInformer();
+    const nodes = new FakeInformer();
+    const deps = new FakeInformer();
+    const rs = new FakeInformer();
+    const ns = new FakeInformer();
+    const factory = {
+        pods: () => pods,
+        nodes: () => nodes,
+        deployments: () => deps,
+        replicaSets: () => rs,
+        namespaces: () => ns,
+        async healthCheck() {
+            return { ok: true, latencyMs: 1 };
+        },
+        async close() { },
+    };
+    return { factory, pods, nodes, deps, rs, ns };
+}
+const CFG = {
+    name: "test-cluster",
+    type: "kubernetes",
+    url: "",
+    enabled: true,
+};
+describe("KubernetesConnector", () => {
+    it("implements the TopologyProvider capability", async () => {
+        const { factory } = makeFakeFactory();
+        const conn = new KubernetesConnector(async () => factory);
+        await conn.connect(CFG);
+        assert.equal(isTopologyProvider(conn), true);
+        assert.equal(conn.signalType, "topology");
+        await conn.disconnect();
+    });
+    it("starts every informer on connect and stops them on disconnect", async () => {
+        const fake = makeFakeFactory();
+        const conn = new KubernetesConnector(async () => fake.factory);
+        await conn.connect(CFG);
+        for (const inf of [fake.pods, fake.nodes, fake.deps, fake.rs, fake.ns]) {
+            assert.equal(inf.started, true);
+        }
+        await conn.disconnect();
+        for (const inf of [fake.pods, fake.nodes, fake.deps, fake.rs, fake.ns]) {
+            assert.equal(inf.stopped, true);
+        }
+    });
+    it("builds the graph from watch events", async () => {
+        const fake = makeFakeFactory();
+        const conn = new KubernetesConnector(async () => fake.factory);
+        await conn.connect(CFG);
+        fake.nodes.emit("add", { metadata: { name: "worker-1" } });
+        fake.ns.emit("add", { metadata: { name: "default" } });
+        fake.deps.emit("add", { metadata: { name: "checkout", namespace: "default" } });
+        fake.rs.emit("add", {
+            metadata: {
+                name: "checkout-7f89",
+                namespace: "default",
+                ownerReferences: [{ kind: "Deployment", name: "checkout" }],
+            },
+        });
+        fake.pods.emit("add", {
+            metadata: {
+                name: "checkout-7f89d",
+                namespace: "default",
+                ownerReferences: [{ kind: "ReplicaSet", name: "checkout-7f89" }],
+            },
+            spec: { nodeName: "worker-1" },
+        });
+        const snap = await conn.getTopologySnapshot();
+        const ids = snap.resources.map((r) => r.id).sort();
+        assert.deepEqual(ids, [
+            "k8s:deployment:default/checkout",
+            "k8s:namespace:default",
+            "k8s:node:worker-1",
+            "k8s:pod:default/checkout-7f89d",
+            "k8s:replicaset:default/checkout-7f89",
+        ]);
+        // Full RCA chain present: pod → rs → deployment, pod → node, * → namespace.
+        const e = snap.edges;
+        assert.ok(e.some((x) => x.from === "k8s:pod:default/checkout-7f89d" && x.relation === "RUNS_ON"));
+        assert.ok(e.some((x) => x.from === "k8s:pod:default/checkout-7f89d" && x.relation === "OWNED_BY"));
+        assert.ok(e.some((x) => x.from === "k8s:replicaset:default/checkout-7f89" && x.relation === "OWNED_BY"));
+        await conn.disconnect();
+    });
+    it("removes a pod's edges when the pod is deleted", async () => {
+        const fake = makeFakeFactory();
+        const conn = new KubernetesConnector(async () => fake.factory);
+        await conn.connect(CFG);
+        const pod = {
+            metadata: { name: "p1", namespace: "default" },
+            spec: { nodeName: "n1" },
+        };
+        fake.pods.emit("add", pod);
+        assert.equal((await conn.listEdges()).length > 0, true);
+        fake.pods.emit("delete", pod);
+        assert.equal((await conn.listResources()).length, 0);
+        assert.equal((await conn.listEdges()).length, 0);
+        await conn.disconnect();
+    });
+    it("watchTopology delivers a resync then live diffs", async () => {
+        const fake = makeFakeFactory();
+        const conn = new KubernetesConnector(async () => fake.factory);
+        await conn.connect(CFG);
+        fake.nodes.emit("add", { metadata: { name: "n0" } });
+        const events = [];
+        const unsub = conn.watchTopology((e) => events.push(e));
+        await new Promise((r) => setImmediate(r));
+        assert.equal(events[0]?.type, "resync");
+        fake.nodes.emit("add", { metadata: { name: "n1" } });
+        assert.ok(events.some((e) => e.type === "resource_added"));
+        unsub();
+        await conn.disconnect();
+    });
+});

package/dist/connectors/loader.js

@@ -4,6 +4,7 @@ import { pathToFileURL } from "node:url";
 import { manifestSchema } from "../sdk/manifest-schema.js";
 import { PrometheusConnector } from "./prometheus.js";
 import { LokiConnector } from "./loki.js";
+import { KubernetesConnector } from "./kubernetes.js";
 import { sanitizeForLog } from "../util/sanitize.js";
 import { instrumentConnector } from "../metrics/instrument-connector.js";
 import { loadTrustRoot, verifyIntegrity, verifyManifestSignature, PluginVerificationError, } from "./verify.js";
@@ -96,6 +97,11 @@ export class PluginLoader {
             source: "builtin",
             factory: () => new LokiConnector(),
         });
+        this.register({
+            name: "kubernetes",
+            source: "builtin",
+            factory: () => new KubernetesConnector(),
+        });
     }
     async loadFilesystem() {
         const dir = this.pluginsDir;

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

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

package/dist/connectors/topology.test.js

@@ -0,0 +1,165 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { isTopologyProvider } from "./interface.js";
+// A minimal connector that exposes no topology methods.
+function makeMetricsOnlyConnector() {
+    return {
+        name: "m1",
+        type: "prometheus",
+        signalType: "metrics",
+        async connect() { },
+        async healthCheck() {
+            return { status: "up", latencyMs: 0 };
+        },
+        async disconnect() { },
+        getDefaultMetrics() {
+            return [];
+        },
+        getMetrics() {
+            return [];
+        },
+        async listServices() {
+            return [];
+        },
+    };
+}
+// A fake topology connector that returns a tiny, well-formed graph.
+function makeTopologyConnector() {
+    const resources = [
+        {
+            id: "k8s:pod:default/checkout-7f89d",
+            kind: "pod",
+            name: "checkout-7f89d",
+            source: "kind-cluster",
+            labels: { app: "checkout" },
+            attributes: { uid: "11111111-1111-1111-1111-111111111111" },
+        },
+        {
+            id: "k8s:node:worker-1",
+            kind: "node",
+            name: "worker-1",
+            source: "kind-cluster",
+            labels: {},
+        },
+    ];
+    const edges = [
+        {
+            from: "k8s:pod:default/checkout-7f89d",
+            to: "k8s:node:worker-1",
+            relation: "RUNS_ON",
+            source: "kind-cluster",
+            confidence: 1.0,
+        },
+    ];
+    return {
+        name: "kind-cluster",
+        type: "kubernetes",
+        signalType: "topology",
+        async connect() { },
+        async healthCheck() {
+            return { status: "up", latencyMs: 0 };
+        },
+        async disconnect() { },
+        getDefaultMetrics() {
+            return [];
+        },
+        getMetrics() {
+            return [];
+        },
+        async listServices() {
+            return [];
+        },
+        async listResources() {
+            return resources;
+        },
+        async listEdges() {
+            return edges;
+        },
+        async getTopologySnapshot() {
+            return { source: "kind-cluster", resources, edges, revision: 1 };
+        },
+        watchTopology(listener) {
+            // emit an initial resync, then a no-op unsubscribe
+            queueMicrotask(() => listener({
+                type: "resync",
+                snapshot: { source: "kind-cluster", resources, edges, revision: 1 },
+            }));
+            return () => { };
+        },
+    };
+}
+describe("isTopologyProvider", () => {
+    it("returns false for metrics-only connectors", () => {
+        assert.equal(isTopologyProvider(makeMetricsOnlyConnector()), false);
+    });
+    it("returns true when all four topology methods are present", () => {
+        assert.equal(isTopologyProvider(makeTopologyConnector()), true);
+    });
+    it("returns false if any topology method is missing", () => {
+        const conn = makeTopologyConnector();
+        // Strip one method — partial topology support is not a TopologyProvider.
+        delete conn.watchTopology;
+        assert.equal(isTopologyProvider(conn), false);
+    });
+});
+describe("topology data model", () => {
+    it("Resource.id follows the k8s:<kind>:<namespace>/<name> shape for namespaced kinds", async () => {
+        const conn = makeTopologyConnector();
+        assert.ok(isTopologyProvider(conn));
+        const resources = await conn.listResources();
+        const pod = resources.find((r) => r.kind === "pod");
+        assert.ok(pod, "expected a pod resource");
+        assert.match(pod.id, /^k8s:pod:[^/]+\/.+$/);
+    });
+    it("Resource.id for cluster-scoped kinds has no namespace segment", async () => {
+        const conn = makeTopologyConnector();
+        assert.ok(isTopologyProvider(conn));
+        const resources = await conn.listResources();
+        const node = resources.find((r) => r.kind === "node");
+        assert.ok(node, "expected a node resource");
+        assert.match(node.id, /^k8s:node:[^/]+$/);
+    });
+    it("every Resource and Edge carries a non-empty source", async () => {
+        const conn = makeTopologyConnector();
+        assert.ok(isTopologyProvider(conn));
+        const snap = await conn.getTopologySnapshot();
+        for (const r of snap.resources)
+            assert.ok(r.source.length > 0);
+        for (const e of snap.edges)
+            assert.ok(e.source.length > 0);
+    });
+    it("Edge endpoints reference existing Resource ids", async () => {
+        const conn = makeTopologyConnector();
+        assert.ok(isTopologyProvider(conn));
+        const snap = await conn.getTopologySnapshot();
+        const ids = new Set(snap.resources.map((r) => r.id));
+        for (const e of snap.edges) {
+            assert.ok(ids.has(e.from), `dangling edge.from: ${e.from}`);
+            assert.ok(ids.has(e.to), `dangling edge.to: ${e.to}`);
+        }
+    });
+    it("confidence is bounded to [0,1]", async () => {
+        const conn = makeTopologyConnector();
+        assert.ok(isTopologyProvider(conn));
+        const edges = await conn.listEdges();
+        for (const e of edges) {
+            assert.ok(e.confidence >= 0 && e.confidence <= 1);
+        }
+    });
+});
+describe("watchTopology", () => {
+    it("delivers a resync event with the current snapshot", async () => {
+        const conn = makeTopologyConnector();
+        assert.ok(isTopologyProvider(conn));
+        const events = [];
+        const unsubscribe = conn.watchTopology((e) => events.push(e));
+        // Allow the queued microtask to fire.
+        await new Promise((resolve) => setImmediate(resolve));
+        unsubscribe();
+        assert.equal(events.length, 1);
+        assert.equal(events[0].type, "resync");
+        if (events[0].type === "resync") {
+            assert.ok(events[0].snapshot.revision >= 1);
+        }
+    });
+});

package/dist/enterprise-gate.d.ts

@@ -0,0 +1,132 @@
+import type { RequestContext } from "./context.js";
+export interface ToolRequest {
+    tool: string;
+    source?: string;
+    service?: string;
+}
+type GateState = {
+    mode: "off";
+} | {
+    mode: "fail-closed";
+    reason: string;
+} | {
+    mode: "active";
+    claims: Record<string, unknown>;
+    accessControl: boolean;
+    enforceRbac?: (policy: unknown, ctx: unknown, req: unknown) => unknown;
+    enforceCatalog?: (catalog: unknown, ctx: unknown, req: unknown) => unknown;
+    rbacPolicy?: unknown;
+    catalog?: unknown;
+    audit?: {
+        record: (e: unknown) => Promise<unknown>;
+    };
+};
+/** Tests only: also drops the audit singleton for full isolation. */
+export declare function _resetEnterpriseAudit(): void;
+/** Reset memoised state (tests only). */
+export declare function _resetEnterpriseGate(): void;
+/** Gate mode — for diagnostics (/api/info). */
+export declare function enterpriseGateStatus(): Promise<{
+    active: boolean;
+    mode: GateState["mode"];
+    reason?: string;
+}>;
+/**
+ * The single enforcement point, called before every MCP tool runs.
+ *
+ * off:         no opt-in, no entitlement → memoised no-op, returns
+ *               immediately. Zero behaviour change for the OSS core;
+ *               the only path the published artifact ever takes.
+ * fail-closed:  a control was configured but the gate could not be
+ *               activated → deny EVERY tool call (a broken/expired
+ *               entitlement must never silently disable enforcement).
+ * active:       record the decision (if audit entitled) and deny by
+ *               throwing — the MCP SDK turns the throw into a clean tool
+ *               error and the handler never runs.
+ */
+export declare function enforceEntitledAccess(ctx: RequestContext, request: ToolRequest): Promise<void>;
+export interface EnterpriseGateInfo {
+    mode: GateState["mode"];
+    active: boolean;
+    reason?: string;
+    rbacConfigured: boolean;
+    catalogConfigured: boolean;
+    auditConfigured: boolean;
+    entitlement: Record<string, unknown> | null;
+}
+export declare function enterpriseGateInfo(): Promise<EnterpriseGateInfo>;
+/** The loaded RBAC policy (read-only view). */
+export declare function enterprisePolicyView(): {
+    configured: false;
+    data?: undefined;
+    error?: undefined;
+} | {
+    configured: true;
+    data: any;
+    error?: undefined;
+} | {
+    configured: true;
+    error: string;
+    data?: undefined;
+};
+/** The loaded product catalog (read-only view). */
+export declare function enterpriseCatalogView(): {
+    configured: false;
+    data?: undefined;
+    error?: undefined;
+} | {
+    configured: true;
+    data: any;
+    error?: undefined;
+} | {
+    configured: true;
+    error: string;
+    data?: undefined;
+};
+/** Recent audit decisions + a tamper-evidence check over the whole log. */
+export declare function enterpriseAuditTail(limit?: number): Promise<{
+    configured: false;
+    error?: undefined;
+    total?: undefined;
+    chain?: undefined;
+    entries?: undefined;
+} | {
+    configured: true;
+    error: string;
+    total?: undefined;
+    chain?: undefined;
+    entries?: undefined;
+} | {
+    configured: true;
+    total: number;
+    chain: unknown;
+    entries: unknown[];
+    error?: undefined;
+}>;
+export declare const ADMIN_CAP = "enterprise:admin";
+/** Structural validation — never trust a PUT body. */
+export declare function validatePolicyShape(p: any): string | null;
+export interface AdminResult {
+    ok: boolean;
+    status: number;
+    error?: string;
+}
+/**
+ * Authorize an admin action for `principalId` against the CURRENT
+ * on-disk policy (read fresh, never the memoised copy).
+ */
+export declare function authorizeAdmin(principalId: string | null): Promise<AdminResult>;
+/**
+ * Replace the RBAC policy. Caller must have passed authorizeAdmin first.
+ * Validates, blocks self-lockout, writes atomically, audits, and
+ * invalidates the gate memo so enforcement picks up the new policy.
+ */
+export declare function updateRbacPolicy(principalId: string, next: unknown): Promise<AdminResult>;
+/** Structural validation for a product catalog PUT body. */
+export declare function validateCatalogShape(c: any): string | null;
+/**
+ * Replace the product catalog. Caller must have passed authorizeAdmin.
+ * Validates, writes atomically, audits, invalidates the gate memo.
+ */
+export declare function updateCatalog(principalId: string, next: unknown): Promise<AdminResult>;
+export {};