@frontmcp/sdk 0.6.1 → 0.6.2

package/src/context/trace-context.js

@@ -1,142 +0,0 @@
-"use strict";
-/**
- * W3C Trace Context Parser
- *
- * Parses distributed tracing headers according to W3C Trace Context specification.
- * Supports traceparent header with fallback to x-frontmcp-trace-id custom header.
- *
- * @see https://www.w3.org/TR/trace-context/
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseTraceContext = parseTraceContext;
-exports.generateTraceContext = generateTraceContext;
-exports.createChildSpanContext = createChildSpanContext;
-const node_crypto_1 = require("node:crypto");
-/**
- * Parse trace context from HTTP headers.
- *
- * Priority:
- * 1. W3C traceparent header
- * 2. x-frontmcp-trace-id custom header
- * 3. Generate new trace context
- *
- * @param headers - HTTP headers object
- * @returns Parsed or generated TraceContext
- */
-function parseTraceContext(headers) {
-    // Priority 1: W3C traceparent header
-    const traceparent = getHeader(headers, 'traceparent');
-    if (traceparent) {
-        const parsed = parseTraceparent(traceparent);
-        if (parsed)
-            return parsed;
-    }
-    // Priority 2: x-frontmcp-trace-id custom header
-    const customTraceId = getHeader(headers, 'x-frontmcp-trace-id');
-    if (customTraceId && isValidTraceId(customTraceId)) {
-        const parentId = generateParentId();
-        return {
-            traceId: customTraceId.toLowerCase(),
-            parentId,
-            traceFlags: 0x01,
-            raw: `00-${customTraceId.toLowerCase()}-${parentId}-01`,
-        };
-    }
-    // Priority 3: Generate new trace context
-    return generateTraceContext();
-}
-/**
- * Parse W3C traceparent header.
- *
- * Format: version-traceId-parentId-traceFlags
- * Example: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
- *
- * @param value - traceparent header value
- * @returns Parsed TraceContext or null if invalid
- */
-function parseTraceparent(value) {
-    const parts = value.split('-');
-    if (parts.length !== 4)
-        return null;
-    const [version, traceId, parentId, flags] = parts;
-    // Validate version (must be 00 for current spec)
-    if (version !== '00')
-        return null;
-    // Validate trace-id (32 hex chars, not all zeros)
-    if (!isValidTraceId(traceId))
-        return null;
-    // Validate parent-id (16 hex chars, not all zeros)
-    if (!isValidParentId(parentId))
-        return null;
-    // Parse trace-flags
-    const traceFlags = parseInt(flags, 16);
-    if (isNaN(traceFlags))
-        return null;
-    return {
-        traceId: traceId.toLowerCase(),
-        parentId: parentId.toLowerCase(),
-        traceFlags,
-        raw: value,
-    };
-}
-/**
- * Validate a trace ID according to W3C spec.
- * Must be 32 lowercase hex characters, not all zeros.
- */
-function isValidTraceId(id) {
-    return /^[a-f0-9]{32}$/i.test(id) && id !== '00000000000000000000000000000000';
-}
-/**
- * Validate a parent ID according to W3C spec.
- * Must be 16 lowercase hex characters, not all zeros.
- */
-function isValidParentId(id) {
-    return /^[a-f0-9]{16}$/i.test(id) && id !== '0000000000000000';
-}
-/**
- * Generate a new parent ID (16 hex chars).
- */
-function generateParentId() {
-    return (0, node_crypto_1.randomUUID)().replace(/-/g, '').slice(0, 16);
-}
-/**
- * Generate a new trace context with random IDs.
- */
-function generateTraceContext() {
-    const traceId = (0, node_crypto_1.randomUUID)().replace(/-/g, '');
-    const parentId = generateParentId();
-    return {
-        traceId,
-        parentId,
-        traceFlags: 0x01, // sampled
-        raw: `00-${traceId}-${parentId}-01`,
-    };
-}
-/**
- * Get a header value from headers object (case-insensitive).
- */
-function getHeader(headers, name) {
-    // Try exact match first
-    const value = headers[name];
-    if (typeof value === 'string')
-        return value;
-    // Try lowercase
-    const lowerValue = headers[name.toLowerCase()];
-    if (typeof lowerValue === 'string')
-        return lowerValue;
-    return undefined;
-}
-/**
- * Create a child span context from a parent context.
- * Generates a new parentId while preserving the traceId.
- */
-function createChildSpanContext(parent) {
-    const newParentId = generateParentId();
-    return {
-        traceId: parent.traceId,
-        parentId: newParentId,
-        traceFlags: parent.traceFlags,
-        raw: `00-${parent.traceId}-${newParentId}-${parent.traceFlags.toString(16).padStart(2, '0')}`,
-    };
-}
-//# sourceMappingURL=trace-context.js.map

package/src/context/trace-context.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"trace-context.js","sourceRoot":"","sources":["../../../src/context/trace-context.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * W3C Trace Context Parser\n *\n * Parses distributed tracing headers according to W3C Trace Context specification.\n * Supports traceparent header with fallback to x-frontmcp-trace-id custom header.\n *\n * @see https://www.w3.org/TR/trace-context/\n */\n\nimport { randomUUID } from 'node:crypto';\n\n/**\n * W3C Trace Context parsed from traceparent header.\n * Format: 00-<trace-id>-<parent-id>-<trace-flags>\n */\nexport interface TraceContext {\n  /** 128-bit trace identifier (32 hex chars) */\n  traceId: string;\n  /** 64-bit parent span identifier (16 hex chars) */\n  parentId: string;\n  /** 8-bit trace flags (sampled = 0x01) */\n  traceFlags: number;\n  /** Raw traceparent header value */\n  raw: string;\n}\n\n/**\n * Parse trace context from HTTP headers.\n *\n * Priority:\n * 1. W3C traceparent header\n * 2. x-frontmcp-trace-id custom header\n * 3. Generate new trace context\n *\n * @param headers - HTTP headers object\n * @returns Parsed or generated TraceContext\n */\nexport function parseTraceContext(headers: Record<string, unknown>): TraceContext {\n  // Priority 1: W3C traceparent header\n  const traceparent = getHeader(headers, 'traceparent');\n  if (traceparent) {\n    const parsed = parseTraceparent(traceparent);\n    if (parsed) return parsed;\n  }\n\n  // Priority 2: x-frontmcp-trace-id custom header\n  const customTraceId = getHeader(headers, 'x-frontmcp-trace-id');\n  if (customTraceId && isValidTraceId(customTraceId)) {\n    const parentId = generateParentId();\n    return {\n      traceId: customTraceId.toLowerCase(),\n      parentId,\n      traceFlags: 0x01,\n      raw: `00-${customTraceId.toLowerCase()}-${parentId}-01`,\n    };\n  }\n\n  // Priority 3: Generate new trace context\n  return generateTraceContext();\n}\n\n/**\n * Parse W3C traceparent header.\n *\n * Format: version-traceId-parentId-traceFlags\n * Example: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01\n *\n * @param value - traceparent header value\n * @returns Parsed TraceContext or null if invalid\n */\nfunction parseTraceparent(value: string): TraceContext | null {\n  const parts = value.split('-');\n  if (parts.length !== 4) return null;\n\n  const [version, traceId, parentId, flags] = parts;\n\n  // Validate version (must be 00 for current spec)\n  if (version !== '00') return null;\n\n  // Validate trace-id (32 hex chars, not all zeros)\n  if (!isValidTraceId(traceId)) return null;\n\n  // Validate parent-id (16 hex chars, not all zeros)\n  if (!isValidParentId(parentId)) return null;\n\n  // Parse trace-flags\n  const traceFlags = parseInt(flags, 16);\n  if (isNaN(traceFlags)) return null;\n\n  return {\n    traceId: traceId.toLowerCase(),\n    parentId: parentId.toLowerCase(),\n    traceFlags,\n    raw: value,\n  };\n}\n\n/**\n * Validate a trace ID according to W3C spec.\n * Must be 32 lowercase hex characters, not all zeros.\n */\nfunction isValidTraceId(id: string): boolean {\n  return /^[a-f0-9]{32}$/i.test(id) && id !== '00000000000000000000000000000000';\n}\n\n/**\n * Validate a parent ID according to W3C spec.\n * Must be 16 lowercase hex characters, not all zeros.\n */\nfunction isValidParentId(id: string): boolean {\n  return /^[a-f0-9]{16}$/i.test(id) && id !== '0000000000000000';\n}\n\n/**\n * Generate a new parent ID (16 hex chars).\n */\nfunction generateParentId(): string {\n  return randomUUID().replace(/-/g, '').slice(0, 16);\n}\n\n/**\n * Generate a new trace context with random IDs.\n */\nexport function generateTraceContext(): TraceContext {\n  const traceId = randomUUID().replace(/-/g, '');\n  const parentId = generateParentId();\n  return {\n    traceId,\n    parentId,\n    traceFlags: 0x01, // sampled\n    raw: `00-${traceId}-${parentId}-01`,\n  };\n}\n\n/**\n * Get a header value from headers object (case-insensitive).\n */\nfunction getHeader(headers: Record<string, unknown>, name: string): string | undefined {\n  // Try exact match first\n  const value = headers[name];\n  if (typeof value === 'string') return value;\n\n  // Try lowercase\n  const lowerValue = headers[name.toLowerCase()];\n  if (typeof lowerValue === 'string') return lowerValue;\n\n  return undefined;\n}\n\n/**\n * Create a child span context from a parent context.\n * Generates a new parentId while preserving the traceId.\n */\nexport function createChildSpanContext(parent: TraceContext): TraceContext {\n  const newParentId = generateParentId();\n  return {\n    traceId: parent.traceId,\n    parentId: newParentId,\n    traceFlags: parent.traceFlags,\n    raw: `00-${parent.traceId}-${newParentId}-${parent.traceFlags.toString(16).padStart(2, '0')}`,\n  };\n}\n"]}

package/src/errors/authorization-required.error.js

@@ -1,274 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.AuthorizationRequiredError = exports.authorizationRequiredMetaSchema = exports.authorizationRequiredParamsSchema = exports.authorizationRequiredDataSchema = exports.elicitResponseSchema = void 0;
-/**
- * Authorization Required Error
- *
- * Thrown when a tool requires app-level authorization that the user has not granted.
- * Used for progressive/incremental authorization flow where users can skip apps
- * during initial auth and authorize later when needed.
- *
- * Behavior depends on session mode:
- * - Stateful: Returns auth_url link for incremental authorization
- * - Stateless: Returns unauthorized error (no link, must re-auth from scratch)
- *
- * Supports MCP elicit flow for clients that support it.
- */
-const zod_1 = require("zod");
-const mcp_error_1 = require("./mcp.error");
-/**
- * Elicit response type for clients that support elicit flow
- */
-exports.elicitResponseSchema = zod_1.z.object({
-    /** Elicit request ID for tracking */
-    elicitId: zod_1.z.string(),
-    /** Authorization URL to display */
-    authUrl: zod_1.z.string().url(),
-    /** Message to display to user */
-    message: zod_1.z.string(),
-    /** App being authorized */
-    appId: zod_1.z.string(),
-    /** Tool that triggered auth */
-    toolId: zod_1.z.string(),
-});
-// ============================================
-// Schemas
-// ============================================
-/**
- * Schema for authorization required response data (stateful mode with link)
- */
-exports.authorizationRequiredDataSchema = zod_1.z.object({
-    /** Error type identifier */
-    error: zod_1.z.literal('authorization_required'),
-    /** App ID that requires authorization */
-    app: zod_1.z.string().min(1),
-    /** Tool ID that triggered the authorization requirement */
-    tool: zod_1.z.string().min(1),
-    /** URL to authorize the app (only in stateful mode) */
-    auth_url: zod_1.z.string().url().optional(),
-    /** Human-readable message */
-    message: zod_1.z.string(),
-    /** Scopes required by the tool (optional) */
-    required_scopes: zod_1.z.array(zod_1.z.string()).optional(),
-    /** Session mode that determines behavior */
-    session_mode: zod_1.z.enum(['stateful', 'stateless']).optional(),
-    /** Whether elicit flow is being used */
-    elicit_id: zod_1.z.string().optional(),
-    /** Whether client can use incremental auth link */
-    supports_incremental: zod_1.z.boolean().optional(),
-});
-/**
- * Schema for authorization required error constructor params
- */
-exports.authorizationRequiredParamsSchema = zod_1.z.object({
-    appId: zod_1.z.string().min(1),
-    toolId: zod_1.z.string().min(1),
-    authUrl: zod_1.z.string().optional(),
-    requiredScopes: zod_1.z.array(zod_1.z.string()).optional(),
-    message: zod_1.z.string().optional(),
-    /** Session mode - determines if auth link is included */
-    sessionMode: zod_1.z.enum(['stateful', 'stateless']).optional(),
-    /** Elicit ID if using elicit flow */
-    elicitId: zod_1.z.string().optional(),
-    /** Vault ID for stateful sessions */
-    vaultId: zod_1.z.string().optional(),
-    /** Pending auth ID for tracking */
-    pendingAuthId: zod_1.z.string().optional(),
-});
-/**
- * Schema for the _meta field in MCP error response
- */
-exports.authorizationRequiredMetaSchema = zod_1.z.object({
-    errorId: zod_1.z.string(),
-    code: zod_1.z.string(),
-    timestamp: zod_1.z.string(),
-    authorization_required: zod_1.z.literal(true),
-    app: zod_1.z.string(),
-    tool: zod_1.z.string(),
-    auth_url: zod_1.z.string().optional(),
-    required_scopes: zod_1.z.array(zod_1.z.string()).optional(),
-    session_mode: zod_1.z.enum(['stateful', 'stateless']),
-    supports_incremental: zod_1.z.boolean(),
-    elicit_id: zod_1.z.string().optional(),
-    pending_auth_id: zod_1.z.string().optional(),
-});
-// ============================================
-// Error Class
-// ============================================
-/**
- * Error thrown when a tool's parent app requires authorization.
- * This enables progressive authorization where users can authorize apps
- * incrementally as needed rather than all at once.
- *
- * Behavior depends on session mode:
- * - **Stateful**: Returns auth_url link for incremental authorization
- *   - User can click link to authorize without full re-authentication
- *   - Supports elicit flow for interactive authorization
- * - **Stateless**: Returns unauthorized error only
- *   - No link provided (all state in JWT, cannot extend)
- *   - User must re-authenticate from scratch
- *
- * @example
- * ```typescript
- * // Stateful mode - can provide auth link
- * throw new AuthorizationRequiredError({
- *   appId: 'slack',
- *   toolId: 'slack:send_message',
- *   authUrl: '/oauth/authorize?app=slack',
- *   sessionMode: 'stateful',
- *   message: 'Please authorize Slack to use this tool.',
- * });
- *
- * // Stateless mode - no link, must re-auth
- * throw new AuthorizationRequiredError({
- *   appId: 'slack',
- *   toolId: 'slack:send_message',
- *   sessionMode: 'stateless',
- *   message: 'You are not authorized to use this tool.',
- * });
- * ```
- */
-class AuthorizationRequiredError extends mcp_error_1.PublicMcpError {
-    /** App ID that requires authorization */
-    appId;
-    /** Tool ID that triggered the authorization requirement */
-    toolId;
-    /** URL to authorize the app (only available in stateful mode) */
-    authUrl;
-    /** Scopes required by the tool (optional) */
-    requiredScopes;
-    /** Session mode determines if incremental auth is supported */
-    sessionMode;
-    /** Elicit ID if using elicit flow */
-    elicitId;
-    /** Vault ID for stateful sessions */
-    vaultId;
-    /** Pending auth ID for tracking */
-    pendingAuthId;
-    /** Whether incremental authorization is supported */
-    supportsIncremental;
-    constructor(params) {
-        const sessionMode = params.sessionMode ?? 'stateful';
-        const supportsIncremental = sessionMode === 'stateful';
-        // Message differs based on mode
-        const defaultMessage = supportsIncremental
-            ? `Authorization required for ${params.appId}. Please authorize to use ${params.toolId}.`
-            : `You are not authorized to use ${params.toolId}. Please re-authenticate to access this tool.`;
-        super(params.message || defaultMessage, 'AUTHORIZATION_REQUIRED', 403);
-        this.appId = params.appId;
-        this.toolId = params.toolId;
-        this.sessionMode = sessionMode;
-        this.supportsIncremental = supportsIncremental;
-        // Only set authUrl in stateful mode
-        if (supportsIncremental && params.authUrl) {
-            this.authUrl = params.authUrl;
-        }
-        this.requiredScopes = params.requiredScopes;
-        this.elicitId = params.elicitId;
-        this.vaultId = params.vaultId;
-        this.pendingAuthId = params.pendingAuthId;
-    }
-    /**
-     * Convert to MCP error response format with authorization metadata.
-     * The _meta field includes structured data that AI agents can use
-     * to prompt users for authorization.
-     *
-     * In stateful mode: includes auth_url for AI to display
-     * In stateless mode: no auth_url, AI should inform user to re-authenticate
-     */
-    toMcpError(isDevelopment) {
-        // Build content text based on mode
-        let contentText = this.getPublicMessage();
-        if (this.supportsIncremental && this.authUrl) {
-            contentText += `\n\nTo authorize, click: ${this.authUrl}`;
-        }
-        else if (!this.supportsIncremental) {
-            contentText += '\n\nPlease re-authenticate to access this tool.';
-        }
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: contentText,
-                },
-            ],
-            isError: true,
-            _meta: {
-                errorId: this.errorId,
-                code: this.code,
-                timestamp: new Date().toISOString(),
-                // Progressive auth specific fields for AI agents to use
-                authorization_required: true,
-                app: this.appId,
-                tool: this.toolId,
-                auth_url: this.authUrl,
-                required_scopes: this.requiredScopes,
-                session_mode: this.sessionMode,
-                supports_incremental: this.supportsIncremental,
-                elicit_id: this.elicitId,
-                pending_auth_id: this.pendingAuthId,
-            },
-        };
-    }
-    /**
-     * Convert to structured authorization required data
-     */
-    toAuthorizationRequiredData() {
-        return {
-            error: 'authorization_required',
-            app: this.appId,
-            tool: this.toolId,
-            auth_url: this.authUrl,
-            message: this.getPublicMessage(),
-            required_scopes: this.requiredScopes,
-            session_mode: this.sessionMode,
-            elicit_id: this.elicitId,
-            supports_incremental: this.supportsIncremental,
-        };
-    }
-    /**
-     * Create an elicit response for clients that support it
-     * Only available in stateful mode
-     */
-    toElicitResponse() {
-        if (!this.supportsIncremental || !this.authUrl || !this.elicitId) {
-            return null;
-        }
-        return {
-            elicitId: this.elicitId,
-            authUrl: this.authUrl,
-            message: this.getPublicMessage(),
-            appId: this.appId,
-            toolId: this.toolId,
-        };
-    }
-    /**
-     * Check if this error can be resolved via incremental auth link
-     */
-    canUseIncrementalAuth() {
-        return this.supportsIncremental && !!this.authUrl;
-    }
-    /**
-     * Get user-facing message based on mode
-     * - Stateful: includes link text
-     * - Stateless: tells user to re-authenticate
-     */
-    getUserFacingMessage() {
-        if (this.supportsIncremental && this.authUrl) {
-            return `${this.getPublicMessage()}\n\nClick here to authorize: ${this.authUrl}`;
-        }
-        return `${this.getPublicMessage()}\n\nYou are not authorized to use this tool. Please re-authenticate to access it.`;
-    }
-    /**
-     * Get message for cancelled authorization
-     */
-    static getCancelledMessage(appId, toolId, authUrl) {
-        const baseMsg = `Authorization was cancelled. You are not authorized to use ${toolId}.`;
-        if (authUrl) {
-            return `${baseMsg}\n\nIf you still want to use this tool, click this link to authorize: ${authUrl}\n\nThen re-prompt your request to try again.`;
-        }
-        return `${baseMsg}\n\nPlease re-authenticate and try again.`;
-    }
-}
-exports.AuthorizationRequiredError = AuthorizationRequiredError;
-//# sourceMappingURL=authorization-required.error.js.map

package/src/errors/authorization-required.error.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"authorization-required.error.js","sourceRoot":"","sources":["../../../src/errors/authorization-required.error.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Authorization Required Error\n *\n * Thrown when a tool requires app-level authorization that the user has not granted.\n * Used for progressive/incremental authorization flow where users can skip apps\n * during initial auth and authorize later when needed.\n *\n * Behavior depends on session mode:\n * - Stateful: Returns auth_url link for incremental authorization\n * - Stateless: Returns unauthorized error (no link, must re-auth from scratch)\n *\n * Supports MCP elicit flow for clients that support it.\n */\nimport { z } from 'zod';\nimport { PublicMcpError } from './mcp.error';\n\n// ============================================\n// Session Mode Types\n// ============================================\n\n/**\n * Session mode determines how authorization state is stored\n */\nexport type SessionMode = 'stateful' | 'stateless';\n\n/**\n * Elicit response type for clients that support elicit flow\n */\nexport const elicitResponseSchema = z.object({\n  /** Elicit request ID for tracking */\n  elicitId: z.string(),\n  /** Authorization URL to display */\n  authUrl: z.string().url(),\n  /** Message to display to user */\n  message: z.string(),\n  /** App being authorized */\n  appId: z.string(),\n  /** Tool that triggered auth */\n  toolId: z.string(),\n});\n\nexport type ElicitResponse = z.infer<typeof elicitResponseSchema>;\n\n// ============================================\n// Schemas\n// ============================================\n\n/**\n * Schema for authorization required response data (stateful mode with link)\n */\nexport const authorizationRequiredDataSchema = z.object({\n  /** Error type identifier */\n  error: z.literal('authorization_required'),\n  /** App ID that requires authorization */\n  app: z.string().min(1),\n  /** Tool ID that triggered the authorization requirement */\n  tool: z.string().min(1),\n  /** URL to authorize the app (only in stateful mode) */\n  auth_url: z.string().url().optional(),\n  /** Human-readable message */\n  message: z.string(),\n  /** Scopes required by the tool (optional) */\n  required_scopes: z.array(z.string()).optional(),\n  /** Session mode that determines behavior */\n  session_mode: z.enum(['stateful', 'stateless']).optional(),\n  /** Whether elicit flow is being used */\n  elicit_id: z.string().optional(),\n  /** Whether client can use incremental auth link */\n  supports_incremental: z.boolean().optional(),\n});\n\n/**\n * Schema for authorization required error constructor params\n */\nexport const authorizationRequiredParamsSchema = z.object({\n  appId: z.string().min(1),\n  toolId: z.string().min(1),\n  authUrl: z.string().optional(),\n  requiredScopes: z.array(z.string()).optional(),\n  message: z.string().optional(),\n  /** Session mode - determines if auth link is included */\n  sessionMode: z.enum(['stateful', 'stateless']).optional(),\n  /** Elicit ID if using elicit flow */\n  elicitId: z.string().optional(),\n  /** Vault ID for stateful sessions */\n  vaultId: z.string().optional(),\n  /** Pending auth ID for tracking */\n  pendingAuthId: z.string().optional(),\n});\n\n/**\n * Schema for the _meta field in MCP error response\n */\nexport const authorizationRequiredMetaSchema = z.object({\n  errorId: z.string(),\n  code: z.string(),\n  timestamp: z.string(),\n  authorization_required: z.literal(true),\n  app: z.string(),\n  tool: z.string(),\n  auth_url: z.string().optional(),\n  required_scopes: z.array(z.string()).optional(),\n  session_mode: z.enum(['stateful', 'stateless']),\n  supports_incremental: z.boolean(),\n  elicit_id: z.string().optional(),\n  pending_auth_id: z.string().optional(),\n});\n\n// ============================================\n// Types (inferred from schemas)\n// ============================================\n\n/**\n * Data structure for authorization required responses\n */\nexport type AuthorizationRequiredData = z.infer<typeof authorizationRequiredDataSchema>;\n\n/**\n * Constructor params for AuthorizationRequiredError\n */\nexport type AuthorizationRequiredParams = z.infer<typeof authorizationRequiredParamsSchema>;\n\n/**\n * Meta field type for MCP error response\n */\nexport type AuthorizationRequiredMeta = z.infer<typeof authorizationRequiredMetaSchema>;\n\n// ============================================\n// Error Class\n// ============================================\n\n/**\n * Error thrown when a tool's parent app requires authorization.\n * This enables progressive authorization where users can authorize apps\n * incrementally as needed rather than all at once.\n *\n * Behavior depends on session mode:\n * - **Stateful**: Returns auth_url link for incremental authorization\n *   - User can click link to authorize without full re-authentication\n *   - Supports elicit flow for interactive authorization\n * - **Stateless**: Returns unauthorized error only\n *   - No link provided (all state in JWT, cannot extend)\n *   - User must re-authenticate from scratch\n *\n * @example\n * ```typescript\n * // Stateful mode - can provide auth link\n * throw new AuthorizationRequiredError({\n *   appId: 'slack',\n *   toolId: 'slack:send_message',\n *   authUrl: '/oauth/authorize?app=slack',\n *   sessionMode: 'stateful',\n *   message: 'Please authorize Slack to use this tool.',\n * });\n *\n * // Stateless mode - no link, must re-auth\n * throw new AuthorizationRequiredError({\n *   appId: 'slack',\n *   toolId: 'slack:send_message',\n *   sessionMode: 'stateless',\n *   message: 'You are not authorized to use this tool.',\n * });\n * ```\n */\nexport class AuthorizationRequiredError extends PublicMcpError {\n  /** App ID that requires authorization */\n  readonly appId: string;\n\n  /** Tool ID that triggered the authorization requirement */\n  readonly toolId: string;\n\n  /** URL to authorize the app (only available in stateful mode) */\n  readonly authUrl?: string;\n\n  /** Scopes required by the tool (optional) */\n  readonly requiredScopes?: string[];\n\n  /** Session mode determines if incremental auth is supported */\n  readonly sessionMode: SessionMode;\n\n  /** Elicit ID if using elicit flow */\n  readonly elicitId?: string;\n\n  /** Vault ID for stateful sessions */\n  readonly vaultId?: string;\n\n  /** Pending auth ID for tracking */\n  readonly pendingAuthId?: string;\n\n  /** Whether incremental authorization is supported */\n  readonly supportsIncremental: boolean;\n\n  constructor(params: AuthorizationRequiredParams) {\n    const sessionMode = params.sessionMode ?? 'stateful';\n    const supportsIncremental = sessionMode === 'stateful';\n\n    // Message differs based on mode\n    const defaultMessage = supportsIncremental\n      ? `Authorization required for ${params.appId}. Please authorize to use ${params.toolId}.`\n      : `You are not authorized to use ${params.toolId}. Please re-authenticate to access this tool.`;\n\n    super(params.message || defaultMessage, 'AUTHORIZATION_REQUIRED', 403);\n    this.appId = params.appId;\n    this.toolId = params.toolId;\n    this.sessionMode = sessionMode;\n    this.supportsIncremental = supportsIncremental;\n\n    // Only set authUrl in stateful mode\n    if (supportsIncremental && params.authUrl) {\n      this.authUrl = params.authUrl;\n    }\n\n    this.requiredScopes = params.requiredScopes;\n    this.elicitId = params.elicitId;\n    this.vaultId = params.vaultId;\n    this.pendingAuthId = params.pendingAuthId;\n  }\n\n  /**\n   * Convert to MCP error response format with authorization metadata.\n   * The _meta field includes structured data that AI agents can use\n   * to prompt users for authorization.\n   *\n   * In stateful mode: includes auth_url for AI to display\n   * In stateless mode: no auth_url, AI should inform user to re-authenticate\n   */\n  override toMcpError(isDevelopment?: boolean): {\n    content: Array<{ type: 'text'; text: string }>;\n    isError: true;\n    _meta: AuthorizationRequiredMeta;\n  } {\n    // Build content text based on mode\n    let contentText = this.getPublicMessage();\n    if (this.supportsIncremental && this.authUrl) {\n      contentText += `\\n\\nTo authorize, click: ${this.authUrl}`;\n    } else if (!this.supportsIncremental) {\n      contentText += '\\n\\nPlease re-authenticate to access this tool.';\n    }\n\n    return {\n      content: [\n        {\n          type: 'text' as const,\n          text: contentText,\n        },\n      ],\n      isError: true as const,\n      _meta: {\n        errorId: this.errorId,\n        code: this.code,\n        timestamp: new Date().toISOString(),\n        // Progressive auth specific fields for AI agents to use\n        authorization_required: true as const,\n        app: this.appId,\n        tool: this.toolId,\n        auth_url: this.authUrl,\n        required_scopes: this.requiredScopes,\n        session_mode: this.sessionMode,\n        supports_incremental: this.supportsIncremental,\n        elicit_id: this.elicitId,\n        pending_auth_id: this.pendingAuthId,\n      },\n    };\n  }\n\n  /**\n   * Convert to structured authorization required data\n   */\n  toAuthorizationRequiredData(): AuthorizationRequiredData {\n    return {\n      error: 'authorization_required',\n      app: this.appId,\n      tool: this.toolId,\n      auth_url: this.authUrl,\n      message: this.getPublicMessage(),\n      required_scopes: this.requiredScopes,\n      session_mode: this.sessionMode,\n      elicit_id: this.elicitId,\n      supports_incremental: this.supportsIncremental,\n    };\n  }\n\n  /**\n   * Create an elicit response for clients that support it\n   * Only available in stateful mode\n   */\n  toElicitResponse(): ElicitResponse | null {\n    if (!this.supportsIncremental || !this.authUrl || !this.elicitId) {\n      return null;\n    }\n\n    return {\n      elicitId: this.elicitId,\n      authUrl: this.authUrl,\n      message: this.getPublicMessage(),\n      appId: this.appId,\n      toolId: this.toolId,\n    };\n  }\n\n  /**\n   * Check if this error can be resolved via incremental auth link\n   */\n  canUseIncrementalAuth(): boolean {\n    return this.supportsIncremental && !!this.authUrl;\n  }\n\n  /**\n   * Get user-facing message based on mode\n   * - Stateful: includes link text\n   * - Stateless: tells user to re-authenticate\n   */\n  getUserFacingMessage(): string {\n    if (this.supportsIncremental && this.authUrl) {\n      return `${this.getPublicMessage()}\\n\\nClick here to authorize: ${this.authUrl}`;\n    }\n    return `${this.getPublicMessage()}\\n\\nYou are not authorized to use this tool. Please re-authenticate to access it.`;\n  }\n\n  /**\n   * Get message for cancelled authorization\n   */\n  static getCancelledMessage(appId: string, toolId: string, authUrl?: string): string {\n    const baseMsg = `Authorization was cancelled. You are not authorized to use ${toolId}.`;\n    if (authUrl) {\n      return `${baseMsg}\\n\\nIf you still want to use this tool, click this link to authorize: ${authUrl}\\n\\nThen re-prompt your request to try again.`;\n    }\n    return `${baseMsg}\\n\\nPlease re-authenticate and try again.`;\n  }\n}\n"]}

package/src/errors/error-handler.js

@@ -1,107 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ErrorHandler = void 0;
-exports.createErrorHandler = createErrorHandler;
-exports.shouldStopExecution = shouldStopExecution;
-// errors/error-handler.ts
-const common_1 = require("../common");
-const mcp_error_1 = require("./mcp.error");
-/**
- * Handle errors in MCP flows and format them appropriately
- */
-class ErrorHandler {
-    isDevelopment;
-    logger;
-    errorTransformer;
-    constructor(options = {}) {
-        this.isDevelopment = options.isDevelopment ?? process.env['NODE_ENV'] !== 'production';
-        this['logger'] = options.logger;
-        this.errorTransformer = options.errorTransformer;
-    }
-    /**
-     * Handle an error and return a formatted MCP response
-     */
-    handle(error, context) {
-        // Transform error if transformer is provided
-        const transformedError = this.errorTransformer ? this.errorTransformer(error) : error;
-        // Log the error
-        this.logError(transformedError, context);
-        // Format for MCP response
-        return (0, mcp_error_1.formatMcpErrorResponse)(transformedError, this.isDevelopment);
-    }
-    /**
-     * Log error with appropriate level
-     */
-    logError(error, context) {
-        if (!this.logger)
-            return;
-        const meta = {
-            ...context,
-            errorId: error instanceof mcp_error_1.McpError ? error.errorId : undefined,
-            code: error instanceof mcp_error_1.McpError ? error.code : undefined,
-            stack: this.isDevelopment ? error.stack : undefined,
-        };
-        if (error instanceof mcp_error_1.McpError) {
-            if (error.isPublic) {
-                this.logger.warn(`Public error: ${error.getInternalMessage()}`, meta);
-            }
-            else {
-                this.logger.error(`Internal error: ${error.getInternalMessage()}`, meta);
-            }
-        }
-        else {
-            this.logger.error(`Unexpected error: ${error.message || String(error)}`, meta);
-        }
-    }
-    /**
-     * Wrap a function with error handling
-     */
-    wrap(fn) {
-        return ((...args) => {
-            try {
-                const result = fn(...args);
-                if (result instanceof Promise) {
-                    return result.catch((error) => {
-                        throw this.transformToMcpError(error);
-                    });
-                }
-                return result;
-            }
-            catch (error) {
-                throw this.transformToMcpError(error);
-            }
-        });
-    }
-    /**
-     * Transform any error to MCP error
-     */
-    transformToMcpError(error) {
-        if (error instanceof mcp_error_1.McpError) {
-            return error;
-        }
-        if (this.errorTransformer) {
-            const transformed = this.errorTransformer(error);
-            if (transformed instanceof mcp_error_1.McpError) {
-                return transformed;
-            }
-        }
-        return (0, mcp_error_1.toMcpError)(error);
-    }
-}
-exports.ErrorHandler = ErrorHandler;
-/**
- * Create a global error handler instance
- */
-function createErrorHandler(options = {}) {
-    return new ErrorHandler(options);
-}
-/**
- * Helper to check if an error should stop execution
- */
-function shouldStopExecution(error) {
-    if (error instanceof common_1.FlowControl) {
-        return ['fail', 'abort'].includes(error.type);
-    }
-    return true;
-}
-//# sourceMappingURL=error-handler.js.map

package/src/errors/error-handler.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"error-handler.js","sourceRoot":"","sources":["../../../src/errors/error-handler.ts"],"names":[],"mappings":"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","sourcesContent":["// errors/error-handler.ts\nimport { FlowControl } from '../common';\nimport { McpError, formatMcpErrorResponse, toMcpError} from './mcp.error';\n\nexport interface ErrorHandlerOptions {\n  /**\n   * Whether to include stack traces in error responses\n   */\n  isDevelopment?: boolean;\n\n  /**\n   * Logger function for error logging\n   */\n  logger?: {\n    error: (message: string, meta?: any) => void;\n    warn: (message: string, meta?: any) => void;\n  };\n\n  /**\n   * Custom error transformer\n   */\n  errorTransformer?: (error: any) => any;\n}\n\n/**\n * Handle errors in MCP flows and format them appropriately\n */\nexport class ErrorHandler {\n  private isDevelopment: boolean;\n  private logger?: ErrorHandlerOptions['logger'];\n  private errorTransformer?: ErrorHandlerOptions['errorTransformer'];\n\n  constructor(options: ErrorHandlerOptions = {}) {\n    this.isDevelopment = options.isDevelopment ?? process.env['NODE_ENV'] !== 'production';\n    this['logger'] = options.logger;\n    this.errorTransformer = options.errorTransformer;\n  }\n\n  /**\n   * Handle an error and return a formatted MCP response\n   */\n  handle(error: any, context?: { flowName?: string; toolName?: string }) {\n    // Transform error if transformer is provided\n    const transformedError = this.errorTransformer ? this.errorTransformer(error) : error;\n\n    // Log the error\n    this.logError(transformedError, context);\n\n    // Format for MCP response\n    return formatMcpErrorResponse(transformedError, this.isDevelopment);\n  }\n\n  /**\n   * Log error with appropriate level\n   */\n  private logError(error: any, context?: { flowName?: string; toolName?: string }) {\n    if (!this.logger) return;\n\n    const meta = {\n      ...context,\n      errorId: error instanceof McpError ? error.errorId : undefined,\n      code: error instanceof McpError ? error.code : undefined,\n      stack: this.isDevelopment ? error.stack : undefined,\n    };\n\n    if (error instanceof McpError) {\n      if (error.isPublic) {\n        this.logger.warn(`Public error: ${error.getInternalMessage()}`, meta);\n      } else {\n        this.logger.error(`Internal error: ${error.getInternalMessage()}`, meta);\n      }\n    } else {\n      this.logger.error(`Unexpected error: ${error.message || String(error)}`, meta);\n    }\n  }\n\n  /**\n   * Wrap a function with error handling\n   */\n  wrap<T extends (...args: any[]) => any>(fn: T): T {\n    return ((...args: any[]) => {\n      try {\n        const result = fn(...args);\n        if (result instanceof Promise) {\n          return result.catch((error) => {\n            throw this.transformToMcpError(error);\n          });\n        }\n        return result;\n      } catch (error) {\n        throw this.transformToMcpError(error);\n      }\n    }) as T;\n  }\n\n  /**\n   * Transform any error to MCP error\n   */\n  private transformToMcpError(error: any): McpError {\n    if (error instanceof McpError) {\n      return error;\n    }\n\n    if (this.errorTransformer) {\n      const transformed = this.errorTransformer(error);\n      if (transformed instanceof McpError) {\n        return transformed;\n      }\n    }\n\n    return toMcpError(error);\n  }\n}\n\n/**\n * Create a global error handler instance\n */\nexport function createErrorHandler(options: ErrorHandlerOptions = {}): ErrorHandler {\n  return new ErrorHandler(options);\n}\n\n/**\n * Helper to check if an error should stop execution\n */\nexport function shouldStopExecution(error: any): boolean {\n  if (error instanceof FlowControl) {\n    return ['fail', 'abort'].includes(error.type);\n  }\n  return true;\n}\n"]}

package/src/errors/index.js

@@ -1,45 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.shouldStopExecution = exports.createErrorHandler = exports.ErrorHandler = exports.AuthorizationRequiredError = exports.authorizationRequiredMetaSchema = exports.authorizationRequiredParamsSchema = exports.authorizationRequiredDataSchema = exports.MCP_ERROR_CODES = exports.formatMcpErrorResponse = exports.toMcpError = exports.isPublicError = exports.GlobalConfigNotFoundError = exports.PromptExecutionError = exports.PromptNotFoundError = exports.AuthConfigurationError = exports.InvalidHookFlowError = exports.DependencyNotFoundError = exports.GenericServerError = exports.UnauthorizedError = exports.QuotaExceededError = exports.RateLimitError = exports.ToolExecutionError = exports.InvalidMethodError = exports.InvalidOutputError = exports.InvalidInputError = exports.InvalidResourceUriError = exports.ResourceReadError = exports.ResourceNotFoundError = exports.ToolNotFoundError = exports.InternalMcpError = exports.PublicMcpError = exports.McpError = void 0;
-// Export all error classes
-var mcp_error_1 = require("./mcp.error");
-Object.defineProperty(exports, "McpError", { enumerable: true, get: function () { return mcp_error_1.McpError; } });
-Object.defineProperty(exports, "PublicMcpError", { enumerable: true, get: function () { return mcp_error_1.PublicMcpError; } });
-Object.defineProperty(exports, "InternalMcpError", { enumerable: true, get: function () { return mcp_error_1.InternalMcpError; } });
-Object.defineProperty(exports, "ToolNotFoundError", { enumerable: true, get: function () { return mcp_error_1.ToolNotFoundError; } });
-Object.defineProperty(exports, "ResourceNotFoundError", { enumerable: true, get: function () { return mcp_error_1.ResourceNotFoundError; } });
-Object.defineProperty(exports, "ResourceReadError", { enumerable: true, get: function () { return mcp_error_1.ResourceReadError; } });
-Object.defineProperty(exports, "InvalidResourceUriError", { enumerable: true, get: function () { return mcp_error_1.InvalidResourceUriError; } });
-Object.defineProperty(exports, "InvalidInputError", { enumerable: true, get: function () { return mcp_error_1.InvalidInputError; } });
-Object.defineProperty(exports, "InvalidOutputError", { enumerable: true, get: function () { return mcp_error_1.InvalidOutputError; } });
-Object.defineProperty(exports, "InvalidMethodError", { enumerable: true, get: function () { return mcp_error_1.InvalidMethodError; } });
-Object.defineProperty(exports, "ToolExecutionError", { enumerable: true, get: function () { return mcp_error_1.ToolExecutionError; } });
-Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return mcp_error_1.RateLimitError; } });
-Object.defineProperty(exports, "QuotaExceededError", { enumerable: true, get: function () { return mcp_error_1.QuotaExceededError; } });
-Object.defineProperty(exports, "UnauthorizedError", { enumerable: true, get: function () { return mcp_error_1.UnauthorizedError; } });
-Object.defineProperty(exports, "GenericServerError", { enumerable: true, get: function () { return mcp_error_1.GenericServerError; } });
-Object.defineProperty(exports, "DependencyNotFoundError", { enumerable: true, get: function () { return mcp_error_1.DependencyNotFoundError; } });
-Object.defineProperty(exports, "InvalidHookFlowError", { enumerable: true, get: function () { return mcp_error_1.InvalidHookFlowError; } });
-Object.defineProperty(exports, "AuthConfigurationError", { enumerable: true, get: function () { return mcp_error_1.AuthConfigurationError; } });
-Object.defineProperty(exports, "PromptNotFoundError", { enumerable: true, get: function () { return mcp_error_1.PromptNotFoundError; } });
-Object.defineProperty(exports, "PromptExecutionError", { enumerable: true, get: function () { return mcp_error_1.PromptExecutionError; } });
-Object.defineProperty(exports, "GlobalConfigNotFoundError", { enumerable: true, get: function () { return mcp_error_1.GlobalConfigNotFoundError; } });
-Object.defineProperty(exports, "isPublicError", { enumerable: true, get: function () { return mcp_error_1.isPublicError; } });
-Object.defineProperty(exports, "toMcpError", { enumerable: true, get: function () { return mcp_error_1.toMcpError; } });
-Object.defineProperty(exports, "formatMcpErrorResponse", { enumerable: true, get: function () { return mcp_error_1.formatMcpErrorResponse; } });
-// Error codes
-Object.defineProperty(exports, "MCP_ERROR_CODES", { enumerable: true, get: function () { return mcp_error_1.MCP_ERROR_CODES; } });
-// Export authorization required error for progressive auth
-var authorization_required_error_1 = require("./authorization-required.error");
-// Schemas
-Object.defineProperty(exports, "authorizationRequiredDataSchema", { enumerable: true, get: function () { return authorization_required_error_1.authorizationRequiredDataSchema; } });
-Object.defineProperty(exports, "authorizationRequiredParamsSchema", { enumerable: true, get: function () { return authorization_required_error_1.authorizationRequiredParamsSchema; } });
-Object.defineProperty(exports, "authorizationRequiredMetaSchema", { enumerable: true, get: function () { return authorization_required_error_1.authorizationRequiredMetaSchema; } });
-// Error class
-Object.defineProperty(exports, "AuthorizationRequiredError", { enumerable: true, get: function () { return authorization_required_error_1.AuthorizationRequiredError; } });
-// Export error handler utilities
-var error_handler_1 = require("./error-handler");
-Object.defineProperty(exports, "ErrorHandler", { enumerable: true, get: function () { return error_handler_1.ErrorHandler; } });
-Object.defineProperty(exports, "createErrorHandler", { enumerable: true, get: function () { return error_handler_1.createErrorHandler; } });
-Object.defineProperty(exports, "shouldStopExecution", { enumerable: true, get: function () { return error_handler_1.shouldStopExecution; } });
-//# sourceMappingURL=index.js.map

package/src/errors/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/errors/index.ts"],"names":[],"mappings":";;;AAAA,2BAA2B;AAC3B,yCA4BqB;AA3BnB,qGAAA,QAAQ,OAAA;AACR,2GAAA,cAAc,OAAA;AACd,6GAAA,gBAAgB,OAAA;AAChB,8GAAA,iBAAiB,OAAA;AACjB,kHAAA,qBAAqB,OAAA;AACrB,8GAAA,iBAAiB,OAAA;AACjB,oHAAA,uBAAuB,OAAA;AACvB,8GAAA,iBAAiB,OAAA;AACjB,+GAAA,kBAAkB,OAAA;AAClB,+GAAA,kBAAkB,OAAA;AAClB,+GAAA,kBAAkB,OAAA;AAClB,2GAAA,cAAc,OAAA;AACd,+GAAA,kBAAkB,OAAA;AAClB,8GAAA,iBAAiB,OAAA;AACjB,+GAAA,kBAAkB,OAAA;AAClB,oHAAA,uBAAuB,OAAA;AACvB,iHAAA,oBAAoB,OAAA;AACpB,mHAAA,sBAAsB,OAAA;AACtB,gHAAA,mBAAmB,OAAA;AACnB,iHAAA,oBAAoB,OAAA;AACpB,sHAAA,yBAAyB,OAAA;AACzB,0GAAA,aAAa,OAAA;AACb,uGAAA,UAAU,OAAA;AACV,mHAAA,sBAAsB,OAAA;AACtB,cAAc;AACd,4GAAA,eAAe,OAAA;AAIjB,2DAA2D;AAC3D,+EAWwC;AAVtC,UAAU;AACV,+IAAA,+BAA+B,OAAA;AAC/B,iJAAA,iCAAiC,OAAA;AACjC,+IAAA,+BAA+B,OAAA;AAK/B,cAAc;AACd,0IAAA,0BAA0B,OAAA;AAG5B,iCAAiC;AACjC,iDAA6G;AAApG,6GAAA,YAAY,OAAA;AAAuB,mHAAA,kBAAkB,OAAA;AAAE,oHAAA,mBAAmB,OAAA","sourcesContent":["// Export all error classes\nexport {\n  McpError,\n  PublicMcpError,\n  InternalMcpError,\n  ToolNotFoundError,\n  ResourceNotFoundError,\n  ResourceReadError,\n  InvalidResourceUriError,\n  InvalidInputError,\n  InvalidOutputError,\n  InvalidMethodError,\n  ToolExecutionError,\n  RateLimitError,\n  QuotaExceededError,\n  UnauthorizedError,\n  GenericServerError,\n  DependencyNotFoundError,\n  InvalidHookFlowError,\n  AuthConfigurationError,\n  PromptNotFoundError,\n  PromptExecutionError,\n  GlobalConfigNotFoundError,\n  isPublicError,\n  toMcpError,\n  formatMcpErrorResponse,\n  // Error codes\n  MCP_ERROR_CODES,\n  type McpErrorCode,\n} from './mcp.error';\n\n// Export authorization required error for progressive auth\nexport {\n  // Schemas\n  authorizationRequiredDataSchema,\n  authorizationRequiredParamsSchema,\n  authorizationRequiredMetaSchema,\n  // Types (inferred from schemas)\n  AuthorizationRequiredData,\n  AuthorizationRequiredParams,\n  AuthorizationRequiredMeta,\n  // Error class\n  AuthorizationRequiredError,\n} from './authorization-required.error';\n\n// Export error handler utilities\nexport { ErrorHandler, ErrorHandlerOptions, createErrorHandler, shouldStopExecution } from './error-handler';\n"]}