@kontext-dev/js-sdk 0.1.0

package/dist/server/index.js

@@ -0,0 +1,1629 @@
+import { createHash } from 'crypto';
+import { createRequire } from 'module';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
+import { mcpAuthMetadataRouter, getOAuthProtectedResourceMetadataUrl } from '@modelcontextprotocol/sdk/server/auth/router.js';
+import { requireBearerAuth } from '@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js';
+import { InvalidTokenError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
+import { jwtVerify, errors, decodeProtectedHeader, createRemoteJWKSet } from 'jose';
+
+// src/server/kontext.ts
+
+// src/management/types.ts
+var TOKEN_EXCHANGE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:token-exchange";
+var TOKEN_TYPE_ACCESS_TOKEN = "urn:ietf:params:oauth:token-type:access_token";
+
+// src/errors.ts
+var KontextError = class extends Error {
+  /** Brand field for type narrowing without instanceof */
+  kontextError = true;
+  /** Machine-readable error code, always prefixed with `kontext_` */
+  code;
+  /** HTTP status code when applicable */
+  statusCode;
+  /** Auto-generated link to error documentation */
+  docsUrl;
+  /** Server request ID for debugging / support escalation */
+  requestId;
+  /** Contextual metadata bag (integration IDs, param names, etc.) */
+  meta;
+  constructor(message, code, options) {
+    super(message, { cause: options?.cause });
+    this.name = "KontextError";
+    this.code = code;
+    this.statusCode = options?.statusCode;
+    this.requestId = options?.requestId;
+    this.meta = options?.meta ?? {};
+    this.docsUrl = `https://docs.kontext.dev/errors/${code}`;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      statusCode: this.statusCode,
+      docsUrl: this.docsUrl,
+      requestId: this.requestId,
+      meta: Object.keys(this.meta).length > 0 ? this.meta : void 0
+    };
+  }
+  toString() {
+    const parts = [`[${this.code}] ${this.message}`];
+    if (this.docsUrl) parts.push(`Docs: ${this.docsUrl}`);
+    if (this.requestId) parts.push(`Request ID: ${this.requestId}`);
+    return parts.join("\n");
+  }
+};
+var OAuthError = class extends KontextError {
+  errorCode;
+  errorDescription;
+  constructor(message, code, options) {
+    super(message, code, {
+      statusCode: options?.statusCode ?? 400,
+      ...options
+    });
+    this.name = "OAuthError";
+    this.errorCode = options?.errorCode;
+    this.errorDescription = options?.errorDescription;
+  }
+};
+var IntegrationConnectionRequiredError = class extends KontextError {
+  integrationId;
+  integrationName;
+  connectUrl;
+  constructor(integrationId, options) {
+    super(
+      options?.message ?? `Connection to integration "${integrationId}" is required. Visit the connect URL to authorize.`,
+      "kontext_integration_connection_required",
+      { statusCode: 403, ...options }
+    );
+    this.name = "IntegrationConnectionRequiredError";
+    this.integrationId = integrationId;
+    this.integrationName = options?.integrationName;
+    this.connectUrl = options?.connectUrl;
+  }
+};
+
+// src/oauth/token-exchange.ts
+async function exchangeToken(config, subjectToken, resource, scope, subjectTokenType = TOKEN_TYPE_ACCESS_TOKEN) {
+  const body = new URLSearchParams();
+  body.set("grant_type", TOKEN_EXCHANGE_GRANT_TYPE);
+  body.set("subject_token", subjectToken);
+  body.set("subject_token_type", subjectTokenType);
+  body.set("resource", resource);
+  const headers = {
+    "Content-Type": "application/x-www-form-urlencoded"
+  };
+  if (config.clientSecret) {
+    const credentials = Buffer.from(
+      `${config.clientId}:${config.clientSecret}`
+    ).toString("base64");
+    headers["Authorization"] = `Basic ${credentials}`;
+  } else {
+    body.set("client_id", config.clientId);
+  }
+  const response = await fetch(config.tokenUrl, {
+    method: "POST",
+    headers,
+    body: body.toString()
+  });
+  if (!response.ok) {
+    let errorMessage = `Token exchange failed: ${response.status} ${response.statusText}`;
+    let errorCode;
+    let integrationName;
+    let integrationId;
+    try {
+      const errorBody = await response.json();
+      errorCode = errorBody.error;
+      if (errorBody.error_description) {
+        errorMessage = errorBody.error_description;
+      } else if (errorBody.error) {
+        errorMessage = `Token exchange failed: ${errorBody.error}`;
+      }
+      if (errorBody.integration_name || errorBody.integration_id) {
+        integrationName = errorBody.integration_name;
+        integrationId = errorBody.integration_id;
+      }
+    } catch {
+    }
+    throw new OAuthError(errorMessage, "kontext_oauth_token_exchange_failed", {
+      errorCode,
+      meta: {
+        integrationName,
+        integrationId
+      }
+    });
+  }
+  const tokenResponse = await response.json();
+  if (!tokenResponse.access_token) {
+    throw new OAuthError(
+      "Token exchange response missing access_token.",
+      "kontext_oauth_token_exchange_failed"
+    );
+  }
+  if (!tokenResponse.issued_token_type) {
+    throw new OAuthError(
+      "Token exchange response missing issued_token_type.",
+      "kontext_oauth_token_exchange_failed"
+    );
+  }
+  if (!tokenResponse.token_type) {
+    throw new OAuthError(
+      "Token exchange response missing token_type.",
+      "kontext_oauth_token_exchange_failed"
+    );
+  }
+  return tokenResponse;
+}
+
+// src/verify/errors.ts
+var TokenVerificationError = class _TokenVerificationError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "TokenVerificationError";
+    this.code = code;
+    Object.setPrototypeOf(this, _TokenVerificationError.prototype);
+  }
+};
+
+// src/verify/jwks-client.ts
+var DEFAULT_CACHE_TTL_MS = 5 * 60 * 1e3;
+var DEFAULT_REFETCH_COOLDOWN_MS = 30 * 1e3;
+var JwksClient = class {
+  jwksUrl;
+  cacheTtlMs;
+  refetchCooldownMs;
+  customFetch;
+  jwks = null;
+  lastFetchAt = 0;
+  lastRefreshAt = 0;
+  constructor(options) {
+    this.jwksUrl = new URL(options.jwksUrl);
+    this.cacheTtlMs = options.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
+    this.refetchCooldownMs = options.refetchCooldownMs ?? DEFAULT_REFETCH_COOLDOWN_MS;
+    this.customFetch = options.fetch;
+  }
+  /**
+   * Get the JWKS key resolver for use with jose's jwtVerify.
+   *
+   * Creates the remote JWKS on first call and caches it.
+   * The jose library handles internal caching and key lookup.
+   */
+  getKeyResolver() {
+    const now = Date.now();
+    if (this.jwks && now - this.lastFetchAt > this.cacheTtlMs) {
+      this.jwks = null;
+    }
+    if (!this.jwks) {
+      this.jwks = createRemoteJWKSet(this.jwksUrl, {
+        // jose handles caching internally, we just track our own refresh timing
+        ...this.customFetch && {
+          [/* @__PURE__ */ Symbol.for("fetch")]: this.customFetch
+        }
+      });
+      this.lastFetchAt = now;
+    }
+    return this.jwks;
+  }
+  /**
+   * Force refresh the JWKS cache.
+   *
+   * Respects the refetch cooldown to prevent rapid refetching.
+   * Returns true if refresh was performed, false if cooldown not elapsed.
+   */
+  refresh() {
+    const now = Date.now();
+    if (!this.canRefresh()) {
+      return false;
+    }
+    this.jwks = null;
+    this.lastRefreshAt = now;
+    return true;
+  }
+  /**
+   * Check if a refresh is allowed (cooldown elapsed).
+   */
+  canRefresh() {
+    return Date.now() - this.lastRefreshAt >= this.refetchCooldownMs;
+  }
+  /**
+   * Handle unknown kid errors by attempting refresh.
+   *
+   * @returns TokenVerificationError if refresh not allowed or already attempted
+   */
+  handleUnknownKid(kid) {
+    if (this.refresh()) {
+      return null;
+    }
+    return new TokenVerificationError(
+      "UNKNOWN_KID",
+      `Unknown key ID: ${kid}. JWKS refresh on cooldown.`
+    );
+  }
+  /**
+   * Clear the cache, forcing a fresh fetch on next access.
+   */
+  clearCache() {
+    this.jwks = null;
+    this.lastFetchAt = 0;
+  }
+};
+
+// src/verify/verifier.ts
+var DEFAULT_CLOCK_TOLERANCE_SEC = 30;
+var SUPPORTED_ALGORITHMS = ["ES256", "RS256"];
+var KontextTokenVerifier = class {
+  config;
+  jwksClient;
+  audiences;
+  constructor(config) {
+    this.config = {
+      jwksUrl: config.jwksUrl,
+      issuer: config.issuer,
+      audience: config.audience,
+      requiredScopes: config.requiredScopes ?? [],
+      cacheTtlMs: config.cacheTtlMs ?? 5 * 60 * 1e3,
+      refetchCooldownMs: config.refetchCooldownMs ?? 30 * 1e3,
+      clockToleranceSec: config.clockToleranceSec ?? DEFAULT_CLOCK_TOLERANCE_SEC,
+      fetch: config.fetch
+    };
+    this.audiences = Array.isArray(config.audience) ? config.audience : [config.audience];
+    this.jwksClient = new JwksClient({
+      jwksUrl: config.jwksUrl,
+      cacheTtlMs: this.config.cacheTtlMs,
+      refetchCooldownMs: this.config.refetchCooldownMs,
+      fetch: config.fetch
+    });
+  }
+  /**
+   * Verify a JWT token.
+   *
+   * @param token - The JWT token string (without "Bearer " prefix)
+   * @returns VerifyResult with success=true and claims, or success=false and error
+   */
+  async verify(token) {
+    try {
+      return await this.verifyInternal(token, false);
+    } catch (error) {
+      if (error instanceof TokenVerificationError) {
+        return { success: false, error };
+      }
+      return {
+        success: false,
+        error: new TokenVerificationError(
+          "INVALID_TOKEN_FORMAT",
+          `Unexpected verification error: ${error.message}`
+        )
+      };
+    }
+  }
+  /**
+   * Verify a JWT token and return claims or null.
+   * Simpler API for cases where you don't need error details.
+   *
+   * @param token - The JWT token string (without "Bearer " prefix)
+   * @returns VerifiedTokenClaims if valid, null if invalid
+   */
+  async verifyOrNull(token) {
+    const result = await this.verify(token);
+    return result.success ? result.claims : null;
+  }
+  /**
+   * Clear the JWKS cache, forcing a fresh fetch on next verification.
+   */
+  clearCache() {
+    this.jwksClient.clearCache();
+  }
+  async verifyInternal(token, isRetry) {
+    const JWKS = this.jwksClient.getKeyResolver();
+    try {
+      const { payload, protectedHeader } = await jwtVerify(token, JWKS, {
+        issuer: this.config.issuer,
+        audience: this.audiences,
+        clockTolerance: this.config.clockToleranceSec,
+        algorithms: SUPPORTED_ALGORITHMS
+      });
+      const alg = protectedHeader.alg;
+      if (!SUPPORTED_ALGORITHMS.includes(alg)) {
+        throw new TokenVerificationError(
+          "UNSUPPORTED_ALGORITHM",
+          `Unsupported algorithm: ${alg}. Expected one of: ${SUPPORTED_ALGORITHMS.join(", ")}`
+        );
+      }
+      const jwtPayload = payload;
+      if (typeof jwtPayload.exp !== "number" || !Number.isFinite(jwtPayload.exp) || jwtPayload.exp <= 0) {
+        throw new TokenVerificationError(
+          "MISSING_CLAIMS",
+          "Token missing required exp claim"
+        );
+      }
+      const scopes = this.parseScopes(jwtPayload.scope);
+      for (const required of this.config.requiredScopes) {
+        if (!scopes.includes(required)) {
+          throw new TokenVerificationError(
+            "MISSING_SCOPE",
+            `Missing required scope: ${required}`
+          );
+        }
+      }
+      const clientId = jwtPayload.client_id || jwtPayload.sub;
+      if (!clientId) {
+        throw new TokenVerificationError(
+          "MISSING_CLAIMS",
+          "Token missing client_id and sub claims"
+        );
+      }
+      const claims = {
+        sub: jwtPayload.sub || "",
+        clientId,
+        scopes,
+        expiresAt: new Date(jwtPayload.exp * 1e3),
+        jti: jwtPayload.jti,
+        payload: jwtPayload
+      };
+      return { success: true, claims };
+    } catch (error) {
+      if (error instanceof errors.JWKSNoMatchingKey) {
+        if (!isRetry) {
+          const kid = this.extractKid(token);
+          const refreshError = this.jwksClient.handleUnknownKid(
+            kid || "unknown"
+          );
+          if (!refreshError) {
+            return this.verifyInternal(token, true);
+          }
+          return { success: false, error: refreshError };
+        }
+        return {
+          success: false,
+          error: new TokenVerificationError(
+            "UNKNOWN_KID",
+            "No matching key found in JWKS"
+          )
+        };
+      }
+      if (error instanceof errors.JWTExpired) {
+        return {
+          success: false,
+          error: new TokenVerificationError(
+            "TOKEN_EXPIRED",
+            "Token has expired"
+          )
+        };
+      }
+      if (error instanceof errors.JWTClaimValidationFailed) {
+        const message = error.message;
+        if (message.includes("iss")) {
+          const expected = Array.isArray(this.config.issuer) ? this.config.issuer.join(" or ") : this.config.issuer;
+          return {
+            success: false,
+            error: new TokenVerificationError(
+              "INVALID_ISSUER",
+              `Invalid issuer: expected ${expected}`
+            )
+          };
+        }
+        if (message.includes("aud")) {
+          return {
+            success: false,
+            error: new TokenVerificationError(
+              "INVALID_AUDIENCE",
+              `Invalid audience: expected one of ${this.audiences.join(", ")}`
+            )
+          };
+        }
+        if (message.includes("nbf")) {
+          return {
+            success: false,
+            error: new TokenVerificationError(
+              "TOKEN_NOT_YET_VALID",
+              "Token is not yet valid (nbf claim)"
+            )
+          };
+        }
+      }
+      if (error instanceof errors.JWSSignatureVerificationFailed) {
+        return {
+          success: false,
+          error: new TokenVerificationError(
+            "INVALID_SIGNATURE",
+            "Signature verification failed"
+          )
+        };
+      }
+      if (error instanceof errors.JWSInvalid) {
+        return {
+          success: false,
+          error: new TokenVerificationError(
+            "INVALID_TOKEN_FORMAT",
+            `Invalid JWS: ${error.message}`
+          )
+        };
+      }
+      if (error instanceof TokenVerificationError) {
+        throw error;
+      }
+      throw new TokenVerificationError(
+        "INVALID_TOKEN_FORMAT",
+        `Verification failed: ${error.message}`
+      );
+    }
+  }
+  parseScopes(scope) {
+    if (!scope) return [];
+    return scope.split(" ").map((s) => s.trim()).filter(Boolean);
+  }
+  extractKid(token) {
+    try {
+      const header = decodeProtectedHeader(token);
+      return header.kid ?? null;
+    } catch {
+      return null;
+    }
+  }
+};
+
+// src/server/sessions.ts
+var SessionManager = class _SessionManager {
+  transports = /* @__PURE__ */ new Map();
+  lastAccessed = /* @__PURE__ */ new Map();
+  expiresAt = /* @__PURE__ */ new Map();
+  cleanupInterval;
+  static STALE_TIMEOUT_MS = 60 * 60 * 1e3;
+  // 1 hour
+  static CLEANUP_INTERVAL_MS = 5 * 60 * 1e3;
+  // 5 minutes
+  constructor() {
+    this.cleanupInterval = setInterval(
+      () => this.cleanupStaleSessions(),
+      _SessionManager.CLEANUP_INTERVAL_MS
+    );
+    if (this.cleanupInterval.unref) {
+      this.cleanupInterval.unref();
+    }
+  }
+  getTransport(sessionId) {
+    return this.transports.get(sessionId);
+  }
+  registerSession(sessionId, transport, callbacks, expiresAt) {
+    this.transports.set(sessionId, transport);
+    this.lastAccessed.set(sessionId, Date.now());
+    if (expiresAt !== void 0) {
+      this.expiresAt.set(sessionId, expiresAt);
+    }
+    transport.onclose = () => {
+      this.removeSession(sessionId);
+      callbacks?.onSessionClosed?.(sessionId);
+    };
+  }
+  touchSession(sessionId) {
+    if (this.transports.has(sessionId)) {
+      this.lastAccessed.set(sessionId, Date.now());
+    }
+  }
+  removeSession(sessionId) {
+    this.transports.delete(sessionId);
+    this.lastAccessed.delete(sessionId);
+    this.expiresAt.delete(sessionId);
+  }
+  /**
+   * Check if a session's token has expired.
+   * Returns true if the token's `expiresAt` has passed.
+   */
+  isSessionExpired(sessionId) {
+    const exp = this.expiresAt.get(sessionId);
+    return exp !== void 0 && Date.now() / 1e3 >= exp;
+  }
+  cleanupStaleSessions() {
+    const now = Date.now();
+    for (const [sid, lastTime] of this.lastAccessed.entries()) {
+      if (now - lastTime > _SessionManager.STALE_TIMEOUT_MS) {
+        const transport = this.transports.get(sid);
+        if (transport) {
+          void transport.close?.();
+        }
+        this.removeSession(sid);
+      }
+    }
+  }
+  destroy() {
+    clearInterval(this.cleanupInterval);
+    for (const [sid, transport] of this.transports.entries()) {
+      void transport.close?.();
+      this.removeSession(sid);
+    }
+  }
+};
+
+// src/server/kontext.ts
+var DEFAULT_API_URL = "https://api.kontext.dev";
+var METADATA_CACHE_TTL_MS = 60 * 60 * 1e3;
+var CREDENTIAL_CACHE_MAX_ENTRIES = 500;
+var RUNTIME_AUTH_CACHE_MAX_ENTRIES = 8;
+var RESOLVED_CREDENTIAL_CACHE_TTL_MS = 30 * 1e3;
+var SDK_VERSION = (() => {
+  try {
+    const esmRequire = createRequire(import.meta.url);
+    const pkg = esmRequire("../../package.json");
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+})();
+var Kontext = class _Kontext {
+  static shutdownInstances = /* @__PURE__ */ new Set();
+  static shutdownHandlersRegistered = false;
+  clientId;
+  clientSecret;
+  apiUrl;
+  tokenIssuers;
+  // AS metadata: fetched lazily, cached with TTL
+  oauthMetadata = null;
+  metadataFetchedAt = 0;
+  metadataPromise = null;
+  // Token exchange caching: keyed by `${integration}\0${subjectToken}`
+  credentialCache = /* @__PURE__ */ new Map();
+  resolvedCredentialCache = /* @__PURE__ */ new Map();
+  runtimeAuthCache = /* @__PURE__ */ new Map();
+  runtimeVerifierIds = /* @__PURE__ */ new WeakMap();
+  runtimeVerifierIdCounter = 0;
+  // Telemetry: cached service token for event reporting
+  serviceToken = null;
+  serviceTokenExp = 0;
+  serviceTokenPromise = null;
+  // Session tracking: MCP sessionId → API agentSessionId
+  agentSessionIds = /* @__PURE__ */ new Map();
+  pendingSessionDisconnects = /* @__PURE__ */ new Set();
+  constructor(options) {
+    this.clientId = options.clientId;
+    this.clientSecret = options.clientSecret ?? process.env.KONTEXT_CLIENT_SECRET;
+    this.apiUrl = (options.apiUrl ?? DEFAULT_API_URL).replace(/\/$/, "");
+    const rawTokenIssuers = Array.isArray(options.tokenIssuer) ? options.tokenIssuer : options.tokenIssuer ? options.tokenIssuer.split(",") : process.env.KONTEXT_TOKEN_ISSUER?.split(",");
+    this.tokenIssuers = Array.from(
+      new Set(rawTokenIssuers?.map((issuer) => issuer.trim()).filter(Boolean))
+    );
+    _Kontext.shutdownInstances.add(this);
+    _Kontext.ensureShutdownHandlers();
+  }
+  /**
+   * Cleanup method for runtimes that create/dispose SDK instances dynamically.
+   * Ensures this instance can be garbage-collected by removing static references.
+   */
+  async destroy() {
+    await this.disconnectAllSessions();
+    _Kontext.shutdownInstances.delete(this);
+    this.credentialCache.clear();
+    this.resolvedCredentialCache.clear();
+    this.oauthMetadata = null;
+    this.metadataFetchedAt = 0;
+    this.metadataPromise = null;
+    this.serviceToken = null;
+    this.serviceTokenExp = 0;
+    this.serviceTokenPromise = null;
+    this.agentSessionIds.clear();
+    this.pendingSessionDisconnects.clear();
+  }
+  static ensureShutdownHandlers() {
+    if (_Kontext.shutdownHandlersRegistered) return;
+    const onShutdown = () => {
+      for (const instance of _Kontext.shutdownInstances) {
+        void instance.disconnectAllSessions();
+      }
+    };
+    process.once("SIGINT", onShutdown);
+    process.once("SIGTERM", onShutdown);
+    _Kontext.shutdownHandlersRegistered = true;
+  }
+  // ===========================================================================
+  // middleware()
+  // ===========================================================================
+  /**
+   * Express middleware: `.well-known` metadata + bearer auth + MCP transport + sessions.
+   *
+   * Must be mounted at the app root (not a sub-path) because RFC 9728 requires
+   * `/.well-known/oauth-protected-resource` at the root. Use `mcpPath` to set
+   * the transport endpoint path.
+   *
+   * @param server - An `McpServer` instance for single-session use, or a
+   *   `() => McpServer` factory for concurrent sessions (recommended in production).
+   *   `McpServer.connect()` is 1:1 per the MCP spec — passing a factory ensures
+   *   each session gets its own instance.
+   *
+   * @example Factory pattern (recommended for concurrent sessions)
+   * ```typescript
+   * app.use(kontext.middleware(() => createServer()));
+   * ```
+   *
+   * @example Single instance (local dev / single session)
+   * ```typescript
+   * app.use(kontext.middleware(server));
+   * ```
+   *
+   * @example Custom path
+   * ```typescript
+   * app.use(kontext.middleware(createServer, { mcpPath: "/api/mcp" }));
+   * ```
+   */
+  middleware(server, options) {
+    const esmRequire = createRequire(import.meta.url);
+    const express = esmRequire("express");
+    const router = express.Router();
+    const mcpPath = options?.mcpPath ?? "/mcp";
+    const sessionManager = new SessionManager();
+    const omitAuth = options?.dangerouslyOmitAuth ?? false;
+    router.use((_req, res, next) => {
+      res.header("Access-Control-Allow-Origin", "*");
+      res.header(
+        "Access-Control-Allow-Headers",
+        "Content-Type, Authorization, Mcp-Session-Id, Mcp-Protocol-Version, Accept"
+      );
+      res.header("Access-Control-Expose-Headers", "Mcp-Session-Id");
+      res.header("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+      if (_req.method === "OPTIONS") {
+        res.sendStatus(204);
+        return;
+      }
+      next();
+    });
+    if (omitAuth) {
+      console.warn(
+        "[kontext] \u26A0\uFE0F  Auth is disabled (dangerouslyOmitAuth). Do NOT use in production."
+      );
+      router.use(mcpPath, express.json({ limit: options?.bodyLimit ?? "1mb" }));
+      const mcpHandler2 = this.createMcpHandler(
+        server,
+        sessionManager,
+        null,
+        options
+      );
+      router.post(mcpPath, mcpHandler2.post);
+      router.get(mcpPath, mcpHandler2.get);
+      router.delete(mcpPath, mcpHandler2.delete);
+      return router;
+    }
+    const getRuntimeAuth = async (req) => {
+      const metadata = this.applyMetadataTransform(
+        await this.getOAuthMetadata(),
+        options?.metadataTransform
+      );
+      const rsUrl = this.resolveResourceServerUrl(req, mcpPath, options);
+      return this.getOrCreateRuntimeAuthContext(
+        metadata,
+        rsUrl,
+        options?.verifier
+      );
+    };
+    router.use(async (req, res, next) => {
+      const path = req.path || req.url || "";
+      const isMetadataRequest = path.startsWith("/.well-known/oauth-authorization-server") || path.startsWith("/.well-known/oauth-protected-resource");
+      if (!isMetadataRequest) {
+        next();
+        return;
+      }
+      try {
+        const runtimeAuth = await getRuntimeAuth(req);
+        runtimeAuth.metadataRouter(req, res, next);
+      } catch (error) {
+        this.respondMetadataInitError(res, error);
+      }
+    });
+    router.use(mcpPath, express.json({ limit: options?.bodyLimit ?? "1mb" }));
+    const mcpHandler = this.createMcpHandler(
+      server,
+      sessionManager,
+      getRuntimeAuth,
+      options
+    );
+    router.post(mcpPath, mcpHandler.post);
+    router.get(mcpPath, mcpHandler.get);
+    router.delete(mcpPath, mcpHandler.delete);
+    return router;
+  }
+  // ===========================================================================
+  // require()
+  // ===========================================================================
+  /**
+   * Exchange a user's access token for an integration credential.
+   *
+   * @param integration - Integration name (e.g., "github")
+   * @param token - The user's Bearer token (from `authInfo.token`)
+   * @returns Integration credential with `accessToken` and `authorization` header
+   *
+   * @throws {IntegrationConnectionRequiredError} User hasn't connected this integration
+   * @throws {OAuthError} Token exchange failed
+   */
+  async require(integration, token) {
+    const now = Date.now();
+    this.evictExpiredCredentials(now);
+    const cacheKey = `${integration}\0${token}`;
+    const cached = this.credentialCache.get(cacheKey);
+    if (cached && now < cached.expiresAt) {
+      this.credentialCache.delete(cacheKey);
+      this.credentialCache.set(cacheKey, cached);
+      return cached.credential;
+    }
+    if (cached) {
+      this.credentialCache.delete(cacheKey);
+    }
+    const exchangeConfig = {
+      tokenUrl: `${this.apiUrl}/oauth2/token`,
+      clientId: this.clientId,
+      clientSecret: this.clientSecret
+    };
+    let response;
+    try {
+      response = await exchangeToken(exchangeConfig, token, integration);
+    } catch (err) {
+      if (err instanceof OAuthError) {
+        if (err.errorCode === "integration_required" || err.message.includes("not connected") || err.message.includes("expired") && err.message.includes("reconnect")) {
+          const integrationId = err.meta.integrationId || integration;
+          const connectUrl = await this.fetchConnectUrl(
+            token,
+            integrationId,
+            exchangeConfig
+          );
+          throw new IntegrationConnectionRequiredError(integrationId, {
+            integrationName: err.meta.integrationName,
+            connectUrl,
+            message: err.message
+          });
+        }
+      }
+      throw err;
+    }
+    const credential = {
+      accessToken: response.access_token,
+      tokenType: response.token_type,
+      authorization: `${response.token_type} ${response.access_token}`,
+      expiresIn: response.expires_in,
+      scope: response.scope,
+      integration
+    };
+    if (response.expires_in) {
+      const ttlMs = Math.min(response.expires_in - 60, 5 * 60) * 1e3;
+      if (ttlMs > 0) {
+        this.trimCacheToFit(this.credentialCache, CREDENTIAL_CACHE_MAX_ENTRIES);
+        this.credentialCache.set(cacheKey, {
+          credential,
+          expiresAt: now + ttlMs
+        });
+      }
+    }
+    return credential;
+  }
+  /**
+   * Resolve per-user credential key/value pairs for an internal MCP integration.
+   *
+   * @param integration - Integration UUID or name
+   * @param token - The user's Bearer token (from `authInfo.token`)
+   * @returns Decrypted credential map for the current user and integration
+   *
+   * @throws {IntegrationConnectionRequiredError} User has not provided required credentials
+   * @throws {OAuthError} Runtime credential resolution failed
+   */
+  async requireCredentials(integration, token) {
+    const now = Date.now();
+    this.evictExpiredResolvedCredentials(now);
+    const cacheKey = `${integration}\0${token}\0internal_credentials`;
+    const cached = this.resolvedCredentialCache.get(cacheKey);
+    if (cached && now < cached.expiresAt) {
+      this.resolvedCredentialCache.delete(cacheKey);
+      this.resolvedCredentialCache.set(cacheKey, cached);
+      return cached.credential;
+    }
+    if (cached) {
+      this.resolvedCredentialCache.delete(cacheKey);
+    }
+    const exchangeConfig = {
+      tokenUrl: `${this.apiUrl}/oauth2/token`,
+      clientId: this.clientId,
+      clientSecret: this.clientSecret
+    };
+    let gatewayAccessToken = token;
+    if (!this.isGatewayScopedToken(token)) {
+      try {
+        const exchanged = await exchangeToken(
+          exchangeConfig,
+          token,
+          "mcp-gateway"
+        );
+        gatewayAccessToken = exchanged.access_token;
+      } catch (err) {
+        throw new OAuthError(
+          "Failed to exchange subject token for runtime",
+          "kontext_credentials_exchange_failed",
+          {
+            errorCode: "credentials_exchange_failed",
+            errorDescription: err instanceof Error ? err.message : String(err ?? "unknown error")
+          }
+        );
+      }
+    }
+    const integrationId = await this.resolveRuntimeIntegrationId(
+      integration,
+      gatewayAccessToken
+    );
+    const res = await fetch(
+      `${this.apiUrl}/mcp/integrations/${integrationId}/credentials/resolve`,
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${gatewayAccessToken}`,
+          "Content-Type": "application/json"
+        },
+        body: "{}"
+      }
+    );
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      const message = text && text.trim().length > 0 ? text : `HTTP ${res.status} while resolving credentials`;
+      if (res.status === 400 && message.toLowerCase().includes("credentials required")) {
+        throw new IntegrationConnectionRequiredError(integrationId, {
+          integrationName: String(integration),
+          message
+        });
+      }
+      throw new OAuthError(
+        `Failed to resolve credentials for integration ${integrationId}`,
+        "kontext_credentials_resolve_failed",
+        {
+          errorCode: "credentials_resolve_failed",
+          errorDescription: message
+        }
+      );
+    }
+    const payload = await res.json();
+    if (!payload.credentials || typeof payload.credentials !== "object" || Array.isArray(payload.credentials)) {
+      throw new OAuthError(
+        "Credential resolve returned invalid payload",
+        "kontext_credentials_invalid_payload"
+      );
+    }
+    const credentials = {};
+    for (const [key, value] of Object.entries(payload.credentials)) {
+      if (typeof value === "string") {
+        credentials[key] = value;
+      }
+    }
+    if (Object.keys(credentials).length === 0) {
+      throw new IntegrationConnectionRequiredError(integrationId, {
+        integrationName: String(integration),
+        message: "No credentials configured for this integration"
+      });
+    }
+    const resolved = {
+      integration,
+      integrationId: payload.integrationId ?? integrationId,
+      credentials
+    };
+    this.trimCacheToFit(
+      this.resolvedCredentialCache,
+      CREDENTIAL_CACHE_MAX_ENTRIES
+    );
+    this.resolvedCredentialCache.set(cacheKey, {
+      credential: resolved,
+      expiresAt: now + RESOLVED_CREDENTIAL_CACHE_TTL_MS
+    });
+    return resolved;
+  }
+  getGatewayAudiences() {
+    return /* @__PURE__ */ new Set([`${new URL(this.apiUrl).origin}/mcp`, "mcp-gateway"]);
+  }
+  isGatewayScopedToken(token) {
+    const audiences = this.extractTokenAudiences(token);
+    if (audiences.length === 0) {
+      return false;
+    }
+    const gatewayAudiences = this.getGatewayAudiences();
+    return audiences.some((audience) => gatewayAudiences.has(audience));
+  }
+  extractTokenAudiences(token) {
+    const [, payloadPart] = token.split(".");
+    if (!payloadPart) return [];
+    try {
+      const payload = JSON.parse(
+        Buffer.from(payloadPart, "base64url").toString("utf8")
+      );
+      if (typeof payload.aud === "string") {
+        return [payload.aud];
+      }
+      if (Array.isArray(payload.aud)) {
+        return payload.aud.filter(
+          (value) => typeof value === "string"
+        );
+      }
+    } catch {
+    }
+    return [];
+  }
+  // ===========================================================================
+  // Private: fetch connect URL (spec §2 — two-step init)
+  // ===========================================================================
+  async resolveRuntimeIntegrationId(integration, runtimeToken) {
+    const raw = String(integration);
+    if (this.isUuid(raw)) {
+      return raw;
+    }
+    const res = await fetch(`${this.apiUrl}/mcp/integrations`, {
+      headers: {
+        Authorization: `Bearer ${runtimeToken}`
+      }
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new OAuthError(
+        "Failed to resolve integration identifier",
+        "kontext_integration_lookup_failed",
+        {
+          errorCode: "integration_lookup_failed",
+          errorDescription: text || `HTTP ${res.status}`
+        }
+      );
+    }
+    const payload = await res.json();
+    const items = Array.isArray(payload.items) ? payload.items : [];
+    const match = items.find((item) => item.id === raw || item.name === raw);
+    const integrationId = match?.id;
+    if (!integrationId) {
+      throw new IntegrationConnectionRequiredError(raw, {
+        integrationName: raw,
+        message: `Integration ${raw} is not attached to this application`
+      });
+    }
+    return integrationId;
+  }
+  isUuid(value) {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(
+      value
+    );
+  }
+  /**
+   * Fetch a browser-openable connect URL for a missing integration.
+   *
+   * Per the integration-interrupt-flow spec, the SDK:
+   * 1. Exchanges the user's token for a resource-scoped mcp-gateway JWT
+   * 2. Calls POST /mcp/integrations/:id/oauth/init with that JWT
+   * 3. Returns the `connectUrl` (intermediate endpoint with one-time token)
+   *
+   * The connect URL points to our own server (ticket pattern), which
+   * validates the ticket, sets a browser session cookie, then redirects
+   * to the actual OAuth provider.
+   */
+  async fetchConnectUrl(subjectToken, integrationId, exchangeConfig) {
+    try {
+      const gatewayToken = await exchangeToken(
+        exchangeConfig,
+        subjectToken,
+        "mcp-gateway"
+      );
+      const initUrl = `${this.apiUrl}/mcp/integrations/${integrationId}/oauth/init`;
+      const res = await fetch(initUrl, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${gatewayToken.access_token}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({})
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        console.warn(
+          `[kontext] fetchConnectUrl: init endpoint returned ${res.status}: ${text}`
+        );
+        return void 0;
+      }
+      const data = await res.json();
+      return data.connectUrl ?? data.authorizationUrl;
+    } catch (err) {
+      console.warn(
+        `[kontext] fetchConnectUrl failed:`,
+        err instanceof Error ? err.message : String(err)
+      );
+      return void 0;
+    }
+  }
+  // ===========================================================================
+  // Private: AS metadata
+  // ===========================================================================
+  async getOAuthMetadata() {
+    const now = Date.now();
+    if (this.oauthMetadata && now - this.metadataFetchedAt < METADATA_CACHE_TTL_MS) {
+      return this.oauthMetadata;
+    }
+    if (this.metadataPromise) {
+      return this.metadataPromise;
+    }
+    this.metadataPromise = this.fetchOAuthMetadata();
+    try {
+      const metadata = await this.metadataPromise;
+      this.oauthMetadata = metadata;
+      this.metadataFetchedAt = Date.now();
+      return metadata;
+    } finally {
+      this.metadataPromise = null;
+    }
+  }
+  applyMetadataTransform(metadata, metadataTransform) {
+    if (!metadataTransform) {
+      return metadata;
+    }
+    return metadataTransform(this.cloneOAuthMetadata(metadata));
+  }
+  cloneOAuthMetadata(metadata) {
+    return JSON.parse(JSON.stringify(metadata));
+  }
+  async fetchOAuthMetadata() {
+    const urls = [
+      `${this.apiUrl}/.well-known/oauth-authorization-server`,
+      `${this.apiUrl}/.well-known/openid-configuration`
+    ];
+    let lastError;
+    for (const url of urls) {
+      try {
+        const res = await fetch(url);
+        if (res.ok) {
+          return await res.json();
+        }
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+      }
+    }
+    throw new Error(
+      `Failed to fetch AS metadata from ${this.apiUrl}: ${lastError?.message ?? "unknown error"}`
+    );
+  }
+  resolveResourceServerUrl(req, mcpPath, options) {
+    if (options?.resourceServerUrl) {
+      return new URL(options.resourceServerUrl);
+    }
+    const host = req.get("host");
+    if (!host) {
+      throw new Error(
+        "Missing Host header. Set middleware({ resourceServerUrl }) to a trusted public URL."
+      );
+    }
+    return new URL(`${req.protocol}://${host}${mcpPath}`);
+  }
+  getOrCreateRuntimeAuthContext(metadata, rsUrl, customVerifier) {
+    const key = this.getRuntimeAuthCacheKey(rsUrl, customVerifier);
+    const cached = this.runtimeAuthCache.get(key);
+    if (cached) {
+      this.runtimeAuthCache.delete(key);
+      this.runtimeAuthCache.set(key, cached);
+      return cached;
+    }
+    const proxiedMetadata = { ...metadata, issuer: `${rsUrl.origin}/` };
+    const metadataRouter = mcpAuthMetadataRouter({
+      oauthMetadata: proxiedMetadata,
+      resourceServerUrl: rsUrl
+    });
+    const resourceMetadataUrl = getOAuthProtectedResourceMetadataUrl(rsUrl);
+    const verifier = customVerifier ?? this.createTokenVerifier(metadata, rsUrl);
+    const runtimeAuth = {
+      metadataRouter,
+      bearerAuth: requireBearerAuth({
+        verifier,
+        resourceMetadataUrl
+      })
+    };
+    this.trimCacheToFit(this.runtimeAuthCache, RUNTIME_AUTH_CACHE_MAX_ENTRIES);
+    this.runtimeAuthCache.set(key, runtimeAuth);
+    return runtimeAuth;
+  }
+  getRuntimeAuthCacheKey(rsUrl, customVerifier) {
+    if (!customVerifier) {
+      return `${rsUrl.href}\0default`;
+    }
+    let verifierId = this.runtimeVerifierIds.get(customVerifier);
+    if (verifierId === void 0) {
+      verifierId = ++this.runtimeVerifierIdCounter;
+      this.runtimeVerifierIds.set(customVerifier, verifierId);
+    }
+    return `${rsUrl.href}\0custom:${verifierId}`;
+  }
+  respondMetadataInitError(res, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`[kontext] Failed to fetch AS metadata: ${message}`);
+    if (res.headersSent) return;
+    res.status(503).json({
+      error: "service_unavailable",
+      error_description: "Failed to fetch authorization server metadata. Retry later."
+    });
+  }
+  evictExpiredCredentials(now) {
+    for (const [key, value] of this.credentialCache.entries()) {
+      if (value.expiresAt <= now) {
+        this.credentialCache.delete(key);
+      }
+    }
+  }
+  evictExpiredResolvedCredentials(now) {
+    for (const [key, value] of this.resolvedCredentialCache.entries()) {
+      if (value.expiresAt <= now) {
+        this.resolvedCredentialCache.delete(key);
+      }
+    }
+  }
+  trimCacheToFit(cache, maxEntries) {
+    while (cache.size >= maxEntries) {
+      const oldestKey = cache.keys().next().value;
+      if (!oldestKey) break;
+      cache.delete(oldestKey);
+    }
+  }
+  // ===========================================================================
+  // Private: token verifier
+  // ===========================================================================
+  createTokenVerifier(metadata, resourceUrl) {
+    const metadataRaw = metadata;
+    const jwksUri = metadataRaw.jwks_uri ?? `${this.apiUrl}/.well-known/jwks.json`;
+    const clientId = this.clientId;
+    const issuers = Array.from(
+      new Set(
+        [metadata.issuer, ...this.tokenIssuers].filter(
+          (issuer2) => typeof issuer2 === "string" && !!issuer2
+        )
+      )
+    );
+    if (!issuers.length) {
+      throw new Error("OAuth metadata missing issuer");
+    }
+    const issuer = issuers.length === 1 ? issuers[0] : issuers;
+    const verifier = new KontextTokenVerifier({
+      jwksUrl: jwksUri,
+      issuer,
+      audience: resourceUrl.href
+    });
+    return {
+      async verifyAccessToken(token) {
+        const result = await verifier.verify(token);
+        if (!result.success) {
+          throw new InvalidTokenError(
+            `Token verification failed: ${result.error.message}`
+          );
+        }
+        const { claims } = result;
+        const payload = claims.payload;
+        const ext = payload.ext ?? {};
+        return {
+          token,
+          clientId: claims.clientId ?? clientId,
+          scopes: claims.scopes,
+          expiresAt: Math.floor(claims.expiresAt.getTime() / 1e3),
+          extra: {
+            ...ext,
+            sub: claims.sub,
+            email: payload.email ?? ext.email
+          }
+        };
+      }
+    };
+  }
+  // ===========================================================================
+  // Private: telemetry
+  // ===========================================================================
+  async getServiceToken() {
+    if (this.serviceToken && Date.now() < this.serviceTokenExp - 3e4) {
+      return this.serviceToken;
+    }
+    if (this.serviceTokenPromise) {
+      return this.serviceTokenPromise;
+    }
+    this.serviceTokenPromise = (async () => {
+      const res = await fetch(`${this.apiUrl}/oauth2/token`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          Authorization: `Basic ${Buffer.from(this.clientId + ":" + this.clientSecret).toString("base64")}`
+        },
+        body: "grant_type=client_credentials"
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(
+          `[kontext:telemetry] client_credentials grant failed: HTTP ${res.status} ${text}`
+        );
+      }
+      const data = await res.json();
+      this.serviceToken = data.access_token;
+      this.serviceTokenExp = Date.now() + data.expires_in * 1e3;
+      return data.access_token;
+    })();
+    try {
+      return await this.serviceTokenPromise;
+    } finally {
+      this.serviceTokenPromise = null;
+    }
+  }
+  reportEvent(event) {
+    if (!this.clientSecret || !event.sessionId) return;
+    this.getServiceToken().then(
+      (token) => fetch(`${this.apiUrl}/api/v1/mcp-events`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${token}`
+        },
+        body: JSON.stringify({
+          ...event,
+          agentId: this.clientId,
+          clientId: this.clientId,
+          clientVersion: SDK_VERSION
+        })
+      }).then((res) => {
+        if (!res.ok) {
+          console.warn(
+            `[kontext:telemetry] event report failed: HTTP ${res.status}`
+          );
+        }
+      })
+    ).catch((err) => {
+      console.warn(
+        `[kontext:telemetry] error:`,
+        err instanceof Error ? err.message : String(err)
+      );
+    });
+  }
+  // ===========================================================================
+  // Private: session lifecycle
+  // ===========================================================================
+  createAgentSession(userToken, mcpSessionId, metadata) {
+    if (!this.clientSecret || !userToken) return;
+    const tokenIdentifier = createHash("sha256").update(userToken).digest("hex");
+    this.getServiceToken().then(
+      (token) => fetch(`${this.apiUrl}/api/v1/agent-sessions`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${token}`
+        },
+        body: JSON.stringify({
+          tokenIdentifier,
+          hostname: metadata?.hostname,
+          userAgent: metadata?.userAgent,
+          clientInfo: metadata?.clientInfo,
+          tokenExpiresAt: metadata?.tokenExpiresAt ? new Date(metadata.tokenExpiresAt * 1e3).toISOString() : void 0
+        })
+      }).then(async (res) => {
+        if (res.ok) {
+          const data = await res.json();
+          if (this.pendingSessionDisconnects.delete(mcpSessionId)) {
+            this.disconnectAgentSessionByAgentSessionId(
+              data.sessionId,
+              token
+            );
+            return;
+          }
+          this.agentSessionIds.set(mcpSessionId, data.sessionId);
+        } else {
+          this.pendingSessionDisconnects.delete(mcpSessionId);
+          console.warn(
+            `[kontext:sessions] create failed: HTTP ${res.status}`
+          );
+        }
+      })
+    ).catch((err) => {
+      this.pendingSessionDisconnects.delete(mcpSessionId);
+      console.warn(
+        `[kontext:sessions] error:`,
+        err instanceof Error ? err.message : String(err)
+      );
+    });
+  }
+  disconnectAgentSessionByAgentSessionId(agentSessionId, serviceToken) {
+    if (!this.clientSecret) return;
+    const tokenPromise = serviceToken ? Promise.resolve(serviceToken) : this.getServiceToken();
+    tokenPromise.then(
+      (token) => fetch(
+        `${this.apiUrl}/api/v1/agent-sessions/${agentSessionId}/disconnect`,
+        {
+          method: "POST",
+          headers: { Authorization: `Bearer ${token}` }
+        }
+      )
+    ).catch(() => {
+    });
+  }
+  disconnectAgentSession(mcpSessionId) {
+    if (!this.clientSecret) return;
+    const agentSessionId = this.agentSessionIds.get(mcpSessionId);
+    this.agentSessionIds.delete(mcpSessionId);
+    if (!agentSessionId) {
+      this.pendingSessionDisconnects.add(mcpSessionId);
+      return;
+    }
+    this.pendingSessionDisconnects.delete(mcpSessionId);
+    this.disconnectAgentSessionByAgentSessionId(agentSessionId);
+  }
+  async disconnectAllSessions() {
+    if (!this.clientSecret) return;
+    if (this.agentSessionIds.size === 0) {
+      this.pendingSessionDisconnects.clear();
+      return;
+    }
+    try {
+      const token = await this.getServiceToken();
+      await Promise.allSettled(
+        [...this.agentSessionIds.values()].map(
+          (agentSessionId) => fetch(
+            `${this.apiUrl}/api/v1/agent-sessions/${agentSessionId}/disconnect`,
+            {
+              method: "POST",
+              headers: { Authorization: `Bearer ${token}` }
+            }
+          )
+        )
+      );
+    } catch {
+    }
+    this.agentSessionIds.clear();
+    this.pendingSessionDisconnects.clear();
+  }
+  // ===========================================================================
+  // Private: MCP transport handlers
+  // ===========================================================================
+  async runBearerAuth(bearerAuth, req, res) {
+    await new Promise((resolve, reject) => {
+      let settled = false;
+      let nextCalled = false;
+      const cleanup = () => {
+        res.removeListener("finish", onResponseDone);
+        res.removeListener("close", onResponseDone);
+      };
+      const settleResolve = () => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        resolve();
+      };
+      const settleReject = (err) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        reject(err instanceof Error ? err : new Error(String(err)));
+      };
+      const onResponseDone = () => {
+        settleResolve();
+      };
+      res.once("finish", onResponseDone);
+      res.once("close", onResponseDone);
+      let middlewareResult;
+      try {
+        middlewareResult = bearerAuth(req, res, (err) => {
+          nextCalled = true;
+          if (err) {
+            settleReject(err);
+            return;
+          }
+          settleResolve();
+        });
+      } catch (err) {
+        settleReject(err);
+        return;
+      }
+      void Promise.resolve(middlewareResult).then(
+        () => {
+          if (!nextCalled && res.headersSent) {
+            settleResolve();
+          }
+        },
+        (err) => {
+          settleReject(err);
+        }
+      );
+    });
+  }
+  createMcpHandler(server, sessionManager, getRuntimeAuth, options) {
+    const callbacks = {
+      onSessionClosed: (sessionId) => {
+        options?.onSessionClosed?.(sessionId);
+        this.disconnectAgentSession(sessionId);
+      }
+    };
+    const post = async (req, res) => {
+      const traceId = crypto.randomUUID();
+      const authReq = req;
+      if (getRuntimeAuth) {
+        let bearerAuth;
+        try {
+          const runtimeAuth = await getRuntimeAuth(req);
+          bearerAuth = runtimeAuth.bearerAuth;
+        } catch (error) {
+          this.respondMetadataInitError(res, error);
+          return;
+        }
+        await this.runBearerAuth(bearerAuth, req, res);
+        const sessionId2 = req.headers["mcp-session-id"];
+        if (sessionId2) {
+          if (res.headersSent) {
+            this.reportEvent({
+              eventType: "auth_error",
+              traceId,
+              sessionId: sessionId2,
+              durationMs: 0,
+              status: "error_auth"
+            });
+            return;
+          }
+          if (authReq.auth) {
+            this.reportEvent({
+              eventType: "auth_ok",
+              traceId,
+              ownerUserId: authReq.auth.extra?.sub,
+              sessionId: sessionId2,
+              durationMs: 0,
+              status: "ok"
+            });
+          }
+        } else if (res.headersSent) {
+          return;
+        }
+      }
+      const sessionId = req.headers["mcp-session-id"];
+      if (sessionId) {
+        const transport2 = sessionManager.getTransport(sessionId);
+        if (transport2) {
+          sessionManager.touchSession(sessionId);
+          await transport2.handleRequest(req, res, req.body);
+          return;
+        }
+      }
+      if (!isInitializeRequest(req.body)) {
+        res.status(400).json({
+          jsonrpc: "2.0",
+          error: {
+            code: -32e3,
+            message: sessionId ? `Session ${sessionId} not found` : "No valid session ID provided"
+          },
+          id: null
+        });
+        return;
+      }
+      const authInfo = authReq.auth;
+      const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => crypto.randomUUID(),
+        onsessioninitialized: (sid) => {
+          sessionManager.registerSession(
+            sid,
+            transport,
+            callbacks,
+            authInfo?.expiresAt
+          );
+          options?.onSessionInitialized?.(sid, authInfo, transport);
+          this.reportEvent({
+            eventType: "initialize",
+            traceId,
+            sessionId: sid,
+            ownerUserId: authInfo?.extra?.sub,
+            durationMs: 0,
+            status: "ok"
+          });
+          this.createAgentSession(authInfo?.token, sid, {
+            hostname: req.headers["x-forwarded-for"],
+            userAgent: req.headers["user-agent"],
+            tokenExpiresAt: authInfo?.expiresAt
+          });
+        }
+      });
+      const originalHandle = transport.handleRequest.bind(transport);
+      transport.handleRequest = async (wrappedReq, wrappedRes, parsedBody) => {
+        const reqTraceId = wrappedReq === req ? traceId : crypto.randomUUID();
+        const sid = wrappedReq.headers["mcp-session-id"] ?? transport.sessionId;
+        const start = Date.now();
+        try {
+          await originalHandle(wrappedReq, wrappedRes, parsedBody);
+          if (parsedBody?.method === "tools/call") {
+            this.reportEvent({
+              eventType: "execute_tool",
+              traceId: reqTraceId,
+              toolName: parsedBody.params?.name,
+              durationMs: Date.now() - start,
+              sessionId: sid,
+              ownerUserId: authInfo?.extra?.sub,
+              status: "ok",
+              requestJson: parsedBody.params
+            });
+          } else if (parsedBody?.method === "tools/list") {
+            this.reportEvent({
+              eventType: "search_tools",
+              traceId: reqTraceId,
+              durationMs: Date.now() - start,
+              sessionId: sid,
+              ownerUserId: authInfo?.extra?.sub,
+              status: "ok"
+            });
+          }
+        } catch (err) {
+          if (parsedBody?.method === "tools/call") {
+            this.reportEvent({
+              eventType: "execute_tool",
+              traceId: reqTraceId,
+              toolName: parsedBody.params?.name,
+              durationMs: Date.now() - start,
+              sessionId: sid,
+              ownerUserId: authInfo?.extra?.sub,
+              status: "error_remote",
+              errorMessage: err instanceof Error ? err.message : String(err)
+            });
+          } else if (parsedBody?.method === "tools/list") {
+            this.reportEvent({
+              eventType: "search_tools",
+              traceId: reqTraceId,
+              durationMs: Date.now() - start,
+              sessionId: sid,
+              ownerUserId: authInfo?.extra?.sub,
+              status: "error_remote",
+              errorMessage: err instanceof Error ? err.message : String(err)
+            });
+          }
+          throw err;
+        }
+      };
+      const mcpServer = typeof server === "function" ? server() : server;
+      await mcpServer.connect(transport);
+      await transport.handleRequest(req, res, req.body);
+    };
+    const get = async (req, res) => {
+      if (getRuntimeAuth) {
+        let bearerAuth;
+        try {
+          const runtimeAuth = await getRuntimeAuth(req);
+          bearerAuth = runtimeAuth.bearerAuth;
+        } catch (error) {
+          this.respondMetadataInitError(res, error);
+          return;
+        }
+        await this.runBearerAuth(bearerAuth, req, res);
+        if (res.headersSent) {
+          return;
+        }
+      }
+      const sessionId = req.headers["mcp-session-id"] || req.headers["Mcp-Session-Id"];
+      if (!sessionId) {
+        res.status(400).json({ error: "Missing Mcp-Session-Id header" });
+        return;
+      }
+      const transport = sessionManager.getTransport(sessionId);
+      if (!transport) {
+        res.status(400).json({ error: "Session not found" });
+        return;
+      }
+      sessionManager.touchSession(sessionId);
+      await transport.handleRequest(req, res);
+    };
+    const del = async (req, res) => {
+      if (getRuntimeAuth) {
+        let bearerAuth;
+        try {
+          const runtimeAuth = await getRuntimeAuth(req);
+          bearerAuth = runtimeAuth.bearerAuth;
+        } catch (error) {
+          this.respondMetadataInitError(res, error);
+          return;
+        }
+        await this.runBearerAuth(bearerAuth, req, res);
+        if (res.headersSent) {
+          return;
+        }
+      }
+      const sessionId = req.headers["mcp-session-id"] || req.headers["Mcp-Session-Id"];
+      if (!sessionId) {
+        res.status(400).json({ error: "Missing Mcp-Session-Id header" });
+        return;
+      }
+      const transport = sessionManager.getTransport(sessionId);
+      if (!transport) {
+        res.status(400).json({ error: "Session not found" });
+        return;
+      }
+      await transport.handleRequest(req, res);
+    };
+    return { post, get, delete: del };
+  }
+};
+
+export { IntegrationConnectionRequiredError, Kontext, KontextTokenVerifier };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map