@thotischner/observability-mcp 1.7.0 → 1.8.1

package/dist/auth/rbac.test.js

@@ -0,0 +1,121 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { hasPermission, buildRequirePermission, listGrantedPermissions, DEFAULT_POLICY, } from "./rbac.js";
+function mkReq(roles) {
+    return {
+        session: roles
+            ? { sub: "u", name: "u", roles, iat: 0, exp: Date.now() / 1000 + 60 }
+            : undefined,
+    };
+}
+function mkRes() {
+    let statusCode = 0;
+    let body = null;
+    return {
+        status(c) { statusCode = c; return this; },
+        json(b) { body = b; return this; },
+        get statusCode() { return statusCode; },
+        get body() { return body; },
+    };
+}
+test("DEFAULT_POLICY — viewer reads but cannot write", () => {
+    assert.equal(hasPermission(["viewer"], "sources", "read"), true);
+    assert.equal(hasPermission(["viewer"], "sources", "write"), false);
+    assert.equal(hasPermission(["viewer"], "sources", "delete"), false);
+});
+test("DEFAULT_POLICY — operator writes sources + settings but never deletes", () => {
+    assert.equal(hasPermission(["operator"], "sources", "write"), true);
+    assert.equal(hasPermission(["operator"], "settings", "write"), true);
+    assert.equal(hasPermission(["operator"], "sources", "delete"), false);
+});
+test("DEFAULT_POLICY — admin can do everything across every resource", () => {
+    for (const resource of ["sources", "services", "health", "topology", "settings", "connectors", "audit", "catalog", "users", "products"]) {
+        for (const action of ["read", "write", "delete"]) {
+            assert.equal(hasPermission(["admin"], resource, action), true, `admin should ${action} ${resource}`);
+        }
+    }
+});
+test("DEFAULT_POLICY — only admin holds redaction:bypass", () => {
+    assert.equal(hasPermission(["admin"], "redaction", "bypass"), true);
+    assert.equal(hasPermission(["operator"], "redaction", "bypass"), false);
+    assert.equal(hasPermission(["viewer"], "redaction", "bypass"), false);
+    // Other actions on the redaction resource are intentionally NOT granted —
+    // there is no read/write/delete semantic, only bypass.
+    assert.equal(hasPermission(["admin"], "redaction", "read"), false);
+    assert.equal(hasPermission(["admin"], "redaction", "write"), false);
+});
+test("hasPermission — empty / missing roles grant nothing", () => {
+    assert.equal(hasPermission(undefined, "sources", "read"), false);
+    assert.equal(hasPermission([], "sources", "read"), false);
+    assert.equal(hasPermission(["unknown-role"], "sources", "read"), false);
+});
+test("hasPermission — union of roles is honoured", () => {
+    // A user assigned both viewer and operator gets the operator superset.
+    assert.equal(hasPermission(["viewer", "operator"], "sources", "write"), true);
+});
+test("hasPermission — custom policy overrides built-in", () => {
+    const custom = {
+        "incident-commander": [{ resource: "sources", action: "delete" }],
+    };
+    assert.equal(hasPermission(["incident-commander"], "sources", "delete", custom), true);
+    // Built-in admin is NOT in the custom policy → loses its grants.
+    assert.equal(hasPermission(["admin"], "sources", "delete", custom), false);
+});
+test("buildRequirePermission — anonymous always allows", () => {
+    const mw = buildRequirePermission({ mode: "anonymous" }, "sources", "write");
+    const res = mkRes();
+    let called = false;
+    mw(mkReq(), res, () => { called = true; });
+    assert.equal(called, true);
+    assert.equal(res.statusCode, 0);
+});
+test("buildRequirePermission — denies viewer on write", () => {
+    const runtime = { mode: "basic", session: { secret: "x".repeat(48) } };
+    const mw = buildRequirePermission(runtime, "sources", "write");
+    const res = mkRes();
+    let called = false;
+    mw(mkReq(["viewer"]), res, () => { called = true; });
+    assert.equal(called, false);
+    assert.equal(res.statusCode, 403);
+    const body = res.body;
+    assert.equal(body.code, "OMCP_PERMISSION_DENIED");
+});
+test("buildRequirePermission — allows operator on write", () => {
+    const runtime = { mode: "basic", session: { secret: "x".repeat(48) } };
+    const mw = buildRequirePermission(runtime, "sources", "write");
+    const res = mkRes();
+    let called = false;
+    mw(mkReq(["operator"]), res, () => { called = true; });
+    assert.equal(called, true);
+    assert.equal(res.statusCode, 0);
+});
+test("buildRequirePermission — denies missing session in basic mode", () => {
+    const runtime = { mode: "basic", session: { secret: "x".repeat(48) } };
+    const mw = buildRequirePermission(runtime, "sources", "read");
+    const res = mkRes();
+    let called = false;
+    mw(mkReq(), res, () => { called = true; });
+    assert.equal(called, false);
+    assert.equal(res.statusCode, 403);
+});
+test("listGrantedPermissions — deduplicates across overlapping roles", () => {
+    const p = listGrantedPermissions(["viewer", "operator"]);
+    const keys = p.map((g) => `${g.resource}:${g.action}`);
+    assert.equal(new Set(keys).size, keys.length, "expected no duplicates");
+    // sanity: includes both a viewer-only read and an operator-only write
+    assert.ok(p.some((g) => g.resource === "sources" && g.action === "read"));
+    assert.ok(p.some((g) => g.resource === "sources" && g.action === "write"));
+});
+test("listGrantedPermissions — admin lists every (resource, action) once", () => {
+    const p = listGrantedPermissions(["admin"]);
+    // 10 resources (added 'products' in the products-RBAC phase) * 3 actions
+    // = 30, plus the special redaction:bypass entry = 31.
+    assert.equal(p.length, 31);
+    assert.ok(p.some((g) => g.resource === "redaction" && g.action === "bypass"));
+    assert.ok(p.some((g) => g.resource === "products" && g.action === "delete"));
+});
+test("DEFAULT_POLICY shape — has the three built-in roles", () => {
+    assert.ok(DEFAULT_POLICY.viewer);
+    assert.ok(DEFAULT_POLICY.operator);
+    assert.ok(DEFAULT_POLICY.admin);
+});

package/dist/auth/session.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Stateless signed-cookie sessions for the management plane (`/api/*`).
+ *
+ * The cookie value is `<base64url(payload)>.<base64url(hmacSha256(payload))>`.
+ * The payload is a small JSON object with the user's identity, the issued-at
+ * timestamp and the absolute expiry. No server-side store; rotating the
+ * secret invalidates every outstanding session.
+ *
+ * MCP transport authentication still uses {@link Credential} bearer tokens
+ * — see `./credentials.ts`. This module is exclusively for the browser /
+ * UI / `/api/*` plane.
+ */
+export interface SessionPayload {
+    /** Stable user identifier (username for the local-users store, sub claim for OIDC, ...) */
+    sub: string;
+    /** Display name shown in the UI. May equal `sub`. */
+    name: string;
+    /** Email address when the identity provider supplied one. Optional —
+     *  local-users-mode sessions usually omit this; OIDC sessions populate
+     *  from the `email` claim when present + verified by the IdP. */
+    email?: string;
+    /** Tenant the identity belongs to. Omitted when single-tenant — the
+     *  request handler defaults to "default" via normaliseTenant() so
+     *  existing single-tenant deployments need no migration. */
+    tenant?: string;
+    /** Optional list of role identifiers — used by later phases for RBAC. */
+    roles?: string[];
+    /** Issued-at, seconds since epoch. */
+    iat: number;
+    /** Hard expiry, seconds since epoch. */
+    exp: number;
+}
+export interface SessionConfig {
+    /** Symmetric key. Must be at least 32 bytes. */
+    secret: string;
+    /** Cookie lifetime, seconds. Defaults to 12 hours. */
+    ttlSeconds?: number;
+    /** Cookie name. Defaults to `omcp_session`. */
+    cookieName?: string;
+}
+export declare const DEFAULT_SESSION_TTL_SECONDS: number;
+export declare const DEFAULT_COOKIE_NAME = "omcp_session";
+/** Create a signed cookie value for the given identity. */
+export declare function issueSession(identity: Pick<SessionPayload, "sub" | "name" | "roles" | "email" | "tenant">, cfg: SessionConfig, now?: number): {
+    cookie: string;
+    payload: SessionPayload;
+};
+/** Reject cookies above this size before any crypto work — practical
+ * browser cookies stay well under 4 KB and a runaway input shouldn't
+ * even reach the HMAC step. Defense-in-depth; Express's
+ * `maxHttpHeaderSize` (16 KB by default) is the outer bound. */
+export declare const MAX_COOKIE_BYTES = 4096;
+/** Verify a cookie value. Returns the payload on success, null on any failure. */
+export declare function verifySession(cookieValue: string | undefined | null, cfg: SessionConfig, now?: number): SessionPayload | null;
+/** Render a Set-Cookie header value for an issued session. */
+export declare function setCookieHeader(cookie: string, cfg: SessionConfig, opts?: {
+    secure?: boolean;
+}): string;
+/** Render a Set-Cookie header that immediately expires the session cookie. */
+export declare function clearCookieHeader(cfg: SessionConfig, opts?: {
+    secure?: boolean;
+}): string;
+/** Parse the named cookie from a raw Cookie header. */
+export declare function readCookie(cookieHeader: string | undefined | null, name?: string): string | null;
+/** Generate a cryptographically strong fallback secret. Logged-once recommended. */
+export declare function generateSecret(): string;

package/dist/auth/session.js

@@ -0,0 +1,146 @@
+/**
+ * Stateless signed-cookie sessions for the management plane (`/api/*`).
+ *
+ * The cookie value is `<base64url(payload)>.<base64url(hmacSha256(payload))>`.
+ * The payload is a small JSON object with the user's identity, the issued-at
+ * timestamp and the absolute expiry. No server-side store; rotating the
+ * secret invalidates every outstanding session.
+ *
+ * MCP transport authentication still uses {@link Credential} bearer tokens
+ * — see `./credentials.ts`. This module is exclusively for the browser /
+ * UI / `/api/*` plane.
+ */
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+export const DEFAULT_SESSION_TTL_SECONDS = 12 * 60 * 60;
+export const DEFAULT_COOKIE_NAME = "omcp_session";
+function b64urlEncode(buf) {
+    return buf.toString("base64url");
+}
+function b64urlDecode(s) {
+    try {
+        return Buffer.from(s, "base64url");
+    }
+    catch {
+        return null;
+    }
+}
+function sign(secret, payload) {
+    return createHmac("sha256", secret).update(payload).digest("base64url");
+}
+/** Create a signed cookie value for the given identity. */
+export function issueSession(identity, cfg, now = Math.floor(Date.now() / 1000)) {
+    assertSecret(cfg.secret);
+    const ttl = cfg.ttlSeconds ?? DEFAULT_SESSION_TTL_SECONDS;
+    const payload = {
+        sub: identity.sub,
+        name: identity.name,
+        email: identity.email,
+        tenant: identity.tenant,
+        roles: identity.roles,
+        iat: now,
+        exp: now + ttl,
+    };
+    const payloadStr = b64urlEncode(Buffer.from(JSON.stringify(payload)));
+    const sig = sign(cfg.secret, payloadStr);
+    return { cookie: `${payloadStr}.${sig}`, payload };
+}
+/** Reject cookies above this size before any crypto work — practical
+ * browser cookies stay well under 4 KB and a runaway input shouldn't
+ * even reach the HMAC step. Defense-in-depth; Express's
+ * `maxHttpHeaderSize` (16 KB by default) is the outer bound. */
+export const MAX_COOKIE_BYTES = 4096;
+/** Verify a cookie value. Returns the payload on success, null on any failure. */
+export function verifySession(cookieValue, cfg, now = Math.floor(Date.now() / 1000)) {
+    if (!cookieValue)
+        return null;
+    if (cookieValue.length > MAX_COOKIE_BYTES)
+        return null;
+    assertSecret(cfg.secret);
+    const dot = cookieValue.indexOf(".");
+    if (dot <= 0 || dot === cookieValue.length - 1)
+        return null;
+    const payloadStr = cookieValue.slice(0, dot);
+    const sig = cookieValue.slice(dot + 1);
+    const expected = sign(cfg.secret, payloadStr);
+    // Constant-time compare on equal-length buffers; reject length mismatch first.
+    const a = Buffer.from(sig);
+    const b = Buffer.from(expected);
+    if (a.length !== b.length || !timingSafeEqual(a, b))
+        return null;
+    const raw = b64urlDecode(payloadStr);
+    if (!raw)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw.toString("utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (!isSessionPayload(parsed))
+        return null;
+    if (parsed.exp <= now)
+        return null;
+    return parsed;
+}
+function isSessionPayload(v) {
+    if (!v || typeof v !== "object")
+        return false;
+    const o = v;
+    if (typeof o.sub !== "string" || typeof o.name !== "string")
+        return false;
+    if (typeof o.iat !== "number" || typeof o.exp !== "number")
+        return false;
+    if (o.roles !== undefined && !(Array.isArray(o.roles) && o.roles.every((r) => typeof r === "string")))
+        return false;
+    if (o.email !== undefined && typeof o.email !== "string")
+        return false;
+    if (o.tenant !== undefined && typeof o.tenant !== "string")
+        return false;
+    return true;
+}
+function assertSecret(secret) {
+    if (!secret || secret.length < 32) {
+        throw new Error("session secret must be at least 32 characters");
+    }
+}
+/** Render a Set-Cookie header value for an issued session. */
+export function setCookieHeader(cookie, cfg, opts = {}) {
+    const ttl = cfg.ttlSeconds ?? DEFAULT_SESSION_TTL_SECONDS;
+    const name = cfg.cookieName ?? DEFAULT_COOKIE_NAME;
+    const parts = [
+        `${name}=${cookie}`,
+        `Max-Age=${ttl}`,
+        "Path=/",
+        "HttpOnly",
+        "SameSite=Lax",
+    ];
+    if (opts.secure !== false)
+        parts.push("Secure");
+    return parts.join("; ");
+}
+/** Render a Set-Cookie header that immediately expires the session cookie. */
+export function clearCookieHeader(cfg, opts = {}) {
+    const name = cfg.cookieName ?? DEFAULT_COOKIE_NAME;
+    const parts = [`${name}=`, "Max-Age=0", "Path=/", "HttpOnly", "SameSite=Lax"];
+    if (opts.secure !== false)
+        parts.push("Secure");
+    return parts.join("; ");
+}
+/** Parse the named cookie from a raw Cookie header. */
+export function readCookie(cookieHeader, name = DEFAULT_COOKIE_NAME) {
+    if (!cookieHeader)
+        return null;
+    for (const part of cookieHeader.split(/;\s*/)) {
+        const eq = part.indexOf("=");
+        if (eq <= 0)
+            continue;
+        if (part.slice(0, eq) === name)
+            return part.slice(eq + 1);
+    }
+    return null;
+}
+/** Generate a cryptographically strong fallback secret. Logged-once recommended. */
+export function generateSecret() {
+    return randomBytes(48).toString("base64url");
+}

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

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

package/dist/auth/session.test.js

@@ -0,0 +1,90 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { issueSession, verifySession, setCookieHeader, clearCookieHeader, readCookie, generateSecret, DEFAULT_COOKIE_NAME, } from "./session.js";
+const secret = "a".repeat(48);
+test("issueSession + verifySession — round-trips identity", () => {
+    const now = 1_700_000_000;
+    const { cookie, payload } = issueSession({ sub: "alice", name: "Alice", roles: ["operator"] }, { secret }, now);
+    assert.equal(payload.sub, "alice");
+    assert.equal(payload.exp, now + 12 * 60 * 60);
+    const verified = verifySession(cookie, { secret }, now + 1);
+    assert.ok(verified, "expected verified payload");
+    assert.equal(verified.sub, "alice");
+    assert.deepEqual(verified.roles, ["operator"]);
+});
+test("issueSession + verifySession — round-trips email when present", () => {
+    const now = 1_700_000_000;
+    const { cookie } = issueSession({ sub: "alice", name: "Alice", email: "alice@example.test", roles: ["operator"] }, { secret }, now);
+    const verified = verifySession(cookie, { secret }, now + 1);
+    assert.ok(verified);
+    assert.equal(verified.email, "alice@example.test");
+});
+test("issueSession + verifySession — omits email when caller doesn't supply one", () => {
+    const now = 1_700_000_000;
+    const { cookie } = issueSession({ sub: "alice", name: "Alice", roles: ["operator"] }, { secret }, now);
+    const verified = verifySession(cookie, { secret }, now + 1);
+    assert.ok(verified);
+    assert.equal(verified.email, undefined);
+});
+test("verifySession — rejects an expired cookie", () => {
+    const now = 1_700_000_000;
+    const { cookie } = issueSession({ sub: "alice", name: "Alice" }, { secret, ttlSeconds: 60 }, now);
+    assert.equal(verifySession(cookie, { secret }, now + 61), null);
+});
+test("verifySession — rejects tampered payload", () => {
+    const { cookie } = issueSession({ sub: "alice", name: "Alice" }, { secret });
+    const [payload, sig] = cookie.split(".");
+    const flipped = Buffer.from(payload, "base64url").toString("utf8").replace("alice", "mallory");
+    const evil = Buffer.from(flipped).toString("base64url") + "." + sig;
+    assert.equal(verifySession(evil, { secret }), null);
+});
+test("verifySession — rejects cookie signed with a different secret", () => {
+    const { cookie } = issueSession({ sub: "alice", name: "Alice" }, { secret });
+    assert.equal(verifySession(cookie, { secret: "b".repeat(48) }), null);
+});
+test("verifySession — null / empty / malformed cookies return null", () => {
+    assert.equal(verifySession(null, { secret }), null);
+    assert.equal(verifySession("", { secret }), null);
+    assert.equal(verifySession("no-dot-anywhere", { secret }), null);
+    assert.equal(verifySession(".trailing", { secret }), null);
+    assert.equal(verifySession("leading.", { secret }), null);
+});
+test("verifySession — rejects oversized cookies before any crypto work", () => {
+    const huge = "x".repeat(10_000) + "." + "y".repeat(10);
+    assert.equal(verifySession(huge, { secret }), null);
+});
+test("verifySession — rejects short secret at verify time too (fail-closed)", () => {
+    const { cookie } = issueSession({ sub: "alice", name: "Alice" }, { secret });
+    assert.throws(() => verifySession(cookie, { secret: "short" }));
+});
+test("issueSession — rejects secrets shorter than 32 chars", () => {
+    assert.throws(() => issueSession({ sub: "alice", name: "A" }, { secret: "short" }));
+});
+test("setCookieHeader / clearCookieHeader — render expected attributes", () => {
+    const { cookie } = issueSession({ sub: "alice", name: "Alice" }, { secret });
+    const setHdr = setCookieHeader(cookie, { secret });
+    assert.match(setHdr, /^omcp_session=/);
+    assert.match(setHdr, /HttpOnly/);
+    assert.match(setHdr, /SameSite=Lax/);
+    assert.match(setHdr, /Secure/);
+    assert.match(setHdr, /Max-Age=43200/);
+    const clearHdr = clearCookieHeader({ secret });
+    assert.match(clearHdr, /^omcp_session=;/);
+    assert.match(clearHdr, /Max-Age=0/);
+});
+test("setCookieHeader — `secure: false` omits Secure (dev / plain http)", () => {
+    const { cookie } = issueSession({ sub: "alice", name: "Alice" }, { secret });
+    const hdr = setCookieHeader(cookie, { secret }, { secure: false });
+    assert.doesNotMatch(hdr, /Secure/);
+});
+test("readCookie — extracts the named cookie from a Cookie header", () => {
+    assert.equal(readCookie("foo=bar; omcp_session=hello; baz=qux"), "hello");
+    assert.equal(readCookie("omcp_session=hello", DEFAULT_COOKIE_NAME), "hello");
+    assert.equal(readCookie(undefined), null);
+    assert.equal(readCookie("missing=1"), null);
+});
+test("generateSecret — always returns ≥ 32 chars of url-safe entropy", () => {
+    const s = generateSecret();
+    assert.ok(s.length >= 32);
+    assert.match(s, /^[A-Za-z0-9_-]+$/);
+});

package/dist/catalog/loader.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Service catalog: an operator-curated map of service name → ownership /
+ * criticality / on-call metadata. Hooked into the existing /api/services
+ * and /api/health responses so the UI (and the agent through the MCP
+ * tools that derive from those endpoints) can see "this is owned by
+ * team-payments, criticality tier-1, on-call URL …" without having to
+ * cross-reference an external CMDB.
+ *
+ * On-disk format: JSON file (commit-friendly, easy to diff in PRs). Path
+ * defaults to `mcp-server/config/catalog.json`; override via
+ * `OMCP_SERVICE_CATALOG_FILE`. Missing or malformed file => no catalog
+ * (the server boots fine, enrichment is a no-op).
+ *
+ * Distinct from the enterprise-gate `OMCP_CATALOG` "product catalog"
+ * which lives behind the entitlement gate and governs MCP-tool grants —
+ * different trust model, different schema.
+ */
+export type CriticalityTier = "tier-1" | "tier-2" | "tier-3" | "tier-4";
+export type DataClassification = "public" | "internal" | "confidential" | "restricted";
+export interface ServiceCatalogEntry {
+    /** Stable short owner identifier — team slug, squad, individual handle. */
+    owner?: string;
+    /** Human-readable description. One sentence. */
+    description?: string;
+    /** Page-the-team URL — Slack channel, on-call rota, runbook index. */
+    onCall?: string;
+    /** Operator-defined criticality bucket. */
+    tier?: CriticalityTier;
+    /** Data classification of what flows through the service. */
+    dataClassification?: DataClassification;
+    /** Free-form SLO label ("99.9% / month" / "99.5%"). Not parsed. */
+    slo?: string;
+    /** Optional list of relevant runbook URLs. */
+    runbooks?: string[];
+    /** Optional list of free-form tags. */
+    tags?: string[];
+    /** Tenant the entry belongs to. Omitted → "default". Used by
+     *  multi-tenant deployments to scope what /api/catalog and the
+     *  list_services / get_service_health tools surface per session. */
+    tenant?: string;
+}
+export interface ServiceCatalog {
+    /** Map service name → entry. Service-name key is the same string
+     * `list_services` returns; no fuzzy matching. */
+    services: Record<string, ServiceCatalogEntry>;
+}
+/** Read + validate a catalog file. Returns the empty catalog on any
+ * problem and (when configured) emits a single warn-level console.error
+ * so the operator notices but the server keeps booting. */
+export declare function readCatalogFile(path: string | undefined): Promise<ServiceCatalog>;
+/** Pure validator — useful in tests and when feeding in-memory data. */
+export declare function validateCatalog(input: unknown): ServiceCatalog;
+/** Lookup wrapper used by the enricher / API handlers. */
+export declare class CatalogStore {
+    private catalog;
+    constructor(catalog?: ServiceCatalog);
+    /** Lookup. When `tenant` is set, returns undefined for entries
+     *  belonging to a different tenant — so a cross-tenant
+     *  enrichment never leaks owner / on-call / SLO bytes. Entries
+     *  without a tenant field are treated as `"default"`. */
+    get(serviceName: string, tenant?: string): ServiceCatalogEntry | undefined;
+    /** Snapshot. When `tenant` is set, filters down to entries in that
+     *  tenant; entries without a tenant field counted as `"default"`. */
+    list(tenant?: string): Record<string, ServiceCatalogEntry>;
+    count(tenant?: string): number;
+    replace(catalog: ServiceCatalog): void;
+}

package/dist/catalog/loader.js

@@ -0,0 +1,122 @@
+/**
+ * Service catalog: an operator-curated map of service name → ownership /
+ * criticality / on-call metadata. Hooked into the existing /api/services
+ * and /api/health responses so the UI (and the agent through the MCP
+ * tools that derive from those endpoints) can see "this is owned by
+ * team-payments, criticality tier-1, on-call URL …" without having to
+ * cross-reference an external CMDB.
+ *
+ * On-disk format: JSON file (commit-friendly, easy to diff in PRs). Path
+ * defaults to `mcp-server/config/catalog.json`; override via
+ * `OMCP_SERVICE_CATALOG_FILE`. Missing or malformed file => no catalog
+ * (the server boots fine, enrichment is a no-op).
+ *
+ * Distinct from the enterprise-gate `OMCP_CATALOG` "product catalog"
+ * which lives behind the entitlement gate and governs MCP-tool grants —
+ * different trust model, different schema.
+ */
+import { promises as fs } from "node:fs";
+const EMPTY_CATALOG = { services: {} };
+const VALID_TIERS = new Set(["tier-1", "tier-2", "tier-3", "tier-4"]);
+const VALID_CLASS = new Set(["public", "internal", "confidential", "restricted"]);
+/** Read + validate a catalog file. Returns the empty catalog on any
+ * problem and (when configured) emits a single warn-level console.error
+ * so the operator notices but the server keeps booting. */
+export async function readCatalogFile(path) {
+    if (!path)
+        return EMPTY_CATALOG;
+    let raw;
+    try {
+        raw = await fs.readFile(path, "utf8");
+    }
+    catch {
+        return EMPTY_CATALOG;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        console.error(`[catalog] OMCP_SERVICE_CATALOG_FILE=${path} is not valid JSON: ${e.message}`);
+        return EMPTY_CATALOG;
+    }
+    return validateCatalog(parsed);
+}
+/** Pure validator — useful in tests and when feeding in-memory data. */
+export function validateCatalog(input) {
+    if (!input || typeof input !== "object")
+        return EMPTY_CATALOG;
+    const obj = input;
+    const rawServices = obj.services;
+    if (!rawServices || typeof rawServices !== "object")
+        return EMPTY_CATALOG;
+    const out = {};
+    for (const [name, value] of Object.entries(rawServices)) {
+        if (!value || typeof value !== "object")
+            continue;
+        const e = value;
+        const entry = {};
+        if (typeof e.owner === "string")
+            entry.owner = e.owner;
+        if (typeof e.description === "string")
+            entry.description = e.description;
+        if (typeof e.onCall === "string")
+            entry.onCall = e.onCall;
+        if (typeof e.tier === "string" && VALID_TIERS.has(e.tier)) {
+            entry.tier = e.tier;
+        }
+        if (typeof e.dataClassification === "string" && VALID_CLASS.has(e.dataClassification)) {
+            entry.dataClassification = e.dataClassification;
+        }
+        if (typeof e.slo === "string")
+            entry.slo = e.slo;
+        if (Array.isArray(e.runbooks)) {
+            entry.runbooks = e.runbooks.filter((x) => typeof x === "string");
+        }
+        if (Array.isArray(e.tags)) {
+            entry.tags = e.tags.filter((x) => typeof x === "string");
+        }
+        if (typeof e.tenant === "string")
+            entry.tenant = e.tenant;
+        out[name] = entry;
+    }
+    return { services: out };
+}
+/** Lookup wrapper used by the enricher / API handlers. */
+export class CatalogStore {
+    catalog;
+    constructor(catalog = EMPTY_CATALOG) {
+        this.catalog = catalog;
+    }
+    /** Lookup. When `tenant` is set, returns undefined for entries
+     *  belonging to a different tenant — so a cross-tenant
+     *  enrichment never leaks owner / on-call / SLO bytes. Entries
+     *  without a tenant field are treated as `"default"`. */
+    get(serviceName, tenant) {
+        const e = this.catalog.services[serviceName];
+        if (!e)
+            return undefined;
+        if (!tenant)
+            return e;
+        const entryTenant = e.tenant || "default";
+        return entryTenant === tenant ? e : undefined;
+    }
+    /** Snapshot. When `tenant` is set, filters down to entries in that
+     *  tenant; entries without a tenant field counted as `"default"`. */
+    list(tenant) {
+        if (!tenant)
+            return this.catalog.services;
+        const out = {};
+        for (const [k, v] of Object.entries(this.catalog.services)) {
+            if ((v.tenant || "default") === tenant)
+                out[k] = v;
+        }
+        return out;
+    }
+    count(tenant) {
+        return Object.keys(this.list(tenant)).length;
+    }
+    replace(catalog) {
+        this.catalog = catalog;
+    }
+}

package/dist/catalog/loader.test.d.ts

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