@thotischner/observability-mcp 3.6.1 → 3.8.0

package/dist/auth/policy/loader.js

@@ -27,7 +27,7 @@ import { BuiltinPolicyEngine } from "./engine.js";
 export const VALID_RESOURCES = new Set([
     "sources", "services", "health", "topology", "settings",
     "connectors", "audit", "catalog", "users", "redaction",
-    "products",
+    "products", "inspection",
 ]);
 export const VALID_ACTIONS = new Set(["read", "write", "delete", "bypass"]);
 export class PolicyLoadError extends Error {

package/dist/auth/rbac.d.ts

@@ -18,7 +18,7 @@ import type { RequestHandler } from "express";
 import type { AuthRuntime } from "./middleware.js";
 import type { PolicyEngine } from "./policy/engine.js";
 export type Action = "read" | "write" | "delete" | "bypass";
-export type Resource = "sources" | "services" | "health" | "topology" | "settings" | "connectors" | "audit" | "catalog" | "users" | "redaction" | "products";
+export type Resource = "sources" | "services" | "health" | "topology" | "settings" | "connectors" | "audit" | "catalog" | "users" | "redaction" | "products" | "inspection";
 export interface Permission {
     resource: Resource;
     action: Action;

package/dist/auth/rbac.js

@@ -30,6 +30,7 @@ export const DEFAULT_POLICY = {
         { resource: "audit", action: "read" },
         { resource: "catalog", action: "read" },
         { resource: "products", action: "read" },
+        { resource: "inspection", action: "read" },
     ],
     operator: [
         // Inherits viewer's read set + write on operational resources.
@@ -46,10 +47,11 @@ export const DEFAULT_POLICY = {
         { resource: "catalog", action: "read" },
         { resource: "products", action: "read" },
         { resource: "products", action: "write" },
+        { resource: "inspection", action: "read" },
     ],
     admin: [
         // Full surface — readable + writable + deletable.
-        ...["sources", "services", "health", "topology", "settings", "connectors", "audit", "catalog", "users", "products"]
+        ...["sources", "services", "health", "topology", "settings", "connectors", "audit", "catalog", "users", "products", "inspection"]
             .flatMap((r) => ["read", "write", "delete"].map((a) => ({ resource: r, action: a }))),
         // Special: admins may bypass log-redaction on per-call MCP tool
         // invocations (when the bearer credential ALSO opts in via

package/dist/auth/rbac.test.js

@@ -108,11 +108,13 @@ test("listGrantedPermissions — deduplicates across overlapping roles", () => {
 });
 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);
+    // 11 resources (added 'products' in the products-RBAC phase, 'inspection'
+    // in the Inspect phase) * 3 actions = 33, plus the special redaction:bypass
+    // entry = 34.
+    assert.equal(p.length, 34);
     assert.ok(p.some((g) => g.resource === "redaction" && g.action === "bypass"));
     assert.ok(p.some((g) => g.resource === "products" && g.action === "delete"));
+    assert.ok(p.some((g) => g.resource === "inspection" && g.action === "write"));
 });
 test("DEFAULT_POLICY shape — has the three built-in roles", () => {
     assert.ok(DEFAULT_POLICY.viewer);

package/dist/conformance/inspect-e2e.test.d.ts

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

package/dist/conformance/inspect-e2e.test.js

@@ -0,0 +1,104 @@
+// Inspect observe-path E2E (live).
+//
+// Proves the full chain: a real tools/call over the Streamable HTTP transport
+// is captured by the observe recorder and surfaces on /api/inspect/events +
+// /api/inspect/flows. Runs against a booted gateway via OMCP_CONFORMANCE_URL
+// (the same env the spec-conformance harness uses); skips entirely when unset
+// so a plain unit-test run stays hermetic.
+//
+//   OMCP_CONFORMANCE_URL=http://localhost:3000/mcp \
+//   npx tsx --test src/conformance/inspect-e2e.test.ts
+//
+// integration.yml runs this after booting the demo stack.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+const URL_ENV = process.env.OMCP_CONFORMANCE_URL;
+const skip = !URL_ENV;
+const opts = skip ? { skip: "OMCP_CONFORMANCE_URL not set" } : {};
+const base = (URL_ENV ?? "").replace(/\/mcp\/?$/, "");
+async function rpc(method, params, session) {
+    const headers = {
+        "content-type": "application/json",
+        accept: "application/json, text/event-stream",
+    };
+    if (session)
+        headers["mcp-session-id"] = session;
+    const res = await fetch(URL_ENV, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+    });
+    return { text: await res.text(), session: res.headers.get("mcp-session-id") ?? session };
+}
+test("observe: a real tools/call surfaces on /api/inspect/events and /flows", opts, async () => {
+    // 1. Handshake — open an MCP session.
+    const init = await rpc("initialize", {
+        protocolVersion: "2025-11-25",
+        capabilities: {},
+        clientInfo: { name: "inspect-e2e", version: "0" },
+    });
+    const session = init.session;
+    assert.ok(session, "server returned a session id");
+    await fetch(URL_ENV, {
+        method: "POST",
+        headers: { "content-type": "application/json", accept: "application/json, text/event-stream", "mcp-session-id": session },
+        body: JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized", params: {} }),
+    });
+    // 2. Make an observable tool call. list_sources is always registered and
+    //    needs no backend data, so it's a stable probe.
+    await rpc("tools/call", { name: "list_sources", arguments: {} }, session);
+    // 3. The observe recorder is synchronous on the post-invoke hook, but give
+    //    the event loop a tick before reading back.
+    await new Promise((r) => setTimeout(r, 250));
+    // 4. /api/inspect/events shows the call.
+    const evRes = await fetch(`${base}/api/inspect/events?tool=list_sources&limit=50`);
+    assert.equal(evRes.status, 200, "events endpoint reachable");
+    const ev = (await evRes.json());
+    assert.ok(["observe", "dryrun", "enforce"].includes(ev.mode), `recording mode active (got ${ev.mode})`);
+    assert.ok(ev.events.some((e) => e.tool === "list_sources" && e.decision === "allow"), "list_sources call was observed");
+    // 5. /api/inspect/flows includes the tool node + an edge into it.
+    const flRes = await fetch(`${base}/api/inspect/flows?window=1h`);
+    assert.equal(flRes.status, 200, "flows endpoint reachable");
+    const fl = (await flRes.json());
+    assert.ok(fl.total >= 1, "flow graph has traffic");
+    assert.ok(fl.nodes.some((n) => n.id === "tool:list_sources"), "tool node present in the flow graph");
+});
+test("/api/inspect/mode reports a recording mode", opts, async () => {
+    const res = await fetch(`${base}/api/inspect/mode`);
+    assert.equal(res.status, 200);
+    const m = (await res.json());
+    assert.ok(["off", "observe", "dryrun", "enforce"].includes(m.mode));
+});
+test("enforce is gated by entitlement; observe/dry-run are free", opts, async () => {
+    // CSRF double-submit: grab the issued token, echo it on every mutation.
+    const probe = await fetch(`${base}/api/inspect/mode`);
+    const sc = probe.headers.get("set-cookie") || "";
+    const tok = (sc.match(/omcp-csrf=([^;]+)/) || [])[1];
+    const csrf = tok ? { "x-csrf-token": decodeURIComponent(tok), cookie: `omcp-csrf=${tok}` } : {};
+    const write = (path, method, body) => fetch(`${base}${path}`, { method, headers: { "content-type": "application/json", ...csrf }, body: JSON.stringify(body) });
+    const modeBody = (await probe.json());
+    // Dry-run is always available (OSS).
+    const dry = await write("/api/inspect/mode", "PUT", { mode: "dryrun" });
+    assert.equal(dry.status, 200, "dry-run is free");
+    try {
+        const enf = await write("/api/inspect/mode", "PUT", { mode: "enforce" });
+        if (modeBody.enforceEntitled) {
+            // Licensed: enforce switches on and blocks out-of-profile calls.
+            assert.equal(enf.status, 200, "enforce accepted when entitled");
+            const init = await rpc("initialize", { protocolVersion: "2025-11-25", capabilities: {}, clientInfo: { name: "inspect-e2e", version: "0" } });
+            const session = init.session;
+            await fetch(URL_ENV, { method: "POST", headers: { "content-type": "application/json", accept: "application/json, text/event-stream", "mcp-session-id": session }, body: JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized", params: {} }) });
+            const blocked = await rpc("tools/call", { name: "list_services", arguments: {} }, session);
+            assert.match(blocked.text, /Blocked by the inspection profile|inspection profile/, "out-of-profile call blocked when entitled");
+        }
+        else {
+            // OSS default: enforce is refused with a clear entitlement error.
+            assert.equal(enf.status, 403, "enforce refused without entitlement");
+            const body = (await enf.json());
+            assert.equal(body.code, "OMCP_ENTITLEMENT_REQUIRED");
+        }
+    }
+    finally {
+        await write("/api/inspect/mode", "PUT", { mode: "observe" }).catch(() => { });
+    }
+});

package/dist/connectors/loader.js

@@ -96,19 +96,49 @@ export class PluginLoader {
         return instrumentConnector(c);
     }
     loadBuiltins() {
+        // Builtins carry inline manifest metadata so the Installed Connectors UI
+        // shows a name/description/version like filesystem plugins do (without it,
+        // describeInstalled() falls back to an empty description). Mirrors
+        // plugins/<name>/manifest.json — keep the description text in sync.
         this.register({
             name: "prometheus",
             source: "builtin",
+            manifest: {
+                schemaVersion: 1,
+                name: "prometheus",
+                displayName: "Prometheus",
+                version: "1.0.0",
+                description: "PromQL-based metrics backend with prom-client default scrape support and dynamic service-label resolution.",
+                signalTypes: ["metrics"],
+                capabilities: { queryMetrics: true, listServices: true, listAvailableMetrics: true },
+            },
             factory: () => new PrometheusConnector(),
         });
         this.register({
             name: "loki",
             source: "builtin",
+            manifest: {
+                schemaVersion: 1,
+                name: "loki",
+                displayName: "Loki",
+                version: "1.0.0",
+                description: "LogQL-based log backend with dynamic service-label discovery (service_name / service / job / app / container).",
+                signalTypes: ["logs"],
+                capabilities: { queryLogs: true, listServices: true },
+            },
             factory: () => new LokiConnector(),
         });
         this.register({
             name: "kubernetes",
             source: "builtin",
+            manifest: {
+                schemaVersion: 1,
+                name: "kubernetes",
+                displayName: "Kubernetes",
+                version: "0.1.0",
+                description: "Watches a Kubernetes cluster (in-cluster or via kubeconfig) and exposes pods, nodes, deployments, replicasets and namespaces as an infrastructure topology graph. Edges: RUNS_ON (pod→node), OWNED_BY (pod→rs→deployment), IN_NAMESPACE.",
+                signalTypes: ["topology"],
+            },
             factory: () => new KubernetesConnector(),
         });
     }

package/dist/connectors/loader.test.js

@@ -76,3 +76,14 @@ test("PluginLoader.load(): with verify on + no trust root → builtins still loa
         assert.ok(names.includes("kubernetes"), "kubernetes builtin must remain available");
     });
 });
+test("PluginLoader.load(): builtins carry manifest metadata (description shows in Installed Connectors)", async () => {
+    const loader = new PluginLoader({ pluginsDir: tmp() });
+    await loader.load();
+    for (const name of ["prometheus", "loki", "kubernetes"]) {
+        const c = loader.get(name);
+        assert.ok(c, `${name} builtin present`);
+        assert.ok(c.manifest, `${name} builtin has a manifest`);
+        assert.ok((c.manifest.description || "").length > 10, `${name} builtin has a non-empty description`);
+        assert.equal(c.manifest.name, name);
+    }
+});

package/dist/enrich/rdap.d.ts

@@ -0,0 +1,40 @@
+import type { IpEnrichment } from "./ip-dataset.js";
+/** Minimal fetch surface so tests can inject a stub (no real network). */
+export type FetchLike = (url: string, init?: {
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    json: () => Promise<unknown>;
+}>;
+export interface RdapResolverOptions {
+    /** Bootstrap base; rdap.org redirects to the authoritative RIR. */
+    baseUrl?: string;
+    /** Cache TTL in ms (default 1h). Negative results cached for a shorter time. */
+    ttlMs?: number;
+    /** Per-request timeout in ms (default 4000). */
+    timeoutMs?: number;
+    /** Injected fetch (defaults to global fetch). */
+    fetch?: FetchLike;
+    /** Max cache entries (LRU-ish trim). */
+    maxCache?: number;
+}
+/** Parse an RDAP IP-network response into our enrichment shape. country +
+ *  org/name only; RDAP carries no city or hosting flag. */
+export declare function parseRdapResponse(body: unknown): IpEnrichment | null;
+export declare class RdapResolver {
+    private readonly baseUrl;
+    private readonly ttlMs;
+    private readonly negTtlMs;
+    private readonly timeoutMs;
+    private readonly fetch;
+    private readonly maxCache;
+    private cache;
+    /** Monotonic clock injected for tests; defaults to Date.now via a getter. */
+    now: () => number;
+    constructor(opts?: RdapResolverOptions);
+    /** Look up one IP via RDAP. Returns null on miss/error (never throws —
+     *  a flaky RIR must not fail the batch). Cached by IP with a TTL. */
+    lookup(ip: string): Promise<IpEnrichment | null>;
+    private put;
+}

package/dist/enrich/rdap.js

@@ -0,0 +1,122 @@
+// Optional ONLINE IP enrichment via RDAP (RFC 9082/9083) — issue #477.
+//
+// OFF by default. The offline OMCP_IP_ENRICH_FILE dataset is the preferred,
+// air-gapped path; RDAP is a zero-setup fallback for non-air-gapped operators
+// who don't want to provision a MaxMind licence just to answer "where is this
+// IP / is it a datacenter". When enabled (OMCP_IP_ENRICH_RDAP=on) the gateway
+// queries the authoritative RIR over HTTPS via the rdap.org bootstrap.
+//
+// Privacy: RDAP queries the authoritative registry (not a third-party geo
+// broker) and yields country + org/network-name only (no city, no hosting
+// flag — same limits called out in #477). Results are cached with a TTL to
+// respect RIR rate limits.
+//
+// This module makes NO network call unless an operator has opted in and the
+// resolver is actually constructed (see index.ts) — the air-gapped default of
+// enrich_ips is preserved.
+import { ipv4ToInt, ipv6ToBigInt } from "./ip-dataset.js";
+/** Pull a display org name out of an RDAP entity's jCard (vcardArray). */
+function orgFromEntities(entities) {
+    if (!Array.isArray(entities))
+        return undefined;
+    // Prefer registrant, then any entity with an fn.
+    const ordered = [...entities].sort((a, b) => roleRank(b) - roleRank(a));
+    for (const e of ordered) {
+        const fn = fnFromVcard(e.vcardArray);
+        if (fn)
+            return fn;
+    }
+    return undefined;
+}
+function roleRank(e) {
+    const roles = e.roles;
+    if (Array.isArray(roles) && roles.includes("registrant"))
+        return 2;
+    if (Array.isArray(roles) && roles.includes("registrar"))
+        return 1;
+    return 0;
+}
+function fnFromVcard(vcardArray) {
+    // jCard shape: ["vcard", [ ["version",{},"text","4.0"], ["fn",{},"text","Google LLC"], ... ]]
+    if (!Array.isArray(vcardArray) || vcardArray.length < 2 || !Array.isArray(vcardArray[1]))
+        return undefined;
+    for (const prop of vcardArray[1]) {
+        if (Array.isArray(prop) && prop[0] === "fn" && typeof prop[3] === "string" && prop[3].trim()) {
+            return prop[3].trim();
+        }
+    }
+    return undefined;
+}
+/** Parse an RDAP IP-network response into our enrichment shape. country +
+ *  org/name only; RDAP carries no city or hosting flag. */
+export function parseRdapResponse(body) {
+    if (!body || typeof body !== "object")
+        return null;
+    const b = body;
+    const country = typeof b.country === "string" && b.country.trim() ? b.country.trim() : undefined;
+    const org = orgFromEntities(b.entities) || (typeof b.name === "string" && b.name.trim() ? b.name.trim() : undefined);
+    if (!country && !org)
+        return null;
+    const out = {};
+    if (country)
+        out.country = country;
+    if (org)
+        out.org = org;
+    return out;
+}
+export class RdapResolver {
+    baseUrl;
+    ttlMs;
+    negTtlMs;
+    timeoutMs;
+    fetch;
+    maxCache;
+    cache = new Map();
+    /** Monotonic clock injected for tests; defaults to Date.now via a getter. */
+    now;
+    constructor(opts = {}) {
+        this.baseUrl = (opts.baseUrl || "https://rdap.org").replace(/\/$/, "");
+        this.ttlMs = opts.ttlMs ?? 3_600_000;
+        this.negTtlMs = Math.min(this.ttlMs, 300_000);
+        this.timeoutMs = opts.timeoutMs ?? 4000;
+        this.fetch = opts.fetch ?? globalThis.fetch;
+        this.maxCache = opts.maxCache ?? 10_000;
+        this.now = () => Date.now();
+    }
+    /** Look up one IP via RDAP. Returns null on miss/error (never throws —
+     *  a flaky RIR must not fail the batch). Cached by IP with a TTL. */
+    async lookup(ip) {
+        if (ipv4ToInt(ip) === null && ipv6ToBigInt(ip) === null)
+            return null;
+        const cached = this.cache.get(ip);
+        if (cached && cached.expiresAt > this.now())
+            return cached.value;
+        let value = null;
+        try {
+            const ac = new AbortController();
+            const timer = setTimeout(() => ac.abort(), this.timeoutMs);
+            try {
+                const res = await this.fetch(`${this.baseUrl}/ip/${encodeURIComponent(ip)}`, { signal: ac.signal });
+                if (res.ok)
+                    value = parseRdapResponse(await res.json());
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+        catch {
+            value = null; // network/timeout/parse — treat as a miss
+        }
+        this.put(ip, { value, expiresAt: this.now() + (value ? this.ttlMs : this.negTtlMs) });
+        return value;
+    }
+    put(ip, entry) {
+        if (this.cache.size >= this.maxCache) {
+            // Drop the oldest insertion (Map preserves insertion order).
+            const oldest = this.cache.keys().next().value;
+            if (oldest !== undefined)
+                this.cache.delete(oldest);
+        }
+        this.cache.set(ip, entry);
+    }
+}

package/dist/enrich/rdap.test.d.ts

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

package/dist/enrich/rdap.test.js

@@ -0,0 +1,78 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { parseRdapResponse, RdapResolver } from "./rdap.js";
+// A realistic RDAP IP-network response (trimmed). org comes from the
+// registrant entity's jCard fn; country is top-level.
+const RDAP_GOOGLE = {
+    handle: "GOGL",
+    name: "GOGL",
+    country: "US",
+    entities: [
+        { roles: ["registrant"], vcardArray: ["vcard", [["version", {}, "text", "4.0"], ["fn", {}, "text", "Google LLC"]]] },
+    ],
+};
+describe("parseRdapResponse", () => {
+    it("extracts country + org (entity fn preferred over name)", () => {
+        assert.deepEqual(parseRdapResponse(RDAP_GOOGLE), { country: "US", org: "Google LLC" });
+    });
+    it("falls back to network `name` when no entity fn", () => {
+        assert.deepEqual(parseRdapResponse({ country: "DE", name: "DTAG" }), { country: "DE", org: "DTAG" });
+    });
+    it("returns null when neither country nor org is present", () => {
+        assert.equal(parseRdapResponse({ handle: "x" }), null);
+        assert.equal(parseRdapResponse(null), null);
+        assert.equal(parseRdapResponse("nope"), null);
+    });
+});
+function stubFetch(handler) {
+    const calls = [];
+    const fetch = async (url) => {
+        calls.push(url);
+        const r = handler(url);
+        return { ok: r.ok, status: r.status, json: async () => r.body };
+    };
+    return { fetch, calls };
+}
+describe("RdapResolver", () => {
+    it("looks up an IP and parses the response", async () => {
+        const { fetch, calls } = stubFetch(() => ({ ok: true, status: 200, body: RDAP_GOOGLE }));
+        const r = new RdapResolver({ fetch });
+        assert.deepEqual(await r.lookup("8.8.8.8"), { country: "US", org: "Google LLC" });
+        assert.equal(calls.length, 1);
+        assert.match(calls[0], /\/ip\/8\.8\.8\.8$/);
+    });
+    it("caches a hit — second lookup does not re-fetch", async () => {
+        const { fetch, calls } = stubFetch(() => ({ ok: true, status: 200, body: RDAP_GOOGLE }));
+        const r = new RdapResolver({ fetch });
+        await r.lookup("8.8.8.8");
+        await r.lookup("8.8.8.8");
+        assert.equal(calls.length, 1, "second lookup served from cache");
+    });
+    it("caches a negative result (miss) too", async () => {
+        const { fetch, calls } = stubFetch(() => ({ ok: false, status: 404, body: {} }));
+        const r = new RdapResolver({ fetch });
+        assert.equal(await r.lookup("203.0.113.7"), null);
+        assert.equal(await r.lookup("203.0.113.7"), null);
+        assert.equal(calls.length, 1, "negative result cached");
+    });
+    it("re-fetches after the TTL expires", async () => {
+        const { fetch, calls } = stubFetch(() => ({ ok: true, status: 200, body: RDAP_GOOGLE }));
+        const r = new RdapResolver({ fetch, ttlMs: 1000 });
+        let t = 1000;
+        r.now = () => t;
+        await r.lookup("8.8.8.8");
+        t = 2001; // past TTL
+        await r.lookup("8.8.8.8");
+        assert.equal(calls.length, 2, "expired entry re-fetched");
+    });
+    it("returns null for an invalid IP WITHOUT making a request", async () => {
+        const { fetch, calls } = stubFetch(() => ({ ok: true, status: 200, body: RDAP_GOOGLE }));
+        const r = new RdapResolver({ fetch });
+        assert.equal(await r.lookup("not-an-ip"), null);
+        assert.equal(calls.length, 0, "no network call for an invalid IP");
+    });
+    it("never throws on a fetch error — returns null", async () => {
+        const r = new RdapResolver({ fetch: (async () => { throw new Error("network down"); }) });
+        assert.equal(await r.lookup("8.8.8.8"), null);
+    });
+});

package/dist/enterprise-gate.d.ts

@@ -13,6 +13,8 @@ type GateState = {
     mode: "active";
     claims: Record<string, unknown>;
     accessControl: boolean;
+    inspectEnforce: boolean;
+    hasFeature: (feature: string) => boolean;
     enforceRbac?: (policy: unknown, ctx: unknown, req: unknown) => unknown;
     enforceCatalog?: (catalog: unknown, ctx: unknown, req: unknown) => unknown;
     rbacPolicy?: unknown;
@@ -25,6 +27,32 @@ type GateState = {
 export declare function _resetEnterpriseAudit(): void;
 /** Reset memoised state (tests only). */
 export declare function _resetEnterpriseGate(): void;
+/**
+ * Is the Inspect ENFORCE control entitled? Inspect observe/dry-run are free
+ * (OSS); only blocking enforcement requires the "inspect-enforce" feature on a
+ * valid entitlement token. Default-OFF (no token) → false, so OSS deployments
+ * keep observe/dry-run and simply can't switch to blocking enforce.
+ */
+export declare function inspectEnforceEntitled(): Promise<boolean>;
+/**
+ * Is a named entitlement feature active? True only with a valid entitlement
+ * token that carries the feature. Default-OFF (no token / enterprise modules
+ * absent) → false, never throws — so OSS deployments keep their free surface
+ * and a feature is only gated when the operator has actively configured it.
+ * Used to license SSO/OIDC ("sso"), SCIM ("scim"), multi-tenancy ("tenancy").
+ */
+export declare function featureEntitled(feature: string): Promise<boolean>;
+/** Every entitlement feature the product knows about — the closed vocabulary
+ *  the UI renders lock badges for. Keep in sync with the gates in index.ts. */
+export declare const ENTITLEABLE_FEATURES: readonly ["access-control", "audit", "inspect-enforce", "sso", "scim", "tenancy"];
+/**
+ * Resolve every known feature to whether it is currently entitled — one flat
+ * map for the UI to drive a consistent lock optic. Default-OFF (no token /
+ * enterprise modules absent) → all false; never throws. This is purely
+ * informational (visibility is free); the real enforcement lives in each
+ * feature's own gate.
+ */
+export declare function entitledFeatures(): Promise<Record<string, boolean>>;
 /** Gate mode — for diagnostics (/api/info). */
 export declare function enterpriseGateStatus(): Promise<{
     active: boolean;

package/dist/enterprise-gate.js

@@ -109,6 +109,8 @@ async function buildGate() {
         mode: "active",
         claims,
         accessControl: has("access-control"),
+        inspectEnforce: has("inspect-enforce"),
+        hasFeature: has,
     };
     // Audit (best-effort; only if entitled and the module loads). The log
     // is a PROCESS singleton, deliberately decoupled from the gate memo:
@@ -137,6 +139,55 @@ async function buildGate() {
 export function _resetEnterpriseGate() {
     gatePromise = null;
 }
+/**
+ * Is the Inspect ENFORCE control entitled? Inspect observe/dry-run are free
+ * (OSS); only blocking enforcement requires the "inspect-enforce" feature on a
+ * valid entitlement token. Default-OFF (no token) → false, so OSS deployments
+ * keep observe/dry-run and simply can't switch to blocking enforce.
+ */
+export async function inspectEnforceEntitled() {
+    return featureEntitled("inspect-enforce");
+}
+/**
+ * Is a named entitlement feature active? True only with a valid entitlement
+ * token that carries the feature. Default-OFF (no token / enterprise modules
+ * absent) → false, never throws — so OSS deployments keep their free surface
+ * and a feature is only gated when the operator has actively configured it.
+ * Used to license SSO/OIDC ("sso"), SCIM ("scim"), multi-tenancy ("tenancy").
+ */
+export async function featureEntitled(feature) {
+    if (!gatePromise)
+        gatePromise = buildGate();
+    const g = await gatePromise;
+    return g.mode === "active" && g.hasFeature(feature);
+}
+/** Every entitlement feature the product knows about — the closed vocabulary
+ *  the UI renders lock badges for. Keep in sync with the gates in index.ts. */
+export const ENTITLEABLE_FEATURES = [
+    "access-control",
+    "audit",
+    "inspect-enforce",
+    "sso",
+    "scim",
+    "tenancy",
+];
+/**
+ * Resolve every known feature to whether it is currently entitled — one flat
+ * map for the UI to drive a consistent lock optic. Default-OFF (no token /
+ * enterprise modules absent) → all false; never throws. This is purely
+ * informational (visibility is free); the real enforcement lives in each
+ * feature's own gate.
+ */
+export async function entitledFeatures() {
+    if (!gatePromise)
+        gatePromise = buildGate();
+    const g = await gatePromise;
+    const active = g.mode === "active";
+    const out = {};
+    for (const f of ENTITLEABLE_FEATURES)
+        out[f] = active && g.hasFeature(f);
+    return out;
+}
 /** Gate mode — for diagnostics (/api/info). */
 export async function enterpriseGateStatus() {
     if (!gatePromise)

package/dist/enterprise-gate.test.js

@@ -4,7 +4,7 @@ import { writeFileSync, mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { defaultContext } from "./context.js";
-import { enforceEntitledAccess, enterpriseGateStatus, enterpriseGateInfo, enterprisePolicyView, enterpriseCatalogView, enterpriseAuditTail, validatePolicyShape, validateCatalogShape, authorizeAdmin, _resetEnterpriseGate, } from "./enterprise-gate.js";
+import { enforceEntitledAccess, enterpriseGateStatus, enterpriseGateInfo, enterprisePolicyView, enterpriseCatalogView, enterpriseAuditTail, validatePolicyShape, validateCatalogShape, authorizeAdmin, featureEntitled, inspectEnforceEntitled, entitledFeatures, ENTITLEABLE_FEATURES, _resetEnterpriseGate, } from "./enterprise-gate.js";
 // These tests run in the mcp-server sandbox where enterprise/ is ABSENT
 // (it is excluded from the npm package and the Docker build context) —
 // exactly the published-artifact state. They pin the security contract:
@@ -55,6 +55,26 @@ describe("enterprise-gate — OFF (no opt-in, published-artifact state)", () =>
             await assert.doesNotReject(enforceEntitledAccess(defaultContext(), { tool }));
         }
     });
+    it("featureEntitled is false for every feature when OFF (OSS default)", async () => {
+        clearEnv();
+        // Default-OFF means no entitled feature is active — SSO/SCIM/tenancy/
+        // inspect-enforce all stay locked, so the OSS surface is unchanged and
+        // a feature only ever gates when the operator has actively licensed it.
+        for (const feature of ["sso", "scim", "tenancy", "inspect-enforce", "anything"]) {
+            assert.equal(await featureEntitled(feature), false, `feature ${feature} must be locked when OFF`);
+        }
+        assert.equal(await inspectEnforceEntitled(), false, "inspectEnforceEntitled mirrors featureEntitled");
+    });
+    it("entitledFeatures returns the full vocabulary, all false when OFF", async () => {
+        clearEnv();
+        const map = await entitledFeatures();
+        // Every known feature is present as a key (so the UI can render a badge
+        // for each) and false on the OSS default.
+        for (const f of ENTITLEABLE_FEATURES) {
+            assert.equal(map[f], false, `feature ${f} must be false when OFF`);
+        }
+        assert.deepEqual(Object.keys(map).sort(), [...ENTITLEABLE_FEATURES].sort());
+    });
     it("gate state is memoised across calls", async () => {
         clearEnv();
         assert.deepEqual(await enterpriseGateStatus(), await enterpriseGateStatus());