@ffschrattenecker/tm1-mcp-server 6.0.0

package/dist/session-manager.js

@@ -0,0 +1,281 @@
+import { createLogger } from "./logger.js";
+import { createConnectionProfile, } from "./tm1-client/connection/profile.js";
+import { getTm1Dispatcher, tm1Fetch } from "./tm1-client/dispatcher.js";
+import { PRODUCT, VERSION } from "./version.js";
+const USER_AGENT = `${PRODUCT}/${VERSION}`;
+export class TimeoutError extends Error {
+    timeoutMs;
+    constructor(label, timeoutMs) {
+        super(`${label} request timed out after ${timeoutMs}ms`);
+        this.name = "TimeoutError";
+        this.timeoutMs = timeoutMs;
+    }
+}
+async function withTimeout(ms, label, fn) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), ms);
+    try {
+        return await fn(controller.signal);
+    }
+    catch (err) {
+        if (err instanceof DOMException && err.name === "AbortError") {
+            throw new TimeoutError(label, ms);
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export class SessionManager {
+    sessionCookie = null;
+    authInFlight = null;
+    keepAliveTimer = null;
+    config;
+    logger;
+    profile;
+    constructor(config, logger) {
+        this.config = config;
+        this.logger = logger ?? createLogger(config);
+        this.profile = createConnectionProfile(config);
+    }
+    /**
+     * Authenticate against TM1. The auth scheme (Basic / CAMNamespace /
+     * CAMPassport for v11, or the configured v12 auth mode) is selected by
+     * config — see ConnectionProfile.buildLoginRequest in
+     * tm1-client/connection/profile.ts.
+     *
+     * Concurrent callers share a single in-flight login. The HTTP transport
+     * re-authenticates directly from its 401 handler (http.ts), so two requests
+     * whose sessions expire at the same time both land here; without this dedup
+     * each opens a fresh TM1 session and the second login's cookie clobbers the
+     * first, leaving the first request retrying with a now-stale cookie (the
+     * "thundering herd on session expiry" race). All re-auth paths — ensureSession,
+     * keepAlive, and the transport 401 retry — funnel through this guard.
+     *
+     * `staleCookie` (optional): the cookie the caller was using when it decided to
+     * re-auth. If another caller has ALREADY rotated the session since then
+     * (current cookie ≠ stale, and non-null), this returns the fresh cookie
+     * without a logout+login. Without this, a delayed 401 carrying an
+     * already-replaced cookie would tear down the healthy session that concurrent
+     * requests are using — the "staggered-401 re-auth churn" cascade.
+     */
+    async authenticate(staleCookie) {
+        if (staleCookie !== undefined &&
+            this.sessionCookie !== null &&
+            this.sessionCookie !== staleCookie) {
+            return this.sessionCookie;
+        }
+        this.authInFlight ??= this.doAuthenticate().finally(() => {
+            this.authInFlight = null;
+        });
+        return this.authInFlight;
+    }
+    /**
+     * Perform the actual login round-trip. The request (URL, method, headers,
+     * body) comes from the connection profile — v11 GETs
+     * /api/v1/Configuration/ProductVersion, v12 POSTs /{instance}/auth/v1/session.
+     * Extracts TM1SessionId cookie from the response.
+     */
+    async doAuthenticate() {
+        // Close any existing session before opening a new one — prevents
+        // orphaned sessions accumulating on the TM1 server across re-auths.
+        if (this.sessionCookie) {
+            try {
+                await this.logout();
+            }
+            catch (err) {
+                this.logger.warn({ err }, "Failed to logout existing session before re-auth");
+            }
+        }
+        const loginReq = await this.profile.buildLoginRequest();
+        this.logger.info({ endpoint: loginReq.url, authMode: this.authMode() }, "Authenticating with TM1");
+        const response = await withTimeout(this.config.requestTimeoutMs, "Authentication", (signal) => tm1Fetch(loginReq.url, {
+            method: loginReq.method,
+            headers: {
+                ...loginReq.headers,
+                Accept: "application/json",
+                "User-Agent": USER_AGENT,
+                "TM1-SessionContext": USER_AGENT,
+                "TM1-Session-Context": USER_AGENT,
+            },
+            body: loginReq.body,
+            signal,
+            dispatcher: getTm1Dispatcher(this.config),
+        }));
+        // Always consume body to release connection
+        await response.text();
+        if (!response.ok) {
+            this.logger.error({ endpoint: loginReq.url, status: response.status }, "Authentication failed");
+            throw new Error(`Authentication failed with status ${response.status}: ${response.statusText}`);
+        }
+        const cookie = this.extractSessionCookie(response);
+        if (!cookie) {
+            throw new Error("Authentication succeeded but no TM1SessionId cookie found in response");
+        }
+        this.sessionCookie = cookie;
+        this.logger.info("Authentication successful, session established");
+        return cookie;
+    }
+    /**
+     * Send a keep-alive request to maintain the active session.
+     * GET /api/v1/ActiveSession with the session cookie.
+     * On 401, triggers re-authentication.
+     */
+    async keepAlive() {
+        if (!this.sessionCookie) {
+            this.logger.warn("No active session for keep-alive, re-authenticating");
+            await this.authenticate();
+            return;
+        }
+        const url = `${this.config.baseUrl}${this.profile.resolveApiPath("/api/v1/ActiveSession")}`;
+        this.logger.debug({ endpoint: url }, "Sending keep-alive");
+        // Snapshot the cookie this keep-alive is probing. If a concurrent request
+        // rotates the session mid-flight, we must not tear down the fresh cookie on
+        // our (now-stale) 401 — authenticate(usedCookie) handles that.
+        const usedCookie = this.sessionCookie;
+        let response;
+        try {
+            response = await withTimeout(this.config.requestTimeoutMs, "Keep-alive", (signal) => tm1Fetch(url, {
+                method: "GET",
+                headers: {
+                    Cookie: `TM1SessionId=${usedCookie}`,
+                    "User-Agent": USER_AGENT,
+                    "TM1-SessionContext": USER_AGENT,
+                    "TM1-Session-Context": USER_AGENT,
+                },
+                signal,
+                dispatcher: getTm1Dispatcher(this.config),
+            }));
+        }
+        catch (err) {
+            if (err instanceof TimeoutError) {
+                // Clear the cookie so the next real request re-authenticates up front
+                // (via ensureSession) instead of serving the possibly-dead session and
+                // eating a 401 round-trip under load. A keep-alive timeout is a strong
+                // signal the session is no longer healthy.
+                this.logger.error("Keep-alive request timed out; clearing session to force re-auth");
+                this.sessionCookie = null;
+                return;
+            }
+            throw err;
+        }
+        // Always consume body to release connection
+        await response.text();
+        if (response.status === 401) {
+            this.logger.warn("Session expired during keep-alive, re-authenticating");
+            // Pass the probed cookie so a race that already rotated the session is a
+            // no-op here instead of a redundant logout+login (staggered-401 churn).
+            await this.authenticate(usedCookie ?? undefined);
+            return;
+        }
+        if (!response.ok) {
+            this.logger.error({ endpoint: url, status: response.status }, "Keep-alive request failed");
+            throw new Error(`Keep-alive failed with status ${response.status}: ${response.statusText}`);
+        }
+        this.logger.debug("Keep-alive successful");
+    }
+    /**
+     * Ensure an active session exists. If no session cookie is present,
+     * authenticate first. Returns the session cookie.
+     */
+    async ensureSession() {
+        if (this.sessionCookie) {
+            return this.sessionCookie;
+        }
+        // authenticate() dedupes concurrent logins internally (see its doc), so
+        // first-auth races and 401 re-auth races share the same in-flight promise.
+        return this.authenticate();
+    }
+    /**
+     * Start periodic keep-alive requests at the configured interval.
+     */
+    startKeepAlive() {
+        if (this.keepAliveTimer) {
+            this.logger.debug("Keep-alive already running");
+            return;
+        }
+        this.logger.info({ intervalMs: this.config.keepAliveIntervalMs }, "Starting keep-alive timer");
+        this.keepAliveTimer = setInterval(() => {
+            this.keepAlive().catch((err) => {
+                this.logger.error({ err }, "Keep-alive error");
+            });
+        }, this.config.keepAliveIntervalMs);
+        // Don't block Node.js from exiting
+        if (this.keepAliveTimer.unref) {
+            this.keepAliveTimer.unref();
+        }
+    }
+    /**
+     * Stop the periodic keep-alive timer.
+     */
+    stopKeepAlive() {
+        if (this.keepAliveTimer) {
+            clearInterval(this.keepAliveTimer);
+            this.keepAliveTimer = null;
+            this.logger.info("Keep-alive timer stopped");
+        }
+    }
+    /**
+     * Check whether a session cookie is currently held.
+     */
+    isSessionActive() {
+        return this.sessionCookie !== null;
+    }
+    /**
+     * Logout from TM1 by deleting the active session.
+     * DELETE /api/v1/ActiveSession
+     */
+    async logout() {
+        if (!this.sessionCookie) {
+            return;
+        }
+        const url = `${this.config.baseUrl}${this.profile.resolveApiPath("/api/v1/ActiveSession")}`;
+        this.logger.info("Logging out from TM1");
+        try {
+            // Bound the logout request — authenticate() calls logout() first, so a
+            // hung DELETE (slow/unreachable server) would otherwise block re-auth
+            // indefinitely. On timeout we still clear the cookie below.
+            const response = await withTimeout(this.config.requestTimeoutMs, "Logout", (signal) => tm1Fetch(url, {
+                method: "DELETE",
+                headers: {
+                    Cookie: `TM1SessionId=${this.sessionCookie}`,
+                    "User-Agent": USER_AGENT,
+                    "TM1-SessionContext": USER_AGENT,
+                    "TM1-Session-Context": USER_AGENT,
+                },
+                dispatcher: getTm1Dispatcher(this.config),
+                signal,
+            }));
+            // Consume body to release connection
+            await response.text();
+            this.sessionCookie = null;
+            this.logger.info("Logged out from TM1");
+        }
+        catch (error) {
+            this.logger.error({ err: error }, "Error during logout");
+            this.sessionCookie = null;
+        }
+    }
+    /** Human-readable auth mode for logging (never logs the credential itself). */
+    authMode() {
+        if (this.config.version === 12)
+            return `v12:${this.config.authMode ?? "s2s"}`;
+        if (this.config.camPassport)
+            return "CAMPassport";
+        if (this.config.namespace)
+            return "CAMNamespace";
+        return "Basic";
+    }
+    /**
+     * Extract TM1SessionId Set-Cookie response headers.
+     */
+    extractSessionCookie(response) {
+        const setCookie = response.headers.get("set-cookie");
+        if (!setCookie)
+            return null;
+        const match = setCookie.match(/TM1SessionId=([^;]+)/);
+        return match ? (match[1] ?? null) : null;
+    }
+}
+//# sourceMappingURL=session-manager.js.map

package/dist/tm1-client/connection/profile.d.ts

@@ -0,0 +1,13 @@
+import type { TM1Config } from "../../config.js";
+export interface LoginRequest {
+    url: string;
+    method: "GET" | "POST";
+    headers: Record<string, string>;
+    body?: string;
+}
+export interface ConnectionProfile {
+    resolveApiPath(path: string): string;
+    buildLoginRequest(): Promise<LoginRequest>;
+}
+export declare function createConnectionProfile(config: TM1Config): ConnectionProfile;
+//# sourceMappingURL=profile.d.ts.map

package/dist/tm1-client/connection/profile.js

@@ -0,0 +1,99 @@
+// OData single-quote escaping for a key segment (double the apostrophes),
+// then URL-encode. Mirrors the `enc` helper used across the service layer.
+const enc = (s) => encodeURIComponent(String(s).replace(/'/g, "''"));
+function buildBasicToken(user, password) {
+    return "Basic " + Buffer.from(`${user}:${password}`).toString("base64");
+}
+// v11 Authorization header (Basic / CAMNamespace / CAMPassport). Lives here
+// (rather than on SessionManager) so all login-header logic — v11 and v12 —
+// is in one place.
+function buildV11Authorization(config) {
+    const { user, password, namespace, camPassport } = config;
+    if (camPassport)
+        return `CAMPassport ${camPassport}`;
+    if (namespace) {
+        return ("CAMNamespace " +
+            Buffer.from(`${user}:${password}:${namespace}`).toString("base64"));
+    }
+    return buildBasicToken(user, password);
+}
+export function createConnectionProfile(config) {
+    if (config.version === 12) {
+        // Implemented in Task 3.
+        return createV12Profile(config);
+    }
+    return {
+        resolveApiPath: (path) => path,
+        buildLoginRequest: () => Promise.resolve({
+            url: `${config.baseUrl}/api/v1/Configuration/ProductVersion`,
+            method: "GET",
+            headers: { Authorization: buildV11Authorization(config) },
+        }),
+    };
+}
+// IBM IAM api-key → access_token exchange (v12 iam mode). Mirrors TM1py's
+// _generate_ibm_iam_cloud_access_token. Bounded by timeoutMs so a hung IAM
+// endpoint can't hang authenticate() forever.
+async function exchangeIamApiKey(apiKey, iamUrl, timeoutMs) {
+    const body = "grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey&apikey=" +
+        encodeURIComponent(apiKey);
+    const response = await fetch(iamUrl, {
+        method: "POST",
+        headers: {
+            Accept: "application/json",
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body,
+        signal: AbortSignal.timeout(timeoutMs ?? 30000),
+    });
+    if (!response.ok) {
+        throw new Error(`IAM token exchange failed with status ${response.status}`);
+    }
+    const json = (await response.json());
+    if (!json.access_token) {
+        throw new Error(`IAM token exchange returned no access_token from ${iamUrl}`);
+    }
+    return json.access_token;
+}
+// The Authorization header for a v12 login POST, by auth mode.
+async function buildV12Authorization(config) {
+    switch (config.authMode) {
+        case "s2s":
+            return ("Basic " +
+                Buffer.from(`${config.clientId}:${config.clientSecret}`).toString("base64"));
+        case "basic":
+            return buildBasicToken(config.user, config.password);
+        case "access_token":
+        case "oidc":
+            return `Bearer ${config.accessToken}`;
+        case "iam": {
+            const token = await exchangeIamApiKey(config.apiKey ?? "", config.iamUrl ?? "", config.requestTimeoutMs);
+            return `Bearer ${token}`;
+        }
+        default:
+            throw new Error(`Unsupported v12 auth mode: ${String(config.authMode)}`);
+    }
+}
+function createV12Profile(config) {
+    const instance = config.instance ?? "";
+    const database = config.database ?? "";
+    // encodeURIComponent (not `enc`) for the instance: it's a bare path segment,
+    // not an OData quoted key — no apostrophe-doubling needed, just percent-encoding.
+    const dbRoot = `/${encodeURIComponent(instance)}/api/v1/Databases('${enc(database)}')`;
+    return {
+        // Replacement FUNCTION, not a string: String.replace treats "$&"/"$$"/"$1"
+        // in a string replacement specially, which would corrupt dbRoot if instance
+        // or database contained a literal "$". A function return is used verbatim.
+        resolveApiPath: (path) => path.replace(/^\/api\/v1/, () => dbRoot),
+        buildLoginRequest: async () => ({
+            url: `${config.baseUrl}/${encodeURIComponent(instance)}/auth/v1/session`,
+            method: "POST",
+            headers: {
+                Authorization: await buildV12Authorization(config),
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ User: config.user }),
+        }),
+    };
+}
+//# sourceMappingURL=profile.js.map

package/dist/tm1-client/dispatcher.d.ts

@@ -0,0 +1,5 @@
+import { Agent } from "undici";
+import type { TM1Config } from "../config.js";
+export declare function getTm1Dispatcher(config: TM1Config): Agent | undefined;
+export declare function tm1Fetch(url: string, init: RequestInit): Promise<Response>;
+//# sourceMappingURL=dispatcher.d.ts.map

package/dist/tm1-client/dispatcher.js

@@ -0,0 +1,31 @@
+// Per-request TLS dispatcher for TM1 fetches. Replaces the previous
+// `process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0"` global side-effect, which
+// disabled TLS verification for the entire Node process (including unrelated
+// HTTPS calls from MCP transport, telemetry, etc.). With undici's Agent we
+// scope `rejectUnauthorized: false` to TM1 fetches only.
+//
+// The Agent is cached so connection-pooling stays effective across requests.
+import { Agent, fetch as undiciFetch } from "undici";
+let cachedAgent;
+export function getTm1Dispatcher(config) {
+    if (config.ssl.rejectUnauthorized)
+        return undefined;
+    if (!cachedAgent) {
+        cachedAgent = new Agent({ connect: { rejectUnauthorized: false } });
+    }
+    return cachedAgent;
+}
+// Node's BUILT-IN fetch silently drops Set-Cookie headers when handed a
+// dispatcher from the npm undici package (cross-instance Headers handling;
+// reproduced on Node 26 + undici 7.25 — auth broke with "no TM1SessionId
+// cookie found"). Pair the npm Agent with the npm fetch instead, where the
+// instances match. Unit tests stub globalThis.fetch — honor the stub when
+// present (identity check against the built-in captured at module load).
+const builtinFetch = globalThis.fetch;
+export function tm1Fetch(url, init) {
+    if (globalThis.fetch !== builtinFetch) {
+        return globalThis.fetch(url, init);
+    }
+    return undiciFetch(url, init);
+}
+//# sourceMappingURL=dispatcher.js.map

package/dist/tm1-client/http.d.ts

@@ -0,0 +1,81 @@
+import type pino from "pino";
+import type { TM1Config } from "../config.js";
+import type { SessionManager } from "../session-manager.js";
+import { TM1Error } from "../types.js";
+export interface RequestOptions {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    retry?: boolean;
+}
+export declare class TM1HttpClient {
+    private readonly config;
+    readonly logger: pino.Logger;
+    protected readonly sessionManager: SessionManager;
+    private readonly profile;
+    constructor(config: TM1Config, sessionManager: SessionManager, logger: pino.Logger);
+    /**
+     * TM1 major version (11 | 12) — the single numeric source of truth for
+     * version-conditional service code. Branch on this, never on the display
+     * string (`tm1Version`): a v12 connection can carry a "11.x"-looking
+     * TM1_VERSION string, but `version` is always authoritative.
+     */
+    get version(): 11 | 12;
+    /**
+     * TM1 server version STRING (e.g. "11.8.…") — DISPLAY ONLY (server_info
+     * output, log fields, user-facing error messages). Do NOT branch on this;
+     * use the numeric `version` getter instead.
+     */
+    get tm1Version(): string;
+    /**
+     * Make an authenticated HTTP request to the TM1 REST API.
+     *
+     * - Ensures an active session via SessionManager
+     * - On 401: re-authenticates once and retries
+     * - On network error for safe methods (GET/HEAD): retries up to 3 times with exponential backoff (1s, 2s, 4s)
+     * - On network error for non-safe methods (POST/PUT/PATCH/DELETE): does NOT retry — these are not idempotent
+     *   and a retry could spawn duplicate side-effects (e.g. parallel TI runs on tm1.Execute)
+     * - On other HTTP errors: classifies and throws TM1Error
+     */
+    /** @internal — for Service-layer use; not part of the public consumer API. */
+    request<T = unknown>(method: string, path: string, body?: unknown, opts?: RequestOptions): Promise<T>;
+    /**
+     * Make an authenticated HTTP request that returns raw text (not JSON).
+     * Used for file content downloads where the response is CSV/TXT/etc.
+     * Re-auths once on 401 like request().
+     */
+    /** @internal — for Service-layer use; not part of the public consumer API. */
+    requestRaw(method: string, path: string, opts?: RequestOptions): Promise<string>;
+    /**
+     * Make an authenticated HTTP request with a binary body (Buffer/Uint8Array).
+     * Used for blob/file uploads where the body is raw bytes (not JSON).
+     * Sends Content-Type: application/octet-stream by default.
+     * Re-auths once on 401 like request(). No network-error retries (non-safe methods).
+     */
+    /** @internal — for Service-layer use; not part of the public consumer API. */
+    requestBinary(method: string, path: string, body: Uint8Array, contentType?: string, opts?: RequestOptions): Promise<void>;
+    /**
+     * Low-level single fetch with timeout + AbortSignal wiring.
+     * Does NOT handle 401, retries, or error classification — callers own that.
+     */
+    private sendOnce;
+    /**
+     * Wraps a send function with cookie-refresh-on-401 and timeout→LOCK_TIMEOUT mapping.
+     * Used by requestRaw and requestBinary (which have no network-retry loop).
+     * On 401: calls sessionManager.authenticate() and retries once with the new cookie.
+     * The caller is responsible for obtaining the initial cookie via ensureSession().
+     */
+    private withReauth;
+    private executeRequest;
+    private handleResponse;
+    private classifyHttpError;
+    private isNetworkError;
+}
+/**
+ * Map an HTTP status + TM1 error text onto a TM1Error. Module-level (not just a
+ * TM1HttpClient method) because `$batch` sub-responses arrive as plain
+ * {status, body} records inside a 200 envelope — BatchService has to classify
+ * them itself, and must do it identically to a standalone request rather than
+ * with a drifting copy of these rules.
+ */
+export declare function classifyHttpError(status: number, endpoint: string, rawDetails?: string): TM1Error;
+//# sourceMappingURL=http.d.ts.map