@frihet/mcp-server 1.16.6 → 1.17.0

package/dist/observability.js

@@ -6,8 +6,9 @@
  *
  * Design:
  *   - Fail-open: any Langfuse error logs a warning and lets the tool proceed.
- *   - PII: tool input content is passed as-is (business data is fine to trace).
- *     userId / apiKey metadata are hashed with a simple SHA-256 fingerprint.
+ *   - Data minimization: only bounded operational facts cross the telemetry
+ *     boundary. Tool input/output, arbitrary error text, and user/workspace
+ *     identity are never serialized.
  *   - Fire-and-forget: traces are sent via waitUntil (Workers) or unref'd promise
  *     (Node.js) so they never block tool responses.
  *
@@ -18,7 +19,53 @@
  *
  * Docs: https://langfuse.com/docs/api/reference/overview
  */
-import { redactClone, redactText } from "./redaction.js";
+import { log } from "./logger.js";
+const CANONICAL_LANGFUSE_ORIGIN = "https://langfuse.frihet.io";
+/**
+ * Langfuse receives a Basic Authorization header, so its authority is exact.
+ * The current product contract documents one hosted origin; arbitrary Frihet
+ * subdomains and self-hosted overrides are intentionally not trusted here.
+ */
+export function normalizeLangfuseBaseUrl(value) {
+    if (value !== value.trim()) {
+        throw new Error("LANGFUSE_BASE_URL must not contain surrounding whitespace");
+    }
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new Error("LANGFUSE_BASE_URL must be a valid URL");
+    }
+    if (parsed.protocol !== "https:")
+        throw new Error("LANGFUSE_BASE_URL must use HTTPS");
+    if (parsed.username || parsed.password) {
+        throw new Error("LANGFUSE_BASE_URL must not contain URL credentials");
+    }
+    if (parsed.port)
+        throw new Error("LANGFUSE_BASE_URL must use the default HTTPS port");
+    if (parsed.search || parsed.hash) {
+        throw new Error("LANGFUSE_BASE_URL must not contain a query or fragment");
+    }
+    if (parsed.pathname !== "/")
+        throw new Error("LANGFUSE_BASE_URL must use the origin root");
+    if (parsed.hostname.toLowerCase() !== "langfuse.frihet.io") {
+        throw new Error("LANGFUSE_BASE_URL hostname is not trusted");
+    }
+    return CANONICAL_LANGFUSE_ORIGIN;
+}
+function buildConfig(publicKey, secretKey, baseUrl) {
+    if (!publicKey || !secretKey || !baseUrl)
+        return null;
+    try {
+        return { publicKey, secretKey, baseUrl: normalizeLangfuseBaseUrl(baseUrl) };
+    }
+    catch {
+        // Telemetry is optional and fail-open for tools. An invalid authority
+        // disables telemetry rather than risking credentials or blocking MCP calls.
+        return null;
+    }
+}
 function getConfig() {
     let publicKey;
     let secretKey;
@@ -29,44 +76,22 @@ function getConfig() {
         secretKey = process.env.LANGFUSE_SECRET_KEY;
         baseUrl = process.env.LANGFUSE_BASE_URL;
     }
-    if (!publicKey || !secretKey || !baseUrl)
-        return null;
-    return { publicKey, secretKey, baseUrl: baseUrl.replace(/\/$/, "") };
+    return buildConfig(publicKey, secretKey, baseUrl);
 }
 // ── Worker env injection (for Cloudflare Workers) ───────────────────────────
-let workerEnv = null;
+// `undefined` means no Worker-specific decision was made, so Node.js may read
+// process.env. `null` is an explicit Worker-side opt-out and must never fall
+// back to process.env (Workers using nodejs_compat expose that global too).
+let workerEnv;
 /**
  * Called once from FrihetMCP.init() in the Worker to inject env vars.
  * Not needed in Node.js stdio mode (reads from process.env directly).
  */
 export function initLangfuse(config) {
-    if (config.publicKey && config.secretKey && config.baseUrl) {
-        workerEnv = {
-            publicKey: config.publicKey,
-            secretKey: config.secretKey,
-            baseUrl: config.baseUrl.replace(/\/$/, ""),
-        };
-    }
+    workerEnv = buildConfig(config.publicKey, config.secretKey, config.baseUrl);
 }
 function resolveConfig() {
-    return workerEnv ?? getConfig();
-}
-// ── PII helpers ──────────────────────────────────────────────────────────────
-/**
- * One-way fingerprint for PII values (apiKey, userId, email).
- * Uses Web Crypto API (available in both Node.js ≥18 and Workers).
- */
-async function hashPii(value) {
-    try {
-        const encoder = new TextEncoder();
-        const data = encoder.encode(value);
-        const hashBuffer = await crypto.subtle.digest("SHA-256", data);
-        const hashArray = Array.from(new Uint8Array(hashBuffer));
-        return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("").slice(0, 16);
-    }
-    catch {
-        return "[hash-error]";
-    }
+    return workerEnv === undefined ? getConfig() : workerEnv;
 }
 // ── ID generation ────────────────────────────────────────────────────────────
 function newId() {
@@ -100,17 +125,11 @@ export function inspectStubMarker(output) {
         candidates.push(sc);
     for (const obj of candidates) {
         if (obj["_stub"] === true || obj["_notImplemented"] === true || obj["_unavailable"] === true) {
-            return {
-                plannedEndpoint: typeof obj["_plannedEndpoint"] === "string" ? obj["_plannedEndpoint"] : undefined,
-                note: typeof obj["_note"] === "string" ? obj["_note"] : undefined,
-            };
+            return { stub: true };
         }
         // A bare _plannedEndpoint (without an explicit flag) is also a stub signal.
         if (typeof obj["_plannedEndpoint"] === "string") {
-            return {
-                plannedEndpoint: obj["_plannedEndpoint"],
-                note: typeof obj["_note"] === "string" ? obj["_note"] : undefined,
-            };
+            return { stub: true };
         }
     }
     return null;
@@ -120,6 +139,7 @@ async function sendBatch(config, batch) {
     const credentials = btoa(`${config.publicKey}:${config.secretKey}`);
     const resp = await fetch(`${config.baseUrl}/api/public/ingestion`, {
         method: "POST",
+        redirect: "error",
         headers: {
             "Content-Type": "application/json",
             "Authorization": `Basic ${credentials}`,
@@ -128,21 +148,25 @@ async function sendBatch(config, batch) {
         signal: AbortSignal.timeout(5000),
     });
     if (!resp.ok) {
-        // Log but don't throw — fail-open
-        const body = await resp.text().catch(() => "");
-        console.error(JSON.stringify({
-            service: "frihet-mcp",
+        // Never read/log the provider response body. Status is sufficient to
+        // correlate an operational delivery failure without importing arbitrary
+        // third-party text into telemetry.
+        log({
             level: "warn",
-            message: `Langfuse ingestion failed: ${resp.status} ${body.slice(0, 200)}`,
+            message: "Langfuse ingestion request failed",
             operation: "langfuse_send",
-            timestamp: new Date().toISOString(),
-        }));
+            error: {
+                message: "MCP operation failed",
+                code: "telemetry_http_error",
+                statusCode: resp.status,
+            },
+        });
     }
 }
 // Module-level context set once per session (Workers: per DO init, Node.js: startup)
 let _sessionContext = {};
 /**
- * Set session-level context (client identity, MCP version).
+ * Set session-level protocol context. Client identity is intentionally absent.
  * Call once from server init; applies to all subsequent traces.
  */
 export function setTraceContext(ctx) {
@@ -151,71 +175,69 @@ export function setTraceContext(ctx) {
 /**
  * Builds the Langfuse trace+span ingestion batch for a single tool call.
  *
- * CRITICAL (Trust): `input` and `output` are passed through {@link redactClone}
- * before they enter the payload, so government IDs (taxId/NIF/CIF), banking
- * identifiers (IBAN), webhook signing secrets, and auth tokens NEVER reach the
- * external Langfuse service — in ANY profile mode. The tool-call output handed
- * to the user is redacted later (OpenAI mode only); this redacts the trace copy
- * unconditionally. Exported so a test can assert no sensitive value survives.
+ * CRITICAL (Trust): this builder is an allowlist. It has no input/output or
+ * identity fields and ignores any extra runtime properties a caller supplies.
+ * Exported so tests can assert the exact operational shape.
  */
 export function buildTracePayload(p) {
-    const { toolName, input, output, isError, errorMessage, startTime, endTime, traceId, spanId, userIdHashed, clientName, mcpVersion, stub, } = p;
+    const { toolName, isError, errorClass, errorCode, statusCode, startTime, endTime, traceId, spanId, mcpVersion, stub, } = p;
     const stubbed = stub !== null;
     // success: false whenever the call threw OR returned a fabricated stub body.
     const success = !isError && !stubbed;
-    const stubNote = stub?.note ??
-        (stub?.plannedEndpoint
-            ? `Backend endpoint not yet available: ${stub.plannedEndpoint}`
-            : undefined);
-    // ── Redact BEFORE the payload is built (never mutates the live response) ──
-    const safeArgs = redactClone(input);
-    const safeError = errorMessage ? redactText(errorMessage) : errorMessage;
-    const safeOutput = isError ? { error: safeError } : redactClone(output);
+    const safeToolName = toolNameToken(toolName) ?? "unknown_tool";
+    const safeMcpVersion = mcpVersion === "mcp/1.0" ? mcpVersion : undefined;
+    const safeErrorClass = TELEMETRY_ERROR_CLASSES.has(errorClass ?? "")
+        ? errorClass
+        : undefined;
+    const safeErrorCode = TELEMETRY_ERROR_CODES.has(errorCode ?? "")
+        ? errorCode
+        : undefined;
+    const safeStatusCode = typeof statusCode === "number"
+        && Number.isInteger(statusCode)
+        && statusCode >= 0
+        && statusCode <= 599
+        ? statusCode
+        : undefined;
+    const errorFacts = {
+        ...(safeErrorClass ? { errorClass: safeErrorClass } : {}),
+        ...(safeErrorCode ? { errorCode: safeErrorCode } : {}),
+        ...(safeStatusCode !== undefined ? { statusCode: safeStatusCode } : {}),
+    };
     const traceBody = {
         id: traceId,
         name: "mcp_request",
         timestamp: startTime.toISOString(),
-        input: { tool: toolName, args: safeArgs },
-        output: safeOutput,
         metadata: {
-            tool: toolName,
-            clientName,
-            mcpVersion,
+            tool: safeToolName,
+            ...(safeMcpVersion ? { mcpVersion: safeMcpVersion } : {}),
             // FALSE on a thrown error AND on a fabricated-stub fallback.
             success,
-            ...(stubbed
-                ? {
-                    stub: true,
-                    ...(stub?.plannedEndpoint ? { plannedEndpoint: stub.plannedEndpoint } : {}),
-                    ...(stubNote ? { note: stubNote } : {}),
-                }
-                : {}),
+            ...(stubbed ? { stub: true } : {}),
+            ...errorFacts,
         },
-        tags: [`mcp.tool.${toolName}`, ...(stubbed ? ["mcp.stub"] : [])],
-        ...(userIdHashed ? { userId: userIdHashed } : {}),
+        tags: [`mcp.tool.${safeToolName}`, ...(stubbed ? ["mcp.stub"] : [])],
     };
     const spanBody = {
         id: spanId,
         traceId,
-        name: `tool.${toolName}`,
+        name: `tool.${safeToolName}`,
         startTime: startTime.toISOString(),
         endTime: endTime.toISOString(),
-        input: safeArgs,
-        output: safeOutput,
         metadata: {
             durationMs: endTime.getTime() - startTime.getTime(),
-            clientName,
-            mcpVersion,
+            ...(safeMcpVersion ? { mcpVersion: safeMcpVersion } : {}),
+            success,
             ...(stubbed ? { stub: true } : {}),
+            ...errorFacts,
         },
         // ERROR on a thrown error; WARNING on a fabricated-stub fallback (the call
         // "succeeded" mechanically but returned no real backend data); DEFAULT only
         // on a genuine success.
         level: isError ? "ERROR" : stubbed ? "WARNING" : "DEFAULT",
-        ...(isError && safeError
-            ? { statusMessage: safeError }
-            : stubbed && stubNote
-                ? { statusMessage: stubNote }
+        ...(isError
+            ? { statusMessage: safeErrorCode ?? safeErrorClass ?? "operation_failed" }
+            : stubbed
+                ? { statusMessage: "stub_response" }
                 : {}),
     };
     return {
@@ -225,6 +247,72 @@ export function buildTracePayload(p) {
         ],
     };
 }
+const TOOL_NAME = /^[a-z][a-z0-9_]{0,63}$/u;
+const TELEMETRY_ERROR_CLASSES = new Set([
+    "handled_mcp_error",
+    "request_timeout",
+    "abort_error",
+    "api_error",
+    "telemetry_error",
+    "unknown_error",
+]);
+const TELEMETRY_ERROR_CODES = new Set([
+    "tool_error",
+    "request_timeout",
+    "unauthorized",
+    "forbidden",
+    "not_found",
+    "rate_limited",
+    "client_error",
+    "backend_error",
+    "telemetry_http_error",
+    "telemetry_error",
+    "unknown_error",
+]);
+function toolNameToken(value) {
+    return typeof value === "string" && TOOL_NAME.test(value) ? value : undefined;
+}
+function statusErrorCode(statusCode) {
+    if (typeof statusCode !== "number" || !Number.isInteger(statusCode))
+        return undefined;
+    if (statusCode === 401)
+        return "unauthorized";
+    if (statusCode === 403)
+        return "forbidden";
+    if (statusCode === 404)
+        return "not_found";
+    if (statusCode === 408)
+        return "request_timeout";
+    if (statusCode === 429)
+        return "rate_limited";
+    if (statusCode >= 400 && statusCode < 500)
+        return "client_error";
+    if (statusCode >= 500 && statusCode <= 599)
+        return "backend_error";
+    return undefined;
+}
+function operationalErrorFacts(error) {
+    if (!error || typeof error !== "object")
+        return { errorClass: "unknown_error" };
+    const record = error;
+    const statusCode = typeof record.statusCode === "number" ? record.statusCode : undefined;
+    const name = record.name;
+    const errorClass = name === "TimeoutError"
+        ? "request_timeout"
+        : name === "AbortError"
+            ? "abort_error"
+            : statusErrorCode(statusCode)
+                ? "api_error"
+                : "unknown_error";
+    return {
+        errorClass,
+        errorCode: statusErrorCode(statusCode) ?? (errorClass === "request_timeout" ? "request_timeout" : "unknown_error"),
+        statusCode,
+    };
+}
+function isHandledMcpError(output) {
+    return !!output && typeof output === "object" && output.isError === true;
+}
 /**
  * Wraps a tool handler fn and sends a Langfuse trace+span for the call.
  *
@@ -236,7 +324,7 @@ export function buildTracePayload(p) {
  * @param fn        Async tool handler to wrap
  * @returns         Result of fn
  */
-export async function traceMCPTool(toolName, input, fn) {
+export async function traceMCPTool(toolName, _input, fn) {
     const config = resolveConfig();
     // No config — pass through silently
     if (!config) {
@@ -247,16 +335,20 @@ export async function traceMCPTool(toolName, input, fn) {
     const startTime = new Date();
     let result;
     let isError = false;
-    let errorMessage;
+    let errorFacts = {};
     let output;
     try {
         result = await fn();
         output = result;
+        if (isHandledMcpError(result)) {
+            isError = true;
+            errorFacts = { errorClass: "handled_mcp_error", errorCode: "tool_error" };
+        }
         return result;
     }
     catch (err) {
         isError = true;
-        errorMessage = err instanceof Error ? err.message : String(err);
+        errorFacts = operationalErrorFacts(err);
         throw err;
     }
     finally {
@@ -274,37 +366,32 @@ export async function traceMCPTool(toolName, input, fn) {
         // Fire-and-forget — build and send async, never awaited
         void (async () => {
             try {
-                // Hash PII fields
-                const userIdRaw = _sessionContext.userId;
-                const userIdHashed = userIdRaw ? await hashPii(userIdRaw) : undefined;
-                // buildTracePayload redacts input/output (taxId/secret/IBAN/tokens) so
-                // the external Langfuse service never stores cleartext PII or credentials.
                 const batch = buildTracePayload({
                     toolName,
-                    input,
-                    output,
                     isError,
-                    errorMessage,
+                    ...errorFacts,
                     startTime,
                     endTime,
                     traceId,
                     spanId,
-                    userIdHashed,
-                    clientName: _sessionContext.clientName,
                     mcpVersion: _sessionContext.mcpVersion,
                     stub,
                 });
                 await sendBatch(config, batch);
             }
             catch (langfuseErr) {
-                // Fail-open: log warn only
-                console.error(JSON.stringify({
-                    service: "frihet-mcp",
+                // Fail-open, but never serialize the provider/runtime exception text.
+                const facts = operationalErrorFacts(langfuseErr);
+                log({
                     level: "warn",
-                    message: `Langfuse trace failed (non-blocking): ${langfuseErr instanceof Error ? langfuseErr.message : String(langfuseErr)}`,
+                    message: "Langfuse trace failed (non-blocking)",
                     operation: "langfuse_trace",
-                    timestamp: new Date().toISOString(),
-                }));
+                    error: {
+                        message: "MCP operation failed",
+                        code: "telemetry_error",
+                        statusCode: facts.statusCode,
+                    },
+                });
             }
         })();
     }

package/dist/openai-profile.d.ts

@@ -15,11 +15,31 @@
  * The full MCP server (157 business tools + MCP extras) remains available for Claude, Cursor,
  * Windsurf, Cline, Codex, and all other MCP clients.
  *
- * OpenAI-safe mode: 53 reviewed business tools, 0 prompts, 0 resources, 0 government IDs in I/O.
+ * OpenAI-safe mode: 33 reviewed business tools, 0 prompts, 0 resources, and no
+ * dedicated government-ID fields in I/O.
  * The full MCP surface remains available outside FRIHET_OPENAI_MODE.
  *
  * @see https://developers.openai.com/apps-sdk/app-submission-guidelines
  */
+/** OAuth requirement advertised on every reviewed business tool. */
+export declare const OPENAI_OAUTH_SECURITY_SCHEMES: readonly [{
+    readonly type: "oauth2";
+    readonly scopes: readonly ["frihet:workspace.manage"];
+}];
+export declare const OPENAI_WORKSPACE_WEBHOOK_EVENT_TOOLS: ReadonlySet<string>;
+export declare const OPENAI_REVIEW_CONFIRM_REQUIRED_TOOLS: ReadonlySet<string>;
+/** Strictly necessary row fields for reviewed collection/search responses. */
+export declare const OPENAI_REVIEW_LIST_OUTPUT_FIELDS: Readonly<Record<string, readonly string[]>>;
+export declare const OPENAI_REVIEW_LIST_LIMIT_MAX = 50;
+export declare const OPENAI_REVIEW_OFFSET_MAX = 10000;
+export declare const OPENAI_REVIEW_PAGINATION_DEFAULT = 20;
+export declare const OPENAI_REVIEW_DOCUMENT_LINE_ITEM_MAX = 100;
+export declare const OPENAI_REVIEW_BUSINESS_CONTEXT_TOP_CLIENTS_MAX = 5;
+export declare const OPENAI_REVIEW_FREE_TEXT_WARNING = "Do not include passwords, credentials, payment-card data, health data, or official/government identifiers in this free-text field / No incluyas contrasenas, credenciales, datos de tarjetas, datos de salud ni identificadores oficiales en este campo de texto libre";
+/** Dot paths whose persisted or query text needs an explicit model-facing warning. */
+export declare const OPENAI_REVIEW_FREE_TEXT_WARNING_PATHS: Readonly<Record<string, readonly string[]>>;
+export declare const OPENAI_REVIEW_PAGINATION_LIMITS: Readonly<Record<string, number>>;
+export declare const OPENAI_REVIEW_TEXT_INPUT_LIMITS: Readonly<Record<string, Readonly<Record<string, number>>>>;
 /**
  * Content-Security-Policy for the OpenAI-safe MCP endpoint.
  * OpenAI requires CSP specifying the exact domains the app fetches from.
@@ -47,28 +67,12 @@ export declare function applyOpenAIProfile(server: any): void;
 export declare const OPENAI_EXCLUDED_COUNT: number;
 /** Number of tools explicitly allowed in OpenAI mode. */
 export declare const OPENAI_ALLOWED_TOOL_COUNT: number;
-/**
- * The reviewed OpenAI tool allow-list (the 53 business tools), exposed read-only
- * so the grouped tool-exposure profile can pin its catalog to EXACTLY this set
- * when the two profiles are composed on openai-mcp.frihet.io. The progressive-
- * disclosure meta-tools (search_tools / describe_tool / list_tool_groups) must
- * never surface a tool outside this allow-list; passing it as the grouped
- * `allowlist` enforces that statically. This is the SAME object used to gate
- * registerTool, so the two can never drift apart.
- *
- * NOTE: this is the 53 BUSINESS tools only. It deliberately does NOT contain the
- * 3 grouped meta-tools — those are registered directly on the real server
- * (bypassing the OpenAI gate) by applyToolExposureProfile when it runs first, so
- * OPENAI_ALLOWED_TOOL_COUNT (and every advertised "53 reviewed tools" doc) stays
- * correct while the live tools/list still materialises 53 + 3 = 56 tools.
- */
+/** The exact 33-tool allow-list reviewed for the OpenAI connector. */
 export declare const OPENAI_REVIEWED_TOOL_ALLOWLIST: ReadonlySet<string>;
 /**
- * Apply the exact profile composition used by the ChatGPT review Worker.
- *
- * Keep this helper as the single source for the security-sensitive ordering:
- * grouped exposure first (with the frozen allow-list), OpenAI profile second.
- * Tool registration happens afterwards through registerAllTools().
+ * Backwards-compatible helper for tests and gates that capture the exact
+ * ChatGPT review profile. The reviewed host deliberately uses full tool
+ * descriptions and exposes no grouped discovery meta-tools.
  */
 export declare function applyOpenAIReviewProfiles(server: any): void;
 /** Number of resources excluded in OpenAI mode (for logging). */