@frihet/mcp-server 1.16.6 → 1.17.0

package/dist/logger.d.ts

@@ -37,10 +37,10 @@ export declare function logToolCall(tool: string, startTime: number, success: bo
 /**
  * Log an outbound API call with timing.
  */
-export declare function logApiCall(method: string, path: string, statusCode: number, durationMs: number): void;
+export declare function logApiCall(method: string, _path: string, statusCode: number, durationMs: number): void;
 /**
  * Log a rate-limit retry.
  */
-export declare function logRetry(method: string, path: string, retryCount: number, delayMs: number): void;
+export declare function logRetry(method: string, _path: string, retryCount: number, delayMs: number): void;
 export {};
 //# sourceMappingURL=logger.d.ts.map

package/dist/logger.js

@@ -6,6 +6,107 @@
  *
  * Set FRIHET_MCP_DEBUG=1 to enable debug-level logs.
  */
+const OPERATION_MESSAGES = {
+    startup: "MCP startup event",
+    session_init: "MCP session event",
+    tool_call: "MCP tool call completed",
+    tool_error: "MCP tool error",
+    api_call: "MCP API call completed",
+    api_retry: "MCP API retry scheduled",
+    http_request: "MCP HTTP request completed",
+    oauth_authorize: "MCP OAuth authorization event",
+    oauth_callback: "MCP OAuth callback event",
+    shutdown_metrics: "MCP shutdown event",
+    langfuse_send: "MCP telemetry delivery event",
+    langfuse_trace: "MCP telemetry trace event",
+};
+const TOOL_NAME = /^[a-z][a-z0-9_]{0,63}$/u;
+const PACKAGE_VERSION = /^\d{1,3}\.\d{1,3}\.\d{1,3}$/u;
+const SAFE_METHODS = new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]);
+const SAFE_TRANSPORTS = new Set(["stdio", "remote"]);
+const SAFE_MCP_VERSIONS = new Set(["mcp/1.0"]);
+const LOCAL_ERROR_CODES = new Set([
+    "tool_error",
+    "telemetry_http_error",
+    "telemetry_error",
+    "startup_error",
+    "unknown_error",
+]);
+function toolNameToken(value) {
+    return typeof value === "string" && TOOL_NAME.test(value) ? value : undefined;
+}
+function operationalErrorCode(value, statusCode) {
+    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 !== undefined && statusCode >= 400 && statusCode < 500)
+        return "client_error";
+    if (statusCode !== undefined && statusCode >= 500)
+        return "backend_error";
+    return typeof value === "string" && LOCAL_ERROR_CODES.has(value) ? value : "unknown_error";
+}
+function safeInteger(value, min, max) {
+    return typeof value === "number" && Number.isInteger(value) && value >= min && value <= max
+        ? value
+        : undefined;
+}
+/**
+ * Central operational metadata allowlist.
+ *
+ * Callers may pass arbitrary objects for backwards compatibility, but only
+ * bounded protocol/runtime facts can cross the logging boundary. Dynamic
+ * paths, identifiers, user agents, emails, provider bodies, and nested objects
+ * are intentionally discarded.
+ */
+function sanitizeMetadata(metadata) {
+    if (!metadata)
+        return undefined;
+    const safe = {};
+    const version = typeof metadata.version === "string" && PACKAGE_VERSION.test(metadata.version)
+        ? metadata.version
+        : undefined;
+    const transport = typeof metadata.transport === "string" && SAFE_TRANSPORTS.has(metadata.transport)
+        ? metadata.transport
+        : undefined;
+    const mcpVersion = typeof metadata.mcpVersion === "string" && SAFE_MCP_VERSIONS.has(metadata.mcpVersion)
+        ? metadata.mcpVersion
+        : undefined;
+    const method = typeof metadata.method === "string" && SAFE_METHODS.has(metadata.method)
+        ? metadata.method
+        : undefined;
+    const statusCode = safeInteger(metadata.statusCode, 0, 599);
+    const retryCount = safeInteger(metadata.retryCount, 0, 100);
+    const delayMs = safeInteger(metadata.delayMs, 0, 86_400_000);
+    const uptime = safeInteger(metadata.uptime, 0, Number.MAX_SAFE_INTEGER);
+    if (version)
+        safe.version = version;
+    if (transport)
+        safe.transport = transport;
+    if (mcpVersion)
+        safe.mcpVersion = mcpVersion;
+    if (method)
+        safe.method = method;
+    if (statusCode !== undefined)
+        safe.statusCode = statusCode;
+    if (retryCount !== undefined)
+        safe.retryCount = retryCount;
+    if (delayMs !== undefined)
+        safe.delayMs = delayMs;
+    if (uptime !== undefined)
+        safe.uptime = uptime;
+    if (typeof metadata.success === "boolean")
+        safe.success = metadata.success;
+    if (typeof metadata.stub === "boolean")
+        safe.stub = metadata.stub;
+    return Object.keys(safe).length > 0 ? safe : undefined;
+}
 /**
  * Returns true if debug logging is enabled.
  * Checks env var in Node.js; always false in Workers unless overridden.
@@ -25,10 +126,41 @@ export function log(entry) {
     if (entry.level === "debug" && !isDebugEnabled()) {
         return;
     }
+    const operation = typeof entry.operation === "string" && Object.hasOwn(OPERATION_MESSAGES, entry.operation)
+        ? entry.operation
+        : undefined;
+    const tool = toolNameToken(entry.tool);
+    const durationMs = typeof entry.durationMs === "number"
+        && Number.isFinite(entry.durationMs)
+        && entry.durationMs >= 0
+        && entry.durationMs <= 86_400_000
+        ? Math.round(entry.durationMs)
+        : undefined;
+    const errorStatus = safeInteger(entry.error?.statusCode, 0, 599);
+    const errorCode = operationalErrorCode(entry.error?.code, errorStatus);
+    const metadata = sanitizeMetadata(entry.metadata);
     const full = {
-        ...entry,
+        level: entry.level,
+        message: operation === "tool_call" && entry.level === "error"
+            ? "MCP tool call failed"
+            : operation
+                ? (OPERATION_MESSAGES[operation] ?? "MCP operational event")
+                : "MCP operational event",
         service: "frihet-mcp",
         timestamp: new Date().toISOString(),
+        ...(tool ? { tool } : {}),
+        ...(operation ? { operation } : {}),
+        ...(durationMs !== undefined ? { durationMs } : {}),
+        ...(entry.error
+            ? {
+                error: {
+                    message: "MCP operation failed",
+                    code: errorCode,
+                    ...(errorStatus !== undefined ? { statusCode: errorStatus } : {}),
+                },
+            }
+            : {}),
+        ...(metadata ? { metadata } : {}),
     };
     // Remove undefined fields for cleaner output
     const cleaned = JSON.stringify(full, (_key, value) => value === undefined ? undefined : value);
@@ -47,7 +179,7 @@ export function logToolCall(tool, startTime, success, error) {
             operation: "tool_call",
             durationMs,
             error: {
-                message: error.message,
+                message: "MCP operation failed",
                 code: error.errorCode ?? error.name,
                 statusCode: error.statusCode,
             },
@@ -66,25 +198,25 @@ export function logToolCall(tool, startTime, success, error) {
 /**
  * Log an outbound API call with timing.
  */
-export function logApiCall(method, path, statusCode, durationMs) {
+export function logApiCall(method, _path, statusCode, durationMs) {
     const level = statusCode >= 500 ? "error" : statusCode >= 400 ? "warn" : "info";
     log({
         level,
-        message: `${method} ${path} ${statusCode} ${durationMs}ms`,
+        message: "MCP API call completed",
         operation: "api_call",
         durationMs,
-        metadata: { method, path, statusCode },
+        metadata: { method, statusCode },
     });
 }
 /**
  * Log a rate-limit retry.
  */
-export function logRetry(method, path, retryCount, delayMs) {
+export function logRetry(method, _path, retryCount, delayMs) {
     log({
         level: "warn",
-        message: `Rate limited, retrying ${method} ${path} (attempt ${retryCount + 1}, delay ${delayMs}ms)`,
+        message: "MCP API retry scheduled",
         operation: "api_retry",
-        metadata: { method, path, retryCount: retryCount + 1, delayMs },
+        metadata: { method, retryCount: retryCount + 1, delayMs },
     });
 }
 //# sourceMappingURL=logger.js.map

package/dist/observability.d.ts

@@ -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,6 +19,12 @@
  *
  * Docs: https://langfuse.com/docs/api/reference/overview
  */
+/**
+ * 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 declare function normalizeLangfuseBaseUrl(value: string): string;
 /**
  * Called once from FrihetMCP.init() in the Worker to inject env vars.
  * Not needed in Node.js stdio mode (reads from process.env directly).
@@ -33,8 +40,6 @@ interface LangfuseSpanBody {
     name: string;
     startTime: string;
     endTime: string;
-    input?: unknown;
-    output?: unknown;
     metadata?: Record<string, unknown>;
     level?: "DEFAULT" | "DEBUG" | "WARNING" | "ERROR";
     statusMessage?: string;
@@ -43,11 +48,8 @@ interface LangfuseTraceBody {
     id: string;
     name: string;
     timestamp: string;
-    input?: unknown;
-    output?: unknown;
     metadata?: Record<string, unknown>;
     tags?: string[];
-    userId?: string;
 }
 interface IngestionBatch {
     batch: Array<{
@@ -58,8 +60,7 @@ interface IngestionBatch {
     }>;
 }
 interface StubMarker {
-    plannedEndpoint?: string;
-    note?: string;
+    stub: true;
 }
 /**
  * Inspect a resolved tool output for stub / not-implemented / unavailable
@@ -79,33 +80,24 @@ interface StubMarker {
  */
 export declare function inspectStubMarker(output: unknown): StubMarker | null;
 interface TraceContext {
-    /** User-Agent from MCP client or other client identifier */
-    clientName?: string;
     /** MCP protocol version */
     mcpVersion?: string;
-    /** Frihet workspace/user ID — will be hashed */
-    userId?: string;
 }
 /**
- * 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 declare function setTraceContext(ctx: TraceContext): void;
 interface TracePayloadParams {
     toolName: string;
-    /** Raw tool input args (redacted before serialization). */
-    input: unknown;
-    /** Raw tool output (redacted before serialization); ignored when isError. */
-    output: unknown;
     isError: boolean;
-    errorMessage?: string;
+    errorClass?: string;
+    errorCode?: string;
+    statusCode?: number;
     startTime: Date;
     endTime: Date;
     traceId: string;
     spanId: string;
-    /** Already-hashed user id, or undefined. */
-    userIdHashed?: string;
-    clientName?: string;
     mcpVersion?: string;
     /** Fabricated-stub marker, or null on a genuine result. */
     stub: StubMarker | null;
@@ -113,12 +105,9 @@ interface TracePayloadParams {
 /**
  * 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 declare function buildTracePayload(p: TracePayloadParams): IngestionBatch;
 /**
@@ -132,6 +121,6 @@ export declare function buildTracePayload(p: TracePayloadParams): IngestionBatch
  * @param fn        Async tool handler to wrap
  * @returns         Result of fn
  */
-export declare function traceMCPTool<T>(toolName: string, input: unknown, fn: () => Promise<T>): Promise<T>;
+export declare function traceMCPTool<T>(toolName: string, _input: unknown, fn: () => Promise<T>): Promise<T>;
 export {};
 //# sourceMappingURL=observability.d.ts.map