@thotischner/observability-mcp 1.4.1 → 1.6.0

package/dist/auth/credentials.js

@@ -0,0 +1,76 @@
+/**
+ * Single-tenant authentication primitive (opt-in, backward compatible).
+ *
+ * If no credentials are configured the server behaves exactly as before
+ * (anonymous, all access). If `OMCP_API_KEYS` is set, the `/mcp` endpoint
+ * requires a valid `Authorization: Bearer <token>` or `X-API-Key: <token>`.
+ *
+ * Config (env, no secrets in files):
+ *   OMCP_API_KEYS="ci:tok_abc,agent:tok_def"   # name:token, comma-separated
+ *                  (a bare "tok_xyz" is allowed; name defaults to "key")
+ *   OMCP_KEY_SOURCES="agent=prom-prod|loki-prod;ci=prom-staging"
+ *                  # optional coarse per-key source allow-list
+ *
+ * Rich role-based access control (tools/services/lookback/read-only, the
+ * full governance object) is intentionally NOT here — this is only the
+ * authentication + identity + coarse source-scoping primitive.
+ */
+function parseKeySources(raw) {
+    const m = new Map();
+    if (!raw)
+        return m;
+    for (const entry of raw.split(";").map((s) => s.trim()).filter(Boolean)) {
+        const [name, list] = entry.split("=");
+        if (!name || !list)
+            continue;
+        m.set(name.trim(), list.split("|").map((s) => s.trim()).filter(Boolean));
+    }
+    return m;
+}
+/** Parse credentials from env. Returns an empty list when unconfigured. */
+export function loadCredentials(env = process.env) {
+    const raw = env.OMCP_API_KEYS?.trim();
+    if (!raw)
+        return [];
+    const keySources = parseKeySources(env.OMCP_KEY_SOURCES);
+    const creds = [];
+    for (const part of raw.split(",").map((s) => s.trim()).filter(Boolean)) {
+        const idx = part.indexOf(":");
+        const name = idx > 0 ? part.slice(0, idx).trim() : "key";
+        const token = (idx > 0 ? part.slice(idx + 1) : part).trim();
+        if (!token)
+            continue;
+        creds.push({ name, token, allowedSources: keySources.get(name) });
+    }
+    return creds;
+}
+export function credentialsConfigured(env = process.env) {
+    return loadCredentials(env).length > 0;
+}
+/** Extract a bearer/api-key token from request headers. */
+export function extractToken(headers) {
+    const auth = headers["authorization"];
+    if (typeof auth === "string" && /^Bearer\s+/i.test(auth)) {
+        return auth.replace(/^Bearer\s+/i, "").trim() || null;
+    }
+    const apiKey = headers["x-api-key"];
+    if (typeof apiKey === "string" && apiKey.trim())
+        return apiKey.trim();
+    return null;
+}
+/** Constant-time-ish token match → resolved credential, or null. */
+export function resolveToken(token, creds) {
+    if (!token)
+        return null;
+    for (const c of creds) {
+        if (c.token.length === token.length && safeEqual(c.token, token))
+            return c;
+    }
+    return null;
+}
+function safeEqual(a, b) {
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}

package/dist/auth/credentials.test.d.ts

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

package/dist/auth/credentials.test.js

@@ -0,0 +1,57 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { loadCredentials, credentialsConfigured, extractToken, resolveToken, } from "./credentials.js";
+import { queryMetricsHandler } from "../tools/query-metrics.js";
+import { principalContext, defaultContext } from "../context.js";
+describe("single-tenant auth primitive", () => {
+    it("unconfigured → no credentials, anonymous (backward compatible)", () => {
+        assert.equal(credentialsConfigured({}), false);
+        assert.deepEqual(loadCredentials({}), []);
+    });
+    it("parses name:token and bare token", () => {
+        const creds = loadCredentials({ OMCP_API_KEYS: "ci:tok_abc, tok_bare " });
+        assert.equal(creds.length, 2);
+        assert.deepEqual(creds[0], { name: "ci", token: "tok_abc", allowedSources: undefined });
+        assert.equal(creds[1].name, "key");
+        assert.equal(creds[1].token, "tok_bare");
+    });
+    it("parses per-key source allow-list", () => {
+        const creds = loadCredentials({
+            OMCP_API_KEYS: "agent:tok1,ci:tok2",
+            OMCP_KEY_SOURCES: "agent=prom-prod|loki-prod; ci=prom-staging",
+        });
+        assert.deepEqual(creds[0].allowedSources, ["prom-prod", "loki-prod"]);
+        assert.deepEqual(creds[1].allowedSources, ["prom-staging"]);
+    });
+    it("extractToken handles Bearer and X-API-Key", () => {
+        assert.equal(extractToken({ authorization: "Bearer abc" }), "abc");
+        assert.equal(extractToken({ authorization: "bearer  xyz " }), "xyz");
+        assert.equal(extractToken({ "x-api-key": "k1" }), "k1");
+        assert.equal(extractToken({}), null);
+    });
+    it("resolveToken matches only an exact token", () => {
+        const creds = loadCredentials({ OMCP_API_KEYS: "a:secret123" });
+        assert.equal(resolveToken("secret123", creds)?.name, "a");
+        assert.equal(resolveToken("secret12", creds), null);
+        assert.equal(resolveToken("wrong", creds), null);
+        assert.equal(resolveToken(null, creds), null);
+    });
+    it("coarse source scoping denies an out-of-scope source", async () => {
+        const ctx = principalContext("agent", ["prom-prod"]);
+        const res = await queryMetricsHandler({}, { service: "svc", metric: "cpu", source: "prom-secret" }, ctx);
+        const text = res.content[0].text;
+        assert.match(text, /forbidden: source.*prom-secret.*not in your allowed sources/);
+    });
+    it("anonymous (no allow-list) does not trigger the scoping guard", async () => {
+        // No allowedSources → guard is a no-op. It must NOT short-circuit with a
+        // forbidden message (it falls through to normal handling, which on a stub
+        // registry may throw — that's fine, it means we passed the guard).
+        try {
+            const res = await queryMetricsHandler({}, { service: "svc", metric: "cpu", source: "anything" }, defaultContext());
+            assert.doesNotMatch(res.content[0].text, /allowed sources/);
+        }
+        catch {
+            // threw past the guard → guard correctly did not fire
+        }
+    });
+});

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

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 {};