@thotischner/observability-mcp 3.7.0 → 3.8.1

package/dist/index.js

@@ -10,8 +10,8 @@ import { loadConfig, saveConfig, DEFAULT_HEALTH_THRESHOLDS, DEFAULT_SETTINGS } f
 import { ConnectorRegistry, getSupportedTypes } from "./connectors/registry.js";
 import { isTopologyProvider } from "./connectors/interface.js";
 import { defaultContext, principalContext, sessionContext, allowsTool } from "./context.js";
-import { parseKeyTenants } from "./tenancy/context.js";
-import { enforceEntitledAccess, enterpriseGateStatus, enterpriseGateInfo, enterprisePolicyView, enterpriseCatalogView, enterpriseAuditTail, authorizeAdmin, updateRbacPolicy, updateCatalog, } from "./enterprise-gate.js";
+import { parseKeyTenants, isMultiTenantConfigured } from "./tenancy/context.js";
+import { enforceEntitledAccess, enterpriseGateStatus, enterpriseGateInfo, enterprisePolicyView, enterpriseCatalogView, enterpriseAuditTail, authorizeAdmin, updateRbacPolicy, updateCatalog, inspectEnforceEntitled, featureEntitled, entitledFeatures, } from "./enterprise-gate.js";
 import { loadCredentials, credentialsConfigured, extractToken, resolveToken, } from "./auth/credentials.js";
 import { issueSession, setCookieHeader, clearCookieHeader, generateSecret, } from "./auth/session.js";
 import { readUsersFile, writeUsersFile, authenticate, } from "./auth/local-users.js";
@@ -45,10 +45,11 @@ import { getPluginLoader } from "./connectors/loader.js";
 import { resolveHubCatalogUrl, describeInstalled, mergeCatalog, fetchHubCatalog, } from "./connectors/hub.js";
 import { isValidConnectorName, installTarball } from "./connectors/install.js";
 import { PluginVerificationError } from "./connectors/verify.js";
-import { selfRegistry, withToolMetrics, apiRequests, mcpActiveSessions, auditDlqDepth } from "./metrics/self.js";
+import { selfRegistry, withToolMetrics, apiRequests, mcpActiveSessions, auditDlqDepth, recordInspectEvent } from "./metrics/self.js";
 import { initOtel } from "./observability/otel.js";
 import { WebSocketServerTransport } from "./transport/websocket.js";
 import { HookRegistry } from "./sdk/hooks.js";
+import { InspectStore, ModeController, bootMode, createInspectRecorder, createInspectEnforcer, buildFlowGraph, durationToSeconds, ProfileStore } from "./inspect/index.js";
 import { wrapToolHandler, wrapResourceHandler, wrapPromptHandler } from "./sdk/hook-wrappers.js";
 import { UpstreamClient } from "./federation/upstream.js";
 import { FederationRegistry, parseFederationEnv } from "./federation/registry.js";
@@ -864,6 +865,9 @@ async function main() {
     let usersStore = null;
     let secretEphemeral = false;
     let oidcRuntime;
+    // Captured so the multi-tenancy entitlement gate below can tell whether
+    // OIDC is configured to read a tenant claim (non-empty → tenant'd logins).
+    let oidcTenantClaim = "";
     if (requestedAuthMode === "basic") {
         const usersPath = process.env.OMCP_USERS_FILE;
         if (!usersPath) {
@@ -894,8 +898,18 @@ async function main() {
         }
     }
     else if (requestedAuthMode === "oidc") {
+        // SSO/OIDC is an entitled control. The OSS surface — anonymous, basic
+        // (local users), and API-key auth — stays free and unchanged; only
+        // delegating identity to an external IdP requires the `sso` entitlement.
+        // Fail-closed when actively requested without it (respects the same
+        // OMCP_AUTH_ALLOW_FALLBACK escape hatch as every other auth misconfig);
+        // a deployment that never sets OMCP_AUTH=oidc is never affected.
         const r = resolveOidcConfig(process.env);
-        if (r.error || !r.config) {
+        if (!(await featureEntitled("sso"))) {
+            authMisconfig("OMCP_AUTH=oidc (SSO) requires an entitlement (sso feature). " +
+                "Use OMCP_AUTH=basic or api-key for the open-source single-sign-on-free setup");
+        }
+        else if (r.error || !r.config) {
             authMisconfig(r.error ?? "OIDC misconfigured");
         }
         else {
@@ -910,12 +924,35 @@ async function main() {
             sessionCfg = { secret };
             authMode = "oidc";
             oidcRuntime = buildOidcRuntime(r.config);
+            oidcTenantClaim = r.config.tenantClaim ?? "";
             console.log(`[auth] OIDC mode active — issuer=${r.config.issuer} clientId=${r.config.clientId} rolesClaim=${r.config.rolesClaim} mappedRoles=${Object.keys(r.config.roleMap).length}`);
         }
     }
     else if (requestedAuthMode !== "anonymous") {
         authMisconfig(`unknown OMCP_AUTH=${requestedAuthMode}`);
     }
+    // Multi-tenancy is an entitled control. The gateway is ALWAYS tenant-scoped,
+    // but every principal lands in DEFAULT_TENANT unless the operator actively
+    // maps identities to NON-default tenants — so the single-tenant default (the
+    // OSS path: anonymous, basic, api-key, or OIDC without a tenant claim) is
+    // free and bit-for-bit unchanged. It becomes "actively multi-tenant" only
+    // when an OIDC tenant claim is configured, or OMCP_KEY_TENANTS maps a
+    // credential to a non-default tenant. That configuration requires the
+    // `tenancy` entitlement; without it we fail closed and refuse to start,
+    // rather than silently collapsing isolated tenants into one (which could
+    // merge data across tenant boundaries). Single-tenant deployments never hit
+    // this branch.
+    const tenancyConfigured = isMultiTenantConfigured(oidcTenantClaim, process.env.OMCP_KEY_TENANTS);
+    if (tenancyConfigured && !(await featureEntitled("tenancy"))) {
+        const which = oidcTenantClaim
+            ? `an OIDC tenant claim (${oidcTenantClaim})`
+            : "OMCP_KEY_TENANTS with non-default tenants";
+        console.error(`[tenancy] ${which} configures multi-tenant isolation, which requires an ` +
+            "entitlement (tenancy feature) — refusing to start (fail-closed). " +
+            "For the open-source single-tenant setup, omit OMCP_OIDC_TENANT_CLAIM and " +
+            "keep OMCP_KEY_TENANTS at the default tenant.");
+        process.exit(1);
+    }
     // Session revocation blocklist (Q17). Only meaningful when sessions
     // exist (basic / oidc); anonymous mode leaves it undefined so the
     // middleware check is a pure no-op. OMCP_AUTH_REVOCATION_FILE persists
@@ -1216,6 +1253,50 @@ async function main() {
     // tool_pre_invoke / tool_post_invoke chains; resource and prompt
     // hooks plug into their respective seams as they ship.
     const hookRegistry = new HookRegistry();
+    // Inspect (observe/learn/enforce). The recorder registers as a permissive
+    // tool_post_invoke hook so it can never block or slow a tool call. Mode
+    // defaults to "observe" (record-only, zero decision); OMCP_INSPECT can set
+    // off/dryrun/enforce at boot, and the API can switch it at runtime. Profile
+    // evaluation (dry-run/enforce) is wired in a later phase.
+    const inspectStore = new InspectStore({ file: process.env.OMCP_INSPECT_FILE?.trim() || undefined });
+    // Inspect ENFORCE (active blocking) is an entitled control; observe/dry-run
+    // are free (OSS). Resolve the entitlement once at boot.
+    const inspectEnforceAllowed = await inspectEnforceEntitled();
+    // SCIM provisioning is likewise an entitled control. OFF by default (no
+    // OMCP_SCIM_TOKEN) so the OSS surface is unchanged; resolve the entitlement
+    // once here so both /api/info and the route-mount block agree.
+    const scimConfigured = !!process.env.OMCP_SCIM_TOKEN?.trim();
+    const scimEntitled = scimConfigured && (await featureEntitled("scim"));
+    // One flat map of every entitled feature → bool, surfaced on /api/info so
+    // the UI can render a consistent lock optic. Resolved once at boot (the
+    // entitlement token is read at startup and never changes at runtime).
+    const entitlements = await entitledFeatures();
+    let inspectBootMode = bootMode(process.env.OMCP_INSPECT);
+    if (inspectBootMode === "enforce" && !inspectEnforceAllowed) {
+        console.warn("[inspect] OMCP_INSPECT=enforce requires an entitlement (inspect-enforce); running in dry-run.");
+        inspectBootMode = "dryrun";
+    }
+    const inspectMode = new ModeController(inspectBootMode);
+    // Behavior profile (the learned ruleset). Accepted rules drive the
+    // evaluator: in dry-run the recorder records a `would-block` deviation for
+    // calls outside the profile (never blocks — enforce blocking is a later
+    // phase). Persists to OMCP_INSPECT_PROFILE_FILE when set.
+    const inspectProfile = new ProfileStore({ file: process.env.OMCP_INSPECT_PROFILE_FILE?.trim() || undefined });
+    hookRegistry.register(createInspectRecorder(inspectStore, inspectMode, {
+        onEvent: (e) => recordInspectEvent(e.tool, e.outcome, e.decision),
+        evaluator: inspectProfile,
+    }));
+    // Enforcer: pre-invoke gate that blocks (and records) calls outside the
+    // accepted profile — only when mode is `enforce`. Pass-through otherwise.
+    hookRegistry.register(createInspectEnforcer(inspectStore, inspectMode, inspectProfile, {
+        onEvent: (e) => recordInspectEvent(e.tool, e.outcome, e.decision),
+        // Belt-and-suspenders: never block without the enforce entitlement, even
+        // if the mode were somehow set to enforce.
+        enforceAllowed: () => inspectEnforceAllowed,
+    }));
+    if (inspectMode.get() !== "observe") {
+        console.log(`[inspect] mode=${inspectMode.get()} (store ${inspectStore.persisted ? "persisted" : "in-memory"})`);
+    }
     // Phase F15: anomaly-history sink — opt-in via
     // OMCP_ANOMALY_HISTORY_REMOTE_WRITE. When configured, anomaly
     // scores written via anomalyHistory.record() flush to the
@@ -1560,7 +1641,16 @@ async function main() {
                     .getAll()
                     .filter((c) => typeof c.queryTraces === "function").length,
                 pluginsVerified: !/^(0|false|no|off)$/i.test(process.env.VERIFY_PLUGINS ?? "true"),
-                scimEnabled: !!process.env.OMCP_SCIM_TOKEN,
+                scimEnabled: scimEntitled,
+                scimConfigured,
+                // Active multi-tenancy (non-default tenants configured). When true the
+                // server is running, so the `tenancy` entitlement is necessarily
+                // present — an unentitled multi-tenant config fails closed at boot.
+                multiTenant: tenancyConfigured,
+                // Per-feature entitlement map ({ "access-control": bool, audit, sso,
+                // scim, tenancy, "inspect-enforce" }) so the UI shows a lock badge on
+                // every entitled feature. All false on the OSS default (no token).
+                entitlements,
                 federationUpstreams: (process.env.OMCP_FEDERATION_UPSTREAMS ?? "")
                     .split(",").map((s) => s.trim()).filter(Boolean).length,
             },
@@ -1999,6 +2089,184 @@ async function main() {
             scopedTo: tenantFilter || (isAdmin ? null : callerTenant),
         });
     });
+    // --- /api/inspect — observe/learn/enforce surface (Inspect feature) ---
+    // Reads need inspection:read; the mode switch needs inspection:write and is
+    // audited. Non-admin callers are scoped to their own tenant's observations;
+    // a cross-tenant admin sees all (or ?tenant=acme to filter).
+    const inspectScope = (req) => {
+        const sess = req.session;
+        const isAdmin = hasPermission(sess?.roles, "users", "delete");
+        return isAdmin ? (qstr(req.query.tenant) || null) : (sess?.tenant || "default");
+    };
+    app.get("/api/inspect/mode", need("inspection", "read"), (_req, res) => {
+        res.json({
+            mode: inspectMode.get(),
+            recording: inspectMode.recording,
+            evaluating: inspectMode.evaluating,
+            blocking: inspectMode.blocking,
+            size: inspectStore.size,
+            persisted: inspectStore.persisted,
+            // observe/dry-run are free; enforce (active blocking) is an entitled
+            // control. The UI uses this to lock the Enforce option when unlicensed.
+            enforceEntitled: inspectEnforceAllowed,
+        });
+    });
+    app.put("/api/inspect/mode", need("inspection", "write"), audit("inspection", "write"), (req, res) => {
+        const body = req.body;
+        // Enforce (active blocking) requires the inspect-enforce entitlement;
+        // observe/dry-run are always available. Refuse the switch otherwise.
+        if (typeof body?.mode === "string" && body.mode.trim().toLowerCase() === "enforce" && !inspectEnforceAllowed) {
+            res.status(403).json({
+                error: "Enforce mode requires an entitlement (inspect-enforce). Observe and dry-run are available without a license.",
+                code: "OMCP_ENTITLEMENT_REQUIRED",
+            });
+            return;
+        }
+        try {
+            const m = inspectMode.set(body?.mode);
+            res.json({ mode: m });
+        }
+        catch (e) {
+            res.status(400).json({ error: e instanceof Error ? e.message : "invalid mode" });
+        }
+    });
+    app.get("/api/inspect/events", need("inspection", "read"), (req, res) => {
+        const tenant = inspectScope(req);
+        let events = inspectStore.list({
+            from: qstr(req.query.from),
+            to: qstr(req.query.to),
+            principal: qstr(req.query.principal),
+            tool: qstr(req.query.tool),
+            outcome: qstr(req.query.outcome),
+            decision: qstr(req.query.decision),
+            limit: qstr(req.query.limit) ? parseInt(qstr(req.query.limit), 10) : undefined,
+        });
+        if (tenant)
+            events = events.filter((e) => e.tenant === tenant);
+        // Backend drill-down (G1): narrow to one backend (the most-specific
+        // resource dim — service|source|namespace, matching the flow graph's
+        // backend node). Applied client-of-store side so the ring filters stay
+        // generic.
+        const backend = qstr(req.query.backend);
+        if (backend) {
+            events = events.filter((e) => (e.service || e.source || e.namespace || "(unrouted)") === backend);
+        }
+        res.json({ events, mode: inspectMode.get(), persisted: inspectStore.persisted, scopedTo: tenant });
+    });
+    app.get("/api/inspect/flows", need("inspection", "read"), (req, res) => {
+        const tenant = inspectScope(req);
+        const windowSecs = durationToSeconds(qstr(req.query.window) || "24h") ?? 86400;
+        const sinceMs = Date.now() - windowSecs * 1000;
+        let obs = inspectStore.since(sinceMs);
+        if (tenant)
+            obs = obs.filter((e) => e.tenant === tenant);
+        const graph = buildFlowGraph(obs, { sinceMs });
+        res.json({ ...graph, mode: inspectMode.get(), scopedTo: tenant });
+    });
+    app.get("/api/inspect/profile", need("inspection", "read"), (_req, res) => {
+        const rules = inspectProfile.list();
+        res.json({
+            rules,
+            counts: {
+                total: rules.length,
+                suggested: rules.filter((r) => r.status === "suggested").length,
+                accepted: rules.filter((r) => r.status === "accepted").length,
+                rejected: rules.filter((r) => r.status === "rejected").length,
+            },
+            persisted: inspectProfile.persisted,
+        });
+    });
+    // Learn: derive suggested rules from the observed window. Mutating (writes
+    // the suggested set) → inspection:write + audited.
+    app.post("/api/inspect/profile/derive", need("inspection", "write"), audit("inspection", "write"), (req, res) => {
+        const windowSecs = durationToSeconds(qstr(req.query.window) || "24h") ?? 86400;
+        const obs = inspectStore.since(Date.now() - windowSecs * 1000);
+        const rules = inspectProfile.derive(obs);
+        res.json({ rules, learnedFrom: obs.length, suggested: inspectProfile.suggested().length });
+    });
+    // Accept / reject / reset a rule, or edit its constraints.
+    app.patch("/api/inspect/profile/rules/:id", need("inspection", "write"), audit("inspection", "write"), (req, res) => {
+        const id = String(req.params.id);
+        const body = (req.body || {});
+        if (body.status != null) {
+            const status = String(body.status);
+            if (!["suggested", "accepted", "rejected"].includes(status)) {
+                res.status(400).json({ error: "status must be suggested|accepted|rejected" });
+                return;
+            }
+            const r = inspectProfile.setStatus(id, status);
+            if (!r) {
+                res.status(404).json({ error: "rule not found" });
+                return;
+            }
+            res.json({ rule: r });
+            return;
+        }
+        if (body.constraints != null || body.subject != null) {
+            const r = inspectProfile.update(id, {
+                constraints: body.constraints,
+                subject: typeof body.subject === "string" ? body.subject : undefined,
+            });
+            if (!r) {
+                res.status(404).json({ error: "rule not found" });
+                return;
+            }
+            res.json({ rule: r });
+            return;
+        }
+        res.status(400).json({ error: "provide status or constraints/subject" });
+    });
+    app.delete("/api/inspect/profile/rules/:id", need("inspection", "write"), audit("inspection", "write"), (req, res) => {
+        const ok = inspectProfile.remove(String(req.params.id));
+        if (!ok) {
+            res.status(404).json({ error: "rule not found" });
+            return;
+        }
+        res.json({ ok: true });
+    });
+    // Deviation → rule (one click): absorb exactly this observed call shape into
+    // the accepted profile (widen the matching rule, or create a tight one).
+    app.post("/api/inspect/profile/from-deviation", need("inspection", "write"), audit("inspection", "write"), (req, res) => {
+        const b = (req.body || {});
+        const principal = typeof b.principal === "string" ? b.principal : "";
+        const tool = typeof b.tool === "string" ? b.tool : "";
+        if (!principal || !tool) {
+            res.status(400).json({ error: "principal and tool are required" });
+            return;
+        }
+        const str = (v) => (typeof v === "string" && v ? v : undefined);
+        const argShape = {};
+        if (b.argShape && typeof b.argShape === "object") {
+            // The arg-shape KEY is remote input. Accept only a conservative
+            // identifier charset (arg names are simple tokens) and never the
+            // prototype-polluting names — barrier for js/remote-property-injection
+            // and prototype pollution.
+            const SAFE_ARG_KEY = /^[A-Za-z0-9_.-]{1,64}$/;
+            for (const [k, v] of Object.entries(b.argShape)) {
+                if (!SAFE_ARG_KEY.test(k) || k === "__proto__" || k === "constructor" || k === "prototype")
+                    continue;
+                if (typeof v === "string")
+                    argShape[k] = v;
+            }
+        }
+        const rule = inspectProfile.absorb({
+            principal, tool,
+            source: str(b.source), service: str(b.service), namespace: str(b.namespace),
+            argShape,
+        });
+        res.json({ rule });
+    });
+    // Deviations: calls in the window that fell outside the accepted profile
+    // (decision != allow). In dry-run these are would-block; in enforce, blocked.
+    app.get("/api/inspect/deviations", need("inspection", "read"), (req, res) => {
+        const tenant = inspectScope(req);
+        const windowSecs = durationToSeconds(qstr(req.query.window) || "24h") ?? 86400;
+        let evs = inspectStore.since(Date.now() - windowSecs * 1000).filter((e) => e.decision !== "allow");
+        if (tenant)
+            evs = evs.filter((e) => e.tenant === tenant);
+        evs.reverse(); // newest first
+        res.json({ deviations: evs, total: evs.length, mode: inspectMode.get(), scopedTo: tenant });
+    });
     // --- /api/audit/dlq — webhook-sink dead-letter queue surface (P9) ---
     // When the audit webhook is configured AND the receiver exhausted
     // its retry budget, entries land in the DLQ file. This endpoint
@@ -2283,7 +2551,18 @@ async function main() {
     // multi-replica deployments stay coherent (Q6); the redis client is
     // built from OMCP_SCIM_REDIS_URL here, mirroring the session store.
     const scimToken = process.env.OMCP_SCIM_TOKEN?.trim();
-    if (scimToken) {
+    // SCIM provisioning is an entitled control (entitlement resolved at boot as
+    // `scimEntitled`). OFF by default (no OMCP_SCIM_TOKEN) → OSS surface
+    // unchanged. Configured without the `scim` entitlement → fail closed: the
+    // /scim/v2/* routes are NOT mounted and the dashboard store stays empty, so
+    // no unentitled provisioning can happen — and the gateway keeps running (a
+    // missing IdP integration must not take the whole server down).
+    if (scimToken && !scimEntitled) {
+        console.error("[scim] OMCP_SCIM_TOKEN is set but SCIM provisioning requires an entitlement " +
+            "(scim feature) — refusing to mount /scim/v2/* (fail-closed). " +
+            "Unset OMCP_SCIM_TOKEN to silence this, or provision an entitlement.");
+    }
+    if (scimToken && scimEntitled) {
         try {
             const scimBackend = (process.env.OMCP_SCIM_BACKEND?.trim() || "file");
             let scimRedis;

package/dist/inspect/enforcer.d.ts

@@ -0,0 +1,19 @@
+import type { HookRegistration } from "../sdk/hooks.js";
+import type { InspectStore } from "./store.js";
+import type { ModeController } from "./mode.js";
+import { type ProfileEvaluator } from "./recorder.js";
+export interface EnforcerOptions {
+    onEvent?: (e: {
+        tool: string;
+        outcome: "ok" | "error";
+        decision: "blocked";
+    }) => void;
+    /** Entitlement gate — when it returns false, the enforcer never blocks (enforce
+     *  is an entitled control; observe/dry-run are free). Defaults to allowed. */
+    enforceAllowed?: () => boolean;
+}
+/**
+ * Build the enforce-mode pre-invoke hook. Blocks (and records) calls outside
+ * the accepted profile only when mode is `enforce`; pass-through otherwise.
+ */
+export declare function createInspectEnforcer(store: InspectStore, mode: ModeController, evaluator: ProfileEvaluator, opts?: EnforcerOptions): HookRegistration;

package/dist/inspect/enforcer.js

@@ -0,0 +1,69 @@
+// Inspect — the enforcer.
+//
+// A `tool_pre_invoke` hook that BLOCKS calls falling outside the accepted
+// profile, but ONLY when the mode is `enforce`. In observe/dry-run it is a
+// pass-through (dry-run's would-block recording happens in the post-invoke
+// recorder). When it blocks, it records a `blocked` observation itself —
+// because a pre-invoke denial short-circuits the dispatch, so the post-invoke
+// recorder never runs for blocked calls (no double-recording).
+//
+// Fail-open: any internal error returns allow:true. An inspector bug must
+// never become a denial-of-service for the agent's tools.
+import { redactValue } from "../policy/redact.js";
+import { deriveSignature } from "./signature.js";
+import { authKind } from "./recorder.js";
+/**
+ * Build the enforce-mode pre-invoke hook. Blocks (and records) calls outside
+ * the accepted profile only when mode is `enforce`; pass-through otherwise.
+ */
+export function createInspectEnforcer(store, mode, evaluator, opts = {}) {
+    const handler = (ctx, payload) => {
+        try {
+            if (!mode.blocking)
+                return { allow: true };
+            // Enforce blocking is an entitled control; without it, pass through.
+            if (opts.enforceAllowed && !opts.enforceAllowed())
+                return { allow: true };
+            const red = redactValue(payload.args);
+            const sig = deriveSignature(ctx.target, red.value);
+            const ev = evaluator.evaluate({
+                principal: ctx.principal, tool: ctx.target,
+                source: sig.source, service: sig.service, namespace: sig.namespace,
+                argShape: sig.argShape,
+            });
+            if (ev.verdict === "deviation") {
+                store.record({
+                    principal: ctx.principal,
+                    auth: authKind(ctx.principal),
+                    tenant: ctx.tenant,
+                    tool: ctx.target,
+                    source: sig.source,
+                    service: sig.service,
+                    namespace: sig.namespace,
+                    argShape: sig.argShape,
+                    outcome: "error",
+                    decision: "blocked",
+                    deviation: ev.kind,
+                    redactions: red.totalMatches,
+                });
+                opts.onEvent?.({ tool: ctx.target, outcome: "error", decision: "blocked" });
+                return {
+                    allow: false,
+                    reason: `Blocked by the inspection profile (${ev.kind ?? "deviation"}). This call falls outside the accepted baseline for ${ctx.principal}; review it under Inspect → Deviations.`,
+                };
+            }
+        }
+        catch {
+            // Fail open — an inspector error must never block a tool call.
+            return { allow: true };
+        }
+        return { allow: true };
+    };
+    return {
+        pluginName: "inspect-enforcer",
+        kind: "tool_pre_invoke",
+        priority: 5,
+        mode: "permissive",
+        handler,
+    };
+}

package/dist/inspect/enforcer.test.d.ts

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

package/dist/inspect/enforcer.test.js

@@ -0,0 +1,76 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { createInspectEnforcer } from "./enforcer.js";
+import { InspectStore } from "./store.js";
+import { ModeController } from "./mode.js";
+const ctx = (over = {}) => ({
+    principal: "key:bot", tenant: "default", kind: "tool_pre_invoke", target: "query_logs", ...over,
+});
+const allowEval = { evaluate: () => ({ verdict: "allow" }) };
+const denyEval = { evaluate: () => ({ verdict: "deviation", kind: "new-resource" }) };
+describe("createInspectEnforcer", () => {
+    it("registers as a permissive tool_pre_invoke hook", () => {
+        const reg = createInspectEnforcer(new InspectStore(), new ModeController("enforce"), allowEval);
+        assert.equal(reg.kind, "tool_pre_invoke");
+        assert.equal(reg.mode, "permissive");
+        assert.equal(reg.pluginName, "inspect-enforcer");
+    });
+    it("enforce: BLOCKS a deviation and records a blocked observation", async () => {
+        const store = new InspectStore();
+        const reg = createInspectEnforcer(store, new ModeController("enforce"), denyEval);
+        const r = await reg.handler(ctx({ target: "query_logs" }), { args: { service: "novel" } });
+        assert.equal(r.allow, false);
+        assert.match(r.reason, /Blocked by the inspection profile/);
+        assert.match(r.reason, /new-resource/);
+        const o = store.all()[0];
+        assert.equal(o.decision, "blocked");
+        assert.equal(o.deviation, "new-resource");
+        assert.equal(o.tool, "query_logs");
+    });
+    it("enforce: ALLOWS an in-profile call and records nothing (post-invoke recorder will)", async () => {
+        const store = new InspectStore();
+        const reg = createInspectEnforcer(store, new ModeController("enforce"), allowEval);
+        const r = await reg.handler(ctx(), { args: {} });
+        assert.deepEqual(r, { allow: true });
+        assert.equal(store.size, 0);
+    });
+    it("observe + dry-run never block (pass-through, no eval)", async () => {
+        for (const mode of ["off", "observe", "dryrun"]) {
+            let consulted = false;
+            const evaluator = { evaluate: () => { consulted = true; return { verdict: "deviation", kind: "new-tool" }; } };
+            const store = new InspectStore();
+            const reg = createInspectEnforcer(store, new ModeController(mode), evaluator);
+            const r = await reg.handler(ctx(), { args: {} });
+            assert.deepEqual(r, { allow: true }, `mode=${mode} must pass through`);
+            assert.equal(consulted, false, `mode=${mode} must not evaluate`);
+            assert.equal(store.size, 0);
+        }
+    });
+    it("never blocks when the enforce entitlement is absent (enforceAllowed=false)", async () => {
+        const store = new InspectStore();
+        const reg = createInspectEnforcer(store, new ModeController("enforce"), denyEval, { enforceAllowed: () => false });
+        const r = await reg.handler(ctx(), { args: { service: "novel" } });
+        assert.deepEqual(r, { allow: true }, "unlicensed enforce must not block");
+        assert.equal(store.size, 0, "nothing recorded as blocked when unlicensed");
+    });
+    it("blocks when the enforce entitlement is present (enforceAllowed=true)", async () => {
+        const reg = createInspectEnforcer(new InspectStore(), new ModeController("enforce"), denyEval, { enforceAllowed: () => true });
+        const r = await reg.handler(ctx(), { args: {} });
+        assert.equal(r.allow, false);
+    });
+    it("fails OPEN — an evaluator that throws never blocks the call", async () => {
+        const store = new InspectStore();
+        const boom = { evaluate: () => { throw new Error("inspector bug"); } };
+        const reg = createInspectEnforcer(store, new ModeController("enforce"), boom);
+        const r = await reg.handler(ctx(), { args: {} });
+        assert.deepEqual(r, { allow: true });
+    });
+    it("fires the onEvent metrics seam on a block", async () => {
+        const seen = [];
+        const reg = createInspectEnforcer(new InspectStore(), new ModeController("enforce"), denyEval, {
+            onEvent: (e) => seen.push(e),
+        });
+        await reg.handler(ctx({ target: "enrich_ips" }), { args: {} });
+        assert.deepEqual(seen, [{ tool: "enrich_ips", outcome: "error", decision: "blocked" }]);
+    });
+});

package/dist/inspect/graph.d.ts

@@ -0,0 +1,33 @@
+import type { Observation } from "./store.js";
+export type FlowNodeKind = "identity" | "tool" | "backend";
+export interface FlowNode {
+    id: string;
+    kind: FlowNodeKind;
+    label: string;
+    calls: number;
+    errors: number;
+    deviations: number;
+}
+export interface FlowEdge {
+    from: string;
+    to: string;
+    count: number;
+    allow: number;
+    deviation: number;
+    denied: number;
+}
+export interface FlowGraph {
+    nodes: FlowNode[];
+    edges: FlowEdge[];
+    total: number;
+    windowMs: number | null;
+    generatedFrom: number;
+}
+/** The backend a call targeted: the most specific resource dimension. */
+export declare function backendOf(o: Observation): string;
+export interface BuildFlowOptions {
+    /** Only include observations at or after this epoch-ms instant. */
+    sinceMs?: number;
+}
+/** Build the flow graph from a list of observations. */
+export declare function buildFlowGraph(observations: Observation[], opts?: BuildFlowOptions): FlowGraph;

package/dist/inspect/graph.test.d.ts

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

package/dist/inspect/graph.test.js

@@ -0,0 +1,74 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { buildFlowGraph, backendOf } from "./graph.js";
+let seq = 0;
+function obs(over = {}) {
+    return {
+        ts: new Date(1_700_000_000_000 + seq * 1000).toISOString(),
+        seq: ++seq,
+        principal: "key:bot",
+        auth: "apikey",
+        tenant: "default",
+        tool: "query_logs",
+        argShape: {},
+        outcome: "ok",
+        decision: "allow",
+        redactions: 0,
+        ...over,
+    };
+}
+describe("backendOf", () => {
+    it("prefers service > source > namespace > (unrouted)", () => {
+        assert.equal(backendOf(obs({ service: "pay", source: "p", namespace: "n" })), "pay");
+        assert.equal(backendOf(obs({ source: "p", namespace: "n" })), "p");
+        assert.equal(backendOf(obs({ namespace: "n" })), "n");
+        assert.equal(backendOf(obs({})), "(unrouted)");
+    });
+});
+describe("buildFlowGraph", () => {
+    it("builds identity→tool→backend nodes and edges", () => {
+        const g = buildFlowGraph([
+            obs({ principal: "alice", tool: "query_logs", service: "pay" }),
+            obs({ principal: "alice", tool: "query_logs", service: "pay" }),
+            obs({ principal: "bob", tool: "query_metrics", source: "prom" }),
+        ]);
+        assert.equal(g.total, 3);
+        const kinds = g.nodes.reduce((m, n) => ((m[n.kind] = (m[n.kind] || 0) + 1), m), {});
+        assert.equal(kinds.identity, 2);
+        assert.equal(kinds.tool, 2);
+        assert.equal(kinds.backend, 2);
+        // alice→query_logs edge has count 2
+        const e = g.edges.find((x) => x.from === "identity:alice" && x.to === "tool:query_logs");
+        assert.equal(e?.count, 2);
+        assert.equal(e?.allow, 2);
+    });
+    it("breaks edges down by decision and counts node errors/deviations", () => {
+        const g = buildFlowGraph([
+            obs({ principal: "a", tool: "t", service: "s", decision: "allow", outcome: "ok" }),
+            obs({ principal: "a", tool: "t", service: "s", decision: "would-block", outcome: "ok" }),
+            obs({ principal: "a", tool: "t", service: "s", decision: "blocked", outcome: "error" }),
+        ]);
+        const e = g.edges.find((x) => x.from === "tool:t" && x.to === "backend:s");
+        assert.equal(e.allow, 1);
+        assert.equal(e.deviation, 1);
+        assert.equal(e.denied, 1);
+        const toolNode = g.nodes.find((n) => n.id === "tool:t");
+        assert.equal(toolNode.calls, 3);
+        assert.equal(toolNode.errors, 1);
+        assert.equal(toolNode.deviations, 2); // would-block + blocked
+    });
+    it("honours the sinceMs window filter", () => {
+        const old = obs({ ts: new Date(1_000_000_000_000).toISOString(), tool: "old" });
+        const fresh = obs({ ts: new Date(1_700_000_500_000).toISOString(), tool: "fresh" });
+        const g = buildFlowGraph([old, fresh], { sinceMs: 1_700_000_000_000 });
+        assert.equal(g.total, 1);
+        assert.ok(g.nodes.some((n) => n.id === "tool:fresh"));
+        assert.ok(!g.nodes.some((n) => n.id === "tool:old"));
+    });
+    it("empty input yields an empty graph", () => {
+        const g = buildFlowGraph([]);
+        assert.deepEqual(g.nodes, []);
+        assert.deepEqual(g.edges, []);
+        assert.equal(g.total, 0);
+    });
+});

package/dist/inspect/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./signature.js";
+export * from "./store.js";
+export * from "./mode.js";
+export * from "./graph.js";
+export * from "./recorder.js";
+export * from "./enforcer.js";
+export * from "./profile.js";
+export * from "./profile-store.js";