@kya-os/mcp-i-cloudflare 1.6.19 → 1.6.20-canary.clientinfo.20251126125404

package/dist/utils/error-formatter.js

@@ -0,0 +1,245 @@
+/**
+ * Error Formatter Utility
+ *
+ * Provides consistent JSON-RPC error response formatting for all error types.
+ * Handles special cases like DelegationRequiredError and OAuthRequiredError.
+ */
+/**
+ * Error codes for different error types
+ */
+export const ERROR_CODES = {
+    // Standard JSON-RPC error codes
+    PARSE_ERROR: -32700,
+    INVALID_REQUEST: -32600,
+    METHOD_NOT_FOUND: -32601,
+    INVALID_PARAMS: -32602,
+    INTERNAL_ERROR: -32603,
+    // Custom error codes for MCP-I
+    DELEGATION_REQUIRED: -32001,
+    OAUTH_REQUIRED: -32002,
+    AUTHORIZATION_REQUIRED: -32003,
+    SESSION_EXPIRED: -32004,
+};
+/**
+ * Format a generic error into JSON-RPC response
+ *
+ * @param error The error to format
+ * @param id Request ID from JSON-RPC request
+ * @returns Formatted JSON-RPC error response
+ */
+export function formatJsonRpcError(error, id) {
+    // Check if this is a special error type
+    if (isDelegationRequiredError(error)) {
+        return formatDelegationError(error, id);
+    }
+    if (isOAuthRequiredError(error)) {
+        return formatOAuthError(error, id);
+    }
+    // Generic error handling
+    let errorMessage = "Internal error";
+    let errorCode = ERROR_CODES.INTERNAL_ERROR;
+    let errorData = undefined;
+    if (error) {
+        // Check if it's an Error object with a message
+        if (typeof error === "object" && error instanceof Error && error.message) {
+            errorMessage = error.message;
+        }
+        // Check for custom error properties
+        else if (typeof error === "object" && "message" in error) {
+            errorMessage = String(error.message);
+        }
+        // For non-Error objects (strings, etc.), try to convert to string
+        else if (typeof error === "string") {
+            errorMessage = error;
+        }
+        // Extract additional error data if available
+        if (typeof error === "object" && "data" in error) {
+            errorData = error.data;
+        }
+        // Check for custom error code
+        if (typeof error === "object" && "code" in error) {
+            const customCode = error.code;
+            if (typeof customCode === "number") {
+                errorCode = customCode;
+            }
+        }
+    }
+    return {
+        jsonrpc: "2.0",
+        id,
+        error: {
+            code: errorCode,
+            message: errorMessage,
+            ...(errorData !== undefined && { data: errorData }),
+        },
+    };
+}
+/**
+ * Format DelegationRequiredError into JSON-RPC response
+ *
+ * @param error Delegation required error
+ * @param id Request ID
+ * @returns Formatted error response with consent URL
+ */
+export function formatDelegationError(error, id) {
+    const toolName = error.toolName || "unknown";
+    const requiredScopes = error.requiredScopes || [];
+    const consentUrl = error.consentUrl;
+    const resumeToken = error.resumeToken;
+    // Format message with consent URL in MCP format
+    let message = error.message || `Delegation required for tool "${toolName}"`;
+    if (consentUrl) {
+        message = `${message}. <authorization_url>${consentUrl}</authorization_url>`;
+    }
+    return {
+        jsonrpc: "2.0",
+        id,
+        error: {
+            code: ERROR_CODES.DELEGATION_REQUIRED,
+            message,
+            data: {
+                toolName,
+                requiredScopes,
+                consentUrl,
+                resumeToken,
+                // MCP-I specific: provide authorization URL for client to display
+                authorizationUrl: consentUrl,
+            },
+        },
+    };
+}
+/**
+ * Format OAuthRequiredError into JSON-RPC response
+ *
+ * @param error OAuth required error
+ * @param id Request ID
+ * @returns Formatted error response with OAuth URL
+ */
+export function formatOAuthError(error, id) {
+    const toolName = error.toolName || "unknown";
+    const requiredScopes = error.requiredScopes || [];
+    const provider = error.provider;
+    const oauthUrl = error.oauthUrl;
+    const resumeToken = error.resumeToken;
+    // Format message with OAuth URL in MCP format
+    let message = error.message || `OAuth required for tool "${toolName}"`;
+    if (oauthUrl) {
+        message = `${message}. <authorization_url>${oauthUrl}</authorization_url>`;
+    }
+    return {
+        jsonrpc: "2.0",
+        id,
+        error: {
+            code: ERROR_CODES.OAUTH_REQUIRED,
+            message,
+            data: {
+                toolName,
+                requiredScopes,
+                provider,
+                oauthUrl,
+                resumeToken,
+                // MCP-I specific: provide authorization URL for client to display
+                authorizationUrl: oauthUrl,
+            },
+        },
+    };
+}
+/**
+ * Check if error is a DelegationRequiredError
+ *
+ * @param error Error to check
+ * @returns true if it's a delegation required error
+ */
+export function isDelegationRequiredError(error) {
+    if (!error || typeof error !== "object") {
+        return false;
+    }
+    const err = error;
+    return (err.name === "DelegationRequiredError" ||
+        err.constructor?.name === "DelegationRequiredError" ||
+        (err.code === ERROR_CODES.DELEGATION_REQUIRED && err.consentUrl));
+}
+/**
+ * Check if error is an OAuthRequiredError
+ *
+ * @param error Error to check
+ * @returns true if it's an OAuth required error
+ */
+export function isOAuthRequiredError(error) {
+    if (!error || typeof error !== "object") {
+        return false;
+    }
+    const err = error;
+    return (err.name === "OAuthRequiredError" ||
+        err.constructor?.name === "OAuthRequiredError" ||
+        (err.code === ERROR_CODES.OAUTH_REQUIRED && err.oauthUrl));
+}
+/**
+ * Format method not found error
+ *
+ * @param method The method that was not found
+ * @param id Request ID
+ * @returns Formatted error response
+ */
+export function formatMethodNotFoundError(method, id) {
+    return {
+        jsonrpc: "2.0",
+        id,
+        error: {
+            code: ERROR_CODES.METHOD_NOT_FOUND,
+            message: `Unknown method: ${method}`,
+        },
+    };
+}
+/**
+ * Format tool not found error
+ *
+ * @param toolName The tool that was not found
+ * @param id Request ID
+ * @returns Formatted error response
+ */
+export function formatToolNotFoundError(toolName, id) {
+    return {
+        jsonrpc: "2.0",
+        id,
+        error: {
+            code: ERROR_CODES.INVALID_PARAMS,
+            message: `Tool not found: ${toolName}`,
+        },
+    };
+}
+/**
+ * Format session expired error
+ *
+ * @param sessionId The expired session ID
+ * @param id Request ID
+ * @returns Formatted error response
+ */
+export function formatSessionExpiredError(sessionId, id) {
+    return {
+        jsonrpc: "2.0",
+        id,
+        error: {
+            code: ERROR_CODES.SESSION_EXPIRED,
+            message: "Session has expired",
+            data: {
+                sessionId,
+            },
+        },
+    };
+}
+/**
+ * Create a success response wrapper
+ *
+ * @param result The result to wrap
+ * @param id Request ID
+ * @returns JSON-RPC success response
+ */
+export function formatSuccessResponse(result, id) {
+    return {
+        jsonrpc: "2.0",
+        id,
+        result,
+    };
+}
+//# sourceMappingURL=error-formatter.js.map

package/dist/utils/error-formatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-formatter.js","sourceRoot":"","sources":["../../src/utils/error-formatter.ts"],"names":[],"mappings":"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"}

package/dist/utils/initialize-context.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Initialize Context Manager
+ *
+ * Manages MCP initialize context storage and retrieval for cross-request state.
+ * This allows us to preserve client info between initialize and handshake calls.
+ */
+import type { MCPClientCapabilities } from "@kya-os/contracts/handshake";
+import type { MCPClientInfo as SessionClientInfo } from "../types/client";
+/**
+ * Context stored from initialize request
+ */
+export interface InitializeContext {
+    timestamp: number;
+    protocolVersion?: string;
+    capabilities?: MCPClientCapabilities;
+    clientInfo?: Partial<SessionClientInfo>;
+}
+/**
+ * Request metadata for fingerprinting
+ */
+export interface RequestMeta {
+    fingerprint?: string;
+    userAgent?: string;
+    ip?: string;
+    cfRay?: string;
+    request?: Request;
+}
+/**
+ * Manages initialize contexts for session continuity
+ */
+export declare class InitializeContextManager {
+    private contexts;
+    constructor();
+    /**
+     * Store initialize context for later use in handshake
+     *
+     * @param meta Request metadata for fingerprinting
+     * @param params Initialize request parameters
+     */
+    store(meta: RequestMeta | undefined, params: unknown): void;
+    /**
+     * Consume initialize context (removes it after retrieval)
+     *
+     * @param meta Request metadata for fingerprinting
+     * @returns Initialize context if found and valid, undefined otherwise
+     */
+    consume(meta: RequestMeta | undefined): InitializeContext | undefined;
+    /**
+     * Prune expired contexts
+     */
+    private prune;
+    /**
+     * Normalize client info from various formats
+     *
+     * @param value Client info from request
+     * @returns Normalized client info or undefined
+     */
+    private normalizeClientInfo;
+    /**
+     * Clone capabilities object (deep copy)
+     *
+     * @param capabilities Capabilities to clone
+     * @returns Cloned capabilities or undefined
+     */
+    private cloneCapabilities;
+    /**
+     * Type guard for record objects
+     *
+     * @param value Value to check
+     * @returns true if value is a record object
+     */
+    private isRecord;
+    /**
+     * Get current size of context cache (for monitoring)
+     *
+     * @returns Number of stored contexts
+     */
+    size(): number;
+    /**
+     * Clear all contexts (for testing)
+     */
+    clear(): void;
+}
+/**
+ * Build request metadata from HTTP request
+ *
+ * @param request HTTP request
+ * @returns Request metadata with fingerprint
+ */
+export declare function buildRequestMeta(request: Request): RequestMeta;
+//# sourceMappingURL=initialize-context.d.ts.map

package/dist/utils/initialize-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"initialize-context.d.ts","sourceRoot":"","sources":["../../src/utils/initialize-context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,IAAI,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAE1E;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,qBAAqB,CAAC;IACrC,UAAU,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAKD;;GAEG;AACH,qBAAa,wBAAwB;IACnC,OAAO,CAAC,QAAQ,CAAiC;;IAMjD;;;;;OAKG;IACH,KAAK,CAAC,IAAI,EAAE,WAAW,GAAG,SAAS,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI;IAqB3D;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,SAAS,GAAG,iBAAiB,GAAG,SAAS;IAoBrE;;OAEG;IACH,OAAO,CAAC,KAAK;IASb;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IA2C3B;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAUzB;;;;;OAKG;IACH,OAAO,CAAC,QAAQ;IAIhB;;;;OAIG;IACH,IAAI,IAAI,MAAM;IAId;;OAEG;IACH,KAAK,IAAI,IAAI;CAGd;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,CAsB9D"}

package/dist/utils/initialize-context.js

@@ -0,0 +1,169 @@
+/**
+ * Initialize Context Manager
+ *
+ * Manages MCP initialize context storage and retrieval for cross-request state.
+ * This allows us to preserve client info between initialize and handshake calls.
+ */
+// TTL for initialize contexts (60 seconds)
+const INITIALIZE_CONTEXT_TTL_MS = 60_000;
+/**
+ * Manages initialize contexts for session continuity
+ */
+export class InitializeContextManager {
+    contexts;
+    constructor() {
+        this.contexts = new Map();
+    }
+    /**
+     * Store initialize context for later use in handshake
+     *
+     * @param meta Request metadata for fingerprinting
+     * @param params Initialize request parameters
+     */
+    store(meta, params) {
+        if (!meta?.fingerprint || !this.isRecord(params)) {
+            return;
+        }
+        const protocolVersion = params.protocolVersion;
+        const capabilities = params.capabilities;
+        const clientInfo = this.normalizeClientInfo(params.clientInfo);
+        const context = {
+            timestamp: Date.now(),
+            protocolVersion: typeof protocolVersion === "string" ? protocolVersion : undefined,
+            capabilities: this.cloneCapabilities(capabilities),
+            clientInfo,
+        };
+        this.contexts.set(meta.fingerprint, context);
+        this.prune();
+    }
+    /**
+     * Consume initialize context (removes it after retrieval)
+     *
+     * @param meta Request metadata for fingerprinting
+     * @returns Initialize context if found and valid, undefined otherwise
+     */
+    consume(meta) {
+        if (!meta?.fingerprint) {
+            return undefined;
+        }
+        const context = this.contexts.get(meta.fingerprint);
+        if (!context) {
+            return undefined;
+        }
+        if (Date.now() - context.timestamp > INITIALIZE_CONTEXT_TTL_MS) {
+            this.contexts.delete(meta.fingerprint);
+            return undefined;
+        }
+        // Remove after consumption to prevent cross-session leakage
+        this.contexts.delete(meta.fingerprint);
+        return context;
+    }
+    /**
+     * Prune expired contexts
+     */
+    prune() {
+        const now = Date.now();
+        for (const [key, context] of this.contexts.entries()) {
+            if (now - context.timestamp > INITIALIZE_CONTEXT_TTL_MS) {
+                this.contexts.delete(key);
+            }
+        }
+    }
+    /**
+     * Normalize client info from various formats
+     *
+     * @param value Client info from request
+     * @returns Normalized client info or undefined
+     */
+    normalizeClientInfo(value) {
+        if (!this.isRecord(value)) {
+            return undefined;
+        }
+        const normalized = {};
+        const record = value;
+        const name = record.name;
+        if (typeof name === "string" && name.trim().length > 0) {
+            normalized.name = name.trim();
+        }
+        const title = record.title;
+        if (typeof title === "string" && title.trim().length > 0) {
+            normalized.title = title.trim();
+        }
+        const version = record.version;
+        if (typeof version === "string" && version.trim().length > 0) {
+            normalized.version = version.trim();
+        }
+        const platform = record.platform;
+        if (typeof platform === "string" && platform.trim().length > 0) {
+            normalized.platform = platform.trim();
+        }
+        const vendor = record.vendor;
+        if (typeof vendor === "string" && vendor.trim().length > 0) {
+            normalized.vendor = vendor.trim();
+        }
+        const persistentId = record.persistentId;
+        if (typeof persistentId === "string" && persistentId.trim().length > 0) {
+            normalized.persistentId = persistentId.trim();
+        }
+        return Object.keys(normalized).length > 0 ? normalized : undefined;
+    }
+    /**
+     * Clone capabilities object (deep copy)
+     *
+     * @param capabilities Capabilities to clone
+     * @returns Cloned capabilities or undefined
+     */
+    cloneCapabilities(capabilities) {
+        if (!this.isRecord(capabilities)) {
+            return undefined;
+        }
+        return JSON.parse(JSON.stringify(capabilities));
+    }
+    /**
+     * Type guard for record objects
+     *
+     * @param value Value to check
+     * @returns true if value is a record object
+     */
+    isRecord(value) {
+        return typeof value === "object" && value !== null && !Array.isArray(value);
+    }
+    /**
+     * Get current size of context cache (for monitoring)
+     *
+     * @returns Number of stored contexts
+     */
+    size() {
+        return this.contexts.size;
+    }
+    /**
+     * Clear all contexts (for testing)
+     */
+    clear() {
+        this.contexts.clear();
+    }
+}
+/**
+ * Build request metadata from HTTP request
+ *
+ * @param request HTTP request
+ * @returns Request metadata with fingerprint
+ */
+export function buildRequestMeta(request) {
+    const ip = request.headers.get("cf-connecting-ip") ??
+        request.headers.get("x-forwarded-for") ??
+        undefined;
+    const userAgent = request.headers.get("user-agent") ?? undefined;
+    const cfRay = request.headers.get("cf-ray") ?? undefined;
+    const origin = request.headers.get("origin") ?? undefined;
+    const secChUa = request.headers.get("sec-ch-ua") ?? undefined;
+    const fingerprintParts = [ip, userAgent, cfRay, origin, secChUa].filter((value) => typeof value === "string" && value.length > 0);
+    return {
+        fingerprint: fingerprintParts.length > 0 ? fingerprintParts.join("|") : undefined,
+        ip,
+        userAgent,
+        cfRay,
+        request, // Include request for cookie access
+    };
+}
+//# sourceMappingURL=initialize-context.js.map

package/dist/utils/initialize-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"initialize-context.js","sourceRoot":"","sources":["../../src/utils/initialize-context.ts"],"names":[],"mappings":"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"}

package/dist/utils/known-clients.d.ts

@@ -2,17 +2,19 @@
  * Known MCP Clients Registry
  *
  * Maps known MCP client names to their official Know That AI (KTA) DIDs.
- * When a known client connects, we use its pre-registered DID instead of generating one.
+ * All known clients get a did:web DID, with ktaRegistered indicating actual KTA registration.
  */
 export interface KnownClientConfig {
     /** Possible client name variations (case-insensitive matching) */
     names: string[];
-    /** Know That AI registered DID for this client (null if not yet registered) */
-    ktaDid: string | null;
+    /** Know That AI DID for this client (did:web format) */
+    ktaDid: string;
+    /** Whether this client is actually registered on knowthat.ai */
+    ktaRegistered: boolean;
     /** Display name for logging */
     displayName: string;
-    /** Optional vendor/organization */
-    vendor?: string;
+    /** Vendor/organization */
+    vendor: string;
 }
 /**
  * Registry of known MCP clients
@@ -20,6 +22,8 @@ export interface KnownClientConfig {
  * Each entry maps a canonical client ID to its configuration.
  * The `names` array contains possible variations of the client name
  * that might appear in the MCP initialize message's clientInfo.name field.
+ *
+ * All known clients get a did:web DID. ktaRegistered indicates if actually on KTA.
  */
 export declare const KNOWN_MCP_CLIENTS: Record<string, KnownClientConfig>;
 /**
@@ -36,9 +40,13 @@ export declare function findKnownClient(clientName: string | undefined): (KnownC
  */
 export declare function isKnownClient(clientName: string | undefined): boolean;
 /**
- * Get the DID for a known client, if registered
+ * Get the DID for a known client
  */
 export declare function getKnownClientDid(clientName: string | undefined): string | null;
+/**
+ * Check if a known client is registered on KTA
+ */
+export declare function isKnownClientRegistered(clientName: string | undefined): boolean;
 /**
  * Get all known client IDs
  */

package/dist/utils/known-clients.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"known-clients.d.ts","sourceRoot":"","sources":["../../src/utils/known-clients.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,+EAA+E;IAC/E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAsF/D,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,CAAC,iBAAiB,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,SAAS,CAclD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAErE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,MAAM,GAAG,IAAI,CAGf;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAE5C"}
+{"version":3,"file":"known-clients.d.ts","sourceRoot":"","sources":["../../src/utils/known-clients.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,aAAa,EAAE,OAAO,CAAC;IACvB,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAgG/D,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,CAAC,iBAAiB,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,SAAS,CAclD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAErE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,MAAM,GAAG,IAAI,CAGf;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,OAAO,CAGT;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAE5C"}