@thotischner/observability-mcp 1.7.0 → 1.8.1

package/dist/catalog/loader.test.js

@@ -0,0 +1,108 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { readCatalogFile, validateCatalog, CatalogStore } from "./loader.js";
+test("readCatalogFile — missing path returns empty catalog", async () => {
+    const c = await readCatalogFile(undefined);
+    assert.deepEqual(c, { services: {} });
+});
+test("readCatalogFile — missing file returns empty catalog (no crash)", async () => {
+    const c = await readCatalogFile("/tmp/definitely-does-not-exist-omcp.json");
+    assert.deepEqual(c, { services: {} });
+});
+test("readCatalogFile — malformed JSON returns empty catalog", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "omcp-catalog-"));
+    try {
+        const file = join(dir, "catalog.json");
+        await writeFile(file, "{this is not json", "utf8");
+        const c = await readCatalogFile(file);
+        assert.deepEqual(c, { services: {} });
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});
+test("readCatalogFile — valid file returns parsed catalog", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "omcp-catalog-"));
+    try {
+        const file = join(dir, "catalog.json");
+        await writeFile(file, JSON.stringify({
+            services: {
+                "payment-service": {
+                    owner: "team-payments",
+                    tier: "tier-1",
+                    dataClassification: "confidential",
+                    slo: "99.9%",
+                    runbooks: ["https://runbooks.example/payments"],
+                    tags: ["pci", "regulated"],
+                },
+            },
+        }), "utf8");
+        const c = await readCatalogFile(file);
+        assert.equal(c.services["payment-service"].owner, "team-payments");
+        assert.equal(c.services["payment-service"].tier, "tier-1");
+        assert.deepEqual(c.services["payment-service"].tags, ["pci", "regulated"]);
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true });
+    }
+});
+test("validateCatalog — rejects invalid tier values", () => {
+    const c = validateCatalog({ services: { svc: { tier: "tier-9" } } });
+    assert.equal(c.services.svc.tier, undefined);
+});
+test("validateCatalog — rejects invalid data classification", () => {
+    const c = validateCatalog({ services: { svc: { dataClassification: "ultra-secret" } } });
+    assert.equal(c.services.svc.dataClassification, undefined);
+});
+test("validateCatalog — strips non-string entries from runbooks / tags", () => {
+    const c = validateCatalog({
+        services: { svc: { runbooks: ["a", 1, "b", null], tags: [{}, "tag1"] } },
+    });
+    assert.deepEqual(c.services.svc.runbooks, ["a", "b"]);
+    assert.deepEqual(c.services.svc.tags, ["tag1"]);
+});
+test("validateCatalog — skips non-object service entries", () => {
+    const c = validateCatalog({ services: { svc1: "string", svc2: null, svc3: { owner: "team" } } });
+    assert.equal(c.services.svc1, undefined);
+    assert.equal(c.services.svc2, undefined);
+    assert.equal(c.services.svc3.owner, "team");
+});
+test("CatalogStore — get / list / count / replace", () => {
+    const store = new CatalogStore({
+        services: {
+            a: { owner: "team-a" },
+            b: { owner: "team-b" },
+        },
+    });
+    assert.equal(store.count(), 2);
+    assert.equal(store.get("a")?.owner, "team-a");
+    assert.equal(store.get("nope"), undefined);
+    assert.equal(Object.keys(store.list()).length, 2);
+    store.replace({ services: { x: { owner: "team-x" } } });
+    assert.equal(store.count(), 1);
+    assert.equal(store.get("x")?.owner, "team-x");
+});
+test("CatalogStore — tenant filter scopes get / list / count", () => {
+    const store = new CatalogStore({
+        services: {
+            "acme-payments": { owner: "team-a", tenant: "acme" },
+            "bigco-payments": { owner: "team-b", tenant: "bigco" },
+            "shared-cdn": { owner: "team-c" }, // no tenant → "default"
+        },
+    });
+    // No tenant filter → see everything (admin-style read)
+    assert.equal(store.count(), 3);
+    // Tenant-scoped: each sees its own entries + nothing else
+    assert.equal(store.count("acme"), 1);
+    assert.equal(store.get("acme-payments", "acme")?.owner, "team-a");
+    assert.equal(store.get("bigco-payments", "acme"), undefined, "cross-tenant get must return undefined");
+    assert.equal(Object.keys(store.list("acme"))[0], "acme-payments");
+    // Default tenant includes entries with no tenant field
+    assert.equal(store.count("default"), 1);
+    assert.equal(store.get("shared-cdn", "default")?.owner, "team-c");
+    // Unknown tenant → empty
+    assert.equal(store.count("unknown"), 0);
+});

package/dist/connectors/kubernetes.d.ts

@@ -29,6 +29,7 @@ export declare class KubernetesConnector implements ObservabilityConnector {
     readonly signalType: SignalType;
     name: string;
     private store;
+    private warnedVocab;
     private factory?;
     private informers;
     private providerOverride?;

package/dist/connectors/kubernetes.js

@@ -1,4 +1,5 @@
 import { TopologyStore, podResource, podEdges, nodeResource, deploymentResource, deploymentEdges, replicaSetResource, replicaSetEdges, namespaceResource, namespacedId, clusterScopedId, } from "./kubernetes-graph.js";
+import { validateSnapshot } from "./topology-vocabulary.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
@@ -19,6 +20,7 @@ export class KubernetesConnector {
     signalType = "topology";
     name = "";
     store;
+    warnedVocab = new Set();
     factory;
     informers = [];
     providerOverride;
@@ -141,12 +143,20 @@ export class KubernetesConnector {
         return this.store?.listEdges() ?? [];
     }
     async getTopologySnapshot() {
-        return (this.store?.snapshot() ?? {
+        const snap = this.store?.snapshot() ?? {
             source: this.name,
             resources: [],
             edges: [],
             revision: 0,
-        });
+        };
+        for (const w of validateSnapshot(snap.resources, snap.edges)) {
+            const key = `${w.kind}:${w.value}`;
+            if (this.warnedVocab.has(key))
+                continue;
+            this.warnedVocab.add(key);
+            console.warn("topology vocabulary warning (source=%s): %s", this.name, w.message);
+        }
+        return snap;
     }
     watchTopology(listener) {
         if (!this.store)

package/dist/connectors/topology-vocabulary.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Canonical vocabulary for the connector-agnostic topology graph.
+ *
+ * The set is intentionally small: only values that are emitted by a shipped
+ * connector OR are reserved as the agreed name for a near-term connector.
+ * Adding a value is a documentation change in docs/topology-vocabulary.md
+ * plus an entry in the const arrays below; never invent a value at the call
+ * site without that paper trail.
+ *
+ * Validation is warn-only by design — a connector that emits an unknown
+ * value still works, but the warning shows up in logs and unit tests so
+ * vocabulary drift gets caught before it spreads.
+ */
+import type { Edge, Resource } from "../types.js";
+export declare const KINDS: readonly ["pod", "node", "deployment", "replicaset", "namespace", "service", "container", "vm", "host", "hypervisor", "cluster"];
+export type Kind = (typeof KINDS)[number];
+export declare const RELATIONS: readonly ["RUNS_ON", "OWNED_BY", "IN_NAMESPACE", "CALLS", "CONTAINS", "DEPENDS_ON"];
+export type Relation = (typeof RELATIONS)[number];
+export declare function isKnownKind(k: string): k is Kind;
+export declare function isKnownRelation(r: string): r is Relation;
+export interface VocabularyWarning {
+    kind: "unknown_resource_kind" | "unknown_relation" | "case_mismatch";
+    message: string;
+    value: string;
+}
+/**
+ * Lint a single resource. Returns warnings for unknown or miscased `kind`
+ * values; an empty array means the resource passes the vocabulary.
+ */
+export declare function validateResource(r: Pick<Resource, "kind">): VocabularyWarning[];
+/**
+ * Lint a single edge. Returns warnings for unknown or miscased `relation`
+ * values; an empty array means the edge passes the vocabulary.
+ */
+export declare function validateEdge(e: Pick<Edge, "relation">): VocabularyWarning[];
+/**
+ * Convenience: lint a full snapshot. Returns the de-duplicated set of
+ * warnings (one per distinct value) so a noisy connector does not flood
+ * the log on each tick.
+ */
+export declare function validateSnapshot(resources: Pick<Resource, "kind">[], edges: Pick<Edge, "relation">[]): VocabularyWarning[];

package/dist/connectors/topology-vocabulary.js

@@ -0,0 +1,120 @@
+/**
+ * Canonical vocabulary for the connector-agnostic topology graph.
+ *
+ * The set is intentionally small: only values that are emitted by a shipped
+ * connector OR are reserved as the agreed name for a near-term connector.
+ * Adding a value is a documentation change in docs/topology-vocabulary.md
+ * plus an entry in the const arrays below; never invent a value at the call
+ * site without that paper trail.
+ *
+ * Validation is warn-only by design — a connector that emits an unknown
+ * value still works, but the warning shows up in logs and unit tests so
+ * vocabulary drift gets caught before it spreads.
+ */
+export const KINDS = [
+    "pod",
+    "node",
+    "deployment",
+    "replicaset",
+    "namespace",
+    "service",
+    "container",
+    "vm",
+    "host",
+    "hypervisor",
+    "cluster",
+];
+export const RELATIONS = [
+    "RUNS_ON",
+    "OWNED_BY",
+    "IN_NAMESPACE",
+    "CALLS",
+    "CONTAINS",
+    "DEPENDS_ON",
+];
+const KIND_SET = new Set(KINDS);
+const RELATION_SET = new Set(RELATIONS);
+export function isKnownKind(k) {
+    return KIND_SET.has(k);
+}
+export function isKnownRelation(r) {
+    return RELATION_SET.has(r);
+}
+/**
+ * Lint a single resource. Returns warnings for unknown or miscased `kind`
+ * values; an empty array means the resource passes the vocabulary.
+ */
+export function validateResource(r) {
+    const out = [];
+    if (!isKnownKind(r.kind)) {
+        const lower = r.kind.toLowerCase();
+        if (isKnownKind(lower)) {
+            out.push({
+                kind: "case_mismatch",
+                value: r.kind,
+                message: `resource kind "${r.kind}" should be lowercase "${lower}" — see docs/topology-vocabulary.md`,
+            });
+        }
+        else {
+            out.push({
+                kind: "unknown_resource_kind",
+                value: r.kind,
+                message: `resource kind "${r.kind}" is not in the canonical vocabulary; either rename or extend docs/topology-vocabulary.md + KINDS`,
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Lint a single edge. Returns warnings for unknown or miscased `relation`
+ * values; an empty array means the edge passes the vocabulary.
+ */
+export function validateEdge(e) {
+    const out = [];
+    if (!isKnownRelation(e.relation)) {
+        const upper = e.relation.toUpperCase();
+        if (isKnownRelation(upper)) {
+            out.push({
+                kind: "case_mismatch",
+                value: e.relation,
+                message: `relation "${e.relation}" should be UPPER_SNAKE "${upper}" — see docs/topology-vocabulary.md`,
+            });
+        }
+        else {
+            out.push({
+                kind: "unknown_relation",
+                value: e.relation,
+                message: `relation "${e.relation}" is not in the canonical vocabulary; either rename or extend docs/topology-vocabulary.md + RELATIONS`,
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Convenience: lint a full snapshot. Returns the de-duplicated set of
+ * warnings (one per distinct value) so a noisy connector does not flood
+ * the log on each tick.
+ */
+export function validateSnapshot(resources, edges) {
+    const seen = new Set();
+    const out = [];
+    for (const r of resources) {
+        for (const w of validateResource(r)) {
+            const key = `r:${w.kind}:${w.value}`;
+            if (!seen.has(key)) {
+                seen.add(key);
+                out.push(w);
+            }
+        }
+    }
+    for (const e of edges) {
+        for (const w of validateEdge(e)) {
+            const key = `e:${w.kind}:${w.value}`;
+            if (!seen.has(key)) {
+                seen.add(key);
+                out.push(w);
+            }
+        }
+    }
+    return out;
+}

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

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

package/dist/connectors/topology-vocabulary.test.js

@@ -0,0 +1,63 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { KINDS, RELATIONS, isKnownKind, isKnownRelation, validateResource, validateEdge, validateSnapshot, } from "./topology-vocabulary.js";
+test("vocabulary — KINDS and RELATIONS contain what the kubernetes connector emits today", () => {
+    for (const k of ["pod", "node", "deployment", "replicaset", "namespace"]) {
+        assert.equal(isKnownKind(k), true, `kind "${k}" must be in the canonical vocabulary`);
+    }
+    for (const r of ["RUNS_ON", "OWNED_BY", "IN_NAMESPACE"]) {
+        assert.equal(isKnownRelation(r), true, `relation "${r}" must be in the canonical vocabulary`);
+    }
+});
+test("vocabulary — CALLS is reserved for the upcoming trace connector", () => {
+    assert.equal(isKnownRelation("CALLS"), true);
+});
+test("validateResource — canonical kinds produce no warnings", () => {
+    for (const k of KINDS) {
+        assert.deepEqual(validateResource({ kind: k }), []);
+    }
+});
+test("validateResource — unknown kind warns", () => {
+    const w = validateResource({ kind: "frobnicator" });
+    assert.equal(w.length, 1);
+    assert.equal(w[0].kind, "unknown_resource_kind");
+    assert.equal(w[0].value, "frobnicator");
+});
+test("validateResource — uppercase kind triggers a case-mismatch hint", () => {
+    const w = validateResource({ kind: "Pod" });
+    assert.equal(w.length, 1);
+    assert.equal(w[0].kind, "case_mismatch");
+    assert.match(w[0].message, /lowercase "pod"/);
+});
+test("validateEdge — canonical relations produce no warnings", () => {
+    for (const r of RELATIONS) {
+        assert.deepEqual(validateEdge({ relation: r }), []);
+    }
+});
+test("validateEdge — unknown relation warns", () => {
+    const w = validateEdge({ relation: "FROBNICATES" });
+    assert.equal(w.length, 1);
+    assert.equal(w[0].kind, "unknown_relation");
+});
+test("validateEdge — lowercase relation triggers a case-mismatch hint", () => {
+    const w = validateEdge({ relation: "runs_on" });
+    assert.equal(w.length, 1);
+    assert.equal(w[0].kind, "case_mismatch");
+    assert.match(w[0].message, /UPPER_SNAKE "RUNS_ON"/);
+});
+test("validateSnapshot — de-duplicates repeated offenders", () => {
+    const warnings = validateSnapshot([
+        { kind: "frobnicator" },
+        { kind: "frobnicator" },
+        { kind: "pod" },
+    ], [
+        { relation: "FROBNICATES" },
+        { relation: "FROBNICATES" },
+        { relation: "RUNS_ON" },
+    ]);
+    assert.equal(warnings.length, 2, `expected one warning per distinct offender, got ${warnings.length}`);
+});
+test("validateSnapshot — a fully canonical snapshot is silent", () => {
+    const warnings = validateSnapshot([{ kind: "pod" }, { kind: "node" }, { kind: "deployment" }], [{ relation: "RUNS_ON" }, { relation: "OWNED_BY" }, { relation: "IN_NAMESPACE" }]);
+    assert.deepEqual(warnings, []);
+});

package/dist/context.d.ts

@@ -18,10 +18,22 @@ export interface RequestContext {
      * scoping (tools/services/lookback/read-only) is a separate concern.
      */
     allowedSources?: string[];
+    /** When true, the credential is allowed to opt out of redaction on a
+     *  per-tool-call basis. The actual bypass is engaged only when the
+     *  tool call ALSO sets `bypass_redaction: true` in its args. Default
+     *  false. Configured via OMCP_KEY_BYPASS_REDACTION. */
+    allowBypassRedaction?: boolean;
+    /** Tenant the request operates in. ALWAYS set — defaults to
+     *  "default" for anonymous principals + missing-tenant credentials,
+     *  preserving the single-namespace behaviour of pre-E7 deployments. */
+    tenant: 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;
+export declare function principalContext(principalId: string, allowedSources?: string[], opts?: {
+    allowBypassRedaction?: boolean;
+    tenant?: string;
+}): RequestContext;

package/dist/context.js

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