@thotischner/observability-mcp 1.4.1 → 1.5.1

package/dist/auth/credentials.js

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

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

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

package/dist/auth/credentials.test.js

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

package/dist/context.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Request-scoped context threaded from the transport boundary (HTTP `/mcp`,
+ * stdio, and the internal REST/dashboard call sites) into every tool handler.
+ *
+ * Today it carries only an anonymous principal and a correlation id — it is a
+ * deliberate pass-through that does not change behaviour. It is the single
+ * seam that later access-control / scoping / audit work attaches to, so those
+ * features become additive rather than a cross-cutting rewrite.
+ */
+export interface RequestContext {
+    /** Stable id for the calling principal. "anonymous" when no auth configured. */
+    principalId: string;
+    /** How the principal was authenticated. */
+    auth: "anonymous" | "apikey";
+    /**
+     * Coarse per-credential source allow-list (single-tenant primitive). When
+     * set, the principal may only target these source names. Rich role-based
+     * scoping (tools/services/lookback/read-only) is a separate concern.
+     */
+    allowedSources?: string[];
+    /** Correlates all tool calls within one transport request/session. */
+    correlationId: string;
+}
+/** Default all-access anonymous context — preserves current behaviour. */
+export declare function defaultContext(): RequestContext;
+/** Context for an authenticated API-key principal. */
+export declare function principalContext(principalId: string, allowedSources?: string[]): RequestContext;

package/dist/context.js

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

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import express from "express";
+import rateLimit from "express-rate-limit";
 import { randomUUID } from "node:crypto";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
@@ -7,6 +8,8 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { loadConfig, saveConfig, DEFAULT_HEALTH_THRESHOLDS, DEFAULT_SETTINGS } from "./config/loader.js";
 import { ConnectorRegistry, getSupportedTypes } from "./connectors/registry.js";
+import { defaultContext, principalContext } from "./context.js";
+import { loadCredentials, credentialsConfigured, extractToken, resolveToken, } from "./auth/credentials.js";
 import { getPluginLoader } from "./connectors/loader.js";
 import { resolveHubCatalogUrl, describeInstalled, mergeCatalog, fetchHubCatalog, } from "./connectors/hub.js";
 import { isValidConnectorName, installTarball } from "./connectors/install.js";
@@ -75,35 +78,18 @@ function validateSourceUrl(url) {
 // Hard cap for a downloaded/uploaded connector tarball (defence against
 // a hostile or accidental huge artifact OOM-ing the server).
 const MAX_CONNECTOR_TGZ_BYTES = 64 * 1024 * 1024;
-// Dependency-free fixed-window per-client rate limiter for the runtime
-// connector install/upload routes (expensive: fetch + extract + verify +
-// fs write + loader rescan). Bounds abuse even with ENABLE_UI_INSTALL on.
-const installRateState = new Map();
-function installRateLimit(req, res, next) {
-    const WINDOW_MS = 60_000;
-    const MAX = 5;
-    const now = Date.now();
-    if (installRateState.size > 5000) {
-        for (const [k, v] of installRateState)
-            if (v.resetAt < now)
-                installRateState.delete(k);
-    }
-    const key = req.ip || "unknown";
-    let s = installRateState.get(key);
-    if (!s || s.resetAt < now) {
-        s = { count: 0, resetAt: now + WINDOW_MS };
-        installRateState.set(key, s);
-    }
-    s.count++;
-    if (s.count > MAX) {
-        res.setHeader("Retry-After", String(Math.ceil((s.resetAt - now) / 1000)));
-        res.status(429).json({
-            error: "rate limit exceeded — too many connector install attempts, slow down",
-        });
-        return;
-    }
-    next();
-}
+// Per-client rate limiter for the expensive runtime routes (connector
+// install/upload: fetch + extract + verify + fs write + loader rescan;
+// add/test source: outbound backend connect). Uses express-rate-limit
+// so the control is explicit and well-tested. Bounds abuse even with
+// ENABLE_UI_INSTALL on.
+const installRateLimit = rateLimit({
+    windowMs: 60_000,
+    limit: 5,
+    standardHeaders: true,
+    legacyHeaders: false,
+    message: { error: "rate limit exceeded — too many attempts, slow down" },
+});
 async function main() {
     // Stdio transport mode (MCP catalogs / desktop clients / Glama's
     // mcp-proxy spawn a stdio MCP server and read JSON-RPC from stdout).
@@ -124,7 +110,7 @@ async function main() {
     // so we cannot share a single McpServer across HTTP sessions. Each new
     // session needs its own server. The factory captures the live registry
     // by reference so tool handlers always see the current configuration.
-    function createMcpServer() {
+    function createMcpServer(ctx) {
         const mcpServer = new McpServer({
             name: "observability-mcp",
             version: SERVER_VERSION,
@@ -135,7 +121,7 @@ async function main() {
             "When to use: call this first to learn which source names exist and are healthy before passing `source` to other tools, or to debug why a query returns no data.",
             "Behavior: read-only, no side effects. Returns one entry per source with its name, type, configured URL, signal types (metrics/logs), and a live up/down status. Never throws for an unreachable backend — the backend is reported as down instead.",
             "Related: use `list_services` to see what is monitored within these sources.",
-        ].join(" "), {}, async () => withToolMetrics("list_sources", () => listSourcesHandler(registry)));
+        ].join(" "), {}, async () => withToolMetrics("list_sources", () => listSourcesHandler(registry, ctx)));
         mcpServer.tool("list_services", [
             "Discover the service names that can be queried, aggregated across every connected backend.",
             "When to use: call this before `query_metrics`, `query_logs`, or `get_service_health` to obtain the exact, case-sensitive service name those tools require.",
@@ -146,7 +132,7 @@ async function main() {
                 .string()
                 .optional()
                 .describe("Optional case-insensitive substring to narrow the result to matching service names (e.g. 'payment'). Omit to list every discovered service."),
-        }, async (args) => withToolMetrics("list_services", () => listServicesHandler(registry, args)));
+        }, async (args) => withToolMetrics("list_services", () => listServicesHandler(registry, args, ctx)));
         const metricsList = getAvailableMetricNames(registry);
         const metricNames = registry.getBySignal("metrics").flatMap(c => c.getMetrics().map(m => m.name));
         const uniqueNames = [...new Set(metricNames)];
@@ -175,7 +161,7 @@ async function main() {
                 .string()
                 .optional()
                 .describe("Optional. Metric label to break the result down by, e.g. 'instance', 'pod', 'node'. When set, the response contains one series per distinct label value under `groups`. Default: a single aggregated series."),
-        }, async (args) => withToolMetrics("query_metrics", () => queryMetricsHandler(registry, args)));
+        }, async (args) => withToolMetrics("query_metrics", () => queryMetricsHandler(registry, args, ctx)));
         mcpServer.tool("query_logs", [
             "Fetch recent log entries for ONE service over a look-back window, with a pre-computed summary (error/warning counts and the most frequent error patterns).",
             "When to use: to inspect what a service actually logged, or to investigate an error spike surfaced by `detect_anomalies` / `get_service_health`. For numeric metrics use `query_metrics` instead.",
@@ -203,7 +189,7 @@ async function main() {
                 .positive()
                 .optional()
                 .describe("Optional. Maximum number of log entries to return (most recent first). Default: 100."),
-        }, async (args) => withToolMetrics("query_logs", () => queryLogsHandler(registry, args)));
+        }, async (args) => withToolMetrics("query_logs", () => queryLogsHandler(registry, args, ctx)));
         mcpServer.tool("get_service_health", [
             "Produce a single aggregated health verdict for ONE service by combining its metrics and logs.",
             "When to use: the fastest way to answer 'is this service healthy right now and why?'. Use `query_metrics`/`query_logs` to drill into the underlying numbers, or `detect_anomalies` to scan many services at once.",
@@ -213,7 +199,7 @@ async function main() {
             service: z
                 .string()
                 .describe("Required. Exact, case-sensitive service name exactly as returned by `list_services` (e.g. 'payment-service')."),
-        }, async (args) => withToolMetrics("get_service_health", () => getServiceHealthHandler(registry, args)));
+        }, async (args) => withToolMetrics("get_service_health", () => getServiceHealthHandler(registry, args, ctx)));
         mcpServer.tool("detect_anomalies", [
             "Scan one or all monitored services for abnormal behavior and return the findings ranked by severity.",
             "When to use: the entry point for 'is anything wrong anywhere?' triage. Once a service is flagged, follow up with `get_service_health` for the verdict or `query_metrics`/`query_logs` for the raw evidence.",
@@ -232,7 +218,7 @@ async function main() {
                 .enum(["low", "medium", "high"])
                 .optional()
                 .describe("Optional. Detection threshold: 'low' flags only strong deviations (>3σ), 'medium' is balanced (>2σ), 'high' is most sensitive and noisier (>1.5σ). Default: 'medium'."),
-        }, async (args) => withToolMetrics("detect_anomalies", () => detectAnomaliesHandler(registry, args)));
+        }, async (args) => withToolMetrics("detect_anomalies", () => detectAnomaliesHandler(registry, args, ctx)));
         return mcpServer;
     }
     // --- HTTP server ---
@@ -485,7 +471,7 @@ async function main() {
         }
     });
     // Add a new source
-    app.post("/api/sources", async (req, res) => {
+    app.post("/api/sources", installRateLimit, async (req, res) => {
         const { name, type, url, enabled, auth, tls } = req.body;
         if (!name || !type || !url) {
             res.status(400).json({ error: "name, type, and url are required" });
@@ -548,7 +534,7 @@ async function main() {
         res.json({ ok: true });
     });
     // Test a source connection (without saving)
-    app.post("/api/sources/test", async (req, res) => {
+    app.post("/api/sources/test", installRateLimit, async (req, res) => {
         const { name, type, url, enabled, auth, tls } = req.body;
         if (!type || !url) {
             res.status(400).json({ error: "type and url are required" });
@@ -594,7 +580,7 @@ async function main() {
     // List discovered services
     app.get("/api/services", async (_req, res) => {
         try {
-            const result = await listServicesHandler(registry, {});
+            const result = await listServicesHandler(registry, {}, defaultContext());
             res.json(parseToolResult(result));
         }
         catch {
@@ -604,7 +590,7 @@ async function main() {
     // Health endpoint for UI dashboard
     app.get("/api/health/:service", async (req, res) => {
         try {
-            const result = await getServiceHealthHandler(registry, { service: req.params.service });
+            const result = await getServiceHealthHandler(registry, { service: req.params.service }, defaultContext());
             res.json(parseToolResult(result));
         }
         catch {
@@ -614,13 +600,13 @@ async function main() {
     // Health for all services
     app.get("/api/health", async (_req, res) => {
         try {
-            const servicesResult = await listServicesHandler(registry, {});
+            const servicesResult = await listServicesHandler(registry, {}, defaultContext());
             const parsed = parseToolResult(servicesResult);
             const services = parsed?.services || [];
             const health = {};
             for (const svc of services) {
                 try {
-                    const result = await getServiceHealthHandler(registry, { service: svc.name });
+                    const result = await getServiceHealthHandler(registry, { service: svc.name }, defaultContext());
                     health[svc.name] = parseToolResult(result);
                 }
                 catch {
@@ -703,7 +689,7 @@ async function main() {
     });
     // Stdio transport: one server over stdin/stdout, no HTTP listener.
     if (STDIO) {
-        const server = createMcpServer();
+        const server = createMcpServer(defaultContext());
         await server.connect(new StdioServerTransport());
         console.error(`observability-mcp running on stdio transport · connectors: ${registry
             .getAll()
@@ -727,7 +713,26 @@ async function main() {
         }
         mcpActiveSessions.set(transports.size);
     }, 5 * 60 * 1000);
+    // Single-tenant auth gate. No credentials configured → anonymous (current
+    // behaviour, fully backward compatible). Configured → require a valid
+    // Bearer/X-API-Key on every /mcp request; resolve the principal + its
+    // coarse source allow-list into the RequestContext.
+    function gateCtx(req, res) {
+        if (!credentialsConfigured())
+            return defaultContext();
+        const cred = resolveToken(extractToken(req.headers), loadCredentials());
+        if (!cred) {
+            res
+                .status(401)
+                .json({ error: "unauthorized: valid Bearer token or X-API-Key required" });
+            return null;
+        }
+        return principalContext(cred.name, cred.allowedSources);
+    }
     app.post("/mcp", async (req, res) => {
+        const ctx = gateCtx(req, res);
+        if (!ctx)
+            return;
         const sessionId = req.headers["mcp-session-id"];
         let transport;
         if (sessionId && transports.has(sessionId)) {
@@ -747,7 +752,7 @@ async function main() {
                 }
                 mcpActiveSessions.set(transports.size);
             };
-            const sessionMcpServer = createMcpServer();
+            const sessionMcpServer = createMcpServer(ctx);
             await sessionMcpServer.connect(transport);
         }
         await transport.handleRequest(req, res, req.body);
@@ -761,6 +766,8 @@ async function main() {
         mcpActiveSessions.set(transports.size);
     });
     app.get("/mcp", async (req, res) => {
+        if (!gateCtx(req, res))
+            return;
         const sessionId = req.headers["mcp-session-id"];
         const transport = transports.get(sessionId);
         if (!transport) {
@@ -770,6 +777,8 @@ async function main() {
         await transport.handleRequest(req, res);
     });
     app.delete("/mcp", async (req, res) => {
+        if (!gateCtx(req, res))
+            return;
         const sessionId = req.headers["mcp-session-id"];
         const transport = transports.get(sessionId);
         if (transport) {

package/dist/net/egress-policy.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Verifiable offline mode — egress policy.
+ *
+ * The server performs **no telemetry, analytics, phone-home, or update
+ * checks**. The only outbound network calls it ever makes are to backends
+ * the operator explicitly configures (Prometheus/Loki/... source URLs) or to
+ * an artifact URL the operator/registry explicitly asks it to install.
+ *
+ * This module is the machine-checkable statement of that guarantee:
+ * `egress-policy.test.ts` fails CI if any source file outside the allowlist
+ * introduces an outbound call — so the "no data egress" property cannot
+ * silently regress.
+ */
+export declare const OFFLINE_STATEMENT: string;
+/** Regex of outbound-call shapes the guard scans for. */
+export declare const OUTBOUND_PATTERN: RegExp;
+/**
+ * Files/prefixes permitted to make outbound calls, each with the reason.
+ * Anything matching OUTBOUND_PATTERN outside these paths is a policy breach
+ * (e.g. a newly added analytics/telemetry module).
+ */
+export declare const EGRESS_ALLOWLIST: ReadonlyArray<{
+    prefix: string;
+    reason: string;
+}>;
+/**
+ * Hard-blocked analytics/telemetry SDKs — matches an *import/require of the
+ * package*, not the word in prose, so comments/policy text don't false-positive.
+ */
+export declare const FORBIDDEN_TELEMETRY: RegExp;
+export declare function isEgressAllowed(relPath: string): boolean;

package/dist/net/egress-policy.js

@@ -0,0 +1,37 @@
+/**
+ * Verifiable offline mode — egress policy.
+ *
+ * The server performs **no telemetry, analytics, phone-home, or update
+ * checks**. The only outbound network calls it ever makes are to backends
+ * the operator explicitly configures (Prometheus/Loki/... source URLs) or to
+ * an artifact URL the operator/registry explicitly asks it to install.
+ *
+ * This module is the machine-checkable statement of that guarantee:
+ * `egress-policy.test.ts` fails CI if any source file outside the allowlist
+ * introduces an outbound call — so the "no data egress" property cannot
+ * silently regress.
+ */
+export const OFFLINE_STATEMENT = "observability-mcp makes no telemetry/analytics/phone-home/update calls. " +
+    "Outbound traffic goes only to operator-configured source backends and " +
+    "operator/registry-requested plugin artifacts. It runs fully air-gapped.";
+/** Regex of outbound-call shapes the guard scans for. */
+export const OUTBOUND_PATTERN = /\b(fetch\s*\(|https?\.request\s*\(|new\s+WebSocket\s*\(|import\s*\(\s*['"]https?:)/;
+/**
+ * Files/prefixes permitted to make outbound calls, each with the reason.
+ * Anything matching OUTBOUND_PATTERN outside these paths is a policy breach
+ * (e.g. a newly added analytics/telemetry module).
+ */
+export const EGRESS_ALLOWLIST = [
+    { prefix: "connectors/", reason: "connectors query operator-configured source backends" },
+    { prefix: "cli/index.ts", reason: "CLI fetches a source location the operator passed explicitly" },
+    { prefix: "index.ts", reason: "connector-hub plugin install of an operator/registry-requested tarball URL" },
+];
+/**
+ * Hard-blocked analytics/telemetry SDKs — matches an *import/require of the
+ * package*, not the word in prose, so comments/policy text don't false-positive.
+ */
+export const FORBIDDEN_TELEMETRY = /(?:from\s*['"]|require\(\s*['"])[^'"]*(sentry|posthog|mixpanel|amplitude|@segment|datadog-rum|analytics-node|google-analytics)/i;
+export function isEgressAllowed(relPath) {
+    const p = relPath.replace(/\\/g, "/");
+    return EGRESS_ALLOWLIST.some((a) => p === a.prefix || p.startsWith(a.prefix));
+}

package/dist/net/egress-policy.test.d.ts

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

package/dist/net/egress-policy.test.js

@@ -0,0 +1,52 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join, relative } from "node:path";
+import { OUTBOUND_PATTERN, FORBIDDEN_TELEMETRY, isEgressAllowed, EGRESS_ALLOWLIST, } from "./egress-policy.js";
+// Verifiable offline mode: static guard so the "no data egress" guarantee
+// cannot silently regress. Any new outbound call outside the documented
+// allowlist, or any analytics/telemetry SDK anywhere, fails CI here.
+const srcRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+function walk(dir) {
+    const out = [];
+    for (const e of readdirSync(dir)) {
+        const p = join(dir, e);
+        if (statSync(p).isDirectory())
+            out.push(...walk(p));
+        else if (e.endsWith(".ts") && !e.endsWith(".test.ts"))
+            out.push(p);
+    }
+    return out;
+}
+describe("verifiable offline mode — egress policy", () => {
+    const files = walk(srcRoot)
+        .map((f) => ({
+        rel: relative(srcRoot, f).replace(/\\/g, "/"),
+        src: readFileSync(f, "utf8"),
+    }))
+        // The policy module itself names these tokens by design.
+        .filter((f) => f.rel !== "net/egress-policy.ts");
+    it("scans a non-trivial number of source files", () => {
+        assert.ok(files.length > 20, `only scanned ${files.length} files`);
+    });
+    it("no outbound call outside the egress allowlist", () => {
+        const breaches = files
+            .filter((f) => OUTBOUND_PATTERN.test(f.src) && !isEgressAllowed(f.rel))
+            .map((f) => f.rel);
+        assert.deepEqual(breaches, [], `outbound calls found outside allowlist (${EGRESS_ALLOWLIST.map((a) => a.prefix).join(", ")}): ` +
+            `${breaches.join(", ")} — telemetry/phone-home is forbidden; if legitimate, extend EGRESS_ALLOWLIST with a reason`);
+    });
+    it("no analytics/telemetry SDK anywhere in source", () => {
+        const hits = files
+            .filter((f) => FORBIDDEN_TELEMETRY.test(f.src))
+            .map((f) => f.rel);
+        assert.deepEqual(hits, [], `forbidden telemetry/analytics identifiers in: ${hits.join(", ")}`);
+    });
+    it("allowlisted files are still present (allowlist not stale)", () => {
+        for (const { prefix } of EGRESS_ALLOWLIST) {
+            const covered = files.some((f) => f.rel === prefix || f.rel.startsWith(prefix));
+            assert.ok(covered, `allowlist entry "${prefix}" matches no source file — prune it`);
+        }
+    });
+});

package/dist/tools/context-seam.test.d.ts

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

package/dist/tools/context-seam.test.js

@@ -0,0 +1,23 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync, readdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+// Keystone guard: every tool handler must accept the RequestContext seam.
+// This prevents a new handler (or a refactor) from silently bypassing the
+// request-scoped context that access-control / scoping / audit attach to.
+const here = dirname(fileURLToPath(import.meta.url));
+describe("RequestContext seam", () => {
+    const handlerFiles = readdirSync(here).filter((f) => f.endsWith(".ts") && !f.endsWith(".test.ts"));
+    for (const file of handlerFiles) {
+        const src = readFileSync(join(here, file), "utf8");
+        const hasHandler = /export\s+(async\s+)?function\s+\w*Handler\s*\(/.test(src);
+        if (!hasHandler)
+            continue;
+        it(`${file}: handler accepts a RequestContext`, () => {
+            assert.match(src, /_ctx:\s*RequestContext/, `${file} exports a *Handler but does not thread RequestContext — ` +
+                `add the ctx seam (see context.ts)`);
+            assert.match(src, /from "\.\.\/context\.js"/, `${file} must import from ../context.js`);
+        });
+    }
+});

package/dist/tools/detect-anomalies.d.ts

@@ -1,4 +1,5 @@
 import type { ConnectorRegistry } from "../connectors/registry.js";
+import { type RequestContext } from "../context.js";
 export declare const detectAnomaliesDefinition: {
     name: "detect_anomalies";
     description: string;
@@ -25,7 +26,7 @@ export declare function detectAnomaliesHandler(registry: ConnectorRegistry, args
     service?: string;
     duration?: string;
     sensitivity?: string;
-}): Promise<{
+}, _ctx?: RequestContext): Promise<{
     content: {
         type: "text";
         text: string;